@llui/vike 0.4.10 → 0.5.0

package/dist/on-render-client.js

@@ -1,13 +1,12 @@
-import { hydrateApp, mountApp, mountAtAnchor, hydrateAtAnchor } from '@llui/dom';
+import { mountSignalComponent, hydrateSignalApp } from '@llui/dom';
 import { _consumePendingSlot, _resetPendingSlot } from './page-slot.js';
 // Re-exported so `@llui/vike/client` is a one-stop-shop for everything
-// a pages/+onRenderClient.ts / +Layout.ts file needs.
+// a pages/+onRenderClient.ts / Layout.ts file needs.
 export { pageSlot } from './page-slot.js';
 /**
  * Resolves the layout chain for a given pageContext. A single layout
  * becomes a one-element chain; a function resolver gives callers full
- * control to return different chains for different routes (e.g. nested
- * layouts keyed on Vike's `pageContext.urlPathname`).
+ * control to return different chains for different routes.
  */
 function resolveLayoutChain(layoutOption, pageContext) {
     if (!layoutOption)
@@ -19,11 +18,14 @@ function resolveLayoutChain(layoutOption, pageContext) {
         return layoutOption;
     return [layoutOption];
 }
+/** Resolve a layer's seed state — a present data slice IS the seed state
+ * (signal init() takes no data); an absent slice falls back to init(). */
+function seedFor(data) {
+    return data === undefined ? undefined : data;
+}
 /**
- * Adapt a `TransitionOptions` object (e.g. the output of
- * `routeTransition()` from `@llui/transitions`, or a preset like `fade`
- * / `slide`) into the `onLeave` / `onEnter` pair expected by
- * `createOnRenderClient`.
+ * Adapt a `TransitionOptions` object into the `onLeave` / `onEnter` pair
+ * expected by `createOnRenderClient`.
  *
  * ```ts
  * import { createOnRenderClient, fromTransition } from '@llui/vike/client'
@@ -36,9 +38,8 @@ function resolveLayoutChain(layoutOption, pageContext) {
  * ```
  *
  * The transition operates on the slot element — in a no-layout setup,
- * the root container; in a layout setup, the innermost surviving
- * layer's `pageSlot()` element. Opacity / transform fades apply to the
- * outgoing page content, then the new page fades in.
+ * the root container; in a layout setup, the innermost surviving layer's
+ * `pageSlot()` element.
  */
 export function fromTransition(t) {
     return {
@@ -58,33 +59,21 @@ export function fromTransition(t) {
     };
 }
 /**
- * Live chain of mounted layers — module-level singleton.
- *
- * Vike runs one client-side adapter per browser tab. Within one tab,
- * a single `chainHandles` array holds the AppHandle for every active
- * layer, indexed `[outermostLayout, ..., innerLayout, page]`. The
- * array mutates in place across navigations: shared layout layers
- * stay live, divergent suffix layers dispose, new layers append.
+ * Live chain of mounted layers — module-level singleton. Vike runs one
+ * client-side adapter per browser tab; within one tab a single
+ * `chainHandles` array holds the handle for every active layer, indexed
+ * `[outermostLayout, ..., innerLayout, page]`. It mutates in place across
+ * navigations: shared layout layers stay live, divergent suffix layers
+ * dispose, new layers append.
  *
- * **Module-level scope is correct for the browser**, where the
- * adapter has exactly one consumer per page load. It would be
- * INCORRECT in a long-running multi-tenant Node SSR worker that
- * imports `@llui/vike/client` and tries to render multiple requests
- * concurrently — every request would clobber the same array. That
- * usage isn't supported today (the client adapter assumes a browser
- * runtime; the SSR side lives in `@llui/vike/server`'s `_renderChain`
- * which keeps state per-call), but the constraint should be made
- * explicit if the adapter ever grows a Node SSR consumer. If you're
- * here to add such a consumer: convert `chainHandles` and the
- * pending-slot register to per-call locals threaded through the
- * adapter API instead of module state, and audit `getLayoutChain`
- * and `_resetChainForTest` for the same change.
+ * Module-level scope is correct for the browser (one consumer per page
+ * load); a multi-tenant Node SSR worker importing the client adapter
+ * would clobber it — that usage isn't supported.
  */
 let chainHandles = [];
 /**
- * @internal — test helper. Disposes every layer in the current chain
- * and clears the module state so subsequent calls behave as a first
- * mount. Not part of the public API; subject to change without notice.
+ * @internal — test helper. Disposes every layer in the current chain and
+ * clears the module state so subsequent calls behave as a first mount.
  */
 export function _resetChainForTest() {
     // Dispose innermost-first to match the normal teardown path.
@@ -104,38 +93,19 @@ export function _resetCurrentHandleForTest() {
 }
 /**
  * Default onRenderClient hook — no layout, no animation hooks. Hydrates
- * on first load, mounts fresh on subsequent navs. Use `createOnRenderClient`
- * for the customizable factory form.
+ * on first load, mounts fresh on subsequent navs.
  */
 export async function onRenderClient(pageContext) {
     await renderClient(pageContext, {});
 }
 /**
- * Factory to create a customized onRenderClient hook. See `RenderClientOptions`
- * for the full option surface — this is the entry point for persistent
- * layouts, route transitions, and lifecycle hooks.
+ * Factory to create a customized onRenderClient hook. See
+ * `RenderClientOptions` for the full option surface.
  *
  * **Do not name your layout file `+Layout.ts`.** Vike reserves the `+`
- * prefix for its own framework config conventions, and `+Layout.ts` is
- * interpreted by `vike-react` / `vike-vue` / `vike-solid` framework
- * adapters as a native layout config. `@llui/vike` isn't a framework
- * adapter in that sense — it's a render adapter, and `createOnRenderClient`
- * consumes the layout component directly via the `Layout` option. Name
- * the file `Layout.ts`, `app-layout.ts`, or anywhere outside `/pages`
- * that Vike won't scan, and import it here by path.
- *
- * ```ts
- * // pages/+onRenderClient.ts
- * import { createOnRenderClient, fromTransition } from '@llui/vike/client'
- * import { routeTransition } from '@llui/transitions'
- * import { AppLayout } from './Layout.js' // ← NOT './+Layout'
- *
- * export const onRenderClient = createOnRenderClient({
- *   Layout: AppLayout,
- *   ...fromTransition(routeTransition({ duration: 200 })),
- *   onMount: () => console.log('page rendered'),
- * })
- * ```
+ * prefix for its own framework config conventions. Name the file
+ * `Layout.ts`, `app-layout.ts`, or anywhere outside `/pages` that Vike
+ * won't scan, and import it here by path.
  */
 export function createOnRenderClient(options) {
     return (pageContext) => renderClient(pageContext, options);
@@ -147,16 +117,14 @@ async function renderClient(pageContext, options) {
         throw new Error(`@llui/vike: container "${selector}" not found in DOM`);
     }
     const rootEl = container;
-    // Resolve the chain for this render. The page component is always
-    // the innermost entry, regardless of layout configuration.
+    // Resolve the chain for this render. The page is always the innermost entry.
     const layoutChain = resolveLayoutChain(options.Layout, pageContext);
     const layoutData = pageContext.lluiLayoutData ?? [];
     const newChain = [...layoutChain, pageContext.Page];
     const newChainData = [...layoutData, pageContext.data];
     if (pageContext.isHydration) {
-        // First load — the chain starts empty and we hydrate every layer
-        // against server-rendered HTML. No onLeave/onEnter on hydration.
-        await mountOrHydrateChain(newChain, newChainData, rootEl, {
+        // First load — hydrate every layer against server-rendered HTML.
+        mountChainSuffix(newChain, newChainData, 0, rootEl, undefined, {
             mode: 'hydrate',
             serverStateEnvelope: window.__LLUI_STATE__,
             runInitEffectsOnHydrate: options.runInitEffectsOnHydrate,
@@ -166,53 +134,22 @@ async function renderClient(pageContext, options) {
     }
     // Subsequent nav — diff the layout chain to find the divergent suffix.
     //
-    // The page (innermost entry, always stored at chainHandles[length-1])
-    // is NEVER considered a surviving layer: every client navigation
-    // disposes the current page and mounts fresh, even when the incoming
-    // `pageContext.Page` happens to resolve to the same `ComponentDef`
-    // reference as the outgoing one.
-    //
-    // Rationale: the persistent-layout feature is about keeping app
-    // *chrome* alive across navigation — headers, sidebars, focus traps,
-    // session state. The page, by definition, is the thing that changes
-    // per route. Content-driven sites routinely share one `ComponentDef`
-    // across many routes (e.g. a docs site where every `+Page.ts`
-    // re-exports the same `DocPage` and per-route `+data.ts` supplies
-    // the content). Treating same-def page navs as no-ops would freeze
-    // those sites visually while the URL advances — a regression that
-    // shipped in 0.0.26 and was reported against the llui.dev site.
-    //
-    // The user-supplied `onLayerDataChange` callback fires for *layouts*
-    // that want to react to nav-scoped data (pathname, session,
-    // breadcrumbs) without remounting — see the loop below. The page is
-    // deliberately excluded from that path because `init(data)` always
-    // re-runs for it.
+    // The page (innermost entry) is NEVER a surviving layer: every client
+    // navigation disposes the current page and mounts fresh, even when the
+    // incoming Page resolves to the same def reference. The persistent-layout
+    // feature is about keeping app chrome alive; the page is the thing that
+    // changes per route.
     let firstMismatch = 0;
-    // `chainHandles` stores `[...layouts, page]`, so the layout prefix
-    // length is `chainHandles.length - 1` (or 0 on first fresh mount, when
-    // the chain is still empty). Bounding `minLen` by this length keeps
-    // `firstMismatch` from ever advancing into the page slot.
     const prevLayoutLen = chainHandles.length === 0 ? 0 : chainHandles.length - 1;
     const minLen = Math.min(prevLayoutLen, layoutChain.length);
     while (firstMismatch < minLen && chainHandles[firstMismatch].def === newChain[firstMismatch]) {
         firstMismatch++;
     }
-    // Push fresh data into surviving layers (layers in the shared prefix).
-    // Without this, persistent layouts can't react to nav-driven data
-    // changes — pathname, breadcrumbs, session, nav-highlight state all
-    // belong to the layout but change on every client navigation.
-    //
-    // The user-supplied `onLayerDataChange` callback receives the layer
-    // def, its AppHandle, the new data slice, and the previously-seen
-    // data slice. The user typically dispatches a state-update message
-    // through `handle.send`. Layers whose data slice is unchanged
-    // (shallow-key Object.is on records, whole-value Object.is for
-    // primitives) are skipped without calling the hook.
-    //
-    // This loop is layouts-only by construction: `firstMismatch` is
-    // bounded by `layoutChain.length` above, so indices [0, firstMismatch)
-    // never reach the page slot. If `onLayerDataChange` is undefined,
-    // surviving layers retain their existing state — opt-in.
+    // Push fresh data into surviving layers (the shared prefix). The
+    // user-supplied `onLayerDataChange` receives the layer def, its handle,
+    // and the new + previous data slices; it typically dispatches a message
+    // through `handle.send`. Unchanged slices are skipped. Layouts-only by
+    // construction (firstMismatch is bounded by layoutChain.length).
     for (let i = 0; i < firstMismatch; i++) {
         const entry = chainHandles[i];
         const newData = newChainData[i];
@@ -221,23 +158,14 @@ async function renderClient(pageContext, options) {
         const prevData = entry.data;
         entry.data = newData;
         if (options.onLayerDataChange) {
-            options.onLayerDataChange({
-                def: entry.def,
-                handle: entry.handle,
-                newData,
-                prevData,
-            });
+            options.onLayerDataChange({ def: entry.def, handle: entry.handle, newData, prevData });
         }
     }
-    // Determine whether this nav replaces the entire root or only a suffix.
-    // For the root swap, the outermost layer mounts/hydrates via mountApp/
-    // hydrateApp on rootEl. For a deeper swap, the mount target is an
-    // anchor comment owned by the surviving layer's slot. `firstMismatch
-    // === 0` covers two cases: no layouts configured (page-only chain,
-    // every nav is a root swap) and all layouts diverging (full re-render).
+    // `firstMismatch === 0` means a root swap (no layouts, or all diverging);
+    // otherwise the surviving layer at firstMismatch-1 owns the slot we mount into.
     const isRootSwap = firstMismatch === 0;
-    // onLeave runs BEFORE any teardown. Outgoing DOM still mounted here.
-    // Skip on the very first mount — there's no outgoing page to leave.
+    // onLeave runs BEFORE any teardown — outgoing DOM still mounted. Skip on the
+    // very first mount (no outgoing page to leave).
     const isFirstMount = chainHandles.length === 0;
     if (options.onLeave && !isFirstMount) {
         const leaveTargetEl = isRootSwap
@@ -245,23 +173,20 @@ async function renderClient(pageContext, options) {
             : (chainHandles[firstMismatch - 1].slotAnchor?.parentElement ?? rootEl);
         await options.onLeave(leaveTargetEl);
     }
-    // Dispose the divergent suffix, innermost first. Each handle.dispose()
-    // calls disposeLifetime on that layer's rootLifetime, which cascades through
-    // every child scope the layer owned (bindings, portals, onMount
-    // cleanups, dialog focus traps, etc.). The surviving layers are
-    // untouched because their scopes live above the disposal roots.
-    // For anchor-based mounts, dispose() also removes the owned DOM region
-    // between the anchor and end sentinel — no additional textContent clear needed.
+    // Dispose the divergent suffix, innermost first. Each handle.dispose() runs
+    // the layer's teardowns; anchor-mounted layers also remove their owned DOM
+    // region (anchor → end sentinel). For a root swap the container is cleared
+    // explicitly below since a container mount's dispose doesn't remove DOM.
     for (let i = chainHandles.length - 1; i >= firstMismatch; i--) {
         chainHandles[i].handle.dispose();
     }
     chainHandles = chainHandles.slice(0, firstMismatch);
+    if (isRootSwap && !isFirstMount)
+        rootEl.replaceChildren();
     // Mount the new suffix starting at firstMismatch.
-    // For a root swap, the target is the container HTMLElement.
-    // For a deeper swap, the target is the surviving layer's slot anchor (Comment).
-    const parentLifetime = firstMismatch === 0 ? undefined : (chainHandles[firstMismatch - 1].slotLifetime ?? undefined);
-    const mountTargetArg = firstMismatch === 0 ? rootEl : chainHandles[firstMismatch - 1].slotAnchor;
-    mountChainSuffix(newChain, newChainData, firstMismatch, mountTargetArg, parentLifetime, {
+    const mountTarget = firstMismatch === 0 ? rootEl : chainHandles[firstMismatch - 1].slotAnchor;
+    const mountContexts = firstMismatch === 0 ? undefined : (chainHandles[firstMismatch - 1].slotContexts ?? undefined);
+    mountChainSuffix(newChain, newChainData, firstMismatch, mountTarget, mountContexts, {
         mode: 'mount',
     });
     // onEnter fires after the new suffix is in place. Fire-and-forget.
@@ -274,18 +199,8 @@ async function renderClient(pageContext, options) {
     options.onMount?.(snapshotLayoutChain());
 }
 /**
- * Public read of the current layout chain. Returns the live
- * `AppHandle`s for `[...layouts, page]`, outermost first. Empty array
- * before the first mount; updates after every navigation.
- *
- * Returns a fresh array each call, but the AppHandle references are
- * shared with the live chain — calling `.send()` / `.dispose()` /
- * `.subscribe()` operates on the same instance the framework manages.
- *
- * Prefer the `onMount(chain)` callback for lifecycle-coupled wiring
- * (the framework guarantees the chain is fully populated when it
- * fires); use this getter for ad-hoc reads where the caller can't
- * thread state through `onMount`.
+ * Public read of the current layout chain — live `LayerHandle`s for
+ * `[...layouts, page]`, outermost first. Empty before the first mount.
  */
 export function getLayoutChain() {
     return snapshotLayoutChain();
@@ -294,81 +209,57 @@ function snapshotLayoutChain() {
     return chainHandles.map((entry) => entry.handle);
 }
 /**
- * Walk the full chain for the first mount or hydration. Starts from
- * depth 0 at the root container, threads each layer's slot into the
- * next layer's mount target + parentLifetime.
- */
-async function mountOrHydrateChain(chain, chainData, rootEl, opts) {
-    mountChainSuffix(chain, chainData, 0, rootEl, undefined, opts);
-}
-/**
- * Mount (or hydrate) `chain[startAt..end]` into `initialTarget`, with
- * the initial layer's rootLifetime parented at `initialParentLifetime`.
- * Threads slot → next-target → next-parentLifetime through the chain.
+ * Mount (or hydrate) `chain[startAt..end]` into `initialTarget`, replaying
+ * `initialContexts` into the first layer's build. Threads each layer's slot
+ * (anchor + captured contexts) into the next layer's target + contexts.
  *
- * `initialTarget` is `HTMLElement` for the outermost layer (container-
- * based mount/hydrate) and `Comment` for inner layers that mount relative
- * to a `pageSlot()` anchor.
+ * `initialTarget` is an `HTMLElement` for the outermost layer (container mount/
+ * hydrate) and a `Comment` for inner layers mounting relative to a `pageSlot()`
+ * anchor.
  *
- * Fails loudly if a non-innermost layer forgot to call `pageSlot()`,
- * or if the innermost layer called `pageSlot()` unnecessarily.
+ * Fails loudly if a non-innermost layer forgot to call `pageSlot()`, or if the
+ * innermost layer called `pageSlot()` unnecessarily.
  *
- * @internal — test helper. Exported so `client-page-slot.test.ts` can
- * test anchor-mount/dispose contracts directly with hand-built DOM.
- * Not part of the public API.
+ * @internal — test helper. Exported so `client-page-slot.test.ts` can exercise
+ * anchor-mount/dispose contracts directly with hand-built DOM.
  */
-export function _mountChainSuffix(chain, chainData, startAt, initialTarget, initialParentLifetime, opts) {
+export function _mountChainSuffix(chain, chainData, startAt, initialTarget, initialContexts, opts) {
     let mountTarget = initialTarget;
-    let parentLifetime = initialParentLifetime;
+    let contexts = initialContexts;
     for (let i = startAt; i < chain.length; i++) {
         const def = chain[i];
         const layerData = chainData[i];
         const isInnermost = i === chain.length - 1;
         // Defensive: clear any stale slot from a prior failed mount.
         _resetPendingSlot();
+        const isContainer = mountTarget.nodeType === 1;
+        const target = isContainer
+            ? mountTarget
+            : { anchor: mountTarget, mode: opts.mode === 'hydrate' ? 'replace' : 'append' };
         let handle;
         if (opts.mode === 'hydrate') {
-            // Hydration envelope: each layer pulls its own state slice. The
-            // envelope shape is `{ layouts: [...], page: {...} }` with each
-            // entry carrying `{ name, state }`. We match by name so a server/
-            // client mismatch throws with a clear error instead of silently
-            // hydrating the wrong state into the wrong instance.
+            // Each layer pulls its own state slice from the envelope, matched by name
+            // so a server/client mismatch throws clearly instead of binding wrong state.
             const layerState = extractHydrationState(opts.serverStateEnvelope, i, chain.length, def);
-            if (mountTarget.nodeType === 1) {
-                // HTMLElement — outermost layer, use hydrateApp (container-based).
-                // Cross from the type-erased AnyComponentDef back into a concrete
-                // ComponentDef<unknown, unknown, unknown, unknown> for the mount
-                // primitive's signature. The cast is safe — mountApp / hydrateApp
-                // don't use the type parameters at runtime.
-                handle = hydrateApp(mountTarget, def, layerState, { parentLifetime, runInitEffectsOnHydrate: opts.runInitEffectsOnHydrate });
-            }
-            else {
-                // Comment anchor — inner layer, use hydrateAtAnchor.
-                handle = hydrateAtAnchor(mountTarget, def, layerState, { parentLifetime, runInitEffectsOnHydrate: opts.runInitEffectsOnHydrate });
-            }
+            handle = hydrateSignalApp(target, def, layerState, {
+                runInitEffects: opts.runInitEffectsOnHydrate,
+                contexts,
+            });
         }
         else {
-            if (mountTarget.nodeType === 1) {
-                // HTMLElement — outermost layer, use mountApp (container-based).
-                handle = mountApp(mountTarget, def, layerData, { parentLifetime });
-            }
-            else {
-                // Comment anchor — inner layer, use mountAtAnchor.
-                handle = mountAtAnchor(mountTarget, def, layerData, { parentLifetime });
-            }
+            handle = mountSignalComponent(target, def, {
+                initialState: seedFor(layerData),
+                contexts,
+            });
         }
         const slot = _consumePendingSlot();
         if (isInnermost && slot !== null) {
-            // Innermost layer declared a slot with nothing to fill it —
-            // probably a misuse of pageSlot() in the page component itself.
             handle.dispose();
             throw new Error(`[llui/vike] <${def.name}> is the innermost component in the chain ` +
                 `but called pageSlot(). pageSlot() only belongs in layout components ` +
                 `that wrap a nested page or layout — not in the page itself.`);
         }
         if (!isInnermost && slot === null) {
-            // Non-innermost layer didn't declare a slot — there's nowhere to
-            // mount the remaining chain.
             handle.dispose();
             throw new Error(`[llui/vike] <${def.name}> is a layout layer at depth ${i} but did not ` +
                 `call pageSlot() in its view(). There are ${chain.length - i - 1} more ` +
@@ -379,47 +270,28 @@ export function _mountChainSuffix(chain, chainData, startAt, initialTarget, init
             def,
             handle,
             slotAnchor: slot?.anchor ?? null,
-            slotLifetime: slot?.slotLifetime ?? null,
+            slotContexts: slot?.contexts ?? null,
             data: layerData,
         });
         if (slot !== null) {
-            // Next layer mounts relative to the slot's comment anchor.
+            // Next layer mounts relative to this slot's anchor, replaying the
+            // contexts captured at the slot so providers above it stay reachable.
             mountTarget = slot.anchor;
-            parentLifetime = slot.slotLifetime;
+            contexts = slot.contexts;
         }
     }
 }
-// Internal alias used by renderClient and mountOrHydrateChain.
-// The public-named export above carries the @internal doc.
+// Internal alias used by renderClient. The public-named export above carries
+// the @internal doc.
 const mountChainSuffix = _mountChainSuffix;
 /**
- * Pull the per-layer state from the hydration envelope. Supports both
- * the new chain-aware shape (`{ layouts: [...], page: {...} }`) and the
- * legacy flat shape (`window.__LLUI_STATE__` is the state object itself)
- * for backward compatibility with pages written against 0.0.15 or earlier.
- *
- * Throws on envelope shape mismatch — missing entries, wrong component
- * name at a given index — so server/client drift fails loud instead of
- * silently binding the wrong state to the wrong instance.
- */
-/**
- * Shallow-key data diff for the persistent-layer prop-update path.
- * Returns true when `next` differs from `prev` enough to warrant
- * dispatching the user's `onLayerDataChange` hook:
- *
- * - `Object.is(prev, next)` short-circuits identical references.
- * - For two plain-object records, walks the union of keys and returns
- *   true on the first `Object.is` mismatch.
- * - For anything else (primitives, arrays, class instances), falls
- *   back to the top-level `Object.is` result — covers the cases where
- *   the host populates `lluiLayoutData[i]` with a primitive or a
- *   referentially-stable object.
+ * Shallow-key data diff for the surviving-layer prop-update path. Returns true
+ * when `next` differs from `prev` enough to warrant dispatching the user's
+ * `onLayerDataChange` hook.
  */
 function hasDataChanged(prev, next) {
     if (Object.is(prev, next))
         return false;
-    // Both must be plain object records to do a key walk; otherwise the
-    // Object.is above is the only signal.
     if (prev === null ||
         next === null ||
         typeof prev !== 'object' ||
@@ -442,9 +314,15 @@ function hasDataChanged(prev, next) {
     }
     return false;
 }
+/**
+ * Pull the per-layer state from the hydration envelope. Supports the chain-aware
+ * shape (`{ layouts: [...], page: {...} }`) and the legacy flat shape (the state
+ * object itself) for a single-layer page-only render.
+ *
+ * Throws on envelope shape mismatch — missing entries, wrong component name at a
+ * given index — so server/client drift fails loud.
+ */
 function extractHydrationState(envelope, layerIndex, chainLength, def) {
-    // Legacy flat envelope — no layout chain at render time. Only valid
-    // when the chain has a single layer (the page).
     const isLegacyFlat = envelope !== null &&
         typeof envelope === 'object' &&
         !('layouts' in envelope) &&