tileflow 0.1.0-alpha.11 → 0.1.0-alpha.12

package/README.md

@@ -151,6 +151,23 @@ on that route. Capture does not start the server or discover ports. It accepts l
 selects exactly one target, verifies the concrete theme, and waits for the component's idle marker.
 Do not run a separate `tileflow preview` server beside the application.
 
+## Render a timed shot
+
+Commit a [capture shot](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/capture-shots.md)
+under `shots` on the same map: a concrete theme, a viewport, and two or more center-camera
+keyframes, optionally with a theme blend. Then render it:
+
+```sh
+npx tileflow capture --shot dusk-flyover --json
+npx tileflow capture --shot dusk-flyover --format frames --out-dir evidence --json
+```
+
+The first command writes `.tileflow/captures/shots/dusk-flyover.webm`; the second writes
+`evidence/dusk-flyover/frame-0000.png` and the following frames. Each output has a sibling
+`.receipt.json` shot receipt. Repeat `--shot` or use `--all-shots` to render several shots; `--out`
+names the `.webm` file or frame directory of a single shot. Every frame waits for the map to be
+ready, so a slow machine renders more slowly without dropping frames.
+
 ## Review pixels without accepting changes
 
 After reviewing a render, create its baseline. Compare subsequent renders separately:

package/dist/index.js

@@ -649,6 +649,7 @@ import { isAbsolute, relative as relative2, resolve as resolve3, sep as sep2 } f
 import {
   createTileflowCaptureSession,
   serializeTileflowCaptureReceipt,
+  serializeTileflowShotReceipt,
   setupTileflowCaptureBrowser,
   TileflowCaptureError,
   tileflowSyntheticAssetOrigin,
@@ -658,7 +659,8 @@ import {
   compareCodeUnits as compareCodeUnits3,
   normalizeTileflowCaptureScene,
   tileflowCaptureSceneNameSchema,
-  tileflowCaptureSceneSchema
+  tileflowCaptureSceneSchema,
+  tileflowCaptureShotNameSchema
 } from "@tileflow/core";
 import {
   createTileflowArtifactDiagnostics,
@@ -670,8 +672,8 @@ import { TileflowStyleValidationError } from "@tileflow/dev/validation";
 
 // src/capture-output.ts
 import { randomUUID } from "crypto";
-import { lstat, mkdir as mkdir2, open as open2, readFile as readFile2, rename as rename2, unlink as unlink2 } from "fs/promises";
-import { basename, dirname as dirname3, relative, resolve as resolve2, sep } from "path";
+import { lstat, mkdir as mkdir2, open as open2, readdir, readFile as readFile2, rename as rename2, rm, unlink as unlink2 } from "fs/promises";
+import { basename, dirname as dirname3, join, relative, resolve as resolve2, sep } from "path";
 var maximumAtomicArtifactBytes = 256 * 1024 * 1024;
 async function writeCapturePair(input) {
   const outputPath = resolve2(input.outputPath);
@@ -815,6 +817,119 @@ async function writeAtomicFile(input) {
     await removeOptional(temporary);
   }
 }
+var shotFrameFilePattern = /^frame-\d{4}\.png$/u;
+function shotFrameFileName(index) {
+  return `frame-${String(index).padStart(4, "0")}.png`;
+}
+async function stageShotFrameDirectory(input) {
+  const boundaryPath = resolve2(input.boundaryPath);
+  const directory = resolve2(input.directory);
+  await assertNoSymlinkComponents(dirname3(directory), boundaryPath);
+  await listShotFrameDirectory(directory);
+  await mkdir2(dirname3(directory), { recursive: true });
+  await assertNoSymlinkComponents(dirname3(directory), boundaryPath);
+  const staging = temporarySibling(directory, `${process.pid}.${randomUUID()}`, "frames");
+  await mkdir2(staging);
+  return {
+    boundaryPath,
+    directory,
+    staging,
+    write: (index, png) => writeSyncedExclusive(join(staging, shotFrameFileName(index)), png),
+    discard: () => rm(staging, { force: true, recursive: true })
+  };
+}
+async function commitShotFrameDirectory(input) {
+  const { stage } = input;
+  const receiptPath = resolve2(input.receiptPath);
+  const receipt = new TextEncoder().encode(input.receipt);
+  await assertNoSymlinkComponents(dirname3(stage.directory), stage.boundaryPath);
+  await assertNoSymlinkComponents(dirname3(receiptPath), stage.boundaryPath);
+  await assertNotSymlink(receiptPath);
+  const existingFrames = await listShotFrameDirectory(stage.directory);
+  const existingReceipt = await readOptional(receiptPath);
+  if (existingFrames && existingReceipt && Buffer.from(existingReceipt).equals(Buffer.from(receipt)) && await sameShotFrames(stage.directory, existingFrames, stage.staging)) {
+    await stage.discard();
+    return false;
+  }
+  if ((existingFrames || existingReceipt) && !input.managed && !input.force) {
+    throw new Error(
+      "Shot output already exists with different contents. Use --force to replace it."
+    );
+  }
+  const transaction = `${process.pid}.${randomUUID()}`;
+  const receiptTemporary = temporarySibling(receiptPath, transaction, "new");
+  const directoryBackup = temporarySibling(stage.directory, transaction, "previous");
+  const receiptBackup = temporarySibling(receiptPath, transaction, "previous");
+  const state = {
+    directoryBackedUp: false,
+    directoryInstalled: false,
+    receiptBackedUp: false,
+    receiptInstalled: false
+  };
+  try {
+    await writeSyncedExclusive(receiptTemporary, receipt);
+    await syncDirectory2(stage.staging);
+    if (existingFrames) {
+      await rename2(stage.directory, directoryBackup);
+      state.directoryBackedUp = true;
+    }
+    if (existingReceipt) {
+      await rename2(receiptPath, receiptBackup);
+      state.receiptBackedUp = true;
+    }
+    await rename2(stage.staging, stage.directory);
+    state.directoryInstalled = true;
+    await rename2(receiptTemporary, receiptPath);
+    state.receiptInstalled = true;
+    await syncDirectory2(dirname3(stage.directory));
+    if (dirname3(receiptPath) !== dirname3(stage.directory))
+      await syncDirectory2(dirname3(receiptPath));
+  } catch (error) {
+    if (state.receiptInstalled) await removeOptional(receiptPath).catch(() => void 0);
+    if (state.receiptBackedUp) await rename2(receiptBackup, receiptPath).catch(() => void 0);
+    if (state.directoryInstalled) {
+      await rename2(stage.directory, stage.staging).catch(() => void 0);
+    }
+    if (state.directoryBackedUp) {
+      await rename2(directoryBackup, stage.directory).catch(() => void 0);
+    }
+    throw error;
+  } finally {
+    await removeOptional(receiptTemporary).catch(() => void 0);
+  }
+  await Promise.allSettled([
+    rm(directoryBackup, { force: true, recursive: true }),
+    removeOptional(receiptBackup)
+  ]);
+  return true;
+}
+async function listShotFrameDirectory(directory) {
+  const info = await lstatOptional(directory);
+  if (!info) return void 0;
+  if (info.isSymbolicLink()) throw new Error("Capture output cannot be a symbolic link.");
+  if (!info.isDirectory()) throw new Error("Shot frame output must be a directory.");
+  const entries = await readdir(directory, { withFileTypes: true });
+  if (entries.some((entry) => !entry.isFile() || !shotFrameFilePattern.test(entry.name))) {
+    throw new Error(
+      "Shot frame output contains files that are not Tileflow frames. Choose an empty or Tileflow-owned directory."
+    );
+  }
+  return entries.map((entry) => entry.name).sort();
+}
+async function sameShotFrames(directory, names, staging) {
+  const staged = (await readdir(staging)).sort();
+  if (staged.length !== names.length || staged.some((name, index) => name !== names[index])) {
+    return false;
+  }
+  for (const name of names) {
+    const [existing, next] = await Promise.all([
+      readOptional(join(directory, name)),
+      readOptional(join(staging, name))
+    ]);
+    if (!existing || !next || !Buffer.from(existing).equals(Buffer.from(next))) return false;
+  }
+  return true;
+}
 function captureReceiptPath(outputPath) {
   return outputPath.toLowerCase().endsWith(".png") ? `${outputPath.slice(0, -4)}.receipt.json` : `${outputPath}.receipt.json`;
 }
@@ -955,7 +1070,14 @@ function registerCaptureCommands(program2, dependencies) {
       controller.close();
     }
   });
-  program2.command("capture").description("Render Tileflow scenes to PNG with a pinned headless browser").argument("[scenes...]", "named committed capture scenes").option("-c, --config <path>", "config path", dependencies.defaultConfigPath).option("--all", "capture every configured scene").option("--map <name>", "capture one map with an uncommitted camera").option("--theme <name>", "required concrete theme for exploratory --map capture").option("--center <lng,lat>", "exploratory center camera").option("--bounds <west,south,east,north>", "exploratory bounds camera").option("--zoom <number>", "exploratory center zoom").option("--bearing <number>", "exploratory camera bearing").option("--pitch <number>", "exploratory camera pitch").option("--width <pixels>", "exploratory viewport width").option("--height <pixels>", "exploratory viewport height").option("--dpr <ratio>", "exploratory device pixel ratio: 1 or 2").option("--app-origin <origin>", "loopback origin for committed application scenes").option("--url <url>", "one-off full loopback URL for exactly one named scene").option("--selector <selector>", "one-off application target selector").option("--frame <frame>", "application capture frame: map or viewport").option("--out <path>", "PNG path for one capture").option("--out-dir <path>", "directory for one or more captures").option("--force", "replace different explicit output files").option("--json", "print deterministic schema-version-1 JSON").option("--watch", "keep running and recapture after each valid local edit").option(
+  program2.command("capture").description(
+    "Render Tileflow scenes to PNG, or timed shots to video, with a pinned headless browser"
+  ).argument("[scenes...]", "named committed capture scenes").option("-c, --config <path>", "config path", dependencies.defaultConfigPath).option("--all", "capture every configured scene").option(
+    "--shot <name>",
+    "render a committed timed shot; repeat for more shots",
+    collectOption,
+    []
+  ).option("--all-shots", "render every committed timed shot").option("--format <format>", "shot output: webm (default) or frames").option("--map <name>", "capture one map with an uncommitted camera").option("--theme <name>", "required concrete theme for exploratory --map capture").option("--center <lng,lat>", "exploratory center camera").option("--bounds <west,south,east,north>", "exploratory bounds camera").option("--zoom <number>", "exploratory center zoom").option("--bearing <number>", "exploratory camera bearing").option("--pitch <number>", "exploratory camera pitch").option("--width <pixels>", "exploratory viewport width").option("--height <pixels>", "exploratory viewport height").option("--dpr <ratio>", "exploratory device pixel ratio: 1 or 2").option("--app-origin <origin>", "loopback origin for committed application scenes").option("--url <url>", "one-off full loopback URL for exactly one named scene").option("--selector <selector>", "one-off application target selector").option("--frame <frame>", "application capture frame: map or viewport").option("--out <path>", "PNG path for one scene, or .webm/frame directory for one shot").option("--out-dir <path>", "directory for one or more captures").option("--force", "replace different explicit output files").option("--json", "print deterministic schema-version-1 JSON").option("--watch", "keep running and recapture after each valid local edit").option(
     "--no-browser-install",
     "require the pinned browser to be prepared; never use system Chrome"
   ).addHelpText(
@@ -965,11 +1087,205 @@ function registerCaptureCommands(program2, dependencies) {
     try {
       await runCaptureCommand(scenes ?? [], options);
     } catch (error) {
-      printCaptureError(error, { command: "capture", json: options.json });
+      printCaptureError(error, {
+        command: isShotSelection(options) ? "capture.shot" : "capture",
+        json: options.json
+      });
       process.exitCode = 1;
     }
   });
 }
+function collectOption(value, previous) {
+  return [...previous, value];
+}
+function isShotSelection(options) {
+  return Boolean(options.allShots) || (options.shot?.length ?? 0) > 0;
+}
+function createTileflowShotCaptureJson(shots, cwd) {
+  return {
+    schemaVersion: 1,
+    command: "capture.shot",
+    shots: [...shots].sort((left, right) => compareCodeUnits3(left.capture.shot, right.capture.shot)).map(({ capture, outputPath, receiptPath }) => ({
+      shot: capture.shot,
+      map: capture.map,
+      theme: capture.theme,
+      status: "captured",
+      format: capture.format,
+      ...capture.codec ? { codec: capture.codec } : {},
+      outputPath: relativePath(cwd, outputPath),
+      receiptPath: relativePath(cwd, receiptPath),
+      sha256: capture.sha256,
+      framesSha256: capture.framesSha256,
+      frameCount: capture.frameCount,
+      fps: capture.fps,
+      durationMs: capture.durationMs,
+      width: capture.width,
+      height: capture.height,
+      dpr: capture.dpr,
+      renderer: capture.renderer,
+      networkDependent: capture.networkDependent,
+      warnings: [...capture.warnings].sort(compareCodeUnits3)
+    }))
+  };
+}
+function serializeTileflowShotCaptureJson(value) {
+  return `${JSON.stringify(value, null, 2)}
+`;
+}
+function shotReceiptPath(outputPath) {
+  return outputPath.toLowerCase().endsWith(".webm") ? `${outputPath.slice(0, -5)}.receipt.json` : `${outputPath}.receipt.json`;
+}
+async function runCaptureShotCommand(options) {
+  const cwd = process.cwd();
+  const format = options.format === "frames" ? "frames" : "webm";
+  const controller = installSignalAbortController();
+  const session = createTileflowCaptureSession({
+    allowBrowserInstall: options.browserInstall,
+    config: options.config,
+    cwd,
+    onBrowserInstallProgress: options.json ? void 0 : printInstallProgress,
+    signal: controller.signal
+  });
+  const stages = /* @__PURE__ */ new Map();
+  try {
+    const onFrame = format === "frames" ? async (frame) => {
+      let stage = stages.get(frame.shot);
+      if (!stage) {
+        const target = resolveShotOutputTarget(frame.shot, options, format, cwd);
+        stage = await stageShotFrameDirectory({
+          boundaryPath: target.boundaryPath,
+          directory: target.outputPath
+        });
+        stages.set(frame.shot, stage);
+      }
+      await stage.write(frame.index, frame.png);
+    } : void 0;
+    const shotOptions = { format, ...onFrame ? { onFrame } : {}, signal: controller.signal };
+    const result = options.allShots ? await session.captureAllShots(shotOptions) : await session.captureShots(options.shot ?? [], shotOptions);
+    const written = [];
+    for (const capture of result.shots) {
+      const target = resolveShotOutputTarget(capture.shot, options, format, cwd);
+      const receipt = serializeTileflowShotReceipt(capture.receipt);
+      if (capture.video) {
+        await writeAtomicFileSet({
+          boundaryPath: target.boundaryPath,
+          files: [
+            { path: target.outputPath, source: capture.video },
+            { path: target.receiptPath, source: receipt }
+          ],
+          force: Boolean(options.force),
+          label: "Shot output",
+          managed: target.managed
+        });
+      } else {
+        const stage = stages.get(capture.shot);
+        if (!stage) throw new Error(`Shot ${capture.shot} produced no frames.`);
+        await commitShotFrameDirectory({
+          force: Boolean(options.force),
+          managed: target.managed,
+          receipt,
+          receiptPath: target.receiptPath,
+          stage
+        });
+        stages.delete(capture.shot);
+      }
+      written.push({ capture, outputPath: target.outputPath, receiptPath: target.receiptPath });
+    }
+    if (!options.out && !options.outDir) await warnIfManagedCapturesAreNotIgnored(cwd);
+    const document = createTileflowShotCaptureJson(written, cwd);
+    if (options.json) {
+      process.stdout.write(serializeTileflowShotCaptureJson(document));
+      return;
+    }
+    for (const entry of document.shots) {
+      console.log(
+        `Rendered ${entry.shot} -> ${entry.outputPath} (${entry.frameCount} frames, ${entry.sha256.slice(0, 12)}).`
+      );
+      if (entry.networkDependent) {
+        console.error(`Shot ${entry.shot} used remote map resources.`);
+      }
+    }
+  } finally {
+    await Promise.allSettled([...stages.values()].map((stage) => stage.discard()));
+    await session.close();
+    controller.close();
+  }
+}
+function resolveShotOutputTarget(shot, options, format, cwd) {
+  const managed = !options.out && !options.outDir;
+  const directory = resolve3(cwd, options.outDir ?? ".tileflow/captures/shots");
+  const outputPath = options.out ? resolve3(cwd, options.out) : resolve3(directory, format === "webm" ? `${shot}.webm` : shot);
+  const receiptPath = shotReceiptPath(outputPath);
+  if (managed) {
+    const relativeToRoot = relative2(directory, outputPath);
+    if (relativeToRoot.startsWith("..") || relativeToRoot.includes(`..${sep2}`)) {
+      throw new Error("Managed shot output escaped .tileflow/captures/shots.");
+    }
+  }
+  relativePath(cwd, outputPath);
+  relativePath(cwd, receiptPath);
+  return {
+    boundaryPath: managed ? cwd : options.outDir ? directory : resolve3(outputPath, ".."),
+    managed,
+    outputPath,
+    receiptPath
+  };
+}
+function validateShotSelectionOptions(positionalScenes, options) {
+  const shots = options.shot ?? [];
+  if (options.allShots && shots.length > 0) {
+    throw new Error("Use either --shot or --all-shots, not both.");
+  }
+  if (positionalScenes.length > 0 || options.all || options.map) {
+    throw new Error("Render shots separately from scenes; --shot and --all-shots take no scenes.");
+  }
+  if (options.watch) {
+    throw new Error("--watch captures scenes; it does not render shots.");
+  }
+  const sceneOnlyOptions = [
+    options.center,
+    options.bounds,
+    options.zoom,
+    options.bearing,
+    options.pitch,
+    options.width,
+    options.height,
+    options.dpr,
+    options.theme,
+    options.url,
+    options.appOrigin,
+    options.selector,
+    options.frame
+  ];
+  if (sceneOnlyOptions.some((value) => value !== void 0)) {
+    throw new Error(
+      "Shots render committed cameras and themes; camera, viewport, theme, and application flags apply to scenes."
+    );
+  }
+  for (const shot of shots) {
+    if (!tileflowCaptureShotNameSchema.safeParse(shot).success) {
+      throw new Error("--shot expects a portable Tileflow shot name.");
+    }
+  }
+  if (options.format !== void 0 && options.format !== "webm" && options.format !== "frames") {
+    throw new Error("--format expects webm or frames.");
+  }
+  if (options.out && options.outDir) {
+    throw new Error("Use either --out or --out-dir, not both.");
+  }
+  if (options.out) {
+    if (options.allShots || new Set(shots).size !== 1) {
+      throw new Error("--out can be used only when rendering one shot. Use --out-dir instead.");
+    }
+    const isVideoPath = options.out.toLowerCase().endsWith(".webm");
+    if ((options.format ?? "webm") === "webm" && !isVideoPath) {
+      throw new Error("--out must name a .webm file.");
+    }
+    if (options.format === "frames" && (isVideoPath || /\.(?:json|png)$/iu.test(options.out))) {
+      throw new Error("--out must name a directory for --format frames.");
+    }
+  }
+}
 function createTileflowCaptureJson(captures, cwd) {
   return {
     schemaVersion: 1,
@@ -1019,6 +1335,10 @@ function serializeTileflowCaptureFailureJson(value) {
 async function runCaptureCommand(positionalScenes, options) {
   validateSelectionOptions(positionalScenes, options);
   await withTileflowConfigSecretsHidden(async () => {
+    if (isShotSelection(options)) {
+      await runCaptureShotCommand(options);
+      return;
+    }
     if (options.watch) {
       await runCaptureWatchCommand(positionalScenes, options);
       return;
@@ -1267,6 +1587,13 @@ function waitForAbort(signal) {
   );
 }
 function validateSelectionOptions(positionalScenes, options) {
+  if (isShotSelection(options)) {
+    validateShotSelectionOptions(positionalScenes, options);
+    return;
+  }
+  if (options.format !== void 0) {
+    throw new Error("--format applies to --shot and --all-shots.");
+  }
   const exploratoryOptions = [
     options.center,
     options.bounds,
@@ -1325,7 +1652,9 @@ function validateSelectionOptions(positionalScenes, options) {
     throw new Error("Exploratory camera, viewport, and theme flags require --map.");
   }
   if (!options.all && positionalScenes.length === 0) {
-    throw new Error("Select at least one scene, use --all, or use --map for exploration.");
+    throw new Error(
+      "Select at least one scene, use --all, use --map for exploration, or select shots with --shot."
+    );
   }
 }
 function createExploratoryScene(options) {
@@ -1467,6 +1796,8 @@ function captureFailurePhase(error, code) {
   if (code === "MAP_LOAD_FAILED") return "map-load";
   if (code === "SCREENSHOT_FAILED" || code === "INVALID_PNG") return "screenshot";
   if (code === "SCENE_NOT_FOUND" || code.startsWith("APPLICATION_")) return "scene-resolution";
+  if (code === "SHOT_NOT_FOUND") return "shot-resolution";
+  if (code.startsWith("VIDEO_")) return "video-encode";
   if (code === "ABORTED") return "capture";
   return "input-validation";
 }
@@ -3137,7 +3468,7 @@ import {
 // src/icon-diff-report.ts
 import { randomUUID as randomUUID2 } from "crypto";
 import { mkdir as mkdir3, readFile as readFile3, rename as rename3, unlink as unlink3, writeFile } from "fs/promises";
-import { basename as basename2, dirname as dirname6, join } from "path";
+import { basename as basename2, dirname as dirname6, join as join2 } from "path";
 import {
   compareCodeUnits as compareCodeUnits5,
   sha256Hex,
@@ -3604,7 +3935,7 @@ async function writeAtomicReport(path, html, force) {
     if (!isMissingFile3(error)) throw error;
   }
   await mkdir3(dirname6(path), { recursive: true });
-  const temporaryPath = join(
+  const temporaryPath = join2(
     dirname6(path),
     `.${basename2(path)}.${process.pid}.${randomUUID2()}.tmp`
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tileflow",
-  "version": "0.1.0-alpha.11",
+  "version": "0.1.0-alpha.12",
   "license": "Apache-2.0",
   "description": "CLI-only tools for Tileflow config, capture, visual testing, and deploy.",
   "type": "module",
@@ -36,11 +36,11 @@
   },
   "dependencies": {
     "@hono/node-server": "2.1.3",
-    "@tileflow/capture": ">=0.1.0-alpha.29 <0.1.0-beta.0",
+    "@tileflow/capture": ">=0.1.0-alpha.30 <0.1.0-beta.0",
     "@tileflow/coordinates": ">=0.1.0-alpha.2 <0.1.0-beta.0",
     "@tileflow/coordinates-runtime": ">=0.1.0-alpha.5 <0.1.0-beta.0",
-    "@tileflow/core": ">=0.1.0-alpha.32 <0.1.0-beta.0",
-    "@tileflow/dev": ">=0.1.0-alpha.30 <0.1.0-beta.0",
+    "@tileflow/core": ">=0.1.0-alpha.34 <0.1.0-beta.0",
+    "@tileflow/dev": ">=0.1.0-alpha.31 <0.1.0-beta.0",
     "@tileflow/maps": ">=0.1.0-alpha.8 <0.1.0-beta.0",
     "commander": "^15.0.0",
     "hono": "4.13.7",