@deepseek-harness-tui/dsh-tui 0.12.0 → 0.13.0

package/lib/types/components/sidePanel/panelBridge.js

@@ -0,0 +1,55 @@
+/**
+ * panelBridge：ctx.tuiPanels 服务（dsh-adapter，Cordis 侧）与 useSidePanel
+ * （Chat 侧控制器）之间的小型 module-level 通道（设计文档 §18.2）。
+ *
+ * 照 jobsFocusStore 的形状刻意做成两个三行 store，而不是塞进 PanelStore
+ * （那是注册表/badge 的家）或 SidePanelRuntimeContext（useSidePanel 不该
+ * 知道插件业务）：
+ * - state：Chat 每次渲染后回写 { open, activePanelId, focus }，服务侧
+ *   close()/focus() 据此判断；
+ * - requests：服务侧 open/focus/close 的请求队列（nonce 保证同 id 重复
+ *   请求也能重新触发），useSidePanel 订阅并在自己的启用集合里裁决。
+ *
+ * hasConsumer：没有任何 Chat 挂载（无头夹具 / 侧栏永不渲染）时 open()
+ * 必须返回 false 而不是假装成功——attach/detach 由 useSidePanel 的
+ * mount effect 维护。
+ */
+const listeners = new Set();
+let consumers = 0;
+let requestSnapshot = Object.freeze({ kind: 'open', id: '', nonce: 0 });
+export const panelBridgeRequests = {
+    subscribe(listener) {
+        listeners.add(listener);
+        return () => { listeners.delete(listener); };
+    },
+    /** 服务侧入口：无 Chat 消费者时返回 false（调用方据此向插件返回 false）。 */
+    request(kind, id) {
+        if (consumers <= 0)
+            return false;
+        requestSnapshot = Object.freeze({ kind, id, nonce: requestSnapshot.nonce + 1 });
+        for (const listener of [...listeners])
+            listener(requestSnapshot);
+        return true;
+    },
+    /** useSidePanel mount/unmount 维护；带消费者才允许请求入队。 */
+    attach() { consumers += 1; },
+    detach() { consumers = Math.max(0, consumers - 1); },
+    hasConsumer() { return consumers > 0; },
+};
+let uiState = Object.freeze({ open: false, activePanelId: undefined, focus: 'chat' });
+const stateListeners = new Set();
+export const panelBridgeState = {
+    subscribe(listener) {
+        stateListeners.add(listener);
+        return () => { stateListeners.delete(listener); };
+    },
+    get() {
+        return uiState;
+    },
+    /** 只由 useSidePanel 回写。 */
+    set(next) {
+        uiState = Object.freeze(next);
+        for (const listener of [...stateListeners])
+            listener();
+    },
+};

package/lib/types/components/sidePanel/pluginPanelAdapter.d.ts

@@ -0,0 +1,22 @@
+/**
+ * PluginPanelAdapter（设计文档 §18.2/§18.5）：把插件注册的 Panel 组件
+ * 接进 PanelHost。PanelHost 看到的仍是普通 PanelDefinition.component
+ * （这里在注册时包好），插件组件拿到的是收窄后的
+ * TuiPanelProps { React, ui, host, width, height, focused, visible, mode }。
+ *
+ * - ui：照 TuiStatusViewUi 的收窄法——Box 去掉 ref/tabIndex/focus/键盘/
+ *   contextMenu（保留 click/hover/drag/onWheel），useTerminalSize 恒等于
+ *   Panel 的 width/height，useAnimationTime 是唯一合法定时源。
+ * - host：策展只读 snapshot（SidePanelRuntimeContext 的 channel/activity/
+ *   attention 的结构拷贝，不含转录正文/凭证/文件内容）+ badge/scene/toast/
+ *   storage/focus/onKey。
+ * - onKey：走 usePanelInput 分发器（v2.1 键盘契约），仅 focused 期间投递；
+ *   preventDefault() = 阻止宿主回退键（等价 handler 返回 true）。
+ * - sendToChat：本阶段授权流程（panels.chat.attach）未落地——返回 false
+ *   并 toast 一次（i18n 文案），不静默。
+ */
+import React from 'react';
+import type { PanelProps } from './types.js';
+import type { TuiPanelProps } from '../../dsh-adapter/panels.js';
+export declare function makePluginPanelComponent(panelId: string, component: React.ComponentType<TuiPanelProps>): React.ComponentType<PanelProps>;
+//# sourceMappingURL=pluginPanelAdapter.d.ts.map

package/lib/types/components/sidePanel/pluginPanelAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pluginPanelAdapter.d.ts","sourceRoot":"","sources":["../../../../src/components/sidePanel/pluginPanelAdapter.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,MAAM,OAAO,CAAA;AAOzB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAC5C,OAAO,KAAK,EAGV,aAAa,EAGd,MAAM,6BAA6B,CAAA;AAYpC,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,KAAK,CAAC,aAAa,CAAC,aAAa,CAAC,GAC5C,KAAK,CAAC,aAAa,CAAC,UAAU,CAAC,CA2HjC"}

package/lib/types/components/sidePanel/pluginPanelAdapter.js

@@ -0,0 +1,148 @@
+/**
+ * PluginPanelAdapter（设计文档 §18.2/§18.5）：把插件注册的 Panel 组件
+ * 接进 PanelHost。PanelHost 看到的仍是普通 PanelDefinition.component
+ * （这里在注册时包好），插件组件拿到的是收窄后的
+ * TuiPanelProps { React, ui, host, width, height, focused, visible, mode }。
+ *
+ * - ui：照 TuiStatusViewUi 的收窄法——Box 去掉 ref/tabIndex/focus/键盘/
+ *   contextMenu（保留 click/hover/drag/onWheel），useTerminalSize 恒等于
+ *   Panel 的 width/height，useAnimationTime 是唯一合法定时源。
+ * - host：策展只读 snapshot（SidePanelRuntimeContext 的 channel/activity/
+ *   attention 的结构拷贝，不含转录正文/凭证/文件内容）+ badge/scene/toast/
+ *   storage/focus/onKey。
+ * - onKey：走 usePanelInput 分发器（v2.1 键盘契约），仅 focused 期间投递；
+ *   preventDefault() = 阻止宿主回退键（等价 handler 返回 true）。
+ * - sendToChat：本阶段授权流程（panels.chat.attach）未落地——返回 false
+ *   并 toast 一次（i18n 文案），不静默。
+ */
+import React from 'react';
+import { Box, Text, Image, ScrollBox, useTheme, useAnimationFrame } from '../../ui.js';
+import { Divider } from '../design-system/Divider.js';
+import { t, getLang } from '../../i18n.js';
+import { SidePanelRuntimeContext } from './SidePanelRuntimeContext.js';
+import { usePanelInput } from './usePanelInput.js';
+import { panelStore } from './PanelStore.js';
+import { pluginPanelFocus, pluginPanelOpenScene, pluginPanelStorage, pluginPanelToast, } from '../../dsh-adapter/panel-runtime-registry.js';
+/** sendToChat 未授权提示每 Panel 每会话只 toast 一次。 */
+const sendToChatWarned = new Set();
+export function makePluginPanelComponent(panelId, component) {
+    function PluginPanelHost(props) {
+        const { width, height, focused, visible, mode } = props;
+        const runtimeCtx = React.useContext(SidePanelRuntimeContext);
+        // ── onKey（v2.1 分发器）：仅 focused && visible 期间投递。listener
+        // 集合在分发时读取，插件在 render 期或 effect 期注册都安全。
+        const keyListeners = React.useRef(new Set());
+        usePanelInput((input, key) => {
+            let consumed = false;
+            const event = {
+                input,
+                key,
+                preventDefault: () => { consumed = true; },
+            };
+            for (const listener of [...keyListeners.current]) {
+                try {
+                    listener(event);
+                }
+                catch {
+                    // 插件 listener 崩溃不得打断后续分发（错误面由 boundary 兜）。
+                }
+            }
+            return consumed;
+        }, { active: focused && visible });
+        // ── host API：identity 随 runtimeCtx（channel/activity/attention）
+        // 与 focused 变化而刷新；其余函数绑定 panelId。
+        const channel = runtimeCtx?.channel;
+        const activity = runtimeCtx?.activity;
+        const attention = runtimeCtx?.attention;
+        const host = React.useMemo(() => ({
+            snapshot: () => {
+                // 结构拷贝、只策展白名单字段——不含转录正文/凭证/文件内容。
+                return Object.freeze({
+                    sessionId: channel?.sessionId ?? '',
+                    cwd: channel?.cwd ?? '',
+                    lang: getLang(),
+                    working: channel?.working === true,
+                    spinnerMode: channel?.spinnerMode ?? 'idle',
+                    version: channel?.version ?? 0,
+                    goal: channel?.goal === undefined
+                        ? undefined
+                        : Object.freeze({
+                            objective: channel.goal.objective,
+                            phase: channel.goal.phase,
+                            roundsStarted: channel.goal.roundsStarted,
+                            maxGoalRounds: channel.goal.maxGoalRounds,
+                        }),
+                    todos: Object.freeze((channel?.todos ?? []).map(item => Object.freeze({
+                        content: item.content,
+                        status: item.status,
+                    }))),
+                    backgroundJobs: Object.freeze((channel?.backgroundJobs ?? []).map(job => Object.freeze({
+                        id: job.id,
+                        kind: job.kind,
+                        label: job.label,
+                        status: job.status,
+                        progress: job.progress,
+                        detail: job.detail,
+                        startedAt: job.startedAt,
+                    }))),
+                    subagents: Object.freeze((channel?.subagents ?? []).map(sub => Object.freeze({
+                        agentId: sub.agentId,
+                        description: sub.description,
+                        status: sub.status,
+                        mode: sub.mode,
+                        model: sub.model,
+                        startedAt: sub.startedAt,
+                        completedAt: sub.completedAt,
+                    }))),
+                    attention: Object.freeze({
+                        approvals: attention?.approvals ?? 0,
+                        questions: attention?.questions ?? 0,
+                    }),
+                    activity: activity === undefined ? undefined : Object.freeze({ ...activity }),
+                });
+            },
+            focused,
+            notify: (level, unread = 0) => { panelStore.setBadge(panelId, { level, unread }); },
+            clearBadge: () => { panelStore.clearBadge(panelId); },
+            sendToChat: () => {
+                if (!sendToChatWarned.has(panelId)) {
+                    sendToChatWarned.add(panelId);
+                    pluginPanelToast(panelId, t('panel-send-to-chat-denied'));
+                }
+                return false;
+            },
+            openScene: sceneId => pluginPanelOpenScene(panelId, sceneId),
+            toast: text => pluginPanelToast(panelId, text),
+            get storage() { return pluginPanelStorage(panelId); },
+            onKey: listener => {
+                keyListeners.current.add(listener);
+                return () => { keyListeners.current.delete(listener); };
+            },
+            focus: () => pluginPanelFocus(panelId),
+        }), [channel, activity, attention, focused]);
+        // ── ui kit：useTerminalSize/useAnimationTime 绑定 Panel 尺寸，其余
+        // 直接复用宿主组件（类型在 TuiPanelUi 处收窄）。
+        const ui = React.useMemo(() => ({
+            Box: Box,
+            Text: Text,
+            Image: Image,
+            ScrollBox: ScrollBox,
+            Divider: Divider,
+            useTerminalSize: () => ({ columns: width, rows: height }),
+            useAnimationTime: (intervalMs) => useAnimationFrame(intervalMs)[1],
+            useTheme: useTheme,
+        }), [width, height]);
+        return React.createElement(component, {
+            React,
+            ui,
+            host,
+            width,
+            height,
+            focused,
+            visible,
+            mode,
+        });
+    }
+    PluginPanelHost.displayName = 'PluginPanelHost(' + panelId + ')';
+    return PluginPanelHost;
+}

package/lib/types/components/sidePanel/types.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Panel 系统的核心契约（设计文档 §6.2 + v2.1 修订）。
+ *
+ * Panel 不知道自己在右侧、比例多少、终端总宽多少；只知道 width /
+ * height / focused / visible / mode。以后把侧栏改到底部，Panel 不用重写。
+ */
+import type React from 'react';
+import type { I18nKey } from '../../i18n.js';
+export type PanelMountPolicy = 
+/** 只有 active 时才挂载（插件默认——防止常驻面板烧资源）。 */
+'active'
+/** 启用即挂载，非 active 时 display:none + focused/visible=false——
+ *  状态（计时、内部路由、滚动位）保留，但不动画、不收键盘（内置
+todo/jobs/agents/companion 用）。 */
+ | 'enabled';
+export interface PanelCapabilities {
+    readonly scroll?: boolean;
+    readonly search?: boolean;
+    readonly selection?: boolean;
+    readonly zoom?: boolean;
+    readonly sendToChat?: boolean;
+    /** 有整屏对应物：PanelBar 右端出现 ⤢「全屏」按钮（点击交给宿主
+     *  openFullscreen(panelId)）。没有整屏形态的面板不声明，按钮不出现。 */
+    readonly fullscreen?: boolean;
+}
+export interface PanelProps {
+    readonly width: number;
+    readonly height: number;
+    readonly focused: boolean;
+    /** 非 active（mountPolicy=enabled 时仍挂载）或侧栏收起时 false：
+     *  组件应停掉高频刷新（useAnimationFrame 传 null），store 继续更新。 */
+    readonly visible: boolean;
+    readonly mode: 'split' | 'zoom' | 'fullscreen';
+}
+export interface PanelCompactProps {
+    readonly width: number;
+    readonly badge: PanelBadge | null;
+}
+export interface PanelDefinition {
+    /** /^[a-z][a-z0-9_-]*(:[a-z][a-z0-9_-]*)*$/；插件用 plugin:sub 命名空间。 */
+    readonly id: string;
+    /** 内置 Panel 走 i18n key；插件给字面量 title。 */
+    readonly titleKey?: I18nKey;
+    readonly title?: string;
+    /** PanelBar 胶囊里的单格图标（显示宽度必须为 1；缺省用首字母）。 */
+    readonly icon?: string;
+    readonly order?: number;
+    /** 低于此宽度时 PanelBar 照显、Host 提示「宽度不足」。 */
+    readonly minColumns?: number;
+    readonly defaultEnabled?: boolean;
+    readonly source: 'builtin' | 'plugin';
+    readonly pluginId?: string;
+    readonly mountPolicy?: PanelMountPolicy;
+    readonly capabilities?: PanelCapabilities;
+    readonly component: React.ComponentType<PanelProps>;
+    /** 可选的 1~3 行紧凑呈现（侧栏收起/窄屏时的紧凑槽，Phase 6 挂载）。 */
+    readonly compact?: {
+        readonly maxRows: 1 | 2 | 3;
+        readonly component: React.ComponentType<PanelCompactProps>;
+    };
+}
+export type PanelOwner = 'builtin' | {
+    readonly pluginId: string;
+    readonly activation?: unknown;
+};
+export interface PanelBadge {
+    readonly level: 'info' | 'warning' | 'error';
+    readonly unread: number;
+    readonly latestAt: number;
+}
+export interface PanelEntry {
+    readonly definition: PanelDefinition;
+    readonly owner: PanelOwner;
+    /** 同 id 重注册时递增，用于重挂 error boundary。 */
+    readonly registrationId: number;
+    readonly badge: PanelBadge | null;
+    readonly lastError: {
+        readonly message: string;
+        readonly at: number;
+    } | null;
+    /** 插件 Panel 连续崩溃后本会话内禁用（PanelHost 渲染禁用卡）。 */
+    readonly disabled?: boolean;
+}
+/** 侧栏按键事件（v2.1：Panel 的业务键优先于宿主回退键）。 */
+export interface SidePanelKeyFlags {
+    readonly escape?: boolean;
+    readonly leftArrow?: boolean;
+    readonly rightArrow?: boolean;
+    readonly upArrow?: boolean;
+    readonly downArrow?: boolean;
+    readonly pageUp?: boolean;
+    readonly pageDown?: boolean;
+    readonly return_?: boolean;
+    readonly ctrl?: boolean;
+    readonly meta?: boolean;
+    readonly shift?: boolean;
+}
+/** 返回 true = 已消费（宿主回退键不再触发）。 */
+export type PanelKeyHandler = (input: string, key: SidePanelKeyFlags) => boolean | void;
+/**
+ * 侧栏运行时：PanelHost / usePanelInput 与 useSidePanel 之间的接缝。
+ * 由 useSidePanel 创建（Chat 侧），经 context 抵达右栏子树。
+ */
+export interface SidePanelRuntime {
+    /** 注册 Panel 的键盘处理器；enabled=false 时保留注册但不投递。 */
+    registerInput: (panelId: string, handler: PanelKeyHandler, enabled: boolean) => () => void;
+    /** 键盘分发的第一棒：焦点在右栏时先问活动 Panel 吃不吃这个键。 */
+    dispatchKey: (panelId: string, input: string, key: SidePanelKeyFlags) => boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/components/sidePanel/types.d.ts.map

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

package/lib/types/components/sidePanel/types.js

@@ -0,0 +1 @@
+export {};

package/lib/types/components/sidePanel/usePanelInput.d.ts

@@ -0,0 +1,5 @@
+import type { PanelKeyHandler } from './types.js';
+export declare function usePanelInput(handler: PanelKeyHandler, opts?: {
+    readonly active?: boolean;
+}): void;
+//# sourceMappingURL=usePanelInput.d.ts.map

package/lib/types/components/sidePanel/usePanelInput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePanelInput.d.ts","sourceRoot":"","sources":["../../../../src/components/sidePanel/usePanelInput.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,eAAe,EAAqB,MAAM,YAAY,CAAA;AAUpE,wBAAgB,aAAa,CAC3B,OAAO,EAAE,eAAe,EACxB,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GACnC,IAAI,CAwBN"}

package/lib/types/components/sidePanel/usePanelInput.js

@@ -0,0 +1,44 @@
+/**
+ * usePanelInput（v2.1 键盘契约的实现）：同一份业务键逻辑，既能整屏、
+ * 也能侧栏。
+ *
+ * - 侧栏形态（组件挂在 PanelHost 下，PanelContext 存在）：handler 注册
+ *   进 PanelHost 的输入分发器；焦点在右栏时，宿主把按键先发给活动
+ *   Panel 的 handler（返回 true = 消费，宿主回退键不再触发），Panel
+ *   没吃的键才轮到宿主回退（←/→ 切面板、Esc 回聊天……）。
+ * - 整屏形态（窄屏 / inline 回退、/jobs 早返回：没有 PanelContext）：
+ *   退化为普通 useInput(handler, { isActive: active })，行为与现状一致。
+ *
+ * active 一般传 focused && visible（PanelProps 直接给），这样
+ * mountPolicy=enabled 的面板在非 active 时保留注册但收不到键。
+ */
+import React from 'react';
+import { useInput } from '../../ui.js';
+import { PanelContext, SidePanelRuntimeContext } from './SidePanelRuntimeContext.js';
+/** ink 的 Enter 是 input='' + key.return；v2.1 的 SidePanelKeyFlags 拼
+ *  作 return_。在接缝处统一归一，两条路径（分发器 / 整屏回退）的
+ *  handler 都只需要认 return_。 */
+function normalizeKey(key) {
+    if (key.return === true && key.return_ !== true)
+        return { ...key, return_: true };
+    return key;
+}
+export function usePanelInput(handler, opts) {
+    const panelCtx = React.useContext(PanelContext);
+    const runtimeCtx = React.useContext(SidePanelRuntimeContext);
+    const active = opts?.active ?? true;
+    const inPanel = panelCtx !== null && runtimeCtx !== null;
+    // Trampoline：handler 不必是稳定引用（内联书写也安全），注册只随
+    // active / panelId 翻转而刷新。
+    const handlerRef = React.useRef(handler);
+    handlerRef.current = handler;
+    React.useEffect(() => {
+        if (!inPanel)
+            return undefined;
+        return runtimeCtx.runtime.registerInput(panelCtx.panelId, (input, key) => handlerRef.current(input, normalizeKey(key)), active);
+    }, [inPanel, runtimeCtx, panelCtx, active]);
+    // 整屏回退路径。面板形态下也挂着（isActive=false），保证 hook 顺序稳定。
+    useInput((input, key) => {
+        handlerRef.current(input, normalizeKey(key));
+    }, { isActive: !inPanel && active });
+}

package/lib/types/components/sidePanel/useSidePanel.d.ts

@@ -0,0 +1,47 @@
+import { type SidePanelSplit } from './dimensions.js';
+import type { SidePanelKeyFlags, SidePanelRuntime } from './types.js';
+export type { SidePanelKeyFlags } from './types.js';
+export type SidePanelFocus = 'chat' | 'panel';
+export interface UseSidePanelOptions {
+    /** Content width after PageMargin (what Chat's useTerminalSize reports). */
+    readonly columns: number;
+    readonly fullscreen: boolean;
+    /** Fullscreen draft editor covers the whole page: force collapsed. */
+    readonly editorOpen: boolean;
+}
+export interface SidePanelKeyEventLike {
+    stopImmediatePropagation?: () => void;
+}
+export interface SidePanelController {
+    /** Resolved split, or null when the chat takes the full width. */
+    readonly geometry: SidePanelSplit | null;
+    readonly split: boolean;
+    readonly chatColumns: number;
+    readonly panelColumns: number;
+    /** Whether a split COULD render right now (setting + width + mode). */
+    readonly splitAvailable: boolean;
+    readonly open: boolean;
+    readonly zoom: boolean;
+    readonly focus: SidePanelFocus;
+    readonly activePanelId: string | undefined;
+    readonly enabledPanelIds: readonly string[];
+    /** 键盘分发与 Panel 注册的接缝（PanelHost / usePanelInput 用）。 */
+    readonly runtime: SidePanelRuntime;
+    focusChat: () => void;
+    focusPanel: () => void;
+    /** Ctrl+B smart three-state: closed → open+focus; chat → panel; panel → close. */
+    toggleSmart: () => void;
+    /** /panel toggle: plain open/close (focus returns to chat on close). */
+    toggleOpen: () => void;
+    toggleZoom: () => void;
+    nudge: (deltaColumns: number) => void;
+    openPanel: (id: string, opts?: {
+        readonly focus?: boolean;
+    }) => void;
+    /** /panel command dispatcher; false = unknown argument. */
+    command: (raw: string) => boolean;
+    /** Keyboard entry point (see the priority contract in the file header). */
+    handleKey: (input: string, key: SidePanelKeyFlags, event?: SidePanelKeyEventLike) => boolean;
+}
+export declare function useSidePanel(options: UseSidePanelOptions): SidePanelController;
+//# sourceMappingURL=useSidePanel.d.ts.map

package/lib/types/components/sidePanel/useSidePanel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSidePanel.d.ts","sourceRoot":"","sources":["../../../../src/components/sidePanel/useSidePanel.ts"],"names":[],"mappings":"AAqCA,OAAO,EAKL,KAAK,cAAc,EACpB,MAAM,iBAAiB,CAAA;AACxB,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAGrE,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEnD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,OAAO,CAAA;AAE7C,MAAM,WAAW,mBAAmB;IAClC,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,sEAAsE;IACtE,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;CAC7B;AAED,MAAM,WAAW,qBAAqB;IACpC,wBAAwB,CAAC,EAAE,MAAM,IAAI,CAAA;CACtC;AAED,MAAM,WAAW,mBAAmB;IAClC,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAA;IACxC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAA;IAChC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAA;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1C,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAA;IAC3C,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAA;IAClC,SAAS,EAAE,MAAM,IAAI,CAAA;IACrB,UAAU,EAAE,MAAM,IAAI,CAAA;IACtB,kFAAkF;IAClF,WAAW,EAAE,MAAM,IAAI,CAAA;IACvB,wEAAwE;IACxE,UAAU,EAAE,MAAM,IAAI,CAAA;IACtB,UAAU,EAAE,MAAM,IAAI,CAAA;IACtB,KAAK,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,IAAI,CAAA;IACrC,SAAS,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAA;IACpE,2DAA2D;IAC3D,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;IACjC,2EAA2E;IAC3E,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,iBAAiB,EAAE,KAAK,CAAC,EAAE,qBAAqB,KAAK,OAAO,CAAA;CAC7F;AAMD,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,mBAAmB,CA6P9E"}