@tileflow/dev 0.1.0-alpha.32 → 0.1.0-alpha.34

package/docs/beacon-map-audits.md

@@ -1,4 +1,8 @@
-# Beacon map audits
+# 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
@@ -20,8 +24,10 @@ takes 45–60 seconds. Slow loading can exhaust the budget: remaining views are
 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 and
-readiness for each view. A p95 requires at least 30 intervals; coverage flags fewer than 60 settled
+**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
@@ -29,7 +35,7 @@ scheduling and other work on the machine, rather than isolated GPU execution tim
 
 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 palette and
+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.
@@ -54,7 +60,7 @@ A map replacement invalidates the run. Reports and preview changes stay local an
   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, minimum evaluated size, approximate density, halos, configured line curvature and
+  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
@@ -63,7 +69,7 @@ A map replacement invalidates the run. Reports and preview changes stay local an
   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, adjacent-zoom size changes, unchanged eligible-layer counts and sampled fill coverage.
+  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
@@ -71,17 +77,48 @@ A map replacement invalidates the run. Reports and preview changes stay local an
   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 per layer. Geometry is discarded after
+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; an unmeasured category shows **—**. For numeric
+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. Diagnostic findings may use
-review scores rather than numeric budgets. A high score does not establish global map quality.
+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
@@ -89,12 +126,18 @@ layer IDs, camera context, measured values, coverage limits and suggested invest
 
 ## Reproducible reports and future automation
 
-Reports use `version: 3` and identify the deterministic tour as `protocol: "active-tour-v1"`.
+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, readiness and observed network transfer. `plannedViews` and
+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. There is no CI runner or GitHub integration in this feature.
+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

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

@@ -40,13 +40,12 @@ const result = await compileTileflowIconPackages(internalCatalog, {
 ```
 
 Streets declares `[streetsIcons]` and keeps light/dark image-token targets in that one closure.
-Baedeker, Cívica, Ferraris, Härad, Siegfried, Soundings, and Blueprint declare only
-`[baedekerIcons]`, `[civicaIcons]`, `[ferrarisIcons]`, `[haradIcons]`, `[siegfriedIcons]`,
+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. Härad's directory contains nine original Tileflow patterns inspired by Lantmäteriet's CC0
-Häradsekonomiska kartan series from 1859–1934. Soundings owns ten original nautical symbols and
+package. Soundings owns eleven 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 `[]`,

package/docs/building-models.md

@@ -0,0 +1,179 @@
+# 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
+
+Material names select a palette slot: `surface`, `secondary`, `glass`, `accent` or `roof`.
+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`.
+
+Legacy models without an explicit role use these defaults:
+
+| Palette slot                     | Lighting role |
+| -------------------------------- | ------------- |
+| `surface`, `secondary`, `accent` | `wall`        |
+| `glass`                          | `window`      |
+| `roof`                           | `roof`        |
+
+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
+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:
+
+| 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.
+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
+supplies the fallback palette 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 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.
+
+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 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.
+
+## 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    | 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.
+
+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.
+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
+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
+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

@@ -26,6 +26,11 @@ 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
@@ -68,7 +73,7 @@ change original paint, layout, source data or feature state. A highlight outline
 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.
 
-**Source tiles** opens Network filtered by source. Tile costs belong to the shared source, not to a
+**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.
 

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

@@ -3,7 +3,7 @@
 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 Beacon. Camera controls
+session by default. A developer-tools 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
@@ -41,7 +41,7 @@ the fixed scene viewport by default.
 Each side handler retains ownership of its styles, fonts, sprites, events, diagnostics, and
 last-known-good artifact generation. The comparison router owns the shell, its bundled UI fonts and
 strict dispatch to disjoint same-origin route prefixes. An optional `workbench: {url, handle}`
-adapter enables palette selection and browser context. Existing CLI capture-record and comparison
+adapter enables theme selection and browser context. Existing CLI capture-record and comparison
 APIs remain separate from this interface. Custom servers that omit the adapter retain inspection,
 zoom-curve sampling and the sprite atlas. Explicit two-map server configurations retain synchronized
 cameras and URL-driven side-by-side/split/overlay/blink layouts without comparison controls.
@@ -116,7 +116,7 @@ traffic or other HTTP resources. Sprite and font sources remain in **Assets**.
 ### Assets and debug overlays
 
 **Assets** separates Icons, 3D models and Fonts. Icons lists registered images, including runtime
-additions, with lazy thumbnails and searchable IDs. Palette and time filters load the actual
+additions, with lazy thumbnails and searchable IDs. Theme and time-of-day filters load the actual
 registered theme atlases; the selected icon's sidebar compares its day/night variants and links to
 consuming layers. Missing variants are marked, never synthesized from a naming convention.
 
@@ -127,4 +127,4 @@ provider and shows observed glyph ranges and consuming layers. Pending requests
 when leaving the panel; unavailable sources do not silently use a fallback font.
 
 **Debug** offers collision boxes, overdraw with a color legend, tile boundaries and real pixel-ratio
-controls. **Beacon** provides controlled map audits; see [Beacon map audits](./beacon-map-audits.md).
+controls. **Diagnostics** lists design findings and optional drawing-cost observations; see [Map design diagnostics](./map-design-diagnostics.md).

package/docs/map-design-diagnostics.md

@@ -0,0 +1,76 @@
+# Map design diagnostics
+
+Open **Diagnostics** in Map DevTools 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.
+
+## Check the map
+
+Style observations refresh after changes settle. **Check view** explicitly collects samples from
+the current map and briefly profiles drawing work. It does not navigate to other cities, change the
+camera, compile themes or save edits. Changing the map or leaving the panel cancels pending work.
+Expensive renderer observations are not repeated continuously while editing colors or dragging.
+
+The initial detectors cover invalid style rules, broken references and zoom ranges, unresolved
+icons, verifiable text contrast, large layer stacks, potentially repeated rules and drawing work.
+Findings group affected layers and keep bounded examples. A missing image must remain unresolved
+after loading; images with a working fallback are not missing resources. An empty viewport or a
+layer outside its zoom range does not by itself create a global problem.
+
+Text contrast is checked only where the evaluated text and opaque halo make the color pair
+verifiable. This is not a measurement of all pixels behind a label or certification that a map is
+readable. Unavailable evaluation context does not become a passing observation. Size thresholds,
+absence of halos and ordinary collision rejection do not establish design defects.
+
+Performance findings are review indications. A style layer, a queried feature, a draw call and an
+overdraw pass measure different things. Layer stacks are grouped by compiler provenance when it is
+available; unknown ownership is not inferred from names. Equivalent drawing rules may be deliberate
+casings, shadows or blending, so they are never automatically removed. Counts and short CPU samples
+do not attribute GPU cost to an individual layer or establish a universal performance grade.
+
+Native overdraw is observed only when the renderer and scene permit a meaningful measurement.
+Custom rendering, terrain, sky, globe projection or active debug modes can make it unavailable. The native sample saturates
+at eight passes, so an eight-pass observation is a lower bound. Sampling temporarily enables the
+native debug rendering and restores it; open **Debug** explicitly to keep an overlay visible.
+
+Drawing-work sampling requests repaints for approximately 650 ms and requires at least ten complete
+frames. Compatible native overdraw sampling has a separate two-second limit. A median of at least
+1,000 draw submissions, or at least 25% of sampled pixels reaching eight passes, creates a review
+finding. These are disclosed review triggers, not universal limits. Label evaluation and retained
+examples are capped; reading the style and querying rendered features still depend on map size.
+Detailed rule checks inspect at most 2,000 non-internal layers, while stack counts include the
+whole style. Contrast sampling retains up to 5,000 symbol candidates, evaluates at most 200 of
+them and keeps up to 40 eligible examples. Coverage limits remain available in the copied report.
+
+## Investigate a finding
+
+Expand a row to read its evidence and limitations. **Open rule** selects the layer and focuses the
+related paint, layout or filter declaration. **Show on map** uses the finding's observed context;
+asset and overdraw actions open the corresponding inspection tools. Available actions depend on
+the evidence. Preview changes remain temporary and share Undo/Redo and Reset all changes.
+
+Findings retain the map revision and camera in which they were observed. Moving away is not proof
+that a problem was fixed. Old view evidence is marked stale until checked again. Local dismissals
+apply to a case fingerprint; changing the relevant evidence makes it reviewable again. Incomplete
+checks and missing renderer capabilities are included in the copied report.
+
+**Copy findings** and each finding's copy action include structured evidence, conditions and
+temporary edits. Context is sanitized, bounded and reports omissions. Nothing is sent to an agent
+automatically. The output is diagnostic evidence, not a benchmark or release certification.
+
+## Explain a layer's visibility
+
+Select a layer in **Layers**, then open **Diagnosis**. It shows declared visibility,
+zoom eligibility, source state and viewport-query observations. With an actual selected feature it
+also evaluates its filter and relevant zero-size or zero-opacity rules. A zero component does not
+prove the whole layer is invisible: a circle stroke or another symbol component may still draw.
+Unknown expression context and geometry-dependent filters remain unavailable. Query matches do
+not establish final pixel visibility, depth or occlusion.
+
+## Compatibility
+
+The tab persists as `tab=diagnostics`. Previous `tab=beacon` links open the new panel. The former
+Beacon scoring and tour interface is retired; its historical report scores are not comparable to
+Diagnostics findings. Network infrastructure, platform regressions and broad map quality remain
+separate concerns from these author-facing checks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/dev",
-  "version": "0.1.0-alpha.32",
+  "version": "0.1.0-alpha.34",
   "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.35 <0.1.0-beta.0",
+    "@tileflow/core": ">=0.1.0-alpha.37 <0.1.0-beta.0",
     "chokidar": "4.0.3",
     "fflate": "0.8.3",
     "fontkit": "2.0.4",
@@ -97,7 +97,7 @@
     "three": "0.185.1"
   },
   "devDependencies": {
-    "@tileflow/maps": "0.1.0-alpha.9"
+    "@tileflow/maps": "0.1.0-alpha.11"
   },
   "optionalDependencies": {
     "sharp": "0.35.5"