@nestjs-ssr/react 0.2.6 → 0.3.1

package/dist/render/index.mjs

@@ -185,6 +185,153 @@ window.__LAYOUTS__ = ${uneval(layoutMetadata)};
 TemplateParserService = _ts_decorate([
   Injectable()
 ], TemplateParserService);
+
+// src/render/renderers/string-renderer.ts
+function _ts_decorate2(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate2, "_ts_decorate");
+function _ts_metadata(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+__name(_ts_metadata, "_ts_metadata");
+var StringRenderer = class _StringRenderer {
+  static {
+    __name(this, "StringRenderer");
+  }
+  templateParser;
+  logger = new Logger(_StringRenderer.name);
+  constructor(templateParser) {
+    this.templateParser = templateParser;
+  }
+  /**
+  * Render a React component to a complete HTML string
+  */
+  async render(viewComponent, data, context, head) {
+    const startTime = Date.now();
+    let template = context.template;
+    if (context.vite) {
+      template = await context.vite.transformIndexHtml("/", template);
+    }
+    let renderModule;
+    if (context.vite) {
+      renderModule = await context.vite.ssrLoadModule(context.entryServerPath);
+    } else {
+      if (context.serverManifest) {
+        const manifestEntry = Object.entries(context.serverManifest).find(([key, value]) => value.isEntry && key.includes("entry-server"));
+        if (manifestEntry) {
+          const [, entry] = manifestEntry;
+          const serverPath = `${process.cwd()}/dist/server/${entry.file}`;
+          renderModule = await import(serverPath);
+        } else {
+          throw new Error("Server bundle not found in manifest. Run `pnpm build:server` to generate the server bundle.");
+        }
+      } else {
+        throw new Error("Server bundle not found in manifest. Run `pnpm build:server` to generate the server bundle.");
+      }
+    }
+    const { data: pageData, __context: pageContext, __layouts: layouts } = data;
+    const appHtml = await renderModule.renderComponent(viewComponent, data);
+    const componentName = viewComponent.displayName || viewComponent.name || "Component";
+    const layoutMetadata = layouts ? layouts.map((l) => ({
+      name: l.layout.displayName || l.layout.name || "default",
+      props: l.props
+    })) : [];
+    const initialStateScript = `
+        <script>
+          window.__INITIAL_STATE__ = ${uneval(pageData)};
+          window.__CONTEXT__ = ${uneval(pageContext)};
+          window.__COMPONENT_NAME__ = ${uneval(componentName)};
+          window.__LAYOUTS__ = ${uneval(layoutMetadata)};
+        </script>
+      `;
+    let clientScript = "";
+    let styles = "";
+    if (context.vite) {
+      clientScript = `<script type="module" src="/src/views/entry-client.tsx"></script>`;
+    } else {
+      if (context.manifest) {
+        const manifestEntry = Object.entries(context.manifest).find(([key, value]) => value.isEntry && key.includes("entry-client"));
+        if (manifestEntry) {
+          const [, entry] = manifestEntry;
+          const entryFile = entry.file;
+          clientScript = `<script type="module" src="/${entryFile}"></script>`;
+          if (entry.css) {
+            const cssFiles = entry.css;
+            styles = cssFiles.map((css) => `<link rel="stylesheet" href="/${css}" />`).join("\n    ");
+          }
+        } else {
+          this.logger.error("\u26A0\uFE0F  Client entry not found in manifest");
+          clientScript = `<script type="module" src="/assets/client.js"></script>`;
+        }
+      } else {
+        this.logger.error("\u26A0\uFE0F  Client manifest not found");
+        clientScript = `<script type="module" src="/assets/client.js"></script>`;
+      }
+    }
+    const headTags = this.templateParser.buildHeadTags(head);
+    let html = template.replace("<!--app-html-->", appHtml);
+    html = html.replace("<!--initial-state-->", initialStateScript);
+    html = html.replace("<!--client-scripts-->", clientScript);
+    html = html.replace("<!--styles-->", styles);
+    html = html.replace("<!--head-meta-->", headTags);
+    if (context.isDevelopment) {
+      const duration = Date.now() - startTime;
+      const name = typeof viewComponent === "function" ? viewComponent.name : String(viewComponent);
+      this.logger.log(`[SSR] ${name} rendered in ${duration}ms (string mode)`);
+    }
+    return html;
+  }
+  /**
+  * Render a segment for client-side navigation.
+  * Returns just the HTML and metadata without the full page template.
+  */
+  async renderSegment(viewComponent, data, context, swapTarget, head) {
+    const startTime = Date.now();
+    let renderModule;
+    if (context.vite) {
+      renderModule = await context.vite.ssrLoadModule(context.entryServerPath);
+    } else {
+      if (context.serverManifest) {
+        const manifestEntry = Object.entries(context.serverManifest).find(([key, value]) => value.isEntry && key.includes("entry-server"));
+        if (manifestEntry) {
+          const [, entry] = manifestEntry;
+          const serverPath = `${process.cwd()}/dist/server/${entry.file}`;
+          renderModule = await import(serverPath);
+        } else {
+          throw new Error("Server bundle not found in manifest. Run `pnpm build:server` to generate the server bundle.");
+        }
+      } else {
+        throw new Error("Server bundle not found in manifest. Run `pnpm build:server` to generate the server bundle.");
+      }
+    }
+    const { data: pageData, __context: pageContext } = data;
+    const html = await renderModule.renderSegment(viewComponent, data);
+    const componentName = viewComponent.displayName || viewComponent.name || "Component";
+    if (context.isDevelopment) {
+      const duration = Date.now() - startTime;
+      this.logger.log(`[SSR] ${componentName} segment rendered in ${duration}ms`);
+    }
+    return {
+      html,
+      head,
+      props: pageData,
+      swapTarget,
+      componentName,
+      context: pageContext
+    };
+  }
+};
+StringRenderer = _ts_decorate2([
+  Injectable(),
+  _ts_metadata("design:type", Function),
+  _ts_metadata("design:paramtypes", [
+    typeof TemplateParserService === "undefined" ? Object : TemplateParserService
+  ])
+], StringRenderer);
 function ErrorPageDevelopment({ error, viewPath, phase }) {
   const stackLines = error.stack ? error.stack.split("\n").slice(1) : [];
   return /* @__PURE__ */ React.createElement("html", {
@@ -300,17 +447,17 @@ function ErrorPageProduction() {
 __name(ErrorPageProduction, "ErrorPageProduction");
 
 // src/render/streaming-error-handler.ts
-function _ts_decorate2(decorators, target, key, desc) {
+function _ts_decorate3(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
   else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
-__name(_ts_decorate2, "_ts_decorate");
-function _ts_metadata(k, v) {
+__name(_ts_decorate3, "_ts_decorate");
+function _ts_metadata2(k, v) {
   if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
-__name(_ts_metadata, "_ts_metadata");
+__name(_ts_metadata2, "_ts_metadata");
 function _ts_param(paramIndex, decorator) {
   return function(target, key) {
     decorator(target, key, paramIndex);
@@ -334,6 +481,14 @@ var StreamingErrorHandler = class _StreamingErrorHandler {
   */
   handleShellError(error, res, viewPath, isDevelopment) {
     this.logger.error(`Shell error rendering ${viewPath}: ${error.message}`, error.stack);
+    if (res.headersSent) {
+      this.logger.error(`Cannot send error page for ${viewPath} - headers already sent (streaming started)`);
+      if (!res.writableEnded) {
+        res.write(this.renderInlineErrorOverlay(error, viewPath, isDevelopment));
+        res.end();
+      }
+      return;
+    }
     res.statusCode = 500;
     res.setHeader("Content-Type", "text/html; charset=utf-8");
     if (isDevelopment) {
@@ -369,32 +524,263 @@ var StreamingErrorHandler = class _StreamingErrorHandler {
     const element = createElement(ErrorComponent);
     return "<!DOCTYPE html>\n" + renderToStaticMarkup(element);
   }
+  /**
+  * Render inline error overlay for when headers are already sent
+  * This gets injected into the stream to show a visible error UI
+  */
+  renderInlineErrorOverlay(error, viewPath, isDevelopment) {
+    const errorMessage = escapeHtml(error.message);
+    const errorStack = escapeHtml(error.stack || "");
+    const escapedViewPath = escapeHtml(viewPath);
+    if (isDevelopment) {
+      return `
+<div id="ssr-error-overlay" style="
+  position: fixed;
+  inset: 0;
+  z-index: 99999;
+  background: rgba(0, 0, 0, 0.85);
+  color: #fff;
+  font-family: ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, monospace;
+  font-size: 14px;
+  padding: 32px;
+  overflow: auto;
+">
+  <div style="max-width: 900px; margin: 0 auto;">
+    <div style="display: flex; align-items: center; gap: 12px; margin-bottom: 24px;">
+      <span style="font-size: 32px;">\u26A0\uFE0F</span>
+      <h1 style="margin: 0; font-size: 24px; font-weight: 600; color: #ff6b6b;">
+        SSR Streaming Error
+      </h1>
+    </div>
+    <p style="color: #aaa; margin-bottom: 16px;">
+      An error occurred after streaming started in <code style="background: #333; padding: 2px 6px; border-radius: 4px;">${escapedViewPath}</code>
+    </p>
+    <div style="background: #1a1a1a; border: 1px solid #333; border-radius: 8px; padding: 16px; margin-bottom: 16px;">
+      <div style="color: #ff6b6b; font-weight: 600; margin-bottom: 8px;">Error Message:</div>
+      <pre style="margin: 0; white-space: pre-wrap; word-break: break-word; color: #fff;">${errorMessage}</pre>
+    </div>
+    <div style="background: #1a1a1a; border: 1px solid #333; border-radius: 8px; padding: 16px;">
+      <div style="color: #888; font-weight: 600; margin-bottom: 8px;">Stack Trace:</div>
+      <pre style="margin: 0; white-space: pre-wrap; word-break: break-word; color: #888; font-size: 12px;">${errorStack}</pre>
+    </div>
+    <button onclick="document.getElementById('ssr-error-overlay').remove()" style="
+      margin-top: 24px;
+      background: #333;
+      color: #fff;
+      border: 1px solid #555;
+      padding: 8px 16px;
+      border-radius: 6px;
+      cursor: pointer;
+      font-family: inherit;
+    ">Dismiss</button>
+  </div>
+</div>
+<script>console.error('SSR Streaming Error in ${escapedViewPath}:', ${uneval(error.message)});</script>
+`;
+    } else {
+      return `
+<div id="ssr-error-overlay" style="
+  position: fixed;
+  inset: 0;
+  z-index: 99999;
+  background: #fff;
+  color: #333;
+  font-family: system-ui, -apple-system, sans-serif;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  text-align: center;
+">
+  <div>
+    <h1 style="font-size: 24px; font-weight: 600; margin-bottom: 16px;">Something went wrong</h1>
+    <p style="color: #666; margin-bottom: 24px;">We're sorry, but something went wrong. Please try refreshing the page.</p>
+    <button onclick="location.reload()" style="
+      background: #333;
+      color: #fff;
+      border: none;
+      padding: 12px 24px;
+      border-radius: 6px;
+      cursor: pointer;
+      font-family: inherit;
+      font-size: 16px;
+    ">Refresh Page</button>
+  </div>
+</div>
+`;
+    }
+  }
 };
-StreamingErrorHandler = _ts_decorate2([
+StreamingErrorHandler = _ts_decorate3([
   Injectable(),
   _ts_param(0, Optional()),
   _ts_param(0, Inject("ERROR_PAGE_DEVELOPMENT")),
   _ts_param(1, Optional()),
   _ts_param(1, Inject("ERROR_PAGE_PRODUCTION")),
-  _ts_metadata("design:type", Function),
-  _ts_metadata("design:paramtypes", [
+  _ts_metadata2("design:type", Function),
+  _ts_metadata2("design:paramtypes", [
     typeof ComponentType === "undefined" ? Object : ComponentType,
     typeof ComponentType === "undefined" ? Object : ComponentType
   ])
 ], StreamingErrorHandler);
 
+// src/render/renderers/stream-renderer.ts
+function _ts_decorate4(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate4, "_ts_decorate");
+function _ts_metadata3(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+__name(_ts_metadata3, "_ts_metadata");
+var StreamRenderer = class _StreamRenderer {
+  static {
+    __name(this, "StreamRenderer");
+  }
+  templateParser;
+  streamingErrorHandler;
+  logger = new Logger(_StreamRenderer.name);
+  constructor(templateParser, streamingErrorHandler) {
+    this.templateParser = templateParser;
+    this.streamingErrorHandler = streamingErrorHandler;
+  }
+  /**
+  * Render a React component using streaming SSR
+  *
+  * @param viewComponent - The React component to render
+  * @param data - Data to pass to the component
+  * @param res - Express response object (required for streaming)
+  * @param context - Render context with Vite and manifest info
+  * @param head - Head data for SEO tags
+  */
+  async render(viewComponent, data, res, context, head) {
+    const startTime = Date.now();
+    let shellReadyTime = 0;
+    return new Promise((resolve, reject) => {
+      const executeStream = /* @__PURE__ */ __name(async () => {
+        let template = context.template;
+        if (context.vite) {
+          template = await context.vite.transformIndexHtml("/", template);
+        }
+        const templateParts = this.templateParser.parseTemplate(template);
+        let renderModule;
+        if (context.vite) {
+          renderModule = await context.vite.ssrLoadModule(context.entryServerPath);
+        } else {
+          if (context.serverManifest) {
+            const manifestEntry = Object.entries(context.serverManifest).find(([key, value]) => value.isEntry && key.includes("entry-server"));
+            if (manifestEntry) {
+              const [, entry] = manifestEntry;
+              const serverPath = `${process.cwd()}/dist/server/${entry.file}`;
+              renderModule = await import(serverPath);
+            } else {
+              throw new Error("Server bundle not found in manifest. Run `pnpm build:server` to generate the server bundle.");
+            }
+          } else {
+            throw new Error("Server bundle not found in manifest. Run `pnpm build:server` to generate the server bundle.");
+          }
+        }
+        const { data: pageData, __context: pageContext, __layouts: layouts } = data;
+        const componentName = viewComponent.displayName || viewComponent.name || "Component";
+        const inlineScripts = this.templateParser.buildInlineScripts(pageData, pageContext, componentName, layouts);
+        const clientScript = this.templateParser.getClientScriptTag(context.isDevelopment, context.manifest);
+        const stylesheetTags = this.templateParser.getStylesheetTags(context.isDevelopment, context.manifest);
+        const headTags = this.templateParser.buildHeadTags(head);
+        let didError = false;
+        let shellErrorOccurred = false;
+        const { PassThrough } = await import('stream');
+        const reactStream = new PassThrough();
+        let allReadyFired = false;
+        const { pipe, abort } = renderModule.renderComponentStream(viewComponent, data, {
+          onShellReady: /* @__PURE__ */ __name(() => {
+            shellReadyTime = Date.now();
+            if (!res.headersSent) {
+              res.statusCode = didError ? 500 : 200;
+              res.setHeader("Content-Type", "text/html; charset=utf-8");
+            }
+            let htmlStart = templateParts.htmlStart;
+            htmlStart = htmlStart.replace("<!--styles-->", stylesheetTags);
+            htmlStart = htmlStart.replace("<!--head-meta-->", headTags);
+            res.write(htmlStart);
+            res.write(templateParts.rootStart);
+            pipe(reactStream);
+            reactStream.pipe(res, {
+              end: false
+            });
+            if (context.isDevelopment) {
+              const ttfb = shellReadyTime - startTime;
+              this.logger.log(`[SSR] ${componentName} shell ready in ${ttfb}ms (stream mode - TTFB)`);
+            }
+          }, "onShellReady"),
+          onShellError: /* @__PURE__ */ __name((error) => {
+            shellErrorOccurred = true;
+            this.streamingErrorHandler.handleShellError(error, res, componentName, context.isDevelopment);
+            resolve();
+          }, "onShellError"),
+          onError: /* @__PURE__ */ __name((error) => {
+            didError = true;
+            this.streamingErrorHandler.handleStreamError(error, componentName);
+          }, "onError"),
+          onAllReady: /* @__PURE__ */ __name(() => {
+            allReadyFired = true;
+          }, "onAllReady")
+        });
+        reactStream.on("end", () => {
+          if (shellErrorOccurred) {
+            return;
+          }
+          res.write(inlineScripts);
+          res.write(clientScript);
+          res.write(templateParts.rootEnd);
+          res.write(templateParts.htmlEnd);
+          res.end();
+          if (context.isDevelopment) {
+            const totalTime = Date.now() - startTime;
+            const streamTime = Date.now() - shellReadyTime;
+            const viaAllReady = allReadyFired ? " (onAllReady fired)" : " (onAllReady never fired)";
+            this.logger.log(`[SSR] ${componentName} streaming complete in ${totalTime}ms total (${streamTime}ms streaming)${viaAllReady}`);
+          }
+          resolve();
+        });
+        reactStream.on("error", (error) => {
+          reject(error);
+        });
+        res.on("close", () => {
+          abort();
+          resolve();
+        });
+      }, "executeStream");
+      executeStream().catch((error) => {
+        const componentName = typeof viewComponent === "function" ? viewComponent.name : String(viewComponent);
+        this.streamingErrorHandler.handleShellError(error, res, componentName, context.isDevelopment);
+        resolve();
+      });
+    });
+  }
+};
+StreamRenderer = _ts_decorate4([
+  Injectable(),
+  _ts_metadata3("design:type", Function),
+  _ts_metadata3("design:paramtypes", [
+    typeof TemplateParserService === "undefined" ? Object : TemplateParserService,
+    typeof StreamingErrorHandler === "undefined" ? Object : StreamingErrorHandler
+  ])
+], StreamRenderer);
+
 // src/render/render.service.ts
-function _ts_decorate3(decorators, target, key, desc) {
+function _ts_decorate5(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
   else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
-__name(_ts_decorate3, "_ts_decorate");
-function _ts_metadata2(k, v) {
+__name(_ts_decorate5, "_ts_decorate");
+function _ts_metadata4(k, v) {
   if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
-__name(_ts_metadata2, "_ts_metadata");
+__name(_ts_metadata4, "_ts_metadata");
 function _ts_param2(paramIndex, decorator) {
   return function(target, key) {
     decorator(target, key, paramIndex);
@@ -405,8 +791,8 @@ var RenderService = class _RenderService {
   static {
     __name(this, "RenderService");
   }
-  templateParser;
-  streamingErrorHandler;
+  stringRenderer;
+  streamRenderer;
   defaultHead;
   logger = new Logger(_RenderService.name);
   vite = null;
@@ -418,12 +804,12 @@ var RenderService = class _RenderService {
   entryServerPath;
   rootLayout = void 0;
   rootLayoutChecked = false;
-  constructor(templateParser, streamingErrorHandler, ssrMode, defaultHead, customTemplate) {
-    this.templateParser = templateParser;
-    this.streamingErrorHandler = streamingErrorHandler;
+  constructor(stringRenderer, streamRenderer, ssrMode, defaultHead, customTemplate) {
+    this.stringRenderer = stringRenderer;
+    this.streamRenderer = streamRenderer;
     this.defaultHead = defaultHead;
     this.isDevelopment = process.env.NODE_ENV !== "production";
-    this.ssrMode = ssrMode || process.env.SSR_MODE || "stream";
+    this.ssrMode = ssrMode || process.env.SSR_MODE || "string";
     const absoluteServerPath = join(__dirname, "/templates/entry-server.tsx");
     const relativeServerPath = relative(process.cwd(), absoluteServerPath);
     if (relativeServerPath.startsWith("..")) {
@@ -431,67 +817,82 @@ var RenderService = class _RenderService {
     } else {
       this.entryServerPath = "/" + relativeServerPath.replace(/\\/g, "/");
     }
+    this.template = this.loadTemplate(customTemplate);
+    if (!this.isDevelopment) {
+      this.loadManifests();
+    }
+  }
+  /**
+  * Load HTML template from custom path, package, or local location
+  */
+  loadTemplate(customTemplate) {
     if (customTemplate) {
-      if (customTemplate.includes("<!DOCTYPE") || customTemplate.includes("<html")) {
-        this.template = customTemplate;
-        this.logger.log(`\u2713 Loaded custom template (inline)`);
+      return this.loadCustomTemplate(customTemplate);
+    }
+    return this.loadDefaultTemplate();
+  }
+  loadCustomTemplate(customTemplate) {
+    if (customTemplate.includes("<!DOCTYPE") || customTemplate.includes("<html")) {
+      this.logger.log(`\u2713 Loaded custom template (inline)`);
+      return customTemplate;
+    }
+    const customTemplatePath = customTemplate.startsWith("/") ? customTemplate : join(process.cwd(), customTemplate);
+    if (!existsSync(customTemplatePath)) {
+      throw new Error(`Custom template file not found at ${customTemplatePath}`);
+    }
+    try {
+      const template = readFileSync(customTemplatePath, "utf-8");
+      this.logger.log(`\u2713 Loaded custom template from ${customTemplatePath}`);
+      return template;
+    } catch (error) {
+      throw new Error(`Failed to read custom template file at ${customTemplatePath}: ${error.message}`);
+    }
+  }
+  loadDefaultTemplate() {
+    let templatePath;
+    if (this.isDevelopment) {
+      const packageTemplatePaths = [
+        join(__dirname, "../templates/index.html"),
+        join(__dirname, "../src/templates/index.html"),
+        join(__dirname, "../../src/templates/index.html")
+      ];
+      const localTemplatePath = join(process.cwd(), "src/views/index.html");
+      const foundPackageTemplate = packageTemplatePaths.find((p) => existsSync(p));
+      if (foundPackageTemplate) {
+        templatePath = foundPackageTemplate;
+      } else if (existsSync(localTemplatePath)) {
+        templatePath = localTemplatePath;
       } else {
-        const customTemplatePath = customTemplate.startsWith("/") ? customTemplate : join(process.cwd(), customTemplate);
-        if (!existsSync(customTemplatePath)) {
-          throw new Error(`Custom template file not found at ${customTemplatePath}`);
-        }
-        try {
-          this.template = readFileSync(customTemplatePath, "utf-8");
-          this.logger.log(`\u2713 Loaded custom template from ${customTemplatePath}`);
-        } catch (error) {
-          throw new Error(`Failed to read custom template file at ${customTemplatePath}: ${error.message}`);
-        }
-      }
-    } else {
-      let templatePath;
-      if (this.isDevelopment) {
-        const packageTemplatePaths = [
-          join(__dirname, "../templates/index.html"),
-          join(__dirname, "../src/templates/index.html"),
-          join(__dirname, "../../src/templates/index.html")
-        ];
-        const localTemplatePath = join(process.cwd(), "src/views/index.html");
-        const foundPackageTemplate = packageTemplatePaths.find((p) => existsSync(p));
-        if (foundPackageTemplate) {
-          templatePath = foundPackageTemplate;
-        } else if (existsSync(localTemplatePath)) {
-          templatePath = localTemplatePath;
-        } else {
-          throw new Error(`Template file not found. Tried:
+        throw new Error(`Template file not found. Tried:
 ` + packageTemplatePaths.map((p) => `  - ${p} (package template)`).join("\n") + `
   - ${localTemplatePath} (local template)`);
-        }
-      } else {
-        templatePath = join(process.cwd(), "dist/client/index.html");
-        if (!existsSync(templatePath)) {
-          throw new Error(`Template file not found at ${templatePath}. Make sure to run the build process first.`);
-        }
       }
-      try {
-        this.template = readFileSync(templatePath, "utf-8");
-        this.logger.log(`\u2713 Loaded template from ${templatePath}`);
-      } catch (error) {
-        throw new Error(`Failed to read template file at ${templatePath}: ${error.message}`);
+    } else {
+      templatePath = join(process.cwd(), "dist/client/index.html");
+      if (!existsSync(templatePath)) {
+        throw new Error(`Template file not found at ${templatePath}. Make sure to run the build process first.`);
       }
     }
-    if (!this.isDevelopment) {
-      const manifestPath = join(process.cwd(), "dist/client/.vite/manifest.json");
-      if (existsSync(manifestPath)) {
-        this.manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
-      } else {
-        this.logger.warn("\u26A0\uFE0F  Client manifest not found. Run `pnpm build:client` first.");
-      }
-      const serverManifestPath = join(process.cwd(), "dist/server/.vite/manifest.json");
-      if (existsSync(serverManifestPath)) {
-        this.serverManifest = JSON.parse(readFileSync(serverManifestPath, "utf-8"));
-      } else {
-        this.logger.warn("\u26A0\uFE0F  Server manifest not found. Run `pnpm build:server` first.");
-      }
+    try {
+      const template = readFileSync(templatePath, "utf-8");
+      this.logger.log(`\u2713 Loaded template from ${templatePath}`);
+      return template;
+    } catch (error) {
+      throw new Error(`Failed to read template file at ${templatePath}: ${error.message}`);
+    }
+  }
+  loadManifests() {
+    const manifestPath = join(process.cwd(), "dist/client/.vite/manifest.json");
+    if (existsSync(manifestPath)) {
+      this.manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+    } else {
+      this.logger.warn("\u26A0\uFE0F  Client manifest not found. Run `pnpm build:client` first.");
+    }
+    const serverManifestPath = join(process.cwd(), "dist/server/.vite/manifest.json");
+    if (existsSync(serverManifestPath)) {
+      this.serverManifest = JSON.parse(readFileSync(serverManifestPath, "utf-8"));
+    } else {
+      this.logger.warn("\u26A0\uFE0F  Server manifest not found. Run `pnpm build:server` first.");
     }
   }
   setViteServer(vite) {
@@ -545,16 +946,50 @@ var RenderService = class _RenderService {
   }
   /**
   * Main render method that routes to string or stream mode
+  *
+  * String mode (default):
+  * - Returns complete HTML string
+  * - Atomic responses - works completely or fails completely
+  * - Proper HTTP status codes always
+  *
+  * Stream mode:
+  * - Writes directly to response
+  * - Better TTFB, progressive rendering
+  * - Requires response object
   */
   async render(viewComponent, data = {}, res, head) {
     const mergedHead = this.mergeHead(this.defaultHead, head);
+    const renderContext = {
+      template: this.template,
+      vite: this.vite,
+      manifest: this.manifest,
+      serverManifest: this.serverManifest,
+      entryServerPath: this.entryServerPath,
+      isDevelopment: this.isDevelopment
+    };
     if (this.ssrMode === "stream") {
       if (!res) {
         throw new Error("Response object is required for streaming SSR mode. Pass res as third parameter.");
       }
-      return this.renderToStream(viewComponent, data, res, mergedHead);
+      return this.streamRenderer.render(viewComponent, data, res, renderContext, mergedHead);
     }
-    return this.renderToString(viewComponent, data, mergedHead);
+    return this.stringRenderer.render(viewComponent, data, renderContext, mergedHead);
+  }
+  /**
+  * Render a segment for client-side navigation.
+  * Always uses string mode (streaming not supported for segments).
+  */
+  async renderSegment(viewComponent, data, swapTarget, head) {
+    const mergedHead = this.mergeHead(this.defaultHead, head);
+    const renderContext = {
+      template: this.template,
+      vite: this.vite,
+      manifest: this.manifest,
+      serverManifest: this.serverManifest,
+      entryServerPath: this.entryServerPath,
+      isDevelopment: this.isDevelopment
+    };
+    return this.stringRenderer.renderSegment(viewComponent, data, renderContext, swapTarget, mergedHead);
   }
   /**
   * Merge default head with page-specific head
@@ -567,7 +1002,6 @@ var RenderService = class _RenderService {
     return {
       ...defaultHead,
       ...pageHead,
-      // Merge arrays (links and meta) instead of replacing
       links: [
         ...defaultHead?.links || [],
         ...pageHead?.links || []
@@ -578,198 +1012,8 @@ var RenderService = class _RenderService {
       ]
     };
   }
-  /**
-  * Traditional string-based SSR using renderToString
-  */
-  async renderToString(viewComponent, data = {}, head) {
-    const startTime = Date.now();
-    try {
-      let template = this.template;
-      if (this.vite) {
-        template = await this.vite.transformIndexHtml("/", template);
-      }
-      let renderModule;
-      if (this.vite) {
-        renderModule = await this.vite.ssrLoadModule(this.entryServerPath);
-      } else {
-        if (this.serverManifest) {
-          const manifestEntry = Object.entries(this.serverManifest).find(([key, value]) => value.isEntry && key.includes("entry-server"));
-          if (manifestEntry) {
-            const [, entry] = manifestEntry;
-            const serverPath = join(process.cwd(), "dist/server", entry.file);
-            renderModule = await import(serverPath);
-          } else {
-            throw new Error("Server bundle not found in manifest. Run `pnpm build:server` to generate the server bundle.");
-          }
-        } else {
-          throw new Error("Server bundle not found in manifest. Run `pnpm build:server` to generate the server bundle.");
-        }
-      }
-      const { data: pageData, __context: context, __layouts: layouts } = data;
-      const appHtml = await renderModule.renderComponent(viewComponent, data);
-      const componentName = viewComponent.displayName || viewComponent.name || "Component";
-      const layoutMetadata = layouts ? layouts.map((l) => ({
-        name: l.layout.displayName || l.layout.name || "default",
-        props: l.props
-      })) : [];
-      const initialStateScript = `
-        <script>
-          window.__INITIAL_STATE__ = ${uneval(pageData)};
-          window.__CONTEXT__ = ${uneval(context)};
-          window.__COMPONENT_NAME__ = ${uneval(componentName)};
-          window.__LAYOUTS__ = ${uneval(layoutMetadata)};
-        </script>
-      `;
-      let clientScript = "";
-      let styles = "";
-      if (this.vite) {
-        clientScript = `<script type="module" src="/src/views/entry-client.tsx"></script>`;
-        styles = "";
-      } else {
-        if (this.manifest) {
-          const manifestEntry = Object.entries(this.manifest).find(([key, value]) => value.isEntry && key.includes("entry-client"));
-          if (manifestEntry) {
-            const [, entry] = manifestEntry;
-            const entryFile = entry.file;
-            clientScript = `<script type="module" src="/${entryFile}"></script>`;
-            if (entry.css) {
-              const cssFiles = entry.css;
-              styles = cssFiles.map((css) => `<link rel="stylesheet" href="/${css}" />`).join("\n    ");
-            }
-          } else {
-            this.logger.error("\u26A0\uFE0F  Client entry not found in manifest");
-            clientScript = `<script type="module" src="/assets/client.js"></script>`;
-          }
-        } else {
-          this.logger.error("\u26A0\uFE0F  Client manifest not found");
-          clientScript = `<script type="module" src="/assets/client.js"></script>`;
-        }
-      }
-      const headTags = this.templateParser.buildHeadTags(head);
-      let html = template.replace("<!--app-html-->", appHtml);
-      html = html.replace("<!--initial-state-->", initialStateScript);
-      html = html.replace("<!--client-scripts-->", clientScript);
-      html = html.replace("<!--styles-->", styles);
-      html = html.replace("<!--head-meta-->", headTags);
-      if (this.isDevelopment) {
-        const duration = Date.now() - startTime;
-        const componentName2 = typeof viewComponent === "function" ? viewComponent.name : String(viewComponent);
-        this.logger.log(`[SSR] ${componentName2} rendered in ${duration}ms (string mode)`);
-      }
-      return html;
-    } catch (error) {
-      throw error;
-    }
-  }
-  /**
-  * Modern streaming SSR using renderToPipeableStream
-  */
-  async renderToStream(viewComponent, data = {}, res, head) {
-    const startTime = Date.now();
-    let shellReadyTime = 0;
-    return new Promise((resolve, reject) => {
-      const executeStream = /* @__PURE__ */ __name(async () => {
-        let template = this.template;
-        if (this.vite) {
-          template = await this.vite.transformIndexHtml("/", template);
-        }
-        const templateParts = this.templateParser.parseTemplate(template);
-        let renderModule;
-        if (this.vite) {
-          renderModule = await this.vite.ssrLoadModule(this.entryServerPath);
-        } else {
-          if (this.serverManifest) {
-            const manifestEntry = Object.entries(this.serverManifest).find(([key, value]) => value.isEntry && key.includes("entry-server"));
-            if (manifestEntry) {
-              const [, entry] = manifestEntry;
-              const serverPath = join(process.cwd(), "dist/server", entry.file);
-              renderModule = await import(serverPath);
-            } else {
-              throw new Error("Server bundle not found in manifest. Run `pnpm build:server` to generate the server bundle.");
-            }
-          } else {
-            throw new Error("Server bundle not found in manifest. Run `pnpm build:server` to generate the server bundle.");
-          }
-        }
-        const { data: pageData, __context: context, __layouts: layouts } = data;
-        const componentName = viewComponent.displayName || viewComponent.name || "Component";
-        const inlineScripts = this.templateParser.buildInlineScripts(pageData, context, componentName, layouts);
-        const clientScript = this.templateParser.getClientScriptTag(this.isDevelopment, this.manifest);
-        const stylesheetTags = this.templateParser.getStylesheetTags(this.isDevelopment, this.manifest);
-        const headTags = this.templateParser.buildHeadTags(head);
-        let didError = false;
-        let shellErrorOccurred = false;
-        const { PassThrough } = await import('stream');
-        const reactStream = new PassThrough();
-        let allReadyFired = false;
-        const { pipe, abort } = renderModule.renderComponentStream(viewComponent, data, {
-          onShellReady: /* @__PURE__ */ __name(() => {
-            shellReadyTime = Date.now();
-            if (!res.headersSent) {
-              res.statusCode = didError ? 500 : 200;
-              res.setHeader("Content-Type", "text/html; charset=utf-8");
-            }
-            let htmlStart = templateParts.htmlStart;
-            htmlStart = htmlStart.replace("<!--styles-->", stylesheetTags);
-            htmlStart = htmlStart.replace("<!--head-meta-->", headTags);
-            res.write(htmlStart);
-            res.write(templateParts.rootStart);
-            pipe(reactStream);
-            reactStream.pipe(res, {
-              end: false
-            });
-            if (this.isDevelopment) {
-              const ttfb = shellReadyTime - startTime;
-              this.logger.log(`[SSR] ${componentName} shell ready in ${ttfb}ms (stream mode - TTFB)`);
-            }
-          }, "onShellReady"),
-          onShellError: /* @__PURE__ */ __name((error) => {
-            shellErrorOccurred = true;
-            this.streamingErrorHandler.handleShellError(error, res, componentName, this.isDevelopment);
-            resolve();
-          }, "onShellError"),
-          onError: /* @__PURE__ */ __name((error) => {
-            didError = true;
-            this.streamingErrorHandler.handleStreamError(error, componentName);
-          }, "onError"),
-          onAllReady: /* @__PURE__ */ __name(() => {
-            allReadyFired = true;
-          }, "onAllReady")
-        });
-        reactStream.on("end", () => {
-          if (shellErrorOccurred) {
-            return;
-          }
-          res.write(inlineScripts);
-          res.write(clientScript);
-          res.write(templateParts.rootEnd);
-          res.write(templateParts.htmlEnd);
-          res.end();
-          if (this.isDevelopment) {
-            const totalTime = Date.now() - startTime;
-            const streamTime = Date.now() - shellReadyTime;
-            const viaAllReady = allReadyFired ? " (onAllReady fired)" : " (onAllReady never fired)";
-            this.logger.log(`[SSR] ${componentName} streaming complete in ${totalTime}ms total (${streamTime}ms streaming)${viaAllReady}`);
-          }
-          resolve();
-        });
-        reactStream.on("error", (error) => {
-          reject(error);
-        });
-        res.on("close", () => {
-          abort();
-          resolve();
-        });
-      }, "executeStream");
-      executeStream().catch((error) => {
-        const componentName = typeof viewComponent === "function" ? viewComponent.name : String(viewComponent);
-        this.streamingErrorHandler.handleShellError(error, res, componentName, this.isDevelopment);
-        resolve();
-      });
-    });
-  }
 };
-RenderService = _ts_decorate3([
+RenderService = _ts_decorate5([
   Injectable(),
   _ts_param2(2, Optional()),
   _ts_param2(2, Inject("SSR_MODE")),
@@ -777,10 +1021,10 @@ RenderService = _ts_decorate3([
   _ts_param2(3, Inject("DEFAULT_HEAD")),
   _ts_param2(4, Optional()),
   _ts_param2(4, Inject("CUSTOM_TEMPLATE")),
-  _ts_metadata2("design:type", Function),
-  _ts_metadata2("design:paramtypes", [
-    typeof TemplateParserService === "undefined" ? Object : TemplateParserService,
-    typeof StreamingErrorHandler === "undefined" ? Object : StreamingErrorHandler,
+  _ts_metadata4("design:type", Function),
+  _ts_metadata4("design:paramtypes", [
+    typeof StringRenderer === "undefined" ? Object : StringRenderer,
+    typeof StreamRenderer === "undefined" ? Object : StreamRenderer,
     typeof SSRMode === "undefined" ? Object : SSRMode,
     typeof HeadData === "undefined" ? Object : HeadData,
     String
@@ -791,17 +1035,17 @@ var RENDER_OPTIONS_KEY = "render_options";
 var LAYOUT_KEY = "layout";
 
 // src/render/render.interceptor.ts
-function _ts_decorate4(decorators, target, key, desc) {
+function _ts_decorate6(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
   else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
-__name(_ts_decorate4, "_ts_decorate");
-function _ts_metadata3(k, v) {
+__name(_ts_decorate6, "_ts_decorate");
+function _ts_metadata5(k, v) {
   if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
-__name(_ts_metadata3, "_ts_metadata");
+__name(_ts_metadata5, "_ts_metadata");
 function _ts_param3(paramIndex, decorator) {
   return function(target, key) {
     decorator(target, key, paramIndex);
@@ -851,15 +1095,20 @@ var RenderInterceptor = class {
     } else if (renderOptions?.layout === false) {
       return layouts;
     }
-    if (controllerLayoutMeta) {
-      const mergedProps = {
-        ...controllerLayoutMeta.options?.props || {},
-        ...dynamicLayoutProps || {}
-      };
-      layouts.push({
-        layout: controllerLayoutMeta.layout,
-        props: mergedProps
-      });
+    if (controllerLayoutMeta?.layout) {
+      const rootLayoutName = rootLayout?.displayName || rootLayout?.name;
+      const controllerLayoutName = controllerLayoutMeta.layout.displayName || controllerLayoutMeta.layout.name;
+      const isDuplicateOfRoot = rootLayout && rootLayoutName && controllerLayoutName === rootLayoutName;
+      if (!isDuplicateOfRoot) {
+        const mergedProps = {
+          ...controllerLayoutMeta.options?.props || {},
+          ...dynamicLayoutProps || {}
+        };
+        layouts.push({
+          layout: controllerLayoutMeta.layout,
+          props: mergedProps
+        });
+      }
     }
     if (renderOptions?.layout) {
       const mergedProps = {
@@ -873,6 +1122,53 @@ var RenderInterceptor = class {
     }
     return layouts;
   }
+  /**
+  * Detect request type based on headers.
+  * - If X-Current-Layouts header is present, this is a segment request
+  * - Only GET requests can be segments
+  */
+  detectRequestType(request) {
+    if (request.method !== "GET") {
+      return {
+        type: "full"
+      };
+    }
+    const layoutsHeader = request.headers["x-current-layouts"];
+    if (layoutsHeader && typeof layoutsHeader === "string") {
+      const currentLayouts = layoutsHeader.split(",").map((s) => s.trim());
+      return {
+        type: "segment",
+        currentLayouts
+      };
+    }
+    return {
+      type: "full"
+    };
+  }
+  /**
+  * Determine swap target by finding deepest common layout.
+  * Returns null if no common ancestor (client should do full navigation).
+  */
+  determineSwapTarget(currentLayouts, targetLayouts) {
+    const targetNames = targetLayouts.map((l) => l.layout.displayName || l.layout.name);
+    let commonLayout = null;
+    for (let i = 0; i < Math.min(currentLayouts.length, targetNames.length); i++) {
+      if (currentLayouts[i] === targetNames[i]) {
+        commonLayout = currentLayouts[i];
+      } else {
+        break;
+      }
+    }
+    return commonLayout;
+  }
+  /**
+  * Filter layouts to only include those below the swap target.
+  * The swap target's outlet will contain the filtered layouts.
+  */
+  filterLayoutsFromSwapTarget(layouts, swapTarget) {
+    const index = layouts.findIndex((l) => (l.layout.displayName || l.layout.name) === swapTarget);
+    return index >= 0 ? layouts.slice(index + 1) : layouts;
+  }
   intercept(context, next) {
     const viewPathOrComponent = this.reflector.get(RENDER_KEY, context.getHandler());
     if (!viewPathOrComponent) {
@@ -921,6 +1217,24 @@ var RenderInterceptor = class {
         __context: renderContext,
         __layouts: layoutChain
       };
+      const { type, currentLayouts } = this.detectRequestType(request);
+      if (type === "segment" && currentLayouts) {
+        const swapTarget = this.determineSwapTarget(currentLayouts, layoutChain);
+        if (!swapTarget) {
+          response.type("application/json");
+          return {
+            swapTarget: null
+          };
+        }
+        const filteredLayouts = this.filterLayoutsFromSwapTarget(layoutChain, swapTarget);
+        const segmentData = {
+          ...fullData,
+          __layouts: filteredLayouts
+        };
+        const result = await this.renderService.renderSegment(viewPathOrComponent, segmentData, swapTarget, renderResponse.head);
+        response.type("application/json");
+        return result;
+      }
       try {
         const html = await this.renderService.render(viewPathOrComponent, fullData, response, renderResponse.head);
         if (html !== void 0) {
@@ -934,31 +1248,31 @@ var RenderInterceptor = class {
     }));
   }
 };
-RenderInterceptor = _ts_decorate4([
+RenderInterceptor = _ts_decorate6([
   Injectable(),
   _ts_param3(2, Optional()),
   _ts_param3(2, Inject("ALLOWED_HEADERS")),
   _ts_param3(3, Optional()),
   _ts_param3(3, Inject("ALLOWED_COOKIES")),
-  _ts_metadata3("design:type", Function),
-  _ts_metadata3("design:paramtypes", [
+  _ts_metadata5("design:type", Function),
+  _ts_metadata5("design:paramtypes", [
     typeof Reflector === "undefined" ? Object : Reflector,
     typeof RenderService === "undefined" ? Object : RenderService,
     Array,
     Array
   ])
 ], RenderInterceptor);
-function _ts_decorate5(decorators, target, key, desc) {
+function _ts_decorate7(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
   else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
-__name(_ts_decorate5, "_ts_decorate");
-function _ts_metadata4(k, v) {
+__name(_ts_decorate7, "_ts_decorate");
+function _ts_metadata6(k, v) {
   if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
-__name(_ts_metadata4, "_ts_metadata");
+__name(_ts_metadata6, "_ts_metadata");
 function _ts_param4(paramIndex, decorator) {
   return function(target, key) {
     decorator(target, key, paramIndex);
@@ -972,14 +1286,12 @@ var ViteInitializerService = class _ViteInitializerService {
   renderService;
   httpAdapterHost;
   logger = new Logger(_ViteInitializerService.name);
-  viteMode;
   vitePort;
   viteServer = null;
   isShuttingDown = false;
   constructor(renderService, httpAdapterHost, viteConfig) {
     this.renderService = renderService;
     this.httpAdapterHost = httpAdapterHost;
-    this.viteMode = viteConfig?.mode || "embedded";
     this.vitePort = viteConfig?.port || 5173;
     this.registerSignalHandlers();
   }
@@ -1011,30 +1323,12 @@ var ViteInitializerService = class _ViteInitializerService {
         appType: "custom"
       });
       this.renderService.setViteServer(this.viteServer);
-      if (this.viteMode === "embedded") {
-        await this.mountViteMiddleware(this.viteServer);
-      } else if (this.viteMode === "proxy") {
-        await this.setupViteProxy();
-      }
-      this.logger.log(`\u2713 Vite initialized for SSR (mode: ${this.viteMode})`);
+      await this.setupViteProxy();
+      this.logger.log("\u2713 Vite initialized for SSR");
     } catch (error) {
       this.logger.warn(`Failed to initialize Vite: ${error.message}. Make sure vite is installed.`);
     }
   }
-  async mountViteMiddleware(vite) {
-    try {
-      const httpAdapter = this.httpAdapterHost.httpAdapter;
-      if (!httpAdapter) {
-        this.logger.warn("HTTP adapter not available, skipping Vite middleware setup");
-        return;
-      }
-      const app = httpAdapter.getInstance();
-      app.use(vite.middlewares);
-      this.logger.log(`\u2713 Vite middleware mounted (embedded mode with HMR)`);
-    } catch (error) {
-      this.logger.warn(`Failed to mount Vite middleware: ${error.message}`);
-    }
-  }
   async setupViteProxy() {
     try {
       const httpAdapter = this.httpAdapterHost.httpAdapter;
@@ -1053,7 +1347,7 @@ var ViteInitializerService = class _ViteInitializerService {
         }, "pathFilter")
       });
       app.use(viteProxy);
-      this.logger.log(`\u2713 Vite HMR proxy configured (external Vite on port ${this.vitePort})`);
+      this.logger.log(`\u2713 Vite HMR proxy configured (Vite dev server on port ${this.vitePort})`);
     } catch (error) {
       this.logger.warn(`Failed to setup Vite proxy: ${error.message}. Make sure http-proxy-middleware is installed.`);
     }
@@ -1104,12 +1398,12 @@ var ViteInitializerService = class _ViteInitializerService {
     }
   }
 };
-ViteInitializerService = _ts_decorate5([
+ViteInitializerService = _ts_decorate7([
   Injectable(),
   _ts_param4(2, Optional()),
   _ts_param4(2, Inject("VITE_CONFIG")),
-  _ts_metadata4("design:type", Function),
-  _ts_metadata4("design:paramtypes", [
+  _ts_metadata6("design:type", Function),
+  _ts_metadata6("design:paramtypes", [
     typeof RenderService === "undefined" ? Object : RenderService,
     typeof HttpAdapterHost === "undefined" ? Object : HttpAdapterHost,
     typeof ViteConfig === "undefined" ? Object : ViteConfig
@@ -1117,13 +1411,13 @@ ViteInitializerService = _ts_decorate5([
 ], ViteInitializerService);
 
 // src/render/render.module.ts
-function _ts_decorate6(decorators, target, key, desc) {
+function _ts_decorate8(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
   else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
-__name(_ts_decorate6, "_ts_decorate");
+__name(_ts_decorate8, "_ts_decorate");
 var RenderModule = class _RenderModule {
   static {
     __name(this, "RenderModule");
@@ -1136,17 +1430,17 @@ var RenderModule = class _RenderModule {
   *
   * @example
   * ```ts
-  * // Zero config - uses defaults
+  * // Zero config - uses string mode (default, recommended)
   * RenderModule.forRoot()
   *
-  * // Enable streaming SSR
-  * RenderModule.forRoot({ mode: 'stream' })
-  *
-  * // Enable HMR with proxy mode
+  * // Custom Vite port
   * RenderModule.forRoot({
-  *   vite: { mode: 'proxy', port: 5173 }
+  *   vite: { port: 3001 }
   * })
   *
+  * // Enable streaming SSR (advanced - see mode docs for trade-offs)
+  * RenderModule.forRoot({ mode: 'stream' })
+  *
   * // Custom error pages
   * RenderModule.forRoot({
   *   errorPageDevelopment: DevErrorPage,
@@ -1160,6 +1454,8 @@ var RenderModule = class _RenderModule {
       TemplateParserService,
       StreamingErrorHandler,
       ViteInitializerService,
+      StringRenderer,
+      StreamRenderer,
       {
         provide: APP_INTERCEPTOR,
         useClass: RenderInterceptor
@@ -1264,6 +1560,8 @@ var RenderModule = class _RenderModule {
       TemplateParserService,
       StreamingErrorHandler,
       ViteInitializerService,
+      StringRenderer,
+      StreamRenderer,
       {
         provide: APP_INTERCEPTOR,
         useClass: RenderInterceptor
@@ -1348,7 +1646,7 @@ var RenderModule = class _RenderModule {
     return this.forRootAsync(options);
   }
 };
-RenderModule = _ts_decorate6([
+RenderModule = _ts_decorate8([
   Global(),
   Module({
     providers: [
@@ -1356,6 +1654,8 @@ RenderModule = _ts_decorate6([
       TemplateParserService,
       StreamingErrorHandler,
       ViteInitializerService,
+      StringRenderer,
+      StreamRenderer,
       {
         provide: APP_INTERCEPTOR,
         useClass: RenderInterceptor