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

package/docs/building-models.md

@@ -1,179 +0,0 @@
-# Prepare recolorable building models
-
-Custom buildings and landmarks use the same preparation path. Export uncompressed glTF 2.0
-binaries in metres, Y up, with the origin on the ground. The default scene's triangles and node
-transforms are read. Building preparation retains physical materials and embedded PNG/JPEG
-textures. Animations, skins and morph targets are not evaluated; export their static geometry.
-
-## Separate colour from architectural role
-
-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

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

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

@@ -1,130 +0,0 @@
-# Inspector and compiler inspection
-
-Start with the [@tileflow/dev guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/README.md) for installation and a complete first example.
-
-The CLI opens Inspector through `tileflow preview`. It uses one map and one watched artifact
-session by default. The panel groups Map, Layers, Tiles, Assets, Debug and Diagnostics. Camera controls
-occupy a separate row below the navigation. Use the three-dot menu to dock left, right or below
-the map and choose System, Light or Dark appearance. Drag the divider to resize it; focused dividers
-also support arrow keys. Dock position and dimensions persist locally. Layer observations and highlights stay local to the preview. The map fills the remaining
-workspace without brand headers or map-status badges. Closing the panel leaves a small **Inspector**
-button to reopen it; capture and comparison controls are absent from the interface.
-
-Add `--against-map ...` or `--against-config ...` for synchronized comparison. Custom local servers
-can compose the same shell around existing dev handlers; omit `right` for a single-map session:
-
-```ts
-import {createTileflowComparisonRequestHandler} from '@tileflow/dev/server';
-
-const fetch = createTileflowComparisonRequestHandler({
-  left: {
-    basePath: '/left',
-    handler: leftHandler,
-    label: 'candidate / light',
-    previewUrl: '/left/',
-    sidecarUrl: '/left/__inspection/candidate/light.json',
-  },
-  right: {
-    basePath: '/right',
-    handler: rightHandler,
-    label: 'reference / light',
-    previewUrl: '/right/',
-    sidecarUrl: '/right/__inspection/reference/light.json',
-  },
-});
-```
-
-Set `fitViewport: true` on each dev handler embedded in a resizable Inspector pane. Scene previews
-then fit their pane while captures retain the scene's declared frame. Standalone dev handlers keep
-the fixed scene viewport by default.
-
-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 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
-serves an available sidecar at `/__inspection/<map>/<theme>.json`; otherwise that route is 404. The
-option is deliberately off by default. Sidecars remain in memory, do not alter Style bytes or
-manifest hashes, and are excluded from `getTileflowArtifactFiles()` and every stable build output.
-
-When a resolved map declares `fonts`, preparation reads its ordered directories and uses OpenType
-full names as the canonical IDs referenced by `text-font`. TTF, OTF, and WOFF2 inputs are supported;
-every contributing directory must contain `LICENSE.txt`. Later directories replace earlier faces
-with the same exact ID, case-only collisions fail, and every primary font in the final style must be
-present. `font` is an exact face ID; local `fallbacks` entries are exact face names or explicit CSS
-generic families such as `sans-serif`. Preparation never synthesizes a face name from a family and
-weight. Only selected primary faces and licenses are emitted as
-content-addressed managed artifacts.
-
-`fonts` and `glyphs` are mutually exclusive map fields. Omission inherits the parent's current text
-provider; declaring either one replaces an inherited provider of either kind atomically. The font
-pipeline is driven only by directory metadata and final style usage—there are no hard-coded map or
-family names, and a URL provider comes only from the resolved map instead of being invented by the
-pipeline. After inheritance resolves, a map with any text layer must have exactly one provider. A
-`glyphs: {kind: 'url', ...}` provider enumerates the exact comma-joined MapLibre request keys
-produced by the style's `text-font` arrays.
-
-The resulting style records strict `tileflow:fontFaces` metadata. Preview, capture, and browser
-framework adapters load those definitions before constructing MapLibre. Hosted deploy rejects a
-prepared local-font bundle before authentication until managed font storage is available. A derived
-map that declares `glyphs` replaces the inherited local provider atomically; the URL-backed map is
-complete as declared and independent of its World selection.
-
-### 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

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