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

package/docs/buildings-3d.md

@@ -1,19 +1,25 @@
 # 3D buildings
 
 `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.
+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.
 
-Scene sun lighting, shadows, decorative effects and animated height remain available through
-explicit options. They are independent of the map's trees.
+Streets supplies architectural flood lighting and subtle model wall emission for its dark
+presets. These controls are independent of invented windows and the optional `nightLight` effects.
 
 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
 
@@ -31,15 +37,14 @@ import {
 
 export function raiseTheCity(map: TileflowBuildings3DMap, controller: TileflowThemeController) {
   const buildings = createTileflowBuildings3D({map, controller});
-  // No animation unless requested.
-  void buildings.show();
+  // Enabled on creation; hide() and show() override visibility.
   return buildings;
 }
 ```
 
 `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.
+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.
@@ -51,7 +56,7 @@ tiles (25 by default), and meshes them a few milliseconds per frame. It reads Wo
 `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.
+compiled metadata keeps explicit settings, including `false`, `0` and `lighting: 'style'`.
 
 ## Design the buildings in the map
 
@@ -108,24 +113,53 @@ 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 false. `windows: true` adds invented night windows, lit by rooms; they are
+  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.
+region's index names its tiles by their hash, with where each landmark stands and its footprint.
+The renderer reads the tileset's TileJSON, then only the indexes of the regions round the camera
+and the landmark tiles near it, from a zoom before the buildings show, so a landmark in Paris costs
+nothing in Madrid. New and improved landmarks reach every map without a new build of the map.
+
+The buildings under a landmark are never raised and then taken away. A tile of buildings is built
+once the indexes round it have arrived, waiting at most a second and a half; while a landmark's
+tile is still on its way, the footprint its index names keeps the buildings under it flat, and the
+landmark fades in when it arrives. A landmark tile that fails, or has not arrived three seconds
+after the buildings round it show, lets those buildings rise until it does. 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:
 
@@ -196,6 +230,10 @@ How to prepare a model:
   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.
+- **Architectural roles control lighting.** A material may set
+  `extras.tileflow.lightingRole` to `wall`, `door`, `roof`, `window`, `lamp`, `logo` or
+  `unclassified`. This preserves its palette slot. Without a role, `surface`, `secondary` and
+  `accent` are walls, `glass` is a window, and `roof` is a roof.
 - **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.
@@ -212,12 +250,49 @@ The build reads each model, reports a problem with the file and what to change,
 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
+the camera, whether or not those tiles hold buildings, 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 tile of
+buildings near a model waits for it, at most a second and a half, so its buildings are not raised
+and then taken away, and the model fades in when it comes to stand. 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`.
 
+Preparation also computes local geometric ambient visibility, independently of the model's
+colour. `modelOcclusion` sets its strength from zero to one (default `0.75`); `occlusion: false`
+disables it. Occluded cavities receive less ambient light while direct sun and dynamic shadows
+remain independent. Existing prepared files with fully exposed vertices retain their appearance.
+Reprepare their original GLBs to gain geometric occlusion. See
+[model preparation](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/docs/building-models.md)
+for authoring, sampling and costs.
+
+## Team 3D models
+
+On Tileflow Hosted, a map's building models are its Team's 3D models: each is published once, under
+its name, and every map of the Team that places a model of that name draws it. Locally, the map
+draws its own `.glb` files, so the map is previewed and developed without an account.
+
+```sh
+npx tileflow models publish ./models/eiffel-tower.glb --team @acme
+npx tileflow models status eiffel-tower --team @acme
+```
+
+`tileflow models publish` prepares each building model as a build does and publishes it as the
+model's new current version; with no path, it publishes the building models of every map in the
+project's config. Publishing the bytes of the current version again changes nothing. A hosted map
+follows each model's current version: a new version, or `tileflow models restore`, which makes the
+previous version current again, changes every map that places it the next time the map loads,
+without deploying the maps again. A model keeps its current and previous versions.
+
+`tileflow deploy` writes each placement of a building model as the placeholder
+`tileflow://team-models/<name>` (`tileflowTeamModelUrl(name)`), which the deploy replaces with the
+model's address in the map's Team; a model the Team has not published fails the deploy. The deploy
+also reports a model whose published version was prepared from other files than the map's, so an
+outdated model is easy to spot. A model's file, and what Tileflow shows about it, can be read
+without decoding its meshes with `readTileflowModelFileSummary`. Models are served publicly and may
+be cached, so they must not hold secrets or restricted personal data.
+
 ## Roofs
 
 A building whose tiles carry a roof shape (World's `roof_shape`) gets that roof: `gabled`,
@@ -236,16 +311,49 @@ roof, and so does a building a tile's buffer cuts short.
 
 ## Light and shadows
 
-`threeDimensional.lighting` defaults to `'style'`: it uses MapLibre's `light` position,
+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 `lighting: 'sun'`, the light comes from `controller.getSun()`: the theme's sun, mixed during a blend, or the sun an
+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
@@ -273,6 +381,42 @@ by day and night, mixed between the themes either side of a blend's position.
 
 ## Night light
 
+Architectural illumination has two independent controls:
+
+- `floodLight` selects ordinary buildings by height. Ground light starts at `minGroundHeight`
+  (30 m by default), with a stable per-building `groundRadius` in metres (default `[30, 100]`).
+  Wall light starts above `minWallHeight` (200 m); its reach is building height times
+  `wallHeightRatio` (default `1/3`). `intensity` is zero to one and `color` is a theme colour.
+  The effect fades with scene brightness; `brightnessScale` compensates an authored light-colour
+  transform and defaults to one. Overlapping ground contributions use their strongest value.
+- `modelLighting` assigns physical materials and emission to architectural roles. Each profile accepts
+  `emissiveStrength` (zero to five), optional `emissiveColor` (otherwise the surface's own colour), and
+  `emissiveHeight`: `[beginHeight, endHeight, beginMultiplier, endMultiplier, curve]`.
+  Heights are fractions of the source mesh's vertical bounds (the full model for legacy files),
+  multipliers are zero to one, and the exponent is
+  `10 ** curve`, with `curve` from -1 to 1. Equal heights give a constant multiplier of one.
+  Every gradient component, strength and colour may use theme tokens. Emission is mixed in linear light and is independent
+  of ambient occlusion and solar shadows. Values above one saturate the surface emission at one;
+  they also control the falloff of explicitly authored area emitters.
+
+Physical profiles also accept `color`, `colorMix` (zero to one, default one when a tint exists),
+`roughness` and `metallic` (zero to one). Explicit `modelColors` override role tints. Missing
+physical overrides retain the glTF material. `emissiveVariation` adds a stable, model-seeded amount
+from zero to its value. Optional `colorVariation` supplies independent `[min, max]` ranges for
+`hue` (0–360), `saturation` and `lightness` (0–100), with `space: 'srgb'` (default) or `'linear'`.
+The same model identity keeps its samples across LODs and theme changes.
+
+Streets leaves ordinary flood lighting off in its light presets. Its dusk/night wall profile uses a strength
+of `0.1` and `[0.5, 0, 0, 1, 0.8]`, concentrating a warm wash near the foot. Monochrome uses a
+weaker neutral wall profile and no architectural ground flood. Prepared models without role
+metadata use their documented palette mapping. Windows use metallic reflection and varied emission;
+doors and logos have separate profiles, and roofs remain non-emissive. Day/dawn profiles follow
+the scene's brighter material response. A role does not generate missing windows or ground emitters.
+See [building-model preparation](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/docs/building-models.md)
+for glTF channels, explicit area emitters, compatibility and resource costs.
+
+The separate `nightLight` control retains its decorative building and shop effects:
+
 With `nightLight` above 0, the buildings light the street from data at night (as the sun's
 `brightness` falls):
 
@@ -297,15 +441,42 @@ 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.
+
+Model ambient visibility and lighting roles retain the existing 16-byte vertex stride. They add
+no geometry pass or texture. Architectural ground lighting uses a separate one-byte-per-pixel
+mask and one geometry/composite pair of passes while active; its mask is released when inactive.
+At 1280 × 720 and DPR 1, the mask occupies 921,600 bytes, excluding driver overhead.
 
 ## Limits
 
@@ -315,7 +486,9 @@ way kept the frame pacing of the same city drawn without shadows.
 - 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.
+- Building models and landmarks take no illuminated edges and cannot be picked or styled by state.
+- Model materials use semantic colours and role emission; physical roughness, metallic
+  reflections and authored textures are not rendered.
+- A hosted map places its building models as its Team's 3D models: `tileflow deploy` uploads no
+  model files (see [Team 3D models](#team-3d-models)). 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/data-is-separate-from-design.md

@@ -121,14 +121,14 @@ their source faces' shapes. Browser adapters load local faces before MapLibre. N
 `glyphs` URL provider instead, which enumerates the exact comma-joined MapLibre request keys in
 `fontStacks`.
 
-Streets, Ferraris, Härad, Soundings, and Blueprint each declare
+Streets, Soundings, and Blueprint each declare
 `https://api.tileflow.dev/base/33d4de5e8086d9d629d67d3f39fedb87e23686c4c1ac653c27e2a52aee9d00b3/glyphs/{fontstack}/{range}.pbf`
 with the exact `Noto Sans Regular` and `Noto Sans Bold` stacks. The full hash identifies one
 published, immutable glyph collection independent of World data. The older `/fonts/...` endpoint
 remains a mutable compatibility URL and does not make a resolved map byte-reproducible. The global
 glyph `assetSetSha256` is not the same-domain value as the per-map `assetSetSha256` in
 `build-manifest.json`.
-Baedeker and Siegfried each own a packaged directory containing Cormorant Garamond Regular, SemiBold, and Italic.
+Baedeker, 1777, and Siegfried each own a packaged directory containing Cormorant Garamond Regular, SemiBold, and Italic.
 
 Name the official generation deliberately, or use another OpenMapTiles-compatible vector source:
 
@@ -212,48 +212,29 @@ export default defineMap({
   marine: 'chart', // 'none' | 'bathymetry' | 'nautical' | 'chart'
   modules: {
     nautical: nautical({
-      soundings: {minZoom: 13},
-      aids: {minZoom: 11},
-      lights: {minZoom: 12},
-      hazards: {minZoom: 12},
-      hazardAreas: {
-        fill: {opacity: fixed(0.1, {reason: 'Chart hazard wash is invariant'})},
-      },
-      wrecks: {minZoom: 12},
-      wreckAreas: {
-        outline: {opacity: fixed(0.6, {reason: 'Chart wreck outline is invariant'})},
-      },
-      reefs: {fill: {opacity: fixed(0.3, {reason: 'Chart reef wash is invariant'})}},
+      buoys: {minZoom: 12},
+      lights: {minZoom: 9},
       navigationAreas: {
         fill: {opacity: fixed(0.05, {reason: 'Chart navigation-area wash is invariant'})},
       },
-      coverage: {outline: {visible: false}},
-      labels: {
-        navigationAreas: {minZoom: 11},
-        reefs: {minZoom: 13},
-      },
+      reefs: {fill: {opacity: fixed(0.3, {reason: 'Chart reef wash is invariant'})}},
+      labels: {navigationAreas: {minZoom: 12}},
     }),
   },
 });
 ```
 
 `bathymetry` resolves to vector source `tileflow-bathymetry` and supplies the 13-stop
-`bathymetry-v1` band contract to `water(...)`. `nautical` resolves to `tileflow-nautical`; the
-`nautical(...)` module
-styles its `sounding`, `aid`, `light`, `hazard`, `wreck`, `reef`, `navigation_area`, and `coverage`
-layers. The schema also names the product's provider-neutral provenance fields (`provenance`,
-`provider`, `cell`, `edition`, `update`, `scale`, `coverage`, and `licence`). `chart` enables both.
-Point features label depth, name, or light character as applicable. The `lighthouses` symbol style
-targets `aid` points whose canonical `class` is `lighthouse`, leaving other aids under `aids`.
-Polygon reefs, navigation
-areas, hazards, wrecks, and named/provider coverage have separate collision-aware labels under
-`nautical({labels: {...}})`; unnamed coverage does not emit empty text.
+`bathymetry-v1` band contract to `water(...)`. `nautical` resolves to `tileflow-nautical` at
+`/tiles/nautical/tiles.json`; the `nautical(...)` module draws its `nautical-v1` buoys, beacons,
+lighthouses, lights, hazards, wrecks, reefs, navigation areas, routes, cables, harbours, ports, and
+a restrained coverage indication. `chart` enables both. Every map that draws Nautical declares a
+"Not for navigation" notice, which the browser runtimes render on the map. The
+[Nautical marks guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/nautical-marks.md)
+describes the schema, the semantic groups, the theme image tokens, and the notice.
 Core does not hard-code a nautical provider or attribution: the selected TileJSON owns its actual
 coverage and attribution, and derived vector tiles are not represented as a certified ENC for
-navigation. The V1 geometry contract preserves `sounding`, `aid`, and `light` as points;
-`reef`, `navigation_area`, and `coverage` as polygons; and both point and polygon geometries for
-`hazard` and `wreck`. Point symbols and polygon areas compile separately, without fabricated
-centroids.
+navigation. Point symbols and polygon areas compile separately, without fabricated centroids.
 Advanced callers can override either TileJSON URL, attribution, or source ID and can set the other
 member to `false`:
 
@@ -408,6 +389,58 @@ labels default to line placement. Band fills still consume `min_depth` and `sort
 `visible: false` to hide either. Without their declaration, those styles emit no name layers.
 Name styles may use `class` in expressions without changing the source classification.
 
+Mixed geometry can opt into `placementByGeometry` on either name style. Its resolved policy must
+include `point`, `line`, and `polygon`; `point` must be `'point'`, while the other two accept
+`'point'`, `'line'`, or `'line-center'`. The policy overrides scalar `placement`, including an
+inherited value. Without it, scalar placement and existing generated layers remain unchanged.
+
+For example, this map labels point features at their coordinates and retains line placement for
+lines and polygon boundaries:
+
+<!-- docs:check -->
+
+```ts
+import {bathymetry, defineMap, labels, water} from '@tileflow/core';
+import {streets} from '@tileflow/maps';
+
+export default defineMap({
+  id: 'marine-names',
+  version: 1,
+  extends: streets,
+  marine: {
+    bathymetry: bathymetry({
+      vectorLayers: {landforms: {zoomRanges: [{minZoom: 0, maxZoom: 24}]}},
+    }),
+    nautical: false,
+  },
+  modules: {
+    labels: labels({language: 'es'}),
+    water: water({
+      bathymetryLandforms: {
+        placementByGeometry: {point: 'point', line: 'line', polygon: 'line'},
+      },
+    }),
+  },
+});
+```
+
+This example declares source availability; the selected source must actually contain those
+features. Equal placements share one geometry-filtered group per source range. A policy emits
+at most three groups per range (384 layers for one name family at the 128-range limit). Groups
+compile in `point`, `line`, `line-center` order below ordinary map labels; source priority orders
+features within each group. Module refinements inherit the policy and style every group.
+Render-stack refinements still address exact semantic targets; inspect each placement/range
+target when applying a narrower refinement.
+Normal collision still applies and can hide a name.
+
+Placement uses the received geometry: `point` places a line label at its first rendered vertex;
+it does not compute a stable line midpoint. Polygon `point` placement uses an interior position
+of the rendered polygon, while `line` follows its boundary. Core does not generate source anchors,
+merge identities or deduplicate names by text. A source can supply multiple stable point anchors
+with shared identity properties and distinct anchor properties; their extent, visibility and
+editorial policy belong to that source. Keep original source identities as properties rather than
+assuming a universal numeric `feature.id`.
+
 Water-module styles override product-level `bands`, `contours`, and `labels`. Existing custom
 `text.field` expressions remain authoritative: when refining a map from legacy polygons to native
 contours, use `expr.get(field('bathymetryContourDepth'))` for its depth. That auxiliary binding

package/docs/hosted-session-authorization.md

@@ -53,10 +53,8 @@ import {
   civica,
   civicaFonts,
   civicaIcons,
-  ferraris,
-  ferrarisIcons,
-  harad,
-  haradIcons,
+  map1777,
+  map1777Icons,
   siegfried,
   siegfriedFonts,
   siegfriedIcons,