@bendyline/squisq-cli 1.0.0 → 1.1.0

package/README.md

@@ -0,0 +1,121 @@
+# @bendyline/squisq-cli
+
+Command-line tool for converting Squisq documents to multiple formats and rendering them to video. Reads Markdown files, ZIP/DBK containers, or folders as input.
+
+Part of the [Squisq](https://github.com/bendyline/squisq) monorepo.
+
+[![npm](https://img.shields.io/npm/v/@bendyline/squisq-cli)](https://www.npmjs.com/package/@bendyline/squisq-cli)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/bendyline/squisq/blob/main/LICENSE)
+
+## Install
+
+```bash
+npm install -g @bendyline/squisq-cli
+```
+
+## Commands
+
+### `squisq convert`
+
+Convert a Squisq document to DOCX, PPTX, PDF, HTML, or DBK (container ZIP):
+
+```bash
+squisq convert input.md --formats docx,pptx,pdf
+squisq convert project.dbk --output-dir ./out --formats html,docx
+squisq convert ./my-folder --formats pdf --theme documentary
+squisq convert input.md --theme cinematic --transform magazine --formats pptx
+```
+
+| Option         | Description                                      | Default     |
+| -------------- | ------------------------------------------------ | ----------- |
+| `--output-dir` | Output directory                                 | current dir |
+| `--formats`    | Comma-separated list: docx, pptx, pdf, html, dbk | all         |
+| `--theme`      | Squisq theme ID (e.g., documentary, cinematic)   | none        |
+| `--transform`  | Transform style (e.g., documentary, magazine)    | none        |
+
+### `squisq video`
+
+Render a Squisq document to MP4 video using Playwright for frame capture and native ffmpeg for encoding:
+
+```bash
+squisq video input.md output.mp4
+squisq video project.dbk --quality high --fps 30
+squisq video ./my-folder --orientation portrait --captions social
+```
+
+| Option          | Description               | Default   |
+| --------------- | ------------------------- | --------- |
+| `--fps`         | Frames per second (1–120) | 30        |
+| `--quality`     | draft, normal, or high    | normal    |
+| `--orientation` | landscape or portrait     | landscape |
+| `--captions`    | off, standard, or social  | off       |
+| `--width`       | Override width in pixels  | auto      |
+| `--height`      | Override height in pixels | auto      |
+
+**Requires:** [ffmpeg](https://ffmpeg.org/) installed and available on your PATH.
+
+## Programmatic API
+
+Use the CLI as a library from Node.js — no shell-out required:
+
+```ts
+import { renderDocToMp4, MemoryContentContainer, readInput } from '@bendyline/squisq-cli/api';
+
+// Load a document from disk
+const { doc, container } = await readInput('./my-article.md');
+
+// Render to MP4
+const result = await renderDocToMp4(doc, container, {
+  outputPath: './output.mp4',
+  fps: 30,
+  quality: 'high',
+  orientation: 'landscape',
+  captionStyle: 'social',
+  onProgress: (phase, pct) => console.log(`${phase}: ${pct}%`),
+});
+
+console.log(`Rendered ${result.frameCount} frames (${result.duration}s)`);
+```
+
+### `extractThumbnails`
+
+Extract JPEG thumbnails from the first frame of a rendered video:
+
+```ts
+import { extractThumbnails } from '@bendyline/squisq-cli/api';
+
+await extractThumbnails({
+  videoPath: './output.mp4',
+  outputDir: './thumbs',
+  slug: 'my-article',
+  sizes: [
+    { name: 'og', width: 1200, height: 630, filter: 'scale=1200:630' },
+    { name: 'thumb', width: 480, height: 270, filter: 'scale=480:270' },
+  ],
+});
+```
+
+See the full [API Reference](../../docs/API.md#bendylinesquisq-cli) for all types and options.
+
+## Input Formats
+
+The CLI accepts three types of input:
+
+| Input         | Description                                               |
+| ------------- | --------------------------------------------------------- |
+| `.md` file    | Plain Markdown file                                       |
+| `.zip`/`.dbk` | Container archive with document + embedded media          |
+| Folder        | Directory with a Markdown file and associated media files |
+
+## Related Packages
+
+| Package                                                                              | Description                                     |
+| ------------------------------------------------------------------------------------ | ----------------------------------------------- |
+| [@bendyline/squisq](https://www.npmjs.com/package/@bendyline/squisq)                 | Headless core — schemas, templates, markdown    |
+| [@bendyline/squisq-formats](https://www.npmjs.com/package/@bendyline/squisq-formats) | DOCX, PDF, HTML import/export (used by convert) |
+| [@bendyline/squisq-video](https://www.npmjs.com/package/@bendyline/squisq-video)     | Headless video rendering (used by video)        |
+| [@bendyline/squisq-react](https://www.npmjs.com/package/@bendyline/squisq-react)     | React components for rendering docs             |
+
+## License
+
+[MIT](https://github.com/bendyline/squisq/blob/main/LICENSE)

package/dist/__tests__/convert.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * convert command integration tests
+ *
+ * Exercises the full convert pipeline: input → all formats → output validation.
+ */
+export {};
+//# sourceMappingURL=convert.test.d.ts.map

package/dist/__tests__/convert.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convert.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/convert.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/__tests__/convert.test.js

@@ -0,0 +1,127 @@
+/**
+ * convert command integration tests
+ *
+ * Exercises the full convert pipeline: input → all formats → output validation.
+ */
+import { describe, it, before, after, beforeEach, afterEach } from 'mocha';
+import { expect } from 'chai';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { readFile, mkdir, rm, stat, writeFile as fsWriteFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { containerToZip } from '@bendyline/squisq-formats/container';
+import { MemoryContentContainer } from '@bendyline/squisq/storage';
+import { zipToContainer } from '@bendyline/squisq-formats/container';
+const exec = promisify(execFile);
+const CLI_PATH = join(import.meta.dirname, '..', '..', 'dist', 'index.js');
+const FIXTURE_MD = join(import.meta.dirname, 'fixtures', 'test.md');
+/**
+ * Run the CLI with the given args and return stdout/stderr.
+ */
+async function runCli(...args) {
+    return exec('node', [CLI_PATH, ...args], { timeout: 30000 });
+}
+describe('convert command', () => {
+    let tempDir;
+    beforeEach(async () => {
+        tempDir = join(tmpdir(), `squisq-convert-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+        await mkdir(tempDir, { recursive: true });
+    });
+    afterEach(async () => {
+        await rm(tempDir, { recursive: true, force: true });
+    });
+    it('converts a .md file to all formats', async () => {
+        const { stderr } = await runCli('convert', FIXTURE_MD, '-o', tempDir);
+        expect(stderr).to.include('Done.');
+        // Verify all four output files exist and are non-empty
+        for (const ext of ['docx', 'pdf', 'html', 'dbk']) {
+            const outPath = join(tempDir, `test.${ext}`);
+            const info = await stat(outPath);
+            expect(info.size).to.be.greaterThan(0);
+        }
+    });
+    it('respects --formats to produce only selected formats', async () => {
+        await runCli('convert', FIXTURE_MD, '-o', tempDir, '-f', 'docx,pdf');
+        // These should exist
+        const docxStat = await stat(join(tempDir, 'test.docx'));
+        expect(docxStat.size).to.be.greaterThan(0);
+        const pdfStat = await stat(join(tempDir, 'test.pdf'));
+        expect(pdfStat.size).to.be.greaterThan(0);
+        // These should NOT exist
+        for (const ext of ['html', 'dbk']) {
+            try {
+                await stat(join(tempDir, `test.${ext}`));
+                expect.fail(`test.${ext} should not exist`);
+            }
+            catch (err) {
+                expect(err.code).to.equal('ENOENT');
+            }
+        }
+    });
+    it('converts a .dbk container to all formats', async () => {
+        // Create a minimal .dbk container
+        const container = new MemoryContentContainer();
+        await container.writeDocument('# Container Doc\n\nSome content here.');
+        const blob = await containerToZip(container);
+        const buf = Buffer.from(await blob.arrayBuffer());
+        const dbkPath = join(tempDir, 'input.dbk');
+        await fsWriteFile(dbkPath, buf);
+        // Convert to a separate output dir to avoid overwriting the input .dbk
+        const outDir = join(tempDir, 'out');
+        const { stderr } = await runCli('convert', dbkPath, '-o', outDir);
+        expect(stderr).to.include('Done.');
+        for (const ext of ['docx', 'pdf', 'html', 'dbk']) {
+            const info = await stat(join(outDir, `input.${ext}`));
+            expect(info.size).to.be.greaterThan(0);
+        }
+    });
+    it('exits with error for nonexistent input', async () => {
+        try {
+            await runCli('convert', '/nonexistent/file.md', '-o', tempDir);
+            expect.fail('Expected a non-zero exit');
+        }
+        catch (err) {
+            // execFile rejects on non-zero exit
+            expect(err.stderr).to.include('Error');
+        }
+    });
+    describe('output validation', () => {
+        let validationDir;
+        before(async () => {
+            validationDir = join(tmpdir(), `squisq-validate-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+            await mkdir(validationDir, { recursive: true });
+            await runCli('convert', FIXTURE_MD, '-o', validationDir);
+        });
+        after(async () => {
+            await rm(validationDir, { recursive: true, force: true });
+        });
+        it('DOCX is a valid ZIP with WordprocessingML content', async () => {
+            const data = await readFile(join(validationDir, 'test.docx'));
+            // ZIP files start with PK (0x50 0x4B)
+            expect(data[0]).to.equal(0x50);
+            expect(data[1]).to.equal(0x4b);
+            // Should contain Content_Types and document.xml inside
+            const asString = data.toString('latin1');
+            expect(asString).to.include('[Content_Types].xml');
+            expect(asString).to.include('word/document.xml');
+        });
+        it('PDF starts with %PDF- magic bytes', async () => {
+            const data = await readFile(join(validationDir, 'test.pdf'));
+            const header = data.subarray(0, 5).toString('ascii');
+            expect(header).to.equal('%PDF-');
+        });
+        it('HTML contains SquisqPlayer and root element', async () => {
+            const html = await readFile(join(validationDir, 'test.html'), 'utf-8');
+            expect(html).to.include('SquisqPlayer');
+            expect(html).to.include('squisq-root');
+        });
+        it('DBK container round-trips through zipToContainer', async () => {
+            const data = await readFile(join(validationDir, 'test.dbk'));
+            const container = await zipToContainer(data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength));
+            const md = await container.readDocument();
+            expect(md).to.be.a('string').that.includes('# Test Document');
+        });
+    });
+});
+//# sourceMappingURL=convert.test.js.map

package/dist/__tests__/convert.test.js.map

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

package/dist/__tests__/readInput.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * readInput unit tests
+ */
+export {};
+//# sourceMappingURL=readInput.test.d.ts.map

package/dist/__tests__/readInput.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readInput.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/readInput.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/__tests__/readInput.test.js

@@ -0,0 +1,120 @@
+/**
+ * readInput unit tests
+ */
+import { describe, it, beforeEach, afterEach } from 'mocha';
+import { expect } from 'chai';
+import { readInput } from '../util/readInput.js';
+import { writeFile, mkdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { containerToZip } from '@bendyline/squisq-formats/container';
+import { MemoryContentContainer } from '@bendyline/squisq/storage';
+const FIXTURE_MD = join(import.meta.dirname, 'fixtures', 'test.md');
+describe('readInput', () => {
+    let tempDir;
+    beforeEach(async () => {
+        tempDir = join(tmpdir(), `squisq-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+        await mkdir(tempDir, { recursive: true });
+    });
+    afterEach(async () => {
+        await rm(tempDir, { recursive: true, force: true });
+    });
+    it('reads a .md file into a container and MarkdownDocument', async () => {
+        const result = await readInput(FIXTURE_MD);
+        expect(result.markdownDoc).to.not.equal(null);
+        expect(result.markdownDoc).to.have.property('type', 'document');
+        expect(result.markdownDoc.children).to.be.an('array');
+        expect(result.markdownDoc.children.length).to.be.greaterThan(0);
+        const docContent = await result.container.readDocument();
+        expect(docContent).to.be.a('string').that.includes('# Test Document');
+    });
+    it('reads a .zip container', async () => {
+        // Build a minimal container ZIP
+        const container = new MemoryContentContainer();
+        await container.writeDocument('# From ZIP\n\nHello from a ZIP container.');
+        const blob = await containerToZip(container);
+        const buf = Buffer.from(await blob.arrayBuffer());
+        const zipPath = join(tempDir, 'test.zip');
+        await writeFile(zipPath, buf);
+        const result = await readInput(zipPath);
+        expect(result.markdownDoc).to.not.equal(null);
+        expect(result.markdownDoc.type).to.equal('document');
+        const doc = await result.container.readDocument();
+        expect(doc).to.include('# From ZIP');
+    });
+    it('reads a .dbk container (same as .zip)', async () => {
+        const container = new MemoryContentContainer();
+        await container.writeDocument('# From DBK\n\nHello from a DBK container.');
+        const blob = await containerToZip(container);
+        const buf = Buffer.from(await blob.arrayBuffer());
+        const dbkPath = join(tempDir, 'test.dbk');
+        await writeFile(dbkPath, buf);
+        const result = await readInput(dbkPath);
+        expect(result.markdownDoc).to.not.equal(null);
+        expect(result.markdownDoc.type).to.equal('document');
+        const doc = await result.container.readDocument();
+        expect(doc).to.include('# From DBK');
+    });
+    it('reads a folder with markdown and media', async () => {
+        const folderPath = join(tempDir, 'mydoc');
+        await mkdir(folderPath, { recursive: true });
+        await writeFile(join(folderPath, 'index.md'), '# Folder Doc\n\nContent here.');
+        await writeFile(join(folderPath, 'image.txt'), 'placeholder');
+        const result = await readInput(folderPath);
+        expect(result.markdownDoc).to.not.equal(null);
+        expect(result.markdownDoc.type).to.equal('document');
+        const doc = await result.container.readDocument();
+        expect(doc).to.include('# Folder Doc');
+        // Media files are also in the container
+        const files = await result.container.listFiles();
+        const paths = files.map((f) => f.path);
+        expect(paths).to.include('image.txt');
+    });
+    it('throws on folder with no markdown file', async () => {
+        const folderPath = join(tempDir, 'empty');
+        await mkdir(folderPath, { recursive: true });
+        await writeFile(join(folderPath, 'image.png'), Buffer.from([0x89, 0x50]));
+        try {
+            await readInput(folderPath);
+            expect.fail('Expected an error');
+        }
+        catch (err) {
+            expect(err).to.be.instanceOf(Error);
+            expect(err.message).to.include('No markdown document');
+        }
+    });
+    it('reads a .json file as Doc JSON', async () => {
+        const doc = {
+            articleId: 'test-article',
+            duration: 30,
+            blocks: [{ id: 'b1', startTime: 0, duration: 30, audioSegment: 0 }],
+            audio: { segments: [] },
+        };
+        const jsonPath = join(tempDir, 'doc.json');
+        await writeFile(jsonPath, JSON.stringify(doc));
+        const result = await readInput(jsonPath);
+        expect(result.markdownDoc).to.equal(null);
+        expect(result.doc).to.deep.include({ articleId: 'test-article', duration: 30 });
+        expect(result.doc.blocks).to.have.length(1);
+    });
+    it('reads a folder with doc.json instead of markdown', async () => {
+        const folderPath = join(tempDir, 'jsondoc');
+        await mkdir(folderPath, { recursive: true });
+        const doc = {
+            articleId: 'folder-doc',
+            duration: 20,
+            blocks: [],
+            audio: { segments: [] },
+        };
+        await writeFile(join(folderPath, 'doc.json'), JSON.stringify(doc));
+        await writeFile(join(folderPath, 'image.txt'), 'placeholder');
+        const result = await readInput(folderPath);
+        expect(result.markdownDoc).to.equal(null);
+        expect(result.doc).to.deep.include({ articleId: 'folder-doc' });
+        // Media files are still in the container
+        const files = await result.container.listFiles();
+        const paths = files.map((f) => f.path);
+        expect(paths).to.include('image.txt');
+    });
+});
+//# sourceMappingURL=readInput.test.js.map

package/dist/__tests__/readInput.test.js.map

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

package/dist/api.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Programmatic Video API
+ *
+ * Provides a library-style entry point for rendering Squisq documents to MP4
+ * from Node.js callers (e.g., Qualla's pipeline). This avoids the need to shell
+ * out to the `squisq video` CLI and gives callers full control over the Doc,
+ * MemoryContentContainer, and encoding options.
+ *
+ * Orchestrates the full pipeline: Doc → render HTML → Playwright frame capture → FFmpeg encode.
+ *
+ * Usage:
+ *   import { renderDocToMp4 } from '@bendyline/squisq-cli/api';
+ *
+ *   await renderDocToMp4(doc, container, {
+ *     outputPath: '/tmp/output.mp4',
+ *     fps: 30,
+ *     quality: 'normal',
+ *     orientation: 'landscape',
+ *   });
+ */
+import type { Doc } from '@bendyline/squisq/schemas';
+import type { MemoryContentContainer } from '@bendyline/squisq/storage';
+import type { VideoQuality, VideoOrientation } from '@bendyline/squisq-video';
+export type { VideoQuality, VideoOrientation } from '@bendyline/squisq-video';
+export { MemoryContentContainer } from '@bendyline/squisq/storage';
+export { readInput } from './util/readInput.js';
+export type { ReadInputResult } from './util/readInput.js';
+/** Options for renderDocToMp4. */
+export interface RenderDocToMp4Options {
+    /** Output file path for the MP4. */
+    outputPath: string;
+    /** Frames per second (default: 30). */
+    fps?: number;
+    /** Encoding quality preset (default: 'normal'). */
+    quality?: VideoQuality;
+    /** Video orientation (default: 'landscape'). */
+    orientation?: VideoOrientation;
+    /** Override video width in pixels. */
+    width?: number;
+    /** Override video height in pixels. */
+    height?: number;
+    /** Caption style to bake into the video (default: none). */
+    captionStyle?: 'standard' | 'social';
+    /** Seconds of cover-slide pre-roll before the story starts (default: 0). */
+    coverPreRoll?: number;
+    /**
+     * Progress callback. Called with a phase name and 0-100 percentage.
+     */
+    onProgress?: (phase: string, percent: number) => void;
+}
+/** Result returned by renderDocToMp4. */
+export interface RenderDocToMp4Result {
+    /** Duration of the rendered video in seconds (including pre-roll). */
+    duration: number;
+    /** Number of frames captured. */
+    frameCount: number;
+    /** Output file path. */
+    outputPath: string;
+}
+/**
+ * Render a Doc + media container to an MP4 video file.
+ *
+ * The container should contain audio and image files referenced by the Doc's
+ * audio.segments[].src and block image paths. Files are embedded as base64
+ * data URIs in a self-contained render HTML page.
+ *
+ * Requires:
+ * - Playwright (chromium) — for headless frame capture
+ * - FFmpeg — for video encoding (must be on PATH)
+ *
+ * @param doc - The Doc structure to render
+ * @param container - MemoryContentContainer with audio/image files
+ * @param options - Rendering and encoding options
+ * @returns Result with duration and frame count
+ */
+export declare function renderDocToMp4(doc: Doc, container: MemoryContentContainer, options: RenderDocToMp4Options): Promise<RenderDocToMp4Result>;
+/** A thumbnail size specification. */
+export interface ThumbnailSpec {
+    /** Label for the thumbnail (used in filename: `{slug}-{width}x{height}.jpg`). */
+    name: string;
+    /** Output width in pixels. */
+    width: number;
+    /** Output height in pixels. */
+    height: number;
+    /** FFmpeg video filter string (e.g., 'scale=1280:720'). */
+    filter: string;
+}
+/** Options for extractThumbnails. */
+export interface ExtractThumbnailsOptions {
+    /** Path to the source MP4 video. */
+    videoPath: string;
+    /** Directory to write thumbnails into. */
+    outputDir: string;
+    /** Base slug for filenames (produces `{slug}-{width}x{height}.jpg`). */
+    slug: string;
+    /** Thumbnail sizes to generate. */
+    sizes: ThumbnailSpec[];
+    /** Overwrite existing thumbnails (default: false). */
+    force?: boolean;
+}
+/**
+ * Extract thumbnail images from the first frame of an MP4 video.
+ * Produces JPEG files at each specified size using FFmpeg video filters.
+ */
+export declare function extractThumbnails(options: ExtractThumbnailsOptions): Promise<void>;
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,2BAA2B,CAAC;AACrD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACxE,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAM9E,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC9E,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,kCAAkC;AAClC,MAAM,WAAW,qBAAqB;IACpC,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAC;IAEnB,uCAAuC;IACvC,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,mDAAmD;IACnD,OAAO,CAAC,EAAE,YAAY,CAAC;IAEvB,gDAAgD;IAChD,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAE/B,sCAAsC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,uCAAuC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,4DAA4D;IAC5D,YAAY,CAAC,EAAE,UAAU,GAAG,QAAQ,CAAC;IAErC,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACvD;AAED,yCAAyC;AACzC,MAAM,WAAW,oBAAoB;IACnC,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IAEjB,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;IAEnB,wBAAwB;IACxB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,GAAG,EACR,SAAS,EAAE,sBAAsB,EACjC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,CAAC,CA8L/B;AAmID,sCAAsC;AACtC,MAAM,WAAW,aAAa;IAC5B,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,qCAAqC;AACrC,MAAM,WAAW,wBAAwB;IACvC,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,sDAAsD;IACtD,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiCxF"}