@blueshed/railroad 0.2.0

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

@@ -0,0 +1,86 @@
+# Railroad — Skill for Claude
+
+You are helping a developer build a UI with `@blueshed/railroad`, a micro reactive framework for Bun.
+
+## What Railroad Is
+
+- ~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).
+
+## 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.
+
+## Critical Setup
+
+### Automatic runtime (recommended)
+
+No JSX imports needed — the compiler inserts them automatically.
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "@blueshed/railroad"
+  }
+}
+```
+
+### Classic runtime
+
+If the project uses explicit imports, every `.tsx` file that uses JSX **must** import `createElement` (and `Fragment` if using `<>...</>`):
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react",
+    "jsxFactory": "createElement",
+    "jsxFragmentFactory": "Fragment"
+  }
+}
+```
+
+Check the project's `tsconfig.json` to see which mode is in use. Prefer the automatic runtime for new projects.
+
+A minimal Bun server to serve the app:
+
+```ts
+import home from "./index.html";
+Bun.serve({ routes: { "/": home } });
+```
+
+## How to Import
+
+```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";
+```
+
+## Reference Docs
+
+Detailed usage for each concern is in the sibling files. Read them before generating railroad code:
+
+- `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
+
+## Anti-Patterns — Do NOT Do These
+
+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.

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

@@ -0,0 +1,325 @@
+# 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

@@ -0,0 +1,157 @@
+# 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

@@ -0,0 +1,94 @@
+# 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.