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](docs/demand-and-reuse.md) 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](SCOPE.md) for current facts and [workplans](workplans/README.md)
for the staged implementation and verification gates.