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

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

@@ -0,0 +1,249 @@
+# Local comparison workbench 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:
+
+```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',
+  },
+});
+```
+
+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.
+
+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.
+
+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.

package/docs/native-artifacts.md

@@ -0,0 +1,285 @@
+# 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 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 and projection normalization. `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 **both** dark and light 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 two-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 both 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

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