@finesoft/front 0.1.30 → 0.1.31

package/dist/{app-O6QY6A43.js → app-IA6JQC7V.js}

@@ -1,10 +1,10 @@
 import {
   createSSRApp
-} from "./chunk-I32JEYQR.js";
-import "./chunk-N4AEOYUR.js";
+} from "./chunk-M7VITIMR.js";
+import "./chunk-ZMOE42LB.js";
 import "./chunk-BUYWNNNQ.js";
 import "./chunk-FYP2ZYYV.js";
 export {
   createSSRApp
 };
-//# sourceMappingURL=app-O6QY6A43.js.map
+//# sourceMappingURL=app-IA6JQC7V.js.map

package/dist/{chunk-I32JEYQR.js → chunk-M7VITIMR.js}

@@ -1,7 +1,7 @@
 import {
   injectCSRShell,
   injectSSRContent
-} from "./chunk-N4AEOYUR.js";
+} from "./chunk-ZMOE42LB.js";
 import {
   parseAcceptLanguage
 } from "./chunk-FYP2ZYYV.js";
@@ -10,24 +10,14 @@ import {
 import { Hono } from "hono";
 
 // ../server/src/internal-fetch.ts
-var MAX_INTERNAL_FETCH_DEPTH = 5;
-function createInternalFetch(appFetch) {
-  let depth = 0;
+var SSR_DEPTH_HEADER = "x-ssr-depth";
+var MAX_SSR_DEPTH = 5;
+function createInternalFetch(appFetch, depth = 1) {
   return ((input, init) => {
     if (typeof input === "string" && input.startsWith("/")) {
-      if (depth >= MAX_INTERNAL_FETCH_DEPTH) {
-        return Promise.resolve(
-          new Response("Internal fetch loop detected", {
-            status: 508
-          })
-        );
-      }
-      depth++;
-      return Promise.resolve(
-        appFetch(new Request(`http://localhost${input}`, init))
-      ).finally(() => {
-        depth--;
-      });
+      const request = new Request(`http://localhost${input}`, init);
+      request.headers.set(SSR_DEPTH_HEADER, String(depth));
+      return Promise.resolve(appFetch(request));
     }
     return globalThis.fetch(input, init);
   });
@@ -46,7 +36,6 @@ function createSSRApp(options) {
     parentFetch
   } = options;
   const app = new Hono();
-  const internalFetch = parentFetch ? createInternalFetch(parentFetch) : void 0;
   const ISR_CACHE_MAX = 1e3;
   const isrCache = /* @__PURE__ */ new Map();
   function isrSet(key, val) {
@@ -56,6 +45,7 @@ function createSSRApp(options) {
     }
     isrCache.set(key, val);
   }
+  let templateCache;
   async function readTemplate(url) {
     if (!isProduction && vite) {
       const { readFileSync: readFileSync2 } = await import(
@@ -69,11 +59,13 @@ function createSSRApp(options) {
       const raw = readFileSync2(resolve2(root, "index.html"), "utf-8");
       return vite.transformIndexHtml(url, raw);
     }
+    if (templateCache) return templateCache;
     const isDeno = typeof globalThis.Deno !== "undefined";
     if (isDeno) {
-      return globalThis.Deno.readTextFileSync(
+      templateCache = globalThis.Deno.readTextFileSync(
         new URL("../dist/client/index.html", import.meta.url)
       );
+      return templateCache;
     }
     const { readFileSync } = await import(
       /* @vite-ignore */
@@ -83,7 +75,11 @@ function createSSRApp(options) {
       /* @vite-ignore */
       "path"
     );
-    return readFileSync(resolve(root, "dist/client/index.html"), "utf-8");
+    templateCache = readFileSync(
+      resolve(root, "dist/client/index.html"),
+      "utf-8"
+    );
+    return templateCache;
   }
   async function loadSSRModule() {
     if (!isProduction && vite) {
@@ -110,11 +106,12 @@ function createSSRApp(options) {
     );
   }
   app.get("*", async (c) => {
+    const ssrDepth = parseInt(c.req.header(SSR_DEPTH_HEADER) ?? "0", 10);
+    if (ssrDepth >= MAX_SSR_DEPTH) {
+      return c.text("SSR recursion loop detected", 508);
+    }
     const url = c.req.path + (c.req.url.includes("?") ? "?" + c.req.url.split("?")[1] : "");
     try {
-      const cacheKey = url;
-      const cached = isrCache.get(cacheKey);
-      if (cached) return c.html(cached);
       const template = await readTemplate(url);
       const { render, serializeServerData } = await loadSSRModule();
       const locale = parseAcceptLanguage(
@@ -122,6 +119,10 @@ function createSSRApp(options) {
         supportedLocales,
         defaultLocale
       );
+      const cacheKey = `${locale}:${url}`;
+      const cached = isrCache.get(cacheKey);
+      if (cached) return c.html(cached);
+      const requestFetch = parentFetch ? createInternalFetch(parentFetch, ssrDepth + 1) : void 0;
       const {
         html: appHtml,
         head,
@@ -131,7 +132,7 @@ function createSSRApp(options) {
       } = await render(
         url,
         locale,
-        internalFetch ? { fetch: internalFetch } : void 0
+        requestFetch ? { fetch: requestFetch } : void 0
       );
       if (renderMode === "csr") {
         return c.html(injectCSRShell(template, locale));
@@ -161,7 +162,9 @@ function createSSRApp(options) {
 }
 
 export {
+  SSR_DEPTH_HEADER,
+  MAX_SSR_DEPTH,
   createInternalFetch,
   createSSRApp
 };
-//# sourceMappingURL=chunk-I32JEYQR.js.map
+//# sourceMappingURL=chunk-M7VITIMR.js.map

package/dist/chunk-M7VITIMR.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../server/src/app.ts","../../server/src/internal-fetch.ts"],"sourcesContent":["/**\n * createSSRApp — 创建 Hono SSR 应用\n *\n * 提供 SSR 通配路由，读取模板、加载 SSR 模块、渲染。\n * 应用层可在此之上追加自定义路由（API 代理等）。\n */\n\nimport { injectCSRShell, injectSSRContent } from \"@finesoft/ssr\";\nimport { Hono } from \"hono\";\nimport type { ViteDevServer } from \"vite\";\nimport {\n\tcreateInternalFetch,\n\tMAX_SSR_DEPTH,\n\tSSR_DEPTH_HEADER,\n} from \"./internal-fetch\";\nimport { parseAcceptLanguage } from \"./locale\";\n\nexport interface SSRModule {\n\trender: (\n\t\turl: string,\n\t\tlocale: string,\n\t\tssrContext?: { fetch?: typeof globalThis.fetch },\n\t) => Promise<{\n\t\thtml: string;\n\t\thead: string;\n\t\tcss: string;\n\t\tserverData: unknown;\n\t\trenderMode?: string;\n\t}>;\n\tserializeServerData: (data: unknown) => string;\n}\n\nexport interface SSRAppOptions {\n\t/** 项目根路径 */\n\troot: string;\n\t/** Vite dev server（仅开发模式） */\n\tvite?: ViteDevServer;\n\t/** 是否生产环境 */\n\tisProduction: boolean;\n\t/** SSR 入口文件路径（开发用，如 \"/src/ssr.ts\"） */\n\tssrEntryPath?: string;\n\t/** 生产环境 SSR 模块路径（如 \"../dist/server/ssr.js\"） */\n\tssrProductionModule?: string;\n\t/** 支持的语言列表 */\n\tsupportedLocales?: string[];\n\t/** 默认语言 */\n\tdefaultLocale?: string;\n\t/**\n\t * 父级 Hono app 的 fetch 函数，用于 SSR 内部路由回环。\n\t * SSR 渲染时，控制器的 fetch 请求（如 /api/apple/*）会通过此函数\n\t * 直接在进程内路由到代理 handler，避免网络自请求死锁。\n\t */\n\tparentFetch?: (request: Request) => Response | Promise<Response>;\n}\n\nexport function createSSRApp(options: SSRAppOptions): Hono {\n\tconst {\n\t\troot,\n\t\tvite,\n\t\tisProduction,\n\t\tssrEntryPath = \"/src/ssr.ts\",\n\t\tssrProductionModule,\n\t\tsupportedLocales,\n\t\tdefaultLocale,\n\t\tparentFetch,\n\t} = options;\n\n\tconst app = new Hono();\n\n\t/** ISR 内存缓存（prerender 路由首次请求后缓存，LRU 驱逐） */\n\tconst ISR_CACHE_MAX = 1000;\n\tconst isrCache = new Map<string, string>();\n\tfunction isrSet(key: string, val: string) {\n\t\tif (isrCache.size >= ISR_CACHE_MAX) {\n\t\t\tconst first = isrCache.keys().next().value;\n\t\t\tif (first !== undefined) isrCache.delete(first);\n\t\t}\n\t\tisrCache.set(key, val);\n\t}\n\n\t/** 生产环境模板缓存（模板不变，避免每请求重复读盘） */\n\tlet templateCache: string | undefined;\n\n\tasync function readTemplate(url: string): Promise<string> {\n\t\tif (!isProduction && vite) {\n\t\t\tconst { readFileSync } = await import(/* @vite-ignore */ \"node:fs\");\n\t\t\tconst { resolve } = await import(/* @vite-ignore */ \"node:path\");\n\t\t\tconst raw = readFileSync(resolve(root, \"index.html\"), \"utf-8\");\n\t\t\treturn vite.transformIndexHtml(url, raw);\n\t\t}\n\n\t\tif (templateCache) return templateCache;\n\n\t\tconst isDeno = typeof (globalThis as any).Deno !== \"undefined\";\n\t\tif (isDeno) {\n\t\t\ttemplateCache = (globalThis as any).Deno.readTextFileSync(\n\t\t\t\tnew URL(\"../dist/client/index.html\", import.meta.url),\n\t\t\t);\n\t\t\treturn templateCache!;\n\t\t}\n\n\t\tconst { readFileSync } = await import(/* @vite-ignore */ \"node:fs\");\n\t\tconst { resolve } = await import(/* @vite-ignore */ \"node:path\");\n\t\ttemplateCache = readFileSync(\n\t\t\tresolve(root, \"dist/client/index.html\"),\n\t\t\t\"utf-8\",\n\t\t);\n\t\treturn templateCache!;\n\t}\n\n\tasync function loadSSRModule(): Promise<SSRModule> {\n\t\tif (!isProduction && vite) {\n\t\t\treturn (await vite.ssrLoadModule(ssrEntryPath)) as SSRModule;\n\t\t}\n\t\tif (ssrProductionModule) {\n\t\t\treturn import(\n\t\t\t\t/* @vite-ignore */ ssrProductionModule\n\t\t\t) as Promise<SSRModule>;\n\t\t}\n\t\tconst { resolve } = await import(/* @vite-ignore */ \"node:path\");\n\t\tconst { pathToFileURL } = await import(/* @vite-ignore */ \"node:url\");\n\t\tconst absPath = pathToFileURL(resolve(root, \"dist/server/ssr.js\")).href;\n\t\treturn import(/* @vite-ignore */ absPath) as Promise<SSRModule>;\n\t}\n\n\tapp.get(\"*\", async (c) => {\n\t\t// 递归深度保护：从请求头读取 SSR 深度\n\t\tconst ssrDepth = parseInt(c.req.header(SSR_DEPTH_HEADER) ?? \"0\", 10);\n\t\tif (ssrDepth >= MAX_SSR_DEPTH) {\n\t\t\treturn c.text(\"SSR recursion loop detected\", 508);\n\t\t}\n\n\t\tconst url =\n\t\t\tc.req.path +\n\t\t\t(c.req.url.includes(\"?\") ? \"?\" + c.req.url.split(\"?\")[1] : \"\");\n\n\t\ttry {\n\t\t\tconst template = await readTemplate(url);\n\t\t\tconst { render, serializeServerData } = await loadSSRModule();\n\n\t\t\tconst locale = parseAcceptLanguage(\n\t\t\t\tc.req.header(\"accept-language\"),\n\t\t\t\tsupportedLocales,\n\t\t\t\tdefaultLocale,\n\t\t\t);\n\n\t\t\t// ISR 缓存命中（key 含 locale，避免跨语言缓存污染）\n\t\t\tconst cacheKey = `${locale}:${url}`;\n\t\t\tconst cached = isrCache.get(cacheKey);\n\t\t\tif (cached) return c.html(cached);\n\n\t\t\t// 每请求创建 internalFetch，深度通过请求头传递\n\t\t\tconst requestFetch = parentFetch\n\t\t\t\t? createInternalFetch(parentFetch, ssrDepth + 1)\n\t\t\t\t: undefined;\n\n\t\t\tconst {\n\t\t\t\thtml: appHtml,\n\t\t\t\thead,\n\t\t\t\tcss,\n\t\t\t\tserverData,\n\t\t\t\trenderMode,\n\t\t\t} = await render(\n\t\t\t\turl,\n\t\t\t\tlocale,\n\t\t\t\trequestFetch ? { fetch: requestFetch } : undefined,\n\t\t\t);\n\n\t\t\t// CSR 模式：返回空壳 HTML\n\t\t\tif (renderMode === \"csr\") {\n\t\t\t\treturn c.html(injectCSRShell(template, locale));\n\t\t\t}\n\n\t\t\tconst serializedData = serializeServerData(serverData);\n\n\t\t\tconst finalHtml = injectSSRContent({\n\t\t\t\ttemplate,\n\t\t\t\tlocale,\n\t\t\t\thead,\n\t\t\t\tcss,\n\t\t\t\thtml: appHtml,\n\t\t\t\tserializedData,\n\t\t\t});\n\n\t\t\t// Prerender ISR 缓存\n\t\t\tif (renderMode === \"prerender\") {\n\t\t\t\tisrSet(cacheKey, finalHtml);\n\t\t\t}\n\n\t\t\treturn c.html(finalHtml);\n\t\t} catch (e) {\n\t\t\tif (!isProduction && vite) {\n\t\t\t\tvite.ssrFixStacktrace(e as Error);\n\t\t\t}\n\t\t\tconsole.error(\"[SSR Error]\", e);\n\t\t\treturn c.text(\"Internal Server Error\", 500);\n\t\t}\n\t});\n\n\treturn app;\n}\n","/**\n * createInternalFetch — SSR 内部路由回环 fetch 包装器\n *\n * 将相对路径（/api/…）请求转为 Hono app.fetch 内存调用，\n * 绝对 URL 和非字符串 input 走 globalThis.fetch（真实网络）。\n *\n * 递归深度保护采用请求头传递：每次 SSR 回环在请求头中写入深度值，\n * SSR catch-all 读取深度判断是否超限。对比闭包计数器方案：\n * - 并发安全：无共享可变状态\n * - 跨渲染准确：深度随请求在 Hono 路由链中传递\n */\n\nexport const SSR_DEPTH_HEADER = \"x-ssr-depth\";\nexport const MAX_SSR_DEPTH = 5;\n\n/**\n * 创建请求级 internal fetch\n *\n * @param appFetch - Hono app.fetch（父级路由）\n * @param depth - 当前 SSR 深度（由 catch-all handler 从请求头读取后 +1 传入）\n */\nexport function createInternalFetch(\n\tappFetch: (request: Request) => Response | Promise<Response>,\n\tdepth: number = 1,\n): typeof globalThis.fetch {\n\treturn ((input: RequestInfo | URL, init?: RequestInit) => {\n\t\t// 只拦截相对路径（以 / 开头），其他一律走真实网络\n\t\tif (typeof input === \"string\" && input.startsWith(\"/\")) {\n\t\t\tconst request = new Request(`http://localhost${input}`, init);\n\t\t\trequest.headers.set(SSR_DEPTH_HEADER, String(depth));\n\t\t\treturn Promise.resolve(appFetch(request));\n\t\t}\n\n\t\t// 绝对 URL / URL 对象 / Request 对象 → 走正常网络\n\t\treturn globalThis.fetch(input, init);\n\t}) as typeof globalThis.fetch;\n}\n"],"mappings":"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","names":["readFileSync","resolve"]}

package/dist/{chunk-N4AEOYUR.js → chunk-ZMOE42LB.js}

@@ -34,7 +34,11 @@ async function ssrRender(options) {
     try {
       page = await framework.dispatch(match.intent);
       serverData = [{ intent: match.intent, data: page }];
-    } catch {
+    } catch (e) {
+      console.error(
+        `[SSR] dispatch failed for intent "${match.intent.id}":`,
+        e
+      );
       page = getErrorPage(500, "Internal error");
     }
   } else {
@@ -109,4 +113,4 @@ export {
   injectCSRShell,
   serializeServerData
 };
-//# sourceMappingURL=chunk-N4AEOYUR.js.map
+//# sourceMappingURL=chunk-ZMOE42LB.js.map

package/dist/chunk-ZMOE42LB.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../ssr/src/render.ts","../../ssr/src/create-render.ts","../../ssr/src/inject.ts","../../ssr/src/server-data.ts"],"sourcesContent":["/**\n * ssrRender — 通用 SSR 渲染管线\n *\n * 1. 创建 Framework + 注册 Controllers\n * 2. routeUrl → Intent\n * 3. dispatch → Page 数据\n * 4. 调用应用层提供的渲染函数\n */\n\nimport {\n\tFramework,\n\ttype BasePage,\n\ttype FrameworkConfig,\n\ttype PrefetchedIntent,\n} from \"@finesoft/core\";\n\nexport interface SSRRenderOptions {\n\t/** 请求 URL */\n\turl: string;\n\t/** Framework 配置（含路由注册等） */\n\tframeworkConfig: FrameworkConfig;\n\t/** 注册 controllers 和路由的引导函数 */\n\tbootstrap: (framework: Framework) => void;\n\t/** 获取错误页面 */\n\tgetErrorPage: (status: number, message: string) => BasePage;\n\t/** 应用层渲染函数（如 Svelte SSR render） */\n\trenderApp: (page: BasePage, framework: Framework) => SSRAppResult;\n\t/** 可选的 SSR 请求上下文（如自定义 fetch） */\n\tssrContext?: SSRContext;\n}\n\n/** SSR 请求级上下文 */\nexport interface SSRContext {\n\t/** 自定义 fetch（如 Hono 内部路由回环） */\n\tfetch?: typeof globalThis.fetch;\n}\n\nexport interface SSRAppResult {\n\thtml: string;\n\thead: string;\n\tcss: string;\n}\n\nexport interface SSRRenderResult {\n\thtml: string;\n\thead: string;\n\tcss: string;\n\tserverData: PrefetchedIntent[];\n\t/** 该路由的渲染模式（由 Router 返回） */\n\trenderMode?: string;\n}\n\nexport async function ssrRender(\n\toptions: SSRRenderOptions,\n): Promise<SSRRenderResult> {\n\tconst {\n\t\turl,\n\t\tframeworkConfig,\n\t\tbootstrap,\n\t\tgetErrorPage,\n\t\trenderApp,\n\t\tssrContext,\n\t} = options;\n\n\t// 将 SSR 上下文中的 fetch 合并到 frameworkConfig，注入 DI 容器\n\tconst mergedConfig: FrameworkConfig = ssrContext?.fetch\n\t\t? { ...frameworkConfig, fetch: ssrContext.fetch }\n\t\t: frameworkConfig;\n\n\tconst framework = Framework.create(mergedConfig);\n\tbootstrap(framework);\n\n\tconst parsed = new URL(url, \"http://localhost\");\n\tconst fullPath = parsed.pathname + parsed.search;\n\tconst match = framework.routeUrl(fullPath);\n\n\t// CSR 模式：跳过服务端渲染，返回空内容由客户端 JS 渲染\n\tif (match?.renderMode === \"csr\") {\n\t\tframework.dispose();\n\t\treturn {\n\t\t\thtml: \"\",\n\t\t\thead: \"\",\n\t\t\tcss: \"\",\n\t\t\tserverData: [],\n\t\t\trenderMode: \"csr\",\n\t\t};\n\t}\n\n\tlet page: BasePage;\n\tlet serverData: PrefetchedIntent[] = [];\n\n\tif (match) {\n\t\ttry {\n\t\t\tpage = (await framework.dispatch(match.intent)) as BasePage;\n\t\t\tserverData = [{ intent: match.intent, data: page }];\n\t\t} catch (e) {\n\t\t\tconsole.error(\n\t\t\t\t`[SSR] dispatch failed for intent \"${match.intent.id}\":`,\n\t\t\t\te,\n\t\t\t);\n\t\t\tpage = getErrorPage(500, \"Internal error\");\n\t\t}\n\t} else {\n\t\tpage = getErrorPage(404, \"Page not found\");\n\t}\n\n\tconst result = renderApp(page, framework);\n\n\tframework.dispose();\n\n\treturn {\n\t\thtml: result.html,\n\t\thead: result.head,\n\t\tcss: result.css,\n\t\tserverData,\n\t\trenderMode: match?.renderMode,\n\t};\n}\n","/**\n * createSSRRender — 工厂函数，返回可直接被 SSR 服务器调用的 render 函数\n *\n * 将一次性配置（bootstrap / getErrorPage / renderApp）绑定后，\n * 返回 `(url, locale) => Promise<SSRRenderResult>` 签名，\n * 与 @finesoft/server 的 SSRModule 接口对齐。\n */\n\nimport type { BasePage, Framework, FrameworkConfig } from \"@finesoft/core\";\nimport {\n\tssrRender,\n\ttype SSRAppResult,\n\ttype SSRContext,\n\ttype SSRRenderResult,\n} from \"./render\";\n\nexport interface SSRRenderConfig {\n\t/** 注册 controllers 和路由的引导函数 */\n\tbootstrap: (framework: Framework) => void;\n\n\t/** 获取错误页面 */\n\tgetErrorPage: (status: number, message: string) => BasePage;\n\n\t/**\n\t * 应用层渲染函数\n\t *\n\t * @param page - 当前页面数据\n\t * @param locale - 当前语言\n\t * @returns SSR 渲染结果 { html, head, css }\n\t */\n\trenderApp: (page: BasePage, locale: string) => SSRAppResult;\n\n\t/** Framework 构造配置（可选） */\n\tframeworkConfig?: FrameworkConfig;\n}\n\n/**\n * 创建 render 函数\n *\n * @returns `render(url, locale, ssrContext?)` — 供 @finesoft/server SSRModule 使用\n */\nexport function createSSRRender(\n\tconfig: SSRRenderConfig,\n): (\n\turl: string,\n\tlocale: string,\n\tssrContext?: SSRContext,\n) => Promise<SSRRenderResult> {\n\tconst { bootstrap, getErrorPage, renderApp, frameworkConfig } = config;\n\n\treturn (url: string, locale: string, ssrContext?: SSRContext) =>\n\t\tssrRender({\n\t\t\turl,\n\t\t\tframeworkConfig: frameworkConfig ?? {},\n\t\t\tbootstrap,\n\t\t\tgetErrorPage,\n\t\t\trenderApp: (page) => renderApp(page, locale),\n\t\t\tssrContext,\n\t\t});\n}\n","/**\n * injectSSRContent — 将 SSR 渲染结果注入 HTML 模板\n */\n\n/** SSR HTML 模板占位符常量 */\nexport const SSR_PLACEHOLDERS = {\n\tLANG: \"<!--ssr-lang-->\",\n\tHEAD: \"<!--ssr-head-->\",\n\tBODY: \"<!--ssr-body-->\",\n\tDATA: \"<!--ssr-data-->\",\n} as const;\n\nexport interface InjectSSROptions {\n\ttemplate: string;\n\tlocale: string;\n\thead: string;\n\tcss: string;\n\thtml: string;\n\tserializedData: string;\n}\n\nexport function injectSSRContent(options: InjectSSROptions): string {\n\tconst { template, locale, head, css, html, serializedData } = options;\n\tconst cssTag = css ? `<style>${css}</style>` : \"\";\n\n\treturn template\n\t\t.replace(SSR_PLACEHOLDERS.LANG, locale)\n\t\t.replace(SSR_PLACEHOLDERS.HEAD, `${head}\\n${cssTag}`)\n\t\t.replace(SSR_PLACEHOLDERS.BODY, html)\n\t\t.replace(\n\t\t\tSSR_PLACEHOLDERS.DATA,\n\t\t\t`<script id=\"serialized-server-data\" type=\"application/json\">${serializedData}</script>`,\n\t\t);\n}\n\n/**\n * CSR 空壳注入 — 只替换 lang，清空 body/head/data 占位符\n * 用于 renderMode === \"csr\" 的路由\n */\nexport function injectCSRShell(template: string, locale: string): string {\n\treturn template\n\t\t.replace(SSR_PLACEHOLDERS.LANG, locale)\n\t\t.replace(SSR_PLACEHOLDERS.HEAD, \"\")\n\t\t.replace(SSR_PLACEHOLDERS.BODY, \"\")\n\t\t.replace(SSR_PLACEHOLDERS.DATA, \"\");\n}\n","/**\n * serializeServerData — 将 PrefetchedIntents 数据序列化为安全的 JSON\n *\n * 返回值可安全嵌入 <script> 标签。\n */\n\nimport type { PrefetchedIntent } from \"@finesoft/core\";\n\nconst HTML_REPLACEMENTS: Record<string, string> = {\n\t\"<\": \"\\\\u003C\",\n\t\">\": \"\\\\u003E\",\n\t\"/\": \"\\\\u002F\",\n\t\"\\u2028\": \"\\\\u2028\",\n\t\"\\u2029\": \"\\\\u2029\",\n};\n\nconst HTML_ESCAPE_PATTERN = /[<>/\\u2028\\u2029]/g;\n\nexport function serializeServerData(data: PrefetchedIntent[]): string {\n\tconst json = JSON.stringify(data);\n\treturn json.replace(\n\t\tHTML_ESCAPE_PATTERN,\n\t\t(match) => HTML_REPLACEMENTS[match] ?? match,\n\t);\n}\n"],"mappings":";;;;;AAoDA,eAAsB,UACrB,SAC2B;AAC3B,QAAM;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACD,IAAI;AAGJ,QAAM,eAAgC,YAAY,QAC/C,EAAE,GAAG,iBAAiB,OAAO,WAAW,MAAM,IAC9C;AAEH,QAAM,YAAY,UAAU,OAAO,YAAY;AAC/C,YAAU,SAAS;AAEnB,QAAM,SAAS,IAAI,IAAI,KAAK,kBAAkB;AAC9C,QAAM,WAAW,OAAO,WAAW,OAAO;AAC1C,QAAM,QAAQ,UAAU,SAAS,QAAQ;AAGzC,MAAI,OAAO,eAAe,OAAO;AAChC,cAAU,QAAQ;AAClB,WAAO;AAAA,MACN,MAAM;AAAA,MACN,MAAM;AAAA,MACN,KAAK;AAAA,MACL,YAAY,CAAC;AAAA,MACb,YAAY;AAAA,IACb;AAAA,EACD;AAEA,MAAI;AACJ,MAAI,aAAiC,CAAC;AAEtC,MAAI,OAAO;AACV,QAAI;AACH,aAAQ,MAAM,UAAU,SAAS,MAAM,MAAM;AAC7C,mBAAa,CAAC,EAAE,QAAQ,MAAM,QAAQ,MAAM,KAAK,CAAC;AAAA,IACnD,SAAS,GAAG;AACX,cAAQ;AAAA,QACP,qCAAqC,MAAM,OAAO,EAAE;AAAA,QACpD;AAAA,MACD;AACA,aAAO,aAAa,KAAK,gBAAgB;AAAA,IAC1C;AAAA,EACD,OAAO;AACN,WAAO,aAAa,KAAK,gBAAgB;AAAA,EAC1C;AAEA,QAAM,SAAS,UAAU,MAAM,SAAS;AAExC,YAAU,QAAQ;AAElB,SAAO;AAAA,IACN,MAAM,OAAO;AAAA,IACb,MAAM,OAAO;AAAA,IACb,KAAK,OAAO;AAAA,IACZ;AAAA,IACA,YAAY,OAAO;AAAA,EACpB;AACD;;;AC5EO,SAAS,gBACf,QAK6B;AAC7B,QAAM,EAAE,WAAW,cAAc,WAAW,gBAAgB,IAAI;AAEhE,SAAO,CAAC,KAAa,QAAgB,eACpC,UAAU;AAAA,IACT;AAAA,IACA,iBAAiB,mBAAmB,CAAC;AAAA,IACrC;AAAA,IACA;AAAA,IACA,WAAW,CAAC,SAAS,UAAU,MAAM,MAAM;AAAA,IAC3C;AAAA,EACD,CAAC;AACH;;;ACtDO,IAAM,mBAAmB;AAAA,EAC/B,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AACP;AAWO,SAAS,iBAAiB,SAAmC;AACnE,QAAM,EAAE,UAAU,QAAQ,MAAM,KAAK,MAAM,eAAe,IAAI;AAC9D,QAAM,SAAS,MAAM,UAAU,GAAG,aAAa;AAE/C,SAAO,SACL,QAAQ,iBAAiB,MAAM,MAAM,EACrC,QAAQ,iBAAiB,MAAM,GAAG,IAAI;AAAA,EAAK,MAAM,EAAE,EACnD,QAAQ,iBAAiB,MAAM,IAAI,EACnC;AAAA,IACA,iBAAiB;AAAA,IACjB,+DAA+D,cAAc;AAAA,EAC9E;AACF;AAMO,SAAS,eAAe,UAAkB,QAAwB;AACxE,SAAO,SACL,QAAQ,iBAAiB,MAAM,MAAM,EACrC,QAAQ,iBAAiB,MAAM,EAAE,EACjC,QAAQ,iBAAiB,MAAM,EAAE,EACjC,QAAQ,iBAAiB,MAAM,EAAE;AACpC;;;ACrCA,IAAM,oBAA4C;AAAA,EACjD,KAAK;AAAA,EACL,KAAK;AAAA,EACL,KAAK;AAAA,EACL,UAAU;AAAA,EACV,UAAU;AACX;AAEA,IAAM,sBAAsB;AAErB,SAAS,oBAAoB,MAAkC;AACrE,QAAM,OAAO,KAAK,UAAU,IAAI;AAChC,SAAO,KAAK;AAAA,IACX;AAAA,IACA,CAAC,UAAU,kBAAkB,KAAK,KAAK;AAAA,EACxC;AACD;","names":[]}

package/dist/index.cjs

@@ -999,7 +999,11 @@ async function ssrRender(options) {
     try {
       page = await framework.dispatch(match.intent);
       serverData = [{ intent: match.intent, data: page }];
-    } catch {
+    } catch (e) {
+      console.error(
+        `[SSR] dispatch failed for intent "${match.intent.id}":`,
+        e
+      );
       page = getErrorPage(500, "Internal error");
     }
   } else {
@@ -1113,32 +1117,22 @@ var init_src2 = __esm({
 });
 
 // ../server/src/internal-fetch.ts
-function createInternalFetch(appFetch) {
-  let depth = 0;
+function createInternalFetch(appFetch, depth = 1) {
   return ((input, init) => {
     if (typeof input === "string" && input.startsWith("/")) {
-      if (depth >= MAX_INTERNAL_FETCH_DEPTH) {
-        return Promise.resolve(
-          new Response("Internal fetch loop detected", {
-            status: 508
-          })
-        );
-      }
-      depth++;
-      return Promise.resolve(
-        appFetch(new Request(`http://localhost${input}`, init))
-      ).finally(() => {
-        depth--;
-      });
+      const request = new Request(`http://localhost${input}`, init);
+      request.headers.set(SSR_DEPTH_HEADER, String(depth));
+      return Promise.resolve(appFetch(request));
     }
     return globalThis.fetch(input, init);
   });
 }
-var MAX_INTERNAL_FETCH_DEPTH;
+var SSR_DEPTH_HEADER, MAX_SSR_DEPTH;
 var init_internal_fetch = __esm({
   "../server/src/internal-fetch.ts"() {
     "use strict";
-    MAX_INTERNAL_FETCH_DEPTH = 5;
+    SSR_DEPTH_HEADER = "x-ssr-depth";
+    MAX_SSR_DEPTH = 5;
   }
 });
 
@@ -1189,7 +1183,6 @@ function createSSRApp(options) {
     parentFetch
   } = options;
   const app = new import_hono.Hono();
-  const internalFetch = parentFetch ? createInternalFetch(parentFetch) : void 0;
   const ISR_CACHE_MAX = 1e3;
   const isrCache = /* @__PURE__ */ new Map();
   function isrSet(key, val) {
@@ -1199,6 +1192,7 @@ function createSSRApp(options) {
     }
     isrCache.set(key, val);
   }
+  let templateCache;
   async function readTemplate(url) {
     if (!isProduction && vite) {
       const { readFileSync: readFileSync2 } = await import(
@@ -1212,11 +1206,13 @@ function createSSRApp(options) {
       const raw = readFileSync2(resolve2(root, "index.html"), "utf-8");
       return vite.transformIndexHtml(url, raw);
     }
+    if (templateCache) return templateCache;
     const isDeno = typeof globalThis.Deno !== "undefined";
     if (isDeno) {
-      return globalThis.Deno.readTextFileSync(
+      templateCache = globalThis.Deno.readTextFileSync(
         new URL("../dist/client/index.html", import_meta.url)
       );
+      return templateCache;
     }
     const { readFileSync } = await import(
       /* @vite-ignore */
@@ -1226,7 +1222,11 @@ function createSSRApp(options) {
       /* @vite-ignore */
       "path"
     );
-    return readFileSync(resolve(root, "dist/client/index.html"), "utf-8");
+    templateCache = readFileSync(
+      resolve(root, "dist/client/index.html"),
+      "utf-8"
+    );
+    return templateCache;
   }
   async function loadSSRModule() {
     if (!isProduction && vite) {
@@ -1253,11 +1253,12 @@ function createSSRApp(options) {
     );
   }
   app.get("*", async (c) => {
+    const ssrDepth = parseInt(c.req.header(SSR_DEPTH_HEADER) ?? "0", 10);
+    if (ssrDepth >= MAX_SSR_DEPTH) {
+      return c.text("SSR recursion loop detected", 508);
+    }
     const url = c.req.path + (c.req.url.includes("?") ? "?" + c.req.url.split("?")[1] : "");
     try {
-      const cacheKey = url;
-      const cached = isrCache.get(cacheKey);
-      if (cached) return c.html(cached);
       const template = await readTemplate(url);
       const { render, serializeServerData: serializeServerData2 } = await loadSSRModule();
       const locale = parseAcceptLanguage(
@@ -1265,6 +1266,10 @@ function createSSRApp(options) {
         supportedLocales,
         defaultLocale
       );
+      const cacheKey = `${locale}:${url}`;
+      const cached = isrCache.get(cacheKey);
+      if (cached) return c.html(cached);
+      const requestFetch = parentFetch ? createInternalFetch(parentFetch, ssrDepth + 1) : void 0;
       const {
         html: appHtml,
         head,
@@ -1274,7 +1279,7 @@ function createSSRApp(options) {
       } = await render(
         url,
         locale,
-        internalFetch ? { fetch: internalFetch } : void 0
+        requestFetch ? { fetch: requestFetch } : void 0
       );
       if (renderMode === "csr") {
         return c.html(injectCSRShell(template, locale));
@@ -1806,20 +1811,28 @@ ${setupCall}
 ${opts.platformMiddleware ?? ""}
 
 // \u5185\u90E8 fetch \u56DE\u73AF\uFF1ASSR \u63A7\u5236\u5668\u7684 fetch \u8BF7\u6C42\u76F4\u63A5\u8D70 Hono \u5185\u5B58\u8DEF\u7531
-// \u53EA\u62E6\u622A\u76F8\u5BF9\u8DEF\u5F84\uFF08/api/* \u7B49\uFF09\uFF0C\u7EDD\u5BF9 URL \u8D70\u6B63\u5E38\u7F51\u7EDC\uFF1B\u542B\u9012\u5F52\u4FDD\u62A4
-let _fetchDepth = 0;
-function _internalFetch(input, init) {
-  if (typeof input === "string" && input.startsWith("/")) {
-    if (_fetchDepth >= 5) {
-      return Promise.resolve(new Response("Internal fetch loop detected", { status: 508 }));
+// \u6DF1\u5EA6\u901A\u8FC7\u8BF7\u6C42\u5934\u4F20\u9012\uFF0C\u5E76\u53D1\u5B89\u5168\u4E14\u80FD\u8DE8\u6E32\u67D3\u6B63\u786E\u8FFD\u8E2A\u9012\u5F52
+const _SSR_DEPTH_HEADER = "x-ssr-depth";
+const _MAX_SSR_DEPTH = 5;
+
+function _createInternalFetch(depth) {
+  return function(input, init) {
+    if (typeof input === "string" && input.startsWith("/")) {
+      const req = new Request("http://localhost" + input, init);
+      req.headers.set(_SSR_DEPTH_HEADER, String(depth));
+      return app.fetch(req);
     }
-    _fetchDepth++;
-    return app.fetch(new Request("http://localhost" + input, init)).finally(() => { _fetchDepth--; });
-  }
-  return globalThis.fetch(input, init);
+    return globalThis.fetch(input, init);
+  };
 }
 
 app.get("*", async (c) => {
+  // \u9012\u5F52\u6DF1\u5EA6\u4FDD\u62A4\uFF1A\u4ECE\u8BF7\u6C42\u5934\u8BFB\u53D6 SSR \u6DF1\u5EA6
+  const _ssrDepth = parseInt(c.req.header(_SSR_DEPTH_HEADER) || "0", 10);
+  if (_ssrDepth >= _MAX_SSR_DEPTH) {
+    return c.text("SSR recursion loop detected", 508);
+  }
+
   const url = c.req.path + (c.req.url.includes("?") ? "?" + c.req.url.split("?")[1] : "");
   try {
     const locale = parseAcceptLanguage(c.req.header("accept-language"));
@@ -1830,11 +1843,12 @@ app.get("*", async (c) => {
       return c.html(injectCSRShell(TEMPLATE, locale));
     }
 
-    // ISR \u7F13\u5B58\u547D\u4E2D
-    const cached = await platformCacheGet(url);
+    // ISR \u7F13\u5B58\u547D\u4E2D\uFF08key \u542B locale\uFF0C\u907F\u514D\u8DE8\u8BED\u8A00\u7F13\u5B58\u6C61\u67D3\uFF09
+    const _cacheKey = locale + ":" + url;
+    const cached = await platformCacheGet(_cacheKey);
     if (cached) return c.html(cached);
 
-    const { html: appHtml, head, css, serverData, renderMode } = await render(url, locale, { fetch: _internalFetch });
+    const { html: appHtml, head, css, serverData, renderMode } = await render(url, locale, { fetch: _createInternalFetch(_ssrDepth + 1) });
 
     // \u8DEF\u7531\u7EA7 CSR
     if (renderMode === "csr") {
@@ -1846,7 +1860,7 @@ app.get("*", async (c) => {
 
     // Prerender ISR \u7F13\u5B58\uFF08\u5305\u62EC Vite \u914D\u7F6E\u8986\u76D6\u548C\u8DEF\u7531\u7EA7\uFF09
     if (renderMode === "prerender" || overrideMode === "prerender") {
-      await platformCacheSet(url, finalHtml);
+      await platformCacheSet(_cacheKey, finalHtml);
       ${opts.platformPrerenderResponseHook ?? ""}
     }
 
@@ -2855,6 +2869,13 @@ function finesoftFrontViteConfig(options = {}) {
           ssrPath
         );
         app.get("*", async (c) => {
+          const ssrDepth = parseInt(
+            c.req.header(SSR_DEPTH_HEADER) ?? "0",
+            10
+          );
+          if (ssrDepth >= MAX_SSR_DEPTH) {
+            return c.text("SSR recursion loop detected", 508);
+          }
           const url = c.req.path + (c.req.url.includes("?") ? "?" + c.req.url.split("?")[1] : "");
           try {
             const locale = parseAcceptLanguage2(
@@ -2869,7 +2890,8 @@ function finesoftFrontViteConfig(options = {}) {
             if (overrideMode === "csr") {
               return c.html(injectCSRShell2(template, locale));
             }
-            const cached = isrCache.get(url);
+            const cacheKey = `${locale}:${url}`;
+            const cached = isrCache.get(cacheKey);
             if (cached) return c.html(cached);
             const {
               html: appHtml,
@@ -2878,7 +2900,10 @@ function finesoftFrontViteConfig(options = {}) {
               serverData,
               renderMode
             } = await ssrModule.render(url, locale, {
-              fetch: createInternalFetch(app.fetch.bind(app))
+              fetch: createInternalFetch(
+                app.fetch.bind(app),
+                ssrDepth + 1
+              )
             });
             if (renderMode === "csr") {
               return c.html(injectCSRShell2(template, locale));
@@ -2893,7 +2918,7 @@ function finesoftFrontViteConfig(options = {}) {
               serializedData
             });
             if (renderMode === "prerender" || overrideMode === "prerender") {
-              isrCache.set(url, finalHtml);
+              isrCache.set(cacheKey, finalHtml);
             }
             return c.html(finalHtml);
           } catch (e) {