@genex-ai/cli-demo 0.93.0 → 0.94.0-dev.250

package/templates/skills/genex-threejs-game-content/references/content-tables.md

@@ -1,269 +0,0 @@
-# Genex game content — copy-paste systems
-
-Four small modules that turn contract lines into shipped content: an event
-bus, a quest engine, a dialogue walker with quest hooks, and items/economy +
-XP. Copy them, fill the tables, and keep content OUT of engine code — adding
-a quest, an item, or a vendor must always be a table edit.
-
-All snippets are plain vanilla-ts (no enums, no decorators) and assume a
-single shared game-state object `G` you already have (player stats, wallet,
-the scene). Adapt names, not shapes.
-
-## 1. Event bus — the only coupling
-
-```ts
-// events.ts — combat, loot, and movement EMIT; quests and UI SUBSCRIBE.
-type GameEvent =
-  | { type: "enemy:died"; enemyKind: string }
-  | { type: "item:pickup"; item: string; count: number }
-  | { type: "chest:opened"; chestId: string }
-  | { type: "npc:talked"; npc: string }
-  | { type: "zone:entered"; location: string };
-
-type Handler = (e: GameEvent) => void;
-const handlers: Handler[] = [];
-
-export function onEvent(h: Handler): void {
-  handlers.push(h);
-}
-export function emit(e: GameEvent): void {
-  for (const h of handlers) h(e);
-}
-```
-
-## 2. Quest engine — defs are data, progress is events
-
-```ts
-// quests.ts
-import { onEvent } from "./events.ts";
-
-type Objective =
-  | { kind: "kill"; target: string; count: number }
-  | { kind: "collect"; item: string; count: number }
-  | { kind: "reach"; location: string }
-  | { kind: "talk"; npc: string };
-
-type QuestDef = {
-  id: string;
-  giver: string;
-  prereq?: string;
-  title: string;
-  brief: string;
-  turnIn: string; // authored prose for the hand-in moment
-  objective: Objective;
-  rewards: { gold?: number; xp?: number; items?: string[] };
-};
-
-// CONTENT — the whole quest list lives here. Main chain via prereq; the
-// prose is authored, not generated filler. Counts must match the contract.
-export const QUESTS: QuestDef[] = [
-  {
-    id: "q_wolves",
-    giver: "elder",
-    title: "Teeth in the Tall Grass",
-    brief:
-      "Wolves have taken the shepherd's flock and now they circle the palisade at dusk. Thin the pack before someone's child is next.",
-    turnIn: "Five pelts. The flock sleeps easy tonight — and so do we. Take this.",
-    objective: { kind: "kill", target: "wolf", count: 5 },
-    rewards: { gold: 40, xp: 60 },
-  },
-  {
-    id: "q_amulet",
-    giver: "elder",
-    prereq: "q_wolves",
-    title: "What the Crypt Keeps",
-    brief:
-      "Our founder's amulet lies in the old crypt east of the fields. The dead have grown restless around it — bring it back, and mind the narrow dark.",
-    turnIn: "The amulet… after all these years. You have the village's gratitude, and its coin.",
-    objective: { kind: "collect", item: "founder_amulet", count: 1 },
-    rewards: { gold: 80, xp: 120, items: ["potion_health"] },
-  },
-  // …side quests: no prereq, different givers, different objective kinds.
-];
-
-type QuestStatus = "locked" | "available" | "active" | "ready" | "done";
-type QuestState = { status: QuestStatus; progress: number };
-
-export const questState = new Map<string, QuestState>();
-for (const q of QUESTS) {
-  questState.set(q.id, { status: q.prereq ? "locked" : "available", progress: 0 });
-}
-
-const def = (id: string): QuestDef => QUESTS.find((q) => q.id === id)!;
-
-export function accept(id: string): void {
-  const s = questState.get(id)!;
-  if (s.status !== "available") return;
-  s.status = "active";
-  // Contract check "can't dead-end": count pre-acceptance progress where the
-  // fiction allows it (kills already made), or reset knowingly.
-}
-
-export function turnIn(id: string): { gold: number; xp: number; items: string[] } | null {
-  const s = questState.get(id)!;
-  if (s.status !== "ready") return null;
-  s.status = "done";
-  for (const q of QUESTS) {
-    if (q.prereq === id && questState.get(q.id)!.status === "locked") {
-      questState.get(q.id)!.status = "available"; // next chain link opens
-    }
-  }
-  const r = def(id).rewards;
-  return { gold: r.gold ?? 0, xp: r.xp ?? 0, items: r.items ?? [] };
-}
-
-function bump(q: QuestDef, s: QuestState, amount = 1): void {
-  const needed = "count" in q.objective ? q.objective.count : 1;
-  s.progress = Math.min(needed, s.progress + amount);
-  if (s.progress >= needed) s.status = "ready"; // journal + marker flip to "return"
-}
-
-onEvent((e) => {
-  for (const q of QUESTS) {
-    const s = questState.get(q.id)!;
-    if (s.status !== "active") continue;
-    const o = q.objective;
-    if (o.kind === "kill" && e.type === "enemy:died" && e.enemyKind === o.target) bump(q, s);
-    if (o.kind === "collect" && e.type === "item:pickup" && e.item === o.item) bump(q, s, e.count);
-    if (o.kind === "reach" && e.type === "zone:entered" && e.location === o.location) bump(q, s);
-    if (o.kind === "talk" && e.type === "npc:talked" && e.npc === o.npc) bump(q, s);
-  }
-});
-```
-
-Journal UI, the tracked-quest compass marker, and toasts subscribe to the
-same state — inventory them as screen elements at `$genex-threejs-game-ui`'s
-gate. Persist `[...questState]` (plus world side-effects like opened chests)
-in the per-player slot via `$genex-threejs-embed-auth`.
-
-## 3. Dialogue walker — quest states become options
-
-```ts
-// dialogue.ts
-import { QUESTS, questState, accept, turnIn } from "./quests.ts";
-
-type DialogueOption = { label: string; next?: DialogueNode; action?: () => void };
-type DialogueNode = { text: string; options: DialogueOption[] };
-
-// CONTENT — per-NPC roots: greeting + a couple of authored lore branches.
-// Three real lines is the difference between a person and a signpost.
-const ROOTS: Record<string, DialogueNode> = {
-  elder: {
-    text: "Maren watches the road as she talks. “Strangers used to mean trade. Lately they mean trouble.”",
-    options: [
-      {
-        label: "Tell me about this village.",
-        next: {
-          text: "“Three generations behind this palisade. The crypt east of here is older than all of it — and lately, louder.”",
-          options: [],
-        },
-      },
-    ],
-  },
-  // blacksmith, herbalist… — every giver and merchant has a root.
-};
-
-// The whole walker: render node.text + numbered options; a click (or the
-// 1–9 key) runs option.action?.(), then shows option.next or closes. Emit
-// { type: "npc:talked", npc } when a conversation OPENS — that's what "talk"
-// objectives listen for.
-export function pickOption(node: DialogueNode, index: number): DialogueNode | null {
-  const opt = node.options[index];
-  if (!opt) return node;
-  opt.action?.();
-  return opt.next ?? null; // null = close the dialogue panel
-}
-
-export function openDialogue(npc: string): DialogueNode {
-  const root = ROOTS[npc];
-  const options = [...root.options];
-  for (const q of QUESTS) {
-    if (q.giver !== npc) continue;
-    const s = questState.get(q.id)!;
-    if (s.status === "available") {
-      options.unshift({
-        label: `[Quest] ${q.title}`,
-        next: {
-          text: q.brief,
-          options: [
-            { label: "I'll do it.", action: () => accept(q.id) },
-            { label: "Not now." },
-          ],
-        },
-      });
-    } else if (s.status === "active") {
-      options.unshift({ label: `[${q.title}] Remind me.`, next: { text: q.brief, options: [] } });
-    } else if (s.status === "ready") {
-      options.unshift({
-        label: `[Complete] ${q.title}`,
-        next: { text: q.turnIn, options: [] },
-        action: () => {
-          const r = turnIn(q.id);
-          // …grant r.gold / r.xp / r.items through your wallet + inventory.
-        },
-      });
-    }
-  }
-  return { text: root.text, options };
-}
-```
-
-## 4. Items, merchants, XP — the economy that closes
-
-```ts
-// items.ts
-type ItemDef = {
-  id: string;
-  kind: "weapon" | "armor" | "potion" | "quest" | "tome";
-  name: string;
-  price: number; // what merchants charge — the SINK side of the economy
-  stats?: { dmg?: number; armor?: number; heal?: number };
-};
-
-export const ITEMS: ItemDef[] = [
-  { id: "sword_iron", kind: "weapon", name: "Iron Sword", price: 120, stats: { dmg: 18 } },
-  { id: "potion_health", kind: "potion", name: "Health Draught", price: 25, stats: { heal: 40 } },
-  { id: "founder_amulet", kind: "quest", name: "Founder's Amulet", price: 0 },
-  // …the catalog. Price the first upgrade to land right after the first quest's gold.
-];
-
-// Merchant stock is per-NPC data — a second vendor is one more entry.
-export const STOCKS: Record<string, string[]> = {
-  blacksmith: ["sword_iron", "armor_leather"],
-  herbalist: ["potion_health", "potion_mana"],
-};
-
-// XP curve + level rewards: one growth axis, wired to quest/enemy rewards.
-export const xpNext = (level: number): number => Math.round(100 * level ** 1.4);
-export function addXp(player: { level: number; xp: number; maxHp: number; hp: number }, amount: number): void {
-  player.xp += amount;
-  while (player.xp >= xpNext(player.level)) {
-    player.xp -= xpNext(player.level);
-    player.level += 1;
-    player.maxHp += 12;
-    player.hp = player.maxHp; // level-up heals — a reward the player FEELS
-  }
-}
-```
-
-## Seeded placement — bulk content for free
-
-Scatter the non-authored bulk (chests, camps, flavor spawns) with a seeded
-RNG so the world is deterministic across loads and machines:
-
-```ts
-export function seededRng(seed: number): () => number {
-  let s = seed >>> 0;
-  return () => {
-    s = (s * 1664525 + 1013904223) >>> 0;
-    return s / 0xffffffff;
-  };
-}
-// const rng = seededRng(1337): place 10 chests at rng()-driven offsets around
-// locations, skip water/steep slopes via the world's height/biome lookups
-// ($genex-threejs-open-world), and hand-place only the authored few.
-```
-
-Hand-authored where it matters (quest prose, boss mechanics, unique loot),
-tables for the bulk, seeds for the scatter — that split is what lets one
-session ship the whole contract.

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

@@ -1,56 +0,0 @@
----
-name: genex-threejs-image-pipeline
-description: Design the final image pipeline for Genex Three.js games. Use for render-target ownership, depth and normal signals, albedo/history buffers, pass ordering, post-processing composition, AO, bloom, exposure, tone mapping, grading, diagnostics, and avoiding conflicting render effects.
----
-
-# Genex Three.js Image Pipeline
-
-Use this skill only when composing several image-space systems or defining shared buffers. For one effect, load its atomic skill instead.
-
-Load:
-
-- `$genex-threejs-screen-space-ambient-occlusion` for GTAO, bent normals, denoising, or AO application;
-- `$genex-threejs-bloom` for HDR extraction and bloom;
-- `$genex-threejs-exposure-color-grading` for metering, adaptation, tone mapping, LUTs, and output conversion.
-
-The pipeline must expose its signals and ordering. Do not install a pile of effects and tune the final frame blindly.
-
-## Signal order
-
-```text
-scene HDR color + depth + normals + albedo where required
-  → lighting-related screen effects
-  → atmosphere/transparency composition
-  → bloom
-  → exposure
-  → tone mapping
-  → grading
-  → lens/presentation effects
-  → output conversion
-```
-
-Read [references/image-pipeline.md](references/image-pipeline.md)
-for four production pass graphs, their buffer/resolution contracts, and the
-ownership boundaries between whole-scene and effect-local graphs.
-
-## Rules
-
-- Tone-map once.
-- Keep HDR bloom before tone mapping.
-- Meter exposure from a small luminance target, not the final 8-bit screen.
-- Separate direct and indirect light before applying bent-normal ambient tint when possible.
-- Upsample low-resolution effects with depth/normal-aware weights.
-- 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
-
-Use this skill when multiple image-space systems must share buffers, ordering,
-or output ownership. For one isolated effect, use its atomic skill without
-loading this coordinator.

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

@@ -1,197 +0,0 @@
-# Production image-pipeline contracts
-
-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. 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
-
-- production WebGPU pipeline WebGPU graph
-- selective gallery pipeline selective gallery graph
-- atlas-based renderer composer graph
-- Temporal-surface effect-local graph
-- Buffer and ownership rules
-- Resolution policies
-- Failure analysis
-- Diagnostics
-
-
-## production WebGPU pipeline WebGPU graph
-
-When GTAO is enabled, the scene pass writes MRT:
-
-```text
-output HDR color
-view-space normal
-diffuse albedo
-depth
-```
-
-Graph:
-
-```text
-scene MRT
-  -> reduced GTAO + bent normal
-  -> full-resolution bilateral/lighting composite
-  -> atmosphere
-  -> bloom
-  -> adapted exposure
-  -> renderOutput / tone map
-  -> 3D LUT
-  -> FXAA
-```
-
-Near/far values, environment intensity, and environment texture remain
-updateable inputs. AO is applied through its dedicated composite rather than
-blindly multiplying the final image.
-
-The atmosphere pass reconstructs view/world position from depth,
-classifies sky, and owns aerial haze, height fog, sun disc/shaft, lens flare,
-and distance grading. Its optional post-process cloud shadow is explicitly
-disabled in its configuration, avoiding duplicate ownership with material
-lighting.
-
-## selective gallery pipeline selective gallery graph
-
-The gallery owns three composers:
-
-```text
-neon selective bloom
-chandelier selective bloom
-base + final additive composite + OutputPass
-```
-
-Selective renders use layer membership plus temporary black material
-substitution with `try/finally` restoration. CSS3D content is rendered by a
-separate renderer after WebGL when invalidated.
-
-Shadows use VSM and manual invalidation:
-
-```text
-shadowMap.autoUpdate = false
-shadowMap.needsUpdate = true only after relevant scene/light changes
-```
-
-This is a bounded-scene optimization. It depends on every moving caster and
-light correctly invalidating the cache.
-
-## atlas-based renderer composer graph
-
-atlas-based renderer performs a separate depth prepass into a depth-stencil target before
-the composer:
-
-```text
-depth prepass target
-main render
-SSAO
-volumetric lighting
-bloom
-lens flare
-fog/color grading
-```
-
-The depth target uses nearest filtering and a
-`DepthStencilFormat`/`UnsignedInt248Type` depth texture. Every depth consumer
-receives that same texture.
-
-The composer recalculates effective pixel dimensions from renderer pixel ratio
-and resizes the depth target and all passes together.
-
-The composer can exist alongside another application post path. Verify the
-actual render-loop call path before claiming that this graph owns runtime
-output.
-
-## Temporal-surface effect-local graph
-
-The temporal frost graph is not a whole-scene post stack. It is a
-self-contained material effect:
-
-```text
-scene at full resolution
-  -> vertical blur at 0.4 DPR
-  -> horizontal blur at 0.4 DPR
-  -> frost composite at full resolution
-  -> pointer history write/swap at full resolution
-  -> final normal/refraction output
-```
-
-Three static procedural texture targets render once. This is a feature-local
-example of mixing persistent, static, low-resolution, and full-resolution
-signals in one feature.
-
-## Buffer and ownership rules
-
-Before implementation, write:
-
-| Signal | Producer | Consumers | Space/format | Resolution | History |
-| --- | --- | --- | --- | --- | --- |
-| HDR scene | scene pass | AO/atmosphere/bloom | linear HDR | full | no |
-| depth | scene or prepass | AO/fog/flare | renderer-defined | full | no |
-| normal | MRT/geometry | AO composite | view space | full | no |
-| albedo | MRT | indirect composite | linear | full | no |
-| bloom contributions | selective passes | final composite | HDR | full/pyramid | no |
-| exposure | meter | final color | scalar | 64x36 source | adapted |
-| interaction | ping-pong pass | frost/output | half-float | full | yes |
-
-Every signal has one producer. If a scene pass already owns depth and normal,
-do not add an uncoordinated duplicate prepass without measuring the reason.
-
-## Resolution policies
-
-selective gallery pipeline caps DPR from both device and pixel budget:
-
-```text
-mobile budget = 1,000,000 pixels, max DPR 1.25
-desktop budget = 1,650,000 pixels, max DPR 1.5
-minimum DPR = 1
-budget DPR = sqrt(pixelBudget / CSS pixel count)
-```
-
-All composers receive the same selected DPR and CSS size.
-
-The temporal frost graph instead gives individual passes fixed roles:
-
-```text
-blur and coarse noise = 0.4 DPR
-composite, history, output = display DPR
-```
-
-Choose global DPR budgeting for scene cost and per-pass scaling for effect
-bandwidth. They solve different problems.
-
-## Failure analysis
-
-- production WebGPU pipeline API names are version-sensitive; `PostProcessing` was renamed
-  and deprecated in favor of `RenderPipeline` in current Three.js history.
-- selective gallery pipeline selective bloom renders the scene multiple times.
-- selective gallery pipeline manual shadow invalidation can freeze unregistered motion.
-- atlas-based renderer depth prepass renders regular scene materials, not an explicit depth
-  override; verify transparent and alpha-tested behavior.
-- atlas-based renderer composer may not be the active runtime path.
-- The frost blur has a zero-weight division risk and pointer decay is frame
-  based.
-- None of these graphs provides a complete velocity/motion-vector
-  contract for general temporal effects.
-- Do not advertise velocity ownership or TAA merely because a generic pipeline
-  could include them.
-
-## Diagnostics
-
-Expose a graph inspector or equivalent stable views:
-
-```text
-scene HDR
-depth raw and reconstructed
-normal/albedo MRT
-GTAO and bent normal
-atmosphere only
-each selective bloom contribution
-exposure meter and current exposure
-pre/post tone map and LUT
-frost static/history/composite targets
-pass resolution, format, memory, and GPU time
-manual invalidation state
-```
-
-The pipeline is accepted only when every enabled pass has a named input,
-output, owner, resolution, and disable path.

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

@@ -1,144 +0,0 @@
----
-name: genex-threejs-lighting-design
-description: Light Genex Three.js games from visible causes, and decide WHERE light belongs — walk the scene's sources one by one, the way the visual-direction gate walks surfaces and the moment gate walks moments. Use for light rigs, sun/moon key lights, practical lights (campfire, torch, neon, lava), emissive-to-light coupling, light shafts and visible beams, fog mood, gameplay light signals, flicker, light budgets, and scenes that read flat or uniformly lit.
----
-
-# Genex Three.js Lighting Design
-
-Light from causes — every light in the frame is the visible consequence of
-something the player can point at. Avoid the uniform ambient wash that lights
-a cave like an office.
-
-## The source gate — run this BEFORE writing any lighting code
-
-The visual-direction gate walks **surfaces**; the moment gate walks
-**moments**. Light lives on neither — it lives on **sources**: what the sky
-pours in and what the fiction burns, glows, or screens. Walk the sources the
-same way, and decide each one.
-
-List the sources the scene contract already names — never invent them. Three
-places to look:
-
-- **the sky** — day, night, overcast, underground, deep space? That one answer
-  sets the rig: a warm sun key with cool sky fill, a dim hard moon, or no sky
-  at all — a cave is keyed by its practicals;
-- **the fiction's emitters** — campfire, torch, lava, neon sign, a monitor,
-  headlights, a portal, a crack of daylight in the roof;
-- **the gameplay signals** — the objective beacon, the telegraph, the
-  checkpoint. Light is information the player navigates by, and it is the
-  cheapest wayfinding you own.
-
-When gameplay needs light where the fiction names no source, add the cause
-first — a lamp prop, embers, a fissure — and then light it; the light alone is
-still a bug. Then judge each source:
-
-> **Does it change what the player sees AROUND it — on the ground, the walls,
-> the player — or does it only need to be seen itself?**
-
-Four verdicts, all legitimate, one forbidden:
-
-- **Seen itself** — an emissive material, no light object. Most sources land
-  here, and that is what keeps the frame cheap; how much it glows is
-  `$genex-threejs-bloom`'s question.
-- **Lights its surroundings** — a real `PointLight` or `SpotLight`, coupled to
-  its emitter (below). A campfire that doesn't paint the ground orange is a
-  prop, not a fire.
-- **Shapes the whole frame** — the key: a sun or moon `DirectionalLight`, the
-  arena floods. One or two per scene, and they own the shadows.
-- **The air itself is lit** — the beam is the point: the cave crack, a dusty
-  window shaft, canopy rays. Build the shaft as geometry first — fog and
-  volumetric passes are scene-wide decisions, never per-beam tools (recipes
-  in the reference).
-- **Not deciding — the only wrong answer.** One white `AmbientLight` over
-  everything is not a rig; it is the unlit look with extra steps, and it is
-  why shipped scenes read the same at noon and at midnight.
-
-"The neon is emissive-only — it doesn't reach the street" is a real answer;
-say it in one line and move on. Then check the inverse: **a light with no
-visible cause reads as a bug**, not mood — the player asks why the floor
-glows. And when the walk returns more real lights than the scene can afford,
-demote the dimmest back to emissive-only: dynamic lights are the scarcest
-resource in the frame, and the eye forgives an unlit distant torch far sooner
-than a dropped frame.
-
-## A practical is coupled, not placed
-
-The light a source throws and the mesh that emits it are one thing. Drive both
-from one envelope — separate flickers, or a light hovering near an unlit prop,
-read instantly as fake:
-
-```ts
-// Values assume a locked renderer baseline — relationships, not mandates.
-const fire = new THREE.PointLight(0xff9142, 14, 18, 2); // range-capped, physical falloff
-fire.position.set(0, 0.9, 0);                 // inside the flame, above the fuel
-campfire.add(fire);
-const flameMat = flame.material as THREE.MeshStandardMaterial;
-flameMat.emissive.set(0xff7a1e);
-
-function flicker(t: number): number {
-  // two incommensurate sines — coherent, frame-rate independent
-  return 0.82 + 0.12 * Math.sin(t * 11.3) + 0.06 * Math.sin(t * 23.7 + 1.7);
-}
-
-function updateFire(elapsed: number): void {
-  const e = flicker(elapsed);
-  fire.intensity = 14 * e;
-  flameMat.emissiveIntensity = 2.4 * e;       // mesh and light breathe together
-  fire.position.x = 0.05 * Math.sin(elapsed * 7.1); // the pool sways with the flame
-}
-```
-
-The same couple serves a neon sign that hums, a monitor whose picture spills
-onto the desk, a muzzle flash (one envelope drives light, emissive, and the
-sound cue). And when `npx genex skybox` has set `scene.environment`, that
-image IS the ambient fill — do not stack an `AmbientLight` on top of it.
-
-Read [references/light-recipes.md](references/light-recipes.md) for rig
-baselines per environment (day, night, interior, cave, space), the shaft and
-fog recipes, light-as-information patterns, budget relationships, and the
-kill-switch diagnostic.
-
-## Rules
-
-- Every light names its cause; a light nothing explains is a bug, not mood.
-- **The light population is fixed at scene build — never add, remove, or hide
-  a light (or a group containing one) during play.** Three.js counts lights
-  into every lit material's shader; a changed count recompiles ALL of them
-  synchronously — a multi-second freeze on the exact frame a pickup, door, or
-  death "removes" a light (a real pilot game froze ~3 s per relic collected
-  this way). Turn a light off by driving `intensity` to 0 and leave it in the
-  graph; per-level swaps rebuild the whole scene anyway, which is the one
-  legitimate time the population changes.
-- Couple a practical to its emitter: one color, one envelope, one on/off state.
-- The key owns shadows; practicals cast none until a shot proves they must.
-- **A shadow-casting practical that never moves gets a FROZEN map**: a
-  PointLight shadow is a 6-face cube render, re-drawn every frame by default —
-  four static lanterns cost 24 shadow passes/frame over your densest props for
-  zero visual change (a pilot game submitted 66M triangles/frame this way).
-  Set `light.shadow.autoUpdate = false; light.shadow.needsUpdate = true;` so
-  the cube renders once; keep only the key (which shadows the movers) dynamic,
-  and budget frozen practicals at ≤1024 map size.
-- Tune intensities only after the renderer baseline is locked — retuning the
-  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 — 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
-
-Tone mapping, exposure, and grading are
-`$genex-threejs-exposure-color-grading`. How much an emissive glows is
-`$genex-threejs-bloom`; whether it also illuminates is this skill. Authoring
-the emissive surface itself — lava, hot rock, a screen's picture — is
-`$genex-threejs-procedural-materials`. `$genex-threejs-shadow-systems` owns
-large roaming-world shadows (cascades, clipmaps) — a bounded scene's one
-shadow-casting key with a tight frustum lives here. Sky scattering, haze, and the sun disc are
-`$genex-threejs-atmosphere-aerial-perspective`; shafts inside clouds are
-`$genex-threejs-volumetric-clouds`; ordering a volumetric pass among other
-post effects is `$genex-threejs-image-pipeline`; the environment map that
-feeds the fill is `$genex-ai-skybox`.