@rtc-agent/component 0.2.7-rc.2 → 0.2.7-rc.4

package/dist/controllers/message.controller.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Message Controller
+ *
+ * Encapsulates message list management: send, streaming append, finalize, clear.
+ * Dispatches `rtc-message-sent` event for external consumers.
+ *
+ * Cross-controller note: When the session switches, the root component calls
+ * `reload()` on this controller to load the message history for the new session.
+ *
+ * Corresponds to: `messageContext` (defined in `contexts/message.ts`).
+ * Provided by: `<rtc-agent>` (root)
+ * Consumed by: `<rtc-content-area>`, `<rtc-message-list>`, `<rtc-input-area>`
+ */
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+import type { MessageActions } from '../types/index.js';
+import type { MessageContextValue } from '../contexts/message.js';
+import type { PersistenceLayer } from '@rtc-agent/persistence';
+import type { SessionController } from './session.controller.js';
+import { MessageRepository } from '../repositories/index.js';
+export declare class MessageController implements ReactiveController {
+    host: ReactiveControllerHost & EventTarget;
+    /** Message repository for multi-session support. */
+    private _repository?;
+    /** Persistence layer — injected by root component after construction. */
+    private _persistence?;
+    /** Session controller — injected by root component after construction. */
+    private _sessionController?;
+    /**
+     * Per-session promise chain to serialize updateMessageFromBus calls.
+     * Prevents race condition when multiple messages arrive concurrently from UIUpdateBus.
+     * Key: sessionClientId, Value: pending promise chain for that session.
+     */
+    private _sessionUpdateChains;
+    readonly actions: MessageActions;
+    /** Setter for persistence injection (avoids circular deps). */
+    set persistence(layer: PersistenceLayer);
+    /**
+     * Build pagination cursor from a message.
+     * Format: "${timestamp}|${clientId}" for (created_at, client_id) composite sorting.
+     */
+    private _buildCursor;
+    /**
+     * Build pagination cursor from a UI Message.
+     *
+     * UI Message.timestamp = new Date(created_at).getTime(), which is the same
+     * numeric value that _buildCursor produces from LocalMessage.created_at.
+     * So "${msg.timestamp}|${msg.clientId}" produces an identical cursor string.
+     */
+    private _buildCursorFromUI;
+    /** Get the message repository for multi-session support. */
+    get repository(): MessageRepository;
+    /** Setter for session controller injection (avoids circular deps). */
+    set sessionController(controller: SessionController);
+    get value(): MessageContextValue;
+    constructor(host: ReactiveControllerHost & EventTarget);
+    hostConnected(): void;
+    hostDisconnected(): void;
+    /**
+     * Add a mock assistant message (demo page only).
+     *
+     * **Note**: This method is NOT part of `MessageActions` and is not exposed
+     * via Context. In a real environment, assistant messages are injected by the
+     * protocol layer via `sendMessage` or a dedicated method.
+     */
+    addDemoAssistantMessage(content: string): void;
+    /**
+     * Fetch initial messages for a session (if repository doesn't have data yet).
+     * Called by rtc-message-list in willUpdate.
+     */
+    fetchInitialMessages(sessionId: string): Promise<void>;
+    /**
+     * Load more messages for a specific session (backward pagination).
+     * Called by rtc-message-list when user scrolls to top.
+     */
+    loadMoreForSession(sessionId: string): Promise<void>;
+    /**
+     * Load newer messages for a session (forward pagination).
+     * Called by rtc-message-list when virtual scroll needs to load newer messages.
+     */
+    loadNewerForSession(sessionId: string): Promise<void>;
+    /**
+     * Evict a session from the repository cache.
+     * Called when a tab is closed to free memory.
+     */
+    evictSession(sessionId: string): void;
+    /**
+     * Update a single message field from UIUpdateBus event.
+     * More efficient than reload() for streaming updates.
+     *
+     * Handles both existing messages (patch) and new messages (append).
+     *
+     * Uses per-session promise chain to serialize updates and prevent race conditions
+     * when multiple messages arrive concurrently from UIUpdateBus.
+     *
+     * @param entityId - Message client ID
+     */
+    updateMessageFromBus(entityId: string): Promise<void>;
+    /**
+     * Apply a single UIUpdateBus update to repository and legacy state.
+     * Called within the per-session promise chain to ensure serialization.
+     */
+    private _applyBusUpdate;
+    /**
+     * Reload messages from persistence. Public method for UIUpdateBus / root wiring.
+     *
+     * - With entityId: immutable single-message update (replace matching clientId).
+     * - Without entityId: full reload for the current session (from SessionController).
+     */
+    reload(entityId?: string): Promise<void>;
+    /**
+     * Upsert a single message into the repository.
+     *
+     * Shared by `reload(entityId)` and `_applyBusUpdate()` to eliminate duplication.
+     * Uses explicit clientId check + sorted insert to prevent duplicates and ensure correct ordering.
+     *
+     * Why not use sort()?
+     * - sort() relies on timestamp values, which may be inconsistent between client and server
+     * - Direct insertion at correct position maintains order incrementally
+     * - Prevents order flips that cause VirtualScroll diff to miscalculate prepend/append
+     */
+    private _upsertMessage;
+    /**
+     * Compare two messages for sorting by (timestamp, role, clientId) composite key.
+     *
+     * Sorting priority:
+     * 1. timestamp (ascending) - primary sort by creation time
+     * 2. role priority (system < user < assistant) - ensures prompt messages appear before user messages
+     *    when timestamps are equal or very close
+     * 3. clientId (ascending) - final tiebreaker for deterministic ordering
+     *
+     * This matches the persistence layer (entity-repository.ts) and _mergeMessages() logic,
+     * with added role priority to handle the common case of prompt+user message pairs.
+     */
+    private _compareMessages;
+    private _sendMessage;
+    /**
+     * Re-send a failed message (preserves original client_id for idempotent retry).
+     */
+    private _resendMessage;
+    /**
+     * Fork a conversation: create a new session based on an existing message.
+     *
+     * Note: After forking, setCurrentSession must be called to add the new
+     * session to the sessions list, otherwise _ensureTabForSession cannot
+     * immediately locate the session to fetch its real title.
+     */
+    private _forkSession;
+    private _reloadFromDB;
+    /**
+     * Merge existing messages with freshly fetched messages.
+     *
+     * Strategy: Pure clientId deduplication.
+     * - Put existing first, then overwrite with fresh for same clientId (fresh is newer version)
+     * - Sort by (timestamp, clientId) composite key, matching persistence layer sorting
+     *
+     * Why not timestamp-based partitioning?
+     * - Timestamps are not unique (multiple messages can be created in the same millisecond)
+     * - clientId is the unique business identifier, deduplication by it is unambiguous
+     */
+    private _mergeMessages;
+    /**
+     * Get user message history for the current session (used for up/down arrow navigation in input).
+     *
+     * Returns an array of plain text content in reverse chronological order (newest first).
+     * Queried via PersistenceLayer.
+     */
+    getUserMessageHistory(sessionId: string, limit?: number): Promise<string[]>;
+    /**
+     * Extract plain text from a message's content field.
+     *
+     * Content storage formats:
+     * - Current format (post-fix): full ContentData JSON, e.g. '{"type":"user_message","data":{"text":"..."}}'
+     * - Legacy format (historical data): plain text string or object with data only, e.g. '{"text":"..."}'
+     * - Plain text: returned as-is
+     */
+    private _extractTextFromContent;
+    private _localMessageToUI;
+    private _appendToLastMessage;
+    private _finalizeLastMessage;
+    private _clearMessages;
+}
+//# sourceMappingURL=message.controller.d.ts.map

package/dist/controllers/message.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message.controller.d.ts","sourceRoot":"","sources":["../../src/controllers/message.controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAC,kBAAkB,EAAE,sBAAsB,EAAC,MAAM,KAAK,CAAC;AACpE,OAAO,KAAK,EAAwB,cAAc,EAA2B,MAAM,mBAAmB,CAAC;AACvG,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,wBAAwB,CAAC;AAChE,OAAO,KAAK,EAAC,gBAAgB,EAAe,MAAM,wBAAwB,CAAC;AAC3E,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,yBAAyB,CAAC;AAE/D,OAAO,EAAC,iBAAiB,EAAoB,MAAM,0BAA0B,CAAC;AAK9E,qBAAa,iBAAkB,YAAW,kBAAkB;IACxD,IAAI,EAAE,sBAAsB,GAAG,WAAW,CAAC;IAE3C,oDAAoD;IACpD,OAAO,CAAC,WAAW,CAAC,CAAoB;IAExC,yEAAyE;IACzE,OAAO,CAAC,YAAY,CAAC,CAAmB;IAExC,0EAA0E;IAC1E,OAAO,CAAC,kBAAkB,CAAC,CAAoB;IAE/C;;;;OAIG;IACH,OAAO,CAAC,oBAAoB,CAAoC;IAEhE,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IAEjC,+DAA+D;IAC/D,IAAI,WAAW,CAAC,KAAK,EAAE,gBAAgB,EAmCtC;IAED;;;OAGG;IACH,OAAO,CAAC,YAAY;IAKpB;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB;IAI1B,4DAA4D;IAC5D,IAAI,UAAU,IAAI,iBAAiB,CAKlC;IAED,sEAAsE;IACtE,IAAI,iBAAiB,CAAC,UAAU,EAAE,iBAAiB,EAElD;IAED,IAAI,KAAK,IAAI,mBAAmB,CAoB/B;gBAEW,IAAI,EAAE,sBAAsB,GAAG,WAAW;IAgBtD,aAAa;IACb,gBAAgB;IAOhB;;;;;;OAMG;IACH,uBAAuB,CAAC,OAAO,EAAE,MAAM;IAkBvC;;;OAGG;IACG,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU5D;;;OAGG;IACG,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM1D;;;OAGG;IACG,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM3D;;;OAGG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAIrC;;;;;;;;;;OAUG;IACG,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAwC3D;;;OAGG;IACH,OAAO,CAAC,eAAe;IAsBvB;;;;;OAKG;IACG,MAAM,CAAC,QAAQ,CAAC,EAAE,MAAM;IAsB9B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,cAAc;IA2BtB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,gBAAgB;YAgBV,YAAY;IAkE1B;;OAEG;YACW,cAAc;IAiC5B;;;;;;OAMG;YACW,YAAY;YAoDZ,aAAa;IA6F3B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,cAAc;IAUtB;;;;;OAKG;IACG,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,SAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAkB9E;;;;;;;OAOG;IACH,OAAO,CAAC,uBAAuB;IA2B/B,OAAO,CAAC,iBAAiB;IA4BzB,OAAO,CAAC,oBAAoB;IAsB5B,OAAO,CAAC,oBAAoB;IAgB5B,OAAO,CAAC,cAAc;CAgBzB"}

package/dist/controllers/mode.controller.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Mode Controller
+ *
+ * Encapsulates AI working mode state. Supports 5 modes:
+ * manual, edit, plan, auto, bypass.
+ *
+ * Corresponds to: `modeContext` (defined in `contexts/mode.ts`).
+ * Provided by: `<rtc-agent>` (root)
+ * Consumed by: `<rtc-input-area>`, `<rtc-mode-panel>`
+ */
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+import type { ModeActions } from '../types/index.js';
+import type { ModeContextValue } from '../contexts/mode.js';
+export declare class ModeController implements ReactiveController {
+    host: ReactiveControllerHost;
+    private _state;
+    readonly actions: ModeActions;
+    get value(): ModeContextValue;
+    constructor(host: ReactiveControllerHost);
+    hostConnected(): void;
+    hostDisconnected(): void;
+    /** Restore mode from localStorage */
+    private _restoreMode;
+    private _setMode;
+}
+//# sourceMappingURL=mode.controller.d.ts.map

package/dist/controllers/mode.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode.controller.d.ts","sourceRoot":"","sources":["../../src/controllers/mode.controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAC,kBAAkB,EAAE,sBAAsB,EAAC,MAAM,KAAK,CAAC;AACpE,OAAO,KAAK,EAAkB,WAAW,EAAC,MAAM,mBAAmB,CAAC;AACpE,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,qBAAqB,CAAC;AAc1D,qBAAa,cAAe,YAAW,kBAAkB;IACrD,IAAI,EAAE,sBAAsB,CAAC;IAE7B,OAAO,CAAC,MAAM,CAAsC;IAEpD,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAE9B,IAAI,KAAK,IAAI,gBAAgB,CAE5B;gBAEW,IAAI,EAAE,sBAAsB;IAWxC,aAAa;IACb,gBAAgB;IAEhB,qCAAqC;IACrC,OAAO,CAAC,YAAY;IAYpB,OAAO,CAAC,QAAQ;CAYnB"}

package/dist/controllers/notification.controller.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Notification Controller
+ *
+ * 轻量级通知系统：监听 UIUpdateBus 的新消息事件，根据焦点检测逻辑
+ * 触发声音提示、Toast 通知和最小化图标动画。
+ *
+ * 架构：
+ * - 订阅 UIUpdateBus 的 'message' 事件（按 entity 过滤）
+ * - 通过 PersistenceLayer 查询消息所属 session
+ * - 焦点检测：当前 session 收到消息不通知，其他 session 才通知
+ * - 通知展示：正常模式 → Toast，最小化模式 → 图标动画
+ *
+ * Corresponds to: `NotificationContext` (defined in `contexts/notification.ts`).
+ * Provided by: `<rtc-agent>` (root)
+ * Consumed by: 需要感知未读通知的组件
+ */
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+import type { NotificationContextValue, NotificationActions } from '../contexts/notification.js';
+import type { SessionController } from './session.controller.js';
+import type { MessageController } from './message.controller.js';
+import type { ToastController } from './toast.controller.js';
+import type { SettingsController } from './settings.controller.js';
+import type { WindowStateController } from './window-state.controller.js';
+import type { PersistenceLayer } from '@rtc-agent/persistence';
+export declare class NotificationController implements ReactiveController {
+    host: ReactiveControllerHost & HTMLElement;
+    sessionController?: SessionController;
+    messageController?: MessageController;
+    toastController?: ToastController;
+    windowStateController?: WindowStateController;
+    settingsController?: SettingsController;
+    persistence?: PersistenceLayer;
+    private _state;
+    readonly actions: NotificationActions;
+    get value(): NotificationContextValue;
+    private _busUnsubscribe?;
+    private _sounds;
+    /** 延迟加载音效的定时器（非关键音效，组件卸载时需清理） */
+    private _deferredSoundTimer?;
+    /** requestIdleCallback 返回的句柄，hostDisconnected 时用于取消尚未触发的 idle 回调。 */
+    private _idleCallbackId?;
+    /** 通知节流：防止快速连续通知导致 UI 卡顿 */
+    private _lastNotifyTime;
+    private static readonly NOTIFY_THROTTLE_MS;
+    /** Fallback delay (ms) when `requestIdleCallback` is available but hasn't fired yet. */
+    private static readonly IDLE_FALLBACK_DELAY_MS;
+    /** Delay (ms) for deferred sound loading when `requestIdleCallback` is not available. */
+    private static readonly DEFERRED_SOUND_DELAY_MS;
+    constructor(host: ReactiveControllerHost & HTMLElement);
+    hostConnected(): void;
+    hostDisconnected(): void;
+    /**
+     * 预加载提示音
+     *
+     * 关键音效（message）立即加载；非关键音效延迟加载以优化首屏性能。
+     * 加载失败时降级处理：不影响 Toast 和动画功能。
+     *
+     * 注意：音效文件路径在构建时应确保存在，运行时加载失败会降级处理。
+     */
+    private _preloadSounds;
+    private _loadSound;
+    private _playSound;
+    /**
+     * 订阅 UIUpdateBus 的新消息事件
+     *
+     * 使用按 entity 过滤的订阅模式（参考 rtc-input-area 用法）。
+     * 仅监听 content 字段的 created 事件（消息内容首次写入时触发）。
+     */
+    private _subscribeToMessages;
+    private _handleNewMessage;
+    /**
+     * 判断是否应该触发通知
+     *
+     * 场景：
+     * - 用户在 session A 看消息，session B 收到新消息 → 通知
+     * - 用户在 session A 看消息，session A 收到新消息 → 不通知
+     * - 用户没在看任何 session → 通知所有新消息
+     * - 用户禁用通知 → 所有消息都不通知
+     */
+    private _shouldNotify;
+    private _triggerNotification;
+    private _showToast;
+    /**
+     * 跳转到目标 session 并清除通知状态
+     *
+     * 流程：切换 session → 标记已读 → 派发 rtc-notification-click 事件
+     */
+    private _navigateToSession;
+    /**
+     * 触发最小化图标脉冲动画
+     *
+     * 通过 host 元素设置 data-notification 属性，
+     * CSS 通过 `:host([data-notification])` 选择器触发动画。
+     * 动画会一直持续，直到用户展开窗口或点击 bubble。
+     */
+    private _animateMinimizeIcon;
+    private _clearAnimation;
+    private _markAsRead;
+    private _clearAll;
+}
+//# sourceMappingURL=notification.controller.d.ts.map

package/dist/controllers/notification.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notification.controller.d.ts","sourceRoot":"","sources":["../../src/controllers/notification.controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAC,kBAAkB,EAAE,sBAAsB,EAAC,MAAM,KAAK,CAAC;AAEpE,OAAO,KAAK,EAAC,wBAAwB,EAAqB,mBAAmB,EAAC,MAAM,6BAA6B,CAAC;AAElH,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAC,qBAAqB,EAAC,MAAM,8BAA8B,CAAC;AACxE,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,wBAAwB,CAAC;AAiB7D,qBAAa,sBAAuB,YAAW,kBAAkB;IAC7D,IAAI,EAAE,sBAAsB,GAAG,WAAW,CAAC;IAG3C,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;IAC9C,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAG/B,OAAO,CAAC,MAAM,CAAsD;IAEpE,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IAEtC,IAAI,KAAK,IAAI,wBAAwB,CAEpC;IAGD,OAAO,CAAC,eAAe,CAAC,CAAa;IACrC,OAAO,CAAC,OAAO,CAAuC;IACtD,iCAAiC;IACjC,OAAO,CAAC,mBAAmB,CAAC,CAAgC;IAC5D,qEAAqE;IACrE,OAAO,CAAC,eAAe,CAAC,CAAS;IACjC,4BAA4B;IAC5B,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAO;IACjD,wFAAwF;IACxF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,sBAAsB,CAAQ;IACtD,yFAAyF;IACzF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,uBAAuB,CAAO;gBAE1C,IAAI,EAAE,sBAAsB,GAAG,WAAW;IAWtD,aAAa,IAAI,IAAI;IAKrB,gBAAgB,IAAI,IAAI;IAiBxB;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc;IAuDtB,OAAO,CAAC,UAAU;IAuBlB,OAAO,CAAC,UAAU;IAqBlB;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;YAad,iBAAiB;IA4B/B;;;;;;;;OAQG;IACH,OAAO,CAAC,aAAa;IAmBrB,OAAO,CAAC,oBAAoB;IA0B5B,OAAO,CAAC,UAAU;IA0BlB;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAe1B;;;;;;OAMG;IACH,OAAO,CAAC,oBAAoB;IAK5B,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,WAAW;IAMnB,OAAO,CAAC,SAAS;CAKpB"}

package/dist/controllers/persistence.controller.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Persistence Controller
+ *
+ * Manages the PersistenceLayer lifecycle: creates it lazily, connects when
+ * auth succeeds, disconnects on logout or host teardown.
+ *
+ * Uses SharedWorker + Comlink architecture:
+ * - SharedWorker hosts PersistenceLayer, Centrifuge WebSocket, IndexedDB
+ * - Comlink bridge exposes a PersistenceLayer-compatible adapter (WorkerPersistenceAdapter)
+ * - MasterLock: Master Tab election via Web Locks API
+ *
+ * Corresponds to: no context (infrastructure concern, not UI state).
+ * Provided by: `<rtc-agent>` (root)
+ * Consumed by: other controllers (via `persistence.layer`)
+ */
+import type { ReactiveController } from 'lit';
+import { type PersistenceLayer } from '@rtc-agent/persistence';
+import type { ConnectionState, ConnectionStateEvent } from '@rtc-agent/client';
+import type { AuthController } from './auth.controller.js';
+import { WorkerBridge } from '../worker-bridge.js';
+import { MasterLock } from '../master-lock.js';
+export declare class PersistenceController implements ReactiveController {
+    private _layer?;
+    private _auth;
+    private _workerBridge?;
+    private _masterLock?;
+    private _databaseNameOverride?;
+    private _workerUrl?;
+    /**
+     * In-flight connection promise — prevents concurrent `connect()` calls from
+     * racing to create multiple SharedWorker / Centrifuge connections.
+     *
+     * Cleared on success (layer is set) or failure (so a retry can proceed).
+     */
+    private _connecting?;
+    private static readonly MAX_CONNECT_RETRIES;
+    private static readonly CONNECT_RETRY_DELAY_MS;
+    constructor(host: {
+        addController(c: ReactiveController): void;
+    }, auth: AuthController);
+    /** Set custom database name prefix. Must be called before connect(). */
+    set databaseName(value: string | undefined);
+    /**
+     * Set custom SharedWorker URL.
+     *
+     * When the component is loaded from NPM, the worker file may not be accessible
+     * from the default location. Use this to specify a custom URL where the worker
+     * file is served (e.g., '/rtc-agent/shared-worker.js').
+     *
+     * Must be called before connect().
+     */
+    set workerUrl(value: string | undefined);
+    /** The PersistenceLayer instance. Only available after connect(). */
+    get layer(): PersistenceLayer | undefined;
+    /** Whether the persistence layer is connected. */
+    get isConnected(): boolean;
+    /**
+     * Get the WorkerBridge instance.
+     */
+    get workerBridge(): WorkerBridge | undefined;
+    /**
+     * Get the MasterLock instance.
+     *
+     * MasterLock 封装 Web Locks API，用于 Master Tab 选举。
+     * 每个 Tab 各自持有一个 MasterLock，自己判断是否为 Master。
+     * 只有 Master Tab 的 RtcProcessor 会执行 RTC 工具调用。
+     *
+     * @see docs/shared-worker-proposal.md §4.3
+     */
+    get masterLock(): MasterLock | undefined;
+    hostConnected(): void;
+    hostDisconnected(): void;
+    /**
+     * Create the PersistenceLayer and connect.
+     *
+     * Creates SharedWorker + Comlink bridge.
+     * The WorkerPersistenceAdapter wraps the Comlink proxy, presenting a
+     * PersistenceLayer-compatible interface to the rest of the application.
+     *
+     * Call this after auth succeeds (tokens are set in AuthController).
+     * Safe to call multiple times — subsequent calls are no-ops.
+     */
+    connect(): Promise<void>;
+    /**
+     * Create SharedWorker + Comlink bridge.
+     *
+     * The WorkerPersistenceAdapter wraps the Comlink proxy, presenting a
+     * PersistenceLayer-compatible interface to the rest of the application.
+     *
+     * 支持重试：如果 Worker 初始化或连接失败，会自动重试。
+     */
+    private _connectWorker;
+    /**
+     * 单次连接尝试
+     */
+    private _connectWorkerOnce;
+    /**
+     * 清理失败的连接
+     */
+    private _cleanupFailedConnection;
+    /**
+     * 延迟指定毫秒数
+     */
+    private _delay;
+    /**
+     * Disconnect and tear down the PersistenceLayer.
+     *
+     * - 先 reset offset，再 close layer
+     * - 额外释放 MasterLock + 销毁 WorkerBridge
+     *
+     * Call this on logout or when auth is lost.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * 获取当前连接状态
+     *
+     * 通过 WorkerBridge 获取连接状态。
+     */
+    getConnectionState(): Promise<ConnectionState>;
+    /**
+     * 监听连接状态变更
+     *
+     * 监听 WorkerBridge 广播的连接状态变更事件。
+     * 返回取消监听的函数。
+     */
+    onConnectionStateChange(listener: (event: ConnectionStateEvent) => void): () => void;
+}
+//# sourceMappingURL=persistence.controller.d.ts.map

package/dist/controllers/persistence.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.controller.d.ts","sourceRoot":"","sources":["../../src/controllers/persistence.controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,KAAK,CAAC;AAE5C,OAAO,EACH,KAAK,gBAAgB,EAMxB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,KAAK,EAAC,eAAe,EAAE,oBAAoB,EAAC,MAAM,mBAAmB,CAAC;AAG7E,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,sBAAsB,CAAC;AAKzD,OAAO,EAAC,YAAY,EAAC,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAC,UAAU,EAAC,MAAM,mBAAmB,CAAC;AAwM7C,qBAAa,qBAAsB,YAAW,kBAAkB;IAC5D,OAAO,CAAC,MAAM,CAAC,CAAmB;IAClC,OAAO,CAAC,KAAK,CAAiB;IAC9B,OAAO,CAAC,aAAa,CAAC,CAAe;IACrC,OAAO,CAAC,WAAW,CAAC,CAAa;IACjC,OAAO,CAAC,qBAAqB,CAAC,CAAS;IACvC,OAAO,CAAC,UAAU,CAAC,CAAS;IAE5B;;;;;OAKG;IACH,OAAO,CAAC,WAAW,CAAC,CAAgB;IAEpC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAAK;IAChD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,sBAAsB,CAAQ;gBAGlD,IAAI,EAAE;QAAC,aAAa,CAAC,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAA;KAAC,EAClD,IAAI,EAAE,cAAc;IAMxB,wEAAwE;IACxE,IAAI,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAEzC;IAED;;;;;;;;OAQG;IACH,IAAI,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAEtC;IAED,qEAAqE;IACrE,IAAI,KAAK,IAAI,gBAAgB,GAAG,SAAS,CAExC;IAED,kDAAkD;IAClD,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED;;OAEG;IACH,IAAI,YAAY,IAAI,YAAY,GAAG,SAAS,CAE3C;IAED;;;;;;;;OAQG;IACH,IAAI,UAAU,IAAI,UAAU,GAAG,SAAS,CAEvC;IAED,aAAa;IAIb,gBAAgB;IAIhB;;;;;;;;;OASG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAyC9B;;;;;;;OAOG;YACW,cAAc;IA2B5B;;OAEG;YACW,kBAAkB;IAiDhC;;OAEG;YACW,wBAAwB;IAYtC;;OAEG;IACH,OAAO,CAAC,MAAM;IAId;;;;;;;OAOG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA4BjC;;;;OAIG;IACG,kBAAkB,IAAI,OAAO,CAAC,eAAe,CAAC;IAOpD;;;;;OAKG;IACH,uBAAuB,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,GAAG,MAAM,IAAI;CAOvF"}

package/dist/controllers/session-tab.controller.d.ts

@@ -0,0 +1,82 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+import type { SessionTabState, SessionTabActions, SessionStatus } from '../types/index.js';
+export declare class SessionTabController implements ReactiveController {
+    host: ReactiveControllerHost;
+    private _state;
+    readonly actions: SessionTabActions;
+    get value(): {
+        state: SessionTabState;
+        actions: SessionTabActions;
+    };
+    constructor(host: ReactiveControllerHost);
+    hostConnected(): void;
+    hostDisconnected(): void;
+    /**
+     * 过滤掉无效 Tab（session 已被删除或不存在）
+     *
+     * 在 session 列表从 IndexedDB 加载后调用，清理持久化中残留的无效 Tab。
+     * `isUnsaved === true` 的 tab 即使 sessionId 不在 DB 中也保留（它们是尚未持久化的 draft）。
+     * 返回 true 表示有 Tab 被移除（调用方可能需要更新 UI）。
+     */
+    filterInvalidTabs(validSessionIds: Set<string>): boolean;
+    /**
+     * 用 sessions 中的最新标题同步已有 Tab 的标题
+     *
+     * DB 是标题的权威来源。UIUpdateBus 推送的 session 变更（用户 rename 或服务端生成）
+     * 都已先写入 DB，此方法负责把 DB 中的最新标题同步到 Tab。
+     *
+     * 跳过条件：
+     * - Tab 对应的 session 不在 DB 中（如 unsaved tab，newTitle 为 undefined）
+     * - DB 返回空标题
+     * - DB 标题与 Tab 当前标题完全相同（无变化）
+     */
+    updateTabTitles(sessionTitleMap: Map<string, string>): boolean;
+    /**
+     * 用 sessions 中的最新状态同步已有 Tab 的 status
+     *
+     * DB 是 status 的权威来源（服务端 turn 生命周期事件写入）。
+     * 在 _loadSessions 时调用，确保 tab status 与 DB 一致。
+     */
+    syncTabStatuses(sessionStatusMap: Map<string, SessionStatus>): boolean;
+    private _isPlaceholderTitle;
+    /** 查找当前 unsaved tab，返回第一个 isUnsaved === true 的 tab。 */
+    private _findUnsavedTab;
+    /** 将指定 tab 标记为已保存。 */
+    private _markSaved;
+    /** 更新指定 tab 的 session 运行状态（active/idle/closed）。 */
+    private _updateTabStatus;
+    private _openOrActivate;
+    private _closeTab;
+    private _setActiveTab;
+    private _clearAll;
+    /**
+     * 把 activeSessionId 写入 localStorage
+     *
+     * 仅在浏览器环境下执行（SSR 安全）；任何异常静默忽略（如隐私模式配额为 0）。
+     */
+    private _persistActiveSessionId;
+    /**
+     * 从 localStorage 读取上次活动 Tab 的 sessionId
+     *
+     * 用于恢复 tabs 循环时决定哪个 tab 应该 activate: true。
+     * 如果 localStorage 为空或不可用，返回 null。
+     */
+    private _getStoredActiveSessionId;
+    /**
+     * 设置指定 tab 的瞬态 UI 参数（initialInputValue, noticeMessage）
+     *
+     * 同时递增 initialValueVersion，确保即使新旧值相同，
+     * input-area 的 updated() 也能被触发（防御 Lit 脏检查跳过）。
+     */
+    private _setTransientParams;
+    /** 清除指定 tab 的瞬态 UI 参数。 */
+    private _clearTransientParams;
+    /**
+     * 从 localStorage 恢复活动 Tab
+     *
+     * 仅当存储的 sessionId 在当前 tabs 列表中时才恢复，否则保持不变。
+     * 用于浏览器刷新后恢复用户上次的活动 tab。
+     */
+    private _restoreActiveFromStorage;
+}
+//# sourceMappingURL=session-tab.controller.d.ts.map

package/dist/controllers/session-tab.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-tab.controller.d.ts","sourceRoot":"","sources":["../../src/controllers/session-tab.controller.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAC,kBAAkB,EAAE,sBAAsB,EAAC,MAAM,KAAK,CAAC;AACpE,OAAO,KAAK,EAAa,eAAe,EAAE,iBAAiB,EAAE,aAAa,EAAC,MAAM,mBAAmB,CAAC;AAOrG,qBAAa,oBAAqB,YAAW,kBAAkB;IAC3D,IAAI,EAAE,sBAAsB,CAAC;IAE7B,OAAO,CAAC,MAAM,CAAsD;IAEpE,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IAEpC,IAAI,KAAK,IAAI;QAAC,KAAK,EAAE,eAAe,CAAC;QAAC,OAAO,EAAE,iBAAiB,CAAA;KAAC,CAEhE;gBAEW,IAAI,EAAE,sBAAsB;IA2BxC,aAAa;IACb,gBAAgB;IAEhB;;;;;;OAMG;IACH,iBAAiB,CAAC,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,OAAO;IAyBxD;;;;;;;;;;OAUG;IACH,eAAe,CAAC,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO;IA4B9D;;;;;OAKG;IACH,eAAe,CAAC,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,OAAO;IAoBtE,OAAO,CAAC,mBAAmB;IAI3B,uDAAuD;IACvD,OAAO,CAAC,eAAe;IAIvB,sBAAsB;IACtB,OAAO,CAAC,UAAU;IAalB,mDAAmD;IACnD,OAAO,CAAC,gBAAgB;IAWxB,OAAO,CAAC,eAAe;IAmEvB,OAAO,CAAC,SAAS;IAyBjB,OAAO,CAAC,aAAa;IAYrB,OAAO,CAAC,SAAS;IAMjB;;;;OAIG;IACH,OAAO,CAAC,uBAAuB;IAa/B;;;;;OAKG;IACH,OAAO,CAAC,yBAAyB;IASjC;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAiB3B,0BAA0B;IAC1B,OAAO,CAAC,qBAAqB;IAa7B;;;;;OAKG;IACH,OAAO,CAAC,yBAAyB;CAiBpC"}

package/dist/controllers/session-tree.controller.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Session Tree Controller
+ *
+ * 将平铺的 session 列表构建为层级树：
+ * - rootClientSessionId 为空的 session 作为根节点
+ * - 其余 session 按 rootClientSessionId 分组，挂到对应根节点的 children 中
+ *
+ * 管理展开/折叠状态。session 列表变化时通过 rebuildTree() 重建。
+ *
+ * 对应：`SessionTreeContext`（contexts/session-tree.ts）
+ * 消费方：<rtc-session-tree>, <rtc-session-tree-item>
+ */
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+import type { SessionTreeState, SessionTreeActions } from '../types/index.js';
+export declare class SessionTreeController implements ReactiveController {
+    host: ReactiveControllerHost;
+    private _state;
+    /** 展开状态的 Map：sessionId → isExpanded。默认全部折叠。 */
+    private _expanded;
+    readonly actions: SessionTreeActions;
+    get value(): {
+        state: SessionTreeState;
+        actions: SessionTreeActions;
+    };
+    constructor(host: ReactiveControllerHost);
+    hostConnected(): void;
+    hostDisconnected(): void;
+    private _restoreExpanded;
+    private _persistExpanded;
+    private _toggleExpand;
+    private _setExpanded;
+    /**
+     * 用当前缓存的 sessions 和展开状态重建树
+     *
+     * rebuildTree 时 sessions 会更新，但展开状态 (_expanded) 保留。
+     * 此方法从 _expanded 读取最新展开状态来重建。
+     */
+    private _rebuildTreeFromCache;
+    private _cachedSessions?;
+    private _rebuildTree;
+    private _buildTree;
+    private _buildNode;
+}
+//# sourceMappingURL=session-tree.controller.d.ts.map

package/dist/controllers/session-tree.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-tree.controller.d.ts","sourceRoot":"","sources":["../../src/controllers/session-tree.controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAC,kBAAkB,EAAE,sBAAsB,EAAC,MAAM,KAAK,CAAC;AACpE,OAAO,KAAK,EAA2B,gBAAgB,EAAE,kBAAkB,EAAC,MAAM,mBAAmB,CAAC;AAStG,qBAAa,qBAAsB,YAAW,kBAAkB;IAC5D,IAAI,EAAE,sBAAsB,CAAC;IAE7B,OAAO,CAAC,MAAM,CAAqC;IACnD,+CAA+C;IAC/C,OAAO,CAAC,SAAS,CAA8B;IAE/C,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IAErC,IAAI,KAAK,IAAI;QAAC,KAAK,EAAE,gBAAgB,CAAC;QAAC,OAAO,EAAE,kBAAkB,CAAA;KAAC,CAElE;gBAEW,IAAI,EAAE,sBAAsB;IAaxC,aAAa;IACb,gBAAgB;IAIhB,OAAO,CAAC,gBAAgB;IAKxB,OAAO,CAAC,gBAAgB;IAqBxB,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,YAAY;IAMpB;;;;;OAKG;IACH,OAAO,CAAC,qBAAqB;IAQ7B,OAAO,CAAC,eAAe,CAAC,CAAY;IAEpC,OAAO,CAAC,YAAY;IAKpB,OAAO,CAAC,UAAU;IA4BlB,OAAO,CAAC,UAAU;CAWrB"}

package/dist/controllers/session.controller.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Session Controller
+ *
+ * Encapsulates session management: create, switch, rename, delete.
+ * Dispatches public `rtc-session-*` events on the host for external consumers.
+ *
+ * When switching sessions, also reloads messages for the new session (via messageController reference).
+ * This cross-controller communication is handled by the root component wiring.
+ *
+ * Corresponds to: `sessionContext` (defined in `contexts/session.ts`).
+ * Provided by: `<rtc-agent>` (root)
+ * Consumed by: `<rtc-session-header>`, `<rtc-session-panel>`, `<rtc-content-area>`
+ */
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+import type { SessionActions } from '../types/index.js';
+import type { SessionContextValue } from '../contexts/session.js';
+import type { PersistenceLayer } from '@rtc-agent/persistence';
+export declare class SessionController implements ReactiveController {
+    host: ReactiveControllerHost & EventTarget;
+    private _state;
+    readonly actions: SessionActions;
+    /** Called when session switches — root wires this to MessageController. */
+    onSessionSwitch?: () => void;
+    /**
+     * Persistence layer reference (injected by root after connect).
+     *
+     * When set, rename/delete operations are persisted to IndexedDB + synced to server.
+     * When unset, rename/delete operate in-memory only (offline / pre-connect fallback).
+     */
+    persistence?: PersistenceLayer;
+    get value(): SessionContextValue;
+    constructor(host: ReactiveControllerHost & EventTarget);
+    hostConnected(): void;
+    hostDisconnected(): void;
+    private _createSession;
+    private _switchSession;
+    private _renameSession;
+    private _deleteSession;
+    /**
+     * 通知后端关闭 session
+     *
+     * 仅发送 RPC 通知，不做本地状态变更（Tab 关闭由调用方处理）。
+     * 失败时仅 log 错误，由调用方决定如何处理。
+     */
+    private _closeSession;
+    /**
+     * 重新打开已关闭的 session（透明 reopen）
+     *
+     * 调用后端 openSession API，将 session 状态从 closed 改回 idle/active。
+     * 后端返回 updates 后由 applyUpdates 处理本地状态同步。
+     */
+    private _reopenSession;
+    private _reset;
+    private _clearCurrentSession;
+    private _setCurrentSession;
+    private _setSessions;
+}
+//# sourceMappingURL=session.controller.d.ts.map

package/dist/controllers/session.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.controller.d.ts","sourceRoot":"","sources":["../../src/controllers/session.controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAC,kBAAkB,EAAE,sBAAsB,EAAC,MAAM,KAAK,CAAC;AACpE,OAAO,KAAK,EAAwB,cAAc,EAAC,MAAM,mBAAmB,CAAC;AAC7E,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,wBAAwB,CAAC;AAEhE,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,wBAAwB,CAAC;AAK7D,qBAAa,iBAAkB,YAAW,kBAAkB;IACxD,IAAI,EAAE,sBAAsB,GAAG,WAAW,CAAC;IAE3C,OAAO,CAAC,MAAM,CAA4C;IAE1D,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IAEjC,2EAA2E;IAC3E,eAAe,CAAC,EAAE,MAAM,IAAI,CAAC;IAE7B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAE/B,IAAI,KAAK,IAAI,mBAAmB,CAE/B;gBAEW,IAAI,EAAE,sBAAsB,GAAG,WAAW;IAkBtD,aAAa;IACb,gBAAgB;IAEhB,OAAO,CAAC,cAAc;IAsBtB,OAAO,CAAC,cAAc;YAeR,cAAc;YA2Bd,cAAc;IAkD5B;;;;;OAKG;YACW,aAAa;IAsB3B;;;;;OAKG;YACW,cAAc;IAe5B,OAAO,CAAC,MAAM;IAKd,OAAO,CAAC,oBAAoB;IAO5B,OAAO,CAAC,kBAAkB;IAiB1B,OAAO,CAAC,YAAY;CAKvB"}