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

package/docs/authoring-model.md

@@ -0,0 +1,241 @@
+# Authoring model
+
+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.
+
+Tileflow exposes one authoring concept and one constructor: `defineMap()`. A complete map omits
+`extends`; an inherited map sets `extends` to another imported map object. All first-party
+maps are independent standalone maps. They use the sole semantic compiler while defining
+their complete designs and asset providers directly; no official map imports or extends another
+official map. Applications can extend any of those maps through the same public API. Streets
+itself owns coordinated light and dark themes.
+There is no public compiler selector or alternate compiler. The authoring contract has no recipe or
+cartographic compatibility alias.
+
+### Machine-readable language surface
+
+`tileflowAuthoringManifest` is the deterministic, deeply frozen description of the public semantic
+language. Its schema version is `tileflowAuthoringManifestSchemaVersion`. The manifest's `domains`
+array is generated from the compiler's closed registry and records exact compile order, module and
+service dependencies, and provided services. `operations` lists only integrated public operations:
+defining/extending a map, directly replacing, refining, disabling, or resetting a keyed domain,
+and adding owner-local render passes or target refinements. Direct declaration is the sole
+replacement syntax; there is no redundant `set()` helper.
+
+Agents and other tools can discover this contract without importing executable configuration:
+`tileflow language manifest --json` emits the manifest and `tileflow language schema --json` emits
+the packaged generated authoring/resolved JSON Schema. Both commands are deterministic, read-only,
+and network-free. The manifest links every domain to its authoring, options, patch, and resolved
+schema definitions, and enumerates the closed expression and render-selector vocabulary with its
+finite limits.
+
+The manifest also describes the exact structured compiler contract. A successful
+`createStyleResult()` has `{ok: true, diagnostics, report, style}`; a failure has
+`{ok: false, diagnostics, report}` and forbids `style`. Report schema version 1 requires
+`domains`, `map`, `planner`, `schemaVersion`, and sorted semantic `targets`; `theme`, source
+`requirements`, and physical `provenance` are optional. Pass `{inspection: true}` only when the
+read-only physical-output provenance sidecar is needed. Its IDs and indexes are diagnostic
+observations, never stable or addressable authoring targets.
+
+`diffTileflowMaps(before, after)` resolves both inputs before comparing them and returns semantic
+diff schema version 1:
+
+```ts
+{
+  schemaVersion: 1,
+  from: {id, version},
+  to: {id, version},
+  summary: {add, remove, change, total},
+  changes: [
+    {kind: 'add', path: '/projection', after: 'globe'},
+    {kind: 'remove', path: '/modules/water', before: {/* ... */}},
+    {kind: 'change', path: '/view/zoom', before: 12, after: 13},
+  ],
+}
+```
+
+Paths are RFC 6901 JSON Pointers. Object keys compare recursively in code-unit order; arrays compare
+atomically because map inheritance replaces arrays. Leaf identity (`id`, `name`, `version`) and
+delivery metadata identify the endpoints but are not cartographic changes.
+
+Custom build tooling can opt into a separate, read-only diagnostic sidecar from the explicit build
+entrypoint:
+
+```ts
+import {createStyleWithInspection} from '@tileflow/core/build';
+
+const {style, inspection} = createStyleWithInspection(map);
+```
+
+`inspection.layers` stays aligned with the final Style layer order and records the semantic
+`owner`, `slot`, `target`, and ordered render passes/refinements represented by each layer, including
+layers merged by the physical planner. `createStyleFromCatalogWithInspection` and
+`createStylesFromCatalogWithInspection` provide the corresponding catalog-oriented forms. The
+ordinary Style bytes are identical to compilation without inspection; private compiler metadata is
+stripped before finalization, and the sidecar never enters a Style, runtime manifest, or production
+artifact unless a caller deliberately stores it.
+
+Resolution happens before validation, asset preparation, compilation, capture, build, or deploy.
+Only `view` deep-merges (its nested arrays and expressions still replace). The `themes` collection
+replaces atomically when declared and clears an inherited `systemThemes` mapping; omission inherits
+the collection. `defaultTheme` may independently choose one inherited concrete theme, while an
+explicit `systemThemes` replaces the complete light/dark mapping. Every resolved selector must name
+a theme in the final collection.
+`modules` merges by domain name: an omitted domain remains inherited, while declaring `roads(...)`
+or another domain replaces that inherited module request and every compiler-owned contribution
+attached to it as a unit. `data`, `projection`, `terrain`, `marine`, `icons`, and the text provider
+are atomic; identity and tooling metadata are leaf-owned. `disable()` removes the domain and
+its complete inherited render stack. The resolved result is a standalone map with no runtime dependency on
+TypeScript imports.
+
+`icons` is an intentional exception to implicit array composition: omission inherits the exact
+parent array, any declaration replaces it atomically, and `[]` disables map icons. Compose with a
+spread when the child should keep a parent's directories. `fonts` and `glyphs` are mutually
+exclusive text providers; declaring either atomically replaces an inherited provider of either
+kind. Unknown keys and former compatibility shapes are rejected.
+
+Most authors should extend an existing official or application map. A complete standalone map uses
+the same `defineMap()` call without `extends`:
+
+```ts
+import {defineMap} from '@tileflow/core';
+import {streetsIcons, streetsThemes} from '@tileflow/maps';
+
+const companyBase = defineMap({
+  id: 'company-base',
+  name: 'Company base',
+  version: 1,
+  glyphs: {
+    kind: 'url',
+    url: 'https://api.tileflow.dev/base/33d4de5e8086d9d629d67d3f39fedb87e23686c4c1ac653c27e2a52aee9d00b3/glyphs/{fontstack}/{range}.pbf',
+    fontStacks: ['Noto Sans Regular', 'Noto Sans Bold'],
+  },
+  icons: [streetsIcons],
+  themes: {light: streetsThemes.light, dark: streetsThemes.dark},
+  defaultTheme: 'light',
+  systemThemes: {light: 'light', dark: 'dark'},
+});
+
+export default defineMap({
+  id: 'company-navigation',
+  version: 1,
+  extends: companyBase,
+  projection: 'globe',
+});
+```
+
+The standalone map above is complete as written. A map always owns its complete text provider; Core does not
+obtain fonts or sprites from World and never invents a fallback URL. The URL-backed first-party
+`streets`, `ferraris`, `harad`, `soundings`, and `blueprint` maps declare their glyph
+providers directly. `baedeker`, `civica`, and `siegfried`
+declare packaged fonts, so ordinary imports and derived maps compile without out-of-band release
+metadata.
+
+```mermaid
+flowchart LR
+  A["tileflow.config.ts exports one map"] --> B["Resolve imported map lineage"]
+  B --> C["Complete semantic design + closed domain registry"]
+  C --> D["Domain IR + assembly + render stacks"]
+  D --> E["Physical planner"]
+  E --> F["Single MapLibre lowering"]
+  F --> G["Validated Style JSON + compilation report"]
+```
+
+Modules are keyed by domain, so object order never controls rendering and a domain can appear only
+once. A map extending Streets inherits its complete module set. Use `disable()` to remove a domain
+deliberately. The public domains are `land`, `water`, `nautical`, `roads`, `buildings`, `boundaries`,
+`labels`, `poi`, `aeroways`, `transit`, `vegetation`, `addresses`, and `landforms`.
+The closed domain registry is exhaustive over that domain set and owns defaults, dependency order,
+services, and compiler orchestration. Contract tests keep its keys and type tags in lockstep with
+the strict resolved schema, generated authoring/options/patch/resolved schema aliases, and public
+exports. Disabling `roads` also removes dependent road names, shields, and junction references;
+independent place, water, aerodrome, and POI labels remain under the labels module.
+
+Every styling module supports semantic shortcuts and exact semantic targets. Visual style values
+accept typed token refs, documented `fixed(value, {reason})` values, closed data expressions through
+`expr.*` plus `field(...)`, and zoom functions through `zoom.step(...)`, `zoom.linear(...)`, or
+`zoom.exponential(...)`. Refs and fixed leaves also work inside typed expressions and zoom stops.
+Structural controls such as presets, visibility, and zoom gates remain ordinary literals. Exact
+controls address stable concepts such as `roads.classes.primary.surface.fill`, not renderer layer
+IDs.
+
+`expr.id()` reads the source-owned feature identifier: a string, number, or `null` when absent.
+It performs no I/O and does not derive an identifier from geometry. `expr.modulo(dividend, divisor)`
+uses native numeric remainder, including its sign behavior. Normalize input and provide a deliberate
+fallback before using numeric IDs for decorative variation; missing or non-numeric IDs must not
+silently imply distinct features. Identity stability across data releases belongs to the producer.
+
+<!-- docs:check -->
+
+```ts
+import {expr} from '@tileflow/core';
+
+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
+urban green: `farmland`, `flowerbed`, `grass`, `ice`, `meadow`, `protected`,
+`recreationGround`, `rock`, `sand`, `scrub`, `urbanPark`, `villageGreen`, `wetland`, and
+`wood`. The plain `grass` branch excludes every typed grass subclass, so one source feature cannot
+receive two opaque green fills. Parking areas are polygons from the configured land-use source;
+parking access aisles remain road features under `roads.serviceTypes.parkingAisle`. The
+`commercial` target recognizes ordinary `commercial` and `retail` values plus Tileflow's derived
+`business_area` ground class. Its `globalLandcover` fill styles the optional low-zoom global
+land-cover extension without a raw layer patch. The `water.bathymetry` fill does the same for the
+typed Tileflow World V1 depth bands. An explicit `water({bathymetryContours: {}})` traces the
+submerged edges between those discrete polygon bands; it is an approximate visual contour, not a
+surveyed isoline. `water({bathymetryLabels: {}})` separately opts into numeric metre values derived
+from each polygon's absolute minimum band depth. Existing maps gain neither detail by default, and
+sources without bathymetry bindings omit both requested layers. These labels describe coarse band
+floors, not measured survey soundings, and must not be presented as hydrographic sounding data.
+
+`addresses` renders the standard OpenMapTiles `housenumber` points at detailed zooms and exposes a
+single semantic `labels` style. `landforms` renders the standard `mountain_peak` classes (`peak`,
+`volcano`, `saddle`, `ridge`, `cliff`, and `arete`) with rank-aware collision priority and optional
+metric elevation. Both source-layer and field names remain remappable through `openMapTiles(...)`;
+landform names share the language selected by `labels({language: ...})`.
+
+`aeroways.runwayRef` owns high-zoom runway designators from the remappable OpenMapTiles `ref`
+field. Aerodrome names stay under `labels.styles.aerodrome`; `labels.aerodromeCodes` controls whether
+they append no code, IATA only, or IATA with an ICAO fallback (`'none' | 'iata' | 'all'`).
+
+The `vegetation` module binds individual-tree points from the optional OpenMapTiles `tree`
+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
+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
+every ground layer, so building fills, boundaries, and trees cannot cover them.
+`labels.collisionPriority` only orders labels within that final stack.
+
+Render passes, and refinements that move a target their module owns, share one `placement`
+vocabulary. A band edge is `below-` or `above-` one of `land`, `relief`, `water`, `roads`,
+`boundaries`, `buildings`, `vegetation`, and `labels`; it needs no anchor, so a vegetation pass can
+draw `'above-relief'` without depending on another module. `{above: target}` and `{below: target}`
+draw beside one semantic target and inherit its band and, without their own `feature`, its vector
+data; passes placed beside a moved target follow it. Operations sharing a placement paint in
+declaration order, the first lowest. For symbols, a higher layer is also placed first in MapLibre
+collisions, so placement decides both drawing and precedence. An owner whose layers are all
+render passes still satisfies other operations' `requirements`.

package/docs/capture-scenes.md

@@ -0,0 +1,36 @@
+# 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` (`tileflow dev` remains an alias) 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.

package/docs/compiled-style-performance.md

@@ -0,0 +1,263 @@
+# Compiled-style performance
+
+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 semantic compiler resolves semantic modules and their owned contributions first, then compacts equivalent
+physical MapLibre layers. At high-detail zooms, road classes become a small set of data-driven
+cohorts; equivalent road labels and tunnel hatches share compatible buckets; and land-cover,
+land-use, and waterway classes share compatible buckets. Compaction selects
+cohorts from compiler-owned semantic targets, not by parsing physical IDs; its temporary
+owner/slot/target provenance is stripped from the public Style JSON.
+
+After physical planning, Core embeds a bounded private `tileflow:interaction-manifest` lookup for the
+final POI representations. `@tileflow/interactions/maplibre` validates and consumes that metadata
+so applications can bind to `domain: 'poi'` without depending on physical layer IDs. The lookup is
+paired atomically with the exact style it describes; it is not a public style-authoring API.
+
+Use the exported structural sweep to enforce budgets without loading tiles or a browser:
+
+```ts
+import {analyzeTileflowStylePerformance, createStyle} from '@tileflow/core';
+import map from './tileflow.config';
+
+const report = analyzeTileflowStylePerformance(createStyle(map));
+console.log(report.zooms[16]);
+```
+
+The report covers z0–z22 by default and includes active layers, conservative bucket estimates,
+symbols, and active layers per source-layer. It is intended for regression gates; browser traces
+remain the source of truth for decode, upload, placement, and frame time.
+
+A `SymbolStyle` root zoom range governs its text/icon layer and is inherited by its marker layer.
+Because a marker is materialized as a separate circle layer, an explicit marker range may refine
+that inherited default. Text and icon ranges must agree because MapLibre renders them together.
+
+The road module distinguishes the path family semantically:
+
+```ts
+roads({
+  extras: {paths: true},
+  crossings: {image: token.image('roads.crosswalk')},
+  sidewalks: {
+    surface: {color: token.color('roads.city.casing'), minZoom: 17},
+    pattern: {
+      pattern: token.image('roads.sidewalkPattern'),
+      minZoom: 17,
+      opacity: fixed(0.6, {reason: 'Sidewalk texture strength is invariant'}),
+    },
+  },
+  roundabouts: {
+    casing: {strokeColor: token.color('roads.default.casing')},
+    fill: {strokeColor: token.color('roads.default')},
+  },
+  areas: {
+    pedestrian: {
+      fill: {color: token.color('surface.land')},
+      outline: {
+        color: token.color('roads.default.casing'),
+        width: fixed(1, {reason: 'Pedestrian-area outline weight is invariant'}),
+      },
+    },
+  },
+  classes: {
+    primary: {
+      tunnel: {
+        casing: {
+          color: token.color('roads.city.tunnelCasing'),
+          width: fixed(10, {reason: 'Primary-tunnel hierarchy is invariant'}),
+        },
+        fill: {
+          color: token.color('roads.city.tunnel'),
+          width: fixed(8, {reason: 'Primary-tunnel hierarchy is invariant'}),
+        },
+        hatch: {
+          color: token.color('roads.city.tunnelCasing'),
+          opacity: fixed(0.25, {reason: 'Tunnel hatch strength is invariant'}),
+          spacing: fixed(10, {reason: 'Tunnel hatch rhythm is invariant'}),
+        },
+      },
+    },
+    pedestrian: {
+      surface: {
+        fill: {
+          color: token.color('roads.path.transition'),
+          width: fixed(6, {reason: 'Pedestrian-road hierarchy is invariant'}),
+        },
+      },
+    },
+    footway: {
+      surface: {
+        fill: {
+          color: token.color('roads.path'),
+          width: fixed(1.2, {reason: 'Path hierarchy is invariant'}),
+        },
+      },
+    },
+    cycleway: {
+      surface: {
+        fill: {
+          color: token.color('roads.cycleway'),
+          width: fixed(1.5, {reason: 'Cycleway hierarchy is invariant'}),
+        },
+      },
+    },
+    steps: {
+      surface: {
+        fill: {
+          color: token.color('roads.path.casing'),
+          width: fixed(1.4, {reason: 'Step hierarchy is invariant'}),
+        },
+      },
+    },
+    pathway: {
+      surface: {
+        fill: {
+          color: token.color('roads.path'),
+          width: fixed(1.2, {reason: 'Path hierarchy is invariant'}),
+        },
+      },
+    },
+  },
+  modifiers: {
+    expressway: {widthScale: 1.06},
+    ramp: {widthScale: 0.7},
+    unpaved: {surface: {fill: {color: token.color('roads.path')}}},
+    construction: {
+      surface: {
+        fill: {opacity: fixed(0.7, {reason: 'Construction emphasis is invariant'})},
+      },
+    },
+    indoor: {
+      surface: {fill: {opacity: fixed(0.4, {reason: 'Indoor-road emphasis is invariant'})}},
+    },
+  },
+  restrictions: {
+    access: {
+      surface: {fill: {opacity: fixed(0.55, {reason: 'Restricted-road emphasis is invariant'})}},
+    },
+    toll: {
+      surface: {
+        casing: {color: fixed('#C5B7D8', {reason: 'Toll ink is regulatory and invariant'})},
+      },
+    },
+  },
+  serviceTypes: {
+    driveway: {widthScale: 0.75},
+    parkingAisle: {widthScale: 0.6},
+  },
+});
+```
+
+These targets are non-overlapping translations of the OpenMapTiles road class and subclass. The
+same names are available under `labels().roadClasses` and `labels().styles.roads`. Surface, tunnel,
+and bridge phases can be controlled independently for each target; each structure has
+`shadow`/`casing`/`fill` and an optional `hatch`. Glyph hatch marks inherit the resolved fill width
+when `size` is omitted and never participate in label collision. Setting `hatch.pattern` instead
+emits a repeated sprite texture clipped to the resolved fill width. No raw source filter or generated
+layer ID is needed. `hatch.patternWidths` can list intrinsic sprite heights named
+`${pattern}-${width}`; the compiler selects the nearest height from the resolved road width so the
+texture's marks remain approximately constant in screen pixels across classes, ramps, and zooms.
+
+`classes.pedestrian` styles line-like pedestrian ways. Polygon pedestrian plazas are a distinct
+geometry and use `areas.pedestrian`, including optional fill opacity, outline color, or sprite
+pattern. This prevents plazas from degrading into a thin polygon outline.
+
+Road treatments refine a class without creating another class or exposing source fields.
+`construction`, `expressway`, `indoor`, `official`, `ramp`, and `unpaved` live under `modifiers`;
+general, bicycle, foot, horse, and toll restrictions live under `restrictions`; `alley`,
+`crossover`, `driveway`, `parkingAisle`, and `yard` live under `serviceTypes`; and exact
+mountain-bike difficulty values live under `mountainBike`. Treatments reuse
+surface/tunnel/bridge and casing/fill/shadow paint controls, plus a relative `widthScale`. The
+compiler emits feature-driven paint expressions inside the existing stable class layers rather
+than multiplying every possible combination.
+
+Road names, shields, and motorway junctions remain label concerns:
+
+```ts
+labels({
+  roads: 'all',
+  shields: 'major',
+  junctions: true,
+  styles: {
+    shields: {
+      default: {
+        icon: {
+          image: token.image('roads.shield.rectangleNeutral'),
+          optional: false,
+          pitchAlignment: 'viewport',
+          rotationAlignment: 'viewport',
+          textFit: 'width',
+          textFitPadding: [0, 4, 0, 4],
+        },
+        text: {
+          color: token.color('labels.shieldDark'),
+          font: token.font('places'),
+          optional: false,
+          pitchAlignment: 'viewport',
+          rotationAlignment: 'viewport',
+        },
+      },
+      overview: {minZoom: 6, maxZoom: 11, placement: 'point'},
+      detail: {minZoom: 11, placement: 'line', spacing: 400},
+      kinds: {
+        'rectangle-neutral': {image: token.image('roads.shield.rectangleNeutral')},
+        'rectangle-blue': {image: token.image('roads.shield.rectangleBlue')},
+      },
+      textColors: {
+        dark: {color: token.color('labels.shieldDark')},
+        light: {color: token.color('labels.shieldLight')},
+      },
+    },
+    junctions: {
+      text: {
+        color: token.color('labels.strong'),
+        haloColor: token.color('labels.halo'),
+        haloWidth: fixed(2, {reason: 'Junction halo weight is invariant'}),
+      },
+    },
+  },
+});
+```
+
+`icon.textFit` and `icon.textFitPadding` let a symbol background grow with its text. Setting both
+icon and text `optional: false` keeps a route shield atomic during collision placement: neither an
+empty badge nor a detached reference can render alone. `overview` renders producer-selected points
+at low zoom and `detail` switches to line placement at street zooms; exclusive `maxZoom: 11` and
+inclusive `minZoom: 11` make that handoff atomic. Keeping both icon and text aligned to `viewport`
+makes the badge horizontal regardless of road bearing.
+
+`kinds` and `textColors` are closed presentation tables. The vector producer supplies semantic
+`shield_kind`, `shield_text_color`, `shield_text`, and `shield_rank` values; Core only matches them
+against the authored tables and falls back to `default`. Country, route-prefix, and network-shape
+rules therefore stay in the data authority instead of leaking into a map theme or multiplying
+runtime layers.
+
+Tileflow World owns POI classification, editorial zoom eligibility, and cross-source ranking. Its
+canonical `poi` layer exposes `category`, `type`, `icon`, `min_zoom`, `filter_rank`, and `size_rank`;
+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
+integer from 0 through 16 used to order eligible candidates before MapLibre performs final
+collision placement.
+
+The closed category vocabulary is `arts-entertainment`, `education`, `food-drink`, `landmark`,
+`lodging`, `medical`, `park-nature`, `public-services`, `religion`, `retail`, `sport-leisure`,
+`transport`, and `visitor-amenity`. Producer `type` and `icon` values use stable snake_case names.
+When an `icon` sprite exists it is used directly; an unknown or absent icon safely falls back to the
+category's themed image role. `labels` and `icons` are booleans. Category styles control only
+presentation and may hide or delay candidates, never promote them above the producer's selection.
+`placement.coupleIconAndLabel` keeps a POI's icon and label atomic during collision placement.
+
+```ts
+poi({
+  categories: ['food-drink', 'landmark', 'transport'],
+  density: 3,
+  icons: true,
+  labels: true,
+});
+```
+
+The same contract drives regular POI layers, custom HUD treatments, semantic interactions, and
+feature inspection. There is intentionally no compatibility path for the former class mapping,
+rank ceilings, or named density/detail presets.