@tileflow/core 0.1.0-alpha.34 → 0.1.0-alpha.35

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

@@ -295,10 +295,129 @@ 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.
-Until native contour fields are contracted, contours are a visual fallback drawn from band polygon
-edges, not surveyed isolines. The V1 schema exposes optional source-layer names
-`bathymetry_contour`, `seafloor_landform`, `water_name`, and `bathymetry_coverage`, but promises
-fields only for required `bathymetry.min_depth` and `bathymetry.sort_key`.
+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.
+
+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
@@ -318,6 +437,15 @@ explicit because the data contract cannot assume a sprite name. They require pos
 `markings` evidence and reject `crossing=no`; both 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
@@ -421,7 +549,11 @@ buildings. Its `activity_score`, `rank`, `min_zoom`, and `confidence` fields con
 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.
-Building visibility is fixed by the layer zoom contract and never by optional semantics. The land
+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.

package/docs/native-artifact-profile.md

@@ -39,6 +39,11 @@ preparing the referenced resources.
 
 The exported `tileflowNativeProfile` targets MapLibre React Native 11.3.10 with Native Android 13.2.0
 and iOS 6.26.0. These are static compatibility targets, not a supported application dependency matrix.
+The application integration uses MapLibre React Native 11.5.0 with Android 13.6.1 and iOS 6.31.0.
+The artifact profile retains its earlier validation targets and build-record engine values, keeping
+prepared artifacts compatible with existing Hosted validators. New application dependencies do not
+expand the accepted style vocabulary.
+
 The wrapper's Style Spec version is 26.2.1. Tileflow retains its existing compiler and parser at
 24.8.5: `native-v1` checks that compiler's vocabulary and the intersection of its recorded Android
 and iOS support. It does not expose every feature of Style Spec 26.2.1 or upgrade the web compiler.

package/docs/native-resource-urls.md

@@ -121,7 +121,7 @@ network request. Do not attach a credential merely because this helper accepted
 
 ## Private parser and source builds
 
-The native entry embeds the low-level parser from `whatwg-url` 15.1.0, `tr46` 6.0.0 (Unicode 17
+The native entry embeds the low-level parser from `whatwg-url` 17.2.0, `tr46` 7.0.0 (Unicode 18
 IDNA processing) and Punycode.js 2.3.1. It exposes no URL class or parser configuration. Package
 consumers only install Core; the published `dist/native.js` has no external runtime imports.
 The parser is a development/build dependency, not an additional runtime package to install.
@@ -136,8 +136,10 @@ policy with its existing host parser; it does not embed the mobile parser in its
 
 From an SDK source checkout, run the ordinary Core build, not a direct source import in a native
 application. `tsup.native.config.ts` builds only the native entry with `platform: 'browser'`,
-`target: 'es2020'`, ESM and no splitting. Its plugin redirects exactly the two relative
-`./encoding` imports in the pinned parser modules to Core's private UTF-8 codec. It rejects an
+`target: 'es2020'`, ESM and no splitting. Its plugin redirects the two relative
+`./encoding` imports and the parser's two `@exodus/bytes` encoding imports to Core's private UTF-8
+codec. Query encoding accepts only UTF-8; the legacy encoding bootstrap has no side effects.
+Exodus and its legacy encoding tables are not embedded. The build rejects an
 unexpected dependency version, an unbound codec import or external runtime imports. It does not
 patch packages on disk, configure a global alias or change another entry's build.
 

package/docs/theme-transitions-and-blends.md

@@ -258,3 +258,53 @@ export async function duskWhileFlying(
 The React, Vue, and Svelte maps take the same flag in `themeBlend`: pass
 `themeBlend={{hold: true, position, themes}}` while the camera moves and drop `hold` when it rests.
 The React Native `Map` blends natively and does not take `hold`.
+
+## Time of day
+
+`timeOfDay` is an optional map capability. It maps a theme and an artistic preset (`day`,
+`dawn`, `dusk`, `night`) to a complete theme already in `themes`:
+
+<!-- docs:check -->
+
+```ts
+import {defineMap} from '@tileflow/core';
+import {streets, streetsThemes} from '@tileflow/maps';
+
+export default defineMap({
+  id: 'city',
+  version: 1,
+  extends: streets,
+  themes: {
+    paper: streetsThemes.light,
+    sunrise: streetsThemes.dawn,
+    evening: streetsThemes.dusk,
+    ink: streetsThemes.dark,
+  },
+  defaultTheme: 'paper',
+  systemThemes: {light: 'paper', dark: 'ink'},
+  timeOfDay: {
+    paper: {day: 'paper', dawn: 'sunrise', dusk: 'evening', night: 'ink'},
+  },
+});
+```
+
+Applications keep `theme` and optionally add `timeOfDay`: `theme="paper" timeOfDay="dusk"`
+selects `evening`. Compilation supports `createStyle(map, {theme: 'paper', timeOfDay: 'dusk'})`;
+`resolveTileflowRuntimeTheme(map, theme, colorScheme, timeOfDay)` uses the same resolution.
+Omitting the preset preserves the existing selection. `system` resolves its light/dark theme
+first. A concrete variant such as `ink` also identifies its family when a preset is supplied.
+Maps or themes without a family ignore this option. Within a declared family, an unavailable
+preset is an error; controls should offer only declared presets. Families must include their own
+name in their presets, and a concrete theme can belong to only one family.
+
+The catalog inherits atomically; `timeOfDay: {}` disables it on an extension. Replacing `themes`
+clears an inherited catalog. `defaultTheme`, `systemThemes`, and `themeTransition` retain their
+behavior. An explicit `themeBlend` owns its concrete theme sequence and takes precedence over
+`timeOfDay`. Changing the preset does not start a clock or call `setSun`; lighting is whatever the
+selected theme already declares, and an application's sun override retains its existing behavior.
+Captures, style URLs, and transition events use the resolved concrete theme name.
+
+Maps with a catalog publish runtime manifest version 2. Updated browser and native readers accept
+both versions. Old readers need a version 1 manifest: `createManifest(project, {manifestVersion: 1})`
+omits the catalog and keeps every concrete theme available. Maps without a catalog still emit
+version 1. Update readers before delivering a version 2 manifest.

package/docs/trees-3d.md

@@ -12,10 +12,68 @@ style it compiles, for every theme, and the renderer follows theme changes and b
 
 It is a custom WebGL2 layer for MapLibre GL JS, drawn above the map's buildings and below its
 labels. It needs WebGL2 and the Mercator projection, and the trees stand from zoom 15 by default.
-Elsewhere (Capture, Static Maps, Native, or a browser without WebGL2) the map draws the vegetation
-module's flat trees.
+When model trees are requested, Capture, Static Maps, Native, and browsers without WebGL2 use
+the module's `fallback`: `flat` by default, or `none` to omit trees. Static output uses the 2D view
+for `auto` maps. Streets chooses `none`, so it never substitutes flat crowns
+for its models unless an extension explicitly chooses `flat` or `auto`.
 
-## Stand the trees
+## Visibility and representation
+
+Use `createTileflowVegetation` for application controls. React, Vue and Svelte mount it automatically
+in interactive maps. The map chooses `vegetation.mode` independently of visibility:
+
+| Mode           | 2D view             | 3D view             |
+| -------------- | ------------------- | ------------------- |
+| `3d` (default) | Model trees         | Model trees         |
+| `flat`         | Flat crowns/circles | Flat crowns/circles |
+| `auto`         | Flat crowns/circles | Model trees         |
+
+`viewMode` is explicit application state (`2d` by default), not a pitch threshold. Tilting the camera
+does not change representation. Visibility defaults to `vegetation.visible ?? true`; OFF hides every
+representation. Turning trees off releases model buffers and tile readers. Controls apply immediately,
+without a grow/sink animation, and do not change building appearance or lighting.
+
+<!-- docs:check -->
+
+```ts
+import {createTileflowVegetation, type TileflowVegetationOptions} from '@tileflow/core/browser';
+
+export function mountVegetation(options: TileflowVegetationOptions) {
+  const trees = createTileflowVegetation({...options, viewMode: '2d'});
+  trees.setVisible(false); // Hide all vegetation, including flat artwork.
+  trees.setVisible(undefined); // Restore the map's authored visibility.
+  trees.setViewMode('3d'); // Only auto maps change representation.
+  return trees; // Call dispose() before removing the map, or let its remove event clean up.
+}
+```
+
+Pass the application's HTTP tile `transformRequest` when it supplies credentials or request headers;
+asynchronous transforms are supported. Use one vegetation controller per map and do not mount a second
+low-level tree renderer alongside it. Style replacement and theme changes retain visibility and view mode.
+
+To change an inherited map's policy while preserving its artwork:
+
+<!-- docs:check -->
+
+```ts
+import {defineMap, refine} from '@tileflow/core';
+import {streets} from '@tileflow/maps';
+
+export default defineMap({
+  id: 'adaptive-trees',
+  version: 1,
+  extends: streets,
+  modules: {vegetation: refine({mode: 'auto', fallback: 'flat'})},
+});
+```
+
+Use `refine({visible: false})` for initially hidden vegetation that can be enabled at runtime.
+Use `vegetation: disable()` to remove the module entirely; a runtime toggle cannot restore a module
+that is absent from the compiled map. Browser framework components accept `vegetation={false}` and
+`viewMode="3d"` (Vue: `:vegetation="false"`, `view-mode="3d"`). Image mode uses the compiled static
+fallback and does not apply these interactive controls.
+
+## Animate trees with the low-level renderer
 
 This example assumes an existing MapLibre map showing a Tileflow map whose vector source is called
 `tileflow`, as Tileflow's maps call World, and a theme controller for it:
@@ -42,7 +100,8 @@ a share of their size, from 0 to 1. Each returns a promise that resolves once th
 newer call takes over from where the trees stand. A browser preference for reduced motion changes at
 once. `dispose()` takes the layer off the map.
 
-While they stand, the 3D trees stand in for the map's flat trees: the layers the vegetation module
+This low-level API retains its flat-layer restoration behavior; use the vegetation controller for
+a visibility toggle. While they stand, the 3D trees stand in for the map's flat trees: the layers the vegetation module
 draws them with are hidden when the trees are shown, and come back as they were once the trees have
 sunk or the layer leaves the map.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/core",
-  "version": "0.1.0-alpha.34",
+  "version": "0.1.0-alpha.35",
   "license": "Apache-2.0",
   "description": "Typed Tileflow config and MapLibre style compiler.",
   "type": "module",
@@ -84,9 +84,10 @@
     "@mapbox/vector-tile": "3.0.0",
     "earcut": "3.2.4",
     "maplibre-contour": "0.1.0",
+    "meshoptimizer": "1.3.0",
     "pbf": "5.1.2",
-    "pmtiles": "4.4.0",
-    "whatwg-url": "15.1.0"
+    "pmtiles": "4.5.0",
+    "whatwg-url": "17.2.0"
   },
   "scripts": {
     "build": "tsup --config tsup.build.config.ts && tsup --config tsup.native-profile.config.ts && tsup src/browser.ts --format esm --dts --no-splitting --platform browser && tsup --config tsup.native.config.ts && cp ../../docs/modules-api-reference.json dist/config-reference.json",