@loomwork/ui-hydration 0.0.0-stage → 0.1.1

package/dist/esm/cache.js

@@ -0,0 +1,151 @@
+import { canonicalJson, fnv1a64 } from "@loomwork/core";
+// ── Result cache ──────────────────────────────────────────────────────────────
+// `scope: "global"` shares one entry per handle; `scope: "principal"` keys on (principal, handle)
+// and refuses to cache when no principal is known — a per-viewer result must never leak to the
+// next viewer. TTL is against an injected clock so tests never sleep.
+//
+// The key also carries the SPEC's fingerprint: a handle whose provider was repaired (a remapped
+// schema pin, a different tool, a new reshaping) is a different question, and must not be
+// answered from the entry the old spec left behind. `invalidate(handle)` still drops every
+// spec-generation of that handle, so the fingerprint never makes a stale entry unreachable.
+// NUL: cannot appear in a handle, so `invalidate(handle)`'s suffix match can never mis-hit
+// another handle whose name happens to contain the delimiter (e.g. a handle literally named "h").
+const SEP = String.fromCharCode(0);
+// Memoized per spec OBJECT: the controller fingerprints the same spec on every `schedule`, and
+// `canonicalJson` walks the whole graph. A WeakMap keeps that O(1) without pinning specs alive.
+const fingerprints = new WeakMap();
+let unhashable = 0;
+/**
+ * The content fingerprint of a provider spec — the identity both the cache key and the
+ * controller's "have I already loaded THIS spec?" check are taken over, so the two can never
+ * disagree about what "the same provider" means.
+ *
+ * Total: `canonicalJson` throws on a spec carrying a non-finite number, a bigint or a nest past
+ * its depth cap. Such a spec gets a fingerprint unique to the OBJECT, which is conservative in
+ * both directions — the same object is still recognised as itself (no reload storm), and two
+ * structurally identical unhashable specs are treated as different (no cache hit).
+ */
+export function specFingerprint(spec) {
+    const memo = fingerprints.get(spec);
+    if (memo !== undefined)
+        return memo;
+    let fp;
+    try {
+        fp = fnv1a64(canonicalJson(spec));
+    }
+    catch {
+        unhashable += 1;
+        fp = `unhashable-${unhashable}`;
+    }
+    fingerprints.set(spec, fp);
+    return fp;
+}
+/** `{kind: version}` for the bound kinds whose contract declares a version; `undefined` if none. */
+function contractVersions(kinds, contracts) {
+    if (contracts === undefined)
+        return undefined;
+    let out;
+    for (const k of kinds) {
+        if (!Object.hasOwn(contracts, k))
+            continue;
+        const v = contracts[k]?.version;
+        if (typeof v !== "string")
+            continue;
+        // Null-prototype-safe: a kind named `__proto__` must not set a prototype.
+        out ??= Object.create(null);
+        out[k] = v;
+    }
+    return out;
+}
+/**
+ * The one normal form of a kinds list — sorted, de-duplicated. The cache key and the controller's
+ * load fingerprint both use it, so they can never disagree about whether two kinds lists are the
+ * same question.
+ */
+export function normaliseKinds(kinds) {
+    return [...new Set(kinds)].sort();
+}
+/** `""` for the plain variant; `undefined` for one that cannot be keyed (never cached). */
+function variantKey(params, kinds, versions) {
+    if (Object.keys(params).length === 0 && kinds.length === 0)
+        return "";
+    try {
+        // `versions` is added ONLY when present, so every key without one is what it always was.
+        return fnv1a64(canonicalJson(versions === undefined ? { params, kinds } : { params, kinds, versions }));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The default cap on cached results (U17). Generous: a surface with fewer live questions never notices it. */
+export const DEFAULT_CACHE_MAX_ENTRIES = 10_000;
+export class HydrationCache {
+    clock;
+    // A Map iterates in insertion order, so re-inserting on use keeps the least recently used entry
+    // FIRST: eviction and promotion are both O(1).
+    entries = new Map();
+    maxEntries;
+    constructor(clock = Date.now, opts = {}) {
+        this.clock = clock;
+        const max = opts.maxEntries ?? DEFAULT_CACHE_MAX_ENTRIES;
+        if (!Number.isInteger(max) || max < 1)
+            throw new RangeError(`HydrationCache maxEntries must be a positive integer, got ${max}`);
+        this.maxEntries = max;
+    }
+    /** How many results are held now (expired ones count until they are read or evicted). */
+    get size() {
+        return this.entries.size;
+    }
+    key(spec, principalId, variant) {
+        const kinds = spec.outputCheck === "contract" ? normaliseKinds(variant.kinds ?? []) : [];
+        const v = variantKey(variant.params ?? {}, kinds, contractVersions(kinds, variant.contracts));
+        if (v === undefined)
+            return undefined;
+        const fp = specFingerprint(spec);
+        // The handle stays LAST: `invalidate(handle)` suffix-matches it across every variant.
+        if (spec.cachePolicy.scope === "global")
+            return `g${SEP}${fp}${SEP}${v}${SEP}${spec.handle}`;
+        return principalId === undefined
+            ? undefined
+            : `p${SEP}${principalId}${SEP}${fp}${SEP}${v}${SEP}${spec.handle}`;
+    }
+    get(spec, principalId, variant = {}) {
+        const k = this.key(spec, principalId, variant);
+        if (k === undefined)
+            return undefined;
+        const e = this.entries.get(k);
+        if (!e)
+            return undefined;
+        if (e.expiresAt <= this.clock()) {
+            this.entries.delete(k);
+            return undefined;
+        }
+        // Promote: most recently used goes to the back of the iteration order.
+        this.entries.delete(k);
+        this.entries.set(k, e);
+        return { value: e.value };
+    }
+    set(spec, principalId, value, variant = {}) {
+        const k = this.key(spec, principalId, variant);
+        if (k === undefined || spec.cachePolicy.ttlSeconds <= 0)
+            return;
+        this.entries.delete(k);
+        this.entries.set(k, { value, expiresAt: this.clock() + spec.cachePolicy.ttlSeconds * 1000 });
+        while (this.entries.size > this.maxEntries) {
+            const oldest = this.entries.keys().next();
+            if (oldest.done === true)
+                break;
+            this.entries.delete(oldest.value);
+        }
+    }
+    invalidate(handle) {
+        if (handle === undefined) {
+            this.entries.clear();
+            return;
+        }
+        for (const k of [...this.entries.keys()])
+            if (k.endsWith(SEP + handle))
+                this.entries.delete(k);
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/esm/cache.js.map

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

package/dist/esm/chatSource.js

@@ -0,0 +1,259 @@
+import { useChatContracts } from "@loomwork/ui-core/browser";
+/**
+ * The most a durable reasoning response may weigh (bytes, or characters for the `text()` check). loom's
+ * route caps the readable text at 1 MiB, so 2 MiB leaves room for the JSON envelope and escaping.
+ * Residual: a host `fetch` that only offers `json()` and sends no `Content-Length` is not bounded here.
+ */
+export const MAX_REASONING_RESPONSE_BYTES = 2 * 1024 * 1024;
+/** A stream open at least this long (ms) was healthy: its end is not a failure streak. */
+const HEALTHY_MS = 5000;
+const EVENTS = [
+    "status",
+    "partial",
+    "delta",
+    "reasoning",
+    "reasoning-partial",
+    "reset",
+    "message",
+    "closed",
+    "reconnect",
+    "error",
+];
+const changedBy = (r) => r?.ok === true && r.changed === true;
+const finding = (code, message) => ({ code, severity: "error", message });
+const defaultTimer = (fn, ms) => {
+    const id = setTimeout(fn, ms);
+    return () => clearTimeout(id);
+};
+export function connectConversation(options) {
+    // The transcript this feeds is published as a Chat value; its contract is deferred in core.
+    useChatContracts();
+    const { feed, baseUrl } = options;
+    const pageLimit = Math.max(1, Math.min(options.pageLimit ?? 50, 500));
+    const maxFrame = options.maxFrameBytes ?? 256 * 1024;
+    const timer = options.setTimer ?? defaultTimer;
+    const ac = new AbortController();
+    let source;
+    let cancelReopen;
+    let closed = false;
+    let loadingOlder = false;
+    let failures = 0;
+    let openedAt = 0;
+    const now = options.now ?? Date.now;
+    const base = Math.max(1, options.reconnectMs ?? 2000);
+    const ceiling = Math.max(base, options.maxReconnectMs ?? 30_000);
+    const floor = Math.max(1, options.reconnectFloorMs ?? 250);
+    /** Consecutive failures double the wait, capped; the first is the base. */
+    const backoff = () => Math.min(ceiling, base * 2 ** Math.min(failures, 16));
+    const report = (code, message) => options.onFinding?.(finding(code, message));
+    const publish = () => options.publish(feed.value(), { streaming: feed.streaming });
+    async function page(cursor) {
+        const q = `direction=backward&limit=${pageLimit}${cursor === undefined ? "" : `&cursor=${encodeURIComponent(cursor)}`}`;
+        let body;
+        try {
+            const res = await options.fetch(`${baseUrl}/history?${q}`, { signal: ac.signal });
+            if (!res.ok)
+                throw new Error("not ok");
+            body = await res.json();
+        }
+        catch {
+            if (!ac.signal.aborted)
+                report("history-unavailable", "the conversation history could not be loaded");
+            return false;
+        }
+        if (closed)
+            return false;
+        const r = feed.applyHistory(body, "backward");
+        if (!r.ok) {
+            report(r.finding.code, r.finding.message);
+            return false;
+        }
+        if (r.changed)
+            publish();
+        return true;
+    }
+    function open() {
+        if (closed)
+            return;
+        const cursor = feed.resumeCursor();
+        const url = `${baseUrl}/events${cursor === undefined ? "" : `?cursor=${encodeURIComponent(cursor)}`}`;
+        const es = options.openStream(url);
+        source = es;
+        openedAt = now();
+        for (const name of EVENTS)
+            es.addEventListener(name, (ev) => {
+                if (closed || source !== es)
+                    return;
+                const raw = ev.data;
+                let data;
+                if (typeof raw === "string") {
+                    if (raw.length > maxFrame)
+                        return report("frame-too-large", "a conversation event was too large and was ignored");
+                    try {
+                        data = JSON.parse(raw);
+                    }
+                    catch {
+                        return report("frame-invalid", "a conversation event was not understood and was ignored");
+                    }
+                }
+                const r = feed.applyEvent(name, data);
+                if (!r.ok) {
+                    // The feed's finding text is fixed; an `error` event's body was never read.
+                    report(r.finding.code, r.finding.message);
+                    return;
+                }
+                if (r.reconnect !== true)
+                    failures = 0; // a frame the feed understood: the connection works
+                if (r.changed)
+                    publish();
+                if (r.reconnect === true) {
+                    // Asked to recycle. A server that does so right after opening is looping: back off like a failure.
+                    const healthy = now() - openedAt >= HEALTHY_MS;
+                    if (healthy)
+                        failures = 0;
+                    reopen(failures === 0 ? floor : Math.max(floor, backoff()));
+                    if (!healthy)
+                        failures++;
+                }
+            });
+        // A stream the platform has given up on (it keeps trying by itself while CONNECTING).
+        es.onerror = () => {
+            if (es.readyState === 2) {
+                // A stream that stayed up long enough was healthy: its end starts the backoff afresh, and the
+                // first wait is the documented base.
+                if (now() - openedAt >= HEALTHY_MS)
+                    failures = 0;
+                const delay = backoff();
+                failures++;
+                reopen(delay);
+            }
+        };
+    }
+    function reopen(delay) {
+        if (closed)
+            return;
+        source?.close();
+        source = undefined;
+        cancelReopen?.();
+        cancelReopen = timer(() => {
+            cancelReopen = undefined;
+            open();
+        }, delay);
+    }
+    /** The first page; on failure (and nothing to show) try again after a backoff instead of giving up. */
+    async function begin() {
+        const ok = await page();
+        if (closed)
+            return;
+        if (ok || feed.value().entries.length > 0) {
+            if (ok)
+                failures = 0;
+            open();
+            return;
+        }
+        const delay = backoff();
+        failures++;
+        cancelReopen?.();
+        cancelReopen = timer(() => {
+            cancelReopen = undefined;
+            void begin();
+        }, delay);
+    }
+    const loadingReasoning = new Set();
+    async function reasoningFor(cursor) {
+        const { feed: f } = options;
+        if (options.reasoning !== true || closed || loadingReasoning.has(cursor))
+            return;
+        if (f.beginReasoning === undefined || !changedBy(f.beginReasoning(cursor)))
+            return;
+        loadingReasoning.add(cursor);
+        publish(); // the entry now reads "loading"
+        try {
+            let body;
+            let gone = false;
+            try {
+                const res = await options.fetch(`${baseUrl}/reasoning?cursor=${encodeURIComponent(cursor)}`, {
+                    signal: ac.signal,
+                });
+                if (!res.ok) {
+                    gone = res.status === 404 || res.status === 403;
+                    throw new Error("not ok");
+                }
+                const declared = Number(res.headers?.get("content-length"));
+                if (Number.isFinite(declared) && declared > MAX_REASONING_RESPONSE_BYTES)
+                    throw new Error("too large");
+                if (res.text !== undefined) {
+                    const raw = await res.text();
+                    if (raw.length > MAX_REASONING_RESPONSE_BYTES)
+                        throw new Error("too large");
+                    body = JSON.parse(raw);
+                }
+                else
+                    body = await res.json();
+            }
+            catch {
+                if (closed)
+                    return;
+                // A refusal is a settled "none for you" (no retry); anything else is a failure the reader can retry.
+                if (gone)
+                    f.reasoningUnavailable?.(cursor);
+                else {
+                    f.reasoningFailed?.(cursor);
+                    report("reasoning-unavailable", "the reasoning could not be loaded");
+                }
+                publish();
+                return;
+            }
+            if (closed)
+                return;
+            if (changedBy(f.applyReasoning?.(cursor, body)))
+                publish();
+        }
+        finally {
+            loadingReasoning.delete(cursor);
+        }
+    }
+    return {
+        start: begin,
+        loadReasoning: reasoningFor,
+        async loadOlder() {
+            const cursor = feed.olderCursor();
+            if (cursor === undefined || loadingOlder || closed)
+                return;
+            loadingOlder = true;
+            try {
+                await page(cursor);
+            }
+            finally {
+                loadingOlder = false;
+            }
+        },
+        close() {
+            closed = true;
+            ac.abort();
+            cancelReopen?.();
+            source?.close();
+            source = undefined;
+        },
+    };
+}
+/**
+ * A `publish` that writes the transcript to a handle THROUGH a controller's gate (`publishValue`):
+ * refused (a finding, nothing written) for a handle the experience does not bind, one that is
+ * restricted for the viewer, one that is not a `Chat`, or a value that fails the `ChatValue`
+ * contract. `pending` while a reply streams (a screen reader holds its announcements), `ready` once
+ * it is durable. Writing the store directly would bypass all of that.
+ */
+export function publishChat(controller, handle, onFinding) {
+    // It publishes Chat values; their contract is deferred in core.
+    useChatContracts();
+    return (value, meta) => {
+        const r = controller.publishValue(handle, value, {
+            state: meta.streaming ? "pending" : "ready",
+            kind: "Chat",
+        });
+        if (!r.ok)
+            onFinding?.(r.finding);
+    };
+}
+//# sourceMappingURL=chatSource.js.map

package/dist/esm/chatSource.js.map

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

package/dist/esm/client.js

@@ -0,0 +1,15 @@
+// ── @loomwork/ui-hydration/client: the browser entry ─────────────────────────────────
+// Everything a browser needs for SPLIT hydration and nothing that executes a provider: the split
+// controller, the loader contract it calls, the store it publishes to, and param checks. The
+// server half (`handleInventory`, `serveHandles`, `executeProvider`, the invokers and reshapers)
+// stays on the root entry, `@loomwork/ui-hydration`, which imports the sandbox and the MCP plugin.
+// `clientEntry.test.ts` fails the build if this entry's module graph ever reaches them.
+export { HYDRATION_PROJECTION_ID, HYDRATION_PROJECTION_VERSION, HYDRATION_SET_EVENT, HydrationStore, hydrationProjection, isReservedHandle, } from "./projection";
+export { HYDRATION_VALUES_PREFIX, handleOfPath } from "./path";
+export { DEFAULT_TIME_RANGE, checkParams } from "./params";
+export { stepReferences, terminalSteps, topoWaves } from "./plan";
+export { jsonPathSelect } from "./select";
+export { outputShapeHashOf } from "./shape";
+export { SplitHydrationController } from "./split/client";
+export { connectConversation, publishChat } from "./chatSource";
+//# sourceMappingURL=client.js.map

package/dist/esm/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,iGAAiG;AACjG,6FAA6F;AAC7F,iGAAiG;AACjG,mGAAmG;AACnG,wFAAwF;AACxF,OAAO,EACL,uBAAuB,EACvB,4BAA4B,EAC5B,mBAAmB,EACnB,cAAc,EACd,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,cAAc,CAAC;AAQtB,OAAO,EAAE,uBAAuB,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAG3D,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE1C,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAG5C,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAQ1D,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC"}

package/dist/esm/contentRefs.js

@@ -0,0 +1,119 @@
+import { contentRefArgFindings, contentRefEntry, markedTopLevelKeys, parseContentRefTable, provenIn, stripNullContentRefs, toolKey, } from "@loomwork/ui-core";
+import { applyParamsDetailed } from "./params";
+// U9b, the SERVER half: a module of its own so that the browser entry (which imports params.ts) never
+// reaches `@loomwork/ui-core`'s root, which pulls in node:crypto.
+const bad = (code, message) => ({ code, severity: "error", message });
+export const contentRefEnv = (table, spec, gate, who) => ({
+    table,
+    handle: spec.handle,
+    steps: new Map(spec.executionGraph.map((s) => [s.stepId, s])),
+    ...(gate !== undefined && { acceptContentRefParam: gate }),
+    ...(who.principalId !== undefined && { principalId: who.principalId }),
+    ...(who.principal !== undefined && { principal: who.principal }),
+});
+/**
+ * U9b, defence in depth behind composition: after params are applied and BEFORE anything resolves,
+ * a marked content-reference argument must be absent / null, a step reference to an output its tool
+ * declares to be a content reference, or a param the host's gate accepted. A model-authored literal,
+ * an echo / concat reference, or an ungated param refuses the step, so the call is never made.
+ * `paramFilled` says a param filled a guarded argument (the caller then caches per principal only).
+ */
+export function checkContentRefs(node, applied, env) {
+    const entry = contentRefEntry(env.table, toolKey(node));
+    if (entry === undefined)
+        return { paramFilled: false };
+    const skip = new Set();
+    // A tool whose schema mentions the marker but cannot be read: every replaced param is gated.
+    const guarded = entry === "unknown"
+        ? new Set(applied.replaced)
+        : typeof entry === "string"
+            ? new Set()
+            : markedTopLevelKeys(entry);
+    let paramFilled = false;
+    for (const name of applied.replaced) {
+        if (!guarded.has(name))
+            continue;
+        paramFilled = true;
+        let ok = false;
+        try {
+            ok =
+                env.acceptContentRefParam?.({
+                    handle: env.handle,
+                    stepId: node.stepId,
+                    toolName: node.toolName,
+                    ...(node.kind !== undefined && { kind: node.kind }),
+                    param: name,
+                    value: applied.args[name],
+                    ...(env.principalId !== undefined && { principalId: env.principalId }),
+                    ...(env.principal !== undefined && { principal: env.principal }),
+                }) === true;
+        }
+        catch {
+            ok = false;
+        }
+        if (!ok)
+            return {
+                paramFilled,
+                finding: bad("media-arg-param-refused", `step "${node.stepId}": the param for "${name}" fills a content-reference argument and the host did not accept it`),
+            };
+        skip.add(name);
+    }
+    const found = contentRefArgFindings(applied.args, entry, `step "${node.stepId}"`, {
+        skipKeys: skip,
+        proven: provenIn(env.table, env.steps, node.stepId, toolKey),
+    }).find((f) => f.severity === "error");
+    return { paramFilled, ...(found !== undefined && { finding: found }) };
+}
+/** `args` without JSON null at the step's marked paths (a tool never sees `null` where a reference belongs). */
+export function finishContentRefArgs(node, args, table) {
+    const entry = contentRefEntry(table, toolKey(node));
+    return entry === undefined || typeof entry === "string"
+        ? args
+        : stripNullContentRefs(args, entry);
+}
+/**
+ * Judge a whole provider BEFORE a cache lookup: the same guard `executeProvider` runs per step, over
+ * every step, with the gate asked now. A cached value was produced for an argument the gate accepted
+ * once; serving it to another principal, or after the host revoked it, would skip the gate. A
+ * refusal means: do not serve from the cache (the load itself will refuse). `paramFilled` means the
+ * answer depends on who is asking: cache it per principal, never globally.
+ */
+export function inspectContentRefs(spec, params, env) {
+    let paramFilled = false;
+    for (const step of spec.executionGraph) {
+        const applied = applyParamsDetailed(step, params);
+        const r = checkContentRefs(step, applied, env);
+        paramFilled ||= r.paramFilled;
+        if (r.finding !== undefined)
+            return { refusal: r.finding, paramFilled };
+    }
+    return { paramFilled };
+}
+const PRINCIPAL_SCOPED = new WeakMap();
+/** `spec` with `cachePolicy.scope: "principal"` (memoised per spec object, so its fingerprint is computed once). */
+export function principalScoped(spec) {
+    if (spec.cachePolicy.scope === "principal")
+        return spec;
+    let s = PRINCIPAL_SCOPED.get(spec);
+    if (s === undefined) {
+        s = { ...spec, cachePolicy: { ...spec.cachePolicy, scope: "principal" } };
+        PRINCIPAL_SCOPED.set(spec, s);
+    }
+    return s;
+}
+/** `contentRefArgs` is missing or malformed: a configuration error, never read as "nothing is guarded". */
+export class ContentRefConfigError extends Error {
+    code = "content-ref-config";
+    constructor(where) {
+        super(`${where}: contentRefArgs is required: pass the table contentRefArgsFrom(capabilities) builds (a malformed or missing one is refused, never read as "none"), or the explicit opt-out "none"`);
+        this.name = "ContentRefConfigError";
+    }
+}
+/** Throws {@link ContentRefConfigError} unless `value` is `"none"` or exactly a well-formed table. */
+export function assertContentRefConfig(value, where) {
+    if (value === "none")
+        return;
+    if (parseContentRefTable(value) === undefined)
+        throw new ContentRefConfigError(where);
+}
+//# sourceMappingURL=contentRefs.js.map

package/dist/esm/contentRefs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contentRefs.js","sourceRoot":"","sources":["../../src/contentRefs.ts"],"names":[],"mappings":"AACA,OAAO,EAKL,qBAAqB,EACrB,eAAe,EACf,kBAAkB,EAClB,oBAAoB,EACpB,QAAQ,EACR,oBAAoB,EACpB,OAAO,GACR,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAmB,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAEhE,sGAAsG;AACtG,kEAAkE;AAElE,MAAM,GAAG,GAAG,CAAC,IAAY,EAAE,OAAe,EAAW,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;AAwC/F,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,KAAsB,EACtB,IAAkB,EAClB,IAAqC,EACrC,GAAsF,EACvE,EAAE,CAAC,CAAC;IACnB,KAAK;IACL,MAAM,EAAE,IAAI,CAAC,MAAM;IACnB,KAAK,EAAE,IAAI,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAU,CAAC,CAAC;IACtE,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,qBAAqB,EAAE,IAAI,EAAE,CAAC;IAC1D,GAAG,CAAC,GAAG,CAAC,WAAW,KAAK,SAAS,IAAI,EAAE,WAAW,EAAE,GAAG,CAAC,WAAW,EAAE,CAAC;IACtE,GAAG,CAAC,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC;CACjE,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAiB,EACjB,OAAyF,EACzF,GAAkB;IAElB,MAAM,KAAK,GAAG,eAAe,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACxD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;IACvD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,6FAA6F;IAC7F,MAAM,OAAO,GACX,KAAK,KAAK,SAAS;QACjB,CAAC,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC;QAC3B,CAAC,CAAC,OAAO,KAAK,KAAK,QAAQ;YACzB,CAAC,CAAC,IAAI,GAAG,EAAU;YACnB,CAAC,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAClC,IAAI,WAAW,GAAG,KAAK,CAAC;IACxB,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACpC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAS;QACjC,WAAW,GAAG,IAAI,CAAC;QACnB,IAAI,EAAE,GAAG,KAAK,CAAC;QACf,IAAI,CAAC;YACH,EAAE;gBACA,GAAG,CAAC,qBAAqB,EAAE,CAAC;oBAC1B,MAAM,EAAE,GAAG,CAAC,MAAM;oBAClB,MAAM,EAAE,IAAI,CAAC,MAAM;oBACnB,QAAQ,EAAE,IAAI,CAAC,QAAQ;oBACvB,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;oBACnD,KAAK,EAAE,IAAI;oBACX,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;oBACzB,GAAG,CAAC,GAAG,CAAC,WAAW,KAAK,SAAS,IAAI,EAAE,WAAW,EAAE,GAAG,CAAC,WAAW,EAAE,CAAC;oBACtE,GAAG,CAAC,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC;iBACjE,CAAC,KAAK,IAAI,CAAC;QAChB,CAAC;QAAC,MAAM,CAAC;YACP,EAAE,GAAG,KAAK,CAAC;QACb,CAAC;QACD,IAAI,CAAC,EAAE;YACL,OAAO;gBACL,WAAW;gBACX,OAAO,EAAE,GAAG,CACV,yBAAyB,EACzB,SAAS,IAAI,CAAC,MAAM,qBAAqB,IAAI,qEAAqE,CACnH;aACF,CAAC;QACJ,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACjB,CAAC;IACD,MAAM,KAAK,GAAG,qBAAqB,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,IAAI,CAAC,MAAM,GAAG,EAAE;QAChF,QAAQ,EAAE,IAAI;QACd,MAAM,EAAE,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC;KAC7D,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC;IACvC,OAAO,EAAE,WAAW,EAAE,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;AACzE,CAAC;AAED,gHAAgH;AAChH,MAAM,UAAU,oBAAoB,CAClC,IAAiB,EACjB,IAA6B,EAC7B,KAAsB;IAEtB,MAAM,KAAK,GAAG,eAAe,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACpD,OAAO,KAAK,KAAK,SAAS,IAAI,OAAO,KAAK,KAAK,QAAQ;QACrD,CAAC,CAAC,IAAI;QACN,CAAC,CAAC,oBAAoB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAkB,EAClB,MAAkB,EAClB,GAAkB;IAElB,IAAI,WAAW,GAAG,KAAK,CAAC;IACxB,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;QACvC,MAAM,OAAO,GAAG,mBAAmB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAClD,MAAM,CAAC,GAAG,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;QAC/C,WAAW,KAAK,CAAC,CAAC,WAAW,CAAC;QAC9B,IAAI,CAAC,CAAC,OAAO,KAAK,SAAS;YAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,WAAW,EAAE,CAAC;IAC1E,CAAC;IACD,OAAO,EAAE,WAAW,EAAE,CAAC;AACzB,CAAC;AAED,MAAM,gBAAgB,GAAG,IAAI,OAAO,EAA8B,CAAC;AAEnE,oHAAoH;AACpH,MAAM,UAAU,eAAe,CAAC,IAAkB;IAChD,IAAI,IAAI,CAAC,WAAW,CAAC,KAAK,KAAK,WAAW;QAAE,OAAO,IAAI,CAAC;IACxD,IAAI,CAAC,GAAG,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;QACpB,CAAC,GAAG,EAAE,GAAG,IAAI,EAAE,WAAW,EAAE,EAAE,GAAG,IAAI,CAAC,WAAW,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,CAAC;QAC1E,gBAAgB,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,2GAA2G;AAC3G,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IACrC,IAAI,GAAG,oBAAoB,CAAC;IACrC,YAAY,KAAa;QACvB,KAAK,CACH,GAAG,KAAK,oLAAoL,CAC7L,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED,sGAAsG;AACtG,MAAM,UAAU,sBAAsB,CAAC,KAAc,EAAE,KAAa;IAClE,IAAI,KAAK,KAAK,MAAM;QAAE,OAAO;IAC7B,IAAI,oBAAoB,CAAC,KAAK,CAAC,KAAK,SAAS;QAAE,MAAM,IAAI,qBAAqB,CAAC,KAAK,CAAC,CAAC;AACxF,CAAC"}