@lumencast/runtime 0.1.0

package/src/state/apply-snapshot.ts

@@ -0,0 +1,8 @@
+import type { SnapshotFrame } from "@lumencast/protocol";
+import type { Store } from "./store.js";
+
+/** Apply an LSDP/1 snapshot to the store. Replaces the entire state — paths
+ *  not present in the snapshot are reset to `undefined`. */
+export function applySnapshot(store: Store, frame: SnapshotFrame): void {
+  store.reset(frame.state);
+}

package/src/state/store.ts

@@ -0,0 +1,141 @@
+// State store — one signal per leaf path.
+//
+// Integration point between the WS layer (snapshot + delta) and the render
+// layer. Each path Lumencast has ever seen owns a `Signal<unknown>`;
+// readers subscribe via @preact/signals-react `useSignals()` and re-render
+// only when their path's value changes.
+//
+// LSDP/1.1 §3.2.2 — incoming deltas may carry a per-leaf `transition`
+// directive. The store keeps the most-recent directive per path so the
+// renderer can pick it up on the next animation cycle. Snapshots clear
+// any pending transitions for the affected paths (snapshots are not
+// animated transitions).
+
+import { signal, type Signal, batch } from "@preact/signals-react";
+import type { Transition } from "../animate/transitions";
+
+export interface Store {
+  /** Get-or-create the signal for a path. New paths start as `undefined`. */
+  signal(path: string): Signal<unknown>;
+  /** Apply a single leaf write. */
+  set(path: string, value: unknown): void;
+  /** Apply a single leaf write with an LSDP/1.1 §3.2.2 transition directive.
+   * The directive lives in a separate signal so the renderer can subscribe
+   * to it independently. Passing `undefined` clears any pending directive. */
+  setWithTransition(path: string, value: unknown, transition: Transition | undefined): void;
+  /** Read the most-recent transition directive for a path (or undefined
+   * when no directive has been applied since the last snapshot). The
+   * returned signal is reactive — components reading via `useSignals()`
+   * re-render when the directive changes. */
+  transitionSignal(path: string): Signal<Transition | undefined>;
+  /**
+   * Replace the whole state — used by `apply-snapshot`. Existing signals are
+   * reused (subscribers stay attached); paths missing from the snapshot reset
+   * to `undefined`. Pending per-path transitions are cleared (a snapshot is
+   * a state restore, not an animated change).
+   */
+  reset(state: Record<string, unknown>): void;
+  /** Snapshot of every known path → current value. For debug / state inspector. */
+  toRecord(): Record<string, unknown>;
+}
+
+class StoreImpl implements Store {
+  private readonly signals = new Map<string, Signal<unknown>>();
+  private readonly transitions = new Map<string, Signal<Transition | undefined>>();
+
+  signal(path: string): Signal<unknown> {
+    let s = this.signals.get(path);
+    if (!s) {
+      s = signal<unknown>(undefined);
+      this.signals.set(path, s);
+    }
+    return s;
+  }
+
+  transitionSignal(path: string): Signal<Transition | undefined> {
+    let s = this.transitions.get(path);
+    if (!s) {
+      s = signal<Transition | undefined>(undefined);
+      this.transitions.set(path, s);
+    }
+    return s;
+  }
+
+  set(path: string, value: unknown): void {
+    const s = this.signal(path);
+    if (!shallowEqual(s.peek(), value)) {
+      s.value = value;
+    }
+  }
+
+  setWithTransition(path: string, value: unknown, transition: Transition | undefined): void {
+    batch(() => {
+      const ts = this.transitionSignal(path);
+      // Update transition before value so the render that observes the
+      // new value sees the correct transition.
+      if (ts.peek() !== transition) ts.value = transition;
+      const s = this.signal(path);
+      if (!shallowEqual(s.peek(), value)) s.value = value;
+    });
+  }
+
+  reset(state: Record<string, unknown>): void {
+    batch(() => {
+      const seen = new Set<string>();
+      for (const [path, value] of Object.entries(state)) {
+        seen.add(path);
+        const s = this.signal(path);
+        if (!shallowEqual(s.peek(), value)) {
+          s.value = value;
+        }
+        // Snapshots are not animated transitions — clear any pending
+        // per-path directive (LSDP/1.1 §3.2.2 — directives apply to
+        // the NEXT delta only, snapshots reseed state authoritatively).
+        const ts = this.transitions.get(path);
+        if (ts && ts.peek() !== undefined) ts.value = undefined;
+      }
+      for (const path of this.signals.keys()) {
+        if (!seen.has(path)) {
+          const s = this.signals.get(path);
+          if (s && s.peek() !== undefined) s.value = undefined;
+        }
+      }
+    });
+  }
+
+  toRecord(): Record<string, unknown> {
+    const out: Record<string, unknown> = {};
+    for (const [path, s] of this.signals.entries()) {
+      out[path] = s.peek();
+    }
+    return out;
+  }
+}
+
+export function createStore(): Store {
+  return new StoreImpl();
+}
+
+function shallowEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (a === null || b === null) return false;
+  if (typeof a !== typeof b) return false;
+  if (typeof a !== "object") return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (a[i] !== b[i]) return false;
+    }
+    return true;
+  }
+  const ao = a as Record<string, unknown>;
+  const bo = b as Record<string, unknown>;
+  const ak = Object.keys(ao);
+  const bk = Object.keys(bo);
+  if (ak.length !== bk.length) return false;
+  for (const k of ak) {
+    if (ao[k] !== bo[k]) return false;
+  }
+  return true;
+}

package/src/transport/reconnect.ts

@@ -0,0 +1,83 @@
+// Exponential backoff schedule for the WS reconnect loop.
+//
+// Aggressive at first (200 ms, 400 ms, 800 ms…) then capped at 5 s so a
+// sustained outage doesn't hammer the gateway. Jittered to avoid thundering
+// herds when several Lumencast instances reconnect together (e.g. a CEF
+// host + a webview waking from suspend at the same time).
+//
+// The reference schedule in LSDP/1 §7 is "0 ms, 500 ms, 1 s, 2 s, 4 s, 8 s,
+// 15 s, 30 s, 60 s cap". This implementation defaults are tighter; both are
+// MAY-bounded by the spec.
+
+export interface ReconnectScheduleOptions {
+  /** First delay in milliseconds. */
+  initial?: number;
+  /** Maximum delay in milliseconds. */
+  max?: number;
+  /** Multiplicative factor between attempts (>= 1). */
+  factor?: number;
+  /** Jitter as a fraction of the delay (0 disables, 0.2 = ±20 %). */
+  jitter?: number;
+  /** Random source — only injected for tests. */
+  random?: () => number;
+}
+
+const DEFAULTS: Required<Omit<ReconnectScheduleOptions, "random">> = {
+  initial: 200,
+  max: 5_000,
+  factor: 2,
+  jitter: 0.2,
+};
+
+export interface ReconnectSchedule {
+  /** Returns the delay to wait before the n-th attempt (1-indexed). */
+  delayFor(attempt: number): number;
+  /** Reset to attempt 1 (called on a successful connection). */
+  reset(): void;
+  /** Current attempt counter. */
+  readonly attempt: number;
+}
+
+class ScheduleImpl implements ReconnectSchedule {
+  private _attempt = 0;
+  constructor(
+    private readonly opts: Required<Omit<ReconnectScheduleOptions, "random">>,
+    private readonly random: () => number,
+  ) {}
+
+  get attempt(): number {
+    return this._attempt;
+  }
+
+  delayFor(attempt: number): number {
+    if (!Number.isInteger(attempt) || attempt < 1) {
+      throw new RangeError(`attempt must be a positive integer, got ${attempt}`);
+    }
+    this._attempt = attempt;
+    const base = Math.min(
+      this.opts.initial * Math.pow(this.opts.factor, attempt - 1),
+      this.opts.max,
+    );
+    if (this.opts.jitter <= 0) return base;
+    const offset = (this.random() * 2 - 1) * this.opts.jitter * base;
+    return Math.max(0, base + offset);
+  }
+
+  reset(): void {
+    this._attempt = 0;
+  }
+}
+
+export function createReconnectSchedule(opts: ReconnectScheduleOptions = {}): ReconnectSchedule {
+  const merged = {
+    initial: opts.initial ?? DEFAULTS.initial,
+    max: opts.max ?? DEFAULTS.max,
+    factor: opts.factor ?? DEFAULTS.factor,
+    jitter: opts.jitter ?? DEFAULTS.jitter,
+  };
+  if (merged.initial <= 0) throw new RangeError("initial must be > 0");
+  if (merged.max < merged.initial) throw new RangeError("max must be >= initial");
+  if (merged.factor < 1) throw new RangeError("factor must be >= 1");
+  if (merged.jitter < 0 || merged.jitter > 1) throw new RangeError("jitter must be within [0, 1]");
+  return new ScheduleImpl(merged, opts.random ?? Math.random);
+}

package/src/transport/ws.ts

@@ -0,0 +1,359 @@
+// LSDP/1 WebSocket client.
+//
+// Lifecycle (LSDP/1 §6):
+//   1. open() — opens the WS with subprotocol `lsdp.v1`
+//   2. on open: send `subscribe` with the resolved token (and scene + session
+//      for test mode)
+//   3. server replies `snapshot` (seq=1) → emit onSnapshot
+//   4. subsequent `delta` / `scene_changed` / `error` / `pong` are dispatched
+//   5. on a sequence gap → close + reconnect (fresh snapshot)
+//   6. on close → reconnect with backoff, unless close was triggered by close()
+//   7. setToken() opens a parallel WS with the new token; once its snapshot
+//      lands, atomically swap and close the old socket — no rendering gap
+
+import {
+  decodeServerFrame,
+  encodeFrame,
+  LumencastError,
+  SequenceTracker,
+  WS_SUBPROTOCOL_V1_1,
+  WS_SUBPROTOCOLS,
+  input as inputFrame,
+  subscribe as subscribeFrame,
+  type DeltaFrame,
+  type ErrorCode,
+  type ErrorFrame,
+  type Patch,
+  type SceneChangedFrame,
+  type SnapshotFrame,
+} from "@lumencast/protocol";
+import type { LumencastToken } from "../types.js";
+import {
+  createReconnectSchedule,
+  type ReconnectSchedule,
+  type ReconnectScheduleOptions,
+} from "./reconnect.js";
+
+export type ConnectionStatus = "disconnected" | "connecting" | "live";
+
+export interface WsClientOptions {
+  url: string;
+  token: LumencastToken;
+  /** Optional scene identifier (test mode). */
+  scene?: string;
+  /** Optional session identifier (test mode). */
+  session?: string;
+  /** Override the WebSocket constructor (for tests / non-browser hosts). */
+  webSocketImpl?: typeof WebSocket;
+  /** Reconnect tuning. */
+  reconnect?: ReconnectScheduleOptions;
+  /** Inject scheduler for tests. */
+  scheduler?: {
+    setTimeout: typeof globalThis.setTimeout;
+    clearTimeout: typeof globalThis.clearTimeout;
+  };
+
+  onStatus?: (status: ConnectionStatus) => void;
+  onSnapshot?: (frame: SnapshotFrame) => void;
+  onDelta?: (frame: DeltaFrame) => void;
+  onSceneChanged?: (frame: SceneChangedFrame) => void;
+  onServerError?: (frame: ErrorFrame) => void;
+  /** Wire-level / codec / unrecoverable errors. */
+  onTransportError?: (err: TransportError) => void;
+}
+
+export class TransportError extends Error {
+  public readonly recoverable: boolean;
+  public readonly code: ErrorCode;
+  public override readonly cause?: unknown;
+  constructor(
+    message: string,
+    recoverable: boolean,
+    code: ErrorCode = "INTERNAL",
+    cause?: unknown,
+  ) {
+    super(message);
+    this.name = "TransportError";
+    this.recoverable = recoverable;
+    this.code = code;
+    this.cause = cause;
+  }
+}
+
+type Timer = ReturnType<typeof setTimeout>;
+
+interface InternalScheduler {
+  setTimeout: typeof globalThis.setTimeout;
+  clearTimeout: typeof globalThis.clearTimeout;
+}
+
+export class WsClient {
+  private status: ConnectionStatus = "disconnected";
+  private socket: WebSocket | null = null;
+  private token: LumencastToken;
+  private readonly url: string;
+  private readonly WebSocketCtor: typeof WebSocket;
+  private readonly schedule: ReconnectSchedule;
+  private readonly seq = new SequenceTracker();
+  private readonly opts: WsClientOptions;
+  private readonly scheduler: InternalScheduler;
+
+  private reconnectTimer: Timer | null = null;
+  private active = true;
+
+  constructor(opts: WsClientOptions) {
+    this.opts = opts;
+    this.url = opts.url;
+    this.token = opts.token;
+    const ctor = opts.webSocketImpl ?? globalThis.WebSocket;
+    if (!ctor) {
+      throw new TypeError(
+        "Lumencast WsClient: no WebSocket implementation found in this environment",
+      );
+    }
+    this.WebSocketCtor = ctor;
+    this.schedule = createReconnectSchedule(opts.reconnect);
+    this.scheduler = opts.scheduler ?? {
+      setTimeout: globalThis.setTimeout.bind(globalThis),
+      clearTimeout: globalThis.clearTimeout.bind(globalThis),
+    };
+  }
+
+  /** Open and start the connection lifecycle. Idempotent. */
+  start(): void {
+    if (!this.active) return;
+    if (this.socket || this.status === "connecting") return;
+    void this.openSocket();
+  }
+
+  /** Send `input` patches to the server. No-op if not connected. */
+  sendInput(patches: Patch[]): void {
+    if (!this.socket || this.socket.readyState !== this.WebSocketCtor.OPEN) return;
+    if (patches.length === 0) return;
+    this.socket.send(encodeFrame(inputFrame(patches)));
+  }
+
+  /** Replace the auth token. Closes and reopens with the new token. */
+  setToken(token: LumencastToken): void {
+    this.token = token;
+    if (!this.active) return;
+    if (this.socket) {
+      this.closeSocket();
+      this.scheduleReconnect(true);
+    }
+  }
+
+  /** Tear down for good. No more reconnect attempts. */
+  close(): void {
+    if (!this.active) return;
+    this.active = false;
+    this.cancelReconnect();
+    this.closeSocket();
+    this.setStatus("disconnected");
+  }
+
+  // --- internals --------------------------------------------------
+
+  private async openSocket(): Promise<void> {
+    if (!this.active) return;
+    this.setStatus("connecting");
+
+    let resolvedToken: string;
+    try {
+      resolvedToken = await resolveToken(this.token);
+    } catch (err) {
+      this.opts.onTransportError?.(
+        new TransportError(
+          `failed to resolve token: ${(err as Error).message}`,
+          true,
+          "AUTH_DENIED",
+          err,
+        ),
+      );
+      this.scheduleReconnect();
+      return;
+    }
+    if (!this.active) return;
+
+    let socket: WebSocket;
+    try {
+      // Advertise both 1.1 (preferred) and 1.0 (fallback) ; the server
+      // picks one. Spread to a mutable array — the WebSocket constructor
+      // type expects string[].
+      socket = new this.WebSocketCtor(this.url, [...WS_SUBPROTOCOLS]);
+    } catch (err) {
+      this.opts.onTransportError?.(
+        new TransportError(
+          `failed to open WebSocket: ${(err as Error).message}`,
+          true,
+          "INTERNAL",
+          err,
+        ),
+      );
+      this.scheduleReconnect();
+      return;
+    }
+
+    this.socket = socket;
+    socket.onopen = () => this.handleOpen(resolvedToken);
+    socket.onmessage = (event) => this.handleMessage(event);
+    socket.onerror = (event) => this.handleError(event);
+    socket.onclose = (event) => this.handleClose(event);
+  }
+
+  private handleOpen(token: string): void {
+    if (!this.socket) return;
+    // LSDP/1.1 §4.1, §18 — if we have a previously-observed seq AND the
+    // negotiated subprotocol is 1.1, request an incremental resume.
+    // The server will EITHER ship buffered deltas (cache stays valid)
+    // OR a fresh snapshot which we rebase via observeSnapshot.
+    const subprotocol = this.socket.protocol;
+    const canResume = subprotocol === WS_SUBPROTOCOL_V1_1 && this.seq.last > 0;
+    const sinceSequence = canResume ? this.seq.last : undefined;
+    if (!canResume) {
+      // Fresh subscription (no resume) — reset the tracker baseline.
+      this.seq.reset();
+    }
+    const frame = subscribeFrame({
+      token,
+      ...(this.opts.scene !== undefined ? { scene: this.opts.scene } : {}),
+      ...(this.opts.session !== undefined ? { session: this.opts.session } : {}),
+      ...(sinceSequence !== undefined ? { since_sequence: sinceSequence } : {}),
+    });
+    this.socket.send(encodeFrame(frame));
+  }
+
+  private handleMessage(event: MessageEvent): void {
+    const data = typeof event.data === "string" ? event.data : "";
+    if (!data) return;
+    let frame;
+    try {
+      frame = decodeServerFrame(data);
+    } catch (err) {
+      const message = err instanceof LumencastError ? err.message : (err as Error).message;
+      const code: ErrorCode = err instanceof LumencastError ? err.code : "INTERNAL";
+      this.opts.onTransportError?.(new TransportError(`codec: ${message}`, true, code, err));
+      this.closeSocket();
+      this.scheduleReconnect();
+      return;
+    }
+    if (frame === null) return; // unknown frame type — forward-compat ignore
+
+    switch (frame.type) {
+      case "snapshot": {
+        // LSDP/1.1 §18.1.1 — snapshot rebases the tracker to its seq
+        // value. This is the ONLY valid way to set or change the
+        // tracker's baseline (handles fresh sub, scene_changed, and
+        // back-pressure recovery uniformly).
+        if (frame.seq < 1) {
+          this.opts.onTransportError?.(
+            new TransportError(`snapshot seq must be >= 1, got ${frame.seq}`, true, "VERSION_GAP"),
+          );
+          this.closeSocket();
+          this.scheduleReconnect();
+          return;
+        }
+        this.seq.observeSnapshot(frame.seq);
+        this.schedule.reset();
+        this.setStatus("live");
+        this.opts.onSnapshot?.(frame);
+        return;
+      }
+      case "delta": {
+        const obs = this.seq.observe(frame.seq);
+        if (obs.kind === "gap") {
+          this.opts.onTransportError?.(
+            new TransportError(
+              `sequence gap: expected ${this.seq.last + 1}, got ${frame.seq}`,
+              true,
+              "VERSION_GAP",
+            ),
+          );
+          this.closeSocket();
+          this.scheduleReconnect();
+          return;
+        }
+        if (obs.kind === "duplicate") return; // silent drop per LSDP/1 §5
+        this.opts.onDelta?.(frame);
+        return;
+      }
+      case "scene_changed": {
+        // The next snapshot will rebase the tracker via observeSnapshot.
+        // Reset here so the tracker doesn't fault on the SceneChanged's
+        // own seq (which advances prev's counter one final step).
+        this.seq.reset();
+        this.opts.onSceneChanged?.(frame);
+        return;
+      }
+      case "error": {
+        this.opts.onServerError?.(frame);
+        if (!frame.recoverable) this.close();
+        return;
+      }
+      case "pong":
+        return;
+    }
+  }
+
+  private handleError(_event: Event): void {
+    // The browser does not give us a real reason — `close` will follow.
+  }
+
+  private handleClose(event: CloseEvent): void {
+    this.socket = null;
+    if (!this.active) {
+      this.setStatus("disconnected");
+      return;
+    }
+    if (event.code === 4401 || event.code === 4403 || event.code === 1008) {
+      // Auth-related close codes: not recoverable without operator intervention.
+      this.opts.onTransportError?.(
+        new TransportError(`server closed: ${event.code} ${event.reason}`, false, "AUTH_DENIED"),
+      );
+      this.close();
+      return;
+    }
+    this.scheduleReconnect();
+  }
+
+  private scheduleReconnect(immediate = false): void {
+    if (!this.active) return;
+    this.cancelReconnect();
+    const attempt = (this.schedule.attempt || 0) + 1;
+    const delay = immediate ? 0 : this.schedule.delayFor(attempt);
+    this.setStatus("disconnected");
+    this.reconnectTimer = this.scheduler.setTimeout(() => {
+      this.reconnectTimer = null;
+      void this.openSocket();
+    }, delay);
+  }
+
+  private cancelReconnect(): void {
+    if (this.reconnectTimer) {
+      this.scheduler.clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+
+  private closeSocket(): void {
+    if (this.socket) {
+      try {
+        this.socket.close(1000, "client closing");
+      } catch {
+        // ignore
+      }
+      this.socket = null;
+    }
+  }
+
+  private setStatus(next: ConnectionStatus): void {
+    if (this.status === next) return;
+    this.status = next;
+    this.opts.onStatus?.(next);
+  }
+}
+
+async function resolveToken(token: LumencastToken): Promise<string> {
+  if (typeof token === "string") return token;
+  return await token.fetch();
+}

package/src/types.ts

@@ -0,0 +1,54 @@
+// Public types of @lumencast/runtime — must align with RUNTIME-API.md.
+
+import type { ErrorCode } from "@lumencast/protocol";
+
+export type LumencastMode = "broadcast" | "control" | "test";
+
+export type LumencastStatus = "disconnected" | "connecting" | "live";
+
+export interface LumencastTokenProvider {
+  fetch: () => Promise<string>;
+}
+
+export type LumencastToken = string | LumencastTokenProvider;
+
+export interface LumencastError {
+  code: ErrorCode;
+  message: string;
+  recoverable: boolean;
+}
+
+export interface LumencastMetric {
+  name:
+    | "delta_received"
+    | "delta_applied"
+    | "frame_dropped"
+    | "reconnect"
+    | "snapshot_received"
+    | "scene_changed";
+  [key: string]: unknown;
+}
+
+export interface MountOptions {
+  target: HTMLElement;
+  /** WebSocket URL of the LSDP/1 server (wss://... in production). */
+  serverUrl: string;
+  token: LumencastToken;
+  mode: LumencastMode;
+  /** Required when mode === "test". */
+  testSession?: string;
+  /** Required when mode === "test". */
+  scene?: string;
+  onStatus?: (status: LumencastStatus) => void;
+  onError?: (err: LumencastError) => void;
+  onMetric?: (metric: LumencastMetric) => void;
+}
+
+export interface LumencastHandle {
+  /** Tear down the WS, unmount the React tree, release timers. Idempotent. */
+  disconnect: () => void;
+  /** Swap the auth token without unmounting the React tree. */
+  setToken: (token: LumencastToken) => void;
+}
+
+export type { ErrorCode };