@fabrika/canvas-kernel 0.1.44

package/src/client/useRegionAnnotation.tsx

@@ -0,0 +1,188 @@
+import React, { useEffect, useRef, useState } from "react";
+import { useAnnotations } from "./AnnotationProvider";
+import { AnnotationCreatePopover } from "./Popover";
+import {
+  applyRegionStyle,
+  createRegionOverlay,
+  describeRegion,
+  isDrawableRegion,
+  regionBetween,
+  regionPointIn,
+  regionTarget,
+  REGION_HOST_ATTR,
+  type RegionPoint,
+  type RegionShape,
+} from "./regionTarget";
+import { generateAnnotationId } from "./utils";
+
+interface UseRegionAnnotationOptions {
+  /** Container holding the image blocks a region can be drawn on. */
+  containerRef: React.RefObject<HTMLElement | null>;
+  /** Re-registers the drawing listener when the canvas remounts. */
+  restoreKey: unknown;
+  /** Shape a new region takes. */
+  shape?: RegionShape;
+  /** Canvas file the created annotation belongs to. */
+  canvasFile?: string;
+  /** Scroll container for popover positioning. */
+  scrollContainer?: HTMLElement | null;
+}
+
+/** One region being drawn out, held outside React: the box follows the pointer
+ *  at pointer rate, which is no reason to re-render the canvas. */
+interface RegionDrag {
+  pointerId: number;
+  host: HTMLElement;
+  src: string;
+  start: RegionPoint;
+  shape: RegionShape;
+  overlay: HTMLElement;
+  id: string;
+}
+
+/** A region drawn but not yet given a note. */
+interface PendingRegion {
+  overlay: HTMLElement;
+  id: string;
+  snippet: string;
+  label: string;
+}
+
+/**
+ * Drag on an image block to annotate one part of it.
+ *
+ * An image carries no text, so a plain drag over one is unambiguous and takes
+ * no modifier: the selection this would compete with cannot start there. It
+ * still has to stay off the two things that already live on an image block —
+ * the whole-image comment button and any region already drawn.
+ */
+export function useRegionAnnotation(options: UseRegionAnnotationOptions) {
+  const { containerRef, restoreKey, shape = "rect", canvasFile, scrollContainer } = options;
+  const { addAnnotationWithId } = useAnnotations();
+
+  const [pending, setPending] = useState<PendingRegion | null>(null);
+  const [isDrawing, setIsDrawing] = useState(false);
+
+  const addAnnotationRef = useRef(addAnnotationWithId);
+  addAnnotationRef.current = addAnnotationWithId;
+  const canvasFileRef = useRef(canvasFile);
+  canvasFileRef.current = canvasFile;
+  const shapeRef = useRef(shape);
+  shapeRef.current = shape;
+
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+
+    let drag: RegionDrag | null = null;
+
+    /** Where the pointer is, on the region grid of `host`. */
+    function pointIn(host: HTMLElement, e: PointerEvent): RegionPoint | null {
+      const rect = host.getBoundingClientRect();
+      return regionPointIn(rect, e.clientX - rect.left, e.clientY - rect.top);
+    }
+
+    function endDrag() {
+      if (!drag) return;
+      const { host, pointerId } = drag;
+      if (host.hasPointerCapture(pointerId)) host.releasePointerCapture(pointerId);
+      host.removeEventListener("pointermove", onMove);
+      host.removeEventListener("pointerup", onUp);
+      host.removeEventListener("pointercancel", onCancel);
+      drag = null;
+      setIsDrawing(false);
+    }
+
+    function onDown(e: PointerEvent) {
+      if (drag || e.button !== 0) return;
+      const target = e.target;
+      if (!(target instanceof Element)) return;
+      // The comment button mints the whole-image annotation, and a region
+      // already drawn is its own click target; neither starts a new one.
+      if (target.closest("[data-block-comment-btn]")) return;
+      if (target.closest("[data-annotation-id]")) return;
+
+      const host = target.closest(`[${REGION_HOST_ATTR}]`);
+      if (!(host instanceof HTMLElement) || !container?.contains(host)) return;
+      const src = host.closest("[data-md='image']")?.getAttribute("data-md-src");
+      if (!src) return;
+      const start = pointIn(host, e);
+      if (!start) return;
+
+      // Without this the browser starts its own image drag instead.
+      e.preventDefault();
+      host.setPointerCapture(e.pointerId);
+
+      const id = generateAnnotationId();
+      const overlay = createRegionOverlay({ ...start, w: 0, h: 0 }, shapeRef.current, id);
+      overlay.classList.add("ann-region-draft");
+      host.appendChild(overlay);
+
+      drag = { pointerId: e.pointerId, host, src, start, shape: shapeRef.current, overlay, id };
+      host.addEventListener("pointermove", onMove);
+      host.addEventListener("pointerup", onUp);
+      host.addEventListener("pointercancel", onCancel);
+      setIsDrawing(true);
+    }
+
+    function onMove(e: PointerEvent) {
+      if (!drag || drag.pointerId !== e.pointerId) return;
+      const point = pointIn(drag.host, e);
+      if (!point) return;
+      applyRegionStyle(drag.overlay, regionBetween(drag.start, point));
+    }
+
+    function onUp(e: PointerEvent) {
+      if (!drag || drag.pointerId !== e.pointerId) return;
+      const { overlay, id, src, shape: drawnShape } = drag;
+      const point = pointIn(drag.host, e) ?? drag.start;
+      const box = regionBetween(drag.start, point);
+      endDrag();
+
+      if (!isDrawableRegion(box)) {
+        overlay.remove();
+        return;
+      }
+      applyRegionStyle(overlay, box);
+      const locator = { src, shape: drawnShape, ...box };
+      setPending({ overlay, id, snippet: regionTarget.format(locator), label: describeRegion(locator) });
+    }
+
+    function onCancel(e: PointerEvent) {
+      if (!drag || drag.pointerId !== e.pointerId) return;
+      drag.overlay.remove();
+      endDrag();
+    }
+
+    container.addEventListener("pointerdown", onDown);
+    return () => {
+      container.removeEventListener("pointerdown", onDown);
+      if (drag) {
+        drag.overlay.remove();
+        endDrag();
+      }
+    };
+  }, [restoreKey]);
+
+  const popovers = pending ? (
+    <AnnotationCreatePopover
+      anchorEl={pending.overlay}
+      scrollContainer={scrollContainer}
+      snippet={pending.label}
+      truncateAt={80}
+      onAdd={(note, images) => {
+        // The overlay already carries the annotation's real id, so committing
+        // is only dropping the draft look — no redraw, no flicker.
+        pending.overlay.classList.remove("ann-region-draft");
+        addAnnotationRef.current(pending.id, pending.snippet, note, undefined, undefined, images, canvasFileRef.current);
+        setPending(null);
+      }}
+      onCancel={() => {
+        pending.overlay.remove();
+        setPending(null);
+      }}
+    />
+  ) : null;
+
+  return { popovers, isDrawing, isPopoverOpen: !!pending };
+}

package/src/client/useTextAnnotation.tsx

@@ -0,0 +1,194 @@
+import React, { useEffect, useState, useRef, useCallback } from "react";
+import type { AnnotationContext, Annotation } from "./AnnotationProvider";
+import { useAnnotations } from "./AnnotationProvider";
+import { wrapRangeWithMark, updateAllMarkStates, renameMarkId, unwrapMarks, rangeIndexText } from "./highlightRange";
+import { restoreAnnotationTargets } from "./annotationDom";
+import { AnnotationCreatePopover, AnnotationEditPopover } from "./Popover";
+import { generateAnnotationId } from "./utils";
+
+interface UseTextAnnotationOptions {
+  /** Ref to the container element where text can be selected and marks are placed */
+  containerRef: React.RefObject<HTMLElement | null>;
+  /** Trigger for mark restoration — when this value changes, marks are restored */
+  restoreKey: unknown;
+  /** Subset of annotations to restore in this container */
+  restoreAnnotations: Annotation[];
+  /** Build AnnotationContext from a selection Range */
+  extractContext: (range: Range) => AnnotationContext | undefined;
+  /** Optional filePath to associate with created annotations */
+  filePath?: string;
+  /** Optional canvasFile to associate with created annotations */
+  canvasFile?: string;
+  /** Scroll container for popover positioning */
+  scrollContainer?: HTMLElement | null;
+}
+
+export function useTextAnnotation(options: UseTextAnnotationOptions) {
+  const { containerRef, restoreKey, restoreAnnotations, extractContext, filePath, canvasFile, scrollContainer } = options;
+  const { annotations: allAnnotations, addAnnotationWithId, removeAnnotation, updateAnnotation, addAnnotationImage, removeAnnotationImage, activeAnnotationId, setActiveAnnotationId } = useAnnotations();
+
+  const [editPopover, setEditPopover] = useState<{ anchorEl: HTMLElement; annId: string } | null>(null);
+  const [createPopover, setCreatePopover] = useState<{ anchorEl: HTMLElement; tempId: string; snippet: string; ctx?: AnnotationContext } | null>(null);
+
+  // Refs for stable handlers (registered with empty or minimal deps)
+  const extractContextRef = useRef(extractContext);
+  extractContextRef.current = extractContext;
+  const filePathRef = useRef(filePath);
+  filePathRef.current = filePath;
+  const canvasFileRef = useRef(canvasFile);
+  canvasFileRef.current = canvasFile;
+  const addAnnotationRef = useRef(addAnnotationWithId);
+  addAnnotationRef.current = addAnnotationWithId;
+  const activeAnnotationIdRef = useRef(activeAnnotationId);
+  activeAnnotationIdRef.current = activeAnnotationId;
+  const setActiveAnnotationIdRef = useRef(setActiveAnnotationId);
+  setActiveAnnotationIdRef.current = setActiveAnnotationId;
+
+  // Decoration restoration after content renders or annotations change. Not
+  // only marks: every locator strategy puts its own decoration back here, so a
+  // host that mounts this hook gets region overlays restored too.
+  const restoreAnnotationsLen = restoreAnnotations.length;
+  useEffect(() => {
+    if (!containerRef.current) return;
+    const timer = setTimeout(() => {
+      if (containerRef.current) {
+        restoreAnnotationTargets(containerRef.current, restoreAnnotations);
+      }
+    }, 50);
+    return () => clearTimeout(timer);
+  }, [restoreKey, restoreAnnotationsLen]);
+
+  // Mark active state tracking
+  const prevActiveRef = useRef<string | null>(null);
+  useEffect(() => {
+    updateAllMarkStates(activeAnnotationId, prevActiveRef.current);
+    prevActiveRef.current = activeAnnotationId;
+  }, [activeAnnotationId]);
+
+  // Mark click/hover/out handlers on the container (uses refs to avoid re-registration on every hover)
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+
+    const handleClick = (e: MouseEvent) => {
+      const mark = (e.target as HTMLElement).closest("[data-annotation-id]") as HTMLElement | null;
+      if (!mark) return;
+      e.stopPropagation();
+      const annId = mark.getAttribute("data-annotation-id")!;
+      if (annId === activeAnnotationIdRef.current) {
+        setEditPopover({ anchorEl: mark, annId });
+      } else {
+        setActiveAnnotationIdRef.current(annId);
+      }
+    };
+
+    const handleMouseOver = (e: MouseEvent) => {
+      const mark = (e.target as HTMLElement).closest("[data-annotation-id]") as HTMLElement | null;
+      if (mark) setActiveAnnotationIdRef.current(mark.getAttribute("data-annotation-id")!);
+    };
+
+    const handleMouseOut = (e: MouseEvent) => {
+      const mark = (e.target as HTMLElement).closest("[data-annotation-id]");
+      const related = (e.relatedTarget as HTMLElement | null)?.closest?.("[data-annotation-id]");
+      if (mark && !related && !document.getElementById("ann-inline-popover")) setActiveAnnotationIdRef.current(null);
+    };
+
+    container.addEventListener("click", handleClick);
+    container.addEventListener("mouseover", handleMouseOver);
+    container.addEventListener("mouseout", handleMouseOut);
+    return () => {
+      container.removeEventListener("click", handleClick);
+      container.removeEventListener("mouseover", handleMouseOver);
+      container.removeEventListener("mouseout", handleMouseOut);
+    };
+  }, [restoreKey]);
+
+  // Document-level mouseup for text selection → mark → popover
+  useEffect(() => {
+    const handler = () => handleMouseUp();
+    document.addEventListener("mouseup", handler);
+    return () => document.removeEventListener("mouseup", handler);
+  }, []);
+
+  const handleMouseUp = useCallback(() => {
+    const sel = window.getSelection();
+    if (!sel || sel.isCollapsed || !sel.toString().trim()) return;
+    if (!containerRef.current) return;
+    const range = sel.getRangeAt(0);
+    if (!containerRef.current.contains(range.startContainer)) return;
+    if ((range.startContainer.parentElement as HTMLElement)?.closest?.("[data-annotation-id]")) return;
+    // Not sel.toString(): a selection reaching over an existing annotation
+    // carries text the index does not hold, and a snippet naming that text can
+    // never be restored.
+    const snippet = rangeIndexText(range).trim();
+    if (snippet.length < 2) return;
+
+    // Extract context before wrapping disturbs the DOM
+    const ctx = extractContextRef.current(range);
+    const savedRange = range.cloneRange();
+    const tempId = `__pending_${Date.now()}`;
+    try { wrapRangeWithMark(savedRange, tempId); } catch {}
+    window.getSelection()?.removeAllRanges();
+
+    const marks = document.querySelectorAll(`[data-annotation-id="${tempId}"]`);
+    const lastMark = marks[marks.length - 1] as HTMLElement | undefined;
+    if (!lastMark) return;
+
+    setCreatePopover({ anchorEl: lastMark, tempId, snippet, ctx });
+  }, []);
+
+  const openCreatePopover = useCallback((anchorEl: HTMLElement, tempId: string, snippet: string, ctx?: AnnotationContext) => {
+    setCreatePopover({ anchorEl, tempId, snippet, ctx });
+  }, []);
+
+  const popovers = (
+    <>
+      {editPopover && (() => {
+        const ann = allAnnotations.find((a) => a.id === editPopover.annId);
+        if (!ann) return null;
+        return (
+          <AnnotationEditPopover
+            anchorEl={editPopover.anchorEl}
+            scrollContainer={scrollContainer}
+            initialNote={ann.note}
+            initialImages={ann.images}
+            onUpdate={(note, images) => {
+              updateAnnotation(editPopover.annId, note);
+              // Sync images
+              const current = ann.images || [];
+              for (const img of images) {
+                if (!current.includes(img)) addAnnotationImage(editPopover.annId, img);
+              }
+              for (const img of current) {
+                if (!images.includes(img)) removeAnnotationImage(editPopover.annId, img);
+              }
+            }}
+            onDelete={() => { removeAnnotation(editPopover.annId); setActiveAnnotationId(null); }}
+            onClose={() => setEditPopover(null)}
+          />
+        );
+      })()}
+
+      {createPopover && (
+        <AnnotationCreatePopover
+          anchorEl={createPopover.anchorEl}
+          scrollContainer={scrollContainer}
+          snippet={createPopover.snippet}
+          truncateAt={80}
+          onAdd={(note, images) => {
+            const id = generateAnnotationId();
+            renameMarkId(createPopover.tempId, id);
+            addAnnotationRef.current(id, createPopover.snippet, note, filePathRef.current, createPopover.ctx, images, canvasFileRef.current);
+            setCreatePopover(null);
+          }}
+          onCancel={() => {
+            unwrapMarks(createPopover.tempId);
+            setCreatePopover(null);
+          }}
+        />
+      )}
+    </>
+  );
+
+  return { popovers, openCreatePopover, isPopoverOpen: !!(editPopover || createPopover) };
+}

package/src/client/utils.ts

@@ -0,0 +1,33 @@
+/** Sentinel filePath for annotations on the agent response banner */
+export const RESPONSE_ANNOTATION_PATH = "__agent-response__";
+
+/**
+ * The file this annotation lives in, or undefined if it lives in no file.
+ * Response annotations ride in the same field under a sentinel, so a bare
+ * `if (ann.filePath)` opens a file tab for a path that is not one.
+ */
+export function fileAnnotationPath(ann: { filePath?: string }): string | undefined {
+  return ann.filePath && ann.filePath !== RESPONSE_ANNOTATION_PATH ? ann.filePath : undefined;
+}
+
+/**
+ * Whether the attach-image affordances are drawn at all.
+ *
+ * The button, the paste handler and the drop zone all end in one POST to the
+ * host's upload endpoint, so a host without one gets none of the three instead
+ * of controls that fail silently.
+ */
+export function hostAcceptsUploads(host: { uploadUrl: (() => string) | null }): boolean {
+  return host.uploadUrl !== null;
+}
+
+/** Generate a unique annotation ID */
+export function generateAnnotationId(): string {
+  return `ann-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+}
+
+/** Auto-resize a textarea to fit its content */
+export function autoResizeTextarea(el: HTMLTextAreaElement, minHeight?: number) {
+  el.style.height = "auto";
+  el.style.height = (minHeight ? Math.max(minHeight, el.scrollHeight) : el.scrollHeight) + "px";
+}

package/src/engine/channel.ts

@@ -0,0 +1,278 @@
+/**
+ * The WebSocket notification channel: a two-role socket registry keyed by an
+ * opaque topic string.
+ *
+ * The kernel owns the plumbing — who is registered under which topic, how a
+ * message reaches browsers or waiters, when a waiter is announced as present,
+ * and the ping/pong sweep that evicts dead waiters. It owns no vocabulary: the
+ * host supplies the frames, decides what a frame does, and decides whether a
+ * relayed frame closes the waiters that received it.
+ *
+ * Two hosts map onto it today:
+ *
+ * - agent-canvas (`engine/websocket.ts`) — topic = session id, waiter policy
+ *   `close-on-delivery` (the CLI's `wait` socket is satisfied by one frame),
+ *   frames `submit` / `render-error`, presence frame `watcher-status`.
+ * - obrazovka — topic = Figma file key, waiter policy `keep-open` (a `--page`
+ *   waiter must survive a relay meant for a different page and filter frames
+ *   client-side), frames `confirm-screens` / `submit` registered by the host
+ *   plus server-initiated relays `run` / `feedback`, presence frame `presence`.
+ */
+
+export type ChannelRole = "browser" | "wait";
+
+/** The minimum a host socket must offer; `Bun.ServerWebSocket` satisfies it. */
+export interface ChannelSocket {
+  send(message: string): unknown;
+  close(): void;
+  ping(): unknown;
+}
+
+export interface RelayOptions {
+  /**
+   * Close every waiter the message was handed to and drop the topic's waiter
+   * set. Defaults to the channel's `waiterPolicy`.
+   */
+  close?: boolean;
+}
+
+/** Channel operations bound to one topic. */
+export interface TopicChannel {
+  readonly topic: string;
+  /** Send to every browser on the topic. */
+  broadcast(message: unknown): void;
+  /** Send to every waiter on the topic; `false` when there was none. */
+  relayToWaiters(message: unknown, options?: RelayOptions): boolean;
+  hasWaiter(): boolean;
+  /** Announce current waiter presence to the topic's browsers. */
+  broadcastPresence(): void;
+}
+
+export interface BrowserFrameHandler {
+  /** The bound work when the frame is this handler's, `undefined` otherwise. */
+  bind(frame: unknown, channel: TopicChannel): (() => void | Promise<void>) | undefined;
+}
+
+/**
+ * Register one frame of a host's vocabulary. Matching is synchronous so the
+ * socket's `message` handler stays synchronous; handling may be async.
+ */
+export function browserFrame<T>(
+  match: (frame: unknown) => frame is T,
+  handle: (frame: T, channel: TopicChannel) => void | Promise<void>,
+): BrowserFrameHandler {
+  return {
+    bind: (frame, channel) => (match(frame) ? () => handle(frame, channel) : undefined),
+  };
+}
+
+export interface NotificationChannelOptions<S extends ChannelSocket> {
+  /** Which registry a socket belongs to. */
+  roleOf(socket: S): ChannelRole;
+  /** The socket's routing key — a canvas session id, a Figma file key, … */
+  topicOf(socket: S): string;
+  /** The host's browser-frame vocabulary, tried in order; first match wins. */
+  frames?: readonly BrowserFrameHandler[];
+  /** Builds the presence frame. Presence is not announced when omitted. */
+  presenceFrame?(hasWaiter: boolean, topic: string): unknown;
+  /** What a relay does to the waiters it reached. Default `"keep-open"`. */
+  waiterPolicy?: "close-on-delivery" | "keep-open";
+  /**
+   * Runs after a waiter is registered and before presence is announced, so a
+   * host that buffers events for an absent waiter can flush them here.
+   */
+  onWaiterOpen?(channel: TopicChannel): void;
+  /** Frame handler failures. Dropped when omitted. */
+  onError?(error: unknown): void;
+  /** Liveness sweep period; `false` leaves the sweep to the host. */
+  pingIntervalMs?: number | false;
+}
+
+export interface NotificationChannel<S extends ChannelSocket> {
+  handlers: {
+    open(socket: S): void;
+    message(socket: S, message: string | Buffer): void;
+    pong(socket: S): void;
+    close(socket: S): void;
+  };
+  broadcast(topic: string, message: unknown): void;
+  relayToWaiters(topic: string, message: unknown, options?: RelayOptions): boolean;
+  hasWaiter(topic: string): boolean;
+  broadcastPresence(topic: string): void;
+  /** The topic-bound view handed to frame handlers. */
+  topic(topic: string): TopicChannel;
+  /** One liveness sweep — ping live waiters, evict the ones that never ponged. */
+  pingWaiters(): void;
+  /** Stop the liveness timer. */
+  stop(): void;
+}
+
+const DEFAULT_PING_INTERVAL_MS = 5_000;
+
+function parseFrame(message: string | Buffer): unknown {
+  const text = typeof message === "string" ? message : new TextDecoder().decode(message);
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+export function createNotificationChannel<S extends ChannelSocket>(
+  options: NotificationChannelOptions<S>,
+): NotificationChannel<S> {
+  const { roleOf, topicOf } = options;
+  const frames = options.frames ?? [];
+  const closeOnDelivery = (options.waiterPolicy ?? "keep-open") === "close-on-delivery";
+  const browserSockets = new Map<string, Set<S>>();
+  const waitSockets = new Map<string, Set<S>>();
+  const pongReceived = new WeakSet<S>();
+
+  function registry(role: ChannelRole): Map<string, Set<S>> {
+    return role === "browser" ? browserSockets : waitSockets;
+  }
+
+  function hasWaiter(topic: string): boolean {
+    return (waitSockets.get(topic)?.size ?? 0) > 0;
+  }
+
+  function broadcast(topic: string, message: unknown): void {
+    const sockets = browserSockets.get(topic);
+    if (!sockets || sockets.size === 0) return;
+    const payload = JSON.stringify(message);
+    for (const socket of sockets) socket.send(payload);
+  }
+
+  function presencePayload(topic: string): string | undefined {
+    if (!options.presenceFrame) return undefined;
+    return JSON.stringify(options.presenceFrame(hasWaiter(topic), topic));
+  }
+
+  function broadcastPresence(topic: string): void {
+    const payload = presencePayload(topic);
+    if (payload === undefined) return;
+    const sockets = browserSockets.get(topic);
+    if (!sockets) return;
+    for (const socket of sockets) socket.send(payload);
+  }
+
+  function relayToWaiters(topic: string, message: unknown, relay: RelayOptions = {}): boolean {
+    const sockets = waitSockets.get(topic);
+    if (!sockets || sockets.size === 0) return false;
+    const close = relay.close ?? closeOnDelivery;
+    if (close) waitSockets.delete(topic);
+    const payload = JSON.stringify(message);
+    for (const socket of sockets) {
+      socket.send(payload);
+      if (close) socket.close();
+    }
+    return true;
+  }
+
+  function topicChannel(topic: string): TopicChannel {
+    return {
+      topic,
+      broadcast: (message) => broadcast(topic, message),
+      relayToWaiters: (message, relay) => relayToWaiters(topic, message, relay),
+      hasWaiter: () => hasWaiter(topic),
+      broadcastPresence: () => broadcastPresence(topic),
+    };
+  }
+
+  function reportError(error: unknown): void {
+    options.onError?.(error);
+  }
+
+  function dropWaiter(topic: string, socket: S): void {
+    const sockets = waitSockets.get(topic);
+    if (sockets) {
+      sockets.delete(socket);
+      if (sockets.size === 0) waitSockets.delete(topic);
+    }
+    try { socket.close(); } catch {}
+    broadcastPresence(topic);
+  }
+
+  // A dead socket never fires `close`, so presence would stay stuck on `true`
+  // until the daemon restarts — sweep for the missing pong instead.
+  function pingWaiters(): void {
+    for (const [topic, sockets] of waitSockets) {
+      for (const socket of sockets) {
+        if (!pongReceived.has(socket)) {
+          dropWaiter(topic, socket);
+          continue;
+        }
+        pongReceived.delete(socket);
+        try { socket.ping(); } catch { dropWaiter(topic, socket); }
+      }
+    }
+  }
+
+  const interval = options.pingIntervalMs === false
+    ? undefined
+    : setInterval(pingWaiters, options.pingIntervalMs ?? DEFAULT_PING_INTERVAL_MS);
+  interval?.unref();
+
+  const handlers = {
+    open(socket: S): void {
+      const topic = topicOf(socket);
+      const role = roleOf(socket);
+      const sockets = registry(role).get(topic) ?? new Set<S>();
+      sockets.add(socket);
+      registry(role).set(topic, sockets);
+
+      if (role === "browser") {
+        const payload = presencePayload(topic);
+        if (payload !== undefined) socket.send(payload);
+        return;
+      }
+      pongReceived.add(socket); // free pass on the first sweep
+      options.onWaiterOpen?.(topicChannel(topic));
+      broadcastPresence(topic);
+    },
+
+    message(socket: S, message: string | Buffer): void {
+      if (roleOf(socket) !== "browser") return;
+      const frame = parseFrame(message);
+      if (frame === undefined) return;
+      const channel = topicChannel(topicOf(socket));
+      for (const handler of frames) {
+        const run = handler.bind(frame, channel);
+        if (!run) continue;
+        try {
+          const result = run();
+          if (result instanceof Promise) result.catch(reportError);
+        } catch (error) {
+          reportError(error);
+        }
+        return;
+      }
+    },
+
+    pong(socket: S): void {
+      if (roleOf(socket) === "wait") pongReceived.add(socket);
+    },
+
+    close(socket: S): void {
+      const topic = topicOf(socket);
+      const role = roleOf(socket);
+      const sockets = registry(role).get(topic);
+      sockets?.delete(socket);
+      if (sockets && sockets.size === 0) registry(role).delete(topic);
+      if (role === "wait") broadcastPresence(topic);
+    },
+  };
+
+  return {
+    handlers,
+    broadcast,
+    relayToWaiters,
+    hasWaiter,
+    broadcastPresence,
+    topic: topicChannel,
+    pingWaiters,
+    stop() {
+      if (interval) clearInterval(interval);
+    },
+  };
+}