playhead-cli 0.1.0

package/dist/mcp/server.d.ts

@@ -0,0 +1,10 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Playhead as a set of tools any coding agent can call. The agent grounds its spec with
+ * `playhead_explore`, renders with `playhead_render`, and iterates on the returned verdict —
+ * the whole author → verify → fix loop, inside the agent's own workspace.
+ */
+export declare function buildServer(): McpServer;
+/** Start the stdio MCP server (called by `playhead mcp`). */
+export declare function startMcpServer(): Promise<void>;
+//# sourceMappingURL=server.d.ts.map

package/dist/mcp/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAWpE;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,SAAS,CA6IvC;AAqBD,6DAA6D;AAC7D,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAIpD"}

package/dist/shared/easing.d.ts

@@ -0,0 +1,9 @@
+/** Cubic bezier easing (CSS-style: fixed endpoints (0,0) and (1,1)). Serializable by its four control values. */
+export type BezierParams = [number, number, number, number];
+export declare const EASE_ZOOM: BezierParams;
+export declare const EASE_PAN: BezierParams;
+/** Evaluate a CSS cubic-bezier at progress t ∈ [0,1] (solves x(t)=t for the parameter, returns y). */
+export declare function cubicBezier(p: BezierParams, t: number): number;
+/** Minimum-jerk position profile: smooth human-like travel, s(0)=0, s(1)=1, zero velocity/acceleration at ends. */
+export declare function minJerk(t: number): number;
+//# sourceMappingURL=easing.d.ts.map

package/dist/shared/easing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"easing.d.ts","sourceRoot":"","sources":["../../src/shared/easing.ts"],"names":[],"mappings":"AAAA,iHAAiH;AACjH,MAAM,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAE5D,eAAO,MAAM,SAAS,EAAE,YAA+B,CAAC;AACxD,eAAO,MAAM,QAAQ,EAAE,YAAgC,CAAC;AAExD,sGAAsG;AACtG,wBAAgB,WAAW,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAc9D;AAYD,mHAAmH;AACnH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAIzC"}

package/dist/shared/exit.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Typed exit codes — a CI pipeline must be able to tell WHICH kind of red this is:
+ *
+ *   0  pass          — rendered and publishable
+ *   1  flow failure  — the APP broke the flow (locator gone, expect failed, step timeout);
+ *                      a partial bundle + failure clip exist
+ *   2  quality fail  — the flow ran but the video failed verification (framing, captions, audio)
+ *   3  infra failure — environment problems (browser/ffmpeg missing, launch failed)
+ *   4  usage error   — bad spec / bad arguments
+ *
+ * A test tool that can't distinguish "your app is broken" from "the video is ugly" from
+ * "the runner is misconfigured" gets `|| true`'d. This is the contract that prevents that.
+ */
+export declare const EXIT: {
+    readonly OK: 0;
+    readonly FLOW: 1;
+    readonly QUALITY: 2;
+    readonly INFRA: 3;
+    readonly USAGE: 4;
+};
+/** The app broke the scripted flow (capture-time step failure). */
+export declare class FlowError extends Error {
+    readonly exitCode: 1;
+}
+/** Environment/tooling problem — nothing about the app or the spec. */
+export declare class InfraError extends Error {
+    readonly exitCode: 3;
+}
+/** Classify an arbitrary thrown error into an exit code. SpecErrors are matched by name to
+ *  avoid a circular import with the spec parser. */
+export declare function exitCodeFor(e: unknown): number;
+//# sourceMappingURL=exit.d.ts.map

package/dist/shared/exit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit.d.ts","sourceRoot":"","sources":["../../src/shared/exit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,IAAI;aACf,EAAE,EAAE,CAAC;aACL,IAAI,EAAE,CAAC;aACP,OAAO,EAAE,CAAC;aACV,KAAK,EAAE,CAAC;aACR,KAAK,EAAE,CAAC;CACA,CAAC;AAEX,mEAAmE;AACnE,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,QAAQ,IAAa;CAC/B;AAED,uEAAuE;AACvE,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,QAAQ,IAAc;CAChC;AAED;oDACoD;AACpD,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAU9C"}

package/dist/shared/ffmpeg.d.ts

@@ -0,0 +1,19 @@
+/** Resolve the ffmpeg binary: $PLAYHEAD_FFMPEG override, else the bundled ffmpeg-static build. */
+export declare function ffmpegPath(): string;
+export declare function ffprobePath(): string;
+export interface RunResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+/** Run ffmpeg/ffprobe to completion, capturing output. For the streaming encoder see compose/render/encoder.ts. */
+export declare function runBinary(bin: string, args: string[], stdin?: Buffer): Promise<RunResult>;
+/** Losslessly concatenate H.264 MP4s (same codec/params) into one file via the concat demuxer. */
+export declare function concatVideos(inputs: string[], outPath: string): Promise<void>;
+/** Run ffmpeg, returning raw stdout bytes (for image2pipe extraction). */
+export declare function runBinaryRaw(bin: string, args: string[]): Promise<{
+    code: number;
+    stdout: Buffer;
+    stderr: string;
+}>;
+//# sourceMappingURL=ffmpeg.d.ts.map

package/dist/shared/ffmpeg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ffmpeg.d.ts","sourceRoot":"","sources":["../../src/shared/ffmpeg.ts"],"names":[],"mappings":"AAKA,kGAAkG;AAClG,wBAAgB,UAAU,IAAI,MAAM,CAKnC;AAED,wBAAgB,WAAW,IAAI,MAAM,CAIpC;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,mHAAmH;AACnH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAkBzF;AAED,kGAAkG;AAClG,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBnF;AAED,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAYnH"}

package/dist/shared/geometry.d.ts

@@ -0,0 +1,47 @@
+/** Axis-aligned rectangle. Space is documented at each use site (viewport CSS px, frame px, or output px). */
+export interface Rect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface Point {
+    x: number;
+    y: number;
+}
+export declare function rectCenter(r: Rect): Point;
+export declare function rectUnion(a: Rect, b: Rect): Rect;
+export declare function padRect(r: Rect, pad: number): Rect;
+/** True when `inner` lies fully inside `outer`, with an optional margin inside `outer`. */
+export declare function rectContains(outer: Rect, inner: Rect, margin?: number): boolean;
+export declare function clamp(v: number, min: number, max: number): number;
+export declare function lerp(a: number, b: number, t: number): number;
+export declare function dist(a: Point, b: Point): number;
+/**
+ * Camera state on the source viewport plane. The visible window always has the
+ * OUTPUT aspect ratio (width-anchored): zoom=1 shows the full viewport width,
+ * with height vpW/zoom/outAspect — the camera pans vertically over pages taller
+ * than 16:9 rather than distorting them.
+ */
+export interface CameraState {
+    cx: number;
+    cy: number;
+    zoom: number;
+}
+export interface CameraPlane {
+    vpW: number;
+    vpH: number;
+    outW: number;
+    outH: number;
+}
+/** The viewport-space rect visible at a camera state (output-aspect, width-anchored). */
+export declare function visibleRect(cam: CameraState, plane: CameraPlane): Rect;
+/** Minimum zoom that keeps the visible window inside a page of this height. */
+export declare function minZoom(plane: CameraPlane): number;
+/** Clamp a camera so its visible rect stays inside the viewport. */
+export declare function clampCamera(cam: CameraState, plane: CameraPlane): CameraState;
+/** Project a viewport-space rect into output space given a camera state. */
+export declare function projectRect(r: Rect, cam: CameraState, plane: CameraPlane): Rect;
+/** Project a viewport-space point into output space given a camera state. */
+export declare function projectPoint(p: Point, cam: CameraState, plane: CameraPlane): Point;
+//# sourceMappingURL=geometry.d.ts.map

package/dist/shared/geometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geometry.d.ts","sourceRoot":"","sources":["../../src/shared/geometry.ts"],"names":[],"mappings":"AAAA,8GAA8G;AAC9G,MAAM,WAAW,IAAI;IACnB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,MAAM,WAAW,KAAK;IACpB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,wBAAgB,UAAU,CAAC,CAAC,EAAE,IAAI,GAAG,KAAK,CAEzC;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,IAAI,CAShD;AAED,wBAAgB,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAElD;AAED,2FAA2F;AAC3F,wBAAgB,YAAY,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,SAAI,GAAG,OAAO,CAO1E;AAED,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,wBAAgB,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,MAAM,CAE/C;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,yFAAyF;AACzF,wBAAgB,WAAW,CAAC,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAItE;AAED,+EAA+E;AAC/E,wBAAgB,OAAO,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAElD;AAED,oEAAoE;AACpE,wBAAgB,WAAW,CAAC,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,GAAG,WAAW,CAS7E;AAED,4EAA4E;AAC5E,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAI/E;AAED,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,GAAG,KAAK,CAIlF"}

package/dist/shared/log.d.ts

@@ -0,0 +1,10 @@
+export declare function setVerbose(v: boolean): void;
+export declare const log: {
+    info(msg: string): void;
+    step(msg: string): void;
+    ok(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+    debug(msg: string): void;
+};
+//# sourceMappingURL=log.d.ts.map

package/dist/shared/log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../../src/shared/log.ts"],"names":[],"mappings":"AAIA,wBAAgB,UAAU,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAE3C;AAID,eAAO,MAAM,GAAG;IACd,IAAI,MAAM,MAAM,GAAG,IAAI;IAGvB,IAAI,MAAM,MAAM,GAAG,IAAI;IAGvB,EAAE,MAAM,MAAM,GAAG,IAAI;IAGrB,IAAI,MAAM,MAAM,GAAG,IAAI;IAGvB,KAAK,MAAM,MAAM,GAAG,IAAI;IAGxB,KAAK,MAAM,MAAM,GAAG,IAAI;CAGzB,CAAC"}

package/dist/shared/version.d.ts

@@ -0,0 +1,4 @@
+/** The ONE version source: package.json. Bundle manifests, the CLI, the MCP server, and
+ *  verdict provenance all read this — they can never disagree with the installed package. */
+export declare const PLAYHEAD_VERSION: string;
+//# sourceMappingURL=version.d.ts.map

package/dist/shared/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/shared/version.ts"],"names":[],"mappings":"AAEA;6FAC6F;AAC7F,eAAO,MAAM,gBAAgB,EAAE,MAEtB,CAAC"}

package/dist/spec/locators.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Playhead locator grammar — resilient, label/role-based element addressing.
+ *
+ *   role=button[name="Add user"]     role + accessible name
+ *   role=cell[name=/api key/i]       regex accessible name
+ *   label=Email                      form control by label
+ *   text="User added"                visible text
+ *   placeholder=Search               input placeholder
+ *   testid=add-user                  data-testid
+ *   css=#legacy .thing               escape hatch (warned)
+ *   ... >> nth=1                     pick among multiple matches
+ *   frame=#preview >> role=button[name="Save"]      pierce into an iframe (chainable)
+ *   frame=iframe[name=a] >> frame=#inner >> text="Hi"  nested frames
+ *
+ * Parsed form is serializable (regexes stored as {source, flags}) so it can live
+ * in spec.resolved.json and events.json.
+ */
+export interface RegexSpec {
+    source: string;
+    flags: string;
+}
+export type TextMatch = {
+    exact: string;
+} | {
+    substring: string;
+} | {
+    regex: RegexSpec;
+};
+export type LocatorBase = {
+    kind: 'role';
+    role: string;
+    name?: TextMatch;
+} | {
+    kind: 'label';
+    match: TextMatch;
+} | {
+    kind: 'text';
+    match: TextMatch;
+} | {
+    kind: 'placeholder';
+    match: TextMatch;
+} | {
+    kind: 'testid';
+    value: string;
+} | {
+    kind: 'css';
+    selector: string;
+};
+export interface ParsedLocator {
+    base: LocatorBase;
+    nth?: number;
+    /** CSS selectors of the iframe chain to pierce (outermost first) before resolving `base`. */
+    frames?: string[];
+    /** The original spec string, kept for captions/diagnostics. */
+    raw: string;
+}
+export declare class LocatorParseError extends Error {
+}
+export declare function parseLocator(input: string): ParsedLocator;
+/** Human-readable form of what a locator points at, used for captions when the accessible name is unavailable. */
+export declare function locatorDisplayName(loc: ParsedLocator): string;
+//# sourceMappingURL=locators.d.ts.map

package/dist/spec/locators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locators.d.ts","sourceRoot":"","sources":["../../src/spec/locators.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,SAAS,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,SAAS,CAAA;CAAE,CAAC;AAEzF,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,SAAS,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtC,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,6FAA6F;IAC7F,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,+DAA+D;IAC/D,GAAG,EAAE,MAAM,CAAC;CACb;AAED,qBAAa,iBAAkB,SAAQ,KAAK;CAAG;AAE/C,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CA4DzD;AA0BD,kHAAkH;AAClH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAc7D"}

package/dist/spec/parse.d.ts

@@ -0,0 +1,16 @@
+import { type Spec } from './schema.js';
+export declare class SpecError extends Error {
+    readonly issues: string[];
+    constructor(message: string, issues?: string[]);
+}
+/**
+ * Parse + validate YAML text into a Spec. Supports:
+ * - `vars:` — `{{name}}` interpolation across every string in the spec; values may reference
+ *   the environment as `${env.NAME}` or `${env.NAME:-default}`. Unknown `{{var}}` is an error.
+ * - line/column positions on every validation error (mapped back to the YAML source).
+ * `extends:` requires file context — use loadSpec.
+ */
+export declare function parseSpec(yamlText: string, sourcePath?: string): Spec;
+/** Load a spec file, resolving `extends:` (base file merged under this one) and `vars:`. */
+export declare function loadSpec(path: string): Promise<Spec>;
+//# sourceMappingURL=parse.d.ts.map

package/dist/spec/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/spec/parse.ts"],"names":[],"mappings":"AAIA,OAAO,EAA4B,KAAK,IAAI,EAAE,MAAM,aAAa,CAAC;AAElE,qBAAa,SAAU,SAAQ,KAAK;aAGhB,MAAM,EAAE,MAAM,EAAE;IAFlC,YACE,OAAO,EAAE,MAAM,EACC,MAAM,GAAE,MAAM,EAAO,EAGtC;CACF;AA6BD;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,SAAa,GAAG,IAAI,CAYzE;AAED,4FAA4F;AAC5F,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ1D"}

package/dist/spec/schema.d.ts

@@ -0,0 +1,365 @@
+import { z } from 'zod';
+export declare const stepSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    caption: z.ZodOptional<z.ZodString>;
+    narration: z.ZodOptional<z.ZodString>;
+    focus: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"target">, z.ZodLiteral<"wide">, z.ZodString]>>;
+    shot: z.ZodOptional<z.ZodEnum<{
+        continue: "continue";
+        cut: "cut";
+    }>>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+    action: z.ZodLiteral<"goto">;
+    url: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    caption: z.ZodOptional<z.ZodString>;
+    narration: z.ZodOptional<z.ZodString>;
+    focus: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"target">, z.ZodLiteral<"wide">, z.ZodString]>>;
+    shot: z.ZodOptional<z.ZodEnum<{
+        continue: "continue";
+        cut: "cut";
+    }>>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+    action: z.ZodEnum<{
+        click: "click";
+        dblclick: "dblclick";
+        hover: "hover";
+    }>;
+    target: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    caption: z.ZodOptional<z.ZodString>;
+    narration: z.ZodOptional<z.ZodString>;
+    focus: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"target">, z.ZodLiteral<"wide">, z.ZodString]>>;
+    shot: z.ZodOptional<z.ZodEnum<{
+        continue: "continue";
+        cut: "cut";
+    }>>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+    action: z.ZodLiteral<"type">;
+    target: z.ZodString;
+    text: z.ZodString;
+    mask: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>, z.ZodObject<{
+    caption: z.ZodOptional<z.ZodString>;
+    narration: z.ZodOptional<z.ZodString>;
+    focus: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"target">, z.ZodLiteral<"wide">, z.ZodString]>>;
+    shot: z.ZodOptional<z.ZodEnum<{
+        continue: "continue";
+        cut: "cut";
+    }>>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+    action: z.ZodLiteral<"press">;
+    keys: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    caption: z.ZodOptional<z.ZodString>;
+    narration: z.ZodOptional<z.ZodString>;
+    focus: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"target">, z.ZodLiteral<"wide">, z.ZodString]>>;
+    shot: z.ZodOptional<z.ZodEnum<{
+        continue: "continue";
+        cut: "cut";
+    }>>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+    action: z.ZodLiteral<"select">;
+    target: z.ZodString;
+    value: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    caption: z.ZodOptional<z.ZodString>;
+    narration: z.ZodOptional<z.ZodString>;
+    focus: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"target">, z.ZodLiteral<"wide">, z.ZodString]>>;
+    shot: z.ZodOptional<z.ZodEnum<{
+        continue: "continue";
+        cut: "cut";
+    }>>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+    action: z.ZodLiteral<"scroll">;
+    target: z.ZodOptional<z.ZodString>;
+    by: z.ZodOptional<z.ZodObject<{
+        x: z.ZodDefault<z.ZodNumber>;
+        y: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    caption: z.ZodOptional<z.ZodString>;
+    narration: z.ZodOptional<z.ZodString>;
+    focus: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"target">, z.ZodLiteral<"wide">, z.ZodString]>>;
+    shot: z.ZodOptional<z.ZodEnum<{
+        continue: "continue";
+        cut: "cut";
+    }>>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+    action: z.ZodLiteral<"expect">;
+    target: z.ZodString;
+    visible: z.ZodOptional<z.ZodBoolean>;
+    text: z.ZodOptional<z.ZodString>;
+    count: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    caption: z.ZodOptional<z.ZodString>;
+    narration: z.ZodOptional<z.ZodString>;
+    focus: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"target">, z.ZodLiteral<"wide">, z.ZodString]>>;
+    shot: z.ZodOptional<z.ZodEnum<{
+        continue: "continue";
+        cut: "cut";
+    }>>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+    action: z.ZodLiteral<"wait">;
+    ms: z.ZodOptional<z.ZodNumber>;
+    for: z.ZodOptional<z.ZodString>;
+    state: z.ZodDefault<z.ZodEnum<{
+        hidden: "hidden";
+        visible: "visible";
+    }>>;
+}, z.core.$strict>], "action">;
+export type Step = z.infer<typeof stepSchema>;
+export declare function editDistance(a: string, b: string): number;
+export declare const specSchema: z.ZodObject<{
+    playhead: z.ZodLiteral<1>;
+    title: z.ZodString;
+    subtitle: z.ZodOptional<z.ZodString>;
+    app: z.ZodObject<{
+        url: z.ZodString;
+        viewport: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<{
+            w: number;
+            h: number;
+        }, string>>>;
+        storageState: z.ZodOptional<z.ZodString>;
+        assertLoggedIn: z.ZodOptional<z.ZodString>;
+        compareUrl: z.ZodOptional<z.ZodString>;
+        environment: z.ZodOptional<z.ZodObject<{
+            timezone: z.ZodOptional<z.ZodString>;
+            locale: z.ZodOptional<z.ZodString>;
+            colorScheme: z.ZodOptional<z.ZodEnum<{
+                dark: "dark";
+                light: "light";
+            }>>;
+            fixedTime: z.ZodOptional<z.ZodString>;
+            reducedMotion: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+        network: z.ZodOptional<z.ZodObject<{
+            block: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            stub: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                url: z.ZodString;
+                status: z.ZodOptional<z.ZodNumber>;
+                body: z.ZodOptional<z.ZodString>;
+                contentType: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>>;
+            har: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        dialogs: z.ZodOptional<z.ZodEnum<{
+            accept: "accept";
+            dismiss: "dismiss";
+        }>>;
+        settle: z.ZodOptional<z.ZodObject<{
+            idleMs: z.ZodOptional<z.ZodNumber>;
+            capMs: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    output: z.ZodPrefault<z.ZodObject<{
+        kind: z.ZodDefault<z.ZodEnum<{
+            "before-after": "before-after";
+            "bug-repro": "bug-repro";
+            demo: "demo";
+            release: "release";
+            social: "social";
+            walkthrough: "walkthrough";
+        }>>;
+        aspect: z.ZodDefault<z.ZodEnum<{
+            "16:9": "16:9";
+            "1:1": "1:1";
+            "9:16": "9:16";
+        }>>;
+        resolution: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<{
+            w: number;
+            h: number;
+        }, string>>>;
+        fps: z.ZodDefault<z.ZodNumber>;
+        pacing: z.ZodOptional<z.ZodEnum<{
+            brisk: "brisk";
+            normal: "normal";
+            relaxed: "relaxed";
+        }>>;
+        dwellScale: z.ZodOptional<z.ZodNumber>;
+        audio: z.ZodOptional<z.ZodObject<{
+            narration: z.ZodDefault<z.ZodEnum<{
+                none: "none";
+                tts: "tts";
+            }>>;
+            provider: z.ZodDefault<z.ZodEnum<{
+                say: "say";
+            }>>;
+            voice: z.ZodOptional<z.ZodString>;
+            rate: z.ZodOptional<z.ZodNumber>;
+            sfx: z.ZodDefault<z.ZodBoolean>;
+            music: z.ZodOptional<z.ZodObject<{
+                file: z.ZodString;
+                gainDb: z.ZodDefault<z.ZodNumber>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+        endCard: z.ZodOptional<z.ZodObject<{
+            title: z.ZodString;
+            subtitle: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    theme: z.ZodPrefault<z.ZodObject<{
+        accent: z.ZodOptional<z.ZodString>;
+        captions: z.ZodDefault<z.ZodEnum<{
+            bottom: "bottom";
+            off: "off";
+            top: "top";
+        }>>;
+    }, z.core.$strict>>;
+    masking: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        target: z.ZodString;
+        style: z.ZodDefault<z.ZodEnum<{
+            blur: "blur";
+            solid: "solid";
+        }>>;
+    }, z.core.$strict>>>;
+    scenes: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        steps: z.ZodArray<z.ZodPipe<z.ZodPipe<z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodTransform<unknown, Record<string, unknown>>>, z.ZodDiscriminatedUnion<[z.ZodObject<{
+            caption: z.ZodOptional<z.ZodString>;
+            narration: z.ZodOptional<z.ZodString>;
+            focus: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"target">, z.ZodLiteral<"wide">, z.ZodString]>>;
+            shot: z.ZodOptional<z.ZodEnum<{
+                continue: "continue";
+                cut: "cut";
+            }>>;
+            timeout: z.ZodOptional<z.ZodNumber>;
+            action: z.ZodLiteral<"goto">;
+            url: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            caption: z.ZodOptional<z.ZodString>;
+            narration: z.ZodOptional<z.ZodString>;
+            focus: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"target">, z.ZodLiteral<"wide">, z.ZodString]>>;
+            shot: z.ZodOptional<z.ZodEnum<{
+                continue: "continue";
+                cut: "cut";
+            }>>;
+            timeout: z.ZodOptional<z.ZodNumber>;
+            action: z.ZodEnum<{
+                click: "click";
+                dblclick: "dblclick";
+                hover: "hover";
+            }>;
+            target: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            caption: z.ZodOptional<z.ZodString>;
+            narration: z.ZodOptional<z.ZodString>;
+            focus: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"target">, z.ZodLiteral<"wide">, z.ZodString]>>;
+            shot: z.ZodOptional<z.ZodEnum<{
+                continue: "continue";
+                cut: "cut";
+            }>>;
+            timeout: z.ZodOptional<z.ZodNumber>;
+            action: z.ZodLiteral<"type">;
+            target: z.ZodString;
+            text: z.ZodString;
+            mask: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strict>, z.ZodObject<{
+            caption: z.ZodOptional<z.ZodString>;
+            narration: z.ZodOptional<z.ZodString>;
+            focus: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"target">, z.ZodLiteral<"wide">, z.ZodString]>>;
+            shot: z.ZodOptional<z.ZodEnum<{
+                continue: "continue";
+                cut: "cut";
+            }>>;
+            timeout: z.ZodOptional<z.ZodNumber>;
+            action: z.ZodLiteral<"press">;
+            keys: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            caption: z.ZodOptional<z.ZodString>;
+            narration: z.ZodOptional<z.ZodString>;
+            focus: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"target">, z.ZodLiteral<"wide">, z.ZodString]>>;
+            shot: z.ZodOptional<z.ZodEnum<{
+                continue: "continue";
+                cut: "cut";
+            }>>;
+            timeout: z.ZodOptional<z.ZodNumber>;
+            action: z.ZodLiteral<"select">;
+            target: z.ZodString;
+            value: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            caption: z.ZodOptional<z.ZodString>;
+            narration: z.ZodOptional<z.ZodString>;
+            focus: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"target">, z.ZodLiteral<"wide">, z.ZodString]>>;
+            shot: z.ZodOptional<z.ZodEnum<{
+                continue: "continue";
+                cut: "cut";
+            }>>;
+            timeout: z.ZodOptional<z.ZodNumber>;
+            action: z.ZodLiteral<"scroll">;
+            target: z.ZodOptional<z.ZodString>;
+            by: z.ZodOptional<z.ZodObject<{
+                x: z.ZodDefault<z.ZodNumber>;
+                y: z.ZodNumber;
+            }, z.core.$strict>>;
+        }, z.core.$strict>, z.ZodObject<{
+            caption: z.ZodOptional<z.ZodString>;
+            narration: z.ZodOptional<z.ZodString>;
+            focus: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"target">, z.ZodLiteral<"wide">, z.ZodString]>>;
+            shot: z.ZodOptional<z.ZodEnum<{
+                continue: "continue";
+                cut: "cut";
+            }>>;
+            timeout: z.ZodOptional<z.ZodNumber>;
+            action: z.ZodLiteral<"expect">;
+            target: z.ZodString;
+            visible: z.ZodOptional<z.ZodBoolean>;
+            text: z.ZodOptional<z.ZodString>;
+            count: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>, z.ZodObject<{
+            caption: z.ZodOptional<z.ZodString>;
+            narration: z.ZodOptional<z.ZodString>;
+            focus: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"target">, z.ZodLiteral<"wide">, z.ZodString]>>;
+            shot: z.ZodOptional<z.ZodEnum<{
+                continue: "continue";
+                cut: "cut";
+            }>>;
+            timeout: z.ZodOptional<z.ZodNumber>;
+            action: z.ZodLiteral<"wait">;
+            ms: z.ZodOptional<z.ZodNumber>;
+            for: z.ZodOptional<z.ZodString>;
+            state: z.ZodDefault<z.ZodEnum<{
+                hidden: "hidden";
+                visible: "visible";
+            }>>;
+        }, z.core.$strict>], "action">>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type Spec = z.infer<typeof specSchema>;
+export type Scene = Spec['scenes'][number];
+export type OutputSettings = Spec['output'];
+export type MaskRule = Spec['masking'][number];
+export type OutputKind = Spec['output']['kind'];
+export type Aspect = Spec['output']['aspect'];
+/** Capture viewport + output resolution for each aspect (portrait/square reflow, never crop). */
+export declare const ASPECTS: Record<Aspect, {
+    viewport: {
+        w: number;
+        h: number;
+    };
+    resolution: {
+        w: number;
+        h: number;
+    };
+}>;
+/** The capture viewport: explicit spec value, else derived from the output aspect. */
+export declare function resolveViewport(spec: Spec): {
+    w: number;
+    h: number;
+};
+/** The output resolution: explicit spec value, else derived from the aspect. */
+export declare function resolveResolution(spec: Spec): {
+    w: number;
+    h: number;
+};
+/** A step with its position in the spec — the unit the capture executor and compositor work in. */
+export interface AddressedStep {
+    sceneId: string;
+    sceneIndex: number;
+    stepIndex: number;
+    /** Global 1-based index across all scenes, used for step numbering. */
+    ordinal: number;
+    step: Step;
+}
+export declare function flattenSteps(spec: Spec): AddressedStep[];
+//# sourceMappingURL=schema.d.ts.map

package/dist/spec/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/spec/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA8GxB,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;8BASrB,CAAC;AAEH,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAmD9C,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAazD;AA+BD,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAqJZ,CAAC;AAEZ,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAC9C,MAAM,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;AAC3C,MAAM,MAAM,cAAc,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC;AAC5C,MAAM,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAC/C,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;AAChD,MAAM,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAC,CAAC;AAE9C,iGAAiG;AACjG,eAAO,MAAM,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,QAAQ,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAAC,UAAU,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAIhH,CAAC;AAEF,sFAAsF;AACtF,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAEpE;AAED,gFAAgF;AAChF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAEtE;AAED,mGAAmG;AACnG,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,IAAI,CAAC;CACZ;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,aAAa,EAAE,CAUxD"}

package/dist/theme/index.d.ts

@@ -0,0 +1,23 @@
+import type { Spec } from '../spec/schema.js';
+export interface ResolvedTheme {
+    name: string;
+    /** Accent color for cursor ripple, badges, highlights. */
+    accent: string;
+    /** Title-card and letterbox background. */
+    bg: string;
+    bgSubtle: string;
+    /** Caption card background (rgba string). */
+    surface: string;
+    onSurface: string;
+    onSurfaceDim: string;
+    fontFamily: string;
+    captionFontPx: number;
+    captionMinFontPx: number;
+    captionMaxLines: number;
+    captionPosition: 'bottom' | 'top' | 'off';
+    radius: number;
+}
+export declare function resolveTheme(spec: Spec): ResolvedTheme;
+/** Register bundled Inter faces so rendering is deterministic across machines. */
+export declare function registerFonts(): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/theme/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/theme/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAE9C,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,QAAQ,GAAG,KAAK,GAAG,KAAK,CAAC;IAC1C,MAAM,EAAE,MAAM,CAAC;CAChB;AAoBD,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,aAAa,CAMtD;AAID,kFAAkF;AAClF,wBAAgB,aAAa,IAAI,IAAI,CAoBpC"}