@tileflow/dev 0.1.0-alpha.38 → 0.1.0-alpha.39

package/README.md

@@ -37,8 +37,6 @@ The CLI's local Inspector provides a dockable layer inspector, loaded tiles, ass
 controls and frame timing. Its element picker selects a layer and evaluates its rules using the
 feature clicked on the map.
 Debug's Overdraw overlay uses a heatmap with a visible pass-count legend and explanation.
-See [Inspector and compiler inspection](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/docs/local-comparison-workbench-and-compiler-inspection.md)
-for interaction details and observation limits.
 
 ## Prepare a generation
 
@@ -84,6 +82,8 @@ await writeTileflowBuildArtifacts({
 
 Serve the complete output. The writer installs immutable generation assets before changing the
 manifest pointer, tracks its own files, and refuses to replace a hosted manifest by default.
+Native builds retain embedded PNG image sources as hashed files beside the styles, so their
+resource URLs remain portable without permitting data URLs in the native profile.
 `overwriteHostedManifest: true` is an explicit migration option, not a normal build setting.
 Production rejects unresolved local PMTiles; publish data explicitly or provide an application-owned
 production source. Local development snapshots do not publish or redistribute the original dataset.
@@ -124,7 +124,12 @@ export async function createMapHandler() {
 The caller mounts `fetch` in its server and calls `close()` on shutdown. This factory does not open
 a listener. Sessions follow config imports and local asset inputs, retain the last good generation
 after invalid edits, and publish structured state changes through `subscribe()`.
+Session creation waits for the first valid generation or a settled invalid result, including
+when a watched edit replaces the initial build before it finishes.
 Watching follows aliased working directories, including newly created or removed icon metadata.
+Package assets resolve from the config directory. Linked package assets inside the selected working
+tree are watched too; installed assets in `node_modules` remain immutable.
+
 A single startup consistency check complements ordinary watcher notifications; no recurring scan
 is added.
 
@@ -140,7 +145,7 @@ for local PMTiles inspection, and `/validation` for diagnostics. `/preview` is t
 contract, including experimental preview-only rendering; it does not promise hosted support.
 The package has no root entry point. `/server` also exposes the reusable Inspector shell. The CLI
 connects appearance controls and shared browser context through its optional local
-workflow adapter; see the [Inspector guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/docs/local-comparison-workbench-and-compiler-inspection.md).
+workflow adapter.
 The navigation contains **Map**, **Layers**, **Tiles**, **Assets**, **Debug** and **Diagnostics**.
 Zoom, Pitch and Bearing appear as **Z**, **P** and **B** directly below it, with live Zoom and Pitch
 sliders and **Copy for AI**. Pitch and Bearing each have an inline reset to 0° within the map's
@@ -165,7 +170,6 @@ feature's layer in **Rules**. Rules expose live colors, numeric sliders, enums,
 defaults, and checkboxes for temporarily disabling paint, layout and filters. Diagnosis, Data and
 Origin explain renderer state, sample features and available compiler provenance. **Visible**
 filters to the current viewport. Context can be reviewed as Markdown or JSON before copying.
-See [Layers inspection](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/docs/layers-inspection.md).
 
 **Tiles** shows resident map tiles as a coordinate grid and source-grouped list. Source layers,
 Features and Info expose raw payload sizes, consumer layers, paginated features, GeoJSON and bounds.
@@ -186,8 +190,6 @@ drawing work. Findings open the affected layer and rule, show available evidence
 for an agent. Unavailable observations and stale results remain explicit. **Diagnosis** in
 Layers describes the selected layer's zoom, visibility and feature-rule context without turning
 empty viewport queries into errors. Legacy `tab=beacon` links open Diagnostics.
-See [Map design diagnostics](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/docs/map-design-diagnostics.md)
-for detectors, sampling and interpretation limits.
 
 The preview's globe rim follows the rendered canvas silhouette, including camera and viewport
 changes, and fades between zooms 3 and 6. Its colors follow the map's atmosphere when declared.
@@ -256,22 +258,8 @@ publish anything. Every normal entry point composes declared shared descriptors
 catalog publication and lock maintenance stay in the `tileflow` CLI, which is the only writer of
 `tileflow.icons.lock.json` and the only caller that resolves `latest`.
 
-## Detailed guides
-
-These references are also included under `docs/` in the installed package:
-
-- [Building model preparation](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/docs/building-models.md): colour slots, architectural roles, ambient visibility and compatibility.
-- [Native artifact preparation](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/docs/native-artifacts.md): static compatibility, renderer-qualified output, and limitations.
-- [Artifact lifecycle](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/docs/artifact-lifecycle.md): generations, immutable snapshots, provenance, and cleanup.
-- [Local comparison and inspection](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/docs/local-comparison-workbench-and-compiler-inspection.md): Inspector controls and preview-only models.
-- [Config diagnostics](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/docs/structured-config-inspection-and-diagnostics.md): bounded, machine-readable inspection.
-- [PMTiles inspection](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/docs/bounded-pmtiles-resource-inspection.md): metadata, sampling limits, and requested properties.
-- [Feature and icon inspection](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/docs/bounded-vector-feature-inspection.md): supported sources, icon compilation, and delivered-pixel hashes.
-
-For an installed release, prefer its declarations and packaged guides over newer source on `main`.
-
 ## Recolorable icons
 
 Declare SDF defaults and optional stretch/content layout in `tileflow.icons.json` beside ordinary artwork. Preparation
 verifies both densities and rejects mixed representations within one symbol layer, including
-fallbacks and local overrides. See [Author recolorable and adaptable icons](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/docs/native-icons.md) for the input profile, diagnostics and recovery.
+fallbacks and local overrides.

package/dist/artifacts.js

@@ -32,20 +32,20 @@ import {
   usesTileflowLineBackgroundGlyphs,
   writeTileflowArtifactPlan,
   writeTileflowBuildArtifacts
-} from "./chunk-MRFNAWWR.js";
+} from "./chunk-AVJMTXW5.js";
 import {
   getTileflowAssetBasePath,
   getTileflowAssetFileName,
   joinTileflowPublicUrl,
   normalizeTileflowBasePath,
   resolveTileflowArtifactPublicUrls
-} from "./chunk-UTRO4IBQ.js";
+} from "./chunk-FOMTSCOP.js";
 import {
   encodeTileflowLandmarkRegion,
   packageTileflowLandmarkTile,
   prepareTileflowBuildingModel
-} from "./chunk-54VM4SNV.js";
-import "./chunk-7C4F6GAX.js";
+} from "./chunk-C4VPHZ3F.js";
+import "./chunk-RTU7TD4M.js";
 import "./chunk-KDFTE4Q5.js";
 import {
   defaultTileflowConfigPath

package/dist/{chunk-MRFNAWWR.js → chunk-AVJMTXW5.js}

@@ -4,11 +4,11 @@ import {
   joinTileflowPublicUrl,
   prepareTileflowStyleFonts,
   replaceTileflowStyleFontSources
-} from "./chunk-UTRO4IBQ.js";
+} from "./chunk-FOMTSCOP.js";
 import {
   getTileflowIconWatchPaths,
   prepareTileflowCatalogIcons
-} from "./chunk-54VM4SNV.js";
+} from "./chunk-C4VPHZ3F.js";
 import {
   TileflowStyleValidationError,
   normalizeTileflowStyleValidationIssues,
@@ -28,7 +28,7 @@ import {
 } from "./chunk-ONYQNLNA.js";
 
 // src/artifacts.ts
-import { createHash as createHash4 } from "crypto";
+import { createHash as createHash5 } from "crypto";
 import { realpathSync as realpathSync2 } from "fs";
 import {
   copyFile as copyFile2,
@@ -68,8 +68,32 @@ import {
   TileflowNativeCompatibilityError as TileflowNativeCompatibilityError4
 } from "@tileflow/core/native-profile";
 
+// src/image-source-assets.ts
+import { createHash } from "crypto";
+function prepareEmbeddedImageSources(input) {
+  const styles = structuredClone(input);
+  const assets = /* @__PURE__ */ new Map();
+  for (const [map, themes] of Object.entries(styles)) {
+    for (const style of Object.values(themes)) {
+      for (const source of Object.values(style.sources)) {
+        if (source.type !== "image" || typeof source.url !== "string") continue;
+        const match = /^data:image\/png;base64,([A-Za-z0-9+/]+={0,2})$/u.exec(source.url);
+        if (!match || match[1].length > 14 * 1024 * 1024) continue;
+        const bytes = Buffer.from(match[1], "base64");
+        if (bytes.length < 24 || !bytes.subarray(0, 8).equals(Buffer.from("89504e470d0a1a0a", "hex")))
+          continue;
+        const hash = createHash("sha256").update(bytes).digest("hex");
+        const fileName = `images/${map}/${hash}.png`;
+        assets.set(fileName, { contentType: "image/png", fileName, source: bytes });
+        source.url = `../../${fileName}`;
+      }
+    }
+  }
+  return { styles, assets: [...assets.values()] };
+}
+
 // src/line-background-glyphs.ts
-import { createHash, randomUUID } from "crypto";
+import { createHash as createHash2, randomUUID } from "crypto";
 import { lstat, mkdir, readFile, rename, rm, writeFile } from "fs/promises";
 import { resolve } from "path";
 import {
@@ -245,7 +269,7 @@ function absoluteHttpUrl(value) {
   }
 }
 function digest(value) {
-  return createHash("sha256").update(value).digest("hex").slice(0, 32);
+  return createHash2("sha256").update(value).digest("hex").slice(0, 32);
 }
 function hasCode(error, code) {
   return Boolean(error && typeof error === "object" && "code" in error && error.code === code);
@@ -567,25 +591,28 @@ function hasErrorCode(error, code) {
 }
 
 // src/native-artifacts.ts
-import { createHash as createHash2 } from "crypto";
 import {
   convertFilter,
   validateStyleMin
 } from "@maplibre/maplibre-gl-style-spec";
+import { createHash as createHash3 } from "crypto";
 import {
   getTileflowStyleFontFaces,
   serializeCanonicalJson,
   steadyTileflowNauticalLights,
-  tileflowStyleFontFacesMetadataKey,
   tileflowIconIdPattern,
-  tileflowIconPackageLimits
+  tileflowIconPackageLimits,
+  tileflowStyleFontFacesMetadataKey
 } from "@tileflow/core";
+import {
+  prepareTileflowNativePathGround
+} from "@tileflow/core/build";
 import {
   createTileflowNativeDiagnostic,
   TileflowNativeCompatibilityError,
   tileflowNativeProfileLimits,
-  validateTileflowNativeStyle,
-  validateTileflowNativePreparedStyle
+  validateTileflowNativePreparedStyle,
+  validateTileflowNativeStyle
 } from "@tileflow/core/native-profile";
 
 // src/native-layer-references.ts
@@ -1266,7 +1293,9 @@ function lowerTileflowNativeCompiledStyles(input, policy = {}) {
     styles[map] = {};
     for (const theme of Object.keys(input[map]).sort()) {
       const web = input[map][theme];
-      const original = steadyTileflowNauticalLights(web);
+      const steady = steadyTileflowNauticalLights(web);
+      const original = prepareTileflowNativePathGround(steady);
+      const pathGroundFallback = original !== steady;
       try {
         const options = { ...urlOptions(map, theme, policy), deferFontClosure: true };
         const pending = validateTileflowNativeStyle(original, options);
@@ -1324,12 +1353,13 @@ function lowerTileflowNativeCompiledStyles(input, policy = {}) {
         transformations.push({
           map,
           theme,
-          inputStyleSha256: createHash2("sha256").update(serializeCanonicalJson(web)).digest("hex"),
-          loweredStyleSha256: createHash2("sha256").update(serializeCanonicalJson(style)).digest("hex"),
+          inputStyleSha256: createHash3("sha256").update(serializeCanonicalJson(web)).digest("hex"),
+          loweredStyleSha256: createHash3("sha256").update(serializeCanonicalJson(style)).digest("hex"),
           inputLayers: lowered.inputLayers,
           outputLayers: lowered.outputLayers,
           projection: lowered.projection,
           ...lowered.sky ? { sky: lowered.sky } : {},
+          ...pathGroundFallback ? { pathGround: "ground-fallback" } : {},
           layers: lowered.layers,
           symbolOverlap: lowered.symbolOverlap
         });
@@ -1441,7 +1471,7 @@ function isNativeFontAsset(asset) {
   if (!/\.(?:ttf|otf)$/u.test(asset.fileName) || !["00010000", "4f54544f"].includes(signature))
     return false;
   const expectedHash = /-([a-f0-9]{64})\.(?:ttf|otf)$/u.exec(asset.fileName)?.[1];
-  return expectedHash === createHash2("sha256").update(bytes).digest("hex");
+  return expectedHash === createHash3("sha256").update(bytes).digest("hex");
 }
 function assertTileflowNativeGeneratedStyle(style, map, theme, policy = {}) {
   const issues = validateTileflowNativePreparedStyle(style, urlOptions(map, theme, policy));
@@ -1647,6 +1677,9 @@ var TileflowArtifactSessionImpl = class {
       await watcherReady;
     }
     await this.refresh("initial");
+    while (!this.#current && this.#state.status === "building" && !this.#closed) {
+      await Promise.all([...this.#refreshes]);
+    }
     if (this.#watcher && !this.#closed) {
       this.#startupCheckTimer = setTimeout(() => {
         this.#startupCheckTimer = void 0;
@@ -2050,7 +2083,7 @@ function boundDiagnosticText(value, limit) {
 }
 
 // src/hosted-native-artifacts.ts
-import { createHash as createHash3 } from "crypto";
+import { createHash as createHash4 } from "crypto";
 import { serializeCanonicalJson as serializeCanonicalJson2 } from "@tileflow/core";
 import {
   inferTileflowDataRequirements,
@@ -2062,7 +2095,7 @@ import {
   TileflowNativeCompatibilityError as TileflowNativeCompatibilityError3,
   createTileflowNativeDiagnostic as createTileflowNativeDiagnostic2
 } from "@tileflow/core/native-profile";
-var digest2 = (value) => createHash3("sha256").update(serializeCanonicalJson2(value)).digest("hex");
+var digest2 = (value) => createHash4("sha256").update(serializeCanonicalJson2(value)).digest("hex");
 var invalidSource = () => new TileflowNativeCompatibilityError3([
   createTileflowNativeDiagnostic2("NATIVE_UNSUPPORTED_SOURCE", "/sources")
 ]);
@@ -2239,7 +2272,8 @@ async function createTileflowArtifactPlan(prepared, options = {}) {
     apiBaseUrl: options.apiBaseUrl,
     mapAssets: prepared.mapAssets
   });
-  const nativeLowering = renderer === "native" ? lowerTileflowNativeCompiledStyles(compiledStyles, nativeUrls) : void 0;
+  const embeddedImages = renderer === "native" ? prepareEmbeddedImageSources(compiledStyles) : { styles: compiledStyles, assets: [] };
+  const nativeLowering = renderer === "native" ? lowerTileflowNativeCompiledStyles(embeddedImages.styles, nativeUrls) : void 0;
   const rendererStyles = nativeLowering?.styles ?? compiledStyles;
   if (renderer === "native")
     assertTileflowNativeCompiledStyles(prepared.project, rendererStyles, nativeUrls);
@@ -2262,7 +2296,7 @@ async function createTileflowArtifactPlan(prepared, options = {}) {
       }
       throw error;
     });
-    const assets = [...prepared.assets, ...preparedFonts.assets];
+    const assets = [...prepared.assets, ...preparedFonts.assets, ...embeddedImages.assets];
     const lineBackgroundGlyphs = renderer === "native" || options.target === "production" ? { providers: {}, styles: preparedFonts.styles } : prepareTileflowLineBackgroundGlyphs(preparedFonts.styles, {
       assetBaseUrl: resolveRendererAssetBaseUrl(options)
     });
@@ -2526,7 +2560,7 @@ function retargetLocalFontAssetUrl(source, assets, generation) {
 function getMapBuildAssets(mapName, assets, fontAssets) {
   const selected = /* @__PURE__ */ new Map();
   for (const asset of assets) {
-    if (asset.fileName.startsWith(`icons/${mapName}/`) || asset.fileName.startsWith(`models/${mapName}/`))
+    if (asset.fileName.startsWith(`icons/${mapName}/`) || asset.fileName.startsWith(`models/${mapName}/`) || asset.fileName.startsWith(`images/${mapName}/`))
       selected.set(asset.fileName, asset);
   }
   for (const asset of fontAssets) {
@@ -2537,7 +2571,7 @@ function getMapBuildAssets(mapName, assets, fontAssets) {
   );
 }
 function hashBytes(source) {
-  return createHash4("sha256").update(typeof source === "string" ? Buffer.from(source, "utf8") : Buffer.from(source)).digest("hex");
+  return createHash5("sha256").update(typeof source === "string" ? Buffer.from(source, "utf8") : Buffer.from(source)).digest("hex");
 }
 async function createTileflowBuildProvenance(cwd) {
   const projectDirectory = resolve4(cwd);
@@ -2981,10 +3015,11 @@ function assertTileflowArtifactFileName(fileName) {
   const logicalName = fileName.replace(/^generations\/[a-f0-9]{64}\//, "");
   const styleMatch = /^styles\/([^/]+)\/([^/]+)\.json$/u.exec(logicalName);
   const iconMatch = /^icons\/([^/]+)\/sprite(?:@2x)?\.(?:json|png)$/u.exec(logicalName);
+  const imageMatch = /^images\/([^/]+)\/[a-f0-9]{64}\.png$/u.exec(logicalName);
   const modelMatch = /^models\/([^/]+)\/[a-z0-9]+(?:-[a-z0-9]+)*-[a-f0-9]{16}\.glb$/u.exec(
     logicalName
   );
-  if (fileName === "manifest.json" || fileName === tileflowMapBuildManifestFileName || fileName === tileflowNativeBuildRecordFileName || styleMatch && tileflowMapIdSchema.safeParse(styleMatch[1]).success && tileflowThemeNameSchema.safeParse(styleMatch[2]).success || iconMatch && tileflowMapIdSchema.safeParse(iconMatch[1]).success || modelMatch && tileflowMapIdSchema.safeParse(modelMatch[1]).success || /^tilesets\/[A-Za-z0-9][A-Za-z0-9._-]{0,127}\.pmtiles$/u.test(logicalName) || /^fonts\/[a-z0-9]+(?:-[a-z0-9]+)*-[a-f0-9]{64}\.(?:otf|ttf|woff2)$/.test(logicalName) || /^fonts\/licenses\/license-[a-f0-9]{64}\.txt$/.test(logicalName)) {
+  if (fileName === "manifest.json" || fileName === tileflowMapBuildManifestFileName || fileName === tileflowNativeBuildRecordFileName || styleMatch && tileflowMapIdSchema.safeParse(styleMatch[1]).success && tileflowThemeNameSchema.safeParse(styleMatch[2]).success || iconMatch && tileflowMapIdSchema.safeParse(iconMatch[1]).success || imageMatch && tileflowMapIdSchema.safeParse(imageMatch[1]).success || modelMatch && tileflowMapIdSchema.safeParse(modelMatch[1]).success || /^tilesets\/[A-Za-z0-9][A-Za-z0-9._-]{0,127}\.pmtiles$/u.test(logicalName) || /^fonts\/[a-z0-9]+(?:-[a-z0-9]+)*-[a-f0-9]{64}\.(?:otf|ttf|woff2)$/.test(logicalName) || /^fonts\/licenses\/license-[a-f0-9]{64}\.txt$/.test(logicalName)) {
     return;
   }
   throw new Error(`Unexpected Tileflow managed artifact file name: ${fileName}`);
@@ -3024,7 +3059,7 @@ async function removeManagedFile(path) {
   }
 }
 function hashArtifactGeneration(files) {
-  const hash = createHash4("sha256");
+  const hash = createHash5("sha256");
   for (const file of files) {
     const source = typeof file.source === "string" ? Buffer.from(file.source, "utf8") : Buffer.from(file.source);
     hash.update(`${file.fileName}\0${file.contentType}\0${source.byteLength}\0`, "utf8");

package/dist/{chunk-54VM4SNV.js → chunk-C4VPHZ3F.js}

@@ -1,7 +1,7 @@
 import {
   TileflowAssetDirectoryError,
   resolveTileflowAssetDirectories
-} from "./chunk-7C4F6GAX.js";
+} from "./chunk-RTU7TD4M.js";
 
 // src/icons.ts
 import { readdir as readdir3, readFile as readFile2, realpath as realpath3, stat } from "fs/promises";

package/dist/{chunk-UTRO4IBQ.js → chunk-FOMTSCOP.js}

@@ -1,7 +1,7 @@
 import {
   TileflowAssetDirectoryError,
   resolveTileflowAssetDirectories
-} from "./chunk-7C4F6GAX.js";
+} from "./chunk-RTU7TD4M.js";
 import {
   isPathWithin
 } from "./chunk-D4OE4ITL.js";

package/dist/{chunk-7C4F6GAX.js → chunk-RTU7TD4M.js}

@@ -71,7 +71,9 @@ async function resolveTileflowAssetDirectories(directories, options) {
       let packageRoot;
       try {
         validatePackageDirectory(directory);
-        const requireFromProject = createRequire(resolve(realCwd, "__tileflow_config__.cjs"));
+        const requireFromProject = createRequire(
+          resolve(realBaseDirectory, "__tileflow_config__.cjs")
+        );
         let packageJson;
         try {
           packageJson = requireFromProject.resolve(`${directory.package}/package.json`);
@@ -120,7 +122,7 @@ async function resolveTileflowAssetDirectories(directories, options) {
         containmentRoot,
         packageOwned,
         realPath: realCandidate,
-        watch: !packageOwned
+        watch: !packageOwned || isPathInside(realCwd, realCandidate) && !realCandidate.split(/[\\/]/u).includes("node_modules")
       });
     } catch (error) {
       issues.push({

package/dist/fonts.js

@@ -4,8 +4,8 @@ import {
   getTileflowFontWatchPaths,
   prepareTileflowStyleFonts,
   replaceTileflowStyleFontSources
-} from "./chunk-UTRO4IBQ.js";
-import "./chunk-7C4F6GAX.js";
+} from "./chunk-FOMTSCOP.js";
+import "./chunk-RTU7TD4M.js";
 import "./chunk-D4OE4ITL.js";
 export {
   TileflowFontCompilationError,

package/dist/icons.js

@@ -17,8 +17,8 @@ import {
   storeTileflowIconSetArtifact,
   verifyTileflowIconArtifact,
   writeTileflowIconsLockfile
-} from "./chunk-54VM4SNV.js";
-import "./chunk-7C4F6GAX.js";
+} from "./chunk-C4VPHZ3F.js";
+import "./chunk-RTU7TD4M.js";
 export {
   TileflowIconCompilationError,
   compileTileflowIconPackages,

package/dist/preview.js

@@ -272,8 +272,8 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
       import * as maplibregl from "${basePath}/__runtime/maplibre-gl.mjs";
       import {createPreviewObserver} from "${basePath}/__runtime/inspector-observer.js";
       import {loadTileflowStyleFonts} from "${basePath}/__runtime/tileflow-browser.js";
-      import {attachTileflowLabelPlacement} from "${basePath}/__runtime/tileflow-browser.js";
-      import {registerTileflowContourProtocol} from "${basePath}/__runtime/tileflow-browser.js";
+      import {attachTileflowHorizonQueries, attachTileflowLabelPlacement} from "${basePath}/__runtime/tileflow-browser.js";
+      import {registerTileflowContourProtocol, registerTileflowPathGroundProtocol} from "${basePath}/__runtime/tileflow-browser.js";
       import {registerTileflowPmtilesProtocol} from "${basePath}/__runtime/tileflow-browser.js";
       import {attachTileflowNauticalLights, attachTileflowNotices} from "${basePath}/__runtime/tileflow-browser.js";
       import {attachTileflowAtmosphere, tileflowMaxPitch} from "${basePath}/__runtime/tileflow-browser.js";
@@ -1674,6 +1674,7 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
         maplibregl.setWorkerCount?.(mapWorkerCount);
         await loadTileflowStyleFonts(styleUrl, {fontFaces: previewFontFaces});
         registerTileflowContourProtocol({addProtocol: maplibregl.addProtocol});
+        registerTileflowPathGroundProtocol({addProtocol: maplibregl.addProtocol});
         registerTileflowPmtilesProtocol({addProtocol: maplibregl.addProtocol});
         const map = new maplibregl.Map({
           canvasContextAttributes: tileflowCanvasContextAttributes({antialias: mapAntialias}),
@@ -1689,6 +1690,7 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
         attachTileflowNauticalLights(map);
         attachTileflowAtmosphere(map);
         attachTileflowLabelPlacement(map);
+        attachTileflowHorizonQueries(map);
         inspectorObserver?.attach(map);
         installMapBenchmark(map);
         if (window.parent === window) map.addControl(new maplibregl.NavigationControl(), "top-right");

package/dist/server.js

@@ -5,16 +5,16 @@ import {
   parseTileflowLineBackgroundGlyphPath,
   tileflowArtifactSessionSchemaVersion,
   tileflowLineBackgroundGlyphRoute
-} from "./chunk-MRFNAWWR.js";
+} from "./chunk-AVJMTXW5.js";
 import {
   getTileflowAssetBasePath,
   getTileflowAssetFileName,
   joinTileflowPublicUrl,
   normalizeTileflowBasePath,
   resolveTileflowArtifactPublicUrls
-} from "./chunk-UTRO4IBQ.js";
-import "./chunk-54VM4SNV.js";
-import "./chunk-7C4F6GAX.js";
+} from "./chunk-FOMTSCOP.js";
+import "./chunk-C4VPHZ3F.js";
+import "./chunk-RTU7TD4M.js";
 import {
   TileflowStyleValidationError
 } from "./chunk-KDFTE4Q5.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/dev",
-  "version": "0.1.0-alpha.38",
+  "version": "0.1.0-alpha.39",
   "license": "Apache-2.0",
   "description": "Node development utilities for Tileflow configs and builds.",
   "type": "module",
@@ -27,7 +27,6 @@
   "files": [
     "dist",
     "ui-fonts",
-    "docs",
     "THIRD_PARTY_NOTICES.md",
     "LICENSE"
   ],
@@ -84,8 +83,8 @@
   "dependencies": {
     "@mapbox/vector-tile": "3.0.0",
     "@maplibre/maplibre-gl-style-spec": "26.4.4",
-    "@tileflow/core": ">=0.1.0-alpha.41 <0.1.0-beta.0",
-    "chokidar": "4.0.3",
+    "@tileflow/core": ">=0.1.0-alpha.43 <0.1.0-beta.0",
+    "chokidar": "6.0.0",
     "fontkit": "2.0.4",
     "jiti": "^2.7.0",
     "maplibre-gl": "6.13.0",
@@ -96,7 +95,7 @@
     "three": "0.185.1"
   },
   "devDependencies": {
-    "@tileflow/maps": "0.1.0-alpha.15"
+    "@tileflow/maps": "0.1.0-alpha.17"
   },
   "optionalDependencies": {
     "sharp": "0.35.5"

package/docs/artifact-lifecycle.md

@@ -1,152 +0,0 @@
-# Artifact lifecycle
-
-Start with the [@tileflow/dev guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/README.md) for installation and a complete first example.
-
-Node utilities used by the Tileflow CLI and build integrations.
-
-Most apps should use `tileflow`, `@tileflow/vite`, or `@tileflow/next` directly. Use this
-package when you are building a custom dev server, bundler plugin, or deployment adapter that needs
-to load and compile the single map exported by `tileflow.config.ts`.
-
-```ts
-import {createTileflowBuildArtifacts} from '@tileflow/dev/artifacts';
-
-const artifacts = await createTileflowBuildArtifacts({
-  config: 'tileflow.config.ts',
-});
-
-try {
-  // Serve, capture, or write this exact generation.
-} finally {
-  await artifacts.dispose?.();
-}
-```
-
-The integration surfaces are deliberately split: use `@tileflow/dev/artifacts` for source
-preparation and production outputs, `@tileflow/dev/server` for HTTP development handling,
-`@tileflow/dev/icons` for icon compilation, `@tileflow/dev/inspect` for safe resolved-config and
-bounded feature inspection, `@tileflow/dev/validation` for structured diagnostics, and
-`@tileflow/dev/preview` only for the local preview contract. The package has no root entry point.
-
-Artifact construction is an explicit `source map → resolved map → prepared map → ArtifactPlan`
-pipeline. Map inheritance resolves before its ordered local/package icon and font directories are
-prepared, and before the result reaches the core style compiler. The Node layer may normalize
-the map into an internal build catalog, but that catalog is orchestration state rather than another
-public authoring model. The plan exposes its complete files and observed input graph, so build
-adapters emit and watch the same generation instead of reconstructing either list themselves. Production manifests
-point to content-addressed `generations/<sha256>/...` theme styles and sprites; those immutable files are
-installed before the manifest pointer changes. Stable style paths are
-`styles/<map>/<theme>.json`; every manifest lookup resolves a concrete theme. The disk writer also stages the complete plan,
-records a managed-file inventory, rolls back caught filesystem failures, and removes only stale
-files named by its previous valid inventory. Stable `styles/` and `icons/` paths remain available,
-but generation-consistent consumers resolve maps through `manifest.json`.
-
-A local `hostedTileset()` path remains user-owned input. Dev performs bounded header, root-directory,
-and metadata checks, then creates an opaque immutable snapshot under
-`.tileflow/cache/pmtiles-snapshots/v1/`, using copy-on-write cloning when available and a safe copy
-otherwise. It does not hash the complete archive or traverse every leaf directory. Dev and Capture
-read only that snapshot. The current generation and already-started acquisitions retain references;
-a replaced generation accepts no new acquisitions and is collected after its last acquisition.
-The Style-facing path remains `tilesets/<logical-id>.pmtiles` across generations; physical snapshot
-identity stays out of Style JSON. Standalone Capture retains one generation for the complete render.
-Application Capture delegates PMTiles reads to the application's development server, where each
-range request retains its generation until that response is prepared; it does not lease one
-generation for the complete capture. Strong generation ETags make a cached PMTiles read restart if
-current changes between its ranges. Invalid edits keep the prior valid generation.
-
-Production writers reject unresolved local PMTiles instead of copying, content-addressing,
-deduplicating, retaining, or publishing them. Production data therefore requires an explicit
-`tileset publish` operation or an application-owned PMTiles location. Managed publication owns its
-separate exhaustive validation and version lifecycle. Startup removes snapshot generations owned
-by dead processes, and symlinked snapshot-store boundaries are rejected.
-
-Every plan also emits canonical `build-manifest.json` (schema version 1). For each map it records
-the leaf `mapVersion`, resolved lineage, effective icon/font source identities, semantic compiler ABI, and
-one entry per concrete theme with `colorScheme`, identity, inferred legacy `dataRequirements`,
-multi-source `sourceRequirements`, and `styleSha256`. The multi-source contract records each
-referenced vector source independently and records raster DEM source ID, encoding, and tile size;
-it therefore distinguishes Bathymetry vector bands from optional relief without inventing vector
-fields. `mapRevisionSha256` identifies the effective cartographic definition after `extends`;
-`assetSetSha256` for that map's generated runtime resources. Data requirements are derived from the
-final Style layers and fields rather than copied from a manually maintained allowlist, so disabled
-or overridden modules do not claim data they no longer use. Maps use the single implicit semantic
-compiler; its ABI remains a separate `semanticCompiler: {name, version}` build-manifest axis.
-
-The map revision is versioned and domain-separated. It contains the resolved cartographic design,
-semantic language version, effective public module/render-stack design, and effective icon/font
-identities. Map `id`, `name`, editorial `mapVersion`, default `view`, capture `scenes`, package
-SemVer, compiler ABI, local paths, timestamps, generated sprite/font output, and a
-concrete resolution of a floating World selector are deliberately outside it. Changing a shadowed
-ancestor does not change the revision; changing an effective cartographic override or source asset
-does. Lineage and the leaf `mapVersion` remain beside the hash for traceability, and Style JSON owns
-its compiled-output identity. Hosted browser policy is managed outside repository artifacts. The
-top-level `provenance` block records the exact participating Tileflow package versions and the
-nearest package-manager lockfile's format and content hash, without embedding its local path;
-provenance remains outside every map revision. The same portable block is available to Hosted
-adapters through
-`createTileflowBuildProvenance(cwd)`. The dev server exposes the complete document at
-`/build-manifest.json`.
-
-`createTileflowStyle`, `createTileflowStyles`, and artifact construction all enforce the same
-recursive JSON-value invariant and MapLibre style-spec semantics without fetching remote resources.
-The family API returns `styles[map][theme]`; it never flattens a default theme into a map alias.
-Invalid output throws `TileflowStyleValidationError` with at most 32 deterministic
-`map`/`path`/`message` issues; layer indexes are projected to stable layer IDs.
-
-For a watched, last-known-good integration, use one artifact session rather than recompiling each
-request independently:
-
-```ts
-import {createTileflowArtifactSession} from '@tileflow/dev/artifacts';
-
-const session = await createTileflowArtifactSession({
-  config: 'tileflow.config.ts',
-  watch: true,
-});
-
-const unsubscribe = session.subscribe((state) => {
-  // building -> ready, or invalid while getLastGoodArtifacts() remains available
-  console.log(state.status, state.generation);
-});
-
-unsubscribe();
-await session.close();
-```
-
-`getState()` and `getLastGoodArtifacts()` are borrowed synchronous views. Before starting async
-work, call `session.acquireArtifacts(generation?)` and release the returned acquisition in `finally`.
-A replacement stops new acquisitions of the old generation and deletes its snapshot after the last
-release. `close()` waits for outstanding acquisitions.
-
-The bounded watcher follows the config, transitive local TypeScript/JavaScript/JSON imports, and
-effective local icon/font directory inputs. Generations are monotonic, overlapping refreshes are latest-wins, invalid
-edits retain the last good snapshot, and caller-supplied output directories can be ignored to avoid
-feedback loops. `tileflow preview`, `capture --watch`, and
-framework adapters use this shared status
-vocabulary. The built-in preview reloads after its live event stream reconnects following a server
-restart, even when the replacement process begins again at generation 1.
-
-Custom preview servers use the exported map or one of its standalone scenes:
-
-```ts
-import {createTileflowDevRequestHandler} from '@tileflow/dev/server';
-
-const fetch = createTileflowDevRequestHandler({
-  config: 'tileflow.config.ts',
-  scene: 'madrid-mobile',
-});
-
-// On server shutdown:
-await fetch.close();
-```
-
-The handler does not close a caller-owned session.
-
-Map preview uses the exported map's `view` and accepts one concrete `theme`; scene preview uses its
-committed concrete theme, camera, and CSS viewport metadata from that same map. A scene does not
-repeat the map ID because its owner is implicit.
-`resolveTileflowPreview()` exposes the validated selection for custom integrations.
-Application-target scenes remain the responsibility of the application's development server. The
-built-in preview records longitude, latitude, zoom, bearing, and pitch in the current URL, so browser
-refreshes and config-triggered reloads return to the same view. Removing those query parameters
-restores the configured camera.