From 17215038596a2ef3d4bbd6f968a4863fc3fb6422 Mon Sep 17 00:00:00 2001
From: umiyosh <yumino99@gmail.com>
Date: Fri, 6 Nov 2026 01:07:35 +0900
Subject: [PATCH 1/6] feat(cli): run API calls in parallel, log step times and
 assemble scene files

---
 skills/motion-render/scripts/audio.ts   |  57 +++++++++--
 skills/motion-render/scripts/cli.ts     |  55 ++++++----
 skills/motion-render/scripts/inorder.ts |  23 +++++
 skills/motion-render/scripts/layout.ts  |  14 ++-
 skills/motion-render/scripts/render.ts  |  28 +++--
 skills/motion-render/scripts/scenes.ts  |  68 ++++++++++++
 skills/motion-render/scripts/sfx.ts     |  19 +++-
 skills/motion-render/scripts/steps.ts   | 131 ++++++++++++++++++++++++
 tests/audio.test.ts                     |  57 ++++++++++-
 tests/inorder.test.ts                   |  30 +++++-
 tests/scenes.test.ts                    | 118 +++++++++++++++++++++
 tests/sfx.test.ts                       |  25 +++++
 tests/steps.test.ts                     | 103 +++++++++++++++++++
 13 files changed, 681 insertions(+), 47 deletions(-)
 create mode 100644 skills/motion-render/scripts/scenes.ts
 create mode 100644 skills/motion-render/scripts/steps.ts
 create mode 100644 tests/scenes.test.ts
 create mode 100644 tests/steps.test.ts

diff --git a/skills/motion-render/scripts/audio.ts b/skills/motion-render/scripts/audio.ts
index 038d91e..cd532b9 100644
--- a/skills/motion-render/scripts/audio.ts
+++ b/skills/motion-render/scripts/audio.ts
@@ -5,6 +5,7 @@ import { spawn, spawnSync, type ChildProcess } from "node:child_process";
 import { createRequire } from "node:module";
 import { errorMessage, field, readJson } from "./json.ts";
 import { limit } from "./limit.ts";
+import { inParallel } from "./inorder.ts";
 import type { Script } from "./work.ts";
 
 const API = "https://generativelanguage.googleapis.com/v1beta/models";
@@ -120,15 +121,49 @@ export async function volumeStats(
   return { mean, max };
 }
 
+// A provider's "too many requests" (HTTP 429). Calls run several at once, so a rate limit is a normal
+// answer: the call waits `wait` ms and tries again without using up one of its attempts.
+export class Busy extends Error {
+  wait: number;
+  constructor(message: string, wait: number) {
+    super(message);
+    this.wait = wait;
+  }
+}
+// Most a call waits on rate limits, in time and in tries, before a 429 counts as a failed attempt.
+const BUSY_TOTAL_MS = 180_000;
+const BUSY_TRIES = 10;
+
+// The wait an HTTP 429 asks for: Gemini's RetryInfo ("retryDelay": "23s") or a Retry-After header
+// in seconds, else `fallback` ms. Never more than a minute at a time.
+export function busyWait(body: unknown, retryAfter: string | null, fallback: number): number {
+  const details = field(field(body, "error"), "details");
+  const delay = Array.isArray(details)
+    ? details.map((d: unknown) => field(d, "retryDelay")).find((d) => typeof d === "string")
+    : undefined;
+  const s = typeof delay === "string" ? parseFloat(delay) : Number(retryAfter ?? NaN);
+  return Math.min(60_000, Number.isFinite(s) && s >= 0 ? s * 1000 : fallback);
+}
+
 // Runs `attempt` up to RETRIES times, logging each failure under `label`, and rethrows the last error.
 export async function withRetries<T>(label: string, attempt: () => Promise<T>): Promise<T> {
   let last: unknown;
-  for (let i = 1; i <= RETRIES; i++) {
+  let waited = 0,
+    waits = 0;
+  for (let i = 1; i <= RETRIES;) {
     try {
       return await attempt();
     } catch (e) {
       last = e;
+      if (e instanceof Busy && waits < BUSY_TRIES && waited + e.wait <= BUSY_TOTAL_MS) {
+        console.error(`motion-render: ${label} is rate-limited, trying again in ${e.wait / 1000}s`);
+        waited += e.wait;
+        waits++;
+        await new Promise((ok) => setTimeout(ok, e.wait));
+        continue;
+      }
       console.error(`motion-render: ${label} attempt ${i}/${RETRIES} failed: ${errorMessage(e)}`);
+      i++;
     }
   }
   throw last;
@@ -163,9 +198,10 @@ async function generateAudio(model: string, body: object): Promise<Audio> {
     const json: unknown = await res.json();
     if (!res.ok) {
       const detail = field(field(json, "error"), "message");
-      throw new Error(
-        `${model}: HTTP ${res.status} ${typeof detail === "string" ? detail : ""}`.trim()
-      );
+      const msg = `${model}: HTTP ${res.status} ${typeof detail === "string" ? detail : ""}`.trim();
+      if (res.status === 429)
+        throw new Busy(msg, busyWait(json, res.headers.get("retry-after"), 5_000));
+      throw new Error(msg);
     }
     const part = audioPart(json);
     if (!part) throw new Error(`${model}: no audio in the response`);
@@ -214,14 +250,21 @@ export function wavSeconds(file: string): number {
   return size / (rate * align);
 }
 
+// Scenes narrated at once. One by one, 14 scenes took 74 s; a rate limit makes a call wait (Busy).
+const TTS_AT_ONCE = 4;
+
 // Writes audio/<scene id>.wav for each scene. A scene is regenerated only when its narration text changed.
 export async function narrate(work: string, script: Script): Promise<void> {
   const dir = join(work, "audio");
   mkdirSync(dir, { recursive: true });
-  for (const s of script.scenes) {
+  const todo = script.scenes.filter((s) => {
+    const wav = join(dir, `${s.id}.wav`),
+      txt = join(dir, `${s.id}.txt`);
+    return !(existsSync(wav) && existsSync(txt) && readFileSync(txt, "utf8") === s.narration);
+  });
+  await inParallel(todo, TTS_AT_ONCE, async (s) => {
     const wav = join(dir, `${s.id}.wav`),
       txt = join(dir, `${s.id}.txt`);
-    if (existsSync(wav) && existsSync(txt) && readFileSync(txt, "utf8") === s.narration) continue;
     console.error(`narration: ${s.id}`);
     const audio = await generateAudio(script.ttsModel, {
       contents: [{ parts: [{ text: s.narration }] }],
@@ -232,7 +275,7 @@ export async function narrate(work: string, script: Script): Promise<void> {
     });
     writeFileSync(wav, toWav(audio));
     writeFileSync(txt, s.narration);
-  }
+  });
 }
 
 // Writes audio/bgm.<ext> from the script's BGM prompt, asking for a little more than the film's length.
diff --git a/skills/motion-render/scripts/cli.ts b/skills/motion-render/scripts/cli.ts
index 4b63193..cec54bf 100755
--- a/skills/motion-render/scripts/cli.ts
+++ b/skills/motion-render/scripts/cli.ts
@@ -16,6 +16,7 @@ import { loadScript, writeTiming, loadTiming, placeOnFilm, placeSfx } from "./wo
 import { checkSfx, makeSfx, narrationLevel, previewSfx, sfxTrack } from "./sfx.ts";
 import { prepare } from "./store.ts";
 import { errorMessage, field, readJson } from "./json.ts";
+import { stepsTable, timed, workOf } from "./steps.ts";
 
 const USAGE = `usage (one work dir per video; see SKILL.md for its layout):
   motion-render narrate <work>            Narrate every scene of <work>/script.json (Gemini TTS)
@@ -27,14 +28,18 @@ const USAGE = `usage (one work dir per video; see SKILL.md for its layout):
                                           Expand a Motion film's store (ArtifactData out_dir) into a film dir.
   motion-render kit <work>                Set up <work>/film for an html film: player, fonts, GSAP and
                                           the scene times from timing.json (write film/index.html after).
-  motion-render check <filmDir>           Check an html film's layout every 0.1s: overlaps, things
+  motion-render check <filmDir> [<scene file>...]
+                                          Check an html film's layout every 0.1s: overlaps, things
                                           sticking out of their box or the frame, things hidden under others,
-                                          and text too small or too faint to read.
+                                          and text too small or too faint to read. With scene files
+                                          (names in <filmDir>/scenes), only those are put in and checked.
   motion-render stills <filmDir> <outDir> <t1,t2,...>
                                           Write PNG stills at the given seconds (and run check).
   motion-render build <work> [out.mp4]    Mix narration + BGM + sound effects and render <work>/film to MP4.
                                           Stops if check finds a layout issue in an html film.
                                           Without out.mp4: $MOTION_RENDER_OUT_DIR or the current dir, <work name>.mp4.
+  motion-render times <work>              Show how long each step of this video took, as a table
+                                          (commands from <work>/steps.jsonl, and Claude's work between them).
 
 env:
   GEMINI_API_KEY         required by narrate and bgm
@@ -69,7 +74,7 @@ async function reportLayout(film: Film): Promise<number> {
 
 async function stills(filmDir: string, outDir: string, list: string): Promise<void> {
   const times = list.split(",").map(Number);
-  if (times.some((t) => !Number.isFinite(t))) die(`times must be numbers: ${list}`);
+  if (times.some((t) => !Number.isFinite(t))) throw new Error(`times must be numbers: ${list}`);
   mkdirSync(outDir, { recursive: true });
   const film = await openFilm(filmDir, { pages: capturePages() });
   try {
@@ -83,18 +88,19 @@ async function stills(filmDir: string, outDir: string, list: string): Promise<vo
   console.log(`done: ${times.length} stills in ${outDir}`);
 }
 
-async function check(filmDir: string): Promise<void> {
+async function check(filmDir: string, scenes: string[]): Promise<void> {
   if (!isHtmlFilm(filmDir))
-    die("check works on html films only (Motion films draw in their own player)");
-  const film = await openFilm(filmDir, { pages: capturePages() });
+    throw new Error("check works on html films only (Motion films draw in their own player)");
+  const film = await openFilm(filmDir, { pages: capturePages(), scenes });
   let n: number;
   try {
     n = await reportLayout(film);
   } finally {
     await film.close();
   }
-  if (n) die(`${n} layout issues in ${filmDir}`);
-  console.log(`layout ok: ${filmDir}`);
+  const what = scenes.length ? `${filmDir} (${scenes.join(", ")})` : filmDir;
+  if (n) throw new Error(`${n} layout issues in ${what}`);
+  console.log(`layout ok: ${what}`);
 }
 
 function runKit(work: string): void {
@@ -156,14 +162,16 @@ async function encode(film: Film, fps: number, audio: string, out: string): Prom
 }
 
 async function build(work: string, out: string, fps: number): Promise<void> {
-  if (!Number.isFinite(fps) || fps <= 0) die("--fps must be a positive number");
+  if (!Number.isFinite(fps) || fps <= 0) throw new Error("--fps must be a positive number");
   const script = loadScript(work);
   const timing = loadTiming(work);
   const missing = timing.scenes
     .filter((s) => !existsSync(join(work, "audio", `${s.id}.wav`)))
     .map((s) => s.id);
   if (missing.length)
-    die(`narration missing for: ${missing.join(", ")} (run "motion-render narrate ${work}")`);
+    throw new Error(
+      `narration missing for: ${missing.join(", ")} (run "motion-render narrate ${work}")`
+    );
   bgmFile(work);
   checkSfx(work, script);
   const filmDir = join(work, "film");
@@ -194,7 +202,7 @@ async function build(work: string, out: string, fps: number): Promise<void> {
 }
 
 interface Command {
-  args: number[]; // accepted argument counts
+  args: [number, number]; // fewest and most arguments
   run(args: string[], fps: number): Promise<void> | void;
 }
 
@@ -207,15 +215,19 @@ function runBuild([a, b]: string[], fps: number): Promise<void> {
 }
 
 const COMMANDS = new Map<string, Command>([
-  ["narrate", { args: [1], run: ([w]) => runNarrate(resolve(w!)) }],
-  ["bgm", { args: [1], run: ([w]) => runBgm(resolve(w!)) }],
-  ["sfx", { args: [1], run: ([w]) => runSfx(resolve(w!)) }],
-  ["kit", { args: [1], run: ([w]) => runKit(resolve(w!)) }],
-  ["prepare", { args: [2], run: ([s, f]) => runPrepare(s!, f!) }],
-  ["stills", { args: [3], run: ([f, o, t]) => stills(f!, o!, t!) }],
-  ["check", { args: [1], run: ([f]) => check(f!) }],
+  ["narrate", { args: [1, 1], run: ([w]) => runNarrate(resolve(w!)) }],
+  ["bgm", { args: [1, 1], run: ([w]) => runBgm(resolve(w!)) }],
+  ["sfx", { args: [1, 1], run: ([w]) => runSfx(resolve(w!)) }],
+  ["kit", { args: [1, 1], run: ([w]) => runKit(resolve(w!)) }],
+  ["prepare", { args: [2, 2], run: ([s, f]) => runPrepare(s!, f!) }],
+  ["stills", { args: [3, 3], run: ([f, o, t]) => stills(f!, o!, t!) }],
+  ["check", { args: [1, Infinity], run: ([f, ...s]) => check(f!, s) }],
   ["build", { args: [1, 2], run: runBuild }],
+  ["times", { args: [1, 1], run: ([w]) => console.log(stepsTable(resolve(w!))) }],
 ]);
+// Commands whose time is logged in the work dir of their first argument (steps.ts). prepare writes
+// to its second.
+const LOGGED = new Set(["narrate", "bgm", "sfx", "kit", "prepare", "stills", "check", "build"]);
 
 function version(): string {
   const v = field(readJson(fileURLToPath(new URL("../package.json", import.meta.url))), "version");
@@ -235,9 +247,12 @@ async function main(): Promise<void> {
   if (values.version) return console.log(version());
   if (values.help || !cmd) return console.log(USAGE);
   const command = COMMANDS.get(cmd);
-  if (!command || !command.args.includes(rest.length) || rest.some((a) => !a))
+  const [fewest, most] = command?.args ?? [0, 0];
+  if (!command || rest.length < fewest || rest.length > most || rest.some((a) => !a))
     die(`unknown command or wrong arguments\n\n${USAGE}`, 2);
-  return command.run(rest, Number(values.fps));
+  const target = cmd === "prepare" ? rest[1] : rest[0];
+  const work = LOGGED.has(cmd) && target ? workOf(target) : null;
+  return timed(work, cmd, () => command.run(rest, Number(values.fps)));
 }
 
 main().catch((e: unknown) => die(errorMessage(e)));
diff --git a/skills/motion-render/scripts/inorder.ts b/skills/motion-render/scripts/inorder.ts
index 240b8ff..36e9596 100644
--- a/skills/motion-render/scripts/inorder.ts
+++ b/skills/motion-render/scripts/inorder.ts
@@ -21,3 +21,26 @@ export async function* inOrder<T>(
     yield await p;
   }
 }
+
+// Runs fn on each item with up to `n` running at once, for API calls whose results are saved one by
+// one. After a failure no new item starts; the ones running finish, and the first error is thrown.
+export async function inParallel<T>(
+  items: readonly T[],
+  n: number,
+  fn: (item: T) => Promise<void>
+): Promise<void> {
+  let next = 0;
+  const errors: unknown[] = [];
+  const worker = async (): Promise<void> => {
+    while (!errors.length && next < items.length) {
+      const i = next++;
+      try {
+        await fn(items[i]);
+      } catch (e) {
+        errors.push(e);
+      }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.max(1, Math.min(n, items.length)) }, worker));
+  if (errors.length) throw errors[0];
+}
diff --git a/skills/motion-render/scripts/layout.ts b/skills/motion-render/scripts/layout.ts
index 713f475..bed761a 100644
--- a/skills/motion-render/scripts/layout.ts
+++ b/skills/motion-render/scripts/layout.ts
@@ -231,16 +231,22 @@ export function parseBoxes(raw: unknown): LayoutBox[] {
 
 // Samples the whole film every `step` seconds, on all of the film's pages at once, and judges the
 // samples in film order. A finding needs two samples in a row, so at 0.1 s a pose held for 0.2 s is
-// reported. Motion films draw inside their own player and cannot be inspected, so they get null.
+// reported. A film opened with only some scene files is sampled over those scenes only. Motion films
+// draw inside their own player and cannot be inspected, so they get null.
 export async function checkLayout(film: Film, step = 0.1): Promise<LayoutIssue[] | null> {
   const inspect = film.inspect;
   if (!inspect) return null;
-  const count = Math.ceil(film.meta.duration / step - 1e-9);
+  const only = film.only;
+  const spans = only ? film.meta.parts.filter((p) => only.includes(p.key)) : null;
+  const times = Array.from(
+    { length: Math.ceil(film.meta.duration / step - 1e-9) },
+    (_, i) => Math.round(i * step * 1000) / 1000
+  ).filter((t) => !spans || spans.some((p) => t >= p.a0 && t < p.a0 + p.dur));
   const sample = (i: number): Promise<LayoutSample> => {
-    const t = Math.round(i * step * 1000) / 1000;
+    const t = times[i] ?? 0;
     return inspect(t).then((boxes) => ({ t, boxes }));
   };
   const samples: LayoutSample[] = [];
-  for await (const s of inOrder(count, film.pages, sample)) samples.push(s);
+  for await (const s of inOrder(times.length, film.pages, sample)) samples.push(s);
   return findLayoutIssues(samples);
 }
diff --git a/skills/motion-render/scripts/render.ts b/skills/motion-render/scripts/render.ts
index 566fa78..b20a62b 100644
--- a/skills/motion-render/scripts/render.ts
+++ b/skills/motion-render/scripts/render.ts
@@ -10,6 +10,7 @@ import { chromium, type Browser, type LaunchOptions, type Page } from "playwrigh
 import { errorMessage, field, isRecord, readJson } from "./json.ts";
 import { parseBoxes, type LayoutBox } from "./layout.ts";
 import { limit } from "./limit.ts";
+import { filmPage } from "./scenes.ts";
 
 const require = createRequire(import.meta.url);
 const PLAYWRIGHT_CLI = join(dirname(require.resolve("playwright-core")), "cli.js");
@@ -96,14 +97,17 @@ export interface Film {
   close(): Promise<void>;
   // How many frame or inspect calls run at once: one per page.
   pages: number;
+  // The scenes on the page when only some scene files were opened (FilmOptions.scenes), else null.
+  only: string[] | null;
 }
 
 // The film as one page shows it.
-type PageFilm = Omit<Film, "close" | "pages">;
+type PageFilm = Omit<Film, "close" | "pages" | "only">;
 
 export interface FilmOptions {
   pageMs?: number; // time limit of each call into a page
   pages?: number; // pages that draw at the same time
+  scenes?: string[]; // html films: open only these files of film/scenes (scenes.ts)
 }
 
 // Pages that draw a film at the same time. Each page has its own browser and keeps about one core
@@ -286,13 +290,13 @@ async function waitReady(page: Page, call: Call): Promise<void> {
   }
 }
 
-async function htmlFilm(page: Page, dir: string, call: Call): Promise<PageFilm> {
+async function htmlFilm(page: Page, file: string, call: Call): Promise<PageFilm> {
   const log: string[] = [];
   page.on("console", (m) => {
     if (m.type() === "warning" || m.type() === "error") log.push(`${m.type()}: ${m.text()}`);
   });
   page.on("pageerror", (e) => log.push(`error: ${e.message}`));
-  await page.goto(pathToFileURL(resolve(dir, "index.html")).href);
+  await page.goto(pathToFileURL(resolve(file)).href);
   await page.waitForFunction(() => typeof window.__film === "object");
   let meta: unknown;
   try {
@@ -356,27 +360,33 @@ function onFreePage(films: PageFilm[]) {
 // captured no faster than 1), while separate browsers draw side by side. Each call into a page
 // fails after pageMs.
 export async function openFilm(dir: string, opts: FilmOptions = {}): Promise<Film> {
-  const { pageMs = PAGE_MS, pages = 1 } = opts;
+  const { pageMs = PAGE_MS, pages = 1, scenes = [] } = opts;
   if (!Number.isInteger(pages) || pages < 1)
     throw new Error(`pages must be 1 or more, got ${pages}`);
   checkFilmDir(dir);
-  // The first launch may download Chromium, so the others wait for it.
-  const browsers = [await launch()];
-  const closeAll = () => Promise.all(browsers.map((b) => b.close())).then(() => undefined);
+  const html = isHtmlFilm(dir);
+  if (scenes.length && !html) throw new Error("only an html film has scene files");
+  const entry = html ? filmPage(dir, scenes) : null;
+  const browsers: Browser[] = [];
+  const closeAll = () => Promise.all(browsers.map((b) => b.close())).then(() => entry?.close());
   const call: Call = (p, what) => limit(p, pageMs, `the film page's ${what}`);
-  const open = isHtmlFilm(dir) ? htmlFilm : motionFilm;
+  const open = (page: Page) =>
+    entry ? htmlFilm(page, entry.file, call) : motionFilm(page, dir, call);
   try {
+    // The first launch may download Chromium, so the others wait for it.
+    browsers.push(await launch());
     const more = await Promise.allSettled(Array.from({ length: pages - 1 }, () => launch()));
     for (const r of more) if (r.status === "fulfilled") browsers.push(r.value);
     const failed = more.find((r) => r.status === "rejected");
     if (failed?.status === "rejected") throw failed.reason;
-    const films = await Promise.all(browsers.map(async (b) => open(await openPage(b), dir, call)));
+    const films = await Promise.all(browsers.map(async (b) => open(await openPage(b))));
     const [first] = films;
     if (!first) throw new Error("no film page opened");
     const run = onFreePage(films);
     return {
       meta: first.meta,
       pages,
+      only: entry?.ids ?? null,
       frame: (t) => run((f) => f.frame(t)),
       inspect:
         first.inspect && ((t) => run((f) => (f.inspect ? f.inspect(t) : Promise.resolve([])))),
diff --git a/skills/motion-render/scripts/scenes.ts b/skills/motion-render/scripts/scenes.ts
new file mode 100644
index 0000000..a0cb6cc
--- /dev/null
+++ b/skills/motion-render/scripts/scenes.ts
@@ -0,0 +1,68 @@
+// html の映像を場面のまとまりごとに分けて書くためのファイル（film/scenes/*.html）を、
+// index.html の <!-- scenes --> の行に差し込んで、プレーヤーが開く 1 枚のページにする。
+// 何人かの書き手（サブエージェント）が同時に別々の場面を書けるようにするため。
+import { existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const MARKER = "<!-- scenes -->";
+const DIR = "scenes";
+
+// The scene files of a film dir, in name order (01-title.html, 02-flow.html, ...).
+export function sceneFiles(dir: string): string[] {
+  const d = join(dir, DIR);
+  return existsSync(d)
+    ? readdirSync(d)
+        .filter((n) => n.endsWith(".html"))
+        .sort()
+    : [];
+}
+
+// The scene ids a scene file defines (<section class="scene" id="...">), in order.
+export function sceneIds(html: string): string[] {
+  const ids: string[] = [];
+  for (const m of html.matchAll(/<section\b[^>]*>/g)) {
+    const tag = m[0];
+    if (!/\bclass="[^"]*\bscene\b[^"]*"/.test(tag)) continue;
+    const id = /\bid="([^"]+)"/.exec(tag)?.[1];
+    if (id) ids.push(id);
+  }
+  return ids;
+}
+
+export interface FilmPage {
+  file: string; // the page to open, in the film dir so its relative paths still work
+  ids: string[] | null; // scene ids of the files put in when only some were asked for
+  close(): void;
+}
+
+let made = 0;
+
+// The page a runner opens. Without scene files it is index.html itself. With them, it is a copy of
+// index.html with every scene file (or only those in `only`) put in at the marker, under a name of
+// this process's own, so writers checking their scenes at the same time never share one.
+export function filmPage(dir: string, only: string[] = []): FilmPage {
+  const index = join(dir, "index.html");
+  const all = sceneFiles(dir);
+  const unknown = only.filter((n) => !all.includes(n));
+  if (unknown.length)
+    throw new Error(`no such scene file in ${join(dir, DIR)}: ${unknown.join(", ")}`);
+  if (!all.length) return { file: index, ids: null, close: () => {} };
+  const html = readFileSync(index, "utf8");
+  if (!html.includes(MARKER))
+    throw new Error(
+      `${index} has no "${MARKER}" line, so the files in ${join(dir, DIR)} have nowhere to go. ` +
+        "Put it inside #root, after the parts that stay across scenes."
+    );
+  const picked = only.length ? only : all;
+  const parts = picked.map((n) => readFileSync(join(dir, DIR, n), "utf8"));
+  const file = join(dir, `.page-${process.pid}-${made++}.html`);
+  writeFileSync(
+    file,
+    html.replace(MARKER, () => parts.join("\n"))
+  );
+  return {
+    file,
+    ids: only.length ? parts.flatMap(sceneIds) : null,
+    close: () => rmSync(file, { force: true }),
+  };
+}
diff --git a/skills/motion-render/scripts/sfx.ts b/skills/motion-render/scripts/sfx.ts
index f595a53..98d9a25 100644
--- a/skills/motion-render/scripts/sfx.ts
+++ b/skills/motion-render/scripts/sfx.ts
@@ -4,6 +4,8 @@ import { join } from "node:path";
 import { createHash } from "node:crypto";
 import { errorMessage, field, readJson } from "./json.ts";
 import {
+  Busy,
+  busyWait,
   runFfmpeg,
   sfxChain,
   TIMEOUT_MS,
@@ -11,6 +13,7 @@ import {
   withRetries,
   type SfxTrack,
 } from "./audio.ts";
+import { inParallel } from "./inorder.ts";
 import type { Script, SfxCue } from "./work.ts";
 
 const API = "https://api.elevenlabs.io/v1/sound-generation?output_format=mp3_44100_128"; // the best format pay-as-you-go allows
@@ -23,6 +26,9 @@ const UNDER_NARRATION_DB = 4;
 const PEAK_DB = -1;
 const NARRATION_DB = -16; // Gemini TTS's usual average level, for when there is no narration yet
 const PREVIEW_GAP = 0.6;
+// Effects made at once. ElevenLabs allows 2 to 10 requests at a time depending on the plan and
+// answers 429 past that, which makes a call wait (Busy).
+const SFX_AT_ONCE = 3;
 
 interface Level {
   mean: number;
@@ -65,7 +71,11 @@ async function soundEffect(key: string, prompt: string, duration: number): Promi
     } catch {
       body = text; // not JSON: the status alone has to do
     }
-    throw new Error(`HTTP ${res.status} ${apiReason(body)}`.trim());
+    const msg = `HTTP ${res.status} ${apiReason(body)}`.trim();
+    // Also sent when more requests run at once than the plan allows.
+    if (res.status === 429)
+      throw new Busy(msg, busyWait(body, res.headers.get("retry-after"), 2_000));
+    throw new Error(msg);
   }
   return Buffer.from(await res.arrayBuffer());
 }
@@ -84,14 +94,15 @@ export async function makeSfx(work: string, script: Script): Promise<number> {
   const key = process.env.ELEVENLABS_API_KEY;
   if (!key) throw new Error("ELEVENLABS_API_KEY is not set (needed for sound effects)");
   mkdirSync(join(work, "audio", "sfx"), { recursive: true });
-  for (const { prompt, duration } of todo.values()) {
+  await inParallel([...todo.values()], SFX_AT_ONCE, async ({ prompt, duration }) => {
     console.error(`sound effect: ${prompt}`);
     const mp3 = sfxFile(work, prompt, duration, "mp3");
     const level = await withRetries(`sound effect "${prompt}"`, async (): Promise<Level> => {
       try {
         writeFileSync(mp3, await soundEffect(key, prompt, duration));
       } catch (e) {
-        throw new Error(`sound effect "${prompt}": ${errorMessage(e)}`);
+        const msg = `sound effect "${prompt}": ${errorMessage(e)}`;
+        throw e instanceof Busy ? new Busy(msg, e.wait) : new Error(msg);
       }
       const l = await volumeStats(mp3);
       if (l.max < SILENT_DB)
@@ -102,7 +113,7 @@ export async function makeSfx(work: string, script: Script): Promise<number> {
       sfxFile(work, prompt, duration, "json"),
       JSON.stringify({ prompt, duration, ...level }, null, 2)
     );
-  }
+  });
   return todo.size;
 }
 
diff --git a/skills/motion-render/scripts/steps.ts b/skills/motion-render/scripts/steps.ts
new file mode 100644
index 0000000..54b4bf8
--- /dev/null
+++ b/skills/motion-render/scripts/steps.ts
@@ -0,0 +1,131 @@
+// 1 本の動画を作る間に、各コマンドがいつからいつまで動いたかを <work>/steps.jsonl に残し、
+// コマンドの時間と、その間の Claude の作業（原稿・映像を書く、静止画を見る）の時間に分けて表にする（times）。
+import { appendFileSync, existsSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { field } from "./json.ts";
+
+interface Step {
+  cmd: string;
+  start: number; // ms since the epoch
+  end: number;
+  ok: boolean;
+}
+
+const FILE = "steps.jsonl";
+// Commands Claude starts in the background and keeps working while they run (SKILL.md), so their
+// time is not a wait and the time beside them still counts as Claude's.
+const BACKGROUND = new Set(["bgm", "sfx"]);
+const GAP_MS = 1_000; // shorter gaps between commands are the shell, not work
+
+// The work dir a command's path belongs to: <work> itself, or <work> for <work>/film. Null when the
+// path is not in a work dir (a film dir on its own), so nothing is logged.
+export function workOf(path: string): string | null {
+  const p = resolve(path);
+  for (const w of [p, basename(p) === "film" ? dirname(p) : null])
+    if (w && existsSync(join(w, "script.json"))) return w;
+  return null;
+}
+
+// Runs a command and logs its span, whether it succeeds or fails.
+export async function timed<T>(
+  work: string | null,
+  cmd: string,
+  run: () => Promise<T> | T
+): Promise<T> {
+  const start = Date.now();
+  let ok = false;
+  try {
+    const r = await run();
+    ok = true;
+    return r;
+  } finally {
+    if (work) {
+      const step: Step = { cmd, start, end: Date.now(), ok };
+      appendFileSync(join(work, FILE), JSON.stringify(step) + "\n");
+    }
+  }
+}
+
+function parseStep(line: string): Step | null {
+  let v: unknown;
+  try {
+    v = JSON.parse(line);
+  } catch {
+    return null; // a line cut short by a crash: the other steps still count
+  }
+  const cmd = field(v, "cmd"),
+    start = field(v, "start"),
+    end = field(v, "end"),
+    ok = field(v, "ok");
+  return typeof cmd === "string" &&
+    typeof start === "number" &&
+    typeof end === "number" &&
+    typeof ok === "boolean"
+    ? { cmd, start, end, ok }
+    : null;
+}
+
+export function readSteps(work: string): Step[] {
+  const file = join(work, FILE);
+  if (!existsSync(file)) return [];
+  return readFileSync(file, "utf8")
+    .split("\n")
+    .map(parseStep)
+    .filter((s): s is Step => s !== null)
+    .sort((a, b) => a.start - b.start);
+}
+
+export interface Row {
+  at: number; // s from the start of the run
+  step: string;
+  seconds: number;
+}
+
+// The run as rows in time order. A run starts when the work dir was made (Claude makes it before it
+// writes script.json). Time no foreground command covers is Claude's; background commands are
+// listed but leave that time to Claude.
+export function stepRows(steps: Step[], runStart: number): Row[] {
+  const rows: Row[] = [];
+  let cursor = Math.min(runStart, steps[0]?.start ?? runStart);
+  const t0 = cursor;
+  const s = (ms: number) => Math.round(ms / 100) / 10;
+  for (const st of steps) {
+    const name = `${st.cmd}${st.ok ? "" : " (failed)"}`;
+    if (BACKGROUND.has(st.cmd)) {
+      rows.push({
+        at: s(st.start - t0),
+        step: `${name} (background)`,
+        seconds: s(st.end - st.start),
+      });
+      continue;
+    }
+    if (st.start - cursor > GAP_MS)
+      rows.push({ at: s(cursor - t0), step: "Claude", seconds: s(st.start - cursor) });
+    rows.push({ at: s(st.start - t0), step: name, seconds: s(st.end - st.start) });
+    cursor = Math.max(cursor, st.end);
+  }
+  return rows;
+}
+
+const clock = (sec: number): string =>
+  `${Math.floor(sec / 60)}:${String(Math.floor(sec % 60)).padStart(2, "0")}`;
+const span = (sec: number): string =>
+  sec < 60 ? `${sec.toFixed(1)} s` : `${Math.floor(sec / 60)} min ${Math.round(sec % 60)} s`;
+
+// A Markdown table of the run, with the totals of Claude's time and of the commands it waited for.
+export function stepsTable(work: string): string {
+  const steps = readSteps(work);
+  if (!steps.length) return `no steps logged in ${join(work, FILE)}`;
+  const born = statSync(work);
+  const rows = stepRows(steps, born.birthtimeMs || born.ctimeMs);
+  const sum = (f: (r: Row) => boolean) => rows.filter(f).reduce((a, r) => a + r.seconds, 0);
+  const last = rows.reduce((a, r) => Math.max(a, r.at + r.seconds), 0);
+  const claude = sum((r) => r.step === "Claude");
+  return [
+    "| Start | Step | Time |",
+    "| --- | --- | --- |",
+    ...rows.map((r) => `| ${clock(r.at)} | ${r.step} | ${span(r.seconds)} |`),
+    "",
+    `total ${span(last)}: Claude ${span(claude)}, waiting on commands ${span(last - claude)}`,
+  ].join("\n");
+}
diff --git a/tests/audio.test.ts b/tests/audio.test.ts
index 7ac17c8..c1f7e1d 100644
--- a/tests/audio.test.ts
+++ b/tests/audio.test.ts
@@ -124,12 +124,65 @@ describe("narrate", () => {
     const dir = workDir(SCRIPT);
     fetchMock.mockImplementation(
       async () =>
-        new Response(JSON.stringify({ error: { message: "quota exceeded" } }), { status: 429 })
+        new Response(JSON.stringify({ error: { message: "internal error" } }), { status: 500 })
+    );
+    await expect(narrate(dir, loadScript(dir))).rejects.toThrow(
+      "gemini-3.8-flash-tts: HTTP 500 internal error"
+    );
+    expect(fetchMock).toHaveBeenCalledTimes(6); // both scenes run at once, 3 attempts each
+  });
+
+  it("narrates several scenes at once", async () => {
+    const scenes = Array.from({ length: 8 }, (_, i) => ({ id: `s${i}`, narration: `場面${i}` }));
+    const dir = workDir({ ...SCRIPT, scenes });
+    let running = 0,
+      most = 0;
+    fetchMock.mockImplementation(async () => {
+      most = Math.max(most, ++running);
+      await new Promise((ok) => setTimeout(ok, 10));
+      running--;
+      return audioResponse("audio/wav", wav(0.5));
+    });
+    await narrate(dir, loadScript(dir));
+    expect(fetchMock).toHaveBeenCalledTimes(8);
+    expect(most).toBe(4);
+    for (const s of scenes) expect(existsSync(join(dir, "audio", `${s.id}.wav`))).toBe(true);
+  });
+
+  it("waits out a rate limit for the delay Gemini asks for, without using up an attempt", async () => {
+    const dir = workDir(SCRIPT);
+    const busy = () =>
+      new Response(
+        JSON.stringify({
+          error: {
+            message: "quota exceeded",
+            details: [{ "@type": "type.googleapis.com/google.rpc.RetryInfo", retryDelay: "0.01s" }],
+          },
+        }),
+        { status: 429 }
+      );
+    let calls = 0;
+    fetchMock.mockImplementation(async () =>
+      ++calls <= 4 ? busy() : audioResponse("audio/wav", wav(0.5))
+    );
+    await narrate(dir, loadScript(dir));
+    expect(fetchMock).toHaveBeenCalledTimes(6);
+    expect(existsSync(join(dir, "audio", "flow.wav"))).toBe(true);
+  });
+
+  it("gives up on a rate limit that never lifts", async () => {
+    const dir = workDir({ ...SCRIPT, scenes: [SCRIPT.scenes[0]] });
+    fetchMock.mockImplementation(
+      async () =>
+        new Response(JSON.stringify({ error: { message: "quota exceeded" } }), {
+          status: 429,
+          headers: { "retry-after": "0" },
+        })
     );
     await expect(narrate(dir, loadScript(dir))).rejects.toThrow(
       "gemini-3.8-flash-tts: HTTP 429 quota exceeded"
     );
-    expect(fetchMock).toHaveBeenCalledTimes(3);
+    expect(fetchMock).toHaveBeenCalledTimes(13); // 10 waits, then 3 attempts
   });
 
   it("fails when the response has no audio", async () => {
diff --git a/tests/inorder.test.ts b/tests/inorder.test.ts
index 3d6f924..2e05675 100644
--- a/tests/inorder.test.ts
+++ b/tests/inorder.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { inOrder } from "../skills/motion-render/scripts/inorder.ts";
+import { inOrder, inParallel } from "../skills/motion-render/scripts/inorder.ts";
 
 const wait = (ms: number) => new Promise((ok) => setTimeout(ok, ms));
 
@@ -32,3 +32,31 @@ describe("inOrder", () => {
     expect(out).toEqual([0, 1]);
   });
 });
+
+describe("inParallel", () => {
+  it("runs every item with no more than `n` at once", async () => {
+    let running = 0,
+      most = 0;
+    const done: number[] = [];
+    await inParallel([1, 2, 3, 4, 5], 2, async (i) => {
+      most = Math.max(most, ++running);
+      await wait(5);
+      running--;
+      done.push(i);
+    });
+    expect(done.sort()).toEqual([1, 2, 3, 4, 5]);
+    expect(most).toBe(2);
+  });
+
+  it("starts nothing new after a failure, lets the running ones finish and throws the first error", async () => {
+    const started: number[] = [];
+    await expect(
+      inParallel([1, 2, 3, 4, 5], 2, async (i) => {
+        started.push(i);
+        await wait(i === 1 ? 1 : 10);
+        if (i === 1) throw new Error("item 1 failed");
+      })
+    ).rejects.toThrow("item 1 failed");
+    expect(started).toEqual([1, 2]);
+  });
+});
diff --git a/tests/scenes.test.ts b/tests/scenes.test.ts
new file mode 100644
index 0000000..a2f54d5
--- /dev/null
+++ b/tests/scenes.test.ts
@@ -0,0 +1,118 @@
+// Scene files: an html film written as index.html plus film/scenes/*.html, put together at its marker.
+import { describe, expect, it } from "vitest";
+import { mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { openFilm } from "../skills/motion-render/scripts/render.ts";
+import { checkLayout, formatIssue } from "../skills/motion-render/scripts/layout.ts";
+import { filmPage, sceneIds } from "../skills/motion-render/scripts/scenes.ts";
+import { writeKit } from "../skills/motion-render/scripts/kit.ts";
+import { tempDir } from "./helpers.ts";
+
+const CLI = join(import.meta.dirname, "..", "skills", "motion-render", "scripts", "cli.ts");
+
+const TIMING = {
+  total: 2,
+  scenes: [
+    { id: "intro", name: "Intro", start: 0, dur: 1, speech: 0.8 },
+    { id: "deny", name: "Deny", start: 1, dur: 1, speech: 0.8 },
+  ],
+};
+
+// The shared page: head, palette and a part that stays across scenes. The scenes go in at the marker.
+const INDEX = `<!doctype html>
+<html lang="ja"><head><meta charset="utf-8">
+<link rel="stylesheet" href="kit/fonts.css"><link rel="stylesheet" href="kit/base.css">
+<script src="kit/gsap.min.js"></script><script src="kit/timing.js"></script><script src="kit/player.js"></script>
+<style>body { background: #0b1622; color: #e9f0f7; }</style></head>
+<body><div id="root">
+  <div id="stage"><p id="logo" class="layer-card" style="position:absolute; left:200px; top:900px; font-size:30px">ロゴ</p></div>
+  <!-- scenes -->
+</div></body></html>`;
+
+const INTRO = `<style>#title { font-size: 80px; }</style>
+<section class="scene" id="intro"><h1 id="title">条件</h1></section>
+<script>
+  film.build(function (tl) {
+    tl.fromTo("#title", { opacity: 0 }, { opacity: 1, duration: 0.3 }, film.at("intro", 0.1));
+  });
+</script>`;
+
+// A ✕ placed on its own, half under the box.
+const DENY = `<section class="scene" id="deny">
+  <div id="cond" class="layer-card" style="position:absolute; left:900px; top:290px; padding:16px; background:#0f1d31; font-size:30px">条件の箱</div>
+  <div id="cross" style="position:absolute; left:868px; top:300px; font-size:64px">✕</div>
+</section>`;
+
+function sceneFilm(files: Record<string, string>, index = INDEX): string {
+  const work = tempDir("mr-scenes-");
+  writeFileSync(join(work, "timing.json"), JSON.stringify(TIMING));
+  const film = writeKit(work);
+  writeFileSync(join(film, "index.html"), index);
+  mkdirSync(join(film, "scenes"));
+  for (const [name, html] of Object.entries(files)) writeFileSync(join(film, "scenes", name), html);
+  return film;
+}
+
+describe("filmPage", () => {
+  it("is index.html itself when there are no scene files", () => {
+    const work = tempDir("mr-scenes-");
+    expect(filmPage(work).file).toBe(join(work, "index.html"));
+  });
+
+  it("puts the scene files in at the marker in name order, and removes its copy on close", () => {
+    const film = sceneFilm({ "02-deny.html": DENY, "01-intro.html": INTRO });
+    const page = filmPage(film);
+    const html = readdirSync(film).filter((n) => n.startsWith(".page-"));
+    expect(html).toHaveLength(1);
+    expect(page.ids).toBeNull();
+    page.close();
+    expect(readdirSync(film).filter((n) => n.startsWith(".page-"))).toEqual([]);
+  });
+
+  it("names a missing marker and an unknown scene file", () => {
+    expect(() => filmPage(sceneFilm({ "01-intro.html": INTRO }, "<html></html>"))).toThrow(
+      /has no "<!-- scenes -->" line/
+    );
+    expect(() => filmPage(sceneFilm({ "01-intro.html": INTRO }), ["03-end.html"])).toThrow(
+      /no such scene file .*: 03-end\.html/
+    );
+  });
+
+  it("reads the scene ids of a file", () => {
+    expect(sceneIds(INTRO + DENY)).toEqual(["intro", "deny"]);
+    expect(sceneIds('<section class="box" id="x"></section>')).toEqual([]);
+  });
+});
+
+describe("a film in scene files", () => {
+  it("draws like one page, and checks only the scenes of the files asked for", async () => {
+    const film = sceneFilm({ "01-intro.html": INTRO, "02-deny.html": DENY });
+    const whole = await openFilm(film);
+    try {
+      expect(whole.meta.duration).toBe(2);
+      expect((await checkLayout(whole))?.map(formatIssue)).toEqual([
+        `1.1-1.9s: #cond "条件の箱" and #cross "✕" partly overlap`,
+      ]);
+      expect(await whole.warnings()).toEqual([]);
+    } finally {
+      await whole.close();
+    }
+    const intro = await openFilm(film, { scenes: ["01-intro.html"] });
+    try {
+      expect(intro.only).toEqual(["intro"]);
+      expect(await checkLayout(intro)).toEqual([]);
+    } finally {
+      await intro.close();
+    }
+    expect(readdirSync(film).filter((n) => n.startsWith(".page-"))).toEqual([]);
+  });
+
+  it("is checked by scene file with the check command", () => {
+    const film = sceneFilm({ "01-intro.html": INTRO, "02-deny.html": DENY });
+    const run = (...args: string[]) =>
+      execFileSync(process.execPath, [CLI, ...args], { encoding: "utf8", stdio: "pipe" });
+    expect(run("check", film, "01-intro.html")).toContain("layout ok");
+    expect(() => run("check", film, "02-deny.html")).toThrow(/#cross "✕" partly overlap/);
+  });
+});
diff --git a/tests/sfx.test.ts b/tests/sfx.test.ts
index 81be7e9..f72843a 100644
--- a/tests/sfx.test.ts
+++ b/tests/sfx.test.ts
@@ -64,6 +64,31 @@ const sfxPath = (dir: string, prompt: string, duration: number, ext: string) =>
   join(dir, "audio", "sfx", `${sfxKey(prompt, duration)}.${ext}`);
 
 describe("makeSfx", () => {
+  it("makes up to three effects at once and waits out a 429 for its Retry-After", async () => {
+    const fx = Array.from({ length: 6 }, (_, i) => ({ at: i, prompt: `sound ${i}`, duration: 1 }));
+    const dir = workDir({ ...SCRIPT, scenes: [{ ...SCRIPT.scenes[0], sfx: fx }] });
+    let running = 0,
+      most = 0,
+      calls = 0;
+    fetchMock.mockImplementation(async () => {
+      if (++calls === 1)
+        return new Response(
+          JSON.stringify({ detail: { message: "too many concurrent requests" } }),
+          {
+            status: 429,
+            headers: { "retry-after": "0.01" },
+          }
+        );
+      most = Math.max(most, ++running);
+      await new Promise((ok) => setTimeout(ok, 10));
+      running--;
+      return new Response(Buffer.from("mp3"), { status: 200 });
+    });
+    expect(await makeSfx(dir, loadScript(dir))).toBe(6);
+    expect(fetchMock).toHaveBeenCalledTimes(7);
+    expect(most).toBe(3);
+  });
+
   it("asks ElevenLabs once per distinct effect and stores the MP3 with its measured level", async () => {
     const dir = workDir(SFX_SCRIPT);
     expect(await makeSfx(dir, loadScript(dir))).toBe(2);
diff --git a/tests/steps.test.ts b/tests/steps.test.ts
new file mode 100644
index 0000000..a2d26c5
--- /dev/null
+++ b/tests/steps.test.ts
@@ -0,0 +1,103 @@
+// The log of a run's steps (steps.jsonl) and the table made from it.
+import { describe, expect, it } from "vitest";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+import {
+  readSteps,
+  stepRows,
+  stepsTable,
+  timed,
+  workOf,
+} from "../skills/motion-render/scripts/steps.ts";
+import { tempDir } from "./helpers.ts";
+
+const CLI = join(import.meta.dirname, "..", "skills", "motion-render", "scripts", "cli.ts");
+
+function work(): string {
+  const dir = tempDir("mr-steps-");
+  writeFileSync(join(dir, "script.json"), "{}");
+  mkdirSync(join(dir, "film"));
+  return dir;
+}
+
+const step = (cmd: string, start: number, end: number, ok = true) => ({ cmd, start, end, ok });
+
+describe("workOf", () => {
+  it("finds the work dir of a work dir and of its film dir, and nothing elsewhere", () => {
+    const dir = work();
+    expect(workOf(dir)).toBe(dir);
+    expect(workOf(join(dir, "film"))).toBe(dir);
+    expect(workOf(tempDir())).toBeNull();
+  });
+});
+
+describe("timed", () => {
+  it("logs a command that succeeds and one that fails", async () => {
+    const dir = work();
+    expect(await timed(dir, "narrate", () => 1)).toBe(1);
+    await expect(
+      timed(dir, "check", () => Promise.reject(new Error("3 layout issues")))
+    ).rejects.toThrow("3 layout issues");
+    expect(readSteps(dir).map(({ cmd, ok }) => [cmd, ok])).toEqual([
+      ["narrate", true],
+      ["check", false],
+    ]);
+  });
+
+  it("logs nothing without a work dir, and skips a broken line", async () => {
+    expect(await timed(null, "check", () => "ok")).toBe("ok");
+    const dir = work();
+    writeFileSync(join(dir, "steps.jsonl"), '{"cmd":"kit","start":1,"end":2,"ok":true}\n{"cmd":');
+    expect(readSteps(dir)).toEqual([step("kit", 1, 2)]);
+  });
+});
+
+describe("stepRows", () => {
+  it("gives the time between foreground commands to Claude and lists background ones beside it", () => {
+    const rows = stepRows(
+      [
+        step("narrate", 120_000, 140_000),
+        step("bgm", 141_000, 170_000),
+        step("sfx", 142_000, 160_000),
+        step("kit", 140_500, 141_000),
+        step("check", 400_000, 430_000, false),
+        step("check", 431_500, 450_000),
+      ].sort((a, b) => a.start - b.start),
+      0
+    );
+    expect(rows).toEqual([
+      { at: 0, step: "Claude", seconds: 120 },
+      { at: 120, step: "narrate", seconds: 20 },
+      { at: 140.5, step: "kit", seconds: 0.5 },
+      { at: 141, step: "bgm (background)", seconds: 29 },
+      { at: 142, step: "sfx (background)", seconds: 18 },
+      { at: 141, step: "Claude", seconds: 259 },
+      { at: 400, step: "check (failed)", seconds: 30 },
+      { at: 430, step: "Claude", seconds: 1.5 },
+      { at: 431.5, step: "check", seconds: 18.5 },
+    ]);
+  });
+
+  it("counts commands that overlap once", () => {
+    const rows = stepRows([step("check", 0, 10_000), step("check", 2_000, 12_000)], 0);
+    expect(rows.map((r) => r.step)).toEqual(["check", "check"]);
+  });
+});
+
+describe("the times command", () => {
+  it("prints the commands the CLI logged as a table with totals", () => {
+    const dir = work();
+    writeFileSync(join(dir, "timing.json"), JSON.stringify({ total: 1, scenes: [] }));
+    const run = (...args: string[]) =>
+      execFileSync(process.execPath, [CLI, ...args], { encoding: "utf8", stdio: "pipe" });
+    run("kit", dir);
+    const log = readFileSync(join(dir, "steps.jsonl"), "utf8");
+    expect(log).toMatch(/"cmd":"kit"/);
+    const table = run("times", dir);
+    expect(table).toContain("| Start | Step | Time |");
+    expect(table).toMatch(/\| kit \| \d+\.\d s \|/);
+    expect(table).toMatch(/^total .*: Claude .*, waiting on commands /m);
+    expect(stepsTable(tempDir())).toMatch(/^no steps logged/);
+  });
+});

From 176d47ecd2172b4538ccb16eaacc34a0b82f0698 Mon Sep 17 00:00:00 2001
From: umiyosh <yumino99@gmail.com>
Date: Fri, 6 Nov 2026 01:22:17 +0900
Subject: [PATCH 2/6] feat(kit): add parts for step rows, cards, time lanes,
 rulers and captions

---
 skills/motion-render/kit/parts.css    | 161 ++++++++++++++++++++++++++
 skills/motion-render/kit/player.js    |  44 +++++++
 skills/motion-render/scripts/audio.ts |   2 +-
 skills/motion-render/scripts/kit.ts   |   5 +-
 tests/parts.test.ts                   | 110 ++++++++++++++++++
 tests/sfx.test.ts                     |   5 +-
 6 files changed, 322 insertions(+), 5 deletions(-)
 create mode 100644 skills/motion-render/kit/parts.css
 create mode 100644 tests/parts.test.ts

diff --git a/skills/motion-render/kit/parts.css b/skills/motion-render/kit/parts.css
new file mode 100644
index 0000000..8a94932
--- /dev/null
+++ b/skills/motion-render/kit/parts.css
@@ -0,0 +1,161 @@
+/* Parts that explainer films keep drawing, so a scene gives only its content and seconds: a row of
+   step cards, a card, lanes on a time axis, a scale with ticks, and the caption. Colors come from the
+   page's variables (--panel --line --ink --muted --accent), so the parts follow every style.
+   The player animates them: film.light (a step or card), film.ticks (a scale), film.caption. */
+
+/* A row of steps. --on is 0 (off) to 1 (lit); film.light tweens it. */
+.steps {
+  position: absolute;
+  display: flex;
+  gap: var(--steps-gap, 20px);
+}
+.step,
+.card {
+  --on: 0;
+  border: 3px solid color-mix(in srgb, var(--accent) calc(var(--on) * 100%), var(--line));
+  background: color-mix(in srgb, var(--accent) calc(var(--on) * 16%), var(--panel));
+  color: var(--ink);
+  border-radius: 14px;
+}
+/* In the hand-drawn styles add drawn: the style draws the line, and the part only lights it. */
+[data-style] :is(.step, .card).drawn {
+  border-color: transparent;
+}
+[data-style] :is(.step, .card).drawn::before {
+  border-color: color-mix(in srgb, var(--accent) calc(var(--on) * 100%), var(--line));
+}
+.step {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 10px;
+  min-width: var(--step-w, 150px);
+  padding: 18px 16px;
+  font-size: 28px;
+}
+.step > svg {
+  width: 44px;
+  height: 44px;
+  color: color-mix(in srgb, var(--accent) calc(var(--on) * 100%), var(--muted));
+}
+/* A card with a title and a body. Place it with position: absolute and a layer class. */
+.card {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  padding: 24px 28px;
+}
+.card-title {
+  font-size: 34px;
+  font-weight: 700;
+}
+.card-body {
+  font-size: 28px;
+  line-height: 1.5;
+  color: var(--muted);
+}
+
+/* Lanes on one time axis: names on the left, tracks on the right. --from and --to (seconds or any
+   unit) set the axis; a .seg starts at --at and lasts --len, a .pin sits at --at. */
+.lanes {
+  --from: 0;
+  --to: 10;
+  position: absolute;
+  display: grid;
+  grid-template-columns: auto 1fr;
+  gap: 14px 20px;
+  align-items: center;
+}
+.lane-name {
+  font-size: 26px;
+  color: var(--muted);
+  text-align: right;
+}
+.track {
+  position: relative;
+  height: var(--lane-h, 52px);
+  border: 2px solid var(--line);
+  border-radius: 10px;
+  background: var(--panel);
+}
+.seg,
+.pin {
+  position: absolute;
+  left: calc((var(--at) - var(--from)) / (var(--to) - var(--from)) * 100%);
+}
+.seg {
+  top: 6px;
+  bottom: 6px;
+  width: calc(var(--len) / (var(--to) - var(--from)) * 100%);
+  display: flex;
+  align-items: center;
+  padding: 0 12px;
+  border: 2px solid var(--accent);
+  border-radius: 8px;
+  background: color-mix(in srgb, var(--accent) 22%, var(--panel));
+  font-size: 24px;
+  white-space: nowrap;
+}
+.pin {
+  top: 50%;
+  width: 18px;
+  height: 18px;
+  margin: -9px 0 0 -9px;
+  border-radius: 50%;
+  background: var(--accent);
+}
+
+/* A scale: a line with ticks and labels, made by film.ticks. --from and --to set its ends. The line
+   runs --ruler-pad in from each side, so the labels at its ends stay inside the box. */
+.ruler {
+  --from: 0;
+  --to: 10;
+  --ruler-pad: 60px;
+  position: absolute;
+  height: 72px;
+}
+.ruler::before {
+  content: "";
+  position: absolute;
+  left: var(--ruler-pad);
+  right: var(--ruler-pad);
+  top: 10px;
+  border-top: 3px solid var(--line);
+}
+.tick {
+  position: absolute;
+  top: 0;
+  left: calc(
+    var(--ruler-pad) + (var(--at) - var(--from)) / (var(--to) - var(--from)) *
+      (100% - 2 * var(--ruler-pad))
+  );
+  transform: translateX(-50%);
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+  font-size: 24px;
+  font-style: normal;
+  color: var(--ink);
+  white-space: nowrap;
+  font-variant-numeric: tabular-nums;
+}
+.tick::before {
+  content: "";
+  width: 3px;
+  height: 23px;
+  background: var(--line);
+}
+
+/* The caption: one line across the bottom, inside the safe area. Add layer-caption. */
+.caption {
+  position: absolute;
+  left: var(--safe-x);
+  right: var(--safe-x);
+  bottom: calc(var(--safe-y) + 8px);
+  text-align: center;
+  font-size: 54px;
+  font-weight: 700;
+  color: var(--ink);
+}
diff --git a/skills/motion-render/kit/player.js b/skills/motion-render/kit/player.js
index f3d0c4d..6f8d02f 100644
--- a/skills/motion-render/kit/player.js
+++ b/skills/motion-render/kit/player.js
@@ -181,6 +181,50 @@
         at
       );
     },
+    // Lights a .step or .card of kit/parts.css at `at` (its --on goes to 1), and puts it out again
+    // at o.off when given. o: { dur = 0.35, off }.
+    light: function (tl, what, at, o) {
+      o = o || {};
+      var dur = o.dur || 0.35;
+      tl.to(what, { "--on": 1, duration: dur, ease: "power2.out" }, at);
+      if (o.off !== undefined) tl.to(what, { "--on": 0, duration: dur, ease: "power2.in" }, o.off);
+      return tl;
+    },
+    // Fills a .ruler of kit/parts.css with a tick every o.step from its --from to its --to, each
+    // labeled with o.label ("{v} 秒"; "" for no labels). Call it inside film.build.
+    ticks: function (what, o) {
+      var e = el(what),
+        css = getComputedStyle(e),
+        from = Number(css.getPropertyValue("--from")),
+        to = Number(css.getPropertyValue("--to")),
+        step = o && o.step,
+        label = o && o.label !== undefined ? o.label : "{v}";
+      if (!(step > 0) || !(to > from)) throw new Error("film.ticks needs --from < --to and a step");
+      for (var i = 0; from + i * step <= to + 1e-9; i++) {
+        var v = Math.round((from + i * step) * 1000) / 1000,
+          t = document.createElement("i");
+        t.className = "tick";
+        t.style.setProperty("--at", String(v));
+        if (label) t.textContent = label.replace("{v}", String(v));
+        e.appendChild(t);
+      }
+      return e;
+    },
+    // Shows a caption from `at` and takes it away so it is gone 0.25 s before scene `id` ends, as
+    // references/html-film.md asks.
+    caption: function (tl, what, id, at) {
+      tl.fromTo(
+        what,
+        { autoAlpha: 0, y: 16 },
+        { autoAlpha: 1, y: 0, duration: 0.4, ease: "expo.out" },
+        at
+      );
+      return tl.to(
+        what,
+        { autoAlpha: 0, duration: 0.2, ease: "power3.in" },
+        window.film.end(id, 0.45)
+      );
+    },
     // Raises the text of `what` one character at a time from below a mask line, starting `at`.
     // The text is split into spans the first time, so call it on an element that holds only text.
     // o: { dur = 0.5, stagger = 0.04 }.
diff --git a/skills/motion-render/scripts/audio.ts b/skills/motion-render/scripts/audio.ts
index cd532b9..a6d37be 100644
--- a/skills/motion-render/scripts/audio.ts
+++ b/skills/motion-render/scripts/audio.ts
@@ -150,7 +150,7 @@ export async function withRetries<T>(label: string, attempt: () => Promise<T>):
   let last: unknown;
   let waited = 0,
     waits = 0;
-  for (let i = 1; i <= RETRIES;) {
+  for (let i = 1; i <= RETRIES; ) {
     try {
       return await attempt();
     } catch (e) {
diff --git a/skills/motion-render/scripts/kit.ts b/skills/motion-render/scripts/kit.ts
index d4f0e00..df842bb 100644
--- a/skills/motion-render/scripts/kit.ts
+++ b/skills/motion-render/scripts/kit.ts
@@ -1,4 +1,4 @@
-// Sets up <work>/film for an html film: the player, the stylesheets, GSAP, the Japanese fonts
+// Sets up <work>/film for an html film: the player, the stylesheets (and the parts of parts.css), GSAP, the Japanese fonts
 // and the scene times. Claude writes <work>/film/index.html against these files.
 import { copyFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
@@ -45,7 +45,8 @@ export function writeKit(work: string): string {
   const film = join(work, "film");
   const kit = join(film, "kit");
   mkdirSync(join(kit, "fonts"), { recursive: true });
-  for (const f of ["player.js", "base.css", "styles.css"]) copyFileSync(join(KIT, f), join(kit, f));
+  for (const f of ["player.js", "base.css", "styles.css", "parts.css"])
+    copyFileSync(join(KIT, f), join(kit, f));
   const gsap = require.resolve("gsap/dist/gsap.min.js");
   copyFileSync(gsap, join(kit, basename(gsap)));
   writeFileSync(join(kit, "fonts.css"), FONT_CSS.map((f) => fontCss(f, kit)).join("\n"));
diff --git a/tests/parts.test.ts b/tests/parts.test.ts
new file mode 100644
index 0000000..1a85e37
--- /dev/null
+++ b/tests/parts.test.ts
@@ -0,0 +1,110 @@
+// The parts of kit/parts.css and the player's helpers for them: steps, cards, lanes, a ruler, a caption.
+import { describe, expect, it } from "vitest";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { openFilm } from "../skills/motion-render/scripts/render.ts";
+import { checkLayout, formatIssue } from "../skills/motion-render/scripts/layout.ts";
+import { writeKit } from "../skills/motion-render/scripts/kit.ts";
+import { tempDir } from "./helpers.ts";
+
+const TIMING = {
+  total: 4,
+  scenes: [
+    { id: "steps", name: "Steps", start: 0, dur: 2, speech: 1.5 },
+    { id: "lanes", name: "Lanes", start: 2, dur: 2, speech: 1.5 },
+  ],
+};
+
+const ICON = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="4" y="3" width="16" height="18" rx="2"/></svg>`;
+
+const PARTS_PAGE = `<!doctype html>
+<html lang="ja"><head><meta charset="utf-8">
+<link rel="stylesheet" href="kit/fonts.css"><link rel="stylesheet" href="kit/base.css">
+<link rel="stylesheet" href="kit/styles.css"><link rel="stylesheet" href="kit/parts.css">
+<script src="kit/gsap.min.js"></script><script src="kit/timing.js"></script><script src="kit/player.js"></script>
+<style>
+  :root { --ground: #0b1622; --panel: #12233a; --line: #2a4466; --ink: #e9f0f7; --muted: #8aa0b8; --accent: #3ed6c4; --danger: #ff6b6b; }
+  body { background: var(--ground); color: var(--ink); }
+  #row { left: 300px; top: 160px; }
+  #note { position: absolute; left: 300px; top: 420px; width: 700px; }
+  #axis { left: 200px; top: 200px; width: 1400px; --to: 10; }
+  #ruler { left: 400px; top: 600px; width: 1000px; --from: 0; --to: 10; }
+</style></head>
+<body><div id="root">
+  <section class="scene" id="steps">
+    <div id="row" class="steps layer-card">
+      <div class="step" id="s1">${ICON}<span>原稿</span></div>
+      <div class="step" id="s2">${ICON}<span>ナレーション</span></div>
+      <div class="step" id="s3">${ICON}<span>映像</span></div>
+    </div>
+    <div id="note" class="card layer-card"><span class="card-title">絵コンテ</span><span class="card-body">見せ場を何秒目に置くかを先に決める</span></div>
+    <p id="cap1" class="caption layer-caption">工程を順に進める</p>
+  </section>
+  <section class="scene" id="lanes">
+    <div id="axis" class="lanes layer-card">
+      <span class="lane-name">語り</span>
+      <div class="track"><div class="seg" id="seg" style="--at: 2; --len: 3"><span>場面 1</span></div></div>
+      <span class="lane-name">効果音</span>
+      <div class="track"><i class="pin" id="pin" style="--at: 7"></i></div>
+    </div>
+    <div id="ruler" class="ruler layer-line"></div>
+  </section>
+</div>
+<script>
+  film.build(function (tl) {
+    film.light(tl, "#s2", film.at("steps", 0.5), { off: film.at("steps", 1.2) });
+    film.caption(tl, "#cap1", "steps", film.at("steps", 0.3));
+    film.ticks("#ruler", { step: 2, label: "{v} 秒" });
+  });
+</script>
+</body></html>`;
+
+function partsFilm(html = PARTS_PAGE): string {
+  const work = tempDir("mr-parts-");
+  writeFileSync(join(work, "timing.json"), JSON.stringify(TIMING));
+  const film = writeKit(work);
+  writeFileSync(join(film, "index.html"), html);
+  return film;
+}
+
+describe("kit parts", () => {
+  it("lay out without layout issues, and place segments, pins and ticks on their axis", async () => {
+    const film = await openFilm(partsFilm());
+    try {
+      expect((await checkLayout(film))?.map(formatIssue)).toEqual([]);
+      const boxes = (await film.inspect?.(3)) ?? [];
+      const box = (l: string) => boxes.find((b) => b.label.startsWith(l));
+      const track = boxes.filter((b) => b.label.startsWith("div.track"))[0];
+      const seg = box("#seg");
+      const pin = box("#pin");
+      if (!track || !seg || !pin) throw new Error("parts not found");
+      // 2 s on a 0-10 s track starts a fifth of the way in (inside its 2px border); 3 s lasts 3 tenths.
+      const inner = track.w - 4;
+      expect(seg.x - (track.x + 2)).toBeCloseTo(inner * 0.2, 0);
+      expect(seg.w).toBeCloseTo(inner * 0.3, 0);
+      expect(pin.x + pin.w / 2 - (track.x + 2)).toBeCloseTo(inner * 0.7, 0);
+      const labels = boxes.filter((b) => b.label.startsWith("i.tick")).map((b) => b.label);
+      expect(labels).toHaveLength(6);
+      expect(labels[5]).toContain("10 秒");
+      expect(await film.warnings()).toEqual([]);
+    } finally {
+      await film.close();
+    }
+  });
+
+  it("lights a step while it is on and shows the caption until just before the scene ends", async () => {
+    const film = await openFilm(partsFilm());
+    try {
+      const off = await film.frame(0.2);
+      const on = await film.frame(1.0);
+      expect(on.equals(off)).toBe(false);
+      expect((await film.frame(1.8)).equals(await film.frame(1.85))).toBe(true);
+      const caption = async (t: number) =>
+        ((await film.inspect?.(t)) ?? []).some((b) => b.label.startsWith("#cap1"));
+      expect(await caption(1.0)).toBe(true);
+      expect(await caption(1.9)).toBe(false);
+    } finally {
+      await film.close();
+    }
+  });
+});
diff --git a/tests/sfx.test.ts b/tests/sfx.test.ts
index f72843a..e46b56c 100644
--- a/tests/sfx.test.ts
+++ b/tests/sfx.test.ts
@@ -27,8 +27,9 @@ vi.mock("node:child_process", async (importOriginal) => {
   };
 });
 
-const { checkSfx, makeSfx, narrationLevel, previewSfx, sfxKey, sfxTrack } =
-  await import("../skills/motion-render/scripts/sfx.ts");
+const { checkSfx, makeSfx, narrationLevel, previewSfx, sfxKey, sfxTrack } = await import(
+  "../skills/motion-render/scripts/sfx.ts"
+);
 const { volumeStats } = await import("../skills/motion-render/scripts/audio.ts");
 const { loadScript } = await import("../skills/motion-render/scripts/work.ts");
 

From 294e9420a630f91e13d8d7b846803d0503dec52a Mon Sep 17 00:00:00 2001
From: umiyosh <yumino99@gmail.com>
Date: Fri, 6 Nov 2026 01:26:39 +0900
Subject: [PATCH 3/6] docs(skill): write scenes in parallel from a shared plan
 and run BGM and sound effects in the background

---
 README.ja.md                                 | 28 +++---
 README.md                                    | 28 +++---
 skills/motion-render/SKILL.md                | 51 +++++++----
 skills/motion-render/references/html-film.md | 91 +++++++++++++++++---
 skills/motion-render/references/pipeline.md  | 34 ++++++++
 skills/motion-render/scripts/audio.ts        |  2 +-
 skills/motion-render/scripts/scenes.ts       |  4 +-
 tests/sfx.test.ts                            |  5 +-
 8 files changed, 188 insertions(+), 55 deletions(-)
 create mode 100644 skills/motion-render/references/pipeline.md

diff --git a/README.ja.md b/README.ja.md
index f5f6683..2b356dc 100644
--- a/README.ja.md
+++ b/README.ja.md
@@ -137,17 +137,18 @@ auto mode を使っていて、それでも実行が拒否される場合は、`
 
 動画 1 本ごとに作業フォルダ（`<work>`）を 1 つ使います。中身と `script.json` の書き方は [SKILL.md](skills/motion-render/SKILL.md) にあります。
 
-| コマンド                                         | やること                                                                                                                              |
-| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
-| `motion-render narrate <work>`                   | `script.json` の原稿からナレーションを作り、場面の秒数を `timing.json` に書く                                                         |
-| `motion-render bgm <work>`                       | `script.json` の `bgm` の指示から BGM を作る                                                                                          |
-| `motion-render sfx <work>`                       | `script.json` の `sfx` から効果音を作り、全部を順に聞ける `preview.m4a` を書く                                                        |
-| `motion-render prepare <storeDir> <work>/film`   | Motion: Motion から取得した映像データを、描画できる形に展開する                                                                       |
-| `motion-render kit <work>`                       | HTML: `<work>/film` にプレーヤー・スタイル・GSAP・日本語フォント・場面の秒数を置く。Claude はそのあと `film/index.html` を書く        |
-| `motion-render check <work>/film`                | HTML: 0.1 秒ごとに配置を調べ、重なり、箱や画面からのはみ出し、ほかのものの下に隠れたもの、小さすぎる文字や薄すぎる文字を報告する      |
-| `motion-render stills <filmDir> <outDir> 0,5,12` | 確認用の静止画を書き出す（HTML の映像は先に配置を調べる）                                                                             |
-| `motion-render build <work> [out.mp4]`           | ナレーション・BGM・効果音を合成し、映像と合わせて MP4 にする。どれかが足りないとき、HTML の映像が配置のチェックに通らないときは止まる |
-| `motion-render --version`                        | 版を表示する                                                                                                                          |
+| コマンド                                              | やること                                                                                                                                                                                                          |
+| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `motion-render narrate <work>`                        | `script.json` の原稿からナレーションを作り、場面の秒数を `timing.json` に書く                                                                                                                                     |
+| `motion-render bgm <work>`                            | `script.json` の `bgm` の指示から BGM を作る                                                                                                                                                                      |
+| `motion-render sfx <work>`                            | `script.json` の `sfx` から効果音を作り、全部を順に聞ける `preview.m4a` を書く                                                                                                                                    |
+| `motion-render prepare <storeDir> <work>/film`        | Motion: Motion から取得した映像データを、描画できる形に展開する                                                                                                                                                   |
+| `motion-render kit <work>`                            | HTML: `<work>/film` にプレーヤー・スタイル・GSAP・日本語フォント・場面の秒数を置く。Claude はそのあと `film/index.html` を書く                                                                                    |
+| `motion-render check <work>/film [<場面のファイル>…]` | HTML: 0.1 秒ごとに配置を調べ、重なり、箱や画面からのはみ出し、ほかのものの下に隠れたもの、小さすぎる文字や薄すぎる文字を報告する。場面のファイル（`film/scenes/` の名前）を渡すと、そのファイルの場面だけを調べる |
+| `motion-render stills <filmDir> <outDir> 0,5,12`      | 確認用の静止画を書き出す（HTML の映像は先に配置を調べる）                                                                                                                                                         |
+| `motion-render build <work> [out.mp4]`                | ナレーション・BGM・効果音を合成し、映像と合わせて MP4 にする。どれかが足りないとき、HTML の映像が配置のチェックに通らないときは止まる                                                                             |
+| `motion-render times <work>`                          | 工程ごとにかかった時間を表にする（各コマンドの時間と、その間の Claude の作業の時間）                                                                                                                              |
+| `motion-render --version`                             | 版を表示する                                                                                                                                                                                                      |
 
 | 環境変数                | 効果                                                                                       |
 | ----------------------- | ------------------------------------------------------------------------------------------ |
@@ -233,7 +234,8 @@ skills/motion-render/     # スキル本体（skills CLI とプラグインの
   SKILL.md                # Claude が読む手順（準備、絵コンテ・原稿・BGM の決め方を含む）
   package.json            # motion-render コマンドと、依存の版（playwright-core, ffmpeg-static, gsap, @fontsource/noto-sans-jp, @fontsource/klee-one）
   references/html-film.md # Claude が HTML の映像を書くときの決まり（配置、動き、配置のチェックの読み方）
-  kit/                    # kit が HTML の映像に写すプレーヤーと基本のスタイル、作風のスタイル
+  references/pipeline.md  # 工程のつながり（何を待ち、何を裏で動かすか）と、工程を足すときの決まり
+  kit/                    # kit が HTML の映像に写すプレーヤーと基本のスタイル、作風のスタイル、部品（parts.css）
   scripts/cli.ts          # motion-render コマンド
   scripts/audio.ts        # ナレーションと BGM の生成、音声の合成
   scripts/sfx.ts          # 効果音の生成（ElevenLabs）、音量のそろえ方、試聴用ファイル
@@ -241,6 +243,8 @@ skills/motion-render/     # スキル本体（skills CLI とプラグインの
   scripts/render.ts       # Motion と HTML の映像をブラウザで描画する部分
   scripts/kit.ts          # HTML の映像のフォルダを用意する
   scripts/layout.ts       # HTML の映像の配置のチェック
+  scripts/scenes.ts       # 場面のファイル（film/scenes/*.html）を index.html に差し込む
+  scripts/steps.ts        # 各コマンドの時間を残し、工程ごとの時間の表にする（times）
   scripts/snapshot.js     # 配置のチェックのため、映像のページの中で箱と文字を測る
   scripts/json.ts         # ファイル・API・プレーヤーから来る JSON を、形を確かめながら読む
   scripts/store.ts        # Motion の store を映像データのフォルダに展開する
diff --git a/README.md b/README.md
index a7aabbd..864275f 100644
--- a/README.md
+++ b/README.md
@@ -137,17 +137,18 @@ On the first run, Chromium (about 210 MB) and ffmpeg are downloaded automaticall
 
 Each video uses one work directory (`<work>`). Its layout and the `script.json` format are in [SKILL.md](skills/motion-render/SKILL.md).
 
-| Command                                          | What it does                                                                                                                                                         |
-| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `motion-render narrate <work>`                   | Generates narration from `script.json` and writes scene lengths to `timing.json`                                                                                     |
-| `motion-render bgm <work>`                       | Generates the BGM from the `bgm` prompt in `script.json`                                                                                                             |
-| `motion-render sfx <work>`                       | Generates the sound effects in `script.json` and a `preview.m4a` of them in order                                                                                    |
-| `motion-render prepare <storeDir> <work>/film`   | Motion: expands a Motion film's data into a directory it can render                                                                                                  |
-| `motion-render kit <work>`                       | HTML: sets up `<work>/film` with the player, styles, GSAP, the Japanese fonts and the scene times. Claude then writes `film/index.html`                              |
-| `motion-render check <work>/film`                | HTML: checks the layout every 0.1 s for overlaps, things sticking out of their box or the frame, things hidden under others, and text that is too small or too faint |
-| `motion-render stills <filmDir> <outDir> 0,5,12` | Writes still frames for checking (an HTML film is checked first)                                                                                                     |
-| `motion-render build <work> [out.mp4]`           | Mixes narration, BGM and sound effects and renders the MP4. Stops if any is missing, or if an HTML film fails the layout check                                       |
-| `motion-render --version`                        | Prints the version                                                                                                                                                   |
+| Command                                           | What it does                                                                                                                                                                                                                                |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `motion-render narrate <work>`                    | Generates narration from `script.json` and writes scene lengths to `timing.json`                                                                                                                                                            |
+| `motion-render bgm <work>`                        | Generates the BGM from the `bgm` prompt in `script.json`                                                                                                                                                                                    |
+| `motion-render sfx <work>`                        | Generates the sound effects in `script.json` and a `preview.m4a` of them in order                                                                                                                                                           |
+| `motion-render prepare <storeDir> <work>/film`    | Motion: expands a Motion film's data into a directory it can render                                                                                                                                                                         |
+| `motion-render kit <work>`                        | HTML: sets up `<work>/film` with the player, styles, GSAP, the Japanese fonts and the scene times. Claude then writes `film/index.html`                                                                                                     |
+| `motion-render check <work>/film [<scene file>…]` | HTML: checks the layout every 0.1 s for overlaps, things sticking out of their box or the frame, things hidden under others, and text that is too small or too faint. Given scene files (names in `film/scenes/`), checks only their scenes |
+| `motion-render stills <filmDir> <outDir> 0,5,12`  | Writes still frames for checking (an HTML film is checked first)                                                                                                                                                                            |
+| `motion-render build <work> [out.mp4]`            | Mixes narration, BGM and sound effects and renders the MP4. Stops if any is missing, or if an HTML film fails the layout check                                                                                                              |
+| `motion-render times <work>`                      | Shows how long each step took, as a table (each command, and Claude's work between them)                                                                                                                                                    |
+| `motion-render --version`                         | Prints the version                                                                                                                                                                                                                          |
 
 | Environment variable    | Effect                                                                                                  |
 | ----------------------- | ------------------------------------------------------------------------------------------------------- |
@@ -233,7 +234,8 @@ skills/motion-render/     # The skill (read by both the skills CLI and the plugi
   SKILL.md                # Instructions for Claude (setup, storyboard, script and BGM choices)
   package.json            # The motion-render command and pinned dependencies (playwright-core, ffmpeg-static, gsap, @fontsource/noto-sans-jp, @fontsource/klee-one)
   references/html-film.md # How Claude writes an HTML film: layout, motion, and reading the layout check
-  kit/                    # The player, base styles and drawing styles that `kit` copies into an HTML film
+  references/pipeline.md  # How the steps depend on each other (what waits, what runs in the background), and how to add a step
+  kit/                    # The player, base styles and drawing styles that `kit` copies into an HTML film, and the parts (parts.css)
   scripts/cli.ts          # The motion-render command
   scripts/audio.ts        # Narration and BGM generation, audio mixing
   scripts/sfx.ts          # Sound effect generation (ElevenLabs), leveling and the listening file
@@ -241,6 +243,8 @@ skills/motion-render/     # The skill (read by both the skills CLI and the plugi
   scripts/render.ts       # Rendering Motion and HTML films in the browser
   scripts/kit.ts          # Setting up an HTML film directory
   scripts/layout.ts       # The layout check of HTML films
+  scripts/scenes.ts       # Putting the scene files (film/scenes/*.html) into index.html
+  scripts/steps.ts        # Logging each command's time and making the per-step table (times)
   scripts/snapshot.js     # Measures boxes and text inside the film page for the layout check
   scripts/json.ts         # Reading JSON from files, APIs and the player without trusting its shape
   scripts/store.ts        # Expanding a Motion store into a film directory
diff --git a/skills/motion-render/SKILL.md b/skills/motion-render/SKILL.md
index 86e4908..a3dc417 100644
--- a/skills/motion-render/SKILL.md
+++ b/skills/motion-render/SKILL.md
@@ -62,8 +62,11 @@ Motion の Artifact 型は作成時に Style・Colors・Length を質問する
 <work>/
   script.json   # 原稿（Claude が書く）
   timing.json   # 場面の秒数（narrate が書く）
+  plan.md       # html の映像の絵コンテと秒の計画（Claude が書く。場面を手分けして書くときの共通の指示書）
+  steps.jsonl   # 各コマンドの開始と終了（コマンドが書く。motion-render times で表にする）
   audio/        # <場面id>.wav、bgm.mp3、mix.m4a、sfx/（効果音と試聴用の preview.m4a）
-  film/         # 映像。Motion から取得したもの（prepare が展開する）か、html の映像（kit が用意し、Claude が index.html を書く）
+  film/         # 映像。Motion から取得したもの（prepare が展開する）か、html の映像（kit が用意し、
+                # Claude が index.html と scenes/*.html を書く）
 ```
 
 `script.json` の形:
@@ -130,26 +133,40 @@ motion-render narrate <work>
 
 #### 3B. html の映像を作る
 
-1. `motion-render kit <work>` で `<work>/film/` にプレーヤー・フォント・GSAP・場面の秒数を置く
-2. [references/html-film.md](references/html-film.md) を読み、その決まりに従って `<work>/film/index.html` を書く。
-   先に「作る前に決めること」を依頼文とテーマから決め、ページの先頭に書く。
-   場面は `<section class="scene" id="<場面id>">`、動きは `film.build` の中で `film.at(場面id, 秒)` に置く
-3. 並行して BGM を作ってよい: `motion-render bgm <work>`
-4. 効果音を付けるときは、`script.json` の `sfx` の `at` に、その動きに渡した `film.at` の秒を書き、
-   `motion-render sfx <work>` で作る。タイトルの場面に `🎧:11.ai` を小さく入れる
+待ち時間を作らない順に進める。API を待つ工程（BGM・効果音）は Bash の `run_in_background` で裏に回し、
+その間に Claude は書き続ける。場面は手分けして同時に書く（工程のつながりは [references/pipeline.md](references/pipeline.md)）。
+
+1. `motion-render kit <work>` で `<work>/film/` にプレーヤー・部品・フォント・GSAP・場面の秒数を置き、
+   `motion-render bgm <work>` を裏で始める
+2. [references/html-film.md](references/html-film.md) を読み、`<work>/plan.md`（絵コンテと秒の計画）を書く。
+   場面ごとに、見せるもの、使う部品、動きとその秒（`film.at` に渡す秒）、効果音、場面をまたいで残る物の
+   入るときと出るときの状態を書く（書き方は html-film.md の「絵コンテと秒の計画」）
+3. 効果音を付けるときは、plan.md の効果音を `script.json` の `sfx` に写し、`motion-render sfx <work>` を裏で始める。
+   効果音は `prompt` と `duration` だけで作られるので、あとで `at` を直しても作り直しにはならない
+4. `<work>/film/index.html` に、全場面で共通の部分を書く: 「作る前に決めること」、配色、共通のスタイル、
+   場面をまたいで残る物（`#stage`）とその動き、場面を差し込む `<!-- scenes -->` の行
+5. 場面を書く。場面が 7 つ以上で Agent ツールがあれば、続いた場面を 3〜4 のまとまりに分け、
+   まとまりごとにサブエージェントを 1 つ、1 つのメッセージでまとめて起動する（頼み方は html-film.md の
+   「場面を分けて書く」）。各サブエージェントは `film/scenes/<番号>-<名前>.html` を書き、
+   `motion-render check <work>/film <そのファイル名>` を `layout ok` まで直して返す。
+   場面が 6 つ以下か Agent ツールが無いときは、Claude が同じ形で場面のファイルを書く
+6. 全員が返ったら `motion-render check <work>/film` で全体を調べ、まとまりの境目の問題を直す。
+   書いた動きの秒が plan.md と違えば、`script.json` の `sfx` の `at` をその秒に直す。
+   効果音を付けるときは、タイトルの場面に `🎧:11.ai` を小さく入れる
 
 ### 4. 映像を確認する
 
-html の映像（3B）は手順 4 の 1〜3 を飛ばし、先に `motion-render check <work>/film` を `layout: ok` になるまで直す
-（出力の読み方は references/html-film.md の「確認」）。そのあと 4・5 で静止画を見る。
+html の映像（3B）は手順 4 の 1〜3 を飛ばし、3B の 6 で `layout: ok` になってから 4・5 で静止画を見る
+（`check` の出力の読み方は references/html-film.md の「確認」）。直すのは、その場面がある `film/scenes/` のファイル。
 
 1. `Artifact` の `read` で `paths: ["index.html", "artifact-type/app.js", "artifact-type/app.css"]`、`out_dir: <work>/film`
 2. `ArtifactData` の `list`（`collection: "modules"`）と `get`（`film`/`script`）を `out_dir: <work>/store` で保存
 3. `motion-render prepare <work>/store <work>/film`
 4. `motion-render stills <work>/film <work>/stills <各場面の中ほどの秒をカンマ区切り>` で全場面を見る。
    見出しの不自然な改行、はみ出し、重なりがあれば Motion 側（html の映像なら index.html）を直し、手順 4 をやり直す
-5. 効果音があれば、各効果音の秒（場面の開始 + `at`）の静止画も書き出し、鳴らす対象がその時点で画面に出ているかを見る。
-   ずれていれば `at` を直して `motion-render sfx` をやり直す（作り直されるのは変えたものだけ）
+5. 効果音があれば、4 の静止画と同じ `stills` の 1 回で、各効果音の秒（場面の開始 + `at`）も書き出し、
+   鳴らす対象がその時点で画面に出ているかを見る。ずれていれば `at` を直す（`at` だけなら作り直しは要らない）。
+   `prompt` か `duration` を変えたときだけ `motion-render sfx` をやり直す（作り直されるのは変えたものだけ）
 
 ### 5. MP4 にする
 
@@ -164,7 +181,8 @@ motion-render build <work> [<出力.mp4>]
 ### 6. 確認して報告する
 
 - `ffprobe` で、長さと映像・音声の両トラックがあることを見る
-- 報告: 出力のパス、長さ、場面の流れ、BGM の雰囲気、Motion の URL（html の映像なら `<work>/film/index.html` のパス）。耳で聞いていないことは聞いていないと書く
+- 報告: 出力のパス、長さ、場面の流れ、BGM の雰囲気、Motion の URL（html の映像なら `<work>/film/index.html` のパス）、
+  かかった時間（`motion-render times <work>` の最後の行）。耳で聞いていないことは聞いていないと書く
 - 効果音を付けたときは、試聴用の `audio/sfx/preview.m4a` のパスと、その中の順番（`motion-render sfx` の出力）も報告し、
   合わない音があれば教えてほしいと頼む。Claude には音の良し悪しが判定できないため、ここは人が聞いて決める
 
@@ -230,8 +248,11 @@ URL を渡された場合も音を付ける。映像データを取得し（手
 - `scripts/sfx.ts`: ElevenLabs による効果音の生成（`sfx`）、音量の測定とそろえ方、試聴用ファイル
 - `scripts/work.ts`: `script.json` の検証、`timing.json` の計算、ナレーションを動画の場面の開始時刻に置く処理
 - `scripts/render.ts`: プレーヤーを開いてコマを返す。描画中は外部への通信を遮断し、Chromium の sandbox を有効にする
-- `scripts/kit.ts`・`kit/`: html の映像のプレーヤー（`player.js`）と土台の CSS（`base.css`）、作風の CSS（`styles.css`）を、フォントと GSAP と一緒に置く（`kit`）
+- `scripts/kit.ts`・`kit/`: html の映像のプレーヤー（`player.js`）と土台の CSS（`base.css`）、作風の CSS（`styles.css`）、部品の CSS（`parts.css`）を、フォントと GSAP と一緒に置く（`kit`）
+- `scripts/scenes.ts`: `film/scenes/*.html` を index.html の `<!-- scenes -->` に差し込んで、描画するページにする
 - `scripts/layout.ts`・`scripts/snapshot.js`: html の映像の配置の確認（`check`。`stills`・`build` も実行する）
-- `references/html-film.md`: html の映像の書き方と配置の決まり
+- `scripts/steps.ts`: 各コマンドの開始と終了を `<work>/steps.jsonl` に残し、工程ごとの時間の表にする（`times`）
+- `references/html-film.md`: html の映像の書き方と配置の決まり、部品、場面を分けて書くときの決まり
+- `references/pipeline.md`: 工程のつながり（何を待ち、何を裏で動かすか）と、工程を足すときの決まり
 - `scripts/json.ts`: ファイル・API・プレーヤーから来る JSON を、形を確かめながら読む
 - `scripts/store.ts`: Motion の store（ArtifactData の保存先）を映像データのフォルダに展開する（`prepare`）
diff --git a/skills/motion-render/references/html-film.md b/skills/motion-render/references/html-film.md
index bde6901..8f43530 100644
--- a/skills/motion-render/references/html-film.md
+++ b/skills/motion-render/references/html-film.md
@@ -1,8 +1,8 @@
 # html の映像の作り方
 
 Claude Motion が使えないときに、映像を 1 枚の HTML として書く。`motion-render kit <work>` が
-`<work>/film/kit/` にプレーヤー・スタイル・フォント（Noto Sans JP と、手描きの作風用の Klee One）・GSAP・場面の秒数を置くので、
-Claude は `<work>/film/index.html` だけを書く。描画中はネットワークが遮断されるので、CDN や Google Fonts は使えない。
+`<work>/film/kit/` にプレーヤー・スタイル・部品・フォント（Noto Sans JP と、手描きの作風用の Klee One）・GSAP・場面の秒数を置くので、
+Claude は `<work>/film/index.html` と、場面を書いた `<work>/film/scenes/*.html` だけを書く。描画中はネットワークが遮断されるので、CDN や Google Fonts は使えない。
 
 ## ページの骨組み
 
@@ -14,6 +14,7 @@ Claude は `<work>/film/index.html` だけを書く。描画中はネットワ
     <link rel="stylesheet" href="kit/fonts.css" />
     <link rel="stylesheet" href="kit/base.css" />
     <link rel="stylesheet" href="kit/styles.css" />
+    <link rel="stylesheet" href="kit/parts.css" />
     <script src="kit/gsap.min.js"></script>
     <script src="kit/timing.js"></script>
     <script src="kit/player.js"></script>
@@ -39,17 +40,13 @@ Claude は `<work>/film/index.html` だけを書く。描画中はネットワ
     <div id="root">
       <!-- 場面をまたいで残るもの（図の全体） -->
       <div id="stage">…</div>
-      <!-- 場面ごとのもの。id は timing.json の場面 id と同じにする。ページの中で同じ id を 2 度使わない -->
-      <section class="scene" id="title">…</section>
-      <section class="scene" id="problem">…</section>
+      <!-- 場面ごとのもの（film/scenes/*.html）が、名前の順にここへ入る -->
+      <!-- scenes -->
     </div>
     <script>
+      // #stage の物の動き。場面のファイルの動きは、それぞれのファイルの film.build に書く
       film.build(function (tl) {
-        var IN = "expo.out",
-          MOVE = "power2.inOut",
-          OUT = "power3.in";
-        tl.fromTo("#t-title", { opacity: 0, y: 20 }, { opacity: 1, y: 0, duration: 0.7, ease: IN }, film.at("title", 0.2));
-        tl.to("#token", { ...film.spot("#token", "#sts"), duration: 0.8, ease: MOVE }, film.at("sts", 0.6));
+        tl.to("#token", { ...film.spot("#token", "#sts"), duration: 0.8, ease: "power2.inOut" }, film.at("sts", 0.6));
       });
     </script>
   </body>
@@ -67,6 +64,9 @@ Claude は `<work>/film/index.html` だけを書く。描画中はネットワ
 | `film.arc(tl, 要素, 相手, 秒, o)`    | `要素` を `相手` へ山なりに動かす。o: `dur`（既定 0.9）・`lift`（既定 120px）・`dx`・`dy` |
 | `film.breathe(tl, 要素, id, 秒, 量)` | `秒` から場面 `id` の終わりまで、`要素` を `量`（既定 0.01）だけゆっくり拡大縮小する      |
 | `film.typeIn(tl, 要素, 秒, o)`       | `要素` の文字を 1 文字ずつ下から立ち上げる。o: `dur`（既定 0.5）・`stagger`（既定 0.04）  |
+| `film.light(tl, 要素, 秒, o)`        | 部品の `step`・`card` を `秒` に光らせる。o: `off`（消す秒）・`dur`（既定 0.35）          |
+| `film.ticks(要素, o)`                | 部品の `ruler` に目盛りを付ける。o: `step`（間隔）・`label`（既定 `"{v}"`、`""` で無し）  |
+| `film.caption(tl, 要素, id, 秒)`     | 字幕を `秒` に出し、場面 `id` の終わりの 0.25 秒前までに消す                              |
 | `section.scene`                      | その場面の間だけ見える。`#stage` のように section の外に置いたものはずっと見える          |
 
 ## 作る前に決めること
@@ -83,6 +83,25 @@ Claude は `<work>/film/index.html` だけを書く。描画中はネットワ
 - **動きの決まり**: 出る・移る・消えるの緩急と、止めて読ませる長さ。同じ役割の物には同じ動きを使う
 - **この 1 本で使わないもの**: 下の「抑えるもの」から、テーマに合わせて足す
 
+## 絵コンテと秒の計画
+
+場面を書き始める前に `<work>/plan.md` を書く。場面を手分けして書くときの共通の指示書であり、効果音を先に作る元でもある。
+秒は `timing.json` の場面の長さに収める。場面ごとに次の 5 つを書く。
+
+```markdown
+## flow（12.4 秒）
+- 見せるもの: 6 つの工程カードが左から並び、今の工程が光る
+- 部品: steps（6 枚）、caption
+- 動き: 0.3 カードが順に出る（0.08 ずつ）／ 1.6 「原稿」が光る ／ 4.2 「ナレーション」が光る ／ 8.0 字幕
+- 効果音: 0.3 soft UI pop 0.6 ／ 1.6 gentle glassy chime 1.0 ／ 4.2 gentle glassy chime 1.0
+- 残る物: #steps は入るとき無い → 出るとき上端に縮んで残る（次の場面 lanes が使う）
+```
+
+- 動きの秒は、その動きに渡す `film.at(場面, 秒)` の秒にする。書き手はこの秒を変えない
+- 残る物（`#stage` の物）は、場面の頭と終わりの状態（位置・大きさ・見えるか）を書く。
+  まとまりの境目の場面ほど詳しく書く。境目で物が飛ばないようにするため
+- 効果音は `prompt` と `duration` まで書く。そのまま `script.json` の `sfx` に写す
+
 ## 作風
 
 依頼文に見た目の指定（「手描きで」「ホワイトボードで」「設計図っぽく」）があればそれに合う作風にする。
@@ -120,6 +139,24 @@ Claude は `<work>/film/index.html` だけを書く。描画中はネットワ
 - 作風が紙の目や揺れを足すので、ページでは模様や影を足さない
 - `Klee One` の太字は 600 まで。`font-weight: 700` は 600 で描かれる
 
+## 部品
+
+`kit/parts.css` に、解説の映像で毎回描く形がある。場面では中身と秒だけを書き、形を一から書かない。
+色はページの変数（`--panel` `--line` `--ink` `--muted` `--accent`）から取るので、どの作風でも使える。
+手描きの作風では `step`・`card` に `drawn` も付ける（線は作風が描き、部品は光らせるだけにする）。
+
+| 部品         | 書き方                                                                                                                                                                                                                                                                                                   | 動かし方                                                                 |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| 工程の列     | `<div class="steps layer-card" style="left:…; top:…">` の中に `<div class="step"><svg>…</svg><span>原稿</span></div>` を並べる                                                                                                                                                                           | `film.light(tl, "#s-script", 秒, { off: 秒 })`                           |
+| カード       | `<div class="card layer-card" style="position:absolute; left:…; top:…">` に `<span class="card-title">` と `<span class="card-body">`                                                                                                                                                                    | `film.light` で光らせる。出し方は自分で書く                              |
+| 時間のレーン | `<div class="lanes layer-card" style="--from: 0; --to: 20; left:…; top:…; width:…">` に `<span class="lane-name">語り</span><div class="track">…</div>` を組で並べる。`track` の中に `<div class="seg" style="--at: 2; --len: 5.8"><span>場面 1</span></div>` と `<i class="pin" style="--at: 7.5"></i>` | `seg`・`pin` を GSAP で出す（`scaleX` で伸ばす、`scale` で跳ねる）       |
+| 目盛り       | `<div class="ruler layer-line" style="--from: 14; --to: 26; left:…; top:…; width:…">`                                                                                                                                                                                                                    | `film.build` の中で `film.ticks("#ruler", { step: 2, label: "{v} 秒" })` |
+| 字幕         | `<p class="caption layer-caption">…</p>`                                                                                                                                                                                                                                                                 | `film.caption(tl, "#cap-flow", "flow", 秒)`                              |
+
+- `seg` と `pin` の位置は、`lanes` の `--from`〜`--to` を `track` の幅に当てて決まる。秒でも、ほかの単位でもよい
+- 1 本の `track` の中で `seg` と `pin` を重ねない（`check` が重なりとして出す）。印は別の `track` に置く
+- 大きさは変数で変えられる: `--step-w`（工程の幅）、`--steps-gap`、`--lane-h`（レーンの高さ）、`--ruler-pad`
+
 ## 配置の決まり
 
 `motion-render check` はこれを破った所を見つけて止める。最初から守って書く。
@@ -156,6 +193,40 @@ Claude は `<work>/film/index.html` だけを書く。描画中はネットワ
 意図した重なり（グラフの基準線が棒を横切る、軸のラベルが目盛りの外に出る、わざと斜めに押す判子）は、
 その要素に `data-layout-ok` を付けると `check` が数えない。間違いを黙らせるためには使わない。
 
+## 場面を分けて書く
+
+場面は `film/scenes/<番号>-<名前>.html` に、続いた場面のまとまりごとに書く。プレーヤーが開くとき、
+`index.html` の `<!-- scenes -->` の行に、ファイル名の順で差し込まれる。1 つのファイルには、
+その場面の `<style>`、`<section class="scene">`、`<script>film.build(…)</script>` を書く。
+
+```html
+<style>
+  #flow .steps { left: 260px; top: 180px; }
+</style>
+<section class="scene" id="flow">…</section>
+<script>
+  film.build(function (tl) {
+    film.light(tl, "#flow-s1", film.at("flow", 1.6));
+  });
+</script>
+```
+
+- id はページ全体で 1 度だけ。場面の id を頭に付ける（`#flow-s1`）
+- スタイルは `#場面id` で始める。ほかの場面に効かせない
+- `index.html` は書き換えない。`#stage` の物は自分の場面の秒の間だけ動かし、場面の終わりに plan.md の状態にする
+- 自分のファイルだけを `motion-render check <work>/film <ファイル名>` で調べる。ほかのファイルを入れずに、
+  自分の場面の秒だけを調べる。`layout ok` になるまで直す
+
+サブエージェントに頼むときは、1 つのまとまりに 1 つ、次を渡す。
+
+```
+<work>/film/scenes/<番号>-<名前>.html に、場面 <id>, <id>, … を書いてください。
+- 先に読むもの: <skill>/references/html-film.md、<work>/plan.md、<work>/film/index.html、<work>/timing.json
+- plan.md の各場面の「動き」の秒と「残る物」の状態を守る。index.html は変えない
+- 書いたら `motion-render check <work>/film <番号>-<名前>.html` を `layout ok` になるまで直す（単体で実行する）
+- 返すもの: ファイル名、plan.md から変えた秒（無ければ「なし」）、直しきれなかった問題
+```
+
 ## 確認
 
 ```bash
diff --git a/skills/motion-render/references/pipeline.md b/skills/motion-render/references/pipeline.md
new file mode 100644
index 0000000..504bfb1
--- /dev/null
+++ b/skills/motion-render/references/pipeline.md
@@ -0,0 +1,34 @@
+# 工程のつながり
+
+1 本の動画は、Claude が書く工程と、API や描画を待つ工程でできている。待つ工程は、後の工程がその結果を
+使うまで裏で動かし、Claude はその間も書き続ける。かかった時間は `motion-render times <work>` で見る。
+
+## html の映像の工程
+
+| 工程                      | する人                                 | 読むもの                                       | 書くもの                          | 待つ人                   |
+| ------------------------- | -------------------------------------- | ---------------------------------------------- | --------------------------------- | ------------------------ |
+| 原稿                      | Claude                                 | 依頼                                           | `script.json`（場面と語り）       | ナレーション             |
+| ナレーション（`narrate`） | API（4 本ずつ）                        | `script.json`                                  | `audio/<場面>.wav`、`timing.json` | 計画（場面の秒数が要る） |
+| BGM（`bgm`）              | API・裏                                | `script.json` の `bgm`、全体の秒               | `audio/bgm.*`                     | 書き出し                 |
+| 絵コンテと秒の計画        | Claude                                 | `timing.json`                                  | `plan.md`                         | 効果音、場面             |
+| 効果音（`sfx`）           | API（3 本ずつ）・裏                    | `script.json` の `sfx` の `prompt`・`duration` | `audio/sfx/`                      | 書き出し                 |
+| 共通部分                  | Claude                                 | `plan.md`                                      | `film/index.html`                 | 場面                     |
+| 場面                      | サブエージェント（まとまりごとに同時） | `plan.md`、`index.html`                        | `film/scenes/*.html`              | 確認                     |
+| 確認（`check`・`stills`） | Claude                                 | 映像                                           | 直し、`sfx` の `at`               | 書き出し                 |
+| 書き出し（`build`）       | 描画                                   | すべて                                         | MP4                               | —                        |
+
+裏で動かすのは、結果を使う工程が先にあるものだけ。BGM は書き出しまで、効果音は書き出しまで誰も待たない。
+ナレーションは場面の秒数を決めるので、終わるまで計画を書かない。
+
+## 工程を足すとき
+
+キューシートと BGM の合わせ込み（#42）のように工程を足すときは、次を決めてから入れる。
+
+1. **読むものと書くもの**: 上の表に行を足す。読むものが揃う一番早い所に置く。秒は `plan.md` か、
+   書いた映像の `film.at` の秒から取る（計画の秒ではなく、実際に書いた秒を正とする）
+2. **誰が待つか**: 結果を使う工程が後ろにしかなければ、Bash の `run_in_background` で裏に回す。
+   コマンドにするなら `scripts/steps.ts` の `BACKGROUND` に入れ、`times` が Claude の時間として数えるようにする
+3. **Claude が書く量**: 場面ごとに分けられるもの（場面ごとの指示、場面ごとのキュー）は、場面のファイルと
+   同じまとまりで分け、サブエージェントに同時に書かせられる形にする。全体を 1 人で通して書く工程を増やさない
+4. **測る**: 足す前と後で同じ動画を作り、`motion-render times <work>` の表を PR に載せる。
+   API を何度もやり直す工程（BGM を作り直すなど）は、回数も書く
diff --git a/skills/motion-render/scripts/audio.ts b/skills/motion-render/scripts/audio.ts
index a6d37be..cd532b9 100644
--- a/skills/motion-render/scripts/audio.ts
+++ b/skills/motion-render/scripts/audio.ts
@@ -150,7 +150,7 @@ export async function withRetries<T>(label: string, attempt: () => Promise<T>):
   let last: unknown;
   let waited = 0,
     waits = 0;
-  for (let i = 1; i <= RETRIES; ) {
+  for (let i = 1; i <= RETRIES;) {
     try {
       return await attempt();
     } catch (e) {
diff --git a/skills/motion-render/scripts/scenes.ts b/skills/motion-render/scripts/scenes.ts
index a0cb6cc..1a548f1 100644
--- a/skills/motion-render/scripts/scenes.ts
+++ b/skills/motion-render/scripts/scenes.ts
@@ -4,11 +4,11 @@
 import { existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
-export const MARKER = "<!-- scenes -->";
+const MARKER = "<!-- scenes -->";
 const DIR = "scenes";
 
 // The scene files of a film dir, in name order (01-title.html, 02-flow.html, ...).
-export function sceneFiles(dir: string): string[] {
+function sceneFiles(dir: string): string[] {
   const d = join(dir, DIR);
   return existsSync(d)
     ? readdirSync(d)
diff --git a/tests/sfx.test.ts b/tests/sfx.test.ts
index e46b56c..f72843a 100644
--- a/tests/sfx.test.ts
+++ b/tests/sfx.test.ts
@@ -27,9 +27,8 @@ vi.mock("node:child_process", async (importOriginal) => {
   };
 });
 
-const { checkSfx, makeSfx, narrationLevel, previewSfx, sfxKey, sfxTrack } = await import(
-  "../skills/motion-render/scripts/sfx.ts"
-);
+const { checkSfx, makeSfx, narrationLevel, previewSfx, sfxKey, sfxTrack } =
+  await import("../skills/motion-render/scripts/sfx.ts");
 const { volumeStats } = await import("../skills/motion-render/scripts/audio.ts");
 const { loadScript } = await import("../skills/motion-render/scripts/work.ts");
 

From c4f38670dd81bcd7d9b84104ba39e070fc0410a0 Mon Sep 17 00:00:00 2001
From: umiyosh <yumino99@gmail.com>
Date: Fri, 6 Nov 2026 02:00:43 +0900
Subject: [PATCH 4/6] fix(kit): keep ruler ticks and lit card text measurable,
 and write scenes two at a time

---
 skills/motion-render/SKILL.md                |  4 ++--
 skills/motion-render/kit/parts.css           |  8 ++++++--
 skills/motion-render/references/html-film.md | 11 ++++++++++-
 tests/parts.test.ts                          | 12 +++++++++++-
 4 files changed, 29 insertions(+), 6 deletions(-)

diff --git a/skills/motion-render/SKILL.md b/skills/motion-render/SKILL.md
index a3dc417..67a5949 100644
--- a/skills/motion-render/SKILL.md
+++ b/skills/motion-render/SKILL.md
@@ -145,11 +145,11 @@ motion-render narrate <work>
    効果音は `prompt` と `duration` だけで作られるので、あとで `at` を直しても作り直しにはならない
 4. `<work>/film/index.html` に、全場面で共通の部分を書く: 「作る前に決めること」、配色、共通のスタイル、
    場面をまたいで残る物（`#stage`）とその動き、場面を差し込む `<!-- scenes -->` の行
-5. 場面を書く。場面が 7 つ以上で Agent ツールがあれば、続いた場面を 3〜4 のまとまりに分け、
+5. 場面を書く。場面が 5 つ以上で Agent ツールがあれば、続いた場面を 2 つずつ（最大 7）のまとまりに分け、
    まとまりごとにサブエージェントを 1 つ、1 つのメッセージでまとめて起動する（頼み方は html-film.md の
    「場面を分けて書く」）。各サブエージェントは `film/scenes/<番号>-<名前>.html` を書き、
    `motion-render check <work>/film <そのファイル名>` を `layout ok` まで直して返す。
-   場面が 6 つ以下か Agent ツールが無いときは、Claude が同じ形で場面のファイルを書く
+   場面が 4 つ以下か Agent ツールが無いときは、Claude が同じ形で場面のファイルを書く
 6. 全員が返ったら `motion-render check <work>/film` で全体を調べ、まとまりの境目の問題を直す。
    書いた動きの秒が plan.md と違えば、`script.json` の `sfx` の `at` をその秒に直す。
    効果音を付けるときは、タイトルの場面に `🎧:11.ai` を小さく入れる
diff --git a/skills/motion-render/kit/parts.css b/skills/motion-render/kit/parts.css
index 8a94932..7f71e46 100644
--- a/skills/motion-render/kit/parts.css
+++ b/skills/motion-render/kit/parts.css
@@ -50,10 +50,11 @@
   font-size: 34px;
   font-weight: 700;
 }
+/* The body darkens to --ink as the card lights, so it keeps its contrast on the lit fill. */
 .card-body {
   font-size: 28px;
   line-height: 1.5;
-  color: var(--muted);
+  color: color-mix(in srgb, var(--ink) calc(var(--on) * 100%), var(--muted));
 }
 
 /* Lanes on one time axis: names on the left, tracks on the right. --from and --to (seconds or any
@@ -126,11 +127,14 @@
 .tick {
   position: absolute;
   top: 0;
+  /* Centered on its value by a negative margin, not a transform: film.spot measures layout boxes,
+     so a transform would put a chip sent to a tick half a tick off. */
+  width: var(--tick-w, 120px);
+  margin-left: calc(var(--tick-w, 120px) / -2);
   left: calc(
     var(--ruler-pad) + (var(--at) - var(--from)) / (var(--to) - var(--from)) *
       (100% - 2 * var(--ruler-pad))
   );
-  transform: translateX(-50%);
   display: flex;
   flex-direction: column;
   align-items: center;
diff --git a/skills/motion-render/references/html-film.md b/skills/motion-render/references/html-film.md
index 8f43530..b8bce4b 100644
--- a/skills/motion-render/references/html-film.md
+++ b/skills/motion-render/references/html-film.md
@@ -98,6 +98,8 @@ Claude は `<work>/film/index.html` と、場面を書いた `<work>/film/scenes
 ```
 
 - 動きの秒は、その動きに渡す `film.at(場面, 秒)` の秒にする。書き手はこの秒を変えない
+- 場所は id で指す（「`#st-mix` の真下」）。座標を書くのは、画面の割り当て（どの帯に置くか）だけにする。
+  中身の大きさで位置が変わる物（並んだカードの 2 枚目以降）を座標で書くと、書き手の計算とずれる
 - 残る物（`#stage` の物）は、場面の頭と終わりの状態（位置・大きさ・見えるか）を書く。
   まとまりの境目の場面ほど詳しく書く。境目で物が飛ばないようにするため
 - 効果音は `prompt` と `duration` まで書く。そのまま `script.json` の `sfx` に写す
@@ -155,7 +157,7 @@ Claude は `<work>/film/index.html` と、場面を書いた `<work>/film/scenes
 
 - `seg` と `pin` の位置は、`lanes` の `--from`〜`--to` を `track` の幅に当てて決まる。秒でも、ほかの単位でもよい
 - 1 本の `track` の中で `seg` と `pin` を重ねない（`check` が重なりとして出す）。印は別の `track` に置く
-- 大きさは変数で変えられる: `--step-w`（工程の幅）、`--steps-gap`、`--lane-h`（レーンの高さ）、`--ruler-pad`
+- 大きさは変数で変えられる: `--step-w`（工程の幅）、`--steps-gap`、`--lane-h`（レーンの高さ）、`--ruler-pad`、`--tick-w`（目盛りの文字の幅）
 
 ## 配置の決まり
 
@@ -216,6 +218,12 @@ Claude は `<work>/film/index.html` と、場面を書いた `<work>/film/scenes
 - `index.html` は書き換えない。`#stage` の物は自分の場面の秒の間だけ動かし、場面の終わりに plan.md の状態にする
 - 自分のファイルだけを `motion-render check <work>/film <ファイル名>` で調べる。ほかのファイルを入れずに、
   自分の場面の秒だけを調べる。`layout ok` になるまで直す
+- 静止画は 1 回だけ、自分の場面の中ほどの秒で見る。全体の見た目は、全員が返ったあとに Claude がまとめて見る
+
+まとまりは続いた 2 場面ずつにする（最大 7）。書き手の時間は、手引きを読む決まった時間と、場面の数に比例する時間の和なので、
+1 人あたりの場面を減らすほど全員がそろって早く返る。ベンチマーク（14 場面）では、3〜4 場面ずつの 4 人だと最も遅い 1 人が
+8 分 40 秒かかり、2 場面ずつの 7 人だと 5 分 15 秒だった（ほかの 6 人は 2 分 24 秒〜3 分 45 秒）。
+書き手 1 人あたり 12〜15 万トークンを使うので、7 人で 1 本あたり約 90 万トークンになる。
 
 サブエージェントに頼むときは、1 つのまとまりに 1 つ、次を渡す。
 
@@ -224,6 +232,7 @@ Claude は `<work>/film/index.html` と、場面を書いた `<work>/film/scenes
 - 先に読むもの: <skill>/references/html-film.md、<work>/plan.md、<work>/film/index.html、<work>/timing.json
 - plan.md の各場面の「動き」の秒と「残る物」の状態を守る。index.html は変えない
 - 書いたら `motion-render check <work>/film <番号>-<名前>.html` を `layout ok` になるまで直す（単体で実行する）
+- 静止画は 1 回だけ見る。plan.md に無い細部は自分で決め、問い返さない
 - 返すもの: ファイル名、plan.md から変えた秒（無ければ「なし」）、直しきれなかった問題
 ```
 
diff --git a/tests/parts.test.ts b/tests/parts.test.ts
index 1a85e37..1394290 100644
--- a/tests/parts.test.ts
+++ b/tests/parts.test.ts
@@ -48,13 +48,16 @@ const PARTS_PAGE = `<!doctype html>
       <div class="track"><i class="pin" id="pin" style="--at: 7"></i></div>
     </div>
     <div id="ruler" class="ruler layer-line"></div>
+    <div id="mark" class="layer-chip" style="position: absolute; left: 300px; top: 820px; font-size: 24px; padding: 4px 10px">印</div>
   </section>
 </div>
 <script>
   film.build(function (tl) {
     film.light(tl, "#s2", film.at("steps", 0.5), { off: film.at("steps", 1.2) });
+    film.light(tl, "#note", film.at("steps", 0.5));
     film.caption(tl, "#cap1", "steps", film.at("steps", 0.3));
     film.ticks("#ruler", { step: 2, label: "{v} 秒" });
+    tl.to("#mark", { ...film.spot("#mark", "#ruler .tick:nth-child(3)", 0, -90), duration: 0.3 }, film.at("lanes", 0.2));
   });
 </script>
 </body></html>`;
@@ -68,7 +71,7 @@ function partsFilm(html = PARTS_PAGE): string {
 }
 
 describe("kit parts", () => {
-  it("lay out without layout issues, and place segments, pins and ticks on their axis", async () => {
+  it("lay out without layout issues, a lit card's body included, and place segments, pins and ticks on their axis", async () => {
     const film = await openFilm(partsFilm());
     try {
       expect((await checkLayout(film))?.map(formatIssue)).toEqual([]);
@@ -86,6 +89,13 @@ describe("kit parts", () => {
       const labels = boxes.filter((b) => b.label.startsWith("i.tick")).map((b) => b.label);
       expect(labels).toHaveLength(6);
       expect(labels[5]).toContain("10 秒");
+      // The 4 s tick sits at 4 tenths of the line, which runs 60px in from each end, and a chip
+      // sent there with film.spot lands right above it.
+      const tick = boxes.find((b) => b.label.startsWith('i.tick "4 秒"'));
+      const mark = box("#mark");
+      if (!tick || !mark) throw new Error("tick or mark not found");
+      expect(tick.x + tick.w / 2).toBeCloseTo(400 + 60 + 0.4 * 880, 0);
+      expect(mark.x + mark.w / 2).toBeCloseTo(tick.x + tick.w / 2, 0);
       expect(await film.warnings()).toEqual([]);
     } finally {
       await film.close();

From 6f4f02c7627bb4dcd6129e929e9ff8fe7a43fd80 Mon Sep 17 00:00:00 2001
From: umiyosh <yumino99@gmail.com>
Date: Fri, 6 Nov 2026 02:13:04 +0900
Subject: [PATCH 5/6] ci: pin the runner to ubuntu-24.04 for the Chromium
 install

---
 .github/workflows/ci.yml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index edaeb04..c32e510 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -13,7 +13,8 @@ permissions:
 
 jobs:
   node-suite:
-    runs-on: ubuntu-latest
+    # ubuntu-latest moved to 26.04, which playwright-core 1.56.1 has no Chromium for (#46).
+    runs-on: ubuntu-24.04
     timeout-minutes: 15
     steps:
       - name: Checkout

From abd6a2014ac361cc7d6f2034f0805e607d19fd99 Mon Sep 17 00:00:00 2001
From: umiyosh <yumino99@gmail.com>
Date: Fri, 6 Nov 2026 02:46:46 +0900
Subject: [PATCH 6/6] fix(cli): show page errors in check and round step times
 to whole seconds

---
 skills/motion-render/references/html-film.md |  4 +++-
 skills/motion-render/scripts/cli.ts          |  3 +++
 skills/motion-render/scripts/steps.ts        |  8 ++++++--
 tests/scenes.test.ts                         | 13 ++++++++++++-
 tests/steps.test.ts                          |  9 +++++++++
 5 files changed, 33 insertions(+), 4 deletions(-)

diff --git a/skills/motion-render/references/html-film.md b/skills/motion-render/references/html-film.md
index b8bce4b..cdaaa63 100644
--- a/skills/motion-render/references/html-film.md
+++ b/skills/motion-render/references/html-film.md
@@ -217,7 +217,7 @@ Claude は `<work>/film/index.html` と、場面を書いた `<work>/film/scenes
 - スタイルは `#場面id` で始める。ほかの場面に効かせない
 - `index.html` は書き換えない。`#stage` の物は自分の場面の秒の間だけ動かし、場面の終わりに plan.md の状態にする
 - 自分のファイルだけを `motion-render check <work>/film <ファイル名>` で調べる。ほかのファイルを入れずに、
-  自分の場面の秒だけを調べる。`layout ok` になるまで直す
+  自分の場面の秒だけを調べる。`layout ok` になり、`runner` の行が出なくなるまで直す
 - 静止画は 1 回だけ、自分の場面の中ほどの秒で見る。全体の見た目は、全員が返ったあとに Claude がまとめて見る
 
 まとまりは続いた 2 場面ずつにする（最大 7）。書き手の時間は、手引きを読む決まった時間と、場面の数に比例する時間の和なので、
@@ -255,6 +255,8 @@ motion-render check <work>/film
 | `A has contrast 2.1:1, needs 4.5:1` | 文字が背景に対して薄い。40px 未満は 4.5:1、40px 以上は 3:1 を超えるよう、文字か背景の色を変える。明るい色の丸やチップに乗せる数字は、地の色（暗い色）で書く |
 
 `layout: ok` になるまで直してから `stills` で見る。`build` は問題が残っていると止まる。
+`runner` で始まる行は、ページのスクリプトの誤り（`NaN` から組んだ図形、見つからないセレクタ）。描かれない物があっても
+配置の決まりは破らないので、`layout: ok` と一緒に出る。出たら直す。
 
 ## 動き
 
diff --git a/skills/motion-render/scripts/cli.ts b/skills/motion-render/scripts/cli.ts
index cec54bf..41d4be4 100755
--- a/skills/motion-render/scripts/cli.ts
+++ b/skills/motion-render/scripts/cli.ts
@@ -95,6 +95,9 @@ async function check(filmDir: string, scenes: string[]): Promise<void> {
   let n: number;
   try {
     n = await reportLayout(film);
+    // Errors from the page's own code (a path built from NaN, a failed selector) draw nothing and
+    // break no layout rule, so the layout check alone would pass them.
+    for (const w of await film.warnings()) console.error("runner", w);
   } finally {
     await film.close();
   }
diff --git a/skills/motion-render/scripts/steps.ts b/skills/motion-render/scripts/steps.ts
index 54b4bf8..24f7f31 100644
--- a/skills/motion-render/scripts/steps.ts
+++ b/skills/motion-render/scripts/steps.ts
@@ -109,8 +109,12 @@ export function stepRows(steps: Step[], runStart: number): Row[] {
 
 const clock = (sec: number): string =>
   `${Math.floor(sec / 60)}:${String(Math.floor(sec % 60)).padStart(2, "0")}`;
-const span = (sec: number): string =>
-  sec < 60 ? `${sec.toFixed(1)} s` : `${Math.floor(sec / 60)} min ${Math.round(sec % 60)} s`;
+// Rounded to the whole second first, so 179.6 s reads "3 min 0 s", not "2 min 60 s".
+export function span(sec: number): string {
+  if (sec < 60) return `${sec.toFixed(1)} s`;
+  const s = Math.round(sec);
+  return `${Math.floor(s / 60)} min ${s % 60} s`;
+}
 
 // A Markdown table of the run, with the totals of Claude's time and of the commands it waited for.
 export function stepsTable(work: string): string {
diff --git a/tests/scenes.test.ts b/tests/scenes.test.ts
index a2f54d5..512dfbe 100644
--- a/tests/scenes.test.ts
+++ b/tests/scenes.test.ts
@@ -2,7 +2,7 @@
 import { describe, expect, it } from "vitest";
 import { mkdirSync, readdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
 import { openFilm } from "../skills/motion-render/scripts/render.ts";
 import { checkLayout, formatIssue } from "../skills/motion-render/scripts/layout.ts";
 import { filmPage, sceneIds } from "../skills/motion-render/scripts/scenes.ts";
@@ -108,6 +108,17 @@ describe("a film in scene files", () => {
     expect(readdirSync(film).filter((n) => n.startsWith(".page-"))).toEqual([]);
   });
 
+  it("passes on errors from the page's own code with the check command", () => {
+    const broken = `<section class="scene" id="intro"><svg width="100" height="100"><path id="p" /></svg></section>
+<script>film.build(function () { document.querySelector("#p").setAttribute("d", "M0 " + NaN); });</script>`;
+    const film = sceneFilm({ "01-intro.html": broken });
+    const r = spawnSync(process.execPath, [CLI, "check", film, "01-intro.html"], {
+      encoding: "utf8",
+    });
+    expect(r.stdout).toContain("layout ok");
+    expect(r.stderr).toMatch(/runner error: .*attribute d/);
+  });
+
   it("is checked by scene file with the check command", () => {
     const film = sceneFilm({ "01-intro.html": INTRO, "02-deny.html": DENY });
     const run = (...args: string[]) =>
diff --git a/tests/steps.test.ts b/tests/steps.test.ts
index a2d26c5..4521ae9 100644
--- a/tests/steps.test.ts
+++ b/tests/steps.test.ts
@@ -5,6 +5,7 @@ import { join } from "node:path";
 import { execFileSync } from "node:child_process";
 import {
   readSteps,
+  span,
   stepRows,
   stepsTable,
   timed,
@@ -101,3 +102,11 @@ describe("the times command", () => {
     expect(stepsTable(tempDir())).toMatch(/^no steps logged/);
   });
 });
+
+describe("span", () => {
+  it("rounds to the whole second before splitting into minutes", () => {
+    expect(span(42.25)).toBe("42.3 s");
+    expect(span(179.6)).toBe("3 min 0 s");
+    expect(span(331.4)).toBe("5 min 31 s");
+  });
+});