@exagone313/dsh-podman 0.2.0-rc.4 → 0.2.0

package/dist/client/podman-terminal.js

@@ -0,0 +1,412 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+// The Podman terminal tab's body: the container and shell pickers over the
+// settings card's live snapshot, and one xterm screen bound to the host's
+// terminal stream. The workspace is the Session's own — never chosen, never
+// shown. Closing the tab only detaches; the host retains the shell, and
+// reopening the same tab reattaches and replays a snapshot.
+import { FitAddon } from "@xterm/addon-fit";
+import { Terminal } from "@xterm/xterm";
+import xtermCss from "@xterm/xterm/css/xterm.css";
+import { Button } from "@deepseek-ai/dsh-client-ui-primitives";
+import { useEffect, useLayoutEffect, useRef, useState, } from "react";
+import { fieldLabel, imageSelect } from "./container-card-styles.js";
+import { containerOptions } from "./terminal-targets.js";
+import { forgetTerminalTitle, publishTerminalTitle, } from "./terminal-titles.js";
+import { base64ToBytes, bytesToBase64, fetchTerminalShells, fetchTerminalTarget, openTerminalStream, sendTerminalControl, } from "./terminal-transport.js";
+// One TextEncoder serves every keystroke: the type is stateless for our use.
+const TEXT_ENCODER = new TextEncoder();
+// The xterm stylesheet is imported as text (the build's `.css` loader) and
+// injected once, under this attribute, so a plugin reload cannot duplicate it.
+const XTERM_STYLE_ATTRIBUTE = "data-dsh-podman-xterm";
+const XTERM_CLASS = "dsh-podman-xterm";
+const XTERM_STYLES = `
+.${XTERM_CLASS}, .${XTERM_CLASS} .xterm { height: 100%; }
+.${XTERM_CLASS} .xterm-viewport { background: var(--dsw-alias-bg-layer-2); }
+`;
+let xtermStylesInstalled = false;
+function installXtermStyles() {
+    if (xtermStylesInstalled || typeof document === "undefined")
+        return;
+    xtermStylesInstalled = true;
+    if (document.head.querySelector(`style[${XTERM_STYLE_ATTRIBUTE}]`) !== null) {
+        return;
+    }
+    const tag = document.createElement("style");
+    tag.setAttribute(XTERM_STYLE_ATTRIBUTE, "");
+    tag.textContent = `${xtermCss}\n${XTERM_STYLES}`;
+    document.head.appendChild(tag);
+}
+// The screen follows the app theme through its CSS variables, read once at
+// mount (a live theme change is a future concern; the harness's own terminal
+// re-reads them through the theme service).
+function readTerminalTheme() {
+    const style = getComputedStyle(document.documentElement);
+    const read = (name, fallback) => {
+        const value = style.getPropertyValue(name).trim();
+        return value === "" ? fallback : value;
+    };
+    const foreground = read("--dsw-alias-label-primary", "#e6e8ee");
+    return {
+        background: read("--dsw-alias-bg-layer-2", "#17191d"),
+        foreground,
+        cursor: read("--dsw-alias-brand-primary", foreground),
+        selectionBackground: read("--dsw-alias-label-secondary", "rgba(126, 146, 184, 0.4)"),
+    };
+}
+export function ContainerField(props) {
+    return (_jsxs(_Fragment, { children: [_jsx("span", { style: fieldLabel, children: props.label }), _jsxs("select", { style: props.selectStyle ?? imageSelect, "aria-label": props.label, value: props.container ?? "", disabled: props.disabled || props.workspaceSlug === undefined, onChange: (event) => {
+                    props.onContainer(event.target.value);
+                }, children: [_jsx("option", { value: "", children: props.defaultLabel }), containerOptions(props.containers, props.workspaceSlug).map((name) => (_jsx("option", { value: name, children: name }, name)))] })] }));
+}
+export function PodmanTerminal(props) {
+    const { t, sessionId } = props;
+    const info = props.useTabInfo();
+    // The host keys retention by session + tab, so the composite keeps the two
+    // unambiguous in one opaque query value.
+    const tabId = `${sessionId}:${info.tab.id}`;
+    const state = props.useContainerCard((snapshot) => snapshot);
+    const params = info.tab.navigation.params;
+    // The workspace comes from the host, which resolves it from the Session
+    // itself: the browser neither chooses nor guesses one. `failed` means the
+    // host cannot place this session in a workspace.
+    const [target, setTarget] = useState({ phase: "loading" });
+    const workspace = target.phase === "ready"
+        ? target.target.workspace
+        : undefined;
+    const workspaceSlug = target.phase === "ready"
+        ? target.target.workspaceSlug
+        : undefined;
+    const unknownWorkspace = target.phase === "failed";
+    const [container, setContainer] = useState(params?.container);
+    const [shell, setShell] = useState(params?.shell);
+    const [shells, setShells] = useState({ phase: "loading" });
+    const [status, setStatus] = useState({ kind: "idle" });
+    const [title, setTitle] = useState("");
+    const [attempt, setAttempt] = useState(0);
+    const node = useRef(null);
+    const terminal = useRef();
+    const stream = useRef();
+    const terminalId = useRef();
+    // False once the screen is torn down, so a late frame or an unmount cleanup
+    // never touches a disposed emulator and an unmount never closes the shell.
+    const alive = useRef(true);
+    const reopen = useRef(false);
+    // The card snapshot is the only source of containers, and the settings scope
+    // may not have loaded yet.
+    useEffect(() => {
+        props.reload();
+    }, [props.reload]);
+    useEffect(() => {
+        const controller = new AbortController();
+        setTarget({ phase: "loading" });
+        void fetchTerminalTarget(sessionId, controller.signal).then((resolved) => {
+            if (!controller.signal.aborted) {
+                setTarget({ phase: "ready", target: resolved });
+            }
+        }, (error) => {
+            if (controller.signal.aborted)
+                return;
+            setTarget({
+                phase: "failed",
+                message: error instanceof Error ? error.message : String(error),
+            });
+        });
+        return () => {
+            controller.abort();
+        };
+    }, [sessionId]);
+    // Default container: the empty value means the workspace's default container
+    // to the host. The workspace row carries that container's podman name, which
+    // the orchestrator rejects, so it is never used as a target.
+    useEffect(() => {
+        if (workspace === undefined || container !== undefined)
+            return;
+        setContainer("");
+    }, [workspace, container]);
+    // The shells a container really offers; refetched whenever the target moves.
+    useEffect(() => {
+        if (workspace === undefined || workspace === "" || container === undefined) {
+            return;
+        }
+        const controller = new AbortController();
+        setShells({ phase: "loading" });
+        void fetchTerminalShells(workspace, container, sessionId, controller.signal).then((list) => {
+            if (controller.signal.aborted)
+                return;
+            setShells({ phase: "ready", shells: list });
+            setShell((previous) => previous ?? list[0]?.path);
+        }, (error) => {
+            if (controller.signal.aborted)
+                return;
+            setShells({
+                phase: "failed",
+                message: error instanceof Error ? error.message : String(error),
+            });
+        });
+        return () => {
+            controller.abort();
+        };
+    }, [workspace, container, sessionId]);
+    // The emulator outlives every connection; a reconnect reuses it.
+    useLayoutEffect(() => {
+        const element = node.current;
+        if (element === null)
+            return;
+        alive.current = true;
+        installXtermStyles();
+        const term = new Terminal({
+            cursorBlink: true,
+            fontSize: 13,
+            fontFamily: "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace",
+            scrollback: 5000,
+            theme: readTerminalTheme(),
+        });
+        const addon = new FitAddon();
+        term.loadAddon(addon);
+        term.open(element);
+        terminal.current = term;
+        const fit = () => {
+            if (element.clientWidth === 0 || element.clientHeight === 0)
+                return;
+            try {
+                addon.fit();
+            }
+            catch {
+                // The element lost its box between measure and resize; the next
+                // observer callback retries.
+            }
+        };
+        fit();
+        const input = term.onData((data) => {
+            const id = terminalId.current;
+            if (id === undefined)
+                return;
+            void sendTerminalControl({
+                terminalId: id,
+                kind: "input",
+                data: bytesToBase64(TEXT_ENCODER.encode(data)),
+            }).catch(() => {
+                // A dead stream reports itself through a frame or the stream's error.
+            });
+        });
+        const resize = term.onResize(({ cols, rows }) => {
+            const id = terminalId.current;
+            if (id === undefined)
+                return;
+            void sendTerminalControl({ terminalId: id, kind: "resize", cols, rows })
+                .catch(() => { });
+        });
+        const observer = new ResizeObserver(fit);
+        observer.observe(element);
+        return () => {
+            alive.current = false;
+            forgetTerminalTitle(tabId);
+            stream.current?.abort();
+            stream.current = undefined;
+            observer.disconnect();
+            input.dispose();
+            resize.dispose();
+            term.dispose();
+            terminal.current = undefined;
+        };
+    }, []);
+    // One attachment per target: a target change (or a reconnect) closes the old
+    // shell, while an unmount only aborts and leaves the shell retained.
+    useEffect(() => {
+        const term = terminal.current;
+        if (term === undefined)
+            return;
+        if (workspace === undefined || workspace === "" ||
+            container === undefined ||
+            shell === undefined || shell === "") {
+            return;
+        }
+        const controller = new AbortController();
+        stream.current = controller;
+        const forceReopen = reopen.current;
+        reopen.current = false;
+        terminalId.current = undefined;
+        term.reset();
+        setStatus({ kind: "connecting" });
+        const onFrame = (frame) => {
+            if (!alive.current)
+                return;
+            switch (frame.type) {
+                case "ready":
+                    terminalId.current = frame.terminalId;
+                    if (frame.title !== "") {
+                        setTitle(frame.title);
+                        publishTerminalTitle(tabId, frame.title);
+                    }
+                    setStatus({ kind: "running" });
+                    break;
+                case "snapshot":
+                    term.write(frame.screen);
+                    break;
+                case "data":
+                    term.write(base64ToBytes(frame.data));
+                    break;
+                case "title":
+                    setTitle(frame.title);
+                    publishTerminalTitle(tabId, frame.title);
+                    break;
+                case "exit":
+                    terminalId.current = undefined;
+                    setStatus({ kind: "exited", code: frame.exitCode });
+                    break;
+                case "error":
+                    setStatus({ kind: "error", message: frame.message });
+                    break;
+                case "detached":
+                    setStatus({ kind: "detached" });
+                    break;
+            }
+        };
+        void openTerminalStream({
+            sessionId,
+            tabId,
+            workspace,
+            container,
+            shell,
+            cols: term.cols > 0 ? term.cols : 80,
+            rows: term.rows > 0 ? term.rows : 24,
+            ...(forceReopen ? { reopen: true } : {}),
+        }, onFrame, controller.signal).catch((error) => {
+            if (controller.signal.aborted)
+                return;
+            setStatus({
+                kind: "error",
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }).finally(() => {
+            if (stream.current === controller)
+                stream.current = undefined;
+        });
+        return () => {
+            controller.abort();
+            if (stream.current === controller)
+                stream.current = undefined;
+            if (!alive.current)
+                return;
+            const id = terminalId.current;
+            terminalId.current = undefined;
+            if (id !== undefined) {
+                void sendTerminalControl({ terminalId: id, kind: "close" }).catch(() => {
+                    // The shell may already be gone; reconnecting still works.
+                });
+            }
+        };
+    }, [sessionId, tabId, workspace, container, shell, attempt]);
+    // The terminal takes focus only while its tab is the visible one.
+    useEffect(() => {
+        if (info.tab.visible)
+            terminal.current?.focus();
+    }, [info.tab.visible]);
+    const canConnect = workspace !== undefined && workspace !== "" &&
+        shell !== undefined && shell !== "";
+    const connect = (forceReopen) => {
+        const id = terminalId.current;
+        stream.current?.abort();
+        stream.current = undefined;
+        terminalId.current = undefined;
+        if (id !== undefined) {
+            void sendTerminalControl({ terminalId: id, kind: "close" }).catch(() => { });
+        }
+        terminal.current?.reset();
+        reopen.current = forceReopen;
+        setAttempt((value) => value + 1);
+    };
+    const shellList = shells.phase === "ready" ? shells.shells : [];
+    let statusLabel;
+    switch (status.kind) {
+        case "connecting":
+            statusLabel = t("terminalStatusConnecting");
+            break;
+        case "running":
+            statusLabel = t("terminalStatusRunning");
+            break;
+        case "exited":
+            statusLabel = t("terminalStatusExited", {
+                code: status.code === null
+                    ? t("terminalNoExitCode")
+                    : String(status.code),
+            });
+            break;
+        case "detached":
+            statusLabel = t("terminalStatusDetached");
+            break;
+        case "error":
+            statusLabel = status.message;
+            break;
+        case "idle":
+            statusLabel = undefined;
+            break;
+    }
+    const idle = status.kind === "idle";
+    const ended = status.kind === "exited" || status.kind === "error";
+    return (_jsxs("section", { style: ROOT_STYLE, "data-dsh-podman-terminal": true, children: [_jsxs("div", { style: TOOLBAR_STYLE, children: [_jsx(ContainerField, { containers: state.containers, workspaceSlug: workspaceSlug, container: container, disabled: state.workspaces.length === 0 || unknownWorkspace, label: t("terminalContainer"), defaultLabel: t("terminalDefaultContainer"), onContainer: (value) => {
+                            setContainer(value);
+                            setShell(undefined);
+                        } }), _jsx("span", { style: fieldLabel, children: t("terminalShell") }), _jsx("select", { style: imageSelect, "aria-label": t("terminalShell"), value: shell ?? "", disabled: unknownWorkspace || shells.phase !== "ready" ||
+                            shellList.length === 0, onChange: (event) => {
+                            setShell(event.target.value);
+                        }, children: shellList.length === 0
+                            ? (_jsx("option", { value: "", children: unknownWorkspace
+                                    ? ""
+                                    : shells.phase === "loading"
+                                        ? t("terminalLoading")
+                                        : t("terminalNoShells") }))
+                            : shellList.map((entry) => (_jsx("option", { value: entry.path, children: entry.name }, entry.path))) }), (idle || ended) && (_jsx(Button, { variant: "outline", size: "sm", disabled: !canConnect, onClick: () => {
+                            connect(!idle);
+                        }, children: idle ? t("terminalConnect") : t("terminalReconnect") })), statusLabel === undefined
+                        ? null
+                        : _jsx("span", { style: STATUS_STYLE, role: "status", children: statusLabel }), title === "" ? null : _jsx("span", { style: TITLE_STYLE, children: title })] }), state.workspaces.length === 0 && (_jsx("p", { style: ERROR_STYLE, role: "status", children: state.busy ? t("terminalLoading") : t("unavailable") })), target.phase === "failed" && (_jsx("p", { style: ERROR_STYLE, role: "alert", children: target.message })), shells.phase === "failed" && (_jsx("p", { style: ERROR_STYLE, role: "alert", children: t("terminalShellsFailed", { message: shells.message }) })), _jsx("div", { ref: node, className: XTERM_CLASS, style: SCREEN_STYLE })] }));
+}
+const ROOT_STYLE = {
+    display: "flex",
+    flex: 1,
+    flexDirection: "column",
+    boxSizing: "border-box",
+    height: "100%",
+    minHeight: 0,
+    color: "var(--dsw-alias-label-primary)",
+    background: "var(--dsw-alias-bg-layer-2)",
+    fontSize: "13px",
+};
+const TOOLBAR_STYLE = {
+    display: "flex",
+    flexWrap: "wrap",
+    alignItems: "center",
+    gap: "8px",
+    padding: "6px 8px",
+    borderBottom: "1px solid var(--dsw-alias-border-l2)",
+};
+const STATUS_STYLE = {
+    fontSize: "12px",
+    color: "var(--dsw-alias-label-tertiary)",
+};
+const TITLE_STYLE = {
+    flex: 1,
+    minWidth: 0,
+    overflow: "hidden",
+    whiteSpace: "nowrap",
+    textOverflow: "ellipsis",
+    fontSize: "12px",
+    color: "var(--dsw-alias-label-secondary)",
+};
+const ERROR_STYLE = {
+    margin: 0,
+    padding: "6px 10px",
+    fontSize: "12px",
+    color: "var(--dsw-alias-label-primary)",
+    background: "var(--dsw-alias-bg-layer-3)",
+};
+const SCREEN_STYLE = {
+    flex: 1,
+    minHeight: 0,
+    minWidth: 0,
+    overflow: "hidden",
+};

package/dist/client/read-only-approval.d.ts

@@ -1,8 +1,8 @@
 import { type PendingApproval } from "@deepseek-ai/dsh-client-ui-approval/client";
 import { type ReactNode } from "react";
-import { type ContainerPluginKey } from "./locales.js";
+import type { Translate } from "./locales.js";
 export declare const BUILTIN_PROMPT_PREFIX = "dsh_podman_builtin_";
 export declare function ReadOnlyApprovalPanel(props: {
-    t: (key: ContainerPluginKey) => string;
+    t: Translate;
     matched: PendingApproval;
 }): ReactNode;

package/dist/client/read-only-approval.js

@@ -12,9 +12,14 @@ export function ReadOnlyApprovalPanel(props) {
 }
 function ReadOnlyApprovalFlow({ t, matched, }) {
     const [answered, setAnswered] = useState(false);
+    const [error, setError] = useState("");
     const answer = (outcome) => {
         setAnswered(true);
-        void matched.answer(outcome).catch(() => setAnswered(false));
+        setError("");
+        void matched.answer(outcome).catch((failure) => {
+            setAnswered(false);
+            setError(failure instanceof Error ? failure.message : String(failure));
+        });
     };
     return (_jsx("div", { style: {
             display: "flex",
@@ -29,7 +34,7 @@ function ReadOnlyApprovalFlow({ t, matched, }) {
                 borderRadius: "20px",
                 background: "var(--dsw-specific-input-major)",
                 boxShadow: "var(--dsw-shadow-lv2)",
-            }, children: [_jsxs("div", { style: {
+            }, children: [_jsxs("div", { role: "status", "aria-live": "polite", style: {
                         display: "flex",
                         alignItems: "center",
                         gap: "8px",
@@ -54,7 +59,12 @@ function ReadOnlyApprovalFlow({ t, matched, }) {
                             fontWeight: 500,
                             lineHeight: "24px",
                             whiteSpace: "pre-line",
-                        }, children: matched.reason ?? "" }) }), _jsxs("div", { style: {
+                        }, children: matched.reason ?? "" }) }), error === "" ? null : (_jsx("p", { role: "alert", style: {
+                        margin: 0,
+                        padding: "8px 16px 0",
+                        fontSize: "13px",
+                        color: "var(--dsw-alias-state-error-primary)",
+                    }, children: error })), _jsxs("div", { style: {
                         display: "flex",
                         justifyContent: "flex-end",
                         gap: "8px",

package/dist/client/slot-contract.d.ts

@@ -1,12 +1 @@
-declare module "@deepseek-ai/dsh-client-ui-slots" {
-    interface SlotMap {
-        "settings.plugin.item": {
-            kind: "keyed";
-            scope: "root";
-            owner: {
-                children?: never;
-            };
-        };
-    }
-}
 export {};

package/dist/client/terminal-preference.d.ts

@@ -0,0 +1,26 @@
+/** Origin-local key holding the target the card last started. */
+export declare const TERMINAL_TARGET_KEY = "dsh.podman.terminal.v1";
+/** What the card starts: a logical container name and a verified shell path. */
+export interface TerminalTargetPreference {
+    /** `""`/"default" for the workspace's default container, or a named one. */
+    readonly container?: string;
+    /** Absolute path of a shell the host offered. */
+    readonly shell?: string;
+}
+/** The two storage operations the preference needs. */
+export interface PreferenceStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+/**
+ * Read the remembered target.
+ * @param storage - storage override for tests; the browser's localStorage otherwise.
+ * @returns the remembered target, or `undefined` when absent or unusable.
+ */
+export declare function readTerminalTarget(storage?: PreferenceStorage): TerminalTargetPreference | undefined;
+/**
+ * Remember the target, best effort.
+ * @param target - the container and shell that were started.
+ * @param storage - storage override for tests; the browser's localStorage otherwise.
+ */
+export declare function writeTerminalTarget(target: TerminalTargetPreference, storage?: PreferenceStorage): void;

package/dist/client/terminal-preference.js

@@ -0,0 +1,67 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+// Browser-local memory of the target last started from the terminal card,
+// mirroring the harness's own client preferences: an origin-local,
+// `dsh.`-prefixed localStorage entry, read and written behind try/catch so
+// private browsing or a quota failure can never break the card.
+/** Origin-local key holding the target the card last started. */
+export const TERMINAL_TARGET_KEY = "dsh.podman.terminal.v1";
+// Accessed through globalThis so this module stays typecheckable without the
+// DOM lib (the host test program imports it), and guarded because even reading
+// the property can throw in a sandboxed frame.
+function browserStorage() {
+    try {
+        const candidate = globalThis
+            .localStorage;
+        return candidate === undefined ? undefined : candidate;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Read the remembered target.
+ * @param storage - storage override for tests; the browser's localStorage otherwise.
+ * @returns the remembered target, or `undefined` when absent or unusable.
+ */
+export function readTerminalTarget(storage) {
+    try {
+        const raw = (storage ?? browserStorage())?.getItem(TERMINAL_TARGET_KEY);
+        if (raw === undefined || raw === null || raw === "")
+            return undefined;
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            return undefined;
+        }
+        const record = parsed;
+        const container = typeof record.container === "string"
+            ? record.container
+            : undefined;
+        const shell = typeof record.shell === "string" ? record.shell : undefined;
+        if (container === undefined && shell === undefined)
+            return undefined;
+        return {
+            ...(container === undefined ? {} : { container }),
+            ...(shell === undefined ? {} : { shell }),
+        };
+    }
+    catch {
+        // Malformed JSON, or storage that refuses to answer, leaves the card on its
+        // own defaults.
+        return undefined;
+    }
+}
+/**
+ * Remember the target, best effort.
+ * @param target - the container and shell that were started.
+ * @param storage - storage override for tests; the browser's localStorage otherwise.
+ */
+export function writeTerminalTarget(target, storage) {
+    try {
+        (storage ?? browserStorage())?.setItem(TERMINAL_TARGET_KEY, JSON.stringify(target));
+    }
+    catch {
+        // Private browsing or a quota failure leaves this launch usable.
+    }
+}

package/dist/client/terminal-protocol.d.ts

@@ -0,0 +1,85 @@
+/** Open or attach one browser terminal. */
+export declare const TERMINAL_PATH = "/api/podman/terminal";
+/** The shells a container really provides, discovered on its PATH. */
+export declare const TERMINAL_SHELLS_PATH = "/api/podman/terminal/shells";
+/** The terminals a session still has retained on the host. */
+export declare const TERMINAL_RETAINED_PATH = "/api/podman/terminal/retained";
+/** The workspace the host resolved for one session. */
+export declare const TERMINAL_TARGET_PATH = "/api/podman/terminal/target";
+/** The workspace a session runs in, resolved by the host from the session itself. */
+export interface TerminalTargetView {
+    /** Workspace project name, as the card lists it. */
+    readonly workspace: string;
+    /** The harness workspace slug, used to filter that workspace's containers. */
+    readonly workspaceSlug: string;
+}
+/** One shell verified inside a container. */
+export interface TerminalShellView {
+    readonly name: string;
+    readonly path: string;
+}
+/** What the host knows about a retained terminal. */
+export interface TerminalRetainedView {
+    readonly tabId: string;
+    readonly terminalId: string;
+    readonly title: string;
+    readonly workspace: string;
+    readonly container: string;
+    readonly shell: string;
+}
+/** Query parameters of the open/attach stream. */
+export interface TerminalOpenQuery {
+    readonly sessionId: string;
+    readonly tabId: string;
+    readonly workspace: string;
+    readonly container: string;
+    readonly shell: string;
+    readonly cols: number;
+    readonly rows: number;
+}
+/** Frames the host writes into the open/attach stream, one JSON object per line. */
+export type TerminalFrame = {
+    readonly type: "ready";
+    readonly terminalId: string;
+    readonly workspace: string;
+    readonly container: string;
+    readonly shell: string;
+    readonly title: string;
+    readonly attached: boolean;
+} | {
+    readonly type: "snapshot";
+    readonly screen: string;
+} | {
+    readonly type: "data";
+    readonly data: string;
+} | {
+    readonly type: "title";
+    readonly title: string;
+} | {
+    readonly type: "exit";
+    readonly exitCode: number | null;
+    readonly signal: string | null;
+} | {
+    readonly type: "error";
+    readonly message: string;
+} | {
+    readonly type: "detached";
+};
+/** One control request against an open terminal. */
+export type TerminalControl = {
+    readonly terminalId: string;
+    readonly kind: "input";
+    readonly data: string;
+} | {
+    readonly terminalId: string;
+    readonly kind: "resize";
+    readonly cols: number;
+    readonly rows: number;
+} | {
+    readonly terminalId: string;
+    readonly kind: "close";
+} | {
+    readonly terminalId: string;
+    readonly kind: "rename";
+    readonly title: string;
+};

package/dist/client/terminal-protocol.js

@@ -0,0 +1,14 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+// Wire contract between the Podman terminal tab (client half) and the host
+// routes that bridge it to a guest terminal. Paths are exact: the connection
+// service dispatches one route per path.
+/** Open or attach one browser terminal. */
+export const TERMINAL_PATH = "/api/podman/terminal";
+/** The shells a container really provides, discovered on its PATH. */
+export const TERMINAL_SHELLS_PATH = "/api/podman/terminal/shells";
+/** The terminals a session still has retained on the host. */
+export const TERMINAL_RETAINED_PATH = "/api/podman/terminal/retained";
+/** The workspace the host resolved for one session. */
+export const TERMINAL_TARGET_PATH = "/api/podman/terminal/target";