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

package/docs/beacon-map-audits.md

@@ -0,0 +1,102 @@
+# Beacon map audits
+
+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 and
+readiness for each view. 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 palette 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, minimum evaluated size, 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, adjacent-zoom size changes, 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 per layer. 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
+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.
+
+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: 3` 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
+`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.
+
+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/layers-inspection.md

@@ -0,0 +1,87 @@
+# 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
+
+- **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.
+
+**Source tiles** opens Network filtered 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 Beacon. 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 palette 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,188 +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.
 
-For Streets styles whose vegetation layer declares `tileflow:vegetation-mode = 3d`, the built-in
-preview uses the same portable circle fallback as capture and the published framework adapters by
-default. This makes an ordinary `tileflow preview` session WYSIWYG with production and visual
-baselines. Append `?treeRenderer=simple` or `?treeRenderer=complex` to opt into the experimental,
-preview-only instanced renderer described below; that explicit mode is not capture evidence.
-
-The experimental renderer uses source height and crown diameter when present, distinguishes palms,
-columnar cypresses, conifers, and three broadleaf silhouettes from the bound botanical fields, and
-falls back to deterministic broadleaf variety and dimensions when tags are missing. Bark color,
-crown palettes, height scale, and crown scale come from `vegetation.threeDimensional`; the preview
-does not maintain a second hard-coded appearance contract. During camera
-gestures the existing 3D batch remains visible while native circles cover newly arriving tiles; the
-batch refreshes when movement ends without waiting for the whole map to become idle. Source-tile
-events are rate-limited and unchanged instance selections do not upload new GPU buffers. The
-preview caps one view at 3,000 trees and uses zoom-dependent density. Both detailed modes use thin,
-tapered trunks, branches that enter the crown, softly shaded overlapping ellipsoids, and stable
-per-tree scale and rotation. `simple` reduces lobe and segment counts; `complex` keeps the complete
-round, open, avenue, pine, cypress, and palm silhouettes. Each archetype remains fused into one
-reusable geometry and every complete tree remains
-one GPU instance, so the additional detail introduces no extra draw calls. The experimental
-renderer defaults to its WebGL2 backend, which
-draws those instances directly without a Three.js scene traversal; append `&treeBackend=three` for
-the compatibility backend. Use `?treeRenderer=circle`, `?treeRenderer=simple`, or
-`?treeRenderer=complex&treeBenchmark=1` to compare identical scenes; the benchmark reports frame
-p95, query, selection, build and render time, draw calls, and triangle count in the tree status badge.
-Visible candidates come from MapLibre's worker-built tile index instead of a second copy of the
-vector source. Terrain height is sampled on a fixed 5-by-5 viewport grid and interpolated per tree,
-avoiding hundreds of synchronous terrain queries when a new batch first appears.
-The separate `TREES ON/OFF` control sits below the building `3D ON/OFF` control and pauses tree
-refresh work while disabled. Both choices survive reloads and shared links through the
-`buildings3d=on|off` and `trees3d=on|off` URL parameters.
-
-Detailed trees retain the compiler's scene order: they render above road and pedestrian surfaces,
-ordinary building geometry, and detailed landmark models. Map labels and other annotations remain
-above the physical scene, while road names and route references stay attached to the carriageway
-below buildings and trees.
-
-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. Palette and time 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. **Beacon** provides controlled map audits; see [Beacon map audits](./beacon-map-audits.md).

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/dev",
-  "version": "0.1.0-alpha.30",
+  "version": "0.1.0-alpha.32",
   "license": "Apache-2.0",
   "description": "Node development utilities for Tileflow configs and builds.",
   "type": "module",
@@ -26,6 +26,7 @@
   },
   "files": [
     "dist",
+    "ui-fonts",
     "docs",
     "THIRD_PARTY_NOTICES.md",
     "LICENSE"
@@ -82,26 +83,27 @@
   },
   "dependencies": {
     "@mapbox/vector-tile": "3.0.0",
-    "@maplibre/maplibre-gl-style-spec": "24.8.5",
-    "@tileflow/core": ">=0.1.0-alpha.32 <0.1.0-beta.0",
+    "@maplibre/maplibre-gl-style-spec": "26.4.4",
+    "@tileflow/core": ">=0.1.0-alpha.35 <0.1.0-beta.0",
     "chokidar": "4.0.3",
     "fflate": "0.8.3",
     "fontkit": "2.0.4",
     "jiti": "^2.7.0",
     "maplibre-gl": "6.13.0",
+    "meshoptimizer": "1.3.0",
     "pbf": "5.1.2",
     "pmtiles": "4.5.0",
     "saxes": "6.0.0",
     "three": "0.185.1"
   },
   "devDependencies": {
-    "@tileflow/maps": "0.1.0-alpha.8"
+    "@tileflow/maps": "0.1.0-alpha.9"
   },
   "optionalDependencies": {
     "sharp": "0.35.5"
   },
   "scripts": {
-    "build": "tsup src/artifacts.ts src/config.ts src/fonts.ts src/icons.ts src/inspect.ts src/preview.ts src/server.ts src/tilesets.ts src/validation.ts --format esm --dts --clean --platform node --external sharp",
+    "build": "tsup src/artifacts.ts src/config.ts src/fonts.ts src/icons.ts src/inspect.ts src/preview.ts src/server.ts src/tilesets.ts src/validation.ts --format esm --dts --clean --platform node --external sharp && tsup --config tsup.devtools.config.ts",
     "test": "tsx --test test/*.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "lint": "tsc -p tsconfig.json --noEmit",