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

package/docs/dynamic-style-images.md

@@ -1,100 +0,0 @@
-# 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/globe-atmosphere.md

@@ -1,113 +0,0 @@
-# Globe atmosphere
-
-Enable atmosphere in the map exported by `tileflow.config.ts`. Install `@tileflow/core` and
-`@tileflow/maps` and use a browser adapter from the same compatible SDK release. The example
-extends the complete Streets map, including its data and text resources.
-
-<!-- docs:check -->
-
-```ts
-import {defineMap} from '@tileflow/core';
-import {streets} from '@tileflow/maps';
-
-export default defineMap({
-  id: 'earth',
-  version: 1,
-  extends: streets,
-  projection: 'globe',
-  atmosphere: true,
-  view: {center: [2.3522, 48.8566], zoom: 2},
-});
-```
-
-The result has a pale white rim with a soft blue halo, a muted blue-gray space background, and a
-deterministic field of 1,100 stars per repeating 1,600 × 1,000 CSS-pixel area. The halo follows the
-globe's contour without brightening its surface or adding glow to labels. Stars have a minimum
-radius of 0.6 CSS pixels so the fainter stars remain visible on high-density screens.
-Stars move slightly with the camera. There is no continuous animation while the camera is still.
-The space background, stars, and rim fade between zooms 3 and 6. Native sun scattering is disabled
-when `atmosphere` is enabled, including maps that also declare `sky`. Coordinates are longitude,
-then latitude.
-
-Omit `atmosphere` to inherit it from the base map. A map without inherited atmosphere remains
-unchanged. Set `atmosphere: false` to disable an inherited atmosphere. An enabled atmosphere requires
-`projection: 'globe'`; validation rejects a Mercator or unspecified projection. Atmosphere options
-replace the inherited object atomically rather than merging individual fields.
-
-## Configure appearance
-
-Use an object instead of `true` to override defaults:
-
-| Option          | Default   | Meaning                                                        |
-| --------------- | --------- | -------------------------------------------------------------- |
-| `skyColor`      | `#263b50` | Near-space sky color                                           |
-| `horizonColor`  | `#b6cfe2` | Horizon and outer halo color                                   |
-| `fogColor`      | `#d4e1ec` | Native atmospheric fog color                                   |
-| `spaceColor`    | `#142233` | Outer space background color                                   |
-| `starColor`     | `#e0ebff` | Star color                                                     |
-| `starCount`     | `1100`    | Stars per repeating 1600 × 1000 CSS-pixel area; integer 0–4096 |
-| `starSize`      | `1`       | Radius multiplier from 0 to 4; 0 hides stars                   |
-| `starIntensity` | `0.6`     | Brightness from 0 to 1; 0 hides stars                          |
-| `starParallax`  | `0.4`     | Camera-relative motion from 0 to 1; 0 keeps stars still        |
-
-Colors follow the usual theme contract: use `token.color(...)`, color operations, or
-`fixed(color, {reason})`. They must resolve to opaque colors. Compilation normalizes them to
-six-digit hexadecimal values in the runtime metadata. Numeric options must be finite and within
-the ranges above. `starCount` controls density rather than the total visible count: the field
-repeats on larger viewports. `starSize` scales both the stars and their glow; changing density
-preserves the positions of existing stars. Unknown properties are rejected. For example, this fragment belongs inside `defineMap(...)`
-and uses `fixed` imported from `@tileflow/core`:
-
-```ts
-atmosphere: {
-  horizonColor: fixed('#b6cfe2', {reason: 'Earth atmosphere stays blue across map themes'}),
-  starCount: 650,
-  starSize: 0.8,
-  starColor: fixed('#e0ebff', {reason: 'Cool stars across map themes'}),
-  starIntensity: 0.5,
-  starParallax: 0.25,
-},
-```
-
-The browser's reduced-motion preference overrides parallax while keeping the sky and stars visible.
-No additional image, font, API key, or network request is needed for the effect.
-
-## Browser integration
-
-The compiler emits MapLibre `sky` and versioned `metadata['tileflow:atmosphere']` in every concrete
-style. React, Vue, Svelte, Inspector, and standalone browser capture attach the shared atmosphere
-runtime. Metadata version 2 includes star appearance; the runtime also reads version 1 with
-the established star defaults. Use matching compiler and browser packages for new styles.
-Theme changes update the effect from the newly loaded style. Loading a style without atmosphere
-removes the decoration.
-
-When constructing a MapLibre map directly, call `attachTileflowAtmosphere(map)` from
-`@tileflow/core/browser` after constructing the map. Keep its returned cleanup function and call it
-before removing the map; the map's `remove` event also disposes it. The helper creates its own
-noninteractive, accessibility-hidden canvases for the stars and halo behind the map. A custom layer
-reads the globe projection; the halo stays outside theme snapshots, preserving its appearance
-through time-of-day transitions. It does not create a map, change the camera, filter the map canvas,
-or add controls.
-Preserve the renderer's transparent canvas and standard
-MapLibre CSS so space can show around the globe.
-
-For a camera-driven presentation, the optional second argument can adjust star speed and direction:
-`attachTileflowAtmosphere(map, {starParallaxScale: -5})` moves stars five times as fast in the
-opposite direction. The multiplier must be finite; it defaults to `1`, and `0` freezes the stars.
-This runtime option does not change the compiled style or animate a stationary map. Reduced motion
-still disables star movement, and stopping the camera also stops the stars.
-Use the map's `starParallax` for its authored appearance; reserve `starParallaxScale` for the
-embedding application's camera presentation. The effective motion multiplies both values, so a
-map declaring `starParallax: 0` remains stationary under any runtime multiplier. Inspector preview
-uses the shared atmosphere helper with its default multiplier, just like the framework adapters.
-
-Importing the browser entry is safe during server rendering. Call the attachment only in the
-browser, after mounting. Raw MapLibre consumers must attach the helper to display the globe halo,
-stars, and space background. The compiled sky alone does not include these effects.
-
-A map that also declares a [street sky](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/street-sky.md)
-uses the sky's colors for MapLibre's `sky`; the atmosphere keeps its halo, space background and stars.
-
-The native artifact profile does not support globe atmosphere and rejects `sky`. This browser
-capability does not establish React Native or hosted Static Maps support. Public availability is
-established by the installed package version, not by this repository's main branch.

package/docs/hosted-session-authorization.md

@@ -1,106 +0,0 @@
-# Hosted session authorization
-
-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.
-
-The framework adapters use `createTileflowSessionController` to obtain one short-lived session
-grant before eligible hosted style, tile, font, or sprite requests. Concurrent resources share the
-same preflight, grants are attached only to reviewed HTTP(S) origins, and an expired unused session
-rotates once when the server requests it. A controller also rotates after six hours or 10,000
-eligible requests. The preflight has a 10-second client timeout by default; direct controller users
-can set `grantTimeoutMs` from 1 to 120,000 milliseconds.
-
-`analytics.enabled: false` disables only the optional analytics beacon. It does not disable this
-server-owned commercial authorization. User `transformRequest` callbacks still run first; Tileflow
-then decorates only the resulting eligible URL and preserves the other request options.
-
-Set `analytics.surfaceId` to a stable product location when the same Map appears in several places:
-
-```ts
-const analytics = {surfaceId: 'store-locator'};
-```
-
-A Surface ID is 1–64 lowercase ASCII letters, digits, `.`, `_`, or `-`; it starts and ends with a
-letter or digit. Missing or invalid values become `default`. Use a durable integration name such as
-`checkout` or `dealer-search`, not a URL, branch, preview, random component instance, or user ID.
-Surface labels do not change authorization, entitlement, or Session identity.
-
-For exact Tileflow World release tiles, framework adapters also use the browser request bridge to
-observe the response's safe fair-use state without adding identity, query parameters, credentials,
-or user headers to the public World URL. The bridge requires the immutable release path and exactly
-one lowercase descriptor digest; the retired mutable World template is never intercepted. Early
-`GRACE` stays silent; signed late `GRACE` creates a compact
-accessible owner-action pill, and `MANAGED_REQUIRED` creates a stronger in-map banner. A missing
-header, absent tile, MapLibre error, or failed response cannot erase an existing manage action; a
-later successful `OPEN` response can clear it. Shaped empty tiles remain render-safe while the owner
-action stays available. Successful World tile bodies are streamed with a 16 MiB maximum: an
-oversized `Content-Length` is rejected before reading, and chunked responses are cancelled as soon
-as their accumulated bytes cross the same bound. Abort signals cancel an active reader; errors do
-not include the remote response body.
-
-Other subpaths under `src/`, `themes/`, `templates/`, and `modules/` are internal implementation
-details and can change during alpha releases.
-
-Official map definitions and the source assets they own ship together in `@tileflow/maps`, not in
-Core. That package exports the maps and their reusable directory descriptors:
-
-```ts
-import {
-  baedeker,
-  baedekerFonts,
-  baedekerIcons,
-  blueprint,
-  blueprintIcons,
-  civica,
-  civicaFonts,
-  civicaIcons,
-  map1777,
-  map1777Icons,
-  siegfried,
-  siegfriedFonts,
-  siegfriedIcons,
-  soundings,
-  soundingsIcons,
-  streets,
-  streetsIcons,
-  streetsThemes,
-} from '@tileflow/maps';
-```
-
-All official maps are complete standalone maps. The sole semantic compiler is implicit; none
-imports or extends another official map, and each declares its own icon directory.
-Streets declares `[streetsIcons]` and exposes its complete coordinated appearances as
-`streetsThemes.light` and `streetsThemes.dark`; image tokens select the matching sidewalk pattern
-without changing the asset collection. Baedeker declares `[baedekerIcons]`, whose eight original
-patterns support its travel-atlas design, and `[baedekerFonts]`, its own Cormorant Garamond
-directory; it derives contours in the browser from unpackaged Mapterhorn terrain tiles. Cívica
-declares `[civicaIcons]` for its original civic-print patterns and destination artwork and
-`[civicaFonts]` for its packaged lettering. Blueprint declares
-`[blueprintIcons]` for its four technical hatches and schematic POI node, derives contours from
-unpackaged Mapterhorn tiles, and uses the canonical Noto Sans glyph provider. The same asset
-operation is available to applications:
-
-```ts
-export default defineMap({
-  id: 'brand-map',
-  version: 1,
-  extends: streets,
-  icons: [...streets.icons, './icons'],
-});
-```
-
-`icons` is a `readonly TileflowIconSource[]`. Omission inherits the parent's exact array,
-declaration replaces it atomically, and `[]` means no icons. Local and package directories, plus
-explicit locked `iconSet('@team/set')` descriptors, apply left to right.
-`<id>.<ext>` publishes an icon as `<id>`; `<id>.pattern.<ext>` publishes an intrinsic-size pattern
-as `<id>`. The published ID must already be canonical lower-kebab; a later exact ID wins and a
-case-only collision fails. There is no built-in selector, mutable external sprite selector, icon
-mapping, icon-specific inheritance, additive command, or compatibility alias. An Icon Set is an
-explicit locked descriptor, not a generic source registry.
-
-`@tileflow/dev` resolves local and package directory descriptors, verifies real-path containment,
-and prepares ordinary public artifacts without serializing installation paths. It compiles one
-deterministic sprite from the final icon composition and validates every literal `icon-image`,
-`fill-pattern`, and `line-pattern` in the final style against it. It also prepares any declared font
-directories generically; `baedekerFonts`, `civicaFonts`, and `siegfriedFonts` are
-ordinary package descriptors rather than pipeline special cases. Calling the pure compiler for a map whose style needs unprepared
-assets fails instead of emitting broken runtime references.

package/docs/map-and-terrain-examples.md

@@ -1,156 +0,0 @@
-# Map and terrain examples
-
-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.
-
-Typed Tileflow map contracts, semantic modules, and deterministic MapLibre style compilation.
-
-Every public `tileflow.config.ts` exports one map. Most maps import an existing map and override only
-the design fields they own:
-
-```ts
-import {
-  defineMap,
-  defineTheme,
-  fixed,
-  labels,
-  poi,
-  roads,
-  token,
-  water,
-  zoom,
-} from '@tileflow/core';
-import {streets, streetsThemes} from '@tileflow/maps';
-
-const madridDark = defineTheme(streetsThemes.dark, {
-  id: 'madrid-dark',
-  version: 1,
-  colorScheme: 'dark',
-  tokens: {color: {'surface.land': '#0d1320', 'surface.water': '#081e2e'}},
-});
-
-export default defineMap({
-  id: 'madrid',
-  name: 'Madrid',
-  version: 1,
-  extends: streets,
-  themes: {light: streetsThemes.light, dark: madridDark},
-  defaultTheme: 'light',
-  systemThemes: {light: 'light', dark: 'dark'},
-  projection: 'globe',
-  modules: {
-    water: water({
-      bodies: {
-        fill: {
-          opacity: fixed(0.95, {reason: 'Madrid keeps this water density in every theme'}),
-        },
-      },
-    }),
-    roads: roads({
-      detail: 'streets',
-      hierarchy: 'strong',
-      classes: {
-        primary: {
-          surface: {
-            fill: {
-              color: fixed('#E4A85B', {reason: 'Madrid brand roads stay warm in every theme'}),
-              width: zoom.linear([
-                [7, fixed(0.6, {reason: 'Madrid keeps its primary-road hierarchy across themes'})],
-                [16, fixed(8, {reason: 'Madrid keeps its primary-road hierarchy across themes'})],
-              ]),
-            },
-          },
-        },
-        secondary: {surface: {fill: {color: token.color('roads.secondary')}}},
-      },
-    }),
-    labels: labels({
-      language: 'local',
-      places: 'all',
-      roads: 'streets',
-      styles: {
-        places: {
-          city: {
-            text: {
-              size: fixed(18, {reason: 'Madrid keeps its city-label scale across themes'}),
-              haloWidth: fixed(1.5, {reason: 'Madrid keeps its city-label halo across themes'}),
-            },
-          },
-        },
-      },
-    }),
-    poi: poi({categories: ['food-drink', 'arts-entertainment', 'transport'], color: 'category'}),
-  },
-  view: {center: [-3.7038, 40.4168], pitch: 35, zoom: 12},
-});
-```
-
-Map identity and scenes belong to the leaf and do not inherit. Hosted browser policy is configured
-in Tileflow and does not enter cartographic authoring or compilation.
-
-Set `projection: 'globe'` for MapLibre's adaptive globe preset. Global zooms render as a sphere,
-then transition to Mercator between zoom 10 and 12 so detailed streets remain planar. Omit the
-property, or set it to `'mercator'`, for a consistently flat map.
-
-Terrain keeps the original `'none' | 'hillshade' | '3d'` shorthand. The object form can style every
-MapLibre hillshade paint control. Raster terrain accepts either a TileJSON `url` or explicit `tiles`
-templates, with optional `tileSize` (256 or 512) and native `minZoom`/`maxZoom` limits. The templates
-must contain `{z}`, `{x}` and `{y}` and use HTTPS (HTTP is allowed for loopback development).
-These source limits control DEM requests independently of `hillshade.minZoom`/`maxZoom` visibility;
-the renderer reuses the highest available native resolution for closer views. Select resolution
-limits supported by the provider and retain its required attribution.
-
-Contours generate vector lines in the browser from their own explicit DEM tile template. They
-require `demUrl`, `demMaxZoom`, and zoom-indexed `[minor, index]` `thresholds`; these are separate
-from the raster source's `url` or `tiles`. Set `mode: 'none'` to compile
-contours without adding a raster source, hillshade, or 3D terrain:
-
-```ts
-terrain: {
-  mode: 'none',
-  encoding: 'terrarium',
-  contours: {
-    demUrl: 'https://terrain.example.test/{z}/{x}/{y}.webp',
-    demMaxZoom: 13,
-    maxZoom: 15,
-    overzoom: 2,
-    thresholds: {
-      9: [100, 500],
-      11: [50, 250],
-      13: [20, 100],
-      15: [10, 50],
-    },
-    minor: {
-      color: token.color('terrain.contour.minor'),
-      width: token.number('terrain.contour.minor-width'),
-    },
-    index: {
-      color: token.color('terrain.contour.index'),
-      width: token.number('terrain.contour.index-width'),
-    },
-    labels: {
-      color: token.color('terrain.contour.label'),
-      haloColor: token.color('terrain.contour.halo'),
-    },
-  },
-}
-```
-
-Declare those `terrain.*` color and number roles with the same keys in every map theme. The
-compiled source is ordinary MapLibre vector data with source layer `contours`; its tile URL
-contains the safely encoded DEM template and complete generation parameters. Register the generic
-protocol before MapLibre reads the style. It lazily initializes the pinned, locally bundled
-`maplibre-contour@0.1.0` browser module on the first contour tile; no public CDN runtime is needed.
-`overzoom` may not exceed the lowest threshold zoom, so generated DEM requests never use a negative
-zoom. Every index interval must be a whole multiple of its minor interval. Contour labels emit the
-scaled numeric elevation without assuming a display unit. Source and layer visibility cannot begin
-before the first configured threshold zoom. To bound main-thread work, effective minor intervals
-must be at least 250 units at z0–4, 100 at z5–7, 50 at z8–10, 20 at z11–12, and 10 from z13 onward.
-Use a trusted, size-bounded DEM tile service; the protocol intentionally accepts author-supplied
-HTTP(S) templates rather than proxying or republishing terrain data.
-
-```ts
-import maplibregl from 'maplibre-gl';
-import {registerTileflowContourProtocol} from '@tileflow/core/browser';
-
-registerTileflowContourProtocol({addProtocol: maplibregl.addProtocol});
-```

package/docs/map-emphasis.md

@@ -1,89 +0,0 @@
-# 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.