dsh-over-ssh 0.0.0-stage → 0.1.0

package/lib/types/src/client/roots/roots-panel-view.d.ts

@@ -0,0 +1,280 @@
+/**
+ * The **editable** remote-workspaces section of the settings panel.
+ *
+ * Three layers, deliberately separated so the interesting parts can be tested without a browser:
+ *
+ *  1. {@link rootsPanelReducer}  - a pure state machine over the panel's drafts, the last host answer and
+ *     whether a request is in flight. No DOM, no I/O, no React: `tests/client-roots-view.test.ts` drives it
+ *     directly.
+ *  2. {@link createRootsPanelController}  - the same state plus the two calls from
+ *     `./roots-panel.ts` (`load` / `send`). Everything that is *not* pure lives here: validation gate,
+ *     double-submit gate, the refresh after a success, and dropping answers that a newer request superseded.
+ *  3. {@link RootsPanelSection}  - a pure template (`createElement`, never JSX: Node's native type stripping
+ *     cannot transform JSX) and {@link RootsPanelContainer}, the thin React shell that subscribes to the
+ *     controller.
+ *
+ * Rules this file is responsible for, and where they are enforced:
+ *
+ *  - **A `config` root never gets a delete button.** The button is rendered from
+ *    {@link RootRowView.removable} and from nothing else; the controller refuses such a key before a POST.
+ *  - **Nothing is submitted before validation.** `validateRootDraft` / `validateConnectionDraft` are the only
+ *    way a draft becomes a request body, and their `MessageKey` refusal is rendered as text through the
+ *    locale dictionaries.
+ *  - **No double submit.** `canEdit === false` (no answer yet, or a request in flight) disables every control
+ *    and stops every handler.
+ *  - **No credentials.** This file can only send the fields its drafts hold; the password field does not
+ *    exist, and `validateConnectionDraft` refuses `authKind: 'password'` outright.
+ *
+ * @module dsh-over-ssh/client/roots-panel-view
+ */
+import { type ReactNode } from 'react';
+import { type CardPortal } from '../core/portal.ts';
+import { type RootLocation, type RootsApi } from './roots-panel.ts';
+import type { RootsPanelCopy, RootsPanelDraftPatch, RootsPanelEditDraftPatch, RootsPanelState } from './roots-panel-state.ts';
+export * from './roots-panel-state.ts';
+export * from './transfer-panel-view.ts';
+/**
+ * Placement of the connection **edit dialog**'s portal.
+ *
+ * `CLASS.portal` is the fixed body-level container; `CLASS.portalTop` is the wider placement the other two
+ * dialogs share, which this form needs because it carries five fields plus the rename note.
+ */
+export declare const ROOTS_EDIT_PORTAL_CLASS: string;
+/**
+ * The click sink for that card: the settings modal's own layers are 900/1001, so the sink sits at 1001 and the
+ * card above it (audit 2026-11-01b ui P2-1). The edit dialog is the case where a click *through* the gap used to
+ * be worst: the 「新增连接」 form behind it shares the screen, and its 保存 was reachable.
+ */
+export declare const ROOTS_EDIT_BACKDROP_CLASS: string;
+/** The calls the section makes. `roots-panel.ts` owns how they are implemented. */
+export interface RootsPanelController {
+    /** The current state; a stable reference until something changes (safe for `useSyncExternalStore`). */
+    readonly getState: () => RootsPanelState;
+    /** Watch for changes; returns the disposer. */
+    readonly subscribe: (listener: () => void) => () => void;
+    /** Ask for the first answer once; a remount does not re-fetch. */
+    readonly start: () => void;
+    /** Reload unconditionally (used after a successful change). */
+    readonly reload: () => Promise<void>;
+    /** Change one field of the **add connection** form. */
+    readonly changeDraft: (patch: RootsPanelDraftPatch) => void;
+    /**
+     * Change one field of the **edit dialog**.
+     *
+     * A separate writer because the two forms have separate drafts (`RootsPanelEditDrafts`): one set made opening
+     * the dialog overwrite the add form and cancelling it wipe it (audit 2026-11-01b ui P1-4).
+     */
+    readonly changeEditDraft: (patch: RootsPanelEditDraftPatch) => void;
+    /** Validate and add a root of the given location. */
+    readonly submitRoot: (location: RootLocation) => Promise<void>;
+    /** Validate and add a connection. */
+    readonly submitConnection: () => Promise<void>;
+    /** Open the edit form for one connection, prefilled from the last host answer. */
+    readonly startEdit: (id: string) => void;
+    /** Close the edit form without saving. */
+    readonly cancelEdit: () => void;
+    /** Validate and save the edit form (a rename included). */
+    readonly submitEdit: () => Promise<void>;
+    /** Ask for confirmation before removing a connection (it takes its remote roots with it). */
+    readonly askRemoveConnection: (id: string) => void;
+    /** Dismiss the confirmation. */
+    readonly cancelRemoveConnection: () => void;
+    /** Remove a connection, once the confirmation was accepted. */
+    readonly confirmRemoveConnection: (id: string) => Promise<void>;
+    /** Remove one row, if the view allows it. */
+    readonly remove: (key: string) => Promise<void>;
+    /** Open the ssh-config import dialog and read the file (FR-2.1.4). */
+    readonly openImport: () => Promise<void>;
+    /** Re-read `~/.ssh/config`, replacing the candidate list. */
+    readonly reloadImport: () => Promise<void>;
+    /** Close the dialog. */
+    readonly closeImport: () => void;
+    /** Tick or untick one alias. */
+    readonly toggleImport: (alias: string) => void;
+    /** Tick every candidate. */
+    readonly selectAllImports: () => void;
+    /** Untick everything. */
+    readonly clearImports: () => void;
+    /** Import the ticked aliases. */
+    readonly submitImport: () => Promise<void>;
+    /**
+     * Tell the controller the settings surface is on screen again.
+     *
+     * Cancels a pending {@link RootsPanelController.surfaceDetached} — see there for why unmounting is not by
+     * itself "the page was closed".
+     */
+    readonly surfaceAttached: () => void;
+    /**
+     * Tell the controller the settings surface went away.
+     *
+     * **Not** "close the editor": the platform re-registers this section whenever its inject face changes, and
+     * opening the editor is such a change, so the component unmounts and remounts as a normal part of opening
+     * it. Closing the settings page looks the same except that **nothing remounts**. The two are told apart in
+     * time: the clear is deferred by one task, and a remount cancels it (audit 0091).
+     */
+    readonly surfaceDetached: () => void;
+    /** Stop accepting results and drop listeners. */
+    readonly dispose: () => void;
+}
+/** What a controller needs: the one call, plus the one scheduling choice. */
+export interface RootsPanelControllerOptions {
+    readonly api: RootsApi;
+    /**
+     * Defer one task and return its canceller.
+     *
+     * Injectable so {@link RootsPanelController.surfaceDetached} is testable without timers: the policy it
+     * encodes ("did anything remount before this ran?") is the whole point, and a test that has to wait on a
+     * real `setTimeout` would be both slow and flaky.
+     */
+    readonly defer?: (run: () => void) => () => void;
+}
+/**
+ * Build the stateful half of the panel.
+ *
+ * The refresh-after-success is the reason this exists at all: `POST` answers with the *persisted* state,
+ * whose `roots` are the user's roots  - the same field name `GET` uses for the *config* roots. Rendering that
+ * answer directly would show a config root as a user root (or the reverse), so a success always ends with a
+ * fresh `GET` and the POST body is used only as a signal.
+ *
+ * @param options - the injected API.
+ * @returns the controller the container subscribes to.
+ */
+export declare function createRootsPanelController(options: RootsPanelControllerOptions): RootsPanelController;
+/**
+ * The section's callbacks, derived from the controller.
+ *
+ * A factory rather than an inline object literal so the shell can `useMemo(() => rootsPanelSectionActions(controller),
+ * [controller])` — stable props are the precondition for ever putting `memo` on the two child components — **and**
+ * so "each callback really drives the controller" is a decision a test can hold on to (audit 2026-11-01b ui P3-7).
+ *
+ * @param controller - the panel's controller.
+ * @returns the callbacks the pure template calls.
+ */
+export declare function rootsPanelSectionActions(controller: RootsPanelController): RootsPanelSectionActions;
+/** What the section's controls call. All of them are no-ops when the gate is closed. */
+export interface RootsPanelSectionActions {
+    readonly onDraftChange: (patch: RootsPanelDraftPatch) => void;
+    /** One field of the edit dialog changed (its own draft set). */
+    readonly onEditDraftChange: (patch: RootsPanelEditDraftPatch) => void;
+    readonly onSubmitRoot: (location: RootLocation) => void;
+    readonly onSubmitConnection: () => void;
+    readonly onRemove: (key: string) => void;
+    readonly onSubmitEdit: () => void;
+    readonly onCancelEdit: () => void;
+    /** FR-2.1.4: the ssh-config import dialog's controls. */
+    readonly onImportOpen: () => void;
+    readonly onImportClose: () => void;
+    readonly onImportReload: () => void;
+    readonly onImportToggle: (alias: string) => void;
+    readonly onImportAll: () => void;
+    readonly onImportNone: () => void;
+    readonly onImportSubmit: () => void;
+}
+/**
+ * The `~/.ssh/config` import dialog (FR-2.1.4).
+ *
+ * Three things it deliberately does:
+ *
+ *  - **It shows the refusals.** Every alias the host would not offer is listed with the reason, because the
+ *    user is looking at their own config file and can see the entry that is missing from the list. A silent
+ *    subset reads as a broken feature.
+ *  - **It shows the id each alias will become.** `deploy@bastion` is a valid alias and not a valid id, so the
+ *    dialog says what the id will be instead of letting `add-connection` refuse it later.
+ *  - **It never shows an identity path.** The host answers `hasIdentityFile` as a boolean; the path itself is
+ *    not on the wire (the route's invariant 1), so nothing here can leak one.
+ *
+ * @param props - copy, state and callbacks.
+ * @returns the dialog, or nothing when it is closed.
+ */
+export declare function SshConfigImportDialog({ copy, state, actions, idPrefix }: RootsPanelSectionProps): ReactNode;
+/**
+ * The **edit** form for one saved connection.
+ *
+ * It exists as its own component because it is the one form whose fields are prefilled from a host answer: the
+ * panel's top list renders the row buttons that open it, and this renders what those buttons open. Splitting
+ * them keeps `RootsPanelSection` about the roots it owns and this about one connection.
+ *
+ * Two rules it inherits and one it adds:
+ *
+ *  - **Nothing is submitted before validation** ({@link validateConnectionEdit} is the only way in);
+ *  - **no credential is ever rendered**  -  the password box is always empty, because no answer carries a
+ *    secret back, and an empty box means "keep the stored password" (see the key's own note);
+ *  - **the id is editable, and the rename is explained**: a rename re-keys the connection's remote roots and
+ *    is therefore not a cosmetic field, so the form says so rather than leaving it to be discovered.
+ *
+ * @param props - copy, state and callbacks.
+ * @returns the form, or nothing when no connection is open for editing.
+ */
+export declare function ConnectionEditForm({ copy, state, actions, idPrefix }: RootsPanelSectionProps): ReactNode;
+/** Props of the pure template: state in, callbacks out, no hooks and no store access. */
+/**
+ * The `id` prefix the pure templates use when the shell does not pass one (direct template calls, tests).
+ *
+ * The shell always passes `useId()`'s value instead, so the ids are **per mount** — see
+ * {@link RootsPanelSectionProps.idPrefix}.
+ */
+export declare const DEFAULT_ROOTS_ID_PREFIX = "dsh-rw-roots";
+export interface RootsPanelSectionProps {
+    readonly copy: RootsPanelCopy;
+    readonly state: RootsPanelState;
+    readonly actions: RootsPanelSectionActions;
+    /**
+     * `id` prefix for this mount's form controls (`{prefix}-edit-host`, `{prefix}-import-<alias>`, …).
+     *
+     * A module constant was enough while there was exactly one section on one page, and it stopped being enough
+     * the moment the platform started re-registering the section on every inject-face change: for one commit the
+     * old mount and the new one are both in the DOM, so two inputs share an `id` and every `<label for>` in the
+     * overlap points at whichever one the browser found first. `useId()` in the container makes that impossible.
+     *
+     * Optional only so the offline view tests can call these templates directly (audit 2026-10-31 client.md §2.4).
+     */
+    readonly idPrefix?: string;
+    /**
+     * The body-level portal the connection **edit dialog** is rendered into.
+     *
+     * Optional on purpose: the pure template is called directly by the offline view tests (and by any caller
+     * without a DOM), where the card is rendered in place. The shell always passes one, so the real UI gets a
+     * card that floats over the settings page instead of being pushed below the "新增连接" form (audit 0088).
+     */
+    readonly portal?: CardPortal;
+}
+/**
+ * Props of the whole settings section.
+ *
+ * It is {@link RootsPanelSectionProps} plus the one element that needs the container: the transfer progress
+ * panel. The remote file **tree** is not here at all: it was deleted (audit 0085) because remote paths are
+ * reached through the conversation, and because this function is called **directly** by the view tests,
+ * outside any React render, where a hook throws `Invalid hook call` (the constraint documented in
+ * `controls.ts`).
+ */
+export interface RootsPanelSectionViewProps extends RootsPanelSectionProps {
+    /** The transfer progress panel element, or `undefined` in a template-only render. */
+    readonly transfers?: ReactNode;
+}
+/**
+ * Render the editable section. Pure: calling it twice with the same props yields the same tree.
+ *
+ * @param props - copy, state and callbacks.
+ * @returns the section element.
+ */
+export declare function RootsPanelSection({ copy, state, actions, transfers, portal, idPrefix, }: RootsPanelSectionViewProps): ReactNode;
+/** Props of the React shell: the controller owns the state, the shell only subscribes. */
+export interface RootsPanelContainerProps {
+    readonly copy: RootsPanelCopy;
+    readonly controller: RootsPanelController;
+}
+/**
+ * Subscribe to a controller and render {@link RootsPanelSection}.
+ *
+ * `useSyncExternalStore` is the whole reason this is a component and not a function call: the slot's inject
+ * face is a synchronous snapshot, so the section has to be re-rendered by the store it reads.
+ *
+ * The right-pane entry point is the one piece of state this shell owns itself: whether the composition
+ * publishes the right sidebar is not a fact the controller's store carries (it is answered live by the entry
+ * point), and an open that failed after the button was enabled must say so somewhere. Both are re-read on
+ * every render, which is exactly when a `ctx.get` seam can have changed.
+ *
+ * @param props - the dictionary and the controller.
+ * @returns the section element.
+ */
+export declare function RootsPanelContainer({ copy, controller }: RootsPanelContainerProps): ReactNode;

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

@@ -0,0 +1,364 @@
+/**
+ * The roots panel's whole decision surface: wire parsing, the HTTP calls to the host route, input validation
+ * and the view model. **No React, no DOM, no `@deepseek-ai/*`** — the component renders what this module
+ * returns and nothing else, which is what makes the panel testable without a browser (红线 2).
+ *
+ * Two rules this module owns:
+ *
+ *  1. **No credentials, ever.** {@link parseRootsSnapshot} copies field by field and drops anything else, so a
+ *     host answer that leaked `keyPath` / `password` still cannot reach the DOM. The host route filters its
+ *     side; this is the client's half of the same rule.
+ *  2. **Password authentication is not editable here.** A password must never round-trip through a browser
+ *     form and a same-origin POST, so {@link validateConnectionDraft} refuses it outright rather than
+ *     growing a field that leaks secrets into web storage.
+ *
+ * @module dsh-over-ssh/client/roots-panel
+ */
+import type { MessageKey } from '../core/message.ts';
+/**
+ * Where the host route lives, as the browser must request it.
+ *
+ * **Relative on purpose, and this is the platform's own convention.** The GUI is served from two different
+ * origins depending on the carrier, and only a relative path is correct in both:
+ *
+ *  - `dsh web` (browser): the page origin *is* the host, so `/api/…` reaches
+ *    `ctx.webServer` directly;
+ *  - the Desktop shell: the page is `dsh-app://app/` and `/api/…` resolves to
+ *    `dsh-app://app/api/…`, which Electron's `protocol.handle('dsh-app')` forwards to the owned host with
+ *    the browser-session cookie the shell keeps out of the page
+ *    (`resources/app.asar/lib/main.js`, `forwardWebRequest`: non-asset paths are proxied with
+ *    `headers.set('cookie', cookie)`; `serveWebDocument` never sees `/api/…`).
+ *
+ * The absolute host origin (`globalThis.__DSH_TRANSPORT__.streamBaseUrl`) is deliberately **not** used here:
+ * the shell strips `set-cookie` from proxied responses and the session cookie is host-only + `HttpOnly`, so
+ * a direct fetch to the host origin cannot authenticate — it would turn a working request into a 401. The
+ * platform uses that origin for the WebSocket only (`dsh-api-gateway`, `REMOTE_STREAM_MUX_PATH`), and its
+ * own HTTP callers resolve against `document.baseURI` (`dsh-client-file-upload`, `new URL(request.path,
+ * document.baseURI)`).
+ */
+export declare const ROOTS_API_PATH = "/api/over-ssh/roots";
+/** A root either lives on this machine or behind a connection. */
+export type RootLocation = 'local' | 'remote';
+/** One root as the panel shows it. */
+export interface RootRow {
+    /** Stable identity: `<location>:<connectionId or '-'>:<path>`. */
+    readonly key: string;
+    readonly location: RootLocation;
+    readonly path: string;
+    readonly connectionId?: string;
+    readonly label?: string;
+    readonly writable: boolean;
+    /** `config` rows come from the profile patch; `user` rows were added in this panel. */
+    readonly source: 'config' | 'user';
+    /** Whether this root also appears in the panel's own file — only those may be deleted. */
+    readonly inUserFile: boolean;
+    /**
+     * The workspaces that list this root; absent means **no session lists it yet**.
+     *
+     * The composer's card shows exactly the roots whose list names its own workspace (one session must not
+     * inherit another's directories). The settings panel ignores it, because that panel manages the whole list
+     * and registers roots with **no** scope of its own — its form has no `workspaces` member (`RootsPanelDrafts`),
+     * so a root added there is not listed by any session until one adds it (audit 0056).
+     */
+    readonly workspaces?: readonly string[];
+    /**
+     * The **sessions** that added this root (ADR-0013); absent on entries written before it.
+     *
+     * The composer's card prefers this over `workspaces`: two conversations opened on the same directory share
+     * the workspace path and differ only here.
+     */
+    readonly sessions?: readonly string[];
+}
+/** A connection, narrowed to what the panel may display. **No credential fields exist on this type.** */
+export interface ConnectionSummary {
+    readonly id: string;
+    readonly host: string;
+    readonly user?: string;
+    readonly port?: number;
+    readonly authKind: 'agent' | 'key' | 'password';
+    /**
+     * The transport in force, **when the host reports it**.
+     *
+     * `publicRoot`/`publicUserState` do not carry it today (the transport is a live fact of the platform's remote
+     * namespace, not of the profile), so production answers leave this `undefined` and the panel says 「未知」
+     * rather than claiming `unknown` — but a host that starts publishing it is honoured without another round
+     * (audit 2026-11-01b ui P2-6).
+     */
+    readonly transport?: ConnectionTransport;
+    /** True when that transport is a degraded substitute, when the host reports it. */
+    readonly degraded?: boolean;
+}
+/** The transports a connection row may name; `unknown` means "the host did not say". */
+/**
+ * Re-exported from `core/panel-model.ts`, which **owns** it: `core` must not depend on `roots`, so the
+ * definition lives in the lower layer and this file points up at it. `export type {…} from` alone does not put
+ * the name in this module's scope, hence the separate `import type` as well.
+ */
+export type { ConnectionTransport } from '../core/panel-model.ts';
+import type { ConnectionTransport } from '../core/panel-model.ts';
+/** Everything one GET answers. */
+export interface RootsSnapshot {
+    readonly roots: readonly RootRow[];
+    readonly connections: readonly ConnectionSummary[];
+    readonly warnings: readonly string[];
+    /**
+     * The plugin's anchor root (`<home>/.dsh/over-ssh/roots`), when the host publishes one.
+     *
+     * Not a row: it is what lets a client recognise that a session's cwd *is* a remote workspace (see
+     * `client/session-remote-mark.ts`). Absent means "the host did not say", and every caller must treat that
+     * as unknown rather than as "no remote sessions".
+     */
+    readonly anchorRoot?: string | undefined;
+}
+/** The outcome of one call: the panel never throws on a host failure, it shows it. */
+export type ApiResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/** What this module needs from `fetch`; injected so tests run without a server (红线 3). */
+export type FetchLike = (input: string, init?: {
+    readonly method?: string;
+    readonly headers?: Record<string, string>;
+    readonly body?: string;
+    readonly signal?: AbortSignal;
+}) => Promise<{
+    readonly ok: boolean;
+    readonly status: number;
+    json: () => Promise<unknown>;
+}>;
+/**
+ * A message is a key plus its parameters; the component resolves it against the locale dictionaries.
+ *
+ * The shape (and the resolver, `resolveMessage`) live in `../core/message.ts` because the session panel and the
+ * transfer panel produce messages too, and both are pure models that must not import React. Re-exported here so
+ * every existing `import { MessageKey } from './roots-panel.ts'` keeps working.
+ */
+export type { MessageKey };
+/** A validated draft, or the reason it was refused. */
+export type Validation<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly message: MessageKey;
+};
+/** The payload the panel sends to add a root. */
+export interface RootDraft {
+    readonly location: RootLocation;
+    readonly path: string;
+    readonly connectionId?: string;
+    readonly label?: string;
+    readonly writable?: boolean;
+}
+/**
+ * The transport a connection record asks for.
+ *
+ * It stays in the wire payload type because the host still accepts and persists it, but the **panel no
+ * longer offers a choice**: every save asks for `agent`, and the host's selector/preflight degrades to the
+ * zero-install transports automatically when the Tier 2 ladder cannot serve the connection. Keeping the type
+ * here documents what the payload can contain without re-opening the UI decision.
+ */
+export type ConnectionTransportChoice = 'alias' | 'ssh2' | 'agent';
+/**
+ * The payload the panel sends to add a connection.
+ *
+ * `password` is the **only** secret this client ever holds, and only long enough to post it: the host writes
+ * it into `ctx.credentials` and answers with a projection that never contains it (FR-2.1.2).
+ */
+export interface ConnectionDraft {
+    readonly id: string;
+    readonly host: string;
+    readonly user: string;
+    readonly authKind: 'agent' | 'key' | 'password';
+    /**
+     * The transport the payload asks for.
+     *
+     * Always `agent` now: the panel offers no choice, and the host degrades automatically. Kept in the payload
+     * (rather than omitted) so an older record's `alias`/`ssh2` is rewritten to the preferred path on the first
+     * save, and so the host keeps the "always explicit" contract it already validates.
+     */
+    readonly transport?: ConnectionTransportChoice;
+    readonly keyPath?: string;
+    readonly password?: string;
+    readonly port?: number;
+}
+/** The identity the host also uses, so removals address the same row the list shows. */
+export declare function rootKey(location: RootLocation, path: string, connectionId?: string): string;
+/**
+ * Narrow one GET answer to the panel's model, field by field.
+ *
+ * Unknown fields are dropped rather than copied: an answer carrying `keyPath` reaches the DOM only as a
+ * missing field, never as a value. A malformed answer becomes an empty snapshot with a warning instead of a
+ * throw — a broken channel must degrade the panel, not break the whole settings page.
+ *
+ * @param value - the parsed JSON the route answered with.
+ * @returns a snapshot that is safe to render.
+ */
+export declare function parseRootsSnapshot(value: unknown): RootsSnapshot;
+/** True when a string is an absolute path this machine can open (drive letter, POSIX root, or UNC). */
+export declare function isAbsoluteLocalPath(path: string): boolean;
+/**
+ * Refuse a draft before it becomes a request.
+ *
+ * @param draft - what the form holds.
+ * @param existing - roots already shown, to reject a duplicate.
+ * @returns the wire payload, or the message key to show next to the field.
+ */
+export declare function validateRootDraft(draft: RootDraft, existing?: readonly RootRow[]): Validation<RootDraft>;
+/**
+ * Refuse a connection draft before it becomes a request.
+ *
+ * The id rule is the **host's** rule (a user-chosen name, Chinese included), so the panel refuses exactly
+ * what `path-grammar.ts` would refuse instead of sending a request that comes back 400.
+ *
+ * Password auth is supported: the draft carries the password once, the host stores it in `ctx.credentials`,
+ * and nothing in any answer ever carries it back (FR-2.1.2).
+ *
+ * The payload always carries `transport: 'agent'`: the panel no longer offers a choice, and the host downgrades
+ * automatically when the Tier 2 ladder cannot serve this connection.
+ *
+ * @param draft - what the form holds.
+ * @param existing - connections already shown, to reject a duplicate id.
+ * @returns the wire payload, or the message key to show next to the field.
+ */
+export declare function validateConnectionDraft(draft: ConnectionDraft, existing?: readonly ConnectionSummary[]): Validation<ConnectionDraft>;
+/**
+ * Refuse an **edit** draft before it becomes a request.
+ *
+ * The same rules as {@link validateConnectionDraft} for every field, with the three differences an edit
+ * needs, and each one exists for a reason:
+ *
+ *  1. **A rename is allowed but must not collide with a *different* connection.** Uniqueness is checked
+ *     against the rows except the one being edited  -  `validateConnectionDraft` cannot express that, and using
+ *     it here would refuse every save that kept the id.
+ *  2. **An empty password means "do not touch the stored secret", not "refuse".** No answer ever carries a
+ *     secret back, so the form's password box is always empty on render; requiring it would make it
+ *     impossible to change a host without retyping the password, and treating empty as "clear" would delete
+ *     the password on every unrelated edit. The field is therefore **omitted** from the payload unless the
+ *     user typed one, which is exactly how the host reads it.
+ *  3. **`keyPath` follows the same rule as the password: blank means "keep the stored one".** The panel
+ *     cannot prefill it, because the host's answer deliberately never carries a `keyPath` (it names a real
+ *     file). Refusing a blank one would therefore make it impossible to edit a key connection's host without
+ *     retyping its private-key path, and *filling* it with a guess would silently repoint the connection.
+ *     So it is omitted unless the user typed one  -  the host's merge keeps what is stored.
+ *
+ * @param draft - what the form holds.
+ * @param originalId - the id of the connection being edited (the lookup key the host needs).
+ * @param existing - connections already shown, to reject a colliding rename.
+ * @returns the wire payload, or the message key to show next to the field.
+ */
+export declare function validateConnectionEdit(draft: ConnectionDraft, originalId: string, existing?: readonly ConnectionSummary[]): Validation<Record<string, unknown>>;
+/** One row as the component renders it. */
+export interface RootRowView {
+    readonly key: string;
+    readonly location: RootLocation;
+    readonly title: string;
+    readonly subtitle: string;
+    readonly badgeKey: string;
+    readonly removable: boolean;
+}
+/** The panel's complete render input. */
+export interface RootsView {
+    readonly rows: readonly RootRowView[];
+    readonly connections: readonly ConnectionSummary[];
+    /** Set when the host did not answer, so the panel can say why instead of looking empty. */
+    readonly notice?: MessageKey;
+    /** False while a request is in flight, so the form cannot double-submit. */
+    readonly canEdit: boolean;
+}
+/**
+ * Turn a snapshot (or the failure to get one) into render input.
+ *
+ * @param input - the last answer, or the last error, plus whether a request is running.
+ * @returns rows, connections, notice and the edit gate.
+ */
+export declare function buildRootsView(input: {
+    readonly snapshot?: RootsSnapshot;
+    readonly error?: string;
+    readonly pending?: boolean;
+}): RootsView;
+/** The calls the panel makes. */
+export interface RootsApi {
+    load(signal?: AbortSignal): Promise<ApiResult<RootsSnapshot>>;
+    send(body: Record<string, unknown>): Promise<ApiResult<RootsSnapshot>>;
+    /**
+     * A POST whose answer is **not** a snapshot.
+     *
+     * The import actions answer a candidate list and an import report, neither of which is a roots snapshot. It
+     * is a separate method rather than a looser return type on {@link RootsApi.send} so that every existing call
+     * keeps the snapshot it already depends on: widening `send` would make `state` optional for all of them.
+     */
+    sendRaw(body: Record<string, unknown>): Promise<ApiResult<Record<string, unknown>>>;
+}
+/** One importable `~/.ssh/config` alias, as the import dialog renders it. */
+export interface SshConfigCandidate {
+    /** The literal alias; also the `ssh` target. Shown verbatim so the user recognises their own config. */
+    readonly alias: string;
+    /** Resolved host name. */
+    readonly host: string;
+    readonly user?: string;
+    readonly port?: number;
+    /** Whether the block named an identity file. The path itself never reaches the client. */
+    readonly hasIdentityFile: boolean;
+    readonly hasProxyJump: boolean;
+    /** The id the import would create. Editable in spirit: the user sees it before committing. */
+    readonly suggestedId: string;
+}
+/** One alias the host refused, with the machine-readable reason. */
+export interface SshConfigSkipped {
+    readonly pattern: string;
+    readonly reason: string;
+    readonly line: number;
+}
+/** What `list-ssh-config` answers. */
+export interface SshConfigListing {
+    readonly candidates: readonly SshConfigCandidate[];
+    readonly skipped: readonly SshConfigSkipped[];
+}
+/**
+ * Narrow the host's `list-ssh-config` answer.
+ *
+ * Defensive in the same way {@link parseRootsSnapshot} is: the client never trusts the wire's shape, and a row
+ * without a usable alias or id is **dropped** rather than rendered as a checkbox that would import nothing.
+ *
+ * @param value - the parsed JSON body.
+ * @returns the listing, with unusable rows removed.
+ */
+export declare function parseSshConfigListing(value: unknown): SshConfigListing;
+/**
+ * The human-readable reason one alias was refused.
+ *
+ * The mapping lives here rather than in the view so the reasons are testable without rendering, and an unknown
+ * reason from a newer host still produces a sentence instead of an empty cell.
+ *
+ * @param reason - the machine-readable reason.
+ * @returns a message key.
+ */
+export declare function sshConfigSkipKey(reason: string): string;
+/** A candidate's one-line summary: `user@host:port`, with the flags that matter for the import. */
+export declare function sshConfigCandidateSummary(candidate: SshConfigCandidate): string;
+/**
+ * The reason a failed response reports, when the host did not name one.
+ *
+ * The path is part of the text on purpose: `http-404` alone cannot distinguish "this route is not
+ * registered" (the host half never claimed it — that was a real defect) from "the request never reached the
+ * host" (the shell's proxy or the composition is at fault). Both are shown verbatim in the panel's notice.
+ *
+ * @param status - the HTTP status.
+ * @param path - the exact URL that was requested.
+ * @returns the machine-readable reason.
+ */
+export declare function transportFailureReason(status: number, path: string): string;
+/**
+ * Bind the route to the panel's two operations.
+ *
+ * @param fetchImpl - `window.fetch` in the app, a stub in tests.
+ * @param path - override for tests; defaults to {@link ROOTS_API_PATH}.
+ * @returns the calls the component uses.
+ */
+export declare function createRootsApi(fetchImpl: FetchLike, path?: string): RootsApi;
+/** The field names the panel must never send, asserted by tests rather than trusted to reviewers. */
+export declare function isForbiddenField(name: string): boolean;