tileflow 0.1.0-alpha.12 → 0.1.0-alpha.14

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

@@ -184,8 +184,19 @@ Hosted deploy currently rejects local or package-owned web fonts before authenti
 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.
 
-For both managed resource kinds, `assetSetSha256` remains a separate per-map output identity. It
+A map's own 3D building models (the building models of its `models` directories) deploy as one
+model bundle per map. Deploy prepares them as `build` does, uploads the bundle with
+`PUT /v1/model-bundles/:contentHash` after authentication and before the first style write, compiles
+each placement's `url` at the bundle's hosted address and publishes the style with the bundle's
+content hash. Byte-identical bundles are reused by content hash. A bundle holds at most 64 models,
+16 MiB a prepared file and 32 MiB together, and shares the organization's hosted-storage pool like
+icon packages. Upload success must confirm the submitted `contentHash`, model count and byte total,
+one opaque `mdb_<id>` and the query-free `/model-bundles/<id>` base URL. 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>/` prefix), and reject the Style when the submitted build-manifest hash diverges.
+`icons/<mapId>/` and `models/<mapId>/` prefixes), and reject the Style when the submitted
+build-manifest hash diverges.

package/docs/local-visual-feedback.md

@@ -54,7 +54,7 @@ export default defineMap({
 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 workbench
+### Live comparison in Map DevTools
 
 Use the ordinary preview server with a right-hand selection to compare two maps or themes while
 authoring:
@@ -62,8 +62,8 @@ authoring:
 ```sh
 # Two maps or themes from one config.
 npx tileflow preview \
-  --map harad --theme light \
-  --against-map ferraris --against-theme light
+  --map baedeker --theme light \
+  --against-map map-1777 --against-theme light
 
 # Or compare against another config.
 npx tileflow preview \
@@ -71,7 +71,7 @@ npx tileflow preview \
   --against-config ./reference.config.ts --against-map reference
 ```
 
-Any `--against-*` option opens the comparison workbench. Both previews remain same-origin and share
+Any `--against-*` option opens Map DevTools 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
@@ -81,7 +81,7 @@ Enable **Inspect** and click a rendered feature to see its bounded feature data,
 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 this local workbench and is not emitted by `tileflow build`.
+only in memory in the local Map DevTools session and is not emitted by `tileflow build`.
 
 ### Reproducible two-style review
 

package/docs/map-authoring.md

@@ -0,0 +1,132 @@
+# 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 Map DevTools 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 Map DevTools. `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. Map DevTools 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 developer-tools 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 a Map DevTools 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.

package/docs/native-artifacts.md

@@ -39,7 +39,7 @@ 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,
+endpoint: it does not render a browser map, open Map DevTools, start Metro, launch a device,
 or establish visual/native acceptance.
 
 With the default host and port, the canonical runtime manifest is:
@@ -77,7 +77,7 @@ developer remain responsible for making an explicitly selected development endpo
 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
+`--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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tileflow",
-  "version": "0.1.0-alpha.12",
+  "version": "0.1.0-alpha.14",
   "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.1.3",
-    "@tileflow/capture": ">=0.1.0-alpha.30 <0.1.0-beta.0",
+    "@tileflow/capture": ">=0.1.0-alpha.31 <0.1.0-beta.0",
     "@tileflow/coordinates": ">=0.1.0-alpha.2 <0.1.0-beta.0",
     "@tileflow/coordinates-runtime": ">=0.1.0-alpha.5 <0.1.0-beta.0",
-    "@tileflow/core": ">=0.1.0-alpha.34 <0.1.0-beta.0",
-    "@tileflow/dev": ">=0.1.0-alpha.31 <0.1.0-beta.0",
-    "@tileflow/maps": ">=0.1.0-alpha.8 <0.1.0-beta.0",
+    "@tileflow/core": ">=0.1.0-alpha.36 <0.1.0-beta.0",
+    "@tileflow/dev": ">=0.1.0-alpha.33 <0.1.0-beta.0",
+    "@tileflow/maps": ">=0.1.0-alpha.10 <0.1.0-beta.0",
     "commander": "^15.0.0",
     "hono": "4.13.7",
     "picocolors": "^1.1.1",