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

package/dist/browser.d.ts

@@ -420,6 +420,24 @@ type TileflowRoadRoundaboutStyle = {
     casing?: TileflowCircleStyle;
     fill?: TileflowCircleStyle;
 };
+/**
+ * How Core's street lights renderer lights the map's streets at night, from the lamps and lit
+ * streets its data holds.
+ */
+type TileflowRoadStreetLightStyle = {
+    /** The light of lamps whose data gives no colour; a warm white by default. */
+    color?: TileflowThemeColorValue;
+    /** Whether the map has street lights; defaults to true where the data binds street furniture. */
+    enabled?: boolean;
+    /**
+     * Where light is estimated where the data maps no lamps: `lit` (the default) along streets and
+     * pavements mapped as lit; `streets` also along streets the data says nothing about, in tiles
+     * that map few lamps, which invents light; `none` nowhere.
+     */
+    estimate?: 'lit' | 'streets' | 'none';
+    /** How bright the lights shine, from 0 to 2; defaults to 1. */
+    intensity?: TileflowThemeNumberValue;
+};
 type TileflowRoadSidewalkStyle = {
     outline?: TileflowLineStyle;
     pattern?: TileflowFillStyle;
@@ -441,6 +459,7 @@ type TileflowRoadsModuleConfig = {
     roundabouts?: TileflowRoadRoundaboutStyle;
     serviceTypes?: Partial<Record<TileflowRoadServiceType, TileflowRoadTreatmentStyle>>;
     sidewalks?: TileflowRoadSidewalkStyle;
+    streetLights?: TileflowRoadStreetLightStyle;
     structures?: Partial<Record<TileflowRoadStructure, TileflowRoadLayerStyle>>;
     weight?: TileflowRoadWeight;
     widthScale?: Partial<Record<TileflowRoadClass, TileflowThemeNumberValue>>;
@@ -536,6 +555,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 = {
@@ -610,11 +760,30 @@ type TileflowBoundariesModuleConfig = TileflowBoundariesModuleOptions & {
 };
 
 type TileflowBuildingMode = '3d' | 'flat';
+/**
+ * How Core's 3D buildings renderer draws the map's buildings. Their colour is the map's own 3D
+ * building colour (its extrusion), else its roofs'.
+ */
+type TileflowBuildingsThreeDimensionalStyle = {
+    /** How strongly roof outlines and outer corners catch the light, from 0 (none) to 1, the default. */
+    edges?: TileflowThemeNumberValue;
+    /** Their own colour, drawn unlit; without it they take the building's colour, lightened. */
+    edgeColor?: TileflowThemeColorValue;
+    /** How bright the buildings light the street at night, from 0 (none) to 2; defaults to 1. */
+    nightLight?: TileflowThemeNumberValue;
+    /** Contact shadow at the foot of the walls and in tight corners; defaults to true. */
+    occlusion?: boolean;
+    /** Shadows from the sun, on the buildings and the flat map; defaults to true. */
+    shadows?: boolean;
+    /** Invented night windows, lit by rooms: decoration, not data. Defaults to false. */
+    windows?: boolean;
+};
 type TileflowBuildingsModuleOptions = {
     businessCorridor?: TileflowAreaStyle;
     extrusion?: TileflowExtrusionStyle;
     flat?: TileflowAreaStyle;
     mode?: TileflowBuildingMode;
+    threeDimensional?: TileflowBuildingsThreeDimensionalStyle;
 };
 type TileflowBuildingsModuleConfig = TileflowBuildingsModuleOptions & {
     type: 'buildings';
@@ -685,13 +854,223 @@ type TileflowTransitModuleConfig = TileflowTransitModuleOptions & {
     type: 'transit';
 };
 
+/** A prepared model, near and optionally far, as the style's tree description carries it. */
+type TileflowTreeModel = Readonly<{
+    near: string;
+    far?: string;
+}>;
+
+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>>;
+
+/** The forms a 3D tree takes. */
+declare const tileflowTreeForms: readonly ["round", "open", "tall", "conifer", "columnar", "palm"];
+type TileflowTreeForm = (typeof tileflowTreeForms)[number];
+/** How a tree's surfaces take the light: facets, a smooth round shape, or bands as drawn. */
+declare const tileflowTreeFinishes: readonly ["faceted", "smooth", "toon"];
+type TileflowTreeFinish = (typeof tileflowTreeFinishes)[number];
+/** A form's own scales, on top of the map's, and the map's own models it draws. */
+type TileflowTreeFormStyle = Readonly<{
+    heightScale?: number;
+    crownScale?: number;
+    /** Ids of the map's own models, one to four; each tree draws one by its stable seed. */
+    models?: readonly string[];
+}>;
+/** Relative weights of the forms given to trees whose data gives none. */
+type TileflowTreeFormMix = Readonly<Partial<Record<TileflowTreeForm, number>>>;
+/** A region whose trees without a form in the data take their own mix. */
+type TileflowTreeRegion = Readonly<{
+    /** `[west, south, east, north]` in degrees. */
+    bounds: readonly [number, number, number, number];
+    unknownForms: TileflowTreeFormMix;
+}>;
+/** The fields of the tree and canopy layers, as World names them. */
+type TileflowTreeFields = Readonly<{
+    height: string;
+    diameterCrown: string;
+    circumference: string;
+    genus: string;
+    species: string;
+    leafType: string;
+    /** The tree's taxon at any rank, such as `Arecaceae` for palms or a genus or species. */
+    taxon: string;
+    canopyRank: string;
+    canopyClearance: string;
+    canopyCover: string;
+    /** A canopy point's measured canopy height, in metres. */
+    canopyHeight: string;
+}>;
+type TileflowTreePlacementOptions = Readonly<{
+    /** The tile's address, for regions and for a stable look per tree. */
+    tile: Readonly<{
+        x: number;
+        y: number;
+        z: number;
+    }>;
+    /** The tile's width in metres. */
+    tileMetres: number;
+    fields?: Partial<TileflowTreeFields>;
+    unknownForms?: TileflowTreeFormMix;
+    regions?: readonly TileflowTreeRegion[];
+    /** Metres between the trees of a row; defaults to 8. */
+    rowSpacing?: number;
+    /** How many models each form draws from, 1 to 4; each tree draws one by its seed. */
+    variants?: Readonly<Partial<Record<TileflowTreeForm, number>>>;
+}>;
+/** A tile's layers trees come from, as World names them. */
+type TileflowTreeLayers = Readonly<{
+    /**
+     * World's `tree`: trees mapped one by one as points, and rows of trees as lines, planted every
+     * `rowSpacing` metres.
+     */
+    trees?: TileflowTileLayer;
+    /** Decorative canopy points in parks and gardens (World's `canopy`). */
+    canopy?: TileflowTileLayer;
+}>;
+/** Where some trees are in a placement, and how many of them have each rank or a lower one. */
+type TileflowTreeRange = Readonly<{
+    start: number;
+    count: number;
+    /** `upTo[r]`: trees of the range with a rank of `r` or lower, from 0 to 15. */
+    upTo: readonly number[];
+}>;
+/** Where a form's trees are in a placement, and those of each of its models in turn. */
+type TileflowTreeFormRange = TileflowTreeRange & Readonly<{
+    /** One range per model the form draws from, in order; one when it draws Core's own tree. */
+    variants: readonly TileflowTreeRange[];
+}>;
+/** One tile's trees, ready to upload. */
+type TileflowTreePlacement = Readonly<{
+    /** `tileflowTreeBytes` bytes per tree, ordered by form, model, then rank; see the layout below. */
+    trees: Uint8Array;
+    forms: Readonly<Record<TileflowTreeForm, TileflowTreeFormRange>>;
+    /** The tallest tree, in metres. */
+    tallest: number;
+    /** Trees from the data's trees and rows, and trees from canopy points. */
+    mapped: number;
+    canopy: number;
+}>;
+/**
+ * Bytes per tree: x and y in tile units of 8192 (uint16 each), height and crown diameter in
+ * decimetres (uint16 each), then one byte each for its turn (of a full turn), its shade among the
+ * theme's colours, its form, its rank (0–15, lower shows first), a seed, whether it stands for a
+ * canopy point (1) or a mapped tree (0), the model of its form it draws, and a byte of padding.
+ */
+declare const tileflowTreeBytes = 16;
+/**
+ * The form a tree's data gives it, or undefined when its data says nothing about its form: a palm
+ * by `leaf_type` or genus, a column, a conifer by `leaf_type` or genus, or one of the broadleaf
+ * forms by genus. `broadleaf` means the data says broadleaved without a known genus.
+ */
+declare function tileflowTreeFormOf(properties: Readonly<Record<string, unknown>>, fields?: Partial<TileflowTreeFields>): TileflowTreeForm | 'broadleaf' | undefined;
+/** Places a tile's trees. Points in the tile's buffer belong to the neighbouring tile. */
+declare function placeTileflowTrees(layers: TileflowTreeLayers, options: TileflowTreePlacementOptions): TileflowTreePlacement;
+/** The style metadata key under which a compiled map describes its 3D trees. */
+declare const tileflowVegetationMetadataKey = "tileflow:vegetation";
+/** How a compiled map's 3D trees look and where their data is, resolved for one theme. */
+type TileflowVegetation3D = Readonly<{
+    /** The vector source and its layers with the trees and the canopy points. */
+    source: string;
+    layers: Readonly<{
+        tree: string;
+        canopy?: string;
+    }>;
+    fields: TileflowTreeFields;
+    /** Sunlit colours: bark, and the leaves of each kind of tree from darkest to lightest. */
+    colors: Readonly<{
+        bark: string;
+        broadleaf: readonly string[];
+        conifer: readonly string[];
+        palm: readonly string[];
+    }>;
+    heightScale: number;
+    crownScale: number;
+    /** Each form's own scales and models. */
+    forms: Readonly<Partial<Record<TileflowTreeForm, TileflowTreeFormStyle>>>;
+    /** The map's own models its forms draw, by id, prepared from its `models` directories. */
+    models: Readonly<Record<string, TileflowTreeModel>>;
+    finish: TileflowTreeFinish;
+    /** How strongly an outline rings each tree, from 0 (none) to 1, and its colour. */
+    edges: number;
+    edgeColor?: string;
+    unknownForms: TileflowTreeFormMix;
+    regions: readonly TileflowTreeRegion[];
+    /** The style's layers that draw the trees flat, which the 3D trees stand in for while shown. */
+    flatLayers: readonly string[];
+}>;
+/**
+ * Reads the 3D trees a compiled style describes, or undefined when its metadata has none or holds
+ * a version or shape this Core does not know.
+ */
+declare function readTileflowVegetation3D(metadata: unknown): TileflowVegetation3D | undefined;
+
 type TileflowVegetationMode = '3d' | 'flat';
 type TileflowVegetationThreeDimensionalStyle = {
     barkColor?: TileflowThemeColorValue;
+    /** Sunlit leaf colours of broadleaf trees, from darkest to lightest; up to four are used. */
     broadleafColors?: readonly TileflowThemeColorValue[];
+    /** Sunlit needle colours of conifers and columns, from darkest to lightest. */
     coniferColors?: readonly TileflowThemeColorValue[];
+    /** Sunlit frond colours of palms, from darkest to lightest; the broadleaf colours by default. */
+    palmColors?: readonly TileflowThemeColorValue[];
     crownScale?: TileflowThemeNumberValue;
     heightScale?: TileflowThemeNumberValue;
+    /**
+     * How trees take the light: `faceted` (the default), low-poly facets softened towards a round
+     * crown; `smooth`, round crowns; or `toon`, three bands of light and a crisp shadow, as a drawn
+     * tree has them.
+     */
+    finish?: TileflowTreeFinish;
+    /** How strongly an outline rings each tree, from 0 (none, the default) to 1. */
+    edges?: TileflowThemeNumberValue;
+    /** The outline's colour; the crown's darkest colour, deepened, by default. */
+    edgeColor?: TileflowThemeColorValue;
+    /**
+     * Each form's own scales, on top of `heightScale` and `crownScale`, such as taller palms, and the
+     * map's own models it draws: ids of `.glb` files in the map's `models` directories, one to four,
+     * each tree drawing one. A model's materials named `bark`, `leaves`, `fronds` or `stem` take
+     * those parts' colours.
+     */
+    forms?: Partial<Record<TileflowTreeForm, {
+        heightScale?: TileflowThemeNumberValue;
+        crownScale?: TileflowThemeNumberValue;
+        models?: readonly string[];
+    }>>;
+    /**
+     * The forms of trees whose data gives none, as relative weights: `round`, `open` and `tall`
+     * (broadleaf), `conifer`, `columnar` and `palm`. Each tree draws one from a stable hash, so it
+     * keeps its form everywhere. Defaults to the three broadleaf forms, evenly. A tree the data calls
+     * broadleaved keeps to the broadleaf forms of the mix.
+     */
+    unknownForms?: TileflowTreeFormMix;
+    /**
+     * Regions whose trees without a form in the data take their own mix, such as palms along a
+     * subtropical coast. Bounds are `[west, south, east, north]` in degrees; the first region holding
+     * a tree applies. At most 16.
+     */
+    regions?: readonly TileflowTreeRegion[];
 };
 type TileflowVegetationModuleOptions = {
     flat?: TileflowCircleStyle;
@@ -830,6 +1209,800 @@ 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 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`, and to Core's PMTiles protocol for a source served from a
+     * Tileflow PMTiles archive (`tileflow-pmtiles://`).
+     */
+    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 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 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 map's design: a Tileflow theme controller. */
+type TileflowBuildings3DThemes = {
+    getSun?(): TileflowSun;
+    getThemeMetadata?(key: string): Readonly<{
+        values: readonly unknown[];
+        position: number;
+    }>;
+};
+type TileflowBuildings3DOptions = Readonly<{
+    map: TileflowBuildings3DMap;
+    /** The theme controller, for the sun and the buildings' design in every theme. */
+    controller?: TileflowBuildings3DThemes;
+    /** 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;
+    /**
+     * Whether the map's style describes its 3D buildings (the buildings module's
+     * `threeDimensional`), tiles raised, buildings and vertices, for diagnostics.
+     */
+    readonly stats: Readonly<{
+        declared: boolean;
+        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 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;
+
+/** 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 and whose themes hold the map's
+     * street lights (the roads module's `streetLights`).
+     */
+    controller?: {
+        getSun?(): TileflowSun;
+        getThemeMetadata?(key: string): Readonly<{
+            values: readonly unknown[];
+            position: 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;
+    /**
+     * Whether the map's style describes its street lights, tiles lit, lamps, and how many of them the
+     * data maps or the layer estimates.
+     */
+    readonly stats: Readonly<{
+        declared: boolean;
+        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 style metadata key under which a compiled map describes its 3D buildings. */
+declare const tileflowBuildingsMetadataKey = "tileflow:buildings";
+/** A compiled map's 3D buildings, resolved for one theme. */
+type TileflowBuildings3DDesign = Readonly<{
+    /** The vector source and its layers with the buildings and the places they hold. */
+    source: string;
+    layers: Readonly<{
+        building: string;
+        places?: string;
+    }>;
+    /**
+     * Each building's colour: a CSS colour, or a MapLibre expression over the building's
+     * properties that gives one, as the map colours its 3D buildings (or its roofs).
+     */
+    color: string | readonly unknown[];
+    /** How strongly roof outlines and outer corners catch the light, from 0 to 1. */
+    edges: number;
+    /** Their own colour, drawn unlit; without it they take the building's colour, lightened. */
+    edgeColor?: string;
+    /** How bright the buildings light the street at night, from 0 to 2. */
+    nightLight: number;
+    /** Invented night windows, lit by rooms: decoration, not data. */
+    windows: boolean;
+    /** Shadows from the sun, and contact shadow at the foot of the walls. */
+    shadows: boolean;
+    occlusion: boolean;
+}>;
+/**
+ * Reads the 3D buildings a compiled style describes, or undefined when its metadata has none or a
+ * version or shape this Core does not know.
+ */
+declare function readTileflowBuildings3D(metadata: unknown): TileflowBuildings3DDesign | undefined;
+
+/** The MapLibre GL JS map capabilities the trees use. */
+type TileflowTrees3DMap = {
+    addLayer(layer: object, beforeId?: string): unknown;
+    getBearing(): number;
+    getCenter(): {
+        lat: number;
+        lng: number;
+    };
+    getLayer(id: string): unknown;
+    getLayoutProperty?(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;
+    setLayoutProperty?(layer: string, name: string, value: unknown): unknown;
+    triggerRepaint(): unknown;
+};
+/** Where the trees read the sun and the map's design: a Tileflow theme controller. */
+type TileflowTrees3DThemes = {
+    getSun?(): TileflowSun;
+    getThemeMetadata?(key: string): Readonly<{
+        values: readonly unknown[];
+        position: number;
+    }>;
+};
+type TileflowTrees3DOptions = Readonly<{
+    map: TileflowTrees3DMap;
+    /** The theme controller, for the sun and the trees' colours in every theme. */
+    controller?: TileflowTrees3DThemes;
+    /** The vector source with the canopy points, when not the map's World source. */
+    canopySource?: string;
+    /** The zoom from which trees stand; they fade in over the zoom above it. Defaults to 15. */
+    minzoom?: number;
+    /** The most tiles of trees 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 TileflowTrees3DChange = Readonly<{
+    transition?: Readonly<{
+        duration?: number;
+    }>;
+}>;
+type TileflowTrees3D = {
+    /** Grows the trees out of the ground; resolves once they stand. */
+    show(options?: TileflowTrees3DChange): Promise<void>;
+    /** Sinks the trees back into the ground; resolves once they are gone. */
+    hide(options?: TileflowTrees3DChange): Promise<void>;
+    /** Eases the trees to `scale` of their size, from 0 (none) to 1. */
+    grow(scale: number, options?: TileflowTrees3DChange): Promise<void>;
+    /** The size scale shown now. */
+    readonly scale: number;
+    /**
+     * Whether the map's style describes 3D trees (`vegetation({mode: '3d'})`), tiles of trees,
+     * trees placed (mapped and from canopy points) and trees drawn in the last frame.
+     */
+    readonly stats: Readonly<{
+        declared: boolean;
+        tiles: number;
+        trees: number;
+        mapped: number;
+        canopy: number;
+        drawn: number;
+    }>;
+    /** Takes the layer off the map and lets go of its buffers. */
+    dispose(): void;
+};
+declare const tileflowTrees3DLayerId = "tileflow-trees-3d";
+/**
+ * Creates the trees and puts their layer on the map, sunk in the ground until `show()`. They read
+ * the source's z15 tiles round the camera, where World carries its trees and canopy points.
+ */
+declare function createTileflowTrees3D(options: TileflowTrees3DOptions): TileflowTrees3D;
+
+/** 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 style metadata key under which a compiled map describes its street lights. */
+declare const tileflowStreetLightsMetadataKey = "tileflow:street-lights";
+/** A compiled map's street lights, as the roads module describes them, resolved for one theme. */
+type TileflowStreetLightsDesign = Readonly<{
+    /** The vector source and its layers with the lamps, the streets and the pavements. */
+    source: string;
+    layers: Readonly<{
+        streetFurniture: string;
+        transportation: string;
+        sidewalk?: string;
+    }>;
+    estimate: TileflowStreetLightEstimate;
+    /** The light of lamps whose data gives no colour, as a CSS colour. */
+    color: string;
+    /** How bright the lights shine, from 0 to 2. */
+    intensity: number;
+}>;
+/**
+ * Reads the street lights a compiled style describes, or undefined when its metadata has none or a
+ * version or shape this Core does not know.
+ */
+declare function readTileflowStreetLights(metadata: unknown): TileflowStreetLightsDesign | undefined;
+
+/** 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;
@@ -940,6 +2113,7 @@ type TileflowThemeBlendState = Readonly<{
     themes: readonly string[];
 }>;
 type TileflowStyleSwitchMap = TileflowThemeMotionMap & TileflowDynamicImageMap & {
+    getCenter?: unknown;
     getGlobalState?: unknown;
     off(event: string, listener: (event?: unknown) => void): unknown;
     on(event: string, listener: (event?: unknown) => void): unknown;
@@ -948,6 +2122,18 @@ type TileflowStyleSwitchMap = TileflowThemeMotionMap & TileflowDynamicImageMap &
 };
 /** 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. */
@@ -958,8 +2144,31 @@ type TileflowThemeController = {
     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;
+    /**
+     * What the compiled styles on screen hold under a metadata key, for an application's own layers
+     * drawn in the map's design (Core's 3D trees read their colours this way): one value outside a
+     * blend, and during a blend one per blended theme, in order, with the blend's position, so a layer
+     * can mix them as the map does. A style without the key gives undefined in its place.
+     */
+    getThemeMetadata(key: string): Readonly<{
+        values: readonly unknown[];
+        position: number;
+    }>;
+    /**
+     * 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
@@ -982,6 +2191,13 @@ type TileflowThemeController = {
      * 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>;
 };
 /**
@@ -1063,4 +2279,4 @@ declare function createTileflowTransformRequest<TRequest extends TileflowTransfo
     worldRequestBridge?: TileflowWorldRequestBridge;
 }): TileflowTransformRequest<TRequest, TResourceType>;
 
-export { type TileflowAtmosphereMap, type TileflowBrowserThemeBlendSelection, type TileflowComposedRequest, type TileflowContourProtocolHandler, type TileflowContourProtocolRegistrationOptions, type TileflowContourProtocolRegistry, type TileflowContourProtocolRequest, type TileflowContourProtocolResponse, type TileflowDynamicImage, type TileflowDynamicImageContext, type TileflowDynamicImageHandle, 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 TileflowStyleStateValue, 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, validateTileflowBrowserThemeBlendSelection, validateTileflowEmphasis };
+export { type TileflowAtmosphereMap, type TileflowBrowserThemeBlendSelection, type TileflowBuildingMesh, type TileflowBuildingMeshOptions, type TileflowBuildings3D, type TileflowBuildings3DChange, type TileflowBuildings3DDesign, 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 TileflowStreetLightsDesign, 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 TileflowTreeFields, type TileflowTreeForm, type TileflowTreeFormMix, type TileflowTreeFormRange, type TileflowTreeLayers, type TileflowTreePlacement, type TileflowTreePlacementOptions, type TileflowTreeRange, type TileflowTreeRegion, type TileflowTrees3D, type TileflowTrees3DChange, type TileflowTrees3DMap, type TileflowTrees3DOptions, type TileflowTrees3DThemes, type TileflowUserTransformRequest, type TileflowVectorTileDecodeOptions, type TileflowVegetation3D, type TileflowWorldProtocolHandler, type TileflowWorldProtocolRequest, type TileflowWorldProtocolResponse, type TileflowWorldRequestBridge, attachTileflowAtmosphere, attachTileflowFairUseNotice, attachTileflowMapLifecycle, createTileflowBuildings3D, createTileflowDepthMarkers, createTileflowGroundLayers, createTileflowLineProgress, createTileflowSessionStarter, createTileflowStreetLights, createTileflowThemeController, createTileflowTileReader, createTileflowTransformRequest, createTileflowTrees3D, decodeTileflowVectorTile, getTileflowSystemColorScheme, loadTileflowStyleFonts, meshTileflowBuildings, mixTileflowRouteInks, mixTileflowSunPresets, placeTileflowStreetLights, placeTileflowTrees, playTileflowShot, readTileflowBuildings3D, readTileflowMapTileSource, readTileflowRouteInks, readTileflowStreetLights, readTileflowSunPreset, readTileflowVegetation3D, registerTileflowContourProtocol, registerTileflowPmtilesProtocol, registerTileflowWorldRequestBridge, resolveTileflowSun, subscribeTileflowSystemColorScheme, tileflowBuildingExtent, tileflowBuildingVertexBytes, tileflowBuildings3DLayerId, tileflowBuildingsMetadataKey, tileflowDefaultRouteInks, tileflowDefaultSunPreset, tileflowDepthMarkerPlacement, tileflowFairUseNoticeMessage, tileflowGroundBeforeId, tileflowLayerDomainMetadataKey, tileflowLineProgressGradient, tileflowMaplibreContourVersion, tileflowPmtilesMaximumDirectoryDepth, tileflowPmtilesProtocol, tileflowRouteMetadataKey, tileflowShotStateAt, tileflowStreetLightBytes, tileflowStreetLightsLayerId, tileflowStreetLightsMetadataKey, tileflowStyleRouteInks, tileflowStyleSunPreset, tileflowSunDirection, tileflowSunLightMatrix, tileflowSunMetadataKey, tileflowSunPosition, tileflowTilePointToLngLat, tileflowTilesForBounds, tileflowTreeBytes, tileflowTreeFormOf, tileflowTreeForms, tileflowTrees3DLayerId, tileflowVegetationMetadataKey, validateTileflowBrowserThemeBlendSelection, validateTileflowEmphasis };