@blueshed/railroad 0.2.8 → 0.3.1

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

@@ -1,86 +1,91 @@
 # Railroad — Skill for Claude
 
-You are helping a developer build a UI with `@blueshed/railroad`, a micro reactive framework for Bun.
+Micro reactive UI framework for Bun. ~900 lines, zero dependencies, real DOM.
 
-## What Railroad Is
+**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
 
-- ~400 lines. Zero dependencies. Real DOM — no virtual DOM, no compiler, no build step.
-- Designed for Bun. TypeScript source files are the distribution (no transpile step).
-- Four concerns: **signals** (state), **JSX** (DOM), **routes** (navigation), **shared** (dependency injection).
+## Setup
 
-## When to Use This Skill
-
-Use railroad when the developer has it installed (`@blueshed/railroad` in package.json) or asks to build a UI with signals and JSX for Bun. Do NOT mix railroad with React, Preact, Solid, or any other framework — they are incompatible.
+```json
+// tsconfig.json — automatic runtime (recommended)
+{ "jsx": "react-jsx", "jsxImportSource": "@blueshed/railroad" }
+```
 
-## Critical Setup
+```ts
+// server.ts
+import home from "./index.html";
+Bun.serve({ routes: { "/": home } });
+```
 
-### Automatic runtime (recommended)
+## API Quick Reference
 
-No JSX imports needed — the compiler inserts them automatically.
+### Signals (`signals.ts`)
 
-```json
-{
-  "compilerOptions": {
-    "jsx": "react-jsx",
-    "jsxImportSource": "@blueshed/railroad"
-  }
-}
+```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
 ```
 
-### Classic runtime
+Signal methods: `.get()` `.set(v)` `.update(fn)` `.mutate(fn)` `.patch(partial)` `.peek()`
 
-If the project uses explicit imports, every `.tsx` file that uses JSX **must** import `createElement` (and `Fragment` if using `<>...</>`):
+Dispose scopes: `pushDisposeScope()` `popDisposeScope(): Dispose` `trackDispose(fn)`
 
-```json
-{
-  "compilerOptions": {
-    "jsx": "react",
-    "jsxFactory": "createElement",
-    "jsxFragmentFactory": "Fragment"
-  }
-}
+### JSX (`jsx.ts`)
+
+Components are functions called **once**. Reactivity comes from signals, not re-rendering.
+
+```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
 ```
 
-Check the project's `tsconfig.json` to see which mode is in use. Prefer the automatic runtime for new projects.
+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.
 
-A minimal Bun server to serve the app:
+SVG: `<svg>` children are auto-adopted into SVG namespace.
+
+### Routes (`routes.ts`)
 
 ```ts
-import home from "./index.html";
-Bun.serve({ routes: { "/": home } });
+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
 ```
 
-## How to Import
+Handlers receive `(params, params$)` — plain object + Signal. Destructure the first, watch the second for same-pattern param changes (e.g. `/users/1` → `/users/2`).
+
+### Shared (`shared.ts`)
 
 ```ts
-// Everything from one place:
-import { createElement, Fragment, signal, computed, effect, batch, text, when, list, routes, navigate, key, provide, inject } from "@blueshed/railroad";
-
-// Or by concern:
-import { signal, computed, effect, batch } from "@blueshed/railroad/signals";
-import { createElement, Fragment, text, when, list } from "@blueshed/railroad/jsx";
-import { routes, navigate, route, matchRoute } from "@blueshed/railroad/routes";
-import { key, provide, inject } from "@blueshed/railroad/shared";
+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)
 ```
 
-## Reference Docs
-
-Detailed usage for each concern is in the sibling files. Read them before generating railroad code:
+### Logger (`logger.ts`)
 
-- `signals.md` — reactive state: signal, computed, effect, batch, dispose, mutate, patch
-- `jsx.md` — DOM creation: createElement, Fragment, text, when, list, props, events, refs
-- `routes.md` — hash-based client router: routes, navigate, route, matchRoute
-- `shared.md` — typed dependency injection: key, provide, inject
+```ts
+createLogger(tag): { info, warn, error, debug }
+setLogLevel(level): void             // "error" | "warn" | "info" | "debug"
+loggedRequest(tag, handler): Handler // wrap route handler with access logging
+```
 
-## Anti-Patterns — Do NOT Do These
+## Anti-Patterns
 
-1. **No React patterns.** There is no `useState`, `useEffect`, `useRef`, `useCallback`, `useMemo`, or any hooks. There are no lifecycle methods. There is no `React.memo`. Do not import from `react`.
-2. **No virtual DOM.** `createElement` produces real DOM nodes. There is no reconciler, no diffing (except in `list()`), no re-rendering of component trees.
-3. **Components run once.** A component function is called once and returns a DOM node. Reactivity comes from signals, not from re-calling the component.
-4. **No JSX without setup.** In classic mode, every `.tsx` file needs `import { createElement } from "@blueshed/railroad"`. In automatic mode (`react-jsx` + `jsxImportSource`), no import is needed — the compiler handles it. Check tsconfig to know which mode.
-5. **Do not call `.get()` in JSX children.** Pass the signal directly: `<p>{count}</p>`, not `<p>{count.get()}</p>`. The latter creates a static text node that never updates.
-6. **Do not use `text()` for attributes.** `text()` creates a DOM text node — use `computed()` for reactive attribute values: `class={computed(() => active.get() ? "on" : "off")}`.
-7. **Do not create signals inside components** unless you want fresh state on every mount. Module-level signals are shared state; component-level signals are local/ephemeral.
-8. **Do not forget `batch()`** when setting multiple signals that feed the same effect — without it, the effect runs once per set.
-9. **Do not rebuild JSX in effects without dispose scopes.** Any effect that does `container.innerHTML = ""; container.appendChild(<JSX/>)` **must** use the full dispose scope pattern — see `jsx.md` Dispose Scopes section. Both the re-run cleanup (`if (childDispose) childDispose()` at top) AND the effect cleanup return (`return () => { ... }`) are required. Without the return, child effects leak when the parent is torn down.
-10. **Do not use `transition-all` in CSS** for elements near layout boundaries (cards, panels). Use specific properties like `transition-colors` or `transition-[width,border-color]` to avoid animating layout properties unintentionally.
+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.

package/README.md

@@ -2,7 +2,7 @@
 
 Signals, JSX, and routes — a micro UI framework for Bun.
 
-~400 lines. Zero dependencies. Real DOM. No virtual DOM, no compiler, no build step.
+~900 lines. Zero dependencies. Real DOM. No virtual DOM, no compiler, no build step.
 
 ## Install
 
@@ -178,14 +178,20 @@ function Greeting() {
 
 ### Routes
 
-Hash-based client router with automatic dispose scoping.
+Hash-based client router with automatic dispose scoping. Handlers receive `(params, params$)` — destructure the first for convenience, watch the second for reactive param changes.
 
 ```tsx
-import { routes, navigate } from "@blueshed/railroad";
+import { routes, navigate, effect, text } from "@blueshed/railroad";
 
 const dispose = routes(app, {
   "/":           () => <Home />,
-  "/users/:id":  ({ id }) => <User id={id} />,
+  // 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>;
+  },
   "*":           () => <NotFound />,
 });
 
@@ -204,6 +210,26 @@ provide(STORE, createStore());
 
 // anywhere:
 const store = inject(STORE);
+
+// Non-throwing variant:
+const maybeStore = tryInject(STORE); // T | undefined
+```
+
+### Logger
+
+Colored, timestamped, level-gated console output.
+
+```ts
+import { createLogger, setLogLevel, loggedRequest } from "@blueshed/railroad";
+
+const log = createLogger("[server]");
+log.info("listening on :3000");
+log.debug("tick");             // only shown when level is "debug"
+
+setLogLevel("debug");          // show everything
+
+// Wrap a route handler with access logging:
+const handler = loggedRequest("[api]", myHandler);
 ```
 
 ## Design
@@ -215,6 +241,38 @@ const store = inject(STORE);
 
 No lifecycle methods. No hooks rules. No context providers. No `useCallback`. Just signals and the DOM.
 
+## Progressive Adoption
+
+Each module is independent — use as much or as little as you need.
+
+```
+signals.ts  ← no deps         Use signals anywhere: server, CLI, worker
+shared.ts   ← no deps         Add typed DI when you need shared state
+logger.ts   ← no deps         Add logging to your Bun server
+jsx.ts      ← signals         Add reactive DOM when you need a UI
+routes.ts   ← signals         Add client-side routing when you need pages
+```
+
+**Level 1 — Reactive state only** (no DOM, no tsconfig changes)
+
+```ts
+import { signal, computed, effect } from "@blueshed/railroad/signals";
+```
+
+**Level 2 — Add JSX** (needs `tsconfig.json` JSX settings)
+
+```ts
+import { signal, createElement, when, list } from "@blueshed/railroad";
+```
+
+**Level 3 — Full app** (signals + JSX + routing + DI + logging)
+
+```ts
+import { signal, routes, inject, createLogger } from "@blueshed/railroad";
+```
+
+Every import path (`/signals`, `/shared`, `/logger`, `/jsx`, `/routes`) works standalone. The barrel export (`@blueshed/railroad`) re-exports everything.
+
 ## 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:

package/jsx.ts

@@ -23,32 +23,16 @@
  *   text(fn)                      — reactive text from computed expression
  */
 
-import { Signal, signal, effect, computed } from "./signals";
+import { Signal, signal, effect, computed, pushDisposeScope, popDisposeScope, trackDispose } from "./signals";
 import type { Dispose } from "./signals";
 
+export { pushDisposeScope, popDisposeScope };
+
 // === SVG namespace ===
 
 const SVG_NS = "http://www.w3.org/2000/svg";
 const storedProps = new WeakMap<Element, Record<string, any>>();
 
-// === Dispose scope management ===
-
-const disposeStack: Dispose[][] = [];
-
-export function pushDisposeScope(): void {
-  disposeStack.push([]);
-}
-
-export function popDisposeScope(): Dispose {
-  const disposers = disposeStack.pop() || [];
-  return () => disposers.forEach((d) => d());
-}
-
-function trackDispose(d: Dispose): void {
-  const scope = disposeStack[disposeStack.length - 1];
-  if (scope) scope.push(d);
-}
-
 // === Fragment ===
 
 export function Fragment(props: any): DocumentFragment {
@@ -84,8 +68,10 @@ function applyProps(el: Element, props: Record<string, any>): void {
       } else {
         (el as any)[key] = value;
       }
-    } else if (key === "style" && typeof value === "object" && !(value instanceof Signal)) {
-      Object.assign((el as any).style, value);
+    } else if (key === "style" && value instanceof Signal) {
+      trackDispose(effect(() => { Object.assign((el as HTMLElement).style, value.get()); }));
+    } else if (key === "style" && typeof value === "object") {
+      Object.assign((el as HTMLElement).style, value);
     } else if (key.startsWith("on")) {
       el.addEventListener(key.slice(2).toLowerCase(), value);
     } else {

package/logger.ts

@@ -69,6 +69,14 @@ export function createLogger(tag: string) {
 type Handler = (req: Request) => Response | Promise<Response>;
 
 /** Wrap a route handler with access logging. */
+function safePathname(url: string): string {
+  try {
+    return new URL(url).pathname;
+  } catch {
+    return url;
+  }
+}
+
 export function loggedRequest(tag: string, handler: Handler): Handler {
   const log = createLogger(tag);
   return async (req: Request) => {
@@ -77,13 +85,14 @@ export function loggedRequest(tag: string, handler: Handler): Handler {
       const res = await handler(req);
       const ms = (performance.now() - start).toFixed(1);
       log.info(
-        `${req.method} ${new URL(req.url).pathname} → ${res.status} (${ms}ms)`,
+        `${req.method} ${safePathname(req.url)} → ${res.status} (${ms}ms)`,
       );
       return res;
-    } catch (err: any) {
+    } catch (err: unknown) {
       const ms = (performance.now() - start).toFixed(1);
+      const msg = err instanceof Error ? err.message : String(err);
       log.error(
-        `${req.method} ${new URL(req.url).pathname} threw (${ms}ms): ${err.message}`,
+        `${req.method} ${safePathname(req.url)} threw (${ms}ms): ${msg}`,
       );
       throw err;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueshed/railroad",
-  "version": "0.2.8",
+  "version": "0.3.1",
   "description": "Signals, JSX, and routes — a micro UI framework for Bun",
   "type": "module",
   "main": "index.ts",

package/routes.ts

@@ -7,29 +7,47 @@
  *   navigate(path)          — set location.hash programmatically
  *   matchRoute(pattern, path) — pure pattern matcher, returns params or null
  *
- * Handlers return a Node to render. The router manages cleanup automatically.
+ * Handlers receive (params, params$) and return a Node (sync or async).
+ *   params  — plain object for destructuring: ({ id }) => ...
+ *   params$ — Signal that updates when params change within the same pattern
+ *
+ * The router manages cleanup automatically. When params change within the
+ * same pattern (e.g. /users/1 → /users/2), params$ updates — no teardown.
  *   routes(app, {
  *     "/":          () => <Home />,
- *     "/site/:id":  ({ id }) => <SiteDetail id={id} />,
+ *     "/site/:id":  ({ id }, params$) => <SiteDetail id={id} params$={params$} />,
+ *     "/status":    async () => { const s = await api.get(); return <Status data={s} />; },
  *   });
  */
 
-import { Signal, computed, effect } from "./signals";
+import { Signal, signal, computed, effect, pushDisposeScope, popDisposeScope } from "./signals";
 import type { Dispose } from "./signals";
-import { pushDisposeScope, popDisposeScope } from "./jsx";
 
 let hashSignal: Signal<string> | null = null;
+let hashListenerCount = 0;
+let hashListener: (() => void) | null = null;
 
 function getHash(): Signal<string> {
   if (!hashSignal) {
     hashSignal = new Signal(location.hash.slice(1) || "/");
-    window.addEventListener("hashchange", () => {
+    hashListener = () => {
       hashSignal!.set(location.hash.slice(1) || "/");
-    });
+    };
+    window.addEventListener("hashchange", hashListener);
   }
+  hashListenerCount++;
   return hashSignal;
 }
 
+function releaseHash(): void {
+  hashListenerCount--;
+  if (hashListenerCount === 0 && hashListener) {
+    window.removeEventListener("hashchange", hashListener);
+    hashListener = null;
+    hashSignal = null;
+  }
+}
+
 export function matchRoute(
   pattern: string,
   path: string,
@@ -61,7 +79,10 @@ export function navigate(path: string): void {
   location.hash = path;
 }
 
-type RouteHandler = (params: Record<string, string>) => Node;
+type RouteHandler = (
+  params: Record<string, string>,
+  params$: Signal<Record<string, string>>,
+) => Node | Promise<Node>;
 
 export function routes(
   target: HTMLElement,
@@ -69,28 +90,54 @@ export function routes(
 ): Dispose {
   const hash = getHash();
   let activePattern: string | null = null;
+  let activeParams: Signal<Record<string, string>> | null = null;
   let activeDispose: Dispose | null = null;
+  let runId = 0;
+  let asyncPending = false;
 
   function teardown() {
+    runId++;
+    if (asyncPending) {
+      popDisposeScope()();
+      asyncPending = false;
+    }
     if (activeDispose) activeDispose();
     activeDispose = null;
     activePattern = null;
+    activeParams = null;
     target.replaceChildren();
   }
 
   function run(handler: RouteHandler, params: Record<string, string>) {
+    const myRunId = ++runId;
+    activeParams = signal(params);
     pushDisposeScope();
-    const node = handler(params);
-    activeDispose = popDisposeScope();
-    target.appendChild(node);
+    const result = handler(params, activeParams);
+
+    if (result instanceof Promise) {
+      asyncPending = true;
+      result.then((node) => {
+        if (myRunId !== runId) return; // navigated away during await
+        asyncPending = false;
+        activeDispose = popDisposeScope();
+        target.appendChild(node);
+      });
+    } else {
+      activeDispose = popDisposeScope();
+      target.appendChild(result);
+    }
   }
 
-  return effect(() => {
+  const disposeEffect = effect(() => {
     const path = hash.get();
     for (const [pattern, handler] of Object.entries(table)) {
       const params = matchRoute(pattern, path);
       if (params) {
-        if (pattern === activePattern) return;
+        if (pattern === activePattern) {
+          // Same pattern, different params — update the signal
+          activeParams!.set(params);
+          return;
+        }
         teardown();
         activePattern = pattern;
         run(handler, params);
@@ -107,4 +154,10 @@ export function routes(
     }
     teardown();
   });
+
+  return () => {
+    disposeEffect();
+    teardown();
+    releaseHash();
+  };
 }

package/signals.ts

@@ -88,7 +88,7 @@ export class Signal<T> {
     }
     effectDepth++;
     try {
-      if (effectDepth > MAX_EFFECT_DEPTH) {
+      if (effectDepth >= MAX_EFFECT_DEPTH) {
         throw new Error(
           "Maximum effect depth exceeded — possible infinite loop",
         );
@@ -142,11 +142,32 @@ export function effect(fn: () => void | (() => void)): () => void {
   };
 }
 
+// === Dispose type & scope management ===
+
+export type Dispose = () => void;
+
+const disposeStack: Dispose[][] = [];
+
+export function pushDisposeScope(): void {
+  disposeStack.push([]);
+}
+
+export function popDisposeScope(): Dispose {
+  const disposers = disposeStack.pop() || [];
+  return () => disposers.forEach((d) => d());
+}
+
+export function trackDispose(d: Dispose): void {
+  const scope = disposeStack[disposeStack.length - 1];
+  if (scope) scope.push(d);
+}
+
 // === computed() ===
 
 export function computed<T>(fn: () => T): Signal<T> {
   const s = new Signal<T>(fn());
-  effect(() => s.set(fn()));
+  const dispose = effect(() => s.set(fn()));
+  trackDispose(dispose);
   return s;
 }
 
@@ -180,7 +201,3 @@ export function batch(fn: () => void): void {
 export function signal<T>(initialValue: T): Signal<T> {
   return new Signal(initialValue);
 }
-
-// === Dispose type ===
-
-export type Dispose = () => void;

package/.claude/skills/railroad/jsx.md

@@ -1,325 +0,0 @@
-# JSX — Real DOM Elements Backed by Signals
-
-Railroad's JSX produces real DOM nodes, not a virtual DOM. Components are plain functions called once. Reactivity comes from signals, not re-rendering.
-
-## JSX Setup
-
-Railroad supports two JSX modes. Check the project's `tsconfig.json` to know which is in use.
-
-### Automatic runtime (recommended)
-
-```json
-{ "jsx": "react-jsx", "jsxImportSource": "@blueshed/railroad" }
-```
-
-No imports needed — the compiler auto-inserts the runtime. Just write JSX:
-
-```tsx
-import { signal } from "@blueshed/railroad";
-const count = signal(0);
-function App() {
-  return <div>{count}</div>;  // works, no createElement import
-}
-```
-
-### Classic runtime
-
-```json
-{ "jsx": "react", "jsxFactory": "createElement", "jsxFragmentFactory": "Fragment" }
-```
-
-Every `.tsx` file must import `createElement` (and `Fragment` for `<>...</>`):
-
-```tsx
-import { createElement, Fragment } from "@blueshed/railroad";
-```
-
-## Components
-
-A component is a function that receives props and returns a DOM Node. It runs **once** per mount.
-
-```tsx
-function Greeting({ name }: { name: string }) {
-  return <h1>Hello {name}</h1>;
-}
-
-// Usage:
-<Greeting name="World" />
-```
-
-### Children
-
-Children are passed as part of props:
-
-```tsx
-function Card({ children }: { children: any[] }) {
-  return <div class="card">{children}</div>;
-}
-
-<Card><p>Content</p></Card>
-```
-
-### Components Run Once
-
-This is the most important thing to understand. Unlike React, the component function body executes once. To make things reactive, use signals:
-
-```tsx
-// WRONG — static, never updates:
-function Counter() {
-  let count = 0;
-  return <p>{count}</p>; // always shows 0
-}
-
-// RIGHT — reactive via signal:
-function Counter() {
-  const count = signal(0);
-  return (
-    <div>
-      <p>{count}</p>  {/* auto-updates when count changes */}
-      <button onclick={() => count.update(n => n + 1)}>+</button>
-    </div>
-  );
-}
-```
-
-## Props and Attributes
-
-### Event Handlers
-
-Lowercase `on` prefix, directly on the element. The handler name after `on` is lowercased and passed to `addEventListener`.
-
-```tsx
-<button onclick={() => doSomething()}>Click</button>
-<input oninput={(e) => query.set(e.target.value)} />
-<form onsubmit={(e) => { e.preventDefault(); save(); }}>
-```
-
-### Class
-
-Use `class` or `className` — both work. Signals are supported:
-
-```tsx
-<div class="active">static</div>
-<div class={activeClass}>reactive</div>  {/* activeClass is a Signal<string> */}
-```
-
-For derived/conditional class values, use `computed()`:
-
-```tsx
-import { computed } from "@blueshed/railroad";
-
-<button class={computed(() => `btn ${active.get() ? "active" : ""}`)}>
-```
-
-**Do NOT use `text()` for attributes** — `text()` creates a text DOM node, not a string. Use `computed()` for any reactive attribute value (class, style, data-*, etc.).
-
-### Style
-
-Pass a plain object (not a signal) to set inline styles:
-
-```tsx
-<div style={{ color: "red", fontSize: "16px" }}>styled</div>
-```
-
-### DOM Properties
-
-These are set as element properties (not attributes) and support signals: `value`, `checked`, `disabled`, `selected`, `src`, `srcdoc`.
-
-```tsx
-const inputValue = signal("");
-<input value={inputValue} oninput={(e) => inputValue.set(e.target.value)} />
-
-const isDisabled = signal(false);
-<button disabled={isDisabled}>Submit</button>
-```
-
-### innerHTML
-
-Set raw HTML (supports signals):
-
-```tsx
-<div innerHTML={htmlSignal} />
-```
-
-### Ref
-
-Get a reference to the underlying DOM element:
-
-```tsx
-<input ref={(el) => el.focus()} />
-```
-
-The ref callback fires immediately after element creation.
-
-### Regular Attributes
-
-Anything not matching the above is set via `setAttribute`. Signals auto-update. `false` and `null`/`undefined` remove the attribute.
-
-```tsx
-<a href="/about">About</a>
-<div data-id={itemId}>...</div>  {/* itemId can be a Signal */}
-<input aria-label={label} />
-```
-
-## Signals as Children
-
-Pass a signal directly as a child to create a reactive text node:
-
-```tsx
-const count = signal(0);
-<p>Count: {count}</p>  // updates automatically
-```
-
-**Do NOT call `.get()` in JSX children** — this evaluates once and creates a static string:
-
-```tsx
-// WRONG — static text, never updates:
-<p>Count: {count.get()}</p>
-
-// RIGHT — reactive:
-<p>Count: {count}</p>
-```
-
-## Null, Boolean, and Undefined Children
-
-`null`, `undefined`, `true`, and `false` are ignored (not rendered). Use this for conditional inline content:
-
-```tsx
-<div>{showWarning.peek() && <span>Warning!</span>}</div>
-```
-
-But prefer `when()` for reactive conditionals — see below.
-
-## `text(fn)` — Reactive Computed Text
-
-For expressions more complex than a single signal, use `text()`:
-
-```tsx
-import { text } from "@blueshed/railroad";
-
-<span>{text(() => count.get() > 5 ? "High" : "Low")}</span>
-<p>{text(() => `${firstName.get()} ${lastName.get()}`)}</p>
-```
-
-`text()` creates a computed signal internally and keeps its text node updated.
-
-## `when(condition, truthy, falsy?)` — Conditional Rendering
-
-Swaps DOM nodes when the truthiness of the condition changes.
-
-```tsx
-import { when } from "@blueshed/railroad";
-
-// With a signal:
-{when(isLoggedIn, () => <Dashboard />, () => <Login />)}
-
-// With a function (becomes a computed internally):
-{when(() => user.get() !== null, () => <Profile />, () => <SignIn />)}
-```
-
-### Key Behavior
-
-- Swaps **only on truthiness transitions** (falsy to truthy, or truthy to falsy).
-- Value changes within the same branch (e.g., user changes from one user to another — both truthy) do **not** re-render the branch.
-- Components inside each branch should read signals to react to value changes.
-- Each branch gets its own dispose scope — effects created inside are cleaned up on swap.
-
-## `list(items, keyFn?, render)` — Keyed List Rendering
-
-Renders a reactive list with DOM diffing by key.
-
-```tsx
-import { list, text } from "@blueshed/railroad";
-
-const todos = signal([
-  { id: 1, text: "Buy milk" },
-  { id: 2, text: "Walk dog" },
-]);
-```
-
-### Keyed form (recommended)
-
-The render function receives **`Signal<T>`** and **`Signal<number>`** — not raw values. When the array updates and an existing key's value changes, the item signal is updated in place, so effects inside the rendered DOM react automatically without recreating the node.
-
-```tsx
-{list(todos, (t) => t.id, (todo, idx) =>
-  <li class={computed(() => todo.get().done ? "done" : "")}>
-    {text(() => todo.get().text)}
-  </li>
-)}
-```
-
-Use `.get()` inside `text()`, `computed()`, or `effect()` to subscribe to item changes. Use `.peek()` for one-off reads.
-
-### Non-keyed form (index-based, raw values)
-
-The render function receives the raw item value and index number. Items are recreated when the array changes.
-
-```tsx
-{list(todos, (t, i) => <li>{t.text}</li>)}
-```
-
-### How It Works
-
-- New items: rendered and inserted.
-- Removed items: disposed and removed from DOM.
-- Reordered items: moved in the DOM (not re-created).
-- **Keyed: changed items** update the existing item `Signal`, triggering reactive updates inside the node.
-- Each item gets its own dispose scope.
-
-## `Fragment` — Grouping Without a Wrapper
-
-```tsx
-import { createElement, Fragment } from "@blueshed/railroad";
-
-function Columns() {
-  return (
-    <>
-      <td>First</td>
-      <td>Second</td>
-    </>
-  );
-}
-```
-
-## Dispose Scopes
-
-The JSX layer manages cleanup automatically via dispose scopes. When `routes()` or `when()` swap content, all effects created during that content's rendering are disposed. You can also manage scopes manually:
-
-```tsx
-import { pushDisposeScope, popDisposeScope } from "@blueshed/railroad";
-
-pushDisposeScope();
-// ... create elements, effects ...
-const dispose = popDisposeScope();
-
-// later, clean up everything:
-dispose();
-```
-
-This is **required** when an effect creates JSX that may contain child effects, event handlers, or WebSocket listeners. Every effect that clears a container and appends new JSX **must** use this pattern:
-
-```tsx
-let childDispose: (() => void) | null = null;
-
-effect(() => {
-  const data = mySignal.get();
-  if (childDispose) { childDispose(); childDispose = null; }
-  container.innerHTML = "";
-  pushDisposeScope();
-  container.appendChild(<ChildComponent data={data} /> as Node);
-  childDispose = popDisposeScope();
-  return () => { if (childDispose) { childDispose(); childDispose = null; } };
-});
-```
-
-### Why the cleanup return matters
-
-The effect handles two lifecycle events:
-
-1. **Re-run** — when a tracked signal changes, the effect re-runs. The `if (childDispose)` call at the top cleans up the previous child scope before creating a new one.
-2. **Dispose** — when the effect itself is stopped (parent scope torn down, route change, `when()` swap), the cleanup function returned from the effect disposes the child scope. **Without this return, child effects leak when the parent is removed.**
-
-### Common mistake
-
-The most frequent porting bug is forgetting dispose scopes in effects that rebuild DOM. Any effect that does `container.innerHTML = ""; container.appendChild(<SomeJSX /> as Node)` needs this pattern. Static JSX with no signals, effects, or event listeners inside does not need it, but when in doubt, wrap it.

package/.claude/skills/railroad/routes.md

@@ -1,157 +0,0 @@
-# Routes — Hash-Based Client Router
-
-Railroad uses hash-based routing (`#/path`). The router swaps content in a target element and automatically manages dispose scoping — when a route changes, all effects from the previous route are cleaned up.
-
-## `routes(target, table)` — Declarative Router
-
-The main entry point. Pass a DOM element and a route table. Returns a dispose function to stop the router.
-
-```tsx
-import { createElement, routes } from "@blueshed/railroad";
-
-const app = document.getElementById("app")!;
-
-const dispose = routes(app, {
-  "/":            () => <Home />,
-  "/users/:id":   ({ id }) => <UserDetail id={id} />,
-  "/settings":    () => <Settings />,
-  "*":            () => <NotFound />,
-});
-```
-
-### Route Table
-
-- Keys are URL patterns (without the `#`).
-- Values are handler functions that receive matched params and return a Node.
-- Patterns are matched in declaration order — first match wins.
-- `*` is a catch-all, checked last.
-
-### Pattern Syntax
-
-- **Exact match:** `/about` matches only `#/about`
-- **Params:** `/users/:id` matches `#/users/42` with `{ id: "42" }`
-- **Multiple params:** `/users/:id/posts/:pid` matches `#/users/1/posts/99` with `{ id: "1", pid: "99" }`
-- **Catch-all:** `*` matches anything not matched by other patterns
-
-Segments must match exactly in count — `/users/:id` does not match `/users/42/extra`.
-
-URI components are automatically decoded (`%20` becomes a space, etc.).
-
-### Automatic Cleanup
-
-When the hash changes to a new route:
-
-1. The previous route's dispose scope is called (cleaning up all effects).
-2. The target element is cleared (`replaceChildren()`).
-3. A new dispose scope is pushed.
-4. The new handler runs, creating DOM and effects.
-5. The dispose scope is popped and stored for next cleanup.
-
-If the hash changes but the **same pattern** matches (e.g., `/users/1` to `/users/2`), the route does **not** re-render. The component should use signals or `route()` to react to param changes.
-
-## `navigate(path)` — Programmatic Navigation
-
-```ts
-import { navigate } from "@blueshed/railroad";
-
-navigate("/users/42");   // sets location.hash = "/users/42"
-navigate("/");           // go home
-```
-
-Use this in event handlers, after form submissions, etc. It triggers a `hashchange` event which the router picks up.
-
-### Navigation Links
-
-For `<a>` tags, use hash hrefs directly:
-
-```tsx
-<a href="#/users/42">View User</a>
-<a href="#/settings">Settings</a>
-```
-
-Or use `navigate()` in an onclick:
-
-```tsx
-<button onclick={() => navigate(`/users/${id}`)}>View</button>
-```
-
-## `route(pattern)` — Reactive Route Signal
-
-Returns a `Signal<T | null>` that is non-null when the pattern matches the current hash, null otherwise. Useful for components that need to react to route changes without being inside the router.
-
-```ts
-import { route } from "@blueshed/railroad";
-
-const userRoute = route<{ id: string }>("/users/:id");
-
-effect(() => {
-  const params = userRoute.get();
-  if (params) {
-    console.log(`Viewing user ${params.id}`);
-  }
-});
-```
-
-This is useful for:
-- Highlighting the active nav link.
-- Loading data when params change within the same route pattern.
-- Reacting to route changes from anywhere in the app.
-
-## `matchRoute(pattern, path)` — Pure Pattern Matcher
-
-A utility function with no side effects. Returns params object on match, `null` on no match.
-
-```ts
-import { matchRoute } from "@blueshed/railroad";
-
-matchRoute("/users/:id", "/users/42");       // { id: "42" }
-matchRoute("/users/:id", "/users/42/extra"); // null (segment count mismatch)
-matchRoute("/about", "/about");              // {}
-matchRoute("/about", "/home");               // null
-```
-
-## Handling Param Changes Within a Route
-
-When navigating from `/users/1` to `/users/2`, the router sees the same pattern (`/users/:id`) and does **not** re-render. The component must handle this itself:
-
-```tsx
-import { createElement, route, when, signal, effect } from "@blueshed/railroad";
-
-function UserDetail({ id }: { id: string }) {
-  // Option 1: Use route() signal to track param changes
-  const userRoute = route<{ id: string }>("/users/:id");
-  const user = signal<User | null>(null);
-
-  effect(() => {
-    const params = userRoute.get();
-    if (params) {
-      fetchUser(params.id).then(u => user.set(u));
-    }
-  });
-
-  return when(user, () => <div>{user.get()!.name}</div>);
-}
-```
-
-## Server-Side Pattern
-
-Railroad's route tables mirror Bun.serve's route syntax. A typical app has both:
-
-```ts
-// server.ts — Bun serves the HTML shell
-import home from "./index.html";
-Bun.serve({
-  routes: {
-    "/": home,
-    "/api/users": () => Response.json(users),
-  },
-});
-
-// app.tsx — client-side routing inside the shell
-routes(document.getElementById("app")!, {
-  "/":           () => <Home />,
-  "/users/:id":  ({ id }) => <UserDetail id={id} />,
-});
-```
-
-Resources and routes. Server and client. Same pattern.

package/.claude/skills/railroad/shared.md

@@ -1,94 +0,0 @@
-# Shared — Typed Dependency Injection
-
-A minimal provide/inject system for sharing values across modules without prop threading. Uses typed symbol keys for safety.
-
-## Creating a Key
-
-```ts
-import { key } from "@blueshed/railroad";
-
-const STORE = key<AppStore>("store");
-const THEME = key<Signal<string>>("theme");
-const API = key<ApiClient>("api");
-```
-
-`key<T>(name)` creates a unique symbol branded with type `T`. The name is for debugging (shows in error messages).
-
-## Providing a Value
-
-```ts
-import { provide } from "@blueshed/railroad";
-
-provide(STORE, createStore());
-provide(THEME, signal("light"));
-provide(API, new ApiClient("/api"));
-```
-
-Call `provide()` during initialization, before any component calls `inject()`. Values are stored in a global registry.
-
-## Injecting a Value
-
-```ts
-import { inject } from "@blueshed/railroad";
-
-const store = inject(STORE);  // typed as AppStore
-const theme = inject(THEME);  // typed as Signal<string>
-```
-
-If no value has been provided for the key, `inject()` throws:
-
-```
-Error: No provider for store
-```
-
-## Typical Pattern
-
-Define keys in a shared module, provide at app init, inject anywhere:
-
-```ts
-// keys.ts — shared key definitions
-import { key } from "@blueshed/railroad";
-import type { Signal } from "@blueshed/railroad";
-
-export interface AppStore {
-  user: Signal<User | null>;
-  todos: Signal<Todo[]>;
-}
-
-export const STORE = key<AppStore>("store");
-```
-
-```ts
-// main.ts — provide at startup
-import { provide, signal } from "@blueshed/railroad";
-import { STORE } from "./keys";
-
-provide(STORE, {
-  user: signal(null),
-  todos: signal([]),
-});
-```
-
-```tsx
-// any-component.tsx — inject where needed
-import { createElement } from "@blueshed/railroad";
-import { inject } from "@blueshed/railroad";
-import { STORE } from "./keys";
-
-function TodoList() {
-  const { todos } = inject(STORE);
-  return list(todos, (t) => t.id, (t) => <li>{t.text}</li>);
-}
-```
-
-## When to Use Shared vs Props
-
-- **Props** — for data that flows parent-to-child and varies per instance.
-- **Shared** — for app-wide services, stores, or configuration that many components need. Avoids threading the same value through every intermediate component.
-
-## Important Notes
-
-- The registry is global and module-scoped. There is one registry per JavaScript realm.
-- Keys are symbols, so two calls to `key("store")` produce **different** keys. Export and import a single key instance.
-- `provide()` can be called again with the same key to replace the value.
-- `inject()` is synchronous — the value must already be provided.

package/.claude/skills/railroad/signals.md

@@ -1,218 +0,0 @@
-# Signals — Reactive State
-
-Signals are the foundation of railroad. Everything reactive flows from them.
-
-## Creating Signals
-
-```ts
-import { signal } from "@blueshed/railroad";
-
-const count = signal(0);          // Signal<number>
-const name = signal("World");     // Signal<string>
-const items = signal<string[]>([]); // Signal<string[]>
-```
-
-## Reading and Writing
-
-```ts
-count.get()              // read (tracks dependency inside effect/computed)
-count.set(5)             // write (notifies listeners if value changed)
-count.update(n => n + 1) // transform and write (caller must return a new value)
-count.mutate(v => ...)   // clone, mutate in place, notify (see below)
-count.patch({ key: v })  // shallow merge for object signals (see below)
-count.peek()             // read WITHOUT tracking — use for one-off reads outside effects
-```
-
-### Equality Check
-
-`set()` uses `Object.is()` to compare old and new values. If they are the same, no listeners are notified. This means:
-
-- Primitives: setting the same number/string/boolean is a no-op.
-- Objects/arrays: you must create a new reference to trigger updates.
-
-```ts
-const todos = signal([{ id: 1, text: "Buy milk" }]);
-
-// WRONG — same array reference, no update:
-todos.peek().push({ id: 2, text: "Walk dog" });
-todos.set(todos.peek()); // Object.is says same reference, listeners NOT notified
-
-// RIGHT — new array:
-todos.update(arr => [...arr, { id: 2, text: "Walk dog" }]);
-```
-
-### `mutate(fn)` — In-Place Mutation
-
-`mutate()` clones the current value with `structuredClone`, passes the clone to your function for in-place mutation, then notifies listeners. Use it when you want to modify objects or arrays naturally without manually creating a new reference.
-
-```ts
-const todos = signal([{ id: 1, text: "Buy milk" }]);
-
-// Append:
-todos.mutate(arr => arr.push({ id: 2, text: "Walk dog" }));
-
-// Modify nested property:
-const doc = signal({ title: "Draft", meta: { tags: ["a"] } });
-doc.mutate(d => d.meta.tags.push("b"));
-
-// Toggle in a Set:
-const selected = signal(new Set([1, 2, 3]));
-selected.mutate(s => s.has(4) ? s.delete(4) : s.add(4));
-```
-
-`mutate()` always notifies listeners (the clone guarantees a new reference). Use `update()` when you can return a new value cheaply; use `mutate()` when in-place mutation is more natural.
-
-### `patch(partial)` — Shallow Merge
-
-`patch()` does a shallow merge for object signals — equivalent to `set({ ...current, ...partial })`:
-
-```ts
-const filter = signal({ color: "red", size: 10, active: true });
-
-filter.patch({ color: "blue" });           // { color: "blue", size: 10, active: true }
-filter.patch({ size: 20, active: false }); // { color: "blue", size: 20, active: false }
-```
-
-Like `set()`, `patch()` uses `Object.is` — since the spread always creates a new reference, listeners are always notified.
-
-## Computed Signals
-
-Derived read-only signals that auto-update when dependencies change.
-
-```ts
-import { computed } from "@blueshed/railroad";
-
-const firstName = signal("John");
-const lastName = signal("Doe");
-const fullName = computed(() => `${firstName.get()} ${lastName.get()}`);
-
-fullName.get(); // "John Doe"
-firstName.set("Jane");
-fullName.get(); // "Jane Doe"
-```
-
-Computed signals chain:
-
-```ts
-const a = signal(1);
-const b = computed(() => a.get() + 1);   // 2
-const c = computed(() => b.get() * 10);  // 20
-a.set(3);
-c.get(); // 40
-```
-
-## Effects
-
-Run a function whenever its signal dependencies change. The function runs immediately on creation.
-
-```ts
-import { effect } from "@blueshed/railroad";
-
-const count = signal(0);
-
-const dispose = effect(() => {
-  console.log(`count is ${count.get()}`);
-});
-// logs: "count is 0"
-
-count.set(1);
-// logs: "count is 1"
-
-dispose(); // stop listening
-count.set(2); // nothing logged
-```
-
-### Cleanup Functions
-
-An effect can return a cleanup function. It runs before each re-execution and on dispose.
-
-```ts
-effect(() => {
-  const id = setInterval(() => console.log(count.get()), 1000);
-  return () => clearInterval(id); // cleanup before re-run or on dispose
-});
-```
-
-### Automatic Dependency Tracking
-
-Effects only track signals read during execution. If a branch is not taken, those signals are not tracked:
-
-```ts
-const showDetail = signal(true);
-const summary = signal("short");
-const detail = signal("long");
-
-effect(() => {
-  if (showDetail.get()) {
-    console.log(detail.get());   // tracked
-  } else {
-    console.log(summary.get());  // tracked only when showDetail is false
-  }
-});
-
-// When showDetail is true, changing summary does NOT re-run the effect.
-```
-
-### Infinite Loop Protection
-
-Effects are guarded against infinite loops (max depth 100). If an effect sets a signal that triggers itself in a cycle, it throws:
-
-```
-Error: Maximum effect depth exceeded — possible infinite loop
-```
-
-## Batch
-
-Group multiple signal writes so effects run only once at the end.
-
-```ts
-import { batch } from "@blueshed/railroad";
-
-const a = signal(1);
-const b = signal(2);
-
-effect(() => {
-  console.log(a.get() + b.get());
-});
-// logs: 3
-
-batch(() => {
-  a.set(10);
-  b.set(20);
-});
-// logs: 30 (once, not twice)
-```
-
-Batches nest safely — effects flush only when the outermost batch completes.
-
-## Dispose Pattern
-
-`effect()` returns a dispose function. Call it to stop the effect and run its cleanup.
-
-The JSX layer manages dispose scopes automatically — effects created during component rendering are collected and disposed when the component is removed (e.g., by the router or `when()`). You rarely need to manage dispose manually unless you create effects outside of JSX rendering.
-
-```ts
-// Manual dispose (outside JSX):
-const dispose = effect(() => { ... });
-// later:
-dispose();
-
-// Inside JSX components, effects are auto-collected.
-// The router or when() calls dispose when swapping content.
-```
-
-## Where to Declare Signals
-
-- **Module level** — shared state, lives for the app lifetime. Good for stores, global UI state.
-- **Inside a component** — local state, created fresh each time the component mounts. Disposed when the component is removed.
-
-```ts
-// Module level — shared, persistent
-const currentUser = signal<User | null>(null);
-
-// Component level — local, ephemeral
-function SearchBox() {
-  const query = signal("");
-  return <input value={query} oninput={(e) => query.set(e.target.value)} />;
-}
-```