@genex-ai/cli-demo 0.71.0 → 0.74.0-dev.190

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

@@ -27,7 +27,7 @@ in another.
 | Pause | always — opens on the Escape key | 1 — menu backdrop under a dark overlay |
 | Fail / retry | always | 1 — a *graded* variant of the menu screen |
 | Win / next | always | 1 — graded variant, warm |
-| Settings | when there is anything to set | 1 |
+| Settings | always — every game carries the Quality picker (Auto/Low/Medium/High, `$genex-threejs-adaptive-quality`), plus whatever else it has to set | 1 |
 | Lobby / waiting | multiplayer only | 1 over the menu backdrop |
 | HUD | always | 2 — generated sprite HUD (`$genex-ai-hud`), enqueued at this gate for EVERY game; plain CSS is the placeholder until the sprites land, never the final HUD |
 
@@ -79,25 +79,40 @@ lap counter in a game without laps). `--aspect 16:9 --quality high
 --no-wait`, enqueued FIRST of all art; the URL goes into the style-brief
 comment.
 
-**Share it before building on it — actually SHOW the image, don't just ask.**
-When the concept lands, pick it up with `genex wait <id> --open` (or generate it
-with `--open`): it opens in the user's browser AND prints the link. Paste that
-URL as a clickable link in your approval message — a URL is invisible in a
-terminal, and "do you like it?" with no picture in front of the user is the #1
-way this checkpoint fails (they end up digging logs for the file path). Then ask
-ONE structured question — "this is roughly how the game will look: keep it, or
-change something?" — with 2–3 concrete adjustment options. Keep building
-gameplay-neutral work (scaffold, physics, netcode) while waiting, but do NOT
-anchor further art to an unapproved frame. **Approval is a LOOP, not a
-one-shot:** if the user dislikes ANYTHING, regenerate with their exact notes
-(`--candidates 2–3` gives them options to choose from), open + link the new
-frame, and ask again — repeat until they actually approve. Carry every note
+**Share it the moment it lands — queue first, show immediately, never wait.**
+When the concept lands, enqueue the Tier-2 UI jobs and the core asset set
+against it in the same breath — the frame you just generated IS the working
+style until the user says otherwise. Then pick it up with
+`genex wait <id> --open` (or generate it with `--open`): it opens in the
+user's browser AND prints the link. Paste that URL as a clickable link in
+your message — a URL is invisible in a terminal, and "do you like it?" with
+no picture in front of the user is the #1 way this checkpoint fails (they end
+up digging logs for the file path). Ask ONE keep-or-change question — "this
+is roughly how the game will look: keep it, or change something?" — **as
+plain chat text, never via the blocking structured-question tool: a suspended
+turn is a gate, and this question must not gate anything.** Silence is
+acceptance; only explicit notes reopen the style. An unanswered style
+question that parks the art pipeline is how a finished game ships bare walls
+and a placeholder HUD — strictly worse than re-rolling a few assets later.
+**Feedback triggers a LOOP whenever it arrives:** if the user comes back
+disliking ANYTHING — immediately or an hour later — regenerate with their
+exact notes (`--candidates 2–3` gives them options to choose from), open +
+link the new frame, and ask again the same non-blocking way. Carry every note
 forward so each round compounds; if two rounds don't converge, offer 2–3
-distinct directions as a structured question instead of re-rolling blind. The
-HUD mockup, the menu, and every downstream asset wait for a frame the user has
-signed off — a single "meh" is never permission to move on. The same "open it +
-paste the link" rule covers every image the user weighs in on — the menu still,
-the HUD mockup candidates.
+distinct directions instead of re-rolling blind (plain chat, same rule).
+Every shown frame becomes the working style exactly like the first did:
+silence after a shown regeneration accepts THAT frame, and when
+`--candidates` goes unanswered, pick the strongest yourself and say so. When
+the style actually changes, re-anchor the style-carrying art made against
+the old frame: the menu still is re-edited (`--edit`) against the new frame
+and its video re-run once from the new still (`$genex-ai-menu` — a
+user-driven style change re-opens its one-video rule), and the HUD chrome
+re-runs its pipeline from Stage 1 with the new frame as the `--edit` anchor
+(`$genex-ai-hud` — budget the full serial chain; it is the most expensive
+re-anchor in the set). Style-neutral assets (most textures, sfx, models)
+usually survive — judge each in one line. The same "open it + paste the
+link" rule covers every image the user weighs in on — the menu still, the
+HUD mockup candidates.
 
 **The concept anchors STYLE, not truth.** Palette, materials, light, and
 register come from the frame; CONTENT comes from the game contract. When
@@ -241,17 +256,28 @@ document.addEventListener("keydown", (e) => {
 
 - **On the bundled `FollowCamera`, it owns the lock — don't fight it.** Do NOT
   call `document.exitPointerLock()` / `canvas.requestPointerLock()` yourself; that
-  desyncs its aim state (the cue flips wrong). Instead pause/resume through it:
-  `followCam.setPaused(true)` on Escape, `followCam.setPaused(false)` from the
-  Resume click, and read `onAimChange` for the cue. The raw calls above are only
-  for a hand-rolled camera with no bundled controller.
+  desyncs its aim state (the cue flips wrong). Instead pause/resume through it —
+  and bind it **on phase transitions, never per frame**: put
+  `followCam?.setPaused(phase !== "playing")` inside `setPhase()` (below) and it
+  covers everything at once — the BOOT menu parks aim, Escape's
+  `setPhase("paused")` frees the cursor, and the Play/Resume click's
+  `setPhase("playing")` re-locks inside the gesture. Read `onAimChange` for the
+  cue. The raw calls above are only for a hand-rolled camera with no bundled
+  controller.
 - **Degradation is built in.** Where Keyboard Lock is absent (Safari, Firefox) or
   the game isn't fullscreen, the browser still releases pointer lock on Escape —
   so ALSO keep the pointer-lock-loss → pause path (`pointerlockchange`: if
   unlocked while `playing`, `setPhase("paused")`). Escape then always pauses; it
   only *also* drops fullscreen on browsers without the lock — unavoidable there.
-- **Only for immersive/pointer-lock games.** A top-down or menu-driven game never
-  captures the mouse and has no window to shrink — skip all of this.
+- **Skip Keyboard Lock + fullscreen only when the cursor stays a tool.**
+  Cursor-core / top-down / menu-driven games never capture the pointer — skip
+  `enterImmersive` and Keyboard Lock entirely. But ANY game that locks the
+  pointer during play — aim games AND keyboard-only racers/platformers/runners
+  under the lock-or-tool rule (next section) — keeps the Escape → pause path and
+  the `pointerlockchange` fallback (if unlocked while `playing`, pause): without
+  it, Esc frees the cursor while the game keeps running. Keyboard-only games may
+  still skip Keyboard Lock + fullscreen; the lock + pause/resume path is the
+  non-negotiable part.
 - **Dashboard embed:** no setup needed — the platform's game frame grants keyboard
   lock (and pointer lock + fullscreen), so Escape-to-pause works the same inside
   `/world/` + `/draft/` as it does standalone (`<slug>.genex.technology`).
@@ -261,6 +287,34 @@ menu — trackpads feel slower than mice, so let the player tune it. On the bund
 camera the setter is live: `slider.oninput = () => { followCam.aimSensitivity = +slider.value; };`
 (radians per pixel; default `0.0023`, a usable range is ~`0.0008`–`0.005`).
 
+## The cursor during play: locked or a tool
+
+During play the OS cursor is either the gameplay tool (cursor-core: click-to-move,
+tower defense, builders, card/board — it stays visible, that's correct) or it is
+**locked away — including keyboard-only games** (racer, platformer, runner): an
+arrow parked over the action for the whole session is a shipped defect. Games on
+the bundled `FollowCamera` get the lock free (on by default). A hand-rolled game
+locks with ~6 lines, reusing this section's Escape flow:
+
+```ts
+// Once at setup (NOT inside the click handler — a fresh listener on every
+// Resume stacks and multi-fires setPhase on a single unlock):
+document.addEventListener("pointerlockchange", () => {
+  if (!document.pointerLockElement && phase === "playing") setPhase("paused");
+});
+// In the Play/Start/Resume CLICK handler (lock needs a user gesture):
+canvas.requestPointerLock?.();          // hides the cursor, focuses the game
+// Required (not optional): without Keyboard Lock, the browser consumes Esc to
+// exit pointer lock and the keydown never reaches the page — the listener
+// above is what pauses. The Resume click re-locks. Keyboard games need nothing
+// more — no reticle, no aim code; the lock just parks the cursor.
+```
+
+If the lock is genuinely unavailable (a third-party embed without
+`allow="pointer-lock"`), fall back to hiding the idle cursor over the canvas:
+`canvas.style.cursor = "none"` after ~2s without `pointermove`, restored
+instantly on move. Menus and pause screens always keep their cursor.
+
 ## The loader
 
 The loader is the first thing every player sees — a bare "Loading… 3/5" over
@@ -292,6 +346,11 @@ function setPhase(phase: "loading" | "playing" | "paused" | "over" | "won") {
     if (on) s.hidden = false;                       // show immediately, then fade in
     else setTimeout(() => { if (!s.classList.contains("is-on")) s.hidden = true; }, 300);
   }
+  // The camera's lock lifecycle rides the SAME transition — never the render loop
+  // (optional-chained: the camera may not exist yet at the first "loading" call).
+  followCam?.setPaused(phase !== "playing");
+  // (Vehicle games combine conditions instead:
+  //  followCam.setPaused(phase !== "playing" || activeId !== CHARACTER_ID).)
 }
 ```
 
@@ -362,6 +421,19 @@ Order the HUD by what the player loses the game for ignoring:
 - **Contrast against the real scene.** Test text over the brightest AND
   darkest areas of actual gameplay; a soft dark plate or text-shadow beats
   restyling per level.
+- **CSS-shaped corners must survive their contents.** `border-radius`,
+  `clip-path`, and `mask` are all fair ways to shape a panel or button —
+  including a chamfered/notched "hi-tech" corner in pure CSS. What is
+  non-negotiable is the execution: the cut must never shear off anything
+  that sits near the corner (text, padding, the focus ring, a glow) — keep
+  enough inner padding that content clears the cut shape — and the result
+  must be clean, not crooked: no jagged aliased diagonals, no half-clipped
+  borders or shadows, no text colliding with an edge or truncating. The
+  same bar applies to CSS plates. Verify the corners at real sizes over
+  real gameplay. When the art direction wants a genuinely ornamented
+  frame, a generated frame sprite (`$genex-ai-hud` chrome, or a Tier-3
+  9-slice panel) is still the richer tool. The masked-fill HUD reveal and
+  `genex ui` masks remain the other established uses of `mask`/`clip-path`.
 - **One cohesion layer.** A single full-screen vignette div (a subtle radial
   gradient darkening the corners, optionally faint grain) over canvas + UI is
   the cheapest way to make DOM-over-WebGL read as one composed image instead
@@ -372,11 +444,13 @@ Order the HUD by what the player loses the game for ignoring:
   `vUv` grain shimmers.
 - **Desktop first.** Verify at desktop sizes and survive window resizes
   without clipping; don't design phone layouts or test mobile viewports unless
-  the user asks. Exception: touch *input* is wired by default when a recipe
-  fits — a bundled controller's built-in touch controls, or the touch kit +
-  recipes in `$genex-threejs-touch-controls` — behind
-  `navigator.maxTouchPoints > 0`, invisible on desktop, so the shared link
-  isn't dead on a phone (skipping needs a one-line reason, not silence).
+  the user asks. Two exceptions ship by default precisely BECAUSE you don't
+  test on phones: touch *input* when a recipe fits — a bundled controller's
+  built-in touch controls, or the touch kit + recipes in
+  `$genex-threejs-touch-controls` — behind `navigator.maxTouchPoints > 0`,
+  invisible on desktop (skipping needs a one-line reason, not silence); and
+  the adaptive-quality tier at boot (`$genex-threejs-adaptive-quality`), which
+  keeps the shared link from being a dead OR crashing link on a phone.
 
 ## Wire UI to game state, never the reverse
 
@@ -399,6 +473,9 @@ architecture and consume the shared style brief.
 - HUD sprites never enqueued at the gate — the placeholder CSS shipped as the
   final HUD.
 - No pause screen, or a pause that isn't bound to Escape.
+- The OS arrow parked over the action for the whole session in a keyboard-driven
+  game (the cursor is either a gameplay tool or locked away — see the cursor
+  section).
 - A style brief whose fonts were never actually loaded (a system-stack display
   font at runtime).
 - A micro-element (reticle, cue, toast, damage number) left as default CSS
@@ -408,6 +485,12 @@ architecture and consume the shared style brief.
 - Hard-cut phase swaps, a menu whose elements just appear, numbers that
   teleport.
 - A silent menu; a bare "Loading…" over black.
+- The art pipeline parked on an unanswered look question — the question is
+  advisory: queue Tier-2 + the asset set against the shown frame and keep
+  moving; silence is acceptance.
+- A CSS-cut corner (`clip-path`/`mask`) that shears its own content — clipped
+  text or padding, a lost focus ring or glow, a jagged aliased edge — the
+  technique is fine; the sloppy cut is the defect.
 - UI panels covering the player or the thing about to kill them.
 - Layout shifting as numbers grow.
 - A fail state with no visible restart key, or a restart that reloads the page.

package/templates/skills/genex-threejs-game-ui/references/style-capsules.md

@@ -10,7 +10,10 @@ says what it's made of in THIS game.
 
 Every capsule below assumes the base rules from the skill: corners/edges for
 UI, one display + one body font, tabular numerals, contrast plates over
-arbitrary scenes.
+arbitrary scenes, and panel/button corners executed cleanly — `border-radius`,
+a CSS `clip-path`/`mask` shape, or a generated frame all work, as long as the
+cut never clips content (text, padding, glow), stays free of jagged-edge
+artifacts, and text never collides or truncates.
 
 ## Fantasy / action RPG
 

package/templates/skills/genex-threejs-image-pipeline/SKILL.md

@@ -43,6 +43,11 @@ ownership boundaries between whole-scene and effect-local graphs.
 - Build pass toggles and effect-only views before tuning.
 - UI rendered in the same target needs an explicit protection strategy.
 - Do not load all atomic post skills by default. Route only the effects actually requested.
+- Budget the pipeline per device tier (`$genex-threejs-adaptive-quality`):
+  phone pixel budget ≈ 1,000,000 px at DPR ≤ 1.25–1.5, desktop ≈ 1,650,000 px —
+  every full-res pass target multiplies that cost, so phone tiers run the light
+  post level and per-pass resolution scales (0.4–0.5 DPR blurs) are the norm,
+  not an optimization.
 
 ## Routing boundary
 

package/templates/skills/genex-threejs-image-pipeline/references/image-pipeline.md

@@ -2,7 +2,7 @@
 
 Use this reference to compose shared scene buffers, lighting effects, atmosphere, bloom, exposure, tone mapping, grading, and feature-local render targets with explicit ownership.
 
-> **Renderer note:** this reference assumes `WebGPURenderer` + TSL node materials. Check the project's actual renderer first — the Genex scaffold ships vanilla WebGL three.js. On WebGL, adapt the technique with standard materials / `EffectComposer` passes or pick a simpler alternative; never switch renderers mid-project.
+> **Renderer note:** this reference assumes `WebGPURenderer` + TSL node materials. Check the project's actual renderer first — the Genex scaffold ships vanilla WebGL three.js. On WebGL, adapt the technique with standard materials / `EffectComposer` passes or pick a simpler alternative; never switch renderers mid-project. Either way the effect obeys the device tier (`$genex-threejs-adaptive-quality`): expensive passes are desktop-tier, and on WebGPU the per-target MSAA sample count is a runtime knob the governor may drive.
 
 ## Contents
 

package/templates/skills/genex-threejs-lighting-design/SKILL.md

@@ -107,7 +107,11 @@ kill-switch diagnostic.
   whole rig after a tone-mapping change is self-inflicted.
 - Never repair unbalanced light ratios with exposure — fix the lights.
 - Flicker from elapsed time, never per-frame randomness.
-- Dispose lights and their shadow maps with the level that spawned them.
+- Dispose lights and their shadow maps with the level that spawned them — and
+  the rest of the level with them: traverse the outgoing scene and dispose
+  geometry, materials, AND textures separately (three frees nothing; material
+  dispose does not touch textures). Leaked levels march phones toward the
+  OS memory kill — `$genex-threejs-adaptive-quality` owns the budget watch.
 - The rig must read with post off: time of day and where-to-go, before bloom.
 
 ## Routing boundary

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

@@ -536,7 +536,13 @@ fights (many writers). A ball on `objects` glides and has one owner. That's the
   `stateRaw` is the raw latest (hit-tests, discrete values). A reconnect-grace seat remains in this
   map with `connected: false`. `avatarUrl` is that player's verified VRM pick (server-set, `''`
   when unknown) — in a VRM-lane game render each remote with
-  `loadVrm(p.avatarUrl || "./assets/avatar.vrm")`; never publish avatar URLs through `me.set`.
+  `loadVrmClone(p.avatarUrl || "./assets/avatar.vrm")` (the vendored loader's shared-GPU clone:
+  N remotes share one set of geometry/textures instead of re-parsing per player — retarget
+  clips once on `loadVrmClone.base(url)` and play them on each clone's own mixer); never
+  publish avatar URLs through `me.set`. On phone tiers, animate and fully draw only the
+  nearest `tier.remoteAvatarCap` remotes (`$genex-threejs-adaptive-quality`) — freeze the
+  mixer and billboard or hide the rest; a room allows up to 64 players and 64 live avatars
+  is a real phone memory kill on its own.
 - `room.activePlayers` — the connected-only subset of `room.players`; use its size for live quorum.
 - `room.objects` — shared objects nobody owns until claimed (a ball, an NPC):
   - `claim(id)` — **legacy** optimistic request. It flips local ownership immediately and is corrected

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

@@ -275,9 +275,12 @@ room.me.set({
 
 // Remote players: a VISUAL-ONLY avatar — NO Rapier body, NO controller instance for remotes.
 // Build each remote's visual from THEIR OWN model: in a VRM-lane game that is
-// loadVrm(pl.avatarUrl || "./assets/avatar.vrm") — the verified per-player pick the relay
-// replicates ('' = unknown → fall back; deepDispose the model on 'leave'). Never reuse your
-// own avatar file for every remote. Position/rotation from smoothed state; animation from the
+// loadVrmClone(pl.avatarUrl || "./assets/avatar.vrm") — the verified per-player pick the
+// relay replicates ('' = unknown → fall back; deepDispose the clone on 'leave'). The clone
+// shares parsed GPU geometry/textures across remotes with the same file (most rooms: all of
+// them) — retarget clips once against loadVrmClone.base(url).vrm and drive each clone's own
+// AnimationMixer. Never reuse your own avatar OBJECT for a remote (clones, not references).
+// Phone tiers animate only the nearest tier.remoteAvatarCap remotes (adaptive-quality skill). Position/rotation from smoothed state; animation from the
 // synced flags via the avatar's own update(flags, dt). The character-controller skill's
 // animations reference owns the flag set.
 const pl = room.players.get(id)!;

package/templates/skills/genex-threejs-physics-rapier/references/colliders-from-assets.md

@@ -26,6 +26,7 @@ already resolved — constructing a collider before WASM init throws.
 | tall dynamic props, posts | `capsuleCollider` / `cylinderCollider` | stable standing shapes |
 | pickups, triggers, zones | any shape + `{ sensor: true, mass: 0 }` | overlap events, no contact forces |
 | the player, cars, drones | none of the above — `npx genex controller` | controllers own their collider recipes |
+| any prop on a PHONE tier (`$genex-threejs-adaptive-quality`) | prefer `cuboidCollider`/hull over trimesh | trimesh contacts scale with triangle count — a phone CPU/memory tax; keep trimesh for static level geometry only |
 
 ## Explicit primitive helpers
 

package/templates/skills/genex-threejs-screen-space-ambient-occlusion/references/ambient-occlusion.md

@@ -2,7 +2,7 @@
 
 Use this reference for a bounded-cost WebGPU/TSL ambient-visibility pass with half-resolution horizon integration, bent normals, bilateral reconstruction, and directional ambient tint.
 
-> **Renderer note:** this reference assumes `WebGPURenderer` + TSL node materials. Check the project's actual renderer first — the Genex scaffold ships vanilla WebGL three.js. On WebGL, adapt the technique with standard materials / `EffectComposer` passes or pick a simpler alternative; never switch renderers mid-project.
+> **Renderer note:** this reference assumes `WebGPURenderer` + TSL node materials. Check the project's actual renderer first — the Genex scaffold ships vanilla WebGL three.js. On WebGL, adapt the technique with standard materials / `EffectComposer` passes or pick a simpler alternative; never switch renderers mid-project. Either way the effect obeys the device tier (`$genex-threejs-adaptive-quality`): expensive passes are desktop-tier, and on WebGPU the per-target MSAA sample count is a runtime knob the governor may drive.
 
 ## Contents
 

package/templates/skills/genex-threejs-shadow-systems/SKILL.md

@@ -12,6 +12,12 @@ and shadows shimmer, swim, or run out of coverage.
 
 Use a single shadow map only when its receiver region is genuinely bounded. For large moving views, make shadow coverage an explicit spatial hierarchy.
 
+**Phone budgets ride the quality tier** (`$genex-threejs-adaptive-quality`):
+shadow maps ≤1024² on phones (512² on the low tier — a 4096² map alone is
+~67 MB of the phone's whole GPU budget), at most 2 cascades where desktop runs
+4, and `shadowMap.autoUpdate = false` for static scenes (re-render on demand:
+a shadow pass is a full extra scene render every frame otherwise).
+
 ## Cached clipmap workflow
 
 1. Define concentric light-space square levels.

package/templates/skills/genex-threejs-shadow-systems/references/shadow-systems.md

@@ -2,7 +2,7 @@
 
 Use this reference for stable directional shadows across a large procedural scene using committed light-space centers, texel snapping, bounded refresh budgets, cross-level blending, and targeted invalidation.
 
-> **Renderer note:** this reference assumes `WebGPURenderer` + TSL node materials. Check the project's actual renderer first — the Genex scaffold ships vanilla WebGL three.js. On WebGL, adapt the technique with standard materials / `EffectComposer` passes or pick a simpler alternative; never switch renderers mid-project.
+> **Renderer note:** this reference assumes `WebGPURenderer` + TSL node materials. Check the project's actual renderer first — the Genex scaffold ships vanilla WebGL three.js. On WebGL, adapt the technique with standard materials / `EffectComposer` passes or pick a simpler alternative; never switch renderers mid-project. Either way the effect obeys the device tier (`$genex-threejs-adaptive-quality`): expensive passes are desktop-tier, and on WebGPU the per-target MSAA sample count is a runtime knob the governor may drive.
 
 ## Contents
 

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

@@ -15,11 +15,12 @@ map, execution order, and acceptance gate.
 
 | Work needed | Load |
 | --- | --- |
-| shot composition, chase/side/orbit rigs, camera handoffs, projection ownership, pointer look, mouse-aimed action (shooter, FPS/first-person, sniper, turret, crosshair/reticle), mouse-look, floating origins | `$genex-threejs-camera-direction` |
+| shot composition, chase/side/orbit rigs, camera handoffs, projection ownership, pointer look, mouse-aimed action (shooter, FPS/first-person, sniper, turret, crosshair/reticle), mouse-look, hand-rolled steering/pan/look input signs (screen-direction contract), floating origins | `$genex-threejs-camera-direction` |
 | on-foot player movement: walk/run/jump/crouch, third-person character, slopes, stairs, moving platforms, personal VRM animation, directional locomotion, transitions, action motion | `$genex-threejs-character-controller` |
 | a custom generated playable humanoid or Meshy animation coverage beyond UAL: reference-informed A-pose concepts, explicit candidate + 10k-remesh approvals, exact action IDs, same-rig adapter | `$genex-ai-character` + `$genex-threejs-character-controller` |
 | the player drives or flies something: cars, drones, vehicle physics, gearbox, enter/exit between character and vehicle | `$genex-threejs-vehicle-controllers` |
 | playable on phones: touch/mobile input for any game — joystick, virtual buttons, drag zones, per-genre touch recipes, rotate-device overlay — wired by default for every NEW game when a recipe fits (skip with a one-line reason) | `$genex-threejs-touch-controls` |
+| phone-survivable rendering — device tiers, DPR/shadow/post budgets, the runtime quality governor, per-tier asset rungs for generated skyboxes/textures, the Quality picker, dispose-on-swap discipline — **mandatory for every game at boot wiring** | `$genex-threejs-adaptive-quality` |
 | anything falls, collides, gets pushed, or needs physics: Rapier world setup, colliders for meshes and GLBs, collision events | `$genex-threejs-physics-rapier` |
 | launch and docking timelines, procedural transform phases, springs, staging, rotating-frame alignment, debris motion | `$genex-threejs-procedural-animation` |
 | reusable scalar/vector fields, domain warping, causal masks, procedural normals | `$genex-threejs-procedural-fields` |
@@ -58,6 +59,14 @@ map, execution order, and acceptance gate.
 mentions sign-in, saves, progress, per-player state, a persistent world, or
 leaderboards. Multiplayer auth (`getColyseusAuth`) comes from it too.
 
+**Adaptive quality is mandatory routing:** every game wires the device tier at
+boot — `$genex-threejs-adaptive-quality` (three lines: `detectTier()` before the
+renderer, tier-capped `setPixelRatio`, the governor in the loop; generated
+skyboxes/textures load through their rungs). Phones enforce a hard GPU-memory
+kill desktops never show you; the tier is what keeps a phone boot alive while
+desktop keeps the full look. This is a completion gate like the post stack —
+cheap to wire, not a new testing burden (desktop-only verification stands).
+
 **Character-animation routing:** use the existing VRM + UAL character
 controller by default. Use `npx genex character` when the game needs a custom
 generated humanoid or an action unavailable in UAL. Before generating a Meshy
@@ -122,7 +131,11 @@ stack this game ships — read off the concept frame's OWN look (the grade, bloo
 level, haze, grain it already shows) and which post the 2–3 AAA references lean
 on, not a default single bloom; ONE built render-pass effect is the FLOOR
 against no-post for EVERY game, never the target — ship the richness the concept
-implies (the UI vignette div or a CSS canvas filter does not count;
+implies. The floor is TIER-AWARE (`$genex-threejs-adaptive-quality`): on phone
+tiers it is satisfied by the built tone-mapping/output pass with the light
+additions the tier allows (FXAA/vignette), while the full named stack remains
+the desktop floor — never ship the heavy stack undropped to phones (the UI
+vignette div or a CSS canvas filter does not count on any tier;
 `$genex-threejs-image-pipeline` owns ordering when 2+ compose), a decision for
 **every primitive surface** the game builds — walls, barriers, kerbs and
 platforms each get a real texture or a **shader** where that surface wants motion
@@ -204,8 +217,16 @@ concept-driven — a richer first build beats a grey-box one.
   drag-orbit (`pointerLockAim: false`) only with a stated reason (e.g. a
   cursor-heavy UI core). **Never** — cursor-core games (click-to-move, tower
   defense, builder, card/puzzle), orbit showcases, touch-only; these MUST pass
-  `pointerLockAim: false`. The mechanism and the full aim contract live in
-  `$genex-threejs-camera-direction`.
+  `pointerLockAim: false`. Keyboard-only games (racer, platformer) lock too —
+  the cursor is either a gameplay tool or locked away during play. The mechanism
+  and the full aim contract live in `$genex-threejs-camera-direction`.
+- Input direction (always — every game that moves with keys or pointer):
+  D/ArrowRight must move or turn the player screen-RIGHT, mouse-right must turn
+  the view right, drag-pan axes share one convention. The screen-direction
+  contract and verified copy-paste bases live in
+  `$genex-threejs-camera-direction` — hand-rolled steering/pan/look math copies
+  one instead of deriving signs, and the smoke check's input-direction pass
+  verifies it.
 - Art direction follows THIS game's concept. The style examples inside skills
   are examples, not defaults — never default to neon/cyberpunk/synthwave (or any
   other single register) unless the concept calls for it.
@@ -222,7 +243,7 @@ concept-driven — a richer first build beats a grey-box one.
 - Use `$genex-threejs-visual-validation` before declaring graphics/procedural-system
   work done. **Game fast path:** for game tasks that loaded no procedural/visual-system
   skill, done = a screenshot plus an interaction smoke check (load the page, press each
-  control, see the visible response) — don't run the full diagnostic gate — PLUS the
+  control, see the visible response in its labeled direction) — don't run the full diagnostic gate — PLUS the
   floors from the routing-map's acceptance gate: the generated sprite HUD wired in
   (not the CSS placeholder), pause on Escape, the branded loader with its key-art
   background, the brief's fonts actually loaded, the renderer baseline + at least one

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

@@ -52,8 +52,10 @@ Three.js release or branch, and do not blindly copy demo architecture.
    while you build the game. FIRST of all art: the gate's **concept frame** —
    a playable-moment shot (verb + threat + objective in frame, per the
    game-ui gate), shown to the user for a keep-or-change answer the moment
-   it lands; later `--edit`-able generations anchor to it for STYLE while
-   the game contract owns content. Then the `$genex-ai-hud` Stage-1 mockup, enqueued
+   it lands — the answer is advisory, never a gate: the art pipeline starts
+   against the frame as-is, and the game-ui skill owns the re-anchor loop
+   when notes arrive; later `--edit`-able generations anchor to it for STYLE
+   while the game contract owns content. Then the `$genex-ai-hud` Stage-1 mockup, enqueued
    here for EVERY game; and the `$genex-ai-menu` video whenever the menu
    decision is yes (the default for every game — "it's only a draft" is not a
    reason to decide no). Skipping this enqueue is
@@ -180,7 +182,10 @@ Three.js release or branch, and do not blindly copy demo architecture.
    (`$genex-threejs-visual-validation` owns the capture discipline).
 7. Add camera direction when framing, controls, transitions, or scale perception
    affect play — or the game aims with the mouse (shooter/FPS/turret): the
-   step-4 bucket decision executes here.
+   step-4 bucket decision executes here. And before ANY hand-rolled
+   steering/pan/look math: the screen-direction contract (D → screen-right,
+   mouse-right → view right, drag axes one convention) with verified copy-paste
+   bases lives there — signs are copied, never derived.
 8. Add procedural animation when object motion needs authored phases,
    convergence, looping, or deterministic timelines.
 9. Add shared fields before writing multiple independent noise layers.
@@ -191,7 +196,11 @@ Three.js release or branch, and do not blindly copy demo architecture.
     step-4 post plan, not inventing one now. This is a completion gate: the
     named post stack must be BUILT before the game is called done, published,
     or handed off — a game rendering on stock three.js defaults is not done,
-    and the gate does not wait for the word "done" to be said.
+    and the gate does not wait for the word "done" to be said. The stack is
+    tier-gated (`$genex-threejs-adaptive-quality`): full on desktop, the built
+    tone-mapping pass + the tier's light additions on phones — wire the
+    governor's post toggle so phone tiers drop the heavy passes, never ship
+    them undropped.
 12. Once the loop is playable, build the planned interface states via
     `$genex-threejs-game-ui` (HUD, pause on Escape, fail/retry, win, and the
     full loading state grown from the step-6 loader), then `npx genex wait`
@@ -250,7 +259,7 @@ module — a corrupted entry point costs more than the minutes saved.
 
 **Game fast path:** for a game task that loaded no procedural/visual-system skill,
 done = a screenshot plus an interaction smoke check (load the page, press each
-control, assert a visible response — `$genex-threejs-visual-validation` has the
+control, assert a visible response in its labeled direction — `$genex-threejs-visual-validation` has the
 procedure), **plus the UI floor from `$genex-threejs-game-ui` (the generated
 sprite HUD wired in — not the CSS placeholder — pause on Escape, the branded
 loader with its key-art background, the brief's font pair actually loaded)
@@ -277,7 +286,11 @@ A routed Genex scene is incomplete until it exposes:
 - named perceptual parameters for the important visual systems;
 - debug views for generated fields, masks, or passes;
 - a no-post baseline that still communicates the subject;
-- a clear quality tier or render-budget knob when the effect is expensive;
+- a clear quality tier or render-budget knob when the effect is expensive —
+  and for every GAME, the adaptive-quality tier wired at boot
+  (`$genex-threejs-adaptive-quality`): tier-capped pixel ratio, tier shadow
+  budget, the runtime governor in the loop, and generated skybox/texture
+  loads routed through their rungs;
 - when physics or controllers are in play, a fixed-timestep loop: per-frame
   work (platforms, enter/exit, controller updates) runs inside the physics
   world's before-step hook, then the world steps — never in the render loop;
@@ -287,9 +300,12 @@ A routed Genex scene is incomplete until it exposes:
 
 **Publishing IS calling it done.** Before `npx genex publish`, every completion
 gate above must pass — sprite HUD wired, Escape pause working, branded loader
-with its key art, fonts loaded, renderer baseline + one built post effect,
-world dressing placed or validly waived, and the content contract's
-countables present or explicitly re-scoped by the user. If any is still
+with its key art, fonts loaded, renderer baseline + one built post effect
+(tier-aware), the adaptive-quality tier wired at boot, world dressing placed
+or validly waived, and the content contract's countables present or
+explicitly re-scoped by the user. `genex preview`/`publish` print a mobile
+preflight (estimated phone GPU memory vs budget) — treat a warning there as a
+gate item too. If any is still
 pending, say which and publish only after an explicit go-ahead.
 
 Do not invent unavailable Genex service APIs. When preparing a game for Genex

package/templates/skills/genex-threejs-spectral-ocean/references/spectral-ocean.md

@@ -2,7 +2,7 @@
 
 Use this reference for a large, unbounded-looking ocean whose identity comes from directional spectral synthesis, staged inverse FFTs, derivative maps, Jacobian whitecaps, and coherent optical shading.
 
-> **Renderer note:** this reference assumes `WebGPURenderer` + TSL node materials. Check the project's actual renderer first — the Genex scaffold ships vanilla WebGL three.js. On WebGL, adapt the technique with standard materials / `EffectComposer` passes or pick a simpler alternative; never switch renderers mid-project.
+> **Renderer note:** this reference assumes `WebGPURenderer` + TSL node materials. Check the project's actual renderer first — the Genex scaffold ships vanilla WebGL three.js. On WebGL, adapt the technique with standard materials / `EffectComposer` passes or pick a simpler alternative; never switch renderers mid-project. Either way the effect obeys the device tier (`$genex-threejs-adaptive-quality`): expensive passes are desktop-tier, and on WebGPU the per-target MSAA sample count is a runtime knob the governor may drive.
 
 ## Contents
 

package/templates/skills/genex-threejs-touch-controls/SKILL.md

@@ -75,6 +75,10 @@ Pick what matches the game; most games need exactly one or two of these.
   lives on the stick; the static circle is fine for slower games. On the
   bundled character controller, pass it through instead — see
   `$genex-threejs-character-controller` (`joystick: { x: joy.x, y: joy.y }`).
+  Touch axes obey the same screen-direction contract as WASD and the mouse
+  (`$genex-threejs-camera-direction`): stick-right must move the player
+  screen-right, drag-right must turn the view right — a flipped feel is a sign
+  bug in the mapping, never a device quirk.
 - **Camera look → drag zone on the right half.** Default `DragZone()` is
   exactly that; per frame `const { dx, dy } = look.consumeDelta()` then apply
   to yaw/pitch with the same sensitivity scale as the mouse path. Games on the
@@ -149,6 +153,13 @@ z-order stays: drag zone (5) under joystick/buttons (10) under pause menus.
   canvas. If the game also needs taps there (tap to shoot), read them from the
   zone (`onChange` + a small-movement threshold) or shrink the zone.
 
+## Input is half of phone-playable
+
+This skill is INPUT only. A phone that can steer a game that then runs out of
+GPU memory still loses the player — the rendering half (device tiers, DPR and
+shadow budgets, the runtime governor, per-tier asset rungs) lives in
+`$genex-threejs-adaptive-quality` and is wired at boot for every game.
+
 ## When you skip
 
 Say it in one plain line — *"skipped touch controls: the game is

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

@@ -212,6 +212,13 @@ aim" cue stays up, and the next gesture (a click OR any keypress — the walk ke
 count) re-locks automatically. So it recovers on its own; just don't expect the lock
 back on the exact exit frame. Vehicle cameras keep their `alignHeading` behavior.
 
+If the game also has a menu phase (most do), fold both signals into ONE derived
+boolean recomputed from `setPhase` AND `onHandoff` —
+`followCam.setPaused(phase !== "playing" || activeId !== CHARACTER_ID)` — so
+neither wiring overwrites the other's pause. Both call sites fire on real
+transitions only; `setPaused` is idempotent, so an occasional repeated value is
+harmless (but never drive it from the render loop).
+
 ## Multiplayer
 
 Occupancy uses confirmed object ownership — remote players must see who is in what. With