@tandryukha/aidemo 0.8.0 → 0.15.0

package/src/types.ts

@@ -42,7 +42,35 @@ const TargetSchema = z.object({
 });
 export type Target = z.infer<typeof TargetSchema>;
 
-const BaseAction = { comment: z.string().optional() };
+const BaseAction = {
+  comment: z.string().optional(),
+  /**
+   * Best-effort action: when its target never appears or the interaction
+   * fails, log and continue instead of failing the take. For state-dependent
+   * one-time UI — e.g. collapsing the ChatGPT sidebar persists in the Chrome
+   * profile, so a re-run finds the close button absent and a required click
+   * would kill the run. Interaction ops (click/type/hover/scrollTo/focus)
+   * probe briefly for the target instead of stalling out the full action
+   * timeout; wait ops honor their own timeoutMs and then continue. Don't mark
+   * actions the demo's visuals depend on — a skipped optional action is only
+   * a log line.
+   */
+  optional: z.boolean().optional(),
+  /**
+   * Re-attempt an interaction (click/type/hover/scrollTo/focus/moveTo/assert)
+   * up to this many extra times when it throws — a beat apart — before the
+   * take fails. For UI that re-renders under the cursor (a list that
+   * reorders on load, a button that mounts twice). Retries land in
+   * timeline.json `actions[].retries`. Optional actions skip instead.
+   */
+  retry: z.number().int().min(0).max(5).optional(),
+  /**
+   * Narration anchor: land this action on the word marked `{{@name}}` in the
+   * scene's narration. Compose retimes the scene piecewise so the beat plays
+   * as the word is spoken. See docs/AUTHORING.md "Narration-anchored beats".
+   */
+  anchor: z.string().regex(/^[\w.-]+$/).optional(),
+};
 
 /**
  * Scroll easing presets. All are eased wheel scrolls; they differ in feel:
@@ -52,12 +80,39 @@ const BaseAction = { comment: z.string().optional() };
 export const EasingPresetSchema = z.enum(["smooth", "snappy", "glide", "linear"]);
 export type EasingPreset = z.infer<typeof EasingPresetSchema>;
 
+/**
+ * Element state a wait/scroll resolves on. "visible" (default) is Playwright's
+ * non-empty-box visibility; "attached" only requires the element to be in the
+ * DOM — the escape hatch for zero-height lazy mount points.
+ */
+export const WaitStateSchema = z.enum(["visible", "attached"]);
+export type WaitState = z.infer<typeof WaitStateSchema>;
+
+/** Look of an attention overlay (highlight ring, spotlight edge, callout pill). */
+export const AttentionStyleSchema = z.object({
+  /** CSS color. Default: the storyboard `attention.color`, else #ff5a5f. */
+  color: z.string().optional(),
+  /** Outline thickness, px. Default 3. */
+  thickness: z.number().min(1).max(12).optional(),
+  /** Room between the element's box and the outline, px. Default 6. */
+  padding: z.number().min(0).max(60).optional(),
+  /** "box" (rounded rectangle, default) or "ring" (pill/circle). */
+  shape: z.enum(["box", "ring"]).optional(),
+});
+export type AttentionStyle = z.infer<typeof AttentionStyleSchema>;
+
 export const ActionSchema = z.discriminatedUnion("op", [
   z.object({ ...BaseAction, op: z.literal("goto"), url: z.string() }),
   z.object({
     ...BaseAction,
     op: z.literal("click"),
     target: TargetSchema,
+    /**
+     * When the click opens a NEW TAB (target=_blank, window.open), close it and
+     * continue in the recorded tab at that URL — the take is one window, a
+     * second tab is never in the video. Default false (a popup is left alone).
+     */
+    followPopup: z.boolean().optional(),
   }),
   z.object({
     ...BaseAction,
@@ -67,11 +122,26 @@ export const ActionSchema = z.discriminatedUnion("op", [
     /** Per-keystroke jitter for a human cadence. Default true. */
     humanize: z.boolean().optional(),
   }),
-  z.object({ ...BaseAction, op: z.literal("press"), key: z.string() }),
+  z.object({
+    ...BaseAction,
+    op: z.literal("press"),
+    key: z.string(),
+    /** Show a keystroke chip for this press (overrides the top-level `keystrokes`). */
+    keystrokes: z.boolean().optional(),
+  }),
   z.object({
     ...BaseAction,
     op: z.literal("hover"),
     target: TargetSchema,
+    /**
+     * Where the pointer parks relative to the element. Default "center" — but
+     * on a small chip or a number the narration is about, the cursor then
+     * COVERS the thing it points at (issue #50). "edge" (or a side) parks it
+     * just outside the element's box, still close enough to read as pointing.
+     */
+    anchor: z.enum(["center", "edge", "top", "bottom", "left", "right"]).optional(),
+    /** Extra nudge from the anchor point, CSS px. */
+    offset: z.object({ x: z.number(), y: z.number() }).optional(),
   }),
   z.object({
     ...BaseAction,
@@ -81,22 +151,51 @@ export const ActionSchema = z.discriminatedUnion("op", [
     easing: EasingPresetSchema.optional(),
     /** Override the preset's duration, ms. */
     durationMs: z.number().optional(),
+    /**
+     * Which element state to wait for before scrolling. Default "visible".
+     * "attached" accepts a zero-size mount point (a lazily-filled empty <div>
+     * that only renders once scrolled into view) — such an element is in the
+     * DOM but never "visible", so the default would time out (issue #44).
+     */
+    state: WaitStateSchema.optional(),
+    /**
+     * After the scroll, wait until the scroll position has been still for this
+     * many ms (bounded at 3 s) — an honest "scroll finished" instead of a fixed
+     * pause against smooth-scroll settle races. Omit for the old fixed settle.
+     */
+    settleMs: z.number().optional(),
   }),
   z.object({
     ...BaseAction,
     op: z.literal("scrollBy"),
     /** CSS pixels to scroll; positive = down. */
     dy: z.number(),
+    /**
+     * Scope the scroll to this element's own scroller: the wheel is dispatched
+     * over the element, and `dy` is clamped to the room its nearest scrollable
+     * ancestor actually has — so a bottomed-out inner panel never chains the
+     * wheel to the page and slides the whole app off-screen (issue #43). Omit
+     * to scroll whatever is under the cursor (the page, usually).
+     */
+    target: TargetSchema.optional(),
     /** Scroll feel preset. Default "smooth". */
     easing: EasingPresetSchema.optional(),
     /** Override the preset's duration, ms. */
     durationMs: z.number().optional(),
+    /** Wait until the scroll position has been still for this many ms (see scrollTo). */
+    settleMs: z.number().optional(),
   }),
   z.object({
     ...BaseAction,
     op: z.literal("waitFor"),
     target: TargetSchema,
     timeoutMs: z.number().optional(),
+    /**
+     * Element state to wait for. Default "visible". "attached" = present in
+     * the DOM even if zero-size/hidden — for lazily-filled mount points that
+     * only become visible once something renders into them (issue #44).
+     */
+    state: WaitStateSchema.optional(),
   }),
   /**
    * Wait for an IN-PLACE mutation of an existing element — the gap that neither
@@ -183,6 +282,138 @@ export const ActionSchema = z.discriminatedUnion("op", [
    * across the storyboard are a hard error at extraction.
    */
   z.object({ ...BaseAction, op: z.literal("still"), name: z.string() }),
+  /**
+   * Attention beats — compose-time overlays drawn from a box the player
+   * measures (like `focus`, they are timeline markers; the drawing happens at
+   * compose, so restyling is a recompose). Each dwells briefly at record time
+   * (min(holdMs, 800) ms) so the eye registers it before the next action.
+   */
+  /** Outline `target` (box or ring) for `holdMs`. */
+  z.object({
+    ...BaseAction,
+    op: z.literal("highlight"),
+    target: TargetSchema,
+    /** How long the outline stays, ms. Default 1600. */
+    holdMs: z.number().min(100).max(15000).optional(),
+    style: AttentionStyleSchema.optional(),
+  }),
+  /** Dim everything except `target` for `holdMs`. */
+  z.object({
+    ...BaseAction,
+    op: z.literal("spotlight"),
+    target: TargetSchema,
+    holdMs: z.number().min(100).max(15000).optional(),
+    /** Opacity of the dim layer, 0–0.9. Default 0.55. */
+    dimTo: z.number().min(0).max(0.9).optional(),
+    /** Extra room around the element, px. Default 10. */
+    padding: z.number().min(0).max(80).optional(),
+    style: AttentionStyleSchema.optional(),
+  }),
+  /** Pin a short label to `target` for `holdMs`. */
+  z.object({
+    ...BaseAction,
+    op: z.literal("callout"),
+    target: TargetSchema,
+    text: z.string().min(1).max(80),
+    /** Where the label sits relative to the element. Default "auto". */
+    placement: z.enum(["auto", "top", "bottom", "left", "right"]).optional(),
+    holdMs: z.number().min(100).max(15000).optional(),
+    style: AttentionStyleSchema.optional(),
+  }),
+  /**
+   * Park the cursor deliberately: glide it to `target` (element center) or an
+   * absolute viewport point (`x`,`y` CSS px) without clicking. Use it to move
+   * the cursor out of the way before a reveal, or to point at what the
+   * narration is talking about without an interaction.
+   */
+  z.object({
+    ...BaseAction,
+    op: z.literal("moveTo"),
+    target: TargetSchema.optional(),
+    x: z.number().optional(),
+    y: z.number().optional(),
+  }),
+  /**
+   * Prove the payoff happened. Fails the take with a named error unless
+   * `target` is visible (and, when set, its text matches `textMatches`) and/or
+   * the page URL matches `url` — polled until `timeoutMs` (default 5000). A
+   * demo whose confirmation never rendered should fail loudly at record time,
+   * not ship a video of a spinner.
+   */
+  z.object({
+    ...BaseAction,
+    op: z.literal("assert"),
+    target: TargetSchema.optional(),
+    /** Regex the target's text must match (JS syntax, e.g. "Order #\\d+"). */
+    textMatches: z.string().optional(),
+    /** Regex the page URL must match. */
+    url: z.string().optional(),
+    timeoutMs: z.number().optional(),
+  }),
+  /** Choose an option in a native <select> by value or visible label (the cursor clicks it first). */
+  z.object({
+    ...BaseAction,
+    op: z.literal("select"),
+    target: TargetSchema,
+    value: z.string().optional(),
+    label: z.string().optional(),
+  }),
+  /**
+   * Drag `target` to `to` (another target, or absolute viewport `x`,`y`):
+   * press, glide with the cursor, release — the drag shows in the take.
+   */
+  z.object({
+    ...BaseAction,
+    op: z.literal("drag"),
+    target: TargetSchema,
+    to: z.object({
+      target: TargetSchema.optional(),
+      x: z.number().optional(),
+      y: z.number().optional(),
+    }),
+  }),
+  /**
+   * Attach files: `target` is a file input (set directly) or the button that
+   * opens the OS file chooser (clicked; the chooser is answered headlessly —
+   * no dialog appears in the take). Paths resolve against the demo dir.
+   */
+  z.object({
+    ...BaseAction,
+    op: z.literal("upload"),
+    target: TargetSchema,
+    files: z.array(z.string()).min(1),
+  }),
+  /** Browser back (history), with the same readiness wait as `goto`. */
+  z.object({ ...BaseAction, op: z.literal("back") }),
+  /**
+   * Arm a one-shot handler for the NEXT native dialog (`alert`, `confirm`,
+   * `prompt`, `beforeunload`) so the action that triggers it actually goes
+   * through (issue #54). Playwright auto-DISMISSES dialogs when nothing is
+   * listening, so without this a filmed click on an "Archive this?" button
+   * looks like it worked while the handler never ran — a false outcome on
+   * camera. Put the `dialog` action immediately BEFORE the click that opens it.
+   *
+   * The dialog itself is chrome, not page content, so it is not visible in the
+   * take; `holdMs` only paces the beat before answering.
+   */
+  z.object({
+    ...BaseAction,
+    op: z.literal("dialog"),
+    /** Answer the dialog with OK (default) or Cancel. */
+    action: z.enum(["accept", "dismiss"]).default("accept"),
+    /** Text typed into a `prompt()` before accepting. */
+    promptText: z.string().optional(),
+    /** Wait this long before answering, ms. Default 0. */
+    holdMs: z.number().min(0).max(5000).optional(),
+    /** How long to wait for the dialog to appear before warning, ms. Default 5000. */
+    timeoutMs: z.number().optional(),
+    /**
+     * Set false when the dialog is not guaranteed to open — the take then only
+     * notes that none came. Default true: a `dialog` whose dialog never fired
+     * fails the take, because the filmed action silently did nothing.
+     */
+    required: z.boolean().optional(),
+  }),
 ]);
 export type Action = z.infer<typeof ActionSchema>;
 
@@ -201,6 +432,13 @@ export const VoicePlanSchema = z.object({
   instructions: z.string().optional(),
   /** Playback speed hint passed to the provider when supported. Default 1.0. */
   speed: z.number().min(0.5).max(2).optional(),
+  /**
+   * TTS-only substitutions, whole-word, case-sensitive: `{"aidemo":"A.I. demo",
+   * "SQL":"sequel"}`. Applied to the text sent to the voice provider; the
+   * narration (and therefore the captions) keeps the written form. Merged
+   * storyboard → scene (scene entries win).
+   */
+  pronounce: z.record(z.string(), z.string()).optional(),
 });
 export type VoicePlan = z.infer<typeof VoicePlanSchema>;
 
@@ -217,8 +455,169 @@ export const MusicCueSchema = z.object({
 // Scene + Storyboard
 // ---------------------------------------------------------------------------
 
+/**
+ * A region to blur at compose time. The player re-measures the selector after
+ * every action (all matches, up to 8) and logs the spans; compose crops, blurs
+ * and overlays each span back — so a price, an email, a token never ships,
+ * and the strength is a recompose. Frame-relative selectors use `frame`.
+ */
+export const RedactSchema = z.object({
+  selector: z.string(),
+  frame: z.string().optional(),
+  /** boxblur radius, px at the logical size. Default 14. */
+  blur: z.number().min(2).max(60).optional(),
+});
+export type Redact = z.infer<typeof RedactSchema>;
+
+/** Caption strip placement + look. */
+export const CaptionsConfigSchema = z.object({
+  /**
+   * "bottom" (default) or "top". With "auto-flip" (the default behaviour when
+   * omitted at scene level) compose moves the strip to the top while a
+   * highlight/spotlight/callout box or a keystroke chip would collide with it.
+   */
+  position: z.enum(["bottom", "top"]).optional(),
+  /** "pill" (default, centered rounded box), "bar" (full-width band), "none" (no captions burned). */
+  style: z.enum(["pill", "bar", "none"]).optional(),
+  /** CSS font-family. Default: the brand font, else the system sans. */
+  font: z.string().optional(),
+  /** Font size, px at the logical width. Default 30. */
+  size: z.number().min(14).max(72).optional(),
+  /** Text color. Default #fff. */
+  color: z.string().optional(),
+  /** Pill/bar background (CSS). Default rgba(12,14,22,.66). */
+  background: z.string().optional(),
+  /**
+   * Cue segmentation (storyboard level only — per-scene overrides just move
+   * the strip). Defaults follow broadcast practice: up to 2 lines of ~38
+   * characters, 1–6 s per cue, broken at punctuation and conjunctions rather
+   * than at a hard word count (issue #48).
+   */
+  /** Max words per cue. Default 12 (≈2 lines). */
+  maxWords: z.number().int().min(2).max(30).optional(),
+  /** Max cue length, ms. Default 6000. */
+  maxCueMs: z.number().min(500).max(12000).optional(),
+  /** Cues shorter than this are merged into a neighbour where they fit, ms. Default 1000. */
+  minCueMs: z.number().min(0).max(4000).optional(),
+  /** Lines a cue may occupy. Default 2. */
+  maxLines: z.number().int().min(1).max(3).optional(),
+  /** Characters per line used to size a cue. Default 38. */
+  maxCharsPerLine: z.number().int().min(16).max(80).optional(),
+});
+export type CaptionsConfig = z.infer<typeof CaptionsConfigSchema>;
+
+/** Storyboard-wide defaults for the attention overlays. */
+export const AttentionConfigSchema = z.object({
+  /** Default outline / pill accent color. Default #ff5a5f. */
+  color: z.string().optional(),
+  /** Draw a click ring where every click lands (compose-time cursor only). */
+  clicks: z.boolean().optional(),
+  /**
+   * Move the cursor out of the way before a highlight/spotlight/callout/focus
+   * beat, so the pointer never sits on top of the value being showcased
+   * (issue #50). Opt-in; the cursor glides to just outside the target's box.
+   */
+  cursorClear: z.boolean().optional(),
+});
+export type AttentionConfig = z.infer<typeof AttentionConfigSchema>;
+
+/**
+ * Produced-look frame around the content: padding, background, rounded
+ * corners, drop shadow, optional browser chrome. Compose-time; captions and
+ * cards render at the framed canvas size. Omit for the raw recording frame.
+ */
+export const FrameSchema = z.object({
+  /** Padding around the video, px at the logical size. Default 48. */
+  padding: z.number().min(0).max(400).optional(),
+  /** CSS background (color or gradient). Default: dark gradient tinted by brand.accent. */
+  background: z.string().optional(),
+  /** Corner radius of the video window, px. Default 14. */
+  radius: z.number().min(0).max(80).optional(),
+  /** Drop shadow under the window. Default true. */
+  shadow: z.boolean().optional(),
+  /**
+   * Window chrome: "none" (default), "browser" / "mac" (a bar with dots or
+   * traffic lights above the video), or a device bezel for phone-sized
+   * viewports — "iphone" (rounded bezel + dynamic island) / "android" (bezel +
+   * punch-hole camera). Device chrome adds no bar; `radius` defaults to 40.
+   */
+  chrome: z.enum(["none", "browser", "mac", "iphone", "android"]).optional(),
+  /**
+   * Device chrome only: reserve a status-bar strip of bezel ABOVE the video
+   * (px at the logical size) instead of drawing the island / punch-hole over
+   * the recording's top pixels. `true` = 46 px (an iPhone status bar). Use it
+   * when the app paints something at the very top that must stay visible.
+   */
+  safeTop: z.union([z.boolean(), z.number().min(0).max(120)]).optional(),
+  /** Text in the chrome's address pill (url wins over title). */
+  title: z.string().optional(),
+  /**
+   * Address-pill text. `"auto"` tracks the page: each scene's pill shows the
+   * host of the URL that scene is actually on (from the take's `goto`s), so a
+   * demo that moves between hosts stops printing one fixed address over all of
+   * them (issue #52). Any other string is used verbatim for the whole video.
+   */
+  url: z.string().optional(),
+});
+export type Frame = z.infer<typeof FrameSchema>;
+
+/** Brand kit applied across cards, frame, captions, callouts and a watermark. */
+export const BrandSchema = z.object({
+  /** Logo image path (png/svg/jpg), relative to the demo dir or absolute. Used as the watermark. */
+  logo: z.string().optional(),
+  /** Accent color: card rule, frame tint, default attention color. */
+  accent: z.string().optional(),
+  /** CSS font-family for cards, captions, callouts, chrome. */
+  font: z.string().optional(),
+  /** Watermark placement for `logo`. */
+  watermark: z
+    .object({
+      position: z
+        .enum(["top-left", "top-right", "bottom-left", "bottom-right"])
+        .optional(),
+      /** 0–1. Default 0.85. */
+      opacity: z.number().min(0).max(1).optional(),
+      /** Logo width as a fraction of the frame width. Default 0.11. */
+      scale: z.number().min(0.03).max(0.5).optional(),
+      /** Set false to keep the logo out of the video (cards only). */
+      enabled: z.boolean().optional(),
+    })
+    .optional(),
+});
+export type Brand = z.infer<typeof BrandSchema>;
+
+/** Tuning for compose-time idle detection (`autoIdle`). */
+export const AutoIdleSchema = z.object({
+  enabled: z.boolean().optional(),
+  /** Shortest motionless span that counts as idle, ms. Default 1500. */
+  minMs: z.number().min(400).max(20000).optional(),
+  /**
+   * Per-pixel noise floor below which two frames count as identical (ffmpeg
+   * `freezedetect` noise, 0..1). Default 0.003 — tolerant of encoder dither,
+   * tight enough that a blinking caret still reads as motion.
+   */
+  noise: z.number().min(0).max(0.2).optional(),
+});
+export type AutoIdle = z.infer<typeof AutoIdleSchema>;
+
+/**
+ * Scene-to-scene transition (opt-in). When present, compose crossfades the
+ * video across every scene boundary instead of hard-cutting. The overlap is
+ * stolen from each scene's own frozen tail so the timeline does NOT shrink —
+ * total duration and per-scene narration alignment are preserved exactly.
+ * Omit the key for the default hard cuts (unchanged stream-copy concat).
+ */
+export const TransitionSchema = z.object({
+  type: z.literal("crossfade"),
+  /** Crossfade length, ms. Default 400. */
+  durationMs: z.number().default(400),
+});
+export type Transition = z.infer<typeof TransitionSchema>;
+
 export const SceneSchema = z.object({
   id: z.string(),
+  /** Chapter title for this beat (`output.chapters`); defaults to the scene id. */
+  title: z.string().optional(),
   /** Spoken narration for this beat. Also the caption source of truth. */
   narration: z.string(),
   /**
@@ -230,10 +629,34 @@ export const SceneSchema = z.object({
    * LLM to translate. A code missing here falls back to `narration`.
    */
   narrations: z.record(z.string(), z.string()).optional(),
+  /**
+   * Engine-populated at parse time from `{{@name}}` markers in `narration`:
+   * name → 0-based index of the word the beat lands on. Don't author this —
+   * write the marker in the narration instead.
+   */
+  anchors: z.record(z.string(), z.number().int().min(0)).optional(),
+  /** Same, per `narrations` language code. */
+  narrationAnchors: z.record(z.string(), z.record(z.string(), z.number().int().min(0))).optional(),
   voice: VoicePlanSchema.optional(),
   music: MusicCueSchema.optional(),
   /** Set false to suppress auto-zoom for this scene's clicks/typing. */
   zoom: z.boolean().optional(),
+  /** Override the top-level `autoIdle` for this scene (true enables, false disables). */
+  autoIdle: z.boolean().optional(),
+  /** Caption placement for this scene (overrides top-level `captions.position`). */
+  captions: CaptionsConfigSchema.optional(),
+  /**
+   * Override the storyboard `transition` at the boundary ENTERING this scene:
+   * `false` hard-cuts into it, an object changes the crossfade. Use it when a
+   * dissolve would ghost — e.g. this scene opens on a new page still painting
+   * (issue #49). Boundaries that cross a navigation hard-cut automatically;
+   * this is the manual override.
+   */
+  transition: z.union([z.literal(false), TransitionSchema]).optional(),
+  /** Blur these regions while this scene records (adds to top-level `redact`). */
+  redact: z.array(RedactSchema).optional(),
+  /** Hide these selectors for this scene (adds to top-level `hide`). */
+  hide: z.array(z.string()).optional(),
   actions: z.array(ActionSchema).default([]),
 });
 export type Scene = z.infer<typeof SceneSchema>;
@@ -317,6 +740,20 @@ export const CursorConfigSchema = z.object({
   hideScenes: z.array(z.string()).optional(),
   /** Cursor size multiplier (1 = the 24px baseline arrow). */
   scale: z.number().min(0.5).max(4).optional(),
+  /** Pointer look: classic "arrow" (default) or a soft "dot" (screen-recorder style). */
+  style: z.enum(["arrow", "dot"]).optional(),
+  /** Dot style only: fill color. Default rgba(255,90,95,.85). */
+  color: z.string().optional(),
+  /**
+   * Outline drawn around the pointer so it stays findable on brand-coloured
+   * UI (a gold dot on a gold chip disappears — issue #50). CSS color; default
+   * rgba(255,255,255,.9) for "dot", the arrow's dark stroke otherwise.
+   */
+  outline: z.string().optional(),
+  /** Outline thickness in cursor units (the pointer is 24 wide). Default 2. */
+  outlineWidth: z.number().min(0).max(6).optional(),
+  /** Soft contrasting halo behind the pointer — findable on any background. */
+  halo: z.boolean().optional(),
 });
 export type CursorConfig = z.infer<typeof CursorConfigSchema>;
 
@@ -347,19 +784,6 @@ export const CardSchema = z.object({
 });
 export type Card = z.infer<typeof CardSchema>;
 
-/**
- * Scene-to-scene transition (opt-in). When present, compose crossfades the
- * video across every scene boundary instead of hard-cutting. The overlap is
- * stolen from each scene's own frozen tail so the timeline does NOT shrink —
- * total duration and per-scene narration alignment are preserved exactly.
- * Omit the key for the default hard cuts (unchanged stream-copy concat).
- */
-export const TransitionSchema = z.object({
-  type: z.literal("crossfade"),
-  /** Crossfade length, ms. Default 400. */
-  durationMs: z.number().default(400),
-});
-export type Transition = z.infer<typeof TransitionSchema>;
 
 /**
  * Master loudness target for the final muxed audio (ffmpeg `loudnorm`). Lands
@@ -389,15 +813,57 @@ export type Loudness = z.infer<typeof LoudnessSchema>;
  * `loudness` (independent of resize) tunes the master level; omit it entirely
  * for the automatic default (loudnorm when there's music, none otherwise).
  */
+/** Named output presets — fill width/height/fit when they are not set explicitly. */
+export const OutputPresetSchema = z.enum(["youtube", "short", "readme-gif", "x"]);
+export type OutputPreset = z.infer<typeof OutputPresetSchema>;
+export const OUTPUT_PRESETS: Record<
+  OutputPreset,
+  { width: number; height: number; fit: "contain" | "cover" }
+> = {
+  youtube: { width: 1920, height: 1080, fit: "contain" },
+  short: { width: 1080, height: 1920, fit: "contain" },
+  "readme-gif": { width: 960, height: 540, fit: "contain" },
+  x: { width: 1280, height: 720, fit: "contain" },
+};
+
 export const OutputSchema = z
   .object({
+    /** Preset sizing (see OUTPUT_PRESETS); explicit width/height/fit win. */
+    preset: OutputPresetSchema.optional(),
+    /** Write MP4 chapter markers, one per scene (scene `title` or id). Default false. */
+    chapters: z.boolean().optional(),
+    /**
+     * Also extract output/poster.png. `true` picks the first frame after the
+     * intro card that actually shows CONTENT (a blank white load frame is
+     * skipped — issue #47); a number picks the frame at that ms of the final
+     * video instead. Default false.
+     */
+    poster: z.union([z.boolean(), z.number().min(0)]).optional(),
+    /**
+     * Drop the browser's blank pre-paint at the very start of the video, so
+     * the demo opens on the product instead of on ~0.5 s of white under the
+     * first caption (issue #47). At most `blankOpenCapMs` of the leading flat
+     * span is kept. Default false (unchanged opening).
+     */
+    trimLeadingBlank: z.boolean().optional(),
+    /** With `trimLeadingBlank`: leading blank kept, ms. Default 100. */
+    blankOpenCapMs: z.number().min(0).max(2000).optional(),
+    /**
+     * Also export output/walkthrough/ (index.html + guide.md + per-scene
+     * frames + captions) after every render. Default false; `aidemo
+     * walkthrough <dir>` / the `walkthrough` job export on demand.
+     */
+    walkthrough: z.boolean().optional(),
     width: z.number().optional(),
     height: z.number().optional(),
     /**
      * "contain" (default) = scale to fit + pad the remainder (letterbox bars).
-     * "cover" = scale to fill + center-crop the overflow (no bars).
+     * "cover" = scale to fill + center-crop the overflow (no bars) — the
+     * edge-to-edge answer when the capture's aspect differs from the
+     * preset's (issue #58). Set explicitly it also wins over a `preset`'s
+     * own fit; leave it out to take the preset's.
      */
-    fit: z.enum(["contain", "cover"]).default("contain"),
+    fit: z.enum(["contain", "cover"]).optional(),
     /** Pad color for "contain" (ffmpeg color syntax, e.g. black, 0x1a1a1a). Default black. */
     background: z.string().optional(),
     /**
@@ -415,6 +881,99 @@ export const OutputSchema = z
   });
 export type Output = z.infer<typeof OutputSchema>;
 
+
+/**
+ * What compose does when a scene's narration outlasts its recorded action
+ * (after the ≤1.6x slow-down): the remainder is a HOLD on the last frame.
+ * Default "freeze" clones that frame (byte-for-byte the pre-`hold` behavior).
+ * "drift" instead pushes in very slowly on it (a Ken-Burns-style creep of
+ * `driftScale` over the hold), so a 10 s hold reads as a deliberate dwell
+ * rather than a stalled video — the fix for narration-heavy demos where half
+ * the runtime was a frozen frame (issue #40). `backoffMs` takes the held frame
+ * from slightly BEFORE the segment's end, dodging a half-painted transition or
+ * a hover state caught mid-flight. Opt-in: omit the key for the old behavior.
+ */
+export const HoldSchema = z.object({
+  mode: z.enum(["freeze", "drift"]).default("freeze"),
+  /** Drift mode: zoom level reached at the end of the hold. Default 1.06. */
+  driftScale: z.number().min(1).max(1.5).default(1.06),
+  /** Take the held frame this many ms before the segment end. Default 0. */
+  backoffMs: z.number().min(0).max(2000).default(0),
+  /**
+   * Shortest hold that still drifts, ms. Default 2000: a 6-px push over a
+   * second reads as a bob — a jitter bug — not as a dwell, so short holds
+   * freeze instead (issue #57).
+   */
+  minDriftMs: z.number().min(0).max(20000).default(2000),
+  /**
+   * Drift even when a window `frame.chrome` is composited around the video.
+   * Default false: the drift zooms the captured PAGE while the drawn browser
+   * chrome stays put, so the eye — locked on the static window edge and the
+   * sticky header — sees the page sliding inside its frame, i.e. a scroll
+   * glitch. Such scenes freeze instead unless you set this (issue #57).
+   */
+  driftInFrame: z.boolean().default(false),
+});
+export type HoldConfig = z.infer<typeof HoldSchema>;
+
+/**
+ * One cookie to seed into the recording profile before the take. Mirrors
+ * Playwright's cookie shape; `domain` + `path` (or `url`) place it.
+ */
+export const SeedCookieSchema = z.object({
+  name: z.string(),
+  value: z.string(),
+  /** Cookie domain, e.g. ".example.com" or "app.example.com". */
+  domain: z.string().optional(),
+  /** Cookie path. Default "/". */
+  path: z.string().optional(),
+  /** Alternative to domain+path: the URL the cookie belongs to. */
+  url: z.string().optional(),
+  /** Unix time in seconds; omit for a session cookie. */
+  expires: z.number().optional(),
+  httpOnly: z.boolean().optional(),
+  secure: z.boolean().optional(),
+  sameSite: z.enum(["Strict", "Lax", "None"]).optional(),
+});
+export type SeedCookie = z.infer<typeof SeedCookieSchema>;
+
+/**
+ * How the take is prepared BEFORE the first action — the answer to "the
+ * feature is behind a cookie gate / a preview token / a rotating fixture"
+ * without a hand-written Playwright seed script (issue #44). Everything here
+ * is opt-in; a storyboard without `setup` records exactly as before.
+ */
+export const SetupSchema = z.object({
+  /**
+   * Path (relative to the demo dir, or absolute) to a Playwright storageState
+   * JSON (`{cookies:[…], origins:[{origin, localStorage:[{name,value}]}]}`),
+   * e.g. one saved by `context.storageState({path})`. Its cookies are added
+   * to the recording profile and each origin's localStorage entries are set
+   * before the storyboard runs. CLI: `--storage-state <file>`.
+   */
+  storageState: z.string().optional(),
+  /** Cookies to add before the take. CLI: `--cookie name=value;domain=host` (repeatable). */
+  cookies: z.array(SeedCookieSchema).optional(),
+  /**
+   * Shell command run from the demo dir before EVERY take (record/probe/render),
+   * after the profile is resolved and before Chrome launches — e.g. a script
+   * that re-seeds a fixture, or patches the storyboard for whichever variant
+   * the app will serve today. Env: AIDEMO_DEMO_DIR, AIDEMO_STORYBOARD (the
+   * storyboard path — re-read after the hook, so edits are honored),
+   * AIDEMO_PROFILE (the Chrome user-data dir the take will use). A non-zero
+   * exit aborts the take.
+   */
+  preflight: z.string().optional(),
+  /**
+   * Acknowledge that the recording profile is deliberately seeded (a login,
+   * a cookie gate) and silence the carried-over-state warning for this
+   * storyboard. Implied when storageState/cookies are given. CLI:
+   * `--profile-seeded`.
+   */
+  expectState: z.boolean().optional(),
+});
+export type Setup = z.infer<typeof SetupSchema>;
+
 export const StoryboardSchema = z.object({
   title: z.string(),
   /**
@@ -429,6 +988,15 @@ export const StoryboardSchema = z.object({
    * fallback for non-English narration. Omit for English / to auto-detect.
    */
   language: z.string().optional(),
+  /**
+   * Product names, brands and jargon that Whisper reliably mis-hears — the
+   * transcript is what gets burned in, so "fitness.ee" coming back as
+   * "fitness topam" ships as a caption (issue #38). Listed here they are sent
+   * at the FRONT of the STT prompt, inside the window Whisper actually biases
+   * on, even when the script itself is long. Cheaper than `captions --offline`,
+   * which fixes spelling but gives up real word timings.
+   */
+  knownTerms: z.array(z.string()).optional(),
   /**
    * Declared template parameters: name → default value. Enables `{{name}}`
    * placeholders in any storyboard string (narration, action url, `type` text,
@@ -439,9 +1007,27 @@ export const StoryboardSchema = z.object({
    */
   params: z.record(z.string(), z.string()).optional(),
   targetLengthSeconds: z.number().optional(),
-  /** Recording viewport / video size. Default 1280x720. */
+  /**
+   * Recording viewport (CSS px) and, with `deviceScaleFactor`, the raw video
+   * size. Default 1280x720.
+   */
   video: z
-    .object({ width: z.number(), height: z.number() })
+    .object({
+      width: z.number(),
+      height: z.number(),
+      /**
+       * Record the video at `width*n x height*n` pixels while the PAGE still
+       * lays out at `width x height` CSS px — the standard fix for "the
+       * product is unreadable" (issue #51). A desktop app recorded at a
+       * 1920-px viewport renders its 1200-px content column tiny; record at
+       * 1280–1440 CSS px with `deviceScaleFactor: 2` instead and let
+       * `output.preset` scale the 2x raw down to 1080p: the UI is a third
+       * bigger on screen and stays crisp. Default 1 (unchanged output).
+       * Built-in (Playwright) capture only — native/OBS capture records real
+       * screen pixels.
+       */
+      deviceScaleFactor: z.number().min(1).max(3).optional(),
+    })
     .default({ width: 1280, height: 720 }),
   /** Named frames used by actions, mapping name -> iframe selector. */
   frames: z.record(z.string(), z.string()).default({}),
@@ -461,6 +1047,32 @@ export const StoryboardSchema = z.object({
   motionBlur: MotionBlurSchema.optional(),
   /** Compose-time cursor control (hide/resize post-hoc). Omit to bake the cursor. */
   cursor: CursorConfigSchema.optional(),
+  /** Pre-take preparation: cookies / storageState seeding, a preflight hook. Opt-in. */
+  setup: SetupSchema.optional(),
+  /** How compose fills narration that outlasts a scene's action (freeze | drift). Opt-in. */
+  hold: HoldSchema.optional(),
+  /**
+   * Trim un-annotated dead air: compose scans the take for spans where nothing
+   * on screen moves and treats them as idle (capped like `waitFor*` idle is),
+   * so a slow XHR or a long `pause` stops inflating the scene. Opt-in — omit
+   * for the old behavior, where only annotated waits count as idle. Pass an
+   * object to tune the threshold; per-scene `autoIdle` overrides it.
+   */
+  autoIdle: z.union([z.boolean(), AutoIdleSchema]).optional(),
+  /** Defaults for highlight/spotlight/callout overlays + click rings. Opt-in. */
+  attention: AttentionConfigSchema.optional(),
+  /** Produced-look frame: padding/background/radius/shadow/chrome. Opt-in. */
+  frame: FrameSchema.optional(),
+  /** Brand kit: logo watermark, accent, font. Opt-in. */
+  brand: BrandSchema.optional(),
+  /** Show a keystroke chip on every `press` (per-action `keystrokes` overrides). Opt-in. */
+  keystrokes: z.boolean().optional(),
+  /** Caption strip placement (bottom | top). Opt-in; per-scene `captions` overrides. */
+  captions: CaptionsConfigSchema.optional(),
+  /** Regions blurred at compose time throughout the demo. Opt-in. */
+  redact: z.array(RedactSchema).optional(),
+  /** Selectors hidden (visibility:hidden) at record time throughout the demo. Opt-in. */
+  hide: z.array(z.string()).optional(),
   scenes: z.array(SceneSchema).min(1),
 });
 export type Storyboard = z.infer<typeof StoryboardSchema>;
@@ -517,6 +1129,63 @@ export const CursorSampleSchema = z.object({
 });
 export type CursorSample = z.infer<typeof CursorSampleSchema>;
 
+/**
+ * What one storyboard action actually did during the take: wall-clock window,
+ * outcome, retries, and anything worth a second look (failed requests seen in
+ * its window, an optional skip). The per-action twin of the compose report —
+ * an agent reads this to see which action ate the time or was skipped without
+ * regex-mining the log. Default [] keeps older timelines valid.
+ */
+export const TimelineActionSchema = z.object({
+  /** 0-based index in the scene's actions[]. */
+  index: z.number(),
+  op: z.string(),
+  /** Resolved target (named→selector, frame-prefixed) / goto URL, when any. */
+  target: z.string().optional(),
+  startMs: z.number(),
+  endMs: z.number(),
+  ok: z.boolean(),
+  /** An `optional` action whose target never appeared / that failed. */
+  skipped: z.boolean().optional(),
+  /** Extra attempts consumed before success (from `retry`). */
+  retries: z.number().optional(),
+  warnings: z.array(z.string()).optional(),
+});
+export type TimelineAction = z.infer<typeof TimelineActionSchema>;
+
+/** A measured attention beat (highlight/spotlight/callout) — viewport CSS px. */
+export const AttentionEventSchema = z.object({
+  tMs: z.number(),
+  kind: z.enum(["highlight", "spotlight", "callout"]),
+  x: z.number(),
+  y: z.number(),
+  w: z.number(),
+  h: z.number(),
+  holdMs: z.number(),
+  text: z.string().optional(),
+  placement: z.string().optional(),
+  dimTo: z.number().optional(),
+  padding: z.number().optional(),
+  style: AttentionStyleSchema.optional(),
+});
+export type AttentionEvent = z.infer<typeof AttentionEventSchema>;
+
+/** A key press to show as a chip (already prettified, e.g. "⌘ K", "Enter"). */
+export const KeyEventSchema = z.object({ tMs: z.number(), keys: z.string() });
+export type KeyEvent = z.infer<typeof KeyEventSchema>;
+
+/** A region blurred at compose time over [startMs, endMs] — viewport CSS px. */
+export const RedactSpanSchema = z.object({
+  startMs: z.number(),
+  endMs: z.number(),
+  x: z.number(),
+  y: z.number(),
+  w: z.number(),
+  h: z.number(),
+  blur: z.number(),
+});
+export type RedactSpan = z.infer<typeof RedactSpanSchema>;
+
 export const TimelineSceneSchema = z.object({
   id: z.string(),
   startMs: z.number(),
@@ -525,6 +1194,21 @@ export const TimelineSceneSchema = z.object({
   focusEvents: z.array(FocusEventSchema).default([]),
   stillEvents: z.array(StillEventSchema).default([]),
   cursorSamples: z.array(CursorSampleSchema).default([]),
+  actions: z.array(TimelineActionSchema).default([]),
+  attentionEvents: z.array(AttentionEventSchema).default([]),
+  keyEvents: z.array(KeyEventSchema).default([]),
+  redactSpans: z.array(RedactSpanSchema).default([]),
+  /** Anchored actions: when the beat happened in the raw take (scene-relative like tMs elsewhere). */
+  anchorEvents: z.array(z.object({ name: z.string(), tMs: z.number(), action: z.number() })).default([]),
+  /**
+   * Resume (`record --from-scene`): scenes reused from an earlier take name the
+   * raw file they live in (relative to the demo dir) and that take's lead-in;
+   * absent = the current take (`recordings/raw.*` + the timeline's leadInMs).
+   */
+  source: z.string().optional(),
+  leadInMs: z.number().optional(),
+  /** Identity of the scene's action-spec at record time — resume reuses a scene only when it matches. */
+  hash: z.string().optional(),
 });
 export type TimelineScene = z.infer<typeof TimelineSceneSchema>;
 
@@ -539,6 +1223,88 @@ export const TimelineSchema = z.object({
 });
 export type Timeline = z.infer<typeof TimelineSchema>;
 
+
+// ---------------------------------------------------------------------------
+// Compose report — written to output/report.json by every compose. The
+// structured twin of the compose log: per-scene retime facts (how much was
+// stretched, held, trimmed) plus machine-readable warnings, so an agent can
+// judge a take without regex-mining logTail (issue #40's 28-scene log
+// overflowed the 40-line tail; the freeze-hold dominance was invisible).
+// ---------------------------------------------------------------------------
+
+export const ComposeWarningSchema = z.object({
+  /** Stable code: scene-freeze | overrun-trim | blank-tail | stale-captions |
+   *  focus-dropped | cursor-missing | scene-no-narration */
+  code: z.string(),
+  scene: z.string().optional(),
+  message: z.string(),
+});
+export type ComposeWarning = z.infer<typeof ComposeWarningSchema>;
+
+export const ComposeSceneReportSchema = z.object({
+  id: z.string(),
+  /** Recorded (kept, non-idle) ms feeding this scene. */
+  srcMs: z.number(),
+  /** Narration + gap ms the scene had to fill. */
+  targetMs: z.number(),
+  /** Time-stretch factor applied (0.5 … 1.6). */
+  factor: z.number(),
+  /** Ms of hold (frozen / drifting last frame) appended after the stretch. */
+  holdMs: z.number(),
+  /** holdMs / targetMs — the share of the scene that is a held frame. */
+  holdPct: z.number(),
+  /** Ms of recorded action cut from the tail because it overran the narration. */
+  tailTrimMs: z.number(),
+  /** Ms of solid-color tail dropped before holding (white pre-paint). */
+  blankTrimMs: z.number(),
+  /** Ms of motionless footage `autoIdle` marked trimmable in this scene (0 when off). */
+  autoIdleMs: z.number().default(0),
+  /** Kept spans the scene was cut from (idle spans trimmed between them). */
+  spans: z.number(),
+  /** Focus points (zoom) this scene contributed. */
+  focusEvents: z.number(),
+  /** Narration anchors: where the beat was asked to land vs where it did (content ms, scene-relative). */
+  anchors: z
+    .array(
+      z.object({
+        name: z.string(),
+        targetMs: z.number(),
+        landedMs: z.number(),
+        /** landedMs − targetMs; |offMs| > 150 raises `anchor-unreachable`. */
+        offMs: z.number(),
+      })
+    )
+    .optional(),
+});
+export type ComposeSceneReport = z.infer<typeof ComposeSceneReportSchema>;
+
+export const ComposeReportSchema = z.object({
+  output: z.string(),
+  /** Final video length, ms. */
+  durationMs: z.number(),
+  scenes: z.array(ComposeSceneReportSchema),
+  zoom: z.object({ focusTotal: z.number(), focusDropped: z.number() }),
+  cursorPoints: z.number(),
+  captions: z.object({ cues: z.number(), passes: z.number() }),
+  /** Attention overlays drawn (highlight/spotlight/callout), key chips, click rings, redact spans. */
+  attention: z
+    .object({
+      events: z.number(),
+      keys: z.number(),
+      clicks: z.number(),
+      redactSpans: z.number(),
+      captionsFlipped: z.number(),
+    })
+    .optional(),
+  hold: z.string(),
+  /** output/poster.png when `output.poster` is set. */
+  poster: z.string().optional(),
+  /** Ms of blank (contentless) video at the very start of the final cut. */
+  blankOpenMs: z.number().optional(),
+  warnings: z.array(ComposeWarningSchema),
+});
+export type ComposeReport = z.infer<typeof ComposeReportSchema>;
+
 // ---------------------------------------------------------------------------
 // Voice manifest — emitted by the voice step. compose uses per-scene durations
 // as the target length for each scene's video segment.
@@ -600,9 +1366,10 @@ export const CaptionsManifestSchema = z.object({
     maxCueMs: z.number(),
   }),
   /**
-   * Per-scene inputs + reusable scene-relative word timings (offline path only).
-   * Enables per-scene reuse: only a scene whose narration/duration changed is
-   * re-derived; the rest keep their stored words.
+   * Per-scene inputs + reusable scene-relative word timings. Offline path:
+   * enables per-scene reuse (only a changed scene is re-derived). STT path:
+   * the transcript split per scene, so compose can place narration anchors
+   * on the word that was actually spoken.
    */
   scenes: z
     .array(
@@ -642,6 +1409,13 @@ export const ProbeActionOutcomeSchema = z.object({
   ms: z.number().optional(),
   dy: z.number().optional(),
   label: z.string().optional(),
+  /**
+   * The action is marked `optional` in the storyboard. Optional actions always
+   * record ok:true and no `found`: their real outcome is environment-dependent
+   * by design (that's what optional is for), so it's normalized out of the
+   * golden projection to keep it deterministic across runs.
+   */
+  optional: z.boolean().optional(),
 });
 export type ProbeActionOutcome = z.infer<typeof ProbeActionOutcomeSchema>;