@fundamental-engine/three 0.4.0

package/dist/bodies.js

@@ -0,0 +1,137 @@
+/**
+ * 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 { Vector3 } from 'three';
+const _w = new Vector3();
+class BodyImpl {
+    object;
+    data;
+    channels = {};
+    el;
+    onFeedback;
+    registry;
+    constructor(registry, object, spec) {
+        this.registry = registry;
+        this.object = object;
+        this.data = spec.data;
+        this.onFeedback = spec.onFeedback;
+        const tokens = Array.isArray(spec.tokens) ? spec.tokens.join(' ') : String(spec.tokens);
+        const attrs = { 'data-body': tokens, ...prefixed(spec.attrs) };
+        if (spec.strength != null)
+            attrs['data-strength'] = String(spec.strength);
+        if (spec.range != null)
+            attrs['data-range'] = String(spec.range);
+        if (spec.spin != null)
+            attrs['data-spin'] = String(spec.spin);
+        if (spec.angle != null)
+            attrs['data-angle'] = String(spec.angle);
+        if (spec.feedback ?? true)
+            attrs['data-feedback'] = '';
+        const half = (spec.sizePx ?? 20) / 2;
+        const self = this;
+        this.el = {
+            // the scanner reads tint from `el.dataset.color` (not getAttribute), so it lives here
+            dataset: spec.color != null ? { color: spec.color } : {},
+            getAttribute: (n) => attrs[n] ?? null,
+            hasAttribute: (n) => n in attrs,
+            getBoundingClientRect: () => {
+                const f = registry.projectToField(self.object);
+                return {
+                    left: f.x - half,
+                    top: f.y - half,
+                    right: f.x + half,
+                    bottom: f.y + half,
+                    width: half * 2,
+                    height: half * 2,
+                    x: f.x - half,
+                    y: f.y - half,
+                    toJSON: () => ({}),
+                };
+            },
+            __body: this,
+        };
+    }
+    /** routed from the registry's sink — store the channels and notify. */
+    receive(channels) {
+        this.channels = channels;
+        this.onFeedback?.(channels, this);
+    }
+    remove() {
+        this.registry.remove(this);
+    }
+}
+function prefixed(attrs) {
+    if (!attrs)
+        return {};
+    const out = {};
+    for (const [k, v] of Object.entries(attrs))
+        out[k.startsWith('data-') ? k : `data-${k}`] = v;
+    return out;
+}
+/**
+ * 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 class FieldBodyRegistry {
+    bodies = [];
+    projection;
+    onChange = () => { };
+    constructor(projection) {
+        this.projection = projection;
+    }
+    /** project a scene object's world position onto the field plane (field pixels). */
+    projectToField(object) {
+        object.getWorldPosition(_w);
+        return this.projection.toField(_w);
+    }
+    /** internal — the FieldLayer re-points this if the projection changes. */
+    setProjection(projection) {
+        this.projection = projection;
+    }
+    /** internal — the FieldLayer wires this to `field.scan()` so adds/removes re-register. */
+    setOnChange(fn) {
+        this.onChange = fn;
+    }
+    /** the scan root the host hands the engine: `[data-body]` queries return the live mesh-bodies. */
+    get root() {
+        const self = this;
+        return {
+            querySelectorAll: (sel) => (sel.startsWith('[data-body]') ? self.bodies.map((b) => b.el) : []),
+            querySelector: () => null,
+        };
+    }
+    /** the feedback sink the field writes through — lands density/load/lit on the body's mesh. */
+    get sink() {
+        return ((el, channels) => {
+            el.__body?.receive(channels);
+        });
+    }
+    add(object, spec) {
+        const body = new BodyImpl(this, object, spec);
+        this.bodies.push(body);
+        this.onChange();
+        return body;
+    }
+    remove(body) {
+        const i = this.bodies.indexOf(body);
+        if (i >= 0) {
+            this.bodies.splice(i, 1);
+            this.onChange();
+        }
+    }
+    /** every registered body (read-only). */
+    all() {
+        return this.bodies;
+    }
+}
+//# sourceMappingURL=bodies.js.map

package/dist/bodies.js.map

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

package/dist/host.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `threeHost` — the `FieldHost` for a WebGL scene. The engine is renderer-agnostic: it reaches the
+ * environment (viewport, animation frame, visibility, input) only through an injected host. This is
+ * the host a Three.js embedding wires — close to `browserHost()`, but the field's viewport comes
+ * from the projection (the field's own pixel space), not `window.innerWidth`, and page-scroll
+ * coupling is off by default (a 3D field has no document scroll unless you opt in).
+ *
+ * `@fundamental-engine/three` is an authoring surface, so unlike `@fundamental-engine/core` it may touch the DOM — the
+ * browser globals here are the same ones any Three.js app already depends on.
+ */
+import type { FieldHost, HostViewport } from '@fundamental-engine/core';
+export interface ThreeHostOptions {
+    /** field-space viewport (CSS pixels) + device-pixel ratio. Wire this to your `FieldProjection`. */
+    viewport: () => HostViewport;
+    /** the subtree scanned for `[data-body]` bodies; omit for a field with no DOM bodies. */
+    root?: ParentNode;
+    /** opt page scroll into the field (drives `scrollV()` / the `scrolling` gate); default off. */
+    scrollY?: () => number;
+    /** total scrollable height when scroll is opted in; defaults to the viewport height. */
+    scrollHeight?: () => number;
+}
+export declare function threeHost(opts: ThreeHostOptions): FieldHost;
+//# sourceMappingURL=host.d.ts.map

package/dist/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAQxE,MAAM,WAAW,gBAAgB;IAC/B,mGAAmG;IACnG,QAAQ,EAAE,MAAM,YAAY,CAAC;IAC7B,yFAAyF;IACzF,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,+FAA+F;IAC/F,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;IACvB,wFAAwF;IACxF,YAAY,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,SAAS,CA2C3D"}

package/dist/host.js

@@ -0,0 +1,62 @@
+/**
+ * `threeHost` — the `FieldHost` for a WebGL scene. The engine is renderer-agnostic: it reaches the
+ * environment (viewport, animation frame, visibility, input) only through an injected host. This is
+ * the host a Three.js embedding wires — close to `browserHost()`, but the field's viewport comes
+ * from the projection (the field's own pixel space), not `window.innerWidth`, and page-scroll
+ * coupling is off by default (a 3D field has no document scroll unless you opt in).
+ *
+ * `@fundamental-engine/three` is an authoring surface, so unlike `@fundamental-engine/core` it may touch the DOM — the
+ * browser globals here are the same ones any Three.js app already depends on.
+ */
+/** A scan root that exposes no `[data-body]` elements — the default for a synthetic / 3D field. */
+const EMPTY_ROOT = {
+    querySelectorAll: () => [],
+    querySelector: () => null,
+};
+export function threeHost(opts) {
+    const root = opts.root ?? EMPTY_ROOT;
+    const events = root.addEventListener
+        ? root
+        : typeof document !== 'undefined'
+            ? document
+            : null;
+    return {
+        root,
+        viewport: opts.viewport,
+        scrollY: opts.scrollY ?? (() => 0),
+        scrollHeight: opts.scrollHeight ?? (() => Math.max(1, opts.viewport().height)),
+        reducedMotion: () => typeof matchMedia !== 'undefined' && matchMedia('(prefers-reduced-motion: reduce)').matches,
+        hidden: () => typeof document !== 'undefined' && document.hidden,
+        raf: (cb) => requestAnimationFrame(cb),
+        cancelRaf: (id) => cancelAnimationFrame(id),
+        createCanvas: () => document.createElement('canvas'),
+        onResize: (cb) => {
+            window.addEventListener('resize', cb, { passive: true });
+            return () => window.removeEventListener('resize', cb);
+        },
+        // a 3D field is not coupled to document scroll by default — opt in via host options if wanted.
+        onScroll: () => () => { },
+        onVisibility: (cb) => {
+            if (typeof document === 'undefined')
+                return () => { };
+            document.addEventListener('visibilitychange', cb);
+            return () => document.removeEventListener('visibilitychange', cb);
+        },
+        onInput: (cb) => {
+            const evs = ['pointermove', 'pointerdown', 'wheel', 'keydown', 'touchstart'];
+            for (const e of evs)
+                window.addEventListener(e, cb, { passive: true });
+            return () => {
+                for (const e of evs)
+                    window.removeEventListener(e, cb);
+            };
+        },
+        onBodyEvent: (type, cb) => {
+            if (!events)
+                return () => { };
+            events.addEventListener(type, cb);
+            return () => events.removeEventListener(type, cb);
+        },
+    };
+}
+//# sourceMappingURL=host.js.map

package/dist/host.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `@fundamental-engine/three` — the Three.js door to the reciprocal field.
+ *
+ * The same engine the `<field-root>` custom element and `@fundamental-engine/{vanilla,react}` wrap, bound to a
+ * WebGL scene instead of the DOM. Two paths, composable:
+ *
+ * 1. **Particle bridge** (`createFieldLayer`) — run the engine headless and render its swarm as a
+ *    `THREE.Points` layer you add to your scene. The fast path to the field in 3D.
+ * 2. **RenderBackend** (`threeBackend`) — implement the engine's structural drawing seam so the
+ *    diagnostic overlays (streamlines, field-lines, grid, contours) draw as scene geometry. Inject
+ *    via `createThreeField({ overlayBackend })`.
+ *
+ * `three` is a peer dependency — you bring your own version. The `FieldProjection` seam keeps the
+ * coordinate model swappable: `PlaneProjection` ships now; a volumetric mode slots in later.
+ *
+ * ```ts
+ * import { createFieldLayer, PlaneProjection } from '@fundamental-engine/three';
+ * const layer = createFieldLayer({ projection: new PlaneProjection({ relief: 2 }), accent: '#4da3ff' });
+ * scene.add(layer.object);
+ * // render loop: layer.tick(); renderer.render(scene, camera);
+ * ```
+ */
+export { FieldLayer, createFieldLayer, createThreeField } from './layer.ts';
+export type { FieldLayerOptions, ThreeFieldOptions } from './layer.ts';
+export { threeHost } from './host.ts';
+export type { ThreeHostOptions } from './host.ts';
+export { threeBackend } from './backend.ts';
+export type { ThreeBackend, ThreeBackendOptions } from './backend.ts';
+export { ParticlePool } from './particles.ts';
+export type { ParticlePoolOptions, ParticleStyle } from './particles.ts';
+export { PlaneProjection, VolumeProjection } from './project.ts';
+export type { FieldProjection, PlaneProjectionOptions, VolumeProjectionOptions } from './project.ts';
+export { FieldBodyRegistry } from './bodies.ts';
+export type { FieldBody, FieldBodySpec } from './bodies.ts';
+export { vectorField, streamlineTubes, traceStreamline } from './samplers.ts';
+export type { FieldSampler, FieldVisual, VectorFieldOptions, StreamlineTubesOptions } from './samplers.ts';
+export { FieldAgent } from './agents.ts';
+export type { FieldAgentOptions } from './agents.ts';
+export { forceAt, netField } from '@fundamental-engine/core';
+export type { FieldHandle, FieldOptions, Particle, Body } from '@fundamental-engine/core';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC5E,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,YAAY,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACzE,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACjE,YAAY,EAAE,eAAe,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAErG,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5D,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC9E,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAE3G,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAIrD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAC7D,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -0,0 +1,37 @@
+/**
+ * `@fundamental-engine/three` — the Three.js door to the reciprocal field.
+ *
+ * The same engine the `<field-root>` custom element and `@fundamental-engine/{vanilla,react}` wrap, bound to a
+ * WebGL scene instead of the DOM. Two paths, composable:
+ *
+ * 1. **Particle bridge** (`createFieldLayer`) — run the engine headless and render its swarm as a
+ *    `THREE.Points` layer you add to your scene. The fast path to the field in 3D.
+ * 2. **RenderBackend** (`threeBackend`) — implement the engine's structural drawing seam so the
+ *    diagnostic overlays (streamlines, field-lines, grid, contours) draw as scene geometry. Inject
+ *    via `createThreeField({ overlayBackend })`.
+ *
+ * `three` is a peer dependency — you bring your own version. The `FieldProjection` seam keeps the
+ * coordinate model swappable: `PlaneProjection` ships now; a volumetric mode slots in later.
+ *
+ * ```ts
+ * import { createFieldLayer, PlaneProjection } from '@fundamental-engine/three';
+ * const layer = createFieldLayer({ projection: new PlaneProjection({ relief: 2 }), accent: '#4da3ff' });
+ * scene.add(layer.object);
+ * // render loop: layer.tick(); renderer.render(scene, camera);
+ * ```
+ */
+export { FieldLayer, createFieldLayer, createThreeField } from "./layer.js";
+export { threeHost } from "./host.js";
+export { threeBackend } from "./backend.js";
+export { ParticlePool } from "./particles.js";
+export { PlaneProjection, VolumeProjection } from "./project.js";
+// Meshes as bodies — register an Object3D as a field body carrying a data record.
+export { FieldBodyRegistry } from "./bodies.js";
+// Native 3D field visuals — vector grids + streamline tubes from FieldHandle.sample().
+export { vectorField, streamlineTubes, traceStreamline } from "./samplers.js";
+// FieldAgent — an Object3D that rides the field: the creatures primitive (bees, fish, drones).
+export { FieldAgent } from "./agents.js";
+// Re-export the field samplers from core so a Three.js consumer building its own field visuals
+// (3D streamline tubes, vector grids, density) has them without a second import.
+export { forceAt, netField } from '@fundamental-engine/core';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE5E,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEjE,kFAAkF;AAClF,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,uFAAuF;AACvF,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAE9E,+FAA+F;AAC/F,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,+FAA+F;AAC/F,iFAAiF;AACjF,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/layer.d.ts

@@ -0,0 +1,115 @@
+/**
+ * `FieldLayer` — the field as a Three.js object. It runs the engine headless (`render: 'none'`) on a
+ * `threeHost`, owns a `ParticlePool`, and on every `tick()` syncs the live swarm onto a
+ * `THREE.Points` you add to your scene via `layer.object`. It implements the full `FieldHandle`
+ * surface (delegating to the wrapped engine), so `burst` / `flowTo` / `setFormation` / `seed` drive
+ * the 3D layer exactly as they drive the DOM field.
+ *
+ * ```ts
+ * const layer = createFieldLayer({ projection: new PlaneProjection({ relief: 2 }), accent: '#4da3ff' });
+ * scene.add(layer.object);
+ * // render loop:
+ * layer.tick();                 // engine self-steps via rAF; tick() pulls the latest swarm
+ * renderer.render(scene, camera);
+ * ```
+ *
+ * The engine self-advances on the host's animation frame; `tick()` only reads the current state into
+ * the geometry, so it is safe to call from any render loop at any cadence.
+ */
+import type { AtomPayload, FieldHandle, FieldOptions, FlowOptions, HostViewport, ThreadLink } from '@fundamental-engine/core';
+import { Group } from 'three';
+import type { Object3D, WebGLRenderer } from 'three';
+import { type FieldProjection } from './project.ts';
+import { ParticlePool, type ParticleStyle } from './particles.ts';
+import { FieldBodyRegistry, type FieldBody, type FieldBodySpec } from './bodies.ts';
+export interface FieldLayerOptions extends Omit<FieldOptions, 'host' | 'render'> {
+    /** the 2D↔3D mapping; defaults to a centered `PlaneProjection`. */
+    projection?: FieldProjection;
+    /** a renderer to read the device-pixel ratio from (used when `dpr` is not given). */
+    renderer?: WebGLRenderer;
+    /** explicit device-pixel ratio override. */
+    dpr?: number;
+    /** `[data-body]` scan root; omit for a field with no DOM bodies. */
+    root?: ParentNode;
+    /** a canvas to satisfy the engine signature; one is created for you when omitted. */
+    canvas?: HTMLCanvasElement;
+    /** max particles the GPU buffers hold; defaults to ~1.25× the seeded pool. */
+    capacity?: number;
+    /** swarm appearance. */
+    style?: ParticleStyle;
+}
+export declare class FieldLayer implements FieldHandle {
+    /** add this to your scene; it holds the swarm `Points` (and future overlay objects). */
+    readonly object: Group;
+    /** the swarm pool — `pool.points`, `pool.size`, `pool.dispose()`. */
+    readonly pool: ParticlePool;
+    /** the active 2D↔3D mapping. */
+    readonly projection: FieldProjection;
+    /** the mesh-bodies registered on this field — `layer.addBody(...)` is the ergonomic entry. */
+    readonly bodies: FieldBodyRegistry;
+    private readonly field;
+    constructor(opts?: FieldLayerOptions);
+    /**
+     * Register a scene object as a field body — it bends the field, the swarm responds, and feedback
+     * (density/load/lit) flows back to it. The body carries `spec.data`, so a mesh can be a meaningful
+     * agent (a bloom with its genome, a hive accruing honey), not just a force. Returns a handle whose
+     * `.data`, `.channels`, and `.remove()` you use; the body tracks the mesh as it moves.
+     */
+    addBody(object: Object3D, spec: FieldBodySpec): FieldBody;
+    /** sync the swarm geometry from the engine's current particle state; returns the live count. */
+    tick(): number;
+    scan(): void;
+    rescan(): void;
+    setAccent(hex: string): void;
+    setPalette(palette: string | readonly string[]): void;
+    setFormation(name: string): void;
+    setAttention(on: boolean): void;
+    setCausality(on: boolean): void;
+    setHeatmap(on: boolean): void;
+    setRender(mode: Parameters<FieldHandle['setRender']>[0]): void;
+    setOverlay(mode: Parameters<FieldHandle['setOverlay']>[0]): void;
+    setVisible(on: boolean): void;
+    threads(list: ThreadLink[] | null): void;
+    burst(x: number, y: number, hex?: string): void;
+    flowTo(x: number, y: number, flowOpts?: FlowOptions): void;
+    clearFlow(): void;
+    seed(atoms: readonly AtomPayload[]): void;
+    atomAt(x: number, y: number): AtomPayload | null;
+    focusAt(x: number, y: number): AtomPayload | null;
+    clearFocus(): void;
+    particleCount(): number;
+    readParticles(out: Float32Array): number;
+    energy(): {
+        kinetic: number;
+        thermal: number;
+        total: number;
+        count: number;
+    };
+    sample(x: number, y: number): {
+        x: number;
+        y: number;
+    };
+    scrollV(): number;
+    setBackground(mode: Parameters<FieldHandle['setBackground']>[0]): void;
+    /** stop the engine, release host listeners, and free the swarm's GPU resources. */
+    destroy(): void;
+}
+/** Construct a `FieldLayer`. The ergonomic entry point — mirrors `mountField()` for Three.js. */
+export declare function createFieldLayer(opts?: FieldLayerOptions): FieldLayer;
+export interface ThreeFieldOptions extends Omit<FieldOptions, 'host'> {
+    /** field-space viewport (CSS pixels) + dpr — wire to your `FieldProjection`. */
+    viewport: () => HostViewport;
+    /** `[data-body]` scan root; omit for a field with no DOM bodies. */
+    root?: ParentNode;
+    /** a canvas to satisfy the engine signature; one is created for you when omitted. */
+    canvas?: HTMLCanvasElement;
+}
+/**
+ * Lower-level builder: `createField` wired to a `threeHost`, returning the raw `FieldHandle` (no
+ * pool, no scene object). Use this when you want the engine on a WebGL scene but will draw it
+ * yourself — e.g. injecting `overlayBackend: threeBackend(...)` to render the diagnostic overlays,
+ * or sampling `forceAt` / `netField` for your own field visuals. `createFieldLayer` is the
+ * batteries-included path; this is the seam under it. (Parallels `createBrowserField`.)
+ */
+export declare function createThreeField(opts: ThreeFieldOptions): FieldHandle;
+//# sourceMappingURL=layer.d.ts.map

package/dist/layer.d.ts.map

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

package/dist/layer.js

@@ -0,0 +1,173 @@
+/**
+ * `FieldLayer` — the field as a Three.js object. It runs the engine headless (`render: 'none'`) on a
+ * `threeHost`, owns a `ParticlePool`, and on every `tick()` syncs the live swarm onto a
+ * `THREE.Points` you add to your scene via `layer.object`. It implements the full `FieldHandle`
+ * surface (delegating to the wrapped engine), so `burst` / `flowTo` / `setFormation` / `seed` drive
+ * the 3D layer exactly as they drive the DOM field.
+ *
+ * ```ts
+ * const layer = createFieldLayer({ projection: new PlaneProjection({ relief: 2 }), accent: '#4da3ff' });
+ * scene.add(layer.object);
+ * // render loop:
+ * layer.tick();                 // engine self-steps via rAF; tick() pulls the latest swarm
+ * renderer.render(scene, camera);
+ * ```
+ *
+ * The engine self-advances on the host's animation frame; `tick()` only reads the current state into
+ * the geometry, so it is safe to call from any render loop at any cadence.
+ */
+import { createField } from '@fundamental-engine/core';
+import { Group } from 'three';
+import { threeHost } from "./host.js";
+import { PlaneProjection, VolumeProjection } from "./project.js";
+import { ParticlePool } from "./particles.js";
+import { FieldBodyRegistry } from "./bodies.js";
+/** Three.js is browser-only; this stub satisfies the `createField` signature (never touched under
+ *  `render: 'none'`, which acquires no 2D context). */
+function stubCanvas() {
+    return typeof document !== 'undefined' ? document.createElement('canvas') : {};
+}
+export class FieldLayer {
+    /** add this to your scene; it holds the swarm `Points` (and future overlay objects). */
+    object;
+    /** the swarm pool — `pool.points`, `pool.size`, `pool.dispose()`. */
+    pool;
+    /** the active 2D↔3D mapping. */
+    projection;
+    /** the mesh-bodies registered on this field — `layer.addBody(...)` is the ergonomic entry. */
+    bodies;
+    field;
+    constructor(opts = {}) {
+        // default the mapping to the field's shape: a real volume when `depth > 0`, else a flat plane.
+        this.projection =
+            opts.projection ?? (opts.depth && opts.depth > 0 ? new VolumeProjection({ depth: opts.depth }) : new PlaneProjection());
+        this.bodies = new FieldBodyRegistry(this.projection);
+        const resolveDpr = () => opts.dpr ?? opts.renderer?.getPixelRatio() ?? (typeof devicePixelRatio !== 'undefined' ? devicePixelRatio : 1);
+        const viewport = () => ({ ...this.projection.size(), dpr: resolveDpr() });
+        // the host scans the body registry; mesh-bodies are added via layer.addBody(...)
+        const host = threeHost({ viewport, root: this.bodies.root });
+        const { projection, renderer, dpr, root, canvas, capacity, style, ...fieldOpts } = opts;
+        void projection;
+        void renderer;
+        void dpr;
+        void root;
+        // route body feedback (density/load/lit) to the meshes instead of CSS custom properties
+        this.field = createField(canvas ?? stubCanvas(), { ...fieldOpts, host, render: 'none', feedbackSink: this.bodies.sink });
+        this.bodies.setOnChange(() => this.field.scan());
+        const cap = Math.max(capacity ?? 0, Math.ceil(this.field.particleCount() * 1.25) + 64);
+        this.pool = new ParticlePool({ capacity: cap, projection: this.projection, style });
+        this.object = new Group();
+        this.object.add(this.pool.points);
+    }
+    /**
+     * Register a scene object as a field body — it bends the field, the swarm responds, and feedback
+     * (density/load/lit) flows back to it. The body carries `spec.data`, so a mesh can be a meaningful
+     * agent (a bloom with its genome, a hive accruing honey), not just a force. Returns a handle whose
+     * `.data`, `.channels`, and `.remove()` you use; the body tracks the mesh as it moves.
+     */
+    addBody(object, spec) {
+        return this.bodies.add(object, spec);
+    }
+    /** sync the swarm geometry from the engine's current particle state; returns the live count. */
+    tick() {
+        return this.pool.sync((out) => this.field.readParticles(out));
+    }
+    // ── FieldHandle surface (delegated to the wrapped engine) ───────────────────────────────────
+    scan() {
+        this.field.scan();
+    }
+    rescan() {
+        this.field.rescan();
+    }
+    setAccent(hex) {
+        this.field.setAccent(hex);
+    }
+    setPalette(palette) {
+        this.field.setPalette(palette);
+    }
+    setFormation(name) {
+        this.field.setFormation(name);
+    }
+    setAttention(on) {
+        this.field.setAttention(on);
+    }
+    setCausality(on) {
+        this.field.setCausality(on);
+    }
+    setHeatmap(on) {
+        this.field.setHeatmap(on);
+    }
+    setRender(mode) {
+        this.field.setRender(mode);
+    }
+    setOverlay(mode) {
+        this.field.setOverlay(mode);
+    }
+    setVisible(on) {
+        this.field.setVisible(on);
+    }
+    threads(list) {
+        this.field.threads(list);
+    }
+    burst(x, y, hex) {
+        this.field.burst(x, y, hex);
+    }
+    flowTo(x, y, flowOpts) {
+        this.field.flowTo(x, y, flowOpts);
+    }
+    clearFlow() {
+        this.field.clearFlow();
+    }
+    seed(atoms) {
+        this.field.seed(atoms);
+    }
+    atomAt(x, y) {
+        return this.field.atomAt(x, y);
+    }
+    focusAt(x, y) {
+        return this.field.focusAt(x, y);
+    }
+    clearFocus() {
+        this.field.clearFocus();
+    }
+    particleCount() {
+        return this.field.particleCount();
+    }
+    readParticles(out) {
+        return this.field.readParticles(out);
+    }
+    energy() {
+        return this.field.energy();
+    }
+    sample(x, y) {
+        return this.field.sample(x, y);
+    }
+    scrollV() {
+        return this.field.scrollV();
+    }
+    setBackground(mode) {
+        this.field.setBackground(mode);
+    }
+    /** stop the engine, release host listeners, and free the swarm's GPU resources. */
+    destroy() {
+        this.field.destroy();
+        this.pool.dispose();
+    }
+}
+/** Construct a `FieldLayer`. The ergonomic entry point — mirrors `mountField()` for Three.js. */
+export function createFieldLayer(opts = {}) {
+    return new FieldLayer(opts);
+}
+/**
+ * Lower-level builder: `createField` wired to a `threeHost`, returning the raw `FieldHandle` (no
+ * pool, no scene object). Use this when you want the engine on a WebGL scene but will draw it
+ * yourself — e.g. injecting `overlayBackend: threeBackend(...)` to render the diagnostic overlays,
+ * or sampling `forceAt` / `netField` for your own field visuals. `createFieldLayer` is the
+ * batteries-included path; this is the seam under it. (Parallels `createBrowserField`.)
+ */
+export function createThreeField(opts) {
+    const { viewport, root, canvas, ...fieldOpts } = opts;
+    const host = threeHost({ viewport, root });
+    return createField(canvas ?? stubCanvas(), { ...fieldOpts, host });
+}
+//# sourceMappingURL=layer.js.map

package/dist/layer.js.map

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