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

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>>;
@@ -490,21 +509,50 @@ declare const tileflowPoiCategories: readonly ["arts-entertainment", "education"
 type TileflowPoiCategory = (typeof tileflowPoiCategories)[number];
 type TileflowPoiDensity = 1 | 2 | 3 | 4 | 5;
 type TileflowPoiColorMode = 'uniform' | 'category';
-type TileflowPoiCategoryStyle = Omit<TileflowMarkerSymbolStyle, 'priority'> & {
-    /** Optional category-local cap within the module's canonical density tiers. */
-    density?: TileflowPoiDensity;
-};
+/**
+ * How POI categories are placed against each other. `importance` places every category in one
+ * order, by World's ranks. `categories` gives each category its own layer and places the
+ * categories in the order they are listed, the first on top; ranks order each category only.
+ */
+type TileflowPoiPlacementOrder = 'categories' | 'importance';
+/**
+ * The appearance of one POI category. With the default `importance` order every category shares
+ * one placement layer, so categories may differ only in properties MapLibre evaluates per feature
+ * (image, size, colors, font, offsets); layer-wide properties such as zoom ranges, padding,
+ * overlap or `optional` must match, or the module uses `placement.order: 'categories'`.
+ */
+type TileflowPoiCategoryStyle = Omit<TileflowMarkerSymbolStyle, 'priority'>;
 type TileflowPoiModuleConfig = {
     type: 'poi';
     categories?: readonly TileflowPoiCategory[];
     color?: TileflowPoiColorMode;
+    /** One density for the whole module: World's ranks decide what each category shows. */
     density?: TileflowPoiDensity;
     icons?: boolean;
     labels?: boolean;
     minZoom?: number;
     placement?: {
+        /**
+         * Places each pictogram with its name as one unit that needs room for both. Defaults to
+         * `false`.
+         */
         coupleIconAndLabel?: boolean;
         iconPadding?: number;
+        /**
+         * World POI `type` values whose pictogram explains them. When pictograms and names are both
+         * drawn, every other POI needs a name, and these types are drawn as a pictogram alone.
+         * Defaults to parking and public toilets.
+         */
+        iconOnlyTypes?: readonly string[];
+        /** Defaults to `importance`. */
+        order?: TileflowPoiPlacementOrder;
+        /**
+         * With the `importance` order, POIs whose World `filter_rank` is at most this value are placed
+         * before the map's road and place labels, and the others after them. A map that gives street
+         * names priority over POIs (labels `collisionPriority: 'navigation'`) keeps its landmarks this
+         * way. Unset, every POI is placed at the module's own position.
+         */
+        prominentRank?: 0 | 1 | 2 | 3 | 4 | 5;
         textPadding?: number;
     };
     styles?: Partial<Record<TileflowPoiCategory, TileflowPoiCategoryStyle>>;
@@ -741,11 +789,69 @@ 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 = {
+    /** Use the style's extrusion light (default), or the theme controller's scene sun. */
+    lighting?: 'style' | 'sun';
+    /** Per-building brightness variation, from 0 to 1; defaults to 0 (authored colour). */
+    colorVariation?: TileflowThemeNumberValue;
+    /** How strongly roof outlines and outer corners catch the light, from 0 (default) to 1. */
+    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 0. */
+    nightLight?: TileflowThemeNumberValue;
+    /** Contact shadow at the foot of the walls and in tight corners; defaults to false. */
+    occlusion?: boolean;
+    /** Shadows from the sun, on the buildings and the flat map; defaults to false. */
+    shadows?: boolean;
+    /**
+     * Invented night windows, lit by rooms: decoration, not data. With World's `class`, none on sheds,
+     * barns, factories and churches, and homes lit apart from offices. Defaults to false.
+     */
+    windows?: boolean;
+    /**
+     * Building models the map places in its city, from the glTF binaries in its `models`
+     * directories. Each stands in for the buildings under its footprint.
+     */
+    models?: readonly TileflowBuildingModelPlacementConfig[];
+    /** The colours of the models' parts; a part without one takes it from the building colour. */
+    modelColors?: Partial<Record<TileflowBuildingModelPart, TileflowThemeColorValue>>;
+    /**
+     * Tileflow's landmarks, such as the Eiffel Tower, drawn as models in place of the buildings
+     * under them. On by default with Tileflow World data; `false` switches them off, and `url` names
+     * the TileJSON of another landmarks tileset. The map's own `models` come first: a landmark with
+     * the same id as one, or whose footprint meets one's, is not drawn.
+     */
+    landmarks?: boolean | {
+        url: string;
+    };
+};
+/** The parts of a building model, as its materials name them. */
+type TileflowBuildingModelPart = 'surface' | 'secondary' | 'glass' | 'accent' | 'roof';
+/** Where a building model stands. */
+type TileflowBuildingModelPlacementConfig = {
+    /** The model's id: the name of its `.glb` file in the map's `models` directories. */
+    model: string;
+    /**
+     * The HTTPS address of the model's prepared file when it is served elsewhere, such as a model
+     * Tileflow hosts for its own maps; the map then needs no `.glb` of its own for it.
+     */
+    url?: string;
+    /** Longitude and latitude of the model's origin, where it stands on the ground. */
+    at: readonly [number, number];
+    /** Degrees clockwise from north that the model's own north (its +y) is turned to; defaults to 0. */
+    heading?: number;
+};
 type TileflowBuildingsModuleOptions = {
     businessCorridor?: TileflowAreaStyle;
     extrusion?: TileflowExtrusionStyle;
     flat?: TileflowAreaStyle;
     mode?: TileflowBuildingMode;
+    threeDimensional?: TileflowBuildingsThreeDimensionalStyle;
 };
 type TileflowBuildingsModuleConfig = TileflowBuildingsModuleOptions & {
     type: 'buildings';
@@ -816,17 +922,232 @@ type TileflowTransitModuleConfig = TileflowTransitModuleOptions & {
     type: 'transit';
 };
 
-type TileflowVegetationMode = '3d' | 'flat';
+/** 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' | 'auto';
 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;
+    /** `3d` uses models at every pitch; `auto` follows the runtime's explicit 2D/3D view mode. */
     mode?: TileflowVegetationMode;
+    /** Representation when a renderer cannot draw models. Defaults to `flat`. */
+    fallback?: 'flat' | 'none';
+    /** Initial visibility; a runtime control may override it. Defaults to true. */
+    visible?: boolean;
     threeDimensional?: TileflowVegetationThreeDimensionalStyle;
 };
 type TileflowVegetationModuleConfig = TileflowVegetationModuleOptions & {
@@ -836,10 +1157,14 @@ type TileflowVegetationModuleConfig = TileflowVegetationModuleOptions & {
 type TileflowWaterwayClass = 'canal' | 'other' | 'river' | 'stream';
 type TileflowWaterModuleOptions = {
     bathymetry?: TileflowFillStyle;
-    /** Opt-in approximate contours traced from discrete bathymetry polygon band edges. */
+    /** Contour lines when declared by Bathymetry; otherwise approximate polygon band edges. */
     bathymetryContours?: TileflowLineStyle;
-    /** Opt-in labels for bathymetry polygon band floors, not measured survey soundings. */
+    /** Contour-depth or legacy band-floor labels, not measured survey soundings. */
     bathymetryLabels?: TileflowSymbolStyle;
+    /** Names from an explicitly declared seafloor_landform layer. */
+    bathymetryLandforms?: TileflowSymbolStyle;
+    /** Names from an explicitly declared water_name layer. */
+    bathymetryWaterNames?: TileflowSymbolStyle;
     bodies?: TileflowAreaStyle;
     intermittent?: {
         bodies?: TileflowAreaStyle;
@@ -1062,30 +1387,20 @@ type TileflowLineProgressController = {
  */
 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[];
+/** Bounded, read-only mesh snapshot for developer tooling. Positions are x east, y north, z up. */
+type TileflowModelInspection = Readonly<{
+    id: string;
+    module: string;
+    format: string;
+    vertices: number;
+    triangles: number;
+    bytes: number;
+    lods: number;
+    instances?: number;
+    positions: number[];
+    indices: number[];
+    colors?: 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;
@@ -1097,7 +1412,11 @@ 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<{
+type TileflowTileRequestTransform = (url: string, resourceType: 'Tile') => Promise<Readonly<{
+    url: string;
+    headers?: Readonly<Record<string, string>>;
+    credentials?: RequestCredentials;
+}> | undefined> | Readonly<{
     url: string;
     headers?: Readonly<Record<string, string>>;
     credentials?: RequestCredentials;
@@ -1117,7 +1436,10 @@ type TileflowTileReaderOptions = Readonly<{
     concurrency?: number;
     /** The map's request rules, applied to every tile request. */
     transformRequest?: TileflowTileRequestTransform;
-    /** Defaults to the global `fetch`. */
+    /**
+     * 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<{
@@ -1162,6 +1484,21 @@ declare function readTileflowMapTileSource(map: TileflowTileSourceMap, sourceId:
     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;
@@ -1170,6 +1507,7 @@ type TileflowBuildings3DMap = {
         lng: number;
     };
     getBearing(): number;
+    getLight?(): unknown;
     getLayer(id: string): unknown;
     getPaintProperty(layer: string, name: string): unknown;
     getPitch(): number;
@@ -1182,64 +1520,18 @@ type TileflowBuildings3DMap = {
     removeLayer(id: string): unknown;
     triggerRepaint(): unknown;
 };
-/** Where the renderer reads the sun and the themes: a Tileflow theme controller. */
+/** Where the renderer reads the sun and the map's design: a Tileflow theme controller. */
 type TileflowBuildings3DThemes = {
-    getBlend?(): {
-        position: number;
-        themes: readonly string[];
-    } | undefined;
-    getCurrent?(): {
-        theme?: string;
-    };
     getSun?(): TileflowSun;
+    getThemeMetadata?(key: string): Readonly<{
+        values: readonly unknown[];
+        position: number;
+    }>;
 };
 type TileflowBuildings3DOptions = Readonly<{
     map: TileflowBuildings3DMap;
-    /** The theme controller, for the sun and, with `color`, the themes on screen. */
+    /** The theme controller, for the sun and the buildings' design in every theme. */
     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. */
@@ -1252,22 +1544,31 @@ type TileflowBuildings3DOptions = Readonly<{
 type TileflowBuildings3DChange = Readonly<{
     transition?: Readonly<{
         duration?: number;
+        mode?: 'grow' | 'fade';
     }>;
 }>;
 type TileflowBuildings3D = {
-    /** Raises the buildings out of the ground; resolves once they stand. */
+    /** Read-only, bounded snapshots of resident prepared model meshes. */
+    inspectModels(): TileflowModelInspection[];
+    /** Shows buildings immediately; pass a transition duration to animate their rise. */
     show(options?: TileflowBuildings3DChange): Promise<void>;
-    /** Sinks the buildings back into the flat map; resolves once they are gone. */
+    /** Hides buildings immediately; pass a transition duration to animate their descent. */
     hide(options?: TileflowBuildings3DChange): Promise<void>;
-    /** Eases the buildings to `scale` of their height, from 0 (flat) to 1. */
+    /** Sets the height scale, from 0 (flat) to 1; animation requires a transition duration. */
     grow(scale: number, options?: TileflowBuildings3DChange): Promise<void>;
     /** The height scale shown now. */
     readonly scale: number;
-    /** Tiles raised, buildings and vertices, for diagnostics. */
+    /**
+     * Whether the map's style describes its 3D buildings (the buildings module's
+     * `threeDimensional`), tiles raised, buildings and vertices, and the placed models standing, for
+     * diagnostics.
+     */
     readonly stats: Readonly<{
+        declared: boolean;
         tiles: number;
         buildings: number;
         vertices: number;
+        models: number;
     }>;
     /** Takes the layer off the map and lets go of its buffers. */
     dispose(): void;
@@ -1278,20 +1579,6 @@ declare const tileflowBuildings3DLayerId = "tileflow-buildings-3d";
  * 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;
@@ -1308,6 +1595,12 @@ type TileflowBuildingMeshOptions = Readonly<{
      * the building its use.
      */
     places?: TileflowTileLayer;
+    /**
+     * Footprints of the building models standing here, as rings of tile units (0 to 8192): a
+     * building whose centre falls inside one, or that reaches more than half a metre into one, is not
+     * raised, since the model stands in for it.
+     */
+    masks?: readonly (readonly number[])[];
 }>;
 /** One tile's buildings, ready to upload. */
 type TileflowBuildingMesh = Readonly<{
@@ -1322,12 +1615,13 @@ type TileflowBuildingMesh = Readonly<{
 }>;
 /**
  * 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:
+ * World's `render_height`, `render_min_height`, `hide_3d`, `building_tone`, `class` 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
+ * 16 the building's centre in the tile (uint16 ×2); 20 tone plus four times its class group, 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
@@ -1340,47 +1634,6 @@ type TileflowBuildingMesh = Readonly<{
  */
 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;
@@ -1402,23 +1655,17 @@ type TileflowStreetLightsMap = {
 };
 type TileflowStreetLightsOptions = Readonly<{
     map: TileflowStreetLightsMap;
-    /** The theme controller, whose sun switches the lights on and off. */
+    /**
+     * 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 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. */
@@ -1431,8 +1678,12 @@ type TileflowStreetLightsOptions = Readonly<{
 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. */
+    /**
+     * 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;
@@ -1448,6 +1699,226 @@ declare const tileflowStreetLightsLayerId = "tileflow-street-lights";
  */
 declare function createTileflowStreetLights(options: TileflowStreetLightsOptions): TileflowStreetLights;
 
+/** The parts of a model, each coloured by the theme: the model's materials name them. */
+declare const tileflowModelParts: Readonly<{
+    surface: 0;
+    secondary: 1;
+    glass: 2;
+    accent: 3;
+    roof: 4;
+}>;
+type TileflowModelPart = keyof typeof tileflowModelParts;
+
+/** 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;
+    /** Style extrusion light by default; scene sun lighting is opt-in. */
+    lighting: 'style' | 'sun';
+    /** Per-building brightness variation, from 0 to 1; 0 preserves the authored colour. */
+    colorVariation: number;
+    /** The authored extrusion's vertical wall gradient. */
+    verticalGradient: boolean;
+    /** 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;
+    /** Building models the map places in its city, each replacing the buildings under it. */
+    models?: readonly TileflowBuildingModelPlacement[];
+    /** The colours of the models' parts; a part without one takes it from the building colour. */
+    modelColors?: Readonly<Partial<Record<TileflowModelPart, string>>>;
+    /**
+     * Tileflow's landmarks, drawn as models in place of the buildings under them: the TileJSON of
+     * their tileset. Without it, the map shows none.
+     */
+    landmarks?: Readonly<{
+        url: string;
+    }>;
+}>;
+/** A building model standing in the map's city. */
+type TileflowBuildingModelPlacement = Readonly<{
+    /** The model's id, its file's name in the map's `models` directories. */
+    model: string;
+    /** Where the prepared model file is served, absolute or relative to the page. */
+    url: string;
+    /** Longitude and latitude of the model's origin, where it stands on the ground. */
+    at: readonly [number, number];
+    /** Degrees clockwise from north that the model's own north is turned to. */
+    heading: number;
+}>;
+/**
+ * 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 most models one map places. */
+declare const tileflowBuildingModelPlacementLimit = 256;
+
+/** 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;
+    /** Let a vegetation controller own flat-layer visibility. Defaults to true. */
+    manageFlatLayers?: boolean;
+}>;
+type TileflowTrees3DChange = Readonly<{
+    transition?: Readonly<{
+        duration?: number;
+    }>;
+}>;
+type TileflowTrees3D = {
+    /** Read-only snapshots of the meshes used by the active vegetation palette. */
+    inspectModels(): TileflowModelInspection[];
+    /** 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;
@@ -1724,6 +2195,50 @@ declare const tileflowPmtilesProtocol: "tileflow-pmtiles";
 /** Register only Tileflow's managed PMTiles namespace. Third-party `pmtiles://` remains untouched. */
 declare function registerTileflowPmtilesProtocol(registry: TileflowPmtilesProtocolRegistry, options?: TileflowPmtilesProtocolRegistrationOptions): void;
 
+type TileflowViewMode = '2d' | '3d';
+type TileflowVegetationRepresentation = 'none' | 'flat' | '3d';
+declare const tileflowVegetationDisplayMetadataKey = "tileflow:vegetation-display";
+/** Display policy, separate from the models' design and the camera's pitch. */
+type TileflowVegetationDisplay = Readonly<{
+    version: 1;
+    mode: TileflowVegetationMode;
+    fallback: 'flat' | 'none';
+    visible: boolean;
+    /** Authored visibility before the compiler applies the static fallback. */
+    flatLayers: readonly Readonly<{
+        id: string;
+        visible: boolean;
+    }>[];
+}>;
+declare function readTileflowVegetationDisplay(metadata: unknown): TileflowVegetationDisplay | undefined;
+declare function resolveTileflowVegetationRepresentation(policy: TileflowVegetationDisplay | undefined, options: {
+    visible?: boolean | undefined;
+    viewMode?: TileflowViewMode;
+    supports3D: boolean;
+}): TileflowVegetationRepresentation;
+
+type TileflowVegetationOptions = Omit<TileflowTrees3DOptions, 'manageFlatLayers' | 'map'> & {
+    map: TileflowTrees3DOptions['map'] & {
+        getCanvas?(): HTMLCanvasElement;
+    };
+    /** Overrides the map's visibility. Undefined restores the authored default. */
+    visible?: boolean | undefined;
+    /** Explicit application view mode, independent of pitch and building visibility. Defaults to 2d. */
+    viewMode?: TileflowViewMode;
+};
+type TileflowVegetationController = {
+    inspectModels: TileflowTrees3D['inspectModels'];
+    setVisible(visible: boolean | undefined): void;
+    setViewMode(mode: TileflowViewMode): void;
+    /** Reapplies the policy after application layer controls change. */
+    refresh(): void;
+    readonly representation: TileflowVegetationRepresentation;
+    readonly stats: TileflowTrees3D['stats'] | undefined;
+    dispose(): void;
+};
+/** Mount once per map. OFF hides every representation; mode selects how enabled trees are drawn. */
+declare function createTileflowVegetation(options: TileflowVegetationOptions): TileflowVegetationController;
+
 type TileflowMapReadinessState = 'error' | 'idle' | 'loading';
 /** Read the browser preference without persisting or mutating user state. */
 declare function getTileflowSystemColorScheme(): TileflowRuntimeColorScheme;
@@ -1834,6 +2349,16 @@ type TileflowThemeController = {
     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
@@ -1951,4 +2476,4 @@ declare function createTileflowTransformRequest<TRequest extends TileflowTransfo
     worldRequestBridge?: TileflowWorldRequestBridge;
 }): TileflowTransformRequest<TRequest, TResourceType>;
 
-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 };
+export { type TileflowAtmosphereMap, type TileflowBrowserThemeBlendSelection, type TileflowBuildingMesh, type TileflowBuildingMeshOptions, type TileflowBuildingModelPlacement, 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 TileflowVegetationController, type TileflowVegetationDisplay, type TileflowVegetationOptions, type TileflowVegetationRepresentation, type TileflowViewMode, type TileflowWorldProtocolHandler, type TileflowWorldProtocolRequest, type TileflowWorldProtocolResponse, type TileflowWorldRequestBridge, attachTileflowAtmosphere, attachTileflowFairUseNotice, attachTileflowMapLifecycle, createTileflowBuildings3D, createTileflowDepthMarkers, createTileflowGroundLayers, createTileflowLineProgress, createTileflowSessionStarter, createTileflowStreetLights, createTileflowThemeController, createTileflowTileReader, createTileflowTransformRequest, createTileflowTrees3D, createTileflowVegetation, decodeTileflowVectorTile, getTileflowSystemColorScheme, loadTileflowStyleFonts, meshTileflowBuildings, mixTileflowRouteInks, mixTileflowSunPresets, placeTileflowStreetLights, placeTileflowTrees, playTileflowShot, readTileflowBuildings3D, readTileflowMapTileSource, readTileflowRouteInks, readTileflowStreetLights, readTileflowSunPreset, readTileflowVegetation3D, readTileflowVegetationDisplay, registerTileflowContourProtocol, registerTileflowPmtilesProtocol, registerTileflowWorldRequestBridge, resolveTileflowSun, resolveTileflowVegetationRepresentation, subscribeTileflowSystemColorScheme, tileflowBuildingExtent, tileflowBuildingModelPlacementLimit, 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, tileflowVegetationDisplayMetadataKey, tileflowVegetationMetadataKey, validateTileflowBrowserThemeBlendSelection, validateTileflowEmphasis };