@tileflow/dev 0.1.0-alpha.40 → 0.1.0-alpha.42

package/README.md

@@ -59,6 +59,9 @@ The artifact plan exposes files and observed inputs from the same generation. St
 `styles[map][theme]`, never as an implicit default-theme alias. Keep that generation alive for the
 whole operation, then release it. Do not reconstruct its asset list from directory guesses.
 
+Generated style files use compact JSON in both stable and immutable generation paths. Their
+parsed contents are unchanged; format the JSON in your editor when inspecting a generated file.
+
 Map-owned tree models are prepared alongside icons and embedded in the styles. Custom tools that
 compile icons separately can use `prepareTileflowMapTreeModels` from `@tileflow/dev/icons` with
 the map's model directories, base directory, working directory, target and diagnostic path. Pass
@@ -82,6 +85,10 @@ 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.
+Web output includes `families/<map>.json` and its immutable generation copy. The version-3
+manifest selects that shared document; conventional theme JSON remains available for exports.
+Web artifacts include semantic runtime colour programs. Native artifacts keep concrete styles.
+Changing SDK/map package versions requires rebuilding and publishing the new artifacts.
 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.

package/dist/artifacts.js

@@ -32,7 +32,7 @@ import {
   usesTileflowLineBackgroundGlyphs,
   writeTileflowArtifactPlan,
   writeTileflowBuildArtifacts
-} from "./chunk-AVJMTXW5.js";
+} from "./chunk-OQCK4AXD.js";
 import {
   getTileflowAssetBasePath,
   getTileflowAssetFileName,

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

@@ -57,6 +57,7 @@ import {
   createStylesFromCatalog,
   createStylesFromCatalogWithInspection,
   createTileflowMapBuildManifest,
+  createTileflowStyleFamily,
   tileflowMapBuildManifestFileName
 } from "@tileflow/core/build";
 import { parseTileflowRuntimeManifest } from "@tileflow/core/manifest";
@@ -67,6 +68,59 @@ import {
   tileflowNativeBuildRecordFileName,
   TileflowNativeCompatibilityError as TileflowNativeCompatibilityError4
 } from "@tileflow/core/native-profile";
+import { prepareTileflowStyleFamilyForRendering } from "@tileflow/core/runtime";
+
+// src/family-style-resources.ts
+function rebaseTileflowFamilyStyle(style, mapName, themeName) {
+  const rebase = (value) => {
+    let start = 0;
+    let end = value.length;
+    while (start < end && value.charCodeAt(start) <= 32) start++;
+    while (end > start && value.charCodeAt(end - 1) <= 32) end--;
+    const reference = value.slice(start, end);
+    if (/^[\\/]/u.test(reference) || /^[a-z][a-z\d+.-]*:/iu.test(reference)) return value;
+    const target = !reference || /^[?#]/u.test(reference) ? `${themeName}.json${reference}` : reference;
+    return `../styles/${mapName}/${target}`;
+  };
+  const property = (value, key2) => {
+    if (record(value) && typeof value[key2] === "string") value[key2] = rebase(value[key2]);
+  };
+  const result = structuredClone(style);
+  property(result, "glyphs");
+  if (typeof result.sprite === "string") result.sprite = rebase(result.sprite);
+  else if (Array.isArray(result.sprite))
+    for (const sprite of result.sprite) property(sprite, "url");
+  const fontFaces = result["font-faces"];
+  if (record(fontFaces))
+    for (const [family, face] of Object.entries(fontFaces)) {
+      if (typeof face === "string") fontFaces[family] = rebase(face);
+      else property(face, "url");
+    }
+  for (const source of Object.values(result.sources)) {
+    property(source, "url");
+    if (source.type === "geojson") property(source, "data");
+    for (const key2 of ["tiles", "urls"]) {
+      const value = source[key2];
+      if (Array.isArray(value))
+        source[key2] = value.map(
+          (url) => typeof url === "string" ? rebase(url) : url
+        );
+    }
+  }
+  const fonts = result.metadata?.["tileflow:fontFaces"];
+  if (Array.isArray(fonts)) for (const face of fonts) property(face, "source");
+  for (const key2 of ["tileflow:buildings", "tileflow:vegetation"]) {
+    const descriptor = result.metadata?.[key2];
+    if (!record(descriptor)) continue;
+    if (Array.isArray(descriptor.models))
+      for (const model of descriptor.models) property(model, "url");
+    property(descriptor.landmarks, "url");
+  }
+  return result;
+}
+function record(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
 
 // src/image-source-assets.ts
 import { createHash } from "crypto";
@@ -1446,6 +1500,7 @@ function prepareTileflowNativeStyles(input, assets, policy = {}) {
         Object.defineProperty(nativeFaces, face.family, { value: face.source, enumerable: true });
       }
       delete metadata[tileflowStyleFontFacesMetadataKey];
+      delete metadata["tileflow:colors"];
       const { projection: _projection, ...rest } = original;
       const style = {
         ...rest,
@@ -2031,8 +2086,8 @@ function optionalDiagnosticPath(value) {
 }
 function isTileflowMapResolutionDiagnostic(value, path) {
   if (!value || typeof value !== "object" || !path) return false;
-  const record = value;
-  return record.name === "TileflowMapResolutionError" && typeof record.code === "string" && typeof record.mapId === "string" && path.startsWith("/modules/") && !/[\p{Cc}]/u.test(path) && !/~(?:[^01]|$)/u.test(path);
+  const record2 = value;
+  return record2.name === "TileflowMapResolutionError" && typeof record2.code === "string" && typeof record2.mapId === "string" && path.startsWith("/modules/") && !/[\p{Cc}]/u.test(path) && !/~(?:[^01]|$)/u.test(path);
 }
 function removeSemanticResolutionPath(message, path) {
   if (!path) return message;
@@ -2264,11 +2319,15 @@ async function createTileflowArtifactPlan(prepared, options = {}) {
     throw new TileflowLocalTilesetProductionError();
   }
   const inspected = options.inspection ? createTileflowStylesWithInspection(prepared.project, {
+    runtimeColors: true,
     apiBaseUrl: options.apiBaseUrl,
     mapAssets: prepared.mapAssets
   }) : void 0;
   const compileStyles = renderer === "native" ? createStylesFromCatalog : createTileflowStyles;
   const compiledStyles = inspected?.styles ?? compileStyles(prepared.project, {
+    // Both renderers share compilation before Native's representation-only lowering.
+    // Native removes the web-only binding catalog after that common semantic pipeline.
+    runtimeColors: true,
     apiBaseUrl: options.apiBaseUrl,
     mapAssets: prepared.mapAssets
   });
@@ -2335,7 +2394,7 @@ async function createTileflowArtifactPlan(prepared, options = {}) {
     const stableManifest = renderer === "native" ? createManifest(prepared.project, {
       styleBaseUrl: nativePublicBase(options.styleBaseUrl ?? ".")
     }) : createFontAwareManifest(
-      createManifest(prepared.project, { styleBaseUrl: options.styleBaseUrl }),
+      createManifest(prepared.project, { styleBaseUrl: options.styleBaseUrl, families: true }),
       styles
     );
     const inputs = {
@@ -2409,6 +2468,9 @@ function getTileflowArtifactFiles(artifacts) {
   return getStableTileflowArtifactFiles(artifacts);
 }
 function getStableTileflowArtifactFiles(artifacts) {
+  for (const [mapName, themes] of Object.entries(artifacts.styles))
+    for (const themeName of Object.keys(themes))
+      assertTileflowArtifactFileName(`styles/${mapName}/${themeName}.json`);
   const files = [
     {
       contentType: "application/json; charset=utf-8",
@@ -2426,10 +2488,16 @@ function getStableTileflowArtifactFiles(artifacts) {
       ([mapName, themes]) => Object.entries(themes).map(([themeName, style]) => ({
         contentType: "application/json; charset=utf-8",
         fileName: `styles/${mapName}/${themeName}.json`,
-        source: `${JSON.stringify(style, null, 2)}
+        source: `${JSON.stringify(style)}
 `
       }))
     ),
+    ...!artifacts.nativeBuild ? Object.entries(artifacts.styles).map(([mapName, styles]) => ({
+      contentType: "application/json; charset=utf-8",
+      fileName: `families/${mapName}.json`,
+      source: `${JSON.stringify(prepareArtifactStyleFamily(mapName, styles))}
+`
+    })) : [],
     ...artifacts.assets,
     ...artifacts.nativeBuild ? [
       {
@@ -2442,6 +2510,18 @@ function getStableTileflowArtifactFiles(artifacts) {
   ];
   return validateArtifactFiles(files);
 }
+function prepareArtifactStyleFamily(mapName, styles) {
+  return prepareTileflowStyleFamilyForRendering(
+    createTileflowStyleFamily(
+      Object.fromEntries(
+        Object.entries(styles).map(([theme, style]) => [
+          theme,
+          rebaseTileflowFamilyStyle(style, mapName, theme)
+        ])
+      )
+    )
+  );
+}
 function validateArtifactFiles(files) {
   const seen = /* @__PURE__ */ new Set();
   for (const file of files) {
@@ -2464,6 +2544,13 @@ function createGenerationManifest(manifest, generation, assets) {
         mapName,
         {
           ...map,
+          ...map.familyUrl ? {
+            familyUrl: insertGenerationInPublicUrl(
+              map.familyUrl,
+              `families/${mapName}.json`,
+              generation
+            )
+          } : {},
           themes: Object.fromEntries(
             Object.entries(map.themes).map(([themeName, theme]) => [
               themeName,
@@ -2517,7 +2604,7 @@ function createGenerationArtifactFiles(artifacts, generation, nativeUrls) {
       return {
         contentType: "application/json; charset=utf-8",
         fileName: `${prefix}/styles/${mapName}/${themeName}.json`,
-        source: `${JSON.stringify(generationStyle, null, 2)}
+        source: `${JSON.stringify(generationStyle)}
 `
       };
     })
@@ -2526,7 +2613,34 @@ function createGenerationArtifactFiles(artifacts, generation, nativeUrls) {
     ...asset,
     fileName: `${prefix}/${asset.fileName}`
   }));
-  return validateArtifactFiles([...stableFiles, ...immutableStyles, ...immutableAssets]);
+  const immutableFamilies = artifacts.nativeBuild ? [] : Object.keys(artifacts.styles).map((mapName) => ({
+    contentType: "application/json; charset=utf-8",
+    fileName: `${prefix}/families/${mapName}.json`,
+    source: `${JSON.stringify(
+      prepareArtifactStyleFamily(
+        mapName,
+        Object.fromEntries(
+          Object.keys(artifacts.styles[mapName]).map((theme) => [
+            theme,
+            JSON.parse(
+              String(
+                immutableStyles.find(
+                  (file) => file.fileName === `${prefix}/styles/${mapName}/${theme}.json`
+                ).source
+              )
+            )
+          ])
+        )
+      )
+    )}
+`
+  }));
+  return validateArtifactFiles([
+    ...stableFiles,
+    ...immutableStyles,
+    ...immutableFamilies,
+    ...immutableAssets
+  ]);
 }
 function createFontAwareManifest(manifest, styles) {
   const maps = Object.fromEntries(
@@ -3014,12 +3128,13 @@ function assertTileflowArtifactFileName(fileName) {
   assertSafeManagedFileName(fileName);
   const logicalName = fileName.replace(/^generations\/[a-f0-9]{64}\//, "");
   const styleMatch = /^styles\/([^/]+)\/([^/]+)\.json$/u.exec(logicalName);
+  const familyMatch = /^families\/([^/]+)\.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 || 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)) {
+  if (fileName === "manifest.json" || fileName === tileflowMapBuildManifestFileName || fileName === tileflowNativeBuildRecordFileName || styleMatch && tileflowMapIdSchema.safeParse(styleMatch[1]).success && tileflowThemeNameSchema.safeParse(styleMatch[2]).success || familyMatch && tileflowMapIdSchema.safeParse(familyMatch[1]).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}`);

package/dist/preview.js

@@ -1306,7 +1306,7 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
       const runtimeLayerVisibility = {};
       globalThis.__tileflowPreviewScene = coreScene;
       globalThis.__tileflowRuntimeVisibility = (id, visible) => {
-        if (!['tileflow-buildings-3d','tileflow-trees-3d','tileflow-street-lights'].includes(id)) return undefined;
+        if (!['tileflow-buildings-scene-3d','tileflow-trees-3d','tileflow-street-lights'].includes(id)) return undefined;
         const previewMap = globalThis.__tileflowPreviewMap;
         if (typeof visible === 'boolean') {
           runtimeLayerVisibility[id] = visible;
@@ -1320,7 +1320,7 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
       globalThis.__tileflowDescribeRuntimeLayers = () => {
         const {buildings, vegetation, streetLights} = coreScene.scene ?? {};
         return {
-          ...(buildings ? {"tileflow-buildings-3d": {controller:"Buildings 3D", state:{visible:runtimeLayerVisibility["tileflow-buildings-3d"] !== false, shown:coreScene.buildingsShown, scale:buildings.scale}, stats:buildings.stats}} : {}),
+          ...(buildings ? {"tileflow-buildings-scene-3d": {controller:"Buildings 3D", state:{visible:runtimeLayerVisibility["tileflow-buildings-scene-3d"] !== false, shown:coreScene.buildingsShown, scale:buildings.scale}, stats:buildings.stats}} : {}),
           ...(vegetation ? {"tileflow-trees-3d": {controller:"Vegetation", state:{visible:runtimeLayerVisibility["tileflow-trees-3d"] !== false, representation:vegetation.representation}, stats:vegetation.stats}} : {}),
           ...(streetLights ? {"tileflow-street-lights": {controller:"Street lights", state:{visible:runtimeLayerVisibility["tileflow-street-lights"] !== false, mounted:true}, stats:streetLights.stats}} : {})
         };
@@ -1376,7 +1376,7 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
             void (threeDimensionalEnabled ? scene.show({transition: {duration, mode: animation === "fade" ? "fade" : "grow"}}) : scene.hide(instant));
           }
           // The inspector can hide the buildings alone.
-          const showBuildings = threeDimensionalEnabled && runtimeLayerVisibility["tileflow-buildings-3d"] !== false;
+          const showBuildings = threeDimensionalEnabled && runtimeLayerVisibility["tileflow-buildings-scene-3d"] !== false;
           if (scene.buildings && coreScene.buildingsShown !== showBuildings) {
             coreScene.buildingsShown = showBuildings;
             void (showBuildings ? scene.buildings.show(instant) : scene.buildings.hide(instant));
@@ -1438,6 +1438,7 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
             if (toggle !== "building" && toggle !== "landmark") continue;
             // Core's 3D buildings stand in for the compiled extrusion where the style describes them.
             const replaced = toggle === "building" && reads.metadata()?.["tileflow:buildings"];
+            if (replaced) continue; // Core switches the native extrusion only when its scene can draw.
             const visibility = this.enabled && !replaced ? "visible" : "none";
             if (this.map.getLayoutProperty(layer.id, "visibility") !== visibility) {
               this.map.setLayoutProperty(layer.id, "visibility", visibility);
@@ -1636,6 +1637,7 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
           // Core's 3D buildings and trees stand in for compiled extrusions and flat trees.
           const replacedByCore =
             threeDimensionalToggle === "building" && styleMetadata["tileflow:buildings"];
+          if (replacedByCore && !hideLayer) continue;
           const toggleVisibility = replacedByCore
             ? "none"
             : threeDimensionalToggle === "building" || threeDimensionalToggle === "landmark"

package/dist/server.js

@@ -5,7 +5,7 @@ import {
   parseTileflowLineBackgroundGlyphPath,
   tileflowArtifactSessionSchemaVersion,
   tileflowLineBackgroundGlyphRoute
-} from "./chunk-AVJMTXW5.js";
+} from "./chunk-OQCK4AXD.js";
 import {
   getTileflowAssetBasePath,
   getTileflowAssetFileName,
@@ -3387,6 +3387,11 @@ function createTileflowDevRequestHandler(options = {}) {
         }
         return compactJsonResponse(style);
       }
+      if (path.startsWith("/families/")) {
+        const fileName = path.slice(1);
+        const asset = artifacts.files?.find((candidate) => candidate.fileName === fileName);
+        return asset ? assetResponse(asset) : jsonResponse2({ error: "Unknown map family." }, 404);
+      }
       if (path.startsWith("/icons/")) {
         const assetName = path.replace(/^\/+/, "");
         const asset = artifacts.assets.find((candidate) => candidate.fileName === assetName);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/dev",
-  "version": "0.1.0-alpha.40",
+  "version": "0.1.0-alpha.42",
   "license": "Apache-2.0",
   "description": "Node development utilities for Tileflow configs and builds.",
   "type": "module",
@@ -83,7 +83,7 @@
   "dependencies": {
     "@mapbox/vector-tile": "3.0.0",
     "@maplibre/maplibre-gl-style-spec": "26.4.4",
-    "@tileflow/core": ">=0.1.0-alpha.44 <0.1.0-beta.0",
+    "@tileflow/core": ">=0.1.0-alpha.46 <0.1.0-beta.0",
     "chokidar": "6.0.0",
     "fontkit": "2.0.4",
     "jiti": "^2.7.0",
@@ -95,14 +95,14 @@
     "three": "0.185.1"
   },
   "devDependencies": {
-    "@tileflow/maps": "0.1.0-alpha.17"
+    "@tileflow/maps": "0.1.0-alpha.18"
   },
   "optionalDependencies": {
     "sharp": "0.35.5"
   },
   "scripts": {
     "build": "tsup src/artifacts.ts src/config.ts src/fonts.ts src/icons.ts src/inspect.ts src/preview.ts src/server.ts src/tilesets.ts src/validation.ts --format esm --dts --clean --platform node --external sharp && tsup --config tsup.inspector.config.ts",
-    "test": "tsx --test test/*.test.ts",
+    "test": "tsx --test --test-concurrency=2 test/*.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "lint": "tsc -p tsconfig.json --noEmit",
     "verify": "pnpm run typecheck && pnpm run test"