@moldable-ai/ui 0.2.21 → 0.2.24

package/dist/lib/host-file-dialog.js

@@ -0,0 +1,221 @@
+import { useCallback, useEffect, useState } from 'react';
+import { HostServiceRequestError, isHostServiceAvailable, requestHostService, } from './host-services.js';
+const HOST_CONTEXT_CHANGE_EVENT = 'moldable:host-context-change';
+const FILE_DIALOG_SERVICE_NAME = 'fileDialog';
+const MAX_TEXT_LENGTH = 512;
+const MAX_DEFAULT_NAME_LENGTH = 255;
+const MAX_FILTERS = 32;
+const MAX_FILTER_NAME_LENGTH = 128;
+const MAX_EXTENSIONS_PER_FILTER = 64;
+const MAX_EXTENSION_LENGTH = 64;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function assertOnlyKeys(value, allowed, label) {
+    if (!Object.keys(value).every((key) => allowed.has(key))) {
+        throw new TypeError(`${label} contain an unknown property.`);
+    }
+}
+function validateOptionalText(label, value) {
+    if (value !== undefined &&
+        (typeof value !== 'string' ||
+            value.trim().length === 0 ||
+            value.length > MAX_TEXT_LENGTH ||
+            value.includes('\0'))) {
+        throw new TypeError(`${label} must contain 1–${MAX_TEXT_LENGTH} characters.`);
+    }
+}
+function validateDefaultLocation(value) {
+    if (value !== undefined &&
+        value !== 'documents' &&
+        value !== 'downloads' &&
+        value !== 'desktop' &&
+        value !== 'home' &&
+        value !== 'appData') {
+        throw new TypeError('File-dialog defaultLocation is not supported.');
+    }
+}
+function validateFilters(filters) {
+    if (filters === undefined)
+        return;
+    if (!Array.isArray(filters) || filters.length > MAX_FILTERS) {
+        throw new TypeError(`File dialogs support at most ${MAX_FILTERS} filters.`);
+    }
+    for (const filter of filters) {
+        if (!isRecord(filter)) {
+            throw new TypeError('File-dialog filters must be objects.');
+        }
+        assertOnlyKeys(filter, new Set(['name', 'extensions']), 'File-dialog filters');
+        if (typeof filter.name !== 'string' ||
+            filter.name.trim().length === 0 ||
+            filter.name.length > MAX_FILTER_NAME_LENGTH ||
+            filter.name.includes('\0') ||
+            !Array.isArray(filter.extensions) ||
+            filter.extensions.length === 0 ||
+            filter.extensions.length > MAX_EXTENSIONS_PER_FILTER) {
+            throw new TypeError('Each file-dialog filter requires a bounded name and extension list.');
+        }
+        if (!filter.extensions.every((extension) => typeof extension === 'string' &&
+            extension.length > 0 &&
+            extension.length <= MAX_EXTENSION_LENGTH &&
+            !extension.startsWith('.') &&
+            !/[\s/\\:*\0]/u.test(extension))) {
+            throw new TypeError('File-dialog extensions must omit dots, wildcards, whitespace, and path separators.');
+        }
+    }
+}
+const COMMON_KEYS = [
+    'title',
+    'buttonLabel',
+    'filters',
+    'defaultLocation',
+    'signal',
+    'timeoutMs',
+];
+const OPEN_KEYS = new Set([...COMMON_KEYS, 'properties']);
+const SAVE_KEYS = new Set([...COMMON_KEYS, 'defaultName', 'createDirectories']);
+const OPEN_PROPERTY_KEYS = new Set([
+    'multiple',
+    'directories',
+    'createDirectories',
+    'showHidden',
+]);
+function validateCommonOptions(options, keys) {
+    assertOnlyKeys(options, keys, 'File-dialog options');
+    validateOptionalText('File-dialog title', options.title);
+    validateOptionalText('File-dialog buttonLabel', options.buttonLabel);
+    validateDefaultLocation(options.defaultLocation);
+    validateFilters(options.filters);
+}
+function validateOpenOptions(options) {
+    if (!isRecord(options)) {
+        throw new TypeError('Open file-dialog options must be an object.');
+    }
+    validateCommonOptions(options, OPEN_KEYS);
+    if (options.properties === undefined)
+        return;
+    if (!isRecord(options.properties)) {
+        throw new TypeError('Open file-dialog properties must be an object.');
+    }
+    assertOnlyKeys(options.properties, OPEN_PROPERTY_KEYS, 'Open file-dialog properties');
+    if (!Object.values(options.properties).every((value) => typeof value === 'boolean')) {
+        throw new TypeError('Open file-dialog properties must be booleans.');
+    }
+}
+function validateSaveOptions(options) {
+    if (!isRecord(options)) {
+        throw new TypeError('Save file-dialog options must be an object.');
+    }
+    validateCommonOptions(options, SAVE_KEYS);
+    if (options.defaultName !== undefined &&
+        (typeof options.defaultName !== 'string' ||
+            options.defaultName.trim().length === 0 ||
+            options.defaultName.length > MAX_DEFAULT_NAME_LENGTH ||
+            /[/\\\0]/u.test(options.defaultName))) {
+        throw new TypeError(`Save-dialog defaultName must be a filename of 1–${MAX_DEFAULT_NAME_LENGTH} characters.`);
+    }
+    if (options.createDirectories !== undefined &&
+        typeof options.createDirectories !== 'boolean') {
+        throw new TypeError('Save-dialog createDirectories must be a boolean.');
+    }
+}
+function requestOptions(options) {
+    return {
+        signal: options.signal,
+        timeoutMs: options.timeoutMs,
+    };
+}
+function abortError() {
+    return new DOMException('The file-dialog request was aborted.', 'AbortError');
+}
+function isPath(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+export async function openFileDialogWithHost(options = {}) {
+    validateOpenOptions(options);
+    if (options.signal?.aborted)
+        throw abortError();
+    if (!isHostServiceAvailable(FILE_DIALOG_SERVICE_NAME)) {
+        return { status: 'fallback' };
+    }
+    try {
+        const result = await requestHostService(FILE_DIALOG_SERVICE_NAME, {
+            mode: 'open',
+            ...(options.title === undefined ? {} : { title: options.title }),
+            ...(options.buttonLabel === undefined
+                ? {}
+                : { buttonLabel: options.buttonLabel }),
+            ...(options.filters === undefined ? {} : { filters: options.filters }),
+            ...(options.defaultLocation === undefined
+                ? {}
+                : { defaultLocation: options.defaultLocation }),
+            ...(options.properties === undefined
+                ? {}
+                : { properties: options.properties }),
+        }, requestOptions(options));
+        if (!isRecord(result) ||
+            !Array.isArray(result.paths) ||
+            result.paths.length === 0 ||
+            !result.paths.every(isPath)) {
+            throw new Error('The native open dialog returned an invalid result.');
+        }
+        return { status: 'completed', paths: result.paths };
+    }
+    catch (error) {
+        if (error instanceof HostServiceRequestError &&
+            error.status === 'cancelled') {
+            return { status: 'cancelled' };
+        }
+        throw error;
+    }
+}
+export async function saveFileDialogWithHost(options = {}) {
+    validateSaveOptions(options);
+    if (options.signal?.aborted)
+        throw abortError();
+    if (!isHostServiceAvailable(FILE_DIALOG_SERVICE_NAME)) {
+        return { status: 'fallback' };
+    }
+    try {
+        const result = await requestHostService(FILE_DIALOG_SERVICE_NAME, {
+            mode: 'save',
+            ...(options.title === undefined ? {} : { title: options.title }),
+            ...(options.buttonLabel === undefined
+                ? {}
+                : { buttonLabel: options.buttonLabel }),
+            ...(options.filters === undefined ? {} : { filters: options.filters }),
+            ...(options.defaultLocation === undefined
+                ? {}
+                : { defaultLocation: options.defaultLocation }),
+            ...(options.defaultName === undefined
+                ? {}
+                : { defaultName: options.defaultName }),
+            ...(options.createDirectories === undefined
+                ? {}
+                : { createDirectories: options.createDirectories }),
+        }, requestOptions(options));
+        if (!isRecord(result) || !isPath(result.path)) {
+            throw new Error('The native save dialog returned an invalid result.');
+        }
+        return { status: 'completed', path: result.path };
+    }
+    catch (error) {
+        if (error instanceof HostServiceRequestError &&
+            error.status === 'cancelled') {
+            return { status: 'cancelled' };
+        }
+        throw error;
+    }
+}
+export function useHostFileDialog() {
+    const [available, setAvailable] = useState(() => isHostServiceAvailable(FILE_DIALOG_SERVICE_NAME));
+    useEffect(() => {
+        const update = () => setAvailable(isHostServiceAvailable(FILE_DIALOG_SERVICE_NAME));
+        update();
+        window.addEventListener(HOST_CONTEXT_CHANGE_EVENT, update);
+        return () => window.removeEventListener(HOST_CONTEXT_CHANGE_EVENT, update);
+    }, []);
+    const open = useCallback((options) => openFileDialogWithHost(options), []);
+    const save = useCallback((options) => saveFileDialogWithHost(options), []);
+    return { available, open, save };
+}

package/dist/lib/host-native-menu.d.ts

@@ -0,0 +1,116 @@
+import type { LucideIcon } from 'lucide-react';
+import { type HostServiceRequestOptions } from './host-services.js';
+export declare const HOST_NATIVE_MENU_MAX_DEPTH = 3;
+export declare const HOST_NATIVE_MENU_MAX_ITEMS = 200;
+export declare const HOST_NATIVE_MENU_MAX_TITLE_LENGTH = 256;
+export declare const HOST_NATIVE_MENU_MAX_SUBLABEL_LENGTH = 512;
+export type NativeMenuItemKind = 'normal' | 'separator' | 'checkbox' | 'radio';
+export interface NativeMenuShortcut {
+    key: string;
+    modifiers?: Array<'cmd' | 'shift' | 'alt' | 'ctrl'>;
+}
+interface MenuItemState {
+    enabled?: boolean;
+    shortcut?: NativeMenuShortcut;
+    destructive?: boolean;
+}
+interface NativeMenuItemBase extends MenuItemState {
+    sublabel?: string;
+}
+export type NativeMenuItem = (NativeMenuItemBase & {
+    id: string;
+    kind?: 'normal';
+    title: string;
+    checked?: never;
+    submenu?: NativeMenuItem[];
+}) | (NativeMenuItemBase & {
+    id?: string;
+    kind: 'separator';
+    title?: string;
+    checked?: never;
+    submenu?: never;
+}) | (NativeMenuItemBase & {
+    id: string;
+    kind: 'checkbox';
+    title: string;
+    checked?: boolean | 'mixed';
+    submenu?: never;
+}) | (NativeMenuItemBase & {
+    id: string;
+    kind: 'radio';
+    title: string;
+    checked?: boolean;
+    submenu?: never;
+});
+interface RendererMenuItemBase extends MenuItemState {
+    id: string;
+    label: string;
+    /** Rendered only by the portable menu. */
+    icon?: LucideIcon;
+    /** Reserved for a future native-symbol allowlist. */
+    sfSymbol?: string;
+}
+/**
+ * A renderer-facing declarative menu item shared by portable and native menu
+ * paths. Despite the pluralized public name, roots accept `MenuItems[]`.
+ */
+export type MenuItems = (RendererMenuItemBase & {
+    kind?: 'normal';
+    checked?: never;
+    submenu?: MenuItems[];
+}) | {
+    id: string;
+    kind: 'separator';
+    label?: never;
+    icon?: never;
+    sfSymbol?: never;
+    enabled?: never;
+    checked?: never;
+    shortcut?: never;
+    destructive?: never;
+    submenu?: never;
+} | (RendererMenuItemBase & {
+    kind: 'checkbox';
+    checked?: boolean | 'mixed';
+    submenu?: never;
+}) | (RendererMenuItemBase & {
+    kind: 'radio';
+    checked?: boolean;
+    submenu?: never;
+});
+export interface HostNativeMenuAnchorRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface HostNativeMenuPoint {
+    x: number;
+    y: number;
+}
+export interface HostNativeMenuOptions extends HostServiceRequestOptions {
+    anchor?: Element | HostNativeMenuAnchorRect;
+    position?: HostNativeMenuPoint;
+}
+export type HostNativeMenuResult = {
+    status: 'completed';
+    selectedId: string;
+} | {
+    status: 'cancelled';
+} | {
+    status: 'fallback';
+};
+export interface HostNativeMenu {
+    available: boolean;
+    open: (items: NativeMenuItem[], options: HostNativeMenuOptions) => Promise<HostNativeMenuResult>;
+}
+/**
+ * Converts renderer menu items to the host wire model by explicit allowlist.
+ * Portable-only icons and sfSymbol metadata, plus any unexpected runtime
+ * fields, are intentionally omitted.
+ */
+export declare function toNativeMenuItems(items: MenuItems[]): NativeMenuItem[];
+export declare function openNativeMenuWithHost(items: NativeMenuItem[], options: HostNativeMenuOptions): Promise<HostNativeMenuResult>;
+export declare function useHostNativeMenu(): HostNativeMenu;
+export {};
+//# sourceMappingURL=host-native-menu.d.ts.map

package/dist/lib/host-native-menu.d.ts.map

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

package/dist/lib/host-native-menu.js

@@ -0,0 +1,242 @@
+import { useCallback, useEffect, useState } from 'react';
+import { HostServiceRequestError, isHostServiceAvailable, requestHostService, } from './host-services.js';
+const HOST_CONTEXT_CHANGE_EVENT = 'moldable:host-context-change';
+const NATIVE_MENU_SERVICE_NAME = 'nativeMenu';
+export const HOST_NATIVE_MENU_MAX_DEPTH = 3;
+export const HOST_NATIVE_MENU_MAX_ITEMS = 200;
+export const HOST_NATIVE_MENU_MAX_TITLE_LENGTH = 256;
+export const HOST_NATIVE_MENU_MAX_SUBLABEL_LENGTH = 512;
+function nativeMenuItemState(item) {
+    return {
+        ...(item.enabled !== undefined ? { enabled: item.enabled } : {}),
+        ...(item.shortcut
+            ? {
+                shortcut: {
+                    key: item.shortcut.key,
+                    ...(item.shortcut.modifiers
+                        ? { modifiers: [...item.shortcut.modifiers] }
+                        : {}),
+                },
+            }
+            : {}),
+        ...(item.destructive !== undefined
+            ? { destructive: item.destructive }
+            : {}),
+    };
+}
+/**
+ * Converts renderer menu items to the host wire model by explicit allowlist.
+ * Portable-only icons and sfSymbol metadata, plus any unexpected runtime
+ * fields, are intentionally omitted.
+ */
+export function toNativeMenuItems(items) {
+    return items.map((item) => {
+        if (item.kind === 'separator') {
+            return { id: item.id, kind: 'separator' };
+        }
+        const state = nativeMenuItemState(item);
+        if (item.kind === 'checkbox') {
+            return {
+                id: item.id,
+                kind: 'checkbox',
+                title: item.label,
+                ...state,
+                ...(item.checked !== undefined ? { checked: item.checked } : {}),
+            };
+        }
+        if (item.kind === 'radio') {
+            return {
+                id: item.id,
+                kind: 'radio',
+                title: item.label,
+                ...state,
+                ...(item.checked !== undefined ? { checked: item.checked } : {}),
+            };
+        }
+        return {
+            id: item.id,
+            title: item.label,
+            ...state,
+            ...(item.submenu ? { submenu: toNativeMenuItems(item.submenu) } : {}),
+        };
+    });
+}
+function finitePoint(value) {
+    return Number.isFinite(value.x) && Number.isFinite(value.y);
+}
+function menuAnchorRect(anchor) {
+    const rect = typeof Element !== 'undefined' && anchor instanceof Element
+        ? anchor.getBoundingClientRect()
+        : anchor;
+    if (!finitePoint(rect) ||
+        !Number.isFinite(rect.width) ||
+        !Number.isFinite(rect.height) ||
+        rect.width < 0 ||
+        rect.height < 0) {
+        throw new TypeError('Native menu anchors require a finite, non-negative rect.');
+    }
+    return {
+        x: rect.x,
+        y: rect.y,
+        width: rect.width,
+        height: rect.height,
+    };
+}
+function validateShortcut(shortcut) {
+    if (typeof shortcut.key !== 'string' || shortcut.key.length === 0) {
+        throw new TypeError('Native menu shortcuts require a non-empty key.');
+    }
+    if (shortcut.modifiers !== undefined &&
+        (!Array.isArray(shortcut.modifiers) ||
+            !shortcut.modifiers.every((modifier) => modifier === 'cmd' ||
+                modifier === 'shift' ||
+                modifier === 'alt' ||
+                modifier === 'ctrl'))) {
+        throw new TypeError('Native menu shortcuts contain an invalid modifier.');
+    }
+}
+function validateMenuItems(items) {
+    if (!Array.isArray(items) ||
+        items.length === 0 ||
+        items.length > HOST_NATIVE_MENU_MAX_ITEMS) {
+        throw new TypeError(`Native menus require 1–${HOST_NATIVE_MENU_MAX_ITEMS} total items.`);
+    }
+    const ids = new Set();
+    let totalItems = 0;
+    const visit = (values, depth) => {
+        if (depth > HOST_NATIVE_MENU_MAX_DEPTH) {
+            throw new TypeError(`Native menu depth must not exceed ${HOST_NATIVE_MENU_MAX_DEPTH}.`);
+        }
+        for (const item of values) {
+            totalItems += 1;
+            if (totalItems > HOST_NATIVE_MENU_MAX_ITEMS) {
+                throw new TypeError(`Native menus must not exceed ${HOST_NATIVE_MENU_MAX_ITEMS} total items.`);
+            }
+            if (!item || typeof item !== 'object' || Array.isArray(item)) {
+                throw new TypeError('Native menu items must be objects.');
+            }
+            const kind = item.kind ?? 'normal';
+            if (kind !== 'normal' &&
+                kind !== 'separator' &&
+                kind !== 'checkbox' &&
+                kind !== 'radio') {
+                throw new TypeError('Native menu items contain an unsupported kind.');
+            }
+            if (kind !== 'separator') {
+                if (typeof item.id !== 'string' ||
+                    item.id.trim().length === 0 ||
+                    ids.has(item.id)) {
+                    throw new TypeError('Selectable native menu items require unique, non-empty ids.');
+                }
+                ids.add(item.id);
+                if (typeof item.title !== 'string' ||
+                    item.title.length === 0 ||
+                    item.title.length > HOST_NATIVE_MENU_MAX_TITLE_LENGTH) {
+                    throw new TypeError(`Native menu item titles must contain 1–${HOST_NATIVE_MENU_MAX_TITLE_LENGTH} characters.`);
+                }
+            }
+            else {
+                if (item.id !== undefined && typeof item.id !== 'string') {
+                    throw new TypeError('Native menu separator ids must be strings when provided.');
+                }
+                if (item.title !== undefined &&
+                    (typeof item.title !== 'string' ||
+                        item.title.length > HOST_NATIVE_MENU_MAX_TITLE_LENGTH)) {
+                    throw new TypeError(`Native menu separator titles must not exceed ${HOST_NATIVE_MENU_MAX_TITLE_LENGTH} characters.`);
+                }
+            }
+            if (item.sublabel !== undefined &&
+                (typeof item.sublabel !== 'string' ||
+                    item.sublabel.length > HOST_NATIVE_MENU_MAX_SUBLABEL_LENGTH)) {
+                throw new TypeError(`Native menu sublabels must not exceed ${HOST_NATIVE_MENU_MAX_SUBLABEL_LENGTH} characters.`);
+            }
+            if (item.enabled !== undefined && typeof item.enabled !== 'boolean') {
+                throw new TypeError('Native menu enabled values must be booleans.');
+            }
+            if (item.destructive !== undefined &&
+                typeof item.destructive !== 'boolean') {
+                throw new TypeError('Native menu destructive values must be booleans.');
+            }
+            if (item.shortcut !== undefined)
+                validateShortcut(item.shortcut);
+            if (kind === 'checkbox' || kind === 'radio') {
+                if (item.checked !== undefined &&
+                    item.checked !== true &&
+                    item.checked !== false &&
+                    item.checked !== 'mixed') {
+                    throw new TypeError('Native menu checked values must be true, false, or mixed.');
+                }
+                if (kind === 'radio' && item.checked === 'mixed') {
+                    throw new TypeError('Native menu radio items do not support the mixed state.');
+                }
+            }
+            else if (item.checked !== undefined) {
+                throw new TypeError('Only checkbox and radio native menu items may be checked.');
+            }
+            if (item.submenu !== undefined) {
+                if (kind !== 'normal' || !Array.isArray(item.submenu)) {
+                    throw new TypeError('Only normal native menu items may contain submenu arrays.');
+                }
+                visit(item.submenu, depth + 1);
+            }
+        }
+    };
+    visit(items, 1);
+}
+function validatePlacement(options) {
+    const hasAnchor = options.anchor !== undefined;
+    const hasPosition = options.position !== undefined;
+    if (hasAnchor === hasPosition) {
+        throw new TypeError('Native menus require exactly one anchor or pointer position.');
+    }
+    if (options.anchor)
+        return { anchor: menuAnchorRect(options.anchor) };
+    if (!options.position || !finitePoint(options.position)) {
+        throw new TypeError('Native menu positions require finite x and y coordinates.');
+    }
+    return { position: { ...options.position } };
+}
+function abortError() {
+    return new DOMException('The native menu request was aborted.', 'AbortError');
+}
+export async function openNativeMenuWithHost(items, options) {
+    validateMenuItems(items);
+    const placement = validatePlacement(options);
+    if (options.signal?.aborted)
+        throw abortError();
+    if (!isHostServiceAvailable(NATIVE_MENU_SERVICE_NAME)) {
+        return { status: 'fallback' };
+    }
+    try {
+        const result = await requestHostService(NATIVE_MENU_SERVICE_NAME, { items, ...placement }, {
+            signal: options.signal,
+            timeoutMs: options.timeoutMs,
+        });
+        if (typeof result !== 'object' ||
+            result === null ||
+            !('selectedId' in result) ||
+            typeof result.selectedId !== 'string' ||
+            result.selectedId.length === 0) {
+            throw new Error('The native menu returned an invalid result.');
+        }
+        return { status: 'completed', selectedId: result.selectedId };
+    }
+    catch (error) {
+        if (error instanceof HostServiceRequestError &&
+            error.status === 'cancelled') {
+            return { status: 'cancelled' };
+        }
+        throw error;
+    }
+}
+export function useHostNativeMenu() {
+    const [available, setAvailable] = useState(() => isHostServiceAvailable(NATIVE_MENU_SERVICE_NAME));
+    useEffect(() => {
+        const update = () => setAvailable(isHostServiceAvailable(NATIVE_MENU_SERVICE_NAME));
+        update();
+        window.addEventListener(HOST_CONTEXT_CHANGE_EVENT, update);
+        return () => window.removeEventListener(HOST_CONTEXT_CHANGE_EVENT, update);
+    }, []);
+    const open = useCallback((items, options) => openNativeMenuWithHost(items, options), []);
+    return { available, open };
+}

package/dist/lib/host-services.d.ts

@@ -0,0 +1,13 @@
+export interface HostServiceRequestOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+export type HostServiceResponseStatus = 'completed' | 'cancelled' | 'error' | 'timeout';
+export declare class HostServiceRequestError extends Error {
+    readonly status: Exclude<HostServiceResponseStatus, 'completed'>;
+    readonly code?: string;
+    constructor(status: Exclude<HostServiceResponseStatus, 'completed'>, message: string, code?: string);
+}
+export declare function isHostServiceAvailable(name: string): boolean;
+export declare function requestHostService<TResult = unknown>(name: string, payload: unknown, options?: HostServiceRequestOptions): Promise<TResult>;
+//# sourceMappingURL=host-services.d.ts.map

package/dist/lib/host-services.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-services.d.ts","sourceRoot":"","sources":["../../src/lib/host-services.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,yBAAyB;IACxC,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,MAAM,yBAAyB,GACjC,WAAW,GACX,WAAW,GACX,OAAO,GACP,SAAS,CAAA;AAuBb,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,yBAAyB,EAAE,WAAW,CAAC,CAAA;IAChE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;gBAGpB,MAAM,EAAE,OAAO,CAAC,yBAAyB,EAAE,WAAW,CAAC,EACvD,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM;CAOhB;AA4GD,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAM5D;AAED,wBAAgB,kBAAkB,CAAC,OAAO,GAAG,OAAO,EAClD,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,OAAO,CAAC,CAiFlB"}