@tileflow/core 0.1.0-alpha.32 → 0.1.0-alpha.33

package/docs/route-drawing.md

@@ -0,0 +1,191 @@
+# Route drawing
+
+An application that draws a route on a Tileflow map can take the route's colours from the theme and
+draw the line on with a moving head. Themes set route inks; the theme controller returns them for
+the theme on screen; `createTileflowLineProgress` animates a group of line layers along their
+length; `createTileflowGroundLayers` keeps them on the ground, under the map's 3D buildings.
+
+## Set route inks in a theme
+
+Route inks are optional theme tokens. A theme that sets none uses defaults for its colour scheme:
+a blue line on a dark edge for light themes, a lighter blue with a glow and a bright core for dark
+themes.
+
+| Token                | Kind   | Use                                                   |
+| -------------------- | ------ | ----------------------------------------------------- |
+| `route.line`         | colour | The chosen route.                                     |
+| `route.casing`       | colour | The edge each side of the line, apart from the roads. |
+| `route.core`         | colour | A thin line along the middle.                         |
+| `route.glow`         | colour | A soft halo around the route.                         |
+| `route.alternative`  | colour | Other routes offered beside the chosen one.           |
+| `route.glow.opacity` | number | The halo's opacity, from 0 (none) to 1.               |
+| `route.core.opacity` | number | The core's opacity, from 0 (none) to 1.               |
+
+Every theme of a map carries the same tokens, so a map that sets route inks sets them in each of
+its themes:
+
+<!-- docs:check -->
+
+```ts
+import {defineTheme, type TileflowTheme} from '@tileflow/core';
+
+export function withNeonRoute(base: TileflowTheme, id: string): TileflowTheme {
+  return defineTheme(base, {
+    id,
+    version: 1,
+    colorScheme: base.colorScheme,
+    tokens: {
+      color: {
+        'route.line': '#ff4fae',
+        'route.casing': '#0b0f12',
+        'route.core': '#ffe0f0',
+        'route.glow': '#ff4fae',
+      },
+      number: {'route.glow.opacity': 0.55, 'route.core.opacity': 0.9},
+    },
+  });
+}
+```
+
+The compiler publishes the resolved inks in the style's `tileflow:route` metadata.
+`readTileflowRouteInks(style.metadata)` reads them from a style document;
+`tileflowStyleRouteInks(style)` also falls back on the defaults for a style compiled without them.
+
+## Draw a route in the theme's inks
+
+The theme controller's `getRouteInks()` returns the inks of the theme on screen. During a blend it
+mixes them between the neighbouring themes at the blend's position, in the same colour space as
+the map's own colours. Read them again after `setTheme` or `setBlend`.
+
+`createTileflowLineProgress(map, {layers})` owns the `line-gradient` and `line-opacity` of a group of
+line layers. Their source must be GeoJSON with `lineMetrics: true`. The controller shows the line
+from `start` to `end` (shares of its length), a highlight at the head while the line is being drawn,
+and an optional light at `light`. It writes only what changed, paints a layer again when a style
+change re-creates it, and skips layers that are not on the map.
+
+This example assumes an existing MapLibre map named `map` whose style already holds four line
+layers over a GeoJSON source with `lineMetrics: true`:
+
+<!-- docs:check -->
+
+```ts
+import {
+  createTileflowLineProgress,
+  type TileflowLineProgressMap,
+  type TileflowRouteInks,
+} from '@tileflow/core/browser';
+
+const layers = (inks: TileflowRouteInks) => [
+  {id: 'route-glow', color: inks.glow, highlight: '#ffffff', opacity: inks.glowOpacity},
+  {id: 'route-casing', color: inks.casing},
+  {id: 'route-line', color: inks.line, highlight: inks.core},
+  {id: 'route-core', color: inks.core, highlight: '#ffffff', opacity: inks.coreOpacity},
+];
+
+export async function drawRoute(
+  map: TileflowLineProgressMap,
+  inks: TileflowRouteInks,
+  lengthInMetres: number,
+) {
+  const route = createTileflowLineProgress(map, {
+    layers: layers(inks),
+    // A 90 m highlight, whatever the route's length.
+    headLength: Math.min(0.2, 90 / lengthInMetres),
+    initial: {end: 0},
+  });
+  await route.animate({to: {end: 1}, duration: 2500});
+  // A light runs along the drawn route.
+  await route.animate({to: {light: 1}, duration: 1500});
+  route.set({light: undefined});
+  return {
+    recolour: (next: TileflowRouteInks) => route.configure({layers: layers(next)}),
+    fadeOut: () => route.animate({to: {opacity: 0}, duration: 400}),
+    dispose: () => route.dispose(),
+  };
+}
+```
+
+`animate` resolves `true` when the line gets where it was sent, and `false` when `set`, another
+animation, or `dispose` stops it first; the line stays where it was stopped. A browser preference
+for reduced motion shows the target at once. `tileflowLineProgressGradient(state, options)` returns
+the same gradient for a single state, for styles built ahead of time.
+
+## Keep a route under 3D buildings
+
+MapLibre draws a 2D layer that comes after a 3D layer, such as extruded buildings or a custom layer
+drawn in 3D, without testing depth. A route added under the labels therefore crosses in front of
+the buildings. A route that lies on the ground goes before the first 3D layer: every building then
+hides it exactly where it stands in front of it.
+
+`tileflowGroundBeforeId(map)` returns that layer: the first 3D layer above the roads, or the start
+of the vegetation when the buildings are flat, so a ground layer still covers the roads and the
+flat buildings. Pass it as `beforeId` to `map.addLayer` for a single layer.
+
+`createTileflowGroundLayers(map, {layers, occludedOpacity})` keeps a group of layers there, bottom
+to top as given:
+
+- It adds the layers, or moves those already on the map. A layer whose source is not on the map yet
+  is added when the source is.
+- After a style change, it brings back the layers the change dropped, with the paint and layout
+  last written through the group.
+- When a 3D layer lands above the group, such as a custom layer added later, the group moves under
+  it.
+- `occludedOpacity` lets a line show through 3D content: by layer id, how much of the line shows
+  where buildings hide it, from 0 (nothing, the default) to 1. The group draws a copy of the line
+  over the 3D content at the line's opacity times that share, as a navigation app shows a route
+  through buildings. The copy lies over the group's other layers too, so where the line shows, it
+  tints the layers drawn above the line slightly; a line at the top of the group shows no change.
+  Only line layers whose `line-opacity` is a number can show through.
+
+Paint the group's layers through the group, so the copies follow them. A helper that paints layers
+takes the group in place of the map:
+
+<!-- docs:check -->
+
+```ts
+import {
+  createTileflowGroundLayers,
+  createTileflowLineProgress,
+  type TileflowGroundLayersMap,
+  type TileflowRouteInks,
+} from '@tileflow/core/browser';
+
+export function addRoute(map: TileflowGroundLayersMap, inks: TileflowRouteInks) {
+  // The map already holds a GeoJSON source named 'route' with `lineMetrics: true`.
+  const line = (id: string, width: number) => ({
+    id,
+    type: 'line',
+    source: 'route',
+    layout: {'line-cap': 'round', 'line-join': 'round'},
+    paint: {'line-width': width},
+  });
+  const ground = createTileflowGroundLayers(map, {
+    layers: [line('route-casing', 12), line('route-line', 8), line('route-core', 2)],
+    occludedOpacity: {'route-line': 0.35},
+  });
+  const route = createTileflowLineProgress(ground, {
+    layers: [
+      {id: 'route-casing', color: inks.casing},
+      {id: 'route-line', color: inks.line, highlight: inks.core},
+      {id: 'route-core', color: inks.core, opacity: inks.coreOpacity},
+    ],
+    initial: {end: 0},
+  });
+  return {
+    draw: () => route.animate({to: {end: 1}, duration: 2500}),
+    remove: () => {
+      route.dispose();
+      ground.dispose();
+    },
+  };
+}
+```
+
+`dispose` takes the group's layers and copies off the map. The copies keep the layer's id with
+`:occluded` after it.
+
+## Cost
+
+Each frame of an animation writes one `line-gradient` per layer, and MapLibre rebuilds that layer's
+gradient texture. A route of a few layers costs little; avoid animating dozens of long lines at
+once.

package/docs/street-lights.md

@@ -0,0 +1,80 @@
+# 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.
+
+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, 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 `color`, a warm white by default.
+- 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.
+
+`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.
+
+## Options
+
+`intensity` scales the light from 0 to 2 (1 by default). `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; `source` names a vector source other than `tileflow`; `transformRequest`
+applies the map's request rules to the tiles the layer 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.
+
+## 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/sun-and-light.md

@@ -0,0 +1,125 @@
+# 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.5, full
+shadows, a white sky at 0.5):
+
+<!-- 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.
+
+## 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. `setSun(undefined)` returns it 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`.

package/docs/themes-and-module-styles.md

@@ -15,6 +15,13 @@ same token keys, so changing a theme can never change map structure or silently
 role. `defineTheme(base, definition)` is an authoring convenience that returns a fully materialized
 document; it does not leave an inheritance edge in the resolved config.
 
+Some optional tokens are for the application rather than the map's own layers. Route inks
+(`route.line`, `route.casing`, `route.core`, `route.glow`, `route.alternative`,
+`route.glow.opacity` and `route.core.opacity`) set how an application draws its routes; a theme
+without them uses its colour scheme's defaults. The compiler publishes them in the style's metadata
+and the theme controller returns them; see
+[route drawing](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/route-drawing.md).
+
 The key in the `themes` record is its concrete runtime selector and output-path segment. The
 theme's own `id` and `version` are its editorial identity and build provenance, so they need not
 equal that key. Concrete keys may be names such as `day` and `night`; every `systemThemes.light` or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/core",
-  "version": "0.1.0-alpha.32",
+  "version": "0.1.0-alpha.33",
   "license": "Apache-2.0",
   "description": "Typed Tileflow config and MapLibre style compiler.",
   "type": "module",
@@ -81,7 +81,10 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@mapbox/vector-tile": "3.0.0",
+    "earcut": "3.2.4",
     "maplibre-contour": "0.1.0",
+    "pbf": "5.1.2",
     "pmtiles": "4.4.0",
     "whatwg-url": "15.1.0"
   },