@tileflow/capture 0.1.0-alpha.16 → 0.1.0-alpha.18

package/dist/index.js

@@ -1,68 +1,18 @@
+import {
+  TileflowCaptureError,
+  captureErrorMessage,
+  createTileflowCaptureReceipt,
+  parseTileflowCaptureReceipt,
+  serializeTileflowCaptureReceipt,
+  tileflowCaptureReceiptLimits,
+  tileflowCaptureReceiptSchemaVersion,
+  validateTileflowCaptureReceipt
+} from "./chunk-BSTB4FN6.js";
+
 // src/browser.ts
 import { spawn } from "child_process";
 import { chromium } from "playwright";
 
-// src/errors.ts
-var TileflowCaptureError = class extends Error {
-  code;
-  details;
-  constructor(code, message, options) {
-    super(message, options?.cause === void 0 ? void 0 : { cause: options.cause });
-    this.name = "TileflowCaptureError";
-    this.code = code;
-    this.details = normalizeDetails(options?.details);
-  }
-};
-function captureErrorMessage(error, fallback) {
-  if (error instanceof TileflowCaptureError) {
-    return error.message;
-  }
-  return fallback;
-}
-function normalizeDetails(details) {
-  if (!details) return void 0;
-  const diagnostics = (details.diagnostics ?? []).map((diagnostic) => ({
-    message: boundText(diagnostic.message.replace(/[\r\n]+/g, " ").trim(), 300),
-    path: boundText(diagnostic.path.replaceAll("\\", "/"), 300)
-  })).sort((left, right) => {
-    const leftKey = `${left.path}\0${left.message}`;
-    const rightKey = `${right.path}\0${right.message}`;
-    return leftKey < rightKey ? -1 : leftKey > rightKey ? 1 : 0;
-  }).slice(0, 32);
-  const resources = (details.resources ?? []).map(normalizeResource).filter((resource) => resource !== void 0).sort((left, right) => {
-    const leftKey = `${left.kind}\0${left.origin}\0${left.status ?? ""}\0${left.context ?? ""}`;
-    const rightKey = `${right.kind}\0${right.origin}\0${right.status ?? ""}\0${right.context ?? ""}`;
-    return leftKey < rightKey ? -1 : leftKey > rightKey ? 1 : 0;
-  }).filter(
-    (resource, index, values) => index === 0 || JSON.stringify(resource) !== JSON.stringify(values[index - 1])
-  ).slice(0, 8);
-  const normalized = {
-    ...details.phase ? { phase: details.phase } : {},
-    ...diagnostics.length > 0 ? { diagnostics } : {},
-    ...resources.length > 0 ? { resources } : {}
-  };
-  return Object.keys(normalized).length > 0 ? normalized : void 0;
-}
-function normalizeResource(resource) {
-  let origin;
-  try {
-    origin = new URL(resource.origin).origin;
-  } catch {
-    return void 0;
-  }
-  const status = resource.status !== void 0 && Number.isInteger(resource.status) && resource.status >= 100 && resource.status <= 599 ? resource.status : void 0;
-  const context = resource.context ? boundText(resource.context.replace(/[^A-Za-z0-9 _.,:@+-]/g, "").trim(), 128) : void 0;
-  return {
-    ...context ? { context } : {},
-    kind: resource.kind,
-    origin,
-    ...status === void 0 ? {} : { status }
-  };
-}
-function boundText(value, limit) {
-  return value.length <= limit ? value : `${value.slice(0, limit - 1)}\u2026`;
-}
-
 // src/metadata.ts
 import { readFileSync } from "fs";
 import { createRequire } from "module";
@@ -346,30 +296,37 @@ import { resolve } from "path";
 import {
   compareCodeUnits as compareCodeUnits3,
   normalizeTileflowCaptureScene,
-  serializeCanonicalJson as serializeCanonicalJson2,
+  parseTileflowMap,
+  resolveThemeSelection,
+  serializeCanonicalJson,
   sha256Hex,
-  tileflowCaptureSceneNameSchema as tileflowCaptureSceneNameSchema2
+  tileflowCaptureSceneNameSchema
 } from "@tileflow/core";
 import {
-  assertValidTileflowStyle as assertValidTileflowStyle2,
   createTileflowBuildArtifacts,
-  defaultTileflowConfigPath,
-  TileflowStyleValidationError as TileflowStyleValidationError2
-} from "@tileflow/dev";
+  defaultTileflowConfigPath
+} from "@tileflow/dev/artifacts";
+import { assertValidTileflowStyle as assertValidTileflowStyle2, TileflowStyleValidationError as TileflowStyleValidationError2 } from "@tileflow/dev/validation";
 
 // src/application.ts
 import { tileflowCaptureSceneLimits } from "@tileflow/core";
 
 // src/standalone.ts
+import { readFileSync as readFileSync2 } from "fs";
 import { createRequire as createRequire2 } from "module";
-import {
-  assertValidTileflowStyle,
-  TileflowStyleValidationError
-} from "@tileflow/dev";
+import { dirname as dirname2, join as join2 } from "path";
+import { getTileflowStyleFontFaces } from "@tileflow/core/runtime";
+import { assertValidTileflowStyle, TileflowStyleValidationError } from "@tileflow/dev/validation";
 var tileflowSyntheticAssetOrigin = "https://tileflow.local.invalid";
 var require3 = createRequire2(import.meta.url);
 var maplibreJsPath = require3.resolve("maplibre-gl/dist/maplibre-gl.js");
 var maplibreCssPath = require3.resolve("maplibre-gl/dist/maplibre-gl.css");
+var tileflowCorePackagePath = require3.resolve("@tileflow/core/package.json");
+var tileflowBrowserModule = `${readFileSync2(
+  join2(dirname2(tileflowCorePackagePath), "dist", "browser.js"),
+  "utf8"
+)}
+globalThis.__tileflowRegisterContourProtocol = registerTileflowContourProtocol;`;
 async function captureStandaloneTileflowScene(input) {
   if (input.scene.target.kind !== "map") {
     throw new TileflowCaptureError(
@@ -430,6 +387,7 @@ async function captureStandaloneTileflowScene(input) {
     }, timeoutMs);
     timeout.unref?.();
     const assets = new Map(input.assets.map((asset) => [asset.fileName, asset]));
+    const fontFaces = getTileflowStyleFontFaces(input.style);
     const remoteOrigins = /* @__PURE__ */ new Set();
     let syntheticAssetFailure;
     const resourceFailures = [];
@@ -452,8 +410,9 @@ async function captureStandaloneTileflowScene(input) {
           await route.abort("blockedbyclient");
           return;
         }
+        const source = asset.source;
         await route.fulfill({
-          body: typeof asset.source === "string" ? asset.source : Buffer.from(asset.source),
+          body: typeof source === "string" ? source : Buffer.from(source),
           contentType: asset.contentType,
           status: 200
         });
@@ -487,6 +446,7 @@ async function captureStandaloneTileflowScene(input) {
     await page.setContent(renderHtml(input.scene.viewport), { waitUntil: "domcontentloaded" });
     await page.addStyleTag({ path: maplibreCssPath });
     await page.addScriptTag({ path: maplibreJsPath });
+    await page.addScriptTag({ content: tileflowBrowserModule, type: "module" });
     await page.addScriptTag({ content: renderMapInPageScript });
     phase = "map-load";
     const loadResult = await page.evaluate(
@@ -495,6 +455,7 @@ async function captureStandaloneTileflowScene(input) {
         return renderWindow.__tileflowCaptureLoad(renderInput);
       },
       {
+        fontFaces,
         mapEventTimeoutMs: Math.max(1, timeoutMs - 1e3),
         style: input.style
       }
@@ -599,7 +560,8 @@ function assertPhaseSucceeded(result, phase, syntheticAssetFailure, resourceFail
     });
   }
   if (result.status === "failed" || pageFailed) {
-    throw new TileflowCaptureError("MAP_LOAD_FAILED", mapFailureMessage(phase), {
+    const message = result.status === "failed" && result.message ? `${mapFailureMessage(phase)} ${safeMapError(result.message)}` : mapFailureMessage(phase);
+    throw new TileflowCaptureError("MAP_LOAD_FAILED", message, {
       details: { phase }
     });
   }
@@ -701,6 +663,9 @@ function timeoutMessage(phase) {
 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.";
 }
+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);
+}
 function safeAssetName(value) {
   return value.replace(/[^A-Za-z0-9._/-]/g, "").slice(0, 200) || "unknown";
 }
@@ -755,6 +720,11 @@ function renderHtml(viewport) {
 var renderMapInPageScript = String.raw`
 window.__tileflowCaptureLoad = async function(input) {
   try {
+    await loadTileflowFontFaces(input.fontFaces || []);
+    window.__tileflowRegisterContourProtocol?.({addProtocol: window.maplibregl.addProtocol});
+    window.__tileflowCaptureLoopbackSourceIds = Object.entries(input.style.sources || {})
+      .filter(([, source]) => isLoopbackSourceUrl(source?.url))
+      .map(([sourceId]) => sourceId);
     const map = new window.maplibregl.Map({
       attributionControl: false,
       container: "map",
@@ -764,11 +734,59 @@ window.__tileflowCaptureLoad = async function(input) {
     });
     window.__tileflowMap = map;
     return await waitForMapEvent(map, "load", input.mapEventTimeoutMs);
-  } catch {
-    return {status: "failed", reason: "error"};
+  } catch (error) {
+    return {status: "failed", reason: "error", message: String(error?.message || error || "")};
   }
 };
 
+async function loadTileflowFontFaces(definitions) {
+  const maximumFontBytes = 1024 * 1024;
+  await Promise.all(definitions.map(async (definition) => {
+    const response = await fetch(definition.source, {
+      cache: "force-cache",
+      credentials: "same-origin",
+      redirect: "error"
+    });
+    if (!response.ok) throw new Error("Tileflow font failed: " + response.status);
+    const declaredLength = response.headers.get("content-length");
+    if (declaredLength && /^\d+$/.test(declaredLength) && Number(declaredLength) > maximumFontBytes) {
+      await response.body?.cancel().catch(() => undefined);
+      throw new Error("Tileflow font exceeds the maximum response size.");
+    }
+    if (!response.body) throw new Error("Tileflow font response is empty.");
+    const reader = response.body.getReader();
+    const chunks = [];
+    let byteLength = 0;
+    try {
+      while (true) {
+        const {done, value} = await reader.read();
+        if (done) break;
+        if (!value) continue;
+        byteLength += value.byteLength;
+        if (byteLength > maximumFontBytes) {
+          await reader.cancel().catch(() => undefined);
+          throw new Error("Tileflow font exceeds the maximum response size.");
+        }
+        chunks.push(value);
+      }
+    } finally {
+      reader.releaseLock();
+    }
+    const bytes = new Uint8Array(byteLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+      bytes.set(chunk, offset);
+      offset += chunk.byteLength;
+    }
+    const face = new FontFace(definition.family, bytes.buffer, {
+      ...(definition.style ? {style: definition.style} : {}),
+      ...(definition.weight ? {weight: definition.weight} : {})
+    });
+    await face.load();
+    document.fonts.add(face);
+  }));
+}
+
 window.__tileflowCaptureIdle = async function(input) {
   const map = window.__tileflowMap;
   if (!map) return {status: "failed", reason: "error"};
@@ -820,9 +838,29 @@ function waitForMapEvent(mapInstance, event, timeoutMs) {
       cleanup();
       resolve({status: "ok"});
     };
-    const onError = () => {
+    const onError = (errorEvent) => {
+      const message = String(errorEvent?.error?.message || errorEvent?.message || "");
+      const missingSourceLayer = message.match(
+        /^Source layer "(.+)" does not exist on source "(.+)" as specified by style layer ".+"\.$/
+      );
+      if (missingSourceLayer) {
+        const [, sourceLayer, sourceId] = missingSourceLayer;
+        const liveSource = mapInstance.getSource(sourceId);
+        const advertisedSourceLayers = liveSource?.vectorLayerIds;
+        const loopbackSource = window.__tileflowCaptureLoopbackSourceIds?.includes(sourceId);
+        // A layer advertised by TileJSON may legitimately be absent from one
+        // MVT. Local PMTiles development archives may also carry stale TileJSON
+        // metadata while their tile payload already contains the layer. Keep
+        // remote contracts strict, but let local visual captures verify pixels.
+        if (
+          loopbackSource ||
+          (Array.isArray(advertisedSourceLayers) && advertisedSourceLayers.includes(sourceLayer))
+        ) {
+          return;
+        }
+      }
       cleanup();
-      resolve({status: "failed", reason: "error"});
+      resolve({status: "failed", reason: "error", message});
     };
     const cleanup = () => {
       window.clearTimeout(timeout);
@@ -831,10 +869,24 @@ function waitForMapEvent(mapInstance, event, timeoutMs) {
     };
 
     mapInstance.once(event, onSuccess);
-    mapInstance.once("error", onError);
+    mapInstance.on("error", onError);
   });
 }
 
+function isLoopbackSourceUrl(value) {
+  if (typeof value !== "string") return false;
+  try {
+    const hostname = new URL(value).hostname.toLowerCase();
+    return (
+      hostname === "localhost" ||
+      hostname === "[::1]" ||
+      /^127(?:\.\d{1,3}){3}$/.test(hostname)
+    );
+  } catch {
+    return false;
+  }
+}
+
 function nextFrame() {
   return new Promise((resolve) => window.requestAnimationFrame(() => resolve()));
 }
@@ -886,7 +938,7 @@ async function captureApplicationTileflowScene(input) {
   try {
     context = await input.browser.newContext({
       acceptDownloads: false,
-      colorScheme: "light",
+      colorScheme: input.colorScheme,
       deviceScaleFactor: input.scene.viewport.dpr,
       ignoreHTTPSErrors: false,
       javaScriptEnabled: true,
@@ -985,6 +1037,25 @@ async function captureApplicationTileflowScene(input) {
       );
     }
     if (targetCount === 0) {
+      try {
+        await locator.first().waitFor({
+          state: "attached",
+          // The implicit map/theme locator starts matching only after the framework has resolved
+          // its manifest and concrete theme. Let the operation-wide timeout remain authoritative;
+          // a separate two-second attachment budget made otherwise healthy cold starts fail early.
+          timeout: timeoutMs
+        });
+        targetCount = await locator.count();
+      } catch {
+      }
+    }
+    if (targetCount === 0) {
+      if (applicationFailure || applicationOriginEscape) {
+        throw new TileflowCaptureError(
+          "APPLICATION_ERROR",
+          "The application reported an error before its capture target became ready."
+        );
+      }
       throw new TileflowCaptureError(
         "APPLICATION_TARGET_NOT_FOUND",
         "The application page did not contain the requested Tileflow capture target."
@@ -1003,6 +1074,11 @@ async function captureApplicationTileflowScene(input) {
       timeoutMs,
       () => applicationFailure || applicationOriginEscape
     );
+    await assertApplicationTargetTheme(
+      locator,
+      input.scene.theme,
+      input.scene.target.selector !== void 0
+    );
     if (applicationFailure || applicationOriginEscape) {
       throw new TileflowCaptureError(
         "APPLICATION_ERROR",
@@ -1022,6 +1098,11 @@ async function captureApplicationTileflowScene(input) {
       input.scene.target.frame === "viewport" ? await page.screenshot({ animations: "disabled", type: "png" }) : await locator.screenshot({ animations: "disabled", type: "png" })
     );
     await assertApplicationTargetRemainsReady(locator, input.scene.target.selector !== void 0);
+    await assertApplicationTargetTheme(
+      locator,
+      input.scene.theme,
+      input.scene.target.selector !== void 0
+    );
     if (applicationFailure || applicationOriginEscape) {
       throw new TileflowCaptureError(
         "APPLICATION_ERROR",
@@ -1080,6 +1161,15 @@ async function assertApplicationTargetRemainsReady(locator, allowUnmarkedSelecto
     "The application capture target stopped being ready while its screenshot was produced."
   );
 }
+async function assertApplicationTargetTheme(locator, expectedTheme, allowUnmarkedSelector) {
+  if (!expectedTheme) return;
+  const actualTheme = await locator.getAttribute("data-tileflow-theme");
+  if (actualTheme === expectedTheme || actualTheme === null && allowUnmarkedSelector) return;
+  throw new TileflowCaptureError(
+    "APPLICATION_ERROR",
+    `The application capture target resolved theme "${actualTheme ?? "(missing)"}" instead of "${expectedTheme}".`
+  );
+}
 function webSocketHttpOrigin(url) {
   const comparable = new URL(url);
   comparable.protocol = url.protocol === "wss:" ? "https:" : "http:";
@@ -1108,7 +1198,7 @@ function createTargetLocator(page, scene) {
       return page.locator(`[data-tileflow-capture-id="${scene.target.captureId}"]`);
     }
     if (scene.target.selector) return page.locator(scene.target.selector);
-    return page.locator(`[data-tileflow-map="${scene.map}"]`);
+    return page.locator(`[data-tileflow-map="${scene.map}"][data-tileflow-theme="${scene.theme}"]`);
   } catch (error) {
     throw new TileflowCaptureError(
       "APPLICATION_TARGET_NOT_FOUND",
@@ -1199,162 +1289,222 @@ function compareCodeUnits2(left, right) {
   return left < right ? -1 : left > right ? 1 : 0;
 }
 
-// src/receipt.ts
+// src/world.ts
 import {
-  serializeCanonicalJson,
-  tileflowCaptureIdSchema,
-  tileflowCaptureSceneLimits as tileflowCaptureSceneLimits2,
-  tileflowCaptureSceneNameSchema
+  isTileflowWorldReleaseId,
+  tileflowWorldTileJsonUrl
 } from "@tileflow/core";
-var tileflowCaptureReceiptSchemaVersion = 1;
-var tileflowCaptureReceiptLimits = Object.freeze({ maximumBytes: 64 * 1024 });
-function createTileflowCaptureReceipt(input) {
-  return validateTileflowCaptureReceipt({
-    schemaVersion: tileflowCaptureReceiptSchemaVersion,
-    scene: {
-      name: input.scene,
-      map: input.map,
-      target: input.target,
-      sha256: input.sceneSha256
-    },
-    style: { sha256: input.styleSha256 },
-    image: {
-      sha256: input.pngSha256,
-      cssWidth: input.width,
-      cssHeight: input.height,
-      physicalWidth: input.width * input.dpr,
-      physicalHeight: input.height * input.dpr,
-      dpr: input.dpr
-    },
-    renderer: input.renderer,
-    platform: { os: process.platform, architecture: process.arch },
-    source: { tilesetVersion: input.sourceVersion ?? null },
-    networkDependent: input.networkDependent
-  });
-}
-function serializeTileflowCaptureReceipt(receipt) {
-  return `${serializeCanonicalJson(validateTileflowCaptureReceipt(receipt))}
-`;
-}
-function parseTileflowCaptureReceipt(source) {
-  const byteLength = typeof source === "string" ? new TextEncoder().encode(source).byteLength : source.byteLength;
-  if (byteLength > tileflowCaptureReceiptLimits.maximumBytes) {
-    throw invalidReceipt("The baseline receipt exceeds the supported byte limit.");
+var tileflowWorldCurrentTileJsonUrl = tileflowWorldTileJsonUrl;
+var maximumTileJsonBytes = 1024 * 1024;
+var TileflowCaptureWorldSession = class {
+  #fetch;
+  #lookupUrl;
+  #resolution;
+  constructor(fetchTileJson = globalThis.fetch) {
+    this.#fetch = fetchTileJson;
+  }
+  async prepare(style, signal) {
+    const metadata = requireDataMetadata(style);
+    if (metadata.kind !== "tileflow-world") {
+      return { data: validateVectorDataInput(metadata), style };
+    }
+    const source = requirePrimaryVectorSource(style);
+    const lookupUrl = worldTileJsonLookupUrl(source, metadata);
+    const resolution = await this.#resolveOne(lookupUrl, signal);
+    const semantics = validateSemantics(metadata.semantics);
+    const data = {
+      ...resolution.identity,
+      kind: "tileflow-world",
+      schema: requireLiteral(metadata.schema, "openmaptiles", "schema"),
+      schemaVersion: requirePositiveInteger(metadata.schemaVersion, "schemaVersion"),
+      ...semantics ? { semantics } : {},
+      sourceId: requireLiteral(metadata.sourceId, "tileflow", "sourceId")
+    };
+    const { tiles: _mutableTiles, url: _mutableUrl, ...sourceWithoutSelector } = source;
+    return {
+      data,
+      style: {
+        ...style,
+        sources: {
+          ...style.sources,
+          tileflow: { ...sourceWithoutSelector, tiles: [...resolution.tiles] }
+        }
+      }
+    };
+  }
+  #resolveOne(lookupUrl, signal) {
+    if (this.#lookupUrl !== void 0 && this.#lookupUrl !== lookupUrl) {
+      throw worldResolutionError(
+        "One capture session cannot mix different Tileflow World selectors."
+      );
+    }
+    this.#lookupUrl ??= lookupUrl;
+    this.#resolution ??= resolveTileflowCaptureWorldTileJson(lookupUrl, {
+      fetchTileJson: this.#fetch,
+      signal
+    });
+    return this.#resolution;
+  }
+};
+async function resolveTileflowCaptureWorldTileJson(tileJsonUrl, options = {}) {
+  const normalizedUrl = validateTileJsonUrl(tileJsonUrl);
+  const expectedRelease = exactWorldReferenceFromSelector(normalizedUrl);
+  let response;
+  try {
+    response = await (options.fetchTileJson ?? globalThis.fetch)(normalizedUrl, {
+      cache: "no-store",
+      redirect: "error",
+      ...options.signal ? { signal: options.signal } : {}
+    });
+  } catch (error) {
+    if (options.signal?.aborted) {
+      throw new TileflowCaptureError("ABORTED", "Tileflow capture was aborted.", { cause: error });
+    }
+    throw worldResolutionError("Tileflow World TileJSON could not be loaded.", error);
+  }
+  if (!response.ok) {
+    throw worldResolutionError(`Tileflow World TileJSON returned HTTP ${String(response.status)}.`);
   }
-  let value;
   let text;
+  let input;
   try {
-    text = typeof source === "string" ? source : new TextDecoder("utf-8", { fatal: true }).decode(source);
-    value = JSON.parse(text);
+    text = await response.text();
+    if (new TextEncoder().encode(text).byteLength > maximumTileJsonBytes) {
+      throw new TypeError("TileJSON exceeds the supported byte limit");
+    }
+    input = JSON.parse(text);
   } catch (error) {
-    throw invalidReceipt("The baseline receipt is not valid UTF-8 JSON.", error);
-  }
-  const receipt = validateTileflowCaptureReceipt(value);
-  if (text.trim() !== serializeCanonicalJson(receipt)) {
-    throw invalidReceipt("The baseline receipt is not canonical JSON.");
-  }
-  return receipt;
-}
-function validateTileflowCaptureReceipt(value) {
-  const receipt = requireRecord(value, "receipt");
-  const commonKeys = [
-    "schemaVersion",
-    "scene",
-    "style",
-    "image",
-    "renderer",
-    "platform",
-    "source",
-    "networkDependent"
-  ];
-  if (receipt.schemaVersion !== tileflowCaptureReceiptSchemaVersion) {
-    throw invalidReceipt("The baseline receipt schema version is unsupported.");
-  }
-  requireExactKeys(receipt, commonKeys);
-  const scene = requireRecord(receipt.scene, "scene");
-  requireExactKeys(scene, ["name", "map", "target", "sha256"]);
-  const name = requireSceneName(scene.name);
-  const map = requireIdentifier(scene.map, "scene.map");
-  if (scene.target !== "map" && scene.target !== "application") {
-    throw invalidReceipt("The baseline receipt has an invalid scene target.");
-  }
-  const style = requireRecord(receipt.style, "style");
-  requireExactKeys(style, ["sha256"]);
-  const image = requireRecord(receipt.image, "image");
-  requireExactKeys(image, [
-    "sha256",
-    "cssWidth",
-    "cssHeight",
-    "physicalWidth",
-    "physicalHeight",
-    "dpr"
+    throw worldResolutionError("Tileflow World TileJSON is not bounded valid JSON.", error);
+  }
+  const tileJson = requireRecord(input, "TileJSON");
+  if (tileJson.tilejson !== "3.0.0") {
+    throw worldResolutionError("Tileflow World requires TileJSON 3.0.0.");
+  }
+  if (!Array.isArray(tileJson.tiles) || tileJson.tiles.length !== 1) {
+    throw worldResolutionError("Tileflow World TileJSON must contain one exact tile template.");
+  }
+  const tileflow = requireRecord(tileJson.tileflow, "TileJSON tileflow");
+  const world = requireRecord(tileflow.world, "TileJSON tileflow.world");
+  requireExactKeys(world, [
+    "archiveSha256",
+    "contractSha256",
+    "dataContractSha256",
+    "descriptorSha256",
+    "product",
+    "releaseId"
   ]);
-  const cssWidth = requirePositiveFinite(image.cssWidth, "image.cssWidth");
-  const cssHeight = requirePositiveFinite(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 baseline receipt has an invalid image DPR.");
-  }
-  if (cssWidth * image.dpr !== physicalWidth || cssHeight * image.dpr !== physicalHeight) {
-    throw invalidReceipt("The baseline receipt image dimensions are inconsistent.");
-  }
-  if (physicalWidth > tileflowCaptureSceneLimits2.viewport.maximum * 2 || physicalHeight > tileflowCaptureSceneLimits2.viewport.maximum * 2 || physicalWidth * physicalHeight > tileflowCaptureSceneLimits2.maximumPhysicalPixels) {
-    throw invalidReceipt("The baseline receipt image exceeds the supported pixel limit.");
-  }
-  const renderer = requireRecord(receipt.renderer, "renderer");
-  requireExactKeys(renderer, [
-    "tileflow",
-    "maplibre",
-    "playwright",
-    "chromiumRevision",
-    "chromiumVersion"
-  ]);
-  const platform = requireRecord(receipt.platform, "platform");
-  requireExactKeys(platform, ["os", "architecture"]);
-  if (typeof receipt.networkDependent !== "boolean") {
-    throw invalidReceipt("The baseline receipt has an invalid network dependency flag.");
+  if (world.product !== "world-v1") {
+    throw worldResolutionError("Tileflow World TileJSON has an unsupported product.");
+  }
+  const releaseId = requireWorldReleaseId(world.releaseId);
+  const descriptorSha256 = requireHash(world.descriptorSha256, "descriptorSha256");
+  if (expectedRelease && (expectedRelease.releaseId !== releaseId || expectedRelease.descriptorSha256 !== descriptorSha256)) {
+    throw worldResolutionError(
+      "Tileflow World TileJSON conflicts with the requested exact release."
+    );
   }
-  const source = requireRecord(receipt.source, "source");
-  requireExactKeys(source, ["tilesetVersion"]);
+  const tileTemplate = validateExactTileTemplate(tileJson.tiles[0], releaseId, descriptorSha256);
   return {
-    schemaVersion: tileflowCaptureReceiptSchemaVersion,
-    scene: {
-      name,
-      map,
-      target: scene.target,
-      sha256: requireHash(scene.sha256, "scene.sha256")
-    },
-    style: { sha256: requireHash(style.sha256, "style.sha256") },
-    image: {
-      sha256: requireHash(image.sha256, "image.sha256"),
-      cssWidth,
-      cssHeight,
-      physicalWidth,
-      physicalHeight,
-      dpr: image.dpr
-    },
-    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")
+    identity: {
+      archiveSha256: requireHash(world.archiveSha256, "archiveSha256"),
+      contractSha256: requireHash(world.contractSha256, "contractSha256"),
+      dataContractSha256: requireHash(world.dataContractSha256, "dataContractSha256"),
+      descriptorSha256,
+      product: "world-v1",
+      releaseId
     },
-    platform: {
-      os: requireBoundedString(platform.os, "platform.os"),
-      architecture: requireBoundedString(platform.architecture, "platform.architecture")
-    },
-    source: { tilesetVersion: requireNullableSourceVersion(source.tilesetVersion) },
-    networkDependent: receipt.networkDependent
+    tileJsonUrl: normalizedUrl,
+    tiles: [tileTemplate]
+  };
+}
+function requireDataMetadata(style) {
+  const data = style.metadata?.["tileflow:data"];
+  if (!data || typeof data !== "object" || Array.isArray(data)) {
+    throw worldResolutionError("The compiled style has no valid Tileflow data identity.");
+  }
+  return data;
+}
+function validateVectorDataInput(data) {
+  if (data.kind !== "vector-tiles") {
+    throw worldResolutionError("The compiled style has an unsupported Tileflow data kind.");
+  }
+  return data;
+}
+function requirePrimaryVectorSource(style) {
+  const source = style.sources.tileflow;
+  if (!source || source.type !== "vector") {
+    throw worldResolutionError("Tileflow World requires the primary vector source.");
+  }
+  return source;
+}
+function worldTileJsonLookupUrl(source, metadata) {
+  if (typeof source.url === "string") return validateTileJsonUrl(source.url);
+  if (typeof metadata.url === "string") return validateTileJsonUrl(metadata.url);
+  throw worldResolutionError(
+    "Tileflow World capture requires a current or exact TileJSON selector."
+  );
+}
+function validateTileJsonUrl(value) {
+  if (value.length < 1 || value.length > 2048) {
+    throw worldResolutionError("Tileflow World TileJSON URL has an invalid length.");
+  }
+  let url;
+  try {
+    url = new URL(value);
+  } catch (error) {
+    throw worldResolutionError("Tileflow World TileJSON URL is invalid.", error);
+  }
+  if (url.username || url.password || url.hash || url.protocol !== "https:" && !(url.protocol === "http:" && isLoopbackHostname2(url.hostname))) {
+    throw worldResolutionError("Tileflow World TileJSON URL is not an approved HTTP URL.");
+  }
+  return url.toString();
+}
+function exactWorldReferenceFromSelector(value) {
+  const url = new URL(value);
+  const releaseId = url.searchParams.get("worldReleaseId");
+  const descriptorSha256 = url.searchParams.get("worldDescriptorSha256");
+  if (releaseId === null !== (descriptorSha256 === null)) {
+    throw worldResolutionError(
+      "An exact Tileflow World selector requires releaseId and descriptorSha256 together."
+    );
+  }
+  return releaseId === null ? void 0 : {
+    descriptorSha256: requireHash(descriptorSha256, "selector descriptorSha256"),
+    releaseId: requireWorldReleaseId(releaseId)
   };
 }
+function validateExactTileTemplate(value, releaseId, descriptorSha256) {
+  if (typeof value !== "string" || value.length < 1 || value.length > 4096) {
+    throw worldResolutionError("Tileflow World has an invalid exact tile template.");
+  }
+  if (!value.includes("{z}") || !value.includes("{x}") || !value.includes("{y}")) {
+    throw worldResolutionError("Tileflow World tile template is missing XYZ placeholders.");
+  }
+  let url;
+  try {
+    url = new URL(value.replace("{z}", "0").replace("{x}", "0").replace("{y}", "0"));
+  } catch (error) {
+    throw worldResolutionError("Tileflow World has an invalid exact tile template.", error);
+  }
+  if (url.username || url.password || url.hash || url.protocol !== "https:" && !(url.protocol === "http:" && isLoopbackHostname2(url.hostname)) || url.pathname.split("/").includes("current") || !url.pathname.split("/").includes(releaseId) || url.searchParams.get("worldDescriptorSha256") !== descriptorSha256) {
+    throw worldResolutionError(
+      "Tileflow World TileJSON did not bind tiles to its exact release and descriptor."
+    );
+  }
+  return value;
+}
+function validateSemantics(value) {
+  if (value === void 0) return void 0;
+  const semantics = requireRecord(value, "data semantics");
+  requireExactKeys(semantics, ["parkLayer"]);
+  if (semantics.parkLayer !== "mixed" && semantics.parkLayer !== "protected-only") {
+    throw worldResolutionError("The compiled style has invalid park semantics.");
+  }
+  return { parkLayer: semantics.parkLayer };
+}
 function requireRecord(value, field) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw invalidReceipt(`The baseline receipt has an invalid ${field} object.`);
+    throw worldResolutionError(`${field} must be an object.`);
   }
   return value;
 }
@@ -1362,55 +1512,39 @@ function requireExactKeys(value, expected) {
   const actual = Object.keys(value).sort();
   const wanted = [...expected].sort();
   if (actual.length !== wanted.length || actual.some((key, index) => key !== wanted[index])) {
-    throw invalidReceipt("The baseline receipt contains missing or unsupported fields.");
+    throw worldResolutionError("Tileflow World identity contains missing or unsupported fields.");
   }
 }
-function requireIdentifier(value, field) {
-  const result = tileflowCaptureIdSchema.safeParse(value);
-  if (!result.success) throw invalidReceipt(`The baseline receipt has an invalid ${field}.`);
-  return result.data;
-}
-function requireSceneName(value) {
-  const result = tileflowCaptureSceneNameSchema.safeParse(value);
-  if (!result.success) throw invalidReceipt("The baseline receipt has an invalid scene.name.");
-  return result.data;
-}
 function requireHash(value, field) {
-  if (typeof value !== "string" || !/^[a-f0-9]{64}$/.test(value)) {
-    throw invalidReceipt(`The baseline receipt has an invalid ${field}.`);
+  if (typeof value !== "string" || !/^[a-f0-9]{64}$/u.test(value)) {
+    throw worldResolutionError(`Tileflow World has an invalid ${field}.`);
   }
   return value;
 }
-function requirePositiveFinite(value, field) {
-  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
-    throw invalidReceipt(`The baseline receipt has an invalid ${field}.`);
+function requireWorldReleaseId(value) {
+  if (!isTileflowWorldReleaseId(value)) {
+    throw worldResolutionError("Tileflow World has an invalid releaseId.");
   }
   return value;
 }
 function requirePositiveInteger(value, field) {
   if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
-    throw invalidReceipt(`The baseline receipt has an invalid ${field}.`);
-  }
-  return value;
-}
-function requireBoundedString(value, field) {
-  if (typeof value !== "string" || value.length < 1 || value.length > 64 || !isSafeRuntimeIdentity(value)) {
-    throw invalidReceipt(`The baseline receipt has an invalid ${field}.`);
+    throw worldResolutionError(`The compiled style has an invalid ${field}.`);
   }
   return value;
 }
-function requireNullableSourceVersion(value) {
-  if (value === null) return null;
-  if (typeof value !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(value)) {
-    throw invalidReceipt("The baseline receipt has an invalid source.tilesetVersion.");
+function requireLiteral(value, expected, field) {
+  if (value !== expected) {
+    throw worldResolutionError(`The compiled style has an invalid ${field}.`);
   }
-  return value;
+  return expected;
 }
-function isSafeRuntimeIdentity(value) {
-  return /^[A-Za-z0-9][A-Za-z0-9._+-]*$/.test(value);
+function isLoopbackHostname2(value) {
+  const hostname = value.toLowerCase().replace(/^\[|\]$/gu, "");
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1";
 }
-function invalidReceipt(message, cause) {
-  return new TileflowCaptureError("BASELINE_INVALID", message, { cause });
+function worldResolutionError(message, cause) {
+  return new TileflowCaptureError("WORLD_RESOLUTION_FAILED", message, { cause });
 }
 
 // src/capture.ts
@@ -1429,6 +1563,7 @@ function createTileflowCaptureSession(options = {}) {
 var TileflowCaptureSessionImpl = class {
   #options;
   #browserManager;
+  #worldSession;
   #closed = false;
   constructor(options = {}) {
     this.#options = options;
@@ -1437,6 +1572,7 @@ var TileflowCaptureSessionImpl = class {
       onInstallProgress: options.onBrowserInstallProgress,
       signal: options.signal
     });
+    this.#worldSession = new TileflowCaptureWorldSession();
   }
   async capture(scenes, signal) {
     this.#assertOpen();
@@ -1468,7 +1604,8 @@ var TileflowCaptureSessionImpl = class {
   async captureArtifacts(artifacts, requestedScenes, signal) {
     this.#assertOpen();
     const sceneNames = selectTileflowCaptureSceneNames(artifacts, requestedScenes);
-    const validatedMaps = /* @__PURE__ */ new Set();
+    const validatedStyles = /* @__PURE__ */ new Set();
+    const preparedStyles = /* @__PURE__ */ new Map();
     for (const sceneName of sceneNames) {
       const scene = this.#resolveScene(artifacts, sceneName);
       if (scene.target.kind === "application" && !this.#options.appOrigin && !this.#options.appUrl) {
@@ -1477,20 +1614,23 @@ var TileflowCaptureSessionImpl = class {
           `Scene "${sceneName}" requires --app-origin or TILEFLOW_APP_ORIGIN.`
         );
       }
-      const style = Object.hasOwn(artifacts.styles, scene.map) ? artifacts.styles[scene.map] : void 0;
+      const style = artifacts.styles[scene.map]?.[scene.theme];
       if (!style) {
         throw new TileflowCaptureError(
           "SCENE_NOT_FOUND",
-          `Scene "${sceneName}" references unavailable map "${scene.map}".`
+          `Scene "${sceneName}" references unavailable theme "${scene.theme}" on map "${scene.map}".`
         );
       }
-      if (!validatedMaps.has(scene.map)) {
+      const styleKey = `${scene.map}/${scene.theme}`;
+      if (!validatedStyles.has(styleKey)) {
+        const prepared = await this.#worldSession.prepare(style, signal);
         try {
-          assertValidTileflowStyle2(style, scene.map);
+          assertValidTileflowStyle2(prepared.style, styleKey);
         } catch (error) {
           throwCaptureStyleValidationError(error);
         }
-        validatedMaps.add(scene.map);
+        preparedStyles.set(styleKey, prepared);
+        validatedStyles.add(styleKey);
       }
     }
     throwIfAborted2(signal);
@@ -1500,17 +1640,23 @@ var TileflowCaptureSessionImpl = class {
     for (const sceneName of sceneNames) {
       throwIfAborted2(signal);
       const scene = this.#resolveScene(artifacts, sceneName);
-      const style = Object.hasOwn(artifacts.styles, scene.map) ? artifacts.styles[scene.map] : void 0;
-      if (!style) {
+      const prepared = preparedStyles.get(`${scene.map}/${scene.theme}`);
+      const style = prepared?.style;
+      if (!style || !prepared) {
         throw new TileflowCaptureError(
           "SCENE_NOT_FOUND",
           `Scene "${sceneName}" references unavailable map "${scene.map}".`
         );
       }
+      const colorScheme = resolveThemeSelection(
+        parseTileflowMap(artifacts.project.maps[scene.map]),
+        scene.theme
+      ).theme.colorScheme;
       const rendered = scene.target.kind === "application" ? await captureApplicationTileflowScene({
         appOrigin: this.#options.appOrigin,
         appUrl: this.#options.appUrl,
         browser,
+        colorScheme,
         scene: { ...scene, target: scene.target },
         signal,
         timeoutMs: this.#options.timeoutMs
@@ -1524,27 +1670,29 @@ var TileflowCaptureSessionImpl = class {
       });
       const [sha256, sceneSha256, styleSha256] = await Promise.all([
         sha256Hex(rendered.png),
-        sha256Hex(serializeCanonicalJson2(scene)),
-        sha256Hex(serializeCanonicalJson2(style))
+        sha256Hex(serializeCanonicalJson(scene)),
+        sha256Hex(serializeCanonicalJson(style))
       ]);
       const target = scene.target.kind;
       const receipt = createTileflowCaptureReceipt({
+        data: prepared.data,
         dpr: scene.viewport.dpr,
         height: rendered.height,
         map: scene.map,
+        theme: scene.theme,
         networkDependent: rendered.networkDependent,
         pngSha256: sha256,
         renderer,
         scene: sceneName,
         sceneSha256,
         styleSha256,
-        ...typeof style.metadata?.["tileflow:tilesetVersion"] === "string" ? { sourceVersion: style.metadata["tileflow:tilesetVersion"] } : {},
         target,
         width: rendered.width
       });
       captures.push({
         scene: sceneName,
         map: scene.map,
+        theme: scene.theme,
         target,
         png: rendered.png,
         sha256,
@@ -1613,7 +1761,7 @@ var TileflowCaptureSessionImpl = class {
   }
 };
 function selectTileflowCaptureSceneNames(artifacts, requestedScenes) {
-  const availableScenes = Object.keys(artifacts.project.scenes ?? {}).filter((sceneName) => tileflowCaptureSceneNameSchema2.safeParse(sceneName).success).sort(compareCodeUnits3);
+  const availableScenes = Object.keys(artifacts.project.scenes ?? {}).filter((sceneName) => tileflowCaptureSceneNameSchema.safeParse(sceneName).success).sort(compareCodeUnits3);
   const sceneNames = [...new Set(requestedScenes)].sort(compareCodeUnits3);
   if (sceneNames.length === 0) {
     throw new TileflowCaptureError(
@@ -1622,7 +1770,7 @@ function selectTileflowCaptureSceneNames(artifacts, requestedScenes) {
     );
   }
   for (const sceneName of sceneNames) {
-    if (!tileflowCaptureSceneNameSchema2.safeParse(sceneName).success) {
+    if (!tileflowCaptureSceneNameSchema.safeParse(sceneName).success) {
       throw new TileflowCaptureError(
         "SCENE_NOT_FOUND",
         "Expected a portable Tileflow capture scene name."
@@ -1643,7 +1791,26 @@ function normalizeScene(artifacts, sceneName) {
   if (!scene) {
     throw new TileflowCaptureError("SCENE_NOT_FOUND", `Unknown Tileflow scene "${sceneName}".`);
   }
-  return normalizeTileflowCaptureScene(scene);
+  const normalized = normalizeTileflowCaptureScene(scene);
+  const authoredMap = artifacts.project.maps[normalized.map];
+  if (!authoredMap) {
+    throw new TileflowCaptureError(
+      "SCENE_NOT_FOUND",
+      `Scene "${sceneName}" references unavailable map "${normalized.map}".`
+    );
+  }
+  const map = parseTileflowMap(authoredMap);
+  let theme;
+  try {
+    theme = resolveThemeSelection(map, normalized.theme).name;
+  } catch (error) {
+    throw new TileflowCaptureError(
+      "SCENE_NOT_FOUND",
+      `Scene "${sceneName}" has an invalid theme: ${error instanceof Error ? error.message : "unknown theme"}`,
+      { cause: error }
+    );
+  }
+  return { ...normalized, theme };
 }
 function throwIfAborted2(signal) {
   if (signal?.aborted) {
@@ -1665,33 +1832,119 @@ function throwCaptureStyleValidationError(error) {
 
 // src/visual.ts
 import pixelmatch from "pixelmatch";
+import { types as nodeUtilTypes } from "util";
 import { PNG } from "pngjs";
 import {
   compareCodeUnits as compareCodeUnits4,
-  serializeCanonicalJson as serializeCanonicalJson3,
+  serializeCanonicalJson as serializeCanonicalJson2,
   sha256Hex as sha256Hex2,
-  tileflowCaptureSceneLimits as tileflowCaptureSceneLimits3
+  tileflowCaptureSceneLimits as tileflowCaptureSceneLimits2
 } from "@tileflow/core";
 var tileflowVisualComparisonSchemaVersion = 1;
 var tileflowVisualAnalysisSchemaVersion = 1;
 var tileflowVisualPerceptualThreshold = 0.1;
+var tileflowVisualEdgeThreshold = 0.05;
 var tileflowVisualArtifactLimits = Object.freeze({
   maximumPngBytes: 256 * 1024 * 1024,
   maximumPaletteColors: 16
 });
+async function analyzeTileflowCapturePairForReview(left, right, options) {
+  if (options.region) {
+    resolveTileflowVisualRegion(
+      options.region,
+      left.receipt.image.physicalWidth,
+      left.receipt.image.physicalHeight
+    );
+    resolveTileflowVisualRegion(
+      options.region,
+      right.receipt.image.physicalWidth,
+      right.receipt.image.physicalHeight
+    );
+  }
+  if (!options.comparePixels) {
+    const leftIdentity = await inspectPngAgainstReceipt(left.png, left.receipt, "left");
+    const rightIdentity = await inspectPngAgainstReceipt(right.png, right.receipt, "right");
+    return {
+      left: leftIdentity,
+      right: rightIdentity,
+      exact: null,
+      perceptual: null,
+      meanAbsoluteChannelDifference: null,
+      appearance: null
+    };
+  }
+  const leftImage = await validatePngAgainstReceipt(left.png, left.receipt, "left");
+  const rightImage = await validatePngAgainstReceipt(right.png, right.receipt, "right");
+  if (leftImage.width !== rightImage.width || leftImage.height !== rightImage.height) {
+    throw invalidBaseline("Comparable review PNGs did not decode to equal dimensions.");
+  }
+  const totalPixels = leftImage.width * leftImage.height;
+  const region = resolveTileflowVisualRegion(options.region, leftImage.width, leftImage.height);
+  const appearance = createTileflowVisualReviewAppearance(leftImage, rightImage, region);
+  const exactChangedPixels = countExactChangedPixels(leftImage.data, rightImage.data);
+  const diffData = options.includeDiff ? new Uint8Array(totalPixels * 4) : void 0;
+  const perceptualChangedPixels = pixelmatch(
+    leftImage.data,
+    rightImage.data,
+    diffData,
+    leftImage.width,
+    leftImage.height,
+    {
+      checkerboard: true,
+      diffColor: [255, 0, 255],
+      diffColorAlt: [0, 255, 255],
+      diffMask: true,
+      includeAA: true,
+      threshold: tileflowVisualPerceptualThreshold
+    }
+  );
+  return {
+    left: reviewImageAnalysisIdentity(leftImage, left.receipt),
+    right: reviewImageAnalysisIdentity(rightImage, right.receipt),
+    exact: pixelMetric(exactChangedPixels, totalPixels),
+    perceptual: {
+      threshold: tileflowVisualPerceptualThreshold,
+      ...pixelMetric(perceptualChangedPixels, totalPixels)
+    },
+    meanAbsoluteChannelDifference: meanAbsoluteChannelDifference(leftImage.data, rightImage.data),
+    appearance,
+    ...diffData ? { diffPng: encodeDiffPng(diffData, leftImage.width, leftImage.height) } : {}
+  };
+}
+async function inspectPngAgainstReceipt(png, receipt, role) {
+  const image = await validatePngAgainstReceipt(png, receipt, role);
+  return reviewImageAnalysisIdentity(image, receipt);
+}
+function reviewImageAnalysisIdentity(image, receipt) {
+  return {
+    sha256: receipt.image.sha256,
+    physicalWidth: image.width,
+    physicalHeight: image.height,
+    palette: createQuantizedPalette(image.data)
+  };
+}
 function validateTileflowVisualReferencePng(png) {
   const image = decodePng(png, "reference");
   return { width: image.width, height: image.height };
 }
-async function analyzeTileflowCaptureReference(actualCapture, referencePng) {
+async function analyzeTileflowCaptureReference(actualCapture, referencePng, options = {}) {
+  const requestedRegion = snapshotTileflowVisualReferenceAnalysisOptions(options);
   const receipt = validateTileflowCaptureReceipt(actualCapture.receipt);
+  if (receipt.schemaVersion !== 4) {
+    throw invalidBaseline("Visual reference analysis requires a schema-v4 capture receipt.");
+  }
   const actualImage = await validatePngAgainstReceipt(actualCapture.png, receipt, "actual");
   const referenceImage = decodePng(referencePng, "reference");
   const dimensionsMatch = referenceImage.width === actualImage.width && referenceImage.height === actualImage.height;
+  if (requestedRegion) {
+    resolveTileflowVisualRegion(requestedRegion, referenceImage.width, referenceImage.height);
+    resolveTileflowVisualRegion(requestedRegion, actualImage.width, actualImage.height);
+  }
   const common = {
     schemaVersion: tileflowVisualAnalysisSchemaVersion,
     scene: receipt.scene.name,
     map: receipt.scene.map,
+    theme: receipt.scene.theme,
     target: receipt.scene.target,
     dimensionsMatch,
     reference: {
@@ -1713,6 +1966,7 @@ async function analyzeTileflowCaptureReference(actualCapture, referencePng) {
       exact: null,
       perceptual: null,
       meanAbsoluteChannelDifference: null,
+      appearance: null,
       warnings: [
         "The reference and actual PNG dimensions differ; pixel metrics and diff were not computed.",
         ...networkWarnings(void 0, receipt)
@@ -1720,6 +1974,11 @@ async function analyzeTileflowCaptureReference(actualCapture, referencePng) {
     };
   }
   const totalPixels = actualImage.width * actualImage.height;
+  const region = resolveTileflowVisualRegion(
+    requestedRegion,
+    actualImage.width,
+    actualImage.height
+  );
   const exactChangedPixels = countExactChangedPixels(referenceImage.data, actualImage.data);
   const diffData = new Uint8Array(totalPixels * 4);
   const perceptualChangedPixels = pixelmatch(
@@ -1748,6 +2007,7 @@ async function analyzeTileflowCaptureReference(actualCapture, referencePng) {
       referenceImage.data,
       actualImage.data
     ),
+    appearance: createTileflowVisualReferenceAppearance(referenceImage, actualImage, region),
     diffPng: encodeDiffPng(diffData, actualImage.width, actualImage.height),
     warnings: networkWarnings(void 0, receipt)
   };
@@ -1835,8 +2095,8 @@ async function compareTileflowCaptureToBaseline(actualCapture, baseline) {
       baselineReceipt.image.physicalHeight,
       actualReceipt.image.physicalHeight
     );
-    const boundedWidth = diffWidth * diffHeight <= tileflowCaptureSceneLimits3.maximumPhysicalPixels ? diffWidth : actualReceipt.image.physicalWidth;
-    const boundedHeight = diffWidth * diffHeight <= tileflowCaptureSceneLimits3.maximumPhysicalPixels ? diffHeight : actualReceipt.image.physicalHeight;
+    const boundedWidth = diffWidth * diffHeight <= tileflowCaptureSceneLimits2.maximumPhysicalPixels ? diffWidth : actualReceipt.image.physicalWidth;
+    const boundedHeight = diffWidth * diffHeight <= tileflowCaptureSceneLimits2.maximumPhysicalPixels ? diffHeight : actualReceipt.image.physicalHeight;
     return {
       ...common,
       status: "changed",
@@ -1901,7 +2161,7 @@ function createTileflowVisualComparisonDocument(comparison) {
   return document;
 }
 function serializeTileflowVisualComparison(comparison) {
-  return `${serializeCanonicalJson3(createTileflowVisualComparisonDocument(comparison))}
+  return `${serializeCanonicalJson2(createTileflowVisualComparisonDocument(comparison))}
 `;
 }
 function imageIdentity(receipt) {
@@ -1947,7 +2207,7 @@ function preflightPng(png, role) {
       `The ${role} PNG is interlaced and cannot be decoded within fixed bounds.`
     );
   }
-  if (dimensions.width > tileflowCaptureSceneLimits3.viewport.maximum * 2 || dimensions.height > tileflowCaptureSceneLimits3.viewport.maximum * 2 || dimensions.width * dimensions.height > tileflowCaptureSceneLimits3.maximumPhysicalPixels) {
+  if (dimensions.width > tileflowCaptureSceneLimits2.viewport.maximum * 2 || dimensions.height > tileflowCaptureSceneLimits2.viewport.maximum * 2 || dimensions.width * dimensions.height > tileflowCaptureSceneLimits2.maximumPhysicalPixels) {
     throw invalidBaseline(`The ${role} PNG exceeds the visual pixel limit.`);
   }
   return dimensions;
@@ -2030,11 +2290,260 @@ function meanAbsoluteChannelDifference(left, right) {
   }
   return Math.round(sum / left.byteLength * 1e6) / 1e6;
 }
+var appearanceHistogramSteps = 4096;
+var maximumOklabChroma = 0.5;
+function createTileflowVisualReferenceAppearance(reference, actual, region) {
+  const referenceProfile = createAppearanceProfile(reference, region);
+  const actualProfile = createAppearanceProfile(actual, region);
+  return {
+    region,
+    reference: referenceProfile,
+    actual: actualProfile,
+    actualMinusReference: subtractAppearanceProfiles(actualProfile, referenceProfile)
+  };
+}
+function createTileflowVisualReviewAppearance(left, right, region) {
+  const leftProfile = createAppearanceProfile(left, region);
+  const rightProfile = createAppearanceProfile(right, region);
+  return {
+    region,
+    left: leftProfile,
+    right: rightProfile,
+    rightMinusLeft: subtractAppearanceProfiles(rightProfile, leftProfile)
+  };
+}
+function createAppearanceProfile(image, region) {
+  const linearLuminanceHistogram = createAppearanceHistogram(1);
+  const oklabLightnessHistogram = createAppearanceHistogram(1);
+  const oklabChromaHistogram = createAppearanceHistogram(maximumOklabChroma);
+  const previousRow = new Float64Array(region.width);
+  const totalPixels = region.width * region.height;
+  let linearLuminanceSum = 0;
+  let oklabLightnessSum = 0;
+  let oklabChromaSum = 0;
+  let neighborCount = 0;
+  let edgeCount = 0;
+  let localContrastSum = 0;
+  for (let localY = 0; localY < region.height; localY += 1) {
+    const y = region.y + localY;
+    let leftLuminance = 0;
+    for (let localX = 0; localX < region.width; localX += 1) {
+      const x = region.x + localX;
+      const offset = (y * image.width + x) * 4;
+      const alpha = image.data[offset + 3] / 255;
+      const red = srgbToLinear(compositeSrgbOnWhite(image.data[offset], alpha));
+      const green = srgbToLinear(compositeSrgbOnWhite(image.data[offset + 1], alpha));
+      const blue = srgbToLinear(compositeSrgbOnWhite(image.data[offset + 2], alpha));
+      const linearLuminance = 0.2126 * red + 0.7152 * green + 0.0722 * blue;
+      const [oklabLightness, oklabA, oklabB] = linearSrgbToOklab(red, green, blue);
+      const oklabChroma = Math.hypot(oklabA, oklabB);
+      linearLuminanceSum += linearLuminance;
+      oklabLightnessSum += oklabLightness;
+      oklabChromaSum += oklabChroma;
+      addAppearanceHistogramValue(linearLuminanceHistogram, linearLuminance);
+      addAppearanceHistogramValue(oklabLightnessHistogram, oklabLightness);
+      addAppearanceHistogramValue(oklabChromaHistogram, oklabChroma);
+      if (localX > 0) {
+        const difference = Math.abs(linearLuminance - leftLuminance);
+        localContrastSum += difference;
+        neighborCount += 1;
+        if (difference >= tileflowVisualEdgeThreshold) edgeCount += 1;
+      }
+      if (localY > 0) {
+        const difference = Math.abs(linearLuminance - previousRow[localX]);
+        localContrastSum += difference;
+        neighborCount += 1;
+        if (difference >= tileflowVisualEdgeThreshold) edgeCount += 1;
+      }
+      leftLuminance = linearLuminance;
+      previousRow[localX] = linearLuminance;
+    }
+  }
+  return {
+    linearLuminance: appearanceStatistics(
+      linearLuminanceSum,
+      totalPixels,
+      linearLuminanceHistogram
+    ),
+    oklabLightness: appearanceStatistics(oklabLightnessSum, totalPixels, oklabLightnessHistogram),
+    oklabChroma: appearanceStatistics(oklabChromaSum, totalPixels, oklabChromaHistogram),
+    edgeDensity: roundAppearanceMetric(neighborCount === 0 ? 0 : edgeCount / neighborCount),
+    localContrast: roundAppearanceMetric(
+      neighborCount === 0 ? 0 : localContrastSum / neighborCount
+    )
+  };
+}
+function createAppearanceHistogram(maximum) {
+  return { counts: new Uint32Array(appearanceHistogramSteps + 1), maximum };
+}
+function addAppearanceHistogramValue(histogram, value) {
+  const normalized = Math.max(0, Math.min(1, value / histogram.maximum));
+  histogram.counts[Math.round(normalized * appearanceHistogramSteps)] += 1;
+}
+function appearanceStatistics(sum, total, histogram) {
+  return {
+    mean: roundAppearanceMetric(sum / total),
+    percentiles: {
+      p10: appearancePercentile(histogram, total, 0.1),
+      p50: appearancePercentile(histogram, total, 0.5),
+      p90: appearancePercentile(histogram, total, 0.9)
+    }
+  };
+}
+function appearancePercentile(histogram, total, percentile) {
+  const position = (total - 1) * percentile;
+  const lowerRank = Math.floor(position);
+  const upperRank = Math.ceil(position);
+  const lower = appearanceHistogramValueAtRank(histogram, lowerRank);
+  const upper = appearanceHistogramValueAtRank(histogram, upperRank);
+  return roundAppearanceMetric(lower + (upper - lower) * (position - lowerRank));
+}
+function appearanceHistogramValueAtRank(histogram, rank) {
+  let cumulative = 0;
+  for (let index = 0; index < histogram.counts.length; index += 1) {
+    cumulative += histogram.counts[index];
+    if (cumulative > rank) {
+      return index / appearanceHistogramSteps * histogram.maximum;
+    }
+  }
+  return histogram.maximum;
+}
+function subtractAppearanceProfiles(minuend, subtrahend) {
+  return {
+    linearLuminance: subtractAppearanceStatistics(
+      minuend.linearLuminance,
+      subtrahend.linearLuminance
+    ),
+    oklabLightness: subtractAppearanceStatistics(minuend.oklabLightness, subtrahend.oklabLightness),
+    oklabChroma: subtractAppearanceStatistics(minuend.oklabChroma, subtrahend.oklabChroma),
+    edgeDensity: subtractAppearanceMetric(minuend.edgeDensity, subtrahend.edgeDensity),
+    localContrast: subtractAppearanceMetric(minuend.localContrast, subtrahend.localContrast)
+  };
+}
+function subtractAppearanceStatistics(minuend, subtrahend) {
+  return {
+    mean: subtractAppearanceMetric(minuend.mean, subtrahend.mean),
+    percentiles: {
+      p10: subtractAppearanceMetric(minuend.percentiles.p10, subtrahend.percentiles.p10),
+      p50: subtractAppearanceMetric(minuend.percentiles.p50, subtrahend.percentiles.p50),
+      p90: subtractAppearanceMetric(minuend.percentiles.p90, subtrahend.percentiles.p90)
+    }
+  };
+}
+function subtractAppearanceMetric(minuend, subtrahend) {
+  return roundAppearanceMetric(minuend - subtrahend);
+}
+function roundAppearanceMetric(value) {
+  const rounded = Math.round(value * 1e6) / 1e6;
+  return Object.is(rounded, -0) ? 0 : rounded;
+}
+function compositeSrgbOnWhite(channel, alpha) {
+  return channel / 255 * alpha + (1 - alpha);
+}
+function srgbToLinear(channel) {
+  return channel <= 0.04045 ? channel / 12.92 : Math.pow((channel + 0.055) / 1.055, 2.4);
+}
+function linearSrgbToOklab(red, green, blue) {
+  const l = Math.cbrt(0.4122214708 * red + 0.5363325363 * green + 0.0514459929 * blue);
+  const m = Math.cbrt(0.2119034982 * red + 0.6806995451 * green + 0.1073969566 * blue);
+  const s = Math.cbrt(0.0883024619 * red + 0.2817188376 * green + 0.6299787005 * blue);
+  return [
+    0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+    1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+    0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s
+  ];
+}
+function snapshotTileflowVisualReferenceAnalysisOptions(options) {
+  const record = requirePlainVisualRecord(options, "Visual reference analysis options");
+  const keys = Object.keys(record);
+  if (keys.some((key) => key !== "region")) {
+    throw invalidBaseline("Visual reference analysis options contain unsupported fields.");
+  }
+  return record.region === void 0 ? void 0 : snapshotTileflowVisualRegion(record.region, "Visual reference analysis region");
+}
+function snapshotTileflowVisualRegion(value, label) {
+  const record = requirePlainVisualRecord(value, label);
+  const keys = Object.keys(record);
+  if (keys.length !== 4 || keys.some((key) => key !== "x" && key !== "y" && key !== "width" && key !== "height")) {
+    throw invalidBaseline(`${label} must contain exactly x, y, width, and height.`);
+  }
+  return {
+    x: record.x,
+    y: record.y,
+    width: record.width,
+    height: record.height
+  };
+}
+function requirePlainVisualRecord(value, label) {
+  if (value === null || typeof value !== "object" || nodeUtilTypes.isProxy(value) || Object.getPrototypeOf(value) !== Object.prototype) {
+    throw invalidBaseline(`${label} must be a plain data object.`);
+  }
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  const entries = [];
+  for (const key of Reflect.ownKeys(descriptors)) {
+    if (typeof key !== "string") {
+      throw invalidBaseline(`${label} must not contain symbol fields.`);
+    }
+    const descriptor = descriptors[key];
+    if (!("value" in descriptor) || !descriptor.enumerable) {
+      throw invalidBaseline(`${label} must not contain accessors or hidden fields.`);
+    }
+    entries.push([key, descriptor.value]);
+  }
+  return Object.fromEntries(entries);
+}
+function resolveTileflowVisualRegion(requested, physicalWidth, physicalHeight) {
+  const region = requested ?? { x: 0, y: 0, width: physicalWidth, height: physicalHeight };
+  if (!Number.isSafeInteger(region.x) || !Number.isSafeInteger(region.y) || !Number.isSafeInteger(region.width) || !Number.isSafeInteger(region.height) || region.x < 0 || region.y < 0 || region.width <= 0 || region.height <= 0 || region.x > physicalWidth - region.width || region.y > physicalHeight - region.height) {
+    throw invalidBaseline(
+      "The visual region must be a positive integer rectangle within the physical PNG bounds."
+    );
+  }
+  return { ...region };
+}
 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.target === actual.scene.target && baseline.scene.sha256 === actual.scene.sha256 && baseline.source.tilesetVersion === actual.source.tilesetVersion;
+  return baseline.scene.name === actual.scene.name && baseline.scene.map === actual.scene.map && baseline.scene.target === actual.scene.target && baseline.scene.sha256 === actual.scene.sha256 && sameDataIdentity(baseline.data, actual.data);
+}
+function sameDataIdentity(baseline, actual) {
+  if (baseline.kind !== actual.kind || baseline.schema !== actual.schema || baseline.schemaVersion !== actual.schemaVersion || baseline.sourceId !== actual.sourceId) {
+    return false;
+  }
+  const baselineExactWorld = exactWorldIdentity(baseline);
+  const actualExactWorld = exactWorldIdentity(actual);
+  if (baselineExactWorld || actualExactWorld) {
+    if (!baselineExactWorld || !actualExactWorld) return false;
+    return baselineExactWorld.product === actualExactWorld.product && baselineExactWorld.releaseId === actualExactWorld.releaseId && baselineExactWorld.descriptorSha256 === actualExactWorld.descriptorSha256 && baselineExactWorld.archiveSha256 === actualExactWorld.archiveSha256 && baselineExactWorld.dataContractSha256 === actualExactWorld.dataContractSha256 && baselineExactWorld.contractSha256 === actualExactWorld.contractSha256 && sameOptionalSemantics(baselineExactWorld.semantics, actualExactWorld.semantics);
+  }
+  const baselineLegacy = baseline;
+  const actualLegacy = actual;
+  if (baselineLegacy.generation !== actualLegacy.generation || baselineLegacy.revision !== actualLegacy.revision || !sameOptionalSemantics(baselineLegacy.semantics, actualLegacy.semantics)) {
+    return false;
+  }
+  if (baselineLegacy.source && (!actualLegacy.source || baselineLegacy.source.kind !== actualLegacy.source.kind || baselineLegacy.source.sha256 !== actualLegacy.source.sha256)) {
+    return false;
+  }
+  if (baselineLegacy.capabilities && (!actualLegacy.capabilities || !isRecordSubset(baselineLegacy.capabilities, actualLegacy.capabilities))) {
+    return false;
+  }
+  if (baselineLegacy.bindings) {
+    if (!actualLegacy.bindings) return false;
+    if (!isRecordSubset(baselineLegacy.bindings.fields, actualLegacy.bindings.fields) || !isRecordSubset(baselineLegacy.bindings.layers, actualLegacy.bindings.layers)) {
+      return false;
+    }
+  }
+  return true;
+}
+function exactWorldIdentity(value) {
+  return value.kind === "tileflow-world" && "product" in value ? value : void 0;
+}
+function sameOptionalSemantics(baseline, actual) {
+  return baseline === void 0 || baseline.parkLayer === actual?.parkLayer;
+}
+function isRecordSubset(baseline, actual) {
+  return Object.entries(baseline).every(([key, value]) => actual[key] === value);
 }
 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;
@@ -2052,22 +2561,455 @@ function networkWarnings(baseline, actual) {
 function invalidBaseline(message, cause) {
   return new TileflowCaptureError("BASELINE_INVALID", message, { cause });
 }
+
+// src/review.ts
+import { types as nodeUtilTypes2 } from "util";
+import {
+  normalizeTileflowCaptureScene as normalizeTileflowCaptureScene2,
+  serializeCanonicalJson as serializeCanonicalJson3,
+  sha256Hex as sha256Hex3
+} from "@tileflow/core";
+var tileflowVisualReviewSchemaVersion = 1;
+var TileflowVisualReviewError = class extends Error {
+  code = "VISUAL_REVIEW_INVALID";
+  constructor(message, options) {
+    super(message, options);
+    this.name = "TileflowVisualReviewError";
+  }
+};
+async function compareTileflowCapturesForReview(leftInput, rightInput, options = {}) {
+  const normalizedOptions = validateReviewOptions(options);
+  const [leftSnapshot, rightSnapshot] = snapshotReviewInputs(leftInput, rightInput);
+  const [left, right] = await Promise.all([
+    validateReviewCapture(leftSnapshot, "left"),
+    validateReviewCapture(rightSnapshot, "right")
+  ]);
+  const frameMatch = sameCanonicalValue(left.comparableFrame, right.comparableFrame);
+  const dimensionsMatch = left.receipt.image.physicalWidth === right.receipt.image.physicalWidth && left.receipt.image.physicalHeight === right.receipt.image.physicalHeight;
+  const rendererMatch = sameCanonicalValue(
+    runtimeIdentity2(left.receipt),
+    runtimeIdentity2(right.receipt)
+  );
+  const dataMatch = sameCanonicalValue(left.receipt.data, right.receipt.data);
+  const status = reviewStatus({ dataMatch, dimensionsMatch, frameMatch, rendererMatch });
+  const comparable = status === "comparable";
+  const warnings = reviewWarnings(status, left.receipt, right.receipt);
+  let analysis;
+  try {
+    analysis = await analyzeTileflowCapturePairForReview(
+      { png: left.png, receipt: left.receipt },
+      { png: right.png, receipt: right.receipt },
+      {
+        comparePixels: comparable,
+        includeDiff: comparable && normalizedOptions.includeDiff,
+        ...normalizedOptions.region ? { region: normalizedOptions.region } : {}
+      }
+    );
+  } catch (error) {
+    const detail = error instanceof Error ? ` ${error.message}` : "";
+    throw invalidReview(`The review PNGs could not be validated.${detail}`, error);
+  }
+  return {
+    schemaVersion: tileflowVisualReviewSchemaVersion,
+    kind: "style-review",
+    status,
+    left: reviewSide(left, analysis.left.palette),
+    right: reviewSide(right, analysis.right.palette),
+    frameMatch,
+    dimensionsMatch,
+    rendererMatch,
+    dataMatch,
+    exact: comparable ? analysis.exact : null,
+    perceptual: comparable ? analysis.perceptual : null,
+    meanAbsoluteChannelDifference: comparable ? analysis.meanAbsoluteChannelDifference : null,
+    appearance: comparable ? analysis.appearance : null,
+    ...comparable && analysis.diffPng ? { diffPng: analysis.diffPng } : {},
+    warnings
+  };
+}
+function createTileflowVisualReviewDocument(comparison) {
+  const { diffPng: _diffPng, ...document } = comparison;
+  return document;
+}
+var tileflowVisualReviewLimits = Object.freeze({
+  maximumAggregatePngBytes: tileflowVisualArtifactLimits.maximumPngBytes
+});
+var reviewCaptureKeys = [
+  "scene",
+  "map",
+  "theme",
+  "target",
+  "png",
+  "sha256",
+  "sceneSha256",
+  "styleSha256",
+  "width",
+  "height",
+  "dpr",
+  "networkDependent",
+  "renderer",
+  "receipt",
+  "warnings"
+];
+var maximumReviewDataNodes = 4096;
+var maximumReviewDataDepth = 32;
+function snapshotReviewInputs(leftInput, rightInput) {
+  const left = inspectReviewInput(leftInput, "left");
+  const right = inspectReviewInput(rightInput, "right");
+  validateTileflowVisualReviewPngByteLengths(left.pngByteLength, right.pngByteLength);
+  return [snapshotInspectedReviewInput(left, "left"), snapshotInspectedReviewInput(right, "right")];
+}
+function inspectReviewInput(input, role) {
+  const wrapper = readPlainDataRecord(input, `${role} review input`, ["capture", "definition"]);
+  const capture = readPlainDataRecord(wrapper.capture, `${role} capture`, reviewCaptureKeys);
+  const definition = clonePlainDataValue(
+    wrapper.definition,
+    `${role} definition`
+  );
+  const renderer = clonePlainDataValue(
+    capture.renderer,
+    `${role} capture.renderer`
+  );
+  const receipt = clonePlainDataValue(
+    capture.receipt,
+    `${role} capture.receipt`
+  );
+  const warnings = clonePlainDataValue(capture.warnings, `${role} capture.warnings`);
+  const png = requireReviewPng(capture.png, role);
+  return {
+    capture: {
+      scene: capture.scene,
+      map: capture.map,
+      theme: capture.theme,
+      target: capture.target,
+      png: png.source,
+      sha256: capture.sha256,
+      sceneSha256: capture.sceneSha256,
+      styleSha256: capture.styleSha256,
+      width: capture.width,
+      height: capture.height,
+      dpr: capture.dpr,
+      networkDependent: capture.networkDependent,
+      renderer,
+      receipt,
+      warnings
+    },
+    pngByteLength: png.byteLength,
+    definition
+  };
+}
+function snapshotInspectedReviewInput(input, role) {
+  let png;
+  try {
+    png = new Uint8Array(input.pngByteLength);
+    png.set(input.capture.png);
+  } catch (error) {
+    throw invalidReview(`The ${role} PNG could not be snapshotted safely.`, error);
+  }
+  if (png.byteLength !== input.pngByteLength) {
+    throw invalidReview(`The ${role} PNG changed while it was being snapshotted.`);
+  }
+  return { capture: { ...input.capture, png }, definition: input.definition };
+}
+function validateTileflowVisualReviewPngByteLengths(leftByteLength, rightByteLength) {
+  for (const [role, byteLength] of [
+    ["left", leftByteLength],
+    ["right", rightByteLength]
+  ]) {
+    if (!Number.isSafeInteger(byteLength) || byteLength < 0) {
+      throw invalidReview(`The ${role} PNG has an invalid byte length.`);
+    }
+    if (byteLength > tileflowVisualArtifactLimits.maximumPngBytes) {
+      throw invalidReview(`The ${role} PNG exceeds the visual artifact byte limit.`);
+    }
+  }
+  if (leftByteLength + rightByteLength > tileflowVisualReviewLimits.maximumAggregatePngBytes) {
+    throw invalidReview("The review PNGs exceed the aggregate visual artifact byte limit.");
+  }
+}
+function requireReviewPng(value, role) {
+  if (value !== null && typeof value === "object" && nodeUtilTypes2.isProxy(value)) {
+    throw invalidReview(`The ${role} PNG must not use an executable proxy.`);
+  }
+  const isBuffer = Buffer.isBuffer(value);
+  if (!(value instanceof Uint8Array) || !isBuffer && Object.getPrototypeOf(value) !== Uint8Array.prototype) {
+    throw invalidReview(`The ${role} PNG must be a plain Uint8Array or Buffer.`);
+  }
+  if (typeof SharedArrayBuffer !== "undefined" && value.buffer instanceof SharedArrayBuffer) {
+    throw invalidReview(`The ${role} PNG must not use shared mutable memory.`);
+  }
+  let byteLength;
+  try {
+    byteLength = value.byteLength;
+  } catch (error) {
+    throw invalidReview(`The ${role} PNG has an invalid byte buffer.`, error);
+  }
+  return { source: value, byteLength };
+}
+function validateReviewOptions(options) {
+  const record = readPlainDataRecord(options, "review options");
+  const keys = Object.keys(record);
+  if (keys.some((key) => key !== "includeDiff" && key !== "region")) {
+    throw invalidReview("The review options contain unsupported fields.");
+  }
+  if (record.includeDiff !== void 0 && typeof record.includeDiff !== "boolean") {
+    throw invalidReview("The review includeDiff option must be boolean.");
+  }
+  if (record.region === void 0) {
+    return { includeDiff: record.includeDiff !== false };
+  }
+  const region = readPlainDataRecord(record.region, "review region", ["x", "y", "width", "height"]);
+  return {
+    includeDiff: record.includeDiff !== false,
+    region: {
+      x: region.x,
+      y: region.y,
+      width: region.width,
+      height: region.height
+    }
+  };
+}
+function clonePlainDataValue(value, path, state = {
+  ancestors: /* @__PURE__ */ new WeakSet(),
+  nodes: 0
+}, depth = 0) {
+  if (value === null || value === void 0 || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value !== "object") {
+    throw invalidReview(`The ${path} value must contain only plain data.`);
+  }
+  if (nodeUtilTypes2.isProxy(value)) {
+    throw invalidReview(`The ${path} value must not use an executable proxy.`);
+  }
+  if (depth > maximumReviewDataDepth || ++state.nodes > maximumReviewDataNodes) {
+    throw invalidReview(`The ${path} value exceeds the bounded plain-data shape.`);
+  }
+  if (state.ancestors.has(value)) {
+    throw invalidReview(`The ${path} value must not contain a cycle.`);
+  }
+  state.ancestors.add(value);
+  try {
+    if (Array.isArray(value)) {
+      if (Object.getPrototypeOf(value) !== Array.prototype || value.length > maximumReviewDataNodes) {
+        throw invalidReview(`The ${path} value must use a plain bounded array.`);
+      }
+      const descriptors = Object.getOwnPropertyDescriptors(value);
+      const indices = Object.keys(descriptors).filter((key) => key !== "length");
+      if (indices.length !== value.length) {
+        throw invalidReview(`The ${path} value must use a dense plain array.`);
+      }
+      const clone = new Array(value.length);
+      for (const key of Reflect.ownKeys(descriptors)) {
+        if (key === "length") continue;
+        if (typeof key !== "string" || !/^(?:0|[1-9][0-9]*)$/.test(key)) {
+          throw invalidReview(`The ${path} value contains an unsupported array field.`);
+        }
+        const index = Number(key);
+        if (!Number.isSafeInteger(index) || index >= value.length) {
+          throw invalidReview(`The ${path} value contains an out-of-bounds array field.`);
+        }
+        const descriptor = descriptors[key];
+        if (!("value" in descriptor) || !descriptor.enumerable) {
+          throw invalidReview(`The ${path} value contains an executable array field.`);
+        }
+        clone[index] = clonePlainDataValue(descriptor.value, `${path}[${key}]`, state, depth + 1);
+      }
+      return clone;
+    }
+    const record = readPlainDataRecord(value, path);
+    state.nodes += Object.keys(record).length;
+    if (state.nodes > maximumReviewDataNodes) {
+      throw invalidReview(`The ${path} value exceeds the bounded plain-data shape.`);
+    }
+    return Object.fromEntries(
+      Object.entries(record).map(([key, child]) => [
+        key,
+        clonePlainDataValue(child, `${path}.${key}`, state, depth + 1)
+      ])
+    );
+  } finally {
+    state.ancestors.delete(value);
+  }
+}
+function readPlainDataRecord(value, path, expectedKeys) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw invalidReview(`The ${path} must be a plain data object.`);
+  }
+  if (nodeUtilTypes2.isProxy(value)) {
+    throw invalidReview(`The ${path} must not use an executable proxy.`);
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    throw invalidReview(`The ${path} must not use a custom prototype.`);
+  }
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  const entries = [];
+  for (const key of Reflect.ownKeys(descriptors)) {
+    if (typeof key !== "string") {
+      throw invalidReview(`The ${path} contains an unsupported symbol field.`);
+    }
+    const descriptor = descriptors[key];
+    if (!("value" in descriptor) || !descriptor.enumerable) {
+      throw invalidReview(`The ${path} contains an accessor or non-enumerable field.`);
+    }
+    entries.push([key, descriptor.value]);
+  }
+  if (expectedKeys) {
+    const actual = entries.map(([key]) => 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.`);
+    }
+  }
+  return Object.fromEntries(entries);
+}
+async function validateReviewCapture(input, role) {
+  let normalized;
+  try {
+    normalized = normalizeTileflowCaptureScene2(input.definition);
+  } catch (error) {
+    throw invalidReview(`The ${role} review definition is invalid.`, error);
+  }
+  const definition = normalized;
+  if (!sameCanonicalValue(input.definition, definition)) {
+    throw invalidReview(`The ${role} review definition must be the exact normalized shape.`);
+  }
+  let parsedReceipt;
+  try {
+    parsedReceipt = validateTileflowCaptureReceipt(input.capture.receipt);
+  } catch (error) {
+    throw invalidReview(`The ${role} capture receipt is invalid.`, error);
+  }
+  const receipt = parsedReceipt;
+  if (receipt.schemaVersion !== 4) {
+    throw invalidReview(`The ${role} review capture requires a schema-v4 receipt.`);
+  }
+  if (definition.map !== receipt.scene.map || definition.theme !== receipt.scene.theme || definition.target.kind !== receipt.scene.target) {
+    throw invalidReview(`The ${role} review identity does not match its capture receipt.`);
+  }
+  const capturesViewport = definition.target.kind === "map" || definition.target.frame === "viewport";
+  if (definition.viewport.dpr !== receipt.image.dpr || capturesViewport && (definition.viewport.width !== receipt.image.cssWidth || definition.viewport.height !== receipt.image.cssHeight)) {
+    throw invalidReview(`The ${role} review frame does not match its captured dimensions.`);
+  }
+  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));
+  if (definitionSha256 !== receipt.scene.sha256) {
+    throw invalidReview(`The ${role} review definition does not match its capture receipt.`);
+  }
+  return {
+    definition,
+    comparableFrame: reviewFrameIdentity(definition),
+    png: input.capture.png,
+    receipt
+  };
+}
+function reviewSide(input, palette) {
+  return {
+    scene: input.receipt.scene,
+    style: input.receipt.style,
+    frame: input.comparableFrame,
+    image: imageIdentity2(input.receipt),
+    runtime: runtimeIdentity2(input.receipt),
+    data: input.receipt.data,
+    verification: input.receipt.verification,
+    palette
+  };
+}
+function reviewFrameIdentity(definition) {
+  return {
+    camera: definition.camera,
+    viewport: definition.viewport,
+    target: definition.target.kind === "map" ? { kind: "map" } : { kind: "application", frame: definition.target.frame }
+  };
+}
+function imageIdentity2(receipt) {
+  return {
+    sha256: receipt.image.sha256,
+    cssWidth: receipt.image.cssWidth,
+    cssHeight: receipt.image.cssHeight,
+    physicalWidth: receipt.image.physicalWidth,
+    physicalHeight: receipt.image.physicalHeight,
+    dpr: receipt.image.dpr,
+    networkDependent: receipt.networkDependent
+  };
+}
+function runtimeIdentity2(receipt) {
+  return { renderer: receipt.renderer, platform: receipt.platform };
+}
+function reviewStatus(input) {
+  if (!input.frameMatch) return "frame-mismatch";
+  if (!input.dimensionsMatch) return "dimensions-mismatch";
+  if (!input.rendererMatch) return "runtime-mismatch";
+  if (!input.dataMatch) return "data-mismatch";
+  return "comparable";
+}
+function reviewWarnings(status, left, right) {
+  const warnings = [];
+  if (left.networkDependent) {
+    warnings.push("The left capture used remote resources and may not be globally byte-stable.");
+  }
+  if (right.networkDependent) {
+    warnings.push("The right capture used remote resources and may not be globally byte-stable.");
+  }
+  if (left.verification.style !== "rendered" || right.verification.style !== "rendered") {
+    warnings.push(
+      "At least one application capture has expected-but-unverified style and data identity."
+    );
+  }
+  if (status === "frame-mismatch") {
+    warnings.push("The review frames differ; pixel metrics and contextual diff were not computed.");
+  } else if (status === "dimensions-mismatch") {
+    warnings.push(
+      "The rendered dimensions differ; pixel metrics and contextual diff were not computed."
+    );
+  } else if (status === "runtime-mismatch") {
+    warnings.push(
+      "The renderer runtimes differ; pixel metrics and contextual diff were not computed."
+    );
+  } else if (status === "data-mismatch") {
+    warnings.push(
+      "The exact data identities differ; pixel metrics and contextual diff were not computed."
+    );
+  } else {
+    warnings.push(
+      "Pixel metrics and the contextual diff describe two deliberate renders; they do not approve either image or create a baseline."
+    );
+  }
+  return [...new Set(warnings)].sort(compareCodeUnits5);
+}
+function sameCanonicalValue(left, right) {
+  return serializeCanonicalJson3(left) === serializeCanonicalJson3(right);
+}
+function compareCodeUnits5(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+function invalidReview(message, cause) {
+  return new TileflowVisualReviewError(message, cause === void 0 ? void 0 : { cause });
+}
 export {
   TileflowCaptureBrowserManager,
   TileflowCaptureError,
+  TileflowCaptureWorldSession,
+  TileflowVisualReviewError,
   analyzeTileflowCaptureReference,
   captureErrorMessage,
   captureTileflowScenes,
   compareTileflowCaptureToBaseline,
+  compareTileflowCapturesForReview,
   createTileflowCaptureBrowserEnvironment,
   createTileflowCaptureReceipt,
   createTileflowCaptureRendererIdentity,
   createTileflowCaptureSession,
   createTileflowVisualComparisonDocument,
   createTileflowVisualReferenceAnalysisDocument,
+  createTileflowVisualReviewDocument,
   launchTileflowCaptureBrowser,
   parseTileflowCaptureReceipt,
   resolveTileflowApplicationUrl,
+  resolveTileflowCaptureWorldTileJson,
   serializeTileflowCaptureReceipt,
   serializeTileflowVisualComparison,
   setupTileflowCaptureBrowser,
@@ -2078,7 +3020,11 @@ export {
   tileflowSyntheticAssetOrigin,
   tileflowVisualArtifactLimits,
   tileflowVisualComparisonSchemaVersion,
+  tileflowVisualEdgeThreshold,
   tileflowVisualPerceptualThreshold,
+  tileflowVisualReviewLimits,
+  tileflowVisualReviewSchemaVersion,
+  tileflowWorldCurrentTileJsonUrl,
   validateTileflowCaptureReceipt,
   validateTileflowVisualReferencePng
 };