feat(use-pages): implement targeted SSR rendering and snapshot optimization

Introduces a high-performance selective rendering mechanism for SSR,
allowing the server to render and collect data for specific layouts
without the overhead of rendering the entire route tree.

Author: Nico Schett

packages/pylon/src/pages/internals.tsx

@@ -150,3 +150,31 @@ const useRouteDataRefetch = (): ((names?: string[]) => Promise<void[]>) => {
 }
 
 export {RouteDataProvider, useRouteData, useRouteDataRefetch}
+
+// ====================================================================
+// 5. SSR PRUNING (Selective Rendering)
+// ====================================================================
+
+const SSRPruningContext = createContext<string | null>(null)
+
+/**
+ * Provider to signal which layout should be the "pruning target" during SSR.
+ * Components matching this target will skip rendering their children.
+ */
+export const SSRPruningProvider: React.FC<{
+  target: string | null
+  children: React.ReactNode
+}> = ({children, target}) => {
+  return (
+    <SSRPruningContext.Provider value={target}>
+      {children}
+    </SSRPruningContext.Provider>
+  )
+}
+
+/**
+ * Hook to consume the SSR pruning target.
+ */
+export const useSSRPruning = () => {
+  return useContext(SSRPruningContext)
+}

packages/pylon/src/plugins/use-pages/build/app-utils.ts

@@ -100,7 +100,7 @@ function scanDirectory(directory: string, basePath: string = ''): Route | null {
           : `${layoutComponentName}`
 
       route.Component = `withLoaderData((props) => <${componentName} children={<Outlet />} {...props} />, "${componentName}")`
-      route.loader = `loader`
+      route.loader = `loader("${componentName}")`
       route.shouldRevalidate = `(args) => args.defaultShouldRevalidate`
 
       if (route.path === '/') {
@@ -132,7 +132,7 @@ function scanDirectory(directory: string, basePath: string = ''): Route | null {
         errorElement: '<ErrorElement standalone={false} />',
         lazy: `async () => {const i = await import(${importPath}).catch(() => {window.reload()}); return {Component: withLoaderData(i.default)}}`,
         HydrateFallback: 'HydrateFallback',
-        loader: `loader`
+        loader: `loader()`
       })
 
       pageFound = true
@@ -266,14 +266,23 @@ const HydrateFallback = () => {
 function withLoaderData<T>(Component: React.ComponentType<{ data: T }>, name?: string) {
   return function WithLoaderDataWrapper(props: T) {
     const dataClient = __PYLON_INTERNALS_DO_NOT_USE.useDataClient()
-    const {useQuery, useHydrateCache} = useMemo(() => dataClient.pageClient(), [])
-    const {cacheSnapshot, context} = __PYLON_ROUTER_INTERNALS_DO_NOT_USE.useLoaderData() || {};
+    const pruningTarget = __PYLON_INTERNALS_DO_NOT_USE.useSSRPruning()
 
+    const {cacheSnapshot, context} = __PYLON_ROUTER_INTERNALS_DO_NOT_USE.useLoaderData() || {};
     const location = __PYLON_ROUTER_INTERNALS_DO_NOT_USE.useLocation()
     const [searchParams] = __PYLON_ROUTER_INTERNALS_DO_NOT_USE.useSearchParams()
     const searchParamsObject = Object.fromEntries(searchParams.entries())
     const params = __PYLON_ROUTER_INTERNALS_DO_NOT_USE.useParams()
 
+    // 1. Handle Transparent Ancestors
+    // If we're optimized-rendering a specific layout, and THIS is not it,
+    // we just act as a passthrough to skip THIS layout's logic/queries.
+    if (pruningTarget && name !== pruningTarget) {
+      return <Outlet />
+    }
+
+    const {useQuery, useHydrateCache} = useMemo(() => dataClient.pageClient(), [])
+
     if(cacheSnapshot) {
       useHydrateCache({cacheSnapshot})
     }
@@ -290,13 +299,17 @@ function withLoaderData<T>(Component: React.ComponentType<{ data: T }>, name?: s
       }
     }, [location.pathname, params, searchParamsObject, data, context])
 
+    // 2. Handle Pruning Target
+    // If THIS is the target, we render it but clear its children (the Outlet).
+    const children = pruningTarget && name === pruningTarget ? null : <Outlet />
+
     return <__PYLON_INTERNALS_DO_NOT_USE.RouteDataProvider props={pageProps} name={name}>
-      <Component {...(props as any)} {...pageProps} />
+      <Component {...(props as any)} {...pageProps} children={children} />
     </__PYLON_INTERNALS_DO_NOT_USE.RouteDataProvider>
   };
 }
 
-const loader: __PYLON_ROUTER_INTERNALS_DO_NOT_USE.LoaderFunction = async ({ request }) => {
+const loader: (ref?: string) => __PYLON_ROUTER_INTERNALS_DO_NOT_USE.LoaderFunction = (ref) => async ({ request, ...args }) => {
   // 1. Skip if request is a JSON-only fetch (e.g., client-side route preloading)
   const acceptHeader = request.headers.get('accept')
   if (acceptHeader?.includes('application/json')) {
@@ -324,6 +337,9 @@ const loader: __PYLON_ROUTER_INTERNALS_DO_NOT_USE.LoaderFunction = async ({ requ
   }
 
   headers.set('Accept', 'application/json') // Ensure the internal request gets JSON
+  if(ref) {
+    headers.set('X-Pylon-Route-Ref', ref)
+  }
 
   const response = await fetchToUse(url.pathname + url.search, {
       method: 'GET',

packages/pylon/src/plugins/use-pages/setup/index.tsx

@@ -58,7 +58,7 @@ export const setup: Plugin['setup'] = async app => {
     .default
   const client = await import(`${process.cwd()}/.pylon/client/index.js`)
 
-  let handler = createStaticHandler(routes)
+  const handler = createStaticHandler(routes)
 
   app.use(trimTrailingSlash() as any)
 
@@ -261,23 +261,33 @@ export const setup: Plugin['setup'] = async app => {
   })
 
   app.get('*', disableCacheMiddleware as any, async c => {
-    const context = await handler.query(c.req.raw)
+    const staticHandlerContext = await handler.query(c.req.raw)
 
-    if (context instanceof Response) {
-      return context
+    if (staticHandlerContext instanceof Response) {
+      return staticHandlerContext
     }
 
-    const router = createStaticRouter(handler.dataRoutes, context)
+    // X-Pylon-Route-Ref header stores the route ref of the current layout
+    // This is used to remove the children of the layout to prevent
+    // rendering overhead
+    const xPylonRouteRef = c.req.header('x-pylon-route-ref')
+
+    const router = createStaticRouter(handler.dataRoutes, staticHandlerContext)
 
     const component = (
       <__PYLON_INTERNALS_DO_NOT_USE.DataClientProvider client={client}>
-        <StaticRouterProvider router={router} context={context} />
+        <__PYLON_INTERNALS_DO_NOT_USE.SSRPruningProvider
+          target={xPylonRouteRef || null}>
+          <StaticRouterProvider
+            router={router}
+            context={staticHandlerContext}
+          />
+        </__PYLON_INTERNALS_DO_NOT_USE.SSRPruningProvider>
       </__PYLON_INTERNALS_DO_NOT_USE.DataClientProvider>
     )
 
     // Check if the request wants JSON, if so, prepare the data
     if (c.req.header('accept')?.includes('application/json')) {
-      const context = c.get('pagesContext' as any) || {}
       let cacheSnapshot
       try {
         client.cache.clear()
@@ -290,6 +300,8 @@ export const setup: Plugin['setup'] = async app => {
         }
       }
 
+      const context = c.get('pagesContext' as any) || {}
+
       return c.json({
         cacheSnapshot,
         context