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

package/docs/capture-scenes.md

@@ -25,7 +25,7 @@ export default defineMap({
 });
 ```
 
-Use `tileflow preview --scene madrid-desktop` (`tileflow dev` remains an alias) for live review and
+Use `tileflow preview --scene madrid-desktop` for live review and
 `tileflow capture madrid-desktop` for exact pixels and a schema-version-4 receipt containing the
 concrete theme plus Streets, data, style, renderer, and image identities. World capture resolves the selected TileJSON
 once and records the exact `world-v1` release plus descriptor/archive/data-contract hashes;

package/docs/compiled-style-performance.md

@@ -237,7 +237,10 @@ canonical `poi` layer exposes `category`, `type`, `icon`, `min_zoom`, `filter_ra
 Core validates that complete contract and never reconstructs those decisions from OpenMapTiles
 `class`, `subclass`, or `rank`. `filter_rank` is an
 integer from 0 through 5, with lower values reserved for the strongest candidates. The numeric
-`density` option is an inclusive threshold from 1 through 5 and defaults to 3. `size_rank` is an
+`density` option is an inclusive threshold from 1 through 5 and defaults to 3. World publishes
+every eligible POI at z15, its last POI zoom, and higher zooms overzoom those tiles with more room,
+so the threshold rises by one rank at z16 and by two from z17. At the default density every rank is
+eligible from z17, and collision placement keeps what fits. `size_rank` is an
 integer from 0 through 16 used to order eligible candidates before MapLibre performs final
 collision placement.
 

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/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/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/style-states.md

@@ -0,0 +1,73 @@
+# Style states
+
+A theme can read a value that the application sets once for the whole style, such as whether
+anything is selected. The theme reads it with `expr.globalState(name)`; the application sets it with
+the theme controller's `setState(name, value)`. MapLibre calls these values global state (GL JS 5.6
+or later).
+
+## Read a state in a theme
+
+A state reads `null` until the application sets it, so wrap it in a typed assertion with a fallback.
+To let a value move smoothly, make the state a number and interpolate on it:
+
+<!-- docs:check -->
+
+```ts
+import {expr} from '@tileflow/core';
+
+// 0 shows the standing highlight, 1 the quiet plate; values between mix the two.
+const selection = expr.toNumber(expr.globalState('selection'), 0);
+export const captionPlate = expr.interpolate({kind: 'linear'}, selection, [
+  [0, '#ef5f57'],
+  [1, '#fff9ee'],
+]);
+```
+
+A boolean works too, through `expr.case`, but it can only switch.
+
+## Set a state from the application
+
+This example assumes an existing MapLibre map named `map` that shows the `light` theme of a
+published Tileflow map:
+
+<!-- docs:check -->
+
+```ts
+import {createTileflowThemeController, type TileflowStyleSwitchMap} from '@tileflow/core/browser';
+
+// A MapLibre map satisfies TileflowStyleSwitchMap.
+export function selectionStates(map: TileflowStyleSwitchMap, styleUrl: string) {
+  const controller = createTileflowThemeController({
+    initial: {style: styleUrl, theme: 'light'},
+    map,
+  });
+  void controller.setState('selection', 0);
+  return {
+    select: () => controller.setState('selection', 1, {transition: {duration: 300}}),
+    clear: () => controller.setState('selection', 0, {transition: {duration: 300}}),
+  };
+}
+```
+
+A number eases from the value the map shows to the new one over the transition, so the plate mixes
+smoothly from one colour to the other. Booleans, strings, `null`, and a number set for the first
+time change at once, so set a starting value before easing it. A browser preference for
+reduced motion changes at once. Each call supersedes an easing of the same state still in progress,
+which resolves with `status: 'superseded'`; the new easing starts from where the old one stood.
+
+States stay through `setTheme` and every `setBlend`: the controller writes them again after each
+new style. `getState(name)` returns the value set last.
+
+## Keep eased values free of feature data
+
+Keep a value that eases on a state free of feature data and feature state. MapLibre evaluates such
+a value for the whole layer at each frame. A value that also reads a feature's data or state is
+evaluated per feature when its tiles are laid out, so each change of the state lays them out
+again: the value follows late, in steps, and each frame costs far more. Put the per-feature choice
+in another layer, or let the application draw the feature it marks.
+
+## Cost
+
+Each frame of an easing sets the state once, and MapLibre then evaluates again every paint value
+that reads it. A state read by a few layers costs little; a state read by most layers of a map can
+cost more per frame than the blend itself on slower devices.

package/docs/theme-transitions-and-blends.md

@@ -83,7 +83,8 @@ While a blend is shown, `data-tileflow-theme` names the theme nearest to the pos
 - Colours and numbers of the ground, such as land, water, roads, buildings, and their widths and
   opacities, follow the position continuously. Colours mix in the OKLab colour space, so halfway
   between two themes looks halfway to the eye.
-- Patterns, the sky, and light follow the position too. Pattern artwork is mixed in its pixels.
+- Patterns, the sky, and light follow the position too. Pattern artwork is mixed in its pixels;
+  artwork two neighbouring themes share, by name or pixel for pixel, is not uploaded again.
 - Labels, icons, and other symbols change when the nearest theme changes, with a short cross-fade.
   Light lettering on a dark plate and dark lettering on a light plate would meet in the same grey
   halfway, so symbols do not follow the position.
@@ -195,7 +196,8 @@ export async function moveThroughTheDay(map: MapLibreMap, manifestMap: TileflowR
   await controller.setBlend({position: 0.5, themes});
   // The same themes: the position applies at once.
   await controller.setBlend({position: 0.6, themes});
-  return controller.getBlend(); // {position: 0.6, themes: ['night', 'dusk', 'day']}
+  // {held: false, position: 0.6, relayoutAt: [...], themes: ['night', 'dusk', 'day']}
+  return controller.getBlend();
 }
 ```
 
@@ -209,6 +211,8 @@ when styles need another loader.
 
 The controller also shows [map emphasis](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/map-emphasis.md),
 which stays through theme changes and follows every blend position.
+Its [dynamic style images](dynamic-style-images.md) receive theme, blend and declared state inputs
+under one resource owner, with fixed geometry and restoration after a style reload.
 
 ## Fast sweeps on slower devices
 
@@ -219,3 +223,38 @@ changes most ground layers on every frame. Measured in Chromium on Apple silicon
 a detailed city map, such a sweep kept 76 frames a second; with the processor slowed four times, as
 on a mid-range phone, it fell to about 11, against 28 for the same camera move without the sweep.
 On slower devices, prefer short sweeps or move the position less often.
+
+## Camera moves and recordings
+
+Some changes make MapLibre lay tiles out again: when the nearest theme changes, the values that
+switch with it (icon names, layout values, and values that read feature data or feature state),
+and each step of pattern or icon artwork that is mixed in pixels. A camera move or a screen
+recording shows that work as dropped frames. `getBlend().relayoutAt` lists the positions where the
+nearest theme changes over such values, so a sequence can be planned around them.
+
+Pass `hold: true` to hold that work back. Colours, numbers, the sky, and light keep following the
+position; the nearest theme, the values that switch with it, and mixed artwork wait.
+`getBlend().held` reports whether anything waits. The next request without `hold` brings it in at
+once, so make it while the camera rests:
+
+```ts
+import type {TileflowThemeController} from '@tileflow/core/browser';
+import type {TileflowRuntimeStyle} from '@tileflow/core/runtime';
+
+export async function duskWhileFlying(
+  controller: TileflowThemeController,
+  themes: readonly TileflowRuntimeStyle[],
+  flight: Promise<void>,
+) {
+  // Through the camera move the ground darkens towards night with no layout work.
+  for (const position of [0.25, 0.5, 0.75])
+    await controller.setBlend({hold: true, position, themes});
+  await flight;
+  // The camera rests: labels, icons, and artwork follow at once.
+  await controller.setBlend({position: 0.75, themes});
+}
+```
+
+The React, Vue, and Svelte maps take the same flag in `themeBlend`: pass
+`themeBlend={{hold: true, position, themes}}` while the camera moves and drop `hold` when it rests.
+The React Native `Map` blends natively and does not take `hold`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/core",
-  "version": "0.1.0-alpha.31",
+  "version": "0.1.0-alpha.32",
   "license": "Apache-2.0",
   "description": "Typed Tileflow config and MapLibre style compiler.",
   "type": "module",