@tileflow/core 0.1.0-alpha.24 → 0.1.0-alpha.25

package/dist/native.d.ts

@@ -0,0 +1,31 @@
+/** URL resolution for native clients, without a renderer or an ambient application origin. */
+declare const tileflowNativeUrlLimits: Readonly<{
+    maximumLength: 2048;
+}>;
+type TileflowNativeNetworkOptions = {
+    /** An exact HTTP development origin; never inferred from the device or environment. */
+    developmentOrigin?: string;
+};
+type TileflowNativeResourceUrlOptions = TileflowNativeNetworkOptions & {
+    /** The absolute URL of the document declaring this resource, after any approved redirects. */
+    documentUrl: string;
+    /** Preserve supported placeholders in the path or query, without expanding them. */
+    template?: 'tile' | 'glyphs';
+};
+type TileflowNativeUrlErrorCode = 'NATIVE_URL_INVALID' | 'NATIVE_URL_ABSOLUTE_REQUIRED' | 'NATIVE_URL_HTTPS_REQUIRED' | 'NATIVE_URL_DEVELOPMENT_ORIGIN_INVALID' | 'NATIVE_URL_TEMPLATE_INVALID';
+type TileflowNativeUrlField = 'manifestUrl' | 'documentUrl' | 'resourceUrl' | 'developmentOrigin';
+/** Safe to report without exposing URL credentials, query parameters or filesystem paths. */
+declare class TileflowNativeUrlError extends TypeError {
+    readonly code: TileflowNativeUrlErrorCode;
+    readonly field: TileflowNativeUrlField;
+    constructor(code: TileflowNativeUrlErrorCode, field: TileflowNativeUrlField);
+}
+/** Resolve a native manifest URL. There is intentionally no browser-relative default. */
+declare function resolveTileflowNativeManifestUrl(value: unknown, options?: TileflowNativeNetworkOptions): string;
+/**
+ * Resolve a resource against its owning manifest, style or TileJSON document.
+ * This checks URL policy only: it neither fetches resources nor authorizes requests.
+ */
+declare function resolveTileflowNativeResourceUrl(value: unknown, options: TileflowNativeResourceUrlOptions): string;
+
+export { type TileflowNativeNetworkOptions, type TileflowNativeResourceUrlOptions, TileflowNativeUrlError, type TileflowNativeUrlErrorCode, type TileflowNativeUrlField, resolveTileflowNativeManifestUrl, resolveTileflowNativeResourceUrl, tileflowNativeUrlLimits };

package/dist/native.js

@@ -0,0 +1,143 @@
+// src/native.ts
+var tileflowNativeUrlLimits = Object.freeze({ maximumLength: 2048 });
+var errorMessages = {
+  NATIVE_URL_INVALID: "Expected a bounded HTTP(S) URL without credentials, fragments or backslashes.",
+  NATIVE_URL_ABSOLUTE_REQUIRED: "An explicit absolute HTTP(S) document URL is required.",
+  NATIVE_URL_HTTPS_REQUIRED: "HTTP is allowed only at the explicitly configured development origin.",
+  NATIVE_URL_DEVELOPMENT_ORIGIN_INVALID: "Expected one HTTP origin without a path, credentials, query or fragment.",
+  NATIVE_URL_TEMPLATE_INVALID: "Expected supported URL placeholders in the resource path or query only."
+};
+var TileflowNativeUrlError = class extends TypeError {
+  code;
+  field;
+  constructor(code, field) {
+    super(errorMessages[code]);
+    this.name = "TileflowNativeUrlError";
+    this.code = code;
+    this.field = field;
+  }
+};
+var tilePlaceholders = /* @__PURE__ */ new Set(["z", "x", "y", "ratio", "quadkey", "bbox-epsg-3857", "prefix"]);
+var glyphPlaceholders = /* @__PURE__ */ new Set(["fontstack", "range"]);
+var absoluteHttpPattern = /^https?:\/\/[^/?#]+/iu;
+var schemePattern = /^[a-z][a-z\d+.-]*:/iu;
+function resolveTileflowNativeManifestUrl(value, options = {}) {
+  assertOptionsObject(options, "developmentOrigin");
+  const developmentOrigin = resolveDevelopmentOrigin(options.developmentOrigin);
+  return resolveDocumentUrl(value, "manifestUrl", developmentOrigin).href;
+}
+function resolveTileflowNativeResourceUrl(value, options) {
+  assertOptionsObject(options, "documentUrl");
+  const developmentOrigin = resolveDevelopmentOrigin(options.developmentOrigin);
+  const document = resolveDocumentUrl(options.documentUrl, "documentUrl", developmentOrigin);
+  assertUrlText(value, "resourceUrl");
+  if (options.template !== void 0 && options.template !== "tile" && options.template !== "glyphs") {
+    throw new TileflowNativeUrlError("NATIVE_URL_TEMPLATE_INVALID", "resourceUrl");
+  }
+  assertReferenceSyntax(value, "resourceUrl", false);
+  const authority = absoluteHttpPattern.exec(value)?.[0];
+  if (authority && /[{}]/u.test(authority)) {
+    throw new TileflowNativeUrlError("NATIVE_URL_TEMPLATE_INVALID", "resourceUrl");
+  }
+  let prefix = "__tileflow_native_template_";
+  while (value.includes(prefix) || document.href.includes(prefix)) prefix += "_";
+  const placeholders = [];
+  const allowed = options.template === "tile" ? tilePlaceholders : glyphPlaceholders;
+  const protectedValue = value.replace(/\{([^{}]*)\}/gu, (placeholder, name) => {
+    if (!options.template || !allowed.has(name)) {
+      throw new TileflowNativeUrlError("NATIVE_URL_TEMPLATE_INVALID", "resourceUrl");
+    }
+    placeholders.push(placeholder);
+    return `${prefix}${placeholders.length - 1}__`;
+  });
+  if (/[{}]/u.test(protectedValue)) {
+    throw new TileflowNativeUrlError("NATIVE_URL_TEMPLATE_INVALID", "resourceUrl");
+  }
+  const resolved = parseUrl(protectedValue, "resourceUrl", document.href);
+  assertTransport(resolved, "resourceUrl", developmentOrigin);
+  const resourcePath = resolved.href.slice(resolved.origin.length);
+  const suffix = resourcePath.replace(
+    new RegExp(`${prefix}(\\d+)__`, "gu"),
+    (match, index) => placeholders[Number(index)] ?? match
+  );
+  const result = resolved.origin + suffix;
+  assertUrlText(result, "resourceUrl");
+  return result;
+}
+function assertOptionsObject(value, field) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new TileflowNativeUrlError(
+      field === "documentUrl" ? "NATIVE_URL_INVALID" : "NATIVE_URL_DEVELOPMENT_ORIGIN_INVALID",
+      field
+    );
+  }
+}
+function resolveDevelopmentOrigin(value) {
+  if (value === void 0) return void 0;
+  try {
+    assertUrlText(value, "developmentOrigin");
+    const match = /^(http:\/\/[^/?#]+)\/?$/iu.exec(value);
+    if (!match || /[{}@*]/u.test(value)) throw new Error();
+    const url = parseUrl(value, "developmentOrigin");
+    if (url.protocol !== "http:" || url.pathname !== "/" || url.search || url.hash || url.hostname.includes("*")) {
+      throw new Error();
+    }
+    return url.origin;
+  } catch {
+    throw new TileflowNativeUrlError("NATIVE_URL_DEVELOPMENT_ORIGIN_INVALID", "developmentOrigin");
+  }
+}
+function resolveDocumentUrl(value, field, developmentOrigin) {
+  assertUrlText(value, field);
+  assertReferenceSyntax(value, field, true);
+  if (/[{}]/u.test(value)) throw new TileflowNativeUrlError("NATIVE_URL_TEMPLATE_INVALID", field);
+  const url = parseUrl(value, field);
+  assertTransport(url, field, developmentOrigin);
+  assertUrlText(url.href, field);
+  return url;
+}
+function assertUrlText(value, field) {
+  if (typeof value !== "string" || value.length === 0 || value.length > tileflowNativeUrlLimits.maximumLength || value !== value.trim() || /[\p{Cc}\\#]/u.test(value) || /%(?![\da-f]{2})/iu.test(value)) {
+    throw new TileflowNativeUrlError("NATIVE_URL_INVALID", field);
+  }
+}
+function assertReferenceSyntax(value, field, absolute) {
+  if (value.startsWith("//")) {
+    throw new TileflowNativeUrlError(
+      absolute ? "NATIVE_URL_ABSOLUTE_REQUIRED" : "NATIVE_URL_INVALID",
+      field
+    );
+  }
+  const authority = absoluteHttpPattern.exec(value)?.[0];
+  if (schemePattern.test(value) && !authority) {
+    throw new TileflowNativeUrlError("NATIVE_URL_INVALID", field);
+  }
+  if (absolute && !authority) {
+    throw new TileflowNativeUrlError("NATIVE_URL_ABSOLUTE_REQUIRED", field);
+  }
+  if (authority?.includes("@")) throw new TileflowNativeUrlError("NATIVE_URL_INVALID", field);
+}
+function parseUrl(value, field, base) {
+  let url;
+  try {
+    url = base === void 0 ? new URL(value) : new URL(value, base);
+    if (!url.hostname || url.username || url.password || url.hash) throw new Error();
+  } catch {
+    throw new TileflowNativeUrlError("NATIVE_URL_INVALID", field);
+  }
+  if (/[{}]/u.test(url.hostname)) {
+    throw new TileflowNativeUrlError("NATIVE_URL_TEMPLATE_INVALID", field);
+  }
+  return url;
+}
+function assertTransport(url, field, developmentOrigin) {
+  if (url.protocol === "https:") return;
+  if (url.protocol === "http:" && url.origin === developmentOrigin) return;
+  throw new TileflowNativeUrlError("NATIVE_URL_HTTPS_REQUIRED", field);
+}
+export {
+  TileflowNativeUrlError,
+  resolveTileflowNativeManifestUrl,
+  resolveTileflowNativeResourceUrl,
+  tileflowNativeUrlLimits
+};

package/docs/authoring-model.md

@@ -0,0 +1,198 @@
+# 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 ten 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/fonts/{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`, `verdant`, and `sanFrancisto` maps declare their glyph
+providers directly, while `baedeker`, `siegfried`, `cyberpunk`, and `matrix` 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.
+
+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
+and road names, buildings, then vegetation. Place, water, aerodrome, and POI annotations remain
+last so geographic names stay readable without making street paint or text float over 3D geometry.

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.