@hypersoniclabs/helix-cli 0.1.7 → 0.1.24-helix3.438

package/package.json

@@ -1,36 +1,101 @@
 {
   "name": "@hypersoniclabs/helix-cli",
-  "version": "0.1.7",
+  "version": "0.1.24-helix3.438",
   "description": "helix — the HELIX creator CLI: scaffold, validate, and publish Instant Worlds",
   "main": "dist/lib.js",
   "types": "dist/lib.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/lib.d.ts",
+      "default": "./dist/lib.js"
+    },
+    "./glb": {
+      "types": "./dist/glb/index.d.ts",
+      "default": "./dist/glb/index.js"
+    },
+    "./bridge": {
+      "types": "./dist/bridge/index.d.ts",
+      "default": "./dist/bridge/index.js"
+    },
+    "./bridge/types": {
+      "types": "./dist/bridge/types.d.ts",
+      "default": "./dist/bridge/types.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "glb": [
+        "dist/glb/index.d.ts"
+      ],
+      "bridge": [
+        "dist/bridge/index.d.ts"
+      ],
+      "bridge/types": [
+        "dist/bridge/types.d.ts"
+      ]
+    }
+  },
   "bin": {
     "helix": "dist/index.js"
   },
   "files": [
+    "assets",
+    "bridge-plugins",
+    "bridge-recipes",
+    "docs/bridge.md",
+    "docs/scene-hlod.md",
+    "docs/device-hand-reach.md",
+    "docs/visual-qa.md",
+    "docs/visual-qa-candidate-versions.md",
+    "docs/vehicle-simulate.md",
+    "docs/vehicle-audio-import.md",
     "dist",
+    "plugins/beamng-vehicle",
     "vendor"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "lint": "eslint \"src/**/*.ts\"",
-    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"
+    "pretest": "npm run build",
+    "test": "node scripts/ci-test.mjs",
+    "test:scene-hlod": "npm run build && node scripts/test-scene-hlod.mjs",
+    "test:scene-hlod-refinements": "npm run build && node scripts/test-scene-hlod-refinements.mjs",
+    "qa:vault-lifecycle": "npm run build && node scripts/run-vault-lifecycle-qa.mjs",
+    "test:looks-live": "npm run build && node scripts/looks-live-smoke.mjs",
+    "check:beamng-basegame-fixtures": "python3 scripts/verify-beamng-basegame-fixtures.py --root scripts/fixtures/beamng-basegame-0.39.4",
+    "check:addon-guard": "node scripts/sync-addon-definition-guard.mjs --check",
+    "check:dev-links": "node scripts/check-dev-links.mjs",
+    "check:slot-budgets": "node scripts/sync-slot-budgets.mjs --check",
+    "check:text-sources": "python3 scripts/check-text-sources.py"
   },
   "dependencies": {
+    "@anthropic-ai/sdk": "^0.131.0",
+    "@dimforge/rapier3d-compat": "^0.14.0",
     "@gltf-transform/core": "^4.4.0",
     "@gltf-transform/extensions": "^4.4.0",
     "@gltf-transform/functions": "^4.4.0",
-    "@hypersoniclabs/helix-manifest": "^0.3.4",
+    "@hypersoniclabs/helix-manifest": "0.3.43-helix3.90",
+    "@hypersoniclabs/helix-sdk": "0.1.9",
+    "@loaders.gl/textures": "^4.4.3",
     "commander": "^13.0.0",
+    "helix-runtime-three": "npm:three@^0.185.1",
+    "ktx-parse": "1.1.0",
     "ktx2-encoder": "^0.5.3",
     "meshoptimizer": "^0.22.0",
+    "playwright": "^1.61.1",
     "sharp": "^0.35.3",
-    "watlas": "^1.0.1"
+    "three": "^0.180.0",
+    "watlas": "^1.0.1",
+    "yauzl": "^3.4.0"
   },
   "devDependencies": {
     "@types/jest": "^29.5.14",
     "@types/node": "^22.10.0",
+    "@types/three": "^0.180.0",
+    "@types/yauzl": "^2.10.3",
     "jest": "^29.7.0",
+    "three-engine": "npm:three@0.185.1",
     "ts-jest": "^29.2.5",
     "typescript": "~5.7.3"
   },

package/plugins/beamng-vehicle/README.md

@@ -0,0 +1,129 @@
+# BeamNG Vehicle Bridge Plugin
+
+This plugin makes `helix bridge import <unpacked-mod>` the single preflight and conversion path for BeamNG road vehicles. It deliberately refuses a source rather than publishing a car that only looks complete in a file listing.
+
+The importer performs two gates:
+
+1. Candidate assessment selects exactly one `vehicles/<id>` root and requires JBeam, render geometry, source material bindings, an authored steering-wheel mesh, real cabin signals, rims **and authored tyre geometry**, four wheel signals, and recorded or source-referenced engine audio. JBeam power-steering text cannot satisfy the visual steering requirement, and a rim radius cannot satisfy the tyre requirement. Candidate-local `vehicles/common` dependencies win over any external common root.
+2. Conversion resolves the strongest renderable JBeam slot/flexbody closure, ranking actual selected-DAE coverage and a complete authored cabin ahead of optional-part volume. It retains only selected common wheel dependencies, expands legacy single/axle-pair road-wheel geometry to four measured shell corners before validation, runs Blender headlessly, preserves authored maps and UVs, semantically projects every vehicle surface onto a required `helix-palette/3` input, and embeds `helix-material-binding/1`. Before downstream material deduplication, reused source materials are split by node/primitive surface and stamped with `helix.vehicle-material-semantic/1`; family identity therefore survives optimization while authored atlases, UVs, and texture references remain shared. This metadata lets runtime consumers bypass name inference for new imports while retaining that fallback for older assets. One size-compatible authored tyre mesh is instanced at the four measured rim centres; all source and unselected tyre nodes are removed. Acceptance then tests dimensions, triangle budget, `+Z` forward semantics, exact-four tyre custody, 90% render-ready material coverage, engine placement, authored seat H-points and steering geometry, cockpit ergonomics, provenance, and audio evidence. Repairs remain recorded but cannot manufacture source eligibility. A rear-at-`+Z` export is converted again with a geometry-only front/back reflection; any other failed check blocks the import.
+
+BeamNG vehicle archives commonly reference tyres and materials shipped by the base game instead of duplicating them in every mod. Index that exact dependency once, review it as the named `beamngCommon` Bridge input, and pass it beside the Palette:
+
+```bash
+node plugins/beamng-vehicle/bin/index-beamng-common.mjs \
+  /path/to/unpacked/basegame > beamng-common.json
+python3 scripts/extract-beamng-abs-receipt.py \
+  --game-root /path/to/BeamNG.drive \
+  --steam-manifest /path/to/steamapps/appmanifest_284160.acf \
+  --beamng-version 0.39.4.0 \
+  --output beamng-abs-controller.json
+
+helix bridge import <unpacked-mod> \
+  --input palette=<helix-materials/palette.json> \
+  --input beamngCommon=beamng-common.json \
+  --input beamngAbsController=beamng-abs-controller.json
+```
+
+The receipt includes the path, size, and SHA-256 of every admitted file under `vehicles/common`, and its fingerprint therefore participates in the reviewed plan identity. Execution selects the exact JBeam/geometry/material closure, re-verifies those source bytes, and creates a confined snapshot backed by a content-addressed cache; a changed selected dependency refuses the import without re-copying the whole base-game corpus. The input is optional only when the mod already contains all required common assets. No host path is written to the GLB or durable source manifest.
+
+The separate `beamngAbsController` receipt proves that the source game's
+wheel-core release matches the adapter. Imports remain valid without it, but
+ABS stays explicitly unsupported and no runtime `AbsSpec` is emitted.
+
+Vehicle imports require the canonical Palette as a named, fingerprinted Bridge input:
+
+```bash
+helix bridge import <unpacked-mod> --input palette=<helix-materials/palette.json>
+```
+
+The Palette contract may be `helix-palette/4` (the current `asset-packs/helix-materials/palette.json`) or the older `helix-palette/3`; the importer reads only `families[].id`, `definitionVersion`, `physical.sizeMeters` and `shader.defaults`, which are identical in both, and the vehicle receipt records the contract it actually read. The supported list lives in `lib/palette-contract.mjs` and `bin/convert-beamng.py` (`SUPPORTED_PALETTE_CONTRACTS`).
+
+Bridge snapshots this plugin directory into `<work>/plugins/<id>` before running it, so everything the plugin imports must live inside it. The Vehicle Package v2 validator is therefore mirrored byte-for-byte at `plugins/beamng-vehicle/vendor/vehicle-package-v2.mjs`; `scripts/vendor-vehicle-package-v2.mjs --write/--check` keeps it and the top-level `vendor/` copy in step. Source DAEs (500 MB and more) are scanned in bounded chunks (`lib/dae-scan.mjs`), never read into one JS string.
+
+Local development:
+
+```bash
+npm run build
+node dist/index.js bridge plugins inspect plugins/beamng-vehicle --json
+node dist/index.js bridge plugins test plugins/beamng-vehicle --json
+node dist/index.js bridge plan /path/to/unpacked-mod --plugin-dir plugins/beamng-vehicle --plugin hypersonic.beamng-vehicle --json
+```
+
+External-plugin execution still requires the Bridge plan key and all permissions named by the reviewed plan. The plugin does not weaken Bridge's immutable source snapshot or provenance rules.
+
+## Material and vehicle-source receipts
+
+The converter reads all four BeamNG material stages. Later authored stages win, while conflicts, declaration provenance, null sentinels, unknown maps, and dynamic `@...` render targets remain explicit diagnostics. Texture resolution is deterministic: selected vehicle files, then mod files, then the reviewed base-game common snapshot; same-tier ambiguity refuses the binding. This parser is packaged with the plugin and never imports engine-repository code at runtime.
+
+Each successful terminal package emits six assets: the canonical GLB, `<vehicle>.vehicle-source.json`, the versioned `<vehicle>.vehicle-lowering.json` diagnostic aggregate, `<vehicle>.vehicle-package.json`, `<vehicle>.vehicle-addons.json`, and `<vehicle>.vehicle-build.json`. The lowering aggregate makes source semantics, structural exclusions, runtime blockers, functional-domain status, and provenance available to CLI and agent consumers instead of discarding them after packaging. The source manifest remains embedded in GLB extras and records the exact configuration and slot closure, fingerprints, material-resolution provenance, and coverage ledger.
+
+`lower-beamng.py` compiles the exact selected `.pc` and admitted JBeam closure into `helix.vehicle-package/2`, stable add-on records, and a source Build. Source literals cover the torque curve, idle/limiter, engine losses, gearbox and final drive, differentials, selected front/rear `pressureWheels` tire/brake values, lights/electrics, audio event references, seats/cameras, and rigid openables when present. Brake, suspension, tire, and differential expressions use a bounded data-only resolver for selected numeric variables, arithmetic, comparisons, boolean conditionals, and `case()`; direct selected-variable references are supported, source code is never evaluated, and unknown variables, calls, or tokens remain explicitly unsupported. HELIX total brake torque is derived from BeamNG's per-wheel axle values and the exact `.pc` variable overrides take precedence over selected JBeam defaults.
+
+Driveline topology is derived from the selected device graph: each connected wheel is traced upstream to the exact selected gearbox, so FWD and RWD packages contain only their driven axle and AWD requires an actual common centre differential. Duplicate devices, cycles, half-connected axles, missing final drives, unknown differential types, invalid fields, and ambiguous output ports retain source receipts but suppress runtime differentials instead of inventing a topology. Open, locked, LSD, and unit-exponent viscous devices lower exactly when every selected behavior field is representable. Nonzero BeamNG torque-loss, virtual-inertia, speed-limit, active-lock/controller, and non-unit viscous-exponent semantics remain explicit parity blockers; a topology-safe approximation stays runnable with `runtimeStatus=approximate` while `functionalDomains.differentials=false`.
+
+Selected tires lower one exact common or vehicle-local leaf per axle. Pressure, radius, width, friction, sliding friction, and load-sensitivity values keep literal/derived/unsupported receipts. HELIX's engine-wide exponential load kernel is deterministically sampled at 24 log-spaced points from 100 N to 40 kN for its compact `muLut`; Pacejka-style shape coefficients remain explicitly identified HELIX priors. Complete selected extraction sets `extractionComplete=true` and uses the selected radius/load data, but remains `functionalDomains.wheelsTyres=false` because the current runtime has no pressure or tire-width fields and still uses shape priors. Missing, duplicate, invalid, or unresolved tire semantics instead produce a complete prior runtime fallback, never a parity claim.
+
+Selected suspension evidence is lowered only from the chosen strut/coilover leaf part on each axle. Matching left/right spring, slow/fast bump, slow/fast rebound, velocity-split, precompression, and bound rows are retained with beam-space frequency and damping-ratio derivations. Structural parent/subframe beams and swaybar construction beams are explicitly excluded by part custody. Selected torsionbar stiffness is retained in `N.m/rad`, but the runtime suspension remains fail-closed: BeamNG element rates need motion-ratio geometry to become HELIX wheel rates, and the current package has one global damping triplet with no axle-specific fast/slow channels. The emitted HELIX suspension therefore remains an explicit fallback and `functionalDomains.suspension` remains false until those exact runtime mappings exist. Raw Lua/controller and other unsupported expressions remain explicit provenance instead of being presented as literal runtime parity. Soft-body deformation, fluids, wear, and detailed damage remain out of scope. Rigid panel poses are semantic on every device, physical bodies begin at `medium`, and detachment remains disabled on every production tier while source break groups are retained as future eligibility. Simulation, authority, package identity, and Build selection are quality-invariant. Bridge currently seals one canonical source GLB and truthfully maps every tier to it; optimized mesh/texture rendition IDs must not be selected until the optimizer has materialized and sealed those artifacts.
+
+## Engine recordings
+
+BeamNG names an engine sound with `soundConfig.sampleName` (and `soundConfigExhaust.sampleName`), which resolves to the mod's `art/sound/blends/<sampleName>.sfxBlend2D.json`. That blend is the mapping from recordings to rpm: `samples` is a list of load rows, each an rpm-ordered ladder of `["art/sound/engine/<set>/<file>.wav", rpm]`. (There is no `.sbeng` format in BeamNG; the blend JSON is the whole definition.) `lower-beamng.py` (via `bin/beamng_audio.py`) reads it and emits, for a mod that ships its own recordings:
+
+- `<out>/audio/<name>.wav` for every recording the selected blend names. A 16-bit PCM WAV at 44.1 or 48 kHz is copied byte for byte. OGG, FLAC, 24-bit or other-rate WAVs are transcoded with `ffmpeg` (`pcm_s16le`, channels kept, one bank sample rate: the most common one among the files); the import is **refused with a clear message when ffmpeg is needed and not installed** (`HELIX_FFMPEG` overrides the lookup). Bare-number file names are prefixed with their folder (`PSH_1768.wav`).
+- `audio.bank.blends.<sampleName>`: the source's own ladders, `[[file, rpm], ...]`, rpm values copied from the blend (sorted ascending; a repeated rpm makes the blend unusable rather than guessed at).
+- `audio.bank.assets[]`: `{ name, file, path: "audio/<name>", role: "vehicle.audio.bank.sample", mediaType: "audio/wav", bytes, checksumSha256, cid }` and **no `url`**. The URL must resolve to the sealed sample before the Vehicle Package is sealed and offered. The engine validator rejects a row with checksum/bytes but no URL, so this plugin validates with a `pending-publish://` placeholder and emits the rows untouched; `helix vehicle validate` on an unfinished package reports those URL errors.
+- `engineBlend` / `exhaustBlend`, `sampleCylinderCount` (the selected engine's cylinder count, see "Cylinder count" below), `strokes: 4`, and `engineLadder` / `exhaustLadder` slots with `buffers: ["blend:<NAME>"]`, `consumed: true`. When the source declines a separate exhaust sample (`sampleName: "0"` or unset, as the 993 does), the one recording serves both ladders. A layer that is stock while the other ships is left out (no `exhaustBlend` naming a blend the bank does not hold) and its slot says why.
+
+A WAV whose header is malformed (the mmbng 993 mod's PSH set declares 2 channels with the byteRate/blockAlign of mono) is copied with its header rebuilt around the untouched sample bytes, recorded in the asset provenance as `wav-header-repair`.
+
+When the sampleName has no blend file inside the mod it is a stock BeamNG blend; the Bridge import keeps its existing behaviour (no `bank`, the slot reason names the stock blend), which `helix vehicle audio-check` now fails as `AUDIO_ENGINE_UNSOURCED`. **The whole sound set — stock blends, starter, shut-off, afterfire, turbo, gear whine, shift levers, door latches, horn and soundscape, and what the base game plays for unnamed slots — comes from `helix vehicle audio-import <mod> --beamng-root <BeamNG.drive>`** (`bin/sim_audio_import.py`, `bin/sim_audio_beamng.py`, `bin/beamng_stock_events.py`, `bin/fmod_studio.py`, `bin/fsb5.py`; Assetto Corsa banks via `bin/sim_audio_ac.py`), which resolves stock FMOD events in the install's `content/art_sound.zip` banks and writes provenance on every recording. See [docs/vehicle-audio-import.md](../../docs/vehicle-audio-import.md). Tests: `python3 -m unittest test_sim_audio` (generated fixtures, no binaries committed).
+
+Packaging copies the WAVs to `assets/audio/` beside `<id>.vehicle-package.json`, re-hashing each against its package row. The Bridge reads an unpacked mod directory or a `.zip` of one (see "Zipped mods").
+
+## Cylinder count
+
+BeamNG has no first-class cylinder field, so `physics.engine.cylinders` and `audio.sampleCylinderCount` are derived from what the selected engine declares, strongest first:
+
+1. `beamngEngine` input: `--input beamngEngine=engine.json` with `{"cylinders": 6, "reason": "..."}`. A deliberate operator correction (fingerprinted into the plan key like any input); wins over everything.
+2. A numeric declaration: `soundConfig` / `soundConfigExhaust.fundamentalFrequencyCylinderCount` (what the base game's engines carry), or `cylinderCount` / `numberOfCylinders` / `firingOrder` on `mainEngine`. Provenance `source-literal`.
+3. The engine part's layout name, `information.name`: `1.6L F4 Engine`, `3.5L V8 Engine`, `2.0L I4`, `Flat-6`, `Inline 6`, `W12`. Provenance `derived`.
+4. The engine's sound identifiers: `starterSample` / `shutOffSample*` FMOD events and `sampleName` (`box4_2006_eng`, `v8flat_1986_eng`, `b4p_...`, `i6_...`). Opaque hash names are ignored. Provenance `derived`.
+5. **4**, only when nothing above exists, recorded as `defaulted` provenance and called out in the lowerer's stderr line (`lower-beamng: engine cylinders=4 [defaulted] ...`) and in `beamng-import-report.json` under `functionalVehicle.engineCylinders`.
+
+When several declarations disagree the strongest wins and the provenance detail lists the rest (`Lower-priority declarations disagree: ...`). A mod can mislabel its engine: the mmbng 993 names its part `3.2L V8 Engine` (template leftover) and carries no cylinder field, so it lowers to 8 until you supply `{"cylinders": 6}` through `beamngEngine`. The importer never measures the recordings: rung rpm labels in mods are not reliable enough to infer a firing frequency.
+
+## JBeam laxities
+
+The JBeam reader accepts what BeamNG's own reader accepts: comments, trailing commas, missing commas between values, repeated commas (`[1,\n, ]`), leading-zero numbers, and extra closers after the root object (a file ending `},\n},\n}` loads; the number of ignored closers is returned as the `strayClosers` diagnostic). Only closers, commas and whitespace may follow the root; any other trailing content, or a mismatched bracket inside the document, still fails.
+
+## Zipped mods
+
+`helix bridge detect|inspect|plan|import <mod.zip>` accepts a mod archive as downloaded from the BeamNG repository. The CLI hashes it, rejects the whole archive for any absolute or `..` path, duplicate entry, over-large entry, over-large total or decompression-bomb ratio (50,000 entries; 1 GiB per entry; 8 GiB total; 1000:1), extracts it with exclusive-create writes into a private temp directory (dropping `__MACOSX/` and `.DS_Store`), reads from inside a single wrapper folder when `vehicles/` is not at the top, runs the command, and deletes the directory. The plan key is content-addressed, so a zip and its unpacked folder plan identically.
+
+ABS is the first portable controller adapter. Version 1 recognizes only the
+fingerprinted BeamNG 0.39.4 wheel-core shape: one selected `enableABS=true`, one
+unambiguous brake owner per axle, the stock 100 Hz update rate, and equal
+front/rear `absSlipRatioTarget` values (or the fingerprinted 0.18 source
+default). It projects that bounded shape into the existing HELIX `AbsSpec` and
+records the selected configuration digest, activating part, axle sources,
+adapter version, Steam build, and exact `wheels.lua` SHA-256. Legacy controller
+files, alternate actuator shapes, custom frequencies, unequal axle targets,
+wheel-scoped or misplaced ABS parameters, and every unknown ABS controller
+shape remain explicitly unsupported and emit no ABS runtime block. The new
+diagnostics are sealed as `helix.beamng-functional-lowering/3`; terminal
+packaging remains backward-readable for pre-ABS `/2` records. Neither the
+extractor nor importer executes or translates Lua.
+Because HELIX uses bounded continuous modulation rather than BeamNG's per-wheel
+PID, v1 is runnable but `functionalDomains.abs` remains false until calibrated
+parity is proven.
+The committed source receipt can be reproduced against a matching base game:
+
+```bash
+python3 scripts/extract-beamng-abs-receipt.py \
+  --game-root '/path/to/BeamNG.drive' \
+  --steam-manifest '/path/to/steamapps/appmanifest_284160.acf' \
+  --beamng-version 0.39.4.0 \
+  --output /tmp/beamng-0.39.4-abs.json
+```
+
+The engine consumer seam is `vehiclePackageToTuning(package, { landSolver: 'v2' })`. The source Build intentionally contains stable source identities rather than invented Continuum CIDs; after publication resolves immutable Package references, the existing `createPrivateBuildDraft` → `freezeBuildDraft` workflow is the canonical Build seam.