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

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

@@ -128,9 +128,7 @@ published, immutable glyph collection independent of World data. The older `/fon
 remains a mutable compatibility URL and does not make a resolved map byte-reproducible. The global
 glyph `assetSetSha256` is not the same-domain value as the per-map `assetSetSha256` in
 `build-manifest.json`.
-Cyberpunk and Matrix each replace the URL provider with their own packaged Oxanium directory and
-reference the exact local faces `Oxanium Medium` and `Oxanium SemiBold`. Baedeker and Siegfried
-each own a packaged directory containing Cormorant Garamond Regular, SemiBold, and Italic.
+Baedeker and Siegfried each own a packaged directory containing Cormorant Garamond Regular, SemiBold, and Italic.
 
 Name the official generation deliberately, or use another OpenMapTiles-compatible vector source:
 
@@ -320,21 +318,117 @@ 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.
 
+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
+points are not surveyed trees, are unrelated to the optional `tree` layer, and are not search or
+interaction targets. `openMapTiles()` and `tileflowWorldV1Schema()` bind the layer as `canopy` and
+its numeric fields as follows:
+
+- `canopyRank` (`rank`): a stable integer from 0 through 15. Lower ranks appear at lower zooms, and
+  the rank can vary artwork.
+- `canopyClearanceAtZoom15` (`clearance_px_z15`): 4, 6, 8, 12, 16, or 24. This is the lower bound
+  of the distance from the point to the nearest edge a crown must not cover, such as a park edge,
+  water, a building, a plaza, a pitch, or a roadway, in pixels of a 512-pixel tile at zoom 15. A
+  grove fits at zoom `z` when its drawn reach in screen pixels is at most
+  `clearance_px_z15 × 2^(z − 15)`.
+- `canopyCoverPercent` (`cover_pct`): 3, 30, or 60, the lower bound of the share, in percent, of
+  canopy taller than 3 m within 10 m of the point. The field is absent where no measurement exists;
+  treat absence as a middle density.
+
+Features are MultiPoints, one per identical set of attributes. Native zoom 15 holds every point,
+zoom 14 holds the points whose rank is below 8 at the same positions, and clients overzoom zoom 15.
+`validateTileflowWorldV1Tilejson(...)` accepts a TileJSON without `canopy`; once declared, the layer
+must occur exactly once, declare native z14–z15, and advertise Number `rank`, `clearance_px_z15`, and
+`cover_pct`. No module draws the layer. A source without it remains valid, and render passes bound
+to it draw nothing. `capabilities: {canopy: false}` removes the binding, after which a pass with
+`feature: 'canopy'` fails with a missing-binding error.
+
+Draw groves with symbol render passes, one grove of whole crowns per point, sized to its room:
+
+<!-- docs:check -->
+
+```ts
+import {expr, field, fixed, renderPass, token, vegetation, withRenderStack} from '@tileflow/core';
+
+// The grove artwork reaches 32 pixels from its center at icon size 1.
+const clearance = expr.get(field('canopyClearanceAtZoom15'));
+// The size that fills the room at one zoom, never larger than the artwork itself.
+const fit = (divisor: number) => expr.min(expr.divide(clearance, divisor), 1);
+
+const groves = (minZoom: number, fromRank: number, toRank: number) =>
+  renderPass({
+    placement: 'above-vegetation',
+    feature: 'canopy',
+    renderer: 'symbol',
+    selector: {
+      kind: 'all',
+      selectors: [
+        {field: 'canopyRank', kind: 'compare', operator: 'gte', value: fromRank},
+        {field: 'canopyRank', kind: 'compare', operator: 'lt', value: toRank},
+      ],
+    },
+    style: {
+      minZoom,
+      icon: {
+        ignorePlacement: true,
+        image: token.image('vegetation.canopy.grove'),
+        overlap: 'always',
+        size: expr.interpolate({base: 2, kind: 'exponential'}, expr.zoom(), [
+          [14, fit(64)],
+          [15, fit(32)],
+          [16, fit(16)],
+          [17, fit(8)],
+          [18, fit(4)],
+        ]),
+      },
+      text: {
+        field: 'o',
+        font: token.font('default'),
+        opacity: fixed(0, {reason: 'The core text only decides placement'}),
+        overlap: 'cooperative',
+        size: fixed(8, {reason: 'Matches the solid core of the grove artwork'}),
+      },
+    },
+  });
+
+export const canopyGroves = withRenderStack(vegetation(), {
+  groves14: groves(14, 0, 4),
+  groves15: groves(15, 4, 8),
+  groves16: groves(16, 8, 16),
+});
+```
+
+- Give each rank range its own pass with `minZoom`, so its points appear whole at their entry zoom.
+  MapLibre evaluates expressions that combine zoom and feature data at whole zoom levels and
+  interpolates between them, so a fade per feature would leave symbols half transparent. Zoom 14
+  tiles carry the ranks below 8, so the first pass may cover ranks 0–7.
+- Size each grove from `canopyClearanceAtZoom15`. Here the size is `clearance / 32` at zoom 15 and
+  doubles with each zoom until the grove reaches the artwork's size, which keeps the reach within
+  the room.
+- Collision tests an icon's whole image, including the transparent margin around the crowns. A small
+  invisible text the size of the grove's core therefore decides placement with
+  `overlap: 'cooperative'`, while the icon draws with `overlap: 'always'` and `ignorePlacement: true`.
+  Groves may overlap each other but give way to labels, which draw above the vegetation band and are
+  therefore placed first, with the default `never`.
+
+Every theme of the map must define the image token, and the map's icon directories must provide the
+artwork. Native artifacts replace `cooperative` with `allowOverlap: true`, so there groves can cover
+labels; see [symbol overlap modes](shared-visual-primitives.md#symbol-overlap-modes).
+
 The optional `business_corridor` extension contains activity-selected source footprints below
 buildings. Its `activity_score`, `rank`, `min_zoom`, and `confidence` fields control a quiet local
 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. Immutable
-V8.9 archives carrying `building_kind` or `has_business` remain readable as a defensive
-compatibility path, but new candidates do not emit those fields. The land module also exposes
+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.
 
 World and text assets are independent contracts. `tileflowWorld()` selects `world-v1/current` or an
-exact `releaseId + descriptorSha256`; a `glyphs` declaration contains its own complete URL. Ordinary
-imports of Streets, Baedeker, Cívica, Ferraris, Härad, Siegfried, Soundings, Cyberpunk, Matrix, Blueprint, and Super Tile World
-remain usable because each official map owns or inherits a URL or packaged-font provider.
+exact `releaseId + descriptorSha256`; a `glyphs` declaration contains its own complete URL. Every
+official map compiles as imported because it owns or inherits a URL or packaged-font provider.
 URL-backed maps become exact-byte reproducible
 when the immutable global base-asset set is published and their explicit URL is updated to its
 `assetSetSha256` path; no World or compiler fallback participates in that rollout. The global

package/docs/depth-markers.md

@@ -0,0 +1,65 @@
+# Depth markers
+
+DOM markers float above the map: in a 3D scene a pin behind a tower still shows in front of it.
+`createTileflowDepthMarkers` draws markers in the map's 3D scene instead. A MapLibre custom layer
+draws them against the depth the map's extrusions write, so nearer buildings hide them as the camera
+moves.
+
+## Add markers
+
+This example assumes an existing MapLibre map named `map` with 3D buildings, and two pictures drawn
+by the application:
+
+<!-- docs:check -->
+
+```ts
+import {createTileflowDepthMarkers, type TileflowDepthMarkerMap} from '@tileflow/core/browser';
+
+export function pinDestination(
+  map: TileflowDepthMarkerMap,
+  at: [number, number],
+  pin: HTMLCanvasElement,
+  ring: HTMLCanvasElement,
+) {
+  const markers = createTileflowDepthMarkers(map);
+  // A pin facing the viewer, 28 × 40 CSS pixels, standing on the position.
+  markers.add({lngLat: at, image: pin, size: [28, 40], anchor: 'bottom'});
+  // A ring lying on the ground, 60 metres across.
+  const halo = markers.add({lngLat: at, image: ring, size: [60, 60], alignment: 'ground'});
+  return {
+    pulse: (opacity: number) => halo.update({opacity}),
+    dispose: () => markers.dispose(),
+  };
+}
+```
+
+A marker has:
+
+- **Position.** `lngLat`, and `altitude` in metres above the ground.
+- **Picture.** `image`: an image, an image bitmap, a canvas or image data. After drawing into a
+  canvas again, pass it to `update({image})` so the marker uploads it once more. Markers that share
+  a picture share its upload.
+- **Alignment.** `screen` (the default) faces the viewer at `size` in CSS pixels, like a pin.
+  `ground` lies flat on the ground at `size` in metres, in the camera's perspective, like a ring or
+  an arrow painted on the street.
+- **Anchor and placement.** `anchor` (`center` or `bottom`), `offset` in CSS pixels for screen
+  markers, and `rotation` in degrees clockwise: from the screen's up for screen markers, from north
+  for ground markers.
+- **Opacity.** From 0 to 1.
+- **`occlude`.** Defaults to true: nearer 3D content hides the marker. Set it to false for a marker
+  that must always show.
+
+Markers test against the scene's depth without writing to it, so they never hide one another. A
+screen marker takes the depth of its position: a tower in front of the position hides the whole
+pin, a tower in front of part of it hides that part.
+
+## Layer and lifecycle
+
+The markers share one custom layer, `tileflow-depth-markers` unless `id` names another, added with
+the first marker. `beforeId` places it under a layer, given as an id or as a function that finds the
+layer again after a style change. After a style change the layer puts itself back, and pictures
+are uploaded again. `dispose()` removes the layer and releases its GPU resources.
+
+Depth markers need MapLibre GL JS on WebGL 2 (GL JS 5 or later). They work on globe and Mercator
+projections. They draw pictures only: draw text and effects into the picture, or keep DOM markers
+for interactive content.

package/docs/dynamic-style-images.md

@@ -0,0 +1,100 @@
+# Dynamic style images
+
+Use `registerImage` on an existing `TileflowThemeController` from `@tileflow/core/browser` when an
+application draws RGBA pixels that depend on a theme or style state. The controller owns the image's
+registration, refresh and restoration. The application owns its drawing and prepares asynchronous
+assets before registration. This browser API is tested with MapLibre GL JS 6.13; it is not a Native
+or Static Maps image contract.
+
+Start with the [Core guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/README.md)
+and [theme controller setup](theme-transitions-and-blends.md#use-the-core-controller).
+The map's symbol layer must already refer to the same image ID in every theme. Register before its
+first placement. Choose an ID that does not exist in the sprite or belong to another application
+resource. Registering an image does not create a layer or add points to a source.
+
+## Draw an alert from state
+
+This helper runs after browser mounting, with the controller for the existing map. The image is
+64 physical pixels at pixel ratio 2, so it occupies 32 logical pixels before the layer's icon scale.
+
+<!-- docs:check -->
+
+```ts
+import type {TileflowThemeController} from '@tileflow/core/browser';
+
+export function registerAlert(controller: TileflowThemeController) {
+  const canvas = document.createElement('canvas');
+  canvas.width = canvas.height = 64;
+  const context = canvas.getContext('2d', {willReadFrequently: true});
+  if (!context) throw new Error('Canvas 2D is unavailable.');
+
+  return controller.registerImage('live-alert', {
+    width: 64,
+    height: 64,
+    pixelRatio: 2,
+    states: ['alert'],
+    render({theme, states}) {
+      context.clearRect(0, 0, 64, 64);
+      context.beginPath();
+      context.arc(32, 32, 24, 0, Math.PI * 2);
+      context.fillStyle = states.alert ? '#ee624e' : '#edbd53';
+      context.fill();
+      context.strokeStyle = theme === 'night' ? '#ffffff' : '#253b42';
+      context.lineWidth = 4;
+      context.stroke();
+      return context.getImageData(0, 0, 64, 64).data;
+    },
+    onError(error) {
+      console.error('Alert image could not refresh:', error);
+    },
+  });
+}
+
+export async function activateAlert(controller: TileflowThemeController) {
+  await controller.setState('alert', true);
+}
+```
+
+The resource receives the states listed in `states`, including intermediate values during numeric
+state transitions. `theme` is the committed theme, or the nearest theme of a blend. `blend` exposes
+its position and ordered theme names for continuous artwork interpolation. States not set through
+this controller remain undefined; an explicit null is distinct from an unset state.
+
+## Update and release
+
+Theme changes and changes to declared states schedule a refresh. Identical inputs do no work;
+several changes before the next animation frame coalesce. The `setState` promise describes the
+state transition, not completion of the next image frame. There is no independent animation clock.
+For camera values, new application data or another external input, call the returned handle's
+`refresh()`. Read those values inside `render`, and return `undefined` when the existing pixels are
+still correct. Undefined output on the first render creates a transparent image.
+
+`render` is synchronous and returns exactly `width * height * 4` RGBA bytes as a `Uint8Array` or
+`Uint8ClampedArray`. The controller copies the buffer. Width and height must be integers from 1
+through 2048; pixel ratio must be positive and finite. All three remain fixed until disposal.
+Changing pixel ratio while keeping physical size would change logical size and collision geometry,
+so choose it at registration rather than following device pixel ratio changes automatically.
+
+A style reload restores the last valid image before placement. WebGL context loss suspends image
+work; restoration replays pixels and processes pending inputs. `handle.dispose()` removes only
+that resource's image and cancels its pending work. `controller.dispose()` releases all of its
+images. Map removal cancels work and releases listeners. Disposal is idempotent.
+
+Invalid registration throws before claiming a resource. Later render failures keep the last valid
+pixels and call `onError`, or `console.error` when omitted. A later refresh can retry. Another image
+owner is never silently overwritten. The application must not call `addImage`, `updateImage` or
+`removeImage` for a registered ID. Dynamic IDs must stay identical across blended themes; mixing
+them with theme-specific atlas artwork is rejected before the blend replaces the style.
+
+## Placement and scope
+
+This API changes image pixels only. It does not resize icons, split layers, change padding,
+anchors, sort order, overlap, filters or source features. Native symbol placement and collisions
+remain governed by the authored style. Transparent pixels still occupy the image's existing
+geometry: this API does not define separate visual and collision bounds.
+
+All features using an ID share its pixels and state. Independent per-feature animation, SDF
+generation, image loading, GPU composition and automatic framework props are outside this API.
+Keep every selectable icon in the same symbol layer RGBA, including fallbacks; mixing these images
+with SDF icons does not become supported through registration.
+Profile the application's drawing cost and visible symbol rendering on its target devices.

package/docs/native-artifact-profile.md

@@ -72,8 +72,10 @@ Dev's `native-lowering-v1` preparation policy explicitly converts a fixed `{type
 projection to Native's implicit Mercator before this validator runs. This is a recorded projection
 change, not globe support or visual equivalence. One authored map serves web and native preparation;
 no native-specific Streets definition is used. Preparation adapts only finite `line-cap` and
-`line-dasharray` decisions into constant-property layers. Other unsupported properties have no implicit fallback. The raw validator continues to reject
-unlowered unsupported expressions. See the [preparation contract](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/docs/native-artifacts.md)
+`line-dasharray` decisions into constant-property layers, and replaces constant `icon-overlap` and
+`text-overlap` modes with their `*-allow-overlap` equivalent. Other unsupported properties have no
+implicit fallback. The raw validator continues to reject unlowered unsupported expressions and
+overlap modes. See the [preparation contract](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/docs/native-artifacts.md)
 for the grammar, expansion limits and pending native visual checks. The lowering checks establish
 per-feature selection and cap/dash values, not global feature draw order. A copied `line-sort-key`
 cannot preserve ordering between simultaneous physical branches; overlapping features may produce
@@ -81,7 +83,7 @@ a different composition even when every property value is retained.
 
 `native-build.json` uses strict schema version 2 and `preparationVersion: 'native-lowering-v1'`.
 Its `transformations` array is ordered by map/theme and binds the input/lowered style hashes,
-projection policy and physical layer spans. The runtime manifest remains version 1. An old v1
+projection policy, physical layer spans and symbol overlap replacements. The runtime manifest remains version 1. An old v1
 build-record decoder must reject v2 rather than silently ignore the preparation evidence.
 
 Text must use a valid glyph template containing `{fontstack}` and `{range}`, or a complete static

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/shared-visual-primitives.md

@@ -22,6 +22,26 @@ Compounds express common cartographic structures: `AreaStyle` has `fill` and `ou
 optional `text`, `icon`, and `marker`. Geographic selection remains owned by semantic modules;
 ordinary visual styles intentionally do not accept raw source filters.
 
+## Symbol overlap modes
+
+`text.allowOverlap` and `icon.allowOverlap` either hide a part that collides with a symbol placed
+before it or always show it. `overlap` selects one of three modes instead:
+
+- `never`: hide the part when it collides.
+- `always`: show the part even when it collides.
+- `cooperative`: show the part unless it collides with a symbol placed with `never`. It may overlap
+  symbols placed with `always` or `cooperative`.
+
+MapLibre places symbols from the top layer down, so a symbol placed before another is usually higher
+in the stack. `overlap` takes precedence over `allowOverlap` on the same part, including an
+`allowOverlap` default supplied by a module or already present on a refined target, so the compiled
+layer carries only `text-overlap` or `icon-overlap`. MapLibre Native has no overlap modes, so native
+artifact preparation replaces the mode with the matching `text-allow-overlap` or
+`icon-allow-overlap`: `false` for `never` and `true` for `always` and `cooperative`. There a
+cooperative part no longer gives way to symbols placed with `never`. The
+[canopy grove recipe](data-is-separate-from-design.md) uses a cooperative text to decide where
+icons draw.
+
 ## Line-fitted text backgrounds
 
 `text.background` draws one opaque strip behind each shaped line of a label, fitted to that line's

package/docs/street-lights.md

@@ -0,0 +1,80 @@
+# 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 `color`, a warm white by default.
+- 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.
+
+`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.
+
+## Options
+
+`intensity` scales the light from 0 to 2 (1 by default). `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; `source` names a vector source other than `tileflow`; `transformRequest`
+applies the map's request rules to the tiles the layer 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.