@blueshed/railroad 0.3.4 → 0.4.0

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

@@ -1,94 +1,60 @@
-# Railroad — Skill for Claude
+---
+name: railroad
+description: "Railroad — micro reactive UI framework for Bun. Use when writing JSX components with signals, routes, when(), list(), 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`
 
 ## 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 } });
-```
-
-## API Quick Reference
-
-### Signals (`signals.ts`)
-
-```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
-```
-
-Signal methods: `.get()` `.set(v)` `.update(fn)` `.mutate(fn)` `.patch(partial)` `.peek()`
-
-Dispose scopes: `pushDisposeScope()` `popDisposeScope(): Dispose` `trackDispose(fn)`
-
-### JSX (`jsx.ts`)
+## Mental Model
 
-Components are functions called **once**. Reactivity comes from signals, not re-rendering.
+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.
 
-```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.
-
-SVG: `<svg>` children are auto-adopted into SVG namespace.
-
-### Routes (`routes.ts`)
+```tsx
+// Bare signal — auto-reactive
+<span>{count}</span>
 
-```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
-```
-
-Handlers receive `(params, params$)` — plain object + Signal. Destructure the first, watch the second for same-pattern param changes (e.g. `/users/1` → `/users/2`).
+// Function child — auto-reactive expression
+<span>{() => count.get() > 5 ? "High" : "Low"}</span>
 
-### Shared (`shared.ts`)
-
-```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)
+// 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>)}
 ```
 
-### Logger (`logger.ts`)
-
-```ts
-createLogger(tag): { info, warn, error, debug }
-setLogLevel(level): void             // "error" | "warn" | "info" | "debug"
-loggedRequest(tag, handler): Handler // wrap route handler with access logging
+## 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 />);
+}
 ```
 
 ## 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/index.ts

@@ -5,8 +5,7 @@ export type { Dispose } from "./signals";
 
 export {
   createElement, Fragment,
-  text, when, list,
-  pushDisposeScope, popDisposeScope,
+  when, list,
 } from "./jsx";
 
 export { routes, route, navigate, matchRoute } from "./routes";

package/jsx.ts

@@ -5,11 +5,16 @@
  *   - tag: string → creates HTML element (or SVG element inside <svg>)
  *   - tag: function → calls component function(props)
  *   - props: attributes, event handlers (onclick etc), ref
- *   - children: string, number, Node, Signal<T>, arrays, null/undefined
+ *   - children: string, number, Node, Signal<T>, () => any, arrays, null/undefined
  *
  * When a Signal is used as a child, an effect auto-updates the text node.
+ * When a function is used as a child, it auto-tracks dependencies:
+ *   <span>{() => count.get() > 5 ? "High" : "Low"}</span>
  * When a Signal is used as a prop value, an effect auto-updates the attribute.
  *
+ * Components are auto-scoped — effects/computeds inside are disposed when
+ * the parent scope (route, when, list) tears down. No manual dispose needed.
+ *
  * SVG support:
  *   <svg> is created with the SVG namespace. Any HTML children appended to
  *   an SVG-namespaced parent are automatically adopted into the SVG namespace.
@@ -20,13 +25,12 @@
  *   when(signal, truthy, falsy?)  — conditional rendering, swaps DOM nodes
  *   list(signal, keyFn, render)   — keyed reactive list, render receives Signal<T>
  *   list(signal, render)          — index-based reactive list, render receives raw T
- *   text(fn)                      — reactive text from computed expression
  */
 
 import { Signal, signal, effect, computed, pushDisposeScope, popDisposeScope, trackDispose } from "./signals";
 import type { Dispose } from "./signals";
 
-export { pushDisposeScope, popDisposeScope };
+// pushDisposeScope / popDisposeScope are internal — used by createElement, when, list, routes
 
 // === SVG namespace ===
 
@@ -52,35 +56,35 @@ function applyProps(el: Element, props: Record<string, any>): void {
       if (typeof value === "function") value(el);
     } else if (key === "innerHTML") {
       if (value instanceof Signal) {
-        trackDispose(effect(() => { el.innerHTML = value.get(); }));
+        effect(() => { el.innerHTML = value.get(); });
       } else {
         el.innerHTML = value;
       }
     } else if (key === "className" || key === "class") {
       if (value instanceof Signal) {
-        trackDispose(effect(() => { el.setAttribute("class", value.get()); }));
+        effect(() => { el.setAttribute("class", value.get()); });
       } else {
         el.setAttribute("class", value);
       }
     } else if (key === "value" || key === "checked" || key === "disabled" || key === "selected" || key === "srcdoc" || key === "src") {
       if (value instanceof Signal) {
-        trackDispose(effect(() => { (el as any)[key] = value.get(); }));
+        effect(() => { (el as any)[key] = value.get(); });
       } else {
         (el as any)[key] = value;
       }
     } else if (key === "style" && value instanceof Signal) {
-      trackDispose(effect(() => { Object.assign((el as HTMLElement).style, value.get()); }));
+      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 {
       if (value instanceof Signal) {
-        trackDispose(effect(() => {
+        effect(() => {
           const v = value.get();
           if (v === false || v == null) el.removeAttribute(key);
           else el.setAttribute(key, String(v));
-        }));
+        });
       } else if (value !== false && value != null) {
         el.setAttribute(key, String(value));
       }
@@ -96,8 +100,12 @@ export function createElement(
   ...children: any[]
 ): Node {
   if (typeof tag === "function") {
+    pushDisposeScope();
     const componentProps = { ...props, children };
-    return tag(componentProps);
+    const node = tag(componentProps);
+    const dispose = popDisposeScope();
+    trackDispose(dispose);
+    return node;
   }
 
   // SVG root element is always created with the SVG namespace.
@@ -160,10 +168,17 @@ function appendChildren(parent: Node, children: any[]): void {
 
     if (child instanceof Signal) {
       const text = document.createTextNode(String(child.peek()));
-      trackDispose(effect(() => {
+      effect(() => {
         text.textContent = String(child.get());
-      }));
+      });
       parent.appendChild(text);
+    } else if (typeof child === "function") {
+      const fn = child as () => any;
+      const textNode = document.createTextNode("");
+      effect(() => {
+        textNode.textContent = String(fn() ?? "");
+      });
+      parent.appendChild(textNode);
     } else if (child instanceof Node) {
       // Adopt HTML elements into SVG namespace when parent is SVG
       if (isSvgParent &&
@@ -179,17 +194,6 @@ function appendChildren(parent: Node, children: any[]): void {
   }
 }
 
-// === text() — reactive computed text node ===
-// Use for expressions: text(() => count.get() > 5 ? "High" : "Low")
-
-export function text(fn: () => string): Node {
-  const value = computed(fn);
-  const node = document.createTextNode(value.peek());
-  trackDispose(effect(() => {
-    node.textContent = value.get();
-  }));
-  return node;
-}
 
 // === when() — conditional rendering ===
 // Swaps DOM nodes only when truthiness transitions (falsy↔truthy).
@@ -203,7 +207,7 @@ export function when(
   falsy?: () => Node,
 ): Node {
   const anchor = document.createComment("when");
-  let current: Node | null = null;
+  let currentNodes: Node[] = [];
   let currentDispose: Dispose | null = null;
   let wasTruthy: boolean | undefined = undefined;
 
@@ -218,32 +222,33 @@ export function when(
     wasTruthy = isTruthy;
 
     if (currentDispose) currentDispose();
-    if (current && anchor.parentNode) {
-      anchor.parentNode.removeChild(current);
-    }
+    for (const n of currentNodes) n.parentNode?.removeChild(n);
+    currentNodes = [];
 
     pushDisposeScope();
-    current = isTruthy ? truthy() : (falsy ? falsy() : null);
+    const result = isTruthy ? truthy() : (falsy ? falsy() : null);
     currentDispose = popDisposeScope();
 
-    if (current && anchor.parentNode) {
-      anchor.parentNode.insertBefore(current, anchor.nextSibling);
+    if (result && anchor.parentNode) {
+      // Capture actual child nodes before fragment is emptied by insertBefore
+      currentNodes = result instanceof DocumentFragment
+        ? [...result.childNodes]
+        : [result];
+      anchor.parentNode.insertBefore(result, anchor.nextSibling);
     }
   }
 
-  trackDispose(effect(() => {
+  effect(() => {
     sig.get(); // track
     if (!anchor.parentNode) {
       queueMicrotask(swap);
     } else {
       swap();
     }
-  }));
+  });
 
-  // Return a fragment: anchor + initial content
   const frag = document.createDocumentFragment();
   frag.appendChild(anchor);
-  if (current) frag.appendChild(current);
   return frag;
 }
 
@@ -252,11 +257,17 @@ export function when(
 //
 // Keyed form — render receives Signal<T> and Signal<number> so item
 // updates flow into existing DOM without re-creating nodes:
-//   list(items, (t) => t.id, (item, index) => <li>{text(() => item.get().name)}</li>)
+//   list(items, (t) => t.id, (item$) => <li>{item$.map(t => t.name)}</li>)
 //
 // Non-keyed form (index-based, raw values):
 //   list(items, (item, index) => <li>{item}</li>)
 
+function collectNodes(result: Node): Node[] {
+  return result instanceof DocumentFragment
+    ? [...result.childNodes]
+    : [result];
+}
+
 export function list<T>(
   items: Signal<T[]>,
   keyFnOrRender: ((item: T) => string | number) | ((item: T, index: number) => Node),
@@ -265,7 +276,7 @@ export function list<T>(
   const hasKeyFn = maybeRender !== undefined;
   const keyFn = hasKeyFn ? keyFnOrRender as (item: T) => string | number : null;
 
-  type Entry = { node: Node; dispose: Dispose; item?: Signal<T>; index?: Signal<number> };
+  type Entry = { nodes: Node[]; dispose: Dispose; item?: Signal<T>; index?: Signal<number> };
   const anchor = document.createComment("list");
   let entries: Map<string | number, Entry> = new Map();
   let order: (string | number)[] = [];
@@ -274,7 +285,7 @@ export function list<T>(
     const entry = entries.get(key);
     if (entry) {
       entry.dispose();
-      entry.node.parentNode?.removeChild(entry.node);
+      for (const n of entry.nodes) n.parentNode?.removeChild(n);
       entries.delete(key);
     }
   }
@@ -282,7 +293,7 @@ export function list<T>(
   function clearAll() {
     for (const [, entry] of entries) {
       entry.dispose();
-      entry.node.parentNode?.removeChild(entry.node);
+      for (const n of entry.nodes) n.parentNode?.removeChild(n);
     }
     entries = new Map();
     order = [];
@@ -310,17 +321,17 @@ export function list<T>(
       if (!entry) {
         // New item — create
         pushDisposeScope();
-        let node: Node;
+        let result: Node;
         if (hasKeyFn) {
           const itemSig = signal(arr[i]!);
           const indexSig = signal(i);
-          node = maybeRender!(itemSig, indexSig);
+          result = maybeRender!(itemSig, indexSig);
           const dispose = popDisposeScope();
-          entry = { node, dispose, item: itemSig, index: indexSig };
+          entry = { nodes: collectNodes(result), dispose, item: itemSig, index: indexSig };
         } else {
-          node = (keyFnOrRender as (item: T, index: number) => Node)(arr[i]!, i);
+          result = (keyFnOrRender as (item: T, index: number) => Node)(arr[i]!, i);
           const dispose = popDisposeScope();
-          entry = { node, dispose };
+          entry = { nodes: collectNodes(result), dispose };
         }
         entries.set(key, entry);
       } else if (hasKeyFn) {
@@ -329,34 +340,43 @@ export function list<T>(
         entry.index!.set(i);
       } else {
         // Index-based — dispose old, recreate with new item
-        const oldNode = entry.node;
+        const oldNodes = entry.nodes;
         entry.dispose();
         pushDisposeScope();
-        const node = (keyFnOrRender as (item: T, index: number) => Node)(arr[i]!, i);
+        const result = (keyFnOrRender as (item: T, index: number) => Node)(arr[i]!, i);
         const dispose = popDisposeScope();
-        entry = { node, dispose };
+        const nodes = collectNodes(result);
+        entry = { nodes, dispose };
         entries.set(key, entry);
-        if (oldNode.parentNode) oldNode.parentNode.replaceChild(node, oldNode);
+        const ref = oldNodes[oldNodes.length - 1]?.nextSibling ?? null;
+        const oldParent = oldNodes[0]?.parentNode;
+        for (const n of oldNodes) n.parentNode?.removeChild(n);
+        if (oldParent) {
+          for (const n of nodes) oldParent.insertBefore(n, ref);
+        }
       }
 
       // Move or insert into correct position
-      if (entry.node.nextSibling !== insertBefore) {
-        parent.insertBefore(entry.node, insertBefore);
+      const lastNode = entry.nodes[entry.nodes.length - 1];
+      if (lastNode?.nextSibling !== insertBefore) {
+        for (const n of entry.nodes) {
+          parent.insertBefore(n, insertBefore);
+        }
       }
-      insertBefore = entry.node;
+      insertBefore = entry.nodes[0] ?? insertBefore;
     }
 
     order = newKeys;
   }
 
-  trackDispose(effect(() => {
+  effect(() => {
     items.get(); // track
     if (!anchor.parentNode) {
       queueMicrotask(sync);
     } else {
       sync();
     }
-  }));
+  });
 
   trackDispose(() => clearAll());
 

package/package.json

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

package/routes.ts

@@ -7,20 +7,31 @@
  *   navigate(path)          — set location.hash programmatically
  *   matchRoute(pattern, path) — pure pattern matcher, returns params or null
  *
+ * Patterns:
+ *   "/users/:id"     — named params, exact segment match
+ *   "/sites/*"       — wildcard, matches /sites and /sites/any/depth
+ *   "/sites/:id/*"   — params + wildcard, rest captured as params["*"]
+ *
  * 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.
+ *
+ * Nested routes — use wildcard to keep a layout mounted:
  *   routes(app, {
  *     "/":          () => <Home />,
- *     "/site/:id":  ({ id }, params$) => <SiteDetail id={id} params$={params$} />,
- *     "/status":    async () => { const s = await api.get(); return <Status data={s} />; },
+ *     "/sites/*":   () => <SitesLayout />,
  *   });
+ *   // Inside SitesLayout, use route() for sub-navigation:
+ *   const detail = route("/sites/:id");
+ *
+ * Both routes() and route() auto-track in the parent dispose scope,
+ * so nested routing cleans up when the parent scope tears down.
  */
 
-import { Signal, signal, computed, effect, pushDisposeScope, popDisposeScope } from "./signals";
+import { Signal, signal, computed, effect, pushDisposeScope, popDisposeScope, trackDispose } from "./signals";
 import type { Dispose } from "./signals";
 
 let hashSignal: Signal<string> | null = null;
@@ -54,10 +65,22 @@ export function matchRoute(
 ): Record<string, string> | null {
   const pp = pattern.split("/");
   const hp = path.split("/");
-  if (pp.length !== hp.length) return null;
+  const isWild = pp.length > 0 && pp[pp.length - 1] === "*";
+
+  if (isWild) {
+    if (hp.length < pp.length - 1) return null;
+  } else {
+    if (pp.length !== hp.length) return null;
+  }
+
   const params: Record<string, string> = {};
   for (let i = 0; i < pp.length; i++) {
-    if (pp[i]!.startsWith(":")) {
+    if (pp[i] === "*") {
+      params["*"] = hp.slice(i).map(s => {
+        try { return decodeURIComponent(s); } catch { return s; }
+      }).join("/");
+      return params;
+    } else if (pp[i]!.startsWith(":")) {
       try {
         params[pp[i]!.slice(1)] = decodeURIComponent(hp[i]!);
       } catch {
@@ -72,6 +95,7 @@ export function route<
   T extends Record<string, string> = Record<string, string>,
 >(pattern: string): Signal<T | null> {
   const hash = getHash();
+  trackDispose(() => releaseHash());
   return computed(() => matchRoute(pattern, hash.get()) as T | null);
 }
 
@@ -144,20 +168,14 @@ export function routes(
         return;
       }
     }
-    if (table["*"]) {
-      if (activePattern !== "*") {
-        teardown();
-        activePattern = "*";
-        run(table["*"], {});
-      }
-      return;
-    }
     teardown();
   });
 
-  return () => {
+  const dispose = () => {
     disposeEffect();
     teardown();
     releaseHash();
   };
+  trackDispose(dispose);
+  return dispose;
 }

package/signals.ts

@@ -16,6 +16,7 @@
  *   .mutate(fn)             — structuredClone, mutate in place, notify: s.mutate(v => v.items.push(x))
  *   .patch(partial)         — shallow merge for object signals: s.patch({ name: "new" })
  *   .peek()                 — read value without tracking
+ *   .map(fn)                — derive a new signal: s.map(v => v.name)
  *
  * Dependency tracking:
  *   Effects automatically track which signals are read during execution.
@@ -24,7 +25,8 @@
  *
  * Dispose pattern:
  *   effect() can return a cleanup function, called before each re-run and on dispose.
- *   Components should collect dispose functions and return a combined Dispose.
+ *   effect() and computed() auto-track in the current dispose scope —
+ *   no manual trackDispose() needed inside components.
  */
 
 type Listener = () => void;
@@ -81,6 +83,10 @@ export class Signal<T> {
     return this.value;
   }
 
+  map<U>(fn: (value: T) => U): Signal<U> {
+    return computed(() => fn(this.get()));
+  }
+
   private notify(): void {
     if (batchDepth > 0) {
       for (const listener of this.listeners) pendingEffects.add(listener);
@@ -133,13 +139,16 @@ export function effect(fn: () => void | (() => void)): () => void {
     deps = nextDeps;
   };
 
-  execute();
-
-  return () => {
+  const dispose = () => {
     if (cleanup) cleanup();
     for (const dep of deps) dep.unsubscribe(execute);
     deps.clear();
   };
+
+  trackDispose(dispose);
+  execute();
+
+  return dispose;
 }
 
 // === Dispose type & scope management ===
@@ -178,8 +187,7 @@ export function computed<T>(fn: () => T): Signal<T> {
     currentDeps = prevDeps;
   }
   const s = new Signal<T>(initial);
-  const dispose = effect(() => s.set(fn()));
-  trackDispose(dispose);
+  effect(() => s.set(fn()));
   return s;
 }