quantum-forge 2.7.0 → 3.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 Real quantum mechanics for game developers. Superposition, entanglement, and interference powered by a compiled C++ quantum simulator running via WebAssembly.
 
-This is the core package — WASM loader, quantum property manager, and Vite plugin. For the full game framework (engine, rendering, input, audio, etc.), install [`quantum-forge-engine`](https://www.npmjs.com/package/quantum-forge-engine) instead.
+This is the core package: WASM loader, quantum property handles, and Vite plugin. For the full game framework (engine, rendering, input, audio, and more), install [`quantum-forge-engine`](https://www.npmjs.com/package/quantum-forge-engine) instead. It depends on this package, so one install gets both.
 
 ## Install
 
@@ -26,51 +26,60 @@ export default defineConfig({
 
 > **ESM note:** If using `vite.config.js` (not `.ts` or `.mjs`), add `"type": "module"` to your `package.json`.
 
-### 2. Use Quantum Mechanics
+### 2. Declare a quantum property
 
 ```typescript
-import { ensureLoaded, QuantumPropertyManager } from "quantum-forge/quantum";
+import { ensureLoaded, quantum } from "quantum-forge/quantum";
 
-// Initialize WASM (call once at startup)
-await ensureLoaded();
-
-// Create a property manager
-const qpm = new QuantumPropertyManager({ dimension: 2 });
+await ensureLoaded(); // once, before the first quantum() call
 
-// Create a qubit and put it in superposition
-const qubit = qpm.acquireProperty();
-qpm.hadamard(qubit);
+const color = quantum(["red", "green", "blue"]); // a qutrit, starts "red"
+color.superpose();                               // equal superposition (alias for hadamard())
 
-// Read probabilities (no collapse)
-const probs = qpm.probabilities(qubit); // [~0.5, ~0.5]
+// Read without collapsing
+color.probability("green");  // 1/3
+color.probabilities();
+// [{ value: "red", probability: 1/3 }, { value: "green", ... }, { value: "blue", ... }]
 
-// Measure (collapses to 0 or 1)
-const [value] = qpm.measureProperties([qubit]);
+// Measure (collapses to one value)
+const seen = color.measure(); // "red", "green" or "blue"
 
-// Recycle for reuse
-qpm.releaseProperty(qubit, value);
+// End its life. dispose() measures, then frees the qudit for the next quantum() call.
+color.dispose();
 ```
 
+A property is declared by the values it can take, and the dimension is how many there are.
+`quantum(3)` is the numeric form, with values `0`, `1`, `2`. A property needs at least two
+values. A `using` declaration disposes the handle at the end of the scope; it needs TypeScript
+5.2 or newer with `"ESNext.Disposable"` in the tsconfig `lib`. Code that never writes `using`
+needs neither.
+
 ### 3. Entanglement
 
+Entanglement is what an interaction leaves behind. A gate that touches two properties is an
+interaction:
+
 ```typescript
-const a = qpm.acquireProperty();
-const b = qpm.acquireProperty();
+import { quantum, measure } from "quantum-forge/quantum";
 
-qpm.hadamard(a);
-qpm.iSwap(a, b); // Entangle — measuring one determines the other
+const a = quantum([false, true]).flip(); // a = true
+const b = quantum([false, true]);        // b = false
+a.iSwap(b, 0.5);                         // half iSwap: exactly one of the pair ends up true
 
-const [va, vb] = qpm.measureProperties([a, b]);
-// va and vb are always anti-correlated
+const [va, vb] = measure(a, b);          // one step, both collapse
+// va !== vb, every time
 ```
 
+So is a gate whose predicate reads another property. `b.flip({ when: [a.is(true)] })` is a
+CNOT: `b` flips only where `a` is `true`. `a.is(1)` builds the same predicate by index.
+
 ## Editions
 
 Two WASM builds are included:
 
 | Edition | Dimensions | Max Qudits | Use Case |
 |---------|-----------|------------|----------|
-| **Qutrit** (default) | 2–3 | 12 | Games using qutrits (3-state quantum digits) |
+| **Qutrit** (default) | 2 to 3 | 12 | Games using qutrits (3-state quantum digits) |
 | **Qubit** | 2 | 20 | Games needing more qubits at dimension 2 |
 
 To use the Qubit Edition:
@@ -78,31 +87,58 @@ To use the Qubit Edition:
 ```typescript
 import { useQuantumForgeBuild, ensureLoaded } from "quantum-forge/quantum";
 
-useQuantumForgeBuild("qubit"); // Call before ensureLoaded()
+useQuantumForgeBuild("qubit"); // before ensureLoaded()
+await ensureLoaded();
+```
+
+## Node and headless use
+
+The same code runs in Node (tests, servers, agents) with no Vite plugin. The loader finds the WASM inside the installed package, and `useQuantumForgeBuild("qubit")` picks the variant the same way. Point the loader elsewhere only when the WASM files live outside the package:
+
+```typescript
+import { setWasmBasePath, ensureLoaded } from "quantum-forge/quantum";
+import { pathToFileURL } from "node:url";
+
+setWasmBasePath(pathToFileURL("/opt/wasm/quantum-forge-qubit").href);
 await ensureLoaded();
 ```
 
+Node 22 or newer.
+
 ## Package Exports
 
 | Export | Contents |
 |--------|----------|
-| `quantum-forge/quantum` | `ensureLoaded`, `QuantumPropertyManager`, `QuantumRecorder`, `useQuantumForgeBuild` |
+| `quantum-forge/quantum` | `quantum`, `Quantum`, `measure`, `forcedMeasure`, `probabilities`, `densityMatrix`, `measureWhen`, `forcedMeasureWhen`, `probabilityWhen`, `phaseRotate`, `isQuantum`, `observeQuantum`, `clearQuantumCache`, `QuantumRecorder`, `ensureLoaded`, `startBackgroundLoad`, `isReady`, `useQuantumForgeBuild`, `setWasmBasePath`, `getVersion`, `getMaxDimension`, `getMaxQudits`, `getMaxStateSize`, `getAttribution`, `registerServiceWorker`, `OP` |
 | `quantum-forge/logging` | `Logger` |
 | `quantum-forge/vite-plugin` | `quantumForgeVitePlugin` |
 
 ## Gates
 
-| Gate | Qudits | Description |
-|------|--------|-------------|
-| `hadamard` | 1 | Equal superposition |
-| `cycle` | 1 | Deterministic rotation: \|0⟩→\|1⟩→\|2⟩→\|0⟩ |
-| `clock` (Z) | 1 | Phase rotation |
-| `shift` (X) | 1 | Value shift |
-| `y` | 1 | Y gate (qubit-only) |
-| `iSwap` | 2 | Entangling swap |
-| `swap` | 2 | Value swap |
-
-All gates support fractional application and conditional predicates.
+Gates are methods on the handle. Each alias runs exactly the same gate as the physics name
+beside it.
+
+| Gate | Alias | Qudits | Description |
+|------|-------|--------|-------------|
+| `hadamard` | `superpose` | 1 | Equal superposition |
+| `inverseHadamard` | | 1 | Undoes `hadamard` |
+| `cycle` | `next`, and `flip` on qubits | 1 | \|0⟩→\|1⟩→\|2⟩→\|0⟩ (a NOT at dimension 2) |
+| `shift` | `previous` | 1 | Inverse of cycle; same as cycle at dimension 2 |
+| `clock` | `phase` | 1 | Phase rotation |
+| `x`, `z` | | 1 | Pauli X (same as `shift`) and Pauli Z (same as `clock`) |
+| `y` | | 1 | Pauli Y, dimension 2 only |
+| `iSwap(other, fraction)` | | 2 | Entangling swap; `fraction` is required |
+| `swap(other)` | | 2 | Value swap |
+| `phaseRotate(angle, { when })` | | any | Free function: phase on the part of the state where the predicates hold |
+
+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. Predicates go last, in `{ when: [...] }`.
+
+Measurement: `prop.measure()`, `measure(...props)`, `measureWhen(preds)`, and the forced
+variants for replays and tests, which throw if the forced value has zero probability.
+Read-only: `prop.probability(value)`, `prop.probabilities()`,
+`probabilities(...props)`, `probabilityWhen(preds)`, `densityMatrix(...props)`.
 
 ## Documentation
 
@@ -112,4 +148,4 @@ All gates support fractional application and conditional predicates.
 
 ## License
 
-TypeScript source: MIT (see [LICENSE.md](./LICENSE.md)). WASM binaries: proprietary — free for apps under $100K annual revenue with attribution. See [dist/LICENSE-BINARY.md](./dist/LICENSE-BINARY.md) for binary terms.
+TypeScript source: MIT (see [LICENSE.md](./LICENSE.md)). WASM binaries: proprietary, free for apps under $100K annual revenue with attribution. See [dist/LICENSE-BINARY.md](./dist/LICENSE-BINARY.md) for binary terms.