@rtif-sdk/web 1.0.0

package/dist/content-handlers.js

@@ -0,0 +1,263 @@
+/**
+ * Built-in content handlers for the RTIF content pipeline.
+ *
+ * Provides handlers for:
+ * - Plain text (`text/plain`) — splits on newlines, creates blocks
+ * - RTIF JSON (`application/x-rtif+json`) — preserves marks and block attrs
+ * - HTML (`text/html`) — stub, falls through to plain text handler
+ *
+ * @module
+ */
+// ---------------------------------------------------------------------------
+// Plain text handler
+// ---------------------------------------------------------------------------
+/**
+ * Create a content handler for plain text paste/drop.
+ *
+ * Accepts `text/plain` content and converts it to RTIF operations by splitting
+ * on newlines. Each line becomes a separate block via `split_block`, with the
+ * text inserted via `insert_text`.
+ *
+ * Priority: -100 (lowest built-in, runs last as fallback).
+ *
+ * @param generateBlockId - Factory for generating unique block IDs
+ * @returns A ContentHandler for plain text
+ *
+ * @example
+ * ```ts
+ * const handler = createPlainTextHandler(() => crypto.randomUUID());
+ * pipeline.register(handler);
+ * ```
+ */
+export function createPlainTextHandler(generateBlockId) {
+    return {
+        id: 'rtif:plain-text',
+        accept: ['text/plain'],
+        priority: -100,
+        async handle(item, context) {
+            const text = await item.getString();
+            if (text === null || text === '')
+                return false;
+            let insertOffset = context.deleteSelectionAndGetOffset();
+            const ops = [];
+            const lines = text.split('\n');
+            for (let i = 0; i < lines.length; i++) {
+                const line = lines[i];
+                if (i > 0) {
+                    ops.push({
+                        type: 'split_block',
+                        offset: insertOffset,
+                        newBlockId: generateBlockId(),
+                    });
+                    // After split_block, offset advances by 1 for the virtual \n
+                    insertOffset += 1;
+                }
+                if (line.length > 0) {
+                    ops.push({
+                        type: 'insert_text',
+                        offset: insertOffset,
+                        text: line,
+                    });
+                    insertOffset += line.length;
+                }
+            }
+            if (ops.length > 0) {
+                context.dispatch(ops);
+            }
+            return true;
+        },
+    };
+}
+/**
+ * Create a content handler for RTIF JSON paste.
+ *
+ * Accepts `application/x-rtif+json` content and preserves full formatting
+ * fidelity including span marks and block attributes. Parses the JSON payload,
+ * validates its structure, and generates the appropriate RTIF operations.
+ *
+ * Priority: -80 (highest built-in, runs before HTML and plain text).
+ *
+ * @param generateBlockId - Factory for generating unique block IDs
+ * @returns A ContentHandler for RTIF JSON paste
+ *
+ * @example
+ * ```ts
+ * const handler = createRtifPasteHandler(() => crypto.randomUUID());
+ * pipeline.register(handler);
+ * ```
+ */
+export function createRtifPasteHandler(generateBlockId) {
+    return {
+        id: 'rtif:rtif-json',
+        accept: ['application/x-rtif+json'],
+        priority: -80,
+        async handle(item, context) {
+            const jsonStr = await item.getString();
+            if (jsonStr === null || jsonStr === '')
+                return false;
+            // Parse and validate
+            const payload = parseRtifPayload(jsonStr);
+            if (payload === null)
+                return false;
+            let insertOffset = context.deleteSelectionAndGetOffset();
+            const ops = [];
+            // Track the offsets where each new block starts, for set_span_marks later
+            const blockInsertions = [];
+            // Phase 1: Insert text and create blocks
+            for (let bi = 0; bi < payload.blocks.length; bi++) {
+                const block = payload.blocks[bi];
+                const isFirst = bi === 0;
+                let newBlockId = null;
+                if (!isFirst) {
+                    newBlockId = generateBlockId();
+                    ops.push({
+                        type: 'split_block',
+                        offset: insertOffset,
+                        newBlockId,
+                    });
+                    insertOffset += 1;
+                }
+                const blockStartOffset = insertOffset;
+                // Insert the full text of all spans in this block
+                const fullText = block.spans.map((s) => s.text).join('');
+                if (fullText.length > 0) {
+                    ops.push({
+                        type: 'insert_text',
+                        offset: insertOffset,
+                        text: fullText,
+                    });
+                    insertOffset += fullText.length;
+                }
+                blockInsertions.push({
+                    blockStartOffset,
+                    block,
+                    isFirstBlock: isFirst,
+                    newBlockId,
+                });
+            }
+            // Phase 2: Apply span marks for each block
+            for (const { blockStartOffset, block } of blockInsertions) {
+                let spanOffset = blockStartOffset;
+                for (const span of block.spans) {
+                    if (span.marks && Object.keys(span.marks).length > 0) {
+                        ops.push({
+                            type: 'set_span_marks',
+                            offset: spanOffset,
+                            count: span.text.length,
+                            marks: span.marks,
+                        });
+                    }
+                    spanOffset += span.text.length;
+                }
+            }
+            // Phase 3: Apply block attrs (only on NEW blocks created by split, not the original)
+            for (const { block, isFirstBlock, newBlockId, } of blockInsertions) {
+                if (isFirstBlock)
+                    continue; // Don't set attrs on the block the cursor was in
+                if (!block.attrs || Object.keys(block.attrs).length === 0)
+                    continue;
+                if (newBlockId === null)
+                    continue;
+                ops.push({
+                    type: 'set_block_attrs',
+                    blockId: newBlockId,
+                    attrs: block.attrs,
+                });
+            }
+            // Phase 4: Apply block type on NEW blocks to match source document
+            for (const { block, isFirstBlock, newBlockId, } of blockInsertions) {
+                if (isFirstBlock)
+                    continue; // Don't change the cursor's original block type
+                if (newBlockId === null)
+                    continue;
+                ops.push({
+                    type: 'set_block_type',
+                    blockId: newBlockId,
+                    blockType: block.type,
+                });
+            }
+            if (ops.length > 0) {
+                context.dispatch(ops);
+            }
+            return true;
+        },
+    };
+}
+/**
+ * Parse and validate an RTIF clipboard JSON payload.
+ *
+ * @param jsonStr - The JSON string from the clipboard
+ * @returns Parsed payload, or null if invalid
+ */
+function parseRtifPayload(jsonStr) {
+    try {
+        const parsed = JSON.parse(jsonStr);
+        if (typeof parsed !== 'object' ||
+            parsed === null ||
+            !('version' in parsed) ||
+            !('blocks' in parsed)) {
+            return null;
+        }
+        const obj = parsed;
+        if (obj['version'] !== 1)
+            return null;
+        if (!Array.isArray(obj['blocks']))
+            return null;
+        const blocks = obj['blocks'];
+        if (blocks.length === 0)
+            return null;
+        // Validate each block has at least spans array
+        for (const block of blocks) {
+            if (typeof block !== 'object' || block === null)
+                return null;
+            const b = block;
+            if (!Array.isArray(b['spans']))
+                return null;
+            // Validate each span has text
+            const spans = b['spans'];
+            for (const span of spans) {
+                if (typeof span !== 'object' || span === null)
+                    return null;
+                const s = span;
+                if (typeof s['text'] !== 'string')
+                    return null;
+            }
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// HTML paste handler (stub)
+// ---------------------------------------------------------------------------
+/**
+ * Create a stub content handler for HTML paste.
+ *
+ * Currently always returns `false` (falls through to the plain text handler).
+ * Will be implemented when the `@rtif-sdk/format-html` plugin is available.
+ *
+ * Priority: -90 (between RTIF JSON and plain text).
+ *
+ * @returns A ContentHandler stub for HTML paste
+ *
+ * @example
+ * ```ts
+ * const handler = createHtmlPasteHandler();
+ * pipeline.register(handler);
+ * ```
+ */
+export function createHtmlPasteHandler() {
+    return {
+        id: 'rtif:html',
+        accept: ['text/html'],
+        priority: -90,
+        async handle(_item, _context) {
+            // Stub — always declines. HTML deserialization will be implemented
+            // when @rtif-sdk/format-html is available.
+            return false;
+        },
+    };
+}
+//# sourceMappingURL=content-handlers.js.map

package/dist/content-handlers.js.map

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

package/dist/content-pipeline.d.ts

@@ -0,0 +1,383 @@
+/**
+ * Content pipeline — unified ingestion for paste, drop, and programmatic input.
+ *
+ * The content pipeline routes incoming content items through a priority-ordered
+ * chain of handlers. Each handler declares which MIME types it accepts and
+ * processes matching items into RTIF operations. All operations from a single
+ * process() call are batched into one engine.dispatch() for a single undo group.
+ *
+ * @module
+ * @see docs/plans/web/03-content-pipeline.md
+ */
+import type { Operation } from '@rtif-sdk/core';
+import type { IEditorEngine } from '@rtif-sdk/engine';
+import type { CommandBus } from './command-bus.js';
+import type { Disposable } from './types.js';
+/**
+ * Source of a content item — how the content entered the editor.
+ *
+ * @example
+ * ```ts
+ * const source: ContentItemSource = 'paste';
+ * ```
+ */
+export type ContentItemSource = 'paste' | 'drop' | 'input' | 'programmatic';
+/**
+ * A single piece of content to be processed by the pipeline.
+ *
+ * Content items wrap clipboard data, dropped files, or programmatic input.
+ * The `type` field is a MIME type string used for handler matching.
+ * Data is accessed lazily via async getters to support both sync and async
+ * clipboard APIs.
+ *
+ * @example
+ * ```ts
+ * const item: ContentItem = {
+ *   type: 'text/plain',
+ *   source: 'paste',
+ *   getString: async () => 'Hello world',
+ *   getFile: async () => null,
+ *   getBlob: async () => null,
+ * };
+ * ```
+ */
+export interface ContentItem {
+    /** MIME type of the content (e.g., 'text/plain', 'image/png'). */
+    readonly type: string;
+    /** How this content entered the editor. */
+    readonly source: ContentItemSource;
+    /**
+     * Get the content as a string.
+     *
+     * @returns The string content, or null if not available as text
+     */
+    getString(): Promise<string | null>;
+    /**
+     * Get the content as a File.
+     *
+     * @returns The File object, or null if not a file
+     */
+    getFile(): Promise<File | null>;
+    /**
+     * Get the content as a Blob.
+     *
+     * @returns The Blob object, or null if not available as a blob
+     */
+    getBlob(): Promise<Blob | null>;
+}
+/**
+ * A handler that processes content items of specific MIME types.
+ *
+ * Handlers are registered with the pipeline and matched against incoming
+ * items by MIME type. Higher-priority handlers run first. The first handler
+ * that returns `true` from `handle()` stops all processing.
+ *
+ * @example
+ * ```ts
+ * const handler: ContentHandler = {
+ *   id: 'plain-text',
+ *   accept: ['text/plain'],
+ *   priority: -100,
+ *   async handle(item, context) {
+ *     const text = await item.getString();
+ *     if (!text) return false;
+ *     context.dispatch([{ type: 'insert_text', offset: context.insertOffset, text }]);
+ *     return true;
+ *   },
+ * };
+ * ```
+ */
+export interface ContentHandler {
+    /** Unique identifier for this handler. */
+    readonly id: string;
+    /**
+     * MIME type patterns this handler accepts.
+     * Supports exact match ('text/plain'), wildcard subtypes ('image/*'),
+     * and catch-all ('*\/*').
+     */
+    readonly accept: readonly string[];
+    /**
+     * Priority for handler ordering. Higher values run first.
+     * Built-in handlers use negative values to allow user handlers to take precedence.
+     * Default: 0.
+     */
+    readonly priority?: number;
+    /**
+     * Optional pre-check before calling handle().
+     * Return false to skip this handler for this item.
+     *
+     * @param item - The content item to check
+     * @param context - The processing context
+     * @returns Whether this handler can process the item
+     */
+    canHandle?(item: ContentItem, context: ContentContext): Promise<boolean>;
+    /**
+     * Process a content item.
+     *
+     * @param item - The content item to process
+     * @param context - The processing context with dispatch and helpers
+     * @returns true if the item was handled, false to pass to next handler
+     */
+    handle(item: ContentItem, context: ContentContext): Promise<boolean>;
+}
+/**
+ * Context provided to content handlers during processing.
+ *
+ * Exposes the engine, commands, and helper methods for dispatching operations.
+ * All operations dispatched through this context are buffered and flushed as
+ * a single batch when processing completes, ensuring a single undo group.
+ *
+ * @example
+ * ```ts
+ * async handle(item: ContentItem, context: ContentContext): Promise<boolean> {
+ *   const offset = context.deleteSelectionAndGetOffset();
+ *   const text = await item.getString();
+ *   if (!text) return false;
+ *   context.dispatch([{ type: 'insert_text', offset, text }]);
+ *   return true;
+ * }
+ * ```
+ */
+export interface ContentContext {
+    /** The RTIF engine instance. */
+    readonly engine: IEditorEngine;
+    /** The command bus for executing commands. */
+    readonly commands: CommandBus;
+    /** The absolute offset where content will be inserted. */
+    readonly insertOffset: number;
+    /** How this content entered the editor. */
+    readonly source: ContentItemSource;
+    /**
+     * Delete the current selection (if non-collapsed) and return the insert offset.
+     *
+     * This is idempotent — calling it multiple times within the same handler
+     * only deletes once. Returns the start of the (former) selection range.
+     *
+     * @returns The absolute offset where content should be inserted
+     */
+    deleteSelectionAndGetOffset(): number;
+    /**
+     * Buffer operations for dispatch.
+     *
+     * Operations are NOT dispatched immediately. They are collected and flushed
+     * as a single `engine.dispatch()` call when the handler returns true.
+     *
+     * @param ops - Operations to add to the buffer
+     */
+    dispatch(ops: Operation[]): void;
+    /**
+     * Generate a unique block ID for split_block operations.
+     *
+     * @returns A unique block ID string
+     */
+    generateBlockId(): string;
+}
+export type { Disposable } from './types.js';
+/**
+ * Emitted before content items are processed.
+ * Call `preventDefault()` to cancel processing.
+ *
+ * @example
+ * ```ts
+ * pipeline.onEvent((event) => {
+ *   if (event.type === 'contentReceived' && shouldBlock(event.items)) {
+ *     event.preventDefault();
+ *   }
+ * });
+ * ```
+ */
+export interface ContentReceivedEvent {
+    readonly type: 'contentReceived';
+    readonly items: readonly ContentItem[];
+    readonly source: ContentItemSource;
+    prevented: boolean;
+    preventDefault(): void;
+}
+/**
+ * Emitted when a handler successfully processes a content item.
+ *
+ * @example
+ * ```ts
+ * pipeline.onEvent((event) => {
+ *   if (event.type === 'contentHandled') {
+ *     console.log(`Handled by ${event.handlerId}`);
+ *   }
+ * });
+ * ```
+ */
+export interface ContentHandledEvent {
+    readonly type: 'contentHandled';
+    readonly handlerId: string;
+    readonly item: ContentItem;
+}
+/**
+ * Emitted when no handler accepted a content item.
+ *
+ * @example
+ * ```ts
+ * pipeline.onEvent((event) => {
+ *   if (event.type === 'contentRejected') {
+ *     console.warn(`No handler for ${event.item.type}: ${event.reason}`);
+ *   }
+ * });
+ * ```
+ */
+export interface ContentRejectedEvent {
+    readonly type: 'contentRejected';
+    readonly item: ContentItem;
+    readonly reason: 'no-handler' | 'all-declined';
+}
+/**
+ * Union of all content pipeline events.
+ */
+export type ContentPipelineEvent = ContentReceivedEvent | ContentHandledEvent | ContentRejectedEvent;
+/**
+ * The content pipeline processes incoming content (paste, drop, programmatic)
+ * through a priority-ordered chain of handlers.
+ *
+ * @example
+ * ```ts
+ * const pipeline = createContentPipeline();
+ * pipeline.register(createPlainTextHandler(() => generateId()));
+ * pipeline.register(createRtifPasteHandler(() => generateId()));
+ *
+ * const items = extractFromPaste(clipboardEvent);
+ * await pipeline.process(items, {
+ *   engine,
+ *   commands: commandBus,
+ *   source: 'paste',
+ *   generateBlockId: () => generateId(),
+ * });
+ * ```
+ */
+export interface ContentPipeline {
+    /**
+     * Register a content handler.
+     *
+     * @param handler - The handler to register
+     * @returns A disposable that unregisters the handler when disposed
+     *
+     * @example
+     * ```ts
+     * const registration = pipeline.register(myHandler);
+     * registration.dispose(); // unregister
+     * ```
+     */
+    register(handler: ContentHandler): Disposable;
+    /**
+     * Process an array of content items through the handler chain.
+     *
+     * Uses handler-first iteration: for each handler (sorted by descending priority),
+     * check each item. The first handler+item match that returns true from handle()
+     * stops ALL processing. All dispatched operations are flushed as a single
+     * engine.dispatch() call.
+     *
+     * @param items - Content items to process
+     * @param contextOpts - Options for creating the processing context
+     * @returns true if any handler accepted an item, false otherwise
+     *
+     * @example
+     * ```ts
+     * const handled = await pipeline.process(items, {
+     *   engine,
+     *   commands: commandBus,
+     *   source: 'paste',
+     *   generateBlockId: () => crypto.randomUUID(),
+     * });
+     * ```
+     */
+    process(items: ContentItem[], contextOpts: ContentContextOpts): Promise<boolean>;
+    /**
+     * Check whether any registered handler accepts a given MIME type.
+     *
+     * @param type - MIME type to check
+     * @returns true if at least one handler accepts this type
+     *
+     * @example
+     * ```ts
+     * if (pipeline.hasHandlerForType('text/html')) { ... }
+     * ```
+     */
+    hasHandlerForType(type: string): boolean;
+    /**
+     * Subscribe to pipeline events.
+     *
+     * @param listener - Event listener callback
+     * @returns Unsubscribe function
+     *
+     * @example
+     * ```ts
+     * const unsub = pipeline.onEvent((event) => console.log(event.type));
+     * unsub();
+     * ```
+     */
+    onEvent(listener: (event: ContentPipelineEvent) => void): () => void;
+    /**
+     * Destroy the pipeline, removing all handlers and listeners.
+     */
+    destroy(): void;
+}
+/**
+ * Options for creating a content processing context.
+ *
+ * @example
+ * ```ts
+ * const opts: ContentContextOpts = {
+ *   engine,
+ *   commands: commandBus,
+ *   source: 'paste',
+ *   generateBlockId: () => crypto.randomUUID(),
+ * };
+ * ```
+ */
+export interface ContentContextOpts {
+    /** The RTIF engine instance. */
+    readonly engine: IEditorEngine;
+    /** The command bus. */
+    readonly commands: CommandBus;
+    /** How this content entered the editor. */
+    readonly source: ContentItemSource;
+    /**
+     * For drop events, the absolute offset at the drop position.
+     * If undefined, uses the current engine selection.
+     */
+    readonly dropOffset?: number;
+    /** Factory for generating unique block IDs. */
+    readonly generateBlockId: () => string;
+}
+/**
+ * Check whether a MIME type matches any of the given patterns.
+ *
+ * Supports exact match, wildcard subtypes (e.g., `image/*`), and
+ * catch-all (`*\/*`).
+ *
+ * @param contentType - The MIME type to test (e.g., 'text/plain')
+ * @param patterns - Array of MIME patterns to match against
+ * @returns true if the content type matches any pattern
+ *
+ * @example
+ * ```ts
+ * matchesMime('image/png', ['image/*']);       // true
+ * matchesMime('text/plain', ['text/html']);     // false
+ * matchesMime('text/plain', ['*\/*']);          // true (catch-all)
+ * ```
+ */
+export declare function matchesMime(contentType: string, patterns: readonly string[]): boolean;
+/**
+ * Create a content pipeline instance.
+ *
+ * The pipeline manages a priority-ordered set of content handlers and routes
+ * incoming content items through them. All operations dispatched by handlers
+ * are buffered and flushed as a single engine.dispatch() call, ensuring each
+ * paste/drop is a single undo group.
+ *
+ * @returns A new ContentPipeline instance
+ *
+ * @example
+ * ```ts
+ * const pipeline = createContentPipeline();
+ * pipeline.register(createPlainTextHandler(() => generateId()));
+ * ```
+ */
+export declare function createContentPipeline(): ContentPipeline;
+//# sourceMappingURL=content-pipeline.d.ts.map

package/dist/content-pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-pipeline.d.ts","sourceRoot":"","sources":["../src/content-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAO7C;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,cAAc,CAAC;AAE5E;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,WAAW;IAC1B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IAEnC;;;;OAIG;IACH,SAAS,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEpC;;;;OAIG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IAEhC;;;;OAIG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,cAAc;IAC7B,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAEnC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B;;;;;;;OAOG;IACH,SAAS,CAAC,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEzE;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,cAAc;IAC7B,gCAAgC;IAChC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAE/B,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAE9B,0DAA0D;IAC1D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IAEnC;;;;;;;OAOG;IACH,2BAA2B,IAAI,MAAM,CAAC;IAEtC;;;;;;;OAOG;IACH,QAAQ,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC;IAEjC;;;;OAIG;IACH,eAAe,IAAI,MAAM,CAAC;CAC3B;AAGD,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAM7C;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,SAAS,EAAE,OAAO,CAAC;IACnB,cAAc,IAAI,IAAI,CAAC;CACxB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;CAC5B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG,cAAc,CAAC;CAChD;AAED;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAC5B,oBAAoB,GACpB,mBAAmB,GACnB,oBAAoB,CAAC;AAMzB;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,UAAU,CAAC;IAE9C;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,OAAO,CACL,KAAK,EAAE,WAAW,EAAE,EACpB,WAAW,EAAE,kBAAkB,GAC9B,OAAO,CAAC,OAAO,CAAC,CAAC;IAEpB;;;;;;;;;;OAUG;IACH,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAEzC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAErE;;OAEG;IACH,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,kBAAkB;IACjC,gCAAgC;IAChC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAE/B,uBAAuB;IACvB,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAE9B,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IAEnC;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B,+CAA+C;IAC/C,QAAQ,CAAC,eAAe,EAAE,MAAM,MAAM,CAAC;CACxC;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CACzB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,OAAO,CAiBT;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,IAAI,eAAe,CA+LvD"}