@hypersoniclabs/helix-mcp 0.2.4 → 0.2.12

package/docs/character-world.md

@@ -12,6 +12,25 @@ lock side-on movement to one axis — see §8a).
 > For a bare scene with no character (a spinning object, a data viz, a menu), use the **scene**
 > recipe instead: `get_started({ kind: "scene" })`.
 
+> ## SCAFFOLD FIRST — DO NOT HAND-WRITE THESE FILES
+>
+> **Call `scaffold_world` and run the `helix init` command it returns.** It writes all nine files —
+> `package.json`, `vite.config.ts`, `tsconfig.json`, `index.html`, `.gitignore`, `public/helix.json`,
+> `src/helix.runtime.ts`, `src/loading.ts`, and a **runnable `src/main.ts`** — already correct and already
+> building. Existing files are skipped by default, so it is safe to run inside an existing project.
+>
+> **Everything below is EXPLANATION, not source to copy.** The snippets show what each generated file
+> means and how to change it. An agent that types them out instead of scaffolding reproduces the exact
+> failure this recipe exists to prevent: the last time one did, it got four API calls wrong against the
+> installed `.d.ts` (`loadCharacterAssets` takes the asset base **positionally**; `RapierBody.create` is a
+> static factory with a private constructor; `Character.create` takes `{model, camera, domElement, body,
+> input}`; the world needs a floor collider) and shipped a world that built, validated, and rendered
+> nothing. **The scaffold is the source of truth. Read the installed `.d.ts` before any call you are
+> unsure of — never this prose.**
+>
+> Then: `npm install` → `install_world_packages` → `npm run build` → `validate_world` →
+> **`helix verify-subpath dist`** → `publish_world` (§9).
+
 ## 0. Discover what's published FIRST — don't assume
 
 The catalog grows. Before you design anything, **fetch the latest** so you reuse what already exists
@@ -29,27 +48,37 @@ shooting → `gun-control`) before writing any custom behavior.
 
 ## 1. Project layout
 
+`helix init` writes every file marked ✎ below. `helix install` fills in the rest.
+
 ```
 my-world/
-├── package.json
-├── vite.config.ts
-├── tsconfig.json
-├── index.html
+├── package.json               ✎
+├── vite.config.ts             ✎
+├── tsconfig.json              ✎
+├── index.html                 ✎
+├── .gitignore                 ✎  node_modules/, dist/, public/helix_modules/
 ├── helix.lock.json            ← written by `helix install`; commit it
 ├── public/
-│   ├── helix.json             ← the v0.2 manifest (pins); lands at dist/ root on build
+│   ├── helix.json             ✎  the v0.2 manifest (pins); lands at dist/ root on build
 │   └── helix_modules/         ← written by `helix install` (code only); gitignored
 └── src/
-    ├── main.ts
-    ├── loading.ts              ← the loading screen (count-based progress bar); restyle/extend freely (§8b)
-    └── helix.runtime.ts        ← written by `helix install`; committed (do not hand-edit)
+    ├── main.ts                ✎  a RUNNABLE starter — edit it, don't replace it
+    ├── loading.ts             ✎  the loading screen (count-based progress bar); restyle/extend freely (§8b)
+    └── helix.runtime.ts       ✎  stub, then overwritten by `helix install`; committed (do not hand-edit)
 ```
 
 ## 2. package.json
 
 `three` is a **devDependency**: it is external at runtime (the platform hosts the single shared
 instance), but Vite needs it at build time to bundle the GLTFLoader/KTX2Loader addons + for types.
-`@dimforge/rapier3d-compat` (the physics engine) bundles into the world.
+`@dimforge/rapier3d-compat` (the physics engine) works the same way — a devDependency for types and
+`helix dev`, import-mapped to the platform-hosted instance at runtime. It never bundles.
+
+**Keep the three devDependency on the platform's line — `0.185.1` today.** The core comes from the import
+map, but the `three/examples/jsm/...` addons bundle out of THIS copy and `helix dev` runs it, so a stale
+devDep ships mismatched halves and makes local dev disagree with the published build. The system pin is what
+decides the hosted version (`humanoid-character` `^0.3` → three 0.185.1); new publishes targeting an older
+three are refused — `read_doc({ name: "upgrades" })` has the migration for an existing world.
 
 ```json
 {
@@ -57,8 +86,8 @@ instance), but Vite needs it at build time to bundle the GLTFLoader/KTX2Loader a
   "private": true,
   "type": "module",
   "scripts": { "dev": "vite", "build": "vite build", "preview": "vite preview", "typecheck": "tsc --noEmit" },
-  "dependencies": { "@dimforge/rapier3d-compat": "^0.14.0", "@hypersoniclabs/helix-sdk": "{{SDK_DEP_SPEC}}" },
-  "devDependencies": { "@types/three": "^0.172.0", "three": "^0.172.0", "typescript": "~5.7.3", "vite": "^6.0.0" }
+  "dependencies": { "@hypersoniclabs/helix-sdk": "{{SDK_DEP_SPEC}}" },
+  "devDependencies": { "@dimforge/rapier3d-compat": "^0.14.0", "@types/three": "^0.185.1", "three": "^0.185.1", "typescript": "~5.7.3", "vite": "^6.0.0" }
 }
 ```
 
@@ -67,25 +96,48 @@ The system itself is NOT an npm dependency — `helix install` materializes it u
 
 ## 3. vite.config.ts
 
-Externalize **only the bare `three`** so the world, the embedded system, and every ability share the
-one hosted instance (two copies of three break `instanceof` and silently corrupt rendering).
+**`base: './'` is REQUIRED and is the single most important line in this file.** A published world is
+served from a nested path (`…/instant-worlds/<id>/<build>/`), never the origin root, so root-absolute
+asset URLs 404 in production while working perfectly in local preview. A relative base is what makes one
+build work in both places.
+
+Externalize the **bare `three`** so the world, the embedded system, and every ability share the
+one hosted instance (two copies of three break `instanceof` and silently corrupt rendering), and
+`@dimforge/rapier3d-compat` so the ~2 MB physics engine loads once from the platform, not per world.
 `three/examples/jsm/...` is NOT externalized — Vite bundles the addons from your `node_modules` three.
 
+The scaffold writes the two aliases a starter world uses. Add the others **only when you import them** —
+the `engine-core` SUBPATH entries must always precede any root `@helix/engine-core` entry, because rollup
+substitutes by `'/'`-boundary prefix in object order and a root alias listed first mangles the subpath
+import into an ENOENT.
+
 ```ts
 import { defineConfig } from 'vite';
 import { fileURLToPath } from 'node:url';
 
 export default defineConfig({
-  base: './',
+  base: './',            // ← REQUIRED; `helix verify-subpath dist` proves it
   resolve: {
     alias: {
+      // Written by the scaffold:
+      '@helix/engine-core/inspect': fileURLToPath(new URL('./public/helix_modules/engine-core/inspect/index.js', import.meta.url)),
       '@helix/humanoid-character': fileURLToPath(new URL('./public/helix_modules/humanoid-character/index.js', import.meta.url)),
+      // Add when you use them (screenshots — read_doc "screenshots"; subpaths BEFORE the root entry):
+      // '@helix/engine-core/screenshot': fileURLToPath(new URL('./public/helix_modules/engine-core/screenshot/index.js', import.meta.url)),
+      // '@helix/engine-core/world-camera': fileURLToPath(new URL('./public/helix_modules/engine-core/world-camera/index.js', import.meta.url)),
+      // '@helix/engine-core': fileURLToPath(new URL('./public/helix_modules/engine-core/index.js', import.meta.url)),
     },
   },
-  build: { target: 'es2022', rollupOptions: { external: ['three'] } },
+  build: {
+    target: 'es2022',
+    rollupOptions: { external: (id) => id === 'three' || id === '@dimforge/rapier3d-compat' || id.startsWith('@helix/') },
+  },
 });
 ```
 
+Keep that `rollupOptions` line **byte-identical and on one line** — `helix install` matches it literally, and any
+reformatting (an equivalent multi-line form included) makes it classify the world `legacy-bundled` and publish fail.
+
 ## 4. tsconfig.json
 
 Point the type path at the embedded system's declarations (installed alongside the code).
@@ -95,7 +147,12 @@ Point the type path at the embedded system's declarations (installed alongside t
   "compilerOptions": {
     "target": "ES2022", "module": "ESNext", "moduleResolution": "bundler",
     "lib": ["ES2022", "DOM"], "strict": true, "noEmit": true, "skipLibCheck": true,
-    "paths": { "@helix/humanoid-character": ["./public/helix_modules/humanoid-character/index.d.ts"] }
+    "paths": {
+      "@helix/humanoid-character": ["./public/helix_modules/humanoid-character/index.d.ts"],
+      "@helix/engine-core": ["./public/helix_modules/engine-core/index.d.ts"],
+      "@helix/engine-core/world-camera": ["./public/helix_modules/engine-core/world-camera/index.d.ts"],
+      "@helix/engine-core/screenshot": ["./public/helix_modules/engine-core/screenshot/index.d.ts"]
+    }
   },
   "include": ["src"]
 }
@@ -104,9 +161,9 @@ Point the type path at the embedded system's declarations (installed alongside t
 ## 5. index.html
 
 Ship the `helix:three` import-map markers exactly as below — `helix install` rewrites the import map
-to the hosted three URL. Leave the placeholder; do not fill it by hand. The `#loading` overlay is the
-loading screen: it paints on HTML parse (before any JS), and `src/loading.ts` drives its progress bar
-(§8b). Keep the markers and the overlay; restyle the overlay freely.
+to the hosted three and Rapier URLs. Leave the placeholder; do not fill it by hand. The `#loading`
+overlay is the loading screen: it paints on HTML parse (before any JS), and `src/loading.ts` drives its
+progress bar (§8b). Keep the markers and the overlay; restyle the overlay freely.
 
 ```html
 <!doctype html>
@@ -138,6 +195,9 @@ loading screen: it paints on HTML parse (before any JS), and `src/loading.ts` dr
       #loading-text { margin-top: 12px; color: #9aa7b4; }
       @keyframes helix-marquee { 0% { transform: translateX(-110%); } 100% { transform: translateX(370%); } }
       @keyframes helix-pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.4; } }
+      /* HUD — the player shell overlays its chrome bar across the TOP-CENTER (~top 56px: Exit / Save / helixOS).
+         Keep your HUD OUT of that strip: anchored top-left here; use a corner or the bottom, never top-center. */
+      #hud { position: fixed; top: 12px; left: 12px; z-index: 10; max-width: min(340px, 40vw); font: 13px/1.5 system-ui, sans-serif; color: #e6edf5; }
     </style>
   </head>
   <body>
@@ -158,9 +218,9 @@ loading screen: it paints on HTML parse (before any JS), and `src/loading.ts` dr
 ## 6. public/helix.json — pin what you discovered in step 0
 
 `helixVersion: "0.2"` opts into systems/abilities. Pin the system + every ability you want as
-`slug -> semver range` (use `^0.2` unless `get_package_manifest` shows a newer line — and keep the system and
-ability pins on the SAME minor: an ability's bundle pins the system minor it was built for, so mixing e.g.
-system `^0.2` with an ability `^0.1` makes the ability refuse to load at runtime). `helix install`
+`slug -> semver range` (the system is `^0.3` unless `get_package_manifest` shows a newer line — and pin each
+ability at the version `get_package_manifest` reports for that system line: an ability's bundle declares the
+system range it was built against and refuses to load at runtime outside it). `helix install`
 resolves each range to an exact version and bakes it into `helix.lock.json`.
 
 ```json
@@ -173,11 +233,16 @@ resolves each range to an exact version and bakes it into `helix.lock.json`.
   "permissions": ["auth.profile"],
   "supportsMobile": true,
   "contentRating": "everyone",
-  "systems": { "humanoid-character": "^0.2" },
-  "abilities": { "fly": "^0.2", "swim": "^0.2" }
+  "systems": { "humanoid-character": "^0.3", "engine-core": "^0.1.2" },
+  "abilities": { "fly": "^0.3", "swim": "^0.3" }
 }
 ```
 
+**Keep the `engine-core` pin the scaffold wrote.** It is what makes `inspect_world`, `world_metrics`
+and `capture_world_screenshot` work on this world. A world published without it cannot be measured or
+screenshotted later without a pin edit + reinstall + rebuild + republish — `check_for_updates` reports
+its absence as `missing-recommended` precisely because retrofitting it is the expensive path.
+
 ## 7. src/helix.runtime.ts — stub (helix install overwrites it)
 
 ```ts
@@ -188,57 +253,131 @@ export const TRANSCODER_PATH = '/runtime/basis/';
 export const SYSTEM_ASSET_BASE = '';
 ```
 
+These are **placeholders**. `helix install` replaces all four with absolute platform-CDN URLs
+(`https://…/runtime/three/<v>/three.module.js`, `https://…/runtime/basis/three-<v>/`, the system's asset
+base). They are the one place root-absolute-looking values are fine before install, because none of them
+survives it — never hand-edit this file, and never hardcode a `/runtime/...` path of your own.
+
 ## 8. src/main.ts — the flow
 
+**`helix init` already wrote a working `src/main.ts`.** Read that file, then edit it. What follows is
+the same flow annotated, so you understand what you are changing — it is not a file to type out.
+
 `loadCharacterAssets` streams the body/face LOD + locomotion clips from the CDN (never bundled);
 `Character.create` drives the chassis; `LocomotionAbility` is the built-in movement; everything you
 pinned loads via `loadInstalledAbilities`. With the `avatar` option, a logged-in player's equipped
 **universal avatar** becomes their body automatically — skeleton-gated and fault-tolerant (guests, no
 avatar, an unconverted rig, or any load failure all fall back to the default body; the world never
-breaks). Delete the `avatar:` line to opt the world out (see `character.universalAvatar.enabled`).
+breaks). **To opt a single-player world out, delete the `avatar:` line** — that is the whole opt-out, because in the bare-`Character` recipe the world resolves the avatar itself. Do *not* reach for `character.universalAvatar.enabled: false` for this: that is the native feature set's TOP SWITCH and it also turns off emotes, the emote wheel, x-ray, pointing, sitting and the avatar camera (§8g).
+
+**Changing the player's avatar: there is ONE function — `mp.changeAvatar(...)`** *(humanoid-character ≥ 0.3.90 / 0.2.69)*.
+```ts
+const outcome = await mp.changeAvatar(inventoryItemId); // an avatar instance the player OWNS
+await mp.changeAvatar(null);                             // take it off → the platform default body
+// outcome: 'changed' | 'unchanged' | 'refused' | 'unreachable' | 'unsupported'
+```
+It is the same call the quick-slot ring and a Home's equip station make. It puts the avatar placeholder up at
+once, persists the change through the platform (which checks ownership and keeps the player to one body),
+swaps the body when the new avatar loads, and hints the room so **every other player sees it** — and it
+survives a reload. An equip station in your world is just a prompt whose action calls this. **Do not** build
+your own: no `Helix.avatar.updateLoadout` to change the body, no loading a GLB onto the local character, no
+hand-rolled placeholder or room message. There is deliberately no local-only variant — other players see only
+what the platform says the player wears. Details: `helix-web-engine-new/docs/architecture/avatar-change.md`.
+
+**Mid-room avatar swaps are transparent — do not write swap code.** When the player equips a different
+avatar mid-session, the platform rebuilds the body behind a stable façade: `mp.local` keeps its identity
+(it is a `LocalCharacter` seat, not the raw `Character`), attachments re-bind to the same handles, ability
+installs replay, and runtime config — ammo included — carries over. Everything wired through
+`mp.attach(...)` / `mp.local` (events, services, combat systems) keeps working untouched. Do NOT rebuild
+on `Helix.avatar.onAvatarChanged` — it fires pre-swap and debounced, the wrong hook. The one legitimate
+use of a swap hook is body-INTERNAL wiring: something you `model.add(...)`ed onto the old body, a held IK
+reach handle, a listener registered on a per-body object. For those, subscribe ONCE to
+`mp.onLocalSwap(cb)`: `{ phase: 'started', url }` fires while the old body is still live (checkpoint
+window), `{ phase: 'ended', url, recovered, props }` after the rebuild — `props` lists each surviving
+attachment as `{ handle, previousObject }` (same handle, re-bound; `previousObject` is your key for
+re-pointing any world-side caches). It rides the seat, so one subscription hears every swap.
 
 ```ts
 import * as THREE from 'three';
 import { Helix } from '@hypersoniclabs/helix-sdk';
-import { Character, loadCharacterAssets, loadInstalledAbilities, LocomotionAbility, RapierBody } from '@helix/humanoid-character';
+import { Character, InputService, loadCharacterAssets, loadInstalledAbilities, LocomotionAbility, RapierBody } from '@helix/humanoid-character';
+import { world } from '@helix/engine-core/inspect';
 import { SYSTEM_ASSET_BASE, TRANSCODER_PATH } from './helix.runtime';
 import { createLoadingScreen } from './loading';   // loading screen — hooks DefaultLoadingManager (§8b)
 
+const SPAWN = { x: 0, y: 0.2, z: 0 };
+
 const scene = new THREE.Scene();
+scene.background = new THREE.Color(0x14161a);            // an unset background renders as a void
 const camera = new THREE.PerspectiveCamera(60, innerWidth / innerHeight, 0.05, 200);
 const renderer = new THREE.WebGLRenderer({ antialias: true });
 renderer.setSize(innerWidth, innerHeight);
+renderer.outputColorSpace = THREE.SRGBColorSpace;
 document.body.appendChild(renderer.domElement);
+
+// LIGHTING: the two hand-placed lights below are the CLASSIC starter — what the scaffold still writes,
+// and what a world that keeps its own visual style (a deliberate opt-out) ships. The PLATFORM DEFAULT is
+// the visual runtime: hand it the canvas, declare how the world is lit in public/helix.visuals.json, and
+// delete both lights AND the renderer block above — createVisualRuntime owns the renderer, sky, sun,
+// tone mapping and grade, and bounded static worlds then ship BAKED lighting at publish. The conversion
+// is five mechanical steps: read_doc({ name: "lighting-world" }). If you keep the classic path:
+// ambient fill ALONE leaves a dark character on a dark background — add a key light, or the world
+// renders as a near-empty frame and `verify-subpath` fails it on blank-render (correctly).
+// Either lane, making the world LOOK good — asset checks, materials, textures, composition —
+// is read_doc({ name: "world-look" }).
 scene.add(new THREE.HemisphereLight(0xbfd4ff, 0x40382a, 0.9));
+const sun = new THREE.DirectionalLight(0xffffff, 2.2);
+sun.position.set(6, 12, 4);
+scene.add(sun);
 
 // Mount the loading screen before any loader runs — it hooks THREE.DefaultLoadingManager so every asset
 // load below (character, abilities, any extra GLB you add) counts on the bar automatically. See §8b.
 const loading = createLoadingScreen();
 
 // Init FIRST — the body is bind-once, so the player's avatar must resolve before Character.create.
-await Helix.init();
-const equipped = await Helix.avatar.getEquipped();  // null for guests / no avatar / any failure
+// Fail-soft: off-platform (a plain `npm run preview`) there is no session and the world must still run.
+await Helix.init().catch(() => undefined);
+const equipped = await Helix.avatar.getEquipped().catch(() => null);  // null for guests / no avatar / any failure
 
+// NOTE the POSITIONAL signature: the asset base is the FIRST argument, not a field on an options
+// object. Passing an object here fails deep inside the loader with "t.replace is not a function".
 const { model, clips } = await loadCharacterAssets(SYSTEM_ASSET_BASE, {
   renderer, transcoderPath: TRANSCODER_PATH,
   avatar: equipped?.glbUrl ? { url: equipped.glbUrl, skeleton: equipped.skeleton } : undefined,
 });
 scene.add(model);
 
-// Assets are in (bar ~90%); the rest is un-metered (Rapier WASM compile, character setup) → show the
-// indeterminate "Starting…" tail so the bar never looks frozen, then dismiss on the first frame.
-loading.working('Starting…');
+// RapierBody.create is a static async factory — the constructor is PRIVATE, `new RapierBody()` will not
+// compile. The world needs a floor collider or the character falls forever through an empty scene.
+const body = await RapierBody.create({ position: SPAWN });
+body.addStaticCuboid({ x: 24, y: 0.5, z: 24 }, { x: 0, y: -0.5, z: 0 }); // floor COLLIDER, top at y=0
 
-const body = await RapierBody.create({ position: { x: 0, y: 0.2, z: 0 } });
-body.addStaticCuboid({ x: 24, y: 0.5, z: 24 }, { x: 0, y: -0.5, z: 0 }); // floor
+// …and a floor you can SEE. The collider above is invisible: physics geometry and visual geometry are
+// separate, and a world with only the collider renders as a character floating in a void.
+const floor = new THREE.Mesh(
+  new THREE.BoxGeometry(48, 1, 48),
+  new THREE.MeshStandardMaterial({ color: 0x2a3138, roughness: 0.95 }),
+);
+floor.position.y = -0.5;
+scene.add(floor);
+
+// ONE world-owned InputService, injected into the character — register every game key on this router,
+// never a raw addEventListener (§8c).
+const input = new InputService();
 
 const character = await Character.create({
-  model, camera, domElement: renderer.domElement, body,
+  model, camera, domElement: renderer.domElement, body, input,
   // FIRST-PERSON: set the initial camera mode. Omit for the third-person default.
-  config: { character: { camera: { mode: 'first-person' } } },
+  config: { character: { spawn: SPAWN, camera: { mode: 'first-person' } } },
 });
 character.abilities.register(new LocomotionAbility(clips));
-await loadInstalledAbilities('/helix_modules', character); // fly, swim, … from helix.json
+
+// Everything `helix install` resolved (fly, swim, … from helix.json). RESOLVE THE MODULES BASE AGAINST
+// document.baseURI. A published world is served from a nested path (…/instant-worlds/<id>/<build>/), so a
+// root-absolute '/helix_modules' 404s in production and THROWS — the world renders nothing but an error
+// bar, while local preview from the origin root looks perfect. `helix verify-subpath dist` proves it.
+const modulesBase = new URL('helix_modules/', document.baseURI).href;
+await loadInstalledAbilities(modulesBase, character);
 
 // First-person mouse-look needs pointer lock — request it from a click (browser gesture rule).
 renderer.domElement.addEventListener('click', () => character.services.input.requestLook());
@@ -248,10 +387,22 @@ let firstFrame = true;
 renderer.setAnimationLoop(() => {
   character.update(Math.min(clock.getDelta(), 0.1));
   renderer.render(scene, camera);
-  if (firstFrame) { firstFrame = false; loading.dismiss(); } // world on screen → fade the overlay
+  if (firstFrame) { firstFrame = false; loading.done(); } // world on screen → fade the overlay
 });
 ```
 
+**One uncaught throw inside this callback stops rendering FOREVER** — three.js schedules the next frame
+only after the callback returns, so a single bad per-frame read ships as "the world froze" (audio keeps
+playing, the last frame stays on screen). Guard reads of state that may not exist yet
+(`blackboard.has(key)` before `get`, optional chaining on services) — the loop is the one place a throw
+has no second chance.
+
+```ts
+// Measurement hook for inspect_world / world_metrics verification (§10). A no-op during normal play —
+// it only activates under ?helixInspect=1. Call it at the END of boot, once the scene is built.
+world.ready({ scene, body, spawn: SPAWN });
+```
+
 ## 8a. Configure the character — read the knobs from the manifest, NEVER guess
 
 **This is the step agents get wrong.** Speed, camera, spawn, slope, jump-feel — almost everything a
@@ -275,8 +426,10 @@ const character = await Character.create({
   model, camera, domElement: renderer.domElement, body,
   config: {
     character: {
-      spawn:  { x: 4, z: -2, facingDeg: 90 },     // where the player starts + which way they look (0 = +Z)
-      camera: { mode: 'third-person', initialYaw: 90, lookSensitivity: 1.4, fov: 70 },
+      // 0° = +Z; 90° = +X. With initialYaw omitted/null, 0.2.21+ derives a stable
+      // behind-character camera (spawn facing - 180°), including after respawn.
+      spawn:  { x: 4, z: -2, facingDeg: 90 },
+      camera: { mode: 'third-person', lookSensitivity: 1.4, fov: 70 },
     },
     locomotion: { runSpeed: 7, coyoteTimeMs: 120 },
     // ability namespaces too, once pinned & installed:  fly: { maxSpeed: 14 }
@@ -284,6 +437,13 @@ const character = await Character.create({
 });
 ```
 
+> **Spawn facing is durable in `humanoid-character` 0.2.21+.** `character.spawn.facingDeg` is body
+> yaw (`0 = +Z`, `90 = +X`). Leave `character.camera.initialYaw` omitted or `null` and the engine
+> derives the matching behind-character boom yaw as `facingDeg - 180`; locomotion no longer erases
+> that authored facing, and `character.respawn()` restores both body and camera. Set a numeric
+> `initialYaw` only when you intentionally want a camera seed independent of spawn facing. Camera
+> yaw is boom azimuth: `0` places the camera on `+Z` looking toward `-Z`.
+
 **2. Runtime — `character.config.set('ns.key', value)`.** Read live every tick; the change applies
 immediately. This is how you do timed buffs, difficulty changes, "look at the boss", etc.
 
@@ -330,6 +490,27 @@ character.camera?.addTrauma(0.6);                      // camera shake for a hit
 speed }` — `impactSpeed` is vertical, use it for fall damage), `fell`, `respawned`, `jumped`,
 `stateEntered`. The full list + payloads are in `capabilities.events`.
 
+### Where the character is FACING — read the model, never the camera
+
+The camera is NOT the character. In third person it orbits the character freely (and in top-down it is
+fixed), so any "is the player facing X" check built from the camera's position or direction is wrong in
+every framing except first-person. The character's authoritative forward is its model yaw (0 = +Z):
+
+```ts
+const fwd = new THREE.Vector3(0, 0, 1).applyQuaternion(character.model.quaternion);
+const to = obj.position.clone().sub(character.model.position);
+to.y = 0; fwd.y = 0; // horizontal test — height must not affect a facing gate
+const facingIt = to.lengthSq() > 1e-8 &&
+  to.normalize().dot(fwd.normalize()) >= Math.cos(THREE.MathUtils.degToRad(50)); // ±50° prompt window
+```
+
+This is the same math the runtime uses internally. **For IK reaches, do not hand-roll it at all** —
+`ik.reach(hand, target, { engage: {} })` already gates on the reaching arm's workspace arc (midline to
+~135° on that arm's side, ≥ 0.2.17) plus distance, and auto-releases when the player turns or walks
+away; a one-off `press` gates itself the same way with `press: { when: {} }` (≥ 0.2.16 — a failed gate
+fires nothing and the handle reports `fired: false`). See the character-animation doc's Runtime IK
+section. Reserve the snippet above for your own prompts and UI ("press E to interact").
+
 ### Lock the controls to the genre — disable what doesn't fit (don't ship every control everywhere)
 
 Every `allow*` gate **defaults to `true`** (all controls enabled). So you must **opt OUT** of the ones
@@ -342,10 +523,10 @@ the manifest `config`):
 
 | gate | removes |
 |---|---|
-| `character.camera.allowModeToggle` | first/third-person switch (the **T** action) |
+| `character.camera.allowModeToggle` | the first↔third-person legs of the camera cycle (the **T** action cycles FP → TP → shoulder-R → shoulder-L) |
 | `character.camera.allowRotate` | orbit / mouse-look (fixed camera angle) |
 | `character.camera.allowZoom` | scroll-wheel zoom |
-| `character.camera.allowShoulderSwap` | over-shoulder side swap (the **V** action) |
+| `character.camera.allowShoulderSwap` | the over-shoulder legs of the camera cycle (**V** is the melee action, not the camera) |
 | `locomotion.allowJump` / `allowCrouch` / `allowSprint` | the jump / crouch / sprint actions |
 
 Genre presets (set these at create time, then add the rest of your tuning):
@@ -366,6 +547,8 @@ config: { locomotion: { allowJump: false } }
 
 You can also flip these live (e.g. disable controls during a cutscene): `character.config.set('character.camera.allowModeToggle', false)`.
 
+The two camera legs are also **native features** with their own refusal ids — `character.native.disabled: ['camera-first-person']` makes the world third-person only and sets `mode` + `allowModeToggle` for you, so every surface that reads the camera policy agrees. Refusing BOTH throws at create. See §8g for the full native set and the rest of the veto.
+
 ### First-person vs third-person (a slice of the camera config)
 
 - Initial mode: `config.character.camera.mode` = `'first-person'` or `'third-person'` (default).
@@ -376,86 +559,25 @@ You can also flip these live (e.g. disable controls during a cutscene): `charact
 ## 8b. Loading screen — `src/loading.ts` (count-based progress, extensible)
 
 The `#loading` overlay in `index.html` paints on HTML parse (before any JS downloads → no flash).
-`src/loading.ts` then hooks **`THREE.DefaultLoadingManager`** — the SAME instance the engine's
-GLTFLoader/KTX2Loader use (one shared three via the import map) — so the character, every ability, and
-ANY extra three load you add count on the bar automatically, with no extra code. The bar climbs as
-assets stream, shows an indeterminate **"Starting…"** tail for the un-metered window (Rapier WASM
-compile, character setup), then fades on the first rendered frame. Ship this file verbatim; restyle freely.
+`src/loading.ts` — **written by `helix init`; open that file, do not retype it** — hooks
+**`THREE.DefaultLoadingManager`**, the SAME instance the engine's GLTFLoader/KTX2Loader use (one shared
+three via the import map). So the character, every ability, and ANY extra three load you add count on the
+bar automatically, with no extra code. Restyle it freely.
 
-```ts
-import * as THREE from 'three';
+The scaffolded module exports exactly this surface — **match it; there is no `dismiss`, `working`,
+`label` or `fail`**:
 
-// Loading screen for this world. It hooks THREE.DefaultLoadingManager — the SAME instance the engine's
-// GLTFLoader/KTX2Loader use (one shared three via the import map) — so the character, every ability, and
-// ANY extra three load you add (a world GLB, a TextureLoader, …) count on the bar automatically, with no
-// extra code. For a NON-three asset (audio, a raw fetch), wrap it in loading.task(). The overlay markup
-// + CSS live in index.html so it paints before this module downloads (no flash). Restyle/extend freely.
-
-const BAND_MAX = 0.9;   // the measured climb fills [0, 0.9]; the last tenth is the post-load tail + first frame
-const QUEUE_MIN = 5;    // go indeterminate→measured only once a real wave is queued (total-loaded ≥ this), so the
-                        // brief body+face 2/2 blip can't fill the bar then snap backward when the 38 clips enqueue
-
-export interface LoadingScreen {
-  /** Fold a NON-three async asset into the bar (counts like one item). Call before the work; handle.done() when it resolves. */
-  task(): { done(): void };
-  /** Set the status line under the bar. */
-  label(text: string): void;
-  /** Enter the indeterminate "Starting…" tail — covers the un-metered window (Rapier WASM compile, character setup). */
-  working(text?: string): void;
+```ts
+export type LoadingScreen = {
+  /** Register an extra async unit of work so it counts on the bar. Returns its completion callback. */
+  task: (label?: string) => () => void;
   /** One-shot fade + remove. Call AFTER the first renderer.render(), never on manager.onLoad (it fires early). */
-  dismiss(): void;
+  done: () => void;
   /** Switch to the error state (red bar + message). */
-  fail(message: string): void;
-}
+  error: (message: string) => void;
+};
 
-export function createLoadingScreen(): LoadingScreen {
-  const root = document.getElementById('loading');
-  const bar = document.getElementById('bar');
-  const textEl = document.getElementById('loading-text');
-  const noop = (): void => {};
-  if (!root || !bar || !textEl) return { task: () => ({ done: noop }), label: noop, working: noop, dismiss: noop, fail: noop };
-
-  const mgr = THREE.DefaultLoadingManager;
-  let determinate = false; // latched once a real queue appears; never reverts (no marquee↔fill flicker)
-  let tail = false;        // working() latched — ignore further manager ticks; the pulse owns the bar
-  let shown = 0;           // last rendered fraction — monotonic, never decreases
-  let extra = 0;           // open task() handles, folded into the denominator
-
-  const render = (loaded: number, total: number): void => {
-    if (tail) return;
-    const t = total + extra;
-    if (!determinate && t - loaded >= QUEUE_MIN) { determinate = true; root.classList.add('determinate'); }
-    if (!determinate) return;
-    const frac = Math.min(loaded / Math.max(t, 1), 1) * BAND_MAX;
-    shown = Math.max(shown, frac);
-    bar.style.width = `${(shown * 100).toFixed(1)}%`;
-  };
-
-  mgr.onStart = (_url, loaded, total) => render(loaded, total);
-  mgr.onProgress = (url, loaded, total) => {
-    render(loaded, total);
-    if (tail) return;
-    if (/anims\/.*\.glb(\?|$)/.test(url)) textEl.textContent = `Loading animations… ${loaded}/${total}`;
-    else if (/\.ktx2(\?|$)/.test(url) || /basis_transcoder/.test(url)) textEl.textContent = 'Decoding textures…';
-  };
-  // No mgr.onLoad: it fires on the transient body/face 2/2 before the clips queue. Dismissal is the world's
-  // job — a one-shot after the first rendered frame (see main.ts).
-
-  return {
-    task() { extra += 1; let closed = false; return { done() { if (!closed) { closed = true; extra -= 1; } } }; },
-    label(text) { textEl.textContent = text; },
-    working(text = 'Starting…') { tail = true; root.classList.add('determinate', 'working'); textEl.textContent = text; },
-    dismiss() {
-      if (root.classList.contains('done')) return;
-      root.classList.remove('working');
-      root.classList.add('determinate');
-      bar.style.width = '100%';
-      root.classList.add('done');
-      setTimeout(() => root.remove(), 450);
-    },
-    fail(message) { root.classList.add('error'); textEl.textContent = `ERROR: ${message}`; },
-  };
-}
+export function createLoadingScreen(): LoadingScreen;
 ```
 
 **Add your own assets to the bar.** An extra three load is counted automatically — just load it on the
@@ -463,25 +585,508 @@ default manager (`new GLTFLoader().loadAsync(...)`). For a NON-three asset (audi
 in `loading.task()`:
 
 ```ts
-loading.label('Loading music…');
-const music = loading.task();                 // counts like one item; the bar waits for it
-const audio = new Audio(new URL('theme.mp3', document.baseURI).href);
-audio.addEventListener('canplaythrough', () => music.done(), { once: true });
+const musicDone = loading.task('Loading music…');   // counts like one item; the bar waits for it
+const audio = new Audio(new URL('theme.mp3', document.baseURI).href);  // relative to baseURI — never '/theme.mp3'
+audio.addEventListener('canplaythrough', () => musicDone(), { once: true });
 audio.load();
 ```
 
-**Errors.** To surface a load failure on the overlay instead of a frozen bar, guard the awaited setup and
-call `loading.fail(...)`:
+**Errors.** The scaffold already wraps boot in a `main().catch(...)` that calls `loading.error(...)` and
+prints the message into the HUD. Keep that guard — a throw with no guard is a frozen bar and a blank
+screen, which is indistinguishable from a hang.
+
+**Refinements worth adding if the bar feels rough** (the scaffold keeps the file small on purpose):
+clamp the measured climb to ~90% so the un-metered tail (Rapier WASM compile, character setup) still has
+somewhere to go; only switch marquee→measured once at least ~5 items are queued, so the brief body+face
+`2/2` blip cannot fill the bar and then snap backwards when the clips enqueue; and make the rendered
+fraction monotonic so it never decreases.
+
+
+## 8c. Input — the standard action set, the world-owned router, menu contexts
+
+The character system ships ONE canonical input vocabulary — the **standard action set**. Movement,
+look, jump, camera come pre-bound (keyboard/mouse + gamepad + touch-ready metadata); your world adds
+its own actions on the **same router** instead of raw `addEventListener`.
+
+> **Rule:** the authoritative action list is in `get_package_manifest("humanoid-character")` →
+> **`capabilities.actions`** (per action: id, kind, context, default bindings, touch hint), the
+> semantic gamepad map in **`capabilities.controller`** (`faceDown`/`triggerR`/`dpadUp`… →
+> standard-mapping indices), and the platform-reserved keys in **`capabilities.reservedKeys`**.
+> Read them before wiring input. Do not invent keys; never bind a reserved key.
+
+**Two different "actions" — don't conflate them.** An **input action** (this section) is a named,
+rebindable device binding on the input router (`jump`, `interact`). A multiplayer **declared action**
+(`room.sendAction('plant')` — multiplayer-logic §14) is a client→server intent the room's rules
+interpret. They compose — read the input action, send the declared action:
+
+```ts
+if (input.wasPressed('interact')) mp.room?.sendAction('plant');
+```
+
+### The world-owned router *(humanoid-character ≥ 0.2.7)*
+
+Create ONE `InputService` in the world, own the DOM attach, register the world-domain standard
+actions you need, and inject it — world UI and character gameplay then share one router and one
+context stack:
+
+```ts
+import { Character, InputService, registerStandardActions } from '@helix/humanoid-character';
+
+const input = new InputService();
+input.attach(window as never);                                                    // keyboard + mouse buttons
+input.attachPointer(renderer.domElement as never, undefined, { dragLook: true }); // locked look, drag/touch look, wheel
+registerStandardActions(input, { only: ['pause', 'inventory', 'confirm', 'cancel', 'uiNavigate'] });
+
+const character = await Character.create({ model, camera, domElement: renderer.domElement, input, body, config });
+// Multiplayer: CharacterMultiplayer.create({ ..., input }) — the same option, forwarded to the inner character.
+```
+
+Omit `input` and the character self-creates a private router — fine for a world with no menus and no
+custom keys. Rebind ability-registered actions via config: `config: { bindings: { jump: { keys: ['KeyJ'] } } }`
+(locomotion's move/sprint/walk/crouch/jump + any installed ability's actions; chassis-registered ones —
+look, cameraMode, zoom, modifier, the equip cycle — take `input.rebind(id, …)` after create instead).
+
+### World input — bind the standard ids first; mint custom actions last
+
+The standard set already ships world-ready ids — `interact` (E / `faceLeft` / touch button),
+`primary`, `secondary` (aim), `ability1..9` + the `equipPrev`/`equipNext` pad cycle, `melee`,
+`emote`, plus the menu set. **Prefer them: you never pick a key at all** — the id carries its
+keyboard + gamepad + touch bindings, and player rebinding later comes for free:
+
+```ts
+registerStandardActions(input, { only: ['interact', 'pause', 'confirm', 'cancel'] });
+
+renderer.setAnimationLoop(() => {
+  const dt = Math.min(clock.getDelta(), 0.1);
+  character.update(dt);                                  // pumps the router — query actions AFTER this
+  if (input.wasPressed('interact')) mp.room?.sendAction('plant');   // E / face-left / touch — one line
+});
+```
+
+Mint a **namespaced custom action** only for something genuinely outside the standard set. The router
+throws on a duplicate action *id* but does NOT police two actions sharing a physical source in the
+same context — collisions are yours to avoid, and the collision rule is about what is **REGISTERED in
+this world**, not what appears in the registry:
+
+- **Never a reserved key** (`capabilities.reservedKeys`: Escape, KeyN, backtick).
+- **Never a source a REGISTERED same-context action uses.** Always live in a character world: the
+  locomotion/camera set — Space/WASD/Shift/KeyC/Alt/Ctrl/KeyT + faceDown/faceRight/stickL/dpadLeft,
+  both sticks, and dpadRight (the modifier). Plus whatever this world opts into (`interact`'s
+  KeyE/faceLeft, the menu set) and whatever its abilities bind (gun-control's mouse buttons +
+  triggers + KeyR/faceUp, the equip cycle's Digit1-9/brackets/bumpers when `equip.slots` is on).
+- **Registry ids this world never registers are FREE REAL ESTATE — reuse their bindings.** A card
+  game has no gunplay: `reload`'s KeyR/faceUp, `primary`/`secondary`'s triggers, `melee`'s
+  KeyV/stickR, `emote`'s KeyG/dpadDown are all unclaimed there, and a plain button always beats a
+  chord or an exotic key. Genre decides: reuse when the owning action clearly can never appear in
+  this world; leave it alone when it plausibly might (a shooter keeps `reload`'s slots free even
+  before guns ship). Note the reuse in a comment at the registration site.
+- **No equip slots ⇒ the bumpers and Digit1-9 are freed** — the bumpers are the natural pad home for
+  a world's own cycling/selection verbs (radio channels, tabs, targets), digits for direct select.
+- **To reuse an ALWAYS-ON action's source, disable the owner first** via its genre gate
+  (`locomotion.allowCrouch: false` frees KeyC/faceRight for a world with no crouching — the same
+  match-controls-to-genre pass you already do). Never bind over a live action.
+
+**Gamepad placement — in order of preference:**
+
+```ts
+input.registerAction('world.mark',  { kind: 'button', keys: ['KeyM'], pad: 'faceLeft' }, 'world');                 // 1: genre-freed (no interact here)
+input.registerAction('world.honk',  { kind: 'button', keys: ['KeyH'], pad: 'dpadUp' }, 'world');                   // 2: the always-free fallback
+input.registerAction('world.taunt', { kind: 'button', keys: ['KeyG'], withModifier: { pad: 'faceUp' } }, 'world'); // 3: a modifier chord (KeyN is reserved — voice PTT)
+input.registerAction('world.debugStats', { kind: 'toggle', keys: ['F9'] }, 'world');                               // 4: keyboard-only (debug)
+```
+
+1. **A genre-freed plain button** (the rules above) — the DEFAULT choice: put the verb where hands
+   expect it (triggers for firing-shaped verbs, bumpers for cycling/selection, face buttons for
+   frequent verbs). **Paired/linked verbs share ONE symmetric group** — bumperL/bumperR,
+   dpadUp/dpadDown, faceLeft/faceRight, or triggerL/triggerR — never split a pair across groups
+   (red-team on the d-pad with blue-team on a face button is disorienting).
+2. **`pad: 'dpadUp'`** — always free in every world, but a FALLBACK, not a first pick: a lone odd
+   verb with no better home, or half of a dpadUp/dpadDown pair when `emote`'s slot is genre-freed.
+3. **A `withModifier` chord** — `dpadRight` is the platform's held `modifier`. While it is down,
+   `withModifier` bindings resolve and their sources go quiet for their plain owners, opening a
+   second layer. Resolution is additive per device — plain bindings stay live while the chord is
+   held (KeyH above still fires). **RESERVED chords — never claim:** `modifier`+right stick (the
+   platform camera zoom), `modifier`+bumperR (the standard `voicePTT` — push-to-talk on pad,
+   auto-registered when the world attaches voice), and `modifier`+bumperL (reserved for future
+   platform voice controls). Ergonomics: holding the modifier occupies the d-pad thumb, so chord
+   only occasional actions that tolerate a movement pause (a zoom does; a dodge would not).
+4. **Keyboard-only (omit `pad`)** — for testing/debug conveniences ONLY (stat overlays, free-cam,
+   cheats). A pad or touch player can never reach it, so anything gameplay-relevant belongs on a
+   plain button, a chord, or an indirect route (contextual `interact`, the equip cycle, a menu
+   entry) — the standard set itself works this way: `ability1..9` are keyboard digits, pad players
+   cycle with `equipPrev`/`equipNext`.
+
+Don't stack chords or mint exotic keys while obvious freed buttons sit idle — reusing the standard
+layout's real estate keeps pad controls where players' hands expect them.
+
+**Installable abilities bind the standard ids too**: an `ability.json` action may declare a bare
+standard character id — `{ "id": "primary" }`, no `kind`, no `defaultBinding` (the registry owns
+both) — instead of minting a private `<ability>.<name>`. gun-control reads `primary`/`secondary`/
+`reload` this way. Custom ability actions stay namespaced.
+
+**Slot cycling comes built in** — enable the chassis tracker instead of writing one:
+`config: { character: { equip: { slots: 4 } } }` registers `ability1..4` + `equipPrev`/`equipNext`,
+tracks the active slot (wraparound + direct select), publishes blackboard `equipSlot`, and emits
+`equipSlotChanged { slot, previous }` — your world does the actual equipping off that state.
+
+A raw `addEventListener('keydown', …)` bypasses the context stack (your key still fires inside
+menus), can collide with platform keys, gets no gamepad/touch support — and can never be rebound.
+Rebinding is per-ACTION, not per-key: `bindings.<id>` config overrides the defaults of
+ability-registered actions (see above), and a settings
+menu rebinds live via `input.rebind(id, { keys: [...] })` — enumerate what's bound with
+`input.actions()` (or `describeActions(input)` for registry labels/touch hints). Keyboard names are W3C
+`KeyboardEvent.code` (`KeyE`, `Space`, `ShiftLeft` — physical/positional, layout-independent);
+gamepad bindings use the semantic names from `capabilities.controller` (`pad: 'faceUp'`,
+`stick: 'leftStick'`) — never raw indices. Kinds: `button` | `toggle` | `vec2` | `delta`; queries:
+`isDown` / `wasPressed` / `wasReleased` / `isToggled` / `vec2` / `delta`.
+
+### Player-facing control text — `format()` tokens, never key names *(humanoid-character ≥ 0.2.7)*
+
+Never write a physical control name ("WASD", "press E", "RT") into HUD/help text — it is wrong the
+moment the player picks up a pad or rebinds. The router knows the truth; render through it and
+re-render each frame — that IS the live device-swap mechanism (the text flips the frame the player
+touches the other device):
+
+```ts
+hudEl.textContent = input.format('Drive with {move} · {interact} to grab');
+```
+
+Bare `{actionId}` tokens expand via `input.hint(id)` — the CURRENT resolved binding of that action
+on the device whose activity was seen last (`input.activeDevice()`), so rebinds and config
+overrides display correctly for free. Keyboard renders short key text ("E", "WASD", "Left click"),
+gamepad renders Xbox-style names ("X", "RT", "Left stick"; chords as "D-pad Right + RB"). An action
+unbound on the shown device renders its OTHER device's binding, and only falls back to its `label`
+when no device has one. Pass a device to pin one (`input.hint('interact', 'gamepad')`); unknown ids
+throw; a doubled opening brace escapes a literal one (token ids are word chars, dots, hyphens).
+Give CUSTOM actions a `label` at registration so fallback text reads like a verb, not an id:
 
 ```ts
-try {
-  // … loadCharacterAssets … Character.create … loadInstalledAbilities …
-} catch (err) {
-  loading.fail(err instanceof Error ? err.message : String(err));
-  throw err;
+// faceRight reuses crouch's slot — this world sets locomotion.allowCrouch:false (gate-disable first!)
+input.registerAction('world.discard', { kind: 'button', keys: ['KeyH'], pad: 'faceRight', label: 'Discard' }, 'world');
+```
+
+Worlds without their own router reach the character's: `mp.local.services.input.format(...)`.
+README/prose may name default keys, stated as defaults ("E by default").
+
+### Menus that actually pause the game — the context stack
+
+Every action carries a `context` (default `'gameplay'`); the router resolves only the top of its
+context stack. Push `'menu'` and every gameplay action reads inert (movement decelerates to a stop,
+look and zoom freeze) while `confirm`/`cancel`/`uiNavigate` go live — the character never learns a
+menu is open, its actions simply stop resolving:
+
+```ts
+if (input.wasPressed('pause') || input.wasPressed('inventory')) { input.pushContext('menu'); showMenu(); }
+if (input.wasPressed('confirm') || input.wasPressed('cancel'))  { input.popContext('menu'); hideMenu(); }
+```
+
+No edge leaks across the transition (the press that opened the menu never re-fires as `confirm`) and
+held keys resume cleanly on pop.
+
+**Context pushes free the mouse — that is their job.** A push that suspends `look` releases pointer lock
+the way Esc would (a menu needs the cursor), and the engine can only re-acquire on a real user click. So
+reach for `pushContext` ONLY for UI that wants the cursor. For gameplay states that suppress input while
+the cursor stays captured — knockout, stun, ragdoll, a cutscene — do NOT push a context: locomotion is
+already gated while `dead`/`ragdolled`/emote-locked, and a camera freeze is
+`config.set('character.camera.allowRotate', false)` (restore on exit), which never touches the lock.
+
+### Reserved keys — never bind these
+
+From `capabilities.reservedKeys`: **Escape** (the SDK's phone/tablet overlay; pointer-lock exit also
+rides it), **KeyN** (the voice push-to-talk default — repoint voice via the SDK's `pttKey` option
+rather than binding over it), **backtick** (the debug-overlay convention). **KeyB is no longer
+reserved** — it is now the `point` standard action's binding, so it is *bound*, not free. The standard
+set already avoids the reserved keys — `pause` is **P**, `cancel` is **Backspace**. Pad players get
+PTT without KeyN: the `voicePTT` standard action (hold modifier + right bumper, `global` context so it
+works under menus) is auto-registered by `mp.attachVoice` and forwarded to the SDK.
+
+### Driving actions without a keyboard (AI / NPCs / tests)
+
+`input.setVirtualButton('jump', true)` / `setVirtualVec2('move', { x, y })` /
+`setVirtualDelta('zoom', d)` write the same actions a player does — abilities and game logic cannot
+tell the difference. Pass `null` to clear.
+
+### Default mobile controls
+
+A current `helix init` character world already mounts `createMobileControls(input, { surface })`
+and calls `mobileControls.update()` before the character tick. The generated, framework-neutral HUD
+uses the same registered action metadata and virtual-input channel described above: left stick,
+open-space drag look, true two-pointer pinch zoom/camera-mode transition, jump, and contextual
+`button`/`hold`/`tap` actions. It activates only for touch capability, respects safe areas plus the
+host-provided top offset, follows the input context stack, and clears captures/virtual state on
+cancel, blur, teardown, or remount.
+
+Customize it through constrained data, not copied DOM:
+
+```ts
+input.registerAction('world.scan', {
+  kind: 'button', context: 'gameplay', label: 'Scan', touch: 'hold', keys: ['KeyF']
+}, 'world');
+
+const mobileControls = createMobileControls(input, {
+  surface: renderer.domElement,
+  actions: [
+    { id: 'world.scan', label: 'Scan', order: 1 },
+    { id: 'cameraMode', placement: 'utility' },
+    { id: 'crouch', visible: false },
+  ],
+  theme: { accent: '#7dd3fc' },
+});
+```
+
+Labels are inserted as plain text; layout and theme are safe tokens. Core move/look/zoom remain on
+unless intentionally disabled with `core`. To replace the default entirely, provide an equivalent
+custom InputService controller and declare `provider: "custom"` in `public/helix.controls.json` while
+preserving the required move/look/zoom/jump capabilities. In both cases, `supportsMobile: true`
+requires touch-only browser proof at portrait and landscape phone sizes.
+
+## 8d. Custom gestures — see the character-animation doc
+
+Worlds can author their own character animations as JSON keyframe poses (no GLB export, no platform
+publish) — a wave, a salute, a world-specific ritual — and they replicate in multiplayer by default.
+
+Most worlds do not need this: locomotion, jumps and the standard emote set already ship with the
+humanoid-character system.
+
+**Scope first:** the pose DSL is for SHORT, SIMPLE, upper-body-led motion — player actions (wave, point,
+sip), held stances (hurt, carrying), one-shot accents (nod, flinch), and additive overlays that ride
+locomotion (a limp, a hunch). It is NOT for dances, fight choreography, acrobatics, or anything where the
+feet must step, plant or leave the ground: a gesture is bone rotations only, with no root motion, no foot
+planting and no weight shift, because the locomotion graph owns the lower body. Those need a
+motion-captured clip.
+
+If you DO need a custom gesture, read the dedicated doc before writing any
+keys — joint-space posing has non-obvious failure modes (rotations chain, so the axis meanings only hold
+near rest) and the doc carries the axis table, the composition rules and the measurement tooling:
+
+```
+read_doc("character-animation")
+```
+
+## 8e. Sitting & lying spots — furniture players can actually use *(humanoid-character ≥ 0.2.36)*
+
+Any world with chairs, benches, couches or beds should register **sit/lie spots** — a social hub without
+them is furniture nobody can use. One call per seat; the prompt ("E — Sit"), the interact press, the seated
+pose, replication to every client and remote occupancy (the prompt walks past a taken chair) are ALL
+platform defaults — the world authors nothing else:
+
+```ts
+const spots = mp.local.sitting.spots;             // (multiplayer facade; solo: character.sitting.spots)
+spots.register({ id: 'couch-left',  seat: { x: -0.4, y: 0.45, z: 2.35 }, facingYawDeg: 180, pose: 'sit' });
+spots.register({ id: 'bed', seat: { x: -3.3, y: 0.35, z: 1.4 }, facingYawDeg: -90, pose: 'lie', label: 'Lie down' });
+// returns an unregister closure; optional: label, exitPoint, clearanceM
+```
+
+**The coordinate contract — get these right and it just works:**
+- `seat` sits **ON the surface** the player sits/lies on: the cushion top, the mattress top — NOT the floor,
+  NOT a point in the air. The engine lifts the hips the anatomical clearance itself (sit ~0.07 m,
+  lie ~0.10 m; `clearanceM` overrides for odd furniture). Place it where a butt (sit) or hips (lie) go —
+  centred on the seating surface, clear of armrests and backrests.
+- `facingYawDeg` = which way the OCCUPANT faces (0 = +Z, positive toward +X). For a chair: outward, away
+  from the backrest. **For a bed: the body lies down BACKWARD, so the head lands OPPOSITE the facing —
+  face AWAY from the pillow end.**
+- **Any seat height works.** Typical surfaces: chair/couch 0.42–0.5 m, bar stool 0.6–0.8 m (the feet
+  simply dangle), bed 0.3–0.5 m. Sub-chair heights (floor cushions ~0.1 m) will plant feet oddly — the
+  shipped sit pose is chair-height; prefer real furniture heights.
+- Two seats on one couch: author one spot per cushion (~0.6–0.8 m apart); occupancy offers the free one.
+- **`seat` goes near the furniture's FRONT face, never at a deep cushion's center.** The seated pose puts
+  the pelvis AT the seat point and drops the knees/shins **~0.25 m in front of it** — any furniture
+  occupying that space clips through the legs. Rule: place the seat point **0.15–0.2 m behind the front
+  face** of the cushion, measured along the facing direction. A chair (~0.5 m deep) can use its center; a
+  couch or bench cushion 0.7 m+ deep CANNOT — bring the point forward (e.g. an 0.8 m-deep cushion with its
+  front face at z=2.0, occupant facing −Z: seat z ≈ 2.2, not the 2.4 center). Depth behind the seat point
+  is free — the body leans back over it.
+- `exitPoint` is optional — standing up defaults to just in front of the seat at the height the player
+  walked in at.
+
+The seated POSE is the player's own carried sit/lie emote, falling back to the DEFAULT BUNDLED WITH THE
+CHARACTER SYSTEM — every player can take a chair or a bed, guests and empty emote sets included; nothing
+needs equipping and no platform config is involved. (The exception: a world that turns EMOTES off turns the
+whole posture lane off with them — the facade's `emotes: false`, `character.emote.enabled: false`, or
+`character.native.disabled: ['emotes']`. Refusing `'sitting'` outright removes the spots, the prompt and the
+seat claim on `interact` (§8g). Do not disable either in a world that authors sitting spots.) Do NOT put furniture colliders where the
+seated body goes — the posture pins the body; a mattress collider only fights it. Tunables:
+`character.sitting.promptRangeM` (1 — HORIZONTAL body→seat-point distance; the seat point is the seat
+CENTER ~0.25 m inside the furniture, so this offers about a stride from the furniture's edge. Height is a
+separate ±1.5 m band, so a mezzanine chair never offers through a floor and a tall stool costs no reach)
+and `.promptSwitchMarginM` (0.35).
+**A world with its OWN interaction UI style should own the sit prompt too**: pass `sitPrompt: false` to the
+facade (kills the built-in pill; the mechanic still takes the seat on `interact`) and render from
+`mp.sitPrompt` / `mp.onSitPrompt((p) => ...)` — `{ kind: 'enter' | 'exit', spotId, label, distance }` or
+null, fired on change, never per frame. That is how sitting joins a world's existing prompt system instead
+of stacking a second pill beside it. Otherwise the prompt pill restyles or
+switches off via the facade's `sitPrompt` option. Paired (two-person) emotes need NO world authoring —
+they are player-carried items; the platform renders the offer and join prompts.
+
+## 8f. Size geometry from `world_metrics` BEFORE you place it
+
+**Call `world_metrics({ projectDir })` the moment you start laying out a world — the first step, ledge,
+gap, ramp, doorway or ceiling — not after publishing.** It reads the traversal envelope out of the
+world's OWN installed character system: player capsule (height / radius / crouch), **step height** (what
+auto-steps versus what is a wall), max walkable slope, movement speeds, and the derived jump envelope
+(air time, max flat-ground gap at run and at sprint) plus corridor and ceiling clearances.
+
+This is the cheapest bug in the catalogue to avoid and one of the most expensive to find: a world shipped
+with a **0.42 m step against a 0.35 m limit** looked completely fine in every screenshot, passed
+validation, and published — the objective was simply unreachable, and nothing flagged it because a
+screenshot cannot show that a player physically cannot get somewhere. Numbers can.
+
+The values are the system DEFAULTS the world starts from; if you override them in `config.locomotion` /
+`config.character.body`, your own values win — read the manifest (§8a) and size against those instead.
+
+Then, once geometry is placed, verify it with `inspect_world` (§10) — `world_metrics` tells you what will
+fit, `inspect_world` tells you what you actually built.
+
+## 8f. Health, death & ragdoll — the survival chassis *(humanoid-character ≥ 0.2.25)*
+
+Any world where the character can DIE (combat, hazards, survival) turns on the health mirror:
+
+```ts
+character: { health: { enabled: true, maxHealth: 100 } }
+```
+
+That registers blackboard `health` / `deathDir` (plus `dead`, which always exists), the events
+`healthChanged{value,previous}` / `died` / `revived` / `respawned`, and `character.setHealth(v)`. **Two
+authority modes:** single-player worlds drive `setHealth` themselves (a hazard zone, a fall); multiplayer
+worlds NEVER write health client-side — declare `playerVars.health` and let server rules mutate it (the
+facade mirrors the room's number onto the chassis, local and replicas alike — see the `shooter-range`
+template). On death the chassis gates input, plays the directional stagger (`deathDir`), and hands the body
+to the **ragdoll**:
+
+```ts
+character: { ragdoll: { enabled: true, blendSeconds: 0.35, launchSpeed: 2.5, deathCamera: 'third-person' } }
+```
+
+Physics takes the body at the death instant (the stagger cross-fades over `blendSeconds`; `0` = hard
+switch); `deathCamera` pulls a first-person victim out to third person to watch the fall (`'none'` opts
+out). All defaults are tuned — most worlds change nothing.
+
+**Ragdoll is also a world MECHANIC**, independent of death: `character.ragdoll.enter({ launch, speedMps })`
+drops the body limp (knockouts, launch pads, physics comedy), `exit()` stands it back up, `.active` reads
+the state, and locomotion input is gated while limp. It replicates automatically — remotes see the body go
+limp and late joiners converge — and any world can read another player's state via
+`room.state.players[id].ragdolled`. `enter()` refuses while dead (death owns that body).
+
+For guns and the full combat loop on top of this, read `read_doc({ name: "shooter-worlds" })`.
+
+## 8g. Native avatar features — what every world gets, and the one way to refuse it *(humanoid-character ≥ 0.2.54)*
+
+**These are ON in every character world, with no world code, no option and no republish.** They are
+constructed by `Character` itself, so they do not depend on which constructor you called: a world built
+on the bare `Character` + `LocomotionAbility` gets exactly what a `CharacterMultiplayer.create` world
+gets.
+
+| id | what it is | its affordance |
+|---|---|---|
+| `emotes` | the player's carried emotes: tap-to-replay, the wheel's slots, and the sit/lie posture lane | `emote` — **KeyG** / dpad-down, touch **Emote** |
+| `emote-wheel` | the 8-petal radial overlay (hold `emote`, steer, release), including the **Customize** door that opens the platform's emote-slots editor | the overlay only (emotes and tap-replay survive refusing it) |
+| `xray` | hold-to-scan whatever is under the reticle — player, placed item or vehicle — and its detail card | `xray` — **KeyZ** (pad: modifier + left bumper), touch hold |
+| `pointing` | hold to point the right index finger along the aim | `point` — **KeyB**, touch hold |
+| `sitting` | sit/lie at authored spots (§8e), the proximity prompt, and the seat claim on `interact` | the *claim* on `interact` — the key itself stays, because worlds share that id |
+| `avatar-camera` | the Helix OS phone presentation and the embodied avatar camera composed on it | `shutter` — **KeyF**, touch button |
+| `camera-first-person` | the first-person camera leg | the FP leg of the `cameraMode` cycle (**KeyT**) |
+| `camera-third-person` | the third-person camera leg | the TP leg of the `cameraMode` cycle |
+| `universal-avatar` | rendering each player's equipped universal avatar as their body | — (the **top switch**, see below) |
+
+The player's carried emotes arrive on their own: the runtime reads the loadout off the shell's platform
+channel, so a world does **not** have to wire `Helix.emotes` for the wheel to work. When the wheel is
+empty it says *why* — signed out, nothing equipped, outside the HELIX app, or the platform could not be
+reached — rather than showing eight blank petals. The **Customize** door on the wheel appears only once
+the shell has proved it can service the request (so: inside the HELIX app, signed in, on a shell that
+mounts the editor) — it is genuinely absent otherwise rather than painted hopefully, which is the same
+rule as the rest of this set: no affordance without its feature.
+
+### The creator veto — `character.native.disabled`
+
+A world that does not want one of these **names it in a refusal list**, in the config you hand
+`Character.create` / `CharacterMultiplayer.create`:
+
+```ts
+config: {
+  character: {
+    native: { disabled: ['xray', 'pointing'] },   // everything not listed stays ON
+  },
 }
 ```
 
+This is **runtime config, not manifest** — it does not go in `public/helix.json`.
+
+Six things to understand before you use it:
+
+1. **It is a blocklist, and never an allow-list.** The platform runtime resolves fresh at launch, so a
+   world published today runs a *newer* character system tomorrow (see §9 and the delivery contract). A
+   list of things you *want* would freeze every future feature out of every already-published world. A
+   list of **refusals** cannot: a feature nobody has heard of yet is in nobody's list, so it arrives ON.
+   That is deliberate. Refuse the features you do not want by name; do **not** exact-pin the system to
+   stop receiving them — engine systems are ranges, and publish refuses an exact pin.
+2. **`universal-avatar` is the top switch, and it is all-or-nothing.** Refusing it also refuses `emotes`,
+   `emote-wheel`, `xray`, `pointing`, `sitting` and `avatar-camera`, and every key, touch button and
+   prompt that advertised them. Those features are authored against the platform humanoid — its skeleton,
+   its sockets, its posture clips — so they are not portable onto a world's own character rig. **The two
+   camera legs survive it**: a world still needs a camera whatever body it draws. One asymmetry to know:
+   on `CharacterMultiplayer` this id also stops the facade resolving equipped avatars at all, while in the
+   bare-`Character` recipe your own code is what passes `avatar:` to `loadCharacterAssets` (§8) — so there,
+   drop that line too, or you will keep drawing the equipped body while having refused everything that
+   hangs off it.
+3. **A refusal takes the affordance with it.** No key binding, no rebind row, no controller button, no
+   touch pad, no prompt. A world that refuses `xray` must not still show a scan key that does nothing —
+   the runtime enforces that for you, and the refusal stands even against a later
+   `registerStandardActions`.
+4. **Refusing both camera legs throws at create.** `['camera-first-person', 'camera-third-person']` is
+   not a world. Refuse one to make the world single-mode — that also sets `character.camera.mode` and
+   clears `allowModeToggle`, so the camera cycle, the zoom-through-mode switch and the death camera all
+   agree — or neither to keep the cycle.
+5. **An id this runtime does not recognise is kept and warned about once, never fatal.** It is either
+   your typo (the warning names the legal ids) or a feature from a runtime newer than the one that
+   happens to be resolved. A `disabled` that is not a list at all is ignored with its own warning, and
+   nothing is refused — check the console if a refusal did not take.
+6. **The older per-feature switches still work**, and route into this same resolver, so you never have to
+   migrate and never get a precedence puzzle — a feature is off if *either* surface says so:
+   `character.emote.enabled: false` (= `emotes`), `character.emote.wheel: false` (= `emote-wheel`),
+   `character.xray.enabled: false` (= `xray`), `character.universalAvatar.enabled: false`
+   (= `universal-avatar`, **and therefore its whole dependent set** — see 2). On the multiplayer facade,
+   `CharacterMultiplayer.create`'s `emotes: false`, `emoteWheel: false` and `universalAvatars: false`
+   options compile into exactly those config keys.
+
+Not part of the veto: `localControl: false` on `CharacterMultiplayer.create`. That is not a feature
+switch — it declares a passive spectator body the world drives its own camera and input for, and such a
+body is not a native host at all (neither are replicas), so it mounts no native overlays by construction.
+
+**Version — read this before you rely on any of it.** All of §8g needs `@helix/humanoid-character`
+**0.2.54** or newer. A runtime older than that ignores `character.native.disabled` silently and keeps
+whatever it already did: your refusals do not take, and the features listed above are not all there to
+refuse. So do not reason from this section about what a given world actually has — **confirm against the
+resolved system's own config schema** (`get_package_manifest` / `list_systems`): if `character.native`
+appears in its `config`, that runtime provides this surface. That schema is also the authoritative id
+list; the table above is prose about it.
+
+## 8h. NPCs — see the NPC recipe *(humanoid-character ≥ 0.3.13)*
+
+A world can put **characters that are not players** in it — a shopkeeper behind a counter, a quest giver, a
+guard on a post, a zombie that hunts you — on the same chassis this recipe just configured. **An NPC is a
+`Character` whose driver is your behaviour instead of the keyboard**: same config namespaces, same locomotion
+and animation graph, same abilities, same gestures, built headless (no camera, no DOM) with an `AIDriver`
+writing virtual intent onto its own private router, so every ability resolves that intent exactly as it
+resolves yours. `NpcScene` owns the model clone, the router, the body, the nameplate and the teardown; you
+author a `behaviour` callback, and `InteractionSpots` gives any of them a "walk up, press interact" prompt.
+
+**Scope first:** the platform ships the *chassis and the steering* — a seek with whisker obstacle avoidance and
+a stuck commit, optional A* routing over a `NavGrid` rasterized off your own level colliders, two body tiers
+(`stand` runs no physics at all, `physics` gets its own Rapier world mirrored from the player's), a 16-NPC
+budget, and Vault characters as bodies. It does **not** ship attacking, patrolling, aggro, factions or
+dialogue: those are game logic you write in the behaviour. And it does not ship replication — `NpcScene` NPCs
+are **client-local**, which is right for a standing NPC and wrong for a moving one (in a multiplayer world a
+moving NPC belongs to the room, rendered by `humanoidEntities`).
+
+If the world needs an NPC, read the dedicated recipe before writing any of it — the failure modes are ordering
+rules with silent symptoms (read `arrived` before re-seeking or the attack never fires; re-seek only when the
+target moved or the stuck detector is disabled), and the doc carries the worked shop NPC, the hunting one, the
+nav-grid limits with real numbers, the Vault-character flow and the multiplayer handoff:
+
+```
+read_doc("npc-world")
+```
+
 ## 9. Install, build, publish
 
 ```bash
@@ -490,22 +1095,72 @@ npm install
 
 Then resolve the pins: call the **`install_world_packages`** tool with this project directory (or run
 `npx -y {{CLI_PKG}}@latest install` in it) — it downloads the pinned code, writes installed.json + the
-lock, and wires the three import map + `src/helix.runtime.ts`. Re-run it after editing pins; pass
+lock, and wires the runtime import map + `src/helix.runtime.ts`. Re-run it after editing pins; pass
 `update: true` (or `--update`) to re-resolve ranges to newer versions. Then:
 
 ```bash
-npm run build            # vite build (three external; system + addons + rapier bundle)
+npm run build            # creator code/addons bundle; three, rapier and @helix systems stay external
 ```
 
 Then `validate_world` on `dist/` (fix every problem — no `.glb`/`.ktx2` may ship; assets stream from
-the CDN), `whoami` to confirm login, and `publish_world` on `dist/` for the play link.
+the CDN), then the sub-path gate:
+
+```bash
+npx -y {{CLI_PKG}}@latest verify-subpath dist
+```
+
+**Do not skip this, and do not publish without it.** `npm run preview`, `validate_world`,
+`inspect_world` and `capture_world_screenshot` all serve `dist/` from an origin **root**. A published
+world is only ever served from a **nested path**. So every one of those gates passes a bundle whose
+root-absolute URL 404s and throws in production — the world renders a red error bar and nothing else.
+`verify-subpath` serves the same bytes from a nested path and fails on a throw, a 404, or a blank
+render. It is the only local check that sees the difference.
+
+Finally `whoami` to confirm login, and `publish_world` on `dist/` for the play link.
+
+## 10. Verify placement by measurement — see the world-inspect doc
+
+Do not judge object placement from screenshots — distances and depth read off an image are unreliable.
+`inspect_world` on `dist/` returns the scene as data (positions, extents, colliders) and runs placement
+checks: floating/sunk/intersecting geometry, collider-vs-visual mismatches, invisible walls.
+`focusNear: [x, y, z]` checks just the object you placed at that coordinate, and `world_metrics` gives the
+capsule/step/slope/jump numbers for sizing gaps, steps and doorways BEFORE you place geometry. Findings are
+measurements to check against your intent, never orders to change the world. Full workflow:
+
+```
+read_doc("world-inspect")
+```
 
 ## The rules that matter
 
+- **NEVER write a root-absolute URL for anything inside your own bundle.** A published world is served
+  from `…/instant-worlds/<id>/<build>/`, so `'/helix_modules'`, `'/models/x.glb'`, `fetch('/data.json')`
+  and friends resolve against the SITE root, 404, and throw. Always resolve against the document:
+  `new URL('helix_modules/', document.baseURI).href`. Keep `base: './'` in the vite config, and prove it
+  with `helix verify-subpath dist` — local preview serves from the root and cannot show you this bug.
+  (Absolute `https://…` CDN URLs and the platform values `helix install` writes into
+  `src/helix.runtime.ts` are a different thing and are correct.)
 - **One three.** `three` is external everywhere (import map → hosted instance). Never bundle it.
+- **One rapier.** Same for `@dimforge/rapier3d-compat`: external in every build, import map → the hosted
+  instance, never bundled. The npm devDependency exists only for types + `helix dev`.
+- **Platform systems stay external.** Keep the generated `id.startsWith('@helix/')` external rule.
+  Compatible `^`/`~` system ranges receive safe native character, emote, camera and pointing updates on
+  a fresh launch without republishing — **including native features that did not exist when you published**
+  (§8g). Engine systems are ranges: validation and publish **refuse an exact version** (it freezes the World on
+  one build). To get an engine fix, promote it rather than pinning to it. Validation and publish also refuse a
+  custom config that silently bundles those systems.
 - **Assets always stream from the CDN.** Animation clips + textures are never downloaded or shipped
   with the world. The build contains no `.glb`/`.ktx2`. `loadCharacterAssets` fetches them at runtime.
 - **Test with `build` + `preview`, not `dev`.** The dev server rewrites bare imports and hides whether
   the import map is correct; preview serves the real built output the platform runs.
 - **Pins are locked.** A rebuild uses the versions in `helix.lock.json`; `helix install --update`
   advances them. Commit the lock so rebuilds are reproducible.
+- **Keep the top-center clear for platform chrome.** The player shell overlays a bar across the TOP-CENTER of
+  every world (~top 56px: Exit / Save Progress / helixOS / fullscreen — user-hideable, shown by default). Anchor
+  your HUD / on-screen UI to a CORNER (top-left/right) or the BOTTOM; a full-width or centered element goes ≥64px
+  down (the templates' banners sit ~20% down). Never place UI at top-center — it renders behind the chrome.
+- **World keys are router actions, not `addEventListener`.** Register them on the shared `InputService`
+  (§8c), read them with `wasPressed`/`isDown` after `character.update(dt)`, use `pushContext('menu')` for
+  pause/UI, and never bind the reserved keys (Escape, KeyN, backtick — `capabilities.reservedKeys`).
+- **Control names come from the router.** Player-facing text uses `input.format('… {move} …')` tokens
+  re-rendered per frame — never hardcoded key names (§8c); custom actions carry a `label`.