dsh-over-ssh 0.0.0-stage → 0.1.0

package/lib/types/src/client/core/latest.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The "only the newest answer may land" gate.
+ *
+ * Why a module instead of a `let token = 0` in each caller: this repository's client tests **cannot render a
+ * React component** (no `react-dom`, see [`portal.ts`](./portal.ts)), so a generation counter written inside a
+ * component's `useCallback` is a decision no test can reach. Extracting it makes "a late answer is dropped"
+ * something a test can hold on to, which is the same reason `actionQueryKey` / `rootsQueryKey` /
+ * long-poll re-arms exist.
+ *
+ * The three call sites share one failure mode: two requests are in flight, the **older** one answers last, and
+ * its answer overwrites the newer state. That is not a theoretical race here — every one of these surfaces has
+ * a button that starts a second request while the first is still open (a refresh during an action, a re-read
+ * after a scope change, a poll racing a manual refresh).
+ *
+ * ```text
+ * const gate = createLatestOnly();
+ * const mine = gate.begin();
+ * const answer = await call();
+ * if (!gate.isCurrent(mine)) return;   // a newer request owns the surface now
+ * ```
+ *
+ * @module dsh-over-ssh/client/latest
+ */
+/** A monotonic gate that admits only the most recently issued request. */
+export interface LatestOnly {
+    /**
+     * Issue a new request id.
+     *
+     * @returns the id this request must present when it answers.
+     */
+    begin(): number;
+    /**
+     * Whether an issued id is still the newest.
+     *
+     * @param token - the id `begin` returned to the request that is answering.
+     * @returns `true` only for the newest id; every earlier one is stale.
+     */
+    isCurrent(token: number): boolean;
+}
+/**
+ * Build a gate.
+ *
+ * Ids start at 1, so `0` (a value a caller can get from an uninitialised variable) is never "current" by
+ * accident.
+ *
+ * @returns the gate.
+ */
+export declare function createLatestOnly(): LatestOnly;

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

@@ -0,0 +1,38 @@
+/**
+ * Client-half copy for the `over-ssh` namespace.
+ *
+ * Registration is the **typed** form of `ctx.locale.register`: the namespace is merged into
+ * `LocaleNamespaceMap`, so a missing key in either shipped locale is a compile error, and the runtime
+ * additionally requires both locales at registration (bilingual balance). Keeping the dictionaries in a
+ * pure module is what makes them testable without a browser.
+ *
+ * @module dsh-over-ssh/client/locale
+ */
+/** Namespace owned by this plugin's client half. */
+export declare const OVER_SSH_NS = "over-ssh";
+/**
+ * Keys of this namespace.
+ *
+ * `LocaleNamespaceMap` maps a namespace to its **key union** (not to a value interface): the runtime then
+ * derives `Record<Key, string>` per locale, which is exactly what makes a missing translation a compile
+ * error.
+ */
+export type OverSshKey = 'sectionTitle' | 'sectionDescription' | 'noHostData'
+/** The connection list's own heading / empty state / unknown-transport badge (audit ui P2-6, P2-7). */
+ | 'connectionsHeading' | 'connectionsEmpty' | 'connectionsTransportUnknown' | 'close' | 'rootsTitle' | 'rootsDescription' | 'rootsAdvancedSummary' | 'rootsAdvancedNote' | 'rootsEmpty' | 'rootsPending' | 'rootsAuthPassword' | 'rootsPasswordLabel' | 'rootsTestConnection' | 'rootsTesting' | 'rootsTestOk' | 'sessionPanelTitle' | 'sessionPanelDescription' | 'sessionPanelUnavailable' | 'sessionPanelLoading' | 'sessionPanelLoadFailed' | 'sessionPanelSessionsEmpty' | 'sessionPanelSessions' | 'sessionPanelBin' | 'sessionPanelBinEmpty' | 'sessionPanelSelectAll' | 'sessionPanelClear' | 'sessionPanelDeleteRecycle' | 'sessionPanelDeletePermanent' | 'sessionPanelRestore' | 'sessionPanelPurge' | 'sessionPanelSweep' | 'sessionPanelRefresh' | 'sessionPanelClose' | 'sessionPanelLive' | 'sessionPanelSubsession' | 'sessionPanelUnreadable' | 'sessionPanelConfirmTitle' | 'sessionPanelConfirmBody' | 'sessionPanelConfirmPurgeBody' | 'sessionPanelConfirmCancel' | 'sessionPanelConfirmAccept' | 'sessionPanelDeleteWorkspace' | 'sessionPanelConfirmWorkspaceBody' | 'sessionPanelSubsessionsHidden' | 'sessionPanelTotals' | 'sessionPanelOpen' | 'sessionPanelLiveWarning' | 'sessionRowRecycle' | 'sessionRowDelete' | 'sessionRowRecycleBody' | 'sessionRowDeleteBody' | 'sessionRowConfirmRecycle' | 'sessionRowConfirmDelete' | 'sessionRowCancel' | 'sessionRowClose' | 'sessionRowLoading' | 'sessionRowBlockedRunning' | 'sessionRowBlockedSubsession' | 'sessionRowBlockedUnreadable' | 'sessionRowMissing' | 'sessionRowUnavailable' | 'rootsTestDegraded' | 'rootsTestFailed' | 'rootsAddConnection' | 'rootsRemove' | 'rootsSave' | 'rootsEdit' | 'rootsEditTitle' | 'rootsEditSave' | 'rootsEditCancel' | 'rootsEditPasswordHint' | 'rootsEditRenameHint' | 'rootsConfirmRemoveTitle' | 'rootsConfirmRemoveBody' | 'rootsConfirmRemoveAccept' | 'rootsConfirmRemoveCancel' | 'rootsConnection' | 'rootsConnectionPlaceholder' | 'rootsRemotePathLabel' | 'rootsIdLabel' | 'rootsHostLabel' | 'rootsUserLabel' | 'rootsAuthLabel' | 'rootsAuthKey' | 'rootsKeyPathLabel' | 'rootsPortLabel' | 'rootsBadgeLocal' | 'rootsBadgeRemote' | 'rootsErrorPathRequired' | 'rootsErrorRemotePath' | 'rootsErrorConnectionRequired' | 'rootsErrorLocalPath' | 'rootsErrorDuplicate' | 'rootsErrorIdRequired' | 'rootsErrorIdInvalid' | 'rootsErrorIdDuplicate' | 'rootsErrorHostRequired' | 'rootsErrorUserRequired' | 'rootsErrorPort' | 'rootsImportTitle' | 'rootsImportDescription' | 'rootsImportOpen' | 'rootsImportEmpty' | 'rootsImportRefresh' | 'rootsImportSelectAll' | 'rootsImportClear' | 'rootsImportAccept' | 'rootsImportCancel' | 'rootsImportBusy' | 'rootsImportDone' | 'rootsImportIdHint' | 'rootsImportSkippedTitle' | 'rootsImportSkipWildcard' | 'rootsImportSkipDuplicate' | 'rootsImportSkipTaken' | 'rootsImportSkipUnusableId' | 'rootsImportSkipNotImportable' | 'rootsImportSkipUnknown' | 'rootsImportHasKey' | 'rootsImportHasJump' | 'transferTitle' | 'transferDescription' | 'transferEmpty' | 'transferLoading' | 'transferRefresh' | 'transferClear' | 'transferFailedTitle' | 'transferDone' | 'transferCancelled' | 'transferUploadLabel' | 'transferDownloadLabel' | 'transferFailed' | 'transferFailedHttp' | 'transferFailedHost' | 'transferFailureLine' | 'transferErrorCodeUnknown' | 'remoteFilesHint' | 'rootsImportFailed' | 'rootsErrorKeyPathRequired' | 'rootsErrorPasswordRequired' | 'rootsNoticeUnavailable' | 'rootsNoticeWarnings' | 'rootsNoticeSavedConnection' | 'rootsNoticeSavedEdit' | 'flowTitle' | 'flowDescription' | 'flowLocalHeading' | 'flowLocalHint' | 'flowPickFailed' | 'flowRemoteHeading' | 'flowRemoteHint' | 'flowConfirmRemote' | 'flowCancel' | 'flowPending' | 'flowBusy' | 'flowNoConnections' | 'flowConnectionsLoading' | 'flowNoAnchor' | 'flowUnavailable' | 'browseHeading' | 'browseUp' | 'browseHome' | 'browseCurrent' | 'browseEmpty' | 'browseLoading' | 'browseRetry' | 'browseFailed' | 'browseUnavailable' | 'browseNeedConnection' | 'browseTruncated'
+/** The remote world's connection list: reading, and failed-with-reason (audit 2026-11-01b ui P2-4). */
+ | 'browseConnectionsLoading' | 'browseConnectionsFailed' | 'browseKindFile' | 'browseKindSymlink' | 'browseKindOther' | 'browseLocalMode' | 'browsePickNative' | 'browseRemoteMode' | 'browseOpenLocal' | 'browseOpenRemote' | 'browseChoose' | 'sessionAddOpen' | 'sessionAddTitle' | 'sessionAddHint' | 'sessionAddWorkspace' | 'sessionAddWorkspaceUnknown' | 'sessionAddPick' | 'sessionBrowse' | 'sessionBrowseBack' | 'sessionRootsTitle' | 'sessionRootsEmpty'
+/** The session entry's card while it reads its directory list (the empty state must not be shown then). */
+ | 'sessionRootsLoading' | 'sessionRootsHint' | 'sessionRootsFailed' | 'sessionAddDone' | 'sessionAddFailed' | 'sessionResultNoSelection' | 'sessionResultMissingCwd' | 'sessionResultMissingEntryId' | 'sessionResultHttpFailed' | 'sessionResultHostRefused' | 'sessionResultActionFailed' | 'sessionResultUnreachable' | 'sessionResultDeletedPermanent' | 'sessionResultDeleteNone' | 'sessionResultRecycled' | 'sessionResultWorkspaceEmpty' | 'sessionResultWorkspacePurged' | 'sessionResultWorkspacePurgedRefused' | 'sessionResultWorkspaceRecycled' | 'sessionResultWorkspaceRecycledRefused' | 'sessionResultRestored' | 'sessionResultPurged' | 'sessionResultSweepNone' | 'sessionResultSweepDone' | 'sessionWorkspaceUnknown' | 'connectionTestNoAnswer' | 'connectionTestFailed' | 'connectionTestRefused'
+/** The probe ran out of the client's own deadline (no host sentence exists for it). */
+ | 'connectionTestTimeout' | 'transferSummaryRunning' | 'transferSummaryDone' | 'transferRemaining' | 'transferRemainingUnknown' | 'transferDurationUnknown' | 'rootsImportSummary' | 'rootsImportRefusedTitle' | 'rootsImportRefusedLine';
+/** Merge this plugin's namespace into the shared locale map, so `t('over-ssh.…')` is typed. */
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        'over-ssh': OverSshKey;
+    }
+}
+/** Every shipped locale's dictionary. Both `zh` and `en` are required by the runtime. */
+export declare const OVER_SSH_DICTS: Record<'zh' | 'en', Record<OverSshKey, string>>;
+/** Dictionary keys, so a completeness test never has to restate them. */
+export declare function overSshKeys(): readonly OverSshKey[];

package/lib/types/src/client/core/message.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Deferred copy: a dictionary key plus its parameters, and the one resolver for it.
+ *
+ * Why this is `core/` and not `roots/`: three modules need the same two lines — the roots panel model, the
+ * transfer panel and (since the audit) the session panel's result sentences — and two of them are **pure
+ * models** that must not import React. `roots/roots-panel-state.ts` used to own the resolver, which meant every
+ * pure model either imported a React-bearing module or (what actually happened) duplicated the six lines with a
+ * comment apologising for the duplication (`core/panel-model.ts`). One implementation, no React.
+ *
+ * The contract a dictionary keeps: a **missing** key renders as the key itself. That is deliberate — a missing
+ * translation must be visible in the UI, never silently blank (see `roots-panel-state.ts`'s original note).
+ *
+ * @module dsh-over-ssh/client/message
+ */
+/** A message is a key plus its parameters; a component resolves it against the active dictionary. */
+export interface MessageKey {
+    /** The dictionary key (an entry of `OverSshKey` for this plugin's own copy). */
+    readonly key: string;
+    /** Values for the template's `{name}` placeholders. */
+    readonly params?: Readonly<Record<string, string | number>>;
+}
+/**
+ * Substitute `{name}` placeholders in one template.
+ *
+ * @param template - the dictionary string.
+ * @param params - the values to substitute; an absent value leaves the placeholder in place.
+ * @returns the rendered text.
+ */
+export declare function resolveTemplate(template: string, params: Readonly<Record<string, string | number>> | undefined): string;
+/**
+ * Resolve one message against a dictionary.
+ *
+ * @param copy - the active locale's dictionary (a plain string map).
+ * @param message - the key plus optional parameters.
+ * @returns the rendered text, or `message.key` itself when the dictionary has no such key.
+ */
+export declare function resolveMessage(copy: Readonly<Record<string, string>>, message: MessageKey): string;

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

@@ -0,0 +1,134 @@
+/**
+ * The settings panel's pure logic and copy wiring.
+ *
+ * Two rules that keep a client component testable without a browser:
+ *
+ *  - **no `ctx` in components** (the platform contract): everything a component shows arrives through props;
+ *  - consequently all decision-making lives here, where Node can run it. The component is a template.
+ *
+ * The host data channel arrives as **untrusted wire data** (`unknown`), so the conversion below whitelists
+ * fields one by one: a leaked `keyPath` / `password` / `credentialKey` cannot reach the panel even if the host
+ * ever started sending one. That is the client half's half of the "no credentials over the channel" rule the
+ * host face also enforces.
+ *
+ * @module dsh-over-ssh/client/panel-model
+ */
+import type { OverSshKey } from './locale.ts';
+/**
+ * Transports a connection row can name; `unknown` means "the host did not say".
+ *
+ * Declared once, in the roots model the wire parser lives in, and re-exported here so both halves of the panel
+ * vocabulary agree (a second identical union is how `unknown` ended up rendered as a raw English word).
+ */
+/**
+ * How a connection reaches the host: `alias`/`ssh2` are Tier 1 (no agent), `agent` is Tier 2, `unknown` is
+ * "the host did not say".
+ *
+ * Defined **here**, in `core`, and re-exported by `roots/roots-panel.ts`, not the other way round: the
+ * dependency rule for this half is `core → roots → session → flows → entry`, and importing it from `roots`
+ * was a reverse edge that `tests/architecture.test.ts` caught (the panel model is what a caller without the
+ * editor imports, so it must not reach into a feature folder for a type it owns).
+ */
+export type ConnectionTransport = 'alias' | 'ssh2' | 'agent' | 'unknown';
+/** One connection line: what the user needs to know about a single saved connection. */
+export interface ConnectionRow {
+    /** Connection id (the profile key the user sees in `ssh://` paths). */
+    readonly id: string;
+    /** Host name as configured. */
+    readonly host: string;
+    /** Transport currently in force, or `unknown` before the first connection. */
+    readonly transport: ConnectionTransport;
+    /** Whether the current transport is a degraded substitute. */
+    readonly degraded: boolean;
+    /** Why: the degradation reason, else the decision's explanation, else "not connected yet". */
+    readonly note: string;
+    /**
+     * The row's badge text, already localized by whoever built the row.
+     *
+     * The template used to render {@link ConnectionRow.transport} raw, so every row carried a badge reading the
+     * English wire word `unknown` in the Chinese UI as well. `alias`/`ssh2`/`agent` are protocol names and stay as
+     * they are; only the "the host did not say" case needs a word, and it now arrives from the dictionary
+     * (audit 2026-11-01b ui P2-6).
+     */
+    readonly transportLabel?: string;
+    /**
+     * The 「测试」 button's state for this row, already localized; absent when the panel has no tester.
+     *
+     * The template stays copy-free (`panel.ts` renders text it is handed), and the strings are rebuilt on every
+     * re-registration, so a locale change re-renders them without any subscription here.
+     */
+    readonly test?: {
+        readonly status: 'idle' | 'running' | 'ok' | 'failed';
+        /** Button label: 「测试」, or 「测试中…」 while the probe runs. */
+        readonly label: string;
+        /** Result line; empty while running. */
+        readonly detail: string;
+    };
+    /**
+     * The row's own edit/delete labels, already localized; absent when the panel has no editor.
+     *
+     * Localized here rather than in the component for the same reason as {@link ConnectionRow.test}: the
+     * template renders strings it is handed and never looks up copy itself.
+     */
+    readonly actions?: {
+        readonly editLabel: string;
+        readonly removeLabel: string;
+    };
+}
+/** What the panel renders. */
+export interface PanelModel {
+    readonly title: string;
+    readonly description: string;
+    /** One line per connection; empty either before the host answered or when no connection is configured. */
+    readonly connections: readonly ConnectionRow[];
+    /** Heading of the connection list (it had none: the rows started right under the description). */
+    readonly connectionsHeading: string;
+    /** What an answered-but-empty list says (it used to render nothing at all). */
+    readonly connectionsEmpty: string;
+    /**
+     * Notice about the missing host data channel; empty once the host answered. An answered-but-empty list
+     * clears it too — "you configured no connection" and "the channel is not wired" are different facts, and
+     * the panel must not claim the second one when the first is true.
+     */
+    readonly notice: string;
+    readonly closeLabel: string;
+    /**
+     * The confirmation card's text for deleting one connection, or absent when the panel cannot delete.
+     *
+     * A function of the row because the sentence names the connection **and** how many remote roots go with it
+     * -  the fact that makes the confirmation necessary at all.
+     */
+    readonly confirmRemove?: {
+        readonly title: string;
+        readonly cancelLabel: string;
+        readonly acceptLabel: string;
+        readonly body: (row: ConnectionRow, remoteRoots: number) => string;
+    };
+}
+/**
+ * Convert the host's connection status payload into panel rows.
+ *
+ * Every field is read individually and type-checked; unknown fields (including any credential the host might
+ * ever add) are dropped rather than forwarded. A row without a usable `id` and `host` is skipped: an
+ * unidentifiable line is worse than a missing one.
+ *
+ * @param value - the remote call's value, exactly as it arrived over the wire.
+ * @returns the rows the panel may render, in the host's order.
+ */
+export declare function toConnectionRows(value: unknown): readonly ConnectionRow[];
+/**
+ * Build the panel model from one locale's dictionary.
+ *
+ * @param copy - the dictionary the caller resolved (`zh` or `en`, chosen by the locale runtime).
+ * @param options - `rows` are the connection lines the host channel produced; **omitted** means the channel
+ *   never answered, which is the only case that shows the notice.
+ * @returns everything the component needs, with no further lookups.
+ */
+export declare function buildPanelModel(copy: Record<OverSshKey, string>, options?: {
+    readonly rows?: readonly ConnectionRow[];
+    /**
+     * Whether the panel has an editor behind it. When true, rows carry their edit/delete labels and the model
+     * carries the removal confirmation; when false (the default) the page is read-only.
+     */
+    readonly editable?: boolean;
+}): PanelModel;

package/lib/types/src/client/core/portal.d.ts

@@ -0,0 +1,266 @@
+/**
+ * The **body-level portal**: the one place this plugin's cards are mounted outside the host's own layout.
+ *
+ * Why it has to exist, and why the previous "inline, narrow-first" plan was wrong: the
+ * `sidebar.workspaces.directoryFlow` hole renders **inside the sidebar's title row**, which is a flex row
+ * that clips its overflow. A card rendered in place there is a flex item, and a flex item is *shrunk*
+ * (`flex-shrink: 1`) before it ever overflows - `max-width: 100%` says nothing about shrinking, and the row
+ * does not wrap. The real screenshot after the last release showed exactly that: two or three vertical lines
+ * with a clipped "选择连接并填写". That is a fact about the real DOM, not a hypothesis, so the card has to
+ * leave the row: one container per mount, appended to the **injected** `document.body` while the interaction
+ * is open, removed again when it closes, and `position: fixed` inside it.
+ *
+ * Two rules this module keeps:
+ *
+ *  - **The DOM is injected.** {@link createCardPortal} takes the document; nothing here touches `document` at
+ *    module scope, so importing this module off-browser (Node's test runner, the host half) does nothing, and
+ *    every branch is driven by a fake in the offline tests.
+ *  - **One container per mount.** `mount()` and `unmount()` are idempotent: a re-render while the card is open
+ *    must not append a second container, and a double close must not remove the same node twice.
+ *
+ * `createPortal` comes from `react-dom`, which is **not** a dependency of this repository but *is* a client
+ * baseline external: `PLATFORM_MODULES` in `packages/client/web/src/platform.ts` names it among the modules
+ * the shell seeds into the frozen module table, and the loader calls every client factory as
+ * `factory(require)` with a `require` that looks a specifier up in that seed table first
+ * (`ClientModuleSystem.makeRequire`). The lookup below therefore goes through that same `require` instead of
+ * a static import, for one concrete reason: a static `import 'react-dom'` is evaluated when Node's test
+ * runner loads this module, and `react-dom` is not installed here - every offline client test would fail at
+ * import time. The lookup is lazy, and a runtime that cannot supply `react-dom` renders the card in place
+ * (the pre-portal behaviour) instead of failing, with one warning so the degradation is visible in a log.
+ *
+ * @module dsh-over-ssh/client/portal
+ */
+import type { ReactNode } from 'react';
+/** The part of `document` this module uses. Structural, so a fake document is a full citizen. */
+export interface PortalDocument {
+    /** The element a card container is attached to while the card is open. */
+    readonly body?: PortalContainer | null | undefined;
+    /** Whatever held focus when the card opened; the card gives focus back to it when it closes. */
+    readonly activeElement?: FocusTarget | null | undefined;
+    createElement(tag: string): PortalElement;
+    /**
+     * Present on a real document; the shell hangs its global key listener here.
+     *
+     * `options` exists for one caller: the settings-hosted card traps Tab in the **capture** phase. The platform's
+     * own modal layer listens on `document` in the bubble phase and, seeing focus outside its panel, pulls it back
+     * — a bubble listener of ours would run *after* it (registration order) and could no longer tell which field
+     * Tab came from. Capture runs first, so the card keeps the key it owns.
+     */
+    addEventListener?(type: 'keydown', listener: (event: PortalKeyEvent) => void, options?: boolean): void;
+    /** The other half of {@link addEventListener}. */
+    removeEventListener?(type: 'keydown', listener: (event: PortalKeyEvent) => void, options?: boolean): void;
+}
+/** One element the portal created. Only what the portal itself does with it is typed here. */
+export interface PortalElement {
+    /** The class attribute; the port has already been given its vocabulary classes when it is attached. */
+    className: string;
+    /** Present on a real element; used to move focus into the card. */
+    querySelector?(selector: string): FocusTarget | null | undefined;
+    /** Present on a real element; used by the Tab trap to list the card's controls in order. */
+    querySelectorAll?(selector: string): ArrayLike<FocusTarget> | null | undefined;
+}
+/**
+ * The part of a keyboard event the portal reads.
+ *
+ * Structural, like {@link KeyEventLike} in `./controls.ts`: the pure helpers are testable offline, and a real
+ * `KeyboardEvent` is assignable to it.
+ */
+export interface PortalKeyEvent {
+    /** The key name, e.g. `'Escape'` or `'Tab'`. */
+    readonly key?: string;
+    /** True while Shift is held: the Tab trap walks backwards. */
+    readonly shiftKey?: boolean;
+    /** Cancel the browser's own focus move when the trap takes over. */
+    preventDefault?(): void;
+    /** Stop the event before a modal layer behind the card sees it (see {@link trapCardTab}). */
+    stopPropagation?(): void;
+}
+/**
+ * The **one** shell every confirmation card is portalled into.
+ *
+ * A confirmation is the same object wherever it is raised: a sentence naming what will be destroyed, and two
+ * buttons. Three surfaces used to compose that object three ways (audit 2026-11-01b ui P2-8 / task-12 B1); this
+ * constant is the whole fix, together with {@link CONFIRM_BACKDROP_CLASS}.
+ */
+export declare const CONFIRM_PORTAL_CLASS: string;
+/**
+ * The confirmation's click sink.
+ *
+ * It uses the settings tier (1001) because the settings panel is one of the three raisers and its modal uses
+ * 900/1001; the overlay is above everything and sits at the same tier, so one constant is right for both.
+ */
+export declare const CONFIRM_BACKDROP_CLASS: string;
+/** The two operations the portal needs from `document.body`. */
+export interface PortalContainer {
+    appendChild(node: PortalElement): unknown;
+    removeChild(node: PortalElement): unknown;
+}
+/** Anything that can take focus; `document.activeElement` is one. */
+export interface FocusTarget {
+    focus?(): void;
+    readonly isConnected?: boolean;
+}
+/** Render a card somewhere else. The browser passes a function built on `react-dom`'s `createPortal`. */
+export type PortalRenderer = (children: ReactNode, container: unknown) => ReactNode;
+/**
+ * What a template needs to put its card in a portal: the container element (created from the injected
+ * document) and the renderer that fills it.
+ *
+ * The template never creates either of them - it only decides whether it has one. That keeps the templates
+ * pure element trees the offline tests walk, and makes "the card is not in the host container" an assertion
+ * about an injected fake rather than about React.
+ */
+export interface CardPortalTarget {
+    /** The body-level element the card is rendered into. */
+    readonly container: unknown;
+    /** Render the card into {@link container}. */
+    readonly render: PortalRenderer;
+}
+/** One mount's body-level container, plus its attach/detach lifecycle. */
+export interface CardPortal extends CardPortalTarget {
+    /**
+     * The click sink that sits **under** the card and counts as "the page behind the dialog".
+     *
+     * `undefined` when the caller asked for no backdrop, when there is no document, or when the runtime cannot
+     * portal at all (an in-place card has no modal geometry to protect). See {@link CreateCardPortalOptions.backdropClassName}.
+     */
+    readonly backdrop: PortalElement | undefined;
+    /** True while the container is attached to `document.body`. */
+    readonly mounted: boolean;
+    /** Attach the container; a second call while attached does nothing. */
+    mount(): void;
+    /** Detach the container; a second call while detached does nothing. */
+    unmount(): void;
+    /** Move focus to the card's first control. `false` when there is nothing focusable (or no DOM). */
+    focusCard(): boolean;
+}
+/** What {@link createCardPortal} needs: the injected document, the container's classes and the renderer. */
+export interface CreateCardPortalOptions {
+    /** The page's `document`, or `undefined` off-browser, where the whole portal is a no-op. */
+    readonly document: PortalDocument | undefined;
+    /** Classes of the body-level container (`CLASS.portal` plus one placement class). */
+    readonly className: string;
+    /** How the card is rendered into the container; the shells pass {@link renderInPortal}. */
+    readonly render: PortalRenderer;
+    /**
+     * Classes of the **backdrop**: the element this portal inserts under the card to swallow pointer input.
+     *
+     * Why it exists at all: the card claims `aria-modal="true"` and traps Tab, but the page behind it stayed
+     * *clickable* — the portal only ever created the card's own container, which hugs the card, so everywhere else
+     * the pointer reached the surface underneath. With the connection editor open that meant a click could land on
+     * the 「保存」 of the form behind it (and, before the drafts were split, submit the dialog's values as a new
+     * connection). A backdrop is the pointer half of the modal promise; the Tab trap is the keyboard half
+     * (audit 2026-11-01b ui P2-1).
+     *
+     * Optional so a caller that renders a **non-modal** card keeps the old behaviour, and so the offline portal
+     * tests can keep asserting the container lifecycle alone.
+     */
+    readonly backdropClassName?: string;
+}
+/**
+ * The selector of the first thing in a card that can take focus.
+ *
+ * Disabled controls are excluded, and so is a `tabindex="-1"` element (a programmatic focus target, not a
+ * user one): the point of the initial focus is that the next Tab goes somewhere sensible.
+ */
+export declare const CARD_FOCUS_SELECTOR = "button:not([disabled]), input:not([disabled]), select:not([disabled]), a[href], [tabindex]:not([tabindex=\"-1\"])";
+/**
+ * Create one mount's card portal.
+ *
+ * The container is created **eagerly** (a React portal needs its container during the commit that renders the
+ * card) but attached **lazily**: nothing is in the body until `mount()` runs, which the shell does from a
+ * layout effect on the open edge, so a closed surface costs no DOM at all.
+ *
+ * @param options - the injected document, the container's classes and the card renderer.
+ * @returns the portal handle; every method is safe with no document and safe to call twice.
+ */
+export declare function createCardPortal(options: CreateCardPortalOptions): CardPortal;
+/**
+ * Move focus to the first control inside a container.
+ *
+ * @param container - the card's container, or `undefined` when there is no DOM.
+ * @returns whether something actually took focus.
+ */
+export declare function focusFirstControl(container: PortalElement | undefined): boolean;
+/**
+ * Every control inside the card that Tab can reach, in DOM order.
+ *
+ * @param container - the card's container, or `undefined` when there is no DOM.
+ * @returns the focusable elements; `[]` when the container or `querySelectorAll` is absent.
+ */
+export declare function focusableWithin(container: PortalElement | undefined): readonly FocusTarget[];
+/**
+ * Keep Tab inside the open card.
+ *
+ * A dialog that lets Tab walk into the page behind it is a dialog the keyboard user can leave without
+ * dismissing; trapping the two ends is the minimum the modal promise requires. `active` is passed in (rather
+ * than read from the document) so the rule is a pure function of its arguments.
+ *
+ * @param event - the keydown event, structurally.
+ * @param container - the card's container.
+ * @param active - the element that currently holds focus.
+ * @returns whether the trap handled the key (and already called `preventDefault`).
+ */
+export declare function trapTab(event: {
+    readonly shiftKey?: boolean;
+    preventDefault?(): void;
+}, container: PortalElement | undefined, active: FocusTarget | undefined): boolean;
+/**
+ * Keep Tab inside a card that is hosted **inside another modal**.
+ *
+ * The settings page is a platform modal with its own focus trap (`useModalLayer`): it listens for Tab on
+ * `document` and, when focus is not inside its panel, moves focus to that panel's first control. This card is
+ * deliberately *outside* that panel (it is portalled to the body above the modal layers, audit 0088), so without
+ * this the platform would pull the caret out of the dialog on the first Tab.
+ *
+ * Two things have to happen, in this order:
+ *
+ *  1. `stopPropagation` — the platform's listener is on `document` in the **bubble** phase, so the card's own
+ *     listener must be registered in the capture phase ({@link PortalDocument.addEventListener}'s `options`) and
+ *     consume the event before it bubbles back up;
+ *  2. delegate to {@link trapTab} for the wrap at both ends. **In the middle it returns `false` and does not
+ *     preventDefault** — the browser's own Tab then walks the card's fields in order, which is exactly right.
+ *
+ * @param event - the keydown event, structurally.
+ * @param container - the card's container.
+ * @param active - the element that currently holds focus.
+ * @returns whether Tab was consumed (the trap already called `preventDefault`).
+ */
+export declare function trapCardTab(event: PortalKeyEvent, container: PortalElement | undefined, active: FocusTarget | undefined): boolean;
+/**
+ * Remember what held focus before the card opened.
+ *
+ * @param doc - the page's `document`, or `undefined` off-browser.
+ * @returns the focused element, or `undefined` when nothing was focused.
+ */
+export declare function captureFocusOrigin(doc: PortalDocument | undefined): FocusTarget | undefined;
+/**
+ * Give focus back to the element {@link captureFocusOrigin} remembered.
+ *
+ * @param origin - the remembered element.
+ * @returns whether focus was handed back; `false` when the trigger is gone (the owner re-rendered it away).
+ */
+export declare function restoreFocusOrigin(origin: FocusTarget | undefined): boolean;
+/**
+ * True when a card can actually be portalled here: this runtime supplies `react-dom`.
+ *
+ * Without it the shell must render the card in place and skip the container lifecycle entirely (an empty
+ * body-level node would just be appended and removed for nothing).
+ *
+ * @returns whether {@link renderInPortal} has a `createPortal` to work with.
+ */
+export declare function canRenderInPortal(): boolean;
+/**
+ * Render a card into the portal container, with `react-dom`'s `createPortal`.
+ *
+ * @param children - the card element the template built.
+ * @param container - the body-level element from {@link createCardPortal}.
+ * @returns the portal element, or `children` unchanged when this runtime supplies no `react-dom`.
+ */
+export declare function renderInPortal(children: ReactNode, container: unknown): ReactNode;
+/**
+ * The page's `document`, when this module runs in a browser.
+ *
+ * @returns the structural document view, or `undefined` off-browser.
+ */
+export declare function browserPortalDocument(): PortalDocument | undefined;

package/lib/types/src/client/core/remote.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The client half's host data channel: mount the `sshdev` namespace and read connection status.
+ *
+ * Three facts decide the shape of this module, all read from 0.2.0-rc.2 (see
+ * [`doc/02-platform/remote-data-channel.md`](../../doc/02-platform/remote-data-channel.md)):
+ *
+ *  1. **The namespace is mounted by us, not by `api-remotes`.** That core assembly lists its packages
+ *     explicitly, so a third-party plugin mounts its own `TypertRemoteContribution` through
+ *     `ctx.remote.$mount`.
+ *  2. **`remote.<ns>` must NOT be in the plugin's `inject`.** We create the namespace ourselves inside
+ *     `apply`; declaring it as a dependency would wait forever for a service only we can provide.
+ *  3. **The descriptors are hand-written and zero-argument.** `$mount` rejects any descriptor whose
+ *     parameter/uplink/Context codec is not strict, and only the Typert build pipeline produces strict
+ *     codecs. A method with **no parameters** triggers none of those checks, which is why the slice stops
+ *     at one zero-argument read; anything with arguments needs generated `lib/typert.remote-client.js`.
+ *
+ * The wire contract (`sshdev/connections` → an array of `{id, host, transport, degraded, note}`) is mirrored
+ * in `src/host/integration/remote-face.ts`; the two halves are separate tsconfig programs and cannot import
+ * each other, so the constants below are a hand-synchronized pair.
+ *
+ * @module dsh-over-ssh/client/remote
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { InvocationDescriptor, TypertDisposer, TypertRemoteContribution } from '@deepseek-ai/dsh-typert-protocol';
+import { type ConnectionRow } from './panel-model.ts';
+/** Wire namespace; the host face declares the same string. */
+export declare const SSH_DEV_REMOTE_NAMESPACE = "sshdev";
+/** Endpoint method name. */
+export declare const SSH_DEV_REMOTE_METHOD = "connections";
+/** Host Cordis service key the descriptor dispatches to (must match the host face's service name). */
+export declare const SSH_DEV_REMOTE_SERVICE = "sshDevRemote";
+/** Contribution identity; `$mount` rejects a repeat of the same package name. */
+export declare const SSH_DEV_REMOTE_PACKAGE = "dsh-over-ssh";
+/**
+ * The one descriptor this slice mounts.
+ *
+ * `result: { mode: 'src-json' }` is the honest declaration: no strict result codec exists for this endpoint in
+ * this repository, and the Client Remote only consults `result.decode` when the mode is `strict`
+ * (`packages/api/gateway/src/client/index.ts:449-451`), so the raw JSON value passes through and is narrowed
+ * by {@link toConnectionRows} instead.
+ */
+export declare const SSH_DEV_CONNECTIONS_DESCRIPTOR: InvocationDescriptor;
+/** The mountable contribution. */
+export declare const SSH_DEV_REMOTE_CONTRIBUTION: TypertRemoteContribution;
+/**
+ * Mount the `sshdev` namespace in the caller's fiber.
+ *
+ * The returned disposer withdraws the namespace and its concrete method; `$mount` also registers everything
+ * as an effect of the calling context, so unloading the plugin tears the channel down even if the caller
+ * never keeps the disposer.
+ *
+ * @param ctx - the plugin's client context (needs `remote`).
+ * @returns the mount disposer.
+ */
+export declare function mountConnectionChannel(ctx: Context): Promise<TypertDisposer>;
+/**
+ * Read the host's connection status once.
+ *
+ * Deliberately non-throwing: a channel that is absent, unmounted, offline, answered with a failure, or that
+ * rejects outright yields `undefined`, and the panel keeps its "no host data" notice.
+ *
+ * @param ctx - the plugin's client context; the namespace must already be mounted.
+ * @returns the panel rows, or `undefined` when no usable answer arrived.
+ */
+export declare function fetchConnectionRows(ctx: Context): Promise<readonly ConnectionRow[] | undefined>;
+/** Where {@link openConnectionChannel} reports its outcome. */
+export interface ConnectionChannelObserver {
+    /** Called once with the first rows the host answered — including an empty list (no connection configured). */
+    readonly onRows: (rows: readonly ConnectionRow[]) => void;
+    /** Called when the channel could not be mounted or answered; the panel keeps its notice. */
+    readonly onUnavailable?: (reason: unknown) => void;
+}
+/**
+ * Mount the channel, read it once, and hand the rows to `observer.onRows`.
+ *
+ * One read, no polling and no subscription: the panel is a snapshot of the moment the settings page (or the
+ * plugin) came up. Live refresh needs an observable source on the inject face — see the limitations section of
+ * `doc/02-platform/remote-data-channel.md`.
+ *
+ * @param ctx - the plugin's client context (needs `remote`).
+ * @param observer - row sink plus an optional unavailable-reason sink.
+ * @returns the mount disposer, or `undefined` when the channel never mounted.
+ */
+export declare function openConnectionChannel(ctx: Context, observer: ConnectionChannelObserver): Promise<TypertDisposer | undefined>;