@descix/egpt-math-sdk 0.1.0

package/dist/notebooks/gallery-collision-matrix-3d.html

@@ -0,0 +1,51 @@
+<frqtl-notebook version="1" title="Collision Matrix 3D — the same density gradient, read in perspective">
+
+<cell type="markdown">
+# Collision Matrix 3D
+
+**Seven lanes of head-on collisions, distributed in a 3×3 grid of depth — the SAME density-vs-bounce-timing law as the 2D matrix, now visibly receding into the z axis.**
+
+Seven pairs of Dim-6 cube bodies (same voxel size, same capacity) launch head-on along X. Mass is swept on a log (powers-of-2) scale from 1 to capacity, giving density ρ ≈ 0.0002 … 1.0. The 2D collision-matrix arranges these lanes in a single column; this version distributes them in rows (Y) and columns (Z) so the perspective orbit camera reveals TRUE DEPTH — cubes at different Z recede convincingly, not just stack vertically. Engine bench C5 (z-axis bounce ≡ x-axis bounce) means this 3D distribution is architecturally free — no new engine behavior, only a different placement of the SAME physics.
+
+*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 — seven mass-swept lanes distributed in Y and Z — as a thin adapter over the canonical factory (see below):
+</cell>
+
+<cell type="module" name="./setups/collision-matrix-3d.js">
+/* setupCollisionMatrix3D — THIN ADAPTER over the canonical setup factory
+ * (WS gym-controls-as-sugar Bite 0 ADDENDUM, CEO 2026-07-03). Same Bite-0
+ * mechanism as every other de-forked notebook: 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 SAME canonical
+ * `lib/frqtl/objects/setup/setupCollisionMatrix3D.js` also drives the
+ * standalone `lib/frqtl/experiments/collision-matrix-3d/` page.
+ */
+import { setupCollisionMatrix3D as _setupCollisionMatrix3D } from '@frqtl/setups/collision-matrix-3d';
+
+export function setupCollisionMatrix3D(frqtl, universe, options) {
+    return _setupCollisionMatrix3D(universe, options);
+}
+</cell>
+
+<cell type="markdown">
+Declare a canvas that runs it. `render3d="true"` requests the three.js 3D renderer + perspective camera for this canvas (the notebook-realm mirror of an experiment page's `window._egpt3D = true;` opt-in). `renderOptions="shape=cube,colorScheme=roygbiv"` is the notebook-cell channel for the SAME `runner.setRenderOption('shape','cube')` / `('colorScheme','roygbiv')` calls the standalone page makes page-side beside `setup()` (WS gym-controls-as-sugar fix-loop #6 Finding B, 2026-07-04) — without it this canvas rendered soft default-shaded blobs instead of the shaded cube meshes the GYM/standalone page show; the render intent did not travel with the physics-only adapter. Click **Run** (or **Run All**):
+</cell>
+
+<cell type="canvas" id="c-cm3d-canvas" setup="./setups/collision-matrix-3d.js#setupCollisionMatrix3D" stage="480x480" seed="42" render3d="true" renderOptions="shape=cube,colorScheme=roygbiv"></cell>
+
+<cell type="markdown">
+## What you are seeing
+
+Seven pairs of cubes, arranged in a 3×3 grid facing the camera, collide head-on. Sparse (low-mass) lanes bounce almost instantly; dense (high-mass, near-capacity) lanes linger before separating — the SAME per-tick occupancy-ceiling law the 2D collision-matrix demonstrates, now visible with true perspective depth: cubes further back in Z genuinely recede, rather than merely stacking on a flat plane.
+
+**Compare to the 2D version** (`collision-matrix`): identical physics, identical lane masses — the ONLY difference is the render intent (`render3d`) and the lane distribution (Y×Z grid instead of a single Y column), both of which the canonical `setupCollisionMatrix3D.js` factory already encodes; nothing in this notebook cell reimplements it.
+
+The simulation runs live in your browser on the compiled FRQTL (WASM) engine.
+</cell>
+
+</frqtl-notebook>

package/dist/notebooks/gallery-double-slit.html

@@ -0,0 +1,53 @@
+<frqtl-notebook version="1" title="Double Slit — the fringe pattern builds itself">
+
+<cell type="markdown">
+# Double Slit
+
+**One particle at a time — the fringe pattern builds itself. Classically this is supposed to be impossible.**
+
+Particles pass through two slits one by one. There is no wave function evaluated anywhere in the engine — each particle is a leaf Frame taking a single 1-pixel step per tick. The banded arrival distribution at the detector wall is **emergent** from single-occupancy collisions and the per-Frame oscillation alone.
+
+*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 — slit screen, light source, detector wall — as editable user code:
+</cell>
+
+<cell type="module" name="./setups/double-slit.js">
+/* setupDoubleSlit — 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/setupDoubleSlit.js that had
+ * already drifted onto a stale `universe.init(...)` positional-argument call the
+ * engine now FAIL-LOUDs on, plus a dead `CollisionActions.RECOLOR` reference the
+ * canonical source removed. 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 { setupDoubleSlit as _setupDoubleSlit } from '@frqtl/setups/double-slit';
+
+export function setupDoubleSlit(frqtl, universe, options) {
+    return _setupDoubleSlit(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-ds-canvas" setup="./setups/double-slit.js#setupDoubleSlit" stage="480x480" seed="42"></cell>
+
+<cell type="markdown">
+## What you are seeing
+
+Particles emit from the light source on the left, most are blocked by the slit screen, and the few that pass through the two openings travel to the detector wall on the right. Over many ticks the arrival positions cluster into fringes — the classical "impossible" result, built from individually launched particles with no wave equation.
+
+**The geometry is a knob.** `wavelength` (default 64) is the single master parameter: it scales slit height, inter-slit gap, wall positions, and detector distance all at once. At `wavelength = 64` on a 480×480 canvas both slits receive balanced illumination (slit1/slit2 ratio ≈ 1.0) and a clear multi-band pattern emerges. The captured sweep across `wavelength` 16 → 128 is in [`docs/physics/double-slit-wavelength.md`](../../docs/physics/double-slit-wavelength.md).
+
+**`detectAtSlits` — the "which-slit" knob.** The default (`1`) applies `RANDOM_XY` at each slit opening: detection disturbs the particle's trajectory. Set it to `0` (transparent slits, no detection) or `2` (color-only, no disturbance) to compare the unobserved and color-only cases.
+
+**Edit the physics:** open the `./setups/double-slit.js` tab and pass an option override to the canonical factory — e.g. change the adapter's `_setupDoubleSlit(universe, options)` call to `_setupDoubleSlit(universe, Object.assign({ wavelength: 32 }, options))` (also try `angleIncrement` or `detectAtSlits`) — then re-Run. The fringe pattern changes because you edited the construction. (The physics body itself lives in the canonical `lib/frqtl/objects/setup/setupDoubleSlit.js` — this cell is a thin, engine-agnostic adapter over it, the SAME construction the `double-slit-rosetta-qft` notebook and the `lib/frqtl/experiments/double-slit/` page drive.) The simulation runs live in your browser on the compiled FRQTL (WASM) engine.
+</cell>
+
+</frqtl-notebook>

package/dist/notebooks/gallery-gun-chamber.html

@@ -0,0 +1,62 @@
+<frqtl-notebook version="1" title="Gun Chamber — L2 effects cascade in a tube">
+
+<cell type="markdown">
+# Gun Chamber
+
+**A breech emitter ignites inside a barrel-scale tube — Dim-0 collisions cascade UP through six declared dimension rungs (light → plasma → air → fire → smoke → haze), with no per-dimension force law anywhere.**
+
+A `Tube` (translucent barrel walls, L1) contains ONE breech `ChamberEmitter` firing rightward down the bore. `universe.addDimension` declares the full sequential Dim 1-6 cascade, so `Universe::handle_promotion` routes each collision's parent to the NEXT declared dimension above it — Dim-0 collisions promote to Dim-1, Dim-1 to Dim-2, and so on, a genuine sequential cascade rather than a skip-ahead. Two hand-placed seeds (Dim-2 "air", Dim-3 "fire") fill tiers the cascade does not reach naturally within the observed window — a reported, measured finding, not a hedge. A muzzle absorber-sink bounds the alive population.
+
+*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 — Tube + ChamberEmitter + the declared dimension cascade + two hand-placed seeds — as a thin adapter over the canonical factory (see below):
+</cell>
+
+<cell type="module" name="./setups/gun-chamber.js">
+/* setupGunChamber — THIN ADAPTER over the canonical setup factory
+ * (WS gym-controls-as-sugar Bite 0 ADDENDUM, CEO 2026-07-03). Same Bite-0
+ * mechanism as every other de-forked notebook: 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 SAME canonical
+ * `lib/frqtl/objects/setup/setupGunChamber.js` also drives the standalone
+ * `lib/frqtl/experiments/gun-chamber/` page.
+ *
+ * NOTE (ground-truthed, not hand-copied): setupGunChamber.js's browser-classic
+ * branch reads window.Tube / window.ChamberEmitter / window.LeafField directly
+ * (the SAME window.* sugar pattern every canonical factory uses) — these three
+ * "Layer class" sugar objects were previously ONLY loaded as per-page
+ * data-page-scripts extras (3 experiment pages: tube-l1, gun, gun-chamber),
+ * NOT part of the shared game layer the notebook realm boots. This bite
+ * promotes them into GAME_LAYER_SCRIPTS (lib/shim/engine/game-layer-manifest.js)
+ * — the canonical move, since they are already reusable across 3 independent
+ * experiments, not gun-chamber-specific — rather than inventing a new
+ * per-notebook "extra scripts" mechanism.
+ */
+import { setupGunChamber as _setupGunChamber } from '@frqtl/setups/gun-chamber';
+
+export function setupGunChamber(frqtl, universe, options) {
+    return _setupGunChamber(universe, options);
+}
+</cell>
+
+<cell type="markdown">
+Declare a canvas that runs it. `render3d="true"` requests the three.js 3D renderer + perspective camera for this canvas (the notebook-realm mirror of an experiment page's `window._egpt3D = true;` opt-in). `cameraPreset="down-barrel"` and `renderOptions="glowIntensity=1.3,godrays=0.8,smoke=4"` carry the standalone page's OWN defaults (WS gym-controls-as-sugar fix-loop #6 Finding B, 2026-07-04 — the tester's fresh-nav side-by-side had flagged these as differing from the GYM/standalone default view). Click **Run** (or **Run All**):
+</cell>
+
+<cell type="canvas" id="c-gunchamber-canvas" setup="./setups/gun-chamber.js#setupGunChamber" stage="480x480" seed="42" render3d="true" cameraPreset="down-barrel" renderOptions="glowIntensity=1.3,godrays=0.8,smoke=4"></cell>
+
+<cell type="markdown">
+## What you are seeing
+
+A bright flash of Dim-0 quanta ignites at the breech and streams down the bore; as collisions cascade upward through the declared dimension ladder, denser compound frames appear further down the tube — light, then plasma, then (from the hand-placed seeds) air and fire tiers — all inside the translucent barrel walls, viewed with true perspective depth, opening on the same down-barrel view (bullet stares at you) as the standalone page and the GYM, with the glow/god-ray/smoke post-process layers on at their page defaults.
+
+**Scope note (this notebook, not the standalone page — fix-loop #6, 2026-07-04):** the camera's default preset and the 3 numeric effect-intensity defaults (glow/god-rays/smoke) now travel identically to the standalone page (via the new `cameraPreset`/`renderOptions` cell attributes — the SAME `runner.cameraControl.setPreset()` / `runner.setRenderOption()` calls the page itself makes). What does NOT travel: the standalone page's PER-DIMENSION `renderTiers` table (flash/plasma/air/fire/smoke/haze/vapor — a structured array-of-objects, not a flat `key=value` pair) and its interactive tier-matrix/preset-button/effect-slider UI, all wired by `fx-experiment.js` reading `window._egptFx` — a substantially larger, separate control system this notebook does not build out. The underlying physics and dimension cascade are byte-identical either way, driven by the identical canonical factory; only the per-dimension VISUAL TREATMENT and the extra UI differ from the standalone page.
+
+The simulation runs live in your browser on the compiled FRQTL (WASM) engine.
+</cell>
+
+</frqtl-notebook>

package/dist/notebooks/gallery-particle-walk-3d.html

@@ -0,0 +1,53 @@
+<frqtl-notebook version="1" title="Particle Walk 3D — the beam fans out in three axes">
+
+<cell type="markdown">
+# Particle Walk 3D
+
+**A radial beam fans out in TWO transverse axes at once — proof the engine's per-axis speed limit is genuinely 3D, not a 2D model with a cosmetic z column bolted on.**
+
+A single `QuantumEmitter` fires quanta rightward (`vx=1`). With `activeAxes:{x,y,z}` all live, the wave-walk coin-flip fires its transverse yo-yo kick on BOTH y AND z independently, every tick — two independent transverse coins, not one. The beam spreads in both directions as it propagates; with only two axes the z column would stay zero throughout. This is the realm-observable proof of Engine Invariant 1 (the ±1px/tick speed limit is independent PER AXIS) in three dimensions.
+
+*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 — one `QuantumEmitter`, full 3D `activeAxes` — as a thin adapter over the canonical factory (see below):
+</cell>
+
+<cell type="module" name="./setups/particle-walk-3d.js">
+/* setupParticleWalk3D — THIN ADAPTER over the canonical setup factory
+ * (WS gym-controls-as-sugar Bite 0 ADDENDUM, CEO 2026-07-03: three notebooks
+ * proving full 3D compliance + the object-architecture contract switching
+ * end-to-end through the notebook path). Same Bite-0 mechanism as every other
+ * de-forked notebook: 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
+ * SAME canonical `lib/frqtl/objects/setup/setupParticleWalk3D.js` also drives the
+ * standalone `lib/frqtl/experiments/particle-walk-3d/` page — one experiment
+ * identity, no divergence possible.
+ */
+import { setupParticleWalk3D as _setupParticleWalk3D } from '@frqtl/setups/particle-walk-3d';
+
+export function setupParticleWalk3D(frqtl, universe, options) {
+    return _setupParticleWalk3D(universe, options);
+}
+</cell>
+
+<cell type="markdown">
+Declare a canvas that runs it. `render3d="true"` requests the three.js 3D renderer + perspective camera for this canvas (the notebook-realm mirror of an experiment page's `window._egpt3D = true;` opt-in — see `lib/components/notebook-pane/realm-frqtl.js`). Click **Run** (or **Run All**):
+</cell>
+
+<cell type="canvas" id="c-walk3d-canvas" setup="./setups/particle-walk-3d.js#setupParticleWalk3D" stage="480x480" seed="42" render3d="true"></cell>
+
+<cell type="markdown">
+## What you are seeing
+
+A cone of quanta streams rightward from the emitter, visibly spreading in BOTH the vertical (y) and depth (z) directions as it travels — the perspective camera makes the z-spread readable as true depth, not a flattened 2D projection. No wave equation, no cone-angle formula: the spread is the accumulated per-tick, per-axis coin-flip of Engine Invariant 6 (the transverse oscillation).
+
+**Compare to the 2D version** (`gallery-wave-interference`, `particle-walk`): those experiments only ever exercise the x/y plane. This notebook is the SAME canonical setup factory the standalone `particle-walk-3d` experiment page drives — the render intent (`render3d`) is the only thing this notebook adds; the physics is identical.
+
+The simulation runs live in your browser on the compiled FRQTL (WASM) engine.
+</cell>
+
+</frqtl-notebook>

package/dist/notebooks/gallery-wave-interference.html

@@ -0,0 +1,52 @@
+<frqtl-notebook version="1" title="Wave Interference — interference without a wave equation">
+
+<cell type="markdown">
+# Wave Interference
+
+**Interference patterns without a wave equation — only quantum particles, with real and local rules, that don't know each other exist. Classically this is supposed to be impossible.**
+
+Using the FRQTL engine, two convenience `PointSource` emitters fire quanta (leaf Frames) radially. Where the two streams overlap, fringes emerge — with no wave function, no superposition term, no interference formula anywhere in the engine.
+
+*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">
+Two radial emitters and their (visual-only) source circles — editable user code:
+</cell>
+
+<cell type="module" name="./setups/wave-interference.js">
+/* setupWaveInterference — 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/setupWaveInterference.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 { setupWaveInterference as _setupWaveInterference } from '@frqtl/setups/wave-interference';
+
+export function setupWaveInterference(frqtl, universe, options) {
+    return _setupWaveInterference(universe, options);
+}
+</cell>
+
+<cell type="markdown">
+Declare a canvas that runs it. The canvas names the setup module (`setup="<module>#<export>"`); the shim synthesizes and runs the builder boilerplate in the realm. `opts` is the validated driving knob, `stage`/`seed` configure the runner. Click **Run** (or **Run All**):
+</cell>
+
+<cell type="canvas" id="c-wave-canvas" setup="./setups/wave-interference.js#setupWaveInterference" opts="quanta=800" stage="480x480" seed="42"></cell>
+
+<cell type="markdown">
+## What just happened
+
+The two black circles are the point sources. Particles stream outward from each; where the streams overlap, regions of constructive and destructive density build into the banded fringe pattern — the classically "impossible" result, produced with no wave equation. Each particle only ever obeyed *move 1 pixel per tick*; the wave behavior is **emergent**.
+
+**The fringe spacing is a knob.** It is set by the universe `wavelengthConstant` (`wavelength = floor((capacity / mass) × WAVELENGTH_CONSTANT)`). Raising it 2 → 32 widens the fringes from a near-uniform dense cloud to sparse, widely-separated radial spokes; lowering it tightens them until they blur together. The captured sweep is in [`docs/physics/wave-interference-wavelength.md`](../../docs/physics/wave-interference-wavelength.md).
+
+Note the two distinct "wavelength" controls: a `PointSource`'s `opts.wavelength` sets each particle's **mass** (`mass = capacity / wavelength`), while the universe `wavelengthConstant` is the global scale on **every** particle's wavelength — the fringe-spacing knob above.
+
+**Edit the physics:** try the `quanta` knob on the canvas (`opts="quanta=200"` or `"quanta=1500"`), or open the `./setups/wave-interference.js` tab and pass an option override to the canonical factory — e.g. change the adapter's `_setupWaveInterference(universe, options)` call to `_setupWaveInterference(universe, Object.assign({ fundamentalWaveLength: 48 }, options))` (also try `sourceSeparation`) — then re-Run. The fringes change because you edited the construction. (The physics body itself lives in the canonical `lib/frqtl/objects/setup/setupWaveInterference.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/getting-started-hello-frqtl.html

@@ -0,0 +1,53 @@
+<frqtl-notebook version="1" title="Hello, FRQTL — your first simulation">
+
+<cell type="markdown">
+# Hello, FRQTL
+
+FRQTL is a discrete physics engine: everything is a **Frame**, and a leaf Frame (a "quantum") obeys one rule — **move 1 pixel per tick**. Complex behavior *emerges*; nothing is hand-coded.
+
+An experiment is two cells:
+
+- a **`module`** cell — editable user code that *assembles* the experiment. It receives `frqtl` (the convenience registry, `caps.frqtl`: `PointSource`, `LargeObject`, `CollisionTypes`, …) and an un-initialized `universe`, and builds objects from them.
+- a **`canvas`** cell — `setup="<module>#<export>"` names that setup; the shim boots the engine, runs your setup, and renders it live. `opts` is a validated driving knob; `stage`/`seed` configure the runner.
+
+That's the whole pattern. (There is no separate builder cell — the canvas declares the setup and the shim synthesizes the wiring.)
+</cell>
+
+<cell type="markdown">
+**1. The setup.** Editable user code — one emitter firing radially from the center:
+</cell>
+
+<cell type="module" name="./setups/hello.js">
+export function setupHello(frqtl, universe, options) {
+    const { PointSource } = frqtl;          // the convenience emitter, via caps.frqtl
+    const r = universe.universe_rect;
+
+    // init(rect, fundamentalDimension, wavelengthConstant, ...): configure + create the field.
+    universe.init(r, 2, 8, false, false, false, true, false);
+
+    // PointSource(universe, x, y, diameter, speed, charge, auto_fire, quantum_limit, delay, angle_increment, opts)
+    //   one source at center; angle_increment 5° → 72 rays; opts.wavelength → particle mass.
+    const source = new PointSource(universe, Math.floor(r.w / 2), Math.floor(r.h / 2),
+        24, 12, null, true, 50000, 0, 5, { wavelength: 32 });
+
+    return { sources: { source }, largeObjects: [] };
+}
+</cell>
+
+<cell type="markdown">
+**2. Render.** Declare a canvas that names the setup. The shim boots the engine and runs it — click **Run** (or **Run All**) and quanta stream outward to fill the field:
+</cell>
+
+<cell type="canvas" id="c-hello-canvas" setup="./setups/hello.js#setupHello" stage="480x480" seed="42"></cell>
+
+<cell type="markdown">
+## That's it
+
+You created a running physics simulation from two small cells. **Edit the setup** — move the source, change `angle_increment`, or the per-emitter `wavelength` — then re-run the canvas; the behavior changes because you changed the construction, not a label.
+
+This runs live in your browser on the compiled FRQTL (WASM) engine.
+
+**Next:** open **Wave Interference** (`gallery-wave-interference`) — two of these emitters produce interference fringes with no wave equation, the classically "impossible" result.
+</cell>
+
+</frqtl-notebook>

package/dist/notebooks/iso-canonical-chain.html

@@ -0,0 +1,203 @@
+<frqtl-notebook version="1" title="U — Canonical Chain Unified (one engine, three lenses)">
+
+<cell type="markdown">
+# U — Canonical Chain Unified
+
+Every case is an instance of the same commuting diagram:
+
+> input ─encode─► EGPTReal[] ─engine─► EGPTReal[] ─decode─► output
+
+The "engine" column names which `EGPTPolynomial` primitive does the work. The same handful of primitives — `forwardTransform`/`inverseTransform`, `multiply`/`add`, `divide` (→ GCD), `evaluateAt` — power number theory, linear algebra, and signal processing alike:
+
+- **U1** `forwardTransform` ≡ pointwise `evaluateAt` at k/N (T1 / F1)
+- **U2** `inverseTransform(forwardTransform(c)) = c` (M2 / F2)
+- **U3** `multiply` + dense `matMul` on polynomial systems (T2 / K1–K6)
+- **U4** iterated `divide` = polynomial GCD (T3 / M6 shared factor)
+- **U5** `evaluateAt` on the atom-root polynomial = factor detection (N1 / N2)
+- **U6** orbit polynomial + `evaluateAt` = order finding ≡ period (N3 / N4)
+- **U7** one example (N=15), all three lenses at once
+
+*(Ported from `theorems/U_CanonicalChainUnified.js`. `EGPTReal/EGPTMath/EGPTPolynomial/PrimeAtomPolynomial/OrderFinder/matMul` come from `caps.math` — no imports. Render + atom/orbit helpers inlined.)*
+</cell>
+
+<cell type="markdown">
+## Setup — inline helpers
+
+`renderVec`/`matricesEqual` and the atom-root / orbit polynomial builders are inlined (they call only `caps.math` primitives). Exposed as a binding for the engine cells.
+</cell>
+
+<cell type="js" lane="math" id="u-setup" out="uhelp">
+const { math } = caps;
+const { EGPTReal, EGPTPolynomial, PrimeAtomPolynomial } = math;
+const ZERO = EGPTReal.fromBigInt(0n);
+const ONE  = EGPTReal.fromBigInt(1n);
+const intN = (n) => EGPTReal.fromBigInt(BigInt(n));
+const frac = (n, d) => EGPTReal.fromRational(BigInt(n), BigInt(d));
+const isZero = (e) => e.equals(ZERO);
+function renderValue(v) {
+  if (v == null) return String(v);
+  if (typeof v._getPPFRationalParts === 'function') {
+    const { numerator, denominator } = v._getPPFRationalParts();
+    if (denominator === 1n || denominator === -1n) return String(denominator < 0n ? -numerator : numerator);
+    return `${numerator}/${denominator}`;
+  }
+  return String(v);
+}
+function showVec(v) { return '[ ' + v.map(renderValue).join(', ') + ' ]'; }
+function matricesEqual(X, Y) {
+  if (X.length !== Y.length) return false;
+  for (let i = 0; i < X.length; i++) {
+    if (X[i].length !== Y[i].length) return false;
+    for (let j = 0; j < X[i].length; j++) if (!X[i][j].equals(Y[i][j])) return false;
+  }
+  return true;
+}
+function polyGCDMonic(a, b) {
+  let A = a.slice(), B = b.slice();
+  while (!B.every(isZero)) { const { remainder } = EGPTPolynomial.divide(A, B); A = B; B = EGPTPolynomial.trimZeros(remainder); }
+  A = EGPTPolynomial.trimZeros(A);
+  const lead = A[A.length - 1];
+  if (isZero(lead)) return A;
+  return EGPTPolynomial.divide(A, [lead]).quotient;
+}
+function buildAtomRootPolynomial(N) {
+  const factors = PrimeAtomPolynomial.factorize(N);
+  let poly = [ONE];
+  for (const { prime, exponent } of factors) { const linear = [intN(-prime), ONE]; for (let k = 0n; k < exponent; k++) poly = EGPTPolynomial.multiply(poly, linear); }
+  return poly;
+}
+function buildOrbitPolynomial(a, N) {
+  const aBi = BigInt(a), NBi = BigInt(N);
+  let poly = [ONE], current = 1n; const seen = new Set([1n]);
+  while (true) { current = (current * aBi) % NBi; if (current === 1n) break; if (seen.has(current)) break; seen.add(current); poly = EGPTPolynomial.multiply(poly, [intN(-Number(current)), ONE]); }
+  return EGPTPolynomial.multiply(poly, [intN(-1), ONE]);
+}
+return { uhelp: { renderValue, showVec, matricesEqual, polyGCDMonic, buildAtomRootPolynomial, buildOrbitPolynomial, intN, frac } };
+</cell>
+
+<cell type="markdown">
+## U1 / U2 — forwardTransform ≡ evaluateAt, and the inverse round-trip
+
+`forwardTransform(c, N)` is per-point `evaluateAt(c, k/N)`; `inverseTransform` recovers `c` exactly.
+</cell>
+
+<cell type="js" lane="math" id="u12" in="uhelp">
+const { math, display } = caps;
+const { EGPTPolynomial, EGPTReal } = math;
+const { showVec, intN, frac } = inputs.uhelp;
+const ONE = EGPTReal.fromBigInt(1n);
+function check(label, cond) { display((cond ? '  ✓ ' : '  ✗ ') + label); if (!cond) throw new Error('U1/U2 FAILED: ' + label); }
+function veq(u, v) { if (u.length !== v.length) return false; for (let i = 0; i < u.length; i++) if (!u[i].equals(v[i])) return false; return true; }
+
+// U1
+const coeffs = [frac(1, 3), frac(-7, 6), ONE];
+const N = 8;
+const samples = EGPTPolynomial.forwardTransform(coeffs, N);
+display('U1  forwardTransform(c,8) = ' + showVec(samples));
+const manual = []; for (let k = 0; k < N; k++) manual.push(EGPTPolynomial.evaluateAt(coeffs, EGPTReal.fromRational(BigInt(k), BigInt(N))));
+check('forwardTransform ≡ per-point evaluateAt at k/N (T1 / F1)', veq(manual, samples));
+
+// U2
+const c2 = [frac(1, 3), frac(-7, 6), ONE];
+const s2 = EGPTPolynomial.forwardTransform(c2, c2.length);
+const rec = EGPTPolynomial.inverseTransform(s2, c2.length);
+display('U2  inverseTransform(forward(c)) = ' + showVec(rec));
+check('inverseTransform(forwardTransform(c)) = c (bit-exact round trip)', veq(rec, c2));
+</cell>
+
+<cell type="markdown">
+## U3 — multiply + dense matMul on polynomial systems
+
+Convolution (T2) is one `multiply` call; a dense 2×2 `matMul` (K1) treats rows as polynomials and accumulates via `multiply` + `add`, matching the explicit dot-product reference.
+</cell>
+
+<cell type="js" lane="math" id="u3" in="uhelp">
+const { math, display } = caps;
+const { EGPTPolynomial, EGPTMath, matMul } = math;
+const { showVec, matricesEqual, intN } = inputs.uhelp;
+function check(label, cond) { display((cond ? '  ✓ ' : '  ✗ ') + label); if (!cond) throw new Error('U3 FAILED: ' + label); }
+
+const a = [intN(1), intN(2)], b = [intN(3), intN(4)];
+const ab = EGPTPolynomial.multiply(a, b);
+display('T2  multiply([1,2],[3,4]) = ' + showVec(ab));
+check('T2 convolution ≡ one multiply call', ab.length === 3 && ab[0].equals(intN(3)) && ab[1].equals(intN(10)) && ab[2].equals(intN(8)));
+
+const A = [[intN(1), intN(2)], [intN(3), intN(4)]];
+const B = [[intN(5), intN(6)], [intN(7), intN(8)]];
+const C = matMul(A, B);
+const Cref = [
+  [EGPTMath.add(EGPTMath.multiply(A[0][0], B[0][0]), EGPTMath.multiply(A[0][1], B[1][0])),
+   EGPTMath.add(EGPTMath.multiply(A[0][0], B[0][1]), EGPTMath.multiply(A[0][1], B[1][1]))],
+  [EGPTMath.add(EGPTMath.multiply(A[1][0], B[0][0]), EGPTMath.multiply(A[1][1], B[1][0])),
+   EGPTMath.add(EGPTMath.multiply(A[1][0], B[0][1]), EGPTMath.multiply(A[1][1], B[1][1]))]
+];
+display('K1  dense matMul rows-are-polynomials  C = [[' + showVec(C[0]) + ',' + showVec(C[1]) + ']]');
+check('K1 dense matMul via polynomial-system form matches reference', matricesEqual(C, Cref));
+</cell>
+
+<cell type="markdown">
+## U4 — iterated divide = polynomial GCD (shared factor)
+
+Two polynomials f1, f2 both vanishing at 1/2; the Euclidean walk (iterated `divide`) recovers the monic gcd `x − 1/2` — the T3 resultant / M6 shared-factor view.
+</cell>
+
+<cell type="js" lane="math" id="u4" in="uhelp">
+const { math, display } = caps;
+const { EGPTPolynomial, EGPTReal } = math;
+const { showVec, polyGCDMonic, frac } = inputs.uhelp;
+const ZERO = EGPTReal.fromBigInt(0n);
+const ONE = EGPTReal.fromBigInt(1n);
+function check(label, cond) { display((cond ? '  ✓ ' : '  ✗ ') + label); if (!cond) throw new Error('U4 FAILED: ' + label); }
+const f1 = [frac(1, 3), frac(-7, 6), ONE];
+const f2 = [frac(1, 6), frac(-5, 6), ONE];
+const g = polyGCDMonic(f1, f2);
+display('U4  monic gcd(f1,f2) = ' + showVec(g) + '   (expected x − 1/2)');
+check('gcd agrees with T3 resultant — exactly x − 1/2', g.length === 2 && g[0].equals(frac(-1, 2)) && g[1].equals(ONE));
+check('gcd vanishes at the shared root 1/2', EGPTPolynomial.evaluateAt(g, frac(1, 2)).equals(ZERO));
+</cell>
+
+<cell type="markdown">
+## U5 / U6 / U7 — factor detection, order finding, all-lenses example
+
+U5: roots of the atom-root polynomial of N=60 are exactly its prime factors. U6: the orbit polynomial of (3 mod 8) has degree = order. U7: N=15 — factoring, order finding, and A·I=A all run on the one engine.
+</cell>
+
+<cell type="js" lane="math" id="u567" in="uhelp">
+const { math, display } = caps;
+const { EGPTPolynomial, EGPTReal, PrimeAtomPolynomial, OrderFinder, matMul } = math;
+const { showVec, matricesEqual, buildAtomRootPolynomial, buildOrbitPolynomial, intN } = inputs.uhelp;
+const ZERO = EGPTReal.fromBigInt(0n);
+function check(label, cond) { display((cond ? '  ✓ ' : '  ✗ ') + label); if (!cond) throw new Error('U5/6/7 FAILED: ' + label); }
+
+// U5 — N=60
+const N5 = 60n;
+const P5 = buildAtomRootPolynomial(N5);
+display('U5  P_60 = ' + showVec(P5));
+for (const { prime } of PrimeAtomPolynomial.factorize(N5)) check(`P_60(${prime}) = 0 (N1/N2 coincide)`, EGPTPolynomial.evaluateAt(P5, intN(prime)).equals(ZERO));
+check('P_60(7) ≠ 0 (7 is not a factor of 60)', !EGPTPolynomial.evaluateAt(P5, intN(7)).equals(ZERO));
+
+// U6 — (3 mod 8)
+const Q = buildOrbitPolynomial(3n, 8n);
+const r = Number(OrderFinder.findOrder(3n, 8n));
+display(`U6  orbit polynomial Q = ${showVec(Q)}   order(3 mod 8) = ${r}`);
+check(`deg(Q) = order(3 mod 8) = ${r} (N3 ≡ N4)`, EGPTPolynomial.degree(Q) === r);
+
+// U7 — N=15, all lenses
+const atomP = buildAtomRootPolynomial(15n);
+const orbitP = buildOrbitPolynomial(7n, 15n);
+const order = Number(OrderFinder.findOrder(7n, 15n));
+const A = [[intN(1), intN(2)], [intN(3), intN(4)]];
+const I = [[intN(1), intN(0)], [intN(0), intN(1)]];
+const AI = matMul(A, I);
+check('U7 N1/N2: prime 3 is a root of P_15', EGPTPolynomial.evaluateAt(atomP, intN(3)).equals(ZERO));
+check('U7 N1/N2: prime 5 is a root of P_15', EGPTPolynomial.evaluateAt(atomP, intN(5)).equals(ZERO));
+check('U7 N3/N4: orbit polynomial degree equals order(7 mod 15)', EGPTPolynomial.degree(orbitP) === order);
+check('U7 T/K: A · I = A (one EGPTPolynomial.multiply)', matricesEqual(AI, A));
+</cell>
+
+<cell type="js" lane="math" id="u-qed">
+const { display } = caps;
+display('QED — one engine (EGPTPolynomial primitives), three lenses (number theory, linear algebra, signal processing).');
+</cell>
+
+</frqtl-notebook>