@plaintake/scenario 1.9.0 → 1.12.0

package/dist/index.js

@@ -443,7 +443,32 @@ var HighlightRectSchema = z5.object({
   height: z5.number().int().positive(),
   startMs: z5.number().int().nonnegative(),
   endMs: z5.number().int().positive(),
-  label: z5.string().min(1).optional()
+  label: z5.string().min(1).optional(),
+  /**
+   * The rect the spotlight glides *from*, when this window's cutout should animate rather
+   * than cut straight to the held `x`/`y`/`width`/`height` — the pre-reveal position a
+   * step's `target` measured before a scroll-causing `reveal` settled it into place.
+   * Present only together with `settleMs`: a glide needs both where it starts and when it
+   * finishes, and one without the other cannot be drawn.
+   *
+   * Absent means exactly today's behaviour — a single static rect held for the window's
+   * whole span — so every plan frozen before this field existed, and every window a future
+   * derivation decides not to glide, is unaffected by construction.
+   */
+  from: z5.object({
+    x: z5.number().int().min(0),
+    y: z5.number().int().min(0),
+    width: z5.number().int().positive(),
+    height: z5.number().int().positive()
+  }).optional(),
+  /**
+   * The absolute video-ms at which the glide from `from` completes and the spotlight
+   * settles into the held rect — not a duration, the same convention `startMs`/`endMs`
+   * and `CameraShot.enterMs`/`holdFromMs` already carry. Strictly after `startMs` (there
+   * has to be real time left to glide across) and no later than `endMs` (the window
+   * cannot settle after it has already closed).
+   */
+  settleMs: z5.number().int().positive().optional()
 }).refine(({ x, y, width, height }) => x + width <= 1920 && y + height <= 1080, {
   // Unlike CameraShotSchema's crop window, a highlight rect is drawn by libass, not fed to
   // `crop` — there is no yuv420p even-pixel rule to enforce — but it still has to fit the
@@ -451,6 +476,27 @@ var HighlightRectSchema = z5.object({
   // meant to sit inside.
   message: "the rect must stay inside the 1920x1080 frame",
   path: ["x"]
+}).refine(({ from, settleMs }) => from === void 0 === (settleMs === void 0), {
+  // A glide needs both where it starts (`from`) and when it finishes (`settleMs`) — one
+  // without the other cannot be drawn, so the pair is refused rather than tolerated as a
+  // half-declared capability.
+  message: "from and settleMs must be present together or both absent",
+  path: ["from"]
+}).refine(
+  ({ from }) => from === void 0 || from.x + from.width <= 1920 && from.y + from.height <= 1080,
+  {
+    // The same 1920x1080 containment the held rect enforces above, applied to the rect the
+    // spotlight glides from — an off-canvas starting point is no more drawable than an
+    // off-canvas held one.
+    message: "from must stay inside the 1920x1080 frame",
+    path: ["from"]
+  }
+).refine(({ startMs, endMs, settleMs }) => settleMs === void 0 || settleMs > startMs && settleMs <= endMs, {
+  // settleMs is absolute video-ms, like startMs/endMs themselves — the glide needs real
+  // room to run (strictly after startMs) and cannot settle after its own window has
+  // already closed (no later than endMs).
+  message: "settleMs must be strictly after startMs and no later than endMs",
+  path: ["settleMs"]
 });
 var HighlightSchema = z5.object({
   assPath: z5.literal("captions/highlight.ass"),
@@ -543,6 +589,7 @@ var SpeechSchema = z5.object({
   message: "engine must be recorded whenever any clip was synthesised",
   path: ["engine"]
 });
+var ThemeSchema = z5.object({ accentColor: HEX_COLOUR });
 var RENDER_PLAN_SCHEMA = "agent-demo.render/v1";
 var RenderPlanSchema = z5.object({
   schema: z5.literal(RENDER_PLAN_SCHEMA),
@@ -730,6 +777,31 @@ var RenderPlanSchema = z5.object({
   camera: CameraSchema.optional(),
   highlight: HighlightSchema.optional(),
   speech: SpeechSchema.optional(),
+  /**
+   * The branding decision, resolved once from the licence and configuration at run time
+   * and frozen whole — the accent the cursor's fill, its click-ripple ring and the
+   * highlight label's text all draw. See `ThemeSchema`.
+   *
+   * Optional and **never defaulted**. The plan's own JSON is a weaker claim than the
+   * render — the schema doc above records how a Zod `.default()` materialises on parse,
+   * so `stableStringify` writes the field into `render/render-plan.json` and diverges the
+   * committed golden plan, which is what `style`'s defaults already did once. A default
+   * here would do it again on every parse; absent means off, and the object appears only
+   * when a theme was actually resolved.
+   *
+   * Top-level — a sibling of `intro`/`outro`/`cursor`/`highlight`, not a key inside one
+   * of them — so `recutPlan`'s `{...plan}` spread carries it through `--aspect` re-cuts
+   * unchanged; a nested key would need explicit handling there.
+   *
+   * The plan is not `.strict()`, so an older binary strips a `theme` it has never heard
+   * of — but a plain re-render is unaffected by that: `renderBundle` executes the frozen
+   * themed `cursor.ass`/`highlight.ass` verbatim and never regenerates them, exactly as
+   * an older build ignoring `speech` still muxes the frozen WAV. The hardcoded colours
+   * return only where derived files are *redrawn* — a fresh freeze, or a `render
+   * --aspect` re-cut, whose `writeCaptions(recut)` regenerates the tracks from a plan the
+   * older binary's own re-parse has stripped `theme` out of.
+   */
+  theme: ThemeSchema.optional(),
   /**
    * The capture timeline cut into windows — of a genuine multi-actor cast, of an implicit
    * single actor pausing for explain cut-aways, or both at once. `segments` is the one

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

@@ -296,9 +296,11 @@ export declare const TRANSITION_CARD_DEFAULT_MS = 3000;
  * to be a pure function of the plan, so the rect a step measured has to survive plan freeze
  * as a rect, not merely as a decision to draw one.
  *
- * `startMs`/`endMs` bound the whole step, not a retimed lead/rest/glide the way a cursor
- * point is — a spotlight has no motion to choreograph, so unlike `CursorPointSchema` there is
- * nothing here to pull earlier or hold open.
+ * `startMs`/`endMs` carry a window the derivation already retimed, the way a cursor point's
+ * do: a click's brackets the press — opening when the pointer parks and closing as the click
+ * ripple ends — while a continuous action's spans its whole step. The times are frozen as
+ * computed, so unlike `CursorPointSchema` (whose `rippleMs` the emitter re-derives fades
+ * around) there is no further choreography left for the render to do.
  *
  * `label` is the optional callout text a scenario may attach (`highlight: { label: '...' }`).
  * Absent means the spotlight alone, exactly what `highlight: true` (no object) asks for.
@@ -312,6 +314,13 @@ export declare const HighlightRectSchema: z.ZodObject<{
     startMs: z.ZodNumber;
     endMs: z.ZodNumber;
     label: z.ZodOptional<z.ZodString>;
+    from: z.ZodOptional<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>>;
+    settleMs: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 /**
  * The highlight track. A rect **list**, ordered and non-overlapping on the same discipline
@@ -330,6 +339,13 @@ export declare const HighlightSchema: z.ZodObject<{
         startMs: z.ZodNumber;
         endMs: z.ZodNumber;
         label: z.ZodOptional<z.ZodString>;
+        from: z.ZodOptional<z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>>;
+        settleMs: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type Highlight = z.infer<typeof HighlightSchema>;
@@ -457,6 +473,54 @@ export type IntroInput = Omit<Intro, 'assPath'>;
  * position in the array against the schema's own `captions/turn-[0-9]+\.ass` family.
  */
 export type TransitionCardInput = Omit<TransitionCard, 'assPath'>;
+/**
+ * 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
+ * the highlight should never disagree about the brand — the same "one block, one decision"
+ * shape as every other optional capability on the plan.
+ *
+ * Present only when a theme actually resolved — Pro tier, branding enabled, at least one
+ * colour named. Absent means every hardcoded colour the emitters already draw, so
+ * an unbranded run's `cursor.ass`/`highlight.ass` are exactly what they always were.
+ * Caption colours deliberately do not live here: `RenderPlanSchema.style` already carries
+ * `textColor`/`outlineColor`/`boxColor` as the single source of `captions/captions.ass`,
+ * and theming captions is a change to what gets frozen into those, not a second place a
+ * colour can hide.
+ *
+ * `accentColor` is `HEX_COLOUR` for the reason every plan colour is: the value reaches
+ * `assColour` and from there an ASS override tag, and `#RRGGBB` admits no ASS
+ * metacharacter. It is stored in the form the author wrote and converted to `&HAABBGGRR`
+ * only at emission, so the bundle shows the colour, not its encoding.
+ *
+ * Like the inputs above, this is the decision as the application layer supplies it — but
+ * it is the narrow end of a wider input: `buildRenderPlan` takes the four-field
+ * `ThemeInput` below and freezes only the accent here, because the caption colours have
+ * somewhere else to go.
+ */
+export declare const ThemeSchema: z.ZodObject<{
+    accentColor: z.ZodString;
+}, z.core.$strip>;
+export type Theme = z.infer<typeof ThemeSchema>;
+/**
+ * The theme decision as the application layer supplies it — all four colours a licence can
+ * resolve, in the same shape `@plaintake/license`'s `resolveTheme` returns, exactly as
+ * `OutroInput`/`IntroInput` are the shapes its other resolvers return. Only the fields the
+ * user actually configured appear; each absent field keeps the hardcoded default at the
+ * freeze, so recolouring `accentColor` alone is a complete theme.
+ *
+ * Wider than `ThemeSchema` on purpose. The plan-level block carries only `accentColor`
+ * because the three caption colours freeze into `RenderPlanSchema.style` — the single
+ * source `captions.ass` already reads — while the accent has no style field to freeze
+ * into and needs the plan key. A theme with no accent therefore freezes no `theme` key at
+ * all: the schema requires one, and defaulting it would recolour cursor surfaces the
+ * author never asked about.
+ */
+export type ThemeInput = {
+    accentColor?: string | undefined;
+    captionTextColor?: string | undefined;
+    captionOutlineColor?: string | undefined;
+    captionBoxColor?: string | undefined;
+};
 /**
  * The one value a plan's `schema` field ever holds.
  *
@@ -638,6 +702,13 @@ export declare const RenderPlanSchema: z.ZodObject<{
             startMs: z.ZodNumber;
             endMs: z.ZodNumber;
             label: z.ZodOptional<z.ZodString>;
+            from: z.ZodOptional<z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+            }, z.core.$strip>>;
+            settleMs: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
     speech: z.ZodOptional<z.ZodObject<{
@@ -663,6 +734,9 @@ export declare const RenderPlanSchema: z.ZodObject<{
             voice: z.ZodString;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
+    theme: z.ZodOptional<z.ZodObject<{
+        accentColor: z.ZodString;
+    }, z.core.$strip>>;
     actors: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         label: z.ZodString;

package/dist/types.d.ts

@@ -49,6 +49,63 @@ export type DemoStep = {
     voice?: string;
     /** Extra presentation hold after the action completes, in whole milliseconds. */
     holdMs?: number;
+    /**
+     * Scrolled into view after `run()` completes and before the hold — the opposite ordering
+     * from `target`, which is measured *before* `run()`. Exists for content the action itself
+     * reveals below the fold (a response panel that renders after a click, say): without it,
+     * an author either remembers to append a separate `Actor.scroll()` step for what is
+     * conceptually part of this one action, or the recording holds on an off-screen result.
+     *
+     * Independent of `target`: the element acted on and the element revealed are often not
+     * the same one, and a step may declare `reveal` with none at all.
+     *
+     * Not best-effort like `target`'s measurement — a `reveal` locator that never appears
+     * fails the step normally, the same as `run()` itself or `Actor.scroll`'s own unguarded
+     * `scrollIntoViewIfNeeded()`, because unlike `target` (inert metadata) this performs a
+     * real action with a real effect on what capture sees.
+     *
+     * `target` (if declared) is re-measured, best-effort, once this scroll settles: the
+     * settled rect and a real "revealed at" timestamp both ride on `step.finish`, alongside
+     * the pre-scroll rect `step.start` already carried. Camera zoom and `highlight` both
+     * prefer that settled rect over the stale one once it is written, so declaring the same
+     * locator as both `target` and `reveal` is the supported way to have them frame the
+     * revealed content rather than the position it was scrolled away from —
+     * `Actor.scroll`'s own locator form takes the mirror-image approach of scrolling in
+     * `prepare`, *before* measuring, for the same reason (see its comment); `reveal` cannot
+     * do that since the scroll it causes is itself a consequence of `run()`. Camera zoom
+     * additionally anchors a shot's settle time to the *later* of the click and the reveal
+     * completing, rather than the click alone, so a `run()` that keeps the page busy after
+     * the click (rendering a response panel, say) does not leave the camera's pan finished
+     * before the captured frames actually show the revealed content. That push has a limit,
+     * though: if this step's reveal is slow AND the next step follows in quick succession,
+     * the settle time is pulled earlier so it cannot land after the next step's own arrival —
+     * preserving step order rather than exactly matching when the reveal finished, diagnosed
+     * with `camera.compressed` when it binds.
+     *
+     * The scroll itself is a real, live glide (`smoothScrollIntoView` in `recorder-playwright`),
+     * not an instant jump — a genuine rAF-driven ease over the capture's own variable-frame-rate
+     * screencast, the one piece of on-screen motion in a plaintake recording that is not
+     * synthesised at render time from frozen numbers. See that function's doc comment for why a
+     * live capture can show it without touching the byte-reproducibility guarantee, which has
+     * only ever covered re-rendering an already-frozen bundle.
+     *
+     * Two narrower caveats remain, both because they cannot be *re*-measured the way `target`
+     * is: (a) the cursor arrow itself still marks the pre-scroll click position and does not
+     * chase the settled rect, so a large reveal-scroll can leave the arrow outside a
+     * tightly-zoomed shot for the rest of the hold; (b) on a `click`-action step specifically,
+     * `highlight`'s spotlight window is a brief pulse bracketing the click, with no structural
+     * room for a glide to read as intentional motion rather than a timing glitch — it still
+     * settles on the target rect instantly, a property of that window's own timing rather than
+     * a gap left to close later. Non-click actions (`type`/`point`/`scroll`) are different:
+     * their window already spans to the step's own end, so when the pre-reveal and settled
+     * rects genuinely differ, the spotlight glides between them at render time — timed to when
+     * the reveal actually finished, not the window's own edges — falling back to the same
+     * instant settle when there isn't genuinely enough of that window left to glide across,
+     * or when the pre-reveal position itself was never usable (no area, or entirely off-frame).
+     *
+     * Also: if `run()` throws, this scroll never executes — the step fails before reaching it.
+     */
+    reveal?: Locator;
     run: () => Promise<unknown>;
 };
 export type DemoAssertion = {
@@ -304,8 +361,25 @@ export type ActorStepMeta = {
     highlight?: boolean | {
         label?: string;
     };
+    /** See `DemoStep.reveal`. */
+    reveal?: Locator;
     /** See `DemoStep.voice` — one verb-call override, ahead of this actor's own `voice`. */
     voice?: string;
+    /**
+     * Alignment `Actor.scroll`'s locator form settles the viewport on, mirroring
+     * `Element.scrollIntoView`'s own `block`. Only `scroll` reads this — every other verb
+     * has no notion of where the viewport ends up after it runs, so this is silently ignored
+     * elsewhere. Absent means `'center'`, the same default a bare `scrollIntoView()` call has.
+     */
+    block?: 'start' | 'center' | 'end' | 'nearest';
+    /**
+     * Minimum gap, in pixels, `Actor.scroll`'s locator form leaves between the target and the
+     * edge `block` settles it against — breathing room so the target doesn't land flush
+     * against the viewport edge. Only meaningful alongside `block: 'start'` or `'end'`, which
+     * name an edge; ignored for `'center'`/`'nearest'` and by every verb but `scroll`. Absent
+     * means 0, flush with the edge.
+     */
+    paddingPx?: number;
 };
 /**
  * A named participant in a multi-actor demo: its own Playwright `BrowserContext`, its own

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plaintake/scenario",
-  "version": "1.9.0",
+  "version": "1.12.0",
   "description": "Authoring SDK for PlainTake demo scenarios: defineDemo and the scenario DSL types. Install for editor autocomplete; the PlainTake binary ships a runtime fallback.",
   "license": "MIT",
   "type": "module",