@kottera/tera-web 0.0.0-stage → 0.1.0-rc.10

package/dist/terminalwire/codec.js

@@ -0,0 +1,556 @@
+// The terminalwire codec (ADR-180 D4; ADR-181 D11 item 3): the frames a view
+// of an attended session's terminal speaks, read and written in the browser.
+// It is github.com/kottera/sdk/terminalwire's, and the committed corpus
+// sdk/testdata/terminalwire-corpus.json holds the two to one wire.
+//
+// A frame is a 4-byte header — one byte of type, three of payload length,
+// little-endian — and its payload; one frame rides in one binary WebSocket
+// message. Control bodies are CBOR from a closed subset this file reads and
+// writes by hand, so the package keeps no runtime dependency: one map of
+// definite length, text keys, and values that are unsigned integers, UTF-8
+// text or booleans. An offset is at most MAX_OFFSET (2^53-1), so it is a
+// number; an encoder refuses an offset past it, or a string with a lone
+// surrogate, with a RangeError rather than write a body its decoder refuses.
+// A field this version does not know is skipped whatever well-formed item it
+// is; a frame type this version does not know is ignored (`isKnownFrameType`).
+// The protocol only grows: types and fields are append-only.
+//
+// Decoding copies nothing: a frame's payload is a view of the message's
+// buffer, so a DATA payload goes to the renderer as it arrived.
+import { collapseCloseReason, collapseRole } from "./collapse.js";
+/** The protocol version this codec speaks. */
+export const VERSION = 1;
+/** The WebSocket subprotocol a view negotiates. */
+export const SUBPROTOCOL = "tera.terminalwire.v1";
+export const HEADER_SIZE = 4;
+/** The bound on a DATA or INPUT payload: the runner link's stream frame. */
+export const MAX_DATA_PAYLOAD = 16 << 10;
+/** The bound on a CBOR control body. */
+export const MAX_CONTROL_PAYLOAD = 4 << 10;
+/** The bound on any frame's payload, a type this version does not know included. */
+export const MAX_PAYLOAD = MAX_DATA_PAYLOAD;
+/** The largest frame, and so the largest message, on the wire. */
+export const MAX_FRAME_BYTES = HEADER_SIZE + MAX_PAYLOAD;
+/**
+ * The bound on an output offset, 2^53-1: every offset the wire admits is a
+ * number held exactly. An encoder refuses one above it and a decoder reads a
+ * body carrying one as malformed, as the Go codec does.
+ */
+export const MAX_OFFSET = Number.MAX_SAFE_INTEGER;
+/**
+ * The frame types of version 1. Zero is no frame; a value is never reassigned.
+ * SIGNAL carries one keystroke's character outside the input window; its
+ * contract is sdk/terminalwire's `TypeSignal` (`encodeSignal`).
+ */
+export const FrameType = {
+    Welcome: 1,
+    Data: 2,
+    Resync: 3,
+    ReplayEnd: 4,
+    InputAck: 5,
+    Status: 6,
+    Close: 7,
+    Input: 8,
+    Ack: 9,
+    Resize: 10,
+    Control: 11,
+    Signal: 12,
+};
+const frameTypeNames = [
+    "",
+    "WELCOME",
+    "DATA",
+    "RESYNC",
+    "REPLAY_END",
+    "INPUT_ACK",
+    "STATUS",
+    "CLOSE",
+    "INPUT",
+    "ACK",
+    "RESIZE",
+    "CONTROL",
+    "SIGNAL",
+];
+/** Whether this version knows frame type `t`. A receiver ignores a frame it does not. */
+export function isKnownFrameType(t) {
+    return Number.isInteger(t) && t > 0 && t < frameTypeNames.length;
+}
+/** The wire name of a frame type: `WELCOME`, `DATA`, …; `FrameType(42)` for one this version does not know. */
+export function frameTypeName(t) {
+    return isKnownFrameType(t) ? frameTypeNames[t] : `FrameType(${t})`;
+}
+export class TerminalwireError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(`terminalwire: ${message}`);
+        this.name = "TerminalwireError";
+        this.kind = kind;
+    }
+}
+const malformed = (why) => new TerminalwireError("malformed", why);
+/**
+ * A view's part in its session (ADR-180 D7). A peek (ADR-190 D7) is output
+ * only and never counted as attached; a version that predates it reads it as
+ * a viewer. Members are appended, never reordered.
+ */
+export const Role = { Controller: "controller", Viewer: "viewer", Peeker: "peeker" };
+const roles = Object.values(Role);
+/** Why a view ended, from a closed set (ADR-180 D4). Members are appended, never reordered. */
+export const CloseReason = {
+    Detached: "detached",
+    Exited: "exited",
+    Handover: "handover",
+    Reauthenticate: "reauthenticate",
+    NotAttendee: "not-attendee",
+    Superseded: "superseded",
+    RunnerUnreachable: "runner-unreachable",
+    FlowControl: "flow-control",
+    Expired: "expired",
+    // A peek fell behind (ADR-190 D7 item 3): its client opens it again at once,
+    // with no resume offset, for a fresh replay. A version that predates it
+    // reads it as detached, and still reads `reconnect`.
+    Reopen: "reopen",
+};
+const closeReasons = Object.values(CloseReason);
+/** What a CONTROL frame asks (ADR-180 D7). */
+export const ControlAction = { Take: "take", Release: "release" };
+const controlActions = Object.values(ControlAction);
+// Each vocabulary's decoder collapses a value it does not know to the safe
+// member (compat-policy §3.5): a role to viewer, so a client never believes it
+// types into a session it does not control; a close reason to detached, so
+// nothing about it is retried (`reconnect` is still read); an action to
+// release, which never moves control to the sender.
+const decodeRole = (s) => collapseRole(roles, s);
+const decodeCloseReason = (s) => collapseCloseReason(closeReasons, s);
+const decodeControlAction = (s) => s === ControlAction.Take ? ControlAction.Take : ControlAction.Release;
+const MAX_U8 = 0xff;
+const MAX_U16 = 0xffff;
+const MAX_U32 = 0xffffffff;
+// uint answers v when it is an integer the field's width holds, so an encoder
+// never writes a body its own decoder refuses.
+function uint(v, max, field) {
+    if (!Number.isInteger(v) || v < 0 || v > max)
+        throw new RangeError(`terminalwire: ${field} ${v} is out of range`);
+    return v;
+}
+function payloadBound(t) {
+    if (t === FrameType.Data || t === FrameType.Input)
+        return MAX_DATA_PAYLOAD;
+    return isKnownFrameType(t) ? MAX_CONTROL_PAYLOAD : MAX_PAYLOAD;
+}
+function asBytes(msg) {
+    return msg instanceof Uint8Array ? msg : new Uint8Array(msg);
+}
+/** Reads a header: the frame type and the payload length. */
+export function parseHeader(msg) {
+    const b = asBytes(msg);
+    if (b.length < HEADER_SIZE)
+        throw new TerminalwireError("truncated", "a header is 4 bytes");
+    const type = b[0];
+    const length = b[1] | (b[2] << 8) | (b[3] << 16);
+    if (length > payloadBound(type)) {
+        throw new TerminalwireError("too_large", `a ${frameTypeName(type)} payload of ${length} bytes`);
+    }
+    return { type, length };
+}
+/** Reads a message holding exactly one frame. The payload aliases the message. */
+export function decodeFrame(msg) {
+    const b = asBytes(msg);
+    const { type, length } = parseHeader(b);
+    if (b.length - HEADER_SIZE < length)
+        throw new TerminalwireError("truncated", "a frame shorter than its header");
+    if (b.length !== HEADER_SIZE + length)
+        throw malformed(`${b.length - HEADER_SIZE - length} bytes after the frame`);
+    return { type, payload: b.subarray(HEADER_SIZE) };
+}
+function withHeader(type, payload) {
+    if (payload.length > payloadBound(type)) {
+        throw new TerminalwireError("too_large", `a ${frameTypeName(type)} payload of ${payload.length} bytes`);
+    }
+    const out = new Uint8Array(HEADER_SIZE + payload.length);
+    out[0] = type;
+    out[1] = payload.length & 0xff;
+    out[2] = (payload.length >> 8) & 0xff;
+    out[3] = (payload.length >> 16) & 0xff;
+    out.set(payload, HEADER_SIZE);
+    return out;
+}
+function expectType(f, ...types) {
+    if (!types.includes(f.type))
+        throw new TerminalwireError("wrong_type", `a ${frameTypeName(f.type)} frame`);
+}
+/** A DATA or INPUT frame of `bytes`. */
+export function encodeBytes(type, bytes) {
+    if (type !== FrameType.Data && type !== FrameType.Input)
+        throw new TerminalwireError("wrong_type", frameTypeName(type));
+    return withHeader(type, bytes);
+}
+export function encodeReplayEnd() {
+    return withHeader(FrameType.ReplayEnd, new Uint8Array(0));
+}
+/** An ACK or INPUT_ACK frame of `count` bytes. */
+export function encodeCount(type, count) {
+    if (type !== FrameType.Ack && type !== FrameType.InputAck)
+        throw new TerminalwireError("wrong_type", frameTypeName(type));
+    if (!Number.isInteger(count) || count < 0 || count > MAX_U32)
+        throw new RangeError(`terminalwire: count ${count} is not a u32`);
+    const p = new Uint8Array(4);
+    new DataView(p.buffer).setUint32(0, count, true);
+    return withHeader(type, p);
+}
+/** An ACK or INPUT_ACK frame's count. Bytes past the first four are a later version's. */
+export function decodeCount(f) {
+    expectType(f, FrameType.Ack, FrameType.InputAck);
+    if (f.payload.length < 4)
+        throw malformed("a count is 4 bytes");
+    return new DataView(f.payload.buffer, f.payload.byteOffset, 4).getUint32(0, true);
+}
+/**
+ * A SIGNAL frame of one keystroke's character, `char` the byte the key
+ * produces (0x03 for Ctrl-C). It rides outside the input window, so it is how
+ * an interrupt reaches a session whose window is full (PRD-031 SC6). The
+ * minder signals the foreground process group when the byte is the pty's
+ * interrupt, quit or suspend character and ISIG is set, and drops it
+ * otherwise; it never queues it and never grants it back. A client sends a
+ * keystroke as INPUT while its credit holds it, and a one-byte keystroke the
+ * credit cannot hold as one SIGNAL instead of holding it for credit, once per
+ * keystroke (sdk/terminalwire `TypeSignal` states the whole contract).
+ */
+export function encodeSignal(char) {
+    if (!Number.isInteger(char) || char < 0 || char > MAX_U8)
+        throw new RangeError(`terminalwire: character ${char} is not a u8`);
+    return withHeader(FrameType.Signal, Uint8Array.of(char));
+}
+/** A SIGNAL frame's character. Bytes past the first are a later version's. */
+export function decodeSignal(f) {
+    expectType(f, FrameType.Signal);
+    if (f.payload.length < 1)
+        throw malformed("a character is 1 byte");
+    return f.payload[0];
+}
+export function encodeResize(size) {
+    for (const v of [size.cols, size.rows]) {
+        if (!Number.isInteger(v) || v < 0 || v > MAX_U16)
+            throw new RangeError(`terminalwire: size ${v} is not a u16`);
+    }
+    const p = new Uint8Array(4);
+    const dv = new DataView(p.buffer);
+    dv.setUint16(0, size.cols, true);
+    dv.setUint16(2, size.rows, true);
+    return withHeader(FrameType.Resize, p);
+}
+/** A RESIZE frame's size. Bytes past the first four are a later version's. */
+export function decodeResize(f) {
+    expectType(f, FrameType.Resize);
+    if (f.payload.length < 4)
+        throw malformed("a size is 4 bytes");
+    const dv = new DataView(f.payload.buffer, f.payload.byteOffset, 4);
+    return { cols: dv.getUint16(0, true), rows: dv.getUint16(2, true) };
+}
+// --- CBOR, the closed subset -------------------------------------------------
+const MAJOR_UINT = 0;
+const MAJOR_TEXT = 3;
+const MAJOR_MAP = 5;
+const CBOR_FALSE = 0xf4;
+const CBOR_TRUE = 0xf5;
+// An unknown field's value nests at most this deep.
+const MAX_SKIP_DEPTH = 16;
+const utf8Encoder = new TextEncoder();
+// A lone surrogate has no UTF-8 form: TextEncoder would write U+FFFD for it.
+const loneSurrogate = /\p{Surrogate}/u;
+const utf8Decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+class Writer {
+    parts = [];
+    head(major, v) {
+        const p = this.parts;
+        if (v < 24)
+            p.push((major << 5) | v);
+        else if (v <= 0xff)
+            p.push((major << 5) | 24, v);
+        else if (v <= 0xffff)
+            p.push((major << 5) | 25, v >> 8, v & 0xff);
+        else if (v <= MAX_U32)
+            p.push((major << 5) | 26, (v >>> 24) & 0xff, (v >>> 16) & 0xff, (v >>> 8) & 0xff, v & 0xff);
+        else {
+            const big = BigInt(v);
+            p.push((major << 5) | 27);
+            for (let shift = 56n; shift >= 0n; shift -= 8n)
+                p.push(Number((big >> shift) & 0xffn));
+        }
+    }
+    text(s) {
+        if (loneSurrogate.test(s))
+            throw new RangeError("terminalwire: text that is not well-formed Unicode");
+        const b = utf8Encoder.encode(s);
+        this.head(MAJOR_TEXT, b.length);
+        for (const x of b)
+            this.parts.push(x);
+    }
+    value(v) {
+        if (typeof v === "boolean")
+            this.parts.push(v ? CBOR_TRUE : CBOR_FALSE);
+        else if (typeof v === "string")
+            this.text(v);
+        else
+            this.head(MAJOR_UINT, v);
+    }
+    bytes() {
+        return Uint8Array.from(this.parts);
+    }
+}
+// encodeBody writes the fields in order, leaving out each at its zero value,
+// so absent and zero are one reading.
+function encodeBody(type, fields) {
+    const present = fields.filter(([, v]) => v !== 0 && v !== "" && v !== false);
+    const w = new Writer();
+    w.head(MAJOR_MAP, present.length);
+    for (const [k, v] of present) {
+        w.text(k);
+        w.value(v);
+    }
+    return withHeader(type, w.bytes());
+}
+class Reader {
+    off = 0;
+    p;
+    dv;
+    constructor(p) {
+        this.p = p;
+        this.dv = new DataView(p.buffer, p.byteOffset, p.byteLength);
+    }
+    // head reads an initial byte and its argument. A 64-bit argument past what a
+    // number holds exactly reads as Infinity, which every bound refuses.
+    head() {
+        if (this.off >= this.p.length)
+            throw malformed("a body ends inside an item");
+        const ib = this.p[this.off++];
+        const major = ib >> 5;
+        const info = ib & 0x1f;
+        if (info < 24)
+            return [major, info];
+        const n = info === 24 ? 1 : info === 25 ? 2 : info === 26 ? 4 : info === 27 ? 8 : 0;
+        if (n === 0)
+            throw malformed(`additional information ${info}`);
+        if (this.p.length - this.off < n)
+            throw malformed("a body ends inside a head");
+        const at = this.off;
+        this.off += n;
+        switch (n) {
+            case 1:
+                return [major, this.p[at]];
+            case 2:
+                return [major, this.dv.getUint16(at)];
+            case 4:
+                return [major, this.dv.getUint32(at)];
+            default: {
+                const big = this.dv.getBigUint64(at);
+                return [major, big <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(big) : Infinity];
+            }
+        }
+    }
+    mapHeader() {
+        const [major, n] = this.head();
+        if (major !== MAJOR_MAP || n > this.p.length)
+            throw malformed("a body is one map");
+        return n;
+    }
+    text() {
+        const [major, n] = this.head();
+        if (major !== MAJOR_TEXT || n > this.p.length - this.off)
+            throw malformed("not a text string");
+        const s = this.p.subarray(this.off, this.off + n);
+        this.off += n;
+        try {
+            return utf8Decoder.decode(s);
+        }
+        catch {
+            throw malformed("text that is not UTF-8");
+        }
+    }
+    uint(max) {
+        const [major, v] = this.head();
+        if (major !== MAJOR_UINT || v > max)
+            throw malformed("not an unsigned integer in range");
+        return v;
+    }
+    bool() {
+        const b = this.p[this.off];
+        if (b !== CBOR_TRUE && b !== CBOR_FALSE)
+            throw malformed("not a boolean");
+        this.off++;
+        return b === CBOR_TRUE;
+    }
+    // skip passes over one well-formed definite-length item of any major type:
+    // the value of a field this version does not know.
+    skip(depth) {
+        if (depth > MAX_SKIP_DEPTH)
+            throw malformed("a value nested too deep");
+        const [major, v] = this.head();
+        switch (major) {
+            case 0:
+            case 1:
+            case 7:
+                return;
+            case 2:
+            case 3:
+                if (v > this.p.length - this.off)
+                    throw malformed("a string past the body");
+                this.off += v;
+                return;
+            case 4:
+            case 5: {
+                if (major === 5 && v > this.p.length)
+                    throw malformed("a map past the body");
+                const items = major === 5 ? v * 2 : v;
+                if (items > this.p.length - this.off)
+                    throw malformed("an array past the body");
+                for (let i = 0; i < items; i++)
+                    this.skip(depth + 1);
+                return;
+            }
+            default:
+                this.skip(depth + 1);
+        }
+    }
+    done() {
+        if (this.off !== this.p.length)
+            throw malformed("bytes after the body's map");
+    }
+}
+// decodeBody walks a body's map, handing each known key's value to its reader
+// once and skipping every other.
+function decodeBody(payload, fields) {
+    const r = new Reader(payload);
+    const pairs = r.mapHeader();
+    const seen = new Set();
+    for (let i = 0; i < pairs; i++) {
+        const k = r.text();
+        const read = Object.hasOwn(fields, k) ? fields[k] : undefined;
+        if (read === undefined) {
+            r.skip(0);
+            continue;
+        }
+        if (seen.has(k))
+            throw malformed(`field ${k} twice`);
+        seen.add(k);
+        read(r);
+    }
+    r.done();
+}
+function requireMember(v, members, what) {
+    if (!members.includes(v))
+        throw new TerminalwireError("not_in_vocabulary", `${what} ${JSON.stringify(v)}`);
+}
+export function encodeWelcome(w) {
+    requireMember(w.role, roles, "role");
+    return encodeBody(FrameType.Welcome, [
+        ["version", uint(w.version, MAX_U32, "version")],
+        ["view_id", w.viewId],
+        ["role", w.role],
+        ["sets_size", w.setsSize],
+        ["cols", uint(w.size.cols, MAX_U16, "cols")],
+        ["rows", uint(w.size.rows, MAX_U16, "rows")],
+        ["offset", uint(w.offset, MAX_OFFSET, "offset")],
+        ["replay", w.replay],
+        ["views", uint(w.views, MAX_U32, "views")],
+    ]);
+}
+export function decodeWelcome(f) {
+    expectType(f, FrameType.Welcome);
+    const w = { version: 0, viewId: "", role: Role.Viewer, setsSize: false, size: { cols: 0, rows: 0 }, offset: 0, replay: false, views: 0 };
+    decodeBody(f.payload, {
+        version: (r) => (w.version = r.uint(MAX_U32)),
+        view_id: (r) => (w.viewId = r.text()),
+        role: (r) => (w.role = decodeRole(r.text())),
+        sets_size: (r) => (w.setsSize = r.bool()),
+        cols: (r) => (w.size.cols = r.uint(MAX_U16)),
+        rows: (r) => (w.size.rows = r.uint(MAX_U16)),
+        offset: (r) => (w.offset = r.uint(MAX_OFFSET)),
+        replay: (r) => (w.replay = r.bool()),
+        views: (r) => (w.views = r.uint(MAX_U32)),
+    });
+    return w;
+}
+export function encodeResync(s) {
+    return encodeBody(FrameType.Resync, [
+        ["offset", uint(s.offset, MAX_OFFSET, "offset")],
+        ["replay", s.replay],
+    ]);
+}
+export function decodeResync(f) {
+    expectType(f, FrameType.Resync);
+    const s = { offset: 0, replay: false };
+    decodeBody(f.payload, {
+        offset: (r) => (s.offset = r.uint(MAX_OFFSET)),
+        replay: (r) => (s.replay = r.bool()),
+    });
+    return s;
+}
+export function encodeStatus(s) {
+    requireMember(s.role, roles, "role");
+    return encodeBody(FrameType.Status, [
+        ["role", s.role],
+        ["views", uint(s.views, MAX_U32, "views")],
+        ["cols", uint(s.size.cols, MAX_U16, "cols")],
+        ["rows", uint(s.size.rows, MAX_U16, "rows")],
+        ["controller", s.controller],
+        ["size_setter", s.sizeSetter],
+        ["handover_pending", s.handoverPending],
+        ["exited", s.exited],
+        ["exit_status", uint(s.exitStatus, MAX_U32, "exit_status")],
+        ["exit_signal", s.exitSignal],
+    ]);
+}
+export function decodeStatus(f) {
+    expectType(f, FrameType.Status);
+    const s = {
+        role: Role.Viewer,
+        views: 0,
+        size: { cols: 0, rows: 0 },
+        controller: "",
+        sizeSetter: "",
+        handoverPending: false,
+        exited: false,
+        exitStatus: 0,
+        exitSignal: "",
+    };
+    decodeBody(f.payload, {
+        role: (r) => (s.role = decodeRole(r.text())),
+        views: (r) => (s.views = r.uint(MAX_U32)),
+        cols: (r) => (s.size.cols = r.uint(MAX_U16)),
+        rows: (r) => (s.size.rows = r.uint(MAX_U16)),
+        controller: (r) => (s.controller = r.text()),
+        size_setter: (r) => (s.sizeSetter = r.text()),
+        handover_pending: (r) => (s.handoverPending = r.bool()),
+        exited: (r) => (s.exited = r.bool()),
+        exit_status: (r) => (s.exitStatus = r.uint(MAX_U32)),
+        exit_signal: (r) => (s.exitSignal = r.text()),
+    });
+    return s;
+}
+export function encodeClose(c) {
+    requireMember(c.reason, closeReasons, "close reason");
+    return encodeBody(FrameType.Close, [
+        ["reason", c.reason],
+        ["reconnect", c.reconnect],
+    ]);
+}
+export function decodeClose(f) {
+    expectType(f, FrameType.Close);
+    const c = { reason: CloseReason.Detached, reconnect: false };
+    decodeBody(f.payload, {
+        reason: (r) => (c.reason = decodeCloseReason(r.text())),
+        reconnect: (r) => (c.reconnect = r.bool()),
+    });
+    return c;
+}
+export function encodeControl(c) {
+    requireMember(c.action, controlActions, "control action");
+    return encodeBody(FrameType.Control, [["action", c.action]]);
+}
+export function decodeControl(f) {
+    expectType(f, FrameType.Control);
+    const c = { action: ControlAction.Release };
+    decodeBody(f.payload, { action: (r) => (c.action = decodeControlAction(r.text())) });
+    return c;
+}

package/dist/terminalwire/collapse.d.ts

@@ -0,0 +1,4 @@
+/** Reads a role against vocabulary, collapsing one outside it to viewer. */
+export declare const collapseRole: (vocabulary: readonly string[], s: string) => string;
+/** Reads a close reason against vocabulary, collapsing one outside it to detached. */
+export declare const collapseCloseReason: (vocabulary: readonly string[], s: string) => string;

package/dist/terminalwire/collapse.js

@@ -0,0 +1,7 @@
+// The role and close-reason decoders' collapses, kept out of the public
+// `terminalwire` namespace so a test can read a value with the vocabulary an
+// earlier version knew.
+/** Reads a role against vocabulary, collapsing one outside it to viewer. */
+export const collapseRole = (vocabulary, s) => vocabulary.includes(s) ? s : "viewer";
+/** Reads a close reason against vocabulary, collapsing one outside it to detached. */
+export const collapseCloseReason = (vocabulary, s) => vocabulary.includes(s) ? s : "detached";

package/dist/unreached.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The plugin was not reached: what tera's UI proxy answers the page's script
+ * when the plugin behind it did not answer.
+ *
+ * A page load is answered a page saying why. Anything else — a `fetch`, an
+ * XHR upload, a feed stream, a write, a WebSocket upgrade — is answered in
+ * the kit's envelope, `{"error": {"code", "message", "retryable"}}`, with one
+ * of these codes, so a page tells a plugin that is down or starting from one
+ * of its own failures and shows the proxy's `message`, a sentence for the
+ * person naming the plugin and why. Every one is retryable, and the two 503s
+ * carry `Retry-After`:
+ *
+ *     const res = await fetch("api/boards");
+ *     if (!res.ok && (await res.clone().json()).error?.code === PLUGIN_NOT_ANSWERING) ...
+ */
+import type { KitErrorCode } from "./generated/kit.ts";
+/** The plugin is at its runner link's stream cap, so tera opened no new connection to it (503, `Retry-After`). */
+export declare const PLUGIN_BUSY: KitErrorCode;
+/** tera has not yet settled where the plugin runs, so it opened no connection to it (503, `Retry-After`). */
+export declare const PLUGIN_STARTING: KitErrorCode;
+/** The plugin is placed on a runner tera has no live link to (502). */
+export declare const PLUGIN_RUNNER_UNREACHABLE: KitErrorCode;
+/** The plugin is installed and its UI did not answer on its socket — it is down, as during an upgrade (502). */
+export declare const PLUGIN_NOT_ANSWERING: KitErrorCode;
+/** Every code the proxy answers a page's script with when it did not reach the plugin. */
+export declare const PLUGIN_UNREACHED_CODES: readonly KitErrorCode[];

package/dist/unreached.js

@@ -0,0 +1,30 @@
+/**
+ * The plugin was not reached: what tera's UI proxy answers the page's script
+ * when the plugin behind it did not answer.
+ *
+ * A page load is answered a page saying why. Anything else — a `fetch`, an
+ * XHR upload, a feed stream, a write, a WebSocket upgrade — is answered in
+ * the kit's envelope, `{"error": {"code", "message", "retryable"}}`, with one
+ * of these codes, so a page tells a plugin that is down or starting from one
+ * of its own failures and shows the proxy's `message`, a sentence for the
+ * person naming the plugin and why. Every one is retryable, and the two 503s
+ * carry `Retry-After`:
+ *
+ *     const res = await fetch("api/boards");
+ *     if (!res.ok && (await res.clone().json()).error?.code === PLUGIN_NOT_ANSWERING) ...
+ */
+/** The plugin is at its runner link's stream cap, so tera opened no new connection to it (503, `Retry-After`). */
+export const PLUGIN_BUSY = "plugin_busy";
+/** tera has not yet settled where the plugin runs, so it opened no connection to it (503, `Retry-After`). */
+export const PLUGIN_STARTING = "plugin_starting";
+/** The plugin is placed on a runner tera has no live link to (502). */
+export const PLUGIN_RUNNER_UNREACHABLE = "plugin_runner_unreachable";
+/** The plugin is installed and its UI did not answer on its socket — it is down, as during an upgrade (502). */
+export const PLUGIN_NOT_ANSWERING = "plugin_not_answering";
+/** Every code the proxy answers a page's script with when it did not reach the plugin. */
+export const PLUGIN_UNREACHED_CODES = [
+    PLUGIN_BUSY,
+    PLUGIN_STARTING,
+    PLUGIN_RUNNER_UNREACHABLE,
+    PLUGIN_NOT_ANSWERING,
+];

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@kottera/tera-web",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-rc.10",
+  "description": "The browser half of a UI over tera: a framework-free client for the /tera/v1/ routes a plugin's webui kit serves (ADR-162 D4).",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kottera/sdk.git",
+    "directory": "web"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "NOTICE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "node --test --test-reporter=tap \"src/**/*.test.ts\""
+  }
+}