@descix/egpt-math-sdk 0.1.0

package/dist/notebooks/fft.html

@@ -0,0 +1,155 @@
+<frqtl-notebook version="1" title="EGPT FFT — Polynomial Forward/Inverse Transform in Canonical Space">
+
+<cell type="markdown">
+# EGPT FFT — Polynomial Forward/Inverse Transform in Canonical Space
+
+The `EGPTFFT` class is the pedagogical entry point to EGPT's transform discipline.
+Where a classical FFT works in floating-point complex arithmetic (`e^{2πik/N}` twiddles, `sin`/`cos` calls), the EGPT formulation stays entirely in **rational canonical space**:
+
+- **Forward transform** — Horner-evaluate the coefficient polynomial `P(x)` at the `N` equally-spaced rational nodes `x_k = k/N` for `k = 0, 1, …, N−1`.
+- **Inverse transform** — recover the original coefficients from those N sample values via Newton divided differences.
+
+Both operations are **O(N²)** in exact `EGPTReal` arithmetic. No `Math.sin`, no `Math.cos`, no floating-point rounding. The round-trip `inverse(forward(c)) ≡ c` is a structural fact proved in the theorem file `F_FFTPolynomialIsomorphism.js`, not a numerical approximation.
+
+Every cell below computes through the injected `math` builtin. No URL imports.
+</cell>
+
+<cell type="js" lane="math" id="backend">
+// Show the active math backend (truth-in-labeling: derived, never asserted).
+const { math, display } = caps;
+const backend = math.activeMathBackend;
+display(`Active math backend (derived from SDK registry): ${backend}`);
+</cell>
+
+<cell type="markdown">
+## 1. Build the input — three integer coefficients
+
+We start with the polynomial `P(x) = 1 + 2x + 3x²` represented as an array of
+`EGPTReal` values. `EGPTReal.fromBigInt(n)` constructs the exact canonical
+representation of the integer `n` (no floating-point, no approximation).
+</cell>
+
+<cell type="js" lane="math" id="build-coeffs" out="coeffs">
+const { math, display } = caps;
+const { EGPTReal } = math;
+
+// P(x) = 1 + 2x + 3x²
+const coeffs = [
+  EGPTReal.fromBigInt(1n),
+  EGPTReal.fromBigInt(2n),
+  EGPTReal.fromBigInt(3n)
+];
+
+display('Coefficients (toMathString): ' + coeffs.map(c => c.toMathString()).join(', '));
+return { coeffs };
+</cell>
+
+<cell type="markdown">
+## 2. Forward transform — evaluate at rational nodes 0/3, 1/3, 2/3
+
+`EGPTFFT.forward(coeffs, N)` evaluates `P(x)` at each of the `N` nodes `k/N`
+using Horner's method in canonical space:
+
+```
+P(0/3) = 1 + 2·(0) + 3·(0)² = 1
+P(1/3) = 1 + 2·(1/3) + 3·(1/3)² = 1 + 2/3 + 1/3 = 2
+P(2/3) = 1 + 2·(2/3) + 3·(2/3)² = 1 + 4/3 + 4/3 = 11/3
+```
+
+These are exact rational results — no approximation.
+</cell>
+
+<cell type="js" lane="math" id="forward" in="coeffs" out="forward">
+const { math, display } = caps;
+const { EGPTFFT } = math;
+const { coeffs } = inputs;
+
+const forward = EGPTFFT.forward(coeffs, 3);
+
+display('Forward transform values at k/3 (toMathString):');
+forward.forEach((v, k) => {
+  display(`  P(${k}/3) = ${v.toMathString()}`);
+});
+
+return { forward };
+</cell>
+
+<cell type="markdown">
+## 3. Inverse transform — recover the original coefficients
+
+`EGPTFFT.inverse(values, N)` runs Newton divided differences on the N sample values
+and reconstructs the polynomial coefficient vector. The result must be
+bit-identical to the original `[1, 2, 3]` — not approximately equal, **exactly equal**
+in `EGPTReal` canonical arithmetic.
+</cell>
+
+<cell type="js" lane="math" id="inverse" in="forward" out="inverse">
+const { math, display } = caps;
+const { EGPTFFT } = math;
+const { forward } = inputs;
+
+const inverse = EGPTFFT.inverse(forward, 3);
+
+display('Recovered coefficients (toMathString):');
+inverse.forEach((c, i) => {
+  display(`  c[${i}] = ${c.toMathString()}`);
+});
+
+return { inverse };
+</cell>
+
+<cell type="markdown">
+## 4. Round-trip verification
+
+The original polynomial was `[1, 2, 3]`. After `forward` then `inverse` we expect
+to get exactly `["1", "2", "3"]` from `toMathString()`. Any deviation would be a
+violation of the polynomial bijection theorem `F2: inverse ∘ forward ≡ identity`.
+</cell>
+
+<cell type="js" lane="math" id="verify" in="inverse">
+const { math, display } = caps;
+const { inverse } = inputs;
+
+const expected = ['1', '2', '3'];
+const got = inverse.map(c => c.toMathString());
+
+const ok = got.length === expected.length &&
+           got.every((v, i) => v === expected[i]);
+
+const el = document.createElement('div');
+el.style.cssText =
+  'font:600 0.95rem/1.5 system-ui,sans-serif;padding:10px 14px;border-radius:6px;margin:4px 0;' +
+  (ok
+    ? 'background:#0f2417;border:1px solid #1f5a36;color:#7ee2a8;'
+    : 'background:#2a0c0c;border:1px solid #5a1f1f;color:#ff8a8a;');
+el.textContent = ok
+  ? `ROUND-TRIP VERIFIED: inverse(forward([1,2,3])) = [${got.join(', ')}] — bit-exact.`
+  : `MISMATCH: expected [${expected.join(', ')}], got [${got.join(', ')}]`;
+
+display(el);
+
+if (!ok) {
+  throw new Error('FFT forward/inverse roundtrip failed');
+}
+</cell>
+
+<cell type="markdown">
+## 5. What makes this different from a classical FFT?
+
+| | Classical FFT | EGPT FFT |
+|---|---|---|
+| Twiddle factors | `e^{2πik/N}` — transcendental, computed via `sin`/`cos` | `k/N` — exact rational nodes, no transcendentals |
+| Arithmetic domain | Complex floating-point (`float64`) | Canonical `EGPTReal` (exact BigInt rationals) |
+| Round-trip error | Floating-point accumulation (`~1e-15`) | Zero — `inverse(forward(c))` is exactly `c` |
+| Complexity | `O(N log N)` via Cooley-Tukey twiddle caching | `O(N²)` Horner + Newton DD in rational space |
+| Purpose | Signal processing via approximation | Polynomial bijection — transform as exact algebraic operation |
+
+The EGPT FFT is not competing with Cooley-Tukey on wall-clock speed for large N.
+Its role is to make the polynomial ↔ transform bijection visible and provable:
+evaluating `P` at `N` nodes and recovering `P` from those values is a bijection —
+`inverse ∘ forward = identity` — with no approximation involved.
+This is the foundation for the CNF ↔ polynomial isomorphism (BIPP theorem)
+and the matrix ↔ ℕ chain (Translation1–7).
+</cell>
+
+</frqtl-notebook>

package/dist/notebooks/frqtl-qft-benchmark.html

@@ -0,0 +1,207 @@
+<frqtl-notebook version="1" title="A Quantum Computer That Runs in Your Browser — FRQTL QFT Benchmark">
+
+<cell type="markdown">
+# A Quantum Computer That Runs in Your Browser
+
+**White Paper:** *Logarithmic Root Finding — A Deterministic, EGPT-Native, efficiently and classically computable QFT.* E. Abadir, Electronic Graph Paper Theory (EGPT) Research Group.
+
+Shor's factoring algorithm has three stages: classical setup, **the Quantum Fourier Transform** (the one step believed to need quantum hardware), and classical post-processing. This notebook computes that QFT step **deterministically, classically, in this browser tab** — and benchmarks it head-to-head against a published large-scale supercomputer Shor simulation.
+
+Every cell below reaches its math through one injected capability — `math` — and imports nothing. `math` is the live FRQTL math SDK the IDE resolved; the backend that actually executes is reported by the SDK itself, never asserted.
+</cell>
+
+<cell type="js" lane="math" id="backend">
+// The ONLY way a cell gets compute: ask the injected builtin BY NAME.
+// activeMathBackend is a DERIVED field — it reports whatever
+// MathBackendRegistry.active() is (wasm-math under audience='public').
+const { math, display } = caps;
+const backend = math.activeMathBackend;
+display(`Live math backend (derived from the SDK): ${backend}`);
+</cell>
+
+<cell type="markdown">
+## 1. Reframing the QFT in information space
+
+Classical statevector simulation of the QFT scales as `O(2^n)` memory and `O(n·2^n)` operations — the exponential wall a supercomputer hit at 39 bits. EGPT sidesteps statevector simulation entirely: a number `k` is bijective to its information vector `H(k) = log2(k)`, and the RET Iron Law gives `H(p×q) = H(p) + H(q)`. Period extraction becomes a deterministic operation in lossless information space, not a search over a `2^n` Hilbert space.
+</cell>
+
+<cell type="markdown">
+## 2. The Logarithmic Root Finding algorithm
+
+Two quantum steps are replaced by deterministic EGPT analogues:
+
+- **Superposition → logarithmic decomposition.** Recursively apply `log2` to `H(k)` for `n = ceil(log2 k)` steps, distilling `L_final = H(H(...H(k)...))`.
+- **QFT → deterministic period extraction.** The order is read directly as `r ~ floor(H(k) / L_final)`, then probed in a small even neighborhood.
+- **Factor extraction (classical Shor tail).** Compute `y = a^(r/2) mod k`; recover factors via `gcd(y±1, k)` (Pollard p-1 packaged in refinement).
+
+Complexity: `O((log k)^3)` — polynomial in the bit length, where statevector simulation is exponential.
+</cell>
+
+<cell type="markdown">
+## 3. The benchmark baseline — a published supercomputer result
+
+We benchmark against the largest published statevector simulation of Shor's algorithm. All figures below are read from the SDK's single baseline authority (`math.benchmarks.qftBaseline`) — this notebook inlines no numbers.
+</cell>
+
+<cell type="js" lane="math" id="baseline">
+// Render the published baseline FROM THE SINGLE AUTHORITY.
+// Reads math.benchmarks.qftBaseline by name; FAIL-LOUD if absent. No literal.
+const { math, display } = caps;
+const b = math.benchmarks && math.benchmarks.qftBaseline;
+if (!b) {
+  throw new Error(
+    '[notebook] math.benchmarks.qftBaseline is absent — the benchmark must ' +
+    'not narrate against a missing baseline. The figures live in ONE authority ' +
+    '(qft-benchmark-baseline.js), surfaced on the SDK as math.benchmarks.qftBaseline. ' +
+    '(FAIL-LOUD — never an inlined literal, never a silent blank.)'
+  );
+}
+const c = b.citation;
+const lines = [
+  `Published result: ${c.authors}`,
+  `  "${c.title}." ${c.venue}, ${c.year}. DOI: ${c.doi}`,
+  `Hardware: ${b.hardware.system}`,
+  `          ${b.hardware.gpus}, ${b.hardware.memory}`,
+  `What was computed: ${b.whatWasComputed}`,
+  `Total study compute: ${b.studyCompute.gpuYears} GPU-years ` +
+    `(${b.studyCompute.coreYears} core-years)`,
+  `Benchmark run: N=${b.benchmarkRun.N} = ${b.benchmarkRun.factors.join(' x ')} ` +
+    `(${b.benchmarkRun.bits}-bit) — ~${b.benchmarkRun.shorGpuSeconds}s per run on the supercomputer`
+];
+display(lines.join('\n'));
+</cell>
+
+<cell type="markdown">
+## 4. Run it here — the same computation, in your browser
+
+The next cell drives the **same** `FraqtlSession` the catalog benchmark entry drives (`math.FraqtlSession.auto()` → `session.run(N)`), on the same math backend, through the same seam. The factors it returns are bit-identical to the entry's. We time the live run with `performance.now()` (the human-facing wall-clock — never part of any byte-stable comparison).
+</cell>
+
+<cell type="js" lane="math" id="run" out="run">
+// THE DOGFOOD: drive the SAME computation as the catalog entry.
+// math.FraqtlSession.auto() is the exact object the entry's run(sdk) uses.
+const { math, display } = caps;
+const b = math.benchmarks.qftBaseline;
+// N comes from the baseline authority's benchmarkRun — the SAME semiprime the
+// supercomputer factored. No inlined literal (value lives in the authority).
+const N = b.benchmarkRun.N;
+const session = math.FraqtlSession.auto();
+
+const t0 = performance.now();
+const result = session.run(N);          // identical path to the entry
+const elapsedMs = (typeof result.elapsed_ms === 'number')
+  ? result.elapsed_ms
+  : (performance.now() - t0);
+
+const run = {
+  N,
+  factors: result.factors,
+  successful: result.successful,
+  post_reason: result.post_reason,
+  elapsedMs,
+  backend: math.activeMathBackend       // DERIVED
+};
+display(run);
+return { run };
+</cell>
+
+<cell type="js" lane="math" id="verify" in="run">
+// The AC assertion: factors match the baseline authority's factors,
+// bit-identical to the catalog entry. Renders PASS/FAIL plainly.
+const { math, display } = caps;
+const run = inputs.run;
+const b = math.benchmarks.qftBaseline;
+const expected = b.benchmarkRun.factors;          // from the single authority
+const got = (run.factors || []).slice().sort((x, y) => x - y);
+const want = expected.slice().sort((x, y) => x - y);
+const ok = got.length === want.length && got.every((v, i) => v === want[i]);
+
+const el = document.createElement('div');
+el.style.cssText =
+  'font:600 0.95rem/1.5 system-ui,sans-serif;padding:10px 14px;border-radius:6px;margin:4px 0;' +
+  (ok
+    ? 'background:#0f2417;border:1px solid #1f5a36;color:#7ee2a8;'
+    : 'background:#2a0c0c;border:1px solid #5a1f1f;color:#ff8a8a;');
+el.textContent = ok
+  ? `FACTORS VERIFIED on ${run.backend}: ${run.N} = ${run.factors.join(' x ')} ` +
+    `— bit-identical to the catalog benchmark entry and to the supercomputer's result.`
+  : `MISMATCH: got [${run.factors}], expected [${expected}] on ${run.backend}.`;
+display(el);
+</cell>
+
+<cell type="js" lane="math" id="comparison" in="run">
+// THE COMPARISON BAR + LIVE WALL-CLOCK. Baseline figures read from
+// math.benchmarks.qftBaseline ONLY. Wall-clock is the TIMING channel
+// (human-facing, excluded from comparison). DOM built directly.
+const { math, display } = caps;
+const run = inputs.run;
+const b = math.benchmarks.qftBaseline;
+const coreYears = b.studyCompute.coreYears;
+const gpuYears = b.studyCompute.gpuYears;
+const shorSecs = b.benchmarkRun.shorGpuSeconds;     // supercomputer s/run
+const bits = b.benchmarkRun.bits;
+const browserMs = run.elapsedMs;                    // live wall-clock (TIMING)
+const browserSecs = browserMs / 1000;
+
+const speedup = shorSecs / Math.max(browserSecs, 1e-9);
+
+const wrap = document.createElement('div');
+wrap.style.cssText = 'font:0.85rem/1.4 system-ui,sans-serif;color:#ddd;margin:6px 0;max-width:680px;';
+
+const head = document.createElement('div');
+head.style.cssText = 'font-weight:600;color:#fff;margin-bottom:8px;font-size:0.95rem;';
+head.textContent = `${bits}-bit QFT period extraction — wall-clock, this run vs. the supercomputer`;
+wrap.appendChild(head);
+
+function bar(label, valueText, fillPct, color) {
+  const row = document.createElement('div');
+  row.style.cssText = 'margin:6px 0;';
+  const lab = document.createElement('div');
+  lab.style.cssText = 'display:flex;justify-content:space-between;margin-bottom:2px;';
+  const l = document.createElement('span'); l.textContent = label;
+  const v = document.createElement('span'); v.style.color = '#aaa'; v.textContent = valueText;
+  lab.appendChild(l); lab.appendChild(v); row.appendChild(lab);
+  const track = document.createElement('div');
+  track.style.cssText = 'background:#1a1a1a;border-radius:4px;height:18px;overflow:hidden;';
+  const fill = document.createElement('div');
+  fill.style.cssText =
+    `background:${color};height:100%;width:${Math.max(fillPct, 0.6)}%;border-radius:4px;transition:width .3s;`;
+  track.appendChild(fill); row.appendChild(track);
+  return row;
+}
+
+const maxLog = Math.log10(Math.max(shorSecs, browserSecs, 1) + 1);
+const shorPct = (Math.log10(shorSecs + 1) / maxLog) * 100;
+const browserPct = (Math.log10(browserSecs + 1) / maxLog) * 100;
+
+wrap.appendChild(bar(
+  `Supercomputer (${b.hardware.gpus})`,
+  `~${shorSecs}s/run`, shorPct, '#c0584f'
+));
+wrap.appendChild(bar(
+  `This browser tab (${run.backend})`,
+  `~${browserSecs < 1 ? browserMs.toFixed(0) + 'ms' : browserSecs.toFixed(2) + 's'}`,
+  browserPct, '#4f9fc0'
+));
+
+const foot = document.createElement('div');
+foot.style.cssText = 'margin-top:10px;color:#bbb;font-size:0.8rem;line-height:1.5;';
+foot.innerHTML =
+  `Per-run wall-clock speedup on this hardware: <b style="color:#7ee2a8;">~${Math.round(speedup).toLocaleString()}x</b>. ` +
+  `The published study consumed <b>${gpuYears} GPU-years (${coreYears} core-years)</b> of compute; ` +
+  `this run finished in <b>${browserSecs < 1 ? browserMs.toFixed(0) + ' ms' : browserSecs.toFixed(2) + ' s'}</b> ` +
+  `on one browser tab. <span style="color:#888;">(Live wall-clock — the TIMING channel, human-facing, excluded from any byte-stable comparison.)</span>`;
+wrap.appendChild(foot);
+
+display(wrap);
+</cell>
+
+<cell type="markdown">
+## If the QFT is classically efficient, "quantum advantage" evaporates
+
+The factorization above ran the QFT period-extraction step — the one part of Shor's algorithm believed to require a quantum computer — deterministically, in polynomial time, in this browser tab. The classical setup and post-processing stages are common to both paths. With the QFT step neutralized, the relevant factoring frontier is classical (GNFS and friends), which remains informationally near-optimal. Internet security does not rest on the unavailability of qubit hardware.
+
+*Same computation, two surfaces:* this notebook and the catalog benchmark entry drive the identical `FraqtlSession` through the identical shim seam — the factors are bit-identical. Reference: Willsch et al., *Mathematics* 2023, 11, 4222 (see the baseline cell for the full citation, surfaced from the SDK).
+</cell>
+
+</frqtl-notebook>

package/dist/notebooks/gallery-atomic-model.html

@@ -0,0 +1,51 @@
+<frqtl-notebook version="1" title="Atomic Model — stable orbits without quantum numbers">
+
+<cell type="markdown">
+# Atomic Model
+
+**Stable orbits emerge — no electron shells, no quantum numbers.**
+
+Particles collide and merge into stable bound structures that persist for thousands of ticks. There are no electron shells, no principal quantum numbers, no Bohr radius — only leaf Frames making local greedy choices and the single-occupancy collision rule.
+
+**Why this is impossible (classically):** Stable atomic orbits require quantized energy levels — continuous mechanics predicts spiral decay (the classical electron should radiate and crash into the nucleus). Here the bound structures stay stable because the discrete 1-pixel-per-tick rule and emergent momentum conservation forbid the spiral.
+
+The experiment setup is **real, editable user code**: the module cell `./setups/atomic-model.js` is a thin adapter over the CANONICAL setup factory (`lib/frqtl/objects/setup/setupAtomicModel.js`, the SAME construction the standalone Gallery exhibit and any experiment page drive) — it builds the proton/atom frame hierarchy and the orbiting electron from `Frame`/`Charge`/`Rectangle`. The **canvas cell** below DECLARES that module (`setup="./setups/atomic-model.js#setupAtomicModel"`) plus its config; the shim synthesizes and runs the builder boilerplate. Nothing runs on load — click **Run** on the canvas (or **Run All**).
+
+*New to FRQTL? Start with **Hello, FRQTL** (`getting-started-hello-frqtl`) for the `caps.frqtl` setup-module + declarative-canvas basics this notebook assumes.*
+
+**Edit the physics:** open the `./setups/atomic-model.js` tab and pass an option override to the canonical factory — e.g. change the adapter's `Object.assign({ canvasRect: universe.universe_rect }, options)` call to `Object.assign({ canvasRect: universe.universe_rect, quarksPerProton: 12, includeElectron: false }, options)` — then re-Run. The emergent bound structure changes because you edited the construction, not a label.
+</cell>
+
+<cell type="module" name="./setups/atomic-model.js">
+/* setupAtomicModel — THIN ADAPTER over the canonical setup factory
+ * (WS gym-controls-as-sugar Bite 0: this cell used to hand-copy the physics —
+ * a divergent fork of lib/frqtl/objects/setup/setupAtomicModel.js that had
+ * already drifted onto a stale `universe.init(...)` positional-argument call the
+ * engine now FAIL-LOUDs on, and was missing the canonical `noObserverFrame: true`
+ * init option. The canonical factory is imported by BARE SPECIFIER (a relative
+ * path here would 404 — see lib/shim/notebook/frqtl-setups-importmap.js); this
+ * cell only bridges the notebook builder's `(frqtl, universe, options)` call
+ * shape to the factory's `(universe, options)` shape — ZERO physics here. The
+ * canonical factory reads `options.canvasRect`, not `universe.universe_rect`
+ * directly, so this adapter supplies it explicitly (matching the factory's own
+ * documented two-cell example).
+ */
+import { setupAtomicModel as _setupAtomicModel } from '@frqtl/setups/atomic-model';
+
+export function setupAtomicModel(frqtl, universe, options) {
+    options = options || {};
+    return _setupAtomicModel(universe, Object.assign({ canvasRect: universe.universe_rect }, options));
+}
+</cell>
+
+<cell type="canvas" id="c-atom-canvas" setup="./setups/atomic-model.js#setupAtomicModel" stage="480x480" seed="42"></cell>
+
+<cell type="markdown">
+## What you are seeing
+
+A dense central structure (the "nucleus") forms as particles merge, with lighter quanta settling into persistent surrounding orbits rather than collapsing inward. The stability is emergent — no force law holds the orbit together.
+
+The simulation runs live in your browser on the compiled FRQTL (WASM) engine. The same canonical sugar objects (`Frame`, `Charge`, `Rectangle`) and `ExperimentRunner` drive the standalone Gallery exhibit and this notebook cell — the difference is only that here the *assembly* is editable user code in the `./setups/atomic-model.js` tab, not an opaque system fetch.
+</cell>
+
+</frqtl-notebook>

package/dist/notebooks/gallery-big-bang.html

@@ -0,0 +1,62 @@
+<frqtl-notebook version="1" title="Big Bang — structure from nothing, no gravity law">
+
+<cell type="markdown">
+# Big Bang
+
+**Large-scale structure — filaments, voids, bound clumps — from a uniform particle field, with no gravity law anywhere.**
+
+A single radial point source fires quanta with zero initial velocity. Every outward movement is emergent: `emergentPhysics = true` means the engine uses top-down frame generation (Phase B `buildFramesFromSprites`) and Brownian motion, not directed launch vectors. Filaments and voids are a consequence of single-occupancy + the recursive compress nudge, nothing else.
+
+*New to FRQTL? Start with **Hello, FRQTL** (`getting-started-hello-frqtl`) for the `caps.frqtl` setup-module + declarative-canvas basics this notebook assumes.*
+</cell>
+
+<cell type="markdown">
+The experiment assembly — a single radial `PointSource` at canvas center — as editable user code:
+</cell>
+
+<cell type="module" name="./setups/big-bang.js">
+/* setupBigBang — THIN ADAPTER over the canonical setup factory
+ * (WS gym-controls-as-sugar Bite 0: this cell used to hand-copy the physics —
+ * a divergent fork of lib/frqtl/objects/setup/setupBigBang.js that had already
+ * drifted onto a stale `universe.init(...)` positional-argument call the engine
+ * now FAIL-LOUDs on. The canonical factory is imported by BARE SPECIFIER (a
+ * relative path here would 404 — see lib/shim/notebook/frqtl-setups-importmap.js);
+ * this cell only bridges the notebook builder's `(frqtl, universe, options)` call
+ * shape to the factory's `(universe, options)` shape — ZERO physics here.)
+ */
+import { setupBigBang as _setupBigBang } from '@frqtl/setups/big-bang';
+
+export function setupBigBang(frqtl, universe, options) {
+    return _setupBigBang(universe, options);
+}
+</cell>
+
+<cell type="markdown">
+Declare a canvas that runs it. `setup="<module>#<export>"` + `stage`/`seed`; the shim synthesizes and runs the builder boilerplate in the realm. Click **Run** (or **Run All**):
+</cell>
+
+<cell type="canvas" id="c-bb-canvas" setup="./setups/big-bang.js#setupBigBang" stage="480x480" seed="42"></cell>
+
+<cell type="markdown">
+## What you are seeing
+
+An initially smooth particle field develops texture: dense filaments thread between emptier voids, and bound clumps condense — the cosmic-web morphology — with no force equation driving the collapse. No Newtonian gravity, no `G`, no cosmological constant.
+
+**`lightSourceDiameter` is the primary knob.** It sets the outer radius of the emission ring. Because `minRadius: 2` fills inward, the total emitter count scales as `(radius / 2) × 72` (at the default 5° increment). Larger diameter → more initial quanta → larger emergent explosion:
+
+| `lightSourceDiameter` | Active quanta (~50 frames) | Field |
+|---|---|---|
+| 16 | ~21,000 | Tight compact cluster, few emergent Frame circles |
+| **64** (default) | ~79,000 | Well-developed explosion, prominent Frame hierarchy |
+| 128 | ~157,000 | Very large expansion; stack overflow observed at init (2k+ emitters) |
+
+The full sweep with screenshots is in [`docs/physics/big-bang-lightSourceDiameter.md`](../../docs/physics/big-bang-lightSourceDiameter.md).
+
+**`dispersionAngleIncrement`** (default 5°) sets the angular resolution of the ring: 5° = 72 rays, 10° = 36 rays. Larger values produce discrete spokes in the initial field.
+
+**`emergentPhysics = true` is the mode switch.** Setting it `false` disables top-down frame generation — the expansion collapses because there are no directed launch vectors to carry particles outward.
+
+**Edit the physics:** open the `./setups/big-bang.js` tab and pass an option override to the canonical factory — e.g. change the adapter's `_setupBigBang(universe, options)` call to `_setupBigBang(universe, Object.assign({ lightSourceDiameter: 32 }, options))` (also try `dispersionAngleIncrement` or `maxTicks`) — then re-Run. The emergent structure changes because you edited the construction. (The physics body itself lives in the canonical `lib/frqtl/objects/setup/setupBigBang.js` — this cell is a thin, engine-agnostic adapter over it.) The simulation runs live in your browser on the compiled FRQTL (WASM) engine.
+</cell>
+
+</frqtl-notebook>

package/dist/notebooks/gallery-blackbody.html

@@ -0,0 +1,52 @@
+<frqtl-notebook version="1" title="Blackbody — the Planck curve from collisions">
+
+<cell type="markdown">
+# Blackbody Radiation
+
+**The Planck curve emerges from collisions — no energy quanta assumed.**
+
+Particles bounce in a walled cavity. The frequency histogram converges to the Planck distribution. No discrete energy quanta, no Planck's constant inserted — the quantization is a consequence of the discrete pixel/tick lattice. Classically this is supposed to produce the Rayleigh-Jeans divergence (infinite energy at high frequencies); the discrete lattice cuts it off and yields the Planck curve instead.
+
+*New to FRQTL? Start with **Hello, FRQTL** (`getting-started-hello-frqtl`) for the `caps.frqtl` setup-module + declarative-canvas basics this notebook assumes.*
+</cell>
+
+<cell type="markdown">
+Bounce-walled oven cavity with thermostat — editable user code:
+</cell>
+
+<cell type="module" name="./setups/blackbody.js">
+/* setupBlackbody — THIN ADAPTER over the canonical setup factory
+ * (WS gym-controls-as-sugar Bite 0: this cell used to hand-copy the physics —
+ * a divergent fork of lib/frqtl/objects/setup/setupBlackbody.js that had
+ * already drifted onto a stale `universe.init(...)` positional-argument call the
+ * engine now FAIL-LOUDs on. The canonical factory is imported by BARE SPECIFIER
+ * (a relative path here would 404 — see lib/shim/notebook/frqtl-setups-importmap.js);
+ * this cell only bridges the notebook builder's `(frqtl, universe, options)` call
+ * shape to the factory's `(universe, options)` shape — ZERO physics here.)
+ */
+import { setupBlackbody as _setupBlackbody } from '@frqtl/setups/blackbody';
+
+export function setupBlackbody(frqtl, universe, options) {
+    return _setupBlackbody(universe, options);
+}
+</cell>
+
+<cell type="markdown">
+Declare a canvas that runs it. `setup="<module>#<export>"` + `stage`/`seed`; the shim synthesizes and runs the builder boilerplate in the realm. Click **Run** (or **Run All**):
+</cell>
+
+<cell type="canvas" id="c-bb-canvas" setup="./setups/blackbody.js#setupBlackbody" stage="480x480" seed="42"></cell>
+
+<cell type="markdown">
+## What you are seeing
+
+Particles bounce within the cavity, exchanging momentum on every collision. Energy redistributes across the population until the frequency distribution stabilizes — the emergent shape matches the Planck curve, not the diverging Rayleigh-Jeans prediction.
+
+**`temperature` is the driving knob.** It sets the thermostat's target `activeQuanta` count. The thermostat emits `floor((temperature - activeQuanta) / 4)` new leaf Frames per emitter per tick until the target is met, then silences all emitters that tick — a discrete proportional controller over quanta count. Raising `temperature` 300 → 4000 densifies the cavity from sparse scattered leaf dots to a near-saturated mass, increases compound-frame (non-leaf, merged) formation dramatically, and widens the escaped-radiation stream through the slit in both volume and angular spread. The captured sweep is in [`docs/physics/blackbody-temperature.md`](../../docs/physics/blackbody-temperature.md).
+
+Note: `temperature` is NOT energy or kinetic temperature in the continuous-mechanics sense — it is the integer target for `universe.activeQuanta`. The per-Frame oscillation wavelength (`wavelength = floor((capacity / mass) × WAVELENGTH_CONSTANT)`, Core Axiom §6) is unchanged by `temperature` directly; it is determined by the mass of each Frame, which grows as frames merge via collisions. Higher temperature → more collisions → larger compound frames → shorter oscillation wavelengths — the FRAQTL analog of Wien's displacement.
+
+**Edit the physics:** open the `./setups/blackbody.js` tab and pass an option override to the canonical factory — e.g. change the adapter's `_setupBlackbody(universe, options)` call to `_setupBlackbody(universe, Object.assign({ temperature: 3000 }, options))` (also try `boxFraction` or `slitHeight`) — then re-Run. The emergent frequency spectrum changes because you edited the construction, not a label. (The physics body itself lives in the canonical `lib/frqtl/objects/setup/setupBlackbody.js` — this cell is a thin, engine-agnostic adapter over it, so every other notebook and experiment page drives the SAME construction.) The simulation runs live in your browser on the compiled FRQTL (WASM) engine.
+</cell>
+
+</frqtl-notebook>

package/dist/notebooks/gallery-circuit-sat.html

@@ -0,0 +1,104 @@
+<frqtl-notebook version="1" title="Circuit SAT — the circuit finds its own satisfying assignment">
+
+<cell type="markdown">
+# Circuit SAT
+
+**A half-adder circuit evaluates itself — particle density, not a search algorithm, selects the truth-table row.**
+
+Leaf Frames flow through wire channels. Density-activated gates (XOR → SUM, AND → CARRY) open and close as quanta accumulate in their control regions. The circuit settles on the correct half-adder output for whatever `(inputA, inputB)` pair you set — with no DPLL, no backtracking, no enumeration of assignments.
+
+*New to FRQTL? Start with **Hello, FRQTL** (`getting-started-hello-frqtl`) for the `caps.frqtl` setup-module + declarative-canvas basics this notebook assumes.*
+</cell>
+
+<cell type="markdown">
+Wire/battery/resistor primitives — the reusable building blocks:
+</cell>
+
+<cell type="module" name="./setups/circuit-basic.js">
+/* createWire / createBattery / createResistor / setupCircuitBasic — THIN
+ * ADAPTERS over the canonical primitives
+ * (WS gym-controls-as-sugar Bite 0: this cell used to hand-copy the physics —
+ * a divergent fork of lib/frqtl/objects/setup/setupCircuitBasic.js that had
+ * already drifted onto a stale `universe.init(...)` positional-argument call
+ * the engine now FAIL-LOUDs on. The canonical primitives are imported by BARE
+ * SPECIFIER (a relative path here would 404 — see
+ * lib/shim/notebook/frqtl-setups-importmap.js); these wrappers only bridge this
+ * notebook's `(frqtl, universe, ...)` calling convention (matching every other
+ * setup module here) to the canonical `(universe, ...)` shape — ZERO physics.
+ *
+ * NOTE: `setupCircuitSAT` below is now a standalone adapter over the FULLY
+ * self-contained canonical `setupCircuitSAT` factory (which builds its own
+ * wires/batteries internally via its own canonical `setupCircuitBasic` import) —
+ * it no longer imports from this cell. This cell is kept as the "reusable
+ * building blocks" reference the notebook's own narrative describes.
+ */
+import {
+    createWire as _createWire,
+    createBattery as _createBattery,
+    createResistor as _createResistor,
+    setupCircuitBasic as _setupCircuitBasic
+} from '@frqtl/setups/circuit-basic';
+
+export function createWire(frqtl, universe, x1, y1, x2, y2, width, wallThickness, color) {
+    return _createWire(universe, x1, y1, x2, y2, width, wallThickness, color);
+}
+
+export function createBattery(frqtl, universe, sourceX, sourceY, sinkX, sinkY, amperage, terminalSize, fundamentalDim, voltage, channelWidth, wallThickness) {
+    return _createBattery(universe, sourceX, sourceY, sinkX, sinkY, amperage, terminalSize, fundamentalDim, voltage, channelWidth, wallThickness);
+}
+
+export function createResistor(frqtl, universe, x, y, length, channelWidth, outerWidth, horizontal, wallThickness, color) {
+    return _createResistor(universe, x, y, length, channelWidth, outerWidth, horizontal, wallThickness, color);
+}
+
+export function setupCircuitBasic(frqtl, universe, options) {
+    return _setupCircuitBasic(universe, options);
+}
+</cell>
+
+<cell type="markdown">
+The half-adder wiring — the canonical experiment factory (assembled from the same wire/battery primitives shown above, wired together inside `lib/frqtl/objects/setup/setupCircuitSAT.js`):
+</cell>
+
+<cell type="module" name="./setups/circuit-sat.js">
+/* setupCircuitSAT — THIN ADAPTER over the canonical setup factory
+ * (WS gym-controls-as-sugar Bite 0: this cell used to hand-copy the physics —
+ * a divergent fork of lib/frqtl/objects/setup/setupCircuitSAT.js that had
+ * already drifted onto a stale `universe.init(...)` positional-argument call
+ * the engine now FAIL-LOUDs on. The canonical factory is imported by BARE
+ * SPECIFIER (a relative path here would 404 — see
+ * lib/shim/notebook/frqtl-setups-importmap.js); this cell only bridges the
+ * notebook builder's `(frqtl, universe, options)` call shape to the factory's
+ * `(universe, options)` shape — ZERO physics here. The canonical factory is
+ * FULLY self-contained: it builds its own wires/batteries by importing the
+ * canonical setupCircuitBasic.js internally, so this adapter no longer needs
+ * `createWire`/`createBattery` from the sibling circuit-basic.js cell.)
+ */
+import { setupCircuitSAT as _setupCircuitSAT } from '@frqtl/setups/circuit-sat';
+
+export function setupCircuitSAT(frqtl, universe, options) {
+    return _setupCircuitSAT(universe, options);
+}
+</cell>
+
+<cell type="markdown">
+Declare a canvas that runs it. `setup="<module>#<export>"` + `stage`/`seed`; the shim synthesizes and runs the builder boilerplate in the realm. Click **Run** (or **Run All**):
+</cell>
+
+<cell type="canvas" id="c-csat-canvas" setup="./setups/circuit-sat.js#setupCircuitSAT" stage="480x480" seed="42"></cell>
+
+<cell type="markdown">
+## What you are seeing
+
+Particles emit from the four batteries (two per gate section) and flow left-to-right along wire channels. Each gate samples the density in two upstream control regions over a `windowTicks`-tick sliding average. When the average crosses `gateThreshold` (default 3) the gate body switches from `WALL` (blocking) to `NONE` (transparent); when it falls below `max(1, gateThreshold − 1)` it closes again (hysteresis). The `CircuitProbe` markers at 75 % of the canvas read the stabilized output without absorbing quanta — no search ever runs.
+
+**The driving parameter is the boolean `(inputA, inputB)` pair.** There is no continuous numeric sweep here — the four input combinations each produce a distinct rendered layout: dark channels when a battery is OFF, a dense particle cloud upstream of a closed gate, clear flow past an open gate. All four are verified correct at tick 1500 (see [`docs/physics/circuit-sat-overview.md`](../../docs/physics/circuit-sat-overview.md)).
+
+When `(A=1, B=1)` the XOR gate closes while the AND gate opens — quanta back-fill and spill visibly above the wire array as the circuit holds the `SUM=0, CARRY=1` result. This is the tell-tale of the `(1,1)` row: the XOR collision creates visible backpressure.
+
+**Gates converge after ~200–400 ticks** (one `windowTicks` window plus wire transit time). If you switch inputs mid-run via `setInputA` / `setInputB`, let it run another 400 ticks before reading the probe.
+
+**Edit the physics:** open the `./setups/circuit-sat.js` tab and pass an option override to the canonical factory — e.g. change the adapter's `_setupCircuitSAT(universe, options)` call to `_setupCircuitSAT(universe, Object.assign({ inputA: false, gateThreshold: 5 }, options))` (also try `emissionRate` or `wireWidth`) — then re-Run. The gate behavior changes because you edited the construction. (The physics body itself lives in the canonical `lib/frqtl/objects/setup/setupCircuitSAT.js` — this cell and `./setups/circuit-basic.js` are thin, engine-agnostic adapters over the canonical factories.) The simulation runs live in your browser on the compiled FRQTL (WASM) engine.
+</cell>
+
+</frqtl-notebook>