dsh-over-ssh 0.1.0 → 0.2.0

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

@@ -1,266 +0,0 @@
-/**
- * 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

@@ -1,84 +0,0 @@
-/**
- * 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>;