@descryy/mcp 0.2.0 → 0.4.0

package/dist/browser/fake-driver.js

@@ -0,0 +1,161 @@
+/**
+ * A `BrowserDriver` with no browser behind it.
+ *
+ * Not a stub. It implements every rule the port states — ref issuance and
+ * invalidation, drain-not-peek, crash invalidation, idempotent close that
+ * still flushes — and `browser-driver-contract.test.ts` runs the same
+ * assertions against it that the real driver will have to pass. Its purpose
+ * is to make those rules *checkable in milliseconds*, so the session
+ * lifecycle in §4 is tested against timeouts, disconnects and crashes that
+ * would otherwise each need a real Chromium.
+ *
+ * Two deliberate non-goals. It does not simulate a page — pages are declared
+ * with `setPage`, because a fake DOM would be a second, wrong browser. And it
+ * does not classify anything, for the same structural reason the port does
+ * not: there is nowhere to put a verdict.
+ */
+import { randomUUID } from "node:crypto";
+import { BrowserSessionCrashedError, UnknownElementRefError, } from "./driver.js";
+const EMPTY_PAGE = (url) => ({ url, title: "", elements: [] });
+export function createFakeBrowserDriver() {
+    const pages = new Map();
+    const states = new Map();
+    let chromiumMissing = null;
+    // Monotonic across the driver, so a ref from one session can never resolve
+    // in another — the same property real refs have by being page-scoped.
+    let snapshotGeneration = 0;
+    function stateOf(sessionId) {
+        const state = states.get(sessionId);
+        if (state === undefined)
+            throw new Error(`no such fake session: ${sessionId}`);
+        return state;
+    }
+    function drain(state) {
+        const observation = {
+            actions: state.buffer.actions,
+            consoleErrors: state.buffer.consoleErrors,
+            requests: state.buffer.requests,
+        };
+        state.buffer.actions = [];
+        state.buffer.consoleErrors = [];
+        state.buffer.requests = [];
+        return observation;
+    }
+    function openSession(targetUrl) {
+        const sessionId = randomUUID();
+        let url = targetUrl;
+        // Refs live here, keyed by the generation that issued them. Navigation
+        // replaces the map wholesale, which is what makes a stale ref refuse
+        // rather than resolve against a page nobody inspected.
+        let refs = new Map();
+        const buffer = { actions: [], consoleErrors: [], requests: [] };
+        function assertUsable() {
+            const state = states.get(sessionId);
+            if (state !== undefined && (state.crashed || state.closed))
+                throw new BrowserSessionCrashedError(sessionId);
+        }
+        function resolve(ref) {
+            const element = refs.get(ref);
+            if (element === undefined)
+                throw new UnknownElementRefError(ref);
+            return element;
+        }
+        function record(action, ref, mode = null) {
+            buffer.actions.push({ action, ref, mode, url, at: new Date().toISOString() });
+        }
+        const session = {
+            sessionId,
+            startedAt: new Date().toISOString(),
+            isUsable() {
+                const state = states.get(sessionId);
+                return state !== undefined && !state.crashed && !state.closed;
+            },
+            currentUrl: () => url,
+            async navigate(to) {
+                assertUsable();
+                url = to;
+                refs = new Map();
+                record("navigate", null);
+            },
+            async snapshot() {
+                assertUsable();
+                const page = pages.get(url) ?? EMPTY_PAGE(url);
+                snapshotGeneration += 1;
+                refs = new Map(page.elements.map((element, index) => {
+                    const ref = `ref-${snapshotGeneration}-${index}`;
+                    return [ref, { ref, role: element.role, name: element.name, selector: element.selector }];
+                }));
+                const elements = [...refs.values()];
+                return { url, title: page.title, elements, totalElements: elements.length };
+            },
+            async click(ref) {
+                assertUsable();
+                resolve(ref);
+                record("click", ref);
+            },
+            async type(ref, _text) {
+                assertUsable();
+                resolve(ref);
+                record("type", ref, "append");
+            },
+            async fill(ref, _text) {
+                assertUsable();
+                resolve(ref);
+                record("fill", ref, "replace");
+            },
+            async drainEvidence() {
+                // Deliberately usable on a crashed session: the whole point of the
+                // flush-on-every-path rule is that a crash must not take the evidence
+                // that preceded it.
+                return drain(stateOf(sessionId));
+            },
+            async close() {
+                const state = stateOf(sessionId);
+                state.closed = true;
+                return drain(state);
+            },
+        };
+        states.set(sessionId, { session, buffer, crashed: false, closed: false });
+        return session;
+    }
+    return {
+        async launch(options) {
+            if (chromiumMissing !== null) {
+                return {
+                    launched: false,
+                    refusal: "chromiumNotInstalled",
+                    message: "No Chromium executable at /fake/path/chrome. This package depends on playwright-core, which does " +
+                        "not download a browser on install, so one has to be installed once before a browser session can launch.",
+                    remedy: chromiumMissing.remedy,
+                    expectedExecutablePath: "/fake/path/chrome",
+                };
+            }
+            return { launched: true, session: openSession(options.targetUrl) };
+        },
+        setPage(url, page) {
+            pages.set(url, page);
+        },
+        setChromiumMissing(remedy = "npx playwright install chromium") {
+            // A remedy string is required rather than defaulted to empty: the
+            // contract test asserts one is present, and a fake that could refuse
+            // without one would let the real driver ship without one too.
+            chromiumMissing = { remedy };
+        },
+        emitConsoleError(sessionId, error) {
+            stateOf(sessionId).buffer.consoleErrors.push({ ...error, at: new Date().toISOString() });
+        },
+        emitRequest(sessionId, request) {
+            stateOf(sessionId).buffer.requests.push({ stackTrace: null, ...request, at: new Date().toISOString() });
+        },
+        emitFailedRequest(sessionId, request) {
+            stateOf(sessionId).buffer.requests.push({ ...request, stackTrace: null, at: new Date().toISOString() });
+        },
+        crash(sessionId) {
+            stateOf(sessionId).crashed = true;
+        },
+        openSessionIds() {
+            return [...states.entries()].filter(([, state]) => !state.closed).map(([id]) => id);
+        },
+    };
+}
+//# sourceMappingURL=fake-driver.js.map

package/dist/browser/fake-driver.js.map

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

package/dist/browser/graph-write.d.ts

@@ -0,0 +1,86 @@
+/**
+ * §5.4 — the payoff. A real browser action becomes a real R4 edge.
+ *
+ * ## What this closes
+ *
+ * The UAT's verdict on runtime evidence was that it proves *"this line
+ * touched this function"* and never *"this frontend action reached this
+ * backend route"* — the cross-boundary confirmation the product's own
+ * description leads with. Everything needed for the second claim was built
+ * and none of it was joined: the browser package captures a real `fetch()`
+ * call-site stack, `confirmObservedFrontendCaller` writes R4 from one, and
+ * `applyRuntimeObservations` is the write path. This module is the join,
+ * reached from an MCP tool call.
+ *
+ * ## Why the edge matters more than the reply
+ *
+ * `impact` and `propagation` already join a frontend caller to a backend
+ * route by **comparing `"GET /business-info"` as a string on both sides**.
+ * That is an R1 name match: it is right often and it cannot know when it is
+ * wrong. What this writes is the same edge *witnessed* — a real click, a real
+ * request, a real call-site stack resolved to a real file — at `resolution:
+ * 4` carrying the run that saw it. No new query tool is needed and none is
+ * added: `impact` and the rest already read `resolution` and pick these up.
+ *
+ * ## Precision over recall, enforced by omission
+ *
+ * Every step that cannot be established drops the observation entirely rather
+ * than weakening it. No parsed stack, no endpoint resolved, an ambiguous
+ * match — each produces **no edge**, not a low-confidence one. A wrong edge
+ * corrupts diff scoping, impact scores and root-cause traversal on every
+ * later run; a missing one is a disclosed gap, and the disclosures below are
+ * how it gets disclosed.
+ *
+ * Note also what is *not* here: no denial. A run establishes that a call
+ * happened and can never establish that one did not — a page visit exercises
+ * one path, and the absence of a stack for some other function is absence of
+ * evidence. `confirmObservedFrontendCaller` refuses to mint denials for the
+ * same reason; this caller must not reintroduce one by another route.
+ */
+import type { SqlDriver } from "@descryy/core";
+import { type ObservedRequest } from "./driver.ts";
+/** A graph node this browser evidence actually reached — §5.3's "any graph node reached, surfaced in the same reply". */
+export interface ReachedNode {
+    readonly nodeId: string;
+    readonly name: string;
+    readonly type: string;
+    /** The request that reached it, so a reader can see which action this was. */
+    readonly via: {
+        readonly method: string;
+        readonly url: string;
+        readonly status: number | null;
+    };
+}
+export interface BrowserGraphWrite {
+    /** Endpoints the page's own requests resolved to, whether or not an edge was written. */
+    readonly reached: readonly ReachedNode[];
+    /** Existing edges promoted to R4 by this observation. */
+    readonly promoted: readonly string[];
+    /** Edges the structural side never named, minted at R4 — the recall gap closing. */
+    readonly created: readonly string[];
+    /** Reasons an observation was declined. Kept, because a silent drop is indistinguishable from nothing having happened. */
+    readonly refused: readonly string[];
+    /** R4-vs-R4 disagreements, passed through untouched — this module does not adjudicate them. */
+    readonly contradictions: readonly string[];
+}
+export declare const NO_GRAPH_WRITE: BrowserGraphWrite;
+export interface BrowserGraphWriteInput {
+    readonly driver: SqlDriver;
+    readonly repo: string;
+    readonly runId: string;
+    readonly commitSha: string;
+    readonly repoRoot: string;
+    readonly requests: readonly ObservedRequest[];
+}
+/**
+ * Correlate what the page did against the graph, and record what was
+ * genuinely witnessed.
+ *
+ * Runs over **every** request, not only the failures. A successful call is
+ * the thing that proves the arrow; narrowing to failures here would mean the
+ * feature only ever confirmed edges on broken pages.
+ */
+export declare function writeBrowserObservations(input: BrowserGraphWriteInput): BrowserGraphWrite;
+/** What a reply says about a write. Empty when nothing was reached — silence about nothing is not a disclosure gap. */
+export declare function graphWriteNotes(write: BrowserGraphWrite, requests: readonly ObservedRequest[]): string[];
+//# sourceMappingURL=graph-write.d.ts.map

package/dist/browser/graph-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-write.d.ts","sourceRoot":"","sources":["../../src/browser/graph-write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAG/C,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAEpE,yHAAyH;AACzH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,QAAQ,CAAC,GAAG,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CACjG;AAED,MAAM,WAAW,iBAAiB;IAChC,yFAAyF;IACzF,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;IACzC,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,oFAAoF;IACpF,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,0HAA0H;IAC1H,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,+FAA+F;IAC/F,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C;AAED,eAAO,MAAM,cAAc,EAAE,iBAA+F,CAAC;AAE7H,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;CAC/C;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,sBAAsB,GAAG,iBAAiB,CAiEzF;AAED,uHAAuH;AACvH,wBAAgB,eAAe,CAAC,KAAK,EAAE,iBAAiB,EAAE,QAAQ,EAAE,SAAS,eAAe,EAAE,GAAG,MAAM,EAAE,CAiCxG"}

package/dist/browser/graph-write.js

@@ -0,0 +1,135 @@
+/**
+ * §5.4 — the payoff. A real browser action becomes a real R4 edge.
+ *
+ * ## What this closes
+ *
+ * The UAT's verdict on runtime evidence was that it proves *"this line
+ * touched this function"* and never *"this frontend action reached this
+ * backend route"* — the cross-boundary confirmation the product's own
+ * description leads with. Everything needed for the second claim was built
+ * and none of it was joined: the browser package captures a real `fetch()`
+ * call-site stack, `confirmObservedFrontendCaller` writes R4 from one, and
+ * `applyRuntimeObservations` is the write path. This module is the join,
+ * reached from an MCP tool call.
+ *
+ * ## Why the edge matters more than the reply
+ *
+ * `impact` and `propagation` already join a frontend caller to a backend
+ * route by **comparing `"GET /business-info"` as a string on both sides**.
+ * That is an R1 name match: it is right often and it cannot know when it is
+ * wrong. What this writes is the same edge *witnessed* — a real click, a real
+ * request, a real call-site stack resolved to a real file — at `resolution:
+ * 4` carrying the run that saw it. No new query tool is needed and none is
+ * added: `impact` and the rest already read `resolution` and pick these up.
+ *
+ * ## Precision over recall, enforced by omission
+ *
+ * Every step that cannot be established drops the observation entirely rather
+ * than weakening it. No parsed stack, no endpoint resolved, an ambiguous
+ * match — each produces **no edge**, not a low-confidence one. A wrong edge
+ * corrupts diff scoping, impact scores and root-cause traversal on every
+ * later run; a missing one is a disclosed gap, and the disclosures below are
+ * how it gets disclosed.
+ *
+ * Note also what is *not* here: no denial. A run establishes that a call
+ * happened and can never establish that one did not — a page visit exercises
+ * one path, and the absence of a stack for some other function is absence of
+ * evidence. `confirmObservedFrontendCaller` refuses to mint denials for the
+ * same reason; this caller must not reintroduce one by another route.
+ */
+import { confirmObservedFrontendCaller, resolveEndpointNode } from "@descryy/runtime-graph-correlator";
+import { isFailedRequest } from "./driver.js";
+export const NO_GRAPH_WRITE = { reached: [], promoted: [], created: [], refused: [], contradictions: [] };
+/**
+ * Correlate what the page did against the graph, and record what was
+ * genuinely witnessed.
+ *
+ * Runs over **every** request, not only the failures. A successful call is
+ * the thing that proves the arrow; narrowing to failures here would mean the
+ * feature only ever confirmed edges on broken pages.
+ */
+export function writeBrowserObservations(input) {
+    const reached = [];
+    const promoted = [];
+    const created = [];
+    const refused = [];
+    const contradictions = [];
+    const seen = new Set();
+    for (const request of input.requests) {
+        let path;
+        try {
+            path = new URL(request.url).pathname;
+        }
+        catch {
+            continue;
+        }
+        const resolution = resolveEndpointNode(input.driver, request.method, path);
+        if (resolution.outcome !== "resolved") {
+            // Not a refusal worth reporting per request: a page issues requests for
+            // stylesheets, images and third-party origins, and none of them is
+            // meant to be an endpoint in this graph. Reporting each as a miss would
+            // bury the real ones.
+            continue;
+        }
+        const endpoint = resolution.node;
+        const key = `${endpoint.id}::${request.method}::${path}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            reached.push({
+                nodeId: endpoint.id,
+                name: endpoint.name,
+                type: endpoint.type,
+                via: { method: request.method, url: request.url, status: request.status },
+            });
+        }
+        if (request.stackTrace === null) {
+            // The endpoint was reached and we can say so; the *caller* half needs a
+            // parsed stack and there is none. Disclosed rather than dropped,
+            // because "we saw this route get hit but could not tell you from where"
+            // is a real, useful, incomplete answer.
+            refused.push(`${request.method} ${path} reached ${endpoint.name}, but no parsed call-site stack was captured, so no ` +
+                "caller edge was written. Name a stackParser on browser_start_session to capture one.");
+            continue;
+        }
+        const outcome = confirmObservedFrontendCaller(input.driver, {
+            endpointNodeId: endpoint.id,
+            stackTrace: request.stackTrace,
+            repo: input.repo,
+            runId: input.runId,
+            commitSha: input.commitSha,
+            repoRoot: input.repoRoot,
+        });
+        promoted.push(...outcome.confirmation.promoted);
+        created.push(...outcome.confirmation.created);
+        refused.push(...outcome.confirmation.refused.map((r) => r.reason));
+        contradictions.push(...outcome.confirmation.contradictions.map((c) => c.detail));
+    }
+    return { reached, promoted, created, refused, contradictions };
+}
+/** What a reply says about a write. Empty when nothing was reached — silence about nothing is not a disclosure gap. */
+export function graphWriteNotes(write, requests) {
+    const notes = [];
+    const confirmed = write.promoted.length + write.created.length;
+    if (confirmed > 0) {
+        notes.push(`${confirmed} frontend→backend edge(s) were confirmed at resolution 4 from this run — ` +
+            `${write.promoted.length} existing edge(s) promoted, ${write.created.length} minted that static ` +
+            "analysis had not found. These are witnessed, not name-matched: a real request carrying a real " +
+            "call-site stack. impact and propagation read them with no further action.");
+    }
+    if (write.reached.length > 0 && confirmed === 0) {
+        notes.push(`${write.reached.length} endpoint(s) in the graph were reached by this page, but no caller edge was ` +
+            "written — see the refusals for why. The endpoints are named so the gap is visible rather than absent.");
+    }
+    if (write.contradictions.length > 0) {
+        notes.push(`${write.contradictions.length} observation(s) disagree with an existing R4 edge. Reported, not resolved: ` +
+            "adjudicating two runtime observations against each other is not this call's job.");
+    }
+    const unexplained = requests.filter((r) => r.stackTrace === null && !isFailedRequest(r)).length;
+    if (unexplained > 0 && confirmed === 0 && write.reached.length === 0) {
+        notes.push(`${requests.length} request(s) were observed and none resolved to an endpoint in the graph. If this ` +
+            "repository has not been analysed, run analyze first — nothing here can be related to code the graph " +
+            "does not hold.");
+    }
+    return notes;
+}
+//# sourceMappingURL=graph-write.js.map

package/dist/browser/graph-write.js.map

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

package/dist/browser/playwright-driver.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The real `BrowserDriver`, over `@descryy/runtime-browser`.
+ *
+ * ## Why the import is dynamic
+ *
+ * `@descryy/runtime-browser` is not on the npm registry yet
+ * (`mcp-browser-tools.md` §3.1 — the publish returns 429 on new-scoped-package
+ * creation). Declaring it in `package.json` today would break `npm install`
+ * for everyone, including the lanes that never touch a browser. So it is
+ * imported by specifier at call time and its absence is a **named refusal
+ * with a remedy**, exactly as a missing Chromium is.
+ *
+ * That is a temporary shape and it is written down as one: the final swap
+ * (§8's tool-count item) declares the dependency and makes this a static
+ * import. What must *not* happen in the meantime is the tools quietly
+ * appearing to work — see `provider.ts`.
+ *
+ * ## What this adds over the runtime package, and what it deliberately does not
+ *
+ * It adds exactly one thing the runtime has no API for: **element refs.** The
+ * port's contract is that an action names an element the agent has seen, and
+ * `BrowserActionCollector` acts on raw selectors. So this module enumerates
+ * the page's interactive elements, holds a Playwright `ElementHandle` per ref,
+ * and drops the whole map on navigation. Handles rather than injected `data-`
+ * attributes on purpose: stamping the DOM would make the act of observing
+ * change the page being observed, and a detached element then fails naturally
+ * instead of resolving to whatever took its place.
+ *
+ * Everything else is composition. Launch, click, type, fill, console capture,
+ * network capture, the `fetch()` initiator stack and its source-map rewrite
+ * are all the runtime package's, called rather than reimplemented.
+ *
+ * ## Rule 1
+ *
+ * No language is named here. The stack-trace parser that turns a raw browser
+ * stack into resolved frames is handed in by the caller as a module specifier
+ * — the same mechanism `runtime-registry.ts` uses for runtime adapters, for
+ * the same reason. Without one, requests are still observed and no caller
+ * edge is written; the reply says so.
+ */
+import type { ServiceRootLookup } from "@descryy/runtime-contracts";
+import type { StackTraceParser } from "@descryy/runtime-backend-observation";
+import type { BrowserDriver } from "./driver.ts";
+export interface PlaywrightDriverOptions {
+    /**
+     * Turns a raw browser stack into resolved frames. Supplied by the caller;
+     * this package cannot construct one without naming a language.
+     *
+     * Absent, the initiator capture is not installed at all — the runtime's own
+     * two-halves-or-neither rule — so no request carries a call site and no R4
+     * caller edge can be written.
+     */
+    readonly stackParser?: StackTraceParser;
+    /** Maps a page origin to the on-disk root that served it. Absent means script URLs stay unresolved. */
+    readonly resolveSourceRoot?: SourceRootResolver;
+    /** Which service the evidence is attributed to. */
+    readonly service?: string;
+}
+type SourceRootResolver = (origin: string) => ServiceRootLookup;
+export declare class BrowserBackendMissingError extends Error {
+    constructor(cause: unknown);
+}
+export declare function createPlaywrightBrowserDriver(options?: PlaywrightDriverOptions): Promise<BrowserDriver>;
+export {};
+//# sourceMappingURL=playwright-driver.d.ts.map

package/dist/browser/playwright-driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playwright-driver.d.ts","sourceRoot":"","sources":["../../src/browser/playwright-driver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EAAc,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAChF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sCAAsC,CAAC;AAmB7E,OAAO,KAAK,EACV,aAAa,EAUd,MAAM,aAAa,CAAC;AAgBrB,MAAM,WAAW,uBAAuB;IACtC;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,gBAAgB,CAAC;IACxC,uGAAuG;IACvG,QAAQ,CAAC,iBAAiB,CAAC,EAAE,kBAAkB,CAAC;IAChD,mDAAmD;IACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,KAAK,kBAAkB,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,iBAAiB,CAAC;AA+ChE,qBAAa,0BAA2B,SAAQ,KAAK;gBACvC,KAAK,EAAE,OAAO;CAO3B;AAgBD,wBAAsB,6BAA6B,CAAC,OAAO,GAAE,uBAA4B,GAAG,OAAO,CAAC,aAAa,CAAC,CAmBjH"}