@plaintake/scenario 1.10.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"),

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

@@ -314,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
@@ -332,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>;
@@ -688,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<{

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.10.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",