@fundamental-engine/core 0.7.0 → 0.9.0

package/dist/core/frame-harness.d.ts.map

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

package/dist/core/frame-harness.js

@@ -0,0 +1,300 @@
+/**
+ * frameHarness — a DOM-free, frame-driving test harness for the element-consumer paths in
+ * `field.ts` (§22.3 element capture / relocate / emit, §22.5 capture/release events).
+ *
+ * `headlessHost` exists for the *signals-first* consumer (an agent reading the field via `addBody`
+ * + `onFeedback`): its scan root is empty by design, so the `[data-move]`/`[data-dock]`/`[data-warp]`/
+ * `[data-emit]` element machinery in the frame loop is never exercised. PR #260 wired all of that —
+ * movers drifting, a `[data-dock]` element collapsing into a sink, warp teleport, element emit, and
+ * the `field:captured` / `field:released` / `field:relocated` dispatch — and it has stayed untested
+ * because the only `createField` stub (`packages/vanilla/src/field.test.ts`) hands back a `raf` that
+ * never fires and a `querySelectorAll` that returns `[]`, so the loop never runs.
+ *
+ * This harness closes that gap WITHOUT a DOM or a test framework (the repo forbids jsdom). It is a
+ * hand-rolled element graph — each {@link HarnessElement} answers exactly the surface the engine
+ * reads (`getBoundingClientRect`, `dataset`, `getAttribute`/`hasAttribute`/`setAttribute`/
+ * `removeAttribute`, `style`, `dispatchEvent`, `isConnected`, `cloneNode`/`appendChild`/`remove`) —
+ * plus a {@link FrameHarnessHost} whose `root.querySelectorAll` returns the live element list and
+ * whose loop is **manual**: the engine re-schedules a frame each `raf`, and {@link FrameHarness.step}
+ * fires them on a deterministic `dt`. Pair it with a seeded `rng` for a fully reproducible run.
+ *
+ * ```ts
+ * const h = frameHarness({ width: 800, height: 600 });
+ * const sink = h.add({ attrs: { 'data-body': 'sink', 'data-absorb': '900', 'data-max': '1' },
+ *                      rect: { left: 400, top: 300, width: 40, height: 40 } });
+ * const dock = h.add({ attrs: { 'data-move': '', 'data-dock': '' },
+ *                      rect: { left: 410, top: 310, width: 20, height: 20 } });
+ * const field = createField(h.canvas, { host: h.host, render: 'none', waves: false, rng: seededRng() });
+ * field.scan();
+ * h.step();                                // drive one frame — the dock element captures
+ * dock.events.includes('field:captured');  // true
+ * ```
+ */
+import { createField } from "./field.js";
+const ZERO_RECT = { left: 0, top: 0, width: 0, height: 0 };
+/**
+ * One element in the harness scan root — a hand-rolled stand-in answering the exact surface the
+ * engine reads off a DOM element. The fields the frame loop mutates (transforms via `style`, a11y
+ * via `aria-hidden`/`inert`, the `data-fx-cap` edge flag) are observable so tests can assert them,
+ * and every `field:*` / `forces:*` event the engine dispatches is recorded in {@link events}.
+ */
+export class HarnessElement {
+    /** mutable layout box; the engine reads it through `getBoundingClientRect`. Move it to relocate. */
+    rect;
+    tagName;
+    id;
+    className = '';
+    isConnected = true;
+    /** every `dispatchEvent`'d event type, in order (e.g. `'field:captured'`, `'forces:captured'`). */
+    events = [];
+    /** every dispatched event with its detail, in order — for asserting the payload. */
+    dispatched = [];
+    dataset = {};
+    /** the writable style surface the engine writes transforms / opacity through. Index it by name
+     *  (e.g. `el.style.transform`, `el.style.opacity`) or via setProperty/getPropertyValue. */
+    style;
+    /** clones appended by element-emit (§22.3) live here (children), so a test can count them. */
+    children = [];
+    attrs;
+    props = {};
+    constructor(spec = {}) {
+        this.attrs = { ...(spec.attrs ?? {}) };
+        this.rect = spec.rect ? { ...spec.rect } : { ...ZERO_RECT };
+        this.tagName = (spec.tag ?? 'DIV').toUpperCase();
+        // `id` may be supplied directly OR as an `id` attribute (so emit templates `{ attrs: { id } }`
+        // resolve through the same `#id` selector path the engine uses); the field is the source of truth.
+        this.id = spec.id ?? this.attrs.id ?? '';
+        delete this.attrs.id;
+        // mirror `data-*` attributes into dataset (camelCased), the way the DOM does — the engine reads
+        // dockable/warpable through hasAttribute but layout/emit/max/active through `dataset`.
+        for (const [k, v] of Object.entries(this.attrs)) {
+            if (k.startsWith('data-'))
+                this.dataset[dashToCamel(k.slice(5))] = v;
+        }
+        const props = this.props;
+        const styleApi = {
+            setProperty(k, v) {
+                props[k] = v;
+            },
+            removeProperty(k) {
+                delete props[k];
+            },
+            getPropertyValue(k) {
+                return props[k] ?? '';
+            },
+        };
+        this.style = new Proxy(styleApi, {
+            get(target, key) {
+                if (key in target)
+                    return target[key];
+                return props[key] ?? '';
+            },
+            set(_t, key, value) {
+                props[key] = value;
+                return true;
+            },
+        });
+    }
+    getBoundingClientRect() {
+        const r = this.rect;
+        return {
+            left: r.left,
+            top: r.top,
+            right: r.left + r.width,
+            bottom: r.top + r.height,
+            width: r.width,
+            height: r.height,
+            x: r.left,
+            y: r.top,
+            toJSON: () => ({}),
+        };
+    }
+    getAttribute(name) {
+        if (name === 'aria-hidden' || name === 'inert')
+            return this.props[name] ?? null;
+        if (name === 'id')
+            return this.id || null;
+        return this.attrs[name] ?? null;
+    }
+    hasAttribute(name) {
+        if (name === 'aria-hidden' || name === 'inert')
+            return name in this.props;
+        if (name === 'id')
+            return this.id !== '';
+        return name in this.attrs;
+    }
+    setAttribute(name, value) {
+        if (name === 'aria-hidden' || name === 'inert') {
+            this.props[name] = value;
+        }
+        else if (name === 'id') {
+            this.id = value;
+        }
+        else {
+            this.attrs[name] = value;
+            if (name.startsWith('data-'))
+                this.dataset[dashToCamel(name.slice(5))] = value;
+        }
+    }
+    removeAttribute(name) {
+        if (name === 'aria-hidden' || name === 'inert') {
+            delete this.props[name];
+            return;
+        }
+        if (name === 'id') {
+            this.id = ''; // element-emit strips the clone's id (no duplicate ids, §22.3)
+            return;
+        }
+        delete this.attrs[name];
+        if (name.startsWith('data-'))
+            delete this.dataset[dashToCamel(name.slice(5))];
+    }
+    dispatchEvent(e) {
+        this.events.push(e.type);
+        this.dispatched.push({ type: e.type, detail: e.detail });
+        return true;
+    }
+    appendChild(child) {
+        this.children.push(child);
+        child.isConnected = true;
+        return child;
+    }
+    remove() {
+        this.isConnected = false;
+    }
+    cloneNode(_deep) {
+        // a deep clone carries the id too (the engine then strips it via removeAttribute('id')).
+        return new HarnessElement({ attrs: { ...this.attrs }, rect: { ...this.rect }, tag: this.tagName, id: this.id });
+    }
+}
+function dashToCamel(s) {
+    return s.replace(/-([a-z])/g, (_m, c) => c.toUpperCase());
+}
+/**
+ * Build a frame-driving harness. The returned {@link FrameHarness.host} drives the REAL `field.ts`
+ * frame loop manually — `createField` schedules a frame through `raf`, and {@link FrameHarness.step}
+ * fires it on a deterministic `dt`. Register elements with {@link FrameHarness.add}, call the field's
+ * `scan()` to pick them up, then `step()` to advance frames and assert on `element.events`,
+ * `element.style`, and `element.dataset`.
+ */
+export function frameHarness(opts = {}) {
+    const W = opts.width ?? 800;
+    const H = opts.height ?? 600;
+    const elements = [];
+    let frame = null;
+    let t = 0;
+    const noop = () => { };
+    const off = () => noop;
+    const matchesClause = (el, clause) => {
+        // the four selector shapes the engine actually issues: a bare attribute (`[data-move]`), an
+        // attribute-value (the warp `data-pair` selector, e.g. `[data-body="anchor"]`), an id (an emit
+        // template, `#spark`), and a class. Anything fancier is out of scope (the engine never uses it).
+        const attrVal = /^\[([a-z-]+)=["']?([^"'\]]*)["']?\]$/.exec(clause);
+        if (attrVal)
+            return el.getAttribute(attrVal[1]) === attrVal[2];
+        const attr = /^\[([a-z-]+)\]$/.exec(clause);
+        if (attr)
+            return el.hasAttribute(attr[1]);
+        if (clause.startsWith('#'))
+            return el.id === clause.slice(1);
+        if (clause.startsWith('.'))
+            return el.className.split(/\s+/).includes(clause.slice(1));
+        return false;
+    };
+    const matches = (el, selector) => selector
+        .split(',')
+        .map((s) => s.trim())
+        .some((clause) => matchesClause(el, clause));
+    const root = {
+        querySelectorAll: (selector) => elements.filter((el) => el.isConnected && matches(el, selector)),
+        querySelector: (selector) => elements.find((el) => el.isConnected && matches(el, selector)) ?? null,
+        contains: (node) => elements.includes(node),
+    };
+    const host = {
+        root,
+        viewport: () => ({ width: W, height: H, dpr: 1 }),
+        scrollY: () => 0,
+        scrollHeight: () => H,
+        reducedMotion: () => false,
+        hidden: () => false,
+        raf: (cb) => {
+            frame = cb;
+            return 1;
+        },
+        cancelRaf: () => {
+            frame = null;
+        },
+        // the harness runs with render:'none', so the heatmap-buffer canvas is never requested; throw a
+        // clear message if a test asks for a drawing mode (it'd need a real canvas anyway).
+        createCanvas: () => {
+            throw new Error("frameHarness does not render — create the field with render:'none'.");
+        },
+        onResize: off,
+        onScroll: off,
+        onVisibility: off,
+        onInput: off,
+        onBodyEvent: off,
+        tick(dt) {
+            t += dt;
+            const cb = frame;
+            frame = null;
+            cb?.(t);
+        },
+    };
+    // a throwaway canvas — never drawn to under render:'none', but createField's signature wants one.
+    const canvas = {
+        width: 0,
+        height: 0,
+        style: {},
+        setAttribute: noop,
+        getContext: () => null,
+    };
+    return {
+        host,
+        canvas,
+        elements,
+        add(spec) {
+            const el = new HarnessElement(spec);
+            elements.push(el);
+            return el;
+        },
+        remove(el) {
+            el.isConnected = false;
+            const i = elements.indexOf(el);
+            if (i >= 0)
+                elements.splice(i, 1);
+        },
+        step(n = 1) {
+            for (let i = 0; i < n; i++)
+                host.tick(16);
+        },
+    };
+}
+/**
+ * Convenience: build a harness AND a field on it in one call, with the signals-first defaults the
+ * harness needs (`render: 'none'`, `waves: false`). Returns both so a test drives `field.scan()` /
+ * `harness.step()` and asserts on `harness.elements`.
+ */
+export function frameHarnessField(opts = {}) {
+    const { width, height, ...fieldOpts } = opts;
+    const harness = frameHarness({ width, height });
+    const field = createField(harness.canvas, {
+        host: harness.host,
+        render: 'none',
+        waves: false,
+        ...fieldOpts,
+    });
+    return { harness, field };
+}
+/** A tiny deterministic PRNG (mulberry32) for reproducible harness runs — pass as `rng`. */
+export function seededRng(seed = 1) {
+    let a = seed >>> 0;
+    return () => {
+        a |= 0;
+        a = (a + 0x6d2b79f5) | 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+//# sourceMappingURL=frame-harness.js.map

package/dist/core/frame-harness.js.map

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

package/dist/core/host-headless.d.ts

@@ -0,0 +1,35 @@
+/**
+ * headlessHost — the reference {@link FieldHost} for non-DOM, non-visual consumers: an agent reading
+ * the field as a salience substrate, a native sidecar, a Node service, or a deterministic test. Where
+ * `browserHost()` binds the engine to `window`/`document`/rAF, `headlessHost()` binds it to nothing —
+ * an abstract volume the caller sets, a no-op scan root (bodies come via `addBody`, not `[data-body]`),
+ * and a **manual** loop the caller drives with `tick()` instead of requestAnimationFrame.
+ *
+ * Pair it with `render: 'none'` (signals-first): the field runs the full simulation + writes its
+ * signals and draws nothing. Read them back per-body through `addBody`'s `onFeedback`, or globally via
+ * `sampleScalar` / `readParticles`. No DOM is touched (`host-headless.ts` references only the DOM
+ * *types* already in `host.ts`, no globals — `dom-boundary.test.ts` stays green).
+ *
+ * ```ts
+ * const host = headlessHost({ width: 1920, height: 1080 });
+ * const field = createField(undefined, { host, render: 'none' });
+ * field.addBody({ tokens: ['attract'], rect: () => box, onFeedback: (ch) => read(ch.density) });
+ * host.tick(); // advance one frame — call per agent turn or on a schedule
+ * ```
+ */
+import type { FieldHost } from './host.ts';
+export interface HeadlessHostOptions {
+    /** the field's coordinate-space width (the abstract "volume"). */
+    width: number;
+    /** the field's coordinate-space height. */
+    height: number;
+}
+/** A {@link FieldHost} the caller drives manually — see {@link headlessHost}. */
+export interface HeadlessHost extends FieldHost {
+    /** Advance the field one frame. Pass an explicit timestamp (ms), or omit to auto-step ~1/60 s. */
+    tick(t?: number): void;
+    /** Resize the abstract volume (the field's coordinate space). */
+    resize(width: number, height: number): void;
+}
+export declare function headlessHost(opts: HeadlessHostOptions): HeadlessHost;
+//# sourceMappingURL=host-headless.d.ts.map

package/dist/core/host-headless.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-headless.d.ts","sourceRoot":"","sources":["../../src/core/host-headless.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAgB,MAAM,WAAW,CAAC;AAEzD,MAAM,WAAW,mBAAmB;IAClC,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,iFAAiF;AACjF,MAAM,WAAW,YAAa,SAAQ,SAAS;IAC7C,kGAAkG;IAClG,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,iEAAiE;IACjE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7C;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,YAAY,CAiDpE"}

package/dist/core/host-headless.js

@@ -0,0 +1,47 @@
+export function headlessHost(opts) {
+    let w = opts.width;
+    let h = opts.height;
+    let frame = null;
+    let t = 0;
+    // a no-op scan root — a headless field has no `[data-body]` DOM; bodies are registered via addBody.
+    const root = {
+        querySelectorAll: () => [],
+        querySelector: () => null,
+        contains: () => false,
+    };
+    return {
+        root,
+        viewport: () => ({ width: w, height: h, dpr: 1 }),
+        scrollY: () => 0,
+        scrollHeight: () => h,
+        reducedMotion: () => false,
+        hidden: () => false,
+        // the loop is manual: raf stashes the next frame, tick() fires it. The consumer owns the cadence.
+        raf: (cb) => {
+            frame = cb;
+            return 1;
+        },
+        cancelRaf: () => {
+            frame = null;
+        },
+        createCanvas: () => {
+            throw new Error("headlessHost does not render — use render:'none' and the signal read-outs (onFeedback / sampleScalar / readParticles).");
+        },
+        onResize: () => () => { },
+        onScroll: () => () => { },
+        onVisibility: () => () => { },
+        onInput: () => () => { },
+        onBodyEvent: () => () => { },
+        tick(at) {
+            t = at ?? t + 1000 / 60;
+            const cb = frame;
+            frame = null;
+            cb?.(t);
+        },
+        resize(width, height) {
+            w = width;
+            h = height;
+        },
+    };
+}
+//# sourceMappingURL=host-headless.js.map

package/dist/core/host-headless.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-headless.js","sourceRoot":"","sources":["../../src/core/host-headless.ts"],"names":[],"mappings":"AAoCA,MAAM,UAAU,YAAY,CAAC,IAAyB;IACpD,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC;IACnB,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;IACpB,IAAI,KAAK,GAAiC,IAAI,CAAC;IAC/C,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,oGAAoG;IACpG,MAAM,IAAI,GAAG;QACX,gBAAgB,EAAE,GAAG,EAAE,CAAC,EAAoC;QAC5D,aAAa,EAAE,GAAG,EAAE,CAAC,IAAI;QACzB,QAAQ,EAAE,GAAG,EAAE,CAAC,KAAK;KACG,CAAC;IAE3B,OAAO;QACL,IAAI;QACJ,QAAQ,EAAE,GAAiB,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC;QAC/D,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC;QAChB,YAAY,EAAE,GAAG,EAAE,CAAC,CAAC;QACrB,aAAa,EAAE,GAAG,EAAE,CAAC,KAAK;QAC1B,MAAM,EAAE,GAAG,EAAE,CAAC,KAAK;QACnB,kGAAkG;QAClG,GAAG,EAAE,CAAC,EAAE,EAAE,EAAE;YACV,KAAK,GAAG,EAAE,CAAC;YACX,OAAO,CAAC,CAAC;QACX,CAAC;QACD,SAAS,EAAE,GAAG,EAAE;YACd,KAAK,GAAG,IAAI,CAAC;QACf,CAAC;QACD,YAAY,EAAE,GAAG,EAAE;YACjB,MAAM,IAAI,KAAK,CACb,wHAAwH,CACzH,CAAC;QACJ,CAAC;QACD,QAAQ,EAAE,GAAG,EAAE,CAAC,GAAG,EAAE,GAAE,CAAC;QACxB,QAAQ,EAAE,GAAG,EAAE,CAAC,GAAG,EAAE,GAAE,CAAC;QACxB,YAAY,EAAE,GAAG,EAAE,CAAC,GAAG,EAAE,GAAE,CAAC;QAC5B,OAAO,EAAE,GAAG,EAAE,CAAC,GAAG,EAAE,GAAE,CAAC;QACvB,WAAW,EAAE,GAAG,EAAE,CAAC,GAAG,EAAE,GAAE,CAAC;QAE3B,IAAI,CAAC,EAAE;YACL,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,IAAI,GAAG,EAAE,CAAC;YACxB,MAAM,EAAE,GAAG,KAAK,CAAC;YACjB,KAAK,GAAG,IAAI,CAAC;YACb,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;QACV,CAAC;QACD,MAAM,CAAC,KAAK,EAAE,MAAM;YAClB,CAAC,GAAG,KAAK,CAAC;YACV,CAAC,GAAG,MAAM,CAAC;QACb,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/core/host.d.ts

@@ -12,6 +12,13 @@ export interface HostViewport {
     width: number;
     height: number;
     dpr: number;
+    /** field-space origin in the host's measurement coords — the top-left the field is drawn from.
+     *  `0,0` for a window-scoped host (the default); a CONTAINED host (`containerHost`) returns its
+     *  element's `left,top` so the field, its bodies, and its canvas all live in container-local space.
+     *  `measureBodies` and the thread/move readouts subtract it. Optional → 0 keeps every window host
+     *  and test byte-identical. */
+    originX?: number;
+    originY?: number;
 }
 export interface FieldHost {
     /** the subtree scanned for `[data-body]` / `[data-move]` / `[data-on]` / `[data-hot]` / `[data-formation]`. */

package/dist/core/host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/core/host.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,sEAAsE;AACtE,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,SAAS;IACxB,+GAA+G;IAC/G,IAAI,EAAE,UAAU,CAAC;IACjB,0DAA0D;IAC1D,QAAQ,IAAI,YAAY,CAAC;IACzB,4CAA4C;IAC5C,OAAO,IAAI,MAAM,CAAC;IAClB,2FAA2F;IAC3F,YAAY,IAAI,MAAM,CAAC;IACvB,iEAAiE;IACjE,aAAa,IAAI,OAAO,CAAC;IACzB,0EAA0E;IAC1E,MAAM,IAAI,OAAO,CAAC;IAClB,iDAAiD;IACjD,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,CAAC;IACrC,gCAAgC;IAChC,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,kDAAkD;IAClD,YAAY,IAAI,iBAAiB,CAAC;IAClC,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IACrC,mDAAmD;IACnD,QAAQ,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IACrC,uEAAuE;IACvE,YAAY,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IACzC,0FAA0F;IAC1F,OAAO,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IACpC,qFAAqF;IACrF,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAC/D"}
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/core/host.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,sEAAsE;AACtE,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ;;;;mCAI+B;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,SAAS;IACxB,+GAA+G;IAC/G,IAAI,EAAE,UAAU,CAAC;IACjB,0DAA0D;IAC1D,QAAQ,IAAI,YAAY,CAAC;IACzB,4CAA4C;IAC5C,OAAO,IAAI,MAAM,CAAC;IAClB,2FAA2F;IAC3F,YAAY,IAAI,MAAM,CAAC;IACvB,iEAAiE;IACjE,aAAa,IAAI,OAAO,CAAC;IACzB,0EAA0E;IAC1E,MAAM,IAAI,OAAO,CAAC;IAClB,iDAAiD;IACjD,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,CAAC;IACrC,gCAAgC;IAChC,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,kDAAkD;IAClD,YAAY,IAAI,iBAAiB,CAAC;IAClC,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IACrC,mDAAmD;IACnD,QAAQ,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IACrC,uEAAuE;IACvE,YAAY,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IACzC,0FAA0F;IAC1F,OAAO,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IACpC,qFAAqF;IACrF,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAC/D"}

package/dist/core/integrator.d.ts

@@ -19,6 +19,12 @@ export interface StepInput {
     conditions: ConditionRegistry;
     /** the carrier waves — free particles drift along their slope (§2.3). */
     waves?: readonly Wave[];
+    waveStyle?: 'linear' | 'circular';
+    waveCenter?: {
+        x: number;
+        y: number;
+    } | null;
+    separation?: number;
 }
 export declare function step(input: StepInput): void;
 //# sourceMappingURL=integrator.d.ts.map

package/dist/core/integrator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"integrator.d.ts","sourceRoot":"","sources":["../../src/core/integrator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,iBAAiB,EAAE,GAAG,EAAS,aAAa,EAAY,MAAM,YAAY,CAAC;AAC/F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,EAAsB,KAAK,IAAI,EAAE,MAAM,eAAe,CAAC;AAK9D,eAAO,MAAM,QAAQ,OAAO,CAAC;AAC7B,eAAO,MAAM,UAAU,QAAQ,CAAC;AAGhC,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,UAAU,CAAC;IAClB,MAAM,EAAE,SAAS,IAAI,EAAE,CAAC;IACxB,GAAG,EAAE,GAAG,CAAC;IACT,MAAM,EAAE,aAAa,CAAC;IACtB,UAAU,EAAE,iBAAiB,CAAC;IAC9B,yEAAyE;IACzE,KAAK,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;CACzB;AA2CD,wBAAgB,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAgV3C"}
+{"version":3,"file":"integrator.d.ts","sourceRoot":"","sources":["../../src/core/integrator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,iBAAiB,EAAE,GAAG,EAAS,aAAa,EAAY,MAAM,YAAY,CAAC;AAC/F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,EAAoC,KAAK,IAAI,EAAE,MAAM,eAAe,CAAC;AAK5E,eAAO,MAAM,QAAQ,OAAO,CAAC;AAC7B,eAAO,MAAM,UAAU,QAAQ,CAAC;AAGhC,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,UAAU,CAAC;IAClB,MAAM,EAAE,SAAS,IAAI,EAAE,CAAC;IACxB,GAAG,EAAE,GAAG,CAAC;IACT,MAAM,EAAE,aAAa,CAAC;IACtB,UAAU,EAAE,iBAAiB,CAAC;IAC9B,yEAAyE;IACzE,KAAK,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;IACxB,SAAS,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAC;IAClC,UAAU,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA2CD,wBAAgB,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAkY3C"}

package/dist/core/integrator.js

@@ -7,7 +7,7 @@
  * untouched. Reduced motion (`dt = 0`) freezes the sim (§18).
  */
 import { accretionTarget } from "./formations.js";
-import { waveYat, waveSlope } from "./currents.js";
+import { waveYat, waveSlope, waveDistance } from "./currents.js";
 import { netField } from "./streamlines.js";
 import { screenFactor } from "./math.js";
 import { classifyBodyTokens } from "../config/forces.config.js";
@@ -55,7 +55,7 @@ function applyForce(f, b, p, env, inv) {
         p.vz = bvz + (p.vz - bvz) * inv;
 }
 export function step(input) {
-    const { store, bodies, env, forces, conditions, waves } = input;
+    const { store, bodies, env, forces, conditions, waves, separation } = input;
     const dt = env.dt;
     if (dt === 0)
         return;
@@ -112,18 +112,51 @@ export function step(input) {
         const pz = p.z;
         // wave current (§2.3): near a wave line, drift along its slope like debris.
         if (hasWaves) {
-            let near = null;
-            let nd = 1e9;
-            for (const w of waves) {
-                const d = Math.abs(waveYat(w, p.x, env.t, H) - p.y);
-                if (d < nd) {
-                    nd = d;
-                    near = w;
+            if (input.waveStyle === 'circular') {
+                let near = null;
+                let nd = 1e9;
+                let nearR = 0;
+                let nearRWave = 0;
+                let nearTheta = 0;
+                const c = input.waveCenter || { x: W / 2, y: H / 2 };
+                for (const w of waves) {
+                    const res = waveDistance(w, p.x, p.y, env.t, W, H, 'circular', c);
+                    if (res.dist < nd) {
+                        nd = res.dist;
+                        near = w;
+                        nearR = res.r;
+                        nearRWave = res.rWave;
+                        nearTheta = res.theta;
+                    }
+                }
+                if (near && nd < 70) {
+                    const factor = 1 - nd / 70;
+                    // Tangential drift
+                    const tx = -Math.sin(nearTheta) * near.dir;
+                    const ty = Math.cos(nearTheta) * near.dir;
+                    p.vx += tx * 0.035 * factor;
+                    p.vy += ty * 0.035 * factor;
+                    // Radial pull towards the wave radius
+                    const rx = Math.cos(nearTheta) * Math.sign(nearRWave - nearR);
+                    const ry = Math.sin(nearTheta) * Math.sign(nearRWave - nearR);
+                    p.vx += rx * 0.05 * factor;
+                    p.vy += ry * 0.05 * factor;
                 }
             }
-            if (near && nd < 70) {
-                p.vx += near.dir * 0.035 * (1 - nd / 70);
-                p.vy += waveSlope(near, p.x, env.t) * 0.1 * (1 - nd / 70);
+            else {
+                let near = null;
+                let nd = 1e9;
+                for (const w of waves) {
+                    const d = Math.abs(waveYat(w, p.x, env.t, H) - p.y);
+                    if (d < nd) {
+                        nd = d;
+                        near = w;
+                    }
+                }
+                if (near && nd < 70) {
+                    p.vx += near.dir * 0.035 * (1 - nd / 70);
+                    p.vy += waveSlope(near, p.x, env.t) * 0.1 * (1 - nd / 70);
+                }
             }
         }
         // formation currents (§7), before the body forces: a lateral lane, an
@@ -302,6 +335,23 @@ export function step(input) {
                 }
             }
         }
+        // short-range particle-to-particle separation to prevent clumping
+        if (separation && separation > 0) {
+            const ns = env.neighbors(p, 12);
+            for (const n of ns) {
+                const dx = p.x - n.x;
+                const dy = p.y - n.y;
+                const dz = (p.z ?? 0) - (n.z ?? 0);
+                const dist = Math.hypot(dx, dy, dz) || 0.1;
+                if (dist < 12) {
+                    const force = ((12 - dist) / 12) * separation * 0.12;
+                    p.vx += (dx / dist) * force;
+                    p.vy += (dy / dist) * force;
+                    if (p.vz !== undefined)
+                        p.vz += (dz / dist) * force;
+                }
+            }
+        }
         // global safety cap (§20.10): no token or composite may drive a free particle past
         // c (the unit system's "speed of light"). The natural primitives self-clamp; this
         // enforces it for *every* force. A non-finite velocity slips the `> c²` test — the