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

package/docs/themes-and-module-styles.md

@@ -15,6 +15,61 @@ same token keys, so changing a theme can never change map structure or silently
 role. `defineTheme(base, definition)` is an authoring convenience that returns a fully materialized
 document; it does not leave an inheritance edge in the resolved config.
 
+## Start with one appearance
+
+A map can have one appearance for its entire lifetime. Neither `systemThemes` nor `timeOfDay` is
+required. This complete theme supplies the twelve base color roles the semantic compiler needs;
+copy it and change its colors to start an independent design without inheriting an official map:
+
+<!-- docs:check -->
+
+```ts
+import {defineTheme} from '@tileflow/core';
+
+export const paper = defineTheme({
+  id: 'paper',
+  version: 1,
+  colorScheme: 'light',
+  tokens: {
+    color: {
+      'surface.background': '#F6F7F3',
+      'surface.land': '#F1F3ED',
+      'surface.water': '#A9D3F5',
+      'surface.park': '#CDE8B5',
+      'surface.building': '#E6E3DA',
+      'roads.default': '#FFFFFF',
+      'roads.major': '#F4C95D',
+      'roads.casing': '#D9DEE2',
+      'boundaries.default': '#C9D1D9',
+      'labels.primary': '#3C4043',
+      'labels.muted': '#727B84',
+      'labels.halo': '#FFFFFF',
+    },
+  },
+});
+```
+
+An existing map definition can select this appearance with `themes: {paper}` and
+`defaultTheme: 'paper'`. Supply that map's data and font assets separately; the default typography
+uses `Noto Sans Regular`. A theme without these base roles is a valid appearance document but cannot
+compile a semantic map. Colors above are an editable starting point, including for monochrome,
+historical, dark-only, or imagined worlds; `colorScheme` describes the appearance for consumers and
+does not generate a palette or choose a time of day.
+
+The compiler derives more specific roles when they are absent. For example, primary and motorway
+roads initially use `roads.major`; declaring `roads.motorway` replaces only that derived color.
+Land-use fills, road casings, and label colors have their own semantic roles, so an explicit role
+always wins over its fallback. Use `color.mix()` and `token.color()` in a theme when the relationship
+itself should be authored and inspectable. Derivations resolve during compilation, without a clock
+or a per-frame palette calculation.
+
+Add named appearances when the map needs them. A day/night pair does not need dawn or dusk, and a
+theme named `paper` or `fantasy` does not need a temporal family. Declare `timeOfDay` only when the
+application should offer those artistic moments; see
+[time-of-day selection](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/theme-transitions-and-blends.md#time-of-day).
+
+## Compose and replace appearance values
+
 Some optional tokens are for the application rather than the map's own layers. Route inks
 (`route.line`, `route.casing`, `route.core`, `route.glow`, `route.alternative`,
 `route.glow.opacity` and `route.core.opacity`) set how an application draws its routes; a theme
@@ -83,6 +138,17 @@ deterministic OKLCH `color.mix()` keep derived palette logic inspectable. Unknow
 cross-category refs, token-schema drift, and unresolved visual nodes fail before Style JSON is
 emitted.
 
+Theme lighting also supports explicit removal during `defineTheme` composition. Use
+`lighting: reset()` to remove the entire inherited lighting configuration, or
+`lighting: {sun: reset(), ambient: reset()}` to remove those presets while retaining other light
+properties. The same operation can remove a direct property such as `position` or `color`.
+Omitting a property, or supplying an empty object, continues to inherit it. Reset operations are
+materialized immediately and never enter the resolved theme or Style JSON. Removing a lighting
+preset restores the renderer's fallback; it does not disable 3D shadows or occlusion. Those remain
+explicit building settings. See
+[sun and light](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/sun-and-light.md#replace-inherited-lighting)
+for a complete example.
+
 There is no physical-layer override for the Tileflow basemap or separate official-map authoring
 surface. Basemap behavior belongs to a typed control or owner-local render stack. Every
 official and application map therefore follows the same schema, inheritance rules, diagnostics,

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
@@ -107,7 +107,7 @@ 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
 
@@ -120,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                                                                |
 | ---------- | ---------------------------------------------------------------------------- |
@@ -139,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 -->
 
@@ -239,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
@@ -258,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.35",
+  "version": "0.1.0-alpha.36",
   "license": "Apache-2.0",
   "description": "Typed Tileflow config and MapLibre style compiler.",
   "type": "module",
@@ -90,7 +90,7 @@
     "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",