playhead-cli 0.1.0

package/Dockerfile

@@ -0,0 +1,24 @@
+# Playhead in a container: capture + compose + verify with no host dependencies.
+# The Playwright base image ships Chromium, its sandbox deps, and system fonts.
+#
+#   docker build -t playhead .
+#   docker run --rm -v "$PWD:/work" -w /work --shm-size=1g playhead \
+#     render specs/examples/add-user.yaml -o out --json
+#
+# Notes:
+# - --shm-size=1g (or --disable-dev-shm-usage) keeps Chromium from OOMing in /dev/shm.
+# - TTS narration (`output.audio.narration: tts`) uses macOS `say` and degrades LOUDLY to a
+#   silent render on Linux; a Linux TTS provider is planned behind the same seam.
+# - ffmpeg/ffprobe come from the npm static binaries — nothing to apt-install.
+FROM mcr.microsoft.com/playwright:v1.49.0-noble
+
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev --ignore-scripts \
+  && npx playwright install chromium
+
+COPY dist ./dist
+COPY demo ./demo
+
+ENTRYPOINT ["node", "dist/cli/index.js"]
+CMD ["--help"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aman Rai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+# Playhead
+
+**Product video as a build artifact, not a performance.** Give Playhead a small text
+spec and a URL; it drives your real web app with real input, records clean footage plus a
+structured event log, applies all presentation at compose time, and reviews its own output
+before delivering a verified MP4.
+
+```
+spec + live product → capture → compose → verify → out.mp4 + verdict.json
+```
+
+Change the spec or the product, regenerate in minutes. **Re-render, don't re-record.**
+
+---
+
+## Quick start
+
+```bash
+npm install
+npx playwright install chromium
+npm run demo &                 # bundled demo app on http://localhost:4173
+npm run playhead -- render specs/examples/add-user.yaml -o out
+```
+
+## Let an agent write the spec
+
+You don't have to hand-write locators. Point the agent at a running app and describe the
+flow — it walks the app, reads each screen's accessibility tree, and authors a spec where
+**every locator is validated against the live DOM** (no more "the name was `☰Contacts`, not
+`Contacts`" surprises):
+
+```bash
+export ANTHROPIC_API_KEY=...   # the agent that drafts the spec
+npx playhead author http://localhost:4173/crm.html "create a new deal for Globex" -o deal.yaml
+npx playhead render deal.yaml -o out
+```
+
+Or just inspect what's addressable on a screen (great input for writing specs by hand):
+
+```bash
+npx playhead explore http://localhost:4173/crm.html
+```
+
+See [VISION.md](VISION.md) for where this is going — Playhead as the video-evidence layer
+for the whole development lifecycle (CI, Jira, PRs, and an MCP tool for coding agents).
+
+## Use it from your coding agent (MCP)
+
+Playhead ships an MCP server, so any agent (Claude Code, Cursor, …) can explore your app,
+write a grounded spec, render it, and read the verdict — inside your own repo. Register it:
+
+```jsonc
+// .mcp.json
+{
+  "mcpServers": {
+    "playhead": { "command": "npx", "args": ["playhead", "mcp"] }
+  }
+}
+```
+
+Tools the agent gets: `playhead_explore` (grounded, validated locators for the current
+screen), `playhead_validate_spec` (schema + locator check, no render), `playhead_author`
+(auto-draft a spec toward a goal), and `playhead_render` (capture → compose → verify,
+returning the publish/no-publish verdict with reasons and artifact paths). The agent's loop
+becomes: *explore → write spec → render → read verdict → fix → re-render.*
+
+Outputs land in `out/`:
+
+- `out/out.mp4` — the finished 1080p walkthrough (title card, planned camera moves, rendered
+  cursor, auto-written numbered captions).
+- `out/capture/` — the re-renderable **capture bundle** (frames + `events.json` + manifest).
+- `out/compose-manifest.json` — everything the compositor rendered, and what verification checks against.
+- `out/verify/verdict.json` — `publishable` / `not-publishable` with per-check reasons.
+- `out/verify/contact-sheet.png` — key moments as an annotated grid, so you can trust the
+  output without watching it end to end.
+
+`render` exits `0` only when the verdict is publishable — drop it in CI as an end-to-end test
+with video evidence attached.
+
+## The spec
+
+A spec is small and reviewable on purpose. Elements are addressed the resilient way — by
+role, label, and text, never brittle CSS — which is also what lets Playhead auto-write the
+instruction captions.
+
+```yaml
+playhead: 1
+title: "Add a user in Acme Admin"
+subtitle: "Admin in 30 seconds"        # title-card subtitle (defaults to the app host)
+vars:
+  base: ${env.APP_URL:-http://localhost:4173}
+app:
+  url: "{{base}}"
+  viewport: 1280x720
+  storageState: session.json           # from `playhead login` (authed apps)
+  assertLoggedIn: 'role=link[name="Deals"]'   # fail fast on stale auth
+  environment: { timezone: UTC, locale: en-US, fixedTime: "2026-01-01T12:00:00Z" }
+  network:
+    block: ["**analytics**"]           # never film third-party noise
+output:
+  kind: demo                           # walkthrough | demo | bug-repro | before-after | release | social
+  audio: { narration: tts, sfx: true } # spoken captions + click ticks, loudness-normalized
+  endCard: { title: "Acme Admin", subtitle: "acme.dev" }
+masking:
+  - target: 'testid=env-banner'        # redacted at capture; never reaches a frame
+    style: solid
+scenes:
+  - id: add-user
+    title: "Add a user"
+    steps:
+      - click: 'role=button[name="Add user"]'
+      - type: { target: 'label=Full name', text: "Jane Doe" }
+      - type: { target: 'label=Temporary password', text: "s3cret!", mask: true }
+      - click: 'role=button[name="Create user"]'
+        caption: "Create it."
+        narration: "One click, and the account is live."   # spoken line ≠ on-screen card
+        focus: 'text="User added"'     # act→react: click here, camera lands THERE
+      - expect: { target: 'text="User added"', visible: true }
+      - wait: { for: 'text="Jane Doe"', state: visible }    # structured wait, never a sleep
+```
+
+Elements inside iframes are addressed with a frame chain: `frame=#preview >> role=button[name="Save"]`.
+Per-step extras: `caption`, `narration`, `focus` (`target`/`wide`/a locator), `shot: cut|continue`,
+`timeout`, `mask`. Specs compose: `extends: ./base.yaml` merges a base file underneath.
+Scaffold one with `npx playhead init`.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `playhead render <specs...>` | capture → compose → verify; `--workers N` pools multiple specs; `--json` / `--junit <path>` for CI |
+| `playhead validate <spec> --live` | preflight EVERY locator against the running app in one pass, with suggestions — before any frame is captured |
+| `playhead capture <spec>` | produce a capture bundle only; `--from-scene <id>` fast-forwards earlier steps unfilmed |
+| `playhead compose <bundle>` | re-render from a bundle — **no live app needed**; `--spec edited.yaml` re-composes with new text/theme/audio; `--expect-sha` asserts determinism |
+| `playhead verify <bundle> <mp4>` | run the verification suite; `--json` / `--junit` |
+| `playhead jira report <KEY>` | attach evidence (video/failure clip, verdict, contact sheet, console log) to an existing Jira issue + post a verdict comment; or `render --jira <KEY>` (env: JIRA_BASE_URL/EMAIL/API_TOKEN) |
+| `playhead attest <verify-dir>` | re-verify a verdict: artifact hashes + HMAC signature (`PLAYHEAD_SIGNING_KEY`) |
+| `playhead explore <url>` | grounded locator catalog (regions, stability marks, iframes); `--storage-state` for authed screens |
+| `playhead login <url>` | you log in in a headed browser; the session is saved for `app.storageState` |
+| `playhead init [path]` | scaffold a starter spec |
+| `playhead doctor [--ci]` | check ffmpeg, browser, fonts — and container/TTS/signing prerequisites |
+
+Add `--vision` to `render`/`verify` for an optional Claude review of the contact sheet (needs
+`ANTHROPIC_API_KEY`; skipped cleanly without one, so CI stays deterministic).
+
+**Exit codes are a contract:** `0` publishable · `1` the app broke the flow (a partial bundle
+**and a watchable failure clip** are written) · `2` rendered but failed verification ·
+`3` infra · `4` bad spec/arguments.
+
+## CI
+
+`action.yml` ships a composite GitHub Action (render → JUnit → artifact upload), and the
+`Dockerfile` runs everything in the Playwright base image. Verdicts carry provenance (version,
+spec hash, capture time, host) and an HMAC signature when `PLAYHEAD_SIGNING_KEY` is set —
+`playhead attest` proves a verdict describes exactly these files and was never edited.
+
+## How it works
+
+1. **Capture** (`src/capture/`) drives the app through an in-house `Driver` interface
+   (Playwright behind it, swappable). It records 2×-resolution frames on a timestamp index,
+   an event log (action kind, accessible label, measured bounding box, timestamps, cursor
+   path), and applies masking in the DOM before any pixel is painted.
+2. **Compose** (`src/compose/`) is a pure function of the bundle. It plans pacing (holds,
+   trimmed idle, min step duration), a camera path from measured UI geometry (quantized zoom,
+   never cropping a target), a re-synthesized cursor, and auto-written captions — then renders
+   per frame with skia canvas piped to ffmpeg. All presentation is here, so any visual change
+   is a re-render.
+3. **Verify** (`src/verify/`) runs ten deterministic checks (target framed and legible, cursor
+   on target, action visibly effective, delivered pixels match the plan, no frozen/blank
+   footage, captions fit, pacing sane, encode intact, masks opaque + log clean, narration
+   audible in its windows at target loudness) and emits a signed verdict and contact sheet.
+
+The **capture bundle is the only artifact that touches the live app** — compose and verify
+never hit the network, which is what makes re-render deterministic and CI-safe.
+
+## Development
+
+```bash
+npm run typecheck
+npm test          # unit + seeded-failure fixtures + full e2e against the demo app
+npm run build
+```
+
+See [AGENTS.md](AGENTS.md) for architecture notes and conventions.

package/action.yml

@@ -0,0 +1,71 @@
+name: 'Playhead Render'
+description: >
+  Render verified product videos from Playhead specs: capture the live app, compose the video,
+  verify it, and publish a JUnit report. Exit codes distinguish flow failure (the app broke — a
+  failure clip is rendered) from video-quality failure from infra problems.
+branding:
+  icon: 'film'
+  color: 'purple'
+
+inputs:
+  specs:
+    description: 'Space-separated spec paths (or a glob expanded by the shell step calling this action)'
+    required: true
+  out:
+    description: 'Output directory for bundles, videos, verdicts'
+    default: 'playhead-out'
+  workers:
+    description: 'Concurrent renders when given multiple specs'
+    default: '2'
+  signing-key:
+    description: 'PLAYHEAD_SIGNING_KEY — when set, verdicts are HMAC-signed and attestable'
+    required: false
+
+outputs:
+  junit:
+    description: 'Path to the JUnit XML report'
+    value: ${{ steps.render.outputs.junit }}
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Cache Chromium
+      uses: actions/cache@v4
+      with:
+        path: ~/.cache/ms-playwright
+        key: playwright-chromium-${{ runner.os }}
+
+    - name: Install browsers
+      shell: bash
+      run: npx playwright install --with-deps chromium
+
+    - name: Render + verify
+      id: render
+      shell: bash
+      env:
+        PLAYHEAD_SIGNING_KEY: ${{ inputs.signing-key }}
+      run: |
+        set +e
+        npx playhead render ${{ inputs.specs }} \
+          -o "${{ inputs.out }}" \
+          --workers "${{ inputs.workers }}" \
+          --junit "${{ inputs.out }}/junit.xml" \
+          --json > "${{ inputs.out }}/verdict-stream.json"
+        code=$?
+        echo "junit=${{ inputs.out }}/junit.xml" >> "$GITHUB_OUTPUT"
+        # 0 pass · 1 flow failure (failure clip rendered) · 2 quality · 3 infra · 4 usage
+        echo "playhead exit code: $code"
+        exit $code
+
+    - name: Upload artifacts (videos, verdicts, contact sheets, failure clips)
+      if: always()
+      uses: actions/upload-artifact@v4
+      with:
+        name: playhead-${{ github.run_id }}
+        path: |
+          ${{ inputs.out }}/**/*.mp4
+          ${{ inputs.out }}/**/verdict.json
+          ${{ inputs.out }}/**/contact-sheet.png
+          ${{ inputs.out }}/**/failure.json
+          ${{ inputs.out }}/junit.xml
+        if-no-files-found: ignore

package/dist/audio/mux.d.ts

@@ -0,0 +1,29 @@
+import type { StepMapEntry, ClickRipple } from '../compose/types.js';
+import type { NarrationClip } from './tts.js';
+export interface PlacedClip {
+    stepRef: string;
+    /** Output-clock ms the clip starts playing. */
+    tStart: number;
+    durMs: number;
+}
+export interface AudioBedOptions {
+    /** Narration clips per stepRef (absent = no narration). */
+    narration?: Map<string, NarrationClip>;
+    /** Click-beat times (output clock) that get a soft synthesized tick. */
+    sfxBeats?: ClickRipple[];
+    /** User-supplied music bed (no asset is bundled). */
+    music?: {
+        file: string;
+        gainDb: number;
+    };
+    /** Directory for the synthesized click sample (cached). */
+    cacheDir: string;
+}
+/**
+ * Build the full audio track — narration clips at their step starts, click ticks at ripple
+ * beats, an optional music bed ducked under narration — normalize loudness (EBU R128, I=-16),
+ * and mux it onto the rendered MP4. Returns where each narration clip landed so verification
+ * can reason about voice windows.
+ */
+export declare function mixAudio(videoPath: string, steps: StepMapEntry[], durationMs: number, opts: AudioBedOptions): Promise<PlacedClip[]>;
+//# sourceMappingURL=mux.d.ts.map

package/dist/audio/mux.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mux.d.ts","sourceRoot":"","sources":["../../src/audio/mux.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAO9C,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,2DAA2D;IAC3D,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACvC,wEAAwE;IACxE,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC;IACzB,qDAAqD;IACrD,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAC5B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,YAAY,EAAE,EACrB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,eAAe,GACpB,OAAO,CAAC,UAAU,EAAE,CAAC,CAyFvB"}

package/dist/audio/timing.d.ts

@@ -0,0 +1,6 @@
+/** Narration placement constants, shared by the timeline (dwell fitting) and the muxer. */
+/** A step's spoken line starts this long after the step (and its caption) begin. */
+export declare const AUDIO_LEAD_MS = 150;
+/** Silence kept after a spoken line finishes before the step is allowed to end. */
+export declare const AUDIO_TAIL_MS = 450;
+//# sourceMappingURL=timing.d.ts.map

package/dist/audio/timing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing.d.ts","sourceRoot":"","sources":["../../src/audio/timing.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAE3F,oFAAoF;AACpF,eAAO,MAAM,aAAa,MAAM,CAAC;AACjC,mFAAmF;AACnF,eAAO,MAAM,aAAa,MAAM,CAAC"}

package/dist/audio/tts.d.ts

@@ -0,0 +1,23 @@
+export interface NarrationOptions {
+    /** Only 'say' (macOS local TTS) is implemented today; the seam is here for cloud providers. */
+    provider: 'say';
+    voice?: string;
+    /** Words per minute (say-specific). */
+    rate?: number;
+}
+export interface NarrationLine {
+    stepRef: string;
+    text: string;
+}
+export interface NarrationClip {
+    stepRef: string;
+    file: string;
+    durationMs: number;
+}
+/**
+ * Synthesize one clip per line. Clips are cached by a content hash of
+ * (provider, voice, rate, text) so re-renders reuse them — keeping compose offline
+ * and deterministic (same text+voice → same audio → same timing).
+ */
+export declare function synthesizeNarration(lines: NarrationLine[], opts: NarrationOptions, cacheDir: string): Promise<Map<string, NarrationClip>>;
+//# sourceMappingURL=tts.d.ts.map

package/dist/audio/tts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tts.d.ts","sourceRoot":"","sources":["../../src/audio/tts.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,gBAAgB;IAC/B,+FAA+F;IAC/F,QAAQ,EAAE,KAAK,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AAqCD;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,aAAa,EAAE,EACtB,IAAI,EAAE,gBAAgB,EACtB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAWrC"}

package/dist/authoring/author.d.ts

@@ -0,0 +1,40 @@
+import type { Driver } from '../capture/driver-api.js';
+import { type PageSnapshot } from './explore.js';
+import { type AuthoredStep } from './serialize.js';
+export interface StepDecision {
+    done: boolean;
+    reason?: string;
+    scene: string;
+    action?: AuthoredStep['action'];
+    locator?: string;
+    text?: string;
+    value?: string;
+    keys?: string;
+    caption?: string;
+    mask?: boolean;
+}
+/** Chooses the next step from the current screen. Default is Claude; injectable for tests/policies. */
+export type Decider = (goal: string, snap: PageSnapshot, soFar: AuthoredStep[]) => Promise<StepDecision>;
+export interface AuthorOptions {
+    url: string;
+    goal: string;
+    outPath: string;
+    title?: string;
+    viewport: {
+        w: number;
+        h: number;
+    };
+    maxSteps: number;
+    headless: boolean;
+    driver?: Driver;
+    /** Override the step decider (defaults to the Claude-backed one). */
+    decide?: Decider;
+}
+/** Agent-author a grounded, validated spec by walking the app toward the goal. Needs ANTHROPIC_API_KEY. */
+export declare function authorSpec(opts: AuthorOptions): Promise<{
+    specPath: string;
+    steps: AuthoredStep[];
+}>;
+/** The default decider: ask Claude for the next step, forcing a structured tool call. */
+export declare function claudeDecider(): Decider;
+//# sourceMappingURL=author.d.ts.map

package/dist/authoring/author.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"author.d.ts","sourceRoot":"","sources":["../../src/authoring/author.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAGvD,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,EAAoC,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAGrF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,uGAAuG;AACvG,MAAM,MAAM,OAAO,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;AAEzG,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAsCD,2GAA2G;AAC3G,wBAAsB,UAAU,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,YAAY,EAAE,CAAA;CAAE,CAAC,CAgD1G;AAED,yFAAyF;AACzF,wBAAgB,aAAa,IAAI,OAAO,CA0CvC"}

package/dist/authoring/catalog.d.ts

@@ -0,0 +1,31 @@
+import type { RawInteractable } from '../capture/driver-api.js';
+export type CatalogKind = 'button' | 'link' | 'input' | 'select' | 'toggle' | 'heading' | 'other';
+export interface CatalogEntry {
+    kind: CatalogKind;
+    role: string | null;
+    name: string | null;
+    /** The chosen, validated Playhead locator string. */
+    locator: string;
+    /** Whether `locator` resolves to exactly one element. */
+    unique: boolean;
+    /** How likely the locator survives app changes: testid/role+name high, label medium, text low. */
+    stability: 'high' | 'medium' | 'low';
+    /** Landmark region: nav | header | sidebar | main | dialog | footer | page. */
+    region: string;
+    bbox: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    visible: boolean;
+    options?: string[];
+}
+/** Stability of a locator string by its engine — a maintenance signal for authors. */
+export declare function stabilityOf(locatorRaw: string): 'high' | 'medium' | 'low';
+/** Ordered locator candidates for an element, best (most resilient/readable) first. */
+export declare function candidateLocators(el: RawInteractable): string[];
+export declare function kindOf(el: RawInteractable): CatalogKind;
+/** Quote for an EXACT locator match; fall back to a regex when the text has awkward characters. */
+export declare function quote(s: string): string;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/authoring/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/authoring/catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEhE,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;AAElG,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,MAAM,EAAE,OAAO,CAAC;IAChB,kGAAkG;IAClG,SAAS,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACrC,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACrD,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,sFAAsF;AACtF,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAMzE;AAKD,uFAAuF;AACvF,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,eAAe,GAAG,MAAM,EAAE,CAkB/D;AAED,wBAAgB,MAAM,CAAC,EAAE,EAAE,eAAe,GAAG,WAAW,CAQvD;AAED,mGAAmG;AACnG,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAMvC"}

package/dist/authoring/explore.d.ts

@@ -0,0 +1,30 @@
+import type { Driver } from '../capture/driver-api.js';
+import { type CatalogEntry } from './catalog.js';
+export interface PageSnapshot {
+    url: string;
+    title: string;
+    aria: string;
+    catalog: CatalogEntry[];
+}
+/**
+ * Explore the app in its current state: read every interactable, choose the first locator
+ * candidate that resolves uniquely against the live DOM, and return a grounded catalog.
+ * This is what makes authored specs correct by construction — locators are validated here,
+ * not discovered to be wrong at render time.
+ */
+export declare function snapshotPage(driver: Driver): Promise<PageSnapshot>;
+/** One-shot exploration: launch, navigate, snapshot, close. Used by `playhead explore`. */
+export declare function exploreUrl(url: string, opts?: {
+    viewport?: {
+        w: number;
+        h: number;
+    };
+    headless?: boolean;
+    driver?: Driver;
+    /** storageState JSON (from `playhead login`) so authed screens are exploreable. */
+    storageStatePath?: string;
+}): Promise<PageSnapshot>;
+/** Render a catalog as a compact, human/agent-readable table: grouped by page REGION (where
+ *  the element lives), then by kind, with a stability signal per locator. */
+export declare function formatCatalog(snap: PageSnapshot): string;
+//# sourceMappingURL=explore.d.ts.map

package/dist/authoring/explore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explore.d.ts","sourceRoot":"","sources":["../../src/authoring/explore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAGvD,OAAO,EAA0C,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAEzF,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,EAAE,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CA+CxE;AAED,2FAA2F;AAC3F,wBAAsB,UAAU,CAC9B,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE;IACL,QAAQ,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACpC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mFAAmF;IACnF,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,GACA,OAAO,CAAC,YAAY,CAAC,CAkBvB;AAED;6EAC6E;AAC7E,wBAAgB,aAAa,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAyBxD"}

package/dist/authoring/serialize.d.ts

@@ -0,0 +1,26 @@
+/** An action the author loop decided on and (usually) executed to advance the app. */
+export interface AuthoredStep {
+    action: 'goto' | 'click' | 'dblclick' | 'hover' | 'type' | 'press' | 'select' | 'scroll' | 'expect';
+    scene: string;
+    locator?: string;
+    text?: string;
+    value?: string;
+    keys?: string;
+    url?: string;
+    visible?: boolean;
+    caption?: string;
+    mask?: boolean;
+}
+export interface AuthoredSpec {
+    title: string;
+    url: string;
+    viewport: {
+        w: number;
+        h: number;
+    };
+    kind: string;
+    steps: AuthoredStep[];
+}
+/** Serialize an authored spec into clean, human-editable Playhead YAML, grouped into scenes. */
+export declare function serializeSpec(spec: AuthoredSpec): string;
+//# sourceMappingURL=serialize.d.ts.map

package/dist/authoring/serialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../../src/authoring/serialize.ts"],"names":[],"mappings":"AAEA,sFAAsF;AACtF,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,UAAU,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACpG,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,YAAY,EAAE,CAAC;CACvB;AA6BD,gGAAgG;AAChG,wBAAgB,aAAa,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CA4BxD"}

package/dist/authoring/validate.d.ts

@@ -0,0 +1,31 @@
+import type { Spec } from '../spec/schema.js';
+import type { Driver } from '../capture/driver-api.js';
+export interface ValidateIssue {
+    stepRef: string;
+    step: string;
+    locator: string;
+    severity: 'error' | 'warn';
+    message: string;
+    suggestions: string[];
+}
+export interface ValidateResult {
+    ok: boolean;
+    checked: number;
+    issues: ValidateIssue[];
+}
+/**
+ * Live preflight: walk the spec against the running app in ONE browser pass, checking every
+ * locator (the action target, the focus hint, waits, expects) *before* any frame is ever
+ * captured — and report ALL problems at once with nearest-candidate suggestions from the
+ * current screen. Steps are executed fast (no cursor choreography, no filming) so later
+ * locators are checked against the state they'll actually meet.
+ *
+ * This collapses "one bad locator = one full capture run" into a single cheap pass.
+ */
+export declare function validateLive(spec: Spec, opts?: {
+    headless?: boolean;
+    driver?: Driver;
+}): Promise<ValidateResult>;
+/** Human-readable report for the CLI. */
+export declare function formatValidateResult(res: ValidateResult): string;
+//# sourceMappingURL=validate.d.ts.map

package/dist/authoring/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/authoring/validate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAG9C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAMvD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,aAAa,EAAE,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,IAAI,EACV,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7C,OAAO,CAAC,cAAc,CAAC,CAsFzB;AAsFD,yCAAyC;AACzC,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,CAiBhE"}

package/dist/beforeafter.d.ts

@@ -0,0 +1,25 @@
+import type { Spec } from './spec/schema.js';
+import type { Verdict } from './verify/types.js';
+export interface BeforeAfterResult {
+    videoPath: string;
+    before: {
+        videoPath: string;
+        verdict: Verdict;
+    };
+    after: {
+        videoPath: string;
+        verdict: Verdict;
+    };
+    verdict: 'publishable' | 'not-publishable';
+}
+/**
+ * Render a before/after comparison: run the SAME spec against two versions of the app
+ * (app.compareUrl = before, app.url = after), compose each with the full pipeline, verify both,
+ * and stitch them into one titled clip. Publishable only if both halves are.
+ */
+export declare function renderBeforeAfter(spec: Spec, opts: {
+    outDir: string;
+    headless?: boolean;
+    vision?: boolean;
+}): Promise<BeforeAfterResult>;
+//# sourceMappingURL=beforeafter.d.ts.map

package/dist/beforeafter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"beforeafter.d.ts","sourceRoot":"","sources":["../src/beforeafter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAK7C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAIjD,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAChD,KAAK,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAC/C,OAAO,EAAE,aAAa,GAAG,iBAAiB,CAAC;CAC5C;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,IAAI,EACV,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAC7D,OAAO,CAAC,iBAAiB,CAAC,CAiC5B"}

package/dist/bundle/hash.d.ts

@@ -0,0 +1,3 @@
+export declare function sha256Json(value: unknown): string;
+export declare function sha256File(path: string): Promise<string>;
+//# sourceMappingURL=hash.d.ts.map

package/dist/bundle/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../src/bundle/hash.ts"],"names":[],"mappings":"AAGA,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEjD;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQxD"}

package/dist/bundle/reader.d.ts

@@ -0,0 +1,6 @@
+import type { BundleData, FrameIndexEntry } from './types.js';
+export declare function openBundle(dir: string): Promise<BundleData>;
+/** Index of the latest frame with t ≤ tMs (hold semantics); clamps to the first frame. */
+export declare function frameIndexForTime(frames: FrameIndexEntry[], tMs: number): number;
+export declare function framePath(bundle: BundleData, index: number): string;
+//# sourceMappingURL=reader.d.ts.map

package/dist/bundle/reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader.d.ts","sourceRoot":"","sources":["../../src/bundle/reader.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAkB,eAAe,EAAc,MAAM,YAAY,CAAC;AAG1F,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAgBjE;AAED,0FAA0F;AAC1F,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,eAAe,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAWhF;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnE"}