@lexmata/micropdf 0.4.0

package/dist/enhanced.d.ts

@@ -0,0 +1,226 @@
+/**
+ * Enhanced - MicroPDF high-level convenience API
+ *
+ * This module provides MicroPDF-specific high-level functions for common PDF operations.
+ * These are convenience wrappers that simplify complex workflows and provide a more
+ * user-friendly API for common tasks.
+ *
+ * The Enhanced API includes operations like:
+ * - Adding blank pages
+ * - Adding watermarks
+ * - Drawing shapes (rectangles, circles, lines)
+ * - Merging and splitting PDFs
+ * - Optimizing and linearizing PDFs
+ *
+ * @module enhanced
+ * @example
+ * ```typescript
+ * import { Enhanced, Document } from 'micropdf';
+ *
+ * const enhanced = new Enhanced();
+ * const doc = Document.open('document.pdf');
+ *
+ * // Add a blank page
+ * enhanced.addBlankPage(doc, 612, 792); // US Letter size
+ *
+ * // Add a watermark
+ * enhanced.addWatermark(
+ *   doc,
+ *   'CONFIDENTIAL',
+ *   { x: 300, y: 400 },
+ *   12,
+ *   0.3 // 30% opacity
+ * );
+ *
+ * // Draw shapes
+ * enhanced.drawRectangle(
+ *   doc,
+ *   0, // page index
+ *   { x0: 100, y0: 100, x1: 200, y1: 200 },
+ *   [255, 0, 0], // red
+ *   0.5, // opacity
+ *   2, // line width
+ *   true // fill
+ * );
+ *
+ * // Save
+ * doc.save('output.pdf');
+ * doc.close();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Merge multiple PDFs
+ * const enhanced = new Enhanced();
+ * enhanced.mergePdfs(
+ *   ['doc1.pdf', 'doc2.pdf', 'doc3.pdf'],
+ *   'merged.pdf'
+ * );
+ *
+ * // Split a PDF
+ * enhanced.splitPdf(
+ *   'document.pdf',
+ *   'output-dir',
+ *   { startPage: 0, endPage: 10 }
+ * );
+ *
+ * // Optimize a PDF
+ * enhanced.optimizePdf('large.pdf', 'optimized.pdf');
+ *
+ * // Linearize for web viewing
+ * enhanced.linearizePdf('document.pdf', 'web-optimized.pdf');
+ * ```
+ */
+import { Context } from './context.js';
+import { Document } from './document.js';
+import { type ColorLike } from './geometry.js';
+/**
+ * Enhanced MicroPDF API for high-level PDF operations.
+ *
+ * Provides convenient methods for common PDF manipulation tasks that would
+ * otherwise require multiple lower-level API calls.
+ *
+ * @class Enhanced
+ * @example
+ * ```typescript
+ * const enhanced = new Enhanced();
+ * const doc = Document.open('document.pdf');
+ *
+ * // Add a watermark to all pages
+ * for (let i = 0; i < doc.pageCount; i++) {
+ *   enhanced.addWatermark(
+ *     doc,
+ *     'DRAFT',
+ *     { x: 300, y: 400 },
+ *     48,
+ *     0.2
+ *   );
+ * }
+ *
+ * doc.save('watermarked.pdf');
+ * doc.close();
+ * ```
+ */
+export declare class Enhanced {
+    private _ctx;
+    constructor(ctx?: Context);
+    /**
+     * Get the context
+     */
+    get context(): Context;
+    /**
+     * Add a blank page to a document using FFI
+     * @returns Page number of newly added page
+     * @throws Error when native bindings are not available
+     */
+    addBlankPage(_doc: Document, width: number, height: number): number;
+    /**
+     * Draw a line on a page using FFI
+     * @throws Error when native bindings are not available
+     */
+    drawLine(page: unknown, x0: number, y0: number, x1: number, y1: number, color: ColorLike, alpha?: number, lineWidth?: number): void;
+    /**
+     * Draw a rectangle on a page using FFI
+     * @throws Error when native bindings are not available
+     */
+    drawRectangle(page: unknown, x: number, y: number, width: number, height: number, color: ColorLike, alpha?: number, fill?: boolean): void;
+    /**
+     * Draw a circle on a page using FFI
+     * @throws Error when native bindings are not available
+     */
+    drawCircle(page: unknown, x: number, y: number, radius: number, color: ColorLike, alpha?: number, fill?: boolean): void;
+    /**
+     * Add watermark to PDF using FFI
+     * @throws Error when native bindings are not available
+     */
+    addWatermark(inputPath: string, _outputPath: string, text: string, _x?: number, _y?: number, fontSize?: number, opacity?: number): Promise<void>;
+    /**
+     * Merge multiple PDFs into one using FFI
+     * @throws Error when native bindings are not available
+     */
+    mergePDFs(inputPaths: string[], outputPath: string): Promise<void>;
+    /**
+     * Split PDF into separate files using FFI
+     * @returns Array of output file paths
+     * @throws Error when native bindings are not available
+     */
+    splitPDF(inputPath: string, outputDir: string): Promise<string[]>;
+    /**
+     * Optimize PDF (compress, remove unused objects) using FFI
+     * @throws Error when native bindings are not available
+     */
+    optimizePDF(path: string): Promise<void>;
+    /**
+     * Linearize PDF for fast web viewing using FFI
+     * @throws Error when native bindings are not available
+     */
+    linearizePDF(inputPath: string, outputPath: string): Promise<void>;
+    /**
+     * Write document to PDF file using FFI
+     * @throws Error when native bindings are not available
+     */
+    writePDF(doc: Document, path: string): Promise<void>;
+    /**
+     * Merge multiple PDF files into a single output file
+     *
+     * @param inputPaths Array of PDF file paths to merge (in order)
+     * @param outputPath Path where the merged PDF will be saved
+     * @returns Promise that resolves to the number of pages in the merged PDF
+     * @throws Error if any input file is invalid, not found, or merge fails
+     * @throws Error when native bindings are not available
+     *
+     * @example
+     * ```typescript
+     * import { Enhanced } from 'micropdf';
+     *
+     * const enhanced = new Enhanced();
+     * const pageCount = await enhanced.mergePDF(
+     *   ['document1.pdf', 'document2.pdf', 'document3.pdf'],
+     *   'merged.pdf'
+     * );
+     * console.log(`Merged ${pageCount} pages`);
+     * ```
+     *
+     * @example Large document handling
+     * ```typescript
+     * // Works with large documents (5000+ pages)
+     * const pageCount = await enhanced.mergePDF(
+     *   ['large_doc1.pdf', 'large_doc2.pdf'],
+     *   'combined.pdf'
+     * );
+     * ```
+     */
+    mergePDF(inputPaths: string[], outputPath: string): Promise<number>;
+    /**
+     * Create a new blank PDF document
+     * @param width Page width in points (default A4 width: 595)
+     * @param height Page height in points (default A4 height: 842)
+     * @throws Error This is a static method that requires instance context
+     */
+    static createBlankDocument(_width?: number, _height?: number): Document;
+    /**
+     * Quick create PDF with text
+     * @throws Error This is a static method that requires instance context
+     */
+    static createTextPDF(_text: string, _outputPath: string, _options?: {
+        fontSize?: number;
+        fontName?: string;
+        pageWidth?: number;
+        pageHeight?: number;
+    }): Promise<void>;
+}
+/**
+ * Get global enhanced API
+ */
+export declare function getEnhanced(): Enhanced;
+/**
+ * Convenience functions (use global instance)
+ */
+export declare function addWatermark(inputPath: string, outputPath: string, text: string, x?: number, y?: number, fontSize?: number, opacity?: number): Promise<void>;
+export declare function mergePDFs(inputPaths: string[], outputPath: string): Promise<void>;
+export declare function splitPDF(inputPath: string, outputDir: string): Promise<string[]>;
+export declare function optimizePDF(path: string): Promise<void>;
+export declare function linearizePDF(inputPath: string, outputPath: string): Promise<void>;
+export declare function createBlankDocument(width?: number, height?: number): Document;
+export declare function createTextPDF(text: string, outputPath: string, options?: Parameters<typeof Enhanced.createTextPDF>[2]): Promise<void>;
+//# sourceMappingURL=enhanced.d.ts.map

package/dist/enhanced.d.ts.map

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

package/dist/enhanced.js

@@ -0,0 +1,368 @@
+/**
+ * Enhanced - MicroPDF high-level convenience API
+ *
+ * This module provides MicroPDF-specific high-level functions for common PDF operations.
+ * These are convenience wrappers that simplify complex workflows and provide a more
+ * user-friendly API for common tasks.
+ *
+ * The Enhanced API includes operations like:
+ * - Adding blank pages
+ * - Adding watermarks
+ * - Drawing shapes (rectangles, circles, lines)
+ * - Merging and splitting PDFs
+ * - Optimizing and linearizing PDFs
+ *
+ * @module enhanced
+ * @example
+ * ```typescript
+ * import { Enhanced, Document } from 'micropdf';
+ *
+ * const enhanced = new Enhanced();
+ * const doc = Document.open('document.pdf');
+ *
+ * // Add a blank page
+ * enhanced.addBlankPage(doc, 612, 792); // US Letter size
+ *
+ * // Add a watermark
+ * enhanced.addWatermark(
+ *   doc,
+ *   'CONFIDENTIAL',
+ *   { x: 300, y: 400 },
+ *   12,
+ *   0.3 // 30% opacity
+ * );
+ *
+ * // Draw shapes
+ * enhanced.drawRectangle(
+ *   doc,
+ *   0, // page index
+ *   { x0: 100, y0: 100, x1: 200, y1: 200 },
+ *   [255, 0, 0], // red
+ *   0.5, // opacity
+ *   2, // line width
+ *   true // fill
+ * );
+ *
+ * // Save
+ * doc.save('output.pdf');
+ * doc.close();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Merge multiple PDFs
+ * const enhanced = new Enhanced();
+ * enhanced.mergePdfs(
+ *   ['doc1.pdf', 'doc2.pdf', 'doc3.pdf'],
+ *   'merged.pdf'
+ * );
+ *
+ * // Split a PDF
+ * enhanced.splitPdf(
+ *   'document.pdf',
+ *   'output-dir',
+ *   { startPage: 0, endPage: 10 }
+ * );
+ *
+ * // Optimize a PDF
+ * enhanced.optimizePdf('large.pdf', 'optimized.pdf');
+ *
+ * // Linearize for web viewing
+ * enhanced.linearizePdf('document.pdf', 'web-optimized.pdf');
+ * ```
+ */
+import { getDefaultContext } from './context.js';
+import { Color } from './geometry.js';
+import { native } from './native.js';
+/**
+ * Enhanced MicroPDF API for high-level PDF operations.
+ *
+ * Provides convenient methods for common PDF manipulation tasks that would
+ * otherwise require multiple lower-level API calls.
+ *
+ * @class Enhanced
+ * @example
+ * ```typescript
+ * const enhanced = new Enhanced();
+ * const doc = Document.open('document.pdf');
+ *
+ * // Add a watermark to all pages
+ * for (let i = 0; i < doc.pageCount; i++) {
+ *   enhanced.addWatermark(
+ *     doc,
+ *     'DRAFT',
+ *     { x: 300, y: 400 },
+ *     48,
+ *     0.2
+ *   );
+ * }
+ *
+ * doc.save('watermarked.pdf');
+ * doc.close();
+ * ```
+ */
+export class Enhanced {
+    _ctx;
+    constructor(ctx) {
+        this._ctx = ctx || getDefaultContext();
+    }
+    /**
+     * Get the context
+     */
+    get context() {
+        return this._ctx;
+    }
+    // ============================================================================
+    // Page Operations
+    // ============================================================================
+    /**
+     * Add a blank page to a document using FFI
+     * @returns Page number of newly added page
+     * @throws Error when native bindings are not available
+     */
+    addBlankPage(_doc, width, height) {
+        // Get native handles (will be available when Document exposes them)
+        const ctx = this._ctx?._nativeCtx;
+        const nativeDoc = _doc?._doc;
+        if (!ctx || !nativeDoc) {
+            throw new Error('Adding blank page requires native FFI bindings (mp_add_blank_page)');
+        }
+        return native.npAddBlankPage(ctx, nativeDoc, width, height);
+    }
+    // ============================================================================
+    // Drawing Operations
+    // ============================================================================
+    /**
+     * Draw a line on a page using FFI
+     * @throws Error when native bindings are not available
+     */
+    drawLine(page, x0, y0, x1, y1, color, alpha = 1.0, lineWidth = 1.0) {
+        const ctx = this._ctx?._nativeCtx;
+        const nativePage = page?._page;
+        if (!ctx || !nativePage) {
+            throw new Error('Drawing line requires native FFI bindings (mp_draw_line)');
+        }
+        const c = Color.from(color);
+        const colorArray = [c.r, c.g, c.b];
+        native.npDrawLine(ctx, nativePage, x0, y0, x1, y1, colorArray, alpha, lineWidth);
+    }
+    /**
+     * Draw a rectangle on a page using FFI
+     * @throws Error when native bindings are not available
+     */
+    drawRectangle(page, x, y, width, height, color, alpha = 1.0, fill = false) {
+        const ctx = this._ctx?._nativeCtx;
+        const nativePage = page?._page;
+        if (!ctx || !nativePage) {
+            throw new Error('Drawing rectangle requires native FFI bindings (mp_draw_rectangle)');
+        }
+        const c = Color.from(color);
+        const colorArray = [c.r, c.g, c.b];
+        native.npDrawRectangle(ctx, nativePage, x, y, width, height, colorArray, alpha, fill);
+    }
+    /**
+     * Draw a circle on a page using FFI
+     * @throws Error when native bindings are not available
+     */
+    drawCircle(page, x, y, radius, color, alpha = 1.0, fill = false) {
+        const ctx = this._ctx?._nativeCtx;
+        const nativePage = page?._page;
+        if (!ctx || !nativePage) {
+            throw new Error('Drawing circle requires native FFI bindings (mp_draw_circle)');
+        }
+        const c = Color.from(color);
+        const colorArray = [c.r, c.g, c.b];
+        native.npDrawCircle(ctx, nativePage, x, y, radius, colorArray, alpha, fill);
+    }
+    // ============================================================================
+    // Watermark Operations
+    // ============================================================================
+    /**
+     * Add watermark to PDF using FFI
+     * @throws Error when native bindings are not available
+     */
+    async addWatermark(inputPath, _outputPath, text, _x = 100, _y = 100, fontSize = 48, opacity = 0.3) {
+        const ctx = this._ctx?._nativeCtx;
+        if (!ctx) {
+            throw new Error('Watermark requires native FFI bindings (mp_add_watermark)');
+        }
+        // Open document
+        const doc = native.openDocumentFromPath(ctx, inputPath);
+        native.npAddWatermark(ctx, doc, text, fontSize, opacity);
+        native.dropDocument(ctx, doc);
+    }
+    // ============================================================================
+    // PDF Manipulation
+    // ============================================================================
+    /**
+     * Merge multiple PDFs into one using FFI
+     * @throws Error when native bindings are not available
+     */
+    async mergePDFs(inputPaths, outputPath) {
+        const ctx = this._ctx?._nativeCtx;
+        if (!ctx) {
+            throw new Error('PDF merging requires native FFI bindings (mp_merge_pdfs)');
+        }
+        native.npMergePDFs(ctx, inputPaths, inputPaths.length, outputPath);
+    }
+    /**
+     * Split PDF into separate files using FFI
+     * @returns Array of output file paths
+     * @throws Error when native bindings are not available
+     */
+    async splitPDF(inputPath, outputDir) {
+        const ctx = this._ctx?._nativeCtx;
+        if (!ctx) {
+            throw new Error('PDF splitting requires native FFI bindings (mp_split_pdf)');
+        }
+        return native.npSplitPDF(ctx, inputPath, outputDir);
+    }
+    /**
+     * Optimize PDF (compress, remove unused objects) using FFI
+     * @throws Error when native bindings are not available
+     */
+    async optimizePDF(path) {
+        const ctx = this._ctx?._nativeCtx;
+        if (!ctx) {
+            throw new Error('PDF optimization requires native FFI bindings (mp_optimize_pdf)');
+        }
+        native.npOptimizePDF(ctx, path);
+    }
+    /**
+     * Linearize PDF for fast web viewing using FFI
+     * @throws Error when native bindings are not available
+     */
+    async linearizePDF(inputPath, outputPath) {
+        const ctx = this._ctx?._nativeCtx;
+        if (!ctx) {
+            throw new Error('PDF linearization requires native FFI bindings (mp_linearize_pdf)');
+        }
+        native.npLinearizePDF(ctx, inputPath, outputPath);
+    }
+    /**
+     * Write document to PDF file using FFI
+     * @throws Error when native bindings are not available
+     */
+    async writePDF(doc, path) {
+        const ctx = this._ctx?._nativeCtx;
+        const nativeDoc = doc?._doc;
+        if (!ctx || !nativeDoc) {
+            throw new Error('Writing PDF requires native FFI bindings (pdf_save_document)');
+        }
+        native.saveDocument(ctx, nativeDoc, path);
+    }
+    /**
+     * Merge multiple PDF files into a single output file
+     *
+     * @param inputPaths Array of PDF file paths to merge (in order)
+     * @param outputPath Path where the merged PDF will be saved
+     * @returns Promise that resolves to the number of pages in the merged PDF
+     * @throws Error if any input file is invalid, not found, or merge fails
+     * @throws Error when native bindings are not available
+     *
+     * @example
+     * ```typescript
+     * import { Enhanced } from 'micropdf';
+     *
+     * const enhanced = new Enhanced();
+     * const pageCount = await enhanced.mergePDF(
+     *   ['document1.pdf', 'document2.pdf', 'document3.pdf'],
+     *   'merged.pdf'
+     * );
+     * console.log(`Merged ${pageCount} pages`);
+     * ```
+     *
+     * @example Large document handling
+     * ```typescript
+     * // Works with large documents (5000+ pages)
+     * const pageCount = await enhanced.mergePDF(
+     *   ['large_doc1.pdf', 'large_doc2.pdf'],
+     *   'combined.pdf'
+     * );
+     * ```
+     */
+    async mergePDF(inputPaths, outputPath) {
+        const ctx = this._ctx?._nativeCtx;
+        if (!ctx) {
+            throw new Error('Merging PDFs requires native FFI bindings (mp_merge_pdfs)');
+        }
+        if (!inputPaths || inputPaths.length === 0) {
+            throw new Error('At least one input PDF path is required');
+        }
+        if (!outputPath) {
+            throw new Error('Output path is required');
+        }
+        try {
+            const pageCount = native.npMergePDFs(ctx, inputPaths, inputPaths.length, outputPath);
+            if (pageCount < 0) {
+                throw new Error('PDF merge failed');
+            }
+            return pageCount;
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Failed to merge PDFs: ${error.message}`);
+            }
+            throw new Error('Failed to merge PDFs: Unknown error');
+        }
+    }
+    // ============================================================================
+    // Convenience Factory Methods
+    // ============================================================================
+    /**
+     * Create a new blank PDF document
+     * @param width Page width in points (default A4 width: 595)
+     * @param height Page height in points (default A4 height: 842)
+     * @throws Error This is a static method that requires instance context
+     */
+    static createBlankDocument(_width = 595, _height = 842) {
+        throw new Error('Document creation requires native FFI bindings (fz_new_document). ' +
+            'Use Document.fromBuffer() or Enhanced instance methods instead.');
+    }
+    /**
+     * Quick create PDF with text
+     * @throws Error This is a static method that requires instance context
+     */
+    static async createTextPDF(_text, _outputPath, _options) {
+        throw new Error('PDF text creation requires native FFI bindings (fz_new_document, fz_show_string). ' +
+            'Use Enhanced instance methods instead.');
+    }
+}
+/**
+ * Global enhanced API instance
+ */
+let globalEnhanced = null;
+/**
+ * Get global enhanced API
+ */
+export function getEnhanced() {
+    if (!globalEnhanced) {
+        globalEnhanced = new Enhanced();
+    }
+    return globalEnhanced;
+}
+/**
+ * Convenience functions (use global instance)
+ */
+export async function addWatermark(inputPath, outputPath, text, x, y, fontSize, opacity) {
+    return getEnhanced().addWatermark(inputPath, outputPath, text, x, y, fontSize, opacity);
+}
+export async function mergePDFs(inputPaths, outputPath) {
+    return getEnhanced().mergePDFs(inputPaths, outputPath);
+}
+export async function splitPDF(inputPath, outputDir) {
+    return getEnhanced().splitPDF(inputPath, outputDir);
+}
+export async function optimizePDF(path) {
+    return getEnhanced().optimizePDF(path);
+}
+export async function linearizePDF(inputPath, outputPath) {
+    return getEnhanced().linearizePDF(inputPath, outputPath);
+}
+export function createBlankDocument(width, height) {
+    return Enhanced.createBlankDocument(width, height);
+}
+export async function createTextPDF(text, outputPath, options) {
+    return Enhanced.createTextPDF(text, outputPath, options);
+}
+//# sourceMappingURL=enhanced.js.map

package/dist/enhanced.js.map

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

package/dist/filter.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Filter - PDF compression and decompression filters
+ *
+ * This implementation mirrors the Rust `pdf::filter` module for 100% API compatibility.
+ */
+import { type FilterType } from './types.js';
+/**
+ * Compress data using FlateDecode (zlib deflate)
+ */
+export declare function flateEncode(data: Uint8Array): Uint8Array;
+/**
+ * Decompress FlateDecode (zlib inflate) data
+ */
+export declare function flateDecode(data: Uint8Array): Uint8Array;
+/**
+ * Encode data to ASCII hex
+ */
+export declare function asciiHexEncode(data: Uint8Array): Uint8Array;
+/**
+ * Decode ASCII hex data
+ */
+export declare function asciiHexDecode(data: Uint8Array): Uint8Array;
+/**
+ * Encode data to ASCII85
+ */
+export declare function ascii85Encode(data: Uint8Array): Uint8Array;
+/**
+ * Decode ASCII85 data
+ */
+export declare function ascii85Decode(data: Uint8Array): Uint8Array;
+/**
+ * Encode data using Run-Length Encoding
+ */
+export declare function runLengthEncode(data: Uint8Array): Uint8Array;
+/**
+ * Decode Run-Length encoded data
+ */
+export declare function runLengthDecode(data: Uint8Array): Uint8Array;
+/**
+ * Decode LZW compressed data
+ */
+export declare function lzwDecode(data: Uint8Array, earlyChange?: boolean): Uint8Array;
+/**
+ * Decode data using the specified filter
+ */
+export declare function decodeFilter(filter: FilterType, data: Uint8Array, params?: Record<string, unknown>): Uint8Array;
+/**
+ * Encode data using the specified filter
+ */
+export declare function encodeFilter(filter: FilterType, data: Uint8Array, _params?: Record<string, unknown>): Uint8Array;
+//# sourceMappingURL=filter.d.ts.map

package/dist/filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../src/filter.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAiB,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAM5D;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAUxD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAUxD;AAMD;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAG3D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAiB3D;AAUD;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAyC1D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CA6D1D;AAMD;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CA0C5D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CA8B5D;AAMD;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,UAAU,EAAE,WAAW,GAAE,OAAc,GAAG,UAAU,CAoFnF;AAMD;;GAEG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,UAAU,EAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,UAAU,CAyBZ;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,UAAU,EAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,UAAU,CAyBZ"}