@genex-ai/cli-demo 1.5.1-dev.396 → 1.5.2-dev.398

package/dist/index.js

@@ -985,6 +985,7 @@ async function exists(p) {
 
 // src/lib/agents-contract.ts
 import fs6 from "fs/promises";
+import os4 from "os";
 import path6 from "path";
 var CONTRACT_BEGIN = "<!-- genex:contract:begin (managed by genex \u2014 edits inside this block are overwritten on sync) -->";
 var CONTRACT_END = "<!-- genex:contract:end -->";
@@ -996,7 +997,7 @@ Your agentic capabilities that can boost your creation (all via \`npx genex \u20
 Important note: put soul into your creations, with many details and love. Aim to make them realistic and feel real. Use genex capabilities as an extension, but never limit your imagination \u2014 you are a powerful agent. Use your built-in sub-agents and iteration loops (\`/loop\` or your platform's equivalent) where you need them to reach outstanding results. Verify yourself. Anything you put in front of the player should already feel alive and impressive \u2014 never a bare scene waiting for "later". Build what's still missing before polishing what already works.
 
 1. Load the \`genex-game-director\` skill before starting the requested work. Route from the player's latest clear request: a focused request starts directly without replaying discovery or commissioning unrelated lanes. After ANY context compaction or session resume, re-read this file and \`DESIGN.md\`, re-load the skill for the stage you are executing, and continue from the Build plan's \`Now:\` line \u2014 never from memory alone.
-2. Ask only when one unresolved answer materially changes the work. If the request is clear, do not repeat an interview, confirm the pitch, force a concept round, or ask whole-game-vs-one-part again. For a genuinely broad new game, ask one decision: whole coordinated build or one request-relevant part first. If there is no clear request \u2014 a setup prompt pasted with nothing of their own \u2014 ask in PLAIN CHAT what they want to make, in their own words, and never fill the blank by pitching concepts. That opening question stays in chat on purpose: their reply carries the whole request, including anything they say about HOW you should work, and a menu of options answers a narrower question than the one they need to answer. Once you know what you are building, ask one decision at a time with your built-in question tool with clickable answer options when you have one; use a short plain-chat question otherwise. If the player stays silent after a necessary question, proceed on stated assumptions where reasonable and record each as "assumed \u2014 player didn't answer" in DESIGN.md \u2192 Decisions.
+2. Ask only when one unresolved answer materially changes the work. If the request is clear, do not repeat an interview, confirm the pitch, force a concept round, or ask whole-game-vs-one-part again. For a genuinely broad new game, ask one decision: whole coordinated build or one request-relevant part first. If there is no clear request \u2014 a setup prompt pasted with nothing of their own \u2014 ask in PLAIN CHAT what they want to make, in their own words, and never fill the blank by pitching concepts. Once you know what you are building, ask one decision at a time with your built-in question tool with clickable answer options when you have one; use a short plain-chat question otherwise. If the player stays silent after a necessary question, proceed on stated assumptions where reasonable and record each as "assumed \u2014 player didn't answer" in DESIGN.md \u2192 Decisions.
 3. \`DESIGN.md\` at the project root is the durable design contract AND build plan. Keep three truths distinct: the player's requested outcome, the current \`Now:\` focus, and open commitments. It must carry a \`## Build plan & status\` section with the working mode (\`whole coordinated build\`, \`step by step\`, or \`focused change\`), numbered milestones with status marks, and a \`Now:\` line naming the current one \u2014 a milestone is done only when its work reached a preview. The latest clear request may replace \`Now:\` immediately; it never silently shrinks the requested outcome or deletes unrelated commitments. Keep every decision, assumption, generation id/URL, local output, and wiring state current. When the plan first lands, tell the player in one plain line that you recorded what they asked for in \`DESIGN.md\` and will keep it current.
 4. Use \`genex\` commands to generate art, audio, video, characters, and UI. A local reference image is not a reason to switch tools: pass its file path to genex (\`--edit\` and \`--inpaint\` accept local paths). Don't limit yourself: add details, and mix generated assets with procedural generation to make scenes and games detailed and lively.
 5. When shipping your game / project: building, previewing, and publishing go only through \`genex preview\` / \`genex publish\` \u2014 never load your platform's own site-building, hosting, or deploy skills for this game.
@@ -1017,13 +1018,13 @@ Important note: put soul into your creations, with many details and love. Aim to
 ${CONTRACT_END}
 `;
 var CLAUDE_IMPORT_LINE = "@AGENTS.md";
+var CONTRACT_REGION = /<!-- genex:contract:begin[^\n]*-->[\s\S]*?<!-- genex:contract:end -->/;
 function mergeContractBlock(existing) {
   const block = GENEX_CONTRACT_BLOCK.trimEnd();
   if (existing === null || existing.trim() === "") return `${block}
 `;
-  const region = /<!-- genex:contract:begin[^\n]*-->[\s\S]*?<!-- genex:contract:end -->/;
-  if (region.test(existing)) {
-    return existing.replace(region, block);
+  if (CONTRACT_REGION.test(existing)) {
+    return existing.replace(CONTRACT_REGION, block);
   }
   const cleaned = existing.split("\n").filter(
     (line) => !line.includes("genex:contract:begin") && !line.includes("genex:contract:end")
@@ -1071,10 +1072,75 @@ ${CLAUDE_IMPORT_LINE}
   }
   return changed;
 }
+async function healAncestorContracts(projectDir, stopDir = os4.homedir()) {
+  const findings = [];
+  const stop = path6.resolve(stopDir);
+  let dir = path6.dirname(path6.resolve(projectDir));
+  for (let depth = 0; depth < 20; depth++) {
+    try {
+      let isProject = false;
+      try {
+        await fs6.access(path6.join(dir, ".genex", "project.json"));
+        isProject = true;
+      } catch {
+      }
+      if (!isProject) {
+        const agentsPath = path6.join(dir, "AGENTS.md");
+        let content = null;
+        try {
+          content = await fs6.readFile(agentsPath, "utf8");
+        } catch {
+        }
+        if (content !== null && CONTRACT_REGION.test(content)) {
+          let remainder = content;
+          while (CONTRACT_REGION.test(remainder)) {
+            remainder = remainder.replace(CONTRACT_REGION, "");
+          }
+          if (remainder.trim() === "") {
+            await fs6.unlink(agentsPath);
+            try {
+              const claudePath = path6.join(dir, "CLAUDE.md");
+              if ((await fs6.readFile(claudePath, "utf8")).trim() === CLAUDE_IMPORT_LINE) {
+                await fs6.unlink(claudePath);
+              }
+            } catch {
+            }
+            findings.push({ dir, removed: true });
+          } else {
+            findings.push({ dir, removed: false });
+          }
+        }
+      }
+    } catch {
+    }
+    if (dir === stop) break;
+    const parent = path6.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return findings;
+}
+async function healAncestorContractsAndReport(log, projectDir) {
+  try {
+    for (const f of await healAncestorContracts(projectDir)) {
+      const file = path6.join(f.dir, "AGENTS.md");
+      if (f.removed) {
+        log.plain(
+          `\u{1F9F9} Removed a stray genex build contract from ${file} \u2014 it belongs in each game's folder, and a stale copy above the project misleads agents.`
+        );
+      } else {
+        log.warn(
+          `A stale genex build contract sits inside ${file} next to your own text. Agents read every parent folder's AGENTS.md, so it conflicts with this game's contract \u2014 delete the block between the genex:contract markers there.`
+        );
+      }
+    }
+  } catch {
+  }
+}
 
 // src/lib/updates.ts
 import fs7 from "fs/promises";
-import os4 from "os";
+import os5 from "os";
 import path7 from "path";
 function parseSemver(v) {
   const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(v.trim());
@@ -1179,7 +1245,7 @@ async function syncSkillsForTarget(target, templatesDir = getTemplatesDir(), ver
 }
 async function cleanupLegacyGlobalSkills(log) {
   try {
-    const home = os4.homedir();
+    const home = os5.homedir();
     const [realCwd, realHome] = await Promise.all([
       fs7.realpath(process.cwd()).catch(() => path7.resolve(process.cwd())),
       fs7.realpath(home).catch(() => path7.resolve(home))
@@ -1235,10 +1301,11 @@ async function syncSkills(log) {
     }
     if (refreshed) log.plain(`\u{1F504} Genex skills updated to ${version}`);
     try {
-      await fs7.access(path7.join(process.cwd(), ".genex"));
+      await fs7.access(path7.join(process.cwd(), ".genex", "project.json"));
       if (await writeAgentsContract(process.cwd())) {
         log.plain("\u{1F504} Genex build contract refreshed (AGENTS.md managed block)");
       }
+      await healAncestorContractsAndReport(log, process.cwd());
     } catch {
     }
   } catch {
@@ -1702,6 +1769,7 @@ async function runInit(opts) {
   if (await writeAgentsContract(process.cwd())) {
     log.dim("  wrote the Genex build contract into AGENTS.md (managed block) + CLAUDE.md stub");
   }
+  await healAncestorContractsAndReport(log, process.cwd());
   const apiUrl = getApiUrl(opts.apiUrl);
   const echoIdentity = async () => {
     const email = await fetchSignedInEmail(apiUrl, token);
@@ -2145,7 +2213,7 @@ function relTime(iso) {
 import { spawn as spawn3 } from "child_process";
 import crypto3 from "crypto";
 import fs15 from "fs/promises";
-import os5 from "os";
+import os6 from "os";
 import path14 from "path";
 
 // ../../packages/mobile-scan/src/image-dims.ts
@@ -4688,7 +4756,7 @@ async function pushWorktree(cwd, pushUrl, managed, log, branch = "main") {
     log.error("Couldn't save your game's source \u2014 please try again.");
     return false;
   };
-  const gitDir = await fs15.mkdtemp(path14.join(os5.tmpdir(), "genex-source-"));
+  const gitDir = await fs15.mkdtemp(path14.join(os6.tmpdir(), "genex-source-"));
   const base = { GIT_DIR: gitDir };
   if (urlHasEmbeddedCredentials(pushUrl)) {
     base.GIT_CONFIG_COUNT = "1";
@@ -5618,7 +5686,7 @@ function surfaceNudges(log, s) {
   }
   for (const d of s.depthRange) {
     log.warn(
-      `Camera depth range ${d.detail} (far/near = ${d.ratio.toExponential(1)}) at ${d.where} is past what a 24-bit depth buffer can serve \u2014 touching surfaces will z-fight and flicker, and it reads fine right up until it doesn't. near is the expensive knob (resolvable depth \u2248 z\xB2 / (near \xD7 2^24)), so raise near to the closest the camera can actually get. If the range is genuinely astronomical, that is what WebGLRenderer's logarithmicDepthBuffer is for: genex-threejs-camera-direction.`
+      `Camera depth range ${d.detail} (far/near = ${d.ratio.toExponential(1)}) at ${d.where} is past what a 24-bit depth buffer can serve \u2014 touching surfaces will z-fight and flicker, and it reads fine right up until it doesn't. near is the expensive knob (resolvable depth \u2248 z\xB2 / (near \xD7 2^24)), so raise near to the closest the camera can actually get \u2014 the quality kit's cameraNearFar derives the pair from the world, and spreading depthRendererOptions() into the renderer adds reversed-Z (free precision at distance, works on WebGL and WebGPU alike): genex-threejs-adaptive-quality. If the range is genuinely astronomical, that is what logarithmicDepthBuffer is for (it costs early-Z): genex-threejs-camera-direction.`
     );
   }
 }
@@ -16581,6 +16649,8 @@ var CONTROLLER_FILE_SETS = {
       "quality/governor.ts",
       "quality/pick-asset.ts",
       "quality/gltf-loader.ts",
+      "quality/depth.ts",
+      "quality/context-loss.ts",
       NOTICE
     ],
     // KTX2Loader's basis transcoder (js+wasm) — loaded by PATH at runtime, so
@@ -16589,7 +16659,8 @@ var CONTROLLER_FILE_SETS = {
     skill: "genex-threejs-adaptive-quality",
     sketch: [
       `const tier = detectTier(); // phone-low | phone | desktop-low | desktop \u2014 manual Quality setting wins`,
-      `const renderer = new THREE.WebGLRenderer({ antialias: rendererAntialias(tier, /* willRunPost */ true) });`,
+      `const renderer = new THREE.WebGLRenderer({ antialias: rendererAntialias(tier, /* willRunPost */ true), ...depthRendererOptions() }); // WebGPURenderer takes the same options`,
+      `const { near, far } = cameraNearFar({ closest: 1.5, farthest: 800 }); // derive the camera's depth range from the world, never 0.1/1000 from a docs example`,
       `const gltf = createGltfLoader(renderer); // meshopt + KTX2 decoders; model = await loadModelWithFallback(MODEL_URL, tier, (u) => gltf.loader.loadAsync(u), { ktx2: gltf.ktx2 })`,
       `const gov = new QualityGovernor(tier, { setDprScale: (m) => renderer.setPixelRatio(Math.min(window.devicePixelRatio, tier.dprCap * m)), setShadowQuality: (l) => sun.shadow.mapSize.setScalar(l === 'full' ? tier.shadowMapSize : tier.shadowMapSize / 2) }, renderer);`
     ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "1.5.1-dev.396",
+  "version": "1.5.2-dev.398",
   "description": "Set up your project's agent workspace (.claude/.codex/.cursor in the game folder), authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {

package/templates/controllers/quality/context-loss.ts

@@ -0,0 +1,76 @@
+// Genex adaptive-quality: GPU context-loss guard (renderer-neutral).
+//
+// Phones revoke GPU contexts under memory pressure and on backgrounding;
+// desktops on driver resets. A game that keeps rendering into a lost context
+// reads as frozen — and the recovery dance is fiddly enough that every game
+// used to re-derive it by hand: the WebGL `webglcontextlost` event MUST be
+// preventDefault()ed or the browser never fires `webglcontextrestored` at
+// all, while WebGPU has no events — it exposes a one-shot `device.lost`
+// promise instead, and a lost WebGPU device does not come back (recovery is
+// re-initialising, in practice a reload the game offers the player).
+//
+// Renderer-neutral like depth.ts: structural types, no THREE import — pass
+// either a WebGLRenderer or a WebGPURenderer.
+
+export interface ContextLossHandlers {
+  /** Pause the game: stop the loop and audio, show a "restoring…" line. */
+  pause: () => void;
+  /** Resume after restore — three re-uploads GPU resources on the next
+   *  frame, so nothing else to rebuild. WebGL only: a lost WebGPU device
+   *  never restores (see onWebGpuLost). */
+  resume: () => void;
+  /** WebGPU only, optional: called after `device.lost` (pause() has already
+   *  run). Default: nothing — the paused "restoring…" state stands, and a
+   *  reasonable game offers a reload. */
+  onWebGpuLost?: () => void;
+}
+
+/**
+ * Attach loss/restore handling to whichever renderer the game built.
+ * Returns a detach function (call it if the game tears the renderer down).
+ *
+ *   attachContextLossGuard(renderer, {
+ *     pause: () => (running = false),
+ *     resume: () => (running = true),
+ *   });
+ */
+export function attachContextLossGuard(
+  renderer: {
+    domElement?: HTMLCanvasElement;
+    isWebGPURenderer?: boolean;
+    backend?: { device?: { lost?: Promise<unknown> } };
+  },
+  handlers: ContextLossHandlers,
+): () => void {
+  const canvas = renderer.domElement;
+  let detached = false;
+
+  // WebGPU: one-shot promise, available once the renderer has init()ed.
+  // Guarded chaining — on a WebGL renderer none of these keys exist.
+  const lost = renderer.isWebGPURenderer ? renderer.backend?.device?.lost : undefined;
+  if (lost && typeof lost.then === "function") {
+    lost.then(() => {
+      if (detached) return;
+      handlers.pause();
+      handlers.onWebGpuLost?.();
+    });
+    return () => {
+      detached = true;
+    };
+  }
+
+  // WebGL: DOM events on the canvas. preventDefault() on the lost event is
+  // the load-bearing line — without it the restored event never fires.
+  const onLost = (event: Event): void => {
+    event.preventDefault();
+    handlers.pause();
+  };
+  const onRestored = (): void => handlers.resume();
+  canvas?.addEventListener("webglcontextlost", onLost);
+  canvas?.addEventListener("webglcontextrestored", onRestored);
+  return () => {
+    detached = true;
+    canvas?.removeEventListener("webglcontextlost", onLost);
+    canvas?.removeEventListener("webglcontextrestored", onRestored);
+  };
+}

package/templates/controllers/quality/depth.ts

@@ -0,0 +1,96 @@
+// Genex adaptive-quality: depth precision (z-fighting prevention).
+//
+// Z-fighting — surfaces flickering through each other — has exactly two
+// causes, and only one of them lives in this file:
+//
+//   1. A camera range the depth buffer cannot serve. The docs-example
+//      `near 0.1, far 1000` gets pasted, the world grows to kilometres, `far`
+//      follows and `near` stays — and precision at distance z is roughly
+//      z² / (near × 2²⁴), so the flicker starts at the horizon and creeps in.
+//      Fixed here: derive the pair from the WORLD (`cameraNearFar`) and spend
+//      float precision where big ranges need it (`depthRendererOptions`).
+//   2. Two opaque surfaces genuinely sharing a plane (road quad on ground at
+//      the same y, decal flush on a wall). NO renderer setting can fix that —
+//      give them a real gap (1–2 mm indoors, ~1 cm at city scale), or make the
+//      decal win with `polygonOffset: true, polygonOffsetFactor: -1,
+//      polygonOffsetUnits: -1` (+ depthWrite: false for a flat sticker).
+//      The visual-validation skill's console scanner finds these pairs.
+//
+// Renderer-agnostic ON PURPOSE: no THREE import, no WebGLRenderer type.
+// `WebGPURenderer` takes the exact same options object — reversed-Z is native
+// there; WebGL self-gates on EXT_clip_control and falls back to the standard
+// buffer with a console warning (three r185 behaviour), so spreading these
+// options is never worse than not spreading them.
+
+/**
+ * Options to spread into EITHER renderer constructor:
+ *
+ *   new THREE.WebGLRenderer({ antialias: ..., ...depthRendererOptions() })
+ *   new WebGPURenderer({ ...depthRendererOptions() })
+ *
+ * Reversed-Z maps near→1/far→0, moving distant geometry — the part that runs
+ * out of depth precision first — into the float-dense end of the range. It
+ * keeps early-Z rejection (unlike logarithmicDepthBuffer, which disables the
+ * exact optimization the phone tiers depend on — reach for log depth only when
+ * a single camera genuinely spans planetary ranges, and say so in DESIGN.md).
+ *
+ * Three's own materials and its `packing.glsl` depth helpers are reversed-Z
+ * aware; a third-party post pass doing hand-rolled depth math might not be.
+ * Pass `{ depthReadingPost: true }` if the game ships such a pass (SSAO/DoF
+ * from outside three's examples, soft particles, custom depth fog) and you
+ * haven't verified it under reversed-Z — plain depth is the safe fallback.
+ */
+export function depthRendererOptions(opts?: { depthReadingPost?: boolean }): {
+  reversedDepthBuffer: boolean;
+} {
+  return { reversedDepthBuffer: !opts?.depthReadingPost };
+}
+
+export interface DepthRange {
+  /** Closest the camera can genuinely get to visible geometry, in metres —
+   *  ~0.3 first-person, 1–2 third-person/top-down. Never "0.001 to be safe":
+   *  halving this halves depth precision at EVERY distance in the scene. */
+  closest: number;
+  /** Farthest visible thing — world edge, sky dome radius, or fog far. */
+  farthest: number;
+}
+
+/**
+ * Derive `near`/`far` from what the game actually shows, instead of copying
+ * `0.1 / 1000` from a docs example:
+ *
+ *   const { near, far } = cameraNearFar({ closest: 1.5, farthest: 800 });
+ *   const camera = new THREE.PerspectiveCamera(60, aspect, near, far);
+ *
+ * near sits at half the stated approach (margin against a clipped wall when
+ * the camera grazes one), far just past the stated edge. The 1e6 warning
+ * threshold mirrors the `genex preview` preflight, so the helper and the
+ * platform never disagree about what "too wide" means.
+ */
+export function cameraNearFar(range: DepthRange): { near: number; far: number } {
+  const closest = Math.max(range.closest, 0.01);
+  const near = closest / 2;
+  const far = Math.max(range.farthest, closest * 10) * 1.05;
+  if (far / near > 1e6) {
+    console.warn(
+      `[genex quality] camera range near ${near} / far ${far} is wider than a plain depth buffer serves — ` +
+        `raise 'closest' to what the camera really reaches, or keep reversed-Z on (depthRendererOptions()).`,
+    );
+  }
+  return { near, far };
+}
+
+/**
+ * Re-range a live camera when the world grows (new zone, bigger arena) —
+ * updating `far` alone is how a mid-build world reintroduces the flicker.
+ * Structural type on purpose: works for any camera, imports nothing.
+ */
+export function applyDepthRange(
+  camera: { near: number; far: number; updateProjectionMatrix(): void },
+  range: DepthRange,
+): void {
+  const { near, far } = cameraNearFar(range);
+  camera.near = near;
+  camera.far = far;
+  camera.updateProjectionMatrix();
+}

package/templates/controllers/quality/gltf-loader.ts

@@ -11,6 +11,7 @@
 // renderer so KTX2Loader can probe GPU support; skip it and models simply use
 // the universal @1024 rung.
 import type * as THREE from "three";
+import type { WebGPURenderer } from "three/webgpu";
 import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
 import { KTX2Loader } from "three/addons/loaders/KTX2Loader.js";
 import { MeshoptDecoder } from "three/addons/libs/meshopt_decoder.module.js";
@@ -34,7 +35,10 @@ export interface GenexGltfLoader {
  * false — every load falls back to browser-decodable variants.
  */
 export function createGltfLoader(
-  renderer?: THREE.WebGLRenderer,
+  // Either renderer — the kit never assumes WebGL. KTX2Loader.detectSupport
+  // takes both; a WebGPU game just constructs the loader after `await
+  // renderer.init()` so the backend it probes is the real one.
+  renderer?: THREE.WebGLRenderer | WebGPURenderer,
   opts?: { transcoderPath?: string },
 ): GenexGltfLoader {
   const loader = new GLTFLoader();

package/templates/skills/genex-game-director/SKILL.md

@@ -17,18 +17,12 @@ the project from memory or replay completed discovery.
 
 ## 1. Check capabilities and boundaries once
 
-Look at your available tools:
-
-- **Question tool:** use it only when this skill says a real unresolved fork
-  remains; otherwise continue. Without one, ask one short plain-language
-  question in chat.
-- **Sub-agents:** useful for independent workstreams in a whole coordinated
-  build; never required for focused work.
-- **Browser:** use it to inspect the actual result. Without one, ask the player
-  for the smallest useful visual observation.
-
-Never claim a capability you did not find, and never stall because one is
-missing.
+Check your tools once — question tool, sub-agents, browser — and use what you
+actually found: without a question tool, ask one short plain-language question
+in chat; without a browser, ask the player for the smallest useful visual
+observation. Sub-agents suit independent workstreams in a whole coordinated
+build and are never required for focused work. Never claim a capability you
+did not find, and never stall because one is missing.
 
 Your platform may bundle its own image/video generation and site-building,
 hosting, or deploy skills. **They are not Genex lanes.** All generated art,

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

@@ -46,7 +46,7 @@ npx genex controller quality
 ```
 
 Installs `src/controllers/quality/{tier.ts, governor.ts, pick-asset.ts,
-gltf-loader.ts}` — game-owned code, edit freely — plus the KTX2 basis
+gltf-loader.ts, depth.ts, context-loss.ts}` — game-owned code, edit freely — plus the KTX2 basis
 transcoder (`basis_transcoder.js` + `.wasm`) into `public/assets/` (loaded by
 path at runtime; Vite would drop it anywhere else).
 
@@ -55,22 +55,62 @@ path at runtime; Vite would drop it anywhere else).
 ```ts
 import { detectTier, rendererAntialias } from "./controllers/quality/tier.ts";
 import { QualityGovernor } from "./controllers/quality/governor.ts";
+import { depthRendererOptions, cameraNearFar } from "./controllers/quality/depth.ts";
+import { attachContextLossGuard } from "./controllers/quality/context-loss.ts";
 
 const tier = detectTier(); // phone-low | phone | desktop-low | desktop; manual Quality setting wins
 // Context MSAA is WASTED under an EffectComposer (it multisamples a buffer the
 // composer never reads — the classic weak-MacBook lag recipe). Games with a
-// post stack pass willRunPost=true and get their AA from the composer target:
-const renderer = new THREE.WebGLRenderer({ antialias: rendererAntialias(tier, true) });
+// post stack pass willRunPost=true and get their AA from the composer target.
+// The same options object works on WebGPURenderer — the kit assumes no backend:
+const renderer = new THREE.WebGLRenderer({
+  antialias: rendererAntialias(tier, true),
+  ...depthRendererOptions(), // reversed-Z: distant surfaces stop z-fighting, early-Z kept
+});
 renderer.setPixelRatio(Math.min(window.devicePixelRatio, tier.dprCap));
+// Camera range comes from the WORLD, never from a docs example (0.1/1000):
+const { near, far } = cameraNearFar({ closest: 1.5, farthest: 800 });
+const camera = new THREE.PerspectiveCamera(60, innerWidth / innerHeight, near, far);
 // With post: AA comes from the composer's multisampled target instead —
 const target = new THREE.WebGLRenderTarget(innerWidth, innerHeight, { samples: tier.composerSamples });
 const composer = new EffectComposer(renderer, target);
+// GPU context loss (phones revoke contexts under memory pressure): pause,
+// resume on restore — the guard owns the fiddly event rules for both backends.
+attachContextLossGuard(renderer, { pause: () => (running = false), resume: () => (running = true) });
 ```
 
 `detectTier()` also demotes WEAK desktops (Intel iGPU MacBooks, old integrated
 AMD — desktop GPU strings are unmasked, unlike iOS) to `desktop-low`: DPR 1.5,
 no MSAA, 1024 shadows, light post. The Quality picker still overrides.
 
+## Depth precision (z-fighting)
+
+Flickering surfaces have two causes; `depth.ts` owns the first and names the
+second:
+
+- **Camera range.** Depth precision at distance z is ~`z² / (near × 2²⁴)` —
+  `near` is the expensive knob, and the pasted `0.1 / 1000` that silently grows
+  to `0.1 / 100000` is how most games get horizon flicker. Derive the pair with
+  `cameraNearFar({ closest, farthest })` (closest the camera truly gets; edge of
+  the world), and re-range with `applyDepthRange(camera, …)` when the world
+  grows. `...depthRendererOptions()` in the renderer constructor adds
+  reversed-Z on top: near→1/far→0, so distant geometry lands in the float-dense
+  end. Native on WebGPU; on WebGL three gates it on `EXT_clip_control` and
+  falls back to the standard buffer with a console line, so spreading it is
+  never worse. Three's materials and `packing.glsl` helpers are reversed-aware;
+  only a post pass doing hand-rolled depth math (custom SSAO/DoF/soft
+  particles) needs verifying — pass `{ depthReadingPost: true }` to opt out
+  until you have. `logarithmicDepthBuffer` is NOT the default fix: it disables
+  early-Z rejection (the optimization phone survival leans on) — planetary
+  ranges only, recorded in DESIGN.md.
+- **Two opaque surfaces sharing a plane** — road quad at the ground's exact y,
+  decal flush on a wall. No renderer flag can fix that: give them a real gap
+  (1–2 mm indoors, ~1 cm at city scale), or let the decal win with
+  `polygonOffset: true, polygonOffsetFactor: -1, polygonOffsetUnits: -1` (+
+  `depthWrite: false` for flat stickers). `$genex-threejs-visual-validation`
+  ships a console scanner that lists the exact offending pairs;
+  `$genex-threejs-procedural-assets` carries the authoring rule.
+
 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
@@ -211,12 +251,15 @@ not the player's account. Default Auto.
 ## 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).
+`WebGPURenderer`, keep it (never switch renderers mid-project) — the kit
+assumes no backend. `...depthRendererOptions()` spreads into its constructor
+identically (reversed-Z is native there, no extension gate), and
+`createGltfLoader(renderer)` accepts it — construct the loader after `await
+renderer.init()` so KTX2 probes the real backend. Context loss:
+`attachContextLossGuard` handles both backends (WebGL DOM events; WebGPU's
+one-shot `device.lost`, after which recovery is re-init — offer a reload via
+`onWebGpuLost`). All tier knobs apply identically except `antialias` (WebGPU
+MSAA is per-render-target and CAN change at runtime).
 
 ## Failure conditions
 

package/templates/skills/genex-threejs-camera-direction/references/camera-rigs.md

@@ -393,8 +393,12 @@ surfaces that touch will fight and flicker. The expensive knob is `near`, not
 halving of `near` halves precision at every distance. Set `near` to the closest
 the camera can genuinely get — for a third-person or top-down game that is
 metres, not centimetres — and `far` to the far edge of the world, and the ratio
-takes care of itself. `genex preview` warns when a camera's range is past what a
-plain depth buffer can serve.
+takes care of itself. The quality kit's `depth.ts` owns this for ordinary games:
+`cameraNearFar({ closest, farthest })` derives the pair from the world, and
+`...depthRendererOptions()` in the renderer constructor adds reversed-Z — free
+precision at distance on WebGL and WebGPU alike, keeping the early-Z rejection
+that log depth sacrifices (`$genex-threejs-adaptive-quality`). `genex preview`
+warns when a camera's range is past what a plain depth buffer can serve.
 
 It prewarms pipelines by temporarily aiming at representative bodies, then
 restores both position and quaternion in `finally`.

package/templates/skills/genex-threejs-procedural-assets/SKILL.md

@@ -119,6 +119,19 @@ pass and the object can still read wrong. The fixes:
 - **Where two sub-assemblies meet, terminate one inside the other's wall
   thickness** (clearance math at the widest point, including any bow) —
   butting them leaves a visible reveal from some angle.
+- **No two opaque surfaces share a plane.** A road quad at the ground's exact
+  y, a panel flush on a wall, a rug at floor height — coplanar opaque faces
+  z-fight, and a still screenshot is the one tool guaranteed to miss it. Give
+  every flat member a real offset from the surface beneath (1–2 mm indoors,
+  ~1 cm at city scale); a true decal instead wins the depth test with
+  `polygonOffset: true, polygonOffsetFactor: -1, polygonOffsetUnits: -1` +
+  `depthWrite: false`. Kit pieces butt end to end (faces meeting back-to-back
+  are safe) — they never overlap at the same face. Flicker in the DISTANCE on
+  clean geometry is the camera's depth range instead: derive near/far with the
+  quality kit's `cameraNearFar` and spread `depthRendererOptions()` into the
+  renderer (`$genex-threejs-adaptive-quality`). The
+  `$genex-threejs-visual-validation` console scanner lists offending pairs by
+  name.
 - **Merging beats instancing for small repeats.** Merge everything static that
   shares a material into one buffer and instance only genuine crowds — eight
   moulded ribs cost a whole extra draw call as an `InstancedMesh` and nothing

package/templates/skills/genex-threejs-procedural-vfx/SKILL.md

@@ -1,11 +1,15 @@
 ---
 name: genex-threejs-procedural-vfx
-description: Author procedural real-time VFX for Genex Three.js games, and decide WHERE effects belong — walk the game's moments one by one, the way the visual-direction gate walks its surfaces. Use for particles, trails, plasma, sparks, shockwaves, impacts, dissolving debris, ability effects, reentry wakes, event-timed visuals, effect pools, HDR emission hierarchy, and gameplay-readable spectacle.
+description: Author procedural real-time VFX for Genex Three.js games, and decide WHERE effects belong — walk the game's moments one by one. Methodology for the cast envelope (travel/impact/fade), GPU-simulated particles, parameter-space filaments (lightning, beams, trails, tendrils), pooled dynamic lights, and impact grammar (shake, flash, shockwaves, aging residue). Use for particles, sparks, plasma, shockwaves, ability effects, event-timed visuals, and gameplay-readable spectacle.
 ---
 
 # Genex Three.js Procedural VFX
 
-Build effects from an event envelope, motion field, geometry representation, and shading response. Avoid independent particle emitters that happen to share a color.
+Build effects from an event envelope, motion field, geometry representation, and
+shading response. Avoid independent particle emitters that happen to share a
+color. Everything below is **method, not library**: the same math works as GLSL
+in a `ShaderMaterial` on WebGL and as TSL nodes on WebGPU — pick the game's
+renderer, keep the method.
 
 ## The moment gate — run this BEFORE writing any effect code
 
@@ -45,14 +49,99 @@ fire. That sentence answers the surface gate correctly and the moment gate not a
 all. If a primitive is standing in for an effect, it is a placeholder, whatever
 the comment says.
 
-## Particles do not render round by default
+## The law: dice on the CPU, dimensions in the shader
 
-`new THREE.PointsMaterial({ size, color })` draws every point as a **hard-edged
-camera-facing square**. There is no soft falloff, no roundness, no fade — those
-are things you add. Shipping the default is the "square flying things" look, and
-it is the single most common particle defect in real builds.
+The one decision that separates an effect that looks authored from one that
+looks stapled on. When an effect spawns, capture **only what randomness
+decided** — unitless fractions along the cast, seeds, timestamps. Never a
+metre, radian, or second. Every dimension is resolved each frame from one live
+config object, and inside the shader wherever possible. Three consequences,
+all load-bearing:
+
+- **Effects tune live.** Change a height or spread value and a field that is
+  already standing regrows to match — because nothing captured the old number.
+  Tuning against a paused frame becomes possible, which is where shapes are
+  actually worth judging.
+- **Geometry becomes reusable.** A vertex that carries only `(t, side)` — how
+  far along, which edge — serves a bolt of any length, shape, and width. The
+  same strip is a lightning filament, a beam coil, a tendril, and a trail.
+- **Nothing goes stale.** There is no CPU-side path or cached transform to
+  desynchronize from what the shader draws.
+
+Corollary: **geometry carries parameters, shaders compute shape.** The
+procedural look in strong VFX comes almost entirely from evaluating position,
+silhouette, and color per frame from parameters, not from ever-larger meshes.
+
+## Anatomy of a moment: the envelope
+
+Every event effect — a cast, an explosion, a landing — shares one envelope,
+and building it once keeps every layer synchronized:
+
+- **Phases**: travel → impact → fade. Each phase exposes a normalized 0..1
+  progress; every layer reads `(phase, t)` instead of keeping its own scattered
+  time constants. Retiming the whole effect is then one number per phase.
+- **The front**: advance in metres/second scaled by delta time, eased off the
+  standstill. Key the ease on **elapsed age, not progress** — an ease keyed on
+  progress multiplies the very first step by zero and the front never leaves
+  the caster.
+- **The local frame**: origin, unit direction, `side = direction × up`. Every
+  layer — geometry, particle velocities, decal orientation — places itself in
+  this frame, which is what makes secondary motion read as caused by the event
+  rather than coincident with it.
+- **Reveal, don't scale.** Build the full shape and clip it at the front's
+  progress (discard fragments past `t = progress`, with a bright leading tip).
+  A shape that stretches as it extends crawls and swims; one that is revealed
+  keeps its character while it grows.
+
+## Particles: spawn on the CPU, simulate in the shader
 
-The fix costs eight lines and no generation call:
+A per-frame CPU particle loop is the naive default: it burns main-thread time
+and caps counts in the hundreds. The method that scales to thousands is
+instanced quads whose motion is **analytic** in the vertex stage:
+
+- One instanced quad; per-instance attributes: start position, velocity, spawn
+  time, lifetime, size, seed, spin, tint. The CPU writes these **once per
+  spawn** into a ring buffer (the cursor wraps, so spamming an ability recycles
+  the oldest slots instead of allocating) and uploads only the changed ranges.
+- Position is a pure function of age — exact exponential drag, no integration:
+
+  ```
+  age = now - spawnTime           // dead if age < 0 or age > lifetime
+  pos = start
+      + velocity * (1 - exp(-drag * age)) / drag
+      + 0.5 * gravity * age * age
+  ```
+
+  Frame-rate independence, pause, and slow-motion all come free. Add curl
+  noise of the start position for turbulence; rotate the start offset around a
+  drifting anchor for vortex swirl.
+- **Kill without touching buffers**: a dead particle outputs a position outside
+  the clip volume and the GPU discards the whole quad before rasterization.
+- **Silhouettes are procedural** in the fragment stage, from centered UV:
+  a feathered dot (`smoothstep` on radius) for anything that is light; an
+  fbm-eroded puff for smoke; a velocity-stretched streak for sparks; an
+  angular chip (radius wobbled by `sin(angle * k + seed)`) for debris; a thin
+  ring for shockwaves. No sprite textures required.
+- Color is a 3–4 stop gradient over normalized lifetime (birth → early → late
+  → death); alpha is a fade-in × fade-out pair of smoothsteps.
+- **Blending is a role decision**: additive for anything that IS light —
+  sparks, glitter, glow. Normal blending for smoke and mist, so they genuinely
+  occlude and give the effect depth. A scene made only of additive layers has
+  no darkness in it.
+- Emission rate: accumulate `rate * dt`, emit the whole part, carry the
+  remainder — truncating emits zero at high frame rates and bursts at low
+  ones. Cap the per-frame emit so a one-second hitch cannot dump a thousand
+  particles into a single frame.
+- Emit a travelling effect's particles from several points along its length,
+  not one — a bolt sheds along its whole span, and a single origin makes every
+  batch read as a starburst.
+
+### Particles do not render round by default
+
+`new THREE.PointsMaterial({ size, color })` draws every point as a **hard-edged
+camera-facing square** — no falloff, no fade. Shipping the default is the
+"square flying things" look, the single most common particle defect in real
+builds. For a quick `Points`-based job, the fix is one canvas sprite:
 
 ```ts
 /** A soft round dot drawn into a canvas — no network, no asset, works offline. */
@@ -70,77 +159,101 @@ function dotTexture(size = 64): THREE.Texture {
   t.needsUpdate = true;
   return t;
 }
-
-const material = new THREE.PointsMaterial({
-  map: dotTexture(),            // ← without this every mote is a square
-  color: 0xffb98a,
-  size: 0.06,
-  sizeAttenuation: true,        // near motes bigger than far ones
-  transparent: true,
-  depthWrite: false,            // motes must not occlude each other
-  blending: THREE.AdditiveBlending,
-});
 ```
 
-For a mote with real art (embers with structure, snowflakes, leaves), generate the
-sprite instead — `npx genex image --transparent "single soft round ember, black
-background"` — and use it as `map`. The canvas dot is the right default for
-anything that is just light.
+…set as `map` with `transparent: true`, `depthWrite: false`, additive blending.
+For a mote with real art (embers with structure, snowflakes, leaves), generate
+the sprite instead — `npx genex image --transparent "single soft round ember,
+black background"`. `depthWrite: false` disables the depth **write**, not the
+**test**: a mote fractionally below the floor vanishes, so spawn above the
+surface, not on it.
 
-`depthWrite: false` turns off the depth **write**, not the depth **test**: a
-particle still gets rejected by geometry in front of it. That's what you want —
-but it also means a mote sitting fractionally below the floor vanishes. Spawn
-above the surface, not on it.
+## Filaments: everything long and bright is one strip
 
-## Bursts are pooled, never allocated
+Lightning, beams, energy tendrils, leashes, trails — one parameterization
+covers them all, and it is the purest case of the law above.
 
-A burst that runs `new Points(...)` per explosion allocates during the exact
-frame the player is watching. Pre-build one pool at load, take from it, return on
-death — the same shape the rest of the scene uses for bombs and flames.
+**Geometry**: a ladder of quads whose vertices carry only `(t, side)` — how far
+along the filament, which edge of the strip — with one instance per filament
+(an index attribute). The vertex stage turns that pair into a world position
+every frame by stacking three terms:
 
-```ts
-const N = 240;
-const pos = new Float32Array(N * 3);
-const vel = new Float32Array(N * 3);
-const life = new Float32Array(N);          // seconds remaining; 0 = free
-const geo = new THREE.BufferGeometry();
-geo.setAttribute("position", new THREE.BufferAttribute(pos, 3));
-const points = new THREE.Points(geo, material);
-points.frustumCulled = false;              // positions move; the bounds don't follow
-
-function burst(x: number, y: number, z: number, n = 24, speed = 3): void {
-  let spawned = 0;
-  for (let i = 0; i < N && spawned < n; i++) {
-    if (life[i] > 0) continue;
-    const th = Math.random() * Math.PI * 2;
-    const ph = Math.acos(2 * Math.random() - 1);
-    const s = speed * (0.5 + Math.random() * 0.5);
-    vel[i * 3] = Math.sin(ph) * Math.cos(th) * s;
-    vel[i * 3 + 1] = Math.abs(Math.cos(ph)) * s;   // bias up — debris arcs
-    vel[i * 3 + 2] = Math.sin(ph) * Math.sin(th) * s;
-    pos[i * 3] = x; pos[i * 3 + 1] = y; pos[i * 3 + 2] = z;
-    life[i] = 0.5 + Math.random() * 0.4;
-    spawned++;
-  }
-}
+1. **The axis** — a line from origin to target, optionally bowed by sag. The
+   only term that knows where the cast points.
+2. **The fan** — a constant per-filament offset in the plane perpendicular to
+   the axis, opening from a near-spread at the hand to a far-spread at the
+   target, rolled around the axis by a twist angle. This is what separates one
+   filament from the next.
+3. **The kinks** — octaves of **linearly interpolated** value noise, frequency
+   expressed in kinks per metre (scale by the cast's span so a long bolt kinks
+   as densely as a short one). Linear on purpose: smooth interpolation rounds
+   the corners off, and the corners are the entire reason it reads as
+   lightning rather than as a wobbly tube.
 
-function step(dt: number): void {
-  for (let i = 0; i < N; i++) {
-    if (life[i] <= 0) continue;
-    life[i] -= dt;
-    if (life[i] <= 0) { pos[i * 3 + 1] = -1000; continue; }  // park it offscreen
-    vel[i * 3 + 1] -= 9.8 * dt;                              // gravity
-    pos[i * 3] += vel[i * 3] * dt;
-    pos[i * 3 + 1] += vel[i * 3 + 1] * dt;
-    pos[i * 3 + 2] += vel[i * 3 + 2] * dt;
-  }
-  geo.attributes.position.needsUpdate = true;
-}
-```
+Then:
+
+- **Face the camera without billboards**: tangent by finite difference along
+  `t`; `binormal = normalize(cross(tangent, toCamera))`; offset the vertex by
+  `binormal * side * halfWidth`. The strip keeps its apparent thickness from
+  any angle without ever being a screen-space line.
+- **Pin the ends**: fade the kink amplitude to zero near `t = 0` and `t = 1`.
+  A bolt that lands anywhere other than where it was aimed reads as a bug.
+- **Draw it twice**: a wide soft halo pass under a narrow hot core pass — same
+  geometry, same path, different width and falloff. Glow drawn as real
+  geometry stays attached to every kink; bloom alone detaches from the shape.
+- **Two clocks**: a restrike clock snaps every filament onto a new shape N
+  times a second (`seed = hash(filamentIndex, floor(time * restrike))`) while
+  a crawl clock slides the kink phase continuously in between. Together they
+  stop a held bolt from looking like a static ribbon. Flicker is **quantized**
+  — `brightness = hash(floor(time * flickerSpeed))` — because lightning
+  stutters between brightnesses; a sine "breathes", and reads as decoration.
+
+**A beam is the same idea one dimension up**: a tube whose vertices carry
+`(t, angle)`, drawn three times at three radii — a halo that is nothing but
+rim, a sheath weighted toward its silhouette edges so it reads as hollow, and
+a core weighted the **opposite** way, brightest where the view ray runs down
+the barrel. Rim-weighted outside, axis-weighted inside, both faces adding:
+that is a volume integral, cheaply, and the inversion is why the middle reads
+as a solid rod of light instead of a lit pipe. Helical coils are the filament
+strip bent around the same radius function; a train of shock discs is an
+instanced ring whose phase is `fract(index / count + time * speed)` — a pure
+function of the clock, no queue on the CPU. And keep the noise families apart:
+a beam's noise is smooth and stretched hard along the flow; a bolt's is
+piecewise-linear. A beam that kinks is a bolt.
+
+## Lights are pooled at boot
+
+Adding or removing a dynamic light mid-game changes the lighting program and
+forces the renderer to **recompile every material** — the classic first-cast
+hitch. Create the maximum count at boot (4–6 point lights is plenty), parked
+at zero intensity; acquire on spawn, release on death, and damp intensity
+toward its target so a released light fades instead of cutting. `acquire()`
+returns null when the pool is exhausted — guard every use. Give impacts a
+transient boost added onto the base intensity that decays on its own.
+
+Same family of trap: run the renderer's async shader precompile during the
+loading screen so the first cast never stutters on compile.
+
+## Impact grammar
+
+One impact is several small systems firing from the **same call site** — the
+place the game already plays the explosion sound. That call site is the proof
+the effect is event-driven rather than ambient decoration.
 
-Call `burst()` from the same place the game already plays the explosion sound —
-that call site IS the moment, and it is the proof the effect is event-driven
-rather than ambient decoration.
+- **Shake is trauma, not offset.** Hits add trauma (clamped 0..1);
+  displacement is `trauma²` (perceptually linear for a linear decay), taken
+  from summed sines at incommensurate frequencies — smooth noise reads as
+  weight, white noise reads as jitter. Overlapping hits stack naturally;
+  small hits feel snappy, big ones heavy.
+- **A shockwave** is the ring silhouette from the particle section, expanded
+  over its lifetime, flat on the ground.
+- **Residue that lives** is a pooled ground quad with a noise/distance-field
+  fragment shader aged by one normalized uniform: scorch cools, cracks spread
+  then dim, frost creeps outward. Trap, measured in this class of effect:
+  never sample radial noise on `atan(y, x)` — every radius along a bearing
+  gets the same value and the mark becomes dead-straight spokes, a firework
+  instead of a burn. Sample the noise in the plane and domain-warp the lookup,
+  and the filaments meander and fork.
 
 ## Rules
 
@@ -148,7 +261,12 @@ rather than ambient decoration.
 - Use normalized lifetime curves instead of scattered time constants.
 - Derive secondary motion from the same flow or event direction.
 - Keep bloom as a response to HDR emission, not as the effect's only shape.
-- Pool instances and trails; do not allocate per burst.
+- Pool everything at load — abilities, particles, decals, lights. Nothing is
+  allocated or built during a cast, and a cap retires the oldest cast rather
+  than letting the scene grow without bound.
+- Know your draw-call budget: an instanced filament bundle is 2 draw calls at
+  any filament count; a particle system is 1. If an effect's cost scales with
+  its visual density, restructure it so it doesn't.
 - Expose spawn, simulation, overdraw, and luminance debug views.
 - Include a non-bloom baseline that remains legible.
 - Never ship a `PointsMaterial` without a `map` or `alphaMap` — see above.
@@ -156,8 +274,10 @@ rather than ambient decoration.
 ## Routing boundary
 
 Keep accumulated screen frost, persistent weather/surface state, and ground
-material changes in the request's owning scene system. Impact **residue** on a
-surface (scorch, bullet holes) is a decal — `$genex-ai-image` owns that; the
-spark that throws the residue is this skill, and a hit usually wants both.
-Keep ship-space plasma, generated wakes, sparks, and pooled debris in this
-skill.
+material changes in the request's owning scene system. Impact residue splits
+by whether it must change while standing: residue that ages or rescales live
+(spreading cracks, creeping frost, a cooling scorch) is a procedural decal in
+this skill; static art-directed residue (bullet holes, a painted scorch) is a
+generated decal — `$genex-ai-image` owns that. The spark that throws either
+kind of residue is this skill, and a hit usually wants both. Keep ship-space
+plasma, generated wakes, sparks, and pooled debris in this skill.

package/templates/skills/genex-threejs-visual-validation/SKILL.md

@@ -169,7 +169,7 @@ imports — pass it straight to your JS-eval tool.
 ```js
 (() => {
   const S = window.__scene, MIN_M2 = 1.0;   // judge real faces, not GLB slivers
-  const out = { stretched: [], zfight: [] };
+  const out = { stretched: [], zfight: [], skipped: [] };
   const xf = (e,x,y,z) => [e[0]*x+e[4]*y+e[8]*z+e[12], e[1]*x+e[5]*y+e[9]*z+e[13], e[2]*x+e[6]*y+e[10]*z+e[14]];
   const sub = (a,b) => [a[0]-b[0], a[1]-b[1], a[2]-b[2]];
   const cross = (a,b) => [a[1]*b[2]-a[2]*b[1], a[2]*b[0]-a[0]*b[2], a[0]*b[1]-a[1]*b[0]];
@@ -211,31 +211,64 @@ imports — pass it straight to your JS-eval tool.
   });
   out.stretched.sort((a,b) => b.m2 - a.m2);   // biggest surfaces first
 
-  // opaque depth-writing meshes that interpenetrate AND share a face plane
-  const solid = [];
+  // z-fight: opaque depth-writing faces that LIE IN the same axis-aligned
+  // world plane, facing the SAME way, with overlapping area. Butted solids —
+  // faces meeting back-to-back, opposite normals — are safe and never flagged
+  // (backface culling hides one of the two). Instanced meshes are expanded.
+  const FIGHT_M2 = 0.04, PE = 1e-3;
+  const mul = (A,B,o) => { const r = new Array(16);
+    for (let c = 0; c < 4; c++) for (let w = 0; w < 4; w++)
+      r[c*4+w] = A[w]*B[o+c*4] + A[4+w]*B[o+c*4+1] + A[8+w]*B[o+c*4+2] + A[12+w]*B[o+c*4+3];
+    return r; };
+  const byMesh = [];
   S.traverse(o => {
     const m = Array.isArray(o.material) ? o.material[0] : o.material;
-    if (!o.isMesh || o.isInstancedMesh || !m || m.transparent || m.depthWrite === false) return;
-    if (!o.geometry.boundingBox) o.geometry.computeBoundingBox();
-    const bb = o.geometry.boundingBox, e = o.matrixWorld.elements;
-    const lo = [Infinity,Infinity,Infinity], hi = [-Infinity,-Infinity,-Infinity];
-    for (const cx of [bb.min.x,bb.max.x]) for (const cy of [bb.min.y,bb.max.y]) for (const cz of [bb.min.z,bb.max.z]) {
-      const w = xf(e,cx,cy,cz);
-      for (let i = 0; i < 3; i++) { lo[i] = Math.min(lo[i],w[i]); hi[i] = Math.max(hi[i],w[i]); }
+    if (!o.isMesh || !m || m.transparent || m.depthWrite === false) return;
+    const g = o.geometry, pos = g.attributes.position, idx = g.index;
+    const tris = (idx ? idx.count : pos.count) / 3, insts = o.isInstancedMesh ? o.count : 1;
+    const name = o.name || o.type;
+    if (tris * insts > 300000) { out.skipped.push(name); return; }
+    const mats = [];
+    if (o.isInstancedMesh) { const a = o.instanceMatrix.array, w = o.matrixWorld.elements;
+      for (let i = 0; i < insts; i++) mats.push(mul(w, a, i*16)); }
+    else mats.push(o.matrixWorld.elements);
+    const planes = [];
+    for (const e of mats) for (let t = 0; t < tris; t++) {
+      const ix = [0,1,2].map(k => idx ? idx.getX(t*3+k) : t*3+k);
+      const p = ix.map(i => xf(e, pos.getX(i), pos.getY(i), pos.getZ(i)));
+      const nc = cross(sub(p[1],p[0]), sub(p[2],p[0])), l = len(nc);
+      if (l < 1e-9) continue;
+      for (let k = 0; k < 3; k++) {
+        if (Math.abs(nc[k]/l) < 0.999) continue;      // axis-aligned faces only
+        for (const s of (m.side === 2 ? [1,-1] : [Math.sign(nc[k])])) {  // 2 = DoubleSide
+          const u = (k+1)%3, v = (k+2)%3, c = p[0][k];
+          let pl = planes.find(q => q.k === k && q.s === s && Math.abs(q.c - c) < PE);
+          if (!pl) planes.push(pl = { k, s, c, area: 0, lo:[Infinity,Infinity], hi:[-Infinity,-Infinity] });
+          pl.area += l/2;
+          for (const q of p) { pl.lo[0] = Math.min(pl.lo[0], q[u]); pl.hi[0] = Math.max(pl.hi[0], q[u]);
+                               pl.lo[1] = Math.min(pl.lo[1], q[v]); pl.hi[1] = Math.max(pl.hi[1], q[v]); }
+        }
+      }
+    }
+    let kept = planes.filter(pl => pl.area >= FIGHT_M2);
+    if (kept.length > 500) kept = kept.sort((x,y) => y.area - x.area).slice(0, 500);
+    // overlapping coplanar faces WITHIN one mesh (a floor added twice, merged dups):
+    for (const pl of kept) {
+      const bb = (pl.hi[0]-pl.lo[0]) * (pl.hi[1]-pl.lo[1]);
+      if (pl.area > bb * 1.02 + 1e-6)
+        out.zfight.push({ a: name, b: name + " (itself)", plane: "xyz"[pl.k] + "=" + pl.c.toFixed(3) });
     }
-    solid.push({ o, lo, hi });
+    byMesh.push({ name, planes: kept });
   });
-  const E = 1e-4;
-  for (let i = 0; i < solid.length; i++) for (let j = i+1; j < solid.length; j++) {
-    const A = solid[i], B = solid[j];
-    if ([0,1,2].some(k => Math.min(A.hi[k],B.hi[k]) - Math.max(A.lo[k],B.lo[k]) <= E)) continue;
-    const shared = [];
-    for (const k of [0,1,2]) {
-      if (Math.abs(A.lo[k]-B.lo[k]) < E) shared.push("min."+"xyz"[k]+"="+A.lo[k].toFixed(2));
-      if (Math.abs(A.hi[k]-B.hi[k]) < E) shared.push("max."+"xyz"[k]+"="+A.hi[k].toFixed(2));
+  for (let i = 0; i < byMesh.length; i++) for (let j = i+1; j < byMesh.length; j++)
+    for (const a of byMesh[i].planes) for (const b of byMesh[j].planes) {
+      if (a.k !== b.k || a.s !== b.s || Math.abs(a.c - b.c) >= PE) continue;
+      const du = Math.min(a.hi[0],b.hi[0]) - Math.max(a.lo[0],b.lo[0]);
+      const dv = Math.min(a.hi[1],b.hi[1]) - Math.max(a.lo[1],b.lo[1]);
+      if (du > 0 && dv > 0 && du*dv >= FIGHT_M2)
+        out.zfight.push({ a: byMesh[i].name, b: byMesh[j].name,
+          plane: "xyz"[a.k] + (a.s > 0 ? "+" : "-") + "=" + a.c.toFixed(3), overlapM2: +(du*dv).toFixed(2) });
     }
-    if (shared.length) out.zfight.push({ a:A.o.name||"mesh", b:B.o.name||"mesh", coplanar:shared });
-  }
   return out;
 })()
 ```
@@ -247,16 +280,28 @@ generated GLB's authored UVs produce hundreds of tiny-triangle readings that
 drown the real finding — raise it if a model still floods the list, and note in
 the handoff that you did.
 
-**`zfight` should be empty.** Every entry is two solids that interpenetrate AND
-share a face plane, which will fight and flicker the moment the camera moves.
-
-Both are wiring defects, so fix the wiring: `worldUV` (`$genex-ai-texture`) for
-the first; for the second, stop the solids overlapping — butt the spans end to
-end rather than crossing them at the corners.
+**`zfight` should be empty.** Every entry is two opaque, depth-writing surfaces
+lying IN the same plane, facing the same way, with real shared area — exactly
+the geometry that flickers the moment the camera moves. Flat-on-flat counts (a
+road quad at the ground's exact y, a decal flush on a wall), instanced kit
+pieces are expanded per instance, and an `(itself)` entry means one mesh
+carries overlapping coplanar faces — usually the same floor added twice.
+Butted solids whose faces meet back-to-back are safe and never flagged, so
+keep butting kit pieces end to end. `skipped` names meshes too heavy to scan
+(>300k effective triangles).
+
+Both are wiring defects, so fix the wiring: `worldUV` (`$genex-ai-texture`)
+for the first; for a `zfight` pair, give the surfaces a real gap (1–2 mm
+indoors, ~1 cm at city scale), or let a decal win with `polygonOffset: true,
+polygonOffsetFactor: -1, polygonOffsetUnits: -1` + `depthWrite: false`.
+Near-coplanar shimmer in the DISTANCE with no pair listed here is the camera's
+depth range, not geometry — `cameraNearFar` + `depthRendererOptions()` from
+the quality kit's `depth.ts` own that (`$genex-threejs-adaptive-quality`).
 
 Run against the shipped BomberDome build, this printed `aspect: 102, m2: 17,
-mPerTile: "0.17x17.00"` for the wall tops and four coplanar pairs at
-`max.y=2.40`. Both had been in front of the agent for an hour of screenshots.
+mPerTile: "0.17x17.00"` for the wall tops, and the interpenetrating wall pairs
+sharing their top plane at y=2.40. Both had been in front of the agent for an
+hour of screenshots.
 
 **Grain shimmer — inspect the mechanism, not the pixels.** A pixel diff is
 confounded by the scene's own ambient motion; the deterministic check is to read