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

package/docs/data-is-separate-from-design.md

@@ -1,610 +0,0 @@
-# Data is separate from design
-
-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.
-
-Team data uses named logical sources and validated MapLibre overlays. The hosted identity never
-contains a CDN URL; `local` is the explicit account-free PMTiles resolution for Dev and Capture:
-
-```ts
-import {defineMap, hostedTileset, maplibreOverlay} from '@tileflow/core';
-import {streets} from '@tileflow/maps';
-
-const stores = hostedTileset({
-  tileset: 'stores',
-  local: './data/stores.pmtiles',
-  attribution: 'Store data © Example',
-});
-
-export default defineMap({
-  id: 'store-locator',
-  version: 1,
-  extends: streets,
-  sources: {stores},
-  overlays: {
-    stores: maplibreOverlay({
-      source: 'stores',
-      placement: 'above-roads',
-      layers: [
-        {
-          id: 'stores-points',
-          type: 'circle',
-          'source-layer': 'store_locations',
-          paint: {
-            'circle-color': ['match', ['get', 'category'], 'restaurant', '#ef4444', '#64748b'],
-          },
-        },
-      ],
-    }),
-  },
-});
-```
-
-Tileflow automatically registers only protocols in namespaces that Tileflow owns.
-`tileflow-pmtiles://` is reserved for PMTiles resources managed by Tileflow. Tileflow never
-automatically registers, removes, or replaces the global `pmtiles://` handler. Explicit PMTiles
-sources supplied by an application remain the application's responsibility.
-
-For local resolution, the Style URL is based on the logical tileset ID and remains stable when Dev
-creates a new immutable snapshot. Physical generation IDs and local content hashes never enter the
-Style representation. Each Dev PMTiles request retains the snapshot it resolved until its response
-is prepared, and strong generation ETags prevent one cached PMTiles read from silently combining
-ranges from different generations. Standalone Capture retains one snapshot for its complete render.
-Application Capture does not freeze every local dataset across the complete screenshot window; the
-application's development server remains authoritative for its per-read generation.
-
-`local` does not make build output own or publish the archive. Production builds reject unresolved
-local PMTiles. Explicitly publish the tileset through Tileflow's managed upload, validation,
-versioning, and hosting flow, or serve it from infrastructure owned by the application.
-
-One overlay owns one ordered group of ordinary MapLibre Style Layers. Public layer IDs are retained
-for `map.on(...)`, feature queries, and application state. Placement is one of `above-water`,
-`below-roads`, `above-roads`, `above-buildings`, `below-labels`, or `above-labels`; overlays sharing
-a placement sort by overlay ID. A map accepts up to 16 Team sources in addition to Tileflow World
-and terrain. These semantic boundaries do not expose generated basemap layer IDs.
-`sources` and `overlays` merge by key through `extends`, declarations replace atomically, and
-`remove()` deletes one inherited key. Removing a still-used source fails validation. There is no
-interaction DSL or parallel expression language.
-
-Omitting `data` selects the compiler-owned Tileflow World `v1` compatibility generation:
-
-```ts
-import {streets} from '@tileflow/maps';
-
-export default streets;
-```
-
-Theme typography can set `fallbacks`, `letterSpacing`, and `transform` globally or per label
-domain, while the font token catalog gives module styles a stable semantic target. Text delivery is
-explicit and atomic: a map may declare either ordered `fonts` directories
-for browser font files or a `glyphs` provider for PBF glyphs, never both. Omitting both inherits the
-parent's provider; declaring either replaces an inherited provider of either kind. After resolution,
-a map that emits text must have exactly one provider. A text-free standalone map may omit both. On a derived
-map, omission inherits the parent provider while `fonts: []` explicitly removes it; that empty array
-is valid only when the resolved map emits no text.
-
-```ts
-import {defineMap, defineTheme} from '@tileflow/core';
-import {streets, streetsThemes} from '@tileflow/maps';
-
-const brandLight = defineTheme(streetsThemes.light, {
-  id: 'brand-light',
-  version: 1,
-  colorScheme: 'light',
-  tokens: {font: {default: 'Brand Sans Regular', places: 'Brand Sans Regular'}},
-});
-const brandDark = defineTheme(streetsThemes.dark, {
-  id: 'brand-dark',
-  version: 1,
-  colorScheme: 'dark',
-  tokens: {font: {default: 'Brand Sans Regular', places: 'Brand Sans Regular'}},
-});
-
-export default defineMap({
-  id: 'brand-map',
-  version: 1,
-  extends: streets,
-  fonts: ['./fonts'],
-  themes: {light: brandLight, dark: brandDark},
-  defaultTheme: 'light',
-  systemThemes: {light: 'light', dark: 'dark'},
-});
-```
-
-Node preparation reads TTF, OTF, and WOFF2 files, uses each OpenType full name as its exact
-`text-font` ID, and requires `LICENSE.txt` in every contributing directory. Directories apply left
-to right; a later exact name replaces an earlier face and case-only collisions fail. Only primary
-faces used by the final style become content-addressed assets and strict `tileflow:fontFaces`
-metadata. `font` names an exact OpenType full name or glyph face; local `fallbacks` name exact faces
-or explicit CSS generic families. Tileflow never appends a weight suffix or derives one face from
-another; the only derived stacks are line-fitted text backgrounds on a `glyphs` provider, which keep
-their source faces' shapes. Browser adapters load local faces before MapLibre. Native releases use a locked PBF
-`glyphs` URL provider instead, which enumerates the exact comma-joined MapLibre request keys in
-`fontStacks`.
-
-Streets, Soundings, and Blueprint each declare
-`https://api.tileflow.dev/base/33d4de5e8086d9d629d67d3f39fedb87e23686c4c1ac653c27e2a52aee9d00b3/glyphs/{fontstack}/{range}.pbf`
-with the exact `Noto Sans Regular` and `Noto Sans Bold` stacks. The full hash identifies one
-published, immutable glyph collection independent of World data. The older `/fonts/...` endpoint
-remains a mutable compatibility URL and does not make a resolved map byte-reproducible. The global
-glyph `assetSetSha256` is not the same-domain value as the per-map `assetSetSha256` in
-`build-manifest.json`.
-Baedeker, 1777, and Siegfried each own a packaged directory containing Cormorant Garamond Regular, SemiBold, and Italic.
-
-Name the official generation deliberately, or use another OpenMapTiles-compatible vector source:
-
-```ts
-import {openMapTiles, tileflowWorld, vectorTiles} from '@tileflow/core';
-
-const official = tileflowWorld();
-const external = vectorTiles({
-  tiles: ['pmtiles://./test/fixtures/world.pmtiles'],
-  revision: 'fixture-1',
-  attribution: '© Example © OpenStreetMap contributors',
-  schema: openMapTiles(),
-});
-```
-
-The resolved map controls how data is drawn; `data` controls where compatible features come from.
-For Tileflow World, the compiler emits the selector TileJSON URL
-`https://api.tileflow.dev/tiles/world/tiles.json`. Omitted data or `tileflowWorld()` selects
-`world-v1/current`; `tileflowWorld({release: {releaseId, descriptorSha256}})` binds an exact release
-through query parameters. Runtime and capture resolve `current` once per session or job and then
-use the immutable release described by that response. `openMapTiles({layers, fields})` can bind renamed
-source-layers or properties while preserving the versioned semantic contract. External browser
-credentials do not belong in public Style JSON; supply them through the framework's
-`transformRequest` integration.
-
-External exact-test sources may use one TileJSON `url` or a bounded direct `tiles` list with optional
-`bounds`, `minzoom`, and `maxzoom`. `pmtiles://` is supported for a checked-in or bring-your-own
-archive. Public vector URLs are HTTPS, root-relative, or HTTP only on loopback development hosts.
-A PMTiles URL names one `.pmtiles` archive through an HTTPS, loopback HTTP, root-relative, or safe
-repository-relative target; credentials, fragments, traversal, and other protocols are rejected at
-both authoring validation and compilation. An external `revision` participates in capture identity,
-so changing fixture bytes cannot silently reuse a baseline.
-
-Tileflow's OpenMapTiles contract also recognizes the optional `globallandcover` extension. The
-official Streets map maps its `barren`, `crop`, `grass`, `shrub`, `snow`, `trees`, and
-`urban` classes beneath the OSM land layers. Tileflow World V1 supplies native generalized
-geometry through z10; Streets fades it progressively while detailed `landcover`/`landuse` gains
-opacity and removes it at z11. This is a macro bridge, not local semantic detail. Sources with a
-different layer name can use `openMapTiles({layers: {globalLandcover: 'my_landcover'}})`; archives
-without the extension remain compatible and simply render no features for that style layer. Use
-`land({globalLandcover: {...}})` to customize its fill, opacity, visibility, and zoom range. `crop`
-shares the theme's semantic `landcover.farmland` color with detailed farmland, while `barren` uses
-`landcover.rock`; neither class borrows a road color.
-
-The normalized schema also records the meaning of the OpenMapTiles `park` layer. Generic
-`openMapTiles()` defaults to `semantics.parkLayer: 'mixed'` and compiles a private compatibility
-branch for ordinary legacy parks. `tileflowWorldV1Schema()` fixes it to `'protected-only'`: that
-layer is a protection tint, while urban parks and gardens come from
-`landcover.class=grass/subclass=park|garden`. The ambiguous legacy `park` class is therefore not
-a public land-cover target.
-
-Tileflow World V1 makes `bathymetry`, `globallandcover`, `circular_feature`, `sidewalk`,
-`street_furniture`, and `transportation_outline` mandatory. Use `tileflowWorldV1Schema()` for that product instead of making raw
-layer names part of a style. Publication tooling calls `validateTileflowWorldV1Tilejson(...)` and
-fails closed unless each layer occurs exactly once, declares its contracted native zooms, and
-advertises the typed fields consumed by the maps. This includes bathymetry z0–z9, global land cover
-z0–z10, the three detailed-city layers at native z15, and numeric
-`transportation.clearance_extra_px_z15` for butt-capping procedural-roundabout approaches. Generic
-OpenMapTiles sources keep the detailed extensions optional and the compiler omits unsupported
-detail. Resolving omitted data or
-`tileflowWorld(...)` uses the strict V1 schema directly, and `water({bathymetry: {...}})` styles the
-emitted depth bands without raw layer IDs. Use `water({bathymetryContours: {...}})` to customize the
-opt-in companion line layer; an empty style selects subtle defaults, and the zero-depth band is
-excluded so the ordinary coastline remains authoritative. The lines follow discrete band polygon
-edges and are therefore approximate rather than surveyed depth contours. Use
-`water({bathymetryLabels: {...}})` to customize the separate opt-in symbol layer; an empty style
-selects the defaults, whose text is the absolute band-minimum number in metres with no unit suffix.
-It remains a band-floor annotation, not a survey sounding.
-
-For independent ocean products, `marine` composes stable auxiliary vector sources without changing
-the primary World source:
-
-```ts
-import {bathymetry, defineMap, fixed, nautical} from '@tileflow/core';
-import {streets} from '@tileflow/maps';
-
-export default defineMap({
-  id: 'chart',
-  version: 1,
-  extends: streets,
-  marine: 'chart', // 'none' | 'bathymetry' | 'nautical' | 'chart'
-  modules: {
-    nautical: nautical({
-      buoys: {minZoom: 12},
-      lights: {minZoom: 9},
-      navigationAreas: {
-        fill: {opacity: fixed(0.05, {reason: 'Chart navigation-area wash is invariant'})},
-      },
-      reefs: {fill: {opacity: fixed(0.3, {reason: 'Chart reef wash is invariant'})}},
-      labels: {navigationAreas: {minZoom: 12}},
-    }),
-  },
-});
-```
-
-`bathymetry` resolves to vector source `tileflow-bathymetry` and supplies the 13-stop
-`bathymetry-v1` band contract to `water(...)`. `nautical` resolves to `tileflow-nautical` at
-`/tiles/nautical/tiles.json`; the `nautical(...)` module draws its `nautical-v1` buoys, beacons,
-lighthouses, lights, hazards, wrecks, reefs, navigation areas, routes, cables, harbours, ports, and
-a restrained coverage indication. `chart` enables both. Every map that draws Nautical declares a
-"Not for navigation" notice, which the browser runtimes render on the map. The
-[Nautical marks guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/nautical-marks.md)
-describes the schema, the semantic groups, the theme image tokens, and the notice.
-Core does not hard-code a nautical provider or attribution: the selected TileJSON owns its actual
-coverage and attribution, and derived vector tiles are not represented as a certified ENC for
-navigation. Point symbols and polygon areas compile separately, without fabricated centroids.
-Advanced callers can override either TileJSON URL, attribution, or source ID and can set the other
-member to `false`:
-
-```ts
-marine: {
-  bathymetry: {url: 'https://tiles.example.test/depth/tiles.json'},
-  nautical: false,
-}
-```
-
-Use the `bathymetry(...)` helper when the map needs relief or product-level styling. Bathymetry is
-one logical product with two independently loaded physical sources:
-
-```ts
-marine: {
-  bathymetry: bathymetry({
-    display: 'hybrid',
-    bands: {
-      opacity: fixed(0.72, {reason: 'Keep chart symbols above the depth wash'}),
-    },
-    contours: {visible: true},
-    relief: {
-      multidirectional: true,
-      opacity: fixed(0.18, {reason: 'Relief stays legible beneath bands and labels'}),
-    },
-  }),
-  nautical: false,
-}
-```
-
-`display: 'bands'` loads only vector TileJSON `/tiles/bathymetry/tiles.json` as
-`tileflow-bathymetry`. `display: 'relief'` loads only `/tiles/bathymetry/dem/tiles.json` as
-`tileflow-bathymetry-dem` and emits continuous `color-relief` plus hillshade. `display: 'hybrid'`
-loads both. The hosted DEM contract is 512 px, Terrarium-encoded, lossless WebP; advanced compatible
-sources may override `url`, `sourceId`, `encoding`, or `tileSize` inside `relief`.
-Multidirectional illumination uses directions 270°, 315°, 0°, and 45°. The simple
-`marine: 'chart'` shorthand deliberately stays vector-only; DEM relief is an explicit advanced
-opt-in.
-
-The vector palette uses thresholds −11 000, −8 000, −6 000, −4 000, −2 000, −1 000, −500, −200,
-−100, −50, −20, −10, and 0 metres. `bands`, `contours`, and `labels` remain separate controls.
-Without an optional-layer declaration, contours and depth labels retain the legacy polygon-band
-behavior. `marine` shorthands and existing maps keep that behavior.
-
-### Declare contour and name layers
-
-For a compatible source, `vectorLayers` explicitly declares optional layers. Core never fetches
-TileJSON to detect them and never substitutes polygon edges for declared contour lines. A missing
-declared layer therefore draws no features; validate the selected dataset before rendering.
-`display: 'bands'` or `'hybrid'` loads the vector source.
-
-| Declaration                             | Source layer         | Geometry and fields                                                                                                 |
-| --------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `contours: true`                        | `bathymetry_contour` | Lines with numeric `depth`, negative metres below the source vertical datum. Zero and positive depths are excluded. |
-| `landforms: true` or a range inventory  | `seafloor_landform`  | Named points, lines, or polygons with stable source `id`, provider `class`, and `name`.                             |
-| `waterNames: true` or a range inventory | `water_name`         | Named points, lines, or polygons with the same name contract.                                                       |
-
-Name geometry stays in its source representation. `placement: 'point'` (the default) lets the
-renderer place names inside polygons or on points. Use `placement: 'line'` to label source lines.
-Core creates no substitute point, centroid, or line feature.
-
-Name layers preserve source properties; `id` is a source identifier, with no guarantee of a numeric
-renderer feature ID. Optional `name:<language>` fields retain the source's language assignments.
-`labels({language: 'es'})` selects a nonempty `name:es`, falling back to `name`; `auto` and `local`
-use `name` directly. Core does not infer the language of an unqualified name or invent translations.
-Optional `min_zoom` is inclusive and `max_zoom` exclusive, defaulting to 0 and 24. These nominal
-ranges intersect the symbol style's range. With `true`, MapLibre evaluates feature zoom filters at
-integer zooms: `min_zoom: 7.6` first becomes eligible at zoom 8. For exact fractional boundaries,
-declare an exhaustive range inventory instead:
-
-```ts
-vectorLayers: {
-  contours: true,
-  landforms: {zoomRanges: [{minZoom: 0, maxZoom: 24}]},
-  waterNames: {
-    zoomRanges: [{minZoom: 1, maxZoom: 6.5}, {minZoom: 7.6, maxZoom: 10}],
-  },
-}
-```
-
-Each declared pair becomes a separate symbol layer with fractional renderer bounds and equality
-filters on the source's original range. A `7.6–10` feature appears at 7.6 and disappears at 10.
-Unlisted pairs are omitted. Core never discovers ranges from tiles: validate the source inventory
-against this exhaustive declaration before rendering, and retain that inventory with reproducible
-captures. Numeric pairs must match the source's encoded values exactly.
-
-Each name layer accepts 1–128 unique pairs with `0 <= minZoom < maxZoom <= 24`;
-`tileflowBathymetryNameLayerLimits.maxZoomRanges` exposes the limit. Input order does not affect
-output. Different pairs can overlap in zoom because equality filters keep their feature sets
-disjoint. A style may narrow a pair's visibility; an empty intersection emits no layer.
-Missing or null source bounds default to 0/24. Nonnumeric values use the same numeric-conversion
-fallbacks; numeric strings are converted. Such features draw only if their normalized pair is
-declared. Core preserves the original source properties.
-
-Optional numeric `sort_key` defaults to 0; smaller values enter collision placement first within
-each cohort. Cohorts follow ascending minimum then maximum zoom and sit below ordinary map labels.
-Names use normal collision placement without overlap by default.
-
-This example declares a source whose regional detail supports zoom 14. Its extended ranges are
-explicit design choices, not a promise of worldwide detail:
-
-<!-- docs:check -->
-
-```ts
-import {bathymetry, defineMap, expr, field, fixed, labels, water} from '@tileflow/core';
-import {soundings} from '@tileflow/maps';
-
-export default defineMap({
-  id: 'regional-depth',
-  version: 1,
-  extends: soundings,
-  marine: {
-    bathymetry: bathymetry({
-      url: 'https://tiles.example.test/regional-depth/tiles.json',
-      vectorLayers: {
-        contours: true,
-        landforms: {zoomRanges: [{minZoom: 0, maxZoom: 24}]},
-        waterNames: {zoomRanges: [{minZoom: 7.6, maxZoom: 10}]},
-      },
-      contours: {},
-      labels: {},
-    }),
-    nautical: false,
-  },
-  modules: {
-    labels: labels({language: 'es'}),
-    water: water({
-      bathymetry: {
-        maxZoom: 15,
-        opacity: fixed(0.8, {reason: 'The selected regional source supplies detailed bands'}),
-      },
-      bathymetryContours: {maxZoom: 15},
-      bathymetryLabels: {
-        maxZoom: 15,
-        text: {
-          field: expr.concat(
-            expr.toString(expr.abs(expr.get(field('bathymetryContourDepth')))),
-            ' m',
-          ),
-        },
-      },
-      bathymetryLandforms: {maxZoom: 15},
-      bathymetryWaterNames: {maxZoom: 15},
-    }),
-  },
-});
-```
-
-`water.bathymetryContours` and `water.bathymetryLabels` now consume the declared lines and `depth`;
-labels default to line placement. Band fills still consume `min_depth` and `sort_key`.
-`water.bathymetryLandforms` and `water.bathymetryWaterNames` style the declared names; set
-`visible: false` to hide either. Without their declaration, those styles emit no name layers.
-Name styles may use `class` in expressions without changing the source classification.
-
-Mixed geometry can opt into `placementByGeometry` on either name style. Its resolved policy must
-include `point`, `line`, and `polygon`; `point` must be `'point'`, while the other two accept
-`'point'`, `'line'`, or `'line-center'`. The policy overrides scalar `placement`, including an
-inherited value. Without it, scalar placement and existing generated layers remain unchanged.
-
-For example, this map labels point features at their coordinates and retains line placement for
-lines and polygon boundaries:
-
-<!-- docs:check -->
-
-```ts
-import {bathymetry, defineMap, labels, water} from '@tileflow/core';
-import {streets} from '@tileflow/maps';
-
-export default defineMap({
-  id: 'marine-names',
-  version: 1,
-  extends: streets,
-  marine: {
-    bathymetry: bathymetry({
-      vectorLayers: {landforms: {zoomRanges: [{minZoom: 0, maxZoom: 24}]}},
-    }),
-    nautical: false,
-  },
-  modules: {
-    labels: labels({language: 'es'}),
-    water: water({
-      bathymetryLandforms: {
-        placementByGeometry: {point: 'point', line: 'line', polygon: 'line'},
-      },
-    }),
-  },
-});
-```
-
-This example declares source availability; the selected source must actually contain those
-features. Equal placements share one geometry-filtered group per source range. A policy emits
-at most three groups per range (384 layers for one name family at the 128-range limit). Groups
-compile in `point`, `line`, `line-center` order below ordinary map labels; source priority orders
-features within each group. Module refinements inherit the policy and style every group.
-Render-stack refinements still address exact semantic targets; inspect each placement/range
-target when applying a narrower refinement.
-Normal collision still applies and can hide a name.
-
-Placement uses the received geometry: `point` places a line label at its first rendered vertex;
-it does not compute a stable line midpoint. Polygon `point` placement uses an interior position
-of the rendered polygon, while `line` follows its boundary. Core does not generate source anchors,
-merge identities or deduplicate names by text. A source can supply multiple stable point anchors
-with shared identity properties and distinct anchor properties; their extent, visibility and
-editorial policy belong to that source. Keep original source identities as properties rather than
-assuming a universal numeric `feature.id`.
-
-Water-module styles override product-level `bands`, `contours`, and `labels`. Existing custom
-`text.field` expressions remain authoritative: when refining a map from legacy polygons to native
-contours, use `expr.get(field('bathymetryContourDepth'))` for its depth. That auxiliary binding
-resolves to `depth` independently of the primary World schema; `bathymetryMinDepth` keeps its
-legacy band meaning. Raw `expr.get('depth')` is rejected by authoring validation.
-Increasing only `maxZoom` does not remove an opacity curve that fades out earlier. Extend ranges
-and opacity only where the selected source supports the intended detail.
-
-The V1 schema also reserves `bathymetry_coverage`; Core adds no coverage rendering by default.
-Derived contours and names provide geographic context, not certified navigation data.
-
-The DEM enables future client-side sampling and depth profiles, but Core intentionally exposes no
-profile or remote sampling API yet. Rendered relief must not be interpreted as navigation-safe
-depth data.
-
-Omitting `marine` preserves the transitional Tileflow World V1 bathymetry fallback. Declaring
-`marine: 'none'` suppresses that fallback, while a selected bathymetry sidecar always takes
-precedence. Compiled styles retain the singular `tileflow:data` metadata for existing consumers and
-add `tileflow:sources` plus `tileflow:sourceRequirements` for independent product validation.
-
-Detailed city datasets can bind `sidewalk`, `streetFurniture`, and `circularFeature` source layers
-through `openMapTiles({layers, fields})`. When present, `roads.sidewalks` owns source-backed
-pedestrian polygons, `roads.crossings` owns oriented crossing icons, and `roads.roundabouts` owns
-metric circular road rings. A `transportationOutline` binding names lines that trace the outer
-boundary of each road area; when bound, `roads.areas` outlines stroke those lines instead of the
-area polygons, so the holes of a plaza (tree pits, planting beds) are not stroked. These bindings
-are optional: a generic OpenMapTiles source remains
-valid and the compiler omits unsupported detail instead of inventing geometry. Crossing icons are
-explicit because the data contract cannot assume a sprite name. They require positive physical
-`markings` evidence, reject `crossing=no`, and require a numeric `direction` from 0 to 360 degrees
-(numbers and numeric strings are accepted). World derives missing directions only when the
-crossing has an unambiguous road axis; unresolved points on adjoining footways therefore remain
-hidden instead of receiving a default rotation. All three fields are semantic bindings, so custom
-schemas can remap them without weakening that rule.
-
-Metric road rings scale continuously with the map from zoom 15 through 24, including fractional
-zooms. Their casing is below surface road fills so approaching streets cover the outline at each
-junction. The ring fill stays below bridges and road markings.
-
-Road treatment `widthScale` scales both the stroke and an authored `gapWidth`, keeping hollow
-casings aligned with the carriageway at fractional zoom levels.
-When every dash treatment is continuous (`[1, 0]`), road layers omit the dash pattern so thin
-casings render as solid strokes. Actual construction and tunnel dashes remain patterned.
-
-Datasets may also publish the optional, decorative `canopy` layer: points inside urban parks and
-gardens, at most one per cell of a grid of about 20 m that measured tree canopy covers. Each point
-tells how much room a drawn grove of tree crowns has and how dense the canopy around it is. The
-points are not surveyed trees, are unrelated to the optional `tree` layer, and are not search or
-interaction targets. `openMapTiles()` and `tileflowWorldV1Schema()` bind the layer as `canopy` and
-its numeric fields as follows:
-
-- `canopyRank` (`rank`): a stable integer from 0 through 15. Lower ranks appear at lower zooms, and
-  the rank can vary artwork.
-- `canopyClearanceAtZoom15` (`clearance_px_z15`): 4, 6, 8, 12, 16, or 24. This is the lower bound
-  of the distance from the point to the nearest edge a crown must not cover, such as a park edge,
-  water, a building, a plaza, a pitch, or a roadway, in pixels of a 512-pixel tile at zoom 15. A
-  grove fits at zoom `z` when its drawn reach in screen pixels is at most
-  `clearance_px_z15 × 2^(z − 15)`.
-- `canopyCoverPercent` (`cover_pct`): 3, 30, or 60, the lower bound of the share, in percent, of
-  canopy taller than 3 m within 10 m of the point. The field is absent where no measurement exists;
-  treat absence as a middle density.
-
-Features are MultiPoints, one per identical set of attributes. Native zoom 15 holds every point,
-zoom 14 holds the points whose rank is below 8 at the same positions, and clients overzoom zoom 15.
-`validateTileflowWorldV1Tilejson(...)` accepts a TileJSON without `canopy`; once declared, the layer
-must occur exactly once, declare native z14–z15, and advertise Number `rank`, `clearance_px_z15`, and
-`cover_pct`. No module draws the layer. A source without it remains valid, and render passes bound
-to it draw nothing. `capabilities: {canopy: false}` removes the binding, after which a pass with
-`feature: 'canopy'` fails with a missing-binding error.
-
-Draw groves with symbol render passes, one grove of whole crowns per point, sized to its room:
-
-<!-- docs:check -->
-
-```ts
-import {expr, field, fixed, renderPass, token, vegetation, withRenderStack} from '@tileflow/core';
-
-// The grove artwork reaches 32 pixels from its center at icon size 1.
-const clearance = expr.get(field('canopyClearanceAtZoom15'));
-// The size that fills the room at one zoom, never larger than the artwork itself.
-const fit = (divisor: number) => expr.min(expr.divide(clearance, divisor), 1);
-
-const groves = (minZoom: number, fromRank: number, toRank: number) =>
-  renderPass({
-    placement: 'above-vegetation',
-    feature: 'canopy',
-    renderer: 'symbol',
-    selector: {
-      kind: 'all',
-      selectors: [
-        {field: 'canopyRank', kind: 'compare', operator: 'gte', value: fromRank},
-        {field: 'canopyRank', kind: 'compare', operator: 'lt', value: toRank},
-      ],
-    },
-    style: {
-      minZoom,
-      icon: {
-        ignorePlacement: true,
-        image: token.image('vegetation.canopy.grove'),
-        overlap: 'always',
-        size: expr.interpolate({base: 2, kind: 'exponential'}, expr.zoom(), [
-          [14, fit(64)],
-          [15, fit(32)],
-          [16, fit(16)],
-          [17, fit(8)],
-          [18, fit(4)],
-        ]),
-      },
-      text: {
-        field: 'o',
-        font: token.font('default'),
-        opacity: fixed(0, {reason: 'The core text only decides placement'}),
-        overlap: 'cooperative',
-        size: fixed(8, {reason: 'Matches the solid core of the grove artwork'}),
-      },
-    },
-  });
-
-export const canopyGroves = withRenderStack(vegetation(), {
-  groves14: groves(14, 0, 4),
-  groves15: groves(15, 4, 8),
-  groves16: groves(16, 8, 16),
-});
-```
-
-- Give each rank range its own pass with `minZoom`, so its points appear whole at their entry zoom.
-  MapLibre evaluates expressions that combine zoom and feature data at whole zoom levels and
-  interpolates between them, so a fade per feature would leave symbols half transparent. Zoom 14
-  tiles carry the ranks below 8, so the first pass may cover ranks 0–7.
-- Size each grove from `canopyClearanceAtZoom15`. Here the size is `clearance / 32` at zoom 15 and
-  doubles with each zoom until the grove reaches the artwork's size, which keeps the reach within
-  the room.
-- Collision tests an icon's whole image, including the transparent margin around the crowns. A small
-  invisible text the size of the grove's core therefore decides placement with
-  `overlap: 'cooperative'`, while the icon draws with `overlap: 'always'` and `ignorePlacement: true`.
-  Groves may overlap each other but give way to labels, which draw above the vegetation band and are
-  therefore placed first, with the default `never`.
-
-Every theme of the map must define the image token, and the map's icon directories must provide the
-artwork. Native artifacts replace `cooperative` with `allowOverlap: true`, so there groves can cover
-labels; see [symbol overlap modes](shared-visual-primitives.md#symbol-overlap-modes).
-
-The optional `business_corridor` extension contains activity-selected source footprints below
-buildings. Its `activity_score`, `rank`, `min_zoom`, and `confidence` fields control a quiet local
-warm tint without drawing POI-radius circles. Current building footprints may carry sparse
-`building_tone=commercial|destination|active`; absence means the neutral base building. The three
-values preserve why the warm tone was selected even when a theme maps them to the same color.
-Buildings may also carry World's `class`, their use in Overture's building subtype values; without
-a tone, the buildings module colours `residential`, `commercial`, public buildings (`civic`,
-`education`, `medical`, `religious` and the like) and works (`industrial`, `agricultural`,
-`service`) with the theme's `residential`, `commercial`, `civic` and `industrial` building colours,
-and every other building with `generic`. Building visibility is fixed by the layer zoom contract and never by optional semantics. The land
-module also exposes
-`medical`, `education`, and `government` independently instead of collapsing their already distinct
-source classes into one civic color.
-
-World and text assets are independent contracts. `tileflowWorld()` selects `world-v1/current` or an
-exact `releaseId + descriptorSha256`; a `glyphs` declaration contains its own complete URL. Every
-official map compiles as imported because it owns or inherits a URL or packaged-font provider.
-URL-backed maps become exact-byte reproducible
-when the immutable global base-asset set is published and their explicit URL is updated to its
-`assetSetSha256` path; no World or compiler fallback participates in that rollout. The global
-base-asset manifest's hash and a map build manifest's identically named `assetSetSha256` use
-different contracts and must never be substituted for one another.
-
-Upstream data attribution remains in the MapLibre source. `Map by Tileflow` is a separate product
-credit/trademark surface and must not replace, obscure, or be presented as upstream attribution.

package/docs/depth-markers.md

@@ -1,65 +0,0 @@
-# Depth markers
-
-DOM markers float above the map: in a 3D scene a pin behind a tower still shows in front of it.
-`createTileflowDepthMarkers` draws markers in the map's 3D scene instead. A MapLibre custom layer
-draws them against the depth the map's extrusions write, so nearer buildings hide them as the camera
-moves.
-
-## Add markers
-
-This example assumes an existing MapLibre map named `map` with 3D buildings, and two pictures drawn
-by the application:
-
-<!-- docs:check -->
-
-```ts
-import {createTileflowDepthMarkers, type TileflowDepthMarkerMap} from '@tileflow/core/browser';
-
-export function pinDestination(
-  map: TileflowDepthMarkerMap,
-  at: [number, number],
-  pin: HTMLCanvasElement,
-  ring: HTMLCanvasElement,
-) {
-  const markers = createTileflowDepthMarkers(map);
-  // A pin facing the viewer, 28 × 40 CSS pixels, standing on the position.
-  markers.add({lngLat: at, image: pin, size: [28, 40], anchor: 'bottom'});
-  // A ring lying on the ground, 60 metres across.
-  const halo = markers.add({lngLat: at, image: ring, size: [60, 60], alignment: 'ground'});
-  return {
-    pulse: (opacity: number) => halo.update({opacity}),
-    dispose: () => markers.dispose(),
-  };
-}
-```
-
-A marker has:
-
-- **Position.** `lngLat`, and `altitude` in metres above the ground.
-- **Picture.** `image`: an image, an image bitmap, a canvas or image data. After drawing into a
-  canvas again, pass it to `update({image})` so the marker uploads it once more. Markers that share
-  a picture share its upload.
-- **Alignment.** `screen` (the default) faces the viewer at `size` in CSS pixels, like a pin.
-  `ground` lies flat on the ground at `size` in metres, in the camera's perspective, like a ring or
-  an arrow painted on the street.
-- **Anchor and placement.** `anchor` (`center` or `bottom`), `offset` in CSS pixels for screen
-  markers, and `rotation` in degrees clockwise: from the screen's up for screen markers, from north
-  for ground markers.
-- **Opacity.** From 0 to 1.
-- **`occlude`.** Defaults to true: nearer 3D content hides the marker. Set it to false for a marker
-  that must always show.
-
-Markers test against the scene's depth without writing to it, so they never hide one another. A
-screen marker takes the depth of its position: a tower in front of the position hides the whole
-pin, a tower in front of part of it hides that part.
-
-## Layer and lifecycle
-
-The markers share one custom layer, `tileflow-depth-markers` unless `id` names another, added with
-the first marker. `beforeId` places it under a layer, given as an id or as a function that finds the
-layer again after a style change. After a style change the layer puts itself back, and pictures
-are uploaded again. `dispose()` removes the layer and releases its GPU resources.
-
-Depth markers need MapLibre GL JS on WebGL 2 (GL JS 5 or later). They work on globe and Mercator
-projections. They draw pictures only: draw text and effects into the picture, or keep DOM markers
-for interactive content.