@bestagentkits/render 0.1.0

package/dist/spec/bounds.js

@@ -0,0 +1,144 @@
+/**
+ * Input bounds.
+ *
+ * Bounds are checked before schema validation so an absurd document fails fast
+ * and cheaply. Every limit is application-level and deliberately far below any
+ * platform limit, because the same code runs in a CLI, in a library caller, and
+ * inside a worker with a bounded memory budget and a request-size ceiling.
+ */
+import { pathIndex, pathKey } from '../diagnostics.js';
+import { isPlainObject } from '../json.js';
+export const LIMITS = {
+    /** Nesting depth of the raw document, root included. */
+    maxDepth: 24,
+    /** Entries in any `blocks` array, and total authored blocks. */
+    maxBlocks: 200,
+    /** Objects in the document, anywhere (props objects and list items included). */
+    maxNodes: 20_000,
+    /** Serialized size of the whole document. */
+    maxSerializedBytes: 1_000_000,
+    /** Items in any single list. */
+    maxListItems: 200,
+    /** Keys in an open-keyed map such as `state`. */
+    maxMapKeys: 200,
+    /** Length of a single-line string. */
+    maxStringLength: 2_000,
+    /** Length of multiline text. */
+    maxTextLength: 50_000,
+};
+function walk(value, path, depth, state) {
+    if (depth > state.depth)
+        state.depth = depth;
+    if (depth > LIMITS.maxDepth && !state.overflowed.depth) {
+        state.overflowed.depth = true;
+        state.bag.add({
+            code: 'SPEC_BOUNDS_ERROR',
+            path,
+            message: `document nests ${depth} levels deep, limit is ${LIMITS.maxDepth}`,
+        });
+        return;
+    }
+    if (typeof value === 'string') {
+        if (value.length > state.longestString)
+            state.longestString = value.length;
+        return;
+    }
+    if (value === null || typeof value !== 'object')
+        return;
+    if (Array.isArray(value)) {
+        if (value.length > state.largestList)
+            state.largestList = value.length;
+        if (value.length > LIMITS.maxListItems) {
+            state.bag.add({
+                code: 'SPEC_BOUNDS_ERROR',
+                path,
+                message: `list has ${value.length} items, limit is ${LIMITS.maxListItems}`,
+            });
+        }
+        for (let index = 0; index < value.length; index += 1) {
+            walk(value[index], pathIndex(path, index), depth + 1, state);
+        }
+        return;
+    }
+    if (!isPlainObject(value))
+        return;
+    state.nodes += 1;
+    if (state.nodes > LIMITS.maxNodes && !state.overflowed.nodes) {
+        state.overflowed.nodes = true;
+        state.bag.add({
+            code: 'SPEC_BOUNDS_ERROR',
+            path,
+            message: `document has more than ${LIMITS.maxNodes} objects`,
+        });
+        return;
+    }
+    for (const [key, child] of Object.entries(value)) {
+        const childPath = pathKey(path, key);
+        if (key === 'blocks' && Array.isArray(child)) {
+            state.blocks += child.length;
+            if (state.blocks > LIMITS.maxBlocks && !state.overflowed.blocks) {
+                state.overflowed.blocks = true;
+                state.bag.add({
+                    code: 'SPEC_BOUNDS_ERROR',
+                    path: childPath,
+                    message: `document declares more than ${LIMITS.maxBlocks} blocks`,
+                });
+            }
+            if (child.length > LIMITS.maxBlocks) {
+                state.bag.add({
+                    code: 'SPEC_BOUNDS_ERROR',
+                    path: childPath,
+                    message: `blocks array has ${child.length} entries, limit is ${LIMITS.maxBlocks}`,
+                });
+            }
+        }
+        walk(child, childPath, depth + 1, state);
+    }
+}
+/**
+ * Measure a raw document and report every exceeded bound.
+ *
+ * The walk is bounded even when the input is not: exceeding a limit stops
+ * descending at that branch instead of continuing to allocate diagnostics.
+ */
+export function checkBounds(value, bag) {
+    const state = {
+        blocks: 0,
+        nodes: 0,
+        depth: 0,
+        bytes: 0,
+        longestString: 0,
+        largestList: 0,
+        bag,
+        overflowed: { depth: false, blocks: false, nodes: false },
+    };
+    let serialized = '';
+    try {
+        serialized = JSON.stringify(value) ?? '';
+    }
+    catch {
+        bag.add({
+            code: 'SPEC_BOUNDS_ERROR',
+            path: '$',
+            message: 'document is not JSON-serializable',
+        });
+    }
+    state.bytes = serialized.length;
+    if (state.bytes > LIMITS.maxSerializedBytes) {
+        bag.add({
+            code: 'SPEC_BOUNDS_ERROR',
+            path: '$',
+            message: `document is ${state.bytes} bytes serialized, limit is ${LIMITS.maxSerializedBytes}`,
+        });
+    }
+    walk(value, '$', 1, state);
+    return {
+        blocks: state.blocks,
+        nodes: state.nodes,
+        depth: state.depth,
+        bytes: state.bytes,
+        longestString: state.longestString,
+        largestList: state.largestList,
+    };
+}
+//# sourceMappingURL=bounds.js.map

package/dist/spec/bounds.js.map

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

package/dist/spec/forbidden.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Forbidden-key scan.
+ *
+ * Two independent things must be true for the trust boundary to hold: an
+ * author must not be able to smuggle executable or presentational-script
+ * content into a spec through a property name, and a typo must not silently
+ * become a no-op. This scan runs before schema validation so the failure is
+ * reported as a policy violation with the exact path, not as an
+ * unknown-property error that a reader might "fix" by adding the key to a
+ * schema.
+ */
+import { type DiagnosticBag } from '../diagnostics.js';
+/**
+ * Keys that must never appear anywhere in a Page Spec.
+ *
+ * `style` is included deliberately: a spec cannot carry CSS, and a theme is
+ * typed token data rather than a stylesheet escape hatch.
+ */
+export declare const FORBIDDEN_KEYS: readonly string[];
+/**
+ * Walk the raw document and report every forbidden key.
+ *
+ * `elements` is a permitted key name: HTML template content lives in compiler
+ * code, never in a spec.
+ */
+export declare function scanForbiddenKeys(value: unknown, bag: DiagnosticBag): void;
+//# sourceMappingURL=forbidden.d.ts.map

package/dist/spec/forbidden.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forbidden.d.ts","sourceRoot":"","sources":["../../src/spec/forbidden.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,KAAK,aAAa,EAAsB,MAAM,mBAAmB,CAAC;AAG3E;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,MAAM,EAqB3C,CAAC;AAeF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,aAAa,GAAG,IAAI,CAgC1E"}

package/dist/spec/forbidden.js

@@ -0,0 +1,91 @@
+/**
+ * Forbidden-key scan.
+ *
+ * Two independent things must be true for the trust boundary to hold: an
+ * author must not be able to smuggle executable or presentational-script
+ * content into a spec through a property name, and a typo must not silently
+ * become a no-op. This scan runs before schema validation so the failure is
+ * reported as a policy violation with the exact path, not as an
+ * unknown-property error that a reader might "fix" by adding the key to a
+ * schema.
+ */
+import { pathIndex, pathKey } from '../diagnostics.js';
+import { isPlainObject } from '../json.js';
+/**
+ * Keys that must never appear anywhere in a Page Spec.
+ *
+ * `style` is included deliberately: a spec cannot carry CSS, and a theme is
+ * typed token data rather than a stylesheet escape hatch.
+ */
+export const FORBIDDEN_KEYS = [
+    'html',
+    'rawhtml',
+    'innerhtml',
+    'outerhtml',
+    'srcdoc',
+    'css',
+    'stylesheet',
+    'style',
+    'script',
+    'javascript',
+    'js',
+    'eval',
+    'expression',
+    'handler',
+    'iframe',
+    'embed',
+    'object',
+    'formaction',
+    'dangerouslysetinnerhtml',
+    'template',
+];
+/** Snake-case and kebab-case event-handler attributes. */
+const HANDLER_KEY = /^(onclick|onchange|oninput|onsubmit|onload|onerror|onfocus|onblur|onkeydown|onkeyup|onkeypress|onmouseover|onmouseout|onmousedown|onmouseup|ondblclick|oncontextmenu|onscroll|onwheel|ontoggle|onanimationstart|ontransitionend|onpointerdown|onpointerup)$/i;
+/** Camel-case handler properties (`onClick`, `onError`, ...). `on` itself is allowed. */
+const CAMEL_HANDLER_KEY = /^on[A-Z]/;
+function isForbiddenKey(key) {
+    if (FORBIDDEN_KEYS.includes(key.toLowerCase()))
+        return true;
+    if (key === 'on')
+        return false;
+    return HANDLER_KEY.test(key) || CAMEL_HANDLER_KEY.test(key);
+}
+/**
+ * Walk the raw document and report every forbidden key.
+ *
+ * `elements` is a permitted key name: HTML template content lives in compiler
+ * code, never in a spec.
+ */
+export function scanForbiddenKeys(value, bag) {
+    const seen = new Set();
+    const visit = (node, path) => {
+        if (node === null || typeof node !== 'object')
+            return;
+        if (seen.has(node))
+            return;
+        seen.add(node);
+        if (Array.isArray(node)) {
+            for (let index = 0; index < node.length; index += 1) {
+                visit(node[index], pathIndex(path, index));
+            }
+            return;
+        }
+        if (!isPlainObject(node))
+            return;
+        for (const [key, child] of Object.entries(node)) {
+            const childPath = pathKey(path, key);
+            if (isForbiddenKey(key)) {
+                bag.add({
+                    code: 'POLICY_VIOLATION',
+                    path: childPath,
+                    message: `"${key}" is not accepted in a Page Spec: presentation and behavior belong to the compiler`,
+                    details: { key },
+                });
+                continue;
+            }
+            visit(child, childPath);
+        }
+    };
+    visit(value, '$');
+}
+//# sourceMappingURL=forbidden.js.map

package/dist/spec/forbidden.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forbidden.js","sourceRoot":"","sources":["../../src/spec/forbidden.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAsB,SAAS,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAsB;IAC/C,MAAM;IACN,SAAS;IACT,WAAW;IACX,WAAW;IACX,QAAQ;IACR,KAAK;IACL,YAAY;IACZ,OAAO;IACP,QAAQ;IACR,YAAY;IACZ,IAAI;IACJ,MAAM;IACN,YAAY;IACZ,SAAS;IACT,QAAQ;IACR,OAAO;IACP,QAAQ;IACR,YAAY;IACZ,yBAAyB;IACzB,UAAU;CACX,CAAC;AAEF,0DAA0D;AAC1D,MAAM,WAAW,GACf,8PAA8P,CAAC;AAEjQ,yFAAyF;AACzF,MAAM,iBAAiB,GAAG,UAAU,CAAC;AAErC,SAAS,cAAc,CAAC,GAAW;IACjC,IAAI,cAAc,CAAC,QAAQ,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5D,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC/B,OAAO,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc,EAAE,GAAkB;IAClE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAE/B,MAAM,KAAK,GAAG,CAAC,IAAa,EAAE,IAAY,EAAQ,EAAE;QAClD,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,OAAO;QACtD,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,OAAO;QAC3B,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAEf,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;gBACpD,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;YAC7C,CAAC;YACD,OAAO;QACT,CAAC;QACD,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC;YAAE,OAAO;QAEjC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YAChD,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YACrC,IAAI,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC;gBACxB,GAAG,CAAC,GAAG,CAAC;oBACN,IAAI,EAAE,kBAAkB;oBACxB,IAAI,EAAE,SAAS;oBACf,OAAO,EAAE,IAAI,GAAG,oFAAoF;oBACpG,OAAO,EAAE,EAAE,GAAG,EAAE;iBACjB,CAAC,CAAC;gBACH,SAAS;YACX,CAAC;YACD,KAAK,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC,CAAC;IAEF,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AACpB,CAAC"}

package/dist/spec/migrate.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Schema versioning and migrations.
+ *
+ * A Page Spec declares its own `version`, independent of the package version.
+ * Older supported versions are upgraded in memory before validation, so a
+ * document that was valid when it was written keeps working. Removing a
+ * supported version is a major release; see `docs/release-policy.md`.
+ */
+import type { DiagnosticBag } from '../diagnostics.js';
+export declare const CURRENT_SPEC_VERSION = 1;
+export interface Migration {
+    from: number;
+    to: number;
+    description: string;
+    apply(document: Record<string, unknown>): Record<string, unknown>;
+}
+export declare const MIGRATIONS: readonly Migration[];
+export declare function supportedVersions(): number[];
+/** The declared version, or 0 for the pre-versioning shape, or undefined. */
+export declare function detectSpecVersion(document: unknown): number | undefined;
+export interface MigrationResult {
+    document: Record<string, unknown>;
+    /** Version the document was written in, before any migration. */
+    originalVersion: number;
+    applied: string[];
+}
+/**
+ * Detect, validate, and apply migrations. Returns the document in the current
+ * schema version. Reports diagnostics instead of throwing so `validate()` can
+ * surface every problem at once.
+ */
+export declare function migrateSpec(document: unknown, bag: DiagnosticBag): MigrationResult | undefined;
+//# sourceMappingURL=migrate.d.ts.map

package/dist/spec/migrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/spec/migrate.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAIvD,eAAO,MAAM,oBAAoB,IAAsB,CAAC;AAExD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnE;AAwBD,eAAO,MAAM,UAAU,EAAE,SAAS,SAAS,EAAqB,CAAC;AAEjE,wBAAgB,iBAAiB,IAAI,MAAM,EAAE,CAE5C;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAQvE;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,iEAAiE;IACjE,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,aAAa,GAAG,eAAe,GAAG,SAAS,CA8D9F"}

package/dist/spec/migrate.js

@@ -0,0 +1,113 @@
+/**
+ * Schema versioning and migrations.
+ *
+ * A Page Spec declares its own `version`, independent of the package version.
+ * Older supported versions are upgraded in memory before validation, so a
+ * document that was valid when it was written keeps working. Removing a
+ * supported version is a major release; see `docs/release-policy.md`.
+ */
+import { isPlainObject } from '../json.js';
+import { SPEC_SCHEMA_VERSION } from '../registry/registry.js';
+export const CURRENT_SPEC_VERSION = SPEC_SCHEMA_VERSION;
+/**
+ * Version 0 is the pre-versioning authoring shape: a bare `blocks` array (or a
+ * document whose only meaningful key is `blocks`). The migration adds the
+ * envelope so v1 validation and normalization have one shape to handle.
+ */
+const VERSION_0_TO_1 = {
+    from: 0,
+    to: 1,
+    description: 'Wrap a bare block document in the v1 envelope: adds version, meta, theme, and policy defaults.',
+    apply(document) {
+        const blocks = Array.isArray(document) ? document : (document.blocks ?? []);
+        return {
+            version: 1,
+            meta: { title: 'Untitled page', locale: 'en' },
+            theme: { preset: 'editorial' },
+            policy: { network: 'deny' },
+            blocks,
+        };
+    },
+};
+export const MIGRATIONS = [VERSION_0_TO_1];
+export function supportedVersions() {
+    return [0, CURRENT_SPEC_VERSION];
+}
+/** The declared version, or 0 for the pre-versioning shape, or undefined. */
+export function detectSpecVersion(document) {
+    if (Array.isArray(document))
+        return 0;
+    if (!isPlainObject(document))
+        return undefined;
+    const declared = document.version;
+    if (typeof declared === 'number')
+        return declared;
+    if (declared !== undefined)
+        return Number.NaN;
+    if (Array.isArray(document.blocks))
+        return 0;
+    return undefined;
+}
+/**
+ * Detect, validate, and apply migrations. Returns the document in the current
+ * schema version. Reports diagnostics instead of throwing so `validate()` can
+ * surface every problem at once.
+ */
+export function migrateSpec(document, bag) {
+    if (!Array.isArray(document) && !isPlainObject(document)) {
+        bag.add({
+            code: 'SPEC_VALIDATION_ERROR',
+            path: '$',
+            message: 'expected a Page Spec object or a block array',
+        });
+        return undefined;
+    }
+    const detected = detectSpecVersion(document);
+    if (detected === undefined || Number.isNaN(detected)) {
+        bag.add({
+            code: 'SPEC_VALIDATION_ERROR',
+            path: '$.version',
+            message: `"version" must be a number; supported versions are ${supportedVersions().join(', ')}`,
+            details: { supported: supportedVersions() },
+        });
+        return undefined;
+    }
+    if (!Number.isInteger(detected) || detected < 0) {
+        bag.add({
+            code: 'SPEC_VALIDATION_ERROR',
+            path: '$.version',
+            message: `"${String(detected)}" is not a supported schema version`,
+            details: { supported: supportedVersions() },
+        });
+        return undefined;
+    }
+    if (detected > CURRENT_SPEC_VERSION) {
+        bag.add({
+            code: 'SPEC_VALIDATION_ERROR',
+            path: '$.version',
+            message: `schema version ${detected} is newer than this compiler supports (${CURRENT_SPEC_VERSION})`,
+            details: { supported: supportedVersions(), documentVersion: detected },
+        });
+        return undefined;
+    }
+    let current = Array.isArray(document) ? { blocks: [...document] } : { ...document };
+    const applied = [];
+    let version = detected;
+    while (version < CURRENT_SPEC_VERSION) {
+        const migration = MIGRATIONS.find((candidate) => candidate.from === version);
+        if (migration === undefined) {
+            bag.add({
+                code: 'SPEC_VALIDATION_ERROR',
+                path: '$.version',
+                message: `no migration path from schema version ${version}`,
+                details: { supported: supportedVersions() },
+            });
+            return undefined;
+        }
+        current = migration.apply(current);
+        applied.push(`v${migration.from}->v${migration.to}`);
+        version = migration.to;
+    }
+    return { document: current, originalVersion: detected, applied };
+}
+//# sourceMappingURL=migrate.js.map

package/dist/spec/migrate.js.map

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

package/dist/spec/normalize.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Normalizer: nested authoring Page Spec -> flat internal IR.
+ *
+ * The author-facing shape is optimized for authoring (nested, tolerant of
+ * omission, semantic). The IR is optimized for the compiler (flat, ordered,
+ * every node resolved). This module owns the crossing between them, including
+ * stable node IDs, slot wiring, and the cross-field checks that a per-prop
+ * schema cannot express.
+ */
+import { type Diagnostic } from '../diagnostics.js';
+import type { IrDocument } from '../ir.js';
+import { type BoundsReport } from './bounds.js';
+import { type ParseOptions } from './parse.js';
+export interface NormalizeResult {
+    ir: IrDocument;
+    diagnostics: Diagnostic[];
+    bounds: BoundsReport;
+}
+export declare const NETWORK_CAPABILITIES: readonly ["media", "fonts", "images"];
+/** Build the IR without throwing: diagnostics are returned, not raised. */
+export declare function normalizeSpec(input: unknown, options?: ParseOptions): NormalizeResult;
+/**
+ * Normalize or throw.
+ *
+ * The thrown error carries the first error's code and path, and lists every
+ * diagnostic in `details.diagnostics` so a caller can render a full report.
+ */
+export declare function normalize(input: unknown, options?: ParseOptions): IrDocument;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/spec/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../src/spec/normalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,KAAK,UAAU,EAAqC,MAAM,mBAAmB,CAAC;AAGvF,OAAO,KAAK,EAAE,UAAU,EAAmB,MAAM,UAAU,CAAC;AAO5D,OAAO,EAAE,KAAK,YAAY,EAAe,MAAM,aAAa,CAAC;AAG7D,OAAO,EAAE,KAAK,YAAY,EAAa,MAAM,YAAY,CAAC;AAG1D,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,UAAU,CAAC;IACf,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,MAAM,EAAE,YAAY,CAAC;CACtB;AAKD,eAAO,MAAM,oBAAoB,uCAAwC,CAAC;AAikB1E,2EAA2E;AAC3E,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,YAAiB,GAAG,eAAe,CA+EzF;AAqBD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,YAAiB,GAAG,UAAU,CAchF"}