tileflow 0.1.0-alpha.7 → 0.1.0-alpha.9

package/docs/agent-icon-composition.md

@@ -30,8 +30,10 @@ Each sorted map entry has one `id` and an `icons` value. `icons.kind` is `none`
   byte length and intrinsic dimensions; an `icon-set` entry carries the exact `reference` and
   `version` and deliberately has no path, because a shared revision publishes verified generated
   cells rather than original artwork. Both carry the winning `contributor` ordinal.
-- `composition`, the exact ordered `tileflow-icon-composition-v1` receipt when the map declares a
-  shared set, and `null` otherwise; and
+- `composition`, the exact ordered receipt when the map declares a shared set, and `null`
+  otherwise. It uses `tileflow-icon-composition-v2` when an effective winner has SDF appearance
+  or stretch/content layout; metadata-free compositions retain v1;
+- optional `appearances` and `layouts`, keyed by effective icon ID; and
 - `insideWorkingTree` and the deterministic generated `packageHash`.
 
 Listing reads the exact `tileflow.icons.lock.json` beside the selected config. It never resolves a
@@ -51,9 +53,11 @@ uses `../` and `insideWorkingTree: false`; no absolute path is emitted. Listing
 authoring semantics. Run `npx tileflow validate --target hosted` separately before a
 hosted deploy to check containment, portable IDs, SVG safety, and hosted limits.
 
-The Tileflow command performs no authentication, browser/server launch, or file write. It performs
-no network request when every locked artifact is already in the verified cache, and `--offline`
-forbids hydration entirely. It removes an ambient `TILEFLOW_API_KEY` before importing config. As with every config-aware
+The Tileflow command performs no authentication or browser/server launch and never writes config,
+repository locks or frontend manifests. A cold cache can download and store the exact public
+sprite artifacts. It performs no network request when every locked artifact is already in the
+verified cache, and `--offline` forbids hydration entirely. `--json` is required; use `--config`
+(or `-c`) to select another config file. It removes an ambient `TILEFLOW_API_KEY` before importing config. As with every config-aware
 command, loading `tileflow.config.ts` executes repository code and is not a sandbox; side effects in
 that code remain the repository's responsibility. Success emits no ANSI or progress prose. Usage,
 config, source, decode, and render failures exit 1, write diagnostics to stderr, and leave stdout

package/docs/build-artifacts.md

@@ -31,3 +31,10 @@ screenshot window.
 Build is local and credential-free. Hosted compatibility is a separate
 `tileflow validate --target hosted` preflight. Primary map data must remain Tileflow World; named
 Team sources are validated and resolved independently.
+
+## Choose an artifact renderer
+
+`validate` and `build` accept `--renderer web|native`; omission preserves the web pipeline and its
+bytes. Native artifacts use a separate `native/` output directory and do not establish a running
+mobile SDK. See [native artifact validation and output](native-artifacts.md) for the target matrix,
+JSON diagnostics, prepared fonts and explicit limitations.

package/docs/command-families.md

@@ -14,11 +14,17 @@ Start with the [tileflow guide](https://github.com/tileflow/tileflow-sdk/blob/ma
 | Hosted delivery   | `deploy`, `status`                                                                             |
 
 Run `tileflow <command> --help` (or the family help, such as `tileflow icons --help`) for the exact
-arguments and bounded JSON modes.
+arguments and bounded JSON modes. `preview` defaults to the existing web renderer. The explicit
+`preview --renderer native` / `dev --renderer native` mode serves watched `native-v1` artifacts only;
+Metro remains the React Native JavaScript development server. See
+[Native artifacts and local preview](./native-artifacts.md) for the endpoint and qualification
+boundary.
 
 `icon-set` and `icons` are deliberately separate. `icon-set` needs Team authority and changes the
-remote catalog. `icons list` and `icons diff` are keyless local inspection, and
-`icons install|update|pin` are the only commands that resolve `latest` or write
+remote catalog. `icons list --json` needs no credential; a cold cache may download exact public
+artifacts. `icons diff` requires a managed `--map-id`, the configured map ID in `--against`, and
+`status:read` authority for its hosted baseline. `icons install|update|pin` use Team `icons:read`
+authority when resolving revisions and are the only commands that select revisions or write
 `tileflow.icons.lock.json`. See the
 [Team Icon Set workflow](https://github.com/tileflow/tileflow-sdk/blob/main/packages/cli/docs/team-icon-sets.md).
 

package/docs/hosted-authentication-and-deploy.md

@@ -171,8 +171,9 @@ For a map with `icons: ['./icons']`, hosted validation compiles the local SVG/PN
 without a key. Ordered directories apply left to right and later exact IDs replace earlier files.
 Deploy uploads the four generated sprite files before its first style write and reuses
 byte-identical packages by content hash. Source icons and absolute paths remain local; generated
-atlas bytes and sorted icon names are public. Each hosted package is limited to 256 icons and 8 MiB
-generated bytes as a processing envelope. There is no package-count quota; physically retained
+atlas bytes and sorted icon names are public. Each hosted package is limited to 1,000 icons and 8 MiB
+generated bytes as a processing envelope. Large artwork may reach the 2,048-pixel atlas bound before
+the icon count. There is no package-count quota; physically retained
 generated packages share the organization's 5/10-GB hosted-storage pool with retained PMTiles,
 remain protected by deployment/library references, and otherwise enter the technical orphan grace
 before deletion. Upload success must confirm the submitted `contentHash`, exact icon count, exact

package/docs/native-artifacts.md

@@ -0,0 +1,169 @@
+# Native artifacts, local preview and Hosted deployment
+
+Use a project-local CLI version that includes the native artifact selector and a trusted
+`tileflow.config.ts`. Follow the [installation instructions](../README.md) first. Native commands
+prepare, serve or publish Tileflow artifacts; they do not install, start or qualify a mobile renderer.
+
+## Validate and build
+
+```sh
+npx tileflow validate --renderer native --target local --json
+npx tileflow build --renderer native --target local --out public/tileflow --json
+```
+
+`validate` prepares and checks the complete theme family without writing production output.
+`build` writes the checked generation beneath `public/tileflow/native`, including a strict version-1
+runtime manifest and a separate schema-v2 `native-build.json` record. Serve the complete renderer
+directory, not just the style. A failed compatibility check leaves existing output unchanged.
+
+Both commands accept `--renderer web|native`; omission means `web`. Renderer selection is separate
+from `--target local|hosted`. Existing `validate --target hosted` continues to perform web Hosted
+preflight. Native with `--target hosted` fails with `NATIVE_RENDERER_UNSUPPORTED` before loading the
+config or writing files. `build --target hosted` is not publication and is rejected. The explicit
+combined Hosted publication command below performs its own complete two-renderer preflight.
+
+JSON success uses the existing version-1 command envelope. Native results additionally identify
+`renderer: 'native'`, `profile: 'native-v1'` and `validation: 'static-artifacts'`. JSON failure writes
+one structured envelope to stderr, leaves stdout empty and exits nonzero. Native diagnostics have
+safe JSON Pointers, stable codes, severity and suggestions. Unknown renderer names are not echoed.
+The ordinary web commands and their default artifact bytes retain their existing behavior.
+
+## Watch and serve native artifacts
+
+`preview` and its `dev` alias use the same renderer selector:
+
+```sh
+npx tileflow preview --renderer native --map stores --theme light
+```
+
+Native mode creates the existing watched artifact session with renderer `native`. It keeps the
+last-known-good native artifact family when a watched generation becomes invalid and replaces it
+only after a later valid generation is prepared. The endpoint is an **assets-only** development
+endpoint: it does not render a browser map, open the visual workbench, start Metro, launch a device,
+or establish visual/native acceptance.
+
+With the default host and port, the canonical runtime manifest is:
+
+```text
+http://127.0.0.1:3333/native/manifest.json
+```
+
+The manifest remains the ordinary strict version-1 Tileflow runtime manifest. Its style, sprite,
+font, tileset and generation references use the existing renderer-specific `/native/...` paths; no
+preview-only manifest schema is introduced. `--map` and `--theme` validate a desired map/theme
+against that finalized manifest but do not narrow or fork the served artifact family.
+
+Human output identifies the exact manifest URL, profile `native-v1`, and `assets-only` endpoint.
+Native NDJSON lifecycle events additionally carry `renderer`, `profile`, `manifest` and
+`assetsOnly`; the default and explicit `--renderer web` lifecycle/output contract remains the
+existing browser-preview contract.
+
+Metro remains the React Native application's JavaScript development server. The application points
+its Tileflow source at the native manifest URL and sets `source.developmentOrigin` to its exact HTTP
+origin, for example `http://127.0.0.1:3333`. Both addresses must be reachable from the target device;
+an Android emulator may use a different host address. Other resource origins still require HTTPS.
+The application supplies its own development networking setup. Tileflow
+does not add a Metro plugin, device discovery or a tunnel.
+
+`preview` still binds to `127.0.0.1` by default. Existing explicit `--host <ip-or-localhost>` behavior
+is preserved. Selecting another host does not add LAN discovery, a public tunnel, an iOS ATS
+exception, an Android cleartext exception, or any native application mutation; the application and
+developer remain responsible for making an explicitly selected development endpoint reachable
+under their own platform/network policy.
+
+Browser-only selections fail before config execution in native mode. In particular, committed
+`--scene` preview and every `--against-*` comparison-workbench option are unavailable with
+`--renderer native`. Native mode does not serve the browser preview root, preview JavaScript runtime,
+compiler-inspection sidecars, or the dev handler's status/event control routes. Use ordinary/default
+web preview for those workflows.
+
+The `native-lowering-v1` preparation policy records fixed globe-to-Mercator normalization and
+finite cap/dash layer partitioning in `native-build.json`; it does not change web artifacts.
+Native preparation rejects adaptive/unknown projections, terrain, browser PMTiles/contour protocols,
+missing text providers and unsupported style values rather than degrading them silently. It preserves
+shared icon inheritance and independent sprite densities, and maps verified licensed TTF/OTF faces
+into native style declarations. See the
+[profile contract](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/native-artifact-profile.md)
+and [artifact layout](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/docs/native-artifacts.md).
+
+## Publish web and Native together
+
+The pre-release source supports an explicit combined deployment against a compatible Hosted API.
+This is a wire and implementation contract, not a statement that a package or server release is
+available. The API must understand renderer-collection deployment schema 2.
+
+```sh
+npx tileflow deploy --with-native --map-id map_0123456789abcdef --map stores
+```
+
+`--map-id` selects the existing managed Tileflow Map. `--map` selects one map from the repository;
+it can be omitted only when the config contains one map. The command uses the ordinary deployment
+credential or account capability, not the publishable mobile credential. Do not put privileged
+credentials in mobile application configuration.
+
+Before authentication, upload or publication, the command loads the trusted config once, prepares
+its icon closure, compiles all web themes and lowers all Native themes from that same compiled
+input. It validates profile `native-v1`, hashes, authored identity, source ownership declarations,
+semantic POI provenance and overlay boundaries. Native incompatibility rejects the entire request;
+it cannot publish a new web family alone. Existing Hosted restrictions still apply, including the
+current rejection of package-owned web font bundles. This opt-in does not bypass those restrictions;
+use an explicitly configured glyph provider for this Hosted path.
+
+Shared icon packages use the existing content-addressed upload protocol once. The command replaces
+only the confirmed owned sprite URL, without reevaluating config, and sends one strict renderer
+collection to `POST /v1/styles`. The server verifies both complete families and their owned resources,
+stages immutable outputs, and activates them through the existing single deployment authority.
+A Native staging failure does not activate the replacement web family. Retry the same input after an
+interrupted response: the server's existing content identity determines reuse or a new deployment.
+
+The successful response has its own explicit schema version 2 and identifies one managed Map and
+deployment plus web and Native theme references. The CLI requires the complete matching response
+before atomically replacing `--manifest`. That local file stays a strict **runtime manifest v1 for
+web**, so existing bundlers do not receive unknown Native fields. The CLI separately prints the
+canonical Native manifest URL. A failed request or invalid response leaves the existing local file
+unchanged; an uncertain response is not proof that the server performed no publication.
+
+Ordinary `deploy` without `--with-native` keeps its schema-1 request and response behavior. A later
+web-only deployment does not inherit a Native family from an older deployment.
+
+## Native discovery and protected resources
+
+The canonical entry URL is on the application's configured API origin:
+
+```text
+https://api.example.test/maps/map_0123456789abcdef/native/manifest.json
+```
+
+This bounded, one-map runtime manifest is **public metadata**. It contains identity, theme names,
+revisions and references, never Style JSON, credentials or grants. It is served with `no-store` only
+for a coherent active Native deployment. Its GET is not a commercial completion event.
+
+Use that URL in the existing `Map` source descriptor, keeping the authored map name in `source.map`.
+The application configures its publishable mobile credential and approved API origin once, using the
+[React Native application configuration contract](../../react-native/docs/native-configuration.md).
+The SDK requires both the requested and final response URLs to be the exact canonical route for the
+declared managed Map. The manifest's `apiUrl` must exactly equal the configured canonical API origin;
+a remote document cannot create a trusted origin or choose where the credential is sent.
+
+The credential goes only to the configured API's `POST /v1/sessions/start`. It is not sent to the
+manifest, a CDN, a style URL or a redirect destination. Styles, TileJSON, tiles, sprites, glyphs and
+font resources remain protected by the existing grant and resource-ownership checks.
+
+A Native theme references `/maps/<mapId>/native/v<deploymentVersion>/<theme>.json` and requires a
+revision. The server verifies that version against the active deployment and the style's stored
+bytes against the revision. Before resource projection, the SDK checks the protected response URL
+and its Map/theme/deployment/revision metadata. If discovery became stale, it refetches the public
+manifest at most once for that selection, preserving its existing session and admission context.
+Another Map, origin, mode or older deployment cannot replace that ownership. A repeated failure
+enters the existing safe error/rollback path rather than mixing generations or looping indefinitely.
+
+Session start, public metadata discovery and Map rendering do not themselves assert a billable
+completion. Completion remains owned by the server's existing eligible protected GET 200/206 path.
+Disabled mobile delivery fails closed; publication does not enable it.
+
+## Qualification boundary
+
+Native local preview is artifact preparation and delivery only. A successful artifact or deployment
+response does not establish Hermes execution, iOS/Android rendering, device reachability, visual
+fidelity, package publication or product availability. Qualify the exact compatible SDK/API pair,
+React Native application, platform networking policy and native runtime separately.

package/docs/read-only-icon-comparison.md

@@ -2,17 +2,20 @@
 
 Start with the [tileflow guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/cli/README.md) for installation and a complete first example.
 
-Compare the exported map with its active hosted revision before deciding whether to deploy:
+Compare the exported map with its active hosted revision before deciding whether to deploy.
+These examples assume the configured map ID is `madrid`; replace the sample managed Map ID with
+your Dashboard destination and use personal CLI login or a credential with `status:read`.
+`--against` selects the exact map ID in the configuration, not a deployment-stage keyword:
 
 ```sh
-npx tileflow icons diff --map-id map_AbCdEfGhIjKlMnOp --against production
-npx tileflow icons diff --map-id map_AbCdEfGhIjKlMnOp --against production --json
-npx tileflow icons diff --map-id map_AbCdEfGhIjKlMnOp --against production --report ./icon-diff.html
+npx tileflow icons diff --map-id map_AbCdEfGhIjKlMnOp --against madrid
+npx tileflow icons diff --map-id map_AbCdEfGhIjKlMnOp --against madrid --json
+npx tileflow icons diff --map-id map_AbCdEfGhIjKlMnOp --against madrid --report ./icon-diff.html
 ```
 
 The command compiles only the exported map, performs authenticated read-only control-plane
 requests, and never uploads a package, creates a deployment, or writes the frontend manifest.
-Plain and JSON modes create no files. A requested HTML report adds reads of the baseline's four
+Plain and JSON modes write no report; preparing locked inputs may download and write cache entries. A requested HTML report adds reads of the baseline's four
 public sprite files and
 embeds verified old/new images in one self-contained file. The report groups exact-cell icon
 previews under `Added`, `Modified`, and `Removed`. Added and removed cards show only the affected
@@ -24,9 +27,15 @@ implementation UI and contains no API key, remote runtime dependency, original i
 local source path. Use `--force` to replace different existing report bytes and `--open` only
 together with `--report`.
 
-Visual modification means that normalized rendered RGBA pixels changed at 1x or 2x. Fully
-transparent RGB is ignored. The manifest also hashes the four encoded artifacts, so an artifact can
-change while its per-icon pixel list remains unchanged. The report and digest analysis operate on
+An icon is `modified` when its rendered record changes: normalized 1x/2x pixel hashes, dimensions,
+SDF defaults or stretch/content layout. Fully transparent RGB is ignored in pixel hashes. Metadata
+edits can therefore mark an icon modified even when its pixel hashes are unchanged. Reports render
+SDF with asset defaults; raw downloadable PNGs still encode distance fields.
+
+`hasChanges` compares effective package content hashes. The manifest also hashes the four encoded
+artifacts, so a package can change while its per-icon list remains unchanged. Conversely, a fully
+shadowed dependency can change the map's composition receipt without changing its effective sprite.
+A clean icon diff is not evidence that the whole map needs no deployment. The report and digest analysis operate on
 generated sprite data; SVG, raster source files, and absolute paths stay on the local machine.
 
 `--json` writes exactly one deterministic schema-version-1 document plus a trailing newline. Its
@@ -35,7 +44,7 @@ stable top-level fields, in order, are:
 ```json
 {
   "schemaVersion": 1,
-  "environment": "production",
+  "environment": "madrid",
   "baseline": {"deploymentId": "dep_...", "package": null, "version": 7},
   "proposed": {"package": null},
   "icons": {"added": [], "removed": [], "modified": [], "unchangedCount": 0},
@@ -47,17 +56,20 @@ stable top-level fields, in order, are:
 
 Package summaries, when present, contain `contentHash`, `iconCount`, `label`, and `totalBytes`.
 A missing hosted baseline is an initial comparison against an empty package. The command compares
-only delivered icon pixels, canonical package manifests, and generated bytes; config-directory
+delivered icon records, canonical package manifests, and generated bytes; config-directory
 provenance and style-reference analysis belong to `icons list` and final style validation.
 
 Normal differences exit 0. Config, compilation, credential, network, response, and report errors
-exit 1.
+exit 1 with diagnostics on stderr, even with `--json`. Invalid or unauthorized baselines are errors,
+not empty packages. `--config` selects a config file; `--api-url` and `--api-key` override hosted
+connection settings. `--cache-dir` selects the artifact cache and `--offline` disables only icon
+hydration: the authenticated hosted baseline request still occurs.
 
 This workflow does not provide OIDC, automatic secret installation, an official
 GitHub Action, an atomic multi-map deploy set, or a Tileflow-hosted remote
 builder.
 
-Docs: https://tileflow.dev/docs/deploy
+Docs: https://tileflow.dev/docs/development-and-deployment/icon-inspection-and-diffs
 
 ### Team credentials and explicit Map targets
 

package/docs/team-icon-sets.md

@@ -8,8 +8,9 @@ independently pinned revisions through `iconSet('@acme/brand')` without copying
 
 Two command families cover this, and the split is deliberate. `icon-set` is a networked Team
 authority that changes the catalog. `icons list` stays local and needs no credential. `icons diff`
-compares prepared output with an active Hosted Map baseline, so it requires `--map-id` and a Map
-credential but never mutates that Map. `install`, `update` and `pin` maintain the exact
+compares prepared output with an active Hosted Map baseline, so it requires `--map-id`, the
+configured map ID in `--against`, and `status:read` authority through personal login or a scoped
+credential, but never mutates that Map. `install`, `update` and `pin` maintain the exact
 `tileflow.icons.lock.json` beside the selected config.
 
 Availability depends on your deployment and your Team's enabled features. Check
@@ -89,7 +90,9 @@ npx tileflow icons pin @acme/brand --version 3 --team @acme --json
 ```
 
 These commands read the `iconSet()` references your config declares. `install` resolves the current
-latest revision for every declared reference that has no pin yet and leaves existing pins alone.
+latest revision for declared references that have no pin yet and leaves existing pins alone.
+Both `install [references...]` and `update [references...]` accept an optional subset; omitted
+selection means every declared reference.
 `update` moves the selected references to their current latest revision; omit the references to
 select every declared one. `pin` selects one exact revision and never resolves a head.
 
@@ -97,7 +100,10 @@ They are the only build-adjacent commands that resolve `latest` or write the loc
 reference is resolved before a single compare-and-swap write of the whole snapshot, so a partial
 lock is never produced and a concurrent writer fails the command rather than losing its pins. An
 undeclared reference is rejected before any request. No lock command rewrites `tileflow.config.ts`;
-add `iconSet('@team/set')` to your config first.
+add `iconSet('@team/set')` to your config first. Lock commands do not hydrate sprite files.
+Serialization retains pins for other declared references and removes stale undeclared references.
+They accept `--config` (or `-c`), `--team`, `--api-url`, `--api-key` and `--json`.
+Do not combine `--team` with an explicit or ambient `TILEFLOW_API_KEY`.
 
 The JSON receipt lists each locked reference with its revision, version ID, package identity and
 content hash, plus any declared reference that is still missing a pin.
@@ -107,7 +113,10 @@ content hash, plus any declared reference that is still missing a pin.
 `validate`, `build`, `preview`, `deploy`, `icons list` and `icons diff` read the lock and compose
 one effective sprite. They never resolve a catalog head, so publishing a newer revision changes
 nothing in a repository until an explicit lock command runs. `--cache-dir` chooses the verified
-artifact cache root; `--offline` fails a cache miss instead of hydrating it.
+artifact cache root on commands that expose it (including `icons list` and `icons diff`);
+`--offline` fails a cache miss instead of hydrating it. These flags are not universal CLI options.
+Other entry points use their documented icon-resolution options or `TILEFLOW_ICON_CACHE_DIR`.
+Offline diff still needs its hosted baseline request.
 
 Hydration downloads only the four public files of the exact pinned artifact, from the trusted
 delivery origin, without credentials and without following redirects. Every file's length,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tileflow",
-  "version": "0.1.0-alpha.7",
+  "version": "0.1.0-alpha.9",
   "license": "Apache-2.0",
   "description": "CLI-only tools for Tileflow config, capture, visual testing, and deploy.",
   "type": "module",
@@ -36,12 +36,12 @@
   },
   "dependencies": {
     "@hono/node-server": "2.0.10",
-    "@tileflow/capture": ">=0.1.0-alpha.24 <0.1.0-beta.0",
+    "@tileflow/capture": ">=0.1.0-alpha.28 <0.1.0-beta.0",
     "@tileflow/coordinates": ">=0.1.0-alpha.1 <0.1.0-beta.0",
-    "@tileflow/coordinates-runtime": ">=0.1.0-alpha.3 <0.1.0-beta.0",
-    "@tileflow/core": ">=0.1.0-alpha.26 <0.1.0-beta.0",
-    "@tileflow/dev": ">=0.1.0-alpha.25 <0.1.0-beta.0",
-    "@tileflow/maps": ">=0.1.0-alpha.4 <0.1.0-beta.0",
+    "@tileflow/coordinates-runtime": ">=0.1.0-alpha.4 <0.1.0-beta.0",
+    "@tileflow/core": ">=0.1.0-alpha.30 <0.1.0-beta.0",
+    "@tileflow/dev": ">=0.1.0-alpha.28 <0.1.0-beta.0",
+    "@tileflow/maps": ">=0.1.0-alpha.7 <0.1.0-beta.0",
     "commander": "^15.0.0",
     "hono": "4.13.5",
     "picocolors": "^1.1.1",