@hypersoniclabs/helix-cli 0.1.7 → 0.1.23

package/docs/visual-qa-candidate-versions.md

@@ -0,0 +1,71 @@
+# Visual QA of a candidate version: `--package-version`
+
+The backend refuses to move a listed item to a new Package Version until **that new version** has a passing visual-QA
+run (`VISUAL_QA_REQUIRED`). A plain `helix item visual-qa <id>` renders the item's *current* pin, so on its own it can
+never produce that run. `--package-version` renders the candidate instead:
+
+```
+helix item visual-qa <item-id> --package-version 1.0.12 --vehicle-package vehicle-definition.json --local-critic
+helix item visual-qa <item-id> --package-version 1.0.4 --submit          # an add-on, wearable or avatar
+helix item visual-qa <item-id> --package-version 1.0.2 --submit          # a Prop or Device
+```
+
+| Category | Route to the candidate | Needs |
+|---|---|---|
+| vehicle | Try Now session with `trial.packageVersion` + `trial.vehiclePackage` | `--vehicle-package <file>` (the move's vehicle package JSON; a `{ "vehiclePackage": … }` wrapper is accepted) |
+| avatar | Try Now session with `trial.packageVersion` | — |
+| vehicle add-on, character add-on, wearable | customiser: `GET …/universal-items/<host>/add-ons?previewItemId=&previewPackageVersion=` and `GET …/universal-items/<add-on>?previewPackageVersion=` | — |
+| Prop, Device | item viewer: `GET …/universal-items/<item>?previewPackageVersion=` under the CLI creator login | — |
+| animation, scene | refused: their routes only show the pinned version | — |
+
+Only the item's creator, an admin, or the hosted runner holding the job's lease can open a candidate; the CLI renders as
+your `helix login` unless `--storage-state` says otherwise. A `--package-version` equal to the item's pin is the normal
+run.
+
+## Moving the item once it passed
+
+`--submit` on a passing candidate prints the next command; run it to make the version the one owners resolve:
+
+```
+helix item set-version <item-id> --package-version 1.0.12 --reason "fixed the cuff seam"
+```
+
+The pin (`packageId`, `version`, `manifestCid`) comes from the public Package API, and the request is
+`POST /api/v1/universal-items/<id>/versions`. If the gate still refuses (422) the server's message is printed first,
+then its `remedy` and any hosted render it queued. `helix item visual-qa <id> --status` lists the item's
+`pendingVersions` (sealed, not current) with each one's latest run. A `--package-version` the package does not have
+fails with the sealed versions listed; a non-creator gets a first-line explanation that only the creator, an admin or
+the hosted runner can render an unreleased version.
+
+## How it stays honest
+
+- **Identity is the candidate's.** The version is read from the item's own pinned package
+  (`GET /api/v1/continuum/public/packages/<packageId>/versions/<v>`; it must be sealed), so the bundle's
+  `packageVersion`, `manifestCid`, root document and model CID describe the candidate. An item with no pin is refused.
+- **The server names what it served.** The Try Now response's `trial.candidate` (`packageId`, `packageVersion`,
+  `packageVersionId`, `manifestCid`, `vehicleChecksum`, `modelCid`) must agree with the sealed version; it then fills the
+  bundle's `packageVersionId` and, for a vehicle, `vehicleChecksum` — minted server-side after preparing the vehicle
+  package, so it is unknown until then. The backend only accepts a non-current vehicle run whose
+  `bundle.item.vehicleChecksum` is the checksum it minted in that trial.
+- **The runtime must agree.** The vehicle route still checks that the runtime served exactly that checksum, and every
+  route still requires the candidate model's CID among the fetched assets. A Prop or Device candidate also requires the
+  item viewer's returned Package ID, Version and manifest CID to equal the sealed Version. The evidence records the
+  definition/root and model CIDs; a Device must have a matching `helix.device/1` definition Version and web GLB.
+- **It never falls back.** No `trial.candidate` (backend refused or not deployed), a session that was never requested,
+  a customiser that never listed add-ons, a preview request that was refused, or a response built from another version
+  is a harness error, so the run fails closed instead of judging the current version under the candidate's name.
+
+`bundle.json` records what was seen under `facts.candidate` (`sessions`, `previews`, the sealed root/model CIDs and bound identity).
+
+## Mechanics
+
+Command code sets a module-level candidate config in `src/visualQa/browser.ts` (`setCandidate`) around the render
+route; every browser the route opens installs Playwright routes that rewrite those requests and read their responses
+before the page sees them. The routes themselves are unchanged. The pure parts (flag checks, body/URL rewrites,
+response → identity) are in `src/visualQa/candidate.ts`.
+
+## Hosted runs
+
+A refused version move queues a hosted job whose claim carries `target.packageVersion` and, for vehicles,
+`target.vehiclePackage`; the runner passes both to the same harness. `--hosted` itself still queues the current version,
+so `--package-version` is not combined with it.

package/docs/visual-qa.md

@@ -0,0 +1,462 @@
+# Visual QA: `helix item visual-qa`
+
+A universal item is judged **rendered, in the real HELIX runtime**, before it can be listed. Every earlier gate
+(triangle and draw-call budgets, skeleton validity, bind checks) is structural or numeric; none of them looks at
+the result, and a car with its wheels sunk into the arches passed all of them.
+
+```
+helix item visual-qa <item-id> --submit            # render, measure, record the verdict the listing gate checks
+helix item visual-qa <item-id> --local-critic      # dry run: render, measure and run the vision critic locally
+```
+
+## What it renders
+
+| Category | Route | Frames |
+|---|---|---|
+| vehicle | hosted test-grounds world (`?tryItem=`), live runtime | front, rear, both sides, both 3/4s, each wheel close-up, cabin, each door/lid open, steering at full lock, moving, then **every declared seat with an occupant in it** (`occupant.<seat>.*`: side through the glass, 3/4 front through the windscreen, a cutaway with that seat's door panel hidden, a head-to-roof close, hips and feet; the driver also with its door opened by its real key) |
+| avatar | hosted test-grounds world (`?tryItem=`, plus `&tryInstance=` with the owner's copy when the item is not Published), live runtime; the avatar is the local player | front, an unlit **base-colour reference** of the same front view (`reference.albedo`), back, both sides, both 3/4s, head, torso and feet close-ups, the walk **paused mid-stride** (`motion.stride.*`: side, front 3/4, legs from the side and the front), then walking away (followed from behind) and towards the camera; then the **world walk** frames (`walk.*`, `subject` = the avatar); then (avatar@3) the **Marketplace item page's walk**, paused with each arm swung fully back, from the true left side, true right side and back (`motion.preview.{left,right,back}.{a,b}`) |
+| vehicle add-on | marketplace customiser on each declared host, this part alone | 3/4 front/rear, side, part close-up, each corner for wheels |
+| character add-on, wearable | customiser on each declared base, individually; then the **world walk**: worn on each declared base in the hosted test grounds (a Try Now draft) and walked | front, back, side, close-up; then per base `walk.front`, `walk.side`, `walk.back`, `walk.turn`, `walk.close` (group `walk`, `subject` = base id) |
+| prop | public item viewer | front, 3/4, side, top |
+| animation (emote) | the emote's item page, played on Base Male and Base Female (the page's "equipped avatar" request is answered with each base's pinned model; the mixer is frozen and the clip seeked) | start, 25 %, 50 %, 75 %, end of the clip, per base |
+| scene (Home) | the Home walk-through a visitor opens (`/marketplace/homes/<id>/preview?debug=1`) | arrival, the four directions from the spawn, an overview from outside, up to three interior / walk-in standpoints probed from the live scene |
+
+Tune-only add-ons with no model have nothing to render and are exempt.
+
+The public item viewer and customiser measure the model's scene-level Group container. Studio lighting and
+contact-shadow meshes sit outside that container; authored model and mesh names never decide what is measured.
+An empty or ambiguous model container fails closed instead of treating stage geometry as the item.
+
+## What it measures
+
+Asserts are numeric, taken from the live scene graph on the **drawn** geometry (index-referenced vertices of
+visible meshes, never accessor min/max or node origins):
+
+- every item: frame not blank, no NaN/collapsed/invisible meshes, textured, size inside the category envelope;
+- avatars (route `avatar@2`, still stage 1 of `avatar@3`): the Try Now player is a rigged, skinned mesh; its lowest drawn vertex sits on the ground plane at rest and through a held-W walk; held W moves it and swings its legs (the locomotion animation drives this skeleton); toes point at the engine's forward and the drawn height matches the declared body height (those two warn). Then whether it LOOKS right and DEFORMS right, every one blocking:
+  - `avatar.materials_resolved` — every drawn primitive has a material, every map it samples decoded, the base-colour textures the GLB declares reached the renderer, and the model bytes did not fail to load;
+  - `avatar.no_emissive_washout` — no material emits a flat colour (emissive >= 0.5 with no emissive map) over more than 25 % of the drawn surface (the "Cream Hoodie Girl" defect: Meshy's emissiveFactor 1 kept, its emissive map dropped, so the whole body glows white);
+  - `avatar.colour_matches_albedo` — the same front view is rendered twice more with the avatar re-shaded (unlit base colour, then a flat magenta mask that marks its pixels; restored at once). Over the avatar's own pixels the lit render must not be > 35 luma brighter than its base colour while keeping < 50 % of its chroma or < 65 % of its contrast (washed out), nor black, nor flat. Good avatars measure -68..+20; metal is darker lit than its albedo, which is fine;
+  - `avatar.limbs_untwisted` — at every walk sample each limb bone's twist about its own axis away from its bind pose stays under 50-55 deg (Base Male/Female: <= 28, worst good avatar 33, a rest-roll mismatch 107-132) and no knee bent more than 6 cm bends backwards (> 110 deg from forward; humanoids measure <= 37, Unitree G1's robot knee 62);
+  - `avatar.skin_intact` — at every walk sample < 3 % of the skinned surface (area-weighted, sampled triangles) collapses below 15 % / stretches over 4x its rest area, and < 1.5 % has an edge stretched over 3x (torn or candy-wrapper joints).
+  Calibration (14 published avatars, Base Male/Female, both Cream Hoodie Girl items and six broken fixtures) is in `src/visualQa/avatar.spec.ts`;
+- avatars, route `avatar@3` (2026-10-06): a second stage on the **Marketplace item page** (`/items/<id>`, the production
+  viewer: the shared walk clip retargeted by the Marketplace's own retargeter, plus the platform DynamicsLayer). The page's
+  own AnimationMixer is found (an `Object.prototype` hook on `_accuIndex`), held at 16 phases of one walk cycle (the
+  viewer's pause, at chosen times), and at each the posed vertices the page draws are read (`SkinnedMesh.getVertexPosition`).
+  Added after **Cream Hoodie Anime Girl 1.0.6** passed avatar@2 while, in this walk seen from the side, its forearms
+  walked inside the hoodie, the hoodie's side tore open as an arm swung back, a strand hung at the waist and its back hair
+  stood off as a slab. Every one blocking; anything it could not read is `not measured` (a failure):
+  - `avatar.preview.arms_clear` — the forearm/hand surface more than 3 cm inside the torso/hips (nearest torso vertex's
+    posed normal, within 10 cm), averaged over the walk cycle, stays under 13 % (good max 8.5 %, Pastel Cyberpunk, whose
+    arms are bound at 20 deg; Cream Hoodie 1.0.6 18 %);
+  - `avatar.preview.surface_closed` — boundary vertices of one connected surface that touch at rest (< 2 cm) but lie
+    7+ edges apart (the two sides of a slit) never part by more than 5 cm (good max 0.8 cm; 1.0.6 36 cm);
+  - `avatar.preview.silhouette` — geometry that is neither torso nor limb (hair and ears hung from the head; capes, coat
+    tails, accessories on their own bones) never stands more than 35 cm (at 1.70 m) behind or beside the torso's own
+    outline between the hips and the neck (good max 28 cm, Kemonomimi's flaring hair and cape). Cream Hoodie 1.0.6's back
+    hair reads 22 cm, inside that envelope: a slab is told from a flaring cape by its look, which is the critic's to judge
+    on the side frames below; this assert catches gross outliers;
+  - `avatar.mesh.no_strands` — no thin fragment floats free (> 2 cm from every other surface) of the rest mesh;
+  - `avatar.bind_pose` — each upper arm is bound at least 17 deg from straight down (standard 36; the walk adducts the arm
+    ~24 deg from the clip's A-pose, so 1.0.6's 13-15 deg walks the arms into the body) and every other canonical bone
+    within its envelope of Base Female's bind direction;
+  - `avatar.preview.posture` — neck and torso lean through the walk within 25 / 15 deg of Base Female's.
+  Frames for the critic: `motion.preview.{left,right,back}.{a,b}` — the walk paused where the left (`a`) and right (`b`)
+  arm swings furthest back, from the avatar's true left side, true right side and back. A candidate version's item read
+  is rewritten (`previewPackageVersion`) exactly as for a Prop. Calibration and the broken Base Male fixtures
+  (`scripts/make-avatar-gate-fixtures.mjs`: arms-low, head-forward, strand, slab) are in `src/visualQa/avatarPreviewMath.spec.ts`.
+  On an avatar, `wear.walk.no_holes` / `wear.walk.no_poke_through` with no separate outfit to measure are reported
+  `not measured` (warn), never a pass, and are not required: the preview asserts measure tears and buried limbs on any avatar;
+- vehicles: drawn wheels at the physics hubs, tyre-to-arch clearance and no body poke-through, ride height,
+  wheels spin with speed, steering wheel and front wheels turn, every panel reaches its declared open angle,
+  every seat addressable;
+- vehicle occupants (route `vehicle@2`, engine >= 0.3.169): the account's own avatar is walked to each declared seat's
+  door and seated with the real E key, one after another (the runtime has no seat-switch key and a Try Now room
+  takes one player), and measured on the DRAWN occupant (skinned vertices) against the DRAWN car (triangles around
+  the seat): `vehicle.occupants.head_clearance` (crown to the first surface above the skull, >= 10 mm),
+  `.hips_on_seat` (not hovering over the cushion, not through the floor pan under it; `.hips_sink_depth` warns
+  when the buttocks sit more than 10 cm into the cushion volume), `.feet_on_floor` (soles within -50..+300 mm of the
+  floor or pedal below), `.hands_on_wheel` (driver: nearest finger/hand bone to the steering wheel <= 70 mm),
+  and the posture checks read off the drawn bones and skull (`vehiclePosture.ts`): `.torso_angle` (hip -> neck base 5..32 deg from
+  vertical), `.knees_up` (thigh -25..+35 deg of horizontal) and `.head_in_wings` (car within 60 mm of the skull below the crown
+  on two or more of back/left/right),
+  `.boarded` (an occupant could be seated in every declared seat) and `.engine_current` (the engine the page
+  resolved is >= 0.3.169). The cutaway frames hide only the seat's own door panel, for that frame, and restore it;
+  their captions say so. `HELIX_VQA_VEHICLE_ONLY=occupants` skips the other phases for debugging (such a run
+  records a harness error and can never be submitted as a verdict);
+- vehicle occupant CLIPPING, measured (`vehicle.occupants.penetration`, block; `vehicle.occupants.near_contact`, warn):
+  every skinned vertex of the seated occupant (skin and clothes) against the car's drawn triangles around the seat.
+  A vertex is through a surface when that surface lies between it and the bone its largest skin weight belongs to
+  (no normals, no closed meshes needed; the depth window is a limb's radius, so nothing on the far side of the car
+  counts); depth is its distance behind that surface, never more than to the nearest surface of the same mesh. What a
+  vertex cannot see is measured the other way round, as cabin surface sampled every 5 mm INSIDE a limb's drawn
+  surface: a small closed object between skin and bone (a steering rim through a knee, a pedal pad inside a sole), and a
+  wall a bone itself goes through (a floor through the shin of a foot sunk 11 cm). Hips, torso, thighs, upper arms and
+  the head against the occupant's OWN seat are support (`hips_sink_depth` judges those), found geometrically so a seat
+  baked into `bodyshell` works; a hand inside its own thigh is measured against the thigh's drawn surface. Tails,
+  skirts, coat flaps, hair and ears (secondary/spring bones) are the avatar's and are not judged. A cluster (3 cm-
+  connected points through one mesh) FAILS with >= 3 points deeper than 8 mm and >= 4 cm² of it deeper than 8 mm, or
+  deeper than 25 mm over >= 1.5 cm² (a part swallowed deeper than a finger is thick); a hand on the wheel and a sole on
+  a pedal are meant to touch and fail only beyond 20 mm. Everything else is a near-contact. Area is projected onto the
+  penetrated surface, each vertex standing for the patch its mesh spacing gives it (less at the edge of a region, so a
+  lone vertex spike stays small). `facts.occupants.seats[].measure.penetration` and the asserts' `measured.clusters`
+  carry the table: seat, body part (head/torso/arm/hand/hip/thigh/knee/leg/foot), cabin part
+  (roof/pillar/door/glass/seat/dash/wheel/pedals/floor/console/self/other, from the mesh name, or from where a
+  generically named triangle sits), mesh, max depth, area. Calibration (must-fail / must-pass fixtures cut from live
+  pulls): `src/visualQa/vehiclePenetration.spec.ts`;
+- add-ons: each instance lands at its socket (a wheel set is four distinct wheels at four hubs), not at the host origin;
+- wearables: on-body bounds for the slot, not floating;
+- wearables, character add-ons and avatars, while WALKING (the world walk below, per base): `wear.walk.no_holes` and
+  `wear.walk.no_poke_through` (block, `subject` = base id);
+- animations (per base body): the clip's tracks bind to the base's skeleton, the drawn skin really moves, the pose leaves
+  the bind pose (no T-pose), every key and skinned vertex is finite, the skin neither collapses nor explodes, the lowest
+  point stays near the floor; the pinned clip's bytes are hashed against the pinned CID;
+- scenes: the scene document the runtime streams hashes to the pinned root document (a legacy home-shell fails this), the
+  visitor spawns at the declared spawn point and stands still on something, stays on the floor at standpoints probed from
+  the live scene (a missing floor collider drops them), and the drawn extent agrees with the declared placement bounds.
+
+### World walk (wearables, character add-ons, avatars)
+
+An owner-proxy review of the catalogue (2026-10-03) wore and walked items that had PASSED the gate and found about 30 %
+still broken in motion: holes opening in skirts as the legs move, feet coming out through shoes and gown hems, models that
+did not match their titles. The customiser's idle pose shows none of it, so every worn item is also worn and walked in the
+real runtime, on each declared base (an avatar: the avatar itself, in the same Try Now session as its own route).
+
+How it is worn: the sanctioned Try Now draft, the same request helixgame.com's customiser builds
+(`lib/iwp/trial-launch.ts`): `trial = { itemId: <base>, draft: { slots: { <slotId>: { kind: 'catalog', itemId } },
+appearance } }`, kept in the tab's sessionStorage (`helix:item-trial:v1:<key>`, bound to the signed-in account) and opened
+as `/play/universal-item-test-grounds?tryItem=<base>&tryDraft=<key>`. The backend composes it
+(`AddOnsService.resolveTrialCompositionWithManager`); nothing is bought, equipped or saved, and the account needs no copy.
+The slot comes from the base's add-ons list. The session answer names the composed add-on's model URL, which must carry
+the version's model CID (else a harness error), and the base model, whose index buffers rebuild the triangles the item
+hides. The item's meshes are found by the composer's `compaddon:<slotId>|` prefix or the item GLB's node names.
+
+The walk is driven with the real keys: Alt (the engine's walk tier; a bare W runs) + W forward with the camera pinned
+behind, W + D to turn, then S back towards the engine camera. Eight poses are snapshotted on the way (the bones' local
+transforms), then replayed and held by the pinned camera for the frames, the hole renders and the geometry pulls. Measured
+(`src/visualQa/worldWalkMath.ts`):
+
+- `wear.walk.no_holes` — see-through holes. The runtime hides the body a garment covers by collapsing those triangles
+  (helix-web-engine-new `regionHide.ts`), so wherever the garment fails to cover a hidden region the player sees through
+  the body. Each pose is rendered twice from two directions (front/back or the sides, alternating): `p1` draws the hidden
+  triangles again (rebuilt from the base model's own index buffers), plus the drawn skin that sits deep inside the
+  garment's rest coverage (more than 5 cm from any skin it leaves bare, so a hem or a slit uncovering the band next to it
+  in a normal stride does not count), in flat magenta over everything flat (the item green, the rest grey, the world
+  hidden); `p2` the item alone, front faces only. A magenta pixel the item's outer faces do not cover is a hole (hidden
+  body poking out of the garment is invisible in the real render and does not count). A pose view fails when its largest
+  8-connected hole is at least 120 px AND 0.4 % of the item's own pixels. Measured: Cassandra Goth Dress (legs hidden,
+  walking out of the gown) 6 900-7 100 px / 12-14 %; a 22 cm hole cut in Pullover Hoodie's back 4 600-4 800 px /
+  12-13 %; every control at most 25 px.
+- `wear.walk.no_poke_through` — body through the garment, two ways. (1) A drawn vertex the garment COVERED at rest (a
+  garment surface within 15 cm outside it, none between it and its bone) is through when, in a walk pose, a garment surface
+  lies between it and the closest point on its own bone (the parent's segment included, so the skin over a bent knee is
+  anchored across the limb, not along it) and it is out in the open: no garment straight over it within 8 cm and at most
+  half of its outward hemisphere meets the garment within 15 cm (loose trousers' shell 8-10 cm off a knee whose skin
+  crossed an inner layer reads 0.78; a thigh out through a skirt panel 0.27). What an item is built to sit inside (an
+  ear's root in the skull) is never covered at rest, so it never counts. (2) A joint that has left the garment: its
+  root-to-joint bone chain changed garment-crossing parity since the rest pose (crossings within 4 cm of the garment's
+  own open edges — a cuff, a hem — are a bone grazing an opening and do not count), it was enclosed at rest and now at
+  most half of 26 directions meet the garment within 30 cm, down by at least 0.25 (a shin out through a gown's front
+  panel, leaving the foot floating): its drawn, uncovered vertices count, at the distance back to the crossing. Hands and
+  fingers never count as a joint leaving (an arm swinging into a skirt), and through a surface fail only beyond 20 mm.
+  Clustered (3 cm); a cluster fails with >= 3 points deeper than 8 mm covering >= 4 cm².
+
+Calibration (must-fail / must-pass, live walks): `src/visualQa/worldWalkMath.spec.ts`. The critic gets the walk frames and
+two walk questions (`wear.walk.covered`, `wear.walk.follows`), and every category now asks `item.matches_title` (is what the
+frames show the thing the title names, with its defining feature: a wedge on wedge sandals, curls on curly hair). The
+backend requires the walk asserts for these categories behind `VISUAL_QA_WORLD_WALK`.
+
+A candidate version (`--package-version`) is asked for as `{ kind: 'catalog', itemId, packageVersion }` in the draft
+slot. helix3's backend accepts it (backend #1693), so a candidate walk composes the candidate through the same path and is
+measured like any other; the candidate's route is recorded as `customiser-preview + test-grounds walk`. If a backend still
+refuses it (a 4xx), the stage records the refusal in `facts.worldWalk.<base>.skipped` and the walk asserts are absent, so a
+server that requires them fails the run closed rather than judging the current version in the candidate's place.
+
+A hole pass that drew no item at all — 0 item pixels in every pose view — is a missing measurement, not a pass: `no_holes`
+fails closed with `not measured: the item was never drawn in the walk pass` and the run re-renders (a first-run race that
+left the item out of the hole pass once measured nothing and reported a false pass; the identical version re-rendered drew
+30k-60k item pixels per view and failed). `no_poke_through` fails closed the same way when the item has no drawn triangles.
+
+`--no-world-walk` (or `HELIX_VQA_WORLD_WALK=0`) skips the stage. Debug: `HELIX_VQA_WALK_GAIT=run` walks at the run gait,
+`HELIX_VQA_WALK_DEBUG=1` writes the `p1`/`p2` renders (`walk-debug/`), `HELIX_VQA_WALK_DUMP=1` the pulls the calibration
+fixtures are cut from (`walk-dump/`). Cost per base: about 20 s of rendering after the page is presented (a full base,
+browser launch to close, is listed in `facts.worldWalk.<base>.timings`).
+
+### Every declared rendition (vehicles)
+
+A vehicle package declares its model renditions as manifest variants (`vehicle.model.web.low` = `target-mobile-low`,
+`vehicle.model.web.medium` = `target-balanced`, ...), and the runtime draws whichever one the player's Graphics tier
+selects (`mesh.visual.tiers[tier].renditionId`). The default pass renders `target-balanced` with every frame. Then each
+other declared rendition gets its own load of the car in the same runtime, served that rendition's sealed bytes at the
+model URL the runtime requests (a headless QA browser resolves the balanced tier, and a forced `low` Graphics setting
+was measured not to reach the vehicle spawn). The bytes are fetched from the rendition's own artifact
+(`mesh.visual.renditions[].artifactRef`) and must hash to its manifest CID, and the pass must see the runtime take them
+(`facts.renditions.passes[].substitution.served`); anything else is a harness error. Such a pass takes no regular
+frames (one small diagnostic frame beside the bundle, never in `bundle.frames`), only EVIDENCE frames of what it
+measured wrong (below), skips steering, cabin view and drive, and
+measures wheels at the hubs, arch clearance, articulation, seats, every occupant assert, NaN/invisible, textures and
+scale. Every vehicle assert carries `rendition: '<variant id>'`, the default ones too. `facts.renditions.passes` records
+each pass's tier, wall time, drawn triangles, substitution and assert results. Measured: the Subaru 1.0.18
+`target-mobile-low` puts both rear tyres 4.9 / 5.3 cm into the arches (`vehicle.wheels.arch_clearance` fails with
+`rendition: 'target-mobile-low'`) while `target-balanced` clears them; the extra pass costs about 80 s of rendering.
+
+### Evidence frames
+
+A measured failure carries its own picture, in the bundle (group `evidence`), shown to the critic and on the contact
+sheet. The measured geometry is DRAWN OVER the render, projected through the live camera, so the clash is in the
+picture even where it is buried (a pedal pad inside a foot draws nothing a camera can see):
+
+- `evidence.penetration.<seat>.<n>` (`evidence.<rendition>.penetration.<seat>.<n>` on another rendition): one per failing
+  `vehicle.occupants.penetration` cluster, the worst 3 of the pass, one per (seat, body part, cabin part). Only the occupant
+  and the clashing cabin mesh are drawn (every other mesh of the car is hidden for that frame and restored); the camera
+  stands outside both, on the side where the body comes through the surface, in the view the occupant's other parts
+  least occlude. Over it: the clashing mesh's triangles around the clash in translucent cyan, and every point where the
+  measure found the occupant and the part overlapping in red. A legend and the caption give depth and area.
+- `evidence.<rendition>.wheel.<w>`: on a non-default rendition, each wheel that fails `at_hubs` or `arch_clearance`
+  there, low and square-on, with the measured cross-section over it: the tyre's circle (white), the body cut across the
+  tread where it reaches deepest (yellow), and the tyre sector the body reaches into in any of five planes across the
+  tread, filled red.
+
+The critic is told that cutaway frames hide parts on purpose and that the colours are the measurement drawn over the
+render. `facts.penetrationEvidence`, `facts.wheelEvidence` and `facts.occupants.seats[].penetrationEvidence` list them.
+The contact sheet wraps every caption and assert reason instead of cutting it.
+
+### The critic's location rule
+
+A failing `vehicle.occupant.*` check must name WHERE: `location` = { seat (from the frame id), bodyPart, cabinPart, frame }.
+The server counts `vehicle.occupant.no_clipping` as failed only when at least two failing votes name the same (seat, body
+part, cabin part) and one of them names a frame the bundle carries; otherwise the failing votes are recorded as warnings
+on the run, never as a reason. A light touch that does not visibly pass through the surface is not a fail. The measured
+`vehicle.occupants.penetration` is independent of the critic and blocks on its own. `--local-critic` asks for the same
+`location` field but makes a single call (no votes).
+
+### Harness reliability
+
+A browser that crashes under load (`Target crashed`, `Page crashed`, `Frame was detached`) says nothing about the item: the
+route is rendered once more from a fresh browser and `facts.retry` records the first attempt. A run that still ends with a
+harness error is `error`; the local critic is not called for it. A browser that HANGS (a browser-slot wait on a loaded box,
+a renderer that never answers) is bounded by a watchdog: the local CLI aborts its own browsers after
+`HELIX_VQA_RENDER_TIMEOUT_SECONDS` (default 900) and records the render as a harness error, so a run never sits silent with
+an empty bundle.
+
+Debug only (each records a harness error, so the run can never be submitted): `HELIX_VQA_RENDITION_ONLY=<variant id>`
+renders just that rendition; `HELIX_VQA_ENGINE_RUNTIME=<version>` serves another humanoid-character runtime version
+(e.g. `0.3.169`) to reproduce an engine-era defect; `HELIX_VQA_ENGINE_BUNDLE=<path>` serves a LOCAL humanoid-character build
+(`systems/humanoid-character/dist/index.js`) in its place, the pre-release proof of an engine change on the real page; `HELIX_VQA_OWN_AVATAR=1` seats this account's own avatar instead of the platform default (vehicle occupants are
+the platform default avatar from `GET /universal-items/avatar/default` by default, so a car's verdict does not depend on what
+the submitter wears); `HELIX_VQA_EQUIPPED_AVATAR=<json>` seats a stated composition (to bisect an avatar defect); `HELIX_VQA_DEBUG_PARK_AT_WALL=1` ends the drive parked nose-on against
+the scenery ahead instead of back at the start (the F40 round-1 end state, to prove the exterior cameras stay clear on their
+own); `HELIX_VQA_DEBUG_ROUTES=<json>` serves local files for matching URLs
+(`[{ "match", "file", "type" }]`, a candidate GLB in place of the pinned one); `HELIX_VQA_DUMP_GEOMETRY=1` writes the wheel and occupant pulls
+(`occupant-<seat>.json`, and `rendition.<id>/` for the other renditions) that the calibration fixtures are cut from
+(`scripts/vqa-penetration-fixtures.mjs`).
+
+The backend then runs a **vision critic** (Claude, Opus 5.5) over the frames with a per-category checklist; every
+check must pass. The verdict **fails closed**: a harness error, an unmeasured required assert, a critic refusal,
+an unanswered check or `cannot_judge` is never a pass.
+
+### Proving an assert: fixtures in the real runtime
+
+`HELIX_VQA_FIXTURE_MODEL=<sha256 hex>=<file.glb>` answers every request for that content hash with a local file, so a deliberately
+broken copy of a good avatar is drawn by the real runtime through the real route (e.g. Base Male `7a93cdb1…` with its calves'
+rest roll turned 120 deg). Such a run always carries a harness error (`fixture substitution active`), so its verdict is `error`,
+and `--submit` refuses it: it proves what an assert catches and can never pass anything.
+
+## A vehicle: every check it must pass
+
+This is the whole list the backend judges a vehicle run on (`helix-backend-api`
+`src/continuum/visual-qa/visual-qa.checklists.ts` and `visual-qa.verdict.ts`). A run PASSES only if the harness reported
+no error, every REQUIRED assert is present with severity `block` and passed, no other `block` assert failed, and the
+vision critic ran and answered `pass` to every one of its checks. `warn` asserts never block.
+
+**Required measured asserts** (missing = fail):
+
+| Assert | Passes when |
+|---|---|
+| `vehicle.wheels.at_hubs` | each drawn wheel centre is on its physics hub, one drawn wheel per physics wheel, no two on one hub |
+| `vehicle.wheels.arch_clearance` | no body surface inside a tyre (> 10 mm), tyre top clear of the arch, body >= 5 cm above the contact plane |
+| `vehicle.wheels.spin_with_speed` | coasting, each drawn wheel turns distance / ITS OWN rolling radius (ratio 0.8-1.25), sampled over >= 1 s and >= 3 rad |
+| `vehicle.steering.wheel_rotates` | at full lock the front wheels yaw >= 10 deg (within 4 deg of the physics steer) and the steering wheel >= 30 deg |
+| `vehicle.articulation.reaches_limits` | every declared panel opens to its hinge limit (5 deg) and closes again (2 deg), attached nodes rigid |
+| `vehicle.lamps.each_function_lights` | every lamp function lights in its state (emissive read per state on the meshes the lamp rows resolve to); each indicator blinks and, per side and on hazards, reaches the front and rear quarter of the car. Emitted only when the package has lamp rows |
+| `vehicle.seats.addressable` | every declared seat is in the runtime's seat evidence and the driver seat boards |
+| `frame.non_empty` | no frame is flat (luma stdev < 6, or mean < 4 / > 251) |
+| `scene.no_nan_or_invisible` | no NaN or zero-scale mesh, something visible, < 50 % invisible materials, >= 12 drawn triangles |
+| `render.textured` | not every material is untextured default white/light grey |
+| `scale.sane_for_category` | largest drawn dimension 1.2-30 m |
+| `vehicle.occupants.penetration` | on an occupant run (every current harness): no occupant surface through the cabin (> 8 mm over >= 4 cm², or > 25 mm over >= 1.5 cm²) |
+
+`vehicle.wheels.at_hubs`, `.arch_clearance`, `.articulation.reaches_limits`, `.occupants.penetration`,
+`scene.no_nan_or_invisible`, `render.textured` and `scale.sane_for_category` are required again on EVERY other declared
+rendition (above).
+
+**Blocking whenever present** (the harness always records them on an occupant run): `vehicle.occupants.engine_current`
+(engine >= 0.3.169), `.boarded`, `.head_clearance` (crown >= 10 mm under the lining), `.hips_on_seat` (<= 120 mm over the
+cushion, <= 20 mm through the base), `.feet_on_floor` (sole -50..+300 mm of the floor or pedal), `.hands_on_wheel`
+(driver, <= 70 mm), `.torso_angle`, `.knees_up`, `.head_in_wings` (posture; see above). Warn only: `vehicle.wheels.radius_matches_physics` (drawn tyre within 3 cm of the radius that wheel
+rolls on), `vehicle.occupants.hips_sink_depth`, `vehicle.occupants.near_contact`, `render.flat_shaded`.
+
+**The vision critic** (every check must be `pass`; `cannot_judge` fails): `item.matches_title`, `frame.nonempty` (the
+item is clearly visible; no frame shows only the environment), `render.textured`, `render.intact`, `scale.plausible`,
+`vehicle.wheels.seated`, `vehicle.wheels.count`, `vehicle.ride_height`, `vehicle.symmetry`, `vehicle.cabin`,
+`vehicle.articulation`, `vehicle.steering`, `vehicle.motion`, and on a run with occupant frames
+`vehicle.occupant.head_clearance`, `vehicle.occupant.seat_contact`, `vehicle.occupant.no_clipping` (only counted when two
+failing votes name the same seat, body part and cabin part) and `vehicle.occupant.hands_on_wheel`.
+
+### A local PASS is not a gate result
+
+Only `--submit` (and a hosted run, `--hosted`) runs the vision critic and records a verdict. A local run without
+`--submit` measures every assert above and prints PASS when they pass, but **no critic has looked at a frame**, so a local
+PASS says nothing about the critic's checks (F40 round 1: five local PASSes, then the hosted critic failed
+`frame.nonempty` on every one). `--local-critic` runs the critic once locally (no votes); it is a dry run, never a
+verdict. The listing gate reads only the server's recorded run.
+
+### When the gate blocks a car that is right
+
+The harness is software and can be wrong. If a check fails on something the car does not actually do (a frame of a wall,
+a measurement of a part that is not there, a camera inside scenery), the creator **reports it** (the run id, the frame or
+assert, why it is the harness) and **never changes the car to get past it**: accuracy to the real vehicle wins over a gate
+artefact. F40 round 1 raised a correct 1.124 m body by 36 mm to lift an occupant camera over a test-grounds wall; the
+camera was the bug, the car was not, and the raise was itself a defect. A harness fix is then followed by a re-queue of
+the same version (`helix item visual-qa <id> --hosted --retry`).
+
+### The drive and the exterior cameras stay clear of the test grounds
+
+The test grounds are small and walled (about 29 m between the north and south walls). The drive
+(`vehicle.wheels.spin_with_speed`) therefore plans against the grounds' own scenery: before it moves it measures the clear
+distance from each bumper along the car's heading to the first scenery box (effects that write no depth do not count;
+`facts.drive.trace[phase=start].clearAheadM/clearBehindM` and the box names), backs up at most 14 m and never within 1.5 m
+of what is behind, stops with the foot brake (the pedal against the motion, as a player does, plus the handbrake),
+releases the throttle early enough to settle, coast and still stop 1.5 m short of what is ahead (`releasedFor: room`),
+lifts the throttle whenever a driven wheel slips more than 25 % (the driver's own traction control: a wheel released
+spinning keeps pushing the car on), samples the coast once every wheel rolls within 6 % of road speed or 0.5 s after
+the release (`slip-settled`), takes the chase frame during the coast, ends the 1.3 s sample early and brakes if the car would otherwise pass
+that margin (`stoppedForRoom`, said in the assert), keeps only the free part of the coast (`impactAtS` if the car met
+something), and finally drives back to where it started, closed loop on position, at most 14 s (`facts.drive.end`:
+`returned`, `endAlongM`, `endFromStartM`, the clearance there). The occupant phase then has the space the car spawned in.
+
+Every exterior occupant frame (`side`, `front34`, `door_open`, `cutaway`, `head_roof`, `hips`, `feet`) is taken with its
+near plane pushed to just short of the car and its occupant (the LIVE drawn bounds, so an open door counts), so anything
+between the lens and the car is clipped and no part of the car is; any scenery box still crossing a sight line to the
+car is hidden for that frame only and restored. `facts.occupants.seats[].frames.<id>` records the near plane and the
+scenery hidden. This is generic: a camera pinned in the body frame is clear for any ride height and any length (before
+the fix, the `front34` camera of any car whose occupant camera sat below the grounds' 1.25 m north wall framed concrete).
+
+Each wheel's spin and drawn radius are judged against the radius THAT wheel rolls on: its axle's tyre on the v2 land
+solver (`simulation.land.tyreByAxle[min(axle, n-1)].radius`), else its contact's. A staggered car (F40: 245 front
+0.3139 m, 335 rear 0.3332 m) is measured as staggered; one chassis-wide `wheelRadius` is never used for it.
+
+### The car still drives with its sound on (`vehicle.drive.responds_with_audio`)
+
+R34 1.0.9 went live with an audio block missing `engineGainDb`, `exhaustGainDb`, `muffling` and `min`/`maxLoadMix`; with an
+add-on fitted the missing gain became NaN, `AudioParam.setValueAtTime(NaN)` threw inside the World's frame loop and the
+car froze in Try Now, while hosted visual QA passed it. The drive now holds full throttle as the seated driver with the
+World's AudioContext running and FAILS when, under throttle: the speed stays at ~0 (peak < 0.5 m/s and < 25 cm travelled),
+the vehicle state stops changing for 0.8 s (frozen), any non-finite number appears in `controller.getState()` or the
+entity's telemetry, any non-finite value is written to an `AudioParam` (`browser.ts` `installHooks` records every
+AudioContext and every non-finite write, then passes the write through unchanged), or the page throws. A drive without a
+running AudioContext, or with `no-audio-host`, is a harness error, never a pass. `facts.driveAlive` holds the samples'
+summary, the AudioContexts, the AudioParam write count and the composed `sound` rows (add-ons' audio deltas). A vehicle
+run requires the assert; an add-on preview (`helix vehicle preview --addon`) drives too, with the add-ons fitted, since
+an add-on's audio delta is what triggered the freeze. Debug proofs (never submissions): `HELIX_VQA_FAULT_AUDIO_NAN=1`
+makes every audio write carry NaN from the throttle on; `HELIX_VQA_ENGINE_CORE=<version>` serves an exact engine-core
+in place of the promoted one where a World loads it.
+
+### Bundle size and the frame cap
+
+The gauntlet renders a fixed set of views per seat, so a bigger car makes more frames (the 4-seat Subaru: 81). The
+backend's cap is the inspection set at the largest realistic car (helix-backend-api `visual-qa.frame-budget.ts`: 9 seats,
+6 wheels, 8 panels, 3 rendition passes, 4 add-ons and the night set = 218). `--submit` checks the count before uploading
+(a clear refusal, never a raw 422) and, when the frames are over the 21 MB base64 budget inside the route's 25 MB body,
+re-encodes every frame a little smaller (JPEG quality, then long edge) rather than dropping any (`submitBudget.ts`).
+
+### A vehicle version that draws bytes it does not seal
+
+The engine draws `mesh.visual.tiers[tier].renditionId` → that rendition's `artifactRef`, not the manifest's
+`vehicle.model.web.*` variant. Subaru 1.0.22 sealed its lamp-fixed GLB as `target-balanced` while its root still drew the
+1.0.21 GLB for `target-balanced` and `target-desktop-high`, so `--package-version 1.0.22` (correctly) drew the old car. The
+vehicle route now fails fast, before rendering, when the sealed root or the `--vehicle-package` names a rendition whose
+digest contradicts the Version's variant of the same id (`vehicle/renditionManifest.ts`); `helix continuum
+publish-package` refuses to seal such a root, and the backend refuses it on the candidate trial and the version move.
+
+## The gate
+
+`--submit` posts the bundle to `POST /api/v1/universal-items/:id/visual-qa`. The backend validates that the
+bundle names the item's exact package version (package id, version and manifest CID), recomputes the verdict,
+stores frames and a contact sheet, and records the run against that version. Public Marketplace/Vault
+listings, active Marketplace/World distributions, and moving a public item to a new version are refused with
+`VISUAL_QA_REQUIRED` until that version has a passing run. A new version always needs a new run. Admins can
+record an audited override, but only on top of a recorded harness run of that exact version whose measurements all passed (the
+override can overrule the vision critic, never a missing or failed measurement or a harness error), and **never for an avatar**:
+a whole avatar is held (not visible to anyone but its creator) until a real run passes. See the backend's
+`docs/architecture/visual-qa-gate.md` §"Override".
+
+## Requirements
+
+- Nothing to install by hand: the harness renders on a **Chrome for Testing build matching current stable**, resolved
+  from Google's [last-known-good endpoint](https://googlechromelabs.github.io/chrome-for-testing/last-known-good-versions-with-downloads.json)
+  and downloaded on first use into its own cache (`~/Library/Caches/helix/vqa-chrome` on macOS, `~/.cache/helix/vqa-chrome`
+  on Linux, `%LOCALAPPDATA%\helix\vqa-chrome` for Windows renders; `HELIX_VQA_CHROME_CACHE` moves it). The pin is
+  re-resolved after 14 days; `node dist/visualQa/pinnedChrome.js --refresh` (or `--windows --refresh` from WSL) does it
+  now. Never Playwright's bundled Chromium (a pre-stable build: chromium-1243 = 153.0.8010.12 cannot compile what three
+  r185 emits for every lit material) and never your own Chrome or profile. `HELIX_VQA_CHROME` / `--chrome` still
+  override, and the bundle says so. Headless always, throwaway profile, a GPU when present.
+- **WebGPU self-test.** Before any render, every browser compiles a control shader and the `v.xy.x` swizzle repro through
+  module + render-pipeline creation. A build whose compiler fails the repro is refused with a harness error naming it
+  (`broken WebGPU shader compiler in <build>; use a Chrome-for-Testing build matching stable`); so is a browser with no
+  WebGPU adapter. The hosted worker runs the same check before it claims a job. No `--enable-unsafe-webgpu` on macOS or
+  Windows: stable ships WebGPU on there, and the flag changes what the compiler accepts (it hid that very bug).
+- Every bundle records `harness.browser` = `{ name, version, executablePath, channel, userAgent, webgpu }` — the full
+  four-part version (the UA string reduces it to `153.0.0.0`) and where the build came from (`pinned-cft`,
+  `env-override`, `explicit`, `remote-cdp`). The contact sheet header shows it.
+- Vehicles, avatars and the customiser need a signed-in account: pass a Playwright storage state with
+  `--storage-state` or `HELIX_VQA_STORAGE_STATE`.
+- `--local-critic` needs `ANTHROPIC_API_KEY` (or `OPENROUTER_API_KEY`).
+
+Outputs land in `./visual-qa/<item>-<timestamp>/`: every frame, `bundle.json`, `contact-sheet.jpg`, and with
+`--submit`, `server-verdict.json`. Exit code 0 = pass, 1 = fail, 2 = harness error.
+
+## Hosted rendering
+
+A publisher does not need Chrome, a GPU or a QA login: the platform renders the item on a dedicated GPU runner.
+
+```
+helix item visual-qa <item-id> --hosted            # queue a render of the current version and wait (exit 0 pass, 1 fail, 2 error)
+helix item visual-qa <item-id> --hosted --no-wait  # queue it and return
+helix item visual-qa <item-id> --hosted --retry    # re-queue after a failed/errored hosted run of this version
+helix item visual-qa <item-id> --status            # read-only: hosted job state, contact sheet URL, pass/fail of the current version
+```
+
+A refused listing (`VISUAL_QA_REQUIRED`), a deferred Marketplace publish and the Dreamer verification all queue a
+hosted run for you and name it (`hostedRun: { jobId, status }`); `--status` follows it. Jobs are per
+`(item, Package Version, manifest)`; a new version needs a new run. States: `queued` → `rendering` →
+`passed` | `failed` (a run was recorded) | `error` (the runner could not produce a judged run after its attempts).
+
+### The runner
+
+`helix item visual-qa --hosted-worker` is the runner side: it signs in as the platform's visual-QA bot account
+(`HELIX_VQA_BOT_EMAIL`, `HELIX_VQA_BOT_PASSWORD`; a user account with claim/heartbeat/fail rights and read access, nothing
+else), then loops claim → render with the same harness as the local command → submit against the job's lease. A
+heartbeat extends the lease while it renders; a render with harness errors is reported with `/fail` (the job is
+retried until its attempts run out), never submitted as a verdict. Each render has a hard 900 s watchdog.
+Flags: `--max-jobs`, `--max-minutes`, `--idle-exit-minutes` (keep polling an empty queue; default exit at once),
+`--poll-seconds`, `--render-timeout`, `--worker`.
+
+It runs as `.github/workflows/visual-qa-hosted.yml` on a dedicated self-hosted runner, `vrpc-vqa`
+(labels `self-hosted, vrpc, vqa-gpu`, a systemd service on the VRPC box), so a long render never blocks CI on the
+other runners (CI targets `helix-ci`). The schedule fires every 5 minutes, a `repository_dispatch` of type
+`visual-qa-job` or a manual dispatch starts one on demand, and a single-slot concurrency group keeps one worker alive.
+The worker polls an empty queue for ~9 minutes, so a queued job starts within seconds.
+
+### Rendering through Windows Chrome (the real GPU)
+
+Inside WSL the only Chrome is Linux's and renders on SwiftShader (CPU). With `HELIX_VQA_WINDOWS_CHROME=1` the
+harness starts a **Windows** Chrome for Testing (the pinned current-stable build under `%LOCALAPPDATA%\helix\vqa-chrome`,
+installed from WSL on first use; the workflow refreshes it each run) through WSL interop: headless,
+throwaway profile, `--remote-debugging-port=0`, D3D11 ANGLE, `--force_high_performance_gpu`, WebGPU on, then
+`connectOverCDP` (mirrored networking shares 127.0.0.1). `bundle.harness.renderer` records the adapter actually in
+use (`webgpu:nvidia/lovelace`, `ANGLE (NVIDIA GeForce RTX 4080 …)`), never one inferred from flags. The wrapper records the
+Windows pid it started and only ever kills that tree (`taskkill /T /F /PID`); a pid file lets a later run reap a
+launch whose owner died, after checking the pid still carries our profile directory. `HELIX_VQA_CDP_URL` instead
+attaches to an already-running headless Chromium; `HELIX_VQA_WIN_CHROME` names a specific `chrome.exe`.