@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.12 → 3.2.0-ultramodern.121

package/docs/zh/components/init-app.mdx

@@ -1,64 +1,32 @@
-Modern.js 提供了 `@modern-js/create` 工具来创建项目，不需要全局安装，直接使用 `npx` 按需运行即可。
+UltraModern.js 提供 BleedingDev create 包来创建 SuperApp workspace，不需要全局安装，直接使用 `pnpm dlx` 按需运行即可。
 
-你可以在已有的空目录来创建项目：
+pnpm 支持的命令契约是 scoped package specifier：
+`pnpm dlx @bleedingdev/modern-js-create <target>`。不要简写成
+`pnpm dlx modern-js-create`；npm 上没有这个未加 scope 的包。
+
+你可以在当前已有的空目录中初始化项目：
 
 ```bash
 mkdir myapp && cd myapp
-npx @modern-js/create@latest
+pnpm dlx @bleedingdev/modern-js-create .
 ```
 
 也可以直接用新目录创建项目：
 
 ```bash
-npx @modern-js/create@latest myapp
-```
-
-初始化 TanStack Router 模板：
-
-```bash
-npx @modern-js/create@latest myapp --router tanstack
-```
-
-初始化 Tailwind CSS v4 模板：
-
-```bash
-npx @modern-js/create@latest myapp --tailwind
-```
-
-同时初始化 TanStack Router + Tailwind CSS v4：
-
-```bash
-npx @modern-js/create@latest myapp --router tanstack --tailwind
-```
-
-初始化当前默认运行时的 BFF 模板：
-
-```bash
-npx @modern-js/create@latest myapp --bff
-```
-
-初始化带 Effect HttpApi 运行时的 BFF 模板：
-
-```bash
-npx @modern-js/create@latest myapp --bff-runtime effect
-```
-
-初始化带 Hono 运行时的 BFF 模板：
-
-```bash
-npx @modern-js/create@latest myapp --bff-runtime hono
+pnpm dlx @bleedingdev/modern-js-create myapp
 ```
 
 使用 workspace 协议依赖初始化（用于在本地 monorepo 中联调未发布的 Modern.js 包）：
 
 ```bash
-npx @modern-js/create@latest myapp --router tanstack --bff-runtime effect --workspace
+pnpm dlx @bleedingdev/modern-js-create myapp --workspace
 ```
 
-`@modern-js/create` 会直接创建应用，不再提供问答界面：
+BleedingDev create 包会直接创建应用，不再提供问答界面：
 
 ```bash
-🚀 欢迎使用 Modern.js
+🚀 欢迎使用 UltraModern.js
 
 📦 正在创建项目 "myapp"...
 
@@ -87,31 +55,34 @@ npx @modern-js/create@latest myapp --router tanstack --bff-runtime effect --work
 
 ```
 .
-├── biome.json
-├── modern.config.ts
+├── apps
+│   └── shell-super-app
 ├── package.json
-├── README.md
-├── src
-│   ├── modern-app-env.d.ts
-│   ├── modern.runtime.ts
-│   └── routes
-│       ├── index.css
-│       ├── layout.tsx
-│       └── page.tsx
-└── tsconfig.json
+├── packages
+│   ├── shared-contracts
+│   ├── shared-design-tokens
+│   └── shared-effect-client
+├── scripts
+├── topology
+└── verticals
 ```
 
-当启用 `--tailwind` 时，项目根目录会额外生成 `postcss.config.mjs` 和 `tailwind.config.ts`。
+默认 workspace 从 shell 起步，并安装已发布的 BleedingDev 包别名：
 
-当启用 `--bff` 或 `--bff-runtime effect` 时，会在 `modern.config.ts` 中启用 `@modern-js/plugin-bff`，生成 `api/effect/index.ts` 与 `shared/effect/api.ts`，并将 `bff.runtimeFramework` 设置为 `effect`。
-当启用 `--bff-runtime hono` 时，会在 `modern.config.ts` 中启用 `@modern-js/plugin-bff`，生成 `api/lambda/hello.ts`，并将 `bff.runtimeFramework` 设置为 `hono`。
-当启用 `--workspace` 时，`@modern-js/*` 依赖会使用 `workspace:*` 版本，便于本地 monorepo 联调。
+```bash
+pnpm dlx @bleedingdev/modern-js-create my-super-app
+```
 
-如果你需要公开的 UltraModern.js SuperApp 路径，请使用 BleedingDev create 包。
-它默认生成规范的 Effect + TanStack + SSR + Micro Verticals workspace，并使用已发布的 BleedingDev 包别名：
+在已生成的 SuperApp workspace 根目录中，可以就地添加业务
+MicroVertical：
 
 ```bash
-pnpm dlx @bleedingdev/modern-js-create myapp
+pnpm dlx @bleedingdev/modern-js-create transportation --vertical
 ```
 
-底层 `--ultramodern-*` 参数只保留给发布工程和本地包源测试使用。
+`--vertical` 会修改当前 workspace：新增 vertical 包，并写入 topology、
+ownership 元数据、shell Module Federation、开发 overlays、包依赖、生成契约、
+路由归属 i18n、CSS 隔离，以及 Effect BFF/client surface。
+
+底层 `--ultramodern-package-*` 参数只保留给发布工程和本地包源测试使用。
+BleedingDev 包通过 GitHub Actions trusted publishing 发布；不要从开发机器手动发布。

package/docs/zh/components/init-rspack-app.mdx

@@ -1,5 +1,5 @@
 ```bash
-$ npx @modern-js/create@latest myapp
+$ pnpm dlx @bleedingdev/modern-js-create myapp
 ? 请选择开发语言：TS
 ? 请选择包管理工具：pnpm
 ```

package/docs/zh/components/prerequisites.mdx

@@ -9,8 +9,7 @@ import NodeVersion from '@site-docs/components/nodeVersion.mdx';
 推荐使用 [pnpm](https://pnpm.io/installation) 来管理依赖：
 
 ```bash
-corepack enable pnpm
-corepack prepare pnpm@11.1.2 --activate
+mise use pnpm@11.4.0
 ```
 
 :::note

package/docs/zh/components/serve-command.mdx

@@ -1,6 +1,6 @@
 ## modern serve
 
-`modern serve` 命令用于在生产环境下启动 Modern.js 工程, 也可以用于在本地预览生产环境构建的产物。注意你需要提前执行 [`build`](/apis/app/commands#modern-build) 命令构建出对应产物。
+`modern serve` 命令用于在生产环境下启动 UltraModern.js 工程, 也可以用于在本地预览生产环境构建的产物。注意你需要提前执行 [`build`](/apis/app/commands#modern-build) 命令构建出对应产物。
 
 ```bash
 Usage: modern serve [options]

package/docs/zh/configure/app/bff/effect.mdx

@@ -123,13 +123,35 @@ export default defineConfig({
 }
 ```
 
-- **默认值：** `{ enabled: true }`
+- **默认值：**
+
+```ts
+{
+  enabled: true,
+  requireEnvelope: false,
+  envelopeHeader: 'x-modernjs-data-envelope',
+  validateOrigin: true,
+  requireTraceContext: false,
+  batch: {
+    enabled: true,
+    endpoint: '/_data/batch',
+    maxBatchSize: 16,
+    maxBatchBytes: 64 * 1024,
+    flushIntervalMs: 8,
+    maxConcurrency: 4,
+    requestTimeoutMs: 10000,
+    allowedMethods: ['GET'],
+  },
+}
+```
 
 用于配置 Effect 运行时的数据请求信封（envelope）校验策略。
 
 生成的 Effect 客户端会将批处理请求发送到 `${bff.prefix}${batch.endpoint}`（例如 `/bff-api/_data/batch`）。
 
-当 `validateOrigin` 开启时，运行时会优先将 envelope 中的 origin 与请求 `Origin` 头比对；若请求无 `Origin`，则回退到请求 URL 的 origin。
+Envelope 校验默认开启但不是强制的：未携带 envelope 的请求会继续通过，除非将 `requireEnvelope` 设为 `true`。如果请求携带 envelope，运行时会按配置校验命名空间、origin、trace 与 selection 策略。`expectedNamespace` 默认不设置，`selection` 默认也不限制，除非显式配置。
+
+Origin 校验默认开启。运行时会优先将 envelope 中的 origin 与请求 `Origin` 头比对；若请求无 `Origin`，则回退到请求 URL 的 origin；设置 `validateOrigin: false` 可关闭该比对。
 
 ```ts title="modern.config.ts"
 export default defineConfig({
@@ -150,3 +172,5 @@ export default defineConfig({
 ```
 
 `batch.flushIntervalMs` 用于控制生成的 Effect 客户端微批处理窗口；`maxConcurrency` 与 `requestTimeoutMs` 由服务端批处理网关用于内部请求分发。
+
+生成的 `effectBff.client.*` API 只存在于 loader 物化后的 `@api/effect/*` 导入中。直接导入服务端入口（`api/effect/index`）时拿到的是 Effect BFF 定义；其中的 `client` 属性只是占位，并会在访问具体操作时报错。

package/docs/zh/configure/app/bff/runtime-framework.mdx

@@ -25,4 +25,4 @@ export default defineConfig({
 - 设置为 `'hono'` 时，仅从 `api/lambda/**` 的文件约定处理函数运行 BFF。
 
 两种运行时之间没有隐式回退，应用需要显式选择其一。
-如果需要优先使用 Effect 分支的公开 UltraModern 预设，请在应用中显式设置，或使用 create 模板提供的 Effect 脚手架路径。
+生成的 UltraModern 应用默认使用 Effect 分支；仅在需要兼容运行时时设置 `runtimeFramework: 'hono'`。

package/docs/zh/configure/app/performance/rsdoctor.mdx

@@ -11,22 +11,23 @@ type RsdoctorConfig =
   | boolean
   | {
       enabled?: boolean;
+      disableClientServer?: boolean;
     };
 ```
 
-- **默认值：** 生产构建时为 `true`，开发模式下为 `false`。
+- **默认值：** `undefined`，未配置该选项时不会启用 Rsdoctor。
 
-用于配置 Modern.js 构建过程中的 Rsdoctor 诊断能力。
+用于配置 Modern.js 构建过程中的 Rsdoctor 诊断能力。将该选项设为 `true` 即可启用 Rsdoctor：
 
 ```ts title="modern.config.ts"
 export default defineConfig({
   performance: {
-    rsdoctor: false,
+    rsdoctor: true,
   },
 });
 ```
 
-你也可以使用对象形式：
+你也可以使用对象形式。提供对象配置时，除非将 `enabled` 设为 `false`，否则会启用 Rsdoctor：
 
 ```ts title="modern.config.ts"
 export default defineConfig({
@@ -37,3 +38,5 @@ export default defineConfig({
   },
 });
 ```
+
+如果需要在共享配置中关闭已经启用的 Rsdoctor，可以将 `rsdoctor` 设为 `false`，或将 `enabled` 设为 `false`。

package/docs/zh/configure/app/tools/ts-checker.mdx

@@ -2,6 +2,8 @@
 title: tsChecker
 ---
 
+import { PackageManagerTabs } from '@theme';
+
 # tools.tsChecker
 
 - **类型：** `Object | Function`
@@ -14,6 +16,8 @@ const defaultOptions = {
     memoryLimit: 8192,
     // use tsconfig of user project
     configFile: tsconfigPath,
+    // use TypeScript Go checker by default
+    tsgo: true,
     // use TS-Go native preview of user project
     typescriptPath: require.resolve('@typescript/native-preview/package.json'),
   },
@@ -35,7 +39,7 @@ const defaultOptions = {
 },
 ```
 
-默认情况下，Modern.js 会开启 [@rsbuild/plugin-type-check](https://github.com/rspack-contrib/rsbuild-plugin-type-check) 进行类型检查。你可以通过 `output.disableTsChecker` 配置项来关闭类型检查。
+默认情况下，Modern.js 会开启 [@rsbuild/plugin-type-check](https://github.com/rstackjs/rsbuild-plugin-type-check) 进行类型检查。你可以通过 `output.disableTsChecker` 配置项来关闭类型检查。
 
 ## 示例
 
@@ -53,4 +57,28 @@ export default {
 };
 ```
 
-> 请参考 [@rsbuild/plugin-type-check](https://github.com/rspack-contrib/rsbuild-plugin-type-check) 了解更多用法。
+## TypeScript Go 默认开启
+
+类型检查默认使用 [TypeScript Go](https://github.com/microsoft/typescript-go)（`tsgo`）。该能力由 [`@rsbuild/plugin-type-check`](https://github.com/rstackjs/rsbuild-plugin-type-check) 底层集成的 [`ts-checker-rspack-plugin`](https://github.com/rstackjs/ts-checker-rspack-plugin) 提供，可以将类型检查耗时减少约 5-10 倍。
+
+`@typescript/native-preview` 已随构建器内置，无需额外安装。如需固定版本，可在项目中自行安装：
+
+<PackageManagerTabs command="install @typescript/native-preview -D" />
+
+开启 `tsgo` 后，默认的 `typescript.typescriptPath` 会解析到 `@typescript/native-preview/package.json`。如果你手动设置了 `typescript.typescriptPath`，它必须是指向 `@typescript/native-preview/package.json` 的绝对路径。
+
+如需回退到经典 TypeScript 检查器，请将 `typescript.tsgo` 设置为 `false`，并确保项目中安装了 `typescript`：
+
+```ts
+export default {
+  tools: {
+    tsChecker: {
+      typescript: {
+        tsgo: false,
+      },
+    },
+  },
+};
+```
+
+关于 `tsgo` 模式下生效的配置项和相关限制，请参考 [ts-checker-rspack-plugin - TypeScript Go support](https://github.com/rstackjs/ts-checker-rspack-plugin#typescript-go-support)。

package/docs/zh/configure/app/usage.mdx

@@ -117,7 +117,7 @@ Modern.js 命令行支持通过 `--config` 选项来指定配置文件的名称
 ```json title="package.json"
 {
   "scripts": {
-    "dev": "modern modern",
+    "dev": "modern dev",
     "build": "modern build --config modern.prod.config.ts"
   }
 }

package/docs/zh/guides/advanced-features/bff/data-platform.mdx

@@ -55,12 +55,14 @@ export default defineConfig({
 });
 ```
 
-当启用 `validateOrigin` 时，Effect 运行时会优先使用请求中的 `Origin` 头进行 origin 校验；若不存在 `Origin`，则回退到请求 URL 的 origin。
+Envelope 校验默认开启，但只有设置 `requireEnvelope` 时才强制要求请求携带 envelope。Origin 校验默认开启；设置 `validateOrigin: false` 后，运行时不会再将 envelope 中的 origin 与请求 `Origin` 头比对，也不会在缺少该请求头时回退到请求 URL 的 origin。
 
 ## Effect 客户端自动行为
 
 使用生成的 Effect 客户端（`@api/effect/index`）时，Modern.js 会在同源请求中自动附加序列化的 envelope 请求头（`x-modernjs-data-envelope`）。
 
+生成客户端由 loader 物化。请在浏览器或会被客户端打包的代码中通过 `@api/effect/*` 导入；直接导入服务端入口（`api/effect/index`）时拿到的是 Effect BFF 定义，其中只包含占位的 `client`。
+
 Envelope 默认包含：
 
 - operation 元数据

package/docs/zh/guides/advanced-features/bff/frameworks.mdx

@@ -105,7 +105,7 @@ const layer = HttpApiBuilder.layer(bffEffectApi).pipe(
 export default defineEffectBff({ api: bffEffectApi, layer });
 ```
 
-在浏览器端通过 `@api/effect/index` 调用接口：
+在浏览器代码中通过 `@api/effect/index` 调用接口：
 
 ```ts title="src/routes/page.tsx"
 import effectBff from '@api/effect/index';
@@ -113,6 +113,8 @@ import effectBff from '@api/effect/index';
 const response = await effectBff.client.hello.ping({});
 ```
 
+`effectBff.client.*` 由 BFF loader 针对 `@api/effect/*` 导入物化生成。不要直接导入 `api/effect/index` 并期望在服务端代码、脚本或测试中运行 `client`；直接导入入口时拿到的是服务端运行时定义，其中的 `client` 只是类型占位。
+
 import Hono from '@site-docs/components/hono';
 
 <Hono />

package/docs/zh/guides/advanced-features/international/api.mdx

@@ -15,10 +15,13 @@ title: API 参考
 | `language` | `string` | 当前语言代码 |
 | `changeLanguage` | `(lang: string) => Promise<void>` | 切换语言 |
 | `supportedLanguages` | `string[]` | 支持的语言列表（来自 `localeDetection.languages`） |
+| `localisedUrls` | `boolean \| Record<string, Record<string, string>>` | 来自 `localeDetection.localisedUrls` 的本地化 URL 映射 |
 | `isLanguageSupported` | `(lang: string) => boolean` | 检查语言是否在支持列表中 |
 | `isResourcesReady` | `boolean` | 当前语言的翻译资源是否已加载完成 |
 | `i18nInstance` | `I18nInstance` | i18next 实例（用于高级场景） |
 
+启用 `localePathRedirect` 且省略 `localisedUrls` 时，Modern.js 会保持 `/en/about` 这类仅语言前缀路径。只有提供非空 `localisedUrls` 映射时，才会启用路径片段翻译。也只有在该映射启用时，路由生成才会校验每个可本地化路径是否覆盖所有已配置语言。
+
 ### 基本用法
 
 ```tsx
@@ -91,7 +94,7 @@ function MyComponent() {
 | `children` | `React.ReactNode` | 是 | 链接内容 |
 | `replace` | `boolean` | 否 | 使用 `history.replace` 而非 `push` |
 | `state` | `any` | 否 | 传递给目标路由的状态 |
-| 其他 Link props | — | 否 | 继承自 `@modern-js/runtime/router` 的 `Link` 组件 |
+| 其他 Link props | — | 否 | 有可用路由时会传递给当前路由的 Link 组件 |
 
 ### 用法
 

package/docs/zh/guides/advanced-features/international/configuration.mdx

@@ -48,6 +48,7 @@ export default defineConfig({
 | `languages` | `string[]` | `[]` | 支持的语言列表 |
 | `fallbackLanguage` | `string` | `''` | 语言检测失败时的兜底语言 |
 | `localePathRedirect` | `boolean` | `false` | 接管 URL 语言前缀的识别、重定向和切换，详见[路由集成](./routing.md#启用语言路径前缀) |
+| `localisedUrls` | `boolean \| Record<string, Record<string, string>>` | 仅语言前缀行为 | 本地化路由路径映射。只有非空映射会启用路径片段翻译；省略、`true`、`false` 和 `{}` 都会保留语言前缀但不翻译路径片段。 |
 | `i18nextDetector` | `boolean` | `false` | 启用 i18next 检测器（Cookie / Header 等） |
 | `detection` | `LanguageDetectorOptions` | — | i18next 检测器详细配置，见[语言检测](./locale-detection.md) |
 | `ignoreRedirectRoutes` | `string[] \| Function` | — | 跳过重定向的路由，见[语言检测](./locale-detection.md#ignoreredirectroutes) |

package/docs/zh/guides/advanced-features/international/locale-detection.mdx

@@ -113,7 +113,7 @@ i18nPlugin({
 
 ## ignoreRedirectRoutes
 
-指定哪些路径跳过语言路径重定向，适用于 API 路由、静态资源等不需要语言前缀的路径。
+指定哪些额外路径跳过语言路径重定向。Modern.js 会自动跳过服务端 API 路由、启用 BFF 但未配置前缀时的默认 `/api` 前缀，以及自定义 `bff.prefix`。`ignoreRedirectRoutes` 适用于其他不需要语言前缀的非 API 业务路径。
 
 **写法一：字符串数组**（支持精确匹配和前缀匹配）
 

package/docs/zh/guides/advanced-features/international/routing.mdx

@@ -32,7 +32,50 @@ i18nPlugin({
 | `/en/about` | 正常访问，语言为 `en` |
 | `/zh/about` | 正常访问，语言为 `zh` |
 
-某些路径（如 API 路由、静态资源）不需要语言前缀，可以通过 `ignoreRedirectRoutes` 跳过重定向，详见[语言检测 → ignoreRedirectRoutes](./locale-detection.md#ignoreredirectroutes)。
+API 和 BFF 前缀会自动跳过，包括服务端 API 路由、启用 BFF 但未配置前缀时的默认 `/api` 前缀，以及自定义 `bff.prefix`。这些路由不需要语言前缀，也不需要配置 `localisedUrls`。如果还有其他业务路径不应该重定向，可以使用 `ignoreRedirectRoutes`，详见[语言检测 → ignoreRedirectRoutes](./locale-detection.md#ignoreredirectroutes)。
+
+## 本地化 URL 路径
+
+默认情况下，`localePathRedirect` 只会添加和识别语言前缀，例如 `/en/about`。翻译路径片段需要显式开启：只有提供非空 `localisedUrls` 映射时才会启用。省略 `localisedUrls`、设置为 `true`、设置为 `false` 或传入空对象时，都会保持仅语言前缀的行为。
+
+配置非空 `localisedUrls` 映射后，每个可本地化的路由路径都必须为所有已配置语言提供 URL。如果向 `languages` 中新增语言，Modern.js 会在路由生成阶段失败，直到每个 `localisedUrls` 条目都补齐该语言。
+
+`localisedUrls` 同时适用于 React Router 和 TanStack Router 项目的约定式路由。不要为 API 路由、BFF 前缀或配置的 `bff.prefix` 添加本地化 URL 条目；这些路径会自动排除在语言重定向之外。
+
+```ts
+// modern.config.ts
+i18nPlugin({
+  localeDetection: {
+    localePathRedirect: true,
+    languages: ['en', 'cs'],
+    fallbackLanguage: 'en',
+    localisedUrls: {
+      '/terms-of-service': {
+        en: '/terms-of-service',
+        cs: '/podminky-pouzivani',
+      },
+      '/products': {
+        en: '/products',
+        cs: '/produkty',
+      },
+      '/products/:slug': {
+        en: '/products/:slug',
+        cs: '/produkty/:slug',
+      },
+    },
+  },
+});
+```
+
+**效果：**
+
+| 访问路径 | 结果 |
+| --- | --- |
+| `/terms-of-service` | 重定向到 `/en/terms-of-service` |
+| `/cs/terms-of-service` | 重定向到 `/cs/podminky-pouzivani` |
+| `/cs/podminky-pouzivani` | 正常访问，语言为 `cs` |
+
+当 preset、共享配置或生成的元数据本来会提供映射，但当前入口只希望保留语言前缀、不翻译路径片段时，可以设置 `localisedUrls: false` 作为逃生口。
 
 ## 路由配置
 
@@ -131,4 +174,4 @@ function Navigation() {
 <I18nLink to="/en/about">关于</I18nLink>
 ```
 
-`I18nLink` 继承自 `@modern-js/runtime/router` 的 `Link` 组件，支持 `replace`、`state`、`className` 等所有标准 Link props，完整 Props 类型见 [API 参考](./api.md#i18nlink-组件)。
+`I18nLink` 会使用当前启用的 Modern.js 路由。在 React Router 项目中渲染 React Router 的 `Link`；在 TanStack Router 项目中通过 TanStack Router 导航。完整 Props 类型见 [API 参考](./api.md#i18nlink-组件)。

package/docs/zh/guides/basic-features/debug/rsdoctor.mdx

@@ -2,14 +2,13 @@
 
 Rsdoctor 是一个 Rspack 构建分析工具。在 Modern.js 中，我们推荐使用 Rsdoctor 来对构建过程与构建产物进行诊断和分析。
 
-Modern.js 默认会在生产构建中开启 Rsdoctor。
+Modern.js 不会默认启用 Rsdoctor。当你需要在构建中运行 Rsdoctor 时，请配置 `performance.rsdoctor`。
 
 ## 执行构建
 
 ```ts title="modern.config.ts"
 export default defineConfig({
   performance: {
-    // 在 production build 默认启用
     rsdoctor: true,
   },
 });
@@ -21,7 +20,7 @@ npm run build
 
 ## 关闭 Rsdoctor
 
-如果你希望关闭 Rsdoctor：
+如果你希望在共享配置中关闭已经启用的 Rsdoctor：
 
 ```ts title="modern.config.ts"
 export default defineConfig({

package/docs/zh/guides/basic-features/deploy.mdx

@@ -38,7 +38,7 @@ MODERNJS_DEPLOY=netlify npx modern deploy
 npx modern deploy
 ```
 
-当执行 `modern deploy` 命令时，Modern.js 将生成可执行的部署产物，并在控制台输出以下内容：
+当执行 `modern deploy` 命令时，UltraModern.js 将生成可执行的部署产物，并在控制台输出以下内容：
 
 ```bash
 Static directory: `.output/static`
@@ -316,7 +316,7 @@ Github Pages 支持两种部署方式，通过分支部署或通过 Github Actio
 
 :::info
 
-1. 执行 `MODERNJS_DEPLOY=ghPages modern deploy`，Modern.js 会把可用于 github 部署的产物构建到 `.output` 目录。
+1. 执行 `MODERNJS_DEPLOY=ghPages modern deploy`，UltraModern.js 会把可用于 github 部署的产物构建到 `.output` 目录。
 2. 可以参考项目[示例](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr)。
 
 :::

package/docs/zh/guides/basic-features/render/_meta.json

@@ -1,10 +1 @@
-[
-  "overview",
-  "ssr",
-  "streaming-ssr",
-  "ssr-cache",
-  "ssg",
-  "rsc",
-  "tanstack-rsc",
-  "before-render"
-]
+["overview", "ssr", "streaming-ssr", "ssr-cache", "ssg", "rsc", "before-render"]

package/docs/zh/guides/basic-features/render/overview.mdx

@@ -48,6 +48,5 @@ Modern.js 支持多种渲染模式组合使用：
 - [服务端渲染（SSR）](/guides/basic-features/render/ssr)
 - [流式服务端渲染（Streaming SSR）](/guides/basic-features/render/streaming-ssr)
 - [React Server Components（RSC）](/guides/basic-features/render/rsc)
-- [TanStack Router RSC](/guides/basic-features/render/tanstack-rsc)
 - [静态站点生成（SSG）](/guides/basic-features/render/ssg)
 - [渲染缓存](/guides/basic-features/render/ssr-cache)

package/docs/zh/guides/basic-features/render/rsc.mdx

@@ -616,4 +616,3 @@ import DeployTip from '@site-docs/components/rsc-deploy-tip';
 - [数据缓存](/guides/basic-features/data/data-cache)
 - [服务端渲染（SSR）](/guides/basic-features/render/ssr)
 - [Streaming SSR](/guides/basic-features/render/streaming-ssr)
-- [TanStack Router RSC](/guides/basic-features/render/tanstack-rsc)

package/docs/zh/guides/basic-features/routes/routes.mdx

@@ -466,7 +466,7 @@ Modern.js 支持通过 `loading.tsx` 文件来解决这个问题，`routes/` 下
 
 ## 预加载
 
-大多数切换路由时白屏的情况，都可以通过定义 `<Loading>` 组件来优化体验。Modern.js 也支持在 `<Link>` 组件上定义 `prefetch` 属性，提前对静态资源和数据进行加载。
+大多数切换路由时白屏的情况，都可以通过定义 `<Loading>` 组件来优化体验。Modern.js 也支持在 `<Link>` 组件上定义 `prefetch` 和 `preload` 属性，提前对导航进行预热。
 
 对于有更高性能要求的应用，预加载可以进一步提升用户体验，减少展示 `<Loading>` 组件的时间：
 
@@ -476,21 +476,36 @@ Modern.js 支持通过 `loading.tsx` 文件来解决这个问题，`routes/` 下
 
 :::tip
 
-对数据的预加载目前只会预加载 SSR 项目中 [Data Loader](/guides/basic-features/data/data-fetch) 中返回的数据。
+在 SSR 项目中，同源路由会为匹配到且带有可调用 loader 的路由预取 [Data Loader](/guides/basic-features/data/data-fetch) 返回的数据。如果某个路由的 loader 数据不应该在导航前请求，可以将该路由的 `handle.navigationWarmup.data` 设置为 `false`。
 
 :::
 
-`prefetch` 属性有三个可选值：
+默认情况下，同源链接会在 `<Link>` 渲染时预取路由模块和匹配到的 loader 数据。当用户开启 Save-Data 或处于慢速网络时，Modern.js 会跳过这些自动预热。
 
-- `none`， 默认值，不会做 prefetch，没有任何额外的行为。
-- `intent`，这是我们推荐大多数场景下使用的值，当你把鼠标放在 Link 上时，会自动开始加载对应的分片和 Data Loader 中定义的数据，当鼠标移开时，会自动取消加载。在我们的测试中，即使是快速点击，也能减少大约 200ms 的加载时间。
-- `render`，当 `<Link>` 组件渲染时，就会加载对应的分片和 Data Loader 中定义的数据。
+`prefetch` 属性有四个可选值：
+
+- `render`，默认值。当 `<Link>` 组件渲染时，就会预热对应的路由模块。
+- `intent`，当用户聚焦、悬停或触摸链接时，会开始预热对应的路由模块。如果意图在预热开始前取消，预热也会取消。
+- `viewport`，当 `<Link>` 组件进入视窗时，会开始预热对应的路由模块。
+- `none`，关闭自动 prefetch。如果没有显式设置 `preload`，也会关闭隐式 preload。
+
+`preload` 属性接受同样的时机值，默认跟随 `prefetch` 的时机。显式设置的 `preload` 总是优先生效，`preload={false}` 会关闭 preload 行为。
+
+如果要让某个路由关闭 SSR 数据预热：
+
+```ts title="routes/page.config.ts"
+export const handle = {
+  navigationWarmup: {
+    data: false,
+  },
+};
+```
 
 :::details 值为 render 和不做路由分片的区别
 
-- `render` 加载路由分片的时机是可控的，只有在 `<Link>` 组件进入视窗时才触发，可以通过控制 `<Link>` 组件的渲染位置来控制分片加载时机。
-- `render` 仅在空闲时对静态资源进行加载，不占用重要模块的加载时间。
-- 除了预加载路由分片，`render` 在 SSR 项目中还会发起数据预取。
+- `render` 可以通过 `<Link>` 组件在组件树中的位置控制路由模块预热时机。
+- `viewport` 可以把模块预热推迟到链接接近可操作时再触发。
+- SSR 数据预取默认开启；当路由的 loader 数据不适合在导航前获取时，使用 `handle.navigationWarmup.data = false` 关闭。
 
 :::
 

package/docs/zh/guides/basic-features/testing/_meta.json

@@ -1 +1 @@
-["playwright", "rstest", "vitest", "jest", "cypress"]
+["rstest", "playwright"]

package/docs/zh/guides/concept/server.mdx

@@ -26,10 +26,10 @@ Modern.js 开发环境和生产环境的 Web 服务器流程是完全同构的
 
 Modern.js 支持在任何 Node.js 环境运行构建产物。在 CI 环境中，通常情况下已经安装了应用全部的依赖。
 
-你可以执行 [`modern build`](/apis/app/commands#modern-build) 来构建应用，执行 [`modern serve`](/apis/app/commands#modern-serve) 命令来运行 Web 服务器，启动 Modern.js 应用。
+你可以执行 [`modern build`](/apis/app/commands#modern-build) 来构建应用，执行 [`modern serve`](/apis/app/commands#modern-serve) 命令来运行 Web 服务器，启动 UltraModern.js 应用。
 
 ## 在生产环境中运行
 
 在部署到生产环境时，产物体积应该尽可能小，而上述在 CI 中运行的方案，会保留原项目的所有产物。因此在生产环境，不推荐通过上述命令运行应用。
 
-Modern.js 提供了独立的部署方案，当运行 [`modern deploy`](/apis/app/commands#modern-deploy) 命令时，产物中会包含可运行 Web 服务器的入口文件。
+UltraModern.js 提供了独立的部署方案，当运行 [`modern deploy`](/apis/app/commands#modern-deploy) 命令时，产物中会包含可运行 Web 服务器的入口文件。

package/docs/zh/guides/get-started/quick-start.mdx

@@ -25,7 +25,7 @@ import DebugApp from '@site-docs/components/debug-app';
 
 ## 使用配置
 
-通过 `@modern-js/create` 创建的 Modern.js 项目中，会默认生成 `modern.config.ts` 文件。
+通过 `@bleedingdev/modern-js-create` 创建的 UltraModern.js 项目中，会默认生成 `modern.config.ts` 文件。
 
 你可以通过该配置文件修改配置，覆盖 Modern.js 的默认行为。例如添加如下配置，开启 SSR：
 

package/docs/zh/guides/get-started/tech-stack.mdx

@@ -18,13 +18,13 @@ Modern.js 底层的 Rsbuild 支持构建 Vue 应用，如果你需要使用 Vue
 
 Modern.js 提供两套一方路由方案：
 
-- 默认使用 [React Router 7](https://reactrouter.com/en/main)，通过 `@modern-js/runtime/router` 导出 API。
-- 支持 [TanStack Router](https://tanstack.com/router)，通过 `@modern-js/plugin-tanstack/runtime` 导出 API。
+- 默认使用 [TanStack Router](https://tanstack.com/router)，通过 `@modern-js/plugin-tanstack/runtime` 导出 API。
+- 兼容 [React Router 7](https://reactrouter.com/en/main)，通过 `@modern-js/runtime/router` 导出 API。
 
-创建项目时，可通过以下命令选择 TanStack Router：
+创建 UltraModern 项目时，默认会包含 TanStack Router：
 
 ```bash
-npx @modern-js/create@latest myapp --router tanstack
+pnpm dlx @bleedingdev/modern-js-create myapp
 ```
 
 Modern.js 支持约定式路由、自控式路由或其他路由方案，请参考 [页面入口](/guides/concept/entries) 进行选择。
@@ -84,6 +84,12 @@ Modern.js 可以与社区中任意的 React 组件库搭配使用，比如 [MUI]
 
 Modern.js 支持使用 [Storybook](https://storybook.js.org/) 来开发 UI 组件。该功能为可选功能，请参考 [使用 Storybook](/guides/basic-features/debug/using-storybook) 启用。
 
+## 测试框架
+
+Modern.js 推荐使用 [Rstest](https://rstest.rs/) 编写单元测试和组件测试。Rstest 基于 Rspack 构建，启动和执行速度快，并且可以通过 [`@modern-js/adapter-rstest`](/guides/basic-features/testing/rstest) 复用 Modern.js 的应用配置。
+
+如果需要编写端到端（E2E）测试，可以使用 [Playwright](/guides/basic-features/testing/playwright)。
+
 ## Node.js 框架
 
 import TechStackNodeFramework from '@site-docs/components/tech-stack-node-framework';