@genex-ai/cli-demo 0.69.0-dev.175 → 0.70.0-dev.182

package/templates/controllers/quality/governor.ts

@@ -0,0 +1,147 @@
+// Genex adaptive-quality: the runtime governor (mobile-readiness program).
+// Tiers pick the START; the governor owns the RUNTIME knobs forever — phones
+// thermally throttle after minutes, so a game that benched fine at 0:30
+// degrades at 8:00. Feed it a frame time every frame; wire the callbacks to
+// the runtime-changeable knobs only (DPR, post passes, draw distance, frame
+// cap — NEVER context-creation flags like antialias, those are fixed).
+//
+// Step-down ladder on sustained slowness: DPR ×0.8 → post off → draw distance
+// down → 30fps cap. Step-up is slow (hysteresis) and a step that failed twice
+// is never re-attempted. It also self-reports renderer.info counts to
+// window.__GENEX_QUALITY__ — the crash watchdog attaches them to its beacons,
+// which is how the field data that calibrates the whole program gets its
+// memory signal.
+import type { QualityTier } from './tier.ts';
+
+export interface GovernorCallbacks {
+  /** Apply a DPR multiplier (1 = tier cap). E.g. renderer.setPixelRatio(Math.min(realDpr, tier.dprCap * m)). */
+  setDprScale?: (multiplier: number) => void;
+  /** Toggle the post stack between the tier's level and 'off'. */
+  setPostEnabled?: (enabled: boolean) => void;
+  /** Apply a draw-distance multiplier (1 = tier scale). */
+  setDrawDistanceScale?: (multiplier: number) => void;
+  /** Apply a frame cap (0 = uncapped). Pace to a STABLE 30 over a stuttery 45. */
+  setFrameCap?: (fps: number) => void;
+}
+
+interface RendererInfoLike {
+  info?: { memory?: { textures?: number; geometries?: number } };
+}
+
+const SLOW_WINDOW_MS = 4000; // sustained, not spikes — shader compiles must not trigger steps
+const RECOVER_WINDOW_MS = 20000; // step up slowly (hysteresis)
+const MEM_REPORT_MS = 5000;
+
+export class QualityGovernor {
+  private tier: QualityTier;
+  private steps: Array<{ apply: () => void; revert: () => void; failures: number; pendingRecovery?: boolean }>;
+  private applied = 0;
+  private slowSince: number | null = null;
+  private goodSince: number | null = null;
+  private lastMemReport = 0;
+  private paused = false;
+
+  constructor(tier: QualityTier, callbacks: GovernorCallbacks, renderer?: RendererInfoLike) {
+    this.tier = tier;
+    this.rendererRef = renderer;
+    const c = callbacks;
+    this.steps = [
+      {
+        apply: () => c.setDprScale?.(0.8),
+        revert: () => c.setDprScale?.(1),
+        failures: 0,
+      },
+      {
+        apply: () => c.setPostEnabled?.(false),
+        revert: () => c.setPostEnabled?.(true),
+        failures: 0,
+      },
+      {
+        apply: () => c.setDrawDistanceScale?.(0.6),
+        revert: () => c.setDrawDistanceScale?.(1),
+        failures: 0,
+      },
+      {
+        apply: () => c.setFrameCap?.(30),
+        revert: () => c.setFrameCap?.(this.tier.frameCap),
+        failures: 0,
+      },
+    ];
+    // Visibility lifecycle: a backgrounded game must stop burning GPU/audio on
+    // exactly the thermally-constrained device class. The game's loop should
+    // also pause itself; the governor at minimum stops judging frames.
+    try {
+      document.addEventListener('visibilitychange', () => {
+        this.paused = document.visibilityState !== 'visible';
+        this.slowSince = null;
+        this.goodSince = null;
+      });
+    } catch {
+      /* non-DOM context */
+    }
+  }
+
+  private rendererRef?: RendererInfoLike;
+
+  /** Call once per frame with the frame delta in ms (performance.now() based). */
+  frame(deltaMs: number): void {
+    if (this.paused) return;
+    const now = performance.now();
+    const budgetMs = 1000 / Math.min(this.tier.frameCap, 60) + 8; // ~24ms at 30, ~25ms at 60
+
+    if (deltaMs > budgetMs) {
+      this.goodSince = null;
+      if (this.slowSince == null) this.slowSince = now;
+      else if (now - this.slowSince > SLOW_WINDOW_MS) {
+        this.stepDown();
+        this.slowSince = null;
+      }
+    } else {
+      this.slowSince = null;
+      if (this.goodSince == null) this.goodSince = now;
+      else if (now - this.goodSince > RECOVER_WINDOW_MS) {
+        this.stepUp();
+        this.goodSince = null;
+      }
+    }
+
+    // Memory self-report for the crash watchdog's beacons (field calibration).
+    if (now - this.lastMemReport > MEM_REPORT_MS) {
+      this.lastMemReport = now;
+      try {
+        const mem = this.rendererRef?.info?.memory;
+        if (mem) {
+          (window as Window & { __GENEX_QUALITY__?: { tex?: number; geo?: number } }).__GENEX_QUALITY__ =
+            { tex: mem.textures ?? 0, geo: mem.geometries ?? 0 };
+        }
+      } catch {
+        /* observational only */
+      }
+    }
+  }
+
+  private stepDown(): void {
+    if (this.applied >= this.steps.length) return;
+    const step = this.steps[this.applied]!;
+    // A re-application of a rung whose recovery is still pending means the
+    // revert did NOT hold — that's the failure being counted, never the
+    // successful revert itself.
+    if (step.pendingRecovery) {
+      step.pendingRecovery = false;
+      step.failures++;
+    }
+    step.apply();
+    this.applied++;
+  }
+
+  private stepUp(): void {
+    if (this.applied === 0) return;
+    const step = this.steps[this.applied - 1]!;
+    // Never re-attempt a knob whose recovery failed twice (reverting it put
+    // the game back over budget both times) — it stays applied for the session.
+    if (step.failures >= 2) return;
+    step.pendingRecovery = true;
+    step.revert();
+    this.applied--;
+  }
+}

package/templates/controllers/quality/pick-asset.ts

@@ -0,0 +1,57 @@
+// Genex adaptive-quality: per-tier asset variant selection (mobile-readiness
+// program, Option A+D). Generated assets ship with GUARANTEED downscale rungs
+// in R2 — sibling roles like "skybox-equirect@2048" — so phones can load a
+// ~11 MB sky instead of the 8192x4096 original (~178 MB decoded). Desktop
+// always loads the bare URL: the ladder exists so phones stop dying, never to
+// make desktops uglier.
+//
+// FALLBACK CONTRACT: a rung can be missing (remixed old URLs, an environment
+// whose backfill hasn't run). loadTextureWithFallback retries the bare URL on
+// a rung failure, so the worst case is today's behavior — never a broken boot.
+import type { QualityTier } from './tier.ts';
+
+const GENEX_GENERATIONS_RE = /^https:\/\/assets\.genex\.technology\/generations\/[^/]+\/[^/@]+$/;
+
+/** Rung widths by role family — mirrors the server's ladder (store.ts MOBILE_RUNGS). */
+function rungWidthFor(url: string, tier: QualityTier): number | null {
+  if (tier.name !== 'phone' && tier.name !== 'phone-low') return null;
+  const role = url.split('/').pop() ?? '';
+  if (role === 'skybox-equirect') return tier.name === 'phone-low' ? 2048 : 4096;
+  if (role === 'texture-basecolor' || role === 'image-main' || /^image-alt-\d+$/.test(role)) {
+    return tier.name === 'phone-low' ? 1024 : 2048;
+  }
+  return null;
+}
+
+/**
+ * Resolve the URL a THIS-tier device should load. Non-generated URLs and
+ * desktop tiers pass through untouched; phone tiers get the rung sibling.
+ */
+export function pickAsset(url: string, tier: QualityTier): string {
+  if (!GENEX_GENERATIONS_RE.test(url)) return url;
+  const width = rungWidthFor(url, tier);
+  return width ? `${url}@${width}` : url;
+}
+
+/**
+ * Load an image URL through the ladder with the bare-URL fallback. Use it for
+ * generated skyboxes/textures instead of raw TextureLoader.loadAsync:
+ *
+ *   const texture = await loadTextureWithFallback(
+ *     SKYBOX_URL, tier, (u) => new THREE.TextureLoader().loadAsync(u),
+ *   );
+ */
+export async function loadTextureWithFallback<T>(
+  url: string,
+  tier: QualityTier,
+  load: (resolvedUrl: string) => Promise<T>,
+): Promise<T> {
+  const picked = pickAsset(url, tier);
+  if (picked === url) return load(url);
+  try {
+    return await load(picked);
+  } catch {
+    // Missing rung (old asset, un-backfilled env) — degrade to the original.
+    return load(url);
+  }
+}

package/templates/controllers/quality/tier.ts

@@ -0,0 +1,170 @@
+// Genex adaptive-quality: device-tier detection (mobile-readiness program).
+// Boot-conservative by design — on phones you can recover from ugly, you
+// cannot recover from a jetsam kill, and boot is exactly when iOS kills. The
+// governor (governor.ts) steps quality UP after smooth seconds, so a
+// too-cautious start costs moments of softness, never a crash.
+//
+// Detection honesty: no single signal is trustworthy. iOS masks the WebGL
+// renderer string to "Apple GPU" (screen+DPR+OS-version is the real Apple
+// signal); Android exposes detailed renderer strings (Adreno/Mali) worth a
+// small lookup; the runtime governor measures actual frame times and corrects
+// both directions. All heuristics here only pick the STARTING tier.
+
+export type TierName = 'phone-low' | 'phone' | 'desktop' | 'desktop-high';
+
+export interface QualityTier {
+  name: TierName;
+  /** Cap for renderer.setPixelRatio(Math.min(devicePixelRatio, dprCap)). */
+  dprCap: number;
+  /** WebGL context antialias (context-creation-FIXED — cannot change live). */
+  antialias: boolean;
+  /** Directional/spot shadow map size (0 = shadows off). */
+  shadowMapSize: number;
+  /** 'off' = tone mapping only; 'light' = +FXAA/vignette; 'full' = the named stack. */
+  postLevel: 'off' | 'light' | 'full';
+  /** Multiplier for particle counts / scatter density. */
+  particleScale: number;
+  /** Multiplier for draw distance / fog far. */
+  drawDistanceScale: number;
+  /** Frame target — phones pace to a STABLE 30 over a stuttery 45. */
+  frameCap: number;
+  /** Max remote players fully animated/drawn (multiplayer); rest billboard. */
+  remoteAvatarCap: number;
+}
+
+export const TIERS: Record<TierName, QualityTier> = {
+  'phone-low': {
+    name: 'phone-low',
+    dprCap: 1,
+    antialias: false,
+    shadowMapSize: 512,
+    postLevel: 'off',
+    particleScale: 0.25,
+    drawDistanceScale: 0.5,
+    frameCap: 30,
+    remoteAvatarCap: 4,
+  },
+  phone: {
+    name: 'phone',
+    dprCap: 1.5,
+    antialias: false,
+    shadowMapSize: 1024,
+    postLevel: 'light',
+    particleScale: 0.5,
+    drawDistanceScale: 0.75,
+    frameCap: 60,
+    remoteAvatarCap: 8,
+  },
+  desktop: {
+    name: 'desktop',
+    dprCap: 2,
+    antialias: true,
+    shadowMapSize: 2048,
+    postLevel: 'full',
+    particleScale: 1,
+    drawDistanceScale: 1,
+    frameCap: 60,
+    remoteAvatarCap: 64,
+  },
+  'desktop-high': {
+    name: 'desktop-high',
+    dprCap: 2,
+    antialias: true,
+    shadowMapSize: 2048,
+    postLevel: 'full',
+    particleScale: 1,
+    drawDistanceScale: 1,
+    frameCap: 240,
+    remoteAvatarCap: 64,
+  },
+};
+
+/** Quality setting persisted PER DEVICE (localStorage) — quality is a property
+ *  of the phone, not the player, so it deliberately does not ride account
+ *  state. 'auto' = heuristics + governor. */
+const SETTING_KEY = 'genex:quality';
+export type QualitySetting = 'auto' | 'low' | 'medium' | 'high';
+
+export function getQualitySetting(): QualitySetting {
+  try {
+    const v = localStorage.getItem(SETTING_KEY);
+    if (v === 'low' || v === 'medium' || v === 'high') return v;
+  } catch {
+    /* storage blocked */
+  }
+  return 'auto';
+}
+
+export function setQualitySetting(v: QualitySetting): void {
+  try {
+    localStorage.setItem(SETTING_KEY, v);
+  } catch {
+    /* storage blocked */
+  }
+}
+
+function isTouchDevice(): boolean {
+  try {
+    const coarse = matchMedia('(pointer: coarse)').matches;
+    const touch = navigator.maxTouchPoints > 1;
+    const nav = navigator as Navigator & { userAgentData?: { mobile?: boolean } };
+    const mobileUA = nav.userAgentData
+      ? !!nav.userAgentData.mobile
+      : /Mobi|Android/i.test(navigator.userAgent);
+    return (touch && coarse) || mobileUA;
+  } catch {
+    return false;
+  }
+}
+
+/** Android GPU model → strong-enough-for-'phone' (vs 'phone-low'). Tiny,
+ *  vendored on purpose (no detect-gpu dependency): renderer strings are only
+ *  meaningful on Android/desktop anyway, and the governor corrects mistakes. */
+const STRONG_ANDROID_GPU = /Adreno \(TM\) [67]\d\d|Adreno \(TM\) 8|Mali-G7[18]|Mali-G[89]\d|Immortalis|Xclipse/i;
+
+function androidGpuLooksStrong(): boolean {
+  try {
+    const canvas = document.createElement('canvas');
+    const gl = canvas.getContext('webgl2') || canvas.getContext('webgl');
+    if (!gl) return false;
+    const info = gl.getExtension('WEBGL_debug_renderer_info');
+    const renderer = info ? String(gl.getParameter(info.UNMASKED_RENDERER_WEBGL)) : '';
+    const ext = gl.getExtension('WEBGL_lose_context');
+    if (ext) ext.loseContext(); // free the probe context immediately
+    return STRONG_ANDROID_GPU.test(renderer);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Pick the STARTING tier. Manual setting wins; 'auto' uses heuristics:
+ * - non-touch → desktop
+ * - touch: old OS or small memory signals → phone-low; strong/new → phone
+ * The kit may have clamped devicePixelRatio — prefer its pristine stash.
+ */
+export function detectTier(): QualityTier {
+  const setting = getQualitySetting();
+  if (setting === 'low') return TIERS['phone-low'];
+  if (setting === 'medium') return TIERS.phone;
+  if (setting === 'high') return TIERS.desktop;
+
+  if (!isTouchDevice()) return TIERS.desktop;
+
+  const ua = navigator.userAgent;
+  const kit = (window as Window & { __GENEX_KIT__?: { realDpr?: number } }).__GENEX_KIT__;
+  const dpr = kit?.realDpr ?? window.devicePixelRatio;
+  const isIOS = /iPhone|iPad|iPod/.test(ua) || (navigator.maxTouchPoints > 1 && /Mac/.test(ua));
+
+  if (isIOS) {
+    // iOS version floors device age (iOS 17 ⇒ XS/2018+; screen+DPR refine).
+    const m = ua.match(/OS (\d+)_/);
+    const major = m ? Number(m[1]) : 0;
+    if (major >= 17) return TIERS.phone;
+    return TIERS['phone-low'];
+  }
+  const am = ua.match(/Android (\d+)/);
+  const androidMajor = am ? Number(am[1]) : 0;
+  if (androidMajor >= 13 && (dpr >= 2.5 || androidGpuLooksStrong())) return TIERS.phone;
+  return TIERS['phone-low'];
+}

package/templates/skills/genex-ai-menu/SKILL.md

@@ -83,7 +83,13 @@ npx genex wait <gen-id>
 
 Never wire the clip as a bare `<video loop>` — the residual seam shows every
 cycle. Two stacked `<video>` elements with the same src crossfade at the
-cycle end; any seam disappears deterministically, no regeneration lottery:
+cycle end; any seam disappears deterministically, no regeneration lottery.
+
+**Phone tiers get the poster, not the videos** (`$genex-threejs-adaptive-quality`):
+two preloading 720p decoders while the 3D scene boots is a spike at exactly the
+moment phones get killed for memory. On a phone tier, show the key-art poster
+image (a captured frame of the clip works) and skip `seamlessLoop` entirely —
+or defer ONE non-preloading video until after the first gameplay frame:
 
 ```ts
 /** Deterministic seamless loop: two stacked <video>s crossfade at cycle end. */

package/templates/skills/genex-ai-skybox/SKILL.md

@@ -35,15 +35,23 @@ in local dev, the published game, and remixes).
 
 ## Load it as background + environment
 
-Load the equirect JPG, mark it equirectangular, and use it for both the visible
-background and the lighting:
+Load the equirect JPG through the quality tier's rung ladder, mark it
+equirectangular, and use it for both the visible background and the lighting.
+The bare URL is an 8192×4096 original — ~178 MB decoded, over half a phone's
+GPU budget in one texture — so phones must load the downscale rung the platform
+stores next to every skybox (`$genex-threejs-adaptive-quality`):
 
 ```ts
 import * as THREE from "three";
+import { detectTier } from "./controllers/quality/tier.ts";
+import { loadTextureWithFallback } from "./controllers/quality/pick-asset.ts";
 
 // the URL `npx genex skybox` printed (R2 sends CORS headers, so cross-origin works):
 const SKYBOX_URL = "https://assets.genex.technology/generations/<id>/skybox-equirect";
-const texture = await new THREE.TextureLoader().loadAsync(SKYBOX_URL);
+const tier = detectTier(); // reuse the boot tier if you already have it
+const texture = await loadTextureWithFallback(SKYBOX_URL, tier, (u) =>
+  new THREE.TextureLoader().loadAsync(u),
+);
 texture.mapping = THREE.EquirectangularReflectionMapping;
 texture.colorSpace = THREE.SRGBColorSpace;
 
@@ -51,6 +59,9 @@ scene.background = texture;   // visible sky
 scene.environment = texture;  // image-based lighting on PBR materials
 ```
 
+Desktop gets the original; phones get the `@2048`/`@4096` rung; a missing rung
+falls back to the original automatically — never a broken boot.
+
 For sharper reflections/lighting, pre-filter it with `PMREMGenerator`:
 
 ```ts

package/templates/skills/genex-threejs-adaptive-quality/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: genex-threejs-adaptive-quality
+description: Make a Genex Three.js game phone-survivable with the vendored adaptive-quality kit — device-tier detection, tier-budgeted renderer settings, a runtime governor that steps quality down before phones run out of memory, per-tier asset rungs for generated skyboxes/textures, and a Quality picker in settings. Load for every game at boot wiring time, and whenever a game is heavy, crashes on phones, or gets flagged desktop-only.
+---
+
+# Genex Three.js Adaptive Quality
+
+Phones enforce a hard GPU-memory ceiling desktops don't have: iOS silently
+kills the page when a game allocates too much, and the kill arrives at BOOT —
+exactly when a skybox, models, and the post stack all decode at once. This
+skill wires the vendored quality kit so the game boots conservatively on
+phones, steps quality UP when the device proves smooth, and never gets uglier
+on desktop. **You can recover from ugly; you cannot recover from a killed
+page.**
+
+This is a completion gate like the post stack: every game wires the tier at
+boot before it is called done. It costs three lines, not a testing burden —
+you still verify on desktop only.
+
+## Install
+
+```bash
+npx genex controller quality
+```
+
+Installs `src/controllers/quality/{tier.ts, governor.ts, pick-asset.ts}` —
+game-owned code, edit freely.
+
+## Wire the tier at boot (before renderer construction)
+
+```ts
+import { detectTier } from "./controllers/quality/tier.ts";
+import { QualityGovernor } from "./controllers/quality/governor.ts";
+
+const tier = detectTier(); // phone-low | phone | desktop; manual Quality setting wins
+const renderer = new THREE.WebGLRenderer({ antialias: tier.antialias });
+renderer.setPixelRatio(Math.min(window.devicePixelRatio, tier.dprCap));
+```
+
+The tier owns every budget decision: `dprCap` (1.5 on phones — the single
+biggest framebuffer lever), `antialias` (off on phones; it is fixed at context
+creation and can never change live), `shadowMapSize` (1024 phone / 2048
+desktop), `postLevel` (`'light'` = tone mapping + cheap passes on phones;
+`'full'` = the named stack on desktop), `particleScale`, `drawDistanceScale`,
+`frameCap`, and `remoteAvatarCap` for multiplayer. The exact ladder and which
+knobs may change at runtime vs load time vs never: [references/adaptive-quality.md](references/adaptive-quality.md).
+
+## Wire the governor (runtime — phones throttle over minutes)
+
+```ts
+const governor = new QualityGovernor(tier, {
+  setDprScale: (m) => renderer.setPixelRatio(Math.min(window.devicePixelRatio, tier.dprCap * m)),
+  setPostEnabled: (on) => (composerEnabled = on),
+  setDrawDistanceScale: (m) => (scene.fog!.far = baseFogFar * tier.drawDistanceScale * m),
+}, renderer);
+
+// In the render loop, with the same performance.now() delta the loop already computes:
+governor.frame(deltaMs);
+```
+
+Sustained slow frames step down (DPR ×0.8 → post off → draw distance →
+30 fps cap); twenty smooth seconds step back up; a knob that failed twice
+stays down for the session. It keeps governing forever — thermal throttling
+arrives at minute eight, not second thirty. It also pauses judgment when the
+tab is hidden and publishes memory counts the platform's crash telemetry
+reads; pause your own loop and audio on `visibilitychange` too.
+
+## Generated assets: load through the rungs
+
+Generated skyboxes are 8192×4096 — about 178 MB decoded, over half a phone's
+whole budget in one texture. Every generated image asset ships with downscale
+rungs; phones must load through them:
+
+```ts
+import { detectTier } from "./controllers/quality/tier.ts";
+import { loadTextureWithFallback } from "./controllers/quality/pick-asset.ts";
+
+const texture = await loadTextureWithFallback(SKYBOX_URL, tier, (u) =>
+  new THREE.TextureLoader().loadAsync(u),
+);
+```
+
+Desktop loads the original, phones the `@2048` rung (~11 MB), and a missing
+rung falls back to the original — never a broken boot. The `$genex-ai-skybox`
+and `$genex-ai-texture` skills show the wiring in place.
+
+## Quality picker in settings
+
+The pause/settings screen (see `$genex-threejs-game-ui`) always carries a
+Quality entry: **Auto / Low / Medium / High**, wired to
+`setQualitySetting(...)` from `tier.ts` + a reload or re-tier. Persisted
+per-device in localStorage on purpose — quality is a property of the phone,
+not the player's account. Default Auto.
+
+## Budgets that ride the tier (not separate rules)
+
+- Shadows: `tier.shadowMapSize`, `shadow.autoUpdate = false` for static scenes,
+  at most 2 cascades on phones (`$genex-threejs-shadow-systems`).
+- Post: phone floor is a BUILT tone-mapping/output pass (`postLevel: 'light'`
+  adds FXAA/vignette); SSAO, volumetrics, and DoF are desktop-tier only
+  (`$genex-threejs-skill-router` owns the floor wording).
+- Particles/scatter: multiply counts by `tier.particleScale`; render heavy
+  transparency at half resolution and upsample.
+- Animation: distant mixers update at 1/2–1/4 rate; multiplayer remotes above
+  `tier.remoteAvatarCap` billboard instead of animating
+  (`$genex-threejs-multiplayer`).
+- Physics: phone tiers prefer hull/cuboid colliders for props — trimesh only
+  where gameplay demands it (`$genex-threejs-physics-rapier`).
+- Shaders: default `mediump` (iOS exception: float-texture sampling needs
+  `highp sampler2D`); precompile with `renderer.compileAsync(scene, camera)`
+  during the loader screen so first-frame jank doesn't read as a stall; skip
+  max anisotropy on phones.
+- Disposal: level swaps traverse the outgoing scene and dispose geometry,
+  materials, AND textures (three never frees them for you); watch
+  `renderer.info.memory` while testing — if textures/geometries climb across
+  swaps, you leak toward the kill.
+
+## WebGPU games
+
+The scaffold ships WebGL and stays the default; if this project already uses
+`WebGPURenderer`, keep it (never switch renderers mid-project). Context loss
+differs: WebGL fires `webglcontextlost` events; WebGPU exposes a
+`device.lost` promise — attach a handler that pauses the loop and rebuilds,
+mirroring the scaffold's WebGL pattern. All tier knobs apply identically
+except `antialias` (WebGPU MSAA is per-render-target and CAN change at
+runtime).
+
+## Failure conditions
+
+- Renderer constructed before `detectTier()` → context-creation knobs
+  (antialias) are locked wrong for the session. Tier first, renderer second.
+- Governor wired to context-creation flags → no-op at best. Runtime knobs
+  only: DPR, post toggles, distances, frame cap.
+- Skybox loaded with a bare `TextureLoader.loadAsync(SKYBOX_URL)` on a game
+  that targets phones → ~178 MB decoded; route it through
+  `loadTextureWithFallback`.
+- Quality stepping on every spike → shader compiles read as slowness. The
+  governor requires SUSTAINED slow windows; do not shorten them.
+- Testing quality tiers by resizing the desktop window → tiers key off touch +
+  OS, not viewport. Trust desktop verification plus the preflight report
+  `genex preview` prints.

package/templates/skills/genex-threejs-adaptive-quality/references/adaptive-quality.md

@@ -0,0 +1,105 @@
+# Genex adaptive quality — tiers, knobs, and the governor in depth
+
+Use this reference when tuning the tier ladder, deciding which knob may change
+when, or teaching the governor a game-specific step.
+
+## Why boot-conservative
+
+The phone budget is a hard ceiling that includes GPU memory (textures,
+framebuffers), and the OS kill arrives with no catchable event. Boot is the
+danger window: skybox + models + post targets decode together. So phone tiers
+START one notch below what the heuristics suggest and the governor steps UP
+after ~20 smooth seconds. The cost of guessing low is moments of softness; the
+cost of guessing high is a dead page.
+
+## The tier ladder
+
+| Knob | phone-low | phone | desktop |
+|---|---|---|---|
+| DPR cap | 1.0 | 1.5 | 2 |
+| antialias (context) | off | off | on |
+| Shadow map | 512 (static-cached) | 1024 | 2048 |
+| Post level | tone map only | + FXAA/vignette | full named stack |
+| Skybox rung | @2048 (~11 MB) | @4096 (~45 MB) | original |
+| Texture rung (props) | @1024 | @2048 | original |
+| Particles/scatter | 0.25× | 0.5× | 1× |
+| Draw distance | 0.5× | 0.75× | 1× |
+| Frame target | stable 30 | 60 | 60 |
+| Remote avatars animated | 4 | 8 | all |
+| Prop colliders | hull/cuboid | hull | as designed |
+
+A DPR drop from 3 (raw iPhone) to 1.5 cuts every full-screen surface — color,
+depth, and each post target — to a quarter of the bytes. It is the single
+strongest lever the tier owns.
+
+## The knob split — what may change when
+
+Getting this wrong produces silent no-ops or a session stuck ugly:
+
+- **Context-creation-fixed (never changes live):** `antialias`, `alpha`,
+  `stencil`, `powerPreference` on WebGL. Changing them means a new context and
+  a full re-init — the tier must decide them BEFORE the renderer exists.
+  (WebGPU differs: MSAA is per-render-target sample count and is runtime-
+  changeable.)
+- **Load-time (fixed for the session once fetched):** asset rungs (skybox and
+  texture resolutions), model LOD sets. `pickAsset` decides them from the tier
+  at load; switching later means a re-fetch — treat as fixed.
+- **Runtime-free (the governor's domain):** `setPixelRatio`, post passes on/off
+  and their target resolutions, shadow map size (realloc), draw distance and
+  fog, LOD bias, particle counts, mixer update rates, frame cap, remote-avatar
+  animation count.
+
+## Governor mechanics
+
+- Slow = frame delta over budget for a SUSTAINED window (4 s) — never single
+  spikes, which are usually shader compiles or GC. Precompiling with
+  `renderer.compileAsync` during the loader screen removes most spikes at the
+  source (and keeps first-frame jank from reading as a stall to the platform's
+  telemetry).
+- Step-down order: DPR ×0.8 → post off → draw distance ×0.6 → 30 fps cap.
+  Each step is the cheapest remaining lever with the biggest headroom return.
+- Step-up needs 20 smooth seconds (hysteresis), and a step that had to be
+  re-applied twice is pinned for the session — oscillating quality reads worse
+  than stable-low.
+- The governor never stops: thermal throttling degrades phones after minutes
+  of play, so a boot-time benchmark alone always ends up wrong.
+- A stable 30 fps cap beats a stuttery 40–50: consistent frame pacing reads
+  smoother and halves GPU work per second (heat, battery, memory bandwidth).
+- Backgrounded tab (`visibilitychange`): pause the render loop and audio, not
+  just the governor — a hidden game burning GPU is pure thermal debt on the
+  device class that can least afford it.
+
+## Detection honesty
+
+- Apple devices mask the GPU renderer string ("Apple GPU") — screen dims + DPR
+  + iOS major version are the usable signals there, and the governor corrects
+  the rest from measured frames.
+- Android exposes real renderer strings (Adreno/Mali/Xclipse); the vendored
+  lookup in `tier.ts` promotes strong GPUs to the `phone` tier. It is a
+  heuristic on purpose — extend the regex when field data shows a
+  misclassified family, and let the governor absorb the rest.
+- Never burn a probe context on a memory-strapped phone at play time; the one
+  probe in `tier.ts` runs at boot and frees its context immediately.
+
+## Memory discipline that rides the tier
+
+- Dispose on every level swap: traverse the outgoing scene and call
+  `.dispose()` on geometry, material, AND each material's textures — material
+  dispose does not free textures, and three frees nothing automatically.
+- Watch `renderer.info.memory.{textures,geometries}` across swaps in dev; a
+  monotonic climb is a leak marching toward the OS kill. The governor
+  publishes these counts for the platform's field telemetry.
+- Prefer meshopt/instanced geometry for repeats; `BatchedMesh` batches
+  HETEROGENEOUS static meshes into one draw where instancing (identical
+  meshes only) can't.
+- Half-resolution transparency: render heavy particle/transparency passes to a
+  half-size target and composite up — fill-rate is the phone bottleneck.
+
+## Multiplayer at tier
+
+Remotes are visual-only; with the shared avatar file, `loadVrmClone` gives N
+remotes one set of GPU geometry/textures. Animate and fully draw only the
+nearest `tier.remoteAvatarCap`; beyond it, freeze the mixer and billboard or
+hide. Matchmade games can also declare a lower `maxPlayers` in
+`genex.matchmaking` for phone-heavy audiences — capacity is a server-owned
+knob.