sygnal 5.2.0 → 5.2.1

package/src/vike/onRenderClient.ts

@@ -4,11 +4,15 @@
  * On first page load (hydration): reads server-serialized state and
  * boots the Sygnal app via run().
  *
- * On client-side navigation: disposes the previous app and boots
- * a fresh one for the new page.
+ * On client-side navigation with a Layout/Wrapper: the Layout and Wrapper
+ * stay mounted and only the Page sub-component is hot-swapped. Layout and
+ * Wrapper state persists across navigations. Without either, the app is
+ * disposed and recreated.
  *
- * Layout is rendered outside #page-view by onRenderHtml, so it persists
- * across navigations without being destroyed by Sygnal's DOM driver.
+ * Nesting order: Wrapper > Layout > Page
+ * - Wrappers are outermost (context providers, state management)
+ * - Layouts are inside wrappers (visual structure, navigation chrome)
+ * - Page is innermost (route-specific content, swapped on navigation)
  */
 
 // Import from the package entry so rollup externalizes it
@@ -24,56 +28,335 @@ declare global {
 interface PageContext {
   Page: any
   data?: any
+  routeParams?: Record<string, string>
+  urlPathname?: string
   isHydration?: boolean
   config: {
     Layout?: any | any[]
+    Wrapper?: any | any[]
     title?: string
     ssr?: boolean
   }
 }
 
 /** Track the running Sygnal app for disposal on navigation */
-let currentApp: { dispose: () => void } | null = null
+let currentApp: { sources: any; sinks: any; dispose: () => void } | null = null
+
+/**
+ * Mutable references read by the wrapper's view function.
+ * Updated on navigation to swap the Page without disposing the Layout.
+ */
+let currentPage: any = null
+let currentPageName: string = ''
+let currentPageData: any = {}
+let currentRouteParams: any = {}
+let currentUrlPathname: string = ''
+let pageNavCounter: number = 0
+
+/**
+ * Build a component vnode that matches what the JSX pragma produces.
+ */
+function componentVNode(comp: any, stateField: string, children: any[], compInitialState?: any): any {
+  const name = comp.componentName || comp.name || 'FUNCTION_COMPONENT'
+  return {
+    sel: name,
+    data: {
+      props: {
+        state: stateField,
+        sygnalOptions: {
+          name,
+          view: comp,
+          model: comp.model,
+          intent: comp.intent,
+          hmrActions: comp.hmrActions,
+          context: comp.context,
+          peers: comp.peers,
+          components: comp.components,
+          initialState: compInitialState,
+          isolatedState: true,
+          calculated: comp.calculated,
+          storeCalculatedInState: comp.storeCalculatedInState,
+          DOMSourceName: comp.DOMSourceName,
+          stateSourceName: comp.stateSourceName,
+          onError: comp.onError,
+          debug: comp.debug,
+        },
+      },
+    },
+    children,
+    text: undefined,
+    elm: undefined,
+    key: '__vike_' + stateField + '__',
+  }
+}
+
+/**
+ * Build a vnode for the current Page as a child of the Layout.
+ * Reads from mutable `currentPage` / `currentPageName` so the wrapper
+ * view picks up the new Page component on navigation without being recreated.
+ */
+function pageChildVNode(pageState: any): any {
+  // Include pageNavCounter in sel so instantiateSubComponents detects a
+  // component swap even when both pages have the same function name (e.g. 'Page').
+  const sel = currentPageName + '__nav' + pageNavCounter
+  return {
+    sel,
+    data: {
+      props: {
+        state: 'page',
+        sygnalOptions: {
+          name: sel,
+          view: currentPage,
+          model: currentPage.model,
+          intent: currentPage.intent,
+          hmrActions: currentPage.hmrActions,
+          context: currentPage.context,
+          peers: currentPage.peers,
+          components: currentPage.components,
+          initialState: pageState,
+          isolatedState: true,
+          calculated: currentPage.calculated,
+          storeCalculatedInState: currentPage.storeCalculatedInState,
+          DOMSourceName: currentPage.DOMSourceName,
+          stateSourceName: currentPage.stateSourceName,
+          onError: currentPage.onError,
+          debug: currentPage.debug,
+        },
+      },
+    },
+    children: [],
+    text: undefined,
+    elm: undefined,
+    key: '__vike_page__',
+  }
+}
+
+/**
+ * Create a synthetic wrapper component that nests Page inside Layout(s)
+ * inside Wrapper(s).
+ *
+ * Nesting order: Wrapper(s) > Layout(s) > Page
+ *
+ * The wrapper's view reads `currentPage` from the mutable closure, so
+ * on client-side navigation only the Page sub-component changes while
+ * the Layout and Wrapper stay mounted with their state preserved.
+ */
+function createLayoutWrapper(wrappers: any[], layouts: any[], Page: any): any {
+  currentPage = Page
+  currentPageName = Page.componentName || Page.name || 'VikePageComponent'
+
+  // Combined shell = wrappers (outermost) + layouts (innermost around Page)
+  // State keys: wrapper_0, wrapper_1, ..., layout_0, layout_1, ...
+  // Page state lives under the innermost shell component's slice.
+  const shell = [
+    ...wrappers.map((w: any, i: number) => ({ comp: w, key: 'wrapper_' + i })),
+    ...layouts.map((l: any, i: number) => ({ comp: l, key: 'layout_' + i })),
+  ]
+
+  function LayoutWrapperView({ state }: any) {
+    if (shell.length === 0) {
+      // No wrappers or layouts — render Page directly
+      return pageChildVNode(state.page)
+    }
+
+    const lastIdx = shell.length - 1
+    const innermostState = state[shell[lastIdx].key] || {}
+    let inner: any = componentVNode(
+      shell[lastIdx].comp,
+      shell[lastIdx].key,
+      [pageChildVNode(innermostState.page)],
+      innermostState
+    )
+
+    // Wrap with outer shell components
+    for (let i = lastIdx - 1; i >= 0; i--) {
+      inner = componentVNode(shell[i].comp, shell[i].key, [inner], state[shell[i].key])
+    }
+
+    // Wrap in a plain div so the view returns a regular DOM vnode.
+    // Sub-component vnodes at the root position are not processed correctly
+    // by the rendering pipeline — they must be children of a DOM element.
+    return {
+      sel: 'div',
+      data: { attrs: { id: 'vike-shell' } },
+      children: [inner],
+      text: undefined,
+      elm: undefined,
+      key: '__vike_shell__',
+    }
+  }
+
+  LayoutWrapperView.componentName = 'VikeLayoutWrapper'
+
+  // Build the wrapper's initial state with a slice for each shell component.
+  // Page state is nested under the innermost shell component's slice.
+  const wrapperInitialState: any = {}
+  shell.forEach(({ comp, key }: any, i: number) => {
+    const sliceState: any = { ...(comp.initialState || {}) }
+    if (i === shell.length - 1) {
+      sliceState.page = Page.initialState || {}
+    }
+    wrapperInitialState[key] = sliceState
+  })
+
+  LayoutWrapperView.initialState = wrapperInitialState
+
+  // Context uses mutable references so navigation updates are picked up.
+  // Wrapper and Layout contexts are merged once; page-level context
+  // (pageData, routeParams, urlPathname) reads from mutable variables
+  // updated on each navigation.
+  const shellContext: any = {}
+  shell.forEach(({ comp }: any) => {
+    if (comp.context) {
+      Object.assign(shellContext, comp.context)
+    }
+  })
+
+  LayoutWrapperView.context = {
+    ...shellContext,
+    ...(Page.context || {}),
+    pageData: () => currentPageData,
+    routeParams: () => currentRouteParams,
+    urlPathname: () => currentUrlPathname,
+  }
+
+  return LayoutWrapperView
+}
+
+/**
+ * Normalize a cumulative config value into an array of functions.
+ */
+function toComponentArray(val: any): any[] {
+  if (!val) return []
+  return (Array.isArray(val) ? val : [val]).filter((c: any) => typeof c === 'function')
+}
 
 export function onRenderClient(pageContext: PageContext) {
   const { Page, config } = pageContext
   const data = pageContext.data || {}
 
-  // Dispose previous app on client-side navigation
-  if (currentApp) {
-    currentApp.dispose()
-    currentApp = null
-  }
+  const wrappers = toComponentArray(config.Wrapper)
+  const layouts = toComponentArray(config.Layout)
+  const hasShell = wrappers.length > 0 || layouts.length > 0
 
-  // On first load with SSR, pick up server-serialized state.
-  // On client navigation (or SPA mode), merge data into initialState.
-  let initialState: any
-  if (typeof window !== 'undefined' && window.__VIKE_SYGNAL_STATE__ !== undefined) {
-    initialState = window.__VIKE_SYGNAL_STATE__
-    // Clear the global after reading to avoid stale state on soft navigation
-    delete window.__VIKE_SYGNAL_STATE__
+  // The shell is wrappers (outermost) + layouts. The innermost component
+  // holds the Page state as a nested sub-component.
+  const shell = [
+    ...wrappers.map((_: any, i: number) => 'wrapper_' + i),
+    ...layouts.map((_: any, i: number) => 'layout_' + i),
+  ]
+  const innermostKey = shell.length > 0 ? shell[shell.length - 1] : null
+
+  // Update mutable context references (used by the wrapper's context functions)
+  currentPageData = data
+  currentRouteParams = pageContext.routeParams || {}
+  currentUrlPathname = pageContext.urlPathname || ''
+
+  // --- Shell path: hot-swap Page, keep Layout/Wrapper alive ---
+  if (hasShell) {
+    if (currentApp) {
+      // Client-side navigation: swap the Page without disposing the shell.
+      currentPage = Page
+      currentPageName = Page.componentName || Page.name || 'VikePageComponent'
+      pageNavCounter++
+
+      const newPageState = { ...(Page.initialState || {}), ...data }
+      if (currentApp.sinks?.STATE?.shamefullySendNext) {
+        currentApp.sinks.STATE.shamefullySendNext((state: any) => {
+          const shellState = state[innermostKey!] || {}
+          return {
+            ...state,
+            [innermostKey!]: { ...shellState, page: newPageState },
+          }
+        })
+      }
+    } else {
+      // First load: read hydrated state or build from initialState
+      let initialState: any
+      if (typeof window !== 'undefined' && window.__VIKE_SYGNAL_STATE__ !== undefined) {
+        initialState = window.__VIKE_SYGNAL_STATE__
+        delete window.__VIKE_SYGNAL_STATE__
+      } else {
+        initialState = null
+      }
+
+      if (initialState && innermostKey && initialState[innermostKey] !== undefined) {
+        // Hydrated combined state — distribute slices to each shell component
+        const allShellComps = [...wrappers, ...layouts]
+        shell.forEach((key: string, i: number) => {
+          if (initialState[key] !== undefined) {
+            if (i === shell.length - 1) {
+              const { page: pageState, ...compState } = initialState[key]
+              allShellComps[i].initialState = compState
+              Page.initialState = pageState || { ...(Page.initialState || {}), ...data }
+            } else {
+              allShellComps[i].initialState = initialState[key]
+            }
+          }
+        })
+      } else {
+        // SPA mode or client-side first navigation
+        Page.initialState = { ...(Page.initialState || {}), ...data }
+      }
+
+      // Inject page-level context into Page (for SSR renderToString compat)
+      Page.context = {
+        ...Page.context,
+        pageData: () => currentPageData,
+        routeParams: () => currentRouteParams,
+        urlPathname: () => currentUrlPathname,
+      }
+
+      const Component = createLayoutWrapper(wrappers, layouts, Page)
+
+      try {
+        currentApp = run(Component, {}, { mountPoint: '#page-view' }) as any
+      } catch (err: any) {
+        console.error('[sygnal/vike] Client render error:', err)
+        const container = document.getElementById('page-view')
+        if (container) {
+          container.innerHTML = `<div data-sygnal-error style="padding:2rem;color:#e74c3c;font-family:monospace">
+            <h2>Render Error</h2>
+            <pre>${String(err.message || err)}</pre>
+          </div>`
+        }
+      }
+    }
+
+  // --- No shell path: dispose and recreate ---
   } else {
-    initialState = {
-      ...(Page.initialState || {}),
-      ...data,
+    if (currentApp) {
+      currentApp.dispose()
+      currentApp = null
+    }
+
+    let initialState: any
+    if (typeof window !== 'undefined' && window.__VIKE_SYGNAL_STATE__ !== undefined) {
+      initialState = window.__VIKE_SYGNAL_STATE__
+      delete window.__VIKE_SYGNAL_STATE__
+    } else {
+      initialState = { ...(Page.initialState || {}), ...data }
+    }
+
+    Page.initialState = initialState
+    Page.context = {
+      ...Page.context,
+      pageData: () => currentPageData,
+      routeParams: () => currentRouteParams,
+      urlPathname: () => currentUrlPathname,
     }
-  }
 
-  // Set the initial state on the component before running
-  Page.initialState = initialState
-
-  // Boot the Sygnal app into #page-view
-  // Layout HTML lives outside #page-view, so it won't be destroyed
-  try {
-    currentApp = run(Page, {}, { mountPoint: '#page-view' })
-  } catch (err: any) {
-    console.error('[sygnal/vike] Client render error:', err)
-    const container = document.getElementById('page-view')
-    if (container) {
-      container.innerHTML = `<div data-sygnal-error style="padding:2rem;color:#e74c3c;font-family:monospace">
-        <h2>Render Error</h2>
-        <pre>${String(err.message || err)}</pre>
-      </div>`
+    try {
+      currentApp = run(Page, {}, { mountPoint: '#page-view' }) as any
+    } catch (err: any) {
+      console.error('[sygnal/vike] Client render error:', err)
+      const container = document.getElementById('page-view')
+      if (container) {
+        container.innerHTML = `<div data-sygnal-error style="padding:2rem;color:#e74c3c;font-family:monospace">
+          <h2>Render Error</h2>
+          <pre>${String(err.message || err)}</pre>
+        </div>`
+      }
     }
   }
 

package/src/vike/onRenderHtml.ts

@@ -5,6 +5,10 @@
  * wraps it in a full HTML document, and embeds serialized state for
  * client hydration.
  *
+ * When a Layout is configured, the Layout HTML wraps the Page HTML
+ * inside #page-view so the structure matches the client-side wrapper
+ * component (see onRenderClient.ts).
+ *
  * Returns a plain HTML string. Vike wraps it with dangerouslySkipEscape
  * automatically. We avoid importing from vike/server because our bundled
  * output lives in node_modules/sygnal/ where vike isn't resolvable.
@@ -16,8 +20,11 @@ import { renderToString } from 'sygnal'
 interface PageContext {
   Page: any
   data?: any
+  routeParams?: Record<string, string>
+  urlPathname?: string
   config: {
     Layout?: any | any[]
+    Wrapper?: any | any[]
     Head?: any
     title?: string
     description?: string
@@ -69,12 +76,34 @@ export function onRenderHtml(pageContext: PageContext) {
     ...data,
   }
 
-  // Render the page component to HTML, with error boundary
+  // Inject page data, route params, and URL into the component's context
+  // so sub-components can access them without prop drilling during SSR.
+  Page.context = {
+    ...Page.context,
+    pageData: () => data,
+    routeParams: () => pageContext.routeParams || {},
+    urlPathname: () => pageContext.urlPathname || '',
+  }
+
+  // Determine if Wrapper(s) and/or Layout(s) are present — this affects hydration state shape
+  const wrapperArray = config.Wrapper
+    ? (Array.isArray(config.Wrapper) ? config.Wrapper : [config.Wrapper])
+        .filter((W: any) => typeof W === 'function')
+    : []
+  const layoutArray = config.Layout
+    ? (Array.isArray(config.Layout) ? config.Layout : [config.Layout])
+        .filter((L: any) => typeof L === 'function')
+    : []
+  const hasShell = wrapperArray.length > 0 || layoutArray.length > 0
+
+  // Render the page component to HTML, with error boundary.
+  // When layouts are present, the hydration state is serialized separately
+  // as the wrapper's combined state (with page + layout slices).
   let pageHtml: string
   try {
     pageHtml = renderToString(Page, {
       state: initialState,
-      hydrateState: '__VIKE_SYGNAL_STATE__',
+      hydrateState: hasShell ? false : '__VIKE_SYGNAL_STATE__',
     })
   } catch (err: any) {
     // If the component has an onError boundary, try rendering its fallback
@@ -83,8 +112,9 @@ export function onRenderHtml(pageContext: PageContext) {
         const fallbackVNode = Page.onError(err, { componentName: Page.name || 'Page' })
         if (fallbackVNode) {
           pageHtml = renderToString(() => fallbackVNode, { state: {} })
-          // Still embed the state so the client can attempt hydration
-          pageHtml += `<script>window.__VIKE_SYGNAL_STATE__=${JSON.stringify(initialState)}</script>`
+          if (!hasShell) {
+            pageHtml += `<script>window.__VIKE_SYGNAL_STATE__=${JSON.stringify(initialState)}</script>`
+          }
         } else {
           pageHtml = `<div data-sygnal-error>Render error</div>`
         }
@@ -97,34 +127,50 @@ export function onRenderHtml(pageContext: PageContext) {
     }
   }
 
-  // If Layout(s) are defined, render them as static HTML wrapping the page.
-  // The Layout is rendered OUTSIDE #page-view so that Sygnal's DOM driver
-  // (which replaces the mount point content) doesn't destroy the Layout.
-  let layoutBeforeHtml = ''
-  let layoutAfterHtml = ''
-  const layouts = config.Layout
-  if (layouts) {
-    const layoutArray = Array.isArray(layouts) ? layouts : [layouts]
-    for (const Layout of layoutArray) {
-      if (typeof Layout === 'function') {
-        // Render the Layout with a placeholder for page content.
-        // The Layout view receives { innerHTML: '<!--PAGE-->' } and we split
-        // the output around the placeholder to get before/after chunks.
-        const PLACEHOLDER = '<!--SYGNAL_PAGE_SLOT-->'
-        const layoutHtml = renderToString(Layout, {
-          state: Layout.initialState || {},
-          props: { innerHTML: PLACEHOLDER },
-        })
-        const splitIdx = layoutHtml.indexOf(PLACEHOLDER)
-        if (splitIdx !== -1) {
-          layoutBeforeHtml += layoutHtml.substring(0, splitIdx)
-          layoutAfterHtml = layoutHtml.substring(splitIdx + PLACEHOLDER.length) + layoutAfterHtml
-        } else {
-          // Fallback: Layout didn't use innerHTML, render it before page content
-          layoutBeforeHtml += layoutHtml
-        }
+  // If Layout(s) and/or Wrapper(s) are defined, render them wrapping the page content.
+  // HTML is rendered INSIDE #page-view so the structure matches the client-side
+  // wrapper component. Nesting order: Wrapper > Layout > Page.
+  // Each shell component receives page content via a placeholder in its children slot.
+  let pageViewContent = pageHtml
+  if (hasShell) {
+    // Combined shell: wrappers (outermost) + layouts (innermost around Page)
+    // Must match the order used in onRenderClient's createLayoutWrapper.
+    const shell = [
+      ...wrapperArray.map((w: any, i: number) => ({ comp: w, key: 'wrapper_' + i })),
+      ...layoutArray.map((l: any, i: number) => ({ comp: l, key: 'layout_' + i })),
+    ]
+
+    // Wrap from innermost to outermost (reverse order)
+    for (let i = shell.length - 1; i >= 0; i--) {
+      const { comp } = shell[i]
+      const PLACEHOLDER = '<!--SYGNAL_PAGE_SLOT-->'
+      const compHtml = renderToString(comp, {
+        state: comp.initialState || {},
+        props: { innerHTML: PLACEHOLDER },
+      })
+      const splitIdx = compHtml.indexOf(PLACEHOLDER)
+      if (splitIdx !== -1) {
+        pageViewContent = compHtml.substring(0, splitIdx) + pageViewContent + compHtml.substring(splitIdx + PLACEHOLDER.length)
+      } else {
+        // Fallback: component didn't use children/innerHTML, wrap content after it
+        pageViewContent = compHtml + pageViewContent
       }
     }
+    // Wrap in a shell div matching the client-side wrapper's root element
+    pageViewContent = `<div id="vike-shell">${pageViewContent}</div>`
+
+    // Serialize the wrapper's combined state for hydration.
+    // Must match the state shape from createLayoutWrapper:
+    //   { wrapper_0: {...}, layout_0: { ...layoutState, page: pageState } }
+    const wrapperState: any = {}
+    shell.forEach(({ comp, key }: any, i: number) => {
+      const compState: any = { ...(comp.initialState || {}) }
+      if (i === shell.length - 1) {
+        compState.page = initialState
+      }
+      wrapperState[key] = compState
+    })
+    pageViewContent += `<script>window.__VIKE_SYGNAL_STATE__=${JSON.stringify(wrapperState)}</script>`
   }
 
   // Render Head component for <head> tags
@@ -161,9 +207,7 @@ export function onRenderHtml(pageContext: PageContext) {
     ${headContent}
   </head>
   <body>
-    ${layoutBeforeHtml}
-    <div id="page-view">${pageHtml}</div>
-    ${layoutAfterHtml}
+    <div id="page-view">${pageViewContent}</div>
   </body>
 </html>`
 

package/src/vike/types.ts

@@ -10,6 +10,8 @@ declare global {
     interface Config {
       /** Sygnal component to wrap all pages (receives children) */
       Layout?: any
+      /** Sygnal component wrapping Layout + Page (for context providers, state management). Cumulative. */
+      Wrapper?: any
       /** Sygnal component rendered inside <head> for per-page meta tags */
       Head?: any
       /** Page <title> */

package/src/vite/plugin.ts

@@ -8,7 +8,7 @@
  *   export default defineConfig({ plugins: [sygnal()] })
  *
  * What it does:
- *   1. Configures esbuild for automatic JSX transform with sygnal as the import source
+ *   1. Configures OXC for automatic JSX transform with sygnal as the import source
  *   2. Detects files that call `run()` from sygnal and auto-injects HMR wiring
  *
  * The HMR transform finds the pattern:
@@ -52,9 +52,11 @@ export default function sygnal(options: SygnalPluginOptions = {}) {
       if (disableJsx) return
 
       return {
-        esbuild: {
-          jsx: 'automatic' as const,
-          jsxImportSource: 'sygnal',
+        oxc: {
+          jsx: {
+            runtime: 'automatic' as const,
+            importSource: 'sygnal',
+          },
         },
       }
     },