@helix3/helix-cli 0.1.18-helix3.369 → 0.1.18-helix3.370

package/README.md

@@ -46,7 +46,7 @@ The token is stored in `~/.helix/credentials.json` (mode `600`). It's sent as
 | `helix publish [dir] [--thumbnail <file>] [--upload-source] [--source-dir <path>]` | Validate → resolve/create the world → upload files → finalize → set the cover image → print the play URL. `--upload-source` additionally sends the project's source through a separate private channel so the world can be edited on the website later — **off by default**. |
 | `helix list` | List your worlds. |
 | `helix vehicle validate <vehicle-package.json> [--glb <model.glb>] [--json]` | One-second local gate for a hand-authored Universal Vehicle, run before `item publish`. Checks the package against the engine's own validator (vendored, pinned to an engine commit), the engine publish gate, the backend pin requirements, `groundToBodyOrigin` vs `wheelRadius + staticRideHeight`, and the `componentBuild` digest; with `--glb` also resolves the four wheel nodes, checks each wheel node's origin is at its hub (`WHEEL_PIVOT_NOT_AT_HUB`), the +X-left / +Z-forward frame, the vehicle publish budgets and the articulation nodes. Exit `0` no errors, `1` errors, `2` unreadable input. See [Vehicle validate](#vehicle-validate). |
-| `helix vehicle preview <dir-or-package.json> [--glb <model.glb>] [--out <dir>] [--proxy-item <id>] [--json]` | Render a vehicle that is **not published yet** headless in the real runtime (hosted test grounds, Try Now through a published proxy vehicle whose car is swapped for your package + GLB, served from disk; nothing uploaded or recorded) and measure it: body-origin height against the declared `groundToBodyOrigin` (the number that locks at first mint), wheels on their hubs, arch clearance, rolling radius vs `wheelRadius`, steering, doors, seats. Prints a numeric summary with PASS/FAIL per check and writes frames, a contact sheet, `bundle.json` and `preview.json`. Exit `0` pass, `1` fail, `2` could not measure. See [docs/vehicle-preview.md](docs/vehicle-preview.md). |
+| `helix vehicle preview [<dir-or-package.json>] [--glb <model.glb>] [--addon <dir>]… [--item <id>] [--tolerance-cm <cm>] [--out <dir>] [--proxy-item <id>] [--json]` | Render a vehicle that is **not published yet** headless in the real runtime (hosted test grounds, Try Now through a published proxy vehicle whose car is swapped for your package + GLB, served from disk; nothing uploaded or recorded) and measure it: body-origin height against the declared `groundToBodyOrigin` (the number that locks at first mint), wheels on their hubs, arch clearance, rolling radius vs `wheelRadius`, steering, doors, seats. Prints a numeric summary with PASS/FAIL per check and writes frames, a contact sheet, `bundle.json` and `preview.json`. Boards with the candidate's own seat ids. With `--addon <dir>` (repeatable) it previews unpublished vehicle **add-ons** instead: fits each to the candidate car or a published car and measures the drawn geometry in world space against its anchor (wheels within 1 cm of each hub, socket/host-framed parts at their mount, not at the car's origin; tune-only ops read back from the live tuning). Exit `0` pass, `1` fail, `2` could not measure. See [docs/vehicle-preview.md](docs/vehicle-preview.md). |
 | `helix vehicle publish <dir> [--dry-run] [--item <id> --package-version <v> --reason <text>] [--json]` | One command from a vehicle package directory to a sealed, pinned, read-back-verified vehicle item: validate → upload each local WAV and write its verified public URL → mint → seal + pin the `vehicle` Package → read back. Resumable (ledger in `<dir>/.helix-publish`). See [Vehicle publish](#vehicle-publish). |
 | `helix vehicle audio-check <dir\|package.json\|item-id> [--json]` | Proves every sound the runtime will select resolves, is PCM WAV and is audible (pre-publish on local files, or read-back on a published item). |
 | `helix vehicle addon check <dir> [--grant] [--json]` / `helix vehicle addon publish <dir> [--no-grant] [--dry-run]` | Add-on fit gate (contract, `helixMeshFrame` anchoring, host hubs, hide targets + grants, the backend's `validate-fit` dry run) and the end-to-end add-on publish (grant → upload → seal + pin the `addon` Package → read back). |

package/dist/index.js

@@ -636,11 +636,18 @@ vehicleCommand
     .command('preview')
     .description('Render a vehicle that is not published yet in the real HELIX runtime (headless) and measure it: ride height against groundToBodyOrigin, '
     + 'wheels on their hubs, arch clearance, rolling radius, steering, doors, seats. Run it BEFORE the first mint, which locks groundToBodyOrigin. '
-    + 'Nothing is uploaded or recorded. Exit 0 = every blocking check passed, 1 = a check failed, 2 = could not measure')
-    .argument('<dir-or-package.json>', 'a directory holding vehicle-package.json + model.glb (the layout `vehicle publish` reads), or the package JSON itself')
+    + 'With --addon <dir> it previews unpublished vehicle ADD-ONS instead: each add-on directory (the layout `vehicle addon check|publish` reads) is fitted '
+    + 'to the candidate car, or to a published car (--item <id>, no car directory) by the engine\'s own fold, and the DRAWN geometry is measured in world space '
+    + 'against its anchor (wheels within 1 cm of each hub, socket-framed parts on their socket, host-framed parts at their authored position, inside the car, '
+    + 'not at its origin; a tune-only add-on has its ops read back from the live tuning). Nothing is uploaded or recorded. '
+    + 'Exit 0 = every blocking check passed, 1 = a check failed, 2 = could not measure')
+    .argument('[dir-or-package.json]', 'a directory holding vehicle-package.json + model.glb (the layout `vehicle publish` reads), or the package JSON itself; omit with --addon to fit to a published car (--item)')
     .option('--glb <model.glb>', 'the model (default: model.glb, or the one .glb, beside the package)')
+    .option('--addon <dir>', 'an UNPUBLISHED add-on directory (addon.json + model.glb) to fit to the car and measure; repeatable', (value, previous = []) => [...previous, value])
+    .option('--item <id>', 'with --addon and no car directory: the published vehicle to fit the add-ons to (default: the proxy item)')
+    .option('--tolerance-cm <cm>', 'with --addon: how far a drawn part may sit from its anchor (default: wheels 1 cm, socket-framed and host-framed parts 3 cm)', (v) => Number(v))
     .option('--out <dir>', 'frames, contact-sheet.jpg, bundle.json and preview.json go here (default: <dir>/.helix-preview)')
-    .option('--proxy-item <id>', 'a published vehicle the QA account can Try Now; the runtime loads it and the candidate replaces its car')
+    .option('--proxy-item <id>', 'a published vehicle the QA account can Try Now; the runtime loads it and the candidate replaces its car (and its slot board is what --addon fits to)')
     .option('--occupants', 'also seat an avatar in every seat and judge the cabin (slow)')
     .option('--storage-state <file>', 'Playwright storageState of a signed-in QA account (default: sign in with `helix login`, or $HELIX_VQA_STORAGE_STATE)')
     .option('--chrome <path>', 'Chromium executable (default: Playwright Chromium / Chrome for Testing, headless; the macOS system Chrome is refused)')
@@ -656,7 +663,8 @@ vehicleCommand
         let summary;
         try {
             summary = await runVehiclePreview({
-                target, glb: opts.glb, out: opts.out, proxyItem: opts.proxyItem, occupants: opts.occupants, apiBase, webBase,
+                target, addOns: opts.addon, item: opts.item, toleranceCm: Number.isFinite(opts.toleranceCm) ? opts.toleranceCm : undefined,
+                glb: opts.glb, out: opts.out, proxyItem: opts.proxyItem, occupants: opts.occupants, apiBase, webBase,
                 token: creds?.token ?? null, storageState: opts.storageState ?? process.env.HELIX_VQA_STORAGE_STATE, chrome: opts.chrome, quiet: opts.json,
             });
         }