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

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.

package/docs/native-artifacts.md

@@ -1,287 +0,0 @@
-# Prepare native map artifacts
-
-Use the existing artifact pipeline with `renderer: 'native'` to prepare the `native-v1` static
-profile. The same config loader, inheritance resolver, semantic compiler, icon composition and
-font pipeline are used. There is no separate native map language.
-
-Install the packages and create a trusted `tileflow.config.ts` as described in the
-[package README](../README.md). The source version containing this option must be installed;
-a source branch or a successful build does not establish npm availability.
-
-## Prepare in memory
-
-<!-- docs:check -->
-
-```ts
-import {createTileflowBuildArtifacts} from '@tileflow/dev/artifacts';
-
-const artifacts = await createTileflowBuildArtifacts({
-  config: 'tileflow.config.ts',
-  renderer: 'native',
-});
-
-try {
-  console.log(artifacts.manifest);
-  console.log(artifacts.nativeBuild);
-} finally {
-  await artifacts.dispose?.();
-}
-```
-
-The pipeline checks every concrete theme. A rejected theme fails the complete generation before
-production output is written. Native preparation applies the versioned transformations below;
-other unsupported layers, fonts or protocols are not silently removed.
-Local PMTiles are rejected before creating archive snapshots. URL checks do not fetch remote
-TileJSON, glyphs or tiles and do not prove their content or availability.
-
-Font preparation verifies the same licensed source bytes as web preparation, then maps exact full
-names into Native's `font-faces` root property. It does not retain browser `tileflow:fontFaces`
-metadata or claim a system font is equivalent. Sprites keep the original independently generated
-1x and 2x bytes; the native check verifies their pair, dimensions, IDs and existing size limits.
-
-## Versioned native lowering
-
-Selecting `renderer: 'native'` applies `native-lowering-v1` after shared semantic compilation and
-before final native validation. It never edits the authored map, the official map definitions or
-the shared compiler. Web output is not lowered.
-
-A browser `sky` is removed, because Native draws no sky, and the entry records `sky: 'removed'`.
-A fixed `projection: {type: 'globe'}` is explicitly normalized to Native's implicit Mercator. This
-is a renderer-specific projection change, not equivalent globe rendering. An explicit fixed
-Mercator declaration is also omitted. Adaptive/expression projections and unknown projection
-options remain errors. Every style receipt states which normalization, if any, occurred.
-
-For line layers, finite `line-cap` and `line-dasharray` decisions become contiguous physical layers
-with constant values. Supported trees use constant leaves, `literal`, first-match `case`, disjoint
-`match` labels and `step`. Predicates may combine boolean operations, scalar equality, membership,
-`has`, geometry type and typed numeric comparisons/steps. Unchecked feature values are restricted
-to vector sources, whose properties are scalar. Numeric coercion requires an explicit finite
-fallback. Arbitrary feature-valued leaves, continuous interpolation, feature state, unsupported
-operators and any unprovable decision fail with the original property pointer.
-
-The partition preserves first-match priority. Each feature accepted by the original filter is
-accepted by exactly one active replacement with the same cap and dash values; all other features
-remain excluded. Existing legacy filters are converted with the pinned Style Spec converter before
-intersection. Source, source-layer, metadata and other layout/paint values are preserved. Existing
-`minzoom`/`maxzoom` are intersected with the decision intervals. Both target properties use integer
-camera-zoom evaluation, so a step at 8.5 changes its value at zoom 9, while an original fractional
-layer visibility bound remains fractional. New branch filters contain no camera-zoom expression.
-
-Grouped outcomes use compact boolean decision trees rather than repeated lists of every earlier
-arm's negated guard. Multi-arm cases remain flat to avoid trading size for excessive depth.
-Identical outcomes and adjacent identical intervals are coalesced. IDs derive from the original
-layer ID, the lowering version and deterministic branch order, with collision checks against the
-whole input style. The original layer's replacements stay together; surrounding layers are not
-reordered. Existing sort-key expressions are retained, not simplified or replaced.
-
-Replacements shift the physical index of every later layer, so lowering rebinds the style's layer
-references from the recorded spans. Each `tileflow:interaction-manifest` POI `priority` becomes its
-layer's final index. An overlay placement anchor naming an expanded layer moves to that layer's first
-replacement, because anchors mark insertion-before boundaries. Metadata that the spans cannot prove,
-such as a POI priority that differs from its compiled layer index, a POI entry whose source does not
-match its layer or an anchor naming a missing layer, fails with `NATIVE_UNSUPPORTED_STYLE` at the
-style's `/metadata` pointer rather than being guessed. Local builds, watched sessions and native
-preview share this step with Hosted publication.
-
-MapLibre Native has no symbol overlap modes and reads only `icon-allow-overlap` and
-`text-allow-overlap`. Lowering replaces each constant `icon-overlap` or `text-overlap` value with
-the matching `*-allow-overlap`: `false` for `never` and `true` for `always` and `cooperative`. A
-cooperative symbol therefore no longer gives way to symbols placed with `never` and can cover labels
-it avoids on the web. The layer keeps its ID and position, so the build record lists it under
-`symbolOverlap` rather than as a layer span. An overlap mode given as an expression fails with its
-property pointer.
-
-Work is bounded per property by depth 16, 512 decision visits, 64 decision paths, 16 distinct
-outcomes and 64 dash elements; the product is limited to 32 physical layers and 32 zoom intervals
-per logical layer. Raw compiler input must fit 160,000 JSON nodes before any lowering. Its expanded
-native representation has a separate fixed 540,000-node ceiling, checked after lowering, after
-font preparation and after generation URL retargeting. Both stages retain 4,096 layers, depth 64
-and 8 MiB. No caller option raises either budget and no rejected input is retried under the output
-allowance. A failure occurs before output writes and leaves the previous valid generation intact.
-
-This is one shared authored map, not a second mobile catalog: the native-v1 representation adapts
-only finite `line-cap`/`line-dasharray` decisions and constant symbol overlap modes, together with
-its explicit fixed-projection policy. Unsupported advanced expressions or other properties fail
-with their native diagnostic and JSON Pointer; their web behavior is unchanged. The raw and
-prepared validators share their semantic checks and bounded traversal. See the
-[Core budget contract](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/native-artifact-profile.md#input-and-prepared-style-budgets)
-for the measured Streets sizes and the approximately 5.2% output margin.
-
-The equivalence checks cover per-feature selection, cap/dash values and zoom ranges, **not draw
-order across features**. Copying `line-sort-key` preserves ordering only inside each physical
-layer. If a feature with sort key 1 enters the first branch and a feature with sort key 0 enters
-the second, the physical layers draw them as 1 then 0 instead of 0 then 1. Both features can satisfy
-mutually exclusive filters yet have overlapping geometry. The resulting composition can differ,
-not merely its antialiasing. Even without a sort key, partitioning can change source feature order.
-
-The native-lowering-v1 policy permits these bounded partitions without promising identical global
-feature order. Applications requiring exact overlapping-feature order must not treat such an
-artifact as order-equivalent to its web style. Automated checks establish feature selection,
-cap/dash values, zoom ranges, determinism and resource bounds, not pixel equivalence.
-
-A small directed iOS/Android rendering check of cap/dash/overlap is required for each accepted
-candidate using the recipe below. Full visual qualification belongs to the general mobile release
-gate; it is not claimed by artifact preparation. Browser capture cannot replace either native
-check, and a few visual samples cannot prove preservation of arbitrary feature order.
-
-## Write a separate output
-
-<!-- docs:check -->
-
-```ts
-import {writeTileflowBuildArtifacts} from '@tileflow/dev/artifacts';
-
-await writeTileflowBuildArtifacts({
-  config: 'tileflow.config.ts',
-  renderer: 'native',
-  outDir: 'public/tileflow',
-});
-```
-
-This writes `public/tileflow/native/manifest.json`, `build-manifest.json`, `native-build.json` and
-the complete style/asset generation beneath `public/tileflow/native`. The writer adds `native` once
-beneath `outDir`; pass the output parent, not an already renderer-qualified directory. The native
-subdirectory owns a separate inventory. A web build at the parent neither replaces its manifest nor
-collects the native generation, and vice versa.
-
-The runtime manifest remains strict version 1 with the same map/theme shape. No renderer/profile
-field is added to it. Native font declarations live in the native styles, not a web font loader.
-`native-build.json` is a separate strict build record that identifies the renderer, profile, selected
-engines, `validation: 'static-artifacts'` and the canonical `build-manifest.json` SHA-256. Its
-schema version is 2 and its `preparationVersion` is `native-lowering-v1`.
-
-The `transformations` array is sorted uniquely by map/theme. Each entry records input and lowered
-style SHA-256 values, input/output layer counts, projection normalization and, when present, sky
-removal. `layers` lists the
-input ordinal, output start/count and affected properties of each partitioned line layer;
-`symbolOverlap` lists the input ordinal and replaced properties of each symbol layer whose overlap
-modes became `*-allow-overlap` values. Ordinals refer to the complete style layer arrays, including
-unchanged layers. These spans make the deterministic
-physical IDs traceable without duplicating layer definitions in the receipt. The input hash binds shared
-compiler output; the lowered hash includes the rebound layer references and precedes native font
-preparation and generation URL retargeting.
-The build-manifest hash separately binds the final prepared styles and assets. All styles receive
-an entry, including styles for which no lowering was needed. Schema v1 build records do not imply
-this preparation policy and are not parsed as v2.
-
-The existing logical map revision remains based on resolved cartography and source asset identity.
-Representation changes, such as native font mapping, change the style hash rather than inventing
-a second logical map. Transport credentials and device state never enter these artifacts.
-
-File names in an in-memory plan remain relative to the renderer output root. Relative style/font
-URLs remain relative to their owning documents. An explicit absolute or host-relative
-`styleBaseUrl`/`assetBaseUrl`, such as `/tileflow`, receives the `/native` suffix. The pipeline uses
-an inert `.invalid` document base only to check relative URL syntax; it does not publish that base
-or infer the application's real delivery origin.
-
-A served local preview can use an absolute HTTP base, such as `http://127.0.0.1:3333`, only when it
-also passes that exact origin as `developmentOrigin`. Native checks then accept HTTP resource URLs,
-such as the sprite and fonts, with that scheme, host and port. Every other origin still requires
-HTTPS, and browser protocols remain rejected. The option is never inferred from a base URL.
-Web preparation, `target: 'production'` and `writeTileflowBuildArtifacts()` reject it with
-`NATIVE_RENDERER_UNSUPPORTED` at `/developmentOrigin`, so written artifacts never depend on it.
-
-Omitting `renderer`, or specifying `renderer: 'web'`, preserves the existing web artifact bytes and
-output layout. The native record is absent from web plans.
-
-## Retain the last valid generation
-
-`createTileflowArtifactSession({renderer: 'native', watch: true})` uses the existing session lifecycle.
-An incompatible edit publishes an `invalid` state with native diagnostic context. It retains the
-previous valid artifacts but does not publish them again as a new successful generation. Acquiring,
-releasing and disposing a generation follow the existing [artifact lifecycle](artifact-lifecycle.md).
-
-This is artifact watching, not a native preview server. Do not pass these artifacts to browser
-preview/capture as evidence of a native render. Native inspection sidecars, React Native components,
-Hermes execution, iOS/Android qualification, Hosted authorization and deployment are not supplied.
-
-## Audit lowering size and feature order
-
-From the SDK source root after installing and building the pinned workspace:
-
-```sh
-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 **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,
-sort-key expression and paint indicators. Simultaneously active branches are marked as an
-unproven feature-order boundary, not as a claim that their geometry is disjoint.
-
-Subtree accounts separate copied unchanged layer payload from generated filters and input
-cap/dash decisions. They identify whether predicate expansion or repetition of other properties
-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 full theme size summary even when a budget assertion fails.
-
-## Prepare Streets for a directed native check
-
-From a source checkout, install and build the pinned workspace first. The test-only
-`test/fixtures/native-streets.config.ts` exports the unchanged official Streets definition. It
-exists to make artifact generation repeatable without a second compiler, custom map or native
-harness. From the SDK root:
-
-```sh
-pnpm --filter @tileflow/dev exec node ../cli/dist/index.js validate \
-  --config test/fixtures/native-streets.config.ts --renderer native --target local --json
-pnpm --filter @tileflow/dev exec node ../cli/dist/index.js build \
-  --config test/fixtures/native-streets.config.ts --renderer native --target local \
-  --out output/native-streets --json
-pnpm exec tsx scripts/native-lowering-audit.ts > /tmp/native-lowering-audit.json
-```
-
-The output root is `packages/dev/output/native-streets/native`. It contains
-`styles/streets/dark.json`, `styles/streets/light.json`, their shared sprite/font assets, a version-1
-`manifest.json` and the version-2 `native-build.json` receipt. Keep the complete directory together.
-The manifest points to the content-addressed generation; use those URLs for an actual render.
-Do not copy only the two style files and leave their relative assets behind. Record the checkout
-SHA, both prepared style hashes, engine versions and the resource origin used for the check.
-The fixture and output are source-checkout tools, not a published mobile component or a baseline.
-
-Use an existing native test application with the pinned engines and a reachable artifact origin;
-artifact generation starts no server and requests no deployment. Load the same generated manifest
-family independently on iOS and Android. Resolve its style URL against the manifest URL, then each
-relative style resource against that style's URL before passing the style to MapLibre Native. A raw
-style URL does not transfer this ownership to the renderer. The directed artifact check may use a
-test-owned resolver, but that does not qualify a future runtime resolver. A useful starting viewport
-is a dense road/rail junction with visible paths and bridges; select one where the loaded vector data
-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 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
-not disappear or double-select a feature, theme replacement preserves the scene, and no resource
-or style errors are reported. Inspect overlapping strokes for the documented composition
-trade-off, not for equality with web drawing order. Keep brief per-platform observations and
-explicitly distinguish an unexercised branch from a passed one.
-
-This check has not been run by the artifact tests. It neither establishes full iOS/Android visual
-qualification nor creates a screenshot baseline. Renderers, native view lifecycle, network
-transport and mobile distribution remain outside these build tools.
-
-## Reproduce the official-map report
-
-From an SDK source checkout after installing and building its pinned workspace:
-
-```sh
-pnpm exec tsx scripts/native-catalog-report.ts > native-catalog-report.json
-```
-
-The report evaluates all ten official maps and each of their themes through the shared pipeline.
-Rows contain either a static-compatible style hash or exact incompatibility diagnostics, sorted by
-map/theme with no timestamp or local path. Each row checks an individual theme; it is not a revision
-receipt for a rewritten single-theme map. Unexpected compilation/tool failures stop report generation
-rather than being relabeled as known incompatibilities. Retain the output together with the checkout
-SHA and lockfile used to produce it. The test suite compares two independent evaluations and requires
-Streets to pass. No unchecked catalog-wide compatibility assertion is implied by the presence of
-this command, and this report is not a device-qualification result.
-
-See the [Core profile contract](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/native-artifact-profile.md)
-for the version intersection, diagnostic codes and unsupported representations.

package/docs/native-icons.md

@@ -1,129 +0,0 @@
-# Author recolorable and adaptable icons
-
-Use SDF for a monochrome silhouette whose fill and halo vary by map. Keep multicolor artwork as
-fixed-color RGBA. Ordinary filenames and icon IDs stay unchanged.
-
-In an icon directory already selected by your map, place `tileflow.icons.json` beside `health.svg`:
-
-```json
-{
-  "schemaVersion": 1,
-  "icons": {
-    "health": {
-      "representation": "sdf",
-      "defaults": {"color": "#c43d35", "haloColor": "#ffffff", "haloWidth": 1, "haloBlur": 0}
-    }
-  }
-}
-```
-
-Only explicitly declared SDF assets are converted. Omitted entries, or `representation: "rgba"`,
-preserve fixed-color rendering. SDF uses the source alpha silhouette; source RGB does not define its
-default color. `defaults.color` is required. Omitted halo fields become transparent, zero width and
-zero blur. Unknown IDs, duplicate JSON keys, unknown fields and invalid colors fail preparation.
-
-The generated cell remains 24 × 24 logical pixels at both densities. Within that cell, the source
-silhouette needs six fully transparent pixels on every side. Tileflow rejects edge-touching,
-empty, or insufficiently defined silhouettes instead of adding padding or shrinking artwork.
-Author opaque silhouettes with antialiased edges; gradients and translucent artwork should remain
-RGBA. Thin shapes without a resolved interior fail verification. Generation rasterizes 1x and 2x
-independently and encodes distance in white-RGB alpha. SDF is for symbol icons, not patterns.
-
-For existing artwork, expand the source canvas explicitly before declaring SDF. A drawing bounded
-by `viewBox="0 0 15 15"` fits the profile when its outer SVG uses `width="24" height="24"`
-and `viewBox="-7.5 -7.5 30 30"`: the drawing occupies at most the central 12px. Review fine details
-at the intended map size; use `icon.size` to choose the displayed size. Keep the original source for
-fixed-color use. A transparent margin does not make an excessively thin silhouette suitable.
-
-## Keep each symbol layer homogeneous
-
-One package may contain RGBA and SDF icons. Every icon selectable by one symbol layer, including
-fallbacks, must use the same representation. Tileflow checks the effective composition after all
-local overrides. It does not split layers or alter collision priority, coupled labels or IDs.
-
-An unbounded selection such as a POI icon read from feature data can select any effective icon ID.
-It therefore requires a homogeneous inventory. To use a mixed package, select one fixed icon or
-an explicit `expr.match`/`expr.case` expression whose possible outputs and fallback are homogeneous.
-Sampling the current feature data does not prove this condition.
-
-`tileflow validate`, `tileflow preview`, `tileflow build`, framework preparation and Capture use the
-same check. `TF_ICON_REPRESENTATION_MIXED` identifies the layer and image-selection path. Replace
-the conflicting override, align all selectable representations, or bound the selection explicitly.
-Compiled SDF admission rejects legacy token templates and function objects with
-`TF_ICON_SELECTION_UNPROVEN`; rebuild using expression-based image selection.
-Development reports an invalid generation and retains its last valid artifact until recovery.
-
-## Style each map independently
-
-Use the existing `styles.<category>.icon` fields: `color`, `haloColor`, `haloWidth`, and `haloBlur`.
-Theme tokens, explicit `fixed(...)` values and supported data, zoom and feature-state expressions
-compile to native MapLibre paint. Feature state is supported in paint, not image selection.
-Keep halo width within 0–2 logical pixels and blur within 0–1. Dynamic halo expressions must prove
-these bounds; use `expr.min`/`expr.max` around unconstrained feature values. Otherwise compilation
-reports `TF_ICON_HALO_BOUNDS`.
-
-An omitted paint property uses that selected icon's declared default, including missing-ID
-fallbacks. An override replaces only its property. It does not edit the shared revision or another
-map. Image IDs remain stable; recoloring does not generate image variants. Existing size, opacity,
-rotation and anchor controls retain their native semantics.
-
-## Fit a background around text
-
-Declare optional `layout` beside the representation. It applies to RGBA and SDF independently.
-For a 24px background whose central region can stretch, use this sidecar entry:
-
-```json
-{
-  "schemaVersion": 1,
-  "icons": {
-    "price": {
-      "representation": "rgba",
-      "layout": {
-        "stretchX": [[9, 15]],
-        "stretchY": [[9, 15]],
-        "content": [7, 7, 17, 17]
-      }
-    }
-  }
-}
-```
-
-Coordinates use the generated logical cell, not the original SVG viewBox. Each stretch interval
-is `[start, end]`; `content` is `[left, top, right, bottom]`. Use positive, ordered, non-overlapping
-integer ranges inside the cell. Each configured axis must overlap its content area. Put corners,
-borders and pointers outside stretch regions. Tileflow scales metadata for the 2x index, verifies
-both densities and rejects layout on patterns. SDF backgrounds still need the six-pixel guard.
-
-Enable the existing map `icon.textFit` control (`width`, `height` or `both`) and set
-`icon.textFitPadding` in top/right/bottom/left order. For centered price labels, also set
-`text.anchor: 'center'` and `text.offset: [0, 0]`; the POI defaults place labels beside icons.
-This style fragment belongs inside the selected category's `styles` entry:
-
-```ts
-{
-  icon: {image: fixed('price', {reason: 'Price background'}), textFit: 'both', textFitPadding: [4, 6, 4, 6]},
-  text: {anchor: 'center', offset: [0, 0]},
-}
-```
-
-Import `fixed` from `@tileflow/core`. The same layer retains label coupling, collision priority and
-interaction identity. Text fitting does not happen merely because an asset has metadata. Explicit
-new local artwork replaces the shared asset's layout; omitted metadata never inherits stale bounds.
-
-## Inspect and distribute the result
-
-Packages with SDF appearance or layout use `tileflow-icon-package-v2`; composition receipts use
-`tileflow-icon-composition-v2` when an effective winner has either capability. Paired sprite JSON entries contain
-`sdf: true` and verified `tileflow` appearance metadata. Defaults and layout participate in revision identity
-and diffs even when pixel hashes match. Metadata-free RGBA packages and receipts keep their v1 identity.
-Old readers reject v2; upgrade every producing and consuming package together.
-
-`tileflow icons list --json` includes `appearances` and `layouts` for effective icons. Diff reports show default appearance;
-downloadable PNGs remain the original distance fields. Bare MapLibre consumes the standard sprite
-and compiled paint without a recoloring adapter. Capture uses the same prepared assets.
-
-Hosted admission, Dashboard and Static Maps require coordinated Platform adoption. Additional
-Static Maps symbols use asset defaults and retain adjacent icon/label layout; base-map symbols use
-compiled map paint and text fitting. Device support
-requires separate Native qualification. This contract does not provide independently parameterized
-multicolor SVG, COLRv1, `textFitWidth`/`textFitHeight` metadata or an icon editor.