@finesoft/front 0.1.19 → 0.1.21

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { FrameworkConfig, Framework, BasePage, PrefetchedIntent } from './browser.cjs';
-export { ACTION_KINDS, Action, ActionDispatcher, ActionHandler, ActionHandlerDependencies, AsyncMapper, BaseController, BaseItem, BaseLogger, BaseShelf, BrowserAppConfig, CompositeLogger, CompositeLoggerFactory, CompoundAction, ConsoleLogger, ConsoleLoggerFactory, Container, DEP_KEYS, ExternalUrlAction, ExternalUrlDependencies, FeatureFlags, FlowAction, FlowActionCallbacks, FlowActionDependencies, History, HttpClient, HttpClientConfig, HttpError, Intent, IntentController, IntentDispatcher, Locale, Logger, LoggerFactory, Logger as LoggerInterface, LruMap, Mapper, MetricsRecorder, Net, None, Optional, PrefetchedIntents, RouteDefinition, RouteMatch, Router, Storage, buildUrl, createPrefetchedIntentsFromDom, defineRoutes, deserializeServerData, generateUuid, getBaseUrl, isCompoundAction, isExternalUrlAction, isFlowAction, isNone, isSome, makeDependencies, makeExternalUrlAction, makeFlowAction, mapEach, pipe, pipeAsync, registerActionHandlers, registerExternalUrlHandler, registerFlowActionHandler, removeHost, removeQueryParams, removeScheme, resetFilterCache, shouldLog, stableStringify, startBrowserApp, tryScroll } from './browser.cjs';
+export { ACTION_KINDS, Action, ActionDispatcher, ActionHandler, ActionHandlerDependencies, AsyncMapper, BaseController, BaseItem, BaseLogger, BaseShelf, BrowserAppConfig, CompositeLogger, CompositeLoggerFactory, CompoundAction, ConsoleLogger, ConsoleLoggerFactory, Container, DEP_KEYS, ExternalUrlAction, ExternalUrlDependencies, FeatureFlags, FlowAction, FlowActionCallbacks, FlowActionDependencies, History, HttpClient, HttpClientConfig, HttpError, Intent, IntentController, IntentDispatcher, Locale, Logger, LoggerFactory, Logger as LoggerInterface, LruMap, Mapper, MetricsRecorder, Net, None, Optional, PrefetchedIntents, RenderMode, RouteDefinition, RouteMatch, Router, Storage, buildUrl, createPrefetchedIntentsFromDom, defineRoutes, deserializeServerData, generateUuid, getBaseUrl, isCompoundAction, isExternalUrlAction, isFlowAction, isNone, isSome, makeDependencies, makeExternalUrlAction, makeFlowAction, mapEach, pipe, pipeAsync, registerActionHandlers, registerExternalUrlHandler, registerFlowActionHandler, removeHost, removeQueryParams, removeScheme, resetFilterCache, shouldLog, stableStringify, startBrowserApp, tryScroll } from './browser.cjs';
 import * as node_fs from 'node:fs';
 import { Hono } from 'hono';
 import { ViteDevServer } from 'vite';
@@ -35,6 +35,8 @@ interface SSRRenderResult {
     head: string;
     css: string;
     serverData: PrefetchedIntent[];
+    /** 该路由的渲染模式（由 Router 返回） */
+    renderMode?: string;
 }
 declare function ssrRender(options: SSRRenderOptions): Promise<SSRRenderResult>;
 
@@ -88,6 +90,11 @@ interface InjectSSROptions {
     serializedData: string;
 }
 declare function injectSSRContent(options: InjectSSROptions): string;
+/**
+ * CSR 空壳注入 — 只替换 lang，清空 body/head/data 占位符
+ * 用于 renderMode === "csr" 的路由
+ */
+declare function injectCSRShell(template: string, locale: string): string;
 
 /**
  * serializeServerData — 将 PrefetchedIntents 数据序列化为安全的 JSON
@@ -121,6 +128,11 @@ interface AdapterContext {
     resolvedResolve: unknown;
     /** Vite 的 css 配置 */
     resolvedCss: unknown;
+    /**
+     * 按路由覆盖的渲染模式。
+     * key: 精确路径或 glob 模式，value: "ssr" | "csr" | "prerender"
+     */
+    renderModes?: Record<string, string>;
     vite: any;
     fs: typeof node_fs;
     path: {
@@ -139,6 +151,25 @@ interface GenerateSSREntryOptions {
     platformImport: string;
     /** 平台特定的导出语句（如 `export default handle(app);`） */
     platformExport: string;
+    /**
+     * 平台特定的 ISR 缓存实现代码（可选）。
+     * 需提供 `async function platformCacheGet(url)` 返回 string|null，
+     * 和 `async function platformCacheSet(url, html)` 的函数定义。
+     * 不提供时使用内置的内存 Map 缓存。
+     */
+    platformCache?: string;
+    /**
+     * 平台特定的响应后处理代码（可选）。
+     * 在 prerender 路由返回前执行，可用于设置 CDN 缓存头等。
+     * 代码中可使用变量 `c`（Hono Context）。
+     */
+    platformPrerenderResponseHook?: string;
+    /**
+     * 平台特定的中间件代码（可选）。
+     * 插入在 catch-all GET 路由之前，可用于添加静态文件服务等。
+     * 代码中可使用变量 `app`（Hono 实例）。
+     */
+    platformMiddleware?: string;
 }
 interface BuildBundleOptions {
     /** 临时入口文件路径 */
@@ -264,6 +295,7 @@ interface SSRModule {
         head: string;
         css: string;
         serverData: unknown;
+        renderMode?: string;
     }>;
     serializeServerData: (data: unknown) => string;
 }
@@ -413,6 +445,20 @@ interface FinesoftFrontViteOptions {
      * - 不设置则不生成部署产物
      */
     adapter?: string | Adapter;
+    /**
+     * 按路由覆盖渲染模式（优先级高于 RouteDefinition.renderMode）。
+     * key: 精确路径或 glob 模式，如 "/search" 或 "/blog/*"
+     * value: "ssr" | "csr" | "prerender"
+     *
+     * @example
+     * ```ts
+     * renderModes: {
+     *   "/search": "csr",
+     *   "/blog/*": "prerender",
+     * }
+     * ```
+     */
+    renderModes?: Record<string, "ssr" | "csr" | "prerender">;
 }
 declare function finesoftFrontViteConfig(options?: FinesoftFrontViteOptions): {
     name: string;
@@ -425,4 +471,4 @@ declare function finesoftFrontViteConfig(options?: FinesoftFrontViteOptions): {
     closeBundle(): Promise<void>;
 };
 
-export { type Adapter, type AdapterContext, BasePage, type FinesoftFrontViteOptions, Framework, FrameworkConfig, type InjectSSROptions, PrefetchedIntent, type RuntimeInfo, type SSRAppOptions, type SSRModule, type SSRRenderConfig, type SSRRenderOptions, type SSRRenderResult, SSR_PLACEHOLDERS, type ServerConfig, type ServerInstance, type StartServerOptions, autoAdapter, cloudflareAdapter, createSSRApp, createSSRRender, createServer, detectRuntime, finesoftFrontViteConfig, injectSSRContent, netlifyAdapter, nodeAdapter, parseAcceptLanguage, resolveAdapter, resolveRoot, serializeServerData, ssrRender, startServer, staticAdapter, vercelAdapter };
+export { type Adapter, type AdapterContext, BasePage, type FinesoftFrontViteOptions, Framework, FrameworkConfig, type InjectSSROptions, PrefetchedIntent, type RuntimeInfo, type SSRAppOptions, type SSRModule, type SSRRenderConfig, type SSRRenderOptions, type SSRRenderResult, SSR_PLACEHOLDERS, type ServerConfig, type ServerInstance, type StartServerOptions, autoAdapter, cloudflareAdapter, createSSRApp, createSSRRender, createServer, detectRuntime, finesoftFrontViteConfig, injectCSRShell, injectSSRContent, netlifyAdapter, nodeAdapter, parseAcceptLanguage, resolveAdapter, resolveRoot, serializeServerData, ssrRender, startServer, staticAdapter, vercelAdapter };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { FrameworkConfig, Framework, BasePage, PrefetchedIntent } from './browser.js';
-export { ACTION_KINDS, Action, ActionDispatcher, ActionHandler, ActionHandlerDependencies, AsyncMapper, BaseController, BaseItem, BaseLogger, BaseShelf, BrowserAppConfig, CompositeLogger, CompositeLoggerFactory, CompoundAction, ConsoleLogger, ConsoleLoggerFactory, Container, DEP_KEYS, ExternalUrlAction, ExternalUrlDependencies, FeatureFlags, FlowAction, FlowActionCallbacks, FlowActionDependencies, History, HttpClient, HttpClientConfig, HttpError, Intent, IntentController, IntentDispatcher, Locale, Logger, LoggerFactory, Logger as LoggerInterface, LruMap, Mapper, MetricsRecorder, Net, None, Optional, PrefetchedIntents, RouteDefinition, RouteMatch, Router, Storage, buildUrl, createPrefetchedIntentsFromDom, defineRoutes, deserializeServerData, generateUuid, getBaseUrl, isCompoundAction, isExternalUrlAction, isFlowAction, isNone, isSome, makeDependencies, makeExternalUrlAction, makeFlowAction, mapEach, pipe, pipeAsync, registerActionHandlers, registerExternalUrlHandler, registerFlowActionHandler, removeHost, removeQueryParams, removeScheme, resetFilterCache, shouldLog, stableStringify, startBrowserApp, tryScroll } from './browser.js';
+export { ACTION_KINDS, Action, ActionDispatcher, ActionHandler, ActionHandlerDependencies, AsyncMapper, BaseController, BaseItem, BaseLogger, BaseShelf, BrowserAppConfig, CompositeLogger, CompositeLoggerFactory, CompoundAction, ConsoleLogger, ConsoleLoggerFactory, Container, DEP_KEYS, ExternalUrlAction, ExternalUrlDependencies, FeatureFlags, FlowAction, FlowActionCallbacks, FlowActionDependencies, History, HttpClient, HttpClientConfig, HttpError, Intent, IntentController, IntentDispatcher, Locale, Logger, LoggerFactory, Logger as LoggerInterface, LruMap, Mapper, MetricsRecorder, Net, None, Optional, PrefetchedIntents, RenderMode, RouteDefinition, RouteMatch, Router, Storage, buildUrl, createPrefetchedIntentsFromDom, defineRoutes, deserializeServerData, generateUuid, getBaseUrl, isCompoundAction, isExternalUrlAction, isFlowAction, isNone, isSome, makeDependencies, makeExternalUrlAction, makeFlowAction, mapEach, pipe, pipeAsync, registerActionHandlers, registerExternalUrlHandler, registerFlowActionHandler, removeHost, removeQueryParams, removeScheme, resetFilterCache, shouldLog, stableStringify, startBrowserApp, tryScroll } from './browser.js';
 import * as node_fs from 'node:fs';
 import { Hono } from 'hono';
 import { ViteDevServer } from 'vite';
@@ -35,6 +35,8 @@ interface SSRRenderResult {
     head: string;
     css: string;
     serverData: PrefetchedIntent[];
+    /** 该路由的渲染模式（由 Router 返回） */
+    renderMode?: string;
 }
 declare function ssrRender(options: SSRRenderOptions): Promise<SSRRenderResult>;
 
@@ -88,6 +90,11 @@ interface InjectSSROptions {
     serializedData: string;
 }
 declare function injectSSRContent(options: InjectSSROptions): string;
+/**
+ * CSR 空壳注入 — 只替换 lang，清空 body/head/data 占位符
+ * 用于 renderMode === "csr" 的路由
+ */
+declare function injectCSRShell(template: string, locale: string): string;
 
 /**
  * serializeServerData — 将 PrefetchedIntents 数据序列化为安全的 JSON
@@ -121,6 +128,11 @@ interface AdapterContext {
     resolvedResolve: unknown;
     /** Vite 的 css 配置 */
     resolvedCss: unknown;
+    /**
+     * 按路由覆盖的渲染模式。
+     * key: 精确路径或 glob 模式，value: "ssr" | "csr" | "prerender"
+     */
+    renderModes?: Record<string, string>;
     vite: any;
     fs: typeof node_fs;
     path: {
@@ -139,6 +151,25 @@ interface GenerateSSREntryOptions {
     platformImport: string;
     /** 平台特定的导出语句（如 `export default handle(app);`） */
     platformExport: string;
+    /**
+     * 平台特定的 ISR 缓存实现代码（可选）。
+     * 需提供 `async function platformCacheGet(url)` 返回 string|null，
+     * 和 `async function platformCacheSet(url, html)` 的函数定义。
+     * 不提供时使用内置的内存 Map 缓存。
+     */
+    platformCache?: string;
+    /**
+     * 平台特定的响应后处理代码（可选）。
+     * 在 prerender 路由返回前执行，可用于设置 CDN 缓存头等。
+     * 代码中可使用变量 `c`（Hono Context）。
+     */
+    platformPrerenderResponseHook?: string;
+    /**
+     * 平台特定的中间件代码（可选）。
+     * 插入在 catch-all GET 路由之前，可用于添加静态文件服务等。
+     * 代码中可使用变量 `app`（Hono 实例）。
+     */
+    platformMiddleware?: string;
 }
 interface BuildBundleOptions {
     /** 临时入口文件路径 */
@@ -264,6 +295,7 @@ interface SSRModule {
         head: string;
         css: string;
         serverData: unknown;
+        renderMode?: string;
     }>;
     serializeServerData: (data: unknown) => string;
 }
@@ -413,6 +445,20 @@ interface FinesoftFrontViteOptions {
      * - 不设置则不生成部署产物
      */
     adapter?: string | Adapter;
+    /**
+     * 按路由覆盖渲染模式（优先级高于 RouteDefinition.renderMode）。
+     * key: 精确路径或 glob 模式，如 "/search" 或 "/blog/*"
+     * value: "ssr" | "csr" | "prerender"
+     *
+     * @example
+     * ```ts
+     * renderModes: {
+     *   "/search": "csr",
+     *   "/blog/*": "prerender",
+     * }
+     * ```
+     */
+    renderModes?: Record<string, "ssr" | "csr" | "prerender">;
 }
 declare function finesoftFrontViteConfig(options?: FinesoftFrontViteOptions): {
     name: string;
@@ -425,4 +471,4 @@ declare function finesoftFrontViteConfig(options?: FinesoftFrontViteOptions): {
     closeBundle(): Promise<void>;
 };
 
-export { type Adapter, type AdapterContext, BasePage, type FinesoftFrontViteOptions, Framework, FrameworkConfig, type InjectSSROptions, PrefetchedIntent, type RuntimeInfo, type SSRAppOptions, type SSRModule, type SSRRenderConfig, type SSRRenderOptions, type SSRRenderResult, SSR_PLACEHOLDERS, type ServerConfig, type ServerInstance, type StartServerOptions, autoAdapter, cloudflareAdapter, createSSRApp, createSSRRender, createServer, detectRuntime, finesoftFrontViteConfig, injectSSRContent, netlifyAdapter, nodeAdapter, parseAcceptLanguage, resolveAdapter, resolveRoot, serializeServerData, ssrRender, startServer, staticAdapter, vercelAdapter };
+export { type Adapter, type AdapterContext, BasePage, type FinesoftFrontViteOptions, Framework, FrameworkConfig, type InjectSSROptions, PrefetchedIntent, type RuntimeInfo, type SSRAppOptions, type SSRModule, type SSRRenderConfig, type SSRRenderOptions, type SSRRenderResult, SSR_PLACEHOLDERS, type ServerConfig, type ServerInstance, type StartServerOptions, autoAdapter, cloudflareAdapter, createSSRApp, createSSRRender, createServer, detectRuntime, finesoftFrontViteConfig, injectCSRShell, injectSSRContent, netlifyAdapter, nodeAdapter, parseAcceptLanguage, resolveAdapter, resolveRoot, serializeServerData, ssrRender, startServer, staticAdapter, vercelAdapter };