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

package/dist/index.js

@@ -2,12 +2,18 @@ import {
   TileflowCaptureError,
   captureErrorMessage,
   createTileflowCaptureReceipt,
+  createTileflowShotReceipt,
   parseTileflowCaptureReceipt,
+  parseTileflowShotReceipt,
   serializeTileflowCaptureReceipt,
+  serializeTileflowShotReceipt,
   tileflowCaptureReceiptLimits,
   tileflowCaptureReceiptSchemaVersion,
-  validateTileflowCaptureReceipt
-} from "./chunk-VNDAYGXY.js";
+  tileflowShotReceiptLimits,
+  tileflowShotReceiptSchemaVersion,
+  validateTileflowCaptureReceipt,
+  validateTileflowShotReceipt
+} from "./chunk-BI5PWIH4.js";
 
 // src/browser.ts
 import { spawn } from "child_process";
@@ -296,11 +302,13 @@ import { resolve } from "path";
 import {
   compareCodeUnits as compareCodeUnits3,
   normalizeTileflowCaptureScene,
+  normalizeTileflowCaptureShot,
   parseResolvedTileflowMap,
   resolveThemeSelection,
-  serializeCanonicalJson,
-  sha256Hex,
-  tileflowCaptureSceneNameSchema
+  serializeCanonicalJson as serializeCanonicalJson2,
+  sha256Hex as sha256Hex2,
+  tileflowCaptureSceneNameSchema,
+  tileflowCaptureShotNameSchema
 } from "@tileflow/core";
 import {
   createTileflowBuildArtifacts,
@@ -341,7 +349,8 @@ var tileflowBrowserModule = `${readFileSync2(
 )}
 globalThis.__tileflowRegisterContourProtocol = registerTileflowContourProtocol;
 globalThis.__tileflowRegisterPmtilesProtocol = registerTileflowPmtilesProtocol;
-globalThis.__tileflowAttachAtmosphere = attachTileflowAtmosphere;`;
+globalThis.__tileflowAttachAtmosphere = attachTileflowAtmosphere;
+globalThis.__tileflowCreateThemeController = createTileflowThemeController;`;
 async function captureStandaloneTileflowScene(input) {
   if (input.scene.target.kind !== "map") {
     throw new TileflowCaptureError(
@@ -349,8 +358,26 @@ async function captureStandaloneTileflowScene(input) {
       "Application scenes require an explicit loopback application origin."
     );
   }
+  assertValidCaptureStyle(input.style, input.scene.map);
+  const { scene, ...pageInput } = input;
+  return withStandaloneTileflowPage({ ...pageInput, viewport: scene.viewport }, async (page) => {
+    await page.load(getTileflowStyleFontFaces(input.style));
+    await page.step("map-idle", "__tileflowCaptureIdle", {
+      camera: scene.camera,
+      mapEventTimeoutMs: page.mapEventTimeoutMs
+    });
+    const png = await page.screenshot();
+    return {
+      height: scene.viewport.height,
+      png,
+      width: scene.viewport.width,
+      ...page.result()
+    };
+  });
+}
+function assertValidCaptureStyle(style, label) {
   try {
-    assertValidTileflowStyle(input.style, input.scene.map);
+    assertValidTileflowStyle(style, label);
   } catch (error) {
     if (error instanceof TileflowStyleValidationError) {
       throw new TileflowCaptureError("STYLE_INVALID", error.message, {
@@ -363,7 +390,10 @@ async function captureStandaloneTileflowScene(input) {
     }
     throw error;
   }
+}
+async function withStandaloneTileflowPage(input, run) {
   const timeoutMs = input.timeoutMs ?? 3e4;
+  const mapEventTimeoutMs = Math.max(1, timeoutMs - 1e3);
   const mapLibreRuntimeUrls = createMapLibreRuntimeUrls(
     resolveMapLibreRuntimeDocumentOrigin(input.style)
   );
@@ -375,6 +405,18 @@ async function captureStandaloneTileflowScene(input) {
     termination = "aborted";
     void context?.close().catch(() => void 0);
   };
+  const stopTimeout = () => {
+    if (timeout) clearTimeout(timeout);
+    timeout = void 0;
+  };
+  const restartTimeout = () => {
+    stopTimeout();
+    timeout = setTimeout(() => {
+      termination = "timeout";
+      void context?.close().catch(() => void 0);
+    }, timeoutMs);
+    timeout.unref?.();
+  };
   if (input.signal?.aborted) {
     throw new TileflowCaptureError("ABORTED", "Tileflow capture was aborted.");
   }
@@ -382,7 +424,7 @@ async function captureStandaloneTileflowScene(input) {
     context = await input.browser.newContext({
       acceptDownloads: false,
       colorScheme: "light",
-      deviceScaleFactor: input.scene.viewport.dpr,
+      deviceScaleFactor: input.viewport.dpr,
       ignoreHTTPSErrors: false,
       javaScriptEnabled: true,
       locale: "en-US",
@@ -390,8 +432,8 @@ async function captureStandaloneTileflowScene(input) {
       serviceWorkers: "block",
       timezoneId: "UTC",
       viewport: {
-        height: input.scene.viewport.height,
-        width: input.scene.viewport.width
+        height: input.viewport.height,
+        width: input.viewport.width
       }
     });
     input.signal?.addEventListener("abort", onAbort, { once: true });
@@ -399,11 +441,7 @@ async function captureStandaloneTileflowScene(input) {
       onAbort();
       throw new TileflowCaptureError("ABORTED", "Tileflow capture was aborted.");
     }
-    timeout = setTimeout(() => {
-      termination = "timeout";
-      void context?.close().catch(() => void 0);
-    }, timeoutMs);
-    timeout.unref?.();
+    restartTimeout();
     const assets = new Map(input.assets.map((asset) => [asset.fileName, asset]));
     const frozenResources = new Map(
       input.assets.filter((asset) => asset.url !== void 0).map((asset) => [asset.url, asset])
@@ -411,7 +449,6 @@ async function captureStandaloneTileflowScene(input) {
     const localTilesets = new Map(
       (input.localTilesets ?? []).map((tileset) => [tileset.fileName, tileset])
     );
-    const fontFaces = getTileflowStyleFontFaces(input.style);
     const remoteOrigins = /* @__PURE__ */ new Set();
     let lineBackgroundGlyphs;
     let syntheticAssetFailure;
@@ -438,7 +475,7 @@ async function captureStandaloneTileflowScene(input) {
         return;
       }
       if (url.origin === mapLibreRuntimeUrls.origin) {
-        const runtime = getMapLibreRuntimeResponse(url.pathname, input.scene.viewport);
+        const runtime = getMapLibreRuntimeResponse(url.pathname, input.viewport);
         if (runtime) {
           await route.fulfill(runtime);
           return;
@@ -540,61 +577,67 @@ globalThis.maplibregl = maplibregl;`,
     );
     await page.addScriptTag({ content: tileflowBrowserModule, type: "module" });
     await page.addScriptTag({ content: renderMapInPageScript });
-    phase = "map-load";
-    const loadResult = await page.evaluate(
-      (renderInput) => {
-        const renderWindow = window;
-        return renderWindow.__tileflowCaptureLoad(renderInput);
-      },
-      {
+    const step = async (stepPhase, name, value) => {
+      phase = stepPhase;
+      const result = await page.evaluate(
+        ({ name: functionName, value: stepInput }) => {
+          const renderWindow = window;
+          return renderWindow[functionName](stepInput);
+        },
+        { name, value }
+      );
+      assertPhaseSucceeded(result, stepPhase, syntheticAssetFailure, resourceFailures, pageFailed);
+    };
+    return await run({
+      page,
+      mapEventTimeoutMs,
+      load: (fontFaces) => step("map-load", "__tileflowCaptureLoad", {
         fontFaces,
-        mapEventTimeoutMs: Math.max(1, timeoutMs - 1e3),
+        mapEventTimeoutMs,
         style: input.style
-      }
-    );
-    assertPhaseSucceeded(loadResult, phase, syntheticAssetFailure, resourceFailures, pageFailed);
-    phase = "map-idle";
-    const idleResult = await page.evaluate(
-      (renderInput) => {
-        const renderWindow = window;
-        return renderWindow.__tileflowCaptureIdle(renderInput);
+      }),
+      step,
+      async screenshot() {
+        phase = "screenshot";
+        let png;
+        try {
+          png = new Uint8Array(
+            await page.locator("#map").screenshot({ animations: "disabled", type: "png" })
+          );
+        } catch (error) {
+          throw new TileflowCaptureError(
+            "SCREENSHOT_FAILED",
+            "Tileflow could not produce the map PNG.",
+            {
+              cause: error,
+              details: { phase }
+            }
+          );
+        }
+        assertPostScreenshotSucceeded(syntheticAssetFailure, resourceFailures, pageFailed);
+        assertPngDimensions(
+          png,
+          input.viewport.width * input.viewport.dpr,
+          input.viewport.height * input.viewport.dpr
+        );
+        return png;
       },
-      {
-        camera: input.scene.camera,
-        mapEventTimeoutMs: Math.max(1, timeoutMs - 1e3)
-      }
-    );
-    assertPhaseSucceeded(idleResult, phase, syntheticAssetFailure, resourceFailures, pageFailed);
-    phase = "screenshot";
-    let png;
-    try {
-      png = new Uint8Array(
-        await page.locator("#map").screenshot({ animations: "disabled", type: "png" })
-      );
-    } catch (error) {
-      throw new TileflowCaptureError(
-        "SCREENSHOT_FAILED",
-        "Tileflow could not produce the map PNG.",
-        {
-          cause: error,
-          details: { phase }
+      restartTimeout,
+      async outside(work) {
+        stopTimeout();
+        try {
+          return await work();
+        } catch (error) {
+          throw new CallerFailure(error);
         }
-      );
-    }
-    assertPostScreenshotSucceeded(syntheticAssetFailure, resourceFailures, pageFailed);
-    assertPngDimensions(
-      png,
-      input.scene.viewport.width * input.scene.viewport.dpr,
-      input.scene.viewport.height * input.scene.viewport.dpr
-    );
-    const warnings = [...remoteOrigins].sort(compareCodeUnits).map((origin) => `Capture requested remote resources from ${origin}.`);
-    return {
-      height: input.scene.viewport.height,
-      networkDependent: remoteOrigins.size > 0,
-      png,
-      warnings,
-      width: input.scene.viewport.width
-    };
+      },
+      result() {
+        return {
+          networkDependent: remoteOrigins.size > 0,
+          warnings: [...remoteOrigins].sort(compareCodeUnits).map((origin) => `Capture requested remote resources from ${origin}.`)
+        };
+      }
+    });
   } catch (error) {
     if (termination === "aborted") {
       throw new TileflowCaptureError("ABORTED", "Tileflow capture was aborted.", { cause: error });
@@ -605,6 +648,9 @@ globalThis.maplibregl = maplibregl;`,
         details: { phase }
       });
     }
+    if (error instanceof CallerFailure) {
+      throw error.error;
+    }
     if (error instanceof TileflowCaptureError) {
       throw error;
     }
@@ -625,18 +671,26 @@ globalThis.maplibregl = maplibregl;`,
         }
       );
     }
-    throw new TileflowCaptureError("MAP_LOAD_FAILED", mapFailureMessage(phase), {
-      cause: error,
-      details: { phase }
-    });
+    throw new TileflowCaptureError(
+      "MAP_LOAD_FAILED",
+      mapFailureMessage(phase === "theme-blend" || phase === "map-load" ? phase : "map-idle"),
+      {
+        cause: error,
+        details: { phase }
+      }
+    );
   } finally {
-    if (timeout) {
-      clearTimeout(timeout);
-    }
+    stopTimeout();
     input.signal?.removeEventListener("abort", onAbort);
     await context?.close().catch(() => void 0);
   }
 }
+var CallerFailure = class {
+  constructor(error) {
+    this.error = error;
+  }
+  error;
+};
 function createMapLibreRuntimeUrls(origin) {
   return Object.freeze({
     css: `${origin}/__runtime/maplibre-gl.css`,
@@ -871,12 +925,15 @@ function resourceLabel(kind) {
 }
 function timeoutMessage(phase) {
   if (phase === "map-load") return "MapLibre did not finish loading before the capture timeout.";
+  if (phase === "theme-blend") return "The theme blend was not ready before the capture timeout.";
   if (phase === "map-idle") return "MapLibre did not become idle before the capture timeout.";
   if (phase === "screenshot") return "PNG production exceeded the capture timeout.";
   return "Tileflow capture exceeded its timeout while creating the browser page.";
 }
 function mapFailureMessage(phase) {
-  return phase === "map-load" ? "MapLibre failed while loading the compiled style." : "MapLibre failed while waiting for the committed camera to become idle.";
+  if (phase === "map-load") return "MapLibre failed while loading the compiled style.";
+  if (phase === "theme-blend") return "Tileflow could not prepare the theme blend.";
+  return "MapLibre failed while waiting for the committed camera to become idle.";
 }
 function safeMapError(value) {
   return value.replace(/[A-Za-z][A-Za-z0-9+.-]*:\/\/\S+/g, "resource").replace(/[^A-Za-z0-9 _.,:'"@+()[\]/=-]/g, "").trim().slice(0, 200);
@@ -951,6 +1008,7 @@ window.__tileflowCaptureLoad = async function(input) {
       style: input.style
     });
     window.__tileflowMap = map;
+    window.__tileflowCaptureStyle = input.style;
     window.__tileflowAttachAtmosphere(map);
     return await waitForMapEvent(map, "load", input.mapEventTimeoutMs);
   } catch (error) {
@@ -1022,6 +1080,58 @@ window.__tileflowCaptureIdle = async function(input) {
   }
 };
 
+// A shot prepares its theme blend once; each frame then only moves the blend position.
+window.__tileflowCapturePrepareBlend = async function(input) {
+  const map = window.__tileflowMap;
+  if (!map) return {status: "failed", reason: "error"};
+
+  try {
+    const controller = window.__tileflowCreateThemeController({
+      initial: {style: window.__tileflowCaptureStyle, theme: input.theme},
+      loadFonts: () => Promise.resolve(),
+      map,
+      timeoutMs: input.mapEventTimeoutMs
+    });
+    const themes = input.themes.map((theme) => ({style: theme.style, theme: theme.theme}));
+    const result = await controller.setBlend({position: input.position, themes});
+    if (result.status !== "applied") {
+      controller.dispose();
+      return {status: "failed", reason: "error", message: String(result.error?.message || "")};
+    }
+    window.__tileflowShotBlend = {controller, themes};
+    return {status: "ok"};
+  } catch (error) {
+    return {status: "failed", reason: "error", message: String(error?.message || error || "")};
+  }
+};
+
+window.__tileflowCaptureFrame = async function(input) {
+  const map = window.__tileflowMap;
+  if (!map) return {status: "failed", reason: "error"};
+
+  try {
+    const blend = window.__tileflowShotBlend;
+    if (blend && input.blendPosition !== undefined) {
+      const result = await blend.controller.setBlend({
+        position: input.blendPosition,
+        themes: blend.themes
+      });
+      if (result.status !== "applied") {
+        return {status: "failed", reason: "error", message: String(result.error?.message || "")};
+      }
+    }
+    applyCamera(map, input.camera);
+    map.triggerRepaint();
+    const result = await waitForMapEvent(map, "idle", input.mapEventTimeoutMs);
+    if (result.status === "failed") return result;
+    await nextFrame();
+    await nextFrame();
+    return {status: "ok"};
+  } catch {
+    return {status: "failed", reason: "error"};
+  }
+};
+
 function applyCamera(mapInstance, camera) {
   if (camera.type === "bounds") {
     mapInstance.fitBounds(
@@ -1509,6 +1619,638 @@ function compareCodeUnits2(left, right) {
   return left < right ? -1 : left > right ? 1 : 0;
 }
 
+// src/shot.ts
+import {
+  serializeCanonicalJson,
+  sha256Hex,
+  tileflowCaptureShotFrames
+} from "@tileflow/core";
+import { getTileflowStyleFontFaces as getTileflowStyleFontFaces2 } from "@tileflow/core/runtime";
+
+// src/shot-encoder.ts
+var encoderDocumentUrl = `${tileflowSyntheticAssetOrigin}/__tileflow/shot-encoder.html`;
+var encoderFrameUrl = `${tileflowSyntheticAssetOrigin}/__tileflow/shot-frame.png`;
+async function openTileflowShotVideoEncoder(input) {
+  const timeoutMs = input.timeoutMs ?? 3e4;
+  let context;
+  const state = {};
+  let pendingPng;
+  const chunks = [];
+  const onAbort = () => {
+    state.termination = "aborted";
+    void context?.close().catch(() => void 0);
+  };
+  const close = async () => {
+    input.signal?.removeEventListener("abort", onAbort);
+    await context?.close().catch(() => void 0);
+  };
+  const run = async (work) => {
+    if (input.signal?.aborted || state.termination === "aborted") {
+      throw new TileflowCaptureError("ABORTED", "Tileflow capture was aborted.");
+    }
+    const timeout = setTimeout(() => {
+      state.termination = "timeout";
+      void context?.close().catch(() => void 0);
+    }, timeoutMs);
+    timeout.unref?.();
+    try {
+      return await work();
+    } catch (error) {
+      const reason = state.termination;
+      if (reason === "aborted") {
+        throw new TileflowCaptureError("ABORTED", "Tileflow capture was aborted.", { cause: error });
+      }
+      if (reason === "timeout") {
+        throw new TileflowCaptureError(
+          "CAPTURE_TIMEOUT",
+          "Video encoding exceeded the capture timeout.",
+          { cause: error, details: { phase: "video-encode" } }
+        );
+      }
+      if (error instanceof TileflowCaptureError) throw error;
+      throw encodeFailed(void 0, error);
+    } finally {
+      clearTimeout(timeout);
+    }
+  };
+  let page;
+  let codec;
+  try {
+    input.signal?.addEventListener("abort", onAbort, { once: true });
+    const opened = await run(async () => {
+      context = await input.browser.newContext({
+        acceptDownloads: false,
+        javaScriptEnabled: true,
+        serviceWorkers: "block",
+        viewport: { height: 64, width: 64 }
+      });
+      await context.route("**/*", async (route) => {
+        const url = route.request().url();
+        if (url === encoderDocumentUrl) {
+          await route.fulfill({
+            body: '<!doctype html><html lang="en"><head><meta charset="utf-8" /></head><body></body></html>',
+            contentType: "text/html; charset=utf-8",
+            status: 200
+          });
+          return;
+        }
+        if (url === encoderFrameUrl && pendingPng) {
+          await route.fulfill({
+            body: Buffer.from(pendingPng),
+            contentType: "image/png",
+            status: 200
+          });
+          return;
+        }
+        await route.abort("blockedbyclient");
+      });
+      await context.routeWebSocket(
+        /.*/,
+        (socket) => socket.close({ code: 1008, reason: "WebSockets are disabled during capture" })
+      );
+      const encoderPage = await context.newPage();
+      await encoderPage.goto(encoderDocumentUrl, { waitUntil: "domcontentloaded" });
+      await encoderPage.addScriptTag({ content: encoderPageScript });
+      const result = await encoderPage.evaluate(
+        (config) => window.__tileflowOpenShotEncoder(config),
+        {
+          bitrate: shotBitrate(input.width, input.height, input.fps),
+          fps: input.fps,
+          frameUrl: encoderFrameUrl,
+          height: input.height,
+          width: input.width
+        }
+      );
+      return { page: encoderPage, result };
+    });
+    page = opened.page;
+    if (opened.result.status === "unsupported" || !opened.result.codec) {
+      throw new TileflowCaptureError(
+        "VIDEO_ENCODER_UNAVAILABLE",
+        `The capture browser cannot encode ${input.width}x${input.height} VP9 or VP8 video. Capture the shot with format "frames" instead.`,
+        { details: { phase: "video-encode" } }
+      );
+    }
+    if (opened.result.status !== "ok") throw encodeFailed(opened.result.message);
+    codec = opened.result.codec;
+  } catch (error) {
+    await close();
+    throw error;
+  }
+  const collect = (result) => {
+    if (result.status !== "ok") throw encodeFailed(result.message);
+    for (const chunk of result.chunks) {
+      chunks.push({
+        data: new Uint8Array(Buffer.from(chunk.data, "base64")),
+        key: chunk.key,
+        timestamp: chunk.timestamp
+      });
+    }
+  };
+  return {
+    codec,
+    async encode(index, png) {
+      await run(async () => {
+        pendingPng = png;
+        try {
+          collect(
+            await page.evaluate(
+              (frame) => window.__tileflowEncodeShotFrame(frame),
+              index
+            )
+          );
+        } finally {
+          pendingPng = void 0;
+        }
+      });
+    },
+    async finish() {
+      await run(
+        async () => collect(
+          await page.evaluate(
+            () => window.__tileflowFinishShotEncoder()
+          )
+        )
+      );
+      return [...chunks];
+    },
+    close
+  };
+}
+function shotBitrate(width, height, fps) {
+  return Math.min(24e6, Math.max(25e4, Math.round(width * height * fps * 0.2)));
+}
+function encodeFailed(message, cause) {
+  const detail = message ? ` ${message.replace(/[^A-Za-z0-9 _.,:'"()[\]/=-]/g, "").trim().slice(0, 200)}` : "";
+  return new TileflowCaptureError("VIDEO_ENCODE_FAILED", `Video encoding failed.${detail}`, {
+    ...cause === void 0 ? {} : { cause },
+    details: { phase: "video-encode" }
+  });
+}
+var encoderPageScript = String.raw`
+let encoder;
+let encoderError;
+let frameDuration = 0;
+let keyInterval = 1;
+let frameUrl = "";
+const pending = [];
+
+window.__tileflowOpenShotEncoder = async function(input) {
+  if (typeof VideoEncoder !== "function" || typeof VideoFrame !== "function") {
+    return {status: "unsupported"};
+  }
+  frameDuration = 1e6 / input.fps;
+  keyInterval = input.fps;
+  frameUrl = input.frameUrl;
+  // VP9 profile 0, 8-bit; VP8 where VP9 is unavailable.
+  for (const [codec, codecString] of [["vp9", "vp09.00.10.08"], ["vp8", "vp8"]]) {
+    const config = {
+      bitrate: input.bitrate,
+      codec: codecString,
+      framerate: input.fps,
+      height: input.height,
+      latencyMode: "quality",
+      width: input.width
+    };
+    let support;
+    try {
+      support = await VideoEncoder.isConfigSupported(config);
+    } catch {
+      continue;
+    }
+    if (!support.supported) continue;
+    try {
+      encoder = new VideoEncoder({
+        error: (error) => {
+          encoderError = String(error?.message || error || "encoder error");
+        },
+        output: (chunk) => {
+          const data = new Uint8Array(chunk.byteLength);
+          chunk.copyTo(data);
+          pending.push({data: toBase64(data), key: chunk.type === "key", timestamp: chunk.timestamp});
+        }
+      });
+      encoder.configure(config);
+      return {codec, status: "ok"};
+    } catch (error) {
+      return {message: String(error?.message || error || ""), status: "failed"};
+    }
+  }
+  return {status: "unsupported"};
+};
+
+window.__tileflowEncodeShotFrame = async function(index) {
+  try {
+    if (encoderError) return {message: encoderError, status: "failed"};
+    const response = await fetch(frameUrl, {cache: "no-store"});
+    if (!response.ok) return {message: "frame unavailable", status: "failed"};
+    const bitmap = await createImageBitmap(await response.blob(), {
+      colorSpaceConversion: "none",
+      premultiplyAlpha: "none"
+    });
+    const frame = new VideoFrame(bitmap, {
+      duration: Math.round(frameDuration),
+      timestamp: Math.round(index * frameDuration)
+    });
+    bitmap.close();
+    try {
+      encoder.encode(frame, {keyFrame: index % keyInterval === 0});
+    } finally {
+      frame.close();
+    }
+    while (encoder.encodeQueueSize > 2 && !encoderError) {
+      await new Promise((resolve) => encoder.addEventListener("dequeue", resolve, {once: true}));
+    }
+    if (encoderError) return {message: encoderError, status: "failed"};
+    return {chunks: pending.splice(0), status: "ok"};
+  } catch (error) {
+    return {message: String(error?.message || error || ""), status: "failed"};
+  }
+};
+
+window.__tileflowFinishShotEncoder = async function() {
+  try {
+    await encoder.flush();
+    encoder.close();
+    if (encoderError) return {message: encoderError, status: "failed"};
+    return {chunks: pending.splice(0), status: "ok"};
+  } catch (error) {
+    return {message: String(encoderError || error?.message || error || ""), status: "failed"};
+  }
+};
+
+function toBase64(bytes) {
+  let text = "";
+  for (let offset = 0; offset < bytes.length; offset += 0x8000) {
+    text += String.fromCharCode.apply(null, bytes.subarray(offset, offset + 0x8000));
+  }
+  return btoa(text);
+}
+`;
+
+// src/webm.ts
+var tileflowWebmElementIds = Object.freeze({
+  ebml: 440786851,
+  ebmlVersion: 17030,
+  ebmlReadVersion: 17143,
+  ebmlMaxIdLength: 17138,
+  ebmlMaxSizeLength: 17139,
+  docType: 17026,
+  docTypeVersion: 17031,
+  docTypeReadVersion: 17029,
+  segment: 408125543,
+  seekHead: 290298740,
+  seek: 19899,
+  seekId: 21419,
+  seekPosition: 21420,
+  info: 357149030,
+  timestampScale: 2807729,
+  duration: 17545,
+  muxingApp: 19840,
+  writingApp: 22337,
+  tracks: 374648427,
+  trackEntry: 174,
+  trackNumber: 215,
+  trackUid: 29637,
+  trackType: 131,
+  flagLacing: 156,
+  defaultDuration: 2352003,
+  codecId: 134,
+  video: 224,
+  pixelWidth: 176,
+  pixelHeight: 186,
+  cluster: 524531317,
+  timestamp: 231,
+  simpleBlock: 163,
+  cues: 475249515,
+  cuePoint: 187,
+  cueTime: 179,
+  cueTrackPositions: 183,
+  cueTrack: 247,
+  cueClusterPosition: 241
+});
+var id = tileflowWebmElementIds;
+var maximumRelativeTimestamp = 32767;
+function writeTileflowWebm(input) {
+  if (input.chunks.length === 0 || !input.chunks[0].key) {
+    throw new RangeError("A WebM video must start with a key frame.");
+  }
+  const header = element(id.ebml, [
+    unsignedElement(id.ebmlVersion, 1),
+    unsignedElement(id.ebmlReadVersion, 1),
+    unsignedElement(id.ebmlMaxIdLength, 4),
+    unsignedElement(id.ebmlMaxSizeLength, 8),
+    stringElement(id.docType, "webm"),
+    unsignedElement(id.docTypeVersion, 4),
+    unsignedElement(id.docTypeReadVersion, 2)
+  ]);
+  const info = element(id.info, [
+    unsignedElement(id.timestampScale, 1e6),
+    floatElement(id.duration, input.durationMs),
+    stringElement(id.muxingApp, "Tileflow"),
+    stringElement(id.writingApp, "Tileflow")
+  ]);
+  const tracks = element(id.tracks, [
+    element(id.trackEntry, [
+      unsignedElement(id.trackNumber, 1),
+      unsignedElement(id.trackUid, 1),
+      unsignedElement(id.trackType, 1),
+      unsignedElement(id.flagLacing, 0),
+      unsignedElement(id.defaultDuration, Math.round(1e9 / input.fps)),
+      stringElement(id.codecId, input.codec === "vp9" ? "V_VP9" : "V_VP8"),
+      element(id.video, [
+        unsignedElement(id.pixelWidth, input.width),
+        unsignedElement(id.pixelHeight, input.height)
+      ])
+    ])
+  ]);
+  const clusters = [];
+  let current;
+  const closeCluster = () => {
+    if (!current) return;
+    clusters.push({
+      bytes: element(id.cluster, [
+        unsignedElement(id.timestamp, current.timestamp),
+        ...current.blocks
+      ]),
+      timestamp: current.timestamp
+    });
+    current = void 0;
+  };
+  for (const chunk of input.chunks) {
+    const timestamp = Math.round(chunk.timestamp / 1e3);
+    if (!current || chunk.key || timestamp - current.timestamp > maximumRelativeTimestamp) {
+      closeCluster();
+      current = { blocks: [], timestamp };
+    }
+    current.blocks.push(simpleBlock(timestamp - current.timestamp, chunk.key, chunk.data));
+  }
+  closeCluster();
+  const seekHeadSize = seekHead([0, 0, 0]).byteLength;
+  const infoPosition = seekHeadSize;
+  const tracksPosition = infoPosition + info.byteLength;
+  let position = tracksPosition + tracks.byteLength;
+  const cuePoints = [];
+  for (const cluster of clusters) {
+    cuePoints.push(
+      element(id.cuePoint, [
+        unsignedElement(id.cueTime, cluster.timestamp),
+        element(id.cueTrackPositions, [
+          unsignedElement(id.cueTrack, 1),
+          unsignedElement(id.cueClusterPosition, position)
+        ])
+      ])
+    );
+    position += cluster.bytes.byteLength;
+  }
+  const cuesPosition = position;
+  const segment = element(id.segment, [
+    seekHead([infoPosition, tracksPosition, cuesPosition]),
+    info,
+    tracks,
+    ...clusters.map((cluster) => cluster.bytes),
+    element(id.cues, cuePoints)
+  ]);
+  return concat([header, segment]);
+}
+function seekHead([info, tracks, cues]) {
+  const seek = (target, offset) => element(id.seek, [
+    binaryElement(id.seekId, elementIdBytes(target)),
+    element(id.seekPosition, [fixedUnsigned(offset, 8)])
+  ]);
+  return element(id.seekHead, [seek(id.info, info), seek(id.tracks, tracks), seek(id.cues, cues)]);
+}
+function simpleBlock(relativeTimestamp, key, data) {
+  const header = new Uint8Array(4);
+  header[0] = 129;
+  new DataView(header.buffer).setInt16(1, relativeTimestamp);
+  header[3] = key ? 128 : 0;
+  return binaryElement(id.simpleBlock, concat([header, data]));
+}
+function element(elementId, children) {
+  return binaryElement(elementId, concat(children));
+}
+function binaryElement(elementId, data) {
+  return concat([elementIdBytes(elementId), sizeBytes(data.byteLength), data]);
+}
+function unsignedElement(elementId, value) {
+  return binaryElement(elementId, minimalUnsigned(value));
+}
+function stringElement(elementId, value) {
+  return binaryElement(elementId, new TextEncoder().encode(value));
+}
+function floatElement(elementId, value) {
+  const bytes = new Uint8Array(8);
+  new DataView(bytes.buffer).setFloat64(0, value);
+  return binaryElement(elementId, bytes);
+}
+function elementIdBytes(elementId) {
+  const length = elementId >= 16777216 ? 4 : elementId >= 65536 ? 3 : elementId >= 256 ? 2 : 1;
+  return fixedUnsigned(elementId, length);
+}
+function sizeBytes(size) {
+  if (!Number.isSafeInteger(size) || size < 0) throw new RangeError("Invalid EBML element size.");
+  let length = 1;
+  while (length < 8 && size >= 2 ** (7 * length) - 1) length += 1;
+  if (size >= 2 ** (7 * length) - 1) throw new RangeError("EBML element is too large.");
+  const bytes = fixedUnsigned(size, length);
+  bytes[0] = (bytes[0] ?? 0) | 1 << 8 - length;
+  return bytes;
+}
+function minimalUnsigned(value) {
+  let length = 1;
+  while (length < 8 && value >= 2 ** (8 * length)) length += 1;
+  return fixedUnsigned(value, length);
+}
+function fixedUnsigned(value, length) {
+  if (!Number.isSafeInteger(value) || value < 0) throw new RangeError("Invalid EBML integer.");
+  const bytes = new Uint8Array(length);
+  let remaining = value;
+  for (let index = length - 1; index >= 0; index -= 1) {
+    bytes[index] = remaining % 256;
+    remaining = Math.floor(remaining / 256);
+  }
+  return bytes;
+}
+function concat(parts) {
+  const bytes = new Uint8Array(parts.reduce((total, part) => total + part.byteLength, 0));
+  let offset = 0;
+  for (const part of parts) {
+    bytes.set(part, offset);
+    offset += part.byteLength;
+  }
+  return bytes;
+}
+
+// src/shot.ts
+async function renderTileflowShot(input) {
+  const { shot } = input;
+  const width = shot.viewport.width * shot.viewport.dpr;
+  const height = shot.viewport.height * shot.viewport.dpr;
+  let encoder;
+  try {
+    if (input.format === "webm") {
+      encoder = await openTileflowShotVideoEncoder({
+        browser: input.browser,
+        fps: shot.fps,
+        height,
+        ...input.signal ? { signal: input.signal } : {},
+        ...input.timeoutMs === void 0 ? {} : { timeoutMs: input.timeoutMs },
+        width
+      });
+    }
+    const frameSha256s = [];
+    const rendered = await captureStandaloneTileflowShot({
+      ...input,
+      onFrame: async ({ index, png }) => {
+        const sha2562 = await sha256Hex(png);
+        frameSha256s.push(sha2562);
+        await input.onFrame?.({ index, png, sha256: sha2562, shot: input.name });
+        await encoder?.encode(index, png);
+      }
+    });
+    const durationMs = shot.keyframes.at(-1).at;
+    const framesSha256 = await tileflowShotFramesSha256(frameSha256s);
+    const video = encoder ? writeTileflowWebm({
+      chunks: await encoder.finish(),
+      codec: encoder.codec,
+      durationMs: rendered.frameCount * 1e3 / shot.fps,
+      fps: shot.fps,
+      height,
+      width
+    }) : void 0;
+    const blendThemes = shot.keyframes[0]?.blend?.themes;
+    const styleHashes = /* @__PURE__ */ new Map();
+    for (const theme of /* @__PURE__ */ new Set([shot.theme, ...blendThemes ?? []])) {
+      styleHashes.set(theme, await sha256Hex(serializeCanonicalJson(input.styles[theme])));
+    }
+    const [sha256, shotSha256] = await Promise.all([
+      video ? sha256Hex(video) : Promise.resolve(framesSha256),
+      sha256Hex(serializeCanonicalJson(shot))
+    ]);
+    const styleSha256 = styleHashes.get(shot.theme);
+    const receipt = createTileflowShotReceipt({
+      ...blendThemes ? { blend: blendThemes.map((name) => ({ name, styleSha256: styleHashes.get(name) })) } : {},
+      data: input.data,
+      dpr: shot.viewport.dpr,
+      durationMs,
+      fps: shot.fps,
+      frameCount: rendered.frameCount,
+      framesSha256,
+      height: rendered.height,
+      map: shot.map,
+      networkDependent: rendered.networkDependent,
+      output: encoder ? { codec: encoder.codec, kind: "webm", sha256 } : { kind: "frames", sha256 },
+      renderer: input.renderer,
+      shot: input.name,
+      shotSha256,
+      styleSha256,
+      theme: shot.theme,
+      width: rendered.width
+    });
+    return {
+      shot: input.name,
+      map: shot.map,
+      theme: shot.theme,
+      format: input.format,
+      ...video ? { video } : {},
+      ...encoder ? { codec: encoder.codec } : {},
+      sha256,
+      framesSha256,
+      frameSha256s,
+      shotSha256,
+      styleSha256,
+      fps: shot.fps,
+      frameCount: rendered.frameCount,
+      durationMs,
+      width: rendered.width,
+      height: rendered.height,
+      dpr: shot.viewport.dpr,
+      networkDependent: rendered.networkDependent,
+      renderer: input.renderer,
+      receipt,
+      warnings: rendered.warnings
+    };
+  } finally {
+    await encoder?.close();
+  }
+}
+function tileflowShotFramesSha256(frameSha256s) {
+  return sha256Hex(frameSha256s.map((sha256) => `${sha256}
+`).join(""));
+}
+async function captureStandaloneTileflowShot(input) {
+  const { shot } = input;
+  const frames = tileflowCaptureShotFrames(shot);
+  const blendThemes = shot.keyframes[0]?.blend?.themes;
+  const themes = [.../* @__PURE__ */ new Set([shot.theme, ...blendThemes ?? []])];
+  const styles = themes.map((theme) => {
+    const style = Object.hasOwn(input.styles, theme) ? input.styles[theme] : void 0;
+    if (!style) {
+      throw new TileflowCaptureError(
+        "SHOT_NOT_FOUND",
+        `Shot theme "${theme}" has no compiled style on map "${shot.map}".`
+      );
+    }
+    assertValidCaptureStyle(style, `${shot.map}/${theme}`);
+    return [theme, pageStyle(style)];
+  });
+  const pageStyles = Object.fromEntries(styles);
+  return withStandaloneTileflowPage(
+    {
+      assets: input.assets,
+      browser: input.browser,
+      ...input.glyphCacheDirectory ? { glyphCacheDirectory: input.glyphCacheDirectory } : {},
+      ...input.lineBackgroundGlyphs ? { lineBackgroundGlyphs: input.lineBackgroundGlyphs } : {},
+      ...input.localTilesets ? { localTilesets: input.localTilesets } : {},
+      ...input.signal ? { signal: input.signal } : {},
+      style: pageStyles[shot.theme],
+      ...input.timeoutMs === void 0 ? {} : { timeoutMs: input.timeoutMs },
+      viewport: shot.viewport
+    },
+    async (page) => {
+      await page.load(uniqueFontFaces(styles.map(([, style]) => style)));
+      if (blendThemes) {
+        page.restartTimeout();
+        await page.step("theme-blend", "__tileflowCapturePrepareBlend", {
+          mapEventTimeoutMs: page.mapEventTimeoutMs,
+          position: frames[0]?.blendPosition ?? 0,
+          theme: shot.theme,
+          themes: blendThemes.map((theme) => ({ style: pageStyles[theme], theme }))
+        });
+      }
+      for (const frame of frames) {
+        page.restartTimeout();
+        await page.step("map-idle", "__tileflowCaptureFrame", {
+          blendPosition: frame.blendPosition,
+          camera: frame.camera,
+          mapEventTimeoutMs: page.mapEventTimeoutMs
+        });
+        const png = await page.screenshot();
+        await page.outside(async () => input.onFrame({ index: frame.index, png }));
+      }
+      return {
+        frameCount: frames.length,
+        height: shot.viewport.height,
+        width: shot.viewport.width,
+        ...page.result()
+      };
+    }
+  );
+}
+function pageStyle(style) {
+  return { ...style, transition: { delay: 0, duration: 0 } };
+}
+function uniqueFontFaces(styles) {
+  const faces = /* @__PURE__ */ new Map();
+  for (const style of styles) {
+    for (const face of getTileflowStyleFontFaces2(style) ?? []) {
+      faces.set(JSON.stringify(face), face);
+    }
+  }
+  return [...faces.values()];
+}
+
 // src/world.ts
 import { createHash } from "crypto";
 import {
@@ -1785,6 +2527,18 @@ async function captureTileflowScenes(options) {
     await session.close();
   }
 }
+async function captureTileflowShot(options) {
+  const { format, onFrame, shot, ...sessionOptions } = options;
+  const session = createTileflowCaptureSession(sessionOptions);
+  try {
+    return await session.captureShot(shot, {
+      ...format ? { format } : {},
+      ...onFrame ? { onFrame } : {}
+    });
+  } finally {
+    await session.close();
+  }
+}
 function createTileflowCaptureSession(options = {}) {
   return new TileflowCaptureSessionImpl(options);
 }
@@ -1914,9 +2668,9 @@ var TileflowCaptureSessionImpl = class {
         timeoutMs: this.#options.timeoutMs
       });
       const [sha256, sceneSha256, styleSha256] = await Promise.all([
-        sha256Hex(rendered.png),
-        sha256Hex(serializeCanonicalJson(scene)),
-        sha256Hex(serializeCanonicalJson(style))
+        sha256Hex2(rendered.png),
+        sha256Hex2(serializeCanonicalJson2(scene)),
+        sha256Hex2(serializeCanonicalJson2(style))
       ]);
       const target = scene.target.kind;
       const receipt = createTileflowCaptureReceipt({
@@ -1935,6 +2689,7 @@ var TileflowCaptureSessionImpl = class {
         width: rendered.width
       });
       captures.push({
+        definition: scene,
         scene: sceneName,
         map: scene.map,
         theme: scene.theme,
@@ -1954,6 +2709,98 @@ var TileflowCaptureSessionImpl = class {
     }
     return { schemaVersion: tileflowCaptureResultSchemaVersion, captures };
   }
+  async captureShot(shot, options = {}) {
+    const result = await this.captureShots([shot], options);
+    return result.shots[0];
+  }
+  async captureAllShots(options = {}) {
+    this.#assertOpen();
+    const artifacts = await this.#createArtifacts();
+    try {
+      return await this.#captureShotArtifacts(
+        artifacts,
+        Object.keys(artifacts.project.shots ?? {}),
+        options
+      );
+    } finally {
+      await disposeCaptureArtifacts(artifacts);
+    }
+  }
+  async captureShots(shots, options = {}) {
+    this.#assertOpen();
+    const artifacts = await this.#createArtifacts();
+    try {
+      return await this.#captureShotArtifacts(artifacts, shots, options);
+    } finally {
+      await disposeCaptureArtifacts(artifacts);
+    }
+  }
+  async #captureShotArtifacts(artifacts, requestedShots, options) {
+    const signal = options.signal ?? this.#options.signal;
+    const format = options.format ?? "webm";
+    if (format !== "webm" && format !== "frames") {
+      throw new TypeError('Expected shot format "webm" or "frames".');
+    }
+    const shotNames = selectTileflowCaptureShotNames(artifacts, requestedShots);
+    const resolved = [];
+    const preparedStyles = /* @__PURE__ */ new Map();
+    for (const name of shotNames) {
+      const shot = normalizeShot(artifacts, name);
+      const themes = [.../* @__PURE__ */ new Set([shot.theme, ...shot.keyframes[0]?.blend?.themes ?? []])];
+      const styles = {};
+      const prepared = [];
+      for (const theme of themes) {
+        const styleKey = `${shot.map}/${theme}`;
+        let preparedStyle = preparedStyles.get(styleKey);
+        if (!preparedStyle) {
+          const style = artifacts.styles[shot.map]?.[theme];
+          if (!style) {
+            throw new TileflowCaptureError(
+              "SHOT_NOT_FOUND",
+              `Shot "${name}" references unavailable theme "${theme}" on map "${shot.map}".`
+            );
+          }
+          preparedStyle = await this.#worldSession.prepare(style, signal);
+          try {
+            assertValidTileflowStyle2(preparedStyle.style, styleKey);
+          } catch (error) {
+            throwCaptureStyleValidationError(error);
+          }
+          preparedStyles.set(styleKey, preparedStyle);
+        }
+        styles[theme] = preparedStyle.style;
+        prepared.push(preparedStyle);
+      }
+      resolved.push({ name, prepared, shot, styles });
+    }
+    throwIfAborted2(signal);
+    const browser = await this.#browserManager.getBrowser(signal);
+    const renderer = createTileflowCaptureRendererIdentity(browser);
+    const shots = [];
+    for (const { name, prepared, shot, styles } of resolved) {
+      throwIfAborted2(signal);
+      const capture = await renderTileflowShot({
+        assets: [...artifacts.assets, ...prepared.flatMap((style) => style.assets ?? [])],
+        browser,
+        data: prepared[0].data,
+        format,
+        ...artifacts.localTilesets ? { localTilesets: artifacts.localTilesets } : {},
+        ...artifacts.lineBackgroundGlyphs ? {
+          glyphCacheDirectory: resolve(this.#options.cwd ?? process.cwd()),
+          lineBackgroundGlyphs: artifacts.lineBackgroundGlyphs
+        } : {},
+        name,
+        ...options.onFrame ? { onFrame: options.onFrame } : {},
+        renderer,
+        shot,
+        ...signal ? { signal } : {},
+        styles,
+        ...this.#options.timeoutMs === void 0 ? {} : { timeoutMs: this.#options.timeoutMs }
+      });
+      shots.push({ ...capture, warnings: [...capture.warnings].sort(compareCodeUnits3) });
+    }
+    return { schemaVersion: tileflowCaptureResultSchemaVersion, shots };
+  }
   async close() {
     if (this.#closed) {
       return;
@@ -2042,6 +2889,53 @@ function selectTileflowCaptureSceneNames(artifacts, requestedScenes) {
   }
   return sceneNames;
 }
+function selectTileflowCaptureShotNames(artifacts, requestedShots) {
+  const availableShots = Object.keys(artifacts.project.shots ?? {}).filter((shotName) => tileflowCaptureShotNameSchema.safeParse(shotName).success).sort(compareCodeUnits3);
+  const shotNames = [...new Set(requestedShots)].sort(compareCodeUnits3);
+  if (shotNames.length === 0) {
+    throw new TileflowCaptureError(
+      "SHOT_NOT_FOUND",
+      "Select at least one capture shot or request every configured shot explicitly."
+    );
+  }
+  for (const shotName of shotNames) {
+    if (!tileflowCaptureShotNameSchema.safeParse(shotName).success) {
+      throw new TileflowCaptureError("SHOT_NOT_FOUND", "Expected a portable Tileflow shot name.");
+    }
+    if (!Object.hasOwn(artifacts.project.shots ?? {}, shotName)) {
+      const suffix = availableShots.length > 0 ? ` Available shots: ${availableShots.join(", ")}.` : " The config defines no capture shots.";
+      throw new TileflowCaptureError(
+        "SHOT_NOT_FOUND",
+        `Unknown Tileflow capture shot "${shotName}".${suffix}`
+      );
+    }
+  }
+  return shotNames;
+}
+function normalizeShot(artifacts, shotName) {
+  const shot = artifacts.project.shots[shotName];
+  const normalized = normalizeTileflowCaptureShot(shot);
+  const resolvedMap = artifacts.project.maps[normalized.map];
+  if (!resolvedMap) {
+    throw new TileflowCaptureError(
+      "SHOT_NOT_FOUND",
+      `Shot "${shotName}" references unavailable map "${normalized.map}".`
+    );
+  }
+  const map = parseResolvedTileflowMap(resolvedMap);
+  for (const theme of [normalized.theme, ...normalized.keyframes[0]?.blend?.themes ?? []]) {
+    try {
+      resolveThemeSelection(map, theme);
+    } catch (error) {
+      throw new TileflowCaptureError(
+        "SHOT_NOT_FOUND",
+        `Shot "${shotName}" has an invalid theme: ${error instanceof Error ? error.message : "unknown theme"}`,
+        { cause: error }
+      );
+    }
+  }
+  return normalized;
+}
 function normalizeScene(artifacts, sceneName) {
   const scene = Object.hasOwn(artifacts.project.scenes ?? {}, sceneName) ? artifacts.project.scenes?.[sceneName] : void 0;
   if (!scene) {
@@ -2092,8 +2986,8 @@ import { types as nodeUtilTypes } from "util";
 import { PNG } from "pngjs";
 import {
   compareCodeUnits as compareCodeUnits4,
-  serializeCanonicalJson as serializeCanonicalJson2,
-  sha256Hex as sha256Hex2,
+  serializeCanonicalJson as serializeCanonicalJson3,
+  sha256Hex as sha256Hex3,
   tileflowCaptureSceneLimits as tileflowCaptureSceneLimits2
 } from "@tileflow/core";
 var tileflowVisualComparisonSchemaVersion = 1;
@@ -2201,7 +3095,7 @@ async function analyzeTileflowCaptureReference(actualCapture, referencePng, opti
     target: receipt.scene.target,
     dimensionsMatch,
     reference: {
-      sha256: await sha256Hex2(referencePng),
+      sha256: await sha256Hex3(referencePng),
       physicalWidth: referenceImage.width,
       physicalHeight: referenceImage.height,
       palette: createQuantizedPalette(referenceImage.data)
@@ -2414,7 +3308,7 @@ function createTileflowVisualComparisonDocument(comparison) {
   return document;
 }
 function serializeTileflowVisualComparison(comparison) {
-  return `${serializeCanonicalJson2(createTileflowVisualComparisonDocument(comparison))}
+  return `${serializeCanonicalJson3(createTileflowVisualComparisonDocument(comparison))}
 `;
 }
 function imageIdentity(receipt) {
@@ -2436,7 +3330,7 @@ async function validatePngAgainstReceipt(png, receipt, role) {
   if (image.width !== receipt.image.physicalWidth || image.height !== receipt.image.physicalHeight) {
     throw invalidBaseline(`The ${role} PNG dimensions do not match its receipt.`);
   }
-  if (await sha256Hex2(png) !== receipt.image.sha256) {
+  if (await sha256Hex3(png) !== receipt.image.sha256) {
     throw invalidBaseline(`The ${role} PNG hash does not match its receipt.`);
   }
   return image;
@@ -2758,7 +3652,7 @@ function pixelMetric(changedPixels, totalPixels) {
   return { changedPixels, totalPixels, ratio: changedPixels / totalPixels };
 }
 function sameSceneIdentity(baseline, actual) {
-  return baseline.scene.name === actual.scene.name && baseline.scene.map === actual.scene.map && baseline.scene.theme === actual.scene.theme && baseline.scene.target === actual.scene.target && baseline.scene.sha256 === actual.scene.sha256 && serializeCanonicalJson2(baseline.data) === serializeCanonicalJson2(actual.data);
+  return baseline.scene.name === actual.scene.name && baseline.scene.map === actual.scene.map && baseline.scene.theme === actual.scene.theme && baseline.scene.target === actual.scene.target && baseline.scene.sha256 === actual.scene.sha256 && serializeCanonicalJson3(baseline.data) === serializeCanonicalJson3(actual.data);
 }
 function sameRuntimeIdentity(baseline, actual) {
   return baseline.renderer.tileflow === actual.renderer.tileflow && baseline.renderer.maplibre === actual.renderer.maplibre && baseline.renderer.playwright === actual.renderer.playwright && baseline.renderer.chromiumRevision === actual.renderer.chromiumRevision && baseline.renderer.chromiumVersion === actual.renderer.chromiumVersion && baseline.platform.os === actual.platform.os && baseline.platform.architecture === actual.platform.architecture;
@@ -2781,8 +3675,8 @@ function invalidBaseline(message, cause) {
 import { types as nodeUtilTypes2 } from "util";
 import {
   normalizeTileflowCaptureScene as normalizeTileflowCaptureScene2,
-  serializeCanonicalJson as serializeCanonicalJson3,
-  sha256Hex as sha256Hex3
+  serializeCanonicalJson as serializeCanonicalJson4,
+  sha256Hex as sha256Hex4
 } from "@tileflow/core";
 var tileflowVisualReviewSchemaVersion = 1;
 var TileflowVisualReviewError = class extends Error {
@@ -2876,7 +3770,9 @@ function snapshotReviewInputs(leftInput, rightInput) {
 }
 function inspectReviewInput(input, role) {
   const wrapper = readPlainDataRecord(input, `${role} review input`, ["capture", "definition"]);
-  const capture = readPlainDataRecord(wrapper.capture, `${role} capture`, reviewCaptureKeys);
+  const capture = readPlainDataRecord(wrapper.capture, `${role} capture`, reviewCaptureKeys, [
+    "definition"
+  ]);
   const definition = clonePlainDataValue(
     wrapper.definition,
     `${role} definition`
@@ -2893,6 +3789,12 @@ function inspectReviewInput(input, role) {
   const png = requireReviewPng(capture.png, role);
   return {
     capture: {
+      ...capture.definition === void 0 ? {} : {
+        definition: clonePlainDataValue(
+          capture.definition,
+          `${role} capture.definition`
+        )
+      },
       scene: capture.scene,
       map: capture.map,
       theme: capture.theme,
@@ -3047,7 +3949,7 @@ function clonePlainDataValue(value, path, state = {
     state.ancestors.delete(value);
   }
 }
-function readPlainDataRecord(value, path, expectedKeys) {
+function readPlainDataRecord(value, path, expectedKeys, optionalKeys = []) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     throw invalidReview(`The ${path} must be a plain data object.`);
   }
@@ -3071,7 +3973,7 @@ function readPlainDataRecord(value, path, expectedKeys) {
     entries.push([key, descriptor.value]);
   }
   if (expectedKeys) {
-    const actual = entries.map(([key]) => key).sort(compareCodeUnits5);
+    const actual = entries.map(([key]) => key).filter((key) => !optionalKeys.includes(key)).sort(compareCodeUnits5);
     const wanted = [...expectedKeys].sort(compareCodeUnits5);
     if (actual.length !== wanted.length || actual.some((key, index) => key !== wanted[index])) {
       throw invalidReview(`The ${path} contains missing or unsupported fields.`);
@@ -3090,6 +3992,9 @@ async function validateReviewCapture(input, role) {
   if (!sameCanonicalValue(input.definition, definition)) {
     throw invalidReview(`The ${role} review definition must be the exact normalized shape.`);
   }
+  if (input.capture.definition !== void 0 && !sameCanonicalValue(input.capture.definition, definition)) {
+    throw invalidReview(`The ${role} retained capture definition does not match its review.`);
+  }
   let parsedReceipt;
   try {
     parsedReceipt = validateTileflowCaptureReceipt(input.capture.receipt);
@@ -3107,7 +4012,7 @@ async function validateReviewCapture(input, role) {
   if (input.capture.scene !== receipt.scene.name || input.capture.map !== receipt.scene.map || input.capture.theme !== receipt.scene.theme || input.capture.target !== receipt.scene.target || input.capture.sha256 !== receipt.image.sha256 || input.capture.sceneSha256 !== receipt.scene.sha256 || input.capture.styleSha256 !== receipt.style.sha256 || input.capture.width !== receipt.image.cssWidth || input.capture.height !== receipt.image.cssHeight || input.capture.dpr !== receipt.image.dpr || input.capture.networkDependent !== receipt.networkDependent || !sameCanonicalValue(input.capture.renderer, receipt.renderer)) {
     throw invalidReview(`The ${role} capture metadata does not match its receipt.`);
   }
-  const definitionSha256 = await sha256Hex3(serializeCanonicalJson3(definition));
+  const definitionSha256 = await sha256Hex4(serializeCanonicalJson4(definition));
   if (definitionSha256 !== receipt.scene.sha256) {
     throw invalidReview(`The ${role} review definition does not match its capture receipt.`);
   }
@@ -3193,7 +4098,7 @@ function reviewWarnings(status, left, right) {
   return [...new Set(warnings)].sort(compareCodeUnits5);
 }
 function sameCanonicalValue(left, right) {
-  return serializeCanonicalJson3(left) === serializeCanonicalJson3(right);
+  return serializeCanonicalJson4(left) === serializeCanonicalJson4(right);
 }
 function compareCodeUnits5(left, right) {
   return left < right ? -1 : left > right ? 1 : 0;
@@ -3209,26 +4114,33 @@ export {
   analyzeTileflowCaptureReference,
   captureErrorMessage,
   captureTileflowScenes,
+  captureTileflowShot,
   compareTileflowCaptureToBaseline,
   compareTileflowCapturesForReview,
   createTileflowCaptureBrowserEnvironment,
   createTileflowCaptureReceipt,
   createTileflowCaptureRendererIdentity,
   createTileflowCaptureSession,
+  createTileflowShotReceipt,
   createTileflowVisualComparisonDocument,
   createTileflowVisualReferenceAnalysisDocument,
   createTileflowVisualReviewDocument,
   launchTileflowCaptureBrowser,
   parseTileflowCaptureReceipt,
+  parseTileflowShotReceipt,
   resolveTileflowApplicationUrl,
   resolveTileflowCaptureWorldTileJson,
   serializeTileflowCaptureReceipt,
+  serializeTileflowShotReceipt,
   serializeTileflowVisualComparison,
   setupTileflowCaptureBrowser,
   tileflowCaptureReceiptLimits,
   tileflowCaptureReceiptSchemaVersion,
   tileflowCaptureResultSchemaVersion,
   tileflowCaptureRuntime,
+  tileflowShotFramesSha256,
+  tileflowShotReceiptLimits,
+  tileflowShotReceiptSchemaVersion,
   tileflowSyntheticAssetOrigin,
   tileflowVisualArtifactLimits,
   tileflowVisualComparisonSchemaVersion,
@@ -3238,5 +4150,6 @@ export {
   tileflowVisualReviewSchemaVersion,
   tileflowWorldCurrentTileJsonUrl,
   validateTileflowCaptureReceipt,
+  validateTileflowShotReceipt,
   validateTileflowVisualReferencePng
 };