@tileflow/dev 0.1.0-alpha.31 → 0.1.0-alpha.33

package/docs/beacon-map-audits.md

@@ -0,0 +1,145 @@
+# 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-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 ten 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/layers-inspection.md

@@ -0,0 +1,92 @@
+# 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. DevTools 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.

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

@@ -1,10 +1,17 @@
-# Local comparison workbench and compiler inspection
+# Map DevTools 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 exposes the complete authoring surface through `tileflow preview --against-map ...` or
-`--against-config ...`. Custom local servers can compose the same shell around two existing dev
-handlers:
+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
+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**
+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
+can compose the same shell around existing dev handlers; omit `right` for a single-map session:
 
 ```ts
 import {createTileflowComparisonRequestHandler} from '@tileflow/dev/server';
@@ -27,11 +34,22 @@ const fetch = createTileflowComparisonRequestHandler({
 });
 ```
 
+Set `fitViewport: true` on each dev handler embedded in a resizable Map DevTools 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.
+
 Each side handler retains ownership of its styles, fonts, sprites, events, diagnostics, and
-last-known-good artifact generation. The comparison router only owns the root HTML and strict
-dispatch to two disjoint same-origin route prefixes. Its synchronized camera, URL state,
-side-by-side/split/overlay/blink modes, rendered-feature inspector, zoom-curve sampling, sprite
-atlas, and scene/capture-command copying require no hosted service.
+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 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.
+
+See the [human/agent workflow](https://github.com/tileflow/tileflow-sdk/blob/main/packages/cli/docs/map-authoring.md#work-with-a-person-and-an-agent)
+for retained evidence, context bounds and `inspect session`. Browser context reports the observed
+camera and viewport; capture commands render compiled source without temporary preview edits. The rendered feature summary shows available semantic paths and
+keeps raw feature data in a disclosure. It does not infer exact source lines or token ownership.
 
 Set `inspection: true` on `createTileflowBuildArtifacts` or
 `createTileflowArtifactSession` to compute `artifacts.styleInspections[map][theme]`. A dev handler
@@ -62,166 +80,51 @@ prepared local-font bundle before authentication until managed font storage is a
 map that declares `glyphs` replaces the inherited local provider atomically; the URL-backed map is
 complete as declared and independent of its World selection.
 
-With both controls off, the built-in preview draws the style as compiled, as Capture and the
-published framework adapters draw it: flat trees, building layers marked for the 3D control left
-hidden, and no street lights. This keeps an ordinary `tileflow preview` session WYSIWYG with
-production and visual baselines.
-
-The `3D ON/OFF` and `TREES ON/OFF` controls mount Core's 3D layers as an application does, from
-the description the compiled style publishes. When the style describes 3D buildings
-(`tileflow:buildings`), `3D ON` raises them with `createTileflowBuildings3D` in place of the
-compiled extrusion and lights the streets with `createTileflowStreetLights` where the style
-describes them. When it describes 3D trees (`tileflow:vegetation`), `TREES ON` stands them with
-`createTileflowTrees3D`, which hides the style's flat trees while they stand. Every look the
-preview shows comes from the map's modules; the preview holds no appearance of its own, and the
-theme on screen supplies the sun. Neither mode is capture evidence. Both choices survive reloads
-and shared links through the `buildings3d=on|off` and `trees3d=on|off` URL parameters.
-
-The same control toggles any compiled layer whose metadata contains
-`tileflow:3d-toggle = building`. It switches the building volumes independently from the camera,
-so enabling 3D never changes the pitch and users remain free to tilt the map with pointer controls.
-
-### Detailed landmark models
-
-A hidden style layer can opt the Streets preview into detailed GLB landmarks by setting
-`tileflow:landmark-manifest-url` in its metadata. The bounded version-2 manifest indexes GLB entries
-inside one or more PMTiles archives and is fetched only when the 3D building control is enabled near
-the landmark runtime zoom. Archive URLs may be absolute or relative to the manifest URL.
-
-```json
-{
-  "schemaVersion": 2,
-  "id": "madrid-landmarks-2026-08-19",
-  "minzoom": 16,
-  "maximumVisibleModels": 8,
-  "maximumCachedModels": 16,
-  "archives": [
-    {
-      "id": "madrid-v1",
-      "url": "./madrid-landmarks-v1.pmtiles",
-      "bytes": 14832912,
-      "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
-    }
-  ],
-  "landmarks": [
-    {
-      "id": "palacio-cibeles",
-      "center": [-3.6921, 40.4193],
-      "bounds": [-3.693, 40.4186, -3.6912, 40.42],
-      "priority": 100,
-      "models": [
-        {
-          "minzoom": 16,
-          "archiveId": "madrid-v1",
-          "z": 0,
-          "x": 0,
-          "y": 0,
-          "bytes": 481024,
-          "sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
-          "axisConvention": "EUN_Y_UP"
-        },
-        {
-          "minzoom": 18,
-          "archiveId": "madrid-v1",
-          "z": 1,
-          "x": 0,
-          "y": 0,
-          "bytes": 1276416,
-          "sha256": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
-          "axisConvention": "EUN_Y_UP"
-        }
-      ]
-    }
-  ]
-}
-```
-
-`maximumVisibleModels` is bounded to 1–64. `maximumCachedModels` defaults to twice that value,
-must be at least the visible limit, and is bounded to 128. Higher `priority` values win when more
-landmarks intersect the viewport than can be shown. `models[0]` is the base LOD and must start at the
-manifest `minzoom`; later entries replace it at their distinct `minzoom`. The parser bounds manifest,
-archive, landmark, model and GLB-entry sizes, rejects credential-bearing or non-HTTP archive URLs,
-and verifies each extracted entry's declared byte length and SHA-256 before parsing it.
-
-The preview starts the Three.js runtime and manifest request together one zoom before the landmark
-layer becomes visible. A landmark entering directly at a close zoom always displays its base LOD
-first and upgrades in place. Nearby base LODs are warmed in the parsed-model cache. Style layers
-marked with `tileflow:landmark-fallback = true` remain visible until the corresponding active GLB is
-ready, so a cold request never leaves an empty building volume.
-
-Embedded Streets previews also accept a same-origin parent command without reloading the document:
-
-```js
-iframe.contentWindow.postMessage(
-  {
-    type: 'tileflow:set-map-state',
-    schemaVersion: 1,
-    state: {
-      center: [-3.688344, 40.453053],
-      zoom: 17.75,
-      bearing: -24,
-      pitch: 58,
-      buildings3d: true,
-      trees3d: false,
-      visibleLayerGroups: ['labels', 'roads', 'buildings', 'landuse', 'water'],
-    },
-  },
-  location.origin,
-);
-```
-
-The command is applied atomically only for the embedding parent, with exact same-origin and numeric
-range checks. `visibleLayerGroups` is optional and accepts only `labels`, `pois`, `roads`, `transit`,
-`buildings`, `landuse`, and `water`; omitted groups are hidden while base background and attribution
-remain. Camera and toggle state continue to be written to the preview URL after application.
-
-GLB base colors, textures, emissive values, metalness, and roughness are authoritative and are not
-rewritten by the preview. Models outside the active selection remain hidden in a least-recently-used
-cache; leaving the cache disposes their geometry, materials, and textures.
-
-The vector building represented by a detailed model must carry `hide_3d = true`. The ordinary
-building extrusion and both screen-space shadow passes filter on that field, preventing the coarse
-volume from intersecting the GLB while retaining the flat footprint below it. This flag belongs in
-the vector-tile dataset; the landmark endpoint cannot substitute for it. Version model and GLB URLs
-so they can be served with immutable caching. Cross-origin endpoints must allow credentialed GETs
-because the development renderer requests the manifest and models with credentials.
-
-If a map uses `icons: ['./icons/brand']`, build artifacts include the generated MapLibre
-`sprite.json`, `sprite.png`, `sprite@2x.json`, and `sprite@2x.png` beside its style. Ordinary sources
-are normalized into 24 px icon cells. A source named `<id>.pattern.svg` (or another supported raster
-format with the same marker) instead keeps its intrinsic dimensions and is published as `<id>`.
-This provides calibrated, non-square textures for line and fill patterns while the runtime still
-consumes only the generated PNG sprite. Pattern widths must be a power of two from 2 through 512
-pixels, matching MapLibre's seamless line-pattern contract.
-
-`icons` is one ordered array. Omitting it inherits the parent's exact array, declaring it replaces
-the array atomically, and `[]` means no icons. Use a spread to preserve imported directories while
-adding or replacing files:
-
-```ts
-import {defineMap} from '@tileflow/core';
-import {streets} from '@tileflow/maps';
-
-export default defineMap({
-  id: 'brand-map',
-  version: 1,
-  extends: streets,
-  icons: [...streets.icons, './icons/brand'],
-});
-```
-
-Directories apply left to right. `<id>.<ext>` publishes an icon as `<id>`;
-`<id>.pattern.<ext>` publishes the intrinsic-size pattern as `<id>`. The published ID must already
-be canonical lower-kebab-case. A later file replaces an earlier file only for the same exact ID;
-case-only collisions fail. Package maps export `streetsIcons`, `baedekerIcons`, `civicaIcons`,
-`ferrarisIcons`, `haradIcons`, `siegfriedIcons`, `soundingsIcons`, `blueprintIcons` directory descriptors from
-`@tileflow/maps`. Baedeker, Cívica, and Siegfried also export
-`baedekerFonts`, `civicaFonts`, and `siegfriedFonts`. Preparation
-resolves package descriptors inside their owning package, checks real-path containment, and
-compiles them through the same pipeline as a config-relative directory. There are no
-built-in/source/sprite selectors, mappings, icon-specific inheritance, or compatibility aliases.
-
-Local directories resolve from the directory containing the selected `tileflow.config.ts`, while
-the workspace `cwd` remains their containment boundary. Canonical local syntax starts with `./` or
-one or more leading `../` segments and then uses only non-empty segments other than `.` or `..`;
-trailing or repeated slashes, backslashes, controls, and paths longer than 512 characters fail.
+### Pick an element in Layers
+
+Press **I** or the element-picker icon, hover for a layer/type/ID hint, then click the map.
+The clicked element selects its physical layer in **Layers** and opens **Rules**, the first detail tab.
+Expression values use that picked feature, rather than an arbitrary viewport sample. **Data** shows
+its properties and additional viewport samples; **Use for rules** chooses a different sample.
+There is no separate Inspect tab. Legacy `tab=inspect` links open Layers.
+
+Selecting another layer clears the picked-feature context. Compiler and scene revisions invalidate
+old feature snapshots. The renderer's layer ID remains selected across reloads through the `layer`
+URL parameter; missing IDs are reported explicitly. Rules expose inline temporary paint/layout
+editors for the entire physical layer, with per-rule reset and shared undo history. Preview edits do
+not write config, source data or build artifacts. See [Layers inspection](./layers-inspection.md) for diagnostic limits,
+map highlighting, provenance and agent context.
+
+### Tiles
+
+**Tiles** shows in-view resident tiles in a spatial grid and source-grouped list, with canonical
+`z/x/y`, display zoom, state and raw tile bytes where available. Filter by source or coordinates.
+Select a tile to outline its bounds and inspect **Source layers**, **Features** and **Info**.
+Source-layer rows link to consuming style layers. Features are paginated in groups of 50 and can
+be copied as real GeoJSON. Counts describe tile fragments, including buffer geometry, rather than
+unique objects across tiles. **Show on map** fits the selected bounds.
+
+Raster DEM tiles show decoded grid dimensions and elevation statistics. Raster imagery has no
+vector features. Eviction, unavailable internals and unsupported MLT decoding are reported explicitly.
+Inspection decodes resident MVT buffers on demand without requesting tiles.
+
+The view reads the pinned MapLibre renderer's tile managers through an isolated adapter. A resident
+tile can come from cache and need not have a new HTTP request. Unsupported renderer internals
+produce an unavailable state. Network does not list application scripts, development-server
+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. 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.
+
+3D models previews bounded samples of the actual loaded building and vegetation meshes. Counts,
+bytes, LODs and available instance counts describe controller data. The wire geometry preview is
+not the map's lighting renderer. Fonts renders editable specimens from the actual font or glyph
+provider and shows observed glyph ranges and consuming layers. Pending requests are cancelled
+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. **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/docs/native-artifacts.md

@@ -202,7 +202,7 @@ pnpm exec tsx scripts/native-lowering-audit.ts > native-lowering-audit.json
 ```
 
 This diagnostic report compiles the unchanged full Streets family through the web preparation
-path, then measures the native representation for **both** dark and light before applying output
+path, then measures the native representation for **all twelve** themes before applying output
 budget assertions. It writes no native artifact generation and is not a compatibility verdict.
 Each theme includes layer counts, visited JSON nodes, UTF-8 bytes and maximum depth before/after;
 every transformed layer is listed with its ID, physical span, branch count and zoom intervals,
@@ -214,7 +214,7 @@ cap/dash decisions. They identify whether predicate expansion or repetition of o
 dominates; they are not an additive byte decomposition. The counters include array keys, matching
 the profile's existing node convention. Retain the report with the checkout SHA. An over-budget
 result must not be treated as a successful native build or fixed by dropping layers or weakening
-validation. The test suite prints the two-theme size summary even when a budget assertion fails.
+validation. The test suite prints the full theme size summary even when a budget assertion fails.
 
 ## Prepare Streets for a directed native check
 
@@ -251,7 +251,7 @@ actually contains features for the transformed layers listed in
 `/tmp/native-lowering-audit.json`. Use the audit's exact physical IDs, source layers, branch counts
 and zoom intervals rather than assuming that a map location exercises every branch.
 
-Check both themes at the same center, viewport, pitch 0 and bearing 0. Exercise at least one cap
+Check all themes at the same center, viewport, pitch 0 and bearing 0. Exercise at least one cap
 partition, one dashed/solid partition and an overlap between simultaneously active branches. Pan
 slightly and inspect just below/at/above the relevant audit zoom cuts (for example 15.99/16/16.01
 when a selected interval changes at 16). Check that caps and dash patterns are visible, layers do