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

package/docs/application-tile-reading.md

@@ -0,0 +1,80 @@
+# Application tile reading
+
+Some application features need the map's data themselves rather than what MapLibre draws: a route
+over the streets, the name of the place under the camera, buildings for a custom 3D layer.
+MapLibre answers `querySourceFeatures` only for the tiles it has loaded for the current view, at
+the zoom it shows. `createTileflowTileReader` reads chosen layers of a vector source for any area
+at a fixed zoom instead, with the map's own tile address and request rules.
+
+## Read an area
+
+This example assumes an existing MapLibre map named `map` whose style has loaded a vector source
+named `tileflow`:
+
+<!-- docs:check -->
+
+```ts
+import {
+  createTileflowTileReader,
+  readTileflowMapTileSource,
+  tileflowTilePointToLngLat,
+  type TileflowTileSourceMap,
+} from '@tileflow/core/browser';
+
+export async function streetNamesNear(map: TileflowTileSourceMap, lng: number, lat: number) {
+  const source = readTileflowMapTileSource(map, 'tileflow');
+  if (!source) return [];
+  const reader = createTileflowTileReader({...source, layers: ['transportation_name']});
+  const tiles = await reader.readArea({
+    bounds: [lng - 0.005, lat - 0.005, lng + 0.005, lat + 0.005],
+    zoom: 14,
+  });
+  const names = new Map<string, [number, number]>();
+  for (const tile of tiles) {
+    const layer = tile.layers.transportation_name;
+    for (const feature of layer?.features ?? []) {
+      const name = feature.properties.name;
+      const [x, y] = feature.geometry[0] ?? [];
+      if (typeof name === 'string' && x !== undefined && y !== undefined)
+        names.set(name, tileflowTilePointToLngLat(tile, x, y, layer!.extent));
+    }
+  }
+  return [...names];
+}
+```
+
+`readArea` reads the tiles covering the bounds at the zoom, clamped to the source's `minzoom` and
+`maxzoom`. Deeper zooms read the source's last zoom. It leaves out tiles the source does not have
+and refuses an area of more than `maxTiles` tiles (64 by default). `readTile({z, x, y})` reads one
+tile. Both take an `AbortSignal`.
+
+## What the reader returns
+
+Each tile holds the chosen layers. Each layer holds its `extent` (tile units across the tile,
+usually 4096) and its features. A feature has `type` (`Point`, `LineString` or `Polygon`),
+`properties`, an `id` when the tile gives one, and `geometry`: one flat `[x0, y0, x1, y1, …]` array
+per point set, line or ring, in tile units. Rings are closed and keep the vector tile winding:
+exterior rings run clockwise in tile units, holes anticlockwise. Coordinates in a tile's buffer
+fall outside `0` to `extent`, and lines are cut at the buffer's edge, so a feature crossing tiles
+comes in pieces. `tileflowTilePointToLngLat(tile, x, y, extent)` converts a point to longitude and
+latitude.
+
+Feature ids read as MapLibre reads them, including ids beyond 2^53, so they can address feature
+state on the map.
+
+## Requests and cache
+
+- **One request per tile.** However many reads wait for a tile, it is requested once. A read whose
+  signal aborts stops waiting, but the request finishes for the cache and the other reads.
+- **Cache.** The reader keeps up to `cacheSize` decoded tiles (128 by default), the most recently
+  read first. It remembers a tile the source does not have (404 or 204) as absent, and does not
+  remember errors. `clear()` forgets everything.
+- **Concurrency.** At most `concurrency` requests (6 by default) run at once; the rest wait their
+  turn.
+- **Requests.** `transformRequest` rewrites each request as a MapLibre map's option does. Pass the
+  map's own so tile reads follow the same rules. The browser's HTTP cache applies as for any
+  request.
+
+The reader has no DOM dependency, so it also runs in a module worker: post the tile address and
+zooms to the worker and create the reader there. `decodeTileflowVectorTile(bytes, {layers})`
+decodes tile bytes an application already has.

package/docs/authoring-model.md

@@ -153,8 +153,17 @@ independent place, water, aerodrome, and POI labels remain under the labels modu
 Every styling module supports semantic shortcuts and exact semantic targets. Visual style values
 accept typed token refs, documented `fixed(value, {reason})` values, closed data expressions through
 `expr.*` plus `field(...)`, and zoom functions through `zoom.step(...)`, `zoom.linear(...)`, or
-`zoom.exponential(...)`. Refs and fixed leaves also work inside typed expressions and zoom stops.
-Structural controls such as presets, visibility, and zoom gates remain ordinary literals. Exact
+`zoom.exponential(...)`. Refs and fixed leaves also work as the results of typed expressions and
+as zoom-stop values; conditions and other operands take plain values, such as `3` rather than
+`fixed(3)` in a rank test inside a colour expression. Structural controls such as presets,
+visibility, text fields, and zoom gates remain ordinary literals. Expression builders take at most
+16 branches, stops, or operands; an error names the received count and the config line of the
+call, and a larger lookup composes nested groups.
+
+Layout properties, such as text fields, text and icon sizes, and symbol placement, are evaluated at
+each tile's integer zoom: a step at zoom 17.5 takes effect at zoom 18. Paint properties follow the
+camera's exact zoom. `createStyleResult()` reports a `TF_LAYOUT_FRACTIONAL_ZOOM_STEP` warning with
+the semantic target for every layout step at a fractional zoom. Exact
 controls address stable concepts such as `roads.classes.primary.surface.fill`, not renderer layer
 IDs.
 

package/docs/buildings-3d.md

@@ -0,0 +1,168 @@
+# 3D buildings
+
+`createTileflowBuildings3D` raises the buildings of a Tileflow map's vector tiles round the camera
+and lights them from the theme controller's sun: walls and roofs take the light by how they face
+it, buildings cast shadows on each other and on the flat map, the ground darkens at the foot of the
+walls, and at night flood lights wash the foot of shops, busy places, landmarks and towers while
+the places busy at night light their ground floors. Showing, hiding and growing the city lays out
+no source, so it works as a 3D switch and as an animated height.
+
+It is a custom WebGL2 layer for MapLibre GL JS, drawn above the map's buildings and below its
+labels. It needs WebGL2 and the Mercator projection, which MapLibre's globe turns into from about
+zoom 12; the buildings stand from zoom 14.5 by default.
+
+## Show the buildings
+
+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 {
+  createTileflowBuildings3D,
+  type TileflowBuildings3DMap,
+  type TileflowThemeController,
+} from '@tileflow/core/browser';
+
+export function raiseTheCity(map: TileflowBuildings3DMap, controller: TileflowThemeController) {
+  const buildings = createTileflowBuildings3D({map, controller});
+  // The buildings slide out of the ground over a second.
+  void buildings.show({transition: {duration: 1000}});
+  return buildings;
+}
+```
+
+`show()` raises the buildings, `hide()` sinks them back into the flat map, and `grow(scale)` eases
+them to a share of their height, from 0 to 1. Each returns a promise that resolves once the motion
+ends; a newer call takes over from where the buildings stand. A browser preference for reduced
+motion changes at once. `dispose()` takes the layer off the map.
+
+The renderer reads the source's z15 tiles round the camera (z15 is where World's buildings carry
+their heights; a source that stops earlier is read at its own maximum zoom), up to `maxTiles`
+tiles (25 by default), and meshes them a few milliseconds per frame. It reads World's
+`render_height`, `render_min_height`, `hide_3d`, `building_tone` and `night_use`, and the places in
+World's `poi` layer (see [night light](#night-light)).
+
+## 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)).
+A sunlit roof keeps the building's colour, a wall turned to a low sun glows, and shade takes the
+sky's colour. As the sun sets, shadows lengthen while they fade; a sun below the horizon casts none.
+
+A wall sees half the sky, so at night, when the ground gives back little light, walls in shade
+stay darker than roofs. A theme's night `lighting.sun` set high (60° or more) lights roofs more than
+any wall, so roofs and walls read apart under the moon.
+
+MapLibre's own layers take no shadows, so the renderer darkens the map it is drawn over: after its
+buildings, it multiplies the ground by the shadows and by a band at the foot of the walls. Labels
+and icons drawn above it keep their colours. Layers kept under 3D content with
+`createTileflowGroundLayers` are darkened with the ground.
+
+`shadows` and `occlusion` (the band at the foot of the walls and the darker tight corners) default
+to true and can be turned off. `windows: true` adds invented night windows, lit by rooms; they are
+decoration, not data, and are off by default.
+
+## Edges
+
+Where one building ends and the next starts stays legible at any distance: each roof's outline and
+each building's outer corners catch the light in a line one CSS pixel wide, whatever the zoom, and
+each building is a little lighter or darker than its colour (up to 6%), so neighbours of one colour
+stay apart. The lines are strongest at night; diagonals inside a roof, inner corners and the cuts at
+a tile's edge draw none. `edges` sets their strength from 0 (none) to 1, the default.
+
+`edgeColor` gives the lines a colour of the application's own, as a CSS colour or per theme: a dark
+outline as on a printed map, or a neon one at night. It is drawn as it is, unlit, at the full
+`edges` strength by day and night. The renderer asks for each theme's colour once and mixes the
+colours of the themes either side of a blend's position; a theme without a valid colour keeps the
+default.
+
+<!-- docs:check -->
+
+```ts
+import {
+  createTileflowBuildings3D,
+  type TileflowBuildings3DMap,
+  type TileflowThemeController,
+} from '@tileflow/core/browser';
+
+export function neonEdges(map: TileflowBuildings3DMap, controller: TileflowThemeController) {
+  return createTileflowBuildings3D({
+    map,
+    controller,
+    // Cyan outlines at night, a dark ink by day.
+    edgeColor: (theme) => (theme === 'night' ? '#7fd8ff' : '#2b2a33'),
+  });
+}
+```
+
+## Night light
+
+At night (as the sun's `brightness` falls), the buildings light the street from data, quietly by
+default:
+
+- Landmarks (World's `building_tone` `destination`) and towers of 40 m or more, one in two, are
+  flood-lit at their foot, on the wall and the ground around it.
+- Buildings that hold places busy at night light the windows of their ground floor and spill their
+  light a few metres onto the pavement: bars and clubs in a neon of their own or a warm light,
+  theatres and cinemas in a bright white, places to eat in amber. A building takes the strongest
+  use of its places, nightlife before entertainment before dining. Walls round a courtyard stay
+  dark.
+
+The night use comes from World's `night_use` on each building. In tiles whose buildings do not
+carry it, the renderer finds it in the tile's places (`placesLayer`, `poi` by default): a place
+inside a building, or within a few metres of its facade, gives the building its use.
+
+`nightLight` sets how bright all of this shines, from 0 (none) to 2; it defaults to 1.
+
+For the streets themselves, see
+[street lights](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/street-lights.md),
+which draws over the buildings so they hide the lamps behind them; both layers share each tile's
+download.
+
+## Colours
+
+Without `color`, buildings take the theme's 3D building colour, the colour Tileflow's buildings
+module compiles for its extrusion, and follow theme changes and blends.
+
+`color(properties, theme)` colours each building from its feature properties for each theme, as a
+CSS colour. The renderer calls it once per building and theme when a tile or the set of themes
+changes, and mixes the colours of the themes either side of a blend's position on the GPU, so a
+moving blend costs nothing per frame:
+
+<!-- docs:check -->
+
+```ts
+import {createTileflowBuildings3D, type TileflowBuildings3DMap} from '@tileflow/core/browser';
+
+const tints: Record<string, readonly string[]> = {
+  day: ['#f1d4cd', '#d3e8da', '#f6e0b5', '#e2d5f0', '#cfe3f2'],
+  night: ['#353d41', '#2f3a3d', '#3a3b44', '#33363f', '#2d3540'],
+};
+
+export function tintedCity(map: TileflowBuildings3DMap) {
+  return createTileflowBuildings3D({
+    map,
+    color(properties, theme) {
+      const floors = Math.floor(Number(properties.render_height ?? 5) / 3.2);
+      const palette = tints[theme] ?? tints.day!;
+      return palette[floors % palette.length]!;
+    },
+  });
+}
+```
+
+## Cost
+
+The shadow map (up to 4096 × 4096) is drawn again only when the sun, the buildings or their height
+change, not when the camera moves. In a campaign over Miami at 1512 × 860 at 2×, a city lit this
+way kept the frame pacing of the same city drawn without shadows.
+
+## Limits
+
+- Mercator only; the layer draws nothing below its `minzoom`.
+- No terrain: buildings stand on flat ground.
+- One building colour per feature and theme; facades, roof shapes and building parts as separate
+  shapes are not drawn.

package/docs/camera-moves-and-tile-cache.md

@@ -0,0 +1,112 @@
+# Camera moves and the tile cache
+
+A long camera move outruns the network: the new view's tiles take longer to arrive than the move
+takes. Some examples are a flight from a street to a region and back, a guided tour, or a scripted
+opening. MapLibre keeps the tiles it no longer shows in an out-of-view cache, so a camera that
+comes back finds them ready. This guide covers what keeps that cache useful and what empties it,
+as MapLibre GL JS 6 behaves.
+
+## What the cache keeps
+
+The out-of-view cache holds about five views' worth of tiles per source:
+
+- **Size.** It is the tiles across the map times `maxTileCacheZoomLevels`, 5 by default.
+  `maxTileCacheSize` caps it.
+- **Too small for a flight.** A move that crosses many zooms (a street, the region, the street
+  again) needs more. Raise `maxTileCacheZoomLevels` on the map, for example to 12, so tiles
+  loaded early in a sequence are still there at its end.
+- **Exact tiles only.** While a tile the camera needs is loading, MapLibre falls back on its loaded
+  parents or children only among the tiles it shows. It does not fall back on tiles it keeps out
+  of view. A cached tile helps only when it is the very tile a frame needs.
+
+## What empties it
+
+Changes that make MapLibre lay a source's tiles out again also empty that source's out-of-view
+cache. The tiles in view are parsed again; the cached ones are dropped and come back from the
+network when the camera returns.
+
+**Changes that lay tiles out:**
+
+- Any layout property, `visibility` included, through `setLayoutProperty`.
+- A filter, through `setFilter`.
+- A new value, through `setPaintProperty`, for a paint property whose value reads feature data,
+  such as `['get', ...]` or `['feature-state', ...]`.
+- `setStyle` with layers that differ. A style that is not diffed starts every source afresh.
+- In a theme blend, a change of the nearest theme over values like these. `setBlend({hold: true})`
+  keeps them back during a move; see
+  [theme transitions and blends](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/theme-transitions-and-blends.md).
+
+**Changes that keep the cache:**
+
+- A constant paint value, or one that reads only the zoom.
+- `setFeatureState`, which rewrites the paint of the features it names.
+- Global state read by values that read no feature data.
+
+During a camera move, change only what keeps the cache. Make layout changes, filters and theme
+crossings before the move starts or after it ends. To mark features during a move, prefer feature
+state over a filter.
+
+## Warm cameras before a move
+
+MapLibre GL JS 6 has no public way to load a camera's tiles without showing it. Until it does,
+warm cameras while something covers the map, such as a title card or a loading screen. Visit each
+camera with `jumpTo`, wait until its tiles are in, then go on to the next:
+
+<!-- docs:check -->
+
+```ts
+type WarmableMap = {
+  jumpTo(options: {
+    center: [number, number];
+    zoom: number;
+    bearing?: number;
+    pitch?: number;
+  }): unknown;
+  loaded(): boolean;
+  on(event: 'render', listener: () => void): unknown;
+  off(event: 'render', listener: () => void): unknown;
+  triggerRepaint(): void;
+};
+
+type Camera = {center: [number, number]; zoom: number; bearing?: number; pitch?: number};
+
+/** Resolves once the tiles of the camera on screen are in, or false after `ms`. */
+function tilesIn(map: WarmableMap, ms: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const check = () => {
+      if (map.loaded()) done(true);
+    };
+    const done = (ok: boolean) => {
+      clearTimeout(timer);
+      map.off('render', check);
+      resolve(ok);
+    };
+    const timer = setTimeout(() => done(false), ms);
+    map.on('render', check);
+    map.triggerRepaint();
+  });
+}
+
+export async function warmCameras(map: WarmableMap, cameras: readonly Camera[], rest: Camera) {
+  for (const camera of cameras) {
+    map.jumpTo(camera);
+    await tilesIn(map, 1500);
+  }
+  map.jumpTo(rest);
+}
+```
+
+Four details matter:
+
+- **Check after a frame.** `map.loaded()` can read false on the frame in which the last tile
+  arrived. So check it after a frame, on `render`, not once right after `jumpTo`.
+- **Do not wait for `idle`.** `idle` also waits for labels to fade in, which adds time and loads
+  nothing.
+- **Visit every zoom the move crosses.** A cached tile helps only when it is the exact tile a frame
+  needs, so warm each zoom, not just the destination.
+- **Make cache-emptying changes first.** Make the changes listed above before the first visit.
+  Otherwise the warm-up is lost.
+
+Mapbox GL JS offers `preloadOnly` on `jumpTo`, `easeTo` and `flyTo`, which loads a move's tiles
+without showing it. A MapLibre release with an equivalent would replace the visits above with one
+call per move.

package/docs/capture-scenes.md

@@ -34,3 +34,7 @@ external fixtures may identify their explicit revision.
 Every exact World V1 release ID is already canonical at the producer boundary: 12–128 characters
 matching `^world-v1-[a-z0-9][a-z0-9._-]*[a-z0-9]$`. Core validates the literal value and never trims,
 lowercases, or upgrades it to another World generation.
+
+To record a timed camera move instead of one image, commit a
+[capture shot](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/capture-shots.md)
+and render it with `tileflow capture --shot <name>`.

package/docs/capture-shots.md

@@ -0,0 +1,173 @@
+# Capture shots
+
+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.
+
+A shot is a short, timed camera move committed on the singular exported map. Capture renders it
+frame by frame into a WebM video or a directory of numbered PNG frames. Like
+[capture scenes](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/capture-scenes.md),
+shots implicitly target their map, do not inherit, and are removed before cartographic compilation;
+they affect visual evidence, not style or manifest identity.
+
+## Commit a shot
+
+This shot moves from central Madrid toward the east over four seconds while the map passes from
+the `light` theme to the `dark` theme:
+
+<!-- docs:check -->
+
+```ts
+import {defineMap} from '@tileflow/core';
+import {streets} from '@tileflow/maps';
+
+export default defineMap({
+  id: 'madrid',
+  version: 1,
+  extends: streets,
+  shots: {
+    'dusk-flyover': {
+      theme: 'light',
+      viewport: {width: 1280, height: 720, dpr: 1},
+      fps: 30,
+      keyframes: [
+        {
+          at: 0,
+          camera: {type: 'center', center: [-3.7038, 40.4168], zoom: 12},
+          blend: {themes: ['light', 'dark'], position: 0},
+        },
+        {
+          at: 4000,
+          camera: {type: 'center', center: [-3.68, 40.42], zoom: 14, bearing: 30, pitch: 45},
+          blend: {themes: ['light', 'dark'], position: 1},
+        },
+      ],
+    },
+  },
+});
+```
+
+A shot has these fields:
+
+- `theme`: a concrete theme of the map; `system` is invalid. The map loads this theme first, and a
+  shot without a blend shows it throughout.
+- `viewport`: CSS pixels and a `dpr` of 1 or 2, with the same limits as a scene viewport.
+- `fps`: 24, 25, 30, 50, or 60 frames per second. The default is 30.
+- `easing`: `smooth` (the default) eases into and out of each keyframe; `linear` moves at a constant
+  rate between keyframes.
+- `keyframes`: 2 to 64 entries. `at` is the whole number of milliseconds from the start of the
+  shot. The first keyframe is at 0, every later keyframe is later than the one before it, and the
+  last is at most 60000.
+
+Keyframe cameras use the scene `center` form: `[longitude, latitude]`, zoom, and optional bearing
+and pitch. The `bounds` form is not accepted, because the camera that fits bounds depends on the
+renderer's viewport and projection, and a shot interpolates between exact cameras.
+
+## Timing and interpolation
+
+A shot renders one frame at the start and one every `1 / fps` seconds up to its last keyframe:
+`floor(lastKeyframe.at × fps / 1000) + 1` frames, at most 3600. Frame `i` shows the shot at
+`i × 1000 / fps` milliseconds, so the last keyframe is itself a frame when its time is a whole
+number of frame intervals, as 4000 ms is at 30 frames per second.
+
+Between two keyframes the center moves in Web Mercator coordinates, along the shorter way around
+the world when it crosses the antimeridian. Zoom and pitch change linearly, and bearing turns along
+the shorter arc. Easing applies to every value in the same way. A frame exactly at a keyframe shows
+that keyframe's camera.
+
+`tileflowCaptureShotFrames` returns the camera and blend position of every frame without rendering
+anything, so tools can inspect a shot before capture:
+
+<!-- docs:check -->
+
+```ts
+import {tileflowCaptureShotFrames, type TileflowMapShot} from '@tileflow/core';
+
+const shot = {
+  theme: 'light',
+  viewport: {width: 640, height: 360},
+  keyframes: [
+    {at: 0, camera: {type: 'center', center: [-3.7038, 40.4168], zoom: 12}},
+    {at: 1000, camera: {type: 'center', center: [-3.68, 40.42], zoom: 13}},
+  ],
+} satisfies TileflowMapShot;
+
+const frames = tileflowCaptureShotFrames(shot);
+console.log(frames.length); // 31
+console.log(frames[15]?.camera.zoom); // 12.5
+```
+
+## Blend themes along a shot
+
+Add `blend` to every keyframe, or to none. Each blend lists the same two to eight concrete themes in
+the same order, and a `position` from 0 to one less than the number of themes, as in a
+[theme blend](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/theme-transitions-and-blends.md).
+The position moves between keyframes with the same easing as the camera.
+
+Capture prepares the blend once with Core's theme controller and moves its position on every frame.
+The controller applies a new position once it differs by at least a four-hundredth of a theme, so a
+very slow blend changes the ground colours every few frames. Labels and icons change at the nearest
+theme, without a cross-fade, because capture renders with reduced motion.
+
+## Render a shot
+
+Render committed shots with the CLI. The first command writes
+`.tileflow/captures/shots/dusk-flyover.webm` and its receipt; the second writes numbered PNG frames
+instead:
+
+```sh
+npx tileflow capture --shot dusk-flyover --json
+npx tileflow capture --shot dusk-flyover --format frames --json
+```
+
+Each frame waits until MapLibre has loaded the tiles and resources it needs, so a slow machine or
+network makes the render take longer but never drops or repeats frames. See the
+[capture guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/capture/README.md) for
+the Node API and the
+[capture contract](https://github.com/tileflow/tileflow-sdk/blob/main/docs/contracts/local-visual-capture.md)
+for output paths, encoding, and the shot receipt.
+
+## Play a shot in the browser
+
+`playTileflowShot(map, shot, options)` from `@tileflow/core/browser` plays the same shot live. The
+camera follows the keyframes frame by frame, with the same interpolation Capture renders, so the
+page and the video show the same film. This example assumes an existing MapLibre map named `map`,
+a theme controller, and the runtime styles of the blended themes:
+
+<!-- docs:check -->
+
+```ts
+import {
+  playTileflowShot,
+  type TileflowShotMotion,
+  type TileflowShotPlayerMap,
+  type TileflowThemeController,
+} from '@tileflow/core/browser';
+import type {TileflowRuntimeStyle} from '@tileflow/core/runtime';
+
+export function playDuskFlyover(
+  map: TileflowShotPlayerMap,
+  controller: TileflowThemeController,
+  themes: readonly TileflowRuntimeStyle[],
+  shot: TileflowShotMotion,
+  showTitle: () => void,
+) {
+  return playTileflowShot(map, shot, {
+    blend: (position) => void controller.setBlend({themes, position}),
+    cues: [{at: 2500, run: showTitle}],
+  });
+}
+```
+
+- **Blend.** `blend` receives the blend position at each frame of a shot that blends themes.
+- **Cues.** `cues` run once each, in time order, as the shot reaches them, for application events
+  such as drawing a route or showing a title.
+- **Stopping.** `stop()` or an aborted `signal` stops the shot where it is; `finished` resolves
+  `true` once the shot reaches its last keyframe and `false` when it was stopped first.
+- **Reduced motion.** With reduced motion requested, the shot shows its last keyframe at once and
+  runs every cue in order.
+
+`tileflowShotStateAt(shot, at)` returns the camera and blend position at any time, for players of
+one's own.
+
+Live playback runs at the browser's pace and does not wait for tiles, unlike a render. Load the
+tiles of the cameras a shot crosses before playing it; see
+[camera moves and the tile cache](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/camera-moves-and-tile-cache.md).

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/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.