@fundamental-engine/dom 0.7.0

package/dist/bind-data.js

@@ -0,0 +1,164 @@
+/**
+ * bindData — make real application data participate in field behavior. Records become bodies, mapped
+ * metrics become state, mapped relationships become graph edges, and a recipe supplies the behavior
+ * (metric/feedback framework) via applyRecipe(). Updates are deterministic (diff by id); removed
+ * records decay before they leave rather than popping.
+ *
+ *   const binding = bindData(container, records, mapper, { recipe: 'search-relevance-field' });
+ *   binding.update(nextRecords);
+ *   binding.destroy();
+ *
+ * The recipe frames the field (which metrics → --field-* are tracked); the per-record mapper owns the
+ * body tokens, metric values, and relationships — so the data drives the field, not a mock.
+ */
+import { recipeById } from '@fundamental-engine/core';
+import { applyRecipe } from "./apply-recipe.js";
+/** Diff two id sets (pure). */
+export function diffIds(prev, next) {
+    const p = new Set(prev);
+    const n = new Set(next);
+    const added = [];
+    const removed = [];
+    const kept = [];
+    for (const id of n)
+        (p.has(id) ? kept : added).push(id);
+    for (const id of p)
+        if (!n.has(id))
+            removed.push(id);
+    return { added, removed, kept };
+}
+const setNum = (el, k, v) => {
+    if (v != null && Number.isFinite(v))
+        el.setAttribute(k, String(v));
+    else
+        el.removeAttribute(k);
+};
+/** Apply a mapped record's body tokens, metric values, label/content, and relationship anchors. */
+function applyMapped(el, m, contentHtml) {
+    const doc = el.ownerDocument;
+    el.setAttribute('data-body', m.body.tokens.join(' '));
+    setNum(el, 'data-strength', m.body.strength);
+    setNum(el, 'data-range', m.body.range);
+    setNum(el, 'data-spin', m.body.spin);
+    setNum(el, 'data-angle', m.body.angle);
+    if (m.body.feedback)
+        el.setAttribute('data-feedback', '');
+    // metric values → data-field-<metric> (the recipe + applyRecipe turn these into --field-* state)
+    for (const [k, v] of Object.entries(m.metrics ?? {}))
+        setNum(el, `data-field-${k}`, v);
+    // domain content (overrides label), else the plain label
+    if (contentHtml != null) {
+        let box = el.querySelector(':scope > .bd-content');
+        if (!box) {
+            box = doc.createElement('div');
+            box.className = 'bd-content';
+            el.prepend(box);
+        }
+        box.innerHTML = contentHtml;
+    }
+    else if (m.label != null) {
+        let lbl = el.querySelector(':scope > .bd-label');
+        if (!lbl) {
+            lbl = doc.createElement('span');
+            lbl.className = 'bd-label';
+            el.prepend(lbl);
+        }
+        lbl.textContent = m.label;
+    }
+    // relationships → child anchors the RelationshipRegistry discovers (one per edge)
+    el.querySelectorAll(':scope > .bd-rel').forEach((a) => a.remove());
+    for (const r of m.relationships ?? []) {
+        const a = doc.createElement('a');
+        a.className = 'bd-rel';
+        a.setAttribute('aria-hidden', 'true');
+        a.setAttribute('href', `#${r.to}`);
+        a.setAttribute('data-field-relation', r.type);
+        a.setAttribute('data-field-target', `#${r.to}`);
+        if (r.strength != null)
+            a.setAttribute('data-field-strength', String(r.strength));
+        el.appendChild(a);
+    }
+}
+/** Bind records to a field. Returns a handle with update()/destroy(). */
+export function bindData(container, records, mapper, options = {}) {
+    const decayMs = options.decayMs ?? 400;
+    const tag = options.tag ?? 'div';
+    const doc = container.ownerDocument;
+    const els = new Map();
+    let applied = null;
+    const recipeArg = options.recipe;
+    const reapply = () => {
+        applied?.destroy();
+        applied = null;
+        const items = [...els.values()].filter((e) => !('bdExiting' in e.dataset));
+        const recipe = typeof recipeArg === 'string' ? recipeById(recipeArg) : recipeArg;
+        if (recipe && items.length)
+            applied = applyRecipe(container, recipe, { bodies: items, annotateBodies: false, reducedMotion: options.reducedMotion });
+    };
+    const render = (recs) => {
+        const mapped = recs.map((rec, i) => mapper(rec, i));
+        const nextIds = mapped.map((m) => m.id);
+        const { added, removed } = diffIds(els.keys(), nextIds);
+        mapped.forEach((m, i) => {
+            let el = els.get(m.id);
+            if (!el) {
+                el = doc.createElement(tag);
+                el.dataset.bdId = m.id;
+                el.id = m.id; // addressable so relationships/anchors can target a record by id
+                if (options.className)
+                    el.className = options.className;
+                el.dataset.bdEntering = '';
+                container.appendChild(el);
+                els.set(m.id, el);
+                const created = el;
+                if (typeof requestAnimationFrame !== 'undefined')
+                    requestAnimationFrame(() => created.removeAttribute('data-bd-entering'));
+                else
+                    el.removeAttribute('data-bd-entering');
+            }
+            applyMapped(el, m, options.content?.(recs[i], m));
+            container.appendChild(el); // keep DOM order aligned with records
+        });
+        for (const id of removed) {
+            const el = els.get(id);
+            if (!el)
+                continue;
+            el.dataset.bdExiting = ''; // CSS fades it; zero its metric vars so feedback eases down
+            for (const attr of Array.from(el.attributes))
+                if (attr.name.startsWith('data-field-'))
+                    el.setAttribute(attr.name, '0');
+            els.delete(id);
+            const finish = () => {
+                el.remove();
+                reapply();
+            };
+            if (typeof setTimeout !== 'undefined')
+                setTimeout(finish, decayMs);
+            else
+                finish();
+        }
+        if (added.length || removed.length)
+            reapply();
+    };
+    render(records);
+    return {
+        container,
+        update: render,
+        ids: () => [...els.keys()],
+        applied: () => applied,
+        inspect: () => {
+            if (!applied)
+                return null;
+            const ins = applied.inspect();
+            return { records: els.size, bodies: ins.measurements, relationships: ins.relationships };
+        },
+        destroy: () => {
+            applied?.destroy();
+            applied = null;
+            for (const el of els.values())
+                el.remove();
+            els.clear();
+        },
+    };
+}
+//# sourceMappingURL=bind-data.js.map

package/dist/bind-data.js.map

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

package/dist/browser-host.d.ts

@@ -0,0 +1,11 @@
+/**
+ * browserHost — the default {@link FieldHost}, binding the renderer-agnostic core engine to the
+ * browser (`window` / `document` / `requestAnimationFrame`). It lives in `@fundamental-engine/dom` (the DOM
+ * participation layer), NOT in `Fundamental` — core imports zero DOM. `createField(canvas, opts)`
+ * requires a host; pass `browserHost()` in the browser (or `createBrowserField` for the convenience),
+ * or a custom host to drive the same engine from a headless renderer / a different document / a test.
+ */
+import type { FieldHost } from '@fundamental-engine/core';
+/** Build a FieldHost backed by `window` / `document`. */
+export declare function browserHost(): FieldHost;
+//# sourceMappingURL=browser-host.d.ts.map

package/dist/browser-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-host.d.ts","sourceRoot":"","sources":["../src/browser-host.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAK1D,yDAAyD;AACzD,wBAAgB,WAAW,IAAI,SAAS,CAkCvC"}

package/dist/browser-host.js

@@ -0,0 +1,41 @@
+import { prefersReducedMotion, pageHidden } from "./env.js";
+const INPUT_EVENTS = ['pointerdown', 'wheel', 'keydown', 'touchstart'];
+/** Build a FieldHost backed by `window` / `document`. */
+export function browserHost() {
+    return {
+        root: document,
+        viewport: () => ({ width: window.innerWidth, height: window.innerHeight, dpr: window.devicePixelRatio || 1 }),
+        scrollY: () => window.scrollY || 0,
+        scrollHeight: () => document.documentElement.scrollHeight,
+        reducedMotion: () => prefersReducedMotion(),
+        hidden: () => pageHidden(),
+        raf: (cb) => requestAnimationFrame(cb),
+        cancelRaf: (id) => cancelAnimationFrame(id),
+        createCanvas: () => document.createElement('canvas'),
+        onResize: (cb) => {
+            window.addEventListener('resize', cb, { passive: true });
+            return () => window.removeEventListener('resize', cb);
+        },
+        onScroll: (cb) => {
+            window.addEventListener('scroll', cb, { passive: true });
+            return () => window.removeEventListener('scroll', cb);
+        },
+        onVisibility: (cb) => {
+            document.addEventListener('visibilitychange', cb);
+            return () => document.removeEventListener('visibilitychange', cb);
+        },
+        onInput: (cb) => {
+            for (const ev of INPUT_EVENTS)
+                window.addEventListener(ev, cb, { passive: true });
+            return () => {
+                for (const ev of INPUT_EVENTS)
+                    window.removeEventListener(ev, cb);
+            };
+        },
+        onBodyEvent: (type, cb) => {
+            document.addEventListener(type, cb);
+            return () => document.removeEventListener(type, cb);
+        },
+    };
+}
+//# sourceMappingURL=browser-host.js.map

package/dist/browser-host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-host.js","sourceRoot":"","sources":["../src/browser-host.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE5D,MAAM,YAAY,GAAG,CAAC,aAAa,EAAE,OAAO,EAAE,SAAS,EAAE,YAAY,CAAU,CAAC;AAEhF,yDAAyD;AACzD,MAAM,UAAU,WAAW;IACzB,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,WAAW,EAAE,GAAG,EAAE,MAAM,CAAC,gBAAgB,IAAI,CAAC,EAAE,CAAC;QAC7G,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,IAAI,CAAC;QAClC,YAAY,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,eAAe,CAAC,YAAY;QACzD,aAAa,EAAE,GAAG,EAAE,CAAC,oBAAoB,EAAE;QAC3C,MAAM,EAAE,GAAG,EAAE,CAAC,UAAU,EAAE;QAC1B,GAAG,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,qBAAqB,CAAC,EAAE,CAAC;QACtC,SAAS,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,oBAAoB,CAAC,EAAE,CAAC;QAC3C,YAAY,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,aAAa,CAAC,QAAQ,CAAC;QACpD,QAAQ,EAAE,CAAC,EAAE,EAAE,EAAE;YACf,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YACzD,OAAO,GAAG,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QACxD,CAAC;QACD,QAAQ,EAAE,CAAC,EAAE,EAAE,EAAE;YACf,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YACzD,OAAO,GAAG,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QACxD,CAAC;QACD,YAAY,EAAE,CAAC,EAAE,EAAE,EAAE;YACnB,QAAQ,CAAC,gBAAgB,CAAC,kBAAkB,EAAE,EAAE,CAAC,CAAC;YAClD,OAAO,GAAG,EAAE,CAAC,QAAQ,CAAC,mBAAmB,CAAC,kBAAkB,EAAE,EAAE,CAAC,CAAC;QACpE,CAAC;QACD,OAAO,EAAE,CAAC,EAAE,EAAE,EAAE;YACd,KAAK,MAAM,EAAE,IAAI,YAAY;gBAAE,MAAM,CAAC,gBAAgB,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YAClF,OAAO,GAAG,EAAE;gBACV,KAAK,MAAM,EAAE,IAAI,YAAY;oBAAE,MAAM,CAAC,mBAAmB,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;YACpE,CAAC,CAAC;QACJ,CAAC;QACD,WAAW,EAAE,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE;YACxB,QAAQ,CAAC,gBAAgB,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YACpC,OAAO,GAAG,EAAE,CAAC,QAAQ,CAAC,mBAAmB,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACtD,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/contours.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Contour typography (#257, #363) — glyph-outline generation for ANY font the author applies to a
+ * body element. The Contour Sink tier of Body Matter Interaction: the element absorbs field matter,
+ * the generated vector layer shows what that absorption means, the semantic text remains the source
+ * of meaning.
+ *
+ * Fundamental ships no font parser (the zero-dependency rule): the caller supplies the parsed font —
+ * any object structurally matching `ContourFont`, which opentype.js's `Font` satisfies directly:
+ *
+ *   import { load } from 'opentype.js';
+ *   import { contourSvgFor } from '@fundamental-engine/dom';
+ *   const font = await load('/fonts/your-font.woff');   // WHATEVER face the element uses
+ *   const handle = contourSvgFor(document.querySelector('#hero-title'), font, { rings: 3 });
+ *   // → an aria-hidden SVG bound via data-field-visual-for, inserted after the element;
+ *   //   the platform's state mirroring carries --d / --load onto it from the body.
+ *
+ * The same primitive runs in node for build-time generation (parse the font file, call
+ * `contourPathData`, commit the output) — the site's gen-contours script is that usage.
+ *
+ * Layout is per-glyph with pair kerning, no shaping: correct for Latin-script display text, the
+ * contour use case. Complex scripts (ligatures, contextual forms) need a real shaper and are out
+ * of scope here.
+ */
+/** The minimal parsed-font surface this module needs — opentype.js `Font` satisfies it. */
+export interface ContourGlyph {
+    advanceWidth?: number;
+    getPath(x: number, y: number, fontSize: number): {
+        toPathData(decimals?: number): string;
+    };
+}
+export interface ContourFont {
+    unitsPerEm: number;
+    ascender: number;
+    charToGlyph(char: string): ContourGlyph;
+    getKerningValue(left: ContourGlyph, right: ContourGlyph): number;
+}
+export interface ContourPathOptions {
+    /** path-data decimal places (default 2). */
+    decimals?: number;
+    /** padding around the bounding viewBox so wide ring strokes don't clip (px, default 12). */
+    pad?: number;
+}
+export interface ContourPath {
+    text: string;
+    fontSize: number;
+    viewBox: string;
+    d: string;
+}
+/**
+ * Lay `text` out in `font` at `fontSize` and return the combined glyph-outline path data plus a
+ * padded viewBox. Pure — runs in the browser or node identically.
+ */
+export declare function contourPathData(font: ContourFont, text: string, fontSize: number, opts?: ContourPathOptions): ContourPath;
+export interface ContourSvgOptions extends ContourPathOptions {
+    /** text to outline — defaults to the element's textContent, trimmed. */
+    text?: string;
+    /** layout size in px — defaults to the element's computed font-size, else 96. */
+    fontSize?: number;
+    /** how many stacked-stroke rings to emit (default 3, classed ring-1…ring-N, innermost first). */
+    rings?: number;
+    /** insert the SVG into the DOM after the element (default true); false returns it unattached. */
+    attach?: boolean;
+    /** document override (tests / detached trees); defaults to the element's ownerDocument. */
+    doc?: Document;
+}
+export interface ContourSvgHandle {
+    svg: SVGSVGElement;
+    path: ContourPath;
+    /** remove the SVG from the DOM. */
+    remove(): void;
+}
+/**
+ * Generate the bound vector representation for a body element from ITS OWN font: an `aria-hidden`
+ * SVG of stacked-stroke contour rings, carrying `data-field-visual-for` back to the element so the
+ * platform's state mirroring (Bound Visual Sink) drives it from the body's live `--d` / `--load`.
+ * The element keeps its semantic text; if it has no id one is assigned (the binding needs a ref).
+ */
+export declare function contourSvgFor(el: HTMLElement, font: ContourFont, opts?: ContourSvgOptions): ContourSvgHandle;
+//# sourceMappingURL=contours.d.ts.map

package/dist/contours.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contours.d.ts","sourceRoot":"","sources":["../src/contours.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,2FAA2F;AAC3F,MAAM,WAAW,YAAY;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG;QAAE,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;CAC5F;AACD,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAAC;IACxC,eAAe,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,GAAG,MAAM,CAAC;CAClE;AAED,MAAM,WAAW,kBAAkB;IACjC,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4FAA4F;IAC5F,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,GAAE,kBAAuB,GAAG,WAAW,CAqB7H;AAED,MAAM,WAAW,iBAAkB,SAAQ,kBAAkB;IAC3D,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iGAAiG;IACjG,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iGAAiG;IACjG,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,2FAA2F;IAC3F,GAAG,CAAC,EAAE,QAAQ,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,aAAa,CAAC;IACnB,IAAI,EAAE,WAAW,CAAC;IAClB,mCAAmC;IACnC,MAAM,IAAI,IAAI,CAAC;CAChB;AAID;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,GAAE,iBAAsB,GAAG,gBAAgB,CA4BhH"}

package/dist/contours.js

@@ -0,0 +1,88 @@
+/**
+ * Contour typography (#257, #363) — glyph-outline generation for ANY font the author applies to a
+ * body element. The Contour Sink tier of Body Matter Interaction: the element absorbs field matter,
+ * the generated vector layer shows what that absorption means, the semantic text remains the source
+ * of meaning.
+ *
+ * Fundamental ships no font parser (the zero-dependency rule): the caller supplies the parsed font —
+ * any object structurally matching `ContourFont`, which opentype.js's `Font` satisfies directly:
+ *
+ *   import { load } from 'opentype.js';
+ *   import { contourSvgFor } from '@fundamental-engine/dom';
+ *   const font = await load('/fonts/your-font.woff');   // WHATEVER face the element uses
+ *   const handle = contourSvgFor(document.querySelector('#hero-title'), font, { rings: 3 });
+ *   // → an aria-hidden SVG bound via data-field-visual-for, inserted after the element;
+ *   //   the platform's state mirroring carries --d / --load onto it from the body.
+ *
+ * The same primitive runs in node for build-time generation (parse the font file, call
+ * `contourPathData`, commit the output) — the site's gen-contours script is that usage.
+ *
+ * Layout is per-glyph with pair kerning, no shaping: correct for Latin-script display text, the
+ * contour use case. Complex scripts (ligatures, contextual forms) need a real shaper and are out
+ * of scope here.
+ */
+/**
+ * Lay `text` out in `font` at `fontSize` and return the combined glyph-outline path data plus a
+ * padded viewBox. Pure — runs in the browser or node identically.
+ */
+export function contourPathData(font, text, fontSize, opts = {}) {
+    const decimals = opts.decimals ?? 2;
+    const pad = opts.pad ?? 12;
+    const scale = fontSize / font.unitsPerEm;
+    const ascent = font.ascender * scale; // baseline at ascender height → bbox starts near y=0
+    const parts = [];
+    let x = 0;
+    let prev = null;
+    // track the bounds ourselves so we don't depend on a Path#getBoundingBox implementation —
+    // the em box is a safe, font-true envelope (exact ink bounds vary per glyph renderer).
+    for (const ch of text) {
+        const glyph = font.charToGlyph(ch);
+        if (prev)
+            x += font.getKerningValue(prev, glyph) * scale;
+        parts.push(glyph.getPath(x, ascent, fontSize).toPathData(decimals));
+        x += (glyph.advanceWidth ?? font.unitsPerEm / 2) * scale;
+        prev = glyph;
+    }
+    // the em box (height = fontSize, baseline at ascent) is the font-true envelope; exact ink
+    // bounds vary per glyph and aren't needed — pad absorbs over/undershoot.
+    const viewBox = `${(-pad).toFixed(1)} ${(-pad).toFixed(1)} ${(x + pad * 2).toFixed(1)} ${(fontSize + pad * 2).toFixed(1)}`;
+    return { text, fontSize, viewBox, d: parts.join('') };
+}
+const SVG_NS = 'http://www.w3.org/2000/svg';
+/**
+ * Generate the bound vector representation for a body element from ITS OWN font: an `aria-hidden`
+ * SVG of stacked-stroke contour rings, carrying `data-field-visual-for` back to the element so the
+ * platform's state mirroring (Bound Visual Sink) drives it from the body's live `--d` / `--load`.
+ * The element keeps its semantic text; if it has no id one is assigned (the binding needs a ref).
+ */
+export function contourSvgFor(el, font, opts = {}) {
+    const doc = opts.doc ?? el.ownerDocument;
+    const text = opts.text ?? (el.textContent ?? '').trim();
+    let fontSize = opts.fontSize;
+    if (fontSize === undefined) {
+        const view = doc?.defaultView;
+        const computed = view?.getComputedStyle ? parseFloat(view.getComputedStyle(el).fontSize) : NaN;
+        fontSize = Number.isFinite(computed) && computed > 0 ? computed : 96;
+    }
+    const path = contourPathData(font, text, fontSize, opts);
+    if (!el.id)
+        el.id = `contour-${Math.abs(text.split('').reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 7))}`;
+    const svg = doc.createElementNS(SVG_NS, 'svg');
+    svg.setAttribute('viewBox', path.viewBox);
+    svg.setAttribute('aria-hidden', 'true');
+    svg.setAttribute('focusable', 'false');
+    svg.setAttribute('data-field-visual-for', el.id);
+    svg.setAttribute('data-field-visual-role', 'representation');
+    const rings = Math.max(1, opts.rings ?? 3);
+    for (let i = rings; i >= 1; i--) {
+        const p = doc.createElementNS(SVG_NS, 'path');
+        p.setAttribute('class', `ring ring-${i}`);
+        p.setAttribute('d', path.d);
+        p.setAttribute('fill', 'none');
+        svg.appendChild(p);
+    }
+    if (opts.attach !== false)
+        el.insertAdjacentElement('afterend', svg);
+    return { svg, path, remove: () => svg.remove() };
+}
+//# sourceMappingURL=contours.js.map

package/dist/contours.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contours.js","sourceRoot":"","sources":["../src/contours.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AA4BH;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,IAAiB,EAAE,IAAY,EAAE,QAAgB,EAAE,OAA2B,EAAE;IAC9G,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC;IACpC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,EAAE,CAAC;IAC3B,MAAM,KAAK,GAAG,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC;IACzC,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,CAAC,qDAAqD;IAC3F,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,IAAI,IAAI,GAAwB,IAAI,CAAC;IACrC,0FAA0F;IAC1F,uFAAuF;IACvF,KAAK,MAAM,EAAE,IAAI,IAAI,EAAE,CAAC;QACtB,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;QACnC,IAAI,IAAI;YAAE,CAAC,IAAI,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,KAAK,CAAC;QACzD,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC;QACpE,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,IAAI,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC;QACzD,IAAI,GAAG,KAAK,CAAC;IACf,CAAC;IACD,0FAA0F;IAC1F,yEAAyE;IACzE,MAAM,OAAO,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3H,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;AACxD,CAAC;AAsBD,MAAM,MAAM,GAAG,4BAA4B,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,EAAe,EAAE,IAAiB,EAAE,OAA0B,EAAE;IAC5F,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,EAAE,CAAC,aAAa,CAAC;IACzC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,CAAC,EAAE,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACxD,IAAI,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;IAC7B,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,GAAG,EAAE,WAAW,CAAC;QAC9B,MAAM,QAAQ,GAAG,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;QAC/F,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;IACvE,CAAC;IACD,MAAM,IAAI,GAAG,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC;IAEzD,IAAI,CAAC,EAAE,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,GAAG,WAAW,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9G,MAAM,GAAG,GAAG,GAAG,CAAC,eAAe,CAAC,MAAM,EAAE,KAAK,CAAkB,CAAC;IAChE,GAAG,CAAC,YAAY,CAAC,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAC1C,GAAG,CAAC,YAAY,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;IACxC,GAAG,CAAC,YAAY,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IACvC,GAAG,CAAC,YAAY,CAAC,uBAAuB,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;IACjD,GAAG,CAAC,YAAY,CAAC,wBAAwB,EAAE,gBAAgB,CAAC,CAAC;IAC7D,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC;IAC3C,KAAK,IAAI,CAAC,GAAG,KAAK,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAChC,MAAM,CAAC,GAAG,GAAG,CAAC,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC9C,CAAC,CAAC,YAAY,CAAC,OAAO,EAAE,aAAa,CAAC,EAAE,CAAC,CAAC;QAC1C,CAAC,CAAC,YAAY,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;QAC5B,CAAC,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/B,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IACrB,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,KAAK,KAAK;QAAE,EAAE,CAAC,qBAAqB,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;IACrE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC;AACnD,CAAC"}

package/dist/env.d.ts

@@ -0,0 +1,39 @@
+/**
+ * env — shared, SSR-safe environment probes for the platform layer.
+ *
+ * Two helpers that multiple platform modules need independently:
+ *   - `prefersReducedMotion()` — true when the OS/browser signals reduced motion preference.
+ *   - `pageHidden()` — true when the document visibility state is "hidden".
+ *
+ * Both are safe to call in a non-DOM environment (SSR, Node test runners, custom hosts): they
+ * default to `false` when `window` / `document` are absent, rather than throwing.
+ *
+ * **Overriding for tests:** call `setEnvOverrides({ reducedMotion, hidden })` before the code
+ * under test runs, then `clearEnvOverrides()` (or a second call with `{}`) afterward. The
+ * override object is shallow-merged — passing only `reducedMotion` leaves `hidden` live, and
+ * vice versa. This is the intended seam; tests no longer need to stub `globalThis.matchMedia` or
+ * `document.hidden` directly.
+ */
+interface EnvOverrides {
+    reducedMotion?: boolean;
+    hidden?: boolean;
+}
+/**
+ * Override one or both env probes — for test use only. Shallow-merges with any existing
+ * overrides so callers can set just the field they need.
+ */
+export declare function setEnvOverrides(o: EnvOverrides): void;
+/** Remove all env overrides, restoring the live DOM probe behaviour. */
+export declare function clearEnvOverrides(): void;
+/**
+ * Returns `true` when `prefers-reduced-motion: reduce` is active.
+ * SSR-safe: returns `false` when `matchMedia` is not available.
+ */
+export declare function prefersReducedMotion(): boolean;
+/**
+ * Returns `true` when the document is currently hidden (background tab / minimised window).
+ * SSR-safe: returns `false` when `document` is not available.
+ */
+export declare function pageHidden(): boolean;
+export {};
+//# sourceMappingURL=env.d.ts.map

package/dist/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,UAAU,YAAY;IACpB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAID;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,YAAY,GAAG,IAAI,CAErD;AAED,wEAAwE;AACxE,wBAAgB,iBAAiB,IAAI,IAAI,CAExC;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAG9C;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,OAAO,CAGpC"}

package/dist/env.js

@@ -0,0 +1,47 @@
+/**
+ * env — shared, SSR-safe environment probes for the platform layer.
+ *
+ * Two helpers that multiple platform modules need independently:
+ *   - `prefersReducedMotion()` — true when the OS/browser signals reduced motion preference.
+ *   - `pageHidden()` — true when the document visibility state is "hidden".
+ *
+ * Both are safe to call in a non-DOM environment (SSR, Node test runners, custom hosts): they
+ * default to `false` when `window` / `document` are absent, rather than throwing.
+ *
+ * **Overriding for tests:** call `setEnvOverrides({ reducedMotion, hidden })` before the code
+ * under test runs, then `clearEnvOverrides()` (or a second call with `{}`) afterward. The
+ * override object is shallow-merged — passing only `reducedMotion` leaves `hidden` live, and
+ * vice versa. This is the intended seam; tests no longer need to stub `globalThis.matchMedia` or
+ * `document.hidden` directly.
+ */
+let _overrides = {};
+/**
+ * Override one or both env probes — for test use only. Shallow-merges with any existing
+ * overrides so callers can set just the field they need.
+ */
+export function setEnvOverrides(o) {
+    _overrides = { ..._overrides, ...o };
+}
+/** Remove all env overrides, restoring the live DOM probe behaviour. */
+export function clearEnvOverrides() {
+    _overrides = {};
+}
+/**
+ * Returns `true` when `prefers-reduced-motion: reduce` is active.
+ * SSR-safe: returns `false` when `matchMedia` is not available.
+ */
+export function prefersReducedMotion() {
+    if (_overrides.reducedMotion !== undefined)
+        return _overrides.reducedMotion;
+    return typeof matchMedia !== 'undefined' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+/**
+ * Returns `true` when the document is currently hidden (background tab / minimised window).
+ * SSR-safe: returns `false` when `document` is not available.
+ */
+export function pageHidden() {
+    if (_overrides.hidden !== undefined)
+        return _overrides.hidden;
+    return typeof document !== 'undefined' && document.hidden;
+}
+//# sourceMappingURL=env.js.map

package/dist/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,IAAI,UAAU,GAAiB,EAAE,CAAC;AAElC;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,CAAe;IAC7C,UAAU,GAAG,EAAE,GAAG,UAAU,EAAE,GAAG,CAAC,EAAE,CAAC;AACvC,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,iBAAiB;IAC/B,UAAU,GAAG,EAAE,CAAC;AAClB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB;IAClC,IAAI,UAAU,CAAC,aAAa,KAAK,SAAS;QAAE,OAAO,UAAU,CAAC,aAAa,CAAC;IAC5E,OAAO,OAAO,UAAU,KAAK,WAAW,IAAI,UAAU,CAAC,kCAAkC,CAAC,CAAC,OAAO,CAAC;AACrG,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU;IACxB,IAAI,UAAU,CAAC,MAAM,KAAK,SAAS;QAAE,OAAO,UAAU,CAAC,MAAM,CAAC;IAC9D,OAAO,OAAO,QAAQ,KAAK,WAAW,IAAI,QAAQ,CAAC,MAAM,CAAC;AAC5D,CAAC"}

package/dist/export-dom.d.ts

@@ -0,0 +1,7 @@
+/** Trigger a browser download of a data/blob URL. */
+export declare function downloadUrl(url: string, filename: string): void;
+/** Download arbitrary text (e.g. an SVG document from `segmentsToSvg`) as a file. */
+export declare function downloadText(text: string, filename: string, mime?: string): void;
+/** Download a canvas as a PNG file (`canvasToPng` + a download). */
+export declare function downloadCanvasPng(canvas: HTMLCanvasElement, filename?: string): void;
+//# sourceMappingURL=export-dom.d.ts.map

package/dist/export-dom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export-dom.d.ts","sourceRoot":"","sources":["../src/export-dom.ts"],"names":[],"mappings":"AAQA,qDAAqD;AACrD,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAQ/D;AAED,qFAAqF;AACrF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,SAAkB,GAAG,IAAI,CAIzF;AAED,oEAAoE;AACpE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,EAAE,QAAQ,SAAc,GAAG,IAAI,CAEzF"}

package/dist/export-dom.js

@@ -0,0 +1,28 @@
+/**
+ * DOM download helpers (Phase: frontier). Triggering a file download needs `document` (an anchor
+ * click), so these live in `@fundamental-engine/dom`, not `Fundamental`. The pure serializers stay in
+ * core: `segmentsToSvg` (vector) and `canvasToPng` (a canvas's own `toDataURL`). Pair them here to
+ * actually save a file.
+ */
+import { canvasToPng } from '@fundamental-engine/core';
+/** Trigger a browser download of a data/blob URL. */
+export function downloadUrl(url, filename) {
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = filename;
+    a.rel = 'noopener';
+    document.body.appendChild(a);
+    a.click();
+    a.remove();
+}
+/** Download arbitrary text (e.g. an SVG document from `segmentsToSvg`) as a file. */
+export function downloadText(text, filename, mime = 'image/svg+xml') {
+    const url = URL.createObjectURL(new Blob([text], { type: mime }));
+    downloadUrl(url, filename);
+    URL.revokeObjectURL(url);
+}
+/** Download a canvas as a PNG file (`canvasToPng` + a download). */
+export function downloadCanvasPng(canvas, filename = 'field.png') {
+    downloadUrl(canvasToPng(canvas), filename);
+}
+//# sourceMappingURL=export-dom.js.map

package/dist/export-dom.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"export-dom.js","sourceRoot":"","sources":["../src/export-dom.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAEvD,qDAAqD;AACrD,MAAM,UAAU,WAAW,CAAC,GAAW,EAAE,QAAgB;IACvD,MAAM,CAAC,GAAG,QAAQ,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;IACtC,CAAC,CAAC,IAAI,GAAG,GAAG,CAAC;IACb,CAAC,CAAC,QAAQ,GAAG,QAAQ,CAAC;IACtB,CAAC,CAAC,GAAG,GAAG,UAAU,CAAC;IACnB,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAC7B,CAAC,CAAC,KAAK,EAAE,CAAC;IACV,CAAC,CAAC,MAAM,EAAE,CAAC;AACb,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,QAAgB,EAAE,IAAI,GAAG,eAAe;IACjF,MAAM,GAAG,GAAG,GAAG,CAAC,eAAe,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAClE,WAAW,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IAC3B,GAAG,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;AAC3B,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,iBAAiB,CAAC,MAAyB,EAAE,QAAQ,GAAG,WAAW;IACjF,WAAW,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,CAAC;AAC7C,CAAC"}

package/dist/feedback.d.ts

@@ -0,0 +1,57 @@
+import type { StateRegistry } from './state.ts';
+/** Map of state-key → CSS-var name written for an element. */
+type VarBinding = Record<string, string>;
+export interface ThresholdOptions {
+    /** the state key whose value crosses the threshold. */
+    metric: string;
+    enter: number;
+    exit: number;
+    debounce?: number;
+    /** event dispatched on the exit edge (e.g. `field:dim` to pair with `field:lit`). */
+    exitEvent?: string;
+}
+export declare class FeedbackRegistry {
+    private readonly bindings;
+    private readonly direct;
+    private readonly thresholds;
+    private _cssWritesLastFrame;
+    /** Declare which state keys map to which CSS vars on an element (e.g. `{ density: '--field-density' }`). */
+    bind(element: Element, map: VarBinding): void;
+    /**
+     * Remove the CSS var bound to `key` on `element` from the DOM. Use
+     * when a metric becomes absent — e.g. the host stops supplying `data-field-confidence` — so a value
+     * written on an earlier `flush()` doesn't linger. A no-op when nothing is bound for `key`; the
+     * binding itself is left intact, so the var is rewritten if the metric returns. `flush()` already
+     * skips keys with no state, so this only clears the previously written inline value.
+     */
+    clearVar(element: Element, key: string): void;
+    /** The declared bindings (element → the CSS-var names it writes), for lint / inspection. */
+    boundVars(): Array<{
+        element: Element;
+        vars: string[];
+    }>;
+    /**
+     * Actual `style.setProperty` calls made during the last `flush()`. Use this (not
+     * `boundVars().length`) to measure real per-frame DOM write cost: off-screen elements with
+     * active bindings still generate mutations even though they produce no visible change.
+     */
+    cssWritesLastFrame(): number;
+    /** Queue a direct CSS-var write (applied on the next `flush`). */
+    set(element: Element, vars: Record<string, number | string>): void;
+    /** Register a thresholded, debounced event for an element metric (hysteresis via enter/exit). */
+    threshold(element: Element, eventName: string, opts: ThresholdOptions): void;
+    /**
+     * Drop ALL bindings and thresholds registered for one element. Use when an element is removed from
+     * the DOM and you want immediate reclamation rather than waiting for the next flush() sweep.
+     */
+    unregister(element: Element): void;
+    /**
+     * Write-phase: apply bound state → CSS vars, apply queued direct writes, and run thresholders →
+     * fire edge events. `state` supplies the numeric values for bound vars + thresholds. Disconnected
+     * elements are pruned here — the natural per-frame moment — so bindings and thresholds for removed
+     * elements never accumulate across the lifetime of the registry.
+     */
+    flush(state: StateRegistry, now?: number): void;
+}
+export {};
+//# sourceMappingURL=feedback.d.ts.map

package/dist/feedback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feedback.d.ts","sourceRoot":"","sources":["../src/feedback.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,8DAA8D;AAC9D,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AA6BzC,MAAM,WAAW,gBAAgB;IAC/B,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qFAAqF;IACrF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkC;IAC3D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8C;IACrE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAwB;IACnD,OAAO,CAAC,mBAAmB,CAAK;IAEhC,4GAA4G;IAC5G,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,UAAU,GAAG,IAAI;IAI7C;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAK7C,4FAA4F;IAC5F,SAAS,IAAI,KAAK,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAIxD;;;;OAIG;IACH,kBAAkB,IAAI,MAAM;IAI5B,kEAAkE;IAClE,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,IAAI;IAMlE,iGAAiG;IACjG,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,IAAI;IAU5E;;;OAGG;IACH,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IASlC;;;;;OAKG;IACH,KAAK,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,SAAI,GAAG,IAAI;CA0B3C"}