@monoes/monomindcli 2.13.0 → 2.14.1

package/dist/src/knowledge/mhtml.js

@@ -0,0 +1,154 @@
+/**
+ * MHTML / MHT container parsing (RCL-01).
+ *
+ * An MHTML archive is an RFC 2557 `multipart/related` MIME message: the page
+ * plus every subresource it referenced, each part carrying its own transfer
+ * encoding and charset. Chrome's `Page.captureSnapshot` writes them
+ * quoted-printable; Internet Explorer and most "save as web archive" tools
+ * write base64.
+ *
+ * Only the ROOT frame is prose. Picking the first `text/html` part instead is
+ * how an ad iframe ends up indexed as the article, so the root is resolved
+ * from the container's `Snapshot-Content-Location` / `Content-Location` when
+ * one is present.
+ *
+ * Read the file as `latin1` (or pass a Buffer): byte fidelity matters before
+ * transfer decoding, and the real charset is only known per part.
+ *
+ * @module v1/cli/knowledge/mhtml
+ */
+/** Decode a quoted-printable body to bytes: soft line breaks vanish, `=XX`
+ *  becomes one byte, everything else is its own latin1 byte. */
+export function decodeQuotedPrintable(input) {
+    const out = [];
+    for (let i = 0; i < input.length; i++) {
+        const ch = input[i];
+        if (ch !== '=') {
+            out.push(input.charCodeAt(i) & 0xff);
+            continue;
+        }
+        if (input[i + 1] === '\r' && input[i + 2] === '\n') {
+            i += 2; // soft line break
+            continue;
+        }
+        if (input[i + 1] === '\n') {
+            i += 1; // soft line break, LF-only file
+            continue;
+        }
+        const hex = input.slice(i + 1, i + 3);
+        if (/^[0-9a-fA-F]{2}$/.test(hex)) {
+            out.push(Number.parseInt(hex, 16));
+            i += 2;
+            continue;
+        }
+        out.push(0x3d); // a lone `=` — keep it
+    }
+    return Buffer.from(out);
+}
+function decodeBody(raw, encoding) {
+    switch (encoding) {
+        case 'quoted-printable':
+            return decodeQuotedPrintable(raw);
+        case 'base64':
+            return Buffer.from(raw.replace(/\s+/g, ''), 'base64');
+        default:
+            return Buffer.from(raw, 'latin1');
+    }
+}
+/** Decode bytes under a MIME charset, falling back to UTF-8 (then latin1)
+ *  rather than failing an ingest over an exotic label. */
+export function decodeCharset(bytes, charset) {
+    const label = (charset ?? 'utf-8').trim().toLowerCase();
+    for (const candidate of [label, 'utf-8']) {
+        try {
+            return new TextDecoder(candidate, { fatal: false }).decode(bytes);
+        }
+        catch {
+            /* unknown label — try the next */
+        }
+    }
+    return bytes.toString('latin1');
+}
+/** Split a MIME chunk into unfolded headers and the body after the first
+ *  blank line. Continuation lines (leading space/tab) join their header. */
+function splitHeaders(chunk) {
+    const sep = /\r?\n\r?\n/.exec(chunk);
+    const headerText = sep ? chunk.slice(0, sep.index) : chunk;
+    const body = sep ? chunk.slice(sep.index + sep[0].length) : '';
+    const headers = {};
+    let current = '';
+    for (const rawLine of headerText.split(/\r?\n/)) {
+        if (/^[ \t]/.test(rawLine) && current) {
+            headers[current] += ` ${rawLine.trim()}`;
+            continue;
+        }
+        const colon = rawLine.indexOf(':');
+        if (colon === -1)
+            continue;
+        current = rawLine.slice(0, colon).trim().toLowerCase();
+        headers[current] = rawLine.slice(colon + 1).trim();
+    }
+    return { headers, body };
+}
+function param(headerValue, name) {
+    if (!headerValue)
+        return null;
+    const m = new RegExp(`${name}\\s*=\\s*("[^"]*"|'[^']*'|[^;\\s]+)`, 'i').exec(headerValue);
+    return m ? m[1].replace(/^["']|["']$/g, '') : null;
+}
+function toPart(chunk) {
+    const { headers, body } = splitHeaders(chunk);
+    const contentType = (headers['content-type'] ?? 'text/html').split(';')[0].trim().toLowerCase();
+    const encoding = (headers['content-transfer-encoding'] ?? 'binary').trim().toLowerCase();
+    return {
+        contentType,
+        charset: param(headers['content-type'], 'charset')?.toLowerCase() ?? null,
+        location: headers['content-location'] ?? null,
+        encoding,
+        body: decodeBody(body, encoding),
+        headers,
+    };
+}
+/**
+ * Parse an MHTML container. Anything that is not a well-formed multipart
+ * message is treated as a single part, so a plain `.html` file renamed to
+ * `.mhtml` still ingests.
+ */
+export function parseMhtml(raw) {
+    const text = typeof raw === 'string' ? raw : raw.toString('latin1');
+    const { headers, body } = splitHeaders(text);
+    const snapshotLocation = headers['snapshot-content-location'] ?? headers['content-location'] ?? null;
+    const subject = headers.subject ?? null;
+    const boundary = param(headers['content-type'], 'boundary');
+    let parts;
+    if (!boundary) {
+        // No boundary: either a single-part message or a bare HTML file. Feeding
+        // the whole document through `toPart` covers both — an HTML file has no
+        // header block, so everything lands in the body.
+        parts = [toPart(/^[a-z-]+:/i.test(text) ? text : `Content-Type: text/html\r\n\r\n${text}`)];
+    }
+    else {
+        const delimiter = `--${boundary}`;
+        parts = body
+            .split(delimiter)
+            .slice(1) // text before the first delimiter is the MIME preamble
+            .filter((chunk) => !chunk.startsWith('--')) // the closing `--boundary--`
+            .map((chunk) => chunk.replace(/^\r?\n/, ''))
+            .map(toPart);
+    }
+    const html = parts.filter((p) => p.contentType === 'text/html' || p.contentType === 'application/xhtml+xml');
+    const root = (snapshotLocation ? html.find((p) => p.location === snapshotLocation) : undefined) ??
+        html[0] ??
+        null;
+    return { root, parts, snapshotLocation, subject };
+}
+/** Parse a container and return its root frame decoded to a string. */
+export function mhtmlToHtml(raw) {
+    const parsed = parseMhtml(raw);
+    return {
+        html: parsed.root ? decodeCharset(parsed.root.body, parsed.root.charset) : '',
+        location: parsed.root?.location ?? parsed.snapshotLocation,
+        subject: parsed.subject,
+    };
+}
+//# sourceMappingURL=mhtml.js.map

package/dist/src/knowledge/mhtml.js.map

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

package/dist/src/knowledge/related.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Related-at-save (RCL-03) — "3 things in your brain relate to this".
+ *
+ * The extension calls this on EVERY capture, while the user watches. That
+ * single fact sets every design decision here:
+ *
+ *  - it never throws. An empty store, a missing embedder, a URL that was
+ *    never captured — all of them are an empty list, because a capture must
+ *    not fail because the sidebar had nothing to say;
+ *  - it is bounded. The vector pass races a timeout (default 2s) and the
+ *    cheap signals — same URL, same site, read straight off the metadata log —
+ *    are computed first, so a slow or absent embedder degrades to a fast
+ *    answer instead of no answer;
+ *  - the target itself is never in its own results, by path AND by canonical
+ *    URL, so a re-capture does not "relate" to the version it replaced.
+ *
+ * Three signals, combined: exact URL (the same page, captured before),
+ * same site, and vector similarity over the chunks already embedded.
+ *
+ * @module v1/cli/knowledge/related
+ */
+export type RelatedReason = 'same-url' | 'same-site' | 'similar';
+export interface RelatedDocument {
+    filePath: string;
+    scope: string;
+    title: string;
+    url?: string;
+    site?: string;
+    /** 0–1. Exact-URL matches lead; similarity and site agreement compound. */
+    score: number;
+    reasons: RelatedReason[];
+    capturedAt?: string;
+    /** The most similar passage, when similarity is one of the reasons. */
+    excerpt?: string;
+    chunkIndex?: number;
+    anchor?: string;
+}
+export interface RelatedOptions {
+    rootDir?: string;
+    scope?: string;
+    limit?: number;
+    /** Budget for the vector pass. The metadata signals ignore it: they are
+     *  synchronous file reads. */
+    timeoutMs?: number;
+    minScore?: number;
+    store?: 'project' | 'global' | 'all';
+    /** Text to compare against, when the caller already has it (a capture that
+     *  has not been ingested yet). */
+    text?: string;
+}
+/**
+ * The documents most related to `target` (a URL, a docId, or an indexed path).
+ *
+ * Safe to call on every capture: bounded, and empty rather than thrown on any
+ * failure.
+ */
+export declare function relatedDocuments(target: string, opts?: RelatedOptions): Promise<RelatedDocument[]>;
+//# sourceMappingURL=related.d.ts.map

package/dist/src/knowledge/related.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"related.d.ts","sourceRoot":"","sources":["../../../src/knowledge/related.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AASH,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,WAAW,GAAG,SAAS,CAAC;AAEjE,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;kCAC8B;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,KAAK,CAAC;IACrC;sCACkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAwFD;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,eAAe,EAAE,CAAC,CAmH5B"}

package/dist/src/knowledge/related.js

@@ -0,0 +1,222 @@
+/**
+ * Related-at-save (RCL-03) — "3 things in your brain relate to this".
+ *
+ * The extension calls this on EVERY capture, while the user watches. That
+ * single fact sets every design decision here:
+ *
+ *  - it never throws. An empty store, a missing embedder, a URL that was
+ *    never captured — all of them are an empty list, because a capture must
+ *    not fail because the sidebar had nothing to say;
+ *  - it is bounded. The vector pass races a timeout (default 2s) and the
+ *    cheap signals — same URL, same site, read straight off the metadata log —
+ *    are computed first, so a slow or absent embedder degrades to a fast
+ *    answer instead of no answer;
+ *  - the target itself is never in its own results, by path AND by canonical
+ *    URL, so a re-capture does not "relate" to the version it replaced.
+ *
+ * Three signals, combined: exact URL (the same page, captured before),
+ * same site, and vector similarity over the chunks already embedded.
+ *
+ * @module v1/cli/knowledge/related
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { captureIdentityUrl, readCaptureProvenance } from './capture-envelope.js';
+import { passageQuote } from './citation.js';
+import { documentCapturedAt, documentSite } from './library.js';
+const DEFAULT_LIMIT = 3;
+const DEFAULT_TIMEOUT_MS = 2000;
+const DEFAULT_MIN_SCORE = 0.25;
+const QUERY_CHARS = 1200;
+const SAME_URL_SCORE = 1;
+/** Ceiling for everything that is not literally the same page. */
+const NEAR_SCORE_CAP = 0.95;
+const SAME_SITE_SCORE = 0.45;
+const BOTH_SIGNALS_BONUS = 0.1;
+const EXCERPT_CHARS = 200;
+function stripFragment(url) {
+    const hash = url.indexOf('#');
+    return (hash === -1 ? url : url.slice(0, hash)).trim();
+}
+function looksLikeUrl(target) {
+    return /^https?:\/\//i.test(target.trim());
+}
+function hostOf(url) {
+    if (!url)
+        return undefined;
+    try {
+        return new URL(url).hostname.toLowerCase().replace(/^www\./, '');
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Words a URL alone gives us — the fallback query when there is no text. */
+function urlWords(url) {
+    try {
+        const u = new URL(url);
+        return [u.hostname.replace(/^www\./, ''), ...u.pathname.split(/[/\-_.]+/)]
+            .filter((w) => w && !/^\d+$/.test(w) && w.length > 1)
+            .join(' ');
+    }
+    catch {
+        return url;
+    }
+}
+async function queryText(record, target, provided) {
+    if (provided?.trim())
+        return provided.slice(0, QUERY_CHARS);
+    const parts = [];
+    if (record?.provenance?.title)
+        parts.push(record.provenance.title);
+    if (record && fs.existsSync(record.filePath)) {
+        try {
+            const { extractText } = await import('../capabilities/cap-documents.js');
+            const stat = fs.statSync(record.filePath);
+            const text = await extractText({
+                path: record.filePath,
+                absolutePath: record.filePath,
+                extension: path.extname(record.filePath).toLowerCase(),
+                size: stat.size,
+                modified: stat.mtime,
+                created: stat.birthtime,
+            });
+            if (text)
+                parts.push(text.slice(0, QUERY_CHARS));
+        }
+        catch {
+            /* fall through to the URL words */
+        }
+    }
+    if (!parts.length)
+        parts.push(urlWords(looksLikeUrl(target) ? target : path.basename(target)));
+    return parts.join('\n').slice(0, QUERY_CHARS);
+}
+/** Resolve the vector pass or give up on time — whichever comes first. */
+function withTimeout(work, ms, fallback) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(fallback), ms);
+        work
+            .then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        })
+            .catch(() => {
+            clearTimeout(timer);
+            resolve(fallback);
+        });
+    });
+}
+/**
+ * The documents most related to `target` (a URL, a docId, or an indexed path).
+ *
+ * Safe to call on every capture: bounded, and empty rather than thrown on any
+ * failure.
+ */
+export async function relatedDocuments(target, opts = {}) {
+    try {
+        const pipeline = await import('./document-pipeline.js');
+        const scope = opts.scope;
+        const rootDir = opts.rootDir ?? pipeline.getKnowledgeRoot(scope ?? 'shared');
+        const limit = opts.limit ?? DEFAULT_LIMIT;
+        const self = pipeline.findDocumentRecord(rootDir, target, scope);
+        // A capture that has been written but not yet ingested is the case this
+        // story exists for: the extension has the directory on disk and wants to
+        // know what it relates to BEFORE the ingest finishes. Its identity comes
+        // from the envelope's own meta.json.
+        const pending = !self && !looksLikeUrl(target) ? readCaptureProvenance(target) : null;
+        const selfUrl = self?.canonicalUrl ??
+            (looksLikeUrl(target) ? stripFragment(target) : captureIdentityUrl(pending));
+        const selfSite = hostOf(selfUrl);
+        const selfPaths = new Set([self?.filePath, looksLikeUrl(target) ? undefined : path.resolve(target)].filter((p) => !!p));
+        // Excluding by URL is right when the target IS that page — an indexed
+        // document, or a caller asking about the URL itself. It is wrong for a
+        // capture still sitting in the inbox: there the earlier capture of the
+        // same page is the single most related thing in the brain.
+        const excludeByUrl = !!self || looksLikeUrl(target);
+        const isSelf = (doc) => selfPaths.has(doc.filePath) || (excludeByUrl && !!selfUrl && doc.canonicalUrl === selfUrl);
+        const docs = pipeline.listDocuments(rootDir, scope).filter((d) => !isSelf(d));
+        const byPath = new Map(docs.map((d) => [d.filePath, d]));
+        const scored = new Map();
+        const put = (doc, reason, score, extra = {}) => {
+            const existing = scored.get(doc.filePath);
+            if (existing) {
+                if (!existing.reasons.includes(reason))
+                    existing.reasons.push(reason);
+                // Agreeing signals compound, but only the same page itself reaches 1 —
+                // otherwise a same-site neighbour that also embeds well would tie with
+                // the earlier capture of this very page and win on sort order.
+                const cap = existing.reasons.includes('same-url') ? SAME_URL_SCORE : NEAR_SCORE_CAP;
+                existing.score = Math.min(cap, Math.max(existing.score, score) + BOTH_SIGNALS_BONUS);
+                Object.assign(existing, extra);
+                return;
+            }
+            const url = doc.canonicalUrl ?? doc.provenance?.canonicalUrl ?? doc.provenance?.url;
+            scored.set(doc.filePath, {
+                filePath: doc.filePath,
+                scope: doc.scope,
+                title: doc.provenance?.title ?? path.basename(doc.filePath),
+                ...(url ? { url } : {}),
+                ...(documentSite(doc) ? { site: documentSite(doc) } : {}),
+                score,
+                reasons: [reason],
+                ...(documentCapturedAt(doc) ? { capturedAt: documentCapturedAt(doc) } : {}),
+                ...extra,
+            });
+        };
+        // 1 + 2 — the cheap signals, straight off the metadata log.
+        for (const doc of docs) {
+            const url = doc.canonicalUrl ?? doc.provenance?.canonicalUrl;
+            if (selfUrl && url && stripFragment(url) === selfUrl)
+                put(doc, 'same-url', SAME_URL_SCORE);
+            else if (selfSite && documentSite(doc) === selfSite)
+                put(doc, 'same-site', SAME_SITE_SCORE);
+        }
+        // 3 — similarity, bounded. A store with no embeddings comes back empty
+        // here and the metadata signals still stand.
+        // For a not-yet-ingested capture the text to compare against is the file
+        // the caller pointed at, read through the same extraction the ingest uses.
+        const queryRecord = self ?? (pending ? { filePath: path.resolve(target), provenance: pending } : undefined);
+        const query = await queryText(queryRecord, target, opts.text);
+        if (query.trim()) {
+            const hits = await withTimeout(pipeline.searchKnowledge(query, {
+                scope: scope ?? 'shared',
+                rootDir,
+                limit: Math.max(limit * 6, 12),
+                minScore: opts.minScore ?? DEFAULT_MIN_SCORE,
+                store: opts.store ?? 'all',
+            }), opts.timeoutMs ?? DEFAULT_TIMEOUT_MS, []);
+            const best = new Map();
+            for (const hit of hits) {
+                if (!hit.filePath || selfPaths.has(hit.filePath))
+                    continue;
+                const current = best.get(hit.filePath);
+                if (!current || hit.similarity > current.similarity)
+                    best.set(hit.filePath, hit);
+            }
+            for (const [filePath, hit] of best) {
+                const doc = byPath.get(filePath);
+                if (!doc || isSelf(doc))
+                    continue;
+                put(doc, 'similar', Math.min(1, hit.similarity), {
+                    excerpt: passageQuote(hit.text ?? '', EXCERPT_CHARS),
+                    chunkIndex: hit.chunkIndex,
+                    ...(hit.anchor ? { anchor: hit.anchor } : {}),
+                });
+            }
+        }
+        return [...scored.values()]
+            .sort((a, b) => b.score - a.score || (b.capturedAt ?? '').localeCompare(a.capturedAt ?? ''))
+            .slice(0, limit);
+    }
+    catch (err) {
+        // Called on every capture: an unexpected failure is "nothing related",
+        // never a broken save. It is still a bug when it is one of ours, so it is
+        // visible under DEBUG rather than only in an empty sidebar.
+        if (process.env.DEBUG || process.env.MONOMIND_DEBUG) {
+            console.error(`[relatedDocuments] ${target}:`, err);
+        }
+        return [];
+    }
+}
+//# sourceMappingURL=related.js.map

package/dist/src/knowledge/related.js.map

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

package/dist/src/knowledge/section-diff.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Semantic diff between two versions of a captured page (RCL-08).
+ *
+ * A character diff of a re-captured page is noise: the byline date moved, an
+ * ad slot re-rendered, the markdown re-wrapped. What a watcher actually wants
+ * to be told is WHICH SECTIONS changed and roughly how much — "Pricing gained
+ * a paragraph, Changelog got three new entries, everything else is the same".
+ *
+ * So the unit here is the markdown section (heading + body), keyed by its
+ * full heading path, and the measure is words and sentences rather than
+ * characters. Sentences are also what gives a change its sample line: the
+ * first sentence that is in the new version and was not in the old one is the
+ * most useful single thing to print.
+ *
+ * No dependency, no LLM: heading paths and sentence sets are enough to say
+ * what moved.
+ *
+ * @module v1/cli/knowledge/section-diff
+ */
+export interface Section {
+    /** Full heading path, e.g. `Pricing > Enterprise`. `(intro)` for text
+     *  before the first heading. */
+    key: string;
+    heading: string;
+    level: number;
+    body: string;
+}
+export interface SectionChange {
+    key: string;
+    addedWords: number;
+    removedWords: number;
+    /** First sentence present in the new version and absent from the old. */
+    sample?: string;
+}
+export interface SectionDiff {
+    added: string[];
+    removed: string[];
+    changed: SectionChange[];
+    unchanged: number;
+    /** One line, ready to print or to put in a notification. */
+    summary: string;
+}
+/** Split markdown into sections keyed by heading path. Duplicate paths get a
+ *  `#2` suffix so two "Notes" sections never collapse into one. */
+export declare function splitSections(text: string): Section[];
+/** What changed between two versions of the same page. */
+export declare function diffSections(oldText: string, newText: string): SectionDiff;
+//# sourceMappingURL=section-diff.d.ts.map

package/dist/src/knowledge/section-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"section-diff.d.ts","sourceRoot":"","sources":["../../../src/knowledge/section-diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,OAAO;IACtB;oCACgC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;CACjB;AAKD;mEACmE;AACnE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CAmCrD;AA2DD,0DAA0D;AAC1D,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,CAgC1E"}