@genex-ai/cli-demo 0.38.0 → 0.40.0

package/templates/skills/genex-threejs-multiplayer/SKILL.md

@@ -34,13 +34,17 @@ example, the shared-object/ball code, rotation, and host usage. Read
 ## Install
 
 ```bash
-npm i @genex-ai/multiplayer@^0.8.0
+npm i @genex-ai/multiplayer@^0.9.0
 ```
 
-> Pin `@^0.8.0` (not a bare `npm i`): `inputs`/`onHostTick`, auto-reconnect, and the `reconnecting`
-> events this skill relies on landed in 0.8. An older resolve would throw `room.onHostTick is not a function` at runtime.
+> Pin `@^0.9.0` (not a bare `npm i`): confirmed object controls, discontinuity snaps, host-tick
+> teardown, and reconnect rebasing landed in 0.9. An older resolve does not have
+> `room.objects.claimConfirmed` or `room.me.snap`.
 
-This skill targets `@genex-ai/multiplayer` **≥ 0.8.0** (`objects`/`host` since 0.4; `matchmake()` since 0.5; presets + `score()`/`finish()` since 0.6; `createPrivate()`/`joinPrivate()` since 0.7; matchmake auto-retry + `retry()` since 0.7.1; auto-reconnect + `inputs`/`onHostTick` since 0.8; soft ownership handoff — claim-on-touch objects glide instead of teleporting — since 0.8.4).
+This skill targets `@genex-ai/multiplayer` **≥ 0.9.0** (`objects`/`host` since 0.4;
+`matchmake()` since 0.5; private lobbies since 0.7; auto-reconnect + `inputs`/`onHostTick`
+since 0.8; soft ownership handoff since 0.8.4; confirmed controls, snap epochs, and host-tick
+lifecycle guarantees since 0.9).
 
 ## Trust model (say it plainly in your game's copy)
 
@@ -189,16 +193,18 @@ const room = await connect<State>({
 });
 ```
 
-**Capacity:** a room holds up to **64 players** (up to 48 of them guests). Above that, the
-relay opens a **second room for the same game** — two parallel worlds, no error. If your
-game needs seated, one-world competition, use the matchmaking presets instead of one big
-`connect()` room.
+**Capacity:** 64 players is the relay's **mechanical seat cap**, not a proven high-motion physics
+envelope. Object-heavy rooms amplify fanout; measure the exact game at 8/16/32/64 before promising a
+supported count. Above the cap the relay opens another room for the same game. If the game needs one
+seated competitive world, use matchmaking rather than one large `connect()` room.
 
 ## Disconnects & reconnection (built in — render it, don't rebuild it)
 
-The SDK auto-reconnects after a network blip or brief signal loss: the relay holds your seat
-for a grace window (~30 s), and on recovery **nothing changed** — same session id, objects
-still yours, host unchanged, and in a match **a blip is not a forfeit**. Your only job is UI:
+The SDK auto-reconnects after a network blip or brief signal loss: the relay holds your seat for a
+grace window (~30 s). A short blip keeps the same session id, ownership, and host. If a disconnected
+host exceeds the shorter simulation lease, an active peer takes authority once; the old host can
+return to its seat but is demoted. Long reconnects rebase remote smoothing rather than replaying a
+whole-map catch-up streak. Your UI still reflects connection state:
 
 ```ts
 room.on("reconnecting", ({ attempt }) => showOverlay(`Reconnecting… (${attempt})`));
@@ -243,20 +249,28 @@ fights (many writers). A ball on `objects` glides and has one owner. That's the
 - `room.id` — your own session id.
 - `room.me.set(state)` — publish your state, **replaces it wholesale**. Fixed **10–20 Hz tick**,
   never per frame.
+- `room.me.snap(state)` — respawn/teleport/mode edge. Publishes a discontinuity epoch so remotes
+  hard-reseed instead of interpolating from the old pose. Never use for ordinary movement.
 - `room.players` — fresh `Map` each read, **includes you** (skip `id === room.id`). Each value is
   `{ id, name, state, stateRaw }`: `state` is auto-smoothed (remotes) / live (you); `stateRaw` is
   the raw latest (hit-tests, discrete values).
 - `room.objects` — shared objects nobody owns until claimed (a ball, an NPC):
-  - `claim(id)` — take ownership (last claim wins; call on kick/contact). Claiming is optimistic:
-    you own it locally the instant you call it, but if another player claimed the same tick the
-    server's last-claim-wins verdict can revoke you — a `set()` you sent before losing the race is
-    dropped. For contested objects, keep publishing while `isMine` stays true, not just once.
+  - `claim(id)` — **legacy** optimistic request. It flips local ownership immediately and is corrected
+    if the relay rejects it. Keep only for reversible old-game behavior.
+  - `await claimConfirmed(id, options?)` — authoritative accepted/rejected result for a kick, seat,
+    reset, or other irreversible action. Ordinary claims, including host-player contact, honor the
+    relay minimum hold. `reason: "held"` includes `retryAfterMs`; retry only while contact/intent is
+    still valid. `{ authority: "host" }` is reserved for current-host seed/reset lifecycle work.
+    A real hold bypass returns `host-authority`; a non-host request returns `not-host`. A current-owner
+    reassert is accepted as `already-owner` without extending the hold.
   - `set(id, state)` — publish it (only lands while you own it; full flat object each call).
-  - `get(id)` → `{ id, owner, isMine, state, stateRaw }` or `undefined`. `state` is auto-smoothed
+  - `get(id)` → `{ id, owner, isMine, epoch, state, stateRaw }` or `undefined`. `state` is auto-smoothed
     (or live if `isMine`); `stateRaw` is the raw latest.
-  - `release(id)` — give up ownership. `remove(id)` — destroy it (for transient bullets/pickups);
-    **owner-only** — claim it first, or let the current owner remove it (the relay rejects a
-    non-owner's destroy).
+  - `release(id)` / `remove(id)` — legacy fire-and-forget operations.
+  - `releaseConfirmed(id)` / `removeConfirmed(id)` — acknowledged, idempotent operations; use when
+    local mode/state depends on convergence. Remove stays owner-only.
+  - `snap(id, state)` — owner-only reset/teleport with an object discontinuity epoch. Ordinary motion
+    stays on `set`.
   - `ids()` — all object ids seen.
 - `room.isHost` / `room.host` — you are (or who is) the elected authority. Use to pick the single
   writer of `shared` scores/rounds and the single simulator of host-owned objects. Settles within
@@ -272,26 +286,25 @@ fights (many writers). A ball on `objects` glides and has one owner. That's the
 - `room.inputs.send(payload)` / `room.inputs.on((fromId, payload) => …)` — the host-routed
   input channel for host-authoritative physics: anyone sends, ONLY the current host receives.
   See [references/host-physics.md](references/host-physics.md).
-- `room.onHostTick(hz, cb)` — run a fixed simulation tick only while you are the host
-  (auto-starts/stops across host migration). Returns a disposer.
+- `room.onHostTick(hz, cb)` — fixed simulation only while connected and host. It pauses during
+  reconnect, resumes only if still host, and stops on demotion, deliberate leave, or terminal
+  disconnect. Returns a disposer for removing the subsystem earlier.
 
 ## Your message budget (every publish is one relay message)
 
-Every `me.set`, `objects.set`, `objects.claim`, `send`, and `inputs.send` costs **one relay
-message**, and the relay caps each connection at **~120 messages/second sustained** (drops
-above that — you'll see a console warning "the relay dropped N of your messages"). The
-budget math that matters:
+Every publish costs one relay message. The relay uses a global ceiling plus reserved lanes: player
+state 30/s sustained, object control 40/s, host input 60/s, and bulk object/shared/custom traffic
+120/s (all with bursts). A bulk-object flood therefore cannot consume the avatar or control lane.
+Drops still produce the SDK warning; confirmed controls additionally resolve `rate-limited` rather
+than silently disappearing. The budget math that matters:
 
 - Your own state (`me.set`) at 15 Hz + ONE driven/owned moving object at 15 Hz = 30/s. Fine.
 - The pattern that blows the budget: **republishing IDLE objects every tick.** A host that
   owns several parked vehicles/props must NOT `objects.set` each of them at full tick rate —
   publish an object **when it changed**, plus a low-rate keepalive (~1–2 Hz) so late joiners
   converge. Unchanged pose ⇒ no message.
-- If you see the drop warning, count your sends-per-tick: streams × tick-rate must stay well
-  under 120/s with headroom for claims and events.
-- Over budget, the relay spreads the loss across ALL your streams (everything gets choppy at
-  once) rather than freezing one — so a single stuttering object is your cue to check the whole
-  budget, not just that object. The warning is the signal; don't design at the edge of the cap.
+- If you see the drop warning, count each lane separately and also leave headroom under the global
+  ceiling. Reserved capacity protects presence and control, but it is not permission to spam bulk.
 
 ## The loop you must build (input → local → tick → render)
 
@@ -325,7 +338,9 @@ relay enforce it), the owner simulates it, and everyone else reads it auto-smoot
 interpolation as a player. Ownership survives the owner leaving (reassigned to the host).
 
 ```ts
-if (iKickedIt) room.objects.claim("ball");          // become the owner on contact
+const result = await room.objects.claimConfirmed("ball");
+if (result.accepted) applyKickAndFeedback();
+else if (result.reason === "held" && stillTouching) retryAfter(result.retryAfterMs);
 
 if (room.objects.get("ball")?.isMine) {
   room.objects.set("ball", stepBallPhysics());       // only the owner's writes land
@@ -334,8 +349,11 @@ const ball = room.objects.get("ball");
 if (ball) drawBall(ball.state);                       // smoothed for everyone, live for the owner
 ```
 
-**Only claim on interaction, not every frame.** Keep object state flat. Full code and the handoff
-details are in [references/realtime-patterns.md](references/realtime-patterns.md).
+**Keep contact validity alive until acceptance; do not consume one rejected rising edge forever.**
+Never claim every frame: maintain one pending request, then retry after the relay delay only while the
+contact remains valid. Keep object state flat. For Rapier pushables, install the shipped state machine
+with `genex controller networked-physics`; see
+[references/host-physics.md](references/host-physics.md).
 
 ## Host authority (scores, rounds, enemies)
 
@@ -454,10 +472,12 @@ host-driven saving works as long as ANY account is in the room.
 
 ## Checklist
 
-- [ ] `npm i @genex-ai/multiplayer@^0.8.0` (auto-reconnect, `inputs`, `onHostTick` — pin `^0.8.0`, a bare install can resolve older); config wired into the build.
+- [ ] `npm i @genex-ai/multiplayer@^0.9.0` (confirmed controls, snap epochs, reconnect-safe host ticks); config wired into the build.
 - [ ] `reconnecting`/`reconnected`/`disconnect` render an overlay (don't tear the scene down).
 - [ ] Numbers rounded (~2 decimals) before `me.set`/`objects.set`.
 - [ ] Pushable/ownable objects (ball, box, prop) use claim-on-touch + a Rapier proxy (the soft handoff glides the handoff); only a genuine simultaneous tug-of-war (sumo) uses the host-authoritative pattern. See host-physics.md.
+- [ ] Irreversible actions wait for `claimConfirmed`; held contact retries after `retryAfterMs` while still valid.
+- [ ] Respawn/reset/vehicle-mode discontinuities use `me.snap`/`objects.snap`; ordinary motion uses `set`.
 - [ ] Idle/unchanged objects republish at ≤2 Hz keepalive, never every tick (message budget).
 - [ ] Host renders objects OWNED BY OTHERS from the stream (authority follows ownership).
 - [ ] `connect()` runs AFTER `await waitForPlayer()` (never `waitForAuth()` — guests would

package/templates/skills/genex-threejs-multiplayer/references/genre-recipes.md

@@ -23,8 +23,9 @@ The genre where a single contested object is the whole game.
 | Goal celebration / whistle | `send` | whoever scored / the host |
 
 **Decisions:**
-- **Claim the ball on contact**, not every frame: when your player's collider touches the ball,
-  `room.objects.claim("ball")` and apply the kick impulse to your local ball sim.
+- **Confirm the ball claim on contact**, not every frame: when your player's collider touches the
+  ball, await `room.objects.claimConfirmed("ball")` and apply the kick impulse only after
+  `accepted`. If the result is `held`, retry after `retryAfterMs` only while contact still exists.
 - **Only the owner simulates** the ball (`if (objects.get("ball")?.isMine) objects.set("ball", …)`
   in the tick). Everyone draws `objects.get("ball").state`. Non-owner writes are dropped by the
   relay, so two players kicking at once resolve to one owner — no fighting.
@@ -85,9 +86,10 @@ and it's the host, so it survives players joining and leaving.
 | Spawn flashes, hit sparks | `send` | the host / whoever hit |
 
 **Decisions:**
-- **The host owns and simulates the enemies.** On spawn, the host `claim`s each enemy object and,
-  in its tick, runs the AI and `objects.set`s each one. Non-host clients never simulate enemies —
-  they just draw `objects.get("enemy:n").state` (smoothed) and read `stateRaw` for hit-tests.
+- **The host owns and simulates the enemies.** On spawn, the host uses
+  `claimConfirmed(id, { authority: "host" })`; after acceptance its tick runs the AI and
+  `objects.set`s each enemy. Non-host clients never simulate enemies — they just draw
+  `objects.get("enemy:n").state` (smoothed) and read `stateRaw` for hit-tests.
 - **One object per enemy** (flat `{x,y,z,hp}`) so each smooths independently. For a big horde keep
   the count modest (≈8–16 active); it's casual, not a bullet-hell server.
 - **Host migration keeps the game alive:** if the host leaves, its enemies are reassigned to the
@@ -98,7 +100,7 @@ and it's the host, so it survives players joining and leaving.
   `send` never echoes to the sender — so when the **host itself** shoots an enemy it owns, it must
   apply that damage to its local enemy sim **directly**, not via `send` (which wouldn't come back).
   Rule of thumb: if `objects.get("enemy:3")?.isMine`, apply the hit locally; otherwise `send` it.
-  Enemy death: the host `objects.remove("enemy:3")`.
+  Enemy death: the host awaits `objects.removeConfirmed("enemy:3")` before finalizing rewards.
 - **Waves/score are host-only** in `shared`; late joiners read the current wave on connect.
 
 **Acceptance feel:** enemies move smoothly for everyone; killing the host's tab mid-wave promotes a

package/templates/skills/genex-threejs-multiplayer/references/host-physics.md

@@ -19,6 +19,17 @@ ownership to "whoever touched last" is itself the wrong model.
 
 ## Tier 1 — pushable / ownable body (claim-on-touch + a Rapier proxy)
 
+Install the product helper first:
+
+```bash
+genex controller networked-physics
+```
+
+`NetworkedPushable` owns the confirmed-claim/retry, dynamic-to-kinematic switch, visible-proxy pose
+plus raw-momentum handoff seed,
+single-smoothed follower, moved-only publishing, keepalive, release-on-rest, finite pose validation,
+and host reset snap. Prefer that helper over copying this explanatory state machine.
+
 The object is a REAL Rapier body on every client, and its body TYPE follows ownership:
 
 - **You own it → a `dynamic` body.** Your (dynamic) character capsule collides with it and Rapier's
@@ -45,14 +56,16 @@ const body = physics.createBody({
   userData: { controller: { excludeCharacterRay: true } },
 });
 ballCollider(physics.world, body, RADIUS, { friction: 0.5, restitution: 0.35, density: 0.6 });
-let wasTouching = false, wasMine = false, claimCd = 0;
+let touching = false, wasMine = false, pendingClaim: Promise<unknown> | null = null, retryAt = 0;
 const MAX_SPEED = 24;
 
 // The host seeds the canonical spawn ONCE so the object exists on `objects` for late joiners.
-function ensureInit() {
+async function ensureInit() {
   if (room.isHost && room.objects.get("ball") === undefined) {
-    room.objects.claim("ball");
-    room.objects.set("ball", { x, y, z, q: [0, 0, 0, 1], vx: 0, vy: 0, vz: 0 });
+    const result = await room.objects.claimConfirmed("ball", { authority: "host" });
+    if (!result.accepted) return;
+    room.objects.snap("ball", { x, y, z, q: [0, 0, 0, 1], vx: 0, vy: 0, vz: 0 });
+    await room.objects.releaseConfirmed("ball");
   }
 }
 
@@ -61,18 +74,17 @@ function updateBall(dt: number) {
   let v = room.objects.get<BallState>("ball");
   let mine = !!v?.isMine;
 
-  // Rising-EDGE claim: sustained contact yields NO new rising edge, so ONE owner holds it (no per-frame
-  // ownership ping-pong). A short cooldown throttles a steal-war. Use HORIZONTAL distance — the feet sit
-  // at ground level while the ball centre is at y≈RADIUS, so a 3D distance would eat into your reach.
+  // Keep contact validity alive. One rejected collision edge must not consume the attempt forever:
+  // retry after the relay hold delay while STILL touching, with at most one request in flight.
   const dx = ballMesh.position.x - feet.x, dz = ballMesh.position.z - feet.z;
-  const touching = onFoot && Math.hypot(dx, dz) < RADIUS + REACH;
-  if (claimCd > 0) claimCd -= dt;
-  if (touching && !wasTouching && !mine && claimCd <= 0) {
-    room.objects.claim("ball");            // optimistic: isMine flips true locally THIS frame
-    claimCd = 0.25;
-    v = room.objects.get<BallState>("ball"); mine = !!v?.isMine;
+  touching = onFoot && Math.hypot(dx, dz) < RADIUS + REACH;
+  if (touching && !mine && !pendingClaim && performance.now() >= retryAt) {
+    pendingClaim = room.objects.claimConfirmed("ball").then((result) => {
+      if (!result.accepted && touching && (result.reason === "held" || result.reason === "rate-limited")) {
+        retryAt = performance.now() + (result.retryAfterMs ?? 50); // both carry a server retry delay — honor it
+      } else retryAt = 0;
+    }).finally(() => { pendingClaim = null; });
   }
-  wasTouching = touching;
 
   if (mine && !wasMine) {
     // Gained ownership → dynamic. SEED velocity from the wire (NEVER zero, or a rolling ball
@@ -121,15 +133,16 @@ function publishBall() {
 
 Rules that make it correct:
 
-- **Rising-edge claim + a short cooldown** (~0.25s), never "am I touching": sustained contact must not
-  re-claim every frame. Add a minimum-hold (~0.5s) before you'll `release`, so a shove finishes under
-  your sim.
+- **Sustained-contact confirmed claim:** keep one request pending; after `held`, retry at
+  `retryAfterMs` only while contact still exists. Never spam every frame and never let one rejected
+  collision edge permanently disable the interaction.
 - **Never zero velocity on claim** — seed `linvel` from the published `vx/vy/vz`, or a rolling ball snaps
   to a dead stop on every handoff.
 - **Publish velocity, not just position** — the next owner seeds from it, so the object keeps its motion
   across the handoff.
 - **Release-on-rest** (optional): once you own an object that's been at rest + untouched a couple of
-  seconds, `room.objects.release("ball")` so ownership doesn't pile up on a lone wanderer — its last
+  seconds, `await room.objects.releaseConfirmed("ball")` so ownership doesn't pile up on a lone
+  wanderer — its last
   state persists on the wire for the next toucher, who re-claims.
 - **Distributed by construction:** each client publishes only what it currently owns, so the message
   budget spreads across players instead of funnelling every object through one host's send budget. This
@@ -168,13 +181,14 @@ room.inputs.on((fromId, payload) => {
   if (p?.obj && Array.isArray(p.push)) pending.push(p as { obj: string; push: number[] });
 });
 
-room.onHostTick(30, (dtMs) => {
+room.onHostTick(30, async (dtMs) => {
   // 1) First tick after election: adopt the objects + seed the physics world from the
   //    last published truth (stateRaw) — NEVER from zero, or the world teleports.
   for (const id of CONTESTED_IDS) {
     const view = room.objects.get(id);
-    if (!view || !view.isMine) {
-      room.objects.claim(id);
+    if (!view?.isMine) {
+      const result = await room.objects.claimConfirmed(id, { authority: "host" });
+      if (!result.accepted) continue;
       seedRapierBody(id, view?.stateRaw); // position/rotation/velocity from the wire
     }
   }
@@ -201,6 +215,10 @@ for (const id of CONTESTED_IDS) {
 
 Rules that make it correct:
 
+- `onHostTick` pauses during reconnect and stops on demotion/leave/terminal disconnect. Bound the input
+  queue, attribute input from the callback's authenticated `fromId` (never payload `from`), and discard
+  stale pre-failover inputs when a new host adopts raw state.
+
 - **Sim internals that must survive migration** (velocities, cooldowns, aggro) either live in
   the published object state or get mirrored at low rate into a dedicated object
   (`objects.set("sim", …)`) the next host reads on adoption. Positions/rotations come free

package/templates/skills/genex-threejs-multiplayer/references/realtime-patterns.md

@@ -104,9 +104,10 @@ ownership changes (no snap), and the object survives its owner leaving (reassign
 // ball.ts
 const ball = { x: 0, y: 0.5, z: 0, vx: 0, vy: 0, vz: 0 }; // the owner's local sim
 
-// claim on contact (you kicked it) — NOT every frame
-function kick(dir: THREE.Vector3, power: number) {
-  room.objects.claim("ball");
+// Confirm on the contact edge; retry a `held` result only while contact remains.
+async function kick(dir: THREE.Vector3, power: number) {
+  const result = await room.objects.claimConfirmed("ball");
+  if (!result.accepted) return;
   ball.vx += dir.x * power; ball.vz += dir.z * power;
 }
 
@@ -129,13 +130,14 @@ function drawBall() {
 
 Rules that keep it correct:
 
-- **Claim on interaction, not continuously.** Whoever last kicked owns and simulates it.
+- **Confirm ownership before an irreversible interaction.** On `held`, respect `retryAfterMs` and
+  retry only while the original contact/action is still valid.
 - **Keep object fields flat** (`x/y/z`, a 4-number quaternion). Nested objects snap instead of glide.
 - **Only the owner's `set` lands** — the relay drops writes from non-owners, so you never get two
   clients fighting over the ball. You don't need to check "am I owner" before drawing, only before
   simulating.
-- **Transient objects** (bullets, pickups): `room.objects.remove(id)` when they expire, so they
-  don't pile up.
+- **Transient objects** (bullets, pickups): the owner awaits `room.objects.removeConfirmed(id)`
+  when they expire, so destruction is acknowledged and idempotent across reconnects.
 
 ## Host authority (scores, rounds, world)
 

package/templates/skills/genex-threejs-vehicle-controllers/SKILL.md

@@ -29,6 +29,9 @@ Existing files are never overwritten (use `--force` to refresh). For the
 on-foot character that enters these vehicles, also run
 `npx genex controller character` and load `$genex-threejs-character-controller`.
 
+These files become game-owned. Do not use `--force` as an upgrade mechanism after editing them;
+install into a scratch project and port the targeted `syncFromBody`/transition changes.
+
 ## The loop contract (get this right first)
 
 Every controller exposes `update(dt?)` that must run once per **fixed physics
@@ -106,20 +109,32 @@ On enter/exit: the on-foot character **disappears into the vehicle on enter
 behavior, not a bug. Don't leave the character mesh standing next to a car it
 is supposedly driving; see [references/enter-exit.md](references/enter-exit.md).
 
-## Multiplayer: vehicle occupancy is shared state
+## Multiplayer: vehicle occupancy is confirmed object ownership
 
 If the game is multiplayer, **who is in what vehicle must be synced** — a
 remote player vanishing into an apparently empty car reads as a bug. Load
 `$genex-threejs-multiplayer` before writing any networking code, then:
 
-- Publish occupancy with the player's state (e.g. `driving: "car" | null`)
-  or as a shared key — and the occupied vehicle's pose with it.
+- Install `genex controller networked-physics` and use `NetworkedVehicle`. A seat is the vehicle
+  object's confirmed owner—not a writable `shared` key. Enter only after `claimConfirmed` accepts;
+  two simultaneous entrants therefore produce one driver and one clean loser.
+- **Occupied means owned.** Idle vehicles stay unowned, so a present owner IS the current driver —
+  `enter()` refuses an owned vehicle by default (the relay's short hold only protects the first
+  ~300 ms of a drive, so without this gate any walk-up claim would hijack a moving car and dump its
+  driver). Pass `enter({ steal: true })` only when carjacking is an intended mechanic, and wire
+  `onSeatLost` so a forcibly dismounted driver returns to on-foot controls instead of a dead seat.
+- Publish `driving: "car" | null` in the player's state for remote visuals. Use `me.snap` on entry/exit
+  mode edges, and continuous `objects.set` only from the confirmed driver.
 - Same authority rule as the character: the **local player simulates the
-  physics of whatever they occupy**; remote vehicles are interpolated
-  visuals only. Never run `VehicleController`/`DroneController` for a
-  remote player — drive a plain mesh from their synced pose.
-- An unoccupied vehicle needs one owner too: elect one client (e.g. the
-  first in the room) to simulate it and publish its pose as shared state.
+  physics of whatever they occupy**; remote vehicles are visuals only —
+  draw the SDK-smoothed `objects.get(id).state` directly on a plain mesh
+  (never re-lerp/buffer it) and never run `VehicleController`/
+  `DroneController` for a remote player.
+- Idle vehicles remain unowned at their last raw pose. The host may explicitly claim+snap+release to
+  seed/reset, but must not continuously adopt or republish parked vehicles. Persist raw idle truth.
+- On accepted entry, seed the body from `stateRaw`, enable/register/wake it, call `syncFromBody`, and
+  `snapBodyInterpolation` before controls/camera read it. On exit, publish final pose, player-snap the
+  character, unregister, then wait for confirmed release.
 
 ## Boundaries and troubleshooting
 

package/templates/skills/genex-threejs-vehicle-controllers/references/enter-exit.md

@@ -98,9 +98,9 @@ registered vehicle wins the prompt.
   reappears. Raise it if the character spawns inside a wide chassis. The
   default equals the default sensor radius so immediate re-entry stays
   possible — intended.
-- Exiting a flipped vehicle whose forward axis is parallel to up produces a
-  degenerate exit basis (faithful upstream non-guard). If vehicles in your
-  game can end up nose-down, right them before allowing exit.
+- Flipped/nose-down vehicles are supported: the manager projects the live forward axis and falls back
+  to body-X/world-Z before normalization, so the exit basis remains finite. Still choose an
+  `exitLength` that clears the actual chassis collider.
 
 ## Seat visuals: Sitting_Enter / Driving_Loop / Sitting_Exit
 
@@ -186,15 +186,24 @@ far-from-Y gravity direction will misbehave. For rigs beyond this, see
 
 ## Multiplayer
 
-Occupancy is shared state — remote players must see who is in what. With
+Occupancy uses confirmed object ownership — remote players must see who is in what. With
 `$genex-threejs-multiplayer` (load it before writing any networking code):
 
 - Put `driving: "car" | "drone" | null` in each player's synced state; on
   remote change, show/hide that player's on-foot avatar and seat their
   visual in the vehicle (the seat-visual pattern above, minus the physics).
-- The occupant simulates the vehicle and publishes its pose; everyone else
-  interpolates a plain mesh. Never run the vehicle controllers for a remote
-  player's vehicle.
-- Gate entry on a shared occupancy key so two players can't board the same
-  seat: claim it (e.g. `room.shared.set("occupant:car", room.id)`) and treat
-  a losing race as "prompt stays up".
+- The occupant simulates the vehicle and publishes its pose; everyone else draws the
+  SDK-smoothed `objects.get(vehicleId).state` directly on a plain mesh — the SDK already
+  interpolates it. Never buffer/lerp that `state` a second time, and never run the vehicle
+  controllers for a remote player's vehicle.
+- Install `genex controller networked-physics` and use `NetworkedVehicle`: gate entry on
+  `NetworkedVehicle.enter()` / `objects.claimConfirmed(vehicleId)` **before** parking the
+  character or switching the `EnterExitManager` active unit — a rejected seat must leave the
+  on-foot prompt and controls untouched. Do NOT put the claim inside `onOccupantEnter` after the
+  park: `performInteract` has no rollback, so a rejection there strands a hidden character wired
+  to a vehicle it never won. Never use `shared.set("occupant:car", ...)` as a lock—any client can
+  overwrite it. An accepted seat seeds from raw pose, calls `syncFromBody` +
+  `snapBodyInterpolation`, and becomes the only publisher.
+- Exit publishes final vehicle truth, uses `me.snap` for the player mode edge, unregisters the local
+  body, and waits for `releaseConfirmed`. Idle vehicles stay unowned; host seed/reset is the narrow
+  `{ authority: "host" }` claim+snap+release path.

package/templates/controllers/shared/NETWORKING.md

@@ -1,11 +0,0 @@
-# Networking these controllers
-
-These controllers simulate **your own player only** (self-authoritative, zero input
-latency). To show OTHER players' rigs in a multiplayer game, publish a small flat state on
-a fixed tick and play it back on a visual-only remote rig — never instantiate a controller
-or a Rapier body for a remote player.
-
-The complete recipe (what to publish per controller, remote playback, contested-contact
-physics via the host) lives in the multiplayer skill:
-`genex-threejs-multiplayer` → `references/host-physics.md`. Load that skill before writing
-any networking code.