@tileflow/core 0.1.0-alpha.42 → 0.1.0-alpha.44

package/docs/authoring-model.md

@@ -1,269 +0,0 @@
-# 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. `models`, the directories of a map's own
-3D models, follows the same rule. `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`, `soundings`, and `blueprint` maps declare their glyph
-providers directly. `baedeker`, `civica`, `map1777`, 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 as the results of typed expressions and
-as zoom-stop values; conditions and other operands take plain values, such as `3` rather than
-`fixed(3)` in a rank test inside a colour expression. Structural controls such as presets,
-visibility, text fields, and zoom gates remain ordinary literals. Expression builders take at most
-16 branches, stops, or operands; an error names the received count and the config line of the
-call, and a larger lookup composes nested groups.
-
-Layout properties, such as text fields, text and icon sizes, and symbol placement, are evaluated at
-each tile's integer zoom: a step at zoom 17.5 takes effect at zoom 18. Paint properties follow the
-camera's exact zoom. `createStyleResult()` reports a `TF_LAYOUT_FRACTIONAL_ZOOM_STEP` warning with
-the semantic target for every layout step at a fractional zoom. 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. Its `barriers` draw `hedge`, `fence` and `wall`
-from the data's barrier layer (Tileflow World V1's `traffic_control`) at the top of the land band:
-a `line`, a `shadow` line under it, and an `area` fill for the hedges the data maps as areas.
-Nothing is drawn for a barrier without a style, nor for data without the layer. 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.
-An explicitly selected Bathymetry source can instead declare `vectorLayers.contours: true` to use
-real contour lines and their `depth` values. Its optional named seafloor and water features have
-separate `water.bathymetryLandforms` and `water.bathymetryWaterNames` styles, with the language
-selected by `labels(...)`. See [the marine source contract](data-is-separate-from-design.md#declare-contour-and-name-layers).
-Those name styles can explicitly select placement for each geometry family with
-`placementByGeometry`; omitting it preserves scalar placement.
-
-`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. `flat.minZoom` sets the
-first zoom with trees. The binding includes height, crown diameter, genus, leaf type, and species
-fields so compatible runtimes can preserve source measurements and botanical form without
-hard-coding raw property names. The module does not draw the unrelated, decorative `canopy` layer;
-render passes can, as in the [canopy grove recipe](data-is-separate-from-design.md). The
-pitched-scene stack follows physical height: pedestrian and transport surfaces, transport markings,
-buildings, then vegetation, so street paint never floats over 3D geometry. Text draws last: road
-names, route shields, junction numbers, and place, water, aerodrome, and POI annotations stay above
-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`.
-
-A target exists only in the mode that draws it: buildings draw `buildings.flat.fill` and
-`buildings.flat.outline` in mode `'flat'`, and `buildings.extrusion` in mode `'3d'`. `refine()`
-keeps the inherited render stack, so refining an inherited module's `mode` fails when a pass is
-placed beside, or a refinement targets, the other mode's target; the error names both modes.
-Streets' shadows and its extrusion pass stand beside its flat buildings. To draw native extrusions
-in a map that extends Streets, remove that stack with `refine({mode: '3d', renderStack: reset()})`,
-or declare `buildings({mode: '3d'})` to replace the module.

package/docs/boundary-areas-and-choropleths.md

@@ -1,230 +0,0 @@
-# Boundary areas and choropleths
-
-Tileflow's Boundaries tileset holds administrative and neighbourhood areas worldwide, from
-countries down to districts and neighbourhoods. A map declares it with `boundaryAreas`, and
-`boundaryChoropleth()` colors its areas from an application's values: unemployment by
-municipality, sales by county, election results by district.
-
-Boundaries is a separate product from World. World's border lines stay in the `boundaries` module;
-`boundaryAreas` adds the areas themselves, each with a stable ID and official codes to join data
-to.
-
-## What the tileset contains
-
-The `boundaries` family comes from OpenStreetMap under the
-[Open Database License](https://opendatacommons.org/licenses/odbl/1-0/). Its source carries the
-attribution `© OpenStreetMap contributors`, which MapLibre shows whenever a layer drawn from it is
-on screen. The attribution is fixed by the family and cannot be replaced.
-
-It has two layers, from zoom 0 to 12:
-
-- `boundary_area`: one polygon per area and class. Its outline is the boundary line.
-- `boundary_label`: one point per area and class, with `name` and `name:<language>`.
-
-Polygons carry the properties needed to filter and join them:
-
-| Property      | Content                                                                                                                           |
-| ------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| feature ID    | The area's registry ID. It survives releases while the area exists.                                                               |
-| `class`       | `country`, `dependency`, `region`, `province_or_county`, `municipality`, `district` or `neighbourhood`.                           |
-| `class_tier`  | `primary` for the level that covers a country with that class, otherwise `secondary`.                                             |
-| `admin_level` | OpenStreetMap's `admin_level`.                                                                                                    |
-| `admin_depth` | Depth in the country's administrative chain, from 0 for the country. Neighbourhoods have none.                                    |
-| `ref`         | The official code with its scheme, such as `ES:INE:28079` or `US:GEOID:36061`; otherwise ISO 3166-2, or ISO 3166-1 for countries. |
-| `iso_3166_1`  | The country's ISO 3166-1 alpha-2 code.                                                                                            |
-
-Labels and the release's lookup table also carry `iso_3166_2`, `nuts`, `wikidata` and names.
-
-One area can serve several classes. Berlin, for example, is a region, a district and a
-municipality: the tileset draws it once per class, with the same ID and the `ref` of each class.
-Filter a choropleth by class so that only one of those features is visible.
-
-Each class appears from a fixed zoom: countries and dependencies from 0, regions from 3, provinces
-and counties from 6 (secondary ones from 7), municipalities from 8, districts from 10 and
-neighbourhoods from 11. `tileflowBoundaryAreasV1Schema.classMinzoom` lists them.
-
-## Declare the source
-
-<!-- docs:check -->
-
-```ts
-import {defineMap} from '@tileflow/core';
-import {streets} from '@tileflow/maps';
-
-export default defineMap({
-  id: 'municipal-indicators',
-  version: 1,
-  extends: streets,
-  boundaryAreas: {family: 'boundaries'},
-});
-```
-
-The compiled style gains the vector source `tileflow-boundaries`, which reads
-`https://api.tileflow.dev/tiles/boundaries/tiles.json` (or the same path under the API base URL
-passed to the compiler). `url` replaces it with a compatible TileJSON or a `pmtiles://` archive,
-such as a local copy for offline development; the attribution stays the same. `false` removes
-Boundaries inherited from a parent map.
-
-## Color areas from values in the style
-
-`values` compiles rows into the style. Rows join by `id` (the registry ID), `ref` or `iso_3166_1`,
-the keys the polygons carry. This example colors municipalities in the Community of Madrid by
-their INE code, the code Spanish statistics publish:
-
-<!-- docs:check -->
-
-```ts
-import {boundaryChoropleth, choroplethScale, defineMap} from '@tileflow/core';
-import {streets} from '@tileflow/maps';
-
-// Rows as a statistics office publishes them: an INE municipality code and a rate.
-const unemployment = [
-  {ine: '28079', rate: 9.8},
-  {ine: '28005', rate: 12.4},
-  {ine: '28006', rate: 6.1},
-  {ine: '28058', rate: 13.7},
-];
-
-export default defineMap({
-  id: 'madrid-unemployment',
-  version: 1,
-  extends: streets,
-  boundaryAreas: {family: 'boundaries'},
-  overlays: {
-    unemployment: boundaryChoropleth({
-      id: 'unemployment',
-      classes: ['municipality'],
-      countries: ['ES'],
-      scale: choroplethScale.step('#fef0d9', [
-        [8, '#fdcc8a'],
-        [10, '#fc8d59'],
-        [12, '#d7301f'],
-      ]),
-      missingColor: '#d9d9d9',
-      outline: {color: '#ffffff', width: 0.75},
-      values: {
-        joinBy: 'ref',
-        rows: unemployment.map(({ine, rate}) => ({key: `ES:INE:${ine}`, value: rate})),
-      },
-    }),
-  },
-});
-```
-
-Municipalities under 8 % are pale, those from 12 % dark red, and municipalities without a row
-gray. The overlay adds the layers `unemployment-fill` and `unemployment-outline` below the
-basemap's labels. Their minimum zoom defaults to the first zoom of the selected classes, here 8.
-
-A choropleth accepts these options:
-
-- `classes` (required), `tiers` and `countries` filter the areas;
-- `minzoom` and `maxzoom` limit the zooms;
-- `scale` sets the colors, `missingColor` the color of areas without a value (transparent by
-  default) and `opacity` the fill opacity (0.8 by default);
-- `outline` draws the boundary lines;
-- `placement` positions the layers among the basemap's like any overlay (`below-labels` by
-  default).
-
-## Choose a color scale
-
-`choroplethScale` builds validated scales:
-
-- `step(base, stops)`: `base` below the first threshold, then one color from each threshold on;
-- `linear(stops)`: colors interpolated between stops and clamped beyond them;
-- `categories({value: color})`: one color per string value.
-
-Stops are `[value, color]` pairs in increasing order, at most 64. A numeric scale gives
-`missingColor` to any area whose value is not a number; a category scale gives it to unknown
-categories. `choroplethColorExpression(scale, input, missingColor)` returns the same MapLibre
-expression for any input, for use in layers of your own.
-
-## Update values at run time with feature-state
-
-Omit `values` and the choropleth reads the feature-state key `value` (or `state`). Set it from the
-application with `createBoundaryFeatureState` from `@tileflow/core/browser` and the map instance:
-
-<!-- docs:check -->
-
-```ts
-import {createBoundaryFeatureState, type TileflowFeatureStateMap} from '@tileflow/core/browser';
-
-// A MapLibre map, such as the one `<Map onLoad>` passes in React.
-export function showRates(map: TileflowFeatureStateMap, rates: ReadonlyMap<number, number>) {
-  const state = createBoundaryFeatureState(map);
-  state.set({joinBy: 'id', rows: [...rates].map(([key, value]) => ({key, value}))});
-  return state;
-}
-```
-
-`set` replaces the previous values and removes those no longer present. Values survive a style
-reload, such as a theme change: the controller sets them again once the source is back. `clear`
-removes them, and `dispose` also stops following the map. `labels: true` also sets the values on
-`boundary_label`, for labels styled by value.
-
-Feature-state is keyed by the source's feature ID, the registry ID by default. To key it by
-official code instead, declare `boundaryAreas: {family: 'boundaries', promoteId: 'ref'}` and set
-rows with `joinBy: 'ref'`. A map that promotes `ref` cannot also join values by `id`; compilation
-fails with `TF_BOUNDARY_CHOROPLETH_JOIN`.
-
-In React, `useBoundaryFeatureState(map, values, options)` from `@tileflow/react` keeps
-feature-state equal to `values`; see the
-[React README](https://github.com/tileflow/tileflow-sdk/blob/main/packages/react/README.md). In
-React Native, the `Map` prop `boundaryFeatureState={{values, labels, state}}` does the same with
-the same rows and options; see the
-[React Native README](https://github.com/tileflow/tileflow-sdk/blob/main/packages/react-native/README.md).
-
-## Join by codes the polygons do not carry
-
-Rows keyed by `iso_3166_1` or `ref` need no table: the polygons carry both codes, and a map that
-promotes `ref` can set feature-state by official code directly. Rows keyed by `iso_3166_2`, `nuts`
-or `wikidata`, or keyed by `ref` while feature-state uses registry IDs, go through the release's
-lookup table.
-
-The table is split by class, one gzip CSV per class with one row per area of that class:
-`boundaries-lookup-country.csv.gz`, `boundaries-lookup-region.csv.gz`, and so on for every class.
-The Boundaries TileJSON lists their URLs under `tileflow.boundaries.lookup.classes`, by class, and
-the description of the table under `tileflow.boundaries.lookup.manifest`. Fine classes cover many
-areas worldwide, so join where the data is prepared, on a server or at build time, and send the
-application the joined rows, keyed by `id` or `ref`. Parse a file with `parseBoundaryLookupCsv`;
-`joinBoundaryRows` then re-keys the rows:
-
-<!-- docs:check -->
-
-```ts
-import {readFile} from 'node:fs/promises';
-import {gunzipSync} from 'node:zlib';
-import {createBoundaryLookup, joinBoundaryRows, parseBoundaryLookupCsv} from '@tileflow/core';
-
-// A downloaded `boundaries-lookup-region.csv.gz`, read where the data is prepared.
-export async function regionsByNuts(lookupFile: string, rows: {nuts: string; value: number}[]) {
-  const text = gunzipSync(await readFile(lookupFile)).toString('utf8');
-  const lookup = createBoundaryLookup(parseBoundaryLookupCsv(text));
-  const joined = joinBoundaryRows(
-    rows.map(({nuts, value}) => ({key: nuts, value})),
-    {joinBy: 'nuts', lookup, classes: ['region']},
-  );
-  if (joined.unmatched.length > 0) console.warn('Unmatched NUTS codes', joined.unmatched);
-  return joined;
-}
-```
-
-Rows from several classes join against one lookup built from the rows of each class file. Lookup
-downloads are web delivery, counted like stored tiles; a native app does not download them.
-
-The result has the same `{joinBy, rows}` shape that `values` and `set` accept, keyed by `id` or,
-with `to: 'ref'`, by `ref`. It also lists the keys it could not use:
-
-- `unmatched`: keys no area has;
-- `ambiguous`: keys shared by more than one area, which are left out;
-- `duplicates`: keys repeated in the rows, where the last row wins.
-
-ISO 3166, NUTS and Wikidata codes are compared upper-cased; `ref` is compared as written, so a
-customer's bare INE code needs its `ES:INE:` prefix.
-
-## Limits
-
-- Values compiled into the style grow it with every row. Use feature-state for large or changing
-  data.
-- The `boundaries-official` family, with one official source per country and level, is not yet
-  available.
-- Tile URLs and the lookup table do not establish redistribution rights beyond the ODbL.