@fundamental-engine/dom 0.7.0

package/dist/lint.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Platform lint — the guardrails that keep a field system honest. A field layer fails quietly: a
+ * relation points at a missing id, a visual duplicates text screen readers already read, an element
+ * is styled from state it was never registered for. These rules surface that drift as warnings.
+ *
+ * Each rule is a pure function over the registries (or the DOM, given a resolver), so it is testable
+ * without a live page; `lintPlatform` aggregates them over a FieldPlatform. Lint reads — it never
+ * mutates state, physics, or the DOM.
+ */
+import type { MeasurementRegistry } from './measurement.ts';
+import type { StateRegistry } from './state.ts';
+import type { FeedbackRegistry } from './feedback.ts';
+import type { OverlayRegistry } from './overlays.ts';
+import type { RelationshipRegistry } from './relationships.ts';
+import type { VisualBindingRegistry } from './visual-bindings.ts';
+import type { FrameScheduler } from './schedule.ts';
+import type { Resolver } from './relationships.ts';
+export type LintCode = 'relation-target-missing' | 'visual-orphan' | 'visual-not-hidden' | 'state-unregistered' | 'overlay-without-links' | 'feedback-non-css-var' | 'measurement-off-phase' | 'sink-without-feedback' | 'feedback-vars-unwritten' | 'feedback-lane-inert';
+export interface PlatformLintWarning {
+    code: LintCode;
+    severity: 'warning' | 'error';
+    message: string;
+    /** the element at fault, when there is one. */
+    element?: Element;
+}
+/** A `[data-field-relation]` whose `data-field-target` does not resolve points at nothing. Pure. */
+export declare function lintRelationTargets(root: ParentNode, resolve: Resolver): PlatformLintWarning[];
+/**
+ * A sink that captures but never reports: `data-absorb`/`data-max` on a `sink` body with no
+ * `data-feedback` — the engine takes matter in but never writes `--load` back, so the body fills
+ * invisibly. This exact gap shipped (a vessel that captured for months while its meter sat empty),
+ * which is why it lints. Pure.
+ */
+export declare function lintSinkFeedback(root: ParentNode): PlatformLintWarning[];
+/**
+ * An element whose inline style *reads* a feedback channel (`var(--d…)`, `var(--load…)`,
+ * `var(--field-…)`) while its body never opted into writes (`data-body` without `data-feedback`)
+ * styles itself from variables that will never be set for it. Pure.
+ */
+export declare function lintFeedbackVarReads(root: ParentNode): PlatformLintWarning[];
+/** An element styled from field state it was never registered to measure is feedback with no source. Pure. */
+export declare function lintStateRegistration(state: StateRegistry, measure: MeasurementRegistry): PlatformLintWarning[];
+/** A relationship overlay with no relationships behind it draws a graph that does not exist. Pure. */
+export declare function lintOverlayLinks(overlays: OverlayRegistry, relationships: RelationshipRegistry): PlatformLintWarning[];
+/**
+ * A feedback binding to a metric lane the platform can never produce: `--field-<m>` where `<m>` is a
+ * DESIGNED metric (not computed generically, not the supplied-only pair) AND the element declares no
+ * `data-field-<m>` to ground it. The lane is bound but will never be written — the element styles
+ * itself from a channel that stays at rest. This is the gap the navigation sweep hit
+ * (`navigation-current` declares `signal`/`route-strength`); same class as a sink that captures but
+ * never reports (`lintSinkFeedback`). Pure.
+ */
+export declare function lintInertFeedback(feedback: FeedbackRegistry): PlatformLintWarning[];
+/** Feedback must write CSS custom properties, not ARIA/attributes — state is not accessibility state. Pure. */
+export declare function lintFeedbackVars(feedback: FeedbackRegistry): PlatformLintWarning[];
+/** Off-phase reads recorded by the scheduler (e.g. a measurement during the write phase). */
+export declare function lintSchedulerViolations(scheduler: FrameScheduler): PlatformLintWarning[];
+/** Visual-binding warnings (orphan representations, un-hidden decorative visuals), mapped to lint. */
+export declare function lintVisuals(visuals: VisualBindingRegistry): PlatformLintWarning[];
+export interface PlatformLike {
+    root: Element;
+    measure: MeasurementRegistry;
+    state: StateRegistry;
+    feedback: FeedbackRegistry;
+    relationships: RelationshipRegistry;
+    visuals: VisualBindingRegistry;
+    overlays: OverlayRegistry;
+    scheduler: FrameScheduler;
+}
+export interface LintOptions {
+    /** the subtree to scan for relation targets (defaults to the platform root). */
+    root?: ParentNode;
+    /** id resolver for relation targets (defaults to document.getElementById). */
+    resolve?: Resolver;
+}
+/** Run every platform lint rule over a FieldPlatform and return the aggregated warnings. */
+export declare function lintPlatform(platform: PlatformLike, opts?: LintOptions): PlatformLintWarning[];
+//# sourceMappingURL=lint.d.ts.map

package/dist/lint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint.d.ts","sourceRoot":"","sources":["../src/lint.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC/D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAGnD,MAAM,MAAM,QAAQ,GAChB,yBAAyB,GACzB,eAAe,GACf,mBAAmB,GACnB,oBAAoB,GACpB,uBAAuB,GACvB,sBAAsB,GACtB,uBAAuB,GACvB,uBAAuB,GACvB,yBAAyB,GACzB,qBAAqB,CAAC;AAE1B,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,SAAS,GAAG,OAAO,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,oGAAoG;AACpG,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,QAAQ,GAAG,mBAAmB,EAAE,CAa9F;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,GAAG,mBAAmB,EAAE,CAcxE;AAKD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,GAAG,mBAAmB,EAAE,CAe5E;AAED,8GAA8G;AAC9G,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,mBAAmB,GAAG,mBAAmB,EAAE,CAO/G;AAED,sGAAsG;AACtG,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,eAAe,EAAE,aAAa,EAAE,oBAAoB,GAAG,mBAAmB,EAAE,CAKtH;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,mBAAmB,EAAE,CAiBnF;AAED,+GAA+G;AAC/G,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,mBAAmB,EAAE,CASlF;AAED,6FAA6F;AAC7F,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,cAAc,GAAG,mBAAmB,EAAE,CAMxF;AAED,sGAAsG;AACtG,wBAAgB,WAAW,CAAC,OAAO,EAAE,qBAAqB,GAAG,mBAAmB,EAAE,CAOjF;AAED,MAAM,WAAW,YAAY;IAC3B,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,SAAS,EAAE,cAAc,CAAC;CAC3B;AAED,MAAM,WAAW,WAAW;IAC1B,gFAAgF;IAChF,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,QAAQ,CAAC;CACpB;AAED,4FAA4F;AAC5F,wBAAgB,YAAY,CAAC,QAAQ,EAAE,YAAY,EAAE,IAAI,GAAE,WAAgB,GAAG,mBAAmB,EAAE,CAclG"}

package/dist/lint.js

@@ -0,0 +1,153 @@
+import { classifyMetric } from "./metrics.js";
+/** A `[data-field-relation]` whose `data-field-target` does not resolve points at nothing. Pure. */
+export function lintRelationTargets(root, resolve) {
+    const out = [];
+    root.querySelectorAll('[data-field-relation]').forEach((el) => {
+        const target = el.getAttribute('data-field-target');
+        if (!target) {
+            out.push({ code: 'relation-target-missing', severity: 'warning', element: el, message: `[data-field-relation="${el.getAttribute('data-field-relation')}"] has no data-field-target` });
+            return;
+        }
+        const id = target.startsWith('#') ? target.slice(1) : target;
+        if (!resolve(id))
+            out.push({ code: 'relation-target-missing', severity: 'warning', element: el, message: `data-field-target "${target}" resolves to no element` });
+    });
+    return out;
+}
+/**
+ * A sink that captures but never reports: `data-absorb`/`data-max` on a `sink` body with no
+ * `data-feedback` — the engine takes matter in but never writes `--load` back, so the body fills
+ * invisibly. This exact gap shipped (a vessel that captured for months while its meter sat empty),
+ * which is why it lints. Pure.
+ */
+export function lintSinkFeedback(root) {
+    const out = [];
+    root.querySelectorAll('[data-absorb], [data-max]').forEach((el) => {
+        const tokens = (el.getAttribute('data-body') ?? '').split(/\s+/).filter(Boolean);
+        if (!tokens.includes('sink'))
+            return;
+        if (el.hasAttribute('data-feedback'))
+            return;
+        out.push({
+            code: 'sink-without-feedback',
+            severity: 'warning',
+            element: el,
+            message: `a sink body carries ${el.hasAttribute('data-absorb') ? 'data-absorb' : 'data-max'} but no data-feedback — the engine will capture matter but never write --load back`,
+        });
+    });
+    return out;
+}
+/** The inline-style substrings that mean "this element reads an engine-written channel". */
+const FEEDBACK_VAR_READS = ['var(--d', 'var(--load', 'var(--field-'];
+/**
+ * An element whose inline style *reads* a feedback channel (`var(--d…)`, `var(--load…)`,
+ * `var(--field-…)`) while its body never opted into writes (`data-body` without `data-feedback`)
+ * styles itself from variables that will never be set for it. Pure.
+ */
+export function lintFeedbackVarReads(root) {
+    const out = [];
+    root.querySelectorAll('[data-body]').forEach((el) => {
+        if (el.hasAttribute('data-feedback'))
+            return;
+        const style = el.getAttribute('style') ?? '';
+        const read = FEEDBACK_VAR_READS.find((v) => style.includes(v));
+        if (read)
+            out.push({
+                code: 'feedback-vars-unwritten',
+                severity: 'warning',
+                element: el,
+                message: `inline style reads ${read}…) but the body carries no data-feedback — that channel is never written for it`,
+            });
+    });
+    return out;
+}
+/** An element styled from field state it was never registered to measure is feedback with no source. Pure. */
+export function lintStateRegistration(state, measure) {
+    const out = [];
+    for (const el of state.elements()) {
+        if (!measure.has(el))
+            out.push({ code: 'state-unregistered', severity: 'warning', element: el, message: 'element holds field state but is not registered for measurement' });
+    }
+    return out;
+}
+/** A relationship overlay with no relationships behind it draws a graph that does not exist. Pure. */
+export function lintOverlayLinks(overlays, relationships) {
+    const hasRelOverlay = overlays.all().some((o) => o.type === 'relationship');
+    if (hasRelOverlay && relationships.size === 0)
+        return [{ code: 'overlay-without-links', severity: 'warning', message: 'a relationship overlay exists but the RelationshipRegistry has no links' }];
+    return [];
+}
+/**
+ * A feedback binding to a metric lane the platform can never produce: `--field-<m>` where `<m>` is a
+ * DESIGNED metric (not computed generically, not the supplied-only pair) AND the element declares no
+ * `data-field-<m>` to ground it. The lane is bound but will never be written — the element styles
+ * itself from a channel that stays at rest. This is the gap the navigation sweep hit
+ * (`navigation-current` declares `signal`/`route-strength`); same class as a sink that captures but
+ * never reports (`lintSinkFeedback`). Pure.
+ */
+export function lintInertFeedback(feedback) {
+    const out = [];
+    for (const { element, vars } of feedback.boundVars()) {
+        for (const name of vars) {
+            if (!name.startsWith('--field-'))
+                continue;
+            const metric = name.slice('--field-'.length);
+            if (!metric || classifyMetric(metric) !== 'designed')
+                continue;
+            if (element.hasAttribute(`data-field-${metric}`))
+                continue; // grounded by the host — fine
+            out.push({
+                code: 'feedback-lane-inert',
+                severity: 'warning',
+                element,
+                message: `feedback binds ${name} but "${metric}" is neither computed by the platform nor supplied (data-field-${metric}) on this element — the lane is never written`,
+            });
+        }
+    }
+    return out;
+}
+/** Feedback must write CSS custom properties, not ARIA/attributes — state is not accessibility state. Pure. */
+export function lintFeedbackVars(feedback) {
+    const out = [];
+    for (const { element, vars } of feedback.boundVars()) {
+        for (const name of vars) {
+            if (!name.startsWith('--'))
+                out.push({ code: 'feedback-non-css-var', severity: 'error', element, message: `feedback binding writes "${name}", which is not a CSS custom property (state must not write ARIA/attributes)` });
+        }
+    }
+    return out;
+}
+/** Off-phase reads recorded by the scheduler (e.g. a measurement during the write phase). */
+export function lintSchedulerViolations(scheduler) {
+    return scheduler.violations().map((v) => ({
+        code: 'measurement-off-phase',
+        severity: 'warning',
+        message: v.message,
+    }));
+}
+/** Visual-binding warnings (orphan representations, un-hidden decorative visuals), mapped to lint. */
+export function lintVisuals(visuals) {
+    return visuals.lint().map((w) => ({
+        code: (w.code === 'orphan-representation' ? 'visual-orphan' : 'visual-not-hidden'),
+        severity: w.severity,
+        message: w.message,
+        element: w.visual,
+    }));
+}
+/** Run every platform lint rule over a FieldPlatform and return the aggregated warnings. */
+export function lintPlatform(platform, opts = {}) {
+    const root = opts.root ?? platform.root;
+    const resolve = opts.resolve ?? ((id) => (typeof document !== 'undefined' ? document.getElementById(id) : null));
+    return [
+        ...lintRelationTargets(root, resolve),
+        ...lintSinkFeedback(root),
+        ...lintFeedbackVarReads(root),
+        ...lintStateRegistration(platform.state, platform.measure),
+        ...lintOverlayLinks(platform.overlays, platform.relationships),
+        ...lintFeedbackVars(platform.feedback),
+        ...lintInertFeedback(platform.feedback),
+        ...lintVisuals(platform.visuals),
+        ...lintSchedulerViolations(platform.scheduler),
+    ];
+}
+//# sourceMappingURL=lint.js.map

package/dist/lint.js.map

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

package/dist/measurement.d.ts

@@ -0,0 +1,44 @@
+/**
+ * MeasurementRegistry — frame-stable geometry. The native primitive Fundamental wishes existed: read
+ * every registered element's box once per frame and hand back an immutable snapshot, so the rest of
+ * the system works from one consistent set of rectangles instead of each force calling
+ * `getBoundingClientRect()` whenever it likes (which risks layout thrash).
+ *
+ * Strict read-phase: `measure()` only reads. Feedback (writes) happens in a separate phase. Default
+ * measurement is the host box (Shadow-DOM safe); a `getRect` override feeds closed roots / inner cores.
+ */
+import type { CoordinateSpace, FieldMeasurement, Viewport } from './types.ts';
+export interface MeasureRegistration {
+    /** semantic role (body, relationship endpoint, container, visual…). */
+    role?: string;
+    coordinateSpace?: CoordinateSpace;
+    /** rectangle provider when the body box is not the element box (closed roots, inner cores). */
+    getRect?: () => DOMRect;
+}
+export declare class MeasurementRegistry {
+    private readonly entries;
+    private snapshot;
+    private guard;
+    /**
+     * Install a phase guard (the FrameScheduler supplies one via `readGuard()`). It is consulted
+     * before reading layout, so a measurement requested in the write phase is caught. Decoupled by
+     * design: measurement never imports the scheduler. Pass `null` to remove the guard.
+     */
+    setPhaseGuard(guard: ((op: string) => void) | null): void;
+    /** Register an element for measurement (idempotent — re-registering refreshes its options). */
+    register(element: Element, opts?: MeasureRegistration): void;
+    unregister(element: Element): void;
+    /** Whether an element is registered for measurement (does not require a measure pass). */
+    has(element: Element): boolean;
+    get size(): number;
+    /**
+     * Read every registered element's geometry once and return the immutable snapshot. Disconnected
+     * elements are pruned. `now`/`viewport` are injectable so this is testable without a live DOM.
+     */
+    measure(now?: number, viewport?: Viewport): readonly FieldMeasurement[];
+    /** The most recent snapshot (without re-reading layout). */
+    last(): readonly FieldMeasurement[];
+    /** The latest measurement for one element, if present. */
+    for(element: Element): FieldMeasurement | undefined;
+}
+//# sourceMappingURL=measurement.d.ts.map

package/dist/measurement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"measurement.d.ts","sourceRoot":"","sources":["../src/measurement.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAa,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEzF,MAAM,WAAW,mBAAmB;IAClC,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,+FAA+F;IAC/F,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC;CACzB;AAkCD,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IACrD,OAAO,CAAC,QAAQ,CAAmC;IACnD,OAAO,CAAC,KAAK,CAAuC;IAEpD;;;;OAIG;IACH,aAAa,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI;IAIzD,+FAA+F;IAC/F,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,GAAE,mBAAwB,GAAG,IAAI;IAIhE,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAIlC,0FAA0F;IAC1F,GAAG,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO;IAI9B,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;OAGG;IACH,OAAO,CAAC,GAAG,SAAI,EAAE,QAAQ,CAAC,EAAE,QAAQ,GAAG,SAAS,gBAAgB,EAAE;IAwBlE,4DAA4D;IAC5D,IAAI,IAAI,SAAS,gBAAgB,EAAE;IAInC,0DAA0D;IAC1D,GAAG,CAAC,OAAO,EAAE,OAAO,GAAG,gBAAgB,GAAG,SAAS;CAGpD"}

package/dist/measurement.js

@@ -0,0 +1,95 @@
+function toFieldRect(r) {
+    const left = r.left;
+    const top = r.top;
+    const width = r.width;
+    const height = r.height;
+    return {
+        x: left,
+        y: top,
+        width,
+        height,
+        cx: left + width / 2,
+        cy: top + height / 2,
+        top,
+        right: left + width,
+        bottom: top + height,
+        left,
+    };
+}
+/** Overlap fraction of a rect within the viewport box ∈ [0,1]. */
+function visibilityRatio(r, vp) {
+    const area = r.width * r.height;
+    if (area <= 0)
+        return 0;
+    const ox = Math.max(0, Math.min(r.right, vp.width) - Math.max(r.left, 0));
+    const oy = Math.max(0, Math.min(r.bottom, vp.height) - Math.max(r.top, 0));
+    return Math.min(1, (ox * oy) / area);
+}
+export class MeasurementRegistry {
+    entries = new Map();
+    snapshot = [];
+    guard = null;
+    /**
+     * Install a phase guard (the FrameScheduler supplies one via `readGuard()`). It is consulted
+     * before reading layout, so a measurement requested in the write phase is caught. Decoupled by
+     * design: measurement never imports the scheduler. Pass `null` to remove the guard.
+     */
+    setPhaseGuard(guard) {
+        this.guard = guard;
+    }
+    /** Register an element for measurement (idempotent — re-registering refreshes its options). */
+    register(element, opts = {}) {
+        this.entries.set(element, { element, ...opts });
+    }
+    unregister(element) {
+        this.entries.delete(element);
+    }
+    /** Whether an element is registered for measurement (does not require a measure pass). */
+    has(element) {
+        return this.entries.has(element);
+    }
+    get size() {
+        return this.entries.size;
+    }
+    /**
+     * Read every registered element's geometry once and return the immutable snapshot. Disconnected
+     * elements are pruned. `now`/`viewport` are injectable so this is testable without a live DOM.
+     */
+    measure(now = 0, viewport) {
+        this.guard?.('measure'); // read-phase discipline: reading layout off-phase thrashes
+        const vp = viewport ?? defaultViewport();
+        const out = [];
+        for (const [el, e] of this.entries) {
+            if (!el.isConnected) {
+                this.entries.delete(el);
+                continue;
+            }
+            const rect = toFieldRect(e.getRect ? e.getRect() : el.getBoundingClientRect());
+            const ratio = visibilityRatio(rect, vp);
+            out.push({
+                element: el,
+                rect,
+                visible: ratio > 0,
+                visibilityRatio: ratio,
+                coordinateSpace: e.coordinateSpace ?? 'viewport',
+                timestamp: now,
+            });
+        }
+        this.snapshot = out;
+        return out;
+    }
+    /** The most recent snapshot (without re-reading layout). */
+    last() {
+        return this.snapshot;
+    }
+    /** The latest measurement for one element, if present. */
+    for(element) {
+        return this.snapshot.find((m) => m.element === element);
+    }
+}
+function defaultViewport() {
+    if (typeof window !== 'undefined')
+        return { width: window.innerWidth, height: window.innerHeight };
+    return { width: 0, height: 0 };
+}
+//# sourceMappingURL=measurement.js.map

package/dist/measurement.js.map

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

package/dist/metrics.d.ts

@@ -0,0 +1,70 @@
+export declare const METRIC_KINDS: readonly ["attention", "memory", "coherence", "entropy", "pressure", "confidence", "risk", "recency", "priority"];
+export type MetricKind = (typeof METRIC_KINDS)[number];
+/** The lanes `computeMetrics` produces generically every frame (everything except the supplied-only pair). */
+export declare const COMPUTED_METRICS: readonly ["attention", "memory", "coherence", "entropy", "pressure", "recency", "priority"];
+/** Metrics the engine NEVER invents — present ONLY when the host supplies them (`data-field-<m>`). */
+export declare const SUPPLIED_ONLY_METRICS: readonly ["confidence", "risk"];
+/**
+ * How a metric lane is produced:
+ * - `computed`     — the generic pipeline writes it every frame (proximity/engagement/relations/age).
+ * - `supplied-only`— confidence/risk; the engine has no evidence, so it's written ONLY when supplied.
+ * - `designed`     — a semantic lane (signal, route-strength, sync, …) the HOST must supply via
+ *                    `data-field-<m>` (or a domain model). With neither a supply nor a computed source
+ *                    its `--field-<m>` is **inert** — declared but never written. This is the gap the
+ *                    nav sweep hit (navigation-current's `signal`/`route-strength`); `lintInertFeedback`
+ *                    surfaces it, the same way `lintSinkFeedback` catches a capturing-but-silent sink.
+ */
+export type MetricSupport = 'computed' | 'supplied-only' | 'designed';
+/** Classify a metric name by how its `--field-<name>` lane is produced (see {@link MetricSupport}). */
+export declare function classifyMetric(name: string): MetricSupport;
+/**
+ * One frame of computed metrics: every lane is a number except `confidence` and `risk`, which are
+ * present ONLY when the host supplies them (the engine never invents them — see `computeMetrics`).
+ */
+export type ComputedMetrics = Record<Exclude<MetricKind, 'confidence' | 'risk'>, number> & {
+    confidence?: number;
+    risk?: number;
+};
+export interface MetricInputs {
+    /** 0..1 — how centred the element is in the viewport (1 = at centre). */
+    proximity: number;
+    /** 0..1 — fraction of the element visible. */
+    visible: number;
+    /** hover / focus / active. */
+    engaged: boolean;
+    /** frames since the last compute (usually 1). */
+    dtFrames: number;
+    /** resolved relationships touching this element. */
+    relResolved: number;
+    /** total relationships touching this element. */
+    relTotal: number;
+    /** contradicting relationships touching this element. */
+    relConflict: number;
+    /** metric values supplied by the recipe/data (data-field-<metric>). */
+    supplied: Partial<Record<MetricKind, number>>;
+    /** prior frame's metric values. */
+    prev: Partial<Record<MetricKind, number>>;
+}
+/** The default half-life for a grounded recency lane: 7 days (override per element with `data-field-halflife`, in ms). */
+export declare const DEFAULT_RECENCY_HALF_LIFE_MS: number;
+/** The slice of Element the derivation reads — structural, so this module stays DOM-free and node-testable. */
+interface AttrReader {
+    getAttribute(name: string): string | null;
+}
+/**
+ * Parse a declared world timestamp (`data-field-at`): epoch milliseconds or an ISO 8601
+ * string. Invalid or absent values read as absent (`undefined`) — never NaN.
+ */
+export declare function parseFieldAt(value: string | null): number | undefined;
+/**
+ * Derive the grounded recency for an element declaring `data-field-at` — `freshness(at, now,
+ * halfLife)` with the half-life from `data-field-halflife` (ms, default 7 days). Returns
+ * `undefined` when no valid timestamp is declared, so the caller falls through to the
+ * interaction-inferred path. `nowMs` is the frame's wall-clock instant, sampled ONCE per
+ * frame by the caller (`apply-recipe.ts`) — never per-element `Date.now()`.
+ */
+export declare function groundedRecency(el: AttrReader, nowMs: number): number | undefined;
+/** Compute one frame of metrics from inputs (pure). Supplied values override/add to computed ones. */
+export declare function computeMetrics(inp: MetricInputs): ComputedMetrics;
+export {};
+//# sourceMappingURL=metrics.d.ts.map

package/dist/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"AAoBA,eAAO,MAAM,YAAY,mHAUf,CAAC;AACX,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD,8GAA8G;AAC9G,eAAO,MAAM,gBAAgB,6FAQnB,CAAC;AACX,sGAAsG;AACtG,eAAO,MAAM,qBAAqB,iCAAkC,CAAC;AAErE;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,eAAe,GAAG,UAAU,CAAC;AAEtE,uGAAuG;AACvG,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAI1D;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,YAAY,GAAG,MAAM,CAAC,EAAE,MAAM,CAAC,GAAG;IACzF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAIF,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;IAC9C,mCAAmC;IACnC,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;CAC3C;AAWD,0HAA0H;AAC1H,eAAO,MAAM,4BAA4B,QAAiB,CAAC;AAE3D,+GAA+G;AAC/G,UAAU,UAAU;IAClB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CAC3C;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAMrE;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAKjF;AAED,sGAAsG;AACtG,wBAAgB,cAAc,CAAC,GAAG,EAAE,YAAY,GAAG,eAAe,CA4BjE"}

package/dist/metrics.js

@@ -0,0 +1,119 @@
+/**
+ * The platform metric library. Makes the metrics a recipe lists real enough to be written and
+ * inspected — typed state values, not prose. The math here is PURE (node-testable); the per-frame
+ * wiring onto a `FieldPlatform` lives in `apply-recipe.ts`.
+ *
+ * Honest about provenance:
+ * - COMPUTED generically: attention / memory / recency (proximity + engagement + decay) and
+ *   coherence / entropy / pressure / priority (from relationship resolution + age). Any of these may
+ *   be overridden by a supplied value.
+ * - SUPPLIED-ONLY: `confidence` and `risk` are external judgments the engine has no evidence for.
+ *   They are present ONLY when the host supplies them (`data-field-<metric>` / recipe options / a
+ *   domain model). Confidence is NEVER inferred from relationship presence — a citation is not
+ *   certainty. Risk is NEVER defaulted to 0 — "no risk" is a claim, not a safe blank. (Relationship
+ *   resolution is a separate signal, see `apply-recipe.ts`, not confidence.)
+ * - GROUNDED by world time: a declared `data-field-at` timestamp GROUNDS the recency lane —
+ *   recency becomes `freshness(at, now, halfLife)` (the core temporal kernel) instead of the
+ *   interaction-inferred ease. See `groundedRecency` below; the wiring is `apply-recipe.ts`.
+ */
+import { freshness } from '@fundamental-engine/core';
+export const METRIC_KINDS = [
+    'attention',
+    'memory',
+    'coherence',
+    'entropy',
+    'pressure',
+    'confidence',
+    'risk',
+    'recency',
+    'priority',
+];
+/** The lanes `computeMetrics` produces generically every frame (everything except the supplied-only pair). */
+export const COMPUTED_METRICS = [
+    'attention',
+    'memory',
+    'coherence',
+    'entropy',
+    'pressure',
+    'recency',
+    'priority',
+];
+/** Metrics the engine NEVER invents — present ONLY when the host supplies them (`data-field-<m>`). */
+export const SUPPLIED_ONLY_METRICS = ['confidence', 'risk'];
+/** Classify a metric name by how its `--field-<name>` lane is produced (see {@link MetricSupport}). */
+export function classifyMetric(name) {
+    if (COMPUTED_METRICS.includes(name))
+        return 'computed';
+    if (SUPPLIED_ONLY_METRICS.includes(name))
+        return 'supplied-only';
+    return 'designed';
+}
+const clamp01 = (n) => (n < 0 ? 0 : n > 1 ? 1 : n);
+const prevOf = (inp, k) => inp.prev[k] ?? 0;
+// ── world time: the declared-timestamp ground for the recency lane ──────────────────────
+// The metric pipeline runs on two clocks. WITHOUT a declared timestamp, recency is
+// EXPERIENTIAL time — inferred from interaction (the eased computeMetrics behavior below,
+// unchanged). WITH one, the element carries WORLD TIME (`data-field-at` — when the data
+// itself last happened), and that declared timestamp GROUNDS the recency lane:
+// recency = freshness(at, now, halfLife), the core temporal kernel's exponential newness.
+/** The default half-life for a grounded recency lane: 7 days (override per element with `data-field-halflife`, in ms). */
+export const DEFAULT_RECENCY_HALF_LIFE_MS = 7 * 86_400_000;
+/**
+ * Parse a declared world timestamp (`data-field-at`): epoch milliseconds or an ISO 8601
+ * string. Invalid or absent values read as absent (`undefined`) — never NaN.
+ */
+export function parseFieldAt(value) {
+    if (value == null || value.trim() === '')
+        return undefined;
+    const n = Number(value);
+    if (Number.isFinite(n))
+        return n;
+    const t = Date.parse(value);
+    return Number.isNaN(t) ? undefined : t;
+}
+/**
+ * Derive the grounded recency for an element declaring `data-field-at` — `freshness(at, now,
+ * halfLife)` with the half-life from `data-field-halflife` (ms, default 7 days). Returns
+ * `undefined` when no valid timestamp is declared, so the caller falls through to the
+ * interaction-inferred path. `nowMs` is the frame's wall-clock instant, sampled ONCE per
+ * frame by the caller (`apply-recipe.ts`) — never per-element `Date.now()`.
+ */
+export function groundedRecency(el, nowMs) {
+    const at = parseFieldAt(el.getAttribute('data-field-at'));
+    if (at == null)
+        return undefined;
+    const hl = Number(el.getAttribute('data-field-halflife'));
+    return freshness(at, nowMs, Number.isFinite(hl) && hl > 0 ? hl : DEFAULT_RECENCY_HALF_LIFE_MS);
+}
+/** Compute one frame of metrics from inputs (pure). Supplied values override/add to computed ones. */
+export function computeMetrics(inp) {
+    const dt = Math.max(1, inp.dtFrames);
+    const attention = clamp01(inp.proximity * inp.visible * (inp.engaged ? 1.3 : 1));
+    const memory = clamp01(prevOf(inp, 'memory') + (attention > 0.6 ? 0.006 * dt : -0.0008 * dt));
+    const recency = inp.engaged || attention > 0.6 ? 1 : clamp01(prevOf(inp, 'recency') - 0.003 * dt);
+    const resolvedRatio = inp.relTotal > 0 ? inp.relResolved / inp.relTotal : 0;
+    const conflictRatio = inp.relTotal > 0 ? inp.relConflict / inp.relTotal : 0;
+    const coherence = inp.relTotal > 0 ? clamp01(resolvedRatio - conflictRatio) : prevOf(inp, 'coherence');
+    const entropy = inp.relTotal > 0 ? clamp01(conflictRatio + (1 - resolvedRatio) * 0.5) : prevOf(inp, 'entropy');
+    // COMPUTED lanes only. `confidence` and `risk` are intentionally absent: the engine has no evidence
+    // for a claim's truth or its danger, so they stay unset unless the host supplies them below. The old
+    // `confidence: relTotal > 0 ? resolvedRatio : 0` meant "any citation ⇒ fully confident", and the old
+    // `risk: 0` meant "everything is safe by default" — both the wrong default for a trust/ops surface.
+    const computed = {
+        attention,
+        memory,
+        recency,
+        coherence,
+        entropy,
+        pressure: clamp01(entropy * 0.6 + (1 - recency) * 0.4),
+        priority: attention,
+    };
+    // supplied values win — these lanes (incl. confidence) are recipe/data-driven, not invented
+    for (const k of METRIC_KINDS) {
+        const s = inp.supplied[k];
+        if (s != null && Number.isFinite(s))
+            computed[k] = clamp01(s);
+    }
+    return computed;
+}
+//# sourceMappingURL=metrics.js.map

package/dist/metrics.js.map

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