@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.98 → 3.4.0-ultramodern.0

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` 关闭。
 
 :::
 
@@ -516,6 +531,6 @@ Modern.js 提供了按路由框架区分的运行时导出：
 
 :::note
 
-如果应用中必须直接使用 React Router 包的 API，例如部分路由行为被封装在统一的 npm 包中，那应用可以通过设置 [`source.alias`](/configure/app/source/alias)，将 `react-router` 和 `react-router-dom` 统一指向项目的依赖，避免两个版本的 React Router 同时存在的问题。
+如果应用中必须直接使用 React Router 包的 API，例如部分路由行为被封装在统一的 npm 包中，那应用可以通过设置 [`source.alias`](/configure/app/source/alias)，将 `react-router` 指向项目的依赖，避免两个版本的 React Router 同时存在的问题。
 
 :::

package/docs/zh/guides/basic-features/testing/rstest.mdx

@@ -8,6 +8,7 @@
 
 先安装基础依赖：
 
+import { Prompt } from '@rspress/core/theme';
 import { PackageManagerTabs } from '@theme';
 
 <PackageManagerTabs command="add @rstest/core @modern-js/adapter-rstest -D" />
@@ -161,3 +162,31 @@ test('Page', () => {
 如果你需要测试 `bff` 等 server-side logic，建议直接参考 [Rstest 文档](https://rstest.rs) 中关于 node mode 的说明。
 
 Modern.js 主要面向 web app，因此这里重点介绍的是 Web UI 测试，以及更贴近真实运行环境的 browser mode。
+
+## 从已有项目迁移
+
+如果你的项目已经使用 Jest 或 Vitest，可以参考 Rstest 官方迁移指南：
+
+- [从 Jest 迁移到 Rstest](https://rstest.rs/guide/migration/jest)
+- [从 Vitest 迁移到 Rstest](https://rstest.rs/guide/migration/vitest)
+
+推荐先安装 `migrate-to-rstest` skill，再复制下面的 Prompt 给编码 Agent；它会在迁移时保留 Modern.js 的 `@modern-js/adapter-rstest` 配置。
+
+<Prompt
+  title="迁移到 Rstest"
+  description="复制这个 Prompt 并发送给你的编码 Agent。"
+  prompt={`Migrate this Modern.js project from Jest or Vitest to Rstest.
+
+First install and use the migrate-to-rstest skill. If it is not installed, install it with:
+npx skills add rstackjs/agent-skills --skill migrate-to-rstest
+
+Follow the migrate-to-rstest skill instructions and the official Rstest migration guides:
+- Jest: https://rstest.rs/guide/migration/jest
+- Vitest: https://rstest.rs/guide/migration/vitest
+
+Modern.js-specific requirement:
+- Install and use @modern-js/adapter-rstest together with @rstest/core.
+- Create or update rstest.config.ts to import withModernConfig from @modern-js/adapter-rstest.
+- Reuse the Modern.js app configuration with extends: withModernConfig().
+- Do not replace this with a plain Rstest config unless the project explicitly does not need Modern.js config integration.`}
+/>

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

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

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

@@ -46,7 +46,7 @@ export default defineConfig({
 
 在新创建的工程中，默认会安装 `@modern-js/app-tools` npm 包，它是 Modern.js 框架的核心包，主要提供以下能力：
 
-- 提供 `ultramodern dev`, `ultramodern build` 等常用的 CLI 命令。
+- 提供 `modern dev`, `modern build` 等常用的 CLI 命令。
 - 集成 Rsbuild，提供构建能力。
 - 集成 Modern.js Server，提供开发和生产服务器相关能力。
 

package/docs/zh/guides/get-started/ultramodern.mdx

@@ -30,7 +30,7 @@ UltraModern.js 的增强能力是新 SuperApp 的默认产品面。兼容分支
 
 | 领域 | Modern.js 3.0 基线 | UltraModern.js 3.0 |
 | --- | --- | --- |
-| 构建诊断能力 | RsDoctor 多为显式开启 | 新增 `performance.rsdoctor`，并在 Rspack 生产构建默认开启，同时产出 `.rsdoctor/ultramodern-diagnostics.json` 契约文件 |
+| 构建诊断能力 | RsDoctor 多为显式开启 | 新增一等的 `performance.rsdoctor` 配置项（按需开启；早期的默认开启行为与诊断契约产物已回退） |
 | 输出与静态资源回源 | 预压缩策略通常由业务自定义 | 默认开启 `output.precompress`，并按 `Accept-Encoding` 协商 `.br` / `.gz` 回源 |
 | BFF 运行时与契约 | 提供标准 BFF 运行时与客户端生成能力 | 增加 `requestId` 维度隔离、初始化 fail-fast 校验与操作/追踪关联 Header |
 | BFF 运行时选型 | Modern.js 3.0 基线仅提供 Hono 运行时路径（无内建 Effect 运行时） | 将 Effect 设为默认运行时，并采用严格运行时拆分（`effect` -> `api/effect`，`hono` -> `api/lambda`），同时补齐 Effect-Schema-first 契约与 MF failure-injection 覆盖 |
@@ -40,7 +40,7 @@ UltraModern.js 的增强能力是新 SuperApp 的默认产品面。兼容分支
 | 模块准入治理 | 基线无模块认证证据化 gate profile | 新增模块 SDK 契约、边界反模式守卫与发布/模块认证 gate 工作流 |
 | 路由运行时 | 默认运行时路径以 React Router 为中心 | 增加 TanStack Router 运行时/CLI 一等支持（React Router 继续可用） |
 | 脚手架模板 | 默认 create 模板以 React Router 起步路径为中心 | 增加 TanStack-ready 与 Tailwind-ready 的 create 模板 |
-| Starter 预设约束 | 生成应用默认没有 UltraModern 预设 gate 工作流 | 生成脚手架会附带 `ultramodern:check`、可关闭的 env 开关，以及 `.github/workflows/ultramodern-gates.yml` |
+| Starter 预设约束 | 生成应用默认没有 UltraModern 预设 gate 工作流 | 生成 workspace 会附带 `.github/workflows/ultramodern-workspace-gates.yml`、`pnpm check`、基础本地 gate 与生成契约校验 |
 
 ## 我们刻意不做的事情
 
@@ -49,38 +49,51 @@ UltraModern.js 的增强能力是新 SuperApp 的默认产品面。兼容分支
 - 运行时保持 `effect` 与 `hono` 双模式并存，但不提供隐式回退。
 - 除非稳定性硬需求，否则避免引入破坏性 API 变更。
 
-## 迁移说明
+## 迁移指南
 
-对于已经在使用 Modern.js 3.0 的团队，迁移路径是“兼容感知”：保留能降低风险的部分，逐步向 MV-first / TanStack-first / Effect-first 默认方向收敛，并把 UltraModern.js 3.0 作为独立框架采用。
+对于已经在使用 Modern.js 3.0 或旧版 BleedingDev UltraModern scaffold 的团队，迁移路径是“兼容感知”：保留能降低风险的部分，逐步向 MV-first / TanStack-first / Effect-first 默认方向收敛，并把 UltraModern.js 3.0 作为独立框架采用。
 
 1. 既有 React Router 应用可以继续按现状运行。TanStack Router 是新脚手架与增量迁移的优先路径，但 React Router 兼容分支仍然保留，团队可以按自己的节奏迁移。
 2. 新建或迁移中的 BFF 能力优先使用 `bff.runtimeFramework: 'effect'`，并将入口实现放在 `api/effect/index.ts`。如果当前应用已经在 `api/lambda/**` 下使用 Hono 处理函数，就继续显式使用 `bff.runtimeFramework: 'hono'`，等准备好再迁移；Hono 仍是受支持的兼容分支。
 3. 将基线契约视为渐进式默认值，而不是一次性强制切换。`MODERN_BASELINE_ENABLE_MF_SSR`、`MODERN_BASELINE_ENABLE_BFF_REQUEST_ID` 和 `MODERN_BASELINE_ENABLE_TELEMETRY_EXPORTERS` 已经提供了按应用、按环境关闭的能力，方便在收敛到目标栈之前逐步过渡。
-4. 这套公开预设现在已经附带显式的发布 / 认证 gate。生成脚手架也会自带 `.github/workflows/ultramodern-gates.yml`，因此 `pnpm run ultramodern:check` 与 `pnpm run build` 从第一天开始就是接入契约的一部分。
+4. 这套公开预设现在已经附带显式的发布 / 认证 gate。生成 workspace 会自带 `.github/workflows/ultramodern-workspace-gates.yml`，因此 `pnpm check` 与 `pnpm build` 从第一天开始就是本地接入契约的一部分；CI 会以并行矩阵运行这些基础 gate。
 
-## 人类工作流
-
-公开的 BleedingDev create 包默认从简单路径开始。默认命令会创建一个
-可上线的 UltraModern 单应用，包含 `presetUltramodern(...)`、SSR、
-TanStack Router、Tailwind CSS v4、i18n、Effect BFF、生成质量 gate，以及
-Cloudflare 部署基础：
+旧版生成 workspace 迁移时，以已发布的包 cohort 作为事实来源：
 
 ```bash
-pnpm dlx @bleedingdev/modern-js-create myapp
-cd myapp
+pnpm dlx @bleedingdev/modern-js-create@latest --help
+pnpm dlx @bleedingdev/modern-js-create@latest catalog --vertical --dry-run
+pnpm dlx @bleedingdev/modern-js-create@latest catalog --vertical
 mise install
 mise exec -- pnpm install
-mise exec -- pnpm ultramodern:check
+mise exec -- pnpm check
+mise exec -- pnpm build
 ```
 
-只有当独立归属边界有实际价值时，才创建 SuperApp workspace：
+每个仓库只使用一种 package-source 策略。已发布的 BleedingDev create 包默认使用
+`--ultramodern-package-source=install`，并把精确 cohort 记录到
+`.modernjs/ultramodern-package-source.json`。`--workspace` 只用于本地 monorepo
+联调未发布包。发布证明和 CI 如果需要证明某个已发布框架版本，应使用
+`--ultramodern-package-version` 固定精确 cohort。
+
+安装新 cohort 后，先运行生成的
+`scripts/validate-ultramodern-workspace.mjs` 契约校验，再接受人工改动。topology、
+ownership、package-source、本地 overlay、生成契约、Tailwind prefix 或 Module
+Federation 冲突，都应在对应归属文件中修复，不要手写补丁覆盖生成结果。
+
+## 人类工作流
+
+公开的 BleedingDev create 包只有一个受支持的生成产品。默认命令会创建一个
+可上线的 UltraModern SuperApp workspace，包含 `presetUltramodern(...)`、
+SSR、TanStack Router、Tailwind CSS v4、i18n、Effect BFF、Module Federation
+topology、生成质量 gate，以及 Cloudflare 部署基础：
 
 ```bash
-pnpm dlx @bleedingdev/modern-js-create my-super-app --ultramodern-workspace
-cd my-super-app
+pnpm dlx @bleedingdev/modern-js-create myapp
+cd myapp
 mise install
 mise exec -- pnpm install
-mise exec -- pnpm ultramodern:check
+mise exec -- pnpm check
 ```
 
 workspace 从 shell 和平台契约起步，不强制生成演示业务域。真实业务边界出现后，
@@ -91,13 +104,94 @@ pnpm dlx @bleedingdev/modern-js-create transportation --vertical
 pnpm dlx @bleedingdev/modern-js-create food-delivery --vertical
 pnpm dlx @bleedingdev/modern-js-create payments --vertical
 pnpm dlx @bleedingdev/modern-js-create maps --vertical
-mise exec -- pnpm ultramodern:check
+mise exec -- pnpm check
 ```
 
 `--vertical` 会修改当前 workspace：创建 vertical 包，并更新 topology 元数据、
 ownership 记录、shell Module Federation、开发 overlays、包依赖、生成契约、
 端口、路由归属 i18n、CSS 隔离，以及 vertical 自己拥有的 Effect BFF/client surface。
 
+### 生成器自动化
+
+自动化脚本可以使用显式 MicroVertical 语法，不必依赖位置参数：
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create --vertical=transportation
+pnpm dlx @bleedingdev/modern-js-create --vertical-name transportation
+pnpm dlx @bleedingdev/modern-js-create transportation --vertical --dry-run
+pnpm dlx @bleedingdev/modern-js-create transportation --vertical \
+  --codesmith-overlay ./generators/vertical-overlay
+```
+
+BleedingDev create 包默认安装已发布的包 cohort。本地 monorepo 联调时使用
+`--workspace` 或 `--ultramodern-package-source=workspace`。发布证明与包源自动化还
+可以传入 `--ultramodern-package-source=install`、
+`--ultramodern-package-version`、`--ultramodern-package-registry`、
+`--ultramodern-package-scope` 与
+`--ultramodern-package-name-prefix`。
+
+受支持的公开生成器 import 是：
+
+```ts
+import {
+  addUltramodernVertical,
+  generateUltramodernWorkspace,
+  planUltramodernVertical,
+} from '@modern-js/create/ultramodern-workspace';
+
+const workspace = generateUltramodernWorkspace({
+  targetDir: '/tmp/my-workspace',
+  packageName: 'my-workspace',
+  modernVersion: '3.4.0',
+});
+
+const plan = planUltramodernVertical({
+  workspaceRoot: workspace.workspaceRoot,
+  name: 'transportation',
+  modernVersion: '3.4.0',
+});
+
+addUltramodernVertical({
+  workspaceRoot: workspace.workspaceRoot,
+  name: 'transportation',
+  modernVersion: '3.4.0',
+  overlays: [{ generator: './generators/vertical-overlay' }],
+});
+```
+
+公开结果包含 workspace root、包源、创建的 apps、创建路径、重写路径、分配端口、
+Module Federation 名称、Effect API 前缀、生成契约路径与 warnings。
+MicroVertical dry-run 返回相同结构，并额外包含 `dryRun`、`selectedPort`、
+`moduleFederationRemote`、`effectApiPrefix`、`jsonMutations`、
+`shellDependencyChanges` 与 `generatedContractChanges`；CLI 会输出 JSON，且不写文件。
+
+CodeSmith 消费方可以使用 adapter subpath：
+
+```ts
+import ultramodernCodeSmith from '@modern-js/create/ultramodern-workspace/codesmith';
+
+await ultramodernCodeSmith({
+  config: {
+    mode: 'vertical',
+    name: 'transportation',
+    workspaceRoot: process.cwd(),
+    dryRun: true,
+    logResult: true,
+  },
+});
+```
+
+校验会在第一次写文件前执行。缺失或非法的 vertical 名称、已存在 topology 占用
+app ID/路径/包后缀/端口/Module Federation 名称/API 前缀/manifest key、workspace
+JSON 契约缺失或不是对象、Tailwind 前缀冲突，都会报告归属契约。修复 workspace
+契约或选择新的 vertical 名称后再重新运行。
+
+Overlays 是显式配置的 CodeSmith 生成器，会在基础 workspace 或 MicroVertical
+生成之后运行。它们只扩展生成结果，不替换、不继承、也不遮蔽基础模板。公开生成器与
+CodeSmith adapter 都是普通 Node 生成器入口。包构建通过 TS-Go 工具链产出声明文件；
+生成出来的 app package 直接安装 TypeScript 7 RC 包线，并且只在本地工具链中使用
+TS-Go，运行时代码不依赖 native-preview compiler 内部实现。
+
 ### 运行时契约
 
 生成应用和 vertical 沿用正常的 Modern.js SSR 路径。SuperApp workspace 在需要
@@ -106,8 +200,13 @@ Module Federation SSR 时会加入 `server.ssr.moduleFederationAppSSR`，但这
 
 每个应用都会产出 `src/routes/ultramodern-route-metadata` 和
 `ultramodernLocalisedUrls`。i18n 插件在 `localeDetection.localisedUrls` 中读取它，
-并从 `/locales/{{lng}}/{{ns}}.json` 提供动态后端 JSON。路由 owner 需要同时维护
-本地化路径和 locale resource JSON。
+这就是在 `localePathRedirect` 之上启用路径片段翻译的显式非空映射。i18n 插件也会从
+`/locales/{{lng}}/{{ns}}.json` 提供动态后端 JSON。路由 owner 需要同时维护本地化路径和
+locale resource JSON。
+
+JSON-LD 是可选的路由 metadata，不会自动推断。私有路由和不可索引路由默认不输出
+JSON-LD。公开路由 owner 可以在本地化路径旁显式添加 `jsonLd`，并使用生成的
+`src/routes/ultramodern-jsonld.ts` helper 编写常见 schema.org 结构。
 
 生成契约会在 `.modernjs/ultramodern-generated-contract.json` 中写入
 `cssFederation`：
@@ -125,7 +224,7 @@ Module Federation SSR 时会加入 `server.ssr.moduleFederationAppSSR`，但这
 本地 gate：
 
 ```bash
-mise exec -- pnpm ultramodern:check
+mise exec -- pnpm check
 mise exec -- pnpm build
 mise exec -- pnpm cloudflare:build
 ```

package/docs/zh/guides/topic-detail/module-federation/application.mdx

@@ -104,7 +104,7 @@ export default RemoteApp;
 
 ## 启动应用
 
-现在，生产者应用和消费者应用都已经搭建完毕，我们可以在本地运行 `ultramodern dev` 启动两个应用。
+现在，生产者应用和消费者应用都已经搭建完毕，我们可以在本地运行 `modern dev` 启动两个应用。
 
 启动后，消费者应用访问 `/remote` 路由时，会进入生产者应用中。访问 `http://localhost:8080/remote`，可以看到页面中已经包含了生产者的远程模块的完整页面。
 

package/docs/zh/guides/topic-detail/module-federation/deploy.mdx

@@ -88,10 +88,10 @@ export default createModuleFederationConfig({
 
 ## 本地验证部署
 
-Modern.js 提供了 `ultramodern deploy` 命令，可以方便生成可运行在 Node.js 环境的产物。
+Modern.js 提供了 `modern deploy` 命令，可以方便生成可运行在 Node.js 环境的产物。
 
 ```bash
-ultramodern deploy
+modern deploy
 ```
 
 执行命令后，可以在控制台看到以下输出：

package/docs/zh/guides/topic-detail/module-federation/usage.mdx

@@ -154,7 +154,7 @@ export default Index;
 
 ## 启动应用
 
-现在，生产者应用和消费者应用都已经搭建完毕，我们可以在本地运行 `ultramodern dev` 启动两个应用。
+现在，生产者应用和消费者应用都已经搭建完毕，我们可以在本地运行 `modern dev` 启动两个应用。
 
 启动后，消费者中对生产者模块的引入，不会再出现抛错，类型已经下载到消费者应用中。
 
@@ -164,7 +164,7 @@ export default Index;
 
 访问 `http://localhost:8080/remote`，可以看到页面中已经包含了生产者的远程模块 `Button` 组件。
 
-我们也可以在本地执行 `ultramodern serve` 来模拟生产环境。
+我们也可以在本地执行 `modern serve` 来模拟生产环境。
 
 因为 Module Federation 插件会自动读取 Modern.js 的 `output.assetPrefix` 配置作为远程模块的访问地址，而该值在生产环境下构建后默认是 `/`。如果不做特殊处理，消费者将从自己的域名下拉取远程模块的入口文件。我们可以添加如下配置：
 
@@ -178,7 +178,7 @@ export default defineConfig({
     port: 3051,
   },
   output: {
-    // Now this configuration is only used in the local when you run ultramodern serve command.
+    // Now this configuration is only used in the local when you run modern serve command.
     // If you want to deploy the application to the platform, use your own domain name.
     // Module federation will automatically write it to mf-manifest.json, which influences consumer to fetch remoteEntry.js.
     assetPrefix: 'http://127.0.0.1:3051',
@@ -187,10 +187,10 @@ export default defineConfig({
 });
 ```
 
-现在，在生产者中运行 `ultramodern build && MODERN_MF_AUTO_CORS=true ultramodern serve`，在消费者中运行 `ultramodern build && ultramodern serve`，即可在本地模拟生产环境，访问到远程模块。
+现在，在生产者中运行 `modern build && MODERN_MF_AUTO_CORS=true modern serve`，在消费者中运行 `modern build && modern serve`，即可在本地模拟生产环境，访问到远程模块。
 
 :::tip
-在使用 `ultramodern serve` 命令时，需要在启动生产者项目时携带 `MODERN_MF_AUTO_CORS=true` 环境变量，以自动处理跨域问题，确保消费者可以正常访问生产者的远程模块资源。
+在使用 `modern serve` 命令时，需要在启动生产者项目时携带 `MODERN_MF_AUTO_CORS=true` 环境变量，以自动处理跨域问题，确保消费者可以正常访问生产者的远程模块资源。
 :::
 
 上述用例可以参考：[Modern.js & Module Federation 基础用法示例](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/module-federation/base)。

package/docs/zh/guides/troubleshooting/builder.mdx

@@ -23,7 +23,7 @@ Modern.js 内部基于 [Rsbuild](https://v2.rsbuild.rs/) 封装了自身的构
 Modern.js 提供 [inspect 命令](/apis/app/commands.html) 用于查看项目最终生成的 Modern.js 配置以及 Rspack 配置。
 
 ```bash
-➜ npx ultramodern inspect
+➜ npx modern inspect
 
 Inspect config succeed, open following files to view the content:
 

package/docs/zh/guides/upgrade/config.mdx

@@ -334,7 +334,7 @@ export default {
 
 ### tools.rsdoctor
 
-**变更内容**：该配置已废弃。v3 中 Modern.js 会在生产构建默认启用 Rsdoctor。可通过 [`performance.rsdoctor`](/configure/app/performance/rsdoctor) 进行配置或关闭。
+**变更内容**：该配置已废弃。v3 中可通过 [`performance.rsdoctor`](/configure/app/performance/rsdoctor) 显式启用 Rsdoctor 诊断能力。
 
 **迁移示例**：
 
@@ -350,7 +350,6 @@ tools: {
 // v3
 export default {
   performance: {
-    // 生产构建默认启用
     rsdoctor: {
       enabled: true,
     },

package/docs/zh/guides/upgrade/other.md

@@ -95,7 +95,7 @@ Modern.js 3.0 不再支持通过 `@bleedingdev/modern-js-create` 创建 Monorepo
 **变更内容**：
 
 - 在 [v2.53.0](https://github.com/web-infra-dev/modern.js/releases/tag/v2.53.0) 版本中，移除了使用 `@bleedingdev/modern-js-create` 创建 Monorepo 项目的功能
-- 在 [v2.61.0](https://github.com/web-infra-dev/modern.js/releases/tag/v2.61.0) 版本中，移除了使用 `@bleedingdev/modern-js-create` 和 `ultramodern new` 命令创建 Modern.js Module 项目的功能
+- 在 [v2.61.0](https://github.com/web-infra-dev/modern.js/releases/tag/v2.61.0) 版本中，移除了使用 `@bleedingdev/modern-js-create` 和 `modern new` 命令创建 Modern.js Module 项目的功能
 
 **处理方式**：
 
@@ -104,12 +104,12 @@ Modern.js 3.0 不再支持通过 `@bleedingdev/modern-js-create` 创建 Monorepo
 
 ## new 命令和 upgrade 命令移除
 
-Modern.js 3.0 移除了 `ultramodern new` 和 `ultramodern upgrade` 命令，需要按照文档手动操作。
+Modern.js 3.0 移除了 `modern new` 和 `modern upgrade` 命令，需要按照文档手动操作。
 
 **变更内容**：
 
-- `ultramodern new` 命令在 Modern.js 3.0 中不再支持，无法通过命令添加入口或启用功能
-- `ultramodern upgrade` 命令在 Modern.js 3.0 中不再支持，无法通过命令自动升级依赖
+- `modern new` 命令在 Modern.js 3.0 中不再支持，无法通过命令添加入口或启用功能
+- `modern upgrade` 命令在 Modern.js 3.0 中不再支持，无法通过命令自动升级依赖
 
 **处理方式**：
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bleedingdev/modern-js-main-doc",
-  "description": "Documentation of modern.js framework",
+  "description": "Documentation for the UltraModern.js framework",
   "type": "module",
   "homepage": "https://github.com/BleedingDev/ultramodern.js#readme",
   "bugs": {
@@ -16,32 +16,35 @@
     "react",
     "framework",
     "modern",
-    "modern.js"
+    "modern.js",
+    "ultramodern.js"
   ],
-  "version": "3.2.0-ultramodern.98",
+  "version": "3.4.0-ultramodern.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "dependencies": {
     "mermaid": "^11.15.0",
-    "@modern-js/sandpack-react": "npm:@bleedingdev/modern-js-sandpack-react@3.2.0-ultramodern.98"
+    "@modern-js/sandpack-react": "npm:@bleedingdev/modern-js-sandpack-react@3.4.0-ultramodern.0"
   },
   "devDependencies": {
-    "@rsbuild/plugin-sass": "1.5.2",
-    "@rspress/core": "2.0.12",
-    "@rspress/plugin-llms": "2.0.12",
-    "@rspress/shared": "2.0.12",
-    "@shikijs/transformers": "^4.1.0",
+    "@rsbuild/plugin-sass": "2.0.0",
+    "@rspress/core": "2.0.14",
+    "@rspress/plugin-llms": "2.0.14",
+    "@rspress/shared": "2.0.14",
+    "@shikijs/transformers": "^4.2.0",
     "@types/fs-extra": "11.0.4",
-    "@types/node": "^25.9.1",
-    "@typescript/native-preview": "7.0.0-dev.20260527.2",
+    "@types/node": "^26.0.0",
+    "@typescript/native-preview": "7.0.0-dev.20260624.1",
     "classnames": "^2.5.1",
     "clsx": "^2.1.1",
     "fs-extra": "^11.3.5",
-    "react": "^19.2.6",
-    "react-dom": "^19.2.6",
-    "rsbuild-plugin-open-graph": "1.1.2"
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "rsbuild-plugin-open-graph": "1.1.3",
+    "ts-node": "^10.9.2",
+    "typescript": "^6.0.3"
   },
   "scripts": {
     "dev": "rspress dev",

package/rspress.config.ts

@@ -5,13 +5,12 @@ import path from 'path';
 import { pluginOpenGraph } from 'rsbuild-plugin-open-graph';
 
 const docPath = path.join(__dirname, 'docs');
+const staticPath = path.join(__dirname, 'static');
 const siteTitle = 'UltraModern.js 3.0';
 const siteDescription =
   'UltraModern.js 3.0 is a SuperApp framework forked from Modern.js for Effect, TanStack Router, SSR, BFF, and independently deployable Micro Verticals.';
 const socialDescription =
   'A SuperApp framework for Effect, TanStack Router, SSR, BFF, and Micro Verticals.';
-const socialImage =
-  'https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/banner.jpeg';
 
 function normalizeBase(base = '/') {
   const trimmed = base.trim();
@@ -23,6 +22,14 @@ function normalizeBase(base = '/') {
 
 // Set by CI for GitHub Pages project sites. Defaults to root for local dev/custom domains.
 const docsBase = normalizeBase(process.env.DOCS_BASE);
+const docsOrigin = (
+  process.env.DOCS_ORIGIN || 'https://bleedingdev.github.io'
+).replace(/\/+$/, '');
+const siteUrl = new URL(docsBase, `${docsOrigin}/`).toString();
+const socialImage = new URL('img/social-card.svg', siteUrl).toString();
+const faviconUrl = new URL('img/favicon.ico', siteUrl).toString();
+const docsAsset = (assetPath: string) =>
+  `${docsBase}${assetPath.replace(/^\//, '')}`;
 
 export default defineConfig({
   root: docPath,
@@ -30,8 +37,8 @@ export default defineConfig({
   title: siteTitle,
   description: siteDescription,
   base: docsBase,
-  logo: 'https://lf-cdn-tos.bytescm.com/obj/static/webinfra/modern-js-website/assets/images/images/modernjs-logo.svg',
-  icon: 'https://lf3-static.bytednsdoc.com/obj/eden-cn/uhbfnupenuhf/favicon.ico',
+  logo: docsAsset('/img/logo.svg'),
+  icon: faviconUrl,
   lang: 'en',
   themeDir: path.join(__dirname, 'src'),
   markdown: {
@@ -121,6 +128,11 @@ export default defineConfig({
     output: {
       dataUriLimit: 0,
     },
+    server: {
+      publicDir: {
+        name: staticPath,
+      },
+    },
     dev: {
       lazyCompilation: process.env.LAZY !== 'false',
     },
@@ -139,7 +151,7 @@ export default defineConfig({
         // While site name is site wide
         siteName: siteTitle,
         type: 'website',
-        url: 'https://bleedingdev.github.io/ultramodern.js/',
+        url: siteUrl,
         image: socialImage,
         description: socialDescription,
         twitter: {

package/src/components/Footer/index.tsx

@@ -81,15 +81,15 @@ export default function Footer() {
       items: [
         {
           label: t('changelog'),
-          to: 'https://github.com/web-infra-dev/modern.js/releases',
+          to: 'https://github.com/BleedingDev/ultramodern.js/releases',
         },
         {
           label: 'GitHub Issues',
-          to: 'https://github.com/web-infra-dev/modern.js/issues',
+          to: 'https://github.com/BleedingDev/ultramodern.js/issues',
         },
         {
           label: t('githubDiscussion'),
-          to: 'https://github.com/web-infra-dev/modern.js/discussions',
+          to: 'https://github.com/BleedingDev/ultramodern.js/discussions',
         },
       ],
     },

package/src/components/Footer/styles.module.scss

@@ -2,7 +2,7 @@
   display: flex;
   justify-content: center;
   padding: 10vh 0;
-  border-top: 1px solid rgba(0,0,0,0.1);
+  border-top: 1px solid rgba(0, 0, 0, 0.1);
 }
 
 .logo {