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

package/dist/runtime.d.ts

@@ -1 +1 @@
-export { z as TileflowAnalytics, $ as TileflowManifestFetchOptions, a0 as TileflowManifestLoadOptions, a1 as TileflowMapMode, a2 as TileflowMapModeOptions, ae as TileflowResolvedRuntimeTheme, aB as TileflowRuntimeCenterLike, a as TileflowRuntimeColorScheme, T as TileflowRuntimeManifest, aC as TileflowRuntimeManifestMap, b as TileflowRuntimeManifestMapEntry, c as TileflowRuntimeManifestTheme, aD as TileflowRuntimeSource, aE as TileflowRuntimeSourceValidation, aF as TileflowRuntimeStyle, aG as TileflowRuntimeStyleOptions, d as TileflowRuntimeSystemThemes, aH as TileflowRuntimeViewOptions, aI as TileflowSessionController, aJ as TileflowSessionGrantResponse, aM as TileflowStyleFontFace, b4 as TileflowThemeBlendSelection, bb as TileflowThemeSelection, bj as assertValidTileflowRuntimeSource, bk as clearTileflowManifestCache, bm as createTileflowSessionController, bn as createTileflowSessionId, bo as defaultTileflowManifestUrl, bp as defaultTileflowRuntimeView, br as getTileflowAnalyticsApiUrl, bs as getTileflowStyleFontFaces, bt as inferTileflowAnalyticsFromStyleUrl, bu as loadTileflowManifest, bv as mergeTileflowAnalytics, bw as nearestTileflowBlendTheme, bx as normalizeTileflowRuntimeCenter, by as normalizeTileflowStaticImageSize, bW as normalizeTileflowSurfaceId, bz as normalizeTileflowUrl, bA as resolveTileflowAnalyticsRequestUrl, bB as resolveTileflowManifestMap, bC as resolveTileflowMapMode, bD as resolveTileflowRuntimeStyle, bE as resolveTileflowRuntimeTheme, bF as resolveTileflowRuntimeThemeBlend, bG as resolveTileflowRuntimeView, bH as resolveTileflowStaticImageUrl, bI as shouldLoadTileflowManifest, bJ as startTileflowSession, bL as tileflowStyleFontFaceLimits, bM as tileflowStyleFontFacesMetadataKey, bN as tileflowThemeBlendLimits, bQ as validateTileflowRuntimeSource, bR as validateTileflowThemeBlendSelection, bS as validateTileflowThemeSelection } from './manifest-types-CTT2eLbp.js';
+export { z as TileflowAnalytics, $ as TileflowManifestFetchOptions, a0 as TileflowManifestLoadOptions, a1 as TileflowMapMode, a2 as TileflowMapModeOptions, ae as TileflowResolvedRuntimeTheme, aB as TileflowRuntimeCenterLike, a as TileflowRuntimeColorScheme, T as TileflowRuntimeManifest, aC as TileflowRuntimeManifestMap, b as TileflowRuntimeManifestMapEntry, c as TileflowRuntimeManifestTheme, aD as TileflowRuntimeSource, aE as TileflowRuntimeSourceValidation, aF as TileflowRuntimeStyle, aG as TileflowRuntimeStyleOptions, d as TileflowRuntimeSystemThemes, aH as TileflowRuntimeViewOptions, aI as TileflowSessionController, aJ as TileflowSessionGrantResponse, aM as TileflowStyleFontFace, b5 as TileflowThemeBlendSelection, bc as TileflowThemeSelection, bk as assertValidTileflowRuntimeSource, bl as clearTileflowManifestCache, bn as createTileflowSessionController, bo as createTileflowSessionId, bp as defaultTileflowManifestUrl, bq as defaultTileflowRuntimeView, bs as getTileflowAnalyticsApiUrl, bt as getTileflowStyleFontFaces, bu as inferTileflowAnalyticsFromStyleUrl, bv as loadTileflowManifest, bw as mergeTileflowAnalytics, bx as nearestTileflowBlendTheme, by as normalizeTileflowRuntimeCenter, bz as normalizeTileflowStaticImageSize, bX as normalizeTileflowSurfaceId, bA as normalizeTileflowUrl, bB as resolveTileflowAnalyticsRequestUrl, bC as resolveTileflowManifestMap, bD as resolveTileflowMapMode, bE as resolveTileflowRuntimeStyle, bF as resolveTileflowRuntimeTheme, bG as resolveTileflowRuntimeThemeBlend, bH as resolveTileflowRuntimeView, bI as resolveTileflowStaticImageUrl, bJ as shouldLoadTileflowManifest, bK as startTileflowSession, bM as tileflowStyleFontFaceLimits, bN as tileflowStyleFontFacesMetadataKey, bO as tileflowThemeBlendLimits, bR as validateTileflowRuntimeSource, bS as validateTileflowThemeBlendSelection, bT as validateTileflowThemeSelection } from './manifest-types-E7m23eXL.js';

package/docs/authoring-model.md

@@ -173,6 +173,21 @@ const numericIdentity = expr.abs(expr.toNumber(expr.id(), 0));
 const decorativeBucket = expr.modulo(numericIdentity, 7);
 ```
 
+`expr.featureState(name)` reads a value an application sets on one feature at runtime, such as a
+selection or a hover. `expr.globalState(name)` reads a value an application sets once for the whole
+style with MapLibre's `map.setGlobalStateProperty(name, value)`, such as whether anything is
+selected. Both read `null` until set, so wrap them in a typed assertion with a fallback. MapLibre
+applies a global-state change to paint properties at once, without the style's paint transition.
+
+<!-- docs:check -->
+
+```ts
+import {expr} from '@tileflow/core';
+
+const selecting = expr.toBoolean(expr.globalState('selection'), false);
+const captionInk = expr.case([{when: selecting, value: '#1f2a44'}], '#ffffff');
+```
+
 The `land` module exposes stable land-use targets for `cemetery`, `civic`, `commercial`,
 `education`, `government`, `industrial`, `medical`, `military`, `parking`, `railway`,
 `recreation`, and `residential`. Its land-cover taxonomy distinguishes physical cover from authored
@@ -205,10 +220,11 @@ The `vegetation` module binds individual-tree points from the optional OpenMapTi
 extension. Its default `mode: '3d'` emits a portable circle fallback plus metadata for runtimes
 that can upgrade the points to instanced 3D trees. `mode: 'flat'` keeps the MapLibre circles, and
 `flat` exposes the complete `CircleStyle` fallback. `threeDimensional` controls bark color,
-broadleaf and conifer palettes, and independent height and crown scales. The legacy `minZoom`
-shortcut remains available; `flat.minZoom` takes precedence when both are present. The binding
-includes height, crown diameter, genus, leaf type, and species fields so compatible runtimes can
-preserve source measurements and botanical form without hard-coding raw property names. The
+broadleaf and conifer palettes, and independent height and crown scales. `flat.minZoom` sets the
+first zoom with trees. The binding includes height, crown diameter, genus, leaf type, and species
+fields so compatible runtimes can preserve source measurements and botanical form without
+hard-coding raw property names. The module does not draw the unrelated, decorative `canopy` layer;
+render passes can, as in the [canopy grove recipe](data-is-separate-from-design.md). The
 pitched-scene stack follows physical height: pedestrian and transport surfaces, transport markings,
 buildings, then vegetation, so street paint never floats over 3D geometry. Text draws last: road
 names, route shields, junction numbers, and place, water, aerodrome, and POI annotations stay above

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/map-emphasis.md

@@ -0,0 +1,89 @@
+# Map emphasis
+
+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.
+
+An application that draws its own content over a Tileflow map, such as a route, a selected place, or
+search results, often needs the map to step back so that content reads first. Map emphasis does
+that on the map's own MapLibre instance: chosen modules recede towards the map's ground colour, and
+the map's labels and icons fade, except inside an area the application keeps at full strength. The
+change eases in and out, stays when the theme changes, and follows a theme blend.
+
+Emphasis needs a browser document and MapLibre GL JS. It changes only the layers a Tileflow map
+compiled, so an application's own layers, such as the route it draws, keep their appearance.
+
+## Show an emphasis
+
+Create the theme controller for the map, then ask for an emphasis. This example assumes an existing
+MapLibre map named `map` that shows the `dark` theme of a published Tileflow map, and a route the
+application has already drawn:
+
+```ts
+import type {Map as MapLibreMap} from 'maplibre-gl';
+import {createTileflowThemeController} from '@tileflow/core/browser';
+
+export function focusOnRoute(map: MapLibreMap, styleUrl: string) {
+  const controller = createTileflowThemeController({
+    initial: {style: styleUrl, theme: 'dark'},
+    map,
+  });
+  void controller.setEmphasis(
+    {
+      labels: 0.6,
+      recede: {boundaries: 0.55, roads: 0.5, transit: 0.5},
+    },
+    {transition: {duration: 560}},
+  );
+  return () => controller.setEmphasis(undefined, {transition: {duration: 560}});
+}
+```
+
+Roads, transit, and boundaries move halfway or a little more towards the ground colour, labels and
+icons keep 60 % of their opacity, and the change eases in over 560 milliseconds. Calling
+`setEmphasis(undefined)` eases the map back to its design. Each call supersedes the previous one;
+the promise of a superseded call resolves with `status: 'superseded'`.
+
+## Choose what steps back
+
+- `recede` maps module names to an amount from 0 (as designed) to 1 (the ground colour itself). The
+  modules are the semantic domains a map compiles, such as `roads`, `transit`, `boundaries`,
+  `water`, `land`, `buildings`, and `vegetation`. Every colour of a receding layer moves towards the
+  ground colour, including the colours inside zoom curves and data cases. Artwork that cannot be
+  recoloured, such as a pattern, fades by the same amount instead.
+- `labels` is the share of their opacity that the map's labels and icons keep, from 0 to 1.
+- `keep` is a GeoJSON `Polygon` or `MultiPolygon`. Labels and icons whose features fall inside it
+  keep their full strength. It can hold up to 4,096 positions. A corridor round a route is a
+  typical keep area.
+
+The ground colour is the map's background colour. During a blend it is the blended background, so
+receding colours follow the hour as the blend moves.
+
+## How it changes over time
+
+Values that depend only on the camera, such as a colour or an opacity with a zoom curve, ease every
+frame. A value that MapLibre evaluates per feature, such as a road colour chosen by class or any
+label opacity once a keep area is given, would make MapLibre lay its source out again on every
+change. Such values change once, at the start of the change, under a snapshot of the map that fades
+out as the transition runs. When the browser asks for reduced motion, every change happens at once.
+
+An emphasis stays through `setTheme` and `setBlend`: after a new style is applied, the emphasis is
+written again under the same cross-fade, and each blend position recomputes the receded colours.
+
+## How it finds modules
+
+Every compiled layer names its semantic module in its metadata:
+
+```json
+{"id": "tileflow-road-major-fill", "metadata": {"tileflow:domain": "roads"}}
+```
+
+Layers that a theme blend splits or copies keep the same entry. Applications can read the key from
+`tileflowLayerDomainMetadataKey` in `@tileflow/core/browser`. Physical layer IDs remain diagnostic;
+use the module name instead. Styles compiled before this metadata existed have no module names, so
+an emphasis leaves them unchanged.
+
+## Cost
+
+Each eased frame writes only the values that changed, with `setPaintProperty` and without
+validation. For a detailed city map with roads, transit, and boundaries receding, that is about 150
+values a frame on a desktop computer. Writing values directly is faster than reading a MapLibre
+global state from every value, because a global state change re-evaluates every layer that reads it.

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.