dsh-over-ssh 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,252 @@
+/**
+ * The visual vocabulary shared by this plugin's three web surfaces.
+ *
+ * **Everything comes from the platform's own theme tokens.** The token names were read off the runtime
+ * theme (`@deepseek-ai/dsh-client-ui-theme/lib/client.js`, the `--dsw-*` custom properties it defines); the
+ * names this plugin used before — `--dsw-alias-text-primary`, `--dsw-alias-border-subtle`,
+ * `--dsw-alias-surface-subtle`, `--dsw-alias-surface-warning` — **are not in the theme at all**, so every
+ * declaration silently fell back to `inherit` / `currentColor` / a hard-coded amber, and the commit button
+ * had no `background` whatsoever. That is why the panel looked like bare HTML with grey default buttons.
+ *
+ * Why a stylesheet and not React components:
+ *
+ *  1. The platform's own atoms (`dsh-client-ui-primitives`: `Button` / `Input` / `Alert`) are **not**
+ *     reusable here — their factories import per-component CSS modules, which a third-party bundle cannot
+ *     supply (the loader materialises only registered factories), and the package is not a dependency of
+ *     this repository. The *tokens* those atoms are built from are on every page, so this module rebuilds
+ *     the same vocabulary.
+ *  2. A React component carrying `useState` (for `:hover` / `:focus`) cannot be rendered by this
+ *     repository's tests: they call the section functions **directly**, outside any React render, where a
+ *     hook throws `Invalid hook call`. Classes + one injected stylesheet keep the templates pure
+ *     `createElement` trees that the offline tests walk, while still giving the browser real `:hover`,
+ *     `:active`, `:focus-visible` and `:disabled` states.
+ *
+ * The stylesheet is injected by the containers that mount these controls ({@link CONTROL_STYLE_ID} makes it
+ * idempotent), so importing this module on the host side has no side effect.
+ *
+ * @module dsh-remote-workspace/client/styles
+ */
+/**
+ * Semantic tokens of the shipped theme, each with a neutral fallback so a page whose theme failed to load
+ * still renders something readable rather than transparent text.
+ */
+export declare const TOKENS: {
+    /** Primary/body text. */
+    readonly textPrimary: "var(--dsw-alias-label-primary, inherit)";
+    /** Secondary text: descriptions, hints, row subtitles. */
+    readonly textSecondary: "var(--dsw-alias-label-secondary, inherit)";
+    /** Tertiary text: the quietest tier. */
+    readonly textTertiary: "var(--dsw-alias-label-tertiary, currentColor)";
+    /** Hairline around inputs and cards. */
+    readonly border: "var(--dsw-alias-border-l2, currentColor)";
+    /** Page background. */
+    readonly bgBase: "var(--dsw-alias-bg-base, transparent)";
+    /** Level-1 surface: the blocks and cards this plugin draws. */
+    readonly bgLayer1: "var(--dsw-alias-bg-layer-1, rgba(127, 127, 127, 0.06))";
+    /** Level-2 surface: controls that must read as inset inside a block. */
+    readonly bgLayer2: "var(--dsw-alias-bg-layer-2, transparent)";
+    /** Level-3 surface: chips and badges. */
+    readonly bgLayer3: "var(--dsw-alias-bg-layer-3, rgba(127, 127, 127, 0.12))";
+    /** The brand fill of a primary button. */
+    readonly primaryFill: "var(--dsw-alias-button-primary-fill, currentColor)";
+    /** Its hover step. */
+    readonly primaryHover: "var(--dsw-alias-button-primary-hover, currentColor)";
+    /** Its active/pressed step (the theme exposes one dimmed step for both). */
+    readonly primaryActive: "var(--dsw-alias-button-primary-dimmed, currentColor)";
+    /** Text on a primary fill. */
+    readonly onPrimary: "var(--dsw-alias-label-primary-foreground, currentColor)";
+    /** The neutral fill of a secondary (outline) button. */
+    readonly secondaryFill: "var(--dsw-alias-button-elevated-fill, transparent)";
+    /** A hover wash for quiet controls. */
+    readonly hoverWash: "var(--dsw-alias-interactive-bg-hover, rgba(127, 127, 127, 0.12))";
+    /** The focus ring the platform draws for keyboard focus. */
+    readonly focusRing: "var(--dsw-focus-ring-color, currentColor)";
+    /** Inline warning surface (the theme's warning tier, not an amber literal). */
+    readonly warnSurface: "var(--dsw-alias-state-warn-tertiary, rgba(255, 196, 0, 0.12))";
+    /** Inline warning text. */
+    readonly warnLabel: "var(--dsw-alias-state-warn-label, inherit)";
+    /** Error text. */
+    readonly errorPrimary: "var(--dsw-alias-state-error-primary, inherit)";
+    /** Successful state. */
+    readonly successPrimary: "var(--dsw-alias-state-success-primary, currentColor)";
+    /**
+     * The floating surface of a panel that is not inside the sidebar's own cards (the session entry).
+     * Read off the shipped theme's `design-platform.css` (`--dsw-alias-bg-overlay`), not invented.
+     */
+    readonly overlaySurface: "var(--dsw-alias-bg-overlay, Canvas)";
+    /** Panel elevation: the theme's own panel shadow, which already carries its hairline stroke. */
+    readonly panelElevation: "var(--dsw-elevation-panel, none)";
+    /** A stronger hairline, for the edge of a floating card over arbitrary content. */
+    readonly borderStrong: "var(--dsw-alias-border-l4, currentColor)";
+    /** The pressed/selected wash, one step past `hoverWash`. */
+    readonly activeWash: "var(--dsw-alias-interactive-bg-active, rgba(127, 127, 127, 0.18))";
+    /** Corner radii, straight from the theme so this plugin matches the surrounding UI. */
+    readonly radiusSm: "var(--dsw-radius-sm, 4px)";
+    readonly radiusMd: "var(--dsw-radius-md, 6px)";
+    readonly radiusLg: "var(--dsw-radius-lg, 8px)";
+    /** The large radius the theme uses for panels; the session entry's floating card. */
+    readonly radiusXl: "var(--dsw-radius-xl, 12px)";
+};
+/** The `id` of the injected `<style>` element; a second mount reuses it. */
+export declare const CONTROL_STYLE_ID = "dsh-remote-workspace-controls";
+/** Class names of the control vocabulary. Templates carry them; {@link controlStylesheet} styles them. */
+export declare const CLASS: {
+    /** A titled block: one form or group. */
+    readonly block: "dsh-rw-block";
+    /** A section heading (`h2`/`h3`). */
+    readonly sectionTitle: "dsh-rw-title";
+    /** A block heading (`h4`). */
+    readonly blockTitle: "dsh-rw-subtitle";
+    /** A description paragraph. */
+    readonly description: "dsh-rw-description";
+    /** A hint/caption paragraph. */
+    readonly hint: "dsh-rw-hint";
+    /** A vertical stack. */
+    readonly stack: "dsh-rw-stack";
+    /** A list of rows. */
+    readonly list: "dsh-rw-list";
+    /** One row (root or connection). */
+    readonly row: "dsh-rw-row";
+    /** A row's title. */
+    readonly rowTitle: "dsh-rw-row-title";
+    /** A row's secondary text (path, note). */
+    readonly rowMeta: "dsh-rw-row-meta";
+    /** A badge/chip. */
+    readonly badge: "dsh-rw-badge";
+    /** A field column: caption above control. */
+    readonly field: "dsh-rw-field";
+    /** A row of fields plus its commit button. */
+    readonly form: "dsh-rw-form";
+    /**
+     * The directory-flow dialog root. Besides the card, this is the **container** for the inline-size query
+     * below (`container-type: inline-size`), so the same component reflows by the width it is *given* rather
+     * than by the viewport.
+     */
+    readonly dialog: "dsh-rw-dialog";
+    /** The dialog's title line: flex-wrap so a long title and its badge share one row when there is space. */
+    readonly dialogHeader: "dsh-rw-dialog-header";
+    /** The dialog's body: one column by default, two columns once the container says there is room. */
+    readonly dialogBody: "dsh-rw-dialog-body";
+    /** A field that spans the whole form row (`grid-column: 1 / -1`). */
+    readonly fieldSpan: "dsh-rw-field-span";
+    /** A button that owns the whole form row. */
+    readonly spanFull: "dsh-rw-span-full";
+    /** A field whose control shares its line with one button (the remote path and its browse button). */
+    readonly inputRow: "dsh-rw-input-row";
+    /** The scroll guard for long paths inside a narrow sidebar. */
+    readonly scrollX: "dsh-rw-scroll-x";
+    /** The button base. Every button also carries one variant class. */
+    readonly button: "dsh-rw-button";
+    /** Primary (brand-filled) button. */
+    readonly buttonPrimary: "dsh-rw-button-primary";
+    /** Secondary (outlined) button. */
+    readonly buttonSecondary: "dsh-rw-button-secondary";
+    /** Ghost button: quiet until hovered (per-row destructive actions). */
+    readonly buttonGhost: "dsh-rw-button-ghost";
+    /**
+     * Row button: a **navigable** list row (the directory browser's enterable entries).
+     *
+     * It exists because the ghost variant carries the theme's **error** tone (`--dsw-alias-state-error-primary`,
+     * which is `--dsw-static-red-600` in the light theme), and that is right for a delete action but wrong for a
+     * directory name: the first release of the browser rendered every directory in red. A row therefore declares
+     * its own colour instead of inheriting the destructive one, so the reading does not depend on rule order.
+     */
+    readonly buttonRow: "dsh-rw-button-row";
+    /**
+     * Chip: a control that sits in a row of the platform's own chrome (the composer tool row) and must not read
+     * as a stray bordered button next to them. Mirrors the platform's own control there: transparent, ~28px tall,
+     * a 12px label, `--dsw-radius-sm`, and the hover/active washes.
+     */
+    readonly buttonChip: "dsh-rw-button-chip";
+    /** Small size modifier. */
+    readonly compact: "dsh-rw-compact";
+    /** A text input. */
+    readonly input: "dsh-rw-input";
+    /** A `<select>`. */
+    readonly select: "dsh-rw-select";
+    /** An inline notice block. */
+    readonly notice: "dsh-rw-notice";
+    /** The neutral (info) notice tone. */
+    readonly noticeInfo: "dsh-rw-notice-info";
+    /** A status dot. */
+    readonly statusDot: "dsh-rw-status-dot";
+    /** A wrapped row of actions (buttons that may share a line when there is room). */
+    readonly actions: "dsh-rw-actions";
+    /** The directory browser: one listing level, one column whatever width it is given. */
+    readonly browser: "dsh-rw-browser";
+    /** The browser's current-path line. */
+    readonly browserPath: "dsh-rw-browser-path";
+    /** The browser's row list. */
+    readonly browserList: "dsh-rw-browser-list";
+    /** One `<li>` of the browser's list. */
+    readonly browserItem: "dsh-rw-browser-item";
+    /** A browser row that can be entered (a directory). */
+    readonly browserRow: "dsh-rw-browser-row";
+    /** A browser row that cannot be entered (a file or a symlink), rendered as text. */
+    readonly browserQuiet: "dsh-rw-browser-quiet";
+    /** The browser's committing action; owns its row. */
+    readonly browserCommit: "dsh-rw-browser-commit";
+    /** The session entry's mount point in the composer tool row. */
+    readonly sessionEntry: "dsh-rw-session-entry";
+    /** The session entry's trigger button. */
+    readonly sessionTrigger: "dsh-rw-session-trigger";
+    /**
+     * The session entry's card surface (the floating panel of `session-directory.ts`).
+     *
+     * Since the portal (`CLASS.portal`) owns the positioning, this class is the *surface*: the theme's overlay
+     * colour, its panel elevation and the hairline a card needs when it floats over arbitrary content.
+     */
+    readonly floating: "dsh-rw-floating";
+    /**
+     * The body-level container a card is portalled into (`src/client/portal.ts`): `position: fixed`, so no
+     * ancestor's `overflow`/`transform`/`contain` can clip or re-anchor the card, and viewport-bounded so it
+     * still fits a narrow window. See {@link controlStylesheet} for the placement it is combined with.
+     */
+    readonly portal: "dsh-rw-portal";
+    /** Placement of the directory-flow dialog's portal: the centre of the window. */
+    readonly portalTop: "dsh-rw-portal-top";
+    /** Placement of the session entry's portal: the centre of the window (its own surface, same placement). */
+    readonly portalComposer: "dsh-rw-portal-composer";
+};
+/**
+ * One class attribute from a class name plus optional modifiers.
+ *
+ * @param names - the classes, `false`/`undefined` entries are dropped.
+ * @returns the `className` value.
+ */
+export declare function classes(...names: readonly (string | false | undefined)[]): string;
+/**
+ * The complete stylesheet for the vocabulary above.
+ *
+ * Exported as a pure string so a test can assert the token contract offline (which tokens are used, that the
+ * primary button really declares a brand `background`, and that hover/active/disabled each have a rule)
+ * without a browser or a CSS engine.
+ *
+ * @returns CSS text, ready for a `<style>` element.
+ */
+export declare function controlStylesheet(): string;
+/** The subset of `Document` the injection needs; structural so no DOM lib is required to type it. */
+export interface StyleDocument {
+    readonly head: {
+        appendChild(node: unknown): unknown;
+    };
+    getElementById(id: string): unknown;
+    createElement(tag: 'style'): {
+        id: string;
+        textContent: string;
+    };
+}
+/**
+ * Mount the stylesheet once per document.
+ *
+ * Idempotent through {@link CONTROL_STYLE_ID}, so two containers (the settings section and a directory-flow
+ * hole) share one element. Returns a disposer that removes it — the container calls this from an effect, so
+ * the stylesheet leaves with the last mounted surface.
+ *
+ * @param doc - the page's `document`, or `undefined` off-browser (tests) where the call is a no-op.
+ * @returns a disposer; never throws.
+ */
+export declare function injectControlStyles(doc: StyleDocument | undefined): () => void;
+/** The idempotent stylesheet mount for a React effect: `useEffect(injectControlStylesInBrowser, [])`. */
+export declare function injectControlStylesInBrowser(): () => void;
+//# sourceMappingURL=styles.d.ts.map

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

@@ -0,0 +1,342 @@
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * **Unverified** (see `doc/02-platform/workspace-directory-flow.md`): this flow has never been rendered or
+ * clicked in a real GUI, and it is not verified that the host accepts an anchor path as a workspace path.
+ *
+ * @module dsh-remote-workspace/client/workspace-directory-flow
+ */
+import { type ReactNode } from 'react';
+import type { SshDevKey } from './locale.ts';
+import { type ApiResult, type ConnectionSummary, type FetchLike, type MessageKey } from './roots-panel.ts';
+import { type RootsPanelCopy } from './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";
+/** 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[];
+    /** 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;
+    /** The last refusal or call failure, rendered through the dictionaries. */
+    readonly notice?: MessageKey;
+}
+/** 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;
+}
+/** 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;
+}
+/** 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 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;
+    /** May the local entry start the platform chooser? */
+    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[];
+    /** 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 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. */
+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 three 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.
+ */
+export interface WorkspaceDirectoryFlowIo {
+    /** The connections the remote form offers (this plugin's own `GET`, `connections` field). */
+    loadConnections(): Promise<ApiResult<readonly ConnectionSummary[]>>;
+    /**
+     * 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>>;
+    /** The platform's local chooser; `null` means the operator dismissed it. */
+    pickDirectory(): Promise<string | null>;
+}
+/**
+ * Bind the flow's three calls to the browser and the platform.
+ *
+ * `loadConnections` reuses `createRootsApi`'s `GET` (and therefore its field-by-field credential filter);
+ * `addRemoteRoot` posts the same 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), the platform chooser, and a path override for tests.
+ * @returns the calls the flow uses.
+ */
+export declare function createWorkspaceDirectoryFlowIo(options: {
+    readonly fetchImpl: FetchLike;
+    readonly pickDirectory: () => Promise<string | null>;
+    readonly path?: string;
+}): WorkspaceDirectoryFlowIo;
+/** What the stateful half needs: the injected calls plus the active dictionary, read at report time. */
+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;
+    /** Run the platform chooser and report what it answered. */
+    readonly pickLocal: () => Promise<void>;
+    /** Validate the remote form, add the root and report its anchor path. */
+    readonly submitRemote: () => Promise<void>;
+    /** Report the operator's dismissal. */
+    readonly cancel: () => 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;
+    readonly onPickLocal: () => void;
+    readonly onSubmitRemote: () => void;
+    readonly onCancel: () => 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;
+}
+/**
+ * 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 and callbacks.
+ * @returns the dialog element, or `null` while closed.
+ */
+export declare function WorkspaceDirectoryFlowSection({ copy, state, actions }: 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.
+ *
+ * @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<SshDevKey, 'flowTitle' | 'flowDescription' | 'flowLocalHeading' | 'flowLocalHint' | 'flowPickLocal' | 'flowRemoteHeading' | 'flowRemoteHint' | 'flowConfirmRemote' | 'flowCancel' | 'flowPending' | 'flowBusy' | 'flowNoConnections' | 'flowNoAnchor' | 'flowUnavailable' | 'rootsConnection' | 'rootsConnectionPlaceholder' | 'rootsRemotePathLabel'>;
+//# sourceMappingURL=workspace-directory-flow.d.ts.map