pikiloom 0.4.26 → 0.4.28

package/dist/pikichannel/rendezvous-broker.js

@@ -1,31 +1,11 @@
-/**
- * pikichannel/rendezvous-broker.ts — the public signaling broker (NAT traversal).
- *
- * This is the "route, don't relay data" rendezvous from the original design. A
- * pikiloom host that sits behind NAT dials OUT to a broker and registers a
- * NodeID; a client dials the same broker by NodeID. The broker pairs them and
- * relays ONLY signaling envelopes (SDP offer/answer + ICE candidates) — it never
- * sees datachannel data, which flows directly P2P (DTLS-encrypted) once ICE
- * hole-punches through. It is dependency-light (no werift) so any pikiloom can
- * act as a broker for reachable peers, or it can be run standalone.
- *
- * Wire protocol (JSON over the rendezvous WebSocket):
- *   host→  {t:'register', nodeId}            ← register to receive dials
- *      ←   {t:'registered', nodeId} | {t:'error', message}
- *   client→{t:'dial', nodeId}                ← reach a registered host
- *      ←   {t:'dialed', sessionId} | {t:'error', message}
- *   broker→host {t:'open', sessionId}        ← a client dialed; prepare answerer
- *   peer↔  {t:'signal', sessionId, data}     ← relayed to the other end verbatim
- *   broker→peer {t:'close', sessionId}       ← the other end went away
- */
 import crypto from 'node:crypto';
 import { WebSocketServer } from 'ws';
 import { writeScopedLog } from '../core/logging.js';
 const rlog = (msg) => writeScopedLog('pikichannel', `[rendezvous] ${msg}`, { level: 'info' });
 export class RendezvousBroker {
     wss = new WebSocketServer({ noServer: true });
-    hosts = new Map(); // nodeId → host socket
-    sessions = new Map(); // sessionId → pair
+    hosts = new Map();
+    sessions = new Map();
     constructor() {
         this.wss.on('connection', (ws) => this.onConnection(ws));
     }
@@ -39,12 +19,12 @@ export class RendezvousBroker {
             try {
                 ws.send(JSON.stringify(msg));
             }
-            catch { /* ignore */ }
+            catch { }
         }
     }
     onConnection(ws) {
-        let myNodeId = null; // set if this socket registers as a host
-        const mySessions = new Set(); // sessions this socket participates in
+        let myNodeId = null;
+        const mySessions = new Set();
         ws.on('message', (raw) => {
             let m;
             try {
@@ -60,7 +40,6 @@ export class RendezvousBroker {
                         this.send(ws, { t: 'error', message: 'nodeId required' });
                         return;
                     }
-                    // Last registration wins (a host reconnecting replaces its stale socket).
                     this.hosts.set(nodeId, ws);
                     myNodeId = nodeId;
                     this.send(ws, { t: 'registered', nodeId });

package/dist/pikichannel/rendezvous-host.js

@@ -1,16 +1,3 @@
-/**
- * pikichannel/rendezvous-host.ts — the host's OUTBOUND registrar (NAT side).
- *
- * A pikiloom host behind NAT can't be dialed directly, so it dials OUT to a
- * reachable {@link RendezvousBroker} and registers its NodeID. For each client
- * that dials that NodeID, the broker relays signaling and this client drives a
- * shared werift answerer — the resulting datachannel is a normal pikichannel
- * connection, indistinguishable downstream from a direct or local one. The
- * registration auto-reconnects so the host stays reachable.
- *
- * Imports werift (via webrtc-shared), so the server wiring loads it only inside
- * the guarded WebRTC dynamic import.
- */
 import WebSocket from 'ws';
 import { writeScopedLog } from '../core/logging.js';
 import { createAnswerer } from './transports/webrtc-shared.js';
@@ -37,7 +24,7 @@ export class RendezvousHostClient {
         try {
             ws?.close();
         }
-        catch { /* ignore */ }
+        catch { }
         for (const a of this.answerers.values())
             a.close();
         this.answerers.clear();
@@ -107,7 +94,7 @@ export class RendezvousHostClient {
             }
             case 'signal': {
                 if (this.adopted.has(m.sessionId))
-                    return; // datachannel already live; ignore late signals
+                    return;
                 const a = this.ensureAnswerer(m.sessionId);
                 void a.onSignal(m.data);
                 return;
@@ -123,7 +110,7 @@ export class RendezvousHostClient {
             log: rlog,
             onConnection: (conn) => {
                 this.adopted.add(sessionId);
-                this.answerers.delete(sessionId); // pc now owned by the connection
+                this.answerers.delete(sessionId);
                 this.onConnection(conn);
             },
             sendSignal: (data) => {

package/dist/pikichannel/server.js

@@ -1,18 +1,3 @@
-/**
- * pikichannel/server.ts — wires pikichannel into the pikiloom dashboard server.
- *
- * Responsibilities:
- *   - build the host over the pikiloom SessionSource,
- *   - stand up BOTH transport bindings (WebSocket always; WebRTC via a guarded
- *     dynamic import so a missing/broken werift never blocks startup),
- *   - register the reference web routes (demo page + browser SDK + status),
- *   - expose `attachUpgrade(server)` so the dashboard's HTTP server can route
- *     `/pikichannel/*` upgrade requests to the right binding.
- *
- * Both bindings funnel into the SAME `host.handleConnection`, so a session
- * behaves identically regardless of transport — that is the pluggability the
- * two bindings exist to demonstrate.
- */
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -24,14 +9,12 @@ import { prewarmTurn, turnStatus } from './turn.js';
 import { PikiloomSessionSource } from './adapter-pikiloom.js';
 import { WebSocketTransport } from './transports/websocket-host.js';
 import { RendezvousBroker } from './rendezvous-broker.js';
-/** A remote address label is loopback when it is the local host. */
 function isLoopback(remote) {
     if (!remote)
         return false;
     const r = remote.toLowerCase();
     return r.startsWith('127.') || r.includes('127.0.0.1') || r === '::1' || r.startsWith('::1:') || r.startsWith('[::1]') || r.includes('::ffff:127.');
 }
-/** Constant-time token comparison. */
 function tokenMatches(presented, expected) {
     if (!presented || !expected)
         return false;
@@ -45,13 +28,7 @@ function readWebAsset(name) {
 }
 export async function mountPikichannel(app) {
     const log = (msg) => writeScopedLog('pikichannel', msg, { level: 'info' });
-    // -- Access token: provision on first run, persist to ~/.pikiloom/setting.json.
-    //    Loopback peers (the local dashboard / same-machine demo) are exempt;
-    //    remote peers must present this token in `hello`. `strict` requires the
-    //    token even from loopback (defense-in-depth / testing). --
     const cfg = loadUserConfig();
-    // Env overrides (docker / headless): PIKICHANNEL_TOKEN pins the token without
-    // persisting; PIKICHANNEL_STRICT=1 forces token even from loopback.
     const envToken = String(process.env.PIKICHANNEL_TOKEN || '').trim();
     let token = envToken || String(cfg.pikichannelToken || '').trim();
     if (!token) {
@@ -70,20 +47,16 @@ export async function mountPikichannel(app) {
             return true;
         return tokenMatches(presented, token);
     };
-    // -- NodeID: the stable address a remote client dials over the rendezvous. --
     let nodeId = String(cfg.pikichannelNodeId || '').trim();
     if (!nodeId) {
         nodeId = crypto.randomBytes(8).toString('hex');
         try {
             updateUserConfig({ pikichannelNodeId: nodeId });
         }
-        catch { /* persisted best-effort */ }
+        catch { }
     }
     const rendezvousUrl = String(process.env.PIKICHANNEL_RENDEZVOUS || cfg.pikichannelRendezvous || '').trim();
     let currentPublicHost = String(process.env.PIKICHANNEL_PUBLIC_HOST || cfg.pikichannelPublicHost || '').trim();
-    // Control-plane tunnel forwarder: replay a tunneled request against the SAME
-    // Hono router that serves /api/* locally — management logic stays single-sourced.
-    // Text responses ride as utf8; anything else (attachment bytes) as base64.
     const forward = async (req) => {
         const init = { method: req.method || 'GET', headers: req.headers };
         if (req.body != null && req.method && req.method !== 'GET' && req.method !== 'HEAD') {
@@ -102,10 +75,8 @@ export async function mountPikichannel(app) {
     const source = new PikiloomSessionSource(forward);
     const host = new PikichannelHost(source, authenticate, log);
     host.start();
-    // -- WebSocket binding (always available) --
     const wsTransport = new WebSocketTransport();
     wsTransport.start((conn) => host.handleConnection(conn));
-    // -- WebRTC binding (guarded; degrades gracefully) --
     let rtcTransport = null;
     let webrtcError = null;
     try {
@@ -119,18 +90,8 @@ export async function mountPikichannel(app) {
         webrtcError = err?.message || String(err);
         log(`webrtc transport unavailable: ${webrtcError}`);
     }
-    // Pre-mint Cloudflare TURN credentials (if configured) so the first WebRTC
-    // connection already has a relay to fall back to. Best-effort, non-blocking;
-    // no creds → no-op, and the answerer resolves STUN until/unless minting lands.
     void prewarmTurn();
-    // -- Rendezvous broker (NAT traversal): always mounted (no werift dep), so any
-    //    reachable pikiloom can broker signaling for NAT'd peers. Relays signaling
-    //    only; data stays P2P. --
     const broker = new RendezvousBroker();
-    // -- Rendezvous registrar: when enabled, this host dials OUT to a broker and
-    //    registers its NodeID so remote clients can reach it through NAT. Can be
-    //    toggled at RUNTIME (one-click from the dashboard) — no restart. Needs
-    //    werift, so the host-client class is loaded only when WebRTC is available. --
     let rendezvousHost = null;
     let HostClientCtor = null;
     let currentRendezvous = '';
@@ -160,14 +121,13 @@ export async function mountPikichannel(app) {
             try {
                 updateUserConfig({ pikichannelRendezvous: next });
             }
-            catch { /* best-effort */ }
+            catch { }
         }
         log(`rendezvous ${next ? `enabled url=${next} nodeId=${nodeId}` : 'disabled'}`);
         return { ok: true };
     }
     if (rendezvousUrl)
-        await setRendezvous(rendezvousUrl, false); // initial from env/config
-    // -- Web assets (read once; the demo + SDK double as the OSS reference client) --
+        await setRendezvous(rendezvousUrl, false);
     let sdkJs = '';
     let demoHtml = '';
     try {
@@ -180,9 +140,6 @@ export async function mountPikichannel(app) {
     const serveDemo = (c) => { c.header('Cache-Control', 'no-cache'); return c.html(demoHtml || '<h1>pikichannel demo asset missing</h1>'); };
     app.get('/pikichannel', serveDemo);
     app.get('/pikichannel/', serveDemo);
-    // QR of a connection code (or any short string) as SVG — reuses the repo's
-    // `qrcode` dep so the browser SDK needs no QR library. Dynamic-imported to
-    // keep startup lean.
     app.get('/pikichannel/qr', async (c) => {
         const data = String(c.req.query('data') || '').slice(0, 2048);
         if (!data)
@@ -204,9 +161,6 @@ export async function mountPikichannel(app) {
         return c.body(sdkJs || '// pikichannel sdk asset missing');
     });
     app.get('/pikichannel/status', (c) => c.json(statusObj()));
-    // -- Pairing: hand the access token to a trusted LOCAL caller only (the
-    //    dashboard / CLI on this machine). Remote callers get 403 — they must be
-    //    paired out-of-band (token shown in the local dashboard, scanned as a QR). --
     app.get('/pikichannel/pair', (c) => {
         let remote;
         try {
@@ -219,9 +173,6 @@ export async function mountPikichannel(app) {
             return c.json({ ok: false, error: 'pairing is only available from localhost' }, 403);
         return c.json({ ok: true, token, strict, nodeId, rendezvous: currentRendezvous || null, publicHost: currentPublicHost || null, registered: !!rendezvousHost, hint: 'paste the connection code into a client' });
     });
-    // -- Remote-access settings: configure how others reach THIS host — a public
-    //    address (direct) and/or internet穿透 (rendezvous). Runtime, one-click,
-    //    localhost-only (it changes who can reach this machine). --
     app.post('/pikichannel/remote', async (c) => {
         let remote;
         try {
@@ -238,7 +189,7 @@ export async function mountPikichannel(app) {
             try {
                 updateUserConfig({ pikichannelPublicHost: currentPublicHost });
             }
-            catch { /* best-effort */ }
+            catch { }
         }
         let r = { ok: true };
         if ('enabled' in body || 'rendezvous' in body) {
@@ -268,7 +219,7 @@ export async function mountPikichannel(app) {
         handleUpgrade(req, socket, head) {
             const url = new URL(req.url || '/', `http://${req.headers.host || 'localhost'}`);
             if (!url.pathname.startsWith('/pikichannel/'))
-                return false; // not ours
+                return false;
             if (url.pathname === '/pikichannel/ws') {
                 wsTransport.handleUpgrade(req, socket, head);
                 return true;
@@ -281,7 +232,7 @@ export async function mountPikichannel(app) {
                 broker.handleUpgrade(req, socket, head);
                 return true;
             }
-            socket.destroy(); // unknown /pikichannel/* subpath (or webrtc disabled)
+            socket.destroy();
             return true;
         },
         status: statusObj,

package/dist/pikichannel/transport.js

@@ -1,25 +1,3 @@
-/**
- * pikichannel/transport.ts — the L1 transport abstraction (host side).
- *
- * This is the seam that makes the two delivery mechanisms — WebSocket and
- * WebRTC datachannel — interchangeable. A {@link ChannelTransport} accepts peer
- * connections and surfaces each as a {@link ChannelConnection}: a reliable,
- * ordered, bidirectional frame pipe. The host ({@link PikichannelHost}) drives
- * the L2 protocol over a ChannelConnection and is wholly blind to whether the
- * bytes travel over a TCP WebSocket or an SCTP datachannel — flip the binding,
- * the session behaves identically. That blindness IS the comparability the two
- * bindings are meant to demonstrate.
- *
- * Contract every binding must honour:
- *   - reliable + ordered delivery of whole frames (no partial frames),
- *   - bidirectional,
- *   - a single 'close' notification, exactly once,
- *   - `send()` after close is a silent no-op (never throws).
- */
-/**
- * Minimal base that implements the callback bookkeeping every binding repeats,
- * so concrete connections only push frames in and call `emitClose()` once.
- */
 export class BaseConnection {
     remote;
     messageCb = null;
@@ -28,16 +6,13 @@ export class BaseConnection {
     onMessage(cb) { this.messageCb = cb; }
     onClose(cb) {
         this.closeCb = cb;
-        // If close already happened before the handler was attached, fire now.
         if (this.closed)
             cb();
     }
-    /** Concrete bindings call this when a frame arrives. */
     emitMessage(frame) {
         if (this.messageCb)
             this.messageCb(frame);
     }
-    /** Concrete bindings call this exactly once when the pipe closes. */
     emitClose() {
         if (this.closed)
             return;

package/dist/pikichannel/transports/webrtc-host.js

@@ -1,16 +1,3 @@
-/**
- * pikichannel/transports/webrtc-host.ts — the DIRECT WebRTC binding (host).
- *
- * SDP/ICE over a same-origin `/pikichannel/signal` WebSocket, for clients that
- * can already reach the host (localhost / LAN / public IP). The cross-NAT path —
- * where the host dials OUT to a public broker — lives in rendezvous.ts. Both
- * paths share the same werift answerer (webrtc-shared.ts), so a connection from
- * either is identical downstream.
- *
- * werift is imported (transitively) here; the server wiring loads this module via
- * a guarded dynamic import, so a missing/broken werift disables WebRTC while the
- * WebSocket binding and the dashboard keep working.
- */
 import { WebSocketServer } from 'ws';
 import { writeScopedLog } from '../../core/logging.js';
 import { createAnswerer } from './webrtc-shared.js';
@@ -23,14 +10,12 @@ export class WebRTCTransport {
         this.onConn = onConnection;
         this.wss.on('connection', (ws, req) => this.runSignaling(ws, req));
     }
-    /** Server wiring routes a matching signaling upgrade request here. */
     handleUpgrade(req, socket, head) {
         this.wss.handleUpgrade(req, socket, head, (ws) => this.wss.emit('connection', ws, req));
     }
     stop() {
         this.wss.close();
     }
-    /** One signaling WebSocket brokers exactly one peer connection. */
     runSignaling(ws, req) {
         const remote = req.socket.remoteAddress ? `${req.socket.remoteAddress}:${req.socket.remotePort}` : undefined;
         const answerer = createAnswerer({
@@ -50,9 +35,6 @@ export class WebRTCTransport {
             }
             void answerer.onSignal(msg);
         });
-        // The signaling socket is only needed for the handshake; once the datachannel
-        // carries traffic it can close. If it drops before a channel was adopted,
-        // tear the half-open peer down.
         const cleanup = () => { if (!answerer.isAdopted())
             answerer.close(); };
         ws.on('close', cleanup);

package/dist/pikichannel/transports/webrtc-shared.js

@@ -1,29 +1,7 @@
-/**
- * pikichannel/transports/webrtc-shared.ts — shared werift answerer + connection.
- *
- * The host is always the WebRTC *answerer* (the browser/SDK creates the offer +
- * datachannel). The same answerer logic drives two signaling paths:
- *   - direct  (webrtc-host.ts): SDP/ICE over a same-origin `/pikichannel/signal`
- *     WebSocket — for clients that can already reach the host.
- *   - rendezvous (rendezvous.ts): SDP/ICE relayed through a public broker both
- *     peers dial OUTBOUND — the NAT-traversal path.
- *
- * Once the datachannel opens the bytes are pure P2P (DTLS-encrypted); signaling
- * only brokers the handshake. `getIceServers()` is the STUN/TURN config hook —
- * see turn.ts: STUN by default, Cloudflare-minted short-lived TURN (or a manual
- * PIKICHANNEL_ICE_SERVERS override) when configured, for symmetric-NAT / CGNAT
- * relay fallback.
- */
 import { RTCPeerConnection } from 'werift';
 import { BaseConnection } from '../transport.js';
 import { getCachedIceServers, toWeriftIceServers } from '../turn.js';
 let connCounter = 0;
-/**
- * ICE servers for the werift answerer, reduced to exactly what werift consumes
- * (one STUN + one UDP TURN — see {@link toWeriftIceServers}). The resolution
- * policy lives in turn.ts: a manual PIKICHANNEL_ICE_SERVERS override, else cached
- * Cloudflare-minted short-lived credentials, else plain STUN.
- */
 export function getIceServers() {
     return toWeriftIceServers(getCachedIceServers());
 }
@@ -39,7 +17,6 @@ function coerceFrame(data) {
         return String(data);
     }
 }
-/** A pikichannel connection riding an SCTP datachannel. */
 export class RtcConnection extends BaseConnection {
     channel;
     pc;
@@ -63,7 +40,7 @@ export class RtcConnection extends BaseConnection {
             try {
                 this.channel.send(frame);
             }
-            catch { /* drop on closing channel */ }
+            catch { }
         }
     }
     isOpen() { return this.channel.readyState === 'open'; }
@@ -71,21 +48,14 @@ export class RtcConnection extends BaseConnection {
         try {
             this.channel.close();
         }
-        catch { /* ignore */ }
+        catch { }
         try {
             this.pc.close();
         }
-        catch { /* ignore */ }
+        catch { }
         this.emitClose();
     }
 }
-/**
- * Build a werift answerer. The caller wires `sendSignal` to whatever signaling
- * channel it has (a WS, or the rendezvous), feeds inbound signals to `onSignal`,
- * and receives the live {@link ChannelConnection} via `onConnection` once the
- * datachannel opens. Trickle ICE: the answer is sent immediately, candidates
- * follow as they are gathered.
- */
 export function createAnswerer(opts) {
     const pc = new RTCPeerConnection({ iceServers: getIceServers() });
     let adopted = false;
@@ -121,6 +91,6 @@ export function createAnswerer(opts) {
         close() { try {
             pc.close();
         }
-        catch { /* ignore */ } },
+        catch { } },
     };
 }

package/dist/pikichannel/transports/websocket-host.js

@@ -1,15 +1,3 @@
-/**
- * pikichannel/transports/websocket-host.ts — the WebSocket L1 binding (host).
- *
- * The baseline transport: protocol frames ride a raw WebSocket. Same-machine /
- * LAN clients (the Dashboard case) want exactly this — there is no NAT to
- * traverse, so a TCP WebSocket is the optimal path. It is the control against
- * which the WebRTC binding is compared.
- *
- * The server wiring owns upgrade routing and feeds matching upgrades to
- * `handleUpgrade`; this class only manages the noServer WebSocketServer and
- * wraps each socket as a {@link ChannelConnection}.
- */
 import { WebSocketServer } from 'ws';
 import { BaseConnection } from '../transport.js';
 const WS_KEEPALIVE_MS = 25_000;
@@ -48,7 +36,7 @@ class WsConnection extends BaseConnection {
         try {
             this.ws.close();
         }
-        catch { /* ignore */ }
+        catch { }
         this.emitClose();
     }
 }
@@ -68,7 +56,6 @@ export class WebSocketTransport {
             this.onConn?.(new WsConnection(ws, remote));
         });
     }
-    /** Server wiring routes a matching upgrade request here. */
     handleUpgrade(req, socket, head) {
         this.wss.handleUpgrade(req, socket, head, (ws) => this.wss.emit('connection', ws, req));
     }

package/dist/pikichannel/turn.js

@@ -1,51 +1,17 @@
-/**
- * pikichannel/turn.ts — Cloudflare Realtime TURN credential minter (host side).
- *
- * Why host-only is sufficient: the host is the WebRTC *answerer*. A TURN relay
- * candidate it gathers is an allocation ON the TURN server that ANY client can
- * reach OUTBOUND (NAT always allows outbound). So configuring TURN here alone
- * gives relay fallback for EVERY NAT combination — symmetric NAT and CGNAT on
- * either end included — without the browser needing its own TURN credentials.
- * The host trickles its relay candidate to the client; the client just sends to
- * it. (The browser keeps plain STUN; see web/sdk.js.)
- *
- * Security: the long-lived Cloudflare API token NEVER leaves this process. We
- * exchange it for SHORT-LIVED (TTL'd) credentials via Cloudflare's API and feed
- * only those to the peer connection. No secret is ever sent over the wire.
- *
- * Cost: callers must keep `iceTransportPolicy` at its default `'all'` (never
- * force `'relay'`), so direct/STUN paths are always preferred and the relay —
- * the only metered part of Cloudflare Realtime — is a genuine last resort.
- * Credentials are minted once and cached across all connections, refreshed just
- * before expiry, so steady state is zero API calls per connection.
- *
- * Fallback: no Cloudflare config (or any mint failure) → plain STUN, exactly as
- * before. Existing hosts see zero behavior change.
- *
- * See https://developers.cloudflare.com/realtime/turn/generate-credentials/.
- */
 import { loadUserConfig } from '../core/config/user-config.js';
 import { writeScopedLog } from '../core/logging.js';
 const tlog = (msg) => writeScopedLog('pikichannel', `[turn] ${msg}`, { level: 'info' });
-/** Default credential lifetime (24h). Must exceed a single session's duration. */
 const DEFAULT_TTL = 86_400;
-/** Floor for TTL so a fat-fingered tiny value can't churn the cache. */
 const MIN_TTL = 600;
-/** Re-mint this long before expiry so live connections never use dead creds. */
 const REFRESH_MARGIN_MS = 5 * 60 * 1000;
-/** Abort a hung Cloudflare call so connection setup falls back to STUN promptly. */
 const MINT_TIMEOUT_MS = 8_000;
-/** Cloudflare credentials endpoint (the array-returning `generate-ice-servers`). */
 const CF_ENDPOINT = (keyId) => `https://rtc.live.cloudflare.com/v1/turn/keys/${encodeURIComponent(keyId)}/credentials/generate-ice-servers`;
-/** Free public STUN used when no TURN is configured. Google first keeps the
- *  no-config host's behavior identical to before; Cloudflare added for redundancy. */
 const DEFAULT_STUN = [
     { urls: 'stun:stun.l.google.com:19302' },
     { urls: 'stun:stun.cloudflare.com:3478' },
 ];
 let cache = null;
 let pending = null;
-/** Resolve TURN config from env (highest) then ~/.pikiloom/setting.json. */
 export function resolveTurnConfig() {
     const cfg = loadUserConfig();
     const keyId = String(process.env.PIKICHANNEL_TURN_KEY_ID || cfg.pikichannelTurnKeyId || '').trim();
@@ -54,8 +20,6 @@ export function resolveTurnConfig() {
     const ttl = Math.max(MIN_TTL, Number.parseInt(ttlRaw, 10) || DEFAULT_TTL);
     return { keyId, apiToken, ttl };
 }
-/** A manual `PIKICHANNEL_ICE_SERVERS` JSON override, flattened — or null. This
- *  preserves the original escape hatch and takes precedence over minting. */
 function manualIceServers() {
     const raw = process.env.PIKICHANNEL_ICE_SERVERS;
     if (!raw)
@@ -65,11 +29,9 @@ function manualIceServers() {
         if (Array.isArray(v) && v.length)
             return flatten(v);
     }
-    catch { /* fall through */ }
+    catch { }
     return null;
 }
-/** Flatten any `{ urls: string | string[], ... }[]` into one entry per URL,
- *  carrying username/credential onto each. werift treats `urls` as a string. */
 function flatten(servers) {
     const out = [];
     for (const s of servers) {
@@ -93,8 +55,6 @@ const flattenCloudflare = flatten;
 function cfgKey(c) {
     return `${c.keyId}::${c.ttl}`;
 }
-/** Mint a fresh set of short-lived ICE servers from Cloudflare. Throws on any
- *  non-2xx / network error / timeout so the caller can fall back to STUN. */
 async function mintCloudflare(cfg) {
     const ctrl = new AbortController();
     const timer = setTimeout(() => ctrl.abort(), MINT_TIMEOUT_MS);
@@ -117,9 +77,6 @@ async function mintCloudflare(cfg) {
         clearTimeout(timer);
     }
 }
-/** (Re)mint into the module cache. Single-flight: concurrent callers await one
- *  in-flight mint. On failure the last-good cache is kept if still for this key;
- *  otherwise cleared so the resolver yields STUN. */
 function refresh(cfg) {
     if (pending)
         return pending;
@@ -141,11 +98,6 @@ function refresh(cfg) {
     })();
     return pending;
 }
-/**
- * Mint TURN credentials ahead of the first connection (call once at mount).
- * Best-effort and non-blocking-by-design — awaiting it is optional. No creds /
- * manual override → no-op.
- */
 export async function prewarmTurn() {
     if (manualIceServers())
         return;
@@ -154,13 +106,6 @@ export async function prewarmTurn() {
         return;
     await refresh(cfg);
 }
-/**
- * The current resolved ICE servers, synchronously, for building a peer
- * connection. Order of precedence: manual override → cached Cloudflare creds →
- * STUN. When the cache is missing/stale it kicks off a background refresh and
- * returns the best value available right now (never blocks, never returns
- * expired creds).
- */
 export function getCachedIceServers() {
     const manual = manualIceServers();
     if (manual)
@@ -171,13 +116,11 @@ export function getCachedIceServers() {
     const key = cfgKey(cfg);
     const fresh = !!cache && cache.key === key && Date.now() < cache.expiresAt - REFRESH_MARGIN_MS;
     if (!fresh)
-        void refresh(cfg); // background; don't block the handshake
-    // Use cached creds only while genuinely unexpired; otherwise STUN.
+        void refresh(cfg);
     if (cache && cache.key === key && Date.now() < cache.expiresAt)
         return cache.servers;
     return DEFAULT_STUN;
 }
-/** Async resolver (mint awaited) — for status, tests, and one-off callers. */
 export async function resolveIceServers() {
     const manual = manualIceServers();
     if (manual)
@@ -193,14 +136,6 @@ export async function resolveIceServers() {
         return cache.servers;
     return DEFAULT_STUN;
 }
-/**
- * Reduce a (flattened) ICE list to what werift's primitive `parseIceServers`
- * actually consumes: it takes the FIRST `stun:` and FIRST `turn:` entry, reads
- * `urls` as a string, and connects to TURN over UDP. So we hand it exactly one
- * STUN and one UDP TURN entry. `turns:` (TLS) is dropped — werift's TURN client
- * speaks only udp/tcp. List order is meaningful: Cloudflare returns :3478/udp
- * first, and DEFAULT_STUN puts Google first, so the right entries win.
- */
 export function toWeriftIceServers(servers) {
     const stun = servers.find((s) => s.urls.startsWith('stun:'));
     const turn = servers.find((s) => s.urls.startsWith('turn:') && s.urls.includes('transport=udp')) ||
@@ -212,7 +147,6 @@ export function toWeriftIceServers(servers) {
         out.push({ urls: turn.urls, username: turn.username, credential: turn.credential });
     return out.length ? out : servers;
 }
-/** Lightweight status for /pikichannel/status (no secrets). */
 export function turnStatus() {
     if (manualIceServers()) {
         const hasTurn = (manualIceServers() || []).some((s) => s.urls.startsWith('turn:') || s.urls.startsWith('turns:'));
@@ -228,7 +162,6 @@ export function turnStatus() {
         expiresAt: live && cache ? cache.expiresAt : null,
     };
 }
-/** Test-only: drop the module cache + in-flight mint so cases start clean. */
 export function __resetTurnCacheForTest() {
     cache = null;
     pending = null;