@tileflow/capture 0.1.0-alpha.35 → 0.1.0-alpha.36

package/README.md

@@ -116,7 +116,7 @@ per-user browser cache.
 
 ## Render a timed shot
 
-A [capture shot](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/capture-shots.md)
+A [capture shot](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/README.md)
 is a committed camera move with keyframes and an optional theme blend. This module assumes a
 `dusk-flyover` shot in `tileflow.config.ts` and writes its WebM video and receipt:
 
@@ -255,8 +255,6 @@ requiring compatible framing, renderer, and data identity. It accepts captures w
 retained `definition`; when present, that definition must match the explicit review definition.
 `analyzeTileflowCaptureReference` analyzes
 an external PNG without claiming receipt compatibility. Neither operation approves a baseline.
-See the [receipt and comparison reference](https://github.com/tileflow/tileflow-sdk/blob/main/packages/capture/docs/receipts-and-comparison.md),
-also included under `docs/` in the installed package, for identities, metrics, and limits.
 
 ## Errors, receipts, and reproducibility
 
@@ -274,6 +272,5 @@ available tiles while preserving the scene camera. Retries reuse the same frozen
 Remote-dependent rendering is not a guarantee of globally identical pixels
 across platforms or future runs.
 
-Read the [capture contract](https://github.com/tileflow/tileflow-sdk/blob/main/docs/contracts/local-visual-capture.md)
-for durable behavior and [third-party notices](https://github.com/tileflow/tileflow-sdk/blob/main/packages/capture/THIRD_PARTY_NOTICES.md)
-for runtime licenses. For release-specific behavior, prefer installed declarations and docs over `main`.
+Read [third-party notices](https://github.com/tileflow/tileflow-sdk/blob/main/packages/capture/THIRD_PARTY_NOTICES.md)
+for runtime licenses. For release-specific behavior, prefer installed README and declarations over `main`.

package/dist/index.js

@@ -371,6 +371,7 @@ var tileflowBrowserModule = `${readFileSync2(
   "utf8"
 )}
 globalThis.__tileflowRegisterContourProtocol = registerTileflowContourProtocol;
+globalThis.__tileflowRegisterPathGroundProtocol = registerTileflowPathGroundProtocol;
 globalThis.__tileflowRegisterPmtilesProtocol = registerTileflowPmtilesProtocol;
 globalThis.__tileflowAttachAtmosphere = attachTileflowAtmosphere;
 globalThis.__tileflowAttachNotices = attachTileflowNotices;
@@ -1021,6 +1022,7 @@ window.__tileflowCaptureLoad = async function(input) {
   try {
     await loadTileflowFontFaces(input.fontFaces || []);
     window.__tileflowRegisterContourProtocol?.({addProtocol: window.maplibregl.addProtocol});
+    window.__tileflowRegisterPathGroundProtocol?.({addProtocol: window.maplibregl.addProtocol});
     window.__tileflowRegisterPmtilesProtocol?.({addProtocol: window.maplibregl.addProtocol});
     const data = input.style.metadata?.["tileflow:data"];
     const worldSourceId = data?.kind === "tileflow-world" ? data.sourceId : undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/capture",
-  "version": "0.1.0-alpha.35",
+  "version": "0.1.0-alpha.36",
   "license": "Apache-2.0",
   "description": "Deterministic local visual capture and comparison for Tileflow maps.",
   "engines": {
@@ -28,7 +28,6 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "docs",
     "THIRD_PARTY_NOTICES.md",
     "LICENSE"
   ],
@@ -48,8 +47,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@tileflow/core": ">=0.1.0-alpha.41 <0.1.0-beta.0",
-    "@tileflow/dev": ">=0.1.0-alpha.38 <0.1.0-beta.0",
+    "@tileflow/core": ">=0.1.0-alpha.43 <0.1.0-beta.0",
+    "@tileflow/dev": ">=0.1.0-alpha.39 <0.1.0-beta.0",
     "maplibre-gl": "6.13.0",
     "pixelmatch": "7.2.0",
     "playwright": "1.62.1",
@@ -57,7 +56,7 @@
   },
   "devDependencies": {
     "@sveltejs/vite-plugin-svelte": "^7.3.0",
-    "@types/node": "^25.9.2",
+    "@types/node": "^26.6.5",
     "@types/pngjs": "6.0.5",
     "@vitejs/plugin-vue": "^6.0.8",
     "maplibre-gl-min": "npm:maplibre-gl@6.4.1",
@@ -68,12 +67,12 @@
     "vite": "^8.3.4",
     "vue": "^3.5.43",
     "webpack": "5.108.3",
-    "@tileflow/maps": "0.1.0-alpha.15",
+    "@tileflow/maps": "0.1.0-alpha.17",
     "@tileflow/next": "0.1.0-alpha.25",
-    "@tileflow/react": "0.1.0-alpha.35",
-    "@tileflow/svelte": "0.1.0-alpha.33",
-    "@tileflow/vite": "0.1.0-alpha.25",
-    "@tileflow/vue": "0.1.0-alpha.33",
+    "@tileflow/react": "0.1.0-alpha.36",
+    "@tileflow/svelte": "0.1.0-alpha.34",
+    "@tileflow/vite": "0.1.0-alpha.26",
+    "@tileflow/vue": "0.1.0-alpha.34",
     "@tileflow/webpack": "0.1.0-alpha.25"
   },
   "scripts": {

package/docs/receipts-and-comparison.md

@@ -1,107 +0,0 @@
-# Capture receipts and visual comparison
-
-`createTileflowCaptureReceipt`, `parseTileflowCaptureReceipt`,
-`validateTileflowCaptureReceipt`, and `serializeTileflowCaptureReceipt` implement the strict,
-bounded schema-version-4 receipt contract. A receipt contains the concrete theme,
-image/scene/style hashes, dimensions,
-renderer/platform identity, the required resolved `data` identity, explicit style/data verification,
-and remote-dependency state. Standalone map receipts mark configured style and data as `rendered`;
-application receipts mark them as `expected-unverified` because capture cannot inspect an arbitrary
-application's live MapLibre instance. Vector endpoints are represented by a query-free SHA-256
-fingerprint rather than a raw URL. Receipts contain no time, user, origin, path, query, signed token,
-repository, absolute filesystem path, config source, environment, or credential.
-
-For Tileflow World, Capture resolves the map's TileJSON selector once per session, requires
-`tileflow.world` to identify `world-v1` with exact release, descriptor, archive, data-contract, and
-product-contract SHA-256 values, and renders every standalone scene from the returned immutable tile
-template. Repeated scenes and retries reuse that one resolution; another selector in the same
-session fails instead of mixing releases. Parsing accepts only schema version 4.
-
-Capture reuses Core's exact World V1 release-ID contract: 12–128 characters matching
-`^world-v1-[a-z0-9][a-z0-9._-]*[a-z0-9]$`. Selector responses and durable receipts reject rather
-than normalize uppercase, whitespace, another generation, or an incomplete boundary value.
-
-Receipt-only tooling can import these contracts from `@tileflow/capture/receipt` without loading the
-Playwright capture runtime.
-
-`createTileflowShotReceipt`, `parseTileflowShotReceipt`, `validateTileflowShotReceipt`, and
-`serializeTileflowShotReceipt` implement the separate schema-version-1 shot receipt, identified by
-`kind: "shot"` and bounded to 64 KiB. It records the shot and its theme and blend styles, timing,
-dimensions, renderer, platform, data identity, and two hashes: `frames.sha256`, computed from every
-frame's PNG SHA-256 in order, identifies the rendered pixels, and `output.sha256` identifies the
-written WebM file or, for the `frames` output, equals `frames.sha256`. The still-receipt parser
-rejects shot receipts, and the shot-receipt parser rejects still receipts.
-
-The following comparison fragments assume captures and PNG/receipt bytes that the caller has
-already loaded and validated. See the package README for a complete baseline-file example.
-
-```ts
-import {compareTileflowCaptureToBaseline} from '@tileflow/capture';
-
-const comparison = await compareTileflowCaptureToBaseline(result.captures[0], {
-  png: baselinePng,
-  receipt: baselineReceiptJson,
-});
-```
-
-Comparison validates PNG CRC, hash, dimensions, pixel bounds, and receipt identity before reading
-pixels. It classifies unchanged, changed, missing, scene-mismatch, and runtime-mismatch results,
-reports exact RGBA changed pixels plus a fixed 0.1 perceptual metric, and returns an optional
-transparent high-contrast diff PNG. Exact RGBA inequality determines `changed`.
-
-To review two deliberate Tileflow renders that are allowed to use different maps, themes, and
-styles, use the separate review primitive:
-
-```ts
-import {
-  compareTileflowCapturesForReview,
-  createTileflowVisualReviewDocument,
-} from '@tileflow/capture';
-
-const review = await compareTileflowCapturesForReview(
-  {capture: leftCapture, definition: leftDefinition},
-  {capture: rightCapture, definition: rightDefinition},
-  {includeDiff: true, region: {x: 0, y: 0, width: 1200, height: 760}},
-);
-const document = createTileflowVisualReviewDocument(review);
-```
-
-Review requires each PNG, its schema-v4 receipt, and the exact normalized definition used to
-produce it. It authenticates both sides before comparing pixels. Different map/style/theme
-identities are intentional, but camera, viewport, target frame, physical dimensions, renderer, and
-resolved data identity must agree before exact or perceptual metrics are meaningful. Statuses are
-`comparable`, `frame-mismatch`, `dimensions-mismatch`, `runtime-mismatch`, and `data-mismatch`.
-Inputs are snapshotted from plain accessor-free data before asynchronous work, and both individual
-and aggregate PNG byte limits are enforced before hashing. Pixelmatch runs only for compatible
-captures; `includeDiff: false` does not allocate or encode a diff. The optional diff is contextual
-evidence only; this API never reads, writes, or approves a visual baseline.
-
-Every comparable review also reports `appearance: {region, left, right, rightMinusLeft}`. Profiles
-contain linear luminance, OKLab lightness/chroma (`mean`, `p10`, `p50`, `p90`), edge density, and
-local contrast. The optional region is one bounded physical-pixel rectangle from the top-left and
-affects only `appearance`; exact/perceptual metrics and the diff still describe the complete frame.
-
-Review documents are a schema-version-1 compatibility boundary, exposed through
-`tileflowVisualReviewSchemaVersion`. `tileflowVisualReviewLimits.maximumAggregatePngBytes` exposes
-the 256 MiB aggregate input cap; each input is also subject to the 256 MiB
-`tileflowVisualArtifactLimits.maximumPngBytes` cap and the shared decoded-pixel limits. Invalid,
-non-plain, unauthenticated, or over-limit inputs throw `TileflowVisualReviewError` with stable code
-`VISUAL_REVIEW_INVALID`. `createTileflowVisualReviewDocument` removes contextual `diffPng` bytes
-while retaining the versioned identities, status, metrics, and warnings.
-
-For an external design screenshot that has no Tileflow receipt, use the separate exploratory
-primitive:
-
-```ts
-import {analyzeTileflowCaptureReference} from '@tileflow/capture';
-
-const analysis = await analyzeTileflowCaptureReference(result.captures[0], referencePng, {
-  region: {x: 0, y: 0, width: 1200, height: 760},
-});
-```
-
-It strictly validates the bounded non-interlaced PNG, reports dimensions and up to 16 deterministic
-quantized palette entries, and—only for equal dimensions—exact/perceptual changed pixels, mean
-absolute RGBA-channel difference, a high-contrast diff PNG, and
-`appearance.actualMinusReference` with the same signed profile. It does not assert scene/runtime
-compatibility, accept a receipt for the reference, or create a baseline.