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

package/docs/buildings-3d.md

@@ -1,15 +1,22 @@
 # 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, uses the scene sun, casts shadows, adds soft
+contact shading and rounds exterior corners by 0.8 metres. An unspecified sun uses soft daylight
+with directional intensity 0.2 and ambient intensity 0.8; authored theme lighting stays in control.
+Showing, hiding and changing height are immediate. Illuminated outlines, random colour variation,
+invented windows and night lights remain off. Every effect is independently overridable and
+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
-zoom 12; the buildings stand from zoom 14.5 by default.
+zoom 12. On every map, buildings and placed models appear automatically from zoom 15,
+with opacity rising linearly from 0 at 15 to 1 at 15.25. Zooming back out reverses the fade.
+Their height stays unchanged throughout; shadows and contact shading fade with them.
+`hide()` keeps them hidden at every zoom until `show()` is called.
 
 ## Show the buildings
 
@@ -27,23 +34,26 @@ 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}});
+  // Enabled on creation; hide() and show() override visibility.
   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
+smooth opacity 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 keeps explicit settings, including `false`, `0` and `lighting: 'style'`.
 
 ## Design the buildings in the map
 
@@ -66,7 +76,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,18 +110,200 @@ 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 true. Set either to false independently. `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.
+- `threeDimensional.edgeRadius` rounds convex exterior corners in the mesh and softens the
+  roof/wall lighting transition. It accepts 0–1 metres and defaults to 0.8; use 0 for sharp corners.
+  Courtyard corners and tile cuts stay unchanged. The authored roof shape is preserved; the top
+  edge is softened through lighting, not a geometric roof bevel. Rounding adds a bounded number
+  of vertices at convex corners, with no extra render pass. Changes to this radius rebuild the
+  resident building meshes.
+
+In both `style` and `sun` lighting, the vertical gradient darkens the foot of a facade by ten percent, fading smoothly over
+at most three metres (half the height for low buildings). It is evaluated per fragment, so a tall
+building does not acquire a full-height dark ramp. Disabling the authored extrusion's
+`verticalGradient` disables this shading. Ground contact shadow is controlled by `occlusion`, enabled by default. It extends three metres
+from grounded walls, darkening the ground by at most 16%, with a smooth distance falloff and round
+corners. Every map uses these defaults when it enables `occlusion`. The reach is measured in world
+metres, so its screen width scales continuously with zoom and becomes subtle at distant views.
+Overlaps use the strongest
+shade once, so shared walls, courtyards and tile joins do not accumulate dark bands. Raised building
+parts do not cast contact shade. Facade occlusion darkens the base by at most 14% and fades
+exponentially with a three-metre decay radius: about 5% remains one floor up and 2% two floors up.
+It follows height above ground, so raised parts do not restart the contact gradient at their base.
+The facade gradient, contact and inner-corner shade use the strongest contribution once, avoiding
+an extra dark strip where they overlap. Both lighting modes use the same falloff at every zoom.
+The ground mask uses one byte per drawing-buffer pixel while enabled and is released when disabled
+or the renderer is removed; it resizes with the drawing buffer.
+
+## 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
+Sun lighting and cast shadows are SDK defaults, including for Streets. Each map can choose its
+own finish. For native extrusion lighting, sharp corners and no shadows in an extending map:
+
+<!-- docs:check -->
+
+```ts
+import {defineMap, refine} from '@tileflow/core';
+import {streets} from '@tileflow/maps';
+
+export default defineMap({
+  id: 'graphic-streets',
+  name: 'Graphic streets',
+  version: 1,
+  extends: streets,
+  modules: {
+    buildings: refine({
+      threeDimensional: {lighting: 'style', edgeRadius: 0, shadows: false, occlusion: false},
+    }),
+  },
+});
+```
+
+Select `timeOfDay` through your map adapter to change the authored direction, colour and strength
+of direct and ambient light. Streets includes moonlight and shadows in its night presets. These
+presets are independent of the user's clock and location. In DevTools, use the 3D view and
+**Map → Buildings → Building light / Cast shadows**. The theme's `lighting.sun.shadowIntensity`
+controls shadow strength; `lighting.ambient` fills the shade. Use `controller.setSun({date,
+location})` for an astronomical direction instead, as described in
+[sun and light](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/sun-and-light.md).
+
+`threeDimensional.lighting: 'style'` 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 the default `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)).
+Without a controller, the renderer reads the compiled style's sun, falling back to the style's
+light direction and then the SDK daylight. It refreshes this cached light on style changes.
 A sunlit roof keeps the building's colour, a wall turned to a low sun glows, and shade takes the
-sky's colour. As the sun sets, shadows lengthen while they fade; a sun below the horizon casts none.
+sky's colour. Shadows lengthen as the sun lowers, with their projected direction limited to 15°
+above the horizon. The actual light retains its authored altitude; a sun below the horizon casts none.
 
 A wall sees half the sky, so at night, when the ground gives back little light, walls in shade
 stay darker than roofs. A theme's night `lighting.sun` set high (60° or more) lights roofs more than
@@ -113,15 +314,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 +331,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 +346,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),
@@ -153,20 +355,48 @@ download.
 
 ## Options
 
-The renderer's own options say only how it is delivered: `minzoom` (14.5 by default), `maxTiles`,
+The renderer's own options say only how it is delivered: `minzoom` (15 by default, with a 0.25-zoom opacity ramp), `maxTiles`,
 `beforeId` to place the layer before another one, and `transformRequest` to apply the map's request
 rules to the tiles it reads.
 
 ## Cost
 
-The shadow map (up to 4096 × 4096) is drawn again only when the sun, the buildings or their height
-change, not when the camera moves. In a campaign over Miami at 1512 × 860 at 2×, a city lit this
-way kept the frame pacing of the same city drawn without shadows.
+During partial opacity, a depth-only geometry pass resolves the nearest surfaces before colour
+blending, preventing rear walls from bleeding through. At full opacity only the normal geometry
+pass runs; zoom fading schedules no extra animation frames or per-zoom mesh rebuilds.
+
+The browser bundle prepares building meshes in one worker per renderer and transfers the finished
+vertex and index buffers. No worker URL or extra asset hosting is needed. A Content Security Policy
+must allow `worker-src blob:` to use this path; if workers are unavailable or blocked, the renderer
+falls back to local meshing. The worker is terminated on `dispose()`. Pending tile updates retain
+the previous mesh until their replacement is ready; cancelled and obsolete results are discarded.
+
+Mercator rendering batches buildings spatially and skips batches outside the camera. Shadow
+casting uses the light's bounds independently, so an offscreen building can still cast a visible
+shadow. Ground contact and flood bands retain their physical reach when testing visibility.
+Rounded corners use fewer segments when their screen radius is small and retain the original
+tessellation up close. Latitude, radius and pitch inform this choice; very oblique views keep full
+detail. Changes are prepared asynchronously; heights, feature colours,
+and the contact-shadow settings stay the same. GPU uploads remain limited to two tiles per frame.
+
+The shared shadow map is at most 4096 × 4096. On a planar view it concentrates resolution on visible
+ground and raised surfaces, while every loaded caster can still project into that area. A snapped
+Mercator texel grid stays stable during small pans, including changes of latitude, without fixing
+the meshes' physical metre scale. One filtered depth comparison keeps edges sharp.
+Missing camera capabilities, terrain or a view near the horizon use the full loaded area instead.
+The depth pass runs again when its focused area, light or casting geometry changes and is reused
+when they stay unchanged.
 
 ## Limits
 
 - 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.
+- A hosted map takes up to 64 building models of its own, 32 MiB once prepared; `tileflow deploy`
+  uploads them with the map. A deploy with `--with-native` does not take them, since MapLibre Native
+  draws no models. Models named by `url` deploy as they are.

package/docs/cartographic-defaults.md

@@ -0,0 +1,142 @@
+# Cartographic defaults
+
+Start with the [Core guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/README.md)
+for installation and a complete map. Semantic modules supply a coordinated starting appearance;
+module styles and owner-local render targets can replace those decisions.
+
+## Roads and roundabouts
+
+`roads({rampOrder: 'below-roads'})` draws ramp fills before receiving carriageways in the same
+surface, bridge or tunnel band. This prevents a rounded ramp endpoint covering the receiving
+road. Choose `'by-class'` to retain class-based fill order instead. Explicit render-stack moves
+remain available; ramp fills have targets `roads.classes.<class>.<structure>.rampFill` when the
+separate ramp order is active. A selector refinement replaces that target's complete filter, so
+retain its ramp eligibility when writing a custom selector. Module class fill styles apply to
+both passes; a refinement of a specific `fill` or `rampFill` target changes only that pass.
+
+Core owns circular-road geometry. Physical inner and outer radii take precedence when provided
+by the source. Otherwise the ring follows the enabled class's effective surface width, including
+width treatments. The default border follows the actual casing width and gap. Hidden classes and
+surface fills do not leave orphan rings. Ring colors remain semantic palette choices, independently
+replaceable through `roundabouts.fill.strokeColor` and `roundabouts.casing.strokeColor`; they do
+not copy arbitrary per-class color curves.
+
+Metric scaling and base-2 width curves retain their native interpolation. Other width curves are
+sampled into the shared geometry curve: numeric widths target 0.1-pixel error, stopping refinement
+once intervals reach 1/32 zoom; very large widths can exceed that target. Feature-dependent width
+expressions retain authored and integer zoom stops without adaptive refinement, keeping expression
+size bounded. Their interpolation between stops is approximate, with no universal pixel-error bound.
+Step changes complete at the authored zoom, with the transition confined to the preceding 0.000001
+zoom interval. Explicit circle radius and stroke-width expressions bypass this sampling when exact
+independent behavior is required.
+
+`roundabouts.fallbackWidth` replaces only the fallback carriageway width in pixels;
+`roundabouts.borderWidth` replaces the total extra width around the ring. Existing circle styles
+can independently replace radius, stroke width, color, opacity and zoom range. For example, this
+module fragment retains geometric defaults but gives rings a deliberate fixed border:
+
+<!-- docs:check -->
+
+```ts
+import {roads} from '@tileflow/core';
+
+export const customRoads = roads({
+  rampOrder: 'by-class',
+  roundabouts: {borderWidth: 0},
+});
+```
+
+## Ground surfaces
+
+The land module draws broad cover and park surfaces before mapped grass, meadow, scrub and
+flowerbed details. Parking, sports pitches, tracks, playgrounds and zoos follow those details so
+they remain visible inside broad green polygons. Both Tileflow World and OpenMapTiles' combined
+park source follow this order. These defaults do not change the map's colors, opacity or textures.
+
+A thematic map can give a park tint more prominence through the existing render stack. This
+module fragment is ready to use as `modules.land` in a map:
+
+<!-- docs:check -->
+
+```ts
+import {land, refineRenderTarget, withRenderStack} from '@tileflow/core';
+
+export const thematicLand = withRenderStack(land(), {
+  parkTint: refineRenderTarget({
+    target: 'land.landcover.urbanPark.fill',
+    placement: 'above-land',
+  }),
+});
+```
+
+Refinements target contributions that the map actually draws. Disabling a target and retaining
+a refinement for it is an authoring error. Disabling the whole module removes its contributions
+and its render stack. The built-in surface order needs no target anchors and works when individual
+surfaces are hidden.
+
+## Street names on the ground or in the foreground
+
+`labels({roadPlacement: 'foreground'})` is the default. Names draw above buildings and vegetation.
+Use `roadPlacement: 'ground'` to draw them below buildings, with text aligned to the map surface.
+Shields and junction numbers remain in the foreground. Ground placement does not require the
+buildings module: street names still draw when buildings are disabled.
+
+This module fragment keeps the normal language selection and road-class filters while opting
+into ground names. Individual symbol styles can override the default text alignment:
+
+<!-- docs:check -->
+
+```ts
+import {labels} from '@tileflow/core';
+
+export const groundLabels = labels({
+  roadPlacement: 'ground',
+  collisionPriority: 'navigation',
+  language: 'local',
+  roads: 'all',
+  styles: {
+    roads: {
+      primary: {text: {pitchAlignment: 'viewport'}},
+    },
+  },
+});
+```
+
+MapLibre offers foreground symbols first when resolving collisions. Ground names therefore yield
+to POIs and other foreground symbols, even with `collisionPriority: 'navigation'`. Navigation
+priority still orders the ground road classes relative to one another; it does not make their
+collision priority independent of drawing order. Foreground placement retains the existing
+navigation priority over ordinary POIs. Neither mode turns collision detection off.
+
+Use a refinement on `labels.roads.<class>` to move an individual class after this default has been
+applied. Symbol size, zoom range, spacing, priority, fonts and halos remain available in
+`styles.roads`. The same names, language fallbacks and class selectors are used in both modes.
+
+## Discover and override decisions
+
+`tileflow describe labels --json` exposes the installed options, and `tileflow inspect --json`
+shows resolved inheritance and merge provenance. `tileflow explain --inspection --json` adds
+compiled semantic targets and physical provenance. These commands describe the authored map;
+they do not rewrite explicit style choices.
+
+`tileflow describe themes --json` lists the twelve required base color roles and composition
+rules. A [single independent theme](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/themes-and-module-styles.md)
+needs no time-of-day catalog. Optional color roles derive from that theme and accept explicit
+replacements. Removing inherited lighting uses `reset()` inside `defineTheme`; it restores the
+SDK fallback, while building shadows and occlusion have separate on/off controls.
+
+`createStyleResult()` and `tileflow inspect compiled --json` include `report.decisions`: actual
+color roles and selected road, label and 3D-building policies, each with its value, source,
+reason and override guidance. Query `--path /report/decisions --limit 80` to bound this output.
+`default` means an SDK fallback, `map` a value in the resolved map, `theme` a role defined by the
+selected theme and `derived` an optional role computed by Core. Use config inspection's merge
+provenance to distinguish inherited map values from leaf overrides. These decisions describe
+module policies and the theme's color context; later module styles and render-stack refinements
+can override them. They are not a trace of every final paint property or a visual-quality score.
+Simple `createStyle()` and browser drawing do not collect this report.
+
+Replace an inherited module with its constructor, patch it with `refine()`, restore an inherited
+value with `reset()`, or remove the whole domain with `disable()`. See the
+[authoring model](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/authoring-model.md)
+for these composition rules. Capture contrasting designs and compare them at matching cameras to
+check both the default result and intentional departures from it.

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.