@tileflow/dev 0.1.0-alpha.36 → 0.1.0-alpha.38

package/docs/building-models.md

@@ -7,7 +7,15 @@ textures. Animations, skins and morph targets are not evaluated; export their st
 
 ## Separate colour from architectural role
 
-Material names select a palette slot: `surface`, `secondary`, `glass`, `accent` or `roof`.
+A material's name is the part it belongs to: an architectural part, `surface`, `secondary`,
+`glass`, `accent` or `roof`, or a part of the model's own, such as `water`, `vegetation`, `wood` or
+`stone`. Names are lower-case words joined by hyphens or underscores, at most 32 characters, and a
+level names at most 16 parts; materials of the same part share its name. The map colours a part
+through `buildings.threeDimensional.modelColors` under its name; a part it does not colour keeps
+its material's colour. Name pools `water`, planting `vegetation` and timber `wood` where they fit:
+Streets colours these from its water and tree colours in every theme. A GLB whose materials name
+only `bark`, `leaves`, `fronds` or `stem` is a tree model, not a building model.
+
 The optional `material.extras.tileflow.lightingRole` selects lighting independently:
 
 ```json
@@ -29,25 +37,29 @@ roles are `unclassified`, `wall`, `door`, `roof`, `window`, `lamp` and `logo`. A
 geometry; it does not turn on light by itself. The map supplies emission through
 `buildings.threeDimensional.modelLighting`.
 
-Legacy models without an explicit role use these defaults:
+A material without an explicit role takes its part's default:
+
+| Part                             | Lighting role  |
+| -------------------------------- | -------------- |
+| `surface`, `secondary`, `accent` | `wall`         |
+| `glass`                          | `window`       |
+| `roof`                           | `roof`         |
+| Any other part                   | `unclassified` |
 
-| Palette slot                     | Lighting role |
-| -------------------------------- | ------------- |
-| `surface`, `secondary`, `accent` | `wall`        |
-| `glass`                          | `window`      |
-| `roof`                           | `roof`        |
+A part names a colour, not a material: physical properties and emission remain controlled by the
+authored material and its independent lighting role.
 
 Doors, lamps and logos require an explicit role. Use `unclassified` for a part that must not inherit
 a role. Invalid role names fail preparation. An exporter's numeric material suffix, such as
 `surface.001`, is ignored.
 
-Keep a stone relief in a wall role when it should receive the wall's lighting. A separate colour
-slot can distinguish its stone without creating a separate light source. Mark roof geometry as
+Keep a stone relief in a wall role when it should receive the wall's lighting. A part of its own,
+such as `stone`, can distinguish its colour without creating a separate light source. Mark roof geometry as
 roof even when it shares a colour with a facade.
 
 ## Physical materials
 
-The importer retains these glTF 2.0 channels independently of palette and role:
+The importer retains these glTF 2.0 channels independently of part and role:
 
 | Channel            | Inputs                                                                            |
 | ------------------ | --------------------------------------------------------------------------------- |
@@ -60,6 +72,7 @@ The importer retains these glTF 2.0 channels independently of palette and role:
 | Unlit              | `KHR_materials_unlit`                                                             |
 
 `TEXCOORD_0`, `TEXCOORD_1`, glTF sampler wrapping/filtering and `KHR_texture_transform` are retained.
+`TEXCOORD_1` must lie between zero and one, since prepared files store it with sixteen bits.
 Every referenced channel must have its declared UV set. UV and colour seams survive welding.
 Colour textures and lit output use the scene's gamma-2.2 transfer approximation.
 Role emission mixes the complete material radiance toward its target, including authored emission.
@@ -107,8 +120,8 @@ A `door` role lights the surface. To project its spill, declare a rectangle in
 
 `start` and `end` form the horizontal lower edge. The spill faces the right of that edge when
 viewed from above. `height` sets the rectangle's height; optional `depth` narrows the spill around
-recessed jambs. Node transforms apply to the emitter. Its role supplies emission and its part
-supplies the fallback palette colour. No emitter is inferred from material colour or geometry.
+recessed jambs. Node transforms apply to the emitter. Its role supplies emission and its part, by name,
+supplies the fallback colour. No emitter is inferred from material colour or geometry.
 
 Each level accepts 128 emitters. Each projects a four-triangle, depth-tested spill with reach
 `clamp(1.3 * height, 4, 10)` metres. This authored effect does not cast a new light or shadow onto
@@ -116,11 +129,30 @@ other meshes. It follows the model's visibility and theme; zero emission removes
 
 ## Ambient visibility
 
-Preparation estimates each vertex's local ambient visibility using 48 deterministic,
-cosine-weighted hemisphere samples, a two-metre reach and a two-millimetre origin bias. A spatial
-hierarchy limits intersection work; repeated positions and normals share samples. Nearby
-occluders contribute more than distant ones. Each level is prepared independently, including
-occlusion between its distinct primitives. Footprint meshes do not occlude.
+Preparation estimates local ambient visibility with deterministic, cosine-weighted hemisphere
+samples, a two-metre reach and a two-millimetre origin bias. A spatial hierarchy limits
+intersection work. Nearby occluders contribute more than distant ones. Each level is prepared
+independently, including occlusion between its distinct primitives. Footprint meshes do not
+occlude.
+
+The near and mid levels carry visibility in an occlusion texture. Preparation lays the level's
+triangles flat in one atlas: connected triangles facing within 20 degrees of each other share a
+chart, curved strips are cut where they would waste their rectangle, and charts under two texels
+share a palette of uniform grey texels. Shade detail grows with the square root of the level's
+surface: about 89·A^0.54 texels of visible shade for A square metres, so a large building takes
+coarser shade per metre than a small one. The near level's atlas budget allows for packing and
+has two floors: 65,536 texels, so small detailed buildings keep their mouldings distinct, and
+1.3 texels a metre, so towers keep each storey's mullions and slabs apart. It takes at most
+524,288 texels; the mid level takes a quarter of it. The density is the highest at which
+the atlas fits its budget. Each texel averages four points inside it, 12 rays each with turned
+patterns; points hidden just behind other surfaces are skipped. The atlas is a greyscale JPEG of
+quality 35, about a tenth of a byte a texel, on the second UV set, and becomes
+every material's occlusion texture. Vertices are split where charts meet; triangles keep their
+order.
+
+Contact shade therefore follows the surface instead of spreading between distant vertices. A
+level whose materials already use an occlusion texture or the second UV set, or whose charts
+cannot fit the budget, and the far level keep 48-sample visibility on their vertices.
 
 The result travels independently of colour. Do not bake ambient occlusion into `COLOR_0`: colour
 also affects direct sunlight and emission. The runtime applies prepared visibility only to the
@@ -130,10 +162,11 @@ ambient contribution; solar visibility still comes from the dynamic shadow map.
 `threeDimensional.occlusion: false` also disables model ambient occlusion. Changing these
 runtime controls does not prepare the geometry again.
 
-Preparation cost grows with unique vertices, samples and nearby geometry. It is paid when a raw
-model is prepared, never per frame. Runtime occlusion adds no draw pass or texture and uses the
-existing visibility byte. It describes opaque geometry at rest; it does not follow moving parts,
-other models, the ground or surrounding buildings.
+Preparation cost grows with texels, rays and nearby geometry; a large landmark's near level takes
+seconds to tens of seconds. It is paid when a raw model is prepared, never per frame. A texture
+used only for occlusion is uploaded with one channel, at most 0.7 MB with mipmaps for a near level.
+Visibility describes opaque geometry at rest; it does not follow moving parts, other models, the
+ground or surrounding buildings.
 
 ## Files and compatibility
 
@@ -144,36 +177,42 @@ for placement and limits.
 
 Prepared files retain a 16-byte vertex:
 
-| Bytes | Content                          |
-| ----- | -------------------------------- |
-| 0–5   | Quantized position               |
-| 6–7   | Padding                          |
-| 8–10  | Normal                           |
-| 11    | Padding                          |
-| 12    | Palette slot                     |
-| 13    | Shade within that slot           |
-| 14    | Ambient visibility, 0–255        |
-| 15    | Architectural lighting role, 0–6 |
-
-The model root's `extras.tileflow.lightingRoles: 1` declares the last byte. Older files without
-that marker use the legacy palette mapping. Existing fully exposed visibility values stay fully
-exposed; reprepare the original GLBs to obtain geometric occlusion. Geometry, normals and palette
-slots are not modified by the visibility calculation.
+| Bytes | Content                               |
+| ----- | ------------------------------------- |
+| 0–5   | Quantized position                    |
+| 6–7   | Padding                               |
+| 8–10  | Normal                                |
+| 11    | Padding                               |
+| 12    | Part, an index into the level's parts |
+| 13    | Shade within that part                |
+| 14    | Ambient visibility, 0–255             |
+| 15    | Architectural lighting role, 0–6      |
+
+Each level node's `extras.tileflow.parts` lists the names its part indices count through. Older
+files without that list count through `surface`, `secondary`, `glass`, `accent` and `roof`. The
+model root's `extras.tileflow.lightingRoles: 1` declares the last byte; older files without that
+marker take each part's default role. Existing fully exposed visibility values stay fully exposed;
+reprepare the original GLBs to obtain geometric occlusion. The occlusion texture splits vertices
+along its charts without moving them or changing their normals or parts.
 
 Roles and visibility survive meshoptimizer compression. The existing `_PAINT` accessor and vertex
 stride are retained; the role occupies previously unused padding. Prepared files are an SDK
 transport format, while material extras are the authoring interface.
 
-Physical data is optional `extras.tileflow.surface` metadata on each level, with `version: 1`.
-Two VEC4 accessors address a separate 32-byte stream: UV0/UV1 followed by linear vertex RGBA.
+Physical data is optional `extras.tileflow.surface` metadata on each level, with `version: 2`.
+Three accessors address two streams: a 24-byte float stream holding UV0 and linear vertex RGBA,
+and a 4-byte stream holding UV1 as normalised sixteen-bit values, so UV1 lies between zero and
+one. Runtimes that read the earlier `version: 1` layout cannot read it, and current runtimes no
+longer read `version: 1`: prepare models again with the matching Dev release.
 The metadata also holds material draw ranges, channel references, embedded images and emitters.
 Ranges preserve each source mesh's vertical emission bounds independently of its material.
-The original primitive layout remains unchanged. Older readers draw its legacy geometry and
-palette; they ignore the optional physical data. New readers preserve the legacy shading path
+The original primitive layout remains unchanged. Older readers draw its geometry and part
+colours; they ignore the optional physical data. New readers preserve the legacy shading path
 when physical data is absent. Reprepare source GLBs to obtain the new channels.
 
 The auxiliary stream costs 32 bytes per retained vertex on the GPU. Each resident texture uses
-four bytes per pixel, plus about one third for mipmaps when enabled. Decoded images stay available
+four bytes per pixel, or one when only occlusion reads it, plus about one third for mipmaps when
+enabled. Decoded images stay available
 for context restoration until the model is evicted. Physical materials add one draw per material
 range per colour/shadow pass; explicit emitters add one four-triangle draw each. No environment
 cube map or screen-space effect is required.

package/docs/layers-inspection.md

@@ -3,7 +3,7 @@
 Open the local preview and select **Layers**. The panel inspects the current map without changing its
 authored style. **By module** groups physical layers using compiler contributions; shared layers retain
 every owner. **Draw order** lists the renderer's public layer sequence, latest draw calls first.
-Custom runtime layers are included even though they are absent from Style JSON. DevTools overlays
+Custom runtime layers are included even though they are absent from Style JSON. Inspector overlays
 are excluded. Unknown ownership is labeled **Unattributed**, rather than guessed from an ID.
 
 Press **I** or the element-picker icon and click an element on the map. Its layer becomes selected in

package/docs/local-comparison-workbench-and-compiler-inspection.md

@@ -1,13 +1,13 @@
-# Map DevTools and compiler inspection
+# Inspector and compiler inspection
 
 Start with the [@tileflow/dev guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/README.md) for installation and a complete first example.
 
-The CLI opens Map DevTools through `tileflow preview`. It uses one map and one watched artifact
-session by default. A developer-tools panel groups Map, Layers, Tiles, Assets, Debug and Diagnostics. Camera controls
+The CLI opens Inspector through `tileflow preview`. It uses one map and one watched artifact
+session by default. The panel groups Map, Layers, Tiles, Assets, Debug and Diagnostics. Camera controls
 occupy a separate row below the navigation. Use the three-dot menu to dock left, right or below
 the map and choose System, Light or Dark appearance. Drag the divider to resize it; focused dividers
 also support arrow keys. Dock position and dimensions persist locally. Layer observations and highlights stay local to the preview. The map fills the remaining
-workspace without brand headers or map-status badges. Closing the panel leaves a small **DevTools**
+workspace without brand headers or map-status badges. Closing the panel leaves a small **Inspector**
 button to reopen it; capture and comparison controls are absent from the interface.
 
 Add `--against-map ...` or `--against-config ...` for synchronized comparison. Custom local servers
@@ -34,7 +34,7 @@ const fetch = createTileflowComparisonRequestHandler({
 });
 ```
 
-Set `fitViewport: true` on each dev handler embedded in a resizable Map DevTools pane. Scene previews
+Set `fitViewport: true` on each dev handler embedded in a resizable Inspector pane. Scene previews
 then fit their pane while captures retain the scene's declared frame. Standalone dev handlers keep
 the fixed scene viewport by default.
 

package/docs/map-design-diagnostics.md

@@ -1,6 +1,6 @@
 # Map design diagnostics
 
-Open **Diagnostics** in Map DevTools to investigate a map's rules, visual resources and current-view
+Open **Diagnostics** in Inspector to investigate a map's rules, visual resources and current-view
 composition. The list groups findings under **Readability**, **Style**, **Assets** and **Performance**.
 **Problem** means a confirmed configuration or resource failure. **Review** means an observed
 situation may be intentional. Counts refer to grouped findings, not quality scores.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/dev",
-  "version": "0.1.0-alpha.36",
+  "version": "0.1.0-alpha.38",
   "license": "Apache-2.0",
   "description": "Node development utilities for Tileflow configs and builds.",
   "type": "module",
@@ -84,7 +84,7 @@
   "dependencies": {
     "@mapbox/vector-tile": "3.0.0",
     "@maplibre/maplibre-gl-style-spec": "26.4.4",
-    "@tileflow/core": ">=0.1.0-alpha.39 <0.1.0-beta.0",
+    "@tileflow/core": ">=0.1.0-alpha.41 <0.1.0-beta.0",
     "chokidar": "4.0.3",
     "fontkit": "2.0.4",
     "jiti": "^2.7.0",
@@ -96,13 +96,13 @@
     "three": "0.185.1"
   },
   "devDependencies": {
-    "@tileflow/maps": "0.1.0-alpha.13"
+    "@tileflow/maps": "0.1.0-alpha.15"
   },
   "optionalDependencies": {
     "sharp": "0.35.5"
   },
   "scripts": {
-    "build": "tsup src/artifacts.ts src/config.ts src/fonts.ts src/icons.ts src/inspect.ts src/preview.ts src/server.ts src/tilesets.ts src/validation.ts --format esm --dts --clean --platform node --external sharp && tsup --config tsup.devtools.config.ts",
+    "build": "tsup src/artifacts.ts src/config.ts src/fonts.ts src/icons.ts src/inspect.ts src/preview.ts src/server.ts src/tilesets.ts src/validation.ts --format esm --dts --clean --platform node --external sharp && tsup --config tsup.inspector.config.ts",
     "test": "tsx --test test/*.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "lint": "tsc -p tsconfig.json --noEmit",