@tileflow/core 0.1.0-alpha.22 → 0.1.0-alpha.24

package/README.md

@@ -753,11 +753,15 @@ sources supplied by an application remain the application's responsibility.
 
 For local resolution, the Style URL is based on the logical tileset ID and remains stable when Dev
 creates a new immutable snapshot. Physical generation IDs and local content hashes never enter the
-Style representation. A new Dev request or Capture operation resolves current and retains that
-snapshot for its duration; an operation already in progress keeps its acquired generation.
+Style representation. Each Dev PMTiles request retains the snapshot it resolved until its response
+is prepared, and strong generation ETags prevent one cached PMTiles read from silently combining
+ranges from different generations. Standalone Capture retains one snapshot for its complete render.
+Application Capture does not freeze every local dataset across the complete screenshot window; the
+application's development server remains authoritative for its per-read generation.
 
 `local` does not make build output own or publish the archive. Production builds reject unresolved
-local PMTiles. Use explicit managed publication or an application-owned production source.
+local PMTiles. Explicitly publish the tileset through Tileflow's managed upload, validation,
+versioning, and hosting flow, or serve it from infrastructure owned by the application.
 
 One overlay owns one ordered group of ordinary MapLibre Style Layers. Public layer IDs are retained
 for `map.on(...)`, feature queries, and application state. Placement is one of `above-water`,

package/THIRD_PARTY_NOTICES.md

@@ -1,6 +1,6 @@
 # Third-party notices
 
-`@tileflow/core/browser` embeds `maplibre-contour` 0.1.0, `PMTiles` 4.4.0, and `fflate` 0.8.2 so
+`@tileflow/core/browser` embeds `maplibre-contour` 0.1.0, `PMTiles` 4.4.0, and `fflate` 0.8.3 so
 contour and local archive rendering remain self-contained. The complete upstream licenses follow.
 
 ## maplibre-contour 0.1.0
@@ -203,7 +203,7 @@ OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 ---
 
-## fflate 0.8.2
+## fflate 0.8.3
 
 MIT License
 

package/dist/browser.js

@@ -2833,7 +2833,7 @@ function mutableThresholds(thresholds) {
   );
 }
 
-// ../../node_modules/.pnpm/fflate@0.8.2/node_modules/fflate/esm/browser.js
+// ../../node_modules/.pnpm/fflate@0.8.3/node_modules/fflate/esm/browser.js
 var u8 = Uint8Array;
 var u16 = Uint16Array;
 var i32 = Int32Array;
@@ -3027,6 +3027,7 @@ var ec = [
   "stream finished",
   "no stream handler",
   ,
+  // determined by compression function
   "no callback",
   "invalid UTF-8 data",
   "extra field too long",

package/dist/build.js

@@ -7984,7 +7984,7 @@ function insertTileflowOverlays(input) {
   for (const placement of tileflowOverlayPlacements) {
     const overlayLayers = groups.get(placement);
     if (!overlayLayers?.length) continue;
-    const index = insertionIndex(layers, placement);
+    const index = tileflowOverlayInsertionIndex(layers, placement);
     layers = [...layers.slice(0, index), ...overlayLayers, ...layers.slice(index)];
   }
   return { identities, layers };
@@ -8011,7 +8011,7 @@ function cloneJson18(value) {
     Object.entries(value).map(([key, child]) => [key, cloneJson18(child)])
   );
 }
-function insertionIndex(layers, placement) {
+function tileflowOverlayInsertionIndex(layers, placement) {
   const threshold = {
     "above-water": tileflowLayerSlots.indexOf("building-areas"),
     "below-roads": tileflowLayerSlots.indexOf("transport-areas"),
@@ -12483,6 +12483,55 @@ function isSafeArtifactName(value) {
   });
 }
 
+// src/cartography/overlay-placement-manifest.ts
+var tileflowOverlayPlacementManifestMetadataKey = "tileflow:overlay-placement-manifest";
+var tileflowOverlayPlacementManifestSchemaVersion = 1;
+function createTileflowOverlayPlacementManifest(layers) {
+  const anchors = Object.fromEntries(
+    tileflowOverlayPlacements.map((placement) => {
+      const index = tileflowOverlayInsertionIndex(layers, placement);
+      const id = index < layers.length ? layers[index]?.id : void 0;
+      if (id !== void 0 && typeof id !== "string") {
+        throw new Error(`Tileflow overlay placement ${placement} resolved an invalid layer ID.`);
+      }
+      return [placement, id ?? null];
+    })
+  );
+  return {
+    anchors,
+    schemaVersion: tileflowOverlayPlacementManifestSchemaVersion
+  };
+}
+function assertTileflowOverlayPlacementManifestLayers(manifest, layers) {
+  if (manifest.schemaVersion !== tileflowOverlayPlacementManifestSchemaVersion) {
+    throw new Error("Tileflow overlay placement manifest schema version is unsupported.");
+  }
+  const keys = Object.keys(manifest.anchors);
+  if (keys.length !== tileflowOverlayPlacements.length || keys.some((key, index) => key !== tileflowOverlayPlacements[index])) {
+    throw new Error("Tileflow overlay placement manifest keys are invalid.");
+  }
+  const layerIndexes = new Map(
+    layers.flatMap(
+      (layer, index) => typeof layer.id === "string" ? [[layer.id, index]] : []
+    )
+  );
+  let previous = -1;
+  for (const placement of tileflowOverlayPlacements) {
+    const anchor = manifest.anchors[placement];
+    const index = anchor === null ? layers.length : layerIndexes.get(anchor);
+    if (index === void 0) {
+      throw new Error(`Tileflow overlay placement manifest references missing layer: ${anchor}`);
+    }
+    if (index < previous) {
+      throw new Error("Tileflow overlay placement manifest anchor order is invalid.");
+    }
+    previous = index;
+  }
+  if (manifest.anchors["above-labels"] !== null) {
+    throw new Error("Tileflow above-labels placement must not have a physical anchor.");
+  }
+}
+
 // src/cartography/physical-planner.ts
 var roadHighZoom = 15;
 var linePaintDefaults = {
@@ -13563,11 +13612,19 @@ function compileSemanticStyleInternal(input, options, inspect, onReport) {
       type: data.schema.fields.poiType
     })
   );
+  const overlayPlacementManifest = runCompilationPhase(
+    "finalization",
+    () => createTileflowOverlayPlacementManifest(plannedLayers)
+  );
   const layers = runCompilationPhase("finalization", () => finalizeTileflowLayers(plannedLayers));
   runCompilationPhase(
     "finalization",
     () => assertTileflowInteractionManifestLayers(interactionManifest, layers)
   );
+  runCompilationPhase(
+    "finalization",
+    () => assertTileflowOverlayPlacementManifestLayers(overlayPlacementManifest, layers)
+  );
   const glyphs = runCompilationPhase("assets", () => resolveGlyphs(config));
   const sprite = options.preparedAssets?.icons?.sprite;
   const primarySource = {
@@ -13632,6 +13689,7 @@ function compileSemanticStyleInternal(input, options, inspect, onReport) {
       ...Object.keys(loweredOverlays.identities).length > 0 ? { "tileflow:overlays": loweredOverlays.identities } : {},
       "tileflow:sourceRequirements": sourceRequirements,
       ...interactionManifest ? { [tileflowInteractionManifestMetadataKey]: interactionManifest } : {},
+      [tileflowOverlayPlacementManifestMetadataKey]: overlayPlacementManifest,
       "tileflow:modules": Object.entries(modules).filter(([, module]) => !isRecord9(module) || module.enabled !== false).map(([name]) => name).sort(),
       ...config.view ? { "tileflow:view": config.view } : {}
     }

package/dist/index.js

@@ -9032,7 +9032,7 @@ function insertTileflowOverlays(input) {
   for (const placement of tileflowOverlayPlacements) {
     const overlayLayers = groups.get(placement);
     if (!overlayLayers?.length) continue;
-    const index = insertionIndex(layers, placement);
+    const index = tileflowOverlayInsertionIndex(layers, placement);
     layers = [...layers.slice(0, index), ...overlayLayers, ...layers.slice(index)];
   }
   return { identities, layers };
@@ -9059,7 +9059,7 @@ function cloneJson18(value) {
     Object.entries(value).map(([key, child]) => [key, cloneJson18(child)])
   );
 }
-function insertionIndex(layers, placement) {
+function tileflowOverlayInsertionIndex(layers, placement) {
   const threshold = {
     "above-water": tileflowLayerSlots.indexOf("building-areas"),
     "below-roads": tileflowLayerSlots.indexOf("transport-areas"),
@@ -13586,6 +13586,55 @@ function isSafeArtifactName(value) {
   });
 }
 
+// src/cartography/overlay-placement-manifest.ts
+var tileflowOverlayPlacementManifestMetadataKey = "tileflow:overlay-placement-manifest";
+var tileflowOverlayPlacementManifestSchemaVersion = 1;
+function createTileflowOverlayPlacementManifest(layers) {
+  const anchors = Object.fromEntries(
+    tileflowOverlayPlacements.map((placement) => {
+      const index = tileflowOverlayInsertionIndex(layers, placement);
+      const id = index < layers.length ? layers[index]?.id : void 0;
+      if (id !== void 0 && typeof id !== "string") {
+        throw new Error(`Tileflow overlay placement ${placement} resolved an invalid layer ID.`);
+      }
+      return [placement, id ?? null];
+    })
+  );
+  return {
+    anchors,
+    schemaVersion: tileflowOverlayPlacementManifestSchemaVersion
+  };
+}
+function assertTileflowOverlayPlacementManifestLayers(manifest, layers) {
+  if (manifest.schemaVersion !== tileflowOverlayPlacementManifestSchemaVersion) {
+    throw new Error("Tileflow overlay placement manifest schema version is unsupported.");
+  }
+  const keys = Object.keys(manifest.anchors);
+  if (keys.length !== tileflowOverlayPlacements.length || keys.some((key, index) => key !== tileflowOverlayPlacements[index])) {
+    throw new Error("Tileflow overlay placement manifest keys are invalid.");
+  }
+  const layerIndexes = new Map(
+    layers.flatMap(
+      (layer, index) => typeof layer.id === "string" ? [[layer.id, index]] : []
+    )
+  );
+  let previous = -1;
+  for (const placement of tileflowOverlayPlacements) {
+    const anchor = manifest.anchors[placement];
+    const index = anchor === null ? layers.length : layerIndexes.get(anchor);
+    if (index === void 0) {
+      throw new Error(`Tileflow overlay placement manifest references missing layer: ${anchor}`);
+    }
+    if (index < previous) {
+      throw new Error("Tileflow overlay placement manifest anchor order is invalid.");
+    }
+    previous = index;
+  }
+  if (manifest.anchors["above-labels"] !== null) {
+    throw new Error("Tileflow above-labels placement must not have a physical anchor.");
+  }
+}
+
 // src/cartography/physical-planner.ts
 init_expression_operators();
 var roadHighZoom = 15;
@@ -14686,11 +14735,19 @@ function compileSemanticStyleInternal(input, options, inspect, onReport) {
       type: data.schema.fields.poiType
     })
   );
+  const overlayPlacementManifest = runCompilationPhase(
+    "finalization",
+    () => createTileflowOverlayPlacementManifest(plannedLayers)
+  );
   const layers = runCompilationPhase("finalization", () => finalizeTileflowLayers(plannedLayers));
   runCompilationPhase(
     "finalization",
     () => assertTileflowInteractionManifestLayers(interactionManifest, layers)
   );
+  runCompilationPhase(
+    "finalization",
+    () => assertTileflowOverlayPlacementManifestLayers(overlayPlacementManifest, layers)
+  );
   const glyphs = runCompilationPhase("assets", () => resolveGlyphs(config));
   const sprite = options.preparedAssets?.icons?.sprite;
   const primarySource = {
@@ -14755,6 +14812,7 @@ function compileSemanticStyleInternal(input, options, inspect, onReport) {
       ...Object.keys(loweredOverlays.identities).length > 0 ? { "tileflow:overlays": loweredOverlays.identities } : {},
       "tileflow:sourceRequirements": sourceRequirements,
       ...interactionManifest ? { [tileflowInteractionManifestMetadataKey]: interactionManifest } : {},
+      [tileflowOverlayPlacementManifestMetadataKey]: overlayPlacementManifest,
       "tileflow:modules": Object.entries(modules).filter(([, module]) => !isRecord9(module) || module.enabled !== false).map(([name]) => name).sort(),
       ...config.view ? { "tileflow:view": config.view } : {}
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/core",
-  "version": "0.1.0-alpha.22",
+  "version": "0.1.0-alpha.24",
   "license": "Apache-2.0",
   "description": "Typed Tileflow config and MapLibre style compiler.",
   "type": "module",
@@ -26,10 +26,7 @@
   "files": [
     "dist",
     "LICENSE",
-    "NOTICE",
-    "THIRD_PARTY_NOTICES.md",
-    "GENERATED_OUTPUT_LICENSE.md",
-    "TRADEMARKS.md"
+    "THIRD_PARTY_NOTICES.md"
   ],
   "exports": {
     ".": {

package/GENERATED_OUTPUT_LICENSE.md

@@ -1,21 +0,0 @@
-# Tileflow generated-output grant
-
-In addition to the rights granted by the Apache License, Version 2.0, Tileflow.dev contributors
-grant recipients a perpetual, worldwide, non-exclusive, no-charge, royalty-free right to use,
-reproduce, modify, display, perform, distribute, sublicense, and commercialize the Tileflow-owned
-parts of output generated by this SDK.
-
-Covered output includes compiled map styles, manifests, receipts, sprites, glyph artifacts, static
-render descriptions, and other build artifacts produced from Tileflow maps or application maps.
-Original Tileflow map definitions, icons, and patterns distributed by `@tileflow/maps` may likewise
-be used, modified, embedded, deployed, and redistributed as part of personal or commercial maps and
-applications.
-
-This grant does not relicense third-party software, fonts, icons, map data, datasets, imagery, or
-other input material. Their licenses, attribution requirements, notices, and use restrictions
-continue to apply to the relevant source and generated output. You are responsible for having the
-rights necessary to process and distribute your own inputs.
-
-This grant does not provide access to Tileflow hosted services or grant rights in Tileflow names,
-logos, or marks. The SDK and generated output are provided without warranties or conditions beyond
-those required by applicable law.

package/NOTICE

@@ -1,9 +0,0 @@
-Tileflow SDK
-Copyright 2026 Tileflow.dev contributors
-
-This product includes software and original map artwork developed by Tileflow.dev contributors.
-
-Third-party materials distributed with a package remain subject to their own license and notice
-files. See THIRD_PARTY_NOTICES.md and asset-adjacent license files where present.
-
-The Tileflow names and marks are not licensed under the Apache License 2.0. See TRADEMARKS.md.

package/TRADEMARKS.md

@@ -1,10 +0,0 @@
-# Tileflow trademarks
-
-The Apache License, Version 2.0, and the Tileflow generated-output grant do not grant permission to
-use the Tileflow name, `tileflow.dev`, logos, service marks, product names, or other Tileflow brand
-features except for reasonable and customary use that truthfully describes the origin of the SDK or
-compatibility with Tileflow, and for reproducing required notices.
-
-You may not use Tileflow brand features in a way that suggests sponsorship, endorsement, or an
-official Tileflow product when none exists. Third-party names and marks remain the property of their
-respective owners.