@fundamental-engine/dom 0.7.0

package/dist/overlays.d.ts

@@ -0,0 +1,48 @@
+/**
+ * OverlayRegistry — visual relationship lines, field lines, callouts, and debug layers, without
+ * corrupting semantic DOM. Overlays are *render layers*: they read from the relationship + measurement
+ * registries and produce geometry to draw. They do not own relationships and never mutate physics.
+ */
+import type { MeasurementRegistry } from './measurement.ts';
+import type { CoordinateSpace } from './types.ts';
+export type OverlayType = 'relationship' | 'field-line' | 'debug' | 'callout' | 'attention' | 'heatmap';
+export type RenderTarget = 'css' | 'svg' | 'canvas' | 'dom';
+export interface FieldOverlay {
+    id: string;
+    type: OverlayType;
+    /** the elements this overlay connects/annotates (e.g. [from, to] for a relationship line). */
+    sourceElements: Element[];
+    coordinateSpace: CoordinateSpace;
+    renderTarget: RenderTarget;
+    interactive: boolean;
+}
+/** A resolved segment to draw, in the overlay's coordinate space. */
+export interface OverlaySegment {
+    overlay: FieldOverlay;
+    from: {
+        x: number;
+        y: number;
+    };
+    to: {
+        x: number;
+        y: number;
+    };
+}
+export declare class OverlayRegistry {
+    private readonly overlays;
+    private seq;
+    /** Register an overlay (a render record — owns no relationship, mutates no physics). */
+    add(o: Omit<FieldOverlay, 'id' | 'coordinateSpace' | 'renderTarget' | 'interactive'> & Partial<FieldOverlay>): FieldOverlay;
+    remove(id: string): void;
+    /** Drop overlays referencing a detached source element — they can never resolve again, and their
+     *  strong Element refs would otherwise pin removed subtrees alive. Run on a cadence by a frame loop. */
+    prune(): void;
+    all(): FieldOverlay[];
+    /**
+     * Resolve connection overlays (relationship/callout) into segments between the centres of their
+     * two source elements, using a measurement snapshot. Overlays whose endpoints aren't measured are
+     * skipped. Pure given the measurement registry — no drawing here.
+     */
+    resolveSegments(measure: MeasurementRegistry): OverlaySegment[];
+}
+//# sourceMappingURL=overlays.d.ts.map

package/dist/overlays.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlays.d.ts","sourceRoot":"","sources":["../src/overlays.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,MAAM,MAAM,WAAW,GAAG,cAAc,GAAG,YAAY,GAAG,OAAO,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,CAAC;AACxG,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,KAAK,GAAG,QAAQ,GAAG,KAAK,CAAC;AAE5D,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,WAAW,CAAC;IAClB,8FAA8F;IAC9F,cAAc,EAAE,OAAO,EAAE,CAAC;IAC1B,eAAe,EAAE,eAAe,CAAC;IACjC,YAAY,EAAE,YAAY,CAAC;IAC3B,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,qEAAqE;AACrE,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,YAAY,CAAC;IACtB,IAAI,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/B,EAAE,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9B;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmC;IAC5D,OAAO,CAAC,GAAG,CAAK;IAEhB,wFAAwF;IACxF,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,IAAI,GAAG,iBAAiB,GAAG,cAAc,GAAG,aAAa,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY;IAY3H,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAIxB;4GACwG;IACxG,KAAK,IAAI,IAAI;IAKb,GAAG,IAAI,YAAY,EAAE;IAIrB;;;;OAIG;IACH,eAAe,CAAC,OAAO,EAAE,mBAAmB,GAAG,cAAc,EAAE;CAWhE"}

package/dist/overlays.js

@@ -0,0 +1,48 @@
+export class OverlayRegistry {
+    overlays = new Map();
+    seq = 0;
+    /** Register an overlay (a render record — owns no relationship, mutates no physics). */
+    add(o) {
+        const full = {
+            coordinateSpace: 'field-root',
+            renderTarget: 'svg',
+            interactive: false,
+            ...o,
+            id: o.id ?? `overlay-${this.seq++}`,
+        };
+        this.overlays.set(full.id, full);
+        return full;
+    }
+    remove(id) {
+        this.overlays.delete(id);
+    }
+    /** Drop overlays referencing a detached source element — they can never resolve again, and their
+     *  strong Element refs would otherwise pin removed subtrees alive. Run on a cadence by a frame loop. */
+    prune() {
+        for (const [id, o] of this.overlays)
+            if (o.sourceElements.some((el) => el.isConnected === false))
+                this.overlays.delete(id);
+    }
+    all() {
+        return [...this.overlays.values()];
+    }
+    /**
+     * Resolve connection overlays (relationship/callout) into segments between the centres of their
+     * two source elements, using a measurement snapshot. Overlays whose endpoints aren't measured are
+     * skipped. Pure given the measurement registry — no drawing here.
+     */
+    resolveSegments(measure) {
+        const segs = [];
+        for (const o of this.overlays.values()) {
+            if (o.sourceElements.length < 2)
+                continue;
+            const a = measure.for(o.sourceElements[0]);
+            const b = measure.for(o.sourceElements[1]);
+            if (!a || !b)
+                continue;
+            segs.push({ overlay: o, from: { x: a.rect.cx, y: a.rect.cy }, to: { x: b.rect.cx, y: b.rect.cy } });
+        }
+        return segs;
+    }
+}
+//# sourceMappingURL=overlays.js.map

package/dist/overlays.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlays.js","sourceRoot":"","sources":["../src/overlays.ts"],"names":[],"mappings":"AA4BA,MAAM,OAAO,eAAe;IACT,QAAQ,GAAG,IAAI,GAAG,EAAwB,CAAC;IACpD,GAAG,GAAG,CAAC,CAAC;IAEhB,wFAAwF;IACxF,GAAG,CAAC,CAAwG;QAC1G,MAAM,IAAI,GAAiB;YACzB,eAAe,EAAE,YAAY;YAC7B,YAAY,EAAE,KAAK;YACnB,WAAW,EAAE,KAAK;YAClB,GAAG,CAAC;YACJ,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,WAAW,IAAI,CAAC,GAAG,EAAE,EAAE;SACpC,CAAC;QACF,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QACjC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,CAAC,EAAU;QACf,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC3B,CAAC;IAED;4GACwG;IACxG,KAAK;QACH,KAAK,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC,QAAQ;YACjC,IAAI,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,WAAW,KAAK,KAAK,CAAC;gBAAE,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC1F,CAAC;IAED,GAAG;QACD,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACrC,CAAC;IAED;;;;OAIG;IACH,eAAe,CAAC,OAA4B;QAC1C,MAAM,IAAI,GAAqB,EAAE,CAAC;QAClC,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;YACvC,IAAI,CAAC,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC;gBAAE,SAAS;YAC1C,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAE,CAAC,CAAC;YAC5C,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAE,CAAC,CAAC;YAC5C,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;gBAAE,SAAS;YACvB,IAAI,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QACtG,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/perf.d.ts

@@ -0,0 +1,62 @@
+/**
+ * FieldPerf — the frame-duration split of the performance-budget story: pure timing math
+ * lifted from the site's DataConsole prototype (which had been running these exact rules in
+ * production). Core's `inspectBudget`/`DEFAULT_BUDGET` judge a *configuration*; the
+ * QualityGovernor turns sustained overruns into a degradation *tier*; FieldPerf is the
+ * *measurement* — feed it rAF timestamps, read back fps / budget / percentiles / dropped.
+ *
+ * The lifted rules (byte-compatible with the DataConsole, so its conversion is
+ * behavior-identical):
+ *   - deltas: consecutive `feed(ts)` differences, kept in a rolling window (default 180).
+ *   - DISCONTINUITY: a gap > 500 ms (tab switch, system sleep) is ignored entirely — it
+ *     enters neither the window, the budget seed, `frames`, nor `dropped`; timing simply
+ *     resumes from the new timestamp (the QualityGovernor's "skip discontinuity frames"
+ *     doctrine, given a concrete constant here).
+ *   - percentile `pct(arr, p)`: nearest-rank-by-floor on the ascending sort —
+ *     `sorted[Math.floor((p / 100) * (sorted.length - 1))]`; `null` when empty.
+ *   - BUDGET DETECTION: the median (`pct(seed, 50)`) of the first `budgetSeed` (default 30)
+ *     clean deltas — "clean" = past the discontinuity filter. Until the seed fills,
+ *     `budgetMs` is `null` and nothing counts as dropped.
+ *   - DROPPED: once the budget exists, a delta strictly greater than `budget × 1.5`
+ *     increments `dropped` (cumulative, not windowed). The seed-completing delta is itself
+ *     checked in the same feed — the DataConsole's exact ordering.
+ *   - fps: `Math.round(1000 / medianMs)` over the current window; `null` while empty.
+ *   - `frames`: total clean deltas ever counted (not capped by the window).
+ *
+ * Pure and host-driven by design: NO `requestAnimationFrame` of its own (callers feed their
+ * loop's timestamps) and NO PerformanceObserver — the LoAF / long-task split stays page-side
+ * in this slice (the DataConsole keeps its own observer; a platform LoAF lane is future work).
+ */
+export interface FieldPerfOptions {
+    /** rolling delta-window size (default 180 — the DataConsole's ~3 s at 60 Hz). Min 1. */
+    window?: number;
+    /** number of clean deltas used to detect the frame budget (default 30); the budget is their median. Min 1. */
+    budgetSeed?: number;
+}
+export interface FieldPerfSnapshot {
+    /** `Math.round(1000 / medianMs)`; `null` until a delta exists. */
+    fps: number | null;
+    /** the detected frame budget (median of the seed deltas); `null` until the seed fills. */
+    budgetMs: number | null;
+    /** windowed median delta (`pct(deltas, 50)`); `null` while empty. */
+    medianMs: number | null;
+    /** windowed 95th-percentile delta; `null` while empty. */
+    p95Ms: number | null;
+    /** windowed 99th-percentile delta; `null` while empty. */
+    p99Ms: number | null;
+    /** cumulative deltas > budget × 1.5 since creation/reset (0 until the budget is detected). */
+    dropped: number;
+    /** total clean deltas counted since creation/reset (not capped by the window). */
+    frames: number;
+}
+export interface FieldPerf {
+    /** Feed one rAF timestamp (ms). Deltas are computed internally; gaps > 500 ms are ignored (discontinuity). */
+    feed(frameTs: number): void;
+    /** Read the current numbers (pure — no layout, no globals). */
+    snapshot(): FieldPerfSnapshot;
+    /** Forget everything: window, seed, budget, counters, and the last timestamp. */
+    reset(): void;
+}
+/** Create a frame-duration meter. Feed it rAF timestamps; read `snapshot()` whenever. */
+export declare function createFieldPerf(opts?: FieldPerfOptions): FieldPerf;
+//# sourceMappingURL=perf.d.ts.map

package/dist/perf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"perf.d.ts","sourceRoot":"","sources":["../src/perf.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,wFAAwF;IACxF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8GAA8G;IAC9G,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,0FAA0F;IAC1F,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,qEAAqE;IACrE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,0DAA0D;IAC1D,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,0DAA0D;IAC1D,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,8FAA8F;IAC9F,OAAO,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,SAAS;IACxB,8GAA8G;IAC9G,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,+DAA+D;IAC/D,QAAQ,IAAI,iBAAiB,CAAC;IAC9B,iFAAiF;IACjF,KAAK,IAAI,IAAI,CAAC;CACf;AAYD,yFAAyF;AACzF,wBAAgB,eAAe,CAAC,IAAI,GAAE,gBAAqB,GAAG,SAAS,CAyDtE"}

package/dist/perf.js

@@ -0,0 +1,94 @@
+/**
+ * FieldPerf — the frame-duration split of the performance-budget story: pure timing math
+ * lifted from the site's DataConsole prototype (which had been running these exact rules in
+ * production). Core's `inspectBudget`/`DEFAULT_BUDGET` judge a *configuration*; the
+ * QualityGovernor turns sustained overruns into a degradation *tier*; FieldPerf is the
+ * *measurement* — feed it rAF timestamps, read back fps / budget / percentiles / dropped.
+ *
+ * The lifted rules (byte-compatible with the DataConsole, so its conversion is
+ * behavior-identical):
+ *   - deltas: consecutive `feed(ts)` differences, kept in a rolling window (default 180).
+ *   - DISCONTINUITY: a gap > 500 ms (tab switch, system sleep) is ignored entirely — it
+ *     enters neither the window, the budget seed, `frames`, nor `dropped`; timing simply
+ *     resumes from the new timestamp (the QualityGovernor's "skip discontinuity frames"
+ *     doctrine, given a concrete constant here).
+ *   - percentile `pct(arr, p)`: nearest-rank-by-floor on the ascending sort —
+ *     `sorted[Math.floor((p / 100) * (sorted.length - 1))]`; `null` when empty.
+ *   - BUDGET DETECTION: the median (`pct(seed, 50)`) of the first `budgetSeed` (default 30)
+ *     clean deltas — "clean" = past the discontinuity filter. Until the seed fills,
+ *     `budgetMs` is `null` and nothing counts as dropped.
+ *   - DROPPED: once the budget exists, a delta strictly greater than `budget × 1.5`
+ *     increments `dropped` (cumulative, not windowed). The seed-completing delta is itself
+ *     checked in the same feed — the DataConsole's exact ordering.
+ *   - fps: `Math.round(1000 / medianMs)` over the current window; `null` while empty.
+ *   - `frames`: total clean deltas ever counted (not capped by the window).
+ *
+ * Pure and host-driven by design: NO `requestAnimationFrame` of its own (callers feed their
+ * loop's timestamps) and NO PerformanceObserver — the LoAF / long-task split stays page-side
+ * in this slice (the DataConsole keeps its own observer; a platform LoAF lane is future work).
+ */
+/** A gap above this (ms) is a discontinuity — tab switch / sleep — and is skipped, not measured. */
+const DISCONTINUITY_MS = 500;
+/** Nearest-rank-by-floor percentile on a copy (the DataConsole's `pct`). `null` when empty. */
+function pct(arr, p) {
+    if (!arr.length)
+        return null;
+    const s = [...arr].sort((a, b) => a - b);
+    return s[Math.floor((p / 100) * (s.length - 1))];
+}
+/** Create a frame-duration meter. Feed it rAF timestamps; read `snapshot()` whenever. */
+export function createFieldPerf(opts = {}) {
+    const windowSize = Math.max(1, Math.floor(opts.window ?? 180));
+    const seedSize = Math.max(1, Math.floor(opts.budgetSeed ?? 30));
+    let lastTs = null;
+    let deltas = [];
+    let seed = [];
+    let budget = null;
+    let dropped = 0;
+    let frames = 0;
+    const feed = (frameTs) => {
+        if (lastTs === null) {
+            lastTs = frameTs;
+            return;
+        }
+        const d = frameTs - lastTs;
+        lastTs = frameTs;
+        if (d > DISCONTINUITY_MS)
+            return; // discontinuity: resume from the new timestamp, count nothing
+        deltas.push(d);
+        if (deltas.length > windowSize)
+            deltas.shift();
+        frames++;
+        // detect the budget from the first `seedSize` clean deltas (median)
+        if (budget === null && seed.length < seedSize) {
+            seed.push(d);
+            if (seed.length === seedSize)
+                budget = pct(seed, 50);
+        }
+        // the seed-completing delta is checked too — the DataConsole's exact ordering
+        if (budget !== null && d > budget * 1.5)
+            dropped++;
+    };
+    const snapshot = () => {
+        const medianMs = pct(deltas, 50);
+        return {
+            fps: medianMs ? Math.round(1000 / medianMs) : null,
+            budgetMs: budget,
+            medianMs,
+            p95Ms: pct(deltas, 95),
+            p99Ms: pct(deltas, 99),
+            dropped,
+            frames,
+        };
+    };
+    const reset = () => {
+        lastTs = null;
+        deltas = [];
+        seed = [];
+        budget = null;
+        dropped = 0;
+        frames = 0;
+    };
+    return { feed, snapshot, reset };
+}
+//# sourceMappingURL=perf.js.map

package/dist/perf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"perf.js","sourceRoot":"","sources":["../src/perf.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAmCH,oGAAoG;AACpG,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAE7B,+FAA+F;AAC/F,SAAS,GAAG,CAAC,GAAsB,EAAE,CAAS;IAC5C,IAAI,CAAC,GAAG,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IAC7B,MAAM,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACzC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;AACpD,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,eAAe,CAAC,OAAyB,EAAE;IACzD,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC;IAC/D,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,CAAC;IAEhE,IAAI,MAAM,GAAkB,IAAI,CAAC;IACjC,IAAI,MAAM,GAAa,EAAE,CAAC;IAC1B,IAAI,IAAI,GAAa,EAAE,CAAC;IACxB,IAAI,MAAM,GAAkB,IAAI,CAAC;IACjC,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,MAAM,GAAG,CAAC,CAAC;IAEf,MAAM,IAAI,GAAG,CAAC,OAAe,EAAQ,EAAE;QACrC,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YACpB,MAAM,GAAG,OAAO,CAAC;YACjB,OAAO;QACT,CAAC;QACD,MAAM,CAAC,GAAG,OAAO,GAAG,MAAM,CAAC;QAC3B,MAAM,GAAG,OAAO,CAAC;QACjB,IAAI,CAAC,GAAG,gBAAgB;YAAE,OAAO,CAAC,8DAA8D;QAEhG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACf,IAAI,MAAM,CAAC,MAAM,GAAG,UAAU;YAAE,MAAM,CAAC,KAAK,EAAE,CAAC;QAC/C,MAAM,EAAE,CAAC;QAET,oEAAoE;QACpE,IAAI,MAAM,KAAK,IAAI,IAAI,IAAI,CAAC,MAAM,GAAG,QAAQ,EAAE,CAAC;YAC9C,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACb,IAAI,IAAI,CAAC,MAAM,KAAK,QAAQ;gBAAE,MAAM,GAAG,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACvD,CAAC;QAED,8EAA8E;QAC9E,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,GAAG,MAAM,GAAG,GAAG;YAAE,OAAO,EAAE,CAAC;IACrD,CAAC,CAAC;IAEF,MAAM,QAAQ,GAAG,GAAsB,EAAE;QACvC,MAAM,QAAQ,GAAG,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACjC,OAAO;YACL,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI;YAClD,QAAQ,EAAE,MAAM;YAChB,QAAQ;YACR,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC;YACtB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC;YACtB,OAAO;YACP,MAAM;SACP,CAAC;IACJ,CAAC,CAAC;IAEF,MAAM,KAAK,GAAG,GAAS,EAAE;QACvB,MAAM,GAAG,IAAI,CAAC;QACd,MAAM,GAAG,EAAE,CAAC;QACZ,IAAI,GAAG,EAAE,CAAC;QACV,MAAM,GAAG,IAAI,CAAC;QACd,OAAO,GAAG,CAAC,CAAC;QACZ,MAAM,GAAG,CAAC,CAAC;IACb,CAAC,CAAC;IAEF,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;AACnC,CAAC"}

package/dist/platform.d.ts

@@ -0,0 +1,40 @@
+/**
+ * createFieldPlatform — the coordinator that binds the platform registries to one shared
+ * FrameScheduler. The native participation surface Fundamental wishes the browser exposed.
+ *
+ * The scheduler owns loop discipline: every frame walks discover → read → compute → state → write →
+ * render in order (see schedule.ts). By default the platform wires the two phases the registries own
+ * outright — `read` (MeasurementRegistry) and `write` (FeedbackRegistry) — and installs the read
+ * guard so an off-phase measurement is caught. Callers add `discover`/`compute`/`state`/`render`
+ * handlers with `platform.on(phase, fn)`; relationships, visual bindings, and overlays plug into
+ * those. The shape is additive — adding handlers never reorders the core read→write spine.
+ */
+import { MeasurementRegistry } from './measurement.ts';
+import { StateRegistry } from './state.ts';
+import { FeedbackRegistry } from './feedback.ts';
+import { RelationshipRegistry } from './relationships.ts';
+import { VisualBindingRegistry } from './visual-bindings.ts';
+import { OverlayRegistry } from './overlays.ts';
+import { FrameScheduler } from './schedule.ts';
+import type { Phase, PhaseHandler, FrameReport, SchedulerOptions } from './schedule.ts';
+import type { Viewport } from './types.ts';
+export interface FieldPlatform {
+    /** the platform root (a `<field-root>`, an article, or the document element). */
+    root: Element;
+    measure: MeasurementRegistry;
+    state: StateRegistry;
+    feedback: FeedbackRegistry;
+    relationships: RelationshipRegistry;
+    visuals: VisualBindingRegistry;
+    overlays: OverlayRegistry;
+    /** the shared frame scheduler driving the six-phase loop. */
+    scheduler: FrameScheduler;
+    /** register a phase handler (discover/compute/state/render are open for callers). Returns unsubscribe. */
+    on(phase: Phase, handler: PhaseHandler): () => void;
+    /** run one full six-phase frame; returns the per-frame report (phases run + any violations). */
+    tick(now?: number, viewport?: Viewport): FrameReport;
+}
+export interface PlatformOptions extends SchedulerOptions {
+}
+export declare function createFieldPlatform(root: Element, opts?: PlatformOptions): FieldPlatform;
+//# sourceMappingURL=platform.d.ts.map

package/dist/platform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACxF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,MAAM,WAAW,aAAa;IAC5B,iFAAiF;IACjF,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,mBAAmB,CAAC;IAC7B,KAAK,EAAE,aAAa,CAAC;IACrB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,aAAa,EAAE,oBAAoB,CAAC;IACpC,OAAO,EAAE,qBAAqB,CAAC;IAC/B,QAAQ,EAAE,eAAe,CAAC;IAC1B,6DAA6D;IAC7D,SAAS,EAAE,cAAc,CAAC;IAC1B,0GAA0G;IAC1G,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,YAAY,GAAG,MAAM,IAAI,CAAC;IACpD,gGAAgG;IAChG,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,QAAQ,GAAG,WAAW,CAAC;CACtD;AAED,MAAM,WAAW,eAAgB,SAAQ,gBAAgB;CAAG;AAE5D,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,GAAE,eAAoB,GAAG,aAAa,CA8C5F"}

package/dist/platform.js

@@ -0,0 +1,61 @@
+/**
+ * createFieldPlatform — the coordinator that binds the platform registries to one shared
+ * FrameScheduler. The native participation surface Fundamental wishes the browser exposed.
+ *
+ * The scheduler owns loop discipline: every frame walks discover → read → compute → state → write →
+ * render in order (see schedule.ts). By default the platform wires the two phases the registries own
+ * outright — `read` (MeasurementRegistry) and `write` (FeedbackRegistry) — and installs the read
+ * guard so an off-phase measurement is caught. Callers add `discover`/`compute`/`state`/`render`
+ * handlers with `platform.on(phase, fn)`; relationships, visual bindings, and overlays plug into
+ * those. The shape is additive — adding handlers never reorders the core read→write spine.
+ */
+import { MeasurementRegistry } from "./measurement.js";
+import { StateRegistry } from "./state.js";
+import { FeedbackRegistry } from "./feedback.js";
+import { RelationshipRegistry } from "./relationships.js";
+import { VisualBindingRegistry } from "./visual-bindings.js";
+import { OverlayRegistry } from "./overlays.js";
+import { FrameScheduler } from "./schedule.js";
+export function createFieldPlatform(root, opts = {}) {
+    const measure = new MeasurementRegistry();
+    const state = new StateRegistry();
+    const feedback = new FeedbackRegistry();
+    const relationships = new RelationshipRegistry();
+    const visuals = new VisualBindingRegistry();
+    const overlays = new OverlayRegistry();
+    const scheduler = new FrameScheduler({ strict: opts.strict ?? false });
+    // read-phase discipline: measurement consults the scheduler before reading layout.
+    measure.setPhaseGuard(scheduler.readGuard());
+    // Body Matter Interaction, Bound Visual tier: source→visual state mirroring is the platform
+    // default — a scanned representation/measurement visual receives its source's feedback channels
+    // (--d / --load / the metrics) without the author wiring anything. Change-gated; see
+    // visual-bindings.ts MIRRORED_CHANNELS.
+    visuals.setMirroring(true);
+    // the two phases the registries own outright. Everything else is opt-in via platform.on(...).
+    scheduler.on('read', (ctx) => measure.measure(ctx.now, ctx.viewport));
+    scheduler.on('write', (ctx) => feedback.flush(state, ctx.now));
+    // staleness sweep: the StateRegistry and OverlayRegistry both hold strong Element refs with no
+    // natural prune moment — the feedback sink writes --lit/--d/--load onto every body every frame,
+    // and overlays pin their source elements — yet nothing deletes an entry when its element leaves
+    // the DOM. Run their prune on a low cadence (every 120th frame ≈ 2s) to release detached
+    // elements for GC. Iterating an empty registry is free, so the sweep is cheap when idle.
+    scheduler.on('write', (ctx) => {
+        if (ctx.frame % 120 === 0) {
+            state.prune();
+            overlays.prune();
+        }
+    });
+    return {
+        root,
+        measure,
+        state,
+        feedback,
+        relationships,
+        visuals,
+        overlays,
+        scheduler,
+        on: (phase, handler) => scheduler.on(phase, handler),
+        tick: (now = 0, viewport) => scheduler.runFrame(now, viewport),
+    };
+}
+//# sourceMappingURL=platform.js.map

package/dist/platform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.js","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAuB/C,MAAM,UAAU,mBAAmB,CAAC,IAAa,EAAE,OAAwB,EAAE;IAC3E,MAAM,OAAO,GAAG,IAAI,mBAAmB,EAAE,CAAC;IAC1C,MAAM,KAAK,GAAG,IAAI,aAAa,EAAE,CAAC;IAClC,MAAM,QAAQ,GAAG,IAAI,gBAAgB,EAAE,CAAC;IACxC,MAAM,aAAa,GAAG,IAAI,oBAAoB,EAAE,CAAC;IACjD,MAAM,OAAO,GAAG,IAAI,qBAAqB,EAAE,CAAC;IAC5C,MAAM,QAAQ,GAAG,IAAI,eAAe,EAAE,CAAC;IACvC,MAAM,SAAS,GAAG,IAAI,cAAc,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,KAAK,EAAE,CAAC,CAAC;IAEvE,mFAAmF;IACnF,OAAO,CAAC,aAAa,CAAC,SAAS,CAAC,SAAS,EAAE,CAAC,CAAC;IAE7C,4FAA4F;IAC5F,gGAAgG;IAChG,qFAAqF;IACrF,wCAAwC;IACxC,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;IAE3B,8FAA8F;IAC9F,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC;IACtE,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IAE/D,+FAA+F;IAC/F,gGAAgG;IAChG,gGAAgG;IAChG,yFAAyF;IACzF,yFAAyF;IACzF,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;QAC5B,IAAI,GAAG,CAAC,KAAK,GAAG,GAAG,KAAK,CAAC,EAAE,CAAC;YAC1B,KAAK,CAAC,KAAK,EAAE,CAAC;YACd,QAAQ,CAAC,KAAK,EAAE,CAAC;QACnB,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO;QACL,IAAI;QACJ,OAAO;QACP,KAAK;QACL,QAAQ;QACR,aAAa;QACb,OAAO;QACP,QAAQ;QACR,SAAS;QACT,EAAE,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC;QACpD,IAAI,EAAE,CAAC,GAAG,GAAG,CAAC,EAAE,QAAmB,EAAE,EAAE,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;KAC1E,CAAC;AACJ,CAAC"}

package/dist/relationships.d.ts

@@ -0,0 +1,79 @@
+/**
+ * RelationshipRegistry — the DOM is a tree, but interfaces are graphs. This normalizes the
+ * relationships HTML/ARIA already express (`a[href#id]`, `label[for]`, `aria-controls` /
+ * `-describedby` / `-labelledby` / `-flowto`, and `data-field-relation`/`-target`) into ONE typed
+ * relationship graph, then lets authors add expressive ones on top. Native semantics are respected
+ * first; Fundamental does not invent a parallel graph for links the platform already declares.
+ *
+ * Output maps to core's `RelationshipAgent` so the field engine treats relationships as agents.
+ */
+import type { RelationshipAgent } from '@fundamental-engine/core';
+export type RelationshipSource = 'html' | 'aria' | 'data' | 'recipe' | 'runtime';
+export type RelationshipDirection = 'from-to' | 'to-from' | 'bidirectional';
+export interface FieldRelationship {
+    id: string;
+    from: Element;
+    to: Element;
+    type: string;
+    strength: number;
+    direction: RelationshipDirection;
+    confidence?: number;
+    source: RelationshipSource;
+    active: boolean;
+    memory: number;
+}
+/**
+ * A relationship an element DECLARES whose target id-ref does not resolve to an element. Tracked so
+ * resolution is real (a declared edge that points at nothing counts toward the total but not the
+ * resolved set) and so inspection can name the missing endpoint — rather than silently dropping it.
+ */
+export interface UnresolvedRelationship {
+    from: Element;
+    type: string;
+    /** the id-ref as authored (e.g. `#ghost` or `ghost`). */
+    target: string;
+    source: RelationshipSource;
+}
+/** Resolve an id-ref to an element. */
+export type Resolver = (id: string) => Element | null;
+export interface ScanResult {
+    resolved: FieldRelationship[];
+    unresolved: UnresolvedRelationship[];
+}
+/**
+ * Scan the relationships a single element declares, partitioning them into RESOLVED edges (both
+ * endpoints known) and UNRESOLVED declarations (an id-ref that points at no element). Pure given a
+ * `resolve` for id-refs, so it is testable without a document. Native relationships first;
+ * `data-field-relation` last.
+ */
+export declare function scanRelationships(el: Element, resolve: Resolver): ScanResult;
+/** The RESOLVED relationships an element declares (back-compat wrapper over {@link scanRelationships}). */
+export declare function relationshipsFromElement(el: Element, resolve: Resolver): FieldRelationship[];
+/** The DECLARED-but-UNRESOLVED relationships an element points at (targets that resolve to nothing). */
+export declare function unresolvedRelationshipsFromElement(el: Element, resolve: Resolver): UnresolvedRelationship[];
+export declare class RelationshipRegistry {
+    private readonly rels;
+    private readonly unresolvedRels;
+    /**
+     * Scan a root for native + declared relationships. Each call REPLACES the unresolved set (so
+     * previously-missing targets that have since mounted resolve on the next pass for free) and prunes
+     * resolved edges whose endpoints are no longer connected (elements removed from the DOM).
+     * Resolved edges accumulate across passes — only disconnected ones are dropped.
+     */
+    discover(root: ParentNode, resolve?: Resolver): void;
+    /**
+     * Drop all resolved and unresolved edges that touch `element` (as either endpoint). Use when an
+     * element is removed and you want immediate reclamation ahead of the next discover() pass.
+     */
+    unregister(element: Element): void;
+    /** Add an expressive relationship by hand (source defaults to `runtime`). */
+    add(r: Omit<FieldRelationship, 'id' | 'direction' | 'active' | 'memory'> & Partial<FieldRelationship>): FieldRelationship;
+    all(): FieldRelationship[];
+    get size(): number;
+    /** Declared relationships whose target id-ref resolved to no element. */
+    unresolvedAll(): UnresolvedRelationship[];
+    get unresolvedSize(): number;
+    /** Map the graph onto core `RelationshipAgent`s (endpoints keyed by element id). */
+    toAgents(): RelationshipAgent[];
+}
+//# sourceMappingURL=relationships.d.ts.map

package/dist/relationships.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationships.d.ts","sourceRoot":"","sources":["../src/relationships.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;AACjF,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,SAAS,GAAG,eAAe,CAAC;AAE5E,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,OAAO,CAAC;IACd,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,qBAAqB,CAAC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,kBAAkB,CAAC;CAC5B;AAED,uCAAuC;AACvC,MAAM,MAAM,QAAQ,GAAG,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI,CAAC;AAuBtD,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,UAAU,EAAE,sBAAsB,EAAE,CAAC;CACtC;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,GAAG,UAAU,CAmC5E;AAED,2GAA2G;AAC3G,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,GAAG,iBAAiB,EAAE,CAE5F;AAED,wGAAwG;AACxG,wBAAgB,kCAAkC,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,GAAG,sBAAsB,EAAE,CAE3G;AAED,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAwC;IAC7D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA6C;IAE5E;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,QAAQ,GAAG,IAAI;IAqBpD;;;OAGG;IACH,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IASlC,6EAA6E;IAC7E,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,iBAAiB,EAAE,IAAI,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC,GAAG,OAAO,CAAC,iBAAiB,CAAC,GAAG,iBAAiB;IAYzH,GAAG,IAAI,iBAAiB,EAAE;IAI1B,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,yEAAyE;IACzE,aAAa,IAAI,sBAAsB,EAAE;IAIzC,IAAI,cAAc,IAAI,MAAM,CAE3B;IAED,oFAAoF;IACpF,QAAQ,IAAI,iBAAiB,EAAE;CAYhC"}

package/dist/relationships.js

@@ -0,0 +1,155 @@
+// Id-less elements need a STABLE, UNIQUE fallback id. A content hash (tagName) collapsed every
+// id-less <a> onto one key, so edges keyed by `${idOf(from)}~type~${idOf(to)}` collided and
+// silently overwrote each other. A WeakMap hands out `el-<seq>` on first sight: same element → same
+// id, distinct elements → distinct ids, entries released when the element is collected.
+const fallbackIds = new WeakMap();
+let fallbackSeq = 0;
+const idOf = (el) => {
+    if (el.id)
+        return el.id;
+    let id = fallbackIds.get(el);
+    if (id === undefined)
+        fallbackIds.set(el, (id = `el-${++fallbackSeq}`));
+    return id;
+};
+function ids(attr) {
+    return (attr ?? '').split(/\s+/).filter(Boolean);
+}
+function rel(from, to, type, source, strength) {
+    return { id: `${idOf(from)}~${type}~${idOf(to)}`, from, to, type, strength, direction: 'from-to', source, active: false, memory: 0 };
+}
+/**
+ * Scan the relationships a single element declares, partitioning them into RESOLVED edges (both
+ * endpoints known) and UNRESOLVED declarations (an id-ref that points at no element). Pure given a
+ * `resolve` for id-refs, so it is testable without a document. Native relationships first;
+ * `data-field-relation` last.
+ */
+export function scanRelationships(el, resolve) {
+    const resolved = [];
+    const unresolved = [];
+    const tag = el.tagName?.toUpperCase();
+    const get = (n) => el.getAttribute(n);
+    // one declared id-ref edge: resolved if the target exists, unresolved otherwise — never dropped.
+    const edge = (idref, type, source, strength) => {
+        const id = idref.startsWith('#') ? idref.slice(1) : idref;
+        const t = resolve(id);
+        if (t)
+            resolved.push(rel(el, t, type, source, strength));
+        else
+            unresolved.push({ from: el, type, target: idref, source });
+    };
+    const href = get('href');
+    if (tag === 'A' && href && href.startsWith('#'))
+        edge(href, 'references', 'html', 0.5);
+    if (tag === 'LABEL') {
+        const f = get('for');
+        if (f)
+            edge(f, 'labels', 'html', 0.8);
+    }
+    for (const [attr, type] of [
+        ['aria-controls', 'controls'],
+        ['aria-describedby', 'describes'],
+        ['aria-labelledby', 'labelledby'],
+        ['aria-flowto', 'flowto'],
+    ]) {
+        for (const id of ids(get(attr)))
+            edge(id, type, 'aria', 0.6);
+    }
+    const declared = get('data-field-relation');
+    const target = get('data-field-target');
+    if (declared && target) {
+        const s = Number(get('data-field-strength'));
+        edge(target, declared, 'data', Number.isFinite(s) && s > 0 ? s : 0.7);
+    }
+    return { resolved, unresolved };
+}
+/** The RESOLVED relationships an element declares (back-compat wrapper over {@link scanRelationships}). */
+export function relationshipsFromElement(el, resolve) {
+    return scanRelationships(el, resolve).resolved;
+}
+/** The DECLARED-but-UNRESOLVED relationships an element points at (targets that resolve to nothing). */
+export function unresolvedRelationshipsFromElement(el, resolve) {
+    return scanRelationships(el, resolve).unresolved;
+}
+export class RelationshipRegistry {
+    rels = new Map();
+    unresolvedRels = new Map();
+    /**
+     * Scan a root for native + declared relationships. Each call REPLACES the unresolved set (so
+     * previously-missing targets that have since mounted resolve on the next pass for free) and prunes
+     * resolved edges whose endpoints are no longer connected (elements removed from the DOM).
+     * Resolved edges accumulate across passes — only disconnected ones are dropped.
+     */
+    discover(root, resolve) {
+        const r = resolve ?? ((id) => (typeof document !== 'undefined' ? document.getElementById(id) : null));
+        // prune resolved edges whose from or to element left the DOM before rescanning
+        for (const [id, rl] of this.rels) {
+            if (!rl.from.isConnected || !rl.to.isConnected)
+                this.rels.delete(id);
+        }
+        // replace the unresolved set entirely — previously-missing targets that have since mounted will
+        // now resolve, and targets that are still absent will be re-recorded fresh
+        this.unresolvedRels.clear();
+        const sel = 'a[href^="#"], label[for], [aria-controls], [aria-describedby], [aria-labelledby], [aria-flowto], [data-field-relation]';
+        root.querySelectorAll(sel).forEach((el) => {
+            const { resolved, unresolved } = scanRelationships(el, r);
+            for (const rl of resolved)
+                this.rels.set(rl.id, rl);
+            for (const u of unresolved)
+                this.unresolvedRels.set(`${idOf(u.from)}~${u.type}~${u.target}`, u);
+        });
+    }
+    /**
+     * Drop all resolved and unresolved edges that touch `element` (as either endpoint). Use when an
+     * element is removed and you want immediate reclamation ahead of the next discover() pass.
+     */
+    unregister(element) {
+        for (const [id, rl] of this.rels) {
+            if (rl.from === element || rl.to === element)
+                this.rels.delete(id);
+        }
+        for (const [key, u] of this.unresolvedRels) {
+            if (u.from === element)
+                this.unresolvedRels.delete(key);
+        }
+    }
+    /** Add an expressive relationship by hand (source defaults to `runtime`). */
+    add(r) {
+        const full = {
+            direction: 'from-to',
+            active: false,
+            memory: 0,
+            ...r,
+            id: r.id ?? `${idOf(r.from)}~${r.type}~${idOf(r.to)}`,
+        };
+        this.rels.set(full.id, full);
+        return full;
+    }
+    all() {
+        return [...this.rels.values()];
+    }
+    get size() {
+        return this.rels.size;
+    }
+    /** Declared relationships whose target id-ref resolved to no element. */
+    unresolvedAll() {
+        return [...this.unresolvedRels.values()];
+    }
+    get unresolvedSize() {
+        return this.unresolvedRels.size;
+    }
+    /** Map the graph onto core `RelationshipAgent`s (endpoints keyed by element id). */
+    toAgents() {
+        return this.all().map((r) => ({
+            id: r.id,
+            from: idOf(r.from),
+            to: idOf(r.to),
+            type: r.type,
+            strength: r.strength,
+            tension: 0,
+            memory: r.memory,
+            active: r.active,
+        }));
+    }
+}
+//# sourceMappingURL=relationships.js.map

package/dist/relationships.js.map

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