@elurjs/kit 2.4.10 → 2.5.0

package/CHANGELOG.md

@@ -5,6 +5,304 @@ All notable changes to Elur Kit are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.5.0]
+
+All changes are additive and backwards-compatible: existing projects work
+unchanged without touching their config.
+
+### Added
+
+- **Structured request logging** — the unified web handler
+  (`createWebHandler`, used by the dev server, preview server, and the
+  generated Node/Bun servers) now creates a `StructuredLogger` per request
+  instead of bare `console.error` calls. Error logs are emitted as JSON in
+  production (readable `[LEVEL]` text in dev) with structured fields
+  (`path`, `method`, `route`, `error`, `stack`), sensitive-header
+  redaction, and a request ID taken from the incoming `X-Request-ID`
+  header or generated per request. Configure via
+  `defineConfig({ logger: { level: "debug" | "info" | "warn" | "error" } })`
+  (default: `debug` in dev, `info` in production).
+- **`X-Request-ID` response header** on every handler response, enabling
+  request correlation between clients, proxies, and logs.
+- **`Server-Timing` response header** with per-phase timings (`action`,
+  `render-endpoint`, `api`, `ssr`), visible in browser DevTools → Network
+  → Server Timing.
+- **Redirects, rewrites, and route headers** — the previously internal
+  `src/router/redirects.ts` module is now wired into the handler pipeline.
+  Configure via `defineConfig({ redirects, rewrites, headers })`:
+  - `redirects: [{ from, to, status? }]` are evaluated before all routing
+    and return a `Location` response (default status `308`; also `301`,
+    `302`, `307`).
+  - `rewrites: [{ from, to }]` rewrite the pathname transparently (the
+    browser URL does not change); the rewritten path drives static
+    serving, SSR, API routes, and the ISR cache key.
+  - `headers: [{ path, headers }]` merge custom headers into responses
+    matching the public (pre-rewrite) path; they may override security
+    headers, while `Server-Timing`/`X-Request-ID` always win.
+  - Patterns support literal segments, `:param`, `*` wildcards, and
+    `:param*` catch-alls, with `:param` interpolation in destinations.
+  - Works in dev, preview, and the generated Node/Bun servers. The
+    Vercel/Netlify bundled handlers do not pick this up yet.
+- **Public exports** — `StructuredLogger`, `createRequestLogger`, and the
+  `LogLevel`/`LogEntry`/`ServerTimingMetric` types are now exported from
+  the package root.
+- **Pluggable ISR cache adapters in the handler** — the unified web
+  handler now stores rendered pages through the `CacheAdapter` interface
+  instead of the legacy cache module. Configure via
+  `defineConfig({ cache: { adapter } })` (e.g. Redis or Cloudflare KV);
+  when omitted, a filesystem adapter rooted at `cache.dir` is created and
+  shared per directory. Page entries are keyed with `cacheKey(pathname)`
+  (SHA-256), the same scheme used by path-based invalidation.
+- **Cache policy tags are now honored** — `tags` declared in a route's
+  `cache` policy (`page.data.ts`) are stored with the cache entry, so
+  tag-based invalidation works end to end.
+- **Automatic cache invalidation from actions** — after a successful
+  action run, `invalidateTags`/`invalidatePaths` declared via
+  `defineAction()` are dispatched to the connected cache adapter
+  (`defaultInvalidator`). Actions that return `fail(...)` do not
+  invalidate anything.
+- **Stale-while-revalidate for ISR pages** — stale cache entries are
+  served immediately while the page re-renders in the background, instead
+  of blocking the request on a full re-render.
+- **New `@elurjs/kit/cache` subpath** — exports `CacheAdapter`,
+  `createFsCacheAdapter`, `createRedisCacheAdapter`,
+  `createCloudflareKVCacheAdapter`, `getWithSWR`, `cacheKey`, the cache
+  policy helpers, and the invalidation primitives.
+- **Automatic sitemap generation in `build`** — when `site` is configured
+  in `defineConfig`, the build now writes `sitemap.xml` from the scanned
+  route manifest (dynamic routes, error pages and internal namespaces are
+  excluded; sites over 50,000 URLs are split into `sitemap-N.xml` files
+  with a `sitemap.xml` index). An existing `sitemap.xml` — copied from
+  `public/` or written by an integration `build` hook — always takes
+  precedence and is never overwritten. `generateSitemapFromRoutes` and its
+  options type are re-exported from `@elurjs/kit/seo`.
+- **`--verbose` / `--quiet` CLI flags** — override `logger.level` from the
+  config: `--verbose` maps to `debug`, `--quiet` maps to `error` (only
+  errors are printed; `--quiet` wins if both are passed).
+- **Real streaming SSR in the unified handler (opt-in, experimental)** —
+  `defineConfig({ streaming: true })` enables true streaming for dynamic
+  routes that declare a `loading` boundary: the document shell + loading
+  fallback are flushed immediately, the page render continues in the
+  background, and the resolved content arrives as a `<template>` chunk that
+  swaps the boundary in-place. Details:
+  - Wired into `createWebHandler` (new `streaming` and `capabilities`
+    options), so `dev`, `preview`, `start` and the generated Node/Bun
+    servers all stream through the same code path. Hosts that declare
+    `capabilities.streaming: false` degrade to buffered rendering, and the
+    CLI `adapter` command validates the combination at build time.
+  - Streamed responses send `Content-Type: text/html` early, no
+    `Content-Length`, `X-Accel-Buffering: no` (nginx must not buffer) and
+    `Cache-Control: no-store`. `Server-Timing`'s `ssr` metric measures
+    time-to-shell.
+  - **ISR interaction**: streamed pages bypass the cache entirely (never
+    read, never written); buffered routes keep the existing ISR behavior.
+  - **Abort handling**: client disconnects cancel the stream via
+    `request.signal`; late background renders are discarded. The Node
+    server now writes responses with the new `sendWebResponse()` helper
+    (`@elurjs/kit/runtime`), which forwards chunks as they are produced
+    with backpressure and cancels the upstream stream on socket close.
+  - **Mid-stream failures**: a loader redirect `Response` navigates via an
+    inline script chunk; a render error swaps the boundary for an
+    inline-styled `role="alert"` notice instead of a dead spinner.
+  - `documentShell` now delimits the `#app` content with explicit
+    `<!--elur:app:start-->`/`<!--elur:app:end-->` markers (invisible HTML
+    comments), replacing the fragile `<div id="app">` regex extraction;
+    `extractAppBody()` is exported for adapters. `createStreamingResponse`
+    and `createBufferedResponse` are now exported from the package root.
+- **User middleware in the unified handler** — `src/middleware.ts` now runs
+  in `dev`, `preview` and `start` (previously only the legacy SSR server ran
+  it). Semantics: after redirects/rewrites and the internal endpoints,
+  before routing; a returned `Response` short-circuits through the standard
+  finalize step (security headers, `X-Request-ID`, `Server-Timing` still
+  apply); `next({ headers })` merges into the downstream request and
+  `next({ locals })` is exposed to API routes as `ctx.locals`. Middleware
+  errors return a sanitized 500 instead of crashing the request. The
+  generated Node/Bun adapter servers do not run the middleware file yet.
+- **`RedirectRule` / `RewriteRule` / `RouteHeadersRule` type exports** from
+  the package root, so config rule arrays can be annotated outside
+  `defineConfig`.
+- **0% JavaScript by default (per-page script gating)** — `documentShell`
+  no longer emits the client entry unconditionally. In the default
+  `js: "modern"` mode the shell inspects the rendered body for
+  `data-elur-island` markers: pages without islands ship **no client JS**
+  when the router is disabled, or **only the router chunk** when it is on.
+  Streaming shells are exempt (the body is not known when the shell is
+  sent, so streamed routes always emit the entry). Opt out entirely with
+  `defineConfig({ js: "legacy" })`, which restores the unconditional
+  combined entry.
+- **Split client entries (hydration vs router)** — the generated client
+  entry is now hydrate-only and the router lives in its own module
+  (`.elur/router.ts` → `/_elur/router.js`). The CLI decides the layout
+  before rendering pages: projects with a two-input
+  `vite.client.config.*` (or no client config at all — a default
+  two-input config is now synthesized) get the split; single-input
+  configs keep the router embedded in `entry-client.js` and the shell
+  emits it whenever islands exist *or* the router is enabled. Wired
+  through `ElurConfig.router`, `BuildConfig.router`,
+  `GenerateEntryOptions.router`, `WebHandlerOptions.router`,
+  `AdapterOptions.router`/`js`, `documentShell` (`routerEntry`,
+  `routerEnabled`), and the generated adapter SSR entries. The example
+  `vite.client.config.ts` now uses two named inputs.
+- **`<link rel="modulepreload">` for emitted entries** — every module
+  script the shell emits (hydration entry and/or router chunk) also gets
+  a `modulepreload` link so the fetch starts during HTML parsing.
+- **Navigation lifecycle events** — the client router dispatches
+  `elur:navigate-start`, `elur:navigate-end` and `elur:navigate-error`
+  with `{ pathname, search, fromCache, popstate }`, plus
+  `elur:before-render` right before the `#app` swap (with
+  `detail.persisted` listing the nodes that will survive). Islands are
+  now disposed on `elur:before-render` — while still attached — instead
+  of on `elur:rendered`.
+- **`data-elur-persist` element persistence** — mark an element with
+  `data-elur-persist="key"` and the router moves the *same live node*
+  into the matching position of the new page (matched by attribute
+  value) using `Element.moveBefore()` when available
+  (`replaceWith` fallback). Island state, media playback and scroll
+  positions survive navigations; islands inside persisted subtrees are
+  skipped by the navigation cleanup. When an island inside a persisted
+  node would receive different props, an `elur:persist-props-changed`
+  event bubbles from its marker. `cleanupHydratedIslands({ except })`
+  supports exclusion lists.
+- **Complete SPA render payload** — `/__elur-js/render` now returns
+  `{ title, body, head, data, actions, clearActionErrorCookie }` in every
+  runtime (unified handler, generated Node/Bun adapters, dev server and
+  the legacy `createSsrServer`): `head` carries the managed
+  `data-elur-head` tags (title/meta/OG/Twitter), `data`/`actions` carry
+  the serialized contents of `#elur-data`/`#elur-actions`, and
+  `clearActionErrorCookie` is also relayed as the
+  `X-Elur-Action-Clear-Cookie` response header. Loader-thrown
+  `Response`s propagate as first-class responses. After a navigation the
+  router refreshes the inert `#elur-data`/`#elur-actions` scripts, merges
+  the managed head tags, and re-executes inline `<script>` elements in
+  the new body (external `src` scripts are deduplicated across
+  navigations; `data-elur-no-reload` opts out).
+- **Router robustness** — the prefetch cache is now a bounded LRU (32
+  entries, 30 s TTL), `history.scrollRestoration` is set to `manual`
+  with per-entry scroll save/restore on back/forward, prefetching starts
+  on `pointerdown` in addition to hover/focus (and opt-in viewport via
+  `data-prefetch="viewport"`), and constrained networks are respected:
+  `Save-Data` and `slow-2g`/`2g` effective connection types skip prefetch
+  unless the link forces it with `data-prefetch="always"` (or
+  `prefetch(path, search, { force: true })` is called directly).
+- **Optional DOM morphing (`router.morph`)** — `defineConfig({ router: {
+  morph: true } })` swaps `#app` with idiomorph-based DOM morphing
+  instead of a wholesale `replaceChildren` (experimental). Hydrated
+  islands and `data-elur-persist` subtrees are treated as opaque. New
+  dependency: `idiomorph` — loaded via dynamic `import()` only when the
+  flag is on, so it stays out of the served bytes when morph is off
+  (a hard dependency is required because bundlers must resolve the
+  specifier at build time even when the chunk is lazy).
+- **Optional loading indicator (`router.loadingIndicator`)** — a minimal
+  top progress bar appears only when a navigation takes longer than
+  ~200 ms, driven by the lifecycle events; it honors
+  `prefers-reduced-motion` (static bar, no trickle) and never flashes on
+  cache hits.
+- **Speculation Rules (`router.speculation`)** —
+  `defineConfig({ router: { speculation: "prefetch" | "prerender" } })`
+  emits a `<script type="speculationrules">` block with document rules
+  (`eagerness: "moderate"`, internal same-origin links excluding actions,
+  downloads, `target`/`data-no-router`/`data-no-speculation` links) on
+  statically built pages. Chromium-only progressive enhancement; other
+  browsers ignore it.
+
+### Deprecated
+
+- **`createSsrServer`** (`@elurjs/kit`) — the legacy standalone SSR server
+  pipeline. All CLI commands (`dev`, `preview`, `start`) now run through
+  `createWebHandler`; the legacy server remains exported for backward
+  compatibility and will be removed in a future major release.
+- **`renderStreamingPage`** — the legacy shell + client-fetch streaming
+  approach, superseded by `createStreamingResponse` (real streaming).
+
+### Changed
+
+- **`elur-kit start` runs on the unified Web handler** — it previously used
+  the legacy `createSsrServer` pipeline. It now shares the dev/preview path:
+  startup banner with Local/Network URLs, busy-port fallback, per-request
+  structured logging with `Server-Timing`/`X-Request-ID`, security headers,
+  redirects/rewrites/route headers, pluggable ISR cache, user middleware, and
+  opt-in streaming SSR. `start` now requires a previous `elur-kit build`
+  (it fails fast with a clear message when `dist/` is missing) instead of
+  silently rendering everything on demand.
+- **CLI output formatting** — build, dev, preview, and adapter messages
+  now use a consistent format (`✓` success, `→` info, `!` warning, `✗`
+  error, `[tag]` lifecycle events) with ANSI colors when stdout is a TTY
+  (disabled via `NO_COLOR` or when piped; no new dependencies). The build
+  summary now includes the total duration plus page/island/file counts.
+  The fatal request-error catch in the dev/preview server now logs through
+  the structured logger (with `path`, `method`, `error`, `stack`) instead
+  of a bare `console.error`.
+- **Dev/preview/start startup banner** — the dev, preview and start servers
+  now print an Astro-style banner with the kit name and version and the
+  bound URLs:
+  `→ Local: http://…` plus `→ Network: http://<LAN-IP>:…` when the
+  machine has a non-internal IPv4 address. The banner reflects the port
+  actually bound after the busy-port fallback.
+- **Build phase timings and file sizes** — `elur-kit build` now reports
+  each phase with a checkmark and its duration (`transform`, `scan`,
+  `pages`, `images`, `integrations`, `sitemap`, `manifest`,
+  `client bundle`; phases that don't run are omitted) via a new optional
+  `BuildConfig.onPhase(name, durationMs)` observer, and lists the
+  generated files with their sizes (aligned, Vite-style). With more than
+  20 files, only the 10 largest are shown followed by a
+  `… and N more` summary. With `--quiet`, the client bundle step is now
+  silent too (new `quiet` option on `buildClientBundle`, which also sets
+  Vite's `logLevel: "silent"`).
+- **ISR storage backend** — `createWebHandler` no longer uses the legacy
+  `getCachedHtml`/`setCachedHtml` module for page caching (it remains
+  exported for backward compatibility). Existing on-disk cache entries use
+  the same SHA-256-of-pathname key, but entries written by older versions
+  lack tag metadata, so they simply miss tag-based invalidation until
+  re-rendered. What gets cached (cacheability gates, TTL rules) is
+  unchanged.
+
+### Fixed
+
+- **Dead legacy config lookup removed** — `findConfigFile` carried a legacy
+  config-name fallback that could never fire (its file list was identical to
+  the preferred one) and referenced pre-rename names that are no longer
+  supported. Config files are now exclusively `elur.config.ts/js/mjs`.
+- **Missing type declarations for `@elurjs/kit/cache`** — the subpath
+  shipped its runtime bundle but no `index.d.ts`/`index.d.cts` because
+  `src/cache/index.ts` was absent from the declaration build inputs
+  (publint error). The `./cache` subpath is now fully typed (including
+  `redis-adapter`).
+- **Infinite restart loop when the dev port is busy** — with port 3000
+  occupied, the dev supervisor restarted the crashed worker forever on the
+  same `EADDRINUSE`. The dev and preview servers now retry on the next
+  port (up to 20 candidates) with a clear warning
+  (`! Puerto 3000 ocupado, usando 3001`), and the startup message shows
+  the port actually bound. If the whole range is busy, the worker exits
+  with a dedicated code (78) that the supervisor treats as fatal instead
+  of restarting. Fallback also applies to an explicit `--port` (with the
+  same warning).
+- **Actions defined with `defineAction()` crashed at the action
+  endpoint** — `handleActionRequest` invoked actions as `action(...args)`
+  without building an `ActionContext`, so any action using the default
+  `concurrency: "latest"` failed with `ctx undefined` (`ctx.signal`
+  access). Defined actions (detected via their `__elurAction` metadata)
+  now receive `(input, ctx)` with `ctx.request`, `ctx.signal` (from the
+  request), `ctx.idempotencyKey` (from the `Idempotency-Key` header),
+  and empty `params`/`locals`. Legacy plain actions keep the `(...args)`
+  call convention unchanged.
+- **Head metadata lost on SPA navigations in production** — the
+  production render endpoint (`/__elur-js/render`) only returned
+  `{ title, body }`, so pages navigated via the client router kept stale
+  `<head>` tags and the consumed action-error cookie was never cleared.
+  The endpoint now ships the full payload and the cookie is relayed as
+  `Set-Cookie` (HTML mode) / `X-Elur-Action-Clear-Cookie` (JSON mode).
+- **`directive: "load"` did not hydrate on load** — the generated client
+  entry wrapped the whole hydration pass in `requestIdleCallback`, so
+  `load` islands were really `idle` islands. The entry now calls
+  `hydrateIslands()` immediately (module scripts are already deferred);
+  `idle`/`visible` keep their deferred scheduling inside the hydrator.
+- **Islands were disposed after the DOM swap** — the generated entry
+  listened only for `elur:rendered` (post-swap), so disposers ran on
+  detached DOM and could not read live state. Cleanup now runs on
+  `elur:before-render`, dispatched before `#app` is replaced, with a
+  compat fallback on `elur:rendered` for hosts that only emit the old
+  event (e.g. the streaming swap chunk).
+
 ## [2.4.10]
 
 ### Fixed

package/README.md

@@ -21,7 +21,7 @@ Elur Kit is a framework built on top of [Elur](https://elur.dev/). It brings con
 ### Key features
 
 - **Routing**: file-based with dynamic segments, optional catch-all `[[...slug]]`, route conflict detection, safe URL decoding, redirects/rewrites/route headers
-- **Rendering**: SSG, SSR, ISR with explicit cache policy (public/private/dynamic), streaming with `ReadableStream` (**experimental** — fallback buffered por adapter; ver nota de streaming)
+- **Rendering**: SSG, SSR, ISR with explicit cache policy (public/private/dynamic), opt-in streaming SSR with `loading.ts` boundaries (**experimental** — ver [Streaming SSR](#streaming-ssr-experimental))
 - **Build-time compiler** (optional, recommended): integrates [`@elurjs/core-compiler`](https://www.npmjs.com/package/@elurjs/core-compiler) via [`@elurjs/vite-plugin-elur`](https://www.npmjs.com/package/@elurjs/vite-plugin-elur) to lower `html\`\`` templates to imperative DOM code at build time — eliminates `detectContext`, `buildHTML`, and both `TreeWalker` passes in runtime
 - **Partial attribute interpolation**: `class="btn ${size}"` works out of the box via the Vite plugin's state-machine lexer (or the kit's legacy transform as fallback)
 - **Actions**: typed `defineAction()` with input validation, AbortSignal, idempotency, concurrency modes (latest/queue/parallel)
@@ -160,10 +160,10 @@ Options:
 
 - **File-based routing** — `src/app/page.ts` maps to URLs with dynamic segments (`[slug]`), catch-all (`[...slug]`), optional catch-all (`[[...slug]]`), route groups `(group)`, and route conflict detection.
 - **SSG, SSR, ISR** — static generation, on-demand SSR, and incremental static regeneration with explicit cache policy (`public`/`private`/`dynamic`), SHA-256 cache keys, atomic writes, single-flight, and tag-based invalidation.
-- **Streaming (experimental)** — `ReadableStream`-based streaming with `loading.ts` boundaries, `createStreamingResponse()`, and `createBufferedResponse()` fallback for adapters without streaming. **Etiquetado como experimental** hasta completar la matriz de paridad streaming/buffered cross-host y la implementación de `renderToChunks()` en el core.
+- **Streaming (experimental)** — real streaming SSR in the unified handler: opt-in via `defineConfig({ streaming: true })`, routes with `loading.ts` stream the shell + fallback immediately and swap in the resolved content with a `<template>` chunk. See [Streaming SSR (experimental)](#streaming-ssr-experimental).
 - **Server actions** — typed `defineAction()` with input validation (`.parse()`), AbortSignal propagation, idempotency metadata, concurrency modes (`latest`/`queue`/`parallel`), and progressive enhancement (plain HTML forms).
 - **RequestContext** — per-request context with `params`, `locals`, `cookies` (CookieJar), `signal` (AbortSignal), `requestId`, `platform`, `route`, and mutable `response` state (headers, Set-Cookie, status). Aligned with runtime-security §4.
-- **Unified Web handler** — `createWebHandler()` is the single entry point for all runtimes (Node, Bun, Vercel, Netlify, Vite dev **y el CLI `dev`/`preview`**). Every runtime is a thin wrapper; no duplicated routing/actions/static pipelines.
+- **Unified Web handler** — `createWebHandler()` is the single entry point for all runtimes (Node, Bun, Vercel, Netlify, Vite dev **y el CLI `dev`/`preview`/`start`**). Every runtime is a thin wrapper; no duplicated routing/actions/static pipelines.
 - **Cache security** — `shouldCachePublic()` rejects requests with cookies/Authorization. `isResultCacheable()` rejects HTML with action error markers. No personalized ISR cache leakage.
 - **Public error sanitization** — production 500s use `toPublicErrorInfo()`/`publicErrorResponse()` (JSON, `no-store`), never exposing stacks, paths or secrets; request id is kept in internal logs.
 - **CSRF protection** — `verifyOrigin()` checks `Origin`, `Referer`, `Host`, and `Sec-Fetch-Site` with allow-list and `strictOrigin` mode.
@@ -173,8 +173,8 @@ Options:
 - **SEO** — sitemap generation from route manifest, sitemap index for >50,000 URLs, robots.txt, JSON-LD with safe escaping (`<`, `>`, `&`, U+2028, U+2029).
 - **Image optimization** — manifest-driven `<picture>` with content-addressed hashed variants, `<source>` per format, real dimensions, no upscales, Sharp optional.
 - **Islands** — lazy `import()` per island, null/error isolation, `load`/`idle`/`visible` directives, auto-scan of `src/islands/`.
-- **Client router** — AbortController + navigation token (no races), head/assets merge, aria-live announcer, canonical URL, View Transitions with reduced-motion fallback.
-- **Middleware** — `src/middleware.ts` with path matchers, `next()` carries params/locals, cleanup in `finally`, runs in dev/preview/adapters.
+- **Client router** — navigation lifecycle events (`elur:navigate-*`, `elur:before-render`), per-page JS gating (0 KB on island-free pages), `data-elur-persist` element persistence, bounded LRU prefetch cache (network-aware, `pointerdown`), `history.scrollRestoration = "manual"`, head/payload/script refresh on navigation, optional idiomorph morphing (`router.morph`), optional loading indicator, Speculation Rules (`router.speculation`), head/assets merge, aria-live announcer, canonical URL, View Transitions with reduced-motion fallback.
+- **Middleware** — `src/middleware.ts` with path matchers, `next()` carries headers/locals into the request pipeline, cleanup in `finally`, runs in `dev`/`preview`/`start` (the unified Web handler).
 - **Integrations** — typed hooks for `elur-i18n`, `elur-auth`, `elur-query`, `elur-testing` without adding them as dependencies.
 - **CLI** — `dev`, `build`, `preview`, `start`, `check`, `routes`, `doctor`, `adapter` with reliable exit codes.
 - **Observability** — structured logger with request ID, Server-Timing, sensitive data redaction (cookies, auth, tokens).
@@ -183,6 +183,89 @@ Options:
 - **`throw new Response()`** — first-class HTTP control flow from loaders and layout loaders (redirects, 404, etc.).
 - **HMAC-signed action errors** — action error cookies signed with SHA-256, rejects tampered/forged values.
 
+## Streaming SSR (experimental)
+
+Real streaming for dynamic routes, wired into the unified Web handler
+(`createWebHandler`) — so it works identically in `dev`, `preview`, `start`
+and the generated Node/Bun servers.
+
+### Enabling it
+
+Streaming is **opt-in** (default `false` — every route renders buffered
+exactly as before unless you enable it):
+
+```ts
+// elur.config.ts
+import { defineConfig } from "@elurjs/kit";
+
+export default defineConfig({
+  streaming: true,
+});
+```
+
+Requirements:
+
+- The route must define a **loading boundary** (`src/app/<route>/loading.ts`).
+  Routes without one render buffered, unchanged.
+- The host adapter must declare `capabilities.streaming: true`. Node, Bun and
+  the CLI dev/preview servers do; hosts that cannot stream fall back to
+  buffered rendering automatically instead of breaking. The CLI `adapter`
+  command validates the combination at build time.
+
+### What you get
+
+1. The browser receives the **document shell + loading fallback immediately**
+   (low TTFB), with status 200 and `Content-Type: text/html; charset=utf-8`.
+2. The page render (loaders included) runs **in the background**.
+3. When it finishes, the server appends a `<template>` chunk plus a small
+   script that **swaps the loading boundary in-place** (`replaceWith`), then
+   dispatches `elur:rendered`. No full re-render, no client fetch.
+
+Emitted headers on streamed responses:
+
+| Header | Why |
+| --- | --- |
+| `Content-Type: text/html; charset=utf-8` | sent early so the browser parses progressively |
+| `Transfer-Encoding: chunked` | no `Content-Length`; each chunk flushes as produced |
+| `X-Accel-Buffering: no` | tells nginx and similar reverse proxies not to buffer the stream |
+| `Cache-Control: no-store` | a half-sent dynamic stream must never be cached by intermediaries |
+
+The usual observability headers (`X-Request-ID`, `Server-Timing`,
+security headers, route headers) apply as always. Note that `Server-Timing`'s
+`ssr` metric measures **time-to-shell**, not the full background render.
+
+### Redirects, errors and disconnects mid-stream
+
+- A loader throwing a redirect `Response` emits a
+  `<script>window.location.href=…</script>` chunk — the browser navigates
+  even though the shell was already sent.
+- A loader failure after the shell went out swaps the boundary for a sober,
+  inline-styled error notice (`role="alert"`) and logs the detail via
+  `console.error`.
+- If the client disconnects, the request's `AbortSignal` cancels the stream;
+  a render completing late is discarded and never writes to a dead stream.
+  The Node server also cancels the upstream stream when the socket closes.
+
+### Interaction with the ISR cache
+
+**Streamed pages bypass the ISR cache entirely** — they are not read from it
+nor written to it, and render live on every request. Nobody caches a stream
+mid-flight; if a route is cacheable, buffered + ISR is the better delivery
+mode. Keep `streaming: false` (or remove the `loading.ts` boundary) for
+routes you want cached.
+
+### Limitations
+
+- **Experimental**: the streaming/buffered parity matrix across hosts is not
+  complete yet, and the API may change.
+- The swap script is inline: a strict `Content-Security-Policy` without
+  `unsafe-inline` (or a nonce) blocks it. Configure CSP accordingly.
+- Verified on Node (dev/preview/`start`, generated Node server) and Bun
+  (`Bun.serve` streams natively). The Vercel/Netlify adapters are out of
+  scope for now.
+- Behind a reverse proxy, make sure buffering and gzip buffering are disabled
+  for streamed routes (the `X-Accel-Buffering: no` header covers nginx).
+
 ## What's new in v2.4
 
 - **Fixed: image pipeline silently no-op** — the CLI bundle was
@@ -234,6 +317,14 @@ Options:
 
 #### Using the `build` hook for sitemaps
 
+When `site` is set in your config, the build **already generates
+`sitemap.xml` automatically** from the scanned routes (dynamic routes,
+error pages and internal namespaces excluded; sites over 50,000 URLs are
+split into a sitemap index). You only need the manual hook below for full
+control over the entries (per-URL `priority`/`changefreq`, dynamic-route
+URLs, extra files). An existing `sitemap.xml` — from `public/` or written
+by an integration — always takes precedence over the automatic one.
+
 ```ts
 // elur.config.ts
 import { defineConfig } from "@elurjs/kit";
@@ -1291,16 +1382,111 @@ export const config = {
 };
 ```
 
-### Prefetch and View Transitions
+The middleware runs in `dev`, `preview` and `start` through the unified Web
+handler: after redirects/rewrites and the internal endpoints, before routing.
+Returning a `Response` short-circuits the pipeline (security headers and
+`X-Request-ID` still apply); `next({ headers })` merges headers into the
+downstream request and `next({ locals })` is exposed to API routes as
+`ctx.locals`. The generated Node/Bun adapter servers do not run the
+middleware file yet.
 
-The SPA router automatically prefetches pages when links enter the viewport
-(IntersectionObserver) and on hover/focus. Prefetched pages are cached for
-30 seconds. Add `data-no-prefetch` to any link to opt out.
+### Redirects, rewrites and route headers
+
+Declare redirects, rewrites and extra response headers in `elur.config.ts`.
+All patterns support `:param` segments, `*` wildcards and `:name*` catch-alls,
+with `:param` interpolation in destinations:
+
+```ts
+import { defineConfig } from "@elurjs/kit";
+
+export default defineConfig({
+  redirects: [
+    { from: "/old-blog/:slug", to: "/blog/:slug", status: 301 },
+  ],
+  rewrites: [
+    { from: "/api/legacy/*", to: "/api/v2/*" },
+  ],
+  headers: [
+    { path: "/admin/*", headers: { "X-Robots-Tag": "noindex" } },
+  ],
+});
+```
+
+Redirects are evaluated before any routing (default status `308`). Rewrites
+transparently change the pathname used for routing — API routes, static files
+and SSR all see the rewritten path. Route headers are matched against the
+original request path and applied to the response.
+
+### Router, prefetch and navigation lifecycle
+
+The SPA router prefetches pages on `pointerenter`, `focus` and `pointerdown`
+(the "tap" strategy — earlier than the click on touch devices), and on links
+that opt into viewport prefetching with `data-prefetch="viewport"`
+(IntersectionObserver, 200px root margin). Prefetched pages live in a
+bounded LRU cache (32 entries, 30 s TTL). Prefetching is skipped on
+constrained networks — `Save-Data` or `slow-2g`/`2g` effective types —
+unless a link forces it with `data-prefetch="always"`. Add
+`data-no-prefetch` to any link to opt out entirely.
+
+Navigation lifecycle events (on `document`) carry
+`{ pathname, search, fromCache, popstate }`:
+
+- `elur:navigate-start` — a navigation begins.
+- `elur:navigate-end` — the DOM swap completed.
+- `elur:navigate-error` — the navigation failed (e.g. render endpoint
+  unavailable); the router falls back to a full page load.
+- `elur:before-render` — fires *before* the `#app` swap; the generated
+  entry disposes islands here (except islands inside persisted nodes,
+  listed in `detail.persisted`).
+- `elur:rendered` — fires after the swap; islands re-hydrate here.
+
+Elements marked `data-elur-persist="key"` survive SPA navigations: the
+router moves the *same live DOM node* into its position in the new page
+(matched by the attribute value), using `Element.moveBefore()` when
+available — media playback, island state and scroll positions are
+preserved. Islands inside persisted subtrees are not disposed/rehydrated;
+if their incoming props differ, an `elur:persist-props-changed` event
+bubbles from the island marker.
+
+Scroll is managed by the router (`history.scrollRestoration = "manual"`):
+the position is saved per history entry and restored on back/forward.
 
 When the browser supports the View Transitions API, page transitions use
 `document.startViewTransition()` for smooth cross-fade animations. This is
 automatically disabled when the user has `prefers-reduced-motion: reduce`.
 
+Router options (`defineConfig`):
+
+```ts
+export default defineConfig({
+  router: {
+    enabled: true,          // SPA navigation; false → MPA + 0 KB JS on island-free pages
+    prefetch: true,         // link prefetching (network-aware)
+    morph: false,           // experimental: idiomorph DOM morphing for the swap
+    loadingIndicator: false,// top progress bar on navigations slower than ~200 ms
+    speculation: undefined, // "prefetch" | "prerender" → Speculation Rules on static pages
+  },
+  js: "modern",             // "legacy" restores the unconditional combined entry
+});
+```
+
+### Per-page JavaScript emission
+
+With `js: "modern"` (default) the document shell inspects the rendered body
+and only ships what the page needs:
+
+| Page contents | `router.enabled: true` | `router.enabled: false` |
+|---|---|---|
+| With islands | `entry-client.js` + `router.js` | `entry-client.js` only |
+| Without islands | `router.js` only | **0 KB of JS** |
+
+The split requires the router to be its own bundle chunk — automatic when
+the project has no `vite.client.config.*` (the CLI synthesizes a default
+two-input config) or when that config declares `.elur/router.ts` as a
+second input. A single-input config keeps the router embedded in
+`entry-client.js` (emitted whenever islands exist *or* the router is on).
+Set `js: "legacy"` to restore the pre-split behavior unconditionally.
+
 ## Project conventions
 
 ```text

package/dist/lib/action/index.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("../action-DZHihU3Z.cjs");exports.callAction=e.t,exports.defineAction=e.r,exports.elurJsAction=e.n;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("../action-BiE4tEty.cjs");exports.callAction=e.t,exports.defineAction=e.r,exports.elurJsAction=e.n;

package/dist/lib/action/index.js

@@ -1,2 +1,2 @@
-import { n as e, r as t, t as n } from "../action-BB6N5yD-.js";
+import { n as e, r as t, t as n } from "../action-CXVk8rWt.js";
 export { n as callAction, t as defineAction, e as elurJsAction };

package/dist/lib/{action-DZHihU3Z.cjs → action-BiE4tEty.cjs}

@@ -1,2 +1,2 @@
-const e=require("./errors-0X7pCFNU.cjs");let t=require("@elurjs/core");var n=globalThis.AbortController;function r(e,t){let r=e.concurrency??`latest`,a=e.idempotent??!1,o=e.invalidateTags??[],s=e.invalidatePaths??[],c=null,l=[],u=0;async function d(n,r){if(e.input)try{n=e.input.parse(n)}catch(e){let t=e instanceof Error?e.message:String(e),{fail:n}=await Promise.resolve().then(()=>require("./errors-0X7pCFNU.cjs")).then(e=>e.r);return n(400,{validation:t})}return t(n,r)}let f=async(e,t)=>{if(r===`latest`){c&&c.abort(),c=new n;let r=i(t.signal,c.signal);return d(e,{...t,signal:r})}if(r===`queue`){u>0&&await new Promise(e=>l.push(e)),u++;try{return await d(e,t)}finally{u--;let e=l.shift();e&&e()}}return d(e,t)};return f.__elurAction={name:t.name||`anonymous`,concurrency:r,idempotent:a,invalidateTags:o,invalidatePaths:s},f}function i(...e){let t=new n;for(let n of e)if(n){if(n.aborted){t.abort();break}n.addEventListener(`abort`,()=>t.abort(),{once:!0})}return t.signal}function a(e){return typeof e==`object`&&!!e&&e.__elur_js_action_failure===!0}function o(e){return typeof e==`object`&&!!e&&e.__elur_js_action_redirect===!0}async function s(t,n=[],r={}){let i=Array.isArray(n)?n:[n],s=await fetch(`/__elur-js/actions`,{method:`POST`,headers:{"Content-Type":`application/json`,Accept:`application/json`},body:JSON.stringify({name:t,page:r.page,args:i})}),c=await s.text();if(!s.ok){let n;try{n=JSON.parse(c)}catch{}if(a(n)&&n.status!==void 0)return new e.t(n.status,n.data);throw Error(`Action "${t}" failed: ${c}`)}let l=JSON.parse(c);return o(l)&&l.status!==void 0&&l.location!==void 0?new e.n(l.status,l.location):l}function c(e,n={}){let r=(0,t.signal)(!1),i=(0,t.signal)(null),a=(0,t.signal)(null);async function o(t){r.value=!0,i.value=null;try{let r=await s(e,t,n);return a.value=r,r}catch(e){throw i.value=e instanceof Error?e:Error(String(e)),e}finally{r.value=!1}}return{submit:o,pending:r,data:a,error:i}}Object.defineProperty(exports,"n",{enumerable:!0,get:function(){return c}}),Object.defineProperty(exports,"r",{enumerable:!0,get:function(){return r}}),Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return s}});
-//# sourceMappingURL=action-DZHihU3Z.cjs.map
+const e=require("./errors-kSl9yLkg.cjs");let t=require("@elurjs/core");var n=globalThis.AbortController;function r(e,t){let r=e.concurrency??`latest`,a=e.idempotent??!1,o=e.invalidateTags??[],s=e.invalidatePaths??[],c=null,l=[],u=0;async function d(n,r){if(e.input)try{n=e.input.parse(n)}catch(e){let t=e instanceof Error?e.message:String(e),{fail:n}=await Promise.resolve().then(()=>require("./errors-kSl9yLkg.cjs")).then(e=>e.r);return n(400,{validation:t})}return t(n,r)}let f=async(e,t)=>{if(r===`latest`){c&&c.abort(),c=new n;let r=i(t.signal,c.signal);return d(e,{...t,signal:r})}if(r===`queue`){u>0&&await new Promise(e=>l.push(e)),u++;try{return await d(e,t)}finally{u--;let e=l.shift();e&&e()}}return d(e,t)};return f.__elurAction={name:t.name||`anonymous`,concurrency:r,idempotent:a,invalidateTags:o,invalidatePaths:s},f}function i(...e){let t=new n;for(let n of e)if(n){if(n.aborted){t.abort();break}n.addEventListener(`abort`,()=>t.abort(),{once:!0})}return t.signal}function a(e){return typeof e==`object`&&!!e&&e.__elur_js_action_failure===!0}function o(e){return typeof e==`object`&&!!e&&e.__elur_js_action_redirect===!0}async function s(t,n=[],r={}){let i=Array.isArray(n)?n:[n],s=await fetch(`/__elur-js/actions`,{method:`POST`,headers:{"Content-Type":`application/json`,Accept:`application/json`},body:JSON.stringify({name:t,page:r.page,args:i})}),c=await s.text();if(!s.ok){let n;try{n=JSON.parse(c)}catch{}if(a(n)&&n.status!==void 0)return new e.t(n.status,n.data);throw Error(`Action "${t}" failed: ${c}`)}let l=JSON.parse(c);return o(l)&&l.status!==void 0&&l.location!==void 0?new e.n(l.status,l.location):l}function c(e,n={}){let r=(0,t.signal)(!1),i=(0,t.signal)(null),a=(0,t.signal)(null);async function o(t){r.value=!0,i.value=null;try{let r=await s(e,t,n);return a.value=r,r}catch(e){throw i.value=e instanceof Error?e:Error(String(e)),e}finally{r.value=!1}}return{submit:o,pending:r,data:a,error:i}}Object.defineProperty(exports,"n",{enumerable:!0,get:function(){return c}}),Object.defineProperty(exports,"r",{enumerable:!0,get:function(){return r}}),Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return s}});
+//# sourceMappingURL=action-BiE4tEty.cjs.map