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

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,26 +31,217 @@ 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)).
+`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
+
+The map describes how its 3D buildings look, in its buildings module, and publishes it with its
+style for every theme; the renderer follows theme changes and blends. The design is visible in
+`tileflow preview` and validated with the rest of the map:
+
+<!-- docs:check -->
+
+```ts
+import {defineMap, expr, field, refine, refineRenderTarget} from '@tileflow/core';
+import {streets} from '@tileflow/maps';
+
+const floors = expr.divide(expr.toNumber(expr.get(field('renderHeight')), 0), 3.2);
+
+export default defineMap({
+  id: 'lit-city',
+  name: 'Lit city',
+  version: 1,
+  extends: streets,
+  modules: {
+    buildings: refine({
+      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({
+          target: 'buildings.render.extrusion',
+          renderer: 'extrusion',
+          style: {
+            color: expr.step(expr.modulo(floors, 3), '#e8d9c4', [
+              [1, '#d6e2d8'],
+              [2, '#e5d4e6'],
+            ]),
+          },
+        }),
+      },
+    }),
+  },
+});
+```
+
+- Colour: each building takes the colour the map gives its 3D buildings: Streets' 3D building pass
+  (the theme's `buildings.extrusion`), else the buildings module's extrusion, else its roofs. A
+  colour that depends on the building's data is evaluated per building and theme when a tile or the
+  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
+  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
@@ -59,49 +254,27 @@ any wall, so roofs and walls read apart under the moon.
 MapLibre's own layers take no shadows, so the renderer darkens the map it is drawn over: after its
 buildings, it multiplies the ground by the shadows and by a band at the foot of the walls. Labels
 and icons drawn above it keep their colours. Layers kept under 3D content with
-`createTileflowGroundLayers` are darkened with the ground.
-
-`shadows` and `occlusion` (the band at the foot of the walls and the darker tight corners) default
-to true and can be turned off. `windows: true` adds invented night windows, lit by rooms; they are
-decoration, not data, and are off by default.
+`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 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.
-
-`edgeColor` gives the lines a colour of the application's own, as a CSS colour or per theme: 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 by day and night. The renderer asks for each theme's colour once and mixes the
-colours of the themes either side of a blend's position; a theme without a valid colour keeps the
-default.
-
-<!-- docs:check -->
-
-```ts
-import {
-  createTileflowBuildings3D,
-  type TileflowBuildings3DMap,
-  type TileflowThemeController,
-} from '@tileflow/core/browser';
+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.
 
-export function neonEdges(map: TileflowBuildings3DMap, controller: TileflowThemeController) {
-  return createTileflowBuildings3D({
-    map,
-    controller,
-    // Cyan outlines at night, a dark ink by day.
-    edgeColor: (theme) => (theme === 'night' ? '#7fd8ff' : '#2b2a33'),
-  });
-}
-```
+`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
+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.
@@ -112,47 +285,21 @@ default:
   dark.
 
 The night use comes from World's `night_use` on each building. In tiles whose buildings do not
-carry it, the renderer finds it in the tile's places (`placesLayer`, `poi` by default): a place
-inside a building, or within a few metres of its facade, gives the building its use.
+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),
 which draws over the buildings so they hide the lamps behind them; both layers share each tile's
 download.
 
-## Colours
-
-Without `color`, buildings take the theme's 3D building colour, the colour Tileflow's buildings
-module compiles for its extrusion, and follow theme changes and blends.
-
-`color(properties, theme)` colours each building from its feature properties for each theme, as a
-CSS colour. The renderer calls it once per building and theme when a tile or the set of themes
-changes, and mixes the colours of the themes either side of a blend's position on the GPU, so a
-moving blend costs nothing per frame:
+## Options
 
-<!-- docs:check -->
-
-```ts
-import {createTileflowBuildings3D, type TileflowBuildings3DMap} from '@tileflow/core/browser';
-
-const tints: Record<string, readonly string[]> = {
-  day: ['#f1d4cd', '#d3e8da', '#f6e0b5', '#e2d5f0', '#cfe3f2'],
-  night: ['#353d41', '#2f3a3d', '#3a3b44', '#33363f', '#2d3540'],
-};
-
-export function tintedCity(map: TileflowBuildings3DMap) {
-  return createTileflowBuildings3D({
-    map,
-    color(properties, theme) {
-      const floors = Math.floor(Number(properties.render_height ?? 5) / 3.2);
-      const palette = tints[theme] ?? tints.day!;
-      return palette[floors % palette.length]!;
-    },
-  });
-}
-```
+The renderer's own options say only how it is delivered: `minzoom` (14.5 by default), `maxTiles`,
+`beforeId` to place the layer before another one, and `transformRequest` to apply the map's request
+rules to the tiles it reads.
 
 ## Cost
 
@@ -164,5 +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.

package/docs/data-is-separate-from-design.md

@@ -295,10 +295,129 @@ opt-in.
 
 The vector palette uses thresholds −11 000, −8 000, −6 000, −4 000, −2 000, −1 000, −500, −200,
 −100, −50, −20, −10, and 0 metres. `bands`, `contours`, and `labels` remain separate controls.
-Until native contour fields are contracted, contours are a visual fallback drawn from band polygon
-edges, not surveyed isolines. The V1 schema exposes optional source-layer names
-`bathymetry_contour`, `seafloor_landform`, `water_name`, and `bathymetry_coverage`, but promises
-fields only for required `bathymetry.min_depth` and `bathymetry.sort_key`.
+Without an optional-layer declaration, contours and depth labels retain the legacy polygon-band
+behavior. `marine` shorthands and existing maps keep that behavior.
+
+### Declare contour and name layers
+
+For a compatible source, `vectorLayers` explicitly declares optional layers. Core never fetches
+TileJSON to detect them and never substitutes polygon edges for declared contour lines. A missing
+declared layer therefore draws no features; validate the selected dataset before rendering.
+`display: 'bands'` or `'hybrid'` loads the vector source.
+
+| Declaration                             | Source layer         | Geometry and fields                                                                                                 |
+| --------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `contours: true`                        | `bathymetry_contour` | Lines with numeric `depth`, negative metres below the source vertical datum. Zero and positive depths are excluded. |
+| `landforms: true` or a range inventory  | `seafloor_landform`  | Named points, lines, or polygons with stable source `id`, provider `class`, and `name`.                             |
+| `waterNames: true` or a range inventory | `water_name`         | Named points, lines, or polygons with the same name contract.                                                       |
+
+Name geometry stays in its source representation. `placement: 'point'` (the default) lets the
+renderer place names inside polygons or on points. Use `placement: 'line'` to label source lines.
+Core creates no substitute point, centroid, or line feature.
+
+Name layers preserve source properties; `id` is a source identifier, with no guarantee of a numeric
+renderer feature ID. Optional `name:<language>` fields retain the source's language assignments.
+`labels({language: 'es'})` selects a nonempty `name:es`, falling back to `name`; `auto` and `local`
+use `name` directly. Core does not infer the language of an unqualified name or invent translations.
+Optional `min_zoom` is inclusive and `max_zoom` exclusive, defaulting to 0 and 24. These nominal
+ranges intersect the symbol style's range. With `true`, MapLibre evaluates feature zoom filters at
+integer zooms: `min_zoom: 7.6` first becomes eligible at zoom 8. For exact fractional boundaries,
+declare an exhaustive range inventory instead:
+
+```ts
+vectorLayers: {
+  contours: true,
+  landforms: {zoomRanges: [{minZoom: 0, maxZoom: 24}]},
+  waterNames: {
+    zoomRanges: [{minZoom: 1, maxZoom: 6.5}, {minZoom: 7.6, maxZoom: 10}],
+  },
+}
+```
+
+Each declared pair becomes a separate symbol layer with fractional renderer bounds and equality
+filters on the source's original range. A `7.6–10` feature appears at 7.6 and disappears at 10.
+Unlisted pairs are omitted. Core never discovers ranges from tiles: validate the source inventory
+against this exhaustive declaration before rendering, and retain that inventory with reproducible
+captures. Numeric pairs must match the source's encoded values exactly.
+
+Each name layer accepts 1–128 unique pairs with `0 <= minZoom < maxZoom <= 24`;
+`tileflowBathymetryNameLayerLimits.maxZoomRanges` exposes the limit. Input order does not affect
+output. Different pairs can overlap in zoom because equality filters keep their feature sets
+disjoint. A style may narrow a pair's visibility; an empty intersection emits no layer.
+Missing or null source bounds default to 0/24. Nonnumeric values use the same numeric-conversion
+fallbacks; numeric strings are converted. Such features draw only if their normalized pair is
+declared. Core preserves the original source properties.
+
+Optional numeric `sort_key` defaults to 0; smaller values enter collision placement first within
+each cohort. Cohorts follow ascending minimum then maximum zoom and sit below ordinary map labels.
+Names use normal collision placement without overlap by default.
+
+This example declares a source whose regional detail supports zoom 14. Its extended ranges are
+explicit design choices, not a promise of worldwide detail:
+
+<!-- docs:check -->
+
+```ts
+import {bathymetry, defineMap, expr, field, fixed, labels, water} from '@tileflow/core';
+import {soundings} from '@tileflow/maps';
+
+export default defineMap({
+  id: 'regional-depth',
+  version: 1,
+  extends: soundings,
+  marine: {
+    bathymetry: bathymetry({
+      url: 'https://tiles.example.test/regional-depth/tiles.json',
+      vectorLayers: {
+        contours: true,
+        landforms: {zoomRanges: [{minZoom: 0, maxZoom: 24}]},
+        waterNames: {zoomRanges: [{minZoom: 7.6, maxZoom: 10}]},
+      },
+      contours: {},
+      labels: {},
+    }),
+    nautical: false,
+  },
+  modules: {
+    labels: labels({language: 'es'}),
+    water: water({
+      bathymetry: {
+        maxZoom: 15,
+        opacity: fixed(0.8, {reason: 'The selected regional source supplies detailed bands'}),
+      },
+      bathymetryContours: {maxZoom: 15},
+      bathymetryLabels: {
+        maxZoom: 15,
+        text: {
+          field: expr.concat(
+            expr.toString(expr.abs(expr.get(field('bathymetryContourDepth')))),
+            ' m',
+          ),
+        },
+      },
+      bathymetryLandforms: {maxZoom: 15},
+      bathymetryWaterNames: {maxZoom: 15},
+    }),
+  },
+});
+```
+
+`water.bathymetryContours` and `water.bathymetryLabels` now consume the declared lines and `depth`;
+labels default to line placement. Band fills still consume `min_depth` and `sort_key`.
+`water.bathymetryLandforms` and `water.bathymetryWaterNames` style the declared names; set
+`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.
+
+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
+resolves to `depth` independently of the primary World schema; `bathymetryMinDepth` keeps its
+legacy band meaning. Raw `expr.get('depth')` is rejected by authoring validation.
+Increasing only `maxZoom` does not remove an opacity curve that fades out earlier. Extend ranges
+and opacity only where the selected source supports the intended detail.
+
+The V1 schema also reserves `bathymetry_coverage`; Core adds no coverage rendering by default.
+Derived contours and names provide geographic context, not certified navigation data.
 
 The DEM enables future client-side sampling and depth profiles, but Core intentionally exposes no
 profile or remote sampling API yet. Rendered relief must not be interpreted as navigation-safe
@@ -318,6 +437,15 @@ explicit because the data contract cannot assume a sprite name. They require pos
 `markings` evidence and reject `crossing=no`; both fields are semantic bindings, so custom schemas
 can remap them without weakening that rule.
 
+Metric road rings scale continuously with the map from zoom 15 through 24, including fractional
+zooms. Their casing is below surface road fills so approaching streets cover the outline at each
+junction. The ring fill stays below bridges and road markings.
+
+Road treatment `widthScale` scales both the stroke and an authored `gapWidth`, keeping hollow
+casings aligned with the carriageway at fractional zoom levels.
+When every dash treatment is continuous (`[1, 0]`), road layers omit the dash pattern so thin
+casings render as solid strokes. Actual construction and tunnel dashes remain patterned.
+
 Datasets may also publish the optional, decorative `canopy` layer: points inside urban parks and
 gardens, at most one per cell of a grid of about 20 m that measured tree canopy covers. Each point
 tells how much room a drawn grove of tree crowns has and how dense the canopy around it is. The
@@ -421,7 +549,11 @@ buildings. Its `activity_score`, `rank`, `min_zoom`, and `confidence` fields con
 warm tint without drawing POI-radius circles. Current building footprints may carry sparse
 `building_tone=commercial|destination|active`; absence means the neutral base building. The three
 values preserve why the warm tone was selected even when a theme maps them to the same color.
-Building visibility is fixed by the layer zoom contract and never by optional semantics. The land
+Buildings may also carry World's `class`, their use in Overture's building subtype values; without
+a tone, the buildings module colours `residential`, `commercial`, public buildings (`civic`,
+`education`, `medical`, `religious` and the like) and works (`industrial`, `agricultural`,
+`service`) with the theme's `residential`, `commercial`, `civic` and `industrial` building colours,
+and every other building with `generic`. Building visibility is fixed by the layer zoom contract and never by optional semantics. The land
 module also exposes
 `medical`, `education`, and `government` independently instead of collapsing their already distinct
 source classes into one civic color.

package/docs/native-artifact-profile.md

@@ -39,6 +39,11 @@ preparing the referenced resources.
 
 The exported `tileflowNativeProfile` targets MapLibre React Native 11.3.10 with Native Android 13.2.0
 and iOS 6.26.0. These are static compatibility targets, not a supported application dependency matrix.
+The application integration uses MapLibre React Native 11.5.0 with Android 13.6.1 and iOS 6.31.0.
+The artifact profile retains its earlier validation targets and build-record engine values, keeping
+prepared artifacts compatible with existing Hosted validators. New application dependencies do not
+expand the accepted style vocabulary.
+
 The wrapper's Style Spec version is 26.2.1. Tileflow retains its existing compiler and parser at
 24.8.5: `native-v1` checks that compiler's vocabulary and the intersection of its recorded Android
 and iOS support. It does not expose every feature of Style Spec 26.2.1 or upgrade the web compiler.

package/docs/native-resource-urls.md

@@ -121,7 +121,7 @@ network request. Do not attach a credential merely because this helper accepted
 
 ## Private parser and source builds
 
-The native entry embeds the low-level parser from `whatwg-url` 15.1.0, `tr46` 6.0.0 (Unicode 17
+The native entry embeds the low-level parser from `whatwg-url` 17.2.0, `tr46` 7.0.0 (Unicode 18
 IDNA processing) and Punycode.js 2.3.1. It exposes no URL class or parser configuration. Package
 consumers only install Core; the published `dist/native.js` has no external runtime imports.
 The parser is a development/build dependency, not an additional runtime package to install.
@@ -136,8 +136,10 @@ policy with its existing host parser; it does not embed the mobile parser in its
 
 From an SDK source checkout, run the ordinary Core build, not a direct source import in a native
 application. `tsup.native.config.ts` builds only the native entry with `platform: 'browser'`,
-`target: 'es2020'`, ESM and no splitting. Its plugin redirects exactly the two relative
-`./encoding` imports in the pinned parser modules to Core's private UTF-8 codec. It rejects an
+`target: 'es2020'`, ESM and no splitting. Its plugin redirects the two relative
+`./encoding` imports and the parser's two `@exodus/bytes` encoding imports to Core's private UTF-8
+codec. Query encoding accepts only UTF-8; the legacy encoding bootstrap has no side effects.
+Exodus and its legacy encoding tables are not embedded. The build rejects an
 unexpected dependency version, an unbound codec import or external runtime imports. It does not
 patch packages on disk, configure a global alias or change another entry's build.