@blueshed/railroad 0.3.4 → 0.5.0

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

@@ -1,94 +1,99 @@
-# Railroad — Skill for Claude
+---
+name: 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.
 
-**Source files are the canonical reference.** Each has a JSDoc header with full API docs. Read the source when you need detail:
-- `signals.ts` — signal, computed, effect, batch, dispose scopes
-- `jsx.ts` — createElement, Fragment, text, when, list, SVG adoption
-- `routes.ts` — routes, route, navigate, matchRoute
-- `shared.ts` — key, provide, inject, tryInject
-- `logger.ts` — createLogger, setLogLevel, loggedRequest
+**Read the source files for full API detail** — each has a JSDoc header:
+`signals.ts` · `jsx.ts` · `routes.ts` · `shared.ts` · `logger.ts` · `delta.ts` · `delta-server.ts` · `delta-client.ts`
 
 ## Setup
 
 ```json
-// tsconfig.json — automatic runtime (recommended)
+// tsconfig.json
 { "jsx": "react-jsx", "jsxImportSource": "@blueshed/railroad" }
 ```
 
-```ts
-// server.ts
-import home from "./index.html";
-Bun.serve({ routes: { "/": home } });
-```
+## Mental Model
 
-## API Quick Reference
+Components run **once**. They return real DOM nodes. Reactivity comes from signals — not re-rendering. Effects and computeds auto-dispose when their parent scope (component, route, `when`, `list`) tears down.
 
-### Signals (`signals.ts`)
+```tsx
+// Bare signal — auto-reactive
+<span>{count}</span>
 
-```ts
-signal<T>(value): Signal<T>           // mutable reactive value
-computed<T>(fn): Signal<T>            // derived, auto-tracked, auto-disposed in scope
-effect(fn): Dispose                   // side-effect, returns dispose function
-batch(fn): void                       // group writes, flush once
+// Function child — auto-reactive expression
+<span>{() => count.get() > 5 ? "High" : "Low"}</span>
+
+// Signal.map() — derive a signal for attributes and list items
+<input disabled={count.map(n => n > 10)} />
+{list(todos, t => t.id, (todo$) => <li>{todo$.map(t => t.name)}</li>)}
 ```
 
-Signal methods: `.get()` `.set(v)` `.update(fn)` `.mutate(fn)` `.patch(partial)` `.peek()`
+## Key Patterns
+
+```tsx
+// Reactive attributes — .map() or computed()
+<div class={visible.map(v => v ? "show" : "hide")}>...</div>
+
+// Keyed list — render gets Signal<T>, use .map() for content
+{list(todos, t => t.id, (todo$, idx$) => (
+  <li class={idx$.map(i => i % 2 ? "odd" : "even")}>
+    {todo$.map(t => t.name)}
+  </li>
+))}
+
+// Nested routes — wildcard keeps layout mounted, route() for sub-navigation
+routes(app, { "/sites/*": () => <SitesLayout /> });
+function SitesLayout() {
+  const detail = route<{ id: string }>("/sites/:id");
+  return when(() => detail.get(), () => <SiteDetail />, () => <SitesList />);
+}
+```
 
-Dispose scopes: `pushDisposeScope()` `popDisposeScope(): Dispose` `trackDispose(fn)`
+## Delta-doc
 
-### JSX (`jsx.ts`)
+Real-time JSON document sync over WebSocket. Server persists to files, client gets reactive signals.
 
-Components are functions called **once**. Reactivity comes from signals, not re-rendering.
+**Read source for full API:** `delta.ts` · `delta-server.ts` · `delta-client.ts`
 
 ```ts
-createElement(tag, props, ...children): Node
-Fragment(props): DocumentFragment
-text(fn): Node                        // reactive computed text node
-when(condition, truthy, falsy?): Node // conditional swap on truthiness transition
-list(items, keyFn, render): Node      // keyed list, render gets Signal<T>, Signal<number>
-list(items, render): Node             // index-based list, render gets raw T
-```
-
-Props: `class`/`className`, `style` (object or Signal), `value`/`checked`/`disabled`/`selected`/`src`/`srcdoc` (as DOM properties), `innerHTML`, `ref(el)`, `on*` events. All support Signal values for reactivity.
+// Server — register docs and methods
+import { createWs, registerDoc, registerMethod } from "@blueshed/railroad/delta-server";
 
-SVG: `<svg>` children are auto-adopted into SVG namespace.
+const ws = createWs();
+await registerDoc<Message>(ws, "message", { file: "./data/message.json", empty: { message: "" } });
+registerMethod(ws, "status", () => ({ bun: Bun.version }));
 
-### Routes (`routes.ts`)
-
-```ts
-routes(target, table): Dispose        // hash router, auto-disposes on swap
-route<T>(pattern): Signal<T | null>   // reactive route match
-navigate(path): void                  // set location.hash
-matchRoute(pattern, path): params | null
+const server = Bun.serve({ routes: { "/ws": ws.upgrade }, websocket: ws.websocket });
+ws.setServer(server);
 ```
 
-Handlers receive `(params, params$)` — plain object + Signal. Destructure the first, watch the second for same-pattern param changes (e.g. `/users/1` → `/users/2`).
+```tsx
+// Client — open docs as reactive signals
+import { provide } from "@blueshed/railroad";
+import { connectWs, WS, openDoc, call } from "@blueshed/railroad/delta-client";
 
-### Shared (`shared.ts`)
+provide(WS, connectWs("/ws"));
 
-```ts
-key<T>(name): Key<T>                 // typed symbol key
-provide<T>(key, value): void         // register value
-inject<T>(key): T                    // retrieve value (throws if missing)
-tryInject<T>(key): T | undefined     // retrieve value (returns undefined if missing)
+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");
 ```
 
-### Logger (`logger.ts`)
+**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
 
-```ts
-createLogger(tag): { info, warn, error, debug }
-setLogLevel(level): void             // "error" | "warn" | "info" | "debug"
-loggedRequest(tag, handler): Handler // wrap route handler with access logging
-```
+Multiple ops in one `send()` are atomic.
 
 ## Anti-Patterns
 
-1. **No React.** No useState, useEffect, hooks, lifecycle methods, memo, or react imports.
-2. **No `.get()` in JSX children.** `<p>{count}</p>` is reactive. `<p>{count.get()}</p>` is static.
-3. **No `text()` for attributes.** `text()` creates a DOM node. Use `computed()` for reactive attributes.
-4. **No JSX in effects without dispose scopes.** Any effect that rebuilds DOM must use `pushDisposeScope`/`popDisposeScope` and return a cleanup function. See `jsx.ts` source for the pattern.
-5. **No `transition-all` in CSS** near layout boundaries. Use specific properties.
-6. **No bare nested `when()`.** `when()` returns a fragment — nesting fragments inside another `when()` breaks dispose scope tracking. Always wrap an inner `when()` in a real element: `<div>{when(...)}</div>`.
-7. **No shared DOM nodes across `when()` branches.** Nodes must be created fresh inside each branch function. A node created outside and reused across branches will be torn out of the DOM when the other branch activates.
-8. **Guard against null inside `when()` branches.** Signal cascade order is not guaranteed — an inner `when()` can fire before the outer `when()` swaps it away. Always null-check even inside a branch that "shouldn't" be reached (e.g. `text(() => item.get()?.name ?? "")`).
+1. **No React.** No useState, useEffect, hooks, lifecycle methods, or react imports.
+2. **No `.get()` in JSX children.** `{count}` or `{() => count.get() + 1}` — never `{count.get()}`.
+3. **No shared DOM nodes across `when()` branches.** Create nodes fresh inside each branch.
+4. **No `transition-all` in CSS** near layout boundaries. Use specific properties.

package/README.md

@@ -37,7 +37,7 @@ function Home() {
     <div>
       <h1>Hello World</h1>
       <button onclick={() => count.update(n => n + 1)}>
-        Count: {count}
+        {() => `Count: ${count.get()}`}
       </button>
     </div>
   );
@@ -74,7 +74,7 @@ function Home() {
     <div>
       <h1>Hello World</h1>
       <button onclick={() => count.update(n => n + 1)}>
-        Count: {count}
+        {() => `Count: ${count.get()}`}
       </button>
     </div>
   );
@@ -107,6 +107,7 @@ import { signal, computed, effect, batch } from "@blueshed/railroad";
 
 const count = signal(0);
 const doubled = computed(() => count.get() * 2);
+const label = count.map(n => `Count: ${n}`);  // derive a signal
 
 const dispose = effect(() => {
   console.log(`count is ${count.get()}`);
@@ -134,10 +135,10 @@ dispose();           // stop listening
 
 ### JSX
 
-Components are functions that return DOM nodes. Signals in children and props auto-update.
+Components are functions that run **once** and return DOM nodes. Reactivity comes from signals, not re-rendering.
 
 ```tsx
-import { createElement, text, when, list, signal } from "@blueshed/railroad";
+import { signal, when, list } from "@blueshed/railroad";
 
 const name = signal("World");
 
@@ -146,10 +147,18 @@ function Greeting() {
 }
 ```
 
-#### `text(fn)` — reactive computed text
+#### Reactive expressions — function children
 
 ```tsx
-<span>{text(() => count.get() > 5 ? "High" : "Low")}</span>
+<span>{() => count.get() > 5 ? "High" : "Low"}</span>
+<p>{() => `${first.get()} ${last.get()}`}</p>
+```
+
+#### Reactive attributes — `computed()` or `.map()`
+
+```tsx
+<div class={visible.map(v => v ? "show" : "hide")}>...</div>
+<input disabled={count.map(n => n > 10)} />
 ```
 
 #### `when(condition, truthy, falsy?)` — conditional rendering
@@ -162,15 +171,17 @@ function Greeting() {
 )}
 ```
 
+Nestable — `when()` inside `when()` works without wrapper elements.
+
 #### `list(items, keyFn?, render)` — keyed list rendering
 
 ```tsx
 // Keyed — render receives Signal<T> and Signal<number>:
-{list(
-  todos,
-  (t) => t.id,
-  (todo, idx) => <li>{text(() => todo.get().name)}</li>,
-)}
+{list(todos, t => t.id, (todo$, idx$) => (
+  <li class={idx$.map(i => i % 2 ? "odd" : "even")}>
+    {todo$.map(t => t.name)}
+  </li>
+))}
 
 // Non-keyed (index-based, raw values):
 {list(items, (item, i) => <li>{item}</li>)}
@@ -178,19 +189,17 @@ function Greeting() {
 
 ### Routes
 
-Hash-based client router with automatic dispose scoping. Handlers receive `(params, params$)` — destructure the first for convenience, watch the second for reactive param changes.
+Hash-based client router. Handlers receive `(params, params$)` — destructure the first for convenience, watch the second for reactive param changes.
 
 ```tsx
-import { routes, navigate, effect, text } from "@blueshed/railroad";
+import { routes, navigate, route, when, effect } from "@blueshed/railroad";
 
-const dispose = routes(app, {
+routes(app, {
   "/":           () => <Home />,
-  // Simple — destructure params as before:
   "/about":      () => <About />,
-  // Reactive — watch params$ for same-pattern navigation (/users/1 → /users/2):
   "/users/:id":  ({ id }, params$) => {
     effect(() => fetchUser(params$.get().id));
-    return <h1>{text(() => `User ${params$.get().id}`)}</h1>;
+    return <h1>{params$.map(p => `User ${p.id}`)}</h1>;
   },
   "*":           () => <NotFound />,
 });
@@ -198,6 +207,33 @@ const dispose = routes(app, {
 navigate("/users/42");
 ```
 
+#### Nested routes
+
+Use wildcard patterns to keep a layout mounted while sub-views swap:
+
+```tsx
+routes(app, {
+  "/":          () => <Home />,
+  "/sites/*":   () => <SitesLayout />,
+});
+
+function SitesLayout() {
+  const detail = route<{ id: string }>("/sites/:id");
+
+  return (
+    <div>
+      <SitesNav />
+      {when(() => detail.get(),
+        () => <SiteDetail params$={detail} />,
+        () => <SitesList />,
+      )}
+    </div>
+  );
+}
+```
+
+Navigate `/sites` → `/sites/42` → `/sites/99`: `SitesLayout` stays mounted, only the inner content swaps. Navigate away from `/sites/*`: layout tears down cleanly.
+
 ### Shared
 
 Typed dependency injection without prop threading.
@@ -235,9 +271,9 @@ const handler = loggedRequest("[api]", myHandler);
 ## Design
 
 - **Signals hold state** — reactive primitives with automatic dependency tracking
-- **Effects update the DOM** — run when dependencies change, return cleanup
+- **Effects update the DOM** — run when dependencies change, auto-cleanup in scope
 - **JSX creates the DOM** — real elements, not virtual. Signal-aware props and children
-- **Routes swap the DOM** — hash-based, dispose-scoped, Bun.serve-style tables
+- **Routes swap the DOM** — hash-based, auto-scoped, nestable via wildcards
 
 No lifecycle methods. No hooks rules. No context providers. No `useCallback`. Just signals and the DOM.
 
@@ -275,7 +311,7 @@ Every import path (`/signals`, `/shared`, `/logger`, `/jsx`, `/routes`) works st
 
 ## Claude Code
 
-This package ships with a [Claude Code](https://claude.com/claude-code) skill in `.claude/skills/railroad/`. Copy it into your project so Claude generates correct railroad code — including API usage, patterns, and anti-patterns:
+This package ships with a [Claude Code](https://claude.com/claude-code) skill in `.claude/skills/railroad/`. Copy it into your project so Claude generates correct railroad code:
 
 ```sh
 cp -r node_modules/@blueshed/railroad/.claude/skills/railroad .claude/skills/

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 });
+}