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

package/dist/browser.d.ts

@@ -1,3 +1,46 @@
+/** Inputs to one fixed-size, application-owned RGBA image. */
+type TileflowDynamicImageContext = Readonly<{
+    theme: string;
+    blend?: Readonly<{
+        position: number;
+        themes: readonly string[];
+    }>;
+    states: Readonly<Record<string, boolean | number | string | null | undefined>>;
+    /** Physical pixel dimensions, fixed for this registration. */
+    width: number;
+    height: number;
+    pixelRatio: number;
+}>;
+type TileflowDynamicImage = Readonly<{
+    /** Physical pixel dimensions, each from 1 through 2048. */
+    width: number;
+    height: number;
+    /** Physical pixels per logical pixel. Defaults to 1; fixed until disposal. */
+    pixelRatio?: number;
+    /** Controller states that invalidate this image, including interpolated values. */
+    states?: readonly string[];
+    /** Synchronous RGBA pixels; undefined keeps the previous pixels (initially transparent). */
+    render(context: TileflowDynamicImageContext): Uint8Array | Uint8ClampedArray | undefined;
+    /** Later render/restore failures retain good pixels. Defaults to console.error. */
+    onError?(error: Error): void;
+}>;
+type TileflowDynamicImageHandle = {
+    /** Refresh external inputs at the next frame. Repeated requests coalesce. */
+    refresh(): void;
+    /** Cancel queued work, release the name and remove only this resource's image. */
+    dispose(): void;
+};
+type TileflowDynamicImageMap = {
+    addImage?: unknown;
+    getCanvas?: unknown;
+    getImage?: unknown;
+    getStyle?: unknown;
+    removeImage?: unknown;
+    updateImage?: unknown;
+    on(event: string, listener: () => void): unknown;
+    off(event: string, listener: () => void): unknown;
+};
+
 type TileflowFairUseNoticeState = 'GRACE' | 'MANAGED_REQUIRED';
 type TileflowFairUseNotice = Readonly<{
     action: string;
@@ -135,6 +178,11 @@ type TileflowTextJustify = 'auto' | 'center' | 'left' | 'right';
 type TileflowIconAnchor = TileflowTextAnchor;
 type TileflowAlignment = 'auto' | 'map' | 'viewport';
 type TileflowIconTextFit = 'both' | 'height' | 'none' | 'width';
+/**
+ * How a symbol part treats collisions with symbols placed before it. `never` hides it, `always`
+ * shows it, and `cooperative` shows it unless the earlier symbol was placed with `never`.
+ */
+type TileflowSymbolOverlap = 'always' | 'cooperative' | 'never';
 /** Visibility and zoom bounds shared by every visual primitive. */
 type TileflowLayerRange = {
     maxZoom?: number;
@@ -231,6 +279,12 @@ type TileflowTextLayout = {
     maxWidth?: TileflowNumberStyleValue;
     offset?: TileflowNumberOffsetStyleValue;
     optional?: boolean;
+    /**
+     * Overlap mode. Takes precedence over `allowOverlap`, so the compiled layer carries only the mode.
+     * Native artifacts, whose renderer has no overlap modes, use `allowOverlap: false` for `never`
+     * and `true` otherwise.
+     */
+    overlap?: TileflowSymbolOverlap;
     padding?: TileflowNumberStyleValue;
     pitchAlignment?: TileflowAlignment;
     radialOffset?: TileflowNumberStyleValue;
@@ -256,6 +310,12 @@ type TileflowIconLayout = {
     keepUpright?: boolean;
     offset?: TileflowNumberOffsetStyleValue;
     optional?: boolean;
+    /**
+     * Overlap mode. Takes precedence over `allowOverlap`, so the compiled layer carries only the mode.
+     * Native artifacts, whose renderer has no overlap modes, use `allowOverlap: false` for `never`
+     * and `true` otherwise.
+     */
+    overlap?: TileflowSymbolOverlap;
     padding?: TileflowNumberStyleValue;
     pitchAlignment?: TileflowAlignment;
     rotate?: TileflowNumberStyleValue;
@@ -476,6 +536,137 @@ type MapLibreStyle = {
     metadata?: Record<string, unknown>;
 };
 
+declare const tileflowSunMetadataKey = "tileflow:sun";
+/** A theme's sun and sky light with every value resolved; see `TileflowThemeSun`. */
+type TileflowSunPreset = Readonly<{
+    /** Degrees clockwise from north, from 0 to 360. */
+    azimuth: number;
+    /** Degrees above the horizon, from -90 to 90. */
+    altitude: number;
+    /** The direct light's colour. */
+    color: string;
+    /** The direct light's strength, from 0 to 1. */
+    intensity: number;
+    /** How dark the shadows the sun casts fall, from 0 (none) to 1. */
+    shadowIntensity: number;
+    /** The light from the sky, which reaches every surface and fills the shadows. */
+    ambient: Readonly<{
+        color: string;
+        intensity: number;
+    }>;
+}>;
+/** The sun as the map shows it, ready for an application's own layers. */
+type TileflowSun = Readonly<{
+    /** Degrees clockwise from north, from 0 to 360. */
+    azimuth: number;
+    /** Degrees above the horizon, from -90 to 90. */
+    altitude: number;
+    /** A unit vector towards the sun: x east, y north, z up. */
+    direction: readonly [number, number, number];
+    /** The direct light's colour, as a CSS colour. */
+    color: string;
+    /** The direct light's colour as sRGB channels from 0 to 1. */
+    rgb: readonly [number, number, number];
+    /**
+     * The direct light's strength, from 0 to 1. It fades to 0 as the sun sets: a sun below the
+     * horizon lights nothing and casts no shadow.
+     */
+    intensity: number;
+    /** How dark the shadows the sun casts fall, from 0 (none) to 1. */
+    shadowIntensity: number;
+    /** The light from the sky, which reaches every surface and fills the shadows. */
+    ambient: Readonly<{
+        color: string;
+        rgb: readonly [number, number, number];
+        intensity: number;
+    }>;
+    /**
+     * How bright flat, open ground is under this light, from 0 (dark) 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.
+     */
+    brightness: number;
+    /** Where the direction comes from: the themes, angles, or a date and place. */
+    source: 'theme' | 'direction' | 'date';
+}>;
+/** The sun of a theme that leaves a value unset: high in the south-south-west, in white light. */
+declare const tileflowDefaultSunPreset: TileflowSunPreset;
+/**
+ * Where the sun stands for an instant and a place ([longitude, latitude] in degrees): its azimuth
+ * in degrees clockwise from north and its apparent altitude above the horizon, with atmospheric
+ * refraction. It follows NOAA's solar equations, accurate to about a hundredth of a degree for
+ * years 1800 to 2200.
+ */
+declare function tileflowSunPosition(date: Date | number, location: readonly [number, number]): Readonly<{
+    azimuth: number;
+    altitude: number;
+}>;
+/** A unit vector towards a direction in the sky: x east, y north, z up. */
+declare function tileflowSunDirection(azimuth: number, altitude: number): readonly [number, number, number];
+/**
+ * The sun as the map shows it: a preset's light from a direction. Direct light fades out over the
+ * sun's last degrees above the horizon and is gone below it.
+ */
+declare function resolveTileflowSun(preset: TileflowSunPreset, direction?: Readonly<{
+    azimuth: number;
+    altitude: number;
+}>, source?: TileflowSun['source']): TileflowSun;
+/**
+ * A preset `t` of the way from `from` to `to`: the azimuth turns the short way round, colours mix
+ * in OKLab, as theme blends mix paint colours, and numbers linearly.
+ */
+declare function mixTileflowSunPresets(from: TileflowSunPreset, to: TileflowSunPreset, t: number): TileflowSunPreset;
+/** Reads the sun a compiled style publishes, or undefined when its metadata has none. */
+declare function readTileflowSunPreset(metadata: unknown): TileflowSunPreset | undefined;
+/**
+ * The sun of a compiled style: the one it publishes, else one read from its light (a style whose
+ * theme describes no sun lights its extrusions from `light.position`), else the default.
+ */
+declare function tileflowStyleSunPreset(style: {
+    light?: unknown;
+    metadata?: unknown;
+} | undefined): TileflowSunPreset;
+
+type TileflowThemeColorScheme = 'dark' | 'light';
+
+declare const tileflowRouteMetadataKey = "tileflow:route";
+/** The resolved inks of a route, from its outer glow to its bright core. */
+type TileflowRouteInks = Readonly<{
+    /** The chosen route's line. */
+    line: string;
+    /** The edge on each side of the line, which sets it apart from the roads under it. */
+    casing: string;
+    /** A thin line along the middle of the route. */
+    core: string;
+    /** A soft halo around the route. */
+    glow: string;
+    /** Other routes offered beside the chosen one. */
+    alternative: string;
+    /** Opacity of the glow, from 0 (no glow) to 1. */
+    glowOpacity: number;
+    /** Opacity of the core, from 0 (no core) to 1. */
+    coreOpacity: number;
+}>;
+/** The inks of a theme that sets no route tokens: a blue that reads on either kind of map. */
+declare const tileflowDefaultRouteInks: Readonly<Record<TileflowThemeColorScheme, TileflowRouteInks>>;
+/**
+ * Reads the route inks a compiled style publishes, or undefined when its metadata has none (a
+ * style compiled before route inks, or not by Tileflow).
+ */
+declare function readTileflowRouteInks(metadata: unknown): TileflowRouteInks | undefined;
+/**
+ * The route inks of a compiled style: those it publishes, or the defaults of its colour scheme
+ * (from its `tileflow:colorScheme` metadata, else `fallbackScheme`).
+ */
+declare function tileflowStyleRouteInks(style: {
+    metadata?: unknown;
+} | undefined, fallbackScheme?: TileflowThemeColorScheme): TileflowRouteInks;
+/**
+ * Inks between two themes' inks, `t` of the way from `from` to `to`: colours mix in OKLab, as theme
+ * blends mix paint colours, and opacities linearly.
+ */
+declare function mixTileflowRouteInks(from: TileflowRouteInks, to: TileflowRouteInks, t: number): TileflowRouteInks;
+
 type TileflowRuntimeColorScheme = 'dark' | 'light';
 
 type TileflowAnalytics = {
@@ -509,6 +700,17 @@ type TileflowStyleFontFace = {
     style?: 'italic' | 'normal' | 'oblique';
     weight?: '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';
 };
+/**
+ * A continuous blend of named themes of one Tileflow map. `position` places the map between
+ * neighbouring themes: 0 is the first, 1 the second, and 1.25 a quarter of the way from the second
+ * to the third.
+ */
+type TileflowThemeBlendSelection = Readonly<{
+    /** From 0 to `themes.length - 1`. */
+    position: number;
+    /** Two to eight concrete theme names of the map, in blend order. */
+    themes: readonly string[];
+}>;
 
 type TileflowAddressesModuleOptions = {
     /** Styling for OpenMapTiles point house-number labels. */
@@ -624,7 +826,6 @@ type TileflowVegetationThreeDimensionalStyle = {
 };
 type TileflowVegetationModuleOptions = {
     flat?: TileflowCircleStyle;
-    minZoom?: number;
     mode?: TileflowVegetationMode;
     threeDimensional?: TileflowVegetationThreeDimensionalStyle;
 };
@@ -760,6 +961,730 @@ type TileflowAtmosphereMap = {
  */
 declare function attachTileflowAtmosphere(map: TileflowAtmosphereMap): () => void;
 
+/** The drawn stretch of a line and its highlights, as shares of the line's length from its start. */
+type TileflowLineProgressState = Readonly<{
+    /** Where the drawn stretch starts, from 0 (the default) to 1. */
+    start?: number;
+    /** Where the drawn stretch ends, from 0 to 1 (the default, the whole line). */
+    end?: number;
+    /** Where a light sits along the line, or undefined (the default) for none. */
+    light?: number;
+    /** The whole line's opacity, multiplied with each layer's own, from 0 to 1 (the default). */
+    opacity?: number;
+}>;
+type TileflowLineProgressGradientOptions = Readonly<{
+    /** The line's colour. */
+    color: string;
+    /** The colour at the head and in the light; defaults to `color`, which shows neither. */
+    highlight?: string;
+    /**
+     * Length of the head's highlight, as a share of the line. The head shows while the drawn stretch
+     * ends before the line does. Defaults to 0.04; 0 shows no head.
+     */
+    headLength?: number;
+    /** Length of the light, as a share of the line. Defaults to `headLength`. */
+    lightLength?: number;
+}>;
+/**
+ * The `line-gradient` of a line drawn from `state.start` to `state.end`. The source of the layer
+ * must be GeoJSON with `lineMetrics: true`.
+ */
+declare function tileflowLineProgressGradient(state: TileflowLineProgressState, options: TileflowLineProgressGradientOptions): unknown[];
+
+/** Structural MapLibre capabilities; importing this module never loads a renderer. */
+type TileflowLineProgressMap = {
+    getCanvas?: unknown;
+    getLayer(id: string): unknown;
+    setPaintProperty(layer: string, name: string, value: unknown): unknown;
+    on(event: 'styledata', listener: () => void): unknown;
+    off(event: 'styledata', listener: () => void): unknown;
+};
+/** One line layer of the group, over a GeoJSON source with `lineMetrics: true`. */
+type TileflowLineProgressLayer = Readonly<{
+    id: string;
+    /** The layer's colour along the drawn line. */
+    color: string;
+    /** The colour at the head and in the light; defaults to `color`. */
+    highlight?: string;
+    /** The layer's own opacity, from 0 to 1 (the default). */
+    opacity?: number;
+}>;
+type TileflowLineProgressOptions = Readonly<{
+    /** The layers drawn together, such as a route's glow, casing, line and core. */
+    layers: readonly TileflowLineProgressLayer[];
+    /** Length of the head's highlight, as a share of the line; defaults to 0.04. */
+    headLength?: number;
+    /** Length of the light, as a share of the line; defaults to `headLength`. */
+    lightLength?: number;
+    /** What the layers show at first; defaults to the whole line, without a light. */
+    initial?: TileflowLineProgressState;
+}>;
+type TileflowLineProgressAnimation = Readonly<{
+    /** The values to reach; values left out keep what they show. */
+    to: TileflowLineProgressState;
+    /** Milliseconds, from 0 to 60000. */
+    duration: number;
+    /** Maps elapsed time (0 to 1) to progress (0 to 1); defaults to an ease in and out. */
+    easing?: (t: number) => number;
+}>;
+/** What the layers show: `light` is absent when no light shows. */
+type TileflowLineProgressShown = Readonly<{
+    start: number;
+    end: number;
+    light?: number;
+    opacity: number;
+}>;
+type TileflowLineProgressController = {
+    /** What the layers show now, mid-animation included. */
+    get(): TileflowLineProgressShown;
+    /**
+     * Shows new values at once and stops a running animation. Values left out keep what they show;
+     * `light: undefined` takes the light off.
+     */
+    set(state: TileflowLineProgressState): void;
+    /**
+     * Moves to new values over a duration and resolves `true` when it gets there, or `false` when
+     * `set`, another animation, or `dispose` stops it first. A light that is not showing starts from
+     * the start of the drawn stretch. With reduced motion requested, it shows the values at once.
+     */
+    animate(animation: TileflowLineProgressAnimation): Promise<boolean>;
+    /** Changes the layers' colours or the highlight lengths, for example when the theme changes. */
+    configure(options: Partial<Omit<TileflowLineProgressOptions, 'initial'>>): void;
+    /** Stops writing to the map. The layers keep what they show. */
+    dispose(): void;
+};
+/**
+ * Draws a line on, a share of its length at a time, over a group of MapLibre line layers: their
+ * `line-gradient` shows the drawn stretch, a bright head where it is being drawn, and a light that
+ * can run along it. The controller owns each layer's `line-gradient` and `line-opacity`, writes
+ * only what changed, and paints a layer again when a style change re-creates it. Layers that are
+ * not on the map are skipped until they are.
+ */
+declare function createTileflowLineProgress(map: TileflowLineProgressMap, options: TileflowLineProgressOptions): TileflowLineProgressController;
+
+type TileflowTileGeometryType = 'Point' | 'LineString' | 'Polygon';
+type TileflowTileFeature = Readonly<{
+    /** The feature's id in the tile, when it has one. */
+    id?: number;
+    type: TileflowTileGeometryType;
+    properties: Readonly<Record<string, string | number | boolean>>;
+    /**
+     * One flat `[x0, y0, x1, y1, …]` array per point set, line or ring, in tile units from 0 to the
+     * layer's extent (coordinates in a tile's buffer fall outside that range). Polygon rings follow
+     * the MVT winding: an exterior ring is clockwise in tile units, a hole anticlockwise.
+     */
+    geometry: readonly (readonly number[])[];
+}>;
+type TileflowTileLayer = Readonly<{
+    /** Tile units across the tile, usually 4096. */
+    extent: number;
+    features: readonly TileflowTileFeature[];
+}>;
+type TileflowVectorTileDecodeOptions = Readonly<{
+    /** The layers to decode; others are skipped without decoding. Defaults to every layer. */
+    layers?: readonly string[];
+}>;
+/** Decodes a Mapbox Vector Tile's layers. Throws on bytes that are not a vector tile. */
+declare function decodeTileflowVectorTile(bytes: Uint8Array, options?: TileflowVectorTileDecodeOptions): Readonly<Record<string, TileflowTileLayer>>;
+
+type TileflowTileAddress = Readonly<{
+    z: number;
+    x: number;
+    y: number;
+}>;
+/** A decoded tile: its address and the chosen layers it holds. */
+type TileflowTile = TileflowTileAddress & Readonly<{
+    layers: Readonly<Record<string, TileflowTileLayer>>;
+}>;
+/** Rewrites a tile request as a MapLibre map's `transformRequest` does. */
+type TileflowTileRequestTransform = (url: string, resourceType: 'Tile') => Readonly<{
+    url: string;
+    headers?: Readonly<Record<string, string>>;
+    credentials?: RequestCredentials;
+}> | undefined;
+type TileflowTileReaderOptions = Readonly<{
+    /** The tile address with `{z}`, `{x}` and `{y}`, such as a MapLibre vector source's `tiles[0]`. */
+    tiles: string;
+    /** The lowest zoom the source has tiles for; defaults to 0. */
+    minzoom?: number;
+    /** The highest zoom the source has tiles for; deeper reads use its tiles. Defaults to 14. */
+    maxzoom?: number;
+    /** The layers to decode; defaults to every layer. */
+    layers?: readonly string[];
+    /** Decoded tiles kept for later reads, from 0 to 4096; defaults to 128. */
+    cacheSize?: number;
+    /** Requests in flight at once, from 1 to 32; defaults to 6. */
+    concurrency?: number;
+    /** The map's request rules, applied to every tile request. */
+    transformRequest?: TileflowTileRequestTransform;
+    /** Defaults to the global `fetch`. */
+    fetch?: (url: string, init: RequestInit) => Promise<Response>;
+}>;
+type TileflowTileAreaRequest = Readonly<{
+    /** `[west, south, east, north]` in degrees. */
+    bounds: readonly [number, number, number, number];
+    /** The zoom to read at, clamped to the source's zooms. */
+    zoom: number;
+    /** The most tiles the area may take; a larger area is refused. Defaults to 64. */
+    maxTiles?: number;
+    signal?: AbortSignal;
+}>;
+type TileflowTileReader = {
+    /** A tile's chosen layers, or undefined when the source has no tile there (404 or 204). */
+    readTile(address: TileflowTileAddress, options?: {
+        signal?: AbortSignal;
+    }): Promise<TileflowTile | undefined>;
+    /** The tiles covering an area at a zoom, without the absent ones, nearest the centre first. */
+    readArea(request: TileflowTileAreaRequest): Promise<TileflowTile[]>;
+    /** Forgets every cached tile. */
+    clear(): void;
+};
+/** The tiles at `zoom` covering `[west, south, east, north]`, nearest the centre first. */
+declare function tileflowTilesForBounds(bounds: readonly [number, number, number, number], zoom: number): TileflowTileAddress[];
+/** The longitude and latitude of a point in a tile, given in tile units of an `extent`. */
+declare function tileflowTilePointToLngLat(tile: TileflowTileAddress, x: number, y: number, extent?: number): [number, number];
+/**
+ * Reads a vector source's tiles in an application: for example a MapLibre map's World source, with
+ * `tiles`, `minzoom` and `maxzoom` taken from `map.getSource(id)`, and the map's `transformRequest`.
+ */
+declare function createTileflowTileReader(options: TileflowTileReaderOptions): TileflowTileReader;
+/** Structural MapLibre capability; importing this module never loads a renderer. */
+type TileflowTileSourceMap = {
+    getSource(id: string): unknown;
+};
+/**
+ * The tile address and zooms of a map's vector source once the map has loaded it, ready for
+ * `createTileflowTileReader`; undefined while the source is not loaded or has no tile address.
+ */
+declare function readTileflowMapTileSource(map: TileflowTileSourceMap, sourceId: string): {
+    tiles: string;
+    minzoom: number;
+    maxzoom: number;
+} | undefined;
+
+/** The MapLibre GL JS map capabilities the renderer uses. */
+type TileflowBuildings3DMap = {
+    addLayer(layer: object, beforeId?: string): unknown;
+    getCenter(): {
+        lat: number;
+        lng: number;
+    };
+    getBearing(): number;
+    getLayer(id: string): unknown;
+    getPaintProperty(layer: string, name: string): unknown;
+    getPitch(): number;
+    getSource(id: string): unknown;
+    getStyle(): unknown;
+    getZoom(): number;
+    isStyleLoaded(): boolean | void;
+    off(event: string, listener: () => void): unknown;
+    on(event: string, listener: () => void): unknown;
+    removeLayer(id: string): unknown;
+    triggerRepaint(): unknown;
+};
+/** Where the renderer reads the sun and the themes: a Tileflow theme controller. */
+type TileflowBuildings3DThemes = {
+    getBlend?(): {
+        position: number;
+        themes: readonly string[];
+    } | undefined;
+    getCurrent?(): {
+        theme?: string;
+    };
+    getSun?(): TileflowSun;
+};
+type TileflowBuildings3DOptions = Readonly<{
+    map: TileflowBuildings3DMap;
+    /** The theme controller, for the sun and, with `color`, the themes on screen. */
+    controller?: TileflowBuildings3DThemes;
+    /** The vector source to read; defaults to `tileflow`, a Tileflow map's World source. */
+    source?: string;
+    /** The source layer with the buildings; defaults to `building`. */
+    sourceLayer?: string;
+    /**
+     * The source layer with the places, for the night use of buildings in tiles whose buildings do
+     * not carry World's `night_use`; defaults to `poi`.
+     */
+    placesLayer?: string;
+    /**
+     * A building's colour for a theme, from its feature properties, as a CSS colour. Each building
+     * is coloured once per theme, and the renderer mixes the colours of the themes either side of
+     * a blend's position. Without it, buildings take the theme's 3D building colour.
+     */
+    color?: (properties: Readonly<Record<string, string | number | boolean>>, theme: string) => string;
+    /** Shadows from the sun, on the buildings and the flat map; defaults to true. */
+    shadows?: boolean;
+    /** Contact shadow at the foot of the walls and in tight corners; defaults to true. */
+    occlusion?: boolean;
+    /**
+     * How bright the buildings light the street at night, from 0 (none) to 2; defaults to 1, a quiet
+     * light. Landmarks (World's `building_tone`) and towers are flood-lit at their foot, and buildings
+     * with places busy at night (World's `night_use`) light their ground floor windows and the
+     * pavement in front: bars and clubs in neon or a warm light, theatres and cinemas in white,
+     * places to eat in amber.
+     */
+    nightLight?: number;
+    /**
+     * How strongly roof outlines and buildings' outer corners catch the light, from 0 (none) to 1;
+     * defaults to 1. They keep a constant width on screen, so where one building ends and the next
+     * starts stays legible at any distance, at night most of all.
+     */
+    edges?: number;
+    /**
+     * The colour of roof outlines and outer corners, as a CSS colour or per theme, drawn as it is,
+     * unlit, at the full `edges` strength by day and night. The renderer asks for each theme's colour
+     * once and mixes the colours of the themes either side of a blend's position; a theme without a
+     * valid colour keeps the default. Without it, edges take the building's own colour, lightened as
+     * if catching the light, half as strong by day as at night.
+     */
+    edgeColor?: string | ((theme: string) => string);
+    /** Invented night windows, lit by rooms; decoration, not data. Defaults to false. */
+    windows?: boolean;
+    /** The zoom from which buildings stand; below it they sink into the flat map. Defaults to 14.5. */
+    minzoom?: number;
+    /** The most tiles raised round the camera, from 1 to 64; defaults to 25. */
+    maxTiles?: number;
+    /** The layer to draw before; defaults to the style's `above-buildings` placement. */
+    beforeId?: string;
+    /** The map's request rules, for the tiles the renderer reads. */
+    transformRequest?: TileflowTileRequestTransform;
+}>;
+type TileflowBuildings3DChange = Readonly<{
+    transition?: Readonly<{
+        duration?: number;
+    }>;
+}>;
+type TileflowBuildings3D = {
+    /** Raises the buildings out of the ground; resolves once they stand. */
+    show(options?: TileflowBuildings3DChange): Promise<void>;
+    /** Sinks the buildings back into the flat map; resolves once they are gone. */
+    hide(options?: TileflowBuildings3DChange): Promise<void>;
+    /** Eases the buildings to `scale` of their height, from 0 (flat) to 1. */
+    grow(scale: number, options?: TileflowBuildings3DChange): Promise<void>;
+    /** The height scale shown now. */
+    readonly scale: number;
+    /** Tiles raised, buildings and vertices, for diagnostics. */
+    readonly stats: Readonly<{
+        tiles: number;
+        buildings: number;
+        vertices: number;
+    }>;
+    /** Takes the layer off the map and lets go of its buffers. */
+    dispose(): void;
+};
+declare const tileflowBuildings3DLayerId = "tileflow-buildings-3d";
+/**
+ * Creates the renderer and puts its layer on the map, flat until `show()`. It reads the source's
+ * z15 tiles round the camera, the zoom at which World's buildings carry their heights.
+ */
+declare function createTileflowBuildings3D(options: TileflowBuildings3DOptions): TileflowBuildings3D;
+/**
+ * The sun's view of a box of buildings: an orthographic projection along `direction` (towards the
+ * sun; x east, y north, z up, in metres) as a column-major matrix to clip space, with the metres its
+ * depth runs over and the metres its wider side spans. It follows only the sun, never the camera,
+ * so shadows hold still while the camera moves.
+ */
+declare function tileflowSunLightMatrix(direction: readonly number[], box: Readonly<{
+    min: readonly number[];
+    max: readonly number[];
+}>): {
+    matrix: Float32Array;
+    depth: number;
+    extent: number;
+};
+
+/** The renderer's tile units: MapLibre projects custom layers' tiles over 8192. */
+declare const tileflowBuildingExtent = 8192;
+/** Bytes per vertex; see `meshTileflowBuildings` for the layout. */
+declare const tileflowBuildingVertexBytes = 28;
+type TileflowBuildingMeshOptions = Readonly<{
+    /** The tile's width in metres, for the length of each wall. */
+    tileMetres: number;
+    /** Height used where a building has none, in metres; defaults to 5, World's own fallback. */
+    defaultHeight?: number;
+    /**
+     * The tile's places (World's `poi` layer), for the night use of buildings when the tile's
+     * buildings do not carry World's `night_use`: a place inside a building, or on its facade, gives
+     * the building its use.
+     */
+    places?: TileflowTileLayer;
+}>;
+/** One tile's buildings, ready to upload. */
+type TileflowBuildingMesh = Readonly<{
+    vertices: Uint8Array;
+    indices: Uint32Array;
+    /** The first wall index: roofs come before it, walls from it. */
+    wallsFrom: number;
+    /** The tallest building, in metres. */
+    top: number;
+    /** Each vertex's building is an index into these feature properties. */
+    features: readonly Readonly<Record<string, string | number | boolean>>[];
+}>;
+/**
+ * Meshes the buildings of one decoded tile layer, or returns undefined when it has none. It reads
+ * World's `render_height`, `render_min_height`, `hide_3d`, `building_tone` and `night_use`. Vertex layout:
+ * 0 position in the tile, 0 to 8192 (uint16 ×2); 4 base and top in decimetres (uint16 ×2); 8 the
+ * wall's outward normal (int8 ×2, normalised); 10 raised to the top, part of a wall (uint8 ×2);
+ * 12 decimetres along the wall (uint16); 14 a per-building jitter and seed (uint8 ×2, normalised);
+ * 16 the building's centre in the tile (uint16 ×2); 20 tone and night use (uint8 ×2: none, dining,
+ * entertainment, nightlife); 22 the wall's
+ * tight corners, bit 0 at its start and bit 1 at its end, and bit 2 when it faces a courtyard, and
+ * its length in metres up to 255
+ * (uint8 ×2); 24 the building's feature index (uint16); 26 on a roof, the vertex's corner of its
+ * triangle (0 to 2), on a wall, 0 at its start and 1 at its end (uint8); 27 on a roof, the triangle's
+ * sides that are the roof's outline, bit n for the side facing corner n, on a wall, bit 0 when its
+ * start and bit 1 when its end lies on the tile's edge (uint8).
+ *
+ * A building's jitter is the same for every piece of it a tile edge cuts, so the renderer can vary
+ * buildings' brightness with it without a seam along the tile's edge.
+ */
+declare function meshTileflowBuildings(layer: TileflowTileLayer, options: TileflowBuildingMeshOptions): TileflowBuildingMesh | undefined;
+
+/** Bytes per lamp; see `placeTileflowStreetLights` for the layout. */
+declare const tileflowStreetLightBytes = 12;
+/**
+ * Where light is estimated where the data maps no lamps: `lit` (the default) along the streets and
+ * pavements the data maps as lit; `streets` also along the streets the data says nothing about,
+ * wherever it maps few lamps, which invents light as night windows do; `none` nowhere, so only
+ * mapped lamps shine.
+ */
+type TileflowStreetLightEstimate = 'streets' | 'lit' | 'none';
+type TileflowStreetLightPlacementOptions = Readonly<{
+    /** The tile's width in metres. */
+    tileMetres: number;
+    /** Defaults to `lit`. */
+    estimate?: TileflowStreetLightEstimate;
+}>;
+/** A tile's layers the lamps come from, as World names them. */
+type TileflowStreetLightLayers = Readonly<{
+    /** Points with `subclass` `street_lamp` (World's `street_furniture`). */
+    streetFurniture?: TileflowTileLayer;
+    /** Streets by `class`, with `lit` where mapped (World's `transportation`). */
+    transportation?: TileflowTileLayer;
+    /** Pavements, as lines or areas, with `lit` where mapped (World's `sidewalk`). */
+    sidewalks?: TileflowTileLayer;
+}>;
+/** One tile's lamps, ready to upload. */
+type TileflowStreetLightPlacement = Readonly<{
+    lamps: Uint8Array;
+    /** Lamps from the data. */
+    mapped: number;
+    /** Points of soft light estimated along streets. */
+    estimated: number;
+}>;
+/**
+ * Places one tile's lamps and estimated light, or returns undefined when it has none. Each is a
+ * point of light, flagged as mapped or estimated. Layout: 0 position in the
+ * tile, 0 to 8192 (uint16 ×2); 4 height in decimetres (uint16); 6 the reach of its light on the
+ * ground in metres (uint8); 7 flags (uint8: bit 0 mapped, bit 1 its own colour); 8 its colour
+ * (uint8 ×3, sRGB); 11 a seed (uint8, normalised).
+ */
+declare function placeTileflowStreetLights(layers: TileflowStreetLightLayers, options: TileflowStreetLightPlacementOptions): TileflowStreetLightPlacement | undefined;
+
+/** The MapLibre GL JS map capabilities the street lights use. */
+type TileflowStreetLightsMap = {
+    addLayer(layer: object, beforeId?: string): unknown;
+    getBearing(): number;
+    getCenter(): {
+        lat: number;
+        lng: number;
+    };
+    getLayer(id: string): unknown;
+    getPitch(): number;
+    getSource(id: string): unknown;
+    getStyle(): unknown;
+    getZoom(): number;
+    isStyleLoaded(): boolean | void;
+    off(event: string, listener: () => void): unknown;
+    on(event: string, listener: () => void): unknown;
+    removeLayer(id: string): unknown;
+    triggerRepaint(): unknown;
+};
+type TileflowStreetLightsOptions = Readonly<{
+    map: TileflowStreetLightsMap;
+    /** The theme controller, whose sun switches the lights on and off. */
+    controller?: {
+        getSun?(): TileflowSun;
+    };
+    /** The vector source to read; defaults to `tileflow`, a Tileflow map's World source. */
+    source?: string;
+    /**
+     * Where soft light is estimated where the data maps no lamps: `lit` (the default) along the
+     * streets and pavements the data maps as lit; `streets` also along the streets the data says
+     * nothing about, wherever it maps few lamps, which invents light as night windows do; `none`
+     * nowhere, so only mapped lamps shine.
+     */
+    estimate?: TileflowStreetLightEstimate;
+    /** The light of the lamps whose data gives no colour, as a CSS colour; a warm white by default. */
+    color?: string;
+    /** How bright the lights shine, from 0 to 2; defaults to 1. */
+    intensity?: number;
+    /** The zoom from which the lights shine. Defaults to 14. */
+    minzoom?: number;
+    /** The most tiles lit round the camera, from 1 to 64; defaults to 25. */
+    maxTiles?: number;
+    /** The layer to draw before; defaults to the style's `above-buildings` placement. */
+    beforeId?: string;
+    /** The map's request rules, for the tiles the layer reads. */
+    transformRequest?: TileflowTileRequestTransform;
+}>;
+type TileflowStreetLights = {
+    /** How far the lights have switched on, from 0 by day to 1 at night. */
+    readonly on: number;
+    /** Tiles lit, lamps, and how many of them the data maps or the layer estimates. */
+    readonly stats: Readonly<{
+        tiles: number;
+        lamps: number;
+        mapped: number;
+        estimated: number;
+    }>;
+    /** Takes the layer off the map and lets go of its buffers. */
+    dispose(): void;
+};
+declare const tileflowStreetLightsLayerId = "tileflow-street-lights";
+/**
+ * Creates the street lights and puts their layer on the map. They read the source's z15 tiles round
+ * the camera once the controller's sun darkens the map, and shine from `minzoom`.
+ */
+declare function createTileflowStreetLights(options: TileflowStreetLightsOptions): TileflowStreetLights;
+
+/** The capabilities `tileflowGroundBeforeId` reads; importing this module never loads a renderer. */
+type TileflowGroundOrderMap = {
+    getLayer(id: string): unknown;
+    getLayersOrder(): string[];
+    getStyle(): unknown;
+};
+/** Structural MapLibre capabilities of a map that holds a ground layer group. */
+type TileflowGroundLayersMap = TileflowGroundOrderMap & {
+    addLayer(layer: unknown, beforeId?: string): unknown;
+    getSource(id: string): unknown;
+    moveLayer(id: string, beforeId?: string): unknown;
+    removeLayer(id: string): unknown;
+    setPaintProperty(layer: string, name: string, value: unknown): unknown;
+    setLayoutProperty(layer: string, name: string, value: unknown): unknown;
+    getCanvas?(): unknown;
+    on(event: 'styledata', listener: () => void): unknown;
+    off(event: 'styledata', listener: () => void): unknown;
+};
+/**
+ * A layer of the group: a MapLibre style layer drawn in 2D, such as a line or a fill, or a custom
+ * layer whose `renderingMode` is `2d`.
+ */
+type TileflowGroundLayer = Readonly<Record<string, unknown> & {
+    id: string;
+    type: string;
+}> | Readonly<{
+    id: string;
+    type: 'custom';
+    renderingMode?: '2d' | '3d';
+}>;
+type TileflowGroundLayersOptions = Readonly<{
+    /** The layers, bottom to top, such as a route's glow, casing, line and core. */
+    layers: readonly TileflowGroundLayer[];
+    /**
+     * How much of each line layer shows where 3D content hides it, by layer id: from 0 (nothing, the
+     * default) to 1 (as much as where it shows). Only line layers whose `line-opacity` is a number
+     * can show through.
+     */
+    occludedOpacity?: Readonly<Record<string, number>>;
+}>;
+type TileflowGroundLayers = {
+    /** The group's layer ids, bottom to top. */
+    readonly ids: readonly string[];
+    /** The map's layer, so helpers that paint layers, such as line progress, can paint the group. */
+    getLayer(id: string): unknown;
+    /**
+     * Sets a paint property of one of the group's layers, and keeps it for when a style change brings
+     * the layer back. A layer that shows through 3D content passes it to its see-through copy too, at
+     * its `line-opacity` times its occluded opacity. Other layers' properties pass straight to the map.
+     */
+    setPaintProperty(layer: string, name: string, value: unknown): void;
+    /** Sets a layout property, such as `visibility`, the same way. */
+    setLayoutProperty(layer: string, name: string, value: unknown): void;
+    getCanvas(): unknown;
+    on(event: 'styledata', listener: () => void): void;
+    off(event: 'styledata', listener: () => void): void;
+    /** Takes the group's layers and their copies off the map and stops following style changes. */
+    dispose(): void;
+};
+/**
+ * The layer a layer lying on the ground goes before: the first 3D layer above the roads, or the
+ * start of the vegetation when the buildings are flat, so the layer covers the roads and the flat
+ * buildings, and every 3D layer hides it where it stands in front. A style without Tileflow's
+ * overlay placements uses its first 3D layer or its first symbol layer. Undefined means the top.
+ */
+declare function tileflowGroundBeforeId(map: TileflowGroundOrderMap): string | undefined;
+/**
+ * Keeps a group of application layers on the ground, under the map's 3D content, from bottom to
+ * top as given. Layers already on the map are moved into place; a layer whose source is not on the
+ * map yet is added when it is. The group follows the map: after a style change it brings back the
+ * layers the change dropped, and it moves its layers again when a 3D layer lands above them, so
+ * a layer added later in 3D hides them too. A line with an occluded opacity gets a see-through
+ * copy over the 3D content, painted through the group.
+ */
+declare function createTileflowGroundLayers(map: TileflowGroundLayersMap, options: TileflowGroundLayersOptions): TileflowGroundLayers;
+
+/** Structural MapLibre capabilities; importing this module never loads a renderer. */
+type TileflowDepthMarkerMap = {
+    addLayer(layer: unknown, beforeId?: string): unknown;
+    getLayer(id: string): unknown;
+    removeLayer(id: string): unknown;
+    getCanvas(): HTMLCanvasElement;
+    getPixelRatio?(): number;
+    triggerRepaint(): void;
+    on(event: 'styledata', listener: () => void): unknown;
+    off(event: 'styledata', listener: () => void): unknown;
+};
+type TileflowDepthMarker = Readonly<{
+    /** `[longitude, latitude]`. */
+    lngLat: readonly [number, number];
+    /** The marker's picture. Pass it again to `update` after drawing into it. */
+    image: TexImageSource;
+    /** Width and height: CSS pixels for a screen marker, metres for a ground marker. */
+    size: readonly [number, number];
+    /**
+     * `screen` (the default) faces the viewer at a fixed size in pixels, as a pin does; `ground`
+     * lies flat on the ground at a size in metres, as a ring or an arrow on the street does.
+     */
+    alignment?: 'screen' | 'ground';
+    /** The point of the image that sits on the position: `center` (the default) or `bottom`. */
+    anchor?: 'center' | 'bottom';
+    /** A screen marker's shift in CSS pixels, right and down. */
+    offset?: readonly [number, number];
+    /** Degrees clockwise: from the screen's up for a screen marker, from north for a ground one. */
+    rotation?: number;
+    /** Metres above the ground; defaults to 0. */
+    altitude?: number;
+    /** From 0 to 1 (the default). */
+    opacity?: number;
+    /** Whether nearer 3D content hides the marker; defaults to true. */
+    occlude?: boolean;
+}>;
+type TileflowDepthMarkerHandle = {
+    /** Changes the marker; an `image` passed again is uploaded again. */
+    update(change: Partial<TileflowDepthMarker>): void;
+    remove(): void;
+};
+type TileflowDepthMarkersOptions = Readonly<{
+    /** The custom layer's id; defaults to `tileflow-depth-markers`. */
+    id?: string;
+    /** The layer the markers are drawn under, or a function that finds it after a style change. */
+    beforeId?: string | (() => string | undefined);
+}>;
+type TileflowDepthMarkers = {
+    add(marker: TileflowDepthMarker): TileflowDepthMarkerHandle;
+    /** Removes the markers' layer and releases its GPU resources. */
+    dispose(): void;
+};
+/** Where a marker sits: its tile and its position there in tile units, and metres in tile units. */
+declare function tileflowDepthMarkerPlacement(lngLat: readonly [number, number]): {
+    tile: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    position: [number, number];
+    unitsPerMetre: number;
+};
+/**
+ * Draws markers in the map's 3D scene, hidden by nearer 3D buildings. Needs a MapLibre GL JS map
+ * on WebGL 2 (GL JS 5 or later). The layer puts itself back after a style change.
+ */
+declare function createTileflowDepthMarkers(map: TileflowDepthMarkerMap, options?: TileflowDepthMarkersOptions): TileflowDepthMarkers;
+
+/** A camera between keyframes: always the center form, with bearing and pitch resolved. */
+type TileflowShotCamera = {
+    type: 'center';
+    center: [number, number];
+    zoom: number;
+    bearing: number;
+    pitch: number;
+};
+type TileflowShotKeyframe = Readonly<{
+    /** Milliseconds from the start: the first keyframe is at 0, later ones rise strictly. */
+    at: number;
+    camera: Readonly<{
+        /** Shots committed on a map name the center camera form; the motion needs no other. */
+        type?: 'center';
+        center: readonly [number, number];
+        zoom: number;
+        bearing?: number;
+        pitch?: number;
+    }>;
+    blend?: Readonly<{
+        themes: readonly string[];
+        position: number;
+    }>;
+}>;
+type TileflowShotMotion = Readonly<{
+    keyframes: readonly TileflowShotKeyframe[];
+    /** `smooth` (the default) eases each segment in and out; `linear` does not. */
+    easing?: 'linear' | 'smooth';
+}>;
+/** The camera and blend position of a shot at a time. */
+type TileflowShotState = {
+    at: number;
+    camera: TileflowShotCamera;
+    /** Present when the shot blends themes. */
+    blendPosition?: number;
+};
+/**
+ * Where a shot is at `at` milliseconds, clamped to its first and last keyframes. Within each
+ * keyframe segment the center moves in Web Mercator coordinates along the shorter way around the
+ * world, zoom and pitch change linearly, bearing turns along the shorter arc, and the blend position
+ * changes linearly; `easing: 'smooth'` eases each segment in and out. A time on a keyframe shows
+ * that keyframe exactly.
+ */
+declare function tileflowShotStateAt(shot: TileflowShotMotion, at: number): TileflowShotState;
+
+/** Structural MapLibre capabilities; importing this module never loads a renderer. */
+type TileflowShotPlayerMap = {
+    getCanvas?: unknown;
+    jumpTo(camera: {
+        center: [number, number];
+        zoom: number;
+        bearing: number;
+        pitch: number;
+    }): unknown;
+};
+/** Something to do once the shot reaches a time, such as drawing a route or showing a title. */
+type TileflowShotCue = Readonly<{
+    at: number;
+    run: () => void;
+}>;
+type TileflowShotPlaybackOptions = Readonly<{
+    /**
+     * Receives the blend position at each frame of a shot that blends themes, to pass on to the
+     * theme controller: `(position) => controller.setBlend({themes, position})`.
+     */
+    blend?: (position: number) => void;
+    /** Run once each, in time order, as the shot reaches them. */
+    cues?: readonly TileflowShotCue[];
+    /** Receives the camera after each frame's move. */
+    onFrame?: (state: {
+        at: number;
+        camera: TileflowShotCamera;
+        blendPosition?: number;
+    }) => void;
+    /** Stops the shot where it is. */
+    signal?: AbortSignal;
+}>;
+type TileflowShotPlayback = {
+    /** True when the shot played to its last keyframe; false when it was stopped first. */
+    readonly finished: Promise<boolean>;
+    /** Milliseconds the shot has played. */
+    readonly at: number;
+    /** Stops the shot where it is. */
+    stop(): void;
+};
+/**
+ * Plays a timed shot live on a map: the camera follows the shot's keyframes frame by frame, the
+ * blend position goes to `blend`, and cues run as the shot reaches them. It moves as Capture renders
+ * the same shot to video, so the page and the film agree. With reduced motion requested, or without
+ * a browser window, it shows the last keyframe at once and runs every cue in order.
+ */
+declare function playTileflowShot(map: TileflowShotPlayerMap, shot: TileflowShotMotion, options?: TileflowShotPlaybackOptions): TileflowShotPlayback;
+
 declare const tileflowMaplibreContourVersion: "0.1.0";
 type TileflowContourProtocolRequest = Readonly<{
     url: string;
@@ -785,7 +1710,7 @@ type TileflowPmtilesProtocolHandler = (request: Readonly<{
     url: string;
 }>, abortController: AbortController) => Promise<Readonly<{
     cacheControl?: string;
-    data: unknown;
+    data: object | string;
     expires?: string;
 }>>;
 type TileflowPmtilesProtocolRegistry = Readonly<{
@@ -840,24 +1765,82 @@ type TileflowThemeBlendRequest = Readonly<{
     position: number;
     /** Two to eight concrete themes of one map, in blend order. */
     themes: readonly TileflowRuntimeStyle[];
+    /**
+     * Holds back what would make MapLibre lay tiles out again: the change of nearest theme, with
+     * the labels, icons, and values it switches, and mixed pattern artwork. Colours, numbers, the
+     * sky, and light keep following the position, so a camera move or a recording never waits on
+     * the blend. The next request without `hold` brings what was held back in at once.
+     */
+    hold?: boolean;
+}>;
+/**
+ * A blend of named themes as the React, Vue, and Svelte maps take it: `hold` holds back what
+ * would make MapLibre lay tiles out again, as `TileflowThemeBlendRequest.hold` does, and the next
+ * selection without it brings what waited in at once.
+ */
+type TileflowBrowserThemeBlendSelection = TileflowThemeBlendSelection & Readonly<{
+    hold?: boolean;
 }>;
+declare function validateTileflowBrowserThemeBlendSelection(value: unknown): value is TileflowBrowserThemeBlendSelection;
 type TileflowThemeBlendState = Readonly<{
+    /** Whether changes held back by `hold` are waiting for a request without it. */
+    held: boolean;
     position: number;
+    /**
+     * Positions where the nearest theme changes over values that make MapLibre lay tiles out
+     * again, such as icon names, layout values, and values that read feature data or state. Plan
+     * a camera move or a recording around them, or pass `hold` across them.
+     */
+    relayoutAt: readonly number[];
     themes: readonly string[];
 }>;
-type TileflowStyleSwitchMap = TileflowThemeMotionMap & {
+type TileflowStyleSwitchMap = TileflowThemeMotionMap & TileflowDynamicImageMap & {
+    getCenter?: unknown;
+    getGlobalState?: unknown;
     off(event: string, listener: (event?: unknown) => void): unknown;
     on(event: string, listener: (event?: unknown) => void): unknown;
+    setGlobalStateProperty?: unknown;
     setStyle: unknown;
 };
+/** A value an application sets for the whole style, which themes read with `expr.globalState`. */
+type TileflowStyleStateValue = boolean | number | string | null;
+/**
+ * Where an application places the sun. `azimuth` (degrees clockwise from north) and `altitude`
+ * (degrees above the horizon) place it directly; `date` places the real sun of that instant over
+ * `location` ([longitude, latitude]), the map's centre when it is left out.
+ */
+type TileflowSunRequest = Readonly<{
+    altitude: number;
+    azimuth: number;
+}> | Readonly<{
+    date: Date | number;
+    location?: readonly [number, number];
+}>;
 type TileflowThemeController = {
     dispose(): void;
+    /** Own a fixed-size RGBA image with a stable name across themes, restored after style reloads. */
+    registerImage(name: string, image: TileflowDynamicImage): TileflowDynamicImageHandle;
     /** The active blend, or undefined when the map shows one theme. */
     getBlend(): TileflowThemeBlendState | undefined;
     /** The theme the map shows; during a blend, the nearest theme. */
     getCurrent(): TileflowRuntimeStyle;
     /** The emphasis requested last, or undefined when the map is shown as designed. */
     getEmphasis(): TileflowEmphasis | undefined;
+    /**
+     * The route inks of the theme on screen, for an application's own route layers. During a blend
+     * they are mixed between the neighbouring themes at the blend's position, as the map's colours
+     * are. Read them again after a theme change or a blend move.
+     */
+    getRouteInks(): TileflowRouteInks;
+    /** The value a style state was set to last, or undefined when it has not been set. */
+    getState(name: string): TileflowStyleStateValue | undefined;
+    /**
+     * The sun the map shows, for an application's own 3D layers: its direction, the light it and
+     * the sky give, and how dark its shadows fall. It is the theme's sun (`lighting.sun`), mixed
+     * between neighbouring themes during a blend, unless `setSun` placed it. Read it when drawing;
+     * the map redraws whenever it changes.
+     */
+    getSun(): TileflowSun;
     /**
      * Shows a blend of themes. The first request for a set of themes loads their styles and
      * prepares one style that holds all of them; later requests for the same themes only move the
@@ -871,6 +1854,22 @@ type TileflowThemeController = {
      * that MapLibre evaluates per feature change at once, under a cross-fade.
      */
     setEmphasis(emphasis: TileflowEmphasis | undefined, options?: TileflowThemeChangeOptions): Promise<TileflowThemeTransitionResult>;
+    /**
+     * Sets a style-wide state that the map's themes read with `expr.globalState(name)`. A number
+     * eases from the value it shows to the new one over the transition, so a colour or size that a
+     * theme interpolates on it moves smoothly; other values, and a number set for the first time,
+     * change at once. A value that also reads feature data or feature state is laid out again by
+     * MapLibre at each change, so it follows late and costs more. States stay through theme changes
+     * and blends. Needs a MapLibre map with global state (GL JS 5.6 or later).
+     */
+    setState(name: string, value: TileflowStyleStateValue, options?: TileflowThemeChangeOptions): Promise<TileflowThemeTransitionResult>;
+    /**
+     * Places the sun by direction or by the real sun of a date and place; `undefined` returns it to
+     * the themes' suns. The themes keep the sun's colours, strengths, and shadow strength, and the
+     * map's light turns to the new direction, anchored to the map. The sun turns the short way round
+     * over the transition; a request that follows an animation, such as a clock, passes none.
+     */
+    setSun(request: TileflowSunRequest | undefined, options?: TileflowThemeChangeOptions): Promise<TileflowThemeTransitionResult>;
     setTheme(style: TileflowRuntimeStyle, options?: TileflowThemeChangeOptions): Promise<TileflowThemeTransitionResult>;
 };
 /**
@@ -921,7 +1920,6 @@ type TileflowTransformRequestParameters = {
 type TileflowComposedRequest<TRequest extends TileflowTransformRequestParameters> = Pick<TRequest, 'url'> & Partial<Omit<TRequest, 'url'>>;
 type TileflowTransformRequest<TRequest extends TileflowTransformRequestParameters, TResourceType> = (url: string, resourceType?: TResourceType) => Promise<TileflowComposedRequest<TRequest>> | TileflowComposedRequest<TRequest> | undefined;
 type TileflowUserTransformRequest<TRequest extends TileflowTransformRequestParameters, TResourceType> = (url: string, resourceType?: TResourceType) => Promise<TRequest> | TRequest | undefined;
-type TileflowAsyncAnalyticsTiming = 'request' | 'resolution';
 declare function createTileflowSessionStarter(options: {
     getSessionId?: () => string;
     sessionId: string;
@@ -940,23 +1938,17 @@ declare function attachTileflowMapLifecycle<TMap, TFrame>(options: {
     setState: (state: TileflowMapReadinessState) => void;
     subscribe: TileflowMapLifecycleSubscriber<TMap>;
 }): TileflowMapLifecycleAttachment;
+/**
+ * Compose the caller's request transform with Tileflow analytics, the Hosted session, and the
+ * World bridge. Analytics are read when each request starts, so an asynchronous user transform
+ * never attaches analytics that changed while it was pending.
+ */
 declare function createTileflowTransformRequest<TRequest extends TileflowTransformRequestParameters = TileflowTransformRequestParameters, TResourceType = unknown>(options: {
-    always: true;
-    asyncAnalyticsTiming?: TileflowAsyncAnalyticsTiming;
     getAnalytics: () => TileflowAnalytics | undefined;
     sessionController?: TileflowSessionController;
     sessionId: string;
     transformRequest?: TileflowUserTransformRequest<TRequest, TResourceType>;
     worldRequestBridge?: TileflowWorldRequestBridge;
 }): TileflowTransformRequest<TRequest, TResourceType>;
-declare function createTileflowTransformRequest<TRequest extends TileflowTransformRequestParameters = TileflowTransformRequestParameters, TResourceType = unknown>(options: {
-    always?: boolean;
-    asyncAnalyticsTiming?: TileflowAsyncAnalyticsTiming;
-    getAnalytics: () => TileflowAnalytics | undefined;
-    sessionController?: TileflowSessionController;
-    sessionId: string;
-    transformRequest?: TileflowUserTransformRequest<TRequest, TResourceType>;
-    worldRequestBridge?: TileflowWorldRequestBridge;
-}): TileflowTransformRequest<TRequest, TResourceType> | undefined;
 
-export { type TileflowAsyncAnalyticsTiming, type TileflowAtmosphereMap, type TileflowComposedRequest, type TileflowContourProtocolHandler, type TileflowContourProtocolRegistrationOptions, type TileflowContourProtocolRegistry, type TileflowContourProtocolRequest, type TileflowContourProtocolResponse, type TileflowEmphasis, type TileflowEmphasisArea, type TileflowEmphasisModule, type TileflowFairUseNotice, type TileflowFairUseNoticeController, type TileflowFairUseNoticeState, type TileflowFrameScheduler, type TileflowMapLifecycleAttachment, type TileflowMapLifecycleEvent, type TileflowMapLifecycleSubscriber, type TileflowMapReadinessState, type TileflowPmtilesProtocolHandler, type TileflowPmtilesProtocolRegistrationOptions, type TileflowPmtilesProtocolRegistry, type TileflowSessionSender, type TileflowSessionStarter, type TileflowStyleFontLoadOptions, type TileflowStyleSwitchMap, type TileflowThemeBlendRequest, type TileflowThemeBlendState, type TileflowThemeChangeOptions, type TileflowThemeController, type TileflowThemeTransition, type TileflowThemeTransitionOptions, type TileflowThemeTransitionPhase, type TileflowThemeTransitionResult, type TileflowTransformRequest, type TileflowTransformRequestParameters, type TileflowUserTransformRequest, type TileflowWorldProtocolHandler, type TileflowWorldProtocolRequest, type TileflowWorldProtocolResponse, type TileflowWorldRequestBridge, attachTileflowAtmosphere, attachTileflowFairUseNotice, attachTileflowMapLifecycle, createTileflowSessionStarter, createTileflowThemeController, createTileflowTransformRequest, getTileflowSystemColorScheme, loadTileflowStyleFonts, registerTileflowContourProtocol, registerTileflowPmtilesProtocol, registerTileflowWorldRequestBridge, subscribeTileflowSystemColorScheme, tileflowFairUseNoticeMessage, tileflowLayerDomainMetadataKey, tileflowMaplibreContourVersion, tileflowPmtilesMaximumDirectoryDepth, tileflowPmtilesProtocol, validateTileflowEmphasis };
+export { type TileflowAtmosphereMap, type TileflowBrowserThemeBlendSelection, type TileflowBuildingMesh, type TileflowBuildingMeshOptions, type TileflowBuildings3D, type TileflowBuildings3DChange, type TileflowBuildings3DMap, type TileflowBuildings3DOptions, type TileflowBuildings3DThemes, type TileflowComposedRequest, type TileflowContourProtocolHandler, type TileflowContourProtocolRegistrationOptions, type TileflowContourProtocolRegistry, type TileflowContourProtocolRequest, type TileflowContourProtocolResponse, type TileflowDepthMarker, type TileflowDepthMarkerHandle, type TileflowDepthMarkerMap, type TileflowDepthMarkers, type TileflowDepthMarkersOptions, type TileflowDynamicImage, type TileflowDynamicImageContext, type TileflowDynamicImageHandle, type TileflowEmphasis, type TileflowEmphasisArea, type TileflowEmphasisModule, type TileflowFairUseNotice, type TileflowFairUseNoticeController, type TileflowFairUseNoticeState, type TileflowFrameScheduler, type TileflowGroundLayer, type TileflowGroundLayers, type TileflowGroundLayersMap, type TileflowGroundLayersOptions, type TileflowGroundOrderMap, type TileflowLineProgressAnimation, type TileflowLineProgressController, type TileflowLineProgressGradientOptions, type TileflowLineProgressLayer, type TileflowLineProgressMap, type TileflowLineProgressOptions, type TileflowLineProgressShown, type TileflowLineProgressState, type TileflowMapLifecycleAttachment, type TileflowMapLifecycleEvent, type TileflowMapLifecycleSubscriber, type TileflowMapReadinessState, type TileflowPmtilesProtocolHandler, type TileflowPmtilesProtocolRegistrationOptions, type TileflowPmtilesProtocolRegistry, type TileflowRouteInks, type TileflowSessionSender, type TileflowSessionStarter, type TileflowShotCamera, type TileflowShotCue, type TileflowShotKeyframe, type TileflowShotMotion, type TileflowShotPlayback, type TileflowShotPlaybackOptions, type TileflowShotPlayerMap, type TileflowShotState, type TileflowStreetLightEstimate, type TileflowStreetLightLayers, type TileflowStreetLightPlacement, type TileflowStreetLightPlacementOptions, type TileflowStreetLights, type TileflowStreetLightsMap, type TileflowStreetLightsOptions, type TileflowStyleFontLoadOptions, type TileflowStyleStateValue, type TileflowStyleSwitchMap, type TileflowSun, type TileflowSunPreset, type TileflowSunRequest, type TileflowThemeBlendRequest, type TileflowThemeBlendState, type TileflowThemeChangeOptions, type TileflowThemeController, type TileflowThemeTransition, type TileflowThemeTransitionOptions, type TileflowThemeTransitionPhase, type TileflowThemeTransitionResult, type TileflowTile, type TileflowTileAddress, type TileflowTileAreaRequest, type TileflowTileFeature, type TileflowTileGeometryType, type TileflowTileLayer, type TileflowTileReader, type TileflowTileReaderOptions, type TileflowTileRequestTransform, type TileflowTileSourceMap, type TileflowTransformRequest, type TileflowTransformRequestParameters, type TileflowUserTransformRequest, type TileflowVectorTileDecodeOptions, type TileflowWorldProtocolHandler, type TileflowWorldProtocolRequest, type TileflowWorldProtocolResponse, type TileflowWorldRequestBridge, attachTileflowAtmosphere, attachTileflowFairUseNotice, attachTileflowMapLifecycle, createTileflowBuildings3D, createTileflowDepthMarkers, createTileflowGroundLayers, createTileflowLineProgress, createTileflowSessionStarter, createTileflowStreetLights, createTileflowThemeController, createTileflowTileReader, createTileflowTransformRequest, decodeTileflowVectorTile, getTileflowSystemColorScheme, loadTileflowStyleFonts, meshTileflowBuildings, mixTileflowRouteInks, mixTileflowSunPresets, placeTileflowStreetLights, playTileflowShot, readTileflowMapTileSource, readTileflowRouteInks, readTileflowSunPreset, registerTileflowContourProtocol, registerTileflowPmtilesProtocol, registerTileflowWorldRequestBridge, resolveTileflowSun, subscribeTileflowSystemColorScheme, tileflowBuildingExtent, tileflowBuildingVertexBytes, tileflowBuildings3DLayerId, tileflowDefaultRouteInks, tileflowDefaultSunPreset, tileflowDepthMarkerPlacement, tileflowFairUseNoticeMessage, tileflowGroundBeforeId, tileflowLayerDomainMetadataKey, tileflowLineProgressGradient, tileflowMaplibreContourVersion, tileflowPmtilesMaximumDirectoryDepth, tileflowPmtilesProtocol, tileflowRouteMetadataKey, tileflowShotStateAt, tileflowStreetLightBytes, tileflowStreetLightsLayerId, tileflowStyleRouteInks, tileflowStyleSunPreset, tileflowSunDirection, tileflowSunLightMatrix, tileflowSunMetadataKey, tileflowSunPosition, tileflowTilePointToLngLat, tileflowTilesForBounds, validateTileflowBrowserThemeBlendSelection, validateTileflowEmphasis };