@ekrooh/bare 0.4.0 → 0.6.0

package/dist/static-file-server-COxd-PFR.d.mts

@@ -0,0 +1,120 @@
+import { HTTPIncomingMessage, HTTPServerResponse } from "bare-http1";
+import "bare-tcp";
+/** The protocol socket as the routing layer sees it. */
+type WebSocketLike = {
+  on(event: 'data', listener: (chunk: unknown) => void): unknown;
+  on(event: 'close', listener: () => void): unknown;
+  on(event: 'drain', listener: () => void): unknown;
+  on(event: 'error', listener: (err: Error) => void): unknown;
+  write(data: Uint8Array): boolean;
+  destroy(): void;
+  /** Stops/restarts `data` events (inbound backpressure). */
+  pause?(): void;
+  resume?(): void;
+};
+/** Minimal shape of the HTTP request object handed to connection handlers. */
+type LoopbackRequest = {
+  url?: string;
+  method?: string;
+  headers: Record<string, string | string[] | number | undefined>;
+};
+type LoopbackConnectionHandler = (socket: WebSocketLike, request: LoopbackRequest) => void;
+/** Accumulates an HTTP request body into a UTF-8 string. Node http emits
+ * Buffers, bare-http1 emits Uint8Arrays, and a setEncoding'd stream emits
+ * strings — `String(uint8array)` would join bytes with commas, so decode
+ * explicitly (the `/login` token body must match byte-for-byte). */
+declare function collectRequestBody(req: HTTPIncomingMessage, maxBytes?: number): Promise<string>;
+/** Handler for a registered HTTP route on the loopback server. */
+type LoopbackRouteHandler = (req: HTTPIncomingMessage, res: HTTPServerResponse) => void;
+interface LoopbackServerOptions {
+  /** Bind address. Defaults to `127.0.0.1`. A non-loopback address throws
+   * unless `auth` is on. */
+  host?: string;
+  /** Port to bind; `0` picks an ephemeral port (on-device). */
+  port?: number;
+  /** Require the per-session token/cookie on every gated request and WS
+   * upgrade. Defaults to on; only the dev backend turns it off. The origin
+   * check applies either way. */
+  auth?: boolean;
+  /** Fixed session token (tests); otherwise a random 32-byte token. */
+  token?: string;
+  /** Extra page origins allowed to call the server, e.g. the Vite dev server
+   * (`http://localhost:5173`). The bound origin and its loopback aliases
+   * (`127.0.0.1`, `localhost`, `[::1]` on the bound port) are always allowed. */
+  allowedOrigins?: readonly string[];
+  /** Idle timeout (ms) after which an authenticated WebSocket connection is
+   * dropped. Defaults to 60s. */
+  wsIdleTimeoutMs?: number;
+  /** Dead-peer timeout for the protocol socket, in ms. The socket sends a
+   * protocol-level ping at half this interval and is destroyed when nothing (a
+   * pong included) arrives within it, so a suspended or reloaded WebView frees
+   * the slot in seconds. Browsers answer pings themselves, so this needs no
+   * application message. Defaults to 10s. */
+  wsDeadPeerTimeoutMs?: number;
+  /** Minimum gap, in ms, between an accepted protocol socket and the next one
+   * that may replace it; an upgrade that arrives sooner is held until then.
+   * Bounds eviction churn if two live clients compete. Defaults to 1000. */
+  wsReplaceMinIntervalMs?: number;
+  /** Most bytes queued behind a protocol socket whose reader has stopped reading
+   * before server pushes are dropped, newest first. Responses are queued past
+   * this (to 8x) and then the socket is closed rather than lose one. Defaults to
+   * 2 MiB. */
+  wsMaxQueuedBytes?: number;
+}
+interface LoopbackServer {
+  /** Resolves to the server origin (`http://127.0.0.1:<port>`), binding on
+   * first use. */
+  origin(): Promise<string>;
+  /** Resolves to a URL for `path` (`<origin><path>`). The per-session cookie
+   * authorizes media loads; no token is embedded in the URL. */
+  url(path: string): Promise<string>;
+  /** The per-session token. The host reads it from `credentials()` for its own
+   * `X-Bare-Token` calls and never injects it into the page. */
+  token(): string;
+  /** Resolves to the bound origin, port, token and the one-time bootstrap
+   * nonce (empty once spent). The host injects `bootstrap` into the page (not
+   * the token); the page exchanges it once via `POST /login` for the HttpOnly
+   * session cookie. */
+  credentials(): Promise<{
+    origin: string;
+    port: number;
+    token: string;
+    bootstrap: string;
+  }>;
+  /** Serves `filePath` at `http://<origin><path>` (exact match). */
+  mount(path: string, filePath: string): void;
+  unmount(path: string): void;
+  /** Serves every file under `dirPath` below `prefix` (longest-prefix match).
+   * The SPA fallback to `dirPath/index.html` for unknown navigation GETs
+   * applies only to `public` mounts (the bootstrap web app). Pass
+   * `{ public: true }` to mark a mount as world-readable bootstrap content
+   * served before auth; a non-public directory mount gates every request
+   * behind the session. A request never resolves outside `dirPath`, symlinks
+   * included. */
+  mountDir(prefix: string, dirPath: string, opts?: {
+    public?: boolean;
+  }): void;
+  /** Registers a handler for authenticated, handshaken WebSocket connections
+   * (the protocol socket). */
+  onConnection(handler: LoopbackConnectionHandler): void;
+  /** Registers an HTTP route. `handler` runs before mount resolution, after
+   * the auth gate (device mode requires the session cookie/token). The route
+   * body is read with `collectRequestBody`. */
+  registerRoute(method: string, path: string, handler: LoopbackRouteHandler): void;
+  /** Writes a raw frame to the connected protocol socket (if any) — the
+   * server-initiated push seam (e.g. a `photos.changed` dispatch). */
+  push(frame: Uint8Array): boolean;
+  /** Stops accepting connections and closes the server. */
+  close(cb?: (err?: Error | null) => void): void;
+}
+/**
+ * The single loopback HTTP+WS server for the worklet. One origin serves the
+ * web app (`/`), the media files mounted by plugins, and the framed-protocol
+ * WebSocket socket the page connects to. On device it binds `127.0.0.1` on an
+ * ephemeral port. Admission (origin rule, session credential, bootstrap login)
+ * is decided by the loopback gate (`loopback-gate.ts`); the protocol socket's
+ * lifecycle by the protocol socket slot (`protocol-socket.ts`). All responses
+ * send `Referrer-Policy: no-referrer`.
+ */
+declare function createLoopbackServer(options?: LoopbackServerOptions): LoopbackServer;
+export { createLoopbackServer as i, LoopbackServer as n, collectRequestBody as r, LoopbackRouteHandler as t };

package/dist/store-DTg1jN5E.mjs

@@ -0,0 +1,49 @@
+// core/logs/store.ts
+/** Bounded FIFO log buffer. Newest entries are retained; the oldest are
+* dropped once `capacity` is exceeded. `seq` is a monotonic counter assigned
+* on append and shared across every source, so read-back stays ordered. */
+function createLogRingBuffer(capacity) {
+	if (!Number.isInteger(capacity) || capacity < 1) throw new RangeError(`log ring capacity must be a positive integer (got ${capacity})`);
+	const ring = Array.from({ length: capacity });
+	let start = 0;
+	let size = 0;
+	let seq = 0;
+	/** Entries oldest-first. */
+	function ordered() {
+		const out = [];
+		for (let i = 0; i < size; i++) out.push(ring[(start + i) % capacity]);
+		return out;
+	}
+	return {
+		get capacity() {
+			return capacity;
+		},
+		append(entry) {
+			const record = {
+				...entry,
+				seq: seq++
+			};
+			if (size < capacity) {
+				ring[(start + size) % capacity] = record;
+				size++;
+			} else {
+				ring[start] = record;
+				start = (start + 1) % capacity;
+			}
+		},
+		view(options = {}) {
+			const { tail, level, source } = options;
+			const filtered = ordered().filter((e) => (level === void 0 || e.level === level) && (source === void 0 || e.source === source));
+			const count = tail === void 0 ? filtered.length : Math.min(tail, filtered.length);
+			return filtered.slice(filtered.length - count);
+		},
+		clear() {
+			const cleared = size;
+			ring.fill(void 0);
+			start = 0;
+			size = 0;
+			return cleared;
+		}
+	};
+}
+export { createLogRingBuffer as t };

package/dist/transports.d.mts

@@ -1,13 +1,14 @@
-import { V as MessageHeader, X as WireMessage, tt as MessageTypeValue } from "./index-DjulYFJL.mjs";
-//#region web/websocket-client.d.ts
+import { K as MessageHeader, ot as MessageTypeValue, tt as WireMessage } from "./index-BkwUzwVt.mjs";
 declare global {
   interface Window {
     /** Per-session bridge state injected by the embedding shell on-device.
-     * `token` is exchanged for a session cookie via `POST /login`, which then
-     * rides every same-origin request — including the WebSocket upgrade.
-     * Browser dev has none (the dev backend runs without auth). */
+     * `bootstrap` is a one-time nonce the page exchanges for a session cookie
+     * via `POST /login` (single-use — the raw session token is never exposed
+     * to page JS). The cookie then rides every same-origin request —
+     * including the WebSocket upgrade. Browser dev has none (the dev backend
+     * runs without auth). */
     __ekrooh?: {
-      token?: string;
+      bootstrap?: string;
       [key: string]: unknown;
     };
     /** Set by the embedding shell on-device. */
@@ -18,21 +19,21 @@ interface CreateWebSocketTransportOptions {
   /** WebSocket URL. Defaults to the page's same-origin (`ws://location.host`).
    * Browser dev passes `VITE_BARE_WS_URL` explicitly. */
   url?: string;
-  /** Whether to bootstrap the session cookie via `POST /login` when a token
-   * is present. Defaults to `true`. */
+  /** Whether to bootstrap the session cookie via `POST /login` when a
+   * bootstrap nonce is present. Defaults to `true`. */
   login?: boolean;
   /** Reconnect attempts after an unexpected close (boot-window). Default 5. */
   maxRetries?: number;
   /** Initial reconnect backoff in ms, doubling to a 2s cap. Default 250. */
   backoffMs?: number;
+  /** How long to wait for `/login` before treating it as failed. Default
+   * 2000ms. Exposed so tests can exercise the timeout without waiting. */
+  loginTimeoutMs?: number;
 }
 interface MessageTransport {
   send(type: MessageTypeValue, header: MessageHeader, payload?: Uint8Array | ArrayBuffer | string | null): void;
   subscribe(handler: (message: WireMessage) => void): () => void;
 }
-declare function createWebSocketTransport(urlOrOptions?: string | CreateWebSocketTransportOptions): MessageTransport;
-//#endregion
-//#region web/transports/mock.d.ts
-declare function createMockTransport(): MessageTransport;
-//#endregion
-export { type MessageTransport, createMockTransport, createWebSocketTransport };
+export declare function createWebSocketTransport(urlOrOptions?: string | CreateWebSocketTransportOptions): MessageTransport;
+export declare function createMockTransport(): MessageTransport;
+export type { MessageTransport };

package/dist/transports.mjs

@@ -1,6 +1,7 @@
-import { ErrorCode, MessageProtocol, MessageType } from "./index.mjs";
+import { g as ErrorCode, o as MessageProtocol, y as MessageType } from "./messages-CevD8qkV.mjs";
+import { t as createLogRingBuffer } from "./store-DTg1jN5E.mjs";
 import { Actor, RealClock, event, state } from "@mantaq/core";
-//#region web/connection-machine.ts
+// web/connection-machine.ts
 const idleState = state("idle")();
 const openingState = state("opening")();
 const connectedState = state("connected")();
@@ -10,31 +11,24 @@ const loginOk = event("LOGIN_OK")();
 const loginFail = event("LOGIN_FAIL")();
 const socketOpen = event("SOCKET_OPEN")();
 const socketClose = event("SOCKET_CLOSE")();
+const wake = event("WAKE")();
 const retryTimer = event("RETRY_TIMER")();
-/** Append the session token to the URL as a `?token=...` query param, keeping
-* any query the URL already carries. */
-function withToken(url, token) {
-	const parsed = new URL(url);
-	parsed.searchParams.set("token", token);
-	return parsed.toString();
-}
 function createConnectionMachine(options) {
 	const context = {
 		url: options.url,
-		baseUrl: options.url,
-		token: options.token,
 		maxRetries: options.maxRetries,
 		initialBackoffMs: options.initialBackoffMs,
 		maxBackoffMs: options.maxBackoffMs,
 		retries: 0,
-		tokenTried: false
+		everConnected: false
 	};
 	const actor = new Actor({
 		inputs: [
 			loginOk,
 			loginFail,
 			socketOpen,
-			socketClose
+			socketClose,
+			wake
 		],
 		internal: [retryTimer],
 		outputs: [],
@@ -51,42 +45,32 @@ function createConnectionMachine(options) {
 		setup: (m) => {
 			m.effect(backoffState, ({ signal, context, clock, emit }) => {
 				const s = context.get();
-				const delay = Math.min(s.initialBackoffMs * 2 ** (s.retries - 1), s.maxBackoffMs);
+				const capped = Math.min(s.initialBackoffMs * 2 ** (s.retries - 1), s.maxBackoffMs);
+				const delay = Math.floor(capped * Math.max(0, Math.min(1, (options.random ?? Math.random)())));
 				clock.setTimeout(delay, () => {
-					if (signal.aborted) return;
+					if (signal.aborted) {
+						try {
+							console.debug(`[ws-machine] backoff aborted by signal; dropping pending retry (retries=${s.retries})`);
+						} catch {}
+						return;
+					}
 					emit({ type: "RETRY_TIMER" });
 				});
 			});
 			m.on(idleState, loginOk, () => ({ state: openingState }));
-			m.on(idleState, loginFail, (_event, opts) => {
-				const s = opts.context.get();
-				const tokenUrl = s.token && s.token.length > 0 ? withToken(s.baseUrl, s.token) : s.url;
-				opts.context.set({
-					...s,
-					url: tokenUrl,
-					tokenTried: true
-				});
-				return { state: openingState };
-			});
+			m.on(idleState, loginFail, () => ({ state: gaveUpState }));
 			m.on(openingState, socketOpen, (_event, opts) => {
 				const s = opts.context.get();
 				opts.context.set({
 					...s,
-					retries: 0
+					retries: 0,
+					everConnected: true
 				});
 				return { state: connectedState };
 			});
 			m.on(openingState, socketClose, (_event, opts) => {
 				const s = opts.context.get();
-				if (!s.tokenTried && typeof s.token === "string" && s.token.length > 0) {
-					opts.context.set({
-						...s,
-						url: withToken(s.baseUrl, s.token),
-						tokenTried: true
-					});
-					return { state: openingState };
-				}
-				if (s.retries >= s.maxRetries) return { state: gaveUpState };
+				if (!s.everConnected && s.retries >= s.maxRetries) return { state: gaveUpState };
 				opts.context.set({
 					...s,
 					retries: s.retries + 1
@@ -95,7 +79,6 @@ function createConnectionMachine(options) {
 			});
 			m.on(connectedState, socketClose, (_event, opts) => {
 				const s = opts.context.get();
-				if (s.retries >= s.maxRetries) return { state: gaveUpState };
 				opts.context.set({
 					...s,
 					retries: s.retries + 1
@@ -103,6 +86,7 @@ function createConnectionMachine(options) {
 				return { state: backoffState };
 			});
 			m.on(backoffState, retryTimer, () => ({ state: openingState }));
+			m.on(backoffState, wake, () => ({ state: openingState }));
 			m.on(backoffState, socketClose, () => ({}));
 		}
 	});
@@ -112,23 +96,27 @@ function createConnectionMachine(options) {
 		state: () => name(actor.snapshot()),
 		isConnected: () => name(actor.snapshot()) === "connected",
 		isGaveUp: () => name(actor.snapshot()) === "gaveUp",
+		isDegraded: () => actor.context.everConnected && actor.context.retries > actor.context.maxRetries,
 		sendLoginOk: () => actor.send(loginOk.create()),
 		sendLoginFail: () => actor.send(loginFail.create()),
 		sendOpen: () => actor.send(socketOpen.create()),
 		sendClose: () => actor.send(socketClose.create()),
+		sendWake: () => actor.send(wake.create()),
 		onChange(fn) {
 			return actor.on("change", (snapshot) => fn(name(snapshot)));
 		}
 	};
 }
-//#endregion
-//#region web/websocket-client.ts
+// web/websocket-client.ts
 const protocol = new MessageProtocol();
 const WS_DISCONNECTED_MESSAGE = "WebSocket disconnected before request could be sent";
 const DEFAULT_RETRIES = 5;
 const DEFAULT_BACKOFF_MS = 250;
 const MAX_BACKOFF_MS = 2e3;
 const LOGIN_TIMEOUT_MS = 2e3;
+/** Wait before the single retry after a 409 (`bootstrap` nonce already
+* spent): long enough for the sibling document's `Set-Cookie` to land. */
+const SPENT_NONCE_RETRY_MS = 250;
 /** Same-origin default: on-device the page is served by the loopback server,
 * so `ws://<location.host>` is the protocol socket with no mixed content and
 * no custom scheme. */
@@ -137,30 +125,66 @@ function defaultWsUrl() {
 	return "ws://localhost:8080";
 }
 /**
-* `websocket.send` needs a `BufferSource` backed by a plain `ArrayBuffer`;
-* the codec may produce a view into a pooled Buffer, so slice a standalone
-* copy of just the frame.
+* `websocket.send` sends exactly the bytes a typed-array view covers (its
+* offset and length), so the frame goes out as is. This was a `slice()` copy of
+* the whole frame, kept for a pooled-`Buffer` view that the browser never
+* produces.
 */
-function toArrayBuffer(bytes) {
-	return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+function toSendable(bytes) {
+	return bytes;
+}
+/** Per-line character cap for the folded log tail. */
+const LOG_TAIL_LINE_CHARS = 200;
+/** How long to wait for the log-tail fetch before giving up on enrichment. */
+const LOG_TAIL_TIMEOUT_MS = 2e3;
+/**
+* Fetches the loopback server's recent `[loopback]` rejection lines over HTTP.
+* This works precisely because the failure class is upgrade-only: the page
+* itself loads from the same server, so the auth-gated `GET /logs` route still
+* answers when every WebSocket handshake dies. Returns null when nothing can
+* be learned (no fetch available, network error, timeout).
+*/
+async function serverRejectionTail(wsUrl) {
+	if (typeof fetch !== "function") return null;
+	const httpBase = wsUrl.startsWith("wss://") ? `https://${wsUrl.slice(6)}` : wsUrl.startsWith("ws://") ? `http://${wsUrl.slice(5)}` : wsUrl;
+	try {
+		const response = await Promise.race([fetch(`${httpBase}/logs?tail=50&format=text`), new Promise((resolve) => setTimeout(() => resolve(null), LOG_TAIL_TIMEOUT_MS))]);
+		if (response === null) return null;
+		if (!response.ok) return `server log tail unavailable (HTTP ${response.status})`;
+		const lines = (await response.text()).split("\n").filter((line) => line.includes("[loopback]")).slice(-3).map((line) => line.slice(0, LOG_TAIL_LINE_CHARS));
+		return lines.length > 0 ? lines.join(" | ") : "no [loopback] rejection lines in server log tail";
+	} catch {
+		return null;
+	}
 }
 function createWebSocketTransport(urlOrOptions = {}) {
 	const options = typeof urlOrOptions === "string" ? { url: urlOrOptions } : urlOrOptions;
 	const url = options.url ?? defaultWsUrl();
 	const maxRetries = options.maxRetries ?? DEFAULT_RETRIES;
 	const initialBackoff = options.backoffMs ?? DEFAULT_BACKOFF_MS;
-	const token = typeof window !== "undefined" ? window.__ekrooh?.token : void 0;
-	const shouldLogin = options.login !== false && typeof token === "string" && token.length > 0;
+	const loginTimeoutMs = options.loginTimeoutMs ?? LOGIN_TIMEOUT_MS;
+	const credential = (typeof window !== "undefined" ? window.__ekrooh : void 0)?.bootstrap;
+	const shouldLogin = options.login !== false && typeof credential === "string" && credential.length > 0;
 	const listeners = /* @__PURE__ */ new Set();
 	const queued = [];
 	let socket = null;
+	/** Human-readable reason when the give-up was caused by the `/login`
+	* exchange. The surfaced transport error is the only telemetry CI gets
+	* from an on-device WebView, so it must say which path fired instead of
+	* collapsing login rejection, login timeout and retry exhaustion into a
+	* single string. */
+	let loginFailureDetail = null;
+	/** Error text for requests lost to a terminal give-up. */
+	function gaveUpMessage() {
+		return loginFailureDetail === null ? `${WS_DISCONNECTED_MESSAGE} (socket never opened after ${maxRetries} retries)` : `${WS_DISCONNECTED_MESSAGE} (${loginFailureDetail})`;
+	}
 	const machine = createConnectionMachine({
 		url,
-		token: typeof token === "string" ? token : void 0,
 		maxRetries,
 		initialBackoffMs: initialBackoff,
 		maxBackoffMs: MAX_BACKOFF_MS
 	});
+	const reconnectingMessage = `${WS_DISCONNECTED_MESSAGE} (reconnecting)`;
 	const emitTransportError = (header, message) => {
 		if (header.type !== "INVOKE_REQUEST") return;
 		for (const listener of listeners) listener({
@@ -183,20 +207,28 @@ function createWebSocketTransport(urlOrOptions = {}) {
 		queued.length = 0;
 	};
 	const flushQueued = () => {
-		for (const queuedMessage of queued) socket?.send(toArrayBuffer(queuedMessage.bytes));
+		for (const queuedMessage of queued) socket?.send(toSendable(queuedMessage.bytes));
 		queued.length = 0;
 	};
 	/** Opens a WebSocket for the machine's current URL and wires it to the
 	* machine's lifecycle events. */
 	function openSocket() {
-		socket = new WebSocket(machine.url());
-		socket.binaryType = "arraybuffer";
-		socket.onopen = () => {
+		const current = new WebSocket(machine.url());
+		socket = current;
+		current.binaryType = "arraybuffer";
+		current.onopen = () => {
+			if (socket !== current) return;
 			machine.sendOpen();
 			flushQueued();
 		};
-		socket.onmessage = (event) => {
-			if ((event.data?.byteLength ?? 0) === 0) return;
+		current.onmessage = (event) => {
+			if (socket !== current) return;
+			if ((event.data?.byteLength ?? 0) === 0) {
+				try {
+					console.debug("[ws] received empty frame; ignoring");
+				} catch {}
+				return;
+			}
 			try {
 				const message = protocol.decode(event.data);
 				for (const listener of listeners) listener(message);
@@ -204,41 +236,89 @@ function createWebSocketTransport(urlOrOptions = {}) {
 				console.error("Failed to parse WS message:", err);
 			}
 		};
-		socket.onclose = () => {
+		current.onclose = () => {
+			if (socket !== current) return;
 			machine.sendClose();
 		};
-		socket.onerror = () => {};
+		current.onerror = () => {};
 	}
 	machine.onChange((state) => {
 		if (state === "opening") openSocket();
-		else if (state === "gaveUp") failQueuedMessages(WS_DISCONNECTED_MESSAGE);
+		else if (state === "gaveUp") failWithServerDetail();
+		else if (state === "backoff" && machine.isDegraded()) failQueuedMessages(reconnectingMessage);
+	});
+	/** The app returned to the foreground. A suspended page may hold a socket
+	* the browser already closed without firing `onclose`; treat it as lost, and
+	* retry now instead of waiting out the backoff. */
+	function onForeground() {
+		if (machine.isConnected() && socket && socket.readyState !== WebSocket.OPEN) machine.sendClose();
+		machine.sendWake();
+	}
+	if (typeof document !== "undefined" && document.addEventListener) document.addEventListener("visibilitychange", () => {
+		if (document.visibilityState === "visible") onForeground();
 	});
+	/** Terminal give-up: when we have no better name for the failure, fold the
+	* server's own view (its `[loopback]` upgrade rejections) into the surfaced
+	* error. Async by one localhost round-trip — queued requests are already
+	* terminally lost, so a short delay changes nothing semantically. */
+	async function failWithServerDetail() {
+		let message = gaveUpMessage();
+		if (loginFailureDetail === null) {
+			const tail = await serverRejectionTail(url);
+			if (tail !== null) message = `${message}; server: ${tail}`;
+		}
+		failQueuedMessages(message);
+	}
+	/** One `/login` attempt, classified for the bootstrap race. `spent` means
+	* the server recognized our nonce as already consumed by a sibling
+	* document whose session cookie is on its way — worth exactly one retry. */
+	function postLogin() {
+		const loginTimeout = new Promise((resolve) => {
+			setTimeout(() => resolve("timeout"), loginTimeoutMs);
+		});
+		const attempt = fetch("/login", {
+			method: "POST",
+			body: credential
+		}).then((response) => {
+			if (response.ok) return "ok";
+			return response.status === 409 ? "spent" : "rejected";
+		});
+		return Promise.race([attempt, loginTimeout]);
+	}
 	async function bootstrap() {
-		if (shouldLogin) {
-			const loginTimeout = new Promise((resolve) => {
-				setTimeout(() => resolve("timeout"), LOGIN_TIMEOUT_MS);
-			});
-			try {
-				if (await Promise.race([fetch("/login", {
-					method: "POST",
-					body: token
-				}).then((response) => response.ok ? "ok" : "rejected"), loginTimeout]) === "ok") machine.sendLoginOk();
-				else machine.sendLoginFail();
-			} catch {
+		if (shouldLogin) try {
+			let outcome = await postLogin();
+			if (outcome === "spent") {
+				await new Promise((resolve) => {
+					setTimeout(resolve, SPENT_NONCE_RETRY_MS);
+				});
+				outcome = await postLogin();
+			}
+			if (outcome === "ok") machine.sendLoginOk();
+			else {
+				loginFailureDetail = outcome === "timeout" ? `session login timed out after ${loginTimeoutMs}ms` : "session login rejected";
 				machine.sendLoginFail();
 			}
-		} else machine.sendLoginOk();
+		} catch {
+			loginFailureDetail = "session login request failed";
+			machine.sendLoginFail();
+		}
+		else machine.sendLoginOk();
 	}
 	bootstrap();
 	return {
 		send(type, header, payload) {
 			const encoded = protocol.encode(type, header, payload);
 			if (machine.isConnected() && socket && socket.readyState === WebSocket.OPEN) {
-				socket.send(toArrayBuffer(encoded));
+				socket.send(toSendable(encoded));
 				return;
 			}
 			if (machine.isGaveUp()) {
-				emitTransportError(header, WS_DISCONNECTED_MESSAGE);
+				emitTransportError(header, gaveUpMessage());
+				return;
+			}
+			if (machine.state() === "backoff" && machine.isDegraded()) {
+				emitTransportError(header, reconnectingMessage);
 				return;
 			}
 			queued.push({
@@ -254,8 +334,22 @@ function createWebSocketTransport(urlOrOptions = {}) {
 		}
 	};
 }
-//#endregion
-//#region web/transports/mock-handlers.ts
+// web/transports/mock-handlers.ts
+function createLogsInvokeHandlers(store = createLogRingBuffer(500)) {
+	return {
+		"logs.view": (args) => {
+			const tail = args?.tail === void 0 ? void 0 : Number(args.tail);
+			const level = args?.level === "debug" || args?.level === "info" || args?.level === "warn" || args?.level === "error" ? args.level : void 0;
+			const source = args?.source === "backend" || args?.source === "web" ? args.source : void 0;
+			return { entries: store.view({
+				tail: tail !== void 0 && Number.isFinite(tail) ? tail : void 0,
+				level,
+				source
+			}) };
+		},
+		"logs.clear": () => ({ cleared: store.clear() })
+	};
+}
 function createHealthInvokeHandlers() {
 	return {
 		"health.ping": (args) => ({
@@ -275,12 +369,12 @@ function createHealthInvokeHandlers() {
 		})
 	};
 }
-//#endregion
-//#region web/transports/mock.ts
+// web/transports/mock.ts
 const MOCK_MEDIA_DATA_URI = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAAbUlEQVR4nO3O7UkCABiAQcd5hjXSyCKLPrCiklRswHOM/rw3wS0s4yquYxXruInb2MRd3MdDbOMxnuI5XuI13mIX7/ERn/EV3/ET+/iNQxzjFOf4y2ICE5jABCYwgQlMYAITmMAEJjCBCfx34ALvwBam5OydHgAAAABJRU5ErkJggg==";
 const permissionOf = (args) => typeof args?.permission === "string" ? args.permission : "storage";
 const mockInvokeHandlers = {
 	...createHealthInvokeHandlers(),
+	...createLogsInvokeHandlers(createLogRingBuffer(500)),
 	"discovery.list": () => ({
 		schemaVersion: 1,
 		capabilities: [
@@ -322,14 +416,8 @@ const mockInvokeHandlers = {
 		permission: permissionOf(args),
 		status: "granted"
 	}),
-	"media.pick": () => ({
-		url: MOCK_MEDIA_DATA_URI,
-		path: ""
-	}),
-	"media.capture": () => ({
-		url: MOCK_MEDIA_DATA_URI,
-		path: ""
-	})
+	"media.pick": () => ({ url: MOCK_MEDIA_DATA_URI }),
+	"media.capture": () => ({ url: MOCK_MEDIA_DATA_URI })
 };
 function createMockTransport() {
 	const listeners = /* @__PURE__ */ new Set();
@@ -380,5 +468,4 @@ function createMockTransport() {
 		}
 	};
 }
-//#endregion
 export { createMockTransport, createWebSocketTransport };