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

package/dist/generated/workorder.d.ts

@@ -476,6 +476,21 @@ export type WorkOrderCreateParams = {
     needs_approval?: boolean;
     /** Existing Work Order to file this one beneath, making it part of that train. It must be one you can read with work_order.get; one you cannot is refused exactly as that read would refuse it. The new Work Order takes that parent's cohort, verbatim; beside it `cohort` accepts `{"new": true, "label"?: …}`, a sub-unit nested under the parent's cohort, and `{"of": "<work-order-id>"}`, joining the cohort of a Work Order in the parent's tree. */
     parent_id?: string;
+    /** Directories of the filing plugin's data volume this Work Order's dispatch is handed. Only a plugin may name them — as itself or acting for a person, or on create_child as the taker of its own off-tera work — and only for a type of its own vault; any other filer is refused (plugin_data_not_a_plugin). The dispatch is placed on the host holding the volume and sees the named directories and nothing else of it. Name input, output or both; neither may contain the other. */
+    plugin_data?: {
+        /** The one directory the dispatch reads, mounted read-only and told to the step in TERA_PLUGIN_DATA_INPUT. It must exist when the step starts (plugin_data_unavailable). */
+        input?: {
+            /** A clean relative path inside the plugin's data volume: no `..`, not absolute. */
+            dir: string;
+        };
+        /** The one directory the dispatch writes, told to the step in TERA_PLUGIN_DATA_OUTPUT. Created if absent; refused when not empty at the step's start (plugin_output_not_empty). */
+        output?: {
+            /** The most the directory may hold when the step ends: at least 1 GiB, at most the installation's hosted { step_output_limit }. Past it the step fails (plugin_output_bound_exceeded). */
+            bound_bytes: number;
+            /** A clean relative path inside the plugin's data volume: no `..`, not absolute. */
+            dir: string;
+        };
+    };
     /** Dispatch priority; higher runs sooner among ready Work Orders. */
     priority?: number;
     /** Typed, NON-CAUSAL relations from this Work Order to others (supersedes / duplicate_of / about / related). Each entry is a {relation, work_order_id} pair with an optional note, and `work_order_id` is a bare Work Order id — the same spelling `depends_on` and `parent_id` use, never a `vault://` ref. Set them here when the fact is known at filing time, which for the superseding case it usually is; discovered later, use work_order.relate. Three of the four gate nothing: no dispatch is blocked, delayed or cancelled by `duplicate_of`, `about` or `related`. A `supersedes` entry is the exception and it is the point of setting one here — it RETIRES the Work Order it names, in this call's own transaction: that Work Order moves to `superseded` with `superseded_by` set to this one, and can no longer be retried. The target must be in `failed:awaiting-ack`; one that is still running is refused, and the door is work_order.force_fail(id, reason) first. A terminal one is refused too — there is no retry to close — and so is a `supersedes` entry on a drafted create, since a draft may never be released. To record the claim WITHOUT moving the row, use work_order.relate. Same authorization as work_order.relate — a worker-class caller is refused, and an operator-class one needs `api/v1/workorders/relate` on top of its create grant, because the edge is the relate operation whichever call delivered it. Every target must exist, and no two entries may name the same target. Reach on the target is required for the two EVALUATIVE relations (`supersedes`, `duplicate_of`) and not for the two descriptive ones (`about`, `related`), per entry rather than per payload. */
@@ -590,6 +605,21 @@ export type WorkOrderCreateChildParams = {
     on_child_failure?: "fail-fast" | "wait-others" | "ignore";
     /** The off-tera Work Order you hold, to file this child beneath (ADR-139 D6). Honoured only for its current taker; omit it inside a dispatch, where the parent is the dispatch's own Work Order. */
     parent?: string;
+    /** Directories of the filing plugin's data volume this Work Order's dispatch is handed. Only a plugin may name them — as itself or acting for a person, or on create_child as the taker of its own off-tera work — and only for a type of its own vault; any other filer is refused (plugin_data_not_a_plugin). The dispatch is placed on the host holding the volume and sees the named directories and nothing else of it. Name input, output or both; neither may contain the other. */
+    plugin_data?: {
+        /** The one directory the dispatch reads, mounted read-only and told to the step in TERA_PLUGIN_DATA_INPUT. It must exist when the step starts (plugin_data_unavailable). */
+        input?: {
+            /** A clean relative path inside the plugin's data volume: no `..`, not absolute. */
+            dir: string;
+        };
+        /** The one directory the dispatch writes, told to the step in TERA_PLUGIN_DATA_OUTPUT. Created if absent; refused when not empty at the step's start (plugin_output_not_empty). */
+        output?: {
+            /** The most the directory may hold when the step ends: at least 1 GiB, at most the installation's hosted { step_output_limit }. Past it the step fails (plugin_output_bound_exceeded). */
+            bound_bytes: number;
+            /** A clean relative path inside the plugin's data volume: no `..`, not absolute. */
+            dir: string;
+        };
+    };
     /** Informational: echoed back for your own bookkeeping. What governs whether the parent waits is the wait it declares, not this field. */
     policy?: "wait-for-all" | "wait-for-any" | "fire-and-forget";
     /** Dispatch priority; higher runs sooner among ready Work Orders. */
@@ -974,6 +1004,9 @@ export type WorkOrderGetResult = {
                 at: string;
             };
             display_name?: string;
+            work_order?: string;
+            attempt?: number;
+            runner?: string;
         };
     };
     question?: {
@@ -994,6 +1027,7 @@ export type WorkOrderGetResult = {
             member?: string;
             pool?: string;
             pool_cause?: string;
+            pool_note?: string;
             verb?: string;
             repairable: boolean;
             refused_at?: string;
@@ -1404,12 +1438,35 @@ export type WorkOrderGetResult = {
     } | null;
     created_by?: string;
     created_via?: string;
+    released_via?: string;
+    lent_by?: string;
     arrival_evidence?: {
         [key: string]: string;
     };
     created_at: string;
     updated_at: string;
     off_tera: boolean;
+    attended?: {
+        host?: string;
+        personal: boolean;
+        candidate?: string;
+        unsandboxed: boolean;
+        unsandboxed_notice?: string;
+        attendee: string;
+        attached: {
+            views: number;
+            controller?: string;
+            size_setter?: string;
+            since?: string;
+            last_detached_at?: string;
+        } | null;
+        signal: {
+            signal: string;
+            message?: string;
+            at: string;
+            dropped?: number;
+        } | null;
+    };
     has_outputs?: boolean;
     archived: boolean;
     history?: {
@@ -1739,6 +1796,8 @@ export type WorkOrderInterruptResult = {
  * Schema: sdk/workorder/schema/v1/list.params.json
  */
 export type WorkOrderListParams = {
+    /** Select only attended Work Orders — sessions a person attends in a terminal — and carry on each row the `attended` projection work_order.get answers (host, personal, candidate, unsandboxed, attendee, attached, signal), so a list of sessions needs no get per row. Absent or false is no constraint, and rows then carry no projection. Unindexed on both store backends; pair it with `states` or `parent_id`. */
+    attended?: boolean;
     /** Select the Work Orders in this cohort — the undertaking a Work Order belongs to, read off any row's `cohort_id` (a Work Order filed alone is a cohort of one, whose id is its own). A UUID; anything else is refused rather than matched. Unlike `tag` this reads an indexed column on both store backends, so it is the filter to pass alone for 'everything in this undertaking', in every state, terminal included. Composes with the other filters as an AND. */
     cohort?: string;
     /** Select Work Orders filed with exactly this resolved capacity key. Matched verbatim against the key on the row, which is already materialized against that Work Order's own inputs — pass `prefilter/<subject id>`, not the type's `${inputs...}` template. This is how a caller asks 'is another Work Order of this tier already working my subject?' without reading inputs back out of every row. */
@@ -1816,6 +1875,27 @@ export type WorkOrderListResult = {
                 at: string;
             };
         };
+        attended?: {
+            host?: string;
+            personal: boolean;
+            candidate?: string;
+            unsandboxed: boolean;
+            unsandboxed_notice?: string;
+            attendee: string;
+            attached: {
+                views: number;
+                controller?: string;
+                size_setter?: string;
+                since?: string;
+                last_detached_at?: string;
+            } | null;
+            signal: {
+                signal: string;
+                message?: string;
+                at: string;
+                dropped?: number;
+            } | null;
+        };
     }[] | null;
 };
 /**
@@ -3115,6 +3195,7 @@ export type WorkOrderTreeResult = {
                 member?: string;
                 pool?: string;
                 pool_cause?: string;
+                pool_note?: string;
                 verb?: string;
                 repairable: boolean;
                 refused_at?: string;
@@ -3345,6 +3426,7 @@ export type WorkOrderTreeResult = {
                 member?: string;
                 pool?: string;
                 pool_cause?: string;
+                pool_note?: string;
                 verb?: string;
                 repairable: boolean;
                 refused_at?: string;

package/dist/generated/wsstream.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The close vocabulary of a tera stream (sdk/wsstream.CloseCodes).
+ *
+ * The WebSocket close codes a tera stream is closed with. Each states only what the hop that closed decided, and a relay passes a close on as it arrived. The reason beside a code is a code of at most 64 bytes of [a-z0-9_.:-], or "closed". A code is never renamed or given a new meaning; a client that meets a code it does not know treats it as retry_later (4001).
+ *
+ * Schema: sdk/wsstream/schema/v1/close-code.json
+ */
+export type StreamCloseCode = 1000 | 1001 | 1009 | 4000 | 4001 | 4003;
+/**
+ * Each member of StreamCloseCode, by name.
+ *
+ * Schema: sdk/wsstream/schema/v1/close-code.json
+ */
+export declare const STREAM_CLOSE_CODES: {
+    /** What the client does: what the protocol above said last; otherwise nothing. */
+    readonly ended: 1000;
+    /** What the client does: reconnects after backoff: the peer is stopping or stopped answering pings. */
+    readonly going_away: 1001;
+    /** What the client does: nothing: a message broke the route's bound, a client defect. */
+    readonly too_big: 1009;
+    /** What the client does: reconnects at once with the same identity: a token renewal. */
+    readonly reconnect: 4000;
+    /** What the client does: reconnects after backoff: the far side is unreachable or not ready. */
+    readonly retry_later: 4001;
+    /** What the client does: nothing until something changes; the reason is the error code. */
+    readonly refused: 4003;
+};
+/**
+ * Every type this module declares, mapped to the repository path of the schema
+ * it was generated from.
+ */
+export declare const STREAM_SCHEMAS: {
+    readonly StreamCloseCode: "sdk/wsstream/schema/v1/close-code.json";
+};

package/dist/generated/wsstream.js

@@ -0,0 +1,28 @@
+// Code generated by cmd/internal/genwebtypes from sdk/wsstream/schema/v1/; DO NOT EDIT.
+// Regenerate with `make web-types` (ADR-162 D4 item 1).
+/**
+ * Each member of StreamCloseCode, by name.
+ *
+ * Schema: sdk/wsstream/schema/v1/close-code.json
+ */
+export const STREAM_CLOSE_CODES = {
+    /** What the client does: what the protocol above said last; otherwise nothing. */
+    ended: 1000,
+    /** What the client does: reconnects after backoff: the peer is stopping or stopped answering pings. */
+    going_away: 1001,
+    /** What the client does: nothing: a message broke the route's bound, a client defect. */
+    too_big: 1009,
+    /** What the client does: reconnects at once with the same identity: a token renewal. */
+    reconnect: 4000,
+    /** What the client does: reconnects after backoff: the far side is unreachable or not ready. */
+    retry_later: 4001,
+    /** What the client does: nothing until something changes; the reason is the error code. */
+    refused: 4003,
+};
+/**
+ * Every type this module declares, mapped to the repository path of the schema
+ * it was generated from.
+ */
+export const STREAM_SCHEMAS = {
+    StreamCloseCode: "sdk/wsstream/schema/v1/close-code.json",
+};

package/dist/index.d.ts

@@ -1,16 +1,23 @@
 export { ROOT_BASE, ROUTE_PREFIX, appBase, routePath, underBase } from "./routes.ts";
 export { phoneURL } from "./phone.ts";
-export { TeraClient, KitRequestError, UNRECOGNIZED_RESPONSE, type FeedOptions, type InvokeVerdict, type KitErrorBody, type TeraClientOptions, type UploadOptions, type UploadProgress, type UploadRequest, type VerbRefusal, } from "./client.ts";
+export { SIGN_IN_REQUIRED, isSignInRequired, isSignInRequiredAnswer, reSignIn, type ReSignInOptions } from "./signin.ts";
+export { PLUGIN_BUSY, PLUGIN_STARTING, PLUGIN_RUNNER_UNREACHABLE, PLUGIN_NOT_ANSWERING, PLUGIN_UNREACHED_CODES, } from "./unreached.ts";
+export { TeraClient, KitRequestError, UNRECOGNIZED_RESPONSE, type FeedOptions, type StreamOptions, type TerminalOptions, type InvokeVerdict, type KitErrorBody, type TeraClientOptions, type UploadOptions, type UploadProgress, type UploadRequest, type VerbRefusal, } from "./client.ts";
 export { STEP_UP_HEADER, STEP_UP_POLL_MS, STEP_UP_REQUIRED, STEP_UP_RESUME_PARAM, StepUpError, resumedStepUp, stepUpChallengeOf, stepUpPageURL, type StepUpChallenge, type StepUpEnd, type StepUpOptions, type StepUpWindow, } from "./stepup.ts";
 export { BASE_DELAY_MS, MAX_DELAY_MS, REPLAY_LIMIT, REPLAY_WINDOW_MS, HEARTBEAT_GRACE_MS, REAUTHENTICATE_EVENT, FeedConnection, browserSignals, defaultOrderKey, type Clock, type FeedConnectionOptions, type FeedConnectionPhase, type FeedConnectionState, type FeedFrame, type FeedLoss, type FeedSignal, type FeedSignals, } from "./feed/connection.ts";
+export { IMMEDIATE_LIMIT, IMMEDIATE_WINDOW_MS, MAX_BUFFERED_BYTES, SEND_BUFFER_EXCEEDED, STABLE_OPEN_MS, StreamConnection, webSocketURL, type NormalCloseNext, type StreamConnectionOptions, type StreamConnectionState, type WebSocketLike, } from "./stream/connection.ts";
+export { ACK_EVERY, INPUT_GRANT_TIMEOUT, INPUT_GRANT_TIMEOUT_MS, INPUT_WINDOW, MAX_QUEUED_INPUT, MAX_SIGNALS_PER_GRANT, RESIZE_DEBOUNCE_MS, TerminalView, newViewId, nextAfterClose, type TerminalRenderer, type TerminalStatus, type TerminalViewOptions, } from "./terminal/view.ts";
 export { FeedOpenError, SSEParser, fetchOpener, isRefusal, type FeedOpener, type SSEEvent } from "./feed/sse.ts";
+export * as terminalwire from "./terminalwire/codec.ts";
 export type * from "./generated/feed.ts";
 export type * from "./generated/kit.ts";
 export type * from "./generated/shares.ts";
 export type * from "./generated/workorder.ts";
 export type * from "./generated/workorder-events.ts";
+export type * from "./generated/wsstream.ts";
 export { FEED_SCHEMAS } from "./generated/feed.ts";
 export { KIT_ROUTE_PREFIX, KIT_ROUTE_TABLE, KIT_PHONE_PATH, KIT_SCHEMAS, KIT_SIGNOUT_PATH } from "./generated/kit.ts";
 export { SHARES_SCHEMAS } from "./generated/shares.ts";
 export { WORK_ORDER_SCHEMAS } from "./generated/workorder.ts";
 export { WORK_ORDER_EVENT_SCHEMAS } from "./generated/workorder-events.ts";
+export { STREAM_CLOSE_CODES, STREAM_SCHEMAS } from "./generated/wsstream.ts";

package/dist/index.js

@@ -4,12 +4,21 @@
 // because the framework is the author's.
 export { ROOT_BASE, ROUTE_PREFIX, appBase, routePath, underBase } from "./routes.js";
 export { phoneURL } from "./phone.js";
+export { SIGN_IN_REQUIRED, isSignInRequired, isSignInRequiredAnswer, reSignIn } from "./signin.js";
+export { PLUGIN_BUSY, PLUGIN_STARTING, PLUGIN_RUNNER_UNREACHABLE, PLUGIN_NOT_ANSWERING, PLUGIN_UNREACHED_CODES, } from "./unreached.js";
 export { TeraClient, KitRequestError, UNRECOGNIZED_RESPONSE, } from "./client.js";
 export { STEP_UP_HEADER, STEP_UP_POLL_MS, STEP_UP_REQUIRED, STEP_UP_RESUME_PARAM, StepUpError, resumedStepUp, stepUpChallengeOf, stepUpPageURL, } from "./stepup.js";
 export { BASE_DELAY_MS, MAX_DELAY_MS, REPLAY_LIMIT, REPLAY_WINDOW_MS, HEARTBEAT_GRACE_MS, REAUTHENTICATE_EVENT, FeedConnection, browserSignals, defaultOrderKey, } from "./feed/connection.js";
+export { IMMEDIATE_LIMIT, IMMEDIATE_WINDOW_MS, MAX_BUFFERED_BYTES, SEND_BUFFER_EXCEEDED, STABLE_OPEN_MS, StreamConnection, webSocketURL, } from "./stream/connection.js";
+export { ACK_EVERY, INPUT_GRANT_TIMEOUT, INPUT_GRANT_TIMEOUT_MS, INPUT_WINDOW, MAX_QUEUED_INPUT, MAX_SIGNALS_PER_GRANT, RESIZE_DEBOUNCE_MS, TerminalView, newViewId, nextAfterClose, } from "./terminal/view.js";
 export { FeedOpenError, SSEParser, fetchOpener, isRefusal } from "./feed/sse.js";
+// The frames a view of an attended session's terminal speaks (ADR-180 D4):
+// github.com/kottera/sdk/terminalwire's codec in the browser, under one name,
+// so its frame and vocabulary names claim nothing at the package's root.
+export * as terminalwire from "./terminalwire/codec.js";
 export { FEED_SCHEMAS } from "./generated/feed.js";
 export { KIT_ROUTE_PREFIX, KIT_ROUTE_TABLE, KIT_PHONE_PATH, KIT_SCHEMAS, KIT_SIGNOUT_PATH } from "./generated/kit.js";
 export { SHARES_SCHEMAS } from "./generated/shares.js";
 export { WORK_ORDER_SCHEMAS } from "./generated/workorder.js";
 export { WORK_ORDER_EVENT_SCHEMAS } from "./generated/workorder-events.js";
+export { STREAM_CLOSE_CODES, STREAM_SCHEMAS } from "./generated/wsstream.js";

package/dist/signin.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Signing in again after tera forgets the page's session.
+ *
+ * tera's UI proxy holds a plugin origin's sessions in memory, so a daemon
+ * restart forgets every one. Only a page load can sign the person in again —
+ * silently, while their tera session lives — so the proxy answers anything
+ * else that arrives with no live session, a script's `fetch` among them, 401
+ * in the kit's envelope with code {@link SIGN_IN_REQUIRED}. The page recovers
+ * by loading itself again ({@link reSignIn}).
+ *
+ * That cannot loop: a page load never receives this answer, it starts the
+ * sign-in. A person whose tera session is gone too lands on tera's sign-in
+ * page, which is where they have to be.
+ *
+ * It is not the kit's `unauthenticated`, which says the request did reach the
+ * plugin, with no verified caller; loading the page again does not fix that.
+ *
+ * {@link TeraClient} and {@link FeedConnection} react on their own. A page
+ * reading one of the plugin's routes with its own `fetch` applies
+ * {@link isSignInRequired} to the response:
+ *
+ *     const res = await fetch("api/boards");
+ *     if (await isSignInRequired(res)) return reSignIn();
+ */
+/** The code of the proxy's answer to a request that needs the page loaded again to sign in. */
+export declare const SIGN_IN_REQUIRED = "sign_in_required";
+export interface ReSignInOptions {
+    /** Sends the page to a URL; `location.assign` when absent. */
+    navigate?: (url: string) => void;
+    /** The page's own URL, which is loaded again; `location.href` when absent. */
+    pageURL?: () => string;
+}
+/**
+ * Whether an answer is the proxy's `sign_in_required`: HTTP 401, a JSON body,
+ * and the kit's envelope carrying that code. Any other 401 — the kit's own
+ * `unauthenticated`, another code, a body that is not JSON — is not.
+ */
+export declare function isSignInRequiredAnswer(status: number, contentType: string, body: string): boolean;
+/**
+ * Whether `res` is the proxy's `sign_in_required` answer. It reads a copy of
+ * the body, so `res` can still be read by the caller.
+ */
+export declare function isSignInRequired(res: Response): Promise<boolean>;
+/**
+ * Loads the page again, a top-level navigation to its own URL, which signs
+ * the person in to the plugin's origin and returns them where they were.
+ */
+export declare function reSignIn(options?: ReSignInOptions): void;

package/dist/signin.js

@@ -0,0 +1,74 @@
+/**
+ * Signing in again after tera forgets the page's session.
+ *
+ * tera's UI proxy holds a plugin origin's sessions in memory, so a daemon
+ * restart forgets every one. Only a page load can sign the person in again —
+ * silently, while their tera session lives — so the proxy answers anything
+ * else that arrives with no live session, a script's `fetch` among them, 401
+ * in the kit's envelope with code {@link SIGN_IN_REQUIRED}. The page recovers
+ * by loading itself again ({@link reSignIn}).
+ *
+ * That cannot loop: a page load never receives this answer, it starts the
+ * sign-in. A person whose tera session is gone too lands on tera's sign-in
+ * page, which is where they have to be.
+ *
+ * It is not the kit's `unauthenticated`, which says the request did reach the
+ * plugin, with no verified caller; loading the page again does not fix that.
+ *
+ * {@link TeraClient} and {@link FeedConnection} react on their own. A page
+ * reading one of the plugin's routes with its own `fetch` applies
+ * {@link isSignInRequired} to the response:
+ *
+ *     const res = await fetch("api/boards");
+ *     if (await isSignInRequired(res)) return reSignIn();
+ */
+/** The code of the proxy's answer to a request that needs the page loaded again to sign in. */
+export const SIGN_IN_REQUIRED = "sign_in_required";
+const JSON_TYPE = "application/json";
+/**
+ * Whether an answer is the proxy's `sign_in_required`: HTTP 401, a JSON body,
+ * and the kit's envelope carrying that code. Any other 401 — the kit's own
+ * `unauthenticated`, another code, a body that is not JSON — is not.
+ */
+export function isSignInRequiredAnswer(status, contentType, body) {
+    if (status !== 401)
+        return false;
+    if (contentType.toLowerCase().split(";")[0].trim() !== JSON_TYPE)
+        return false;
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return false;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return false;
+    const error = parsed.error;
+    return typeof error === "object" && error !== null && error.code === SIGN_IN_REQUIRED;
+}
+/**
+ * Whether `res` is the proxy's `sign_in_required` answer. It reads a copy of
+ * the body, so `res` can still be read by the caller.
+ */
+export async function isSignInRequired(res) {
+    if (res.status !== 401)
+        return false;
+    let text;
+    try {
+        text = await res.clone().text();
+    }
+    catch {
+        return false;
+    }
+    return isSignInRequiredAnswer(res.status, res.headers.get("content-type") ?? "", text);
+}
+/**
+ * Loads the page again, a top-level navigation to its own URL, which signs
+ * the person in to the plugin's origin and returns them where they were.
+ */
+export function reSignIn(options = {}) {
+    const navigate = options.navigate ?? ((url) => globalThis.location.assign(url));
+    const pageURL = options.pageURL ?? (() => globalThis.location.href);
+    navigate(pageURL());
+}

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;
+}