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

package/dist/{manifest-types-E7m23eXL.d.ts → manifest-types-hmzy2bBX.d.ts}

@@ -444,6 +444,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;
@@ -465,6 +483,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>>;
@@ -804,4 +823,4 @@ type TileflowRuntimeManifest = {
     version: typeof tileflowRuntimeManifestVersion;
 };
 
-export { type TileflowManifestFetchOptions as $, type TileflowAreaStyle as A, type TileflowBackgroundPaint as B, type TileflowCirclePaint as C, type TileflowColor as D, type TileflowColorStyleValue as E, type TileflowExtrusionPaint as F, type TileflowFillPaint as G, type TileflowIconAnchor as H, type TileflowIconLayout as I, type TileflowIconPaint as J, type TileflowIconStyle as K, type TileflowIconTextFit as L, type MapLibreStyle as M, type TileflowImageStyleValue as N, type TileflowLabelDetail as O, type TileflowLabelLanguage as P, type TileflowLabelStyles as Q, type TileflowLayerRange as R, type TileflowLight as S, type TileflowRuntimeManifest as T, type TileflowLineCap as U, type ValidationMessage as V, type TileflowLineHatchStyle as W, type TileflowLineJoin as X, type TileflowLineLayout as Y, type TileflowLinePaint as Z, type TileflowLineStackStyle as _, type TileflowRuntimeColorScheme as a, type TileflowTextAnchor as a$, type TileflowManifestLoadOptions as a0, type TileflowMapMode as a1, type TileflowMapModeOptions as a2, type TileflowMarkerSymbolStyle as a3, type TileflowMountainBikeScale as a4, type TileflowNumberInsetsStyleValue as a5, type TileflowNumberStyleValue as a6, type TileflowPlaceLabelClass as a7, type TileflowPoiCategory as a8, type TileflowPoiCategoryStyle as a9, type TileflowRoadWeight as aA, type TileflowRuntimeCenterLike as aB, type TileflowRuntimeManifestMap as aC, type TileflowRuntimeSource as aD, type TileflowRuntimeSourceValidation as aE, type TileflowRuntimeStyle as aF, type TileflowRuntimeStyleOptions as aG, type TileflowRuntimeViewOptions as aH, type TileflowSessionController as aI, type TileflowSessionGrantResponse as aJ, type TileflowStringStyleValue as aK, type TileflowStructuralStyleValue as aL, type TileflowStyleFontFace as aM, type TileflowStyleValue as aN, type TileflowSymbolOverlap as aO, type TileflowSymbolPlacement as aP, type TileflowSymbolPlacementStyle as aQ, type TileflowSymbolZOrder as aR, type TileflowTerrain as aS, type TileflowTerrainConfig as aT, type TileflowTerrainContourLabelStyle as aU, type TileflowTerrainContourLineStyle as aV, type TileflowTerrainContoursConfig as aW, type TileflowTerrainEncoding as aX, type TileflowTerrainHillshadeStyle as aY, type TileflowTerrainLayerRange as aZ, type TileflowTerrainMode as a_, type TileflowPoiColorMode as aa, type TileflowPoiDensity as ab, type TileflowPriorityOrder as ac, type TileflowProjection as ad, type TileflowResolvedRuntimeTheme as ae, type TileflowRoadAreaStyle as af, type TileflowRoadClass as ag, type TileflowRoadClassStyle as ah, type TileflowRoadCrossingStyle as ai, type TileflowRoadDetail as aj, type TileflowRoadExtras as ak, type TileflowRoadHierarchy as al, type TileflowRoadLabelDetail as am, type TileflowRoadLayerStyle as an, type TileflowRoadModifier as ao, type TileflowRoadOutline as ap, type TileflowRoadRestriction as aq, type TileflowRoadRoundaboutStyle as ar, type TileflowRoadServiceType as as, type TileflowRoadShieldDetail as at, type TileflowRoadShieldStyles as au, type TileflowRoadSidewalkStyle as av, type TileflowRoadStructure as aw, type TileflowRoadTreatmentLayerStyle as ax, type TileflowRoadTreatmentLineStyle as ay, type TileflowRoadTreatmentStyle as az, type TileflowRuntimeManifestMapEntry as b, type TileflowTextBackground as b0, type TileflowTextJustify as b1, type TileflowTextLayout as b2, type TileflowTextPaint as b3, type TileflowTextStyle as b4, type TileflowThemeBlendSelection as b5, type TileflowThemeColorAlpha as b6, type TileflowThemeColorMix as b7, type TileflowThemeColorValue as b8, type TileflowThemeFontValue as b9, normalizeTileflowUrl as bA, resolveTileflowAnalyticsRequestUrl as bB, resolveTileflowManifestMap as bC, resolveTileflowMapMode as bD, resolveTileflowRuntimeStyle as bE, resolveTileflowRuntimeTheme as bF, resolveTileflowRuntimeThemeBlend as bG, resolveTileflowRuntimeView as bH, resolveTileflowStaticImageUrl as bI, shouldLoadTileflowManifest as bJ, startTileflowSession as bK, tileflowPoiCategories as bL, tileflowStyleFontFaceLimits as bM, tileflowStyleFontFacesMetadataKey as bN, tileflowThemeBlendLimits as bO, tileflowThemeTokenCategories as bP, token as bQ, validateTileflowRuntimeSource as bR, validateTileflowThemeBlendSelection as bS, validateTileflowThemeSelection as bT, zoom as bU, type TileflowTypographyStyle as bV, type ResolvedTileflowTypography as bW, normalizeTileflowSurfaceId as bX, type TileflowThemeImageValue as ba, type TileflowThemeNumberValue as bb, type TileflowThemeSelection as bc, type TileflowThemeTokenCategory as bd, type TileflowThemeValue as be, type TileflowViewConfig as bf, type TileflowWaterLabelClass as bg, type TileflowZoomInterpolation as bh, type TileflowZoomValue as bi, type ValidationResult as bj, assertValidTileflowRuntimeSource as bk, clearTileflowManifestCache as bl, color as bm, createTileflowSessionController as bn, createTileflowSessionId as bo, defaultTileflowManifestUrl as bp, defaultTileflowRuntimeView as bq, fixed as br, getTileflowAnalyticsApiUrl as bs, getTileflowStyleFontFaces as bt, inferTileflowAnalyticsFromStyleUrl as bu, loadTileflowManifest as bv, mergeTileflowAnalytics as bw, nearestTileflowBlendTheme as bx, normalizeTileflowRuntimeCenter as by, normalizeTileflowStaticImageSize as bz, type TileflowRuntimeManifestTheme as c, type TileflowRuntimeSystemThemes as d, tileflowRuntimeManifestVersion as e, type TileflowExpression as f, type TileflowFixedValue as g, type TileflowThemeTokenReference as h, type TileflowThemeColorOperation as i, type TileflowBackgroundStyle as j, type TileflowCircleStyle as k, type TileflowExtrusionStyle as l, type TileflowFillStyle as m, type TileflowLineStyle as n, type TileflowSymbolStyle as o, type TileflowRoadsModuleOptions as p, type TileflowRoadsModuleConfig as q, type TileflowLabelsModuleOptions as r, type TileflowLabelsModuleConfig as s, tileflowRuntimeManifestLimits as t, type TileflowPoiModuleOptions as u, type TileflowPoiModuleConfig as v, type MapLibreSprite as w, type TileflowAerodromeCodeDetail as x, type TileflowAlignment as y, type TileflowAnalytics as z };
+export { type TileflowManifestFetchOptions as $, type TileflowAreaStyle as A, type TileflowBackgroundPaint as B, type TileflowCirclePaint as C, type TileflowColor as D, type TileflowColorStyleValue as E, type TileflowExtrusionPaint as F, type TileflowFillPaint as G, type TileflowIconAnchor as H, type TileflowIconLayout as I, type TileflowIconPaint as J, type TileflowIconStyle as K, type TileflowIconTextFit as L, type MapLibreStyle as M, type TileflowImageStyleValue as N, type TileflowLabelDetail as O, type TileflowLabelLanguage as P, type TileflowLabelStyles as Q, type TileflowLayerRange as R, type TileflowLight as S, type TileflowRuntimeManifest as T, type TileflowLineCap as U, type ValidationMessage as V, type TileflowLineHatchStyle as W, type TileflowLineJoin as X, type TileflowLineLayout as Y, type TileflowLinePaint as Z, type TileflowLineStackStyle as _, type TileflowRuntimeColorScheme as a, type TileflowTerrainMode as a$, type TileflowManifestLoadOptions as a0, type TileflowMapMode as a1, type TileflowMapModeOptions as a2, type TileflowMarkerSymbolStyle as a3, type TileflowMountainBikeScale as a4, type TileflowNumberInsetsStyleValue as a5, type TileflowNumberStyleValue as a6, type TileflowPlaceLabelClass as a7, type TileflowPoiCategory as a8, type TileflowPoiCategoryStyle as a9, type TileflowRoadTreatmentStyle as aA, type TileflowRoadWeight as aB, type TileflowRuntimeCenterLike as aC, type TileflowRuntimeManifestMap as aD, type TileflowRuntimeSource as aE, type TileflowRuntimeSourceValidation as aF, type TileflowRuntimeStyle as aG, type TileflowRuntimeStyleOptions as aH, type TileflowRuntimeViewOptions as aI, type TileflowSessionController as aJ, type TileflowSessionGrantResponse as aK, type TileflowStringStyleValue as aL, type TileflowStructuralStyleValue as aM, type TileflowStyleFontFace as aN, type TileflowStyleValue as aO, type TileflowSymbolOverlap as aP, type TileflowSymbolPlacement as aQ, type TileflowSymbolPlacementStyle as aR, type TileflowSymbolZOrder as aS, type TileflowTerrain as aT, type TileflowTerrainConfig as aU, type TileflowTerrainContourLabelStyle as aV, type TileflowTerrainContourLineStyle as aW, type TileflowTerrainContoursConfig as aX, type TileflowTerrainEncoding as aY, type TileflowTerrainHillshadeStyle as aZ, type TileflowTerrainLayerRange as a_, type TileflowPoiColorMode as aa, type TileflowPoiDensity as ab, type TileflowPriorityOrder as ac, type TileflowProjection as ad, type TileflowResolvedRuntimeTheme as ae, type TileflowRoadAreaStyle as af, type TileflowRoadClass as ag, type TileflowRoadClassStyle as ah, type TileflowRoadCrossingStyle as ai, type TileflowRoadDetail as aj, type TileflowRoadExtras as ak, type TileflowRoadHierarchy as al, type TileflowRoadLabelDetail as am, type TileflowRoadLayerStyle as an, type TileflowRoadModifier as ao, type TileflowRoadOutline as ap, type TileflowRoadRestriction as aq, type TileflowRoadRoundaboutStyle as ar, type TileflowRoadServiceType as as, type TileflowRoadShieldDetail as at, type TileflowRoadShieldStyles as au, type TileflowRoadSidewalkStyle as av, type TileflowRoadStreetLightStyle as aw, type TileflowRoadStructure as ax, type TileflowRoadTreatmentLayerStyle as ay, type TileflowRoadTreatmentLineStyle as az, type TileflowRuntimeManifestMapEntry as b, type TileflowTextAnchor as b0, type TileflowTextBackground as b1, type TileflowTextJustify as b2, type TileflowTextLayout as b3, type TileflowTextPaint as b4, type TileflowTextStyle as b5, type TileflowThemeBlendSelection as b6, type TileflowThemeColorAlpha as b7, type TileflowThemeColorMix as b8, type TileflowThemeColorValue as b9, normalizeTileflowStaticImageSize as bA, normalizeTileflowUrl as bB, resolveTileflowAnalyticsRequestUrl as bC, resolveTileflowManifestMap as bD, resolveTileflowMapMode as bE, resolveTileflowRuntimeStyle as bF, resolveTileflowRuntimeTheme as bG, resolveTileflowRuntimeThemeBlend as bH, resolveTileflowRuntimeView as bI, resolveTileflowStaticImageUrl as bJ, shouldLoadTileflowManifest as bK, startTileflowSession as bL, tileflowPoiCategories as bM, tileflowStyleFontFaceLimits as bN, tileflowStyleFontFacesMetadataKey as bO, tileflowThemeBlendLimits as bP, tileflowThemeTokenCategories as bQ, token as bR, validateTileflowRuntimeSource as bS, validateTileflowThemeBlendSelection as bT, validateTileflowThemeSelection as bU, zoom as bV, type TileflowTypographyStyle as bW, type ResolvedTileflowTypography as bX, normalizeTileflowSurfaceId as bY, type TileflowThemeFontValue as ba, type TileflowThemeImageValue as bb, type TileflowThemeNumberValue as bc, type TileflowThemeSelection as bd, type TileflowThemeTokenCategory as be, type TileflowThemeValue as bf, type TileflowViewConfig as bg, type TileflowWaterLabelClass as bh, type TileflowZoomInterpolation as bi, type TileflowZoomValue as bj, type ValidationResult as bk, assertValidTileflowRuntimeSource as bl, clearTileflowManifestCache as bm, color as bn, createTileflowSessionController as bo, createTileflowSessionId as bp, defaultTileflowManifestUrl as bq, defaultTileflowRuntimeView as br, fixed as bs, getTileflowAnalyticsApiUrl as bt, getTileflowStyleFontFaces as bu, inferTileflowAnalyticsFromStyleUrl as bv, loadTileflowManifest as bw, mergeTileflowAnalytics as bx, nearestTileflowBlendTheme as by, normalizeTileflowRuntimeCenter as bz, type TileflowRuntimeManifestTheme as c, type TileflowRuntimeSystemThemes as d, tileflowRuntimeManifestVersion as e, type TileflowExpression as f, type TileflowFixedValue as g, type TileflowThemeTokenReference as h, type TileflowThemeColorOperation as i, type TileflowBackgroundStyle as j, type TileflowCircleStyle as k, type TileflowExtrusionStyle as l, type TileflowFillStyle as m, type TileflowLineStyle as n, type TileflowSymbolStyle as o, type TileflowRoadsModuleOptions as p, type TileflowRoadsModuleConfig as q, type TileflowLabelsModuleOptions as r, type TileflowLabelsModuleConfig as s, tileflowRuntimeManifestLimits as t, type TileflowPoiModuleOptions as u, type TileflowPoiModuleConfig as v, type MapLibreSprite as w, type TileflowAerodromeCodeDetail as x, type TileflowAlignment as y, type TileflowAnalytics as z };

package/dist/manifest.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { T as TileflowRuntimeManifest } from './manifest-types-E7m23eXL.js';
-export { a as TileflowRuntimeColorScheme, b as TileflowRuntimeManifestMapEntry, c as TileflowRuntimeManifestTheme, d as TileflowRuntimeSystemThemes, t as tileflowRuntimeManifestLimits, e as tileflowRuntimeManifestVersion } from './manifest-types-E7m23eXL.js';
+import { T as TileflowRuntimeManifest } from './manifest-types-hmzy2bBX.js';
+export { a as TileflowRuntimeColorScheme, b as TileflowRuntimeManifestMapEntry, c as TileflowRuntimeManifestTheme, d as TileflowRuntimeSystemThemes, t as tileflowRuntimeManifestLimits, e as tileflowRuntimeManifestVersion } from './manifest-types-hmzy2bBX.js';
 
 declare const tileflowRuntimeManifestSchema: z.ZodType<TileflowRuntimeManifest>;
 declare function parseTileflowRuntimeManifest(input: unknown): TileflowRuntimeManifest;

package/dist/runtime.d.ts

@@ -1 +1 @@
-export { z as TileflowAnalytics, $ as TileflowManifestFetchOptions, a0 as TileflowManifestLoadOptions, a1 as TileflowMapMode, a2 as TileflowMapModeOptions, ae as TileflowResolvedRuntimeTheme, aB as TileflowRuntimeCenterLike, a as TileflowRuntimeColorScheme, T as TileflowRuntimeManifest, aC as TileflowRuntimeManifestMap, b as TileflowRuntimeManifestMapEntry, c as TileflowRuntimeManifestTheme, aD as TileflowRuntimeSource, aE as TileflowRuntimeSourceValidation, aF as TileflowRuntimeStyle, aG as TileflowRuntimeStyleOptions, d as TileflowRuntimeSystemThemes, aH as TileflowRuntimeViewOptions, aI as TileflowSessionController, aJ as TileflowSessionGrantResponse, aM as TileflowStyleFontFace, b5 as TileflowThemeBlendSelection, bc as TileflowThemeSelection, bk as assertValidTileflowRuntimeSource, bl as clearTileflowManifestCache, bn as createTileflowSessionController, bo as createTileflowSessionId, bp as defaultTileflowManifestUrl, bq as defaultTileflowRuntimeView, bs as getTileflowAnalyticsApiUrl, bt as getTileflowStyleFontFaces, bu as inferTileflowAnalyticsFromStyleUrl, bv as loadTileflowManifest, bw as mergeTileflowAnalytics, bx as nearestTileflowBlendTheme, by as normalizeTileflowRuntimeCenter, bz as normalizeTileflowStaticImageSize, bX as normalizeTileflowSurfaceId, bA as normalizeTileflowUrl, bB as resolveTileflowAnalyticsRequestUrl, bC as resolveTileflowManifestMap, bD as resolveTileflowMapMode, bE as resolveTileflowRuntimeStyle, bF as resolveTileflowRuntimeTheme, bG as resolveTileflowRuntimeThemeBlend, bH as resolveTileflowRuntimeView, bI as resolveTileflowStaticImageUrl, bJ as shouldLoadTileflowManifest, bK as startTileflowSession, bM as tileflowStyleFontFaceLimits, bN as tileflowStyleFontFacesMetadataKey, bO as tileflowThemeBlendLimits, bR as validateTileflowRuntimeSource, bS as validateTileflowThemeBlendSelection, bT as validateTileflowThemeSelection } from './manifest-types-E7m23eXL.js';
+export { z as TileflowAnalytics, $ as TileflowManifestFetchOptions, a0 as TileflowManifestLoadOptions, a1 as TileflowMapMode, a2 as TileflowMapModeOptions, ae as TileflowResolvedRuntimeTheme, aC as TileflowRuntimeCenterLike, a as TileflowRuntimeColorScheme, T as TileflowRuntimeManifest, aD as TileflowRuntimeManifestMap, b as TileflowRuntimeManifestMapEntry, c as TileflowRuntimeManifestTheme, aE as TileflowRuntimeSource, aF as TileflowRuntimeSourceValidation, aG as TileflowRuntimeStyle, aH as TileflowRuntimeStyleOptions, d as TileflowRuntimeSystemThemes, aI as TileflowRuntimeViewOptions, aJ as TileflowSessionController, aK as TileflowSessionGrantResponse, aN as TileflowStyleFontFace, b6 as TileflowThemeBlendSelection, bd as TileflowThemeSelection, bl as assertValidTileflowRuntimeSource, bm as clearTileflowManifestCache, bo as createTileflowSessionController, bp as createTileflowSessionId, bq as defaultTileflowManifestUrl, br as defaultTileflowRuntimeView, bt as getTileflowAnalyticsApiUrl, bu as getTileflowStyleFontFaces, bv as inferTileflowAnalyticsFromStyleUrl, bw as loadTileflowManifest, bx as mergeTileflowAnalytics, by as nearestTileflowBlendTheme, bz as normalizeTileflowRuntimeCenter, bA as normalizeTileflowStaticImageSize, bY as normalizeTileflowSurfaceId, bB as normalizeTileflowUrl, bC as resolveTileflowAnalyticsRequestUrl, bD as resolveTileflowManifestMap, bE as resolveTileflowMapMode, bF as resolveTileflowRuntimeStyle, bG as resolveTileflowRuntimeTheme, bH as resolveTileflowRuntimeThemeBlend, bI as resolveTileflowRuntimeView, bJ as resolveTileflowStaticImageUrl, bK as shouldLoadTileflowManifest, bL as startTileflowSession, bN as tileflowStyleFontFaceLimits, bO as tileflowStyleFontFacesMetadataKey, bP as tileflowThemeBlendLimits, bS as validateTileflowRuntimeSource, bT as validateTileflowThemeBlendSelection, bU as validateTileflowThemeSelection } from './manifest-types-hmzy2bBX.js';

package/docs/application-tile-reading.md

@@ -74,6 +74,9 @@ state on the map.
 - **Requests.** `transformRequest` rewrites each request as a MapLibre map's option does. Pass the
   map's own so tile reads follow the same rules. The browser's HTTP cache applies as for any
   request.
+- **Archives.** A source served from a Tileflow PMTiles archive (a `tileflow-pmtiles://` address)
+  is read through Core's PMTiles protocol, sharing the archives the page's map has opened. A
+  `fetch` of your own replaces both.
 
 The reader has no DOM dependency, so it also runs in a module worker: post the tile address and
 zooms to the worker and create the reader there. `decodeTileflowVectorTile(bytes, {layers})`

package/docs/authoring-model.md

@@ -89,7 +89,8 @@ TypeScript imports.
 
 `icons` is an intentional exception to implicit array composition: omission inherits the exact
 parent array, any declaration replaces it atomically, and `[]` disables map icons. Compose with a
-spread when the child should keep a parent's directories. `fonts` and `glyphs` are mutually
+spread when the child should keep a parent's directories. `models`, the directories of a map's own
+3D models, follows the same rule. `fonts` and `glyphs` are mutually
 exclusive text providers; declaring either atomically replaces an inherited provider of either
 kind. Unknown keys and former compatibility shapes are rejected.
 

package/docs/buildings-3d.md

@@ -42,7 +42,59 @@ The renderer reads the source's z15 tiles round the camera (z15 is where World's
 their heights; a source that stops earlier is read at its own maximum zoom), up to `maxTiles`
 tiles (25 by default), and meshes them a few milliseconds per frame. It reads World's
 `render_height`, `render_min_height`, `hide_3d`, `building_tone` and `night_use`, and the places in
-World's `poi` layer (see [night light](#night-light)).
+World's `poi` layer (see [night light](#night-light)). `stats.declared` tells whether the map's
+style describes its 3D buildings; a style compiled before this description gets the defaults below.
+
+## Design the buildings in the map
+
+The map describes how its 3D buildings look, in its buildings module, and publishes it with its
+style for every theme; the renderer follows theme changes and blends. The design is visible in
+`tileflow preview` and validated with the rest of the map:
+
+<!-- docs:check -->
+
+```ts
+import {defineMap, expr, field, refine, refineRenderTarget} from '@tileflow/core';
+import {streets} from '@tileflow/maps';
+
+const floors = expr.divide(expr.toNumber(expr.get(field('renderHeight')), 0), 3.2);
+
+export default defineMap({
+  id: 'lit-city',
+  name: 'Lit city',
+  version: 1,
+  extends: streets,
+  modules: {
+    buildings: refine({
+      threeDimensional: {windows: true, nightLight: 0.6, edgeColor: '#2b2a33'},
+      renderStack: {
+        // Core's 3D buildings take the colour of the map's 3D building pass.
+        tints: refineRenderTarget({
+          target: 'buildings.render.extrusion',
+          renderer: 'extrusion',
+          style: {
+            color: expr.step(expr.modulo(floors, 3), '#e8d9c4', [
+              [1, '#d6e2d8'],
+              [2, '#e5d4e6'],
+            ]),
+          },
+        }),
+      },
+    }),
+  },
+});
+```
+
+- Colour: each building takes the colour the map gives its 3D buildings: Streets' 3D building pass
+  (the theme's `buildings.extrusion`), else the buildings module's extrusion, else its roofs. A
+  colour that depends on the building's data is evaluated per building and theme when a tile or the
+  set of themes changes, and the themes either side of a blend's position mix on the GPU, so a
+  moving blend costs nothing per frame.
+- `threeDimensional.shadows` and `occlusion` (the band at the foot of the walls and the darker tight
+  corners) default to true. `windows: true` adds invented night windows, lit by rooms; they are
+  decoration, not data, and are off by default.
+- `threeDimensional.edges` and `edgeColor` set the [edges](#edges), and `nightLight` the
+  [night light](#night-light). Numbers and colours may be theme tokens.
 
 ## Light and shadows
 
@@ -59,11 +111,9 @@ any wall, so roofs and walls read apart under the moon.
 MapLibre's own layers take no shadows, so the renderer darkens the map it is drawn over: after its
 buildings, it multiplies the ground by the shadows and by a band at the foot of the walls. Labels
 and icons drawn above it keep their colours. Layers kept under 3D content with
-`createTileflowGroundLayers` are darkened with the ground.
-
-`shadows` and `occlusion` (the band at the foot of the walls and the darker tight corners) default
-to true and can be turned off. `windows: true` adds invented night windows, lit by rooms; they are
-decoration, not data, and are off by default.
+`createTileflowGroundLayers` are darkened with the ground. Other Core 3D layers on the map, such as
+[3D trees](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/trees-3d.md), share
+the buildings' shadows.
 
 ## Edges
 
@@ -73,30 +123,9 @@ each building is a little lighter or darker than its colour (up to 6%), so neigh
 stay apart. The lines are strongest at night; diagonals inside a roof, inner corners and the cuts at
 a tile's edge draw none. `edges` sets their strength from 0 (none) to 1, the default.
 
-`edgeColor` gives the lines a colour of the application's own, as a CSS colour or per theme: a dark
-outline as on a printed map, or a neon one at night. It is 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.
-
-<!-- docs:check -->
-
-```ts
-import {
-  createTileflowBuildings3D,
-  type TileflowBuildings3DMap,
-  type TileflowThemeController,
-} from '@tileflow/core/browser';
-
-export function neonEdges(map: TileflowBuildings3DMap, controller: TileflowThemeController) {
-  return createTileflowBuildings3D({
-    map,
-    controller,
-    // Cyan outlines at night, a dark ink by day.
-    edgeColor: (theme) => (theme === 'night' ? '#7fd8ff' : '#2b2a33'),
-  });
-}
-```
+`edgeColor` gives the lines a colour of the map's own, per theme through a token: a dark outline as
+on a printed map, or a neon one at night. It is drawn as it is, unlit, at the full `edges` strength
+by day and night, mixed between the themes either side of a blend's position.
 
 ## Night light
 
@@ -112,8 +141,8 @@ default:
   dark.
 
 The night use comes from World's `night_use` on each building. In tiles whose buildings do not
-carry it, the renderer finds it in the tile's places (`placesLayer`, `poi` by default): a place
-inside a building, or within a few metres of its facade, gives the building its use.
+carry it, the renderer finds it in the tile's places: a place inside a building, or within a few
+metres of its facade, gives the building its use.
 
 `nightLight` sets how bright all of this shines, from 0 (none) to 2; it defaults to 1.
 
@@ -122,37 +151,11 @@ For the streets themselves, see
 which draws over the buildings so they hide the lamps behind them; both layers share each tile's
 download.
 
-## Colours
+## Options
 
-Without `color`, buildings take the theme's 3D building colour, the colour Tileflow's buildings
-module compiles for its extrusion, and follow theme changes and blends.
-
-`color(properties, theme)` colours each building from its feature properties for each theme, as a
-CSS colour. The renderer calls it once per building and theme when a tile or the set of themes
-changes, and mixes the colours of the themes either side of a blend's position on the GPU, so a
-moving blend costs nothing per frame:
-
-<!-- docs:check -->
-
-```ts
-import {createTileflowBuildings3D, type TileflowBuildings3DMap} from '@tileflow/core/browser';
-
-const tints: Record<string, readonly string[]> = {
-  day: ['#f1d4cd', '#d3e8da', '#f6e0b5', '#e2d5f0', '#cfe3f2'],
-  night: ['#353d41', '#2f3a3d', '#3a3b44', '#33363f', '#2d3540'],
-};
-
-export function tintedCity(map: TileflowBuildings3DMap) {
-  return createTileflowBuildings3D({
-    map,
-    color(properties, theme) {
-      const floors = Math.floor(Number(properties.render_height ?? 5) / 3.2);
-      const palette = tints[theme] ?? tints.day!;
-      return palette[floors % palette.length]!;
-    },
-  });
-}
-```
+The renderer's own options say only how it is delivered: `minzoom` (14.5 by default), `maxTiles`,
+`beforeId` to place the layer before another one, and `transformRequest` to apply the map's request
+rules to the tiles it reads.
 
 ## Cost
 
@@ -166,3 +169,4 @@ way kept the frame pacing of the same city drawn without shadows.
 - No terrain: buildings stand on flat ground.
 - One building colour per feature and theme; facades, roof shapes and building parts as separate
   shapes are not drawn.
+- A colour expression is evaluated at zoom 16.

package/docs/street-lights.md

@@ -45,13 +45,37 @@ detail:
 - Lamps from World's `street_furniture` points whose `subclass` is `street_lamp`. Where the data
   gives them, a lamp's `height`, `lamp_mount`, `light_count`, `lamp_type` and `light_colour` set how
   high it stands, how far its light reaches and its colour: sodium lamps shine orange, LED and
-  metal-halide lamps white. Other lamps take `color`, a warm white by default.
+  metal-halide lamps white. Other lamps take the map's light colour.
 - Streets in World's `transportation` layer, and pavements in its `sidewalk` layer, that the data
   maps as lit (`lit`). A street mapped as unlit never takes light.
 
 How much of this a city's data holds varies widely: some map most of their lamps or most of their
 lit streets, others almost none. Where the data says nothing, the streets stay dark.
 
+## Design the lights in the map
+
+The map describes its street lights in its roads module, next to the other details drawn from
+street furniture, and publishes them with its style for every theme; `stats.declared` tells whether
+it does. Without a description the lights take the defaults below:
+
+<!-- docs:check -->
+
+```ts
+import {defineMap, refine} from '@tileflow/core';
+import {streets} from '@tileflow/maps';
+
+export default defineMap({
+  id: 'night-city',
+  name: 'Night city',
+  version: 1,
+  extends: streets,
+  modules: {
+    // Sodium-orange light, a little brighter, on every street of tiles that map few lamps.
+    roads: refine({streetLights: {color: '#ffb35c', intensity: 1.3, estimate: 'streets'}}),
+  },
+});
+```
+
 `estimate` chooses where the layer adds light the data does not map as lamps:
 
 - `lit` (the default): along the streets and pavements mapped as lit.
@@ -63,12 +87,15 @@ lit streets, others almost none. Where the data says nothing, the streets stay d
 Estimated light keeps to the middle of its street and shows no lamp head, so it reads as a lit
 street rather than as lamps that may not stand there.
 
+`color` is the light of the lamps whose data gives no colour, a warm white by default, and
+`intensity` scales the light from 0 to 2 (1 by default); both may be theme tokens and mix during a
+blend. `streetLights: {enabled: false}` gives the map none.
+
 ## Options
 
-`intensity` scales the light from 0 to 2 (1 by default). `minzoom` (14 by default) and `maxTiles`
-(25 by default, at most 64) bound where and how far the lights shine. `beforeId` places the layer
-before another one; `source` names a vector source other than `tileflow`; `transformRequest`
-applies the map's request rules to the tiles the layer reads.
+The layer's own options say only how it is delivered: `minzoom` (14 by default) and `maxTiles` (25
+by default, at most 64) bound where and how far the lights shine, `beforeId` places the layer before
+another one, and `transformRequest` applies the map's request rules to the tiles it reads.
 
 Layers that read the same source share each tile's download, so the street lights and the 3D
 buildings fetch a tile once between them.

package/docs/trees-3d.md

@@ -0,0 +1,211 @@
+# 3D trees
+
+`createTileflowTrees3D` stands the trees of a Tileflow map's vector tiles round the camera as 3D
+trees, lit by the theme controller's sun. Each tree takes the form and the size its data gives:
+palms, conifers, columns and three broadleaf forms, at their mapped height and crown where the data
+has them. Trees cast shadows on the ground and, with `createTileflowBuildings3D`, on the buildings,
+and take the buildings' shadows; nearer buildings hide them.
+
+The map describes how its trees look; the renderer only stands them. A map that declares
+`vegetation({mode: '3d'})`, as Streets does, publishes its tree colours, scales and forms in the
+style it compiles, for every theme, and the renderer follows theme changes and blends.
+
+It is a custom WebGL2 layer for MapLibre GL JS, drawn above the map's buildings and below its
+labels. It needs WebGL2 and the Mercator projection, and the trees stand from zoom 15 by default.
+Elsewhere (Capture, Static Maps, Native, or a browser without WebGL2) the map draws the vegetation
+module's flat trees.
+
+## Stand the trees
+
+This example assumes an existing MapLibre map showing a Tileflow map whose vector source is called
+`tileflow`, as Tileflow's maps call World, and a theme controller for it:
+
+<!-- docs:check -->
+
+```ts
+import {
+  createTileflowTrees3D,
+  type TileflowThemeController,
+  type TileflowTrees3DMap,
+} from '@tileflow/core/browser';
+
+export function standTheTrees(map: TileflowTrees3DMap, controller: TileflowThemeController) {
+  const trees = createTileflowTrees3D({map, controller});
+  // The trees grow out of the ground over a second.
+  void trees.show({transition: {duration: 1000}});
+  return trees;
+}
+```
+
+`show()` grows the trees, `hide()` sinks them back into the ground, and `grow(scale)` eases them to
+a share of their size, from 0 to 1. Each returns a promise that resolves once the motion ends; a
+newer call takes over from where the trees stand. A browser preference for reduced motion changes at
+once. `dispose()` takes the layer off the map.
+
+While they stand, the 3D trees stand in for the map's flat trees: the layers the vegetation module
+draws them with are hidden when the trees are shown, and come back as they were once the trees have
+sunk or the layer leaves the map.
+
+`stats.declared` tells whether the map's style describes 3D trees. When it is false the layer draws
+nothing: declare `vegetation({mode: '3d'})` in the map. `stats` also counts the tiles, the trees
+placed and the trees drawn in the last frame.
+
+## What the trees come from
+
+The renderer reads the source's z15 tiles round the camera:
+
+- World's `tree` layer: the trees OpenStreetMap maps one by one, as points, and its rows of trees,
+  as lines, along which a tree stands every 8 metres. A tree's `leaf_type`, `genus`, `species` and
+  `taxon` choose its form; its `height` and `diameter_crown` its size, and a trunk's
+  `circumference` sizes a tree with neither. A row's attributes apply to each of its trees.
+- World's `canopy` layer, where the data has it: decorative points in urban parks and gardens, each
+  standing one to three trees by its canopy cover, inside the room it leaves before a path, a
+  building or the park's edge. They stand for measured canopy, not for mapped trees.
+
+| Form       | From the data                                                                |
+| ---------- | ---------------------------------------------------------------------------- |
+| `palm`     | `leaf_type` `palm`, `taxon` `Arecaceae`, or a palm genus such as `Roystonea` |
+| `columnar` | the cypress genera `Cupressus`, `Calocedrus` and `Thuja`                     |
+| `conifer`  | `leaf_type` `needleleaved`, or a conifer genus such as `Pinus` or `Cedrus`   |
+| `open`     | spreading genera such as `Quercus`, `Olea`, `Ficus` or `Jacaranda`           |
+| `tall`     | upright genera such as `Platanus`, `Populus`, `Ulmus` or `Ginkgo`            |
+| `round`    | rounded genera such as `Acer`, `Tilia`, `Aesculus` or `Prunus`               |
+
+A tree whose data gives no form, and every canopy tree, takes one of the three broadleaf forms; a
+tree the data calls broadleaved keeps to them. Each tree's form, size, turn and shade come from a
+stable hash of where it stands, so it looks the same at every zoom and on every device. Points in a
+tile's buffer belong to the neighbouring tile, so no tree stands twice.
+
+## Design the trees in the map
+
+Colours come from the theme: `vegetation.tree.bark`, `vegetation.tree.broadleaf.a` to `.d`,
+`vegetation.tree.conifer.a` to `.c` and `vegetation.tree.palm.a` to `.c`, sunlit, from darkest to
+lightest. A crown facing a sunlit sky takes its colour; shade takes the sky's light, as on 3D
+buildings. The vegetation module's `threeDimensional` options refine them for one map:
+
+<!-- docs:check -->
+
+```ts
+import {defineMap, token, vegetation} from '@tileflow/core';
+import {streets} from '@tileflow/maps';
+
+export default defineMap({
+  id: 'subtropical-city',
+  name: 'Subtropical city',
+  version: 1,
+  extends: streets,
+  modules: {
+    vegetation: vegetation({
+      mode: '3d',
+      threeDimensional: {
+        barkColor: token.color('vegetation.tree.bark'),
+        heightScale: 1.1,
+        finish: 'toon',
+        edges: 1,
+        // Along this coast most trees the data does not describe are palms.
+        regions: [{bounds: [-81.0, 24.4, -79.8, 26.9], unknownForms: {palm: 3, round: 1, open: 1}}],
+      },
+    }),
+  },
+});
+```
+
+`finish` sets 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. `edges` rings each tree with an outline a constant width on screen, from 0 (none,
+the default) to 1, in `edgeColor` or the crown's darkest colour deepened; buildings use the same
+two words for their outlines.
+
+`heightScale` and `crownScale` stretch every tree, and `forms` each form on top of them, such as
+`forms: {palm: {heightScale: 1.2}}` for taller palms. `unknownForms` sets, as relative weights, the
+forms of trees whose data gives none, and `regions` sets them inside `[west, south, east, north]`
+bounds in degrees, the first region holding a tree applying. They are a choice of look, not data:
+they never change a tree whose data gives its form, and as mapping improves they apply to fewer
+trees.
+
+## Your own trees
+
+A map can draw a form with its own models. Put glTF binaries (`.glb`) in a directory, declare it in
+the map's `models`, and name the models a form draws by their file names:
+
+<!-- docs:check -->
+
+```ts
+import {defineMap, vegetation} from '@tileflow/core';
+import {streets} from '@tileflow/maps';
+
+export default defineMap({
+  id: 'palm-coast',
+  name: 'Palm coast',
+  version: 1,
+  extends: streets,
+  // ./models holds sabal-palm.glb and royal-palm.glb, and sabal-palm.far.glb for far trees.
+  models: ['./models'],
+  modules: {
+    vegetation: vegetation({
+      mode: '3d',
+      threeDimensional: {
+        forms: {palm: {models: ['sabal-palm', 'royal-palm'], heightScale: 1.1}},
+      },
+    }),
+  },
+});
+```
+
+Each tree of the form draws one of its models, one to four, by its stable hash, so a palm keeps its
+model wherever it is read. The data still chooses each tree's form and size: a model replaces how a
+form looks, not which trees take it.
+
+How to prepare a model:
+
+- **Materials name the parts.** Name each material `bark`, `leaves`, `fronds` or `stem` (an
+  exporter's `.001` suffix is ignored). Each part takes its theme colours, as Core's trees do; the
+  material's colour and any vertex colours set how light or dark each part of the model is within
+  them, so the model follows the theme from day to night.
+- **The origin is where the trunk meets the ground**, with the tree above it. Tileflow stands the
+  model as a unit tree: its top is the tree's height, and its widest leaf half its crown.
+- **Budgets.** A model has at most 1,000 triangles and 4,096 vertices; `<id>.far.glb`, drawn
+  beyond the nearest tiles, at most 120 triangles. Without a far model, the form's own far tree
+  stands in. A map draws at most 16 models.
+- **What is read.** Triangles of the default scene with their node transforms; textures,
+  animations and compressed geometry (Draco or meshopt) are not. Export without compression.
+
+`tileflow preview` and every build read the models, report a problem with the file and what to
+change, and watch the directories. The models travel inside the compiled style, so they need no
+files of their own when the map is deployed. A later directory's model replaces an earlier one of
+the same name; omitting `models` inherits them, and `[]` declares none.
+
+## Light and shadows
+
+The light comes from `controller.getSun()`: the theme's sun, mixed during a blend, or the sun an
+application places by direction or by date and place (see
+[sun and light](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/sun-and-light.md)).
+Leaves take light round their edges and glow a little against a low sun; the underside and the
+inside of a crown stay darker.
+
+Trees and 3D buildings on one map share one shadow map: trees cast shadows on the ground and on the
+buildings, and stand in the buildings' shade. The flat map darkens under both. Without 3D buildings
+the trees darken the map themselves.
+
+## Options
+
+`minzoom` (15 by default) and `maxTiles` (25 by default, at most 64) bound where and how far trees
+stand; trees thin out and fade with distance from the map's centre, and near trees take more detail
+than far ones. `canopySource` names a vector source with canopy points when they are not in the
+map's World source. `beforeId` places the layer before another one; `transformRequest` applies the
+map's request rules to the tiles the layer reads. Layers that read the same source share each
+tile's download.
+
+## Cost
+
+A near tree has 60 to 120 triangles and a far one about 20, and each form is one instanced draw per
+tile. The shadow map is drawn again only when the sun, the trees on screen or their size change, not
+when the camera moves. Over the Champ de Mars in Paris, where OpenStreetMap maps every tree, about
+13,000 trees stand in a pitched view at zoom 16.6.
+
+## Limits
+
+- Mercator only; the layer draws nothing below its `minzoom`.
+- No terrain: trees stand on flat ground.
+- No wind or seasons; one form per tree.
+- Models replace a form's look; a model per genus or species is not available.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/core",
-  "version": "0.1.0-alpha.33",
+  "version": "0.1.0-alpha.34",
   "license": "Apache-2.0",
   "description": "Typed Tileflow config and MapLibre style compiler.",
   "type": "module",