tileflow 0.1.0-alpha.6 → 0.1.0-alpha.8

package/docs/agent-icon-composition.md

@@ -9,21 +9,35 @@ npx tileflow icons list --json
 ```
 
 The successful stdout contract is one deterministic JSON document followed by exactly one newline.
-Its top-level fields, in order, are `schemaVersion: 2`, `pathBase: "cwd"`, and `maps`.
-Schema version 2 is a compatibility boundary: removing or renaming a field or changing an enum's
+Its top-level fields, in order, are `schemaVersion: 3`, `pathBase: "cwd"`, and `maps`.
+Schema version 3 is a compatibility boundary: removing or renaming a field or changing an enum's
 meaning requires a new schema version. Additive optional fields require corresponding documentation
-and tests.
+and tests. It replaces version 2's directory-only shape so a locked `iconSet('@team/set')`
+contributor can be represented without inventing a local path.
 
 Each sorted map entry has one `id` and an `icons` value. `icons.kind` is `none` for `icons: []`, or
-`directories` for a prepared ordered composition. A directory entry contains:
+`sources` for a prepared ordered composition. A `sources` entry contains:
 
-- `directories`, in the exact left-to-right authoring order, using config-relative paths or safe
-  `npm:<package>/<path>` descriptors;
+- `contributors`, in the exact left-to-right authoring order. Each has a `kind` of `local`,
+  `package` or `icon-set`, a `label` (a config-relative path, a safe `npm:<package>/<path>`
+  descriptor, or the canonical `@team/set` reference) and the `iconIds` it declares. Filesystem
+  contributors also report `insideWorkingTree`; shared contributors report their exact locked
+  `reference` and integer `version`.
 - `finalIds`, the sorted canonical lower-kebab IDs in the resulting sprite;
-- `replacements`, with the replaced path and winning path for every later exact-ID replacement;
-- `sources`, with the winning ID, cwd-relative path, format, byte length, and intrinsic dimensions;
-- `insideWorkingTree`; and
-- the deterministic generated `packageHash`.
+- `replacements`, naming the replaced and winning contributor export for every later exact-ID
+  replacement, by authored file for filesystem contributors and by `@team/set` for shared ones;
+- `sources`, one entry for each winning ID. A `file` entry carries the cwd-relative `path`, format,
+  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
+- `insideWorkingTree` and the deterministic generated `packageHash`.
+
+Listing reads the exact `tileflow.icons.lock.json` beside the selected config. It never resolves a
+catalog head, so a newly published revision does not change this output until `tileflow icons
+install`, `update` or `pin` changes the lock. `--cache-dir` selects the verified artifact cache root
+and `--offline` fails a cache miss instead of hydrating it.
 
 There is deliberately no parallel catalog registry, provider kind, semantic mapping, external
 sprite branch, or arbitrary source-to-runtime renaming. `<id>.<ext>` publishes `<id>` and the
@@ -37,8 +51,9 @@ 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, network request, browser/server launch, or file
-write. It removes an ambient `TILEFLOW_API_KEY` before importing config. As with every config-aware
+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
 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

@@ -8,11 +8,23 @@ Start with the [tileflow guide](https://github.com/tileflow/tileflow-sdk/blob/ma
 | Map authoring     | `init`, `validate`, `inspect`, `explain`, `semantic-diff`, `build`, `preview` (`dev` alias)    |
 | Local evidence    | `setup capture`, `capture`, `visual compare`, `visual analyze`, `visual diff`, `visual update` |
 | Data and assets   | `tileset inspect`, `tileset publish/list/status/purge`, `inspect features`, `icons list/diff`  |
+| Team Icon Sets    | `icon-set publish/list/status/versions/uses/archive/unarchive/purge`                           |
+| Repository locks  | `icons install`, `icons update`, `icons pin`                                                   |
 | Account           | `login`, `logout`, `whoami`                                                                    |
 | 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
+`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).
 
 The CLI retains the hidden `projects` command family as a compatibility and support surface for the
 internal application boundary. It is not part of the ordinary workflow or the product catalog.

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/team-icon-sets.md

@@ -0,0 +1,121 @@
+# Team Icon Sets and repository locks
+
+Start with the [tileflow guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/cli/README.md) for installation and a complete first example.
+
+A Team Icon Set is a named catalog resource such as `@acme/brand`. Publishing creates an immutable
+integer revision of the four generated sprite files. Maps in different repositories consume
+independently pinned revisions through `iconSet('@acme/brand')` without copying original artwork.
+
+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
+`tileflow.icons.lock.json` beside the selected config.
+
+Availability depends on your deployment and your Team's enabled features. Check
+`npx tileflow icon-set --help` for the installed command surface.
+
+## Authorize a Team
+
+Catalog commands need Team authority. Either sign in and let the CLI exchange your account session
+for a short-lived Team capability, or pass a Team data key:
+
+```sh
+npx tileflow login
+npx tileflow icon-set list --team @acme --json
+```
+
+Reads request `icons:read`; publication, archive state and purge request `icons:write`. A
+Map-scoped deploy key never gains catalog authority, and `--team` is rejected together with
+`--api-key` because a Team data key already selects its Team.
+
+## Publish a revision
+
+```sh
+npx tileflow icon-set publish ./icons --id brand --team @acme --idempotency-key brand-2026-09-14 --json
+```
+
+`publish` compiles exactly one repository-relative directory into `sprite.json`, `sprite.png`,
+`sprite@2x.json` and `sprite@2x.png`, then uploads those four files under one durable retry key.
+The first successful publication creates the set. Republishing identical bytes reports
+`"publication": "unchanged"` and returns the same revision rather than a new integer. Repeating an
+uncertain request with the same `--idempotency-key` returns its original result instead of creating
+extra history.
+
+`--name` and `--description` set bounded catalog display metadata after the immutable revision is
+confirmed. If that metadata update fails, the revision remains published; rerun the same command to
+retry the display update.
+
+The JSON receipt reports the Team, the canonical reference, the immutable revision and version ID,
+the package identity, the content hash, the byte count and whether the publication changed
+anything. It contains no credential, source path, or original artwork.
+
+## Inspect and manage the catalog
+
+```sh
+npx tileflow icon-set list --team @acme --json
+npx tileflow icon-set status brand --team @acme --json
+npx tileflow icon-set versions brand --team @acme --json
+npx tileflow icon-set uses brand --team @acme --json
+npx tileflow icon-set archive brand --team @acme --json
+npx tileflow icon-set unarchive brand --team @acme --json
+```
+
+Reads follow bounded cursors and reject a repeated page, a duplicate row or an unsafe page count.
+`uses` reports the known hosted deployments that retain a revision; its
+`includesUndeployedRepositoryLocks` field is always `false`, because a repository lock that was
+never deployed is not discoverable by the catalog. Archiving prevents new publication and implicit
+discovery while retained consumers keep working.
+
+## Purge an exact revision
+
+```sh
+npx tileflow icon-set purge brand --version 3 --team @acme \
+  --idempotency-key purge-brand-3 --confirm '@acme/brand@3' --acknowledge-unknown-locks --json
+```
+
+Purge needs all four guards: an exact positive `--version`, a durable `--idempotency-key`, a
+`--confirm` value repeating the exact `@team/set@version`, and `--acknowledge-unknown-locks`.
+The acknowledgement is not a formality. Purge tombstones the publication hold and keeps retained
+deployment holds, including fully shadowed dependencies; it cannot discover undeployed repository
+locks and cannot revoke public bytes that were already downloaded.
+
+## Maintain the repository lock
+
+```sh
+npx tileflow icons install --team @acme --json
+npx tileflow icons update @acme/brand --team @acme --json
+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.
+`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.
+
+They are the only build-adjacent commands that resolve `latest` or write the lock. Every requested
+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.
+
+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.
+
+## Build, preview and deploy against the lock
+
+`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.
+
+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,
+checksum, sprite index, PNG geometry and per-icon pixel hashes are verified before use.
+
+Deploy uploads the effective composed package and sends the same ordered composition receipt in the
+build manifest and the request body, bound to that package's content hash. A referenced source
+revision is never re-uploaded by a deploy.
+
+Offline composition is not an offline map. Remote tiles, glyphs and other external resources keep
+their own requirements.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tileflow",
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.0-alpha.8",
   "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.23 <0.1.0-beta.0",
+    "@tileflow/capture": ">=0.1.0-alpha.25 <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.25 <0.1.0-beta.0",
-    "@tileflow/dev": ">=0.1.0-alpha.24 <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.27 <0.1.0-beta.0",
+    "@tileflow/dev": ">=0.1.0-alpha.26 <0.1.0-beta.0",
+    "@tileflow/maps": ">=0.1.0-alpha.5 <0.1.0-beta.0",
     "commander": "^15.0.0",
     "hono": "4.13.5",
     "picocolors": "^1.1.1",