quantum-forge 2.7.1 → 3.0.0

package/QUANTUM_FORGE.md

@@ -1,6 +1,6 @@
 ---
 name: quantum-forge
-description: Quantum Forge framework reference — quantum operations, gates, entanglement, rendering, input. Use when writing game code, debugging WASM/imports, or understanding quantum mechanics in games.
+description: Quantum Forge 3.0 reference for game code that imports quantum-forge or quantum-forge-engine. Covers quantum() handles, gates and their aliases, predicates, entanglement through interaction, measurement, dispose, QuantumRecorder, and the engine's rendering and input. Use when writing or debugging quantum game code or WASM loading.
 allowed-tools: Read Glob Grep
 user-invocable: true
 argument-hint: [topic]
@@ -8,24 +8,12 @@ argument-hint: [topic]
 
 # Quantum Forge Reference
 
-## Project Configuration
-
-```!
-node -e "
-const fs = require('fs');
-try {
-  const p = JSON.parse(fs.readFileSync('package.json', 'utf-8'));
-  const deps = { ...p.dependencies, ...p.devDependencies };
-  const core = deps['quantum-forge'] || deps['quantum-forge'] || 'not installed';
-  const engine = deps['quantum-forge-engine'] || deps['quantum-forge-engine'] || 'not installed';
-  const corePkg = deps['quantum-forge'] ? 'quantum-forge' : 'quantum-forge';
-  const enginePkg = deps['quantum-forge-engine'] ? 'quantum-forge-engine' : 'quantum-forge-engine';
-  console.log('Core: ' + corePkg + '@' + core);
-  if (engine !== 'not installed') console.log('Engine: ' + enginePkg + '@' + engine);
-  console.log('Type: ' + (p.type || 'commonjs'));
-} catch { console.log('No package.json found'); }
-" 2>/dev/null
-```
+## Version
+
+This reference covers core 3.0 and newer, where every quantum property is a `quantum()`
+handle. Check the core version in the project's `package.json`. A 2.x install has no handles:
+upgrade it rather than writing `QuantumPropertyManager` code, which is deprecated through 3.x
+and removed in 4.0.
 
 ## Initialization
 
@@ -47,11 +35,11 @@ await ensureLoaded();
 No Vite plugin is needed in Node (tests, servers, agents). The loader finds the WASM inside the installed package, and `useQuantumForgeBuild("qubit")` selects the variant the same way as in a page. Use `setWasmBasePath(fileUrl)` only for WASM files kept outside the package. Node 22 or newer.
 
 ```typescript
-import { useQuantumForgeBuild, ensureLoaded, getModule, getVersion } from "quantum-forge/quantum";
+import { useQuantumForgeBuild, ensureLoaded, getVersion, quantum } from "quantum-forge/quantum";
 useQuantumForgeBuild("qubit");
 await ensureLoaded();
 console.log(getVersion()); // the package version
-const m = getModule();
+const coin = quantum([false, true]).superpose();
 ```
 
 ### Vite Plugin
@@ -70,10 +58,11 @@ ESM note: if using `vite.config.js` (not `.ts`/`.mjs`), add `"type": "module"` t
 
 Quantum Forge gives game objects real quantum state. The usage loop:
 
-1. **Attach quantum properties** to things — each property is a qudit (d-dimensional quantum digit)
+1. **Declare quantum properties** on things with `quantum([...values])`. Each property is a qudit (d-dimensional quantum digit)
 2. **Apply gates** to transform state without collapsing it
-3. **Use predicated gates** to create entanglement — correlations between properties
+3. **Let properties interact** (a two-property gate, or a gate predicated on another property). Entanglement is what an interaction leaves behind
 4. **Measure** to collapse quantum state to a classical value (the game moment)
+5. **Dispose** the handle when the thing it describes is gone
 
 ### Programmer's Mental Model
 
@@ -81,301 +70,307 @@ Quantum Forge gives game objects real quantum state. The usage loop:
 
 **Gates** are collection algorithms that transform every entry at once. `cycle` increments each value. `hadamard` creates equal superposition.
 
-**Predicated gates** apply a filter: "if property A is |1⟩, flip property B." This creates entanglement — correlated entries in the collection.
+**Predicated gates** apply a filter: "if property A is true, flip property B." This creates entanglement, correlated entries in the collection.
 
 The weights are **complex amplitudes**, not probabilities. When two entries with the same value meet, their amplitudes add. In phase = constructive interference (probability increases). Out of phase = destructive interference (probability cancels). Probability of a value = squared magnitude of its amplitude.
 
-## QuantumPropertyManager
+## Quantum properties
 
-Extend this class to build your game's quantum system. It manages property lifecycle, pooling, and WASM access.
+A property is declared by the values it can take. The dimension is the number of values, and
+the property starts at the first one.
 
 ```typescript
-import { QuantumPropertyManager, ensureLoaded } from "quantum-forge/quantum";
+import { ensureLoaded, quantum } from "quantum-forge/quantum";
 
 await ensureLoaded();
 
-class QuantumRegistry extends QuantumPropertyManager {
-  constructor(logger?: any) { super({ dimension: 2, logger }); }
+const color = quantum(["red", "green", "blue"]); // qutrit, starts "red"
+const alive = quantum([false, true]);            // qubit, starts false
+const die = quantum(3);                          // numeric form: values 0, 1, 2
 
-  makeQuantum(id: string): void {
-    const prop = this.acquireProperty();
-    const m = this.getModule();
-    m.cycle(prop);        // |0⟩ → |1⟩
-    m.hadamard(prop);     // → 50/50 superposition
-    this.setProperty(id, prop);
-  }
+color.superpose();                 // alias for hadamard()
+color.probability("green");        // 1/3, no collapse
+const seen = color.measure();      // "red" | "green" | "blue"
+color.dispose();                   // end of life; the qudit is cached for reuse
+```
 
-  entangle(id1: string, id2: string): void {
-    const p1 = this.getProperty(id1);
-    const p2 = this.getProperty(id2);
-    if (!p1 || !p2) return;
-    this.getModule().i_swap(p1, p2, 0.5);
-  }
+Keep each handle on the entity it describes (`ball.exists = quantum([false, true])`). A ball
+without a handle is classical. There is no id map and no manager.
 
-  getProbability(id: string): number {
-    const prop = this.getProperty(id);
-    if (!prop) return 1.0;
-    const results = this.getModule().probabilities([prop]);
-    for (const r of results) {
-      if (r.qudit_values[0] === 1) return r.probability;
-    }
-    return 0;
-  }
+### Dimension
 
-  measure(id: string): number {
-    const prop = this.getProperty(id);
-    if (!prop) return 1;
-    const [value] = this.getModule().measure_properties([prop]);
-    this.deleteProperty(id);
-    this.releaseProperty(prop, value); // reset to |0⟩, return to pool
-    return value;
-  }
-}
-```
+| Dimension | Declaration | Use Case |
+|-----------|-------------|----------|
+| 2 (qubit) | `quantum([false, true])` | Binary: exists/doesn't, alive/dead |
+| 3 (qutrit) | `quantum(["rock", "paper", "scissors"])` | Three-way choices |
 
-### Dimension
+Start with two values unless your design needs more. The shipped Qutrit Edition allows up to
+three; `quantum()` throws past the build's maximum.
 
-| Dimension | States | Use Case |
-|-----------|--------|----------|
-| 2 (qubit) | `\|0⟩`, `\|1⟩` | Binary: exists/doesn't, alive/dead |
-| 3 (qutrit) | `\|0⟩` – `\|2⟩` | Three-way: rock/paper/scissors |
+### Values and indices
 
-Start with dimension 2 unless your design needs more. Shipped package supports up to 3.
+Every method that takes a value (`is`, `isNot`, `probability`, `forcedMeasure`) accepts the
+declared value or its index. `alive.is(true)` and `alive.is(1)` are the same predicate. A value
+that is not declared throws at the call. `measure()` returns the declared value.
 
 ## Gates
 
-All gates are called via `getModule()`. Every gate accepts optional `predicates` for conditional execution (creates entanglement). Omit `fraction` for the discrete gate. Passing a number, `1` included, selects the continuous rotation instead: at `1` it lands on the same state as the discrete gate, but by the slower rotation path. Write `undefined` when you mean the discrete gate.
+Gates are methods on the handle and return it, so they chain. Physics names are primary; each
+alias runs exactly the same gate.
 
-| Gate | Method | Dim | Description |
-|------|--------|-----|-------------|
-| Cycle | `m.cycle(prop, fraction?, preds?)` | Any | Cyclic permutation. `\|0⟩→\|1⟩→\|0⟩` for dim=2 (NOT gate) |
-| Shift / X | `m.shift(prop, fraction?, preds?)` | Any | Inverse of cycle. Same as cycle for dim=2 |
-| Hadamard | `m.hadamard(prop, fraction?, preds?)` | Any | Equal superposition. The main "make it quantum" gate |
-| Inv. Hadamard | `m.inverse_hadamard(prop, preds?)` | Any | Reverse of hadamard |
-| Clock / Z | `m.clock(prop, fraction?, preds?)` | Any | Phase rotation. Invisible until interaction |
-| Y | `m.y(prop, fraction?, preds?)` | **2 only** | Pauli Y. Throws if dimension != 2 |
-| iSwap | `m.i_swap(p1, p2, fraction, preds?)` | Any | Anti-correlated entanglement |
-| Swap | `m.swap(p1, p2, preds?)` | Any | Direct state exchange, no entanglement |
-| Phase Rotate | `m.phase_rotate(preds, angle)` | Any | Phase rotation conditioned on predicates (required) |
+| Physics call | Alias | Dim | Description |
+|--------------|-------|-----|-------------|
+| `hadamard(f?, opts?)` | `superpose` | Any | Equal superposition. The main "make it quantum" gate |
+| `inverseHadamard(opts?)` | | Any | Reverse of hadamard |
+| `cycle(f?, opts?)` | `next`; `flip` on qubits | Any | Next value, wrapping. NOT at dimension 2 |
+| `shift(f?, opts?)` | `previous` | Any | Previous value, wrapping. Same as cycle at dimension 2 |
+| `clock(f?, opts?)` | `phase` | Any | Phase rotation. Shows on a superposition at the next gate that mixes values |
+| `x(f?, opts?)` / `z(f?, opts?)` | | Any | Pauli X (= shift) and Pauli Z (= clock) |
+| `y(f?, opts?)` | | **2 only** | Pauli Y. Throws if dimension != 2 |
+| `a.iSwap(b, f, opts?)` | | Any | Anti-correlated entanglement. Fraction required |
+| `a.swap(b, opts?)` | | Any | Direct state exchange |
+| `phaseRotate(angle, { when })` | | Any | Free function. Phase on the states where the predicates hold |
 
-**Fractional gates**: `0.5` is the square root of the gate, `0.1` barely moves the state, `1` completes the rotation. Apply a small fraction every frame for a gradual effect.
+`flip` throws on anything but two values; use `next` on a qutrit. `swap` and `iSwap` throw
+when passed the handle they are called on. There is no `entangle()`. A property needs at least
+two values, and `quantum()` is the only way to make one; the `Quantum` constructor is private.
 
-### Predicates (Conditional Gates)
+Every gate except `inverseHadamard`, `swap` and `iSwap` takes an optional fraction first. An
+omitted fraction, or exactly 1, is the discrete gate; any other number is the continuous version, and 0.5 is the square root of the gate. `0.1` barely moves the state.
+Apply a small fraction every frame for a gradual effect.
 
-Every gate accepts predicates that condition it on other properties' states. **This is how entanglement works** — a gate that depends on another property's state correlates them.
+### Predicates (conditional gates)
 
-**Gotcha:** predicates are the third argument, so the discrete gate with predicates is `m.shift(target, undefined, [control.is(1)])`. Passing `1` runs the fractional path instead (same state, slower).
+Pass predicates in `{ when: [...] }`. The gate acts only where every predicate holds. A
+predicate on another property makes the gate an interaction, which entangles the two.
 
 ```typescript
-// CNOT: flip target only when control is |1⟩
-m.shift(target, undefined, [control.is(1)]);
-// Result: (|00⟩ + |11⟩)/√2 — positively correlated
+// CNOT: flip target only when control is true
+target.flip({ when: [control.is(true)] });
+// Result: (|00⟩ + |11⟩)/√2, positively correlated
+
+// CZ
+target.phase({ when: [control.is(true)] });
 
-// Controlled Hadamard: target enters superposition conditionally
-m.hadamard(target, undefined, [control.is(1)]);
+// Controlled Hadamard, and a fractional controlled gate
+target.superpose({ when: [control.is(true)] });
+target.flip(0.5, { when: [control.is(true)] });
 
-// Predicate types:
-prop.is(value)      // true when property is |value⟩
-prop.is_not(value)  // true when property is NOT |value⟩
+// Predicate types
+prop.is(value)      // holds when the property equals value (declared value or index)
+prop.isNot(value)   // holds when it does not
 
 // Multiple predicates are AND'd
-m.shift(target, undefined, [controlA.is(1), controlB.is(1)]);
+target.flip({ when: [controlA.is(true), controlB.is(true)] });
 ```
 
-For `PredicateSpec` objects (used in some APIs):
-
-```typescript
-import type { PredicateSpec } from "quantum-forge/quantum";
-const specs: PredicateSpec[] = [
-  { property: controlProp, value: 1, isEqual: true },
-];
-const wasmPreds = specs.map(s =>
-  s.isEqual ? s.property.is(s.value) : s.property.is_not(s.value)
-);
-```
+## Entanglement patterns
 
-## Entanglement Patterns
+Entanglement is what an interaction leaves behind. A gate that touches two properties, or one
+whose predicate reads another property, is an interaction. Measuring one entangled property
+settles the other.
 
-### Entangle-Split (iSwap)
+### Entangle-split (iSwap)
 
-Object splits into anti-correlated pair. Exactly one is real.
+Object splits into an anti-correlated pair. Exactly one is real.
 
 ```typescript
-entangleSplit(originalId: string, newId: string): void {
-  const prop1 = this.acquireProperty();
-  const prop2 = this.acquireProperty();
-  const m = this.getModule();
-  m.cycle(prop1);                // |1⟩ (exists)
-  m.i_swap(prop1, prop2, 0.5);  // entangle
-  this.setProperty(originalId, prop1);
-  this.setProperty(newId, prop2);
+function entangleSplit(original: Ball, clone: Ball): void {
+  original.exists = quantum([false, true]).flip(); // exists
+  clone.exists = quantum([false, true]);           // does not
+  original.exists.iSwap(clone.exists, 0.5);
 }
 ```
 
-### Correlated Pair (CNOT)
+### Correlated pair (CNOT)
 
-Both match — both alive or both dead.
+Both match: both alive or both dead.
 
 ```typescript
-createLinkedPair(id1: string, id2: string): void {
-  const prop1 = this.acquireProperty();
-  const prop2 = this.acquireProperty();
-  const m = this.getModule();
-  m.cycle(prop1);
-  m.hadamard(prop1);
-  m.shift(prop2, undefined, [prop1.is(1)]); // CNOT
-  this.setProperty(id1, prop1);
-  this.setProperty(id2, prop2);
+function linkPair(a: Enemy, b: Enemy): void {
+  a.alive = quantum([false, true]).superpose();
+  b.alive = quantum([false, true]);
+  b.alive.flip({ when: [a.alive.is(true)] });
 }
 ```
 
-### Quantum-Split
+### Quantum-split
 
-Split an already-quantum object. Pooled properties preferred (no tensor product growth).
+Split an already-quantum object. The split adds one qudit to the original's shared state, so
+check that there is room first. Catching the over-limit throw instead leaks WASM memory on
+every catch.
 
 ```typescript
-quantumSplit(originalId: string, newId: string): boolean {
-  const prop1 = this.getProperty(originalId);
-  if (!prop1) return false;
-  const prop2 = this.acquireProperty();
-  try {
-    this.getModule().i_swap(prop1, prop2, 0.5);
-  } catch {
-    this.releaseProperty(prop2, 0); // qudit limit
-    return false;
-  }
-  this.setProperty(newId, prop2);
+import { getMaxQudits, quantum } from "quantum-forge/quantum";
+
+function quantumSplit(original: Ball, clone: Ball): boolean {
+  if (!original.exists) return false;
+  if (original.exists.numActiveQudits() >= getMaxQudits()) return false; // state is full
+  const split = quantum([false, true]);
+  original.exists.iSwap(split, 0.5);
+  clone.exists = split;
   return true;
 }
 ```
 
-### Overlap Entanglement
-
-Objects that spatially overlap become entangled:
-
-```typescript
-this.getModule().i_swap(propA, propB, 0.5);
-```
-
-### Conditional Superposition
+### Overlap entanglement
 
-A control property determines whether a target enters superposition:
+Quantum objects that spatially overlap become entangled. Both need a handle, and the pair
+must differ somewhere: iSwap on two equal values does nothing.
 
 ```typescript
-m.hadamard(target, undefined, [control.is(1)]);
+function overlap(a: Ball, b: Ball): void {
+  if (a.exists && b.exists) a.exists.iSwap(b.exists, 0.5);
+}
 ```
 
-### Choosing Between Mechanisms
+### Choosing between mechanisms
 
 | Mechanism | Correlation | Use |
 |-----------|-------------|-----|
-| Predicated shift (CNOT) | Positive — both match | Linked states: both alive or both dead |
-| Predicated hadamard | Conditional superposition | One object's quantumness depends on another |
-| `i_swap(0.5)` | Anti-correlated — exactly one | Object splits into two ghosts |
-| `i_swap` + phase | Tunable bias | Player-influenced split probability |
+| `b.flip({ when: [a.is(true)] })` (CNOT) | Positive, both match | Linked states: both alive or both dead |
+| `b.superpose({ when: [a.is(true)] })` | Conditional superposition | One object's quantumness depends on another |
+| `a.iSwap(b, 0.5)` | Anti-correlated, exactly one | Object splits into two ghosts |
+| `iSwap(0.5)`, `phase(f)`, `iSwap(0.5)` | Tunable bias | Player-influenced split probability |
 
 ## Measurement
 
-Measurement collapses superposition to a definite value. Entangled partners collapse instantly too.
+Measurement collapses superposition to a definite value. Entangled partners collapse too.
 
 ```typescript
-const [value] = m.measure_properties([prop]); // probabilistic collapse
-// Always pool after:
-this.deleteProperty(id);
-this.releaseProperty(prop, value);
+const value = prop.measure(); // declared value, e.g. true or false
 ```
 
-### Batch Measurement
+A measured handle is still usable. It holds a definite value and can go back into
+superposition. When the object is gone, `dispose()` it.
+
+### Joint measurement
 
 ```typescript
-const [va, vb, vc] = m.measure_properties([propA, propB, propC]);
+import { measure } from "quantum-forge/quantum";
+const [va, vb, vc] = measure(propA, propB, propC);
 ```
 
-### Reading State (No Collapse)
+### Reading state (no collapse)
 
 ```typescript
-// Probabilities — read-only, no state change
-const results = m.probabilities([prop]);
-// [{ probability: 0.5, qudit_values: [0] }, { probability: 0.5, qudit_values: [1] }]
+import { probabilities, densityMatrix, probabilityWhen, measureWhen, forcedMeasure } from "quantum-forge/quantum";
+
+prop.probability(true);              // one value
+prop.probabilities();                // [{ value: false, probability: 0.5 }, { value: true, probability: 0.5 }]
+probabilities(a, b);                 // joint: [{ values: [false, true], probability }, ...]
 
-// Reduced density matrix — phase and correlation info
-const rdm = m.reduced_density_matrix([prop1, prop2]);
-// Off-diagonal entries carry relative phase
+// Reduced density matrix: phase and correlation info, labelled with declared values
+densityMatrix(a, b);                 // [{ row: [...], col: [...], real, imag }, ...]
 
-// Measure predicate — projective measurement
-const outcome = m.measure_predicate([prop1.is(1), prop2.is(0)]);
-// 1 = satisfied, 0 = not
+probabilityWhen([a.is(true), b.is(false)]); // probability all predicates hold
 
-// Forced measurement — replay/save-load only
-const [value] = m.forced_measure_properties([prop], [1]);
+// Predicate measurement: collapses to agree, returns a boolean
+measureWhen([a.is(true), b.is(false)]);
+
+// Forced measurement: replay and tests only. Throws if the value has zero probability.
+prop.forcedMeasure(true);
+forcedMeasure([a, b], [true, false]);
 ```
 
 ## Phase & Interference
 
-Phase is invisible to measurement but changes how properties interact. Phase + iSwap = probability redistribution through interference.
+Phase is invisible to measurement on its own. A definite value ignores it. On a superposition it shows up at the next gate that mixes values, such as superpose or a partial iSwap, and steers that gate through interference. A phase between two half-splits decides where the object ends up:
 
 ```typescript
-// Apply phase bias
-m.clock(prop, 0.5);  // π/2 phase on |1⟩
-
-// Later, entangle → phase redistributes probability
-m.i_swap(propA, propB, 0.5);
-// Same phase = constructive interference (probability concentrates)
-// Opposite phase = destructive interference (probability cancels)
+const a = quantum([false, true]).flip(); // exists
+const b = quantum([false, true]);        // does not
+a.iSwap(b, 0.5);                         // split
+a.phase(bias);                           // bias from 0 to 1; 0.5 is a π/2 phase on true
+a.iSwap(b, 0.5);                         // split again: the phase now moves probability
+// a.probability(true) is 0 at bias 0, 0.5 at bias 0.5, 1 at bias 1
 ```
 
+A phase before a single split changes nothing. It needs a later superpose or interaction to turn into probability.
+
 **Grover oracle** (walls/barriers): mark states with π phase, then diffuse with fractional Hadamard. Probability "bounces off" marked states.
 
 ```typescript
-m.phase_rotate([hexProp.is(wallState)], Math.PI); // mark
-m.hadamard(hexProp, 0.1); // diffuse
+phaseRotate(Math.PI, { when: [hex.is(wallState)] }); // mark
+hex.superpose(0.1);                                  // diffuse
 ```
 
-**Key insight:** Phase is the control knob that lets players influence quantum outcomes without directly choosing them. The player can't pick which ball exists, but they can bias the odds by applying phase before the next entanglement interaction.
+**Key insight:** Phase is the control knob that lets players influence quantum outcomes without directly choosing them. The player can't pick which ball exists, but they can bias the odds by applying phase between two interactions.
 
-### Visualizing Phase
+### Visualizing phase
 
 Extract from the reduced density matrix:
 
 ```typescript
-const rdm = m.reduced_density_matrix([propRef, propTarget]);
-for (const entry of rdm) {
-  if (entry.row_values[0] === 1 && entry.row_values[1] === 0 &&
-      entry.col_values[0] === 0 && entry.col_values[1] === 1) {
-    const phase = Math.atan2(entry.value.imag, entry.value.real);
+for (const entry of densityMatrix(ref, target)) {
+  if (entry.row[0] === true && entry.row[1] === false &&
+      entry.col[0] === false && entry.col[1] === true) {
+    const phase = Math.atan2(entry.imag, entry.real);
     // Map to dial rotation, color hue, force magnitude, compass direction
   }
 }
 ```
 
-## Recording & Replay
+## Lifecycle
+
+`dispose()` is the only lifecycle call. It measures the property, which collapses anything
+entangled with it. A qudit that is then alone is reset and cached for the next `quantum()` of
+the same dimension; one that still shares a state is destroyed, which splits it out of the
+group. A reused handle never carries an old group.
+
+A `using` declaration disposes at scope exit. It needs TypeScript 5.2+ with `"ESNext.Disposable"`
+in the tsconfig `lib`; scaffolded projects have both.
+
+The engine's `EntityManager.remove()` and `clear()` dispose handles stored directly on an entity
+(string or symbol keys) or in an array field on it, and `add()` disposes the handles of an
+entity it replaces that the new entity no longer carries. Removing an entity therefore
+collapses whatever its handles were entangled with. A handle belongs to one entity. Pass
+`{ disposeQuantum: false }` to keep the handles.
+
+## Recording and replay
+
+`QuantumRecorder` logs every operation on `quantum()` handles so you can save a session and rebuild its quantum state later, for replays, bug reports or deterministic tests. It listens through `observeQuantum()`, so the game makes no extra calls once recording has started.
 
 ```typescript
-import { QuantumRecorder } from "quantum-forge/quantum";
+import { QuantumRecorder, quantum, measure } from "quantum-forge/quantum";
 
-const recorder = new QuantumRecorder(qpm);
+const recorder = new QuantumRecorder();
 recorder.startRecording();
-// ... operations ...
-const log = recorder.getOperationLog(); // serializable JSON (also returned by stopRecording())
-// Save: localStorage.setItem("quantum-save", JSON.stringify(log));
-// Load: recorder.replayLog(JSON.parse(saved)); // forced measurements
+const a = quantum([false, true]);
+const b = quantum([false, true]);
+a.superpose();
+b.flip({ when: [a.is(true)] });
+measure(a, b);
+const saved = QuantumRecorder.serialize(recorder.stopRecording());
+
+const handles = QuantumRecorder.replay(QuantumRecorder.deserialize(saved));
+const replayedA = handles.get(a.id);
 ```
 
+The log is plain JSON: `{ version: 1, entries: [...] }`. Entries name handles by their `id`, values by basis index, and operations by their physics name, so `superpose()` is logged as `hadamard` and `flip()` as `cycle`. `deserialize()` and `replay()` reject a log without that envelope or with any other version, and `deserialize()` checks every entry and throws on anything malformed.
+
+Replay creates a fresh handle for every `create` entry and returns a map from the logged id to the new handle. Handles the log disposes are not in the map. Every measurement is replayed as a forced measurement with the recorded outcome, so the rebuilt state matches the original, including entangled pairs. A recorder that is running during `replay()` records what the replay did, so a game can load a save and keep recording into one log.
+
+Start recording before creating the handles you want to replay. A handle created earlier has no `create` entry. The recorder warns once for each such handle and lists its id in the log's `untrackedIds`, and `replay()` refuses that log with an error naming the ids.
+
+`new QuantumRecorder()` takes no arguments. Passing one, as 2.x code did with a manager, throws and points to `LegacyQuantumRecorder`.
+
+Observers, the recorder included, cannot break the game. An error thrown inside an observer is caught and reported through `reportError()`, or `console.error` where the runtime lacks it, and the game call that triggered it goes on as normal. Observers receive operations in the order they ran.
+
 ## Performance
 
-**The one rule: pool your properties.** Measure → delete → release. Every time.
+Dispose handles when their object is gone, or let `EntityManager` do it. A disposed property
+stops counting against the qudit limit, so a game that keeps spawning and removing objects
+stays within it.
 
 Shipped limits: Qutrit Edition has dimension 3, 12 max qudits. Qubit Edition has dimension 2, 20 max qudits.
 
-| Active Properties | Performance |
-|-------------------|-------------|
-| 1–4 | No issues |
-| 4–8 | Good with pooling |
-| 8–12 | At the limit, aggressive pooling required |
-
-**Most expensive operation**: tensor product (triggered by iSwap between properties in different shared states). Pooled properties avoid this — they're already in the shared state.
+The most expensive operation is the tensor product, triggered the first time two properties in
+different shared states interact.
 
-**Strategies**: aggressive pooling, limit concurrent quantum objects, use dimension 2 unless needed, separate registries for independent systems, batch measurements, throttle probability queries.
+To stay fast: dispose promptly, limit concurrent quantum objects, use two values unless you
+need more, measure several properties in one `measure(a, b, c)` call, throttle probability
+queries. `prop.numActiveQudits()` and `prop.stateVectorSize()` report how big the shared state is.
 
 ```typescript
 // Monitor WASM memory
@@ -465,6 +460,7 @@ loop.start();
 
 Map probability to visual properties (opacity, size, color):
 
+<!-- sample:skip: method shown outside its class -->
 ```typescript
 protected draw(state: GameState) {
   for (const ball of state.balls) {
@@ -511,7 +507,7 @@ input.destroy();
 
 | Export | Key APIs |
 |--------|----------|
-| `./quantum` | `ensureLoaded`, `getModule`, `QuantumPropertyManager`, `QuantumRecorder`, `useQuantumForgeBuild`, `setWasmBasePath` |
+| `./quantum` | `quantum`, `Quantum`, `measure`, `probabilities`, `densityMatrix`, `measureWhen`, `phaseRotate`, `ensureLoaded`, `QuantumRecorder`, `useQuantumForgeBuild`, `setWasmBasePath` |
 | `./logging` | `Logger` |
 | `./vite-plugin` | `quantumForgeVitePlugin` |