@navipartner/demo-video 0.7.1 → 0.7.3

package/README.md

@@ -33,7 +33,7 @@ video of the app: it writes the adapter and the primary story with you.
 | Linear | @Linear "… for Northwind (northwind.example)" | the same, in a customer's researched brand |
 | A PR | the `demo video` label | reviewing the stories the PR adds or changes |
 | A PR | `/demo-video checkout` (`help` for the menu) | filming any story from the PR's branch |
-| Your machine | `pnpm exec demo-video render` | writing and tuning a story |
+| Your machine | Claude with the skill | writing and tuning a story: 30 fps drafts, then the 60 fps video once you say the whole flow is right |
 
 Requests only pick existing stories; new stories come through a developer's
 PR. In a PR comment, the first line is the request, a translation is found
@@ -44,8 +44,9 @@ the menu.
 
 Ask @Linear in plain words, naming the repo, the story and the customer. In
 a coding session it follows the skill's `linear.md`, attaches the MP4 and
-its contact sheet to the issue, and commits nothing. It runs on Linear's AI
-credits; its sandbox is slow, about 15× the video's length at 60 fps.
+its contact sheet to the issue, and commits nothing. It films the agreed
+story at 60 fps. It runs on Linear's AI credits; its sandbox is slow, about
+15× the video's length at 60 fps.
 
 For a customer, the video is a **pitch draft**. @Linear researches their
 brand from their own website, the engine checks it and films at 30 fps, and
@@ -92,8 +93,8 @@ output is kept in `demo/out/failed/`.
     pnpm test && pnpm typecheck && pnpm lint && pnpm build
 
 CI runs the tests, actionlint and a smoke render of the fixture app. To
-release, bump `version` in `package.json` on main, then
-`git tag vX.Y.Z && git push origin vX.Y.Z`. CI publishes to npm as `latest`
+release, tag main: `git tag vX.Y.Z && git push origin vX.Y.Z`. The tag
+sets the version; `package.json` isn't bumped by hand. CI publishes to npm as `latest`
 through trusted publishing (no npm token) and moves the `v0` tag. Running
 `release.yml` by hand publishes a `next` prerelease.
 

package/bin/demo-video.mjs

@@ -135,6 +135,12 @@ const printReport = (report) => {
         `  about ${report.seconds} s; a ${report.kind === "feature" ? "feature clip" : "showcase"} runs ${low}–${high} s${fits ? `, so this is ${fits}` : ""}`,
       );
     }
+    // A card held up by its setup lingers: worth moving some of it.
+    for (const card of report.slowCards ?? []) {
+      console.log(
+        `  ${card.where}: the setup behind it takes about ${card.setupSeconds} s, so it stays up longer than its ${card.readSeconds} s to read; move some setup behind an earlier card`,
+      );
+    }
     return;
   }
   const where = report.step

package/bin/runner.mjs

@@ -14,6 +14,12 @@ const importPath = (from, to) => {
 const HEADER =
   "// Generated by @navipartner/demo-video on every run; do not edit.\n";
 
+// In an app that isn't ESM, Playwright compiles demo.config.ts as CommonJS,
+// and its `export default` arrives wrapped: { __esModule, default }.
+const importAdapter = (from) => `import loaded from ${from};
+
+const adapter = loaded?.__esModule ? loaded.default : loaded;`;
+
 /** Writes playwright.config.mjs and demo.spec.mjs; returns the config path. */
 export const writeRunner = ({
   runnerDir,
@@ -28,7 +34,7 @@ export const writeRunner = ({
     configPath,
     `${HEADER}import { createDemoConfig } from "@navipartner/demo-video/runner";
 
-import adapter from ${adapter};
+${importAdapter(adapter)}
 
 export default createDemoConfig(adapter, ${dirs});
 `,
@@ -38,7 +44,7 @@ export default createDemoConfig(adapter, ${dirs});
     `${HEADER}import { registerDemoTests } from "@navipartner/demo-video/runner";
 import { test } from "@playwright/test";
 
-import adapter from ${adapter};
+${importAdapter(adapter)}
 
 registerDemoTests(test, adapter, ${JSON.stringify(demoDir)});
 `,

package/dist/{adapter-bOi1ZBRa.d.ts → adapter-DxZmb-QU.d.ts}

@@ -71,8 +71,8 @@ interface CardOptions {
     /** The story's kind: how long the open card may stay up. */
     kind?: Kind;
     /**
-     * Done while the card covers the app (setup, the chapter's first shot):
-     * no cursor, no camera moves, and the card stays up until it's done.
+     * Done while the card covers the app (setup): no cursor, no camera
+     * moves, and the card stays up until it's done.
      */
     behind?: () => Promise<void>;
 }
@@ -116,7 +116,10 @@ interface DirectorApi {
      * Runs an adapter action. While filming, time is stopped, so an action that
      * waits on the app (a scan that fetches) needs frames filmed meanwhile.
      */
-    during<T>(work: () => Promise<T>): Promise<T>;
+    during<T>(work: () => Promise<T>, options?: {
+        /** The control the work uses: the cursor goes there, as for a click. */
+        target?: Target;
+    }): Promise<T>;
     /**
      * The app's clock, in ms: real time in check mode, the filmed (virtual)
      * time while filming. The idle accounting measures waits with it.
@@ -140,6 +143,13 @@ interface DirectorApi {
 interface DemoAction<S extends z.ZodRawShape = z.ZodRawShape> {
     params: z.ZodObject<S>;
     run(d: DirectorApi, params: z.infer<z.ZodObject<S>>): Promise<void>;
+    /**
+     * The control the action uses (a colour field, an upload button), as a
+     * testid, a selector or `{ target, nth }`. With one, the cursor glides to
+     * it and rests before the action, the camera rules apply as for a click,
+     * and the app's reaction plays out after it.
+     */
+    target?(params: z.infer<z.ZodObject<S>>): string | Target | undefined;
 }
 /** One thing a brand gives the app: what it is and where it shows. */
 type BrandNeed = string | {

package/dist/{chunk-RMBVQL2J.js → chunk-XMOGUZJU.js}

@@ -12,6 +12,11 @@ var CURSOR_MIN_MS = 400;
 var CURSOR_MAX_MS = 800;
 var CURSOR_MS_PER_PX = 0.7;
 var SETTLE_MS = 150;
+var ESTABLISH_MS = 800;
+var SETTLED_MS = 250;
+var REACTION_MS = 1e3;
+var COVERED_SETTLED_MS = 150;
+var COVERED_MAX_MS = 600;
 var PRE_CLICK_MS = 160;
 var PRESS_MS = 110;
 var POST_CLICK_MS = 450;
@@ -26,7 +31,7 @@ var TITLE_MAX_SECONDS = {
 var POLL_MS = 100;
 var wordCount = (text) => text ? text.replace(/\*/g, "").split(/\s+/).filter(Boolean).length : 0;
 var cardSeconds = (spec, maxSeconds = Number.POSITIVE_INFINITY) => {
-  const read = 0.6 + 0.28 * (wordCount(spec.heading) + wordCount(spec.sub)) + 0.14 * wordCount(spec.eyebrow);
+  const read = 0.5 + 0.25 * wordCount(spec.heading) + 0.2 * wordCount(spec.sub) + 0.12 * wordCount(spec.eyebrow);
   return Math.max(
     spec.seconds,
     Math.min(maxSeconds, Math.round(read * 10) / 10)
@@ -453,7 +458,7 @@ var cardFields = {
   logo: z.boolean().optional(),
   /** "pale" = brand-tinted white; "brand" = full-bleed primary colour. */
   style: z.enum(["pale", "brand"]).default("pale"),
-  seconds: z.number().min(0.5).max(10).default(1.8)
+  seconds: z.number().min(0.5).max(10).default(1.6)
 };
 var show = z.union([z.string().min(1), z.object({ ...target }).strict()]).optional();
 var stepCardFields = {
@@ -516,7 +521,7 @@ var coreStepSchemas = [
 var CORE_STEP_NAMES = coreStepSchemas.map(
   (s) => s.shape.do.value
 );
-var RESERVED_FIELDS = ["do"];
+var RESERVED_FIELDS = ["do", "behindCard"];
 var cardSchema = z.object(cardFields).strict().refine(hasContent, CARD_EMPTY);
 var titleSchema = z.object({ ...cardFields, show }).strict().refine(hasContent, CARD_EMPTY);
 var isCoreStep = (step) => CORE_STEP_NAMES.includes(step.do);
@@ -533,7 +538,7 @@ var buildStoryboardSchema = (adapter) => {
           );
         }
       }
-      return z.object({ do: z.literal(name) }).merge(action.params).strict();
+      return z.object({ do: z.literal(name), ...behindCard }).merge(action.params).strict();
     }
   );
   const stepSchema = z.discriminatedUnion("do", [
@@ -823,6 +828,11 @@ export {
   CURSOR_MIN_MS,
   CURSOR_MAX_MS,
   SETTLE_MS,
+  ESTABLISH_MS,
+  SETTLED_MS,
+  REACTION_MS,
+  COVERED_SETTLED_MS,
+  COVERED_MAX_MS,
   PRE_CLICK_MS,
   PRESS_MS,
   POST_CLICK_MS,

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { K as Kind, D as DemoAdapter } from './adapter-bOi1ZBRa.js';
-export { B as Brand, C as CardSpec, a as DemoAction, b as DirectorApi, T as Target, V as VideoBrand, d as defineAction, c as defineDemo } from './adapter-bOi1ZBRa.js';
+import { K as Kind, D as DemoAdapter } from './adapter-DxZmb-QU.js';
+export { B as Brand, C as CardSpec, a as DemoAction, b as DirectorApi, T as Target, V as VideoBrand, d as defineAction, c as defineDemo } from './adapter-DxZmb-QU.js';
 import { Page } from '@playwright/test';
 import { z } from 'zod';
 export { z } from 'zod';

package/dist/index.js

@@ -1,7 +1,7 @@
 import {
   StoryboardError,
   parseStoryboard
-} from "./chunk-RMBVQL2J.js";
+} from "./chunk-XMOGUZJU.js";
 
 // src/adapter.ts
 var defineDemo = (adapter) => adapter;

package/dist/runner/index.d.ts

@@ -1,5 +1,5 @@
 import { PlaywrightTestConfig, Page } from '@playwright/test';
-import { D as DemoAdapter } from '../adapter-bOi1ZBRa.js';
+import { D as DemoAdapter } from '../adapter-DxZmb-QU.js';
 import 'zod';
 
 /**

package/dist/runner/index.js

@@ -1,9 +1,12 @@
 import {
   CARD_IN_MS,
   CARD_OUT_MS,
+  COVERED_MAX_MS,
+  COVERED_SETTLED_MS,
   CURSOR_MAX_MS,
   CURSOR_MIN_MS,
   DEFAULT_VIEWPORT,
+  ESTABLISH_MS,
   LINGER_MS,
   MIN_SCALE,
   PARK,
@@ -13,6 +16,8 @@ import {
   POST_KEY_MS,
   PRESS_MS,
   PRE_CLICK_MS,
+  REACTION_MS,
+  SETTLED_MS,
   SETTLE_MS,
   STAGE_HEIGHT,
   STAGE_PATH,
@@ -36,7 +41,7 @@ import {
   unionRect,
   visibleRect,
   wideShot
-} from "../chunk-RMBVQL2J.js";
+} from "../chunk-XMOGUZJU.js";
 
 // src/runner/config.ts
 import path from "path";
@@ -260,15 +265,31 @@ import fs2 from "fs";
 import path3 from "path";
 
 // src/changes.ts
+var MAX_RESTYLES = 3;
 var watchChanges = (target) => target.evaluate((el) => {
-  const changed = /* @__PURE__ */ new Set();
+  const w = window;
+  w.__demoChanges?.observer.disconnect();
+  const changed = /* @__PURE__ */ new Map();
+  const watch = { changed, lastAt: Date.now() };
   const observer = new MutationObserver((records) => {
     for (const record of records) {
+      if (record.type !== "attributes") {
+        watch.lastAt = Date.now();
+      }
       const nodes = record.type === "childList" ? Array.from(record.addedNodes) : [record.target];
       for (const node of nodes) {
         const changedEl = node.nodeType === Node.ELEMENT_NODE ? node : node.parentElement;
         if (changedEl && !el.contains(changedEl) && !changedEl.contains(el)) {
-          changed.add(changedEl);
+          const seen = changed.get(changedEl) ?? {
+            content: false,
+            restyles: 0
+          };
+          if (record.type === "attributes") {
+            seen.restyles++;
+          } else {
+            seen.content = true;
+          }
+          changed.set(changedEl, seen);
         }
       }
     }
@@ -276,14 +297,21 @@ var watchChanges = (target) => target.evaluate((el) => {
   observer.observe(document.body, {
     subtree: true,
     childList: true,
-    characterData: true
+    characterData: true,
+    attributes: true,
+    attributeFilter: ["style", "class", "src"]
   });
-  window.__demoChanges = {
-    observer,
-    changed
-  };
+  watch.observer = observer;
+  w.__demoChanges = watch;
+});
+var watching = (app) => app.evaluate(
+  () => Boolean(window.__demoChanges)
+);
+var quietMs = (app) => app.evaluate(() => {
+  const watch = window.__demoChanges;
+  return watch ? Date.now() - watch.lastAt : Number.POSITIVE_INFINITY;
 });
-var biggestChange = (app) => app.evaluate(() => {
+var biggestChange = (app) => app.evaluate((maxRestyles) => {
   const w = window;
   const watch = w.__demoChanges;
   delete w.__demoChanges;
@@ -292,9 +320,10 @@ var biggestChange = (app) => app.evaluate(() => {
   }
   watch.observer.disconnect();
   let best = null;
+  let bestEl = null;
   let label = "";
-  for (const el of watch.changed) {
-    if (!el.isConnected) {
+  for (const [el, seen] of watch.changed) {
+    if (!el.isConnected || !seen.content && seen.restyles > maxRestyles) {
       continue;
     }
     const r = el.getBoundingClientRect();
@@ -303,17 +332,35 @@ var biggestChange = (app) => app.evaluate(() => {
     }
     if (!best || r.width * r.height > best.width * best.height) {
       best = { x: r.x, y: r.y, width: r.width, height: r.height };
+      bestEl = el;
       label = el.getAttribute("data-testid") ?? el.tagName.toLowerCase() + (el.textContent ? ` "${el.textContent.trim().slice(0, 30)}"` : "");
     }
   }
-  return best ? { rect: best, label } : null;
-});
+  if (!best || !bestEl) {
+    return null;
+  }
+  let fontPx = Number.POSITIVE_INFINITY;
+  const texts = [
+    bestEl,
+    ...Array.from(bestEl.querySelectorAll("*")).slice(0, 200)
+  ];
+  for (const node of texts) {
+    const hasText = Array.from(node.childNodes).some(
+      (c) => c.nodeType === Node.TEXT_NODE && c.textContent?.trim()
+    );
+    if (hasText) {
+      fontPx = Math.min(fontPx, parseFloat(getComputedStyle(node).fontSize));
+    }
+  }
+  return { rect: best, label, fontPx };
+}, MAX_RESTYLES);
 
 // src/director.ts
 var TARGET_TIMEOUT_MS = 15e3;
 var SHOWN = 0.5;
 var FRAME_MAX_SCALE = 1.8;
 var PUSH_WORTHY = 1.4;
+var READABLE_PX = 16;
 var STILL_MAX_PX = 1600;
 var testIdSelector = (selector) => /^[\w-]+$/.test(selector) ? `[data-testid="${selector}"]` : selector;
 var normalise = (text) => text.replace(/\s+/g, " ").trim();
@@ -347,8 +394,11 @@ var Director = class {
    */
   wideUse = {
     rects: [],
-    names: []
+    names: [],
+    textPx: Number.POSITIVE_INFINITY
   };
+  /** When the whole window came into view (virtual ms), for ESTABLISH_MS. */
+  wideSince = 0;
   cdp;
   get fast() {
     return this.options.fast;
@@ -440,16 +490,21 @@ var Director = class {
     if (sameShot(next, this.shot)) {
       return;
     }
+    this.wasWide = this.isWide();
     this.shot = next;
     this.shotLabel = `the shot on "${t.target}" at ${scale}`;
     await this.moveCamera(next);
   }
-  // Films a camera move. Behind a card the shot is simply there when the
-  // card goes, so the chapter opens on it.
+  // Films a camera move. A push-in from the wide shot waits until the whole
+  // window has been seen for ESTABLISH_MS: a page never opens zoomed.
   async moveCamera(shot) {
     if (this.fast) {
       return;
     }
+    const fromWide = this.wasWide;
+    if (fromWide && !this.covered) {
+      await this.wait(ESTABLISH_MS - (this.clockMs() - this.wideSince));
+    }
     const instant = this.covered;
     await this.page.evaluate(([s, i]) => window.__demo.setShot(s, i), [
       shot,
@@ -484,7 +539,7 @@ var Director = class {
     );
     if (scale < MIN_SCALE) {
       throw new Error(
-        `${names} only fit in the wide shot (at ${scale.toFixed(2)}); frame things that sit together, or stay wide`
+        `${names} only fit in the wide shot (at ${scale.toFixed(2)}): stay wide, or frame things that sit together`
       );
     }
     const next = shotFor(this.layout, all, scale);
@@ -495,6 +550,7 @@ var Director = class {
     if (sameShot(next, this.shot)) {
       return;
     }
+    this.wasWide = this.isWide();
     this.shot = next;
     this.shotLabel = `the shot framing ${names}`;
     await this.moveCamera(next);
@@ -520,7 +576,15 @@ var Director = class {
       await this.page.evaluate((s) => window.__demo.setShot(s), wide);
     }
     await this.wait(Math.max(moving ? ZOOM_MS + SETTLE_MS : 0, parkMs));
+    if (moving) {
+      this.wideSince = this.clockMs();
+    }
   }
+  // Whether the camera shows the whole window now.
+  isWide() {
+    return this.shot.k <= this.layout.fit * 1.01;
+  }
+  wasWide = false;
   // --- cursor + input -----------------------------------------------------------
   /** Rests the cursor in empty space, off the content. */
   async park() {
@@ -542,32 +606,41 @@ var Director = class {
     const margin = 8;
     if (cx < v.x + margin || cx > v.x + v.width - margin || cy < v.y + margin || cy > v.y + v.height - margin) {
       throw new Error(
-        `"${t.target}" is outside ${this.shotLabel}. Zoom on an area that holds everything this shot uses, or zoomOut first.`
+        `"${t.target}" is outside ${this.shotLabel}: zoomOut first, or frame an area that holds everything this shot uses.`
       );
     }
     return { point: this.toStagePoint(rect), rect };
   }
   async click(t, options = {}) {
+    await this.interact(t, { zoom: options.zoom, verb: "clicking" });
+  }
+  // One interaction with a control, as a person makes it: the cursor glides
+  // there and rests, presses (a real click, or only the look of one when an
+  // adapter action does the work), `then` runs (typing, the action), and the
+  // app's reaction plays out. What it changes is watched from before the
+  // press to the end, so typing's live preview, a toast after a save and a
+  // restyle all count as the result. Behind a card none of it is filmed.
+  async interact(t, options) {
     if (options.zoom !== void 0) {
       await this.zoomTo(t, options.zoom);
     } else {
       this.requireSeen("other");
     }
     const { point, rect } = await this.pointAt(t);
-    const zoomed = this.shot.k > this.layout.fit * 1.01;
-    const wide = !zoomed && !this.covered;
-    if (zoomed || wide) {
+    const filmed = !this.fast && !this.covered;
+    const zoomed = !this.isWide();
+    const inner = await watching(this.app);
+    const fontPx = inner ? Number.NaN : await this.locator(t).evaluate(
+      (el) => parseFloat(getComputedStyle(el).fontSize),
+      void 0,
+      {
+        timeout: 1e3
+      }
+    ).catch(() => Number.NaN);
+    if (!inner) {
       await watchChanges(this.locator(t));
     }
-    if (this.fast) {
-      await this.page.mouse.click(point.x, point.y);
-      if (zoomed || wide) {
-        await this.page.waitForTimeout(POST_CLICK_MS);
-      }
-    } else if (this.covered) {
-      await this.page.mouse.click(point.x, point.y);
-      await this.wait(POST_CLICK_MS);
-    } else {
+    if (filmed) {
       const ms = await this.page.evaluate(
         ([x, y]) => window.__demo.cursorTo(x, y),
         [point.x, point.y]
@@ -575,33 +648,79 @@ var Director = class {
       await this.wait(ms);
       await this.page.mouse.move(point.x, point.y);
       await this.wait(PRE_CLICK_MS);
+    }
+    if (options.press === "look") {
+      await this.wait(PRESS_MS);
+    } else if (filmed) {
       await this.page.mouse.down();
       await this.wait(PRESS_MS);
       await this.page.mouse.up();
+    } else {
+      await this.page.mouse.click(point.x, point.y);
+    }
+    await options.then?.();
+    if (this.covered) {
+      await this.settle(COVERED_SETTLED_MS, COVERED_MAX_MS);
+      if (!inner) {
+        await biggestChange(this.app);
+      }
+      return;
+    }
+    if (filmed) {
       await this.wait(POST_CLICK_MS);
+    } else {
+      await this.page.waitForTimeout(POST_CLICK_MS);
+    }
+    await this.settle(SETTLED_MS, REACTION_MS);
+    if (inner) {
+      return;
     }
     if (zoomed) {
-      await this.assertChangeInShot(t);
-    } else if (wide) {
-      const biggest = await biggestChange(this.app);
-      this.wideUse.rects.push(rect, ...biggest ? [biggest.rect] : []);
-      this.wideUse.names.push(t.target);
+      await this.assertChangeInShot(t, options.verb);
+      return;
+    }
+    const biggest = await biggestChange(this.app);
+    this.wideUse.rects.push(rect, ...biggest ? [biggest.rect] : []);
+    this.wideUse.names.push(t.target);
+    const smallest = Math.min(
+      Number.isFinite(fontPx) ? fontPx : Number.POSITIVE_INFINITY,
+      biggest?.fontPx ?? Number.POSITIVE_INFINITY
+    );
+    if (Number.isFinite(smallest)) {
+      this.wideUse.textPx = Math.min(
+        this.wideUse.textPx,
+        smallest * this.layout.fit
+      );
+    }
+  }
+  // Until nothing in the app has changed for `quiet` ms, at most `max` ms:
+  // filmed on the virtual clock, in real time in check.
+  async settle(quiet, max) {
+    for (let waited = 0; waited < max; waited += POLL_MS) {
+      if (await quietMs(this.app) >= quiet) {
+        return;
+      }
+      if (this.fast) {
+        await this.page.waitForTimeout(POLL_MS);
+      } else {
+        await this.wait(POLL_MS);
+      }
     }
   }
   // The wide shot ends (a push-in, a card, the end). Its clicks must have
   // needed it: if their controls and results all fit a push-in, the wide
   // shot showed them too small to read on a phone.
   closeWide() {
-    const { rects, names } = this.wideUse;
-    this.wideUse = { rects: [], names: [] };
-    if (names.length === 0) {
+    const { rects, names, textPx } = this.wideUse;
+    this.wideUse = { rects: [], names: [], textPx: Number.POSITIVE_INFINITY };
+    if (names.length === 0 || textPx >= READABLE_PX) {
       return;
     }
     const scale = fittingScale(this.layout, unionRect(rects));
     if (scale >= PUSH_WORTHY) {
-      const clicked = [...new Set(names)].map((n) => `"${n}"`).join(", ");
+      const used = [...new Set(names)].map((n) => `"${n}"`).join(", ");
       throw new Error(
-        `${clicked} ${names.length > 1 ? "are" : "is"} clicked in the wide shot, but the controls and what they change fit a push-in at ${Math.min(scale, FRAME_MAX_SCALE).toFixed(1)}: frame them so the shot reads on a phone, or do it behindCard if it's setup`
+        `${used} ${names.length > 1 ? "are" : "is"} used in the wide shot, where its text is ${Math.round(textPx)} px, too small to read, and the controls with what they change fit a push-in at ${Math.min(scale, FRAME_MAX_SCALE).toFixed(1)}: frame them (the engine pushes in after a wide beat), or do it behindCard if it's setup`
       );
     }
   }
@@ -609,7 +728,7 @@ var Director = class {
   // click changed lands outside the shot (an item added to a basket
   // off-screen), the zoom is on the wrong area: the viewer would see a
   // button pressed and nothing happen.
-  async assertChangeInShot(t) {
+  async assertChangeInShot(t, verb) {
     const biggest = await biggestChange(this.app);
     if (!biggest) {
       return;
@@ -617,7 +736,7 @@ var Director = class {
     if (coverage(biggest.rect, visibleRect(this.layout, this.shot)) < SHOWN) {
       this.unseen = {
         rect: biggest.rect,
-        message: `clicking "${t.target}" changes ${biggest.label}, which is outside ${this.shotLabel}, and the next step doesn't show it. Frame what the click changes, or pull out right after.`
+        message: `${verb} "${t.target}" changes ${biggest.label}, which is outside ${this.shotLabel}, and the next step doesn't show it: zoomOut right after, or frame the control with what it changes.`
       };
     }
   }
@@ -637,20 +756,33 @@ var Director = class {
     throw new Error(unseen.message);
   }
   async type(t, text, perCharMs = TYPE_CHAR_MS, options = {}) {
-    await this.click(t);
-    if (options.replace) {
-      await this.page.keyboard.press("ControlOrMeta+A");
-    }
-    if (this.fast || this.covered) {
-      await this.page.keyboard.type(text);
-      await this.wait(POST_KEY_MS);
-      return;
-    }
-    for (const char of text) {
-      await this.page.keyboard.type(char);
-      await this.wait(perCharMs);
-    }
-    await this.wait(POST_KEY_MS);
+    await this.interact(t, {
+      verb: "typing in",
+      then: async () => {
+        if (options.replace) {
+          await this.page.keyboard.press("ControlOrMeta+A");
+        } else {
+          await this.app.evaluate(() => {
+            const el = document.activeElement;
+            if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
+              try {
+                el.setSelectionRange(el.value.length, el.value.length);
+              } catch {
+              }
+            }
+          });
+        }
+        if (this.fast || this.covered) {
+          await this.page.keyboard.type(text);
+          return;
+        }
+        await this.wait(POST_KEY_MS);
+        for (const char of text) {
+          await this.page.keyboard.type(char);
+          await this.wait(perCharMs);
+        }
+      }
+    });
   }
   async press(key) {
     this.requireSeen("other");
@@ -666,13 +798,22 @@ var Director = class {
     this.requireSeen("other");
     this.closeWide();
   }
-  async during(work) {
-    this.requireSeen("other");
+  async during(work, options = {}) {
     const recorder = this.options.recorder;
-    if (this.fast || !recorder) {
-      return work();
+    const run = () => this.fast || !recorder ? work() : recorder.during(work());
+    if (options.target) {
+      let result2;
+      await this.interact(options.target, {
+        verb: "using",
+        press: "look",
+        then: async () => {
+          result2 = await run();
+        }
+      });
+      return result2;
     }
-    const result = await recorder.during(work());
+    this.requireSeen("other");
+    const result = await run();
     await this.wait(POST_ACTION_MS);
     return result;
   }
@@ -737,6 +878,7 @@ var Director = class {
     if (!options.keepUp) {
       await this.hideCard();
       await this.wait(CARD_OUT_MS);
+      this.wideSince = this.clockMs();
     }
   }
   async behind(work) {
@@ -897,10 +1039,16 @@ var runStep = async (d, step, adapter) => {
     throw new Error(`unknown step "${step.do}"`);
   }
   const params = Object.fromEntries(
-    Object.entries(step).filter(([key]) => key !== "do")
+    Object.entries(step).filter(
+      ([key]) => key !== "do" && key !== "behindCard"
+    )
   );
   const parsed = action.params.parse(params);
-  await d.during(() => action.run(d, parsed));
+  const target = action.target?.(parsed);
+  await d.during(
+    () => action.run(d, parsed),
+    target === void 0 ? void 0 : { target: toTarget(target) }
+  );
 };
 var needsLinger = (previous) => previous !== void 0 && previous.do !== "hold" && previous.do !== "card" && !isBehindCard(previous);
 var TITLE = -1;
@@ -916,9 +1064,6 @@ var planCards = (steps, hasTitle) => {
     while (j < steps.length && isBehindCard(steps[j])) {
       behind.push(j++);
     }
-    if (j < steps.length && (steps[j].do === "zoom" || steps[j].do === "frame")) {
-      behind.push(j++);
-    }
     plans.set(start, {
       behind,
       opens: j < steps.length && steps[j].do !== "card"
@@ -948,9 +1093,9 @@ var stillCards = (steps, title) => [
 var WAITS = /* @__PURE__ */ new Set(["waitFor", "expectText"]);
 var runSteps = async (d, steps, adapter, options = {}) => {
   const idleLimitMs = adapter.idleTimeoutSeconds ? adapter.idleTimeoutSeconds * 1e3 - IDLE_MARGIN_MS : Number.POSITIVE_INFINITY;
-  let quietMs = options.initialQuietMs ?? 0;
+  let quietMs2 = options.initialQuietMs ?? 0;
   const tooQuiet = () => new Error(
-    `the app would sit untouched for ${Math.round(quietMs / 1e3)} s; its idle timeout is ${adapter.idleTimeoutSeconds} s. Add an interaction or shorten the holds.`
+    `the app would sit untouched for ${Math.round(quietMs2 / 1e3)} s; its idle timeout is ${adapter.idleTimeoutSeconds} s. Add an interaction or shorten the holds.`
   );
   const plans = planCards(steps, Boolean(options.title));
   const covered = new Set([...plans.values()].flatMap((p) => p.behind));
@@ -1017,8 +1162,8 @@ var runSteps = async (d, steps, adapter, options = {}) => {
     try {
       const linger = step.do === "card" && needsLinger(steps[index - 1]);
       if (step.do === "hold" || step.do === "card" || CAMERA_MOVES.has(step.do) && !covered.has(index)) {
-        quietMs += step.do === "hold" ? Number(step.seconds) * 1e3 : step.do === "card" ? cardSeconds(step) * 1e3 + CARD_DISSOLVE_MS + (linger ? LINGER_MS : 0) : CAMERA_MOVE_MS;
-        if (quietMs > idleLimitMs) {
+        quietMs2 += step.do === "hold" ? Number(step.seconds) * 1e3 : step.do === "card" ? cardSeconds(step) * 1e3 + CARD_DISSOLVE_MS + (linger ? LINGER_MS : 0) : CAMERA_MOVE_MS;
+        if (quietMs2 > idleLimitMs) {
           throw tooQuiet();
         }
       }
@@ -1032,13 +1177,13 @@ var runSteps = async (d, steps, adapter, options = {}) => {
         await runStep(d, step, adapter);
       }
       if (WAITS.has(step.do)) {
-        quietMs += d.clockMs() - started;
-        if (quietMs > idleLimitMs) {
+        quietMs2 += d.clockMs() - started;
+        if (quietMs2 > idleLimitMs) {
           throw tooQuiet();
         }
       }
       if (INTERACTIONS.has(step.do) || adapter.actions?.[step.do]) {
-        quietMs = 0;
+        quietMs2 = 0;
       }
     } catch (cause) {
       await fail(index, cause);
@@ -1055,7 +1200,7 @@ var runSteps = async (d, steps, adapter, options = {}) => {
     }
   };
   if (options.title) {
-    quietMs += titleSeconds(options.title, options.kind) * 1e3 + CARD_OUT_MS;
+    quietMs2 += titleSeconds(options.title, options.kind) * 1e3 + CARD_OUT_MS;
     await runCard(TITLE);
   }
   for (const index of steps.keys()) {
@@ -1099,22 +1244,33 @@ var stepMs = (step) => {
       return POST_ACTION_MS + CURSOR_MS;
   }
 };
-var estimateSeconds = (story) => {
+var estimateSeconds = (story) => Math.round(estimateMs(story) / 1e3);
+var estimateMs = (story) => {
   const steps = story.steps;
   const plans = planCards(steps, Boolean(story.title));
   const covered = new Set([...plans.values()].flatMap((p) => p.behind));
   const after = (at) => steps[(plans.get(at)?.behind.at(-1) ?? at) + 1];
   let ms = 0;
+  let wideAt = 0;
   if (story.title) {
     ms += titleSeconds(story.title, story.kind) * 1e3;
     ms += after(TITLE)?.do === "card" ? 0 : CARD_OUT_MS;
+    wideAt = ms;
   }
   steps.forEach((step, i) => {
     if (covered.has(i)) {
       return;
     }
     if (step.do !== "card") {
+      const pushes = step.do === "zoom" || step.do === "frame" || step.do === "click" && step.zoom !== void 0;
+      if (pushes && wideAt !== null) {
+        ms += Math.max(0, ESTABLISH_MS - (ms - wideAt));
+        wideAt = null;
+      }
       ms += stepMs(step);
+      if (step.do === "zoomOut") {
+        wideAt = ms;
+      }
       return;
     }
     const previous = steps[i - 1];
@@ -1122,13 +1278,45 @@ var estimateSeconds = (story) => {
     ms += (linger ? LINGER_MS : 0) + CARD_IN_MS;
     ms += cardSeconds(step) * 1e3;
     ms += after(i)?.do === "card" || !after(i) && story.closing ? 0 : CARD_OUT_MS;
+    wideAt = ms;
   });
   if (story.closing) {
     const last = steps.at(-1)?.do;
     ms += last !== "card" && last !== "hold" ? LINGER_MS : 0;
     ms += CARD_IN_MS + titleSeconds(story.closing, story.kind) * 1e3;
   }
-  return Math.round(ms / 1e3);
+  return ms;
+};
+var COVERED_STEP_MS = {
+  click: 300,
+  type: 350,
+  press: 100,
+  waitFor: 200
+};
+var COVERED_ACTION_MS = 500;
+var slowCards = (story) => {
+  const steps = story.steps;
+  const plans = planCards(steps, Boolean(story.title));
+  const slow = [];
+  for (const [at, plan] of plans) {
+    const card = at === TITLE ? story.title : steps[at];
+    if (!card || plan.behind.length === 0) {
+      continue;
+    }
+    const setupMs = plan.behind.reduce(
+      (sum, i) => sum + (COVERED_STEP_MS[steps[i].do] ?? COVERED_ACTION_MS),
+      0
+    );
+    const readSeconds = at === TITLE ? titleSeconds(card, story.kind) : cardSeconds(card);
+    if (setupMs / 1e3 > readSeconds + 0.3) {
+      slow.push({
+        where: at === TITLE ? "title" : `steps.${at}`,
+        readSeconds,
+        setupSeconds: Math.round(setupMs / 100) / 10
+      });
+    }
+  }
+  return slow;
 };
 
 // src/frames.ts
@@ -1497,7 +1685,8 @@ var registerDemoTests = (test, adapter, demoDir) => {
           ok: true,
           steps: story.steps.length,
           kind: story.kind ?? "showcase",
-          seconds: estimateSeconds(story)
+          seconds: estimateSeconds(story),
+          slowCards: slowCards(story)
         });
       } catch (error) {
         writeJson(reportPath, failureReport(error));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@navipartner/demo-video",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "Marketing demo videos of a React app, filmed by Playwright against the app's own e2e mocks.",
   "license": "UNLICENSED",
   "repository": {
@@ -9,18 +9,20 @@
   },
   "type": "module",
   "engines": {
-    "node": ">=22"
+    "node": ">=22.12"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     },
     "./runner": {
       "types": "./dist/runner/index.d.ts",
-      "import": "./dist/runner/index.js"
+      "import": "./dist/runner/index.js",
+      "default": "./dist/runner/index.js"
     }
   },
   "bin": {

package/skills/np-demo-video/SKILL.md

@@ -71,7 +71,7 @@ step of the spec, decide:
 
 | The step is… | In the video |
 |---|---|
-| The idea itself (scan, pay, the preview changing) | On screen, pushed in |
+| The idea itself (scan, pay, the preview changing) | On screen: wide when it reads, pushed in only when it's too small |
 | Needed, but not the idea (a language dialog, a cookie banner, a tab, a login) | `"behindCard": true` right after the chapter's card: done while the card covers the app |
 | Filling a form | One or two short values, in fields whose effect shows on screen (the preview, the total). The rest stays as the mocks have it |
 | Proof (a total, a confirmation) | `expectText`, framed and held |
@@ -88,8 +88,10 @@ Before any JSON, write the plan. For each chapter, in this order:
 2. **Behind the card:** the setup it needs, if any.
 3. **Actions** (2–4), each with **what it changes and where** (a row at the
    top, the total at the bottom, a new screen).
-4. **Shots:** the chapter opens on its first push-in: one shot on the area
-   that holds a control *and* what it changes. It ends framing the result.
+4. **Shots:** the chapter opens wide, on the whole window. Push in only
+   where the text is too small to read wide, framing the control *and* what
+   it changes (a live preview included); the engine shows the whole window
+   first. End on the result, framed if it needs reading.
 5. **The card:** statement + benefit, written last (below), and the
    snapshot (`show`) of the result it ends on, if that result is visual.
 6. **Proof:** the value the app shows, checked with `expectText`.
@@ -156,7 +158,10 @@ end     NaviPartner logo · "Now in NP Restaurant."
    - `brandNeeds`: every `config` key and asset slot `setup` uses, each with
      what it is and where it shows. Be specific: a pitch's research fills
      exactly these.
-   - `actions` for what a test does through code (a scanner bridge), and
+   - `actions` for what a test does through code (a scanner bridge, a
+     colour picker, a file upload). An action the viewer sees names its
+     control (`target`), so the cursor goes there and the camera rules
+     apply; don't add holds to make up for a missing one. Also
      `idleTimeoutSeconds` if the app resets when idle.
 3. Write the primary story, then `check` it.
 
@@ -187,10 +192,13 @@ A chapter in steps:
     { "do": "frame", "targets": ["receipt", "receipt-total"] },
     { "do": "hold", "seconds": 2 }
 
-- **Shots:** prefer `frame` (2–4 targets, pushed in as far as they fit) to
-  guessing one `zoom` target. The chapter's first shot is set behind its
-  card. When a click changes something outside the shot, `zoomOut` right
-  after it. End the chapter framing its result.
+- **Shots:** stay wide while the shot reads. When a push-in is needed,
+  prefer `frame` (2–4 targets: the control and what it changes) to guessing
+  one `zoom` target, and keep the live preview in it; use `maxScale` to
+  stay looser. When an action changes something outside the shot,
+  `zoomOut` right after it. When `check` asks for a shot, question the shot
+  before adding a frame: staying wide, or framing the result, is often the
+  better fix.
 - **Typing:** `"replace": true` clears what the field holds first. Type
   short, believable values that change something on screen.
 - **Leave the beats to the engine.** It pauses around every click, settles
@@ -244,7 +252,7 @@ the base story.
 
 Videos are silent: they must work on mute.
 
-## 6. Check, then render
+## 6. Check, then film a draft
 
     pnpm --dir <app> exec demo-video check [--story <name>] --json
 
@@ -254,15 +262,15 @@ how long the video will run against its kind's range. Its error names
 the fix; reference.md lists them all. Its `visible` list shows what is on
 screen at the failing step. Repeat until it passes, at most 3 rounds; a
 story that still fails is reported as "couldn't show this", with the last
-report. Then:
+report. Then film a draft:
 
-    pnpm --dir <app> exec demo-video render [--story <name>]
+    pnpm --dir <app> exec demo-video render --draft [--story <name>]
 
-Rendering films every frame (60 fps), about 15× the video's length, and
-runs a check first when cards show snapshots, to capture them. While tuning,
-`render --draft` films at 30 fps in about half the time. Playwright starts
-the app's dev server from the adapter's `webServer`; if it can't on this
-machine, start it yourself with the same command and env, and it is reused.
+A draft films at 30 fps, in about half the time of the final (which is
+about 15× the video's length). It runs a check first when cards show
+snapshots, to capture them. Playwright starts the app's dev server from the
+adapter's `webServer`; if it can't on this machine, start it yourself with
+the same command and env, and it is reused.
 
 ## 7. Review like a viewer
 
@@ -277,11 +285,31 @@ stills beside it. Judge against look.md:
   screen; chapters end on their result.
 - **Truth:** every word is true of what's on screen.
 
-Adjust the JSON and re-render. Two rounds of tuning is normal; more means
-the plan from step 3 is the problem.
+Adjust the JSON and film another draft. Two rounds of tuning is normal;
+more means the plan from step 3 is the problem.
+
+## 8. The final, only on the developer's go-ahead
+
+Give the developer the draft (its MP4 and contact sheet) and **stop**. Film
+the final 60 fps video only when the developer has watched the latest draft
+and says, specifically, that they are satisfied with the whole flow and want
+the final: "the flow is right, render the final", "go ahead at 60".
+
+These are not a go-ahead, so ask instead ("Happy with the whole flow? Say
+so and I'll render the final at 60 fps."):
+- "looks good" or praise of one part, without asking for the final;
+- approval of an earlier draft;
+- a request for changes, however small;
+- no answer.
+
+A go-ahead covers the draft it was given for. After any change to the
+story, film a new draft and wait for a new go-ahead. Then:
+
+    pnpm --dir <app> exec demo-video render [--story <name>]
 
 ## Report
 
-Give the MP4 path and duration, the chapter plan, the contact sheet, and
-anything the video could not show truthfully (it shows demo fixture data,
-not a real tenant's).
+Give the MP4 path and duration (the draft's, or the final's), the chapter
+plan, the contact sheet, and anything the video could not show truthfully
+(it shows demo fixture data, not a real tenant's). After a draft, say that
+the final waits for their go-ahead.

package/skills/np-demo-video/look.md

@@ -13,10 +13,11 @@ importance:
 2. **No dead time.** Setup happens behind cards, only values that show
    something are typed, and every beat is there so the viewer sees
    something. Never rushed: results and cards stay up long enough to read.
-3. **Purposeful camera.** It moves between shots, never during the action:
-   the chapter opens on the shot that holds the action and its result,
-   holds steady through the clicks, and ends on the result. It never chases
-   the cursor, and there are no hard cuts inside a chapter.
+3. **Purposeful camera.** Every page opens wide, on the whole window. The
+   camera pushes in only where the action would be too small to read, and
+   then only after the viewer has seen where they are. It moves between
+   shots, never during the action, never chases the cursor, and there are no
+   hard cuts inside a chapter.
 4. **Soft, light, branded.** A pale brand-tinted background, a floating app
    window, big serif statements, and the brand colour used boldly.
 5. **Believable data.** The most real-looking records the e2e mocks have.
@@ -104,9 +105,11 @@ text only, centred.
   the receipt that appears), checked by an `expectText`. No invented
   durations or customer statistics.
 - **Never on a card:** testids, barcodes, internal names or any other code.
-- **Reading time:** a card stays up 0.6 s plus ~0.28 s a word (an eyebrow's
-  words count half), at least 1.8 s. The open and end cards stay at most
-  3.5 s in a showcase and 2.5 s in a clip, unless the story asks for more.
+- **Reading time:** a card stays up 0.5 s plus ~0.25 s a word of its
+  statement and ~0.2 s a word of its sub-line (an eyebrow's words 0.12 s),
+  at least 1.6 s. The open and end cards stay at most 3.5 s in a showcase
+  and 2.5 s in a clip, unless the story asks for more. Setup behind a card
+  that takes longer holds it up: `check` says so.
 
 ## Transitions
 
@@ -120,17 +123,19 @@ text only, centred.
 
 ## Camera
 
-- **Wide shot:** the app floats in the middle of the frame at ~90 % width.
-  Small corner radius, soft long shadow, no browser chrome. Wide is for
-  moments that need the whole window (a new screen arriving). A desktop app
-  shown wide is too small to read on a phone, so clicks whose controls and
-  results would fit a push-in get one (`check` asks for it).
-- **A chapter opens on its first shot.** When a chapter starts with a
-  push-in, the camera is already there when its card dissolves: no push-in
-  after every card.
-- **Push in once per shot** on the area that holds the control *and* what it
-  changes, to scale **1.4–1.8** (never past 2: tighter loses the context and
-  softens the picture). The UI should fill the frame and read on a phone.
+- **Wide is the default.** The app floats in the middle of the frame at
+  ~90 % width, with a small corner radius, a soft long shadow and no browser
+  chrome. A wide shot whose text reads (16 px or more on the 1080p frame)
+  needs no push-in.
+- **A page never opens zoomed.** Every chapter opens wide when its card
+  dissolves, and so does every new screen. When a push-in is needed, the
+  whole window is seen first (the engine holds it ~0.8 s), then the camera
+  moves in.
+- **Push in only where it's needed:** where the text is too small to read
+  wide (`check` asks for it), or to read a result. Frame the control *and*
+  what it changes, and no tighter than it takes to read (scale 1.3–1.8,
+  never past 2: tighter loses the context and softens the picture). A live
+  preview that the action changes belongs in the shot.
 - **Hold steady through the action.** The clicks happen inside the shot; the
   camera doesn't move with them. At most two push-ins a chapter.
 - **Show the result.** When an action changes something outside the shot (a
@@ -150,7 +155,11 @@ text only, centred.
   and doesn't pulse, ripple or jerk.
 - **A beat around every click:** it rests on the control (160 ms, its hover
   state shows), presses (110 ms, the pressed state shows), and the app's
-  reaction plays (450 ms) before anything else happens.
+  reaction plays: 450 ms, then until the app has settled (a toast after a
+  save, a preview redrawn), up to a second more.
+- **Every control the viewer sees used gets the cursor**, a colour picker or
+  an upload as much as a button: an adapter action names its control, and
+  the cursor goes there and rests before it acts.
 - Typing runs at ~45 ms a character.
 - Between actions it rests where it doesn't cover what the viewer should
   read.
@@ -238,8 +247,9 @@ the product as the hero), not their technique.
   ([Nemo](https://www.nemovideo.com/blog/kinetic-typography-product-ads),
   [Arcade, 14 million demo sessions](https://www.arcade.software/post/2026-arcade-benchmarks))
 - **Reading time.** Netflix allows at most 20 characters a second, text up
-  0.83–7 s; the BBC works to about 0.3 s a word. Our 0.6 s + 0.28 s a word
-  sits between them.
+  0.83–7 s; the BBC works to about 0.3 s a word. Our cards are read faster
+  than subtitles (0.25 s a statement word, 0.2 s a sub-line word): the viewer
+  isn't also following speech.
   ([Netflix](https://backlothelp.netflix.com/hc/en-us/articles/219375728))
 - **Camera.** Screen Studio's "Focused" motion settles quickly so UI can be
   read; that is the model: quick moves, then stillness.

package/skills/np-demo-video/reference.md

@@ -49,7 +49,7 @@ export default defineDemo({
 | Step | Fields |
 |---|---|
 | `click` | `target`, `nth`, `zoom` (push in on it first, 1.3–2), `behindCard` |
-| `type` | `target`, `nth`, `text`, `perCharMs` (≥ 40, default 45), `replace` (clear the field first; without it the text is added), `behindCard` |
+| `type` | `target`, `nth`, `text`, `perCharMs` (≥ 40, default 45), `replace` (clear the field first; without it the text goes at its end), `behindCard` |
 | `press` | `key`, `behindCard` |
 | `zoom` | `target`, `nth`, `scale` (1.3–2) |
 | `frame` | `targets` (2–4 testids or `{ target, nth }`), `maxScale` (1.3–2, default 1.8) |
@@ -77,16 +77,24 @@ checked by an `expectText` in the story.
 
 **Behind a card:** `behindCard` steps right after a card (or at the very
 start, behind the title card) run while the card covers the app, with no
-cursor and no camera. The chapter's first `zoom` or `frame` is set behind the
-card too, so the chapter opens on it. A card stays up until what's behind it
-is done.
-
-**Camera rules** (`check` enforces them): at most two push-ins a chapter,
-and a push-in needs something done or read in its shot. A click target must
-be inside the current shot. What a zoomed click changes must be in the shot
-or shown by the next step (a `zoomOut`, or a zoom that frames it). Clicks in
-the wide shot whose controls and results would fit a push-in of 1.4 or more
-need one.
+cursor and no camera. `click`, `type`, `press`, `waitFor` and adapter
+actions take it; never a push-in, since every chapter opens wide. A card stays up until what's behind
+it is done: `check` names a card whose setup outlasts its reading time.
+
+**Camera rules** (`check` enforces them): every page opens wide, and a
+push-in from the wide shot comes after the whole window has been seen. At
+most two push-ins a chapter, and a push-in needs something done or read in
+its shot. A control a step uses must be inside the current shot. What it
+changes (watched from the press to the app settling: typing's preview, a
+toast, a restyle) must be in the shot or shown by the next step (a
+`zoomOut`, or a zoom that frames it). A wide shot whose text is under 16 px
+on the frame, where the controls and what they change would fit a push-in
+of 1.4 or more, needs one.
+
+**Adapter actions** may name the control they use (`target(params)`); the
+cursor then goes there and rests, and the camera rules apply as for a
+click. Without one, an action has no cursor and only a short beat after
+it.
 
 **Timing:** the engine adds the beats around clicks, the camera's settle and
 a linger before each card (look.md has the numbers). Holds may not add up
@@ -97,11 +105,11 @@ length against its kind's range (`seconds` and `kind` in `--json`).
 
 | It says | Fix |
 |---|---|
-| `"x" is outside the shot …` | The shot frames the wrong area: frame what this shot clicks, or `zoomOut` first |
-| `clicking "x" changes y, which is outside the shot …` | Frame what the click changes, or `zoomOut` right after the click |
-| `"x" is clicked in the wide shot, but … fit a push-in` | `frame` the controls and what they change; or, if it's setup, `behindCard` |
+| `"x" is outside the shot …` | `zoomOut` first, or frame an area that holds everything the shot uses |
+| `clicking / typing in / using "x" changes y, which is outside the shot …` | `zoomOut` right after, or frame the control with what it changes |
+| `"x" is used in the wide shot, where its text is N px, too small to read …` | `frame` the controls and what they change (the engine pushes in after a wide beat); or, if it's setup, `behindCard` |
 | `N camera push-ins in one chapter` | Push in once on the chapter's area and hold steady |
-| `… only fit in the wide shot` | `frame` things that sit together, or stay wide |
+| `… only fit in the wide shot` | Stay wide, or frame things that sit together |
 | `a zoom with nothing in its shot` | Remove it, or act or read something in it |
 | `zoom 2.4; use 1.3–2` | Zoom less: context reads better and stays sharp |
 | `behindCard only right after a card` | Move the step to just after a card, or drop `behindCard` |