@tileflow/dev 0.1.0-alpha.37 → 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
 
@@ -66,6 +64,8 @@ compile icons separately can use `prepareTileflowMapTreeModels` from `@tileflow/
 the map's model directories, base directory, working directory, target and diagnostic path. Pass
 its `models` result as `preparedAssets.models` when compiling the style; retain its source
 identities and watch paths when managing revisions. The artifact pipeline does this automatically.
+A GLB whose materials name only `bark`, `leaves`, `fronds` or `stem` is a tree model; any other
+is a building model, whose materials name its parts.
 
 To write production output rather than manage it in memory:
 
@@ -82,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.
@@ -122,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.
 
@@ -138,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
@@ -163,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.
@@ -184,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.
@@ -254,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-UKWAQKLH.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-5RT4CHSK.js";
-import "./chunk-7C4F6GAX.js";
+} from "./chunk-C4VPHZ3F.js";
+import "./chunk-RTU7TD4M.js";
 import "./chunk-KDFTE4Q5.js";
 import {
   defaultTileflowConfigPath

package/dist/{chunk-UKWAQKLH.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-5RT4CHSK.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");