@fundamental-engine/elements 0.5.1

package/dist/base.d.ts

@@ -0,0 +1,9 @@
+/**
+ * SSR-safe `HTMLElement` base. In the browser it is the real `HTMLElement`; under Node — an SSR
+ * pass, a build step, or the dist smoke check — it is an inert stand-in, so merely *importing*
+ * the package never throws `HTMLElement is not defined`. The elements only do anything once a
+ * browser upgrades them (every `customElements.define` is guarded too), so the stand-in is never
+ * constructed.
+ */
+export declare const HTMLElementBase: typeof HTMLElement;
+//# sourceMappingURL=base.d.ts.map

package/dist/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../src/base.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,EAAE,OAAO,WAGY,CAAC"}

package/dist/base.js

@@ -0,0 +1,12 @@
+/**
+ * SSR-safe `HTMLElement` base. In the browser it is the real `HTMLElement`; under Node — an SSR
+ * pass, a build step, or the dist smoke check — it is an inert stand-in, so merely *importing*
+ * the package never throws `HTMLElement is not defined`. The elements only do anything once a
+ * browser upgrades them (every `customElements.define` is guarded too), so the stand-in is never
+ * constructed.
+ */
+export const HTMLElementBase = typeof HTMLElement !== 'undefined'
+    ? HTMLElement
+    : class {
+    };
+//# sourceMappingURL=base.js.map

package/dist/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../src/base.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,eAAe,GAC1B,OAAO,WAAW,KAAK,WAAW;IAChC,CAAC,CAAC,WAAW;IACb,CAAC,CAAE;KAA0C,CAAC"}

package/dist/cell-force.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The Field Cell's in-frame force math (§25.1) — a deliberately simplified,
+ * centre-of-frame model for demos. NOT the canonical force math (§6); the cell is
+ * a poster engine. `dx,dy` point from the particle TO the frame centre.
+ */
+export declare function cellForce(force: string, dx: number, dy: number, reach: number): {
+    ax: number;
+    ay: number;
+};
+//# sourceMappingURL=cell-force.d.ts.map

package/dist/cell-force.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cell-force.d.ts","sourceRoot":"","sources":["../src/cell-force.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,MAAM,GACZ;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CA8B5B"}

package/dist/cell-force.js

@@ -0,0 +1,38 @@
+/**
+ * The Field Cell's in-frame force math (§25.1) — a deliberately simplified,
+ * centre-of-frame model for demos. NOT the canonical force math (§6); the cell is
+ * a poster engine. `dx,dy` point from the particle TO the frame centre.
+ */
+export function cellForce(force, dx, dy, reach) {
+    const d = Math.hypot(dx, dy) || 1;
+    // stream and buoyancy are uniform fields — not distance-gated.
+    const uniform = force === 'stream' || force === 'buoyancy';
+    if (!uniform && d >= reach)
+        return { ax: 0, ay: 0 };
+    const ux = dx / d;
+    const uy = dy / d;
+    const f = (1 - Math.min(d, reach) / reach) * 0.4;
+    switch (force) {
+        case 'repel':
+            return { ax: -ux * f, ay: -uy * f };
+        case 'swirl':
+            return { ax: -uy * f, ay: ux * f };
+        case 'stream':
+            return { ax: 0.12, ay: 0 };
+        case 'buoyancy':
+            return { ax: 0, ay: -0.12 }; // a steady lift (−y is up)
+        case 'gravity': {
+            const g = Math.min(0.8, ((reach * reach) / (d * d)) * 0.02); // true-ish 1/d²
+            return { ax: ux * g, ay: uy * g };
+        }
+        case 'tether': {
+            const rest = reach * 0.45;
+            const s = (d - rest) * 0.025; // pull in past the shell, push out within it
+            return { ax: ux * s, ay: uy * s };
+        }
+        case 'attract':
+        default:
+            return { ax: ux * f, ay: uy * f };
+    }
+}
+//# sourceMappingURL=cell-force.js.map

package/dist/cell-force.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cell-force.js","sourceRoot":"","sources":["../src/cell-force.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,UAAU,SAAS,CACvB,KAAa,EACb,EAAU,EACV,EAAU,EACV,KAAa;IAEb,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;IAClC,+DAA+D;IAC/D,MAAM,OAAO,GAAG,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,UAAU,CAAC;IAC3D,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,KAAK;QAAE,OAAO,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC;IACpD,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IAClB,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IAClB,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,KAAK,CAAC,GAAG,GAAG,CAAC;IACjD,QAAQ,KAAK,EAAE,CAAC;QACd,KAAK,OAAO;YACV,OAAO,EAAE,EAAE,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;QACtC,KAAK,OAAO;YACV,OAAO,EAAE,EAAE,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,CAAC;QACrC,KAAK,QAAQ;YACX,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC;QAC7B,KAAK,UAAU;YACb,OAAO,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,2BAA2B;QAC1D,KAAK,SAAS,CAAC,CAAC,CAAC;YACf,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,gBAAgB;YAC7E,OAAO,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,CAAC;QACpC,CAAC;QACD,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,MAAM,IAAI,GAAG,KAAK,GAAG,IAAI,CAAC;YAC1B,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC,6CAA6C;YAC3E,OAAO,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,CAAC;QACpC,CAAC;QACD,KAAK,SAAS,CAAC;QACf;YACE,OAAO,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,CAAC;IACtC,CAAC;AACH,CAAC"}

package/dist/field-cell.d.ts

@@ -0,0 +1,62 @@
+import { HTMLElementBase } from './base.ts';
+/**
+ * `<field-cell force="swirl" color="#2dd4bf">` — an in-frame field surface (§25.1).
+ *
+ * A standalone field sized to its container that renders *one* force, with its own
+ * lightweight particle pool, its own pointer interaction, and a lifecycle that pauses
+ * when off-screen. It is **not** the §-engine: it's a lighter "demo/poster" engine,
+ * completely separate from the page `<field-root>` and the core field loop.
+ *
+ * - `ResizeObserver` re-fits the canvas (DPR-aware) and rebuilds the pool.
+ * - `IntersectionObserver` gates the rAF loop — paused when off-screen.
+ * - Honours `prefers-reduced-motion`: renders one static frame, no animation.
+ *
+ * @summary A standalone, in-frame demo field that renders one force with its own
+ * particle pool, in-view-gated. Registered as `<field-cell>`.
+ * @attr {string} force - The single force token rendered: `attract` | `repel` | `swirl` | `gravity` | `stream` | `buoyancy` | `tether`.
+ * @attr {string} color - Accent color (hex) for the cell's particles.
+ * @attr {number} count - Number of particles in the cell's pool.
+ */
+export declare class FieldCell extends HTMLElementBase {
+    static readonly observedAttributes: string[];
+    private readonly canvas;
+    private ctx;
+    private particles;
+    private raf;
+    private resizeObserver?;
+    private intersectionObserver?;
+    /** frame box in CSS pixels (post-DPR transform space). */
+    private boxW;
+    private boxH;
+    /** cursor in frame-local CSS px, or null when absent. */
+    private cursorX;
+    private cursorY;
+    private readonly onPointerMove;
+    private readonly onPointerLeave;
+    private readonly tick;
+    constructor();
+    /** the force this cell demonstrates (§25.1). */
+    get force(): string;
+    /** dot color. */
+    get color(): string;
+    /** particle count; `0` (default) means auto-size to the frame area. */
+    get count(): number;
+    attributeChangedCallback(): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private isPrefersReducedMotion;
+    /** Fit the canvas to the element box (DPR-aware) and rebuild the pool. */
+    private fit;
+    /** Build the particle pool sized to the frame area. */
+    private buildPool;
+    private start;
+    private stop;
+    /** Advance + render one frame. */
+    private step;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'field-cell': FieldCell;
+    }
+}
+//# sourceMappingURL=field-cell.d.ts.map

package/dist/field-cell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-cell.d.ts","sourceRoot":"","sources":["../src/field-cell.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAa5C;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,SAAU,SAAQ,eAAe;IAC5C,MAAM,CAAC,QAAQ,CAAC,kBAAkB,WAA+B;IAEjE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;IAC3C,OAAO,CAAC,GAAG,CAAyC;IAEpD,OAAO,CAAC,SAAS,CAAsB;IACvC,OAAO,CAAC,GAAG,CAAK;IAChB,OAAO,CAAC,cAAc,CAAC,CAAiB;IACxC,OAAO,CAAC,oBAAoB,CAAC,CAAuB;IAEpD,0DAA0D;IAC1D,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,IAAI,CAAK;IAEjB,yDAAyD;IACzD,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,OAAO,CAAuB;IAEtC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA4B;IAC1D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAa;IAC5C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;;IA2BlC,gDAAgD;IAChD,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,iBAAiB;IACjB,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,uEAAuE;IACvE,IAAI,KAAK,IAAI,MAAM,CAGlB;IAED,wBAAwB,IAAI,IAAI;IAKhC,iBAAiB,IAAI,IAAI;IAqBzB,oBAAoB,IAAI,IAAI;IAU5B,OAAO,CAAC,sBAAsB;IAO9B,0EAA0E;IAC1E,OAAO,CAAC,GAAG;IAmBX,uDAAuD;IACvD,OAAO,CAAC,SAAS;IAejB,OAAO,CAAC,KAAK;IASb,OAAO,CAAC,IAAI;IAKZ,kCAAkC;IAClC,OAAO,CAAC,IAAI;CAwDb;AAMD,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,YAAY,EAAE,SAAS,CAAC;KACzB;CACF"}

package/dist/field-cell.js

@@ -0,0 +1,220 @@
+import { cellForce } from "./cell-force.js";
+import { HTMLElementBase } from "./base.js";
+const clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
+/**
+ * `<field-cell force="swirl" color="#2dd4bf">` — an in-frame field surface (§25.1).
+ *
+ * A standalone field sized to its container that renders *one* force, with its own
+ * lightweight particle pool, its own pointer interaction, and a lifecycle that pauses
+ * when off-screen. It is **not** the §-engine: it's a lighter "demo/poster" engine,
+ * completely separate from the page `<field-root>` and the core field loop.
+ *
+ * - `ResizeObserver` re-fits the canvas (DPR-aware) and rebuilds the pool.
+ * - `IntersectionObserver` gates the rAF loop — paused when off-screen.
+ * - Honours `prefers-reduced-motion`: renders one static frame, no animation.
+ *
+ * @summary A standalone, in-frame demo field that renders one force with its own
+ * particle pool, in-view-gated. Registered as `<field-cell>`.
+ * @attr {string} force - The single force token rendered: `attract` | `repel` | `swirl` | `gravity` | `stream` | `buoyancy` | `tether`.
+ * @attr {string} color - Accent color (hex) for the cell's particles.
+ * @attr {number} count - Number of particles in the cell's pool.
+ */
+export class FieldCell extends HTMLElementBase {
+    static observedAttributes = ['force', 'color', 'count'];
+    canvas;
+    ctx = null;
+    particles = [];
+    raf = 0;
+    resizeObserver;
+    intersectionObserver;
+    /** frame box in CSS pixels (post-DPR transform space). */
+    boxW = 0;
+    boxH = 0;
+    /** cursor in frame-local CSS px, or null when absent. */
+    cursorX = null;
+    cursorY = null;
+    onPointerMove;
+    onPointerLeave;
+    tick;
+    constructor() {
+        super();
+        const root = this.attachShadow({ mode: 'open' });
+        const style = document.createElement('style');
+        style.textContent =
+            ':host{display:block;position:relative}' +
+                'canvas{width:100%;height:100%;display:block}';
+        this.canvas = document.createElement('canvas');
+        root.append(style, this.canvas);
+        this.onPointerMove = (e) => {
+            const rect = this.canvas.getBoundingClientRect();
+            this.cursorX = e.clientX - rect.left;
+            this.cursorY = e.clientY - rect.top;
+        };
+        this.onPointerLeave = () => {
+            this.cursorX = null;
+            this.cursorY = null;
+        };
+        this.tick = () => {
+            this.step();
+            this.raf = requestAnimationFrame(this.tick);
+        };
+    }
+    /** the force this cell demonstrates (§25.1). */
+    get force() {
+        return this.getAttribute('force') ?? 'attract';
+    }
+    /** dot color. */
+    get color() {
+        return this.getAttribute('color') ?? '#4da3ff';
+    }
+    /** particle count; `0` (default) means auto-size to the frame area. */
+    get count() {
+        const v = Number(this.getAttribute('count'));
+        return Number.isFinite(v) && v > 0 ? Math.round(v) : 0;
+    }
+    attributeChangedCallback() {
+        // force/color read live each frame; count change rebuilds on next resize.
+        if (this.isPrefersReducedMotion() && this.ctx)
+            this.step();
+    }
+    connectedCallback() {
+        // a decorative demo surface — hide it from assistive tech (§18 a11y).
+        if (!this.hasAttribute('aria-hidden'))
+            this.setAttribute('aria-hidden', 'true');
+        this.ctx = this.canvas.getContext('2d');
+        if (!this.ctx)
+            return;
+        this.resizeObserver = new ResizeObserver(() => this.fit());
+        this.resizeObserver.observe(this);
+        this.fit();
+        this.intersectionObserver = new IntersectionObserver((entries) => {
+            const entry = entries[0];
+            if (entry?.isIntersecting)
+                this.start();
+            else
+                this.stop();
+        });
+        this.intersectionObserver.observe(this);
+        this.addEventListener('pointermove', this.onPointerMove);
+        this.addEventListener('pointerleave', this.onPointerLeave);
+    }
+    disconnectedCallback() {
+        this.stop();
+        this.resizeObserver?.disconnect();
+        this.resizeObserver = undefined;
+        this.intersectionObserver?.disconnect();
+        this.intersectionObserver = undefined;
+        this.removeEventListener('pointermove', this.onPointerMove);
+        this.removeEventListener('pointerleave', this.onPointerLeave);
+    }
+    isPrefersReducedMotion() {
+        return (typeof matchMedia !== 'undefined' &&
+            matchMedia('(prefers-reduced-motion: reduce)').matches);
+    }
+    /** Fit the canvas to the element box (DPR-aware) and rebuild the pool. */
+    fit() {
+        if (!this.ctx)
+            return;
+        const rect = this.getBoundingClientRect();
+        const w = Math.max(1, Math.round(rect.width));
+        const h = Math.max(1, Math.round(rect.height));
+        this.boxW = w;
+        this.boxH = h;
+        const dpr = Math.min(2, typeof devicePixelRatio !== 'undefined' ? devicePixelRatio : 1);
+        this.canvas.width = Math.max(1, Math.round(w * dpr));
+        this.canvas.height = Math.max(1, Math.round(h * dpr));
+        this.ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+        this.buildPool();
+        // Static cells (reduced motion or off-screen) get one fresh frame.
+        if (!this.raf)
+            this.step();
+    }
+    /** Build the particle pool sized to the frame area. */
+    buildPool() {
+        const area = this.boxW * this.boxH;
+        const n = this.count > 0 ? this.count : clamp(Math.round(area / 9000), 16, 90);
+        const pool = [];
+        for (let i = 0; i < n; i++) {
+            pool.push({
+                x: Math.random() * this.boxW,
+                y: Math.random() * this.boxH,
+                vx: (Math.random() - 0.5) * 0.4,
+                vy: (Math.random() - 0.5) * 0.4,
+            });
+        }
+        this.particles = pool;
+    }
+    start() {
+        if (this.raf)
+            return;
+        if (this.isPrefersReducedMotion()) {
+            this.step(); // one static frame, no loop
+            return;
+        }
+        this.raf = requestAnimationFrame(this.tick);
+    }
+    stop() {
+        if (this.raf)
+            cancelAnimationFrame(this.raf);
+        this.raf = 0;
+    }
+    /** Advance + render one frame. */
+    step() {
+        const ctx = this.ctx;
+        if (!ctx)
+            return;
+        const W = this.boxW;
+        const H = this.boxH;
+        const cx = W / 2;
+        const cy = H / 2;
+        const reach = Math.min(W, H) * 0.62;
+        const force = this.force;
+        const color = this.color;
+        const animate = this.raf !== 0;
+        ctx.clearRect(0, 0, W, H);
+        ctx.fillStyle = color;
+        ctx.shadowColor = color;
+        ctx.shadowBlur = 6;
+        for (const p of this.particles) {
+            if (animate) {
+                const dx = cx - p.x;
+                const dy = cy - p.y;
+                const { ax, ay } = cellForce(force, dx, dy, reach);
+                p.vx += ax;
+                p.vy += ay;
+                // Per-cell cursor repel (§25.1).
+                if (this.cursorX !== null && this.cursorY !== null) {
+                    const rx = p.x - this.cursorX;
+                    const ry = p.y - this.cursorY;
+                    const dd = Math.hypot(rx, ry);
+                    if (dd > 0 && dd < 80) {
+                        const push = (1 - dd / 80) * 1.8;
+                        p.vx += (rx / dd) * push;
+                        p.vy += (ry / dd) * push;
+                    }
+                }
+                p.x += p.vx;
+                p.y += p.vy;
+                p.vx *= 0.94;
+                p.vy *= 0.94;
+                // Wrap edges.
+                if (p.x < 0)
+                    p.x += W;
+                else if (p.x >= W)
+                    p.x -= W;
+                if (p.y < 0)
+                    p.y += H;
+                else if (p.y >= H)
+                    p.y -= H;
+            }
+            ctx.beginPath();
+            ctx.arc(p.x, p.y, 1.4, 0, Math.PI * 2);
+            ctx.fill();
+        }
+        ctx.shadowBlur = 0;
+    }
+}
+if (typeof customElements !== 'undefined' && !customElements.get('field-cell')) {
+    customElements.define('field-cell', FieldCell);
+}
+//# sourceMappingURL=field-cell.js.map

package/dist/field-cell.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,174 @@
+import { type AgentHandle, type AgentSpec, type AtomPayload, type ThreadLink, type FlowOptions, type OverlayInput, type ScalarGrid, type FieldEventType, type FieldEventMap, type BodySpec, type BodyHandle, type FieldChannelHandle } from '@fundamental-engine/core';
+import { type FieldPlatform } from '@fundamental-engine/platform';
+import { HTMLElementBase } from './base.ts';
+import { type PlatformRuntime } from './platform-runtime.ts';
+export { usePlatformRuntime, isPlatformRuntimeDefault, shouldUsePlatformRuntime, startPlatformRuntime } from './platform-runtime.ts';
+export type { PlatformRuntime } from './platform-runtime.ts';
+export declare class FieldField extends HTMLElementBase {
+    /**
+     * The engine options `<field-root>` forwards to `createBrowserField`, as ONE declarative table —
+     * the single source of truth for the option object built in `start()`, so a new forwarded
+     * `FieldOption` can never be silently dropped from forwarding the way `depth` once was. `accent`
+     * (raw passthrough so a `palette` with no `accent` adopts the palette stop) and
+     * `overlayCanvas`/`feedbackSink` (managed internally) are special-cased in `start()` and absent here.
+     *
+     * `observedAttributes` stays an explicit literal below — the Custom-Elements-Manifest analyzer reads
+     * it statically and can't enumerate a computed array — but the `option-attrs-observed` test pins it
+     * to this table (every `attr` here must be observed), so the two lists can't drift apart.
+     */
+    private static readonly OPTIONS;
+    static readonly observedAttributes: string[];
+    private readonly canvas;
+    private field?;
+    /** Field Surfaces: the optional front overlay surface (light-DOM, above content). */
+    private overlayCanvas?;
+    /** element-level visibility: pages can hide the field (display:none) — skip draw work then. */
+    private visibilityObserver?;
+    private fieldVisible;
+    /** experimental platform runtime (Phase D); present only when the flag is on. */
+    platformRuntime?: PlatformRuntime;
+    /**
+     * The live `@fundamental-engine/platform` instance backing this field (Phase D default), or `undefined` on
+     * the legacy path. Read-only introspection for tools like the Inspector — the registries here are
+     * the real running state (measurements, state, feedback bindings, relationships, overlays, lint).
+     * Read with `measure.last()` etc.; don't call `measure.measure()` off the read phase.
+     */
+    get platform(): FieldPlatform | undefined;
+    constructor();
+    /** the travelling accent (§9); defaults to the first palette color. */
+    get accent(): string;
+    /** particle-count multiplier (§2.5). */
+    get density(): number;
+    /** draw the background Currents (§24). */
+    get waves(): boolean;
+    /** render mode (§20.6); `none` = the signals-only engine — simulate + feed back, never draw (#297). */
+    get renderMode(): 'dots' | 'trails' | 'links' | 'metaballs' | 'voronoi' | 'streamlines' | 'flow' | 'none';
+    /** substrate background: `transparent` (present and not `"false"`) clears to transparent so the
+     *  underlay composites over light content; default `opaque` paints the near-black substrate. */
+    get background(): 'opaque' | 'transparent';
+    /** Field Surfaces: the overlay reading(s) — one mode or a space-separated additive stack. Default `off`. */
+    get overlay(): OverlayInput;
+    /** color template name for the travelling accent (§9), or undefined for `ours`. */
+    get palette(): string | undefined;
+    /** conserved attention (§2.4): present and not `"false"` → one finite strength budget. */
+    get attention(): boolean;
+    /** cross-boundary causality (Concept 4): present and not `"false"` → density spills. */
+    get causality(): boolean;
+    /** first-class mass (§21.3): present and not `"false"` → particle mass ∝ size. */
+    get mass(): boolean;
+    /** density heatmap (field-systems H1): present and not `"false"` → the pooling glow underlay. */
+    get heatmap(): boolean;
+    /** `dpr-cap` — backing-store DPR ceiling (#410); undefined (engine default 2) if absent/invalid. */
+    get dprCap(): number | undefined;
+    /** `depth` — optional z-volume; undefined (engine default 0, the flat field) if absent/invalid. */
+    get depth(): number | undefined;
+    /** re-scan the document for `[data-body]` bodies after a DOM change. */
+    scan(): void;
+    /** alias of `scan`. */
+    rescan(): void;
+    /** recolor the travelling accent (§9). */
+    setAccent(hex: string): void;
+    /** swap the accent color template live (§9). */
+    setPalette(palette: string | readonly string[]): void;
+    /** switch the global formation (§7). */
+    setFormation(name: string): void;
+    /** toggle conserved attention (§2.4) live. */
+    setAttention(on: boolean): void;
+    /** toggle cross-boundary causality (Concept 4) live. */
+    setCausality(on: boolean): void;
+    /** switch the substrate background live: `transparent` composites the underlay over light content. */
+    setBackground(mode: 'opaque' | 'transparent'): void;
+    /** toggle the density heatmap layer (field-systems H1) live. */
+    setHeatmap(on: boolean): void;
+    /** lower/raise the backing-store DPR ceiling at runtime (the dominant fill-rate lever). */
+    setDprCap(cap: number): void;
+    /** switch the underlay render mode (§20.6) live; `none` = signals-only — stop drawing, keep the signals (#297). */
+    setRender(mode: 'dots' | 'trails' | 'links' | 'metaballs' | 'voronoi' | 'streamlines' | 'flow' | 'none'): void;
+    /** render field readings on the overlay surface (Field Surfaces — in front of content); one mode or an additive stack. */
+    setOverlay(mode: OverlayInput): void;
+    /** wire glowing connector lines between a set, or clear with null (§10). */
+    threads(list: ThreadLink[] | null): void;
+    /** a discrete one-shot: shove + heat matter near (x, y), optionally tinting it (§11). */
+    burst(x: number, y: number, hex?: string): void;
+    /** place/move a dynamic flow focus the field bends toward — pulls matter, curves the streamlines. */
+    flowTo(x: number, y: number, opts?: FlowOptions): void;
+    /** remove the flow focus. */
+    clearFlow(): void;
+    /** bind a data record to each base particle (its `weight` scales mass + size); pick back with `atomAt`. */
+    seed(atoms: readonly AtomPayload[]): void;
+    /** add an engine-stepped agent; returns an inert no-op handle if the field hasn't started. */
+    addAgent(spec: AgentSpec): AgentHandle;
+    /** add a programmatic body (no DOM) from a spec; a no-op handle until the field starts. */
+    addBody(spec: BodySpec): BodyHandle;
+    /** register a named external scalar field channel the engine samples; inert handle until the field starts. */
+    addField(name: string, sampler: (x: number, y: number) => number): FieldChannelHandle;
+    /** sample a registered field channel at (x, y); 0 for an unknown channel or before the field starts. */
+    sampleField(name: string, x: number, y: number): number;
+    /** the seeded record on the nearest particle to (x, y), or null — for hover-to-inspect. */
+    atomAt(x: number, y: number): AtomPayload | null;
+    /** focus the nearest seeded particle (hold + light it), returning its record — the dwell affordance. */
+    focusAt(x: number, y: number): AtomPayload | null;
+    /** release the focused particle. */
+    clearFocus(): void;
+    /** live particle-pool size — `store.size` forwarded through the public handle. */
+    particleCount(): number;
+    /** copy live particle state into `out` (stride 5: x, y, z, heat, size); returns the count written
+     *  (0 before the field starts) — the render-agnostic swarm read-out an alternative surface draws. */
+    readParticles(out: Float32Array): number;
+    /** copy each live particle's stable id into a Uint32Array, parallel to readParticles. */
+    readParticleIds(out: Uint32Array): number;
+    /** kinetic/thermal/total energy snapshot for the current frame. */
+    energy(): {
+        kinetic: number;
+        thermal: number;
+        total: number;
+        count: number;
+    };
+    /** sample the live field at `(x, y)` — the net force vector a still test particle would feel
+     *  (zero before the field starts). The seam external visualizers consume to build field geometry. */
+    sample(x: number, y: number): {
+        x: number;
+        y: number;
+    };
+    /** sample the smooth density scalar ∈ [0,1] at `(x, y)` (needs `heatmap`); 0 when off/not started. */
+    sampleScalar(x: number, y: number): number;
+    /** sample the density gradient ∇ at `(x, y)` — up-density direction (needs `heatmap`); `{0,0}` when off/not started. */
+    sampleGradient(x: number, y: number): {
+        x: number;
+        y: number;
+    };
+    /** open a named host-authorable scalar grid (deposit/sample/gradient/decay); a no-op grid until the field starts. */
+    grid(name: string): ScalarGrid;
+    /** subscribe to a discrete field event (absorb/release/settle); a no-op unsubscribe until the field starts. */
+    on<K extends FieldEventType>(type: K, cb: (e: FieldEventMap[K]) => void): () => void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * React to live attribute changes after mount (§13). The color / render / toggle attributes
+     * apply through the field's setters; the construction-time ones (`density`, `waves`, `mass`)
+     * rebuild the field. Fires before `connectedCallback` for the initial attributes too, which the
+     * `this.field` guard skips — the first mount reads every attribute itself.
+     */
+    attributeChangedCallback(name: string, oldVal: string | null, newVal: string | null): void;
+    /** (re)create the engine on the canvas, reading the current attributes. */
+    private start;
+}
+/**
+ * `<field-root>` — the recommended tag for the singleton field. The registry rejects registering one
+ * constructor under two tag names, so this is a thin subclass of {@link FieldField} with identical
+ * behaviour, attributes, and body contract.
+ */
+export declare class FieldRoot extends FieldField {
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'field-field': FieldField;
+        'field-root': FieldRoot;
+    }
+}
+export * from './field-cell.ts';
+export * from './cell-force.ts';
+export * from './mount.ts';
+export { FieldController, REGISTER_BODY, UNREGISTER_BODY, UPDATE_BODY, } from '@fundamental-engine/core';
+export type { RegisterBodyDetail } 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":"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"}