@navipartner/demo-video 0.7.0 → 0.7.2

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.
 
@@ -30,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
@@ -41,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
@@ -72,7 +76,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 |
@@ -89,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

@@ -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,91 @@ 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}` : ""}`,
+      );
+    }
+    // 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
@@ -100,6 +176,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 +291,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 +367,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 +379,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-DxZmb-QU.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): 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: {
@@ -91,19 +116,26 @@ 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.
      */
     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[]>;
 }
@@ -111,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 | {
@@ -166,4 +205,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 };