@rune-kit/rune 2.2.0 → 2.2.1

package/extensions/gamedev/skills/multiplayer.md

@@ -0,0 +1,180 @@
+---
+name: "multiplayer"
+pack: "@rune/gamedev"
+description: "WebSocket game server and client prediction — authoritative server model, client-side prediction, reconciliation, entity interpolation, and lag compensation."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# multiplayer
+
+WebSocket game server and client prediction — authoritative server model, client-side prediction, reconciliation, entity interpolation, and lag compensation.
+
+Authoritative server model: server owns game state, clients send inputs only. Never trust client position.
+
+#### Workflow
+
+**Step 1 — Assess multiplayer architecture**
+Use Grep to find existing WebSocket code: `WebSocket`, `socket.io`, `ws`, `onmessage`, `postMessage`. Determine: is there a server or is this client-only? What is the tick rate?
+
+**Step 2 — Implement authoritative server**
+Emit: Node.js WebSocket server with fixed-tick update (20Hz sufficient), input queue per player, server-side physics/movement, state broadcast.
+
+**Step 3 — Implement client prediction**
+Emit: local input application before server confirmation, pending input buffer, reconciliation on server update, smooth interpolation for remote entities.
+
+**Step 4 — Add lag compensation**
+Emit: snapshot buffer for entity interpolation (render ~100ms behind server), client prediction with rollback on desync.
+
+#### WebSocket Game Server Pattern
+
+```typescript
+// Server (Node.js + ws) — authoritative game server
+import { WebSocketServer, WebSocket } from 'ws';
+
+interface PlayerInput { seq: number; keys: { up: boolean; down: boolean; left: boolean; right: boolean }; }
+interface PlayerState { id: string; x: number; y: number; vx: number; vy: number; }
+
+const wss = new WebSocketServer({ port: 3001 });
+const players = new Map<string, PlayerState>();
+const inputQueues = new Map<string, PlayerInput[]>();
+
+wss.on('connection', (ws: WebSocket, req) => {
+  const id = crypto.randomUUID();
+  players.set(id, { id, x: 0, y: 0, vx: 0, vy: 0 });
+  inputQueues.set(id, []);
+
+  ws.send(JSON.stringify({ type: 'init', id, state: Object.fromEntries(players) }));
+  broadcast({ type: 'player_joined', id });
+
+  ws.on('message', (raw) => {
+    const msg = JSON.parse(raw.toString());
+    if (msg.type === 'input') {
+      inputQueues.get(id)?.push(msg.input);
+    }
+  });
+
+  ws.on('close', () => {
+    players.delete(id);
+    inputQueues.delete(id);
+    broadcast({ type: 'player_left', id });
+  });
+});
+
+// Fixed-tick server update (20Hz is sufficient for authoritative server)
+const TICK_MS = 50;
+setInterval(() => {
+  inputQueues.forEach((queue, id) => {
+    const player = players.get(id)!;
+    const input = queue.shift(); // process one input per tick
+    if (input) applyInput(player, input);
+    integratePhysics(player);
+  });
+
+  broadcast({ type: 'state_update', tick: Date.now(), players: Object.fromEntries(players) });
+}, TICK_MS);
+
+function broadcast(msg: object) {
+  const data = JSON.stringify(msg);
+  wss.clients.forEach(c => c.readyState === WebSocket.OPEN && c.send(data));
+}
+
+function applyInput(p: PlayerState, input: PlayerInput) {
+  const speed = 200;
+  p.vx = (input.keys.right ? 1 : 0) - (input.keys.left ? 1 : 0);
+  p.vy = (input.keys.down ? 1 : 0) - (input.keys.up ? 1 : 0);
+  const len = Math.hypot(p.vx, p.vy);
+  if (len > 0) { p.vx = (p.vx / len) * speed; p.vy = (p.vy / len) * speed; }
+}
+
+function integratePhysics(p: PlayerState) {
+  p.x += p.vx * (TICK_MS / 1000);
+  p.y += p.vy * (TICK_MS / 1000);
+}
+```
+
+#### Client Prediction & Reconciliation
+
+```typescript
+// Client — predict locally, reconcile on server update
+class NetworkedPlayer {
+  private pendingInputs: { seq: number; input: PlayerInput; }[] = [];
+  private seq = 0;
+  localState: PlayerState;
+  serverState: PlayerState;
+
+  constructor(initial: PlayerState) {
+    this.localState = { ...initial };
+    this.serverState = { ...initial };
+  }
+
+  sendInput(keys: PlayerInput['keys'], ws: WebSocket) {
+    const input: PlayerInput = { seq: ++this.seq, keys };
+    this.pendingInputs.push({ seq: this.seq, input });
+    ws.send(JSON.stringify({ type: 'input', input }));
+
+    // Apply immediately (client prediction)
+    applyInputToState(this.localState, keys);
+  }
+
+  reconcile(serverUpdate: PlayerState & { lastProcessedSeq: number }) {
+    this.serverState = serverUpdate;
+
+    // Remove acknowledged inputs
+    this.pendingInputs = this.pendingInputs.filter(p => p.seq > serverUpdate.lastProcessedSeq);
+
+    // Reapply unacknowledged inputs on top of server state
+    this.localState = { ...serverUpdate };
+    for (const { input } of this.pendingInputs) {
+      applyInputToState(this.localState, input.keys);
+    }
+  }
+}
+
+function applyInputToState(state: PlayerState, keys: PlayerInput['keys']) {
+  const dt = 1 / 60;
+  const speed = 200;
+  state.x += ((keys.right ? 1 : 0) - (keys.left ? 1 : 0)) * speed * dt;
+  state.y += ((keys.down ? 1 : 0) - (keys.up ? 1 : 0)) * speed * dt;
+}
+```
+
+#### Lag Compensation & Entity Interpolation
+
+```typescript
+// Interpolate remote entities between server snapshots (smooth movement, ~100ms behind)
+interface Snapshot { tick: number; timestamp: number; entities: Map<string, PlayerState>; }
+
+class EntityInterpolator {
+  private buffer: Snapshot[] = [];
+  private readonly delay = 100; // ms behind server
+
+  addSnapshot(snapshot: Snapshot) {
+    this.buffer.push(snapshot);
+    // Keep only last 1 second of snapshots
+    const cutoff = Date.now() - 1000;
+    this.buffer = this.buffer.filter(s => s.timestamp > cutoff);
+  }
+
+  getInterpolatedState(entityId: string): PlayerState | null {
+    const renderTime = Date.now() - this.delay;
+
+    // Find the two snapshots bracketing renderTime
+    const newer = this.buffer.find(s => s.timestamp >= renderTime);
+    const older = this.buffer.slice().reverse().find(s => s.timestamp < renderTime);
+
+    if (!older || !newer) return newer?.entities.get(entityId) ?? null;
+
+    const t = (renderTime - older.timestamp) / (newer.timestamp - older.timestamp);
+    const a = older.entities.get(entityId);
+    const b = newer.entities.get(entityId);
+    if (!a || !b) return null;
+
+    return {
+      ...a,
+      x: a.x + (b.x - a.x) * t,
+      y: a.y + (b.y - a.y) * t,
+    };
+  }
+}
+```

package/extensions/gamedev/skills/particles.md

@@ -0,0 +1,105 @@
+---
+name: "particles"
+pack: "@rune/gamedev"
+description: "GPU particle system with WebGL instancing — object-pooled particles, emission presets, and performance-safe rendering for 10k+ particles."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# particles
+
+GPU particle system with WebGL instancing — object-pooled particles, emission presets, and performance-safe rendering for 10k+ particles.
+
+#### Workflow
+
+**Step 1 — Detect particle usage**
+Use Grep to find particle code: `particles`, `emitter`, `ParticleSystem`, `createBufferSource`. Understand current implementation: CPU vs GPU, pooling strategy, and draw call count.
+
+**Step 2 — Audit particle performance**
+Check for: new particle objects created on emit (GC pressure), no object pool, drawing each particle as a separate draw call, no life/alpha fade.
+
+**Step 3 — Emit particle system**
+Emit: ParticleSystem with pre-allocated pool, update/render separation, emitter presets for common effects (explosion, sparks, smoke).
+
+#### GPU Particles with WebGL Instancing
+
+```typescript
+// GPU particle system — update on CPU, render 10k+ particles via instancing
+interface Particle {
+  x: number; y: number;
+  vx: number; vy: number;
+  life: number; maxLife: number;
+  size: number;
+  r: number; g: number; b: number; a: number;
+}
+
+class ParticleSystem {
+  private particles: Particle[] = [];
+  private pool: Particle[] = [];
+  private readonly maxParticles: number;
+
+  constructor(maxParticles = 5000) {
+    this.maxParticles = maxParticles;
+    // Pre-allocate pool
+    for (let i = 0; i < maxParticles; i++) {
+      this.pool.push({ x:0,y:0,vx:0,vy:0,life:0,maxLife:1,size:4,r:1,g:1,b:1,a:1 });
+    }
+  }
+
+  emit(x: number, y: number, count: number, config: Partial<Particle> = {}) {
+    for (let i = 0; i < count && this.particles.length < this.maxParticles; i++) {
+      const p = this.pool.pop() ?? { x:0,y:0,vx:0,vy:0,life:0,maxLife:1,size:4,r:1,g:1,b:1,a:1 };
+      const angle = Math.random() * Math.PI * 2;
+      const speed = 50 + Math.random() * 150;
+      Object.assign(p, {
+        x, y,
+        vx: Math.cos(angle) * speed,
+        vy: Math.sin(angle) * speed,
+        life: 1, maxLife: 0.5 + Math.random() * 1.5,
+        size: 3 + Math.random() * 5,
+        r: 1, g: 0.5, b: 0.1, a: 1,
+        ...config,
+      });
+      this.particles.push(p);
+    }
+  }
+
+  update(dt: number) {
+    const gravity = 200;
+    for (let i = this.particles.length - 1; i >= 0; i--) {
+      const p = this.particles[i];
+      p.x += p.vx * dt;
+      p.y += p.vy * dt;
+      p.vy += gravity * dt;
+      p.life -= dt / p.maxLife;
+      p.a = Math.max(0, p.life);
+      if (p.life <= 0) {
+        this.pool.push(p);
+        this.particles.splice(i, 1);
+      }
+    }
+  }
+
+  // Render with Canvas 2D (swap with WebGL instancing for >10k particles)
+  render(ctx: CanvasRenderingContext2D) {
+    for (const p of this.particles) {
+      ctx.globalAlpha = p.a;
+      ctx.fillStyle = `rgb(${p.r * 255 | 0},${p.g * 255 | 0},${p.b * 255 | 0})`;
+      ctx.beginPath();
+      ctx.arc(p.x, p.y, p.size * p.life, 0, Math.PI * 2);
+      ctx.fill();
+    }
+    ctx.globalAlpha = 1;
+  }
+}
+
+// Emitter presets
+const EMITTER_PRESETS = {
+  explosion: (x: number, y: number, sys: ParticleSystem) =>
+    sys.emit(x, y, 80, { r: 1, g: 0.4, b: 0 }),
+  sparks: (x: number, y: number, sys: ParticleSystem) =>
+    sys.emit(x, y, 20, { r: 1, g: 0.9, b: 0.2, size: 2, maxLife: 0.8 }),
+  smoke: (x: number, y: number, sys: ParticleSystem) =>
+    sys.emit(x, y, 10, { r: 0.5, g: 0.5, b: 0.5, size: 12, maxLife: 3, vx: 0, vy: -30 }),
+};
+```

package/extensions/gamedev/skills/physics-engine.md

@@ -0,0 +1,89 @@
+---
+name: "physics-engine"
+pack: "@rune/gamedev"
+description: "Physics integration — Rapier.js, rigid bodies, constraints, raycasting, collision callbacks, deterministic simulation."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# physics-engine
+
+Physics integration — Rapier.js, rigid bodies, constraints, raycasting, collision callbacks, deterministic simulation.
+
+#### Workflow
+
+**Step 1 — Detect physics setup**
+Use Grep to find physics libraries: `rapier`, `cannon`, `ammo`, `@dimforge/rapier3d`, `RigidBody`, `Collider`. Read physics initialization and body creation to understand: engine choice, world configuration, and collision handling.
+
+**Step 2 — Audit physics configuration**
+Check for: physics step tied to render frame (non-deterministic), missing collision groups (everything collides with everything), no sleep threshold (wasted CPU on static objects), raycasts without max distance (expensive), and missing body cleanup on entity destroy.
+
+**Step 3 — Emit optimized physics**
+Emit: Rapier.js (WASM, deterministic) setup with proper collision groups, sleep thresholds, event-driven collision callbacks, and raycasting utility.
+
+#### Example
+
+```typescript
+// Rapier.js (WASM) — setup with collision groups and raycasting
+import RAPIER from '@dimforge/rapier3d-compat';
+
+await RAPIER.init();
+const world = new RAPIER.World({ x: 0, y: -9.81, z: 0 });
+
+// Collision groups: player=0x0001, enemy=0x0002, ground=0x0004, projectile=0x0008
+const GROUPS = { PLAYER: 0x0001, ENEMY: 0x0002, GROUND: 0x0004, PROJECTILE: 0x0008 };
+
+// Ground — static, collides with everything
+const groundBody = world.createRigidBody(RAPIER.RigidBodyDesc.fixed().setTranslation(0, 0, 0));
+world.createCollider(
+  RAPIER.ColliderDesc.cuboid(50, 0.1, 50)
+    .setCollisionGroups((GROUPS.GROUND << 16) | 0xFFFF),
+  groundBody,
+);
+
+// Player — dynamic, collides with ground + enemy (not own projectiles)
+const playerBody = world.createRigidBody(RAPIER.RigidBodyDesc.dynamic().setTranslation(0, 5, 0));
+world.createCollider(
+  RAPIER.ColliderDesc.capsule(0.5, 0.3)
+    .setCollisionGroups((GROUPS.PLAYER << 16) | (GROUPS.GROUND | GROUPS.ENEMY))
+    .setActiveEvents(RAPIER.ActiveEvents.COLLISION_EVENTS),
+  playerBody,
+);
+
+// Raycast utility
+function raycast(origin: RAPIER.Vector3, direction: RAPIER.Vector3, maxDist = 100) {
+  const ray = new RAPIER.Ray(origin, direction);
+  const hit = world.castRay(ray, maxDist, true);
+  if (hit) {
+    const point = ray.pointAt(hit.timeOfImpact);
+    return { point, normal: hit.normal, collider: hit.collider };
+  }
+  return null;
+}
+```
+
+#### Collision Event Handling
+
+```typescript
+// Event-driven collision callbacks — no polling
+const eventQueue = new RAPIER.EventQueue(true);
+
+// In fixed update step:
+world.step(eventQueue);
+
+eventQueue.drainCollisionEvents((handle1, handle2, started) => {
+  const body1 = world.getRigidBody(world.getCollider(handle1).parent()!);
+  const body2 = world.getRigidBody(world.getCollider(handle2).parent()!);
+
+  const entity1 = entityMap.get(body1.handle);
+  const entity2 = entityMap.get(body2.handle);
+
+  if (started) {
+    entity1?.onCollisionEnter(entity2);
+    entity2?.onCollisionEnter(entity1);
+  } else {
+    entity1?.onCollisionExit(entity2);
+    entity2?.onCollisionExit(entity1);
+  }
+});
+```

package/extensions/gamedev/skills/scene-management.md

@@ -0,0 +1,146 @@
+---
+name: "scene-management"
+pack: "@rune/gamedev"
+description: "Scene transitions, preloading, serialization — stack-based SceneManager with fade transitions, asset preloading before enter, and level JSON serialization."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# scene-management
+
+Scene transitions, preloading, serialization — stack-based SceneManager with fade transitions, asset preloading before enter, and level JSON serialization.
+
+#### Workflow
+
+**Step 1 — Detect scene structure**
+Use Grep to find scene code: `Scene`, `GameState`, `StateMachine`, `push`, `pop`, `replace`. Read to understand: how scenes transition, whether assets are preloaded, and how scene data is persisted.
+
+**Step 2 — Audit scene management**
+Check for: abrupt scene switches with no transition (jarring UX), assets loaded mid-scene causing stutters, no scene stack (can't return to previous state), missing cleanup on exit.
+
+**Step 3 — Emit SceneManager**
+Emit: stack-based SceneManager with fade in/out, asset preloading tied to scene.assets[], push/pop/replace operations, and level serialization/deserialization.
+
+#### Scene Stack with Transitions and Preloading
+
+```typescript
+// Scene manager — stack-based, asset preloading, fade transitions
+interface Scene {
+  name: string;
+  assets: string[]; // asset keys to preload before entering
+  onEnter(data?: unknown): void;
+  onExit(): void;
+  update(dt: number): void;
+  render(ctx: CanvasRenderingContext2D): void;
+}
+
+class SceneManager {
+  private stack: Scene[] = [];
+  private loader: AssetLoader;
+  private transitioning = false;
+  private fadeAlpha = 0;
+  private fadeDir: 1 | -1 = 1;
+
+  constructor(loader: AssetLoader) { this.loader = loader; }
+
+  get current(): Scene | undefined { return this.stack[this.stack.length - 1]; }
+
+  async push(scene: Scene, data?: unknown) {
+    if (this.transitioning) return;
+    this.transitioning = true;
+
+    await this.fadeOut();
+    await this.preloadScene(scene);
+    this.stack.push(scene);
+    scene.onEnter(data);
+    await this.fadeIn();
+
+    this.transitioning = false;
+  }
+
+  async pop() {
+    if (this.transitioning || this.stack.length <= 1) return;
+    this.transitioning = true;
+
+    await this.fadeOut();
+    this.current?.onExit();
+    this.stack.pop();
+    await this.fadeIn();
+
+    this.transitioning = false;
+  }
+
+  async replace(scene: Scene, data?: unknown) {
+    if (this.transitioning) return;
+    this.transitioning = true;
+
+    await this.fadeOut();
+    this.current?.onExit();
+    this.stack.pop();
+    await this.preloadScene(scene);
+    this.stack.push(scene);
+    scene.onEnter(data);
+    await this.fadeIn();
+
+    this.transitioning = false;
+  }
+
+  private async preloadScene(scene: Scene) {
+    // Preload only assets not already cached
+    await Promise.all(scene.assets.map(key => this.loader.load(key, `/assets/${key}`)));
+  }
+
+  renderTransition(ctx: CanvasRenderingContext2D, w: number, h: number) {
+    if (this.fadeAlpha > 0) {
+      ctx.save();
+      ctx.globalAlpha = this.fadeAlpha;
+      ctx.fillStyle = '#000';
+      ctx.fillRect(0, 0, w, h);
+      ctx.restore();
+    }
+  }
+
+  private fadeOut(): Promise<void> {
+    return new Promise(resolve => {
+      this.fadeDir = 1;
+      const interval = setInterval(() => {
+        this.fadeAlpha = Math.min(1, this.fadeAlpha + 0.05);
+        if (this.fadeAlpha >= 1) { clearInterval(interval); resolve(); }
+      }, 16);
+    });
+  }
+
+  private fadeIn(): Promise<void> {
+    return new Promise(resolve => {
+      this.fadeDir = -1;
+      const interval = setInterval(() => {
+        this.fadeAlpha = Math.max(0, this.fadeAlpha - 0.05);
+        if (this.fadeAlpha <= 0) { clearInterval(interval); resolve(); }
+      }, 16);
+    });
+  }
+}
+
+// Level serialization — save/load level state as JSON
+interface LevelData {
+  name: string;
+  entities: Array<{ type: string; x: number; y: number; props: Record<string, unknown> }>;
+  tilemap: number[][];
+}
+
+function serializeLevel(world: World): LevelData {
+  const entities: LevelData['entities'] = [];
+  for (const id of world.query(Position)) {
+    const pos = world.getComponent(id, Position)!;
+    entities.push({ type: 'generic', x: pos.x, y: pos.y, props: {} });
+  }
+  return { name: 'level1', entities, tilemap: [] };
+}
+
+function deserializeLevel(data: LevelData, world: World) {
+  for (const e of data.entities) {
+    const id = world.createEntity();
+    world.addComponent(id, new Position(e.x, e.y));
+  }
+}
+```

package/extensions/gamedev/skills/threejs-patterns.md

@@ -0,0 +1,90 @@
+---
+name: "threejs-patterns"
+pack: "@rune/gamedev"
+description: "Three.js patterns — scene setup, React Three Fiber integration, PBR materials, post-processing, performance optimization."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# threejs-patterns
+
+Three.js patterns — scene setup, React Three Fiber integration, PBR materials, post-processing, performance optimization.
+
+#### Workflow
+
+**Step 1 — Detect Three.js setup**
+Use Grep to find Three.js usage: `THREE.`, `useThree`, `useFrame`, `Canvas`, `@react-three/fiber`, `@react-three/drei`. Read the main scene file to understand: renderer setup, scene graph structure, camera type, and lighting model.
+
+**Step 2 — Audit performance**
+Check for: objects created inside `useFrame` (GC pressure), missing `dispose()` on unmount (memory leak), no frustum culling on large scenes, textures without power-of-two dimensions, unoptimized geometry (too many draw calls), and missing LOD for distant objects.
+
+**Step 3 — Emit optimized scene**
+Emit: properly structured R3F scene with declarative lights, memoized geometries, disposal on unmount, instanced meshes for repeated objects, and post-processing pipeline.
+
+#### Example
+
+```tsx
+// React Three Fiber — optimized scene with instancing and post-processing
+import { Canvas, useFrame } from '@react-three/fiber';
+import { OrbitControls, Environment, useGLTF, Instances, Instance } from '@react-three/drei';
+import { EffectComposer, Bloom, Vignette } from '@react-three/postprocessing';
+import { useRef, useMemo } from 'react';
+
+function InstancedTrees({ count = 500 }) {
+  const positions = useMemo(() =>
+    Array.from({ length: count }, () => [
+      (Math.random() - 0.5) * 100,
+      0,
+      (Math.random() - 0.5) * 100,
+    ] as [number, number, number]),
+  [count]);
+
+  return (
+    <Instances limit={count}>
+      <cylinderGeometry args={[0.2, 0.4, 3]} />
+      <meshStandardMaterial color="#4a7c59" />
+      {positions.map((pos, i) => <Instance key={i} position={pos} />)}
+    </Instances>
+  );
+}
+
+function GameScene() {
+  return (
+    <Canvas camera={{ position: [0, 10, 20], fov: 60 }} gl={{ antialias: true }}>
+      <ambientLight intensity={0.3} />
+      <directionalLight position={[10, 20, 10]} intensity={1} castShadow />
+      <Environment preset="sunset" />
+      <InstancedTrees count={500} />
+      <OrbitControls maxPolarAngle={Math.PI / 2.2} />
+      <EffectComposer>
+        <Bloom intensity={0.3} luminanceThreshold={0.8} />
+        <Vignette offset={0.3} darkness={0.6} />
+      </EffectComposer>
+    </Canvas>
+  );
+}
+```
+
+#### LOD (Level of Detail) Pattern
+
+```typescript
+import * as THREE from 'three';
+
+// Swap geometry based on camera distance
+function buildLODMesh(
+  highGeo: THREE.BufferGeometry,
+  midGeo: THREE.BufferGeometry,
+  lowGeo: THREE.BufferGeometry,
+  material: THREE.Material,
+): THREE.LOD {
+  const lod = new THREE.LOD();
+  lod.addLevel(new THREE.Mesh(highGeo, material), 0);    // < 20 units
+  lod.addLevel(new THREE.Mesh(midGeo, material), 20);    // 20–80 units
+  lod.addLevel(new THREE.Mesh(lowGeo, material), 80);    // > 80 units
+  return lod;
+}
+
+// In render loop — LOD auto-updates based on camera distance
+// scene.add(buildLODMesh(highGeo, midGeo, lowGeo, mat));
+// lod.update(camera); // call once per frame
+```

package/extensions/gamedev/skills/webgl.md

@@ -0,0 +1,71 @@
+---
+name: "webgl"
+pack: "@rune/gamedev"
+description: "WebGL patterns — shader programming, GLSL, buffer management, texture handling, instanced rendering."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# webgl
+
+WebGL patterns — shader programming, GLSL, buffer management, texture handling, instanced rendering.
+
+#### Workflow
+
+**Step 1 — Detect WebGL usage**
+Use Grep to find WebGL code: `getContext('webgl`, `gl.createShader`, `gl.createProgram`, `*.glsl`, `*.vert`, `*.frag`. Read shader files and GL initialization to understand: WebGL version, shader complexity, and buffer strategy.
+
+**Step 2 — Audit shader and buffer efficiency**
+Check for: uniforms set every frame that don't change (use UBO), separate draw calls for identical geometry (use instancing), textures not using mipmaps, missing `gl.deleteBuffer`/`gl.deleteTexture` cleanup, and shaders with expensive per-fragment branching.
+
+**Step 3 — Emit optimized WebGL code**
+Emit: WebGL2 setup with proper context attributes, VAO-based buffer management, instanced rendering for repeated geometry, and GLSL shaders with documented inputs/outputs.
+
+#### Example
+
+```glsl
+// Vertex shader — instanced rendering with per-instance transform
+#version 300 es
+layout(location = 0) in vec3 aPosition;
+layout(location = 1) in vec3 aNormal;
+layout(location = 2) in mat4 aInstanceMatrix; // per-instance (locations 2-5)
+
+uniform mat4 uViewProjection;
+
+out vec3 vNormal;
+out vec3 vWorldPos;
+
+void main() {
+  vec4 worldPos = aInstanceMatrix * vec4(aPosition, 1.0);
+  vWorldPos = worldPos.xyz;
+  vNormal = mat3(transpose(inverse(aInstanceMatrix))) * aNormal;
+  gl_Position = uViewProjection * worldPos;
+}
+```
+
+```glsl
+// Fragment shader — PBR-lite with single directional light
+#version 300 es
+precision highp float;
+
+in vec3 vNormal;
+in vec3 vWorldPos;
+out vec4 fragColor;
+
+uniform vec3 uLightDir;
+uniform vec3 uCameraPos;
+uniform vec3 uBaseColor;
+
+void main() {
+  vec3 N = normalize(vNormal);
+  vec3 L = normalize(uLightDir);
+  vec3 V = normalize(uCameraPos - vWorldPos);
+  vec3 H = normalize(L + V);
+
+  float diffuse = max(dot(N, L), 0.0);
+  float specular = pow(max(dot(N, H), 0.0), 32.0);
+  vec3 ambient = uBaseColor * 0.15;
+
+  fragColor = vec4(ambient + uBaseColor * diffuse + vec3(specular * 0.5), 1.0);
+}
+```