@descix/frqtl-node 0.0.0-stage → 0.6.0-p0.1

package/CLAUDE.md

@@ -0,0 +1,87 @@
+# @descix/frqtl-node
+
+A discrete cellular-automata physics engine (compiled Rust → WASM) for node: the same modules as
+`@descix/frqtl-web` (one source, built twice), plus the node engine door `bootNode` and the hosted eyes.
+Pre-release `0.6.0-p0.1` (npm dist-tag `next`). Node ≥ 22.12.
+
+## Install
+  npm install @descix/frqtl-node@next
+
+## Rung 0 — the seven primitives
+```js
+import { bootNode } from '@descix/frqtl-node';            // or require() from CommonJS
+const { EGPTUniverse } = await bootNode();
+const u = EGPTUniverse.create({ rect: { left: 0, top: 0, w: 200, h: 200 }, seed: 42 });
+u.init(0, { wavelengthScale: 1 });                         // ALWAYS first
+u.experimentTickFunctions.push((uni) => uni.injectFrame(uni.makeLeafFrame(20, 100, 0, null, 1, 0)));
+const tick = u.doTick();                                   // pure data: frameData + objects
+```
+
+## Exports
+| subpath | what |
+|---|---|
+| `.` | the parts, `bootNode`, `engine`, `engineState`, `FrqtlCapture`, `RenderStages`, `FieldBuilder`, `CaptureEnvelope`, `validateRendererProvider` |
+| `./eyes` | `openHostedEyes`, `FrqtlVision` — a `composite` through the REAL renderer (pulls the pinned `playwright`) |
+| `./register` | installs the resolve hook for a sketch's `@descix/frqtl-web/...` imports: `node --import @descix/frqtl-node/register` |
+| `./parts`, `./parts/*`, `./project`, `./registry`, `./kinds`, the six non-part sketch modules, `./dist-manifest.json` | as in `@descix/frqtl-web` |
+
+## Scene files in node
+A scene imports `@descix/frqtl-web/parts`. Link it with `linkProject` (`./project`), which resolves those
+specifiers to this package's own copy:
+```js
+import { linkProject } from '@descix/frqtl-node/project';
+const dataMint = (text) => ({ url: 'data:text/javascript,' + encodeURIComponent(text) });
+const { buildExperiment } = await linkProject({ files: { 'sketch.js': text }, entry: 'sketch.js', mint: dataMint });
+```
+A scene file on disk is imported directly under the package's resolve hook, which maps its
+`@descix/frqtl-web/...` imports to this package's own files: `node --import @descix/frqtl-node/register run.mjs`
+(or `import '@descix/frqtl-node/register'` first).
+
+## Eyes
+Headless: `FrqtlCapture` / `FrqtlVision` — the `tick` and `field` stages need no canvas.
+Through the real renderer:
+```js
+import { openHostedEyes } from '@descix/frqtl-node/eyes';
+const eyes = await openHostedEyes({
+    sceneRecord: { seed: 42, sourceRef: 'my-scene' },
+    sceneSource: { kind: 'project', files: { 'sketch.js': text }, entry: 'sketch.js' },   // REGENERATE-grade
+    renderState,                                                       // optional: the declared look
+    pageUrl: '<origin>/experiments/empty/index.html'                   // a served @descix/frqtl-web dist
+});
+try {
+    await eyes.driveToTick(300);
+    const still = await eyes.vision.getStill('composite');
+    eyes.saveStill(still, 'out.png');
+} finally { await eyes.dispose(); }
+```
+  - REGENERATE-grade or nothing: hosting re-runs the scene, so the project is required; an ad-hoc or
+    raster-only scene is refused by name. The page and this process compute the same project identity.
+  - The picture is SOURCE + declared renderState. A rung's look lives on its registry row: pass
+    `effectiveRenderState(rung, mode)` (`./registry`).
+  - The browser is a real, pinned dependency reached only by `./eyes`; bring your own via `browserType`.
+  - Every still's `build.gl` records the raster path the browser actually used.
+
+No CLI ships with this package. Acceptance is visual.
+
+## The physics model (enough to code against)
+Three primitives: time = 1 tick, space = 1 pixel, mass = pixel occupancy.
+Everything is a Frame (recursive); there is no separate "particle" class.
+
+  - A frame moves at most 1 pixel/tick per axis relative to its parent; excess
+    intended motion accumulates as momentum (this is the speed limit).
+  - Single occupancy: two quanta can't share a pixel; a failed placement is a
+    collision (bounce/merge), not a force.
+  - Interference fringes are the statistics of many discrete walks through the
+    slits — the pattern builds up from individual quanta, not a wave equation.
+  - Fullness (mass/capacity) sets two decoupled things: how often a frame steps
+    (its effective speed) and its oscillation wavelength
+    (wavelength = floor(capacity/mass × constant), minimum 4).
+  - `doTick()` runs a fixed pipeline (inject → structure → physics → collect) and
+    returns pure data; rendering is downstream.
+
+## What this is NOT
+  - Not a general PDE / force-integration physics library.
+  - Not a math library — that is the sibling package @descix/egpt-math-sdk.
+  - The published build is WASM-only on the engine side (compiled surface).
+
+## No account, credits, or tokens are needed for anything above.

package/README.md

@@ -1,3 +1,85 @@
-# Temporary Holding Version
+# @descix/frqtl-node
+
+FRQTL for node: a discrete cellular-automata physics engine (compiled Rust → WASM). Physics comes out of
+local per-pixel rules — a frame moves one pixel per tick, single occupancy, momentum — rather than force
+equations. Interference, blackbody spectra and atom-like binding emerge from the automaton.
+
+Pre-release `0.6.0-p0.1` (npm dist-tag `next`). Node ≥ 22.12.
+
+## Install
+
+    npm install @descix/frqtl-node@next
+
+## Rung 0 — the seven primitives
+
+```js
+import { bootNode } from '@descix/frqtl-node';
+
+const { EGPTUniverse } = await bootNode();                       // the WASM engine, once per process
+const u = EGPTUniverse.create({ rect: { left: 0, top: 0, w: 200, h: 200 }, seed: 42 });
+u.init(0, { wavelengthScale: 1 });                               // ALWAYS first
+u.experimentTickFunctions.push((uni) => uni.injectFrame(uni.makeLeafFrame(20, 100, 0, null, 1, 0)));
+const tick = u.doTick();                                         // TickData: frameData + objects
+```
+
+`require('@descix/frqtl-node')` works from CommonJS too (nothing in the graph awaits at top level).
+
+## Exports
+
+| subpath | what |
+|---|---|
+| `.` | the parts (`Wall`, `SphereEmitter`, `Tunnel`, `FrqtlVision`, …), `bootNode`, the engine accessors (`engine`, `engineState`), the capture contracts (`FrqtlCapture`, `RenderStages`, `FieldBuilder`, `CaptureEnvelope`) and `validateRendererProvider` |
+| `./eyes` | `openHostedEyes` — a `composite` still through the REAL renderer, in a managed headless browser (pulls the pinned `playwright`) |
+| `./parts`, `./parts/*` | the parts barrel; one part = one file |
+| `./project` | `FRQTL_WEB_SPECIFIERS`, `libPathOf`, `importMapFor`, `linkProject`, `projectIdentity` |
+| `./registry` | the walk-through rungs, the showcase roster, the experiment registry, `loadSceneSource` |
+| `./kinds` | `registerKind`, `kindNamed`, `kindOf`, `registeredKinds` |
+| `./register` | installs the resolve hook for a sketch's `@descix/frqtl-web/...` imports (`node --import @descix/frqtl-node/register`) |
+| `./shim/controls/registry.js`, `./shim/render/sun-look.js`, `./compat/renderer/display-slot.js`, `./compat/renderer/orbit-bag.js`, `./objects/setup/_collisionMatrixLanes.js`, `./compat/engine.js` | the six non-part modules a scene may import (the rows of `FRQTL_WEB_SPECIFIERS`) |
+| `./dist-manifest.json` | sha256 of every dist file |
+
+These modules are the same files `@descix/frqtl-web` ships (one source, built twice).
+
+## A scene file in node
+
+A scene is an ES module whose default export is `buildExperiment(exp)`, and it imports its parts as
+`@descix/frqtl-web/parts`. In this package a project is linked by `linkProject` (`./project`), which
+resolves those specifiers to this package's own copy:
+
+```js
+import { linkProject } from '@descix/frqtl-node/project';
+const dataMint = (text) => ({ url: 'data:text/javascript,' + encodeURIComponent(text) });
+const { buildExperiment } = await linkProject({ files: { 'sketch.js': text }, entry: 'sketch.js', mint: dataMint });
+```
+
+A scene file on disk imports `@descix/frqtl-web/...`; this package resolves those specifiers to its own files
+through one resolve hook:
+
+```sh
+node --import @descix/frqtl-node/register my-scene-runner.mjs
+```
+
+(or `import '@descix/frqtl-node/register'` before the first import of a scene). Without it, node does not
+know the `@descix/frqtl-web` name in a node-only install.
+
+## Hosted eyes
+
+```js
+import { openHostedEyes } from '@descix/frqtl-node/eyes';
+const eyes = await openHostedEyes({
+    sceneRecord: { seed: 42, sourceRef: 'my-scene' },
+    sceneSource: { kind: 'project', files: { 'sketch.js': text }, entry: 'sketch.js' },
+    pageUrl: '<origin>/experiments/empty/index.html'    // the empty page of a served @descix/frqtl-web dist
+});
+await eyes.driveToTick(300);
+const still = await eyes.vision.getStill('composite');
+await eyes.dispose();
+```
+
+The still's SceneRecord carries the project's identity (`projectIdentity`) as `sourceSha256`.
+
+## Acceptance is visual
+
+There is no CLI. FRQTL scenes are fractal and non-linear: run a scene and look at it. A numeric score
+is a design aid in your own harness, never the acceptance criterion.
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.

package/dist/dist-manifest.json

@@ -0,0 +1,218 @@
+{
+  "name": "@descix/frqtl-node",
+  "version": "0.6.0-p0.1",
+  "files": {
+    "eyes/index.js": "c74d5595ea2f778f2f63ef3ce2b6568433cef80ec21b6d66901c1d1a942dbe9a",
+    "fat/pkg-node/egpt_wasm.js": "2db4de19be9744458e9dd9cb89333d2a11cc3e0f6dab52fa1585510bba7b8e69",
+    "fat/pkg-node/egpt_wasm_bg.wasm": "24575b7ccb98e27ed031d406d839d71f0440ca327f471f819a694499732658c5",
+    "fat/pkg-node/package.json": "5303da90c63f92c0599d3c99a0ccd0da16fea0011c3111189394c2a90b4070bd",
+    "frqtl/assets/vendor/chroma.mjs": "f25f4a17d8ceedf58e278df8df83c2804b4f0cf3ff659d963da144e368f8e525",
+    "frqtl/compat/boot-node.js": "7cfd4645f965fa3e3d3072688b268a8aa5b8b4d727c7d842d3bad841dacd1194",
+    "frqtl/compat/engine.js": "a849144e80f93694290f4567fa78d09c88b277162be9f1c15ab820328690c3a4",
+    "frqtl/compat/package-root.js": "9ff4b6bc958c524b5084f849c811f1491a788afc99cab81cd281add02316ff83",
+    "frqtl/compat/providers/wasm-engine.js": "379d43b7fdfc97ccebe7c95078a551135d94e1fc66cab574a117aca797ef0927",
+    "frqtl/compat/providers/wasm-load-browser.js": "24d8480d83e18894f42c1e43cfe88170803624544ed544d07c7eb940ff3d8903",
+    "frqtl/compat/providers/wasm-load-node.js": "0ec1d50e204bf073caac5218b3007eff65c480a94c8d87ad567a6d80b6b6c435",
+    "frqtl/compat/renderer/FieldBuilder.js": "af30df8b04ee05a006882eb8cb56ff84e76142348339d039296304877770c519",
+    "frqtl/compat/renderer/Filters.js": "5201a33473dcfd96c8694b5ff1e297bea27195f6c7940a8e51669d07856026db",
+    "frqtl/compat/renderer/RenderFamily.js": "7549f5d73e75cccfdfa678b11efc38f6b93261630b351de63e3945a8a1cda1fb",
+    "frqtl/compat/renderer/RenderMesh.js": "1755ef5ee291ea98dffe0701b9fe9412bc4dd46672b3bc0c42c4d3a1402ad826",
+    "frqtl/compat/renderer/RenderShape.js": "584e64c72f79c34077d4f395d40d5b3d5f6ea489b10b1be4d3718f05a8b63bc1",
+    "frqtl/compat/renderer/camera2d-geometry.js": "d34aa7737962fcbab774bff18da724aa351a47971632ad7fe052e3db0b8cdd69",
+    "frqtl/compat/renderer/captureStill-common.js": "7ee5353f0c913fea90229a1e8a24e93c60182a463e50524fb899966621837593",
+    "frqtl/compat/renderer/display-slot.js": "389765484b6ab3bda4c1a7519b6afc6bfae3cd054bcd185b057851afddcee5d5",
+    "frqtl/compat/renderer/lo-drawn-center.js": "4cb2e1f32dc03b188701163a9e3f711c344f269c7886bceb27d49fe5a4194b81",
+    "frqtl/compat/renderer/orbit-bag.js": "b6671d3b35fcf5f79e228934a8032e729309e62b66920602f34c834f3f911681",
+    "frqtl/compat/renderer/providers/godrays-layer.js": "be76fb8e69c74dd9bd0fb9aa6189a816d0ed29b9f4e04b60277be375b93d606c",
+    "frqtl/compat/renderer/providers/index.js": "fa669158a082a0081125c81694ca79962639caf86a575ee198a815f3e13a19e7",
+    "frqtl/compat/renderer/providers/p5-provider.js": "252e991b52b5feed64b1a049ccb959cdf92f8e0cbe79984255a05cd7172861d0",
+    "frqtl/compat/renderer/providers/three-camera-contract.js": "2ced4a2339604965b53e4f148415326b16bb18f13a19f989bda6070955b5b49f",
+    "frqtl/compat/renderer/providers/three-camera-geometry.js": "6d682e2c70c336835cc022a2aa9d637174d18f11867bdb7355f8d563d05ae239",
+    "frqtl/compat/renderer/providers/three-provider.js": "3cf4314de6e96e3aceebff6ea36af2f5c41800264ac36986528392a46769ea56",
+    "frqtl/compat/renderer/renderCapabilities-common.js": "af6d8d4fe92c7c691bd187977b05bc0726e78f8f0e57282b3ce3d2035b7209bf",
+    "frqtl/compat/renderer/renderer-provider-contract.js": "6643b9e9cdaa7fb9623ee30ebeaaa29c477d2da14d688d2d14254f214599d61e",
+    "frqtl/compat/renderer/unprojectStill.js": "43c4286c124eaa238d963fe3ae5551a1c87727809d5245a129f368a117863c45",
+    "frqtl/compat/vendor.js": "b53bdb9c23057e20b652d3960211781ddc7454e14395d858d6ba9f33aa120cab",
+    "frqtl/node-entry.js": "a401039b4fcf53ac620edbd80985aa4448122f2e3caaeaf4d5595f5e9d512b60",
+    "frqtl/objects/FrqtlApp.js": "4fd016f4921ec933d148542c09f744d450bb1fdb0b75c20db62a0b0a9d958b70",
+    "frqtl/objects/ObjectFactory.js": "6bcbfe05ec5f32473b928988de27be26d4a80fb8bcc2327442966c75f7dbe202",
+    "frqtl/objects/RecipeContext.js": "e1f77a2a77bcb05859ab206bfea98746ef98cdd6e1a9a74979aa39348d058f42",
+    "frqtl/objects/collectors/DataCollector.js": "8736d6cb77eec36ce2adcf2bc3b0d2436eeb70a73b77182ff053efdc6ca071df",
+    "frqtl/objects/constants/WallBehaviors.js": "2848c4bc088fb37c9c49c45b04017993d5dbc38fab9a3b935fc7973e2d076750",
+    "frqtl/objects/geometry/SlabFace.js": "4f1b848286e17c8fd24d8cb6afc168f11e42a4370c9d9d6c6bd2085b13f4b60f",
+    "frqtl/objects/instruments/capture-host.js": "0514c7f1e6dc6cd062367d4491534ab279d3f9d1ae73df03f330a99bffd3f168",
+    "frqtl/objects/instruments/capture.js": "3229487febc1554dad90d9b80a1036ca056d2565815fa344d4e17fb61fba3027",
+    "frqtl/objects/instruments/hosted-eyes.js": "8fa00f65b67a08541e692f61b8433e99ed10324c92e3b41f2d36d6eee7b3f8a9",
+    "frqtl/objects/kinds-entry.js": "a7818357864dc900bd93350635016f938c3dca8dcb665a62df802ba5cd0b3c93",
+    "frqtl/objects/kinds.js": "107b166c96c93fd517f173fdbe7006d6f0b2694d5f799f7ec9d4f695313f1832",
+    "frqtl/objects/objects/Box.js": "0c08fa4753b78ef56d07aae3393a6268647b550ead58e409cff13eabc8b34b5d",
+    "frqtl/objects/objects/Bullet.js": "9192dcdf80fc0e0bd2287b75aef5375cc81c7ef4c8411d30cab54b9e88619516",
+    "frqtl/objects/objects/CircuitGate.js": "15a5e6d6a5d5354513c431fd0e567e30aac32ff42f2ab993010f30388a230be3",
+    "frqtl/objects/objects/CircuitProbe.js": "f13408324f710f55416e074d914bbd44960268dd631fa6617648d92991812b38",
+    "frqtl/objects/objects/DirectedTunnel.js": "da83bc06e14c73b6e9289606200e0ca38ae399149aa6db2d515ce393a542d184",
+    "frqtl/objects/objects/EgptFractal.js": "3ae5ecbdcc08ba60ab5fe06d8f5567cb16b375b1472fdad704b6ea17c5509f1e",
+    "frqtl/objects/objects/LightSource.js": "15dc7977581ad2abff450e1fc34a103938009a61403554f126dae2273f78bdda",
+    "frqtl/objects/objects/QuantumEmitter.js": "716cf29aa05c74357c6ebf02243d3ce637235fb0075e292ae0be6c2e78909c69",
+    "frqtl/objects/objects/Tube.js": "1d72e8b341b52e7f8610f28ca86a6fe23b0ecefc060fea4dd5622769070cac58",
+    "frqtl/objects/objects/absorbRadiation.js": "58c04dfc3eb5f62ab9d711deac82d105f5ec59ea4ef547d9cf228a1a80494fd3",
+    "frqtl/objects/objects/actionCompiler.js": "8bc7e876c167ea608b1ee666fceea5b0c67c55a387e6ca91704fe38612a503c8",
+    "frqtl/objects/objects/controlAction.js": "f7b2d6f0ea8ec4f46bfaaa36005bf3d4cd281ab90d6ea824f787a6b962d1cb2f",
+    "frqtl/objects/objects/controlBind.js": "8c0ba2f77fe338f94dcee17eb7fb220857f27cf47d5d0570e1c1f892856af210",
+    "frqtl/objects/objects/directedRedirectProgram.js": "275b1bcebf6142f8d33996b3f68153fb9587be6fbd8dc80df45e0a115dfb03fb",
+    "frqtl/objects/objects/emitterProgram.js": "97c75abaca321c08d45120f8fa9a514cc6f24d52eb3c7b8e0b77d16fd0ab48e9",
+    "frqtl/objects/objects/frqtl-control-slider.js": "5b32e9254803c2462073dc100337aa63b9910391187b9b845de6a11be455106d",
+    "frqtl/objects/objects/frqtl-control-sync.js": "4c4e57edd6836c8eb2ffc2284f8cfeabae7ceb71b2afd47cc5ad51eec251f5ab",
+    "frqtl/objects/objects/frqtl-control-widgets.js": "8893feda9d4ecd664dca6993b276bab1e00ce69a6bf72cf7b745c4dc0a97701b",
+    "frqtl/objects/objects/frqtl-control-write-queue.js": "5356d2248a990e4b535421bb6dc7ef3c6fdf79e60a3d8466ad582b1af2621e86",
+    "frqtl/objects/objects/makeControlsForObject.js": "4aad4f7adba532fe8c54ae0e257008acbd87ca990f9806bef4f9e2872f16712b",
+    "frqtl/objects/objects/makeControlsForRenderSurface.js": "5664a968f42124ad2cffaaf3e07f2e34ac0b1c18f4f6f689af8df4b3e54801bb",
+    "frqtl/objects/objects/slitLinerScatter.js": "dbb16f6ddb350887beca35c421867807d799b6b18662e307fe871e3064b7ae27",
+    "frqtl/objects/objects/sustainedSource.js": "1bee702bb71b6f50a2ccb7fba0dd384b56a93de405fd9345a201a67c01d0cac6",
+    "frqtl/objects/objects/tagger.js": "48035d1481da3f9a3878108ba9a7e621d507d71831320a512e7cdb82b5a96bcc",
+    "frqtl/objects/schema/engine-scopes.js": "35c17ecd9be20d2a6aeb5e87ae07744f803394e256d24d2e55c526b91bfe3d04",
+    "frqtl/objects/schema/index.js": "713688782e65adc5138d5792a08c68cbb01494b58834266096759b384b562565",
+    "frqtl/objects/schema/scopes.js": "345db8a3f73a4cb66a7ddc710d34f0c07699b8196b49d1f554e30f7df064cd8b",
+    "frqtl/objects/schema/validate-descriptor.js": "32572a7c7f5262a46d13bcd05424555151287c4438e3e081ab2f3884fd5a2f10",
+    "frqtl/objects/schema/valueNormalizer.js": "00dc4eb188f23964336d45de021846b63a3603c423b5444f132bf470c73c4354",
+    "frqtl/objects/setup/_collisionMatrixLanes.js": "7435b98f2282f2ee9ba05dbe723aec1c63576e9f4e7303fda7fb9f8850ab7d99",
+    "frqtl/objects/setup/_setupOptions.js": "bc9bff3c647418db452976b54e9f91474c59abf5acbde1d62747a11a9501cca0",
+    "frqtl/objects/setup/_worldInit.js": "fb9b3716f93415100581e1bd12c8170d28c1d1cbda2e5236530598b197d7fdb3",
+    "frqtl/objects/setup/setupBlackbodySubstrate.js": "3194209d90a6a05fd894383f89f91a8f4299039a7b9d384bac892d5e893b58d4",
+    "frqtl/objects/setup/setupCircuitBasic.js": "8204f7d42f8dd888e6a4e1175b16a6e67b69fb2d943af6c2b40c900b905dd453",
+    "frqtl/objects/setup/setupCollisionMatrix.js": "e528ab86c94d4eb5d666ac23b8471e6777dbc917605814eecee6c5910398945a",
+    "frqtl/objects/setup/setupConeEmitter3D.js": "a74a73e7573a384ed684ce02377507f29c7137b9cfa48b435b5f5c6fc7c158b3",
+    "frqtl/objects/setup/setupDoubleSlit.js": "97b72c5600ddb0f823e42759ea3109dae7d2a298a80485a89c3ef33c78dcbe62",
+    "frqtl/objects/setup/setupDoubleSlit_Laser.js": "373f0b8a5087072063457b5cf9f67f43afc26a71a89d667520fde5a81cc075d7",
+    "frqtl/objects/setup/setupEmpty.js": "d0fc6e8661514965fa68720a714a2fe44bfbf414f92549e4c86c8bf60a4cc1d1",
+    "frqtl/objects/setup/setupFxSmoke.js": "cafbcd825f5c6038f2a8051892e510b7d490dd75dc149df8a0e006f8d05d8ea9",
+    "frqtl/objects/setup/setupG1Race.js": "431df40700a8633fae54eea98f160e7852deb3765c3b374c35c0e1af24611d31",
+    "frqtl/objects/setup/setupG2Sweep.js": "2d44e194a6def2f5cb3eb32db4d69b7f709894f345b77d2305047f37a5d14773",
+    "frqtl/objects/setup/setupG3Collide.js": "f3e9c5f0a9efc2c50d92d48b975544d40a48d03b189969217fe994df7385ae48",
+    "frqtl/objects/setup/setupLightSourceLab.js": "72ece6da3d4a4f2f01ca1b7376ab87e0b9074c2c9c5fa48b2a2fdf4aba154b01",
+    "frqtl/objects/setup/setupOscillator.js": "0b706b20d98088f47c351b0b84280cf5e4468504bb07517360f3999a0cf0fbfb",
+    "frqtl/objects/setup/setupParticleWalk.js": "38e1a939c180d1921c9b338083017505a3326936531cfae62c603b3b86c3b033",
+    "frqtl/objects/setup/setupParticleWalk3D.js": "df0a24aaf3d9acb474faa9f7b7a4c83446e63935d2e7e0f28185fd197097a15e",
+    "frqtl/objects/setup/setupSphereEmitter3D.js": "f7b8d5b2b408f569328ed24f8607758b1483d8b55d5437ad9df1a6bce462ab31",
+    "frqtl/objects/setup/setupTraceCircuit.js": "cc551cdfa1879289574dd93b97669387371c488b27ec6b53df2ff75ba83525f0",
+    "frqtl/objects/setup/setupTunnelLab.js": "bf7181fdf142a217c55521859bf857e2651129aa07d37b289ede9f8eb7f6dcd0",
+    "frqtl/objects/setup/setupTunnelPointExit.js": "afacecd73a7a4be04b16cb05e6c4d7938f39ed1a494ecc0e3cdd6b37a3b20c2a",
+    "frqtl/objects/setup/setupWaveInterference.js": "4865d77d4b10a16ad6e73d273aa1d0d14117c1ac68d2759621620ed1fb73c29e",
+    "frqtl/objects/v1-replacements.js": "9f3c0a1119e205f408b779a3fd171586c8b6ba8de61d6440c1b2a750832a00b6",
+    "frqtl/package-core.js": "4e645a91edf27f9631dd97aeafc72b11c06a7fbfc0f435d194f4635da872f6d7",
+    "frqtl/parts/CameraControls.js": "03773dfba0e02a2509582f8b268841c1d911c364b7713c9a22adeb46bd7c7331",
+    "frqtl/parts/CameraPath.js": "170ceaad9cdfd5d1de5fc21ca4b1e5dca37a4620b8548ee0538491b13fef022b",
+    "frqtl/parts/CollisionActions.js": "c62b1934935be7a45be9c9adc70fd081a5eaefa3847effa397a0476f23d0efbf",
+    "frqtl/parts/CollisionTypes.js": "ffd276b8f93d5ec2175bd61e9eae4ddc8a2fc5ae9f0f631e603da5b59c54b18d",
+    "frqtl/parts/DetectorWall.js": "691dd13e84d09f11e48c9a519c37c107cd4286f609ed16668d10a4aafe8f5ccd",
+    "frqtl/parts/FrqtlControlOverlay.js": "f862b1529265224aa96878b56b0c1c6e65683ba3fd6b517df86e17e92147f9c4",
+    "frqtl/parts/FrqtlControlsPanel.js": "77fe34d7f2a9e50c2d80e2addbdb483071634d4159e18a67a9169b15e193291d",
+    "frqtl/parts/FrqtlVision.js": "8543b88103f801a4553e0a3dfbd8d12a7dcf3423649af615a704ebe13a21cd3d",
+    "frqtl/parts/GraphingDetectorWall.js": "a83a89493987cb87a5b8a7b8541beaee07d82c37b4906dc7549d116e23d72d16",
+    "frqtl/parts/LargeObject.js": "ab715dbd91c437455dc632bed32402aae2b74ddc5fe746efc472442f500b5482",
+    "frqtl/parts/LightColor.js": "815f5f8de920ad26b112684e3016f72b0335c20c7fec69386c597925a99160f2",
+    "frqtl/parts/LiveChart.js": "b0e2e01c8b0bcb5998e71fc785bb4b7698aa733ffae25ed1cf94a6f4749a78fe",
+    "frqtl/parts/LogicGate.js": "c50ead4aa2a55501a3371ef1c321fa30ea85f7cf4dd62d890ccae998faf80794",
+    "frqtl/parts/OvenBox.js": "2798ee4193154ae2ab4a326ff2af2fccdb8d9dfff4d6c57c32fa0ec92e7999f0",
+    "frqtl/parts/PointSource.js": "ebfade9a117b2ee2cd4824806e417251e235adc50ba994a555e9e827ac8b6ae2",
+    "frqtl/parts/Rectangle.js": "8be4cae13135c3cb185d025dfd10d3a03b21d5627bfa92363c2faa021f751571",
+    "frqtl/parts/SlitLightSource.js": "a24c36dcd16c20da3032ffa3e9ea0506d5519ec49c2ecff03ca1f4a86297ea9d",
+    "frqtl/parts/SlitScreen.js": "74d6f6c6f32b41a7f0d2cf87b27d4fb0702c439fe4d5d80e7747820138472111",
+    "frqtl/parts/SphereEmitter.js": "0c86bcaf78c2bfe311dc557c3e162e59e01f0e34a25d2db01369f87d6dbef3d1",
+    "frqtl/parts/Trace.js": "63944f420b6538a88609a1f251b5f5d909ac9835f556d82f73525077ba6a6df6",
+    "frqtl/parts/Tunnel.js": "3cb65aad93a771867d7a1a9542a3a452325e6c36e85fa5622d67967edf6c152b",
+    "frqtl/parts/Wall.js": "193cf044f0565be281929a8d22181f782868138070dc91a095e9d24f2fe26f61",
+    "frqtl/parts/index.js": "70b8e227e09663889f4c7942d385f843d977579765723f829880fd6e9868ac53",
+    "frqtl/scenes/absorbing-wall-3d.js": "7e0e1e3ab1df56558c2a818fc501e54f90806fc029d8c58ed84fa0bf293717e7",
+    "frqtl/scenes/absorbing-wall.js": "6d5b5eae8f26af998bd41f5b8e304562dd96188f1efdc1900afecd556e92f9c0",
+    "frqtl/scenes/atomic-model.js": "fdbf7c96f1482ea79a3257d75ae28a9e379cbc34414df120678521fac8720007",
+    "frqtl/scenes/big-bang.js": "b6324009a011c34b45e5d19fdf5fae57ca11749d585f8c773032a55d6a42b7d7",
+    "frqtl/scenes/blackbody.js": "b516832c84800aa4ac818a9f90f52e81c1611ca39f1258d49ff1835f057c29a6",
+    "frqtl/scenes/circuit-sat.js": "4d6669bf3191d24134a5340ec1a28871308d005a31e89844879e59e02bd215d7",
+    "frqtl/scenes/collision-matrix-3d.js": "bedd47b7da995e7100040c5598e42d604db46485b875954e0b47e756644b17dd",
+    "frqtl/scenes/counting-wall-3d.js": "ebd09c137b7c56e429da297681db00a4d3ee7e9e5f9fabe74ae9fc4908ce4919",
+    "frqtl/scenes/counting-wall.js": "0ba692fc87d34eee2d3ce258473f709960b24d047a4a9543904b70986214deb4",
+    "frqtl/scenes/double-slit.js": "543b2385c891d64b59486362d1191ba580fcd71934dd15bf90ef1be701d9cf03",
+    "frqtl/scenes/dse-one-emitter.js": "9476e9c91c90141e5505b3911425030d159042a1d3d3813e26db98994ff7c5ac",
+    "frqtl/scenes/dse-one-slit.js": "87af01bbca0f11d199a1afdcc8bf215b35a883ccf07d447ba3100ff9e8dbfda9",
+    "frqtl/scenes/dse-photoelectric.js": "9ef61e14fce7b806bd723135bf64fa8577d5d29330e279eb87c3cf286f5d53ba",
+    "frqtl/scenes/dse-tunnel-rebuild.js": "638e01189882f5fde927db388f73eab997d35d11116e8fdd69774a39ea1ab2ff",
+    "frqtl/scenes/dse-two-emitters.js": "05582b40b7c5e4ca994cc50239cfb7b5b24b58a182c731dccadd11a9696b97c7",
+    "frqtl/scenes/dse-two-slits.js": "bf495e45cca0b7b6a98d5a4ba5ba534de759293c4f3c13528b8d2c6adaa1e840",
+    "frqtl/scenes/empty.js": "90ebe0cee9f0374f564ce49c4b2bba87336c2ab64011d993402d1ff5a22857f7",
+    "frqtl/scenes/laser-buildup.js": "2f9f723191d7034de80bf3dd839ea42c3bd88b325afc540fbdff1e63fed33caa",
+    "frqtl/scenes/mirror-3d.js": "76d40f9e573d48e638a7e4455da5dac9c9094c119ef83d0347bf8365da303b1e",
+    "frqtl/scenes/mirror-route.js": "7e6f2eaa270f71fcf0ec0db4e698e256fb8b5af2ab7f883610ef1b05ba6ba0c3",
+    "frqtl/scenes/mirror.js": "aacac3108a63753de6d0f1cc67f3b8864103e274f4ddb9eda2a8c48126c4a247",
+    "frqtl/scenes/omni-3d.js": "5ebcc692b73196d3dc57d5fbadc117a290d5e6c0022df755ed328c2613a47a62",
+    "frqtl/scenes/omni-source.js": "d872a14258ffe700442216c8932a62cc28cf25ab630a5c8122b42ea0040881cd",
+    "frqtl/scenes/self-interference.js": "24684e3a24687f62cb187a5f4f273b9173201786029585fa454ca875589e11f8",
+    "frqtl/scenes/smoking-gun.js": "4cd62799746f7015b5ac4b0f610f9032d3a8f2db28313f5cb12a8a295484167f",
+    "frqtl/scenes/straight-walk.js": "ef46ff908ab6b60086adee3fb575ed674f0e015e3729afd9d7aa843683a2ee9e",
+    "frqtl/scenes/sun.js": "037e180f436a5d81623d5f5dd5f642f15a25758be20e284d80ed14195c1f911b",
+    "frqtl/scenes/two-source.js": "914f7ba4e0d2ca67f2da126b788196653d4e061734956e43898904e42bd5f428",
+    "frqtl/scenes/wave.js": "ca91454ac21f81e25d3c273bc9ac2ee3b3131b75de1ac38ecac8d89b4f61c344",
+    "shim/bundle/frqnb.js": "9466ee158db6b3333374f77a5f3dd2677565c16038b02b6edb61bd271f257556",
+    "shim/bundle/index.js": "3c3a1dede0f0778acdb78fc063b7c1b3546c14d9b02e72da3f7242be99c82eb1",
+    "shim/bundle/indexHtml.js": "6d3ce242c4f139b542981164fe2b1d8b1c37d9423904bc1299531f594ce4ccc6",
+    "shim/bundle/manifest.js": "71ffd51550bc68cdfb1a5860c3767177e85cbb3d3fbab82c40f178f7d06f21f7",
+    "shim/bundle/zip.js": "9a70845b522a017fabb3df1abb6fa31df8716e83dea603403e40916e25c99a05",
+    "shim/bus.js": "dac2eeccd8774268c51014be4c46c00b9985fdf49ebb44355aa370e949c8c5bc",
+    "shim/controls/index.js": "8a20e458885604b3dea7416171024e3203b87cec59448d8507446c4e474aaaa1",
+    "shim/controls/registry.js": "70400d7e45075ef65e6b14edc5e4e0b97ac8d7042a2c3a78d9be44c93fa973c7",
+    "shim/engine/artifact-shell.js": "89ed0f819f751a3eb53914f92e9547596cebd95347268717cab81c0ba395c88d",
+    "shim/engine/boot-phases.js": "c6e12e12824bcf6f1a289f46e41c898a5416c80c131594525145aae9a3eefbfa",
+    "shim/engine/engine-stack-boot.js": "0abf57dcff2ca2bb025c787a17875d49d54d9218ac08c78cb9c678dbb6118d08",
+    "shim/engine/router.js": "4ca369d6c8d0e8c671172aa35285f3f0599cbcb31f5a4ac02edfe0fd76e57e3f",
+    "shim/experiment-frame/index.js": "5a0219aaa225d8f808c405b08623ce85ada37d83fb4f55f983db3303e431e47f",
+    "shim/expr/ast-schema.js": "3611816832bd0fbc12bf9eaf0d1f959a434cd0a7063ccf25782a6d47634c801f",
+    "shim/field-descriptor/index.js": "78a83aaf47ffe205f18ed31e4c0c6432ea74098942e418265d069985e8fe1351",
+    "shim/frame-data/index.js": "85683ec9befbfbe733d28d3e9a37ad41031c03b799a3efd481fcb50b7a7a6b76",
+    "shim/index.js": "338fd2ef2d11284ad9656dbfd7ea40da5fe94c6c26733ee6ae8d44d9e67d5cea",
+    "shim/notebook/canvas-guard.js": "2a153a1ea2c2bded825a25efd66379c9a55e943f083b39e4fe832d208e22e868",
+    "shim/notebook/catalog.js": "b5fec2797f324fd9c2d99bfb14ba4646d1d31a04796d6adcdb2e4f9247126292",
+    "shim/notebook/format.js": "a4283144a2dc5e8a9404c8e04321ce305b3f7329698d43b949a557269fedda22",
+    "shim/notebook/frqtl-setups-importmap.js": "df86defa90cb85675564e7bb269451684b5cc7679f2c6b1884c07c8272e8ff1c",
+    "shim/notebook/kernel.js": "9225764e15e8d95401c9e1f27024df2ac7447c4b6a924576edb6eed265c38942",
+    "shim/notebook/knob.js": "3bd5ff90dacbedfd8986c765c40302e9d226475e9b254f82eca9cd75309115bb",
+    "shim/notebook/module-resolver.js": "5a976290ccb40bc78353b1ff6e4f6fac427d64ccb2bafbf30f01e1ad1e8e9b9c",
+    "shim/notebook/notebook-knobs.js": "891cd6a24ed70256ed723844918866ba162dd71f839cd06ff4d8fc92a0a17452",
+    "shim/notebook/produced-bindings.js": "d4b12f003d93ebe785a3c1bf44b69d1a2921319bcf6b4bb75688fe297f0f5ae3",
+    "shim/notebook/realm-registry.js": "ffee52e7c93447c8b82bfc0784b51346686b4373766da298f50a759d3443ab6a",
+    "shim/notebook/realm-transport.js": "5173676a94211f85122e0581a16abba925e9c4b5900b5891911bfaec5ea02daf",
+    "shim/notebook/setup-builder.js": "c73d29e07bf18bf3100502ee91fa82f3d4d40a0d7266a8550ceb0b5b1db8dd5a",
+    "shim/notebook/store.js": "ff73cd6f2d9ffa4dc434f15edbf69c5c62360b0ced6a023fd6279f6d95ae895e",
+    "shim/notebook/vendor-importmap.js": "63cb6f496992e58753f3a560af715c2ddf22a2038779d48b37c900c6a98e6a7c",
+    "shim/notebook/view-builder.js": "ebe3432d050636626212cacc051ea683ae0b268f845a8102265cf98af90c205d",
+    "shim/notebook/view-ctx.js": "7c9e19dca5145d37d6df9832721b82deea4ac44b285888c0057023ac4cc767d9",
+    "shim/notebook/view-handle.js": "fe0d1530e3311cb96bb22f5cded35b9f25a0a4ef002588f3e47d9eef8089664d",
+    "shim/notebook/warmup.js": "3cddd4a33a0cf7ea5b44ac5738c908fe6c2d503c0d4331c6e0761a419f7ab39c",
+    "shim/package.json": "609158e6c5fbc237939fa3ddf7faab80ab690bdc0c8d584414a885130103c4e8",
+    "shim/page-params/index.js": "fc04e7a56842b35e962adfaf90a6c25a139564fc068e2f505dd122136852de87",
+    "shim/project/identity.js": "5a0dbd07bfad5c5aa6a529994a604546dbf3e6978b9529ca97ce2c57aa8e563f",
+    "shim/project/index.js": "316b76daf970f3dc245fdb868095fd556ebee98f113de83029cbd76dfacda7ac",
+    "shim/project/link.js": "f1b064052a87a4f8c46fb5fd86402971c436a24adb3c069318b68b5dc694ca5c",
+    "shim/project/node-specifier-hook.mjs": "8601edf762bd9cd011632bc681d0589dfc77368cda0e994125d0eb123fea89d0",
+    "shim/project/register-node.mjs": "9b408da7dc1b11d16237cd62caca281c823ea80173d386ad35e41ea17c34857f",
+    "shim/project/specifiers.js": "a7e7f3dd193783faac00d63360acff525db3af6d0abae012e90bd31c3d29b8ae",
+    "shim/registry/copy-gate.js": "4cc20b35c4b715e3db105263845ed1ed96b1e0115f85f9e56013a4f7498e5925",
+    "shim/registry/exhibits.js": "f75e25297d18af9dc4119cc6fe7a322f03d43b917ff6ae20682f48748e7cb284",
+    "shim/registry/experiments.js": "8a61dc244791ddf62f4e09a27663eadfbde71beeba1d41cff142641ec8ef0a27",
+    "shim/registry/index.js": "2a8e27dc83b5f7eb74b747b511ebc413a0de0dd43e27535296f504535353e2cd",
+    "shim/registry/scene-source.js": "1e02af7af7ee0d879554f9dc12b9aba446d7966a3ea6aa6b4b2e8b460041ab01",
+    "shim/registry/walkthrough.js": "66c959e2e3c7b2a75267e015c190864dbf4f1ccc592cbbb5315b971bb2c41384",
+    "shim/render-state/apply.js": "6b4c830c39b5f669fc1b56b90582fcea00441fd871d7a4edc8ffc37afaebf793",
+    "shim/render-state/index.js": "9015405ef2ea3d88bf004a0aa3bea04eb6bdb86270d68ef5622538a9bae5fa6d",
+    "shim/render/capture-envelope.js": "2667a355169bb124fd8117e9cbf1d630085257b9f6fa537362f12d0aa649da2d",
+    "shim/render/heat-colormap.js": "0eadc758179024734c45eaeffd8f5b44e7c4102b7042767a4a5b66541b3bbd7c",
+    "shim/render/render-stages.js": "cf267ab9cbb20da2f6a2e5555c471cac9f3f5b74e3aab9f29a91685e01ac6f36",
+    "shim/render/sun-look.js": "6367703ed47f493eb7d11de6c10e2748436785c7bc49da2f5bf9d7e949cbd873",
+    "shim/rpc/index.js": "ff8024c05dfa88ed32fd6357d077a7145afe42a166938bdfa4c3fa71a55b79ca",
+    "shim/runtime/index.js": "390a2919fa1acf8c4a60bd852a00d5e64b085131c514a80b3d009b7706391c55",
+    "shim/storage/boot.js": "689504e15dc075e32d08abf61c75a45b1d565c09f086b42400dae40d8186c411",
+    "shim/storage/index.js": "9f10a2ac220e7066493c3da0cea125ab5afb1e3d27d71fbef349f99caaeaa8b9",
+    "shim/storage/local-storage-provider.js": "e14894e5d33bce961e66a2816e4b5c23b8e00534398ca9635d19de117f0f150e",
+    "shim/storage/make-namespace-store.js": "da15fe99b19e25bd6e7f1c9e8a8852b15c43627fc0f9e2eb909503736f850a4a",
+    "shim/storage/modules.js": "7c164e46981e86c7b421a6772c38cb6b9c5a112fc32f29c6048b54f902781a2b",
+    "shim/storage/projects.js": "1c7398dedbb7a67c80acbfe0dfb08ba4f069db9a7d946266c4636212834bd671"
+  }
+}

package/dist/eyes/index.js

@@ -0,0 +1,109 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * eyes.js — the HOSTED EYES entry of `@descix/frqtl-node` (`exports["./eyes"]`), node-only.
+ *
+ * Ships at `dist/eyes/index.js`. It is a SEPARATE entry from `.` for exactly one reason: it is the
+ * only surface in this package with a heavyweight runtime dependency.
+ *
+ * ── Why the dependency is REAL, pinned, and lives HERE ───────────────────────
+ *
+ * `composite` is the render stack's own output. A node raster backend that RE-DREW the
+ * scene would show an agent a different picture than the end user sees — which is the whole
+ * failure the hosted design exists to avoid (a god-rays shader turns a bunch of particles
+ * into A SUN; the renderer and its filters are part of the experiment, not decoration). So
+ * the eyes look through the SAME stack, in a real browser, and the browser is therefore not
+ * an optional extra — it is THE default stack this package ships for anyone who does not
+ * BYO one.
+ *
+ * That is why `playwright` is a real `dependencies` entry, PINNED to an exact version (a
+ * range would let a browser build drift under a published corpus, and the raster path is
+ * provenance — see `build.gl`), and NOT `optionalDependencies`: an optional dependency is a
+ * surface that sometimes exists, which is a compat fence wearing a package-manager hat.
+ * Keeping it off the `.` entry keeps the core install exactly as light as it
+ * was: a consumer who never imports `./eyes` never loads it.
+ *
+ * The BYO seam is `browserType`: pass your own Playwright browser type (or a compatible
+ * driver) and this entry gets out of the way. The library layer
+ * (`lib/frqtl/objects/instruments/hosted-eyes.js`) REQUIRES it and declares no dependency of
+ * its own — the dependency is declared exactly once, by the entry that ships it.
+ *
+ * The picture is the scene SOURCE plus the `renderState` you hand it — nothing else. A
+ * walk-through rung's look (render rows, filters, camera) lives on its registry row, not in its
+ * sketch: pass `effectiveRenderState(rung, mode)` as `renderState` to record the rung as the GYM
+ * shows it; the sketch alone records its PLAIN render.
+ *
+ * @example
+ *   import { openHostedEyes } from '@descix/frqtl-node/eyes';   // or require() from CommonJS
+ *   const eyes = await openHostedEyes({
+ *       sceneRecord: { seed: 42, sourceRef: 'my-scene' },
+ *       sceneSource: { kind: 'project', files: { 'sketch.js': buildExperimentSource }, entry: 'sketch.js' },
+ *       pageUrl: 'http://localhost:8080/experiments/empty/index.html'
+ *   });
+ *   try {
+ *       await eyes.driveToTick(300);
+ *       const still = await eyes.vision.getStill('composite');   // the SAME normalized bag
+ *       eyes.saveStill(still, 'out.png');                        // …and the picture, in one line
+ *   } finally { await eyes.dispose(); }
+ *
+ * `FrqtlVision` is re-exported for the encoder itself (`FrqtlVision.toPNG(still)` → PNG bytes) — the
+ * node half of the one-encoder-per-host pair; it is the parts barrel's own instance.
+ */
+
+import { createRequire } from 'node:module';
+import { FrqtlHostedEyes as HostedEyes } from '../frqtl/objects/instruments/hosted-eyes.js';
+import { FrqtlVision } from '../frqtl/parts/index.js';
+
+// The WRONG-HOST DOOR: `./eyes` DRIVES a browser from node; loaded IN a page it can only fail, so the
+// wrong host gets a thrown error naming the right door, BEFORE any dependency resolves.
+if (typeof document !== 'undefined') {
+    throw new Error(
+        '[frqtl-node/eyes] `@descix/frqtl-node/eyes` is a NODE-HOST surface and this is a browser.\n' +
+        '\n' +
+        'openHostedEyes LAUNCHES a real browser (playwright) and drives a page from outside it —\n' +
+        'there is nothing for it to launch from inside one.\n' +
+        '\n' +
+        'THE RIGHT DOOR IN A PAGE is @descix/frqtl-web:  import { FrqtlCapture, FrqtlVision } from\n' +
+        "'@descix/frqtl-web'  — the in-page capture tap, already looking through THIS page's own\n" +
+        'render stack. To boot a scene into the page first, use  @descix/frqtl-web/boot.\n' +
+        '\n' +
+        '(FAIL-LOUD.)'
+    );
+}
+
+const require = createRequire(import.meta.url);
+let _memoBrowserType = null;
+
+/** The pinned playwright's chromium (resolved on first use). */
+function _defaultBrowserType() {
+    if (_memoBrowserType) { return _memoBrowserType; }
+    let pw;
+    try { pw = require('playwright'); }
+    catch (e) {
+        throw new Error('[frqtl-node/eyes] the pinned `playwright` dependency is not installed ' +
+            '(' + (e && e.message) + '). It is a REAL dependency of this package, not an ' +
+            'optional one: the hosted eyes look through a real browser because that is the only ' +
+            'way an agent sees the real render stack\'s picture. Reinstall the package, or pass your ' +
+            'own `browserType` (the BYO seam). (FAIL-LOUD.)');
+    }
+    if (!pw || !pw.chromium) {
+        throw new Error('[frqtl-node/eyes] `playwright` resolved but exposes no `chromium` browser type. (FAIL-LOUD.)');
+    }
+    _memoBrowserType = pw.chromium;
+    return _memoBrowserType;
+}
+
+/**
+ * openHostedEyes(opts) — HostedEyes.open with the packaged browser as the default `browserType`.
+ * @param {object} opts — see lib/frqtl/objects/instruments/hosted-eyes.js open()
+ * @returns {Promise<object>} the handle
+ */
+export function openHostedEyes(opts) {
+    const bag = Object.assign({}, opts || {});
+    if (!bag.browserType) {
+        Object.defineProperty(bag, 'browserType', { get: _defaultBrowserType, enumerable: true, configurable: true });
+    }
+    return HostedEyes.open(bag);
+}
+
+export { FrqtlVision };