@monoes/monomindcli 2.14.1 → 2.15.0

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

@@ -0,0 +1,168 @@
+/**
+ * Highlights as atomic notes (RCL-04) — the ingest half.
+ *
+ * The extension writes `highlights.json` into the capture envelope beside
+ * `readable.md` (chrome-extension/highlights.js). This module turns each
+ * entry into a NOTE IN ITS OWN RIGHT that points back at the document it
+ * came from — searchable on its own terms, not buried inside a chunk of
+ * the page it was taken from.
+ *
+ * WHY A CHILD NOTE AND NOT A TAG ON THE PARENT. A highlight is a claim
+ * about what mattered, made by the reader, at a moment. Folding it into the
+ * parent's chunks loses all three: it stops being separately findable, it
+ * stops carrying its own comment, and it stops having a date. So each one
+ * is stored as its own entry, keyed under the parent's content hash, and
+ * linked back by `parent:` and `url:` tags.
+ *
+ * THE ANCHOR is the careful part. The extension measured its offsets
+ * against the LIVE PAGE'S TEXT; what got indexed is `readable.md`, a
+ * Readability pass over that same DOM. The two are close and not identical.
+ * So the offsets that arrive are treated as a hint and the QUOTE is treated
+ * as the truth: `locate` re-locates the quote in the extracted text and
+ * cuts a real citation anchor (`<hash12>#<start>-<end>`, citation.ts's
+ * shape) against the version it actually found. A highlight whose text is
+ * not in the document at all gets NO anchor rather than a plausible wrong
+ * one — the same rule citation.ts applies to a stale anchor, for the same
+ * reason.
+ *
+ * Everything here is as defensive as capture-envelope.ts, and for the same
+ * reason: `highlights.json` was written by a browser extension on a machine
+ * we do not control, and a malformed one must cost the capture nothing.
+ *
+ * @module v1/cli/knowledge/highlights
+ */
+import type { CaptureProvenance } from './capture-envelope.js';
+export declare const HIGHLIGHTS_FILE = "highlights.json";
+/** Tag namespaces, so a highlight is findable as one and traceable to its
+ *  parent without parsing anything. */
+export declare const HIGHLIGHT_TAG = "highlight";
+export declare const PARENT_TAG_PREFIX = "parent:";
+export declare const URL_TAG_PREFIX = "url:";
+/** The anchor as the extension measured it — offsets against the page's
+ *  visible text, plus the quote and its neighbourhood. */
+export interface HighlightAnchor {
+    /** A HINT. Measured against the live page, not the extracted text. */
+    startChar?: number;
+    endChar?: number;
+    /** The truth. What the reader actually selected. */
+    quote: string;
+    prefix?: string;
+    suffix?: string;
+    /** W3C `:~:text=` fragment, as citation.ts builds one. */
+    fragment?: string;
+}
+export interface Highlight {
+    id: string;
+    text: string;
+    anchor: HighlightAnchor;
+    createdAt?: string;
+    comment?: string;
+    color?: string;
+    /** The page URL pointed at this passage, as the extension wrote it. */
+    url?: string;
+}
+/** One highlight, resolved against the document it belongs to. */
+export interface HighlightNote {
+    id: string;
+    /** `<scope>:<filePath>` — the parent document's own id. */
+    parentDocId: string;
+    parentPath: string;
+    scope: string;
+    /** The parent's identity URL. */
+    parentUrl?: string;
+    parentTitle?: string;
+    text: string;
+    quote: string;
+    comment?: string;
+    createdAt?: string;
+    color?: string;
+    /** `<hash12>#<start>-<end>` against the EXTRACTED text — present only
+     *  when the quote was actually found there. */
+    anchor?: string;
+    startChar?: number;
+    endChar?: number;
+    /** The link that lands on the passage in the live page. */
+    citeUrl?: string;
+    capturedAt?: string;
+    /** What gets stored and embedded: the highlight, its note, its source. */
+    content: string;
+    tags: string[];
+}
+/** Keep only what we understand, coerced. An entry with no text is not a
+ *  highlight and is dropped rather than carried through as an empty note. */
+export declare function normalizeHighlight(raw: unknown, index?: number): Highlight | null;
+/**
+ * readHighlights reads the `highlights.json` sitting in `dir`. Returns an
+ * empty list — never throws — when there is none, it is unreadable,
+ * oversized, not JSON, or the wrong shape entirely.
+ */
+export declare function readHighlights(dir: string): Highlight[];
+/** readHighlightsFor reads the highlights belonging to an indexed file,
+ *  i.e. the ones in its envelope directory. */
+export declare function readHighlightsFor(filePath: string): Highlight[];
+/**
+ * locate finds a highlight's quote in the extracted text and returns its
+ * span there, or null.
+ *
+ * The order is the order of trustworthiness, and it is the SAME order the
+ * extension's own restore path uses (chrome-extension/highlights.js
+ * `relocate`), so a highlight that can be painted back onto the page can
+ * also be cited out of the archive:
+ *
+ *  1. prefix + quote + suffix — the neighbourhood, which survives the
+ *     Readability pass dropping a nav bar above it;
+ *  2. the occurrence nearest the recorded offset, for a quote that appears
+ *     more than once;
+ *  3. nothing. A quote that is not in the document gets no anchor. It is
+ *     still stored as a note — the reader did read it — but a citation
+ *     that cannot be checked is not offered as if it could.
+ */
+export declare function locate(text: string, anchor: HighlightAnchor): {
+    startChar: number;
+    endChar: number;
+} | null;
+export interface ParentDocument {
+    filePath: string;
+    scope: string;
+    /** Hash of the EXTRACTED text — the same one the anchor binds to. */
+    contentHash: string;
+    /** The extracted text itself, when the caller has it. Without it, no
+     *  anchor can be cut and the notes are stored unanchored. */
+    text?: string;
+    canonicalUrl?: string;
+    provenance?: CaptureProvenance;
+}
+/**
+ * highlightNotes turns an envelope's highlights into notes against a parent
+ * document. Pure: it reads nothing and writes nothing, so it is the whole
+ * of the interesting behaviour and the whole of what is tested.
+ */
+export declare function highlightNotes(parent: ParentDocument, highlights: readonly Highlight[]): HighlightNote[];
+export interface IngestHighlightsResult {
+    /** How many notes were stored. */
+    stored: number;
+    /** How many were found in the envelope at all. */
+    found: number;
+    /** How many resolved to a citable span in the extracted text. */
+    anchored: number;
+    notes: HighlightNote[];
+    error?: string;
+}
+/** The storage key for one highlight. Keyed under the PARENT'S content
+ *  hash, so re-ingesting the same version upserts the same notes rather
+ *  than accumulating a copy per ingest — the same discipline as the
+ *  pipeline's `doc:<hash>:<index>` chunk keys. */
+export declare function highlightKey(parentContentHash: string, id: string): string;
+/**
+ * ingestHighlights stores an envelope's highlights as notes linked to the
+ * parent document.
+ *
+ * Reports rather than throws: a capture whose highlights could not be
+ * stored is still a perfectly good capture, and failing the whole ingest
+ * over the annotations would lose the page as well as the notes.
+ */
+export declare function ingestHighlights(parent: ParentDocument, opts?: {
+    highlights?: readonly Highlight[];
+    dbPath?: string;
+}): Promise<IngestHighlightsResult>;
+//# sourceMappingURL=highlights.d.ts.map

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

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

package/dist/src/knowledge/highlights.js

@@ -0,0 +1,311 @@
+/**
+ * Highlights as atomic notes (RCL-04) — the ingest half.
+ *
+ * The extension writes `highlights.json` into the capture envelope beside
+ * `readable.md` (chrome-extension/highlights.js). This module turns each
+ * entry into a NOTE IN ITS OWN RIGHT that points back at the document it
+ * came from — searchable on its own terms, not buried inside a chunk of
+ * the page it was taken from.
+ *
+ * WHY A CHILD NOTE AND NOT A TAG ON THE PARENT. A highlight is a claim
+ * about what mattered, made by the reader, at a moment. Folding it into the
+ * parent's chunks loses all three: it stops being separately findable, it
+ * stops carrying its own comment, and it stops having a date. So each one
+ * is stored as its own entry, keyed under the parent's content hash, and
+ * linked back by `parent:` and `url:` tags.
+ *
+ * THE ANCHOR is the careful part. The extension measured its offsets
+ * against the LIVE PAGE'S TEXT; what got indexed is `readable.md`, a
+ * Readability pass over that same DOM. The two are close and not identical.
+ * So the offsets that arrive are treated as a hint and the QUOTE is treated
+ * as the truth: `locate` re-locates the quote in the extracted text and
+ * cuts a real citation anchor (`<hash12>#<start>-<end>`, citation.ts's
+ * shape) against the version it actually found. A highlight whose text is
+ * not in the document at all gets NO anchor rather than a plausible wrong
+ * one — the same rule citation.ts applies to a stale anchor, for the same
+ * reason.
+ *
+ * Everything here is as defensive as capture-envelope.ts, and for the same
+ * reason: `highlights.json` was written by a browser extension on a machine
+ * we do not control, and a malformed one must cost the capture nothing.
+ *
+ * @module v1/cli/knowledge/highlights
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { citationAnchor, citationUrl, passageQuote } from './citation.js';
+export const HIGHLIGHTS_FILE = 'highlights.json';
+/** Tag namespaces, so a highlight is findable as one and traceable to its
+ *  parent without parsing anything. */
+export const HIGHLIGHT_TAG = 'highlight';
+export const PARENT_TAG_PREFIX = 'parent:';
+export const URL_TAG_PREFIX = 'url:';
+const MAX_FILE_BYTES = 2 * 1024 * 1024;
+const MAX_HIGHLIGHTS = 500;
+const MAX_TEXT = 4000;
+const MAX_COMMENT = 2000;
+// ── Reading ────────────────────────────────────────────────────────
+const str = (v, max) => {
+    if (typeof v !== 'string')
+        return undefined;
+    const trimmed = v.trim().slice(0, max).trim();
+    return trimmed ? trimmed : undefined;
+};
+const int = (v) => {
+    const n = typeof v === 'number' ? v : Number.NaN;
+    return Number.isFinite(n) && n >= 0 ? Math.floor(n) : undefined;
+};
+/** Keep only what we understand, coerced. An entry with no text is not a
+ *  highlight and is dropped rather than carried through as an empty note. */
+export function normalizeHighlight(raw, index = 0) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const o = raw;
+    const text = str(o.text, MAX_TEXT);
+    if (!text)
+        return null;
+    const rawAnchor = o.anchor && typeof o.anchor === 'object' && !Array.isArray(o.anchor)
+        ? o.anchor
+        : {};
+    const quote = str(rawAnchor.quote, MAX_TEXT) ?? text;
+    const anchor = { quote };
+    const start = int(rawAnchor.startChar);
+    const end = int(rawAnchor.endChar);
+    if (start !== undefined)
+        anchor.startChar = start;
+    if (end !== undefined && (start === undefined || end >= start))
+        anchor.endChar = end;
+    const prefix = str(rawAnchor.prefix, 200);
+    const suffix = str(rawAnchor.suffix, 200);
+    const fragment = str(rawAnchor.fragment, 4000);
+    if (prefix)
+        anchor.prefix = prefix;
+    if (suffix)
+        anchor.suffix = suffix;
+    if (fragment)
+        anchor.fragment = fragment;
+    return {
+        id: str(o.id, 128) ?? `hl-${index}`,
+        text,
+        anchor,
+        ...(str(o.createdAt, 64) ? { createdAt: str(o.createdAt, 64) } : {}),
+        ...(str(o.comment, MAX_COMMENT) ? { comment: str(o.comment, MAX_COMMENT) } : {}),
+        ...(str(o.color, 32) ? { color: str(o.color, 32) } : {}),
+        ...(str(o.url, 4000) ? { url: str(o.url, 4000) } : {}),
+    };
+}
+/**
+ * readHighlights reads the `highlights.json` sitting in `dir`. Returns an
+ * empty list — never throws — when there is none, it is unreadable,
+ * oversized, not JSON, or the wrong shape entirely.
+ */
+export function readHighlights(dir) {
+    const file = path.join(path.resolve(dir), HIGHLIGHTS_FILE);
+    try {
+        if (!fs.existsSync(file))
+            return [];
+        if (fs.statSync(file).size > MAX_FILE_BYTES)
+            return [];
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        const list = Array.isArray(parsed) ? parsed : parsed?.highlights;
+        if (!Array.isArray(list))
+            return [];
+        const out = [];
+        const seen = new Set();
+        for (const [i, raw] of list.slice(0, MAX_HIGHLIGHTS).entries()) {
+            const h = normalizeHighlight(raw, i);
+            if (!h || seen.has(h.id))
+                continue;
+            seen.add(h.id);
+            out.push(h);
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+/** readHighlightsFor reads the highlights belonging to an indexed file,
+ *  i.e. the ones in its envelope directory. */
+export function readHighlightsFor(filePath) {
+    return readHighlights(path.dirname(path.resolve(filePath)));
+}
+// ── Resolving ──────────────────────────────────────────────────────
+/**
+ * locate finds a highlight's quote in the extracted text and returns its
+ * span there, or null.
+ *
+ * The order is the order of trustworthiness, and it is the SAME order the
+ * extension's own restore path uses (chrome-extension/highlights.js
+ * `relocate`), so a highlight that can be painted back onto the page can
+ * also be cited out of the archive:
+ *
+ *  1. prefix + quote + suffix — the neighbourhood, which survives the
+ *     Readability pass dropping a nav bar above it;
+ *  2. the occurrence nearest the recorded offset, for a quote that appears
+ *     more than once;
+ *  3. nothing. A quote that is not in the document gets no anchor. It is
+ *     still stored as a note — the reader did read it — but a citation
+ *     that cannot be checked is not offered as if it could.
+ */
+export function locate(text, anchor) {
+    const haystack = String(text ?? '');
+    const quote = String(anchor?.quote ?? '');
+    if (!quote || !haystack)
+        return null;
+    if (anchor.prefix || anchor.suffix) {
+        const window = `${anchor.prefix ?? ''}${quote}${anchor.suffix ?? ''}`;
+        const at = haystack.indexOf(window);
+        if (at !== -1) {
+            const start = at + (anchor.prefix ?? '').length;
+            return { startChar: start, endChar: start + quote.length };
+        }
+    }
+    const hint = anchor.startChar;
+    let best = -1;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (let at = haystack.indexOf(quote); at !== -1; at = haystack.indexOf(quote, at + 1)) {
+        if (hint === undefined) {
+            best = at;
+            break;
+        }
+        const distance = Math.abs(at - hint);
+        if (distance < bestDistance) {
+            best = at;
+            bestDistance = distance;
+        }
+    }
+    if (best === -1)
+        return null;
+    return { startChar: best, endChar: best + quote.length };
+}
+/** A note's stored body: the passage, the reader's comment, and where it
+ *  came from — so a search hit is legible without another lookup. */
+function noteContent(note) {
+    const lines = [note.text];
+    if (note.comment)
+        lines.push('', `Note: ${note.comment}`);
+    const source = note.parentTitle || note.parentUrl;
+    if (source)
+        lines.push('', `— ${source}`);
+    return lines.join('\n');
+}
+/**
+ * highlightNotes turns an envelope's highlights into notes against a parent
+ * document. Pure: it reads nothing and writes nothing, so it is the whole
+ * of the interesting behaviour and the whole of what is tested.
+ */
+export function highlightNotes(parent, highlights) {
+    const parentDocId = `${parent.scope}:${parent.filePath}`;
+    const parentUrl = parent.canonicalUrl ?? parent.provenance?.canonicalUrl ?? parent.provenance?.url;
+    const parentTitle = parent.provenance?.title;
+    const capturedAt = parent.provenance?.capturedAt;
+    return highlights.map((h) => {
+        const span = parent.text ? locate(parent.text, h.anchor) : null;
+        const note = {
+            id: h.id,
+            parentDocId,
+            parentPath: parent.filePath,
+            scope: parent.scope,
+            ...(parentUrl ? { parentUrl } : {}),
+            ...(parentTitle ? { parentTitle } : {}),
+            text: h.text,
+            quote: passageQuote(h.text),
+            ...(h.comment ? { comment: h.comment } : {}),
+            ...(h.createdAt ? { createdAt: h.createdAt } : {}),
+            ...(h.color ? { color: h.color } : {}),
+            ...(span
+                ? {
+                    anchor: citationAnchor(parent.contentHash, span.startChar, span.endChar),
+                    startChar: span.startChar,
+                    endChar: span.endChar,
+                }
+                : {}),
+            // The extension already built a text-fragment link; prefer it, and
+            // fall back to building one the same way citation.ts does.
+            ...(h.url
+                ? { citeUrl: h.url }
+                : parentUrl
+                    ? { citeUrl: citationUrl(parentUrl, h.text) }
+                    : {}),
+            ...(capturedAt ? { capturedAt } : {}),
+            content: '',
+            tags: [
+                HIGHLIGHT_TAG,
+                `${PARENT_TAG_PREFIX}${parentDocId}`,
+                ...(parentUrl ? [`${URL_TAG_PREFIX}${parentUrl}`] : []),
+                ...(h.color ? [`color:${h.color}`] : []),
+            ],
+        };
+        note.content = noteContent(note);
+        return note;
+    });
+}
+const KNOWLEDGE_NS_PREFIX = 'knowledge:';
+/** The storage key for one highlight. Keyed under the PARENT'S content
+ *  hash, so re-ingesting the same version upserts the same notes rather
+ *  than accumulating a copy per ingest — the same discipline as the
+ *  pipeline's `doc:<hash>:<index>` chunk keys. */
+export function highlightKey(parentContentHash, id) {
+    return `highlight:${parentContentHash}:${id}`;
+}
+async function getBridge() {
+    try {
+        return (await import('../memory/memory-bridge.js'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * ingestHighlights stores an envelope's highlights as notes linked to the
+ * parent document.
+ *
+ * Reports rather than throws: a capture whose highlights could not be
+ * stored is still a perfectly good capture, and failing the whole ingest
+ * over the annotations would lose the page as well as the notes.
+ */
+export async function ingestHighlights(parent, opts = {}) {
+    const highlights = opts.highlights ?? readHighlightsFor(parent.filePath);
+    const notes = highlightNotes(parent, highlights);
+    const anchored = notes.filter((n) => n.anchor).length;
+    const base = {
+        stored: 0,
+        found: highlights.length,
+        anchored,
+        notes,
+    };
+    if (!notes.length)
+        return base;
+    const bridge = await getBridge();
+    if (!bridge)
+        return { ...base, error: 'memory bridge unavailable — no highlights stored' };
+    let stored = 0;
+    for (const note of notes) {
+        try {
+            const result = await bridge.bridgeStoreEntry({
+                key: highlightKey(parent.contentHash, note.id),
+                value: note.content,
+                namespace: `${KNOWLEDGE_NS_PREFIX}${parent.scope}`,
+                generateEmbeddingFlag: true,
+                tags: note.tags,
+                upsert: true,
+                ...(opts.dbPath ? { dbPath: opts.dbPath } : {}),
+            });
+            if (result?.success)
+                stored++;
+        }
+        catch {
+            // One note failing is not the others' problem, and the count below
+            // reports the shortfall honestly.
+        }
+    }
+    return {
+        ...base,
+        stored,
+        ...(stored === notes.length
+            ? {}
+            : { error: `stored ${stored}/${notes.length} highlights — re-ingest to repair` }),
+    };
+}
+//# sourceMappingURL=highlights.js.map

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

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

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

@@ -0,0 +1,80 @@
+/**
+ * "Have I already saved this?" (RCL-02) — one URL in, one answer out.
+ *
+ * The browser extension asks this on every navigation. That is the only
+ * thing that shapes this module:
+ *
+ *  - it NEVER throws. An empty store, a store that has never been written,
+ *    a URL that is not a URL — all of them are `{saved: false}`, because a
+ *    page load must not be able to fail on a badge;
+ *  - it is a pure read. No embedder, no subprocess, no index write. The
+ *    answer comes off the metadata log, which is a file read;
+ *  - it answers the WHOLE question in one call. `doc list` can already say
+ *    that a URL is present, but not what note was written at save time —
+ *    and "you saved this, and here is why you said you were saving it" is
+ *    the entire value of the badge over a bookmark.
+ *
+ * Identity is `captureIdentityUrl`'s rule and nothing else: canonical URL
+ * when the capturer resolved one, fragment stripped, nothing else rewritten.
+ * Matching more loosely than the ingest side would make the badge claim
+ * pages are saved that cannot actually be found again.
+ *
+ * @module v1/cli/knowledge/lookup
+ */
+/** What the badge and the "already saved" panel render. */
+export interface UrlLookup {
+    saved: boolean;
+    /** The identity URL the lookup was performed against. */
+    url: string;
+    title?: string;
+    site?: string;
+    /** When the page was captured (not when it was indexed). */
+    capturedAt?: string;
+    /** RCL-06: 1 for a first save, +1 per stored revision. 0 when unsaved. */
+    versions: number;
+    /** The note written at save time (CLIP-07) — the reason it was kept. */
+    note?: string;
+    tags: string[];
+    collection?: string;
+    source?: string;
+    /** The indexed file (`…/readable.md`). */
+    filePath?: string;
+    /** The capture envelope directory holding it — what "open the archived
+     *  copy" opens. Absent when the document is an ordinary file on disk. */
+    envelope?: string;
+    scope?: string;
+    contentHash?: string;
+    /** RCL-04: how many highlight notes were saved on this page. */
+    highlights?: number;
+}
+export interface LookupOptions {
+    rootDir?: string;
+    scope?: string;
+    /** Skip the `highlights.json` read. The badge path does not need it. */
+    withHighlights?: boolean;
+}
+/**
+ * identityUrl mirrors `captureIdentityUrl` for a raw URL rather than a
+ * provenance record: drop the fragment, trim, rewrite nothing else.
+ *
+ * Duplicated deliberately rather than reshaping the URL into a fake
+ * `CaptureProvenance` to borrow that function — the two callers mean
+ * different things ("the URL a tab is on" vs. "what this capture is of")
+ * and only happen to agree on the rule.
+ */
+export declare function identityUrl(raw: string | undefined): string;
+/** The envelope directory for an indexed file, or undefined when the file
+ *  is not inside one. */
+export declare function envelopeFor(filePath: string | undefined): string | undefined;
+/**
+ * lookupUrl answers whether this URL is in the store, and what is known
+ * about it. `rootDir` is the store to look in; pass the global brain's root
+ * to ask the personal store.
+ */
+export declare function lookupUrl(rawUrl: string, opts?: LookupOptions): UrlLookup;
+/**
+ * lookupUrls answers a batch in one pass over the metadata, for a caller
+ * with several tabs to ask about. Same rules, same guarantees.
+ */
+export declare function lookupUrls(urls: readonly string[], opts?: LookupOptions): UrlLookup[];
+//# sourceMappingURL=lookup.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lookup.d.ts","sourceRoot":"","sources":["../../../src/knowledge/lookup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAaH,2DAA2D;AAC3D,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,OAAO,CAAC;IACf,yDAAyD;IACzD,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;6EACyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAID;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAI3D;AAwBD;yBACyB;AACzB,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAQ5E;AAMD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,aAAkB,GAAG,SAAS,CA8D7E;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,GAAE,aAAkB,GAAG,SAAS,EAAE,CAEzF"}