@fundamental-engine/dom 0.7.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,107 @@
+# @fundamental-engine/dom
+
+**The platform layer for [Fundamental](../core)** — the native browser primitives the engine wishes
+existed, built on the ones it has. The core is renderer-agnostic; this package owns DOM participation:
+it supplies the browser host, the six registries that let the engine treat the DOM as a connected,
+measurable, semantic environment, the frame scheduler that keeps reads and writes from thrashing, and
+the runtime that runs recipes and binds data.
+
+→ Live at **[fundamental-engine.com](https://fundamental-engine.com)**.
+
+## Install
+
+```sh
+npm i @fundamental-engine/dom
+```
+
+The public surface is frozen for `0.x` (see
+[API stability](../../docs/canonical/api-stability.md)).
+
+## The browser host
+
+The core's `createField` is renderer-agnostic and requires a `FieldHost`. `browserHost()` is the
+canonical DOM implementation, and `createBrowserField()` is the host-bundled shortcut:
+
+```ts
+import { createField } from '@fundamental-engine/core';
+import { browserHost, createBrowserField } from '@fundamental-engine/dom';
+
+const canvas = document.querySelector('canvas')!;
+const field = createField(canvas, { host: browserHost() });
+// or, equivalently:
+const same = createBrowserField(canvas, {});
+```
+
+## The platform
+
+`createFieldPlatform(root)` wires the six native-first registries on a root element and a frame
+scheduler that runs them in order: **discover → read → compute → state → write → render**.
+
+| Registry | Role |
+|---|---|
+| `MeasurementRegistry` | frame-stable geometry snapshots (read-phase only) |
+| `StateRegistry` | typed numeric / boolean / vector2 element state (not ARIA) |
+| `FeedbackRegistry` | write-phase CSS vars + thresholded, debounced events |
+| `RelationshipRegistry` | normalize native links (`href#id`, `aria-controls`, `for`, …) into one graph |
+| `VisualBindingRegistry` | bind a Canvas / SVG / WebGL visual layer to its semantic source |
+| `OverlayRegistry` | relationship / field-line / debug render layers |
+
+```ts
+import { createFieldPlatform } from '@fundamental-engine/dom';
+
+const platform = createFieldPlatform(document.documentElement);
+platform.measure.register(card, { role: 'body' });
+platform.state.set(card, 'density', 0.72);
+platform.feedback.bind(card, { density: '--field-density' });
+platform.feedback.threshold(card, 'field:lit', { metric: 'density', enter: 0.7, exit: 0.45 });
+platform.tick(); // run one frame through the scheduler
+```
+
+`createFieldPlatform` returns a `FieldPlatform` — the surface the inspector and tools read.
+
+## Recipes and data
+
+The platform runs recipes and binds application data to the field. `compileRecipe()` (the pure
+compiler) lives in [the core](../core); application lives here:
+
+```ts
+import { applyRecipe, bindData } from '@fundamental-engine/dom';
+import { recipeById } from '@fundamental-engine/core';
+
+// Run a recipe over a region; inspect the live run; tear it down.
+const applied = applyRecipe(root, recipeById('reading-field')!);
+applied.inspect(); // { frame, measurements, relationships, lint }
+
+// Bind records → bodies. Updates diff by id; removed records decay out.
+const binding = bindData(listEl, tasks, (t) => ({
+  id: t.id,
+  body: { tokens: ['attract'], strength: 0.4 + t.priority },
+  metrics: { priority: t.priority },
+  label: t.title,
+}), { recipe: 'priority-well' });
+binding.update(nextTasks);
+```
+
+`computeMetrics()` (pure) turns measurements and relationships into the metric values recipes track.
+
+## Lint
+
+`lintPlatform(platform)` runs pure rules over the live registries and the markup (missing
+relationship targets, sinks that capture without `data-feedback`, styles reading feedback
+variables no body writes, unregistered state, overlays without links, off-phase measurement,
+orphan visuals, …) and returns structured diagnostics. The inspector reads it each frame.
+
+## Dependency direction
+
+Strict and one-way: **`platform → core`**. The core stays renderer-agnostic and never imports this
+package. During the migration window, writes mirror `--field-*` to `--forces-*` and `field:*` events to
+`forces:*`. See [`docs/canonical/platform-architecture.md`](../../docs/canonical/platform-architecture.md).
+
+## Related
+
+[`Fundamental`](../core) · [`@fundamental-engine/elements`](../elements) · [`@fundamental-engine/react`](../react) ·
+[`@fundamental-engine/vanilla`](../vanilla) · the [documentation map](../../docs/README.md).
+
+## License
+
+MIT © Zach Shallbetter

package/dist/apply-recipe.d.ts

@@ -0,0 +1,103 @@
+/**
+ * applyRecipe — the DOM counterpart to core's `compileRecipe`. Turns a `FieldRecipe` from a record
+ * into a running field program: it registers the recipe's bodies (TOKEN lane only — concepts are never
+ * executed), binds its metrics to feedback variables, discovers its relationships, computes metric
+ * state each frame, installs a reduced-motion output when motion is reduced, and returns a handle that
+ * can be inspected and destroyed.
+ *
+ * It runs on a scoped `createFieldPlatform(root)` — the registry/feedback layer, not a particle canvas
+ * — so it works on ordinary content the way the Reading Field studies do.
+ */
+import { type FieldPlatform } from './platform.ts';
+import { type FieldRecipe, type CompiledRecipe } from '@fundamental-engine/core';
+export interface ApplyRecipeOptions {
+    /** existing elements (or a selector within root) to annotate as the recipe's bodies; if omitted, demo elements are created. */
+    bodies?: Element[] | string;
+    /** when bodies are provided, whether to overwrite their data-body attributes with the recipe's (default true). Set false to keep caller-owned tokens (e.g. bindData) while still binding the recipe's metrics. */
+    annotateBodies?: boolean;
+    /** force the reduced-motion output (defaults to the OS prefers-reduced-motion setting). */
+    reducedMotion?: boolean;
+    /** compute + bind metrics (default true). */
+    metrics?: boolean;
+    /** run the rAF loop (default true). Set false to drive `tick()` yourself. */
+    drive?: boolean;
+    /** text for created demo bodies (default: the body's tokens). */
+    label?: (recipe: FieldRecipe, index: number) => string;
+    /**
+     * Apply the recipe with its render stack stripped (`render: []`) — the scoped invisible-field
+     * idiom the example family runs: the field exists purely as metrics/feedback signals on real
+     * content, with no drawn layers. The caller's recipe object is NEVER mutated (it may be the
+     * shared catalog object); `applyRecipe` derives an effective copy, which is what the returned
+     * handle's `recipe`/`compiled` reflect.
+     */
+    renderless?: boolean;
+    /**
+     * A live field to DRIVE with the recipe's render plan (#370) — the missing execution half of
+     * `recipe.render`. Structural: a `FieldHandle` or a `<field-root>` element both satisfy it.
+     * When provided (and not `renderless`/reduced-motion), the compiled plan executes — underlay
+     * matter mode via setRender, the additive overlay reading stack via setOverlay, the heatmap
+     * toggle — and `destroy()` resets the surfaces it drove (dots / off / false). Omitted → the
+     * recipe stays signals-only, exactly as before (fully additive).
+     */
+    field?: RecipeFieldTarget;
+    /**
+     * Extra metric lanes appended to the recipe's `metrics` (deduped, original order preserved) —
+     * e.g. `['attention', 'recency']`. Each appended metric gains the standard feedback binding
+     * (`attention` → `--field-attention`) and flows through the per-frame metric pipeline exactly
+     * like a recipe-declared one. Same no-mutation guarantee as `renderless`.
+     */
+    extraMetrics?: string[];
+}
+export interface AppliedRecipeInspection {
+    id: string;
+    frame: number;
+    measurements: number;
+    /** resolved relationships (both endpoints known). */
+    relationships: number;
+    /** declared relationships whose target id-ref resolves to no element. */
+    relationshipsUnresolved: number;
+    /** resolved / (resolved + unresolved); undefined when no relationships are declared. */
+    relationshipResolution?: number;
+    /** the unresolved declarations, so inspection can name each missing endpoint. */
+    unresolvedRelationships: Array<{
+        from: string;
+        type: string;
+        target: string;
+    }>;
+    /** elementKey → metric → value (the compiled recipe's lanes, live). */
+    metrics: Record<string, Record<string, number>>;
+    lint: number;
+    reducedMotion: boolean;
+}
+export interface AppliedRecipe {
+    id: string;
+    recipe: FieldRecipe;
+    compiled: CompiledRecipe;
+    platform: FieldPlatform;
+    root: Element;
+    elements: Element[];
+    reducedMotion: boolean;
+    inspect(): AppliedRecipeInspection;
+    tick(now?: number): void;
+    destroy(): void;
+}
+/**
+ * Apply a recipe to a root element. Validates, compiles, registers bodies, binds metrics, discovers
+ * relationships, installs the reduced-motion output, and returns a destroyable, inspectable handle.
+ */
+/** The slice of a live field a recipe can drive — FieldHandle and <field-root> both fit. */
+export interface RecipeFieldTarget {
+    setRender?(mode: string): void;
+    setOverlay?(mode: string | string[]): void;
+    setHeatmap?(on: boolean): void;
+}
+/** Execute a compiled render plan on a field target. Exported for tests and custom hosts. */
+export declare function driveRenderPlan(field: RecipeFieldTarget, plan: {
+    underlay: string | null;
+    overlay: string[];
+    heatmap: boolean;
+}): void;
+export declare function applyRecipe(root: Element, recipe: FieldRecipe, options?: ApplyRecipeOptions): AppliedRecipe;
+/** Tear down an applied recipe (alias of `applied.destroy()`). */
+export declare function destroyRecipe(applied: AppliedRecipe): void;
+//# sourceMappingURL=apply-recipe.d.ts.map

package/dist/apply-recipe.d.ts.map

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

package/dist/apply-recipe.js

@@ -0,0 +1,271 @@
+/**
+ * applyRecipe — the DOM counterpart to core's `compileRecipe`. Turns a `FieldRecipe` from a record
+ * into a running field program: it registers the recipe's bodies (TOKEN lane only — concepts are never
+ * executed), binds its metrics to feedback variables, discovers its relationships, computes metric
+ * state each frame, installs a reduced-motion output when motion is reduced, and returns a handle that
+ * can be inspected and destroyed.
+ *
+ * It runs on a scoped `createFieldPlatform(root)` — the registry/feedback layer, not a particle canvas
+ * — so it works on ordinary content the way the Reading Field studies do.
+ */
+import { createFieldPlatform } from "./platform.js";
+import { lintPlatform } from "./lint.js";
+import { prefersReducedMotion } from "./env.js";
+import { computeMetrics, groundedRecency, METRIC_KINDS } from "./metrics.js";
+import { validateRecipe, compileRecipe, } from '@fundamental-engine/core';
+const isMetricKind = (m) => METRIC_KINDS.includes(m);
+const num = (v) => {
+    if (v == null)
+        return undefined;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : undefined;
+};
+const elementKey = (el, i) => el.id || `${el.tagName.toLowerCase()}#${i}`;
+/** Execute a compiled render plan on a field target. Exported for tests and custom hosts. */
+export function driveRenderPlan(field, plan) {
+    if (plan.underlay && field.setRender)
+        field.setRender(plan.underlay);
+    if (field.setOverlay)
+        field.setOverlay(plan.overlay.length ? plan.overlay : 'off');
+    if (field.setHeatmap)
+        field.setHeatmap(plan.heatmap);
+}
+export function applyRecipe(root, recipe, options = {}) {
+    // Derive the effective recipe from the scoped-field options — a copy, so a shared catalog
+    // recipe object is never mutated by an applied run (`renderless` strips the render stack;
+    // `extraMetrics` appends + dedupes metric lanes). No options → the input recipe, untouched.
+    const extra = options.extraMetrics ?? [];
+    if (options.renderless || extra.length) {
+        recipe = {
+            ...recipe,
+            ...(options.renderless ? { render: [] } : {}),
+            ...(extra.length ? { metrics: [...new Set([...(recipe.metrics ?? []), ...extra])] } : {}),
+        };
+    }
+    const problems = validateRecipe(recipe);
+    if (problems.length)
+        throw new Error(`applyRecipe: invalid recipe "${recipe.id}": ${problems.map((p) => `${p.path} (${p.issue})`).join('; ')}`);
+    const compiled = compileRecipe(recipe);
+    const wantMetrics = options.metrics !== false;
+    // the execution half of recipe.render (#370): drive the supplied field with the compiled plan.
+    // Reduced motion skips the drive entirely — the recipe's static plan is the equivalent, and a
+    // field left at its resting surfaces (dots / off) IS the static reading.
+    let droveField = null;
+    const reducedMotion = options.reducedMotion ?? prefersReducedMotion();
+    const platform = createFieldPlatform(root);
+    if (options.field && !options.renderless && !reducedMotion) {
+        driveRenderPlan(options.field, compiled.render);
+        droveField = options.field;
+    }
+    // ── resolve body elements: annotate provided ones, or create demo bodies ──────────────
+    const created = [];
+    const restore = [];
+    let elements;
+    if (options.bodies) {
+        elements = typeof options.bodies === 'string' ? Array.from(root.querySelectorAll(options.bodies)) : options.bodies.slice();
+        if (options.annotateBodies !== false) {
+            elements.forEach((el, i) => {
+                const body = compiled.bodies[i % compiled.bodies.length];
+                const snap = {};
+                for (const [k, v] of Object.entries(body.attributes)) {
+                    snap[k] = el.getAttribute(k);
+                    el.setAttribute(k, v);
+                }
+                restore.push({ el, attrs: snap });
+            });
+        }
+    }
+    else {
+        elements = compiled.bodies.map((body, i) => {
+            const el = (root.ownerDocument ?? document).createElement('span');
+            for (const [k, v] of Object.entries(body.attributes))
+                el.setAttribute(k, v);
+            el.setAttribute('data-recipe-body', recipe.id);
+            el.textContent = options.label ? options.label(recipe, i) : body.tokens.join(' ');
+            root.appendChild(el);
+            created.push(el);
+            return el;
+        });
+    }
+    // ── register for measurement + bind the metric lane to feedback variables ──────────────
+    const varMap = {};
+    for (const f of compiled.feedback)
+        varMap[f.metric] = f.var;
+    for (const el of elements) {
+        platform.measure.register(el, { role: 'recipe-body' });
+        if (wantMetrics && compiled.feedback.length)
+            platform.feedback.bind(el, varMap);
+    }
+    // ── discover relationships once ──────────────────────────────────────────────────────
+    let discovered = false;
+    platform.on('discover', () => {
+        if (!discovered) {
+            platform.relationships.discover(root);
+            discovered = true;
+        }
+    });
+    // ── metric computation (compute → state); write phase flushes state → --field-* vars ───
+    const prev = new Map();
+    if (wantMetrics) {
+        const pending = new Map();
+        platform.on('compute', (ctx) => {
+            const vh = ctx.viewport?.height ?? (typeof window !== 'undefined' ? window.innerHeight : 800);
+            const centre = vh / 2;
+            // WORLD TIME, once per frame: ctx.now is the scheduler's rAF timebase, not an epoch, so
+            // the declared-timestamp derivation samples the wall clock HERE — one instant shared by
+            // every element in the frame, never a per-element Date.now().
+            const worldNow = Date.now();
+            const rels = platform.relationships.all();
+            const unresolved = platform.relationships.unresolvedAll();
+            for (const m of platform.measure.last()) {
+                const el = m.element;
+                const proximity = Math.max(0, 1 - Math.abs(m.rect.cy - centre) / (vh * 0.55));
+                const engaged = el.matches(':hover, :focus, :focus-within') || el.hasAttribute('data-active');
+                // a body touches a relationship if either endpoint is the body or sits inside it (child anchors)
+                const touching = rels.filter((r) => el.contains(r.from) || el.contains(r.to));
+                // declared-but-unresolved edges originating in this body count toward the total but not the
+                // resolved set, so resolution is real: a citation pointing at nothing lowers it (raising entropy).
+                const touchingUnresolved = unresolved.filter((u) => el.contains(u.from));
+                const relResolved = touching.length;
+                const relTotal = touching.length + touchingUnresolved.length;
+                const relConflict = touching.filter((r) => r.type === 'contradicts' || r.type === 'opposes' || r.type === 'conflicts-with').length;
+                const supplied = {};
+                for (const k of METRIC_KINDS) {
+                    const s = num(el.getAttribute(`data-field-${k}`));
+                    if (s != null)
+                        supplied[k] = s;
+                }
+                // A declared world timestamp (data-field-at) GROUNDS the recency lane: recency becomes
+                // freshness(at, now, halfLife) — data time, not interaction time. An explicit
+                // data-field-recency still wins; without either, computeMetrics infers recency from
+                // interaction (the existing eased behavior, unchanged).
+                if (supplied.recency == null) {
+                    const r = groundedRecency(el, worldNow);
+                    if (r != null)
+                        supplied.recency = r;
+                }
+                pending.set(el, computeMetrics({
+                    proximity,
+                    visible: m.visibilityRatio,
+                    engaged,
+                    dtFrames: 1,
+                    relResolved,
+                    relTotal,
+                    relConflict,
+                    supplied,
+                    prev: prev.get(el) ?? {},
+                }));
+            }
+        });
+        platform.on('state', () => {
+            for (const [el, computed] of pending) {
+                prev.set(el, computed);
+                for (const metric of compiled.metrics) {
+                    const value = isMetricKind(metric)
+                        ? computed[metric]
+                        : (num(el.getAttribute(`data-field-${metric}`)) ?? 0);
+                    if (value == null) {
+                        // The metric is absent this frame — e.g. the host supplied data-field-confidence on an
+                        // earlier frame and has since removed it. Drop any stale state AND clear the bound CSS
+                        // var, so the write phase neither re-emits a value nor leaves one written on a previous
+                        // flush lingering on the element. Absent must read as absent, not last-known. Both calls
+                        // are no-ops when nothing was ever set, so the common "never supplied" case stays cheap.
+                        platform.state.delete(el, metric);
+                        platform.feedback.clearVar(el, metric);
+                        continue;
+                    }
+                    platform.state.set(el, metric, value);
+                }
+            }
+        });
+    }
+    // ── reduced-motion output: a real static surface, not just prose ──────────────────────
+    let staticNode = null;
+    if (reducedMotion) {
+        root.dataset.recipeReduced = 'on';
+        const doc = root.ownerDocument ?? document;
+        staticNode = doc.createElement('aside');
+        staticNode.className = 'recipe-static';
+        staticNode.setAttribute('data-recipe-static', recipe.id);
+        staticNode.innerHTML =
+            `<p class="rs-note">${escapeHtml(compiled.reducedMotion.meaningWithoutMotion)}</p>` +
+                (compiled.metrics.length ? `<p class="rs-metrics">Metrics: ${compiled.metrics.map((m) => `<span>${escapeHtml(m)}</span>`).join(' ')}</p>` : '') +
+                (compiled.relationships.length ? `<p class="rs-rels">Relationships: ${compiled.relationships.map((r) => `${escapeHtml(r.from)}→${escapeHtml(r.to)}`).join(', ')}</p>` : '');
+        root.appendChild(staticNode);
+    }
+    // ── drive ─────────────────────────────────────────────────────────────────────────────
+    let raf = 0;
+    const viewport = () => (typeof window !== 'undefined' ? { width: window.innerWidth, height: window.innerHeight } : undefined);
+    const tick = (now = 0) => {
+        platform.tick(now, viewport());
+    };
+    if (options.drive !== false && typeof requestAnimationFrame !== 'undefined') {
+        const loop = (now) => {
+            tick(now);
+            raf = requestAnimationFrame(loop);
+        };
+        raf = requestAnimationFrame(loop);
+    }
+    const inspect = () => {
+        const metrics = {};
+        elements.forEach((el, i) => {
+            const row = {};
+            for (const metric of compiled.metrics)
+                row[metric] = platform.state.number(el, metric);
+            metrics[elementKey(el, i)] = row;
+        });
+        const unresolved = platform.relationships.unresolvedAll();
+        const resolvedCount = platform.relationships.all().length;
+        const declaredTotal = resolvedCount + unresolved.length;
+        return {
+            id: recipe.id,
+            frame: platform.scheduler.frame,
+            measurements: platform.measure.size,
+            relationships: resolvedCount,
+            relationshipsUnresolved: unresolved.length,
+            relationshipResolution: declaredTotal > 0 ? resolvedCount / declaredTotal : undefined,
+            unresolvedRelationships: unresolved.map((u) => ({
+                from: u.from.id || u.from.tagName.toLowerCase(),
+                type: u.type,
+                target: u.target,
+            })),
+            metrics,
+            lint: lintPlatform(platform).length,
+            reducedMotion,
+        };
+    };
+    const destroy = () => {
+        if (raf)
+            cancelAnimationFrame(raf);
+        raf = 0;
+        // release the surfaces this recipe drove — the field returns to its resting reading
+        if (droveField) {
+            driveRenderPlan(droveField, { underlay: 'dots', overlay: [], heatmap: false });
+            droveField = null;
+        }
+        // clear the feedback variables this recipe wrote, so a torn-down recipe leaves the DOM plain
+        // (typeof-guarded like every other global here, so destroy() is safe off-DOM too)
+        if (typeof HTMLElement !== 'undefined')
+            for (const el of elements)
+                if (el instanceof HTMLElement)
+                    for (const f of compiled.feedback)
+                        el.style.removeProperty(f.var);
+        for (const el of created)
+            el.remove();
+        for (const { el, attrs } of restore)
+            for (const [k, v] of Object.entries(attrs))
+                v == null ? el.removeAttribute(k) : el.setAttribute(k, v);
+        staticNode?.remove();
+        if (reducedMotion)
+            delete root.dataset.recipeReduced;
+    };
+    return { id: recipe.id, recipe, compiled, platform, root, elements, reducedMotion, inspect, tick, destroy };
+}
+/** Tear down an applied recipe (alias of `applied.destroy()`). */
+export function destroyRecipe(applied) {
+    applied.destroy();
+}
+function escapeHtml(s) {
+    return s.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c] ?? c);
+}
+//# sourceMappingURL=apply-recipe.js.map

package/dist/apply-recipe.js.map

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

package/dist/bind-data.d.ts

@@ -0,0 +1,72 @@
+/**
+ * bindData — make real application data participate in field behavior. Records become bodies, mapped
+ * metrics become state, mapped relationships become graph edges, and a recipe supplies the behavior
+ * (metric/feedback framework) via applyRecipe(). Updates are deterministic (diff by id); removed
+ * records decay before they leave rather than popping.
+ *
+ *   const binding = bindData(container, records, mapper, { recipe: 'search-relevance-field' });
+ *   binding.update(nextRecords);
+ *   binding.destroy();
+ *
+ * The recipe frames the field (which metrics → --field-* are tracked); the per-record mapper owns the
+ * body tokens, metric values, and relationships — so the data drives the field, not a mock.
+ */
+import { type FieldRecipe } from '@fundamental-engine/core';
+import { type AppliedRecipe } from './apply-recipe.ts';
+export interface MappedBody {
+    tokens: string[];
+    strength?: number;
+    range?: number;
+    spin?: number;
+    angle?: number;
+    feedback?: boolean;
+}
+export interface MappedRelationship {
+    to: string;
+    type: string;
+    strength?: number;
+}
+export interface MappedRecord {
+    id: string;
+    body: MappedBody;
+    metrics?: Record<string, number>;
+    relationships?: MappedRelationship[];
+    label?: string;
+}
+export type RecordMapper<T> = (record: T, index: number) => MappedRecord;
+export interface BindDataOptions<T = unknown> {
+    /** the recipe whose metric/feedback framework drives the bound bodies (id or object). */
+    recipe?: string | FieldRecipe;
+    /** decay duration (ms) before a removed record leaves the DOM (default 400). */
+    decayMs?: number;
+    /** element tag for each record (default 'div'). */
+    tag?: string;
+    /** class added to each record element. */
+    className?: string;
+    /** install the recipe's reduced-motion output instead of motion (passed to applyRecipe). */
+    reducedMotion?: boolean;
+    /** custom inner HTML per record (domain markup); overrides the default label. Relationship anchors are kept. */
+    content?: (record: T, mapped: MappedRecord) => string;
+}
+export interface DataBindingInspection {
+    records: number;
+    bodies: number;
+    relationships: number;
+}
+export interface DataBinding<T> {
+    container: HTMLElement;
+    update(records: T[]): void;
+    ids(): string[];
+    applied(): AppliedRecipe | null;
+    inspect(): DataBindingInspection | null;
+    destroy(): void;
+}
+/** Diff two id sets (pure). */
+export declare function diffIds(prev: Iterable<string>, next: Iterable<string>): {
+    added: string[];
+    removed: string[];
+    kept: string[];
+};
+/** Bind records to a field. Returns a handle with update()/destroy(). */
+export declare function bindData<T>(container: HTMLElement, records: T[], mapper: RecordMapper<T>, options?: BindDataOptions<T>): DataBinding<T>;
+//# sourceMappingURL=bind-data.d.ts.map

package/dist/bind-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bind-data.d.ts","sourceRoot":"","sources":["../src/bind-data.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAc,KAAK,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACxE,OAAO,EAAe,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEpE,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AACD,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AACD,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,aAAa,CAAC,EAAE,kBAAkB,EAAE,CAAC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AACD,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,YAAY,CAAC;AAEzE,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,OAAO;IAC1C,yFAAyF;IACzF,MAAM,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IAC9B,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4FAA4F;IAC5F,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,gHAAgH;IAChH,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,YAAY,KAAK,MAAM,CAAC;CACvD;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;CACvB;AACD,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,SAAS,EAAE,WAAW,CAAC;IACvB,MAAM,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC;IAC3B,GAAG,IAAI,MAAM,EAAE,CAAC;IAChB,OAAO,IAAI,aAAa,GAAG,IAAI,CAAC;IAChC,OAAO,IAAI,qBAAqB,GAAG,IAAI,CAAC;IACxC,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,+BAA+B;AAC/B,wBAAgB,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAS9H;AAkDD,yEAAyE;AACzE,wBAAgB,QAAQ,CAAC,CAAC,EAAE,SAAS,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,OAAO,GAAE,eAAe,CAAC,CAAC,CAAM,GAAG,WAAW,CAAC,CAAC,CAAC,CA2E3I"}