@fabrika/canvas-kernel 0.1.44

package/src/engine/waiter.ts

@@ -0,0 +1,188 @@
+/**
+ * The CLI half of the notification channel: connect to a daemon's wait socket
+ * and block until the host says the wait is over.
+ *
+ * What settles the wait is a host predicate, so one helper covers "feedback
+ * arrived", "screens confirmed" and "a run was requested". The socket factory
+ * is injectable, which is what makes the retry and settle logic testable
+ * without a live daemon.
+ */
+
+/** The slice of `WebSocket` a waiter uses; a real `WebSocket` satisfies it. */
+export interface WaiterSocket {
+  close(): void;
+  onopen: ((event: Event) => void) | null;
+  onmessage: ((event: MessageEvent) => void) | null;
+  onerror: ((event: Event) => void) | null;
+  onclose: ((event: CloseEvent) => void) | null;
+}
+
+/** What a frame means to the waiter; `undefined` means "not mine, keep waiting". */
+export type WaitVerdict<T> =
+  | { type: "settle"; value: T }
+  | { type: "fail"; error: Error }
+  /** Wake the probe — the frame announces state the waiter has to read back. */
+  | { type: "recheck" };
+
+export interface WaitMessages {
+  /** Deadline passed. Default: "Timed out waiting." */
+  timeout?: string;
+  /** Socket closed before the wait settled. Default: "Connection closed before the wait settled." */
+  closed?: string;
+  /** The socket errored. Default: "WebSocket connection failed." */
+  connectionFailed?: string;
+  /**
+   * `createSocket` threw, so no socket ever existed; the factory's own message
+   * is appended after a colon. Default: "Could not create the WebSocket".
+   */
+  socketCreateFailed?: string;
+}
+
+export interface WaitOptions<T> {
+  /** The daemon's wait socket, e.g. `ws://localhost:19400/ws/wait/<topic>`. */
+  url: string;
+  /** Reads a frame; returns how it settles the wait, if at all. */
+  onFrame(frame: unknown): WaitVerdict<T> | undefined;
+  /**
+   * Fast path against server state. Runs before connecting (unless the caller
+   * already did that read — see `alreadyProbed`), again once the socket opens —
+   * closing the race where the event lands between the two — and whenever a
+   * frame asks for a recheck. A probe that rejects is dropped: the socket, not
+   * the probe, is what the wait ultimately hangs on.
+   */
+  probe?(): Promise<{ value: T } | undefined>;
+  /**
+   * The caller has already made the probe's read itself and it came up empty,
+   * so the wait starts at the socket. Set it when that read is the caller's own
+   * error channel — a probe that rejects is dropped here, so a caller that must
+   * report *why* the read failed has to make it before calling. The on-open
+   * re-read still runs; it is what closes the subscribe race.
+   */
+  alreadyProbed?: boolean;
+  createSocket?(url: string): WaiterSocket;
+  /** Deadline for the whole wait, spanning reconnects. */
+  timeoutMs: number;
+  reconnect?: {
+    /** Reconnects after a dropped connection. Default 0. */
+    attempts?: number;
+    /** Delay before a reconnect, capped by the remaining deadline. Default 1000. */
+    delayMs?: number;
+  };
+  messages?: WaitMessages;
+}
+
+/** Why the wait ended without an answer; hosts map these onto their own errors. */
+export type WaitFailure =
+  | "timeout"
+  | "closed"
+  /** The socket was created, then errored. */
+  | "connection-failed"
+  /** `createSocket` threw — nothing was ever connected to. */
+  | "socket-create-failed";
+
+export class WaitError extends Error {
+  constructor(
+    message: string,
+    readonly reason: WaitFailure,
+    readonly retryable: boolean,
+    options?: ErrorOptions,
+  ) {
+    super(message, options);
+    this.name = "WaitError";
+  }
+}
+
+const DEFAULT_MESSAGES: Required<WaitMessages> = {
+  timeout: "Timed out waiting.",
+  closed: "Connection closed before the wait settled.",
+  connectionFailed: "WebSocket connection failed.",
+  socketCreateFailed: "Could not create the WebSocket",
+};
+
+function parseFrame(data: unknown): unknown {
+  if (typeof data !== "string") return undefined;
+  try {
+    return JSON.parse(data);
+  } catch {
+    return undefined;
+  }
+}
+
+function connectAndWait<T>(
+  options: WaitOptions<T>,
+  createSocket: (url: string) => WaiterSocket,
+  messages: Required<WaitMessages>,
+  remainingMs: number,
+): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    let socket: WaiterSocket;
+    try {
+      socket = createSocket(options.url);
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      const message = `${messages.socketCreateFailed}: ${detail}`;
+      reject(new WaitError(message, "socket-create-failed", true, { cause: error }));
+      return;
+    }
+
+    let settled = false;
+    // The value is wrapped so a settling `T` of any shape stays distinguishable.
+    const finish = (outcome: { value: T } | Error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.close();
+      if (outcome instanceof Error) reject(outcome);
+      else resolve(outcome.value);
+    };
+
+    const timer = setTimeout(() => finish(new WaitError(messages.timeout, "timeout", false)), remainingMs);
+
+    const runProbe = () => {
+      if (!options.probe) return;
+      options.probe().then((result) => {
+        if (result) finish(result);
+      }).catch(() => {});
+    };
+
+    socket.onopen = () => runProbe();
+
+    socket.onmessage = (event) => {
+      const frame = parseFrame(event.data);
+      if (frame === undefined) return;
+      const verdict = options.onFrame(frame);
+      if (!verdict) return;
+      if (verdict.type === "settle") finish({ value: verdict.value });
+      else if (verdict.type === "fail") finish(verdict.error);
+      else runProbe();
+    };
+
+    socket.onerror = () => finish(new WaitError(messages.connectionFailed, "connection-failed", true));
+    socket.onclose = () => finish(new WaitError(messages.closed, "closed", true));
+  });
+}
+
+export async function waitForEvent<T>(options: WaitOptions<T>): Promise<T> {
+  const createSocket = options.createSocket ?? ((url: string) => new WebSocket(url));
+  const messages = { ...DEFAULT_MESSAGES, ...options.messages };
+  const attempts = options.reconnect?.attempts ?? 0;
+  const delayMs = options.reconnect?.delayMs ?? 1_000;
+  const deadline = Date.now() + options.timeoutMs;
+
+  if (!options.alreadyProbed) {
+    const known = await options.probe?.().catch(() => undefined);
+    if (known) return known.value;
+  }
+
+  for (let attempt = 0; ; attempt++) {
+    const remainingMs = deadline - Date.now();
+    if (remainingMs <= 0) throw new WaitError(messages.timeout, "timeout", false);
+
+    try {
+      return await connectAndWait(options, createSocket, messages, remainingMs);
+    } catch (error) {
+      if (!(error instanceof WaitError) || !error.retryable || attempt >= attempts) throw error;
+      await Bun.sleep(Math.min(delayMs, Math.max(0, deadline - Date.now())));
+    }
+  }
+}

package/src/engine/watcher.ts

@@ -0,0 +1,84 @@
+import { watch, existsSync, readFileSync, readdirSync } from "fs";
+import { join } from "path";
+import { compileJsx, type CanvasComponents } from "./compiler";
+import type { SessionManager } from "./session";
+
+type BroadcastFn = (sessionId: string) => void;
+
+export interface WatchOptions {
+  /** Scratch dir for recompiles, from `createCanvasPaths()`. */
+  tempDir?: string;
+  /** Host components, same value the push path compiles with — a recompile
+   *  that dropped them would fail on canvases the original push accepted. */
+  components?: CanvasComponents;
+}
+
+const watchers = new Map<string, ReturnType<typeof watch>[]>();
+
+export function watchSession(
+  sessionId: string,
+  sessionManager: SessionManager,
+  broadcast: BroadcastFn,
+  options: WatchOptions = {},
+) {
+  // Close existing watchers for this session
+  unwatchSession(sessionId);
+
+  const session = sessionManager.get(sessionId);
+  if (!session) return;
+
+  const rev = session.currentRevision;
+  const canvasFiles = sessionManager.getRevisionCanvasFiles(sessionId, rev);
+  if (canvasFiles.length === 0) return;
+
+  const fileWatchers: ReturnType<typeof watch>[] = [];
+  const debounceTimers = new Map<string, ReturnType<typeof setTimeout>>();
+
+  for (const filename of canvasFiles) {
+    const filePath = sessionManager.getRevisionJsxPath(sessionId, rev, filename);
+    if (!existsSync(filePath)) continue;
+
+    const watcher = watch(filePath, async (event) => {
+      if (event !== "change") return;
+
+      // Debounce per-file
+      const existing = debounceTimers.get(filename);
+      if (existing) clearTimeout(existing);
+
+      debounceTimers.set(filename, setTimeout(async () => {
+        debounceTimers.delete(filename);
+        try {
+          const jsx = readFileSync(filePath, "utf-8");
+          const result = await compileJsx(jsx, {
+            projectRoot: session.projectRoot,
+            tempDir: options.tempDir,
+            ...(options.components ? { components: options.components } : {}),
+          });
+          if (result.ok) {
+            sessionManager.saveCompiled(sessionId, filename, result.js, rev);
+            broadcast(sessionId);
+          }
+        } catch {}
+      }, 200));
+    });
+
+    fileWatchers.push(watcher);
+  }
+
+  watchers.set(sessionId, fileWatchers);
+}
+
+export function unwatchSession(sessionId: string) {
+  const sessionWatchers = watchers.get(sessionId);
+  if (sessionWatchers) {
+    for (const w of sessionWatchers) w.close();
+    watchers.delete(sessionId);
+  }
+}
+
+export function unwatchAll() {
+  for (const [, sessionWatchers] of watchers) {
+    for (const w of sessionWatchers) w.close();
+  }
+  watchers.clear();
+}

package/src/engine/websocket.ts

@@ -0,0 +1,159 @@
+/**
+ * The canvas vocabulary on top of the generic channel: topic = session id,
+ * `submit` persists feedback, and a waiter is the CLI blocking on one answer,
+ * so a delivery closes it.
+ */
+
+import { browserFrame, createNotificationChannel, type ChannelSocket, type TopicChannel } from "./channel";
+import type { SessionManager, RemoteFeedbackEntry } from "./session";
+
+export type WSData = { type: "browser" | "wait"; sessionId: string };
+
+export interface CanvasSocket extends ChannelSocket {
+  data: WSData;
+}
+
+interface CanvasRenderError {
+  revision: number;
+  filename: string;
+  message: string;
+  stack?: string;
+  componentStack?: string;
+}
+
+interface SubmitFrame {
+  type: "submit";
+  feedback: string;
+}
+
+interface RenderErrorFrame {
+  type: "render-error";
+  error: CanvasRenderError;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isCanvasRenderError(value: unknown): value is CanvasRenderError {
+  return typeof value === "object" && value !== null
+    && "revision" in value && Number.isInteger(value.revision)
+    && "filename" in value && typeof value.filename === "string"
+    && "message" in value && typeof value.message === "string"
+    && (!("stack" in value) || value.stack === undefined || typeof value.stack === "string")
+    && (!("componentStack" in value) || value.componentStack === undefined || typeof value.componentStack === "string");
+}
+
+function isSubmitFrame(value: unknown): value is SubmitFrame {
+  return isRecord(value) && value.type === "submit" && typeof value.feedback === "string";
+}
+
+function isRenderErrorFrame(value: unknown): value is RenderErrorFrame {
+  return isRecord(value) && value.type === "render-error" && isCanvasRenderError(value.error);
+}
+
+export interface WebSocketManagerOptions {
+  /**
+   * Who marks feedback consumed once a waiting client has been handed it.
+   *
+   * `"on-delivery"` (default) clears it in the same step, so the same feedback
+   * can never be delivered twice — right when the waiting client *is* the
+   * consumer. `"external"` leaves it pending for a separate gate to claim
+   * through the consume endpoint, for hosts where delivery and consumption are
+   * different steps.
+   */
+  feedbackConsumption?: "on-delivery" | "external";
+}
+
+export function createWebSocketManager(
+  sessionManager: SessionManager,
+  options: WebSocketManagerOptions = {},
+) {
+  const consumeOnDelivery = (options.feedbackConsumption ?? "on-delivery") === "on-delivery";
+  const pendingRenderErrors = new Map<string, CanvasRenderError>();
+
+  /** Hands a held error to the waiters, if any showed up; the caller announces the departure. */
+  function deliverPendingRenderError(sessionId: string): boolean {
+    const error = pendingRenderErrors.get(sessionId);
+    if (!error) return false;
+    if (!channel.relayToWaiters(sessionId, { type: "render-error", error })) return false;
+    pendingRenderErrors.delete(sessionId);
+    return true;
+  }
+
+  function submit(frame: SubmitFrame, topic: TopicChannel) {
+    const sessionId = topic.topic;
+    const session = sessionManager.get(sessionId);
+    if (!session) return;
+
+    sessionManager.saveFeedback(sessionId, session.currentRevision, frame.feedback);
+    broadcastRevisionUpdate(sessionId);
+    if (!topic.hasWaiter()) return;
+
+    if (consumeOnDelivery) {
+      sessionManager.consumeFeedback(sessionId, session.currentRevision);
+      broadcastRevisionUpdate(sessionId);
+    }
+    topic.relayToWaiters({ type: "submit", feedback: frame.feedback });
+  }
+
+  function renderError(frame: RenderErrorFrame, topic: TopicChannel) {
+    const sessionId = topic.topic;
+    const session = sessionManager.get(sessionId);
+    if (!session) return;
+    if (frame.error.revision !== session.currentRevision) return;
+    if (!session.canvasFiles.includes(frame.error.filename)) return;
+
+    pendingRenderErrors.set(sessionId, frame.error);
+    if (deliverPendingRenderError(sessionId)) topic.broadcastPresence();
+  }
+
+  const channel = createNotificationChannel<CanvasSocket>({
+    roleOf: (socket) => socket.data.type,
+    topicOf: (socket) => socket.data.sessionId,
+    waiterPolicy: "close-on-delivery",
+    presenceFrame: (watching) => ({ type: "watcher-status", watching }),
+    // A render error raised before the CLI watcher connected is held for it.
+    onWaiterOpen: (topic) => { deliverPendingRenderError(topic.topic); },
+    frames: [
+      browserFrame(isSubmitFrame, submit),
+      browserFrame(isRenderErrorFrame, renderError),
+    ],
+  });
+
+  function broadcastPlanUpdate(sessionId: string) {
+    pendingRenderErrors.delete(sessionId);
+    const session = sessionManager.get(sessionId);
+    if (!session) return;
+    channel.broadcast(sessionId, {
+      type: "plan-updated",
+      currentRevision: session.currentRevision,
+      revisions: session.revisions,
+    });
+  }
+
+  function broadcastRevisionUpdate(sessionId: string) {
+    const session = sessionManager.get(sessionId);
+    if (!session) return;
+    channel.broadcast(sessionId, {
+      type: "revision-updated",
+      revisions: session.revisions,
+    });
+  }
+
+  function broadcastRemoteFeedback(sessionId: string, revision: number, entries: RemoteFeedbackEntry[]) {
+    channel.broadcast(sessionId, { type: "remote-feedback", revision, entries });
+  }
+
+  function broadcastWatcherStatus(sessionId: string) {
+    channel.broadcastPresence(sessionId);
+  }
+
+  return {
+    handlers: channel.handlers,
+    broadcastPlanUpdate,
+    broadcastRevisionUpdate,
+    broadcastWatcherStatus,
+    broadcastRemoteFeedback,
+  };
+}