@tileflow/dev 0.1.0-alpha.33 → 0.1.0-alpha.34

package/README.md

@@ -258,6 +258,7 @@ catalog publication and lock maintenance stay in the `tileflow` CLI, which is th
 
 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): Map DevTools controls and preview-only models.

package/dist/artifacts.d.ts

@@ -1,10 +1,10 @@
 import { MapLibreStyle, TileflowViewConfig, TileflowStyleOptions } from '@tileflow/core';
-export { tileflowLandmarkRegionOf, tileflowLandmarkRegionZoom, tileflowLandmarkTileOf, tileflowLandmarkTileZoom } from '@tileflow/core';
+export { TileflowLandmarkFootprint, readTileflowLandmarkTileFootprints, tileflowLandmarkRegionOf, tileflowLandmarkRegionZoom, tileflowLandmarkTileOf, tileflowLandmarkTileZoom } from '@tileflow/core';
 import { TileflowBuildCatalog, TileflowBuildStyles, TileflowMapBuildManifestV1, TileflowRendererDeploymentArtifact, TileflowPreparedMapAssets, TileflowStyleInspection, TileflowMapBuildProvenanceV1 } from '@tileflow/core/build';
 import { TileflowRuntimeManifest } from '@tileflow/core/manifest';
 import { TileflowRenderer, TileflowNativeBuildRecord } from '@tileflow/core/native-profile';
-import { T as TileflowBuildAsset, a as TileflowIconResolutionOptions, P as PreparedTileflowBuildCatalog, b as TileflowSourceCatalog, c as PreparedTileflowCatalog } from './icons-BdOehQmB.js';
-export { d as TileflowBuildingModelLevels, e as TileflowLandmarkSource, f as encodeTileflowLandmarkRegion, p as packageTileflowLandmarkTile, g as prepareTileflowBuildingModel } from './icons-BdOehQmB.js';
+import { T as TileflowBuildAsset, a as TileflowIconResolutionOptions, P as PreparedTileflowBuildCatalog, b as TileflowSourceCatalog, c as PreparedTileflowCatalog } from './icons-BIHpw5Zy.js';
+export { d as TileflowBuildingModelLevels, e as TileflowLandmarkSource, f as encodeTileflowLandmarkRegion, p as packageTileflowLandmarkTile, g as prepareTileflowBuildingModel } from './icons-BIHpw5Zy.js';
 export { defaultTileflowConfigPath } from './config.js';
 
 /**

package/dist/artifacts.js

@@ -19,6 +19,7 @@ import {
   parseTileflowLineBackgroundGlyphPath,
   prepareTileflowHostedNativeDeployment,
   prepareTileflowLocalTilesets,
+  readTileflowLandmarkTileFootprints,
   refreshTileflowArtifactSession,
   tileflowArtifactInventoryFileName,
   tileflowArtifactPlanSchemaVersion,
@@ -31,7 +32,7 @@ import {
   usesTileflowLineBackgroundGlyphs,
   writeTileflowArtifactPlan,
   writeTileflowBuildArtifacts
-} from "./chunk-WJOF6USY.js";
+} from "./chunk-2F7LOYQI.js";
 import {
   getTileflowAssetBasePath,
   getTileflowAssetFileName,
@@ -43,7 +44,7 @@ import {
   encodeTileflowLandmarkRegion,
   packageTileflowLandmarkTile,
   prepareTileflowBuildingModel
-} from "./chunk-QYU4OW5A.js";
+} from "./chunk-5RT4CHSK.js";
 import "./chunk-7C4F6GAX.js";
 import "./chunk-KDFTE4Q5.js";
 import {
@@ -80,6 +81,7 @@ export {
   prepareTileflowBuildingModel,
   prepareTileflowHostedNativeDeployment,
   prepareTileflowLocalTilesets,
+  readTileflowLandmarkTileFootprints,
   refreshTileflowArtifactSession,
   resolveTileflowArtifactPublicUrls,
   tileflowArtifactInventoryFileName,

package/dist/{chunk-WJOF6USY.js → chunk-2F7LOYQI.js}

@@ -8,7 +8,7 @@ import {
 import {
   getTileflowIconWatchPaths,
   prepareTileflowCatalogIcons
-} from "./chunk-QYU4OW5A.js";
+} from "./chunk-5RT4CHSK.js";
 import {
   TileflowStyleValidationError,
   normalizeTileflowStyleValidationIssues,
@@ -2125,6 +2125,7 @@ async function prepareTileflowHostedNativeDeployment(input) {
 
 // src/artifacts.ts
 import {
+  readTileflowLandmarkTileFootprints,
   tileflowLandmarkRegionOf,
   tileflowLandmarkRegionZoom,
   tileflowLandmarkTileOf,
@@ -3096,6 +3097,7 @@ export {
   writeTileflowArtifactPlan,
   assertNoLocalTilesetsForProduction,
   assertTileflowSelfHostedManifestTarget,
+  readTileflowLandmarkTileFootprints,
   tileflowLandmarkRegionOf,
   tileflowLandmarkRegionZoom,
   tileflowLandmarkTileOf,

package/dist/{chunk-QYU4OW5A.js → chunk-5RT4CHSK.js}

@@ -25,7 +25,7 @@ import {
   sha256Hex as sha256Hex3,
   tileflowIconIdPattern,
   tileflowIconPackageLimits as tileflowIconPackageLimits4,
-  tileflowModelContentType as tileflowModelContentType2
+  tileflowModelContentType
 } from "@tileflow/core";
 
 // src/icon-composition.ts
@@ -949,17 +949,384 @@ import {
   compareCodeUnits as compareCodeUnits4,
   encodeTileflowModels,
   encodeTileflowTreeModel,
-  hashTileflowModelBundleManifest,
+  readTileflowLandmarkTileFootprints,
   serializeTileflowLandmarkRegion,
   tileflowLandmarkTileOf,
-  tileflowModelBundleFileName,
-  tileflowModelBundleLimits,
-  tileflowModelContentType,
+  tileflowModelFileName,
   tileflowTreeModelLimits as tileflowTreeModelLimits2
 } from "@tileflow/core";
 
 // src/building-model-mesh.ts
-import { tileflowModelLimits, tileflowModelParts } from "@tileflow/core";
+import {
+  tileflowModelDefaultLightingRoles,
+  tileflowModelLightingRoles,
+  tileflowModelLimits,
+  tileflowModelParts
+} from "@tileflow/core";
+
+// src/building-model-materials.ts
+import {
+  checkTileflowModelSurface,
+  tileflowModelTextureChannels
+} from "@tileflow/core";
+function buildingModelSurface(primitives) {
+  if (!primitives.some((primitive) => primitive.surface)) return void 0;
+  const attributes = [];
+  const materials = [];
+  const materialIds = /* @__PURE__ */ new Map();
+  const textures = [];
+  const textureIds = /* @__PURE__ */ new Map();
+  const ranges = [];
+  const emitters = [];
+  let indexCount = 0;
+  for (const primitive of primitives) {
+    const count = primitive.positions.length / 3;
+    const surface = primitive.surface;
+    if (surface) {
+      checkTileflowModelSurface(surface, count, primitive.indices.length);
+      for (const value of surface.attributes) attributes.push(value);
+      emitters.push(...surface.emitters ?? []);
+    } else {
+      for (let vertex = 0; vertex < count; vertex++) attributes.push(0, 0, 0, 0, 1, 1, 1, 1);
+    }
+    const remap = (surface?.materials ?? [{}]).map((material) => {
+      const copy = { ...material };
+      for (const channel of tileflowModelTextureChannels) {
+        const ref = copy[channel];
+        if (!ref) continue;
+        const texture = surface.textures[ref.texture];
+        let id2 = textureIds.get(texture);
+        if (id2 === void 0) {
+          id2 = textures.length;
+          textures.push(texture);
+          textureIds.set(texture, id2);
+        }
+        copy[channel] = { ...ref, texture: id2 };
+      }
+      const key = JSON.stringify(copy);
+      let id = materialIds.get(key);
+      if (id === void 0) {
+        id = materials.length;
+        materials.push(copy);
+        materialIds.set(key, id);
+      }
+      return id;
+    });
+    const sourceRanges = surface?.ranges ?? [
+      { from: 0, count: primitive.indices.length, material: 0 }
+    ];
+    for (const range of sourceRanges) {
+      const material = remap[range.material];
+      const previous = ranges.at(-1);
+      if (previous?.material === material && JSON.stringify(previous.emissiveBounds) === JSON.stringify(range.emissiveBounds))
+        ranges[ranges.length - 1] = { ...previous, count: previous.count + range.count };
+      else ranges.push({ ...range, from: indexCount + range.from, material });
+    }
+    indexCount += primitive.indices.length;
+  }
+  const result = { attributes, materials, textures, ranges, ...emitters.length ? { emitters } : {} };
+  checkTileflowModelSurface(result, attributes.length / 8, indexCount);
+  return result;
+}
+
+// src/building-model-occlusion.ts
+function buildingModelAmbientVisibility(mesh, { radius = 2, samples = 48 } = {}) {
+  if (!(radius > 0 && Number.isFinite(radius)) || !Number.isInteger(samples) || samples < 1 || samples > 256)
+    throw new RangeError("Model ambient visibility needs a positive radius and 1 to 256 samples.");
+  const { positions, normals, indices } = mesh;
+  const count = indices.length / 3;
+  const triangles2 = new Float64Array(count * 9);
+  const bounds = new Float64Array(count * 6);
+  const centres = new Float64Array(count * 3);
+  const order = Uint32Array.from({ length: count }, (_, i) => i);
+  for (let i = 0; i < count; i += 1) {
+    const a = indices[i * 3] * 3;
+    const b = indices[i * 3 + 1] * 3;
+    const c = indices[i * 3 + 2] * 3;
+    for (let axis = 0; axis < 3; axis += 1) {
+      const x = positions[a + axis], y = positions[b + axis], z = positions[c + axis];
+      triangles2[i * 9 + axis] = x;
+      triangles2[i * 9 + 3 + axis] = y - x;
+      triangles2[i * 9 + 6 + axis] = z - x;
+      bounds[i * 6 + axis] = Math.min(x, y, z);
+      bounds[i * 6 + 3 + axis] = Math.max(x, y, z);
+      centres[i * 3 + axis] = (x + y + z) / 3;
+    }
+  }
+  const nodes = [];
+  const build = (from, to) => {
+    const box = [Infinity, Infinity, Infinity, -Infinity, -Infinity, -Infinity];
+    for (let at = from; at < to; at += 1) {
+      const i = order[at] * 6;
+      for (let axis2 = 0; axis2 < 3; axis2 += 1) {
+        box[axis2] = Math.min(box[axis2], bounds[i + axis2]);
+        box[axis2 + 3] = Math.max(box[axis2 + 3], bounds[i + axis2 + 3]);
+      }
+    }
+    let axis = 0;
+    for (let next = 1; next < 3; next += 1)
+      if (box[next + 3] - box[next] > box[axis + 3] - box[axis]) axis = next;
+    const index = nodes.length;
+    const node = { bounds: box, from, to, left: -1, right: -1, axis };
+    nodes.push(node);
+    if (to - from > 8) {
+      order.subarray(from, to).sort((a, b) => centres[a * 3 + axis] - centres[b * 3 + axis] || a - b);
+      const middle = from + to >>> 1;
+      node.left = build(from, middle);
+      node.right = build(middle, to);
+    }
+    return index;
+  };
+  build(0, count);
+  const hemisphere = Array.from({ length: samples }, (_, i) => {
+    const r = Math.sqrt((i + 0.5) / samples), angle = i * Math.PI * (3 - Math.sqrt(5));
+    return [r * Math.cos(angle), r * Math.sin(angle), Math.sqrt(1 - r * r)];
+  });
+  const bias = Math.min(2e-3, radius * 1e-3);
+  const stack = new Int32Array(64);
+  const origin = [0, 0, 0];
+  const direction = [0, 0, 0];
+  const nearest = () => {
+    let best = radius, pending = 1;
+    stack[0] = 0;
+    while (pending > 0) {
+      const node = nodes[stack[--pending]];
+      if (!hitsBox(node.bounds, origin, direction, best)) continue;
+      if (node.left >= 0) {
+        const forward = direction[node.axis] >= 0;
+        stack[pending++] = forward ? node.right : node.left;
+        stack[pending++] = forward ? node.left : node.right;
+        continue;
+      }
+      for (let at = node.from; at < node.to; at += 1) {
+        const i = order[at] * 9;
+        const e1x = triangles2[i + 3], e1y = triangles2[i + 4], e1z = triangles2[i + 5];
+        const e2x = triangles2[i + 6], e2y = triangles2[i + 7], e2z = triangles2[i + 8];
+        const px = direction[1] * e2z - direction[2] * e2y;
+        const py = direction[2] * e2x - direction[0] * e2z;
+        const pz = direction[0] * e2y - direction[1] * e2x;
+        const determinant2 = e1x * px + e1y * py + e1z * pz;
+        if (Math.abs(determinant2) < 1e-12) continue;
+        const tx = origin[0] - triangles2[i], ty = origin[1] - triangles2[i + 1], tz = origin[2] - triangles2[i + 2];
+        const inverse = 1 / determinant2;
+        const u = (tx * px + ty * py + tz * pz) * inverse;
+        if (u < 0 || u > 1) continue;
+        const qx = ty * e1z - tz * e1y, qy = tz * e1x - tx * e1z, qz = tx * e1y - ty * e1x;
+        const v = (direction[0] * qx + direction[1] * qy + direction[2] * qz) * inverse;
+        if (v < 0 || u + v > 1) continue;
+        const distance = (e2x * qx + e2y * qy + e2z * qz) * inverse;
+        if (distance > bias && distance < best) best = distance;
+      }
+    }
+    return best;
+  };
+  const values = new Array(positions.length / 3);
+  const cache = /* @__PURE__ */ new Map();
+  for (let vertex = 0; vertex < values.length; vertex += 1) {
+    const at = vertex * 3;
+    const nx = normals[at], ny = normals[at + 1], nz = normals[at + 2];
+    const point3 = [positions[at], positions[at + 1], positions[at + 2]];
+    const key = [...point3, nx, ny, nz].map((v) => Math.round(v * 1e5)).join(",");
+    const cached = cache.get(key);
+    if (cached !== void 0) {
+      values[vertex] = cached;
+      continue;
+    }
+    const tangent = Math.abs(nz) < 0.9 ? [-ny, nx, 0] : [nz, 0, -nx];
+    const length = Math.hypot(...tangent);
+    if (length === 0) {
+      values[vertex] = 1;
+      continue;
+    }
+    for (let axis = 0; axis < 3; axis += 1) {
+      tangent[axis] /= length;
+      origin[axis] = point3[axis] + normals[at + axis] * bias;
+    }
+    const bitangent = [
+      ny * tangent[2] - nz * tangent[1],
+      nz * tangent[0] - nx * tangent[2],
+      nx * tangent[1] - ny * tangent[0]
+    ];
+    let visibility = 0;
+    for (const sample of hemisphere) {
+      for (let axis = 0; axis < 3; axis += 1)
+        direction[axis] = sample[0] * tangent[axis] + sample[1] * bitangent[axis] + sample[2] * normals[at + axis];
+      visibility += nearest() / radius;
+    }
+    values[vertex] = visibility / samples;
+    cache.set(key, values[vertex]);
+  }
+  return values;
+}
+function hitsBox(box, origin, direction, limit) {
+  let low = 0, high = limit;
+  for (let axis = 0; axis < 3; axis += 1) {
+    const o = origin[axis], d = direction[axis];
+    if (Math.abs(d) < 1e-12) {
+      if (o < box[axis] || o > box[axis + 3]) return false;
+      continue;
+    }
+    const a = (box[axis] - o) / d, b = (box[axis + 3] - o) / d;
+    low = Math.max(low, Math.min(a, b));
+    high = Math.min(high, Math.max(a, b));
+    if (low > high) return false;
+  }
+  return true;
+}
+
+// src/gltf-materials.ts
+import {
+  checkTileflowModelSurface as checkTileflowModelSurface2,
+  tileflowModelImageSize,
+  tileflowModelSurfaceLimits
+} from "@tileflow/core";
+function createGltfMaterialReader(json, bin, accessor2) {
+  const textures = [];
+  const textureIds = /* @__PURE__ */ new Map();
+  const imageCache = /* @__PURE__ */ new Map();
+  function imageAt(index) {
+    if (!Number.isInteger(index)) throw new RangeError("A material names a missing image.");
+    const cached = imageCache.get(index);
+    if (cached) return cached;
+    const image = record(list(json.images)[index]);
+    let bytes;
+    let mimeType = image.mimeType;
+    if (typeof image.uri === "string") {
+      const match = /^data:(image\/(?:png|jpeg));base64,([A-Za-z0-9+/=\r\n]+)$/.exec(image.uri);
+      if (!match || image.uri.length > 24 * 1024 * 1024)
+        throw new RangeError("Embed PNG/JPEG images in the GLB; external images are not read.");
+      if (mimeType !== void 0 && mimeType !== match[1])
+        throw new RangeError("An image has conflicting media types.");
+      mimeType = match[1];
+      bytes = new Uint8Array(Buffer.from(match[2], "base64"));
+    } else {
+      if (!Number.isInteger(image.bufferView)) throw new RangeError("Embed each image in the GLB.");
+      const view = record(list(json.bufferViews)[image.bufferView]);
+      const start = view.byteOffset ?? 0;
+      const length = view.byteLength;
+      if (!bin || (view.buffer ?? 0) !== 0 || !Number.isInteger(start) || !Number.isInteger(length) || start < 0 || length <= 0 || start + length > bin.length)
+        throw new RangeError("An embedded image extends outside the GLB.");
+      bytes = bin.subarray(start, start + length);
+    }
+    if (mimeType !== "image/png" && mimeType !== "image/jpeg")
+      throw new RangeError("Use an embedded PNG or JPEG image.");
+    const size = tileflowModelImageSize(bytes, mimeType);
+    if (!size || Math.max(...size) > tileflowModelSurfaceLimits.textureDimension || size[0] * size[1] > tileflowModelSurfaceLimits.texturePixels)
+      throw new RangeError("The model image is invalid or exceeds its pixel budget.");
+    const result = {
+      bytes,
+      width: size[0],
+      height: size[1],
+      mimeType
+    };
+    imageCache.set(index, result);
+    return result;
+  }
+  function textureAt(index) {
+    if (!Number.isInteger(index)) throw new RangeError("A material names a missing texture.");
+    const cached = textureIds.get(index);
+    if (cached !== void 0) return cached;
+    const source = record(list(json.textures)[index]);
+    const image = imageAt(source.source);
+    const sampler = source.sampler === void 0 ? {} : record(list(json.samplers)[source.sampler]);
+    if (source.sampler !== void 0 && (!Number.isInteger(source.sampler) || !list(json.samplers)[source.sampler]))
+      throw new RangeError("A texture names a missing sampler.");
+    const id = textures.length;
+    if (id >= tileflowModelSurfaceLimits.textures)
+      throw new RangeError("The model has too many textures.");
+    textures.push({
+      ...image,
+      ...pick(sampler, ["wrapS", "wrapT", "minFilter", "magFilter"])
+    });
+    textureIds.set(index, id);
+    return id;
+  }
+  function textureRef(value, normal = false) {
+    if (value === void 0) return void 0;
+    const ref = record(value);
+    const transform3 = record(record(ref.extensions).KHR_texture_transform);
+    const texCoord = transform3.texCoord ?? ref.texCoord;
+    return {
+      texture: textureAt(ref.index),
+      ...texCoord === void 0 ? {} : { texCoord },
+      ...pick(transform3, ["offset", "scale", "rotation"]),
+      ...normal && ref.scale !== void 0 ? { strength: ref.scale } : {},
+      ...!normal && ref.strength !== void 0 ? { strength: ref.strength } : {}
+    };
+  }
+  return (primitive, count, indexCount) => {
+    const source = primitive.material === void 0 ? {} : record(list(json.materials)[primitive.material]);
+    if (primitive.material !== void 0 && (!Number.isInteger(primitive.material) || !list(json.materials)[primitive.material]))
+      throw new RangeError("A primitive names a missing material.");
+    const pbr = record(source.pbrMetallicRoughness);
+    const extensions = record(source.extensions);
+    const material = {
+      ...pick(pbr, ["baseColorFactor", "metallicFactor", "roughnessFactor"]),
+      ...pick(source, ["emissiveFactor", "alphaMode", "alphaCutoff", "doubleSided"]),
+      ...extensions.KHR_materials_unlit === void 0 ? {} : { unlit: true },
+      ...pick(record(extensions.KHR_materials_emissive_strength), ["emissiveStrength"]),
+      ...optional("baseColorTexture", textureRef(pbr.baseColorTexture)),
+      ...optional("metallicRoughnessTexture", textureRef(pbr.metallicRoughnessTexture)),
+      ...optional("normalTexture", textureRef(source.normalTexture, true)),
+      ...optional("occlusionTexture", textureRef(source.occlusionTexture)),
+      ...optional("emissiveTexture", textureRef(source.emissiveTexture))
+    };
+    const attributes = record(primitive.attributes);
+    const read = (name, size) => {
+      const index = attributes[name];
+      if (index === void 0) return void 0;
+      if (!Number.isInteger(index)) throw new RangeError(`Invalid ${name} accessor.`);
+      const value = accessor2(index);
+      if (!size.includes(value.size) || value.values.length !== count * value.size)
+        throw new RangeError(`${name} must have one value per vertex.`);
+      return value;
+    };
+    const uv0 = read("TEXCOORD_0", [2]), uv1 = read("TEXCOORD_1", [2]);
+    const colour = read("COLOR_0", [3, 4]);
+    for (const key of [
+      "baseColorTexture",
+      "metallicRoughnessTexture",
+      "normalTexture",
+      "occlusionTexture",
+      "emissiveTexture"
+    ]) {
+      const ref = material[key];
+      if (ref && !(ref.texCoord === 1 ? uv1 : ref.texCoord === void 0 || ref.texCoord === 0 ? uv0 : void 0))
+        throw new RangeError(`The ${key} needs its declared UV coordinates.`);
+    }
+    const data = new Float32Array(count * 8);
+    for (let vertex = 0; vertex < count; vertex++) {
+      for (let axis = 0; axis < 2; axis++) {
+        data[vertex * 8 + axis] = uv0?.values[vertex * 2 + axis] ?? 0;
+        data[vertex * 8 + 2 + axis] = uv1?.values[vertex * 2 + axis] ?? 0;
+      }
+      for (let channel = 0; channel < 4; channel++)
+        data[vertex * 8 + 4 + channel] = colour && channel < colour.size ? colour.values[vertex * colour.size + channel] : 1;
+    }
+    const surface = {
+      attributes: data,
+      materials: [material],
+      textures,
+      ranges: [{ from: 0, count: indexCount, material: 0 }]
+    };
+    checkTileflowModelSurface2(surface, count, indexCount);
+    return surface;
+  };
+}
+function record(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function list(value) {
+  return Array.isArray(value) ? value : [];
+}
+function pick(value, keys) {
+  return Object.fromEntries(
+    keys.filter((key) => value[key] !== void 0).map((key) => [key, value[key]])
+  );
+}
+function optional(key, value) {
+  return value === void 0 ? {} : { [key]: value };
+}
 
 // src/gltf-reader.ts
 var TileflowGltfError = class extends Error {
@@ -984,7 +1351,7 @@ var componentBytes = {
   5126: 4
 };
 var typeSizes = { SCALAR: 1, VEC2: 2, VEC3: 3, VEC4: 4 };
-function readTileflowGltfTriangles(bytes) {
+function readTileflowGltfTriangles(bytes, { materials = false } = {}) {
   const { json, bin } = chunks(bytes);
   const required = array(json.extensionsRequired).filter((name) => typeof name === "string");
   const compressed = required.find((name) => compressions.has(name));
@@ -993,24 +1360,57 @@ function readTileflowGltfTriangles(bytes) {
       `uses compressed geometry (${String(compressed)}); export it without compression`
     );
   for (const buffer of array(json.buffers))
-    if (record(buffer).uri !== void 0)
+    if (record2(buffer).uri !== void 0)
       throw new TileflowGltfError("keeps its geometry in another file; export a single .glb");
-  const nodes = array(json.nodes).map(record);
-  const scenes = array(json.scenes).map(record);
+  const nodes = array(json.nodes).map(record2);
+  const scenes = array(json.scenes).map(record2);
   const scene = scenes[typeof json.scene === "number" ? json.scene : 0];
   const roots = scene ? array(scene.nodes) : nodes.map((_, index) => index).filter((index) => !nodes.some((node) => array(node.children).includes(index)));
   const out = [];
+  const physical = materials ? createGltfMaterialReader(json, bin, (index) => accessorWithSize(json, bin, index)) : void 0;
+  const emitters = [];
   const visit = (index, parent, depth) => {
     if (typeof index !== "number" || !nodes[index])
       throw new TileflowGltfError("names a node it does not hold");
     if (depth > 64) throw new TileflowGltfError("nests its nodes more than 64 deep");
     const node = nodes[index];
     const world = multiply(parent, local(node));
-    if (typeof node.mesh === "number") out.push(...meshOf(json, bin, node.mesh, world));
+    if (physical) {
+      const lights = record2(record2(node.extras).tileflow).emitters;
+      if (lights !== void 0 && !Array.isArray(lights))
+        throw new TileflowGltfError("area emitters must be an array");
+      for (const value of array(lights)) {
+        const own = record2(value);
+        const point3 = (key) => {
+          const input = array(own[key]);
+          if (input.length !== 3 || !input.every((value2) => typeof value2 === "number" && Number.isFinite(value2)))
+            throw new TileflowGltfError("an area emitter needs finite three-dimensional endpoints");
+          const p = transform2(world, input[0], input[1], input[2], 1);
+          return [p[0], -p[2], p[1]];
+        };
+        const heightScale = Math.hypot(...transform2(world, 0, 1, 0, 0));
+        const depthScale = Math.hypot(...transform2(world, 0, 0, 1, 0));
+        if (typeof own.height !== "number")
+          throw new TileflowGltfError("an area emitter needs its height");
+        emitters.push({
+          start: point3("start"),
+          end: point3("end"),
+          height: own.height * heightScale,
+          ...own.depth === void 0 ? {} : { depth: Number(own.depth) * depthScale },
+          role: own.role,
+          part: own.part
+        });
+      }
+    }
+    if (typeof node.mesh === "number") out.push(...meshOf(json, bin, node.mesh, world, physical));
     for (const child of array(node.children)) visit(child, world, depth + 1);
   };
   for (const root of roots) visit(root, identity(), 0);
   if (out.length === 0) throw new TileflowGltfError("holds no triangles in its scene");
+  if (emitters.length) {
+    const first = out.find((part) => !/^footprint(?:\.\d+)?$/i.test(part.material ?? ""));
+    if (first?.surface) first.surface = { ...first.surface, emitters };
+  }
   return out;
 }
 function chunks(bytes) {
@@ -1031,7 +1431,7 @@ function chunks(bytes) {
     const body = bytes.subarray(start, start + length);
     if (type === jsonChunk && json === void 0) {
       try {
-        json = record(JSON.parse(new TextDecoder().decode(body)));
+        json = record2(JSON.parse(new TextDecoder().decode(body)));
       } catch {
         throw new TileflowGltfError("has an unreadable JSON chunk");
       }
@@ -1041,14 +1441,14 @@ function chunks(bytes) {
   if (!json) throw new TileflowGltfError("has no JSON chunk");
   return { json, bin };
 }
-function meshOf(json, bin, index, world) {
-  const mesh = record(array(json.meshes)[index]);
+function meshOf(json, bin, index, world, physical) {
+  const mesh = record2(array(json.meshes)[index]);
   const normalMatrix = inverseTranspose(world);
-  return array(mesh.primitives).map((value) => {
-    const primitive = record(value);
+  const result = array(mesh.primitives).map((value) => {
+    const primitive = record2(value);
     if ((primitive.mode ?? triangles) !== triangles)
       throw new TileflowGltfError("draws points or lines; a tree model draws triangles");
-    const attributes = record(primitive.attributes);
+    const attributes = record2(primitive.attributes);
     if (typeof attributes.POSITION !== "number")
       throw new TileflowGltfError("has a primitive without positions");
     const raw = accessor(json, bin, attributes.POSITION, 3);
@@ -1080,8 +1480,8 @@ function meshOf(json, bin, index, world) {
         normals.push(x / size, -z / size, y / size);
       }
     }
-    const material = typeof primitive.material === "number" ? record(array(json.materials)[primitive.material]) : void 0;
-    const base = array(record(material?.pbrMetallicRoughness).baseColorFactor).map(Number);
+    const material = typeof primitive.material === "number" ? record2(array(json.materials)[primitive.material]) : void 0;
+    const base = array(record2(material?.pbrMetallicRoughness).baseColorFactor).map(Number);
     const factor = base.length >= 3 && base.every(Number.isFinite) ? base : [1, 1, 1];
     const colours = [];
     const vertexColours = typeof attributes.COLOR_0 === "number" ? accessorWithSize(json, bin, attributes.COLOR_0) : void 0;
@@ -1098,12 +1498,37 @@ function meshOf(json, bin, index, world) {
         [indices[at + 1], indices[at + 2]] = [indices[at + 2], indices[at + 1]];
     return {
       material: typeof material?.name === "string" ? material.name : void 0,
+      ...record2(record2(material?.extras).tileflow).lightingRole === void 0 ? {} : {
+        lightingRole: record2(record2(material?.extras).tileflow).lightingRole
+      },
       positions,
       normals,
       colours,
-      indices
+      indices,
+      ...physical ? { surface: physical(primitive, count, indices.length) } : {}
     };
   });
+  if (physical) {
+    let low = Infinity, high = -Infinity;
+    for (const part of result)
+      if (!/^footprint(?:\.\d+)?$/i.test(part.material ?? ""))
+        for (let at = 2; at < part.positions.length; at += 3) {
+          low = Math.min(low, part.positions[at]);
+          high = Math.max(high, part.positions[at]);
+        }
+    if (Number.isFinite(low)) {
+      for (const part of result)
+        if (part.surface)
+          part.surface = {
+            ...part.surface,
+            ranges: part.surface.ranges.map((range) => ({
+              ...range,
+              emissiveBounds: [low, high]
+            }))
+          };
+    }
+  }
+  return result;
 }
 function accessor(json, bin, index, size) {
   const read = accessorWithSize(json, bin, index);
@@ -1112,7 +1537,7 @@ function accessor(json, bin, index, size) {
   return read.values;
 }
 function accessorWithSize(json, bin, index) {
-  const accessor2 = record(array(json.accessors)[index]);
+  const accessor2 = record2(array(json.accessors)[index]);
   if (accessor2.sparse !== void 0)
     throw new TileflowGltfError("uses sparse accessors; export without them");
   const size = typeSizes[String(accessor2.type)];
@@ -1123,7 +1548,7 @@ function accessorWithSize(json, bin, index) {
     throw new TileflowGltfError("has an accessor Tileflow cannot read");
   if (typeof accessor2.bufferView !== "number")
     return { values: new Array(count * size).fill(0), size };
-  const view = record(array(json.bufferViews)[accessor2.bufferView]);
+  const view = record2(array(json.bufferViews)[accessor2.bufferView]);
   if (!bin || Number(view.buffer ?? 0) !== 0)
     throw new TileflowGltfError("has geometry outside its binary chunk");
   const stride = Number(view.byteStride ?? 0) || size * bytesEach;
@@ -1245,15 +1670,15 @@ function inverseTranspose(m) {
     1
   ];
 }
-function record(value) {
+function record2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
 }
 function array(value) {
   return Array.isArray(value) ? value : [];
 }
 function vector(value, fallback) {
-  const list = array(value).map(Number);
-  return list.length === fallback.length && list.every(Number.isFinite) ? list : fallback;
+  const list2 = array(value).map(Number);
+  return list2.length === fallback.length && list2.every(Number.isFinite) ? list2 : fallback;
 }
 
 // src/building-model-mesh.ts
@@ -1273,25 +1698,33 @@ function tileflowBuildingModelDeclaredFootprint(primitives) {
   }
   return indices.length > 0 ? { positions, indices } : void 0;
 }
-function prepareTileflowBuildingModelMesh(bytes) {
-  const primitives = bytes instanceof Uint8Array ? readTileflowGltfTriangles(bytes) : bytes;
+function prepareTileflowBuildingModelMesh(bytes, { ambientOcclusion = true } = {}) {
+  const primitives = bytes instanceof Uint8Array ? readTileflowGltfTriangles(bytes, { materials: true }) : bytes;
+  const drawn = primitives.filter((primitive) => !isFootprint(primitive));
+  const surface = buildingModelSurface(drawn);
   const positions = [];
   const normals = [];
   const parts = [];
+  const lightingRoles = [];
   const luminance = [];
   const indices = [];
-  for (const primitive of primitives) {
-    if (isFootprint(primitive)) continue;
+  for (const primitive of drawn) {
     const part = partOf(primitive.material);
     if (part === void 0)
       throw new TileflowGltfError(
         primitive.material === void 0 ? "has a mesh without a material; name each material surface, secondary, glass, accent or roof" : `has a material "${primitive.material}" that names no part of a building; name each material surface, secondary, glass, accent or roof`
       );
     const offset = positions.length / 3;
+    const role = primitive.lightingRole === void 0 ? tileflowModelDefaultLightingRoles[part] : typeof primitive.lightingRole === "string" && Object.hasOwn(tileflowModelLightingRoles, primitive.lightingRole) ? tileflowModelLightingRoles[primitive.lightingRole] : void 0;
+    if (role === void 0)
+      throw new TileflowGltfError(
+        "has an unknown lighting role; use unclassified, wall, door, roof, window, lamp or logo"
+      );
     const count2 = primitive.positions.length / 3;
     positions.push(...primitive.positions);
     for (let vertex = 0; vertex < count2; vertex += 1) {
       parts.push(part);
+      lightingRoles.push(role);
       normals.push(primitive.normals?.slice(vertex * 3, vertex * 3 + 3));
       const [r, g, b] = primitive.colours.slice(vertex * 3, vertex * 3 + 3);
       luminance.push(0.2126 * r + 0.7152 * g + 0.0722 * b);
@@ -1347,8 +1780,10 @@ function prepareTileflowBuildingModelMesh(bytes) {
     positions,
     normals: outNormals,
     parts,
+    lightingRoles,
     shades,
-    occlusion: new Array(count).fill(1),
+    ...surface ? { surface } : {},
+    occlusion: ambientOcclusion ? buildingModelAmbientVisibility({ positions, normals: outNormals, indices }) : new Array(count).fill(1),
     indices
   };
 }
@@ -1426,9 +1861,9 @@ function tileflowBuildingModelFootprint(mesh) {
   const next = /* @__PURE__ */ new Map();
   const add = (from, to) => {
     const key = `${from[0]},${from[1]}`;
-    const list = next.get(key) ?? [];
-    list.push(to);
-    next.set(key, list);
+    const list2 = next.get(key) ?? [];
+    list2.push(to);
+    next.set(key, list2);
   };
   for (let y = 0; y < rows; y += 1)
     for (let x = 0; x < columns; x += 1) {
@@ -1520,8 +1955,8 @@ function ringArea(ring) {
 function edge(a, b, p) {
   return (b[0] - a[0]) * (p[1] - a[1]) - (b[1] - a[1]) * (p[0] - a[0]);
 }
-function point(list, vertex) {
-  return [list[vertex * 3], list[vertex * 3 + 1], list[vertex * 3 + 2]];
+function point(list2, vertex) {
+  return [list2[vertex * 3], list2[vertex * 3 + 1], list2[vertex * 3 + 2]];
 }
 function sub(a, b) {
   return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
@@ -1657,8 +2092,8 @@ function partOf2(material) {
 function isCrown(part) {
   return part === tileflowTreeParts.leaves || part === tileflowTreeParts.fronds;
 }
-function point2(list, vertex) {
-  return [list[vertex * 3], list[vertex * 3 + 1], list[vertex * 3 + 2]];
+function point2(list2, vertex) {
+  return [list2[vertex * 3], list2[vertex * 3 + 1], list2[vertex * 3 + 2]];
 }
 function sub2(a, b) {
   return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
@@ -1727,14 +2162,16 @@ async function packageTileflowLandmarkTile(landmarks) {
   }
   await MeshoptEncoder.ready;
   const bytes = encodeTileflowModels(models, MeshoptEncoder);
-  return { x: tile[0], y: tile[1], bytes, sha256: sha256Of(bytes) };
+  const footprints = readTileflowLandmarkTileFootprints(bytes);
+  if (!footprints) throw new Error("The packaged landmark tile cannot be read back.");
+  return { x: tile[0], y: tile[1], bytes, sha256: sha256Of(bytes), landmarks: footprints };
 }
 function encodeTileflowLandmarkRegion(region) {
   const bytes = serializeTileflowLandmarkRegion(region);
   return { bytes, sha256: sha256Of(bytes) };
 }
 function buildingModelEntry(id, levels) {
-  const primitives = readTileflowGltfTriangles(levels.near);
+  const primitives = readTileflowGltfTriangles(levels.near, { materials: true });
   if (!isTileflowBuildingModel(primitives))
     throw new TileflowGltfError(
       "is not a building model; name each material surface, secondary, glass, accent or roof"
@@ -1750,34 +2187,6 @@ function buildingModelEntry(id, levels) {
     )
   };
 }
-async function createTileflowModelBundle(buildings) {
-  const entries = Object.entries(buildings).sort(([a], [b]) => compareCodeUnits4(a, b));
-  if (entries.length === 0) return void 0;
-  const totalBytes = entries.reduce((total, [, model]) => total + model.bytes.byteLength, 0);
-  if (totalBytes > tileflowModelBundleLimits.maxPackageBytes)
-    throw new RangeError(
-      `The map's building models together are ${totalBytes} bytes once prepared; a hosted map takes at most ${tileflowModelBundleLimits.maxPackageBytes}. Simplify or remove models.`
-    );
-  const manifest = {
-    format: "tileflow-model-bundle-v1",
-    models: entries.map(([id, model]) => ({
-      byteLength: model.bytes.byteLength,
-      contentType: tileflowModelContentType,
-      file: model.fileName,
-      id,
-      sha256: model.sha256
-    }))
-  };
-  return {
-    contentHash: await hashTileflowModelBundleManifest(manifest),
-    manifest,
-    files: entries.map(([, model]) => ({
-      contentType: tileflowModelContentType,
-      fileName: model.fileName,
-      source: model.bytes
-    }))
-  };
-}
 function sha256Of(bytes) {
   return createHash("sha256").update(bytes).digest("hex");
 }
@@ -1858,6 +2267,7 @@ async function prepareTileflowMapTreeModels(directories, options) {
     }
     if (isTileflowBuildingModel(primitives)) {
       const files2 = { near: nearBytes };
+      const sources = [];
       let failing = entry.near;
       try {
         for (const level of ["near", "mid", "far"]) {
@@ -1866,15 +2276,18 @@ async function prepareTileflowMapTreeModels(directories, options) {
           failing = file;
           const bytes = level === "near" ? nearBytes : new Uint8Array(await readFile(file.path));
           files2[level] = bytes;
-          if (level !== "near") prepareTileflowBuildingModelMesh(bytes);
-          identities.push({ id, level, sha256: createHash("sha256").update(bytes).digest("hex") });
+          if (level !== "near") prepareTileflowBuildingModelMesh(bytes, { ambientOcclusion: false });
+          const sha256 = createHash("sha256").update(bytes).digest("hex");
+          identities.push({ id, level, sha256 });
+          sources.push({ level, sha256, byteLength: bytes.byteLength });
         }
         failing = entry.near;
         const prepared2 = await prepareTileflowBuildingModel(id, files2);
         buildings[id] = {
-          fileName: tileflowModelBundleFileName(id, prepared2.sha256),
+          fileName: tileflowModelFileName(id, prepared2.sha256),
           bytes: prepared2.bytes,
-          sha256: prepared2.sha256
+          sha256: prepared2.sha256,
+          sources
         };
       } catch (error) {
         issues.push({
@@ -2215,7 +2628,7 @@ async function prepareTileflowCatalogIcons(project, options) {
     const buildingModels = {};
     for (const [id, model] of Object.entries(models.buildings)) {
       const fileName = `models/${mapName}/${model.fileName}`;
-      assets.push({ contentType: tileflowModelContentType2, fileName, source: model.bytes });
+      assets.push({ contentType: tileflowModelContentType, fileName, source: model.bytes });
       buildingModels[id] = joinUrl(options.assetBaseUrl, fileName);
     }
     mapAssets[mapName] = {
@@ -2833,7 +3246,6 @@ export {
   prepareTileflowBuildingModel,
   packageTileflowLandmarkTile,
   encodeTileflowLandmarkRegion,
-  createTileflowModelBundle,
   prepareTileflowMapTreeModels,
   renderTileflowIconAtlasPreview,
   TileflowIconCompilationError,

package/dist/fonts.d.ts

@@ -1,6 +1,6 @@
 import { TileflowFontBundleManifest, MapLibreStyle } from '@tileflow/core';
 import { TileflowEffectiveFontSourceIdentity, TileflowBuildStyles, TileflowBuildCatalog } from '@tileflow/core/build';
-import { T as TileflowBuildAsset } from './icons-BdOehQmB.js';
+import { T as TileflowBuildAsset } from './icons-BIHpw5Zy.js';
 
 type TileflowFontCompilationTarget = 'hosted' | 'local';
 type TileflowFontCompilationIssue = {

package/dist/{icons-BdOehQmB.d.ts → icons-BIHpw5Zy.d.ts}

@@ -1,4 +1,4 @@
-import { TileflowIconAppearance, TileflowIconLayoutMetadata, TileflowIconSetPin, TileflowLandmarkRegion, TileflowModelBundleManifest, TileflowModelDirectory, TileflowTreeModel, TileflowIconSpriteIndex, TileflowIconSource, TileflowIconsLockfileV1, TileflowIconCompositionV1, TileflowIconPackageFileName, TileflowIconPackageManifest, TileflowIconDirectory } from '@tileflow/core';
+import { TileflowIconAppearance, TileflowIconLayoutMetadata, TileflowIconSetPin, TileflowLandmarkRegion, TileflowLandmarkFootprint, TileflowModelDirectory, TileflowTreeModel, TileflowIconSpriteIndex, TileflowIconSource, TileflowIconsLockfileV1, TileflowIconCompositionV1, TileflowIconPackageFileName, TileflowIconPackageManifest, TileflowIconDirectory } from '@tileflow/core';
 import { TileflowEffectiveModelSourceIdentity, TileflowEffectiveIconSourceIdentity, TileflowBuildCatalog, TileflowPreparedMapAssets } from '@tileflow/core/build';
 
 type TileflowRenderedIconCell = {
@@ -44,6 +44,12 @@ type PreparedTileflowBuildingModel = {
     fileName: string;
     bytes: Uint8Array;
     sha256: string;
+    /** The glTF binaries it was prepared from, nearest level first. */
+    sources: readonly Readonly<{
+        level: 'near' | 'mid' | 'far';
+        sha256: string;
+        byteLength: number;
+    }>[];
 };
 /** A building model's glTF binaries, nearest level first. */
 type TileflowBuildingModelLevels = Readonly<{
@@ -73,39 +79,26 @@ type TileflowLandmarkSource = Readonly<{
 /**
  * Packages the landmarks standing in one tile of a landmarks tileset into that tile's prepared
  * model file, the landmarks in the order of their ids. Every landmark's origin must fall in the
- * same zoom-14 tile. The result depends only on its input.
+ * same zoom-14 tile. It also returns each landmark's place and footprint, as the region's index
+ * names them. The result depends only on its input.
  */
 declare function packageTileflowLandmarkTile(landmarks: readonly TileflowLandmarkSource[]): Promise<{
     x: number;
     y: number;
     bytes: Uint8Array;
     sha256: string;
+    landmarks: readonly TileflowLandmarkFootprint[];
 }>;
 /**
- * Writes the index of one region of a landmarks tileset, `{region: [x, y], tiles: [[x, y,
- * sha256], ...]}`, as the bytes the tileset serves, with their SHA-256.
+ * Writes the index of one region of a landmarks tileset, `{region: [x, y], tiles: [[x, y, sha256,
+ * landmarks], ...]}`, as the bytes the tileset serves, with their SHA-256. A tile's `landmarks` are
+ * the ones `packageTileflowLandmarkTile` returned for it, or `readTileflowLandmarkTileFootprints`
+ * reads back from its bytes.
  */
 declare function encodeTileflowLandmarkRegion(region: TileflowLandmarkRegion): {
     bytes: Uint8Array;
     sha256: string;
 };
-/** A map's building models as the model bundle a hosted deploy uploads before its styles. */
-type TileflowModelBundle = {
-    /** The SHA-256 of the manifest's canonical JSON. */
-    contentHash: string;
-    manifest: TileflowModelBundleManifest;
-    /** Each model's prepared file, named as the manifest names it. */
-    files: {
-        contentType: string;
-        fileName: string;
-        source: Uint8Array;
-    }[];
-};
-/**
- * Bundles a map's prepared building models, or returns undefined when it has none. Throws a
- * `RangeError` an author can act on when the models together are too large to host.
- */
-declare function createTileflowModelBundle(buildings: Readonly<Record<string, PreparedTileflowBuildingModel>>): Promise<TileflowModelBundle | undefined>;
 type PreparedTileflowTreeModels = {
     /** The prepared tree models by id. */
     models: Record<string, TileflowTreeModel>;
@@ -421,4 +414,4 @@ declare function readTileflowIconDirectory(source: TileflowIconDirectory, option
     target: TileflowIconCompilationTarget;
 }): Promise<ReadTileflowIconDirectoryResult>;
 
-export { readTileflowIconDirectory as $, TileflowIconCompilationError as A, type TileflowIconCompilationIssue as B, type CompileTileflowIconPackagesOptions as C, type TileflowIconCompilationTarget as D, type TileflowIconDirectoryEntry as E, type TileflowIconDirectorySourceFile as F, type TileflowIconReplacement as G, type TileflowMapIconPackageBinding as H, type InspectTileflowIconCatalogsOptions as I, type TileflowModelBundle as J, type TileflowRenderedIcon as K, type TileflowRenderedIconCell as L, compileTileflowIconPackages as M, composeTileflowIconSources as N, createTileflowModelBundle as O, type PreparedTileflowBuildCatalog as P, getTileflowIconCacheDirectory as Q, type ReadTileflowIconDirectoryResult as R, getTileflowIconWatchPaths as S, type TileflowBuildAsset as T, iconFileExtensions as U, type VerifiedTileflowIconArtifact as V, inspectTileflowIconCatalogs as W, loadTileflowIconSetArtifact as X, packTileflowRenderedIcons as Y, prepareTileflowCatalogIcons as Z, prepareTileflowMapTreeModels as _, type TileflowIconResolutionOptions as a, readTileflowIconsLockfile as a0, readTileflowIconsLockfileText as a1, renderTileflowIconAtlasPreview as a2, storeTileflowIconSetArtifact as a3, verifyTileflowIconArtifact as a4, writeTileflowIconsLockfile as a5, type TileflowSourceCatalog as b, type PreparedTileflowCatalog as c, type TileflowBuildingModelLevels as d, type TileflowLandmarkSource as e, encodeTileflowLandmarkRegion as f, prepareTileflowBuildingModel as g, type CompileTileflowIconPackagesResult as h, type CompiledTileflowIconPackage as i, type CompiledTileflowIconPackageFile as j, type ComposeTileflowIconSourcesOptions as k, type PreparedTileflowBuildingModel as l, type TileflowComposedIconContributor as m, type TileflowComposedIconSources as n, type TileflowComposedIconWinner as o, packageTileflowLandmarkTile as p, type TileflowIconCacheOptions as q, type TileflowIconCatalog as r, type TileflowIconCatalogAtlasRectangle as s, type TileflowIconCatalogContributor as t, type TileflowIconCatalogIcon as u, type TileflowIconCatalogIconSource as v, type TileflowIconCatalogInspection as w, type TileflowIconCatalogMap as x, type TileflowIconCatalogRenderedDensity as y, type TileflowIconCatalogSourceFormat as z };
+export { readTileflowIconsLockfileText as $, TileflowIconCompilationError as A, type TileflowIconCompilationIssue as B, type CompileTileflowIconPackagesOptions as C, type TileflowIconCompilationTarget as D, type TileflowIconDirectoryEntry as E, type TileflowIconDirectorySourceFile as F, type TileflowIconReplacement as G, type TileflowMapIconPackageBinding as H, type InspectTileflowIconCatalogsOptions as I, type TileflowRenderedIcon as J, type TileflowRenderedIconCell as K, compileTileflowIconPackages as L, composeTileflowIconSources as M, getTileflowIconCacheDirectory as N, getTileflowIconWatchPaths as O, type PreparedTileflowBuildCatalog as P, iconFileExtensions as Q, type ReadTileflowIconDirectoryResult as R, inspectTileflowIconCatalogs as S, type TileflowBuildAsset as T, loadTileflowIconSetArtifact as U, type VerifiedTileflowIconArtifact as V, packTileflowRenderedIcons as W, prepareTileflowCatalogIcons as X, prepareTileflowMapTreeModels as Y, readTileflowIconDirectory as Z, readTileflowIconsLockfile as _, type TileflowIconResolutionOptions as a, renderTileflowIconAtlasPreview as a0, storeTileflowIconSetArtifact as a1, verifyTileflowIconArtifact as a2, writeTileflowIconsLockfile as a3, type TileflowSourceCatalog as b, type PreparedTileflowCatalog as c, type TileflowBuildingModelLevels as d, type TileflowLandmarkSource as e, encodeTileflowLandmarkRegion as f, prepareTileflowBuildingModel as g, type CompileTileflowIconPackagesResult as h, type CompiledTileflowIconPackage as i, type CompiledTileflowIconPackageFile as j, type ComposeTileflowIconSourcesOptions as k, type PreparedTileflowBuildingModel as l, type TileflowComposedIconContributor as m, type TileflowComposedIconSources as n, type TileflowComposedIconWinner as o, packageTileflowLandmarkTile as p, type TileflowIconCacheOptions as q, type TileflowIconCatalog as r, type TileflowIconCatalogAtlasRectangle as s, type TileflowIconCatalogContributor as t, type TileflowIconCatalogIcon as u, type TileflowIconCatalogIconSource as v, type TileflowIconCatalogInspection as w, type TileflowIconCatalogMap as x, type TileflowIconCatalogRenderedDensity as y, type TileflowIconCatalogSourceFormat as z };

package/dist/icons.d.ts

@@ -1,3 +1,3 @@
 import '@tileflow/core';
 import '@tileflow/core/build';
-export { C as CompileTileflowIconPackagesOptions, h as CompileTileflowIconPackagesResult, i as CompiledTileflowIconPackage, j as CompiledTileflowIconPackageFile, k as ComposeTileflowIconSourcesOptions, I as InspectTileflowIconCatalogsOptions, P as PreparedTileflowBuildCatalog, l as PreparedTileflowBuildingModel, c as PreparedTileflowCatalog, R as ReadTileflowIconDirectoryResult, T as TileflowBuildAsset, m as TileflowComposedIconContributor, n as TileflowComposedIconSources, o as TileflowComposedIconWinner, q as TileflowIconCacheOptions, r as TileflowIconCatalog, s as TileflowIconCatalogAtlasRectangle, t as TileflowIconCatalogContributor, u as TileflowIconCatalogIcon, v as TileflowIconCatalogIconSource, w as TileflowIconCatalogInspection, x as TileflowIconCatalogMap, y as TileflowIconCatalogRenderedDensity, z as TileflowIconCatalogSourceFormat, A as TileflowIconCompilationError, B as TileflowIconCompilationIssue, D as TileflowIconCompilationTarget, E as TileflowIconDirectoryEntry, F as TileflowIconDirectorySourceFile, G as TileflowIconReplacement, a as TileflowIconResolutionOptions, H as TileflowMapIconPackageBinding, J as TileflowModelBundle, K as TileflowRenderedIcon, L as TileflowRenderedIconCell, b as TileflowSourceCatalog, V as VerifiedTileflowIconArtifact, M as compileTileflowIconPackages, N as composeTileflowIconSources, O as createTileflowModelBundle, Q as getTileflowIconCacheDirectory, S as getTileflowIconWatchPaths, U as iconFileExtensions, W as inspectTileflowIconCatalogs, X as loadTileflowIconSetArtifact, Y as packTileflowRenderedIcons, Z as prepareTileflowCatalogIcons, _ as prepareTileflowMapTreeModels, $ as readTileflowIconDirectory, a0 as readTileflowIconsLockfile, a1 as readTileflowIconsLockfileText, a2 as renderTileflowIconAtlasPreview, a3 as storeTileflowIconSetArtifact, a4 as verifyTileflowIconArtifact, a5 as writeTileflowIconsLockfile } from './icons-BdOehQmB.js';
+export { C as CompileTileflowIconPackagesOptions, h as CompileTileflowIconPackagesResult, i as CompiledTileflowIconPackage, j as CompiledTileflowIconPackageFile, k as ComposeTileflowIconSourcesOptions, I as InspectTileflowIconCatalogsOptions, P as PreparedTileflowBuildCatalog, l as PreparedTileflowBuildingModel, c as PreparedTileflowCatalog, R as ReadTileflowIconDirectoryResult, T as TileflowBuildAsset, m as TileflowComposedIconContributor, n as TileflowComposedIconSources, o as TileflowComposedIconWinner, q as TileflowIconCacheOptions, r as TileflowIconCatalog, s as TileflowIconCatalogAtlasRectangle, t as TileflowIconCatalogContributor, u as TileflowIconCatalogIcon, v as TileflowIconCatalogIconSource, w as TileflowIconCatalogInspection, x as TileflowIconCatalogMap, y as TileflowIconCatalogRenderedDensity, z as TileflowIconCatalogSourceFormat, A as TileflowIconCompilationError, B as TileflowIconCompilationIssue, D as TileflowIconCompilationTarget, E as TileflowIconDirectoryEntry, F as TileflowIconDirectorySourceFile, G as TileflowIconReplacement, a as TileflowIconResolutionOptions, H as TileflowMapIconPackageBinding, J as TileflowRenderedIcon, K as TileflowRenderedIconCell, b as TileflowSourceCatalog, V as VerifiedTileflowIconArtifact, L as compileTileflowIconPackages, M as composeTileflowIconSources, N as getTileflowIconCacheDirectory, O as getTileflowIconWatchPaths, Q as iconFileExtensions, S as inspectTileflowIconCatalogs, U as loadTileflowIconSetArtifact, W as packTileflowRenderedIcons, X as prepareTileflowCatalogIcons, Y as prepareTileflowMapTreeModels, Z as readTileflowIconDirectory, _ as readTileflowIconsLockfile, $ as readTileflowIconsLockfileText, a0 as renderTileflowIconAtlasPreview, a1 as storeTileflowIconSetArtifact, a2 as verifyTileflowIconArtifact, a3 as writeTileflowIconsLockfile } from './icons-BIHpw5Zy.js';

package/dist/icons.js

@@ -2,7 +2,6 @@ import {
   TileflowIconCompilationError,
   compileTileflowIconPackages,
   composeTileflowIconSources,
-  createTileflowModelBundle,
   getTileflowIconCacheDirectory,
   getTileflowIconWatchPaths,
   iconFileExtensions,
@@ -18,13 +17,12 @@ import {
   storeTileflowIconSetArtifact,
   verifyTileflowIconArtifact,
   writeTileflowIconsLockfile
-} from "./chunk-QYU4OW5A.js";
+} from "./chunk-5RT4CHSK.js";
 import "./chunk-7C4F6GAX.js";
 export {
   TileflowIconCompilationError,
   compileTileflowIconPackages,
   composeTileflowIconSources,
-  createTileflowModelBundle,
   getTileflowIconCacheDirectory,
   getTileflowIconWatchPaths,
   iconFileExtensions,

package/dist/preview.js

@@ -348,6 +348,7 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
       import {loadTileflowStyleFonts} from "${basePath}/__runtime/tileflow-browser.js";
       import {registerTileflowContourProtocol} from "${basePath}/__runtime/tileflow-browser.js";
       import {registerTileflowPmtilesProtocol} from "${basePath}/__runtime/tileflow-browser.js";
+      import {attachTileflowNotices} from "${basePath}/__runtime/tileflow-browser.js";
       import {createTileflowBuildings3D, createTileflowStreetLights, createTileflowVegetation} from "${basePath}/__runtime/tileflow-browser.js";
       import {readTileflowSunPreset, resolveTileflowSun, tileflowDefaultSunPreset} from "${basePath}/__runtime/tileflow-browser.js";
 
@@ -2383,6 +2384,7 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
           ...resolveInitialMapOptions(previewMapOptions)
         });
         globalThis.__tileflowPreviewMap = map;
+        attachTileflowNotices(map);
         devtoolsObserver?.attach(map);
         installMapBenchmark(map);
         if (window.parent === window) map.addControl(new maplibregl.NavigationControl(), "top-right");

package/dist/server.d.ts

@@ -5,7 +5,7 @@ import '@tileflow/core';
 import '@tileflow/core/build';
 import '@tileflow/core/manifest';
 import '@tileflow/core/native-profile';
-import './icons-BdOehQmB.js';
+import './icons-BIHpw5Zy.js';
 import './config.js';
 
 declare const tileflowComparisonSchemaVersion: 1;

package/dist/server.js

@@ -5,7 +5,7 @@ import {
   parseTileflowLineBackgroundGlyphPath,
   tileflowArtifactSessionSchemaVersion,
   tileflowLineBackgroundGlyphRoute
-} from "./chunk-WJOF6USY.js";
+} from "./chunk-2F7LOYQI.js";
 import {
   getTileflowAssetBasePath,
   getTileflowAssetFileName,
@@ -13,7 +13,7 @@ import {
   normalizeTileflowBasePath,
   resolveTileflowArtifactPublicUrls
 } from "./chunk-UTRO4IBQ.js";
-import "./chunk-QYU4OW5A.js";
+import "./chunk-5RT4CHSK.js";
 import "./chunk-7C4F6GAX.js";
 import {
   TileflowStyleValidationError

package/docs/bounded-vector-feature-inspection.md

@@ -45,7 +45,7 @@ Baedeker, Cívica, 1777, Siegfried, Soundings, and Blueprint declare only
 `[soundingsIcons]`, and `[blueprintIcons]`, respectively. No official root composes another map's assets even though all
 use the semantic compiler ABI. Baedeker's directory contains eight original travel-atlas patterns;
 its browser-derived Mapterhorn contours use runtime terrain tiles and are not part of the icon
-package. Soundings owns ten original nautical symbols and
+package. Soundings owns eleven original nautical symbols and
 patterns. Blueprint owns four technical blueprint patterns and one schematic POI node; its
 unbundled Mapterhorn contours remain runtime terrain, and its text uses the canonical Noto Sans
 glyph provider. An application map may inherit a root's exact array, replace it, clear it with `[]`,

package/docs/building-models.md

@@ -0,0 +1,179 @@
+# Prepare recolorable building models
+
+Custom buildings and landmarks use the same preparation path. Export uncompressed glTF 2.0
+binaries in metres, Y up, with the origin on the ground. The default scene's triangles and node
+transforms are read. Building preparation retains physical materials and embedded PNG/JPEG
+textures. Animations, skins and morph targets are not evaluated; export their static geometry.
+
+## Separate colour from architectural role
+
+Material names select a palette slot: `surface`, `secondary`, `glass`, `accent` or `roof`.
+The optional `material.extras.tileflow.lightingRole` selects lighting independently:
+
+```json
+{
+  "name": "accent",
+  "extras": {
+    "tileflow": {
+      "lightingRole": "door"
+    }
+  },
+  "pbrMetallicRoughness": {
+    "baseColorFactor": [0.8, 0.8, 0.8, 1]
+  }
+}
+```
+
+This door can take the map's `accent` colour while receiving its `door` lighting profile. Accepted
+roles are `unclassified`, `wall`, `door`, `roof`, `window`, `lamp` and `logo`. A role describes
+geometry; it does not turn on light by itself. The map supplies emission through
+`buildings.threeDimensional.modelLighting`.
+
+Legacy models without an explicit role use these defaults:
+
+| Palette slot                     | Lighting role |
+| -------------------------------- | ------------- |
+| `surface`, `secondary`, `accent` | `wall`        |
+| `glass`                          | `window`      |
+| `roof`                           | `roof`        |
+
+Doors, lamps and logos require an explicit role. Use `unclassified` for a part that must not inherit
+a role. Invalid role names fail preparation. An exporter's numeric material suffix, such as
+`surface.001`, is ignored.
+
+Keep a stone relief in a wall role when it should receive the wall's lighting. A separate colour
+slot can distinguish its stone without creating a separate light source. Mark roof geometry as
+roof even when it shares a colour with a facade.
+
+## Physical materials
+
+The importer retains these glTF 2.0 channels independently of palette and role:
+
+| Channel            | Inputs                                                                            |
+| ------------------ | --------------------------------------------------------------------------------- |
+| Base colour        | Linear `baseColorFactor`, linear `COLOR_0` RGB/RGBA, sRGB base-colour texture     |
+| Reflection         | `metallicFactor`, `roughnessFactor`, texture blue/green channels                  |
+| Surface normal     | Tangent-space normal texture and `scale`; tangent basis from geometry and UVs     |
+| Ambient visibility | Occlusion texture red channel and `strength`, multiplied by geometric visibility  |
+| Emission           | Linear `emissiveFactor`, sRGB emissive texture, `KHR_materials_emissive_strength` |
+| Coverage           | `OPAQUE`, `MASK` with `alphaCutoff`, or `BLEND`; `doubleSided`                    |
+| Unlit              | `KHR_materials_unlit`                                                             |
+
+`TEXCOORD_0`, `TEXCOORD_1`, glTF sampler wrapping/filtering and `KHR_texture_transform` are retained.
+Every referenced channel must have its declared UV set. UV and colour seams survive welding.
+Colour textures and lit output use the scene's gamma-2.2 transfer approximation.
+Role emission mixes the complete material radiance toward its target, including authored emission.
+Images must be embedded in buffer views or PNG/JPEG data URIs; preparation never fetches external
+images. Other image formats and physical-material extensions are not supported.
+
+Each level accepts at most 256 distinct materials, 32 textures, 4096 pixels per image dimension
+and 16,777,216 decoded image pixels in total. The complete prepared file remains limited to 16 MiB.
+Invalid references, missing UVs and image headers that disagree with their dimensions fail preparation.
+
+Without overrides, a physical model retains its authored material. `modelLighting` can tint and
+override roughness/metallicity by role. Explicit `modelColors` take precedence over role tints;
+textures and vertex colours still modulate the chosen colour. Keep vertex colours neutral when
+they should not affect recolouring.
+
+Colour and normal textures, metallic reflection and alpha coverage use the browser's physical
+model path. Ambient visibility never attenuates solar light or emission. Masked pixels also leave
+holes in dynamic solar shadows; blended surfaces cast an alpha-tested shadow at 0.5. Transparent
+material ranges draw back to front after opaque surfaces; intersecting transparent triangles are
+not sorted individually.
+
+## Explicit area emitters
+
+A `door` role lights the surface. To project its spill, declare a rectangle in
+`node.extras.tileflow.emitters`. This glTF fragment uses node-local metres and Y up:
+
+```json
+{
+  "extras": {
+    "tileflow": {
+      "emitters": [
+        {
+          "start": [-1, 0, 0],
+          "end": [1, 0, 0],
+          "height": 3,
+          "depth": 0.2,
+          "role": "door",
+          "part": "accent"
+        }
+      ]
+    }
+  }
+}
+```
+
+`start` and `end` form the horizontal lower edge. The spill faces the right of that edge when
+viewed from above. `height` sets the rectangle's height; optional `depth` narrows the spill around
+recessed jambs. Node transforms apply to the emitter. Its role supplies emission and its part
+supplies the fallback palette colour. No emitter is inferred from material colour or geometry.
+
+Each level accepts 128 emitters. Each projects a four-triangle, depth-tested spill with reach
+`clamp(1.3 * height, 4, 10)` metres. This authored effect does not cast a new light or shadow onto
+other meshes. It follows the model's visibility and theme; zero emission removes it.
+
+## Ambient visibility
+
+Preparation estimates each vertex's local ambient visibility using 48 deterministic,
+cosine-weighted hemisphere samples, a two-metre reach and a two-millimetre origin bias. A spatial
+hierarchy limits intersection work; repeated positions and normals share samples. Nearby
+occluders contribute more than distant ones. Each level is prepared independently, including
+occlusion between its distinct primitives. Footprint meshes do not occlude.
+
+The result travels independently of colour. Do not bake ambient occlusion into `COLOR_0`: colour
+also affects direct sunlight and emission. The runtime applies prepared visibility only to the
+ambient contribution; solar visibility still comes from the dynamic shadow map.
+
+`threeDimensional.modelOcclusion` controls strength from zero to one and defaults to `0.75`.
+`threeDimensional.occlusion: false` also disables model ambient occlusion. Changing these
+runtime controls does not prepare the geometry again.
+
+Preparation cost grows with unique vertices, samples and nearby geometry. It is paid when a raw
+model is prepared, never per frame. Runtime occlusion adds no draw pass or texture and uses the
+existing visibility byte. It describes opaque geometry at rest; it does not follow moving parts,
+other models, the ground or surrounding buildings.
+
+## Files and compatibility
+
+Use `<id>.glb`, optionally `<id>.mid.glb` and `<id>.far.glb`. A mesh whose material is `footprint`
+defines the area replaced by the model and is not drawn. Otherwise preparation derives a footprint.
+See the [Core building guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/buildings-3d.md)
+for placement and limits.
+
+Prepared files retain a 16-byte vertex:
+
+| Bytes | Content                          |
+| ----- | -------------------------------- |
+| 0–5   | Quantized position               |
+| 6–7   | Padding                          |
+| 8–10  | Normal                           |
+| 11    | Padding                          |
+| 12    | Palette slot                     |
+| 13    | Shade within that slot           |
+| 14    | Ambient visibility, 0–255        |
+| 15    | Architectural lighting role, 0–6 |
+
+The model root's `extras.tileflow.lightingRoles: 1` declares the last byte. Older files without
+that marker use the legacy palette mapping. Existing fully exposed visibility values stay fully
+exposed; reprepare the original GLBs to obtain geometric occlusion. Geometry, normals and palette
+slots are not modified by the visibility calculation.
+
+Roles and visibility survive meshoptimizer compression. The existing `_PAINT` accessor and vertex
+stride are retained; the role occupies previously unused padding. Prepared files are an SDK
+transport format, while material extras are the authoring interface.
+
+Physical data is optional `extras.tileflow.surface` metadata on each level, with `version: 1`.
+Two VEC4 accessors address a separate 32-byte stream: UV0/UV1 followed by linear vertex RGBA.
+The metadata also holds material draw ranges, channel references, embedded images and emitters.
+Ranges preserve each source mesh's vertical emission bounds independently of its material.
+The original primitive layout remains unchanged. Older readers draw its legacy geometry and
+palette; they ignore the optional physical data. New readers preserve the legacy shading path
+when physical data is absent. Reprepare source GLBs to obtain the new channels.
+
+The auxiliary stream costs 32 bytes per retained vertex on the GPU. Each resident texture uses
+four bytes per pixel, plus about one third for mipmaps when enabled. Decoded images stay available
+for context restoration until the model is evicted. Physical materials add one draw per material
+range per colour/shadow pass; explicit emitters add one four-triangle draw each. No environment
+cube map or screen-space effect is required.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/dev",
-  "version": "0.1.0-alpha.33",
+  "version": "0.1.0-alpha.34",
   "license": "Apache-2.0",
   "description": "Node development utilities for Tileflow configs and builds.",
   "type": "module",
@@ -84,7 +84,7 @@
   "dependencies": {
     "@mapbox/vector-tile": "3.0.0",
     "@maplibre/maplibre-gl-style-spec": "26.4.4",
-    "@tileflow/core": ">=0.1.0-alpha.36 <0.1.0-beta.0",
+    "@tileflow/core": ">=0.1.0-alpha.37 <0.1.0-beta.0",
     "chokidar": "4.0.3",
     "fflate": "0.8.3",
     "fontkit": "2.0.4",
@@ -97,7 +97,7 @@
     "three": "0.185.1"
   },
   "devDependencies": {
-    "@tileflow/maps": "0.1.0-alpha.10"
+    "@tileflow/maps": "0.1.0-alpha.11"
   },
   "optionalDependencies": {
     "sharp": "0.35.5"