@plaintake/scenario 1.2.1

package/dist/schema/results.d.ts

@@ -0,0 +1,335 @@
+import { z } from 'zod';
+declare const ArtifactRefSchema: z.ZodObject<{
+    path: z.ZodString;
+    sha256: z.ZodString;
+    bytes: z.ZodNumber;
+}, z.core.$strip>;
+export declare const ValidationResultSchema: z.ZodObject<{
+    scenario: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        language: z.ZodString;
+        handoff: z.ZodDefault<z.ZodEnum<{
+            none: "none";
+            preflight: "preflight";
+            session: "session";
+        }>>;
+        sha256: z.ZodString;
+    }, z.core.$strip>>;
+    schema: z.ZodLiteral<"agent-demo.result/v1">;
+    kind: z.ZodLiteral<"validate">;
+    ok: z.ZodBoolean;
+    problems: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export declare const RunCommandResultSchema: z.ZodObject<{
+    bundleDir: z.ZodString;
+    status: z.ZodEnum<{
+        passed: "passed";
+        failed: "failed";
+    }>;
+    cueCount: z.ZodNumber;
+    chapterCount: z.ZodNumber;
+    narratedCount: z.ZodNumber;
+    diagnostics: z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        cueId: z.ZodString;
+        detail: z.ZodString;
+    }, z.core.$strip>>;
+    assertions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        status: z.ZodEnum<{
+            passed: "passed";
+            failed: "failed";
+        }>;
+    }, z.core.$strip>>;
+    outputs: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        sha256: z.ZodString;
+        bytes: z.ZodNumber;
+    }, z.core.$strip>>;
+    schema: z.ZodLiteral<"agent-demo.result/v1">;
+    kind: z.ZodLiteral<"run">;
+    ok: z.ZodBoolean;
+    problems: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export declare const RenderCommandResultSchema: z.ZodObject<{
+    bundleDir: z.ZodString;
+    variants: z.ZodEnum<{
+        soft: "soft";
+        hard: "hard";
+    }>;
+    streams: z.ZodObject<{
+        base: z.ZodOptional<z.ZodObject<{
+            container: z.ZodEnum<{
+                mp4: "mp4";
+                webm: "webm";
+                other: "other";
+            }>;
+            durationMs: z.ZodNumber;
+            video: z.ZodObject<{
+                codec: z.ZodString;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+                pixelFormat: z.ZodString;
+                fps: z.ZodNumber;
+                frames: z.ZodNumber;
+                durationMs: z.ZodNumber;
+            }, z.core.$strip>;
+            subtitles: z.ZodArray<z.ZodObject<{
+                codec: z.ZodString;
+                language: z.ZodString;
+                title: z.ZodString;
+            }, z.core.$strip>>;
+            audio: z.ZodArray<z.ZodObject<{
+                codec: z.ZodString;
+                sampleRate: z.ZodNumber;
+                channels: z.ZodNumber;
+            }, z.core.$strip>>;
+            dataStreams: z.ZodNumber;
+            chapters: z.ZodArray<z.ZodObject<{
+                startMs: z.ZodNumber;
+                endMs: z.ZodNumber;
+                title: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        soft: z.ZodOptional<z.ZodObject<{
+            container: z.ZodEnum<{
+                mp4: "mp4";
+                webm: "webm";
+                other: "other";
+            }>;
+            durationMs: z.ZodNumber;
+            video: z.ZodObject<{
+                codec: z.ZodString;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+                pixelFormat: z.ZodString;
+                fps: z.ZodNumber;
+                frames: z.ZodNumber;
+                durationMs: z.ZodNumber;
+            }, z.core.$strip>;
+            subtitles: z.ZodArray<z.ZodObject<{
+                codec: z.ZodString;
+                language: z.ZodString;
+                title: z.ZodString;
+            }, z.core.$strip>>;
+            audio: z.ZodArray<z.ZodObject<{
+                codec: z.ZodString;
+                sampleRate: z.ZodNumber;
+                channels: z.ZodNumber;
+            }, z.core.$strip>>;
+            dataStreams: z.ZodNumber;
+            chapters: z.ZodArray<z.ZodObject<{
+                startMs: z.ZodNumber;
+                endMs: z.ZodNumber;
+                title: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        hard: z.ZodOptional<z.ZodObject<{
+            container: z.ZodEnum<{
+                mp4: "mp4";
+                webm: "webm";
+                other: "other";
+            }>;
+            durationMs: z.ZodNumber;
+            video: z.ZodObject<{
+                codec: z.ZodString;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+                pixelFormat: z.ZodString;
+                fps: z.ZodNumber;
+                frames: z.ZodNumber;
+                durationMs: z.ZodNumber;
+            }, z.core.$strip>;
+            subtitles: z.ZodArray<z.ZodObject<{
+                codec: z.ZodString;
+                language: z.ZodString;
+                title: z.ZodString;
+            }, z.core.$strip>>;
+            audio: z.ZodArray<z.ZodObject<{
+                codec: z.ZodString;
+                sampleRate: z.ZodNumber;
+                channels: z.ZodNumber;
+            }, z.core.$strip>>;
+            dataStreams: z.ZodNumber;
+            chapters: z.ZodArray<z.ZodObject<{
+                startMs: z.ZodNumber;
+                endMs: z.ZodNumber;
+                title: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    outputs: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        sha256: z.ZodString;
+        bytes: z.ZodNumber;
+    }, z.core.$strip>>;
+    schema: z.ZodLiteral<"agent-demo.result/v1">;
+    kind: z.ZodLiteral<"render">;
+    ok: z.ZodBoolean;
+    problems: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export declare const VerificationReportSchema: z.ZodObject<{
+    bundleDir: z.ZodString;
+    artifactCount: z.ZodNumber;
+    schema: z.ZodLiteral<"agent-demo.result/v1">;
+    kind: z.ZodLiteral<"verify">;
+    ok: z.ZodBoolean;
+    problems: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export declare const InspectResultSchema: z.ZodObject<{
+    bundleDir: z.ZodString;
+    status: z.ZodEnum<{
+        passed: "passed";
+        failed: "failed";
+    }>;
+    scenario: z.ZodObject<{
+        id: z.ZodString;
+        sourceSha256: z.ZodString;
+    }, z.core.$strip>;
+    toolchain: z.ZodObject<{
+        node: z.ZodString;
+        playwright: z.ZodString;
+        chromiumRevision: z.ZodString;
+        ffmpeg: z.ZodString;
+        libass: z.ZodString;
+        fontSha256: z.ZodString;
+    }, z.core.$strip>;
+    video: z.ZodObject<{
+        durationMs: z.ZodNumber;
+        frames: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        fps: z.ZodNumber;
+        contentDurationMs: z.ZodNumber;
+        introDurationMs: z.ZodDefault<z.ZodNumber>;
+        outroDurationMs: z.ZodNumber;
+    }, z.core.$strip>;
+    captions: z.ZodObject<{
+        language: z.ZodString;
+        cueCount: z.ZodNumber;
+        characterCount: z.ZodNumber;
+        medianCueMs: z.ZodNumber;
+        shortestCueMs: z.ZodNumber;
+        longestCueMs: z.ZodNumber;
+    }, z.core.$strip>;
+    chapters: z.ZodArray<z.ZodObject<{
+        startMs: z.ZodNumber;
+        title: z.ZodString;
+    }, z.core.$strip>>;
+    narration: z.ZodOptional<z.ZodObject<{
+        clipCount: z.ZodNumber;
+        spokenMs: z.ZodNumber;
+        suppliedCount: z.ZodNumber;
+        voice: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    outputs: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        sha256: z.ZodString;
+        bytes: z.ZodNumber;
+    }, z.core.$strip>>;
+    assertions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        status: z.ZodEnum<{
+            passed: "passed";
+            failed: "failed";
+        }>;
+    }, z.core.$strip>>;
+    artifactCount: z.ZodNumber;
+    bundleBytes: z.ZodNumber;
+    schema: z.ZodLiteral<"agent-demo.result/v1">;
+    kind: z.ZodLiteral<"inspect">;
+    ok: z.ZodBoolean;
+    problems: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export declare const DoctorResultSchema: z.ZodObject<{
+    version: z.ZodString;
+    ffmpeg: z.ZodString;
+    ffprobe: z.ZodString;
+    libass: z.ZodString;
+    hasLibass: z.ZodBoolean;
+    hasX264: z.ZodBoolean;
+    hasAac: z.ZodBoolean;
+    filters: z.ZodArray<z.ZodString>;
+    speech: z.ZodObject<{
+        ready: z.ZodBoolean;
+        voices: z.ZodArray<z.ZodString>;
+        notes: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    schema: z.ZodLiteral<"agent-demo.result/v1">;
+    kind: z.ZodLiteral<"doctor">;
+    ok: z.ZodBoolean;
+    problems: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export declare const ActivateResultSchema: z.ZodObject<{
+    reason: z.ZodOptional<z.ZodEnum<{
+        "empty-key": "empty-key";
+        "not-found": "not-found";
+        revoked: "revoked";
+        offline: "offline";
+        "unexpected-response": "unexpected-response";
+        "not-configured": "not-configured";
+    }>>;
+    licence: z.ZodOptional<z.ZodObject<{
+        subject: z.ZodString;
+        activatedAt: z.ZodString;
+        uses: z.ZodNumber;
+    }, z.core.$strip>>;
+    schema: z.ZodLiteral<"agent-demo.result/v1">;
+    kind: z.ZodLiteral<"activate">;
+    ok: z.ZodBoolean;
+    problems: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Mirrors `LicenseStatus` in @plaintake/license: a discriminated union on `tier`, so a
+ * caller cannot read `subject` without having established the tier.
+ */
+export declare const LicenceResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    tier: z.ZodLiteral<"free">;
+    problem: z.ZodOptional<z.ZodString>;
+    schema: z.ZodLiteral<"agent-demo.result/v1">;
+    kind: z.ZodLiteral<"licence">;
+    ok: z.ZodBoolean;
+    problems: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    tier: z.ZodLiteral<"pro">;
+    subject: z.ZodString;
+    activatedAt: z.ZodString;
+    uses: z.ZodNumber;
+    schema: z.ZodLiteral<"agent-demo.result/v1">;
+    kind: z.ZodLiteral<"licence">;
+    ok: z.ZodBoolean;
+    problems: z.ZodArray<z.ZodString>;
+}, z.core.$strip>], "tier">;
+export type ArtifactRef = z.infer<typeof ArtifactRefSchema>;
+export type ValidationResult = z.infer<typeof ValidationResultSchema>;
+export type RunCommandResult = z.infer<typeof RunCommandResultSchema>;
+export type RenderCommandResult = z.infer<typeof RenderCommandResultSchema>;
+export type VerificationReport = z.infer<typeof VerificationReportSchema>;
+export type InspectResult = z.infer<typeof InspectResultSchema>;
+export type DoctorResult = z.infer<typeof DoctorResultSchema>;
+export type ActivateResult = z.infer<typeof ActivateResultSchema>;
+export type LicenceResult = z.infer<typeof LicenceResultSchema>;
+export type DemoResult = ValidationResult | RunCommandResult | RenderCommandResult | VerificationReport | InspectResult | DoctorResult | ActivateResult | LicenceResult;
+/**
+ * Renders a filesystem location for display in a result, relative to `root` when it
+ * lies inside it.
+ *
+ * A path outside the root is returned unchanged rather than rejected, because the CLI
+ * is deliberately not sandboxed and `--output /tmp/scratch` is a legitimate
+ * thing to ask for. The MCP server has the opposite requirement — spec §6, "return
+ * relative artifact paths" — and gets it from its sandbox, which resolves every input
+ * beneath the workspace root before this is ever called, so the relative branch always
+ * wins there. `assertNoAbsolutePaths` enforces that at the MCP boundary.
+ *
+ * Note this applies to *locations* like `bundleDir`. Paths *within* a bundle stay
+ * strictly relative, enforced by the schemas above.
+ */
+export declare function toResultPath(root: string, path: string): string;
+/**
+ * Guards the MCP contract: no field anywhere in a result may be an absolute path.
+ * Cheap, and it fails loudly rather than quietly leaking the server's filesystem
+ * layout to a client that asked for workspace-relative paths.
+ */
+export declare function assertNoAbsolutePaths(result: DemoResult): void;
+export {};

package/dist/schema/scenario.d.ts

@@ -0,0 +1,89 @@
+import { z } from 'zod';
+/**
+ * The opening card, declared by the scenario rather than by configuration.
+ *
+ * The counterpart to the closing credit, and deliberately not the same kind of thing. The
+ * outro is *branding* — one card for everything a machine records, owned by the licence and
+ * fixed in code on the Free Tier so the credit cannot be quietly removed. An intro is
+ * *content*: the hook for this demo and no other, which is why it is authored here beside
+ * the steps it introduces and is available on every tier. Only its colours follow branding.
+ *
+ * `narration` is spoken by the same voice that reads a step's `subtitle`, and is optional:
+ * a silent title card is a reasonable thing to want, and a scenario recorded without
+ * `--speech` has no voice to read it with either way. `durationMs` is a floor rather than a
+ * cut — the recorder lengthens the card when the line needs longer, exactly as `holdMs`
+ * gives way to a step's own narration.
+ *
+ * Two lines, matching the outro: same card, same layout, and a third line would have to
+ * shrink the type to fit.
+ */
+export declare const ScenarioIntroSchema: z.ZodObject<{
+    lines: z.ZodArray<z.ZodString>;
+    narration: z.ZodOptional<z.ZodString>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type ScenarioIntro = z.infer<typeof ScenarioIntroSchema>;
+/**
+ * Per-scenario camera framing, for the demos whose pages the defaults do not suit.
+ *
+ * Every field is optional and every default is the constant the camera already used, so a
+ * scenario that says nothing is framed exactly as it was before this existed. That is the
+ * whole design: the ceiling is not lowered globally, because doing so would silently
+ * re-frame every recording anyone has ever made, and the values here were measured against
+ * real pages rather than guessed.
+ *
+ * `maxZoom` is the one that matters. At the 1.6x default the tightest window is 1216x684 —
+ * 37% of the frame discarded — which is fine for a compact form and is why one recorded demo
+ * lost the whole left third of a results page. A busy layout wants 1.3x or so; text-heavy
+ * pages that need the magnification can keep 1.6.
+ *
+ * `margin` is the breathing room kept around the target when choosing that zoom, as a
+ * fraction of the target on each side. Raising it is the gentler way to keep context in
+ * frame: it lowers the zoom the target asks for, rather than capping the zoom it gets.
+ *
+ * `minDwellMs` is the one thing here that changes the recording rather than the framing —
+ * see `runtime.ts`, where it is applied.
+ */
+export declare const ScenarioCameraSchema: z.ZodObject<{
+    maxZoom: z.ZodOptional<z.ZodNumber>;
+    margin: z.ZodOptional<z.ZodNumber>;
+    easeMs: z.ZodOptional<z.ZodNumber>;
+    minDwellMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type ScenarioCamera = z.infer<typeof ScenarioCameraSchema>;
+export declare const ScenarioMetaSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"agent-demo.scenario/v1">;
+    id: z.ZodString;
+    title: z.ZodString;
+    language: z.ZodDefault<z.ZodString>;
+    viewport: z.ZodObject<{
+        width: z.ZodLiteral<1920>;
+        height: z.ZodLiteral<1080>;
+        deviceScaleFactor: z.ZodLiteral<1>;
+    }, z.core.$strip>;
+    locale: z.ZodLiteral<"en-US">;
+    timezoneId: z.ZodLiteral<"UTC">;
+    colorScheme: z.ZodLiteral<"light">;
+    reducedMotion: z.ZodLiteral<"reduce">;
+    allowedConsoleErrors: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    handoff: z.ZodDefault<z.ZodEnum<{
+        none: "none";
+        preflight: "preflight";
+        session: "session";
+    }>>;
+    handoffTimeoutMs: z.ZodDefault<z.ZodNumber>;
+    intro: z.ZodOptional<z.ZodObject<{
+        lines: z.ZodArray<z.ZodString>;
+        narration: z.ZodOptional<z.ZodString>;
+        durationMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    camera: z.ZodOptional<z.ZodObject<{
+        maxZoom: z.ZodOptional<z.ZodNumber>;
+        margin: z.ZodOptional<z.ZodNumber>;
+        easeMs: z.ZodOptional<z.ZodNumber>;
+        minDwellMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** Which phase, if any, hands the browser over. Read by the recorder and the surfaces. */
+export type HandoffMode = z.infer<typeof ScenarioMetaSchema>['handoff'];
+export type ScenarioMeta = z.infer<typeof ScenarioMetaSchema>;

package/dist/schema/stable-json.d.ts

@@ -0,0 +1,4 @@
+/** Deterministic JSON: sorted keys, 2-space indent, LF, exactly one trailing newline. */
+export declare function stableStringify(value: unknown): string;
+/** Single-line deterministic JSON for NDJSON records. */
+export declare function stableJsonLine(value: unknown): string;

package/dist/schema/zod-format.d.ts

@@ -0,0 +1,8 @@
+import { ZodError } from 'zod';
+/** So a caller outside this package's Zod boundary never needs its own `zod` dependency. */
+export declare function isZodError(error: unknown): error is ZodError;
+/**
+ * One line per issue, `path: message`, instead of `ZodError.message`'s raw JSON array —
+ * the same array `validate` and `demo_validate` were both printing verbatim as a "problem".
+ */
+export declare function formatZodError(error: ZodError): string;

package/dist/types.d.ts

@@ -0,0 +1,194 @@
+import type { ScenarioMeta } from './schema/index.js';
+import type { Locator, Page } from 'playwright-core';
+/**
+ * What kind of interaction `run()` performs, declared rather than observed. Like
+ * `target`, this is metadata the recorder records and never performs — it tells the
+ * cursor track what to draw at the target (`click` a ripple, `type`/`point` a settle).
+ * Absent means `point`: the cursor still moves to the target, nothing pulses.
+ */
+export type DemoAction = 'click' | 'type' | 'point';
+export type DemoStep = {
+    id: string;
+    title: string;
+    subtitle?: string;
+    /** Locator whose bounding box is recorded on step.start. Never used to perform the action. */
+    target?: Locator;
+    /** Declared interaction kind, recorded on step.start and consumed by the cursor track. */
+    action?: DemoAction;
+    /** Extra presentation hold after the action completes, in whole milliseconds. */
+    holdMs?: number;
+    run: () => Promise<unknown>;
+};
+export type DemoAssertion = {
+    id: string;
+    title: string;
+    run: () => Promise<unknown>;
+};
+/**
+ * A CSS selector string, not a Locator, so a mask can be registered
+ * before the element it hides exists.
+ */
+export type DemoMask = {
+    id: string;
+    selector: string;
+    reason?: string;
+};
+/**
+ * A bounded wait for something PlainTake is not driving — a person approving a push
+ * notification on their phone, clicking a link in an email, or a background job finishing.
+ * Prompts nobody and needs no visible window, so unlike a handoff it works headless and in
+ * CI.
+ *
+ * It exists rather than leaving authors to `await page.waitForSelector(...)` for the three
+ * reasons `demo.pause` exists rather than `page.waitForTimeout`: it races the run's abort
+ * signal, so Ctrl-C during a five-minute wait does not hang until the wait expires; it puts
+ * the wait on the timeline, so a still stretch of video has a recorded explanation; and it
+ * gives timeouts one error kind instead of whatever Playwright happened to throw.
+ */
+export type DemoWaitFor = {
+    id: string;
+    /** Recorded as the event title, and shown to a person in later phases. Never a secret. */
+    title: string;
+    /**
+     * Resolves when the wait is over. Invoked once; a rejection fails the run.
+     *
+     * Pass `{ timeout: 0 }` to whatever Playwright call is inside, so `timeoutMs` below is the
+     * only deadline. Otherwise Playwright's own 30s default fires first and reports the
+     * author's locator as the culprit rather than the wait.
+     */
+    until: () => Promise<unknown>;
+    /** Defaults to 120s, capped at 300s. Out-of-range values are a usage error. */
+    timeoutMs?: number;
+};
+/**
+ * Hands the real browser window to a person, and waits for them.
+ *
+ * The counterpart to `waitFor`: that one blocks on a condition and prompts nobody, this one
+ * prompts somebody and blocks on them. The person acts *in the browser* — types the one-time
+ * code, solves the CAPTCHA, completes the SSO round trip — so no secret ever passes through
+ * PlainTake. See `HumanReply`: the only thing that comes back is which of three things
+ * happened.
+ *
+ * Requires `handoff` in the scenario's metadata, and the phase must match. That is checked
+ * before Chromium starts, so a scenario that could never work says so immediately.
+ */
+export type PreflightHandoff = {
+    id: string;
+    /** Shown to the person and recorded as the event title. Never a secret. */
+    title: string;
+    /** Extra lines at the prompt: what to do, and how to know it worked. */
+    detail?: string;
+    /**
+     * Optional. When present, the handoff can end on its own the moment the condition holds,
+     * without the person confirming — the same `{ timeout: 0 }` rule as `DemoWaitFor.until`
+     * applies. Without it, the only way out is the person, the deadline, or a cancellation.
+     */
+    until?: () => Promise<unknown>;
+    /** Defaults to the scenario's `handoffTimeoutMs`, itself 120s and capped at 300s. */
+    timeoutMs?: number;
+};
+/**
+ * A handoff that happens on camera. Everything a pre-flight one has, plus the single
+ * thing that only means anything once the recording is running.
+ */
+export type DemoHandoff = PreflightHandoff & {
+    /**
+     * CSS selector, registered before the window is handed over and left registered afterwards,
+     * exactly as `demo.mask` does — so a field the *person* fills during the handoff is
+     * unreadable from the moment it exists, on this document and on every one after it.
+     *
+     * It hides what it names and nothing else. Anything already on screen when the handoff
+     * begins was already in the frames before it, so mask that with `demo.mask` earlier
+     * instead; and a confirmation toast, a URL bar or a desktop notification is beyond reach
+     * of any selector. A person cannot proofread what they cannot see.
+     *
+     * Session-only, and a usage error in pre-flight: nothing is being recorded there, so a mask
+     * would hide nothing while silently applying to the whole video that follows.
+     */
+    mask?: string;
+};
+/**
+ * What a scenario may do before recording starts.
+ *
+ * Deliberately narrower than `DemoContext`. `chapter`, `step`, `assert` and `mask` all exist
+ * to put something on a video timeline, and during pre-flight there is no video timeline
+ * yet. Offering them here and silently dropping their output is exactly the "quietly does
+ * nothing" failure the rest of the DSL is built to avoid, so they are absent instead.
+ *
+ * Both members are here rather than only on `DemoContext` because pre-flight is the *better*
+ * place for a handoff: a sign-in done here reaches neither the video nor the trace.
+ *
+ * `handoff` takes the narrower `PreflightHandoff` for the same reason the four missing
+ * methods are missing: `mask` exists to keep something out of the pixels, and there are no
+ * pixels yet. Passing one here is a compile error on the spot rather than a mask that
+ * quietly does nothing — and the runtime refuses it too, for the object that was not a
+ * literal.
+ */
+export interface PreflightContext {
+    waitFor(condition: DemoWaitFor): Promise<void>;
+    handoff(request: PreflightHandoff): Promise<void>;
+}
+export interface DemoContext extends PreflightContext {
+    /** Widened by exactly one optional property, `mask`. See `DemoHandoff`. */
+    handoff(request: DemoHandoff): Promise<void>;
+    chapter(title: string): Promise<void>;
+    step(step: DemoStep): Promise<void>;
+    assert(assertion: DemoAssertion): Promise<void>;
+    mask(mask: DemoMask): Promise<void>;
+    pause(ms: number): Promise<void>;
+}
+export type DemoRunArgs = {
+    page: Page;
+    demo: DemoContext;
+    baseURL: string;
+};
+/** Same property names as `DemoRunArgs`, so moving code between phases changes nothing else. */
+export type PreflightArgs = {
+    page: Page;
+    demo: PreflightContext;
+    baseURL: string;
+};
+/**
+ * Runs before `tracing.start()` as well as before `screencast.start()`, so nothing it
+ * does reaches either the trace or the video, and hands the page back on `about:blank`.
+ */
+type PreflightHook = {
+    preflight?(args: PreflightArgs): Promise<void>;
+};
+/**
+ * Runs after pre-flight's `about:blank` hand-back and before `runtime.beginSession()`,
+ * `tracing.start()` and `screencast.start()`.
+ *
+ * It exists because the hand-back is load-bearing and must stay: whatever pre-flight ended
+ * on is not frame 0 of the video, and the timeline origin is measured under the same starting
+ * condition a no-preflight run starts under. But that same hand-back is why a scenario
+ * cannot start its video on a loaded page by navigating in pre-flight — the reset throws
+ * the navigation away, and the alternative, a `page.goto` as the first step's action, films
+ * the load: a client-rendered app whose first paint is blank puts seconds of white between
+ * the opening card and the first screen. This phase is the way out. What it navigates to and
+ * waits for is the author's to declare, because only the scenario knows which page the video
+ * opens on and what "ready" means on it; that it runs off-camera is the recorder's to
+ * guarantee, and is the same guarantee pre-flight already rests on.
+ *
+ * Takes `PreflightArgs` rather than a context of its own: it is still pre-session, so
+ * `chapter`, `step`, `assert`, `mask` and `pause` would have no timeline to write to and are
+ * absent for the same reason they are absent from pre-flight. A `waitFor` or a `handoff`
+ * called here records under the pre-flight phase, which is the honest phase for anything
+ * that happens before the session begins.
+ */
+type WarmupHook = {
+    warmup?(args: PreflightArgs): Promise<void>;
+};
+export type DemoDefinition = ScenarioMeta & {
+    run(args: DemoRunArgs): Promise<void>;
+} & PreflightHook & WarmupHook;
+/**
+ * The metadata fields `ScenarioMetaSchema` supplies a `.default()` for, and which an author
+ * may therefore leave out. Named rather than spelled inline twice, so adding a defaulted
+ * field is one edit here instead of two that can drift apart.
+ */
+type Defaulted = 'language' | 'allowedConsoleErrors' | 'handoff' | 'handoffTimeoutMs';
+export type DemoDefinitionInput = Omit<ScenarioMeta, Defaulted> & Partial<Pick<ScenarioMeta, Defaulted>> & {
+    run(args: DemoRunArgs): Promise<void>;
+} & PreflightHook & WarmupHook;
+export {};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@plaintake/scenario",
+  "version": "1.2.1",
+  "description": "Authoring SDK for PlainTake demo scenarios: defineDemo and the scenario DSL types. Install for editor autocomplete; the PlainTake binary ships a runtime fallback.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "playwright-core": "1.62.1",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@plaintake/schema": "0.0.0"
+  },
+  "scripts": {}
+}