@navipartner/demo-video 0.6.0 → 0.7.1

package/dist/runner/index.js

@@ -1,6 +1,8 @@
 import {
   CARD_IN_MS,
   CARD_OUT_MS,
+  CURSOR_MAX_MS,
+  CURSOR_MIN_MS,
   DEFAULT_VIEWPORT,
   LINGER_MS,
   MIN_SCALE,
@@ -15,11 +17,14 @@ import {
   STAGE_HEIGHT,
   STAGE_PATH,
   STAGE_WIDTH,
+  STILLS_PATH,
   StoryboardError,
+  TYPE_CHAR_MS,
   ZOOM_MS,
   cardSeconds,
   coverage,
   fittingScale,
+  isBehindCard,
   isCoreStep,
   lintStoryboard,
   loadStoryboard,
@@ -27,10 +32,11 @@ import {
   shows,
   stageHtml,
   stageLayout,
+  titleSeconds,
   unionRect,
   visibleRect,
   wideShot
-} from "../chunk-D7UYGNSF.js";
+} from "../chunk-RMBVQL2J.js";
 
 // src/runner/config.ts
 import path from "path";
@@ -67,8 +73,8 @@ var createDemoConfig = (adapter, demoDir, runnerDir, mode = process.env.DEMO_MOD
 });
 
 // src/runner/register.ts
-import fs3 from "fs";
-import path4 from "path";
+import fs4 from "fs";
+import path5 from "path";
 
 // src/brand.ts
 import fs from "fs";
@@ -249,6 +255,10 @@ var missingNeeds = (brand, needs = {}) => {
   ];
 };
 
+// src/director.ts
+import fs2 from "fs";
+import path3 from "path";
+
 // src/changes.ts
 var watchChanges = (target) => target.evaluate((el) => {
   const changed = /* @__PURE__ */ new Set();
@@ -303,6 +313,8 @@ var biggestChange = (app) => app.evaluate(() => {
 var TARGET_TIMEOUT_MS = 15e3;
 var SHOWN = 0.5;
 var FRAME_MAX_SCALE = 1.8;
+var PUSH_WORTHY = 1.4;
+var STILL_MAX_PX = 1600;
 var testIdSelector = (selector) => /^[\w-]+$/.test(selector) ? `[data-testid="${selector}"]` : selector;
 var normalise = (text) => text.replace(/\s+/g, " ").trim();
 var sameShot = (a, b) => Math.abs(a.k - b.k) < 1e-3 && Math.abs(a.tx - b.tx) < 1 && Math.abs(a.ty - b.ty) < 1;
@@ -327,6 +339,17 @@ var Director = class {
    * what the click did.
    */
   unseen;
+  /** Behind a card: no cursor, no camera moves, nothing for the viewer. */
+  covered = false;
+  /**
+   * What clicks in the current wide shot used: their controls and what they
+   * changed. When the wide shot ends, all of it must not have fit a push-in.
+   */
+  wideUse = {
+    rects: [],
+    names: []
+  };
+  cdp;
   get fast() {
     return this.options.fast;
   }
@@ -410,6 +433,7 @@ var Director = class {
   }
   // --- camera -----------------------------------------------------------------
   async zoomTo(t, scale) {
+    this.closeWide();
     const rect = await this.appRect(t);
     const next = shotFor(this.layout, rect, scale);
     this.requireSeen("zoom", next);
@@ -418,13 +442,25 @@ var Director = class {
     }
     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.
+  async moveCamera(shot) {
     if (this.fast) {
       return;
     }
-    await this.page.evaluate((s) => window.__demo.setShot(s), next);
-    await this.wait(ZOOM_MS + SETTLE_MS);
+    const instant = this.covered;
+    await this.page.evaluate(([s, i]) => window.__demo.setShot(s, i), [
+      shot,
+      instant
+    ]);
+    if (!instant) {
+      await this.wait(ZOOM_MS + SETTLE_MS);
+    }
   }
   async frame(targets, options = {}) {
+    this.closeWide();
     const names = targets.map((t) => `"${t.target}"`).join(" and ");
     for (const t of targets) {
       await this.appRect(t);
@@ -461,11 +497,7 @@ var Director = class {
     }
     this.shot = next;
     this.shotLabel = `the shot framing ${names}`;
-    if (this.fast) {
-      return;
-    }
-    await this.page.evaluate((s) => window.__demo.setShot(s), next);
-    await this.wait(ZOOM_MS + SETTLE_MS);
+    await this.moveCamera(next);
   }
   async zoomOut(options = {}) {
     this.requireSeen("zoomOut");
@@ -492,7 +524,7 @@ var Director = class {
   // --- cursor + input -----------------------------------------------------------
   /** Rests the cursor in empty space, off the content. */
   async park() {
-    if (this.fast) {
+    if (this.fast || this.covered) {
       return;
     }
     const ms = await this.page.evaluate(
@@ -513,7 +545,7 @@ var Director = class {
         `"${t.target}" is outside ${this.shotLabel}. Zoom on an area that holds everything this shot uses, or zoomOut first.`
       );
     }
-    return this.toStagePoint(rect);
+    return { point: this.toStagePoint(rect), rect };
   }
   async click(t, options = {}) {
     if (options.zoom !== void 0) {
@@ -521,16 +553,20 @@ var Director = class {
     } else {
       this.requireSeen("other");
     }
-    const point = await this.pointAt(t);
+    const { point, rect } = await this.pointAt(t);
     const zoomed = this.shot.k > this.layout.fit * 1.01;
-    if (zoomed) {
+    const wide = !zoomed && !this.covered;
+    if (zoomed || wide) {
       await watchChanges(this.locator(t));
     }
     if (this.fast) {
       await this.page.mouse.click(point.x, point.y);
-      if (zoomed) {
+      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 {
       const ms = await this.page.evaluate(
         ([x, y]) => window.__demo.cursorTo(x, y),
@@ -546,6 +582,27 @@ var Director = class {
     }
     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);
+    }
+  }
+  // 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) {
+      return;
+    }
+    const scale = fittingScale(this.layout, unionRect(rects));
+    if (scale >= PUSH_WORTHY) {
+      const clicked = [...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`
+      );
     }
   }
   // A zoomed shot is about what the click does. If the biggest thing the
@@ -579,10 +636,14 @@ var Director = class {
     }
     throw new Error(unseen.message);
   }
-  async type(t, text, perCharMs = 70) {
+  async type(t, text, perCharMs = TYPE_CHAR_MS, options = {}) {
     await this.click(t);
-    if (this.fast) {
+    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) {
@@ -603,6 +664,7 @@ var Director = class {
   /** After the last step: a zoomed click's change must have been shown. */
   end() {
     this.requireSeen("other");
+    this.closeWide();
   }
   async during(work) {
     this.requireSeen("other");
@@ -651,24 +713,84 @@ var Director = class {
   // --- overlays --------------------------------------------------------------------
   async card(spec, options = {}) {
     this.requireSeen("other");
+    this.closeWide();
     this.shot = wideShot(this.layout);
     this.shotLabel = "the wide shot";
     if (this.fast) {
+      await this.behind(options.behind);
       return;
     }
-    await this.showCard(spec);
-    await this.wait(CARD_IN_MS);
+    if (!options.opening) {
+      await this.showCard(spec);
+      await this.wait(CARD_IN_MS);
+    }
     await this.page.evaluate(() => {
       window.__demo.resetCamera();
       window.__demo.parkNow();
     });
     await this.page.mouse.move(PARK.x, PARK.y);
-    await this.wait(cardSeconds(spec) * 1e3);
+    const started = this.clockMs();
+    await this.behind(options.behind);
+    await this.page.mouse.move(PARK.x, PARK.y);
+    const readMs = (options.opening ? titleSeconds(spec, options.kind) : cardSeconds(spec)) * 1e3;
+    await this.wait(readMs - (this.clockMs() - started));
     if (!options.keepUp) {
       await this.hideCard();
       await this.wait(CARD_OUT_MS);
     }
   }
+  async behind(work) {
+    if (!work) {
+      return;
+    }
+    this.covered = true;
+    try {
+      await work();
+    } finally {
+      this.covered = false;
+    }
+  }
+  async capture(t, file) {
+    const locator = this.locator(t);
+    if (!await locator.isVisible().catch(() => false)) {
+      return false;
+    }
+    const r = await this.readRect(locator);
+    const { width, height } = this.layout.viewport;
+    const x0 = Math.max(0, r.x);
+    const y0 = Math.max(0, r.y);
+    const x1 = Math.min(width, r.x + r.width);
+    const y1 = Math.min(height, r.y + r.height);
+    if (x1 - x0 < 1 || y1 - y0 < 1) {
+      return false;
+    }
+    const shot = this.fast ? wideShot(this.layout) : this.shot;
+    const k = shot.k;
+    const left = Math.ceil(this.layout.left + shot.tx + k * x0);
+    const top = Math.ceil(this.layout.top + shot.ty + k * y0);
+    const right = Math.floor(this.layout.left + shot.tx + k * x1);
+    const bottom = Math.floor(this.layout.top + shot.ty + k * y1);
+    if (right - left < 1 || bottom - top < 1) {
+      return false;
+    }
+    this.cdp ??= await this.page.context().newCDPSession(this.page);
+    const { data } = await this.cdp.send("Page.captureScreenshot", {
+      format: "png",
+      clip: {
+        x: left,
+        y: top,
+        width: right - left,
+        height: bottom - top,
+        scale: Math.min(
+          2 / k,
+          STILL_MAX_PX / Math.max(right - left, bottom - top)
+        )
+      }
+    });
+    fs2.mkdirSync(path3.dirname(file), { recursive: true });
+    fs2.writeFileSync(file, Buffer.from(data, "base64"));
+    return true;
+  }
   /** `instant` puts the card up with no dissolve (the video's first frame). */
   async showCard(spec, instant = false) {
     if (!this.fast) {
@@ -698,10 +820,321 @@ var Director = class {
   }
 };
 
+// src/run.ts
+var CAMERA_MOVE_MS = ZOOM_MS + SETTLE_MS;
+var CARD_DISSOLVE_MS = CARD_IN_MS + CARD_OUT_MS;
+var IDLE_MARGIN_MS = 1e4;
+var INTERACTIONS = /* @__PURE__ */ new Set(["click", "type", "press"]);
+var CAMERA_MOVES = /* @__PURE__ */ new Set(["zoom", "frame", "zoomOut"]);
+var describeTarget = (t) => typeof t === "string" ? t : typeof t === "object" && t !== null && "target" in t ? `${String(t.target)}${"nth" in t && typeof t.nth === "number" ? `[${t.nth}]` : ""}` : "";
+var describeStep = (step) => {
+  if ("targets" in step && Array.isArray(step.targets)) {
+    return `${step.do} ${step.targets.map(describeTarget).join(" + ")}`;
+  }
+  const target = "target" in step ? describeTarget(step) : "";
+  return `${step.do}${target ? ` ${target}` : ""}`;
+};
+var StepError = class extends Error {
+  constructor(index, step, reason, visible) {
+    super(`Step ${index + 1} (${describeStep(step)}) failed: ${reason}`);
+    this.index = index;
+    this.step = step;
+    this.reason = reason;
+    this.visible = visible;
+  }
+  index;
+  step;
+  reason;
+  visible;
+};
+var reasonOf = (cause) => {
+  if (cause && typeof cause === "object" && "issues" in cause && Array.isArray(cause.issues)) {
+    return cause.issues.map((i) => `${i.path.join(".") || "(params)"}: ${i.message}`).join("; ");
+  }
+  const text = cause instanceof Error ? cause.message : String(cause);
+  return text.split("\n")[0].trim();
+};
+var runStep = async (d, step, adapter) => {
+  if (isCoreStep(step)) {
+    switch (step.do) {
+      case "click":
+        return d.click(step, { zoom: step.zoom });
+      case "type":
+        return d.type(step, step.text, step.perCharMs, {
+          replace: step.replace
+        });
+      case "press":
+        return d.press(step.key);
+      case "zoom":
+        return d.zoomTo(step, step.scale);
+      case "frame":
+        return d.frame(
+          step.targets.map((t) => typeof t === "string" ? { target: t } : t),
+          { maxScale: step.maxScale }
+        );
+      case "zoomOut":
+        return d.zoomOut({ park: step.park });
+      case "park":
+        return d.park();
+      case "waitFor":
+        return d.waitFor(step, {
+          hidden: step.hidden,
+          timeoutMs: step.timeout * 1e3
+        });
+      case "expectText":
+        return d.expectText(step, step.text, {
+          contains: step.contains,
+          timeoutMs: step.timeout * 1e3
+        });
+      case "hold":
+        return d.hold(step.seconds * 1e3);
+      case "card":
+        throw new Error("a card is run by runSteps, not runStep");
+    }
+  }
+  const action = adapter.actions?.[step.do];
+  if (!action) {
+    throw new Error(`unknown step "${step.do}"`);
+  }
+  const params = Object.fromEntries(
+    Object.entries(step).filter(([key]) => key !== "do")
+  );
+  const parsed = action.params.parse(params);
+  await d.during(() => action.run(d, parsed));
+};
+var needsLinger = (previous) => previous !== void 0 && previous.do !== "hold" && previous.do !== "card" && !isBehindCard(previous);
+var TITLE = -1;
+var planCards = (steps, hasTitle) => {
+  const plans = /* @__PURE__ */ new Map();
+  const starts = [
+    ...hasTitle ? [TITLE] : [],
+    ...steps.flatMap((s, i) => s.do === "card" ? [i] : [])
+  ];
+  for (const start of starts) {
+    const behind = [];
+    let j = start + 1;
+    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"
+    });
+  }
+  [...plans.entries()].filter(([at, plan]) => at !== TITLE && plan.opens).forEach(([, plan], n) => {
+    plan.chapter = n + 1;
+  });
+  return plans;
+};
+var toTarget = (t) => typeof t === "string" ? { target: t } : t;
+var cardSpecFor = (card, plan, still) => ({
+  eyebrow: card.eyebrow,
+  heading: card.heading,
+  sub: card.sub,
+  logo: card.logo,
+  seconds: card.seconds,
+  style: card.style ?? (plan?.chapter !== void 0 && plan.chapter % 2 === 0 ? "brand" : "pale"),
+  ...still ? { still } : {}
+});
+var stillCards = (steps, title) => [
+  ...title?.show !== void 0 ? [TITLE] : [],
+  ...steps.flatMap(
+    (s, i) => s.do === "card" && s.show !== void 0 ? [i] : []
+  )
+];
+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;
+  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.`
+  );
+  const plans = planCards(steps, Boolean(options.title));
+  const covered = new Set([...plans.values()].flatMap((p) => p.behind));
+  let pending;
+  const hero = options.title?.show && options.stillFile ? { target: toTarget(options.title.show), seen: false } : void 0;
+  const fail = async (index, cause) => {
+    if (cause instanceof StepError) {
+      throw cause;
+    }
+    const visible = await d.visibleTestIds().catch(() => []);
+    throw new StepError(index, steps[index], reasonOf(cause), visible);
+  };
+  const settlePending = async () => {
+    const was = pending;
+    pending = void 0;
+    if (was && !was.seen) {
+      await fail(
+        was.card,
+        new Error(
+          `"${was.target.target}" (show) never appears in the chapter after this card, so there is no still to put on it`
+        )
+      );
+    }
+  };
+  const runCard = async (at) => {
+    const plan = plans.get(at);
+    const card = at === TITLE ? options.title : steps[at];
+    const show = card.show ? toTarget(card.show) : void 0;
+    if (show && options.stillFile && at !== TITLE) {
+      if (plan?.opens) {
+        pending = { card: at, target: show, seen: false };
+      } else if (!await d.capture(show, options.stillFile(at))) {
+        throw new Error(
+          `"${show.target}" (show) isn't on screen when this card comes up`
+        );
+      }
+    }
+    const behind = plan?.behind ?? [];
+    const last = behind.at(-1) ?? at;
+    const next = steps[last + 1] ?? (last === steps.length - 1 && options.keepLastCardUp ? { do: "card" } : void 0);
+    await d.card(
+      cardSpecFor(
+        card,
+        plan,
+        show && options.stillUrl ? options.stillUrl(at) : void 0
+      ),
+      {
+        keepUp: next?.do === "card",
+        opening: at === TITLE,
+        kind: options.kind,
+        behind: behind.length ? async () => {
+          for (const index of behind) {
+            await runOne(index);
+          }
+        } : void 0
+      }
+    );
+  };
+  const runOne = async (index) => {
+    const step = steps[index];
+    if (step.do === "card") {
+      await settlePending();
+    }
+    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) {
+          throw tooQuiet();
+        }
+      }
+      if (linger) {
+        await d.hold(LINGER_MS);
+      }
+      const started = d.clockMs();
+      if (step.do === "card") {
+        await runCard(index);
+      } else {
+        await runStep(d, step, adapter);
+      }
+      if (WAITS.has(step.do)) {
+        quietMs += d.clockMs() - started;
+        if (quietMs > idleLimitMs) {
+          throw tooQuiet();
+        }
+      }
+      if (INTERACTIONS.has(step.do) || adapter.actions?.[step.do]) {
+        quietMs = 0;
+      }
+    } catch (cause) {
+      await fail(index, cause);
+    }
+    if (pending && step.do !== "card" && options.stillFile) {
+      const seen = await d.capture(
+        pending.target,
+        options.stillFile(pending.card)
+      );
+      pending.seen ||= seen;
+    }
+    if (hero && step.do !== "card" && options.stillFile) {
+      hero.seen ||= await d.capture(hero.target, options.stillFile(TITLE));
+    }
+  };
+  if (options.title) {
+    quietMs += titleSeconds(options.title, options.kind) * 1e3 + CARD_OUT_MS;
+    await runCard(TITLE);
+  }
+  for (const index of steps.keys()) {
+    if (!covered.has(index)) {
+      await runOne(index);
+    }
+  }
+  await settlePending();
+  if (hero && !hero.seen) {
+    throw new Error(
+      `title.show: "${hero.target.target}" never appears in the story, so the open card has no snapshot`
+    );
+  }
+};
+
+// src/estimate.ts
+var CURSOR_MS = (CURSOR_MIN_MS + CURSOR_MAX_MS) / 2;
+var CLICK_MS = CURSOR_MS + PRE_CLICK_MS + PRESS_MS + POST_CLICK_MS;
+var CAMERA_MS = ZOOM_MS + SETTLE_MS;
+var stepMs = (step) => {
+  const s = step;
+  switch (step.do) {
+    case "click":
+      return CLICK_MS + (s.zoom !== void 0 ? CAMERA_MS : 0);
+    case "type":
+      return CLICK_MS + String(s.text).length * Number(s.perCharMs ?? TYPE_CHAR_MS) + POST_KEY_MS;
+    case "press":
+      return POST_KEY_MS;
+    case "zoom":
+    case "frame":
+    case "zoomOut":
+      return CAMERA_MS;
+    case "park":
+      return CURSOR_MS;
+    case "hold":
+      return Number(s.seconds) * 1e3;
+    case "waitFor":
+    case "expectText":
+      return 0;
+    default:
+      return POST_ACTION_MS + CURSOR_MS;
+  }
+};
+var estimateSeconds = (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;
+  if (story.title) {
+    ms += titleSeconds(story.title, story.kind) * 1e3;
+    ms += after(TITLE)?.do === "card" ? 0 : CARD_OUT_MS;
+  }
+  steps.forEach((step, i) => {
+    if (covered.has(i)) {
+      return;
+    }
+    if (step.do !== "card") {
+      ms += stepMs(step);
+      return;
+    }
+    const previous = steps[i - 1];
+    const linger = previous !== void 0 && previous.do !== "hold" && previous.do !== "card" && !isBehindCard(previous);
+    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;
+  });
+  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);
+};
+
 // src/frames.ts
 import { spawn } from "child_process";
-import fs2 from "fs";
-import path3 from "path";
+import fs3 from "fs";
+import path4 from "path";
 import ffmpegPath from "ffmpeg-static";
 var FPS = 60;
 var DRAFT_FPS = 30;
@@ -712,8 +1145,8 @@ var FrameRecorder = class {
     this.workDir = workDir;
     this.stem = stem;
     this.fps = fps;
-    this.rawDir = path3.join(workDir, "raw");
-    this.videoPath = path3.join(this.rawDir, "stage.mkv");
+    this.rawDir = path4.join(workDir, "raw");
+    this.videoPath = path4.join(this.rawDir, "stage.mkv");
   }
   page;
   workDir;
@@ -748,13 +1181,13 @@ var FrameRecorder = class {
   }
   /** Starts writing frames. Time advanced before this is not filmed. */
   start() {
-    if (!ffmpegPath || !fs2.existsSync(ffmpegPath)) {
+    if (!ffmpegPath || !fs3.existsSync(ffmpegPath)) {
       throw new Error(
         "ffmpeg-static has no binary; with pnpm >= 10, allow its install script (onlyBuiltDependencies) and reinstall."
       );
     }
-    fs2.rmSync(this.rawDir, { recursive: true, force: true });
-    fs2.mkdirSync(this.rawDir, { recursive: true });
+    fs3.rmSync(this.rawDir, { recursive: true, force: true });
+    fs3.mkdirSync(this.rawDir, { recursive: true });
     const ffmpeg = spawn(
       ffmpegPath,
       [
@@ -963,138 +1396,14 @@ var FrameRecorder = class {
       endAt: null,
       storyboard: this.stem
     };
-    fs2.writeFileSync(
-      path3.join(this.workDir, "manifest.json"),
+    fs3.writeFileSync(
+      path4.join(this.workDir, "manifest.json"),
       JSON.stringify(manifest, null, 2)
     );
     return manifest;
   }
 };
 
-// src/run.ts
-var CAMERA_MOVE_MS = ZOOM_MS + SETTLE_MS;
-var CARD_DISSOLVE_MS = CARD_IN_MS + CARD_OUT_MS;
-var IDLE_MARGIN_MS = 1e4;
-var INTERACTIONS = /* @__PURE__ */ new Set(["click", "type", "press"]);
-var CAMERA_MOVES = /* @__PURE__ */ new Set(["zoom", "frame", "zoomOut"]);
-var describeTarget = (t) => typeof t === "string" ? t : typeof t === "object" && t !== null && "target" in t ? `${String(t.target)}${"nth" in t && typeof t.nth === "number" ? `[${t.nth}]` : ""}` : "";
-var describeStep = (step) => {
-  if ("targets" in step && Array.isArray(step.targets)) {
-    return `${step.do} ${step.targets.map(describeTarget).join(" + ")}`;
-  }
-  const target = "target" in step ? describeTarget(step) : "";
-  return `${step.do}${target ? ` ${target}` : ""}`;
-};
-var StepError = class extends Error {
-  constructor(index, step, reason, visible) {
-    super(`Step ${index + 1} (${describeStep(step)}) failed: ${reason}`);
-    this.index = index;
-    this.step = step;
-    this.reason = reason;
-    this.visible = visible;
-  }
-  index;
-  step;
-  reason;
-  visible;
-};
-var reasonOf = (cause) => {
-  if (cause && typeof cause === "object" && "issues" in cause && Array.isArray(cause.issues)) {
-    return cause.issues.map((i) => `${i.path.join(".") || "(params)"}: ${i.message}`).join("; ");
-  }
-  const text = cause instanceof Error ? cause.message : String(cause);
-  return text.split("\n")[0].trim();
-};
-var runStep = async (d, step, adapter, next) => {
-  if (isCoreStep(step)) {
-    switch (step.do) {
-      case "click":
-        return d.click(step, { zoom: step.zoom });
-      case "type":
-        return d.type(step, step.text, step.perCharMs);
-      case "press":
-        return d.press(step.key);
-      case "zoom":
-        return d.zoomTo(step, step.scale);
-      case "frame":
-        return d.frame(
-          step.targets.map((t) => typeof t === "string" ? { target: t } : t),
-          { maxScale: step.maxScale }
-        );
-      case "zoomOut":
-        return d.zoomOut({ park: step.park });
-      case "park":
-        return d.park();
-      case "waitFor":
-        return d.waitFor(step, {
-          hidden: step.hidden,
-          timeoutMs: step.timeout * 1e3
-        });
-      case "expectText":
-        return d.expectText(step, step.text, {
-          contains: step.contains,
-          timeoutMs: step.timeout * 1e3
-        });
-      case "hold":
-        return d.hold(step.seconds * 1e3);
-      case "card":
-        return d.card(step, { keepUp: next?.do === "card" });
-    }
-  }
-  const action = adapter.actions?.[step.do];
-  if (!action) {
-    throw new Error(`unknown step "${step.do}"`);
-  }
-  const params = Object.fromEntries(
-    Object.entries(step).filter(([key]) => key !== "do")
-  );
-  const parsed = action.params.parse(params);
-  await d.during(() => action.run(d, parsed));
-};
-var needsLinger = (previous) => previous !== void 0 && previous.do !== "hold" && previous.do !== "card";
-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;
-  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.`
-  );
-  for (const [index, step] of steps.entries()) {
-    try {
-      const linger = step.do === "card" && needsLinger(steps[index - 1]);
-      if (step.do === "hold" || step.do === "card" || CAMERA_MOVES.has(step.do)) {
-        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) {
-          throw tooQuiet();
-        }
-      }
-      if (linger) {
-        await d.hold(LINGER_MS);
-      }
-      const isLast = index === steps.length - 1;
-      const started = d.clockMs();
-      await runStep(
-        d,
-        step,
-        adapter,
-        steps[index + 1] ?? (isLast && options.keepLastCardUp ? { do: "card" } : void 0)
-      );
-      if (WAITS.has(step.do)) {
-        quietMs += d.clockMs() - started;
-        if (quietMs > idleLimitMs) {
-          throw tooQuiet();
-        }
-      }
-      if (INTERACTIONS.has(step.do) || adapter.actions?.[step.do]) {
-        quietMs = 0;
-      }
-    } catch (cause) {
-      const visible = await d.visibleTestIds().catch(() => []);
-      throw new StepError(index, step, reasonOf(cause), visible);
-    }
-  }
-};
-
 // src/runner/env.ts
 var readRunEnv = (env = process.env) => {
   const storyboardPath = env.DEMO_STORYBOARD;
@@ -1111,7 +1420,8 @@ var readRunEnv = (env = process.env) => {
     workDir: env.DEMO_WORK || `${outDir}/.work`,
     brand: env.DEMO_BRAND || void 0,
     brandsDir: env.DEMO_BRANDS || void 0,
-    draft: env.DEMO_DRAFT === "1"
+    draft: env.DEMO_DRAFT === "1",
+    stillsDir: env.DEMO_STILLS || void 0
   };
 };
 
@@ -1156,20 +1466,20 @@ var bootFailure = (adapter, frameUrl, headers, cause) => {
   return `The app didn't get ready: ${reason}. Check that the adapter's setup mocks what the app calls at start, and that "${adapter.ready}" is shown once it booted.`;
 };
 var writeJson = (file, value) => {
-  fs3.mkdirSync(path4.dirname(file), { recursive: true });
-  fs3.writeFileSync(file, JSON.stringify(value, null, 2));
+  fs4.mkdirSync(path5.dirname(file), { recursive: true });
+  fs4.writeFileSync(file, JSON.stringify(value, null, 2));
 };
 var registerDemoTests = (test, adapter, demoDir) => {
   if (process.env.DEMO_MODE === "needs") {
     test("demo", async () => {
-      writeJson(path4.join(process.env.DEMO_WORK ?? demoDir, "needs.json"), {
+      writeJson(path5.join(process.env.DEMO_WORK ?? demoDir, "needs.json"), {
         app: adapter.app,
         viewport: adapter.viewport ?? DEFAULT_VIEWPORT,
         video: VIDEO_NEEDS,
         appNeeds: describeNeeds(adapter.brandNeeds),
         example: JSON.parse(
-          fs3.readFileSync(
-            path4.join(sharedBrandsDir(), "navipartner.json"),
+          fs4.readFileSync(
+            path5.join(sharedBrandsDir(), "navipartner.json"),
             "utf8"
           )
         )
@@ -1180,10 +1490,15 @@ var registerDemoTests = (test, adapter, demoDir) => {
   test("demo", async ({ page }) => {
     const env = readRunEnv();
     if (env.mode === "check") {
-      const reportPath = path4.join(env.workDir, "check.json");
+      const reportPath = path5.join(env.workDir, "check.json");
       try {
-        const steps = await perform(page, env);
-        writeJson(reportPath, { ok: true, steps });
+        const story = await perform(page, env);
+        writeJson(reportPath, {
+          ok: true,
+          steps: story.steps.length,
+          kind: story.kind ?? "showcase",
+          seconds: estimateSeconds(story)
+        });
       } catch (error) {
         writeJson(reportPath, failureReport(error));
         throw error;
@@ -1198,7 +1513,7 @@ var registerDemoTests = (test, adapter, demoDir) => {
     if (issues.length > 0) {
       throw new StoryboardError(
         [
-          `${path4.basename(env.storyboardPath)} won't film well:`,
+          `${path5.basename(env.storyboardPath)} won't film well:`,
           ...issues.map((i) => `  ${i}`)
         ].join("\n")
       );
@@ -1235,6 +1550,31 @@ var registerDemoTests = (test, adapter, demoDir) => {
       })
     );
     const fast = env.mode === "check";
+    const stillsDir = env.stillsDir ?? path5.join(env.workDir, "stills");
+    const stillName = (index) => index === TITLE ? "card-title.png" : `card-${index}.png`;
+    const stillFile = (index) => path5.join(stillsDir, stillName(index));
+    const stillUrl = (index) => `${STILLS_PATH}/${stillName(index)}`;
+    const stills = stillCards(storyboard.steps, storyboard.title);
+    if (!fast && stills.length > 0) {
+      const missing2 = stills.filter((i) => !fs4.existsSync(stillFile(i)));
+      if (missing2.length > 0) {
+        throw new Error(
+          `No still for the card at ${missing2.map((i) => i === TITLE ? "title" : `steps.${i}`).join(", ")}: render the story with the demo-video CLI, which checks it first and captures them`
+        );
+      }
+      await page.route(
+        `**${STILLS_PATH}/*`,
+        (route) => route.fulfill({
+          contentType: "image/png",
+          body: fs4.readFileSync(
+            path5.join(
+              stillsDir,
+              path5.basename(new URL(route.request().url()).pathname)
+            )
+          )
+        })
+      );
+    }
     if (!fast) {
       await FrameRecorder.prepare(page);
     }
@@ -1262,39 +1602,44 @@ var registerDemoTests = (test, adapter, demoDir) => {
         cause: error
       });
     }
+    const title = storyboard.title;
     if (fast) {
-      await runSteps(boot, storyboard.steps, adapter);
+      await runSteps(boot, storyboard.steps, adapter, {
+        title,
+        kind: storyboard.kind,
+        ...stills.length > 0 ? { stillFile } : {}
+      });
       boot.end();
-      return storyboard.steps.length;
+      return storyboard;
     }
     await page.evaluate(() => document.fonts.ready.then(() => void 0));
     await frame.evaluate(() => document.fonts.ready.then(() => void 0));
+    await page.evaluate(
+      (urls) => window.__demo.preload(urls),
+      stills.map(stillUrl)
+    );
     await page.waitForTimeout(300);
     const recorder = new FrameRecorder(
       page,
       env.workDir,
-      `${path4.basename(env.storyboardPath, ".json")}-${brand.name}${env.draft ? "-draft" : ""}`,
+      `${path5.basename(env.storyboardPath, ".json")}-${brand.name}${env.draft ? "-draft" : ""}`,
       env.draft ? DRAFT_FPS : FPS
     );
     await recorder.freeze();
     const d = new Director(page, frame, { fast: false, viewport, recorder });
-    const title = storyboard.title;
     if (title) {
-      await d.showCard(title, true);
+      await d.showCard(
+        cardSpecFor(title, void 0, title.show ? stillUrl(TITLE) : void 0),
+        true
+      );
     }
     recorder.start();
-    if (title) {
-      await recorder.advance(cardSeconds(title) * 1e3);
-      if (storyboard.steps[0]?.do !== "card") {
-        await d.hideCard();
-        await recorder.advance(CARD_OUT_MS);
-      }
-    }
     const closing = storyboard.closing;
     await runSteps(d, storyboard.steps, adapter, {
-      // Booted, the title card and its dissolve.
-      initialQuietMs: title ? cardSeconds(title) * 1e3 + CARD_OUT_MS : 0,
-      keepLastCardUp: Boolean(closing)
+      title,
+      kind: storyboard.kind,
+      keepLastCardUp: Boolean(closing),
+      stillUrl
     });
     d.end();
     if (closing) {
@@ -1303,11 +1648,13 @@ var registerDemoTests = (test, adapter, demoDir) => {
         await recorder.advance(LINGER_MS);
       }
       await d.showCard(closing);
-      await recorder.advance(CARD_IN_MS + cardSeconds(closing) * 1e3);
+      await recorder.advance(
+        CARD_IN_MS + titleSeconds(closing, storyboard.kind) * 1e3
+      );
     }
     await recorder.advance(300);
     await recorder.stop();
-    return storyboard.steps.length;
+    return storyboard;
   };
 };
 export {