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

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

@@ -0,0 +1,40 @@
+# Capture scenes
+
+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.
+
+Commit named `scenes` on the singular exported map. A scene implicitly targets that map, so it does
+not repeat a `map` selector. Scene metadata does not inherit and is removed before cartographic
+compilation; it affects visual evidence, not style or manifest identity.
+
+```ts
+import {defineMap} from '@tileflow/core';
+import {streets} from '@tileflow/maps';
+
+export default defineMap({
+  id: 'madrid',
+  name: 'Madrid',
+  version: 1,
+  extends: streets,
+  scenes: {
+    'madrid-desktop': {
+      theme: 'dark',
+      camera: {type: 'center', center: [-3.7038, 40.4168], zoom: 12},
+      viewport: {width: 1280, height: 800, dpr: 1},
+    },
+  },
+});
+```
+
+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;
+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/cartographic-defaults.md

@@ -0,0 +1,210 @@
+# Cartographic defaults
+
+Start with the [Core guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/README.md)
+for installation and a complete map. Semantic modules supply a coordinated starting appearance;
+module styles and owner-local render targets can replace those decisions.
+
+## Roads and roundabouts
+
+`roads({rampOrder: 'below-roads'})` draws ramp fills before receiving carriageways in the same
+surface, bridge or tunnel band. This prevents a rounded ramp endpoint covering the receiving
+road. Choose `'by-class'` to retain class-based fill order instead. Explicit render-stack moves
+remain available; ramp fills have targets `roads.classes.<class>.<structure>.rampFill` when the
+separate ramp order is active. A selector refinement replaces that target's complete filter, so
+retain its ramp eligibility when writing a custom selector. Module class fill styles apply to
+both passes; a refinement of a specific `fill` or `rampFill` target changes only that pass.
+
+Core owns circular-road geometry. Physical inner and outer radii take precedence when provided
+by the source. Otherwise the ring follows the enabled class's effective surface width, including
+width treatments. The default border follows the actual casing width and gap. Hidden classes and
+surface fills do not leave orphan rings. Ring colors remain semantic palette choices, independently
+replaceable through `roundabouts.fill.strokeColor` and `roundabouts.casing.strokeColor`; they do
+not copy arbitrary per-class color curves.
+
+Metric scaling and base-2 width curves retain their native interpolation. Other width curves are
+sampled into the shared geometry curve: numeric widths target 0.1-pixel error, stopping refinement
+once intervals reach 1/32 zoom; very large widths can exceed that target. Feature-dependent width
+expressions retain authored and integer zoom stops without adaptive refinement, keeping expression
+size bounded. Their interpolation between stops is approximate, with no universal pixel-error bound.
+Step changes complete at the authored zoom, with the transition confined to the preceding 0.000001
+zoom interval. Explicit circle radius and stroke-width expressions bypass this sampling when exact
+independent behavior is required.
+
+`roundabouts.fallbackWidth` replaces only the fallback carriageway width in pixels;
+`roundabouts.borderWidth` replaces the total extra width around the ring. Existing circle styles
+can independently replace radius, stroke width, color, opacity and zoom range. For example, this
+module fragment retains geometric defaults but gives rings a deliberate fixed border:
+
+<!-- docs:check -->
+
+```ts
+import {roads} from '@tileflow/core';
+
+export const customRoads = roads({
+  rampOrder: 'by-class',
+  roundabouts: {borderWidth: 0},
+});
+```
+
+## Ground surfaces
+
+The land module draws broad cover and park surfaces before mapped grass, meadow, scrub and
+flowerbed details. Parking, sports pitches, tracks, playgrounds and zoos follow those details so
+they remain visible inside broad green polygons. Both Tileflow World and OpenMapTiles' combined
+park source follow this order. These defaults do not change the map's colors, opacity or textures.
+
+A thematic map can give a park tint more prominence through the existing render stack. This
+module fragment is ready to use as `modules.land` in a map:
+
+<!-- docs:check -->
+
+```ts
+import {land, refineRenderTarget, withRenderStack} from '@tileflow/core';
+
+export const thematicLand = withRenderStack(land(), {
+  parkTint: refineRenderTarget({
+    target: 'land.landcover.urbanPark.fill',
+    placement: 'above-land',
+  }),
+});
+```
+
+Refinements target contributions that the map actually draws. Disabling a target and retaining
+a refinement for it is an authoring error. Disabling the whole module removes its contributions
+and its render stack. The built-in surface order needs no target anchors and works when individual
+surfaces are hidden.
+
+## Street names on the ground or in the foreground
+
+`labels({roadPlacement: 'foreground'})` is the default. Names draw above buildings and vegetation.
+Use `roadPlacement: 'ground'` to draw them above flat building footprints and below raised
+buildings, with text aligned to the map surface. Flat footprints must not clip the glyphs.
+Shields and junction numbers remain in the foreground. Ground placement does not require the
+buildings module: street names still draw when buildings are disabled.
+
+This module fragment keeps the normal language selection and road-class filters while opting
+into ground names. Individual symbol styles can override the default text alignment:
+
+<!-- docs:check -->
+
+```ts
+import {labels} from '@tileflow/core';
+
+export const groundLabels = labels({
+  roadPlacement: 'ground',
+  collisionPriority: 'navigation',
+  language: 'local',
+  roads: 'all',
+  styles: {
+    roads: {
+      primary: {text: {pitchAlignment: 'viewport'}},
+    },
+  },
+});
+```
+
+MapLibre offers foreground symbols first when resolving collisions. Ground names therefore yield
+to POIs and other foreground symbols, even with `collisionPriority: 'navigation'`. Navigation
+priority still orders the ground road classes relative to one another; it does not make their
+collision priority independent of drawing order. Foreground placement retains the existing
+navigation priority over ordinary POIs. Neither mode turns collision detection off.
+
+When compatible road-name layers share a physical bucket, their top-to-bottom collision priority
+and each class's authored feature priority are retained. Overlap-enabled names retain drawing order.
+
+`labels({roadGrouping: 'network'})` instead shares placement and repeated-name suppression across
+compatible classes, in source feature order (or their common authored priority). It retains each
+class's zoom thresholds and size curve. Different fonts, spacing, colors or priorities stay separate,
+as do explicit ordered passes and fractional zoom thresholds. Streets uses this for its ordinary
+roads and a separate pedestrian/path group. The default `'class'` retains road-class priority.
+
+Use a refinement on `labels.roads.<class>` to move an individual class after this default has been
+applied. Symbol size, zoom range, spacing, priority, fonts and halos remain available in
+`styles.roads`. The same names, language fallbacks and class selectors are used in both modes.
+
+## Compact road names
+
+`labels({roadNameFormat: 'compact'})` abbreviates recognized Spanish and French road-type
+prefixes and English suffixes after language selection: `Calle de Alcalá` becomes `C. de Alcalá`,
+`Avenue Paul Doumer` becomes `Av. Paul Doumer`, and `West 34th Street` becomes `W 34th St`.
+The default, `full`, preserves source names. Proper names, unknown types and route shields stay
+unchanged. An explicit `styles.roads.<class>.text.field` takes precedence over this formatting.
+
+## Label density and perspective
+
+The SDK starts with local street names (`labels.roads: 'streets'`), POI density 2 and a
+3-pixel text collision margin. Street names follow enabled road geometry and their zoom thresholds;
+set `roads: 'major'` to retain a map with only arterial names, and `density: 3` for more POIs.
+
+`poi({density: 2, densityByCategory: {landmark: 3, lodging: 1}})` changes category eligibility
+while retaining one importance order across categories. Unspecified categories inherit `density`.
+Each value is 1–5; eligible rank increases by one at z16 and two at `detailZoom` (default 17;
+Streets uses 18). `detailZoom` must exceed 16 and cannot exceed 24. Source rank meanings
+and category coverage differ between datasets, so equal settings need not produce equal counts.
+
+MapLibre owns perspective scaling, distant-symbol rejection, collision placement and fading.
+These native behaviors apply without a module switch. The SDK does not change feature filters
+when panning, rotating, tilting or ending a gesture. Category and zoom eligibility remain compiled
+into the style; explicit application filter edits remain application-owned. The experimental
+`perspective` module option and `attachTileflowLabelPerspective` helper have been removed.
+
+Default POIs place their pictogram and name together, with four alternative text anchors and
+native collision detection. Parking and public toilets retain their icon-only representation.
+Set `placement.coupleIconAndLabel: false` to place pictograms and names independently. Maps refining
+separate `poi.icon` or `poi.label` targets should set this explicitly; coupled POIs use `poi`.
+Explicit anchors, offsets and variable anchors replace the SDK's automatic text clearance.
+
+Balanced foreground priority offers place names and route references first, followed by major
+road names, ordinary POIs, minor road names and house numbers. `collisionPriority: 'navigation'`
+also promotes minor road names above ordinary POIs. `placement.prominentRank` can promote selected
+POI ranks above the orientation labels. Eligibility still depends on zoom, enabled classes and
+source data. Feature priority sorts within a layer; it does not override the order between layers.
+Explicit render-stack placements take precedence over these defaults.
+
+With `roadPlacement: 'ground'`, the browser keeps road names above the 3D scene below 30° pitch,
+so roofs cannot cut letters in narrow streets viewed from above. At 30° and above, names return
+below solid raised geometry. Tileflow trees mount below these names so foliage cannot cut
+individual letters. This policy follows `roadPlacement` alone and does not affect camera tilt.
+Explicit render-stack moves opt a target out of automatic ordering; explicit tree `beforeId`
+placement remains application-owned.
+
+React, Vue, Svelte, preview and standalone capture attach the shared placement controller.
+Applications constructing MapLibre maps directly call `attachTileflowLabelPlacement(map)` from
+`@tileflow/core/browser` once after map construction. The returned function detaches its listeners
+and restores ground ordering; map removal detaches without further map writes. Replacement styles
+and late-mounted 3D layers are discovered automatically. Static style JSON and native renderers
+retain compiled eligibility and hierarchy, but do not execute this browser scene-order controller.
+
+Native perspective rejection is not a configurable per-category distance curve. The SDK does not
+emulate Mapbox's `pitch` or `distance-from-center` symbol filters, which the supported MapLibre
+style specification does not provide. Runtime fade duration and cross-source collisions continue
+to use MapLibre defaults unless overridden through the adapter's `mapOptions`.
+
+## Discover and override decisions
+
+`tileflow describe labels --json` exposes the installed options, and `tileflow inspect --json`
+shows resolved inheritance and merge provenance. `tileflow explain --inspection --json` adds
+compiled semantic targets and physical provenance. These commands describe the authored map;
+they do not rewrite explicit style choices.
+
+`tileflow describe themes --json` lists the twelve required base color roles and composition
+rules. A [single independent theme](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/themes-and-module-styles.md)
+needs no time-of-day catalog. Optional color roles derive from that theme and accept explicit
+replacements. Removing inherited lighting uses `reset()` inside `defineTheme`; it restores the
+SDK fallback, while building shadows and occlusion have separate on/off controls.
+
+`createStyleResult()` and `tileflow inspect compiled --json` include `report.decisions`: actual
+color roles and selected road, label and 3D-building policies, each with its value, source,
+reason and override guidance. Query `--path /report/decisions --limit 80` to bound this output.
+`default` means an SDK fallback, `map` a value in the resolved map, `theme` a role defined by the
+selected theme and `derived` an optional role computed by Core. Use config inspection's merge
+provenance to distinguish inherited map values from leaf overrides. These decisions describe
+module policies and the theme's color context; later module styles and render-stack refinements
+can override them. They are not a trace of every final paint property or a visual-quality score.
+Simple `createStyle()` and browser drawing do not collect this report.
+
+Replace an inherited module with its constructor, patch it with `refine()`, restore an inherited
+value with `reset()`, or remove the whole domain with `disable()`. See the
+[authoring model](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/authoring-model.md)
+for these composition rules. Capture contrasting designs and compare them at matching cameras to
+check both the default result and intentional departures from it.