@mrkt_frwd/reel 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joe Asare
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,17 @@
+# @mrkt_frwd/reel
+
+Drive a real browser from a declarative script and record it.
+
+```bash
+npx reel recordings/studio-tour/script.json --dry-run
+npx reel recordings/studio-tour/script.json --deterministic
+```
+
+The script is data, not code. `--dry-run` validates it and resolves every
+selector in seconds, so a capture never dies four minutes in on a renamed one.
+`--deterministic` runs a fixed clock, so the frames do not depend on how long a
+frame cost to draw.
+
+Needs Chromium and ffmpeg — the only engine here that is not zero-dependency.
+
+MIT.

package/docs/getting-started.md

@@ -0,0 +1,280 @@
+# Recording
+
+Video of the product being used — multi-page flows, real interactions, WebGL captured as
+painted, with an optional deterministic mode whose output does not depend on machine speed.
+
+```bash
+npm run record:dry   -- recordings/studio-tour/script.json  # validate, resolve selectors
+npm run record       -- recordings/studio-tour/script.json  # realtime capture
+npm run record:exact -- recordings/studio-tour/script.json  # deterministic capture
+npm run record       -- <script> --formats mp4,gif,vertical
+npm run record       -- <script> --live https://joeasare.com
+npm run record       -- <script> --keep-frames              # keep frames for inspection
+```
+
+Set `"capture": "deterministic"` in the script to make it the default for that recording.
+
+`npm run record:test` validates every script in `recordings/` and runs inside `npm run gates`.
+
+## Why a script file rather than browser code
+
+A recording is `recordings/<name>/script.json`. It is declarative because more than one
+agent touches it: a director writes the shots and their intent, an interaction developer
+resolves the selectors and timings, a critic judges the frames against the stated intent.
+A number in a JSON file can be diffed, reviewed and adjusted; a hundred lines of
+imperative Playwright cannot be critiqued usefully by anyone who did not write it.
+
+`name` must be a lowercase slug matching its directory. **Every shot needs an `intent`** —
+the validator rejects a shot without one, because it is what a critique is measured
+against.
+
+## Architecture
+
+| file | job |
+|---|---|
+| `packages/reel/src/cli.mjs` | entry point; validate, capture, encode, write `capture.json` |
+| `packages/reel/src/runner.mjs` | owns the browser for the whole story; launch flags; one context |
+| `packages/reel/src/actions.mjs` | the verb vocabulary, all eased |
+| `packages/reel/src/capture.mjs` | CDP screencast to timestamped frames |
+| `packages/reel/src/assemble.mjs` | ffmpeg: master MP4, 9:16 crop, GIF, critic samples |
+| `packages/reel/src/cursor.mjs` | synthetic pointer, injected before page scripts |
+| `packages/reel/src/clock.mjs` | the virtual clock shim for deterministic capture |
+| `packages/reel/src/timeline.mjs` | the two timing drivers behind one `wait`/`animate` seam |
+| `packages/reel/src/critic.mjs` | judges a finished recording from its frames |
+| `packages/reel/src/edit.mjs` | edit decision lists — resolve segments against a capture |
+| `packages/reel/src/edit-cli.mjs` | `npm run record:edit` |
+| `packages/reel/src/caption.mjs` | captions rendered in Chromium, in studio typography |
+| `packages/reel/src/frame-grid.mjs` | downsampled luminance grids for frame comparison |
+| `packages/reel/src/schema.mjs` | validation and the dry run |
+| `packages/reel/src/server.mjs` | static server honouring `cleanUrls`, with commerce endpoints stubbed |
+
+**One browser context for the entire story.** That is what makes a multi-page narrative
+work: cookies, `localStorage` and in-page state survive navigation, so a later shot can
+show a state an earlier shot created. A recorder that opens a page per shot can only
+produce disconnected clips.
+
+**The cursor is drawn, not real.** The OS pointer is not part of what the compositor
+paints, so a screencast of a click shows the effect and never the cause — fields appear to
+fill themselves. `cursor.mjs` injects a pointer that follows real `pointermove` events and
+draws a ripple on click. It is `pointer-events:none` and tagged `data-recording-chrome`, so
+it cannot alter what it documents.
+
+**Frames carry real timestamps.** The screencast delivers a frame when the compositor
+paints one, which is irregular — a heavy Three.js scene may give 8fps for a second and
+30fps the next. Every frame's true timestamp goes into an ffmpeg concat manifest and the
+encode resamples to a constant rate. Treating irregular frames as evenly spaced is what
+makes naive WebGL captures appear to speed up and slow down.
+
+## Two capture modes
+
+### `realtime` (default)
+
+The compositor paints when it can and every frame carries a real timestamp. Fast to run —
+roughly wall-clock — but the output is bound to machine speed:
+
+| content | measured motion fps |
+|---|---|
+| DOM pages, scrolling and typing | 20–23 |
+| Three.js under SwiftShader | ~10 |
+
+No launch flag lifts this. `--disable-frame-rate-limit` and `--disable-gpu-vsync` were
+measured and made it **worse** (15.9fps), so they are deliberately absent. Dropping JPEG
+quality from 92 to 35 bought about 3fps, which is why the default sits at 80.
+
+There is a second, larger problem that is easy to miss: **realtime output does not match
+the duration the script asks for.** Driver round trips, paint waits and per-keystroke IPC
+all add to every action, and they compound. The four-shot `studio-tour` declares about 21
+seconds and produced **87.5 seconds** of video. A director writing a 30-second social clip
+was getting two minutes.
+
+### `deterministic`
+
+Page time is replaced by a virtual clock (`clock.mjs`, installed before any page script
+runs). The recorder advances it exactly one frame, runs the timers and animation callbacks
+that became due, screenshots, and repeats.
+
+| | realtime | deterministic |
+|---|---|---|
+| frame rate | 10–23, varies | exactly `fps` |
+| duration vs script | ~4x over | matches |
+| same script twice | different | **byte-identical** |
+| wall-clock cost | ~1x | ~6x |
+
+Measured on `studio-tour`: 515 frames at exactly 24fps, 21.5s of video from a script
+declaring ~21s, 152ms of real work per frame, and two runs producing identical frame
+checksums. The 3D shot has 50 unique frames out of 50 — the render loop is genuinely being
+driven, not frozen.
+
+**Why a JS shim rather than CDP `Emulation.setVirtualTimePolicy`:** virtual time freezes
+the whole renderer, so a page awaiting a real network response hangs until the policy is
+nursed through pending fetches. The shim replaces only the *timing* APIs, so network,
+decoding and layout continue on real time and a page that fetches mid-recording simply
+works.
+
+**What it cannot virtualise:** `<video>`/`<audio>` playback; CSS animations are *sampled*
+rather than stepped (paused, with `currentTime` set each frame — exact for time-based
+animations, wrong for anything keyed to `transitionend` timing); `new Date()`, whose
+constructor is deliberately left alone because replacing it breaks date maths in harder-to-
+see ways; and worker or iframe timers, which have their own global scopes.
+
+**Reproducibility has a sharp edge.** Anything non-deterministic in an action breaks it.
+Keystroke jitter is seeded (`resetJitter`, xorshift32) and the gate fails on `Math.random`
+or a direct `page.waitForTimeout` anywhere in `actions.mjs` — either would silently opt out
+of the virtual clock while still looking correct in realtime mode.
+
+### Which to use
+
+Realtime for iterating on a script: it runs at 1x and you are looking at composition, not
+smoothness. Deterministic for anything anyone else will see.
+
+## The critic
+
+Every recording is judged from its own frames and writes `critique.json` beside the video.
+No model call — it runs on pixels and the capture timeline, so it works with no egress and
+gives the same answer twice.
+
+```
+✓ critique 100/100 — 0 finding(s)
+```
+
+| axis | weight | catches |
+|---|---|---|
+| `deadFrames` | 0.30 | a shot that rendered nothing — blank or a uniform wash |
+| `frozenMotion` | 0.30 | a shot claiming movement whose frames never change |
+| `continuity` | 0.15 | an isolated jump inside a shot, where the eye reads a cut |
+| `pacing` | 0.15 | a shot too short for anyone to read |
+| `ending` | 0.10 | a clip that lands mid-motion instead of on a held state |
+
+`frozenMotion` is the one worth having. A WebGL scene that never animated produces frames
+that each look perfectly correct, so a reviewer flicking through stills cannot see it —
+only comparing consecutive frames can. Findings carry a timecode and the shot id, and a
+frozen-shot finding quotes the shot's stated intent back, which is what the required
+`intent` field is for.
+
+Add `--gate` to make the verdict decide the exit code, for a loop that should stop on a
+bad take rather than quietly producing one.
+
+**The plan for this phase was wrong and was corrected.** It said to point `design-eval`'s
+still-image rubric at the samples. That rubric's axes are `subjectFirst`, `framing`,
+`geometryCredibility` and `materials` — product-photography measures. A frame of someone
+filling in a form has no subject on a background and no material response, so those axes
+would have scored noise and dressed it in a calibrated-looking number. What carried over
+is the *shape*: measured axes, blockers separated from warnings, and a `skip` status that
+renormalises rather than scoring a default.
+
+### Two things it got wrong before it got them right
+
+**Comparing luminance aggregates could not see movement.** The first version diffed
+`imageStats`'s mean, spread and occupancy. A pure translation leaves all three unchanged,
+so a scrolling repeated pattern — or a 3D object rotating under constant light — measured
+as perfectly still, and the critic reported moving shots as frozen. It now compares 16x16
+downsampled luminance grids (`frame-grid.mjs`), which see position. Coarse on purpose:
+a pixel-exact comparison would read compression noise as constant motion.
+
+**Large change is not the same as discontinuity.** Scrolling the landing page from its
+dark hero into the cream section below produces enormous frame-to-frame deltas, and every
+one was reported as a cut. A jump is *isolated* — one large change among small ones —
+so it must also stand clear of its local median. Separately, the analysis strip is coarser
+than a shot boundary, so the delta straddling a `goto` was being filed under the shot it
+landed in; both ends of a shot are now treated as legitimate cuts.
+
+Both survive as regression cases in `tools/test-record-critic.mjs`, alongside a fixture
+for every axis. That file lives apart from `test-record.mjs` because it needs a pixel
+backend, which CI installs only for the `tests` job — and it **fails rather than skips**
+when the backend is missing, since a silently skipped gate is how one stops gating.
+
+## Edits — cutting a short piece from a master
+
+A social clip is not a different recording, it is a different *reading* of one. Cutting
+from the master keeps the two consistent, costs seconds rather than minutes, and means the
+30-second version cannot drift from the two-minute version it claims to summarise.
+
+```bash
+npm run record:edit -- recordings/studio-tour/social.edit.json --check   # resolve only
+npm run record:edit -- recordings/studio-tour/social.edit.json
+```
+
+```json
+{
+  "name": "studio-tour-social",
+  "source": "studio-tour",
+  "aspect": "9:16",
+  "budgetSec": 30,
+  "segments": [
+    { "shot": "start", "from": 0.6, "to": 6.5, "fit": "contain",
+      "kicker": "Brand it live", "caption": "Your palette, applied as you type." },
+    { "shot": "webgl", "from": 2.0, "focusX": 0.62,
+      "kicker": "Real WebGL", "caption": "Live 3D — not a video of it." }
+  ]
+}
+```
+
+Segments address the master **by shot id**, resolved against the timeline in
+`capture.json`, so an edit survives the script being re-timed — shots move, the edit still
+points at the right material. `from`/`to` alongside a shot are offsets *within* it, which
+is how a director thinks about trimming: "the last two seconds of the orbit", not "second
+19.6 of the file". An edit naming a shot that no longer exists is refused rather than cut
+from zero.
+
+| field | |
+|---|---|
+| `aspect` | `16:9` · `9:16` · `1:1` |
+| `fit` | `cover` crops to fill (default) · `contain` letterboxes on the studio ground |
+| `focusX` | 0–1, where a `cover` crop sits. Per segment, falling back to the edit |
+| `speed` | 0.25–4, retimes a segment |
+| `budgetSec` | reported when exceeded, never enforced |
+| `caption` · `kicker` | burned in, in the studio's own typefaces |
+
+`budgetSec` advises rather than trimming: silently retiming a cut to hit a number changes
+the pacing the director chose, and pacing is the whole point of a short format.
+
+### Captions are rendered by Chromium
+
+The obvious route is ffmpeg's `drawtext`. It is not available — the bundled `ffmpeg-static`
+reports `--enable-libfreetype` but ships **no `drawtext` filter**, leaving only libass,
+which renders in whatever face fontconfig finds on the machine. A caption that is one
+typeface locally and another in CI is not a caption, it is a defect that appears only in
+the deliverable.
+
+So captions are rendered by the browser the recorder already launches, using the studio's
+own `tokens.css`, and overlaid as transparent PNGs. Real typeface, real kerning, matching
+the pages being recorded — with no font vendored into the repo.
+
+### Framing a landscape master vertically
+
+A 1440x900 master narrowed to 9:16 keeps only **35% of its width**. That frames a centred
+3D stage well and slices the left column off a two-column form. Hence `fit`:
+
+- `cover` where a *detail* is the subject — a 3D stage, a single control.
+- `contain` where the *layout* is the subject — a form, a dense page. It letterboxes on the
+  studio background, and the resulting empty band is where the caption sits.
+
+For a vertical piece that is mostly dense UI, the better answer is to record a vertical
+take rather than crop a landscape one — `setViewport`, or a script with a vertical
+`viewport`.
+
+## Roadmap
+
+**Phase 1 — done.** Multi-page flows with preserved state, real interactions, live page
+manipulation, WebGL captured as painted, MP4/GIF/vertical output, a schema gate and a
+dry run.
+
+**Phase 2 — done.** Deterministic capture, above. Both modes share one timing seam
+(`timeline.mjs`): actions ask the driver to `wait` or to `animate`, and the driver decides
+whether that means sleeping or advancing a virtual frame. That is what let phase 2 land
+without rewriting the verb vocabulary.
+
+**Phase 3 — done.** The frame critic, below.
+
+**Phase 4 — done.** Edits, below.
+
+## Retired
+
+`tools/inject-recorder-all.mjs` injected a canvas-only recorder button into the blueprint
+editors. It emitted emoji, which `tools/verify.mjs` treats as an **error**, so running it
+broke the build; and `canvas.captureStream()` sees only the 3D surface, so the DOM and all
+text overlays were invisible in the result. It now exits with a pointer here.
+
+`assets/lib/recorder.js` is still loaded by the blueprint editors and was not removed — it
+does a genuinely different job, letting a customer export their own 3D scene from the
+browser.

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@mrkt_frwd/reel",
+  "version": "0.1.0",
+  "description": "Reel — drive a real browser from a declarative script and record it. Deterministic mode gives the same frames every run.",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.mjs"
+  },
+  "bin": {
+    "reel": "./src/cli.mjs"
+  },
+  "files": [
+    "src",
+    "docs"
+  ],
+  "dependencies": {
+    "@playwright/browser-chromium": "^1.62.1",
+    "ffmpeg-static": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT"
+}

package/src/actions.mjs

@@ -0,0 +1,215 @@
+/**
+ * The action vocabulary a recording script may use.
+ *
+ * Every verb is declarative and named, because the scripts are written and critiqued by
+ * different agents: a director can say "beat 3 lingers" and an interaction developer can
+ * change one number, which is not true of a pile of imperative Playwright calls.
+ *
+ * Motion is eased rather than instant throughout. A cursor that teleports and a scroll
+ * that jumps both read as a robot driving the page; the reference formats — Linear,
+ * Stripe, Raycast — are legible precisely because movement has acceleration and the eye
+ * can follow it.
+ *
+ * No verb sleeps or eases on its own. Waiting goes through `ctx.driver.wait` and motion
+ * through `ctx.driver.animate`, so the same script runs unchanged under wall-clock capture
+ * or under the deterministic clock, where a duration means a frame count rather than
+ * elapsed time. Anything that reached for `page.waitForTimeout` directly would silently
+ * opt out of deterministic mode and desynchronise from the frames around it.
+ */
+
+const clamp = (n, lo, hi) => Math.max(lo, Math.min(hi, n));
+
+/**
+ * Seeded jitter for keystroke cadence.
+ *
+ * Typing on a metronome does not read as typing, so the delay between keys is varied —
+ * but `Math.random()` would make every run of a script produce different frames, which
+ * silently defeats deterministic capture. A counter-seeded generator keeps the variation
+ * and keeps the reproducibility.
+ */
+let jitterState = 0x2f6e2b1;
+export function resetJitter(seed = 0x2f6e2b1) { jitterState = seed >>> 0; }
+function jitter() {
+  // xorshift32 — small, fast, and good enough for spacing keystrokes.
+  jitterState ^= jitterState << 13; jitterState >>>= 0;
+  jitterState ^= jitterState >>> 17;
+  jitterState ^= jitterState << 5; jitterState >>>= 0;
+  return jitterState / 0xffffffff;
+}
+
+async function centerOf(page, selector) {
+  const box = await page.locator(selector).first().boundingBox();
+  if (!box) throw new Error(`selector has no box on screen: ${selector}`);
+  return { x: box.x + box.width / 2, y: box.y + box.height / 2 };
+}
+
+/**
+ * Glide the real mouse. The drawn cursor follows via a `pointermove` listener installed
+ * by CURSOR_INIT, so this issues one message per step rather than three — the earlier
+ * version positioned the overlay with its own `evaluate` per frame and that IPC cost, not
+ * rendering, was what held capture near 20fps during motion.
+ */
+async function glide(ctx, to, ms = 520) {
+  const { page, driver } = ctx;
+  const from = await page.evaluate(() => ({ x: window.__rec?._x ?? 0, y: window.__rec?._y ?? 0 }));
+  await driver.animate(ms, async (t) => {
+    await page.mouse.move(from.x + (to.x - from.x) * t, from.y + (to.y - from.y) * t);
+  });
+}
+
+export const ACTIONS = {
+  async goto(ctx, a) {
+    const { page, baseUrl } = ctx;
+    const url = /^https?:/i.test(a.url) ? a.url : baseUrl + (a.url.startsWith('/') ? a.url : `/${a.url}`);
+    await page.goto(url, { waitUntil: a.waitUntil || 'load', timeout: a.timeout || 30000 });
+    // Fonts settle after load and a swap mid-shot is visible in the frames.
+    await page.evaluate(() => document.fonts?.ready).catch(() => {});
+    if (a.ms) await ctx.driver.wait(a.ms);
+  },
+
+  async waitFor({ page }, a) {
+    if (a.selector) await page.locator(a.selector).first().waitFor({ state: a.state || 'visible', timeout: a.timeout || 15000 });
+    else if (a.fn) await page.waitForFunction(a.fn, undefined, { timeout: a.timeout || 15000 });
+    else throw new Error('waitFor needs a selector or fn');
+  },
+
+  /** Dead time on purpose — a beat where the viewer reads what just happened. */
+  async hold(ctx, a) {
+    const { page } = ctx;
+    await ctx.driver.wait(a.ms ?? 700);
+  },
+
+  async moveTo(ctx, a) {
+    const { page } = ctx;
+    await glide(ctx, { x: a.x, y: a.y }, a.ms);
+  },
+
+  async hover(ctx, a) {
+    const { page } = ctx;
+    await glide(ctx, await centerOf(page, a.selector), a.ms);
+    await page.locator(a.selector).first().hover({ force: true }).catch(() => {});
+    if (a.hold) await ctx.driver.wait(a.hold);
+  },
+
+  async click(ctx, a) {
+    const { page } = ctx;
+    const point = await centerOf(page, a.selector);
+    await glide(ctx, point, a.ms);
+    await page.evaluate(() => window.__rec?.ripple());
+    await page.mouse.click(point.x, point.y);
+    if (a.hold) await ctx.driver.wait(a.hold);
+  },
+
+  /**
+   * Types at a human cadence rather than pasting. `cps` is characters per second; the
+   * per-key jitter keeps it off a metronome, which is what makes typing read as typing.
+   */
+  async type(ctx, a) {
+    const { page } = ctx;
+    const el = page.locator(a.selector).first();
+    if (a.click !== false) {
+      const point = await centerOf(page, a.selector);
+      await glide(ctx, point, a.ms);
+      await page.evaluate(() => window.__rec?.ripple());
+      await page.mouse.click(point.x, point.y);
+    }
+    if (a.clear) await el.fill('');
+    const cps = a.cps || 18;
+    for (const ch of String(a.text)) {
+      await el.press(ch === ' ' ? 'Space' : ch, { timeout: 5000 }).catch(async () => {
+        await page.keyboard.type(ch);
+      });
+      await ctx.driver.wait(clamp((1000 / cps) * (0.6 + jitter() * 0.8), 12, 220));
+    }
+    if (a.hold) await ctx.driver.wait(a.hold);
+  },
+
+  async press(ctx, a) {
+    const { page } = ctx;
+    for (let i = 0; i < (a.times || 1); i++) {
+      await page.keyboard.press(a.key);
+      await ctx.driver.wait(a.every ?? 120);
+    }
+  },
+
+  /** Eased programmatic scroll. The page's own smooth-scroll is disabled by POLISH_INIT. */
+  async scroll(ctx, a) {
+    const { page } = ctx;
+    const target = await page.evaluate((spec) => {
+      if (typeof spec === 'number') return spec;
+      if (spec === 'bottom') return document.documentElement.scrollHeight - window.innerHeight;
+      if (spec === 'top') return 0;
+      const el = document.querySelector(spec);
+      if (!el) throw new Error('scroll target not found: ' + spec);
+      return window.scrollY + el.getBoundingClientRect().top - window.innerHeight * 0.2;
+    }, a.to);
+
+    // Stepped from the driver rather than animated in-page. An in-page requestAnimationFrame
+    // loop cannot work under the deterministic clock: rAF only fires when the driver ticks,
+    // and the driver is blocked awaiting the very promise those ticks would resolve. Driving
+    // it from outside is the only formulation that holds in both modes.
+    const from = await page.evaluate(() => window.scrollY);
+    await ctx.driver.animate(a.ms ?? 1400, async (t) => {
+      await page.evaluate((y) => window.scrollTo(0, y), from + (target - from) * t);
+    });
+    if (a.hold) await ctx.driver.wait(a.hold);
+  },
+
+  /**
+   * Press, glide, release. This is how a 3D scene gets orbited — the WebGL templates
+   * read pointer deltas, so the drag has to be many small moves rather than one jump.
+   */
+  async drag(ctx, a) {
+    const { page } = ctx;
+    const start = a.selector ? await centerOf(page, a.selector) : { x: a.x, y: a.y };
+    await glide(ctx, start, a.approachMs ?? 420);
+    await page.mouse.down();
+    await ctx.driver.animate(a.ms ?? 1200, async (t) => {
+      await page.mouse.move(start.x + (a.dx || 0) * t, start.y + (a.dy || 0) * t);
+    });
+    await page.mouse.up();
+    if (a.hold) await ctx.driver.wait(a.hold);
+  },
+
+  /**
+   * Run script in the page — the lever for making the page itself dynamic mid-recording:
+   * seed data, trigger an animation, force a state the UI cannot reach quickly. The
+   * source is a local script file the operator wrote, same trust level as the tool.
+   */
+  async eval(ctx, a) {
+    const { page } = ctx;
+    await page.evaluate(a.fn, a.arg);
+    if (a.ms) await ctx.driver.wait(a.ms);
+  },
+
+  async inject(ctx, a) {
+    const { page } = ctx;
+    if (a.css) await page.addStyleTag({ content: a.css });
+    if (a.js) await page.addScriptTag({ content: a.js });
+    if (a.ms) await ctx.driver.wait(a.ms);
+  },
+
+  /** Stub a network response so a demo never depends on a live service being up. */
+  async route({ page }, a) {
+    await page.route(a.url, (route) =>
+      route.fulfill({
+        status: a.status || 200,
+        contentType: a.json ? 'application/json' : a.contentType || 'text/plain',
+        body: a.json ? JSON.stringify(a.json) : (a.body ?? ''),
+      })
+    );
+  },
+
+  async setViewport(ctx, a) {
+    const { page } = ctx;
+    await page.setViewportSize({ width: a.width, height: a.height });
+    if (a.ms) await ctx.driver.wait(a.ms);
+  },
+
+  async cursor({ page }, a) {
+    if (a.hide) await page.evaluate(() => window.__rec?.hide());
+    else await page.evaluate(([x, y]) => window.__rec?.cursor(x, y), [a.x ?? 0, a.y ?? 0]);
+  },
+};
+
+export const ACTION_TYPES = Object.keys(ACTIONS);