@bitmagic/cli 0.1.53-dev.1 → 0.1.53-dev.11

package/README.md

@@ -49,6 +49,9 @@ npm install -g @bitmagic/cli
 bitmagic --version
 ```
 
+That is the only time you need npm. From then on, `bitmagic self-update` updates the CLI — see
+[Staying current](#staying-current) for why the npm line is the wrong tool for the second install.
+
 ### The dev line
 
 ```bash
@@ -61,9 +64,10 @@ installs the unreleased build the Bitmagic team and external testers run — a p
 production, so a CLI that uses them has to be installable before it is released. Pair it with
 `bitmagic login --env dev`.
 
-`npm install -g @bitmagic/cli` puts you back on the release at any time. One global install is a
-single `bitmagic` on your PATH, so `bitmagic --version` is how you tell which line you are on: a
-`-dev.N` suffix means the dev line. To have both at once, see below.
+`bitmagic self-update --tag latest` puts you back on the release at any time, and `--tag dev` takes
+you the other way. One global install is a single `bitmagic` on your PATH, so `bitmagic --version`
+is how you tell which line you are on: a `-dev.N` suffix means the dev line. To have both at once,
+see below.
 
 ### Running both lines side by side
 
@@ -113,6 +117,11 @@ env=local
 apiUrl=http://localhost:3102
 ```
 
+`bitmagic self-update` works inside this setup unchanged: it reinstalls into the root the
+`bitmagic` you just ran came from, with the same `--global-dir` and `--global-bin-dir`, so updating
+from `dev-games/` cannot disturb the prod root. (Running `pnpm add -g` by hand would, unless you
+repeat both flags.)
+
 `direnv allow` each, and both halves are right in each tree:
 
 ```
@@ -184,11 +193,12 @@ browser reloads itself on every change and the assets panel shows each generatio
 | `bitmagic whoami [--env <env>]` | Show the identity the CLI is authenticated as — the account's email address alongside its user id — and which environment answered, including where that environment was chosen from. |
 | `bitmagic init [dir] [--template <id>] [--name <name>] [--idea "<pitch>"] [--env <env>] [--force]` | Scaffold a new project: mints a game, downloads the vendored engine, writes `AGENTS.md`, `GAME-DESIGN.md` and templates. Starts from `empty-3d` unless told otherwise. `--idea` seeds the design doc's pitch **and** picks the template whose camera and controls fit it — "a doom-like corridor shooter" scaffolds `first-person`, "jump between floating islands" scaffolds `sidescroller`. `--template` overrides both; a suggestion that fails for any reason falls back to `empty-3d` rather than failing the scaffold. Dependencies are installed with **pnpm** when your machine has it and npm otherwise — the lockfile that produces is what every later command reads, so it never tells you to run the wrong one. |
 | `bitmagic check` | Typecheck (`tsc --noEmit`) against the vendored engine. Fast; does not prove the game runs. |
-| `bitmagic dev [--port <port>] [--editor-port <port>] [--no-open]` | Build, then serve everything and keep it running: `tsc --watch`, `vite` on 3010, and a **Game / Editor** view on 3011 that reloads itself when the project changes. Opens the view in your browser; `--no-open` (or `BITMAGIC_NO_OPEN=1`) skips that. The one command to leave open. See **The dev view** below. |
+| `bitmagic dev [--port <port>] [--editor-port <port>] [--no-open]` | Build, then serve everything and keep it running: `tsc --watch`, `vite` on 3010, and a **Game / Editor** view on 3011 that reloads itself when the project changes, and shows where the game is published (with a QR code) once it has been. Opens the view in your browser; `--no-open` (or `BITMAGIC_NO_OPEN=1`) skips that. The one command to leave open. See **The dev view** below. |
 | `bitmagic reload [--port <port>]` | Tell a running `bitmagic dev` to reload the browser now. For agents: run it when you finish a round of edits. Exits 0 and does nothing when no dev server is running. |
 | `bitmagic verify [--timeout <ms>] [--renderer webgpu\|webgl] [--platform desktop\|mobile\|both] [--fast] [--watch]` | Build, boot the game in a headless browser, press the engine's Play button like a player would, and report what broke. A game without the button passes as long as gameplay starts by itself (auto-starting genres, custom start UIs); a run where gameplay never starts fails. The settle is adaptive: the run ends as soon as the live engine proves stable gameplay (state, rendered frames, no fresh errors, player standing), with `--timeout` as the cap. The verdict includes live engine state — actual GPU backend, fps, player position, physics body count, gameplay events (see **Gameplay events** below) — recorded in `result.json`. `--renderer` pins the pipeline (default `webgpu`, what players run; a silent WebGPU→WebGL2 fallback **fails** the run, and `--renderer webgl` is the deliberate escape hatch). A run failing on a lost WebGL context retries once on software rendering automatically. `--fast` skips the screenshot pipeline (then there is no thumbnail candidate from this run). `--watch` keeps everything warm — incremental `tsc --watch`, one vite, one browser — and re-verifies on file change in seconds; `--fast` is the watch default (`--no-fast` restores the screenshot). `--platform` picks what the run emulates — see **Verifying the mobile path** below. Every run also reports the engine's mobile-parity check: a desktop action with no touch button is a warning, and a **failure** when `game.json` declares `primaryPlatform: "mobile"`. Writes the artifacts the publish gate reads (see below). |
-| `bitmagic build` | Bundle the game into one self-contained `.bitmagic/build/index.html`. Rarely needs to be run by hand — `publish` builds automatically when the project changed. |
-| `bitmagic publish [--visibility public\|private] [--name <name>] [--description <desc>] [--force]` | Verify-gate, build if needed, and upload straight to GCS. **Private unless `--visibility public` is passed.** |
+| `bitmagic build [--single-file]` | Bundle the game into a single `.bitmagic/build/index.html`. The engine, your game and its data are inlined; three.js, Rapier and the other third-party packages load from a CDN at the versions your import map pins — the same shape a game published from bitmagic.ai has. `--single-file` inlines those too, for a game that has to run with no network (offline, `file://`, a packaged shell); the file is several megabytes bigger. Rarely needs to be run by hand — `publish` builds automatically when the project changed. |
+| `bitmagic publish [--visibility public\|private] [--name <name>] [--description <desc>] [--force] [--single-file] [--no-qr]` | Verify-gate, build if needed, and upload straight to GCS. `--single-file` publishes the offline bundle described under `bitmagic build`; switching the flag between runs always rebuilds, since it changes nothing on disk for the reuse check to notice. **Keeps the game's current visibility**; a new game is private until published with `--visibility public`. Shows the published URL as a QR code so you can scan it onto a phone — drawn in the terminal, or written to `.bitmagic/publish-qr.png` when it cannot be. `--no-qr` skips both. |
+| `bitmagic self-update [--tag latest\|dev]` | Update the **CLI itself** to the newest build of its line, installing into the place this CLI actually lives rather than wherever the `npm` on your `PATH` would put it — which under nvm is routinely somewhere else. Reads the project's line from `bitmagic.json` when there is one, so it also fixes a wrong-line install; `--tag` overrides. Verifies the version on disk moved, and refuses (naming the path) for an `npx` run, a source checkout, or an install shape it cannot recognise. Not to be confused with `upgrade`, which is about the project's engine. |
 | `bitmagic upgrade [--engine <version>] [--force]` | Refresh vendored platform files and the CLI's own skills to the currently published engine. Refuses a dirty git tree unless `--force`. Also records the project's `environment` in `bitmagic.json` if it has none yet — the engine it just vendored came from that api-server — and says so when it does. |
 | `bitmagic generate <skybox\|background\|block-type\|sound\|image\|character\|animation\|model\|prop\|vehicle> ...` | Generate one asset directly into `src/work/world.json`. Costs sparks. `model` mints a **new** 3D object from a prompt, `prop` upgrades an existing placeholder **in place**, `vehicle` adds a new drivable one, `animation` takes a parameter spec rather than a prompt, `block-type` registers a custom voxel block — see below. `skybox` and `background` write the **same** field: pick one. |
 | `bitmagic assets add <file> [--name <n>] [--asset-id <id>] [--keep-glb] [--voxel-size <m>] [--max-voxel-size <m>] [--height <m>] [--hollow\|--solid] [--force]` | Upload **your own** file — `.glb`, `.vxl`, `.png/.jpg/.webp`, `.opus/.ogg/.m4a/.mp3`, `.json` — into the game's assets and write its entry into `src/work/world.json`. A `.glb` is voxelized in a headless browser (Chrome + a free port in 3000–3199, like `prop`) unless `--keep-glb`. Free — no sparks. See **Adding your own assets** below. |
@@ -411,6 +421,21 @@ While the game boots, the mark hops over the stage — the first time only. Late
 still, and only if the reload is slow enough to be worth explaining. If a boot fails it stays put,
 says what went wrong and offers to try again, instead of leaving you a black rectangle.
 
+### Where your game is published
+
+Once the project has been published, a **Published** pill appears in the top bar. It opens the
+game's address, the visibility it went out with, which publish this is and how long ago — and the
+same QR code the terminal draws, so the phone in your hand can reach the build without you typing
+anything.
+
+The pill lights up on its own within a second or two of a publish finishing, with no reload: the
+page polls, and the publish it should show almost always happens in another terminal — often your
+agent's, which you never look at. Until the first publish the pill is there but dead, because a
+control that opens an empty dialog is worse than one that is plainly not ready.
+
+It works even when the game will not boot, which is deliberate: that is the moment the link matters
+most, since the last good build is still live at that address.
+
 Put the page beside your agent's window. It is one page with
 two tabs over the same running game, so switching costs nothing and does not restart anything:
 
@@ -727,12 +752,18 @@ manage the registry, not gameplay.
    publish rebuilds automatically; a prior manual `bitmagic build` is never required, only useful
    if you want to inspect `.bitmagic/build/index.html` before it ships.
 
-**Publishing does not make a game public.** Every `bitmagic publish` uploads and registers the
-game, but by default `visibility` is `private` — reachable by URL, not listed anywhere on
-bitmagic.ai. You must pass `--visibility public` explicitly, every time you want the game listed;
-omitting it on a later publish makes it private again — and takes the game's `/play/` page out of
-service, so a previously-public game re-published bare is gone from bitmagic.ai until you publish
-publicly again.
+**Publishing does not make a game public.** A new game starts `private` — reachable by URL, not
+listed anywhere on bitmagic.ai. Pass `--visibility public` when you want it listed.
+
+**Visibility is sticky.** `bitmagic publish` with no `--visibility` keeps the game exactly as it
+is, so shipping an update to a public game leaves it public. You only need `--visibility` when you
+want to *change* something: `public` to list it, `private` to take it out of service.
+
+**Managing a published game** — changing its visibility, or taking it down for good — happens on
+the web, at the **My games** page `publish` prints a link to (`bitmagic.ai/my-games/`). It is
+the same page web-lane creators use, so there is one place to manage a game regardless of how it
+was built. Withdrawing a game there unlists it and frees any custom `/play/` address; it does not
+touch your project, and you can publish it again afterwards.
 
 `--force` overrides a **stale or failed** verify verdict. It does **not** override a missing
 verify record — a project with no cover art has only the verify screenshot to publish a thumbnail
@@ -744,6 +775,33 @@ from, so `bitmagic verify` must have produced at least one screenshot — `scree
 stick — and note that writing them into `game.json` yourself would change the fingerprint and
 invalidate the verify you just checked.
 
+### Testing it on a phone
+
+Publish draws the URL it just printed as a QR code, so you can point a phone at the terminal
+instead of retyping a twelve-character game id into a mobile browser. Scan it and the game opens.
+
+This is the pro lane's "try it on my phone" loop, and `--visibility private` is the whole of it: a
+private game is *unlisted*, not access-controlled, so its URL works from any device while the game
+stays off bitmagic.ai. Publish as often as you like and scan the code each time.
+
+**When the code cannot be drawn, publish writes it as a file instead** — `.bitmagic/publish-qr.png`
+— and names the path (`qrPath` in the `--json` result). That is the normal case for an agent-driven
+publish: your agent's stdout is a pipe, not a terminal, so there is nothing to paint a code onto,
+and the person who would scan it is on the other side of that pipe. The image is how it reaches
+them. The same happens under `--json`, for `TERM=dumb`, and when the terminal is narrower than the
+code (37 columns for a typical publish URL), since a wrapped code cannot be scanned anyway. A
+terminal that draws the code successfully writes no file.
+
+`.bitmagic/` is excluded from the publish fingerprint, so the image cannot invalidate a verify.
+
+The code is extra, never a substitute — the URL is always printed as a plain line above it, and
+everything still works if neither a drawing nor a file appears. `--no-qr` and `BITMAGIC_NO_QR`
+suppress both.
+
+`bitmagic dev` deliberately has no equivalent. Its servers bind `127.0.0.1`, and the asset CDN
+only serves assets to `localhost` origins — a phone pointed at your machine's LAN address would
+load the game with no terrain and drop the player through the floor. Publish privately instead.
+
 ### Which platform the game is catalogued as
 
 Publish syncs two indicators from your project files, so bitmagic.ai lists the game as what it
@@ -792,7 +850,7 @@ refused is a bundle that is not a Bitmagic engine build at all (exit 1).
 
 | Code | Meaning |
 |---|---|
-| 1 | Build failed, or the uploaded bundle was not a Bitmagic engine build (check `vite.publish.config.js`). Not retryable — republishing the same bytes gets the same refusal. |
+| 1 | Build failed, or the uploaded bundle was not a Bitmagic engine build (check `vite.publish.config.js`, or `vite.publish-standalone.config.js` for a `--single-file` build). Not retryable — republishing the same bytes gets the same refusal. |
 | 2 | Not logged in |
 | 3 | Verify missing, stale, or failed |
 | 4 | `bitmagic judge --min-score`: the judge ran, but the overall score is below the bar. The scorecard is in `.bitmagic/judge.json`. |
@@ -849,10 +907,12 @@ exact install command to run, using your project's own package manager (detected
 added needs that command run once before `bitmagic build` (and therefore `bitmagic publish`) will
 work.
 
-A project scaffolded before `vite.publish.config.js` existed cannot be bundled at all: `bitmagic
+A project scaffolded before the bundle config it needs existed cannot be bundled at all: `bitmagic
 build` stops with a message naming `bitmagic upgrade`, which vendors the file without touching
-your game code. Run the printed install command afterwards if `upgrade` reports missing
-dependencies too.
+your game code. This applies to `vite.publish-standalone.config.js` too, which arrived later than
+`vite.publish.config.js` — so a project can have one and not the other, and the message names
+whichever one your build actually needs. Run the printed install command afterwards if `upgrade`
+reports missing dependencies too.
 
 ## Machine-readable output
 
@@ -867,7 +927,12 @@ parses one stream whether the command succeeded or not. The exit code remains au
 
 Without `--json` nothing changes: prose goes to stdout as before and no JSON is emitted.
 
-The result shape is per-command — `publish` reports `url`/`visibility`/`publishVersion`, `init`
+`--json` suppresses `publish`'s *drawn* QR code, which uses terminal escape sequences: under
+`--json` stdout carries the result document and nothing else. The image is still written, and
+`qrPath` in the result names it — that is the only way an agent learns the file exists.
+
+The result shape is per-command — `publish` reports
+`url`/`visibility`/`publishVersion`/`manageUrl`, plus `qrPath` when it wrote a QR image, `init`
 reports `gameId`/`root`/`dependenciesInstalled`/`packageManager`, `upgrade` reports `replaced` and any
 `missingDependencies` as structured entries rather than only as a printed install command, plus
 `cliUpdate` (`{ current, latest, updateAvailable }`, or `null` when the engine did not move and so
@@ -877,7 +942,39 @@ no check was made — which is not the same as "no update"), and `legacyAssetsRe
 
 ## Staying current
 
-Three nudges, all advisory — nothing is ever blocked because something is out of date.
+```bash
+bitmagic self-update
+```
+
+updates the CLI itself. Use it rather than `npm install -g @bitmagic/cli`, which is only for the
+first install — see [Why self-update and not npm](#why-self-update-and-not-npm) below.
+
+It installs into the exact place this CLI is already installed, on the line it is already on. Inside
+a project it uses that project's line instead (`environment` in `bitmagic.json`), so running it in a
+`dev` project from a release build crosses you over; `--tag dev` / `--tag latest` overrides both. It
+reads back the version on disk afterwards and fails if it did not move, so a successful-looking
+update that changed nothing is reported rather than believed.
+
+It refuses, with the path it looked at, when there is nothing for it to do: a run through `npx`
+(nothing is installed), a source checkout (`git pull` and rebuild), or an install shape it does not
+recognise — it will not guess at where to write.
+
+### Why self-update and not npm
+
+`npm install -g @bitmagic/cli` installs into whichever Node the `npm` on your `PATH` belongs to,
+which is not necessarily the one this CLI is installed in. Under a version manager — nvm, fnm,
+Volta — those two are routinely different, and a coding agent's non-interactive shell makes it
+worse: it sources no profile, so nvm never loads and `npm` is whatever else is on the system path.
+The install then succeeds, into a prefix nothing on your `PATH` points at, and `bitmagic --version`
+never moves. The same applies to the two-root pnpm setup below, where a bare `npm i -g` writes to a
+third place entirely.
+
+`self-update` resolves its own install from the Node binary running it, so it cannot be aimed
+anywhere else.
+
+### The nudges
+
+Three, all advisory — nothing is ever blocked because something is out of date.
 
 - **The CLI itself.** Commands print a line when a newer `@bitmagic/cli` is on npm. The check reads
   a cache written by an earlier run, so it costs no time; the cache refreshes in the background at
@@ -885,15 +982,17 @@ Three nudges, all advisory — nothing is ever blocked because something is out
   every merge to `main` and can move several times an hour, so an older answer there is usually
   about a build several versions back. It asks about the line you are actually on — a build
   installed from `@dev` asks the `dev` dist-tag and hears about the next dev build, rather than
-  being told the production release is "newer" — and it names the install command for that line. An
-  unreachable registry, a first-ever run, and a version with no recognisable numeric core all stay
-  quiet.
+  being told the production release is "newer". An unreachable registry, a first-ever run, and a
+  version with no recognisable numeric core all stay quiet. `bitmagic dev` also shows it as a
+  banner in the browser, because that command runs for hours and the terminal line scrolls away.
 - **The CLI, after an engine bump.** When `bitmagic upgrade` actually moves the engine version, it
   asks npm there and then instead of trusting that cache — which can be a whole interval stale, and
   so silent about the CLI published alongside the engine you just vendored. The CLI and the engine
   ship together, so a newer engine can need build config or a command only the newer CLI has, and
-  finding that out as a failed `bitmagic build` is worse than being told here. No request is made when the
-  engine version did not change, and an unreachable registry costs the hint and nothing else.
+  finding that out as a failed `bitmagic build` is worse than being told here. It names the line the
+  *project* is on rather than the one you happen to be running, so it says `bitmagic self-update
+  --tag dev` where that is the crossing you need. No request is made when the engine version did not
+  change, and an unreachable registry costs the hint and nothing else.
 - **The vendored engine.** `bitmagic dev` and `bitmagic publish` say when a newer engine exists and
   suggest `bitmagic upgrade`. Publishing is never refused for an old engine — the prompt belongs
   where rebuilding is cheap, not at the moment you ship.
@@ -916,19 +1015,23 @@ and where the generators fall short. It is the same thing the web editor already
 typed there, and it goes to the same place. None of it reaches Google Analytics, which only ever
 receives counts, outcomes and timings.
 
-If your agent passes it, the wording *you* used when you asked it is kept alongside the command's
-own text. That is optional and most agents will not send it.
-
-This does not include what you type into Claude Code, Codex or any other agent. Bitmagic never sees
-that — the CLI only ever receives the arguments your agent chooses to pass it.
+**What you asked your agent for is kept too, when it passes it on.** The scaffolded project docs
+tell your agent to add `--original-prompt "<your request, verbatim>"`, so on those commands the
+wording *you* used — typically what you typed into Claude Code or Codex — is stored beside the
+command's own text and as a record of its own. The CLI has no other view of your agent's
+conversation: it sees only the arguments your agent chooses to pass it, and this is the one
+argument that is your words rather than its paraphrase. It is optional, never required, and never
+influences what gets generated.
 
 Set `DO_NOT_TRACK=1` in your environment to switch the end-of-command report off. Nothing is
-collected for it in that case — not even the file reads it would have needed.
+collected for it in that case — not even the file reads it would have needed. It also stops
+`--original-prompt` being forwarded: the CLI drops it at the point every command reads its flags,
+so no request carries it, whether or not your agent passed it.
 
-It does **not** switch off the paragraph above. The text you pass to `forge`, `generate`, `cover`
-and `init --idea` is not telemetry: it is the request, and the server cannot generate anything
-without it. If you would rather it were not kept, the honest answer is that today there is no flag
-for that — tell us and we will add one.
+It does **not** switch off the paragraph before that one. The text you pass to `forge`, `generate`,
+`cover` and `init --idea` is not telemetry: it is the request, and the server cannot generate
+anything without it. If you would rather it were not kept, the honest answer is that today there is
+no flag for that — tell us and we will add one.
 
 The report is deliberately unobtrusive but it is not free: it is capped at 1.5 seconds per request
 (two at worst, when your access token is due for a refresh first), it never prints, and it can never
@@ -953,9 +1056,10 @@ it, modified or not, free or paid, as a game engine, framework, SDK, library, st
 game-creation tool.
 
 One practical consequence: a published game contains compiled engine code, so the licence requires
-the notice to travel with it. `vite.publish.config.js` carries a `banner` that does this
-automatically, along with the attribution three.js, Rapier and the other bundled libraries require.
-Leave it in place. `engine/THIRD-PARTY-NOTICES.md` has the full texts.
+the notice to travel with it. Both bundle configs carry a `banner` that does this automatically,
+along with the attribution three.js, Rapier and the other libraries require — which a
+`--single-file` build inlines outright, and a default build still ships loaders for. Leave it in
+place. `engine/THIRD-PARTY-NOTICES.md` has the full texts.
 
 ## Development
 

package/dist/assets/revoxelize.d.ts

@@ -45,12 +45,72 @@ export declare function findRevoxelizableAsset(world: Record<string, unknown>, a
     asset: Record<string, unknown>;
     source: RevoxelizeSource;
 };
+/**
+ * A voxel size fit to show a person and to store.
+ *
+ * The `.vxl` header holds float32, so the size read back out of it is `0.019999999552965164` where
+ * the creator asked for `0.01` and got a doubling. Six significant figures is far beyond any
+ * resolution this means anything at, and it puts the number back in the vocabulary the flag uses —
+ * both in the note and in world.json, which would otherwise carry the artifact into every diff.
+ */
+export declare function tidyVoxelSize(value: number): number;
+/**
+ * What the bake actually produced, when that is not what was asked for.
+ *
+ * The engine's compiler halves resolution until the model fits a leaf budget
+ * (`compileVoxelModelToVxlAsset`: `while (cells.size > maxLeaves) { downsample; vs *= 2 }`, budget
+ * 600k for a working asset). It says so — but only as a `console.warn` inside the headless Chrome
+ * the CLI drives, which reaches nobody, and `REVOXELIZE_FROM_VXL_MASTER_RESULT` did not carry it.
+ * So a request just under the knee came back at exactly twice the size, silently, with a zero exit
+ * code.
+ *
+ * The effect is worse than "not quite what you asked for", which is why this is said out loud
+ * rather than left to whoever compares two numbers in world.json: the result is NON-MONOTONIC.
+ * One step below the knee the asset is coarser than a COARSER request would have produced —
+ * measured on a 2.78 m stall with a 512³ master, 0.011 m gave 556k voxels and 0.0105 m gave 141k.
+ * Nothing about "I asked for finer voxels and got a blockier model" suggests looking at a budget.
+ *
+ * Detected from the .vxl header rather than from anything the engine says, deliberately: the
+ * header is what was actually written, and the CLI drives whatever engine the project vendored —
+ * including ones that predate any reply field carrying this.
+ */
+export declare function describeBudgetCoarsening(requested: number, achieved: number): {
+    coarsened: boolean;
+    factor: number;
+    note: string;
+};
+/**
+ * The height a master re-bake will be resampled to.
+ *
+ * `--height` wins. Otherwise the height the asset was BAKED at, which the master path records in
+ * `voxelizeSettings` for exactly this. Falling through to neither is the case worth naming: a
+ * master is a grid, not a size, so the engine has nothing to derive a height from and lands on its
+ * own `DEFAULT_TARGET_HEIGHT` of 2 m — silently returning a 10 m building as a 2 m one. The mesh
+ * branch has no such gap, which is why `--height`'s "omit to keep the source's own size" only ever
+ * described half of this command.
+ */
+export declare function resolveMasterTargetHeight(asset: Record<string, unknown>, requested: number | undefined): number | undefined;
 /**
  * Refuse a master re-bake that asks for more detail than the master holds.
  *
  * The engine would refuse it too — `resampleMaster` throws "re-forge at a higher resolution rather
  * than upsampling" — but only after the browser, vite and the page have started. Saying it here
  * costs nothing and names the thing to do instead, which the engine's message cannot know.
+ *
+ * The floor is derived from the MASTER, not from the previous bake. Those are very different
+ * numbers: a 512³ master baked once at 0.1 m holds detail down to about `targetHeight / 512`, and
+ * refusing everything below 0.1 m would make that headroom unreachable from the CLI — which is the
+ * whole reason the master is stored rather than the working asset.
+ *
+ * Deliberately PERMISSIVE. The engine's real limit is the master's occupied span along the up
+ * axis, which is at most its resolution and usually less, so a request between
+ * `targetHeight / resolution` and `targetHeight / spanUp` still throws in the browser. That is the
+ * right way round: this pre-flight exists to avoid paying for a browser on a request that cannot
+ * work, never to refuse a size the master can serve. The engine stays the authority.
+ *
+ * Falls back to the old "no finer than the last bake" rule when either field is missing, so assets
+ * written before `sourceVxlMasterResolution` existed — or hand-edited ones — keep a guard rather
+ * than losing it.
  */
-export declare function assertMasterCanGoFiner(asset: Record<string, unknown>, requestedVoxelSize: number, name: string): void;
+export declare function assertMasterCanGoFiner(asset: Record<string, unknown>, requestedVoxelSize: number, targetHeight: number | undefined, name: string): void;
 export declare function revoxelizeAsset(options: RevoxelizeOptions): Promise<RevoxelizeResult>;

package/dist/assets/revoxelize.js

@@ -3,11 +3,13 @@
  *
  * Every voxelized asset keeps what it was made from, and either source can be baked again:
  *
- *   - `sourceVxlMasterUrl` — the voxel master, written by the direct-voxel path. Cheap (about a
- *     megabyte) and already occupancy, so the engine only resamples and recompiles it.
+ *   - `sourceVxlMasterUrl` — the voxel master, written by the direct-voxel path. Cheap (a few
+ *     megabytes) and already occupancy, so the engine only resamples and recompiles it. It can go
+ *     finer than a previous bake, but never finer than the grid it was forged at — masters are
+ *     resampled by merging cells, never by inventing them.
  *   - `sourceGlbUrl` — the mesh, written by the GLB path. Heavier (50-100 MB to refetch) and a full
- *     re-voxelization, but the mesh is resolution-independent, so it is the only source that can go
- *     FINER than any previous bake.
+ *     re-voxelization, but the mesh is resolution-independent, so it is the only source with no
+ *     ceiling at all.
  *
  * One command over both, because "re-bake this at a different size" is one thing a creator wants
  * and which pipeline produced the asset months ago is not something they should have to remember.
@@ -19,6 +21,7 @@
  * Writes under the SAME id, so every placed instance changes with it — the same upgrade-in-place
  * contract `generate prop` makes, and the reason this is not "add a second asset at a new size".
  */
+import { propVoxelGrids } from '@bitmagic/asset-core';
 import { CliError } from '../errors.js';
 import { VOXELIZE_TIMEOUT_MS, withVoxelizeSession } from '../forge/voxelize-session.js';
 import { applyModificationsToWorld } from '../forge/apply-modifications.js';
@@ -65,20 +68,138 @@ function countInstances(world, assetId) {
     const objects = Array.isArray(world.environmentObjects) ? world.environmentObjects : [];
     return objects.filter((item) => isJsonObject(item) && item.assetId === assetId).length;
 }
+/** A positive number from an unknown field, or undefined. */
+function positiveNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : undefined;
+}
+/** The finest grid the generator will forge a master at. */
+const MAX_MASTER_GRID = Math.max(...propVoxelGrids);
+/**
+ * Floating-point slack for "the engine baked what I asked for".
+ *
+ * The requested size round-trips through a float32 header, so an exact `===` would report a
+ * coarsening on every bake. A real one is a DOUBLING, so anything under a few percent is noise.
+ */
+const VOXEL_SIZE_EPSILON = 0.02;
+/**
+ * A voxel size fit to show a person and to store.
+ *
+ * The `.vxl` header holds float32, so the size read back out of it is `0.019999999552965164` where
+ * the creator asked for `0.01` and got a doubling. Six significant figures is far beyond any
+ * resolution this means anything at, and it puts the number back in the vocabulary the flag uses —
+ * both in the note and in world.json, which would otherwise carry the artifact into every diff.
+ */
+export function tidyVoxelSize(value) {
+    return Number(value.toPrecision(6));
+}
+/**
+ * What the bake actually produced, when that is not what was asked for.
+ *
+ * The engine's compiler halves resolution until the model fits a leaf budget
+ * (`compileVoxelModelToVxlAsset`: `while (cells.size > maxLeaves) { downsample; vs *= 2 }`, budget
+ * 600k for a working asset). It says so — but only as a `console.warn` inside the headless Chrome
+ * the CLI drives, which reaches nobody, and `REVOXELIZE_FROM_VXL_MASTER_RESULT` did not carry it.
+ * So a request just under the knee came back at exactly twice the size, silently, with a zero exit
+ * code.
+ *
+ * The effect is worse than "not quite what you asked for", which is why this is said out loud
+ * rather than left to whoever compares two numbers in world.json: the result is NON-MONOTONIC.
+ * One step below the knee the asset is coarser than a COARSER request would have produced —
+ * measured on a 2.78 m stall with a 512³ master, 0.011 m gave 556k voxels and 0.0105 m gave 141k.
+ * Nothing about "I asked for finer voxels and got a blockier model" suggests looking at a budget.
+ *
+ * Detected from the .vxl header rather than from anything the engine says, deliberately: the
+ * header is what was actually written, and the CLI drives whatever engine the project vendored —
+ * including ones that predate any reply field carrying this.
+ */
+export function describeBudgetCoarsening(requested, achieved) {
+    const factor = achieved / requested;
+    if (!(factor > 1 + VOXEL_SIZE_EPSILON))
+        return { coarsened: false, factor: 1, note: '' };
+    return {
+        coarsened: true,
+        factor,
+        note: `note: baked at ${tidyVoxelSize(achieved)} m, not the ${requested} m requested — the model did not fit `
+            + 'the renderer\'s 600,000-leaf budget, so the engine halved the resolution to make it fit. '
+            + 'A slightly LARGER --voxel-size will come back finer than this one did; there is a knee '
+            + 'just above the size you asked for.',
+    };
+}
+/**
+ * What to actually do about a master that cannot go finer — which is NOT the same advice at every
+ * resolution.
+ *
+ * "Re-generate at a higher --voxel-grid" is a dead end once the master is already at
+ * {@link MAX_MASTER_GRID}: that is the top of the generator's allowlist, so there is no higher
+ * value to pass and the reader is sent to look for one that does not exist. At the ceiling the two
+ * things that DO still work are a resolution-independent source (the mesh path keeps a GLB, which
+ * has no ceiling at all) and a shorter bake — the floor is `targetHeight / resolution`, so the same
+ * cells spread over less world buy proportionally finer voxels.
+ */
+function wayPastTheFloor(resolution) {
+    return resolution >= MAX_MASTER_GRID
+        ? `${MAX_MASTER_GRID} is the finest grid the generator offers, so there is no higher `
+            + '--voxel-grid to ask for: either bake it shorter (--height, which spreads the same cells '
+            + 'over less world) or re-generate WITHOUT --direct-voxels, whose mesh source has no '
+            + 'resolution ceiling.'
+        : `Re-generate it at a higher --voxel-grid (up to ${MAX_MASTER_GRID}) for more detail.`;
+}
+/**
+ * The height a master re-bake will be resampled to.
+ *
+ * `--height` wins. Otherwise the height the asset was BAKED at, which the master path records in
+ * `voxelizeSettings` for exactly this. Falling through to neither is the case worth naming: a
+ * master is a grid, not a size, so the engine has nothing to derive a height from and lands on its
+ * own `DEFAULT_TARGET_HEIGHT` of 2 m — silently returning a 10 m building as a 2 m one. The mesh
+ * branch has no such gap, which is why `--height`'s "omit to keep the source's own size" only ever
+ * described half of this command.
+ */
+export function resolveMasterTargetHeight(asset, requested) {
+    if (requested !== undefined)
+        return requested;
+    const settings = asset.voxelizeSettings;
+    return isJsonObject(settings) ? positiveNumber(settings.targetHeight) : undefined;
+}
 /**
  * Refuse a master re-bake that asks for more detail than the master holds.
  *
  * The engine would refuse it too — `resampleMaster` throws "re-forge at a higher resolution rather
  * than upsampling" — but only after the browser, vite and the page have started. Saying it here
  * costs nothing and names the thing to do instead, which the engine's message cannot know.
+ *
+ * The floor is derived from the MASTER, not from the previous bake. Those are very different
+ * numbers: a 512³ master baked once at 0.1 m holds detail down to about `targetHeight / 512`, and
+ * refusing everything below 0.1 m would make that headroom unreachable from the CLI — which is the
+ * whole reason the master is stored rather than the working asset.
+ *
+ * Deliberately PERMISSIVE. The engine's real limit is the master's occupied span along the up
+ * axis, which is at most its resolution and usually less, so a request between
+ * `targetHeight / resolution` and `targetHeight / spanUp` still throws in the browser. That is the
+ * right way round: this pre-flight exists to avoid paying for a browser on a request that cannot
+ * work, never to refuse a size the master can serve. The engine stays the authority.
+ *
+ * Falls back to the old "no finer than the last bake" rule when either field is missing, so assets
+ * written before `sourceVxlMasterResolution` existed — or hand-edited ones — keep a guard rather
+ * than losing it.
  */
-export function assertMasterCanGoFiner(asset, requestedVoxelSize, name) {
-    const existing = asset.voxelSize;
-    if (typeof existing !== 'number' || requestedVoxelSize >= existing)
+export function assertMasterCanGoFiner(asset, requestedVoxelSize, targetHeight, name) {
+    const resolution = positiveNumber(asset.sourceVxlMasterResolution);
+    if (resolution !== undefined && targetHeight !== undefined) {
+        const floor = targetHeight / resolution;
+        if (requestedVoxelSize >= floor)
+            return;
+        throw new CliError(`"${name}" has a ${resolution}³ voxel master, which at ${targetHeight} m holds detail down `
+            + `to about ${floor.toPrecision(3)} m — ${requestedVoxelSize} m would be upsampling, and a `
+            + `master is only ever resampled coarser. ${wayPastTheFloor(resolution)} `
+            + 'world.json is unchanged.');
+    }
+    const existing = positiveNumber(asset.voxelSize);
+    if (existing === undefined || requestedVoxelSize >= existing)
         return;
-    throw new CliError(`"${name}" was baked at ${existing} m and its voxel master cannot be resampled finer than `
-        + `itself, so ${requestedVoxelSize} m would be upsampling. Re-generate it instead — or use a `
-        + 'voxel size at or above the current one. world.json is unchanged.');
+    throw new CliError(`"${name}" was baked at ${existing} m and records no master resolution, so there is nothing `
+        + `saying its master can be resampled finer than that — ${requestedVoxelSize} m may be `
+        + 'upsampling. Re-generate it instead, or use a voxel size at or above the current one. '
+        + 'world.json is unchanged.');
 }
 export async function revoxelizeAsset(options) {
     const { context, assetId } = options;
@@ -115,7 +236,12 @@ export async function revoxelizeAsset(options) {
  */
 async function rebakeFromMaster(options) {
     const { context, environment, token, assetId, voxel, assetName, source, log } = options;
-    assertMasterCanGoFiner(options.asset, voxel.minVoxelSize, assetName);
+    const targetHeight = resolveMasterTargetHeight(options.asset, voxel.targetHeight);
+    assertMasterCanGoFiner(options.asset, voxel.minVoxelSize, targetHeight, assetName);
+    if (targetHeight === undefined) {
+        log(`note: "${assetName}" records no baked height, so the engine's 2 m default applies. `
+            + 'Pass --height to keep it the size it is.');
+    }
     const runSession = options.session ?? withVoxelizeSession;
     const retryHint = `Nothing was spent — the master is still at ${source.masterUrl}, so this is `
         + 'safe to retry.';
@@ -130,7 +256,9 @@ async function rebakeFromMaster(options) {
             options: {
                 minVoxelSize: voxel.minVoxelSize,
                 maxVoxelSize: voxel.maxVoxelSize,
-                ...(voxel.targetHeight !== undefined ? { targetHeight: voxel.targetHeight } : {}),
+                // The RESOLVED height, not `voxel.targetHeight`: omitting it lands on the engine's 2 m
+                // default, which resizes every asset that is not 2 m tall.
+                ...(targetHeight !== undefined ? { targetHeight } : {}),
             },
         }, 'REVOXELIZE_FROM_VXL_MASTER_RESULT', VOXELIZE_TIMEOUT_MS, { maxRetries: 1 });
         if (!result)
@@ -155,6 +283,9 @@ async function rebakeFromMaster(options) {
     if (summary === null) {
         throw new CliError(`The engine returned bytes that are not a readable .vxl for "${assetName}". ${retryHint}`);
     }
+    const achieved = describeBudgetCoarsening(voxel.minVoxelSize, summary.minVoxelSize);
+    if (achieved.coarsened)
+        log(achieved.note);
     const timestamp = Date.now();
     const upload = await uploadProjectFile(environment, token, {
         gameId: context.metadata.gameId,
@@ -168,9 +299,22 @@ async function rebakeFromMaster(options) {
         size: bytes.byteLength,
         boundingBox: summary.boundingBox,
         boundingBoxInMeters: true,
-        voxelSize: summary.minVoxelSize,
+        voxelSize: tidyVoxelSize(summary.minVoxelSize),
         fragmentCount: summary.fragmentCount,
         ...(summary.voxelCount !== undefined ? { voxelCount: summary.voxelCount } : {}),
+        // Re-recorded from what the bake ACHIEVED, never from what was asked for. A `--height` re-bake
+        // that left the old height here would leave the next run computing its master floor against a
+        // size that no longer matches the asset — and recording the requested voxel size next to a
+        // `voxelSize` the compiler coarsened leaves world.json asserting two resolutions for one file.
+        // `fillInterior` is meaningless on this path: a master already carries its own occupancy.
+        voxelizeSettings: {
+            minVoxelSize: tidyVoxelSize(summary.minVoxelSize),
+            // Scaled by the same factor, so the ladder the creator asked for (a 5x spread, say) survives
+            // a coarsening rather than silently narrowing to 2.5x.
+            maxVoxelSize: tidyVoxelSize(voxel.maxVoxelSize * achieved.factor),
+            ...(targetHeight !== undefined ? { targetHeight } : {}),
+            fillInterior: false,
+        },
     };
 }
 /**