tileflow 0.1.0-alpha.14 → 0.1.0-alpha.16

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

@@ -30,8 +30,41 @@ account or hosted command stops with a clear message and asks you to run `tilefl
 Project API and CI keys are independent project credentials and are not removed by a personal
 password change.
 
-The dashboard creates the Map and browser-access policy before repository setup. Keep that exact
-Map ID in the deploy action. If the config contains several maps, select the authored map explicitly:
+## 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 \
@@ -184,15 +217,17 @@ 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.
 
-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.
+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

package/docs/native-artifacts.md

@@ -82,8 +82,8 @@ Browser-only selections fail before config execution in native mode. In particul
 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 and
-finite cap/dash layer partitioning in `native-build.json`; it does not change web artifacts.
+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

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.14",
+  "version": "0.1.0-alpha.16",
   "license": "Apache-2.0",
   "description": "CLI-only tools for Tileflow config, capture, visual testing, and deploy.",
   "type": "module",
@@ -36,14 +36,14 @@
   },
   "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.33 <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.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",
+    "@tileflow/core": ">=0.1.0-alpha.39 <0.1.0-beta.0",
+    "@tileflow/dev": ">=0.1.0-alpha.36 <0.1.0-beta.0",
+    "@tileflow/maps": ">=0.1.0-alpha.13 <0.1.0-beta.0",
     "commander": "^15.0.0",
-    "hono": "4.13.7",
+    "hono": "4.13.13",
     "picocolors": "^1.1.1",
     "zod": "^4.4.3"
   },