@tileflow/core 0.1.0-alpha.4 → 0.1.0-alpha.41

package/docs/nautical-marks.md

@@ -0,0 +1,308 @@
+# Nautical marks
+
+The `nautical` module draws navigation marks from a `nautical-v1` vector source: buoys, beacons,
+lighthouses, lights that flash in their rhythm, rocks and other hazards, wrecks, reefs, navigation
+areas, routes, submarine and overhead cables, bridges with their clearances, harbours, marinas,
+berths, small-craft facilities, inland notice boards, waterway distance marks, 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`. Clearances, depths, and heights are in
+metres. `tileflowNauticalV1Schema` lists the field names, layers, geometry types, and known
+providers: `openstreetmap` (coverage class `community`), `nga-list-of-lights` (`list`), and the
+`chart` providers `noaa-office-of-coast-survey` and `usace-ienc` (U.S. Army Corps of Engineers
+Inland ENCs). The source's TileJSON owns every provider credit.
+
+| Source layer      | Geometry                   | Fields the module reads                                                                                            |
+| ----------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `aid`             | Point                      | `class`, `subclass`, `category`, `color`, `rank`, `name`, `information`, `distance`, `distance_unit`               |
+| `light`           | Point                      | `class` (`major` or `minor`), `color`, `label`, `rank`, `character`, `group`, `period_s`, `sequence`               |
+| `hazard`          | Point, LineString, Polygon | `class`, `water_level`, `name`                                                                                     |
+| `wreck`           | Point, Polygon             | `class`, `name`                                                                                                    |
+| `reef`            | Polygon                    | `name`                                                                                                             |
+| `navigation_area` | Point, LineString, Polygon | `class`, `subclass`, `size`, `rank`, `name`, `vertical_clearance` and its `_closed`, `_open`, and `_safe` variants |
+| `coverage`        | Polygon                    | `families`                                                                                                         |
+| `sounding`        | Point                      | `depth`                                                                                                            |
+
+The Nautical source promotes each light's `provenance` as its feature ID
+(`promoteId: {light: 'provenance'}`), so lights can be animated with MapLibre feature state.
+
+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                                   |
+| `overheadCables`  | `navigation_area` lines of class `overhead-cable`                            | Dash-dot accent line                                      |
+| `bridges`         | `navigation_area` bridge polygons; the outline also strokes bridge lines     | Land-coloured deck with an ink outline                    |
+| `berths`          | `navigation_area` berth polygons; the outline also strokes berth lines       | Thin ink outline, wider and darker for `guest` berths     |
+| `harbourAreas`    | `navigation_area` harbour and marina polygons                                | Faint ink wash with a solid outline                       |
+| `harbours`        | `navigation_area` harbour points, and a symbol inside harbour polygons       | Ink circle and name; the marina token for marinas         |
+| `facilities`      | `navigation_area` facility points, polygons, and line centres, from zoom 13  | Hollow circle; facility icons from the theme              |
+| `notices`         | `aid` notice boards, from zoom 12                                            | Circle in the board's function colour and `information`   |
+| `distanceMarks`   | `aid` distance marks, from zoom 11                                           | Ink dot and distance with its unit, fainter if not posted |
+| `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 polygons, bridge and overhead-cable clearances; coverage opt-in | Collision-aware text                                      |
+
+Bridge, berth, facility, and harbour polygons are drawn by their own groups rather than as
+navigation areas. `labels.bridges` shows `clearance 4.5 m`, or `closed 3.6 m · open 12 m` for an
+opening bridge, at bridge points, inside bridge polygons, and at the centre of bridge lines, from
+zoom 13. `labels.overheadCables` shows `safe clearance 28.5 m`, or the plain clearance, at cable
+points and along cable lines. Distance marks read `12 km`, `5 hm`, `300 m`, `12 mi`, or `4.5 NM`
+from zoom 13. Notice boards follow the CEVNI colours: red for prohibitions, regulations, and
+restrictions, green for recommendations, and blue for information; their `information`, such as a
+speed limit, appears from zoom 14. Board orientation and impact are not drawn.
+
+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}},
+    }),
+  },
+});
+```
+
+## Flashing lights
+
+In React, Vue, Svelte, and the development preview, every light with a rhythm flashes: its flare or
+circle draws at its styled opacity while the light shines and at 15 % of it during an eclipse.
+Fixed lights, lights without a usable characteristic, reduced motion, capture, native renderers, and
+static images show every light steadily, exactly as it is styled. Set `animateLights: false` to keep
+a map's lights steady everywhere:
+
+<!-- docs:check -->
+
+```ts
+import {defineMap, nautical} from '@tileflow/core';
+import {streets} from '@tileflow/maps';
+
+export default defineMap({
+  id: 'harbour-guide',
+  version: 1,
+  extends: streets,
+  marine: 'nautical',
+  modules: {nautical: nautical({animateLights: false})},
+});
+```
+
+A light flashes by its published `sequence` when it has one: light and eclipse durations in
+seconds, eclipses in parentheses, for example `0.5+(1.5)+0.5+(4.5)`. Otherwise
+`tileflowLightRhythm(properties)` derives a conventional rhythm from `character`, `group`, and
+`period_s`; `tileflowLightRhythmConventions` holds the values below.
+
+| Character                             | Rhythm                                                                                                 |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `Fl`                                  | Flashes of `min(1 s, 0.3 × period ÷ flashes)`; gaps within a group at most twice the flash             |
+| `Fl` with a group such as `2+1`       | Groups separated by twice the inner gap; the rest of the period is the final eclipse                   |
+| `LFl`                                 | The same layout with 2 s flashes, shorter only when the period cannot hold them                        |
+| `Q`, `VQ`, `UQ`                       | 60, 120, and 240 flashes a minute, lit for 30 % of each; a group of `n` flashes then eclipses          |
+| `IQ`, `IVQ`, `IUQ`                    | Quick flashes for 60 % of the period, then an eclipse                                                  |
+| `Iso`                                 | Equal light and eclipse                                                                                |
+| `Oc`                                  | Eclipses totalling 25 % of the period, laid out like `Fl`, so the light is always longer               |
+| `Mo`                                  | The Morse letter in `group`: 0.5 s dots, three-unit dashes, one-unit gaps, then the rest of the period |
+| `FFl`, `F+LFl`                        | A fixed light at half intensity with full flashes, or long flashes                                     |
+| `Q+LFl`, `VQ+LFl`, `UQ+LFl`, `Fl+LFl` | The group (six quick flashes by default), one 2 s long flash, then the eclipse                         |
+| `Oc+Fl`                               | Its occulting part                                                                                     |
+| `Al.<character>`, `Al`                | Each lit phase shows the next colour of `color`; `Al` alone shows each colour for an equal share       |
+| `F`, unknown, or missing period       | Steady; grouped `Q` and `VQ` cardinal marks without a period use the IALA periods                      |
+
+`tileflowLightStateAt(rhythm, seconds)` returns the intensity, colour index, and time to the next
+change at any moment. Lights with the same rhythm flash together.
+
+React, Vue, Svelte, the development preview, and standalone capture call
+`attachTileflowNauticalLights(map)` from `@tileflow/core/browser`. It reads the light layers the
+style declares in `metadata['tileflow:nautical-lights']`, and writes each rendered light's
+`tileflowLightIntensity` and `tileflowLightColour` feature state only when its phase changes. It runs
+one timer for the next change, and none while the page is hidden, while no light layer is visible at
+the current zoom, or under reduced motion. A direct MapLibre integration attaches it after
+constructing the map:
+
+```ts
+import maplibregl from 'maplibre-gl';
+import {attachTileflowNauticalLights, attachTileflowNotices} from '@tileflow/core/browser';
+
+const map = new maplibregl.Map({
+  container: 'map',
+  style: '/tileflow/styles/harbour-guide/light.json',
+});
+attachTileflowNotices(map);
+const detach = attachTileflowNauticalLights(map);
+// Call detach() to return every light to steady; removing the map also detaches it.
+```
+
+`steadyTileflowNauticalLights(style)` returns a copy that draws every light steadily without feature
+state; native artifact preparation applies it automatically.
+
+## 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.marina`         | Harbours whose `subclass` lists a marina   |
+| `nautical.port`           | `ports`                                    |
+| `nautical.notice`         | `notices`                                  |
+| `nautical.notice.<role>`  | Notices of that function                   |
+| `nautical.distance-mark`  | `distanceMarks`                            |
+| `nautical.facility`       | `facilities`                               |
+| `nautical.facility.<cat>` | Facilities listing that category           |
+
+Notice roles are `prohibition`, `regulation`, `restriction`, `recommendation`, and `information`.
+Facility categories are `fuel-station`, `slipway`, `boat-hoist`, `pump-out`, `water-tap`,
+`visitor-berth` (also used for `visitors-mooring`), and `boatyard`: a facility listing several shows
+the first in that order (`tileflowNauticalFacilityIcons`), and the others show `nautical.facility`.
+Every icon expression selects among the declared image names only.
+
+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. Notice
+boards take their function colour. Soundings declares these tokens with its own buoy, light,
+lighthouse, wreck, harbour, marina, notice-board, distance-mark, and facility symbols and keeps
+beacons as coloured dots.

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

@@ -0,0 +1,101 @@
+# Public API and browser subpath
+
+Start with the [@tileflow/core guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/README.md) for installation and a complete first example.
+
+Config, data, modules, compilation, validation, runtime resolution, and capture-scene APIs remain
+available from the package root. Capture scenes, manifests, and browser-runtime surfaces also have
+explicit `@tileflow/core/capture`, `@tileflow/core/manifest`, and `@tileflow/core/runtime`
+subpaths. Node build integrations import the small deterministic map-identity contract from
+`@tileflow/core/build`: `collectTileflowMapBuildLineage`, `createTileflowMapBuildManifest`,
+`hashTileflowMapRevision`, `hashTileflowAssetSet`, and `hashTileflowAssetSetIdentities`. The latter
+reproduces the same asset-set v1 hash from exact per-file identities after another system has
+independently confirmed the immutable bytes; package or bundle hashes are not substitutes. The
+previous aggregate-wrapper and recipe-selector APIs, `renderer`, top-level `tiles`/`tileset`, module
+arrays, and top-level raw `layers` are not part of this API. Raw MapLibre layers are accepted only
+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 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.
+Leaf `id`, `name`, editorial `mapVersion`, default `view`, capture `scenes`, and `delivery` policy do
+not change that content identity. They remain explicit on the map, manifest, Style, capture receipt,
+or Hosted deployment fingerprint that owns them. Compiler ABI, package versions, generated assets,
+and the concrete release selected by World `current` likewise have separate identities.
+
+Runtime manifest version 1 has one shape for local and Hosted delivery. Every map entry owns
+`defaultTheme`, optional `systemThemes`, and a `themes` record whose leaves contain
+`colorScheme`, `styleUrl`, and optional font/deployment identity. Hosted-only identity is additive
+metadata on the same map entry; there is no delivery discriminator or parallel `styles` alias.
+`parseTileflowRuntimeManifest()` accepts only this canonical shape. The strict bounded schema uses
+the same portable map and theme IDs as authoring, rejects `system` as a published name, duplicate
+font identities, unsafe owner-relative URLs, prototype-bearing input, unknown fields, and JSON
+larger than 1 MiB.
+
+```json
+{
+  "version": 1,
+  "maps": {
+    "madrid": {
+      "defaultTheme": "light",
+      "systemThemes": {"light": "light", "dark": "dark"},
+      "themes": {
+        "light": {"colorScheme": "light", "styleUrl": "/styles/madrid/light.json"},
+        "dark": {"colorScheme": "dark", "styleUrl": "/styles/madrid/dark.json"}
+      }
+    }
+  }
+}
+```
+
+Runtime fetches share a successful result for 30 seconds, never cache failures, use
+`cache: 'no-store'`, enforce a 10-second timeout (configurable up to 60 seconds), compose an
+external abort signal, and can be invalidated with `clearTileflowManifestCache()`.
+
+Named map `view` values travel in the manifest. `resolveTileflowRuntimeTheme()` turns an omitted,
+explicit, or `system` request with a supplied color scheme into one concrete published entry;
+unknown names fail closed. `resolveTileflowRuntimeView()` defines the shared precedence as explicit
+runtime values, then the manifest view, then the single exported `defaultTileflowRuntimeView`
+(`[0, 20]`, zoom 2, bearing/pitch 0).
+
+`TileflowRuntimeSource` is one object, `{map, manifestUrl?}`, selecting a named Tileflow map only
+through its published manifest. React, Vue and Svelte share that source contract. Omitting the URL
+means exactly `/tileflow/manifest.json`; other locations must be explicit. The native Core contract
+uses `{map, manifestUrl}` with a required absolute URL and no discovery, as described in the
+[native guide](native-resource-urls.md). The React Native type contract preserves that requirement.
+No public framework Map source exposes a renderer discriminator or direct-style branch. The obsolete
+`kind` and `style` fields are rejected; completely unmanaged maps use upstream MapLibre directly.
+The runtime subpath does not import the config compiler, invent a localhost style URL, or change
+image mode by environment.
+
+Framework adapters import the browser-only lifecycle kernel explicitly:
+
+```ts
+import {
+  attachTileflowAtmosphere,
+  attachTileflowFairUseNotice,
+  attachTileflowMapLifecycle,
+  attachTileflowNauticalLights,
+  attachTileflowNotices,
+  createTileflowSessionStarter,
+  createTileflowTransformRequest,
+  registerTileflowWorldRequestBridge,
+} from '@tileflow/core/browser';
+```
+
+`@tileflow/core/3d` holds only `createTileflowMap3D` and the 3D renderers it mounts, so an
+application can load them with a dynamic import when a style declares a 3D scene; see
+[3D buildings](buildings-3d.md#the-maps-3d-scene). The browser entry exports the same function.
+
+`attachTileflowNotices(map)` renders the notices a compiled style declares, such as Nautical's
+"Not for navigation", as a compact map control, and `attachTileflowNauticalLights(map)` flashes
+Nautical lights in their rhythm; 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
+resolution and asset rules live in the
+[map inheritance contract](https://github.com/tileflow/tileflow-sdk/blob/main/docs/contracts/map-inheritance.md).

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.