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

package/docs/buildings-3d.md

@@ -1,19 +1,22 @@
 # 3D buildings
 
 `createTileflowBuildings3D` raises the buildings of a Tileflow map's vector tiles round the camera.
-By default it preserves the map's building colours and native extrusion lighting (`style.light`
-and its vertical wall gradient). Showing, hiding and changing height are immediate. Cast shadows,
-contact shadow, illuminated outlines, random colour variation and night lights are off.
-
-Scene sun lighting, shadows, decorative effects and animated height remain available through
-explicit options. They are independent of the map's trees.
+By default it preserves the map's building colours, uses the scene sun, casts shadows, adds soft
+contact shading and rounds exterior corners by 0.8 metres. An unspecified sun uses soft daylight
+with directional intensity 0.2 and ambient intensity 0.8; authored theme lighting stays in control.
+Showing, hiding and changing height are immediate. Illuminated outlines, random colour variation,
+invented windows and night lights remain off. Every effect is independently overridable and
+independent of the map's trees.
 
 Tileflow landmarks and a map's own building models can stand in the same 3D scene, replacing
 the buildings under their footprints.
 
 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, which MapLibre's globe turns into from about
-zoom 12; the buildings stand from zoom 14.5 by default.
+zoom 12. On every map, buildings and placed models appear automatically from zoom 15,
+with opacity rising linearly from 0 at 15 to 1 at 15.25. Zooming back out reverses the fade.
+Their height stays unchanged throughout; shadows and contact shading fade with them.
+`hide()` keeps them hidden at every zoom until `show()` is called.
 
 ## Show the buildings
 
@@ -31,15 +34,14 @@ import {
 
 export function raiseTheCity(map: TileflowBuildings3DMap, controller: TileflowThemeController) {
   const buildings = createTileflowBuildings3D({map, controller});
-  // No animation unless requested.
-  void buildings.show();
+  // Enabled on creation; hide() and show() override visibility.
   return buildings;
 }
 ```
 
 `show()`, `hide()` and `grow(scale)` change the height immediately by default (duration 0).
 `show({transition: {duration: 800, mode: 'fade'}})` reveals full-height buildings with a
-dithered fade. The default animation mode is `grow`; both modes respect reduced-motion settings.
+smooth opacity fade. The default animation mode is `grow`; both modes respect reduced-motion settings.
 To animate, pass `{transition: {duration: 800}}` explicitly; `grow(scale)` accepts a height share
 from 0 to 1. Each returns a promise that resolves once the change ends; a newer call takes over from where the buildings stand. A browser preference for reduced
 motion changes at once. `dispose()` takes the layer off the map.
@@ -51,7 +53,7 @@ tiles (25 by default), and meshes them a few milliseconds per frame. It reads Wo
 `night_use` and the roof fields (see [roofs](#roofs)), and the places in World's `poi` layer (see
 [night light](#night-light)). `stats.declared` tells whether the map's
 style describes its 3D buildings. Recompile existing maps to pick up the new defaults: previously
-compiled metadata with explicit effects enabled continues to honour those values.
+compiled metadata keeps explicit settings, including `false`, `0` and `lighting: 'style'`.
 
 ## Design the buildings in the map
 
@@ -108,13 +110,36 @@ export default defineMap({
   set of themes changes, and the themes either side of a blend's position mix on the GPU, so a
   moving blend costs nothing per frame.
 - `threeDimensional.shadows` and `occlusion` (the band at the foot of the walls and the darker tight
-  corners) default to false. `windows: true` adds invented night windows, lit by rooms; they are
+  corners) default to true. Set either to false independently. `windows: true` adds invented night windows, lit by rooms; they are
   decoration, not data, and are off by default. Where World says what a building is used for
   (`class`), sheds, garages, barns, factories, churches and service buildings get no rows of
   windows, homes light more of theirs at night, in a warm light, and offices, schools and hospitals
   fewer, in a cooler one.
 - `threeDimensional.edges` and `edgeColor` set the [edges](#edges), and `nightLight` the
   [night light](#night-light). Numbers and colours may be theme tokens.
+- `threeDimensional.edgeRadius` rounds convex exterior corners in the mesh and softens the
+  roof/wall lighting transition. It accepts 0–1 metres and defaults to 0.8; use 0 for sharp corners.
+  Courtyard corners and tile cuts stay unchanged. The authored roof shape is preserved; the top
+  edge is softened through lighting, not a geometric roof bevel. Rounding adds a bounded number
+  of vertices at convex corners, with no extra render pass. Changes to this radius rebuild the
+  resident building meshes.
+
+In both `style` and `sun` lighting, the vertical gradient darkens the foot of a facade by ten percent, fading smoothly over
+at most three metres (half the height for low buildings). It is evaluated per fragment, so a tall
+building does not acquire a full-height dark ramp. Disabling the authored extrusion's
+`verticalGradient` disables this shading. Ground contact shadow is controlled by `occlusion`, enabled by default. It extends three metres
+from grounded walls, darkening the ground by at most 16%, with a smooth distance falloff and round
+corners. Every map uses these defaults when it enables `occlusion`. The reach is measured in world
+metres, so its screen width scales continuously with zoom and becomes subtle at distant views.
+Overlaps use the strongest
+shade once, so shared walls, courtyards and tile joins do not accumulate dark bands. Raised building
+parts do not cast contact shade. Facade occlusion darkens the base by at most 14% and fades
+exponentially with a three-metre decay radius: about 5% remains one floor up and 2% two floors up.
+It follows height above ground, so raised parts do not restart the contact gradient at their base.
+The facade gradient, contact and inner-corner shade use the strongest contribution once, avoiding
+an extra dark strip where they overlap. Both lighting modes use the same falloff at every zoom.
+The ground mask uses one byte per drawing-buffer pixel while enabled and is released when disabled
+or the renderer is removed; it resizes with the drawing buffer.
 
 ## Landmarks
 
@@ -236,16 +261,49 @@ roof, and so does a building a tile's buffer cuts short.
 
 ## Light and shadows
 
-`threeDimensional.lighting` defaults to `'style'`: it uses MapLibre's `light` position,
+Sun lighting and cast shadows are SDK defaults, including for Streets. Each map can choose its
+own finish. For native extrusion lighting, sharp corners and no shadows in an extending map:
+
+<!-- docs:check -->
+
+```ts
+import {defineMap, refine} from '@tileflow/core';
+import {streets} from '@tileflow/maps';
+
+export default defineMap({
+  id: 'graphic-streets',
+  name: 'Graphic streets',
+  version: 1,
+  extends: streets,
+  modules: {
+    buildings: refine({
+      threeDimensional: {lighting: 'style', edgeRadius: 0, shadows: false, occlusion: false},
+    }),
+  },
+});
+```
+
+Select `timeOfDay` through your map adapter to change the authored direction, colour and strength
+of direct and ambient light. Streets includes moonlight and shadows in its night presets. These
+presets are independent of the user's clock and location. In DevTools, use the 3D view and
+**Map → Buildings → Building light / Cast shadows**. The theme's `lighting.sun.shadowIntensity`
+controls shadow strength; `lighting.ambient` fills the shade. Use `controller.setSun({date,
+location})` for an astronomical direction instead, as described in
+[sun and light](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/sun-and-light.md).
+
+`threeDimensional.lighting: 'style'` uses MapLibre's `light` position,
 anchor, colour and intensity, together with the authored extrusion's `verticalGradient`.
 Changing the scene sun does not change this base lighting. The style's native lighting defaults
 apply when it declares no light.
 
-With `lighting: 'sun'`, the light comes from `controller.getSun()`: the theme's sun, mixed during a blend, or the sun an
+With the default `lighting: 'sun'`, the light comes from `controller.getSun()`: the theme's sun, mixed during a blend, or the sun an
 application places by direction or by date and place (see
 [sun and light](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/sun-and-light.md)).
+Without a controller, the renderer reads the compiled style's sun, falling back to the style's
+light direction and then the SDK daylight. It refreshes this cached light on style changes.
 A sunlit roof keeps the building's colour, a wall turned to a low sun glows, and shade takes the
-sky's colour. As the sun sets, shadows lengthen while they fade; a sun below the horizon casts none.
+sky's colour. Shadows lengthen as the sun lowers, with their projected direction limited to 15°
+above the horizon. The actual light retains its authored altitude; a sun below the horizon casts none.
 
 A wall sees half the sky, so at night, when the ground gives back little light, walls in shade
 stay darker than roofs. A theme's night `lighting.sun` set high (60° or more) lights roofs more than
@@ -297,15 +355,37 @@ download.
 
 ## Options
 
-The renderer's own options say only how it is delivered: `minzoom` (14.5 by default), `maxTiles`,
+The renderer's own options say only how it is delivered: `minzoom` (15 by default, with a 0.25-zoom opacity ramp), `maxTiles`,
 `beforeId` to place the layer before another one, and `transformRequest` to apply the map's request
 rules to the tiles it reads.
 
 ## Cost
 
-The shadow map (up to 4096 × 4096) is drawn again only when the sun, the buildings or their height
-change, not when the camera moves. In a campaign over Miami at 1512 × 860 at 2×, a city lit this
-way kept the frame pacing of the same city drawn without shadows.
+During partial opacity, a depth-only geometry pass resolves the nearest surfaces before colour
+blending, preventing rear walls from bleeding through. At full opacity only the normal geometry
+pass runs; zoom fading schedules no extra animation frames or per-zoom mesh rebuilds.
+
+The browser bundle prepares building meshes in one worker per renderer and transfers the finished
+vertex and index buffers. No worker URL or extra asset hosting is needed. A Content Security Policy
+must allow `worker-src blob:` to use this path; if workers are unavailable or blocked, the renderer
+falls back to local meshing. The worker is terminated on `dispose()`. Pending tile updates retain
+the previous mesh until their replacement is ready; cancelled and obsolete results are discarded.
+
+Mercator rendering batches buildings spatially and skips batches outside the camera. Shadow
+casting uses the light's bounds independently, so an offscreen building can still cast a visible
+shadow. Ground contact and flood bands retain their physical reach when testing visibility.
+Rounded corners use fewer segments when their screen radius is small and retain the original
+tessellation up close. Latitude, radius and pitch inform this choice; very oblique views keep full
+detail. Changes are prepared asynchronously; heights, feature colours,
+and the contact-shadow settings stay the same. GPU uploads remain limited to two tiles per frame.
+
+The shared shadow map is at most 4096 × 4096. On a planar view it concentrates resolution on visible
+ground and raised surfaces, while every loaded caster can still project into that area. A snapped
+Mercator texel grid stays stable during small pans, including changes of latitude, without fixing
+the meshes' physical metre scale. One filtered depth comparison keeps edges sharp.
+Missing camera capabilities, terrain or a view near the horizon use the full loaded area instead.
+The depth pass runs again when its focused area, light or casting geometry changes and is reused
+when they stay unchanged.
 
 ## Limits
 
@@ -317,5 +397,6 @@ way kept the frame pacing of the same city drawn without shadows.
 - A colour expression is evaluated at zoom 16.
 - Building models and landmarks take no edges or night light of their own yet, and cannot be
   picked or styled by state.
-- Hosted deploys do not take a map's own model files yet: `tileflow validate --target hosted` reports
-  them. Models named by `url` deploy as they are.
+- A hosted map takes up to 64 building models of its own, 32 MiB once prepared; `tileflow deploy`
+  uploads them with the map. A deploy with `--with-native` does not take them, since MapLibre Native
+  draws no models. Models named by `url` deploy as they are.

package/docs/cartographic-defaults.md

@@ -0,0 +1,142 @@
+# Cartographic defaults
+
+Start with the [Core guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/README.md)
+for installation and a complete map. Semantic modules supply a coordinated starting appearance;
+module styles and owner-local render targets can replace those decisions.
+
+## Roads and roundabouts
+
+`roads({rampOrder: 'below-roads'})` draws ramp fills before receiving carriageways in the same
+surface, bridge or tunnel band. This prevents a rounded ramp endpoint covering the receiving
+road. Choose `'by-class'` to retain class-based fill order instead. Explicit render-stack moves
+remain available; ramp fills have targets `roads.classes.<class>.<structure>.rampFill` when the
+separate ramp order is active. A selector refinement replaces that target's complete filter, so
+retain its ramp eligibility when writing a custom selector. Module class fill styles apply to
+both passes; a refinement of a specific `fill` or `rampFill` target changes only that pass.
+
+Core owns circular-road geometry. Physical inner and outer radii take precedence when provided
+by the source. Otherwise the ring follows the enabled class's effective surface width, including
+width treatments. The default border follows the actual casing width and gap. Hidden classes and
+surface fills do not leave orphan rings. Ring colors remain semantic palette choices, independently
+replaceable through `roundabouts.fill.strokeColor` and `roundabouts.casing.strokeColor`; they do
+not copy arbitrary per-class color curves.
+
+Metric scaling and base-2 width curves retain their native interpolation. Other width curves are
+sampled into the shared geometry curve: numeric widths target 0.1-pixel error, stopping refinement
+once intervals reach 1/32 zoom; very large widths can exceed that target. Feature-dependent width
+expressions retain authored and integer zoom stops without adaptive refinement, keeping expression
+size bounded. Their interpolation between stops is approximate, with no universal pixel-error bound.
+Step changes complete at the authored zoom, with the transition confined to the preceding 0.000001
+zoom interval. Explicit circle radius and stroke-width expressions bypass this sampling when exact
+independent behavior is required.
+
+`roundabouts.fallbackWidth` replaces only the fallback carriageway width in pixels;
+`roundabouts.borderWidth` replaces the total extra width around the ring. Existing circle styles
+can independently replace radius, stroke width, color, opacity and zoom range. For example, this
+module fragment retains geometric defaults but gives rings a deliberate fixed border:
+
+<!-- docs:check -->
+
+```ts
+import {roads} from '@tileflow/core';
+
+export const customRoads = roads({
+  rampOrder: 'by-class',
+  roundabouts: {borderWidth: 0},
+});
+```
+
+## Ground surfaces
+
+The land module draws broad cover and park surfaces before mapped grass, meadow, scrub and
+flowerbed details. Parking, sports pitches, tracks, playgrounds and zoos follow those details so
+they remain visible inside broad green polygons. Both Tileflow World and OpenMapTiles' combined
+park source follow this order. These defaults do not change the map's colors, opacity or textures.
+
+A thematic map can give a park tint more prominence through the existing render stack. This
+module fragment is ready to use as `modules.land` in a map:
+
+<!-- docs:check -->
+
+```ts
+import {land, refineRenderTarget, withRenderStack} from '@tileflow/core';
+
+export const thematicLand = withRenderStack(land(), {
+  parkTint: refineRenderTarget({
+    target: 'land.landcover.urbanPark.fill',
+    placement: 'above-land',
+  }),
+});
+```
+
+Refinements target contributions that the map actually draws. Disabling a target and retaining
+a refinement for it is an authoring error. Disabling the whole module removes its contributions
+and its render stack. The built-in surface order needs no target anchors and works when individual
+surfaces are hidden.
+
+## Street names on the ground or in the foreground
+
+`labels({roadPlacement: 'foreground'})` is the default. Names draw above buildings and vegetation.
+Use `roadPlacement: 'ground'` to draw them below buildings, with text aligned to the map surface.
+Shields and junction numbers remain in the foreground. Ground placement does not require the
+buildings module: street names still draw when buildings are disabled.
+
+This module fragment keeps the normal language selection and road-class filters while opting
+into ground names. Individual symbol styles can override the default text alignment:
+
+<!-- docs:check -->
+
+```ts
+import {labels} from '@tileflow/core';
+
+export const groundLabels = labels({
+  roadPlacement: 'ground',
+  collisionPriority: 'navigation',
+  language: 'local',
+  roads: 'all',
+  styles: {
+    roads: {
+      primary: {text: {pitchAlignment: 'viewport'}},
+    },
+  },
+});
+```
+
+MapLibre offers foreground symbols first when resolving collisions. Ground names therefore yield
+to POIs and other foreground symbols, even with `collisionPriority: 'navigation'`. Navigation
+priority still orders the ground road classes relative to one another; it does not make their
+collision priority independent of drawing order. Foreground placement retains the existing
+navigation priority over ordinary POIs. Neither mode turns collision detection off.
+
+Use a refinement on `labels.roads.<class>` to move an individual class after this default has been
+applied. Symbol size, zoom range, spacing, priority, fonts and halos remain available in
+`styles.roads`. The same names, language fallbacks and class selectors are used in both modes.
+
+## Discover and override decisions
+
+`tileflow describe labels --json` exposes the installed options, and `tileflow inspect --json`
+shows resolved inheritance and merge provenance. `tileflow explain --inspection --json` adds
+compiled semantic targets and physical provenance. These commands describe the authored map;
+they do not rewrite explicit style choices.
+
+`tileflow describe themes --json` lists the twelve required base color roles and composition
+rules. A [single independent theme](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/themes-and-module-styles.md)
+needs no time-of-day catalog. Optional color roles derive from that theme and accept explicit
+replacements. Removing inherited lighting uses `reset()` inside `defineTheme`; it restores the
+SDK fallback, while building shadows and occlusion have separate on/off controls.
+
+`createStyleResult()` and `tileflow inspect compiled --json` include `report.decisions`: actual
+color roles and selected road, label and 3D-building policies, each with its value, source,
+reason and override guidance. Query `--path /report/decisions --limit 80` to bound this output.
+`default` means an SDK fallback, `map` a value in the resolved map, `theme` a role defined by the
+selected theme and `derived` an optional role computed by Core. Use config inspection's merge
+provenance to distinguish inherited map values from leaf overrides. These decisions describe
+module policies and the theme's color context; later module styles and render-stack refinements
+can override them. They are not a trace of every final paint property or a visual-quality score.
+Simple `createStyle()` and browser drawing do not collect this report.
+
+Replace an inherited module with its constructor, patch it with `refine()`, restore an inherited
+value with `reset()`, or remove the whole domain with `disable()`. See the
+[authoring model](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/authoring-model.md)
+for these composition rules. Capture contrasting designs and compare them at matching cameras to
+check both the default result and intentional departures from it.

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:
 
@@ -408,6 +408,58 @@ labels default to line placement. Band fills still consume `min_depth` and `sort
 `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

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/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: