@navipartner/demo-video 0.7.4 → 0.7.5

package/bin/args.d.mts

@@ -22,6 +22,8 @@ export interface DemoArgs {
   draft: boolean;
 }
 export const COMMANDS: readonly string[];
+/** Creates demo/out/ with a .gitignore that ignores all of it. */
+export function makeOutDir(outDir: string): void;
 /** The package.json that makes demo.config.ts CommonJS, or null. */
 export function commonJsDemo(demoDir: string): string | null;
 export function parseArgs(argv: string[], cwd: string): DemoArgs;

package/bin/args.mjs

@@ -14,6 +14,22 @@ const NEEDS_STORYBOARD = new Set(["check", "render", "record"]);
 // Commands whose Playwright run loads demo.config.ts.
 const LOADS_ADAPTER = new Set(["check", "render", "record", "brand-needs"]);
 
+/**
+ * Creates demo/out/ with a .gitignore of its own, so the renders, the
+ * contact sheet and the stills are never committed, whether or not init
+ * added the repo's ignore line.
+ */
+export const makeOutDir = (outDir) => {
+  fs.mkdirSync(outDir, { recursive: true });
+  const ignore = path.join(outDir, ".gitignore");
+  if (!fs.existsSync(ignore)) {
+    fs.writeFileSync(
+      ignore,
+      "# Written by @navipartner/demo-video: nothing here is committed.\n*\n",
+    );
+  }
+};
+
 /**
  * The package.json that makes demo.config.ts CommonJS, or null. Playwright
  * compiles a .ts file as CommonJS unless the nearest package.json says

package/bin/demo-video.mjs

@@ -6,9 +6,9 @@ import { createRequire } from "node:module";
 import os from "node:os";
 import path from "node:path";
 
-import { listStories, parseArgs } from "./args.mjs";
+import { listStories, makeOutDir, parseArgs } from "./args.mjs";
 import { encodeRecording, extractStillsFrom } from "./encode.mjs";
-import { findApps, initApp, initProject } from "./init.mjs";
+import { findApps, initApp, initProject, skillDrift } from "./init.mjs";
 import { appMenu, menuMarkdown, pick } from "./pick.mjs";
 import { buildPitchBrand } from "./pitch.mjs";
 import { writeRunner } from "./runner.mjs";
@@ -38,6 +38,7 @@ const runPlaywright = (args, mode) => {
   const require = createRequire(path.join(args.appDir, "package.json"));
   const cli = require.resolve("@playwright/test/cli");
   fs.rmSync(args.workDir, { recursive: true, force: true });
+  makeOutDir(args.outDir);
   fs.mkdirSync(args.workDir, { recursive: true });
   writeRunner(args);
   const result = spawnSync(
@@ -313,7 +314,7 @@ const runPitch = async (argv) => {
       finish(render, false);
       throw new Error("Filming the pitch draft failed (see above)");
     }
-    fs.mkdirSync(render.outDir, { recursive: true });
+    makeOutDir(render.outDir);
     const result = encodeRecording(render.workDir, render.outDir);
     finish(render, true);
     // The video leaves the repo; its stills and sheet there go.
@@ -363,6 +364,12 @@ const run = () => {
     console.error(error.message);
     return 2;
   }
+  if (["check", "render", "record"].includes(args.command)) {
+    const drift = skillDrift(args.appDir);
+    if (drift) {
+      console.error(drift);
+    }
+  }
   switch (args.command) {
     case "check": {
       const status = runPlaywright(args, "check");
@@ -391,7 +398,7 @@ const run = () => {
         finish(args, false);
         return status;
       }
-      fs.mkdirSync(args.outDir, { recursive: true });
+      makeOutDir(args.outDir);
       const result = encodeRecording(args.workDir, args.outDir);
       finish(args, true);
       if (args.json) {
@@ -404,7 +411,7 @@ const run = () => {
       return 0;
     }
     case "encode": {
-      fs.mkdirSync(args.outDir, { recursive: true });
+      makeOutDir(args.outDir);
       const { output, duration } = encodeRecording(args.workDir, args.outDir);
       finish(args, true);
       console.log(`Wrote ${output} (${duration.toFixed(1)} s)`);

package/bin/init.d.mts

@@ -12,6 +12,8 @@ export function initRepo(
   root: string,
   options?: { dryRun?: boolean; label?: boolean },
 ): InitResult;
+/** A line to print when the repo's copy of the skill isn't this engine's. */
+export function skillDrift(appDir: string): string | null;
 /** The repo's apps (folders with a playwright.config), "." for the root. */
 export function findApps(root: string): string[];
 export function initProject(

package/bin/init.mjs

@@ -87,6 +87,11 @@ const withKey = (object, key, value) => {
   return Object.fromEntries(entries);
 };
 
+// Line endings aside: git may check the repo's copy out with CRLF.
+const sameText = (x, y) =>
+  fs.readFileSync(x, "utf8").replace(/\r\n/g, "\n") ===
+  fs.readFileSync(y, "utf8").replace(/\r\n/g, "\n");
+
 const sameTree = (a, b) => {
   if (!fs.existsSync(b)) {
     return false;
@@ -95,8 +100,37 @@ const sameTree = (a, b) => {
     const [x, y] = [path.join(a, entry.name), path.join(b, entry.name)];
     return entry.isDirectory()
       ? sameTree(x, y)
-      : fs.existsSync(y) && fs.readFileSync(x).equals(fs.readFileSync(y));
+      : fs.existsSync(y) && sameText(x, y);
+  });
+};
+
+/**
+ * What to tell the developer when the repo's copy of the skill (init puts
+ * it in .claude/skills/) isn't this engine's: Claude would follow an older
+ * workflow and look than the engine checks. Null when it is, or when the
+ * repo has no copy.
+ */
+export const skillDrift = (appDir) => {
+  const top = spawnSync("git", ["rev-parse", "--show-toplevel"], {
+    cwd: appDir,
+    encoding: "utf8",
   });
+  if (top.error || top.status !== 0) {
+    return null;
+  }
+  const copy = path.join(
+    top.stdout.trim(),
+    ".claude",
+    "skills",
+    "np-demo-video",
+  );
+  if (
+    !fs.existsSync(copy) ||
+    sameTree(path.join(engineDir, "skills", "np-demo-video"), copy)
+  ) {
+    return null;
+  }
+  return `.claude/skills/np-demo-video isn't the skill of ${PKG} ${engineVersion()}: run "demo-video init" at the repo root to update it.`;
 };
 
 const gitIgnores = (root, file) =>

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

@@ -338,9 +338,11 @@ var stageHtml = (background, appUrl, look, options = {}) => {
     font-family: ${font(look.headingFont)}, Georgia, serif;
     font-size: 116px; font-weight: 400; line-height: 1.08; letter-spacing: -0.015em;
     color: ${look.ink};
+    /* Lines of even length: no word left alone on the last one. */
+    text-wrap: balance;
   }
   .card .heading em { font-style: italic; color: ${look.primary}; }
-  .card .sub { font-size: 40px; font-weight: 400; line-height: 1.3; color: ${look.text}; opacity: 0.85; }
+  .card .sub { font-size: 40px; font-weight: 400; line-height: 1.3; color: ${look.text}; opacity: 0.85; text-wrap: balance; }
   .card.split .heading { font-size: 92px; }
   .card.split .sub { font-size: 36px; }
   .card .still {
@@ -685,6 +687,7 @@ var lintStoryboard = (story) => {
   }
   let chapterStart = 0;
   let pushes = [];
+  let pushedIn = false;
   const endChapter = (end) => {
     if (pushes.length > MAX_PUSHES_PER_CHAPTER) {
       issues.push(
@@ -716,6 +719,7 @@ var lintStoryboard = (story) => {
     if (step.do === "card") {
       endChapter(index);
       chapterStart = index + 1;
+      pushedIn = false;
       lintCard(where, s);
       if (s.eyebrow !== void 0) {
         issues.push(
@@ -742,6 +746,15 @@ var lintStoryboard = (story) => {
     if (shot && pushes.at(-1) !== shot) {
       pushes.push(shot);
     }
+    if (shot && !isBehindCard(step)) {
+      pushedIn = true;
+    }
+    if (step.do === "zoomOut" && pushedIn) {
+      issues.push(
+        `${where}: a pull-out. A push-in stays in until the next card, which takes the camera back to wide: push in on what is read (a dialog, the basket, the confirmation) and stay in, and use what opens something new from the wide shot, before the push-in`
+      );
+      pushedIn = false;
+    }
     if (step.do === "zoom" || step.do === "frame") {
       const rest = steps.slice(index + 1);
       const end = rest.findIndex(

package/dist/index.js

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

package/dist/runner/index.js

@@ -41,7 +41,7 @@ import {
   unionRect,
   visibleRect,
   wideShot
-} from "../chunk-XMOGUZJU.js";
+} from "../chunk-DBH2CI6K.js";
 
 // src/runner/config.ts
 import path from "path";
@@ -266,6 +266,43 @@ import path3 from "path";
 
 // src/changes.ts
 var MAX_RESTYLES = 3;
+var NEW_SCREEN_GONE = 0.5;
+var markScreen = (app) => app.evaluate(() => {
+  const w = window;
+  const read = () => {
+    const texts = [];
+    for (const node of Array.from(document.body.querySelectorAll("*"))) {
+      const own = Array.from(node.childNodes).filter((c) => c.nodeType === Node.TEXT_NODE).map((c) => c.textContent ?? "").join(" ").replace(/\s+/g, " ").trim();
+      if (!own) {
+        continue;
+      }
+      const r = node.getBoundingClientRect();
+      const x = r.x + r.width / 2;
+      const y = r.y + r.height / 2;
+      if (r.width === 0 || r.height === 0 || x < 0 || y < 0 || x > innerWidth || y > innerHeight || !node.checkVisibility({
+        opacityProperty: true,
+        visibilityProperty: true
+      })) {
+        continue;
+      }
+      const top = document.elementFromPoint(x, y);
+      if (top && (node.contains(top) || top.contains(node))) {
+        texts.push({
+          text: own,
+          x: r.x,
+          y: r.y,
+          width: r.width,
+          height: r.height
+        });
+      }
+      if (texts.length >= 300) {
+        break;
+      }
+    }
+    return texts;
+  };
+  w.__demoScreen = { read, before: read() };
+});
 var watchChanges = (target) => target.evaluate((el) => {
   const w = window;
   w.__demoChanges?.observer.disconnect();
@@ -304,6 +341,28 @@ var watchChanges = (target) => target.evaluate((el) => {
   watch.observer = observer;
   w.__demoChanges = watch;
 });
+var newScreen = (app) => app.evaluate((share) => {
+  const screen = window.__demoScreen;
+  if (!screen) {
+    return { x: 0, y: 0, width: innerWidth, height: innerHeight };
+  }
+  if (screen.before.length === 0) {
+    return null;
+  }
+  const now = screen.read();
+  const nowTexts = new Set(now.map((r) => r.text));
+  const beforeTexts = new Set(screen.before.map((r) => r.text));
+  const gone = screen.before.filter((r) => !nowTexts.has(r.text));
+  if (gone.length / screen.before.length < share) {
+    return null;
+  }
+  const moved = [...gone, ...now.filter((r) => !beforeTexts.has(r.text))];
+  const x0 = Math.min(...moved.map((r) => r.x));
+  const y0 = Math.min(...moved.map((r) => r.y));
+  const x1 = Math.max(...moved.map((r) => r.x + r.width));
+  const y1 = Math.max(...moved.map((r) => r.y + r.height));
+  return { x: x0, y: y0, width: x1 - x0, height: y1 - y0 };
+}, NEW_SCREEN_GONE);
 var watching = (app) => app.evaluate(
   () => Boolean(window.__demoChanges)
 );
@@ -348,7 +407,12 @@ var biggestChange = (app) => app.evaluate((maxRestyles) => {
     const hasText = Array.from(node.childNodes).some(
       (c) => c.nodeType === Node.TEXT_NODE && c.textContent?.trim()
     );
-    if (hasText) {
+    const r = node.getBoundingClientRect();
+    const shown = r.width > 0 && r.height > 0 && r.bottom > 0 && r.right > 0 && r.top < innerHeight && r.left < innerWidth && node.checkVisibility({
+      opacityProperty: true,
+      visibilityProperty: true
+    });
+    if (hasText && shown) {
       fontPx = Math.min(fontPx, parseFloat(getComputedStyle(node).fontSize));
     }
   }
@@ -361,6 +425,7 @@ var SHOWN = 0.5;
 var FRAME_MAX_SCALE = 1.8;
 var PUSH_WORTHY = 1.4;
 var READABLE_PX = 16;
+var MOVES_ON_MS = POST_CLICK_MS + REACTION_MS + ZOOM_MS + SETTLE_MS;
 var STILL_MAX_PX = 1600;
 var testIdSelector = (selector) => /^[\w-]+$/.test(selector) ? `[data-testid="${selector}"]` : selector;
 var normalise = (text) => text.replace(/\s+/g, " ").trim();
@@ -397,6 +462,11 @@ var Director = class {
     names: [],
     textPx: Number.POSITIVE_INFINITY
   };
+  /**
+   * The chapter so far: whether it pushed in, and the smallest text its
+   * clicks showed wide. A chapter that stays wide must read wide.
+   */
+  chapter = { pushed: false, textPx: Number.POSITIVE_INFINITY };
   /** When the whole window came into view (virtual ms), for ESTABLISH_MS. */
   wideSince = 0;
   cdp;
@@ -493,8 +563,14 @@ var Director = class {
     this.wasWide = this.isWide();
     this.shot = next;
     this.shotLabel = `the shot on "${t.target}" at ${scale}`;
+    await this.pushedIn();
     await this.moveCamera(next);
   }
+  // The screen a push-in is on is the one it stays on, until the card.
+  async pushedIn() {
+    this.chapter.pushed = true;
+    await markScreen(this.app);
+  }
   // 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) {
@@ -553,6 +629,7 @@ var Director = class {
     this.wasWide = this.isWide();
     this.shot = next;
     this.shotLabel = `the shot framing ${names}`;
+    await this.pushedIn();
     await this.moveCamera(next);
   }
   async zoomOut(options = {}) {
@@ -606,7 +683,7 @@ 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}: zoomOut first, or frame an area that holds everything this shot uses.`
+        `"${t.target}" is outside ${this.shotLabel}: frame an area that holds everything this shot uses, or use it from the wide shot, before the push-in.`
       );
     }
     return { point: this.toStagePoint(rect), rect };
@@ -638,6 +715,7 @@ var Director = class {
       }
     ).catch(() => Number.NaN);
     if (!inner) {
+      await markScreen(this.app);
       await watchChanges(this.locator(t));
     }
     if (filmed) {
@@ -659,6 +737,7 @@ var Director = class {
       await this.page.mouse.click(point.x, point.y);
     }
     await options.then?.();
+    const pressedAt = Date.now();
     if (this.covered) {
       await this.settle(COVERED_SETTLED_MS, COVERED_MAX_MS);
       if (!inner) {
@@ -675,23 +754,60 @@ var Director = class {
     if (inner) {
       return;
     }
+    const biggest = await biggestChange(this.app);
+    const opened = await newScreen(this.app);
     if (zoomed) {
-      await this.assertChangeInShot(t, options.verb);
+      if (this.cropped(opened) || await this.movesOn(pressedAt)) {
+        throw new Error(
+          `${options.verb} "${t.target}" opens a new screen or dialog under the push-in, so it would show cropped: use it from the wide shot (no push-in before it), and push in on the new screen once it has been seen whole.`
+        );
+      }
+      this.assertChangeInShot(t, options.verb, biggest);
       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
-      );
+    ) * this.layout.fit;
+    this.chapter.textPx = Math.min(this.chapter.textPx, smallest);
+    if (opened) {
+      return;
+    }
+    this.wideUse.rects.push(rect, ...biggest ? [biggest.rect] : []);
+    this.wideUse.names.push(t.target);
+    this.wideUse.textPx = Math.min(this.wideUse.textPx, smallest);
+  }
+  // After a press under a push-in, in check: the time render's beat and a
+  // camera move would take, watching for a screen that moves on by itself.
+  // The screen as the reaction left it is what the push-in stays on.
+  async movesOn(pressedAt) {
+    await markScreen(this.app);
+    if (!this.fast) {
+      return false;
     }
+    while (Date.now() - pressedAt < MOVES_ON_MS) {
+      await this.page.waitForTimeout(POLL_MS);
+      if (this.cropped(await newScreen(this.app))) {
+        return true;
+      }
+    }
+    return false;
+  }
+  // A new screen (where its texts left and arrived) that the shot doesn't
+  // hold whole. A list filtered inside the shot is not one.
+  cropped(screen) {
+    return screen !== null && !shows(this.layout, this.shot, screen);
+  }
+  // While pushed in, the screen stays the one the push-in is on: a screen
+  // the app moves on to (after a wait, a hold, by an action) would show
+  // cropped. Check skips holds, so there only render catches a timer.
+  async assertSameScreen() {
+    if (this.isWide() || this.covered || !this.cropped(await newScreen(this.app))) {
+      return;
+    }
+    throw new Error(
+      "the app moves on to a new screen while the camera is pushed in, so it would show cropped: push in only on a screen the chapter then stays on, and do what leads to the next one from the wide shot."
+    );
   }
   // Until nothing in the app has changed for `quiet` ms, at most `max` ms:
   // filmed on the virtual clock, in real time in check.
@@ -728,15 +844,14 @@ 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, verb) {
-    const biggest = await biggestChange(this.app);
+  assertChangeInShot(t, verb, biggest) {
     if (!biggest) {
       return;
     }
     if (coverage(biggest.rect, visibleRect(this.layout, this.shot)) < SHOWN) {
       this.unseen = {
         rect: biggest.rect,
-        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.`
+        message: `${verb} "${t.target}" changes ${biggest.label}, which is outside ${this.shotLabel}, and the next step doesn't show it: frame the control with what it changes, or use it from the wide shot.`
       };
     }
   }
@@ -797,6 +912,19 @@ var Director = class {
   end() {
     this.requireSeen("other");
     this.closeWide();
+    this.closeChapter();
+  }
+  // A chapter ends (a card, the end). One that never pushed in must have
+  // read wide: a portrait kiosk scaled into the frame, or small text, gives
+  // the viewer nothing to read on a phone.
+  closeChapter() {
+    const { pushed, textPx } = this.chapter;
+    this.chapter = { pushed: false, textPx: Number.POSITIVE_INFINITY };
+    if (!pushed && textPx < READABLE_PX) {
+      throw new Error(
+        `the chapter before this stays wide, where its text is ${Math.round(textPx)} px on the frame, too small to read: push in on what the viewer should read (the result it ends on), and stay in until the card.`
+      );
+    }
   }
   async during(work, options = {}) {
     const recorder = this.options.recorder;
@@ -815,6 +943,7 @@ var Director = class {
     this.requireSeen("other");
     const result = await run();
     await this.wait(POST_ACTION_MS);
+    await this.assertSameScreen();
     return result;
   }
   // --- waits and checks ------------------------------------------------------------
@@ -826,6 +955,7 @@ var Director = class {
       options.timeoutMs,
       () => `"${t.target}" did not ${options.hidden ? "disappear" : "appear"} within ${options.timeoutMs / 1e3} s`
     );
+    await this.assertSameScreen();
   }
   async expectText(t, text, options) {
     this.requireSeen("other");
@@ -846,15 +976,19 @@ var Director = class {
       options.timeoutMs,
       () => `expected "${want}"${options.contains ? " (contains)" : ""}, saw "${last}"`
     );
+    await this.assertSameScreen();
   }
   async hold(ms) {
     this.requireSeen("other");
     await this.wait(ms);
+    await this.assertSameScreen();
   }
   // --- overlays --------------------------------------------------------------------
   async card(spec, options = {}) {
     this.requireSeen("other");
+    await this.assertSameScreen();
     this.closeWide();
+    this.closeChapter();
     this.shot = wideShot(this.layout);
     this.shotLabel = "the wide shot";
     if (this.fast) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@navipartner/demo-video",
-  "version": "0.7.4",
+  "version": "0.7.5",
   "description": "Marketing demo videos of a React app, filmed by Playwright against the app's own e2e mocks.",
   "license": "UNLICENSED",
   "repository": {

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

@@ -89,9 +89,11 @@ Before any JSON, write the plan. For each chapter, in this order:
 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 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.
+   where the text is too small to read wide, framing what is read: the
+   control *and* what it changes (a live preview included), or the result
+   (a dialog, the basket). The engine shows the whole window first, and
+   the camera stays in until the card, so taps that open a new screen come
+   before the push-in. 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`.
@@ -112,8 +114,8 @@ ch1     sees: a guest scans two waters and they land in the basket
               show: basket
 ch2     sees: the guest pays by card and the payment goes through
         behind: —
-        shots: frame "Go to payment" + total; pull out when payment opens;
-               end framing the receipt
+        shots: wide: "Go to payment" opens a new screen; pay wide too;
+               end framing the receipt, held until the card
         card: "Pay *by card*." / "Tap, insert or phone: the terminal takes it."
               show: receipt
 payoff  "Paid *in seconds*." · sub "64,50 kr. by card." (expectText on the total)
@@ -184,21 +186,23 @@ A chapter in steps:
     { "do": "card", "heading": "Pay *by card*.",
       "sub": "Tap, insert or phone: the terminal takes it.", "show": "receipt" },
     { "do": "click", "target": "accept-terms", "behindCard": true },
-    { "do": "frame", "targets": ["pay-button", "order-total"] },
     { "do": "expectText", "target": "order-total", "text": "64,50 kr." },
     { "do": "click", "target": "pay-button" },
-    { "do": "zoomOut" },
     { "do": "waitFor", "target": "receipt" },
     { "do": "frame", "targets": ["receipt", "receipt-total"] },
     { "do": "hold", "seconds": 2 }
 
-- **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.
+- **Shots:** stay wide while the shot reads. When it doesn't, push in on
+  what the viewer reads (a dialog, the basket, the receipt) and stay in until the next
+  card, which takes the camera back to wide; never pull out (`check`
+  refuses a `zoomOut` after a push-in). A tap that opens a new screen or
+  dialog happens wide, so what it opens is seen whole first: `check`
+  refuses it under a push-in, also when the screen moves on by itself a
+  moment later (a payment going on to "processing"). 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
+  `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
@@ -266,8 +270,9 @@ report. Then film a draft:
 
     pnpm --dir <app> exec demo-video render --draft [--story <name>]
 
-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
+A draft films at 30 fps, in about half the time of the final (which takes
+6–15× the video's length, depending on the machine; a developer laptop is
+at the low end). 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.

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

@@ -15,7 +15,8 @@ importance:
    something. Never rushed: results and cards stay up long enough to read.
 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
+   then only after the viewer has seen where they are; once in, it stays
+   in until the next card. 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
@@ -128,22 +129,29 @@ text only, centred.
   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
+  dissolves, and so does every new screen or dialog, the first time it is
+  seen: a tap that opens one is made from the wide shot, also when the
+  screen moves on by itself a moment later. 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.
+- **Push in only to read:** where the text is too small to read wide
+  (`check` asks for it), and then on what the viewer reads (a dialog, the
+  basket, the confirmation), not on the control that leads there. A
+  portrait app scaled into the frame almost always needs it. 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.
+- **Never pull out.** A push-in stays in until the next card, which takes
+  the camera back to wide behind it. In and out on the same screen is
+  wasted motion: do the taps that open something new wide, before the
+  push-in.
 - **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
-  row added at the top, a new screen), pull out right after it. A push-in
+- **Show the result.** What an action changes is in its shot. A push-in
   that shows a button pressed and nothing happening is the worst shot.
 - **End on the result.** The last shot of a chapter frames what it achieved
   (the pass with its wallet badge, the receipt), held long enough to read,
-  then the card covers it.
+  then the card covers it, still pushed in.
 - **Each move eases in and out** (engine: 900 ms,
   `cubic-bezier(0.65, 0, 0.35, 1)`), then settles 150 ms before anything
   happens.

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

@@ -58,7 +58,7 @@ export default defineDemo({
 | `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) |
-| `zoomOut` | `park` (rest the cursor too) |
+| `zoomOut` | `park` (rest the cursor too). Never after a push-in: a card takes the camera back to wide |
 | `park` | rests the cursor in empty space |
 | `waitFor` | `target`, `nth`, `hidden`, `timeout` (s), `behindCard` |
 | `expectText` | `target`, `nth`, `text`, `contains`, `timeout` (s) |
@@ -91,10 +91,19 @@ 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.
+toast, a restyle) must be in the shot or framed by the next step. A
+push-in stays in until the next card: no `zoomOut` after one. A tap that
+opens a new screen or dialog (most of what was read is gone or covered,
+and the shot doesn't hold all that changed), or one after which the app
+moves on by itself within about 2.5 s, happens wide; so does whatever the
+app moves on to while pushed in (a wait, a hold, an action; check skips
+holds, so a timer there only fails render). A list filtered inside the
+shot is not a new screen. 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 (taps that open a new
+screen don't count: they stay wide). A chapter that never pushes in needs
+text of 16 px or more on the frame throughout; a portrait kiosk scaled
+into the frame rarely has it.
 
 **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
@@ -110,8 +119,12 @@ length against its kind's range (`seconds` and `kind` in `--json`).
 
 | It says | Fix |
 |---|---|
-| `"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 outside the shot …` | Frame an area that holds everything the shot uses, or use `x` wide, before the push-in |
+| `clicking / typing in / using "x" changes y, which is outside the shot …` | Frame the control with what it changes, or use it wide |
+| `clicking "x" opens a new screen or dialog under the push-in …` | Drop the push-in before it: tap wide, then push in on the new screen if it needs reading |
+| `the app moves on to a new screen while the camera is pushed in …` | Don't push in on a screen that moves on by itself; push in on the one it moves to |
+| `a pull-out` | Remove the `zoomOut`: end the chapter pushed in on its result, or do the wide taps before the push-in |
+| `the chapter before this stays wide, where its text is N px …` | Push in on the result the chapter ends on (`frame` it) and hold until the card |
 | `"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` | Stay wide, or frame things that sit together |