@cplieger/sse 1.0.0 → 1.1.2-dev.1

package/NOTICE

@@ -0,0 +1,3 @@
+sse
+Copyright 2026 cplieger
+https://github.com/cplieger/sse

package/README.md

@@ -64,7 +64,7 @@ The package typechecks under `lib: ["ESNext", "WebWorker"]` as well as under the
 
 ## Full documentation
 
-The Go server API, the hub options, the hello's verdicts, the digest and the presence hook are in the [repository README](https://github.com/cplieger/sse#readme). The shared timing constants both halves pin are in the repository's `timing.json`.
+The Go server API is in the [repository README](https://github.com/cplieger/sse#readme). The hub options and the presence hook are in [Running the hub](https://github.com/cplieger/sse/blob/main/docs/hub.md), and the hello's verdicts and the digest are in [The wire contract](https://github.com/cplieger/sse/blob/main/docs/wire.md). The shared timing constants both halves pin are in the repository's `timing.json`.
 
 ## Disclaimer
 

package/jsr.json

@@ -1,12 +1,23 @@
 {
   "name": "@cplieger/sse",
-  "version": "1.0.0",
+  "version": "1.1.2-dev.1",
   "license": "Apache-2.0",
   "exports": {
     ".": "./src/index.ts"
   },
   "publish": {
-    "include": ["LICENSE", "README.md", "THIRD_PARTY_NOTICES.md", "src/**/*.ts", "jsr.json"],
-    "exclude": ["src/**/*.test.ts", "src/**/*-setup.ts", "src/**/test-helpers/**"]
+    "include": [
+      "LICENSE",
+      "NOTICE",
+      "README.md",
+      "THIRD_PARTY_NOTICES.md",
+      "src/**/*.ts",
+      "jsr.json"
+    ],
+    "exclude": [
+      "src/**/*.test.ts",
+      "src/**/*-setup.ts",
+      "src/**/test-helpers/**"
+    ]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/sse",
-  "version": "1.0.0",
+  "version": "1.1.2-dev.1",
   "description": "Server-Sent Events hub and client that resume from an exact cursor and reconcile after sleep",
   "license": "Apache-2.0",
   "type": "module",
@@ -34,7 +34,9 @@
     "!src/**/test-helpers/**",
     "!src/**/*.golden.json",
     "jsr.json",
-    "THIRD_PARTY_NOTICES.md"
+    "THIRD_PARTY_NOTICES.md",
+    "LICENSE",
+    "NOTICE"
   ],
   "sseFixture": "./ssetest/cmd",
   "browserEngines": [
@@ -47,23 +49,29 @@
     "test": "vitest --run",
     "test:browser": "vitest --run --project browser",
     "lint:eslint": "eslint .",
-    "lint:prettier": "prettier --check ."
+    "lint:prettier": "prettier --check .",
+    "lint:knip": "knip",
+    "lint:fix": "eslint . --fix && prettier --write ."
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
-    "@types/node": "24.13.4",
+    "@stryker-mutator/core": "10.0.0",
+    "@stryker-mutator/typescript-checker": "10.0.0",
+    "@stryker-mutator/vitest-runner": "10.0.0",
+    "@types/node": "26.6.4",
     "@typescript/native": "npm:typescript@7.0.2",
-    "@vitest/browser": "5.0.0",
-    "@vitest/browser-playwright": "5.0.0",
-    "@vitest/coverage-v8": "5.0.0",
-    "eslint": "10.10.0",
-    "eventsource-parser": "4.1.0",
-    "fast-check": "4.9.0",
+    "@vitest/browser": "5.0.3",
+    "@vitest/browser-playwright": "5.0.3",
+    "@vitest/coverage-v8": "5.0.3",
+    "eslint": "10.12.0",
+    "eventsource-parser": "4.1.1",
+    "fast-check": "4.10.2",
+    "knip": "6.39.0",
     "playwright": "1.63.0",
-    "prettier": "3.9.6",
+    "prettier": "3.9.9",
     "typescript": "npm:@typescript/typescript6@6.0.2",
-    "typescript-eslint": "8.70.0",
-    "vitest": "5.0.0"
+    "typescript-eslint": "8.71.0",
+    "vitest": "5.0.3"
   },
   "overrides": {
     "qs": "^6.15.2"

package/src/digest.ts

@@ -10,20 +10,51 @@ export interface Removed extends Subject {
   readonly reason: "gone" | "forbidden";
 }
 
+/**
+ * The answer to one check, always positioned at the epoch and head the server held when it
+ * answered. `must_refetch` means no comparison happened and the application must refetch rather
+ * than apply a diff: the presented epoch was absent or not the server's, its resolver failed, or
+ * the answer did not match the batch that was asked about. `ok` names the subjects whose version
+ * moved and the ones the server no longer answers for; a subject in neither list is unchanged.
+ */
 export type DigestResult =
   | { kind: "must_refetch"; epoch: string; head: string }
   | { kind: "ok"; epoch: string; head: string; changed: State[]; removed: Removed[] };
 
+/**
+ * What one check asks about: the epoch the held versions were minted under, and the versions
+ * themselves. `VersionMap.snapshot()` produces one directly. A null epoch presents none, which the
+ * server answers with must_refetch for any non-empty snapshot, so an unbound map is worth checking
+ * only when it is also empty.
+ */
 export interface DigestSnapshot {
   readonly epoch: string | null;
   readonly held: readonly Held[];
 }
 
+/**
+ * The client of the digest route, and nothing more: it reads no version map and writes to none, so
+ * applying its answer is the caller's step. `check` splits the snapshot into POSTs of at most
+ * `maxSubjects` and stops at the first must_refetch, since a refusal makes every remaining batch
+ * moot. It rejects with DigestStatusError on any status but 200, with a TimeoutError DOMException
+ * when a POST's request phase outlives `timeoutMs`, and with a plain Error when a 200 body is not
+ * a positioned digest answer.
+ */
 export interface DigestClient {
   /** Asks the server which held versions moved; the optional signal cancels every POST. */
   check(snapshot: DigestSnapshot, signal?: AbortSignal): Promise<DigestResult>;
 }
 
+/**
+ * How the client reaches the route. `url` is POSTed with `credentials: "same-origin"`; `fetch`
+ * defaults to globalThis.fetch and is where a consumer merges its own credentials or bearer
+ * header; `headers` is merged first, so it cannot displace the Accept and Content-Type the route
+ * requires. `timeoutMs` defaults to digestTimeoutMs and bounds one POST's request and the wait for
+ * its response headers, not the whole check and not the body read: it is released as soon as the
+ * response object arrives, so the body read is bounded only by the signal passed to `check`, and
+ * by nothing at all when that argument is omitted.
+ * `maxSubjects` defaults to DIGEST_MAX_SUBJECTS, the cap the server enforces at its own default.
+ */
 export interface DigestClientOptions {
   readonly url: string;
   readonly fetch?: typeof fetch;

package/src/fold.ts

@@ -1,6 +1,12 @@
 import type { OnlineSource } from "./online.js";
 import type { VisibilityEvent, VisibilityInput, VisibilitySource } from "./visibility.js";
 
+/**
+ * One attached tab's contribution to the profile: the two readings it forwards. A tab is in the fold
+ * from its attach until it is removed or reports `pagehide`. Its visibility stops counting the moment
+ * it leaves; the profile's network reading is not recomputed on a departure and keeps the last value
+ * reported, by whichever tab.
+ */
 export interface TabState {
   readonly visible: boolean;
   readonly online: boolean;
@@ -8,6 +14,12 @@ export interface TabState {
   readonly pageshowPending: boolean;
 }
 
+/**
+ * One tab's report into the fold, always keyed by `tabId`. An `attach` seeds that tab's two readings,
+ * and `visibility` and `network` update them afterwards. A `visibility` report for a tab the fold does
+ * not know is dropped; a `network` report from one still counts as the profile's latest reading, since
+ * the network is a property of the machine rather than of the tab that noticed.
+ */
 export type FoldInput =
   | {
       readonly type: "attach";
@@ -20,8 +32,17 @@ export type FoldInput =
   /** Detach, port close, expiry: the tab leaves as if by pagehide. */
   | { readonly type: "remove"; readonly tabId: string };
 
+/**
+ * What a fold step emits for the profile's one stream: a transition, never a tab's report. A step that
+ * changes nothing the stream can act on emits nothing — a tab going hidden while another stays visible
+ * is silent — and `pageshow` is emitted at most once per visible period however many tabs are restored.
+ */
 export type FoldOutput = "visible" | "hidden" | "pageshow" | "online" | "offline";
 
+/**
+ * The profile's folded view of its tabs. Every step returns a new value rather than mutating this one,
+ * so a caller may hold an earlier state and compare against it.
+ */
 export interface FoldState {
   readonly tabs: ReadonlyMap<string, TabState>;
   /** The latest network report from any tab, seeded by the host. */
@@ -30,6 +51,11 @@ export interface FoldState {
   readonly pageshown: boolean;
 }
 
+/**
+ * The fold before any tab has attached. `online` is the host's own reading, which stands as the
+ * profile's until a tab reports one, so a host that seeds it wrong holds the stream off the network
+ * until the first tab corrects it.
+ */
 export function createFoldState(online: boolean): FoldState {
   return { tabs: new Map(), online, pageshown: false };
 }
@@ -147,6 +173,12 @@ export interface ProfileVisibilitySource extends VisibilitySource {
   report(tabId: string, ev: VisibilityInput): void;
 }
 
+/**
+ * Creates the visibility reading the worker host gives its stream: the fold over the tabs it has, fed
+ * by attach, detach and report rather than by any platform event. It emits only the profile's own
+ * transitions, so the stream sees one `visible` for a whole set of tabs coming back and one `hidden`
+ * only once none is left showing.
+ */
 export function createProfileVisibilitySource(): ProfileVisibilitySource {
   let state = createFoldState(true);
   const out = listenable<VisibilityEvent>();
@@ -188,6 +220,12 @@ export interface ProfileOnlineSource extends OnlineSource {
   report(tabId: string, online: boolean): void;
 }
 
+/**
+ * Creates the network reading the worker host gives its stream: the last value any tab reported,
+ * starting at `seed`. The tabs are the source because createDOMOnlineSource registers nothing inside a
+ * worker — there is no `window` there to hear `online` and `offline` on — so a host reading the DOM
+ * directly would never be handed a transition to act on.
+ */
 export function createProfileOnlineSource(seed: boolean): ProfileOnlineSource {
   let state = createFoldState(seed);
   const out = listenable<boolean>();

package/src/lifecycle.ts

@@ -2,8 +2,21 @@ import type { ClientState, ConnectFailure } from "./reducer.js";
 import type { Subject } from "./versions.js";
 import type { ResetReason } from "./wire.js";
 
+/**
+ * Why a revalidation was scheduled. The first three are the platform waking the client up; `hello`
+ * is every run the runtime demands for itself — a hello that did not resume, a version map the
+ * hello cleared, a frame the application threw on, and the connect after a run that failed. A
+ * `hello` run never coalesces with a neighbouring one, and neither does anything arriving while
+ * one is in flight.
+ */
 export type RevalidateCause = "visible" | "pageshow" | "online" | "hello";
 
+/**
+ * Why frames held for a run were dropped instead of delivered: the attempt was aborted, the stream
+ * ended under it, the run passed revalidateTimeoutMs, the hold passed its frame or byte bound, or
+ * the run rejected. A held frame never advanced the cursor, so the next connect asks for the
+ * discarded ones again.
+ */
 export type HeldDiscardCause =
   "abort" | "stream_ended" | "hold_timeout" | "hold_overflow" | "revalidate_failed";
 

package/src/online.ts

@@ -1,8 +1,19 @@
+/**
+ * The network reading, injected rather than assumed. A true is only ever a reason to try — no
+ * platform can promise a route — while a false is taken at its word and holds the client off the
+ * network, so a source that guesses false is the expensive mistake. `listen` returns the unsubscribe.
+ */
 export interface OnlineSource {
   online(): boolean;
   listen(cb: (online: boolean) => void): () => void;
 }
 
+/**
+ * One network reading shared by every subscriber, listening to the source only while at least one
+ * subscriber is attached. createWorkerHost does not read the DOM source through this: it folds the
+ * readings its tabs forward, because createDOMOnlineSource registers nothing where there is no
+ * `window` to hear `online` and `offline` on.
+ */
 export interface OnlineManager {
   isOnline(): boolean;
   /** The source is listened to from the first subscriber to the last. */

package/src/parser.ts

@@ -10,6 +10,12 @@ export interface ParsedEvent {
   readonly bytes: number;
 }
 
+/**
+ * What the parser reports. `onEvent` fires once per dispatched frame, which per WHATWG means a
+ * frame carrying no `data` field dispatches nothing at all — its `id` is still remembered as
+ * the sticky last event id. The other three are optional and each fires for one wire feature:
+ * a well-formed `retry:` value, a comment line, and the buffer cap being passed.
+ */
 export interface ParserHandlers {
   readonly onEvent: (event: ParsedEvent) => void;
   readonly onRetry?: (ms: number) => void;
@@ -18,10 +24,20 @@ export interface ParserHandlers {
   readonly onOverflow?: (bytes: number) => void;
 }
 
+/**
+ * The parser's only bound: the encoded bytes one frame may occupy, counted from the end of the
+ * previous frame and including its own terminating blank line. It must be at least
+ * MAX_FRAME_BYTES, or a frame the server is entitled to send would abort every connection.
+ */
 export interface ParserOptions {
   readonly maxBufferBytes: number;
 }
 
+/**
+ * A byte-fed event-stream parser. Feeding is incremental: a chunk may split a line, a CRLF pair
+ * or a multi-byte character, and the parse resumes from the next chunk. Once a frame passes
+ * maxBufferBytes the parser latches off — every further feed is ignored until reset().
+ */
 export interface Parser {
   feed(chunk: Uint8Array): void;
   /** Returns the parser to its construction state; a partial event is discarded. */

package/src/port-protocol.ts

@@ -6,6 +6,12 @@ import type { Subject } from "./versions.js";
 import type { VisibilityInput } from "./visibility.js";
 import type { Cursor } from "./wire.js";
 
+/**
+ * Why a tab is leaving the host. `unload` and `logout` are the application's, through
+ * `TabAttachment.detach`; `respawn` and `fallback` are the tab's own ladder giving up on a worker that
+ * stopped answering. Only `logout` stops the profile's stream — the other three leave it running for
+ * whatever tabs remain.
+ */
 export type DetachCause = "unload" | "respawn" | "fallback" | "logout";
 
 /** RevalidateContext without its signal, which cannot cross a port; the tab supplies its own. */
@@ -19,6 +25,13 @@ export interface PortRevalidateContext {
   readonly removed?: readonly Removed[];
 }
 
+/**
+ * Every message a tab sends the host. `attach` comes first and identifies the tab: until the host has
+ * one, only `ping` is answered and everything else is discarded. Its `hadWorker` says this tab held a
+ * worker link before this attach, which is what earns it a full revalidation where a first attach to a
+ * live stream is given none — the state it holds was built against a stream it can no longer account
+ * for.
+ */
 export type TabToWorker =
   | {
       readonly type: "attach";
@@ -45,6 +58,15 @@ export type TabToWorker =
   | { readonly type: "revalidate_failed"; readonly runId: number; readonly cause: string }
   | { readonly type: "frame_failed"; readonly generation: number; readonly cursor: Cursor | null };
 
+/**
+ * Every message the host sends a tab. Two of them are obligations rather than notifications: a
+ * `heartbeat` must be answered with `heartbeat_ack` or the host expires the port and stops folding this
+ * tab's readings, and a `revalidate_run` must be answered with `revalidate_done` or `revalidate_failed`
+ * carrying the same `runId`, or the host's run stays pending until this port expires, leaves, or the
+ * run's own signal aborts, which the runtime does at `revalidateTimeoutMs` and on `stop()`. A `state`
+ * message precedes the `lifecycle` record of the same transition, so a tab reading its own state inside
+ * that handler reads the new one.
+ */
 export type WorkerToTab =
   | { readonly type: "frame"; readonly frame: Frame; readonly generation: number }
   | { readonly type: "lifecycle"; readonly event: LifecycleEvent }

package/src/reducer.ts

@@ -33,6 +33,13 @@ export type ClientState =
   | { kind: "offline"; generation: number; attempt: number; visible: boolean }
   | { kind: "hidden_closed"; generation: number; attempt: number; online: boolean };
 
+/**
+ * Why a stream ended. `eof`, `error` and the two `reset:` reasons are read off the wire; the rest
+ * are the client's own decisions — silence past the watchdog interval, a frame over the buffer
+ * cap, and the three ways a hold ends without delivering. An attempt still connecting reports one
+ * of these too, and the reducer reads every one of them as a `network` connect failure there. All
+ * of them take one transition and none discards the cursor, so the next attempt resumes from it.
+ */
 export type StreamEnd =
   | "eof"
   | "error"
@@ -44,6 +51,14 @@ export type StreamEnd =
   | "hold_overflow"
   | "revalidate_failed";
 
+/**
+ * Why an attempt never became an open stream: either of the two connect-phase deadlines, a
+ * rejected fetch, a status other than 200, a media type other than `text/event-stream`, or one
+ * of the two hello refusals. Each is reported as a `connect_failed` record, and the attempt then
+ * backs off — or waits in `offline` instead, when the network reading has already gone false.
+ * `wire_unsupported` carries the revision the server announced and emits its own record beside
+ * the shared one.
+ */
 export type ConnectFailure =
   | { kind: "timeout_headers" }
   | { kind: "timeout_hello" }
@@ -58,6 +73,14 @@ interface FromTransport {
   readonly generation: number;
 }
 
+/**
+ * Every input the reducer accepts: the caller's three verbs, one connection attempt's reports, the
+ * four timer expiries, and the platform's visibility and network events. The caller supplies what
+ * the reducer refuses to read for itself — `now` from its clock, `rand` drawn in [0, 1) for the
+ * backoff, and `retryMs`, the reconnection delay in force, which floors the backoff after a stream
+ * that was open ends. A report tagged with a generation other than the current one is ignored,
+ * which is how a late answer from a replaced attempt is dropped rather than acted on.
+ */
 export type ClientEvent =
   | { type: "start"; now: number; visible: boolean; online: boolean }
   | { type: "stop" }
@@ -83,6 +106,12 @@ export type ClientEvent =
   | { type: "pagehide"; now: number }
   | { type: "pageshow"; now: number; rand: number; retryMs: number };
 
+/**
+ * The four timers the reducer arms and disarms by name, never by handle: byte silence, the
+ * hidden-tab close, the backoff delay, and the connected time after which the attempt counter
+ * resets. The runtime owns the handles and dispatches the matching expiry event; arming one that
+ * is already armed replaces it.
+ */
 export type Timer = "watchdog" | "hidden" | "backoff" | "stable";
 
 /**
@@ -98,6 +127,11 @@ export type Effect =
   | { kind: "revalidate"; cause: RevalidateCause }
   | { kind: "emit"; event: LifecycleEvent };
 
+/**
+ * One transition's result: the state to hold from now on, and the effects to execute in the order
+ * given. The reducer performs none of them, so a caller that drops `effects` has a state machine
+ * that transitions and a client that does nothing.
+ */
 export interface Reduction {
   readonly state: ClientState;
   readonly effects: Effect[];

package/src/stream.ts

@@ -20,6 +20,13 @@ import {
 } from "./visibility.js";
 import { type Cursor, type Hello, compareOffset } from "./wire.js";
 
+/**
+ * How one stream is built. Four fields are required — `url`, `versions`, `onFrame` and
+ * `revalidate` — and the rest have defaults that make a plain browser tab work unconfigured: the
+ * timing is filled from DEFAULT_TIMING, both wire bounds are this package's WIRE, and the
+ * visibility and network readings are the DOM sources, taken lazily at start(). A consumer replaces
+ * those two for a worker, a test, or a host folding several tabs into one connection.
+ */
 export interface StreamOptions {
   readonly url: string;
   /** Defaults to globalThis.fetch; the place to merge `credentials: "include"` or a bearer header. */
@@ -42,12 +49,26 @@ export interface StreamOptions {
   readonly revalidate: (ctx: RevalidateContext) => Promise<void>;
 }
 
+/**
+ * One application frame, as `onFrame` receives it: the event name, the data payload exactly as it
+ * arrived, and the frame's position when it carried one. Library frames are never delivered here,
+ * `id` is null for a frame the server published without one, and a frame whose id is not a valid
+ * `epoch:offset` is reported as `bad_cursor` and dropped instead. Delivering a frame advances the
+ * cursor past it whether or not the handler threw: a throw earns a revalidation, never a redelivery.
+ */
 export interface Frame {
   readonly type: string;
   readonly data: string;
   readonly id: Cursor | null;
 }
 
+/**
+ * The context of one reconciliation run. Runs are single-flight, so a body is never entered while
+ * another is in flight, and at most one more run is ever queued behind the current one. Every fetch
+ * the body makes must take `signal`: the runtime aborts it at revalidateTimeoutMs and ends the
+ * connection rather than waiting, and a body that ignores the signal keeps running against state
+ * the runtime has already given up on.
+ */
 export interface RevalidateContext {
   readonly cause: RevalidateCause;
   /** The version map's epoch when the run started. */
@@ -59,6 +80,13 @@ export interface RevalidateContext {
   readonly signal: AbortSignal;
 }
 
+/**
+ * The runtime's handle. Frames and records do not arrive through it — they go to the `onFrame` and
+ * `onLifecycle` of the options the stream was created with — so what is left here is the four verbs
+ * and the two readings. `start()` is ignored unless the stream is stopped, and `cursor()` is the
+ * position the next connect will present as `Last-Event-ID`, or null when it will ask for a fresh
+ * hello instead.
+ */
 export interface Stream {
   start(): void;
   /** For leaving the page: aborts the in-flight revalidate's signal. */

package/src/tab.ts

@@ -35,6 +35,15 @@ export interface TabFallback {
   readonly headers: Record<string, string>;
 }
 
+/**
+ * How this tab attaches. `spawn` is called for every attempt at the worker — the first one, each respawn
+ * after a silent window, the re-spawn on `pageshow` when the page came back with no live port, and each
+ * recovery probe from fallback mode — so it must build a fresh worker each time rather than return a
+ * held one; a throw from it is read as the worker being unavailable. `fallback` is called when the
+ * ladder gives up, and immediately where `SharedWorker` is absent. `revalidate` is optional, and a tab
+ * without one reports every routed run as done, which is correct only when the host's own body did the
+ * reconciliation.
+ */
 export interface AttachOptions {
   /** Constructs the worker with the fixed URL, name and options; called on every spawn. */
   readonly spawn: () => SharedWorkerLike;
@@ -55,6 +64,13 @@ export interface AttachOptions {
   readonly revalidateTimeoutMs?: number;
 }
 
+/**
+ * This tab's handle on the profile's stream. Every verb works the same in both modes, which is the point
+ * of it: `mode()` reports whether they currently reach the worker host over a port or this tab's own
+ * fallback stream, and a consumer needs it for reporting rather than for branching. `state()` is the
+ * host's last broadcast in worker mode, so it reads null until the first one arrives, and the fallback
+ * stream's own state otherwise.
+ */
 export interface TabAttachment {
   /** Leaves the host; `logout` also ends the profile's stream, or this tab's fallback stream. */
   detach(cause?: "unload" | "logout"): void;

package/src/timing.ts

@@ -58,6 +58,11 @@ export interface TimingConfig {
   readonly maxBufferBytes: number;
 }
 
+/**
+ * The value every field a caller leaves unset takes. Each one is pinned, directly or by derivation,
+ * to the repository's `timing.json` — the single source both halves of the protocol read — so a
+ * client default and the server behaviour it assumes cannot drift apart.
+ */
 export const DEFAULT_TIMING: TimingConfig = {
   connectTimeoutMs: 15_000,
   helloTimeoutMs: 10_000,
@@ -77,7 +82,12 @@ export const DEFAULT_TIMING: TimingConfig = {
   maxBufferBytes: MAX_FRAME_BYTES,
 };
 
-// Silence watchdog derivation follows Yaffle/EventSource: max(3 beats, 15 s), 45 s at the default keepalive.
+/**
+ * Silence watchdog derivation follows Yaffle/EventSource: max(3 beats, 15 s), 45 s at the
+ * default keepalive. `keepaliveMs` is the interval the hello reported, so a server running a
+ * shorter one shortens the watchdog until the floor takes over; the value is re-derived on
+ * every re-arm rather than held.
+ */
 export function watchdogMs(keepaliveMs: number, cfg: TimingConfig = DEFAULT_TIMING): number {
   return Math.max(cfg.watchdogBeats * keepaliveMs, cfg.watchdogFloorMs);
 }

package/src/transport.ts

@@ -38,6 +38,13 @@ export interface TransportCallbacks {
   readonly onEnd: (generation: number, reason: StreamEnd) => void;
 }
 
+/**
+ * One attempt's inputs. `cursor` is presented as `Last-Event-ID` and `maxWire` as `SSE-Wire`, both
+ * merged under `headers`, so a caller's header of the same name wins over the transport's own — the
+ * seam a consumer uses to override them, and the one it must not trip over by accident. `generation`
+ * tags every callback with it, which is what lets the runtime tell a live report from one belonging
+ * to an attempt it has already replaced.
+ */
 export interface ConnectOptions {
   readonly url: string;
   readonly fetch: typeof fetch;
@@ -50,6 +57,11 @@ export interface ConnectOptions {
   readonly callbacks: TransportCallbacks;
 }
 
+/**
+ * A connection attempt in progress. `abort` is the whole surface: the attempt reports its outcome
+ * through the callbacks it was given, and aborting it silences those callbacks for good, the fetch
+ * and the reader it is still waiting on included. A second abort does nothing.
+ */
 export interface Connection {
   /** Ends the attempt; nothing is dispatched afterwards. */
   abort(reason: string): void;

package/src/versions.ts

@@ -29,6 +29,12 @@ export interface VersionMap {
   snapshot(): { epoch: string | null; held: Held[] };
 }
 
+/**
+ * The map's one hook. A stamp from a foreign epoch is not an error the application has to handle:
+ * observe() ignores it and answers false, and this is how the application learns it happened.
+ * staleListener reports the same events, which is the path the runtime uses for its `stale_stamp`
+ * records, so a consumer that wants both gets both.
+ */
 export interface VersionMapOptions {
   /** Called for every stamp ignored because its epoch differs from the bound epoch. */
   readonly onStale?: (subject: Subject, epoch: string) => void;

package/src/visibility.ts

@@ -1,13 +1,29 @@
+/**
+ * The six page events a source reports. Two of them never reach the reducer: adaptVisibility folds
+ * `freeze` onto `hidden` and `resume` onto `visible`, the latter only while the source still reads
+ * visible, because a resumed page may have been resumed in the background.
+ */
 export type VisibilityEvent = "visible" | "hidden" | "pagehide" | "pageshow" | "freeze" | "resume";
 
 /** The four visibility inputs the reducer accepts; the adapter folds freeze and resume into them. */
 export type VisibilityInput = "visible" | "hidden" | "pagehide" | "pageshow";
 
+/**
+ * The page-visibility reading, injected rather than assumed: `visible()` is asked on demand and
+ * `listen` returns the unsubscribe for the stream of events. createDOMVisibilitySource is the
+ * implementation over `document` and `window`; the worker host passes the fold over its tabs
+ * instead, and a test passes whatever it wants to drive.
+ */
 export interface VisibilitySource {
   visible(): boolean;
   listen(cb: (ev: VisibilityEvent) => void): () => void;
 }
 
+/**
+ * One visibility reading shared by every subscriber. The source is listened to only while at least
+ * one subscriber is attached, so a manager nobody uses registers no listener, and a pin set through
+ * setVisible replaces the source's answer for readers and emitters alike.
+ */
 export interface VisibilityManager {
   isVisible(): boolean;
   /** The source is listened to from the first subscriber to the last. */

package/src/wire.ts

@@ -27,10 +27,19 @@ export interface Hello {
   readonly keepalive_event: string;
 }
 
-/** Why a hello was refused; both reasons take the ordinary backoff ladder. */
+/**
+ * Why a hello was refused. Both reasons end the attempt in its connect phase, so both take the
+ * jitter backoff ladder — or wait in `offline` instead, when the network reading has already gone
+ * false — rather than the server's `retry:` delay, which a refused attempt never reaches.
+ */
 export type HelloRefusal =
   { kind: "bad_hello" } | { kind: "wire_unsupported"; wire: number | null };
 
+/**
+ * validateHello's answer: the accepted hello, or the reason the frame was refused. A refusal
+ * ends the attempt before it counts as open and leaves the client's cursor untouched, so the
+ * next connect presents the same one.
+ */
 export type HelloResult = { ok: true; hello: Hello } | { ok: false; reason: HelloRefusal };
 
 const EPOCH_RE = /^[0-9a-f]{16}$/;

package/src/worker.ts

@@ -34,6 +34,13 @@ export interface TabSet {
   size(): number;
 }
 
+/**
+ * The host's options: a stream's, minus the three it supplies itself — the visibility and network
+ * readings, which it folds from its tabs, and `onFrame`, which it spends fanning frames to the ports.
+ * `revalidate` is widened to receive the attached TabSet beside the context, so the application, not
+ * this package, decides whether the reconciliation body runs in the worker or in the tabs. Everything
+ * else is a stream's, `versions` included: the profile has one map, and it lives here.
+ */
 export interface WorkerHostOptions extends Omit<
   StreamOptions,
   "visibility" | "online" | "onFrame" | "onLifecycle" | "revalidate"
@@ -46,6 +53,12 @@ export interface WorkerHostOptions extends Omit<
   readonly heartbeatMs?: number;
 }
 
+/**
+ * The profile's stream owner: one stream, one cursor and one version map behind however many tabs.
+ * The stream starts when the first tab attaches, and it is stopped by `close()`, by a `logout` detach
+ * or by a 401 — not by the last port going away, since the browser keeps a SharedWorker alive for its
+ * owner documents and a tab that navigates is expected back.
+ */
 export interface WorkerHost {
   /** Called from the SharedWorker's onconnect with each new port. */
   attach(port: MessagePort): void;