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

package/docs/map-and-terrain-examples.md

@@ -92,9 +92,16 @@ then transition to Mercator between zoom 10 and 12 so detailed streets remain pl
 property, or set it to `'mercator'`, for a consistently flat map.
 
 Terrain keeps the original `'none' | 'hillshade' | '3d'` shorthand. The object form can style every
-MapLibre hillshade paint control, or generate vector contours in the browser from an explicit DEM
-tile template. Contours require `demUrl`, `demMaxZoom`, and zoom-indexed `[minor, index]`
-`thresholds`; the raster `url` remains the separate TileJSON endpoint. Set `mode: 'none'` to compile
+MapLibre hillshade paint control. Raster terrain accepts either a TileJSON `url` or explicit `tiles`
+templates, with optional `tileSize` (256 or 512) and native `minZoom`/`maxZoom` limits. The templates
+must contain `{z}`, `{x}` and `{y}` and use HTTPS (HTTP is allowed for loopback development).
+These source limits control DEM requests independently of `hillshade.minZoom`/`maxZoom` visibility;
+the renderer reuses the highest available native resolution for closer views. Select resolution
+limits supported by the provider and retain its required attribution.
+
+Contours generate vector lines in the browser from their own explicit DEM tile template. They
+require `demUrl`, `demMaxZoom`, and zoom-indexed `[minor, index]` `thresholds`; these are separate
+from the raster source's `url` or `tiles`. Set `mode: 'none'` to compile
 contours without adding a raster source, hillshade, or 3D terrain:
 
 ```ts

package/docs/nautical-marks.md

@@ -0,0 +1,200 @@
+# Nautical marks
+
+The `nautical` module draws navigation marks from a `nautical-v1` vector source: buoys, beacons,
+lighthouses, lights, rocks and other hazards, wrecks, reefs, navigation areas, routes, cables,
+harbours, ports, and a restrained indication of where a provider publishes marks. It is reference
+cartography for general-purpose maps. It is not a nautical chart, and a map that draws it always
+shows a "Not for navigation" notice.
+
+## Enable Nautical on a map
+
+Nautical is opt-in through the map's `marine` option. `'nautical'` adds it alone, `'chart'` adds it
+with Bathymetry, and the object form selects or replaces each member. The official Soundings map
+enables it with its own chart symbols; every other official map draws it with the module's default
+symbology once the map opts in.
+
+<!-- docs:check -->
+
+```ts
+import {defineMap} from '@tileflow/core';
+import {streets} from '@tileflow/maps';
+
+export default defineMap({
+  id: 'harbour-guide',
+  version: 1,
+  extends: streets,
+  marine: 'nautical',
+  view: {center: [-1.3, 50.77], zoom: 12},
+});
+```
+
+`marine` is atomic: declaring it replaces the inherited value. Without a URL, the source is the
+TileJSON at `/tiles/nautical/tiles.json` on the map's API base, with the style source ID
+`tileflow-nautical`. Compiling a map that names this URL does not establish that a hosted Nautical
+source is available to it. To use any schema-compatible source, name its TileJSON or PMTiles
+archive and, when the TileJSON does not carry one, its attribution:
+
+<!-- docs:check -->
+
+```ts
+import {defineMap} from '@tileflow/core';
+import {streets} from '@tileflow/maps';
+
+export default defineMap({
+  id: 'harbour-guide',
+  version: 1,
+  extends: streets,
+  marine: {
+    bathymetry: false,
+    nautical: {
+      url: 'https://tiles.example.com/nautical/tiles.json',
+      attribution: '© Example © OpenStreetMap contributors',
+    },
+  },
+});
+```
+
+The selected TileJSON owns the provider credit. Core never invents a nautical provider or
+attribution, and an explicit `attribution` replaces the one the TileJSON supplies.
+
+## The "Not for navigation" notice
+
+When any layer of the compiled style reads the Nautical source, the style declares a notice in its
+`tileflow:notices` metadata:
+
+```json
+[
+  {
+    "id": "nautical-not-for-navigation",
+    "sources": ["tileflow-nautical"],
+    "text": "Not for navigation"
+  }
+]
+```
+
+React, Vue, Svelte, the development preview, and standalone capture render it as a compact,
+always-visible control beside the attribution, and keep it in step with style replacements. A map
+that does not draw Nautical, including one whose `nautical` module is disabled, declares no notice.
+The notice is separate from the source attribution, so the provider credit stays complete.
+
+A direct MapLibre integration attaches the same control after constructing the map:
+
+```ts
+import maplibregl from 'maplibre-gl';
+import {attachTileflowNotices} from '@tileflow/core/browser';
+
+const map = new maplibregl.Map({
+  container: 'map',
+  style: '/tileflow/styles/harbour-guide/light.json',
+});
+const detach = attachTileflowNotices(map, {position: 'bottom-right'});
+// Call detach() to remove the control early; removing the map also removes it.
+```
+
+`readTileflowNotices(style.metadata)` returns the bounded notices of a style for an application
+that draws its own legend or exports images by other means. Show the notice wherever such a map is
+displayed.
+
+## Source layers and fields
+
+Every feature carries `provider`, `provenance`, `edition`, `coverage`, `licence`, and `min_zoom`,
+the first zoom at which the feature appears. `rank` (1 is the most important feature of its layer)
+and `name` are optional. Colours are S-57 colour names, and multi-valued colours and categories are
+comma-separated in source order, for example `black,yellow`. `tileflowNauticalV1Schema` lists the
+field names, layers, and geometry types.
+
+| Source layer      | Geometry                   | Fields the module reads                                  |
+| ----------------- | -------------------------- | -------------------------------------------------------- |
+| `aid`             | Point                      | `class`, `subclass`, `category`, `color`, `rank`, `name` |
+| `light`           | Point                      | `class` (`major` or `minor`), `color`, `label`, `rank`   |
+| `hazard`          | Point, LineString, Polygon | `class`, `water_level`, `name`                           |
+| `wreck`           | Point, Polygon             | `class`, `name`                                          |
+| `reef`            | Polygon                    | `name`                                                   |
+| `navigation_area` | Point, LineString, Polygon | `class`, `size`, `rank`, `name`                          |
+| `coverage`        | Polygon                    | `families`                                               |
+| `sounding`        | Point                      | `depth`                                                  |
+
+Every layer filters on `min_zoom`, so a compatible source that keeps features in lower-zoom tiles
+still shows each one from its own first zoom. Point groups place a lower `rank` first.
+
+## Semantic groups
+
+Each group is a style option of `nautical(...)`, with the same marker, symbol, area, and line style
+objects as other modules.
+
+| Option            | Draws                                                                           | Default symbology                                         |
+| ----------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| `buoys`           | `aid` buoys, light floats, and light vessels                                    | Circle in the first colour, ringed with the second        |
+| `beacons`         | `aid` beacons and daymarks                                                      | Small circle in the first colour                          |
+| `lighthouses`     | `aid` lighthouses                                                               | Ink circle and name                                       |
+| `aids`            | Other `aid` classes, such as moorings, fog signals, and racons                  | Small hollow circle                                       |
+| `lights`          | `light` points, one per sector                                                  | Flare in the light's first colour and its chart `label`   |
+| `hazards`         | `hazard` points                                                                 | `+` for rocks, `*` for rocks that show; circled obstacles |
+| `hazardAreas`     | `hazard` polygons; the outline also strokes linear hazards                      | Accent wash with a dotted outline                         |
+| `wrecks`          | `wreck` points                                                                  | `Wk`, in the accent colour when dangerous                 |
+| `wreckAreas`      | `wreck` polygons                                                                | Ink wash with a dashed outline                            |
+| `reefs`           | `reef` polygons                                                                 | Sand wash with a dotted outline                           |
+| `navigationAreas` | `navigation_area` polygons                                                      | Dashed outlines; accent for operational areas             |
+| `routes`          | `navigation_area` lines of class `route` and `traffic-separation`               | Dashed line; accent for traffic separation                |
+| `cables`          | `navigation_area` lines of class `cable`, `pipeline`, and their area classes    | Fine dashed accent line                                   |
+| `harbours`        | `navigation_area` points of class `harbour`                                     | Ink circle and name                                       |
+| `ports`           | `navigation_area` points of class `port`                                        | Ink circle and name sized by `size`, from low zooms       |
+| `coverage`        | `coverage` polygons that cover every family                                     | Faint tint at low zooms only                              |
+| `soundings`       | `sounding` points                                                               | Depth figure                                              |
+| `labels`          | Names inside hazard, navigation-area, reef, and wreck polygons; coverage opt-in | Collision-aware text                                      |
+
+Operational areas are restricted, military, anchorage, anchor-berth, dumping-ground, and
+traffic-separation areas. Marks keep their conventional colours in every theme; a white light is
+drawn as a warm yellow so it remains visible on pale water. Ink, halo, and accent come from the
+theme's `hydro.label`, `hydro.water`, and `poi.transport` colours, so a theme can restyle Nautical
+without new options. Override any group like any other module style:
+
+<!-- docs:check -->
+
+```ts
+import {defineMap, fixed, nautical} from '@tileflow/core';
+import {streets} from '@tileflow/maps';
+
+export default defineMap({
+  id: 'harbour-guide',
+  version: 1,
+  extends: streets,
+  marine: 'nautical',
+  modules: {
+    nautical: nautical({
+      buoys: {minZoom: 12},
+      cables: {visible: false},
+      navigationAreas: {
+        fill: {opacity: fixed(0.04, {reason: 'Keep operational areas quiet on the base map'})},
+      },
+      labels: {coverage: {visible: true}},
+    }),
+  },
+});
+```
+
+## Chart symbols from the theme
+
+A theme that declares the image tokens below replaces a point group's circle marker with that icon.
+Buoy variants fall back to `nautical.buoy`. `tileflowNauticalImageRoles` lists the tokens.
+
+| Token                     | Group                                      |
+| ------------------------- | ------------------------------------------ |
+| `nautical.buoy`           | `buoys`                                    |
+| `nautical.buoy.port`      | Lateral buoys of a port-hand category      |
+| `nautical.buoy.starboard` | Lateral buoys of a starboard-hand category |
+| `nautical.buoy.cardinal`  | Cardinal buoys                             |
+| `nautical.beacon`         | `beacons`                                  |
+| `nautical.lighthouse`     | `lighthouses`                              |
+| `nautical.light`          | `lights`                                   |
+| `nautical.aid`            | `aids`                                     |
+| `nautical.wreck`          | `wrecks`                                   |
+| `nautical.harbour`        | `harbours`                                 |
+| `nautical.port`           | `ports`                                    |
+
+Buoys, beacons, other aids, and lights colour their icon with the mark's own colour, so declare
+them as [SDF icons](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/docs/native-icons.md)
+that share one representation within each group. The defaults size icons for the SDF profile,
+whose drawing occupies the central 12 of 24 pixels; set `icon.size` for other artwork. Soundings
+declares these tokens with its own buoy, light, lighthouse, wreck, and harbour symbols and keeps
+beacons as coloured dots.

package/docs/public-api-and-browser-subpath.md

@@ -79,13 +79,16 @@ import {
   attachTileflowAtmosphere,
   attachTileflowFairUseNotice,
   attachTileflowMapLifecycle,
+  attachTileflowNotices,
   createTileflowSessionStarter,
   createTileflowTransformRequest,
   registerTileflowWorldRequestBridge,
 } from '@tileflow/core/browser';
 ```
 
-The browser entry is not re-exported from the root. It is SSR-safe to import, has no MapLibre
+`attachTileflowNotices(map)` renders the notices a compiled style declares, such as Nautical's
+"Not for navigation", as a compact map control; see
+[Nautical marks](nautical-marks.md). The browser entry is not re-exported from the root. It is SSR-safe to import, has no MapLibre
 runtime dependency, and reads no browser global during module evaluation. See the
 [framework browser runtime contract](https://github.com/tileflow/tileflow-sdk/blob/main/docs/contracts/framework-browser-runtime.md) and the
 [cartographic authoring contract](https://github.com/tileflow/tileflow-sdk/blob/main/docs/contracts/cartographic-authoring.md). Exact field

package/docs/street-lights.md

@@ -6,6 +6,9 @@ glowing head. Streets and pavements the data maps as lit, but whose lamps it doe
 soft light along them that claims no lamp's place. As the theme controller's sun darkens the map,
 the lights switch on one by one; they go out as day comes.
 
+Street lights are off by default in the SDK and in Streets. A compiled map must explicitly set
+`roads.streetLights.enabled: true` before the renderer or preview will show lamp glows.
+
 It is a custom WebGL2 layer for MapLibre GL JS, drawn above the map's buildings and below its
 labels. When `createTileflowBuildings3D` raises the buildings, they hide the lamps behind them. It
 needs WebGL2 and the Mercator projection, and shines from zoom 14 by default.
@@ -13,7 +16,8 @@ needs WebGL2 and the Mercator projection, and shines from zoom 14 by default.
 ## Light the streets
 
 This example assumes an existing MapLibre map showing a Tileflow map whose vector source is called
-`tileflow`, as Tileflow's maps call World, and a theme controller for it:
+`tileflow`, as Tileflow's maps call World, with `roads.streetLights.enabled: true` in its map
+definition and a theme controller for it:
 
 <!-- docs:check -->
 
@@ -56,12 +60,12 @@ lit streets, others almost none. Where the data says nothing, the streets stay d
 
 The map describes its street lights in its roads module, next to the other details drawn from
 street furniture, and publishes them with its style for every theme; `stats.declared` tells whether
-it does. Without a description the lights take the defaults below:
+it does. Without an enabled description the renderer stays off and mounts no layer:
 
 <!-- docs:check -->
 
 ```ts
-import {defineMap, refine} from '@tileflow/core';
+import {defineMap, fixed, refine} from '@tileflow/core';
 import {streets} from '@tileflow/maps';
 
 export default defineMap({
@@ -71,7 +75,14 @@ export default defineMap({
   extends: streets,
   modules: {
     // Sodium-orange light, a little brighter, on every street of tiles that map few lamps.
-    roads: refine({streetLights: {color: '#ffb35c', intensity: 1.3, estimate: 'streets'}}),
+    roads: refine({
+      streetLights: {
+        enabled: true,
+        color: fixed('#ffb35c', {reason: 'Constant sodium-lamp color.'}),
+        intensity: 1.3,
+        estimate: 'streets',
+      },
+    }),
   },
 });
 ```
@@ -89,11 +100,16 @@ street rather than as lamps that may not stand there.
 
 `color` is the light of the lamps whose data gives no colour, a warm white by default, and
 `intensity` scales the light from 0 to 2 (1 by default); both may be theme tokens and mix during a
-blend. `streetLights: {enabled: false}` gives the map none.
+blend. These settings apply only after `enabled: true`; `streetLights: {enabled: false}` gives
+the map none.
 
 ## Options
 
-The layer's own options say only how it is delivered: `minzoom` (14 by default) and `maxTiles` (25
+The layer follows the compiled map by default. `createTileflowStreetLights({map, controller,
+enabled: true})` explicitly enables the fallback design for a style without street-light metadata;
+`enabled: false` keeps the renderer off even when the map declares lights.
+
+The delivery options are `minzoom` (14 by default) and `maxTiles` (25
 by default, at most 64) bound where and how far the lights shine, `beforeId` places the layer before
 another one, and `transformRequest` applies the map's request rules to the tiles it reads.
 

package/docs/sun-and-light.md

@@ -15,8 +15,8 @@ application's own WebGL layers to draw, from the values `getSun()` returns.
 ## Describe a theme's sun
 
 Set `lighting.sun` and `lighting.ambient` in the theme. Every value is optional; unset values take
-the defaults in `tileflowDefaultSunPreset` (azimuth 210°, altitude 60°, white light at 0.5, full
-shadows, a white sky at 0.5):
+the defaults in `tileflowDefaultSunPreset` (azimuth 210°, altitude 60°, white light at 0.2, full
+shadow strength, a white sky at 0.8 for soft daylight shadows):
 
 <!-- docs:check -->
 
@@ -43,6 +43,46 @@ others are inherited. The compiled style carries the resolved sun in its metadat
 direction in `lighting.position` no longer apply to a theme with a sun. A theme without `sun` or
 `ambient` compiles exactly as before.
 
+## Replace inherited lighting
+
+`defineTheme(base, definition)` normally merges lighting field by field. An empty `lighting`,
+`sun`, or `ambient` object therefore preserves inherited values. Use the existing `reset()`
+operation to remove a preset explicitly while keeping the base theme's palette and typography:
+
+<!-- docs:check -->
+
+```ts
+import {defineTheme, reset} from '@tileflow/core';
+import {streetsThemes} from '@tileflow/maps';
+
+export const studio = defineTheme(streetsThemes.light, {
+  id: 'studio',
+  version: 1,
+  colorScheme: 'light',
+  lighting: {
+    sun: reset(),
+    ambient: reset(),
+    anchor: 'viewport',
+    position: [1.15, 180, 40],
+    color: '#FFFFFF',
+    intensity: 0.15,
+  },
+});
+```
+
+Removing both presets lets the native extrusion light use the authored `anchor` and `position`.
+Resetting only `sun` keeps an inherited ambient preset, and resetting only `ambient` keeps the sun;
+the missing counterpart then uses the SDK defaults. `lighting: reset()` clears all inherited
+lighting properties. A direct property such as `position`, `color`, or `intensity` can also be
+reset. The result is a complete theme with those properties absent; it contains no reset nodes.
+To replace a whole sun or ambient object, first derive a theme that resets that object, then derive
+the replacement values from the cleared theme.
+
+Removing a preset does not turn off the renderer's lighting, cast shadows, or ambient occlusion.
+The SDK's 3D scene uses its fallback light when no preset is published. For a graphic building
+style, choose the building module's `lighting: 'style'`, `shadows: false`, and `occlusion: false`
+explicitly. A single static theme needs no time-of-day family or running clock.
+
 ## Read the sun in an application
 
 `themeController.getSun()` returns the sun the map shows:

package/docs/themes-and-module-styles.md

@@ -15,6 +15,61 @@ same token keys, so changing a theme can never change map structure or silently
 role. `defineTheme(base, definition)` is an authoring convenience that returns a fully materialized
 document; it does not leave an inheritance edge in the resolved config.
 
+## Start with one appearance
+
+A map can have one appearance for its entire lifetime. Neither `systemThemes` nor `timeOfDay` is
+required. This complete theme supplies the twelve base color roles the semantic compiler needs;
+copy it and change its colors to start an independent design without inheriting an official map:
+
+<!-- docs:check -->
+
+```ts
+import {defineTheme} from '@tileflow/core';
+
+export const paper = defineTheme({
+  id: 'paper',
+  version: 1,
+  colorScheme: 'light',
+  tokens: {
+    color: {
+      'surface.background': '#F6F7F3',
+      'surface.land': '#F1F3ED',
+      'surface.water': '#A9D3F5',
+      'surface.park': '#CDE8B5',
+      'surface.building': '#E6E3DA',
+      'roads.default': '#FFFFFF',
+      'roads.major': '#F4C95D',
+      'roads.casing': '#D9DEE2',
+      'boundaries.default': '#C9D1D9',
+      'labels.primary': '#3C4043',
+      'labels.muted': '#727B84',
+      'labels.halo': '#FFFFFF',
+    },
+  },
+});
+```
+
+An existing map definition can select this appearance with `themes: {paper}` and
+`defaultTheme: 'paper'`. Supply that map's data and font assets separately; the default typography
+uses `Noto Sans Regular`. A theme without these base roles is a valid appearance document but cannot
+compile a semantic map. Colors above are an editable starting point, including for monochrome,
+historical, dark-only, or imagined worlds; `colorScheme` describes the appearance for consumers and
+does not generate a palette or choose a time of day.
+
+The compiler derives more specific roles when they are absent. For example, primary and motorway
+roads initially use `roads.major`; declaring `roads.motorway` replaces only that derived color.
+Land-use fills, road casings, and label colors have their own semantic roles, so an explicit role
+always wins over its fallback. Use `color.mix()` and `token.color()` in a theme when the relationship
+itself should be authored and inspectable. Derivations resolve during compilation, without a clock
+or a per-frame palette calculation.
+
+Add named appearances when the map needs them. A day/night pair does not need dawn or dusk, and a
+theme named `paper` or `fantasy` does not need a temporal family. Declare `timeOfDay` only when the
+application should offer those artistic moments; see
+[time-of-day selection](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/theme-transitions-and-blends.md#time-of-day).
+
+## Compose and replace appearance values
+
 Some optional tokens are for the application rather than the map's own layers. Route inks
 (`route.line`, `route.casing`, `route.core`, `route.glow`, `route.alternative`,
 `route.glow.opacity` and `route.core.opacity`) set how an application draws its routes; a theme
@@ -83,6 +138,17 @@ deterministic OKLCH `color.mix()` keep derived palette logic inspectable. Unknow
 cross-category refs, token-schema drift, and unresolved visual nodes fail before Style JSON is
 emitted.
 
+Theme lighting also supports explicit removal during `defineTheme` composition. Use
+`lighting: reset()` to remove the entire inherited lighting configuration, or
+`lighting: {sun: reset(), ambient: reset()}` to remove those presets while retaining other light
+properties. The same operation can remove a direct property such as `position` or `color`.
+Omitting a property, or supplying an empty object, continues to inherit it. Reset operations are
+materialized immediately and never enter the resolved theme or Style JSON. Removing a lighting
+preset restores the renderer's fallback; it does not disable 3D shadows or occlusion. Those remain
+explicit building settings. See
+[sun and light](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/sun-and-light.md#replace-inherited-lighting)
+for a complete example.
+
 There is no physical-layer override for the Tileflow basemap or separate official-map authoring
 surface. Basemap behavior belongs to a typed control or owner-local render stack. Every
 official and application map therefore follows the same schema, inheritance rules, diagnostics,

package/docs/trees-3d.md

@@ -3,7 +3,7 @@
 `createTileflowTrees3D` stands the trees of a Tileflow map's vector tiles round the camera as 3D
 trees, lit by the theme controller's sun. Each tree takes the form and the size its data gives:
 palms, conifers, columns and three broadleaf forms, at their mapped height and crown where the data
-has them. Trees cast shadows on the ground and, with `createTileflowBuildings3D`, on the buildings,
+has them. The data's hedges stand beside them as clipped green walls. Trees cast shadows on the ground and, with `createTileflowBuildings3D`, on the buildings,
 and take the buildings' shadows; nearer buildings hide them.
 
 The map describes how its trees look; the renderer only stands them. A map that declares
@@ -107,7 +107,7 @@ sunk or the layer leaves the map.
 
 `stats.declared` tells whether the map's style describes 3D trees. When it is false the layer draws
 nothing: declare `vegetation({mode: '3d'})` in the map. `stats` also counts the tiles, the trees
-placed and the trees drawn in the last frame.
+placed, the pieces of hedge placed and the trees drawn in the last frame.
 
 ## What the trees come from
 
@@ -120,6 +120,10 @@ The renderer reads the source's z15 tiles round the camera:
 - World's `canopy` layer, where the data has it: decorative points in urban parks and gardens, each
   standing one to three trees by its canopy cover, inside the room it leaves before a path, a
   building or the park's edge. They stand for measured canopy, not for mapped trees.
+- World's `traffic_control` layer: its hedges (`subclass` `hedge`), the lines OpenStreetMap maps and
+  the hedges it maps as areas. A hedge stands as pieces 1.2 metres apart along each line and round
+  each area, 0.8 metres thick, at its `height` or 1.3 metres, a metre higher where `hedge` says
+  `hedge_bank`. The style still draws the hedge flat underneath, and fences and walls stay flat.
 
 | Form       | From the data                                                                |
 | ---------- | ---------------------------------------------------------------------------- |
@@ -139,8 +143,12 @@ tile's buffer belong to the neighbouring tile, so no tree stands twice.
 
 Colours come from the theme: `vegetation.tree.bark`, `vegetation.tree.broadleaf.a` to `.d`,
 `vegetation.tree.conifer.a` to `.c` and `vegetation.tree.palm.a` to `.c`, sunlit, from darkest to
-lightest. A crown facing a sunlit sky takes its colour; shade takes the sky's light, as on 3D
-buildings. The vegetation module's `threeDimensional` options refine them for one map:
+lightest. Hedges take `hedgeColors`, the two darkest broadleaf colours unless the map gives its own;
+Streets gives its flat hedge's colours, so a hedge keeps its colour as it rises. `hedges: false`
+leaves hedges flat. A crown facing a sunlit sky takes its colour; shade takes the sky's light, as on 3D
+buildings. At night a neutral lift keeps crown tops visible; grey materials stay grey under neutral
+lighting, while coloured scene lighting can tint them. The vegetation module's `threeDimensional`
+options refine them for one map:
 
 <!-- docs:check -->
 
@@ -239,16 +247,20 @@ the same name; omitting `models` inherits them, and `[]` declares none.
 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, trees read the compiled style's sun and light direction, falling back to
+SDK daylight, just as 3D buildings do. This cached light refreshes when the style changes.
 Leaves take light round their edges and glow a little against a low sun; the underside and the
 inside of a crown stay darker.
 
 Trees and 3D buildings on one map share one shadow map: trees cast shadows on the ground and on the
 buildings, and stand in the buildings' shade. The flat map darkens under both. Without 3D buildings
-the trees darken the map themselves.
+the trees darken the map themselves. The depth pass uses the same visible tree ranks, near/far
+models and distance fade as the colour pass, so hidden trees do not leave full shadows behind.
+Shadow direction stops lowering at 15° above the horizon; the actual scene light keeps its angle.
 
 ## Options
 
-`minzoom` (15 by default) and `maxTiles` (25 by default, at most 64) bound where and how far trees
+`minzoom` (15 by default, fading to full coverage at 15.25 like buildings) and `maxTiles` (25 by default, at most 64) bound where and how far trees
 stand; trees thin out and fade with distance from the map's centre, and near trees take more detail
 than far ones. `canopySource` names a vector source with canopy points when they are not in the
 map's World source. `beforeId` places the layer before another one; `transformRequest` applies the
@@ -258,9 +270,10 @@ tile's download.
 ## Cost
 
 A near tree has 60 to 120 triangles and a far one about 20, and each form is one instanced draw per
-tile. The shadow map is drawn again only when the sun, the trees on screen or their size change, not
-when the camera moves. Over the Champ de Mars in Paris, where OpenStreetMap maps every tree, about
-13,000 trees stand in a pitched view at zoom 16.6.
+tile. The shared shadow map concentrates resolution on the view when its public camera methods
+provide a safe planar fit. It is drawn again when that focused area, the light, visible tree
+selection, fading or geometry changes. Unchanged views reuse it. Over the Champ de Mars in Paris,
+where OpenStreetMap maps every tree, about 13,000 trees stand in a pitched view at zoom 16.6.
 
 ## Limits
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/core",
-  "version": "0.1.0-alpha.35",
+  "version": "0.1.0-alpha.37",
   "license": "Apache-2.0",
   "description": "Typed Tileflow config and MapLibre style compiler.",
   "type": "module",
@@ -90,7 +90,7 @@
     "whatwg-url": "17.2.0"
   },
   "scripts": {
-    "build": "tsup --config tsup.build.config.ts && tsup --config tsup.native-profile.config.ts && tsup src/browser.ts --format esm --dts --no-splitting --platform browser && tsup --config tsup.native.config.ts && cp ../../docs/modules-api-reference.json dist/config-reference.json",
+    "build": "tsup --config tsup.build.config.ts && tsup --config tsup.native-profile.config.ts && tsup --config tsup.browser.config.ts && tsup --config tsup.native.config.ts && cp ../../docs/modules-api-reference.json dist/config-reference.json",
     "reference:check": "tsx scripts/generate-config-reference.ts --check",
     "reference:generate": "tsx scripts/generate-config-reference.ts --write",
     "verify": "pnpm run build && tsx --test test/*.test.ts",