davaux 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David L Dyess II
+
+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,36 @@
+# Davaux
+
+#### Please note Davaux is in early alpha. Expect breaking changes, and please report any issues you encounter.
+
+An SSR-first JSX framework for Node.js. The server is a first-class citizen — not an afterthought bolted onto a client-side runtime.
+
+- **File-based routing** with HTTP methods explicit in the filename
+- **Async JSX** — any component can `await` data, no `getServerSideProps` ceremony
+- **Layouts** — drop `_layout.tsx` in any directory, nesting composes automatically
+- **Islands + signals** — zero client JS by default, opt-in fine-grained reactivity
+- **Typed request context** — params, query, cookies, head, body parsing, redirect
+- **Static generation** — `davaux static` pre-renders your app to static HTML + assets
+- **Multi-sites** — multiple apps in one codebase, shared components, separate configs
+
+---
+
+## Quick start
+
+```bash
+npx davaux create my-app
+cd my-app
+npm install
+npm run dev
+```
+
+Davaux requires Node.js 22+.
+
+`davaux create` scaffolds a complete project: `package.json`, `tsconfig.json`, `davaux.config.ts`, `biome.json`, a root layout, and a starter index page — ready to run.
+
+## Documentation
+
+Full documentation at **[davaux.codeberg.page/docs](https://davaux.codeberg.page/docs/)** — routing, request context, middleware, layouts, islands, signals, CLI, configuration, static generation, and more.
+
+## License
+
+MIT © David L Dyess II

package/ROADMAP.md

@@ -0,0 +1,198 @@
+# Davaux — Roadmap
+
+What the framework needs, roughly in the order I'd build it. 
+
+---
+
+## Tier 1 — What to build next
+
+### `@davaux/docs-gen` — CSS base theme
+
+The generated site has no stylesheet. docs-gen should write a minimal `src/layout.css` alongside `_layout.tsx` — enough to be readable and usable out of the box: sidebar layout, prose width, code block styling, light/dark via `data-theme`, active nav link. Opinionated but overridable; users can replace the file entirely. The CSS class names in the generated layout (`docs-shell`, `sidebar`, `prose`, etc.) are the stable contract.
+
+### `@davaux/docs-gen` — Route tree page
+
+Scan a Davaux project's `src/routes/` directory and generate a `routes.page.mdx` showing the full routing tree: every URL pattern, its HTTP method(s), whether it's a page or an API handler, dynamic segments, and which layouts and middlewares apply. Reuses the same filename convention logic as `src/router/scanner.ts`.
+
+```
+Method   Path                    File
+────────────────────────────────────────────────
+GET      /                       index.page.tsx
+GET      /about                  about.page.tsx
+GET      /api/users              api/users.get.ts
+POST     /api/users              api/users.post.ts
+DELETE   /api/users/:id          api/users.[id].delete.ts
+GET      /blog/:slug             blog/[slug].page.tsx
+         └─ layout               blog/_layout.tsx
+         └─ middleware           blog/_middleware.ts
+```
+
+Configured via a `routes` field in `docs-gen.config.ts` that points at the routes directory to scan.
+
+### `@davaux/docs-gen` — JSDoc API extraction
+
+Walk exported TypeScript symbols using the TypeScript compiler API. For each export, extract the full type signature, `@param` / `@returns` / `@example` / `@throws` JSDoc tags, and whether it's deprecated. Output one `api.page.mdx` per package, rendered as a structured API reference table alongside the README page.
+
+Because the content derives from the source, the only way to have outdated API docs is to have outdated comments — and those show up in code review diffs next to the functions they describe.
+
+**Prerequisite**: consistent JSDoc coverage on all public exports. The `@davaux/*` packages have this; the core `davaux` package is close.
+
+### `@davaux/docs-gen` — Error page
+
+Generate a `_error.tsx` for the docs site so 404s and runtime errors render within the docs layout rather than a blank page.
+
+---
+
+## Tier 2 — Developer experience and ecosystem
+
+### `@davaux/multisite` — CLI integration
+
+The MVP is shipped — see the Shipped section for the full feature list. Remaining work: `davaux.config.ts`-driven multisite with no boilerplate entry files:
+
+```ts
+// davaux.config.ts
+import { defineConfig } from 'davaux/config'
+import { defineSites } from '@davaux/multisite'
+
+export default defineConfig({
+  server: { port: 3000 },
+  sites: defineSites<SiteConfig>({
+    baseDir: './src/routes',
+    sites: [...],
+  }),
+})
+```
+
+The CLI detects `config.sites` and switches to multisite mode automatically. `server.ts` remains available as an escape hatch.
+
+### Custom server entry point (`server.ts`) — dev mode
+
+Build and start support is shipped — see the Shipped section. Remaining work: dev-mode integration. Currently `davaux dev` warns when `server.ts` is present and suggests `node --watch --import tsx/esm server.ts` as the development approach. Proper dev-mode integration would compile `server.ts` into an esbuild watch context alongside routes and re-invoke the start function on rebuild, similar to how the standard dev server hot-swaps the compiled app without restarting. This requires carefully threading the server lifecycle through the watch loop — the start function must be disposable so a new server can replace it when `server.ts` or its imports change.
+
+### Server-Sent Events support for handlers (`ctx.sse()`)
+
+Users building real-time features (live notifications, dashboards, log tails) currently have to set SSE headers and write the wire format manually against `ctx.res`. A `ctx.sse(setup)` method would handle the protocol details:
+
+```ts
+export default defineHandler((ctx) => {
+  ctx.sse((stream) => {
+    const interval = setInterval(() => {
+      stream.send({ data: JSON.stringify({ ts: Date.now() }) })
+    }, 1000)
+    stream.onClose(() => clearInterval(interval))
+  })
+})
+```
+
+`SSEStream` would expose `send({ data, event?, id? })` for typed events and `onClose(fn)` for cleanup. Lives in core (`types.ts` + `makeContext`) alongside `ctx.send()` — no separate package needed since SSE is a standard web primitive and the implementation is ~40 lines.
+
+### Islands lazy hydration strategy
+
+Allow islands to declare when they should hydrate rather than always hydrating immediately on page load:
+
+```tsx
+<Counter client:visible />   // hydrate when scrolled into view (IntersectionObserver)
+<Analytics client:idle />    // hydrate during requestIdleCallback
+<Modal client:load />        // hydrate immediately (current default)
+```
+
+Useful for content-heavy pages with many islands below the fold — deferring hydration improves Time-to-Interactive without changing how the islands are authored. The `island()` wrapper would emit extra data attributes; `hydrate.ts` would route each island through the appropriate scheduler.
+
+---
+
+## Tier 3 — Production completeness
+
+### Deployment adapters
+Davaux is currently Node.js-only — it starts an `http.createServer` and assumes a persistent process. This rules out Cloudflare Workers, Vercel Edge Functions, Deno Deploy, and similar platforms that use a fetch-handler model (`(req: Request) => Response`). An adapter system would let the framework core stay agnostic while platform-specific packages (`@davaux/adapter-cloudflare`, `@davaux/adapter-vercel`) wrap the dispatch logic in the right runtime interface.
+
+The main challenge is that `RequestContext` is built on Node's `IncomingMessage`/`ServerResponse` — a web-fetch adapter would need a compatibility shim or a new context model. The SSG mock req/res (already in `ssg.ts`) is a proof of concept that the context can be faked; a real adapter would do the same thing cleanly.
+
+
+### Streaming SSR
+Sending HTML as it renders rather than waiting for the full page. Perceived performance wins on pages with slow data fetches — the browser renders the shell while deeper components load.
+
+This is a significant architectural change: `JSX.Element = Promise<string>` would need to become a `ReadableStream`, and the server would switch from `res.end(html)` to streaming. The signals/islands architecture doesn't depend on it. I'd revisit after the framework is otherwise solid.
+
+---
+
+## Tier 4 — Things worth thinking about but not building yet
+
+### Islands HMR
+After live reload (full page refresh) is working, the next level is hot-replacing only the changed island without a full reload — preserving counter state across edits, for example. Requires the dev server to send a more specific message (which island changed) and the client runtime to tear down and remount just that component. Genuinely useful for iterating on island UI; not urgent.
+
+---
+
+## Known Limitations
+
+Intentional tradeoffs and deferred design decisions. Not bugs, but worth understanding before building on top of them.
+
+### Island props must be JSON-serializable
+The `island()` wrapper serializes props into a `data-props` attribute as JSON for client hydration. `Date` objects, class instances, `undefined`, functions, and circular references are silently lost or corrupted. Pass primitive values and plain objects only. This is inherent to the SSR→hydration boundary and would require a serialization library (e.g. superjson) to work around.
+
+### `<For>` without `key` does full re-renders
+Without a `key` prop, every array change destroys and recreates all child nodes — O(n) on every update. Pass `key={(item) => item.id}` to enable keyed diffing (create once, move/update in O(n) DOM ops).
+
+### Scoped middleware (`_middleware.ts`) does not run for 404s
+`_middleware.ts` only applies to matched routes. An unmatched request goes directly to `sendErrorPage` without passing through any scoped middleware. This is intentional — auth middleware that redirects on no-session would otherwise loop on a missing asset. Use `src/middleware.ts` (app-level) for middleware that must run on every request, including 404s.
+
+### Signals implementation covers the common cases but not the edge cases
+The custom signal implementation handles the 90% case cleanly — `createSignal`, `createEffect`, `createMemo`, `batch`, `createStore` all behave correctly for typical island patterns. The remaining 10% is the territory that SolidJS spent years hardening: nested effects that create child effects, signals read inside async gaps (after an `await`), effects that conditionally read different signals on different runs, and memory leaks when reactive roots aren't disposed. None of these are currently tested. For complex islands, it's worth being aware that the implementation may have subtle differences from SolidJS's semantics in these edge cases.
+
+### `@davaux/session` uses `writeHead` monkey-patching to set cookies
+
+The session middleware needs to write the `Set-Cookie` header after `next()` resolves but before headers are sent. The problem is that route handlers call `res.writeHead()` themselves (via `sendPage` / `sendErrorPage`), at which point `res.setHeader()` is no longer valid.
+
+The current implementation patches `ctx.res.writeHead` at middleware setup time, injects the cookie inside the patched function, then restores the original. This works correctly in all tested cases but is a non-obvious workaround. A cleaner approach would be a framework-level "before-send" hook that middleware can register callbacks on — similar to Fastify's `onSend` hook — so cookie injection doesn't need to reach into Node's internals. This is a Tier 3 architectural item; the monkey-patch is not broken, just worth revisiting when the response lifecycle is formalised.
+
+### Cookie-based sessions are capped at ~4 KB
+`@davaux/session` stores the entire session payload in a signed cookie. Browsers enforce a per-cookie size limit (typically 4096 bytes). Large session objects — deep user profiles, embedded tokens, permission sets — will be silently truncated or rejected by the browser. Keep session data minimal (a user ID, a CSRF token) and fetch the rest from a database in the handler.
+
+---
+
+## Tooling
+
+### `@davaux/docs-gen` — Watch mode
+
+`davaux-gen --watch` — rebuild pages when source files change (READMEs, TypeScript exports, routes directory). Pairs with the generated site's `npm run dev` so the docs stay live during development. Uses Node's `fs.watch` or a similar low-dependency watcher; rebuilds only the affected pages rather than the full site.
+
+### `@davaux/docs-gen` — Changelog page
+
+Generate a `changelog.page.mdx` from a `CHANGELOG.md` file or by walking git log with conventional commit format. Useful for communicating what changed between versions without maintaining the changelog manually.
+
+### `@davaux/docs-gen` — Package dependency graph
+
+Visualise how `@davaux/*` packages relate to each other — which ones are peers, which are runtime dependencies, which are dev-only. Rendered as a simple Mermaid diagram embedded in a generated page. Helps contributors understand the dependency order before making changes.
+
+---
+
+## Ecosystem — @davaux packages
+
+The `@davaux` NPM organisation makes it possible to keep the core lean while shipping official, well-integrated add-ons. The strategy: `davaux` (core) handles routing, rendering, islands, and the request/response model. `@davaux/*` packages build on top of that without pulling unnecessary weight into every app.
+
+### `@davaux/docs-gen` — documentation site generator
+
+Shipped MVP: scaffolds a complete Davaux project (package.json, davaux.config.ts, tsconfig.json, `_layout.tsx`) and generates MDX pages from package READMEs with auto-built sidebar nav. Run `npm run docs` at the monorepo root.
+
+Companion to `@davaux/pka`: `pka` produces machine-readable project knowledge for LLMs; `docs-gen` produces the human-readable docs site. Both derive from the same source artifacts — write a JSDoc comment or README once, both audiences benefit. `pka` is optional and fully decoupled from `docs-gen`.
+
+**Planned additions** (see Tier 1 and Tooling above): CSS base theme, route tree page, JSDoc API extraction, error page, watch mode, changelog, dependency graph.
+
+---
+
+## What I'd build next
+
+1. **`@davaux/docs-gen` CSS theme** — the generated site is functional but unstyled; a base `layout.css` is the quickest way to make it presentable
+2. **`@davaux/docs-gen` route tree** — Davaux-specific killer feature; scan `src/routes/` and render a URL × method × file table for any project
+3. **`@davaux/docs-gen` JSDoc extraction** — TypeScript compiler API walk of exported symbols into structured API reference pages; JSDoc coverage on `@davaux/*` is already in good shape
+
+---
+
+## Shipped
+
+- **Lazy `<Show>` children** — `children` and `fallback` now accept `() => Node` factories; construction is deferred until the condition is first true and cached for subsequent toggles
+- **Reactive source for `createResource`** — `createResource(source, fetcher)` re-fetches whenever the source signal changes; stale in-flight responses are discarded automatically
+- **`<ErrorBoundary>`** — catches errors during initial island construction (including first-run effects) and renders a fallback; errors from subsequent reactive updates are not caught
+- **`@davaux/scoped-css`** — location-based CSS scoping for islands; class names get a deterministic hash suffix, `?global` opt-out, and a reactive `cx()` helper that returns a signal getter when conditions are signals
+- **`@davaux/docs-gen`** — CLI tool (`davaux-gen`) that generates a complete deployable Davaux site from source artifacts: scaffolds `package.json`/`davaux.config.ts`/`tsconfig.json`, generates MDX pages from package READMEs, and produces a `_layout.tsx` with auto-built nav. pka (`@davaux/pka`) remains a separate optional step for CLAUDE.md generation
+- **`@davaux/multisite`** — Multi-site hosting from a single Davaux process. Core runtime: `buildMultisiteApps(config, opts)` scans and merges route trees for each site; `startMultisiteServer(apps, opts)` dispatches by `Host` header; `getSite<T>(ctx)` injects per-site config via a `WeakMap` keyed on the request; `defineSites<T>` provides TypeScript inference; `mergeScanResults(base, overlay)` applies site-specific overrides (same URL pattern + type wins, layout/middleware override at `dirPath`, error page fallback to base); `dispatchToSite` for custom server embedding and testing. Convenience layer: `startMultisite(config, opts)` combines build + start in one call with automatic `isDev` detection from `NODE_ENV`; `buildMultisite(config, opts)` from `@davaux/multisite/build` compiles all site route trees and entry points to `dist/` using esbuild. Three operating modes: shared base + per-site overlay (layered CMS), fully independent co-located sites, same routes + different config (SaaS tenancy). CLI integration via `config.sites` and per-site island bundles are planned.
+- **Custom server entry point (`server.ts`)** — An optional `server.ts` at the project root lets single-site apps take full control of server startup. `davaux build` compiles it to `dist/server.js` alongside routes and islands. `davaux start` detects the default export and calls `start(app, serveStatics)` instead of starting its own server; `serveStatics` pre-handles `/_davaux/*.js`, `/_davaux/*.css`, and `public/` so the custom server doesn't need to. `davaux dev` warns when `server.ts` is present and points to `node --watch --import tsx/esm server.ts`. Unlocks HTTPS/TLS, HTTP/2, WebSocket co-hosting, Node.js clustering, and custom middleware stacks without framework changes. Dev-mode integration is planned.

package/build.mjs

@@ -0,0 +1,101 @@
+import { execSync } from 'node:child_process'
+import { build } from 'esbuild'
+
+const shared = { bundle: false, sourcemap: true }
+
+// ── Server-side top-level entries ──────────────────────────────────────────────
+await build({
+  ...shared,
+  entryPoints: [
+    'src/index.ts',
+    'src/types.ts',
+    'src/jsx-runtime.ts',
+    'src/signal.ts',
+    'src/island.ts',
+    'src/link.ts',
+    'src/config.ts',
+    'src/errors.ts',
+    'src/create.ts',
+    'src/create-multisite.ts',
+    'src/generate.ts',
+    'src/ssg.ts',
+  ],
+  outdir: 'dist',
+  format: 'esm',
+  platform: 'node',
+  target: 'node22',
+})
+
+// ── Router, server, dev internals ──────────────────────────────────────────────
+await build({
+  ...shared,
+  entryPoints: [
+    'src/router/scanner.ts',
+    'src/router/matcher.ts',
+    'src/router/handler.ts',
+    'src/server/index.ts',
+    'src/build/index.ts',
+    'src/build/plugins.ts',
+    'src/build/config.ts',
+    'src/dev/blueprints.ts',
+    'src/dev/components.ts',
+    'src/dev/insert.ts',
+    'src/dev/remove.ts',
+    'src/dev/watch.ts',
+    'src/oml/fragment.ts',
+    'src/oml/index.ts',
+    'src/oml/jsx-runtime.ts',
+    'src/oml/jsx.ts',
+    'src/oml/page.ts',
+    'src/oml/render.ts',
+    'src/oml/types.ts',
+  ],
+  outdir: 'dist',
+  outbase: 'src',
+  format: 'esm',
+  platform: 'node',
+  target: 'node22',
+})
+
+// ── CLI — unbundled so all imports resolve to dist/* at runtime, keeping a
+//    single module instance of types.ts shared with user route files. ──────────
+await build({
+  ...shared,
+  entryPoints: ['src/cli.ts'],
+  outfile: 'dist/cli.js',
+  format: 'esm',
+  platform: 'node',
+  target: 'node22',
+  banner: { js: '#!/usr/bin/env node' },
+})
+
+// ── Client (browser islands) ────────────────────────────────────────────────────
+// bundle: false so the app's bundler sees a single shared signal.js and
+// deduplicates it. Bundling here would inline signal.ts into both
+// jsx-runtime.js and index.js, giving two separate currentSubscriber globals.
+await build({
+  bundle: false,
+  sourcemap: true,
+  entryPoints: [
+    'client/signal.ts',
+    'client/jsx-runtime.ts',
+    'client/hydrate.ts',
+    'client/control.ts',
+    'client/resource.ts',
+    'client/store.ts',
+    'client/useHead.ts',
+    'client/index.ts',
+  ],
+  outdir: 'dist/client',
+  format: 'esm',
+  platform: 'browser',
+  target: 'es2022',
+})
+
+// ── Type declarations ───────────────────────────────────────────────────────────
+execSync('npx tsc -p tsconfig.json --emitDeclarationOnly --noEmit false', { stdio: 'inherit' })
+execSync('npx tsc -p tsconfig.client.json --emitDeclarationOnly --noEmit false', {
+  stdio: 'inherit',
+})
+
+console.log('Build complete.')

package/client/control.ts

@@ -0,0 +1,247 @@
+import { createEffect, createSignal } from './signal.js'
+
+// DocumentFragment is consumed on first insert, so we must spread its children
+// into a plain array before we can track and re-attach them.
+function flatNodes(node: Node): Node[] {
+  if (node instanceof DocumentFragment) return [...node.childNodes]
+  return [node]
+}
+
+// ─── <For> ───────────────────────────────────────────────────────────────────
+
+export interface ForProps<T> {
+  each: (() => T[]) | T[]
+  /** When provided, enables keyed diffing: nodes are reused/moved instead of
+   *  destroyed and recreated on every array change. The key must be unique
+   *  within the list. Same key → same DOM node; the index signal updates in place. */
+  key?: (item: T) => string | number
+  children: (item: T, index: () => number) => Node
+}
+
+/**
+ * Render a reactive list. Re-renders the full list on every array change by default.
+ * Pass `key` to enable keyed diffing — each item's DOM node is created once per key
+ * and moved or removed rather than destroyed and recreated on every update.
+ * The `index` argument to the render function is a reactive signal that stays
+ * correct as items are inserted, removed, or reordered.
+ */
+export function For<T>(props: ForProps<T>): Node {
+  const anchor = document.createTextNode('')
+
+  if (!props.key) {
+    // Non-keyed: full re-render on every change.
+    let prevNodes: Node[] = []
+    let initialized = false
+
+    createEffect(() => {
+      const items = typeof props.each === 'function' ? props.each() : props.each
+      const newNodes: Node[] = items.flatMap((item, i) => flatNodes(props.children(item, () => i)))
+
+      if (!initialized) {
+        initialized = true
+        prevNodes = newNodes
+      } else {
+        const parent = anchor.parentNode
+        if (parent) {
+          for (const n of newNodes) parent.insertBefore(n, anchor)
+          for (const n of prevNodes) n.parentNode?.removeChild(n)
+          prevNodes = newNodes
+        }
+      }
+    })
+
+    const frag = document.createDocumentFragment()
+    for (const n of prevNodes) frag.append(n)
+    frag.append(anchor)
+    return frag as unknown as Node
+  }
+
+  // Keyed diffing: create once per key, move/update on subsequent changes.
+  type Entry = { nodes: Node[]; setIndex: (i: number) => void }
+  const keyFn = props.key
+  const entries = new Map<string | number, Entry>()
+  let initialized = false
+
+  createEffect(() => {
+    const items = typeof props.each === 'function' ? props.each() : props.each
+    const nextKeys = new Set<string | number>()
+    const ordered: Entry[] = []
+
+    for (let i = 0; i < items.length; i++) {
+      const k = keyFn(items[i])
+      nextKeys.add(k)
+      let entry = entries.get(k)
+      if (entry) {
+        entry.setIndex(i)
+      } else {
+        const [index, setIndex] = createSignal(i)
+        entry = { nodes: flatNodes(props.children(items[i], index)), setIndex }
+        entries.set(k, entry)
+      }
+      ordered.push(entry)
+    }
+
+    if (!initialized) {
+      initialized = true
+      return
+    }
+
+    // Remove entries no longer in the list.
+    for (const [k, entry] of entries) {
+      if (!nextKeys.has(k)) {
+        for (const n of entry.nodes) n.parentNode?.removeChild(n)
+        entries.delete(k)
+      }
+    }
+
+    // Reorder: walk backwards, inserting each entry's nodes before a running
+    // reference node. This places every entry exactly once in O(n) DOM ops.
+    const parent = anchor.parentNode
+    if (parent) {
+      let ref: Node = anchor
+      for (let i = ordered.length - 1; i >= 0; i--) {
+        const { nodes } = ordered[i]
+        for (let ni = nodes.length - 1; ni >= 0; ni--) {
+          parent.insertBefore(nodes[ni], ref)
+        }
+        ref = nodes[0]
+      }
+    }
+  })
+
+  // Initial fragment — entries were populated synchronously by the first
+  // effect run above; anchor hasn't been inserted yet so no DOM ops ran.
+  const frag = document.createDocumentFragment()
+  for (const [, { nodes }] of entries) {
+    for (const n of nodes) frag.append(n)
+  }
+  frag.append(anchor)
+  return frag as unknown as Node
+}
+
+// ─── <Show> ──────────────────────────────────────────────────────────────────
+// Conditional rendering. Children and fallback are resolved lazily — pass a
+// function child `() => <Node>` to defer construction until `when` is first
+// true. Once resolved, nodes are cached and only attached/detached on toggle.
+
+export interface ShowProps {
+  when: (() => boolean) | boolean
+  children: Node | Node[] | (() => Node | Node[])
+  fallback?: Node | (() => Node)
+}
+
+/**
+ * Conditionally render content. Children and fallback are cached after first
+ * construction and only attached or detached as the condition toggles.
+ *
+ * Pass a function child `() => <Node>` to defer construction until `when` is
+ * first true — useful when children contain expensive effects or data fetching.
+ */
+export function Show(props: ShowProps): Node {
+  const anchor = document.createTextNode('')
+
+  let childNodes: Node[] | null = null
+  let fallbackNodes: Node[] | null = null
+
+  function getChildNodes(): Node[] {
+    if (childNodes !== null) return childNodes
+    const raw = typeof props.children === 'function' ? props.children() : props.children
+    childNodes = flatNodes(
+      Array.isArray(raw)
+        ? (() => {
+            const f = document.createDocumentFragment()
+            for (const n of raw) f.append(n)
+            return f
+          })()
+        : raw,
+    )
+    return childNodes
+  }
+
+  function getFallbackNodes(): Node[] {
+    if (fallbackNodes !== null) return fallbackNodes
+    if (!props.fallback) {
+      fallbackNodes = []
+      return fallbackNodes
+    }
+    const raw = typeof props.fallback === 'function' ? props.fallback() : props.fallback
+    fallbackNodes = flatNodes(raw)
+    return fallbackNodes
+  }
+
+  let prevVisible: boolean | undefined
+
+  createEffect(() => {
+    const visible = typeof props.when === 'function' ? props.when() : props.when
+    if (visible === prevVisible) return
+    prevVisible = visible
+
+    const parent = anchor.parentNode
+    if (!parent) return
+
+    const toAdd = visible ? getChildNodes() : getFallbackNodes()
+    const toRemove = visible ? (fallbackNodes ?? []) : (childNodes ?? [])
+
+    for (const n of toAdd) parent.insertBefore(n, anchor)
+    for (const n of toRemove) n.parentNode?.removeChild(n)
+  })
+
+  const frag = document.createDocumentFragment()
+  const initialVisible = typeof props.when === 'function' ? props.when() : props.when
+  const initialNodes = initialVisible ? getChildNodes() : getFallbackNodes()
+  for (const n of initialNodes) frag.append(n)
+  frag.append(anchor)
+  return frag as unknown as Node
+}
+
+// ─── <ErrorBoundary> ─────────────────────────────────────────────────────────
+
+export interface ErrorBoundaryProps {
+  /** Rendered when children throw. Receives the caught error if passed as a function. */
+  fallback: Node | ((error: Error) => Node)
+  /** Must be a function so construction is deferred into the try/catch. */
+  children: () => Node | Node[]
+}
+
+/**
+ * Catch errors thrown during the initial construction of children — including
+ * errors in the first run of any `createEffect` inside them — and render
+ * `fallback` instead.
+ *
+ * Children must be a function so their construction is deferred into the
+ * boundary's try/catch. A plain JSX child would be evaluated before
+ * `ErrorBoundary` runs and could not be caught.
+ *
+ * Errors from subsequent reactive updates are not caught — add try/catch
+ * inside those effects for fine-grained recovery.
+ */
+export function ErrorBoundary(props: ErrorBoundaryProps): Node {
+  let nodes: Node[] = []
+  let caught: Error | null = null
+
+  try {
+    const raw = props.children()
+    nodes = Array.isArray(raw)
+      ? flatNodes(
+          (() => {
+            const f = document.createDocumentFragment()
+            for (const n of raw) f.append(n)
+            return f
+          })(),
+        )
+      : flatNodes(raw)
+  } catch (e) {
+    caught = e instanceof Error ? e : new Error(String(e))
+  }
+
+  const frag = document.createDocumentFragment()
+
+  if (caught !== null) {
+    const fallback = typeof props.fallback === 'function' ? props.fallback(caught) : props.fallback
+    for (const n of flatNodes(fallback)) frag.append(n)
+  } else {
+    for (const n of nodes) frag.append(n)
+  }
+
+  return frag as unknown as Node
+}

package/client/hydrate.ts

@@ -0,0 +1,37 @@
+// Island hydration — runs in the browser after the server-rendered page loads.
+// Finds [data-island] elements, imports the matching component module, and
+// mounts it with the serialized props so signals become reactive.
+
+import { createRoot } from './signal.js'
+
+export interface IslandManifest {
+  [islandId: string]: () => Promise<{ default: (props: Record<string, unknown>) => Node }>
+}
+
+export async function hydrate(manifest: IslandManifest): Promise<void> {
+  const islands = document.querySelectorAll<HTMLElement>('[data-island]')
+
+  await Promise.all(
+    Array.from(islands).map(async (el) => {
+      const id = el.dataset.island
+      if (!id || !(id in manifest)) return
+
+      let props: Record<string, unknown> = {}
+      try {
+        props = JSON.parse(el.dataset.props ?? '{}')
+      } catch {
+        console.warn(`[davaux] Failed to parse props for island "${id}"`)
+      }
+
+      const { default: Component } = await manifest[id]()
+
+      // Run the component inside a reactive root so any onCleanup() calls
+      // (e.g. from createResource refetchInterval) are collected and can be
+      // disposed if the island is ever unmounted.
+      const node = createRoot(() => Component(props))
+
+      // Replace server-rendered children with the live DOM subtree
+      el.replaceChildren(node)
+    }),
+  )
+}

package/client/index.ts

@@ -0,0 +1,19 @@
+export type { ErrorBoundaryProps, ForProps, ShowProps } from './control.js'
+export { ErrorBoundary, For, Show } from './control.js'
+export type { IslandManifest } from './hydrate.js'
+export { hydrate } from './hydrate.js'
+export type { Resource, ResourceOptions, ResourceReturn } from './resource.js'
+export { createEventSource, createResource } from './resource.js'
+export {
+  batch,
+  createEffect,
+  createMemo,
+  createRoot,
+  createSignal,
+  onCleanup,
+  untrack,
+} from './signal.js'
+export type { SetStoreFn, Updater } from './store.js'
+export { createStore } from './store.js'
+export type { MetaDescriptor, UseHeadOptions } from './useHead.js'
+export { useHead } from './useHead.js'