@fundamental-engine/core 0.4.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,128 @@
+# field-ui
+
+**The renderer-agnostic field engine.** `@fundamental-engine/core` computes the field: forces, particles, metrics,
+recipes, diagnostics, and conformance, against plain data, with **zero runtime dependencies** and
+**zero DOM**. Your page's elements become physical bodies in one shared field; they exert force, and
+the field's local density bends them back. The visible canvas is one render surface, not the system.
+
+This is the core. Most apps consume it through a thin adapter that wires the browser for you:
+[`@fundamental-engine/elements`](../elements) (web component), [`@fundamental-engine/react`](../react), or
+[`@fundamental-engine/vanilla`](../vanilla). Reach for the core directly when you own the render loop or target a
+renderer other than the DOM canvas.
+
+→ Live manual, Lab, and design system at **[fundamental-engine.com](https://fundamental-engine.com)**.
+
+## Install
+
+```sh
+npm i @fundamental-engine/core
+```
+
+The browser host lives in [`@fundamental-engine/platform`](../platform); most apps reach for a thin adapter
+([`@fundamental-engine/elements`](../elements), [`@fundamental-engine/react`](../react), [`@fundamental-engine/vanilla`](../vanilla))
+instead of wiring the host themselves. The public surface is frozen for `0.x` (see
+[API stability](../../docs/canonical/field-ui-api-stability.md)).
+
+## What's inside
+
+- **36 forces** in three families: **9 canonical** verbs (`attract`, `repel`, `swirl`, `stream`,
+  `viscosity`, `jet`, `tether`, `wall`, `sink`), **8 natural** primitives (`gravity`, `charge`,
+  `magnetism`, `thermal`, `collide`, `diffuse`, `propagate`, `memory`), and **19 designed-extended**
+  forces (`lens`, `gate`, `buoyancy`, `shear`, `crystallize`, `align`, `wind`, `cohesion`, `pressure`,
+  `link`, `morph`, `hunt`, `spawn`, `resonate`, `spotlight`, the `screen` quiet zone, `pigment`,
+  field-line transport `fieldflow`, and wormhole relocate `warp`).
+- **8 presets** compose those primitives into cosmology with no new engine code (`blackhole`, `star`,
+  `galaxy`, `tornado`, …), plus **5 formations** that bias the whole field and **6 condition** gates.
+- **16 render modes**: matter/structure (`dots`, `trails`, `links`, `streamlines`, `metaballs`,
+  `voronoi`, `field-lines`, `heatmap`) and diagnostics (`force-vectors`, `contours`, `potential`,
+  `energy`, `topology`, `inspector`, `causality`, `prediction`).
+- **64 recipes** across 4 tiers: a recipe is a portable field program. `compileRecipe()` lives here
+  (pure, no DOM); `applyRecipe()` and `bindData()` are in [`@fundamental-engine/platform`](../platform).
+- **A conformance framework** that fires known particles into each force and checks the measured
+  trajectory against the math. The same catalog drives the tests and the visual Lab.
+
+## Quick start
+
+`createField` is renderer-agnostic, so it **requires a host** (a `FieldHost`: viewport, scroll, raf,
+and a canvas). In the browser, the host comes from [`@fundamental-engine/platform`](../platform):
+
+```ts
+import { createField } from '@fundamental-engine/core';
+import { browserHost } from '@fundamental-engine/platform';
+
+const canvas = document.querySelector('canvas')!;
+const field = createField(canvas, { host: browserHost(), accent: '#4da3ff' });
+
+// Any [data-body] element on the page becomes a force the field reacts to:
+//   <a data-body="attract" data-strength="0.9" data-range="320" data-feedback>pull me</a>
+field.scan(); // re-scan [data-body] after a DOM change
+```
+
+If you do not want to wire the host yourself, [`@fundamental-engine/vanilla`](../vanilla) re-exports a
+host-bundled `createField` (and a `FieldField` class), and [`@fundamental-engine/elements`](../elements) /
+[`@fundamental-engine/react`](../react) wrap it as a custom element / component. `createField` called without a
+host throws a clear error pointing you to those doors.
+
+## The model
+
+- **Bodies** are declared in markup with `data-body="<force> <force>…"` (forces compose). Common
+  attributes: `data-strength`, `data-range`, `data-color`, `data-when` (a condition gate), and
+  `data-feedback` (two-way density write-back).
+- **The field** is one conserved pool of particles. It re-reads every body's rectangle each frame, so
+  any layout change *is* a change to the force geometry.
+- **Feedback** samples the density gathered on a body and eases it into the element's `--field-density`
+  custom property (with `--d` and `--forces-density` as legacy aliases). Drive weight, glow, and scale
+  from it.
+
+## The handle
+
+`createField` returns a `FieldHandle`:
+
+```ts
+field.scan();                   // re-scan [data-body] after a DOM change
+field.setAccent('#a78bfa');     // recolor the travelling accent
+field.setPalette('heatmap');    // swap the accent color template
+field.setFormation('wells');    // switch the global formation
+field.setAttention(true);       // conserved attention — one finite strength budget
+field.setCausality(true);       // cross-boundary causality — density spills to neighbours
+field.setRender('streamlines'); // draw the force field itself (a diagnostic mode)
+field.flowTo(x, y);             // place a movable flow focus the field bends toward
+field.burst(x, y, '#fff');      // a one-shot shove + heat near a point
+field.destroy();                // stop the loop, release listeners
+```
+
+Reduced motion is honoured (`prefers-reduced-motion` freezes the sim), and the loop pauses when the tab
+is backgrounded.
+
+## Recipes
+
+A recipe names an intent and composes existing tokens into behavior. It never adds engine behavior, and
+its lanes stay separate: concepts describe, tokens execute, metrics measure, diagnostics explain,
+conditions activate. `compileRecipe()` turns a `FieldRecipe` into a compiled plan with no DOM:
+
+```ts
+import { compileRecipe, recipeById } from '@fundamental-engine/core';
+
+const plan = compileRecipe(recipeById('priority-well')!);
+// → bodies, relationships, feedback, diagnostics, metrics, and a reduced-motion output.
+```
+
+`applyRecipe()` (run a recipe on a live DOM platform) and `bindData()` (records → bodies) are in
+[`@fundamental-engine/platform`](../platform). Browse all 64 at [`/docs/gallery`](https://fundamental-engine.com/docs/gallery).
+
+## Renderer-agnostic
+
+The engine touches no DOM globals (a boundary test keeps the allowlist empty). Everything the browser
+provides arrives through an injected `FieldHost`, so the same engine runs on a DOM canvas, an offscreen
+canvas, a headless harness, or any renderer you implement. `browserHost()` (in
+[`@fundamental-engine/platform`](../platform)) is the canonical DOM implementation of that contract.
+
+## Related
+
+[`@fundamental-engine/platform`](../platform) · [`@fundamental-engine/elements`](../elements) ·
+[`@fundamental-engine/react`](../react) · [`@fundamental-engine/vanilla`](../vanilla) · the
+[documentation map](../../docs/README.md).
+
+## License
+
+MIT © Zach Shallbetter

package/dist/agents/element-agent.d.ts

@@ -0,0 +1,38 @@
+/**
+ * ElementAgent (system-contracts §6) — a DOM element that receives field metrics and writes DOM
+ * state. The engine already writes `--d` / `--field-density` for the density metric; this widens
+ * that to the full ElementAgent metric set (attention, heat, entropy, coherence, memory, pressure,
+ * pull-x/y) and emits the `--field-*` var for each, plus a
+ * `data-field-*` state attribute band for CSS that prefers attribute selectors.
+ *
+ * `elementAgentVars` / `elementAgentState` are pure (no DOM) so they are node-testable; the thin
+ * `writeElementAgent` applies them to a real element. An ElementAgent never mutates particles
+ * unless it is also a registered body (the §6 rule).
+ */
+/** The metrics an ElementAgent can receive (system-contracts §6). All optional. */
+export interface ElementMetrics {
+    density?: number;
+    attention?: number;
+    heat?: number;
+    entropy?: number;
+    coherence?: number;
+    memory?: number;
+    pressure?: number;
+    pullX?: number;
+    pullY?: number;
+}
+/**
+ * The CSS custom properties an ElementAgent writes for a metric set — each metric as
+ * `--field-<m>`. Pure.
+ */
+export declare function elementAgentVars(m: ElementMetrics): Record<string, string>;
+/**
+ * A coarse `data-field-*` state band for a metric (`low` < 0.33 ≤ `mid` < 0.66 ≤ `high`), so CSS
+ * can switch on `[data-field-density="high"]` without reading the numeric var. Pure.
+ */
+export declare function elementAgentState(m: ElementMetrics): Record<string, string>;
+/** Apply an ElementAgent's metrics to a real element (CSS vars + data-field-* state). Thin DOM. */
+export declare function writeElementAgent(el: HTMLElement, m: ElementMetrics): void;
+/** Clear everything an ElementAgent wrote (teardown / unregister). Thin DOM. */
+export declare function clearElementAgent(el: HTMLElement): void;
+//# sourceMappingURL=element-agent.d.ts.map

package/dist/agents/element-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-agent.d.ts","sourceRoot":"","sources":["../../src/agents/element-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,mFAAmF;AACnF,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAiBD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQ1E;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAS3E;AAED,mGAAmG;AACnG,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,WAAW,EAAE,CAAC,EAAE,cAAc,GAAG,IAAI,CAK1E;AAED,gFAAgF;AAChF,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,CAKvD"}

package/dist/agents/element-agent.js

@@ -0,0 +1,70 @@
+/**
+ * ElementAgent (system-contracts §6) — a DOM element that receives field metrics and writes DOM
+ * state. The engine already writes `--d` / `--field-density` for the density metric; this widens
+ * that to the full ElementAgent metric set (attention, heat, entropy, coherence, memory, pressure,
+ * pull-x/y) and emits the `--field-*` var for each, plus a
+ * `data-field-*` state attribute band for CSS that prefers attribute selectors.
+ *
+ * `elementAgentVars` / `elementAgentState` are pure (no DOM) so they are node-testable; the thin
+ * `writeElementAgent` applies them to a real element. An ElementAgent never mutates particles
+ * unless it is also a registered body (the §6 rule).
+ */
+/** metric key → CSS-var suffix (kebab). */
+const SUFFIX = {
+    density: 'density',
+    attention: 'attention',
+    heat: 'heat',
+    entropy: 'entropy',
+    coherence: 'coherence',
+    memory: 'memory',
+    pressure: 'pressure',
+    pullX: 'pull-x',
+    pullY: 'pull-y',
+};
+const fmt = (n) => (Number.isFinite(n) ? n.toFixed(3) : '0');
+/**
+ * The CSS custom properties an ElementAgent writes for a metric set — each metric as
+ * `--field-<m>`. Pure.
+ */
+export function elementAgentVars(m) {
+    const out = {};
+    for (const key of Object.keys(m)) {
+        const v = m[key];
+        if (v == null)
+            continue;
+        out[`--field-${SUFFIX[key]}`] = fmt(v);
+    }
+    return out;
+}
+/**
+ * A coarse `data-field-*` state band for a metric (`low` < 0.33 ≤ `mid` < 0.66 ≤ `high`), so CSS
+ * can switch on `[data-field-density="high"]` without reading the numeric var. Pure.
+ */
+export function elementAgentState(m) {
+    const band = (v) => (v < 0.33 ? 'low' : v < 0.66 ? 'mid' : 'high');
+    const out = {};
+    for (const key of Object.keys(m)) {
+        const v = m[key];
+        if (v == null || key === 'pullX' || key === 'pullY')
+            continue; // bands are for scalar 0..1 metrics
+        out[`data-field-${SUFFIX[key]}`] = band(v);
+    }
+    return out;
+}
+/** Apply an ElementAgent's metrics to a real element (CSS vars + data-field-* state). Thin DOM. */
+export function writeElementAgent(el, m) {
+    const vars = elementAgentVars(m);
+    for (const name of Object.keys(vars))
+        el.style.setProperty(name, vars[name]);
+    const state = elementAgentState(m);
+    for (const name of Object.keys(state))
+        el.setAttribute(name, state[name]);
+}
+/** Clear everything an ElementAgent wrote (teardown / unregister). Thin DOM. */
+export function clearElementAgent(el) {
+    for (const key of Object.keys(SUFFIX)) {
+        el.style.removeProperty(`--field-${SUFFIX[key]}`);
+        el.removeAttribute(`data-field-${SUFFIX[key]}`);
+    }
+}
+//# sourceMappingURL=element-agent.js.map

package/dist/agents/element-agent.js.map

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

package/dist/agents/event-agent.d.ts

@@ -0,0 +1,47 @@
+/**
+ * EventAgent — the Event Contract runtime (system-contracts §9). A field event must be
+ * thresholded, debounced, and not fire every frame. The `Thresholder` turns a continuous metric
+ * (density, attention, relationship strength…) into discrete `entered` / `exited` edges with
+ * hysteresis (separate enter/exit levels) and a debounce window, so a body crossing a level emits
+ * one clean event instead of a per-frame storm.
+ */
+export type ThresholdEdge = 'entered' | 'exited' | null;
+export interface ThresholdConfig {
+    /** value at or above which the agent becomes "lit" (fires `entered`). */
+    enter: number;
+    /** value at or below which it goes "dim" (fires `exited`). Should be ≤ enter for hysteresis. */
+    exit: number;
+    /** minimum ms between edge changes — debounce. */
+    debounceMs: number;
+}
+/** A hysteretic, debounced edge detector over a single metric. */
+export declare class Thresholder {
+    private lit;
+    private lastEdgeMs;
+    private readonly cfg;
+    constructor(cfg: ThresholdConfig);
+    /** Feed the current metric value and time; returns the edge crossed this tick, or null. */
+    update(value: number, nowMs: number): ThresholdEdge;
+    /** Whether the agent is currently above threshold. */
+    get isLit(): boolean;
+    /** Reset to the dim state (e.g. on teardown). */
+    reset(): void;
+}
+/** A named field event with its `field:*` name. */
+export interface FieldEventName {
+    field: string;
+    /** the metric whose threshold crossing fires it (where applicable). */
+    metric?: string;
+}
+/**
+ * The named field-event catalog (system-contracts §9, shadow-dom §22, interaction §12). These are
+ * the thresholded, debounced events the engine may dispatch — never per-frame by default.
+ * `field:lit`/`dim` and the `*-body` lifecycle events are dispatched today; the rest are the agreed
+ * names for agent/threshold events as they wire up.
+ */
+export declare const FIELD_EVENTS: Readonly<Record<string, FieldEventName>>;
+/** Map a metric to its conventional `field:*` event name for an edge. */
+export declare function eventNamesFor(metric: string, edge: Exclude<ThresholdEdge, null>): {
+    field: string;
+};
+//# sourceMappingURL=event-agent.d.ts.map

package/dist/agents/event-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-agent.d.ts","sourceRoot":"","sources":["../../src/agents/event-agent.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,QAAQ,GAAG,IAAI,CAAC;AAExD,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;IACd,gGAAgG;IAChG,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,kEAAkE;AAClE,qBAAa,WAAW;IACtB,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAkB;gBAC1B,GAAG,EAAE,eAAe;IAIhC,2FAA2F;IAC3F,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa;IAenD,sDAAsD;IACtD,IAAI,KAAK,IAAI,OAAO,CAEnB;IAED,iDAAiD;IACjD,KAAK,IAAI,IAAI;CAId;AAED,mDAAmD;AACnD,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAsBjE,CAAC;AAEF,yEAAyE;AACzE,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,aAAa,EAAE,IAAI,CAAC,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAWnG"}

package/dist/agents/event-agent.js

@@ -0,0 +1,82 @@
+/**
+ * EventAgent — the Event Contract runtime (system-contracts §9). A field event must be
+ * thresholded, debounced, and not fire every frame. The `Thresholder` turns a continuous metric
+ * (density, attention, relationship strength…) into discrete `entered` / `exited` edges with
+ * hysteresis (separate enter/exit levels) and a debounce window, so a body crossing a level emits
+ * one clean event instead of a per-frame storm.
+ */
+/** A hysteretic, debounced edge detector over a single metric. */
+export class Thresholder {
+    lit = false;
+    lastEdgeMs = -Infinity;
+    cfg;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    /** Feed the current metric value and time; returns the edge crossed this tick, or null. */
+    update(value, nowMs) {
+        const settled = nowMs - this.lastEdgeMs >= this.cfg.debounceMs;
+        if (!this.lit && value >= this.cfg.enter && settled) {
+            this.lit = true;
+            this.lastEdgeMs = nowMs;
+            return 'entered';
+        }
+        if (this.lit && value <= this.cfg.exit && settled) {
+            this.lit = false;
+            this.lastEdgeMs = nowMs;
+            return 'exited';
+        }
+        return null;
+    }
+    /** Whether the agent is currently above threshold. */
+    get isLit() {
+        return this.lit;
+    }
+    /** Reset to the dim state (e.g. on teardown). */
+    reset() {
+        this.lit = false;
+        this.lastEdgeMs = -Infinity;
+    }
+}
+/**
+ * The named field-event catalog (system-contracts §9, shadow-dom §22, interaction §12). These are
+ * the thresholded, debounced events the engine may dispatch — never per-frame by default.
+ * `field:lit`/`dim` and the `*-body` lifecycle events are dispatched today; the rest are the agreed
+ * names for agent/threshold events as they wire up.
+ */
+export const FIELD_EVENTS = {
+    // --- dispatched today (shipped) ---
+    registerBody: { field: 'field:register-body' },
+    unregisterBody: { field: 'field:unregister-body' },
+    updateBody: { field: 'field:update-body' },
+    lit: { field: 'field:lit', metric: 'density' },
+    dim: { field: 'field:dim', metric: 'density' },
+    // capture/release (§22.3): a sink fires field:captured on the rising edge of accreting and
+    // field:released on supernova; docked elements fire them too. Edge-debounced (see field.ts).
+    captured: { field: 'field:captured' },
+    released: { field: 'field:released' },
+    // relocate (§22.3): a [data-warp] element teleports its transform to its paired throat.
+    relocated: { field: 'field:relocated' },
+    // --- names reserved; NOT yet dispatched by the engine (planned agent-threshold events).
+    //     See docs/canonical/field-ui-agent-consumption-model.md (Events). ---
+    entered: { field: 'field:entered', metric: 'density' },
+    exited: { field: 'field:exited', metric: 'density' },
+    saturated: { field: 'field:saturated', metric: 'accreted' },
+    attentionShifted: { field: 'field:attention-shifted', metric: 'attention' },
+    relationshipStrengthened: { field: 'field:relationship-strengthened', metric: 'strength' },
+    memoryThreshold: { field: 'field:memory-threshold', metric: 'memory' },
+    entropyWarning: { field: 'field:entropy-warning', metric: 'entropy' },
+};
+/** Map a metric to its conventional `field:*` event name for an edge. */
+export function eventNamesFor(metric, edge) {
+    // density → lit/dim; attention → attention-shifted; generic → entered/exited
+    const verb = metric === 'density'
+        ? edge === 'entered'
+            ? 'lit'
+            : 'dim'
+        : edge === 'entered'
+            ? 'entered'
+            : 'exited';
+    return { field: `field:${verb}` };
+}
+//# sourceMappingURL=event-agent.js.map

package/dist/agents/event-agent.js.map

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

package/dist/agents/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The FieldAgent model (Phase 5 — interaction-and-relationship-model). Particles are only one kind
+ * of agent: an agent is anything that can receive influence, hold state, change behavior, or affect
+ * another thing. This module adds the non-particle agents (element, relationship, user, layout,
+ * data) and the thresholded EventAgent runtime, plus the agent-type contracts deferred from Phase 4.
+ */
+import type { ContractMeta } from '../contracts/types.ts';
+export * from './event-agent.ts';
+export * from './relationship.ts';
+export * from './element-agent.ts';
+export * from './user-agent.ts';
+export * from './region-agents.ts';
+/** The kinds of agent that can participate in the field (definition-document). */
+export type FieldAgentKind = 'particle' | 'element' | 'relationship' | 'user' | 'layout' | 'data' | 'event';
+/** The agent-type contracts (system-contracts §5–§9), formalized in Phase 5. */
+export declare const AGENT_CONTRACTS: readonly ContractMeta[];
+//# sourceMappingURL=index.d.ts.map

package/dist/agents/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE1D,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AAEnC,kFAAkF;AAClF,MAAM,MAAM,cAAc,GACtB,UAAU,GACV,SAAS,GACT,cAAc,GACd,MAAM,GACN,QAAQ,GACR,MAAM,GACN,OAAO,CAAC;AAEZ,gFAAgF;AAChF,eAAO,MAAM,eAAe,EAAE,SAAS,YAAY,EAiDlD,CAAC"}

package/dist/agents/index.js

@@ -0,0 +1,57 @@
+export * from "./event-agent.js";
+export * from "./relationship.js";
+export * from "./element-agent.js";
+export * from "./user-agent.js";
+export * from "./region-agents.js";
+/** The agent-type contracts (system-contracts §5–§9), formalized in Phase 5. */
+export const AGENT_CONTRACTS = [
+    {
+        name: 'ElementAgent Contract',
+        mustExist: 'a DOM element + the metrics it receives (density, attention, heat, entropy, coherence, memory, pressure, pull-x/y)',
+        mayMutate: 'CSS variables and data-field-* state on its element',
+        sideEffectFree: 'metric reads; it must not mutate particles unless also a registered body',
+        testable: 'receives metrics → writes the matching --field-* vars and data bands; respects reduced motion',
+        inspectable: 'the CSS variables and data-field-* attributes on the element',
+    },
+    {
+        name: 'RelationshipAgent Contract',
+        mustExist: 'id, from, to, type, strength, tension, memory, active',
+        mayMutate: 'its own strength/tension/memory; the attention it transfers between its endpoints',
+        sideEffectFree: 'its dynamics are a pure function of (active, tension, dt)',
+        testable: 'strengthens with use, decays over time, transfers attention, emits thresholded events',
+        inspectable: 'strength/tension/memory and the strengthen/weaken threshold edges',
+    },
+    {
+        name: 'UserAgent Contract',
+        mustExist: 'pointer position/velocity, focus, selection, scroll, reduced-motion flag',
+        mayMutate: 'nothing in the DOM — it projects a field source the engine consumes',
+        sideEffectFree: 'the source it derives from its input state',
+        testable: 'pointer creates a wake; focus creates an accessible attention source; reduced motion drops travel',
+        inspectable: 'the derived UserFieldSource (wake / focus / capture)',
+    },
+    {
+        name: 'LayoutAgent Contract',
+        mustExist: 'a region rect + the metrics aggregated over the bodies inside it',
+        mayMutate: 'its own aggregated metrics (then writes back like an ElementAgent)',
+        sideEffectFree: 'the aggregation',
+        testable: 'aggregates contained body metrics; empty region reads zero',
+        inspectable: 'the region rect and aggregated metrics',
+    },
+    {
+        name: 'DataAgent Contract',
+        mustExist: 'a record’s semantic fields + a salience that decays unless reinforced',
+        mayMutate: 'its own salience',
+        sideEffectFree: 'the salience update is a pure function of (reinforced, dt)',
+        testable: 'reinforce raises salience; idle decays it; bounded to [0,1]',
+        inspectable: 'the record fields and current salience',
+    },
+    {
+        name: 'EventAgent Contract',
+        mustExist: 'a metric, an enter/exit threshold with hysteresis, and a debounce window',
+        mayMutate: 'nothing — it emits notifications',
+        sideEffectFree: 'the edge detection is a pure function of (value, now)',
+        testable: 'one clean edge per crossing; no per-frame firing; hysteresis prevents flicker',
+        inspectable: 'the lit state and the configured thresholds',
+    },
+];
+//# sourceMappingURL=index.js.map

package/dist/agents/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAQA,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AAYnC,gFAAgF;AAChF,MAAM,CAAC,MAAM,eAAe,GAA4B;IACtD;QACE,IAAI,EAAE,uBAAuB;QAC7B,SAAS,EAAE,oHAAoH;QAC/H,SAAS,EAAE,qDAAqD;QAChE,cAAc,EAAE,0EAA0E;QAC1F,QAAQ,EAAE,+FAA+F;QACzG,WAAW,EAAE,8DAA8D;KAC5E;IACD;QACE,IAAI,EAAE,4BAA4B;QAClC,SAAS,EAAE,uDAAuD;QAClE,SAAS,EAAE,mFAAmF;QAC9F,cAAc,EAAE,2DAA2D;QAC3E,QAAQ,EAAE,uFAAuF;QACjG,WAAW,EAAE,mEAAmE;KACjF;IACD;QACE,IAAI,EAAE,oBAAoB;QAC1B,SAAS,EAAE,0EAA0E;QACrF,SAAS,EAAE,qEAAqE;QAChF,cAAc,EAAE,4CAA4C;QAC5D,QAAQ,EAAE,mGAAmG;QAC7G,WAAW,EAAE,sDAAsD;KACpE;IACD;QACE,IAAI,EAAE,sBAAsB;QAC5B,SAAS,EAAE,kEAAkE;QAC7E,SAAS,EAAE,oEAAoE;QAC/E,cAAc,EAAE,iBAAiB;QACjC,QAAQ,EAAE,4DAA4D;QACtE,WAAW,EAAE,wCAAwC;KACtD;IACD;QACE,IAAI,EAAE,oBAAoB;QAC1B,SAAS,EAAE,uEAAuE;QAClF,SAAS,EAAE,kBAAkB;QAC7B,cAAc,EAAE,4DAA4D;QAC5E,QAAQ,EAAE,6DAA6D;QACvE,WAAW,EAAE,wCAAwC;KACtD;IACD;QACE,IAAI,EAAE,qBAAqB;QAC3B,SAAS,EAAE,0EAA0E;QACrF,SAAS,EAAE,kCAAkC;QAC7C,cAAc,EAAE,uDAAuD;QACvE,QAAQ,EAAE,+EAA+E;QACzF,WAAW,EAAE,6CAA6C;KAC3D;CACF,CAAC"}

package/dist/agents/region-agents.d.ts

@@ -0,0 +1,40 @@
+/**
+ * LayoutAgent and DataAgent (interaction-and-relationship-model) — the region-level and
+ * record-level field participants. A LayoutAgent is a viewport region that aggregates the field
+ * metrics under it (so a whole column or card can respond, not just leaf elements). A DataAgent is
+ * a semantic record placed in the field, carrying a salience that decays unless reinforced.
+ *
+ * Pure aggregation/decay, node-testable. Rendering and DOM binding live in the field loop.
+ */
+import type { ElementMetrics } from './element-agent.ts';
+export interface LayoutAgent {
+    id: string;
+    /** the region in field space. */
+    rect: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    /** aggregated metrics over the bodies inside the region. */
+    metrics: ElementMetrics;
+}
+/**
+ * Aggregate a metric across the bodies whose centre falls in the region (mean of the contained
+ * values). Returns 0 for an empty region. Pure.
+ */
+export declare function aggregateMetric(region: LayoutAgent, bodies: readonly {
+    cx: number;
+    cy: number;
+    value: number;
+}[]): number;
+export interface DataAgent {
+    id: string;
+    /** arbitrary semantic fields of the record. */
+    fields: Readonly<Record<string, unknown>>;
+    /** attention/relevance ∈ [0,1] — decays unless reinforced. */
+    salience: number;
+}
+/** Reinforce (matched a query / was viewed) or let salience decay. Pure. */
+export declare function updateDataAgent(d: DataAgent, reinforced: boolean, dt: number, decay?: number, gain?: number): void;
+//# sourceMappingURL=region-agents.d.ts.map

package/dist/agents/region-agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"region-agents.d.ts","sourceRoot":"","sources":["../../src/agents/region-agents.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAGzD,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,iCAAiC;IACjC,IAAI,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACrD,4DAA4D;IAC5D,OAAO,EAAE,cAAc,CAAC;CACzB;AAKD;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,GAC3D,MAAM,CAUR;AAGD,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,+CAA+C;IAC/C,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1C,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAID,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,SAAM,EAAE,IAAI,SAAM,GAAG,IAAI,CAE5G"}

package/dist/agents/region-agents.js

@@ -0,0 +1,22 @@
+const inRect = (r, x, y) => x >= r.x && x <= r.x + r.w && y >= r.y && y <= r.y + r.h;
+/**
+ * Aggregate a metric across the bodies whose centre falls in the region (mean of the contained
+ * values). Returns 0 for an empty region. Pure.
+ */
+export function aggregateMetric(region, bodies) {
+    let sum = 0;
+    let n = 0;
+    for (const b of bodies) {
+        if (inRect(region.rect, b.cx, b.cy)) {
+            sum += b.value;
+            n++;
+        }
+    }
+    return n === 0 ? 0 : sum / n;
+}
+const clamp01 = (n) => (n < 0 ? 0 : n > 1 ? 1 : n);
+/** Reinforce (matched a query / was viewed) or let salience decay. Pure. */
+export function updateDataAgent(d, reinforced, dt, decay = 0.4, gain = 1.2) {
+    d.salience = clamp01(d.salience + (reinforced ? gain : -decay) * dt);
+}
+//# sourceMappingURL=region-agents.js.map

package/dist/agents/region-agents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"region-agents.js","sourceRoot":"","sources":["../../src/agents/region-agents.ts"],"names":[],"mappings":"AAmBA,MAAM,MAAM,GAAG,CAAC,CAAsB,EAAE,CAAS,EAAE,CAAS,EAAW,EAAE,CACvE,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAE3D;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAmB,EACnB,MAA4D;IAE5D,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;YACpC,GAAG,IAAI,CAAC,CAAC,KAAK,CAAC;YACf,CAAC,EAAE,CAAC;QACN,CAAC;IACH,CAAC;IACD,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC;AAC/B,CAAC;AAWD,MAAM,OAAO,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAEnE,4EAA4E;AAC5E,MAAM,UAAU,eAAe,CAAC,CAAY,EAAE,UAAmB,EAAE,EAAU,EAAE,KAAK,GAAG,GAAG,EAAE,IAAI,GAAG,GAAG;IACpG,CAAC,CAAC,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC;AACvE,CAAC"}

package/dist/agents/relationship.d.ts

@@ -0,0 +1,55 @@
+/**
+ * RelationshipAgent (system-contracts §7) — an active connection between two bodies. It is not
+ * merely a rendered line: it carries strength, tension, and memory; it strengthens with use and
+ * decays over time; it can transfer attention and emit thresholded events.
+ *
+ * The dynamics here are pure (plain state + dt), so they are deterministic and node-testable. The
+ * rendering (a line, a current) and the DOM event dispatch live in the field loop / feedback layer.
+ */
+import { Thresholder } from './event-agent.ts';
+export interface RelationshipAgent {
+    id: string;
+    /** body ids. */
+    from: string;
+    to: string;
+    /** relationship kind, e.g. 'cites', 'reply', 'depends'. */
+    type: string;
+    /** active coupling strength ∈ [0,1]. */
+    strength: number;
+    /** instantaneous strain ∈ [0,1] (e.g. distance vs. desired). */
+    tension: number;
+    /** slow-moving accumulated familiarity ∈ [0,1]. */
+    memory: number;
+    /** whether it was used this tick. */
+    active: boolean;
+}
+export interface RelationshipDynamics {
+    /** strength gained per second while active. */
+    strengthen: number;
+    /** strength lost per second while idle. */
+    decay: number;
+    /** memory gained per second while active (lost at half-rate while idle). */
+    remember: number;
+}
+export declare const DEFAULT_RELATIONSHIP_DYNAMICS: RelationshipDynamics;
+/**
+ * Advance a relationship one step. `active` is whether it was exercised this tick (a click, a
+ * traversal, attention flowing across it); `tension` is the current strain. Strengthens toward 1
+ * while active, decays toward 0 while idle, and memory follows more slowly — so a long-used
+ * relationship stays warm after a pause, while a one-off fades.
+ */
+export declare function updateRelationship(r: RelationshipAgent, active: boolean, tension: number, dt: number, dyn?: RelationshipDynamics): void;
+/**
+ * Attention transferred across a relationship: a fraction of the source body's attention flows to
+ * the target, scaled by the live strength. Pure — returns the amount to add at `to` and remove at
+ * `from` (the caller applies it, conserving the budget).
+ */
+export declare function attentionTransfer(r: RelationshipAgent, fromAttention: number, rate?: number): number;
+/** A relationship paired with a strength thresholder, for `field:relationship-strengthened` events. */
+export interface WatchedRelationship {
+    agent: RelationshipAgent;
+    threshold: Thresholder;
+}
+/** Build a watched relationship with a sensible strengthen/weaken threshold. */
+export declare function watchRelationship(agent: RelationshipAgent, debounceMs?: number): WatchedRelationship;
+//# sourceMappingURL=relationship.d.ts.map

package/dist/agents/relationship.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship.d.ts","sourceRoot":"","sources":["../../src/agents/relationship.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,gBAAgB;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,eAAO,MAAM,6BAA6B,EAAE,oBAI3C,CAAC;AAIF;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,CAAC,EAAE,iBAAiB,EACpB,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,MAAM,EACf,EAAE,EAAE,MAAM,EACV,GAAG,GAAE,oBAAoD,GACxD,IAAI,CAKN;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,EAAE,IAAI,SAAO,GAAG,MAAM,CAElG;AAED,uGAAuG;AACvG,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,iBAAiB,CAAC;IACzB,SAAS,EAAE,WAAW,CAAC;CACxB;AAED,gFAAgF;AAChF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,iBAAiB,EAAE,UAAU,SAAM,GAAG,mBAAmB,CAEjG"}