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

package/docs/trees-3d.md

@@ -3,7 +3,7 @@
 `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,
+has them. The data's hedges stand beside them as clipped green walls. 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
@@ -12,10 +12,68 @@ style it compiles, for every theme, and the renderer follows theme changes and b
 
 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.
+When model trees are requested, Capture, Static Maps, Native, and browsers without WebGL2 use
+the module's `fallback`: `flat` by default, or `none` to omit trees. Static output uses the 2D view
+for `auto` maps. Streets chooses `none`, so it never substitutes flat crowns
+for its models unless an extension explicitly chooses `flat` or `auto`.
 
-## Stand the trees
+## Visibility and representation
+
+Use `createTileflowVegetation` for application controls. React, Vue and Svelte mount it automatically
+in interactive maps. The map chooses `vegetation.mode` independently of visibility:
+
+| Mode           | 2D view             | 3D view             |
+| -------------- | ------------------- | ------------------- |
+| `3d` (default) | Model trees         | Model trees         |
+| `flat`         | Flat crowns/circles | Flat crowns/circles |
+| `auto`         | Flat crowns/circles | Model trees         |
+
+`viewMode` is explicit application state (`2d` by default), not a pitch threshold. Tilting the camera
+does not change representation. Visibility defaults to `vegetation.visible ?? true`; OFF hides every
+representation. Turning trees off releases model buffers and tile readers. Controls apply immediately,
+without a grow/sink animation, and do not change building appearance or lighting.
+
+<!-- docs:check -->
+
+```ts
+import {createTileflowVegetation, type TileflowVegetationOptions} from '@tileflow/core/browser';
+
+export function mountVegetation(options: TileflowVegetationOptions) {
+  const trees = createTileflowVegetation({...options, viewMode: '2d'});
+  trees.setVisible(false); // Hide all vegetation, including flat artwork.
+  trees.setVisible(undefined); // Restore the map's authored visibility.
+  trees.setViewMode('3d'); // Only auto maps change representation.
+  return trees; // Call dispose() before removing the map, or let its remove event clean up.
+}
+```
+
+Pass the application's HTTP tile `transformRequest` when it supplies credentials or request headers;
+asynchronous transforms are supported. Use one vegetation controller per map and do not mount a second
+low-level tree renderer alongside it. Style replacement and theme changes retain visibility and view mode.
+
+To change an inherited map's policy while preserving its artwork:
+
+<!-- docs:check -->
+
+```ts
+import {defineMap, refine} from '@tileflow/core';
+import {streets} from '@tileflow/maps';
+
+export default defineMap({
+  id: 'adaptive-trees',
+  version: 1,
+  extends: streets,
+  modules: {vegetation: refine({mode: 'auto', fallback: 'flat'})},
+});
+```
+
+Use `refine({visible: false})` for initially hidden vegetation that can be enabled at runtime.
+Use `vegetation: disable()` to remove the module entirely; a runtime toggle cannot restore a module
+that is absent from the compiled map. Browser framework components accept `vegetation={false}` and
+`viewMode="3d"` (Vue: `:vegetation="false"`, `view-mode="3d"`). Image mode uses the compiled static
+fallback and does not apply these interactive controls.
+
+## Animate trees with the low-level renderer
 
 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:
@@ -42,13 +100,14 @@ a share of their size, from 0 to 1. Each returns a promise that resolves once th
 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
+This low-level API retains its flat-layer restoration behavior; use the vegetation controller for
+a visibility toggle. 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.
+placed, the pieces of hedge placed and the trees drawn in the last frame.
 
 ## What the trees come from
 
@@ -61,6 +120,10 @@ The renderer reads the source's z15 tiles round the camera:
 - 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.
+- World's `traffic_control` layer: its hedges (`subclass` `hedge`), the lines OpenStreetMap maps and
+  the hedges it maps as areas. A hedge stands as pieces 1.2 metres apart along each line and round
+  each area, 0.8 metres thick, at its `height` or 1.3 metres, a metre higher where `hedge` says
+  `hedge_bank`. The style still draws the hedge flat underneath, and fences and walls stay flat.
 
 | Form       | From the data                                                                |
 | ---------- | ---------------------------------------------------------------------------- |
@@ -80,8 +143,12 @@ tile's buffer belong to the neighbouring tile, so no tree stands twice.
 
 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:
+lightest. Hedges take `hedgeColors`, the two darkest broadleaf colours unless the map gives its own;
+Streets gives its flat hedge's colours, so a hedge keeps its colour as it rises. `hedges: false`
+leaves hedges flat. A crown facing a sunlit sky takes its colour; shade takes the sky's light, as on 3D
+buildings. At night a neutral lift keeps crown tops visible; grey materials stay grey under neutral
+lighting, while coloured scene lighting can tint them. The vegetation module's `threeDimensional`
+options refine them for one map:
 
 <!-- docs:check -->
 
@@ -180,16 +247,20 @@ the same name; omitting `models` inherits them, and `[]` declares none.
 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, trees read the compiled style's sun and light direction, falling back to
+SDK daylight, just as 3D buildings do. This cached light refreshes when the style changes.
 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.
+the trees darken the map themselves. The depth pass uses the same visible tree ranks, near/far
+models and distance fade as the colour pass, so hidden trees do not leave full shadows behind.
+Shadow direction stops lowering at 15° above the horizon; the actual scene light keeps its angle.
 
 ## Options
 
-`minzoom` (15 by default) and `maxTiles` (25 by default, at most 64) bound where and how far trees
+`minzoom` (15 by default, fading to full coverage at 15.25 like buildings) 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
@@ -199,9 +270,10 @@ 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.
+tile. The shared shadow map concentrates resolution on the view when its public camera methods
+provide a safe planar fit. It is drawn again when that focused area, the light, visible tree
+selection, fading or geometry changes. Unchanged views reuse it. 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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/core",
-  "version": "0.1.0-alpha.34",
+  "version": "0.1.0-alpha.36",
   "license": "Apache-2.0",
   "description": "Typed Tileflow config and MapLibre style compiler.",
   "type": "module",
@@ -84,12 +84,13 @@
     "@mapbox/vector-tile": "3.0.0",
     "earcut": "3.2.4",
     "maplibre-contour": "0.1.0",
+    "meshoptimizer": "1.3.0",
     "pbf": "5.1.2",
-    "pmtiles": "4.4.0",
-    "whatwg-url": "15.1.0"
+    "pmtiles": "4.5.0",
+    "whatwg-url": "17.2.0"
   },
   "scripts": {
-    "build": "tsup --config tsup.build.config.ts && tsup --config tsup.native-profile.config.ts && tsup src/browser.ts --format esm --dts --no-splitting --platform browser && tsup --config tsup.native.config.ts && cp ../../docs/modules-api-reference.json dist/config-reference.json",
+    "build": "tsup --config tsup.build.config.ts && tsup --config tsup.native-profile.config.ts && tsup --config tsup.browser.config.ts && tsup --config tsup.native.config.ts && cp ../../docs/modules-api-reference.json dist/config-reference.json",
     "reference:check": "tsx scripts/generate-config-reference.ts --check",
     "reference:generate": "tsx scripts/generate-config-reference.ts --write",
     "verify": "pnpm run build && tsx --test test/*.test.ts",