@blueshed/railroad 0.2.0

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

@@ -0,0 +1,218 @@
+# 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)} />;
+}
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 blueshed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,234 @@
+# Railroad
+
+Signals, JSX, and routes — a micro UI framework for Bun.
+
+~400 lines. Zero dependencies. Real DOM. No virtual DOM, no compiler, no build step.
+
+## Install
+
+```sh
+bun add @blueshed/railroad
+```
+
+## Quick Start
+
+### Automatic runtime (recommended)
+
+No JSX imports needed — the compiler inserts them for you.
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "@blueshed/railroad"
+  }
+}
+```
+
+```tsx
+// app.tsx
+import { signal, routes } from "@blueshed/railroad";
+
+const count = signal(0);
+
+function Home() {
+  return (
+    <div>
+      <h1>Hello World</h1>
+      <button onclick={() => count.update(n => n + 1)}>
+        Count: {count}
+      </button>
+    </div>
+  );
+}
+
+routes(document.getElementById("app")!, {
+  "/": () => <Home />,
+});
+```
+
+### Classic runtime
+
+If you prefer explicit imports:
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "jsx": "react",
+    "jsxFactory": "createElement",
+    "jsxFragmentFactory": "Fragment"
+  }
+}
+```
+
+```tsx
+// app.tsx
+import { createElement, signal, routes } from "@blueshed/railroad";
+
+const count = signal(0);
+
+function Home() {
+  return (
+    <div>
+      <h1>Hello World</h1>
+      <button onclick={() => count.update(n => n + 1)}>
+        Count: {count}
+      </button>
+    </div>
+  );
+}
+
+routes(document.getElementById("app")!, {
+  "/": () => <Home />,
+});
+```
+
+### Server
+
+```ts
+// server.ts
+import home from "./index.html";
+
+Bun.serve({
+  routes: { "/": home },
+});
+```
+
+Resources and routes. Server and client. Same pattern.
+
+## API
+
+### Signals
+
+```ts
+import { signal, computed, effect, batch } from "@blueshed/railroad";
+
+const count = signal(0);
+const doubled = computed(() => count.get() * 2);
+
+const dispose = effect(() => {
+  console.log(`count is ${count.get()}`);
+});
+
+count.set(1);        // logs "count is 1"
+count.update(n => n + 1); // logs "count is 2"
+count.peek();        // read without tracking
+
+// In-place mutation (auto-clones, always notifies):
+const todos = signal([{ id: 1, text: "Buy milk" }]);
+todos.mutate(arr => arr.push({ id: 2, text: "Walk dog" }));
+
+// Shallow merge for object signals:
+const filter = signal({ color: "red", size: 10 });
+filter.patch({ color: "blue" }); // { color: "blue", size: 10 }
+
+batch(() => {
+  count.set(10);
+  count.set(20);     // effect runs once, not twice
+});
+
+dispose();           // stop listening
+```
+
+### JSX
+
+Components are functions that return DOM nodes. Signals in children and props auto-update.
+
+```tsx
+import { createElement, text, when, list, signal } from "@blueshed/railroad";
+
+const name = signal("World");
+
+function Greeting() {
+  return <h1>Hello {name}</h1>;  // updates when name changes
+}
+```
+
+#### `text(fn)` — reactive computed text
+
+```tsx
+<span>{text(() => count.get() > 5 ? "High" : "Low")}</span>
+```
+
+#### `when(condition, truthy, falsy?)` — conditional rendering
+
+```tsx
+{when(
+  () => loggedIn.get(),
+  () => <Dashboard />,
+  () => <Login />,
+)}
+```
+
+#### `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>,
+)}
+
+// Non-keyed (index-based, raw values):
+{list(items, (item, i) => <li>{item}</li>)}
+```
+
+### Routes
+
+Hash-based client router with automatic dispose scoping.
+
+```tsx
+import { routes, navigate } from "@blueshed/railroad";
+
+const dispose = routes(app, {
+  "/":           () => <Home />,
+  "/users/:id":  ({ id }) => <User id={id} />,
+  "*":           () => <NotFound />,
+});
+
+navigate("/users/42");
+```
+
+### Shared
+
+Typed dependency injection without prop threading.
+
+```ts
+import { key, provide, inject } from "@blueshed/railroad";
+
+const STORE = key<AppStore>("store");
+provide(STORE, createStore());
+
+// anywhere:
+const store = inject(STORE);
+```
+
+## Design
+
+- **Signals hold state** — reactive primitives with automatic dependency tracking
+- **Effects update the DOM** — run when dependencies change, return cleanup
+- **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
+
+No lifecycle methods. No hooks rules. No context providers. No `useCallback`. Just signals and the DOM.
+
+## 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:
+
+```sh
+cp -r node_modules/@blueshed/railroad/.claude/skills/railroad .claude/skills/
+```
+
+Or install it user-wide (available in all projects):
+
+```sh
+cp -r node_modules/@blueshed/railroad/.claude/skills/railroad ~/.claude/skills/
+```
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,18 @@
+// Railroad — Signals, JSX, and Routes
+
+export { Signal, signal, computed, effect, batch } from "./signals";
+export type { Dispose } from "./signals";
+
+export {
+  createElement, Fragment,
+  text, when, list,
+  pushDisposeScope, popDisposeScope,
+} from "./jsx";
+
+export { routes, route, navigate, matchRoute } from "./routes";
+
+export { key, provide, inject, tryInject } from "./shared";
+export type { Key } from "./shared";
+
+export { createLogger, setLogLevel, getLogLevel, loggedRequest } from "./logger";
+export type { LogLevel } from "./logger";

package/jsx-dev-runtime.ts

@@ -0,0 +1,4 @@
+// Development JSX runtime — re-exports the production runtime.
+// Required for TypeScript's "jsx": "react-jsxdev" mode.
+
+export { jsx, jsx as jsxDEV, jsxs, Fragment, type JSX } from "./jsx-runtime";

package/jsx-runtime.ts

@@ -0,0 +1,35 @@
+/**
+ * Automatic JSX Runtime for Railroad
+ *
+ * Enables "jsx": "react-jsx" / jsxImportSource so consumers
+ * can write JSX without importing createElement.
+ *
+ * tsconfig.json:
+ *   { "jsx": "react-jsx", "jsxImportSource": "@blueshed/railroad" }
+ */
+
+import { createElement, Fragment } from "./jsx";
+
+export { Fragment };
+
+export function jsx(
+  type: string | Function,
+  props: Record<string, any> | null,
+  _key?: string,
+): Node {
+  if (!props) return createElement(type, null);
+  const { children, ...rest } = props;
+  if (children === undefined) return createElement(type, rest);
+  if (Array.isArray(children)) return createElement(type, rest, ...children);
+  return createElement(type, rest, children);
+}
+
+export { jsx as jsxs };
+
+// Re-export JSX namespace so TypeScript react-jsx mode finds the types
+export namespace JSX {
+  export type Element = globalThis.Node;
+  export interface IntrinsicElements {
+    [tag: string]: any;
+  }
+}