@plaintake/scenario 1.24.0 → 1.30.0

package/README.md

@@ -58,6 +58,16 @@ The PlainTake CLI discovers and records files matching `*.demo.ts`. See the
 assertions, masks, waits, and handoffs to a person for steps PlainTake cannot perform itself
 (entering a one-time code, for example).
 
+A scenario can also declare `terminal` to record a live command-line program (`run` is then
+handed a `term` with `run`, `type`, `press`, `waitForText` and friends), and with
+`terminal.browser: true` it can take turns between the terminal and a web app:
+`demo.turn(term.actor)` and `demo.turn(web)` switch with a hard cut by default, and
+`demo.turn(actor, { card })` or `{ card: false }` decides per turn. See the scenario guide.
+
+For TikTok and YouTube Shorts, a scenario can declare a `hook` — `'3 PDFs → 1, free'` or
+`{ text, durationMs }` — drawn above the picture for the video's first seconds when it is
+recorded with `--for tiktok` or `--for shorts`. One or two lines; emoji are drawn as outlines.
+
 ## Licence
 
 This package (`@plaintake/scenario`) is MIT licensed — see [LICENSE](./LICENSE).

package/dist/index.js

@@ -114,7 +114,7 @@ var DemoEventTypeSchema = z2.enum([
   "turn",
   /*
    * A full-frame motion-graphics cut-away: `demo.explain(...)` stops the screencast, splices
-   * in a PlainMotion-rendered scene at this point on the timeline, and resumes the recording
+   * in a rendered motion-graphics scene at this point on the timeline, and resumes the recording
    * on the same page, same actor. A member of its own for the same reason `turn` is one: a
    * cut-away is not a step — no target, no verb, no hold — and its `payload` carries the
    * whole authored request (id, narration, scene props, cues) because the scene is compiled
@@ -161,6 +161,13 @@ var ScenarioIntroSchema = z3.object({
   narration: z3.string().min(1).optional(),
   durationMs: z3.number().int().positive().max(15e3, "intro.durationMs must be at most 15000ms").optional()
 });
+var ScenarioHookSchema = z3.union([
+  z3.string().min(1),
+  z3.object({
+    text: z3.string().min(1),
+    durationMs: z3.number().int().min(1e3, "hook.durationMs must be at least 1000ms").max(1e4, "hook.durationMs must be at most 10000ms \u2014 past that it is a title, not a hook").optional()
+  })
+]);
 var ScenarioCameraSchema = z3.object({
   maxZoom: z3.number().min(1, "camera.maxZoom must be at least 1 (no zoom)").max(1.6, "camera.maxZoom must be at most 1.6 \u2014 beyond that the upscaled capture turns UI text to mush").optional(),
   margin: z3.number().min(0, "camera.margin must be at least 0").max(2, "camera.margin must be at most 2 (as a fraction of the target, per side)").optional(),
@@ -197,6 +204,30 @@ var ScenarioSpeechSchema = z3.object({
    */
   voices: z3.array(z3.string().min(1, "speech.voices entries must be non-empty voice names")).min(1, "speech.voices must name at least one voice \u2014 an empty list declares nothing, so omit it").optional()
 });
+var EnvName = z3.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/);
+var TerminalMetaSchema = z3.object({
+  shell: z3.enum(["bash", "zsh", "sh"]).default("bash"),
+  command: z3.array(z3.string().min(1)).min(1).optional(),
+  cols: z3.number().int().min(40).max(200).default(120),
+  rows: z3.number().int().min(12).max(60).default(34),
+  cwd: z3.string().min(1).optional(),
+  env: z3.array(EnvName).default([]),
+  secrets: z3.array(EnvName).default([]),
+  browser: z3.boolean().optional(),
+  label: z3.string().trim().min(1).optional(),
+  transition: z3.enum(["cut", "card"]).optional()
+}).superRefine((t, ctx) => {
+  for (const field of ["label", "transition"]) {
+    if (t[field] !== void 0 && t.browser !== true) {
+      ctx.addIssue({ code: "custom", path: [field], message: `terminal.${field} needs terminal.browser: true` });
+    }
+  }
+  for (const name of t.secrets) {
+    if (!t.env.includes(name)) {
+      ctx.addIssue({ code: "custom", path: ["secrets"], message: `secret ${name} must also be listed in terminal.env` });
+    }
+  }
+});
 var ScenarioMetaSchema = z3.object({
   schema: z3.literal("agent-demo.scenario/v1"),
   id: z3.string().regex(/^[a-z0-9][a-z0-9-]*$/, "must be a lowercase kebab-case id"),
@@ -207,6 +238,21 @@ var ScenarioMetaSchema = z3.object({
     height: z3.literal(1080),
     deviceScaleFactor: z3.literal(1)
   }),
+  /*
+   * How large the page is drawn inside the fixed 1920x1080 capture. At `s`, the page lays out
+   * at a 1920/s x 1080/s CSS viewport with deviceScaleFactor `s`, so Chromium paints every
+   * CSS pixel as s x s device pixels: the frame is still 1920x1080, the UI in it is s times
+   * larger and sharp, and the app's own responsive layout sees the narrower viewport. It is
+   * what a person gets from browser zoom, and what a vertical (`--aspect 9:16`) cut needs to
+   * stay legible once the whole frame is letterboxed to 1080 wide.
+   *
+   * `viewport` above still describes the capture, not the layout, which is why it stays a
+   * literal. Only 1.5 and 2 are offered besides 1: both divide 1920x1080 into whole CSS
+   * pixels, and both were measured (`ui-scale-dpr-spike.spec.ts`) to capture device-pixel
+   * frames headless and headed. Optional and inert when absent: every scenario written
+   * before this records exactly as it always did.
+   */
+  uiScale: z3.union([z3.literal(1), z3.literal(1.5), z3.literal(2)]).optional(),
   locale: z3.literal("en-US"),
   timezoneId: z3.literal("UTC"),
   colorScheme: z3.literal("light"),
@@ -253,6 +299,12 @@ var ScenarioMetaSchema = z3.object({
    * discarded in silence rather than refused.
    */
   intro: ScenarioIntroSchema.optional(),
+  /*
+   * The hook, drawn over the top band of a portrait render. Optional on the same precedent as
+   * `intro`; a scenario without one renders exactly what it always did, and a 16:9 render of one
+   * that has it carries it undrawn.
+   */
+  hook: ScenarioHookSchema.optional(),
   /*
    * Framing overrides for this scenario's pages. Optional like everything above it, and
    * inert when absent: the defaults are the constants the camera has always used.
@@ -268,6 +320,8 @@ var ScenarioMetaSchema = z3.object({
    * comment for the field's shape and the reasoning behind `speed`'s bounds.
    */
   speech: ScenarioSpeechSchema.optional(),
+  /* A live terminal as the recorded source instead of a web page; see `TerminalMetaSchema`. */
+  terminal: TerminalMetaSchema.optional(),
   /*
    * A text-substitution dictionary applied to narration immediately before synthesis — not the
    * vendored en-us phoneme dictionary `install-voice` fetches (a different thing entirely: that
@@ -307,10 +361,10 @@ var BundleManifestSchema = z5.object({
     fontSha256: Sha2562,
     containerImage: z5.string().optional(),
     /**
-     * The plainmotion CLI's own `--version` string, present exactly when a scenario called
-     * `demo.explain()` at least once — a run that never cut away never spawned it, and
-     * `containerImage`'s own optionality is the precedent for saying so with an absent field
-     * rather than a fabricated one.
+     * The plainmotion CLI's own `--version` string, present on bundles recorded by 1.28.0 or earlier
+     * whose scenario called `demo.explain()` — explain scenes were then rendered by that
+     * external CLI. Read-only now: explain scenes render in process, so nothing writes it, and
+     * it stays optional so those bundles keep verifying.
      */
     plainmotion: z5.string().optional()
   }),
@@ -320,8 +374,19 @@ var BundleManifestSchema = z5.object({
     architecture: z5.string(),
     locale: z5.literal("en-US"),
     timezone: z5.literal("UTC"),
+    /*
+     * The captured frame: 1920x1080 pixels at one pixel per video pixel, always. `uiScale`
+     * below says how the page was laid out into that frame; it never changes these two.
+     */
     viewport: z5.tuple([z5.literal(1920), z5.literal(1080)]),
-    deviceScaleFactor: z5.literal(1)
+    deviceScaleFactor: z5.literal(1),
+    /*
+     * The scenario's `uiScale`, written only when it is not 1 — so every manifest recorded
+     * before the option existed, and every one recorded without it, stays byte-identical.
+     * Recorded because it changes what every target rect in the bundle was measured against
+     * (CSS pixels times this), which a diff between two bundles must not mistake for drift.
+     */
+    uiScale: z5.union([z5.literal(1.5), z5.literal(2)]).optional()
   }),
   assertions: z5.array(z5.object({ id: z5.string().min(1), status: z5.enum(["passed", "failed"]) })),
   artifacts: z5.array(
@@ -376,8 +441,26 @@ var CueSchema = z7.object({
   id: z7.string().min(1),
   startMs: z7.number().int().nonnegative(),
   endMs: z7.number().int().positive(),
-  lines: z7.array(z7.string()).min(1).max(2)
-});
+  lines: z7.array(z7.string()).min(1).max(2),
+  /**
+   * When each word of `lines` is spoken, in video milliseconds — one entry per space-separated
+   * word of the lines joined, in order. Frozen only by a narrated recording under the social
+   * layout, whose captions light each word as the voice reaches it (`toAss`); absent everywhere
+   * else, so every other plan's cues serialise exactly as they did.
+   *
+   * Times, never invented: they are the synthesiser's own word timestamps, mapped back through
+   * the pronunciation dictionary onto the caption's words. A cue whose words those timestamps
+   * do not describe gets no `words` at all and is drawn whole, which is what a silent recording
+   * gets too.
+   */
+  words: z7.array(z7.number().int().nonnegative()).min(1).optional()
+}).refine(
+  ({ words, lines, startMs, endMs }) => words === void 0 || words.length === lines.join(" ").split(" ").filter((word) => word !== "").length && words.every((at, index) => at >= startMs && at < endMs && (index === 0 || at >= words[index - 1])),
+  {
+    message: "words must time every word of the cue, in order, inside the cue",
+    path: ["words"]
+  }
+);
 var HEX_COLOUR = z7.string().regex(/^#[0-9A-Fa-f]{6}$/, "must be a #RRGGBB colour");
 var OutroSchema = z7.object({
   durationMs: z7.number().int().positive().max(15e3),
@@ -393,6 +476,24 @@ var IntroSchema = z7.object({
   textColor: HEX_COLOUR,
   assPath: z7.literal("captions/intro.ass")
 });
+var HookSchema = z7.object({
+  lines: z7.array(z7.string().min(1)).min(1).max(2),
+  durationMs: z7.number().int().min(1e3).max(1e4),
+  assPath: z7.literal("captions/hook.ass"),
+  /**
+   * The hook drawn as a picture rather than as ASS: a transparent PNG the width of the output
+   * and as tall as the bottom of its band, rasterised in Chromium when the hook was set (at
+   * record time, or by a `render --hook`/`--aspect` re-cut) so its emoji are drawn in colour by
+   * the system's emoji face — libass can only draw them as outlines. Frozen as a source file:
+   * a plain re-render overlays it and never opens a browser. Absent, the hook is drawn from
+   * `assPath` exactly as it was before 1.30, so older bundles re-render byte-identically.
+   */
+  imagePath: z7.literal("captions/hook.png").optional()
+});
+var FrameSchema = z7.object({
+  radius: z7.number().int().positive().max(96),
+  assPath: z7.literal("captions/frame.ass")
+});
 var ChapterMarkSchema = z7.object({
   startMs: z7.number().int().nonnegative(),
   endMs: z7.number().int().positive(),
@@ -451,7 +552,17 @@ var CursorPointSchema = z7.object({
    * always did — so a cursor bundle from before the camera, or from before the letterbox,
    * still parses and regenerates byte-for-byte.
    */
-  scale: z7.number().int().min(1).max(400).optional()
+  scale: z7.number().int().min(1).max(400).optional(),
+  /**
+   * Present only on the first point after a hard cut (`TransitionCutSchema`): the output
+   * instant the picture changes to the next actor's segment. The pointer then does not glide
+   * from the previous point — it parks there until `cutMs` and is parked on this point from
+   * `cutMs` on, so it never slides from a terminal row into a web page over live frames, nor
+   * moves over a frozen picture. Bounded by the previous point's `departMs` and this point's
+   * `arriveMs` (`CursorSchema`'s refine). Absent everywhere else, so a cut-free plan's points
+   * are byte-identical.
+   */
+  cutMs: z7.number().int().nonnegative().optional()
 });
 var CursorSchema = z7.object({
   assPath: z7.literal("captions/cursor.ass"),
@@ -467,6 +578,16 @@ var CursorSchema = z7.object({
     message: "points must be ordered, arrive before departing, and not overlap",
     path: ["points"]
   }
+).refine(
+  ({ points }) => points.every(
+    (point, index) => point.cutMs === void 0 || index > 0 && points[index - 1].departMs <= point.cutMs && point.cutMs <= point.arriveMs
+  ),
+  {
+    // A jump needs somewhere to jump from, and it must happen between leaving the previous
+    // point and reaching this one — anything else would show two arrows or none.
+    message: "cutMs must fall within [previous point departMs, arriveMs], never on the first point",
+    path: ["points"]
+  }
 );
 var CameraShotSchema = z7.object({
   id: z7.string().min(1),
@@ -515,7 +636,22 @@ var SegmentSchema = z7.object({
   id: z7.string().min(1),
   actorId: z7.string().min(1),
   startMs: z7.number().int().nonnegative(),
-  endMs: z7.number().int().positive()
+  endMs: z7.number().int().positive(),
+  /**
+   * Where this segment's frames actually sit inside the concatenated `raw/session.webm`,
+   * measured from the segment files themselves (`probeSegmentSpanMs`, last packet's pts plus
+   * its duration — the offset the concat demuxer gives the next file). Present only on plans
+   * with a hard cut or a `terminal.browser` scenario, and then on every segment (`RenderPlanSchema`'s refine): the splice trims
+   * `[sourceStartMs, sourceEndMs)` instead of the capture-derived `[startMs, endMs)`, because
+   * Chromium's WebM writer can end a segment file short of its capture window, or round a
+   * sub-second capture up to a 1 s file, and a cut's freeze would otherwise clone a frame of
+   * the wrong actor. `sourceEndMs` is the usable end — the file's span capped at `captureMs` for
+   * every segment but the last (which reads past its file's end into the head tail-pad clone, as
+   * the capture-based trim always has) — so it may stop short of the next `sourceStartMs`.
+   * `startMs`/`endMs` keep their capture-derived values regardless.
+   */
+  sourceStartMs: z7.number().int().nonnegative().optional(),
+  sourceEndMs: z7.number().int().positive().optional()
 });
 var TransitionCardSchema = z7.object({
   fromActorId: z7.string().min(1),
@@ -524,12 +660,45 @@ var TransitionCardSchema = z7.object({
   lines: z7.array(z7.string().min(1)).min(1).max(2),
   backgroundColor: HEX_COLOUR,
   textColor: HEX_COLOUR,
-  assPath: z7.string().regex(/^captions\/turn-[0-9]+\.ass$/)
+  assPath: z7.string().regex(/^captions\/turn-[0-9]+\.ass$/),
+  /**
+   * The outgoing segment's last-frame hold before this card, exactly as on a cut
+   * (`TransitionCutSchema.freezeMs`): `contentMs − trimmedSpanMs(source window)`. Only plans
+   * with measured source bounds (every plan with a cut, and every `terminal.browser` plan) carry it; a card in any other plan
+   * never does, so it parses and serialises as it always has.
+   */
+  freezeMs: z7.number().int().positive().optional()
 });
+var TransitionCutSchema = z7.object({
+  kind: z7.literal("cut"),
+  fromActorId: z7.string().min(1),
+  toActorId: z7.string().min(1),
+  /**
+   * How long the outgoing segment's last frame is held before the cut (`tpad=stop_mode=clone`),
+   * so the video reaches the joint the derivation placed at the segment's content length:
+   * `contentMs − trimmedSpanMs(source window)`, present only when that is at least one frame —
+   * usually a trailing cue's overrun, but possibly a single frame (33ms) with no overrun at
+   * all, when the trim keeps one frame fewer than the content slot reserves. The joint itself
+   * still claims 0 (`transitionGapMs`). Cards and explain scenes in a source-bound plan (a cut, or `terminal.browser`) carry the
+   * same optional `freezeMs`; in a plan without source bounds nothing carries one.
+   */
+  freezeMs: z7.number().int().positive().optional()
+}).refine((cut) => cut.fromActorId !== cut.toActorId, {
+  // The same reason `runtime.ts` refuses a turn to the actor already holding the browser:
+  // a joint where nobody changes is an explain scene's, never a hand-off's.
+  message: "a cut must hand off between two different actors (fromActorId !== toActorId)",
+  path: ["toActorId"]
+});
+var TransitionSchema = z7.union([TransitionCardSchema, TransitionCutSchema]);
 var ExplainSegmentPlanSchema = z7.object({
   id: z7.string().min(1),
   segmentPath: z7.string().regex(/^explain\/[a-z0-9][a-z0-9-]*\/segment\.mp4$/),
-  durationMs: z7.number().int().positive()
+  durationMs: z7.number().int().positive(),
+  /**
+   * The hold on the capture segment *before* this scene, as on a cut or card joint
+   * (`TransitionCutSchema.freezeMs`). Only in plans with measured source bounds.
+   */
+  freezeMs: z7.number().int().positive().optional()
 });
 var HighlightRectSchema = z7.object({
   id: z7.string().min(1),
@@ -660,7 +829,23 @@ var SpeechSchema = z7.object({
   sampleRate: z7.literal(24e3),
   channels: z7.literal(1),
   clips: z7.array(SpeechClipSchema).min(1),
-  engine: SpeechEngineSchema.optional()
+  engine: SpeechEngineSchema.optional(),
+  /**
+   * Normalise the assembled track's integrated loudness (ITU-R BS.1770) to `targetLufs`, with
+   * a make-up gain and a lookahead limiter that holds every sample at or under `maxPeakDbfs`.
+   * The short-form platforms play every upload at about -14 LUFS and turn a quieter one down
+   * no further — they only ever turn a louder one *down* — so an unnormalised narration simply
+   * plays quieter than everything around it.
+   *
+   * A target, not a gain: the gain and the limiting are a pure function of the frozen clips
+   * (`normalizeLoudness`, `@plaintake/audio`) recomputed by every freeze in a fixed sequence of
+   * double-precision operations, so the same clips always produce the same track. Absent means the clips are laid out at the level they
+   * were synthesised at, which is every plan before this field.
+   */
+  loudness: z7.object({
+    targetLufs: z7.number().min(-30).max(-5),
+    maxPeakDbfs: z7.number().min(-12).max(0)
+  }).optional()
 }).refine(
   ({ clips }) => new Set(clips.map((clip) => clip.id)).size === clips.length && clips.every(
     (clip, index) => index === 0 || clips[index - 1].atMs + clips[index - 1].durationMs <= clip.atMs
@@ -680,8 +865,8 @@ var SpeechSchema = z7.object({
   // A synthesised clip with no record of what synthesised it is the one state this block
   // exists to prevent. The converse is fine: an engine recorded on an all-file track is
   // merely redundant, not misleading. An `explain` clip is exempt rather than overlooked:
-  // it was synthesised by plainmotion, whose identity the manifest's toolchain block
-  // carries — the `engine` here would name a synthesiser that never touched it.
+  // its scene's own frozen plan records what synthesised it — the `engine` here names the
+  // step narrator's identity, which an explain scene's voice need not share.
   message: "engine must be recorded whenever any clip was synthesised",
   path: ["engine"]
 });
@@ -770,7 +955,31 @@ var RenderPlanSchema = z7.object({
        * `OutroSchema`'s colours are: the value reaches an FFmpeg filtergraph, and that
        * grammar admits no metacharacter.
        */
-      padColor: HEX_COLOUR
+      padColor: HEX_COLOUR,
+      /**
+       * `follow` — the `--reframe follow` opt-in — fills the box with a 4:3 window of the
+       * capture that follows the camera shots (or a fixed centre window with no camera),
+       * instead of the whole 16:9 frame. The one place this plan crops the picture for its
+       * shape rather than for a zoom, and still a render-time decision: the window is a
+       * pure function of `camera.shots` and this box (`followWindow`, `renderer-ffmpeg`),
+       * so a bundle re-cuts into or out of it without re-recording. Absent means the whole
+       * frame is scaled in — every plan before this field, unchanged.
+       */
+      reframe: z7.literal("follow").optional(),
+      /**
+       * The two layouts that treat the picture as an object on a background rather than as
+       * the background itself — `--reframe social` and `--reframe inset`:
+       *
+       * - `social` (9:16, always `follow`): a 9:8 follow window in a box sized and placed for
+       *   short-form feeds — clear of the platforms' own top bar, bottom caption block and
+       *   right-hand action rail — with a band above it for the `hook`, bold captions below it,
+       *   and rounded corners on a branded pad;
+       * - `inset` (16:9, never `follow`): the whole frame scaled into a box inset from every
+       *   edge, with rounded corners on a branded pad.
+       *
+       * Absent means the plain letterbox or follow box — every plan before these, unchanged.
+       */
+      layout: z7.enum(["social", "inset"]).optional()
     }).optional(),
     /*
      * Everything before the closing card: the opening card, if there is one, plus the
@@ -801,6 +1010,21 @@ var RenderPlanSchema = z7.object({
       message: "the letterbox box must fit inside the output frame",
       path: ["letterbox"]
     }
+  ).refine(
+    ({ letterbox }) => letterbox?.reframe === void 0 || (letterbox.layout === "social" ? letterbox.width * 8 === letterbox.height * 9 : letterbox.width * 3 === letterbox.height * 4),
+    {
+      // The follow window is cut to the box's own shape and scaled into it with no further
+      // correction, so a box of any other shape would freeze a stretched picture: 4:3 for the
+      // plain follow box, 9:8 for the social one.
+      message: "a follow letterbox must be exactly 4:3 (9:8 under the social layout)",
+      path: ["letterbox"]
+    }
+  ).refine(
+    ({ letterbox }) => letterbox?.layout === void 0 || (letterbox.layout === "social" ? letterbox.reframe === "follow" : letterbox.reframe === void 0),
+    {
+      message: "the social layout always follows the camera and the inset layout never does",
+      path: ["letterbox"]
+    }
   ),
   captions: z7.object({
     language: z7.string().min(2),
@@ -859,7 +1083,15 @@ var RenderPlanSchema = z7.object({
      * remaining code, middle-centre (5), would put the words back over the picture — which
      * is the thing the letterbox exists to stop.
      */
-    alignment: z7.union([z7.literal(2), z7.literal(8)]).default(2)
+    alignment: z7.union([z7.literal(2), z7.literal(8)]).default(2),
+    /**
+     * The social layout's captions: bold, every character drawn by an explicitly chosen face
+     * (`faceRuns`, `@plaintake/subtitles`, so an emoji or an arrow never depends on the font
+     * provider's fallback), and — on a cue that carries `words` — each word lit in
+     * `highlightColor` as it is spoken, the short-form convention. Absent means the caption style
+     * every other plan has, so its ASS is byte-for-byte what it was.
+     */
+    social: z7.object({ highlightColor: HEX_COLOUR }).optional()
   }),
   ffmpeg: z7.object({
     base: z7.array(z7.string()),
@@ -868,6 +1100,8 @@ var RenderPlanSchema = z7.object({
   }),
   intro: IntroSchema.optional(),
   outro: OutroSchema.optional(),
+  hook: HookSchema.optional(),
+  frame: FrameSchema.optional(),
   chapters: ChaptersSchema.optional(),
   cursor: CursorSchema.optional(),
   camera: CameraSchema.optional(),
@@ -929,8 +1163,8 @@ var RenderPlanSchema = z7.object({
    * field of the five below that a segmented capture *always* carries; the other four are
    * two independent, narrower capabilities layered on top of it:
    *
-   * - `actors`/`transitionCards`/`badgesAssPath` — the multi-actor demo's cast, the cards
-   *   drawn at each hand-off, and the badge track naming the active actor throughout. Three
+   * - `actors`/`transitionCards`/`badgesAssPath` — the multi-actor demo's cast, the card
+   *   drawn (or the hard cut taken — `TransitionCutSchema`, zero screen time) at each hand-off, and the badge track naming the active actor throughout. Three
    *   fields that carry one capability and so, like every other optional block above, are
    *   present or absent together (the first refinement below) — and never without
    *   `segments`, which they reference by `actorId` (the second). Absent means no genuine
@@ -939,8 +1173,8 @@ var RenderPlanSchema = z7.object({
    *   whenever a scenario called `demo.explain()` at all, with or without a cast alongside
    *   it — never without `segments` either (the third refinement), for the same reason.
    *
-   * Every gap between adjacent `segments` is claimed by exactly one occupant, a card or an
-   * explain scene, never both and never neither (the fifth refinement) — which is also why
+   * Every gap between adjacent `segments` is claimed by exactly one occupant, a card, a cut or
+   * an explain scene — a cut claims its gap with zero screen time, but it still claims it — never both and never neither (the fifth refinement) — which is also why
    * `segments` can appear with `transitionCards` and `explainSegments` both absent only when
    * `segments.length === 1` never occurs (`SegmentSchema`'s own `.min(2)` on the array rules
    * it out): a lone, unsegmented capture has no gap to claim in the first place, and needs
@@ -948,7 +1182,7 @@ var RenderPlanSchema = z7.object({
    */
   actors: z7.array(ActorSchema).min(2).optional(),
   segments: z7.array(SegmentSchema).min(2).optional(),
-  transitionCards: z7.array(TransitionCardSchema).min(1).optional(),
+  transitionCards: z7.array(TransitionSchema).min(1).optional(),
   badgesAssPath: z7.literal("captions/badges.ass").optional(),
   explainSegments: z7.array(ExplainSegmentPlanSchema).min(1).optional()
 }).refine(
@@ -963,7 +1197,12 @@ var RenderPlanSchema = z7.object({
     message: "actors, transitionCards and badgesAssPath must be present together or absent together",
     path: ["actors"]
   }
-).refine((plan) => plan.actors === void 0 || plan.segments !== void 0, {
+).refine((plan) => plan.frame === void 0 || plan.video.letterbox?.layout !== void 0, {
+  // Corners are drawn on the box a layout lays the picture in; a plan with no such box has no
+  // corner to round, and drawing one anyway would paint pad colour over the picture itself.
+  message: "frame needs a social or inset letterbox to round the corners of",
+  path: ["frame"]
+}).refine((plan) => plan.actors === void 0 || plan.segments !== void 0, {
   // A cast with nowhere to draw its own windows — `segment.actorId` is what a badge or a
   // transition card is drawn against — cannot render.
   message: "actors requires segments \u2014 a cast with no capture windows of its own cannot render",
@@ -988,6 +1227,24 @@ var RenderPlanSchema = z7.object({
     message: "segments must tile raw/session.webm contiguously from 0",
     path: ["segments"]
   }
+).refine(
+  (plan) => {
+    if (plan.segments === void 0) return true;
+    const { segments } = plan;
+    const sourced = segments.filter(
+      (segment) => segment.sourceStartMs !== void 0 || segment.sourceEndMs !== void 0
+    );
+    if (sourced.length === 0) return true;
+    return segments.every(
+      (segment, index) => segment.sourceStartMs !== void 0 && segment.sourceEndMs !== void 0 && segment.sourceEndMs > segment.sourceStartMs && (index === 0 || segment.sourceStartMs >= segments[index - 1].sourceEndMs)
+    );
+  },
+  {
+    // All or none: a splice that trimmed some segments by measured source position and the
+    // rest by capture position would mix two coordinate systems in one graph.
+    message: "sourceStartMs/sourceEndMs must be present on every segment or on none, each window non-empty and in order without overlap",
+    path: ["segments"]
+  }
 ).refine(
   (plan) => {
     if (plan.segments === void 0) return true;
@@ -1100,7 +1357,20 @@ var ValidationResultSchema = z8.object({
      * without first trying to run it. Defaulted, so a result written before this parses.
      */
     handoff: z8.enum(["none", "preflight", "session"]).default("none"),
-    sha256: Sha2563
+    sha256: Sha2563,
+    /**
+     * The terminal the scenario records instead of a web page, with its defaults applied, or
+     * null for a browser scenario. Defaulted like `handoff`, so a result written before
+     * terminals existed parses.
+     */
+    terminal: z8.object({
+      cols: z8.number().int(),
+      rows: z8.number().int(),
+      shell: z8.string(),
+      command: z8.array(z8.string()).optional(),
+      /** Present (true) only when the scenario declares `terminal.browser`. */
+      browser: z8.literal(true).optional()
+    }).nullable().default(null)
   }).optional()
 });
 var RunCommandResultSchema = z8.object({
@@ -1381,21 +1651,16 @@ var DoctorResultSchema = z8.object({
     notes: z8.array(z8.string())
   }),
   /**
-   * Whether the plainmotion CLI is on `PATH`, for a scenario that wants to call
-   * `demo.explain()`. The same stance `hasAac`/`speech` above already take: absence is a
-   * *state*, not a fault — the overwhelming majority of scenarios never cut away to an
-   * explain scene, so `doctor` must not fail an otherwise-healthy installation over a binary
-   * most runs will never invoke. `assertPlainmotion` (`recorder-playwright`) is the same
-   * probe a run's own first `demo.explain()` pays, so `doctor` cannot say plainmotion is fine
-   * and then a run refuse it.
+   * Whether a terminal scenario could be recorded right now: the vendored node-pty loads, and
+   * xterm.js and the terminal font are in place. Never folded into `problems` — the same stance as
+   * `speech` — because only a scenario declaring `terminal` needs any of it. Optional so a result
+   * written before terminals existed parses.
    */
-  plainmotion: z8.object({
-    installed: z8.boolean(),
-    /** plainmotion's own `--version` output. Absent when not installed. */
-    version: z8.string().optional(),
-    /** Why the probe failed, in the same words a run's own refusal would use. Absent when installed. */
-    note: z8.string().optional()
-  })
+  terminal: z8.object({
+    ready: z8.boolean(),
+    /** What is missing, in the words a refused run would use. Empty when ready. */
+    notes: z8.array(z8.string())
+  }).optional()
 });
 var okMatchesProblems = (value) => value.ok === (value.problems.length === 0);
 var ActivateReasonSchema = z8.enum([
@@ -1451,6 +1716,7 @@ var PublishReasonSchema = z8.enum([
   "hash-mismatch",
   "length-mismatch",
   "conflict",
+  "taken-down",
   "unexpected-response"
 ]);
 var PublishResultSchema = z8.discriminatedUnion("ok", [
@@ -1467,6 +1733,12 @@ var PublishResultSchema = z8.discriminatedUnion("ok", [
     url: z8.string().regex(/^https?:\/\/\S+$/, "must be an http or https URL"),
     /** False when the video was already on the service — nothing was uploaded. */
     uploaded: z8.boolean(),
+    /**
+     * True when the share had been unpublished (or had expired) and this publish brought
+     * it back — `unpublish`'s undo. Defaults to false so a result written before the
+     * field existed still parses.
+     */
+    restored: z8.boolean().default(false),
     /**
      * Present only when `--remember` was asked: true when the key was stored beside
      * license.json, false when the key file could not be written. The service's
@@ -1486,6 +1758,42 @@ var PublishResultSchema = z8.discriminatedUnion("ok", [
     poster: z8.boolean()
   })
 ]).refine(okMatchesProblems, "ok must be true iff problems is empty");
+var UnpublishReasonSchema = z8.enum([
+  "no-endpoint",
+  "no-key",
+  "invalid-store",
+  "not-a-bundle",
+  "invalid-target",
+  "endpoint-mismatch",
+  "unauthorized",
+  "forbidden",
+  "not-found",
+  "unreachable",
+  "unexpected-response"
+]);
+var UnpublishResultSchema = z8.discriminatedUnion("ok", [
+  z8.object({
+    ...envelope("unpublish"),
+    ok: z8.literal(false),
+    reason: UnpublishReasonSchema
+  }),
+  z8.object({
+    ...envelope("unpublish"),
+    ok: z8.literal(true),
+    videoId: z8.string().regex(/^[a-z2-7]{26}$/, "must be a 26-char base32 share id"),
+    /** The page that now answers 410. */
+    url: z8.string().regex(/^https?:\/\/\S+$/, "must be an http or https URL"),
+    /** When the share went dark; repeating an unpublish keeps the first instant. */
+    deletedAt: z8.string().min(1),
+    /**
+     * Who holds the tombstone. `admin` means the service's operator had already taken
+     * the share down — still a success (it is dark), but only the operator can undo it.
+     */
+    deletedBy: z8.enum(["producer", "admin", "expired"]),
+    /** When retention may delete the bytes for good; a republish before then restores. */
+    purgeAfter: z8.string().min(1)
+  })
+]).refine(okMatchesProblems, "ok must be true iff problems is empty");
 
 // ../schema/src/zod-format.ts
 import { ZodError } from "zod";

package/dist/schema/manifest.d.ts

@@ -26,6 +26,7 @@ export declare const BundleManifestSchema: z.ZodObject<{
         timezone: z.ZodLiteral<"UTC">;
         viewport: z.ZodTuple<[z.ZodLiteral<1920>, z.ZodLiteral<1080>], null>;
         deviceScaleFactor: z.ZodLiteral<1>;
+        uiScale: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<1.5>, z.ZodLiteral<2>]>>;
     }, z.core.$strip>;
     assertions: z.ZodArray<z.ZodObject<{
         id: z.ZodString;

package/dist/schema/narration-index.d.ts

@@ -19,7 +19,7 @@ import { z } from 'zod';
  * version): those come from the current build, never from the file.
  *
  * Only `synth`-sourced clips appear. A `--speech file` clip is the author's own audio with nothing
- * to synthesise, and an `explain` scene is plainmotion's, not this narrator's.
+ * to synthesise, and an `explain` scene's narration is synthesised by its own compile, not this narrator.
  */
 export declare const NARRATION_INDEX_SCHEMA = "agent-demo.narration-index/v1";
 /**