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

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.2` (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.