tileflow 0.1.0-alpha.13 → 0.1.0-alpha.15

package/docs/command-families.md

@@ -9,6 +9,7 @@ Start with the [tileflow guide](https://github.com/tileflow/tileflow-sdk/blob/ma
 | Local evidence    | `setup capture`, `capture`, `visual compare`, `visual analyze`, `visual diff`, `visual update` |
 | Data and assets   | `tileset inspect`, `tileset publish/list/status/purge`, `inspect features`, `icons list/diff`  |
 | Team Icon Sets    | `icon-set publish/list/status/versions/uses/archive/unarchive/purge`                           |
+| Team 3D models    | `models publish/list/status/restore/purge`                                                     |
 | Repository locks  | `icons install`, `icons update`, `icons pin`                                                   |
 | Account           | `login`, `logout`, `whoami`                                                                    |
 | Hosted delivery   | `deploy`, `status`                                                                             |
@@ -28,5 +29,8 @@ authority when resolving revisions and are the only commands that select revisio
 `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).
 
+`models` publishes and manages the Team 3D models that maps place by name; see
+[Team 3D models](https://github.com/tileflow/tileflow-sdk/blob/main/packages/cli/docs/team-3d-models.md).
+
 The hidden `projects` command family lists and manages the internal application destinations of an
 account for support. It is not part of the ordinary workflow or the product catalog.

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

@@ -184,8 +184,21 @@ 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) 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>/` 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

@@ -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 \

package/docs/map-authoring.md

@@ -25,6 +25,7 @@ Start with bounded queries, then request more detail at the returned JSON Pointe
 ```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
@@ -54,6 +55,12 @@ Inspection includes resolved inheritance, merge provenance, and the theme contra
 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.

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

@@ -0,0 +1,36 @@
+# 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tileflow",
-  "version": "0.1.0-alpha.13",
+  "version": "0.1.0-alpha.15",
   "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.31 <0.1.0-beta.0",
+    "@tileflow/capture": ">=0.1.0-alpha.32 <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.35 <0.1.0-beta.0",
-    "@tileflow/dev": ">=0.1.0-alpha.32 <0.1.0-beta.0",
-    "@tileflow/maps": ">=0.1.0-alpha.9 <0.1.0-beta.0",
+    "@tileflow/core": ">=0.1.0-alpha.37 <0.1.0-beta.0",
+    "@tileflow/dev": ">=0.1.0-alpha.34 <0.1.0-beta.0",
+    "@tileflow/maps": ">=0.1.0-alpha.11 <0.1.0-beta.0",
     "commander": "^15.0.0",
     "hono": "4.13.7",
     "picocolors": "^1.1.1",