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

package/README.md

@@ -70,6 +70,14 @@ Capture verifies the concrete theme before and after screenshot production. A fu
 props own application camera state; capture includes that camera in scene identity but does not
 rewrite it.
 
+The application's development server also remains authoritative for local PMTiles. Each range is
+served from one immutable snapshot and strong ETags prevent one PMTiles read from silently mixing
+generations. Application Capture deliberately adds no lease or token that freezes every local
+dataset for the complete screenshot. A source edit during that exact window can therefore move a
+later read to the next valid generation; application receipts already classify style and data as
+`expected-unverified`. Standalone Capture is stricter because it owns and retains its artifact
+snapshot for the complete render.
+
 ## Prepared/offline browser setup
 
 ```ts

package/dist/index.js

@@ -296,7 +296,7 @@ import { resolve } from "path";
 import {
   compareCodeUnits as compareCodeUnits3,
   normalizeTileflowCaptureScene,
-  parseTileflowMap,
+  parseResolvedTileflowMap,
   resolveThemeSelection,
   serializeCanonicalJson,
   sha256Hex,
@@ -313,6 +313,7 @@ import { tileflowCaptureSceneLimits } from "@tileflow/core";
 
 // src/standalone.ts
 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 { getTileflowStyleFontFaces } from "@tileflow/core/runtime";
@@ -326,7 +327,8 @@ var tileflowBrowserModule = `${readFileSync2(
   join2(dirname2(tileflowCorePackagePath), "dist", "browser.js"),
   "utf8"
 )}
-globalThis.__tileflowRegisterContourProtocol = registerTileflowContourProtocol;`;
+globalThis.__tileflowRegisterContourProtocol = registerTileflowContourProtocol;
+globalThis.__tileflowRegisterPmtilesProtocol = registerTileflowPmtilesProtocol;`;
 async function captureStandaloneTileflowScene(input) {
   if (input.scene.target.kind !== "map") {
     throw new TileflowCaptureError(
@@ -387,6 +389,9 @@ async function captureStandaloneTileflowScene(input) {
     }, timeoutMs);
     timeout.unref?.();
     const assets = new Map(input.assets.map((asset) => [asset.fileName, asset]));
+    const localTilesets = new Map(
+      (input.localTilesets ?? []).map((tileset) => [tileset.fileName, tileset])
+    );
     const fontFaces = getTileflowStyleFontFaces(input.style);
     const remoteOrigins = /* @__PURE__ */ new Set();
     let syntheticAssetFailure;
@@ -404,6 +409,15 @@ async function captureStandaloneTileflowScene(input) {
       const url = new URL(route.request().url());
       if (url.origin === tileflowSyntheticAssetOrigin) {
         const fileName = decodeURIComponent(url.pathname.slice(1));
+        const localTileset = url.search === "" ? localTilesets.get(fileName) : void 0;
+        if (localTileset) {
+          const response = await localTilesetCaptureResponse(
+            route.request().headers()["range"],
+            localTileset
+          );
+          await route.fulfill(response);
+          return;
+        }
         const asset = url.search === "" ? assets.get(fileName) : void 0;
         if (!asset) {
           syntheticAssetFailure = fileName || "unknown";
@@ -545,6 +559,58 @@ async function captureStandaloneTileflowScene(input) {
     await context?.close().catch(() => void 0);
   }
 }
+async function localTilesetCaptureResponse(rangeHeader, file) {
+  const match = rangeHeader?.match(/^bytes=(\d+)-(\d*)$/u);
+  if (!match) {
+    return {
+      body: Buffer.alloc(0),
+      headers: {
+        "Accept-Ranges": "bytes",
+        "Content-Range": `bytes */${file.byteLength}`,
+        ETag: file.etag
+      },
+      status: 416
+    };
+  }
+  const start = Number(match[1]);
+  const requestedEnd = match[2] ? Number(match[2]) : file.byteLength - 1;
+  const end = Math.min(requestedEnd, file.byteLength - 1);
+  if (!Number.isSafeInteger(start) || !Number.isSafeInteger(requestedEnd) || start < 0 || start >= file.byteLength || requestedEnd < start || end - start + 1 > 16 * 1024 * 1024) {
+    return {
+      body: Buffer.alloc(0),
+      headers: {
+        "Accept-Ranges": "bytes",
+        "Content-Range": `bytes */${file.byteLength}`,
+        ETag: file.etag
+      },
+      status: 416
+    };
+  }
+  const length = end - start + 1;
+  const handle = await open(file.sourcePath, "r");
+  try {
+    const body = Buffer.alloc(length);
+    let read = 0;
+    while (read < length) {
+      const result = await handle.read(body, read, length - read, start + read);
+      if (result.bytesRead === 0) throw new Error("Local PMTiles snapshot ended during capture.");
+      read += result.bytesRead;
+    }
+    return {
+      body,
+      contentType: "application/vnd.pmtiles",
+      headers: {
+        "Accept-Ranges": "bytes",
+        "Content-Length": String(length),
+        "Content-Range": `bytes ${start}-${end}/${file.byteLength}`,
+        ETag: file.etag
+      },
+      status: 206
+    };
+  } finally {
+    await handle.close();
+  }
+}
 function assertPhaseSucceeded(result, phase, syntheticAssetFailure, resourceFailures, pageFailed) {
   if (syntheticAssetFailure) {
     throw new TileflowCaptureError(
@@ -722,6 +788,7 @@ window.__tileflowCaptureLoad = async function(input) {
   try {
     await loadTileflowFontFaces(input.fontFaces || []);
     window.__tileflowRegisterContourProtocol?.({addProtocol: window.maplibregl.addProtocol});
+    window.__tileflowRegisterPmtilesProtocol?.({addProtocol: window.maplibregl.addProtocol});
     window.__tileflowCaptureLoopbackSourceIds = Object.entries(input.style.sources || {})
       .filter(([, source]) => isLoopbackSourceUrl(source?.url))
       .map(([sourceId]) => sourceId);
@@ -1577,16 +1644,24 @@ var TileflowCaptureSessionImpl = class {
   async capture(scenes, signal) {
     this.#assertOpen();
     const artifacts = await this.#createArtifacts();
-    return this.captureArtifacts(artifacts, scenes, signal ?? this.#options.signal);
+    try {
+      return await this.captureArtifacts(artifacts, scenes, signal ?? this.#options.signal);
+    } finally {
+      await disposeCaptureArtifacts(artifacts);
+    }
   }
   async captureAll(signal) {
     this.#assertOpen();
     const artifacts = await this.#createArtifacts();
-    return this.captureArtifacts(
-      artifacts,
-      Object.keys(artifacts.project.scenes ?? {}),
-      signal ?? this.#options.signal
-    );
+    try {
+      return await this.captureArtifacts(
+        artifacts,
+        Object.keys(artifacts.project.scenes ?? {}),
+        signal ?? this.#options.signal
+      );
+    } finally {
+      await disposeCaptureArtifacts(artifacts);
+    }
   }
   async captureDefinitions(scenes, signal) {
     this.#assertOpen();
@@ -1595,11 +1670,15 @@ var TileflowCaptureSessionImpl = class {
       ...artifacts,
       project: { ...artifacts.project, scenes }
     };
-    return this.captureArtifacts(
-      withDefinitions,
-      Object.keys(scenes),
-      signal ?? this.#options.signal
-    );
+    try {
+      return await this.captureArtifacts(
+        withDefinitions,
+        Object.keys(scenes),
+        signal ?? this.#options.signal
+      );
+    } finally {
+      await disposeCaptureArtifacts(artifacts);
+    }
   }
   async captureArtifacts(artifacts, requestedScenes, signal) {
     this.#assertOpen();
@@ -1649,7 +1728,7 @@ var TileflowCaptureSessionImpl = class {
         );
       }
       const colorScheme = resolveThemeSelection(
-        parseTileflowMap(artifacts.project.maps[scene.map]),
+        parseResolvedTileflowMap(artifacts.project.maps[scene.map]),
         scene.theme
       ).theme.colorScheme;
       const rendered = scene.target.kind === "application" ? await captureApplicationTileflowScene({
@@ -1663,6 +1742,7 @@ var TileflowCaptureSessionImpl = class {
       }) : await captureStandaloneTileflowScene({
         assets: artifacts.assets,
         browser,
+        ...artifacts.localTilesets ? { localTilesets: artifacts.localTilesets } : {},
         scene,
         signal,
         style,
@@ -1716,13 +1796,18 @@ var TileflowCaptureSessionImpl = class {
     this.#closed = true;
     await this.#browserManager.close();
   }
-  #createArtifacts() {
+  async #createArtifacts() {
     const cwd = resolve(this.#options.cwd ?? process.cwd());
-    return createTileflowBuildArtifacts({
-      assetBaseUrl: tileflowSyntheticAssetOrigin,
-      config: this.#options.config ?? defaultTileflowConfigPath,
-      cwd
-    }).catch((error) => throwCaptureStyleValidationError(error));
+    try {
+      const artifacts = await createTileflowBuildArtifacts({
+        assetBaseUrl: tileflowSyntheticAssetOrigin,
+        config: this.#options.config ?? defaultTileflowConfigPath,
+        cwd
+      });
+      return artifacts;
+    } catch (error) {
+      return throwCaptureStyleValidationError(error);
+    }
   }
   #assertOpen() {
     if (this.#closed) {
@@ -1760,6 +1845,11 @@ var TileflowCaptureSessionImpl = class {
     };
   }
 };
+async function disposeCaptureArtifacts(artifacts) {
+  const dispose = artifacts.dispose;
+  artifacts.dispose = void 0;
+  await dispose?.();
+}
 function selectTileflowCaptureSceneNames(artifacts, requestedScenes) {
   const availableScenes = Object.keys(artifacts.project.scenes ?? {}).filter((sceneName) => tileflowCaptureSceneNameSchema.safeParse(sceneName).success).sort(compareCodeUnits3);
   const sceneNames = [...new Set(requestedScenes)].sort(compareCodeUnits3);
@@ -1792,14 +1882,14 @@ function normalizeScene(artifacts, sceneName) {
     throw new TileflowCaptureError("SCENE_NOT_FOUND", `Unknown Tileflow scene "${sceneName}".`);
   }
   const normalized = normalizeTileflowCaptureScene(scene);
-  const authoredMap = artifacts.project.maps[normalized.map];
-  if (!authoredMap) {
+  const resolvedMap = artifacts.project.maps[normalized.map];
+  if (!resolvedMap) {
     throw new TileflowCaptureError(
       "SCENE_NOT_FOUND",
       `Scene "${sceneName}" references unavailable map "${normalized.map}".`
     );
   }
-  const map = parseTileflowMap(authoredMap);
+  const map = parseResolvedTileflowMap(resolvedMap);
   let theme;
   try {
     theme = resolveThemeSelection(map, normalized.theme).name;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/capture",
-  "version": "0.1.0-alpha.18",
+  "version": "0.1.0-alpha.20",
   "license": "Apache-2.0",
   "description": "Deterministic local visual capture and comparison for Tileflow maps.",
   "engines": {
@@ -50,8 +50,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@tileflow/core": ">=0.1.0-alpha.21 <0.1.0-beta.0",
-    "@tileflow/dev": ">=0.1.0-alpha.19 <0.1.0-beta.0",
+    "@tileflow/core": ">=0.1.0-alpha.23 <0.1.0-beta.0",
+    "@tileflow/dev": ">=0.1.0-alpha.21 <0.1.0-beta.0",
     "maplibre-gl": "5.24.0",
     "pixelmatch": "7.2.0",
     "playwright": "1.62.1",
@@ -69,13 +69,13 @@
     "vite": "^8.0.16",
     "vue": "^3.5.39",
     "webpack": "5.108.3",
-    "@tileflow/maps": "0.1.0-alpha.0",
-    "@tileflow/next": "0.1.0-alpha.18",
-    "@tileflow/react": "0.1.0-alpha.20",
-    "@tileflow/svelte": "0.1.0-alpha.20",
-    "@tileflow/vue": "0.1.0-alpha.20",
-    "@tileflow/vite": "0.1.0-alpha.18",
-    "@tileflow/webpack": "0.1.0-alpha.18"
+    "@tileflow/maps": "0.1.0-alpha.1",
+    "@tileflow/vite": "0.1.0-alpha.19",
+    "@tileflow/vue": "0.1.0-alpha.21",
+    "@tileflow/next": "0.1.0-alpha.19",
+    "@tileflow/react": "0.1.0-alpha.21",
+    "@tileflow/webpack": "0.1.0-alpha.19",
+    "@tileflow/svelte": "0.1.0-alpha.21"
   },
   "scripts": {
     "build": "tsup src/index.ts src/receipt.ts --format esm --dts --clean --platform node",