<!-- Once this directory changes, update this README.md -->

# features/workspace

Workspace management UI — sidebar listing, directory picker, session grouping.
Connects to main-process IPC for workspace CRUD, session listing, and native open actions.
Also owns the sidebar interaction contract between workspace groups and the launcher route.
Expanded Workspace sections use Session as the single sidebar list entity. Primary
Work Sessions participate in the same ordering, preview limit, and Session Group
partitioning as ordinary Chats, with Work metadata decorating their rows and routing
them to the Work surface.

## Files

- **index.ts**: Barrel re-exports for the workspace feature
- **file-tree-loader.ts**: Workspace file tree 的共享 lazy loader 与 intent preload 入口，供 right aside Files tab 使用
- **file-tree.tsx**: Right-aside workspace file tree using `@pierre/trees`, with persistent model-backed i18n-backed search, Git status annotations sourced from the shared Git status hook, active refresh for external file changes, double-click BrowserPanel tabs that open text/code files in the editor and rich files in preview, Space-triggered BrowserPanel preview tabs, shared workspace-owned Base UI file context menu actions, workspace file drag payloads for chat/TUI drops, and a first-render performance completion mark once workspace files and Git status are ready.
- **file-context-menu/**: Shared workspace file action surface. Its `lib/` owns file mutation and path helpers reused by Files and Changes containers; its `views/` directory contains the props-only Base UI context menu and create file/folder dialog.
- **workspace-file-preview.tsx**: Embedded read-only rich workspace file preview content for BrowserPanel tabs; uses workspace preview metadata to render Markdown with Streamdown, code previews with Shiki, browser-native images, PDF previews, Office-to-PDF renditions, and unsupported file fallbacks. Enter/double-click opens the text editor only for text and Markdown files.
- **workspace-pdf-preview.tsx**: PDF.js canvas renderer used for native PDF files and server-generated Office PDF renditions.
- **workspace-file-editor.tsx**: Monaco-backed editable workspace file surface for workspace-relative files, with language mapping, line numbers, folding, dirty-state feedback, save controls, and Cmd/Ctrl+S write-through to the workspace file content API.
- **workspace-file-language.ts**: Shared workspace file language helpers mapping file names/extensions to Monaco and Shiki language ids.
- **use-workspace-file-content.ts**: Hooks and URL builders for workspace file text content, preview metadata, raw bytes, and PDF renditions through workspace-owned APIs.
- **use-workspace-files.ts**: Workspace file search helper/hook for composer mentions, smart mentions, and quick open, using the bounded workspace file search API instead of preloading recursive inventories.
- **use-workspace.ts**: Hooks for listing, adding (via native directory picker), pin toggling, and deleting workspaces; exposes list readiness for interaction-level performance gates that depend on workspace names.
- **use-session.ts**: Hooks for listing active or archived sessions globally or under a single workspace, with memoized row normalization, session layout metadata hydration for app chrome, latest-user-message activity timestamps for list display, and targeted session-list cache updates; ordinary row patches preserve the API's latest-user-message order and existing timestamps, while explicit optimistic promotion is reserved for new user messages or newly created chat sessions.
- **use-cli-agents.ts**: Transitional hook for listing CLI-TUI Agent Profiles from the unified Agent Runtime
- **workspace-sidebar-ui-store.ts**: Workspace-owned persisted UI state (v4) for sidebar grouping, session ordering, list filters, preview limit, project group collapse, and per-project full session-list expansion, using the shared safe localStorage wrapper and bounded workspace-id flag maps.
- **workspace-group-disclosure.tsx**: Thin adapter that owns persisted collapse state and workspace-detail navigation for a project group.
- **workspace-group-disclosure-view.tsx**: Pure props project-group rendering seam for local, missing, and remote workspaces. It owns the disclosure header, button menu, context menu, pinned/missing state, and child composition without reading routes or stores.
- **workspace-group-disclosure-view.stories.tsx**: Fixture-driven Storybook catalog for expanded, missing, and remote project groups, including composed Session rows and interactive menu/disclosure callbacks.
- **workspace-session-item.tsx**: Runtime adapter for a sidebar Session or Work row. It owns active-surface lookup, title-regeneration state, preview-card orchestration, navigation, and Electron drag/tear-off behavior before rendering the pure row View.
- **workspace-session-item-view.tsx**: Pure props rendering seam for sidebar Session and Work rows. It owns the row's visual and local interaction semantics without reading route, store, preview-card, drag, or Electron dependencies.
- **workspace-session-item-view.stories.tsx**: Fixture-driven Storybook catalog covering active, unread, running, user-input, tool-approval, error, automation, title-regeneration, Work/PR, and rename states without mounting the workspace runtime.
- **workspace-session-actions-menu.tsx**: Runtime adapter for Session and Work row actions. It owns generated clients, query invalidation, navigation, Electron tear-off/close behavior, clipboard/export operations, and title-regeneration state.
- **workspace-session-actions-menu-state.ts**: Shared controlled-menu state contract used by the sidebar adapter and Session actions adapter.
- **workspace-session-actions-menu-view.tsx**: Pure props rendering seam for open, edit, read/pin, export, grouping, and archive actions.
- **workspace-session-actions-menu-view.stories.tsx**: Interactive fixture-driven Storybook catalog for standard, unread/pinned, and grouped Session menus.
- **workspace-session-group-partition.ts**: Pure owner-typed Session grouping calculation kept outside the Session-group rendering module.
- **workspace-session-list-section.tsx**: Session-list runtime adapter that owns persisted expansion state, running-session retention, progressive row rendering, and composition of individual Session adapters.
- **workspace-session-list-view.tsx**: Pure props rendering seam for the sidebar Session list track, empty state, and show-more/show-fewer control.
- **workspace-session-list-view.stories.tsx**: Interactive fixture-driven Storybook catalog for bounded, expanded, and empty Session lists.
- **workspace-session-status.ts**: Shared owner-typed running-status predicate used by sidebar sorting, retention, filters, and Session-list composition.
- **workspace-text-input-dialog-view.tsx**: Pure props dialog for workspace, Session-group, file, and folder naming flows.
- **workspace-text-input-dialog-view.stories.tsx**: Fixture-driven rename and create variants for the shared workspace text input dialog.
- **workspace-recognition-dialog-view.tsx**: Pure props rendering seam for valid, invalid, experimental, already-imported, and busy Cradle Workspace recognition states.
- **workspace-recognition-dialog-view.stories.tsx**: Owner-typed Storybook variants for the workspace recognition decision surface.
- **fixtures/workspace-recognition.ts**: Owner-typed recognition results covering the supported inspection outcomes.
- **workspace-multi-folder-menu-view.tsx**: Submenu checkbox flow for combining already-registered local workspaces into a multi-folder symlink workspace.
- **workspace-multi-folder-menu-view.stories.tsx**: Storybook states for the multi-folder submenu create surface.
- **multi-folder-entry-name.ts**: Safe symlink entry names derived from registered workspace identity.
- **workspace-multi-folder-dialog.tsx**: Thin DirectoryPicker adapter for multi-folder workspace creation (legacy dialog path; create UX now uses the submenu).
- **workspace-multi-folder-dialog-view.tsx**: Pure props, owner-contract-typed multi-folder form with local row editing, validation, responsive layout, and browse/submit callbacks.
- **workspace-multi-folder-dialog-view.stories.tsx**: Interactive default and creating Storybook states for multi-folder workspace creation.
- **fixtures/workspace-sidebar.ts**: Owner-typed Workspace, Session, and Work fixtures shared by workspace rendering previews.
- **fixtures/screenshots/**: Desktop and mobile golden captures for workspace fixture-driven rendering surfaces.
- **preview-card/**: Sidebar preview-card lifecycle and type-specific renderers. The shared provider keeps the interaction warm while crossing rows without previews, and `session/` owns transcript-backed session preview content.
- **workspace-sidebar.tsx**: Sidebar component whose workspace name opens the detail route surface for that workspace while the folder icon controls collapse state; app-level navigation opens New Chat, Search, Automation, Usage, and Settings before workspace-owned sections; workspace groups support pinned-first project ordering with shared visible-menu and right-click context-menu actions for pin/unpin, native Finder opening, create file/folder, rename, path copy, and delete; sidebar-owned session rendering uses one global sessions query grouped by workspace before handing rows to each workspace group, avoiding per-workspace list requests; collapsed sidebar mode keeps only the top app navigation visible and suppresses workspace/project rows; workspace/session menus handle new-surface open, Electron tear-off window open, rename, server-backed read-state toggle, pin, Markdown copy, archive, and native Finder opening through the workspace i18n namespace; archiving a session closes matching chat route surfaces and Electron tear-off windows after the session-owned archive write succeeds; session rows can be dragged outside the Electron window or double-clicked to tear chat sessions into separate windows while sharing the chat session tear-off reservation used by header surfaces; session hover/focus/open calls the chat-owned session prefetch boundary before navigation without owning transcript query details; the deferred Kanban sidebar records its own boards-query-backed first-render gate; session rows expose their actions through right-click and the keyboard Context Menu shortcut without reserving a trailing overflow-button slot; session rows keep a complete `min-w-0` shrink chain so long titles truncate inside the app sidebar; workspace session groups expand/collapse without height animation and show a bounded preview that automatically expands to include every pinned and running session, retaining just-finished running sessions until the user opens them; key navigation entries, including Search and Automation, expose stable `data-testid` anchors for E2E regression; unread display and manual read-state changes are driven by the server Session projection, and running/error display prefers the session API status with chat store as a local immediate supplement
