@tileflow/core 0.1.0-alpha.41 → 0.1.0-alpha.43

package/docs/buildings-3d.md

@@ -1,608 +0,0 @@
-# 3D buildings
-
-`createTileflowBuildings3D` raises the buildings of a Tileflow map's vector tiles round the camera.
-By default it preserves the map's building colours, uses the scene sun, casts shadows, adds soft
-contact shading and rounds exterior corners by 0.8 metres. An unspecified sun uses soft daylight
-with directional intensity 0.2 and ambient intensity 0.8; authored theme lighting stays in control.
-Showing, hiding and changing height are immediate. Illuminated outlines, random colour variation,
-invented windows and night lights remain off. Every effect is independently overridable and
-independent of the map's trees.
-
-Streets supplies architectural flood lighting and subtle model wall emission for its dark
-presets. These controls are independent of invented windows and the optional `nightLight` effects.
-
-Tileflow landmarks and a map's own building models can stand in the same 3D scene, replacing
-the buildings under their footprints.
-
-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, which MapLibre's globe turns into from about
-zoom 12. On every map the city comes in as the camera zooms in: placed models and landmarks first,
-fading in and rising from the ground between zooms 14.2 and 14.6, then the buildings between 15 and
-15.3. Their shadows and contact shading follow their height. Zooming back out lowers and fades them
-again. With reduced motion (`prefers-reduced-motion`) they keep their height and only fade.
-`hide()` keeps them hidden at every zoom until `show()` is called.
-
-A map sets these bands with the buildings module's `threeDimensional.entrance`, each a
-`[from, to]` pair of zooms; a band left out keeps its default:
-
-```ts
-buildings({threeDimensional: {entrance: {buildings: [15.5, 16], models: [14.5, 15]}}});
-```
-
-The renderer reads its tiles from a zoom below its `minzoom`, so a band that starts earlier than
-that comes in from there.
-
-## The map's 3D scene
-
-React, Vue and Svelte `Map` components show the 3D scene of every map whose style declares one, by
-default: buildings with Tileflow landmarks and the map's Team building models, 3D trees, and street
-lights where the map enables them. They load the 3D renderers from `@tileflow/core/3d` only when
-the style declares a scene, so a 2D map does not download them. Set `viewMode="2d"` (Vue:
-`view-mode="2d"`) to opt out: no 3D buildings or street lights are mounted, and vegetation follows
-its [display policy](trees-3d.md#visibility-and-representation) for the 2D view. Changing it back to
-`3d` shows the scene on the same map. React Native, image mode, Capture and Static Maps do not draw
-the scene.
-
-Applications that build their own MapLibre map mount the same scene with `createTileflowMap3D`.
-It mounts each renderer the style declares, follows theme and style changes, and releases a
-renderer when the style no longer declares it:
-
-<!-- docs:check -->
-
-```ts
-import {
-  createTileflowMap3D,
-  type TileflowMap3DMap,
-  type TileflowThemeController,
-} from '@tileflow/core/browser';
-
-export function showTheScene(map: TileflowMap3DMap, controller: TileflowThemeController) {
-  const scene = createTileflowMap3D({map, controller});
-  // Shown on creation; hide() and show() switch the whole scene, dispose() removes it.
-  return scene;
-}
-```
-
-`hide()` takes the buildings down and releases the street lights; `show()` brings them back. Both
-take the same transition as the buildings' `show()` and `hide()`. `setVegetation(false)` hides
-every tree and `setVegetation(undefined)` restores the map's default. To load the renderers only
-for maps that need them, call `attachTileflowMap3D({map, controller, load: () =>
-import('@tileflow/core/3d')})` from `@tileflow/core/browser`, as the framework components do; its
-`setViewMode()` and `setVegetation()` apply once the scene mounts.
-
-A MapLibre application that loads a compiled `style.json` directly gets no 3D scene: buildings,
-landmarks, models, trees and lights are custom WebGL layers added only by this runtime. Where a map
-draws a plain `fill-extrusion` building pass, the style ships it hidden and grouped under
-`metadata['tileflow:3d-toggle'] = 'building'`; showing those layers gives extruded footprints only.
-
-## Decorative building surfaces
-
-`threeDimensional.surfaces` adds optional brick joints, roof tiles and a painted cornice to
-ordinary extruded buildings. These are artistic decoration, not surveyed materials. They keep
-the building's authored colour and use its existing lighting, shadows and footprint. Custom GLB
-models and landmarks retain their own materials. Leaving `surfaces` out preserves a smooth finish.
-
-```ts
-buildings({
-  threeDimensional: {
-    surfaces: {
-      walls: {kind: 'brick', size: [6, 3], jointWidth: 0.16, contrast: 0.28},
-      roof: {kind: 'tiles', size: 10, jointWidth: 0.12, contrast: 0.12},
-      cornice: {height: 0.7, contrast: 0.3},
-    },
-  },
-});
-```
-
-Wall `size` is `[width, courseHeight]` in metres. Roof size is a square in projected Mercator
-metres: its ground size shrinks with latitude, while its grid remains fixed through camera moves
-and tile boundaries. Sizes accept 0.5–100; joints accept 0.01–2 and are limited to a quarter of the
-smallest cell dimension. `contrast` accepts 0–1, including theme number tokens; zero hides that
-finish. The defaults are `[6, 3]`, 0.12 and 0.2 for walls, and 8, 0.12 and 0.1 for roofs.
-
-The cornice is a light band with a subtle seam, not an overhanging mesh. Its `height` accepts
-0.05–5 metres, defaults to 0.6 and is limited to one fifth of a wall's height; its contrast defaults
-to 0.2. The roof border uses projected metres and follows exterior and courtyard edges without
-drawing internal triangle edges. The shader filters joints and fades details smaller than a few
-pixels. No texture downloads, extra draw calls or per-brick geometry are required. These finishes
-belong to the WebGL 3D scene; portable 2D styles retain their ordinary building fill.
-
-## Show the buildings
-
-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 {
-  createTileflowBuildings3D,
-  type TileflowBuildings3DMap,
-  type TileflowThemeController,
-} from '@tileflow/core/browser';
-
-export function raiseTheCity(map: TileflowBuildings3DMap, controller: TileflowThemeController) {
-  const buildings = createTileflowBuildings3D({map, controller});
-  // Enabled on creation; hide() and show() override visibility.
-  return buildings;
-}
-```
-
-`show()`, `hide()` and `grow(scale)` change the height immediately by default (duration 0).
-`show({transition: {duration: 800, mode: 'fade'}})` reveals full-height buildings with a
-smooth opacity fade. The default animation mode is `grow`; both modes respect reduced-motion settings.
-To animate, pass `{transition: {duration: 800}}` explicitly; `grow(scale)` accepts a height share
-from 0 to 1. Each returns a promise that resolves once the change ends; a newer call takes over from where the buildings stand. A browser preference for reduced
-motion changes at once. `dispose()` takes the layer off the map.
-
-The renderer reads the source's z15 tiles round the camera (z15 is where World's buildings carry
-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`, `height_source`, `building_tone`, `class`,
-`night_use` and the roof fields (see [roofs](#roofs)), and the places in World's `poi` layer (see
-[night light](#night-light)). `stats.declared` tells whether the map's
-style describes its 3D buildings. Recompile existing maps to pick up the new defaults: previously
-compiled metadata keeps explicit settings, including `false`, `0` and `lighting: 'style'`.
-
-## 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: {
-        lighting: 'sun',
-        shadows: true,
-        occlusion: true,
-        edges: 1,
-        colorVariation: 0.06,
-        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. Set either to false independently. `windows: true` adds invented night windows, lit by rooms; they are
-  decoration, not data, and are off by default. Where World says what a building is used for
-  (`class`), sheds, garages, barns, factories, churches and service buildings get no rows of
-  windows, homes light more of theirs at night, in a warm light, and offices, schools and hospitals
-  fewer, in a cooler one.
-- `threeDimensional.edges` and `edgeColor` set the [edges](#edges), and `nightLight` the
-  [night light](#night-light). Numbers and colours may be theme tokens.
-- `threeDimensional.edgeRadius` rounds convex exterior corners in the mesh and softens the
-  roof/wall lighting transition. It accepts 0–1 metres and defaults to 0.8; use 0 for sharp corners.
-  Courtyard corners and tile cuts stay unchanged. The authored roof shape is preserved; the top
-  edge is softened through lighting, not a geometric roof bevel. Rounding adds a bounded number
-  of vertices at convex corners, with no extra render pass. Changes to this radius rebuild the
-  resident building meshes.
-
-In both `style` and `sun` lighting, the vertical gradient darkens the foot of a facade by ten percent, fading smoothly over
-at most three metres (half the height for low buildings). It is evaluated per fragment, so a tall
-building does not acquire a full-height dark ramp. Disabling the authored extrusion's
-`verticalGradient` disables this shading. Ground contact shadow is controlled by `occlusion`, enabled by default. It extends three metres
-from grounded walls, darkening the ground by at most 16%, with a smooth distance falloff and round
-corners. Every map uses these defaults when it enables `occlusion`. The reach is measured in world
-metres, so its screen width scales continuously with zoom and becomes subtle at distant views.
-Overlaps use the strongest
-shade once, so shared walls, courtyards and tile joins do not accumulate dark bands. Raised building
-parts do not cast contact shade. Facade occlusion darkens the base by at most 14% and fades
-exponentially with a three-metre decay radius: about 5% remains one floor up and 2% two floors up.
-It follows height above ground, so raised parts do not restart the contact gradient at their base.
-The facade gradient, contact and inner-corner shade use the strongest contribution once, avoiding
-an extra dark strip where they overlap. Both lighting modes use the same falloff at every zoom.
-The ground mask uses one byte per drawing-buffer pixel while enabled and is released when disabled
-or the renderer is removed; it resizes with the drawing buffer.
-
-## Landmarks
-
-Maps on Tileflow World show Tileflow's landmarks, such as the Eiffel Tower, as 3D models in place of
-the buildings under them. They come from a landmarks tileset kept apart from the map's data: each of
-its tiles carries the models standing in it, with their levels of detail and footprints, and each
-region's index names its tiles by their hash, with where each landmark stands and its footprint.
-Core reads only indexes in the `tileflow-landmark-region-v2` format; an index that names no
-footprints is not read, and its region shows no landmarks.
-The renderer reads the tileset's TileJSON, then only the indexes of the regions round the camera
-and the landmark tiles near it, from a zoom before the buildings show, so a landmark in Paris costs
-nothing in Madrid. New and improved landmarks reach every map without a new build of the map.
-
-The buildings under a landmark are never raised and then taken away. A tile of buildings is built
-once the indexes round it have arrived, waiting at most a second and a half; while a landmark's
-tile is still on its way, the footprint its index names keeps the buildings under it flat, and the
-landmark fades in when it arrives. A landmark tile that fails, or has not arrived three seconds
-after the buildings round it show, lets those buildings rise until it does. A tileset that cannot be read is tried again
-after five minutes, and the buildings stay drawn meanwhile.
-
-A map switches them off, or names the TileJSON of another landmarks tileset:
-
-<!-- docs:check -->
-
-```ts
-import {defineMap, refine} from '@tileflow/core';
-import {streets} from '@tileflow/maps';
-
-export default defineMap({
-  id: 'no-landmarks',
-  name: 'Streets without landmarks',
-  version: 1,
-  extends: streets,
-  modules: {
-    buildings: refine({threeDimensional: {landmarks: false}}),
-  },
-});
-```
-
-The map's own building models come first: a landmark with the same id as one of them, or whose
-footprint meets one's, is not drawn.
-
-## Building models
-
-A map can place its own 3D models of buildings in the city: a landmark the extruded footprints draw
-badly, or the buildings an application presents. Each model stands where the map says, in the same
-light, shadows and theme as the buildings round it, and the buildings under its footprint are no
-longer raised while it stands. Put glTF binaries (`.glb`) in a directory, declare it in the map's
-`models`, and say where each model stands:
-
-<!-- docs:check -->
-
-```ts
-import {defineMap, fixed, refine} from '@tileflow/core';
-import {streets, streetsModels} from '@tileflow/maps';
-
-export default defineMap({
-  id: 'paris-landmarks',
-  name: 'Paris landmarks',
-  version: 1,
-  extends: streets,
-  // ./models holds eiffel-tower.glb, and eiffel-tower.mid.glb and eiffel-tower.far.glb for
-  // farther views.
-  // Keep Streets' tree models alongside the building models.
-  models: [streetsModels, './models'],
-  modules: {
-    buildings: refine({
-      threeDimensional: {
-        models: [{model: 'eiffel-tower', at: [2.294481, 48.858258], heading: 0}],
-        modelColors: {
-          surface: fixed('#7a5c45', {reason: "The tower's bronze paint"}),
-          accent: fixed('#5b4332', {reason: "The tower's bronze paint, in shadow"}),
-        },
-      },
-    }),
-  },
-});
-```
-
-`at` is the longitude and latitude of the model's origin and `heading` the degrees clockwise from
-north its own north is turned to. A map places up to 256 models; one model may stand in several
-places. A placement may instead name a prepared model file served elsewhere with `url`, its HTTPS
-address; the map then needs no `.glb` of its own for it.
-
-How to prepare a model:
-
-- **Materials name the parts.** Name each material after the part it is: an architectural part,
-  `surface`, `secondary`, `glass`, `accent` or `roof`, or a part of the model's own, such as
-  `water`, `vegetation`, `wood` or `stone`. A name is lower-case words joined by hyphens or
-  underscores, at most 32 characters; an exporter's `.001` suffix is ignored, and a level names at
-  most 16 parts. A model whose materials name only a tree's parts (`bark`, `leaves`, `fronds`,
-  `stem`) is a
-  [tree model](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/trees-3d.md)
-  instead.
-- **The map colours parts by name.** A part takes the colour `modelColors` gives its name, so the
-  model follows the theme from day to night; a part the map does not colour keeps its material's
-  own colour. Like every visual colour, a `modelColors` entry is a theme token such as
-  `token.color('buildings.modelRoof')`, or a literal wrapped in `fixed(value, {reason})`; vertex
-  colours lighter or darker than the rest of their part shade it within that colour. Name pools
-  `water`, planting `vegetation` and timber `wood` where they fit: Streets colours these from its
-  water and tree colours, so a model that uses them follows the map without a colour of its own.
-- **Architectural roles control lighting.** A material may set
-  `extras.tileflow.lightingRole` to `wall`, `door`, `roof`, `window`, `lamp`, `logo` or
-  `unclassified`, whatever part it names. Without a role, `surface`, `secondary` and `accent` are
-  walls, `glass` is a window, and `roof` is a roof; every other part is `unclassified`, so a pool
-  or a planted bed never takes a window's light.
-- **Metres round an origin on the ground.** The origin is where the model stands, with the model
-  above it and its own north along +y once read Z up; nothing may lie more than half a metre below
-  it.
-- **What it stands in for.** A mesh whose material is named `footprint` is never drawn: it lays
-  out on the ground what the model stands in for, such as a landmark's whole base. Without one, the
-  model's own outline on the ground stands in, courtyards included.
-- **Levels of detail.** `<id>.mid.glb` and `<id>.far.glb`, when present, are drawn farther from the
-  camera, measured to the centre of the model's bounds: a model 30 m or taller from 2 km and 5 km,
-  one 80 m or more across from 1.5 km and 3.5 km, and any other from 1 km and 2.5 km. A model beside
-  a low camera at a steep pitch keeps its near level however far the map's centre is, and a model
-  near a threshold keeps its level until it is about 10% past it. A model casts its shadow with its
-  next lighter level, and a model outside the view or the light's reach is not drawn.
-- **Budgets.** A level has at most 200,000 triangles and 200,000 vertices, and a map at most 64
-  building models. Triangles of the default scene are read with their node transforms; textures,
-  animations and compressed geometry (Draco or meshopt) are not.
-
-The build reads each model, reports a problem with the file and what to change, works out its
-footprint and writes it beside the style as a prepared model file: a glTF binary whose meshes are
-quantised (`KHR_mesh_quantization`) and compressed by meshoptimizer (`EXT_meshopt_compression`),
-which any glTF viewer opens. The renderer downloads a model only when it stands near the tiles round
-the camera, whether or not those tiles hold buildings, keeps the nearest dozen, and builds the tiles
-under it again without the buildings that
-reach more than half a metre into its footprint; a neighbour that only touches it stays. A tile of
-buildings near a model waits for it, at most a second and a half, so its buildings are not raised
-and then taken away, and the model fades in when it comes to stand. A model that cannot be
-downloaded leaves those buildings standing. Reading a prepared model file loads
-meshoptimizer's WebAssembly decoder, so a page with a Content Security Policy allows
-`'wasm-unsafe-eval'` in its `script-src`.
-
-Preparation also computes local geometric ambient visibility, independently of the model's
-colour. `modelOcclusion` sets its strength from zero to one (default `0.75`); `occlusion: false`
-disables it. Occluded cavities receive less ambient light while direct sun and dynamic shadows
-remain independent. Existing prepared files with fully exposed vertices retain their appearance.
-Reprepare their original GLBs to gain geometric occlusion. See
-[model preparation](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/docs/building-models.md)
-for authoring, sampling and costs.
-
-## Team 3D models
-
-On Tileflow Hosted, a map's building models are its Team's 3D models: each is published once, under
-its name, and every map of the Team that places a model of that name draws it. Locally, the map
-draws its own `.glb` files, so the map is previewed and developed without an account.
-
-```sh
-npx tileflow models publish ./models/eiffel-tower.glb --team @acme
-npx tileflow models status eiffel-tower --team @acme
-```
-
-`tileflow models publish` prepares each building model as a build does and publishes it as the
-model's new current version; with no path, it publishes the building models of every map in the
-project's config. Publishing the bytes of the current version again changes nothing. A hosted map
-follows each model's current version: a new version, or `tileflow models restore`, which makes the
-previous version current again, changes every map that places it the next time the map loads,
-without deploying the maps again. A model keeps its current and previous versions.
-
-`tileflow deploy` writes each placement of a building model as the placeholder
-`tileflow://team-models/<name>` (`tileflowTeamModelUrl(name)`), which the deploy replaces with the
-model's address in the map's Team; a model the Team has not published fails the deploy. The deploy
-also reports a model whose published version was prepared from other files than the map's, so an
-outdated model is easy to spot. A model's file, and what Tileflow shows about it, can be read
-without decoding its meshes with `readTileflowModelFileSummary`. Models are served publicly and may
-be cached, so they must not hold secrets or restricted personal data.
-
-## Roofs
-
-A building whose tiles carry a roof shape (World's `roof_shape`) gets that roof: `gabled`,
-`hipped`, `half_hipped`, `pyramidal`, `skillion`, `gambrel`, `mansard` and `saltbox` roofs, and
-faceted `dome`, `onion` and `round` ones. The ridge follows the building's long side, or
-`roof_orientation` and `roof_direction` when the tiles state them, and the walls rise to the roof,
-so gable ends are walls. Each slope takes the sun, shadows and edges like any face: the ridge and
-the hips are drawn as edges too.
-
-The roof's height is `roof_height` where the tiles state it, taken from the building's height.
-Otherwise the roof keeps the pitch of its shape (30° for a gabled or hipped roof, a half sphere for a
-dome); it stands on the walls when the height came from levels or a fallback, and reaches the
-building's height when that was measured (`height_source` `height`). A building without a roof
-shape, a flat roof, a building with courtyards or one far from a rectangle (an L, a U) keeps a flat
-roof, and so does a building a tile's buffer cuts short.
-
-## Light and shadows
-
-Sun lighting and cast shadows are SDK defaults, including for Streets. Each map can choose its
-own finish. For native extrusion lighting, sharp corners and no shadows in an extending map:
-
-<!-- docs:check -->
-
-```ts
-import {defineMap, refine} from '@tileflow/core';
-import {streets} from '@tileflow/maps';
-
-export default defineMap({
-  id: 'graphic-streets',
-  name: 'Graphic streets',
-  version: 1,
-  extends: streets,
-  modules: {
-    buildings: refine({
-      threeDimensional: {lighting: 'style', edgeRadius: 0, shadows: false, occlusion: false},
-    }),
-  },
-});
-```
-
-Select `timeOfDay` through your map adapter to change the authored direction, colour and strength
-of direct and ambient light. Streets includes moonlight and shadows in its night presets. These
-presets are independent of the user's clock and location. In Inspector, use the 3D view and
-**Map → Buildings → Building light / Cast shadows**. The theme's `lighting.sun.shadowIntensity`
-controls shadow strength; `lighting.ambient` fills the shade. Use `controller.setSun({date,
-location})` for an astronomical direction instead, as described in
-[sun and light](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/sun-and-light.md).
-
-`threeDimensional.lighting: 'style'` uses MapLibre's `light` position,
-anchor, colour and intensity, together with the authored extrusion's `verticalGradient`.
-Changing the scene sun does not change this base lighting. The style's native lighting defaults
-apply when it declares no light.
-
-With the default `lighting: 'sun'`, 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)).
-Without a controller, the renderer reads the compiled style's sun, falling back to the style's
-light direction and then the SDK daylight. It refreshes this cached light on style changes.
-A sunlit roof keeps the building's colour, a wall turned to a low sun glows, and shade takes the
-sky's colour. Shadows lengthen as the sun lowers, with their projected direction limited to 15°
-above the horizon. The actual light retains its authored altitude; a sun below the horizon casts none.
-
-A wall sees half the sky, so at night, when the ground gives back little light, walls in shade
-stay darker than roofs. A theme's night `lighting.sun` set high (60° or more) lights roofs more than
-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. 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 when `shadows: true`. With it off, buildings neither cast nor receive
-scene shadows, even when another 3D layer uses them.
-
-## Edges
-
-Where one building ends and the next starts stays legible at any distance: each roof's outline and
-each building's outer corners catch the light in a line one CSS pixel wide, whatever the zoom, when enabled. `colorVariation` independently varies building brightness by up to the specified
-fraction (0–1); it defaults to 0, so authored colours remain unchanged. Use 0.06 for the earlier
-6% variation. 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 (the default, none) to 1.
-
-`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
-
-Architectural illumination has two independent controls:
-
-- `floodLight` selects ordinary buildings by height. Ground light starts at `minGroundHeight`
-  (30 m by default), with a stable per-building `groundRadius` in metres (default `[30, 100]`).
-  Wall light starts above `minWallHeight` (200 m); its reach is building height times
-  `wallHeightRatio` (default `1/3`). `intensity` is zero to one and `color` is a theme colour.
-  The effect fades with scene brightness; `brightnessScale` compensates an authored light-colour
-  transform and defaults to one. Overlapping ground contributions use their strongest value.
-- `modelLighting` assigns physical materials and emission to architectural roles. Each profile accepts
-  `emissiveStrength` (zero to five), optional `emissiveColor` (otherwise the surface's own colour), and
-  `emissiveHeight`: `[beginHeight, endHeight, beginMultiplier, endMultiplier, curve]`.
-  Heights are fractions of the source mesh's vertical bounds (the full model for legacy files),
-  multipliers are zero to one, and the exponent is
-  `10 ** curve`, with `curve` from -1 to 1. Equal heights give a constant multiplier of one.
-  Every gradient component, strength and colour may use theme tokens. Emission is mixed in linear light and is independent
-  of ambient occlusion and solar shadows. Values above one saturate the surface emission at one;
-  they also control the falloff of explicitly authored area emitters.
-
-Physical profiles also accept `color`, `colorMix` (zero to one, default one when a tint exists),
-`roughness` and `metallic` (zero to one). Explicit `modelColors` override role tints. Missing
-physical overrides retain the glTF material. `emissiveVariation` adds a stable, model-seeded amount
-from zero to its value. Optional `colorVariation` supplies independent `[min, max]` ranges for
-`hue` (0–360), `saturation` and `lightness` (0–100), with `space: 'srgb'` (default) or `'linear'`.
-The same model identity keeps its samples across LODs and theme changes.
-
-Streets leaves ordinary flood lighting off in its light presets. Its dusk/night wall profile uses a strength
-of `0.1` and `[0.5, 0, 0, 1, 0.8]`, concentrating a warm wash near the foot. Monochrome uses a
-weaker neutral wall profile and no architectural ground flood. Prepared models without role
-metadata take each part's default role. Windows use metallic reflection and varied emission;
-doors and logos have separate profiles, and roofs remain non-emissive. Day/dawn profiles follow
-the scene's brighter material response. A role does not generate missing windows or ground emitters.
-See [building-model preparation](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/docs/building-models.md)
-for glTF channels, explicit area emitters, compatibility and resource costs.
-
-The separate `nightLight` control retains its decorative building and shop effects:
-
-With `nightLight` above 0, the buildings light the street from data at night (as the sun's
-`brightness` falls):
-
-- Landmarks (World's `building_tone` `destination`) and towers of 40 m or more, one in two, are
-  flood-lit at their foot, on the wall and the ground around it.
-- Buildings that hold places busy at night light the windows of their ground floor and spill their
-  light a few metres onto the pavement: bars and clubs in a neon of their own or a warm light,
-  theatres and cinemas in a bright white, places to eat in amber. A building takes the strongest
-  use of its places, nightlife before entertainment before dining. Walls round a courtyard stay
-  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: 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 0.
-
-For the streets themselves, see
-[street lights](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/street-lights.md),
-which draws over the buildings so they hide the lamps behind them; both layers share each tile's
-download.
-
-## Options
-
-The renderer's own options say only how it is delivered: `minzoom` (15 by default; the default
-entrance bands start from it), `maxTiles`,
-`beforeId` to place the layer before another one, and `transformRequest` to apply the map's request
-rules to the tiles it reads.
-
-## Cost
-
-During partial opacity, a depth-only geometry pass resolves the nearest surfaces before colour
-blending, preventing rear walls from bleeding through. At full opacity only the normal geometry
-pass runs; zoom fading schedules no extra animation frames or per-zoom mesh rebuilds.
-
-The browser bundle builds from the tiles' bytes in one worker that the page's 3D buildings, trees
-and street lights share, nearest tiles first: it decodes each tile once for all of them, meshes its
-buildings, keeps their indices to 16 bits when the vertices allow, lays out the walls' contact-band
-segments and transfers the finished arrays. The renderer uploads them to the GPU and keeps no copy;
-a style reloaded in full keeps the uploaded buffers. No worker URL or extra asset hosting is needed.
-A Content Security Policy must allow `worker-src blob:` to use this path; if workers are
-unavailable or blocked, the layers build in the page instead. The worker is terminated when the
-last of those layers is disposed. Tiles the camera has left are not downloaded or built. Pending tile updates retain
-the previous mesh until their replacement is ready; cancelled and obsolete results are discarded.
-
-Mercator rendering batches buildings spatially and skips batches outside the camera. Shadow
-casting uses the light's bounds independently, so an offscreen building can still cast a visible
-shadow. Ground contact and flood bands retain their physical reach when testing visibility.
-Rounded corners use fewer segments when their screen radius is small and retain the original
-tessellation up close. Latitude, radius and pitch inform this choice; very oblique views keep full
-detail. Changes are prepared asynchronously; heights, feature colours,
-and the contact-shadow settings stay the same. GPU uploads remain limited to two tiles per frame.
-
-The shared shadow map is at most 4096 × 4096. On a planar view it concentrates resolution on visible
-ground and raised surfaces, while every loaded caster can still project into that area. A snapped
-Mercator texel grid stays stable during small pans, including changes of latitude, without fixing
-the meshes' physical metre scale. One filtered depth comparison keeps edges sharp.
-Missing camera capabilities, terrain or a view near the horizon use the full loaded area instead.
-The depth pass runs again when its focused area, light or casting geometry changes and is reused
-when they stay unchanged. While the camera moves, the focused area takes a quarter of its span as a
-margin on each side and is kept while it still covers the view at a similar resolution, so the
-depth pass is not drawn on every frame; once the camera stops, it is fitted to the view again.
-
-Model ambient visibility and lighting roles retain the existing 16-byte vertex stride. They add
-no geometry pass or texture. Architectural ground lighting uses a separate one-byte-per-pixel
-mask and one geometry/composite pair of passes while active; its mask is released when inactive.
-The contact band and the architectural light draw their masks in the layer's prerender, before
-the map's main pass, so the map's framebuffer is never switched while its layers draw.
-At 1280 × 720 and DPR 1, the mask occupies 921,600 bytes, excluding driver overhead.
-
-## Limits
-
-- Mercator only; the layer draws nothing below its `minzoom`.
-- No terrain: buildings stand on flat ground.
-- One building colour per feature and theme, on its roof and walls alike; facades are not drawn.
-- Roofs follow the building's smallest enclosing rectangle: a building with courtyards or far from a
-  rectangle keeps a flat roof, and `sawtooth` roofs are drawn flat.
-- A colour expression is evaluated at zoom 16.
-- Building models and landmarks take no illuminated edges and cannot be picked or styled by state.
-- Model materials use semantic colours and role emission; physical roughness, metallic
-  reflections and authored textures are not rendered.
-- A hosted map places its building models as its Team's 3D models: `tileflow deploy` uploads no
-  model files (see [Team 3D models](#team-3d-models)). A deploy with `--with-native` does not take
-  them, since MapLibre Native draws no models. Models named by `url` deploy as they are.