tileflow 0.1.0-alpha.17 → 0.1.0-alpha.19

package/docs/native-artifacts.md

@@ -1,174 +0,0 @@
-# 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` selects the renderer with `--renderer`:
-
-```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 Inspector, 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.
-
-Locally built sprites and fonts are served from the preview's own HTTP origin. Native preview checks
-each generation with that exact origin as its development origin, the same exception the application
-configures below. Resources on any other origin still require HTTPS. `validate` and `build` never
-apply this exception.
-
-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-*` live-comparison 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, removal
-of a browser sky 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

@@ -1,81 +0,0 @@
-# Read-only icon comparison
-
-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.
-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 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 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
-icon; modified cards compare `Before` with `Next`. A script-free 1x/2x selector defaults to 2x,
-switches the embedded density, and renders 1x at half the 2x preview size inside a stable frame so
-the selected state is immediately visible. Package hashes, generated sizes, and icon counts stay in
-collapsed `Details`. A map badge is shown only for a map-scoped report. It exposes no atlas
-implementation UI and contains no API key, remote runtime dependency, original icon source, or
-local source path. Use `--force` to replace different existing report bytes and `--open` only
-together with `--report`.
-
-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
-stable top-level fields, in order, are:
-
-```json
-{
-  "schemaVersion": 1,
-  "environment": "madrid",
-  "baseline": {"deploymentId": "dep_...", "package": null, "version": 7},
-  "proposed": {"package": null},
-  "icons": {"added": [], "removed": [], "modified": [], "unchangedCount": 0},
-  "generatedBytes": {"before": 0, "after": 0, "delta": 0},
-  "artifacts": {"report": null},
-  "hasChanges": false
-}
-```
-
-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
-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 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/development-and-deployment/icon-inspection-and-diffs
-
-### Team credentials and explicit Map targets
-
-A unified Team credential can combine data and Map operations. Use `TILEFLOW_API_KEY` and an
-explicit `--map-id` for deployment, status and hosted icon comparisons. The CLI sends that target
-with style, icon and font requests and verifies the credential covers it. The Hosted API must
-support unified credentials. All Maps includes future Maps; selected Maps is an explicit list.
-A legacy Map key keeps its original binding. Personal CLI login remains separate from machine
-credentials. Credential administration and Team management use the Hosted API or dashboard.

package/docs/team-3d-models.md

@@ -1,36 +0,0 @@
-# Team 3D models
-
-A Team publishes its own 3D building models, such as a store or a kiosk, once, under their names,
-and every map of the Team places them by name. Hosted maps follow each model's current version, so
-publishing an improvement changes every map that places the model on its next load, without
-deploying the maps again. Locally, maps draw their own `.glb` files and need no account.
-
-```sh
-npx tileflow models publish ./models/flagship-store.glb --team @acme --json
-npx tileflow models list --team @acme
-npx tileflow models status flagship-store --team @acme
-npx tileflow models restore flagship-store --team @acme
-```
-
-- `publish [paths...]` prepares each building model as `build` does (its levels of detail, its
-  footprint and meshoptimizer compression) and publishes it as the model's new current version.
-  Paths are `.glb` files or directories; with none, it publishes the building models of every map in
-  the config. Publishing the bytes of the current version again changes nothing.
-- `list` and `status <name>` read the Team's models, their versions and the maps that place them.
-- `restore <name>` makes the previous version current again. A model keeps its current and previous
-  versions.
-- `purge <name> --confirm <name>` deletes a model and its versions, and is refused while a map
-  places it.
-
-Each command needs Team authority: an account session with access to the Team, or a Team API key
-with the 3D models permission (`--api-key`). Pass `--team @team` when the account has several Teams.
-
-`tileflow deploy` uploads no model files. It writes each placement of a building model as the
-placeholder `tileflow://team-models/<name>`, which Hosted replaces with the model's address in the
-map's Team; a model the Team has not published fails the deploy, and the deploy warns when a placed
-model's published version was prepared from other files than the map's. Models are served publicly
-and may be cached, so they must not hold secrets or restricted personal data. MapLibre Native draws
-no models, so a deploy with `--with-native` does not take them.
-
-See [3D buildings](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/buildings-3d.md#building-models)
-for how to prepare a model.

package/docs/team-icon-sets.md

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