@kottera/tera-web 0.1.0-rc.6 → 0.1.0-rc.7

package/dist/stream/connection.d.ts

@@ -0,0 +1,145 @@
+import { type Clock, type FeedSignals } from "../feed/connection.ts";
+/** Immediate reconnects allowed in {@link IMMEDIATE_WINDOW_MS} before the next is taken with backoff. */
+export declare const IMMEDIATE_LIMIT = 3;
+export declare const IMMEDIATE_WINDOW_MS = 30000;
+/** How long a socket stays open before the backoff resets. */
+export declare const STABLE_OPEN_MS = 10000;
+/** The most a page lets wait unsent before it treats the socket as a defect (ADR-181 D6 item 5). */
+export declare const MAX_BUFFERED_BYTES: number;
+/** The close reason the connection sends when it closes a socket for {@link MAX_BUFFERED_BYTES}. */
+export declare const SEND_BUFFER_EXCEEDED = "send_buffer_exceeded";
+/**
+ * The part of the browser's `WebSocket` the connection uses; a real one
+ * satisfies it.
+ */
+export interface WebSocketLike {
+    binaryType: string;
+    readonly bufferedAmount: number;
+    onopen: ((ev: unknown) => void) | null;
+    onmessage: ((ev: {
+        data: unknown;
+    }) => void) | null;
+    onclose: ((ev: {
+        code: number;
+        reason: string;
+    }) => void) | null;
+    onerror: ((ev: unknown) => void) | null;
+    send(data: ArrayBufferView | ArrayBuffer): void;
+    close(code?: number, reason?: string): void;
+}
+/**
+ * Where the connection is.
+ *
+ *   connecting    a socket is being opened; attempt 0 is the first, and an
+ *                 immediate reconnect keeps the attempt it had
+ *   open          the socket is open; messages flow
+ *   reconnecting  the socket ended and the next opens in `delayMs`
+ *   ended         nothing will be opened again; `code` is the close that ended
+ *                 it, and `reason` its reason, or what the probe answered
+ */
+export type StreamConnectionState = {
+    readonly phase: "connecting";
+    readonly attempt: number;
+} | {
+    readonly phase: "open";
+} | {
+    readonly phase: "reconnecting";
+    readonly attempt: number;
+    readonly delayMs: number;
+    readonly reason: string;
+} | {
+    readonly phase: "ended";
+    readonly code: number;
+    readonly reason: string;
+};
+/** What a normal closure (1000) of the current socket does, as the protocol above decided. */
+export type NormalCloseNext = "reconnect" | "backoff" | "end";
+export interface StreamConnectionOptions {
+    /** The stream route's path, built with {@link routePath}. */
+    path: string;
+    /** The one subprotocol the route speaks. */
+    subprotocol: string;
+    /** Read at every connect, so a resume offset in it is current. */
+    query?: () => URLSearchParams;
+    /** Each message, whole. A text message arrives as its UTF-8 bytes. */
+    onMessage: (data: ArrayBuffer) => void;
+    /** Every change of {@link StreamConnectionState}. */
+    onState?: (state: StreamConnectionState) => void;
+    /** The path the app is served under on its origin, as a client's `base` option names it; `/` when absent. */
+    base?: string;
+    /** Opens one socket; the browser's `WebSocket` when absent. */
+    socket?: (url: string, protocol: string) => WebSocketLike;
+    /** Sends the handshake's probe; the global `fetch` when absent. */
+    fetch?: typeof fetch;
+    /**
+     * Loads the page again when the probe answers `sign_in_required`;
+     * {@link reSignIn} when absent. A {@link TeraClient}'s stream passes the
+     * client's own, so the page is loaded once per client.
+     */
+    reSignIn?: () => void;
+    clock?: Clock;
+    /** The window's `online` event when absent; only `online` is acted on. */
+    signals?: FeedSignals;
+}
+/**
+ * webSocketURL resolves a path on the page's origin to the `ws:` or `wss:` URL
+ * a `WebSocket` is opened with. With no page URL — outside a browser — the
+ * path is answered as it is.
+ */
+export declare function webSocketURL(path: string, pageURL: string | undefined): string;
+export declare class StreamConnection {
+    private readonly options;
+    private readonly clock;
+    private readonly openSocket;
+    private view;
+    private unsubscribe;
+    private generation;
+    private ws;
+    private opened;
+    private retryTimer;
+    private stableTimer;
+    private attempt;
+    private immediate;
+    private normalNext;
+    /** Opens the first socket. */
+    constructor(options: StreamConnectionOptions);
+    get state(): StreamConnectionState;
+    /** The socket's URL as of now: the route under the app's base, with the query read afresh. */
+    get url(): string;
+    /** What the open socket has not yet handed to the network; 0 with none open. */
+    get bufferedAmount(): number;
+    /**
+     * Sends one message, answering whether it was handed to an open socket. A
+     * send that leaves more than {@link MAX_BUFFERED_BYTES} unsent closes the
+     * socket and reconnects with backoff.
+     */
+    send(message: ArrayBufferView): boolean;
+    /**
+     * Says what the normal closure (1000) that follows does: the protocol above
+     * read why the far side is ending, which the close code does not carry
+     * (ADR-181 D9 item 2). It holds for the current socket only; each new socket
+     * starts at `"end"`.
+     */
+    onNormalClose(next: NormalCloseNext): void;
+    /**
+     * Gives up on the open socket: closes it 1000 with `reason` and reconnects
+     * at once, within the ration. It is how the protocol above acts on a
+     * connection it finds dead, which a page cannot ping. With no socket open
+     * it does nothing.
+     */
+    reconnect(reason: string): void;
+    /** The page's own end: closes the socket 1000, and nothing is opened again. */
+    close(): void;
+    private set;
+    private teardown;
+    private connect;
+    private closed;
+    /** Settles a failed handshake with one same-origin request to the kit's `me` route. */
+    private probe;
+    /** Reconnects at once, within the ration; past it, with backoff. */
+    private reconnectNow;
+    private backoff;
+    private end;
+    /** Closes a socket the connection is giving up on, and stops listening to it. */
+    private drop;
+}

package/dist/stream/connection.js

@@ -0,0 +1,377 @@
+/**
+ * The stream connection: one WebSocket to a kit stream route (ADR-181 D7),
+ * held open for a page and reopened by the close code the far side chose
+ * (ADR-181 D9, D11 item 1). It is general: it carries whole binary messages
+ * and names no protocol above it — a terminal view tells it, through
+ * {@link StreamConnection.onNormalClose}, what a normal closure means.
+ *
+ * # What ends a socket, and what happens next
+ *
+ * | Ending                                     | Next                                       |
+ * |--------------------------------------------|--------------------------------------------|
+ * | 1000 `ended`                               | what {@link StreamConnection.onNormalClose} said last; otherwise end |
+ * | 1001 `going_away`                          | reconnect with backoff                     |
+ * | 1009 `too_big`                             | end: a message broke the route's bound     |
+ * | 4000 `reconnect`                           | reconnect at once, rationed (see Ration)   |
+ * | 4001 `retry_later`                         | reconnect with backoff                     |
+ * | 4003 `refused`                             | end; the reason is the refusal's code      |
+ * | any other code (1006: the network, a       | reconnect with backoff, as `retry_later`   |
+ * | peer that stopped answering pings)         | (ADR-181 D15 item 2)                       |
+ * | the handshake failed                       | one probe decides (see The handshake)      |
+ * | more than {@link MAX_BUFFERED_BYTES} unsent | close and reconnect with backoff           |
+ * | {@link StreamConnection.close}             | end: the page's own, 1000                  |
+ * | {@link StreamConnection.reconnect}         | reconnect at once, rationed                |
+ *
+ * # The handshake
+ *
+ * A browser tells a script nothing about a failed handshake — no status, no
+ * body, code 1006 — so the connection asks once, with a `GET` of the kit's
+ * `me` route on the same origin, which tera's UI proxy answers as it answered
+ * the upgrade:
+ *
+ * - `sign_in_required`: the person's session on the plugin's origin is gone.
+ *   The page is loaded again ({@link StreamConnectionOptions.reSignIn}), which
+ *   signs them in, and the connection ends.
+ * - A success: the session is live and the stream route refused or failed
+ *   for a reason of its own, so the connection reconnects with backoff.
+ * - No answer, a 5xx, a 408 or a 429: tera or the network is not there yet —
+ *   a daemon restarting — so it reconnects with backoff as well.
+ * - Anything else is a refusal, and the connection ends with its code.
+ *
+ * # Backoff, and the ration
+ *
+ * FeedConnection's constants: {@link BASE_DELAY_MS} doubling to
+ * {@link MAX_DELAY_MS}, each delay scaled by a jitter in [0.5, 1]. It resets
+ * once a socket has stayed open {@link STABLE_OPEN_MS}, not on a mere open, so
+ * a route that accepts and then closes every socket `retry_later` still backs
+ * off. A scheduled reconnect is taken at once when the network returns.
+ *
+ * An immediate reconnect — a `reconnect` close, or `"reconnect"` given to
+ * {@link StreamConnection.onNormalClose} — is rationed to
+ * {@link IMMEDIATE_LIMIT} in {@link IMMEDIATE_WINDOW_MS}; past it the next is
+ * taken with backoff, so a peer that closes `reconnect` in a loop cannot spin
+ * the page (ADR-181 D9 item 3).
+ *
+ * # Sending
+ *
+ * A `WebSocket`'s `send` never blocks: what the network has not taken waits in
+ * the page as `bufferedAmount`. The protocol above holds what it sends to its
+ * own window, so more than {@link MAX_BUFFERED_BYTES} waiting is a defect, and
+ * the connection closes the socket and reconnects rather than let it grow
+ * (ADR-181 D6 item 5). A message sent while no socket is open is not sent:
+ * {@link StreamConnection.send} answers false, and the protocol above resends
+ * from its own offsets once it is open again.
+ *
+ * It is a plain class with an injected socket, clock, fetch and signals, so its
+ * tests drive it with fake timers and a scripted socket and no network.
+ */
+import { routePath, underBase, ROOT_BASE } from "../routes.js";
+import { BASE_DELAY_MS, MAX_DELAY_MS } from "../feed/connection.js";
+import { SIGN_IN_REQUIRED, isSignInRequiredAnswer, reSignIn } from "../signin.js";
+import { STREAM_CLOSE_CODES } from "../generated/wsstream.js";
+/** Immediate reconnects allowed in {@link IMMEDIATE_WINDOW_MS} before the next is taken with backoff. */
+export const IMMEDIATE_LIMIT = 3;
+export const IMMEDIATE_WINDOW_MS = 30_000;
+/** How long a socket stays open before the backoff resets. */
+export const STABLE_OPEN_MS = 10_000;
+/** The most a page lets wait unsent before it treats the socket as a defect (ADR-181 D6 item 5). */
+export const MAX_BUFFERED_BYTES = 1 << 20;
+/** The close reason the connection sends when it closes a socket for {@link MAX_BUFFERED_BYTES}. */
+export const SEND_BUFFER_EXCEEDED = "send_buffer_exceeded";
+/** The code a browser reports for a socket that ended with no close frame: a failed handshake, a dropped network. */
+const ABNORMAL_CLOSURE = 1006;
+const realClock = {
+    now: () => Date.now(),
+    setTimeout: (fn, ms) => setTimeout(fn, ms),
+    clearTimeout: (handle) => clearTimeout(handle),
+    random: () => Math.random(),
+};
+/** The browser's `online` event; the connection reconnects on nothing else from outside. */
+const onlineSignal = (notify) => {
+    const win = globalThis;
+    const onOnline = () => notify("online");
+    win.addEventListener?.("online", onOnline);
+    return () => win.removeEventListener?.("online", onOnline);
+};
+const browserSocket = (url, protocol) => new WebSocket(url, protocol);
+/**
+ * webSocketURL resolves a path on the page's origin to the `ws:` or `wss:` URL
+ * a `WebSocket` is opened with. With no page URL — outside a browser — the
+ * path is answered as it is.
+ */
+export function webSocketURL(path, pageURL) {
+    if (pageURL === undefined)
+        return path;
+    const u = new URL(path, pageURL);
+    u.protocol = u.protocol === "https:" ? "wss:" : "ws:";
+    return u.href;
+}
+/** The name of each close code the connection knows, for a state's reason. */
+const CLOSE_NAMES = new Map(Object.entries(STREAM_CLOSE_CODES).map(([name, code]) => [code, name]));
+const encoder = new TextEncoder();
+export class StreamConnection {
+    options;
+    clock;
+    openSocket;
+    view = { phase: "connecting", attempt: 0 };
+    unsubscribe;
+    // Every socket, timer and probe belongs to one generation; a callback from
+    // an older one writes nothing.
+    generation = 0;
+    ws = null;
+    opened = false;
+    retryTimer = null;
+    stableTimer = null;
+    attempt = 0;
+    immediate = [];
+    normalNext = "end";
+    /** Opens the first socket. */
+    constructor(options) {
+        this.options = options;
+        this.clock = options.clock ?? realClock;
+        this.openSocket = options.socket ?? browserSocket;
+        this.unsubscribe = (options.signals ?? onlineSignal)((signal) => {
+            if (signal === "online" && this.retryTimer !== null)
+                this.connect();
+        });
+        this.connect();
+    }
+    get state() {
+        return this.view;
+    }
+    /** The socket's URL as of now: the route under the app's base, with the query read afresh. */
+    get url() {
+        const path = underBase(this.options.base ?? ROOT_BASE, this.options.path);
+        const query = this.options.query?.().toString() ?? "";
+        return webSocketURL(query === "" ? path : path + "?" + query, globalThis.location?.href);
+    }
+    /** What the open socket has not yet handed to the network; 0 with none open. */
+    get bufferedAmount() {
+        return this.opened ? (this.ws?.bufferedAmount ?? 0) : 0;
+    }
+    /**
+     * Sends one message, answering whether it was handed to an open socket. A
+     * send that leaves more than {@link MAX_BUFFERED_BYTES} unsent closes the
+     * socket and reconnects with backoff.
+     */
+    send(message) {
+        const ws = this.ws;
+        if (!this.opened || ws === null)
+            return false;
+        ws.send(message);
+        if (ws.bufferedAmount > MAX_BUFFERED_BYTES) {
+            this.drop(ws, 1000, SEND_BUFFER_EXCEEDED);
+            this.backoff(`more than ${MAX_BUFFERED_BYTES} bytes waited unsent`);
+        }
+        return true;
+    }
+    /**
+     * Says what the normal closure (1000) that follows does: the protocol above
+     * read why the far side is ending, which the close code does not carry
+     * (ADR-181 D9 item 2). It holds for the current socket only; each new socket
+     * starts at `"end"`.
+     */
+    onNormalClose(next) {
+        this.normalNext = next;
+    }
+    /**
+     * Gives up on the open socket: closes it 1000 with `reason` and reconnects
+     * at once, within the ration. It is how the protocol above acts on a
+     * connection it finds dead, which a page cannot ping. With no socket open
+     * it does nothing.
+     */
+    reconnect(reason) {
+        const ws = this.ws;
+        if (!this.opened || ws === null)
+            return;
+        this.drop(ws, STREAM_CLOSE_CODES.ended, reason);
+        this.reconnectNow(reason);
+    }
+    /** The page's own end: closes the socket 1000, and nothing is opened again. */
+    close() {
+        if (this.view.phase === "ended")
+            return;
+        const ws = this.ws;
+        this.end(STREAM_CLOSE_CODES.ended, "closed");
+        if (ws !== null)
+            ws.close(STREAM_CLOSE_CODES.ended, "closed");
+    }
+    set(state) {
+        this.view = state;
+        this.options.onState?.(state);
+    }
+    teardown() {
+        this.generation += 1;
+        const ws = this.ws;
+        this.ws = null;
+        this.opened = false;
+        if (ws !== null) {
+            ws.onopen = ws.onmessage = ws.onclose = ws.onerror = null;
+        }
+        if (this.retryTimer !== null)
+            this.clock.clearTimeout(this.retryTimer);
+        if (this.stableTimer !== null)
+            this.clock.clearTimeout(this.stableTimer);
+        this.retryTimer = null;
+        this.stableTimer = null;
+    }
+    connect() {
+        this.teardown();
+        const mine = this.generation;
+        this.normalNext = "end";
+        this.set({ phase: "connecting", attempt: this.attempt });
+        let ws;
+        try {
+            ws = this.openSocket(this.url, this.options.subprotocol);
+        }
+        catch (err) {
+            // The browser refused to open one at all: a malformed URL or a CSP that
+            // does not admit it. Neither changes on its own.
+            this.end(ABNORMAL_CLOSURE, err instanceof Error ? err.message : String(err));
+            return;
+        }
+        this.ws = ws;
+        ws.binaryType = "arraybuffer";
+        ws.onopen = () => {
+            if (mine !== this.generation)
+                return;
+            this.opened = true;
+            this.stableTimer = this.clock.setTimeout(() => {
+                this.stableTimer = null;
+                if (mine === this.generation)
+                    this.attempt = 0;
+            }, STABLE_OPEN_MS);
+            this.set({ phase: "open" });
+        };
+        ws.onmessage = (ev) => {
+            if (mine !== this.generation)
+                return;
+            const data = ev.data;
+            if (data instanceof ArrayBuffer)
+                this.options.onMessage(data);
+            else if (typeof data === "string")
+                this.options.onMessage(encoder.encode(data).buffer);
+        };
+        ws.onclose = (ev) => {
+            if (mine === this.generation)
+                this.closed(ev.code, ev.reason);
+        };
+    }
+    closed(code, reason) {
+        const why = reason !== "" ? reason : (CLOSE_NAMES.get(code) ?? `closed ${code}`);
+        if (!this.opened) {
+            this.teardown();
+            void this.probe(this.generation, code);
+            return;
+        }
+        switch (code) {
+            case STREAM_CLOSE_CODES.ended:
+                switch (this.normalNext) {
+                    case "reconnect":
+                        this.reconnectNow(why);
+                        return;
+                    case "backoff":
+                        this.backoff(why);
+                        return;
+                    case "end":
+                        this.end(code, reason);
+                        return;
+                }
+                return;
+            case STREAM_CLOSE_CODES.reconnect:
+                this.reconnectNow(why);
+                return;
+            case STREAM_CLOSE_CODES.too_big:
+            case STREAM_CLOSE_CODES.refused:
+                this.end(code, reason);
+                return;
+        }
+        // going_away, retry_later, and every code the vocabulary does not name
+        // (D15 item 2), a dropped network's 1006 among them.
+        this.backoff(why);
+    }
+    /** Settles a failed handshake with one same-origin request to the kit's `me` route. */
+    async probe(mine, code) {
+        let status;
+        let contentType;
+        let body;
+        try {
+            const fetchFn = this.options.fetch ?? globalThis.fetch.bind(globalThis);
+            const res = await fetchFn(underBase(this.options.base ?? ROOT_BASE, routePath("me")), {
+                method: "GET",
+                credentials: "same-origin",
+                headers: { accept: "application/json" },
+            });
+            status = res.status;
+            contentType = res.headers.get("content-type") ?? "";
+            body = await res.text();
+        }
+        catch (err) {
+            if (mine === this.generation)
+                this.backoff(`the handshake failed and its probe had no answer: ${err instanceof Error ? err.message : String(err)}`);
+            return;
+        }
+        if (mine !== this.generation)
+            return;
+        if (isSignInRequiredAnswer(status, contentType, body)) {
+            this.end(code, SIGN_IN_REQUIRED);
+            // The person's session on the plugin's origin is gone; only a page load
+            // brings it back, and that ends this connection with the page.
+            (this.options.reSignIn ?? reSignIn)();
+            return;
+        }
+        if ((status >= 200 && status < 300) || status >= 500 || status === 408 || status === 429) {
+            this.backoff(`the handshake failed; its probe answered ${status}`);
+            return;
+        }
+        this.end(code, refusalCode(contentType, body) ?? `http_${status}`);
+    }
+    /** Reconnects at once, within the ration; past it, with backoff. */
+    reconnectNow(why) {
+        const now = this.clock.now();
+        this.immediate = this.immediate.filter((at) => now - at < IMMEDIATE_WINDOW_MS);
+        if (this.immediate.length >= IMMEDIATE_LIMIT) {
+            this.backoff(`${why} (immediate reconnects rationed)`);
+            return;
+        }
+        this.immediate.push(now);
+        this.teardown();
+        this.set({ phase: "reconnecting", attempt: this.attempt, delayMs: 0, reason: why });
+        this.connect();
+    }
+    backoff(why) {
+        this.teardown();
+        this.attempt += 1;
+        const exp = Math.min(MAX_DELAY_MS, BASE_DELAY_MS * 2 ** (this.attempt - 1));
+        const delayMs = Math.round(exp * (0.5 + this.clock.random() * 0.5));
+        this.set({ phase: "reconnecting", attempt: this.attempt, delayMs, reason: why });
+        this.retryTimer = this.clock.setTimeout(() => {
+            this.retryTimer = null;
+            this.connect();
+        }, delayMs);
+    }
+    end(code, reason) {
+        this.teardown();
+        this.unsubscribe?.();
+        this.unsubscribe = null;
+        this.set({ phase: "ended", code, reason });
+    }
+    /** Closes a socket the connection is giving up on, and stops listening to it. */
+    drop(ws, code, reason) {
+        this.teardown();
+        ws.close(code, reason);
+    }
+}
+/** The kit's envelope's `error.code`, when the body is one. */
+function refusalCode(contentType, body) {
+    if (contentType.toLowerCase().split(";")[0].trim() !== "application/json")
+        return undefined;
+    try {
+        const parsed = JSON.parse(body);
+        const code = parsed?.error?.code;
+        return typeof code === "string" && code !== "" ? code : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/terminal/view.d.ts

@@ -0,0 +1,168 @@
+import type { Clock, FeedSignals } from "../feed/connection.ts";
+import { type NormalCloseNext, type StreamConnectionOptions, type StreamConnectionState } from "../stream/connection.ts";
+import { CloseReason, Role, type Size } from "../terminalwire/codec.ts";
+/** The `INPUT` a view sends beyond what the minder has granted back (ADR-180 D6 item 2). */
+export declare const INPUT_WINDOW: number;
+/** The parsed bytes that make one `ACK`; a renderer with nothing left to parse acknowledges sooner. */
+export declare const ACK_EVERY: number;
+/** How long a grant may stay outstanding before the view treats its socket as dead. */
+export declare const INPUT_GRANT_TIMEOUT_MS = 5000;
+/** The close reason the view gives up on a socket with after {@link INPUT_GRANT_TIMEOUT_MS}. */
+export declare const INPUT_GRANT_TIMEOUT = "input_grant_timeout";
+/** How long `resize` waits for the next before the size is sent. */
+export declare const RESIZE_DEBOUNCE_MS = 100;
+/** The most input the view queues for credit; a paste past it is dropped. */
+export declare const MAX_QUEUED_INPUT: number;
+/**
+ * The `SIGNAL`s sent between two grants: half of the 8 KiB control allowance
+ * outside the input window (ADR-180 D6 item 3), at five bytes a frame.
+ */
+export declare const MAX_SIGNALS_PER_GRANT: number;
+/**
+ * What draws the terminal. xterm.js's `Terminal` satisfies it as it is; the
+ * package bundles no emulator (ADR-181 D11 item 4).
+ */
+export interface TerminalRenderer {
+    /**
+     * Queues `data` to be drawn and calls `parsed` once it has been. `data` is
+     * a view of the message it arrived in, and the view never writes to it.
+     */
+    write(data: Uint8Array, parsed: () => void): void;
+}
+/** What the view knows of its session. */
+export interface TerminalStatus {
+    /** The view's id: a UUIDv7 minted when the view was made, kept across its reconnects. */
+    readonly viewId: string;
+    readonly connection: StreamConnectionState;
+    /** Whether the current socket's `WELCOME` has arrived; input is sent only then. */
+    readonly welcomed: boolean;
+    /** This view's part, as the minder last said: `viewer` until it says otherwise. */
+    readonly role: Role;
+    /** Whether this view's `RESIZE` sizes the pty. */
+    readonly setsSize: boolean;
+    readonly views: number;
+    /** The pty's size, which a view that does not set the size renders at. */
+    readonly size: Size;
+    /** The controlling view's id; empty when none controls. */
+    readonly controller: string;
+    /** The id of the view that sets the size. */
+    readonly sizeSetter: string;
+    /** A handover is waiting for the session to go quiet. */
+    readonly handoverPending: boolean;
+    /** The process's exit, once it has exited. */
+    readonly exit: {
+        readonly status: number;
+        readonly signal: string;
+    } | null;
+    /** History is being drawn, and input is dropped. */
+    readonly restoring: boolean;
+    /** The reason of the last `CLOSE` frame, until the next `WELCOME`. */
+    readonly closeReason: CloseReason | null;
+    /** Input bytes the view dropped: typed while restoring or after the end, past the queue's bound, or past the `SIGNAL` allowance. */
+    readonly dropped: number;
+}
+export interface TerminalViewOptions {
+    /** The attended session's Work Order. */
+    workOrder: string;
+    /** Whether the view asks to type when it attaches. */
+    want: "control" | "view";
+    renderer: TerminalRenderer;
+    /** The view's own size in cells, each from 1 to 65535. */
+    cols: number;
+    rows: number;
+    /** Every change of {@link TerminalStatus}. */
+    onStatus?: (status: TerminalStatus) => void;
+    /** The app's base, as a client's `base` option names it; `/` when absent. */
+    base?: string;
+    socket?: StreamConnectionOptions["socket"];
+    clock?: Clock;
+    /** The handshake probe's fetch, as {@link StreamConnectionOptions.fetch}. */
+    fetch?: typeof fetch;
+    /** As {@link StreamConnectionOptions.reSignIn}. */
+    reSignIn?: () => void;
+    signals?: FeedSignals;
+}
+/** A canonical lower-case UUIDv7 (RFC 9562) at `ms`, which the kit's terminal route requires of a view id. */
+export declare function newViewId(ms: number): string;
+/** What the normal closure after a `CLOSE` frame of `reason` does (ADR-181 D11 item 2). */
+export declare function nextAfterClose(reason: CloseReason): NormalCloseNext;
+export declare class TerminalView {
+    readonly viewId: string;
+    private readonly renderer;
+    private readonly clock;
+    private readonly onStatus;
+    private readonly conn;
+    private want;
+    private local;
+    private sent;
+    private gen;
+    private connection;
+    private welcomed;
+    private ended;
+    private role;
+    private setsSize;
+    private views;
+    private size;
+    private controller;
+    private sizeSetter;
+    private handoverPending;
+    private exit;
+    private closeReason;
+    private dropped;
+    private takeSent;
+    private hasOffset;
+    private base;
+    private handed;
+    private unacked;
+    private pending;
+    private restoring;
+    private writeSeq;
+    private parsedSeq;
+    private replayEndSeq;
+    private readonly queue;
+    private queueHead;
+    private queued;
+    private inFlight;
+    private signalsSinceGrant;
+    private grantTimer;
+    private resizeTimer;
+    /** Opens the view's socket at once. */
+    constructor(options: TerminalViewOptions);
+    get status(): TerminalStatus;
+    /**
+     * Sends what the person typed: what xterm.js's `onData` hands the page, a
+     * string sent as its UTF-8 bytes. A `Uint8Array` is copied, so the caller
+     * may reuse it.
+     */
+    input(data: string | Uint8Array): void;
+    /** The view's own size changed. It reaches the pty only while this view sets the size. */
+    resize(cols: number, rows: number): void;
+    /** Asks for control now, rather than at the next keystroke. */
+    takeControl(): void;
+    /** The page's own end: tells the minder the view detached, and closes the socket. */
+    detach(): void;
+    private get ready();
+    private emit;
+    private query;
+    private connectionState;
+    private message;
+    private apply;
+    private welcome;
+    private statusFrame;
+    private data;
+    private parsed;
+    private startRestoring;
+    /** Ends the restoring once the renderer has parsed every write before REPLAY_END. */
+    private restored;
+    private granted;
+    /** Sends queued input as far as the window allows. */
+    private pump;
+    private signal;
+    private sendTake;
+    private drop;
+    private discardQueue;
+    private armGrantTimer;
+    private clearGrantTimer;
+    private scheduleResize;
+    private clearResizeTimer;
+}