tileflow 0.1.0-alpha.8 → 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/command-families.md

@@ -21,8 +21,10 @@ Metro remains the React Native JavaScript development server. See
 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/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.8",
+  "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.25 <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.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",
+    "@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",