@tileflow/dev 0.1.0-alpha.17 → 0.1.0-alpha.19

package/README.md

@@ -4,18 +4,69 @@ Node utilities used by the Tileflow CLI and build integrations.
 
 Most apps should use `@tileflow/cli`, `@tileflow/vite`, or `@tileflow/next` directly. Use this
 package when you are building a custom dev server, bundler plugin, or deployment adapter that needs
-to load and compile a `tileflow.config.ts`.
+to load and compile the single map exported by `tileflow.config.ts`.
 
 ```ts
-import {createTileflowBuildArtifacts} from '@tileflow/dev';
+import {createTileflowBuildArtifacts} from '@tileflow/dev/artifacts';
 
 const artifacts = await createTileflowBuildArtifacts({
   config: 'tileflow.config.ts',
 });
 ```
 
+The integration surfaces are deliberately split: use `@tileflow/dev/artifacts` for source
+preparation and production outputs, `@tileflow/dev/server` for HTTP development handling,
+`@tileflow/dev/icons` for icon compilation, `@tileflow/dev/inspect` for safe resolved-config and
+bounded feature inspection, `@tileflow/dev/validation` for structured diagnostics, and
+`@tileflow/dev/preview` only for the local preview contract. The root entry keeps compatibility
+re-exports.
+
+Artifact construction is an explicit `source map → resolved map → prepared map → ArtifactPlan`
+pipeline. Map inheritance resolves before its ordered local/package icon and font directories are
+prepared, and before the result reaches the core style compiler. The Node layer may normalize
+the map into an internal build catalog, but that catalog is orchestration state rather than another
+public authoring model. The plan exposes its complete files and observed input graph, so build
+adapters emit and watch the same generation instead of reconstructing either list themselves. Production manifests
+point to content-addressed `generations/<sha256>/...` theme styles and sprites; those immutable files are
+installed before the manifest pointer changes. Stable style paths are
+`styles/<map>/<theme>.json`; every manifest lookup resolves a concrete theme. The disk writer also stages the complete plan,
+records a managed-file inventory, rolls back caught filesystem failures, and removes only stale
+files named by its previous valid inventory. It retains the immediately preceding immutable
+generation during each replacement, so a client that already read the old manifest can finish its
+style and sprite requests; the next replacement retires that older generation. Stable `styles/`
+and `icons/` paths remain available, but generation-consistent consumers
+resolve maps through `manifest.json`.
+
+Every plan also emits canonical `build-manifest.json` (schema version 1). For each map it records
+the leaf `mapVersion`, resolved lineage, effective icon/font source identities, Recipe ABI, and
+one entry per concrete theme with `colorScheme`, identity, inferred legacy `dataRequirements`,
+multi-source `sourceRequirements`, and `styleSha256`. The multi-source contract records each
+referenced vector source independently and records raster DEM source ID, encoding, and tile size;
+it therefore distinguishes Bathymetry vector bands from optional relief without inventing vector
+fields. `mapRevisionSha256` identifies the effective cartographic definition after `extends`;
+`assetSetSha256` for that map's generated runtime resources. Data requirements are derived from the
+final Style layers and fields rather than copied from a manually maintained allowlist, so disabled
+or overridden modules do not claim data they no longer use. The Recipe ABI remains a separate
+`recipe: {compiler, compilerVersion}` compatibility axis.
+
+The map revision is versioned and domain-separated. It contains the resolved cartographic design,
+the compiler family, private effective module contributions, and effective icon/font source
+identities. Map `id`, `name`, editorial `mapVersion`, default `view`, capture `scenes`, delivery
+policy, package SemVer, compiler ABI, local paths, timestamps, generated sprite/font output, and a
+concrete resolution of a floating World selector are deliberately outside it. Changing a shadowed
+ancestor does not change the revision; changing an effective cartographic override or source asset
+does. Lineage and the leaf `mapVersion` remain beside the hash for traceability, Style JSON owns its
+compiled-output identity, and Hosted delivery policy belongs to the deployment fingerprint. The
+top-level `provenance` block records the exact participating Tileflow package versions and the
+nearest package-manager lockfile's format and content hash, without embedding its local path;
+provenance remains outside every map revision. The same portable block is available to Hosted
+adapters through
+`createTileflowBuildProvenance(cwd)`. The dev server exposes the complete document at
+`/build-manifest.json`.
+
 `createTileflowStyle`, `createTileflowStyles`, and artifact construction all enforce the same
 recursive JSON-value invariant and MapLibre style-spec semantics without fetching remote resources.
+The family API returns `styles[map][theme]`; it never flattens a default theme into a map alias.
 Invalid output throws `TileflowStyleValidationError` with at most 32 deterministic
 `map`/`path`/`message` issues; layer indexes are projected to stable layer IDs.
 
@@ -23,7 +74,7 @@ For a watched, last-known-good integration, use one artifact session rather than
 request independently:
 
 ```ts
-import {createTileflowArtifactSession} from '@tileflow/dev';
+import {createTileflowArtifactSession} from '@tileflow/dev/artifacts';
 
 const session = await createTileflowArtifactSession({
   config: 'tileflow.config.ts',
@@ -40,15 +91,17 @@ await session.close();
 ```
 
 The bounded watcher follows the config, transitive local TypeScript/JavaScript/JSON imports, and
-effective icon inputs. Generations are monotonic, overlapping refreshes are latest-wins, invalid
+effective local icon/font directory inputs. Generations are monotonic, overlapping refreshes are latest-wins, invalid
 edits retain the last good snapshot, and caller-supplied output directories can be ignored to avoid
-feedback loops. `tileflow dev`, `capture --watch`, and framework adapters use this shared status
-vocabulary.
+feedback loops. `tileflow preview` (`tileflow dev` compatibility alias), `capture --watch`, and
+framework adapters use this shared status
+vocabulary. The built-in preview reloads after its live event stream reconnects following a server
+restart, even when the replacement process begins again at generation 1.
 
-Custom preview servers can select the same map or standalone scene semantics as the CLI:
+Custom preview servers use the exported map or one of its standalone scenes:
 
 ```ts
-import {createTileflowDevRequestHandler} from '@tileflow/dev';
+import {createTileflowDevRequestHandler} from '@tileflow/dev/server';
 
 const fetch = createTileflowDevRequestHandler({
   session,
@@ -56,14 +109,308 @@ const fetch = createTileflowDevRequestHandler({
 });
 ```
 
-`map` and `scene` are mutually exclusive. Map preview uses the configured `view`; scene preview
-uses its committed camera and CSS viewport. `resolveTileflowPreview()` exposes the validated
-selection for custom integrations. Application-target scenes remain the responsibility of the
-application's development server.
+Map preview uses the exported map's `view` and accepts one concrete `theme`; scene preview uses its
+committed concrete theme, camera, and CSS viewport metadata from that same map. A scene does not
+repeat the map ID because its owner is implicit.
+`resolveTileflowPreview()` exposes the validated selection for custom integrations.
+Application-target scenes remain the responsibility of the application's development server. The
+built-in preview records longitude, latitude, zoom, bearing, and pitch in the current URL, so browser
+refreshes and config-triggered reloads return to the same view. Removing those query parameters
+restores the configured camera.
+
+## Local comparison workbench and compiler inspection
+
+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 generic definitions before constructing MapLibre. Hosted preparation
+also emits one canonical `tileflow-font-bundle-v1` closure containing only selected faces and their
+license bytes. Its manifest SHA-256 is the sole content identity; Hosted adds an opaque project-owned
+storage ID. Deploy uploads that bundle before the Style and then replaces provisional sources with
+the exact immutable ID URLs confirmed by Hosted. 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.
+
+That upload and binding contract is implemented, but it is not by itself a production-availability
+promise. The matching Hosted rollout candidate adds DB-backed project ownership, organization quota,
+durable deployment references, grace-based garbage collection, and deletion receipts; availability
+still requires that matching migration, API, and SDK pair to be promoted together.
+
+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`, `ferrarisIcons`,
+`haradIcons`, `siegfriedIcons`, `soundingsIcons`, `cyberpunkIcons`, `matrixIcons`, and `verdantIcons`
+directory descriptors from `@tileflow/maps`. Cyberpunk, Matrix, and Siegfried also export
+`cyberpunkFonts`, `matrixFonts`, 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.
 
-If a map uses `icons: './icons/brand'`, build artifacts include the generated
-MapLibre `sprite.json`, `sprite.png`, `sprite@2x.json`, and `sprite@2x.png`
-assets alongside the styles.
+## Structured config inspection and diagnostics
+
+Custom Node tooling can use the same deterministic documents as `tileflow validate --json` and
+`tileflow inspect --json`:
+
+```ts
+import {inspectTileflowConfig} from '@tileflow/dev/inspect';
+import {
+  createTileflowCommandFailureDocument,
+  serializeTileflowCommandDocument,
+} from '@tileflow/dev/validation';
+
+try {
+  const inspection = await inspectTileflowConfig({config: 'tileflow.config.ts'});
+  process.stdout.write(serializeTileflowCommandDocument(inspection));
+} catch (error) {
+  const failure = createTileflowCommandFailureDocument('inspect', error, process.cwd(), {
+    code: 'INSPECTION_FAILED',
+    phase: 'config-inspection',
+  });
+  process.stderr.write(serializeTileflowCommandDocument(failure));
+}
+```
+
+The inspection resolves one config load into sorted maps, root-to-leaf lineage, declared paths, and
+leaf-level merge provenance. Its `themeContract` exposes the default/system mapping, shared token
+schema, concrete resolved token values, typography and lighting, differences from the default, and
+stable `THEME_IMPLICIT_FIXED` diagnostics across modules, terrain, and compiler-owned effects. Each
+diagnostic carries a semantic scope and, for compiler effects, its owner, target, and effect kind,
+plus machine-readable severity and remediation. Colors, fonts, and images are followed through
+expression outputs; numeric diagnostics intentionally cover only direct visual scalars, excluding
+expression operands, zoom stops, tuples, placement, priority, and other structural numbers.
+Agents can therefore edit semantic roles without
+reverse-engineering compiler layers or parsing prose. It never returns `inputFiles`, absolute filesystem paths, credentials,
+URL queries, data URLs, or recognized secret formats. Structured summaries and diagnostics use the
+same required schema-version-1 fields and bounded safe suggestions so consumers do not need to
+parse human prose.
 
 ## Bounded vector-feature inspection
 
@@ -71,13 +418,14 @@ Custom Node tooling can inspect only the features visible near a configured came
 a browser:
 
 ```ts
-import {inspectTileflowFeatures} from '@tileflow/dev';
+import {inspectTileflowFeatures} from '@tileflow/dev/inspect';
 
-const inspection = await inspectTileflowFeatures(project, 'madrid', {
+const internalCatalog = artifacts.project;
+const inspection = await inspectTileflowFeatures(internalCatalog, 'madrid', {
   center: [-3.6927512, 40.4086555],
   zoom: 16,
   sourceLayers: ['poi'],
-  properties: ['name', 'class', 'subclass', 'rank'],
+  properties: ['name', 'category', 'type', 'icon', 'filter_rank', 'size_rank'],
   width: 512,
   height: 512,
   limit: 100,
@@ -94,19 +442,33 @@ paths. PMTiles and authenticated provider adapters are not currently supported b
 Deployment adapters can compile the same sources without writing them to disk:
 
 ```ts
-import {compileTileflowIconPackages} from '@tileflow/dev';
+import {compileTileflowIconPackages} from '@tileflow/dev/icons';
 
-const result = await compileTileflowIconPackages(project, {
+const internalCatalog = artifacts.project;
+const result = await compileTileflowIconPackages(internalCatalog, {
   cwd: process.cwd(),
   target: 'hosted',
 });
 ```
 
+Streets declares `[streetsIcons]` and keeps light/dark image-token targets in that one closure;
+Cyberpunk and Matrix independently declare `[cyberpunkIcons]` and `[matrixIcons]`. Ferraris, Härad,
+Siegfried, Soundings, and Verdant declare only `[ferrarisIcons]`, `[haradIcons]`, `[siegfriedIcons]`,
+`[soundingsIcons]`, and `[verdantIcons]`, respectively. No official root composes another map's
+assets even though all use the semantic Streets compiler ABI. Härad's directory contains nine original Tileflow
+patterns inspired by Lantmäteriet's CC0 Häradsekonomiska kartan series from 1859–1934. Soundings owns ten
+original nautical symbols and patterns. An application map may inherit a root's exact array,
+replace it, clear it with `[]`, or
+compose it explicitly with a spread.
+`modules.poi.icons: false` or a disabled POI module suppresses POI icon layers without moving asset
+ownership into dev. POI density is the numeric producer threshold 1–5; it is not an asset-provider
+preset.
+
 The hosted target enforces repository containment, portable icon IDs, safe SVG
-references, deterministic ordering, and the public package limits. It returns
-deduplicated generated files plus a canonical manifest/content hash. Upload only
-those generated files: source icons and absolute paths remain local. External
-sprite URLs are preserved as references and are not downloaded.
+references, deterministic ordering, and the public package limits. Package-owned directories are
+trusted only inside their declared owning package and are exempt from config working-tree
+containment. It returns deduplicated generated files plus a canonical manifest/content hash. Upload
+only those generated files: source icons and absolute paths remain local.
 
 The version-1 manifest includes `renderedIcons` in the exact sorted `iconNames` order. Each entry
 contains SHA-256 digests for the normalized 1x and 2x RGBA cell. The digest framing includes its
@@ -124,22 +486,24 @@ Custom Node tooling can inspect the same local pipeline without walking or decod
 second time:
 
 ```ts
-import {inspectTileflowIconCatalogs} from '@tileflow/dev';
+import {inspectTileflowIconCatalogs} from '@tileflow/dev/icons';
 
-const inspection = await inspectTileflowIconCatalogs(project, {
+const internalCatalog = artifacts.project;
+const inspection = await inspectTileflowIconCatalogs(internalCatalog, {
   cwd: process.cwd(),
   mapNames: ['madrid'],
 });
 ```
 
-The result keeps one catalog per resolved source directory, map-specific resolved mappings,
-cwd-relative source metadata, exact atlas rectangles, both manifest pixel digests, and the shared
-compiled package. It classifies remote and absent catalogs without fetching them. This is a
-local-authoring integration surface: use the hosted compilation target separately for deployment
-compatibility, and project only the metadata needed by an external protocol rather than serializing
-generated byte arrays accidentally.
+The result keeps one catalog per distinct ordered directory composition, the exact winning source
+for every final ID, explicit same-ID replacements, config-relative source metadata, exact atlas rectangles,
+both manifest pixel digests, and the shared compiled package. `icons: []` is represented as an
+absent catalog. This is a local-authoring integration surface: use the hosted compilation target
+separately for deployment compatibility, and project only the metadata needed by an external
+protocol rather than serializing generated byte arrays accidentally.
 
-This package is public, but it is an integration layer. Map styling primitives live in
-`@tileflow/core`; React rendering lives in `@tileflow/react`.
+This package is public, but it is an integration layer. Styling primitives live in
+`@tileflow/core`, official maps and their source assets live in `@tileflow/maps`, and React
+rendering lives in `@tileflow/react`.
 
 Docs: https://tileflow.dev/docs

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,69 @@
+# Third-party notices
+
+This file records third-party components used by Node preparation and preview. Official map artwork
+and fonts are owned and published by `@tileflow/maps`; `@tileflow/dev` does not carry an `assets/`
+directory. Runtime dependencies are installed as separate npm packages, and their code and native
+binaries are not copied into the dev package.
+
+## Package-owned map fonts
+
+The generic font preparation pipeline reads map-owned TTF, OTF, and WOFF2 directories; it does not
+embed fonts in `@tileflow/dev`. Each source directory must carry its own `LICENSE.txt`, which is
+copied into the deterministic build artifacts whenever that directory contributes a selected face.
+
+The Cyberpunk map in `@tileflow/maps` currently owns unmodified Oxanium Medium and SemiBold TTFs.
+Oxanium is copyright 2019 The Oxanium Project Authors and is distributed under the SIL Open Font
+License 1.1. The source and binaries are pinned to upstream commit
+`a8f39e0c71186190027a093e9001459410192d1e`; the complete license accompanies the files at
+`@tileflow/maps/assets/cyberpunk/fonts/LICENSE.txt`.
+
+- Source: <https://github.com/sevmeyer/oxanium/tree/a8f39e0c71186190027a093e9001459410192d1e>
+- Google Fonts specimen: <https://fonts.google.com/specimen/Oxanium>
+- License: <https://github.com/sevmeyer/oxanium/blob/a8f39e0c71186190027a093e9001459410192d1e/OFL.txt>
+
+## fontkit 2.0.4
+
+Font metadata for TTF, OTF, and WOFF2 inputs is read with the separately installed `fontkit`
+package. fontkit is copyright Devon Govett and contributors and is distributed under the MIT
+License.
+
+- Source: <https://github.com/foliojs/fontkit/tree/v2.0.4>
+- License: <https://github.com/foliojs/fontkit/blob/v2.0.4/LICENSE>
+
+## PMTiles JavaScript 4.5.0
+
+The local Streets preview loads the separately installed `pmtiles` browser decoder to retrieve
+individual landmark GLB entries with HTTP byte ranges. PMTiles is copyright Protomaps and
+contributors and is distributed under the BSD 3-Clause License. Its `fflate` dependency is
+copyright 2020 Arjun Barrett and is distributed under the MIT License.
+
+- PMTiles source and license: <https://github.com/protomaps/PMTiles/tree/v4.5.0/js>
+- fflate source and license: <https://github.com/101arrowz/fflate/tree/v0.8.2>
+
+## sharp 0.35.3
+
+`@tileflow/dev` declares `sharp` as an optional dependency and loads it dynamically only when local
+SVG or raster icon sources must be inspected and packed. The Tileflow build externalizes `sharp`
+rather than bundling it. `sharp` is copyright Lovell Fuller and contributors and is distributed under
+the Apache License 2.0.
+
+- Source: <https://github.com/lovell/sharp/tree/v0.35.3>
+- License: <https://github.com/lovell/sharp/blob/v0.35.3/LICENSE>
+
+## sharp libvips distributions 1.3.2
+
+`sharp` selects a separate optional `@img/sharp-libvips-*` package for the current platform. The
+installed platform-package manifest declares `LGPL-3.0-or-later`; the packaging scripts themselves
+are distributed under Apache-2.0. The packages contain prebuilt libvips and separately licensed
+runtime dependencies. For `sharp` 0.35.3 the selected libvips ABI is 8.18.3.
+
+- Packaging source: <https://github.com/lovell/sharp-libvips/tree/v1.3.2>
+- Packaging-script license: <https://github.com/lovell/sharp-libvips/blob/v1.3.2/LICENSE>
+- libvips 8.18.3 source: <https://github.com/libvips/libvips/tree/v8.18.3>
+- libvips 8.18.3 license (LGPL-2.1-or-later):
+  <https://github.com/libvips/libvips/blob/v8.18.3/LICENSE>
+
+Because `sharp` remains a separately installed optional package, users can install, update, remove,
+or replace it independently of `@tileflow/dev`. Tileflow does not modify libvips and does not place a
+libvips shared library or a `sharp` native addon inside any Tileflow package tarball. Release smoke
+tests enforce that package boundary.

package/TRADEMARKS.md

@@ -0,0 +1,10 @@
+# Tileflow trademarks
+
+The Apache License, Version 2.0, and the Tileflow generated-output grant do not grant permission to
+use the Tileflow name, `tileflow.dev`, logos, service marks, product names, or other Tileflow brand
+features except for reasonable and customary use that truthfully describes the origin of the SDK or
+compatibility with Tileflow, and for reproducing required notices.
+
+You may not use Tileflow brand features in a way that suggests sponsorship, endorsement, or an
+official Tileflow product when none exists. Third-party names and marks remain the property of their
+respective owners.