dsh-over-ssh 0.0.0-stage → 0.1.0

package/lib/local-bridge-refs.js

@@ -0,0 +1,16 @@
+// src/local-bridge-refs.ts
+import "@deepseek-ai/cordis";
+var LocalFileReferencesBridge = class {
+  static inject = ["fileReferences"];
+  constructor(ctx) {
+    const local = ctx.get("fileReferences");
+    if (local === void 0) {
+      ctx.logger?.warn?.("local-bridge-refs: \u9694\u79BB\u57DF\u91CC\u6CA1\u6709 fileReferences\uFF1B\u8DEF\u7531\u5668\u5C06\u6CA1\u6709\u672C\u5730\u540E\u7AEF");
+      return;
+    }
+    ctx.provide("localFileReferences", local);
+  }
+};
+export {
+  LocalFileReferencesBridge as default
+};

package/lib/local-bridge.js

@@ -0,0 +1,16 @@
+// src/local-bridge.ts
+import "@deepseek-ai/cordis";
+var LocalFsBridge = class {
+  static inject = ["fs"];
+  constructor(ctx) {
+    const local = ctx.get("fs");
+    if (local === void 0) {
+      ctx.logger?.warn?.("local-bridge: \u9694\u79BB\u57DF\u91CC\u6CA1\u6709 fs\uFF1B\u8DEF\u7531\u5668\u5C06\u6CA1\u6709\u672C\u5730\u540E\u7AEF");
+      return;
+    }
+    ctx.provide("localFs", local);
+  }
+};
+export {
+  LocalFsBridge as default
+};

package/lib/terminal-wrapper.js

@@ -0,0 +1,294 @@
+#!/usr/bin/env -S node
+
+// tools/over-ssh-terminal.ts
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// src/host/domain/errors.ts
+var SshDevError = class extends Error {
+  code;
+  details;
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = "SshDevError";
+    this.code = code;
+    this.details = details;
+  }
+};
+
+// src/host/domain/roots/root.ts
+function normalizeLocalPath(path, options = {}) {
+  const caseInsensitive = options.caseInsensitive ?? process.platform === "win32";
+  const unified = path.replace(/\\/g, "/");
+  const unc = unified.startsWith("//");
+  const posixAbsolute = unified.startsWith("/");
+  const driveMatch = /^([A-Za-z]):/.exec(unified);
+  const driveLetter = driveMatch?.[1];
+  const drive = driveLetter === void 0 ? "" : `${driveLetter.toUpperCase()}:`;
+  const rest = unc ? unified.slice(2) : drive === "" ? unified : unified.slice(2);
+  const segments = [];
+  for (const segment of rest.split("/")) {
+    if (segment === "" || segment === ".") continue;
+    if (segment === "..") {
+      segments.pop();
+      continue;
+    }
+    segments.push(segment);
+  }
+  const body = segments.join("/");
+  let normalized;
+  if (unc) normalized = `//${body}`;
+  else if (drive !== "") normalized = body === "" ? `${drive}/` : `${drive}/${body}`;
+  else if (posixAbsolute) normalized = body === "" ? "/" : `/${body}`;
+  else normalized = body === "" ? "." : body;
+  return caseInsensitive ? normalized.toLowerCase() : normalized;
+}
+function localPathContains(root, candidate, options = {}) {
+  const normalizedRoot = normalizeLocalPath(root, options);
+  const normalizedCandidate = normalizeLocalPath(candidate, options);
+  if (normalizedRoot === "/" || /^[a-z]:\/$/.test(normalizedRoot)) {
+    return normalizedCandidate.startsWith(normalizedRoot);
+  }
+  return normalizedCandidate === normalizedRoot || normalizedCandidate.startsWith(`${normalizedRoot}/`);
+}
+function fnv1aHex(input) {
+  let hash = 2166136261;
+  for (let index = 0; index < input.length; index++) {
+    hash ^= input.charCodeAt(index);
+    hash = Math.imul(hash, 16777619) >>> 0;
+  }
+  return hash.toString(16).padStart(8, "0");
+}
+
+// src/host/domain/shell.ts
+function quote(value) {
+  if (value.includes("\0")) {
+    throw new SshDevError("REMOTE_COMMAND_FAILED", "\u8DEF\u5F84\u6216\u53C2\u6570\u4E2D\u4E0D\u80FD\u5305\u542B NUL \u5B57\u7B26", {});
+  }
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+// src/host/domain/session/terminal-target.ts
+var MANIFEST_VERSION = 1;
+var SESSION_STATE_MAX_AGE_MS = 24 * 60 * 60 * 1e3;
+function parseRootManifest(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return void 0;
+  }
+  if (parsed === null || typeof parsed !== "object") return void 0;
+  const candidate = parsed;
+  if (candidate.version !== MANIFEST_VERSION) return void 0;
+  if (!Array.isArray(candidate.roots)) return void 0;
+  const roots = [];
+  for (const entry of candidate.roots) {
+    if (entry === null || typeof entry !== "object") continue;
+    const root = entry;
+    if (typeof root.connectionId !== "string" || typeof root.remoteRoot !== "string") continue;
+    if (typeof root.anchorPath !== "string" || root.anchorPath === "") continue;
+    if (root.ssh === void 0 || typeof root.ssh.destination !== "string" || !Array.isArray(root.ssh.args)) continue;
+    roots.push({
+      connectionId: root.connectionId,
+      remoteRoot: root.remoteRoot,
+      anchorPath: root.anchorPath,
+      ssh: { destination: root.ssh.destination, args: [...root.ssh.args] }
+    });
+  }
+  return { version: MANIFEST_VERSION, roots };
+}
+function parseSessionState(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return void 0;
+  }
+  if (parsed === null || typeof parsed !== "object") return void 0;
+  const state = parsed;
+  if (typeof state.sessionId !== "string" || state.sessionId === "") return void 0;
+  if (typeof state.connectionId !== "string" || typeof state.remoteRoot !== "string") return void 0;
+  if (typeof state.recordedAt !== "number" || !Number.isFinite(state.recordedAt)) return void 0;
+  if (state.ssh === void 0 || typeof state.ssh.destination !== "string" || !Array.isArray(state.ssh.args)) return void 0;
+  return {
+    sessionId: state.sessionId,
+    connectionId: state.connectionId,
+    remoteRoot: state.remoteRoot,
+    ssh: { destination: state.ssh.destination, args: [...state.ssh.args] },
+    recordedAt: state.recordedAt
+  };
+}
+function remoteCommandFor(remoteRoot, remoteShell = "$SHELL") {
+  return `cd ${quote(remoteRoot)} && exec ${remoteShell} -l`;
+}
+function sshArgvFor(ssh, remoteCommand) {
+  return ["ssh", "-tt", ...ssh.args, ssh.destination, "--", remoteCommand];
+}
+function decideTerminal(options) {
+  const now = options.now ?? Date.now();
+  const local = { kind: "local", argv: [options.localShell], reason: "no-target" };
+  const state = options.sessionState;
+  if (state !== void 0) {
+    if (now - state.recordedAt > SESSION_STATE_MAX_AGE_MS || state.recordedAt > now + 6e4) {
+      const manifestRoot = matchRoot(options.manifest, options.cwd, now);
+      return manifestRoot === void 0 ? { ...local, reason: "state-unusable" } : remoteDecision(manifestRoot, "anchor", options.remoteShell);
+    }
+    const command = remoteCommandFor(state.remoteRoot, options.remoteShell);
+    return {
+      kind: "remote",
+      connectionId: state.connectionId,
+      remoteRoot: state.remoteRoot,
+      argv: sshArgvFor(state.ssh, command),
+      remoteCommand: command,
+      reason: "session"
+    };
+  }
+  const matched = matchRoot(options.manifest, options.cwd, now);
+  if (matched !== void 0) return remoteDecision(matched, "anchor", options.remoteShell);
+  return options.manifest === void 0 ? { ...local, reason: "no-target" } : local;
+}
+function matchRoot(manifest, cwd, _now) {
+  if (manifest === void 0) return void 0;
+  return manifest.roots.find((root) => localPathContains(root.anchorPath, cwd, { caseInsensitive: false }));
+}
+function remoteDecision(root, reason, remoteShell) {
+  const command = remoteCommandFor(root.remoteRoot, remoteShell ?? "$SHELL");
+  return {
+    kind: "remote",
+    connectionId: root.connectionId,
+    remoteRoot: root.remoteRoot,
+    argv: sshArgvFor(root.ssh, command),
+    remoteCommand: command,
+    reason
+  };
+}
+
+// src/host/integration/tools/terminal-manifest.ts
+function sessionFileName(sessionId) {
+  const sanitized = sessionId.replaceAll(/[^A-Za-z0-9._-]/g, "_").slice(0, 48);
+  return `${sanitized}-${fnv1aHex(sessionId)}.json`;
+}
+
+// tools/over-ssh-terminal.ts
+var RECONNECT_DELAYS_MS = [500, 1e3, 2e3, 4e3];
+var SSH_CONNECTION_FAILED = 255;
+function parseWrapperArgs(argv) {
+  const flags = /* @__PURE__ */ new Map();
+  for (let index = 0; index < argv.length; index++) {
+    const token = argv[index];
+    if (token === void 0 || !token.startsWith("--")) continue;
+    const next = argv[index + 1];
+    if (next !== void 0 && !next.startsWith("--")) {
+      flags.set(token.slice(2), next);
+      index++;
+    } else {
+      flags.set(token.slice(2), "true");
+    }
+  }
+  return flags;
+}
+function defaultLocalShell(platform, env) {
+  if (platform === "win32") return env["COMSPEC"] ?? "cmd.exe";
+  return env["SHELL"] ?? "/bin/sh";
+}
+async function readIfPresent(path) {
+  try {
+    return await readFile(path, "utf8");
+  } catch {
+    return void 0;
+  }
+}
+async function loadInputs(options) {
+  const manifestRaw = await readIfPresent(join(options.stateDir, "roots.json"));
+  const manifest = manifestRaw === void 0 ? void 0 : parseRootManifest(manifestRaw);
+  if (options.sessionId === void 0) return { manifest, sessionState: void 0 };
+  const stateRaw = await readIfPresent(join(options.stateDir, "state", sessionFileName(options.sessionId)));
+  return { manifest, sessionState: stateRaw === void 0 ? void 0 : parseSessionState(stateRaw) };
+}
+var STATE_DIR_NAMES = ["over-ssh", "remote-workspace", "ssh-dev"];
+function defaultStateDir() {
+  const base = join(homedir(), ".dsh");
+  for (const name of STATE_DIR_NAMES) {
+    const dir = join(base, name);
+    if (existsSync(join(dir, "roots.json"))) return dir;
+  }
+  return join(base, STATE_DIR_NAMES[0]);
+}
+async function decide(input) {
+  const flags = parseWrapperArgs(input.argv);
+  const stateDir = flags.get("state-dir") ?? input.env["DSH_OVER_SSH_STATE_DIR"] ?? input.env["DSH_SSH_DEV_STATE_DIR"] ?? defaultStateDir();
+  const sessionId = flags.get("session") ?? input.env["DSH_SESSION_ID"];
+  const localShell = flags.get("local-shell") ?? defaultLocalShell(input.platform ?? process.platform, input.env);
+  const inputs = await loadInputs({ stateDir, sessionId });
+  const decideOptions = {
+    cwd: input.cwd,
+    localShell,
+    ...inputs.manifest === void 0 ? {} : { manifest: inputs.manifest },
+    ...inputs.sessionState === void 0 ? {} : { sessionState: inputs.sessionState }
+  };
+  const base = decideTerminal(decideOptions);
+  const override = flags.get("remote-command");
+  const decision = override === void 0 || base.kind !== "remote" ? base : { ...base, argv: [...base.argv.slice(0, -1), override], remoteCommand: override };
+  return { decision, label: flags.get("name") ?? "SSH / Local", stateDir, sessionId, localShell };
+}
+async function main(input) {
+  const { decision } = await decide(input);
+  if (parseWrapperArgs(input.argv).has("dry-run")) {
+    process.stdout.write(`${JSON.stringify(decision, void 0, 2)}
+`);
+    return 0;
+  }
+  const [executable, ...args] = decision.argv;
+  if (executable === void 0) throw new Error("terminal wrapper: empty argv");
+  const spawnFn = input.spawnFn ?? spawn;
+  const sleepFn = input.sleepFn ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const runOnce = async () => {
+    const child = spawnFn(executable, args, {
+      stdio: "inherit",
+      // A local terminal keeps the caller's cwd; a remote one is entered by the ssh command itself.
+      ...decision.kind === "local" ? { cwd: input.cwd } : {}
+    });
+    return await new Promise((resolve) => {
+      child.on("exit", (code, signal) => {
+        if (typeof code === "number") resolve({ code, signalled: false });
+        else resolve({ code: signal === null || signal === void 0 ? 0 : 1, signalled: true });
+      });
+      child.on("error", () => resolve({ code: 127, signalled: false }));
+    });
+  };
+  const first = await runOnce();
+  if (decision.kind !== "remote" || parseWrapperArgs(input.argv).has("no-reconnect")) return first.code;
+  let outcome = first;
+  for (const delay of RECONNECT_DELAYS_MS) {
+    if (outcome.signalled || outcome.code !== SSH_CONNECTION_FAILED) return outcome.code;
+    process.stderr.write(
+      `\r
+[dsh] \u4E0E\u8FDC\u7AEF\u7684\u8FDE\u63A5\u5DF2\u65AD\u5F00\uFF0C${delay} ms \u540E\u91CD\u8FDE\uFF08\u65B0\u7684\u767B\u5F55 shell\uFF1B\u539F\u5148\u8FD0\u884C\u7684\u8FDB\u7A0B\u5DF2\u4E22\u5931\uFF09\u2026\r
+`
+    );
+    await sleepFn(delay);
+    outcome = await runOnce();
+  }
+  return outcome.code;
+}
+var selfPath = fileURLToPath(import.meta.url);
+if (process.argv[1] !== void 0 && process.argv[1] === selfPath) {
+  main({ argv: process.argv.slice(2), env: process.env, cwd: process.cwd(), platform: process.platform }).then((code) => process.exit(code)).catch((error) => {
+    process.stderr.write(`over-ssh terminal wrapper: ${error instanceof Error ? error.message : String(error)}
+`);
+    process.exit(1);
+  });
+}
+export {
+  RECONNECT_DELAYS_MS,
+  decide,
+  defaultLocalShell,
+  loadInputs,
+  main,
+  parseWrapperArgs
+};

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

@@ -0,0 +1,131 @@
+/**
+ * The controls the three surfaces share, as plain `createElement` templates.
+ *
+ * **No hooks, on purpose.** `:hover`, `:active`, `:focus-visible` and `:disabled` come from the stylesheet in
+ * [`styles.ts`](./styles.ts) via class names, because a component holding `useState` cannot be rendered by
+ * this repository's tests: they call the section functions **directly**, outside any React render, where a
+ * hook throws `Invalid hook call`. Classes keep the templates pure element trees — a test walks the returned
+ * tree and reads the same `type` / `name` / `disabled` / `role` it always did — while the browser still gets
+ * real interaction states.
+ *
+ * These are deliberately **not** the platform's `dsh-client-ui-primitives` atoms: those factories import
+ * per-component CSS modules, which a third-party bundle cannot supply (the loader materialises only
+ * registered factories), and the package is not a dependency of this repository. `styles.ts` carries the
+ * tokens those atoms are built from.
+ *
+ * @module dsh-remote-workspace/client/controls
+ */
+import { type ChangeEvent, type ReactNode } from 'react';
+/** The sizes a control may have. */
+export type ControlSize = 'normal' | 'compact';
+/** The visual weight of a button. */
+export type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'row' | 'chip';
+/** Props every control shares: extra classes from the caller. */
+export interface ControlClassProps {
+    /** Extra classes from the caller; appended after the vocabulary's own. */
+    readonly className?: string;
+}
+/**
+ * The part of a keyboard event a card's Esc handler reads.
+ *
+ * Structural, so the pure templates need no DOM types and a test drives the handler with a plain object. It is
+ * assignable from React's `KeyboardEvent` (which carries both members), and it is the whole reason a dialog
+ * closes on Esc: the shell focuses into the card when it opens, so the event reaches the card's own handler.
+ */
+export interface KeyEventLike {
+    /** The key name, e.g. `'Escape'`. */
+    readonly key?: string;
+    /** Stop the platform's own Esc handling from also firing while the dialog is up. */
+    stopPropagation?(): void;
+}
+/** True when the event is the Esc key. */
+export declare function isEscape(event: KeyEventLike): boolean;
+/**
+ * One button.
+ *
+ * @param props - the button's own props plus the variants this plugin uses.
+ * @returns the button element.
+ */
+export declare function Button(props: ControlClassProps & {
+    readonly variant: ButtonVariant;
+    readonly size?: ControlSize;
+    readonly type?: 'button' | 'submit';
+    readonly disabled?: boolean;
+    readonly name?: string;
+    readonly title?: string;
+    readonly onClick?: () => void;
+    readonly children?: ReactNode;
+}): ReactNode;
+/** Props of a text input, narrowed to what the templates pass. */
+export interface TextInputProps extends ControlClassProps {
+    readonly id: string;
+    readonly name: string;
+    readonly value: string;
+    readonly disabled?: boolean;
+    readonly placeholder?: string;
+    readonly inputMode?: 'numeric';
+    /** `password` for a secret field: the browser masks it and no autofill offers to save it. */
+    readonly type?: 'text' | 'password';
+    readonly autoComplete?: 'off' | 'new-password';
+    readonly size?: ControlSize;
+    readonly onChange: (event: ChangeEvent<HTMLInputElement>) => void;
+}
+/**
+ * One text input, with the platform's border, inset surface and focus ring.
+ *
+ * @param props - the input's own props.
+ * @returns the input element.
+ */
+export declare function TextInput(props: TextInputProps): ReactNode;
+/** One option of a {@link Select}. */
+export interface SelectOption {
+    readonly value: string;
+    readonly label: string;
+}
+/**
+ * A `<select>` over a fixed list of options.
+ *
+ * @param props - id, name, the current value, the options and the change handler.
+ * @returns the select element.
+ */
+export declare function Select(props: ControlClassProps & {
+    readonly id: string;
+    readonly name: string;
+    readonly value: string;
+    readonly options: readonly SelectOption[];
+    readonly disabled?: boolean;
+    readonly size?: ControlSize;
+    readonly onChange: (value: string) => void;
+}): ReactNode;
+/**
+ * A labelled field: the caption above its control, so the column and its label move together.
+ *
+ * @param props - the label text, the control's id and the control itself.
+ * @returns the labelled column.
+ */
+export declare function Field(props: {
+    readonly label: string;
+    readonly htmlFor: string;
+    readonly children: ReactNode;
+}): ReactNode;
+/**
+ * An inline notice block: the surface for a refusal, a host warning or "no host data".
+ *
+ * @param props - `warn` for something the operator may need to act on, `info` for a neutral status.
+ * @returns the notice element carrying the role its caller needs (`alert` / `note` / `status`).
+ */
+export declare function Notice(props: {
+    readonly role: 'alert' | 'note' | 'status';
+    readonly tone?: 'warn' | 'info';
+    readonly children: ReactNode;
+}): ReactNode;
+/**
+ * The status dot of a connection row, so the row's state is not carried by colour alone.
+ *
+ * @param props - the dot's accessible description.
+ * @returns the dot element.
+ */
+export declare function StatusDot(props: {
+    readonly label: string;
+}): ReactNode;
+//# sourceMappingURL=controls.d.ts.map

package/lib/types/src/client/core/card-focus-trap.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The **one** Tab trap every card in this plugin installs.
+ *
+ * Five surfaces are dialogs and every one of them has to keep Tab inside itself, for two different reasons:
+ *
+ *  - the settings-hosted cards sit **outside** the platform settings modal, whose own focus trap listens on
+ *    `document` in the bubble phase and pulls focus back into its panel — a bubble-phase listener of ours would
+ *    run after it (registration order) and could no longer tell which field Tab came from, so the trap has to
+ *    be in the **capture** phase (audit 0090);
+ *  - the overlay and composer cards are simply modals: Tab walking into the page behind them is a dialog the
+ *    keyboard user leaves without dismissing.
+ *
+ * Both cases want the same mechanics, so they live here instead of being spelled out per surface (the two that
+ * were first — the connection editor and the session-panel confirmation — each carried their own copy of the
+ * same eight lines, and the two newer ones had none at all; audit 2026-10-31 `client.md` §2.3).
+ *
+ * The split is the same one the rest of `core/` uses: {@link installCardTabTrap} is pure and takes the document
+ * as an argument (so an offline test drives it with a fake), and {@link useCardTabTrap} is the two-line React
+ * binding.
+ *
+ * @module dsh-over-ssh/client/card-focus-trap
+ */
+import { type PortalDocument } from './portal.ts';
+/**
+ * Install the card's Tab trap on one document.
+ *
+ * Capture phase on purpose: see the module note. The listener is removed with the same `options` value, so a
+ * runtime that keys listeners by phase cannot leak one.
+ *
+ * @param doc - the page's document, or `undefined` off-browser (where this is a no-op).
+ * @param container - the card's body-level container; `undefined` while it is not attached.
+ * @returns the remover; safe to call more than once.
+ */
+export declare function installCardTabTrap(doc: PortalDocument | undefined, container: unknown): () => void;
+/**
+ * Trap Tab while a card is open.
+ *
+ * `open` is the caller's own condition (`editingId !== undefined`, `pending !== undefined`, `request !==
+ * undefined`); the container comes from that surface's portal. Nothing is installed while the card is closed, so
+ * the settings panel keeps its own Tab behaviour the rest of the time.
+ *
+ * @param open - whether the card is up.
+ * @param container - the card's container from its portal.
+ */
+export declare function useCardTabTrap(open: boolean, container: unknown): void;

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

@@ -0,0 +1,164 @@
+/**
+ * The controls the three surfaces share, as plain `createElement` templates.
+ *
+ * **No hooks, on purpose.** `:hover`, `:active`, `:focus-visible` and `:disabled` come from the stylesheet in
+ * [`styles.ts`](./styles.ts) via class names, because a component holding `useState` cannot be rendered by
+ * this repository's tests: they call the section functions **directly**, outside any React render, where a
+ * hook throws `Invalid hook call`. Classes keep the templates pure element trees — a test walks the returned
+ * tree and reads the same `type` / `name` / `disabled` / `role` it always did — while the browser still gets
+ * real interaction states.
+ *
+ * These are deliberately **not** the platform's `dsh-client-ui-primitives` atoms: those factories import
+ * per-component CSS modules, which a third-party bundle cannot supply (the loader materialises only
+ * registered factories), and the package is not a dependency of this repository. `styles.ts` carries the
+ * tokens those atoms are built from.
+ *
+ * @module dsh-over-ssh/client/controls
+ */
+import { type ChangeEvent, type ReactNode } from 'react';
+/** The sizes a control may have. */
+export type ControlSize = 'normal' | 'compact';
+/** The visual weight of a button. */
+export type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'row' | 'chip';
+/** Props every control shares: extra classes from the caller. */
+export interface ControlClassProps {
+    /** Extra classes from the caller; appended after the vocabulary's own. */
+    readonly className?: string;
+}
+/**
+ * The part of a keyboard event a card's Esc handler reads.
+ *
+ * Structural, so the pure templates need no DOM types and a test drives the handler with a plain object. It is
+ * assignable from React's `KeyboardEvent` (which carries both members), and it is the whole reason a dialog
+ * closes on Esc: the shell focuses into the card when it opens, so the event reaches the card's own handler.
+ */
+export interface KeyEventLike {
+    /** The key name, e.g. `'Escape'`. */
+    readonly key?: string;
+    /** Stop the platform's own Esc handling from also firing while the dialog is up. */
+    stopPropagation?(): void;
+}
+/** True when the event is the Esc key. */
+export declare function isEscape(event: KeyEventLike): boolean;
+/**
+ * One button.
+ *
+ * @param props - the button's own props plus the variants this plugin uses.
+ * @returns the button element.
+ */
+export declare function Button(props: ControlClassProps & {
+    readonly variant: ButtonVariant;
+    readonly size?: ControlSize;
+    readonly type?: 'button' | 'submit';
+    readonly disabled?: boolean;
+    readonly name?: string;
+    readonly title?: string;
+    /** The name a screen reader reads instead of the visible text, when the text alone is not a name. */
+    readonly ariaLabel?: string;
+    /** For a control that opens something: whether it is open right now (`aria-expanded`). */
+    readonly ariaExpanded?: boolean;
+    /** What the control opens (`aria-haspopup`). */
+    readonly ariaHaspopup?: 'dialog' | 'menu';
+    readonly onClick?: () => void;
+    readonly children?: ReactNode;
+}): ReactNode;
+/** Props of a text input, narrowed to what the templates pass. */
+export interface TextInputProps extends ControlClassProps {
+    readonly id: string;
+    readonly name: string;
+    readonly value: string;
+    readonly disabled?: boolean;
+    readonly placeholder?: string;
+    readonly inputMode?: 'numeric';
+    /** `password` for a secret field: the browser masks it and no autofill offers to save it. */
+    readonly type?: 'text' | 'password';
+    readonly autoComplete?: 'off' | 'new-password';
+    readonly size?: ControlSize;
+    readonly onChange: (event: ChangeEvent<HTMLInputElement>) => void;
+}
+/**
+ * One text input, with the platform's border, inset surface and focus ring.
+ *
+ * @param props - the input's own props.
+ * @returns the input element.
+ */
+export declare function TextInput(props: TextInputProps): ReactNode;
+/** One option of a {@link Select}. */
+export interface SelectOption {
+    readonly value: string;
+    readonly label: string;
+}
+/**
+ * A `<select>` over a fixed list of options.
+ *
+ * @param props - id, name, the current value, the options and the change handler.
+ * @returns the select element.
+ */
+export declare function Select(props: ControlClassProps & {
+    readonly id: string;
+    readonly name: string;
+    readonly value: string;
+    readonly options: readonly SelectOption[];
+    readonly disabled?: boolean;
+    readonly size?: ControlSize;
+    readonly onChange: (value: string) => void;
+}): ReactNode;
+/**
+ * A labelled field: the caption above its control, so the column and its label move together.
+ *
+ * @param props - the label text, the control's id and the control itself.
+ * @returns the labelled column.
+ */
+export declare function Field(props: {
+    readonly label: string;
+    readonly htmlFor: string;
+    readonly children: ReactNode;
+}): ReactNode;
+/**
+ * An inline notice block: the surface for a refusal, a host warning or "no host data".
+ *
+ * Three tones, and the split is deliberate: **`warn` is the default** (something the operator may need to act
+ * on), `info` is a neutral status, and `error` is a hard failure. Before this, a failed read and a soft
+ * warning rendered identically — both `role: 'alert'` on the amber surface — so "the host refused" and
+ * "the host is telling you something" looked the same. A failure is not a warning.
+ *
+ * @param props - the tone, the role, and the text.
+ * @returns the notice element carrying the role its caller needs (`alert` / `note` / `status`).
+ */
+export declare function Notice(props: {
+    readonly role: 'alert' | 'note' | 'status';
+    readonly tone?: 'warn' | 'info' | 'error';
+    readonly children: ReactNode;
+}): ReactNode;
+/**
+ * A checkbox whose whole row is the hit target.
+ *
+ * The templates used to render a bare `<input type="checkbox">`: the stylesheet had **no rule for it at all**,
+ * so it kept the browser's default size and accent colour, and — in the session inventory — it sat next to a
+ * body that was not a `<label>`, so clicking the row's own text did nothing and the target was a 16px square.
+ *
+ * `id`/`name` are optional because the two call sites differ: the ssh-config list already pairs the box with a
+ * separate `<label htmlFor>` naming the alias, while the session row wants the box and its body wrapped
+ * together. Passing neither is allowed; passing `id` makes the input addressable by a sibling label.
+ *
+ * @param props - the box's identity, state and handler.
+ * @returns the input element.
+ */
+export declare function Checkbox(props: {
+    readonly checked: boolean;
+    readonly disabled?: boolean;
+    readonly id?: string;
+    readonly name?: string;
+    readonly onChange: () => void;
+    /** The accessible name, when no `<label>` wraps or names this box. */
+    readonly ariaLabel?: string;
+}): ReactNode;
+/**
+ * The status dot of a connection row, so the row's state is not carried by colour alone.
+ *
+ * @param props - the dot's accessible description.
+ * @returns the dot element.
+ */
+export declare function StatusDot(props: {
+    readonly label: string;
+}): ReactNode;