@fundamental-engine/three 0.4.0

package/dist/particles.d.ts

@@ -0,0 +1,58 @@
+/**
+ * `ParticlePool` — the particle bridge. The engine runs headless (`render: 'none'`) and exposes its
+ * swarm through `FieldHandle.readParticles(buf)` (stride 5: `x, y, z, heat, size`). This pool pulls
+ * that buffer each frame and writes it onto a `THREE.Points` geometry via the `FieldProjection` —
+ * position from `(x, y, z)`, an `aHeat`/`aSize` attribute per vertex for the material. Zero per-frame
+ * allocation: the typed buffers are sized once to `capacity`.
+ *
+ * The conversion (`write`) is a pure function of the packed buffer + projection, so it is unit-
+ * testable without a WebGL context; only the live `sync` needs a running field.
+ */
+import { BufferGeometry, Points, ShaderMaterial } from 'three';
+import type { FieldProjection } from './project.ts';
+export interface ParticleStyle {
+    /** color of cool (heat 0) matter (default a dim slate). */
+    base?: string;
+    /** color matter blends toward as it heats (default the field accent blue). */
+    accent?: string;
+    /** overall point-size multiplier (default 1). */
+    size?: number;
+    /** perspective focal term — larger = points shrink less with distance (default 300). */
+    focal?: number;
+}
+export interface ParticlePoolOptions {
+    /** maximum particles the buffers hold; the engine's live count is clamped to this. */
+    capacity: number;
+    /** the 2D↔3D mapping. */
+    projection: FieldProjection;
+    /** appearance. */
+    style?: ParticleStyle;
+}
+export declare class ParticlePool {
+    readonly points: Points;
+    readonly geometry: BufferGeometry;
+    readonly material: ShaderMaterial;
+    readonly capacity: number;
+    private readonly projection;
+    /** stride-4 staging buffer `readParticles` fills: `[x, y, heat, size, …]`. */
+    private readonly packed;
+    private readonly position;
+    private readonly aHeat;
+    private readonly aSize;
+    private count;
+    constructor(opts: ParticlePoolOptions);
+    /** the live particle count written by the last `sync`/`write`. */
+    get size(): number;
+    /** pull from a `readParticles`-shaped reader and push onto the geometry; returns the count. */
+    sync(read: (out: Float32Array) => number): number;
+    /**
+     * Convert the first `n` particles in the staging buffer into geometry attributes. Pure given the
+     * projection — call directly in a test with a pre-filled `packed` buffer (via `staging`).
+     */
+    write(n: number): number;
+    /** the stride-5 staging buffer (`[x, y, z, heat, size]`) — exposed for tests to fill before `write`. */
+    get staging(): Float32Array;
+    /** release GPU resources. */
+    dispose(): void;
+}
+//# sourceMappingURL=particles.d.ts.map

package/dist/particles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"particles.d.ts","sourceRoot":"","sources":["../src/particles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAEL,cAAc,EAGd,MAAM,EACN,cAAc,EAEf,MAAM,OAAO,CAAC;AACf,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAIpD,MAAM,WAAW,aAAa;IAC5B,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wFAAwF;IACxF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,sFAAsF;IACtF,QAAQ,EAAE,MAAM,CAAC;IACjB,yBAAyB;IACzB,UAAU,EAAE,eAAe,CAAC;IAC5B,kBAAkB;IAClB,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AA2CD,qBAAa,YAAY;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkB;IAC7C,8EAA8E;IAC9E,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;IAClD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAyB;IAC/C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAyB;IAC/C,OAAO,CAAC,KAAK,CAAK;gBAEN,IAAI,EAAE,mBAAmB;IAsBrC,kEAAkE;IAClE,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,+FAA+F;IAC/F,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,YAAY,KAAK,MAAM,GAAG,MAAM;IAIjD;;;OAGG;IACH,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM;IA6BxB,wGAAwG;IACxG,IAAI,OAAO,IAAI,YAAY,CAE1B;IAED,6BAA6B;IAC7B,OAAO,IAAI,IAAI;CAIhB"}

package/dist/particles.js

@@ -0,0 +1,127 @@
+/**
+ * `ParticlePool` — the particle bridge. The engine runs headless (`render: 'none'`) and exposes its
+ * swarm through `FieldHandle.readParticles(buf)` (stride 5: `x, y, z, heat, size`). This pool pulls
+ * that buffer each frame and writes it onto a `THREE.Points` geometry via the `FieldProjection` —
+ * position from `(x, y, z)`, an `aHeat`/`aSize` attribute per vertex for the material. Zero per-frame
+ * allocation: the typed buffers are sized once to `capacity`.
+ *
+ * The conversion (`write`) is a pure function of the packed buffer + projection, so it is unit-
+ * testable without a WebGL context; only the live `sync` needs a running field.
+ */
+import { AdditiveBlending, BufferGeometry, Color, Float32BufferAttribute, Points, ShaderMaterial, Vector3, } from 'three';
+const _v = new Vector3();
+/** The shader: color by `aHeat` (base→accent), size by `aSize` with perspective attenuation. */
+function particleMaterial(style) {
+    return new ShaderMaterial({
+        uniforms: {
+            uBase: { value: new Color(style.base ?? '#3a4a63') },
+            uAccent: { value: new Color(style.accent ?? '#4da3ff') },
+            uSize: { value: style.size ?? 1 },
+            uFocal: { value: style.focal ?? 300 },
+        },
+        vertexShader: /* glsl */ `
+      attribute float aHeat;
+      attribute float aSize;
+      varying float vHeat;
+      uniform float uSize;
+      uniform float uFocal;
+      void main() {
+        vHeat = aHeat;
+        vec4 mv = modelViewMatrix * vec4(position, 1.0);
+        float s = aSize * uSize * (uFocal / max(0.0001, -mv.z));
+        gl_PointSize = clamp(s, 1.0, 48.0);
+        gl_Position = projectionMatrix * mv;
+      }
+    `,
+        fragmentShader: /* glsl */ `
+      varying float vHeat;
+      uniform vec3 uBase;
+      uniform vec3 uAccent;
+      void main() {
+        float r = length(gl_PointCoord - vec2(0.5));
+        if (r > 0.5) discard;
+        float glow = smoothstep(0.5, 0.0, r);
+        vec3 c = mix(uBase, uAccent, clamp(vHeat, 0.0, 1.0));
+        gl_FragColor = vec4(c, glow);
+      }
+    `,
+        transparent: true,
+        depthWrite: false,
+        blending: AdditiveBlending,
+    });
+}
+export class ParticlePool {
+    points;
+    geometry;
+    material;
+    capacity;
+    projection;
+    /** stride-4 staging buffer `readParticles` fills: `[x, y, heat, size, …]`. */
+    packed;
+    position;
+    aHeat;
+    aSize;
+    count = 0;
+    constructor(opts) {
+        this.capacity = Math.max(1, opts.capacity | 0);
+        this.projection = opts.projection;
+        this.packed = new Float32Array(this.capacity * 5);
+        this.geometry = new BufferGeometry();
+        this.position = new Float32BufferAttribute(new Float32Array(this.capacity * 3), 3);
+        this.aHeat = new Float32BufferAttribute(new Float32Array(this.capacity), 1);
+        this.aSize = new Float32BufferAttribute(new Float32Array(this.capacity), 1);
+        this.position.setUsage(35048 /* DynamicDrawUsage */);
+        this.aHeat.setUsage(35048);
+        this.aSize.setUsage(35048);
+        this.geometry.setAttribute('position', this.position);
+        this.geometry.setAttribute('aHeat', this.aHeat);
+        this.geometry.setAttribute('aSize', this.aSize);
+        this.geometry.setDrawRange(0, 0);
+        this.material = particleMaterial(opts.style ?? {});
+        this.points = new Points(this.geometry, this.material);
+        this.points.frustumCulled = false; // positions live in the attribute, not a static bound
+    }
+    /** the live particle count written by the last `sync`/`write`. */
+    get size() {
+        return this.count;
+    }
+    /** pull from a `readParticles`-shaped reader and push onto the geometry; returns the count. */
+    sync(read) {
+        return this.write(read(this.packed));
+    }
+    /**
+     * Convert the first `n` particles in the staging buffer into geometry attributes. Pure given the
+     * projection — call directly in a test with a pre-filled `packed` buffer (via `staging`).
+     */
+    write(n) {
+        const count = Math.min(n, this.capacity);
+        const pos = this.position.array;
+        const heat = this.aHeat.array;
+        const sz = this.aSize.array;
+        for (let i = 0; i < count; i++) {
+            const o = i * 5; // [x, y, z, heat, size]
+            this.projection.toWorld(this.packed[o], this.packed[o + 1], this.packed[o + 2], this.packed[o + 3], this.packed[o + 4], _v);
+            pos[i * 3] = _v.x;
+            pos[i * 3 + 1] = _v.y;
+            pos[i * 3 + 2] = _v.z;
+            heat[i] = this.packed[o + 3];
+            sz[i] = this.packed[o + 4];
+        }
+        this.count = count;
+        this.geometry.setDrawRange(0, count);
+        this.position.needsUpdate = true;
+        this.aHeat.needsUpdate = true;
+        this.aSize.needsUpdate = true;
+        return count;
+    }
+    /** the stride-5 staging buffer (`[x, y, z, heat, size]`) — exposed for tests to fill before `write`. */
+    get staging() {
+        return this.packed;
+    }
+    /** release GPU resources. */
+    dispose() {
+        this.geometry.dispose();
+        this.material.dispose();
+    }
+}
+//# sourceMappingURL=particles.js.map

package/dist/particles.js.map

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

package/dist/project.d.ts

@@ -0,0 +1,111 @@
+/**
+ * `FieldProjection` — the 2D↔3D coordinate seam. The engine integrates in a flat, CSS-pixel field
+ * space (`0..width`, `0..height`); a Three.js scene lives in 3D world units. Every renderer-facing
+ * mapping goes through this one interface so the plane model ships now and a volumetric mode can
+ * slot in later without changing `FieldLayer` or the backend.
+ *
+ * - `PlaneProjection`: the field stands up on a quad — pixels map to world units on a plane; the
+ *   engine's `z` is ignored and `z` is instead lifted from per-particle `heat` for stylistic relief.
+ *   The right choice for a flat (`depth`-less) field.
+ * - `VolumeProjection`: maps the engine's real depth lane (`z ∈ [0, depth)`, the opt-in z axis from
+ *   z-axis.md) onto a world depth range — a genuinely volumetric swarm. Use it when the field was
+ *   created with `depth > 0`.
+ *
+ * Both implement one interface, so `FieldLayer` and `threeBackend` are unchanged by the choice.
+ */
+import { Vector3 } from 'three';
+export interface FieldProjection {
+    /** the engine's field-space size in CSS pixels — feeds `FieldHost.viewport()`. */
+    size(): {
+        width: number;
+        height: number;
+    };
+    /**
+     * field point `(x, y, z)` + per-particle scalars → world position (writes `target` if given).
+     * `z` is the engine's depth lane (always `0` in a flat field); a `PlaneProjection` ignores it.
+     */
+    toWorld(x: number, y: number, z: number, heat: number, size: number, target?: Vector3): Vector3;
+    /** world position → field pixel, for projecting scene objects back onto the field (`z` ignored). */
+    toField(p: Vector3): {
+        x: number;
+        y: number;
+    };
+}
+export interface PlaneProjectionOptions {
+    /** field-space width in CSS pixels (default 1000). */
+    width?: number;
+    /** field-space height in CSS pixels (default 600). */
+    height?: number;
+    /** world units per field pixel (default 0.01 → a 1000px field is 10 world units wide). */
+    scale?: number;
+    /** world-space `z` lift at `heat === 1`; `0` keeps the field perfectly flat (default 0). */
+    relief?: number;
+    /** center the plane on the world origin (default true); when false, `(0,0)` field = origin. */
+    center?: boolean;
+}
+/**
+ * The field on a plane: `(x, y)` field pixels map onto the world XY plane (screen-`y`-down flipped
+ * to world-`y`-up), with `z` lifted from `heat`. Allocation-free on the hot path — pass a reused
+ * `target` Vector3 to `toWorld`.
+ */
+export declare class PlaneProjection implements FieldProjection {
+    readonly width: number;
+    readonly height: number;
+    readonly scale: number;
+    readonly relief: number;
+    readonly center: boolean;
+    constructor(opts?: PlaneProjectionOptions);
+    size(): {
+        width: number;
+        height: number;
+    };
+    toWorld(x: number, y: number, _z: number, heat: number, _size: number, target?: Vector3): Vector3;
+    toField(p: Vector3): {
+        x: number;
+        y: number;
+    };
+}
+export interface VolumeProjectionOptions {
+    /** field-space width in CSS pixels (default 1000). */
+    width?: number;
+    /** field-space height in CSS pixels (default 600). */
+    height?: number;
+    /** world units per field pixel in x/y (default 0.01). */
+    scale?: number;
+    /** the engine `depth` (z-axis.md) this maps — match `FieldOptions.depth` (default 300). */
+    depth?: number;
+    /** world units per unit of engine z; defaults to `scale` (an isotropic volume). */
+    depthScale?: number;
+    /** center the field in x/y on the world origin (default true). */
+    center?: boolean;
+    /** center the volume in z too, so the page plane (`z = 0`) sits at world-z 0 and matter extends
+     *  both ways; when false (default) the plane is at world-z 0 and depth extends toward +z. */
+    centerZ?: boolean;
+}
+/**
+ * The field as a volume: `(x, y)` map onto the world plane exactly as `PlaneProjection`, and the
+ * engine's real depth lane `z ∈ [0, depth)` maps onto a world depth range — a genuinely 3D swarm.
+ * Bodies (DOM elements) stay on the `z = 0` page plane; free matter drifts through the volume and is
+ * pulled gently back toward the plane (the engine's behavior), so the cloud reads as depth + parallax
+ * around the content rather than a slab.
+ */
+export declare class VolumeProjection implements FieldProjection {
+    readonly width: number;
+    readonly height: number;
+    readonly scale: number;
+    readonly depth: number;
+    readonly depthScale: number;
+    readonly center: boolean;
+    readonly centerZ: boolean;
+    constructor(opts?: VolumeProjectionOptions);
+    size(): {
+        width: number;
+        height: number;
+    };
+    toWorld(x: number, y: number, z: number, _heat: number, _size: number, target?: Vector3): Vector3;
+    toField(p: Vector3): {
+        x: number;
+        y: number;
+    };
+}
+//# sourceMappingURL=project.d.ts.map

package/dist/project.d.ts.map

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

package/dist/project.js

@@ -0,0 +1,95 @@
+/**
+ * `FieldProjection` — the 2D↔3D coordinate seam. The engine integrates in a flat, CSS-pixel field
+ * space (`0..width`, `0..height`); a Three.js scene lives in 3D world units. Every renderer-facing
+ * mapping goes through this one interface so the plane model ships now and a volumetric mode can
+ * slot in later without changing `FieldLayer` or the backend.
+ *
+ * - `PlaneProjection`: the field stands up on a quad — pixels map to world units on a plane; the
+ *   engine's `z` is ignored and `z` is instead lifted from per-particle `heat` for stylistic relief.
+ *   The right choice for a flat (`depth`-less) field.
+ * - `VolumeProjection`: maps the engine's real depth lane (`z ∈ [0, depth)`, the opt-in z axis from
+ *   z-axis.md) onto a world depth range — a genuinely volumetric swarm. Use it when the field was
+ *   created with `depth > 0`.
+ *
+ * Both implement one interface, so `FieldLayer` and `threeBackend` are unchanged by the choice.
+ */
+import { Vector3 } from 'three';
+/**
+ * The field on a plane: `(x, y)` field pixels map onto the world XY plane (screen-`y`-down flipped
+ * to world-`y`-up), with `z` lifted from `heat`. Allocation-free on the hot path — pass a reused
+ * `target` Vector3 to `toWorld`.
+ */
+export class PlaneProjection {
+    width;
+    height;
+    scale;
+    relief;
+    center;
+    constructor(opts = {}) {
+        this.width = opts.width ?? 1000;
+        this.height = opts.height ?? 600;
+        this.scale = opts.scale ?? 0.01;
+        this.relief = opts.relief ?? 0;
+        this.center = opts.center ?? true;
+    }
+    size() {
+        return { width: this.width, height: this.height };
+    }
+    toWorld(x, y, _z, heat, _size, target = new Vector3()) {
+        const cx = this.center ? this.width / 2 : 0;
+        const cy = this.center ? this.height / 2 : 0;
+        return target.set((x - cx) * this.scale, (cy - y) * this.scale, // screen-y is down; world-y is up
+        heat * this.relief);
+    }
+    toField(p) {
+        const cx = this.center ? this.width / 2 : 0;
+        const cy = this.center ? this.height / 2 : 0;
+        return {
+            x: p.x / this.scale + cx,
+            y: cy - p.y / this.scale,
+        };
+    }
+}
+/**
+ * The field as a volume: `(x, y)` map onto the world plane exactly as `PlaneProjection`, and the
+ * engine's real depth lane `z ∈ [0, depth)` maps onto a world depth range — a genuinely 3D swarm.
+ * Bodies (DOM elements) stay on the `z = 0` page plane; free matter drifts through the volume and is
+ * pulled gently back toward the plane (the engine's behavior), so the cloud reads as depth + parallax
+ * around the content rather than a slab.
+ */
+export class VolumeProjection {
+    width;
+    height;
+    scale;
+    depth;
+    depthScale;
+    center;
+    centerZ;
+    constructor(opts = {}) {
+        this.width = opts.width ?? 1000;
+        this.height = opts.height ?? 600;
+        this.scale = opts.scale ?? 0.01;
+        this.depth = opts.depth ?? 300;
+        this.depthScale = opts.depthScale ?? this.scale;
+        this.center = opts.center ?? true;
+        this.centerZ = opts.centerZ ?? false;
+    }
+    size() {
+        return { width: this.width, height: this.height };
+    }
+    toWorld(x, y, z, _heat, _size, target = new Vector3()) {
+        const cx = this.center ? this.width / 2 : 0;
+        const cy = this.center ? this.height / 2 : 0;
+        const cz = this.centerZ ? this.depth / 2 : 0;
+        return target.set((x - cx) * this.scale, (cy - y) * this.scale, (z - cz) * this.depthScale);
+    }
+    toField(p) {
+        const cx = this.center ? this.width / 2 : 0;
+        const cy = this.center ? this.height / 2 : 0;
+        return {
+            x: p.x / this.scale + cx,
+            y: cy - p.y / this.scale,
+        };
+    }
+}
+//# sourceMappingURL=project.js.map

package/dist/project.js.map

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

package/dist/samplers.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Native 3D field visuals — the field as geometry, not particles. Because the engine is queryable at
+ * any point (`FieldHandle.sample`), you can build visuals the 2D canvas can't: an instanced arrow
+ * **vector field** and **streamline tubes** that trace the flow through the scene. Both read the live
+ * field each `update()`, mapped through the same `FieldProjection` the swarm and bodies use, so they
+ * register exactly.
+ *
+ * The tracing/sampling core is pure (no WebGL) and unit-tested; only the geometry needs a renderer.
+ */
+import { Group } from 'three';
+import type { FieldProjection } from './project.ts';
+/** Anything with the engine's `sample` — a `FieldLayer`, a `FieldHandle`, or a test stub. */
+export interface FieldSampler {
+    sample(x: number, y: number): {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Trace one streamline from a seed, integrating the field direction. Pure (field-pixel space) —
+ * returns the polyline of points it passes through. Stops at the viewport edge, a stall (near-zero
+ * field), or `maxSteps`.
+ */
+export declare function traceStreamline(field: FieldSampler, seed: {
+    x: number;
+    y: number;
+}, opts: {
+    width: number;
+    height: number;
+    maxSteps?: number;
+    stepLen?: number;
+    minMag?: number;
+}): {
+    x: number;
+    y: number;
+}[];
+export interface VectorFieldOptions {
+    /** the 2D↔3D mapping (share the layer's). */
+    projection: FieldProjection;
+    /** grid spacing in field pixels (default 64). */
+    step?: number;
+    /** longest arrow in world units, at the peak sampled magnitude (default 0.4). */
+    maxLength?: number;
+    /** arrow color (default a field blue). */
+    color?: string;
+    /** world-z the arrows sit at (default 0.02, just off the plane). */
+    z?: number;
+}
+export interface FieldVisual {
+    /** add this to your scene. */
+    readonly object: Group;
+    /** re-sample the live field and refresh the geometry — call when the field changed. */
+    update(): void;
+    /** release GPU resources. */
+    dispose(): void;
+}
+/** An instanced grid of arrows showing the field direction + magnitude across the plane. */
+export declare function vectorField(field: FieldSampler, opts: VectorFieldOptions): FieldVisual;
+export interface StreamlineTubesOptions {
+    /** the 2D↔3D mapping (share the layer's). */
+    projection: FieldProjection;
+    /** seed points in field pixels; omit for an auto grid at `step` spacing. */
+    seeds?: {
+        x: number;
+        y: number;
+    }[];
+    /** auto-seed grid spacing in field pixels when `seeds` is omitted (default 120). */
+    step?: number;
+    /** integration steps per line (default 80) and step length in field px (default 8). */
+    maxSteps?: number;
+    stepLen?: number;
+    /** tube radius in world units (default 0.03). */
+    radius?: number;
+    /** tube color (default a field blue). */
+    color?: string;
+    /** world-z the tubes sit at (default 0.02). */
+    z?: number;
+}
+/** Flow lines traced through the field, rendered as tubes — the field's structure as geometry. */
+export declare function streamlineTubes(field: FieldSampler, opts: StreamlineTubesOptions): FieldVisual;
+//# sourceMappingURL=samplers.d.ts.map

package/dist/samplers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"samplers.d.ts","sourceRoot":"","sources":["../src/samplers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAIL,KAAK,EAQN,MAAM,OAAO,CAAC;AACf,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,6FAA6F;AAC7F,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACxD;AAQD;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EAC9B,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5F;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,CAe5B;AAED,MAAM,WAAW,kBAAkB;IACjC,6CAA6C;IAC7C,UAAU,EAAE,eAAe,CAAC;IAC5B,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,CAAC,CAAC,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,WAAW;IAC1B,8BAA8B;IAC9B,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC;IACvB,uFAAuF;IACvF,MAAM,IAAI,IAAI,CAAC;IACf,6BAA6B;IAC7B,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,4FAA4F;AAC5F,wBAAgB,WAAW,CAAC,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,kBAAkB,GAAG,WAAW,CA6DtF;AAED,MAAM,WAAW,sBAAsB;IACrC,6CAA6C;IAC7C,UAAU,EAAE,eAAe,CAAC;IAC5B,4EAA4E;IAC5E,KAAK,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACnC,oFAAoF;IACpF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uFAAuF;IACvF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,CAAC,CAAC,EAAE,MAAM,CAAC;CACZ;AAED,kGAAkG;AAClG,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,sBAAsB,GAAG,WAAW,CAuC9F"}

package/dist/samplers.js

@@ -0,0 +1,143 @@
+/**
+ * Native 3D field visuals — the field as geometry, not particles. Because the engine is queryable at
+ * any point (`FieldHandle.sample`), you can build visuals the 2D canvas can't: an instanced arrow
+ * **vector field** and **streamline tubes** that trace the flow through the scene. Both read the live
+ * field each `update()`, mapped through the same `FieldProjection` the swarm and bodies use, so they
+ * register exactly.
+ *
+ * The tracing/sampling core is pure (no WebGL) and unit-tested; only the geometry needs a renderer.
+ */
+import { CatmullRomCurve3, Color, ConeGeometry, Group, InstancedMesh, Matrix4, Mesh, MeshBasicMaterial, Quaternion, TubeGeometry, Vector3, } from 'three';
+const _pos = new Vector3();
+const _quat = new Quaternion();
+const _scl = new Vector3();
+const _mat = new Matrix4();
+const _zAxis = new Vector3(0, 0, 1);
+/**
+ * Trace one streamline from a seed, integrating the field direction. Pure (field-pixel space) —
+ * returns the polyline of points it passes through. Stops at the viewport edge, a stall (near-zero
+ * field), or `maxSteps`.
+ */
+export function traceStreamline(field, seed, opts) {
+    const { width, height, maxSteps = 80, stepLen = 8, minMag = 1e-6 } = opts;
+    const pts = [{ x: seed.x, y: seed.y }];
+    let x = seed.x;
+    let y = seed.y;
+    for (let i = 0; i < maxSteps; i++) {
+        const v = field.sample(x, y);
+        const m = Math.hypot(v.x, v.y);
+        if (m < minMag)
+            break;
+        x += (v.x / m) * stepLen;
+        y += (v.y / m) * stepLen;
+        if (x < 0 || y < 0 || x > width || y > height)
+            break;
+        pts.push({ x, y });
+    }
+    return pts;
+}
+/** An instanced grid of arrows showing the field direction + magnitude across the plane. */
+export function vectorField(field, opts) {
+    const { projection, step = 64, maxLength = 0.4, color = '#7cc0ff', z = 0.02 } = opts;
+    const { width, height } = projection.size();
+    const cols = Math.max(1, Math.floor(width / step));
+    const rows = Math.max(1, Math.floor(height / step));
+    const count = cols * rows;
+    // a cone pointing +X (so a Z-rotation aims it along the in-plane force direction)
+    const geo = new ConeGeometry(0.16, 1, 6);
+    geo.rotateZ(-Math.PI / 2);
+    geo.translate(0.5, 0, 0);
+    const material = new MeshBasicMaterial({ color: new Color(color), transparent: true, opacity: 0.85 });
+    const mesh = new InstancedMesh(geo, material, count);
+    mesh.frustumCulled = false;
+    const group = new Group();
+    group.add(mesh);
+    const update = () => {
+        let max = 1e-6;
+        const fx = [];
+        const fy = [];
+        const vx = [];
+        const vy = [];
+        for (let r = 0; r < rows; r++) {
+            for (let c = 0; c < cols; c++) {
+                const px = (c + 0.5) * step;
+                const py = (r + 0.5) * step;
+                const v = field.sample(px, py);
+                const m = Math.hypot(v.x, v.y);
+                if (m > max)
+                    max = m;
+                fx.push(px);
+                fy.push(py);
+                vx.push(v.x);
+                vy.push(v.y);
+            }
+        }
+        for (let i = 0; i < count; i++) {
+            projection.toWorld(fx[i], fy[i], 0, 0, 0, _pos);
+            _pos.z = z;
+            const rel = Math.sqrt(Math.hypot(vx[i], vy[i]) / max); // sqrt compression so weak arrows read
+            // field-y is down → world-y up, so the world direction is (vx, -vy)
+            const angle = Math.atan2(-vy[i], vx[i]);
+            _quat.setFromAxisAngle(_zAxis, angle);
+            const len = Math.max(0.0001, rel * maxLength);
+            _scl.set(len, len, len);
+            _mat.compose(_pos, _quat, _scl);
+            mesh.setMatrixAt(i, _mat);
+        }
+        mesh.instanceMatrix.needsUpdate = true;
+    };
+    update();
+    return {
+        object: group,
+        update,
+        dispose: () => {
+            geo.dispose();
+            material.dispose();
+        },
+    };
+}
+/** Flow lines traced through the field, rendered as tubes — the field's structure as geometry. */
+export function streamlineTubes(field, opts) {
+    const { projection, step = 120, maxSteps = 80, stepLen = 8, radius = 0.03, color = '#9fd4ff', z = 0.02 } = opts;
+    const { width, height } = projection.size();
+    const material = new MeshBasicMaterial({ color: new Color(color), transparent: true, opacity: 0.7 });
+    const group = new Group();
+    const seedPoints = () => {
+        if (opts.seeds)
+            return opts.seeds;
+        const out = [];
+        for (let y = step / 2; y < height; y += step)
+            for (let x = step / 2; x < width; x += step)
+                out.push({ x, y });
+        return out;
+    };
+    const update = () => {
+        for (const child of group.children)
+            child.geometry.dispose();
+        group.clear();
+        for (const seed of seedPoints()) {
+            const pts = traceStreamline(field, seed, { width, height, maxSteps, stepLen });
+            if (pts.length < 2)
+                continue;
+            const path = pts.map((p) => {
+                const w = projection.toWorld(p.x, p.y, 0, 0, 0, new Vector3());
+                w.z = z;
+                return w;
+            });
+            const tube = new TubeGeometry(new CatmullRomCurve3(path), Math.max(1, path.length - 1), radius, 6, false);
+            group.add(new Mesh(tube, material));
+        }
+    };
+    update();
+    return {
+        object: group,
+        update,
+        dispose: () => {
+            for (const child of group.children)
+                child.geometry.dispose();
+            group.clear();
+            material.dispose();
+        },
+    };
+}
+//# sourceMappingURL=samplers.js.map