@tileflow/capture 0.1.0-alpha.39 → 0.1.0-alpha.40

package/README.md

@@ -256,6 +256,16 @@ retained `definition`; when present, that definition must match the explicit rev
 `analyzeTileflowCaptureReference` analyzes
 an external PNG without claiming receipt compatibility. Neither operation approves a baseline.
 
+## Complete images and warnings
+
+A map whose style declares a 3D scene is captured with it mounted, and each image waits until the
+scene has nothing pending, within `timeoutMs` (30 seconds by default). An image whose scene had not
+settled, a dataset the capture is not entitled to read (HTTP 401 or 403, named in the warning) and a
+missing 3D model leave a drawable map: the capture succeeds and `capture.warnings` says what is
+missing. Set `graphics: 'gpu'` on the session to render with the machine's graphics hardware, much
+faster for dense 3D views but with hardware-dependent pixels; keep the default `software` for
+baselines. `session.contactSheet(images)` lays captured PNGs out in one labelled grid.
+
 ## Errors, receipts, and reproducibility
 
 `TileflowCaptureError` reports a stable code, phase, and bounded details. Phases distinguish style

package/dist/index.d.ts

@@ -5,14 +5,21 @@ import { NormalizedTileflowCaptureShot, NormalizedTileflowCaptureScene, Tileflow
 import { TileflowBuildAsset, TileflowIconResolutionOptions, TileflowBuildArtifacts } from '@tileflow/dev/artifacts';
 
 type TileflowBrowserInstallProgress = 'installing' | 'installed';
+/**
+ * `software` (the default) renders WebGL on the CPU, so images match across machines. `gpu` uses
+ * this machine's graphics hardware: many times faster for 3D scenes, but its pixels depend on the
+ * hardware and driver, so it suits exploration rather than committed baselines.
+ */
+type TileflowCaptureGraphics = 'software' | 'gpu';
 type TileflowBrowserLaunchOptions = {
     allowInstall?: boolean;
+    graphics?: TileflowCaptureGraphics;
     onInstallProgress?: (progress: TileflowBrowserInstallProgress) => void;
     signal?: AbortSignal;
 };
 type TileflowCaptureBrowserDependencies = {
     install(signal?: AbortSignal): Promise<void>;
-    launch(): Promise<Browser>;
+    launch(graphics?: TileflowCaptureGraphics): Promise<Browser>;
 };
 declare function createTileflowCaptureBrowserEnvironment(source?: NodeJS.ProcessEnv): Record<string, string>;
 declare function launchTileflowCaptureBrowser(options?: TileflowBrowserLaunchOptions): Promise<Browser>;
@@ -24,6 +31,34 @@ declare class TileflowCaptureBrowserManager {
     close(): Promise<void>;
 }
 
+/** One captured image on a contact sheet, with the label printed under it. */
+type TileflowContactSheetImage = {
+    label: string;
+    png: Uint8Array;
+};
+type TileflowContactSheetOptions = {
+    /** Images per row; defaults to the square root of the count, at most 4. */
+    columns?: number;
+    /** Width of each image on the sheet in CSS pixels; defaults to 480. */
+    cellWidth?: number;
+};
+declare const tileflowContactSheetLimits: Readonly<{
+    cellWidth: {
+        maximum: number;
+        minimum: number;
+    };
+    columns: {
+        maximum: number;
+        minimum: number;
+    };
+    images: 64;
+}>;
+/**
+ * Lays captured images out in one labelled grid PNG, for choosing between candidates at a glance.
+ * The sheet renders offline in the given browser: it loads nothing but the images it is given.
+ */
+declare function renderTileflowContactSheet(browser: Browser, images: readonly TileflowContactSheetImage[], options?: TileflowContactSheetOptions): Promise<Uint8Array>;
+
 declare const tileflowSyntheticAssetOrigin = "https://tileflow.local.invalid";
 type TileflowCaptureAsset = TileflowBuildAsset & {
     url?: string;
@@ -83,6 +118,8 @@ type TileflowCaptureOptions = {
     icons?: TileflowIconResolutionOptions;
     onBrowserInstallProgress?: (progress: TileflowBrowserInstallProgress) => void;
     frame?: 'map' | 'viewport';
+    /** How the browser renders WebGL; see `TileflowCaptureGraphics`. Defaults to `software`. */
+    graphics?: TileflowCaptureGraphics;
     scenes: string[];
     signal?: AbortSignal;
     selector?: string;
@@ -139,6 +176,10 @@ type TileflowCaptureSession = {
     /** Renders committed shots in name order from one compiled artifact snapshot. */
     captureShots(shots: string[], options?: TileflowShotCaptureOptions): Promise<TileflowShotCaptureResult>;
     captureAllShots(options?: TileflowShotCaptureOptions): Promise<TileflowShotCaptureResult>;
+    /** Lays captured images out in one labelled grid PNG, with this session's browser. */
+    contactSheet(images: readonly TileflowContactSheetImage[], options?: TileflowContactSheetOptions & {
+        signal?: AbortSignal;
+    }): Promise<Uint8Array>;
     close(): Promise<void>;
 };
 declare function captureTileflowScenes(options: TileflowCaptureOptions): Promise<TileflowCaptureResult>;
@@ -428,4 +469,4 @@ declare const tileflowVisualReviewLimits: Readonly<{
     maximumAggregatePngBytes: number;
 }>;
 
-export { type CaptureTileflowShotOptions, type CreateTileflowCaptureSessionOptions, type PreparedTileflowCaptureStyle, type TileflowBrowserInstallProgress, type TileflowBrowserLaunchOptions, type TileflowCapture, TileflowCaptureBrowserManager, TileflowCaptureDataInput, type TileflowCaptureDiagnostic, TileflowCaptureError, type TileflowCaptureErrorCode, type TileflowCaptureErrorDetails, type TileflowCaptureOptions, type TileflowCapturePhase, TileflowCaptureReceipt, TileflowCaptureRendererIdentity, type TileflowCaptureResolvedWorldV1, type TileflowCaptureResourceDiagnostic, type TileflowCaptureResourceKind, type TileflowCaptureResult, type TileflowCaptureSession, TileflowCaptureWorldIdentity, TileflowCaptureWorldSession, type TileflowShotCapture, type TileflowShotCaptureOptions, type TileflowShotCaptureResult, type TileflowShotFormat, type TileflowShotFrame, TileflowShotReceiptV1, type TileflowShotVideoCodec, type TileflowVisualAppearanceDelta, type TileflowVisualAppearanceProfile, type TileflowVisualAppearanceStatistics, type TileflowVisualBaseline, type TileflowVisualComparison, type TileflowVisualComparisonDocument, type TileflowVisualComparisonStatus, type TileflowVisualImageIdentity, type TileflowVisualPaletteColor, type TileflowVisualPixelMetric, type TileflowVisualReferenceAnalysis, type TileflowVisualReferenceAnalysisDocument, type TileflowVisualReferenceAnalysisOptions, type TileflowVisualReferenceAppearance, type TileflowVisualRegion, type TileflowVisualReviewAppearance, type TileflowVisualReviewCapture, type TileflowVisualReviewComparison, type TileflowVisualReviewDefinition, type TileflowVisualReviewDocument, TileflowVisualReviewError, type TileflowVisualReviewFrameIdentity, type TileflowVisualReviewOptions, type TileflowVisualReviewSide, type TileflowVisualReviewStatus, type TileflowVisualRuntimeIdentity, type TileflowVisualSceneIdentity, analyzeTileflowCaptureReference, captureErrorMessage, captureTileflowScenes, captureTileflowShot, compareTileflowCaptureToBaseline, compareTileflowCapturesForReview, createTileflowCaptureBrowserEnvironment, createTileflowCaptureSession, createTileflowVisualComparisonDocument, createTileflowVisualReferenceAnalysisDocument, createTileflowVisualReviewDocument, launchTileflowCaptureBrowser, resolveTileflowApplicationUrl, resolveTileflowCaptureWorldTileJson, serializeTileflowVisualComparison, setupTileflowCaptureBrowser, tileflowCaptureResultSchemaVersion, tileflowShotFramesSha256, tileflowSyntheticAssetOrigin, tileflowVisualArtifactLimits, tileflowVisualComparisonSchemaVersion, tileflowVisualEdgeThreshold, tileflowVisualPerceptualThreshold, tileflowVisualReviewLimits, tileflowVisualReviewSchemaVersion, tileflowWorldCurrentTileJsonUrl, validateTileflowVisualReferencePng };
+export { type CaptureTileflowShotOptions, type CreateTileflowCaptureSessionOptions, type PreparedTileflowCaptureStyle, type TileflowBrowserInstallProgress, type TileflowBrowserLaunchOptions, type TileflowCapture, TileflowCaptureBrowserManager, TileflowCaptureDataInput, type TileflowCaptureDiagnostic, TileflowCaptureError, type TileflowCaptureErrorCode, type TileflowCaptureErrorDetails, type TileflowCaptureGraphics, type TileflowCaptureOptions, type TileflowCapturePhase, TileflowCaptureReceipt, TileflowCaptureRendererIdentity, type TileflowCaptureResolvedWorldV1, type TileflowCaptureResourceDiagnostic, type TileflowCaptureResourceKind, type TileflowCaptureResult, type TileflowCaptureSession, TileflowCaptureWorldIdentity, TileflowCaptureWorldSession, type TileflowContactSheetImage, type TileflowContactSheetOptions, type TileflowShotCapture, type TileflowShotCaptureOptions, type TileflowShotCaptureResult, type TileflowShotFormat, type TileflowShotFrame, TileflowShotReceiptV1, type TileflowShotVideoCodec, type TileflowVisualAppearanceDelta, type TileflowVisualAppearanceProfile, type TileflowVisualAppearanceStatistics, type TileflowVisualBaseline, type TileflowVisualComparison, type TileflowVisualComparisonDocument, type TileflowVisualComparisonStatus, type TileflowVisualImageIdentity, type TileflowVisualPaletteColor, type TileflowVisualPixelMetric, type TileflowVisualReferenceAnalysis, type TileflowVisualReferenceAnalysisDocument, type TileflowVisualReferenceAnalysisOptions, type TileflowVisualReferenceAppearance, type TileflowVisualRegion, type TileflowVisualReviewAppearance, type TileflowVisualReviewCapture, type TileflowVisualReviewComparison, type TileflowVisualReviewDefinition, type TileflowVisualReviewDocument, TileflowVisualReviewError, type TileflowVisualReviewFrameIdentity, type TileflowVisualReviewOptions, type TileflowVisualReviewSide, type TileflowVisualReviewStatus, type TileflowVisualRuntimeIdentity, type TileflowVisualSceneIdentity, analyzeTileflowCaptureReference, captureErrorMessage, captureTileflowScenes, captureTileflowShot, compareTileflowCaptureToBaseline, compareTileflowCapturesForReview, createTileflowCaptureBrowserEnvironment, createTileflowCaptureSession, createTileflowVisualComparisonDocument, createTileflowVisualReferenceAnalysisDocument, createTileflowVisualReviewDocument, launchTileflowCaptureBrowser, renderTileflowContactSheet, resolveTileflowApplicationUrl, resolveTileflowCaptureWorldTileJson, serializeTileflowVisualComparison, setupTileflowCaptureBrowser, tileflowCaptureResultSchemaVersion, tileflowContactSheetLimits, tileflowShotFramesSha256, tileflowSyntheticAssetOrigin, tileflowVisualArtifactLimits, tileflowVisualComparisonSchemaVersion, tileflowVisualEdgeThreshold, tileflowVisualPerceptualThreshold, tileflowVisualReviewLimits, tileflowVisualReviewSchemaVersion, tileflowWorldCurrentTileJsonUrl, validateTileflowVisualReferencePng };

package/dist/index.js

@@ -116,7 +116,7 @@ async function launchTileflowCaptureBrowser(options = {}) {
 async function launchTileflowCaptureBrowserWithDependencies(options, dependencies) {
   throwIfAborted(options.signal);
   try {
-    return await dependencies.launch();
+    return await dependencies.launch(options.graphics);
   } catch (error) {
     if (!isMissingBrowserError(error)) {
       throw new TileflowCaptureError(
@@ -137,7 +137,7 @@ async function launchTileflowCaptureBrowserWithDependencies(options, dependencie
     throwIfAborted(options.signal);
     options.onInstallProgress?.("installed");
     try {
-      return await dependencies.launch();
+      return await dependencies.launch(options.graphics);
     } catch (retryError) {
       throw new TileflowCaptureError(
         "BROWSER_START_FAILED",
@@ -224,11 +224,21 @@ var windowsChromiumDisabledFeatures = [
   // Avoid intermittent Windows loopback failures: https://issues.chromium.org/issues/572515601.
   "TcpPortRandomizationWin"
 ];
-function launchPinnedBrowser() {
+function tileflowGpuBrowserArguments(platform = process.platform) {
+  const backend = platform === "darwin" ? "metal" : platform === "win32" ? "d3d11" : "vulkan";
+  return [
+    "--enable-gpu",
+    "--ignore-gpu-blocklist",
+    `--use-angle=${backend}`,
+    ...platform === "linux" ? ["--enable-features=Vulkan"] : []
+  ];
+}
+function launchPinnedBrowser(graphics = "software") {
   return chromium.launch({
     args: [
       "--disable-dev-shm-usage",
-      ...process.platform === "win32" ? [`--disable-features=${windowsChromiumDisabledFeatures.join(",")}`] : []
+      ...process.platform === "win32" ? [`--disable-features=${windowsChromiumDisabledFeatures.join(",")}`] : [],
+      ...graphics === "gpu" ? tileflowGpuBrowserArguments() : []
     ],
     chromiumSandbox: true,
     env: createTileflowCaptureBrowserEnvironment(),
@@ -347,6 +357,12 @@ import { readFileSync as readFileSync2 } from "fs";
 import { open } from "fs/promises";
 import { createRequire as createRequire2 } from "module";
 import { dirname as dirname2, join as join2 } from "path";
+import {
+  tileflowBuildingsMetadataKey,
+  tileflowStreetLightsMetadataKey,
+  tileflowVegetationDisplayMetadataKey,
+  tileflowVegetationMetadataKey
+} from "@tileflow/core";
 import { getTileflowStyleFontFaces } from "@tileflow/core/runtime";
 import {
   createTileflowLineBackgroundGlyphResponder,
@@ -379,6 +395,7 @@ globalThis.__tileflowAttachNotices = attachTileflowNotices;
 globalThis.__tileflowAttachNauticalLights = attachTileflowNauticalLights;
 globalThis.__tileflowMaxPitch = tileflowMaxPitch;
 globalThis.__tileflowAttachLabelPlacement = attachTileflowLabelPlacement;
+globalThis.__tileflowCreateMap3D = createTileflowMap3D;
 globalThis.__tileflowCreateThemeController = createTileflowThemeController;`;
 async function captureStandaloneTileflowScene(input) {
   if (input.scene.target.kind !== "map") {
@@ -430,6 +447,8 @@ async function withStandaloneTileflowPage(input, run) {
   let context;
   let phase = "browser-start";
   let timeout;
+  let budgetStartedAt = Date.now();
+  const pageWarnings = /* @__PURE__ */ new Set();
   const onAbort = () => {
     termination = "aborted";
     void context?.close().catch(() => void 0);
@@ -440,6 +459,7 @@ async function withStandaloneTileflowPage(input, run) {
   };
   const restartTimeout = () => {
     stopTimeout();
+    budgetStartedAt = Date.now();
     timeout = setTimeout(() => {
       termination = "timeout";
       void context?.close().catch(() => void 0);
@@ -484,6 +504,11 @@ async function withStandaloneTileflowPage(input, run) {
     const resourceFailures = [];
     let pageFailed = false;
     const recordResourceFailure = (url, status) => {
+      const degraded = describeDegradedResource(url, status);
+      if (degraded) {
+        if (pageWarnings.size < 32) pageWarnings.add(degraded);
+        return;
+      }
       const diagnostic = classifyResource(url, status);
       if (!diagnostic || resourceFailures.length >= 16) return;
       const key = JSON.stringify(diagnostic);
@@ -591,7 +616,10 @@ async function withStandaloneTileflowPage(input, run) {
         recordResourceFailure(response.url(), response.status());
       }
     });
-    page.on("requestfailed", (request) => recordResourceFailure(request.url()));
+    page.on("requestfailed", (request) => {
+      if (request.failure()?.errorText === "net::ERR_ABORTED") return;
+      recordResourceFailure(request.url());
+    });
     page.setDefaultTimeout(timeoutMs);
     await page.goto(mapLibreRuntimeUrls.document, { waitUntil: "domcontentloaded" });
     await page.addStyleTag({ url: mapLibreRuntimeUrls.css });
@@ -606,16 +634,31 @@ globalThis.maplibregl = maplibregl;`,
     );
     await page.addScriptTag({ content: tileflowBrowserModule, type: "module" });
     await page.addScriptTag({ content: renderMapInPageScript });
+    if (input.graphics === "gpu") {
+      const renderer = await page.evaluate(() => {
+        const context2 = document.createElement("canvas").getContext("webgl2");
+        const info = context2?.getExtension("WEBGL_debug_renderer_info");
+        return info ? String(context2.getParameter(info.UNMASKED_RENDERER_WEBGL)) : "";
+      });
+      pageWarnings.add(
+        /swiftshader|llvmpipe|software/iu.test(renderer) || renderer === "" ? "GPU rendering is unavailable on this machine; the capture used software rendering." : "Rendered with this machine's GPU: pixels depend on its hardware and driver, so compare it only with other GPU captures from the same machine."
+      );
+    }
     const step = async (stepPhase, name, value) => {
       phase = stepPhase;
+      const reserveMs = Math.max(1e4, Math.round(timeoutMs * 0.35));
+      const sceneBudgetMs = Math.max(0, timeoutMs - (Date.now() - budgetStartedAt) - reserveMs);
       const result = await page.evaluate(
         ({ name: functionName, value: stepInput }) => {
           const renderWindow = window;
           return renderWindow[functionName](stepInput);
         },
-        { name, value }
+        { name, value: { ...value, sceneBudgetMs } }
       );
       assertPhaseSucceeded(result, stepPhase, syntheticAssetFailure, resourceFailures, pageFailed);
+      if (result.status === "ok") {
+        for (const warning of result.warnings ?? []) pageWarnings.add(safeSceneWarning(warning));
+      }
     };
     return await run({
       page,
@@ -663,7 +706,10 @@ globalThis.maplibregl = maplibregl;`,
       result() {
         return {
           networkDependent: remoteOrigins.size > 0,
-          warnings: [...remoteOrigins].sort(compareCodeUnits).map((origin) => `Capture requested remote resources from ${origin}.`)
+          warnings: [
+            ...[...remoteOrigins].sort(compareCodeUnits).map((origin) => `Capture requested remote resources from ${origin}.`),
+            ...[...pageWarnings].sort(compareCodeUnits)
+          ]
         };
       }
     });
@@ -672,10 +718,11 @@ globalThis.maplibregl = maplibregl;`,
       throw new TileflowCaptureError("ABORTED", "Tileflow capture was aborted.", { cause: error });
     }
     if (termination === "timeout") {
-      throw new TileflowCaptureError("CAPTURE_TIMEOUT", timeoutMessage(phase), {
-        cause: error,
-        details: { phase }
-      });
+      throw new TileflowCaptureError(
+        "CAPTURE_TIMEOUT",
+        `${timeoutMessage(phase)}${slowSceneHint(input.style, input.graphics, phase)}`,
+        { cause: error, details: { phase } }
+      );
     }
     if (error instanceof CallerFailure) {
       throw error.error;
@@ -926,6 +973,41 @@ function classifyResource(value, status) {
     ...status === void 0 ? {} : { status }
   };
 }
+function describeDegradedResource(value, status) {
+  if (status === void 0) return void 0;
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return void 0;
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") return void 0;
+  const kind = classifyResource(value, status)?.kind;
+  if (kind === "glyph" || kind === "sprite-json" || kind === "sprite-image") return void 0;
+  const dataset = tileflowDatasetOf(url);
+  if (status === 401 || status === 403) {
+    const subject = dataset ? `Tileflow dataset "${dataset}"` : `Data from ${url.origin}`;
+    return `${subject} returned HTTP ${status}: this capture is not entitled to read it, so its layers are missing from the image.`;
+  }
+  if (status === 404 && isModelResource(url)) {
+    return `A 3D model from ${dataset ? `Tileflow dataset "${dataset}"` : url.origin} returned HTTP 404; the buildings under it were captured instead.`;
+  }
+  return void 0;
+}
+function tileflowDatasetOf(url) {
+  const match = /^\/(?:v1\/)?tiles\/([^/]+)\//u.exec(url.pathname);
+  if (!match) return void 0;
+  try {
+    const name = decodeURIComponent(match[1]);
+    return /^[a-z0-9][a-z0-9,_-]{0,63}$/u.test(name) ? name : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function isModelResource(url) {
+  const path = url.pathname.toLowerCase();
+  return path.endsWith(".glb") || /\/(?:landmarks|models)(?:\/|$)/u.test(path);
+}
 function fontStackContext(path) {
   const segments = path.split("/").filter(Boolean);
   const index = segments.findIndex((segment) => /^(?:fonts?|glyphs?)$/i.test(segment));
@@ -952,6 +1034,20 @@ function resourceLabel(kind) {
     "vector-tile": "Vector tile"
   }[kind];
 }
+var sceneMetadataKeys = [
+  tileflowBuildingsMetadataKey,
+  tileflowVegetationMetadataKey,
+  tileflowVegetationDisplayMetadataKey,
+  tileflowStreetLightsMetadataKey
+];
+function slowSceneHint(style, graphics, phase) {
+  if (graphics === "gpu" || phase !== "map-idle" && phase !== "screenshot") return "";
+  const metadata = style.metadata;
+  if (!sceneMetadataKeys.some((key) => metadata?.[key] !== void 0 && metadata[key] !== null)) {
+    return "";
+  }
+  return " Software rendering draws a dense 3D scene slowly: raise --timeout, or pass --gpu for exploratory captures.";
+}
 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.";
@@ -967,6 +1063,9 @@ function mapFailureMessage(phase) {
 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 safeSceneWarning(value) {
+  return value.replace(/[A-Za-z][A-Za-z0-9+.-]*:\/\/\S+/g, "resource").replace(/[^A-Za-z0-9 _.,:;'"@+()[\]/=-]/g, "").trim().slice(0, 300);
+}
 function safeAssetName(value) {
   return value.replace(/[^A-Za-z0-9._/-]/g, "").slice(0, 200) || "unknown";
 }
@@ -1049,6 +1148,17 @@ window.__tileflowCaptureLoad = async function(input) {
     // Capture prefers reduced motion, so Nautical lights stay steady and every image is stable.
     window.__tileflowAttachNauticalLights(map);
     window.__tileflowAttachLabelPlacement(map);
+    // The 3D scene the style declares (buildings, landmarks and Team models, trees, street
+    // lights), mounted as an application and the preview mount it, so captures show the same map.
+    window.__tileflowSceneErrors = [];
+    window.__tileflowScene = window.__tileflowCreateMap3D?.({
+      map,
+      onError: (error) => {
+        if (window.__tileflowSceneErrors.length < 4) {
+          window.__tileflowSceneErrors.push(String(error?.message || error || "unknown error"));
+        }
+      }
+    });
     return await waitForMapEvent(map, "load", input.mapEventTimeoutMs);
   } catch (error) {
     return {status: "failed", reason: "error", message: String(error?.message || error || "")};
@@ -1106,14 +1216,11 @@ async function loadTileflowFontFaces(definitions) {
 window.__tileflowCaptureIdle = async function(input) {
   const map = window.__tileflowMap;
   if (!map) return {status: "failed", reason: "error"};
+  releaseFrames(map);
 
   try {
     applyCamera(map, input.camera);
-    const result = await waitForMapEvent(map, "idle", input.mapEventTimeoutMs);
-    if (result.status === "failed") return result;
-    await nextFrame();
-    await nextFrame();
-    return {status: "ok"};
+    return await settleMap(map, input);
   } catch {
     return {status: "failed", reason: "error"};
   }
@@ -1123,6 +1230,7 @@ window.__tileflowCaptureIdle = async function(input) {
 window.__tileflowCapturePrepareBlend = async function(input) {
   const map = window.__tileflowMap;
   if (!map) return {status: "failed", reason: "error"};
+  releaseFrames(map);
 
   try {
     const controller = window.__tileflowCreateThemeController({
@@ -1147,6 +1255,7 @@ window.__tileflowCapturePrepareBlend = async function(input) {
 window.__tileflowCaptureFrame = async function(input) {
   const map = window.__tileflowMap;
   if (!map) return {status: "failed", reason: "error"};
+  releaseFrames(map);
 
   try {
     const blend = window.__tileflowShotBlend;
@@ -1161,17 +1270,110 @@ window.__tileflowCaptureFrame = async function(input) {
     }
     applyCamera(map, input.camera);
     map.triggerRepaint();
+    return await settleMap(map, input);
+  } catch {
+    return {status: "failed", reason: "error"};
+  }
+};
+
+// MapLibre's idle covers the style's own sources only, and a 3D scene still preparing keeps asking
+// for frames, so on a slow renderer the map may not become idle. With a 3D scene the capture waits until
+// the map's tiles have loaded and the scene has nothing pending, across a few consecutive checks.
+async function settleMap(map, input) {
+  const scene = window.__tileflowScene;
+  if (!scene) {
     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"};
+    return {status: "ok", warnings: []};
   }
-};
+  const warnings = [];
+  const budget = Math.max(0, Math.min(input.mapEventTimeoutMs, input.sceneBudgetMs ?? 0));
+  const deadline = performance.now() + budget;
+  const failure = watchMapErrors(map);
+  let quiet = 0;
+  let pending = scene.pending();
+  try {
+    // The scene asks for the frames it needs; forcing more would only slow a software renderer.
+    while (quiet < 3 && performance.now() < deadline) {
+      await delay(100);
+      await nextFrame();
+      if (failure.result) return failure.result;
+      pending = scene.pending();
+      const busy = pending.buildingTiles + pending.models + pending.treeTiles + pending.transitions;
+      quiet = busy === 0 && map.loaded() ? quiet + 1 : 0;
+    }
+  } finally {
+    failure.stop();
+  }
+  if (quiet < 3) {
+    const parts = [];
+    if (!map.loaded()) parts.push("map tiles");
+    if (pending.buildingTiles) parts.push(pending.buildingTiles + " building tiles");
+    if (pending.models) parts.push(pending.models + " models");
+    if (pending.treeTiles) parts.push(pending.treeTiles + " tree tiles");
+    if (pending.transitions) parts.push(pending.transitions + " transitions");
+    // Map tiles still loading are a MapLibre failure to settle, as without a 3D scene.
+    if (!map.loaded() && parts.length === 1) return {status: "failed", reason: "timeout"};
+    warnings.push(
+      "The 3D scene was still loading when the capture budget ran out (" +
+        parts.join(", ") +
+        " pending after " + Math.round(budget / 1000) + " s); the image may be incomplete. Raise --timeout, or pass --gpu for exploratory captures."
+    );
+  }
+  for (const message of window.__tileflowSceneErrors || []) {
+    warnings.push("The 3D scene failed to draw (" + message + "); the flat map was captured instead.");
+  }
+  if (quiet >= 3) {
+    map.triggerRepaint();
+    await nextFrame();
+    await nextFrame();
+  }
+  holdFrames(map);
+  return {status: "ok", warnings};
+}
+
+// Keeps the last frame on screen while the PNG is taken: on a software renderer a 3D scene that
+// is still preparing would otherwise queue frames that take seconds each and stall the screenshot.
+// The next frame step releases it.
+function holdFrames(map) {
+  if (map.__tileflowHeldRepaint) return;
+  map.__tileflowHeldRepaint = map.triggerRepaint;
+  map.triggerRepaint = () => map;
+}
 
+function releaseFrames(map) {
+  if (!map.__tileflowHeldRepaint) return;
+  map.triggerRepaint = map.__tileflowHeldRepaint;
+  map.__tileflowHeldRepaint = undefined;
+}
+
+// Reports the first map error while the scene settles, with the idle wait's tolerance for source
+// layers a TileJSON advertises but one tile lacks.
+function watchMapErrors(map) {
+  const state = {result: undefined, stop: () => undefined};
+  const pending = waitForMapEvent(map, "tileflow:never", 2147483647);
+  pending.then((result) => {
+    if (result.status === "failed" && result.reason === "error") state.result = result;
+  });
+  state.stop = () => pending.cancel?.();
+  return state;
+}
+
+function delay(milliseconds) {
+  return new Promise((resolve) => window.setTimeout(resolve, milliseconds));
+}
+
+// A map's pitch cap can depend on zoom (a 3D scene lowers it over the overview), so a camera
+// that changes both is applied again once the new zoom has lifted the cap.
 function applyCamera(mapInstance, camera) {
+  moveCamera(mapInstance, camera);
+  const pitch = camera.pitch ?? 0;
+  if (Math.abs(mapInstance.getPitch() - pitch) > 1e-6) moveCamera(mapInstance, camera);
+}
+
+function moveCamera(mapInstance, camera) {
   if (camera.type === "bounds") {
     mapInstance.fitBounds(
       [
@@ -1197,7 +1399,8 @@ function applyCamera(mapInstance, camera) {
 }
 
 function waitForMapEvent(mapInstance, event, timeoutMs) {
-  return new Promise((resolve) => {
+  let cancel;
+  const promise = new Promise((resolve) => {
     const timeout = window.setTimeout(() => {
       cleanup();
       resolve({status: "failed", reason: "timeout"});
@@ -1207,6 +1410,15 @@ function waitForMapEvent(mapInstance, event, timeoutMs) {
       resolve({status: "ok"});
     };
     const onError = (errorEvent) => {
+      // Data the key cannot read leaves the rest of the map drawable; the capture reports it as a
+      // warning naming the dataset instead of failing.
+      const status = errorEvent?.error?.status;
+      if (status === 401 || status === 403) {
+        // MapLibre never finishes loading a style whose source it could not read; the source and
+        // its layers come off, so the rest of the map loads and draws.
+        if (errorEvent?.sourceId) removeRefusedSource(mapInstance, errorEvent.sourceId);
+        return;
+      }
       const message = String(errorEvent?.error?.message || errorEvent?.message || "");
       const missingSourceLayer = message.match(
         /^Source layer "(.+)" does not exist on source "(.+)" as specified by style layer ".+"\.$/
@@ -1236,9 +1448,27 @@ function waitForMapEvent(mapInstance, event, timeoutMs) {
       mapInstance.off("error", onError);
     };
 
+    cancel = () => {
+      cleanup();
+      resolve({status: "cancelled"});
+    };
     mapInstance.once(event, onSuccess);
     mapInstance.on("error", onError);
   });
+  promise.cancel = cancel;
+  return promise;
+}
+
+function removeRefusedSource(mapInstance, sourceId) {
+  try {
+    if (!mapInstance.getSource(sourceId)) return;
+    for (const layer of mapInstance.getStyle()?.layers || []) {
+      if (layer.source === sourceId) mapInstance.removeLayer(layer.id);
+    }
+    mapInstance.removeSource(sourceId);
+  } catch {
+    // The warning still names the dataset; MapLibre reports anything else it cannot load.
+  }
 }
 
 function isLoopbackSourceUrl(value) {
@@ -1658,6 +1888,90 @@ function compareCodeUnits2(left, right) {
   return left < right ? -1 : left > right ? 1 : 0;
 }
 
+// src/contact-sheet.ts
+var tileflowContactSheetLimits = Object.freeze({
+  cellWidth: { maximum: 1024, minimum: 120 },
+  columns: { maximum: 8, minimum: 1 },
+  images: 64
+});
+async function renderTileflowContactSheet(browser, images, options = {}) {
+  const limits = tileflowContactSheetLimits;
+  if (images.length === 0 || images.length > limits.images) {
+    throw new TileflowCaptureError(
+      "SCREENSHOT_FAILED",
+      `A contact sheet holds from 1 to ${limits.images} images.`
+    );
+  }
+  const columns = Math.round(options.columns ?? Math.min(4, Math.ceil(Math.sqrt(images.length))));
+  const cellWidth = Math.round(options.cellWidth ?? 480);
+  if (!(columns >= limits.columns.minimum && columns <= limits.columns.maximum) || !(cellWidth >= limits.cellWidth.minimum && cellWidth <= limits.cellWidth.maximum)) {
+    throw new TileflowCaptureError(
+      "SCREENSHOT_FAILED",
+      `Contact sheet columns must be ${limits.columns.minimum}-${limits.columns.maximum} and cell width ${limits.cellWidth.minimum}-${limits.cellWidth.maximum}.`
+    );
+  }
+  const cells = images.map(({ label, png }) => {
+    const { height: height2, width: width2 } = readPngDimensions(png);
+    return {
+      height: Math.round(cellWidth * height2 / width2),
+      label,
+      src: `data:image/png;base64,${Buffer.from(png).toString("base64")}`
+    };
+  });
+  const gap = 12;
+  const labelHeight = 22;
+  const rows = Math.ceil(cells.length / columns);
+  const rowHeights = Array.from(
+    { length: rows },
+    (_, row) => Math.max(...cells.slice(row * columns, row * columns + columns).map((cell) => cell.height))
+  );
+  const width = gap + columns * (cellWidth + gap);
+  const height = gap + rowHeights.reduce((sum, rowHeight) => sum + rowHeight + labelHeight + gap, 0);
+  const context = await browser.newContext({
+    deviceScaleFactor: 1,
+    javaScriptEnabled: false,
+    serviceWorkers: "block",
+    viewport: { height: Math.min(height, 16384), width }
+  });
+  try {
+    await context.route("**/*", (route) => route.abort("blockedbyclient"));
+    const page = await context.newPage();
+    await page.setContent(contactSheetHtml(cells, { cellWidth, columns, gap, labelHeight }), {
+      waitUntil: "load"
+    });
+    return new Uint8Array(await page.screenshot({ fullPage: true, type: "png" }));
+  } catch (error) {
+    throw new TileflowCaptureError(
+      "SCREENSHOT_FAILED",
+      "Tileflow could not render the contact sheet.",
+      {
+        cause: error,
+        details: { phase: "screenshot" }
+      }
+    );
+  } finally {
+    await context.close().catch(() => void 0);
+  }
+}
+function contactSheetHtml(cells, layout) {
+  const figures = cells.map(
+    (cell) => `<figure><img src="${cell.src}" width="${layout.cellWidth}" height="${cell.height}" alt=""><figcaption>${escapeHtml(cell.label)}</figcaption></figure>`
+  ).join("");
+  return `<!doctype html><html><head><meta charset="utf-8"><style>
+html,body{margin:0;background:#f4f2ee;}
+main{display:grid;grid-template-columns:repeat(${layout.columns},${layout.cellWidth}px);gap:${layout.gap}px;padding:${layout.gap}px;align-items:start;}
+figure{margin:0;}
+img{display:block;border-radius:4px;}
+figcaption{height:${layout.labelHeight}px;line-height:${layout.labelHeight}px;font:500 13px/22px ui-monospace,Menlo,Consolas,monospace;color:#2b2824;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;}
+</style></head><body><main>${figures}</main></body></html>`;
+}
+function escapeHtml(value) {
+  return value.replace(
+    /[&<>"']/gu,
+    (character) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[character]
+  );
+}
+
 // src/shot.ts
 import {
   serializeCanonicalJson,
@@ -2610,6 +2924,7 @@ var TileflowCaptureSessionImpl = class {
     this.#options = options;
     this.#browserManager = new TileflowCaptureBrowserManager({
       allowInstall: options.allowBrowserInstall,
+      ...options.graphics ? { graphics: options.graphics } : {},
       onInstallProgress: options.onBrowserInstallProgress,
       signal: options.signal
     });
@@ -2721,6 +3036,7 @@ var TileflowCaptureSessionImpl = class {
           glyphCacheDirectory: resolve(this.#options.cwd ?? process.cwd()),
           lineBackgroundGlyphs: artifacts.lineBackgroundGlyphs
         } : {},
+        ...this.#options.graphics ? { graphics: this.#options.graphics } : {},
         scene,
         signal,
         style,
@@ -2860,6 +3176,12 @@ var TileflowCaptureSessionImpl = class {
     }
     return { schemaVersion: tileflowCaptureResultSchemaVersion, shots };
   }
+  async contactSheet(images, options = {}) {
+    this.#assertOpen();
+    const { signal, ...layout } = options;
+    const browser = await this.#browserManager.getBrowser(signal ?? this.#options.signal);
+    return await renderTileflowContactSheet(browser, images, layout);
+  }
   async close() {
     if (this.#closed) {
       return;
@@ -3219,8 +3541,8 @@ async function analyzeTileflowCaptureReference(actualCapture, referencePng, opti
   };
 }
 function createTileflowVisualReferenceAnalysisDocument(analysis) {
-  const { diffPng: _diffPng, ...document } = analysis;
-  return document;
+  const { diffPng: _diffPng, ...document2 } = analysis;
+  return document2;
 }
 async function compareTileflowCaptureToBaseline(actualCapture, baseline) {
   const actualReceipt = validateTileflowCaptureReceipt(actualCapture.receipt);
@@ -3363,8 +3685,8 @@ async function compareTileflowCaptureToBaseline(actualCapture, baseline) {
   };
 }
 function createTileflowVisualComparisonDocument(comparison) {
-  const { diffPng: _diffPng, ...document } = comparison;
-  return document;
+  const { diffPng: _diffPng, ...document2 } = comparison;
+  return document2;
 }
 function serializeTileflowVisualComparison(comparison) {
   return `${serializeCanonicalJson3(createTileflowVisualComparisonDocument(comparison))}
@@ -3796,8 +4118,8 @@ async function compareTileflowCapturesForReview(leftInput, rightInput, options =
   };
 }
 function createTileflowVisualReviewDocument(comparison) {
-  const { diffPng: _diffPng, ...document } = comparison;
-  return document;
+  const { diffPng: _diffPng, ...document2 } = comparison;
+  return document2;
 }
 var tileflowVisualReviewLimits = Object.freeze({
   maximumAggregatePngBytes: tileflowVisualArtifactLimits.maximumPngBytes
@@ -4187,6 +4509,7 @@ export {
   launchTileflowCaptureBrowser,
   parseTileflowCaptureReceipt,
   parseTileflowShotReceipt,
+  renderTileflowContactSheet,
   resolveTileflowApplicationUrl,
   resolveTileflowCaptureWorldTileJson,
   serializeTileflowCaptureReceipt,
@@ -4197,6 +4520,7 @@ export {
   tileflowCaptureReceiptSchemaVersion,
   tileflowCaptureResultSchemaVersion,
   tileflowCaptureRuntime,
+  tileflowContactSheetLimits,
   tileflowShotFramesSha256,
   tileflowShotReceiptLimits,
   tileflowShotReceiptSchemaVersion,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/capture",
-  "version": "0.1.0-alpha.39",
+  "version": "0.1.0-alpha.40",
   "license": "Apache-2.0",
   "description": "Deterministic local visual capture and comparison for Tileflow maps.",
   "engines": {
@@ -47,8 +47,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@tileflow/core": ">=0.1.0-alpha.49 <0.1.0-beta.0",
-    "@tileflow/dev": ">=0.1.0-alpha.44 <0.1.0-beta.0",
+    "@tileflow/core": ">=0.1.0-alpha.50 <0.1.0-beta.0",
+    "@tileflow/dev": ">=0.1.0-alpha.45 <0.1.0-beta.0",
     "maplibre-gl": "6.16.0",
     "pixelmatch": "7.2.0",
     "playwright": "1.62.1",
@@ -69,12 +69,13 @@
     "vite": "^8.3.4",
     "vue": "^3.5.43",
     "webpack": "5.108.3",
-    "@tileflow/maps": "0.1.0-alpha.21",
-    "@tileflow/react": "0.1.0-alpha.39",
-    "@tileflow/next": "0.1.0-alpha.25",
-    "@tileflow/svelte": "0.1.0-alpha.37",
-    "@tileflow/vue": "0.1.0-alpha.37",
-    "@tileflow/vite": "0.1.0-alpha.26",
+    "@tileflow/dom": "0.1.0-alpha.0",
+    "@tileflow/next": "0.1.0-alpha.26",
+    "@tileflow/react": "0.1.0-alpha.40",
+    "@tileflow/svelte": "0.1.0-alpha.38",
+    "@tileflow/maps": "0.1.0-alpha.22",
+    "@tileflow/vite": "0.1.0-alpha.27",
+    "@tileflow/vue": "0.1.0-alpha.38",
     "@tileflow/webpack": "0.1.0-alpha.25"
   },
   "scripts": {