@elurjs/kit 2.4.4

package/CHANGELOG.md

@@ -0,0 +1,874 @@
+# Changelog
+
+All notable changes to Nix.js 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.4.4]
+
+### Fixed
+
+- **`island()` directive `"only"` never hydrated on the client** — v2.4.3
+  added `"only"` to the SSR side (skip rendering) but the client hydrator
+  (`hydrateIslands`) only had branches for `"load"`, `"idle"`, and
+  `"visible"`. Markers with `data-directive="only"` were silently skipped
+  — the component never mounted, leaving the fallback HTML (or empty
+  marker) permanently. Now `"only"` hydrates immediately like `"load"`.
+- **`hydrateTemplate` did nothing for islands without SSR DOM** —
+  `hydrateTemplate` from the core walks existing DOM for hydration
+  markers (`<!--nix-N-->`, `data-nix-e-*`). Islands with `"only"` or
+  `ssr: false` have no SSR DOM in the marker (only fallback HTML or
+  nothing), so `hydrateTemplate` either silently did nothing (templates
+  with no bindings) or threw a mismatch and remounted (templates with
+  bindings). The hydrator now detects the absence of `<!--nix-` markers
+  and does a fresh `_render` mount instead of `hydrateTemplate`, which
+  is the correct operation when there's no SSR DOM to hydrate against.
+  This also fixes the same issue for `ssr: false` with any directive.
+
+## [2.4.3]
+
+### Fixed
+
+- **`island()` crashed for client-only components after happy-dom removal**
+  — since v2.4.0 removed the happy-dom SSR fallback, `island()` always
+  executed the component during SSR. Any island accessing browser-only
+  globals (`document`, `window`, `navigator`, ...) in its body crashed with
+  `ReferenceError: document is not defined`, breaking carousels, charts, and
+  any third-party widget that touches the DOM. The kit now provides two
+  opt-out mechanisms mirroring the industry standard (Astro `client:only`,
+  Next.js `dynamic(..., { ssr: false })`):
+  - `directive: "only"` — shortcut for client-only with `load` scheduling.
+    The component is never called during SSR; only the fallback is rendered.
+  - `options: { ssr: false }` — client-only with any directive
+    (`load`/`idle`/`visible`), combinable with `options.fallback`.
+  SSR errors are never silently swallowed: they propagate wrapped with the
+  island name and three concrete remediation paths (`"only"`, `{ ssr: false }`,
+  `isSSR()`), matching Astro and Next.js behavior.
+
+### Added
+
+- **`IslandOptions`** — new optional 5th parameter to `island()` with:
+  - `ssr?: boolean` (default `true`, forced `false` when `directive: "only"`)
+  - `fallback?: NixTemplate | string` — HTML rendered inside the island
+    marker when SSR is skipped or the component returns `null`/`false`.
+    Accepts a reactive `NixTemplate` (with signals) or a plain string.
+- **`island()` `fallback` for null components** — when an SSR-safe component
+  returns `null`/`false`/`undefined`, the `fallback` option is now rendered
+  instead of an empty marker.
+- **`isSSR()` exported from the main entry** — reads the Nix.js reactivity
+  SSR flag. Use it to guard environment reads (`window.matchMedia`,
+  `localStorage`, `navigator`) in SSR-safe components. Note: `isSSR()` is
+  NOT a replacement for `"only"`/`ssr: false` — it cannot make
+  `document.querySelectorAll` of the component's own children work, because
+  the DOM is not inserted when the function body runs. For DOM queries of
+  own children, use `NixComponent.onMount()` + `ref`.
+- **`IslandDirective` now includes `"only"`** — the type union is
+  `"load" | "idle" | "visible" | "only"`. The duplicate type definition in
+  `hydrate.ts` was replaced with a re-export from `island.ts` for a single
+  source of truth.
+
+## [2.4.2]
+
+### Fixed
+
+- **`BuildResult.outDir`** — added `outDir` field to `BuildResult` so
+  integration `build` hooks know the actual output directory (the atomic
+  staging temp dir when called via the CLI, not the final `dist/`).
+  Without this, integrations that wrote to `join(context.root, "dist")`
+  had their artifacts wiped by the atomic staging commit. Now integrations
+  can use `result.outDir` to write to the correct directory.
+
+## [2.4.1]
+
+### Fixed
+
+- **Integration `build` hook never invoked** — the `build` hook was
+  declared in `NixKitIntegration` but never called from `build()`.
+  `runIntegrationHook` was only wired for `"config"` (from
+  `config/index.ts`) and `"routes"` (from `manifest/index.ts`). Now
+  `build()` invokes `runIntegrationHook(integrations, "build", [result,
+  ctx])` at the end of the build pipeline, after all pages, image
+  variants, and the manifest are written. This lets integrations
+  generate post-build artifacts (sitemaps, robots.txt, search indexes)
+  into the output directory. The hook fires before the CLI's atomic
+  staging commit, so integration artifacts survive the swap.
+- **`BuildConfig.integrations`** — new optional field. The CLI's
+  `toBuildConfig()` now passes `resolvedConfig.integrations` through.
+
+## [2.4.0]
+
+### Fixed
+
+- **CLI bundling bug — image registry dual instance** — the CLI bundle
+  (`dist/lib/cli.js`) was inlining its own copy of the image registry
+  (`renderRegistry`, `activeManifest`), separate from the chunk
+  `dist/lib/image/index.js` that user pages import. This caused
+  `consumeImageRegistry()` to always return `[]`, so the two-pass image
+  pipeline silently processed nothing (no manifest, no variants, no
+  `<picture>`). Fixed by extracting the registry state to a dedicated
+  chunk `src/image/registry.ts` and externalizing it in
+  `vite.cli.config.ts` via a custom plugin, so the CLI imports the same
+  physical `./image/registry.js` chunk that `image/index.js` uses.
+- **`raw()` missing `renderServer`** — after removing the happy-dom
+  fallback, the core's DOM-free `renderToString` requires templates to
+  expose `NIX_RENDER_PROTOCOL.renderServer`. `raw()` only had `mount`
+  and `_render` (DOM-dependent), causing "Template does not support
+  server rendering" errors. Fixed by adding `renderServer: () => html`
+  to `raw()`, matching the pattern already used by `image()` and
+  `island()`.
+- **Streaming response test mocks** — updated mock templates in
+  `test/streaming-response.test.ts` to use `renderServer` instead of
+  DOM-dependent `_render`, and removed an invalid `supportsStreaming({})`
+  call that didn't match the `Pick<AdapterCapabilities, "streaming">`
+  parameter type.
+
+### Changed
+
+- **`happy-dom` fully removed** — the kit no longer references happy-dom
+  anywhere. The SSR runtime uses the core's DOM-free `renderToString`
+  (`@deijose/nix-js/server`) directly, with no DOM fallback. Removed
+  from `peerDependenciesMeta`, from both vite build configs
+  (`external`/`globals`), and from `src/render/render-to-string.ts`
+  (the `renderWithDom` fallback and `MANAGED_GLOBALS` injection were
+  deleted). The `test/happy-dom-optional.test.ts` now asserts happy-dom
+  is absent from all dependency fields.
+- **Config file renamed: `nix.config.*` → `nix-js.config.*`** — the
+  generic `nix.config.ts` name was a design error that could collide
+  with other tools. The kit now looks for `nix-js.config.{ts,js,mjs}`
+  first. Legacy `nix.config.*` files are still detected for backward
+  compatibility, but emit a deprecation warning guiding migration.
+  `doDoctor` reports legacy config files as `warn` status.
+
+### Added
+
+- **`src/image/registry.ts`** — new shared singleton module owning the
+  image pipeline's mutable state (`renderRegistry`, `activeManifest`).
+  Exported as `dist/lib/image/registry.js` and added to
+  `tsconfig.lib.json` and `vite.lib.config.ts` entry points. Both the
+  CLI bundle and the library chunk import this physical file, ensuring
+  a single module instance across the build pipeline.
+
+## [2.3.0]
+
+### Changed
+
+- **Interpolation now delegates to the Vite plugin** — when
+  `@deijose/vite-plugin-nix-js` >= 1.1.0 is installed, the kit's legacy
+  interpolation transform is skipped (the plugin's state-machine lexer takes
+  precedence). The kit's transform remains as a fallback for projects that
+  use the kit without the plugin.
+- New `pluginSupportsPartialInterpolation()` function detects the Vite plugin
+  at runtime.
+- `shouldUseLegacyInterpolation("auto")` now returns `false` when the plugin
+  is installed, `true` when neither the plugin nor the core supports partials.
+- `@deijose/vite-plugin-nix-js` added as an optional peer dependency.
+
+### Migration
+
+- Install `@deijose/vite-plugin-nix-js` >= 1.1.0 for the best interpolation
+  support (state-machine lexer, compile-time errors, raw-text tag handling).
+- The kit's legacy transform still works without the plugin but is less
+  powerful (no comment/raw-text handling, no boolean attr validation).
+
+## [2.2.1]
+
+### Changed
+
+- `coreSupportsPartialInterpolation()` and `shouldUseLegacyInterpolation()`
+  are now exported from `@deijose/nix-js-kit/vite` so consumers can resolve
+  the interpolation mode programmatically.
+
+## [2.2.0]
+
+### Changed
+
+- **Native partial attribute interpolation** — when the installed Nix.js core
+  exposes `templateFeatures.partialAttributeInterpolation` (core ≥ 3.3), the
+  kit no longer injects the legacy `nixJsInterpolationPlugin` transform
+  (`interpolation: "auto"`). Partial attributes now run through the runtime's
+  native normalization, which preserves fine-grained reactivity instead of
+  collapsing getters into a static concatenation.
+  - New `interpolation: "auto" | "legacy" | "off"` option on `nixJsKit()`,
+    `buildClientBundle()` and `transformProjectFiles()`.
+  - `interpolation: "legacy"` forces the old transform for migrations and
+    emits a one-time deprecation warning; `interpolation: "off"` disables it.
+  - `transformPartialInterpolations` stays exported for direct consumers and
+    is marked deprecated.
+
+## [2.1.0]
+
+### Added — five reported limitations fixed
+
+- **#1: Route-level code-splitting** — the generated client entry already uses
+  `import()` per island, producing separate chunks per page for a minimal
+  initial bundle. Documented and verified with tests.
+- **#2: Layout Slots** — `*.slot.ts` files are now detected by the route
+  scanner and passed to layout components as named slots (`slots.sidebar`,
+  `slots.header`, etc.). Route groups (`(group)`) already worked; this adds
+  named slot composition on top.
+- **#3: Redis / Upstash / Cloudflare KV cache adapters** — new
+  `createRedisCacheAdapter()` and `createCloudflareKVCacheAdapter()` in
+  `@deijose/nix-js-kit/cache`, implementing the same `CacheAdapter` interface
+  as the filesystem adapter. Tag-based invalidation works via Redis sets or
+  KV JSON indexes.
+- **#4: Real Suspense streaming** — `streamBoundary()` and
+  `createStreamingResponse()` now emit a `<template>` chunk + replacement
+  script that swaps the fallback `<div>` for the resolved content in-place
+  (using `replaceWith`), instead of the old `innerHTML` append pattern.
+  New helpers: `buildFallbackHtml()`, `buildResolvedChunk()`.
+
+### Changed
+
+- **#5: `happy-dom` moved to optional peer dependency** — removed from
+  `dependencies`, added to `peerDependenciesMeta` with `optional: true`.
+  The SSR runtime loads it via dynamic `import("happy-dom")` only when the
+  core renderer needs a DOM fallback; it is never bundled into client code.
+
+## [2.0.4]
+
+### Added — recursive content collections
+
+- `getCollection()` now scans nested directories and derives nested slugs
+  (e.g. `getting-started/intro`), removing the need for manual content scanners.
+
+## [2.0.3]
+
+### Added — island HMR (Vite plugin)
+
+- The generated client entry now registers `import.meta.hot.accept` so island
+  module changes are **hot-swapped without a full page reload**: current islands
+  are disposed and re-hydrated from the updated modules (audit §10.2 / §12.2).
+- New E2E in `example/e2e/hmr.spec.ts` (Playwright + Vite plugin dev server)
+  verifies the DOM updates with `performance navigation` count unchanged.
+- Script: `npm run test:e2e:hmr`.
+
+## [2.0.2]
+
+### Fixed — compliance and correctness (audit §8–§10)
+
+- **Unified CLI request pipeline** — `handleRequest` (dev/preview) now delegates
+  to `createWebHandler`, the same code used by the Node/Bun/Vercel/Netlify
+  adapters. The duplicated actions/render-endpoint/API/static/SSR/404/500
+  pipeline in `src/cli.ts` was removed (audit §8.1, Risk 1).
+- **`start` with missing middleware (Bun)** — `loadMiddleware` matched
+  "module not found" via `err instanceof Error`, but Bun's `ResolveMessage` is
+  not an `Error` instance, so projects without `src/middleware.ts` failed to
+  start. Detection now uses the message property directly.
+- **Stale content after server actions under SSR** — the `start` server and the
+  unified handler rewrite the baked `nix-js:render-endpoint content="off"` meta
+  to `"on"` when serving static HTML, so SPA navigations after a mutating
+  action fetch live server-rendered content instead of the stale static file
+  (fixes e.g. "review published without reload").
+- **Stale core bundled in the CLI** — `vite.cli.config.ts` externalizes
+  `@deijose/nix-js/*` (including subpaths) so the CLI never bundles an
+  outdated copy of the core server renderer.
+- **Island loader detection without probing** — the registry now uses a
+  discriminated `{ load }` lazy form plus `AsyncFunction` detection (never
+  invoking the component as a probe, avoiding side effects / duplicate signal
+  creation). New `lazyIsland()` helper (audit §10.3).
+- **Production error sanitization** — new `toPublicErrorInfo()` /
+  `publicErrorResponse()` in `src/errors.ts`; the unified handler, action
+  server and adapters no longer expose `String(err)` (paths/stacks/secrets) in
+  responses (audit §8.4, Risk 5).
+
+### Added — static serving, images and capabilities
+
+- **Static serving Range/If-Range/HEAD** — `serveStaticFile` now supports
+  `Accept-Ranges`, single `Range` with `If-Range` (ETag or date), `206` with
+  `Content-Range`, `416` for unsatisfiable ranges, and uniform HEAD responses
+  (audit §8.3).
+- **Image pipeline hardening** — SHA-256 transform keys (content + normalized
+  options + encoder/naming versions), path containment for sources and outputs
+  (no traversal/NUL/symlink escape), atomic temp+rename writes, single-flight
+  per transform key, bounded concurrency pool, and `images.strict` build mode
+  (audit §9.4–§9.7).
+- **`getImage()` and `ImageService`** — programmatic async image API and the
+  `ImageService`/`createImageService` contract with declared capabilities
+  (audit §9.2–§9.3).
+- **Adapter capability contract** — `AdapterCapabilities` (streaming,
+  filesystem none/readonly/persistent/ephemeral, imageRuntime, backgroundWork,
+  maxBodySize), defaults for full/serverless/edge hosts, and build-time
+  `validateCapabilities()` diagnostics in the CLI `adapter` command
+  (audit §8.5).
+
+### Test
+
+- New suites: static range/HEAD (10), error sanitization (6), image hardening
+  (12), capabilities (10), cross-runtime parity (3), island lazy-loader
+  detection (3). Full suite at 442 tests (was 398). Fixed pre-existing failing
+  tests: island entry generator (`require` in ESM), benchmark variance
+  threshold, and the router clear-cookie test (happy-dom does not honor
+  `Max-Age=0` removal).
+
+### Docs
+
+- README: streaming labelled experimental; static serving now documents
+  Range/HEAD. See `docs/nix-js-kit/` for the full remediation record.
+
+## [2.1.x] — v2 development
+
+### Fixed — v2.0.1 patch: hydration and asset serving
+
+- **SSR hydration markers** — `renderToString` in `src/render/render-to-string.ts` now passes `markers: "hydration"` to the core `renderServer` by default. Previously it omitted the option, so the SSR output had no `<!--nix-N-->` comments or `data-nix-e-*`/`data-nix-a-*` attributes, causing `[nix-js] Hydration marker mismatch: Template has no hydration descriptor` on every island.
+- **Island async loader detection** — `src/island/hydrate.ts` detected lazy loaders via `entry.constructor?.name === "AsyncFunction"`, but `() => import(...).then(m => m.default)` is a regular function returning a Promise, not an `AsyncFunction`. This caused `e._render is not a function` because the loader function was passed directly to `hydrateTemplate` instead of being awaited. Fixed by probing the entry and checking `result instanceof Promise`.
+- **Client bundle base path** — `buildClientBundle` in `src/cli.ts` used `base: "/"` by default, so Vite's modulepreload helper generated URLs like `/assets/ThemeToggle.js` instead of `/_nix-js/assets/ThemeToggle.js`, causing 404s for all island chunks. Fixed by hardcoding `base: "/_nix-js/"` for the client bundle (independent of the project's deployment `base`).
+- **Test assertions updated** — integration, render, preview, and adapter tests now strip `<!--nix-N-->` / `<!--nix-end-N-->` hydration markers before content assertions, since SSR output now includes them by default.
+
+### Added — Phase 13: Verification, packaging, audit, benchmarks
+
+- **Package smoke test** — `test/package-smoke.test.ts` validates tarball creation, ESM/CJS entry imports, CLI binary, exports map, Node engine, and tarball contents (no src/test/scripts leaked).
+- **Path traversal fuzz tests** — `test/path-traversal-fuzz.test.ts` (20 tests) covers encoded traversal (`%2e%2e`, `%2f`, `%5c`), mixed separators, NUL bytes, Unicode normalization (U+FF0E, U+FF0F), prefix-sibling paths, and symlink escape (A-06).
+- **CSRF cross-origin tests** — `test/csrf-origin.test.ts` (19 tests) covers same-origin, cross-origin, missing headers, `strictOrigin` mode, allow-list, invalid headers, non-HTTP protocols, and `Sec-Fetch-Site` (A-07).
+- **Cache concurrency + isolation tests** — `test/cache-concurrency.test.ts` (13 tests) covers single-flight deduplication, stale-while-revalidate, private/public isolation (cookies, Authorization, no-store), atomicity, collision resistance, and tag invalidation (A-08).
+- **SSR benchmark baseline** — `test/benchmark-ssr.test.ts` measures `renderToString` throughput (126,940 renders/sec on the test machine) with a budget floor of 500 renders/sec for regression detection.
+- **RequestContext tests** — `test/request-context.test.ts` (17 tests) verifies per-request state: `params`, `locals` isolation, `cookies` (read/write), `signal`, `requestId` uniqueness, `platform`, `response` state, and `applyToResponse()` merging.
+- **`bun audit`** — zero vulnerabilities after lockfile cleanup (A-24).
+- **`publint`** — `All good!` after splitting `types` conditions into `import`/`require` and adding `.d.cts` declaration copies.
+- **Pendientes documentados** — `docs/nix-js-kit/pendientes-infraestructura.md` lista los items que requieren infraestructura externa (Playwright E2E, CI matrix, Provenance/SBOM, `arethetypeswrong`, examples, Lighthouse).
+
+### Changed — Phase 13
+
+- **`RequestContext` aligned with runtime-security §4** — added `params`, `locals`, `cookies` (CookieJar), `signal` (AbortSignal), `requestId` (auto-generated UUID), `platform`, `route`, and `response` (ResponseState with mutable headers and ResponseCookieJar). New `applyToResponse()` method merges accumulated headers, Set-Cookie values, and status into the final Response. New types: `CookieJar`, `ResponseCookieJar`, `CookieOptions`, `ResponseState`.
+- **`handleApiRoute`** now passes `locals` alongside `params` to API route handlers.
+- **`src/runtime/index.ts`** exports the new cookie and response types.
+- **`defineAction`** and related types now exported from `src/index.ts` (main entry).
+
+### Added — Phase 10: Actions, middleware, cookies, cache/ISR
+
+- **`defineAction()`** — typed server action definition with input validation (`.parse()`), AbortSignal propagation, idempotency metadata, and concurrency modes (`latest`, `queue`, `parallel`). Legacy action exports preserved.
+- **`CacheAdapter`** — filesystem cache with SHA-256 identity keys, atomic temp+rename writes, single-flight per process, stale-while-revalidate (`getWithSWR()`), tag-based invalidation, size limits and periodic cleanup.
+- **Cache policy per route** — `CachePolicy` with `public`/`private`/`dynamic` modes, `normalizeCachePolicy()` reads `export const cache` from data modules, `shouldCachePublic()` enforces no public caching for requests with cookies/auth/action-state.
+- **Middleware propagation** — `next()` now carries `params` and `locals`, cleanup callbacks executed in `finally`, `loadMiddleware()` distinguishes "file not found" from "file has errors".
+- **Cache invalidation hub** — `CacheInvalidator` pub/sub with `connectCacheAdapter()`, `defaultInvalidator` singleton. Actions emit tags/paths; cache listens. No coupling to `nix-query`.
+
+### Added — Phase 11: Streaming, routing, content, SEO, integrations
+
+- **Real streaming** — `createStreamingResponse()` with `ReadableStream` that sends shell + loading fallback, then resolved content chunks with deterministic IDs. `createBufferedResponse()` for adapters without streaming. `streamBoundary` uses `AsyncLocalStorage` per-request.
+- **Optional catch-all** — `[[...slug]]` route segments that match the base path and any depth.
+- **Route conflict detection** — `scanRoutes()` throws on duplicate path patterns during manifest generation.
+- **Safe URL decoding** — `safeDecodeURIComponent()` handles malformed percent-encoding without throwing.
+- **Redirects/rewrites/route headers** — `matchRedirect()`, `matchRewrite()`, `matchRouteHeaders()` with `:param` and `*` wildcard support.
+- **Sitemap from route manifest** — `generateSitemapFromRoutes()` excludes dynamic/API/error routes, supports `extraUrls` for dynamic routes, splits into sitemap index for >50,000 URLs.
+- **Content scope per request** — `withContentRoot()` via `AsyncLocalStorage`, cache key includes root, collection name containment validation (no path traversal).
+- **Integration hooks** — typed registry for `I18nIntegration`, `AuthIntegration`, `QueryIntegration`, `TestingIntegration` + custom integrations. Optional packages register without being dependencies.
+
+### Added — Phase 12: DX, scaffold, observability
+
+- **CLI commands** — `check` (typecheck + route/config integrity), `routes` (list all discovered routes), `doctor` (diagnose common issues).
+- **Structured logger** — `StructuredLogger` with request ID generation, `Server-Timing` header accumulation, sensitive data redaction (cookies, auth headers), structured JSON output in production.
+- **Error messages** — `formatError()` with cause/path/suggestion format, reliable exit codes (`ExitCode`).
+- **create-nix-app template** — `template-kit` with config, public, islands, content, tests, adapter-ready scripts.
+
+### Security hardening (Phase 10)
+
+- JSON-LD escapes `<`, `>`, `&`, U+2028, U+2029 to prevent script injection (A-19).
+- Action error cookies signed with HMAC SHA-256 (A-20).
+- Body limits enforced with stream reading and `413` responses (§8.2).
+- Default security headers: `X-Content-Type-Options`, `Referrer-Policy`, `X-Frame-Options`, CSP with nonce support, HSTS when appropriate, Permissions-Policy.
+- Static serving with `ETag`/`If-None-Match`, `Last-Modified`/`If-Modified-Since`, immutable caching for hashed assets.
+- `throw new Response()` treated as first-class HTTP control flow from loaders and layout loaders (A-22).
+- No public caching of responses with `Set-Cookie`, `private`, or `no-store`.
+
+---
+
+## [1.x] — Release history
+
+## 1.4.8
+
+### Added
+
+- **Full Open Graph image metadata** — `OpenGraphMetadata` now supports `imageAlt`, `imageWidth`, `imageHeight`, and `imageType`, emitted as `og:image:alt`, `og:image:width`, `og:image:height`, and `og:image:type`. `TwitterMetadata` gained `imageAlt` (`twitter:image:alt`). Social scrapers (Twitter/X, LinkedIn, iMessage, WhatsApp) use these tags to render share previews reliably.
+
+## 1.4.7
+
+### Fixed
+
+- **No more 404 storms on static deployments** — static builds now emit `<meta name="nix-js:render-endpoint" content="off">` in the HTML `<head>`, so the client router skips the `/__nix-js/render` endpoint entirely (zero 404 requests). For older builds without the marker, endpoint detection now uses a single shared probe promise — concurrent prefetches generate at most **one** request to the endpoint, and any other failed page falls back to HTML fetching without disabling the endpoint globally.
+
+### Changed
+
+- **Prefetch is now interaction-only by default (Astro-style)** — the router prefetches internal pages on hover/focus instead of prefetching every visible link on load. This removes the post-load burst of page fetches that competed with fonts and images for bandwidth on slow connections. Links can opt back into viewport prefetching with `data-prefetch="viewport"`.
+
+### Added
+
+- **`renderEndpoint` build option** — `BuildConfig.renderEndpoint` (default `true`) controls whether the built HTML announces the render endpoint as available. The SSG `build()` passes `renderEndpoint: false` automatically; dev/preview/SSR servers leave it enabled.
+
+## 1.4.6
+
+### Fixed
+
+- **SPA router now works on static deployments** — when the `/__nix-js/render` endpoint is unavailable (Vercel static, Netlify static, GitHub Pages), the router falls back to fetching the full HTML page and extracting `#app` + `<head>` tags. This enables SPA navigation without a server, matching the dev-mode experience.
+
+## 1.4.5
+
+### Added
+
+- **`headLinks` support in data loaders** — loaders can now return a `headLinks: string[]` array of raw HTML strings (e.g. `<link rel="icon">`, `<link rel="manifest">`, `<meta name="theme-color">`) that are injected directly into `<head>`, alongside the existing `headScripts`. Deduplicated across layout and page data.
+
+## 1.4.4
+
+### Fixed
+
+- **Removed dependency on `_setSSR` from `@deijose/nix-js`** — the published 2.6.0 on npm does not export `_setSSR`/`_isSSR`. The kit now manipulates the reactivity state's `ssr` flag directly via a local `setSSR()` utility in `src/render/ssr-flag.ts`. This fixes the Vercel build error: `SyntaxError: Export named '_setSSR' not found`.
+
+## 1.4.3
+
+### Fixed
+
+- **Pinned `@deijose/nix-js` to 2.6.0** — fixed a build error on Vercel where `^2.5.3` resolved to a newer version that no longer exports `_setSSR`.
+
+## 1.4.2
+
+### Fixed
+
+- **Hash link navigation** — the SPA router now handles `#anchor` links with smooth scroll instead of ignoring them or reloading the page.
+- **Scrollable element preservation** — elements marked with `data-scroll-preserve="key"` have their scroll position saved and restored across SPA navigations, preventing sidebar scroll resets.
+
+## 1.4.1
+
+### Fixed
+
+- **JSON-LD in headScripts** — `documentShell` now detects when a `headScript` is already a complete `<script>` tag (e.g. `<script type="application/ld+json">...`) and renders it as-is instead of wrapping it in another `<script>` tag.
+
+## 1.4.0
+
+### Added
+
+- **SEO module** (`@deijose/nix-js-kit/seo`) — sitemap.xml, robots.txt, and JSON-LD structured data generation:
+  - `generateSitemap({ siteUrl, urls, outDir })` writes a valid `sitemap.xml` from a list of URL entries (supports `lastmod`, `changefreq`, `priority`).
+  - `generateRobots({ siteUrl, outDir, rules?, disallow? })` writes a `robots.txt` with per-user-agent rules and automatic sitemap reference.
+  - `jsonLd(schema)` serializes Schema.org structured data into a `<script type="application/ld+json">` tag for rich snippets.
+  - Full TypeScript types for all config objects.
+
+## 1.3.1
+
+### Fixed
+
+- **SPA router FOUC fix** — stylesheets (`<link rel="stylesheet">`) and `<style>` tags rendered inside `#app` by layouts are now hoisted to `<head>` on page load and before every SPA navigation, preventing flash-of-unstyled-content on route changes.
+- **`headScripts` deduplication** — `collectShellExtras()` now deduplicates `headScripts` from page and layout data, preventing duplicate inline scripts (e.g. anti-flash theme scripts) when both layers emit the same script.
+
+## 1.3.0
+
+### Added
+
+- **CSRF protection for server actions** — `verifyOrigin()` checks the `Origin`/`Referer` header against the `Host` header with optional `allowedOrigins` and `strictOrigin` mode. Configured via `actionSecurity` in the Vite plugin and SSR server options.
+- **Action error cookie store** — action failure data is now stored in an ephemeral `__nix_js_action_error` cookie (SameSite=Lax, Max-Age=15s) instead of URL query parameters, improving security and privacy. `props.form` is populated from the cookie and cleared on the next response.
+- **Metadata API** — pages can export `generateMetadata(context)` or return a `metadata` field from loaders/layouts. Supports `title`, `description`, `canonical`, `openGraph`, `twitter`, `robots`, and `other` fields. Head tags are marked with `data-nix-js-head` for SPA head merge.
+- **Head merge in SPA router** — the client router swaps `<head>` tags marked with `data-nix-js-head` on every navigation, keeping metadata in sync with the current page.
+- **Scroll restoration** — the client router saves and restores scroll position per path on `popstate`, so back/forward navigation feels native.
+- **Content layer** (`@deijose/nix-js-kit/content`) — typed Markdown collections with YAML frontmatter:
+  - `defineCollection({ schema })` for typed frontmatter validation (optional `zod` peer dep).
+  - `getCollection(name)`, `getEntry(collection, slug)`, `getEntries(collection, slugs)` for querying content.
+  - `renderEntryHTML(entry)` renders Markdown to HTML via `marked` (optional peer dep).
+  - Built-in YAML frontmatter parser (strings, numbers, booleans, dates, inline/block arrays) — zero dependencies.
+  - `raw(html)` helper for injecting trusted HTML without escaping (e.g. rendered Markdown).
+  - HMR for `.md` files in the Vite dev server.
+  - `src/content/config.ts` convention for collection definitions.
+- **Image optimization** (`@deijose/nix-js-kit/image`):
+  - `image()` helper emits responsive `<img>` with `srcset`, `sizes`, `loading="lazy"`, `decoding="async"`, `fetchpriority`, and `width`/`height` to prevent CLS.
+  - Build-time pipeline with `sharp` (optional peer dep) generates WebP/AVIF variants at multiple widths with content-based hashing.
+  - `processImages()` API for programmatic access; integrated into `build()` via `consumeImageRegistry()`.
+  - `BuildConfig.publicDir` and `BuildConfig.imageFormats` options; `BuildResult.imagesProcessed` reports variant count.
+- **Link prefetch** — the client router prefetches pages on viewport intersection (IntersectionObserver) and on hover/focus, with a 30s TTL cache. Respects `data-no-prefetch` attribute on individual links.
+- **View Transitions API** — the client router uses `document.startViewTransition()` for smooth page transitions when available, with automatic `prefers-reduced-motion` respect.
+- **Middleware** — `src/middleware.ts` convention with `config.matcher` for path filtering. Supports `:param` and `:param*` patterns. Return a `Response` to short-circuit (redirect, 401, etc.) or call `next()` to continue. Integrated into SSR server and Vite plugin.
+- **Stream boundary** (experimental) — `streamBoundary()` wraps a promise with a loading fallback for out-of-order streaming during SSR.
+
+### Changed
+
+- Action error data moved from URL query params to ephemeral cookies (`__nix_js_action_error`) for security and privacy.
+- Head tags use `data-nix-js-head` attribute (was `data-nix-head` internally) for consistent `nix-js` naming.
+- `BuildResult` now includes `imagesProcessed` count.
+- `SsrServerOptions` includes `actionSecurity` for CSRF configuration.
+- `NixJsKitViteOptions` includes `actionSecurity`, `contentDir` for content layer root.
+- TypeScript upgraded to 7.0.2 (native Go compiler, 10x faster builds). `baseUrl` removed from `tsconfig.json` (deprecated in TS 7); `paths` now resolve relative to the config file.
+- `marked`, `zod`, and `sharp` added as optional peer dependencies via `peerDependenciesMeta`.
+
+## 1.2.7
+
+### Changed
+
+- All identifiers now use the `nix-js` / `nixJs` naming consistently. Public API: `nixAction` is now `nixJsAction` (and the `NixAction` interface is `NixJsAction`). Form protocol fields are now `__nix_js_action_name`, `__nix_js_action_page`, `__nix_js_action_failure`, `__nix_js_action_redirect` and `__nix_js_action_error`; island DOM markers use `__nix_js_island_dispose`. The default document title is `Nix.js Kit App`.
+
+## 1.2.6
+
+### Added
+
+- `fail()` and `redirect()` now accept both argument orders (`fail(400, data)` or `fail(data, 400)`, `redirect(303, "/x")` or `redirect("/x")`) and are detected via marker fields, so they work even when the CLI/adapters are bundled separately from the user's action modules.
+- Source transform (`transformProjectFiles`) mirrors the project layout and compensates relative imports that escape the mirrored tree, so apps importing outside `src/` (e.g. the kit's own example) build correctly.
+- Vite plugin now serves the `/__nix-js/render` endpoint (HTML or JSON) used by the SPA router and streaming boundaries.
+- ISR now also caches the `/__nix-js/render` endpoint, so streamed pages (with `loading.ts`) regenerate on their `revalidate` TTL instead of being skipped.
+- Data loaders (page and layouts) can return a top-level `htmlAttributes` object to set attributes on the `<html>` element of the document shell (e.g. `{ "data-theme": "dark" }`), applied in SSG, SSR and streaming shells — useful for themes persisted via cookie that must survive redirects.
+- Data loaders can also return `headScripts: string[]`: inline scripts injected into `<head>` that run synchronously before the first paint and before the deferred client bundle. This is the standard no-flash bootstrap (e.g. applying a stored theme to static pages whose SSG shell was baked with the build-time theme).
+- The client router now exports `navigateTo(pathname, search, push)`: a programmatic SPA navigation that fetches the fresh page body from `/__nix-js/render`, swaps `#app`, updates the title and re-hydrates islands. Server actions can use it after a redirect to show fresh server data (e.g. a new review) without a full reload that would serve a stale static page.
+
+### Fixed
+
+- CLI bin re-executes itself under the Bun runtime for bun-managed projects, so apps using `bun:sqlite` work with `nix-js-kit build/dev/start/preview`.
+- Attribute interpolation plugin: rewritten with a proper template scanner. Handles nested braces/strings in expressions, single-quoted attributes, comments, and leaves full-value quoted interpolations (`datetime="${x}"`) and unquoted bindings (`value=${() => x}`) untouched.
+- Streaming shells now fetch the concrete path (`/blog/:slug` → `/blog/hello-world`) instead of the route pattern.
+- Client router now requests JSON (`{ title, body }`) from the render endpoint (titles update on SPA navigation), preserves query strings, and ignores modifier-key clicks.
+- Island `data-props` serialization escapes single quotes, so props containing apostrophes hydrate correctly.
+- Declaration files are emitted with explicit `.js` extensions, fixing type resolution for NodeNext consumers; the main entry no longer re-exports the CLI or the Vite plugin (use `@deijose/nix-js-kit/cli` / `@deijose/nix-js-kit/vite`), removing the CLI side-effect from adapter bundles.
+- Adapters: the SSR entry now embeds the full route table (no runtime filesystem scanning), includes `layout.data.ts` modules in the registry, fixes action resolution by page scope, preserves the query string for page rendering, and serves the `/__nix-js/render` endpoint (HTML or JSON) so the SPA router and streaming keep working in production. Works with Node (`node:sqlite`) and Bun (`bun:sqlite`) runtimes.
+- SSR page rendering now forwards the request query string as `searchParams` to loaders.
+- Cookies are forwarded to API routes and server actions in every server mode, so auth/middleware that reads the session works in `start`, `preview`, `dev` and the Vite plugin.
+- Server actions scoped to dynamic routes now work: the resolver maps concrete page paths (`/movies/inception`) to their route pattern (`/movies/:slug`) in `start`, `preview`, `dev`, the Vite plugin and all adapters.
+- The client hydration bundle is now built through a wrapped Vite config that automatically injects the attribute-interpolation plugin, so partial interpolations inside islands (e.g. `href="/movies/${slug}"`) hydrate correctly instead of producing broken attributes.
+- `preview` now renders the custom 404/500 error pages instead of plain-text responses.
+- The `/__nix-js/render` endpoint returns a clean 404 (instead of a 500 with a stack trace) when the requested path has no matching route, in every server mode and in the adapters.
+- Dev server (`nix-js-kit dev`) now runs the actual server in a child process supervised by a watcher: any source change restarts the worker, so page/loader/layout/island edits are always served (previously the ESM module cache served stale modules). Atomic saves (sed/editors) are detected via `rename` events.
+- The dev supervisor exits on SIGTERM so stale processes cannot hold the port.
+
+## 1.2.5
+
+### Added
+
+- `layout.data.ts` support: `renderPage` now resolves the nearest `layout.data.ts` loader for each `layout.ts` and passes the returned data to the layout component.
+- Data loaders (page and layout) now receive the current `Request` object in their context, enabling SSR auth, cookies, and per-request headers.
+- Streaming and SSR servers forward the request to both static and streaming render paths so loaders can read session cookies.
+
+### Changed
+
+- `LayoutProps` data is now populated from `layout.data.ts` when present; `PageProps` retains the `layoutData` slot for future nested layout support.
+
+## 1.2.4
+
+### Fixed
+
+- Client router now re-hydrates islands after navigating to a new page. The generated client entry listens for the `nix-js:rendered` event and mounts islands over the swapped page body.
+- Hydration no longer flashes the static markup: it renders the live island into a `DocumentFragment` and swaps the entire island content with `replaceChildren` in one DOM operation.
+- Old island effects are disposed before the client router swaps `#app.innerHTML`, preventing leaked effects and stale DOM writes after SPA navigation.
+- Vite interpolation plugin rewrites partial attribute interpolations (e.g. `href="/blog/${slug}"`) into a single interpolation in both `src/app` and `src/islands` files during the source transformation step.
+
+## 1.2.3
+
+### Fixed
+
+- Dynamic API routes (`[slug]/route.ts`) now receive route parameters as a second argument (`{ params }`) in `nix-js-kit start`, `preview` and `dev`, matching the behavior already documented for API routes.
+
+## 1.2.2
+
+### Changed
+
+- Server action registry serialized in the HTML shell now exposes only action names per page (`{"/contact":["subscribe"]}`), never file paths or implementation details.
+- Client router is no longer inlined in every HTML page. It is bundled into the generated client entry (`/_nix-js/entry-client.js`) via `startClientRouter()` from `@deijose/nix-js-kit/router`, so routing code lives in the JS bundle like other frameworks.
+
+## 1.2.1
+
+### Fixed
+
+- Server action file paths serialized in the HTML shell (`<script id="nix-js-actions">`) are now relative to the project root instead of absolute server paths. This prevents leaking the host file system layout (e.g. `/home/user/...`) in production HTML.
+
+## 1.2.0
+
+### Added
+
+- Vite interpolation plugin transforms partial attribute interpolations (`href="/blog/${slug}"`) into single Nix.js interpolations automatically.
+- Source transformation runs before build/dev/start/preview so authors can write natural `href` attributes without manual workarounds.
+- Inline client-side router in the HTML shell: intercepts internal link clicks, fetches page body from `/__nix-js/render`, swaps `#app` and updates `history.pushState`.
+- `preview` server falls back to on-demand SSR for routes that do not exist in the static `dist/` (e.g. dynamic slugs).
+- Client hydration bundle is built automatically when a `vite.client.config.ts` exists.
+
+## 1.1.1
+
+### Added
+
+- Streaming `loading.ts` boundaries: shell renders loading UI and client fetches real content from `/__nix-js/render`.
+- `renderStreamingPage` and `renderPageBody` helpers exported.
+- `streaming` option for `createSsrServer` (defaults to true when a page has `loading.ts`).
+
+## 1.1.0
+
+### Added
+
+- ISR (Incremental Static Regeneration) with disk-based cache.
+- `revalidate` export support in `page.data.ts`.
+- `cacheDir` and `defaultRevalidate` options for `createSsrServer` and `nix-js-kit start`.
+- Cache helpers exported: `getCachedHtml`, `setCachedHtml`, `clearCache`.
+- `renderPage` now returns `{ html, revalidate? }`.
+
+## 1.0.0
+
+### Added
+
+- Official v1.0 release. The framework is now stable with full test coverage.
+- All v1.0 roadmap items completed: unit and integration tests, HMR, automatic `PageProps<typeof load>` typing, `nixJsAction`, scoped actions, progressive enhancement, `fail()`/`redirect()`, `route.ts` API endpoints, and `loading.ts` boundary scanning.
+
+## 0.11.7
+
+### Added
+
+- `fail()` and `redirect()` helpers for server actions with client-side detection in `callAction`/`nixJsAction`.
+- `route.ts` API endpoints supported in SSR server, Vite dev server, CLI preview/dev, and all adapters.
+- `loading.ts` boundary scanned and included in the SSR module registry.
+- `matchApiRoute` helper exported for dispatching API routes.
+- Tests for `fail()`/`redirect()`, API routes, and loading boundaries.
+
+## 0.11.6
+
+### Added
+
+- Integration test for the preview server (`doPreview`): serves static files and handles server actions.
+- `doPreview` now returns the Node `http.Server` instance for easier programmatic control and testing.
+
+## 0.11.5
+
+### Added
+
+- Integration tests for Vercel and Netlify adapters: build handlers and verify SSR responses.
+- Integration test for Bun adapter: build server entry and verify it serves SSR with `bun run`.
+- Cleanup hooks for Vercel/Netlify/Bun adapter tests.
+
+## 0.11.4
+
+### Added
+
+- Integration tests for static build + SSR server.
+- Node adapter integration test: builds `.nix-js/node-server.mjs` and verifies it serves SSR pages.
+- Unit tests for `nixJsAction` helper (pending, data, and error signals).
+- Cleanup hooks for integration tests to remove temporary `dist/` and `.nix-js/` folders.
+
+## 0.11.3
+
+### Added
+
+- Initial test suite using Node's built-in test runner (`node:test`) and `tsx` for TypeScript imports.
+- Tests for `scanRoutes`, `scanActions`, `handleActionRequest` (JSON and form), and `renderPage`.
+- `test/fixtures/minimal` with sample pages, data loaders, actions, layout, and a dynamic route.
+- `npm test` and `npm run test:watch` scripts.
+
+## 0.11.2
+
+### Added
+
+- `PageProps<typeof load>` and `LayoutProps<typeof load>` now automatically infer the loader's return type (with `Awaited` for async functions).
+- README quick example and dynamic route example use `PageProps<typeof load>`.
+- Example home page uses `PageProps<typeof load>` instead of a manually exported interface.
+
+## 0.11.1
+
+### Added
+
+- HMR for routes, actions, loaders, and islands in the Vite dev plugin.
+- Vite dev plugin now resolves actions via `ssrLoadModule` so changed `page.action.ts` files are reloaded without a server restart.
+
+## 0.11.0
+
+### Added
+
+- `nixJsAction` helper in `@deijose/nix-js-kit/action` with reactive `pending`, `error`, and `data` signals.
+- Per-page action scoping: `scanActions` now returns `ActionRegistry` keyed by page URL path.
+- `callAction` accepts an optional `{ page }` option to resolve actions scoped to a specific route.
+- Progressive enhancement: `POST /__nix-js/actions` also accepts HTML form submissions and redirects back when `Accept: application/json` is missing.
+
+### Changed
+
+- Action registry serialized in `<script id="nix-js-actions">` is now grouped by page path.
+- All action resolvers (SSR server, CLI dev/preview, Vite plugin, adapters) resolve by page first, then fall back to a global search.
+- `callAction` signature updated to `callAction(name, args, options?)` where `args` can be a single value or an array.
+- `callAction` now sends `Accept: application/json` so the server returns JSON instead of a redirect.
+- SSR server, CLI dev/preview, and Vite plugin now forward `Content-Type`, `Accept`, and `Referer` headers to the action handler for correct JSON/form negotiation and redirects.
+- README updated with `nixJsAction`, scoped actions, and progressive enhancement examples.
+
+## 0.10.0
+
+### Added
+
+- Node adapter: `nix-js-kit adapter node` generates a self-contained `.nix-js/node-server.mjs` that serves `dist/` static files and renders pages on demand.
+- New subpath export `@deijose/nix-js-kit/adapters/node`.
+- Custom error pages: `src/app/404.page.ts` and `src/app/500.page.ts` are rendered for 404/500 responses during SSG, SSR, and in all deployment adapters.
+- `renderErrorPage()` and `RenderErrorPageOptions` exported from `@deijose/nix-js-kit`.
+
+### Changed
+
+- CLI `adapter` command now accepts `vercel`, `netlify`, `bun`, and `node`.
+- Route scanner detects `404.page.ts` and `500.page.ts` files and adds `error404`/`error500` to `ScannedRoutes`.
+- Static build writes `dist/404.html` and `dist/500.html` when error pages are present.
+- README updated with Node adapter and error pages sections.
+
+## 0.9.0
+
+### Added
+
+- Server actions: create `page.action.ts` files next to `page.ts` and call exported functions from the client with `callAction()`.
+- New client subpath export `@deijose/nix-js-kit/action` exporting `callAction()` and `ActionRequest`.
+- Server-side action endpoint `POST /__nix-js/actions` handled by the CLI (`dev`, `preview`, `start`), the Vite plugin, and all deployment adapters (Vercel, Netlify, Bun).
+- New server exports `handleActionRequest`, `ActionResolver` and `scanActions` for custom integrations.
+- Document shell now serializes the scanned action registry into `<script id="nix-js-actions">` for client reference.
+- Island hydration markers renamed from `data-nix-island` to `data-nix-js-island`.
+
+### Changed
+
+- Route scanner detects `page.action.ts` files and adds `actionPath` to `PageRoute`.
+- README updated with a Server actions section and project conventions tree.
+
+## 0.8.1
+
+### Added
+
+- Bun adapter: `nix-js-kit adapter bun` generates `.nix-js/bun-server.ts` and `.nix-js/bun-index.ts` for running a production Bun server.
+- New subpath export `@deijose/nix-js-kit/adapters/bun`.
+
+### Changed
+
+- CLI `adapter` command now accepts `vercel`, `netlify` and `bun`.
+- README updated with Bun adapter instructions and roadmap v0.9.
+
+## 0.8.0
+
+### Added
+
+- Netlify adapter: `nix-js-kit adapter netlify` generates a Netlify Functions v2 SSR function and `netlify.toml`.
+- New subpath export `@deijose/nix-js-kit/adapters/netlify`.
+- Shared adapter helpers in `src/adapters/shared.ts` used by both Vercel and Netlify adapters.
+
+### Changed
+
+- CLI `adapter` command now accepts `vercel` and `netlify`.
+- README updated with Netlify adapter instructions and roadmap v0.8.
+
+## 0.7.0
+
+### Added
+
+- Vercel adapter: `nix-js-kit adapter vercel` generates a `.vercel/output` directory compatible with the Vercel Build Output API v3.
+- New adapter interface in `src/adapters/index.ts`.
+- New CLI command `nix-js-kit adapter <name>` (currently supports `vercel`).
+- New subpath exports `@deijose/nix-js-kit/adapters` and `@deijose/nix-js-kit/adapters/vercel`.
+
+### Changed
+
+- README updated with adapters section, CLI command list and roadmap v0.7/v0.8.
+
+## 0.6.1
+
+### Changed
+
+- Renamed Vite plugin function from `nixKit` to `nixJsKit` and the options interface from `NixKitViteOptions` to `NixJsKitViteOptions` to keep the `js` word in the public API.
+- Updated README, CHANGELOG and example import to use `nixJsKit`.
+
+## 0.6.0
+
+### Added
+
+- Official Vite plugin: `import { nixJsKit } from "@deijose/nix-js-kit/vite"`.
+- Vite plugin generates the islands entry automatically and renders pages via SSR on the Vite dev server.
+- New subpath export `@deijose/nix-js-kit/vite` for plugin usage.
+- Added `example/vite.config.ts` demonstrating the Vite plugin.
+
+### Changed
+
+- README updated with Vite plugin section and roadmap v0.6/v0.7.
+
+## 0.5.0
+
+### Added
+
+- SSR runtime: `nix-js-kit start` renders pages on demand and serves static assets from `dist/`.
+- `matchRoute` URL matcher for dynamic and catch-all routes.
+- `renderPage` shared renderer used by both SSG and SSR.
+- `createSsrServer` exported from the public API for custom Node deployments.
+
+### Changed
+
+- `src/build/build.ts` now uses the shared `renderPage` from `src/ssr/render.ts`.
+- CLI help text and README updated to include the `start` command.
+
+## 0.4.2
+
+### Added
+
+- Route groups `(marketing)` support: folders wrapped in parentheses are ignored in the URL path but can provide a shared `layout.ts`.
+- Added `example/src/app/(marketing)/` with `pricing` and `features` pages demonstrating route groups.
+
+### Fixed
+
+- Route scanner now reads `layout.ts` from inside the route group directory instead of the parent directory.
+
+## 0.4.1
+
+### Added
+
+- `nix-js-kit preview` command to serve the static build in production mode.
+- Clean URL support for static files (e.g. `/about` → `/about/index.html`).
+
+### Changed
+
+- CLI help text and README updated to include the `preview` command.
+
+## 0.4.0
+
+### Added
+
+- `generateStaticParams` export for dynamic routes (`[slug]`) and catch-all routes (`[...slug]`).
+- Dynamic routes with `generateStaticParams` are now rendered to static HTML during SSG instead of being skipped.
+- `GenerateStaticParams` type exported from the public API.
+- Added `example/src/app/blog/[slug]` demonstrating a generated blog post route.
+
+### Changed
+
+- Updated `tsconfig.json` with `paths` mapping so examples can import from `@deijose/nix-js-kit` during development and typechecking.
+
+## 0.3.1
+
+### Changed
+
+- Renamed CLI binary from `nix-kit` to `nix-js-kit` to avoid confusion with the Nix package manager.
+- Updated runtime warning prefix from `[nix-kit]` to `[nix-js-kit]`.
+
+## 0.3.0
+
+### Added
+
+- `nix-js-kit` CLI binary with `build` and `dev` commands.
+- Dev server (`nix-js-kit dev`) with rebuild-on-change for `src/app/` and `src/islands/`.
+- `--client-config` option to rebuild the client hydration bundle on each source change.
+- `run()` and `CliOptions` exported from `@deijose/nix-js-kit` for programmatic CLI usage.
+
+### Changed
+
+- `build:lib` now produces a separate SSR build for `dist/lib/cli.js` so the CLI can import user `.ts` files at runtime.
+- Added `tsx` as a runtime dependency so the CLI can load user pages and islands without extra setup.
+
+## 0.2.2
+
+### Added
+
+- `scanIslands()` — recursively scans an islands directory; each `.ts` file becomes an island named by its relative path.
+- `generateClientEntry()` / `buildEntrySource()` — generates the client hydration entry from scanned islands.
+- `build()` now accepts `islandsDir`, `generatedEntry`, and `hydrateImport`; `BuildResult` reports `islands` and `generatedEntry`.
+- Second example island (`Counter`) demonstrating multiple islands and the `visible` directive.
+
+## 0.2.1
+
+### Added
+
+- `island()` helper — marks interactive components with `data-nix-island` markers during SSG.
+- `hydrateIslands()` — client-side hydration registry with `load`, `idle`, and `visible` directives.
+- `example/src/islands/` + `example/src/entry-client.ts` demonstrating a `LikeButton` island.
+- `./island` subpath export so client bundles don't pull server-only code.
+
+## 0.2.0
+
+### Added
+
+- `scanRoutes` — file-based route scanner that maps `src/app/page.ts` to URL paths, including dynamic segments (`[slug]`, `[...slug]`).
+- `build` — SSG orchestrator that scans `src/app/`, runs loaders, composes layout chains, renders pages, and writes static HTML.
+- Example app with two pages (`/`, `/about`) sharing a root layout.
+
+## 0.1.0
+
+### Added
+
+- Initial release of `@deijose/nix-js-kit`.
+- `renderToString` for Nix.js templates using `happy-dom` as a build-time DOM (client bundle remains dependency-free).
+- `documentShell` helper to wrap rendered HTML with a full document shell and serialize loader data via `<script id="nix-js-data">`.
+- Public types: `PageProps`, `LayoutProps`, `PageDataLoad`, `LoadContext`, `RouteParams`, `ShellOptions`.
+- Proof-of-concept example under `example/` that generates `dist/index.html` from a `page.ts` + `page.data.ts` pair.
+- Vite library build configuration and TypeScript declaration generation.
+
+### Notes
+
+- `linkedom` was evaluated as a lighter DOM alternative but rejected because it does not expose `NodeFilter` in a way compatible with the Nix.js core (`template2.js` reads `NodeFilter.SHOW_ELEMENT` from `globalThis`).