@deepseek-ai/dsh-client-ui-workspace 0.0.1-rc.1

package/lib/index.js

@@ -0,0 +1,11 @@
+//#region lib/types/index.js
+/**
+* Workspace picker plugin, node half. Pure UI plugin: the empty apply exists
+* so the plugin appears in the host cordis.yml / Loader (load and lifecycle
+* follow the host; the browser half ships via exports["./client"], discovered
+* through the package.json dsh.client declaration).
+*/
+/** Host plugin body — no host-side behavior for the workspace picker plugin. */
+function apply() {}
+//#endregion
+export { apply };

package/lib/invariant.js

@@ -0,0 +1,25 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-client-ui-workspace`.
+* @module @deepseek-ai/dsh-client-ui-workspace/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-client-ui-workspace";
+/** Cordis companion plugin name. */
+const name = "client-ui-workspace-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: a pure-consumer plugin registering presentational
+* components into two host-declared slots plus its locale dictionaries — its
+* inject face is stateless RPC wrappers plus a create-and-open call; it
+* emits no cordis events and owns no cross-plugin mutable state.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/client/WorkspaceBrowser.d.ts

@@ -0,0 +1,8 @@
+import type { WorkspaceBrowserProps } from './contract/slots.ts';
+/**
+ * Render the browsing region.
+ * @param props - composed slot props (shell owner share + store + injected actions).
+ * @returns the region element tree.
+ */
+export declare function WorkspaceBrowser({ wide, expandSidebar, useSessions, useWorkspaces, useStore, actions, startSession, open, renameSession, forkSession, renameWorkspace, deleteWorkspace, archiveSession, insertSessionBefore, createWorkspace, searchSessions, searchResultLimit, useDirectoryFlow, renderSlot, t, }: WorkspaceBrowserProps): import("react").JSX.Element;
+//# sourceMappingURL=WorkspaceBrowser.d.ts.map

package/lib/types/client/WorkspacePicker.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Workspace pick/add flow. WorkspacePickFlow is the reusable core (menu +
+ * path error dialog) consumed directly by WorkspaceBrowser (same package) and
+ * wrapped by WorkspacePicker for the conversation empty-state slot
+ * registration. Directory picking itself lives in the composed flow package's
+ * slot occupant (see the contract module doc): this core only opens the flow,
+ * adopts the picked path, and owns the error surface. Adding a workspace has
+ * exactly one route — pick a host directory, new or existing — because the
+ * occupant's own create-folder affordance already covers creating one.
+ */
+import type { ReactNode, RefObject } from 'react';
+import type { WorkspaceId, WorkspaceListState, WorkspaceView } from '@deepseek-ai/dsh-client-runtime/client';
+import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots';
+import type { DirectoryFlowOwnerProps, WorkspacePickerProps } from './contract/slots.ts';
+/** Core flow props: the owner supplies popover control and pick semantics. */
+export interface WorkspacePickFlowProps {
+    /** The standard locale seat, forwarded by whichever slot entry hosts the flow. */
+    t: WorkspacePickerProps['t'];
+    /** Popover visibility (anchor button toggle state, owner-local). */
+    open: boolean;
+    /** The anchor button element — the popover's placement anchor. */
+    anchorRef?: RefObject<HTMLElement | null> | undefined;
+    /** Selector hook over the workspace list (framework standard hook). */
+    useWorkspaces: <S>(selector: (state: WorkspaceListState) => S) => S;
+    /** Adopt a picked host directory as a real Workspace. */
+    createWorkspace: (input: {
+        path: string;
+    }) => Promise<WorkspaceView>;
+    /** Bound occupancy selector hook for this surface's directory-flow hole (empty leaves the surface with no add action). */
+    useDirectoryFlow: SnapshotSelectorHook<boolean>;
+    /** Render this surface's directory-flow hole with the owner conversation (the entry's narrowed renderSlot). */
+    renderDirectoryFlow: (owner: DirectoryFlowOwnerProps) => ReactNode;
+    /** A real Workspace was picked or created. */
+    onPick: (workspaceId: WorkspaceId) => void;
+    /** Close the popover (outside click / Escape / post-pick). */
+    onClose: () => void;
+    /** Only offer the add action, hide existing workspaces. */
+    addOnly?: boolean;
+    /** Menu opening direction relative to the anchor. */
+    side?: 'bottom' | 'top' | 'right';
+    /** Currently active workspace (trailing check in the picker list). */
+    selectedId?: WorkspaceId | undefined;
+}
+/**
+ * Render the pick menu plus the adoption error dialog.
+ * @param props - owner-controlled flow props.
+ * @returns menu + dialog elements.
+ */
+export declare function WorkspacePickFlow({ t, open, anchorRef, useWorkspaces, createWorkspace, useDirectoryFlow, renderDirectoryFlow, onPick, onClose, addOnly, side, selectedId, }: WorkspacePickFlowProps): import("react").JSX.Element;
+/**
+ * The conversation empty-state registration: adapts the owner share to the
+ * core flow (all state and semantics live in the flow / the owner).
+ * @param props - empty-state slot props (owner share + injected creation callback).
+ * @returns the flow element.
+ */
+export declare function WorkspacePicker({ open, anchorRef, useWorkspaces, selectedId, onPick, onClose, createWorkspace, useDirectoryFlow, renderSlot, t, }: WorkspacePickerProps): import("react").JSX.Element;
+//# sourceMappingURL=WorkspacePicker.d.ts.map

package/lib/types/client/contract/slots.d.ts

@@ -0,0 +1,149 @@
+/**
+ * ui-workspace contracts. Two registrations share this package:
+ *
+ * - WorkspaceBrowser fills the sidebar shell's `sidebar.workspaces` hole —
+ *   the whole browsing region (section header, search, grouped/flat session
+ *   list, workspace dialogs). It registers this package's viewing store and
+ *   consumes the shell's two-fact owner share (wide / expandSidebar).
+ * - WorkspacePicker fills the conversation empty-state hole (menu + error
+ *   dialog shared with the browser).
+ *
+ * Each registration also declares one **directory-flow hole** (`single`
+ * kind): the slot a composed picker package's client half fills with its
+ * picking interaction — a renderless native-chooser driver or an in-app
+ * browsing dialog. ui-workspace owns the trigger (the "Add workspace…"
+ * entry, present only while the hole is occupied) and the adoption
+ * semantics (`createWorkspace({ path })`, the retryable error dialog,
+ * Choose again); the occupant owns everything between `open` and the picked path,
+ * including creating a new directory to hand back. That occupant-owned
+ * creation is why adding a workspace has a single route: an unoccupied hole
+ * leaves the surface with no add affordance at all.
+ * Two holes exist because the two menu surfaces are independent slot entries
+ * and a hole has exactly one declaring entry — they carry the same owner
+ * contract and the same occupant.
+ */
+import type { HostObservable, PropsLocale, PropsRenderSlots, PropsRuntime, PropsStore, SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots';
+import type { SessionId, SessionSearchResultItem, WorkspaceId, WorkspaceView } from '@deepseek-ai/dsh-client-runtime/client';
+import type { createWorkspaceViewStore } from '../stores.ts';
+/**
+ * Owner share of the directory-flow holes: the complete conversation between
+ * the trigger surface and the picking interaction. The occupant reads `open`
+ * to run/render its interaction and reports exactly one outcome per open.
+ */
+export interface DirectoryFlowOwnerProps {
+    /** True while a picking interaction is requested; flipping back to false withdraws the request. */
+    open: boolean;
+    /** True while the owner adopts a picked path (`createWorkspace` in flight); occupants disable their commit affordances. */
+    busy: boolean;
+    /** The operator picked a directory (absolute host path); the owner adopts it. */
+    onPicked: (path: string) => void;
+    /** The operator dismissed the interaction; the owner just closes the flow. */
+    onCancel: () => void;
+    /** The interaction itself failed (chooser missing, listing denied); the owner shows its error surface. */
+    onError: (message: string) => void;
+}
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface SlotMap {
+        /** Directory-flow hole under the conversation empty-state picker (declared by the WorkspacePicker entry). */
+        'conversation.hero.workspace.directoryFlow': {
+            kind: 'single';
+            scope: 'root';
+            owner: DirectoryFlowOwnerProps;
+        };
+        /** Directory-flow hole under the sidebar browsing region (declared by the WorkspaceBrowser entry). */
+        'sidebar.workspaces.directoryFlow': {
+            kind: 'single';
+            scope: 'root';
+            owner: DirectoryFlowOwnerProps;
+        };
+    }
+}
+/** The two directory-flow holes; a flow package's client half registers its one component into both. */
+export type DirectoryFlowSlotName = 'conversation.hero.workspace.directoryFlow' | 'sidebar.workspaces.directoryFlow';
+/**
+ * Directory-picking share both trigger surfaces consume. Occupancy rides the
+ * inject face's reserved `hooks` compartment: the renderer binds the source
+ * into the `useDirectoryFlow` selector hook, so an empty hole hides the
+ * "Add workspace…" entry reactively and the surface withdraws an open
+ * flow whose occupant unloaded mid-interaction (nobody is left to cancel).
+ */
+export type DirectoryPickingInjected = {
+    hooks: {
+        /** True while this surface's directory-flow hole is occupied. */
+        directoryFlow: HostObservable<boolean>;
+    };
+};
+/** Component-side view of the picking share: the bound occupancy selector hook. */
+export type DirectoryPickingHooks = {
+    /** Selector hook over this surface's directory-flow occupancy. */
+    useDirectoryFlow: SnapshotSelectorHook<boolean>;
+};
+/**
+ * Browser-private injected share (arrives via the register inject factory).
+ * Data reads use the global framework hooks; these are the Host actions the
+ * browsing region drives.
+ */
+export type WorkspaceBrowserInjected = DirectoryPickingInjected & {
+    /**
+     * Start a New Session in a Workspace: reuse-or-create its blank session
+     * and open it; with no workspace, clear the selection into the New Session
+     * pure view state (the conversation.empty seat).
+     */
+    startSession: (workspaceId?: WorkspaceId) => void;
+    /** Open a real Session. */
+    open: (sessionId: SessionId) => void;
+    /**
+     * Search current visible conversation messages. The Host fixes the result
+     * bound; `hasMore` means the query needs narrowing.
+     */
+    searchSessions: (query: string, signal: AbortSignal) => Promise<{
+        items: readonly SessionSearchResultItem[];
+        hasMore: boolean;
+    }>;
+    /** Maximum number of merged rows rendered for one search. */
+    searchResultLimit: number;
+    /** Rename a Session (explicit user title; resolves on host acceptance). */
+    renameSession: (sessionId: SessionId, title: string) => Promise<void>;
+    /** Fork a Session at its last completed turn and open the child. */
+    forkSession: (sessionId: SessionId) => void;
+    /** Rename a Host Workspace (rejects on name conflict; resolves on durability). */
+    renameWorkspace: (workspaceId: WorkspaceId, title: string) => Promise<void>;
+    /** Delete only a Host Workspace registration; directory and Session logs remain. */
+    deleteWorkspace: (workspaceId: WorkspaceId) => Promise<void>;
+    /**
+     * Archive a Session into the registry-global set: hidden from grouping
+     * surfaces, log and accounting slot retained. Archiving the current
+     * session clears the selection into the New Session view state.
+     */
+    archiveSession: (sessionId: SessionId) => Promise<void>;
+    /**
+     * Reorder a session inside its Workspace account (DOM-insertBefore
+     * semantics: omitted anchor appends to the end). The view refreshes from
+     * the Host response/changed frame; failures leave the order unchanged.
+     */
+    insertSessionBefore: (workspaceId: WorkspaceId, sessionId: SessionId, beforeSessionId?: SessionId) => Promise<void>;
+    /** Adopt a picked host directory as a real Workspace before targeting a Session. */
+    createWorkspace: (input: {
+        path: string;
+    }) => Promise<WorkspaceView>;
+};
+/** Full browser props: shell owner share + viewing store + injected actions + the locale seat. */
+export type WorkspaceBrowserProps = PropsRuntime<'sidebar.workspaces'> & PropsRenderSlots<'sidebar.workspaces.directoryFlow'> & PropsStore<ReturnType<typeof createWorkspaceViewStore>> & Omit<WorkspaceBrowserInjected, 'hooks'> & DirectoryPickingHooks & PropsLocale<'workspace'>;
+/**
+ * Picker-private injected share. Pick semantics remain in the owner's onPick
+ * callback; this callback creates only the real Host Workspace. A type alias
+ * supplies the implicit index signature required by the registry.
+ */
+export type WorkspacePickerInjected = DirectoryPickingInjected & {
+    /** Adopt a picked host directory as a real Workspace before targeting a Session. */
+    createWorkspace: (input: {
+        path: string;
+    }) => Promise<WorkspaceView>;
+};
+/**
+ * Full picker props: the owner share plus the creation callback and the
+ * locale seat. The two picker holes (blank-session hero / New-Session view)
+ * share one owner currency, so one composed type serves both registrations.
+ */
+export type WorkspacePickerProps = PropsRuntime<'conversation.hero.workspace'> & PropsRenderSlots<'conversation.hero.workspace.directoryFlow'> & Omit<WorkspacePickerInjected, 'hooks'> & DirectoryPickingHooks & PropsLocale<'workspace'>;
+//# sourceMappingURL=slots.d.ts.map

package/lib/types/client/index.d.ts

@@ -0,0 +1,27 @@
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+import { type WorkspaceKey } from './locales.ts';
+export type { DirectoryFlowOwnerProps, DirectoryFlowSlotName, DirectoryPickingHooks, DirectoryPickingInjected, WorkspaceBrowserInjected, WorkspaceBrowserProps, WorkspacePickerInjected, WorkspacePickerProps, } from './contract/slots.ts';
+export type { WorkspaceKey } from './locales.ts';
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** The workspace browsing region and pick/create flow copy. */
+        workspace: WorkspaceKey;
+    }
+}
+/**
+ * Required services (cordis fiber inject). The target slots are declared by
+ * the ui-sidebar / ui-conversation applies, whose activation order relative
+ * to this one is NOT constrained: dsh.client.inject edges are informational
+ * (loading/prefetch metadata, never apply sequencing) and neither owner
+ * provides a waitable service. apply therefore depends on each slot
+ * declaration through `slots.inject()` instead of assuming order.
+ */
+export declare const inject: string[];
+/**
+ * Register the browser and picker once their slot declarations are on the
+ * ledger. Inject factories return plain callbacks; data reads use the
+ * framework's global hooks.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: ClientContext): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/locales.d.ts

@@ -0,0 +1,126 @@
+/**
+ * `workspace` namespace dictionaries: the browsing region (section header,
+ * search, tree rows, dialogs) and the pick/add flow. Runtime failure
+ * messages (wire error strings) pass through untranslated by policy.
+ */
+/** Simplified Chinese dictionary (the key-set source of truth). */
+export declare const zh: {
+    'group.ungrouped': string;
+    'session.new': string;
+    'section.workspaces': string;
+    'section.sessions': string;
+    'groupBy.label': string;
+    'groupBy.workspace': string;
+    'groupBy.flat': string;
+    'empty.none': string;
+    'empty.noMatches': string;
+    'workspace.add': string;
+    'search.sessions.aria': string;
+    'search.placeholder': string;
+    'search.clear': string;
+    'search.results.aria': string;
+    'search.pending': string;
+    'search.unavailable': string;
+    'search.noMatches': string;
+    'search.hasMore': string;
+    'menu.addWorkspace': string;
+    'picker.loading': string;
+    'conflict.named': string;
+    'folderError.title': string;
+    'folderError.retry': string;
+    rename: string;
+    'rename.workspace.title': string;
+    'rename.session.title': string;
+    'field.workspaceName': string;
+    'field.sessionName': string;
+    'delete.workspace': string;
+    'delete.desc': string;
+    'delete.pending': string;
+    'menu.fork': string;
+    'menu.archiveSession': string;
+    'sessions.count.one': string;
+    'sessions.count.other': string;
+    'actions.workspace.aria': string;
+    'actions.session.aria': string;
+    'actions.newSession.aria': string;
+    'status.running': string;
+    'status.subagentsRunning.one': string;
+    'status.subagentsRunning.other': string;
+    'status.idle': string;
+    'status.waitingApproval': string;
+    'status.planReview': string;
+    'status.waitingAnswer': string;
+    'status.completed': string;
+    'hover.created': string;
+    'hover.copied': string;
+    'date.ymd': string;
+    'time.now': string;
+    'time.minutes': string;
+    'time.hours': string;
+    'time.days': string;
+    'time.months': string;
+    'time.years': string;
+    'time.ago': string;
+};
+/** The workspace namespace key union. */
+export type WorkspaceKey = keyof typeof zh;
+/** English dictionary, checked complete against the zh key set. */
+export declare const en: {
+    'group.ungrouped': string;
+    'session.new': string;
+    'section.workspaces': string;
+    'section.sessions': string;
+    'groupBy.label': string;
+    'groupBy.workspace': string;
+    'groupBy.flat': string;
+    'empty.none': string;
+    'empty.noMatches': string;
+    'workspace.add': string;
+    'search.sessions.aria': string;
+    'search.placeholder': string;
+    'search.clear': string;
+    'search.results.aria': string;
+    'search.pending': string;
+    'search.unavailable': string;
+    'search.noMatches': string;
+    'search.hasMore': string;
+    'menu.addWorkspace': string;
+    'picker.loading': string;
+    'conflict.named': string;
+    'folderError.title': string;
+    'folderError.retry': string;
+    rename: string;
+    'rename.workspace.title': string;
+    'rename.session.title': string;
+    'field.workspaceName': string;
+    'field.sessionName': string;
+    'delete.workspace': string;
+    'delete.desc': string;
+    'delete.pending': string;
+    'menu.fork': string;
+    'menu.archiveSession': string;
+    'sessions.count.one': string;
+    'sessions.count.other': string;
+    'actions.workspace.aria': string;
+    'actions.session.aria': string;
+    'actions.newSession.aria': string;
+    'status.running': string;
+    'status.subagentsRunning.one': string;
+    'status.subagentsRunning.other': string;
+    'status.idle': string;
+    'status.waitingApproval': string;
+    'status.planReview': string;
+    'status.waitingAnswer': string;
+    'status.completed': string;
+    'hover.created': string;
+    'hover.copied': string;
+    'date.ymd': string;
+    'time.now': string;
+    'time.minutes': string;
+    'time.hours': string;
+    'time.days': string;
+    'time.months': string;
+    'time.years': string;
+    'time.ago': string;
+};
+//# sourceMappingURL=locales.d.ts.map

package/lib/types/client/rows/Rows.d.ts

@@ -0,0 +1,90 @@
+import type { WorkspaceBrowserProps } from '../contract/slots.ts';
+import type { GroupNode, SearchResultNode, SessionNode } from '../tree.ts';
+/** The standard locale seat, prop-passed from the browser root. */
+type RowTranslate = WorkspaceBrowserProps['t'];
+/**
+ * Project (workspace) header row: 54px, folder + title + session count;
+ * hover reveals the chevron and create button, and dwelling on a real
+ * Workspace shows its hover card (the ungrouped bucket has none).
+ * `containsCurrent` arrives on the node (derivation fact, no renderer scan).
+ * @param props.group - derived group node.
+ * @param props.onToggle - expand/collapse the group.
+ * @param props.onCreate - start a frontend Session inside this Workspace.
+ * @param props.t - the browser root's locale seat.
+ * @returns the row element.
+ */
+export declare function ProjectRowItem({ group, onToggle, onCreate, actions, t }: {
+    group: GroupNode;
+    onToggle: () => void;
+    onCreate: () => void;
+    /** Real-Workspace actions; absent for the ungrouped bucket (no menu shown). */
+    actions?: {
+        rename: () => void;
+        delete: () => void;
+    } | undefined;
+    t: RowTranslate;
+}): import("react").JSX.Element;
+/**
+ * Session-row drag wiring supplied by the group owner (workspace groups only).
+ * `drop` reports the half of the row the pointer released on: 'before'
+ * inserts above this row, 'after' below it (the owner resolves the anchor).
+ */
+export interface RowDragProps {
+    /** Start dragging this row. */
+    start: () => void;
+    /** A drag from the same group is in flight (rows show insert markers). */
+    active: boolean;
+    /** Current marker on this row: insert line above, below, or none. */
+    marker: 'before' | 'after' | null;
+    /** Report the hovered half while a same-group drag passes over this row. */
+    hover: (half: 'before' | 'after') => void;
+    drop: (half: 'before' | 'after') => void;
+    end: () => void;
+}
+/**
+ * One flat search result: title, Workspace context, and optional content
+ * excerpt. Search navigation opens the session only; it does not address an
+ * event inside the conversation.
+ * @param props.result - merged local/content search row.
+ * @param props.currentId - selected session id.
+ * @param props.onOpen - open the selected session.
+ * @param props.t - Workspace-browser translation seat.
+ * @returns the result button.
+ */
+export declare function SearchResultItem({ result, currentId, onOpen, t }: {
+    result: SearchResultNode;
+    currentId: string | undefined;
+    onOpen: (id: SearchResultNode['id']) => void;
+    t: RowTranslate;
+}): import("react").JSX.Element;
+/**
+ * One top-level 34px session row: status dot (pending user interaction outranks
+ * own or descendant activity), title, relative time, and the row actions menu.
+ * @param props.node - derived session node.
+ * @param props.currentId - selected session id (row highlight).
+ * @param props.now - epoch ms for relative-time formatting.
+ * @param props.onOpen - open a session by id.
+ * @param props.onRename - open the session rename dialog (id + current title).
+ * @param props.onFork - fork a session at its last completed turn.
+ * @param props.onArchive - archive a session by id.
+ * @param props.drag - optional draggable-row wiring.
+ * @param props.t - the browser root's locale seat.
+ * @returns the session row.
+ */
+export declare function SessionNodeItem({ node, currentId, now, onOpen, onRename, onFork, onArchive, drag, t }: {
+    node: SessionNode;
+    currentId: string | undefined;
+    now: number;
+    onOpen: (id: SessionNode['id']) => void;
+    /** Open the browser-owned session rename dialog (row menu action). */
+    onRename: (id: SessionNode['id'], currentTitle: string) => void;
+    /** Fork a session at its last completed turn (row menu action). */
+    onFork: (id: SessionNode['id']) => void;
+    /** Archive this session (row menu action; commits without a dialog). */
+    onArchive: (id: SessionNode['id']) => void;
+    /** Present only on draggable rows (workspace-group sessions outside search). */
+    drag?: RowDragProps | undefined;
+    t: RowTranslate;
+}): import("react").JSX.Element;
+export {};
+//# sourceMappingURL=Rows.d.ts.map

package/lib/types/client/stores.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The workspace browser's viewing store: the session-list grouping mode,
+ * persisted across reloads. Module level exports the factory only (a
+ * module-level handle would pin the store identity across plugin reloads);
+ * register() receives the factory and the browser derives its PropsStore
+ * share from the return type.
+ */
+import { type EngineStoreHandle } from '@deepseek-ai/dsh-client-runtime/client';
+/** Session-list grouping mode: workspace sections or one flat recency list. */
+export type WorkspaceGroupBy = 'workspace' | 'flat';
+/** Workspace browser viewing state (grouping mode only; transient UI facts stay component-local). */
+type WorkspaceViewState = {
+    groupBy: WorkspaceGroupBy;
+};
+/**
+ * Annotation twin of the actions literal below (the export needs a declared
+ * return type); drift fails assignability at the defineStore call.
+ */
+type WorkspaceViewActions = {
+    setGroupBy: (draft: WorkspaceViewState, mode: WorkspaceGroupBy) => void;
+};
+/**
+ * Create the workspace browser viewing store handle.
+ * @returns the store handle (spec + type + identity + factory in one).
+ */
+export declare function createWorkspaceViewStore(): EngineStoreHandle<WorkspaceViewState, WorkspaceViewActions>;
+export {};
+//# sourceMappingURL=stores.d.ts.map

package/lib/types/client/tree.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Derives the workspace browser tree from Host Workspace order and membership.
+ * Unassigned Sessions trail under Ungrouped; only the selected blank Session
+ * remains visible.
+ */
+import { type PendingInteractionStatus, type SessionId, type SessionListState, type SessionSearchResultItem, type WorkspaceId, type WorkspaceView } from '@deepseek-ai/dsh-client-runtime/client';
+/** Group key for Sessions outside every Workspace. */
+export declare const UNGROUPED_KEY = "";
+/** Display label for the ungrouped bucket row. */
+export declare const UNGROUPED_LABEL = "Ungrouped";
+/** One top-level session row in a group or the flat list. */
+export interface SessionNode {
+    id: SessionId;
+    /** Stored display title; the renderer substitutes the localized New Session label for blank rows. */
+    title: string;
+    /** The provisional blank session (renderer shows the localized New Session title). */
+    blank: boolean;
+    /** The runtime Session list reports an interaction awaiting this user. */
+    pendingInteraction?: PendingInteractionStatus;
+    running: boolean;
+    /** Running descendants connected through uninterrupted subagent-origin lineage. */
+    runningSubagentCount: number;
+    /** Finished running while not selected and not yet opened (the green "done" reminder dot). */
+    completed: boolean;
+    updatedAt: number;
+}
+/** One workspace group section: header row facts + visible top-level session rows. */
+export interface GroupNode {
+    /** Group key: the workspace id or {@link UNGROUPED_KEY}. */
+    key: string;
+    /** Backing Workspace id; absent only for the ungrouped bucket. */
+    workspaceId: WorkspaceId | undefined;
+    cwd: string | undefined;
+    /** Workspace creation time (epoch ms); absent only for the ungrouped bucket. */
+    createdAt: number | undefined;
+    label: string;
+    /** Total visible sessions in the group. */
+    sessionCount: number;
+    expanded: boolean;
+    /** The group contains the selected session (active folder tint; supplied here so the renderer never scans). */
+    containsCurrent: boolean;
+    /** Visible session rows (empty while the group is folded). */
+    sessions: readonly SessionNode[];
+}
+/** One flat search row combining list metadata with an optional content match. */
+export interface SearchResultNode {
+    id: SessionId;
+    title: string;
+    workspace: string;
+    /** The runtime Session list reports an interaction awaiting this user. */
+    pendingInteraction?: PendingInteractionStatus;
+    running: boolean;
+    /** Running descendants connected through uninterrupted subagent-origin lineage. */
+    runningSubagentCount: number;
+    /** Finished running while not selected and not yet opened (the green "done" reminder dot). */
+    completed: boolean;
+    snippet?: string;
+}
+/** Bounded merged search projection plus the refine-query hint bit. */
+export interface SearchResultSet {
+    items: readonly SearchResultNode[];
+    hasMore: boolean;
+}
+/** Viewing state consumed by the derivation. */
+export interface TreeView {
+    expandedProjects: readonly string[];
+}
+/**
+ * Directory display label: basename of the path (both separators accepted).
+ * Ungrouped-bucket fallback for surfaces without a workspace title.
+ * @param cwd - directory path, or undefined for the ungrouped bucket.
+ * @returns basename, the raw cwd when it has no basename, or the ungrouped label.
+ */
+export declare function projectLabel(cwd: string | undefined): string;
+/**
+ * Derive the workspace browser groups with every session as a top-level row.
+ *
+ * Every group shows; sessions populate under expanded groups, preserving
+ * Host account order. Blank sessions are excluded except for the selected
+ * provisional New Session row; archived sessions are excluded everywhere.
+ * Content search lives outside this derivation
+ * (see {@link deriveSearchResults}).
+ * @param list - sessions list snapshot (`current` feeds containsCurrent).
+ * @param workspaces - real workspaces in stable Host order.
+ * @param archivedSessionIds - registry-global archive set.
+ * @param view - local expansion arrays.
+ * @returns group sections in render order.
+ */
+export declare function deriveGroups(list: SessionListState, workspaces: readonly WorkspaceView[], archivedSessionIds: readonly SessionId[], view: TreeView): GroupNode[];
+/**
+ * Derive the flat session list ("In one list" mode): every session — fork
+ * children included — as a top-level row, strictly newest-first. No grouping,
+ * no parent/child adjacency. Content search lives outside this derivation
+ * (see {@link deriveSearchResults}).
+ * @param list - sessions list snapshot.
+ * @param archivedSessionIds - registry-global archive set.
+ * @returns flat rows in render order.
+ */
+export declare function deriveFlat(list: SessionListState, archivedSessionIds: readonly SessionId[]): SessionNode[];
+/** Relative-time bucket of a session row's trailing label. */
+export type RelativeTimeUnit = 'now' | 'minutes' | 'hours' | 'days' | 'months' | 'years';
+/** Structured relative time: the bucket plus its magnitude (0 for 'now'). */
+export interface RelativeTime {
+    unit: RelativeTimeUnit;
+    n: number;
+}
+/**
+ * Merge immediate title/Workspace substring matches with ranked Host content
+ * matches. Local rows lead newest-first, content-only rows retain backend
+ * order, and duplicate sessions receive the backend snippet in place.
+ * @param list - session metadata authority.
+ * @param workspaces - Workspace membership and display labels.
+ * @param query - caller text; surrounding whitespace is ignored.
+ * @param archivedSessionIds - registry-global archive set (members never match).
+ * @param content - ranked Host content-search page.
+ * @param limit - protocol-owned maximum merged row count.
+ * @returns bounded deduplicated flat rows and a refine-query hint bit.
+ */
+export declare function deriveSearchResults(list: SessionListState, workspaces: readonly WorkspaceView[], query: string, archivedSessionIds: readonly SessionId[], content: {
+    items: readonly SessionSearchResultItem[];
+    hasMore: boolean;
+}, limit: number): SearchResultSet;
+/**
+ * Compact relative time for session rows, as a structured bucket the
+ * renderer localizes ("now"/"5min"/"3h"/"2d"/"4mo"/"1y" in en).
+ * @param updatedAt - epoch ms of the session's last activity.
+ * @param now - current epoch ms (injected for pure rendering).
+ * @returns the row's trailing time bucket and magnitude.
+ */
+export declare function relativeTime(updatedAt: number, now: number): RelativeTime;
+//# sourceMappingURL=tree.d.ts.map