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

package/docs/beacon-map-audits.md

@@ -1,145 +0,0 @@
-# Beacon map audits (legacy)
-
-The Beacon scoring and tour interface has been replaced by **Diagnostics**. See
-[Map design diagnostics](./map-design-diagnostics.md) for the current workflow. This document
-describes historical audit reports; its scores are not comparable with Diagnostics findings.
-
-Open `tileflow preview`, select **Beacon**, choose **Desktop** or **Mobile** and
-**Active tour** (default), **Quick check** or **All zooms**, then **Run audit**. The report includes 48 checks grouped into Rendering (9), Loading
-(8), Legibility (8), Accessibility (8), Cartography (7) and Integrity (8). Expand a result for its
-measured value, target, evidence and suggested fix. Findings open Layers, Tiles or Debug. **Copy
-context for agent** copies the bounded report; it does not upload it.
-
-## Scope and restoration
-
-Active tour follows a deterministic route through the current view, London, New York, Tokyo,
-Nairobi and São Paulo. Each location has an overview and a detailed view, with zoom, bearing and
-pitch changes within the map's camera limits. Destinations outside explicit map bounds are skipped
-and listed in coverage. The current theme stays active; this route does not cover every theme.
-
-The tour has a 60-second budget: up to 55 seconds for navigation and sampling, with the remainder
-reserved for diagnostics. Each stop measures a 1.2-second flight, waits up to two seconds for tiles,
-then samples up to 2.4 seconds of continuous settled repaints. On a responsive map the run usually
-takes 45–60 seconds. Slow loading can exhaust the budget: remaining views are explicitly unmeasured,
-not passed. Synchronous analysis and restoration may add a small overhead. Reduced-motion settings
-replace flights with jumps; the report does not claim an animated navigation measurement then.
-
-**Tour measurements** lists the actual camera, moving/settled p95 frame intervals, sample counts,
-remaining tile wait after navigation, and total readiness including navigation for each view.
-Loading scores use the remaining wait, excluding scripted animation; any timed-out view fails
-readiness. A p95 requires at least 30 intervals; coverage flags fewer than 60 settled
-intervals. A view that did not finish loading before sampling receives no settled performance score.
-The rendering check uses the worst qualifying per-view p95, so a slow location is not hidden by an
-average across fast locations. Long stalls are retained. These measurements include browser
-scheduling and other work on the machine, rather than isolated GPU execution time.
-
-Quick check samples the current camera and concrete theme for about three seconds. It is useful
-for static style checks and a short settled rendering sample. All zooms visits each integer zoom
-from 0 through 22 within map limits at the same geographic centre, for every registered theme and
-time-of-day variant. It waits up to five seconds for readiness and samples 150 ms per view. This
-exhaustive scope can take several minutes; it is not the one-minute navigation benchmark. Use
-**New audit** from a result to change scope or viewport.
-
-Desktop uses an actual 1280×800 CSS iframe viewport; Mobile uses 390×844. The iframe is scaled to
-fit the workspace. CPU, GPU and network are those of the current computer: this is not phone
-hardware emulation. No cache clearing, network throttling or cold navigation occurs.
-
-Camera, viewport, pixel ratio, overlays and scene are restored after completion or cancellation.
-Moving the map interrupts the audit and keeps the user's camera. Leaving Beacon cancels the run.
-A map replacement invalidates the run. Reports and preview changes stay local and in memory.
-
-## Measurements and limits
-
-- **Rendering:** inter-render p95 during continuous repaints (moving and settled windows for Active tour), native overdraw samples (saturating at
-  8 passes), eligible layer count, intercepted WebGL draw calls, CPU placement time, data-driven
-  paint-rule count, custom-renderer CPU submission time, and an observable GPU allocation estimate.
-  CPU submission is not GPU execution time. Readbacks and feature inspection are outside the frame
-  sample. GPU memory excludes inaccessible allocations; a low estimate is informational.
-- **Loading:** unused source-layer MVT message bytes, original map-load event time, individual tile
-  sizes when exposed, view readiness, per-view transfer and request counts, compression and cache
-  observations. PMTiles archive ranges are not individual tile sizes. Resource Timing cannot prove
-  Cache-Control policy. Cached audit views are not a fresh visitor estimate.
-- **Legibility:** observed text-placement rejections, line-label candidates, nearby repeated label
-  anchors, a scored text-size budget, approximate density, halos, configured line curvature and
-  requested language-field coverage. Rejections can result from collisions, offscreen placement or
-  line fit; the report does not pretend to know the renderer's exact rejection cause.
-- **Accessibility:** sampled text contrast in current/night/other themes, color-vision simulation
-  heuristics, static non-text contrast, categorical color-only rules, the system motion preference,
-  and sampled label retention after temporarily setting the real canvas ratio to 3×. Contrast uses
-  evaluated colors and supported flat fill/halo backgrounds. Raster, 3D and unresolved backgrounds
-  are excluded. This is diagnostic evidence, not accessibility certification.
-- **Cartography:** enabled zoom-range gaps, potential abrupt layer entry, road and place hierarchy
-  heuristics, scored size-rule continuity, unchanged eligible-layer counts and sampled fill coverage.
-  Naming-based hierarchy checks explicitly identify their inferred roles and exclude unmatched IDs.
-- **Integrity:** missing icon references, actual theme coverage, hidden-layer source residency,
-  cached missing glyphs, unresolved expressions, locally unmatched filters, style-spec validation
-  and retained runtime/resource errors. Resident data is bounded; zero local matches does not mean
-  a filter never matches globally.
-
-Samples are bounded to 4,000 rendered query results, 100 labels and 64 resident vector tiles per
-view; feature expression checks use up to 24 candidates spread across the bounded source sample per
-layer. Filter evidence counts only the candidates actually evaluated. Geometry is discarded after
-observation. All-zoom style snapshots are shared per theme. Custom renderer and private MapLibre
-observations are version-isolated and can be unavailable on unsupported renderers.
-
-## Scores and useful comparisons
-
-Category scores average checks with a measured score. Overall score averages measured categories.
-Informational and unavailable checks are excluded. Legibility and Cartography show a numeric score
-when eligible samples exist, together with the specific score basis and sample count. Each currently
-has one scored benchmark; its other checks remain diagnostic. Their scores do not assess the entire
-visual quality of a map.
-A category with no measurable scores shows **—**. For numeric
-budgets, meeting the displayed target scores 100; exceeding it by up to 1.5× scores 70, by up to 2×
-scores 45, and beyond that scores 0. Minimum targets invert the ratio. Structural counts and cartographic heuristics are explicitly marked **Diagnostic · not scored**.
-These include expression counts, rejected candidates, localized name fields, halos, fill coverage
-and locally unmatched filters. They remain visible as evidence without asserting a defect.
-Error scoring includes only resources and runtime errors observed during the audit, not prior session failures. A high score does not establish global map quality.
-
-The two quality benchmarks use an explicit percentage, rather than the generic budget tiers:
-
-- **Legibility / Text-size budget:** percentage of sampled labels whose evaluated `text-size` is
-  at least 10 CSS px. The threshold is a design budget, not an accessibility standard.
-  The bounded sample rotates between rendered symbol layers so dense POI layers do not monopolize it.
-  Font metrics, formatted section scaling, script, perspective and final glyph rasterization are not measured.
-  Unresolved expressions are excluded; their renderer fallback does not count as a passing size.
-- **Cartography / Size-rule continuity:** percentage of sampled layer/view size rules without a
-  jump exceeding both 1 px and 25% of the smaller size (with a 1 px denominator floor). For line
-  width, text size and circle radius, evaluate immediately around the actual zoom stops at
-  `stop ± 0.0001`, within the layer and camera zoom bounds. Continuous interpolation and physical
-  width scaling pass, even when sizes double between integer zooms. Changes at layer entry/exit,
-  filtered-out features and stops with opacity at or below 1% on either side are excluded.
-  Each ready view checks up to 128 visible layers, four feature contexts per layer and 128 stops
-  per rule. Missing or oversized evaluations are excluded. This measures authored rule continuity,
-  not final GPU pixels, label placement or transition animations. Intentional steps can exceed
-  the budget and should be reviewed before changing them.
-
-Only views that finished loading contribute to these scores. Each check exports `sample` with
-`passed`, `total`, `skipped` and `unit`; category `scoreBasis` identifies what its number represents.
-An observed outlier remains a warning even when rounding produces a high percentage. Findings
-include the layer and camera, with the exact zoom stop for a size jump. No eligible samples means
-unavailable, never an automatic 100. Repeated features in different views are separate observations.
-
-Repeat with the same view, scope, device, cache conditions and browser load when comparing changes.
-Review the evidence before acting on a warning. Copying findings supplies an agent with concrete
-layer IDs, camera context, measured values, coverage limits and suggested investigation steps.
-
-## Reproducible reports and future automation
-
-Reports use `version: 4`, `scoring: "measured-evidence-v3"` and identify the deterministic tour as `protocol: "active-tour-v1"`.
-Scenarios carry stable IDs, location, actual camera, theme, frame sample counts, p95, long-frame
-fraction, maximum frame interval, `tileWaitMs` after navigation, end-to-end `readyMs` and observed
-network transfer. Policy v2 excludes scripted camera time from loading scores; v1 included it.
-Policy v3 adds the sampled text-size and rule-continuity benchmarks described above; v2 left both
-categories entirely diagnostic. Old reports retain their original scores and must be rerun to use v3.
-`plannedViews` and
-`budgetExhausted` distinguish completed coverage from a partial run. Camera, viewport, DPR, duration
-and warnings accompany the scores. Change the protocol identifier when its itinerary or sampling
-rules change. The scoring policy is versioned separately: do not compare aggregate scores across
-policies. The original Active tour itinerary, timing windows and thresholds for measured frame
-performance are unchanged. There is no CI runner or GitHub integration in this feature.
-
-For future comparisons, keep protocol, map revision, initial view, browser/device, viewport, theme,
-DPR and cache conditions fixed. A single one-minute run is a diagnostic sample; repeated runs on a
-controlled worker are needed before setting regression gates. The tour does not clear caches,
-emulate mobile hardware, or prove worldwide coverage from six locations.

package/docs/bounded-pmtiles-resource-inspection.md

@@ -1,21 +0,0 @@
-# Bounded PMTiles resource 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.
-
-Node tooling can inspect one local PMTiles archive without reading it completely:
-
-```ts
-import {inspectTileflowPmtiles} from '@tileflow/dev/tilesets';
-
-const inspection = await inspectTileflowPmtiles('./data/stores.pmtiles', {
-  includeValues: ['category', 'status'],
-});
-```
-
-Inspection schema 1 separates the authoritative PMTiles header and TileJSON `vector_layers` metadata
-from deterministic bounded MVT observations. Each sampled field reports present/missing feature
-counts, observed primitive types, capped distinct-value cardinality, numeric min/max, and explicit
-truncation. Values are returned only for requested portable field names, with at most 32 requested
-fields, 16 values per field, and 256 characters per string. Sampling reads at most eight tiles,
-20,000 features, or 24 MB of tile data; `sample: false` returns only authoritative metadata and does
-not accept `includeValues`.

package/docs/bounded-vector-feature-inspection.md

@@ -1,99 +0,0 @@
-# Bounded vector-feature 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.
-
-Custom Node tooling can inspect only the features visible near a configured camera without opening
-a browser:
-
-```ts
-import {inspectTileflowFeatures} from '@tileflow/dev/inspect';
-
-const internalCatalog = artifacts.project;
-const inspection = await inspectTileflowFeatures(internalCatalog, 'madrid', {
-  center: [-3.6927512, 40.4086555],
-  zoom: 16,
-  sourceLayers: ['poi'],
-  properties: ['name', 'category', 'type', 'icon', 'filter_rank', 'size_rank'],
-  width: 512,
-  height: 512,
-  limit: 100,
-});
-```
-
-The inspector supports ordinary HTTP(S) vector sources and TileJSON. It bounds viewport, tile
-count, individual/total bytes, scanned and returned features, property count/string lengths, and
-request time; results are deduplicated and sorted deterministically. Output contains projected
-properties, geometry summaries, safe origin/path metadata, and the configured source revision or
-`null`. It never emits URL queries, credentials, hidden properties, response bodies, or absolute
-paths. PMTiles and authenticated provider adapters are not currently supported by this primitive.
-
-Deployment adapters can compile the same sources without writing them to disk:
-
-```ts
-import {compileTileflowIconPackages} from '@tileflow/dev/icons';
-
-const internalCatalog = artifacts.project;
-const result = await compileTileflowIconPackages(internalCatalog, {
-  cwd: process.cwd(),
-  target: 'hosted',
-});
-```
-
-Streets declares `[streetsIcons]` and keeps light/dark image-token targets in that one closure.
-Baedeker, Cívica, 1777, Siegfried, Soundings, and Blueprint declare only
-`[baedekerIcons]`, `[civicaIcons]`, `[map1777Icons]`, `[siegfriedIcons]`,
-`[soundingsIcons]`, and `[blueprintIcons]`, respectively. No official root composes another map's assets even though all
-use the semantic compiler ABI. Baedeker's directory contains eight original travel-atlas patterns;
-its browser-derived Mapterhorn contours use runtime terrain tiles and are not part of the icon
-package. Soundings owns twenty-seven original nautical symbols and
-patterns. Blueprint owns four technical blueprint patterns and one schematic POI node; its
-unbundled Mapterhorn contours remain runtime terrain, and its text uses the canonical Noto Sans
-glyph provider. An application map may inherit a root's exact array, replace it, clear it with `[]`,
-or compose it explicitly with a spread.
-`modules.poi.icons: false` or a disabled POI module suppresses POI icon layers without moving asset
-ownership into dev. POI density is the numeric producer threshold 1–5; it is not an asset-provider
-preset.
-
-The hosted target enforces repository containment, portable icon IDs, safe SVG
-references, deterministic ordering, and the public package limits. Package-owned directories are
-trusted only inside their declared owning package and are exempt from config working-tree
-containment. It returns deduplicated generated files plus a canonical manifest/content hash. Upload
-only those generated files: source icons and absolute paths remain local.
-
-The version-1 manifest includes `renderedIcons` in the exact sorted `iconNames` order. Each entry
-contains SHA-256 digests for the normalized 1x and 2x RGBA cell. The digest framing includes its
-density and dimensions, zeroes RGB only where alpha is zero, and excludes filenames/source bytes.
-The package content hash still covers the complete canonical manifest, including all four encoded
-file hashes. Consumers can therefore distinguish a visible per-icon change from an atlas-layout or
-encoding-only package change without receiving the original SVG/raster file.
-
-`compileTileflowIconPackages` retains the exact RGBA cells used to assemble each atlas, so its
-pixel digests describe delivered pixels rather than a second render. Hosted upload services must
-decode the submitted PNGs and reconstruct those digests independently; client-authored manifest
-analysis is not authoritative.
-
-Custom Node tooling can inspect the same local pipeline without walking or decoding source files a
-second time:
-
-```ts
-import {inspectTileflowIconCatalogs} from '@tileflow/dev/icons';
-
-const internalCatalog = artifacts.project;
-const inspection = await inspectTileflowIconCatalogs(internalCatalog, {
-  cwd: process.cwd(),
-  mapNames: ['madrid'],
-});
-```
-
-The result keeps one catalog per distinct ordered directory composition, the exact winning source
-for every final ID, explicit same-ID replacements, config-relative source metadata, exact atlas rectangles,
-both manifest pixel digests, and the shared compiled package. `icons: []` is represented as an
-absent catalog. This is a local-authoring integration surface: use the hosted compilation target
-separately for deployment compatibility, and project only the metadata needed by an external
-protocol rather than serializing generated byte arrays accidentally.
-
-This package is public, but it is an integration layer. Styling primitives live in
-`@tileflow/core`, official maps and their source assets live in `@tileflow/maps`, and React
-rendering lives in `@tileflow/react`.
-
-Docs: https://tileflow.dev/docs

package/docs/building-models.md

@@ -1,218 +0,0 @@
-# Prepare recolorable building models
-
-Custom buildings and landmarks use the same preparation path. Export uncompressed glTF 2.0
-binaries in metres, Y up, with the origin on the ground. The default scene's triangles and node
-transforms are read. Building preparation retains physical materials and embedded PNG/JPEG
-textures. Animations, skins and morph targets are not evaluated; export their static geometry.
-
-## Separate colour from architectural role
-
-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
-{
-  "name": "accent",
-  "extras": {
-    "tileflow": {
-      "lightingRole": "door"
-    }
-  },
-  "pbrMetallicRoughness": {
-    "baseColorFactor": [0.8, 0.8, 0.8, 1]
-  }
-}
-```
-
-This door can take the map's `accent` colour while receiving its `door` lighting profile. Accepted
-roles are `unclassified`, `wall`, `door`, `roof`, `window`, `lamp` and `logo`. A role describes
-geometry; it does not turn on light by itself. The map supplies emission through
-`buildings.threeDimensional.modelLighting`.
-
-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` |
-
-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 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 part and role:
-
-| Channel            | Inputs                                                                            |
-| ------------------ | --------------------------------------------------------------------------------- |
-| Base colour        | Linear `baseColorFactor`, linear `COLOR_0` RGB/RGBA, sRGB base-colour texture     |
-| Reflection         | `metallicFactor`, `roughnessFactor`, texture blue/green channels                  |
-| Surface normal     | Tangent-space normal texture and `scale`; tangent basis from geometry and UVs     |
-| Ambient visibility | Occlusion texture red channel and `strength`, multiplied by geometric visibility  |
-| Emission           | Linear `emissiveFactor`, sRGB emissive texture, `KHR_materials_emissive_strength` |
-| Coverage           | `OPAQUE`, `MASK` with `alphaCutoff`, or `BLEND`; `doubleSided`                    |
-| 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.
-Images must be embedded in buffer views or PNG/JPEG data URIs; preparation never fetches external
-images. Other image formats and physical-material extensions are not supported.
-
-Each level accepts at most 256 distinct materials, 32 textures, 4096 pixels per image dimension
-and 16,777,216 decoded image pixels in total. The complete prepared file remains limited to 16 MiB.
-Invalid references, missing UVs and image headers that disagree with their dimensions fail preparation.
-
-Without overrides, a physical model retains its authored material. `modelLighting` can tint and
-override roughness/metallicity by role. Explicit `modelColors` take precedence over role tints;
-textures and vertex colours still modulate the chosen colour. Keep vertex colours neutral when
-they should not affect recolouring.
-
-Colour and normal textures, metallic reflection and alpha coverage use the browser's physical
-model path. Ambient visibility never attenuates solar light or emission. Masked pixels also leave
-holes in dynamic solar shadows; blended surfaces cast an alpha-tested shadow at 0.5. Transparent
-material ranges draw back to front after opaque surfaces; intersecting transparent triangles are
-not sorted individually.
-
-## Explicit area emitters
-
-A `door` role lights the surface. To project its spill, declare a rectangle in
-`node.extras.tileflow.emitters`. This glTF fragment uses node-local metres and Y up:
-
-```json
-{
-  "extras": {
-    "tileflow": {
-      "emitters": [
-        {
-          "start": [-1, 0, 0],
-          "end": [1, 0, 0],
-          "height": 3,
-          "depth": 0.2,
-          "role": "door",
-          "part": "accent"
-        }
-      ]
-    }
-  }
-}
-```
-
-`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, 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
-other meshes. It follows the model's visibility and theme; zero emission removes it.
-
-## Ambient visibility
-
-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
-ambient contribution; solar visibility still comes from the dynamic shadow map.
-
-`threeDimensional.modelOcclusion` controls strength from zero to one and defaults to `0.75`.
-`threeDimensional.occlusion: false` also disables model ambient occlusion. Changing these
-runtime controls does not prepare the geometry again.
-
-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
-
-Use `<id>.glb`, optionally `<id>.mid.glb` and `<id>.far.glb`. A mesh whose material is `footprint`
-defines the area replaced by the model and is not drawn. Otherwise preparation derives a footprint.
-See the [Core building guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/buildings-3d.md)
-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    | 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: 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 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, 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

@@ -1,92 +0,0 @@
-# Layers inspection
-
-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. 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
-Layers and **Rules**, the first detail tab, opens with values evaluated for the picked feature. The
-picked feature is a snapshot from that click; changing the layer or artifact/scene revision clears it.
-Inspect no longer has a separate top-level tab. Legacy `tab=inspect` links resolve to Layers.
-
-Enable **Visible only** beside the organization buttons to hide hidden/out-of-zoom layers and vector
-layers with no rendered features in the current viewport. The filter combines with search and both
-organization modes, and refreshes after camera movement, style changes and tile loading. One viewport
-query serves the whole list after a 250 ms pause. During movement the last result remains stable;
-failed queries do not classify layers as empty. Custom, raster and background layers remain listed
-when their visibility cannot be measured; explicit hidden runtime state is excluded. This is a
-rendered-feature filter, not a measurement of final pixels, transparency or occlusion.
-
-Search by ID, semantic target, module, type, source or source-layer. Click anywhere on a row, or use
-Up/Down and Home/End from a focused row. Selection stays in Layers and is retained in the `layer` URL
-parameter. If a selected ID disappears, its detail shows that absence and keeps the ID for when it
-returns. The Layers tab remains in the existing `tab=layers` parameter.
-
-## Read the evidence
-
-Open **Diagnosis** in the selected layer's detail tabs. With a picked feature or a
-Data sample, it explains the filter result and any evaluated zero-size or zero-opacity components.
-A zero component is not proof that the whole layer is invisible. Diagnostics findings can open a
-specific paint, layout or filter declaration directly in Rules, highlighting its row.
-
-- **Diagnosis** reports presence, declared visibility, the inclusive minimum/exclusive maximum zoom
-  range, source loading, shared source tiles and viewport-query observations. Pixel visibility,
-  occlusion, transparency and depth are explicitly unmeasured. Later draw calls do not necessarily
-  cover every earlier layer. Runtime 3D controllers report only the state and statistics they expose.
-- **Rules** shows paint and layout values inline, without expandable rows, alongside their zoom,
-  feature, feature-state, global-state and image dependencies. Values use the current zoom and the
-  picked feature or selected data sample. Edit a value and press Enter or leave the field to preview
-  it; color pickers update live while open. Enumerations and booleans use selectors. Invalid values
-  show an error and leave the map unchanged. Edits override the entire physical layer across zooms,
-  including when a picked feature supplied the evaluated value. Each modified rule has a reset
-  button that restores its original expression or renderer default. Paint checkboxes temporarily
-  remove a declaration from the renderer so its default applies. The disabled row stays visible and
-  crossed out, showing its retained value at the current view; re-enabling restores the exact saved
-  expression or override. Toggles share edit history and appear in copied context. Implicit defaults
-  cannot be disabled; edit one to create an explicit rule first. **Undo** and **Redo** beside the
-  three-dot menu share the temporary style history. **Reset all changes** in that menu restores
-  temporary style and geometry edits and clears their history. Reload clears temporary edits;
-  config, source data and build artifacts stay unchanged. Filters remain read-only. Copy context includes the raw rules and temporary edits.
-  Evaluation does not reproduce placement, transitions or final pixel colors.
-- **Data** queries only the selected layer after the viewport settles. At most 80 returned fragments
-  are retained; the renderer's query itself may return more. Fragments can duplicate logical features
-  across tile boundaries or world copies. Zero results are not proof that a filter excluded all data.
-  Unsupported custom/raster/background queries are unavailable, not zero. Choose an actual sample
-  to inspect its properties, or use **Use for rules** to evaluate that fragment in Rules. Inline
-  source data is excluded from source details.
-- **Origin** preserves sidecar owners, targets, slots and operations. Semantic module paths do not
-  establish exact source-file or line provenance; token paths appear only if explicitly supplied.
-
-## Follow a layer through the map
-
-Hover or keyboard-focus a layer row to highlight its sampled geometry live in the current map view.
-Click a row to keep that layer highlighted. Hovering another row temporarily replaces the highlight;
-leaving restores the clicked layer, or clears the preview when no row was clicked. Closing the panel
-clears both previews. Hover and click work with the element-picker mode on or off. The camera stays unchanged. The preview refreshes when map movement settles or source tiles
-change, even when the hovered layer differs from the selected layer. Hover is coalesced over 80 ms;
-queries are cached for the current view. There is no separate **Highlight on map** button.
-
-Overlays retain at most 30 fragments and 25,000 vertices. They use separate scratch sources and never
-change original paint, layout, source data or feature state. A highlight outlines queried geometry;
-it is not a reconstruction of glyphs, symbols or 3D meshes. Hidden, out-of-zoom, custom and raster
-layers without queryable rendered geometry report that limitation instead of moving the camera.
-
-**Tiles** inspects tiles grouped by source. Tile costs belong to the shared source, not to a
-single style layer. Sprite and font links in Rules open Assets. Other inspection tabs remain usable
-while compilation or tile loading continues; obsolete scheduled measurements are discarded.
-
-## Give an agent context
-
-**Copy context** opens a frozen preview in Markdown or JSON. Add an optional investigation question,
-then copy it. The packet includes the selected ID, map/theme, generation, scene revision, camera,
-viewport, rules, provenance, diagnostic evidence, source, runtime state, recent changes and temporary
-edits. It retains at most eight feature property samples, excludes their geometries and inline source
-data, removes credentials and query strings from source URLs, and reports projection omissions.
-Nothing is sent to an agent automatically.
-
-While Layers is active, the same observation replaces stale feature selection in the local
-`tileflow inspect session --url http://127.0.0.1:3333 --json` context. The CLI applies an additional
-bounded projection and reports omitted paths. Temporary edits are observations; capture commands
-still use the compiled map rather than reproducing scratch edits.