@genex-ai/cli-demo 0.53.0-dev.117 → 0.53.0-dev.118

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.53.0-dev.117",
+  "version": "0.53.0-dev.118",
   "description": "Set up your ~/.claude workspace, authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {

package/templates/skills/genex-threejs-game-feel/SKILL.md

@@ -77,7 +77,11 @@ hits, layer two or three of:
   With the bundled physics pack this is built in — `physics.paused = true` /
   `physics.timeScale = 0.2` (see the physics skill's pause/slow-mo section) plus
   `anims.setPaused(true)` / `anims.setTimeScale(0.2)` for the character's
-  animations. Don't hand-roll a second clock.
+  animations. Don't hand-roll a second clock. **In multiplayer, hitstop is local
+  presentation feedback:** never pause the network pump, reconnect/quorum timers,
+  remote interpolation, or another player's/host's simulation. Slow/freeze only
+  your locally owned gameplay clock and visuals; the authoritative hit is still
+  deduped and applied once through the multiplayer skill's normal event path.
 
 One layer per small event, three for the biggest — uniform intensity flattens
 everything back out.
@@ -99,4 +103,6 @@ everything back out.
 - Restart requires reloading the page (kills the retry loop — and reloads
   re-run auth and asset loading).
 - Shake/flash spam with no cause — feedback inflation reads as noise.
+- Multiplayer hitstop pauses networking or host simulation, turning impact feedback
+  into packet bursts, quorum lag, or a freeze for players who were not hit.
 - Feel constants scattered through the code where nobody dares touch them.

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

@@ -29,20 +29,23 @@ whole reason this skill exists.
 Read [references/realtime-patterns.md](references/realtime-patterns.md) for the complete movement
 example, the shared-object/ball code, rotation, and host usage. Read
 [references/genre-recipes.md](references/genre-recipes.md) for ready-made per-genre setups
-(sports/ball, shooter, co-op with host-simulated enemies) — pick the one matching the game.
+(sports/ball, shooter, co-op with host-simulated enemies) — pick the one matching the game. Before
+calling multiplayer done, run the mandatory
+[netcode feel gate](references/genex-netcode-feel-checklist.md).
 
 ## Install
 
 ```bash
-npm i @genex-ai/multiplayer@^0.10.1
+npm i @genex-ai/multiplayer@^0.10.2
 ```
 
-> Pin `@^0.10.1` (not a bare `npm i`): live connected-player presence, supplier-form `connect()`
+> Pin `@^0.10.2` (not a bare `npm i`): unowned object writes now warn instead of failing silently;
+> live connected-player presence, supplier-form `connect()`
 > auth, regional relay selection (`getColyseusUrls()` + `urls`)
 > landed in 0.10; confirmed object controls, snaps, host-tick teardown, and reconnect rebasing
 > in 0.9. An older resolve does not have those.
 
-This skill targets `@genex-ai/multiplayer` **≥ 0.10.1** (`objects`/`host` since 0.4;
+This skill targets `@genex-ai/multiplayer` **≥ 0.10.2** (`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; regional relay selection via `getColyseusUrls()` since 0.10).
@@ -56,18 +59,30 @@ ownership, match seating/adjudication, and rate/size caps — but a modified cli
 lie about its own position or score. Great for friends and casual lobbies; don't promise
 ranked-grade fairness.
 
-## Choose one net model first
+## Choose one net model from the player experience
 
-- **`connect()` — shared world:** everyone for this slug shares a room. Use for
-  persistent/co-op spaces where the game may remain valid with one player.
-  Pass auth as a FUNCTION so each explicit connect attempt reads fresh; after
-  a terminal disconnect the game starts a new connect flow.
-- **`matchmake()` — capped matches:** the queue seats players into separate
-  rooms. Use for duels, races, teams, and finite arenas. It requires
-  `genex.matchmaking` in `package.json`; auth is a FUNCTION; the handle may
-  replace `mm.session`, so the game polls and rebinds it.
+Infer this yourself when the experience is clear. Do **not** make the player choose an SDK API,
+preset, or config. Ask one plain-language question only when the design genuinely supports both
+models and the answer changes the experience — for example: *"Should this be one ongoing arena
+people drop into, or a fresh fair match that waits for everyone and then starts together?"*
 
-Do not combine the requirements or silently convert one model into the other.
+| Player experience | Model | Why |
+| --- | --- | --- |
+| One ongoing drop-in world; late joiners enter what is already happening; solo play remains valid | `connect()` | One shared room, no queue or round formation |
+| Fresh bounded match/mission; quorum, fair start, capacity, teams, or parallel sessions matter | `matchmake()` | Server forms capped rooms and exposes queue/waiting state |
+
+Genre names do not decide this. A sumo game may be an always-online drop-in ring (`connect()`) or a
+fair-start bout (`matchmake()`). A co-op game may be an ongoing shared space (`connect()`) or a
+bounded dungeon run (`matchmake()`). Write one plan line before coding:
+
+> Net model: `<connect|matchmake>` — `<player-experience reason>`; start/quorum: `<rule>`;
+> late join/backfill: `<rule>`; below-quorum/end tail: `<rule>`.
+
+Use `connect()` when the game is honestly one always-online world. Use `matchmake()` when it promises
+a match, run, race, mission, teams, a waiting count, or a synchronized start. If the brief says
+"100 players in the same world," or mixes a shared hub with instanced matches, do not guess: surface
+the platform/capacity mismatch or ask which experience matters. Do not combine the requirements or
+silently convert one model into the other.
 
 ## Matchmaking (competitive presets — server-owned)
 
@@ -372,6 +387,25 @@ const lobby = await joinPrivate<MyState>(code, { urls, room: slug, auth: () => g
 Pick your own per-player state shape (any JSON). `room` is the **project slug**
 (printed by `genex init`) — same id = same room, different ids are fully isolated.
 
+### WHEN to call `connect()` — make the screen tell the truth (MANDATORY)
+
+`connect()` immediately joins the shared world and makes the player present. Two lifecycles are
+valid; pick exactly one:
+
+- **Always-online world:** there is no Play/Online commitment screen. After identity is ready,
+  connect and spawn immediately. This is correct for a drop-in social space or an ongoing sumo ring
+  where loading the game already means joining it. A lightweight loading/reconnecting overlay is
+  honest; a Play button that appears to delay entry is not.
+- **Menu before online:** if the game shows **Play**, **Play Online**, **Join Arena**, or offers
+  Local/Bots, that click is the commitment point. Boot the menu/offline world with no relay contact,
+  call `connect()` only inside the online handler, and spawn the network player only after it
+  resolves. Local/Bots never connect. Leaving online calls `room.leave()`, disables terminal rejoin,
+  removes the online avatar, and returns to the pre-online state.
+
+Never auto-connect/spawn behind a title menu and then ask the player to press Play. The API is not
+the bug in that case; the lifecycle is. Likewise, do not add a fake queue/finding screen to an
+always-online `connect()` world — it has no match formation to report.
+
 **Joining requires the SDK's player identity — the relay rejects tokenless
 joins, but accepts guests** (accountless players named like `Guest-1234`).
 Load the `genex-threejs-embed-auth` skill first (it sets up `initEmbed(...)`),
@@ -587,6 +621,19 @@ is the newest value with no smoothing. **Draw** from `state`; **test** against `
 detection, "am I close enough to kick", pickups, and any discrete number (hp, ammo, animation id,
 a 0/1 flag) that must not arrive fractional. This holds for both players and objects.
 
+**HARD RULE — `state` is for RENDER ONLY.** Every GAMEPLAY read — hit tests, deflection/catch/
+return windows, physics seeding after adoption, distance and reach checks — uses `stateRaw`.
+The smoothed view is ~100–150 ms in the past; at projectile or ball speeds the REAL object has
+already passed where the ghost still is. Two field-verified failures caused by breaking this rule:
+- A pong-style game read the incoming ball via `state` for its deflection window — at top speed
+  the real ball crossed the paddle plane before the smoothed one arrived; returns were literally
+  impossible online while feeling fine in solo testing.
+- A dodgeball game aimed at opponents drawn from `state` — a strafing target's real position was
+  already elsewhere, so "direct hits" never registered damage.
+Corollary: **cap top speeds against the network, not just the physics** — an object's arena/table
+crossing time should stay above ~2× the smoothing delay (~0.25 s), or receivers are reacting to
+history no matter how correct the code is.
+
 ## Shared objects (the ball, the NPC) — use `objects`, never `shared`
 
 A ball belongs to no player. Put it on `objects`: exactly one client owns it at a time (the SDK +
@@ -611,6 +658,67 @@ contact remains valid. Keep object state flat. For Rapier pushables, install the
 with `genex controller networked-physics`; see
 [references/host-physics.md](references/host-physics.md).
 
+**OWNERSHIP INVARIANT — a host-simulated object MUST be claimed before it publishes.**
+`objects.set()` / `objects.snap()` on an object you do not own are ignored; SDK ≥0.10.2 warns once
+per object/operation instead of failing silently.
+The field-verified symptom is unmistakable — *the object moves on the host's screen and sits
+frozen at spawn for everyone else* (each client falls back to whatever local body it has; only
+the host's is simulated). If the host simulates an object (a crate, an NPC, a puck), it must:
+
+```ts
+let hostReady: Promise<boolean> | null = null;
+function ensureHostObjects(room: Session<S>) {
+  if (!room.isHost) return Promise.resolve(false);
+  if (hostReady) return hostReady;                    // one adoption flight, never per tick
+  hostReady = (async () => {
+    for (const id of HOST_OBJECT_IDS) {
+      const before = room.objects.get(id)?.stateRaw;  // last published truth, before claiming
+      const res = await room.objects.claimConfirmed(id, { authority: "host" });
+      if (!res.accepted) return false;
+      seedPhysicsFromRaw(id, before);                 // pose + velocity/cooldowns, never zero
+    }
+    return true;
+  })();
+  return hostReady;
+}
+
+room.on("host", () => { hostReady = null; void ensureHostObjects(room); });
+room.onHostTick(30, async () => {
+  if (!(await ensureHostObjects(room))) return;       // no step/publish before adoption
+  stepAndPublishHostPhysics();
+});
+```
+
+Do not assume `onHostTick` firing means you own anything — host *election* and object
+*ownership* are separate systems. Claim explicitly, check `accepted`, re-claim on migration, and
+do not step or publish until the whole host-owned set is ready.
+
+**RENDER SPLIT — the host draws its own authority, only NON-hosts read the wire.** Once the
+host owns the object and publishes, `objects.get(id).state` becomes defined on EVERY client
+including the host — and if the host now renders from that networked `state` instead of its
+own sim body, a subtle trap bites: a freshly-claimed object's smoothed `state` can briefly be
+a DEGENERATE transform (a zero/NaN quaternion, or a position mid-interpolation from origin),
+which renders the mesh to NaN and it vanishes ON EVERY SCREEN. Field-verified: enabling the
+claim above without this split made a crate invisible for everyone. The fix:
+
+```ts
+// Host renders its own authoritative sim; non-hosts render the published truth, GUARDED.
+const cs = room.isHost ? null : room.objects.get(id)?.state;
+const ok = cs && Number.isFinite(cs.x) && Number.isFinite(cs.y) && Number.isFinite(cs.z);
+if (ok) {
+  mesh.position.set(cs.x, cs.y, cs.z);
+  if (Array.isArray(cs.q) && cs.q.length === 4) {         // normalize — a bad sample must not vanish the mesh
+    const n = Math.hypot(cs.q[0], cs.q[1], cs.q[2], cs.q[3]);
+    if (n > 1e-3) mesh.quaternion.set(cs.q[0]/n, cs.q[1]/n, cs.q[2]/n, cs.q[3]/n);
+  }
+} else {
+  mesh.position.copy(localBodyPos); // host, offline, or non-host awaiting first valid sample
+}
+```
+Prefer syncing the MINIMAL transform a slide/roll needs (a puck on a plane is `{x,z}` + a
+constant y — no quaternion at all); every field you don't send is a field that can't arrive
+degenerate. The netcode-park reference does exactly this.
+
 ## Host authority (scores, rounds, enemies)
 
 One client is the `host`. Let *only* the host write agreed state and simulate shared enemies, so
@@ -776,11 +884,16 @@ host-driven saving works as long as ANY account is in the room.
 
 ## Checklist
 
-- [ ] `npm i @genex-ai/multiplayer@^0.10.1` (connected presence, supplier auth, confirmed controls, snap epochs, reconnect-safe host ticks); config wired into the build.
+- [ ] `npm i @genex-ai/multiplayer@^0.10.2` (connected presence, supplier auth, confirmed controls, snap epochs, reconnect-safe host ticks, unowned-write warnings); config wired into the build.
+- [ ] The plan names one net model, the player-experience reason, start/quorum, late-join/backfill,
+      and below-quorum/end behavior. The agent inferred it unless the experience was genuinely ambiguous.
 - [ ] `reconnecting`/`reconnected`/`disconnect` render an overlay (don't tear the scene down).
 - [ ] `connect()` terminal `disconnect` starts a guarded backoff rejoin that reruns
       `waitForPlayer()` and reads fresh auth on every attempt; deliberate leave stops it;
       replacement code `4409` NEVER auto-rejoins.
+- [ ] `connect()` lifecycle is honest: an always-online world has no fake Play screen and may
+      connect/spawn after identity; if a Play/Online/Local/Bots menu exists, connect and spawn happen
+      only after the online click, Local/Bots stay offline, and leaving calls `room.leave()`.
 - [ ] 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.
@@ -830,6 +943,8 @@ host-driven saving works as long as ANY account is in the room.
       per-client, never `mm.matchmaking.teams`, never a default for the unassigned — and you
       WATCHED two browsers land on OPPOSITE teams.
 - [ ] Picked the matching recipe from [references/genre-recipes.md](references/genre-recipes.md).
+- [ ] Passed the [netcode feel gate](references/genex-netcode-feel-checklist.md), including the two-
+      identity real-input proof for the chosen model.
 
 ## Troubleshooting auth
 

package/templates/skills/genex-threejs-multiplayer/references/genex-netcode-feel-checklist.md

@@ -0,0 +1,61 @@
+# Genex multiplayer netcode feel gate
+
+Run this gate before calling any multiplayer loop playable. A build, screenshot, or one local client
+does not prove networking. Keep the check proportional: one focused two-client pass, not a new test
+suite for the game.
+
+## Before coding
+
+- Write the net-model line: `connect` or `matchmake`, the player-experience reason, start/quorum,
+  late-join/backfill, and below-quorum/end behavior.
+- Infer the model from the experience. Ask the user only if both an ongoing drop-in world and fresh
+  bounded sessions are plausible and the brief does not choose between them.
+- State authority per thing: local player, remote player, shared object, score/round, projectile/hit,
+  and host-simulated entity.
+- Budget the fastest interaction. Rendered remote state is delayed for smoothness; gameplay tests use
+  `stateRaw`, sweep between raw samples, and cap speeds so reaction windows remain humanly possible.
+
+## Lifecycle
+
+- `connect` always-online world: no fake Play/finding screen; identity may be followed by immediate
+  join/spawn. Leaving is explicit and stops terminal rejoin.
+- `connect` behind Play/Online/Local/Bots: no relay contact or network spawn before the online click;
+  Local/Bots stay offline; leaving online calls `room.leave()`.
+- `matchmake`: create the handle only on Play/Find Match; show searching/waiting only after that
+  commitment; leaving calls `mm.cancel()`; bind every replacement `mm.session`.
+- Quorum-required games leave `playing` when connected quorum falls below the declared minimum.
+  Ongoing shared worlds may continue solo only when that was the stated design.
+
+## Authority and interaction
+
+- Self movement and immediate reversible feedback happen locally on the input frame.
+- Remote players and non-owned objects render `state` directly, with no second interpolator.
+- Every gameplay read uses `stateRaw`: hit, return/deflect/catch, reach, pickup, goal, physics adoption,
+  hp/ammo/flags, and target selection.
+- Fast bodies/projectiles use a segment or swept-volume test from previous raw position to current raw
+  position; point samples are not enough.
+- Irreversible shared results wait for confirmed authority. `objects.set`/`snap` happen only after an
+  accepted claim; host simulation waits for single-flight adoption and seeds from last raw truth.
+- Every travel-time PvP projectile has attacker-side raw detection plus victim-side/self detection
+  where appropriate, both feeding one projectile-id-deduped hit application.
+- Hitstop never pauses the networking pump or another player's simulation. Freeze/slow the local
+  presentation and locally owned gameplay clock only; keep sends, receives, reconnects, and quorum
+  checks running.
+
+## One focused proof with two distinct identities
+
+Use regular + incognito guest identities, two accounts/devices, or ask the user to perform the exact
+sequence. Two tabs sharing one identity are one enforced seat.
+
+1. Enter online using real clicks. Then press Space/Enter/the main action using real key input; confirm
+   focus did not re-trigger Play/Leave and both sessions remain live.
+2. Confirm reciprocal presence and movement: A sees B move and B sees A move.
+3. Exercise the signature interaction at full intended speed: kick/return, projectile hit, shared
+   object claim, enemy hit, or vehicle seat. Confirm immediate local feedback and exactly one result.
+4. Exercise one authority transition: object ownership, seat, or host migration. Confirm no freeze,
+   teleport-to-origin, duplicate point/damage, or host-only visual divergence.
+5. For `matchmake`, drop one player, observe quorum/waiting behavior, then join a new identity and
+   confirm re-seat/backfill. For `connect`, verify the declared leave/solo/host-migration behavior.
+
+If this proof was not possible, say exactly which items remain unverified. Never substitute a
+screenshot or local-test mode for multiplayer evidence.

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

@@ -34,9 +34,18 @@ The genre where a single contested object is the whole game.
   everyone else) and writes the score to `shared`; everyone reads `shared.get("score_a")` in the HUD.
 - **A player quitting mid-match doesn't kill the ball** — if the owner leaves, the ball is
   reassigned to the host automatically and play continues.
+- **The receiver's interaction window reads `stateRaw`, never `state`** — return/deflect/catch
+  checks against the smoothed ball test a ghost ~120 ms in the past; at rally speeds the REAL
+  ball has already crossed your paddle/goal line before the ghost arrives (field-verified: it
+  made a pong-style game unreturnable online while feeling perfect in solo play). Render the
+  smoothed ball, but run the window on the raw one, sweeping raw-sample→raw-sample.
+- **Cap top ball speed against the network:** keep the arena/table crossing time above ~2× the
+  smoothing delay (≳0.25 s). Faster than that, no human can respond to what they're shown —
+  no amount of correct code fixes reacting to history.
 
 **Acceptance feel:** the kicker sees the ball respond the same frame; everyone else sees it glide;
-a contested kick settles on one owner within a snapshot; the owner leaving doesn't freeze the ball.
+a contested kick settles on one owner within a snapshot; the owner leaving doesn't freeze the ball;
+a full-speed shot is still humanly returnable by the receiving player.
 
 ---
 
@@ -94,6 +103,25 @@ slow physical projectiles, all against the same damage/defeat rules.)
 scores exactly one point even if the host changes mid-fight; the scoreboard survives a reload; one
 player on a throttled/backgrounded tab doesn't drag others.
 
+### Every travel-time projectile vs moving targets — the "visual hit, no damage" trap
+
+Any projectile that spends time moving through the world — object-owned, host-simulated, or
+deterministically replayed from a throw event (fireball, rocket, dodgeball) — inherits BOTH classic
+netcode failures, and the symptom is always the same: *the projectile visibly hits a strafing player
+and nothing happens.* Do not limit these rules to one implementation style:
+
+1. **Detection must run on the ATTACKER too, against `stateRaw`.** Target-only self-detection
+   ("each player owns their own hp, so only I test hits on me") silently fails against movers:
+   the thrower aimed at the smoothed ghost (~120 ms old), the deterministic projectile flies to
+   where the target WAS, and the target's self-test against its own REAL position never fires.
+   Run the attacker-side test each frame vs every remote's `stateRaw`, then send the damage
+   event the victim always honors (dedupe by projectile id so self-detection can coexist).
+2. **Sweep, never point-sample.** A projectile at 20 m/s moves ~0.33 m per 60 Hz frame — more
+   than most hit radii. Track `prev` each frame and test segment(prev→pos) vs the target
+   sphere, on both the attacker's and the target's tests.
+3. Both channels apply damage through ONE deduped `applyHit(projectileId)` on the victim, so a
+   ball registered by both sides still counts once.
+
 ---
 
 ## Recipe 3 — Co-op vs enemies (horde, tower defense, dungeon)
@@ -178,17 +206,22 @@ the short-handed side.
 
 Almost every game opens on a menu: **Play Online**, **Local / Single-player**, **Bots**. The rule
 that keeps online matches clean: **the menu is pre-multiplayer — there is no room, no queue, no
-server contact until the player commits to online.** `matchmake()` IS the "Play Online" button. Call
-it anywhere earlier (page load, boot code, beside `waitForPlayer()`) and a player who picks Bots is
-still parked in an online room, counting toward `minPlayers` while three real players wait for a
-fourth who never comes.
+server contact until the player commits to online.** The chosen online API — `matchmake()` for fresh
+bounded sessions, `connect()` for one ongoing shared world — IS the "Play Online" button. Call either
+one earlier (page load, boot code, beside `waitForPlayer()`) and a player who picks Bots is already
+present online. With matchmaking they contaminate quorum; with a shared world they spawn an avatar
+for someone who never chose to enter it.
+
+Exception: a truly always-online game may call `connect()` after identity and spawn immediately,
+but then loading the game already means "join" — it has no Local/Bots choice and no fake Play screen.
+An ongoing drop-in sumo ring can use that shape; a sumo title menu cannot auto-spawn behind Play.
 
 | Moment | What runs | Relay contact |
 | --- | --- | --- |
 | Page load → menu | An **offline world** generated locally, menu overlay on top | NONE. Not `connect()`, not `matchmake()`. `waitForPlayer()` may run (mints identity only, seats nobody). |
 | "Bots" / "Local" | The same offline world + local AI / single-player | NONE, ever. |
-| "Play Online" | `matchmake()` → queue → the server seats you | FIRST contact. Only now are you a counted participant. |
-| Leaving online (back to menu / quit / switch to Bots after being seated) | Tear down the online view, return to the offline menu | `mm.cancel()` — frees the seat so you stop counting toward `minPlayers`. |
+| "Play Online" | `matchmake()` → queue/seat, or `connect()` → ongoing shared world | FIRST contact. Only now are you an online participant. |
+| Leaving online (back to menu / quit / switch to Bots after joining) | Tear down the online view, return to the offline menu | `mm.cancel()` for matchmaking; intentional `room.leave()` for connect. |
 
 **Decisions:**
 - **Every menu action blurs its button before acting.** Otherwise the first gameplay Space/Enter
@@ -196,6 +229,9 @@ fourth who never comes.
   menu/lobby phases (see the game-ui skill).
 - **`matchmake()` is created lazily, on the click — not held from boot.** Keep the handle in a
   variable so you can `cancel()` it; create it inside the "Play Online" handler, not at module load.
+- **`connect()` follows the same commitment rule when this menu exists.** Create the session and
+  network avatar inside the online handler; intentional leave disables the rejoin loop, calls
+  `room.leave()`, removes the online avatar, and returns to the offline world.
 - **Bots/Local touch nothing networked.** They run the exact offline world the menu already booted.
   A player can sit in Bots forever and the online queue never knows they exist — which is the point.
 - **The waiting screen is an online-only, post-commit overlay.** Show it only when

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

@@ -181,17 +181,27 @@ room.inputs.on((fromId, payload) => {
   if (p?.obj && Array.isArray(p.push)) pending.push(p as { obj: string; push: number[] });
 });
 
-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?.isMine) {
+let hostReady: Promise<boolean> | null = null;
+function ensureHostReady() {
+  if (!room.isHost) return Promise.resolve(false);
+  if (hostReady) return hostReady; // single flight: async host ticks never overlap adoption
+  hostReady = (async () => {
+    for (const id of CONTESTED_IDS) {
+      const raw = room.objects.get(id)?.stateRaw; // capture BEFORE claim changes local ownership view
       const result = await room.objects.claimConfirmed(id, { authority: "host" });
-      if (!result.accepted) continue;
-      seedRapierBody(id, view?.stateRaw); // position/rotation/velocity from the wire
+      if (!result.accepted) return false;
+      seedRapierBody(id, raw); // position/rotation/velocity from the wire, NEVER zero
     }
-  }
+    pending.length = 0; // discard intent queued for the previous host/timeline
+    return true;
+  })();
+  return hostReady;
+}
+room.on("host", () => { hostReady = null; void ensureHostReady(); });
+
+room.onHostTick(30, async (dtMs) => {
+  // 1) No physics or publishing until the whole host-owned set is adopted and seeded.
+  if (!(await ensureHostReady())) return;
   // 2) Apply everyone's inputs to the ONE authoritative Rapier world.
   for (const { obj, push } of pending.splice(0)) applyImpulse(obj, push);
   // 3) Step and publish (flat state: numbers + one [x,y,z,w] quaternion).
@@ -206,10 +216,13 @@ room.onHostTick(30, async (dtMs) => {
 });
 const r2 = (v: number) => Math.round(v * 100) / 100; // quantize — floats are JSON bloat
 
-// ---- rendering: identical on every client, host included ----
+// ---- rendering: host draws its live simulation; followers draw the guarded smooth stream ----
 for (const id of CONTESTED_IDS) {
+  if (room.isHost) { drawFromBody(meshOf(id), bodyOf(id)); continue; }
   const view = room.objects.get(id);
-  if (view) meshOf(id).position.set(view.state.x, view.state.y, view.state.z); // auto-smoothed
+  if (view && Number.isFinite(view.state.x) && Number.isFinite(view.state.y) && Number.isFinite(view.state.z)) {
+    meshOf(id).position.set(view.state.x, view.state.y, view.state.z); // auto-smoothed
+  }
 }
 ```
 
@@ -218,6 +231,8 @@ 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.
+- Host election and object ownership are separate. Adoption is one async flight per host term; never
+  issue claims every tick, and never step/publish until every required claim was accepted.
 
 - **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

package/templates/skills/genex-threejs-skill-router/SKILL.md

@@ -90,12 +90,16 @@ execution order.
 **Multiplayer is mandatory routing:** if the game has 2+ players sharing a world, loading
 `$genex-threejs-multiplayer` is **required** before any networking code — the SDK auto-smooths
 remote players **and shared objects**, and gives you server-enforced object ownership (a ball) and
-a room `host` (scores, enemies). Choose the net model before coding: `connect()` is one shared-world
-room; `matchmake()` creates capped queued rooms. Only `matchmake()` requires a server-owned
-`genex.matchmaking` block in `package.json`, reported by preview/publish. Both models accept a fresh
-auth supplier, but their terminal-recovery duties differ, so follow the chosen model's section rather than
-mixing the two. The skill also covers the rules that keep it smooth and its per-genre recipes
-(sports/ball, shooter, co-op).
+a room `host` (scores, enemies). Choose the net model from the player experience before coding:
+`connect()` is one ongoing drop-in world; `matchmake()` forms capped rooms for fresh matches or
+missions with quorum/fair-start/backfill rules. Infer it when clear; ask one plain-language
+ongoing-world-vs-fresh-session question only when both experiences genuinely fit. A Play/Online
+button is always the commitment point for either API; only a truly always-online `connect()` world
+may join/spawn immediately, and then it must not show a fake Play screen. Only `matchmake()` requires
+a server-owned `genex.matchmaking` block in `package.json`, reported by preview/publish. Both models
+accept a fresh auth supplier, but their terminal-recovery duties differ, so follow the chosen model's
+section rather than mixing the two. Run that skill's netcode feel gate before handoff. The skill also
+covers the rules that keep it smooth and its per-genre recipes (sports/ball, shooter, co-op).
 
 ## Real (AI-generated) assets — `npx genex` commands
 

package/templates/skills/genex-threejs-skill-router/references/routing-map.md

@@ -243,4 +243,11 @@ claim-on-touch + a Rapier proxy — the soft handoff glides the ownership change
 **simultaneous** contest (two players pushing one crate against each other — sumo, tug-of-war)
 uses the host-authoritative pattern (`inputs` + `onHostTick`). Both are in that skill's
 host-physics reference.
+Choose the net model from player experience: one ongoing drop-in world uses `connect()`; a fresh
+bounded match/mission with quorum, fair start, teams, backfill, or parallel sessions uses
+`matchmake()`. Infer this when the brief is clear. Ask one experience-level question only when both
+are genuinely plausible — never ask the user to select an SDK API or preset. For either model, a
+Play/Online button is the first relay contact; immediate `connect()` + spawn is valid only when
+loading the game already means joining the always-online world and there is no fake Play screen.
+Before handoff, run the multiplayer skill's netcode feel gate with two distinct identities.
 Use only the APIs that skill documents — do not invent transport methods.