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

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

@@ -121,14 +121,14 @@ their source faces' shapes. Browser adapters load local faces before MapLibre. N
 `glyphs` URL provider instead, which enumerates the exact comma-joined MapLibre request keys in
 `fontStacks`.
 
-Streets, Ferraris, Härad, Soundings, and Blueprint each declare
+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 and Siegfried each own a packaged directory containing Cormorant Garamond Regular, SemiBold, and Italic.
+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:
 
@@ -295,10 +295,181 @@ 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.
+
+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
@@ -318,6 +489,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 +601,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/hosted-session-authorization.md

@@ -53,10 +53,8 @@ import {
   civica,
   civicaFonts,
   civicaIcons,
-  ferraris,
-  ferrarisIcons,
-  harad,
-  haradIcons,
+  map1777,
+  map1777Icons,
   siegfried,
   siegfriedFonts,
   siegfriedIcons,

package/docs/map-and-terrain-examples.md

@@ -92,9 +92,16 @@ then transition to Mercator between zoom 10 and 12 so detailed streets remain pl
 property, or set it to `'mercator'`, for a consistently flat map.
 
 Terrain keeps the original `'none' | 'hillshade' | '3d'` shorthand. The object form can style every
-MapLibre hillshade paint control, or generate vector contours in the browser from an explicit DEM
-tile template. Contours require `demUrl`, `demMaxZoom`, and zoom-indexed `[minor, index]`
-`thresholds`; the raster `url` remains the separate TileJSON endpoint. Set `mode: 'none'` to compile
+MapLibre hillshade paint control. Raster terrain accepts either a TileJSON `url` or explicit `tiles`
+templates, with optional `tileSize` (256 or 512) and native `minZoom`/`maxZoom` limits. The templates
+must contain `{z}`, `{x}` and `{y}` and use HTTPS (HTTP is allowed for loopback development).
+These source limits control DEM requests independently of `hillshade.minZoom`/`maxZoom` visibility;
+the renderer reuses the highest available native resolution for closer views. Select resolution
+limits supported by the provider and retain its required attribution.
+
+Contours generate vector lines in the browser from their own explicit DEM tile template. They
+require `demUrl`, `demMaxZoom`, and zoom-indexed `[minor, index]` `thresholds`; these are separate
+from the raster source's `url` or `tiles`. Set `mode: 'none'` to compile
 contours without adding a raster source, hillshade, or 3D terrain:
 
 ```ts

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/street-lights.md

@@ -6,6 +6,9 @@ glowing head. Streets and pavements the data maps as lit, but whose lamps it doe
 soft light along them that claims no lamp's place. As the theme controller's sun darkens the map,
 the lights switch on one by one; they go out as day comes.
 
+Street lights are off by default in the SDK and in Streets. A compiled map must explicitly set
+`roads.streetLights.enabled: true` before the renderer or preview will show lamp glows.
+
 It is a custom WebGL2 layer for MapLibre GL JS, drawn above the map's buildings and below its
 labels. When `createTileflowBuildings3D` raises the buildings, they hide the lamps behind them. It
 needs WebGL2 and the Mercator projection, and shines from zoom 14 by default.
@@ -13,7 +16,8 @@ needs WebGL2 and the Mercator projection, and shines from zoom 14 by default.
 ## Light the streets
 
 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:
+`tileflow`, as Tileflow's maps call World, with `roads.streetLights.enabled: true` in its map
+definition and a theme controller for it:
 
 <!-- docs:check -->
 
@@ -56,12 +60,12 @@ lit streets, others almost none. Where the data says nothing, the streets stay d
 
 The map describes its street lights in its roads module, next to the other details drawn from
 street furniture, and publishes them with its style for every theme; `stats.declared` tells whether
-it does. Without a description the lights take the defaults below:
+it does. Without an enabled description the renderer stays off and mounts no layer:
 
 <!-- docs:check -->
 
 ```ts
-import {defineMap, refine} from '@tileflow/core';
+import {defineMap, fixed, refine} from '@tileflow/core';
 import {streets} from '@tileflow/maps';
 
 export default defineMap({
@@ -71,7 +75,14 @@ export default defineMap({
   extends: streets,
   modules: {
     // Sodium-orange light, a little brighter, on every street of tiles that map few lamps.
-    roads: refine({streetLights: {color: '#ffb35c', intensity: 1.3, estimate: 'streets'}}),
+    roads: refine({
+      streetLights: {
+        enabled: true,
+        color: fixed('#ffb35c', {reason: 'Constant sodium-lamp color.'}),
+        intensity: 1.3,
+        estimate: 'streets',
+      },
+    }),
   },
 });
 ```
@@ -89,11 +100,16 @@ street rather than as lamps that may not stand there.
 
 `color` is the light of the lamps whose data gives no colour, a warm white by default, and
 `intensity` scales the light from 0 to 2 (1 by default); both may be theme tokens and mix during a
-blend. `streetLights: {enabled: false}` gives the map none.
+blend. These settings apply only after `enabled: true`; `streetLights: {enabled: false}` gives
+the map none.
 
 ## Options
 
-The layer's own options say only how it is delivered: `minzoom` (14 by default) and `maxTiles` (25
+The layer follows the compiled map by default. `createTileflowStreetLights({map, controller,
+enabled: true})` explicitly enables the fallback design for a style without street-light metadata;
+`enabled: false` keeps the renderer off even when the map declares lights.
+
+The delivery options are `minzoom` (14 by default) and `maxTiles` (25
 by default, at most 64) bound where and how far the lights shine, `beforeId` places the layer before
 another one, and `transformRequest` applies the map's request rules to the tiles it reads.
 

package/docs/sun-and-light.md

@@ -15,8 +15,8 @@ application's own WebGL layers to draw, from the values `getSun()` returns.
 ## Describe a theme's sun
 
 Set `lighting.sun` and `lighting.ambient` in the theme. Every value is optional; unset values take
-the defaults in `tileflowDefaultSunPreset` (azimuth 210°, altitude 60°, white light at 0.5, full
-shadows, a white sky at 0.5):
+the defaults in `tileflowDefaultSunPreset` (azimuth 210°, altitude 60°, white light at 0.2, full
+shadow strength, a white sky at 0.8 for soft daylight shadows):
 
 <!-- docs:check -->
 
@@ -43,6 +43,46 @@ others are inherited. The compiled style carries the resolved sun in its metadat
 direction in `lighting.position` no longer apply to a theme with a sun. A theme without `sun` or
 `ambient` compiles exactly as before.
 
+## Replace inherited lighting
+
+`defineTheme(base, definition)` normally merges lighting field by field. An empty `lighting`,
+`sun`, or `ambient` object therefore preserves inherited values. Use the existing `reset()`
+operation to remove a preset explicitly while keeping the base theme's palette and typography:
+
+<!-- docs:check -->
+
+```ts
+import {defineTheme, reset} from '@tileflow/core';
+import {streetsThemes} from '@tileflow/maps';
+
+export const studio = defineTheme(streetsThemes.light, {
+  id: 'studio',
+  version: 1,
+  colorScheme: 'light',
+  lighting: {
+    sun: reset(),
+    ambient: reset(),
+    anchor: 'viewport',
+    position: [1.15, 180, 40],
+    color: '#FFFFFF',
+    intensity: 0.15,
+  },
+});
+```
+
+Removing both presets lets the native extrusion light use the authored `anchor` and `position`.
+Resetting only `sun` keeps an inherited ambient preset, and resetting only `ambient` keeps the sun;
+the missing counterpart then uses the SDK defaults. `lighting: reset()` clears all inherited
+lighting properties. A direct property such as `position`, `color`, or `intensity` can also be
+reset. The result is a complete theme with those properties absent; it contains no reset nodes.
+To replace a whole sun or ambient object, first derive a theme that resets that object, then derive
+the replacement values from the cleared theme.
+
+Removing a preset does not turn off the renderer's lighting, cast shadows, or ambient occlusion.
+The SDK's 3D scene uses its fallback light when no preset is published. For a graphic building
+style, choose the building module's `lighting: 'style'`, `shadows: false`, and `occlusion: false`
+explicitly. A single static theme needs no time-of-day family or running clock.
+
 ## Read the sun in an application
 
 `themeController.getSun()` returns the sun the map shows:

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/themes-and-module-styles.md

@@ -15,6 +15,61 @@ same token keys, so changing a theme can never change map structure or silently
 role. `defineTheme(base, definition)` is an authoring convenience that returns a fully materialized
 document; it does not leave an inheritance edge in the resolved config.
 
+## Start with one appearance
+
+A map can have one appearance for its entire lifetime. Neither `systemThemes` nor `timeOfDay` is
+required. This complete theme supplies the twelve base color roles the semantic compiler needs;
+copy it and change its colors to start an independent design without inheriting an official map:
+
+<!-- docs:check -->
+
+```ts
+import {defineTheme} from '@tileflow/core';
+
+export const paper = defineTheme({
+  id: 'paper',
+  version: 1,
+  colorScheme: 'light',
+  tokens: {
+    color: {
+      'surface.background': '#F6F7F3',
+      'surface.land': '#F1F3ED',
+      'surface.water': '#A9D3F5',
+      'surface.park': '#CDE8B5',
+      'surface.building': '#E6E3DA',
+      'roads.default': '#FFFFFF',
+      'roads.major': '#F4C95D',
+      'roads.casing': '#D9DEE2',
+      'boundaries.default': '#C9D1D9',
+      'labels.primary': '#3C4043',
+      'labels.muted': '#727B84',
+      'labels.halo': '#FFFFFF',
+    },
+  },
+});
+```
+
+An existing map definition can select this appearance with `themes: {paper}` and
+`defaultTheme: 'paper'`. Supply that map's data and font assets separately; the default typography
+uses `Noto Sans Regular`. A theme without these base roles is a valid appearance document but cannot
+compile a semantic map. Colors above are an editable starting point, including for monochrome,
+historical, dark-only, or imagined worlds; `colorScheme` describes the appearance for consumers and
+does not generate a palette or choose a time of day.
+
+The compiler derives more specific roles when they are absent. For example, primary and motorway
+roads initially use `roads.major`; declaring `roads.motorway` replaces only that derived color.
+Land-use fills, road casings, and label colors have their own semantic roles, so an explicit role
+always wins over its fallback. Use `color.mix()` and `token.color()` in a theme when the relationship
+itself should be authored and inspectable. Derivations resolve during compilation, without a clock
+or a per-frame palette calculation.
+
+Add named appearances when the map needs them. A day/night pair does not need dawn or dusk, and a
+theme named `paper` or `fantasy` does not need a temporal family. Declare `timeOfDay` only when the
+application should offer those artistic moments; see
+[time-of-day selection](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/theme-transitions-and-blends.md#time-of-day).
+
+## Compose and replace appearance values
+
 Some optional tokens are for the application rather than the map's own layers. Route inks
 (`route.line`, `route.casing`, `route.core`, `route.glow`, `route.alternative`,
 `route.glow.opacity` and `route.core.opacity`) set how an application draws its routes; a theme
@@ -83,6 +138,17 @@ deterministic OKLCH `color.mix()` keep derived palette logic inspectable. Unknow
 cross-category refs, token-schema drift, and unresolved visual nodes fail before Style JSON is
 emitted.
 
+Theme lighting also supports explicit removal during `defineTheme` composition. Use
+`lighting: reset()` to remove the entire inherited lighting configuration, or
+`lighting: {sun: reset(), ambient: reset()}` to remove those presets while retaining other light
+properties. The same operation can remove a direct property such as `position` or `color`.
+Omitting a property, or supplying an empty object, continues to inherit it. Reset operations are
+materialized immediately and never enter the resolved theme or Style JSON. Removing a lighting
+preset restores the renderer's fallback; it does not disable 3D shadows or occlusion. Those remain
+explicit building settings. See
+[sun and light](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/sun-and-light.md#replace-inherited-lighting)
+for a complete example.
+
 There is no physical-layer override for the Tileflow basemap or separate official-map authoring
 surface. Basemap behavior belongs to a typed control or owner-local render stack. Every
 official and application map therefore follows the same schema, inheritance rules, diagnostics,