dsh-over-ssh 0.0.0-stage → 0.1.0

package/lib/types/src/client/flows/workspace-directory-flow.d.ts

@@ -0,0 +1,480 @@
+/**
+ * The **directory-flow occupant**: "add a local or remote directory to a workspace".
+ *
+ * Both workspace surfaces of the platform declare one `single` hole  - `sidebar.workspaces.directoryFlow` and
+ * `conversation.hero.workspace.directoryFlow`  - and each renders its "add workspace" action **only while that
+ * hole is occupied** (a composition without a picker has no such action at all). This module fills both holes
+ * with one dialog offering two entries:
+ *
+ *  - **local**: the platform's own chooser (`ctx.uiWorkspace.pickDirectory()`); the absolute path it answers
+ *    is handed straight back through `onPicked`;
+ *  - **remote**: a connection plus a remote path, POSTed to this plugin's own route (`add-root`); the host
+ *    answers with the **anchor path** it registered for that root, and *that* path is what goes back through
+ *    `onPicked`. The platform creates a workspace on a **host path**, and the router resolves a path under
+ *    the anchor back to the remote root (`doc/02-platform/roots-http-route.md`), so the anchor  - not the
+ *    remote path  - is the only answer that puts a remote directory in a workspace.
+ *
+ * Three layers, mirroring `roots-panel-view.ts`:
+ *
+ *  1. {@link workspaceDirectoryFlowReducer}  - a pure state machine over the dialog's drafts, the connection
+ *     list and the owner conversation. No DOM, no I/O, no React.
+ *  2. {@link createWorkspaceDirectoryFlow}  - the same state plus the injected calls, the owner conversation
+ *     and the **one result per open** gate.
+ *  3. {@link WorkspaceDirectoryFlowSection}  - a pure template (`createElement`, never JSX: Node's native type
+ *     stripping cannot transform JSX) and {@link WorkspaceDirectoryFlowContainer}, the thin React shell.
+ *
+ * Each entry also embeds the shared **directory browser** (`./directory-browser.ts`), so a path can be found
+ * by looking instead of typed from memory: both worlds come from this plugin's own read-only route
+ * (`list-local` / `list-remote`), never from the platform's `uiWorkspace.listDirectory()` — that call needs
+ * the directory-picker's `browse` capability and fails outright in a composition whose picker serves only the
+ * native dialog (see `doc/02-platform/roots-http-route.md` §2). `browse` in the state says which of the two
+ * browsers is open (never both: two listing panels in a ~260px column would each get half the height for no
+ * gain).
+ *
+ * Rules this file is responsible for:
+ *
+ *  - **Exactly one outcome per open.** The owner contract says so; {@link canReport} is the single gate, and
+ *    a settlement that arrives after the owner withdrew `open` (or after an earlier settlement) is dropped
+ *    rather than reported.
+ *  - **No submission while `busy`.** The owner is adopting a path; every commit affordance is disabled and
+ *    every handler re-checks the gate, so a double submit is impossible even if a caller bypasses the view.
+ *  - **Nothing is POSTed before validation.** `validateRootDraft` (the same authority the settings panel
+ *    uses) is the only way a draft becomes a request, and its refusal is rendered through the dictionaries.
+ *  - **No credentials.** The connection list comes from `parseRootsSnapshot`, which copies field by field.
+ *  - **The card is portalled, and it has to be.** `sidebar.workspaces.directoryFlow` renders *inside the
+ *    sidebar's title row* - a flex row that clips its overflow - so a card rendered in place is a flex item
+ *    that gets shrunk to almost nothing (`max-width: 100%` does not stop flex shrinking and the row never
+ *    wraps). The release before this one shipped exactly that and the user photographed the result: a
+ *    vertical strip with a clipped hint. `./portal.ts` therefore attaches one container to `document.body`
+ *    while the interaction is open, and the card lives in it with `position: fixed`. The **internals** stay
+ *    narrow-first: one column by default, every cell capped at the container, committing buttons on their own
+ *    row, no pixel widths, and the two-column shape only ever added by the card's own `@container` query.
+ *
+ * **Unverified** (see `doc/02-platform/workspace-directory-flow.md`): the portal has not been looked at in a
+ * real GUI, and it is not verified that the host accepts an anchor path as a workspace path.
+ *
+ * @module dsh-over-ssh/client/workspace-directory-flow
+ */
+import { type ReactNode } from 'react';
+import { type DirectoryBrowserIo } from './directory-browser.ts';
+import type { OverSshKey } from '../core/locale.ts';
+import { type CardPortalTarget } from '../core/portal.ts';
+import { type ApiResult, type ConnectionSummary, type FetchLike, type MessageKey } from '../roots/roots-panel.ts';
+import { type RootsPanelCopy } from '../roots/roots-panel-view.ts';
+/**
+ * The owner share of both directory-flow holes, quoted from the platform (`DirectoryFlowOwnerProps` in
+ * `@deepseek-ai/dsh-client-ui-workspace/client`, `packages/client/ui-workspace/src/client/contract/slots.ts`).
+ *
+ * Mirrored instead of imported: that package is not a dependency of this repository (its types are only in
+ * the DSH checkout), and the merge below has to compile here.
+ */
+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. */
+        'conversation.hero.workspace.directoryFlow': {
+            kind: 'single';
+            scope: 'root';
+            owner: DirectoryFlowOwnerProps;
+        };
+        /** Directory-flow hole under the sidebar browsing region. */
+        'sidebar.workspaces.directoryFlow': {
+            kind: 'single';
+            scope: 'root';
+            owner: DirectoryFlowOwnerProps;
+        };
+    }
+}
+/** The two holes, in registration order; one occupant fills both. */
+export declare const WORKSPACE_DIRECTORY_FLOW_SLOTS: readonly ["sidebar.workspaces.directoryFlow", "conversation.hero.workspace.directoryFlow"];
+/** One of the two holes. */
+export type WorkspaceDirectoryFlowSlotName = (typeof WORKSPACE_DIRECTORY_FLOW_SLOTS)[number];
+/**
+ * Shadowing rank of this occupant inside the single-cell hole.
+ *
+ * A `single` slot holds one entry **per priority**: a second registration at the same priority throws
+ * (`SlotCore.register`), while a different priority shadows. The platform ships a picker for this hole
+ * (`ui-directory-picker-native` / `-browse`) whose profile row mounts it at the default priority 0, so a
+ * plain registration would throw  - or, worse, fail the whole client half  - in exactly the compositions that
+ * already have a picker. `-1` renders lower (ascending: lowest renders) and therefore replaces the shipped
+ * picker instead of colliding with it. The local entry below still reaches the same platform chooser.
+ */
+export declare const WORKSPACE_DIRECTORY_FLOW_PRIORITY = -1;
+/** The error {@link WorkspaceDirectoryFlowIo.addRemoteRoot} answers when the host did not report an anchor. */
+export declare const NO_ANCHOR_ERROR = "no-anchor-path";
+/**
+ * Classes of the body-level container this dialog's card is portalled into: the floating shell
+ * (`CLASS.portal`) plus the dialog's placement (`CLASS.portalTop`, centred below the top of the window).
+ *
+ * The container is created by {@link WorkspaceDirectoryFlowContainer} from `./portal.ts`; the template only
+ * receives it. Its width (`min(26rem, calc(100vw - 2rem))`) is what the card's own `@container` query measures.
+ */
+export declare const WORKSPACE_DIRECTORY_FLOW_PORTAL_CLASS: string;
+/** The dialog's click sink: the sidebar dialog is modal, so the title row behind it is not clickable through the gap. */
+export declare const WORKSPACE_DIRECTORY_FLOW_BACKDROP_CLASS: "dsh-rw-backdrop";
+/** The dialog heading's `id` when the shell did not pass a per-mount one (direct template calls, tests). */
+export declare const WORKSPACE_DIRECTORY_FLOW_TITLE_ID = "dsh-rw-flow-title";
+/** One shipped dictionary of this plugin's namespace, as the template consumes it. */
+export type WorkspaceDirectoryFlowCopy = RootsPanelCopy;
+/** The remote form's contents. Flat, so a patch is one spread and a test can name a single field. */
+export interface WorkspaceDirectoryFlowDrafts {
+    /** Connection the remote root belongs to. */
+    readonly connectionId: string;
+    /** Remote path as typed; validated by the controller so a bad value is refused, not coerced. */
+    readonly path: string;
+}
+/** A change to the drafts; every field is optional so one handler can serve every input. */
+export type WorkspaceDirectoryFlowDraftPatch = Partial<WorkspaceDirectoryFlowDrafts>;
+/** Everything the dialog renders from. */
+export interface WorkspaceDirectoryFlowState {
+    /** The owner's `open`, as last synced. */
+    readonly open: boolean;
+    /** The owner's `busy`, as last synced. */
+    readonly busy: boolean;
+    /** Bumped on every rising `open` edge; every call and every settlement is addressed by it. */
+    readonly generation: number;
+    /** True once this generation reported its one outcome (or the owner withdrew the request). */
+    readonly settled: boolean;
+    /** True while one of the flow's own calls is in flight. */
+    readonly pending: boolean;
+    /** The connections the remote form offers. */
+    readonly connections: readonly ConnectionSummary[];
+    /** True while the connection list is being read (the first read of an open, or a retry). */
+    readonly connectionsLoading: boolean;
+    /** The last connection-list failure, kept so the window can be re-opened without a stale list. */
+    readonly connectionsError?: string;
+    /** The remote form's contents. */
+    readonly drafts: WorkspaceDirectoryFlowDrafts;
+    /** Which world the operator is adding a directory from. Only that world's block is rendered. */
+    readonly mode: WorkspaceDirectoryFlowMode;
+    /** The embedded remote browser; `'none'` while it is closed. */
+    readonly browse: WorkspaceDirectoryFlowBrowse;
+    /** The last refusal or call failure, rendered through the dictionaries. */
+    readonly notice?: MessageKey;
+}
+/**
+ * Which world this dialog is adding from.
+ *
+ * The two entries used to be shown together with one commit button each, which read as two competing ways to
+ * add a directory. The dialog now asks **first**: the operator picks local or remote, and only that block is
+ * rendered. Both blocks still end in the same single owner report (`onPicked`).
+ */
+export type WorkspaceDirectoryFlowMode = 'local' | 'remote';
+/**
+ * Which embedded browser is open.
+ *
+ * Only the **remote** block embeds one: local picking goes through the platform's native chooser (audit 0071),
+ * so `'local'` no longer exists. `'none'` is the state a fresh open starts in.
+ */
+export type WorkspaceDirectoryFlowBrowse = 'none' | 'remote';
+/** What the reducer accepts. */
+export type WorkspaceDirectoryFlowAction = 
+/** The owner asked for the interaction (an edge: `open` false -> true). */
+{
+    readonly type: 'opened';
+}
+/** The owner withdrew the request without an outcome; nothing may be reported for that generation. */
+ | {
+    readonly type: 'withdrawn';
+}
+/** The owner's adoption flag moved. */
+ | {
+    readonly type: 'busy-changed';
+    readonly busy: boolean;
+}
+/** A connection-list read started (the first read of an open, or a retry). */
+ | {
+    readonly type: 'connections-loading';
+}
+/** The connection list arrived. */
+ | {
+    readonly type: 'connections-loaded';
+    readonly connections: readonly ConnectionSummary[];
+}
+/** The connection list failed. */
+ | {
+    readonly type: 'connections-failed';
+    readonly error: string;
+}
+/** One draft field changed: clears the inline message, because the user is fixing it. */
+ | {
+    readonly type: 'draft-changed';
+    readonly patch: WorkspaceDirectoryFlowDraftPatch;
+}
+/** The operator switched between adding a local and a remote directory. */
+ | {
+    readonly type: 'mode-changed';
+    readonly mode: WorkspaceDirectoryFlowMode;
+}
+/** The embedded remote browser was opened or closed. */
+ | {
+    readonly type: 'browse-toggled';
+    readonly browse: WorkspaceDirectoryFlowBrowse;
+}
+/** A call is in flight; the reducer itself refuses it when the gate is closed. */
+ | {
+    readonly type: 'submitted';
+}
+/** A draft was refused before any call; nothing was sent. */
+ | {
+    readonly type: 'refused';
+    readonly message: MessageKey;
+}
+/** One outcome was reported to the owner. */
+ | {
+    readonly type: 'settled';
+}
+/** The native chooser was dismissed: the dialog stays open and usable, nothing is reported. */
+ | {
+    readonly type: 'pick-cancelled';
+}
+/** Reporting threw before the owner adopted; the dialog must become usable again. */
+ | {
+    readonly type: 'report-failed';
+};
+/** The empty remote form. */
+export declare function emptyWorkspaceDirectoryFlowDrafts(): WorkspaceDirectoryFlowDrafts;
+/** @returns the state a freshly created flow holds. */
+export declare function initialWorkspaceDirectoryFlowState(): WorkspaceDirectoryFlowState;
+/**
+ * The dialog's state machine. Pure: same state + same action => same result, and an action that changes
+ * nothing returns the **same object**, so a subscriber is never woken for a no-op.
+ *
+ * @param state - the current state.
+ * @param action - what happened.
+ * @returns the next state.
+ */
+export declare function workspaceDirectoryFlowReducer(state: WorkspaceDirectoryFlowState, action: WorkspaceDirectoryFlowAction): WorkspaceDirectoryFlowState;
+/** The dialog's complete render input. */
+export interface WorkspaceDirectoryFlowView {
+    /** True while the owner asks for the interaction. */
+    readonly visible: boolean;
+    /** True while one of the flow's own calls is in flight. */
+    readonly pending: boolean;
+    /** True while the owner adopts a picked path. */
+    readonly busy: boolean;
+    /** True once this generation reported its outcome. */
+    readonly settled: boolean;
+    /** Which world is being added from; only that block is rendered. */
+    readonly mode: WorkspaceDirectoryFlowMode;
+    /** May the interaction be driven (mode switch, local browser, remote form)? */
+    readonly canPickLocal: boolean;
+    /** May the remote form be submitted? */
+    readonly canSubmitRemote: boolean;
+    /** May the interaction be dismissed? (Never while the owner is adopting.) */
+    readonly canCancel: boolean;
+    /** The connections the remote form offers. */
+    readonly connections: readonly ConnectionSummary[];
+    /** True while the connection list is being read. */
+    readonly connectionsLoading: boolean;
+    /** Which embedded browser is open. */
+    readonly browse: WorkspaceDirectoryFlowBrowse;
+    /** The last refusal or call failure. */
+    readonly notice?: MessageKey;
+    /** The last connection-list failure. */
+    readonly connectionsError?: string;
+}
+/**
+ * Turn the state into render input.
+ *
+ * @param state - the flow state.
+ * @returns the visible flags, the connection list, the browse mode, the messages and the three gates.
+ */
+export declare function selectWorkspaceDirectoryFlowView(state: WorkspaceDirectoryFlowState): WorkspaceDirectoryFlowView;
+/** True when the interaction may still be driven: open, not adopting, no call in flight, nothing reported. */
+export declare function canPickLocal(state: WorkspaceDirectoryFlowState): boolean;
+/** True when the remote form is complete enough to submit (the path rules are checked on submit). */
+export declare function canSubmitRemote(state: WorkspaceDirectoryFlowState): boolean;
+/**
+ * True when `cancel()` may report the dismissal.
+ *
+ * A request in flight (`pending`) is not cancellable either: the host may already have written the root (or
+ * the chooser may already have answered), and a dismissal reported at that moment would leave a root the
+ * owner never hears about. The late answer is dropped by {@link canReport} instead, so the caller always
+ * settles exactly once — which is why the race cannot happen at all rather than being repaired afterwards.
+ */
+export declare function canCancel(state: WorkspaceDirectoryFlowState): boolean;
+/**
+ * True when a settlement may still be reported to the owner: this generation is open and nothing was
+ * reported for it yet. The one gate behind the owner contract's "exactly one outcome per open".
+ *
+ * @param state - the flow state.
+ * @returns whether a result may be reported now.
+ */
+export declare function canReport(state: WorkspaceDirectoryFlowState): boolean;
+/**
+ * The calls the flow makes. All of them are injected, so the state machine is testable offline
+ * (红线 3) and no test starts a server or opens a chooser.
+ *
+ * The browser's calls are part of the same face ({@link DirectoryBrowserIo}): both worlds embed the same
+ * browser, and giving it a second injection path would mean two places to keep the route, the credentials
+ * filter and the failure vocabulary identical.
+ */
+export interface WorkspaceDirectoryFlowIo extends DirectoryBrowserIo {
+    /**
+     * Open the platform's **native** directory chooser and answer the absolute path the operator picked, or
+     * `null` when they dismissed it. This is the local block's one entry (audit 0071): the OS dialog is what
+     * users mean by「浏览目录」, and it can reach drives the embedded browser cannot.
+     */
+    pickDirectory(): Promise<string | null>;
+    /**
+     * Add one remote root and answer the **anchor path** the host registered for it.
+     * `{ ok: false, error: NO_ANCHOR_ERROR }` means the host answered without one, which is not a path the
+     * owner may create a workspace on.
+     */
+    addRemoteRoot(input: {
+        readonly connectionId: string;
+        readonly path: string;
+    }): Promise<ApiResult<string>>;
+}
+/**
+ * Bind the flow's calls to the browser and the platform.
+ *
+ * The connection list and both listings come from {@link createDirectoryBrowserIo}, i.e. from the plugin's
+ * own `GET` and its own `list-local` / `list-remote` actions; `addRemoteRoot` posts the same `add-root` body
+ * the settings panel posts, but reads the answer's `anchorPath`, which the snapshot projection drops because
+ * it belongs to the *live* root, not to the persisted entry.
+ *
+ * @param options - `fetch` (same-origin in the app) and a route override.
+ * @returns the calls the flow uses.
+ */
+export declare function createWorkspaceDirectoryFlowIo(options: {
+    readonly fetchImpl: FetchLike;
+    readonly path?: string;
+    /** The platform's native chooser; the entry (`index.ts`) reads it from `uiWorkspace` lazily. */
+    readonly pickDirectory: () => Promise<string | null>;
+}): WorkspaceDirectoryFlowIo;
+/**
+ * What the stateful half needs: the injected calls plus the active dictionary, read at report time.
+ *
+ * The dialog deliberately has **no session-mode seam** (0069): the session this flow starts runs the Host's
+ * new-task default, which the platform's own Settings → Agent Preset page controls for every new session. A
+ * per-workspace preset choice was a fragile, silently-failing duplicate of that global setting.
+ */
+export interface WorkspaceDirectoryFlowDeps {
+    readonly io: WorkspaceDirectoryFlowIo;
+    /** The dictionary of the active locale. A thunk, because `onError` needs text and the locale can change. */
+    readonly copy: () => WorkspaceDirectoryFlowCopy;
+}
+/** The calls the container makes. `createWorkspaceDirectoryFlow` owns how they are implemented. */
+export interface WorkspaceDirectoryFlowController {
+    /** The current state; a stable reference until something changes (safe for `useSyncExternalStore`). */
+    readonly getState: () => WorkspaceDirectoryFlowState;
+    /** Watch for changes; returns the disposer. */
+    readonly subscribe: (listener: () => void) => () => void;
+    /** Push the owner's current conversation in; called by the shell on every render. */
+    readonly syncOwner: (props: DirectoryFlowOwnerProps) => void;
+    /** Change one draft field. */
+    readonly changeDraft: (patch: WorkspaceDirectoryFlowDraftPatch) => void;
+    /** Switch between adding a local and a remote directory (only the selected block is rendered). */
+    readonly changeMode: (mode: WorkspaceDirectoryFlowMode) => void;
+    /** Validate the remote form, add the root and report its anchor path. */
+    readonly submitRemote: () => Promise<void>;
+    /** Re-read the connection list while the dialog stays open (the inline retry). */
+    readonly reloadConnections: () => void;
+    /** Report the operator's dismissal. */
+    readonly cancel: () => void;
+    /** Open or close the embedded remote browser. */
+    readonly toggleBrowse: (browse: WorkspaceDirectoryFlowBrowse) => void;
+    /** Open the platform's native chooser; its answer is validated and reported exactly like any other pick. */
+    readonly pickLocal: () => Promise<void>;
+    /** Adopt an already-absolute local path (the chooser's answer without the chooser: tests and fallbacks). */
+    readonly browseLocal: (path: string) => void;
+    /** Adopt a directory picked in the remote browser: fill the draft from it, then add the root. */
+    readonly browseRemote: (path: string, connectionId: string | undefined) => void;
+    /** Re-arm after a mount (React's development replay runs the cleanup once per lifetime). */
+    readonly activate: () => void;
+    /** Stop accepting results and drop listeners. */
+    readonly dispose: () => void;
+}
+/**
+ * Build the stateful half of the directory flow.
+ *
+ * The one gate that matters lives here: {@link canReport} is consulted **before** the owner is told anything,
+ * so a call that settles after the owner withdrew `open`  - or a second settlement racing the first  - is
+ * dropped instead of driving `onPicked` / `onCancel` / `onError` twice.
+ *
+ * @param deps - the injected calls and the active dictionary.
+ * @returns the controller the container subscribes to.
+ */
+export declare function createWorkspaceDirectoryFlow(deps: WorkspaceDirectoryFlowDeps): WorkspaceDirectoryFlowController;
+/** What the dialog's controls call. All of them are no-ops when the gate is closed. */
+export interface WorkspaceDirectoryFlowSectionActions {
+    readonly onDraftChange: (patch: WorkspaceDirectoryFlowDraftPatch) => void;
+    /** The world switch moved (local or remote). */
+    readonly onWorldChange: (mode: WorkspaceDirectoryFlowMode) => void;
+    readonly onSubmitRemote: () => void;
+    /** Re-read the connection list after an inline failure. */
+    readonly onReloadConnections: () => void;
+    readonly onCancel: () => void;
+    /** Open or close the embedded remote browser. */
+    readonly onBrowseToggle: (browse: WorkspaceDirectoryFlowBrowse) => void;
+    /** Open the platform's native folder chooser; its answer is adopted as the workspace path. */
+    readonly onPickLocal: () => void;
+    /** A directory was picked in the remote browser: fill the path field, then let the form submit. */
+    readonly onBrowseRemote: (path: string, connectionId: string | undefined) => void;
+}
+/** Props of the pure template: state in, callbacks out, no hooks and no store access. */
+export interface WorkspaceDirectoryFlowSectionProps {
+    readonly copy: WorkspaceDirectoryFlowCopy;
+    readonly state: WorkspaceDirectoryFlowState;
+    readonly actions: WorkspaceDirectoryFlowSectionActions;
+    /** The browser's injected calls; the same face as {@link WorkspaceDirectoryFlowIo}, narrower. */
+    readonly browseIo: DirectoryBrowserIo;
+    /**
+     * The body-level portal the card is mounted into. Absent renders the card **in place**, which is the
+     * DOM-less degradation (SSR, a direct template call): there is no layout to escape in a runtime without a
+     * document. The shell always passes it in a browser.
+     */
+    readonly portal?: CardPortalTarget | undefined;
+    /**
+     * `id` prefix of this mount's own controls; the shell passes a per-mount value so two mounted occupants
+     * cannot produce duplicate DOM ids (`flow-session-mode`, the remote fields, the embedded browsers).
+     */
+    readonly idPrefix: string;
+    /** `id` of the dialog's heading, referenced by `aria-labelledby`; the shell passes a per-mount id. */
+    readonly titleId?: string | undefined;
+}
+/**
+ * Render the directory flow. Pure: calling it twice with the same props yields the same tree, and a closed
+ * flow renders nothing (the owner keeps the occupant mounted and drives it through `open`).
+ *
+ * @param props - copy, state, callbacks, the portal and the heading's id.
+ * @returns the dialog element (inside the portal when one is given), or `null` while closed.
+ */
+export declare function WorkspaceDirectoryFlowSection({ copy, state, actions, browseIo, portal, idPrefix, titleId, }: WorkspaceDirectoryFlowSectionProps): ReactNode;
+/** Props of the React shell: the injected face plus the owner's conversation, which arrives as normal props. */
+export interface WorkspaceDirectoryFlowContainerProps extends DirectoryFlowOwnerProps {
+    /** The active locale's dictionary; the shell resolves its own dynamic keys through it. */
+    readonly copy: WorkspaceDirectoryFlowCopy;
+    /** The injected calls. Created once by the entry (`index.ts`), never by the component. */
+    readonly io: WorkspaceDirectoryFlowIo;
+}
+/**
+ * Subscribe to a per-mount controller and render {@link WorkspaceDirectoryFlowSection}.
+ *
+ * One controller **per mount**, not per plugin load: the two holes are two independent surfaces with two
+ * independent owner conversations, and both can be mounted at the same time.
+ *
+ * The card is **portalled**: one container per mount (created from the injected document, attached to
+ * `document.body` while the interaction is open, removed again when it closes), because the sidebar hole sits
+ * in a clipping flex row that shrinks an in-place card to a vertical strip. Opening also moves focus into the
+ * card and remembers what held it, so Esc reaches the card and closing hands focus back to the trigger.
+ *
+ * @param props - the owner conversation plus the injected dictionary and calls.
+ * @returns the dialog element, or `null` while the owner has not asked for it.
+ */
+export declare function WorkspaceDirectoryFlowContainer(props: WorkspaceDirectoryFlowContainerProps): ReactNode;
+/** The dictionary keys this module renders, so a test can assert the two locales carry them without a second list. */
+export type WorkspaceDirectoryFlowKey = Extract<OverSshKey, 'flowTitle' | 'flowDescription' | 'flowLocalHeading' | 'flowLocalHint' | 'flowRemoteHeading' | 'flowRemoteHint' | 'flowConfirmRemote' | 'flowCancel' | 'flowPending' | 'flowBusy' | 'flowNoConnections' | 'flowConnectionsLoading' | 'flowNoAnchor' | 'flowUnavailable' | 'flowPickFailed' | 'browseOpenLocal' | 'browseOpenRemote' | 'browseChoose' | 'close' | 'rootsConnection' | 'rootsConnectionPlaceholder' | 'rootsRemotePathLabel'>;

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

@@ -0,0 +1,49 @@
+/**
+ * The web client half: one settings section that explains how this plugin chooses a transport, the connection
+ * list once the host answers, the editable remote-workspaces editor (`src/client/roots-panel-view.ts`) that
+ * adds and removes roots and connections through the host's same-origin `/api/over-ssh/roots` route,
+ * the **remote-files tab** (`src/client/roots/remote-files-tab.ts`) that the editor opens into the sidebar's
+ * right column,
+ * the **directory-flow occupant** (`src/client/workspace-directory-flow.ts`) that both workspace surfaces
+ * render their "add workspace" action from, and the **session entry**
+ * (`src/client/session-directory.ts`) that adds a directory to the workspace a session is already in,
+ * without creating a workspace.
+ *
+ * Both browsers of the flow and the session entry are the same component
+ * (`src/client/directory-browser.ts`): local levels come from this plugin's own read-only `list-local`
+ * action and remote levels from its `list-remote` action, both through the same same-origin route. The
+ * platform's `uiWorkspace.listDirectory()` is deliberately **not** used: it needs the directory-picker's
+ * `browse` capability, which a profile whose composed picker serves only the native dialog does not have
+ * (see `doc/02-platform/roots-http-route.md` §2).
+ *
+ * Deliberately small, but structurally complete:
+ *
+ *  - dictionaries are registered through the **typed** `ctx.locale.register` (both shipped locales required);
+ *  - the section is registered through `ctx.slots.register` inside `ctx.effect`, so unloading the plugin
+ *    removes it;
+ *  - the directory flow and the session entry go through `ctx.slots.inject` instead, because their holes
+ *    belong to other entries (the workspace surfaces, the composer), which may activate before or after this
+ *    plugin and whose absence must not fail the rest of this half;
+ *  - the panel receives its data through the registration's `inject` face, never through `ctx` (components
+ *    cannot see `ctx` — platform contract);
+ *  - the section re-registers on `locale/change`, because registrant options carry localized text and the
+ *    shell does not subscribe to locale state on the registrant's behalf; the same re-registration is what
+ *    brings the first host rows onto the screen (the slot's inject face is a synchronous snapshot, so new
+ *    data needs a fresh registration until an observable source replaces it);
+ *  - the host channel is mounted here, by this plugin: `api-remotes` only mounts the packages it lists, and a
+ *    third-party half is not one of them. `remote.<namespace>` is therefore **not** in `inject` — waiting for
+ *    a service this plugin creates itself would deadlock activation;
+ *  - the **right sidebar** is an optional seam like `uiWorkspace`: its two services are read through
+ *    `ctx.get`, never awaited, so a profile without that column loses one tab and nothing else.
+ *
+ * @module dsh-over-ssh/client
+ */
+import { Context } from '@deepseek-ai/cordis';
+/** Client services this half needs. `remote` is injected; `remote.sshdev` is mounted by `apply` below. */
+export declare const inject: string[];
+/**
+ * Install the client half.
+ *
+ * @param ctx - client plugin context (has `slots`, `locale` and `remote` by injection).
+ */
+export declare function apply(ctx: Context): void;

package/lib/types/src/client/locale.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Client-half copy for the `ssh-dev` namespace.
+ *
+ * Registration is the **typed** form of `ctx.locale.register`: the namespace is merged into
+ * `LocaleNamespaceMap`, so a missing key in either shipped locale is a compile error, and the runtime
+ * additionally requires both locales at registration (bilingual balance). Keeping the dictionaries in a
+ * pure module is what makes them testable without a browser.
+ *
+ * @module dsh-remote-workspace/client/locale
+ */
+/** Namespace owned by this plugin's client half. */
+export declare const SSH_DEV_NS = "ssh-dev";
+/**
+ * Keys of this namespace.
+ *
+ * `LocaleNamespaceMap` maps a namespace to its **key union** (not to a value interface): the runtime then
+ * derives `Record<Key, string>` per locale, which is exactly what makes a missing translation a compile
+ * error.
+ */
+export type SshDevKey = 'sectionTitle' | 'sectionDescription' | 'legendHeading' | 'legendAlias' | 'legendSsh2' | 'legendAgent' | 'noHostData' | 'close' | 'rootsTitle' | 'rootsDescription' | 'rootsEmpty' | 'rootsPending' | 'rootsAddLocal' | 'rootsAddRemote' | 'rootsAddConnection' | 'rootsRemove' | 'rootsSave' | 'rootsConnection' | 'rootsConnectionPlaceholder' | 'rootsPathLabel' | 'rootsRemotePathLabel' | 'rootsLabelLabel' | 'rootsIdLabel' | 'rootsHostLabel' | 'rootsUserLabel' | 'rootsAuthLabel' | 'rootsAuthAgent' | 'rootsAuthKey' | 'rootsKeyPathLabel' | 'rootsPortLabel' | 'rootsBadgeLocal' | 'rootsBadgeRemote' | 'rootsErrorPathRequired' | 'rootsErrorRemotePath' | 'rootsErrorConnectionRequired' | 'rootsErrorLocalPath' | 'rootsErrorDuplicate' | 'rootsErrorIdRequired' | 'rootsErrorIdInvalid' | 'rootsErrorIdDuplicate' | 'rootsErrorHostRequired' | 'rootsErrorUserRequired' | 'rootsErrorPort' | 'rootsErrorKeyPathRequired' | 'rootsErrorPasswordNotAllowed' | 'rootsNoticeUnavailable' | 'rootsNoticeWarnings' | 'flowTitle' | 'flowDescription' | 'flowLocalHeading' | 'flowLocalHint' | 'flowPickLocal' | 'flowRemoteHeading' | 'flowRemoteHint' | 'flowConfirmRemote' | 'flowCancel' | 'flowPending' | 'flowBusy' | 'flowNoConnections' | 'flowNoAnchor' | 'flowUnavailable';
+/** Merge this plugin's namespace into the shared locale map, so `t('ssh-dev.…')` is typed. */
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        'ssh-dev': SshDevKey;
+    }
+}
+/** Every shipped locale's dictionary. Both `zh` and `en` are required by the runtime. */
+export declare const SSH_DEV_DICTS: Record<'zh' | 'en', Record<SshDevKey, string>>;
+/** Dictionary keys, so a completeness test never has to restate them. */
+export declare function sshDevKeys(): readonly SshDevKey[];
+//# sourceMappingURL=locale.d.ts.map

package/lib/types/src/client/panel-model.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The settings panel's pure logic and copy wiring.
+ *
+ * Two rules that keep a client component testable without a browser:
+ *
+ *  - **no `ctx` in components** (the platform contract): everything a component shows arrives through props;
+ *  - consequently all decision-making lives here, where Node can run it. The component is a template.
+ *
+ * @module dsh-remote-workspace/client/panel-model
+ */
+import type { SshDevKey } from './locale.ts';
+/** One rendered row: a title and its explanation, already localized. */
+export interface PanelRow {
+    readonly title: string;
+    readonly body: string;
+}
+/** What the panel renders. */
+export interface PanelModel {
+    readonly title: string;
+    readonly description: string;
+    readonly legendHeading: string;
+    readonly legend: readonly PanelRow[];
+    /** Notice about the not-yet-wired host data channel; empty when host data is available. */
+    readonly notice: string;
+    readonly closeLabel: string;
+}
+/**
+ * Build the panel model from one locale's dictionary.
+ *
+ * @param copy - the dictionary the caller resolved (`zh` or `en`, chosen by the locale runtime).
+ * @param options - `hasHostData` flips the notice off once the host channel exists.
+ * @returns everything the component needs, with no further lookups.
+ */
+export declare function buildPanelModel(copy: Record<SshDevKey, string>, options?: {
+    readonly hasHostData?: boolean;
+}): PanelModel;
+//# sourceMappingURL=panel-model.d.ts.map