dsh-over-ssh 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,587 @@
+/**
+ * The **directory browser**: pick a directory by looking at it, on this machine or on a connection.
+ *
+ * Why a browser at all: the platform's own chooser (`ctx.uiWorkspace.pickDirectory()`) is a **native**
+ * dialog, and the panel's remote form asked for a path typed from memory. The client asked for browsing
+ * ("添加工作区应该要添加浏览目录的功能"), and **both** worlds now come from this plugin's own read-only route:
+ *
+ *  - **local** listings come from `POST { action: 'list-local', path? }`, which the host answers with the
+ *    absolute, canonical path it resolved, the breadcrumb chain to it, and `{ name, kind }` rows. The
+ *    platform's `uiWorkspace.listDirectory()` is **not** used: its Host half needs the directory-picker's
+ *    `browse` capability, and a profile whose composed picker serves only the native dialog fails the call
+ *    outright ("directoryPicker.list needs the browse capability; the composed picker serves \"native\"").
+ *    The host process always has `node:fs`, so browsing this machine is one action of our own route;
+ *  - **remote** listings come from `POST { action: 'list-remote', connectionId, path }`, answered with
+ *    `{ name, kind }` rows only. The client never composes an SSH command or a shell script: a browser that
+ *    built its own `ls` would be a second, unaudited path to the remote host, and it would be the client that
+ *    decides what a "directory" is.
+ *
+ * The platform chooser is still a second way in, but it is a **different surface**: the dialog around this
+ * browser keeps its own "pick a folder" button (`ctx.uiWorkspace.pickDirectory()`), and this module never
+ * touches it.
+ *
+ * Three layers, the same split every other surface here uses (`workspace-directory-flow.ts`):
+ *
+ *  1. {@link directoryBrowserReducer} - pure state machine over one listing level.
+ *  2. {@link createDirectoryBrowser} - the same state plus the injected calls and a request token, so an
+ *     answer for a directory the user already left cannot overwrite the current one.
+ *  3. {@link DirectoryBrowserSection} (pure template) + {@link DirectoryBrowserContainer} (the React
+ *     shell), so a test walks the element tree without a renderer.
+ *
+ * The browser is **narrow-friendly by construction**: one column, wrapping rows, and no declaration that
+ * could exceed its container (see `styles.ts`; the widths are percentages, and the only fixed lengths are
+ * radii and hairlines). The dialog it is embedded in is what decides between one and two columns.
+ *
+ * **Unverified** (see `doc/02-platform/workspace-directory-flow.md`): this tree has never been rendered or
+ * clicked in a real GUI. A local listing now needs nothing from the composition but the host route itself;
+ * a host without the `listLocalDirectory` seam answers `500 capability-missing`, which the browser reports
+ * instead of pretending the machine is empty.
+ *
+ * @module dsh-over-ssh/client/directory-browser
+ */
+import { type ReactNode, type RefObject } from 'react';
+import type { OverSshKey } from '../core/locale.ts';
+import { type ApiResult, type ConnectionSummary, type FetchLike } from '../roots/roots-panel.ts';
+import { type RootsPanelCopy } from '../roots/roots-panel-view.ts';
+/** Which world a listing level belongs to. */
+export type DirectoryBrowserMode = 'local' | 'remote';
+/**
+ * What one row is, in either world.
+ *
+ * The remote action classifies a row as a directory, a file or a symlink; the local one uses the narrower
+ * vocabulary `directory | file | other`, because a local link can only be told from a file or a directory by
+ * **following** it, which the host never does (see `doc/02-platform/roots-http-route.md` §2).
+ */
+export type DirectoryBrowserKind = 'directory' | 'file' | 'symlink' | 'other';
+/** One **local** row as this plugin's route answers it: **a name and a kind, nothing else**. */
+export interface LocalDirectoryEntry {
+    readonly name: string;
+    readonly kind: 'directory' | 'file' | 'other';
+}
+/**
+ * One local listing level, exactly as `list-local` answers it.
+ *
+ * Every path here is the **host's own**: `path` is the absolute canonical path it resolved, and `crumbs` is
+ * the absolute chain from the filesystem root down to it. The browser reads no other field and derives no
+ * path of its own ("up" is `crumbs[len - 2]`, "home" is a request without a `path`), which is what keeps
+ * drive letters, UNC shares and separators out of the client.
+ */
+export interface LocalDirectoryListing {
+    /** Absolute, host-resolved path of the listed directory. */
+    readonly path: string;
+    /** Absolute ancestor chain of {@link path}: root first, `path` last. */
+    readonly crumbs: readonly string[];
+    /** Direct children of {@link path}, as the host classified them. */
+    readonly entries: readonly LocalDirectoryEntry[];
+    /** True when the host cut the list at its own bound. */
+    readonly truncated: boolean;
+}
+/** The kinds the **remote** action can report; a remote listing never answers `other`. */
+export type RemoteDirectoryKind = 'directory' | 'file' | 'symlink';
+/** One remote row as this plugin's route answers it: **a name and a kind, nothing else**. */
+export interface RemoteDirectoryEntry {
+    readonly name: string;
+    readonly kind: RemoteDirectoryKind;
+}
+/** One remote listing level. */
+export interface RemoteDirectoryListing {
+    /**
+     * Absolute path the host actually listed.
+     *
+     * Carried back because the host may have resolved it: an empty request path means "this connection's start
+     * directory", which the host answers with the login user's home (on this site `/home1/<user>`, not
+     * `/home/<user>`). The browser reads this instead of assuming what it asked for.
+     */
+    readonly path: string;
+    readonly entries: readonly RemoteDirectoryEntry[];
+    /** True when the host cut the list at its own bound. */
+    readonly truncated: boolean;
+}
+/**
+ * The route the host serves git badges on. **Duplicated here on purpose**: the client bundle cannot import host
+ * modules (architecture: `client` may not depend on `host`), and the value is asserted equal in the host's own
+ * test so the two cannot drift silently.
+ */
+export declare const GIT_STATUS_API_PATH = "/api/over-ssh/git-status";
+/** One normalized status; the host and the agent only ever send these six. */
+export type GitChangeStatus = 'modified' | 'added' | 'deleted' | 'renamed' | 'untracked' | 'conflicted';
+/** One changed path, relative to the git work-tree root the host resolved. */
+export interface GitStatusChange {
+    readonly path: string;
+    readonly status: GitChangeStatus;
+}
+/**
+ * What the host answers for one browsed directory.
+ *
+ * `available: false` is normal (Tier 1, an agent without `git.status`, a directory outside any work tree): the
+ * browser simply draws no badges. `directory` is the browsed path **relative to the work-tree root**, which is
+ * what lets the client match a row to its change without knowing any path rules.
+ */
+export interface GitStatusView {
+    readonly available: boolean;
+    readonly root?: string;
+    readonly directory?: string;
+    readonly branch?: string;
+    readonly changes: readonly GitStatusChange[];
+    readonly truncated: boolean;
+    readonly reason?: string;
+}
+/** Badge letter per status. Language-neutral on purpose (no locale key is added for them). */
+export declare const GIT_STATUS_BADGE: Readonly<Record<GitChangeStatus, string>>;
+/** Narrow one host answer; unknown statuses and empty paths are dropped. */
+export declare function parseGitStatusView(value: Record<string, unknown>): GitStatusView;
+/** The calls the browser makes. All of them are injected, so the state machine is testable offline. */
+export interface DirectoryBrowserIo {
+    /** The connections the remote mode offers (this plugin's own `GET`). */
+    loadConnections(): Promise<ApiResult<readonly ConnectionSummary[]>>;
+    /** One local directory level, through this plugin's own route (`list-local`); no `path` means the host's home. */
+    listLocal(path?: string): Promise<ApiResult<LocalDirectoryListing>>;
+    /** One remote directory level, through this plugin's own route. */
+    listRemote(input: {
+        readonly connectionId: string;
+        readonly path: string;
+    }): Promise<ApiResult<RemoteDirectoryListing>>;
+    /**
+     * Remote git badges for one listed level, through this plugin's own route.
+     *
+     * Optional so a surface (or an older composition) that does not serve the route keeps compiling: absent means
+     * no badges, never a failed listing.
+     */
+    loadGitStatus?(input: {
+        readonly connectionId: string;
+        readonly path: string;
+    }): Promise<ApiResult<GitStatusView>>;
+}
+/**
+ * The host's machine-readable reason for "this composition cannot list a local directory at all".
+ *
+ * The route answers it as a **500** and never as an empty listing: a machine nobody can read and a machine
+ * with nothing in it are two different facts. The browser renders it through `browseUnavailable`.
+ */
+export declare const NO_LOCAL_CAPABILITY_REASON = "capability-missing";
+/** The error reported when a remote listing is asked for without a connection. */
+export declare const NO_CONNECTION_ERROR = "no-connection";
+/**
+ * Prefix of the reason a failed **native chooser** reports.
+ *
+ * The chooser is not a listing: when the platform dialog is missing (`directory-picker/unavailable`) or it
+ * rejects, the rows on screen are still the ones the host listed, and telling the user "listing failed" would
+ * describe the wrong thing. The prefix is what lets the failure text pick the right sentence without a second
+ * error field in the state.
+ */
+export declare const PICK_ERROR_PREFIX = "pick:";
+/**
+ * The text one refused `POST` reports.
+ *
+ * Order, and the reason for it: the host's `reason` is the **machine-readable** field (it names the case, so
+ * a surface can branch on it), its `error` is the prose behind it, and `transportFailureReason(status, path)`
+ * is what is left when the body named nothing at all - the path is part of that text on purpose, because
+ * `http-404` alone cannot distinguish "the route is not registered" from "the request never reached the host"
+ * (see `doc/02-platform/roots-http-route.md` §2).
+ *
+ * @param parsed - the response body, when it parsed as an object.
+ * @param status - the HTTP status.
+ * @param path - the exact URL that was requested.
+ * @returns the reason the surface shows.
+ */
+export declare function postFailureReason(parsed: Record<string, unknown> | undefined, status: number, path: string): string;
+/**
+ * POST one action to this plugin's route and answer the **raw** JSON object.
+ *
+ * Deliberately not `createRootsApi().send`: that path projects the answer through `parseRootsSnapshot`, which
+ * is right for the panel's snapshot and wrong for an action that answers something else (`anchorPath` for
+ * `add-root`, `entries` for `list-remote` and `list-local`). The failure vocabulary is still shared - the
+ * host's machine-readable `reason` wins, then its prose, and otherwise `transportFailureReason(status, path)`
+ * names the request that failed.
+ *
+ * @param fetchImpl - the page's `fetch`, or a stub in tests.
+ * @param path - the route to post to; `ROOTS_API_PATH` for every caller in this plugin.
+ * @param body - the action and its whitelisted parameters.
+ * @returns the parsed object, or the reason it could not be produced.
+ */
+export declare function postRootsJson(fetchImpl: FetchLike, path: string, body: Record<string, unknown>): Promise<ApiResult<Record<string, unknown>>>;
+/**
+ * Bind the browser's three calls to this plugin's own route.
+ *
+ * There is **no platform directory service in this face**: `uiWorkspace.listDirectory()` needs the
+ * directory-picker's `browse` capability, and a profile whose composed picker serves the native dialog fails
+ * that call outright. Both listings are therefore POSTs to the same relative route, with the same failure
+ * vocabulary, and the composition cannot take local browsing away.
+ *
+ * @param options - `fetch` and an optional route override (tests).
+ * @returns the calls the browser uses.
+ */
+export declare function createDirectoryBrowserIo(options: {
+    readonly fetchImpl: FetchLike;
+    readonly path?: string;
+}): DirectoryBrowserIo;
+/** One rendered row. */
+export interface DirectoryBrowserRow {
+    /** Stable identity inside the current listing (the child's path for local rows, name for remote ones). */
+    readonly key: string;
+    readonly name: string;
+    /** Absolute path: for a local row the host's path plus its name, for a remote row the joined remote path. */
+    readonly path: string;
+    readonly kind: DirectoryBrowserKind;
+    readonly hidden: boolean;
+}
+/** Everything the browser renders from. */
+export interface DirectoryBrowserState {
+    /** Which world the current level belongs to. */
+    readonly mode: DirectoryBrowserMode;
+    /** True while a listing call is in flight. */
+    readonly pending: boolean;
+    /** The listed directory; `''` before the first answer. Always the path the **host** answered with. */
+    readonly path: string;
+    /** Ancestor chain of {@link path}, root first and `path` last (local listings only; `[]` for remote). */
+    readonly crumbs: readonly string[];
+    /** Child rows of {@link path}. */
+    readonly rows: readonly DirectoryBrowserRow[];
+    /** True when the listing was cut at the host's bound. */
+    readonly truncated: boolean;
+    /** The connection remote listings go through. */
+    readonly connectionId: string;
+    /** The connections remote mode offers. */
+    readonly connections: readonly ConnectionSummary[];
+    /** The last connection-list failure, kept so the surface can say why the list is empty. */
+    readonly connectionsError?: string;
+    /**
+     * True while the remote world's connection list is being read.
+     *
+     * Without it the browser rendered 「还没有连接：请先在『SSH 远程开发』里新增一个连接。」 during the read — telling the
+     * user to add a connection they already had (audit 2026-11-01b ui P2-4).
+     */
+    readonly connectionsPending: boolean;
+    /** The last listing failure, as the host reported it. */
+    readonly error?: string;
+    /**
+     * Remote git badges for {@link path}.
+     *
+     * Absent means "no badges": local mode, a failed/slow git read, or a connection without git support. Its own
+     * optional field rather than more booleans, so "we asked and got nothing" and "we never asked" render the same
+     * (no badges) and the listing cannot be affected by it.
+     */
+    readonly git?: DirectoryBrowserGitState;
+}
+/** The badge data of one listed level. */
+export interface DirectoryBrowserGitState {
+    /** The work-tree root the host resolved; `''` when the answer carried none. */
+    readonly root: string;
+    /** The browsed directory relative to {@link root} ('' when the browsed path *is* the root). */
+    readonly directory: string;
+    /** Branch name; absent for a detached HEAD (never substituted). */
+    readonly branch?: string;
+    /** Root-relative path → status. */
+    readonly changes: Readonly<Record<string, GitChangeStatus>>;
+    readonly truncated: boolean;
+}
+/** What the reducer accepts. */
+export type DirectoryBrowserAction = 
+/** The user switched world; the current level is dropped, not carried over. */
+{
+    readonly type: 'mode-changed';
+    readonly mode: DirectoryBrowserMode;
+}
+/** The user chose another connection. */
+ | {
+    readonly type: 'connection-changed';
+    readonly connectionId: string;
+}
+/** The connection list is being read (also clears a previous failure, so the retry shows "reading"). */
+ | {
+    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;
+}
+/** A level is being read: the rows are cleared so a stale level is never shown under a new path. */
+ | {
+    readonly type: 'target';
+    readonly path: string;
+}
+/** A local level arrived. */
+ | {
+    readonly type: 'local-loaded';
+    readonly listing: LocalDirectoryListing;
+}
+/** A remote level arrived. */
+ | {
+    readonly type: 'remote-loaded';
+    readonly path: string;
+    readonly listing: RemoteDirectoryListing;
+}
+/**
+ * The remote git badges for the current level arrived.
+ *
+ * Its own action rather than a field of `remote-loaded`: the git read and the listing are independent calls,
+ * and a level must render (and stay interactive) while the badge read is still in flight or has failed.
+ */
+ | {
+    readonly type: 'git-loaded';
+    readonly view: GitStatusView;
+}
+/** Reading the level failed. */
+ | {
+    readonly type: 'failed';
+    readonly error: string;
+}
+/**
+ * The native chooser round trip failed.
+ *
+ * Its own action rather than `failed`: the listing is untouched, so only the failure line changes.
+ */
+ | {
+    readonly type: 'pick-failed';
+    readonly error: string;
+};
+/** @returns the state a freshly mounted browser holds. */
+export declare function initialDirectoryBrowserState(mode?: DirectoryBrowserMode): DirectoryBrowserState;
+/**
+ * The browser's state machine. Pure: an action that changes nothing returns the **same object**.
+ *
+ * @param state - the current state.
+ * @param action - what happened.
+ * @returns the next state.
+ */
+export declare function directoryBrowserReducer(state: DirectoryBrowserState, action: DirectoryBrowserAction): DirectoryBrowserState;
+/** The parent of one absolute POSIX path, or `undefined` at the root (and for a path never listed). */
+export declare function parentRemotePath(path: string): string | undefined;
+/** One child of a remote directory. Only ever called with a name the host reported (no separators). */
+export declare function remoteChildPath(base: string, name: string): string;
+/**
+ * The path to ask for when entering one child of a **local** listing.
+ *
+ * This is the browser's only path composition, and it is deliberately the smallest one that can work: the
+ * route accepts absolute paths only, so "enter" has to name the child, and the host's row carries the name
+ * alone. Everything else stays host-owned - the **base is always the path the host answered with** (never a
+ * `dirname` of anything), "up" is a crumb the host sent, and "home" is a request with no path at all.
+ *
+ * `/` is the separator appended, because it is the one both dialects accept: `node:path.isAbsolute` and
+ * `node:path.resolve` take `D:/work/name` on Windows (and canonicalise it back to `D:\work\name`), while on
+ * POSIX a backslash can be part of a real file name, so `/` is the only correct choice there. Trailing
+ * separators are dropped first so the filesystem root (`/`, `D:\`, `\\server\share\`) does not yield `//name`.
+ *
+ * @param base - the host's own absolute path of the listed directory.
+ * @param name - a name the host reported (by contract it carries no separator).
+ * @returns the absolute path to list for that child.
+ */
+export declare function localChildPath(base: string, name: string): string;
+/** The complete render input. */
+export interface DirectoryBrowserView {
+    /** True while a listing is in flight. */
+    readonly pending: boolean;
+    /** The level being listed: the last answer's path, or the one being read now. */
+    readonly path: string;
+    readonly rows: readonly DirectoryBrowserRow[];
+    readonly connections: readonly ConnectionSummary[];
+    readonly connectionId: string;
+    /** May "go up" be pressed, and where does it go? */
+    readonly canGoUp: boolean;
+    /** Where "up" goes; absent at the top of the tree. */
+    readonly upPath?: string;
+    /** May the current level be committed? */
+    readonly canCommit: boolean;
+    /** Remote mode with no connection chosen: nothing can be listed yet. */
+    readonly needsConnection: boolean;
+    /** The level was read and holds no child. */
+    readonly empty: boolean;
+    /** The level was read and cut at the service's bound. */
+    readonly truncated: boolean;
+    /** The last listing failure. */
+    readonly error?: string;
+    /** The last connection-list failure. */
+    readonly connectionsError?: string;
+    /** True while the connection list is being read (remote world, nothing chosen yet). */
+    readonly connectionsPending: boolean;
+    /** Branch badge at the top of the level; absent when unknown (detached HEAD, no git, read failed). */
+    readonly gitBranch?: string;
+    /** Root-relative path → status, for {@link gitBadgeForRow}. Empty when no badges apply. */
+    readonly gitChanges: Readonly<Record<string, GitChangeStatus>>;
+    /** The browsed directory relative to the git root ('' when browsing the root itself or no badge data). */
+    readonly gitDirectory: string;
+    /** The badge list was cut (agent/service cap): the UI must not claim it is complete. */
+    readonly gitTruncated: boolean;
+}
+/**
+ * Turn the state into render input. The single place the browser's gates are decided.
+ *
+ * @param state - the browser state.
+ * @returns the flags, the path, the rows and the two failure texts.
+ */
+export declare function selectDirectoryBrowserView(state: DirectoryBrowserState): DirectoryBrowserView;
+/**
+ * The badge of one row: the status of the row's **own path**, or `undefined`.
+ *
+ * Two deliberate rules:
+ *  - only a **direct** change marks a row: a modified file two levels down does not paint its ancestor directory
+ *    (an aggregate status would be a guess; the user can enter the directory and see it);
+ *  - directory rows get no badge at all — `git status` reports paths, not directories, and inventing `M` for a
+ *    directory that merely *contains* changes is exactly the "unknown status guessed into a badge" this task
+ *    forbids.
+ *
+ * @param view - the rendered level.
+ * @param row - one row of that level.
+ * @returns the status to draw, or `undefined` (no badge).
+ */
+export declare function gitBadgeForRow(view: DirectoryBrowserView, row: DirectoryBrowserRow): GitChangeStatus | undefined;
+/** What the controller needs: the injected calls, the active dictionary and its mount-time world. */
+export interface DirectoryBrowserDeps {
+    readonly io: DirectoryBrowserIo;
+    /** The dictionary of the active locale; a thunk, because the locale can change under a mounted browser. */
+    readonly copy: () => RootsPanelCopy;
+    /** The world this occurrence browses; a mount-time input (changing it remounts). */
+    readonly mode?: DirectoryBrowserMode;
+    /** A connection chosen before the first listing (the embedding surface may already know one). */
+    readonly connectionId?: string;
+    /**
+     * The connection list the embedding surface already read, when it has one.
+     *
+     * The workspace directory flow reads it when it opens; the embedded remote browser used to read the **whole
+     * roots snapshot** again just to get the same list, i.e. one extra full GET per "open browse" (audit
+     * 2026-11-01b ui P3-8). Seeding it here removes the duplicate, and `ensureConnections` still reads for a
+     * surface that opens the browser on its own (the session entry).
+     */
+    readonly connections?: readonly ConnectionSummary[];
+}
+/** The calls the container makes. */
+export interface DirectoryBrowserController {
+    readonly getState: () => DirectoryBrowserState;
+    readonly subscribe: (listener: () => void) => () => void;
+    /** Read the first level (and, in remote mode, the connection list) once. */
+    readonly start: (seedPath?: string) => void;
+    readonly setMode: (mode: DirectoryBrowserMode) => void;
+    readonly setConnection: (connectionId: string) => void;
+    /** Enter a child directory. */
+    readonly enter: (path: string) => void;
+    /** Go one level up, when the view allows it. */
+    readonly up: () => void;
+    /** Jump to this side's home directory: the local host's, or the remote login user's (resolved by the host). */
+    readonly home: () => void;
+    /** Re-read the current level. */
+    readonly reload: () => void;
+    /** Re-read the connection list after its own failure (the remote world's retry). */
+    readonly reloadConnections: () => void;
+    /** Report a failed native-chooser round trip; the listing is not touched. */
+    readonly failPick: (reason: string) => void;
+    /**
+     * Re-arm after a mount.
+     *
+     * React's development-mode replay runs the effect's cleanup once before the real lifetime, so a controller
+     * that stayed disposed would never load anything (or, for the session entry, never write). The flow's
+     * controller has the same method for the same reason.
+     */
+    readonly activate: () => void;
+    readonly dispose: () => void;
+}
+/**
+ * Build the stateful half of the browser.
+ *
+ * Every listing is addressed by a monotonically increasing token: a late answer for a directory the user
+ * already left is dropped rather than rendered, which is the one race a browsing UI really has (click
+ * through a slow host, then go up).
+ *
+ * @param deps - the injected calls, the dictionary and the mount-time world.
+ * @returns the controller the container subscribes to.
+ */
+export declare function createDirectoryBrowser(deps: DirectoryBrowserDeps): DirectoryBrowserController;
+/** What the browser's controls call. All of them are no-ops when the gate is closed. */
+export interface DirectoryBrowserActions {
+    readonly onModeChange: (mode: DirectoryBrowserMode) => void;
+    readonly onConnectionChange: (connectionId: string) => void;
+    readonly onEnter: (path: string) => void;
+    readonly onUp: () => void;
+    /** Jump to the host account's home directory (local mode only). */
+    readonly onHome: () => void;
+    readonly onReload: () => void;
+    /** The connection list's own retry (its failure is inline, in the remote block). */
+    readonly onReloadConnections: () => void;
+    readonly onCommit: () => void;
+    /**
+     * 用宿主系统的原生目录选择框挑一个目录（本机模式、且宿主提供了这个能力时才有）。
+     *
+     * 为什么要有：内置浏览器能到的地方有限，而本机用户通常已经知道路径，或者想从「最近使用」里挑。
+     * 平台为此提供了 `uiWorkspace.pickDirectory()`（桌面壳里是 `__DSH_DIRECTORY_PICKER__`），
+     * 直接弹系统框比一层层点进去快得多。
+     */
+    readonly onPickNative?: (() => void) | undefined;
+}
+/** The default `id` prefix when the embedding surface does not pass one (direct template calls, tests). */
+export declare const DEFAULT_DIRECTORY_BROWSER_ID_PREFIX = "dsh-rw-browse";
+/** Props of the pure template: state in, callbacks out, no hooks and no store access. */
+export interface DirectoryBrowserSectionProps {
+    readonly copy: RootsPanelCopy;
+    readonly state: DirectoryBrowserState;
+    readonly actions: DirectoryBrowserActions;
+    /** Label of the committing action ("use this directory"), supplied by the surface that embedded it. */
+    readonly commitLabel: string;
+    /** True while the embedding surface cannot accept a pick (owner busy, request in flight). */
+    readonly disabled?: boolean | undefined;
+    /** Hide the mode switch when the surface already decided which world this browser is for. */
+    readonly fixedMode?: boolean | undefined;
+    /** `id` prefix of this occurrence's controls, so two embedded browsers cannot produce duplicate ids. */
+    readonly idPrefix?: string | undefined;
+    /**
+     * The level list, so the container can move focus into it after a navigation.
+     *
+     * The row the user activated is **unmounted** by that navigation (the level is replaced), so without this the
+     * focus falls to `<body>` and every keyboard step starts over (audit 2026-10-31 client.md §2.3).
+     */
+    readonly listRef?: RefObject<HTMLUListElement | null> | undefined;
+}
+/**
+ * Render one directory level. Pure: the same props yield the same tree.
+ *
+ * @param props - copy, state, callbacks and the surface's own gate.
+ * @returns the browser element.
+ */
+export declare function DirectoryBrowserSection({ copy, state, actions, commitLabel, disabled, fixedMode, idPrefix, listRef, }: DirectoryBrowserSectionProps): ReactNode;
+/** Props of the React shell: the injected calls, the mount-time world and the surface's callback. */
+export interface DirectoryBrowserContainerProps {
+    /** The active locale's dictionary. */
+    readonly copy: RootsPanelCopy;
+    /** The injected calls; created once by the entry, never by the component. */
+    readonly io: DirectoryBrowserIo;
+    /** Which world this browser is for; changing it is expressed by remounting (the caller sets `key`). */
+    readonly mode: DirectoryBrowserMode;
+    /** Where a local listing starts; absent means the host account's home. */
+    readonly seedPath?: string | undefined;
+    /** Pre-selected connection for remote mode. */
+    readonly initialConnectionId?: string | undefined;
+    /**
+     * The connection list the embedding surface already has (see {@link DirectoryBrowserDeps.connections}).
+     *
+     * Absent means "read it yourself", which is what the composer entry does.
+     */
+    readonly initialConnections?: readonly ConnectionSummary[] | undefined;
+    readonly disabled?: boolean | undefined;
+    /** Hide the local/remote switch (the embedding surface already decided). */
+    readonly fixedMode?: boolean | undefined;
+    /**
+     * 宿主系统的原生目录选择框；`null` 表示用户取消。
+     *
+     * 缺席就完全不画那颗按钮——「没有这个能力」和「有这个能力但调用会失败」是两件事，
+     * 界面上只应该出现前者对应的样子。
+     */
+    readonly pickNative?: (() => Promise<string | null>) | undefined;
+    /** `id` prefix of this occurrence's controls; defaults to {@link DEFAULT_DIRECTORY_BROWSER_ID_PREFIX}. */
+    readonly idPrefix?: string | undefined;
+    readonly commitLabel: string;
+    /** The operator picked the current directory. */
+    readonly onCommit: (path: string, connectionId: string | undefined) => void;
+}
+/**
+ * Subscribe to a per-mount browser and render {@link DirectoryBrowserSection}.
+ *
+ * @param props - the injected calls, the world and the commit callback.
+ * @returns the browser element.
+ */
+export declare function DirectoryBrowserContainer(props: DirectoryBrowserContainerProps): ReactNode;
+/** The dictionary keys this module renders, so a test can assert the two locales carry them without a second list. */
+export type DirectoryBrowserKey = Extract<OverSshKey, 'browseHeading' | 'browseUp' | 'browseCurrent' | 'browseEmpty' | 'browseLoading' | 'browseFailed' | 'browseUnavailable' | 'browseNeedConnection' | 'browseTruncated' | 'browseKindFile' | 'browseKindSymlink' | 'browseKindOther' | 'browseRetry' | 'browseLocalMode' | 'browseRemoteMode' | 'browseHome' | 'browseChoose' | 'flowNoConnections' | 'rootsConnection' | 'rootsConnectionPlaceholder'>;