tileflow 0.1.0-alpha.13 → 0.1.0-alpha.14

package/README.md

@@ -53,7 +53,8 @@ workspaces are advanced repository orchestration, not a second application autho
 
 ## Map development tools
 
-Use `describe` for bounded language discovery, `inspect` for configuration and data, `capture`
+Use `describe` for bounded language discovery (`describe themes --json` lists palette requirements
+and optional time-of-day composition), `inspect` for configuration and data, `capture`
 for reproducible evidence, and `compare` for saved captures, semantic edits, styles, references or
 baselines. `preview` opens Map DevTools. These tools work in independent projects with
 custom maps and data; official maps are optional.

package/dist/index.js

@@ -3922,7 +3922,7 @@ function isRecord(value) {
 
 // src/describe-command.ts
 function registerDescribeCommand(program2) {
-  program2.command("describe").description("Discover domains and query the generated authoring schema without loading a map").argument("[topic]", "domain name, expressions, or schema").option(
+  program2.command("describe").description("Discover domains and query the generated authoring schema without loading a map").argument("[topic]", "domain name, themes, expressions, or schema").option(
     "--ref <pointer>",
     "exact local schema reference, such as #/$defs/TileflowRoadsModuleOptions"
   ).option("--path <pointer>", "JSON Pointer within the selected topic or schema", "").option("--limit <count>", "maximum returned tree entries (1\u2013500)", "80").option("--depth <count>", "maximum returned tree depth (1\u201312)", "4").option("--json", "print deterministic bounded JSON").action(
@@ -3933,7 +3933,7 @@ function registerDescribeCommand(program2) {
         const manifest = tileflowAuthoringManifest2;
         let value;
         let schemaRef;
-        if (options.ref || topic && topic !== "expressions") {
+        if (options.ref || topic && topic !== "expressions" && topic !== "themes") {
           const schema = await loadPackagedSchema();
           const domain = manifest.domains.find((entry) => entry.name === topic);
           if (topic && topic !== "schema" && !domain)
@@ -3946,6 +3946,8 @@ function registerDescribeCommand(program2) {
           value = selectJsonPointer(schema, schemaRef.replace(/^#/u, ""));
         } else if (topic === "expressions") {
           value = manifest.expressions;
+        } else if (topic === "themes") {
+          value = manifest.themes;
         } else {
           value = {
             domains: manifest.domains.map(({ name, api, optionsSchemaRef }) => ({
@@ -3953,7 +3955,7 @@ function registerDescribeCommand(program2) {
               api,
               schemaRef: optionsSchemaRef
             })),
-            topics: ["expressions", "schema"],
+            topics: ["expressions", "schema", "themes"],
             commands: ["describe", "inspect", "capture", "compare", "preview"]
           };
         }
@@ -4126,11 +4128,14 @@ function printFeatureInspectError(error) {
 }
 
 // src/hosted-client.ts
-import { serializeTileflowFontBundleManifest } from "@tileflow/core";
+import {
+  serializeTileflowFontBundleManifest,
+  serializeTileflowModelBundleManifest
+} from "@tileflow/core";
 
 // src/hosted-response.ts
 import { z as z2 } from "zod";
-import { tileflowIconPackageLimits } from "@tileflow/core";
+import { tileflowIconPackageLimits, tileflowModelBundleLimits } from "@tileflow/core";
 var maximumHostedResponseBytes = 1024 * 1024;
 var safeTextSchema = z2.string().min(1).max(300).refine((value) => !/[\p{Cc}]/u.test(value));
 var safeIdentifierSchema = z2.string().min(1).max(200).regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/u);
@@ -4168,6 +4173,14 @@ var hostedFontBundleResponseSchema = z2.object({
   id: z2.string().regex(/^fnb_[A-Za-z0-9_-]{16,64}$/u),
   totalBytes: z2.number().int().positive().max(Number.MAX_SAFE_INTEGER)
 });
+var hostedModelBundleResponseSchema = z2.object({
+  baseUrl: publicHttpUrlSchema,
+  changed: z2.boolean().optional(),
+  contentHash: z2.string().regex(/^[a-f0-9]{64}$/u),
+  id: z2.string().regex(/^mdb_[A-Za-z0-9_-]{16,64}$/u),
+  modelCount: z2.number().int().positive().max(tileflowModelBundleLimits.maxModelCount),
+  totalBytes: z2.number().int().positive().max(tileflowModelBundleLimits.maxPackageBytes)
+});
 var hostedStatusStyleSchema = z2.object({
   environment: safeTextSchema,
   key: safeStorageKeySchema,
@@ -4520,6 +4533,42 @@ async function uploadHostedFontBundle(api, bundle, options = {}) {
   }
   return { ok: true, value };
 }
+async function uploadHostedModelBundle(api, bundle, options = {}) {
+  const formData = new FormData();
+  formData.append(
+    "manifest",
+    new Blob([serializeTileflowModelBundleManifest(bundle.manifest)], {
+      type: "application/json"
+    }),
+    "manifest.json"
+  );
+  for (const file of bundle.files) {
+    const bytes = new Uint8Array(file.source.byteLength);
+    bytes.set(file.source);
+    formData.append(
+      `file:${encodeURIComponent(file.fileName)}`,
+      new Blob([bytes.buffer], { type: file.contentType }),
+      file.fileName
+    );
+  }
+  const response = await requestHostedJson(
+    api.apiUrl,
+    `/v1/model-bundles/${encodeURIComponent(bundle.contentHash)}`,
+    { body: formData, headers: authorizationHeaders(api.apiKey, api.mapId), method: "PUT" },
+    options
+  );
+  if (!response.ok) return { ok: false, status: response.status };
+  const value = parseResponse(
+    response,
+    hostedModelBundleResponseSchema,
+    "Model bundle upload response"
+  );
+  const publicBaseUrl = new URL(value.baseUrl);
+  if (value.contentHash !== bundle.contentHash || value.modelCount !== bundle.manifest.models.length || value.totalBytes !== bundle.manifest.models.reduce((total, model) => total + model.byteLength, 0) || publicBaseUrl.pathname !== `/model-bundles/${value.id}` || publicBaseUrl.search !== "") {
+    throw new Error("Model bundle upload response did not confirm the submitted bundle.");
+  }
+  return { ok: true, value };
+}
 async function fetchHostedMapStatus(api, options = {}) {
   const response = await requestHostedJson(
     api.apiUrl,
@@ -4773,22 +4822,6 @@ function inspectTileflowHostedCompatibility(project, styles) {
         });
       }
     }
-    const own = /* @__PURE__ */ new Set();
-    for (const style of Object.values(themes)) {
-      const models = style?.metadata?.["tileflow:buildings"]?.models;
-      if (!Array.isArray(models)) continue;
-      for (const entry of models) {
-        const { model, url } = entry ?? {};
-        if (typeof url === "string" && url.includes(`models/${mapName}/`) && typeof model === "string")
-          own.add(model);
-      }
-    }
-    if (own.size > 0)
-      issues.push({
-        map: mapName,
-        message: `Hosted deploy does not take a map's own 3D building models yet. Map ${mapName} places ${[...own].sort(compareCodeUnits5).join(", ")}; keep the map local or remove them from buildings.threeDimensional.models.`,
-        path: `maps.${mapName}.modules.buildings.threeDimensional.models`
-      });
   }
   return issues;
 }
@@ -4797,17 +4830,36 @@ function cloneStyle(style) {
 }
 
 // src/model-assets.ts
-import { prepareTileflowMapTreeModels } from "@tileflow/dev/icons";
+import {
+  createTileflowModelBundle,
+  prepareTileflowMapTreeModels
+} from "@tileflow/dev/icons";
 async function prepareModelAssets(project, options) {
-  const assets = {};
+  const prepared = { assets: {}, bundles: {}, identities: {} };
   for (const [name, map] of Object.entries(project.maps)) {
     if (!map.models?.length) continue;
-    const prepared = await prepareTileflowMapTreeModels(map.models, {
+    const models = await prepareTileflowMapTreeModels(map.models, {
       ...options,
       cwd: process.cwd(),
       configPath: `maps.${name}.models`
     });
-    assets[name] = { models: prepared.models };
+    prepared.assets[name] = { models: models.models };
+    const bundle = await createTileflowModelBundle(models.buildings);
+    if (bundle) prepared.bundles[name] = bundle;
+    if (models.identities.length > 0) prepared.identities[name] = models.identities;
+  }
+  return prepared;
+}
+function mapAssetsWithBuildingModels(prepared, baseOf) {
+  const assets = { ...prepared.assets };
+  for (const [mapName, bundle] of Object.entries(prepared.bundles)) {
+    const base = baseOf(mapName, bundle).replace(/\/+$/u, "");
+    assets[mapName] = {
+      ...assets[mapName],
+      buildingModels: Object.fromEntries(
+        bundle.manifest.models.map((model) => [model.id, `${base}/${model.file}`])
+      )
+    };
   }
   return assets;
 }
@@ -4850,13 +4902,17 @@ async function prepareNativeHostedDeploy(options) {
   const iconPackage = binding ? compiledIcons.packages.find((entry) => entry.contentHash === binding.packageHash) : void 0;
   const sprite = binding ? `${apiOrigin}/sprites/preflight/${binding.packageHash}/sprite` : void 0;
   const modelAssets = await prepareModelAssets(project, { baseDirectory, target: "hosted" });
+  if (modelAssets.bundles[mapName])
+    throw failure(
+      "A deployment with --with-native does not take a map's own 3D building models yet. Deploy without --with-native, or remove them from the map's models directories."
+    );
   const mapAssets = {
-    ...modelAssets,
+    ...modelAssets.assets,
     ...Object.fromEntries(
       compiledIcons.bindings.map((entry) => [
         entry.mapName,
         {
-          ...modelAssets[entry.mapName],
+          ...modelAssets.assets[entry.mapName],
           icons: {
             ids: entry.iconIds,
             sprite: `${apiOrigin}/sprites/preflight/${entry.packageHash}/sprite`
@@ -9348,7 +9404,10 @@ program.command("validate").description("Validate a Tileflow config").option("-c
       const mapAssets = createCompiledMapAssets(
         compiledIcons,
         (binding) => options.target === "hosted" ? `${normalizeUrl(options.apiBaseUrl)}/sprites/preflight/${binding.packageHash}/sprite` : `/tileflow/icons/${binding.mapName}/sprite`,
-        modelAssets
+        mapAssetsWithBuildingModels(
+          modelAssets,
+          (mapName) => options.target === "hosted" ? `${normalizeUrl(options.apiBaseUrl)}/model-bundles/preflight` : `/tileflow/models/${mapName}`
+        )
       );
       failureDefaults = { code: "STYLE_INVALID", phase: "style-validation" };
       const compiledStyles = createTileflowStyles2(project, {
@@ -9824,7 +9883,7 @@ program.command("deploy").description("Deploy maps to Tileflow and write the fro
     const preflightMapAssets = createCompiledMapAssets(
       compiledIcons,
       (binding) => `${apiUrl}/sprites/preflight/${binding.packageHash}/sprite`,
-      modelAssets
+      mapAssetsWithBuildingModels(modelAssets, () => `${apiUrl}/model-bundles/preflight`)
     );
     const compiledPreflightStyles = createTileflowStyles2(deploymentProject, {
       apiBaseUrl: apiUrl,
@@ -9898,6 +9957,25 @@ program.command("deploy").description("Deploy maps to Tileflow and write the fro
       );
       hostedSpriteByPackageHash.set(iconPackage.contentHash, uploaded.value.spriteUrl);
     }
+    const hostedModelBaseByHash = /* @__PURE__ */ new Map();
+    const uniqueModelBundles = [
+      ...new Map(
+        Object.values(modelAssets.bundles).map((bundle) => [bundle.contentHash, bundle])
+      ).values()
+    ].sort((left, right) => left.contentHash.localeCompare(right.contentHash));
+    for (const bundle of uniqueModelBundles) {
+      const uploaded = await uploadHostedModelBundle(api, bundle);
+      if (!uploaded.ok) {
+        logError(`Model bundle upload failed: ${uploaded.status}.`);
+        process.exitCode = 1;
+        return;
+      }
+      const action = uploaded.value.changed === false ? "Reused" : "Uploaded";
+      logSuccess(
+        `${action} 3D model bundle (${plural(bundle.manifest.models.length, "model")}, ${formatBytes3(uploaded.value.totalBytes)}, ${bundle.contentHash.slice(0, 12)}).`
+      );
+      hostedModelBaseByHash.set(bundle.contentHash, uploaded.value.baseUrl);
+    }
     const hostedMapAssets = createCompiledMapAssets(
       compiledIcons,
       (binding) => {
@@ -9905,7 +9983,11 @@ program.command("deploy").description("Deploy maps to Tileflow and write the fro
         if (!sprite) throw new Error(`Missing hosted sprite URL for map ${binding.mapName}`);
         return sprite;
       },
-      modelAssets
+      mapAssetsWithBuildingModels(modelAssets, (mapName, bundle) => {
+        const base = hostedModelBaseByHash.get(bundle.contentHash);
+        if (!base) throw new Error(`Missing hosted model bundle URL for map ${mapName}.`);
+        return base;
+      })
     );
     const compiledHostedStyles = createTileflowStyles2(deploymentProject, {
       apiBaseUrl: api.apiUrl,
@@ -9996,7 +10078,12 @@ program.command("deploy").description("Deploy maps to Tileflow and write the fro
                   fileName: `icons/${mapName}/${file.fileName}`,
                   source: file.source
                 })),
-                ...hostedFonts.bundles[mapName]?.files ?? []
+                ...hostedFonts.bundles[mapName]?.files ?? [],
+                ...(modelAssets.bundles[mapName]?.files ?? []).map((file) => ({
+                  contentType: file.contentType,
+                  fileName: `models/${mapName}/${file.fileName}`,
+                  source: file.source
+                }))
               ],
               lineage: deploymentProject.mapMetadata?.[mapName]?.lineage ?? [
                 { id: map.id, mapVersion: map.version }
@@ -10005,7 +10092,8 @@ program.command("deploy").description("Deploy maps to Tileflow and write the fro
               sourceAssets: {
                 fonts: hostedFonts.sourceIdentities[mapName] ?? [],
                 icons: compiledIcons.sourceIdentities[mapName] ?? [],
-                ...compiledIcons.compositions[mapName] ? { iconComposition: compiledIcons.compositions[mapName] } : {}
+                ...compiledIcons.compositions[mapName] ? { iconComposition: compiledIcons.compositions[mapName] } : {},
+                ...modelAssets.identities[mapName] ? { models: modelAssets.identities[mapName] } : {}
               },
               styles: styles[mapName]
             }
@@ -10018,11 +10106,13 @@ program.command("deploy").description("Deploy maps to Tileflow and write the fro
       const iconBinding = bindingsByMap.get(mapName);
       const iconPackage = iconBinding ? packagesByHash.get(iconBinding.packageHash) : void 0;
       const fontBundle = hostedFonts.bundles[mapName];
+      const modelBundle = modelAssets.bundles[mapName];
       return {
         iconBinding,
         iconComposition: compiledIcons.compositions[mapName],
         iconPackage,
         fontBundle,
+        modelBundle,
         mapName,
         teamSources: hostedThemeFamilies[mapName].teamSources,
         buildManifest: {
@@ -10042,6 +10132,7 @@ program.command("deploy").description("Deploy maps to Tileflow and write the fro
         iconComposition,
         iconPackage,
         mapName,
+        modelBundle,
         teamSources,
         styles: themeStyles
       } = deployment;
@@ -10076,6 +10167,7 @@ program.command("deploy").description("Deploy maps to Tileflow and write the fro
           } : {},
           ...iconComposition ? { iconComposition } : {},
           ...fontBundle ? { fontBundle: { contentHash: fontBundle.contentHash } } : {},
+          ...modelBundle ? { modelBundle: { contentHash: modelBundle.contentHash } } : {},
           source
         },
         `Deploy response for ${mapName}`

package/docs/hosted-authentication-and-deploy.md

@@ -184,8 +184,19 @@ Hosted deploy currently rejects local or package-owned web fonts before authenti
 writes. Use self-hosted delivery or an explicit public glyph provider. Enabling managed font bundles
 requires a separately deployed ownership, quota, retention, and immutable-delivery contract.
 
-For both managed resource kinds, `assetSetSha256` remains a separate per-map output identity. It
+A map's own 3D building models (the building models of its `models` directories) deploy as one
+model bundle per map. Deploy prepares them as `build` does, uploads the bundle with
+`PUT /v1/model-bundles/:contentHash` after authentication and before the first style write, compiles
+each placement's `url` at the bundle's hosted address and publishes the style with the bundle's
+content hash. Byte-identical bundles are reused by content hash. A bundle holds at most 64 models,
+16 MiB a prepared file and 32 MiB together, and shares the organization's hosted-storage pool like
+icon packages. Upload success must confirm the submitted `contentHash`, model count and byte total,
+one opaque `mdb_<id>` and the query-free `/model-bundles/<id>` base URL. A deploy with
+`--with-native` rejects a map's own building models, because MapLibre Native draws no models.
+
+For every managed resource kind, `assetSetSha256` remains a separate per-map output identity. It
 hashes each generated file's exact portable name, media type, byte count, and SHA-256 using Core's
 asset-set v1 contract; it does not hash only the icon-package manifest. Hosted must
 confirm the immutable resource bytes, reconstruct those same per-file identities (including the
-`icons/<mapId>/` prefix), and reject the Style when the submitted build-manifest hash diverges.
+`icons/<mapId>/` and `models/<mapId>/` prefixes), and reject the Style when the submitted
+build-manifest hash diverges.

package/docs/local-visual-feedback.md

@@ -62,8 +62,8 @@ authoring:
 ```sh
 # Two maps or themes from one config.
 npx tileflow preview \
-  --map harad --theme light \
-  --against-map ferraris --against-theme light
+  --map baedeker --theme light \
+  --against-map map-1777 --against-theme light
 
 # Or compare against another config.
 npx tileflow preview \

package/docs/map-authoring.md

@@ -25,6 +25,7 @@ Start with bounded queries, then request more detail at the returned JSON Pointe
 ```sh
 npx tileflow describe --json
 npx tileflow describe roads --path /properties/classes --json
+npx tileflow describe themes --json
 npx tileflow inspect --domain roads --limit 80 --json
 npx tileflow inspect compiled --domain roads --theme dark --json
 npx tileflow compare configs --from-config before/tileflow.config.ts --to-config after/tileflow.config.ts --json
@@ -54,6 +55,12 @@ Inspection includes resolved inheritance, merge provenance, and the theme contra
 returns compilation diagnostics and a report, not the complete Style JSON. Add `--inspection` only
 when physical output provenance is needed; those layer IDs are not stable authoring targets.
 
+`describe themes` lists the minimal palette roles and optional time-of-day behavior. Compiled
+inspection includes `report.decisions` for resolved color roles and selected module defaults,
+with the effective value, source, reason and override guidance. Query it with
+`inspect compiled --path /report/decisions --limit 80 --json`. It describes semantic decisions,
+not every final paint property; config inspection retains inheritance provenance separately.
+
 For a normal config, map selection is implicit. Paired `--from-config` and `--to-config` compare
 two ordinary configs. Workspace comparisons use their documented explicit map selectors; do not
 mix the paired-config and same-workspace forms.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tileflow",
-  "version": "0.1.0-alpha.13",
+  "version": "0.1.0-alpha.14",
   "license": "Apache-2.0",
   "description": "CLI-only tools for Tileflow config, capture, visual testing, and deploy.",
   "type": "module",
@@ -39,9 +39,9 @@
     "@tileflow/capture": ">=0.1.0-alpha.31 <0.1.0-beta.0",
     "@tileflow/coordinates": ">=0.1.0-alpha.2 <0.1.0-beta.0",
     "@tileflow/coordinates-runtime": ">=0.1.0-alpha.5 <0.1.0-beta.0",
-    "@tileflow/core": ">=0.1.0-alpha.35 <0.1.0-beta.0",
-    "@tileflow/dev": ">=0.1.0-alpha.32 <0.1.0-beta.0",
-    "@tileflow/maps": ">=0.1.0-alpha.9 <0.1.0-beta.0",
+    "@tileflow/core": ">=0.1.0-alpha.36 <0.1.0-beta.0",
+    "@tileflow/dev": ">=0.1.0-alpha.33 <0.1.0-beta.0",
+    "@tileflow/maps": ">=0.1.0-alpha.10 <0.1.0-beta.0",
     "commander": "^15.0.0",
     "hono": "4.13.7",
     "picocolors": "^1.1.1",