@tileflow/core 0.1.0-alpha.38 → 0.1.0-alpha.39

package/docs/nautical-marks.md

@@ -1,10 +1,12 @@
 # Nautical marks
 
 The `nautical` module draws navigation marks from a `nautical-v1` vector source: buoys, beacons,
-lighthouses, lights, rocks and other hazards, wrecks, reefs, navigation areas, routes, cables,
-harbours, ports, and a restrained indication of where a provider publishes marks. It is reference
-cartography for general-purpose maps. It is not a nautical chart, and a map that draws it always
-shows a "Not for navigation" notice.
+lighthouses, lights that flash in their rhythm, rocks and other hazards, wrecks, reefs, navigation
+areas, routes, submarine and overhead cables, bridges with their clearances, harbours, marinas,
+berths, small-craft facilities, inland notice boards, waterway distance marks, ports, and a
+restrained indication of where a provider publishes marks. It is reference cartography for
+general-purpose maps. It is not a nautical chart, and a map that draws it always shows a "Not for
+navigation" notice.
 
 ## Enable Nautical on a map
 
@@ -100,19 +102,25 @@ displayed.
 Every feature carries `provider`, `provenance`, `edition`, `coverage`, `licence`, and `min_zoom`,
 the first zoom at which the feature appears. `rank` (1 is the most important feature of its layer)
 and `name` are optional. Colours are S-57 colour names, and multi-valued colours and categories are
-comma-separated in source order, for example `black,yellow`. `tileflowNauticalV1Schema` lists the
-field names, layers, and geometry types.
-
-| Source layer      | Geometry                   | Fields the module reads                                  |
-| ----------------- | -------------------------- | -------------------------------------------------------- |
-| `aid`             | Point                      | `class`, `subclass`, `category`, `color`, `rank`, `name` |
-| `light`           | Point                      | `class` (`major` or `minor`), `color`, `label`, `rank`   |
-| `hazard`          | Point, LineString, Polygon | `class`, `water_level`, `name`                           |
-| `wreck`           | Point, Polygon             | `class`, `name`                                          |
-| `reef`            | Polygon                    | `name`                                                   |
-| `navigation_area` | Point, LineString, Polygon | `class`, `size`, `rank`, `name`                          |
-| `coverage`        | Polygon                    | `families`                                               |
-| `sounding`        | Point                      | `depth`                                                  |
+comma-separated in source order, for example `black,yellow`. Clearances, depths, and heights are in
+metres. `tileflowNauticalV1Schema` lists the field names, layers, geometry types, and known
+providers: `openstreetmap` (coverage class `community`), `nga-list-of-lights` (`list`), and the
+`chart` providers `noaa-office-of-coast-survey` and `usace-ienc` (U.S. Army Corps of Engineers
+Inland ENCs). The source's TileJSON owns every provider credit.
+
+| Source layer      | Geometry                   | Fields the module reads                                                                                            |
+| ----------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `aid`             | Point                      | `class`, `subclass`, `category`, `color`, `rank`, `name`, `information`, `distance`, `distance_unit`               |
+| `light`           | Point                      | `class` (`major` or `minor`), `color`, `label`, `rank`, `character`, `group`, `period_s`, `sequence`               |
+| `hazard`          | Point, LineString, Polygon | `class`, `water_level`, `name`                                                                                     |
+| `wreck`           | Point, Polygon             | `class`, `name`                                                                                                    |
+| `reef`            | Polygon                    | `name`                                                                                                             |
+| `navigation_area` | Point, LineString, Polygon | `class`, `subclass`, `size`, `rank`, `name`, `vertical_clearance` and its `_closed`, `_open`, and `_safe` variants |
+| `coverage`        | Polygon                    | `families`                                                                                                         |
+| `sounding`        | Point                      | `depth`                                                                                                            |
+
+The Nautical source promotes each light's `provenance` as its feature ID
+(`promoteId: {light: 'provenance'}`), so lights can be animated with MapLibre feature state.
 
 Every layer filters on `min_zoom`, so a compatible source that keeps features in lower-zoom tiles
 still shows each one from its own first zoom. Point groups place a lower `rank` first.
@@ -122,26 +130,42 @@ still shows each one from its own first zoom. Point groups place a lower `rank`
 Each group is a style option of `nautical(...)`, with the same marker, symbol, area, and line style
 objects as other modules.
 
-| Option            | Draws                                                                           | Default symbology                                         |
-| ----------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------- |
-| `buoys`           | `aid` buoys, light floats, and light vessels                                    | Circle in the first colour, ringed with the second        |
-| `beacons`         | `aid` beacons and daymarks                                                      | Small circle in the first colour                          |
-| `lighthouses`     | `aid` lighthouses                                                               | Ink circle and name                                       |
-| `aids`            | Other `aid` classes, such as moorings, fog signals, and racons                  | Small hollow circle                                       |
-| `lights`          | `light` points, one per sector                                                  | Flare in the light's first colour and its chart `label`   |
-| `hazards`         | `hazard` points                                                                 | `+` for rocks, `*` for rocks that show; circled obstacles |
-| `hazardAreas`     | `hazard` polygons; the outline also strokes linear hazards                      | Accent wash with a dotted outline                         |
-| `wrecks`          | `wreck` points                                                                  | `Wk`, in the accent colour when dangerous                 |
-| `wreckAreas`      | `wreck` polygons                                                                | Ink wash with a dashed outline                            |
-| `reefs`           | `reef` polygons                                                                 | Sand wash with a dotted outline                           |
-| `navigationAreas` | `navigation_area` polygons                                                      | Dashed outlines; accent for operational areas             |
-| `routes`          | `navigation_area` lines of class `route` and `traffic-separation`               | Dashed line; accent for traffic separation                |
-| `cables`          | `navigation_area` lines of class `cable`, `pipeline`, and their area classes    | Fine dashed accent line                                   |
-| `harbours`        | `navigation_area` points of class `harbour`                                     | Ink circle and name                                       |
-| `ports`           | `navigation_area` points of class `port`                                        | Ink circle and name sized by `size`, from low zooms       |
-| `coverage`        | `coverage` polygons that cover every family                                     | Faint tint at low zooms only                              |
-| `soundings`       | `sounding` points                                                               | Depth figure                                              |
-| `labels`          | Names inside hazard, navigation-area, reef, and wreck polygons; coverage opt-in | Collision-aware text                                      |
+| Option            | Draws                                                                        | Default symbology                                         |
+| ----------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------- |
+| `buoys`           | `aid` buoys, light floats, and light vessels                                 | Circle in the first colour, ringed with the second        |
+| `beacons`         | `aid` beacons and daymarks                                                   | Small circle in the first colour                          |
+| `lighthouses`     | `aid` lighthouses                                                            | Ink circle and name                                       |
+| `aids`            | Other `aid` classes, such as moorings, fog signals, and racons               | Small hollow circle                                       |
+| `lights`          | `light` points, one per sector                                               | Flare in the light's first colour and its chart `label`   |
+| `hazards`         | `hazard` points                                                              | `+` for rocks, `*` for rocks that show; circled obstacles |
+| `hazardAreas`     | `hazard` polygons; the outline also strokes linear hazards                   | Accent wash with a dotted outline                         |
+| `wrecks`          | `wreck` points                                                               | `Wk`, in the accent colour when dangerous                 |
+| `wreckAreas`      | `wreck` polygons                                                             | Ink wash with a dashed outline                            |
+| `reefs`           | `reef` polygons                                                              | Sand wash with a dotted outline                           |
+| `navigationAreas` | `navigation_area` polygons                                                   | Dashed outlines; accent for operational areas             |
+| `routes`          | `navigation_area` lines of class `route` and `traffic-separation`            | Dashed line; accent for traffic separation                |
+| `cables`          | `navigation_area` lines of class `cable`, `pipeline`, and their area classes | Fine dashed accent line                                   |
+| `overheadCables`  | `navigation_area` lines of class `overhead-cable`                            | Dash-dot accent line                                      |
+| `bridges`         | `navigation_area` bridge polygons; the outline also strokes bridge lines     | Land-coloured deck with an ink outline                    |
+| `berths`          | `navigation_area` berth polygons; the outline also strokes berth lines       | Thin ink outline, wider and darker for `guest` berths     |
+| `harbourAreas`    | `navigation_area` harbour and marina polygons                                | Faint ink wash with a solid outline                       |
+| `harbours`        | `navigation_area` harbour points, and a symbol inside harbour polygons       | Ink circle and name; the marina token for marinas         |
+| `facilities`      | `navigation_area` facility points, polygons, and line centres, from zoom 13  | Hollow circle; facility icons from the theme              |
+| `notices`         | `aid` notice boards, from zoom 12                                            | Circle in the board's function colour and `information`   |
+| `distanceMarks`   | `aid` distance marks, from zoom 11                                           | Ink dot and distance with its unit, fainter if not posted |
+| `ports`           | `navigation_area` points of class `port`                                     | Ink circle and name sized by `size`, from low zooms       |
+| `coverage`        | `coverage` polygons that cover every family                                  | Faint tint at low zooms only                              |
+| `soundings`       | `sounding` points                                                            | Depth figure                                              |
+| `labels`          | Names inside polygons, bridge and overhead-cable clearances; coverage opt-in | Collision-aware text                                      |
+
+Bridge, berth, facility, and harbour polygons are drawn by their own groups rather than as
+navigation areas. `labels.bridges` shows `clearance 4.5 m`, or `closed 3.6 m · open 12 m` for an
+opening bridge, at bridge points, inside bridge polygons, and at the centre of bridge lines, from
+zoom 13. `labels.overheadCables` shows `safe clearance 28.5 m`, or the plain clearance, at cable
+points and along cable lines. Distance marks read `12 km`, `5 hm`, `300 m`, `12 mi`, or `4.5 NM`
+from zoom 13. Notice boards follow the CEVNI colours: red for prohibitions, regulations, and
+restrictions, green for recommendations, and blue for information; their `information`, such as a
+speed limit, appears from zoom 14. Board orientation and impact are not drawn.
 
 Operational areas are restricted, military, anchorage, anchor-berth, dumping-ground, and
 traffic-separation areas. Marks keep their conventional colours in every theme; a white light is
@@ -173,6 +197,77 @@ export default defineMap({
 });
 ```
 
+## Flashing lights
+
+In React, Vue, Svelte, and the development preview, every light with a rhythm flashes: its flare or
+circle draws at its styled opacity while the light shines and at 15 % of it during an eclipse.
+Fixed lights, lights without a usable characteristic, reduced motion, capture, native renderers, and
+static images show every light steadily, exactly as it is styled. Set `animateLights: false` to keep
+a map's lights steady everywhere:
+
+<!-- docs:check -->
+
+```ts
+import {defineMap, nautical} from '@tileflow/core';
+import {streets} from '@tileflow/maps';
+
+export default defineMap({
+  id: 'harbour-guide',
+  version: 1,
+  extends: streets,
+  marine: 'nautical',
+  modules: {nautical: nautical({animateLights: false})},
+});
+```
+
+A light flashes by its published `sequence` when it has one: light and eclipse durations in
+seconds, eclipses in parentheses, for example `0.5+(1.5)+0.5+(4.5)`. Otherwise
+`tileflowLightRhythm(properties)` derives a conventional rhythm from `character`, `group`, and
+`period_s`; `tileflowLightRhythmConventions` holds the values below.
+
+| Character                             | Rhythm                                                                                                 |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `Fl`                                  | Flashes of `min(1 s, 0.3 × period ÷ flashes)`; gaps within a group at most twice the flash             |
+| `Fl` with a group such as `2+1`       | Groups separated by twice the inner gap; the rest of the period is the final eclipse                   |
+| `LFl`                                 | The same layout with 2 s flashes, shorter only when the period cannot hold them                        |
+| `Q`, `VQ`, `UQ`                       | 60, 120, and 240 flashes a minute, lit for 30 % of each; a group of `n` flashes then eclipses          |
+| `IQ`, `IVQ`, `IUQ`                    | Quick flashes for 60 % of the period, then an eclipse                                                  |
+| `Iso`                                 | Equal light and eclipse                                                                                |
+| `Oc`                                  | Eclipses totalling 25 % of the period, laid out like `Fl`, so the light is always longer               |
+| `Mo`                                  | The Morse letter in `group`: 0.5 s dots, three-unit dashes, one-unit gaps, then the rest of the period |
+| `FFl`, `F+LFl`                        | A fixed light at half intensity with full flashes, or long flashes                                     |
+| `Q+LFl`, `VQ+LFl`, `UQ+LFl`, `Fl+LFl` | The group (six quick flashes by default), one 2 s long flash, then the eclipse                         |
+| `Oc+Fl`                               | Its occulting part                                                                                     |
+| `Al.<character>`, `Al`                | Each lit phase shows the next colour of `color`; `Al` alone shows each colour for an equal share       |
+| `F`, unknown, or missing period       | Steady; grouped `Q` and `VQ` cardinal marks without a period use the IALA periods                      |
+
+`tileflowLightStateAt(rhythm, seconds)` returns the intensity, colour index, and time to the next
+change at any moment. Lights with the same rhythm flash together.
+
+React, Vue, Svelte, the development preview, and standalone capture call
+`attachTileflowNauticalLights(map)` from `@tileflow/core/browser`. It reads the light layers the
+style declares in `metadata['tileflow:nautical-lights']`, and writes each rendered light's
+`tileflowLightIntensity` and `tileflowLightColour` feature state only when its phase changes. It runs
+one timer for the next change, and none while the page is hidden, while no light layer is visible at
+the current zoom, or under reduced motion. A direct MapLibre integration attaches it after
+constructing the map:
+
+```ts
+import maplibregl from 'maplibre-gl';
+import {attachTileflowNauticalLights, attachTileflowNotices} from '@tileflow/core/browser';
+
+const map = new maplibregl.Map({
+  container: 'map',
+  style: '/tileflow/styles/harbour-guide/light.json',
+});
+attachTileflowNotices(map);
+const detach = attachTileflowNauticalLights(map);
+// Call detach() to return every light to steady; removing the map also detaches it.
+```
+
+`steadyTileflowNauticalLights(style)` returns a copy that draws every light steadily without feature
+state; native artifact preparation applies it automatically.
+
 ## Chart symbols from the theme
 
 A theme that declares the image tokens below replaces a point group's circle marker with that icon.
@@ -190,11 +285,24 @@ Buoy variants fall back to `nautical.buoy`. `tileflowNauticalImageRoles` lists t
 | `nautical.aid`            | `aids`                                     |
 | `nautical.wreck`          | `wrecks`                                   |
 | `nautical.harbour`        | `harbours`                                 |
+| `nautical.marina`         | Harbours whose `subclass` lists a marina   |
 | `nautical.port`           | `ports`                                    |
+| `nautical.notice`         | `notices`                                  |
+| `nautical.notice.<role>`  | Notices of that function                   |
+| `nautical.distance-mark`  | `distanceMarks`                            |
+| `nautical.facility`       | `facilities`                               |
+| `nautical.facility.<cat>` | Facilities listing that category           |
+
+Notice roles are `prohibition`, `regulation`, `restriction`, `recommendation`, and `information`.
+Facility categories are `fuel-station`, `slipway`, `boat-hoist`, `pump-out`, `water-tap`,
+`visitor-berth` (also used for `visitors-mooring`), and `boatyard`: a facility listing several shows
+the first in that order (`tileflowNauticalFacilityIcons`), and the others show `nautical.facility`.
+Every icon expression selects among the declared image names only.
 
 Buoys, beacons, other aids, and lights colour their icon with the mark's own colour, so declare
 them as [SDF icons](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/docs/native-icons.md)
 that share one representation within each group. The defaults size icons for the SDF profile,
-whose drawing occupies the central 12 of 24 pixels; set `icon.size` for other artwork. Soundings
-declares these tokens with its own buoy, light, lighthouse, wreck, and harbour symbols and keeps
+whose drawing occupies the central 12 of 24 pixels; set `icon.size` for other artwork. Notice
+boards take their function colour. Soundings declares these tokens with its own buoy, light,
+lighthouse, wreck, harbour, marina, notice-board, distance-mark, and facility symbols and keeps
 beacons as coloured dots.

package/docs/public-api-and-browser-subpath.md

@@ -79,6 +79,7 @@ import {
   attachTileflowAtmosphere,
   attachTileflowFairUseNotice,
   attachTileflowMapLifecycle,
+  attachTileflowNauticalLights,
   attachTileflowNotices,
   createTileflowSessionStarter,
   createTileflowTransformRequest,
@@ -91,8 +92,8 @@ application can load them with a dynamic import when a style declares a 3D scene
 [3D buildings](buildings-3d.md#the-maps-3d-scene). The browser entry exports the same function.
 
 `attachTileflowNotices(map)` renders the notices a compiled style declares, such as Nautical's
-"Not for navigation", as a compact map control; see
-[Nautical marks](nautical-marks.md). The browser entry is not re-exported from the root. It is SSR-safe to import, has no MapLibre
+"Not for navigation", as a compact map control, and `attachTileflowNauticalLights(map)` flashes
+Nautical lights in their rhythm; see [Nautical marks](nautical-marks.md). The browser entry is not re-exported from the root. It is SSR-safe to import, has no MapLibre
 runtime dependency, and reads no browser global during module evaluation. See the
 [framework browser runtime contract](https://github.com/tileflow/tileflow-sdk/blob/main/docs/contracts/framework-browser-runtime.md) and the
 [cartographic authoring contract](https://github.com/tileflow/tileflow-sdk/blob/main/docs/contracts/cartographic-authoring.md). Exact field

package/docs/street-sky.md

@@ -0,0 +1,153 @@
+# 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.
+
+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/sun-and-light.md

@@ -106,8 +106,10 @@ custom layer draws; the map redraws whenever the sun changes.
 
 `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. `setSun(undefined)` returns it to the
-themes. This example assumes an existing MapLibre map and a controller for it:
+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 -->
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/core",
-  "version": "0.1.0-alpha.38",
+  "version": "0.1.0-alpha.39",
   "license": "Apache-2.0",
   "description": "Typed Tileflow config and MapLibre style compiler.",
   "type": "module",