rapp-playwright/INTENT.md

INTENT — rapp-playwright

Why this repo exists

rapp-playwright provides and operates a reusable Playwright and headless Chromium environment on Railiance so coding agents can arrange UI testing without assembling a browser stack or copying another application's fixtures. An agent should be able to discover availability, follow one documented command path, exercise a target UI, and retrieve inspectable evidence of the result.

The initial demand is content-explorer's CONTENT-WP-0000-T04: responsive screenshots and a keyboard interaction walkthrough. Its environment lacked a browser launcher, and discovery of existing source examples did not supply a verified runnable path. Demand evidence separates this delivery gap from reuse-surface's search and ranking defects.

What it owns

• The agent consumption contract: availability/preflight, submission or session setup, target reachability, execution, results, cleanup, and actionable failures.
• A reproducible Playwright/Chromium runtime with compatible pinned versions, browser dependencies, immutable release identification, and upgrade checks.
• The thin service and client integration needed to expose that runtime through a supported command path, with a minimal consumer-independent example.
• Per-run isolation, bounded concurrency and duration, cancellation, abandoned run cleanup, and artifact lifecycle. Consumers must not see each other's browser state or results.
• The Railiance workload package, health/readiness checks, resource envelope, deployment evidence, recovery and rollback instructions.
• Evidence-backed availability reports and consumption references supplied to reuse-surface when the service changes.

Consumer outcome

From a fresh agent environment, a documented trial must say whether execution is available now and where the browser runs. A local browser is not required for the intended managed service path. Any required client setup must be named, versioned and verified; an optional local fallback must be labeled separately.

The trial opens a supplied reachable page, checks a meaningful rendered state, captures desktop and narrow-viewport screenshots, and records a short keyboard interaction with its observed result. It returns machine-readable status and artifact references, plus the exact command, target, package/browser versions, timestamps and assertion outcomes. Infrastructure/setup failures must be distinguishable from failed UI assertions. A failed run must remain diagnosable.

The contract must explain how a remote browser reaches a consumer's development server; a workstation's localhost is not a remote browser's localhost. Unreachable targets should produce a useful diagnosis and a supported setup path.

Ownership boundaries

Consumers own their applications, fixtures, assertions, target authorization, visual baseline decisions, and acceptance of their own tasks. This repo supplies execution and evidence; it does not mark content-explorer's task done.

Playwright owns its upstream browser automation APIs. Existing consumer examples are reuse inputs, not service dependencies or an estate-wide technology mandate. Reuse-surface owns capability discovery, relevance, maturity assessment, and the existing capability.infotech.headless-browser record. This repo owns the provider contract and runtime, not a competing registry or a second browser stack.

Railiance platform owners govern cluster admission, shared networking and access policy. Credential custody and identity stay with their established owners. Service access and test authentication must use those lanes when required; credentials and browser storage state must not enter ordinary result logs.

Initial scope and later decisions

Start with Chromium, one consumer-independent trial, and the content-explorer pilot. Native Playwright compatibility is the starting point. The consumption contract decides whether remote sessions, submitted jobs, or a combination best satisfies agent use and artifact retrieval. Transport, endpoint, deployment binding, package versions, and access mechanism are not selected by this intent.

Multi-browser coverage, a general browser farm, unrestricted script execution, arbitrary external-site automation, and a visual-baseline approval product are outside the initial increment. They require demonstrated demand and explicit scope decisions.

Success and availability

Success means an independent coding agent follows the published instructions without copying sibling fixtures, completes the screenshot/keyboard trial, retrieves evidence, and can distinguish a service outage from a UI failure. Isolation, timeouts and cleanup must have executed negative-case evidence.

Planning, registration, image publication and a successful health check alone do not prove this outcome. Availability advances only with runtime and consumer receipts. Claims must distinguish a verified local runtime from an admitted managed endpoint; neither image publication nor local proof establishes Railiance availability.

See SCOPE.md for current facts and workplans for the staged implementation and verification gates.