@plaintake/scenario 1.23.0 → 1.30.0

package/dist/schema/results.d.ts

@@ -15,6 +15,13 @@ export declare const ValidationResultSchema: z.ZodObject<{
             session: "session";
         }>>;
         sha256: z.ZodString;
+        terminal: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+            cols: z.ZodNumber;
+            rows: z.ZodNumber;
+            shell: z.ZodString;
+            command: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            browser: z.ZodOptional<z.ZodLiteral<true>>;
+        }, z.core.$strip>>>;
     }, z.core.$strip>>;
     schema: z.ZodLiteral<"agent-demo.result/v1">;
     kind: z.ZodLiteral<"validate">;
@@ -48,6 +55,34 @@ export declare const RunCommandResultSchema: z.ZodObject<{
         bytes: z.ZodNumber;
     }, z.core.$strip>>;
     archivedPath: z.ZodOptional<z.ZodString>;
+    baseline: z.ZodOptional<z.ZodObject<{
+        path: z.ZodString;
+        status: z.ZodEnum<{
+            match: "match";
+            drift: "drift";
+            "scenario-changed": "scenario-changed";
+            absent: "absent";
+            skipped: "skipped";
+            updated: "updated";
+        }>;
+        differences: z.ZodArray<z.ZodObject<{
+            category: z.ZodEnum<{
+                step: "step";
+                assertion: "assertion";
+                "target-name": "target-name";
+                "target-role": "target-role";
+                "target-bounds": "target-bounds";
+                timing: "timing";
+                caption: "caption";
+                actor: "actor";
+            }>;
+            severity: z.ZodEnum<{
+                fail: "fail";
+                report: "report";
+            }>;
+            detail: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
     schema: z.ZodLiteral<"agent-demo.result/v1">;
     kind: z.ZodLiteral<"run">;
     ok: z.ZodBoolean;
@@ -72,6 +107,34 @@ export declare const CheckCommandResultSchema: z.ZodObject<{
         cueId: z.ZodString;
         detail: z.ZodString;
     }, z.core.$strip>>;
+    baseline: z.ZodOptional<z.ZodObject<{
+        path: z.ZodString;
+        status: z.ZodEnum<{
+            match: "match";
+            drift: "drift";
+            "scenario-changed": "scenario-changed";
+            absent: "absent";
+            skipped: "skipped";
+            updated: "updated";
+        }>;
+        differences: z.ZodArray<z.ZodObject<{
+            category: z.ZodEnum<{
+                step: "step";
+                assertion: "assertion";
+                "target-name": "target-name";
+                "target-role": "target-role";
+                "target-bounds": "target-bounds";
+                timing: "timing";
+                caption: "caption";
+                actor: "actor";
+            }>;
+            severity: z.ZodEnum<{
+                fail: "fail";
+                report: "report";
+            }>;
+            detail: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
     schema: z.ZodLiteral<"agent-demo.result/v1">;
     kind: z.ZodLiteral<"check">;
     ok: z.ZodBoolean;
@@ -244,12 +307,18 @@ export declare const DiffCommandResultSchema: z.ZodObject<{
     identical: z.ZodBoolean;
     differences: z.ZodArray<z.ZodObject<{
         category: z.ZodEnum<{
-            assertion: "assertion";
-            target: "target";
-            actor: "actor";
             step: "step";
+            assertion: "assertion";
+            "target-name": "target-name";
+            "target-role": "target-role";
+            "target-bounds": "target-bounds";
             timing: "timing";
             caption: "caption";
+            actor: "actor";
+        }>;
+        severity: z.ZodEnum<{
+            fail: "fail";
+            report: "report";
         }>;
         detail: z.ZodString;
     }, z.core.$strip>>;
@@ -461,11 +530,10 @@ export declare const DoctorResultSchema: z.ZodObject<{
         voices: z.ZodArray<z.ZodString>;
         notes: z.ZodArray<z.ZodString>;
     }, z.core.$strip>;
-    plainmotion: z.ZodObject<{
-        installed: z.ZodBoolean;
-        version: z.ZodOptional<z.ZodString>;
-        note: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>;
+    terminal: z.ZodOptional<z.ZodObject<{
+        ready: z.ZodBoolean;
+        notes: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
     schema: z.ZodLiteral<"agent-demo.result/v1">;
     kind: z.ZodLiteral<"doctor">;
     ok: z.ZodBoolean;
@@ -533,6 +601,7 @@ export declare const PublishResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         "hash-mismatch": "hash-mismatch";
         "length-mismatch": "length-mismatch";
         conflict: "conflict";
+        "taken-down": "taken-down";
     }>;
     schema: z.ZodLiteral<"agent-demo.result/v1">;
     kind: z.ZodLiteral<"publish">;
@@ -542,6 +611,7 @@ export declare const PublishResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     videoId: z.ZodString;
     url: z.ZodString;
     uploaded: z.ZodBoolean;
+    restored: z.ZodDefault<z.ZodBoolean>;
     remembered: z.ZodOptional<z.ZodBoolean>;
     expiresAt: z.ZodOptional<z.ZodString>;
     captions: z.ZodBoolean;
@@ -551,6 +621,44 @@ export declare const PublishResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"publish">;
     problems: z.ZodArray<z.ZodString>;
 }, z.core.$strip>], "ok">;
+/**
+ * A share taken down, or not. The service tombstones: the link answers 410 at once and
+ * the bytes stay until `purgeAfter`, so publishing the same bundle again before then
+ * restores it. Discriminated on `ok` for the same reason as `PublishResultSchema`.
+ */
+export declare const UnpublishResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    ok: z.ZodLiteral<false>;
+    reason: z.ZodEnum<{
+        "not-found": "not-found";
+        "unexpected-response": "unexpected-response";
+        "no-endpoint": "no-endpoint";
+        "no-key": "no-key";
+        "invalid-store": "invalid-store";
+        "not-a-bundle": "not-a-bundle";
+        unauthorized: "unauthorized";
+        unreachable: "unreachable";
+        "invalid-target": "invalid-target";
+        "endpoint-mismatch": "endpoint-mismatch";
+        forbidden: "forbidden";
+    }>;
+    schema: z.ZodLiteral<"agent-demo.result/v1">;
+    kind: z.ZodLiteral<"unpublish">;
+    problems: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    videoId: z.ZodString;
+    url: z.ZodString;
+    deletedAt: z.ZodString;
+    deletedBy: z.ZodEnum<{
+        producer: "producer";
+        admin: "admin";
+        expired: "expired";
+    }>;
+    purgeAfter: z.ZodString;
+    schema: z.ZodLiteral<"agent-demo.result/v1">;
+    kind: z.ZodLiteral<"unpublish">;
+    problems: z.ZodArray<z.ZodString>;
+}, z.core.$strip>], "ok">;
 export type ArtifactRef = z.infer<typeof ArtifactRefSchema>;
 export type ValidationResult = z.infer<typeof ValidationResultSchema>;
 export type RunCommandResult = z.infer<typeof RunCommandResultSchema>;
@@ -568,7 +676,8 @@ export type DoctorResult = z.infer<typeof DoctorResultSchema>;
 export type ActivateResult = z.infer<typeof ActivateResultSchema>;
 export type LicenceResult = z.infer<typeof LicenceResultSchema>;
 export type PublishResult = z.infer<typeof PublishResultSchema>;
-export type DemoResult = ValidationResult | RunCommandResult | CheckCommandResult | RenderCommandResult | VerificationReport | WarmCommandResult | DiffCommandResult | CompareCommandResult | InitResult | PruneCommandResult | ImportCommandResult | InspectResult | DoctorResult | ActivateResult | LicenceResult | PublishResult;
+export type UnpublishResult = z.infer<typeof UnpublishResultSchema>;
+export type DemoResult = ValidationResult | RunCommandResult | CheckCommandResult | RenderCommandResult | VerificationReport | WarmCommandResult | DiffCommandResult | CompareCommandResult | InitResult | PruneCommandResult | ImportCommandResult | InspectResult | DoctorResult | ActivateResult | LicenceResult | PublishResult | UnpublishResult;
 /**
  * Renders a filesystem location for display in a result, relative to `root` when it
  * lies inside it.

package/dist/schema/scenario.d.ts

@@ -23,6 +23,22 @@ export declare const ScenarioIntroSchema: z.ZodObject<{
     durationMs: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type ScenarioIntro = z.infer<typeof ScenarioIntroSchema>;
+/**
+ * The hook: a line or two of text over the top band of a portrait video for its first seconds
+ * (`HookSchema` in the render plan says what it is and is not). A string, or `{ text,
+ * durationMs }` to hold it for other than the default 3 s.
+ *
+ * `text` is author-chosen and never generated. A `\n` in it is a line break the author chose;
+ * otherwise a long hook is balanced onto two lines at the hook's measured width. Whether every
+ * character can be drawn, and whether it fits on two lines, depends on the bundled fonts, which
+ * this package cannot see — `validate` checks both (`hookProblems`, `apps/cli`), before a browser
+ * opens, and `run` refuses with exit 2 on the same grounds.
+ */
+export declare const ScenarioHookSchema: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    text: z.ZodString;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>]>;
+export type ScenarioHook = z.infer<typeof ScenarioHookSchema>;
 /**
  * Per-scenario camera framing, for the demos whose pages the defaults do not suit.
  *
@@ -78,6 +94,28 @@ export declare const ScenarioSpeechSchema: z.ZodObject<{
     voices: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 export type ScenarioSpeech = z.infer<typeof ScenarioSpeechSchema>;
+export declare const TerminalMetaSchema: z.ZodObject<{
+    shell: z.ZodDefault<z.ZodEnum<{
+        bash: "bash";
+        zsh: "zsh";
+        sh: "sh";
+    }>>;
+    command: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    cols: z.ZodDefault<z.ZodNumber>;
+    rows: z.ZodDefault<z.ZodNumber>;
+    cwd: z.ZodOptional<z.ZodString>;
+    env: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    secrets: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    browser: z.ZodOptional<z.ZodBoolean>;
+    label: z.ZodOptional<z.ZodString>;
+    transition: z.ZodOptional<z.ZodEnum<{
+        cut: "cut";
+        card: "card";
+    }>>;
+}, z.core.$strip>;
+export type TerminalMeta = z.infer<typeof TerminalMetaSchema>;
+/** What an author writes: every defaulted field (`shell`, `cols`, `rows`, `env`, `secrets`) optional. */
+export type TerminalMetaInput = z.input<typeof TerminalMetaSchema>;
 export declare const ScenarioMetaSchema: z.ZodObject<{
     schema: z.ZodLiteral<"agent-demo.scenario/v1">;
     id: z.ZodString;
@@ -88,6 +126,7 @@ export declare const ScenarioMetaSchema: z.ZodObject<{
         height: z.ZodLiteral<1080>;
         deviceScaleFactor: z.ZodLiteral<1>;
     }, z.core.$strip>;
+    uiScale: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<1.5>, z.ZodLiteral<2>]>>;
     locale: z.ZodLiteral<"en-US">;
     timezoneId: z.ZodLiteral<"UTC">;
     colorScheme: z.ZodLiteral<"light">;
@@ -104,6 +143,10 @@ export declare const ScenarioMetaSchema: z.ZodObject<{
         narration: z.ZodOptional<z.ZodString>;
         durationMs: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
+    hook: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        text: 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>;
@@ -114,6 +157,25 @@ export declare const ScenarioMetaSchema: z.ZodObject<{
         speed: z.ZodOptional<z.ZodNumber>;
         voices: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>;
+    terminal: z.ZodOptional<z.ZodObject<{
+        shell: z.ZodDefault<z.ZodEnum<{
+            bash: "bash";
+            zsh: "zsh";
+            sh: "sh";
+        }>>;
+        command: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        cols: z.ZodDefault<z.ZodNumber>;
+        rows: z.ZodDefault<z.ZodNumber>;
+        cwd: z.ZodOptional<z.ZodString>;
+        env: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        secrets: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        browser: z.ZodOptional<z.ZodBoolean>;
+        label: z.ZodOptional<z.ZodString>;
+        transition: z.ZodOptional<z.ZodEnum<{
+            cut: "cut";
+            card: "card";
+        }>>;
+    }, z.core.$strip>>;
     pronunciations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, z.core.$strip>;
 /** Which phase, if any, hands the browser over. Read by the recorder and the surfaces. */

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { ScenarioMeta } from './schema/index.js';
+import type { ScenarioMeta, TerminalMetaInput } from './schema/index.js';
 import type { BrowserContextOptions, Locator, Page } from 'playwright-core';
 /**
  * What kind of interaction `run()` performs, declared rather than observed. Like
@@ -217,10 +217,10 @@ export type ExplainConnection = {
     to: string;
     label?: string;
 };
-/** One side of a `comparison` explain scene: what this alternative is called, and its points. */
+/** One side of a `comparison` explain scene: what this alternative is called, and two to six short items. */
 export type ExplainColumn = {
     heading: string;
-    points: string[];
+    items: string[];
 };
 /** A named group of imported svg parts a `diagram` scene's cue can target as one thing. */
 export type ExplainRegion = {
@@ -228,16 +228,16 @@ export type ExplainRegion = {
     of: string[];
 };
 /**
- * The five motion-graphics scenes an explain cut-away can be, mirroring PlainMotion's scene
- * registry prop-for-prop (`title`/`process`/`comparison`/`diagram`/`recap`). PlainTake does
- * not draw these — it compiles each one through the `plainmotion` CLI and splices the frozen
- * result into the recording — so this union is a structural mirror of PlainMotion's own
- * schemas, and the deep validation (character caps, list bounds, phrase resolution) belongs
- * to PlainMotion at run time, not to this package's types. What `validate` checks without a
+ * The five motion-graphics scenes an explain cut-away can be, mirroring the scene registry in
+ * `@plaintake/motion` prop-for-prop (`title`/`process`/`comparison`/`diagram`/`recap`). This
+ * package is types only — each scene is compiled and drawn after capture and spliced into the
+ * recording as a frozen segment — so this union is a structural mirror of those scene schemas,
+ * and the deep validation (character caps, list bounds, phrase resolution) belongs to the
+ * compile at run time, not to this package's types. What `validate` checks without a
  * browser is the shape around the scene: id, narration, a known `type`.
  *
  * Geometry is deliberately absent. Where a pixel appears is the scene layout's decision,
- * exactly as it is in a `plainmotion.yaml`; an author says what exists and what the
+ * exactly as it is in any motion-graphics scene; an author says what exists and what the
  * narration points at, and nothing about inches.
  */
 export type ExplainScene = {
@@ -273,7 +273,7 @@ export type ExplainScene = {
     items: string[];
 };
 /**
- * What a cue does to the viewer's attention. The same vocabulary PlainMotion defines —
+ * What a cue does to the viewer's attention. The same vocabulary the explain compile defines —
  * deliberately small, and deliberately not easing curves or tween internals: an author says
  * what should happen; how that is expressed is the renderer's job.
  */
@@ -281,7 +281,7 @@ export type ExplainCueAction = 'reveal' | 'hide' | 'emphasize' | 'deemphasize' |
 /**
  * When a cue fires: bound to words in the narration, resolved against the timings the speech
  * model measures. Rewriting a sentence moves the animation with it instead of silently
- * desynchronising — which is why there is no numeric `at` offset here the way PlainMotion's
+ * desynchronising — which is why there is no numeric `at` offset here the way the compile's
  * own cue schema allows one. An explain scene always speaks (its narration is the scene's
  * clock), so a phrase is the only anchor that survives a rewording, and an offset that could
  * not is not offered.
@@ -296,22 +296,23 @@ export type ExplainCue = {
 };
 /**
  * A full-frame motion-graphics cut-away in the middle of a browser demo — "explain while
- * demoing". `demo.explain()` stops the screencast, splices in a PlainMotion-rendered scene
+ * demoing". `demo.explain()` stops the screencast, splices in a rendered motion-graphics scene
  * (`title`/`process`/`comparison`/`diagram`/`recap`), and resumes the recording on the same
  * page: the cut-away is a boundary on the timeline, the same mechanism a multi-actor `turn`
  * uses, so nothing about the recording's determinism or re-renderability changes. The scene
  * is compiled and rendered after capture finishes, from a generated one-scene project — the
  * only inputs that matter are the ones right here.
  *
- * Free on every tier, like every authoring verb. Requires the `plainmotion` CLI on `PATH`
- * at record time (`plaintake doctor` reports whether it is there); a bundle that carries an
- * explain segment re-renders without it, the same way it re-renders without a browser.
+ * Free on every tier, like every authoring verb. Always narrated — the narration is the
+ * scene's clock — so it needs the voice model installed at record time even when speech is
+ * off (`plaintake doctor` reports whether it is there); a bundle that carries an explain
+ * segment re-renders without it, the same way it re-renders without a browser.
  */
 export type DemoExplain = {
     /**
      * Stable, authored — the same rule every other id here follows. It becomes the directory
-     * the frozen artifacts live in (`explain/<id>/segment.mp4` and its plainmotion plan) and
-     * the generated scene's own id, so it must read as plainmotion ids do: lower-case
+     * the frozen artifacts live in (`explain/<id>/segment.mp4` and its frozen plan) and
+     * the generated scene's own id, so it must read as scene ids do: lower-case
      * alphanumeric and hyphens, starting alphanumeric. Checked at run time, with the offending
      * id named.
      */
@@ -320,7 +321,7 @@ export type DemoExplain = {
     title: string;
     /**
      * What the scene says. The source of truth for both the audio and the caption — there is
-     * no separate caption field, for the same reason PlainMotion has none: two strings that
+     * no separate caption field, for the same reason a motion-graphics scene has none: two strings that
      * are supposed to say the same thing will eventually disagree, and the one the viewer
      * hears is the one that matters. The measured speech is also the scene's duration: the
      * cut-away lasts exactly as long as it takes to say this, plus its lead-in and lead-out.
@@ -387,6 +388,53 @@ export type ActorStepMeta = {
      */
     paddingPx?: number;
 };
+/**
+ * `ActorStepMeta` for a `TermHandle` verb, plus the one thing a terminal step can mean that a
+ * browser step cannot: `expectExit: true` says the terminal process exiting during this step is
+ * the point of it (a `quit`, an `exit`), not a capture failure.
+ */
+export type TermStepMeta = ActorStepMeta & {
+    expectExit?: boolean;
+};
+/** A rectangle of terminal cells: zero-based `row`/`col` of its top-left cell, size in cells. */
+export type TermCells = {
+    row: number;
+    col: number;
+    width: number;
+    height: number;
+};
+/**
+ * The live terminal a scenario declaring `terminal` drives, handed to `run()` as `term`. Each
+ * verb records `step.start`/`step.finish` through the same bracket `Actor` verbs use, so
+ * captions, narration, cursor, camera, highlight and chapters work unchanged.
+ */
+export type TermHandle = {
+    /**
+     * The terminal as an actor, to turn back to it with `demo.turn(term.actor)`. Only with
+     * `terminal.browser: true`; reading it otherwise throws (exit 2).
+     */
+    readonly actor: Actor;
+    /** Types `line`, then Enter. Records a step whose target is the prompt line. */
+    run(line: string, meta?: TermStepMeta): Promise<void>;
+    /** Types at a fixed per-character delay — part of the timeline, never wall-clock driven. */
+    type(text: string, meta?: TermStepMeta): Promise<void>;
+    /** `'Enter'`, `'Ctrl+C'`, or a space-separated sequence such as `'Ctrl+B c'`. */
+    press(keys: string, meta?: TermStepMeta): Promise<void>;
+    /** Same bounds and timeout semantics as `demo.waitFor`. */
+    waitForText(pattern: RegExp | string, opts?: {
+        timeoutMs?: number;
+        id?: string;
+        title?: string;
+    }): Promise<void>;
+    /** A locator over the first match on the visible screen. */
+    getByText(pattern: RegExp | string): Locator;
+    /** A locator over a rectangle of cells, refused when it is outside the grid. */
+    cells(r: TermCells): Locator;
+    /** The visible screen, one line per row. */
+    screenText(): Promise<string>;
+    /** Reuses `DemoAssertion` verbatim, recorded against the default actor like `demo.assert`. */
+    assert(assertion: DemoAssertion): Promise<void>;
+};
 /**
  * A named participant in a multi-actor demo: its own Playwright `BrowserContext`, its own
  * page, and a handle of verbs that each perform a Playwright action *and* record the
@@ -539,20 +587,14 @@ export interface DemoContext extends PreflightContext {
      * `opts.card`, when given, plays a full-frame transition card between the two actors'
      * segments — the `lines` it names, an optional spoken `narration`, held for `durationMs`.
      *
-     * Omitting `opts.card` is allowed, but still draws a card: `RenderPlanSchema.transitionCards`
-     * requires exactly one entry per hand-off with non-empty `lines`, so a card-less turn's card
-     * is synthesised at render time as `Now: <label>`, naming the incoming actor by the `label`
-     * it was given to `demo.actor()`, held for the same default duration an explicit card with no
-     * `durationMs` of its own gets. The persistent corner badge names the active actor throughout
-     * either way; `opts.card` only ever changes whether that hand-off also gets a full-frame beat
-     * of its own, and what it says.
+     * `opts.card: false` is a hard cut: no card and no gap. With no `opts.card` the scenario
+     * default applies: a cut for a `terminal.browser` scenario unless `terminal.transition` is
+     * `'card'`; otherwise the card is synthesised at render time as `Now: <label>`, naming the
+     * incoming actor by the `label` it was given to `demo.actor()`, held for the default
+     * duration. The persistent corner badge names the active actor throughout either way.
      */
     turn(actor: Actor, opts?: {
-        card?: {
-            lines: string[];
-            narration?: string;
-            durationMs?: number;
-        };
+        card?: TurnCard | false;
     }): Promise<void>;
     /**
      * Cuts away from the browser recording to a full-frame motion-graphics scene — a diagram
@@ -561,10 +603,10 @@ export interface DemoContext extends PreflightContext {
      * a `turn` does minus the actor switch, so the cut-away occupies its own slot on the
      * timeline and nothing it covers is ever captured.
      *
-     * The scene is not drawn live: it is compiled and rendered by the `plainmotion` CLI after
-     * capture finishes, from the request's own fields, and spliced in at render time as a
-     * frozen 1920×1080@30 segment — which is what keeps the bundle re-renderable without
-     * `plainmotion`, without a browser, and byte-identically. Its narration is spoken by the
+     * The scene is not drawn live: it is compiled and rendered in process after capture
+     * finishes, from the request's own fields, and spliced in at render time as a frozen
+     * 1920×1080@30 segment — which is what keeps the bundle re-renderable without a voice
+     * model, without a browser, and byte-identically. Its narration is spoken by the
      * same engine as the rest of the recording (`--speech on`), lands in the same caption
      * track, and is the scene's clock: the cut-away lasts exactly as long as it takes to say.
      *
@@ -574,10 +616,25 @@ export interface DemoContext extends PreflightContext {
      */
     explain(request: DemoExplain): Promise<void>;
 }
+/** An explicit transition card for `demo.turn`. */
+export type TurnCard = {
+    lines: string[];
+    narration?: string;
+    durationMs?: number;
+};
+/**
+ * `term` is present only when the scenario declares `terminal`; a scenario without one is
+ * handed no `term` key at all.
+ *
+ * `page` is the terminal page in a terminal scenario. `baseURL` is the web target (`--base-url`
+ * or the fixture) when `terminal.browser` is set; without it, in a terminal scenario, it is the
+ * terminal page's URL.
+ */
 export type DemoRunArgs = {
     page: Page;
     demo: DemoContext;
     baseURL: string;
+    term?: TermHandle;
 };
 /** Same property names as `DemoRunArgs`, so moving code between phases changes nothing else. */
 export type PreflightArgs = {
@@ -625,7 +682,8 @@ export type DemoDefinition = ScenarioMeta & {
  * 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>> & {
+export type DemoDefinitionInput = Omit<ScenarioMeta, Defaulted | 'terminal'> & Partial<Pick<ScenarioMeta, Defaulted>> & {
+    terminal?: TerminalMetaInput;
     run(args: DemoRunArgs): Promise<void>;
 } & PreflightHook & WarmupHook;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plaintake/scenario",
-  "version": "1.23.0",
+  "version": "1.30.0",
   "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",