@plaintake/scenario 1.24.0 → 1.30.0

package/dist/schema/render-plan.d.ts

@@ -4,6 +4,7 @@ export declare const CueSchema: z.ZodObject<{
     startMs: z.ZodNumber;
     endMs: z.ZodNumber;
     lines: z.ZodArray<z.ZodString>;
+    words: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
 }, z.core.$strip>;
 /**
  * The closing credit card. Absent means no card, which is a Pro-Tier-only outcome.
@@ -54,6 +55,41 @@ export declare const IntroSchema: z.ZodObject<{
     assPath: z.ZodLiteral<"captions/intro.ass">;
 }, z.core.$strip>;
 export type Intro = z.infer<typeof IntroSchema>;
+/**
+ * The hook: one or two lines of author text drawn in the top band of a portrait video for its
+ * first seconds — the scroll-stopper a short-form feed shows before anyone has decided to watch.
+ *
+ * **Not the intro, and not narration.** The intro is a full-frame card that takes its own time
+ * at the head of the video; the hook sits *over* the recording, in the band above the picture,
+ * and costs no time at all. It is never spoken and never a caption cue, so it stays out of the
+ * SRT, the VTT, the `mov_text` track and `cueCount`, exactly as the cards do.
+ *
+ * `lines` are frozen already wrapped — by the author's own line break, or balanced to the
+ * hook's measured width (`wrapHook`, `@plaintake/subtitles`) — because nothing downstream
+ * re-wraps text. Frozen on every plan whose scenario declares one, whatever the aspect: only a
+ * portrait frame has a band to draw it in, so a 16:9 plan carries it undrawn and a later
+ * `render --aspect 9:16` re-cut picks it up, the same way a re-cut carries every other field.
+ */
+export declare const HookSchema: z.ZodObject<{
+    lines: z.ZodArray<z.ZodString>;
+    durationMs: z.ZodNumber;
+    assPath: z.ZodLiteral<"captions/hook.ass">;
+    imagePath: z.ZodOptional<z.ZodLiteral<"captions/hook.png">>;
+}, z.core.$strip>;
+export type Hook = z.infer<typeof HookSchema>;
+/** The hook as the application layer supplies it; `assPath` is filled in by `buildRenderPlan`. */
+export type HookInput = Omit<Hook, 'assPath'>;
+/**
+ * Rounded corners on the box a letterbox lays the picture in, drawn by libass in the pad colour
+ * over the box's four corners. Present only on the two layouts that frame the picture as an
+ * object on a background — `social` and `inset` — and absent on every plain letterbox, whose
+ * picture runs edge to edge across the frame and has no corner a radius could round.
+ */
+export declare const FrameSchema: z.ZodObject<{
+    radius: z.ZodNumber;
+    assPath: z.ZodLiteral<"captions/frame.ass">;
+}, z.core.$strip>;
+export type Frame = z.infer<typeof FrameSchema>;
 /**
  * One MP4 chapter marker. `endMs` is stored rather than derived from the next mark, so
  * `render/chapters.ffmetadata` is a pure function of the plan and nothing is recomputed at
@@ -99,8 +135,9 @@ export type ChapterMark = z.infer<typeof ChapterMarkSchema>;
  *
  * `arriveMs` is when the cursor reaches the point — no later than the step's start, and
  * pulled earlier for clicks so the arrow is parked and visible before it ripples — and
- * `departMs` is when it may leave for the next point, pulled back from the step's finish
- * to leave the glide room. `rippleMs` is when a click's ripple *starts*: the step's own
+ * `departMs` is when it leaves for the next point: it parks until one distance-scaled glide
+ * (200–500ms) before the next arrival rather than leaving at the step's finish, so a gap of
+ * untargeted narration is spent waiting, not crawling. `rippleMs` is when a click's ripple *starts*: the step's own
  * start minus a measured 200ms lead, so the ripple is visibly under way before the
  * screen the click changes — the step start rather than the action end because whatever
  * `run()` awaits after the click is the change itself. Present only on `action: 'click'`
@@ -124,6 +161,7 @@ export declare const CursorPointSchema: z.ZodObject<{
     }>;
     rippleMs: z.ZodOptional<z.ZodNumber>;
     scale: z.ZodOptional<z.ZodNumber>;
+    cutMs: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export declare const CursorSchema: z.ZodObject<{
     assPath: z.ZodLiteral<"captions/cursor.ass">;
@@ -140,6 +178,7 @@ export declare const CursorSchema: z.ZodObject<{
         }>;
         rippleMs: z.ZodOptional<z.ZodNumber>;
         scale: z.ZodOptional<z.ZodNumber>;
+        cutMs: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type Cursor = z.infer<typeof CursorSchema>;
@@ -216,8 +255,34 @@ export declare const SegmentSchema: z.ZodObject<{
     actorId: z.ZodString;
     startMs: z.ZodNumber;
     endMs: z.ZodNumber;
+    sourceStartMs: z.ZodOptional<z.ZodNumber>;
+    sourceEndMs: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type Segment = z.infer<typeof SegmentSchema>;
+/**
+ * The length FFmpeg's `trim=start=S:end=E` actually keeps of a CFR stream, in ms: `trim`
+ * rescales both bounds onto the frame grid rounding to nearest (measured: `[0, 2743)` keeps 82
+ * frames, `[1400, 2640)` keeps 37), so it keeps `round(E·fps) − round(S·fps)` frames, expressed
+ * as `ceil(frames · 1000 / fps)` — exact integer arithmetic, no float `FRAME_MS`. The one place
+ * this lives, so a cut's freeze (`cutFreezeMs`) and the badge window it extends cannot disagree
+ * by the sub-frame residue of an off-grid span (Chromium's segment files end on a 40ms packet
+ * cadence, not on the 30 fps grid).
+ */
+export declare const trimmedSpanMs: (window: {
+    startMs: number;
+    endMs: number;
+}, fps?: number) => number;
+/**
+ * A segment's window into `raw/session.webm` that the splice trims: the measured
+ * `sourceStartMs`/`sourceEndMs` when the plan carries them (any plan with a cut, and any
+ * `terminal.browser` plan), else the capture-derived `startMs`/`endMs` — so every other plan is
+ * read exactly as it always was. The splice and the badge windows both read through this, so
+ * they cannot disagree about a segment's on-screen length.
+ */
+export declare const segmentSourceWindow: (segment: Pick<Segment, "startMs" | "endMs" | "sourceStartMs" | "sourceEndMs">) => {
+    startMs: number;
+    endMs: number;
+};
 /**
  * A full-frame card drawn between two actors' segments on a hand-off — structurally
  * `Intro`/`Outro`'s sibling, down to the same `HEX_COLOUR` injection guard on its colours,
@@ -236,8 +301,58 @@ export declare const TransitionCardSchema: z.ZodObject<{
     backgroundColor: z.ZodString;
     textColor: z.ZodString;
     assPath: z.ZodString;
+    freezeMs: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type TransitionCard = z.infer<typeof TransitionCardSchema>;
+/**
+ * A hard cut: the other occupant a joint where the actor changes can have. No card, no gap,
+ * no ASS file — the two capture segments either side of it simply abut in the output. It
+ * still takes its joint's one slot in `transitionCards` (so "one entry per joint" and the
+ * gap-count refine below hold unchanged), and it still names who hands off to whom (so the
+ * declared-actor refine holds unchanged too).
+ *
+ * `kind` exists on the cut alone, never on a card: a card frozen before cuts existed has no
+ * `kind` key, and adding one to it would change every existing plan's JSON. The card branch
+ * of `TransitionSchema` cannot swallow a cut — it requires `lines`, `durationMs`, both
+ * colours and `assPath`, none of which a cut carries — and a cut carrying stray card keys
+ * parses as a cut with those keys stripped (Zod's default for unknown keys).
+ */
+export declare const TransitionCutSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"cut">;
+    fromActorId: z.ZodString;
+    toActorId: z.ZodString;
+    freezeMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type TransitionCut = z.infer<typeof TransitionCutSchema>;
+/**
+ * One joint where the actor changes: a card or a cut. **Card first**, so every entry frozen
+ * before cuts existed parses through branch one exactly as it always did — same keys, same
+ * order — and serialises byte-identically.
+ */
+export declare const TransitionSchema: z.ZodUnion<readonly [z.ZodObject<{
+    fromActorId: z.ZodString;
+    toActorId: z.ZodString;
+    durationMs: z.ZodNumber;
+    lines: z.ZodArray<z.ZodString>;
+    backgroundColor: z.ZodString;
+    textColor: z.ZodString;
+    assPath: z.ZodString;
+    freezeMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"cut">;
+    fromActorId: z.ZodString;
+    toActorId: z.ZodString;
+    freezeMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>]>;
+export type Transition = z.infer<typeof TransitionSchema>;
+/** Whether a joint is a hard cut rather than a card. Accepts the input shape too (no `assPath`). */
+export declare const isTransitionCut: (transition: TransitionCard | TransitionCut | Omit<TransitionCard, "assPath">) => transition is TransitionCut;
+/**
+ * The screen time a hand-off joint claims: 0 for a cut, the card's own `durationMs` otherwise.
+ * The one place this arithmetic lives, so the derivation's offsets, the badge windows and the
+ * splice graph cannot disagree about it.
+ */
+export declare const transitionGapMs: (transition: TransitionCard | TransitionCut | Omit<TransitionCard, "assPath">) => number;
 /**
  * One frozen explain scene's real render file, occupying one of the gaps between `segments`.
  *
@@ -249,7 +364,8 @@ export type TransitionCard = z.infer<typeof TransitionCardSchema>;
  * `demo.turn()` boundary always changes who is filming (`runtime.ts` refuses a turn to the
  * actor already holding the browser), and a `demo.explain()` boundary never does (the same
  * actor's capture merely pauses for the cut-away) — so an "actor changed" gap is always a
- * card, and an "actor unchanged" gap is always an explain, and the renderer recovers the
+ * `transitionCards` entry (a card, or a zero-length cut — `TransitionCutSchema`), and an
+ * "actor unchanged" gap is always an explain, and the renderer recovers the
  * interleaving from that invariant rather than from a stored index. `segments` may also
  * carry no `actorId` at all — the no-cast, explain-only case — in which every gap is,
  * necessarily, an explain (there is no hand-off to draw a card for).
@@ -263,6 +379,7 @@ export declare const ExplainSegmentPlanSchema: z.ZodObject<{
     id: z.ZodString;
     segmentPath: z.ZodString;
     durationMs: z.ZodNumber;
+    freezeMs: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type ExplainSegmentPlan = z.infer<typeof ExplainSegmentPlanSchema>;
 /**
@@ -362,13 +479,14 @@ export type HighlightRect = z.infer<typeof HighlightRectSchema>;
  * `source` distinguishes a synthesised clip from an author-supplied WAV, because they are the
  * same bytes by the time they reach here and the distinction is not otherwise recoverable.
  *
- * `explain` is the third provenance: a cut-away scene's narration, synthesised by *plainmotion*
- * at record time rather than by this project's own narrator. It never requires the `engine`
- * block below, because that block describes one synthesiser — the recorder's kokoro worker —
- * and these clips were made by the other one; plainmotion's identity is recorded where the
- * rest of its contribution is, the manifest's toolchain block. The rule the refine below
- * actually states is "every clip must be accounted for": `synth` is accounted for by `engine`,
- * `file` by the author who supplied it, `explain` by the toolchain.
+ * `explain` is the third provenance: a cut-away scene's whole laid-out narration track, made
+ * by the explain compile (`@plaintake/motion`) rather than by this project's step narrator. It
+ * never requires the `engine` block below, because that block describes the run's one step
+ * synthesiser and voice; an explain scene may speak in another voice, and its identity is
+ * frozen in that scene's own `explain-plan.json` (or, for bundles recorded by 1.28.0 or earlier, in the
+ * manifest's `toolchain.plainmotion`). The rule the refine below actually states is "every clip
+ * must be accounted for": `synth` is accounted for by `engine`,
+ * `file` by the author who supplied it, `explain` by its scene's frozen plan.
  */
 export declare const SpeechClipSchema: z.ZodObject<{
     id: z.ZodString;
@@ -434,6 +552,10 @@ export declare const SpeechSchema: z.ZodObject<{
         modelSha256: z.ZodString;
         voice: z.ZodString;
     }, z.core.$strip>>;
+    loudness: z.ZodOptional<z.ZodObject<{
+        targetLufs: z.ZodNumber;
+        maxPeakDbfs: z.ZodNumber;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type Speech = z.infer<typeof SpeechSchema>;
 export type SpeechClip = z.infer<typeof SpeechClipSchema>;
@@ -470,9 +592,11 @@ export type IntroInput = Omit<Intro, 'assPath'>;
  * practice, which resolves a hand-off's concrete `durationMs` via `transitionCardDurationMs`
  * before this is ever built, exactly as `intro`/`outro` durations are resolved before
  * `buildRenderPlan` is called. `assPath` is filled in by `buildRenderPlan`, indexed by
- * position in the array against the schema's own `captions/turn-[0-9]+\.ass` family.
+ * position in the array against the schema's own `captions/turn-[0-9]+\.ass` family. A cut
+ * passes through as it is — it has no file — and keeps its slot, so a card's index is still its
+ * joint's position in the whole array and a cards-only plan's paths are unchanged.
  */
-export type TransitionCardInput = Omit<TransitionCard, 'assPath'>;
+export type TransitionCardInput = Omit<TransitionCard, 'assPath'> | TransitionCut;
 /**
  * The brand accent: one colour shared by the cursor's fill, its click-ripple ring and the
  * highlight label's text. One field rather than one per consumer, because the cursor and
@@ -604,6 +728,11 @@ export declare const RenderPlanSchema: z.ZodObject<{
             x: z.ZodNumber;
             y: z.ZodNumber;
             padColor: z.ZodString;
+            reframe: z.ZodOptional<z.ZodLiteral<"follow">>;
+            layout: z.ZodOptional<z.ZodEnum<{
+                social: "social";
+                inset: "inset";
+            }>>;
         }, z.core.$strip>>;
         durationMs: z.ZodNumber;
         tailPadMs: z.ZodNumber;
@@ -618,6 +747,7 @@ export declare const RenderPlanSchema: z.ZodObject<{
             startMs: z.ZodNumber;
             endMs: z.ZodNumber;
             lines: z.ZodArray<z.ZodString>;
+            words: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
         }, z.core.$strip>>;
     }, z.core.$strip>;
     style: z.ZodObject<{
@@ -634,6 +764,9 @@ export declare const RenderPlanSchema: z.ZodObject<{
         boxColor: z.ZodDefault<z.ZodString>;
         boxOpacity: z.ZodDefault<z.ZodNumber>;
         alignment: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<2>, z.ZodLiteral<8>]>>;
+        social: z.ZodOptional<z.ZodObject<{
+            highlightColor: z.ZodString;
+        }, z.core.$strip>>;
     }, z.core.$strip>;
     ffmpeg: z.ZodObject<{
         base: z.ZodArray<z.ZodString>;
@@ -654,6 +787,16 @@ export declare const RenderPlanSchema: z.ZodObject<{
         textColor: z.ZodString;
         assPath: z.ZodLiteral<"captions/outro.ass">;
     }, z.core.$strip>>;
+    hook: z.ZodOptional<z.ZodObject<{
+        lines: z.ZodArray<z.ZodString>;
+        durationMs: z.ZodNumber;
+        assPath: z.ZodLiteral<"captions/hook.ass">;
+        imagePath: z.ZodOptional<z.ZodLiteral<"captions/hook.png">>;
+    }, z.core.$strip>>;
+    frame: z.ZodOptional<z.ZodObject<{
+        radius: z.ZodNumber;
+        assPath: z.ZodLiteral<"captions/frame.ass">;
+    }, z.core.$strip>>;
     chapters: z.ZodOptional<z.ZodObject<{
         metadataPath: z.ZodLiteral<"render/chapters.ffmetadata">;
         marks: z.ZodArray<z.ZodObject<{
@@ -677,6 +820,7 @@ export declare const RenderPlanSchema: z.ZodObject<{
             }>;
             rippleMs: z.ZodOptional<z.ZodNumber>;
             scale: z.ZodOptional<z.ZodNumber>;
+            cutMs: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
     camera: z.ZodOptional<z.ZodObject<{
@@ -733,6 +877,10 @@ export declare const RenderPlanSchema: z.ZodObject<{
             modelSha256: z.ZodString;
             voice: z.ZodString;
         }, z.core.$strip>>;
+        loudness: z.ZodOptional<z.ZodObject<{
+            targetLufs: z.ZodNumber;
+            maxPeakDbfs: z.ZodNumber;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
     theme: z.ZodOptional<z.ZodObject<{
         accentColor: z.ZodString;
@@ -747,8 +895,10 @@ export declare const RenderPlanSchema: z.ZodObject<{
         actorId: z.ZodString;
         startMs: z.ZodNumber;
         endMs: z.ZodNumber;
+        sourceStartMs: z.ZodOptional<z.ZodNumber>;
+        sourceEndMs: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>>;
-    transitionCards: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    transitionCards: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
         fromActorId: z.ZodString;
         toActorId: z.ZodString;
         durationMs: z.ZodNumber;
@@ -756,12 +906,19 @@ export declare const RenderPlanSchema: z.ZodObject<{
         backgroundColor: z.ZodString;
         textColor: z.ZodString;
         assPath: z.ZodString;
-    }, z.core.$strip>>>;
+        freezeMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"cut">;
+        fromActorId: z.ZodString;
+        toActorId: z.ZodString;
+        freezeMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>]>>>;
     badgesAssPath: z.ZodOptional<z.ZodLiteral<"captions/badges.ass">>;
     explainSegments: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         segmentPath: z.ZodString;
         durationMs: z.ZodNumber;
+        freezeMs: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type RenderPlan = z.infer<typeof RenderPlanSchema>;

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">;
@@ -523,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;
@@ -595,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">;
@@ -604,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;
@@ -613,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>;
@@ -630,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. */