@shadow-garden/bapbong-mcp 0.1.0

package/dist/lib/contract.d.ts

@@ -0,0 +1,144 @@
+/**
+ * The host-agnostic contract between MCP tools and a document host.
+ *
+ * Tools (packages/mcp/src/lib/server.ts) are written once against
+ * {@link DocumentSession}; hosts implement it for their document store:
+ * the desktop app binds the live editor (WebView), a server binds a headless
+ * ProseMirror EditorState ({@link ../headless-session}). Anything here must
+ * therefore stay meaningful for BOTH — no DOM, no desktop-isms.
+ *
+ * Anchoring semantics (the part language-agnostic hosts must reproduce):
+ * - Text anchors match within a single block (paragraph/cell paragraph);
+ *   matches never span blocks or inline atoms (images/fields).
+ * - A mutation anchor must match exactly once, or the caller must pass
+ *   `occurrence` (1-based, in document order). Ambiguity is an error that
+ *   lists the occurrence count — the model retries with `occurrence`.
+ * - `docVersion` is an opaque string that changes whenever the document
+ *   changes. Mutations MAY pass `expectedVersion`; a mismatch raises
+ *   {@link VersionConflictError} and the caller re-reads before retrying.
+ */
+/** An inline image (bitmap picture or drawn shape) inside a block —
+ *  addressable as (block index, image index) by updateImage. */
+export interface DocImage {
+    /** 0-based among the block's images, in block order. */
+    index: number;
+    alt: string;
+    /** CSS px. */
+    width: number;
+    height: number;
+    /** Clockwise degrees around the image center (0 when unrotated). */
+    rotation: number;
+    /** Drawn vector shape (rect/ellipse/…) vs a bitmap picture. */
+    kind: 'bitmap' | 'shape';
+}
+/** One addressable block in reading order (table-cell paragraphs included). */
+export interface DocBlock {
+    /** Stable only within one docVersion — re-read after any change. */
+    index: number;
+    /** 'paragraph' | 'heading1'..'heading6' | future kinds. */
+    type: string;
+    text: string;
+    /** The block's inline images, when it has any. */
+    images?: DocImage[];
+}
+export interface DocSnapshot {
+    docVersion: string;
+    blocks: DocBlock[];
+    /** Host metadata (file name, dirty state…) — informational only. */
+    meta: {
+        name?: string;
+        dirty?: boolean;
+    };
+}
+export interface FindMatch {
+    blockIndex: number;
+    /** 1-based occurrence of the query across the whole document. */
+    occurrence: number;
+    /** The match with surrounding text — enough to disambiguate. */
+    context: string;
+}
+/** Where insertContent puts new blocks. */
+export type InsertAnchor = {
+    position: 'before' | 'after';
+    text: string;
+    occurrence?: number;
+} | {
+    position: 'document_end';
+};
+/** Character marks are tri-state: true = apply, false = remove, absent = keep. */
+export interface Formatting {
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strike?: boolean;
+    /** Paragraph alignment of the block(s) containing the target text. */
+    align?: 'left' | 'center' | 'right' | 'justify';
+}
+/** Partial image update — absent fields keep their current value. */
+export interface ImageChanges {
+    /** CSS px (rounded; must be positive). */
+    width?: number;
+    /** CSS px (rounded; must be positive). */
+    height?: number;
+    /** Clockwise degrees around the center — normalized to [0, 360). */
+    rotation?: number;
+}
+export interface MutationResult {
+    docVersion: string;
+    /** The affected range (PM positions) — informational; hosts use it to
+     *  surface the edit (the desktop selects + scrolls to it). Positions are
+     *  only stable within the returned docVersion. */
+    range?: {
+        from: number;
+        to: number;
+    };
+}
+export interface MutationOptions {
+    expectedVersion?: string;
+    /** 1-based pick when the anchor text matches more than once. */
+    occurrence?: number;
+}
+/** What a host supports; tools that need a missing capability aren't offered. */
+export interface SessionCapabilities {
+    /** A live user selection exists (desktop editor) — enables get_selection. */
+    selection: boolean;
+}
+/** The port every document host implements. */
+export interface DocumentSession {
+    readonly capabilities: SessionCapabilities;
+    snapshot(): Promise<DocSnapshot>;
+    find(query: string): Promise<FindMatch[]>;
+    replaceText(oldText: string, newText: string, opts?: MutationOptions): Promise<MutationResult>;
+    /** `content`: plain text; each line becomes one paragraph. */
+    insertContent(content: string, anchor: InsertAnchor, opts?: MutationOptions): Promise<MutationResult>;
+    applyFormatting(target: string, format: Formatting, opts?: MutationOptions): Promise<MutationResult>;
+    /** Resize/rotate one image, addressed as (blockIndex, imageIndex) from the
+     *  latest snapshot. One transaction — a single undo step in a live editor. */
+    updateImage(blockIndex: number, imageIndex: number, changes: ImageChanges, opts?: MutationOptions): Promise<MutationResult>;
+    /** Only when capabilities.selection — the user's current selection. */
+    getSelection?(): Promise<{
+        text: string;
+        blockIndex: number;
+    } | null>;
+    /** Persist to the host's backing store (file, DB…). */
+    save(): Promise<void>;
+    close(): Promise<void>;
+}
+/** Resolves the session a tool call operates on. Desktop: `documentId`
+ *  omitted = the open document. Server: id is required (tenancy). */
+export interface SessionProvider {
+    get(documentId?: string): Promise<DocumentSession | null>;
+}
+/** The document changed since `expectedVersion` — re-read, then retry. */
+export declare class VersionConflictError extends Error {
+    constructor(current: string, expected: string);
+}
+/** Anchor text not found, or ambiguous without `occurrence`. */
+export declare class AnchorError extends Error {
+    constructor(message: string);
+}
+/** The host has no document to operate on (desktop: nothing open yet). */
+export declare class NoDocumentError extends Error {
+    constructor(message?: string);
+}
+//# sourceMappingURL=contract.d.ts.map

package/dist/lib/contract.d.ts.map

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

package/dist/lib/headless-session.d.ts

@@ -0,0 +1,27 @@
+import type { DocSnapshot, DocumentSession, FindMatch, Formatting, ImageChanges, InsertAnchor, MutationOptions, MutationResult, SessionCapabilities } from './contract.js';
+export interface HeadlessSessionOptions {
+    /** Where save() writes the exported bytes (file, DB, test sink…). */
+    onSave?: (bytes: Uint8Array) => void | Promise<void>;
+    name?: string;
+}
+export declare class HeadlessSession implements DocumentSession {
+    private readonly raw;
+    private readonly opts;
+    readonly capabilities: SessionCapabilities;
+    private state;
+    private version;
+    private dirty;
+    private readonly inner;
+    private constructor();
+    static open(bytes: ArrayBuffer | Uint8Array, opts?: HeadlessSessionOptions): Promise<HeadlessSession>;
+    get docVersion(): string;
+    snapshot(): Promise<DocSnapshot>;
+    find(query: string): Promise<FindMatch[]>;
+    replaceText(oldText: string, newText: string, opts?: MutationOptions): Promise<MutationResult>;
+    insertContent(content: string, anchor: InsertAnchor, opts?: MutationOptions): Promise<MutationResult>;
+    applyFormatting(target: string, format: Formatting, opts?: MutationOptions): Promise<MutationResult>;
+    updateImage(blockIndex: number, imageIndex: number, changes: ImageChanges, opts?: MutationOptions): Promise<MutationResult>;
+    save(): Promise<void>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=headless-session.d.ts.map

package/dist/lib/headless-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headless-session.d.ts","sourceRoot":"","sources":["../../src/lib/headless-session.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,WAAW,EACX,eAAe,EACf,SAAS,EACT,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,cAAc,EACd,mBAAmB,EACpB,MAAM,eAAe,CAAC;AAGvB,MAAM,WAAW,sBAAsB;IACrC,qEAAqE;IACrE,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,eAAgB,YAAW,eAAe;IAUnD,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAVvB,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAwB;IAElE,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IAErC,OAAO;WAyBM,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG,UAAU,EAAE,IAAI,GAAE,sBAA2B,GAAG,OAAO,CAAC,eAAe,CAAC;IAK/G,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,QAAQ,IAAI,OAAO,CAAC,WAAW,CAAC;IAGhC,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAGzC,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;IAG9F,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;IAGrG,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;IAGpG,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;IAG3H,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAGrB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAGvB"}

package/dist/lib/pm-session.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The shared DocumentSession semantics over ANY ProseMirror editor state —
+ * anchoring (atom-safe text hits → PM positions), unique-match rules,
+ * optimistic locking, mutations as transactions.
+ *
+ * Hosts provide the state and the dispatch:
+ *  - HeadlessSession owns an EditorState (server / tests);
+ *  - the desktop WebView wraps its live editor (state + dispatch) so AI edits
+ *    ride the normal transaction pipeline (undo, autosave, journal).
+ * Keeping ALL semantics here means both hosts behave identically — tested
+ * once, headlessly.
+ */
+import type { EditorState, Transaction } from 'prosemirror-state';
+import { type DocSnapshot, type DocumentSession, type FindMatch, type Formatting, type ImageChanges, type InsertAnchor, type MutationOptions, type MutationResult, type SessionCapabilities } from './contract.js';
+/** What a PmDocSession needs from its host. */
+export interface PmSessionHost {
+    getState(): EditorState;
+    /** Dispatch a transaction (live editor) / apply it (headless state). */
+    apply(tr: Transaction): void;
+    /** Opaque, changes on every doc change — INCLUDING user edits. */
+    getVersion(): string;
+    meta(): {
+        name?: string;
+        dirty?: boolean;
+    };
+    save(): Promise<void>;
+    /** Current user selection, when the host has one (desktop editor). */
+    selection?(): {
+        from: number;
+        to: number;
+    } | null;
+}
+export declare class PmDocSession implements DocumentSession {
+    private readonly host;
+    readonly capabilities: SessionCapabilities;
+    constructor(host: PmSessionHost);
+    snapshot(): Promise<DocSnapshot>;
+    find(query: string): Promise<FindMatch[]>;
+    getSelection(): Promise<{
+        text: string;
+        blockIndex: number;
+    } | null>;
+    replaceText(oldText: string, newText: string, opts?: MutationOptions): Promise<MutationResult>;
+    insertContent(content: string, anchor: InsertAnchor, opts?: MutationOptions): Promise<MutationResult>;
+    applyFormatting(target: string, format: Formatting, opts?: MutationOptions): Promise<MutationResult>;
+    updateImage(blockIndex: number, imageIndex: number, changes: ImageChanges, opts?: MutationOptions): Promise<MutationResult>;
+    save(): Promise<void>;
+    close(): Promise<void>;
+    private checkVersion;
+    /** All textblocks (paragraphs, incl. inside table cells) in reading order. */
+    private textblocks;
+    /** Every occurrence of `query`, atom-safe (matches never span images/fields
+     *  or block boundaries), in document order with absolute PM positions. */
+    private hits;
+    private uniqueHit;
+}
+//# sourceMappingURL=pm-session.d.ts.map

package/dist/lib/pm-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pm-session.d.ts","sourceRoot":"","sources":["../../src/lib/pm-session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAElE,OAAO,EAIL,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACzB,MAAM,eAAe,CAAC;AAEvB,+CAA+C;AAC/C,MAAM,WAAW,aAAa;IAC5B,QAAQ,IAAI,WAAW,CAAC;IACxB,wEAAwE;IACxE,KAAK,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,CAAC;IAC7B,kEAAkE;IAClE,UAAU,IAAI,MAAM,CAAC;IACrB,IAAI,IAAI;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAC3C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,sEAAsE;IACtE,SAAS,CAAC,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACnD;AAYD,qBAAa,YAAa,YAAW,eAAe;IAGtC,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;gBAEd,IAAI,EAAE,aAAa;IAM1C,QAAQ,IAAI,OAAO,CAAC,WAAW,CAAC;IAiBhC,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAIzC,YAAY,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAapE,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,cAAc,CAAC;IAOlG,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,cAAc,CAAC;IAqBzG,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,cAAc,CAAC;IAyBxG,WAAW,CACf,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,YAAY,EACrB,IAAI,GAAE,eAAoB,GACzB,OAAO,CAAC,cAAc,CAAC;IA+BpB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B,OAAO,CAAC,YAAY;IAOpB,8EAA8E;IAC9E,OAAO,CAAC,UAAU;IAYlB;8EAC0E;IAC1E,OAAO,CAAC,IAAI;IAsCZ,OAAO,CAAC,SAAS;CAuBlB"}

package/dist/lib/server.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The MCP server over a {@link SessionProvider} — the host-agnostic half of
+ * M15. Hosts supply sessions (desktop: the live editor; server: headless
+ * EditorStates) and a transport (loopback Bun.serve, TLS gateway, stdio…);
+ * everything the agent sees — tool names, schemas, anchoring/versioning
+ * semantics, error texts that teach the retry — is defined once, here.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type SessionProvider } from './contract.js';
+export interface CreateMcpServerOptions {
+    name?: string;
+    version?: string;
+    /** Offer get_selection (hosts with a live user selection — the desktop). */
+    selection?: boolean;
+}
+export declare function createMcpServer(provider: SessionProvider, opts?: CreateMcpServerOptions): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/lib/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/lib/server.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAA4E,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAE/H,MAAM,WAAW,sBAAsB;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AA4BD,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe,EAAE,IAAI,GAAE,sBAA2B,GAAG,SAAS,CAsMvG"}

package/dist/lib/wire.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The wire protocol between a DocumentSession host process and the process
+ * where the document actually lives, when they are not the same — on desktop,
+ * the Bun process hosts the MCP server while the document lives in the
+ * WebView editor.
+ *
+ * Bun side: {@link RemoteSession} — a DocumentSession whose every method
+ * serializes into one {@link SessionOpRequest} (pushed over the app's SSE
+ * command channel) and awaits the matching {@link SessionOpResponse}.
+ * WebView side: {@link executeOp} — runs the request against the local
+ * session and produces the response, round-tripping contract errors by name
+ * so optimistic-locking / anchoring semantics survive the process hop.
+ */
+import { type DocumentSession, type Formatting, type ImageChanges, type InsertAnchor, type MutationOptions, type SessionCapabilities } from './contract.js';
+export type SessionOpName = 'snapshot' | 'find' | 'replaceText' | 'insertContent' | 'applyFormatting' | 'updateImage' | 'getSelection' | 'save' | 'consent';
+export interface SessionOpRequest {
+    id: string;
+    op: SessionOpName;
+    args: unknown[];
+}
+export type SessionOpResponse = {
+    id: string;
+    ok: true;
+    value: unknown;
+} | {
+    id: string;
+    ok: false;
+    error: {
+        name: string;
+        message: string;
+    };
+};
+/** Run one wire op against a local session ('consent' is host-level and is
+ *  handled by the caller before this). Never throws — errors are encoded. */
+export declare function executeOp(session: DocumentSession | null, request: SessionOpRequest): Promise<SessionOpResponse>;
+/** Rebuild a contract error from its wire form so upstream catch-by-class
+ *  (createMcpServer's teaching errors) keeps working across the hop. */
+export declare function reviveError(error: {
+    name: string;
+    message: string;
+}): Error;
+/** DocumentSession proxy: forwards every call over `send` (the transport is
+ *  the host's business — desktop uses its SSE command channel + POST-back). */
+export declare class RemoteSession implements DocumentSession {
+    private readonly send;
+    readonly capabilities: SessionCapabilities;
+    constructor(send: (op: SessionOpName, args: unknown[]) => Promise<unknown>, capabilities: SessionCapabilities);
+    private call;
+    snapshot(): Promise<import("./contract.js").DocSnapshot>;
+    find(query: string): Promise<import("./contract.js").FindMatch[]>;
+    replaceText(oldText: string, newText: string, opts?: MutationOptions): Promise<import("./contract.js").MutationResult>;
+    insertContent(content: string, anchor: InsertAnchor, opts?: MutationOptions): Promise<import("./contract.js").MutationResult>;
+    applyFormatting(target: string, format: Formatting, opts?: MutationOptions): Promise<import("./contract.js").MutationResult>;
+    updateImage(blockIndex: number, imageIndex: number, changes: ImageChanges, opts?: MutationOptions): Promise<import("./contract.js").MutationResult>;
+    getSelection(): Promise<{
+        text: string;
+        blockIndex: number;
+    } | null>;
+    save(): Promise<void>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=wire.d.ts.map

package/dist/lib/wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../../src/lib/wire.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAIL,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACzB,MAAM,eAAe,CAAC;AAEvB,MAAM,MAAM,aAAa,GACrB,UAAU,GACV,MAAM,GACN,aAAa,GACb,eAAe,GACf,iBAAiB,GACjB,aAAa,GACb,cAAc,GACd,MAAM,GACN,SAAS,CAAC;AAEd,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,aAAa,CAAC;IAClB,IAAI,EAAE,OAAO,EAAE,CAAC;CACjB;AAED,MAAM,MAAM,iBAAiB,GACzB;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACxC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC;AAExE;6EAC6E;AAC7E,wBAAsB,SAAS,CAC7B,OAAO,EAAE,eAAe,GAAG,IAAI,EAC/B,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,iBAAiB,CAAC,CAS5B;AA8BD;wEACwE;AACxE,wBAAgB,WAAW,CAAC,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,KAAK,CAiB3E;AAED;+EAC+E;AAC/E,qBAAa,aAAc,YAAW,eAAe;IAEjD,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,QAAQ,CAAC,YAAY,EAAE,mBAAmB;gBADzB,IAAI,EAAE,CAAC,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,EACtE,YAAY,EAAE,mBAAmB;YAG9B,IAAI;IAIlB,QAAQ;IAGR,IAAI,CAAC,KAAK,EAAE,MAAM;IAGlB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,eAAe;IAGpE,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,CAAC,EAAE,eAAe;IAG3E,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,eAAe;IAG1E,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,IAAI,CAAC,EAAE,eAAe;IAG3F,YAAY;cACS,MAAM;oBAAc,MAAM;;IAE/C,IAAI;IAGJ,KAAK;CAGZ"}