catalyst-core 0.3.0-beta.5 → 0.3.0-canary.2

package/dist/server/renderer/handler.jsx

@@ -1,328 +1,333 @@
-import React from "react"
-import { renderStart, renderEnd } from "./render.js"
-import { Provider } from "react-redux"
-import { Body } from "./document/Body.jsx"
-import { Head } from "./document/Head.jsx"
-
-import { StaticRouter } from "react-router"
-import ServerRouter from "../../router/ServerRouter.js"
-import { renderToPipeableStream } from "react-dom/server"
-import { getUserAgentDetails } from "../utils/userAgentUtil.js"
-import { serverDataFetcher, matchRoutes as NestedMatchRoutes, getMetaData } from "../../index.jsx"
-import { validateConfigureStore, validateGetRoutes, safeCall } from "../utils/validator.js"
-import { ChunkExtractor } from "./ChunkExtractor.js"
-import {
-    readCssFromDisk,
-    generateScriptElements,
-    generateCssLinkStrings,
-    generateScriptStrings,
-    getDeferredRouteKey,
-    getCachedDeferredCssPathsForRoute,
-    registerDeferredAssetsForRoute,
-    getDeferredPreloadScriptUrls,
-    generateModulePreloadLinkElements,
-} from "./extract.js"
-import path from "path"
-import { Transform } from "node:stream"
-
-import CustomDocument from "@catalyst/template/server/document"
-
-import App from "@catalyst/template/src/js/containers/App/index"
-import { getRoutes } from "@catalyst/template/src/js/routes/utils"
-import createStore from "@catalyst/template/src/js/store/index.js"
-import { SsrRequestProvider } from "../../web-router/components/SsrRequestContext.jsx"
-import { getManifest, getAssetManifest } from "../manifestCache.js"
-
-const DEFAULT_SAFE_AREA_INSETS = { top: 0, right: 0, bottom: 0, left: 0 }
-
-const parseSafeAreaFromHeaders = (req) => {
-    const readEdge = (header) => {
-        const raw = req.get(header) ?? req.headers[header.toLowerCase()]
-        const value = Number(raw)
-        return Number.isFinite(value) && value >= 0 ? value : null
-    }
-
-    const top = readEdge("X-Safe-Area-Top")
-    const right = readEdge("X-Safe-Area-Right")
-    const bottom = readEdge("X-Safe-Area-Bottom")
-    const left = readEdge("X-Safe-Area-Left")
-
-    if (![top, right, bottom, left].some((value) => value !== null)) return null
-
-    return {
-        top: top ?? 0,
-        right: right ?? 0,
-        bottom: bottom ?? 0,
-        left: left ?? 0,
-    }
-}
+/* global globalThis */
+import React from "react";
+import { renderStart, renderEnd } from "./render.js";
+import { Provider } from "react-redux";
+import { Body } from "./document/Body.jsx";
+import { Head } from "./document/Head.jsx";
+import { StaticRouter, matchRoutes as NestedMatchRoutes } from "react-router";
+import ServerRouter from "../../router/ServerRouter.js";
+import { renderToPipeableStream } from "react-dom/server";
+import { getUserAgentDetails } from "../utils/userAgentUtil.js";
+import { serverDataFetcher } from "../../web-router/components/RouterDataProvider.jsx";
+import { getMetaData } from "../../web-router/utils/metaDataUtils.jsx";
+import { validateConfigureStore, validateGetRoutes, validateCustomDocument, handleError, safeCall } from "../utils/validator.js";
+import { ChunkExtractor } from "./ChunkExtractor.js";
+import { readCssFromDisk, generateScriptElements, generateScriptStrings, getDeferredRouteKey, getCachedDeferredCssPathsForRoute, registerDeferredAssetsForRoute, getDeferredPreloadScriptUrls, generateModulePreloadLinkElements } from "./extract.js";
+import path from "path";
+import { Transform } from "node:stream";
+import CustomDocument from "@catalyst/template/server/document";
+import App from "@catalyst/template/src/js/containers/App/index";
+import { getRoutes } from "@catalyst/template/src/js/routes/utils";
+import createStore from "@catalyst/template/src/js/store/index.js";
+import { SsrRequestProvider } from "../../web-router/components/SsrRequestContext.jsx";
+import { getManifest, getAssetManifest } from "../manifestCache.js";
+import { wrapSSRError, formatError } from "../../errors/index.js";
+import { resolveOutputMode, getDebugEnvInfo } from "../../scripts/scriptUtils.js";
+
+// Resolved once at module load — spawned via serve.js/start.js, which
+// forward the mode as CATALYST_OUTPUT_MODE. Passed an empty argv on purpose:
+// this process never sees the parent's CLI flags, so process.argv here would
+// never contain --debug/--verbose — only CATALYST_OUTPUT_MODE is real input.
+const outputMode = resolveOutputMode([], process.env);
+// Debug mode's boxed output already embeds the full stack trace (see
+// errors/index.js#formatDebug), so only default/verbose need the original
+// error printed separately to avoid losing the stack.
+const logSSRError = (stage, error) => {
+  const wrapped = wrapSSRError(stage, error);
+  const debugEnv = outputMode === "debug" ? getDebugEnvInfo() : undefined;
+  console.error(formatError(wrapped, outputMode, debugEnv));
+  if (outputMode !== "debug") console.error(error);
+};
+const DEFAULT_SAFE_AREA_INSETS = {
+  top: 0,
+  right: 0,
+  bottom: 0,
+  left: 0
+};
+const parseSafeAreaFromHeaders = req => {
+  const readEdge = header => {
+    const raw = req.get(header) ?? req.headers[header.toLowerCase()];
+    const value = Number(raw);
+    return Number.isFinite(value) && value >= 0 ? value : null;
+  };
+  const top = readEdge("X-Safe-Area-Top");
+  const right = readEdge("X-Safe-Area-Right");
+  const bottom = readEdge("X-Safe-Area-Bottom");
+  const left = readEdge("X-Safe-Area-Left");
+  if (![top, right, bottom, left].some(value => value !== null)) return null;
+  return {
+    top: top ?? 0,
+    right: right ?? 0,
+    bottom: bottom ?? 0,
+    left: left ?? 0
+  };
+};
+
+// App contract checks run at module load, not per request. The validators
+// log-and-continue (see server/utils/validator.ts): a violation is reported once
+// through the shared structured-error formatter at module load — server startup
+// in production, first SSR request in dev — rather than being re-reported on
+// every request or swallowed into onRequestError by _handler's try/catch.
+validateGetRoutes(getRoutes);
+validateConfigureStore(createStore);
 
 // Routes are static for the lifetime of the server — resolve once and reuse
 // the same instance per request to avoid per-request allocation.
-let _cachedRoutes
+let _cachedRoutes;
 const getCachedRoutes = () => {
-    if (_cachedRoutes === undefined) {
-        _cachedRoutes = validateGetRoutes(getRoutes) ? getRoutes() : null
-    }
-    return _cachedRoutes
-}
+  if (_cachedRoutes === undefined) {
+    const getRoutesErr = validateGetRoutes(getRoutes);
+    if (getRoutesErr) handleError(getRoutesErr);
+    _cachedRoutes = getRoutesErr ? null : getRoutes();
+  }
+  return _cachedRoutes;
+};
 
 // Try to import user-defined hooks. These are optional — apps that don't export them
 // will get undefined, and safeCall is a no-op for non-functions.
-let _onRouteMatch,
-    _onFetcherSuccess,
-    _onFetcherError,
-    _onAppServerSideSuccess,
-    _onAppServerSideError,
-    _onRenderError,
-    _onRequestError
+let _onRouteMatch, _onFetcherSuccess, _onFetcherError, _onAppServerSideSuccess, _onAppServerSideError, _onRenderError, _onRequestError;
 try {
-    const hooks = await import("@catalyst/template/server/index.js")
-    _onRouteMatch = hooks.onRouteMatch
-    _onFetcherSuccess = hooks.onFetcherSuccess
-    _onFetcherError = hooks.onFetcherError
-    _onAppServerSideSuccess = hooks.onAppServerSideSuccess
-    _onAppServerSideError = hooks.onAppServerSideError
-    _onRenderError = hooks.onRenderError
-    _onRequestError = hooks.onRequestError
+  const hooks = await import("@catalyst/template/server/index.js");
+  _onRouteMatch = hooks.onRouteMatch;
+  _onFetcherSuccess = hooks.onFetcherSuccess;
+  _onFetcherError = hooks.onFetcherError;
+  _onAppServerSideSuccess = hooks.onAppServerSideSuccess;
+  _onAppServerSideError = hooks.onAppServerSideError;
+  _onRenderError = hooks.onRenderError;
+  _onRequestError = hooks.onRequestError;
 } catch {
-    // No hooks file — all hooks remain undefined, safeCall will skip them
+  // No hooks file — all hooks remain undefined, safeCall will skip them
 }
 
 // Passthrough no-ops used when OTEL_ENABLE is not set; replaced below if enabled.
-let withObservability = (_service, fn) => fn
-let withSyncObservability = (_service, fn) => fn
+let withObservability = (_service, fn) => fn;
+let withSyncObservability = (_service, fn) => fn;
 
+// config.json booleans survive the process.env swap in loadEnvironmentVariables(),
+// so this is genuinely true at runtime when config sets OTEL_ENABLE: true. The cast
+// exists only because TS types process.env values as string | undefined.
 if (process.env.OTEL_ENABLE === true) {
-    try {
-        const otel = await import("../../otel.js")
-        withObservability = otel.withObservability
-        withSyncObservability = otel.withSyncObservability
-    } catch {
-        // otel packages not installed — continue without tracing
-    }
+  try {
+    const otel = await import("../../otel.js");
+    withObservability = otel.withObservability;
+    withSyncObservability = otel.withSyncObservability;
+  } catch {
+    // otel packages not installed — continue without tracing
+  }
 }
-
-const SSR_SERVICE = process.env.SERVICE_NAME || `pwa-${process.env.APPLICATION}-node-server`
-
-const traceHook = (fn, spanName) =>
-    typeof fn === "function" ? withSyncObservability(SSR_SERVICE, fn, spanName) : fn
-
-const onRouteMatch = traceHook(_onRouteMatch, "onRouteMatch")
-const onFetcherSuccess = traceHook(_onFetcherSuccess, "onFetcherSuccess")
-const onFetcherError = traceHook(_onFetcherError, "onFetcherError")
-const onAppServerSideSuccess = traceHook(_onAppServerSideSuccess, "onAppServerSideSuccess")
-const onAppServerSideError = traceHook(_onAppServerSideError, "onAppServerSideError")
-const onRenderError = traceHook(_onRenderError, "onRenderError")
-const onRequestError = traceHook(_onRequestError, "onRequestError")
+const SSR_SERVICE = process.env.SERVICE_NAME || `pwa-${process.env.APPLICATION}-node-server`;
+const traceHook = (fn, spanName) => typeof fn === "function" ? withSyncObservability(SSR_SERVICE, fn, spanName) : fn;
+const onRouteMatch = traceHook(_onRouteMatch, "onRouteMatch");
+const onFetcherSuccess = traceHook(_onFetcherSuccess, "onFetcherSuccess");
+const onFetcherError = traceHook(_onFetcherError, "onFetcherError");
+const onAppServerSideSuccess = traceHook(_onAppServerSideSuccess, "onAppServerSideSuccess");
+const onAppServerSideError = traceHook(_onAppServerSideError, "onAppServerSideError");
+const onRenderError = traceHook(_onRenderError, "onRenderError");
+const onRequestError = traceHook(_onRequestError, "onRequestError");
 
 // ── Asset collection ───────────────────────────────────────────────────
 const _collectAssets = (req, allMatches) => {
-    const chunkExtractor = new ChunkExtractor({
-        manifest: getManifest() || {},
-        assetManifest: getAssetManifest() || {},
-    })
+  const chunkExtractor = new ChunkExtractor({
+    manifest: getManifest() || {},
+    assetManifest: getAssetManifest() || {}
+  });
 
-    // Add route-matched CSS/JS to critical bucket (loaded in <head>)
-    chunkExtractor.preloadRouteCss(allMatches)
-
-    return chunkExtractor
-}
-
-const collectAssets = withSyncObservability(SSR_SERVICE, _collectAssets, "collectAssets")
+  // Add route-matched CSS/JS to critical bucket (loaded in <head>)
+  chunkExtractor.preloadRouteCss(allMatches);
+  return chunkExtractor;
+};
+const collectAssets = withSyncObservability(SSR_SERVICE, _collectAssets, "collectAssets");
 
 // ── JSX tree ───────────────────────────────────────────────────────────
-const getComponent = (store, context, req, fetcherData, isBot) => (
-    <div id="app">
-        <SsrRequestProvider value={{ isBot }}>
-            <Provider store={store}>
-                <StaticRouter context={context} location={req.originalUrl}>
+// Three type-only escape hatches in the tree below. They are declared here as
+// plain aliases rather than inline @ts-expect-error comments, whose placement
+// inside JSX is unreliable. The aliases are erased at compile time and change
+// nothing at runtime.
+//
+//   - SsrRequestProvider / Provider are still .jsx, so TypeScript infers their
+//     props from the implementation and does not model implicit JSX children.
+//     Both aliases can go away once those modules are converted.
+//   - `context` is a react-router v5 prop that v7's StaticRouter no longer
+//     accepts or reads. It is kept because this conversion must not change
+//     runtime behaviour; removing it is a separate change.
+const SsrRequestProviderAny = SsrRequestProvider;
+const ProviderAny = Provider;
+const StaticRouterAny = StaticRouter;
+const getComponent = (store, context, req, fetcherData, isBot) => <div id="app">
+        <SsrRequestProviderAny value={{
+    isBot
+  }}>
+            <ProviderAny store={store}>
+                <StaticRouterAny context={context} location={req.originalUrl}>
                     <ServerRouter store={store} intialData={fetcherData} />
-                </StaticRouter>
-            </Provider>
-        </SsrRequestProvider>
-    </div>
-)
+                </StaticRouterAny>
+            </ProviderAny>
+        </SsrRequestProviderAny>
+    </div>;
 
 // ── Render and stream ──────────────────────────────────────────────────
-const _renderMarkUp = async (
-    errorCode,
+const _renderMarkUp = async (errorCode, req, res, metaTags, fetcherData, store, allMatches, context, chunkExtractor) => {
+  const deviceDetails = getUserAgentDetails(req.headers["user-agent"] || "");
+  // Match mweb's wider definition: synthetic monitors (StatusCake) and AI crawlers
+  // also need the bot code path — no JS, and split(... ssr: false ...) widgets that
+  // previously read state.shellReducer.isBot now read this via SsrRequestContext.
+  const isBot = !!(deviceDetails.googleBot || deviceDetails.aiBot || deviceDetails.statusCakeBot);
+  const safeArea = parseSafeAreaFromHeaders(req) || {
+    ...DEFAULT_SAFE_AREA_INSETS
+  };
+  const previousSafeArea = globalThis.__SAFE_AREA_INITIAL__;
+  globalThis.__SAFE_AREA_INITIAL__ = safeArea;
+  const cleanupSafeArea = () => {
+    if (previousSafeArea === undefined) {
+      delete globalThis.__SAFE_AREA_INITIAL__;
+    } else {
+      globalThis.__SAFE_AREA_INITIAL__ = previousSafeArea;
+    }
+  };
+
+  // Critical assets → <head>
+  const criticalAssets = chunkExtractor ? chunkExtractor.getCriticalAssets() : {
+    js: [],
+    css: []
+  };
+
+  // Inline critical CSS from disk (small thanks to natural code-splitting)
+  const buildDir = path.join(process.env.src_path, process.env.BUILD_OUTPUT_PATH || "build");
+  const inlineCss = readCssFromDisk(criticalAssets.css, buildDir);
+  const deferredRouteKey = getDeferredRouteKey(req, allMatches);
+  const deferredRouteInlineCss = readCssFromDisk(getCachedDeferredCssPathsForRoute(deferredRouteKey), buildDir);
+  const jsScripts = generateScriptElements(criticalAssets.js);
+  const criticalPreloadLinks = generateModulePreloadLinkElements(criticalAssets.js, "critical-js");
+  const deferredPreloadUrls = getDeferredPreloadScriptUrls(deferredRouteKey, criticalAssets.js);
+  const deferredPreloadLinks = generateModulePreloadLinkElements(deferredPreloadUrls, "deferred-js");
+
+  // Build Head props
+  const shellStart = renderStart({
+    inlineCss,
+    deferredRouteInlineCss,
+    jsScripts,
+    criticalPreloadLinks,
+    deferredPreloadLinks,
+    metaTags,
+    isBot,
+    fetcherData
+  });
+  const state = store.getState();
+  const jsx = getComponent(store, context, req, fetcherData, isBot);
+  const shellEnd = renderEnd(state, res, jsx, errorCode, fetcherData);
+
+  // The response status also reaches the document as `statusCode`, which Body
+  // exposes as window.__STATUS_CODE__. `errorCode` stays for custom documents.
+  const status = errorCode || (allMatches.length && allMatches[0]?.route?.path === "*" ? 404 : 200);
+  const finalProps = {
+    ...shellStart,
+    ...shellEnd,
+    jsx,
     req,
     res,
-    metaTags,
-    fetcherData,
-    store,
-    allMatches,
-    context,
-    chunkExtractor
-) => {
-    const deviceDetails = getUserAgentDetails(req.headers["user-agent"] || "")
-    // Match mweb's wider definition: synthetic monitors (StatusCake) and AI crawlers
-    // also need the bot code path — no JS, and split(... ssr: false ...) widgets that
-    // previously read state.shellReducer.isBot now read this via SsrRequestContext.
-    const isBot = !!(deviceDetails.googleBot || deviceDetails.aiBot || deviceDetails.statusCakeBot)
-    const safeArea = parseSafeAreaFromHeaders(req) || { ...DEFAULT_SAFE_AREA_INSETS }
-    const previousSafeArea = globalThis.__SAFE_AREA_INITIAL__
-    globalThis.__SAFE_AREA_INITIAL__ = safeArea
-
-    const cleanupSafeArea = () => {
-        if (previousSafeArea === undefined) {
-            delete globalThis.__SAFE_AREA_INITIAL__
-        } else {
-            globalThis.__SAFE_AREA_INITIAL__ = previousSafeArea
-        }
+    safeArea,
+    statusCode: status
+  };
+  const CompleteDocument = () => {
+    // CustomDocument is an OPTIONAL export (server/document.js) — its
+    // absence is valid, so PREFLIGHT-020 (missing) is not surfaced. If it
+    // IS exported but isn't callable, flag it (PREFLIGHT-021) and fall
+    // back to the built-in document rather than crashing the render.
+    if (CustomDocument) {
+      const customDocErr = validateCustomDocument(CustomDocument);
+      if (customDocErr) handleError(customDocErr);else return CustomDocument(finalProps);
     }
-
-    // Critical assets → <head>
-    const criticalAssets = chunkExtractor ? chunkExtractor.getCriticalAssets() : { js: [], css: [] }
-
-    // Inline critical CSS from disk (small thanks to natural code-splitting)
-    const buildDir = path.join(process.env.src_path, process.env.BUILD_OUTPUT_PATH || "build")
-    const inlineCss = readCssFromDisk(criticalAssets.css, buildDir)
-
-    const deferredRouteKey = getDeferredRouteKey(req, allMatches)
-    const deferredRouteInlineCss = readCssFromDisk(
-        getCachedDeferredCssPathsForRoute(deferredRouteKey),
-        buildDir
-    )
-
-    const jsScripts = generateScriptElements(criticalAssets.js)
-    const criticalPreloadLinks = generateModulePreloadLinkElements(criticalAssets.js, "critical-js")
-    const deferredPreloadUrls = getDeferredPreloadScriptUrls(deferredRouteKey, criticalAssets.js)
-    const deferredPreloadLinks = generateModulePreloadLinkElements(deferredPreloadUrls, "deferred-js")
-
-    // Build Head props
-    const shellStart = renderStart({
-        inlineCss,
-        deferredRouteInlineCss,
-        jsScripts,
-        criticalPreloadLinks,
-        deferredPreloadLinks,
-        metaTags,
-        isBot,
-        fetcherData,
-    })
-
-    const state = store.getState()
-    const jsx = getComponent(store, context, req, fetcherData, isBot)
-    const shellEnd = renderEnd(state, res, jsx, errorCode, fetcherData)
-
-    const finalProps = { ...shellStart, ...shellEnd, jsx, req, res, safeArea }
-
-    const CompleteDocument = () => {
-        if (CustomDocument) {
-            return CustomDocument(finalProps)
+    return <html lang={finalProps.lang}>
+                <Head isBot={finalProps.isBot} inlineCss={finalProps.inlineCss} deferredRouteInlineCss={finalProps.deferredRouteInlineCss} jsScripts={finalProps.jsScripts} criticalPreloadLinks={finalProps.criticalPreloadLinks} deferredPreloadLinks={finalProps.deferredPreloadLinks} fetcherData={finalProps.fetcherData} metaTags={finalProps.metaTags} publicAssetPath={finalProps.publicAssetPath} />
+                <Body initialState={finalProps.initialState} jsx={finalProps.jsx} statusCode={finalProps.statusCode} fetcherData={finalProps.fetcherData} safeArea={finalProps.safeArea} />
+            </html>;
+  };
+  try {
+    res.set({
+      "content-type": "text/html; charset=utf-8"
+    });
+    res.status(status);
+    return new Promise((resolve, reject) => {
+      // Single completion path: React's pipe() auto-ends `tail`, and
+      // `flush()` appends the deferred asset tags before that end
+      // signal propagates to `res` via the plain pipe below. This
+      // avoids the onShellReady/onAllReady race where React's own
+      // stream-end and a manual res.end() compete to close `res`
+      // (see issue #320).
+      const tail = new Transform({
+        transform(chunk, _enc, cb) {
+          cb(null, chunk);
+        },
+        flush(cb) {
+          // Deferred assets — injected after body (non-blocking)
+          const deferredAssets = chunkExtractor ? chunkExtractor.getDeferredAssets() : {
+            js: [],
+            css: []
+          };
+
+          // Tell client which components were SSR'd so split() can
+          // eagerly import them (prevents Suspense fallback flash)
+          this.push(`<script>window.__CATALYST_IS_BOT__=${isBot ? "true" : "false"};</script>`);
+          if (chunkExtractor) {
+            const renderedKeys = chunkExtractor.getRenderedComponentKeys();
+            this.push(
+            // nosemgrep: javascript.lang.security.audit.unknown-value-with-script-tag.unknown-value-with-script-tag - renderedKeys are internal bundler component-module keys tracked by ChunkExtractor, never request/user input, and are JSON.stringify-escaped before embedding.
+            `<script>window.__SSR_RENDERED_COMPONENTS__=new Set(${JSON.stringify(renderedKeys)})</script>`);
+          }
+          const {
+            newCssPaths
+          } = registerDeferredAssetsForRoute(deferredRouteKey, deferredAssets, isBot);
+          if (newCssPaths.length) {
+            this.push(`<style>${readCssFromDisk(newCssPaths, buildDir)}</style>`);
+          }
+          if (!isBot) {
+            this.push(generateScriptStrings(deferredAssets.js));
+          }
+          cb();
         }
-        return (
-            <html lang={finalProps.lang}>
-                <Head
-                    isBot={finalProps.isBot}
-                    inlineCss={finalProps.inlineCss}
-                    deferredRouteInlineCss={finalProps.deferredRouteInlineCss}
-                    jsScripts={finalProps.jsScripts}
-                    criticalPreloadLinks={finalProps.criticalPreloadLinks}
-                    deferredPreloadLinks={finalProps.deferredPreloadLinks}
-                    fetcherData={finalProps.fetcherData}
-                    metaTags={finalProps.metaTags}
-                    publicAssetPath={finalProps.publicAssetPath}
-                />
-                <Body
-                    initialState={finalProps.initialState}
-                    jsx={finalProps.jsx}
-                    statusCode={finalProps.statusCode}
-                    fetcherData={finalProps.fetcherData}
-                    safeArea={finalProps.safeArea}
-                />
-            </html>
-        )
-    }
-
-    try {
-        const status = errorCode || (allMatches.length && allMatches[0]?.route?.path === "*" ? 404 : 200)
-        res.set({ "content-type": "text/html; charset=utf-8" })
-        res.status(status)
-
-        return new Promise((resolve, reject) => {
-            // Single completion path: React's pipe() auto-ends `tail`, and
-            // `flush()` appends the deferred asset tags before that end
-            // signal propagates to `res` via the plain pipe below. This
-            // avoids the onShellReady/onAllReady race where React's own
-            // stream-end and a manual res.end() compete to close `res`
-            // (see issue #320).
-            const tail = new Transform({
-                transform(chunk, _enc, cb) {
-                    cb(null, chunk)
-                },
-                flush(cb) {
-                    // Deferred assets — injected after body (non-blocking)
-                    const deferredAssets = chunkExtractor
-                        ? chunkExtractor.getDeferredAssets()
-                        : { js: [], css: [] }
-
-                    // Tell client which components were SSR'd so split() can
-                    // eagerly import them (prevents Suspense fallback flash)
-                    this.push(`<script>window.__CATALYST_IS_BOT__=${isBot ? "true" : "false"};</script>`)
-                    if (chunkExtractor) {
-                        const renderedKeys = chunkExtractor.getRenderedComponentKeys()
-                        this.push(
-                            // nosemgrep: javascript.lang.security.audit.unknown-value-with-script-tag.unknown-value-with-script-tag - renderedKeys are internal bundler component-module keys tracked by ChunkExtractor, never request/user input, and are JSON.stringify-escaped before embedding.
-                            `<script>window.__SSR_RENDERED_COMPONENTS__=new Set(${JSON.stringify(renderedKeys)})</script>`
-                        )
-                    }
-
-                    const { newCssPaths } = registerDeferredAssetsForRoute(
-                        deferredRouteKey,
-                        deferredAssets,
-                        isBot
-                    )
-                    if (newCssPaths.length) {
-                        this.push(`<style>${readCssFromDisk(newCssPaths, buildDir)}</style>`)
-                    }
-                    if (!isBot) {
-                        this.push(generateScriptStrings(deferredAssets.js))
-                    }
-
-                    cb()
-                },
-            })
-            tail.pipe(res)
-
-            const { pipe } = renderToPipeableStream(<CompleteDocument />, {
-                onShellReady() {
-                    res.setHeader("content-type", "text/html")
-                    pipe(tail)
-                },
-
-                onAllReady() {
-                    cleanupSafeArea()
-                    resolve()
-                },
-
-                onError(error) {
-                    console.error("Error in renderToPipeableStream:", error)
-                    safeCall(onRenderError, { req, res, store, error })
-                    cleanupSafeArea()
-                    tail.destroy(error)
-                    reject(error)
-                },
-            })
-        })
-    } catch (error) {
-        cleanupSafeArea()
-        console.error("Error in rendering document on server:", error)
-        safeCall(onRenderError, { req, res, store, error })
-        return Promise.reject(error)
-    }
-}
-
-const tracedRenderMarkUp = withObservability(SSR_SERVICE, _renderMarkUp, "renderMarkUp")
-const tracedAppServerSideFunction = withObservability(
-    SSR_SERVICE,
-    (args) => App.serverSideFunction(args),
-    "App.serverSideFunction"
-)
-const tracedServerDataFetcher = withObservability(SSR_SERVICE, serverDataFetcher, "serverDataFetcher")
-const tracedGetMetaData = withSyncObservability(SSR_SERVICE, getMetaData, "getMetaData")
+      });
+      tail.pipe(res);
+      const {
+        pipe
+      } = renderToPipeableStream(<CompleteDocument />, {
+        onShellReady() {
+          res.setHeader("content-type", "text/html");
+          pipe(tail);
+        },
+        onAllReady() {
+          cleanupSafeArea();
+          resolve();
+        },
+        onError(error) {
+          logSSRError("RENDER", error);
+          safeCall(onRenderError, {
+            req,
+            res,
+            store,
+            error
+          });
+          cleanupSafeArea();
+          tail.destroy(error);
+          reject(error);
+        }
+      });
+    });
+  } catch (error) {
+    cleanupSafeArea();
+    logSSRError("RENDER", error);
+    safeCall(onRenderError, {
+      req,
+      res,
+      store,
+      error
+    });
+    return Promise.reject(error);
+  }
+};
+const tracedRenderMarkUp = withObservability(SSR_SERVICE, _renderMarkUp, "renderMarkUp");
+const tracedAppServerSideFunction = withObservability(SSR_SERVICE, args => App.serverSideFunction(args), "App.serverSideFunction");
+const tracedServerDataFetcher = withObservability(SSR_SERVICE, serverDataFetcher, "serverDataFetcher");
+const tracedGetMetaData = withSyncObservability(SSR_SERVICE, getMetaData, "getMetaData");
 
 // ── Express middleware ──────────────────────────────────────────────────
 /**
@@ -337,115 +342,107 @@ const tracedGetMetaData = withSyncObservability(SSR_SERVICE, getMetaData, "getMe
  * (e.g. a redirect), we bail out early without attempting another render.
  */
 async function _handler(req, res) {
+  try {
+    let context = {};
+    let fetcherData = {};
+    // A missing / non-function configureStore is not recoverable per
+    // request: every downstream step (serverSideFunction, data fetchers,
+    // render) assumes a real store. Log the coded error and fail the
+    // request with a 500 rather than rendering with `store = null`, which
+    // surfaces as a confusing render-time crash further down.
+    const configureStoreErr = validateConfigureStore(createStore);
+    if (configureStoreErr) {
+      handleError(configureStoreErr);
+      if (!res.headersSent) res.status(500).send("Internal Server Error");
+      return;
+    }
+    const store = await createStore({}, req, res);
+    const cachedRoutes = getCachedRoutes();
+    const allMatches = cachedRoutes ? NestedMatchRoutes(cachedRoutes, req.originalUrl) || [] : [];
+    let allTags = [];
+    safeCall(onRouteMatch, {
+      req,
+      res,
+      matches: allMatches,
+      store
+    });
+    if (res.headersSent) return;
     try {
-        let context = {}
-        let fetcherData = {}
-        const store = validateConfigureStore(createStore) ? await createStore({}, req, res) : null
-
-        const cachedRoutes = getCachedRoutes()
-        const allMatches = cachedRoutes ? NestedMatchRoutes(cachedRoutes, req.originalUrl) || [] : []
-        let allTags = []
-
-        safeCall(onRouteMatch, { req, res, matches: allMatches, store })
-
-        if (res.headersSent) return
-
-        try {
-            await tracedAppServerSideFunction({ store, req, res })
-            safeCall(onAppServerSideSuccess, { req, res, store })
-
-            if (res.headersSent) return
-
-            try {
-                fetcherData = await tracedServerDataFetcher(
-                    { routes: cachedRoutes, req, res, url: req.originalUrl },
-                    { store }
-                )
-
-                if (res.headersSent) return
-
-                const err = fetcherData?.[req.originalUrl]?.error
-                allTags = tracedGetMetaData(allMatches, fetcherData)
-                const chunkExtractor = collectAssets(req, allMatches)
-
-                if (err) {
-                    safeCall(onFetcherError, { req, res, store, error: err })
-
-                    if (res.headersSent) return
-
-                    const statusCode = err.status_code || 404
-                    await tracedRenderMarkUp(
-                        statusCode,
-                        req,
-                        res,
-                        allTags,
-                        fetcherData,
-                        store,
-                        allMatches,
-                        context,
-                        chunkExtractor
-                    )
-                } else {
-                    safeCall(onFetcherSuccess, { req, res, store })
-
-                    if (res.headersSent) return
-
-                    await tracedRenderMarkUp(
-                        null,
-                        req,
-                        res,
-                        allTags,
-                        fetcherData,
-                        store,
-                        allMatches,
-                        context,
-                        chunkExtractor
-                    )
-                }
-            } catch (error) {
-                console.error("Error in executing serverFetcher functions:", error)
-                safeCall(onFetcherError, { req, res, store, error })
-
-                if (res.headersSent) return
-
-                const chunkExtractor = collectAssets(req, allMatches)
-                await tracedRenderMarkUp(
-                    404,
-                    req,
-                    res,
-                    allTags,
-                    fetcherData,
-                    store,
-                    allMatches,
-                    context,
-                    chunkExtractor
-                )
-            }
-        } catch (error) {
-            console.error("Error in executing serverSideFunction inside App:", error)
-            safeCall(onAppServerSideError, { req, res, store, error })
-
-            if (res.headersSent) return
-
-            const chunkExtractor = collectAssets(req, allMatches)
-            await tracedRenderMarkUp(
-                error.status_code,
-                req,
-                res,
-                allTags,
-                fetcherData,
-                store,
-                allMatches,
-                context,
-                chunkExtractor
-            )
+      await tracedAppServerSideFunction({
+        store,
+        req,
+        res
+      });
+      safeCall(onAppServerSideSuccess, {
+        req,
+        res,
+        store
+      });
+      if (res.headersSent) return;
+      try {
+        fetcherData = await tracedServerDataFetcher({
+          routes: cachedRoutes,
+          req,
+          res,
+          url: req.originalUrl
+        }, {
+          store
+        });
+        if (res.headersSent) return;
+        const err = fetcherData?.[req.originalUrl]?.error;
+        allTags = tracedGetMetaData(allMatches, fetcherData);
+        const chunkExtractor = collectAssets(req, allMatches);
+        if (err) {
+          safeCall(onFetcherError, {
+            req,
+            res,
+            store,
+            error: err
+          });
+          if (res.headersSent) return;
+          const statusCode = err.status_code || 404;
+          await tracedRenderMarkUp(statusCode, req, res, allTags, fetcherData, store, allMatches, context, chunkExtractor);
+        } else {
+          safeCall(onFetcherSuccess, {
+            req,
+            res,
+            store
+          });
+          if (res.headersSent) return;
+          await tracedRenderMarkUp(null, req, res, allTags, fetcherData, store, allMatches, context, chunkExtractor);
         }
+      } catch (error) {
+        logSSRError("FETCHER", error);
+        safeCall(onFetcherError, {
+          req,
+          res,
+          store,
+          error
+        });
+        if (res.headersSent) return;
+        const chunkExtractor = collectAssets(req, allMatches);
+        await tracedRenderMarkUp(404, req, res, allTags, fetcherData, store, allMatches, context, chunkExtractor);
+      }
     } catch (error) {
-        console.error("Error in handling document request:", error)
-        safeCall(onRequestError, { req, res, error })
+      logSSRError("SERVER_SIDE_FUNCTION", error);
+      safeCall(onAppServerSideError, {
+        req,
+        res,
+        store,
+        error
+      });
+      if (res.headersSent) return;
+      const chunkExtractor = collectAssets(req, allMatches);
+      await tracedRenderMarkUp(error.status_code, req, res, allTags, fetcherData, store, allMatches, context, chunkExtractor);
     }
+  } catch (error) {
+    logSSRError("REQUEST_HANDLING", error);
+    safeCall(onRequestError, {
+      req,
+      res,
+      error
+    });
+  }
 }
-
-const handler = withObservability(SSR_SERVICE, _handler, "handler")
-
-export default handler
+const handler = withObservability(SSR_SERVICE, _handler, "handler");
+export default handler;