Quick Chat Selection System Design

Purpose and boundaries

This design extends the shared Quick Chat tab contract. It owns remembered conversation selection, not tab membership or agent lifecycle.

Requirement mapping

Requirement	Design sections
`REQ-UI-QUICK-TERMINAL-003`	Ownership and persistence; selection and restoration; responsive behavior and verification

Ownership and persistence

UI owns the reading preference. Task services still own conversation membership, and the existing session-resumption hook owns runtime recovery. This section is the proposed design for REQ-UI-QUICK-TERMINAL-003.

Add a typed selection map to QuickChatState, separate from the visible activeSessionId and terminal-selection fields. Key it by workspace and conversation kind (chat or config). Values identify persisted session IDs, never titles. Track in-memory setup selection separately from the persisted choice.

Use a small browser-storage module under apps/web/lib/quick-chat/. Store a versioned map in localStorage, scoped by authenticated user ID. Use a distinct local identity only when authentication is disabled. Anonymous authentication-enabled pages must not read or write another identity's preference. Validate parsed shapes and entries. Retain at most 200 workspace entries per identity, ordered by the latest explicit selection. Catch unavailable storage and quota failures. On identity change, clear the old in-memory map before loading the new identity. Store only identifiers; never store conversation content or credentials.

Selection belongs to the local reading context, unlike portable tab order. Backend user settings would couple independent devices and add a write for every selection. Browser storage provides restart recovery without that coupling. Do not subscribe to storage events to change an open dialog. Each mounted client keeps its own selection; a fresh client reads the last stored choice. No backend schema, endpoint, or preference migration is needed.

Selection and restoration

Centralize remembered-choice updates for explicit openQuickChat, setActiveQuickChatSession, and successful new-conversation activation. activateQuickTerminal must not erase either conversation-kind preference. Background upserts and hydration fallbacks must not write a new remembered choice. Keep storage side effects outside Immer recipes. The root store integration must cover direct action callers, including configuration launchers and new-chat flows.

useQuickChatLauncher resolves the requested workspace and kind against current state at activation time. Prefer an explicitly selected current-page setup, then the valid remembered conversation. Otherwise use orderQuickChatTabs with the current optimistic or saved workspace order, filtered to eligible conversations. Without a candidate, retain the existing kind-specific setup behavior. An explicit session-ID open always wins over remembered selection.

Add per-workspace list readiness to the existing hydration/resync path. An accepted boot snapshot or successful syncQuickChatSessions marks that workspace ready. An initial empty state, failed request, or discarded stale response does not. An open request before readiness displays the existing loading presentation without mounting another persisted session view. A pending request carries workspace, kind, and a selection revision. Dismissal, a workspace change, or explicit selection invalidates it. Resolve it once after an accepted snapshot; never poll separately. Existing resync error handling remains authoritative. A failed load preserves the remembered ID and leaves the surface dismissible.

restoreQuickChatSelection, reconcileQuickChatSessions, and deletion paths must distinguish missing-before-readiness from authoritative removal. After removal, clear only the matching workspace/kind entry. Preserve existing adjacent-tab behavior when closing the visible tab; record its replacement only for that kind. Never prune unrelated workspace preferences from a partial workspace snapshot.

Responsive behavior and verification

Keep the existing desktop floating dialog and phone full-height dialog. The phone listing menu remains the entry point and closes before Quick Chat opens. The tab strip owns horizontal overflow; the selected content owns vertical scrolling. No new toolbar, sizing, or focus policy is introduced.

Unit tests cover storage failure, identity separation, selection precedence, terminal/config visits, ordered fallback, authoritative deletion, and delayed hydration. Desktop and phone E2E select a non-first conversation, dismiss, reload, and reopen. They assert the active content identity and unchanged conversation count. The fix package is Quick Chat selection.

4.9 KiB Raw Blame History