vite-plugin-vanjs 0.2.2 → 0.2.4

package/AGENTS.md

@@ -0,0 +1,72 @@
+# AGENTS.md
+
+## Project Overview
+
+**vite-plugin-vanjs** is a mini meta-framework for [VanJS](https://vanjs.org/) powered by Vite. It provides file-system routing, SSR/SSG, JSX support, metadata management, and a data caching layer — all as a Vite plugin.
+
+## Architecture
+
+| Directory | Package export | Purpose |
+|-----------|---------------|---------|
+| `plugin/` | `vite-plugin-vanjs` | Core Vite plugin — route scanning, virtual modules, build/dev config |
+| `router/` | `@vanjs/router` | Router, Route, lazy, A, navigate, routerState, dataCache, matchRoute, extractParams |
+| `client/` | `@vanjs/client` | Hydration — `hydrate()` for SSR-to-client DOM reconciliation |
+| `server/` | `@vanjs/server` | `renderToString()`, preload link generation, data cache serialization |
+| `meta/` | `@vanjs/meta` | Head/Title/Meta/Link — SSR-safe document metadata |
+| `setup/` | `@vanjs/setup` | User setup file resolution |
+| `jsx/` | `@vanjs/jsx` | JSX runtime (jsx, jsxs, jsxDev) |
+
+## Key Concepts
+
+- **ESM only** — all source files are `.mjs`, types are `.d.ts`
+- **Isomorphic** — same router code runs on server and client; `isServer` (from `setup/isServer.mjs`) gates SSR vs SPA paths
+- **Reactive state** — `microStore()` (in `router/state.mjs`) creates reactive proxy objects using `van.state()` under the hood
+- **Async-first lazy()** — both server and client return `async () => ComponentModule` with `.isLazy = true`
+- **Data flow** — `route.load()` returns data → cached by `executeLifecycle()` in `dataCache` → read via `useRouteData()`
+- **Cache key** — `""` for empty params, `JSON.stringify(params)` otherwise
+- **No `DynamicModule`** — replaced by `LazyComponent = Promise<{ default?, Page?, route? }>`
+- **`routerState._oldVal`** — non-reactive reads via `rawVal` property (cross-env: writable on client, getter fallback on server). Used to avoid re-triggering derivations
+- **Single Router instance** — `Router()` setup reads via `_oldVal`; only internal `van.derive()` subscribes to `pathname` + `searchParams`
+- **Stale navigation guard** — `navToken` counter re-checked after `executeLifecycle()` before any DOM mutation
+- **Layout chain diffing** — `buildChain()` uses prefix-diff on layout paths to reuse shared layouts across sibling pages; `outlet` swapped on leaf-only changes
+- **JSX Fragment flattening** — `buildChain()` and `resolveChildren()` call `.flat()` on results because JSX Fragments return nested arrays
+- **Live-target hydration** — real DOM adopted after initial render; navigations mutate the live root, not the detached render wrapper
+
+## Commands
+
+```sh
+pnpm test          # Run vitest (watch mode)
+pnpm test -- --run # Run vitest once
+pnpm lint          # deno lint + tsc -noEmit
+pnpm format        # deno fmt
+pnpm check:ts      # tsc -noEmit only
+```
+
+## Testing
+
+- **Framework**: Vitest 4 with `@vitest/browser` and `happy-dom`
+- **Environments**: `client.test.ts` uses `happy-dom`, `server.test.ts` uses `@vitest-environment node`
+- **Config**: `vitest.config.ts` — routes dir is `tests/routes`
+- **Coverage**: Istanbul, enabled by default, covers `plugin/`, `router/`, `setup/`, `client/`, `server/`, `meta/`, `jsx/`
+- **Test files**: `tests/client.test.ts`, `tests/client.test.tsx`, `tests/server.test.ts`, `tests/server.test.tsx`, `tests/dataCache.test.ts`, `tests/state.test.ts`, `tests/router.helpers.test.ts`, `tests/router.hydration.test.ts`, `tests/router.spa.test.ts`, `tests/router.search.test.ts`, `tests/router.template-pattern.test.ts`, `tests/hydration-diff.test.ts`, `tests/setup.test.ts`
+- **Coverage**: 100% statements / branches / functions / lines for all covered directories
+
+## Code Style
+
+- **No comments** unless explicitly requested
+- **No semicolons** at line ends (deno fmt default)
+- **JSDoc** on public APIs only — `@typedef` references `./types.d.ts`
+- **Formatting**: `deno fmt` handles all formatting — don't fight it
+- **Linting**: `deno lint` — fix with `pnpm fix:ts`
+
+## Type Definitions
+
+- `router/global.d.ts` — module declaration for `@vanjs/router` (augments `"@vanjs/router"`)
+- `router/types.d.ts` — standalone type exports (references `global.d.ts`)
+- Each package directory has its own `types.d.ts`
+- **Keep them in sync** — when changing exports, update both `global.d.ts` and `types.d.ts`
+
+## Common Pitfalls
+
+- `microStore()` skips proxying for empty plain objects (`{}`) — they're assigned directly, so `Object.assign` on `routerState.params` works but changes aren't reactive
+- `lazy()` is **not** synchronous on the client anymore — always `await route.component()`

package/client/global.d.ts

@@ -58,4 +58,17 @@ declare module "@vanjs/client" {
       | JSX.Element
       | Promise<ChildElement | ChildElement[] | JSX.Element>,
   ) => T;
+
+  /**
+   * Shallow compare two elements, optionally recursing into keyed children.
+   *
+   * @param el1 the server rendered element
+   * @param el2 the client rendered element or elements
+   * @param deep when true, compares the hydrated children of both elements
+   */
+  export const elementsMatch = (
+    el1: HTMLElement,
+    el2: HTMLElement | HTMLElement[],
+    deep?: boolean,
+  ) => boolean;
 }

package/client/index.mjs

@@ -141,37 +141,99 @@ export function elementsMatch(el1, el2, deep) {
 }
 
 function createHydrationContext() {
-  /** @type {WeakMap<Element, Element>} */
-  const parentCache = new WeakMap();
+  /**
+   * Significant child nodes: elements + non-empty text.
+   * SSR omits empty text nodes while the client creates Text("") for
+   * empty bindings, so those are filtered out on both sides.
+   * @param {Element} el
+   * @returns {ChildNode[]}
+   */
+  const significantChildren = (el) =>
+    Array.from(el.childNodes).filter((n) =>
+      n.nodeType !== 3 || n.textContent !== ""
+    );
 
-  /** @type {(element: HTMLElement, root: HTMLElement) => HTMLElement | null} */
-  function getParent(element, root) {
-    const cacheKey = element;
-    // istanbul ignore if - must be connected to a read DOM
-    if (parentCache.has(cacheKey)) {
-      const cached = parentCache.get(cacheKey);
-      // Verify the cached parent is still valid for this root
-      if (cached && cached.isConnected && root.contains(cached)) {
-        return cached;
-      }
-      // If not valid, remove from cache
-      parentCache.delete(cacheKey);
-    }
+  /**
+   * Whether an element carries a hydration key
+   * @param {Node} el
+   * @returns {el is Element}
+   */
+  const isKeyed = (el) => el instanceof Element && el.hasAttribute("data-hk");
 
-    const chain = [];
-    let current = element;
+  /**
+   * Consume hydration keys under a freshly hydrated root: adoption is done,
+   * subsequent renders are born keyless, so keys must not linger.
+   * @param {Element} root
+   */
+  function stripHydrationKeys(root) {
+    // istanbul ignore if - the diffed root is always an Element
+    if (!(root instanceof Element)) return;
+    if (root.hasAttribute("data-hk")) root.removeAttribute("data-hk");
+    root.querySelectorAll("[data-hk]").forEach((el) =>
+      el.removeAttribute("data-hk")
+    );
+  }
 
-    while (current !== root && current) {
-      chain.push(current);
-      current = current.parentElement;
+  /**
+   * Whether two nodes can pair up: same kind, same tag/id/class, same text.
+   * className is coerced to String so SVG (SVGAnimatedString) pairs by tag+id.
+   * @param {ChildNode} oldN
+   * @param {ChildNode} newN
+   * @returns {boolean}
+   */
+  function nodesPairable(oldN, newN) {
+    if (oldN.nodeType === 3 || newN.nodeType === 3) {
+      return oldN.nodeType === newN.nodeType &&
+        oldN.textContent === newN.textContent;
+    }
+    if (oldN.nodeType === 8 || newN.nodeType === 8) {
+      return oldN.nodeType === newN.nodeType &&
+        oldN.textContent === newN.textContent;
     }
+    if (!(oldN instanceof Element) || !(newN instanceof Element)) {
+      return false;
+    }
+    return oldN.tagName === newN.tagName &&
+      (oldN.id || "") === (newN.id || "") &&
+      String(oldN.className || "") === String(newN.className || "");
+  }
 
-    const parent = chain.slice(-1)[0];
-    // istanbul ignore else
-    if (parent) {
-      parentCache.set(cacheKey, parent);
+  /**
+   * Adopt a node pair. Keyed SSR elements are replaced with their fresh
+   * client render (keys follow the client gate); static subtrees are walked
+   * so untouched nodes (e.g. images) are never re-instantiated. Text nodes
+   * are swapped for identical client ones so van bindings stay live.
+   * @param {ChildNode} oldNode
+   * @param {ChildNode} newNode
+   */
+  function adoptNode(oldNode, newNode) {
+    if (isKeyed(oldNode)) {
+      // istanbul ignore else - pairable nodes always share the same tag
+      if (newNode instanceof Element && oldNode.tagName === newNode.tagName) {
+        oldNode.replaceWith(newNode);
+      }
+      // else: no trustworthy counterpart — leave the SSR node in place
+      return;
+    }
+    if (!(oldNode instanceof Element) || !(newNode instanceof Element)) return;
+    const oldSiblings = significantChildren(oldNode);
+    const newSiblings = significantChildren(newNode);
+    if (
+      oldSiblings.length !== newSiblings.length ||
+      !oldSiblings.every((ok, i) => nodesPairable(ok, newSiblings[i]))
+    ) {
+      // structural divergence — swap the whole subtree with the fresh client render
+      oldNode.replaceWith(newNode);
+      return;
     }
-    return parent;
+    oldSiblings.forEach((os, i) => {
+      const ns = newSiblings[i];
+      if (os.nodeType === 3) {
+        os.replaceWith(ns);
+      } else {
+        adoptNode(os, ns);
+      }
+    });
   }
 
   /** @type {(oldDom: HTMLElement, newDom: HTMLElement | HTMLElement[]) => HTMLElement} */
@@ -180,47 +242,38 @@ function createHydrationContext() {
     // SPA mode
     // istanbul ignore else
     if (!oldDom.children.length && !elementsMatch(oldDom, newDom)) {
-      return oldDom.replaceChildren(...unwrap(newDom).children);
+      oldDom.replaceChildren(...unwrap(newDom).children);
+      stripHydrationKeys(oldDom);
+      return;
     }
     // istanbul ignore else
     if (newDom instanceof Array) {
       oldDom.replaceChildren(...unwrap(newDom).children);
+      stripHydrationKeys(oldDom);
       return;
     }
 
-    // SSR Mode
-    /** @type {Set<HTMLElement>} */
-    const oldSet = new Set();
-    /** @type {Set<HTMLElement>} */
-    const newSet = new Set();
-
-    const processElements = (root, set) => {
-      const elements = root.querySelectorAll("[data-hk]");
-      let lastParent = null;
-
-      elements.forEach((el) => {
-        const parent = getParent(el, root);
-        if (parent && parent !== lastParent) {
-          set.add(parent);
-          lastParent = parent;
-        }
-      });
-    };
-
-    processElements(oldDom, oldSet);
-    processElements(newDom, newSet);
-
-    // istanbul ignore else
-    if (newSet.size > 0) {
-      const newArray = Array.from(newSet);
-      oldSet.forEach((el) => {
-        const match = newArray.find((m) => elementsMatch(m, el));
-        // istanbul ignore else
-        if (match) {
-          el.replaceWith(match);
-        }
-      });
+    // SSR mode: adopt keyed elements 1:1 with fresh client renders,
+    // leave static subtrees untouched
+    const oldSiblings = significantChildren(oldDom);
+    const newSiblings = significantChildren(newDom);
+    if (
+      oldSiblings.length !== newSiblings.length ||
+      !oldSiblings.every((ok, i) => nodesPairable(ok, newSiblings[i]))
+    ) {
+      oldDom.replaceChildren(...newSiblings);
+      stripHydrationKeys(oldDom);
+      return;
     }
+    oldSiblings.forEach((ok, i) => {
+      const nk = newSiblings[i];
+      if (ok.nodeType === 3) {
+        ok.replaceWith(nk);
+      } else {
+        adoptNode(ok, nk);
+      }
+    });
+    stripHydrationKeys(oldDom);
   }
 
   return { diffAndHydrate };

package/client/types.d.ts

@@ -52,3 +52,16 @@ export const hydrate: <T = HTMLElement>(
     | JSX.Element
     | Promise<HTMLElement | HTMLElement[] | JSX.Element>,
 ) => T;
+
+/**
+ * Shallow compare two elements, optionally recursing into keyed children.
+ *
+ * @param el1 the server rendered element
+ * @param el2 the client rendered element or elements
+ * @param deep when true, compares the hydrated children of both elements
+ */
+export const elementsMatch: (
+  el1: HTMLElement,
+  el2: HTMLElement | HTMLElement[],
+  deep?: boolean,
+) => boolean;

package/llms.txt

@@ -0,0 +1,55 @@
+# vite-plugin-vanjs
+
+An async-first mini meta-framework for VanJS powered by Vite. Provides file-system routing, SSR/SSG, JSX support, metadata management, and a data caching layer — all as a Vite plugin.
+
+## Packages
+
+- `vite-plugin-vanjs` — Core Vite plugin: route scanning, virtual modules, build/dev config
+- `@vanjs/router` — Router, Route, lazy, A, navigate, routerState, dataCache, matchRoute, extractParams
+- `@vanjs/client` — Hydration: `hydrate()` for SSR-to-client DOM reconciliation
+- `@vanjs/server` — `renderToString()`, preload link generation, data cache serialization
+- `@vanjs/meta` — Head/Title/Meta/Link: SSR-safe document metadata
+- `@vanjs/setup` — Isomorphic VanJS setup, `needsHydration`, `markHydrationComplete`
+- `@vanjs/jsx` — JSX runtime (jsx, jsxs, jsxDev) with automatic namespace resolution
+
+## Key Concepts
+
+- ESM only — all source `.mjs`, types `.d.ts`
+- Isomorphic — `isServer` gates SSR vs SPA paths
+- Reactive state — `microStore()` creates reactive proxy objects via `van.state()`
+- `routerState._oldVal` — non-reactive reads via `rawVal` to avoid re-triggering derivations
+- Single Router instance — only internal `van.derive()` subscribes to pathname + searchParams
+- Stale navigation guard — `navToken` counter re-checked after lifecycle before DOM mutation
+- Layout chain diffing — prefix-diff on layout paths to reuse shared layouts across sibling pages
+- JSX Fragment flattening — `.flat()` on layout/leaf results because Fragments return nested arrays
+- Live-target hydration — navigations mutate the adopted SSR root, not the detached render wrapper
+- Server one-shot render — no shared loading flag, concurrent requests don't interfere
+
+## Commands
+
+```
+pnpm test -- --run   # Run vitest once
+pnpm lint            # deno lint + tsc -noEmit
+pnpm format          # deno fmt
+pnpm check:ts        # tsc -noEmit only
+```
+
+## Code Style
+
+- No comments unless explicitly requested
+- No semicolons (deno fmt)
+- JSDoc on public APIs only
+- deno fmt + deno lint
+
+## Source Layout
+
+```
+plugin/         Core Vite plugin
+router/         Router, state, helpers, lazy, dataCache, matchRoute, unwrap
+client/         Hydration (hydrate, elementsMatch, setAttribute)
+server/         renderToString, data cache serialization
+meta/           Head/Title/Meta/Link
+setup/          Isomorphic VanJS setup (van.mjs, van-ssr.mjs, helpers.mjs)
+jsx/            JSX runtime (jsx, Fragment, ns)
+tests/          Vitest tests (76 tests, 100% coverage)
+```

package/meta/tags.mjs

@@ -2,7 +2,10 @@ import van from "vanjs-core";
 import { addMeta } from "./Head.mjs";
 
 /** @typedef {import("./types.d.ts").SupportedTags} SupportedTags */
-/** @typedef {import("vanjs-core").PropsWithKnownKeys<T = SupportedTags>} PropsWithKnownKeys<T> */
+/**
+ * @template T
+ * @typedef {import("vanjs-core").PropsWithKnownKeys<T>} PropsWithKnownKeys
+ */
 /** @typedef {import("./types.d.ts").TagProps} TagProps */
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-vanjs",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "author": "thednp",
   "license": "MIT",
   "description": "An async first mini meta-framework for VanJS powered by Vite",
@@ -27,6 +27,8 @@
     "jsx-runtime.d.ts",
     "jsx-dev-runtime.d.ts",
     "README.md",
+    "AGENTS.md",
+    "llms.txt",
     "LICENSE"
   ],
   "keywords": [
@@ -91,7 +93,7 @@
     "vanjs-ext": "^0.6.3"
   },
   "devDependencies": {
-    "@types/node": "^26.5.1",
+    "@types/node": "^26.6.1",
     "@vitest/browser": "^5.0.1",
     "@vitest/coverage-istanbul": "^5.0.1",
     "@vitest/ui": "^5.0.1",

package/plugin/index.mjs

@@ -1,12 +1,11 @@
-/** @typedef {typeof import("./types").VitePluginVanJS} VitePluginVanJS */
-/** @typedef {import("./types").VanJSPluginOptions} VanJSPluginOptions */
 /** @typedef {import("vite").ResolvedConfig} ResolvedConfig */
-/** @typedef {import("./types").PageFile} PageFile */
-/** @typedef {import("./types").RouteFile} RouteFile */
 /** @typedef {import("vite").BuildAppHook} BuildAppHook */
 /** @typedef {import("vite").TransformResult} TransformResult */
 /** @typedef {import("vite").Plugin} Plugin */
-/** @typedef {ThisParameterType<BuildAppHook>} PluginContext */
+/** @typedef {import("./types.d.ts").VitePluginVan} VitePluginVan */
+/** @typedef {import("./types.d.ts").VanJSPluginOptions} VanJSPluginOptions */
+/** @typedef {import("./types.d.ts").PageFile} PageFile */
+/** @typedef {import("./types.d.ts").RouteFile} RouteFile */
 
 import { fileURLToPath } from "node:url";
 import { dirname, join, resolve } from "node:path";
@@ -56,7 +55,7 @@ const debugModuleAliases = {
   "@vanjs/setup": "../setup/index-debug",
 };
 
-/** @type {VitePluginVanJS} */
+/** @type {VitePluginVan} */
 export default function VitePluginVanJS(options = {}) {
   const pluginConfig = { ...pluginDefaults, ...options };
   const { routesDir } = pluginConfig;

package/plugin/types.d.ts

@@ -1,21 +1,29 @@
 // plugin/types.ts
+import type { Plugin } from "vite";
 export * from "../jsx/types.d.ts";
 export * from "../setup/types.d.ts";
 export * from "../router/types.d.ts";
 export * from "../meta/types.d.ts";
 export * from "../server/types.d.ts";
 export * from "../client/types.d.ts";
-import type { Plugin } from "vite";
 
 export type VanJSPluginOptions = {
   routesDir?: string;
   extensions?: string[];
-  excludeRoutes?: string[]; // NEW — excluded in all envs
-  excludeRoutesProd?: string[]; // NEW — excluded in production only
+  excludeRoutes?: string[]; // excluded in all envs
+  excludeRoutesProd?: string[]; // excluded in production only
+};
+
+/**
+ * The plugin context members the plugin reads from `this`.
+ */
+export type VitePluginContext = {
+  meta?: { viteVersion?: string };
 };
 
-const VitePluginVanJS: (
+export type VitePluginVan = (
   config?: VanJSPluginOptions,
-) => Plugin<VanJSPluginOptions>;
+) => Plugin;
 
+declare const VitePluginVanJS: VitePluginVan;
 export default VitePluginVanJS;

package/router/global.d.ts

@@ -266,6 +266,7 @@ declare module "@vanjs/router" {
   export type LazyComponent = Promise<{
     default?: ComponentFn;
     Page?: ComponentFn;
+    component?: ComponentFn;
     route?: Pick<RouteEntry, "load" | "preload">;
     layouts?: RouteLayout[];
     leaf?: ComponentFn;
@@ -334,6 +335,14 @@ declare module "@vanjs/router" {
    */
   export const matchRoute: (path: string) => RouteEntry | null;
 
+  /**
+   * Extract the route params from a route pattern and a path
+   */
+  export const extractParams: (
+    pattern: string,
+    path: string,
+  ) => Record<string, string> | null;
+
   /**  * Convenience hook to get the current route's cached data.
    */
   export const useRouteData: <T>() => T | undefined;

package/router/helpers.mjs

@@ -9,8 +9,7 @@ import { Head } from "../meta/index.mjs";
 import * as dataCache from "./dataCache.mjs";
 
 /** @typedef {typeof import("./types.d.ts").navigate} Navigate */
-/** @typedef {import("./types.d.ts").SearchParamDef} SearchParamDef */
-/** @typedef {import("./types.d.ts").Route} Route */
+/** @typedef {import("./types.d.ts").RouteEntry} RouteEntry */
 /** @typedef {import("./types.d.ts").VanNode} VanNode */
 /** @typedef {import("./types.d.ts").ComponentModule} ComponentModule */
 /** @typedef {import("./types.d.ts").ComponentFn} ComponentFn */

package/router/lazy.mjs

@@ -2,7 +2,6 @@
 import { cacheRoute, getCachedRoute } from "./routeCache.mjs";
 
 /** @typedef {import('./types').VanNode} VanNode */
-/** @typedef {import('./types').DynamicModule} DynamicModule */
 /** @typedef {import('./types').ComponentModule} ComponentModule */
 /** @typedef {import('./types').ComponentFn} ComponentFn */
 

package/router/routeCache.mjs

@@ -1,7 +1,7 @@
 /** @typedef {import("./types").ComponentModule} ComponentModule */
 /** @typedef {import("./types").ImportFn} ImportFn */
-/** @typedef {typeof import("./types").getCached} GetCachedRoute */
-/** @typedef {typeof import("./types").cache} CacheRoute */
+/** @typedef {typeof import("./types").getCachedRoute} GetCachedRoute */
+/** @typedef {typeof import("./types").cacheRoute} CacheRoute */
 
 /** @type {Map<ImportFn, ComponentModule>} */
 const routeCache = new Map();

package/router/router.mjs

@@ -10,6 +10,7 @@ import {
 } from "./helpers.mjs";
 import { initializeHeadTags } from "../meta/index.mjs";
 import { hydrate } from "../client/index.mjs";
+import { markHydrationComplete } from "../setup/helpers.mjs";
 import { Head } from "../meta/index.mjs";
 import * as dataCache from "./dataCache.mjs";
 import "virtual:@vanjs/routes";
@@ -132,9 +133,16 @@ export const Router = (initialProps = /* istanbul ignore next */ {}) => {
   let initialized = false;
 
   // Client-side: hydrate data cache from SSR output
-  // This must happen BEFORE any component renders so useRouteData() works
-  // Skip in dev mode: we manually clear dataCache on mutations for instant updates
-  if (globalThis.__DATA_CACHE && !isDev) {
+  // This must happen BEFORE any component renders so useRouteData() works.
+  // Skip in dev mode for /admin pages: we manually clear dataCache on
+  // mutations for instant updates. Public pages reuse SSR data like prod.
+  // NOTE: read via _oldVal — subscribing here would re-create the whole
+  // Router on every navigation.
+  if (
+    globalThis.__DATA_CACHE &&
+    /* istanbul ignore next -- build-time constant, isDev is false in vitest */
+    (!isDev || !routerState._oldVal.pathname.startsWith("/admin"))
+  ) {
     dataCache.hydrateFromJSON(globalThis.__DATA_CACHE);
   }
 
@@ -243,6 +251,9 @@ export const Router = (initialProps = /* istanbul ignore next */ {}) => {
       // not the detached wrapper used for the initial render.
       liveTarget = root;
       initialized = true;
+      // Initial hydration is done: freshly rendered client nodes are born
+      // into live DOM and need no hydration keys from here on.
+      markHydrationComplete();
       return result;
     };
   }

package/router/types.d.ts

@@ -227,6 +227,7 @@ export type ComponentModule = {
 export type LazyComponent = Promise<{
   default?: ComponentFn;
   Page?: ComponentFn;
+  component?: ComponentFn;
   route?: Pick<RouteEntry, "load" | "preload">;
   layouts?: RouteLayout[];
   leaf?: ComponentFn;

package/server/types.d.ts

@@ -97,7 +97,7 @@ export const processLayoutRoutes: (
   routes: Array<PageFile>,
   config: ResolvedConfig,
   pluginConfig: PluginConfig,
-) => Array<PRouteFile>;
+) => Array<RouteFile>;
 
 /**
  * Scan and process layouts and return them.

package/setup/helpers.mjs

@@ -1,7 +1,31 @@
+/**
+ * Once initial hydration completes, freshly rendered client nodes are born
+ * into live DOM that is never diffed again, so they need no hydration keys.
+ * Server bundles get their own module instance where this stays false.
+ */
+let hydrationComplete = false;
+
+/** @type {() => void} */
+export function markHydrationComplete() {
+  hydrationComplete = true;
+}
+
+/** @type {() => void} */
+export function resetHydrationState() {
+  hydrationComplete = false;
+}
+
 /** @type {(props: Record<string, unknown>) => boolean} */
 export function needsHydration(props) {
+  if (hydrationComplete) return false;
   return props && (
     Object.keys(props).some((k) => k.startsWith("on")) || // has events
-    Object.values(props).some((v) => v && typeof v === "object" && "val" in v) // has state
+    Object.entries(props).some(([k, v]) =>
+      v && typeof v === "object" && (
+        "val" in v || k === "style" && Object.values(v).some((sv) =>
+            sv && typeof sv === "object" && "val" in sv
+          )
+      )
+    ) // has state
   );
 }