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

package/docs/style-states.md

@@ -0,0 +1,73 @@
+# 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

@@ -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/theme-transitions-and-blends.md

@@ -83,7 +83,8 @@ While a blend is shown, `data-tileflow-theme` names the theme nearest to the pos
 - Colours and numbers of the ground, such as land, water, roads, buildings, and their widths and
   opacities, follow the position continuously. Colours mix in the OKLab colour space, so halfway
   between two themes looks halfway to the eye.
-- Patterns, the sky, and light follow the position too. Pattern artwork is mixed in its pixels.
+- Patterns, the sky, and light follow the position too. Pattern artwork is mixed in its pixels;
+  artwork two neighbouring themes share, by name or pixel for pixel, is not uploaded again.
 - Labels, icons, and other symbols change when the nearest theme changes, with a short cross-fade.
   Light lettering on a dark plate and dark lettering on a light plate would meet in the same grey
   halfway, so symbols do not follow the position.
@@ -195,7 +196,8 @@ export async function moveThroughTheDay(map: MapLibreMap, manifestMap: TileflowR
   await controller.setBlend({position: 0.5, themes});
   // The same themes: the position applies at once.
   await controller.setBlend({position: 0.6, themes});
-  return controller.getBlend(); // {position: 0.6, themes: ['night', 'dusk', 'day']}
+  // {held: false, position: 0.6, relayoutAt: [...], themes: ['night', 'dusk', 'day']}
+  return controller.getBlend();
 }
 ```
 
@@ -209,6 +211,8 @@ when styles need another loader.
 
 The controller also shows [map emphasis](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/map-emphasis.md),
 which stays through theme changes and follows every blend position.
+Its [dynamic style images](dynamic-style-images.md) receive theme, blend and declared state inputs
+under one resource owner, with fixed geometry and restoration after a style reload.
 
 ## Fast sweeps on slower devices
 
@@ -219,3 +223,38 @@ changes most ground layers on every frame. Measured in Chromium on Apple silicon
 a detailed city map, such a sweep kept 76 frames a second; with the processor slowed four times, as
 on a mid-range phone, it fell to about 11, against 28 for the same camera move without the sweep.
 On slower devices, prefer short sweeps or move the position less often.
+
+## Camera moves and recordings
+
+Some changes make MapLibre lay tiles out again: when the nearest theme changes, the values that
+switch with it (icon names, layout values, and values that read feature data or feature state),
+and each step of pattern or icon artwork that is mixed in pixels. A camera move or a screen
+recording shows that work as dropped frames. `getBlend().relayoutAt` lists the positions where the
+nearest theme changes over such values, so a sequence can be planned around them.
+
+Pass `hold: true` to hold that work back. Colours, numbers, the sky, and light keep following the
+position; the nearest theme, the values that switch with it, and mixed artwork wait.
+`getBlend().held` reports whether anything waits. The next request without `hold` brings it in at
+once, so make it while the camera rests:
+
+```ts
+import type {TileflowThemeController} from '@tileflow/core/browser';
+import type {TileflowRuntimeStyle} from '@tileflow/core/runtime';
+
+export async function duskWhileFlying(
+  controller: TileflowThemeController,
+  themes: readonly TileflowRuntimeStyle[],
+  flight: Promise<void>,
+) {
+  // Through the camera move the ground darkens towards night with no layout work.
+  for (const position of [0.25, 0.5, 0.75])
+    await controller.setBlend({hold: true, position, themes});
+  await flight;
+  // The camera rests: labels, icons, and artwork follow at once.
+  await controller.setBlend({position: 0.75, themes});
+}
+```
+
+The React, Vue, and Svelte maps take the same flag in `themeBlend`: pass
+`themeBlend={{hold: true, position, themes}}` while the camera moves and drop `hold` when it rests.
+The React Native `Map` blends natively and does not take `hold`.

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.31",
+  "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"
   },

package/dist/capture-scene-D6soWztE.d.ts

@@ -1,161 +0,0 @@
-import { z } from 'zod';
-
-declare const tileflowCaptureSceneSchemaVersion: 1;
-declare const tileflowCaptureSceneLimits: Readonly<{
-    applicationPathLength: 2048;
-    boundsPadding: {
-        maximum: number;
-        minimum: number;
-    };
-    captureIdLength: 64;
-    maximumPhysicalPixels: 16777216;
-    pitch: {
-        maximum: number;
-        minimum: number;
-    };
-    selectorLength: 256;
-    viewport: {
-        maximum: number;
-        minimum: number;
-    };
-    zoom: {
-        maximum: number;
-        minimum: number;
-    };
-}>;
-declare const tileflowCaptureCenterCameraSchema: z.ZodObject<{
-    type: z.ZodLiteral<"center">;
-    center: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
-    zoom: z.ZodNumber;
-    bearing: z.ZodOptional<z.ZodNumber>;
-    pitch: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strict>;
-declare const tileflowCaptureBoundsCameraSchema: z.ZodObject<{
-    type: z.ZodLiteral<"bounds">;
-    bounds: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
-    padding: z.ZodOptional<z.ZodNumber>;
-    bearing: z.ZodOptional<z.ZodNumber>;
-    pitch: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strict>;
-declare const tileflowCaptureCameraSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    type: z.ZodLiteral<"center">;
-    center: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
-    zoom: z.ZodNumber;
-    bearing: z.ZodOptional<z.ZodNumber>;
-    pitch: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strict>, z.ZodObject<{
-    type: z.ZodLiteral<"bounds">;
-    bounds: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
-    padding: z.ZodOptional<z.ZodNumber>;
-    bearing: z.ZodOptional<z.ZodNumber>;
-    pitch: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strict>], "type">;
-declare const tileflowCaptureViewportSchema: z.ZodObject<{
-    width: z.ZodNumber;
-    height: z.ZodNumber;
-    dpr: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>]>>;
-}, z.core.$strict>;
-declare const tileflowCaptureIdSchema: z.ZodString;
-declare const tileflowCaptureSceneNameSchema: z.ZodString;
-declare const tileflowCaptureMapTargetSchema: z.ZodObject<{
-    kind: z.ZodLiteral<"map">;
-}, z.core.$strict>;
-declare const tileflowCaptureApplicationTargetSchema: z.ZodObject<{
-    kind: z.ZodLiteral<"application">;
-    path: z.ZodString;
-    captureId: z.ZodOptional<z.ZodString>;
-    selector: z.ZodOptional<z.ZodString>;
-    frame: z.ZodOptional<z.ZodEnum<{
-        map: "map";
-        viewport: "viewport";
-    }>>;
-}, z.core.$strict>;
-declare const tileflowCaptureTargetSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    kind: z.ZodLiteral<"map">;
-}, z.core.$strict>, z.ZodObject<{
-    kind: z.ZodLiteral<"application">;
-    path: z.ZodString;
-    captureId: z.ZodOptional<z.ZodString>;
-    selector: z.ZodOptional<z.ZodString>;
-    frame: z.ZodOptional<z.ZodEnum<{
-        map: "map";
-        viewport: "viewport";
-    }>>;
-}, z.core.$strict>], "kind">;
-declare const tileflowCaptureSceneSchema: z.ZodObject<{
-    map: z.ZodString;
-    theme: z.ZodString;
-    camera: z.ZodDiscriminatedUnion<[z.ZodObject<{
-        type: z.ZodLiteral<"center">;
-        center: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
-        zoom: z.ZodNumber;
-        bearing: z.ZodOptional<z.ZodNumber>;
-        pitch: z.ZodOptional<z.ZodNumber>;
-    }, z.core.$strict>, z.ZodObject<{
-        type: z.ZodLiteral<"bounds">;
-        bounds: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
-        padding: z.ZodOptional<z.ZodNumber>;
-        bearing: z.ZodOptional<z.ZodNumber>;
-        pitch: z.ZodOptional<z.ZodNumber>;
-    }, z.core.$strict>], "type">;
-    viewport: z.ZodObject<{
-        width: z.ZodNumber;
-        height: z.ZodNumber;
-        dpr: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>]>>;
-    }, z.core.$strict>;
-    target: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
-        kind: z.ZodLiteral<"map">;
-    }, z.core.$strict>, z.ZodObject<{
-        kind: z.ZodLiteral<"application">;
-        path: z.ZodString;
-        captureId: z.ZodOptional<z.ZodString>;
-        selector: z.ZodOptional<z.ZodString>;
-        frame: z.ZodOptional<z.ZodEnum<{
-            map: "map";
-            viewport: "viewport";
-        }>>;
-    }, z.core.$strict>], "kind">>;
-}, z.core.$strict>;
-type TileflowCaptureCenterCamera = z.infer<typeof tileflowCaptureCenterCameraSchema>;
-type TileflowCaptureBoundsCamera = z.infer<typeof tileflowCaptureBoundsCameraSchema>;
-type TileflowCaptureCamera = z.infer<typeof tileflowCaptureCameraSchema>;
-type TileflowCaptureViewport = z.infer<typeof tileflowCaptureViewportSchema>;
-type TileflowCaptureMapTarget = z.infer<typeof tileflowCaptureMapTargetSchema>;
-type TileflowCaptureApplicationTarget = z.infer<typeof tileflowCaptureApplicationTargetSchema>;
-type TileflowCaptureTarget = z.infer<typeof tileflowCaptureTargetSchema>;
-type TileflowCaptureScene = z.infer<typeof tileflowCaptureSceneSchema>;
-type NormalizedTileflowCaptureScene = {
-    map: string;
-    theme: string;
-    camera: {
-        type: 'center';
-        center: [number, number];
-        zoom: number;
-        bearing: number;
-        pitch: number;
-    } | {
-        type: 'bounds';
-        bounds: [number, number, number, number];
-        padding: number;
-        bearing: number;
-        pitch: number;
-    };
-    viewport: {
-        width: number;
-        height: number;
-        dpr: 1 | 2;
-    };
-    target: {
-        kind: 'map';
-    } | {
-        kind: 'application';
-        path: string;
-        captureId?: string;
-        selector?: string;
-        frame: 'map' | 'viewport';
-    };
-};
-declare function normalizeTileflowCaptureScene(input: TileflowCaptureScene): NormalizedTileflowCaptureScene;
-declare function normalizeTileflowCaptureId(value: string | undefined): string | undefined;
-
-export { type NormalizedTileflowCaptureScene as N, type TileflowCaptureScene as T, type TileflowCaptureApplicationTarget as a, type TileflowCaptureBoundsCamera as b, type TileflowCaptureCamera as c, type TileflowCaptureCenterCamera as d, type TileflowCaptureMapTarget as e, type TileflowCaptureTarget as f, type TileflowCaptureViewport as g, normalizeTileflowCaptureScene as h, tileflowCaptureBoundsCameraSchema as i, tileflowCaptureCameraSchema as j, tileflowCaptureCenterCameraSchema as k, tileflowCaptureIdSchema as l, tileflowCaptureMapTargetSchema as m, normalizeTileflowCaptureId as n, tileflowCaptureSceneLimits as o, tileflowCaptureSceneNameSchema as p, tileflowCaptureSceneSchema as q, tileflowCaptureSceneSchemaVersion as r, tileflowCaptureTargetSchema as s, tileflowCaptureApplicationTargetSchema as t, tileflowCaptureViewportSchema as u };