@tileflow/capture 0.1.0-alpha.29 → 0.1.0-alpha.31

package/README.md

@@ -1,5 +1,10 @@
 # @tileflow/capture
 
+For the complete CLI workflow, use `describe`, `inspect`, `capture`, `compare`, and Map DevTools (`preview`)
+as described in the [CLI guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/cli/README.md).
+New still captures include their normalized `definition` for later review. The CLI stores immutable
+capture IDs so `compare --before <id> --after <id>` can reuse evidence without rendering again.
+
 Headless Tileflow map capture for Node.js. Produce PNGs with versioned receipts, compare reviewed
 baselines, or inspect differences between deliberate renders. Use the
 [CLI](https://github.com/tileflow/tileflow-sdk/blob/main/packages/cli/README.md) for ordinary terminal
@@ -106,6 +111,66 @@ The equivalent CLI command is `tileflow setup capture`. These settings control b
 not the network access required by a map's remote resources. Tileflow never deletes the shared
 per-user browser cache.
 
+## Render a timed shot
+
+A [capture shot](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/capture-shots.md)
+is a committed camera move with keyframes and an optional theme blend. This module assumes a
+`dusk-flyover` shot in `tileflow.config.ts` and writes its WebM video and receipt:
+
+<!-- docs:check -->
+
+```ts
+import {mkdir, writeFile} from 'node:fs/promises';
+import {captureTileflowShot, serializeTileflowShotReceipt} from '@tileflow/capture';
+
+const shot = await captureTileflowShot({shot: 'dusk-flyover', allowBrowserInstall: true});
+if (!shot.video) throw new Error('The shot produced no video.');
+
+await mkdir('.tileflow/captures/shots', {recursive: true});
+await writeFile('.tileflow/captures/shots/dusk-flyover.webm', shot.video);
+await writeFile(
+  '.tileflow/captures/shots/dusk-flyover.receipt.json',
+  serializeTileflowShotReceipt(shot.receipt),
+);
+console.log(shot.frameCount, shot.codec, shot.framesSha256);
+```
+
+Every frame moves the camera with MapLibre `jumpTo`, moves the blend position, and waits for
+MapLibre `idle` and two animation frames before its screenshot, exactly as a scene does. A slow
+machine or network makes the render take longer; the video keeps its frame rate and shows every
+frame. `timeoutMs` bounds page setup and each frame separately.
+
+The pinned browser encodes the captured PNGs with WebCodecs: VP9, or VP8 where VP9 is unavailable.
+A browser that supports neither fails before the first frame with `VIDEO_ENCODER_UNAVAILABLE`.
+Use `format: 'frames'` to receive the PNG frames through `onFrame` instead of a video; frames are
+delivered in order and are not kept in memory:
+
+<!-- docs:check -->
+
+```ts
+import {mkdir, writeFile} from 'node:fs/promises';
+import {createTileflowCaptureSession} from '@tileflow/capture';
+
+await mkdir('frames', {recursive: true});
+const session = createTileflowCaptureSession({allowBrowserInstall: true});
+try {
+  const shot = await session.captureShot('dusk-flyover', {
+    format: 'frames',
+    onFrame: (frame) =>
+      writeFile(`frames/frame-${String(frame.index).padStart(4, '0')}.png`, frame.png),
+  });
+  console.log(shot.frameCount, shot.framesSha256);
+} finally {
+  await session.close();
+}
+```
+
+`captureShots` and `captureAllShots` render several shots from one compiled snapshot. A shot
+receipt records the shot, theme and blend styles, timing, dimensions, renderer, data identity, and
+`frames.sha256`, a digest of every frame's PNG SHA-256. Frames are reproducible under the same
+conditions as scene captures; encoder bytes may differ between runs, so `output.sha256` identifies
+the written video while `frames.sha256` identifies its pixels.
+
 ## Capture the running application
 
 Application capture uses the app's normal loopback server; it does not start a server or discover a
@@ -183,7 +248,9 @@ the perceptual metric and optional diff image are additional evidence. Never upd
 merely to make a failing comparison pass.
 
 `compareTileflowCapturesForReview` compares two deliberate renders with different styles while
-requiring compatible framing, renderer, and data identity. `analyzeTileflowCaptureReference` analyzes
+requiring compatible framing, renderer, and data identity. It accepts captures with or without a
+retained `definition`; when present, that definition must match the explicit review definition.
+`analyzeTileflowCaptureReference` analyzes
 an external PNG without claiming receipt compatibility. Neither operation approves a baseline.
 See the [receipt and comparison reference](https://github.com/tileflow/tileflow-sdk/blob/main/packages/capture/docs/receipts-and-comparison.md),
 also included under `docs/` in the installed package, for identities, metrics, and limits.
@@ -195,7 +262,8 @@ validation, browser startup, resource loading, MapLibre readiness, and screensho
 Resource diagnostics contain safe classification and origin/status information, not credentials,
 query strings, response bodies, raw browser stacks, or DOM contents.
 
-Receipts use schema version 4; parsing rejects any other version. Import
+Receipts use schema version 4; parsing rejects any other version. Shot receipts use their own
+schema version 1. Import
 `@tileflow/capture/receipt` for receipt-only tooling without loading the capture runtime. World selectors resolve once per capture session to
 an immutable release. Capture retains the complete resolved TileJSON, including its zoom range,
 bounds, attribution and vector-layer metadata. Above the data's maximum zoom, MapLibre enlarges

package/dist/{chunk-VNDAYGXY.js → chunk-BI5PWIH4.js}

@@ -6,6 +6,7 @@ import {
   serializeCanonicalJson,
   tileflowCaptureSceneLimits,
   tileflowCaptureSceneNameSchema,
+  tileflowCaptureShotLimits,
   tileflowPortableIdSchema,
   tileflowThemeNameSchema
 } from "@tileflow/core";
@@ -231,6 +232,219 @@ function validateTileflowCaptureReceipt(value) {
   assertCanonicalReceiptByteLimit(normalized);
   return normalized;
 }
+var tileflowShotReceiptSchemaVersion = 1;
+var tileflowShotReceiptLimits = Object.freeze({ maximumBytes: 64 * 1024 });
+function createTileflowShotReceipt(input) {
+  return validateTileflowShotReceipt({
+    schemaVersion: tileflowShotReceiptSchemaVersion,
+    kind: "shot",
+    shot: { name: input.shot, map: input.map, theme: input.theme, sha256: input.shotSha256 },
+    style: { sha256: input.styleSha256 },
+    ...input.blend ? { blend: { themes: input.blend } } : {},
+    timing: { fps: input.fps, frameCount: input.frameCount, durationMs: input.durationMs },
+    image: {
+      cssWidth: input.width,
+      cssHeight: input.height,
+      physicalWidth: input.width * input.dpr,
+      physicalHeight: input.height * input.dpr,
+      dpr: input.dpr
+    },
+    frames: { sha256: input.framesSha256 },
+    output: input.output,
+    renderer: input.renderer,
+    platform: { os: process.platform, architecture: process.arch },
+    data: normalizeCaptureDataInput(input.data),
+    verification: { data: "rendered", style: "rendered" },
+    networkDependent: input.networkDependent
+  });
+}
+function serializeTileflowShotReceipt(receipt) {
+  const serialized = `${serializeCanonicalJson(validateTileflowShotReceipt(receipt))}
+`;
+  if (new TextEncoder().encode(serialized).byteLength > tileflowShotReceiptLimits.maximumBytes) {
+    throw invalidReceipt("The shot receipt exceeds the supported byte limit.");
+  }
+  return serialized;
+}
+function parseTileflowShotReceipt(source) {
+  const byteLength = typeof source === "string" ? new TextEncoder().encode(source).byteLength : source.byteLength;
+  if (byteLength > tileflowShotReceiptLimits.maximumBytes) {
+    throw invalidReceipt("The shot receipt exceeds the supported byte limit.");
+  }
+  let value;
+  let text;
+  try {
+    text = typeof source === "string" ? source : new TextDecoder("utf-8", { fatal: true }).decode(source);
+    value = JSON.parse(text);
+  } catch (error) {
+    throw invalidReceipt("The shot receipt is not valid UTF-8 JSON.", error);
+  }
+  const receipt = validateTileflowShotReceipt(value);
+  if (text.trim() !== serializeCanonicalJson(value)) {
+    throw invalidReceipt("The shot receipt is not canonical JSON.");
+  }
+  return receipt;
+}
+function validateTileflowShotReceipt(value) {
+  assertPlainReceiptData(value, "receipt", {
+    allowArrays: true,
+    ancestors: /* @__PURE__ */ new WeakSet(),
+    nodes: 0
+  });
+  const receipt = requireRecord(value, "receipt");
+  if (receipt.schemaVersion !== tileflowShotReceiptSchemaVersion || receipt.kind !== "shot") {
+    throw invalidReceipt("The shot receipt schema version is unsupported.");
+  }
+  requireExactKeys(receipt, [
+    "schemaVersion",
+    "kind",
+    "shot",
+    "style",
+    ...receipt.blend === void 0 ? [] : ["blend"],
+    "timing",
+    "image",
+    "frames",
+    "output",
+    "renderer",
+    "platform",
+    "data",
+    "verification",
+    "networkDependent"
+  ]);
+  const shot = requireRecord(receipt.shot, "shot");
+  requireExactKeys(shot, ["name", "map", "theme", "sha256"]);
+  const style = requireRecord(receipt.style, "style");
+  requireExactKeys(style, ["sha256"]);
+  const blend = receipt.blend === void 0 ? void 0 : validateShotBlend(receipt.blend);
+  const timing = requireRecord(receipt.timing, "timing");
+  requireExactKeys(timing, ["fps", "frameCount", "durationMs"]);
+  const fps = timing.fps;
+  if (fps !== 24 && fps !== 25 && fps !== 30 && fps !== 50 && fps !== 60) {
+    throw invalidReceipt("The shot receipt has an invalid timing.fps.");
+  }
+  const frameCount = requirePositiveInteger(timing.frameCount, "timing.frameCount");
+  const durationMs = requirePositiveInteger(timing.durationMs, "timing.durationMs");
+  if (durationMs > tileflowCaptureShotLimits.durationMs.maximum || frameCount > tileflowCaptureShotLimits.maximumFrames || frameCount !== Math.floor(durationMs * fps / 1e3 + 1e-9) + 1) {
+    throw invalidReceipt("The shot receipt timing is inconsistent.");
+  }
+  const image = requireRecord(receipt.image, "image");
+  requireExactKeys(image, ["cssWidth", "cssHeight", "physicalWidth", "physicalHeight", "dpr"]);
+  const cssWidth = requirePositiveInteger(image.cssWidth, "image.cssWidth");
+  const cssHeight = requirePositiveInteger(image.cssHeight, "image.cssHeight");
+  const physicalWidth = requirePositiveInteger(image.physicalWidth, "image.physicalWidth");
+  const physicalHeight = requirePositiveInteger(image.physicalHeight, "image.physicalHeight");
+  if (image.dpr !== 1 && image.dpr !== 2) {
+    throw invalidReceipt("The shot receipt has an invalid image DPR.");
+  }
+  if (cssWidth * image.dpr !== physicalWidth || cssHeight * image.dpr !== physicalHeight) {
+    throw invalidReceipt("The shot receipt image dimensions are inconsistent.");
+  }
+  if (physicalWidth > tileflowCaptureSceneLimits.viewport.maximum || physicalHeight > tileflowCaptureSceneLimits.viewport.maximum || physicalWidth * physicalHeight > tileflowCaptureSceneLimits.maximumPhysicalPixels) {
+    throw invalidReceipt("The shot receipt image exceeds the supported pixel limit.");
+  }
+  const frames = requireRecord(receipt.frames, "frames");
+  requireExactKeys(frames, ["sha256"]);
+  const framesSha256 = requireHash(frames.sha256, "frames.sha256");
+  const output = requireRecord(receipt.output, "output");
+  if (output.kind === "webm") {
+    requireExactKeys(output, ["kind", "codec", "sha256"]);
+    if (output.codec !== "vp8" && output.codec !== "vp9") {
+      throw invalidReceipt("The shot receipt has an invalid output.codec.");
+    }
+  } else if (output.kind === "frames") {
+    requireExactKeys(output, ["kind", "sha256"]);
+    if (output.sha256 !== framesSha256) {
+      throw invalidReceipt("The shot receipt frame output does not match its frames.");
+    }
+  } else {
+    throw invalidReceipt("The shot receipt has an invalid output.kind.");
+  }
+  const renderer = requireRecord(receipt.renderer, "renderer");
+  requireExactKeys(renderer, [
+    "tileflow",
+    "maplibre",
+    "playwright",
+    "chromiumRevision",
+    "chromiumVersion"
+  ]);
+  const platform = requireRecord(receipt.platform, "platform");
+  requireExactKeys(platform, ["os", "architecture"]);
+  const verification = requireRecord(receipt.verification, "verification");
+  requireExactKeys(verification, ["data", "style"]);
+  if (verification.data !== "rendered" || verification.style !== "rendered") {
+    throw invalidReceipt("The shot receipt verification must record rendered style and data.");
+  }
+  if (typeof receipt.networkDependent !== "boolean") {
+    throw invalidReceipt("The shot receipt has an invalid network dependency flag.");
+  }
+  const normalized = {
+    schemaVersion: tileflowShotReceiptSchemaVersion,
+    kind: "shot",
+    shot: {
+      name: requireSceneName(shot.name),
+      map: requirePortableIdentifier(shot.map, "shot.map"),
+      theme: requireShotTheme(shot.theme, "shot.theme"),
+      sha256: requireHash(shot.sha256, "shot.sha256")
+    },
+    style: { sha256: requireHash(style.sha256, "style.sha256") },
+    ...blend ? { blend } : {},
+    timing: { fps, frameCount, durationMs },
+    image: { cssWidth, cssHeight, physicalWidth, physicalHeight, dpr: image.dpr },
+    frames: { sha256: framesSha256 },
+    output: output.kind === "webm" ? {
+      kind: "webm",
+      codec: output.codec,
+      sha256: requireHash(output.sha256, "output.sha256")
+    } : { kind: "frames", sha256: framesSha256 },
+    renderer: {
+      tileflow: requireBoundedString(renderer.tileflow, "renderer.tileflow"),
+      maplibre: requireBoundedString(renderer.maplibre, "renderer.maplibre"),
+      playwright: requireBoundedString(renderer.playwright, "renderer.playwright"),
+      chromiumRevision: requireBoundedString(
+        renderer.chromiumRevision,
+        "renderer.chromiumRevision"
+      ),
+      chromiumVersion: requireBoundedString(renderer.chromiumVersion, "renderer.chromiumVersion")
+    },
+    platform: {
+      os: requireBoundedString(platform.os, "platform.os"),
+      architecture: requireBoundedString(platform.architecture, "platform.architecture")
+    },
+    data: validateDataIdentity(receipt.data),
+    verification: { data: "rendered", style: "rendered" },
+    networkDependent: receipt.networkDependent
+  };
+  const serialized = `${serializeCanonicalJson(normalized)}
+`;
+  if (new TextEncoder().encode(serialized).byteLength > tileflowShotReceiptLimits.maximumBytes) {
+    throw invalidReceipt("The shot receipt exceeds the supported byte limit.");
+  }
+  return normalized;
+}
+function requireShotTheme(value, field) {
+  const result = tileflowThemeNameSchema.safeParse(value);
+  if (!result.success) throw invalidReceipt(`The shot receipt has an invalid ${field}.`);
+  return result.data;
+}
+function validateShotBlend(value) {
+  const blend = requireRecord(value, "blend");
+  requireExactKeys(blend, ["themes"]);
+  if (!Array.isArray(blend.themes) || blend.themes.length < tileflowCaptureShotLimits.blendThemes.minimum || blend.themes.length > tileflowCaptureShotLimits.blendThemes.maximum) {
+    throw invalidReceipt("The shot receipt has an invalid blend.themes list.");
+  }
+  const themes = blend.themes.map((entry, index) => {
+    const theme = requireRecord(entry, `blend.themes.${index}`);
+    requireExactKeys(theme, ["name", "styleSha256"]);
+    return {
+      name: requireShotTheme(theme.name, `blend.themes.${index}.name`),
+      styleSha256: requireHash(theme.styleSha256, `blend.themes.${index}.styleSha256`)
+    };
+  });
+  if (new Set(themes.map((theme) => theme.name)).size !== themes.length) {
+    throw invalidReceipt("The shot receipt blends a theme more than once.");
+  }
+  return { themes };
+}
 function validateDataIdentity(value) {
   const data = requireRecord(value, "data");
   if (data.kind === "tileflow-world") {
@@ -390,12 +604,17 @@ function assertCanonicalReceiptByteLimit(receipt) {
   }
 }
 function assertPlainReceiptData(value, path = "receipt", state = {
+  allowArrays: false,
   ancestors: /* @__PURE__ */ new WeakSet(),
   nodes: 0
 }, depth = 0) {
   if (value === null || value === void 0 || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
     return;
   }
+  if (typeof value === "object" && Array.isArray(value) && state.allowArrays) {
+    assertPlainReceiptArray(value, path, state, depth);
+    return;
+  }
   if (typeof value !== "object" || Array.isArray(value)) {
     throw invalidReceipt(`The baseline receipt has an executable or non-plain ${path} value.`);
   }
@@ -434,6 +653,35 @@ function assertPlainReceiptData(value, path = "receipt", state = {
     state.ancestors.delete(value);
   }
 }
+function assertPlainReceiptArray(value, path, state, depth) {
+  if (nodeUtilTypes.isProxy(value)) {
+    throw invalidReceipt(`The baseline receipt has an executable proxy at ${path}.`);
+  }
+  if (Object.getPrototypeOf(value) !== Array.prototype) {
+    throw invalidReceipt(`The baseline receipt has a non-plain ${path} array.`);
+  }
+  if (depth > 32 || ++state.nodes > 4096 || value.length > 4096) {
+    throw invalidReceipt("The baseline receipt exceeds the supported structural limit.");
+  }
+  if (state.ancestors.has(value)) {
+    throw invalidReceipt("The baseline receipt must not contain cyclic data.");
+  }
+  if (Reflect.ownKeys(value).length !== value.length + 1) {
+    throw invalidReceipt(`The baseline receipt has a sparse or extended ${path} array.`);
+  }
+  state.ancestors.add(value);
+  try {
+    for (let index = 0; index < value.length; index += 1) {
+      const descriptor = Object.getOwnPropertyDescriptor(value, index);
+      if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) {
+        throw invalidReceipt("The baseline receipt contains an accessor or non-enumerable field.");
+      }
+      assertPlainReceiptData(descriptor.value, `${path}.${index}`, state, depth + 1);
+    }
+  } finally {
+    state.ancestors.delete(value);
+  }
+}
 function requireRecord(value, field) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     throw invalidReceipt(`The baseline receipt has an invalid ${field} object.`);
@@ -544,5 +792,11 @@ export {
   createTileflowCaptureReceipt,
   serializeTileflowCaptureReceipt,
   parseTileflowCaptureReceipt,
-  validateTileflowCaptureReceipt
+  validateTileflowCaptureReceipt,
+  tileflowShotReceiptSchemaVersion,
+  tileflowShotReceiptLimits,
+  createTileflowShotReceipt,
+  serializeTileflowShotReceipt,
+  parseTileflowShotReceipt,
+  validateTileflowShotReceipt
 };

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { Browser } from 'playwright';
-import { T as TileflowCaptureRendererIdentity, a as TileflowCaptureReceipt, b as TileflowCaptureDataInput, c as TileflowCaptureWorldIdentity } from './receipt-DhFOATRO.js';
-export { C as CreateTileflowCaptureReceiptInput, d as TileflowCaptureDataBindings, e as TileflowCaptureDataCapabilities, f as TileflowCaptureDataIdentity, g as TileflowCaptureDataSemantics, h as TileflowCaptureDataSource, i as TileflowCaptureVectorIdentity, j as TileflowCaptureVerification, k as createTileflowCaptureReceipt, l as createTileflowCaptureRendererIdentity, p as parseTileflowCaptureReceipt, s as serializeTileflowCaptureReceipt, t as tileflowCaptureReceiptLimits, m as tileflowCaptureReceiptSchemaVersion, n as tileflowCaptureRuntime, v as validateTileflowCaptureReceipt } from './receipt-DhFOATRO.js';
-import { TileflowCaptureScene, MapLibreStyle, NormalizedTileflowCaptureScene } from '@tileflow/core';
-import { TileflowIconResolutionOptions, TileflowBuildArtifacts, TileflowBuildAsset } from '@tileflow/dev/artifacts';
+import { T as TileflowCaptureRendererIdentity, a as TileflowShotReceiptV1, b as TileflowCaptureReceipt, c as TileflowCaptureDataInput, d as TileflowCaptureWorldIdentity } from './receipt-CfZkzyXd.js';
+export { C as CreateTileflowCaptureReceiptInput, e as CreateTileflowShotReceiptInput, f as TileflowCaptureDataBindings, g as TileflowCaptureDataCapabilities, h as TileflowCaptureDataIdentity, i as TileflowCaptureDataSemantics, j as TileflowCaptureDataSource, k as TileflowCaptureVectorIdentity, l as TileflowCaptureVerification, m as createTileflowCaptureReceipt, n as createTileflowCaptureRendererIdentity, o as createTileflowShotReceipt, p as parseTileflowCaptureReceipt, q as parseTileflowShotReceipt, s as serializeTileflowCaptureReceipt, r as serializeTileflowShotReceipt, t as tileflowCaptureReceiptLimits, u as tileflowCaptureReceiptSchemaVersion, v as tileflowCaptureRuntime, w as tileflowShotReceiptLimits, x as tileflowShotReceiptSchemaVersion, y as validateTileflowCaptureReceipt, z as validateTileflowShotReceipt } from './receipt-CfZkzyXd.js';
+import { NormalizedTileflowCaptureShot, NormalizedTileflowCaptureScene, TileflowCaptureScene, MapLibreStyle } from '@tileflow/core';
+import { TileflowBuildAsset, TileflowIconResolutionOptions, TileflowBuildArtifacts } from '@tileflow/dev/artifacts';
 
 type TileflowBrowserInstallProgress = 'installing' | 'installed';
 type TileflowBrowserLaunchOptions = {
@@ -24,6 +24,49 @@ declare class TileflowCaptureBrowserManager {
     close(): Promise<void>;
 }
 
+declare const tileflowSyntheticAssetOrigin = "https://tileflow.local.invalid";
+type TileflowCaptureAsset = TileflowBuildAsset & {
+    url?: string;
+};
+
+type TileflowShotVideoCodec = 'vp8' | 'vp9';
+
+type TileflowShotFormat = 'frames' | 'webm';
+/** One rendered frame, delivered in order while a shot renders. */
+type TileflowShotFrame = {
+    shot: string;
+    index: number;
+    png: Uint8Array;
+    sha256: string;
+};
+type TileflowShotCapture = {
+    shot: string;
+    map: string;
+    theme: string;
+    format: TileflowShotFormat;
+    /** WebM bytes for the `webm` format. Frames reach `onFrame` and are not retained. */
+    video?: Uint8Array;
+    codec?: TileflowShotVideoCodec;
+    /** SHA-256 of the video, or of the frame set (`framesSha256`) for the `frames` format. */
+    sha256: string;
+    framesSha256: string;
+    frameSha256s: string[];
+    shotSha256: string;
+    styleSha256: string;
+    fps: NormalizedTileflowCaptureShot['fps'];
+    frameCount: number;
+    durationMs: number;
+    width: number;
+    height: number;
+    dpr: 1 | 2;
+    networkDependent: boolean;
+    renderer: TileflowCaptureRendererIdentity;
+    receipt: TileflowShotReceiptV1;
+    warnings: string[];
+};
+/** SHA-256 of each frame's PNG SHA-256 in lowercase hex, one per line, in frame order. */
+declare function tileflowShotFramesSha256(frameSha256s: readonly string[]): Promise<string>;
+
 declare const tileflowCaptureResultSchemaVersion: 1;
 type TileflowCaptureOptions = {
     allowBrowserInstall?: boolean;
@@ -47,6 +90,10 @@ type TileflowCaptureOptions = {
 };
 type CreateTileflowCaptureSessionOptions = Omit<TileflowCaptureOptions, 'scenes'>;
 type TileflowCapture = {
+    /** Concrete normalized frame retained for later review without rendering again. */
+    definition?: NormalizedTileflowCaptureScene & {
+        theme: string;
+    };
     scene: string;
     map: string;
     theme: string;
@@ -68,18 +115,39 @@ type TileflowCaptureResult = {
     schemaVersion: 1;
     captures: TileflowCapture[];
 };
+type TileflowShotCaptureOptions = {
+    /** `webm` (the default) encodes a VP9 or VP8 video; `frames` delivers only PNG frames. */
+    format?: TileflowShotFormat;
+    /** Receives each frame's PNG in order while the shot renders. */
+    onFrame?: (frame: TileflowShotFrame) => Promise<void> | void;
+    signal?: AbortSignal;
+};
+type TileflowShotCaptureResult = {
+    schemaVersion: 1;
+    shots: TileflowShotCapture[];
+};
+type CaptureTileflowShotOptions = CreateTileflowCaptureSessionOptions & Omit<TileflowShotCaptureOptions, 'signal'> & {
+    shot: string;
+};
 type TileflowCaptureSession = {
     capture(scenes: string[], signal?: AbortSignal): Promise<TileflowCaptureResult>;
     captureAll(signal?: AbortSignal): Promise<TileflowCaptureResult>;
     captureDefinitions(scenes: Record<string, TileflowCaptureScene>, signal?: AbortSignal): Promise<TileflowCaptureResult>;
     captureArtifacts(artifacts: TileflowBuildArtifacts, requestedScenes: string[], signal?: AbortSignal): Promise<TileflowCaptureResult>;
+    /** Renders one committed shot. */
+    captureShot(shot: string, options?: TileflowShotCaptureOptions): Promise<TileflowShotCapture>;
+    /** Renders committed shots in name order from one compiled artifact snapshot. */
+    captureShots(shots: string[], options?: TileflowShotCaptureOptions): Promise<TileflowShotCaptureResult>;
+    captureAllShots(options?: TileflowShotCaptureOptions): Promise<TileflowShotCaptureResult>;
     close(): Promise<void>;
 };
 declare function captureTileflowScenes(options: TileflowCaptureOptions): Promise<TileflowCaptureResult>;
+/** Renders one committed shot with a temporary session. */
+declare function captureTileflowShot(options: CaptureTileflowShotOptions): Promise<TileflowShotCapture>;
 declare function createTileflowCaptureSession(options?: CreateTileflowCaptureSessionOptions): TileflowCaptureSession;
 
-type TileflowCaptureErrorCode = 'ABORTED' | 'APPLICATION_ORIGIN_REQUIRED' | 'APPLICATION_ORIGIN_INVALID' | 'APPLICATION_NAVIGATION_FAILED' | 'APPLICATION_TARGET_NOT_FOUND' | 'APPLICATION_TARGET_AMBIGUOUS' | 'APPLICATION_ERROR' | 'BASELINE_INVALID' | 'BROWSER_INSTALL_FAILED' | 'BROWSER_MISSING' | 'BROWSER_START_FAILED' | 'CAPTURE_TIMEOUT' | 'INVALID_PNG' | 'MAP_LOAD_FAILED' | 'RENDER_FAILED' | 'RESOURCE_FAILED' | 'SCENE_NOT_FOUND' | 'SCREENSHOT_FAILED' | 'STYLE_INVALID' | 'SYNTHETIC_ASSET_NOT_FOUND' | 'WORLD_RESOLUTION_FAILED';
-type TileflowCapturePhase = 'style-validation' | 'browser-start' | 'resource-load' | 'map-load' | 'map-idle' | 'screenshot';
+type TileflowCaptureErrorCode = 'ABORTED' | 'APPLICATION_ORIGIN_REQUIRED' | 'APPLICATION_ORIGIN_INVALID' | 'APPLICATION_NAVIGATION_FAILED' | 'APPLICATION_TARGET_NOT_FOUND' | 'APPLICATION_TARGET_AMBIGUOUS' | 'APPLICATION_ERROR' | 'BASELINE_INVALID' | 'BROWSER_INSTALL_FAILED' | 'BROWSER_MISSING' | 'BROWSER_START_FAILED' | 'CAPTURE_TIMEOUT' | 'INVALID_PNG' | 'MAP_LOAD_FAILED' | 'RENDER_FAILED' | 'RESOURCE_FAILED' | 'SCENE_NOT_FOUND' | 'SCREENSHOT_FAILED' | 'SHOT_NOT_FOUND' | 'STYLE_INVALID' | 'SYNTHETIC_ASSET_NOT_FOUND' | 'VIDEO_ENCODE_FAILED' | 'VIDEO_ENCODER_UNAVAILABLE' | 'WORLD_RESOLUTION_FAILED';
+type TileflowCapturePhase = 'style-validation' | 'browser-start' | 'resource-load' | 'map-load' | 'theme-blend' | 'map-idle' | 'screenshot' | 'video-encode';
 type TileflowCaptureDiagnostic = {
     message: string;
     path: string;
@@ -106,11 +174,6 @@ declare class TileflowCaptureError extends Error {
 }
 declare function captureErrorMessage(error: unknown, fallback: string): string;
 
-declare const tileflowSyntheticAssetOrigin = "https://tileflow.local.invalid";
-type TileflowCaptureAsset = TileflowBuildAsset & {
-    url?: string;
-};
-
 declare const tileflowWorldCurrentTileJsonUrl: "https://api.tileflow.dev/tiles/world/tiles.json";
 type FetchTileJson = (input: string, init: {
     cache: 'no-store';
@@ -365,4 +428,4 @@ declare const tileflowVisualReviewLimits: Readonly<{
     maximumAggregatePngBytes: number;
 }>;
 
-export { type CreateTileflowCaptureSessionOptions, type PreparedTileflowCaptureStyle, type TileflowBrowserInstallProgress, type TileflowBrowserLaunchOptions, type TileflowCapture, TileflowCaptureBrowserManager, TileflowCaptureDataInput, type TileflowCaptureDiagnostic, TileflowCaptureError, type TileflowCaptureErrorCode, type TileflowCaptureErrorDetails, type TileflowCaptureOptions, type TileflowCapturePhase, TileflowCaptureReceipt, TileflowCaptureRendererIdentity, type TileflowCaptureResolvedWorldV1, type TileflowCaptureResourceDiagnostic, type TileflowCaptureResourceKind, type TileflowCaptureResult, type TileflowCaptureSession, TileflowCaptureWorldIdentity, TileflowCaptureWorldSession, type TileflowVisualAppearanceDelta, type TileflowVisualAppearanceProfile, type TileflowVisualAppearanceStatistics, type TileflowVisualBaseline, type TileflowVisualComparison, type TileflowVisualComparisonDocument, type TileflowVisualComparisonStatus, type TileflowVisualImageIdentity, type TileflowVisualPaletteColor, type TileflowVisualPixelMetric, type TileflowVisualReferenceAnalysis, type TileflowVisualReferenceAnalysisDocument, type TileflowVisualReferenceAnalysisOptions, type TileflowVisualReferenceAppearance, type TileflowVisualRegion, type TileflowVisualReviewAppearance, type TileflowVisualReviewCapture, type TileflowVisualReviewComparison, type TileflowVisualReviewDefinition, type TileflowVisualReviewDocument, TileflowVisualReviewError, type TileflowVisualReviewFrameIdentity, type TileflowVisualReviewOptions, type TileflowVisualReviewSide, type TileflowVisualReviewStatus, type TileflowVisualRuntimeIdentity, type TileflowVisualSceneIdentity, analyzeTileflowCaptureReference, captureErrorMessage, captureTileflowScenes, compareTileflowCaptureToBaseline, compareTileflowCapturesForReview, createTileflowCaptureBrowserEnvironment, createTileflowCaptureSession, createTileflowVisualComparisonDocument, createTileflowVisualReferenceAnalysisDocument, createTileflowVisualReviewDocument, launchTileflowCaptureBrowser, resolveTileflowApplicationUrl, resolveTileflowCaptureWorldTileJson, serializeTileflowVisualComparison, setupTileflowCaptureBrowser, tileflowCaptureResultSchemaVersion, tileflowSyntheticAssetOrigin, tileflowVisualArtifactLimits, tileflowVisualComparisonSchemaVersion, tileflowVisualEdgeThreshold, tileflowVisualPerceptualThreshold, tileflowVisualReviewLimits, tileflowVisualReviewSchemaVersion, tileflowWorldCurrentTileJsonUrl, validateTileflowVisualReferencePng };
+export { type CaptureTileflowShotOptions, type CreateTileflowCaptureSessionOptions, type PreparedTileflowCaptureStyle, type TileflowBrowserInstallProgress, type TileflowBrowserLaunchOptions, type TileflowCapture, TileflowCaptureBrowserManager, TileflowCaptureDataInput, type TileflowCaptureDiagnostic, TileflowCaptureError, type TileflowCaptureErrorCode, type TileflowCaptureErrorDetails, type TileflowCaptureOptions, type TileflowCapturePhase, TileflowCaptureReceipt, TileflowCaptureRendererIdentity, type TileflowCaptureResolvedWorldV1, type TileflowCaptureResourceDiagnostic, type TileflowCaptureResourceKind, type TileflowCaptureResult, type TileflowCaptureSession, TileflowCaptureWorldIdentity, TileflowCaptureWorldSession, type TileflowShotCapture, type TileflowShotCaptureOptions, type TileflowShotCaptureResult, type TileflowShotFormat, type TileflowShotFrame, TileflowShotReceiptV1, type TileflowShotVideoCodec, type TileflowVisualAppearanceDelta, type TileflowVisualAppearanceProfile, type TileflowVisualAppearanceStatistics, type TileflowVisualBaseline, type TileflowVisualComparison, type TileflowVisualComparisonDocument, type TileflowVisualComparisonStatus, type TileflowVisualImageIdentity, type TileflowVisualPaletteColor, type TileflowVisualPixelMetric, type TileflowVisualReferenceAnalysis, type TileflowVisualReferenceAnalysisDocument, type TileflowVisualReferenceAnalysisOptions, type TileflowVisualReferenceAppearance, type TileflowVisualRegion, type TileflowVisualReviewAppearance, type TileflowVisualReviewCapture, type TileflowVisualReviewComparison, type TileflowVisualReviewDefinition, type TileflowVisualReviewDocument, TileflowVisualReviewError, type TileflowVisualReviewFrameIdentity, type TileflowVisualReviewOptions, type TileflowVisualReviewSide, type TileflowVisualReviewStatus, type TileflowVisualRuntimeIdentity, type TileflowVisualSceneIdentity, analyzeTileflowCaptureReference, captureErrorMessage, captureTileflowScenes, captureTileflowShot, compareTileflowCaptureToBaseline, compareTileflowCapturesForReview, createTileflowCaptureBrowserEnvironment, createTileflowCaptureSession, createTileflowVisualComparisonDocument, createTileflowVisualReferenceAnalysisDocument, createTileflowVisualReviewDocument, launchTileflowCaptureBrowser, resolveTileflowApplicationUrl, resolveTileflowCaptureWorldTileJson, serializeTileflowVisualComparison, setupTileflowCaptureBrowser, tileflowCaptureResultSchemaVersion, tileflowShotFramesSha256, tileflowSyntheticAssetOrigin, tileflowVisualArtifactLimits, tileflowVisualComparisonSchemaVersion, tileflowVisualEdgeThreshold, tileflowVisualPerceptualThreshold, tileflowVisualReviewLimits, tileflowVisualReviewSchemaVersion, tileflowWorldCurrentTileJsonUrl, validateTileflowVisualReferencePng };