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

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

@@ -16,9 +16,9 @@ inside a named `maplibreOverlay()` bound to a named Team source.
 
 Advanced cartography remains in the same public language: `withRenderStack()`, `renderPass()`, and
 `refineRenderTarget()` address owner-local semantic targets without exposing physical layer IDs,
-sources, source layers, raw filters, or before/after anchors. Typed `field()` references and
-`expr.*` builders stay semantic until the compiler's single lowering boundary. There is no recipe
-subpath or alternate compiler integration API.
+sources, source layers, raw filters, or physical before/after layer anchors. Typed `field()`
+references and `expr.*` builders stay semantic until the compiler's single lowering boundary. There
+is no recipe subpath or alternate compiler integration API.
 
 `mapRevisionSha256` hashes only resolved cartography: the effective design after `extends`, the
 semantic language, compiler-owned effective contributions, and exact source icon/font identities.

package/docs/route-drawing.md

@@ -0,0 +1,191 @@
+# Route drawing
+
+An application that draws a route on a Tileflow map can take the route's colours from the theme and
+draw the line on with a moving head. Themes set route inks; the theme controller returns them for
+the theme on screen; `createTileflowLineProgress` animates a group of line layers along their
+length; `createTileflowGroundLayers` keeps them on the ground, under the map's 3D buildings.
+
+## Set route inks in a theme
+
+Route inks are optional theme tokens. A theme that sets none uses defaults for its colour scheme:
+a blue line on a dark edge for light themes, a lighter blue with a glow and a bright core for dark
+themes.
+
+| Token                | Kind   | Use                                                   |
+| -------------------- | ------ | ----------------------------------------------------- |
+| `route.line`         | colour | The chosen route.                                     |
+| `route.casing`       | colour | The edge each side of the line, apart from the roads. |
+| `route.core`         | colour | A thin line along the middle.                         |
+| `route.glow`         | colour | A soft halo around the route.                         |
+| `route.alternative`  | colour | Other routes offered beside the chosen one.           |
+| `route.glow.opacity` | number | The halo's opacity, from 0 (none) to 1.               |
+| `route.core.opacity` | number | The core's opacity, from 0 (none) to 1.               |
+
+Every theme of a map carries the same tokens, so a map that sets route inks sets them in each of
+its themes:
+
+<!-- docs:check -->
+
+```ts
+import {defineTheme, type TileflowTheme} from '@tileflow/core';
+
+export function withNeonRoute(base: TileflowTheme, id: string): TileflowTheme {
+  return defineTheme(base, {
+    id,
+    version: 1,
+    colorScheme: base.colorScheme,
+    tokens: {
+      color: {
+        'route.line': '#ff4fae',
+        'route.casing': '#0b0f12',
+        'route.core': '#ffe0f0',
+        'route.glow': '#ff4fae',
+      },
+      number: {'route.glow.opacity': 0.55, 'route.core.opacity': 0.9},
+    },
+  });
+}
+```
+
+The compiler publishes the resolved inks in the style's `tileflow:route` metadata.
+`readTileflowRouteInks(style.metadata)` reads them from a style document;
+`tileflowStyleRouteInks(style)` also falls back on the defaults for a style compiled without them.
+
+## Draw a route in the theme's inks
+
+The theme controller's `getRouteInks()` returns the inks of the theme on screen. During a blend it
+mixes them between the neighbouring themes at the blend's position, in the same colour space as
+the map's own colours. Read them again after `setTheme` or `setBlend`.
+
+`createTileflowLineProgress(map, {layers})` owns the `line-gradient` and `line-opacity` of a group of
+line layers. Their source must be GeoJSON with `lineMetrics: true`. The controller shows the line
+from `start` to `end` (shares of its length), a highlight at the head while the line is being drawn,
+and an optional light at `light`. It writes only what changed, paints a layer again when a style
+change re-creates it, and skips layers that are not on the map.
+
+This example assumes an existing MapLibre map named `map` whose style already holds four line
+layers over a GeoJSON source with `lineMetrics: true`:
+
+<!-- docs:check -->
+
+```ts
+import {
+  createTileflowLineProgress,
+  type TileflowLineProgressMap,
+  type TileflowRouteInks,
+} from '@tileflow/core/browser';
+
+const layers = (inks: TileflowRouteInks) => [
+  {id: 'route-glow', color: inks.glow, highlight: '#ffffff', opacity: inks.glowOpacity},
+  {id: 'route-casing', color: inks.casing},
+  {id: 'route-line', color: inks.line, highlight: inks.core},
+  {id: 'route-core', color: inks.core, highlight: '#ffffff', opacity: inks.coreOpacity},
+];
+
+export async function drawRoute(
+  map: TileflowLineProgressMap,
+  inks: TileflowRouteInks,
+  lengthInMetres: number,
+) {
+  const route = createTileflowLineProgress(map, {
+    layers: layers(inks),
+    // A 90 m highlight, whatever the route's length.
+    headLength: Math.min(0.2, 90 / lengthInMetres),
+    initial: {end: 0},
+  });
+  await route.animate({to: {end: 1}, duration: 2500});
+  // A light runs along the drawn route.
+  await route.animate({to: {light: 1}, duration: 1500});
+  route.set({light: undefined});
+  return {
+    recolour: (next: TileflowRouteInks) => route.configure({layers: layers(next)}),
+    fadeOut: () => route.animate({to: {opacity: 0}, duration: 400}),
+    dispose: () => route.dispose(),
+  };
+}
+```
+
+`animate` resolves `true` when the line gets where it was sent, and `false` when `set`, another
+animation, or `dispose` stops it first; the line stays where it was stopped. A browser preference
+for reduced motion shows the target at once. `tileflowLineProgressGradient(state, options)` returns
+the same gradient for a single state, for styles built ahead of time.
+
+## Keep a route under 3D buildings
+
+MapLibre draws a 2D layer that comes after a 3D layer, such as extruded buildings or a custom layer
+drawn in 3D, without testing depth. A route added under the labels therefore crosses in front of
+the buildings. A route that lies on the ground goes before the first 3D layer: every building then
+hides it exactly where it stands in front of it.
+
+`tileflowGroundBeforeId(map)` returns that layer: the first 3D layer above the roads, or the start
+of the vegetation when the buildings are flat, so a ground layer still covers the roads and the
+flat buildings. Pass it as `beforeId` to `map.addLayer` for a single layer.
+
+`createTileflowGroundLayers(map, {layers, occludedOpacity})` keeps a group of layers there, bottom
+to top as given:
+
+- It adds the layers, or moves those already on the map. A layer whose source is not on the map yet
+  is added when the source is.
+- After a style change, it brings back the layers the change dropped, with the paint and layout
+  last written through the group.
+- When a 3D layer lands above the group, such as a custom layer added later, the group moves under
+  it.
+- `occludedOpacity` lets a line show through 3D content: by layer id, how much of the line shows
+  where buildings hide it, from 0 (nothing, the default) to 1. The group draws a copy of the line
+  over the 3D content at the line's opacity times that share, as a navigation app shows a route
+  through buildings. The copy lies over the group's other layers too, so where the line shows, it
+  tints the layers drawn above the line slightly; a line at the top of the group shows no change.
+  Only line layers whose `line-opacity` is a number can show through.
+
+Paint the group's layers through the group, so the copies follow them. A helper that paints layers
+takes the group in place of the map:
+
+<!-- docs:check -->
+
+```ts
+import {
+  createTileflowGroundLayers,
+  createTileflowLineProgress,
+  type TileflowGroundLayersMap,
+  type TileflowRouteInks,
+} from '@tileflow/core/browser';
+
+export function addRoute(map: TileflowGroundLayersMap, inks: TileflowRouteInks) {
+  // The map already holds a GeoJSON source named 'route' with `lineMetrics: true`.
+  const line = (id: string, width: number) => ({
+    id,
+    type: 'line',
+    source: 'route',
+    layout: {'line-cap': 'round', 'line-join': 'round'},
+    paint: {'line-width': width},
+  });
+  const ground = createTileflowGroundLayers(map, {
+    layers: [line('route-casing', 12), line('route-line', 8), line('route-core', 2)],
+    occludedOpacity: {'route-line': 0.35},
+  });
+  const route = createTileflowLineProgress(ground, {
+    layers: [
+      {id: 'route-casing', color: inks.casing},
+      {id: 'route-line', color: inks.line, highlight: inks.core},
+      {id: 'route-core', color: inks.core, opacity: inks.coreOpacity},
+    ],
+    initial: {end: 0},
+  });
+  return {
+    draw: () => route.animate({to: {end: 1}, duration: 2500}),
+    remove: () => {
+      route.dispose();
+      ground.dispose();
+    },
+  };
+}
+```
+
+`dispose` takes the group's layers and copies off the map. The copies keep the layer's id with
+`:occluded` after it.
+
+## Cost
+
+Each frame of an animation writes one `line-gradient` per layer, and MapLibre rebuilds that layer's
+gradient texture. A route of a few layers costs little; avoid animating dozens of long lines at
+once.

package/docs/street-lights.md

@@ -0,0 +1,107 @@
+# Street lights
+
+`createTileflowStreetLights` lights a Tileflow map's streets at night from its own vector tiles. The
+lamps the map's data holds shine where they stand, each with a pool of light on the ground and a
+glowing head. Streets and pavements the data maps as lit, but whose lamps it does not hold, take a
+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.
+
+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.
+
+## 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:
+
+<!-- docs:check -->
+
+```ts
+import {
+  createTileflowStreetLights,
+  type TileflowStreetLightsMap,
+  type TileflowThemeController,
+} from '@tileflow/core/browser';
+
+export function lightTheStreets(map: TileflowStreetLightsMap, controller: TileflowThemeController) {
+  // The lights switch on as the theme's or the application's sun darkens the map.
+  return createTileflowStreetLights({map, controller});
+}
+```
+
+The lights follow `controller.getSun()`: they switch on as its `brightness` falls through dusk, each
+lamp at its own moment, and are all on at night. A theme whose night has no `lighting.sun` keeps
+the default daylight sun, so its lights stay off; see
+[sun and light](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/sun-and-light.md).
+`on` reports how far they have switched on, from 0 to 1, `stats` the lamps on screen, and
+`dispose()` takes the layer off the map.
+
+## What the light comes from
+
+The layer reads the source's z15 tiles round the camera, the zoom at which World carries its street
+detail:
+
+- Lamps from World's `street_furniture` points whose `subclass` is `street_lamp`. Where the data
+  gives them, a lamp's `height`, `lamp_mount`, `light_count`, `lamp_type` and `light_colour` set how
+  high it stands, how far its light reaches and its colour: sodium lamps shine orange, LED and
+  metal-halide lamps white. Other lamps take the map's light colour.
+- Streets in World's `transportation` layer, and pavements in its `sidewalk` layer, that the data
+  maps as lit (`lit`). A street mapped as unlit never takes light.
+
+How much of this a city's data holds varies widely: some map most of their lamps or most of their
+lit streets, others almost none. Where the data says nothing, the streets stay dark.
+
+## Design the lights in the map
+
+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:
+
+<!-- docs:check -->
+
+```ts
+import {defineMap, refine} from '@tileflow/core';
+import {streets} from '@tileflow/maps';
+
+export default defineMap({
+  id: 'night-city',
+  name: 'Night city',
+  version: 1,
+  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'}}),
+  },
+});
+```
+
+`estimate` chooses where the layer adds light the data does not map as lamps:
+
+- `lit` (the default): along the streets and pavements mapped as lit.
+- `streets`: also along streets the data says nothing about, in tiles where the data maps few
+  lamps. This invents light, as night windows do, for maps that want every street lit; a tile whose
+  data maps its lamps keeps to them.
+- `none`: only mapped lamps shine.
+
+Estimated light keeps to the middle of its street and shows no lamp head, so it reads as a lit
+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.
+
+## Options
+
+The layer's own options say only how it is delivered: `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.
+
+Layers that read the same source share each tile's download, so the street lights and the 3D
+buildings fetch a tile once between them.
+
+## Limits
+
+- Mercator only; the layer draws nothing below its `minzoom`.
+- The light falls on the ground; walls the lamps face are not lit by them.
+- No terrain: lamps stand on flat ground.

package/docs/sun-and-light.md

@@ -0,0 +1,125 @@
+# Sun and light
+
+A theme can describe its sun and the light from its sky, as a light preset for that theme: a high
+sun in white light for a day theme, a low amber sun in the west for an evening theme, a cold moon
+with faint shadows for a night theme. In a browser, the theme controller returns the sun the map
+shows, mixed between neighbouring themes during a blend, so an application's own 3D layers can light
+their models and cast their shadows from it. An application can also place the sun itself, by
+direction or by the real position of the sun for a date and place.
+
+MapLibre lights its `fill-extrusion` layers with one directional light and casts no shadows. When a
+theme describes a sun, the map's light is anchored to the map and points from the sun, so Tileflow's
+3D buildings are shaded from where it stands. Shadows, ambient occlusion and lit windows are for the
+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):
+
+<!-- docs:check -->
+
+```ts
+import {defineTheme} from '@tileflow/core';
+import {streetsThemes} from '@tileflow/maps';
+
+export const evening = defineTheme(streetsThemes.dark, {
+  id: 'city-evening',
+  version: 1,
+  colorScheme: 'dark',
+  lighting: {
+    // Degrees clockwise from north, and above the horizon.
+    sun: {azimuth: 285, altitude: 9, color: '#ff9a50', intensity: 1, shadowIntensity: 0.9},
+    ambient: {color: '#5a4290', intensity: 0.3},
+  },
+});
+```
+
+`intensity` values run from 0 to 1. `shadowIntensity` says how dark the shadows the sun casts fall,
+from 0 (none) to 1. A theme derived from another changes single values of its sun and sky light; the
+others are inherited. The compiled style carries the resolved sun in its metadata
+(`tileflow:sun`) and a map-anchored `light` that points from it; MapLibre's `anchor` and the
+direction in `lighting.position` no longer apply to a theme with a sun. A theme without `sun` or
+`ambient` compiles exactly as before.
+
+## Read the sun in an application
+
+`themeController.getSun()` returns the sun the map shows:
+
+- `azimuth` and `altitude`, in degrees, and `direction`, a unit vector towards the sun with x east,
+  y north and z up.
+- `color` and `rgb` (sRGB channels from 0 to 1) of the direct light, and its `intensity`, which fades
+  to 0 over the sun's last degrees above the horizon: a sun below it lights nothing.
+- `ambient`, the light from the sky, with its own `color`, `rgb` and `intensity`.
+- `shadowIntensity`, how dark the sun's shadows fall.
+- `brightness`, how bright flat, open ground is under this light, from 0 to 1: the sky's light plus
+  the sun's at its height, each weighted by its colour's luminance. Use it to switch lamps or windows
+  on as a scene darkens, whatever theme or sun lights it.
+- `source`: `theme`, `direction`, or `date`.
+
+During a blend the sun is mixed between the neighbouring themes' suns: the azimuth turns the short
+way round, colours mix in OKLab as the map's colours do, and numbers mix linearly. Read it when a
+custom layer draws; the map redraws whenever the sun changes.
+
+## Place the sun
+
+`setSun` places the sun by direction, or by the real sun of a date over a place given as
+`[longitude, latitude]`, the map's centre when it is left out. The themes keep the sun's colours,
+strengths and shadow strength; only its direction changes. `setSun(undefined)` returns it to the
+themes. This example assumes an existing MapLibre map and a controller for it:
+
+<!-- docs:check -->
+
+```ts
+import type {TileflowThemeController} from '@tileflow/core/browser';
+
+export function followTheRealSun(controller: TileflowThemeController) {
+  // Where the sun stands over Miami Beach now; a later call moves it on.
+  void controller.setSun({date: Date.now(), location: [-80.13, 25.79]});
+}
+
+export function lowWesternSun(controller: TileflowThemeController) {
+  // Turns the short way round to the west over a second.
+  return controller.setSun({azimuth: 270, altitude: 8}, {transition: {duration: 1000}});
+}
+```
+
+A request that follows an animation, such as a clock that moves every frame, passes no transition.
+A request with a transition supersedes one still in progress, which resolves with
+`status: 'superseded'`; a browser preference for reduced motion changes at once.
+
+`tileflowSunPosition(date, [longitude, latitude])` returns the sun's azimuth and apparent altitude,
+with atmospheric refraction, from NOAA's solar equations (accurate to about a hundredth of a degree
+for years 1800 to 2200). It runs anywhere, without a map:
+
+<!-- docs:check -->
+
+```ts
+import {tileflowSunPosition} from '@tileflow/core/browser';
+
+// Solar noon in Miami at the June solstice, 17:22 UTC: the sun stands about 87.7° high, due south.
+export const noon = tileflowSunPosition(Date.UTC(2026, 5, 21, 17, 22), [-80.19, 25.77]);
+```
+
+## Light a custom layer
+
+For a custom WebGL layer that draws 3D content, light each surface with the sky's light, plus the
+sun's where the surface faces it and nothing stands in the way:
+
+    light = ambient.rgb × ambient.intensity + rgb × intensity × max(normal · direction, 0) × (1 − shadowIntensity × shadowed)
+
+Convert the colours to linear light before adding them and back to sRGB after. MapLibre's own 2D
+layers take no shadows, so a layer that casts shadows on the ground darkens the map it is drawn over:
+draw the ground under the scene, after the scene's own geometry, with multiplying blending and a
+depth test against it.
+
+## Limits
+
+- MapLibre shades extrusions with its one light; it has no shadow maps, ambient occlusion or
+  emissive light. The sun gives custom layers what they need to draw them.
+- Themes interpolate the sun linearly between presets; a request by date follows the real sun, not
+  the themes' presets.
+- Style expressions cannot read the sun yet. An application that wants a theme to react to it sets a
+  [style state](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/style-states.md)
+  from `getSun().brightness`.

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

@@ -15,6 +15,13 @@ 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.
 
+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
+without them uses its colour scheme's defaults. The compiler publishes them in the style's metadata
+and the theme controller returns them; see
+[route drawing](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/route-drawing.md).
+
 The key in the `themes` record is its concrete runtime selector and output-path segment. The
 theme's own `id` and `version` are its editorial identity and build provenance, so they need not
 equal that key. Concrete keys may be names such as `day` and `night`; every `systemThemes.light` or

package/docs/trees-3d.md

@@ -0,0 +1,211 @@
+# 3D trees
+
+`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,
+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
+`vegetation({mode: '3d'})`, as Streets does, publishes its tree colours, scales and forms in the
+style it compiles, for every theme, and the renderer follows theme changes and blends.
+
+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, and the trees stand from zoom 15 by default.
+Elsewhere (Capture, Static Maps, Native, or a browser without WebGL2) the map draws the vegetation
+module's flat trees.
+
+## Stand the trees
+
+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:
+
+<!-- docs:check -->
+
+```ts
+import {
+  createTileflowTrees3D,
+  type TileflowThemeController,
+  type TileflowTrees3DMap,
+} from '@tileflow/core/browser';
+
+export function standTheTrees(map: TileflowTrees3DMap, controller: TileflowThemeController) {
+  const trees = createTileflowTrees3D({map, controller});
+  // The trees grow out of the ground over a second.
+  void trees.show({transition: {duration: 1000}});
+  return trees;
+}
+```
+
+`show()` grows the trees, `hide()` sinks them back into the ground, and `grow(scale)` eases them to
+a share of their size, from 0 to 1. Each returns a promise that resolves once the motion ends; a
+newer call takes over from where the trees stand. A browser preference for reduced motion changes at
+once. `dispose()` takes the layer off the map.
+
+While they stand, the 3D trees stand in for the map's flat trees: the layers the vegetation module
+draws them with are hidden when the trees are shown, and come back as they were once the trees have
+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.
+
+## What the trees come from
+
+The renderer reads the source's z15 tiles round the camera:
+
+- World's `tree` layer: the trees OpenStreetMap maps one by one, as points, and its rows of trees,
+  as lines, along which a tree stands every 8 metres. A tree's `leaf_type`, `genus`, `species` and
+  `taxon` choose its form; its `height` and `diameter_crown` its size, and a trunk's
+  `circumference` sizes a tree with neither. A row's attributes apply to each of its trees.
+- 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.
+
+| Form       | From the data                                                                |
+| ---------- | ---------------------------------------------------------------------------- |
+| `palm`     | `leaf_type` `palm`, `taxon` `Arecaceae`, or a palm genus such as `Roystonea` |
+| `columnar` | the cypress genera `Cupressus`, `Calocedrus` and `Thuja`                     |
+| `conifer`  | `leaf_type` `needleleaved`, or a conifer genus such as `Pinus` or `Cedrus`   |
+| `open`     | spreading genera such as `Quercus`, `Olea`, `Ficus` or `Jacaranda`           |
+| `tall`     | upright genera such as `Platanus`, `Populus`, `Ulmus` or `Ginkgo`            |
+| `round`    | rounded genera such as `Acer`, `Tilia`, `Aesculus` or `Prunus`               |
+
+A tree whose data gives no form, and every canopy tree, takes one of the three broadleaf forms; a
+tree the data calls broadleaved keeps to them. Each tree's form, size, turn and shade come from a
+stable hash of where it stands, so it looks the same at every zoom and on every device. Points in a
+tile's buffer belong to the neighbouring tile, so no tree stands twice.
+
+## Design the trees in the map
+
+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:
+
+<!-- docs:check -->
+
+```ts
+import {defineMap, token, vegetation} from '@tileflow/core';
+import {streets} from '@tileflow/maps';
+
+export default defineMap({
+  id: 'subtropical-city',
+  name: 'Subtropical city',
+  version: 1,
+  extends: streets,
+  modules: {
+    vegetation: vegetation({
+      mode: '3d',
+      threeDimensional: {
+        barkColor: token.color('vegetation.tree.bark'),
+        heightScale: 1.1,
+        finish: 'toon',
+        edges: 1,
+        // Along this coast most trees the data does not describe are palms.
+        regions: [{bounds: [-81.0, 24.4, -79.8, 26.9], unknownForms: {palm: 3, round: 1, open: 1}}],
+      },
+    }),
+  },
+});
+```
+
+`finish` sets how trees take the light: `faceted` (the default), low-poly facets softened towards a
+round crown; `smooth`, round crowns; or `toon`, three bands of light and a crisp shadow, as a drawn
+tree has them. `edges` rings each tree with an outline a constant width on screen, from 0 (none,
+the default) to 1, in `edgeColor` or the crown's darkest colour deepened; buildings use the same
+two words for their outlines.
+
+`heightScale` and `crownScale` stretch every tree, and `forms` each form on top of them, such as
+`forms: {palm: {heightScale: 1.2}}` for taller palms. `unknownForms` sets, as relative weights, the
+forms of trees whose data gives none, and `regions` sets them inside `[west, south, east, north]`
+bounds in degrees, the first region holding a tree applying. They are a choice of look, not data:
+they never change a tree whose data gives its form, and as mapping improves they apply to fewer
+trees.
+
+## Your own trees
+
+A map can draw a form with its own models. Put glTF binaries (`.glb`) in a directory, declare it in
+the map's `models`, and name the models a form draws by their file names:
+
+<!-- docs:check -->
+
+```ts
+import {defineMap, vegetation} from '@tileflow/core';
+import {streets} from '@tileflow/maps';
+
+export default defineMap({
+  id: 'palm-coast',
+  name: 'Palm coast',
+  version: 1,
+  extends: streets,
+  // ./models holds sabal-palm.glb and royal-palm.glb, and sabal-palm.far.glb for far trees.
+  models: ['./models'],
+  modules: {
+    vegetation: vegetation({
+      mode: '3d',
+      threeDimensional: {
+        forms: {palm: {models: ['sabal-palm', 'royal-palm'], heightScale: 1.1}},
+      },
+    }),
+  },
+});
+```
+
+Each tree of the form draws one of its models, one to four, by its stable hash, so a palm keeps its
+model wherever it is read. The data still chooses each tree's form and size: a model replaces how a
+form looks, not which trees take it.
+
+How to prepare a model:
+
+- **Materials name the parts.** Name each material `bark`, `leaves`, `fronds` or `stem` (an
+  exporter's `.001` suffix is ignored). Each part takes its theme colours, as Core's trees do; the
+  material's colour and any vertex colours set how light or dark each part of the model is within
+  them, so the model follows the theme from day to night.
+- **The origin is where the trunk meets the ground**, with the tree above it. Tileflow stands the
+  model as a unit tree: its top is the tree's height, and its widest leaf half its crown.
+- **Budgets.** A model has at most 1,000 triangles and 4,096 vertices; `<id>.far.glb`, drawn
+  beyond the nearest tiles, at most 120 triangles. Without a far model, the form's own far tree
+  stands in. A map draws at most 16 models.
+- **What is read.** Triangles of the default scene with their node transforms; textures,
+  animations and compressed geometry (Draco or meshopt) are not. Export without compression.
+
+`tileflow preview` and every build read the models, report a problem with the file and what to
+change, and watch the directories. The models travel inside the compiled style, so they need no
+files of their own when the map is deployed. A later directory's model replaces an earlier one of
+the same name; omitting `models` inherits them, and `[]` declares none.
+
+## Light and shadows
+
+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)).
+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.
+
+## Options
+
+`minzoom` (15 by default) 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
+map's request rules to the tiles the layer reads. Layers that read the same source share each
+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.
+
+## Limits
+
+- Mercator only; the layer draws nothing below its `minzoom`.
+- No terrain: trees stand on flat ground.
+- No wind or seasons; one form per tree.
+- Models replace a form's look; a model per genus or species is not available.