@navipartner/demo-video 0.7.0 → 0.7.1

package/README.md

@@ -1,7 +1,9 @@
 # @navipartner/demo-video
 
-Marketing demo videos of React apps, in the NaviPartner look: calm camera
-pushes and serif statement cards. The engine films an app on its own
+Marketing demo videos of React apps, in the NaviPartner look: brisk camera
+pushes and big serif cards that can show a snapshot of the result beside
+the words. A story is a showcase of an app's main journey (45–90 s) or a
+clip of one feature (15–30 s). The engine films an app on its own
 Playwright e2e mocks, frame by frame at 60 fps, so pans stay smooth. It
 works in pnpm repos on GitHub Actions, with `@playwright/test` 1.59 or later.
 
@@ -18,7 +20,8 @@ From the repo root:
 
 `init` adds the skill, the `demo video` label and the workflow, and finds
 the apps: folders with a `playwright.config`. A repo with one app is set up
-in one go; with several, run `init --app <folder>` for each one you want.
+in one go; with several, it prints the `init --app <folder>` line to run
+for each.
 It's safe to re-run, and `--dry-run` previews. Then ask Claude for a demo
 video of the app: it writes the adapter and the primary story with you.
 
@@ -72,7 +75,7 @@ Run them in the app's folder: `pnpm exec demo-video <command>`.
 | `init` | sets up a repo or an app |
 | `list` | the stories, primary first |
 | `check` | a dry run in seconds that names what would film badly |
-| `render` | the MP4, a contact sheet and ten stills, in `demo/out/` |
+| `render` | the MP4, a contact sheet and ten stills, in `demo/out/` (it checks first when cards show snapshots) |
 | `record`, `encode`, `stills` | `render` in parts |
 | `brand-needs` | what a brand must give this app |
 | `pitch <proposal.json>` | a pitch draft from a researched brand |

package/bin/demo-video.mjs

@@ -8,7 +8,7 @@ import path from "node:path";
 
 import { listStories, parseArgs } from "./args.mjs";
 import { encodeRecording, extractStillsFrom } from "./encode.mjs";
-import { initApp, initProject } from "./init.mjs";
+import { findApps, initApp, initProject } from "./init.mjs";
 import { appMenu, menuMarkdown, pick } from "./pick.mjs";
 import { buildPitchBrand } from "./pitch.mjs";
 import { writeRunner } from "./runner.mjs";
@@ -56,15 +56,85 @@ const runPlaywright = (args, mode) => {
         DEMO_OUT: args.outDir,
         DEMO_WORK: args.workDir,
         DEMO_DRAFT: args.draft ? "1" : "",
+        DEMO_STILLS: args.stillsDir ?? "",
       },
     },
   );
   return result.status ?? 1;
 };
 
+const readReport = (args) => {
+  const reportPath = path.join(args.workDir, "check.json");
+  return fs.existsSync(reportPath)
+    ? JSON.parse(fs.readFileSync(reportPath, "utf8"))
+    : {
+        ok: false,
+        error:
+          "the dry run produced no report (Playwright did not run the demo test — see its output above)",
+      };
+};
+
+// A card that shows a still of its chapter's result (`show`) needs the
+// still before filming: a check captures it, as the element last looks in
+// that chapter. Returns the check's run, whose folder holds the stills
+// until the take is filmed, or null when no card shows one.
+const captureStills = (args) => {
+  const story = JSON.parse(fs.readFileSync(args.storyboardPath, "utf8"));
+  const shows =
+    story.title?.show !== undefined ||
+    (story.steps ?? []).some((s) => s?.do === "card" && s.show !== undefined);
+  if (!shows) {
+    return null;
+  }
+  const workDir = path.join(path.dirname(args.workDir), "check");
+  const runnerDir = path.join(workDir, "runner");
+  const check = {
+    ...args,
+    command: "check",
+    workDir,
+    runnerDir,
+    configPath: path.join(runnerDir, "playwright.config.mjs"),
+    stillsDir: path.join(workDir, "stills"),
+  };
+  const status = runPlaywright(check, "check");
+  const report = readReport(check);
+  if (!report.ok || status !== 0) {
+    finish(check, false);
+    throw new Error(
+      `The story doesn't pass check, so its card stills can't be captured: ${report.error}`,
+    );
+  }
+  return check;
+};
+
+// Films the take, with the card stills when the story has any.
+const film = (args) => {
+  const check = captureStills(args);
+  const status = runPlaywright(
+    { ...args, stillsDir: check?.stillsDir },
+    "record",
+  );
+  if (check) {
+    finish(check, true);
+  }
+  return status;
+};
+
+// How long each kind runs (look.md, src/timing.ts KIND_SECONDS).
+const KIND_SECONDS = { showcase: [45, 90], feature: [15, 30] };
+
 const printReport = (report) => {
   if (report.ok) {
     console.log(`✓ story passes (${report.steps} steps)`);
+    const range = KIND_SECONDS[report.kind];
+    if (report.seconds !== undefined && range) {
+      const [low, high] = range;
+      const fits =
+        report.seconds < low ? "short" : report.seconds > high ? "long" : null;
+      console.log(
+        `  about ${report.seconds} s; a ${report.kind === "feature" ? "feature clip" : "showcase"} runs ${low}–${high} s${fits ? `, so this is ${fits}` : ""}`,
+      );
+    }
     return;
   }
   const where = report.step
@@ -100,6 +170,14 @@ const runInit = (argv) => {
     return 2;
   }
   const root = process.cwd();
+  if (app && !fs.existsSync(path.join(root, app, "package.json"))) {
+    // Name the folders that are apps, so the fix is a copy away.
+    const apps = findApps(root);
+    console.error(
+      `${app} isn't an app: it has no package.json.${apps.length ? `\nApps here: ${apps.join(", ")}` : ""}`,
+    );
+    return 2;
+  }
   const result = app
     ? initApp(path.resolve(root, app), { dryRun })
     : initProject(root, { dryRun });
@@ -207,21 +285,25 @@ const runPitch = async (argv) => {
       brandsDir,
       "--json",
     ];
+    // The check also captures the card stills, in the customer's brand.
     const check = parseArgs(["check", ...common], process.cwd());
+    check.stillsDir = path.join(check.workDir, "stills");
     const checked = runPlaywright(check, "check");
-    const reportPath = path.join(check.workDir, "check.json");
-    const report = fs.existsSync(reportPath)
-      ? JSON.parse(fs.readFileSync(reportPath, "utf8"))
-      : { ok: false, error: "the dry run produced no report" };
-    finish(check, report.ok && checked === 0);
+    const report = readReport(check);
     if (!report.ok || checked !== 0) {
+      finish(check, false);
       throw new Error(
         `The researched brand doesn't film with this story: ${report.error}`,
       );
     }
     // A pitch is a draft for one customer: 30 fps, about half the time.
     const render = parseArgs(["render", ...common, "--draft"], process.cwd());
-    if (runPlaywright(render, "record") !== 0) {
+    const filmed = runPlaywright(
+      { ...render, stillsDir: check.stillsDir },
+      "record",
+    );
+    finish(check, true);
+    if (filmed !== 0) {
       finish(render, false);
       throw new Error("Filming the pitch draft failed (see above)");
     }
@@ -279,14 +361,7 @@ const run = () => {
     case "check": {
       const status = runPlaywright(args, "check");
       // The report comes back through the work folder and goes with it.
-      const reportPath = path.join(args.workDir, "check.json");
-      const report = fs.existsSync(reportPath)
-        ? JSON.parse(fs.readFileSync(reportPath, "utf8"))
-        : {
-            ok: false,
-            error:
-              "the dry run produced no report (Playwright did not run the demo test — see its output above)",
-          };
+      const report = readReport(args);
       const ok = report.ok && status === 0;
       finish(args, ok);
       if (args.json) {
@@ -298,14 +373,14 @@ const run = () => {
     }
     case "record": {
       // The recording stays in the work folder for `encode`.
-      const status = runPlaywright(args, "record");
+      const status = film(args);
       if (status !== 0) {
         finish(args, false);
       }
       return status;
     }
     case "render": {
-      const status = runPlaywright(args, "record");
+      const status = film(args);
       if (status !== 0) {
         finish(args, false);
         return status;

package/bin/init.d.mts

@@ -5,6 +5,8 @@ export interface InitResult {
 }
 export const IGNORE_LINE: string;
 export const LABEL: string;
+/** How init is run before the package is installed. */
+export const INIT: string;
 export const CALLER_WORKFLOW: string;
 export function initRepo(
   root: string,

package/bin/init.mjs

@@ -9,6 +9,8 @@ import { fileURLToPath } from "node:url";
 // workflow. Safe to re-run; with dryRun it reports what it would change.
 
 const PKG = "@navipartner/demo-video";
+/** How init is run before the package is installed (the README's way). */
+export const INIT = `npx --ignore-scripts ${PKG} init`;
 export const IGNORE_LINE = "**/demo/out/";
 export const LABEL = "demo video";
 
@@ -366,7 +368,7 @@ export const initApp = (appDir, { dryRun = false } = {}) => {
   const todo = [];
   const pkgFile = path.join(appDir, "package.json");
   if (!fs.existsSync(pkgFile)) {
-    throw new Error(`No package.json in ${appDir}`);
+    throw new Error(`${appDir} has no package.json, so it isn't an app.`);
   }
   const pkg = JSON.parse(fs.readFileSync(pkgFile, "utf8"));
   const version = engineVersion();
@@ -396,14 +398,19 @@ export const initApp = (appDir, { dryRun = false } = {}) => {
     );
   }
 
+  const configFile = ["ts", "mts", "js", "mjs", "cts", "cjs"]
+    .map((ext) => path.join(appDir, `playwright.config.${ext}`))
+    .find((f) => fs.existsSync(f));
+  if (!configFile) {
+    todo.push(
+      "Add a playwright.config to this folder: videos run on the app's e2e setup.",
+    );
+  }
   const demoDir = path.join(appDir, "demo");
   const adapter = path.join(demoDir, "demo.config.ts");
   if (fs.existsSync(adapter)) {
     changes.push(["ok", "demo/demo.config.ts", "exists"]);
   } else {
-    const configFile = ["ts", "mts", "js", "mjs"]
-      .map((ext) => path.join(appDir, `playwright.config.${ext}`))
-      .find((f) => fs.existsSync(f));
     const webServer = configFile ? webServerOf(read(configFile)) : {};
     const skeleton = adapterSkeleton({
       app: (pkg.name ?? path.basename(appDir)).replace(/^@[^/]+\//, ""),
@@ -492,12 +499,16 @@ export const initProject = (root, options = {}) => {
   }
   const todo = [...repo.todo];
   if (apps.length > 1) {
+    // Exactly what to run: one line per app, copied as is.
     todo.push(
-      `This repo has ${apps.length} apps with Playwright e2e tests: ${apps.join(", ")}. Set up each one you want videos of with init --app <folder>.`,
+      [
+        `${apps.length} apps found and none set up yet. Run this for each app you want videos of:`,
+        ...apps.map((app) => `    ${INIT} --app ${app}`),
+      ].join("\n"),
     );
   } else {
     todo.push(
-      "No app with a playwright.config found: the demo films an app on its Playwright e2e tests. Add them, then run init again (or init --app <folder>).",
+      `No app found (a folder with package.json and playwright.config). Run ${INIT} --app <folder> once it has both.`,
     );
   }
   return { apps, changes: repo.changes, todo };

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

@@ -38,6 +38,13 @@ interface VideoBrand {
     fontsUrl: string;
 }
 
+/**
+ * What a story is (look.md): a showcase walks the app's main journey for a
+ * buyer (45–90 s); a feature clip shows one feature (15–30 s). The beats are
+ * the same; the shape differs.
+ */
+type Kind = "showcase" | "feature";
+
 /** A testid (letters, digits, dash, underscore) or a Playwright selector. */
 interface Target {
     target: string;
@@ -53,6 +60,21 @@ interface CardSpec {
     logo?: boolean;
     style: "pale" | "brand";
     seconds: number;
+    /** A still of what the chapter achieves, beside the words (a URL). */
+    still?: string;
+}
+interface CardOptions {
+    /** The next card replaces this one directly, with no app in between. */
+    keepUp?: boolean;
+    /** The video's open card: already up on the first frame, no dissolve in. */
+    opening?: boolean;
+    /** 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.
+     */
+    behind?: () => Promise<void>;
 }
 interface DirectorApi {
     /** The app's iframe, for actions that talk to the app directly. */
@@ -75,7 +97,10 @@ interface DirectorApi {
     click(target: Target, options?: {
         zoom?: number;
     }): Promise<void>;
-    type(target: Target, text: string, perCharMs?: number): Promise<void>;
+    /** `replace`: select what the field holds first, so the text replaces it. */
+    type(target: Target, text: string, perCharMs?: number, options?: {
+        replace?: boolean;
+    }): Promise<void>;
     press(key: string): Promise<void>;
     park(): Promise<void>;
     waitFor(target: Target, options: {
@@ -98,12 +123,16 @@ interface DirectorApi {
      */
     clockMs(): number;
     /**
-     * Dissolves the card in over the app and holds it. It dissolves back out
-     * unless `keepUp`: then the next card replaces it directly.
+     * Dissolves the card in over the app and holds it, doing `behind` while
+     * it covers the app. It dissolves back out unless `keepUp`: then the next
+     * card replaces it directly.
      */
-    card(spec: CardSpec, options?: {
-        keepUp?: boolean;
-    }): Promise<void>;
+    card(spec: CardSpec, options?: CardOptions): Promise<void>;
+    /**
+     * Saves a still of the element as it looks now, for a card that shows it.
+     * False when it isn't on screen.
+     */
+    capture(target: Target, file: string): Promise<boolean>;
     /** Testids currently visible in the app, for failure reports. */
     visibleTestIds(): Promise<string[]>;
 }
@@ -166,4 +195,4 @@ interface DemoAdapter {
 declare const defineDemo: (adapter: DemoAdapter) => DemoAdapter;
 declare const defineAction: <S extends z.ZodRawShape>(action: DemoAction<S>) => DemoAction<S>;
 
-export { type Brand as B, type CardSpec as C, type DemoAdapter as D, type Target as T, type VideoBrand as V, type DemoAction as a, type DirectorApi as b, defineDemo as c, defineAction as d };
+export { type Brand as B, type CardSpec as C, type DemoAdapter as D, type Kind as K, type Target as T, type VideoBrand as V, type DemoAction as a, type DirectorApi as b, defineDemo as c, defineAction as d };