@tandryukha/aidemo 0.18.0 → 0.20.0

package/README.md

@@ -154,7 +154,7 @@ A bundled fixture store (search → results → cart → checkout) that renders
 finished demo with zero external dependencies:
 
 ```bash
-npm install                                # Node 22+, system Chrome, ffmpeg on PATH
+npm install                                # Node 22.12+, system Chrome, ffmpeg on PATH
 node examples/local-demo/serve.mjs         # terminal 1: fixture on :8787
 node bin/aidemo.mjs render examples/local-demo --headless   # terminal 2
 open examples/local-demo/output/final-demo.mp4   # xdg-open on Linux, start on Windows
@@ -254,7 +254,7 @@ Codex).
 
 ## Setup
 
-Prereqs: **Node 22+**, **Google Chrome**, **ffmpeg + ffprobe** on `PATH`. The
+Prereqs: **Node 22.12+**, **Google Chrome**, **ffmpeg + ffprobe** on `PATH`. The
 first take also fetches Playwright's ~2 MB ffmpeg helper, which encodes the
 recording (once per Playwright version; `AIDEMO_NO_AUTO_INSTALL=1` opts out).
 Developed and tested on macOS; Linux works for the default (Playwright) capture
@@ -304,9 +304,9 @@ demos/<name>/          ← your working area (untracked; scaffold with `aidemo i
   ffmpeg helper that encodes the take; off with `AIDEMO_NO_AUTO_INSTALL=1`), and
   `github.com` (your own `gh`, for `aidemo feedback`). Recording/composing are
   otherwise fully local. The MCP server is **stdio-only** — no listener.
-- **Small, auditable surface:** ~20 source files, 7 runtime deps, MIT. Pin an
-  immutable ref if you're wary of the moving `#stable` tag:
-  `npx -y github:tandryukha/aidemo#v0.14.0` (any released tag).
+- **Small, auditable surface:** ~50 source files, 7 runtime deps (11 packages
+  installed in all), MIT. Pin an immutable ref if you're wary of the moving
+  `#stable` tag: `npx -y github:tandryukha/aidemo#v0.20.0` (any released tag).
 - Full detail: [docs/LOCAL_MODELS.md](docs/LOCAL_MODELS.md#what-leaves-the-machine)
   · report vulnerabilities privately per [SECURITY.md](SECURITY.md).
 

package/bin/aidemo.mjs

@@ -7,15 +7,16 @@ import { existsSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 
 // Fail fast on an unsupported Node with the fix, instead of an arbitrary crash
-// deep inside a dependency (openai 7 needs Node 22). Node 20 reached
-// end-of-life on 2026-04-30. Keep in sync with package.json "engines".
-const MIN_NODE_MAJOR = 22;
-const nodeMajor = Number(process.versions.node.split(".")[0]);
-if (nodeMajor < MIN_NODE_MAJOR) {
+// deep inside a dependency (openai 7 needs Node 22, commander 15 22.12). Node
+// 20 reached end-of-life on 2026-04-30. Keep in sync with package.json
+// "engines" and the doctor check (src/distribute.ts).
+const MIN_NODE = [22, 12];
+const [nodeMajor, nodeMinor] = process.versions.node.split(".").map(Number);
+if (nodeMajor < MIN_NODE[0] || (nodeMajor === MIN_NODE[0] && nodeMinor < MIN_NODE[1])) {
   console.error(
-    `aidemo: Node.js ${MIN_NODE_MAJOR}+ is required (found ${process.version}). ` +
-      `Install Node ${MIN_NODE_MAJOR} LTS or newer (nvm install ${MIN_NODE_MAJOR}; in CI, ` +
-      `actions/setup-node with node-version: ${MIN_NODE_MAJOR}) and re-run.`
+    `aidemo: Node.js ${MIN_NODE.join(".")}+ is required (found ${process.version}). ` +
+      `Install Node ${MIN_NODE[0]} LTS or newer (nvm install ${MIN_NODE[0]}; in CI, ` +
+      `actions/setup-node with node-version: ${MIN_NODE[0]}) and re-run.`
   );
   process.exit(1);
 }

package/docs/AUTHORING.md

@@ -625,8 +625,8 @@ artifacts in `output/walkthrough/`: `index.html` (one card per scene with
 its payoff frame, title, narration and a jump-to-time button over the video;
 ← / → keys step through, Enter plays from a step), `guide.md` (the same as a
 README/SOP section: heading + frame + narration per scene), `scene-NN-<id>.png`
-frames, the SRT/VTT captions (timed to the video, like the sidecars), and
-`walkthrough.json`. Frames come from the
+frames, the SRT/VTT captions (timed to the video, like the sidecars; the
+page's player offers them as a captions track), and `walkthrough.json`. Frames come from the
 **final** video, so they carry zoom, cursor, overlays and the frame. Scene
 `title`s name the steps (falling back to ids).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tandryukha/aidemo",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "license": "MIT",
   "description": "AI Demo Engine — turn a storyboard into a narrated, captioned product demo video",
   "type": "module",
@@ -8,7 +8,7 @@
     "aidemo": "bin/aidemo.mjs"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=22.12"
   },
   "publishConfig": {
     "access": "public"
@@ -31,6 +31,7 @@
     "build": "tsc --noEmit",
     "serve-example": "node examples/local-demo/serve.mjs",
     "mcp-smoke": "node test/mcp-smoke.mjs",
+    "test": "tsx --test test/issue-64.mjs test/issue-89.mjs test/runtime-setup.mjs test/mcp-schemas.mjs test/mcp-stdio.mjs",
     "test:blank-open": "tsx --test test/blank-open.mjs",
     "mcp-env-test": "node test/mcp-env.mjs",
     "guard-openai-key": "tsx scripts/guard-openai-key.ts",
@@ -38,16 +39,17 @@
     "check:plugin-skill": "diff -q .claude/skills/record-demo/SKILL.md plugins/record-demo/skills/record-demo/SKILL.md"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.32.2",
-    "commander": "^12.1.0",
+    "@modelcontextprotocol/server": "2.4.0",
+    "commander": "^15.0.0",
     "openai": "^7.47.0",
-    "playwright": "^1.55.1",
+    "playwright": "^1.64.1",
     "re2js": "2.9.1",
-    "tsx": "^4.23.1",
+    "tsx": "^4.23.15",
     "zod": "^4.6.7"
   },
   "devDependencies": {
-    "@types/node": "^22.20.1",
-    "typescript": "^5.6.0"
+    "@modelcontextprotocol/client": "2.4.0",
+    "@types/node": "^26.6.6",
+    "typescript": "^7.0.2"
   }
 }

package/src/caption-track.ts

@@ -75,6 +75,21 @@ export function mp4Language(tag: string | undefined): string {
   return ISO639_2T[primary] ?? "und";
 }
 
+/**
+ * `srclang` + human label for an HTML `<track>` of captions in `tag` (a BCP-47
+ * code: "en", "en-GB", "de"), e.g. { srclang: "en-GB", label: "British English" }.
+ */
+export function htmlTrackLanguage(tag: string | undefined): { srclang: string; label: string } {
+  const srclang = tag?.trim() || "en";
+  let label = srclang;
+  try {
+    label = new Intl.DisplayNames(["en"], { type: "language" }).of(srclang) ?? srclang;
+  } catch {
+    // not a valid BCP-47 tag — keep the raw code as the label
+  }
+  return { srclang, label };
+}
+
 /** Track handler types that carry subtitles/captions in ISO-BMFF / QuickTime. */
 const SUBTITLE_HANDLERS = new Set(["sbtl", "text", "subt"]);
 

package/src/capture.ts

@@ -348,7 +348,7 @@ interface ObsPending {
 }
 
 /**
- * Minimal obs-websocket v5 client on Node's global WebSocket (Node 22+).
+ * Minimal obs-websocket v5 client on Node's global WebSocket.
  * Assumes the current OBS scene captures the FULL primary display (Display
  * Capture) — the recorder crops to the viewport afterwards, same as native.
  */
@@ -366,11 +366,6 @@ export class ObsCapture implements CaptureProvider {
   }
 
   async start(): Promise<void> {
-    if (typeof WebSocket === "undefined") {
-      throw new Error(
-        "OBS capture needs Node 22+ (built-in WebSocket). Use --capture native instead."
-      );
-    }
     await this.connect();
     await this.request("StartRecord", {});
     await sleep(500); // let OBS write its first frames

package/src/distribute.ts

@@ -685,10 +685,12 @@ export interface DoctorReport {
   ok: boolean;
 }
 
-/** Oldest supported Node major (bin/aidemo.mjs fails fast below it; package.json "engines"). */
-const MIN_NODE_MAJOR = 22;
-const nodeSupported = (version: string): boolean =>
-  Number(version.replace(/^v/, "").split(".")[0]) >= MIN_NODE_MAJOR;
+/** Oldest supported Node (bin/aidemo.mjs fails fast below it; package.json "engines"). */
+const MIN_NODE: [number, number] = [22, 12];
+export const nodeSupported = (version: string): boolean => {
+  const [major, minor] = version.replace(/^v/, "").split(".").map(Number);
+  return major > MIN_NODE[0] || (major === MIN_NODE[0] && minor >= MIN_NODE[1]);
+};
 
 /** Build the structured preflight report (used by CLI doctor + MCP doctor). */
 export async function doctorReport(dir: string | undefined): Promise<DoctorReport> {
@@ -794,7 +796,7 @@ export async function doctor(dir: string | undefined): Promise<void> {
     val ? ok(`${label}: ${val}`) : fail(`${label}: NOT FOUND`);
 
   if (nodeSupported(r.node)) ok(`node: ${r.node}`);
-  else fail(`node: ${r.node} — aidemo needs Node ${MIN_NODE_MAJOR}+ (Node 20 is end-of-life)`);
+  else fail(`node: ${r.node} — aidemo needs Node ${MIN_NODE.join(".")}+ (Node 20 is end-of-life)`);
   line("ffmpeg", r.ffmpeg);
   if (r.browser.source === "default") {
     line("chrome", r.chrome);

package/src/embed.ts

@@ -12,10 +12,12 @@
  * hits the network beyond the local `git` invocation, and never renders.
  */
 import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
 import { promisify } from "node:util";
 import { resolve, isAbsolute, basename } from "node:path";
 import { exists } from "./util.js";
 import { UPSTREAM_REPO } from "./distribute.js";
+import { htmlTrackLanguage } from "./caption-track.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -49,6 +51,8 @@ export interface EmbedResult {
     still: string;
     /** GitHub Pages MP4 (correct video/mp4 MIME for <video>) — needs Pages on the branch. */
     pagesMp4: string;
+    /** GitHub Pages WebVTT captions, timed to the video — the <video> embed's <track>. */
+    pagesVtt: string;
     /** GitHub Pages project-site base. */
     pagesBase: string;
   };
@@ -140,12 +144,25 @@ export async function buildEmbed(
   // GitHub Pages project-site host is the lowercased owner login.
   const pagesBase = `https://${owner.toLowerCase()}.github.io/${repo}`;
   const pagesMp4 = `${pagesBase}/media/${demo}/latest.mp4`;
+  const pagesVtt = `${pagesBase}/media/${demo}/latest.vtt`;
+  // Track language = the storyboard's narration language (best-effort read).
+  let language: string | undefined;
+  try {
+    const sb = JSON.parse(await readFile(resolve(demoDir, "generated", "storyboard.json"), "utf8"));
+    if (typeof sb?.language === "string") language = sb.language;
+  } catch {
+    // no storyboard here (or unreadable) — English
+  }
+  const { srclang, label } = htmlTrackLanguage(language);
 
   const markdownGif = `![${demo} demo](${gif})`;
   const markdownStill = `![${demo}](${stillUrl})`;
+  // crossorigin: the page embedding this is on another origin than Pages, and
+  // a cross-origin <track> only loads in CORS mode (Pages sends ACAO: *).
   const htmlVideo =
-    `<video controls muted loop playsinline width="960" poster="${stillUrl}">\n` +
+    `<video controls muted loop playsinline width="960" crossorigin="anonymous" poster="${stillUrl}">\n` +
     `  <source src="${pagesMp4}" type="video/mp4" />\n` +
+    `  <track kind="captions" src="${pagesVtt}" srclang="${srclang}" label="${label}" />\n` +
     `  <a href="${gif}">▶ Watch the ${demo} demo</a>\n` +
     `</video>`;
 
@@ -158,7 +175,7 @@ export async function buildEmbed(
     demo,
     branch: DEMO_MEDIA_BRANCH,
     still,
-    urls: { gif, mp4, still: stillUrl, pagesMp4, pagesBase },
+    urls: { gif, mp4, still: stillUrl, pagesMp4, pagesVtt, pagesBase },
     snippets: { markdownGif, markdownStill, htmlVideo },
     workflow: {
       path: PUBLISH_WORKFLOW_REL,

package/src/mcp/jobs.ts

@@ -87,9 +87,6 @@ export class JobManager {
   private jobs = new Map<string, Job>();
   private activeId: string | null = null;
 
-  /** Best-effort per-line forwarding (e.g. MCP logging notifications). */
-  onLine?: (job: Job, cleanChunk: string) => void;
-
   /** Start a job or throw JobBusyError if one is already running. */
   startJob(
     kind: JobKind,
@@ -284,6 +281,5 @@ export class JobManager {
     if (job.ring.length > RING_MAX) {
       job.ring.splice(0, job.ring.length - RING_MAX);
     }
-    this.onLine?.(job, chunk);
   }
 }

package/src/mcp/server.ts

@@ -1,5 +1,5 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { McpServer } from "@modelcontextprotocol/server";
+import { serveStdio, StdioServerTransport } from "@modelcontextprotocol/server/stdio";
 import { z } from "zod";
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
@@ -81,6 +81,44 @@ function storyboardJsonSchema(): Record<string, unknown> {
   }) as Record<string, unknown>;
 }
 
+/**
+ * Tool input schemas advertise `additionalProperties: false` on every object,
+ * as they did before the zod 4 migration: the MCP SDK converts zod schemas
+ * through zod's Standard JSON Schema with io:"input", which leaves objects
+ * open. Metadata only — zod still strips unknown arguments at runtime,
+ * exactly as before. (A tool without arguments registers no input schema;
+ * the SDK lists it as an empty object.)
+ */
+function closedInput<Shape extends z.ZodRawShape>(shape: Shape) {
+  for (const field of Object.values(shape)) closeObjects(field);
+  return z.object(shape).meta({ additionalProperties: false });
+}
+
+/** Mark every object schema reachable from `schema` closed (keeps existing metadata). */
+function closeObjects(schema: z.core.$ZodType, seen = new Set<unknown>()): void {
+  if (seen.has(schema)) return;
+  seen.add(schema);
+  const def = schema._zod.def as {
+    type: string;
+    shape?: Record<string, z.core.$ZodType>;
+    innerType?: z.core.$ZodType;
+    element?: z.core.$ZodType;
+    options?: z.core.$ZodType[];
+    valueType?: z.core.$ZodType;
+  };
+  if (def.type === "object") {
+    z.globalRegistry.add(schema, { ...z.globalRegistry.get(schema), additionalProperties: false });
+  }
+  const children = [
+    ...Object.values(def.shape ?? {}),
+    ...(def.options ?? []),
+    def.innerType,
+    def.element,
+    def.valueType,
+  ];
+  for (const child of children) if (child) closeObjects(child, seen);
+}
+
 type ToolResult = {
   content: Array<{ type: "text"; text: string }>;
   structuredContent?: Record<string, unknown>;
@@ -243,29 +281,20 @@ function throwIfAborted(signal: AbortSignal): void {
   if (signal.aborted) throw new CanceledError("canceled between stages");
 }
 
-export function buildMcpServer(): { server: McpServer; jobs: JobManager } {
-  const jobs = new JobManager();
+/**
+ * One MCP server instance over the process-wide job manager. Under stdio the
+ * SDK may build more than one instance per process (a discarded
+ * `server/discover` probe, then the connection's instance), so job state lives
+ * in the shared `jobs`, never in an instance. Progress reaches clients through
+ * job_status polling; engine logging goes to stderr and the job's log file
+ * (MCP logging notifications are deprecated as of protocol 2026-07-28).
+ */
+export function buildMcpServer(jobs: JobManager = new JobManager()): { server: McpServer; jobs: JobManager } {
   const server = new McpServer(
     { name: "aidemo", version: engineVersion() },
-    { instructions: INSTRUCTIONS, capabilities: { logging: {} } }
+    { instructions: INSTRUCTIONS }
   );
 
-  // Best-effort log forwarding (throttled); job_status polling is the source
-  // of truth — many clients don't surface logging notifications.
-  const lastSent = new Map<string, number>();
-  jobs.onLine = (job, chunk) => {
-    const now = Date.now();
-    if (now - (lastSent.get(job.jobId) ?? 0) < 1000) return;
-    lastSent.set(job.jobId, now);
-    void server
-      .sendLoggingMessage({
-        level: "info",
-        logger: "aidemo",
-        data: { jobId: job.jobId, stage: job.stage, line: chunk.trim() },
-      })
-      .catch(() => {});
-  };
-
   const guidePath = guideFilePath();
 
   server.registerTool(
@@ -279,21 +308,21 @@ export function buildMcpServer(): { server: McpServer; jobs: JobManager } {
         `\`topic\` (${GUIDE_TOPIC_NAMES.join(" | ")}, or any H2 heading prefix) ` +
         "for one slice instead of the whole ~1000-line guide; start with " +
         "`core`, then fetch `attention`/`polish`/`chatgpt-apps` as needed.",
-      inputSchema: {
+      inputSchema: closedInput({
         topic: z
           .string()
           .optional()
           .describe(
             `Slice: ${GUIDE_TOPIC_NAMES.join(", ")} — or an H2 heading prefix. Omit for the full guide.`
           ),
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         guide: z.string(),
         engineVersion: z.string(),
         topic: z.string().optional(),
         topics: z.array(z.string()),
         sections: z.array(z.string()),
-      },
+      }),
       annotations: { readOnlyHint: true },
     },
     async ({ topic }) => {
@@ -329,8 +358,7 @@ export function buildMcpServer(): { server: McpServer; jobs: JobManager } {
       description:
         "JSON Schema for storyboard.json, generated from the engine's own " +
         "zod schema — the exact contract the engine validates against.",
-      inputSchema: {},
-      outputSchema: { schema: z.record(z.string(), z.unknown()) },
+      outputSchema: z.object({ schema: z.record(z.string(), z.unknown()) }),
       annotations: { readOnlyHint: true },
     },
     async () =>
@@ -348,14 +376,14 @@ export function buildMcpServer(): { server: McpServer; jobs: JobManager } {
         "anything. Pass exactly one of: dir (uses generated/storyboard.json), " +
         "path (a storyboard file), or json (storyboard JSON as a string). " +
         "relaxed makes narration optional (probe semantics).",
-      inputSchema: {
+      inputSchema: closedInput({
         dir: z.string().optional().describe("demo dir → generated/storyboard.json"),
         path: z.string().optional().describe("path to a storyboard .json file"),
         json: z.string().optional().describe("storyboard JSON as a string"),
         relaxed: z.boolean().optional(),
         params: PARAMS_INPUT,
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         valid: z.boolean(),
         storyboardPath: z.string().optional(),
         title: z.string().optional(),
@@ -365,7 +393,7 @@ export function buildMcpServer(): { server: McpServer; jobs: JobManager } {
         ),
         warnings: z.array(z.string()),
         lint: z.array(LINT_ISSUE_SHAPE).optional(),
-      },
+      }),
       annotations: { readOnlyHint: true },
     },
     async (args) => {
@@ -441,14 +469,14 @@ export function buildMcpServer(): { server: McpServer; jobs: JobManager } {
         "Run it after every storyboard edit, before probe/render. Pass exactly " +
         "one of dir / path / json. lang lints a narrations[lang] translation at " +
         "that language's speaking rate.",
-      inputSchema: {
+      inputSchema: closedInput({
         dir: z.string().optional().describe("demo dir → generated/storyboard.json"),
         path: z.string().optional().describe("path to a storyboard .json file"),
         json: z.string().optional().describe("storyboard JSON as a string"),
         lang: z.string().optional(),
         params: PARAMS_INPUT,
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         issues: z.array(LINT_ISSUE_SHAPE),
         estimate: z.array(
           z.object({
@@ -462,7 +490,7 @@ export function buildMcpServer(): { server: McpServer; jobs: JobManager } {
         ),
         narrationTotalMs: z.number(),
         wordsPerSec: z.number(),
-      },
+      }),
       annotations: { readOnlyHint: true },
     },
     async (args) => {
@@ -508,7 +536,7 @@ export function buildMcpServer(): { server: McpServer; jobs: JobManager } {
         "With fromUrl the page is inspected first (no LLM): its headings become " +
         "scenes and its unique selectors become the beats + a `_candidates` list — " +
         "you then write the narration and turn the candidate hover into the real click.",
-      inputSchema: {
+      inputSchema: closedInput({
         name: z.string().describe("demo name (creates demos/<name>/)"),
         dir: z.string().optional(),
         force: z.boolean().optional(),
@@ -519,12 +547,12 @@ export function buildMcpServer(): { server: McpServer; jobs: JobManager } {
           .object({ width: z.number(), height: z.number() })
           .optional()
           .describe("fromUrl: viewport (default 1280x720)"),
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         demoDir: z.string(),
         storyboardPath: z.string(),
         briefPath: z.string(),
-      },
+      }),
     },
     async (args) => {
       // fromUrl launches Chrome: honour the target repo's .env (#77).
@@ -559,10 +587,10 @@ export function buildMcpServer(): { server: McpServer; jobs: JobManager } {
         "LLM-only servers like Ollama), API key, playwright + its ffmpeg " +
         "helper (records the take; installed on the first take unless " +
         "AIDEMO_NO_AUTO_INSTALL=1), installed skill.",
-      inputSchema: {
+      inputSchema: closedInput({
         dir: z.string().optional().describe("repo to check for an installed skill"),
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         engineVersion: z.string(),
         node: z.string(),
         ffmpeg: z.string().nullable(),
@@ -610,7 +638,7 @@ export function buildMcpServer(): { server: McpServer; jobs: JobManager } {
             .nullable(),
         }),
         ok: z.boolean(),
-      },
+      }),
       annotations: { readOnlyHint: true },
     },
     async (args) => {
@@ -633,7 +661,7 @@ export function buildMcpServer(): { server: McpServer; jobs: JobManager } {
         "Owner/repo come from the repo's origin remote; the demo name from the " +
         "directory basename. Pair with the demo-publish workflow so CI keeps " +
         "the URLs fresh. See docs/EMBEDS.md.",
-      inputSchema: {
+      inputSchema: closedInput({
         dir: DIR_INPUT,
         repo: z
           .string()
@@ -643,8 +671,8 @@ export function buildMcpServer(): { server: McpServer; jobs: JobManager } {
           .string()
           .optional()
           .describe("still-frame basename under stills/ (default: poster)"),
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         owner: z.string(),
         repo: z.string(),
         demo: z.string(),
@@ -655,6 +683,7 @@ export function buildMcpServer(): { server: McpServer; jobs: JobManager } {
           mp4: z.string(),
           still: z.string(),
           pagesMp4: z.string(),
+          pagesVtt: z.string().describe("captions for the <video> embed's <track>"),
           pagesBase: z.string(),
         }),
         snippets: z.object({
@@ -667,7 +696,7 @@ export function buildMcpServer(): { server: McpServer; jobs: JobManager } {
           present: z.boolean(),
           template: z.string(),
         }),
-      },
+      }),
       annotations: { readOnlyHint: true },
     },
     async (args) => {
@@ -698,7 +727,7 @@ export function buildMcpServer(): { server: McpServer; jobs: JobManager } {
         "network call. Call this whenever something felt broken, surprising, " +
         "or needed a workaround; skip it if the session was clean. Set dryRun " +
         "to preview the assembled title/body without filing anything.",
-      inputSchema: {
+      inputSchema: closedInput({
         title: z.string().describe("short issue title"),
         body: z
           .string()
@@ -719,15 +748,15 @@ export function buildMcpServer(): { server: McpServer; jobs: JobManager } {
           .boolean()
           .optional()
           .describe("assemble the title/body but don't file anything — preview only"),
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         filed: z.boolean(),
         title: z.string(),
         body: z.string(),
         url: z.string().optional(),
         localPath: z.string().optional(),
         message: z.string(),
-      },
+      }),
     },
     async (args) => {
       const demoDir = args.dir ? resolve(args.dir) : null;
@@ -751,11 +780,11 @@ export function buildMcpServer(): { server: McpServer; jobs: JobManager } {
         "compose), log tail, and final result or error (with failure-artifact " +
         "paths and, on a genuine failure, a feedbackHint pointing at the " +
         "feedback tool) of a pipeline job.",
-      inputSchema: {
+      inputSchema: closedInput({
         jobId: z.string(),
         tailLines: z.number().optional().describe("log lines to return (default 40)"),
-      },
-      outputSchema: JOB_STATUS_SHAPE,
+      }),
+      outputSchema: z.object(JOB_STATUS_SHAPE),
       annotations: { readOnlyHint: true },
     },
     async (args) => {
@@ -776,8 +805,7 @@ export function buildMcpServer(): { server: McpServer; jobs: JobManager } {
     {
       title: "List jobs",
       description: "All jobs this server session, newest last.",
-      inputSchema: {},
-      outputSchema: {
+      outputSchema: z.object({
         jobs: z.array(
           z.object({
             jobId: z.string(),
@@ -789,7 +817,7 @@ export function buildMcpServer(): { server: McpServer; jobs: JobManager } {
             endedAt: z.string().nullable(),
           })
         ),
-      },
+      }),
       annotations: { readOnlyHint: true },
     },
     async () =>
@@ -814,8 +842,8 @@ export function buildMcpServer(): { server: McpServer; jobs: JobManager } {
         "Best-effort cancel (checked between actions/scenes/stages). A " +
         "mid-record cancel salvages the partial timeline + footage. The job " +
         "settles asynchronously — poll job_status for the final state.",
-      inputSchema: { jobId: z.string() },
-      outputSchema: JOB_STATUS_SHAPE,
+      inputSchema: closedInput({ jobId: z.string() }),
+      outputSchema: z.object(JOB_STATUS_SHAPE),
     },
     async (args) => {
       const job = jobs.cancel(args.jobId);
@@ -840,8 +868,8 @@ export function buildMcpServer(): { server: McpServer; jobs: JobManager } {
         description:
           `${description} Returns a jobId immediately — poll job_status. ` +
           `Rejects if another job is running.`,
-        inputSchema: inputShape,
-        outputSchema: JOB_START_SHAPE,
+        inputSchema: closedInput(inputShape),
+        outputSchema: z.object(JOB_START_SHAPE),
       },
       (async (args: z.infer<z.ZodObject<Shape>>) => {
         const project = new Project((args as { dir: string }).dir);
@@ -1019,19 +1047,19 @@ export function buildMcpServer(): { server: McpServer; jobs: JobManager } {
         "and selectors become scenes (cut at navigations and async payoffs), narration " +
         "is left as placeholders, and `_notes` lists what was approximated. No LLM, " +
         "no browser. Then write the narration and probe.",
-      inputSchema: {
+      inputSchema: closedInput({
         file: z.string().describe("absolute path to trace.zip or the test file"),
         name: z.string().describe("demo name (creates demos/<name>/)"),
         dir: z.string().optional().describe("repo to scaffold into (default: server cwd)"),
         force: z.boolean().optional(),
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         demoDir: z.string(),
         storyboardPath: z.string(),
         steps: z.number(),
         scenes: z.number(),
         notes: z.array(z.string()),
-      },
+      }),
     },
     async (args) => {
       try {
@@ -1488,9 +1516,30 @@ export function buildMcpServer(): { server: McpServer; jobs: JobManager } {
   return { server, jobs };
 }
 
-/** Run the stdio server until the client disconnects. Never resolves. */
+/**
+ * The process's stdio wire, reporting when the connection ends. serveStdio
+ * owns the wire and closes it when the connection is over (stdin EOF, a
+ * broken stdout, an oversized message, or the connection's server closing);
+ * discarding a `server/discover` probe instance never closes it.
+ */
+class ProcessStdioTransport extends StdioServerTransport {
+  constructor(private readonly onEnd: () => void) {
+    super();
+  }
+
+  override async close(): Promise<void> {
+    await super.close();
+    this.onEnd();
+  }
+}
+
+/**
+ * Run the stdio server until the client disconnects. Never resolves.
+ * serveStdio answers both protocol eras: a 2025-era client (`initialize`
+ * handshake, what deployed clients speak) and a 2026-07-28 client.
+ */
 export async function runMcpServer(): Promise<void> {
-  const { server, jobs } = buildMcpServer();
+  const jobs = new JobManager();
   let shuttingDown = false;
   const shutdown = () => {
     if (shuttingDown) return;
@@ -1513,8 +1562,9 @@ export async function runMcpServer(): Promise<void> {
   };
   process.stdin.on("end", shutdown);
   process.stdin.on("close", shutdown);
-  server.server.onclose = shutdown;
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
+  serveStdio(() => buildMcpServer(jobs).server, {
+    transport: new ProcessStdioTransport(shutdown),
+    onerror: (err) => log(`mcp: ${err.message}`),
+  });
   await new Promise(() => {}); // lives until shutdown() exits the process
 }

package/src/walkthrough.ts

@@ -13,7 +13,8 @@ import { Project } from "./project.js";
 import { ComposeReportSchema, type Storyboard } from "./types.js";
 import { runFfmpeg } from "./ffmpeg.js";
 import { toSrt, toVtt } from "./captions.js";
-import { finalVideoCues } from "./caption-track.js";
+import { finalVideoCues, htmlTrackLanguage } from "./caption-track.js";
+import { resolveNarrationLanguage } from "./i18n.js";
 import { ensureDir, exists, readJson, writeJson, log, step } from "./util.js";
 
 export interface WalkthroughOptions {
@@ -150,7 +151,15 @@ export async function exportWalkthrough(
   );
 
   const index = resolve(dir, "index.html");
-  await fs.writeFile(index, renderHtml(title, videoRel, scenes, report.durationMs));
+  // The page's player offers the shipped VTT as a captions track (off until
+  // the viewer turns it on, like the MP4's own subtitle track).
+  const track = captions.vtt
+    ? {
+        src: basename(captions.vtt),
+        ...htmlTrackLanguage(resolveNarrationLanguage(storyboard, project.lang)),
+      }
+    : undefined;
+  await fs.writeFile(index, renderHtml(title, videoRel, scenes, report.durationMs, track));
   const manifest = resolve(dir, "walkthrough.json");
   await writeJson(manifest, {
     title,
@@ -167,7 +176,8 @@ function renderHtml(
   title: string,
   videoRel: string,
   scenes: WalkthroughScene[],
-  durationMs: number
+  durationMs: number,
+  track?: { src: string; srclang: string; label: string }
 ): string {
   const cards = scenes
     .map(
@@ -215,7 +225,11 @@ function renderHtml(
   <h1>${esc(title)}</h1>
   <div class="hint">${scenes.length} steps · ${mmss(durationMs)} · ← → to move between steps, Enter to play from a step</div>
 </header>
-<video id="v" src="${esc(videoRel)}" controls preload="metadata"></video>
+<video id="v" src="${esc(videoRel)}" controls preload="metadata">${
+    track
+      ? `<track kind="captions" src="${esc(track.src)}" srclang="${esc(track.srclang)}" label="${esc(track.label)}">`
+      : ""
+  }</video>
 <main>${cards}
 </main>
 <script>