@celljs/ta-web 4.6.1 → 4.8.0

package/src/browser/components/remote-prompts.tsx

@@ -0,0 +1,111 @@
+import type { TaRemoteEvent, TaRemotePrompt } from '@celljs/ta-protocol';
+import { KeyRound, Server, ShieldQuestion } from 'lucide-react';
+import * as React from 'react';
+import { createPortal } from 'react-dom';
+import { useNotices, useWorkbench } from '../hooks';
+import { useT } from '../i18n/use-t';
+import { Icon } from './icon';
+
+/** Asks what ssh asks: a password or a passphrase (not shown), whether to trust a new host, or a line of text. */
+function PromptDialog({ prompt, onAnswer }: { prompt: TaRemotePrompt; onAnswer(value: string | null): void }) {
+    const t = useT();
+    const [value, setValue] = React.useState('');
+    const confirm = prompt.kind === 'confirm';
+    return createPortal(
+        <div className="ta-modal-scrim">
+            <button type="button" className="ta-overlay-close" aria-label={t('ta.cancel')} tabIndex={-1} onClick={() => onAnswer(null)} />
+            <form
+                className="ta-modal ta-confirm ta-remote-prompt"
+                role="alertdialog"
+                aria-modal="true"
+                aria-label={t('ta.remote.prompt.title', { host: prompt.host })}
+                onKeyDown={event => event.key === 'Escape' && onAnswer(null)}
+                onSubmit={event => {
+                    event.preventDefault();
+                    onAnswer(confirm ? 'yes' : value);
+                }}
+            >
+                <div className="ta-confirm-title">
+                    <Icon icon={confirm ? ShieldQuestion : prompt.kind === 'secret' ? KeyRound : Server} size={16} />
+                    {t('ta.remote.prompt.title', { host: prompt.host })}
+                </div>
+                <pre className="ta-remote-message">{prompt.message}</pre>
+                {!confirm && (
+                    <label className="ta-field">
+                        <input
+                            autoFocus
+                            type={prompt.kind === 'secret' ? 'password' : 'text'}
+                            autoComplete="off"
+                            spellCheck={false}
+                            value={value}
+                            aria-label={prompt.message}
+                            onChange={event => setValue(event.target.value)}
+                        />
+                    </label>
+                )}
+                <div className="ta-dialog-actions">
+                    <button type="button" className="ta-button" onClick={() => onAnswer(confirm ? 'no' : null)}>
+                        {t('ta.cancel')}
+                    </button>
+                    <button type="submit" className="ta-button ta-primary" autoFocus={confirm}>
+                        {t(confirm ? 'ta.remote.prompt.trust' : 'ta.remote.prompt.continue')}
+                    </button>
+                </div>
+            </form>
+        </div>,
+        document.body,
+    );
+}
+
+/**
+ * What ssh asks while ta serve connects to a host, one question at a time, in every page that is open (the
+ * first answer counts); a line at the bottom while a host connects, which may take a while the first
+ * time (it installs Node.js there); and a notice when a connection is lost.
+ */
+export function RemotePrompts() {
+    const t = useT();
+    const [, bench] = useWorkbench();
+    const [, notices] = useNotices();
+    const [prompts, setPrompts] = React.useState<TaRemotePrompt[]>([]);
+    const [steps, setSteps] = React.useState<Record<string, string>>({});
+    const connected = React.useRef(new Set<string>());
+    React.useEffect(
+        () =>
+            bench.onRemoteEvent((event: TaRemoteEvent) => {
+                if (event.type === 'prompt') {
+                    setPrompts(shown => (shown.some(prompt => prompt.promptId === event.prompt.promptId) ? shown : [...shown, event.prompt]));
+                } else if (event.type === 'prompt_closed') {
+                    setPrompts(shown => shown.filter(prompt => prompt.promptId !== event.promptId));
+                } else if (event.type === 'progress') {
+                    setSteps(shown => ({ ...shown, [event.host]: t(`ta.remote.step.${event.step}`, { host: event.host, detail: event.detail ?? '' }) }));
+                } else {
+                    setSteps(({ [event.host]: _gone, ...rest }) => rest);
+                    // Lost, not closed on purpose; a connection that failed is the caller's to tell.
+                    if (!event.connected && event.error && connected.current.has(event.host)) {
+                        notices.notify(t('ta.remote.lost', { host: event.host }), { level: 'warning', detail: event.error });
+                    }
+                    connected.current[event.connected ? 'add' : 'delete'](event.host);
+                }
+            }),
+        [bench, notices, t],
+    );
+    const [prompt] = prompts;
+    const answer = (value: string | null) => {
+        setPrompts(shown => shown.slice(1));
+        void bench.remote.answer(prompt.promptId, value).catch(() => undefined);
+    };
+    const lines = Object.values(steps);
+    return (
+        <>
+            {prompt && <PromptDialog key={prompt.promptId} prompt={prompt} onAnswer={answer} />}
+            {lines.length > 0 &&
+                createPortal(
+                    <div className="ta-remote-status" role="status">
+                        <span className="ta-spinner" />
+                        {lines.join(' · ')}
+                    </div>,
+                    document.body,
+                )}
+        </>
+    );
+}

package/src/browser/components/session-view.tsx

@@ -4,6 +4,7 @@ import * as React from 'react';
 import { useNotices, useOpenLink, useSessionState } from '../hooks';
 import { useT } from '../i18n/use-t';
 import { MessageUtil } from '../util/message';
+import { TerminalText } from '../util/terminal-text';
 import { Composer } from './composer';
 import type { ComposerBoxHandle } from './composer-box';
 import { useConversationScroll } from './conversation-scroll';
@@ -14,11 +15,17 @@ import { useMessageActions } from './message-actions';
 import { MessageActions } from './message-footer';
 import { ConversationSession, MessageList } from './message-list';
 import { useSessionSettings } from './session-settings';
+import { TerminalArt } from './terminal-art';
 
-/** What the extensions of the session say with `notify` goes to the notices of the page; what was said before it opened stays quiet. */
+/**
+ * What the extensions of the session say with `notify` goes to the notices of the page; what was said before it
+ * opened stays quiet. A picture in it (a QR code to sign in) is drawn, and stays until the next notice of the
+ * session, which says how it went or brings a new code.
+ */
 function useSessionNotices(notices: Notice[]) {
     const [, center] = useNotices();
     const seen = React.useRef<Set<string> | undefined>(undefined);
+    const picture = React.useRef<number>(undefined);
     React.useEffect(() => {
         if (!seen.current) {
             seen.current = new Set(notices.map(notice => notice.id));
@@ -27,12 +34,46 @@ function useSessionNotices(notices: Notice[]) {
         for (const notice of notices) {
             if (!seen.current.has(notice.id)) {
                 seen.current.add(notice.id);
-                center.notify(notice.message, { level: notice.type });
+                if (picture.current !== undefined) {
+                    center.dismiss(picture.current);
+                    picture.current = undefined;
+                }
+                const { text, art } = TerminalText.art(notice.message);
+                const id = center.notify(text, { level: notice.type, art, sticky: art !== undefined });
+                picture.current = art ? id : undefined;
             }
         }
     }, [notices, center]);
 }
 
+/** What an extension shows above or below the message box (`setWidget`): its lines as a terminal draws them, a picture in them drawn. */
+function WidgetView({ lines }: { lines: string[] }) {
+    const t = useT();
+    const { text, art } = React.useMemo(() => TerminalText.art(lines.join('\n')), [lines]);
+    return (
+        <div className="ta-widget">
+            {text && <pre className="ta-widget-text">{text}</pre>}
+            {art && <TerminalArt art={art} className="ta-widget-art" label={t('ta.notice.picture')} />}
+        </div>
+    );
+}
+
+/** The status of an extension, as a chip: its label, then each part, with a dot for the sign of its state. */
+function StatusChip({ text }: { text: string }) {
+    const { label, segments } = React.useMemo(() => TerminalText.status(text), [text]);
+    return (
+        <span className="ta-statusline-item" title={text}>
+            {label && <span className="ta-statusline-label">{label}</span>}
+            {segments.map((segment, index) => (
+                <span key={index} className={`ta-statusline-part${segment.tone ? ` ta-tone-${segment.tone}` : ''}`}>
+                    {segment.tone && <span className={`ta-status ta-status-${segment.tone}`} />}
+                    {segment.text}
+                </span>
+            ))}
+        </span>
+    );
+}
+
 export interface SessionViewProps {
     store: SessionStore;
     server: TaServer;
@@ -80,6 +121,15 @@ export function SessionView({
     const composer = React.useRef<ComposerBoxHandle>(null);
     const cwd = info?.cwd;
     const messageActions = useMessageActions(store, server, state.working, cwd, composer, onActivity);
+    // An extension puts text in the message box, as in pi's terminal.
+    const editorText = state.editorText;
+    const takenText = React.useRef(editorText?.id);
+    React.useEffect(() => {
+        if (editorText && editorText.id !== takenText.current) {
+            takenText.current = editorText.id;
+            composer.current?.setText(TerminalText.plain(editorText.text));
+        }
+    }, [editorText]);
     React.useEffect(() => {
         if (draftText) {
             composer.current?.setText(draftText);
@@ -97,7 +147,10 @@ export function SessionView({
         }
     }, [state.closed, onClosed]);
 
-    const statuses = Object.values(state.status);
+    const statuses = Object.entries(state.status).filter(([, text]) => TerminalText.plain(text).trim());
+    const widgets = Object.entries(state.widgets);
+    const widgetsAt = (placement: 'aboveEditor' | 'belowEditor') =>
+        widgets.filter(([, widget]) => widget.placement === placement).map(([key, widget]) => <WidgetView key={key} lines={widget.lines} />);
     const dialog = state.pendingUi[0];
     const title = info?.sessionName || (info ? MessageUtil.basename(info.cwd) : t('ta.session.title'));
 
@@ -134,6 +187,7 @@ export function SessionView({
             <div className="ta-bottom">
                 {dialog && <DialogView key={dialog.id} request={dialog} respond={response => store.respondUi(response).catch(fail)} />}
                 {aboveComposer}
+                {widgetsAt('aboveEditor')}
                 <Composer
                     ref={composer}
                     store={store}
@@ -146,7 +200,14 @@ export function SessionView({
                     onError={fail}
                 />
                 {belowComposer}
-                {statuses.length > 0 && <div className="ta-statusline">{statuses.join(' · ')}</div>}
+                {widgetsAt('belowEditor')}
+                {statuses.length > 0 && (
+                    <div className="ta-statusline">
+                        {statuses.map(([key, text]) => (
+                            <StatusChip key={key} text={text} />
+                        ))}
+                    </div>
+                )}
             </div>
         </section>
     );

package/src/browser/components/settings-view.tsx

@@ -19,6 +19,7 @@ import {
     Puzzle,
     RefreshCw,
     Search,
+    Server,
     Smartphone,
     Sparkles,
     Sun,
@@ -37,6 +38,7 @@ import { AgentControl, ScopeBar, useAgentSettings } from './agent-settings-view'
 import { AuthDialog } from './auth-view';
 import { Icon, IconButton } from './icon';
 import { RelayDialog } from './relay-view';
+import { RemoteHosts } from './remote-hosts';
 import { type Choice, Keys, Row, type RowEntry, row, Segmented, Switch } from './settings-controls';
 import { TrustedDomains } from './trusted-domains';
 import { WorkingDirectoryPicker } from './working-directory';
@@ -336,6 +338,12 @@ function useParts(scope: TaSettingsScope, onScope: (scope: TaSettingsScope) => v
                 ),
             ],
         },
+        {
+            id: 'remote',
+            title: t('ta.remote.title'),
+            icon: Server,
+            rows: [row('remote', [t('ta.remote.title'), t('ta.remote.description'), 'ssh'], <RemoteHosts />)],
+        },
         {
             id: 'shortcuts',
             title: t('ta.settings.shortcuts'),

package/src/browser/components/terminal-art.tsx

@@ -0,0 +1,21 @@
+import * as React from 'react';
+import { TerminalText } from '../util/terminal-text';
+
+/** A picture of cells, as a QR code to scan: black on white whatever the theme, with a margin of white. */
+export function TerminalArt({ art, className, label }: { art: boolean[][]; className: string; label: string }) {
+    const path = React.useMemo(() => TerminalText.path(art), [art]);
+    const width = Math.max(...art.map(row => row.length));
+    const margin = 2;
+    return (
+        <svg
+            className={className}
+            viewBox={`${-margin} ${-margin} ${width + margin * 2} ${art.length + margin * 2}`}
+            role="img"
+            aria-label={label}
+            shapeRendering="crispEdges"
+        >
+            <rect x={-margin} y={-margin} width={width + margin * 2} height={art.length + margin * 2} fill="#fff" />
+            <path d={path} fill="#111" />
+        </svg>
+    );
+}

package/src/browser/components/tool-view.tsx

@@ -63,7 +63,7 @@ function ToolRow({ name, args, status, trailing, details }: ToolRowProps) {
     const line = (
         <>
             <StatusDot status={status} />
-            <span className="ta-tool-verb">{summary.verb ? t(summary.verb) : name}</span>
+            <span className="ta-tool-verb">{summary.verb ? t(summary.verb) : summary.name}</span>
             {summary.target && <span className={`ta-tool-target ${summary.code ? 'ta-mono' : ''}`}>{summary.target}</span>}
             {details ? <Icon icon={ChevronRight} size={13} className="ta-tool-chevron" /> : <span className="ta-tool-chevron" />}
         </>

package/src/browser/components/web-composer.tsx

@@ -5,7 +5,7 @@ import { useT } from '../i18n/use-t';
 import type { TaNotices } from '../notices/notices-protocol';
 import { ComposerUtil } from '../util/composer';
 import { ComposerBox } from './composer-box';
-import { DirectoryButton } from './folder-picker';
+import { DirectoryButton, type FolderPickerRemote } from './folder-picker';
 
 export interface WebComposerHostProps extends WebComposerProps {
     /** Where a failure to send goes. */
@@ -14,10 +14,24 @@ export interface WebComposerHostProps extends WebComposerProps {
     listDirectory?(directory: string): Promise<TaDirEntry[]>;
     /** The directory of ta serve: that of a `cwd` left empty. */
     serverCwd?: string;
+    /** The hosts of ssh, which the button offers too. */
+    remote?: FolderPickerRemote;
 }
 
 /** The message box as web extensions get it (`pi.ui.Composer`): text only, `@` for the names they give; a failure is a notice of the page. */
-export function WebComposer({ notices, placeholder, onSend, mentions, mentionLabel, actions, cwd, onPickCwd, listDirectory, serverCwd }: WebComposerHostProps) {
+export function WebComposer({
+    notices,
+    placeholder,
+    onSend,
+    mentions,
+    mentionLabel,
+    actions,
+    cwd,
+    onPickCwd,
+    listDirectory,
+    serverCwd,
+    remote,
+}: WebComposerHostProps) {
     const t = useT();
     const [query, setQuery] = React.useState<string>();
     return (
@@ -40,7 +54,8 @@ export function WebComposer({ notices, placeholder, onSend, mentions, mentionLab
             }
             mentionLabel={mentions ? mentionLabel : undefined}
             actions={actions}
-            beside={onPickCwd && listDirectory && <DirectoryButton cwd={cwd || serverCwd || ''} list={listDirectory} onPick={onPickCwd} />}
+            beside={onPickCwd && listDirectory && <DirectoryButton cwd={cwd || serverCwd || ''} list={listDirectory} remote={remote} onPick={onPickCwd} />}
+            cwd={cwd || serverCwd}
             onError={cause => notices.error(cause)}
         />
     );

package/src/browser/components/working-directory.tsx

@@ -18,5 +18,5 @@ export function WorkingDirectoryPicker({ onClose }: { onClose(): void }) {
             notices.error(error);
         }
     };
-    return <FolderPicker list={list} initial={workbench.server?.cwd ?? '.'} onPick={pick} onClose={onClose} />;
+    return <FolderPicker list={list} initial={workbench.server?.cwd ?? '.'} remote={bench} onPick={pick} onClose={onClose} />;
 }

package/src/browser/extension/icons.ts

@@ -1,4 +1,5 @@
 import {
+    AlarmClock,
     ArrowDown,
     ArrowLeft,
     ArrowRight,
@@ -12,6 +13,7 @@ import {
     ChevronRight,
     ChevronsDownUp,
     ChevronsUpDown,
+    CircleAlert,
     Clipboard,
     Code,
     Columns2,
@@ -51,6 +53,7 @@ import {
     Pencil,
     Pin,
     PinOff,
+    Play,
     Plus,
     Puzzle,
     RefreshCw,
@@ -62,11 +65,13 @@ import {
     Save,
     ScrollText,
     Search,
+    Server,
     Sparkles,
     Square,
     SquareMinus,
     SquarePlus,
     SquareTerminal,
+    Store,
     Text,
     Trash2,
     Undo2,
@@ -81,6 +86,7 @@ import type { WebIcon } from './web-extension-api';
 
 /** The icons a web extension gets as `pi.ui.icons`; names are lucide's. Only add: removing one breaks extensions. */
 export const WEB_ICONS: Readonly<Record<string, WebIcon>> = Object.freeze({
+    AlarmClock,
     ArrowDown,
     ArrowLeft,
     ArrowRight,
@@ -94,6 +100,7 @@ export const WEB_ICONS: Readonly<Record<string, WebIcon>> = Object.freeze({
     ChevronRight,
     ChevronsDownUp,
     ChevronsUpDown,
+    CircleAlert,
     Clipboard,
     Code,
     Columns2,
@@ -132,6 +139,7 @@ export const WEB_ICONS: Readonly<Record<string, WebIcon>> = Object.freeze({
     PackageOpen,
     Pencil,
     Pin,
+    Play,
     PinOff,
     Plus,
     Puzzle,
@@ -144,11 +152,13 @@ export const WEB_ICONS: Readonly<Record<string, WebIcon>> = Object.freeze({
     Save,
     ScrollText,
     Search,
+    Server,
     Sparkles,
     Square,
     SquareMinus,
     SquarePlus,
     SquareTerminal,
+    Store,
     Text,
     Trash2,
     Undo2,

package/src/browser/extension/web-extension-api.ts

@@ -1,4 +1,13 @@
-import type { TaEvent, TaPackageServer, TaServer, TaSessionInfo, TaTerminalServer, TaWorkspaceServer } from '@celljs/ta-protocol';
+import type {
+    TaEvent,
+    TaPackageServer,
+    TaRemoteServer,
+    TaServer,
+    TaSessionInfo,
+    TaSettingsServer,
+    TaTerminalServer,
+    TaWorkspaceServer,
+} from '@celljs/ta-protocol';
 import type * as React from 'react';
 import type { Mood } from '../avatar/dino-avatar';
 import type { Language, Theme } from '../settings/settings-protocol';
@@ -13,12 +22,16 @@ export interface WebExtensionAPI {
     readonly React: typeof React;
     /** The sessions of ta serve, for what the rest of the API does not do: the commands of pi's RPC mode. */
     readonly server: TaServer;
-    /** The files and programs of a directory on the machine of ta serve. */
+    /** The files and programs of a directory, on the machine of ta serve or of an `ssh://` directory. */
     readonly workspace: TaWorkspaceServer;
     /** Shells; their output comes by {@link onTerminalData}. */
     readonly terminals: TaTerminalServer;
     /** The packages pi loads; for the data of the extension's own package, {@link storage}. */
     readonly packages: TaPackageServer;
+    /** The other machines of `ssh://` directories (TaLocation): their ports, for a page served there. */
+    readonly remote: TaRemoteServer;
+    /** pi's settings of ta (`settings.json`): `getSettings(cwd)` also lists the models with credentials, for a model picker. */
+    readonly settings: TaSettingsServer;
     readonly ui: WebExtensionUI;
     /** A view of its own: a page or a sidebar view, in the navigation on the left, or a tool of the workbench on the right. */
     registerView(name: string, view: WebView): void;
@@ -127,6 +140,31 @@ export interface WebExtensionUI {
     editor(title: string, prefill?: string): Promise<string | undefined>;
     readonly theme: Theme;
     readonly language: Language;
+    /**
+     * Whether a view can show a site in a `<webview>` element, as in Ta Desktop: a page of its own rather
+     * than a frame, which sites cannot refuse, where signing in works and stays, with the history, title and
+     * icon of the page as events and methods of the element (Electron's). Elsewhere, an iframe.
+     */
+    readonly supportsWebview: boolean;
+    /**
+     * Ta Desktop's way to the file manager of the system (Finder, File Explorer, that of Linux), for paths of
+     * this machine; undefined in a browser and the mobile app. A directory of `ssh://` is not of this machine.
+     */
+    readonly desktop?: WebDesktop;
+    /**
+     * Files dragged between views, as the explorer drags them: `set` them in `dragstart`. Dropped on the
+     * message box of a conversation they become `@` references (relative to its directory when they are in
+     * it); a terminal takes their `paths`; anywhere else they are their paths as text.
+     */
+    readonly fileDrag: WebFileDrag;
+    /**
+     * Ta Desktop: sends a command of the Chrome DevTools Protocol to the page of a `<webview>` of this page
+     * (its `getWebContentsId()`), as that page's debugger, and resolves with its result; `undefined`
+     * elsewhere. Only commands on the page itself: Accessibility, CSS, DOM, DOMSnapshot, Emulation, Input,
+     * Log, Overlay, Page and Runtime, without those that touch files, downloads or navigate (use the
+     * element's `loadURL`); the app refuses the rest.
+     */
+    readonly debugWebview?: (webContentsId: number, method: string, params?: Record<string, unknown>) => Promise<unknown>;
     /**
      * A tab in the editor area beside the conversation (a file, a diff, a browser); an open id is shown
      * again. With `preserveFocus`, it opens behind the tab shown, and the workbench is not revealed: for
@@ -164,6 +202,11 @@ export interface WebExtensionUI {
     readonly CodeEditor: React.ComponentType<CodeEditorProps>;
     /** Monaco's diff editor on two texts of a file, side by side or inline; the right side can be edited. */
     readonly DiffEditor: React.ComponentType<DiffEditorProps>;
+    /**
+     * A terminal as VS Code's: xterm.js drawn on the GPU, in the theme of the page. It loads the first
+     * time one is made; what it shows stays while no view shows it (`attach` it to the next one).
+     */
+    createTerminal(options?: WebTerminalOptions): WebTerminal;
     /** The message box of the conversations of the page, with its + menu: one look for every conversation. */
     readonly Composer: React.ComponentType<WebComposerProps>;
     /** Markdown as the conversations show it. */
@@ -174,6 +217,95 @@ export interface WebExtensionUI {
     readonly FolderPicker: React.ComponentType<WebFolderPickerProps>;
 }
 
+export interface WebDesktop {
+    /** Node's `process.platform` of the machine (`darwin`, `win32`, `linux`): what its file manager is called. */
+    readonly platform: string;
+    /** Opens the folder of an absolute path of this machine in the file manager, the item selected. */
+    showItemInFolder(path: string): Promise<void>;
+    /** The sign-ins of the user's browsers taken into the browser of Ta; macOS and Windows only. */
+    readonly browserData?: WebBrowserData;
+}
+
+/** A profile of the user's Chrome, Edge, Brave, Arc, Vivaldi or Chromium. */
+export interface WebBrowserProfile {
+    /** What `import` takes. */
+    id: string;
+    /** The name of the browser, `Google Chrome`. */
+    browser: string;
+    /** The name of the profile, as the browser shows it. */
+    name: string;
+}
+
+/** The cookies an import took into the browser of Ta. */
+export interface WebBrowserImport {
+    imported: number;
+    /** Those that could not be read or set. */
+    skipped: number;
+    /** Windows: those under Chrome's app-bound encryption, which only Chrome can read: sign in again. */
+    appBound: number;
+}
+
+/**
+ * Ta Desktop's browser of the workbench keeps its own sign-ins. These take those of the user's browser:
+ * its cookies, never its passwords or history, once the user said yes in a dialog of the app (on macOS,
+ * the Keychain asks too).
+ */
+export interface WebBrowserData {
+    /** The profiles with cookies of the browsers installed. */
+    profiles(): Promise<WebBrowserProfile[]>;
+    /** Takes the cookies of a profile; `undefined` when the user said no. */
+    import(profileId: string): Promise<WebBrowserImport | undefined>;
+    /** Forgets the cookies, storage and cache of the browser of Ta. */
+    clear(): Promise<void>;
+}
+
+/** Files of a directory on a drag. */
+export interface WebDraggedFiles {
+    /** The directory they are of (`ui.useCwd()` or another): a path of the machine of ta serve, or `ssh://`. */
+    cwd: string;
+    /** Relative to `cwd`, with `/`. */
+    paths: string[];
+}
+
+export interface WebFileDrag {
+    set(dataTransfer: DataTransfer, files: WebDraggedFiles): void;
+    /** Whether a drag holds files: what `dragover` can tell, before the drop. */
+    has(dataTransfer: DataTransfer): boolean;
+    /** The files of a drop; undefined when it holds none. */
+    get(dataTransfer: DataTransfer): WebDraggedFiles | undefined;
+    /** Their absolute paths inside their machine. */
+    paths(files: WebDraggedFiles): string[];
+}
+
+export interface WebTerminalOptions {
+    /** Its size until a view fits it: the size the program started with. Default: 80 × 24. */
+    cols?: number;
+    rows?: number;
+    /**
+     * The directory of the program: paths of its output (`src/a.ts:10`) are read from there, and from the
+     * one a shell reports (OSC 7) once it does. URLs and paths are links, opened with Cmd or Ctrl + click
+     * as the links of a reply are (with Shift, a page in the browser of the system).
+     */
+    cwd?: string;
+}
+
+/** A terminal screen; the program behind it is the extension's (`pi.terminals` for a shell of the server). */
+export interface WebTerminal {
+    /** Its size in characters. */
+    readonly cols: number;
+    readonly rows: number;
+    /** Output of the program, with its control sequences. */
+    write(data: string): void;
+    /** What the user types or pastes, and the mouse reports the program asked for, as a terminal sends them. */
+    onData(listener: (data: string) => void): () => void;
+    /** It fitted a view of another size: the program should know it (`resizeTerminal`). */
+    onResize(listener: (size: { cols: number; rows: number }) => void): () => void;
+    /** Shows it in `element`, which it fills and follows in size; the function returned takes it out again. */
+    attach(element: HTMLElement): () => void;
+    focus(): void;
+    dispose(): void;
+}
+
 export interface WebFolderPickerProps {
     /** Where it opens; default: the directory of ta serve. */
     initial?: string;