@fundamental-engine/three 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zach Shallbetter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+# @fundamental-engine/three
+
+**The Three.js door to [`@fundamental-engine/core`](../core)** — run the reciprocal field engine headless and
+render its swarm as a `THREE.Points` layer in your own WebGL scene. The same physics the
+`<field-root>` element and `@fundamental-engine/{vanilla,react}` wrap, bound to a 3D scene instead of the DOM.
+
+→ Live manual, Lab, and gallery at **[fundamental-engine.com](https://fundamental-engine.com)**.
+
+## Install
+
+```sh
+npm i @fundamental-engine/three three
+```
+
+`three` is a **peer dependency** — you bring your own version (**≥ 0.147**, the tested floor).
+The package touches only long-stable three APIs (the newest are `InstancedMesh`, r109, and
+`Object3D.clear()`, r123); it is built against modern three (0.169) and r147 is verified live in
+a real integration.
+
+### No build step? (CDN / single-file pages)
+
+The package is plain ESM, so a page with no bundler consumes it straight from a CDN. Pin the
+`three` peer to **the same revision your page already uses** so the library and your scene share
+one Three.js:
+
+```html
+<script type="module">
+  // ?deps pins the peer; match it to your page's three version
+  import * as FieldUI from "https://esm.sh/@fundamental-engine/three@0.3.1?deps=three@0.147.0";
+  window.FieldUI = FieldUI;                          // hand it to classic scripts
+  window.dispatchEvent(new Event("fieldui-ready"));  // module scripts are deferred — signal readiness
+</script>
+<script>
+  // a classic script can't await the module — start on the ready signal
+  function startField() {
+    const layer = window.FieldUI.createFieldLayer({ /* … */ });
+    // scene.add(layer.object); tick in your render loop
+  }
+  if (window.FieldUI) startField();
+  else window.addEventListener("fieldui-ready", startField, { once: true });
+</script>
+```
+
+Prefer a fully offline page? Bundle once with esbuild and commit the artifact, mapping the peer
+onto your page's global `THREE`:
+
+```sh
+echo "module.exports = window.THREE" > three-shim.cjs
+npx esbuild node_modules/@fundamental-engine/three/dist/index.js --bundle --format=iife \
+  --global-name=FieldUI --alias:three=./three-shim.cjs --outfile=vendor/field-ui-three.js
+```
+
+## The particle bridge
+
+The engine runs in signals-only mode (`render: 'none'`) and exposes its particle pool through
+`FieldHandle.readParticles()`. `FieldLayer` pulls that each frame and writes it onto a `THREE.Points`
+geometry via a `FieldProjection`.
+
+```ts
+import * as THREE from 'three';
+import { createFieldLayer, PlaneProjection } from '@fundamental-engine/three';
+
+const scene = new THREE.Scene();
+const renderer = new THREE.WebGLRenderer({ antialias: true });
+
+const layer = createFieldLayer({
+  projection: new PlaneProjection({ relief: 2 }), // the field on a plane, z lifted from heat
+  renderer,                                       // reads the device-pixel ratio
+  accent: '#4da3ff',
+});
+scene.add(layer.object);
+
+renderer.setAnimationLoop(() => {
+  layer.tick();                 // the engine self-steps; tick() pulls the latest swarm
+  renderer.render(scene, camera);
+});
+```
+
+`FieldLayer` implements the full `FieldHandle` surface, so `layer.burst()`, `layer.flowTo()`,
+`layer.setFormation()`, and `layer.seed()` drive the 3D layer exactly as they drive the DOM field.
+
+## Flat plane or real volume
+
+`FieldProjection` maps the engine's CSS-pixel field space to 3D world space:
+
+- **`PlaneProjection`** — the field on a quad; `z` is lifted stylistically from per-particle `heat`.
+  The right choice for a flat field.
+- **`VolumeProjection`** — maps the engine's real **depth lane** (`z ∈ [0, depth)`, the opt-in z axis)
+  onto a world depth range, for a genuinely volumetric swarm.
+
+Pass `depth` and the layer defaults to a `VolumeProjection` automatically — bodies stay on the page
+plane (`z = 0`) while free matter drifts through the volume and is pulled gently back, reading as depth
+and parallax around the content:
+
+```ts
+const layer = createFieldLayer({ depth: 300, renderer, accent: '#4da3ff' });
+```
+
+Both projections implement one interface, so `FieldLayer` and `threeBackend` are unchanged by the choice.
+
+## RenderBackend (diagnostic overlays)
+
+`threeBackend` implements the engine's structural drawing seam (`RenderBackend`), so the diagnostic
+overlays — streamlines, field-lines, grid, contours, force-vector arrows — draw as scene geometry.
+Inject it via the lower-level `createThreeField`:
+
+```ts
+import { createThreeField, threeBackend, PlaneProjection } from '@fundamental-engine/three';
+
+const projection = new PlaneProjection();
+const overlay = threeBackend({ projection });
+scene.add(overlay.object);
+
+const field = createThreeField({
+  viewport: () => ({ ...projection.size(), dpr: renderer.getPixelRatio() }),
+  overlayBackend: overlay,
+  overlay: 'streamlines',
+});
+```
+
+The line overlays render fully; numeric label sprites (the `data` reading) are a tracked follow-up.
+
+## Building your own field visuals
+
+The package re-exports the engine's field samplers — `forceAt` and `netField` — so you can drive
+your own 3D visuals (streamline tubes, vector grids, density volumes) from the live field without a
+second import.
+
+## License
+
+MIT © Zach Shallbetter

package/dist/agents.d.ts

@@ -0,0 +1,73 @@
+/**
+ * `FieldAgent` — an `Object3D` that rides the field: the creatures primitive (#426). The swarm
+ * bridge renders free matter; an agent is a *specific* scene object (a bee, a fish, a drone) that
+ * samples the live field at its own position each frame, steers along the force, and writes its
+ * world position through the shared `FieldProjection`.
+ *
+ * Agents are **consumers, not bodies** — they feel the field but exert nothing back unless you also
+ * register them with `layer.addBody(...)`. The `sampler` is the small `FieldSampler` interface, so
+ * an agent can follow a whole layer, a raw handle, or any custom blend (a wind-only stub, a scaled
+ * mix). Pure math + `Object3D` writes: renderer-free and unit-testable.
+ *
+ * ```ts
+ * const bee = new FieldAgent(beeMesh, { projection, sampler: layer, maxSpeed: 90 });
+ * // render loop:
+ * bee.update(dt);
+ * ```
+ */
+import type { Object3D } from 'three';
+import type { FieldProjection } from './project.ts';
+import type { FieldSampler } from './samplers.ts';
+export interface FieldAgentOptions {
+    /** the 2D↔3D mapping (share the layer's so agents and swarm agree). */
+    projection: FieldProjection;
+    /** what to follow — anything with `sample(x, y)`: a `FieldLayer`, a `FieldHandle`, a stub. */
+    sampler: FieldSampler;
+    /** top speed in field px/s (default 80). */
+    maxSpeed?: number;
+    /** acceleration along the sampled force, px/s² per unit force (default 240). */
+    accel?: number;
+    /** velocity damping per second — higher coasts to rest sooner in a dead field (default 1.4). */
+    drag?: number;
+    /** random wander acceleration in px/s² so agents don't railroad one streamline (default 0). */
+    wander?: number;
+    /** optional world-y hover bob layered on the projected position. */
+    hover?: {
+        amp: number;
+        freq: number;
+    };
+    /** orient the object along its travel direction each update (default true). */
+    faceVelocity?: boolean;
+    /** deterministic random source for `wander` (default `Math.random`). */
+    rng?: () => number;
+}
+export declare class FieldAgent {
+    /** the scene object this agent drives. */
+    readonly object: Object3D;
+    /** position in field pixels — read/write (set it to spawn or teleport). */
+    fieldPosition: {
+        x: number;
+        y: number;
+    };
+    /** velocity in field px/s (read/write). */
+    velocity: {
+        x: number;
+        y: number;
+    };
+    private readonly projection;
+    private readonly sampler;
+    private readonly maxSpeed;
+    private readonly accel;
+    private readonly drag;
+    private readonly wander;
+    private readonly hover?;
+    private readonly faceVelocity;
+    private readonly rng;
+    private t;
+    private readonly phase;
+    private readonly look;
+    constructor(object: Object3D, opts: FieldAgentOptions);
+    /** sample → steer → integrate → write the object's position. Call once per frame with dt in s. */
+    update(dt: number): void;
+}
+//# sourceMappingURL=agents.d.ts.map

package/dist/agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACtC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAIlD,MAAM,WAAW,iBAAiB;IAChC,uEAAuE;IACvE,UAAU,EAAE,eAAe,CAAC;IAC5B,8FAA8F;IAC9F,OAAO,EAAE,YAAY,CAAC;IACtB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gGAAgG;IAChG,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+FAA+F;IAC/F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,KAAK,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACtC,+EAA+E;IAC/E,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,wEAAwE;IACxE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,qBAAa,UAAU;IACrB,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,2EAA2E;IAC3E,aAAa,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACxC,2CAA2C;IAC3C,QAAQ,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAEnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkB;IAC7C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAgC;IACvD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAU;IACvC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,CAAC,CAAK;IACd,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiB;gBAE1B,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,iBAAiB;IAuBrD,kGAAkG;IAClG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;CAyCzB"}

package/dist/agents.js

@@ -0,0 +1,114 @@
+/**
+ * `FieldAgent` — an `Object3D` that rides the field: the creatures primitive (#426). The swarm
+ * bridge renders free matter; an agent is a *specific* scene object (a bee, a fish, a drone) that
+ * samples the live field at its own position each frame, steers along the force, and writes its
+ * world position through the shared `FieldProjection`.
+ *
+ * Agents are **consumers, not bodies** — they feel the field but exert nothing back unless you also
+ * register them with `layer.addBody(...)`. The `sampler` is the small `FieldSampler` interface, so
+ * an agent can follow a whole layer, a raw handle, or any custom blend (a wind-only stub, a scaled
+ * mix). Pure math + `Object3D` writes: renderer-free and unit-testable.
+ *
+ * ```ts
+ * const bee = new FieldAgent(beeMesh, { projection, sampler: layer, maxSpeed: 90 });
+ * // render loop:
+ * bee.update(dt);
+ * ```
+ */
+import { Vector3 } from 'three';
+const _w = new Vector3();
+export class FieldAgent {
+    /** the scene object this agent drives. */
+    object;
+    /** position in field pixels — read/write (set it to spawn or teleport). */
+    fieldPosition;
+    /** velocity in field px/s (read/write). */
+    velocity;
+    projection;
+    sampler;
+    maxSpeed;
+    accel;
+    drag;
+    wander;
+    hover;
+    faceVelocity;
+    rng;
+    t = 0;
+    phase;
+    look = new Vector3();
+    constructor(object, opts) {
+        this.object = object;
+        this.projection = opts.projection;
+        this.sampler = opts.sampler;
+        this.maxSpeed = opts.maxSpeed ?? 80;
+        this.accel = opts.accel ?? 240;
+        this.drag = opts.drag ?? 1.4;
+        this.wander = opts.wander ?? 0;
+        this.hover = opts.hover;
+        this.faceVelocity = opts.faceVelocity ?? true;
+        this.rng = opts.rng ?? Math.random;
+        this.phase = this.rng() * Math.PI * 2;
+        // spawn where the object currently sits (world → field); centre if it has no position yet
+        object.getWorldPosition(_w);
+        this.fieldPosition = this.projection.toField(_w);
+        if (!Number.isFinite(this.fieldPosition.x) || !Number.isFinite(this.fieldPosition.y)) {
+            const { width, height } = this.projection.size();
+            this.fieldPosition = { x: width / 2, y: height / 2 };
+        }
+        this.velocity = { x: 0, y: 0 };
+    }
+    /** sample → steer → integrate → write the object's position. Call once per frame with dt in s. */
+    update(dt) {
+        if (!(dt > 0))
+            return;
+        this.t += dt;
+        const p = this.fieldPosition;
+        const v = this.velocity;
+        const f = this.sampler.sample(p.x, p.y);
+        v.x += f.x * this.accel * dt;
+        v.y += f.y * this.accel * dt;
+        if (this.wander > 0) {
+            v.x += (this.rng() * 2 - 1) * this.wander * dt;
+            v.y += (this.rng() * 2 - 1) * this.wander * dt;
+        }
+        // drag, then clamp to top speed
+        const damp = Math.max(0, 1 - this.drag * dt);
+        v.x *= damp;
+        v.y *= damp;
+        const speed = Math.hypot(v.x, v.y);
+        if (speed > this.maxSpeed) {
+            v.x = (v.x / speed) * this.maxSpeed;
+            v.y = (v.y / speed) * this.maxSpeed;
+        }
+        p.x += v.x * dt;
+        p.y += v.y * dt;
+        // keep agents inside the field with a soft edge bounce
+        const { width, height } = this.projection.size();
+        if (p.x < 0) {
+            p.x = 0;
+            v.x = Math.abs(v.x);
+        }
+        if (p.y < 0) {
+            p.y = 0;
+            v.y = Math.abs(v.y);
+        }
+        if (p.x > width) {
+            p.x = width;
+            v.x = -Math.abs(v.x);
+        }
+        if (p.y > height) {
+            p.y = height;
+            v.y = -Math.abs(v.y);
+        }
+        this.projection.toWorld(p.x, p.y, 0, 0, 0, this.object.position);
+        if (this.hover)
+            this.object.position.y += Math.sin(this.t * this.hover.freq + this.phase) * this.hover.amp;
+        if (this.faceVelocity && speed > 1e-3) {
+            // look one step ahead along the travel direction, in world space
+            this.projection.toWorld(p.x + v.x * 0.1, p.y + v.y * 0.1, 0, 0, 0, this.look);
+            this.look.y = this.object.position.y;
+            this.object.lookAt(this.look);
+        }
+    }
+}
+//# sourceMappingURL=agents.js.map

package/dist/agents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.js","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"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"}

package/dist/backend.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `threeBackend` — a `RenderBackend` (the engine's structural drawing seam, #373) that draws the
+ * overlay readings as Three.js geometry instead of a 2D canvas. Inject it via
+ * `createField({ overlayBackend })` (or `createThreeField`) and add `backend.object` to your scene.
+ *
+ * The engine describes WHAT to draw in CSS-pixel primitives; this backend owns HOW — mapping those
+ * pixels through the `FieldProjection` onto an overlay plane and batching them into a `LineSegments`
+ * (arrows, field-lines, grid, contours, traced paths) and a triangle `Mesh` (the data-chip plates).
+ * Per-stroke alpha is premultiplied into the vertex color and composited additively, so magnitude
+ * still reads. Geometry is rebuilt on each `clear()` (the engine clears once at the top of every
+ * overlay frame), so the scene always shows the latest readings.
+ *
+ * Scope: the line + rect primitives — i.e. every field-structure overlay — render fully. Text
+ * labels (the `data` reading's numeric chips) are not yet drawn; `measureText` is honored so the
+ * plates size correctly, and label sprites are a tracked follow-up. The line overlays need no text.
+ */
+import { Group } from 'three';
+import type { RenderBackend } from '@fundamental-engine/core';
+import type { FieldProjection } from './project.ts';
+export interface ThreeBackendOptions {
+    /** the 2D↔3D mapping (share the one your `FieldLayer` uses so overlay and swarm align). */
+    projection: FieldProjection;
+    /** world-space `z` the overlay draws at — put it just in front of a flat field (default 0.01). */
+    z?: number;
+}
+export interface ThreeBackend extends RenderBackend {
+    /** add this to your scene to show the overlay readings. */
+    readonly object: Group;
+    /** release GPU resources. */
+    dispose(): void;
+}
+export declare function threeBackend(opts: ThreeBackendOptions): ThreeBackend;
+//# sourceMappingURL=backend.d.ts.map

package/dist/backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAIL,KAAK,EAMN,MAAM,OAAO,CAAC;AACf,OAAO,KAAK,EAAE,aAAa,EAAU,MAAM,0BAA0B,CAAC;AACtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAIpD,MAAM,WAAW,mBAAmB;IAClC,2FAA2F;IAC3F,UAAU,EAAE,eAAe,CAAC;IAC5B,kGAAkG;IAClG,CAAC,CAAC,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,YAAa,SAAQ,aAAa;IACjD,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC;IACvB,6BAA6B;IAC7B,OAAO,IAAI,IAAI,CAAC;CACjB;AAQD,wBAAgB,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,YAAY,CA2GpE"}

package/dist/backend.js

@@ -0,0 +1,120 @@
+/**
+ * `threeBackend` — a `RenderBackend` (the engine's structural drawing seam, #373) that draws the
+ * overlay readings as Three.js geometry instead of a 2D canvas. Inject it via
+ * `createField({ overlayBackend })` (or `createThreeField`) and add `backend.object` to your scene.
+ *
+ * The engine describes WHAT to draw in CSS-pixel primitives; this backend owns HOW — mapping those
+ * pixels through the `FieldProjection` onto an overlay plane and batching them into a `LineSegments`
+ * (arrows, field-lines, grid, contours, traced paths) and a triangle `Mesh` (the data-chip plates).
+ * Per-stroke alpha is premultiplied into the vertex color and composited additively, so magnitude
+ * still reads. Geometry is rebuilt on each `clear()` (the engine clears once at the top of every
+ * overlay frame), so the scene always shows the latest readings.
+ *
+ * Scope: the line + rect primitives — i.e. every field-structure overlay — render fully. Text
+ * labels (the `data` reading's numeric chips) are not yet drawn; `measureText` is honored so the
+ * plates size correctly, and label sprites are a tracked follow-up. The line overlays need no text.
+ */
+import { AdditiveBlending, BufferGeometry, Float32BufferAttribute, Group, LineBasicMaterial, LineSegments, Mesh, MeshBasicMaterial, Vector3, } from 'three';
+const _v = new Vector3();
+/** A lazily-created 2D context purely for text metrics — never rendered to. */
+function metricsContext() {
+    if (typeof document === 'undefined')
+        return null;
+    return document.createElement('canvas').getContext('2d');
+}
+export function threeBackend(opts) {
+    const projection = opts.projection;
+    const z = opts.z ?? 0.01;
+    const linePos = [];
+    const lineCol = [];
+    const rectPos = [];
+    const rectCol = [];
+    const lineGeom = new BufferGeometry();
+    const lines = new LineSegments(lineGeom, new LineBasicMaterial({ vertexColors: true, transparent: true, depthWrite: false, blending: AdditiveBlending }));
+    lines.frustumCulled = false;
+    const rectGeom = new BufferGeometry();
+    const rects = new Mesh(rectGeom, new MeshBasicMaterial({ vertexColors: true, transparent: true, depthWrite: false, blending: AdditiveBlending }));
+    rects.frustumCulled = false;
+    const object = new Group();
+    object.add(lines, rects);
+    const metrics = metricsContext();
+    /** map a CSS-pixel point to the overlay plane and push xyz onto `arr` (overlay owns its own z). */
+    function pushPoint(arr, x, y) {
+        projection.toWorld(x, y, 0, 0, 0, _v); // z/heat/size irrelevant — the overlay draws at a fixed plane
+        arr.push(_v.x, _v.y, z);
+    }
+    /** premultiplied 0..1 rgb (additive compositing turns alpha into intensity). */
+    function pushColor(arr, r, g, b, a) {
+        arr.push((r / 255) * a, (g / 255) * a, (b / 255) * a);
+    }
+    function flush() {
+        lineGeom.setAttribute('position', new Float32BufferAttribute(Float32Array.from(linePos), 3));
+        lineGeom.setAttribute('color', new Float32BufferAttribute(Float32Array.from(lineCol), 3));
+        lineGeom.setDrawRange(0, linePos.length / 3);
+        rectGeom.setAttribute('position', new Float32BufferAttribute(Float32Array.from(rectPos), 3));
+        rectGeom.setAttribute('color', new Float32BufferAttribute(Float32Array.from(rectCol), 3));
+        rectGeom.setDrawRange(0, rectPos.length / 3);
+    }
+    return {
+        object,
+        size() {
+            // the projection owns the field→world transform; nothing to size on the GPU here.
+        },
+        clear() {
+            // finalize the frame just drawn, then reset the accumulators for the next one.
+            flush();
+            linePos.length = 0;
+            lineCol.length = 0;
+            rectPos.length = 0;
+            rectCol.length = 0;
+        },
+        segments(packed, stroke) {
+            for (let i = 0; i + 3 < packed.length; i += 4) {
+                pushPoint(linePos, packed[i], packed[i + 1]);
+                pushPoint(linePos, packed[i + 2], packed[i + 3]);
+                pushColor(lineCol, stroke.r, stroke.g, stroke.b, stroke.alpha);
+                pushColor(lineCol, stroke.r, stroke.g, stroke.b, stroke.alpha);
+            }
+        },
+        polyline(points, stroke) {
+            // expand the connected polyline into the disjoint-segment buffer (pairs of consecutive points)
+            for (let i = 0; i + 3 < points.length; i += 2) {
+                pushPoint(linePos, points[i], points[i + 1]);
+                pushPoint(linePos, points[i + 2], points[i + 3]);
+                pushColor(lineCol, stroke.r, stroke.g, stroke.b, stroke.alpha);
+                pushColor(lineCol, stroke.r, stroke.g, stroke.b, stroke.alpha);
+            }
+        },
+        rect(x, y, w, h, r, g, b, alpha) {
+            // two triangles (x,y)-(x+w,y+h); the data-chip plate
+            const x2 = x + w;
+            const y2 = y + h;
+            pushPoint(rectPos, x, y);
+            pushPoint(rectPos, x2, y);
+            pushPoint(rectPos, x2, y2);
+            pushPoint(rectPos, x, y);
+            pushPoint(rectPos, x2, y2);
+            pushPoint(rectPos, x, y2);
+            for (let k = 0; k < 6; k++)
+                pushColor(rectCol, r, g, b, alpha);
+        },
+        text() {
+            // label sprites are a tracked follow-up; the line overlays need no text, and the chip plate
+            // (rect) still renders. measureText is honored so plate sizing stays correct.
+        },
+        measureText(value) {
+            if (metrics) {
+                metrics.font = '10px ui-monospace, SFMono-Regular, Menlo, monospace';
+                return metrics.measureText(value).width;
+            }
+            return value.length * 6; // coarse fallback when no 2D context is available
+        },
+        dispose() {
+            lineGeom.dispose();
+            rectGeom.dispose();
+            lines.material.dispose();
+            rects.material.dispose();
+        },
+    };
+}
+//# sourceMappingURL=backend.js.map

package/dist/backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"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"}

package/dist/bodies.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Meshes as bodies — the 3D form of field-ui's core idea ("every element is a body"). A
+ * `THREE.Object3D` registers as a field body: it bends the field (bodies are force sources), the
+ * swarm responds to it, and the field's local density bends *it* back through feedback. And because
+ * a body **carries a data record**, a mesh can be a meaningful agent — a bloom carrying its genome,
+ * a hive accumulating honey — not just a force.
+ *
+ * It needs no core change: the engine builds a body from anything implementing the small element
+ * contract (`getAttribute` / `hasAttribute` / `dataset` / `getBoundingClientRect`), so each body is a
+ * lightweight non-DOM "virtual element" whose rect is the mesh's position projected onto the field
+ * plane, refreshed live as the mesh moves. Feedback is routed to the body via a custom sink, so
+ * `density` / `load` / `lit` land on the mesh (drive a uniform, accumulate a value) instead of CSS.
+ */
+import type { Object3D } from 'three';
+import type { FeedbackChannels, FeedbackSink } from '@fundamental-engine/core';
+import type { FieldProjection } from './project.ts';
+export interface FieldBodySpec {
+    /** force token(s) the body radiates — e.g. `'attract'`, `'gravity'`, `['charge', 'swirl']`. */
+    tokens: string | readonly string[];
+    /** force magnitude (`data-strength`). */
+    strength?: number;
+    /** influence radius in field pixels (`data-range`). */
+    range?: number;
+    /** swirl / charge sign (`data-spin`). */
+    spin?: number;
+    /** heading in radians for directional forces (`data-angle`). */
+    angle?: number;
+    /** the body's tint (`data-color`) — the `pigment` force dyes passing matter with it, so the
+     *  swarm visibly carries this body's color to wherever it drifts next (conserved color transport). */
+    color?: string;
+    /** opt into density/load feedback back onto the mesh (default `true`). */
+    feedback?: boolean;
+    /** the body's box half-size in field pixels — its footprint, not its range (default 20). */
+    sizePx?: number;
+    /** the carried record: a genome, an inventory, anything. Opaque to the engine; yours to read. */
+    data?: unknown;
+    /** raw `data-*` passthrough (without the `data-` prefix) for tokens this spec doesn't model. */
+    attrs?: Record<string, string>;
+    /** called each frame the body has feedback, with its live channels — drive a uniform from here. */
+    onFeedback?: (channels: FeedbackChannels, body: FieldBody) => void;
+}
+export interface FieldBody {
+    /** the registered scene object. */
+    readonly object: Object3D;
+    /** the carried record — read it when a pollinator reaches this bloom, mutate it freely. */
+    data: unknown;
+    /** the body's most recent feedback (density/load/lit/…); `{}` until the field writes. */
+    readonly channels: Readonly<FeedbackChannels>;
+    /** unregister this body from the field. */
+    remove(): void;
+}
+/**
+ * Manages the mesh-bodies for one field. Provides the `root` the host scans and the `sink` that
+ * routes feedback to meshes; a `FieldLayer` wires both. Add via `layer.addBody(...)`.
+ */
+export declare class FieldBodyRegistry {
+    private bodies;
+    private projection;
+    private onChange;
+    constructor(projection: FieldProjection);
+    /** project a scene object's world position onto the field plane (field pixels). */
+    projectToField(object: Object3D): {
+        x: number;
+        y: number;
+    };
+    /** internal — the FieldLayer re-points this if the projection changes. */
+    setProjection(projection: FieldProjection): void;
+    /** internal — the FieldLayer wires this to `field.scan()` so adds/removes re-register. */
+    setOnChange(fn: () => void): void;
+    /** the scan root the host hands the engine: `[data-body]` queries return the live mesh-bodies. */
+    get root(): ParentNode;
+    /** the feedback sink the field writes through — lands density/load/lit on the body's mesh. */
+    get sink(): FeedbackSink;
+    add(object: Object3D, spec: FieldBodySpec): FieldBody;
+    remove(body: FieldBody): void;
+    /** every registered body (read-only). */
+    all(): readonly FieldBody[];
+}
+//# sourceMappingURL=bodies.d.ts.map

package/dist/bodies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bodies.d.ts","sourceRoot":"","sources":["../src/bodies.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC/E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAIpD,MAAM,WAAW,aAAa;IAC5B,+FAA+F;IAC/F,MAAM,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IACnC,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;0GACsG;IACtG,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,4FAA4F;IAC5F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iGAAiG;IACjG,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,gGAAgG;IAChG,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,mGAAmG;IACnG,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,gBAAgB,EAAE,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;CACpE;AAED,MAAM,WAAW,SAAS;IACxB,mCAAmC;IACnC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,2FAA2F;IAC3F,IAAI,EAAE,OAAO,CAAC;IACd,yFAAyF;IACzF,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC;IAC9C,2CAA2C;IAC3C,MAAM,IAAI,IAAI,CAAC;CAChB;AAsFD;;;GAGG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,UAAU,CAAkB;IACpC,OAAO,CAAC,QAAQ,CAAwB;gBAE5B,UAAU,EAAE,eAAe;IAIvC,mFAAmF;IACnF,cAAc,CAAC,MAAM,EAAE,QAAQ,GAAG;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE;IAK1D,0EAA0E;IAC1E,aAAa,CAAC,UAAU,EAAE,eAAe,GAAG,IAAI;IAIhD,0FAA0F;IAC1F,WAAW,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI;IAIjC,kGAAkG;IAClG,IAAI,IAAI,IAAI,UAAU,CAMrB;IAED,8FAA8F;IAC9F,IAAI,IAAI,IAAI,YAAY,CAIvB;IAED,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,aAAa,GAAG,SAAS;IAOrD,MAAM,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAQ7B,yCAAyC;IACzC,GAAG,IAAI,SAAS,SAAS,EAAE;CAG5B"}