tileflow 0.1.0-alpha.18 → 0.1.0-alpha.19

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

@@ -1,237 +0,0 @@
-# Hosted authentication and deploy
-
-Start with the [tileflow guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/cli/README.md) for installation and a complete first example.
-
-Hosted writes have two independent authorization paths:
-
-- Personal developer session: run `npx tileflow login` once for a
-  Tileflow API origin. Login authenticates the account and selects no Map.
-  Map commands exchange it for a brief Map capability; tileset commands use a separate Team data
-  capability.
-- CI key: create a dashboard `CI deploy` key, store it as
-  `TILEFLOW_API_KEY`, and let the repository workflow deploy without a local login. The server
-  binds that key to exactly one Map.
-
-Hosted control-plane requests stay pinned to the configured HTTP(S) origin, apply a hard bounded
-timeout, and stream at most 1 MiB of response data. CLI diagnostics never echo an untrusted remote
-response body or bearer credential.
-
-Inspect the account, then target the Map shown in the dashboard:
-
-```sh
-npx tileflow whoami --json
-npx tileflow deploy --map-id map_AbCdEfGhIjKlMnOp
-npx tileflow status --map-id map_AbCdEfGhIjKlMnOp
-npx tileflow logout
-```
-
-Changing or resetting the hosted account password revokes saved personal CLI sessions. The next
-account or hosted command stops with a clear message and asks you to run `tileflow login` again.
-Project API and CI keys are independent project credentials and are not removed by a personal
-password change.
-
-## Create the Map from the terminal
-
-After `tileflow login`, the CLI can create the Map itself; nothing has to be copied from the
-dashboard. Run `deploy` without `--map-id`, or create the Map first with `maps create`:
-
-```sh
-npx tileflow login
-npx tileflow deploy --origin https://www.example.com
-npx tileflow maps create --any-website --json
-```
-
-The new Map belongs to a Team you administer. When you administer exactly one Team that can add a
-Map, the CLI uses it; when several can, it asks, or takes `--team @team`; when none can, it stops
-and says why (no administered Team, or every Team has reached its Map limit).
-
-Browser access is always an explicit choice: `--origin` with an exact website origin such as
-`https://www.example.com` (repeat it for up to 20 sites), or `--any-website`. Paths, wildcards and
-bare host names are rejected. On a terminal the CLI asks; without one (for example when an agent
-runs it), a missing choice stops before anything is created and names the flags. Browser access
-is stored with the Map in Tileflow and can be changed in the dashboard; it is never written to the
-repository.
-
-`deploy` creates the Map only after the local config, assets and styles pass, then publishes to it
-in the same run and prints `tileflow deploy --map-id <mapId>` for later deploys. If the manifest
-already records a Map for that repository map, `deploy` stops and shows that command instead of
-creating another Map. Each creation prints a setup key; rerunning an interrupted command with
-`--setup-key <key>` returns the same Map instead of a second one.
-
-Map creation uses only the personal session. With `TILEFLOW_API_KEY`, `--api-key`, `--with-native`,
-or in CI, `deploy` requires `--map-id`.
-
-## Deploy to an existing Map
-
-A Map created in the dashboard, or by an earlier CLI run, is deployed with its exact Map ID. If the
-config contains several maps, select the authored map explicitly:
-
-```sh
-npx tileflow deploy \
-  --map-id map_AbCdEfGhIjKlMnOp \
-  --map store-locator
-```
-
-The Map ID is a public destination, not a credential. A successful server-confirmed deploy keeps
-unrelated manifest entries and records that Map's stable ID, hosted theme URLs, World `v1`
-generation, and fixed session usage mode. Browser access remains server-owned and is never read
-from or written to repository configuration. Do not add an API key or payment authority to a copied
-prompt.
-
-Team tileset commands exchange the same account session for a separate Team-scoped data capability;
-it carries no Map authority. Inspect and preview remain account-free:
-
-```sh
-npx tileflow tileset inspect ./data/stores.pmtiles --json
-npx tileflow tileset inspect ./data/stores.pmtiles \
-  --include-values category,status --json
-npx tileflow tileset publish ./data/stores.pmtiles \
-  --id stores --team @acme --attribution 'Store data © Example' --json
-npx tileflow tileset list --team @acme --json
-npx tileflow tileset status stores --team @acme --json
-```
-
-Inspection schema 1 separates authoritative PMTiles/TileJSON declarations from bounded MVT
-observations. Sampled fields report present/missing feature counts, observed distinct-value counts,
-numeric min/max, and truncation. Raw primitive values remain absent unless `--include-values`
-explicitly selects their comma-separated field names; the command emits at most 16 values per field,
-32 selected fields, and 256 characters per string. `--no-sample` returns only authoritative metadata
-and cannot be combined with value inspection. Directory traversal recomputes addressed-tile and
-tile-entry counts; the header's tile-content count is reported only as a nullable declaration and is
-not treated as authority.
-
-`publish --id` names a Team-local logical resource; Tileflow owns its opaque delivery ID. The
-command validates the archive locally before authentication, hashes it in fixed 16 MiB parts, then
-uploads at most four parts concurrently without buffering the complete file. Interrupted sessions
-remain resumable for 24 hours: rerunning the same command reconciles server receipts and transfers
-only missing parts. Normal Queue initialization is polled for at most two minutes before the command
-returns a resumable availability error. Retryable transfer failures receive fresh short-lived authorization; a changed
-local file stops before completion. Free accepts versions through exactly 2,000,000,000 bytes and
-Starter through exactly 4,000,000,000 bytes, subject to the Team's hosted-storage capacity.
-
-Publication completes only after server-side integrity and PMTiles validation. A compatible new
-version becomes current at the same stable TileJSON and tile URLs, so newly resolved browser
-requests see it without creating a Map deployment. Purge requires `--confirm <exact-id>` and fails
-with bounded dependency context while any retained Map deployment uses the resource. Automation may set a Team data
-`TILEFLOW_API_KEY`; that key selects its Team, so commands omit `--team` and never load account
-state.
-
-`tileset publish --json` emits schema version 2 with the Team selector when known, logical and
-opaque tileset identities, immutable version ID and number, exact byte count, content-hash
-algorithm/hash, final state, and `changed` or `unchanged` publication result. It never emits the
-local path, upload session, storage key, signed URL, ETag, credential, or retry details.
-
-An explicit key or `TILEFLOW_API_KEY` never uses the saved account session. The deploy API rejects a
-`--map-id` that does not match the key. Read-only hosted icon comparison validates the same binding
-before loading its baseline.
-
-A deploy-only key grants `styles:write` and `status:read`. Without additional permissions it cannot upload
-datasets or render images. Give it an expiration, rotate the repository secret
-before it expires, and avoid non-expiring CI keys.
-
-Detected CI never falls back to the credential saved by `tileflow login`: if
-`TILEFLOW_API_KEY` is absent, deploy stops before loading config or making a
-request. Once captured, the key is hidden from `process.env` and `--api-key` is removed from the
-temporary `process.argv` view before the CLI imports executable `tileflow.config.ts`; both process
-surfaces are restored after the protected operation. Every config-aware command uses the same
-scope, including validate, build, dev/watch, capture, visual, inspect, icon inspection, and deploy.
-This is defense in depth, not a sandbox; deploy only reviewed repository code on a trusted runner,
-and do not pass keys through the `--api-key` command line in CI.
-
-The [deploy documentation](https://tileflow.dev/docs/deploy) contains copyable
-GitHub Actions and GitLab CI workflows. Both use `npm ci`, the committed
-lockfile, and the repository-local CLI. GitHub exposes the key only to its deploy
-step. GitLab variables are job-scoped, so its example validates in a keyless job
-and deploys in a protected `production` job; the locked install and runner are
-part of that trusted job boundary. Both serialize publications and intentionally
-omit path filters because `tileflow.config.ts` can import arbitrary repository
-files.
-
-The CLI records bounded private provenance for GitHub Actions, GitLab CI,
-generic CI, and local runs. These provider fields are descriptive client
-reports, not OIDC attestations. Provider values can be overridden with:
-
-```txt
-TILEFLOW_DEPLOY_REPOSITORY
-TILEFLOW_DEPLOY_REVISION
-TILEFLOW_DEPLOY_REF
-TILEFLOW_DEPLOY_RUN_ID
-TILEFLOW_DEPLOY_RUN_URL
-```
-
-Invalid explicit values fail before a network write. Provider metadata that is
-missing, malformed, or too long is omitted. Secrets and the complete
-environment are never logged.
-
-A separate app-build step is absent from the minimal workflows. Self-hosted build and deploy emit the same
-runtime manifest version 1 shape; Hosted fields are optional identity metadata on its map/theme
-entries. Filesystem build writers refuse to replace a manifest carrying Hosted metadata by default,
-and deploy refuses to replace a purely local manifest. Prefer `emitBuildArtifacts: false` or
-separate output paths when the app deliberately packages a deploy manifest. The explicit
-`overwriteHostedManifest: true` build option and
-`tileflow deploy --overwrite-self-hosted-manifest` flag authorize that destination replacement. A
-retry of the same compiled theme family reuses its deployment version and prints `Unchanged`;
-changed cartography prints `Published` with a new version. Allowed websites is managed separately
-in Tileflow and is never read from repository config. The
-fingerprint binds resource references, not the changing bytes behind referenced
-glyph or sprite URLs. Every theme of one logical map publishes atomically; separate maps can still
-partially succeed when no remote batch release is used.
-
-All config, theme-style, icon, and compatibility preflight happens before the first style write. After
-that boundary the current Hosted API has no batch commit across repository-internal orchestration:
-one singular config can publish before a later config fails. The orchestrator then leaves the
-previous local manifest untouched, reports which publications succeeded, and tells the operator to
-retry; idempotent publication converges on that retry. The local manifest
-writer uses a durable same-directory temporary followed by direct rename and directory sync, so
-readers see either the previous or next complete manifest. Multi-file artifact writers remain
-rollback-capable sets. Neither mechanism is a remote transaction or can make several API writes
-all-or-none.
-
-Deploy treats the locally compiled MapLibre Style family as one logical-map artifact. The request
-contains an exact `styles[theme]` collection, per-theme canonical SHA-256 identities in the build
-manifest, only bounded hosting policy that does not belong in MapLibre itself, and the exact managed
-icon-package identity when the family has one. Delivery
-policy is not inherited with cartographic fields. Deploy does not serialize the module
-configuration, send a public `tileset` selector, or ask the hosted API to compile the map again.
-Hosted publication currently requires Tileflow World; `vectorTiles()` remains available for local
-builds and previews but fails deploy before any remote write. The API binds recognized
-Tileflow-owned world and terrain URLs to its generated map ID. A successful response must return
-exactly the submitted theme names and a hosted Style URL for each. Deploy writes strict runtime
-manifest version 1 with stable theme URLs, `colorScheme`, content revision, optional font faces and
-style IDs, rather than duplicating dataset configuration. No older manifest is normalized.
-
-For a map with `icons: ['./icons']`, hosted validation compiles the local SVG/PNG/JPEG/WebP files
-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 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
-generated byte total, one opaque `icp_<id>`, and the corresponding query-free
-`/sprites/<id>/sprite` URL. The CLI rejects any missing or divergent field before using that URL.
-
-Hosted deploy currently rejects local or package-owned web fonts before authentication or remote
-writes. Use self-hosted delivery or an explicit public glyph provider. Enabling managed font bundles
-requires a separately deployed ownership, quota, retention, and immutable-delivery contract.
-
-A map's own 3D building models (the building models of its `models` directories) are its Team's
-3D models, which `tileflow models publish` publishes by name. Deploy uploads no model files: it
-compiles each placement's `url` as the placeholder `tileflow://team-models/<name>`, leaves the
-building models out of the build's assets and model source identities, so the map's revision binds
-their names and not their bytes, and sends `teamModelSources`, the SHA-256 and size of each glTF
-binary a model was prepared from. Hosted replaces each placeholder with the model's address in the
-map's Team, which follows the model's current version, and fails the deploy for a model the Team has
-not published. The response's `teamModels` names each placed model's current version and whether it
-was prepared from the same files (`match`, `differ` or `unknown`); the CLI warns on `differ`. A
-deploy with `--with-native` rejects a map's own building models, because MapLibre Native draws no
-models.
-
-For every managed resource kind, `assetSetSha256` remains a separate per-map output identity. It
-hashes each generated file's exact portable name, media type, byte count, and SHA-256 using Core's
-asset-set v1 contract; it does not hash only the icon-package manifest. Hosted must
-confirm the immutable resource bytes, reconstruct those same per-file identities (including the
-`icons/<mapId>/` and `models/<mapId>/` prefixes), and reject the Style when the submitted
-build-manifest hash diverges.

package/docs/inspect-vector-features.md

@@ -1,19 +0,0 @@
-# Inspect vector features
-
-Start with the [tileflow guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/cli/README.md) for installation and a complete first example.
-
-See which bounded source features the exported map sees near a camera before tuning taxonomy,
-density, or labels:
-
-```sh
-npx tileflow inspect features \
-  --center=-3.6927512,40.4086555 --zoom=16 \
-  --layers=poi --properties=name,category,type,icon,filter_rank,size_rank --json
-```
-
-The command supports HTTP(S) TileJSON/vector sources and returns only requested properties plus
-geometry summaries in stable order. Viewport, tiles, bytes, scanned/returned features, names, and
-timeouts are bounded. Safe provenance includes origins, a query-free TileJSON path, and configured
-source revision or `null`; credentials, URL queries, hidden properties, response bodies, and
-absolute paths are omitted. It is read-only apart from executable config's own possible side
-effects and removes `TILEFLOW_API_KEY` before loading config.

package/docs/local-visual-feedback.md

@@ -1,268 +0,0 @@
-# Local visual feedback
-
-Start with the [tileflow guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/cli/README.md) for installation and a complete first example.
-
-Explore with capture itself. The first run may install Playwright's exact pinned Chromium headless
-shell into its versioned per-user cache:
-
-```sh
-npx tileflow capture \
-  --map madrid \
-  --theme dark \
-  --center=-3.69201,40.40871 \
-  --zoom=16.15 \
-  --width=1200 \
-  --height=1200 \
-  --json
-```
-
-The successful entry includes a normalized `definition` with its concrete `theme`, `camera`,
-`viewport`, and default map `target`. Copy it under a chosen `scenes.<name>` key; the CLI never rewrites
-executable TypeScript config. Then commit the bounded scene so agents and CI render the same map,
-camera, and viewport:
-
-```ts
-import {defineMap} from '@tileflow/core';
-import {streets} from '@tileflow/maps';
-
-export default defineMap({
-  id: 'madrid',
-  name: 'Madrid',
-  version: 1,
-  extends: streets,
-  scenes: {
-    'madrid-desktop': {
-      theme: 'dark',
-      camera: {type: 'center', center: [-3.7038, 40.4168], zoom: 12},
-      viewport: {width: 1280, height: 800, dpr: 1},
-    },
-    'madrid-product': {
-      theme: 'dark',
-      camera: {type: 'center', center: [-3.7038, 40.4168], zoom: 12},
-      viewport: {width: 390, height: 844, dpr: 2},
-      target: {
-        kind: 'application',
-        path: '/maps/madrid',
-        captureId: 'product-map',
-      },
-    },
-  },
-});
-```
-
-`scenes` is tooling metadata owned by this map. It is not inherited and does not enter the
-cartographic compiler; tooling supplies the exported map ID when it normalizes a scene internally.
-Every scene stores a concrete theme; omission and browser-only `system` are invalid.
-
-### Live comparison in Inspector
-
-Use the ordinary preview server with a right-hand selection to compare two maps or themes while
-authoring:
-
-```sh
-# Two maps or themes from one config.
-npx tileflow preview \
-  --map baedeker --theme light \
-  --against-map map-1777 --against-theme light
-
-# Or compare against another config.
-npx tileflow preview \
-  --config ./candidate.config.ts --map candidate \
-  --against-config ./reference.config.ts --against-map reference
-```
-
-Any `--against-*` option opens Inspector in comparison mode. Both previews remain same-origin and share
-one synchronized camera. The toolbar switches between side-by-side, split, opacity overlay, and
-blink modes; the selected mode, camera, split, opacity, and active interaction side survive in the
-URL. Each config has its own watched, last-known-good session, so an invalid edit shows bounded
-diagnostics without discarding the last valid map and recovers automatically after a fix.
-
-Enable **Inspect** and click a rendered feature to see its bounded feature data, paint/layout values,
-zoom-curve samples, and compiler contribution sidecar. The sprite gallery shows the compiled atlas,
-not source directories. **Copy scene** produces a concrete-theme scene for the current camera and
-viewport; **Copy command** produces the corresponding capture command. The inspector sidecar exists
-only in memory in the local Inspector session and is not emitted by `tileflow build`.
-
-### Reproducible two-style review
-
-For shareable evidence with exact pixels, use headless capture instead of the live preview:
-
-```sh
-npx tileflow visual compare \
-  --config ./candidate.config.ts --map candidate --theme light \
-  --against-config ./reference.config.ts --against-map reference --against-theme light \
-  --center=-3.7038,40.4168 --zooms=12,14,16 \
-  --width=1200 --height=800 --dpr=1 --region=0,0,1200,760 \
-  --diff --open --json
-```
-
-`--against-config` is explicit and may name the same config. Both sides use one camera, viewport,
-DPR, ordered zoom matrix, pinned browser session, and concrete theme. At most 16 zooms and 64 MiB
-of aggregate embedded PNG data are accepted; an earlier preflight also caps the matrix at
-67,108,864 aggregate physical pixels. The default transaction writes
-`.tileflow/comparisons/compare.html`, a machine-readable sibling JSON document, and PNG/receipt-v4
-pairs below `compare.assets`; `--diff` adds a highlighted diff when identities are comparable. The
-HTML embeds every image, uses a restrictive CSP, performs no network request, and offers the same
-side-by-side, wipe, overlay, and blink review modes.
-
-`--region=x,y,width,height` selects one shared physical-pixel rectangle for compact appearance
-profiles. Review JSON uses the explicit signed direction `rightMinusLeft`; the region does not crop
-captures, changed-pixel metrics, or diffs.
-
-Stdout and the sibling JSON use the same schema-version-1 `visual.compare` document: concrete
-left/right selections, shared camera and viewport, zoom-sorted rows with Review v1 documents and
-relative artifact paths, report/document paths, and sorted warnings. This document and the watch
-NDJSON described below are versioned compatibility boundaries.
-
-The asset directory also contains a bounded schema-version-1
-`.tileflow-visual-compare.json` inventory. It assigns ownership only to the listed sibling assets
-and records each exact SHA-256. A later successful transaction removes stale generated rows or
-diffs only when that valid prior inventory names them, preserves unrelated files, and refuses a
-managed asset that has been modified, replaced by a symlink/non-file, or grown beyond its bound.
-`--force` does not weaken those ownership checks. The inventory is capped at 64 KiB and the complete
-report, JSON, inventory, PNGs, receipts, stale cleanup, and optional diffs commit or roll back as one
-file transaction.
-
-Different pixels are ordinary review evidence and exit 0. A frame, dimension, runtime, or exact
-data mismatch exits 1 and suppresses pixel metrics because the images are not comparable.
-`--allow-data-mismatch` keeps a data-mismatch report inspectable with exit 0, but does not invent
-pixel metrics. `--watch` observes both configs, cancels stale renders, preserves the last complete
-report through invalid edits, and emits deterministic NDJSON with `--json`. An explicit report path
-requires `--force` in watch mode; the managed default path is safely replaceable.
-
-Watch events are `watching`, `building`, `invalid`, `recovered`, `generation-complete`, `failed`,
-and `stopped`, with monotonic comparison generations and source-side generations where applicable.
-Without `--allow-data-mismatch`, an incompatible generation emits `failed`, does not replace the
-last complete report, and remains an unresolved failure; an allowed data mismatch emits
-`generation-complete` but still has no pixel metrics. An orderly stop exits 0 only after at least
-one complete generation and no unresolved invalid or failed state; otherwise it exits 1.
-
-Render one checkpoint, or recapture after every edit:
-
-```sh
-npx tileflow capture madrid-desktop --json
-npx tileflow capture --all --json
-npx tileflow capture madrid-desktop --watch --json
-```
-
-Use the first command when you want a single image and the last command while refining a map. Watch
-mode stays open, follows changes to the config, its local imports, and its effective icons and fonts,
-and writes a new PNG after each valid edit. Keeping the browser ready makes repeated renders faster.
-If an edit is invalid, the last good image remains in place and capture resumes automatically after
-the fix. Stop watch mode with `Ctrl+C`. It accepts named committed scenes or `--all`, not exploratory
-camera options.
-
-Standalone scenes need no app server, account, API key, MCP service, system Chrome, or visible
-window. The first command—or the first capture—may provision Playwright's pinned Chromium headless
-shell in its versioned per-user cache. `--no-browser-install` makes a prepared/offline environment
-strict. Tileflow never falls back to a system browser or packages the browser in npm.
-
-For prepared or offline CI, install ahead of time with
-`npx tileflow setup capture --json`. Use `setup capture --no-browser-install` or
-`capture --no-browser-install` as an enforcement check that the exact shell is already cached.
-
-For an application scene, its route and component props must render the committed camera. Tileflow
-uses the camera in scene identity but does not mutate arbitrary application map state.
-
-One-shot success JSON is one deterministic schema-version-1 document plus one newline. It contains
-sorted scene/map/theme/target entries, relative output and receipt paths, image hash/dimensions/DPR,
-renderer identity, remote-dependency state, and warnings; it contains no image bytes, credential,
-origin, absolute path, user, or timestamp. Managed output is an atomic pair under
-`.tileflow/captures/<scene>.png` and `<scene>.receipt.json`. `tileflow init` ignores managed captures
-and `.tileflow/diffs` when creating a new `.gitignore`. Explicit output replacement requires
-`--force`; symlinks and path escapes fail closed.
-
-Each written receipt uses capture schema v4 and records the concrete theme. A Tileflow World
-capture resolves its TileJSON once for
-the whole capture session and records the exact `world-v1` release plus descriptor, archive, data
-contract, and product-contract hashes. All selected scenes and retries therefore use one immutable
-World release even if `current` moves while the command is running.
-
-One-shot `--json` failures leave stdout empty and write exactly one deterministic failure document
-to stderr with `code`, `phase`, bounded diagnostics, and optional origin-only resource metadata.
-
-Watch JSON is NDJSON with monotonic `building`, `invalid`, `recovered`, `captured`, `failed`, and
-`stopped` generation events. It watches config, transitive local imports, and effective icon/font
-files, preserves the last good capture through invalid edits, cancels stale work, and reuses one
-headless Browser. An orderly stop exits 0 only after a successful capture with no unresolved
-terminal failure.
-
-### Capture through the real application
-
-Application scenes use the app's existing Vite, Next.js, Webpack, or custom loopback server. Start
-only that normal server; Tileflow does not run a package script, scan ports, or start
-`tileflow preview`:
-
-```sh
-npm run dev
-TILEFLOW_APP_ORIGIN=http://127.0.0.1:3000 \
-  npx tileflow capture madrid-product --json
-```
-
-The React, Vue, and Svelte wrappers expose `data-tileflow-map`, the resolved concrete
-`data-tileflow-theme`, optional `data-tileflow-capture-id`, and
-`data-tileflow-state="loading|idle|error"`. The headless client selects exactly one target, verifies
-the theme, and waits for idle. Use `--url` for one explicit full loopback URL, `--selector` to
-override target selection, and `--frame map|viewport` to override framing. Origins and URLs must be
-credential-free loopback HTTP(S) without fragments. Each navigation uses a fresh context without a
-reused profile, cookies, local storage, or service workers.
-
-### Match a reference and protect the result
-
-While refining a style, compare the current scene with any reference screenshot:
-
-```sh
-npx tileflow visual analyze madrid-desktop \
-  --reference ./design-reference.png --region=0,0,1200,760 --json
-```
-
-`visual analyze` renders exactly one committed scene and writes the current image and a JSON report
-under `.tileflow/analysis` by default. The report includes both images' dimensions and dominant
-colors. When their physical dimensions match, it also includes exact and perceptual pixel metrics,
-mean channel difference, a high-contrast `.diff.png`, and signed
-`appearance.actualMinusReference` luminance, OKLab, edge-density, and local-contrast evidence. The
-optional region affects only those appearance metrics. The reference PNG is never modified or
-treated as a baseline.
-
-Once the map is approved, save it as the expected baseline and use that image to catch later
-regressions:
-
-```sh
-# Save the reviewed current render as the expected baseline.
-npx tileflow visual update madrid-desktop \
-  --baseline-dir test/visual-baselines --json
-
-# Compare a fresh render without changing the baseline.
-npx tileflow visual diff madrid-desktop \
-  --baseline-dir test/visual-baselines --json
-
-# Or apply the operation to every committed scene.
-npx tileflow visual diff --all \
-  --baseline-dir test/visual-baselines --json
-
-# In CI, return exit 2 when the pixels have changed.
-npx tileflow visual diff madrid-desktop \
-  --baseline-dir test/visual-baselines --fail-on changed --json
-```
-
-`visual diff` and `visual update` require either one or more positional scene names or `--all`;
-those forms are mutually exclusive. `visual analyze` always accepts exactly one scene.
-
-The baseline directory holds the reviewed expected PNG and its receipt. The files generated by a
-comparison are working evidence: the current `.actual.png`, a transparent high-contrast
-`.diff.png` when comparable, and a `.visual.json` report under `.tileflow/diffs` by default.
-`visual diff` may replace those working files on each run, but it never changes the baseline. This
-separation prevents a check from silently accepting the change it was meant to reveal.
-
-Before comparing, `visual diff` validates the baseline PNG and receipt, including their hashes,
-dimensions, runtime, and scene identity, without executing or fetching baseline metadata.
-Statuses are `unchanged`, `changed`, `missing-baseline`, `scene-mismatch`, and `runtime-mismatch`.
-Same-size images report exact RGBA changed pixels and an informational fixed-threshold perceptual
-metric; exact inequality determines changed.
-
-Changed pixels exit 0 by default so a person or agent can inspect the working files.
-`--fail-on changed` exits 2 for CI; missing or incompatible baselines and operational failures exit 1.
-
-Run `visual update` again only after reviewing and accepting the new render. It is the only
-command that creates or changes baseline pairs, and it never stages, commits, or pushes. Remote
-tiles, glyphs, and sprites are reported because their pixels can change independently of the style.

package/docs/map-authoring.md

@@ -1,132 +0,0 @@
-# Map authoring workflow
-
-Install the CLI and your map's dependencies in your project as described in the
-[CLI guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/cli/README.md).
-Run these commands from that project directory, with a trusted `tileflow.config.ts`.
-Discovery and saved-capture comparison also work without a config.
-
-## Discover the language and inspect a change
-
-Use four primary command groups for map development:
-
-| Command    | Purpose                                                                                                                             |
-| ---------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `describe` | Discover the generated language and query one domain or schema fragment.                                                            |
-| `inspect`  | Read resolved configuration; `compiled`, `features`, `icons`, and `tileset` inspect output/data; `session` reads Inspector context. |
-| `capture`  | Render reproducible evidence and return a reusable capture ID.                                                                      |
-| `compare`  | Compare saved capture IDs; `configs`, `styles`, `reference`, and `baseline` cover other comparisons.                                |
-
-`preview` opens Inspector. `init`, `validate`, and `build` remain project utilities;
-`visual update` is the explicit operation that approves baselines. All these tools work from an
-independent project with its own map and data; official maps are optional.
-
-Start with bounded queries, then request more detail at the returned JSON Pointers:
-
-```sh
-npx tileflow describe --json
-npx tileflow describe roads --path /properties/classes --json
-npx tileflow describe themes --json
-npx tileflow inspect --domain roads --limit 80 --json
-npx tileflow inspect compiled --domain roads --theme dark --json
-npx tileflow compare configs --from-config before/tileflow.config.ts --to-config after/tileflow.config.ts --json
-```
-
-`describe` needs no project or network. It reads the generated schema and manifest, with `--ref`
-for an exact local schema reference, `--path` for an RFC 6901 JSON Pointer, and `--limit`/`--depth`
-for bounded tree projections. `projection.truncated` and `projection.omitted` explicitly identify
-missing detail; omitted pointers are relative to the selected data. These fragments are discovery
-results, not standalone validation schemas. Examples and expression syntax remain in the generated
-contracts and package guides. Config inspection supports the same bounds; without projection
-options it preserves the complete legacy result.
-
-Legacy aliases remain available: `explain` → `inspect compiled`, `semantic-diff` → `compare configs`,
-`icons list` → `inspect icons`, `tileset inspect` → `inspect tileset`, and `visual compare/analyze/diff`
-→ `compare styles/reference/baseline`. Aliases share implementations and retain their established
-versioned JSON document formats. `language manifest` returns
-the raw authoring manifest (schema version 2); `language schema` returns the raw generated config
-reference (version 4). Use their versions and schema references when consuming the output.
-
-`validate`, `inspect`, `explain`, and `semantic-diff` return one version-1 command envelope on
-stdout. JSON-mode failures leave stdout empty, write one structured failure to stderr, and exit
-nonzero. Diagnostics include `phase`, `code`, `path`, `severity`, `message`, and `suggestion`.
-A non-empty semantic diff is informational, not a command failure.
-
-Inspection includes resolved inheritance, merge provenance, and the theme contract. `explain`
-returns compilation diagnostics and a report, not the complete Style JSON. Add `--inspection` only
-when physical output provenance is needed; those layer IDs are not stable authoring targets.
-
-`describe themes` lists the minimal palette roles and optional time-of-day behavior. Compiled
-inspection includes `report.decisions` for resolved color roles and selected module defaults,
-with the effective value, source, reason and override guidance. Query it with
-`inspect compiled --path /report/decisions --limit 80 --json`. It describes semantic decisions,
-not every final paint property; config inspection retains inheritance provenance separately.
-
-For a normal config, map selection is implicit. Paired `--from-config` and `--to-config` compare
-two ordinary configs. Workspace comparisons use their documented explicit map selectors; do not
-mix the paired-config and same-workspace forms.
-
-## Reuse capture evidence
-
-Every still capture saves an immutable record under `.tileflow/captures/records` and returns its
-full `captureId` in JSON (or prints it in human output). Keep the ID before editing, capture again,
-then compare the two IDs:
-
-```sh
-npx tileflow capture madrid --json
-# Edit the map, then capture the same scene again.
-npx tileflow capture madrid --json
-npx tileflow compare --before <before-capture-id> --after <after-capture-id> --json
-```
-
-Replace the placeholders with the full IDs from the two capture results. This comparison loads
-only saved evidence: no config evaluation, compilation, browser startup, or network access.
-`--capture-dir` selects another record directory; `--diff <path>` writes a contextual PNG diff.
-Records verify their JSON, PNG, receipt, and scene hashes. Different cameras, viewport dimensions,
-renderers, or data identities produce a mismatch and nonzero exit instead of misleading pixel
-metrics. A visual difference between comparable captures is informational. Records remain until
-you remove their directory; moving only the mutable scene PNG does not move its saved record.
-
-For repeated capture use `capture --watch`; it reuses the artifact session and browser. Config
-inspection does not render; `compare configs` compares semantic authoring without rendering.
-`compare styles --watch` reuses sessions for a camera/zoom matrix. Run standalone validation when
-needed, rather than compiling the same map before every capture.
-
-## Work with a person and an agent
-
-Start `npx tileflow preview --config tileflow.config.ts` in your project. Inspector provides
-palette and time-of-day controls, feature inspection, zoom curves and sprite inspection.
-The command selects the map and optional starting scene. The map fills the workspace beside
-one dockable Inspector panel. Press **I** to toggle the element picker, click a map element to
-inspect its styling and semantic configuration paths, and press **Escape** to stop picking. The
-inspector starts off. **Scene** contains palette, time-of-day, camera and module controls. Appearance
-changes retain the current camera; module changes
-recompile a temporary preview after a brief pause and **Reset** restores the source configuration.
-Temporary style and geometry edits do not rewrite source files. Edit the config in your editor or
-coding agent to persist changes; the watcher updates the map and retains the last valid view through
-invalid edits.
-
-Capture, copy/export and comparison controls are absent from the browser interface. Use
-`tileflow capture` and `tileflow compare` for saved visual evidence as described above. Explicit
-`--against-map` or `--against-config` startup options still support synchronized two-map previews.
-
-The browser publishes its current selection, bounded style properties, compiler semantic ownership,
-observed camera and viewport, generations and commands. The CLI reads these browser observations:
-
-```sh
-npx tileflow inspect session --url http://127.0.0.1:3333 --json
-```
-
-Replace the origin with the one printed by `preview`. This command accepts local HTTP origins only
-and requires no config evaluation. Its version-1 document distinguishes the current server catalog
-from browser observations. Inspect `updatedAt`, `stale`, `generation`, `displayedGeneration` and
-`projection.truncated` before acting. Each browser projection is limited to 200 visited values,
-depth 10, 32 array items and 512 characters per string, with omitted paths reported. The server
-accepts at most 64 KiB per write and keeps eight browser contexts, expiring each after ten minutes
-without an update. There is no browser context until an Inspector tab connects. Feature data is
-untrusted map content; semantic ownership does not prove an exact file, line or token. Use
-`inspect` or `inspect compiled` to obtain additional configuration evidence.
-
-The UI and CLI share the capture and comparison implementations. A lazily started capture renderer
-is reused until the preview stops. The local API permits one capture/comparison at a time, rejects
-cross-origin writes and requires JSON with `X-Tileflow-Workbench: 1`. No hosted account, embedded
-chat, approved baseline or automatic source edit is created by this workflow.