@finesoft/front 0.1.34 → 0.1.36

package/README.md

@@ -2,10 +2,10 @@
 
 `@finesoft/front` 是一个面向 SSR Web 应用的聚合包，统一导出了以下四层能力：
 
-- `@finesoft/core`：路由、Intent、Controller、依赖注入、Framework
-- `@finesoft/browser`：浏览器启动、导航、hydrate、prefetched data
-- `@finesoft/ssr`：SSR 渲染与服务端数据注入
-- `@finesoft/server`：Hono 服务端集成、Vite 插件、部署适配器
+-   `@finesoft/core`：路由、Intent、Controller、依赖注入、Framework
+-   `@finesoft/browser`：浏览器启动、导航、hydrate、prefetched data
+-   `@finesoft/ssr`：SSR 渲染与服务端数据注入
+-   `@finesoft/server`：Hono 服务端集成、Vite 插件、声明式代理、渲染模式覆盖、部署适配器
 
 它适合这样一类应用：
 
@@ -21,16 +21,16 @@ $$
 
 `@finesoft/front` 更适合以下类型的项目：
 
-- 需要 SSR 的内容型站点
-- 有明确 URL 语义的多页面 Web 应用
-- 希望将页面获取逻辑集中在 Controller 中的项目
-- 需要同一套页面模型同时服务 SSR 和客户端导航的项目
+-   需要 SSR 的内容型站点
+-   有明确 URL 语义的多页面 Web 应用
+-   希望将页面获取逻辑集中在 Controller 中的项目
+-   需要同一套页面模型同时服务 SSR 和客户端导航的项目
 
 例如：
 
-- 内容聚合站点
-- 应用商店、媒体展示、排行榜、搜索、详情页
-- 需要 SEO 的展示型前端
+-   内容聚合站点
+-   应用商店、媒体展示、排行榜、搜索、详情页
+-   需要 SEO 的展示型前端
 
 如果你的项目非常轻量、完全不需要 SSR，也可以只使用其中的 Browser/Core 能力。
 
@@ -40,52 +40,54 @@ $$
 
 ### Core
 
-- `Framework`
-- `Router`
-- `Container`
-- `BaseController`
-- `defineRoutes`
-- `ActionDispatcher`
-- `IntentDispatcher`
-- `HttpClient`
-- `LruMap`
-- `buildUrl`
+-   `Framework`
+-   `Router`
+-   `Container`
+-   `BaseController`
+-   `defineRoutes`
+-   `ActionDispatcher`
+-   `IntentDispatcher`
+-   `HttpClient`
+-   `LruMap`
+-   `buildUrl`
 
 ### Browser
 
-- `startBrowserApp`
-- `History`
-- `registerActionHandlers`
-- `registerFlowActionHandler`
-- `registerExternalUrlHandler`
-- `deserializeServerData`
-- `createPrefetchedIntentsFromDom`
-- `tryScroll`
+-   `startBrowserApp`
+-   `History`
+-   `registerActionHandlers`
+-   `registerFlowActionHandler`
+-   `registerExternalUrlHandler`
+-   `deserializeServerData`
+-   `createPrefetchedIntentsFromDom`
+-   `tryScroll`
 
 ### SSR
 
-- `createSSRRender`
-- `ssrRender`
-- `injectSSRContent`
-- `serializeServerData`
-- `SSR_PLACEHOLDERS`
+-   `createSSRRender`
+-   `ssrRender`
+-   `injectSSRContent`
+-   `serializeServerData`
+-   `SSR_PLACEHOLDERS`
 
 ### Server / Deployment
 
-- `createServer`
-- `createSSRApp`
-- `startServer`
-- `parseAcceptLanguage`
-- `detectRuntime`
-- `resolveRoot`
-- `finesoftFrontViteConfig`
-- `nodeAdapter`
-- `vercelAdapter`
-- `cloudflareAdapter`
-- `netlifyAdapter`
-- `staticAdapter`
-- `autoAdapter`
-- `resolveAdapter`
+-   `createServer`
+-   `createSSRApp`
+-   `startServer`
+-   `parseAcceptLanguage`
+-   `detectRuntime`
+-   `resolveRoot`
+-   `finesoftFrontViteConfig`
+-   `registerProxyRoutes`
+-   `ProxyRouteConfig`
+-   `nodeAdapter`
+-   `vercelAdapter`
+-   `cloudflareAdapter`
+-   `netlifyAdapter`
+-   `staticAdapter`
+-   `autoAdapter`
+-   `resolveAdapter`
 
 ---
 
@@ -97,25 +99,28 @@ $$
 
 优点：
 
-- `vite` 可直接用于开发
-- `vite build` 会同时完成客户端与 SSR 构建
-- 可以直接接入平台适配器输出部署产物
-- `vite preview` 可用于本地预览 SSR 构建结果
+-   `vite` 可直接用于开发
+-   `vite build` 会同时完成客户端与 SSR 构建
+-   可以直接接入平台适配器输出部署产物
+-   `vite preview` 可用于本地预览 SSR 构建结果
+-   可通过 `renderModes` 统一覆盖路由的 `ssr` / `csr` / `prerender` 策略
+-   可通过 `proxies` 声明式配置代理路由，避免在 `setup` 中手写转发逻辑
+-   开发模式会尽量把入口依赖的全局 CSS 提前注入到 SSR HTML，减少首屏布局抖动
 
 ### 方式 B：手动使用 `createServer()`
 
 适合以下情况：
 
-- 你需要完全控制服务启动流程
-- 你已经有自定义的 Hono / Node 集成方式
-- 你不希望依赖 Vite 插件生命周期
+-   你需要完全控制服务启动流程
+-   你已经有自定义的 Hono / Node 集成方式
+-   你不希望依赖 Vite 插件生命周期
 
 ### 方式 C：仅使用 Browser/Core
 
 适合以下情况：
 
-- 你不需要 SSR
-- 你只希望复用 Router / Intent / Controller / Framework 模型
+-   你不需要 SSR
+-   你只希望复用 Router / Intent / Controller / Framework 模型
 
 ---
 
@@ -141,9 +146,9 @@ pnpm add dotenv
 
 ### 当前 peer dependencies
 
-- `hono`
-- `@hono/node-server`
-- `vite`
+-   `hono`
+-   `@hono/node-server`
+-   `vite`
 
 如果你只使用浏览器侧能力，不一定需要全部安装；如果你使用 SSR、Server 或 Vite 插件，则建议全部安装。
 
@@ -155,8 +160,8 @@ pnpm add dotenv
 
 这意味着：
 
-- 浏览器构建时，会优先解析 browser-only entry，避免引入服务端实现
-- Node / SSR 环境下，会解析完整入口，包含 Browser、SSR、Server 全部导出
+-   浏览器构建时，会优先解析 browser-only entry，避免引入服务端实现
+-   Node / SSR 环境下，会解析完整入口，包含 Browser、SSR、Server 全部导出
 
 因此大多数情况下你可以直接这样写：
 
@@ -190,12 +195,14 @@ index.html
 vite.config.ts
 ```
 
-如果你需要注册 API 代理或额外 Hono 路由，可以增加：
+如果你需要注册额外 Hono 路由，可以增加：
 
 ```text
 src/setup.ts
 ```
 
+如果只是配置 API 代理，优先使用 `vite.config.ts` / `createServer()` 中的 `proxies`，通常不再需要单独写 `src/setup.ts`。
+
 ---
 
 ### 2. 编写 `index.html`
@@ -203,7 +210,7 @@ src/setup.ts
 你的 HTML 模板必须包含以下 SSR 占位符：
 
 ```html
-<!doctype html>
+<!DOCTYPE html>
 <html lang="<!--ssr-lang-->">
 	<head>
 		<meta charset="utf-8" />
@@ -218,12 +225,12 @@ src/setup.ts
 </html>
 ```
 
-| 占位符 | 用途 |
-| --- | --- |
-| `<!--ssr-lang-->` | 当前语言 |
+| 占位符            | 用途                    |
+| ----------------- | ----------------------- |
+| `<!--ssr-lang-->` | 当前语言                |
 | `<!--ssr-head-->` | SSR `<head>` 内容与样式 |
-| `<!--ssr-body-->` | 服务端渲染后的 HTML |
-| `<!--ssr-data-->` | 序列化后的服务端数据 |
+| `<!--ssr-body-->` | 服务端渲染后的 HTML     |
+| `<!--ssr-data-->` | 序列化后的服务端数据    |
 
 ---
 
@@ -343,7 +350,7 @@ export { serializeServerData };
 
 ---
 
-### 6. 如果你有自定义 Hono 路由，编写 `src/setup.ts`
+### 6. 如果你有自定义 Hono 路由（非代理类），编写 `src/setup.ts`
 
 ```ts
 import type { Hono } from "hono";
@@ -355,10 +362,14 @@ export default function setup(app: Hono) {
 
 建议优先导出 `default` 函数。
 
+`setup` 更适合放健康检查、业务回调、实验性接口等自定义路由。
+
+如果你的需求是“把 `/api/foo/*` 转发到某个 HTTPS 上游”，请优先使用 `proxies` 选项，让框架统一处理路径校验、认证头、缓存头和错误响应。
+
 `setup` 在插件中有两种用法：
 
-- 传入函数：适用于 `dev` / `preview`
-- 传入文件路径字符串：适用于 `dev` / `build` / `preview` / adapter
+-   传入函数：适用于 `dev` / `preview`
+-   传入文件路径字符串：适用于 `dev` / `build` / `preview` / adapter
 
 如果你需要让构建产物也包含这些路由，建议传入文件路径字符串。
 
@@ -376,6 +387,18 @@ export default defineConfig({
 			locales: ["zh", "en"],
 			defaultLocale: "en",
 			ssr: { entry: "src/ssr.ts" },
+			renderModes: {
+				"/search": "csr",
+				"/stories/*": "prerender",
+			},
+			proxies: [
+				{
+					prefix: "/api/itunes",
+					target: "https://itunes.apple.com",
+					cache: "public, max-age=300, s-maxage=600",
+					followRedirects: true,
+				},
+			],
 			setup: "src/setup.ts",
 			adapter: "node",
 		}),
@@ -385,13 +408,52 @@ export default defineConfig({
 
 当前支持的 adapter：
 
-- `"node"`
-- `"vercel"`
-- `"cloudflare"`
-- `"netlify"`
-- `"static"`
-- `"auto"`
-- 或自定义 `Adapter` 对象
+-   `"node"`
+-   `"vercel"`
+-   `"cloudflare"`
+-   `"netlify"`
+-   `"static"`
+-   `"auto"`
+-   或自定义 `Adapter` 对象
+
+### `renderModes` 与 `proxies` 的推荐用法
+
+#### `renderModes`
+
+`renderModes` 用于在 Vite 插件层按 URL 覆盖渲染模式，优先级高于路由定义里的 `renderMode`。
+
+支持两种 key：
+
+-   精确路径：如 `"/search"`
+-   glob 模式：如 `"/stories/*"`
+
+可用值：
+
+-   `"ssr"`
+-   `"csr"`
+-   `"prerender"`
+
+当你需要“页面逻辑不变，但按部署 / 产品策略切换渲染方式”时，优先改这里，而不是到各个路由定义里逐个改。
+
+#### `proxies`
+
+`proxies` 用于声明式注册代理路由，适合 Apple API、RSS、上游聚合接口这类“路径前缀固定、目标域名固定”的转发场景。
+
+每一项支持这些关键字段：
+
+-   `prefix`：本地路由前缀，如 `"/api/itunes"`
+-   `target`：上游 HTTPS 地址
+-   `methods`：允许的方法列表，默认 `["all"]`
+-   `headers`：附加请求头
+-   `auth`：从环境变量读取 Bearer / Basic 认证
+-   `cache`：统一设置 `Cache-Control`
+-   `followRedirects`：是否跟随 3xx
+
+相比在 `setup` 中手写 Hono 代理，`proxies` 的好处是：
+
+-   框架统一做 SSRF 基础防护
+-   dev / preview / adapter 构建产物行为一致
+-   代理逻辑更容易复用和审查
 
 ---
 
@@ -669,7 +731,7 @@ export const render = createSSRRender({
 
 输出：
 
-- `dist/server/index.mjs`
+-   `dist/server/index.mjs`
 
 运行方式：
 
@@ -679,10 +741,10 @@ node dist/server/index.mjs
 
 适合：
 
-- Node 服务器
-- Docker
-- VPS
-- PM2
+-   Node 服务器
+-   Docker
+-   VPS
+-   PM2
 
 ---
 
@@ -690,14 +752,14 @@ node dist/server/index.mjs
 
 输出：
 
-- `.vercel/output/config.json`
-- `.vercel/output/static/`
-- `.vercel/output/functions/ssr.func/`
+-   `.vercel/output/config.json`
+-   `.vercel/output/static/`
+-   `.vercel/output/functions/ssr.func/`
 
 说明：
 
-- 它不在 `dist/` 中，这是平台约定
-- 对应 Vercel Build Output API v3
+-   它不在 `dist/` 中，这是平台约定
+-   对应 Vercel Build Output API v3
 
 建议将 `.vercel/` 加入 `.gitignore`。
 
@@ -707,13 +769,13 @@ node dist/server/index.mjs
 
 输出：
 
-- `.netlify/functions-internal/ssr/index.mjs`
-- `dist/client/_redirects`
+-   `.netlify/functions-internal/ssr/index.mjs`
+-   `dist/client/_redirects`
 
 说明：
 
-- `.netlify/` 在 `dist/` 外同样属于平台约定
-- 常见发布目录是 `dist/client/`
+-   `.netlify/` 在 `dist/` 外同样属于平台约定
+-   常见发布目录是 `dist/client/`
 
 建议将 `.netlify/` 加入 `.gitignore`。
 
@@ -723,13 +785,13 @@ node dist/server/index.mjs
 
 输出：
 
-- `dist/cloudflare/_worker.js`
-- `dist/cloudflare/assets/`
+-   `dist/cloudflare/_worker.js`
+-   `dist/cloudflare/assets/`
 
 说明：
 
-- Cloudflare Workers 不是完整 Node.js 环境
-- 如果运行时代码依赖 Node API，可能需要额外兼容配置
+-   Cloudflare Workers 不是完整 Node.js 环境
+-   如果运行时代码依赖 Node API，可能需要额外兼容配置
 
 ---
 
@@ -737,13 +799,13 @@ node dist/server/index.mjs
 
 输出：
 
-- `dist/static/`
+-   `dist/static/`
 
 适合：
 
-- 纯静态托管
-- CDN / 对象存储 / Pages 类平台
-- 不依赖运行时服务端逻辑的页面
+-   纯静态托管
+-   CDN / 对象存储 / Pages 类平台
+-   不依赖运行时服务端逻辑的页面
 
 它会执行：
 
@@ -758,14 +820,14 @@ node dist/server/index.mjs
 
 例如这些通常会自动生成：
 
-- `/`
-- `/search`
-- `/about`
+-   `/`
+-   `/search`
+-   `/about`
 
 这些通常不会自动生成：
 
-- `/product/:id`
-- `/list/:category`
+-   `/product/:id`
+-   `/list/:category`
 
 如果你要预渲染动态地址，请补充具体 URL：
 
@@ -787,8 +849,8 @@ finesoftFrontViteConfig({
 
 常见解决方式：
 
-- 构建期确保 API 可访问
-- 为 Controller 提供 fallback / mock 数据
+-   构建期确保 API 可访问
+-   为 Controller 提供 fallback / mock 数据
 
 ##### 3）验证静态产物时，应直接查看 `dist/static/`
 
@@ -805,10 +867,10 @@ python3 -m http.server 3000
 
 自动识别顺序：
 
-- `VERCEL` → `vercel`
-- `CF_PAGES` → `cloudflare`
-- `NETLIFY` → `netlify`
-- 默认 → `node`
+-   `VERCEL` → `vercel`
+-   `CF_PAGES` → `cloudflare`
+-   `NETLIFY` → `netlify`
+-   默认 → `node`
 
 适合 CI 或平台自动识别场景。
 
@@ -852,6 +914,13 @@ const { app, vite, runtime } = await createServer({
 	locales: ["zh", "en"],
 	defaultLocale: "en",
 	port: 3000,
+	proxies: [
+		{
+			prefix: "/api/itunes",
+			target: "https://itunes.apple.com",
+			followRedirects: true,
+		},
+	],
 	setup(app) {
 		app.get("/api/health", (c) => c.json({ ok: true }));
 	},
@@ -872,15 +941,15 @@ void runtime;
 3. 检测当前运行时
 4. 在开发模式下创建 Vite middleware server
 5. 创建 Hono app
-6. 先注册业务路由
+6. 先注册声明式代理路由，再注册自定义业务路由
 7. 再挂载 SSR catch-all
 8. 启动服务
 
 默认行为：
 
-- `root` 默认值：`process.cwd()`
-- `port` 默认值：`process.env.PORT ?? 3000`
-- 根目录存在 `.env` 且安装了 `dotenv` 时，会尝试自动加载
+-   `root` 默认值：`process.cwd()`
+-   `port` 默认值：`process.env.PORT ?? 3000`
+-   根目录存在 `.env` 且安装了 `dotenv` 时，会尝试自动加载
 
 ---
 
@@ -920,16 +989,16 @@ startBrowserApp({
 
 现象：
 
-- 页面未正常 hydrate
-- SSR 内容缺失
-- 服务端数据未注入
+-   页面未正常 hydrate
+-   SSR 内容缺失
+-   服务端数据未注入
 
 请检查以下四个占位符是否全部存在：
 
-- `<!--ssr-lang-->`
-- `<!--ssr-head-->`
-- `<!--ssr-body-->`
-- `<!--ssr-data-->`
+-   `<!--ssr-lang-->`
+-   `<!--ssr-head-->`
+-   `<!--ssr-body-->`
+-   `<!--ssr-data-->`
 
 ---
 
@@ -937,47 +1006,56 @@ startBrowserApp({
 
 原因：
 
-- 直接传函数主要适用于 `dev` / `preview`
-- 构建期更适合通过文件路径构建 `setup` 模块
+-   直接传函数主要适用于 `dev` / `preview`
+-   构建期更适合通过文件路径构建 `setup` 模块
 
 建议：
 
-- 使用文件路径字符串，例如 `setup: "src/setup.ts"`
+-   使用文件路径字符串，例如 `setup: "src/setup.ts"`
+
+### 3. 什么时候该用 `proxies`，什么时候该用 `setup`
+
+一般可以这样判断：
+
+-   **固定前缀 → 固定 HTTPS 上游**：用 `proxies`
+-   **自定义 JSON 接口 / webhook / health check / 特殊中间件**：用 `setup`
+
+如果你在 `setup` 里主要写的是“拼接目标 URL 再 `fetch` 转发”，那大概率更适合迁移到 `proxies`。
 
 ---
 
-### 3. `static` 模式下动态路由没有页面
+### 4. `static` 模式下动态路由没有页面
 
 原因：
 
-- `staticAdapter()` 只会自动预渲染无参数路由
+-   `staticAdapter()` 只会自动预渲染无参数路由
 
 解决方式：
 
-- 使用 `dynamicRoutes` 提供具体 URL
+-   使用 `dynamicRoutes` 提供具体 URL
 
 ---
 
-### 4. `static` 模式构建出来的是错误页
+### 5. `static` 模式构建出来的是错误页
 
 原因通常是：
 
-- 构建期 Controller 访问外部 API 失败
-- 但 fallback 没有提供可用的本地数据
+-   构建期 Controller 访问外部 API 失败
+-   但 fallback 没有提供可用的本地数据
 
 解决方式：
 
-- 保证构建期 API 可访问，或
-- 给 Controller 提供 fallback / mock 数据
+-   保证构建期 API 可访问，或
+-   给 Controller 提供 fallback / mock 数据
 
 ---
 
-### 5. `.vercel/` 和 `.netlify/` 为什么不在 `dist/`
+### 6. `.vercel/` 和 `.netlify/` 为什么不在 `dist/`
 
 这是平台约定，不是框架异常：
 
-- Vercel 使用 `.vercel/output/`
-- Netlify 使用 `.netlify/functions-internal/`
+-   Vercel 使用 `.vercel/output/`
+-   Netlify 使用 `.netlify/functions-internal/`
 
 建议将这些目录加入 `.gitignore`。
 

package/dist/browser.cjs

@@ -948,7 +948,7 @@ var History = class {
     this.log.info("saving scroll position", scrollTop);
   }
   onPopState(listener) {
-    window.addEventListener("popstate", (event) => {
+    window.addEventListener("popstate", async (event) => {
       this.currentStateId = event.state?.id;
       if (!this.currentStateId) {
         this.log.warn(
@@ -958,7 +958,7 @@ var History = class {
       }
       this.log.info("popstate", this.entries, this.currentStateId);
       const entry = this.currentStateId ? this.entries.get(this.currentStateId) : void 0;
-      listener(window.location.href, entry?.state);
+      await listener(window.location.href, entry?.state);
       if (!entry) {
         return;
       }