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

package/docs/shared-visual-primitives.md

@@ -1,101 +0,0 @@
-# Shared visual primitives
-
-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.
-
-The same small visual language is reused across every geographic domain. This keeps an agent from
-having to learn different spellings for the same MapLibre behavior:
-
-- `BackgroundStyle`: color, opacity, pattern, visibility, and zoom range.
-- `FillStyle`: color, opacity, pattern, antialiasing, visibility, and zoom range.
-- `LineStyle`: color, width, opacity, dash, blur, gap, offset, pattern, caps, joins, and zoom range.
-- `LineHatchStyle`: repeated diagonal detail with color, opacity, spacing, size, angle, and zoom
-  range for a road structure.
-- `TextStyle`: field, exact font face, exact fallback faces, size, color, halo, line-fitted
-  background, spacing metrics, transform, collision policy, rotation, fixed/variable anchoring, line
-  constraints, and zoom range.
-- `IconStyle`: image, size, color, halo, rotation/alignment, collision policy, and zoom range.
-- `CircleStyle`: radius, fill/stroke appearance, blur, opacity, pitch behavior, and zoom range.
-- `ExtrusionStyle`: color, height, base, opacity, pattern, vertical gradient, and zoom range.
-
-Compounds express common cartographic structures: `AreaStyle` has `fill` and `outline`,
-`LineStackStyle` has `shadow`, `casing`, and `fill`, and `SymbolStyle` combines placement with
-optional `text`, `icon`, and `marker`. Geographic selection remains owned by semantic modules;
-ordinary visual styles intentionally do not accept raw source filters.
-
-## Symbol overlap modes
-
-`text.allowOverlap` and `icon.allowOverlap` either hide a part that collides with a symbol placed
-before it or always show it. `overlap` selects one of three modes instead:
-
-- `never`: hide the part when it collides.
-- `always`: show the part even when it collides.
-- `cooperative`: show the part unless it collides with a symbol placed with `never`. It may overlap
-  symbols placed with `always` or `cooperative`.
-
-MapLibre places symbols from the top layer down, so a symbol placed before another is usually higher
-in the stack. `overlap` takes precedence over `allowOverlap` on the same part, including an
-`allowOverlap` default supplied by a module or already present on a refined target, so the compiled
-layer carries only `text-overlap` or `icon-overlap`. MapLibre Native has no overlap modes, so native
-artifact preparation replaces the mode with the matching `text-allow-overlap` or
-`icon-allow-overlap`: `false` for `never` and `true` for `always` and `cooperative`. There a
-cooperative part no longer gives way to symbols placed with `never`. The
-[canopy grove recipe](data-is-separate-from-design.md) uses a cooperative text to decide where
-icons draw.
-
-## Line-fitted text backgrounds
-
-`text.background` draws one opaque strip behind each shaped line of a label, fitted to that line's
-own width. Use it for captions whose lines differ in length, where a stretched icon plate
-(`icon.textFit`) would cover the whole block.
-
-<!-- docs:check -->
-
-```ts
-import {fixed, poi, zoom} from '@tileflow/core';
-
-export const captions = poi({
-  categories: ['arts-entertainment'],
-  styles: {
-    'arts-entertainment': {
-      text: {
-        background: {
-          color: fixed('#080E11', {reason: 'Caption strip'}),
-          fit: 'lines',
-          padding: 0.33,
-        },
-        color: fixed('#ECEEE9', {reason: 'Caption text'}),
-        font: fixed('Noto Sans Bold', {reason: 'Caption face'}),
-        letterSpacing: fixed(0.08, {reason: 'Caption tracking'}),
-        lineHeight: fixed(1.2, {reason: 'Caption leading'}),
-        size: zoom.linear([
-          [14, 11],
-          [18, 14],
-        ]),
-      },
-    },
-  },
-});
-```
-
-Tileflow lowers the background to MapLibre properties only. `text-font` becomes a derived stack,
-such as `Noto Sans Bold lines-v1-t80-l1200-p330`. Its glyphs keep the source advances and shapes and
-add a rectangular cell, which the text halo paints. The halo width tracks `text-size / 6`, including
-zoom curves. Shaping, wrapping, collision, variable anchors, fading and right-to-left text therefore
-stay native, and the compiled style needs no runtime extension.
-
-- The colour must be opaque. Neighbouring cells overlap where they join.
-- `font` must name one stack served by the map's `glyphs` provider, without `fallbacks`. Maps that
-  use browser-rendered `fonts` reject backgrounds.
-- `letterSpacing` and `lineHeight` must be constants. The derived stack encodes them in thousandths
-  of an em, and the layer uses those rounded values. Tracking runs from 0 to 0.5em, leading from 0.8
-  to 3 and padding from 0 to 1em.
-- The background replaces the text halo. While a background is active, `haloWidth` and `haloBlur`
-  are derived, and `haloColor` is the strip colour. Later refinements of size, tracking, leading or
-  font re-derive the stack and halo.
-- Collision still reserves the shaped block. Padding beyond it is drawn outside that box, so keep
-  `padding` (text padding) at least as large as the strip padding in pixels.
-
-The map's `glyphs` provider must serve derived stacks. `deriveTileflowLineBackgroundGlyphs`
-computes any range from the source stack's range, and `parseTileflowLineBackgroundFontStack`
-recognises derived requests. Local previews and captures derive ranges themselves; hosted and
-self-hosted providers must do the same.

package/docs/street-lights.md

@@ -1,127 +0,0 @@
-# Street lights
-
-`createTileflowStreetLights` lights a Tileflow map's streets at night from its own vector tiles. The
-lamps the map's data holds shine where they stand, each with a pool of light on the ground and a
-glowing head. Streets and pavements the data maps as lit, but whose lamps it does not hold, take a
-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.
-
-React, Vue and Svelte maps light a map that enables street lights automatically, as part of its
-[3D scene](buildings-3d.md#the-maps-3d-scene); the 2D view has no street lights.
-
-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.
-
-## 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, with `roads.streetLights.enabled: true` in its map
-definition and a theme controller for it:
-
-<!-- docs:check -->
-
-```ts
-import {
-  createTileflowStreetLights,
-  type TileflowStreetLightsMap,
-  type TileflowThemeController,
-} from '@tileflow/core/browser';
-
-export function lightTheStreets(map: TileflowStreetLightsMap, controller: TileflowThemeController) {
-  // The lights switch on as the theme's or the application's sun darkens the map.
-  return createTileflowStreetLights({map, controller});
-}
-```
-
-The lights follow `controller.getSun()`: they switch on as its `brightness` falls through dusk, each
-lamp at its own moment, and are all on at night. A theme whose night has no `lighting.sun` keeps
-the default daylight sun, so its lights stay off; see
-[sun and light](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/sun-and-light.md).
-`on` reports how far they have switched on, from 0 to 1, `stats` the lamps on screen, and
-`dispose()` takes the layer off the map.
-
-## What the light comes from
-
-The layer reads the source's z15 tiles round the camera, the zoom at which World carries its street
-detail:
-
-- Lamps from World's `street_furniture` points whose `subclass` is `street_lamp`. Where the data
-  gives them, a lamp's `height`, `lamp_mount`, `light_count`, `lamp_type` and `light_colour` set how
-  high it stands, how far its light reaches and its colour: sodium lamps shine orange, LED and
-  metal-halide lamps white. Other lamps take the map's light colour.
-- Streets in World's `transportation` layer, and pavements in its `sidewalk` layer, that the data
-  maps as lit (`lit`). A street mapped as unlit never takes light.
-
-How much of this a city's data holds varies widely: some map most of their lamps or most of their
-lit streets, others almost none. Where the data says nothing, the streets stay dark.
-
-## Design the lights in the map
-
-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 an enabled description the renderer stays off and mounts no layer:
-
-<!-- docs:check -->
-
-```ts
-import {defineMap, fixed, refine} from '@tileflow/core';
-import {streets} from '@tileflow/maps';
-
-export default defineMap({
-  id: 'night-city',
-  name: 'Night city',
-  version: 1,
-  extends: streets,
-  modules: {
-    // Sodium-orange light, a little brighter, on every street of tiles that map few lamps.
-    roads: refine({
-      streetLights: {
-        enabled: true,
-        color: fixed('#ffb35c', {reason: 'Constant sodium-lamp color.'}),
-        intensity: 1.3,
-        estimate: 'streets',
-      },
-    }),
-  },
-});
-```
-
-`estimate` chooses where the layer adds light the data does not map as lamps:
-
-- `lit` (the default): along the streets and pavements mapped as lit.
-- `streets`: also along streets the data says nothing about, in tiles where the data maps few
-  lamps. This invents light, as night windows do, for maps that want every street lit; a tile whose
-  data maps its lamps keeps to them.
-- `none`: only mapped lamps shine.
-
-Estimated light keeps to the middle of its street and shows no lamp head, so it reads as a lit
-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. These settings apply only after `enabled: true`; `streetLights: {enabled: false}` gives
-the map none.
-
-## Options
-
-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.
-
-Layers that read the same source share each tile's download, so the street lights and the 3D
-buildings fetch a tile once between them. The lamps are placed in the worker the page's 3D layers
-share, which decodes each tile once for all of them.
-
-## Limits
-
-- Mercator only; the layer draws nothing below its `minzoom`.
-- The light falls on the ground; walls the lamps face are not lit by them.
-- No terrain: lamps stand on flat ground.

package/docs/street-sky.md

@@ -1,156 +0,0 @@
-# Street sky
-
-A map's `sky` paints the sky above the horizon when the camera tilts up the street, in either
-projection: blue by day, warm at dusk, dark with stars at night. Install `@tileflow/core` and
-`@tileflow/maps` and use a browser adapter from the same compatible SDK release. Streets declares a
-sky in every theme; the example extends it and keeps its sky.
-
-<!-- docs:check -->
-
-```ts
-import {defineMap} from '@tileflow/core';
-import {streets} from '@tileflow/maps';
-
-export default defineMap({
-  id: 'street-level',
-  version: 1,
-  extends: streets,
-  view: {center: [-3.6904, 40.4493], zoom: 17, bearing: 8, pitch: 80},
-});
-```
-
-The view looks north along Paseo de la Castellana in Madrid, with the sky above the skyline.
-Coordinates are longitude, then latitude.
-
-## Camera pitch
-
-React, Vue, Svelte, the Dev preview, and browser capture create maps with a maximum pitch of 85
-degrees, `tileflowMaxPitch`, instead of MapLibre's default of 60. Every portable view already admits
-pitch 0–85. Pass `mapOptions: {maxPitch}` to lower the limit for one map. A map constructed directly
-with MapLibre keeps MapLibre's default unless it sets `maxPitch: tileflowMaxPitch` itself.
-
-The React Native surface still uses the native engines' 60-degree limit.
-
-## Configure the sky
-
-`sky: true` uses the defaults. An options object replaces an inherited sky atomically, and
-`sky: false` removes it.
-
-| Option          | Default   | Meaning                                                           |
-| --------------- | --------- | ----------------------------------------------------------------- |
-| `color`         | `#5c9ce6` | The sky overhead                                                  |
-| `horizonColor`  | `#dcebf7` | The pale band along the horizon, also 3D terrain's distance fog   |
-| `horizonBlend`  | `0.6`     | How far up the band reaches, as a share of half the view's height |
-| `glowColor`     | `#ffc68a` | The light round a low sun, which glows on the horizon towards it  |
-| `starIntensity` | `0.6`     | The brightest the stars shine, from 0 (none) to 1                 |
-
-Colors take `token.color(...)`, color operations, or `fixed(color, {reason})`, and must resolve to
-opaque colors. Numbers take `token.number(...)`, `fixed(number, {reason})`, or a number, and must
-resolve to 0–1. Unknown properties are rejected. Because tokens resolve per theme, one declaration
-gives each theme its own sky. Streets uses its themes' `sky.color`, `sky.horizon`,
-`sky.horizonBlend`, and `sky.glow` tokens:
-
-```ts
-sky: {
-  color: token.color('sky.color'),
-  horizonColor: token.color('sky.horizon'),
-  horizonBlend: token.number('sky.horizonBlend'),
-  glowColor: token.color('sky.glow'),
-  starIntensity: 0.6,
-},
-```
-
-A map that replaces Streets' themes supplies those tokens or declares its own `sky`.
-
-## A sky that follows the sun
-
-When an application places the sun with the theme controller's `setSun`, by direction or by the
-real sun of a date and place, the sky follows its height continuously instead of staying on the
-theme's preset. Above about 14 degrees the sky is the day theme's; it warms into the dawn or dusk
-theme's sky as the sun nears the horizon, using dawn while the sun stands in the eastern half of
-the sky and dusk in the western half; it holds that sky within two degrees of sunrise or sunset,
-and it darkens into the night theme's sky as twilight ends, about ten degrees below the horizon.
-The themes come from the map's `timeOfDay` family of the theme on screen, and every colour is
-resolved from that theme's own tokens, so a Monochrome family stays grey and a client's own
-family keeps its palette. A family with only one twilight uses it at both ends of the day; a theme
-outside a family, or a family without a day and a night theme, keeps its own sky.
-`setSun(undefined)` returns the sky to the themes. The map's colours on the ground stay those of
-the theme or blend on screen; pair `setSun` with `setBlend` to move them too. See
-[sun and light](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/sun-and-light.md).
-
-<!-- docs:check -->
-
-```ts
-import type {TileflowThemeController} from '@tileflow/core/browser';
-
-export function sunsetOverMadrid(controller: TileflowThemeController) {
-  // 19:15 in Madrid on 21 October 2026: the sun stands 1.5 degrees above the western horizon.
-  return controller.setSun({date: Date.UTC(2026, 9, 21, 17, 15), location: [-3.69, 40.45]});
-}
-```
-
-## Glow, sun and stars
-
-A low sun glows on the horizon towards it, in the theme's `glowColor` or, for a sun an application
-placed, in the glow of its hour. The glow is strongest as the sun touches the horizon, fades by
-mid-morning, and is gone once the sun is about nine degrees below. While the sun is low and above
-the horizon, its disc shows too. The sun is the one the theme controller shows, so its
-disc stands where the 3D scene's shadows say it is; without a controller, the theme's own sun.
-
-Stars come out as the sky darkens: a night sky shows them, a day or dusk sky does not, and a
-time-of-day blend or a placed sun moving into night brings them in with the dark. They sit on a
-fixed dome, so they turn with the camera's bearing and pitch but not with its position.
-
-The glow, the sun, and the stars draw beneath every map layer and only where nothing else has
-drawn, so buildings and trees stand in front of them. With 3D terrain enabled, they are not
-drawn.
-
-## Distance haze
-
-Above 45 degrees of pitch, the far city fades into the sky's horizon color, so streets meet the sky
-instead of ending in a sharp edge. The haze starts at the camera's distance to the map's center and
-is complete where MapLibre stops drawing the ground, about 6.7 times farther, where the sky starts in
-the same color. It comes in between 45 and 60 degrees, follows the current sky (theme blends
-and a sky that follows the sun included), and leaves the globe alone. Place and POI labels above the
-3D layers stay clear.
-
-Tileflow's 3D buildings stand on the tiles round the camera, up to a limit of 25 by default, which
-end well before the horizon. Where that ring ends nearer than the horizon, the haze fits itself to
-it: it is nine-tenths complete at the nearest point where the ring's far side shows across the view,
-and complete soon after, never nearer than three camera distances for the nine-tenths, so a renderer
-held to few tiles does not pull the haze in. Buildings on the ring's far side sink into the ground
-over its last fifth, and nothing past the ring or past the complete haze is drawn. Buildings on the
-near side of a ring held short by the tile limit keep standing.
-
-The haze is drawn twice, from one model: Tileflow's 3D buildings, trees, and placed models haze
-each pixel by its depth, and a band over the flat map, just under the first 3D layer, hazes the
-flat ground by the depth its screen row has. Road names and one-way arrows that a style draws on the
-ground before its 3D layers fade with the ground, and so do distant 3D shadows, contact shade, and
-night floodlight. A style without a sky, or whose sky has no opaque horizon color, has no haze.
-
-## Browser integration
-
-The compiler emits MapLibre `sky` in every concrete style and versioned `metadata['tileflow:sky']`
-with the star brightness, the glow, and, for a theme in a time-of-day family, the family's skies;
-`readTileflowSky` reads it and `tileflowSkyAtSun` mixes the sky of a sun's height. MapLibre draws the sky itself, so raw MapLibre consumers see it. On a
-globe, the sky blends into MapLibre's atmosphere at world zooms; when a map also declares
-`atmosphere`, the sky's colors replace the atmosphere's sky colors while its space background and
-globe stars stay.
-
-React, Vue, Svelte, and standalone browser capture draw the glow, the sun, the stars, and the flat
-map's haze through `attachTileflowAtmosphere(map)`. A direct MapLibre integration calls that
-function, or `attachTileflowSky(map)` or `attachTileflowSkyHaze(map)` from `@tileflow/core/browser`
-for one of them alone, after constructing the map; each returns a cleanup function. The sky is the
-custom layer `tileflow-sky` at the bottom of the layer stack, and the haze the custom layer
-`tileflow-sky-haze` under the first 3D layer, or the first label layer without one. Tileflow's 3D
-layers haze themselves. A sky that follows the sun needs the theme controller, which writes the
-sky's colours; raw MapLibre consumers see each theme's own sky.
-
-These helpers can attach before the first style is set. They wait for style events, follow style
-replacements, and tolerate a cleared style. Dispose them when the integration releases the map.
-
-MapLibre applies its own fog only to 3D terrain; with 3D terrain enabled, the flat haze band is not
-drawn and the terrain's fog takes its place. Other layers drawn by an application, such as
-`fill-extrusion` layers, stay sharp. Native artifacts remove the sky during preparation and record
-the removal; see the
-[native artifact profile](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/native-artifact-profile.md).

package/docs/style-states.md

@@ -1,73 +0,0 @@
-# Style states
-
-A theme can read a value that the application sets once for the whole style, such as whether
-anything is selected. The theme reads it with `expr.globalState(name)`; the application sets it with
-the theme controller's `setState(name, value)`. MapLibre calls these values global state (GL JS 5.6
-or later).
-
-## Read a state in a theme
-
-A state reads `null` until the application sets it, so wrap it in a typed assertion with a fallback.
-To let a value move smoothly, make the state a number and interpolate on it:
-
-<!-- docs:check -->
-
-```ts
-import {expr} from '@tileflow/core';
-
-// 0 shows the standing highlight, 1 the quiet plate; values between mix the two.
-const selection = expr.toNumber(expr.globalState('selection'), 0);
-export const captionPlate = expr.interpolate({kind: 'linear'}, selection, [
-  [0, '#ef5f57'],
-  [1, '#fff9ee'],
-]);
-```
-
-A boolean works too, through `expr.case`, but it can only switch.
-
-## Set a state from the application
-
-This example assumes an existing MapLibre map named `map` that shows the `light` theme of a
-published Tileflow map:
-
-<!-- docs:check -->
-
-```ts
-import {createTileflowThemeController, type TileflowStyleSwitchMap} from '@tileflow/core/browser';
-
-// A MapLibre map satisfies TileflowStyleSwitchMap.
-export function selectionStates(map: TileflowStyleSwitchMap, styleUrl: string) {
-  const controller = createTileflowThemeController({
-    initial: {style: styleUrl, theme: 'light'},
-    map,
-  });
-  void controller.setState('selection', 0);
-  return {
-    select: () => controller.setState('selection', 1, {transition: {duration: 300}}),
-    clear: () => controller.setState('selection', 0, {transition: {duration: 300}}),
-  };
-}
-```
-
-A number eases from the value the map shows to the new one over the transition, so the plate mixes
-smoothly from one colour to the other. Booleans, strings, `null`, and a number set for the first
-time change at once, so set a starting value before easing it. A browser preference for
-reduced motion changes at once. Each call supersedes an easing of the same state still in progress,
-which resolves with `status: 'superseded'`; the new easing starts from where the old one stood.
-
-States stay through `setTheme` and every `setBlend`: the controller writes them again after each
-new style. `getState(name)` returns the value set last.
-
-## Keep eased values free of feature data
-
-Keep a value that eases on a state free of feature data and feature state. MapLibre evaluates such
-a value for the whole layer at each frame. A value that also reads a feature's data or state is
-evaluated per feature when its tiles are laid out, so each change of the state lays them out
-again: the value follows late, in steps, and each frame costs far more. Put the per-feature choice
-in another layer, or let the application draw the feature it marks.
-
-## Cost
-
-Each frame of an easing sets the state once, and MapLibre then evaluates again every paint value
-that reads it. A state read by a few layers costs little; a state read by most layers of a map can
-cost more per frame than the blend itself on slower devices.

package/docs/sun-and-light.md

@@ -1,167 +0,0 @@
-# Sun and light
-
-A theme can describe its sun and the light from its sky, as a light preset for that theme: a high
-sun in white light for a day theme, a low amber sun in the west for an evening theme, a cold moon
-with faint shadows for a night theme. In a browser, the theme controller returns the sun the map
-shows, mixed between neighbouring themes during a blend, so an application's own 3D layers can light
-their models and cast their shadows from it. An application can also place the sun itself, by
-direction or by the real position of the sun for a date and place.
-
-MapLibre lights its `fill-extrusion` layers with one directional light and casts no shadows. When a
-theme describes a sun, the map's light is anchored to the map and points from the sun, so Tileflow's
-3D buildings are shaded from where it stands. Shadows, ambient occlusion and lit windows are for the
-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.2, full
-shadow strength, a white sky at 0.8 for soft daylight shadows):
-
-<!-- docs:check -->
-
-```ts
-import {defineTheme} from '@tileflow/core';
-import {streetsThemes} from '@tileflow/maps';
-
-export const evening = defineTheme(streetsThemes.dark, {
-  id: 'city-evening',
-  version: 1,
-  colorScheme: 'dark',
-  lighting: {
-    // Degrees clockwise from north, and above the horizon.
-    sun: {azimuth: 285, altitude: 9, color: '#ff9a50', intensity: 1, shadowIntensity: 0.9},
-    ambient: {color: '#5a4290', intensity: 0.3},
-  },
-});
-```
-
-`intensity` values run from 0 to 1. `shadowIntensity` says how dark the shadows the sun casts fall,
-from 0 (none) to 1. A theme derived from another changes single values of its sun and sky light; the
-others are inherited. The compiled style carries the resolved sun in its metadata
-(`tileflow:sun`) and a map-anchored `light` that points from it; MapLibre's `anchor` and the
-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:
-
-- `azimuth` and `altitude`, in degrees, and `direction`, a unit vector towards the sun with x east,
-  y north and z up.
-- `color` and `rgb` (sRGB channels from 0 to 1) of the direct light, and its `intensity`, which fades
-  to 0 over the sun's last degrees above the horizon: a sun below it lights nothing.
-- `ambient`, the light from the sky, with its own `color`, `rgb` and `intensity`.
-- `shadowIntensity`, how dark the sun's shadows fall.
-- `brightness`, how bright flat, open ground is under this light, from 0 to 1: the sky's light plus
-  the sun's at its height, each weighted by its colour's luminance. Use it to switch lamps or windows
-  on as a scene darkens, whatever theme or sun lights it.
-- `source`: `theme`, `direction`, or `date`.
-
-During a blend the sun is mixed between the neighbouring themes' suns: the azimuth turns the short
-way round, colours mix in OKLab as the map's colours do, and numbers mix linearly. Read it when a
-custom layer draws; the map redraws whenever the sun changes.
-
-## Place the sun
-
-`setSun` places the sun by direction, or by the real sun of a date over a place given as
-`[longitude, latitude]`, the map's centre when it is left out. The themes keep the sun's colours,
-strengths and shadow strength; only its direction changes. A map with a
-[street sky](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/street-sky.md)
-also takes the sky of the sun's hour from its time-of-day themes. `setSun(undefined)` returns both
-to the themes. This example assumes an existing MapLibre map and a controller for it:
-
-<!-- docs:check -->
-
-```ts
-import type {TileflowThemeController} from '@tileflow/core/browser';
-
-export function followTheRealSun(controller: TileflowThemeController) {
-  // Where the sun stands over Miami Beach now; a later call moves it on.
-  void controller.setSun({date: Date.now(), location: [-80.13, 25.79]});
-}
-
-export function lowWesternSun(controller: TileflowThemeController) {
-  // Turns the short way round to the west over a second.
-  return controller.setSun({azimuth: 270, altitude: 8}, {transition: {duration: 1000}});
-}
-```
-
-A request that follows an animation, such as a clock that moves every frame, passes no transition.
-A request with a transition supersedes one still in progress, which resolves with
-`status: 'superseded'`; a browser preference for reduced motion changes at once.
-
-`tileflowSunPosition(date, [longitude, latitude])` returns the sun's azimuth and apparent altitude,
-with atmospheric refraction, from NOAA's solar equations (accurate to about a hundredth of a degree
-for years 1800 to 2200). It runs anywhere, without a map:
-
-<!-- docs:check -->
-
-```ts
-import {tileflowSunPosition} from '@tileflow/core/browser';
-
-// Solar noon in Miami at the June solstice, 17:22 UTC: the sun stands about 87.7° high, due south.
-export const noon = tileflowSunPosition(Date.UTC(2026, 5, 21, 17, 22), [-80.19, 25.77]);
-```
-
-## Light a custom layer
-
-For a custom WebGL layer that draws 3D content, light each surface with the sky's light, plus the
-sun's where the surface faces it and nothing stands in the way:
-
-    light = ambient.rgb × ambient.intensity + rgb × intensity × max(normal · direction, 0) × (1 − shadowIntensity × shadowed)
-
-Convert the colours to linear light before adding them and back to sRGB after. MapLibre's own 2D
-layers take no shadows, so a layer that casts shadows on the ground darkens the map it is drawn over:
-draw the ground under the scene, after the scene's own geometry, with multiplying blending and a
-depth test against it.
-
-## Limits
-
-- MapLibre shades extrusions with its one light; it has no shadow maps, ambient occlusion or
-  emissive light. The sun gives custom layers what they need to draw them.
-- Themes interpolate the sun linearly between presets; a request by date follows the real sun, not
-  the themes' presets.
-- Style expressions cannot read the sun yet. An application that wants a theme to react to it sets a
-  [style state](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/style-states.md)
-  from `getSun().brightness`.