@tileflow/core 0.1.0-alpha.34 → 0.1.0-alpha.35

package/dist/runtime.d.ts

@@ -1 +1 @@
-export { z as TileflowAnalytics, $ as TileflowManifestFetchOptions, a0 as TileflowManifestLoadOptions, a1 as TileflowMapMode, a2 as TileflowMapModeOptions, ae as TileflowResolvedRuntimeTheme, aC as TileflowRuntimeCenterLike, a as TileflowRuntimeColorScheme, T as TileflowRuntimeManifest, aD as TileflowRuntimeManifestMap, b as TileflowRuntimeManifestMapEntry, c as TileflowRuntimeManifestTheme, aE as TileflowRuntimeSource, aF as TileflowRuntimeSourceValidation, aG as TileflowRuntimeStyle, aH as TileflowRuntimeStyleOptions, d as TileflowRuntimeSystemThemes, aI as TileflowRuntimeViewOptions, aJ as TileflowSessionController, aK as TileflowSessionGrantResponse, aN as TileflowStyleFontFace, b6 as TileflowThemeBlendSelection, bd as TileflowThemeSelection, bl as assertValidTileflowRuntimeSource, bm as clearTileflowManifestCache, bo as createTileflowSessionController, bp as createTileflowSessionId, bq as defaultTileflowManifestUrl, br as defaultTileflowRuntimeView, bt as getTileflowAnalyticsApiUrl, bu as getTileflowStyleFontFaces, bv as inferTileflowAnalyticsFromStyleUrl, bw as loadTileflowManifest, bx as mergeTileflowAnalytics, by as nearestTileflowBlendTheme, bz as normalizeTileflowRuntimeCenter, bA as normalizeTileflowStaticImageSize, bY as normalizeTileflowSurfaceId, bB as normalizeTileflowUrl, bC as resolveTileflowAnalyticsRequestUrl, bD as resolveTileflowManifestMap, bE as resolveTileflowMapMode, bF as resolveTileflowRuntimeStyle, bG as resolveTileflowRuntimeTheme, bH as resolveTileflowRuntimeThemeBlend, bI as resolveTileflowRuntimeView, bJ as resolveTileflowStaticImageUrl, bK as shouldLoadTileflowManifest, bL as startTileflowSession, bN as tileflowStyleFontFaceLimits, bO as tileflowStyleFontFacesMetadataKey, bP as tileflowThemeBlendLimits, bS as validateTileflowRuntimeSource, bT as validateTileflowThemeBlendSelection, bU as validateTileflowThemeSelection } from './manifest-types-hmzy2bBX.js';
+export { C as TileflowAnalytics, a2 as TileflowManifestFetchOptions, a3 as TileflowManifestLoadOptions, a4 as TileflowMapMode, a5 as TileflowMapModeOptions, ai as TileflowResolvedRuntimeTheme, aG as TileflowRuntimeCenterLike, a as TileflowRuntimeColorScheme, T as TileflowRuntimeManifest, aH as TileflowRuntimeManifestMap, b as TileflowRuntimeManifestMapEntry, c as TileflowRuntimeManifestTheme, aI as TileflowRuntimeSource, aJ as TileflowRuntimeSourceValidation, aK as TileflowRuntimeStyle, aL as TileflowRuntimeStyleOptions, d as TileflowRuntimeSystemThemes, aM as TileflowRuntimeViewOptions, aN as TileflowSessionController, aO as TileflowSessionGrantResponse, aR as TileflowStyleFontFace, ba as TileflowThemeBlendSelection, bh as TileflowThemeSelection, e as TileflowTimeOfDay, f as TileflowTimeOfDayVariants, bp as assertValidTileflowRuntimeSource, bq as clearTileflowManifestCache, bs as createTileflowSessionController, bt as createTileflowSessionId, bu as defaultTileflowManifestUrl, bv as defaultTileflowRuntimeView, bx as getTileflowAnalyticsApiUrl, by as getTileflowStyleFontFaces, bz as inferTileflowAnalyticsFromStyleUrl, bA as isTileflowTimeOfDay, bB as loadTileflowManifest, bC as mergeTileflowAnalytics, bD as nearestTileflowBlendTheme, bE as normalizeTileflowRuntimeCenter, bF as normalizeTileflowStaticImageSize, c2 as normalizeTileflowSurfaceId, bG as normalizeTileflowUrl, bH as resolveTileflowAnalyticsRequestUrl, bI as resolveTileflowManifestMap, bJ as resolveTileflowMapMode, bK as resolveTileflowRuntimeStyle, bL as resolveTileflowRuntimeTheme, bM as resolveTileflowRuntimeThemeBlend, bN as resolveTileflowRuntimeView, bO as resolveTileflowStaticImageUrl, bP as shouldLoadTileflowManifest, bQ as startTileflowSession, bS as tileflowStyleFontFaceLimits, bT as tileflowStyleFontFacesMetadataKey, bU as tileflowThemeBlendLimits, bW as tileflowTimesOfDay, bY as validateTileflowRuntimeSource, bZ as validateTileflowThemeBlendSelection, b_ as validateTileflowThemeSelection } from './manifest-types-Bzxon3dx.js';

package/dist/runtime.js

@@ -29,12 +29,70 @@ var init_portable_identity_rules = __esm({
   }
 });
 
+// src/time-of-day.ts
+function isTileflowTimeOfDay(value) {
+  return typeof value === "string" && tileflowTimesOfDay.includes(value);
+}
+function validateTileflowTimeOfDayVariants(variants, themes) {
+  const issues = [];
+  const owners = /* @__PURE__ */ new Map();
+  const families = Object.entries(variants);
+  for (const [family, moments] of families) {
+    if (!isTileflowThemeName(family) || !Object.hasOwn(themes, family)) {
+      issues.push({ path: [family], message: "Time-of-day family must name an existing theme" });
+    }
+    if (!Object.values(moments).includes(family)) {
+      issues.push({ path: [family], message: "A family must include its own theme in its presets" });
+    }
+    for (const [moment, name] of Object.entries(moments)) {
+      if (name === void 0) continue;
+      if (!isTileflowTimeOfDay(moment) || !isTileflowThemeName(name) || !Object.hasOwn(themes, name)) {
+        issues.push({
+          path: [family, moment],
+          message: "Expected a supported moment and an existing theme"
+        });
+      }
+      const owner = owners.get(name);
+      if (owner !== void 0 && owner !== family) {
+        issues.push({
+          path: [family, moment],
+          message: `Theme "${name}" already belongs to family "${owner}"`
+        });
+      }
+      owners.set(name, family);
+    }
+  }
+  return issues;
+}
+function resolveTileflowTimeOfDayTheme(variants, theme, timeOfDay) {
+  if (timeOfDay === void 0 || variants === void 0) return theme;
+  if (!isTileflowTimeOfDay(timeOfDay)) throw new TypeError("Expected day, dawn, dusk, or night");
+  const family = Object.hasOwn(variants, theme) ? variants[theme] : Object.values(variants).find((moments) => Object.values(moments).includes(theme));
+  if (!family) return theme;
+  const result = family[timeOfDay];
+  if (result === void 0) {
+    throw new Error(
+      `Theme "${theme}" does not offer timeOfDay="${timeOfDay}". Available: ${Object.keys(family).join(", ")}.`
+    );
+  }
+  return result;
+}
+var tileflowTimesOfDay;
+var init_time_of_day = __esm({
+  "src/time-of-day.ts"() {
+    "use strict";
+    init_portable_identity_rules();
+    tileflowTimesOfDay = ["day", "dawn", "dusk", "night"];
+  }
+});
+
 // src/manifest-types.ts
-var tileflowRuntimeManifestVersion, tileflowRuntimeManifestLimits;
+var tileflowRuntimeManifestVersion, tileflowTimeOfDayManifestVersion, tileflowRuntimeManifestLimits;
 var init_manifest_types = __esm({
   "src/manifest-types.ts"() {
     "use strict";
     tileflowRuntimeManifestVersion = 1;
+    tileflowTimeOfDayManifestVersion = 2;
     tileflowRuntimeManifestLimits = Object.freeze({ maximumBytes: 1024 * 1024 });
   }
 });
@@ -103,6 +161,24 @@ var init_model = __esm({
   }
 });
 
+// src/time-of-day-schema.ts
+function createTileflowTimeOfDaySchema(operations, themeName) {
+  return operations.record(
+    themeName,
+    operations.object({
+      day: operations.optional(themeName),
+      dawn: operations.optional(themeName),
+      dusk: operations.optional(themeName),
+      night: operations.optional(themeName)
+    })
+  );
+}
+var init_time_of_day_schema = __esm({
+  "src/time-of-day-schema.ts"() {
+    "use strict";
+  }
+});
+
 // src/manifest-schema.ts
 function createTileflowRuntimeManifestSchema(primitives, operations, identities = createPortableIdentitySchemas(operations)) {
   const { tileflowPortableIdSchema: tileflowPortableIdSchema2, tileflowThemeNameSchema: tileflowThemeNameSchema2 } = identities;
@@ -158,12 +234,24 @@ function createTileflowRuntimeManifestSchema(primitives, operations, identities
         })
       ),
       themes: operations.record(tileflowThemeNameSchema2, manifestThemeSchema),
+      timeOfDay: operations.optional(
+        createTileflowTimeOfDaySchema(operations, tileflowThemeNameSchema2)
+      ),
       usageMode: operations.optional(operations.literal("session")),
       view: operations.optional(viewSchema),
       worldGeneration: operations.optional(operations.literal("v1"))
     }),
     (entry, context) => {
       const names = Object.keys(entry.themes);
+      if (entry.timeOfDay) {
+        for (const issue of validateTileflowTimeOfDayVariants(entry.timeOfDay, entry.themes)) {
+          context.addIssue({
+            code: "custom",
+            message: issue.message,
+            path: ["timeOfDay", ...issue.path]
+          });
+        }
+      }
       if (names.length === 0) {
         context.addIssue({
           code: "custom",
@@ -217,10 +305,23 @@ function createTileflowRuntimeManifestSchema(primitives, operations, identities
     operations.object({
       apiUrl: operations.optional(apiOriginSchema),
       maps: operations.record(tileflowPortableIdSchema2, manifestMapSchema),
-      version: operations.literal(tileflowRuntimeManifestVersion)
+      version: operations.union(
+        operations.literal(tileflowRuntimeManifestVersion),
+        operations.literal(2)
+      )
     }),
     (manifest, context) => {
       const mapCount = Object.keys(manifest.maps).length;
+      if (manifest.version === 1) {
+        for (const [name, map] of Object.entries(manifest.maps)) {
+          if (map.timeOfDay !== void 0)
+            context.addIssue({
+              code: "custom",
+              message: "timeOfDay requires manifest version 2",
+              path: ["maps", name, "timeOfDay"]
+            });
+        }
+      }
       if (mapCount === 0) {
         context.addIssue({ code: "custom", message: "Expected at least one map", path: ["maps"] });
       }
@@ -333,6 +434,8 @@ var init_manifest_schema = __esm({
     init_portable_identity_schema();
     init_runtime_view_schema();
     init_model();
+    init_time_of_day();
+    init_time_of_day_schema();
   }
 });
 
@@ -387,6 +490,7 @@ var init_manifest_schema_classic = __esm({
         return z2.enum(values);
       },
       literal: (value) => z2.literal(value),
+      union: (left, right) => z2.union([classic(left), classic(right)]),
       tuplePair(left, right) {
         return z2.tuple([classic(left), classic(right)]);
       },
@@ -422,7 +526,8 @@ __export(manifest_exports, {
   safeParseTileflowRuntimeManifest: () => safeParseTileflowRuntimeManifest,
   tileflowRuntimeManifestLimits: () => tileflowRuntimeManifestLimits,
   tileflowRuntimeManifestSchema: () => tileflowRuntimeManifestSchema,
-  tileflowRuntimeManifestVersion: () => tileflowRuntimeManifestVersion
+  tileflowRuntimeManifestVersion: () => tileflowRuntimeManifestVersion,
+  tileflowTimeOfDayManifestVersion: () => tileflowTimeOfDayManifestVersion
 });
 function parseTileflowRuntimeManifest(input) {
   return tileflowRuntimeManifestSchema.parse(input);
@@ -451,6 +556,8 @@ var init_manifest = __esm({
 
 // src/runtime.ts
 init_portable_identity_rules();
+init_time_of_day();
+init_time_of_day();
 var defaultTileflowManifestUrl = "/tileflow/manifest.json";
 var defaultTileflowRuntimeView = Object.freeze({
   bearing: 0,
@@ -532,7 +639,8 @@ function resolveTileflowRuntimeStyle(options) {
     const theme = resolveTileflowRuntimeTheme(
       options.manifestMap,
       options.theme,
-      options.colorScheme
+      options.colorScheme,
+      options.timeOfDay
     );
     return {
       analytics: {
@@ -549,7 +657,7 @@ function resolveTileflowRuntimeStyle(options) {
   }
   return null;
 }
-function resolveTileflowRuntimeTheme(map, selection, colorScheme) {
+function resolveTileflowRuntimeTheme(map, selection, colorScheme, timeOfDay) {
   let name;
   if (selection === void 0) {
     name = map.defaultTheme;
@@ -571,6 +679,8 @@ function resolveTileflowRuntimeTheme(map, selection, colorScheme) {
       `Tileflow resolved invalid theme ${JSON.stringify(name)} for map "${map.name}"; expected a concrete portable theme name.`
     );
   }
+  if (Object.hasOwn(map.themes, name))
+    name = resolveTileflowTimeOfDayTheme(map.timeOfDay, name, timeOfDay);
   const theme = Object.hasOwn(map.themes, name) ? map.themes[name] : void 0;
   if (!theme) {
     const available = Object.keys(map.themes).sort().join(", ");
@@ -1106,6 +1216,7 @@ function resolveTileflowManifestMap(manifest, mapName) {
     defaultTheme: entry.defaultTheme,
     ...entry.environment ? { environment: entry.environment } : {},
     ...entry.systemThemes ? { systemThemes: { ...entry.systemThemes } } : {},
+    ...entry.timeOfDay ? { timeOfDay: entry.timeOfDay } : {},
     themes: entry.themes,
     usageMode: entry.usageMode,
     view: entry.view,
@@ -1123,7 +1234,12 @@ function resolveTileflowStaticImageUrl(input) {
   const apiUrl = normalizeTileflowUrl(input.manifestMap.apiUrl ?? "https://api.tileflow.dev");
   const mapId = encodeURIComponent(input.manifestMap.mapId);
   const url = new URL(`/maps/${mapId}/static.png`, apiUrl);
-  const theme = resolveTileflowRuntimeTheme(input.manifestMap, input.theme, input.colorScheme);
+  const theme = resolveTileflowRuntimeTheme(
+    input.manifestMap,
+    input.theme,
+    input.colorScheme,
+    input.timeOfDay
+  );
   url.searchParams.set("center", input.center.join(","));
   url.searchParams.set("theme", theme.name);
   url.searchParams.set("zoom", String(input.zoom));
@@ -1291,6 +1407,7 @@ export {
   getTileflowAnalyticsApiUrl,
   getTileflowStyleFontFaces,
   inferTileflowAnalyticsFromStyleUrl,
+  isTileflowTimeOfDay,
   loadTileflowManifest,
   mergeTileflowAnalytics,
   nearestTileflowBlendTheme,
@@ -1311,6 +1428,7 @@ export {
   tileflowStyleFontFaceLimits,
   tileflowStyleFontFacesMetadataKey,
   tileflowThemeBlendLimits,
+  tileflowTimesOfDay,
   validateTileflowRuntimeSource,
   validateTileflowThemeBlendSelection,
   validateTileflowThemeSelection

package/docs/authoring-model.md

@@ -215,6 +215,10 @@ surveyed isoline. `water({bathymetryLabels: {}})` separately opts into numeric m
 from each polygon's absolute minimum band depth. Existing maps gain neither detail by default, and
 sources without bathymetry bindings omit both requested layers. These labels describe coarse band
 floors, not measured survey soundings, and must not be presented as hydrographic sounding data.
+An explicitly selected Bathymetry source can instead declare `vectorLayers.contours: true` to use
+real contour lines and their `depth` values. Its optional named seafloor and water features have
+separate `water.bathymetryLandforms` and `water.bathymetryWaterNames` styles, with the language
+selected by `labels(...)`. See [the marine source contract](data-is-separate-from-design.md#declare-contour-and-name-layers).
 
 `addresses` renders the standard OpenMapTiles `housenumber` points at detailed zooms and exposes a
 single semantic `labels` style. `landforms` renders the standard `mountain_peak` classes (`peak`,

package/docs/buildings-3d.md

@@ -1,11 +1,15 @@
 # 3D buildings
 
-`createTileflowBuildings3D` raises the buildings of a Tileflow map's vector tiles round the camera
-and lights them from the theme controller's sun: walls and roofs take the light by how they face
-it, buildings cast shadows on each other and on the flat map, the ground darkens at the foot of the
-walls, and at night flood lights wash the foot of shops, busy places, landmarks and towers while
-the places busy at night light their ground floors. Showing, hiding and growing the city lays out
-no source, so it works as a 3D switch and as an animated height.
+`createTileflowBuildings3D` raises the buildings of a Tileflow map's vector tiles round the camera.
+By default it preserves the map's building colours and native extrusion lighting (`style.light`
+and its vertical wall gradient). Showing, hiding and changing height are immediate. Cast shadows,
+contact shadow, illuminated outlines, random colour variation and night lights are off.
+
+Scene sun lighting, shadows, decorative effects and animated height remain available through
+explicit options. They are independent of the map's trees.
+
+Tileflow landmarks and a map's own building models can stand in the same 3D scene, replacing
+the buildings under their footprints.
 
 It is a custom WebGL2 layer for MapLibre GL JS, drawn above the map's buildings and below its
 labels. It needs WebGL2 and the Mercator projection, which MapLibre's globe turns into from about
@@ -27,23 +31,27 @@ import {
 
 export function raiseTheCity(map: TileflowBuildings3DMap, controller: TileflowThemeController) {
   const buildings = createTileflowBuildings3D({map, controller});
-  // The buildings slide out of the ground over a second.
-  void buildings.show({transition: {duration: 1000}});
+  // No animation unless requested.
+  void buildings.show();
   return buildings;
 }
 ```
 
-`show()` raises the buildings, `hide()` sinks them back into the flat map, and `grow(scale)` eases
-them to a share of their height, from 0 to 1. Each returns a promise that resolves once the motion
-ends; a newer call takes over from where the buildings stand. A browser preference for reduced
+`show()`, `hide()` and `grow(scale)` change the height immediately by default (duration 0).
+`show({transition: {duration: 800, mode: 'fade'}})` reveals full-height buildings with a
+dithered fade. The default animation mode is `grow`; both modes respect reduced-motion settings.
+To animate, pass `{transition: {duration: 800}}` explicitly; `grow(scale)` accepts a height share
+from 0 to 1. Each returns a promise that resolves once the change ends; a newer call takes over from where the buildings stand. A browser preference for reduced
 motion changes at once. `dispose()` takes the layer off the map.
 
 The renderer reads the source's z15 tiles round the camera (z15 is where World's buildings carry
 their heights; a source that stops earlier is read at its own maximum zoom), up to `maxTiles`
 tiles (25 by default), and meshes them a few milliseconds per frame. It reads World's
-`render_height`, `render_min_height`, `hide_3d`, `building_tone` and `night_use`, and the places in
-World's `poi` layer (see [night light](#night-light)). `stats.declared` tells whether the map's
-style describes its 3D buildings; a style compiled before this description gets the defaults below.
+`render_height`, `render_min_height`, `hide_3d`, `height_source`, `building_tone`, `class`,
+`night_use` and the roof fields (see [roofs](#roofs)), and the places in World's `poi` layer (see
+[night light](#night-light)). `stats.declared` tells whether the map's
+style describes its 3D buildings. Recompile existing maps to pick up the new defaults: previously
+compiled metadata with explicit effects enabled continues to honour those values.
 
 ## Design the buildings in the map
 
@@ -66,7 +74,16 @@ export default defineMap({
   extends: streets,
   modules: {
     buildings: refine({
-      threeDimensional: {windows: true, nightLight: 0.6, edgeColor: '#2b2a33'},
+      threeDimensional: {
+        lighting: 'sun',
+        shadows: true,
+        occlusion: true,
+        edges: 1,
+        colorVariation: 0.06,
+        windows: true,
+        nightLight: 0.6,
+        edgeColor: '#2b2a33',
+      },
       renderStack: {
         // Core's 3D buildings take the colour of the map's 3D building pass.
         tints: refineRenderTarget({
@@ -91,14 +108,140 @@ export default defineMap({
   set of themes changes, and the themes either side of a blend's position mix on the GPU, so a
   moving blend costs nothing per frame.
 - `threeDimensional.shadows` and `occlusion` (the band at the foot of the walls and the darker tight
-  corners) default to true. `windows: true` adds invented night windows, lit by rooms; they are
-  decoration, not data, and are off by default.
+  corners) default to false. `windows: true` adds invented night windows, lit by rooms; they are
+  decoration, not data, and are off by default. Where World says what a building is used for
+  (`class`), sheds, garages, barns, factories, churches and service buildings get no rows of
+  windows, homes light more of theirs at night, in a warm light, and offices, schools and hospitals
+  fewer, in a cooler one.
 - `threeDimensional.edges` and `edgeColor` set the [edges](#edges), and `nightLight` the
   [night light](#night-light). Numbers and colours may be theme tokens.
 
+## Landmarks
+
+Maps on Tileflow World show Tileflow's landmarks, such as the Eiffel Tower, as 3D models in place of
+the buildings under them. They come from a landmarks tileset kept apart from the map's data: each of
+its tiles carries the models standing in it, with their levels of detail and footprints, and each
+region's index names its tiles by their hash. The renderer reads the tileset's TileJSON once the
+buildings show in 3D, then only the indexes of the regions round the camera and the landmark tiles
+near it, so a landmark in Paris costs nothing in Madrid. New and improved landmarks reach every map
+without a new build of the map. A tileset that cannot be read is tried again after five minutes,
+and the buildings stay drawn meanwhile.
+
+A map switches them off, or names the TileJSON of another landmarks tileset:
+
+<!-- docs:check -->
+
+```ts
+import {defineMap, refine} from '@tileflow/core';
+import {streets} from '@tileflow/maps';
+
+export default defineMap({
+  id: 'no-landmarks',
+  name: 'Streets without landmarks',
+  version: 1,
+  extends: streets,
+  modules: {
+    buildings: refine({threeDimensional: {landmarks: false}}),
+  },
+});
+```
+
+The map's own building models come first: a landmark with the same id as one of them, or whose
+footprint meets one's, is not drawn.
+
+## Building models
+
+A map can place its own 3D models of buildings in the city: a landmark the extruded footprints draw
+badly, or the buildings an application presents. Each model stands where the map says, in the same
+light, shadows and theme as the buildings round it, and the buildings under its footprint are no
+longer raised while it stands. Put glTF binaries (`.glb`) in a directory, declare it in the map's
+`models`, and say where each model stands:
+
+<!-- docs:check -->
+
+```ts
+import {defineMap, refine} from '@tileflow/core';
+import {streets, streetsModels} from '@tileflow/maps';
+
+export default defineMap({
+  id: 'paris-landmarks',
+  name: 'Paris landmarks',
+  version: 1,
+  extends: streets,
+  // ./models holds eiffel-tower.glb, and eiffel-tower.mid.glb and eiffel-tower.far.glb for
+  // farther views.
+  // Keep Streets' tree models alongside the building models.
+  models: [streetsModels, './models'],
+  modules: {
+    buildings: refine({
+      threeDimensional: {
+        models: [{model: 'eiffel-tower', at: [2.294481, 48.858258], heading: 0}],
+        modelColors: {surface: '#7a5c45', accent: '#5b4332'},
+      },
+    }),
+  },
+});
+```
+
+`at` is the longitude and latitude of the model's origin and `heading` the degrees clockwise from
+north its own north is turned to. A map places up to 256 models; one model may stand in several
+places. A placement may instead name a prepared model file served elsewhere with `url`, its HTTPS
+address; the map then needs no `.glb` of its own for it.
+
+How to prepare a model:
+
+- **Materials name the parts.** Name each material `surface`, `secondary`, `glass`, `accent` or
+  `roof` (an exporter's `.001` suffix is ignored); a model whose materials name a tree's parts is a
+  [tree model](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/trees-3d.md)
+  instead. Each part takes its colour from `modelColors`, or from the buildings' colour when the
+  design gives it none, so the model follows the theme from day to night; vertex colours lighter or
+  darker than the rest of their part shade it within that colour.
+- **Metres round an origin on the ground.** The origin is where the model stands, with the model
+  above it and its own north along +y once read Z up; nothing may lie more than half a metre below
+  it.
+- **What it stands in for.** A mesh whose material is named `footprint` is never drawn: it lays
+  out on the ground what the model stands in for, such as a landmark's whole base. Without one, the
+  model's own outline on the ground stands in, courtyards included.
+- **Levels of detail.** `<id>.mid.glb` and `<id>.far.glb`, when present, are drawn farther from the
+  camera's centre, from about 900 m and 2.6 km.
+- **Budgets.** A level has at most 200,000 triangles and 200,000 vertices, and a map at most 64
+  building models. Triangles of the default scene are read with their node transforms; textures,
+  animations and compressed geometry (Draco or meshopt) are not.
+
+The build reads each model, reports a problem with the file and what to change, works out its
+footprint and writes it beside the style as a prepared model file: a glTF binary whose meshes are
+quantised (`KHR_mesh_quantization`) and compressed by meshoptimizer (`EXT_meshopt_compression`),
+which any glTF viewer opens. The renderer downloads a model only when it stands near the tiles round
+the camera, keeps the nearest dozen, and builds the tiles under it again without the buildings that
+reach more than half a metre into its footprint; a neighbour that only touches it stays. A model
+that cannot be downloaded leaves those buildings standing. Reading a prepared model file loads
+meshoptimizer's WebAssembly decoder, so a page with a Content Security Policy allows
+`'wasm-unsafe-eval'` in its `script-src`.
+
+## Roofs
+
+A building whose tiles carry a roof shape (World's `roof_shape`) gets that roof: `gabled`,
+`hipped`, `half_hipped`, `pyramidal`, `skillion`, `gambrel`, `mansard` and `saltbox` roofs, and
+faceted `dome`, `onion` and `round` ones. The ridge follows the building's long side, or
+`roof_orientation` and `roof_direction` when the tiles state them, and the walls rise to the roof,
+so gable ends are walls. Each slope takes the sun, shadows and edges like any face: the ridge and
+the hips are drawn as edges too.
+
+The roof's height is `roof_height` where the tiles state it, taken from the building's height.
+Otherwise the roof keeps the pitch of its shape (30° for a gabled or hipped roof, a half sphere for a
+dome); it stands on the walls when the height came from levels or a fallback, and reaches the
+building's height when that was measured (`height_source` `height`). A building without a roof
+shape, a flat roof, a building with courtyards or one far from a rectangle (an L, a U) keeps a flat
+roof, and so does a building a tile's buffer cuts short.
+
 ## Light and shadows
 
-The light comes from `controller.getSun()`: the theme's sun, mixed during a blend, or the sun an
+`threeDimensional.lighting` defaults to `'style'`: it uses MapLibre's `light` position,
+anchor, colour and intensity, together with the authored extrusion's `verticalGradient`.
+Changing the scene sun does not change this base lighting. The style's native lighting defaults
+apply when it declares no light.
+
+With `lighting: 'sun'`, the light comes from `controller.getSun()`: the theme's sun, mixed during a blend, or the sun an
 application places by direction or by date and place (see
 [sun and light](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/sun-and-light.md)).
 A sunlit roof keeps the building's colour, a wall turned to a low sun glows, and shade takes the
@@ -113,15 +256,16 @@ buildings, it multiplies the ground by the shadows and by a band at the foot of
 and icons drawn above it keep their colours. Layers kept under 3D content with
 `createTileflowGroundLayers` are darkened with the ground. Other Core 3D layers on the map, such as
 [3D trees](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/trees-3d.md), share
-the buildings' shadows.
+the buildings' shadows when `shadows: true`. With it off, buildings neither cast nor receive
+scene shadows, even when another 3D layer uses them.
 
 ## Edges
 
 Where one building ends and the next starts stays legible at any distance: each roof's outline and
-each building's outer corners catch the light in a line one CSS pixel wide, whatever the zoom, and
-each building is a little lighter or darker than its colour (up to 6%), so neighbours of one colour
-stay apart. The lines are strongest at night; diagonals inside a roof, inner corners and the cuts at
-a tile's edge draw none. `edges` sets their strength from 0 (none) to 1, the default.
+each building's outer corners catch the light in a line one CSS pixel wide, whatever the zoom, when enabled. `colorVariation` independently varies building brightness by up to the specified
+fraction (0–1); it defaults to 0, so authored colours remain unchanged. Use 0.06 for the earlier
+6% variation. The lines are strongest at night; diagonals inside a roof, inner corners and the cuts at
+a tile's edge draw none. `edges` sets their strength from 0 (the default, none) to 1.
 
 `edgeColor` gives the lines a colour of the map's own, per theme through a token: a dark outline as
 on a printed map, or a neon one at night. It is drawn as it is, unlit, at the full `edges` strength
@@ -129,8 +273,8 @@ by day and night, mixed between the themes either side of a blend's position.
 
 ## Night light
 
-At night (as the sun's `brightness` falls), the buildings light the street from data, quietly by
-default:
+With `nightLight` above 0, the buildings light the street from data at night (as the sun's
+`brightness` falls):
 
 - Landmarks (World's `building_tone` `destination`) and towers of 40 m or more, one in two, are
   flood-lit at their foot, on the wall and the ground around it.
@@ -144,7 +288,7 @@ The night use comes from World's `night_use` on each building. In tiles whose bu
 carry it, the renderer finds it in the tile's places: a place inside a building, or within a few
 metres of its facade, gives the building its use.
 
-`nightLight` sets how bright all of this shines, from 0 (none) to 2; it defaults to 1.
+`nightLight` sets how bright all of this shines, from 0 (none) to 2; it defaults to 0.
 
 For the streets themselves, see
 [street lights](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/street-lights.md),
@@ -167,6 +311,11 @@ way kept the frame pacing of the same city drawn without shadows.
 
 - Mercator only; the layer draws nothing below its `minzoom`.
 - No terrain: buildings stand on flat ground.
-- One building colour per feature and theme; facades, roof shapes and building parts as separate
-  shapes are not drawn.
+- One building colour per feature and theme, on its roof and walls alike; facades are not drawn.
+- Roofs follow the building's smallest enclosing rectangle: a building with courtyards or far from a
+  rectangle keeps a flat roof, and `sawtooth` roofs are drawn flat.
 - A colour expression is evaluated at zoom 16.
+- Building models and landmarks take no edges or night light of their own yet, and cannot be
+  picked or styled by state.
+- Hosted deploys do not take a map's own model files yet: `tileflow validate --target hosted` reports
+  them. Models named by `url` deploy as they are.

package/docs/compiled-style-performance.md

@@ -249,8 +249,19 @@ The closed category vocabulary is `arts-entertainment`, `education`, `food-drink
 `transport`, and `visitor-amenity`. Producer `type` and `icon` values use stable snake_case names.
 When an `icon` sprite exists it is used directly; an unknown or absent icon safely falls back to the
 category's themed image role. `labels` and `icons` are booleans. Category styles control only
-presentation and may hide or delay candidates, never promote them above the producer's selection.
-`placement.coupleIconAndLabel` keeps a POI's icon and label atomic during collision placement.
+presentation and never promote candidates above the producer's selection.
+`placement.coupleIconAndLabel` keeps a POI's icon and label atomic during collision placement:
+both are required.
+
+MapLibre orders symbol placement only within a layer, so the module compiles every category into
+one layer per representation and orders it by `filter_rank` and `size_rank`: a station is placed
+before a cash machine whatever their categories. Per-category appearance becomes a `match` on
+`category`; zoom curves are hoisted above it so each category keeps its exact curve. Categories that
+need different layer-wide properties use `placement.order: 'categories'`, one layer per category in
+listed order. `placement.prominentRank` places the most important ranks in a second layer above road
+and place labels, which keeps landmarks visible on maps whose labels give street names priority.
+When icons and labels are both drawn, unnamed POIs are omitted except the self-explanatory types in
+`placement.iconOnlyTypes` (parking and public toilets by default), which draw only their pictogram.
 
 ```ts
 poi({
@@ -263,4 +274,4 @@ poi({
 
 The same contract drives regular POI layers, custom HUD treatments, semantic interactions, and
 feature inspection. There is intentionally no compatibility path for the former class mapping,
-rank ceilings, or named density/detail presets.
+rank ceilings, per-category densities, or named density/detail presets.