@blueshed/railroad 0.4.0 → 0.5.0

package/.claude/skills/railroad/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: railroad
-description: "Railroad — micro reactive UI framework for Bun. Use when writing JSX components with signals, routes, when(), list(), or importing @blueshed/railroad."
+description: "Railroad — micro reactive UI framework for Bun. Use when writing JSX components with signals, routes, when(), list(), delta-doc, or importing @blueshed/railroad."
 ---
 
 Micro reactive UI framework for Bun. ~900 lines, zero dependencies, real DOM.
 
 **Read the source files for full API detail** — each has a JSDoc header:
-`signals.ts` · `jsx.ts` · `routes.ts` · `shared.ts` · `logger.ts`
+`signals.ts` · `jsx.ts` · `routes.ts` · `shared.ts` · `logger.ts` · `delta.ts` · `delta-server.ts` · `delta-client.ts`
 
 ## Setup
 
@@ -52,6 +52,45 @@ function SitesLayout() {
 }
 ```
 
+## Delta-doc
+
+Real-time JSON document sync over WebSocket. Server persists to files, client gets reactive signals.
+
+**Read source for full API:** `delta.ts` · `delta-server.ts` · `delta-client.ts`
+
+```ts
+// Server — register docs and methods
+import { createWs, registerDoc, registerMethod } from "@blueshed/railroad/delta-server";
+
+const ws = createWs();
+await registerDoc<Message>(ws, "message", { file: "./data/message.json", empty: { message: "" } });
+registerMethod(ws, "status", () => ({ bun: Bun.version }));
+
+const server = Bun.serve({ routes: { "/ws": ws.upgrade }, websocket: ws.websocket });
+ws.setServer(server);
+```
+
+```tsx
+// Client — open docs as reactive signals
+import { provide } from "@blueshed/railroad";
+import { connectWs, WS, openDoc, call } from "@blueshed/railroad/delta-client";
+
+provide(WS, connectWs("/ws"));
+
+const message = openDoc<Message>("message");
+effect(() => console.log(message.data.get()));
+message.send([{ op: "replace", path: "/message", value: "hello" }]);
+
+const status = await call<Status>("status");
+```
+
+**Delta ops** use JSON Pointer paths:
+- `{ op: "replace", path: "/field", value: "new" }` — set
+- `{ op: "add", path: "/items/-", value: item }` — append to array
+- `{ op: "remove", path: "/items/0" }` — delete by index
+
+Multiple ops in one `send()` are atomic.
+
 ## Anti-Patterns
 
 1. **No React.** No useState, useEffect, hooks, lifecycle methods, or react imports.

package/delta-client.ts

@@ -0,0 +1,246 @@
+/**
+ * Delta Client — WebSocket client + reactive document sync for the browser.
+ *
+ * Provides the client half of the delta-doc system:
+ *   - connectWs()  — reconnecting WebSocket with request/response and notifications
+ *   - openDoc()    — open a persisted document as a reactive signal
+ *   - call()       — invoke a stateless RPC method
+ *
+ * Usage:
+ *   import { connectWs, openDoc, call, WS } from "@blueshed/railroad/delta-client";
+ *   import { provide } from "@blueshed/railroad/shared";
+ *
+ *   provide(WS, connectWs("/ws"));
+ *
+ *   const message = openDoc<Message>("message");
+ *   effect(() => console.log(message.data.get()));
+ *   message.send([{ op: "replace", path: "/message", value: "hello" }]);
+ *
+ *   const status = await call<Status>("status");
+ */
+import { signal, createLogger } from "./index";
+import { key, inject } from "./shared";
+import { applyOps, type DeltaOp } from "./delta";
+
+export type { DeltaOp } from "./delta";
+
+// ---------------------------------------------------------------------------
+// Reconnecting WebSocket
+// ---------------------------------------------------------------------------
+
+function reconnectingWebSocket(url: string): WebSocket {
+  let ws!: WebSocket;
+  const proxy = new EventTarget();
+  let backoff = 500;
+
+  function connect() {
+    ws = new WebSocket(url);
+    ws.addEventListener("open", () => {
+      backoff = 500;
+      proxy.dispatchEvent(new Event("open"));
+    });
+    ws.addEventListener("message", (e: MessageEvent) => {
+      proxy.dispatchEvent(new MessageEvent("message", { data: e.data }));
+    });
+    ws.addEventListener("close", () => {
+      proxy.dispatchEvent(new Event("close"));
+      setTimeout(connect, (backoff = Math.min(backoff * 2, 30_000)));
+    });
+    ws.addEventListener("error", () => {
+      proxy.dispatchEvent(new Event("error"));
+    });
+  }
+
+  (proxy as any).send = (data: string) => {
+    if (ws.readyState === WebSocket.OPEN) ws.send(data);
+  };
+
+  Object.defineProperty(proxy, "readyState", {
+    get: () => ws.readyState,
+  });
+
+  connect();
+  return proxy as unknown as WebSocket;
+}
+
+// ---------------------------------------------------------------------------
+// WebSocket client
+// ---------------------------------------------------------------------------
+
+export type NotifyHandler = (msg: any) => void;
+
+export interface WsClient {
+  connected: ReturnType<typeof signal<boolean>>;
+  send(msg: any): Promise<any>;
+  on(event: string, handler: NotifyHandler): () => void;
+}
+
+export const WS = key<WsClient>("ws");
+
+/** Connect to a delta-server WebSocket endpoint. */
+export function connectWs(
+  wsPath: string = "/ws",
+  opts?: { clientId?: string },
+): WsClient {
+  const log = createLogger("[ws]");
+  const proto = location.protocol === "https:" ? "wss:" : "ws:";
+  const query = opts?.clientId ? `?clientId=${opts.clientId}` : "";
+  const connected = signal(false);
+  const ws = reconnectingWebSocket(
+    `${proto}//${location.host}${wsPath}${query}`,
+  );
+  const pending = new Map<
+    number,
+    { resolve: (v: any) => void; reject: (e: any) => void }
+  >();
+  const listeners = new Map<string, Set<NotifyHandler>>();
+  let nextId = 1;
+  let readyResolve: () => void;
+  let ready = new Promise<void>((r) => {
+    readyResolve = r;
+  });
+
+  ws.addEventListener("open", () => {
+    log.info("connected");
+    connected.set(true);
+    readyResolve();
+    listeners.get("open")?.forEach((fn) => fn({}));
+  });
+
+  ws.addEventListener("close", () => {
+    log.info("disconnected");
+    connected.set(false);
+    ready = new Promise<void>((r) => {
+      readyResolve = r;
+    });
+    listeners.get("close")?.forEach((fn) => fn({}));
+  });
+
+  ws.addEventListener(
+    "message",
+    ((ev: MessageEvent) => {
+      const msg = JSON.parse(ev.data);
+      if (msg.id != null && pending.has(msg.id)) {
+        const { resolve, reject } = pending.get(msg.id)!;
+        pending.delete(msg.id);
+        if (msg.error) {
+          log.error(`#${msg.id} error: ${msg.error.message}`);
+          reject(msg.error);
+        } else {
+          log.debug(`#${msg.id} ack`);
+          resolve(msg.result);
+        }
+      } else {
+        log.debug(`notify ${JSON.stringify(msg).slice(0, 80)}`);
+        listeners.get("message")?.forEach((fn) => fn(msg));
+      }
+    }) as EventListener,
+  );
+
+  return {
+    connected,
+    async send(msg: any): Promise<any> {
+      await ready;
+      return new Promise((resolve, reject) => {
+        const id = nextId++;
+        pending.set(id, { resolve, reject });
+        log.debug(`#${id} ${msg.action} ${msg.doc ?? msg.method ?? ""}`);
+        ws.send(JSON.stringify({ ...msg, id }));
+      });
+    },
+    on(event: string, handler: NotifyHandler): () => void {
+      if (!listeners.has(event)) listeners.set(event, new Set());
+      listeners.get(event)!.add(handler);
+      return () => listeners.get(event)!.delete(handler);
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Document — reactive signal backed by a server-side delta-doc
+// ---------------------------------------------------------------------------
+
+export interface Doc<T> {
+  data: ReturnType<typeof signal<T | null>>;
+  dataVersion: ReturnType<typeof signal<number>>;
+  ready: Promise<void>;
+  send(ops: DeltaOp[]): Promise<any>;
+}
+
+const log = createLogger("[doc]");
+const openDocs = new Map<
+  string,
+  { data: ReturnType<typeof signal<any>>; dataVersion: ReturnType<typeof signal<number>> }
+>();
+
+/** Lazily resolve the WS client — deferred so openDoc can be called at module level. */
+let _ws: WsClient | null = null;
+function ws(): WsClient {
+  if (!_ws) {
+    _ws = inject(WS);
+
+    _ws.on("open", () => {
+      for (const [name, entry] of openDocs) {
+        _ws!.send({ action: "open", doc: name }).then((state) => {
+          entry.data.set(state);
+          entry.dataVersion.set(entry.dataVersion.peek() + 1);
+        });
+      }
+    });
+
+    _ws.on("message", (msg) => {
+      if (msg.doc && msg.ops) {
+        const entry = openDocs.get(msg.doc);
+        if (entry) {
+          const current = entry.data.peek();
+          if (current) {
+            const updated = structuredClone(current);
+            applyOps(updated, msg.ops);
+            entry.data.set(updated);
+            entry.dataVersion.set(entry.dataVersion.peek() + 1);
+          }
+        }
+      }
+    });
+  }
+  return _ws;
+}
+
+/** Open a persisted doc as a reactive signal. Safe to call at module level. */
+export function openDoc<T>(name: string): Doc<T> {
+  const data = signal<T | null>(null);
+  const dataVersion = signal(0);
+  openDocs.set(name, { data, dataVersion });
+
+  let readyResolve: () => void;
+  const ready = new Promise<void>((r) => {
+    readyResolve = r;
+  });
+
+  queueMicrotask(() => {
+    try {
+      ws()
+        .send({ action: "open", doc: name })
+        .then((state) => {
+          data.set(state as T);
+          readyResolve();
+        });
+    } catch (err: any) {
+      log.error(`openDoc("${name}"): ${err.message}`);
+    }
+  });
+
+  return {
+    data,
+    dataVersion,
+    ready,
+    send(ops: DeltaOp[]) {
+      return ws().send({ action: "delta", doc: name, ops });
+    },
+  };
+}
+
+/** Call a stateless RPC method. */
+export function call<T>(method: string, params?: any): Promise<T> {
+  return ws().send({ action: "call", method, params });
+}

package/delta-server.ts

@@ -0,0 +1,234 @@
+/**
+ * Delta Server — WebSocket protocol layer + document/method registration for Bun.
+ *
+ * Provides the server half of the delta-doc system:
+ *   - createWs()       — shared WebSocket infrastructure (action routing, pub/sub, upgrade)
+ *   - registerDoc()    — persist a typed JSON document, sync via delta ops
+ *   - registerMethod() — expose a stateless RPC handler
+ *
+ * Usage:
+ *   import { createWs, registerDoc, registerMethod } from "@blueshed/railroad/delta-server";
+ *
+ *   const ws = createWs();
+ *   await registerDoc<Message>(ws, "message", { file: "./message.json", empty: { message: "" } });
+ *   registerMethod(ws, "status", () => ({ bun: Bun.version }));
+ *
+ *   const server = Bun.serve({ routes: { "/ws": ws.upgrade }, websocket: ws.websocket });
+ *   ws.setServer(server);
+ */
+import { createLogger } from "./logger";
+import { applyOps, type DeltaOp } from "./delta";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type ActionHandler = (
+  msg: any,
+  ws: any,
+  respond: (result: any) => void,
+) => any | Promise<any>;
+
+export interface WsServer {
+  on(action: string, handler: ActionHandler): void;
+  publish(channel: string, data: any): void;
+  sendTo(clientId: string, data: any): void;
+  setServer(s: any): void;
+  upgrade: (req: Request, server: any) => Response | undefined;
+  websocket: {
+    idleTimeout: number;
+    sendPings: boolean;
+    publishToSelf: boolean;
+    open(ws: any): void;
+    message(ws: any, raw: any): void;
+    close(ws: any): void;
+  };
+}
+
+export interface DocHandle<T> {
+  getDoc(): T;
+  setDoc(d: T): void;
+  persist(): Promise<void>;
+  applyAndBroadcast(ops: DeltaOp[]): void;
+}
+
+export interface DocOptions<T> {
+  file: string;
+  empty: T;
+}
+
+// ---------------------------------------------------------------------------
+// WebSocket server
+// ---------------------------------------------------------------------------
+
+/** Create a shared WebSocket server with action routing and Bun pub/sub. */
+export function createWs(): WsServer {
+  const log = createLogger("[ws]");
+  const actions = new Map<string, ActionHandler[]>();
+  const clients = new Map<string, any>();
+  let serverRef: any;
+
+  return {
+    on(action: string, handler: ActionHandler) {
+      if (!actions.has(action)) actions.set(action, []);
+      actions.get(action)!.push(handler);
+    },
+
+    publish(channel: string, data: any) {
+      serverRef?.publish(channel, JSON.stringify(data));
+    },
+
+    sendTo(clientId: string, data: any) {
+      const ws = clients.get(clientId);
+      if (ws?.readyState === 1) ws.send(JSON.stringify(data));
+    },
+
+    setServer(s: any) {
+      serverRef = s;
+    },
+
+    upgrade: (req: Request, server: any) => {
+      const url = new URL(req.url, "http://localhost");
+      const clientId = url.searchParams.get("clientId") ?? crypto.randomUUID();
+      if (server.upgrade(req, { data: { clientId } })) return;
+      return new Response("WebSocket upgrade failed", { status: 400 });
+    },
+
+    websocket: {
+      idleTimeout: 60,
+      sendPings: true,
+      publishToSelf: true,
+      open(ws: any) {
+        const clientId = ws.data?.clientId;
+        if (clientId) clients.set(clientId, ws);
+        for (const ch of ws.data?.channels ?? []) ws.subscribe(ch);
+        log.debug(`open id=${clientId ?? "?"}`);
+      },
+      async message(ws: any, raw: any) {
+        const msg = JSON.parse(String(raw));
+        const { id, action } = msg;
+
+        if (!action) {
+          for (const handler of actions.get("_raw") ?? []) {
+            await handler(msg, ws, () => {});
+          }
+          return;
+        }
+
+        try {
+          const handlers = actions.get(action);
+          if (!handlers?.length) {
+            if (id)
+              ws.send(
+                JSON.stringify({
+                  id,
+                  error: { code: -1, message: `Unknown action: ${action}` },
+                }),
+              );
+            return;
+          }
+          let responded = false;
+          const respond = (response: any) => {
+            if (!responded && id) {
+              responded = true;
+              ws.send(JSON.stringify({ id, ...response }));
+            }
+          };
+          for (const handler of handlers) {
+            await handler(msg, ws, respond);
+            if (responded) break;
+          }
+          if (!responded && id) {
+            ws.send(
+              JSON.stringify({
+                id,
+                error: { code: -1, message: `No handler matched: ${action}` },
+              }),
+            );
+          }
+        } catch (err: any) {
+          log.error(`error: ${err.message}`);
+          if (id)
+            ws.send(
+              JSON.stringify({ id, error: { code: -1, message: err.message } }),
+            );
+        }
+      },
+      close(ws: any) {
+        const clientId = ws.data?.clientId;
+        if (clientId) clients.delete(clientId);
+        log.debug(`close id=${clientId ?? "?"}`);
+      },
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Document registration
+// ---------------------------------------------------------------------------
+
+/** Register a persisted JSON document with the WebSocket server. */
+export async function registerDoc<T>(
+  ws: Pick<WsServer, "on" | "publish">,
+  name: string,
+  opts: DocOptions<T>,
+): Promise<DocHandle<T>> {
+  const log = createLogger(`[${name}]`);
+  const dataFile = Bun.file(opts.file);
+  let doc: T = (await dataFile.exists())
+    ? { ...structuredClone(opts.empty), ...((await dataFile.json()) as T) }
+    : structuredClone(opts.empty);
+
+  log.info(`loaded from ${opts.file}`);
+
+  async function persist() {
+    await Bun.write(dataFile, JSON.stringify(doc, null, 2));
+  }
+
+  function applyAndBroadcast(ops: DeltaOp[]) {
+    applyOps(doc, ops);
+    log.info(`delta [${ops.map((o) => `${o.op} ${o.path}`).join(", ")}]`);
+    ws.publish(name, { doc: name, ops });
+    persist();
+  }
+
+  ws.on("open", (msg, client, respond) => {
+    if (msg.doc !== name) return;
+    client.subscribe(name);
+    respond({ result: doc });
+    log.debug("opened");
+  });
+
+  ws.on("delta", (msg, _client, respond) => {
+    if (msg.doc !== name) return;
+    applyAndBroadcast(msg.ops);
+    respond({ result: { ack: true } });
+  });
+
+  ws.on("close", (msg, client, respond) => {
+    if (msg.doc !== name) return;
+    client.unsubscribe(name);
+    respond({ result: { ack: true } });
+    log.debug("closed");
+  });
+
+  return { getDoc: () => doc, setDoc: (d: T) => { doc = d; }, persist, applyAndBroadcast };
+}
+
+// ---------------------------------------------------------------------------
+// Method registration
+// ---------------------------------------------------------------------------
+
+/** Register a stateless RPC method with the WebSocket server. */
+export function registerMethod(
+  ws: Pick<WsServer, "on">,
+  name: string,
+  handler: (params: any, client: any) => any | Promise<any>,
+) {
+  ws.on("call", async (msg, client, respond) => {
+    if (msg.method !== name) return;
+    const log = createLogger(`[${name}]`);
+    log.debug("called");
+    respond({ result: await handler(msg.params, client) });
+  });
+}

package/delta.ts

@@ -0,0 +1,66 @@
+/**
+ * Delta — shared types and operations for JSON document patching.
+ *
+ * Used by both delta-server (apply + persist) and delta-client (apply + render).
+ * No dependencies — safe to import anywhere.
+ *
+ * Delta ops use JSON Pointer paths (`/`-separated, numeric for array index, `-` for append):
+ *   { op: "replace", path: "/field",    value: "new" }  — set a value at path
+ *   { op: "add",     path: "/items/-",  value: item }   — append to array
+ *   { op: "remove",  path: "/items/0" }                  — delete by index
+ *
+ * Multiple ops applied via applyOps() are atomic in memory.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type DeltaOp =
+  | { op: "replace"; path: string; value: unknown }
+  | { op: "add"; path: string; value: unknown }
+  | { op: "remove"; path: string };
+
+// ---------------------------------------------------------------------------
+// Apply
+// ---------------------------------------------------------------------------
+
+function parsePath(path: string): (string | number)[] {
+  return path
+    .split("/")
+    .filter(Boolean)
+    .map((s) => (/^\d+$/.test(s) ? Number(s) : s));
+}
+
+function walk(
+  obj: any,
+  segments: (string | number)[],
+): { parent: any; key: string | number } {
+  let current = obj;
+  for (let i = 0; i < segments.length - 1; i++) {
+    current = current[segments[i]!];
+    if (current == null)
+      throw new Error(`Path not found at segment ${segments[i]}`);
+  }
+  return { parent: current, key: segments[segments.length - 1]! };
+}
+
+/** Apply delta ops to a document in place. */
+export function applyOps(doc: any, ops: DeltaOp[]): void {
+  for (const op of ops) {
+    const segments = parsePath(op.path);
+    const { parent, key } = walk(doc, segments);
+    switch (op.op) {
+      case "replace":
+      case "add":
+        if (Array.isArray(parent) && key === "-") parent.push(op.value);
+        else parent[key] = op.value;
+        break;
+      case "remove":
+        if (Array.isArray(parent) && typeof key === "number")
+          parent.splice(key, 1);
+        else delete parent[key];
+        break;
+    }
+  }
+}

package/index.ts

@@ -1,4 +1,4 @@
-// Railroad — Signals, JSX, and Routes
+// Railroad — Signals, JSX, Routes, and Delta-doc
 
 export { Signal, signal, computed, effect, batch } from "./signals";
 export type { Dispose } from "./signals";
@@ -15,3 +15,6 @@ export type { Key } from "./shared";
 
 export { createLogger, setLogLevel, getLogLevel, loggedRequest } from "./logger";
 export type { LogLevel } from "./logger";
+
+export { applyOps } from "./delta";
+export type { DeltaOp } from "./delta";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@blueshed/railroad",
-  "version": "0.4.0",
-  "description": "Signals, JSX, and routes — a micro UI framework for Bun",
+  "version": "0.5.0",
+  "description": "Signals, JSX, routes, and delta-doc — a micro UI framework for Bun",
   "type": "module",
   "main": "index.ts",
   "types": "index.ts",
@@ -11,6 +11,9 @@
     "./jsx": "./jsx.ts",
     "./routes": "./routes.ts",
     "./shared": "./shared.ts",
+    "./delta": "./delta.ts",
+    "./delta-server": "./delta-server.ts",
+    "./delta-client": "./delta-client.ts",
     "./jsx-runtime": "./jsx-runtime.ts",
     "./jsx-dev-runtime": "./jsx-dev-runtime.ts"
   },
@@ -36,5 +39,5 @@
     "type": "git",
     "url": "https://github.com/blueshed/railroad"
   },
-  "keywords": ["signals", "jsx", "router", "bun", "ui", "framework"]
+  "keywords": ["signals", "jsx", "router", "delta-doc", "bun", "ui", "framework"]
 }