@bleedingdev/modern-js-main-doc 3.9.0-ultramodern.1 → 3.9.0-ultramodern.11

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

@@ -46,10 +46,9 @@ import EnableBFFCaution from "@site-docs/components/enable-bff-caution";
 仅当 `bff.runtimeFramework` 设置为 `'effect'` 时，`bff.effect` 才会生效。
 
 :::caution 需要自行安装 Effect peer 依赖
-`effect` 与 `@effect/opentelemetry` 是 `@modern-js/plugin-bff` 的**可选精确 peer
-依赖**，而不是直接依赖。插件不再自带副本——Effect 4 的 `Context` / `Service` 键按模块
-实例生成，自带副本会让应用出现第二份 Effect 身份。在设置 `runtimeFramework: 'effect'`
-或引入 `@modern-js/plugin-bff/effect`、`/effect-server`、`/effect-edge`、
+`effect` 与 `@effect/opentelemetry` 是 `@modern-js/bff-effect` 的**可选精确 peer
+依赖**。应用必须安装这些依赖，让 API 模块与框架使用同一个 Effect 实例。在设置
+`runtimeFramework: 'effect'` 或引入 `@modern-js/bff-effect/effect`、`/effect-edge`、
 `/effect-client` 之前，请安装精确版本的依赖组：
 
 ```bash
@@ -57,9 +56,19 @@ pnpm add effect@4.0.0-rc.112 @effect/opentelemetry@4.0.0-rc.112
 ```
 
 采用精确版本是因为 UltraModern 以锁步依赖组的方式发布 Effect。只使用
-`runtimeFramework: 'hono'` 或 `./data-platform` 通道的应用无需安装这两个包。
+原生 `runtimeFramework: 'hono'` 或 `@modern-js/bff-effect/data-platform` 的应用无需安装这两个包。
 :::
 
+使用 `@modern-js/plugin-bff-build-extensions` 导出的 `bffPlugin` 注册 Effect
+运行时，它会组合原生 BFF 插件。将同一框架版本组中的 `@modern-js/bff-effect` 和
+`@modern-js/plugin-bff-extensions` 安装为应用的生产依赖，保证移除开发依赖后仍能加载
+运行时适配器。构建插件可以作为开发依赖。参见[运行时配置示例](/guides/advanced-features/bff/frameworks)。
+
+原生 `@modern-js/plugin-bff/server` 导出 Hono API。Node Effect API 从
+`@modern-js/bff-effect/effect` 导入 `defineEffectBff` 等框架 helper，命名空间从对应的
+`effect/*` 模块导入。Worker handler 和 Worker 请求上下文使用
+`@modern-js/bff-effect/effect-edge`。
+
 生成的 UltraModern workspace 只把这个运行时作为生成 HTTP API 路径。API 契约固定在
 `shared/api.ts`，服务端运行时固定在 `api/index.ts`，客户端固定在
 `src/api/*-client.ts`。生成检查会拒绝 `api/effect`、`api/lambda`、
@@ -169,7 +178,6 @@ export default defineConfig({
     endpoint: '/_data/batch',
     maxBatchSize: 16,
     maxBatchBytes: 64 * 1024,
-    flushIntervalMs: 8,
     maxConcurrency: 4,
     requestTimeoutMs: 10000,
     allowedMethods: ['GET'],
@@ -203,9 +211,9 @@ export default defineConfig({
 });
 ```
 
-`batch.flushIntervalMs` 用于控制生成的 Effect 客户端微批处理窗口；`maxConcurrency` 与 `requestTimeoutMs` 由服务端批处理网关用于内部请求分发。
+`maxConcurrency` 与 `requestTimeoutMs` 控制服务端批处理网关。原生 `HttpApiClient` 发送独立请求，不会自动批处理。
 
-生成的 `api.client.*` API 只存在于 loader 物化后的 `@api/index` 导入中。直接导入服务端入口（`api/index`）时拿到的是 Effect BFF 定义；其中的 `client` 属性只是占位，并会在访问具体操作时报错。
+导入共享 `HttpApi` 契约并传给 `HttpApiClient.make` 或 `makeEffectHttpApiClient`，即可获得完全类型推导的客户端。`defineEffectBff` 只提供服务端 handler，不包含客户端。
 
 ## Effect 版本组
 
@@ -237,7 +245,7 @@ attestation 的迁移，并不等同于 release-age 审批。
 Edge 兼容测试可以使用框架 helper：
 
 ```ts
-import { createEffectBffTestHandler } from '@modern-js/plugin-bff/effect-edge';
+import { createEffectBffTestHandler } from '@modern-js/bff-effect/effect-edge';
 import apiModule from '../api/index';
 
 const testApi = await createEffectBffTestHandler({
@@ -252,12 +260,9 @@ const response = await testApi.handler(new Request('http://localhost/api/ping'))
 `HttpServer.layerServices`：
 
 ```ts
-import {
-  HttpApiBuilder,
-  HttpRouter,
-  HttpServer,
-  Layer,
-} from '@modern-js/plugin-bff/effect-server';
+import * as Layer from 'effect/Layer';
+import { HttpRouter, HttpServer } from 'effect/unstable/http';
+import { HttpApiBuilder } from 'effect/unstable/httpapi';
 
 const handler = HttpRouter.toWebHandler(
   HttpApiBuilder.layer(api).pipe(
@@ -275,13 +280,10 @@ const handler = HttpRouter.toWebHandler(
 Effect v4 beta 版本组中，`HttpRouter.middleware(...)` 直接返回 `Layer`：
 
 ```ts
-import {
-  Effect,
-  HttpApiBuilder,
-  HttpMiddleware,
-  HttpRouter,
-  Layer,
-} from '@modern-js/plugin-bff/effect-server';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { HttpMiddleware, HttpRouter } from 'effect/unstable/http';
+import { HttpApiBuilder } from 'effect/unstable/httpapi';
 
 const corsLayer = HttpRouter.middleware(
   Effect.succeed(

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

@@ -17,7 +17,7 @@ Modern.js 的 Effect BFF 已支持基于请求信封（request envelope）的数
 
 ## 运行时契约工具
 
-可通过 `@modern-js/plugin-bff/data-platform` 使用以下能力：
+可通过 `@modern-js/bff-effect/data-platform` 使用以下能力：
 
 ```ts
 import {
@@ -30,7 +30,7 @@ import {
   validateHydrationEnvelope,
   createInvalidationEvent,
   shouldApplyInvalidation,
-} from '@modern-js/plugin-bff/data-platform';
+} from '@modern-js/bff-effect/data-platform';
 ```
 
 ## Effect 运行时校验

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

@@ -5,10 +5,10 @@ title: 运行时框架
 
 # 运行时框架
 
-Modern.js 目前支持两种 BFF 运行时框架：
+Modern.js 与 UltraModern BFF 扩展提供两种运行时框架：
 
-- `effect`（默认）：使用 `api/index` 的 [Effect HttpApi](https://effect.website/) 运行时。
-- `hono`：使用 `api/lambda/**` 的文件约定 BFF 处理函数。
+- `hono` 是原生插件的默认运行时，使用 `api/lambda/**` 的文件约定处理函数。
+- `effect` 是 UltraModern 扩展的默认运行时，使用 `api/index` 的 [Effect HttpApi](https://effect.website/) 运行时。
 
 `effect` 与 `hono` 为严格模式，两者之间不会自动回退。
 
@@ -22,12 +22,16 @@ workspace 中加入 Hono/file-convention handler、原始 request parsing 或手
 
 ## 切换到 Effect 运行时
 
+使用下面的 fork 构建插件，它会包含原生 BFF 插件并注册 Effect 适配器。应用需要将
+同一框架版本组中的 `@modern-js/bff-effect` 和 `@modern-js/plugin-bff-extensions`
+安装为生产依赖。Effect 的精确 peer 版本见 [`bff.effect`](/configure/app/bff/effect)。
+
 ```ts title="modern.config.ts"
-import { bffPlugin } from '@modern-js/plugin-bff';
-import { defineConfig } from '@modern-js/app-tools';
+import { bffPlugin } from '@modern-js/plugin-bff-build-extensions';
+import { appTools, defineConfig } from '@modern-js/app-tools';
 
 export default defineConfig({
-  plugins: [bffPlugin()],
+  plugins: [appTools(), bffPlugin()],
   bff: {
     runtimeFramework: 'effect',
     effect: {
@@ -49,7 +53,7 @@ import {
   HttpApiEndpoint,
   HttpApiGroup,
   Schema,
-} from '@modern-js/plugin-bff/effect-client';
+} from '@modern-js/bff-effect/effect-client';
 
 export const bffApi = HttpApi.make('MyApi').add(
   HttpApiGroup.make('hello').add(
@@ -63,14 +67,12 @@ export const bffApi = HttpApi.make('MyApi').add(
 然后在 `api/index.ts` 中实现 Effect BFF 入口：
 
 ```ts title="api/index.ts"
-import {
-  Schema,
-  Effect,
-  HttpApiBuilder,
-  defineEffectBff,
-  Layer,
-  ServiceMap,
-} from '@modern-js/plugin-bff/effect-server';
+import { defineEffectBff } from '@modern-js/bff-effect/effect';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Schema from 'effect/Schema';
+import { HttpApiBuilder } from 'effect/unstable/httpapi';
 import { bffApi } from '../shared/api';
 
 class GreetingUnavailableError extends Schema.TaggedError<GreetingUnavailableError>()(
@@ -80,7 +82,7 @@ class GreetingUnavailableError extends Schema.TaggedError<GreetingUnavailableErr
   },
 ) {}
 
-class GreetingService extends ServiceMap.Service<GreetingService>()('GreetingService', {
+class GreetingService extends Context.Service<GreetingService>()('GreetingService', {
   make: Effect.succeed({
     hello: Effect.fn('GreetingService.hello')(function* () {
       if (Date.now() < 0) {
@@ -115,15 +117,24 @@ const layer = HttpApiBuilder.layer(bffApi).pipe(
 export default defineEffectBff({ api: bffApi, layer });
 ```
 
-在浏览器代码中通过 `@api/index` 调用接口：
+从共享契约创建原生、完全类型推导的客户端：
 
 ```ts title="src/routes/page.tsx"
-import api from '@api/index';
+import { Effect, makeEffectHttpApiClient } from '@modern-js/bff-effect/effect-client';
+import { bffApi } from '../../shared/api';
 
-const response = await api.client.hello.ping({});
+const response = await Effect.runPromise(
+  makeEffectHttpApiClient(bffApi, { baseUrl: '/api' }).pipe(
+    Effect.flatMap(client => client.hello.ping({})),
+  ),
+);
 ```
 
-`api.client.*` 由 BFF loader 针对 `@api/index` 导入物化生成。不要直接导入 `api/index` 并期望在服务端代码、脚本或测试中运行 `client`；直接导入入口时拿到的是服务端运行时定义，其中的 `client` 只是类型占位。
+请求、响应和声明的错误类型均从 `bffApi` 推导，无需生成客户端代码或导入服务端入口。
+
+原生 Hono 应用从 `@modern-js/plugin-bff/server` 导入操作符。生成的 UltraModern
+应用继续使用严格 Effect API。Worker handler 及其请求上下文使用
+`@modern-js/bff-effect/effect-edge`；Node handler 使用上面示例中的 Effect 入口。
 
 import Hono from '@site-docs/components/hono';
 

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

@@ -188,7 +188,7 @@ Dynamic Path 之后的参数是包含 querystring、request body 的对象 `Requ
 在不存在动态路由的普通函数中，可以从第一个入参中获取传入的 `data` 和 `query`，例如：
 
 ```ts title="api/lambda/hello.ts"
-import type { RequestOption } from '@modern-js/plugin-bff/hono-server';
+import type { RequestOption } from '@modern-js/plugin-bff/server';
 
 export async function post({
   query,
@@ -201,7 +201,7 @@ export async function post({
 这里你也可以使用自定义类型：
 
 ```ts title="api/lambda/hello.ts"
-import type { RequestOption } from '@modern-js/plugin-bff/hono-server';
+import type { RequestOption } from '@modern-js/plugin-bff/server';
 
 type IQuery = {
   // some types

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

@@ -36,7 +36,7 @@ import BFFOperatorCode from '@site-docs/components/bff-operator-code';
 <BFFOperatorCode>
 
 ```typescript title="api/lambda/user.ts"
-import { Api, Post, Query, Data } from '@modern-js/plugin-bff/hono-server';
+import { Api, Post, Query, Data } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -89,7 +89,7 @@ addUser({
 <BFFOperatorCode>
 
 ```typescript title="api/lambda/user.ts"
-import { Api, Get, Query, Data } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Query, Data } from '@modern-js/plugin-bff/server';
 
 // 指定接口路由，Modern.js 默认设置 `bff.prefix` 为 `/api`，
 // 因此该接口路由为 `/api/user`，Http Method 为 GET。
@@ -107,7 +107,7 @@ export const getHello = Api(
 <BFFOperatorCode>
 
 ```typescript title="api/lambda/user.ts"
-import { Api, Get, Query, Data } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Query, Data } from '@modern-js/plugin-bff/server';
 
 // 未指定接口路由，根据文件约定和函数名，该接口为 api/user，Http Method 为 get。
 export const get = Api(Query(UserSchema), async ({ query }) => query);
@@ -144,7 +144,7 @@ Modern.js 推荐基于文件约定去定义接口，保持项目中路由清晰
 
 ```typescript title="api/lambda/user.ts"
 // 服务端代码
-import { Api, Query } from '@modern-js/plugin-bff/hono-server';
+import { Api, Query } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -176,7 +176,7 @@ URL query 参数默认是字符串类型，如果需要数字类型，需要使
 <BFFOperatorCode>
 
 ```typescript title="api/lambda/user.ts"
-import { Api, Get, Query } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Query } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const QuerySchema = z.object({
@@ -216,7 +216,7 @@ URL query 参数都是字符串类型，如果需要数字类型，需要使用
 <BFFOperatorCode>
 
 ```typescript title="api/lambda/user.ts"
-import { Api, Data } from '@modern-js/plugin-bff/hono-server';
+import { Api, Data } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const DataSchema = z.object({
@@ -249,7 +249,7 @@ post({
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Get, Params } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Params } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -274,7 +274,7 @@ export const queryUser = Api(
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Headers } from '@modern-js/plugin-bff/hono-server';
+import { Api, Headers } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const headerSchema = z.object({
@@ -336,7 +336,7 @@ try {
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Query, Middleware } from '@modern-js/plugin-bff/hono-server';
+import { Api, Query, Middleware } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -376,7 +376,7 @@ export const get = Api(
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Query, Pipe } from '@modern-js/plugin-bff/hono-server';
+import { Api, Query, Pipe } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -408,7 +408,7 @@ export const get = Api(
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Query, Pipe } from '@modern-js/plugin-bff/hono-server';
+import { Api, Query, Pipe } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -443,7 +443,7 @@ export const get = Api(
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Query, Pipe } from '@modern-js/plugin-bff/hono-server';
+import { Api, Query, Pipe } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -487,7 +487,7 @@ export const get = Api(
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Query, Data, HttpCode } from '@modern-js/plugin-bff/hono-server';
+import { Api, Query, Data, HttpCode } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -523,7 +523,7 @@ export const post = Api(
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Get, SetHeaders } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, SetHeaders } from '@modern-js/plugin-bff/server';
 
 export default Api(
   Get('/hello'),
@@ -543,7 +543,7 @@ export default Api(
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Get, Redirect } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Redirect } from '@modern-js/plugin-bff/server';
 
 export default Api(
   Get('/hello'),
@@ -561,7 +561,7 @@ export default Api(
 <BFFOperatorCode>
 
 ```typescript title="api/lambda/user.ts"
-import { Api, Get, Query } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Query } from '@modern-js/plugin-bff/server';
 import { useHonoContext } from '@modern-js/server-runtime';
 import { z } from 'zod';
 
@@ -610,7 +610,7 @@ export const queryUser = Api(
 <BFFOperatorCode>
 
 ```typescript
-import { Api, SetHeaders } from '@modern-js/plugin-bff/hono-server';
+import { Api, SetHeaders } from '@modern-js/plugin-bff/server';
 
 export const get = Api(
   // 缓存使用一体化调用或者 fetch 进行请求才会生效

package/docs/zh/guides/basic-features/render/ssr-cache.mdx

@@ -39,7 +39,7 @@ export interface CacheControl {
 }
 ```
 
-其中 `customKey` 为自定义缓存 key。默认情况下 Modern.js 将会把请求 `pathname` 作为 key 进行缓存，但在某些情况下这不能满足你的需求，开发者可以进行自定义。
+其中 `customKey` 为自定义缓存 key。默认情况下，缓存 key 由请求的 origin、归一化后的 pathname（去除末尾斜杠）以及 query 组成。当设置了 `customKey` 后，它会完全替代默认 key：`customKey` 回调函数接收的是归一化后的 pathname（而非 `CacheOptionProvider` 的 `req`），并需要自行负责整个分区（例如按租户、host 或 query 区分）——不能将原始 cookie 或其他凭证嵌入返回的 key 中。
 
 **Function 类型**
 
@@ -111,6 +111,19 @@ export const cacheOption: CacheOption = {
 
 上述 `/home` 和 `/about` 将会作为模式进行匹配，这意味着 `/home/abc` 也会匹配上该规则。同时，你也可以在其中编写正则语法：`/home/.+`
 
+### 缓存策略
+
+以下策略由框架自动执行，返回的 `CacheControl` 无法覆盖：
+
+- 只有 `GET` 请求会被缓存。
+- 请求携带 `Cookie` 或 `Authorization` 请求头时会跳过缓存，除非设置了 `customKey`（自定义 key 被视为一份明确的分区约定）。
+- 请求的 `Cache-Control` 为 `private`、`no-cache` 或 `no-store` 时会跳过缓存。
+- 只有当响应为 `200`、`Cache-Control` 中不含 `private`/`no-cache`/`no-store`、不含 `Set-Cookie`、也不含非空的 `Vary` 头时才会被写入缓存；否则会删除该 key 已有的缓存条目，而不是写入新的。
+- 当 `stale` 状态触发的重新渲染结果不再可缓存时（例如变为按用户区分），本次已返回的 stale 响应不受影响，但缓存条目会被清除，后续请求将不再命中该缓存。
+- `CacheOptionProvider` 返回 `false` 依然会完全禁用该请求的缓存，不受上述策略影响。
+
+缓存 key 带有命名空间（`__ssr__cache:v2:...`）。旧版本未加命名空间的缓存条目（包括自定义 `Container` 中已存储的条目）不会再被读取，只会依据容器自身的淘汰/TTL 机制自然过期；不存在全局缓存清空操作。
+
 ### 缓存容器
 
 默认情况下，Server 将会使用内存进行缓存。但通常情况下服务将会部署在 Serverless 容器上。每一次的服务访问可能都是一个新的进程，这样每次访问都不能应用缓存。

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

@@ -16,15 +16,11 @@ UltraModern.js 3.0 是我们从 Modern.js 分叉出来的 SuperApp 框架。它
 - 仅在跨团队稳定性场景增加平台契约。
 - 保留显式 escape hatch，但它们必须位于生成 HTTP API 模块之外。
 
-## 兼容性承诺
+## 当前 Workspace 契约
 
-UltraModern.js 3.0 保持以下不变：
-
-- Modern.js 的应用/配置/插件心智模型。
-- 既有项目结构与命令使用方式。
-- 渐进式接入路径（应用无需大规模重构）。
-
-UltraModern.js 的增强能力是新 SuperApp 的默认产品面。框架方向是 Effect + TanStack + SSR + Micro Verticals，生成的 HTTP API 只走严格 Effect HttpApi surface。既有 Modern.js 应用可以渐进迁移；一旦某个 API surface 被生成为或迁移为 UltraModern HTTP API，就必须使用严格 Effect HttpApi 路径。
+UltraModern.js 使用 Effect HttpApi、TanStack Router、SSR 和可独立部署的 Micro Verticals。
+生成的 workspace 使用 `api/index.ts`、`shared/api.ts`、`src/api/*` 和具体的 Effect schema。
+CLI 按当前契约创建、扩展和验证 workspace。
 
 ## 有意引入的差异（3.0 线）
 
@@ -50,20 +46,9 @@ UltraModern.js 的增强能力是新 SuperApp 的默认产品面。框架方向
 - 生成的 UltraModern HTTP API 只走严格 Effect HttpApi surface；原始 request handler 和 Hono/file-function API 不属于生成架构。
 - 除非稳定性硬需求，否则避免引入破坏性 API 变更。
 
-## 迁移指南
-
-对于已经在使用 Modern.js 3.0 或旧版 BleedingDev UltraModern scaffold 的团队，迁移路径是把 API 工作迁到严格 Effect HttpApi surface，而不是保留旧的原始 handler 布局。
-
-1. 既有 Modern.js 应用在尚未进入生成 UltraModern surface 前可以继续按现状运行。TanStack Router 是新脚手架与增量迁移的优先路径，团队可以按自己的节奏迁移路由层。
-2. 新建或迁移中的 BFF 能力使用 `bff.runtimeFramework: 'effect'`、`bff.effect.entry: './api/index'` 和 `bff.effect.strictEffectApproach: true`。接口先改 `shared/api.ts` 的 `HttpApi` 契约，再在 `api/index.ts` 用 `defineEffectBff(...)` / `HttpApiBuilder` 实现。
-3. 在生成或已迁移的 UltraModern workspace 中，把 raw handler、`api/lambda/**`、手写 `Response` 和手写 request parsing 视为迁移缺陷。
-4. 这套公开预设现在已经附带显式的发布 / 认证 gate。生成 workspace 会自带 `.github/workflows/ultramodern-workspace-gates.yml`，因此 `pnpm check` 与 `pnpm build` 从第一天开始就是本地接入契约的一部分；CI 会以并行矩阵运行这些基础 gate。
-
-旧版生成 workspace 迁移时，以已发布的包 cohort 作为事实来源：
+## 创建并验证 Workspace
 
 ```bash
-pnpm dlx @bleedingdev/modern-js-ultramodern-create@latest --help
-pnpm dlx @bleedingdev/modern-js-ultramodern-create@latest catalog --vertical --dry-run
 pnpm dlx @bleedingdev/modern-js-ultramodern-create@latest catalog --vertical
 mise install
 mise exec -- pnpm install
@@ -71,62 +56,14 @@ mise exec -- pnpm check
 mise exec -- pnpm build
 ```
 
-### 迁移本地化 Cloudflare SSR workspace
-
-当前 cohort 均支持本地化 Cloudflare SSR workspace。框架将裸 locale root 重定向移动到框架拥有的 Cloudflare Worker entry 和 i18n
-server runtime 中。请求 `/` 时，框架会按语言协商在服务端返回 `302`，例如
-`Accept-Language: cs-CZ` 会跳转到 `/cs`，英语或 fallback 流量会跳转到 `/en`。
-
-既有生成 workspace 应整体升级同一个 BleedingDev Modern package cohort。
-先解析当前 cohort 版本，再运行同版本迁移命令：
-
-```bash
-COHORT="$(npm view @bleedingdev/modern-js-ultramodern-create version)"
-pnpm dlx "@bleedingdev/modern-js-ultramodern-create@$COHORT" ultramodern \
-  migrate-strict-effect --version "$COHORT"
-pnpm install
-pnpm check
-pnpm build
-pnpm cloudflare:build
-```
-
-Cloudflare Workers 已部署环境需要在 cohort 更新后重新部署，并在接受迁移前验证 root
-响应：
+本地化 Cloudflare SSR workspace 在服务端将 `/` 重定向到协商的语言路径。
+`Accept-Language: cs-CZ` 返回 `302`、`Location: /cs`、
+`Cache-Control: private, no-store`，以及覆盖语言检测 Header 的 `Vary`。
 
 ```bash
 curl -I -H 'Accept-Language: cs-CZ,cs;q=0.9,en;q=0.1' https://<worker-host>/
 ```
 
-期望响应是 `302`，并带有 `Location: /cs` 或匹配的 locale、
-`Cache-Control: private, no-store`，以及覆盖语言检测 Header 的 `Vary`。继续跟随该
-redirect 后，应返回匹配语言的 SSR 页面，文档语言和 i18n SSR 数据也应一致。
-
-不要通过 app 自有 root route、客户端 redirect、自定义导航 wrapper、Cloudflare Worker
-postprocess、生成产物编辑或本地 redirect shim 来修复旧版本的 root `404`。如果升级后
-`/` 仍然返回 `404`，先确认生产构建日志显示的
-`Modern.js Framework v<cohort-version>` 就是迁移目标 cohort，然后重新部署 Worker。
-
-严格生成 API 迁移是当前每个 cohort 的组成部分：直接 `api/index.ts` 生成器、生成的
-`.mts` 检查、严格 Oxlint 边界规则、Effect 版本组 overrides 和严格 Effect 迁移命令。
-还不能安装 BleedingDev cohort 的 agent 应使用本地 Modern.js workspace 做迁移校验；
-否则用 `--ultramodern-package-version` 固定目标 cohort。
-
-手写 package alias 或生成 metadata 之前，先在目标 workspace 运行框架迁移命令：
-
-```bash
-COHORT="$(npm view @bleedingdev/modern-js-ultramodern-create version)"
-pnpm dlx "@bleedingdev/modern-js-ultramodern-create@$COHORT" ultramodern \
-  migrate-strict-effect --version "$COHORT"
-pnpm api:check
-pnpm contract:check
-```
-
-该命令会更新 `.modernjs/ultramodern.json`、根 `modernjs.packageSource`、生成的
-Modern package alias、框架拥有的 toolchain pin、直接 topology API metadata、严格 Effect
-pnpm overrides/trust policy 和 pnpm lockfile。剩余失败就是源码迁移：把代码移到
-`shared/api.ts`、`api/index.ts` 和 `src/api/*-client.ts`，再删除 `api/effect`、
-`api/lambda`、`shared/effect` 和 `src/effect`。
-
 严格 Effect 生成 workspace 会通过 pnpm overrides 固定兼容版本组：
 `effect@4.0.0-rc.112`、`@effect/opentelemetry@4.0.0-rc.112` 和
 `@effect/vitest@4.0.0-rc.112`。不要添加与这些 overrides 冲突的 app 本地直接
@@ -141,12 +78,12 @@ provenance attestation 的迁移；它不属于 release-age 审批。
 | 范围 | 固定版本 |
 | --- | --- |
 | Effect runtime 与测试版本组 | `effect`、`@effect/opentelemetry`、`@effect/vitest`：`4.0.0-rc.112` |
-| Effect compiler | `@effect/tsgo@0.37.0` |
-| Oxc 与 Ultracite | `oxlint@1.80.0`、`oxfmt@0.65.0`、`ultracite@7.10.6` |
-| TanStack Router | `@tanstack/react-router@1.170.32`、`@tanstack/router-core@1.171.27`、`@tanstack/history@1.162.1` |
+| Effect compiler | `@effect/tsgo@0.41.0` |
+| Oxc 与 Ultracite | `oxlint@1.81.0`、`oxfmt@0.66.0`、`ultracite@7.11.0` |
+| TanStack Router | `@tanstack/react-router@1.170.33`、`@tanstack/router-core@1.171.28`、`@tanstack/history@1.162.2` |
 | Module Federation | `bridge-react`、`manifest`、`modern-js-v3`、`rspack`：`2.9.0`；`@module-federation/node@2.7.50` |
 | Tailwind CSS | `tailwindcss@4.3.3` |
-| Node 与包管理工具 | Node `26.7.0`、`@types/node@^26.2.0`、pnpm `11.24.0` |
+| Node 与包管理工具 | Node `26.7.0`、`@types/node@^26.4.1`、pnpm `11.24.0` |
 
 生成的 workspace 默认使用 `@module-federation/bridge-react` 的
 router-free base entry（`bridge.enableBridgeRouter: false`），应用路由由
@@ -190,7 +127,7 @@ Effect RPC、WebSockets 和其他传输方式应在需要时作为显式 transpo
 它们不能作为在生成 HTTP API 模块中重新引入原始 request handler 的理由。
 
 严格 API 测试应执行 `HttpApi` 契约。Edge 兼容 proof 测试使用
-`@modern-js/plugin-bff/effect-edge` 的 `createEffectBffTestHandler`；如果必须手动组合
+`@modern-js/bff-effect/effect-edge` 的 `createEffectBffTestHandler`；如果必须手动组合
 web handler，在调用 `HttpRouter.toWebHandler` 前要把 `HttpServer.layerServices` 和
 API group layer 一起提供。
 

package/package.json

@@ -19,27 +19,27 @@
     "modern.js",
     "ultramodern.js"
   ],
-  "version": "3.9.0-ultramodern.1",
+  "version": "3.9.0-ultramodern.11",
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@modern-js/sandpack-react": "npm:@bleedingdev/modern-js-sandpack-react@3.9.0-ultramodern.1",
-    "@modern-js/ultramodern-sandpack-profile": "npm:@bleedingdev/modern-js-ultramodern-sandpack-profile@3.9.0-ultramodern.1",
-    "mermaid": "^11.16.0"
+    "@modern-js/sandpack-react": "npm:@bleedingdev/modern-js-sandpack-react@3.9.0-ultramodern.11",
+    "@modern-js/ultramodern-sandpack-profile": "npm:@bleedingdev/modern-js-ultramodern-sandpack-profile@3.9.0-ultramodern.11",
+    "mermaid": "^11.17.2"
   },
   "devDependencies": {
     "@rsbuild/plugin-sass": "2.0.1",
-    "@rspress/core": "2.0.17",
-    "@rspress/plugin-llms": "2.0.17",
-    "@rspress/shared": "2.0.17",
-    "@shikijs/transformers": "^4.3.1",
+    "@rspress/core": "2.0.21",
+    "@rspress/plugin-llms": "2.0.21",
+    "@rspress/shared": "2.0.21",
+    "@shikijs/transformers": "^4.4.3",
     "@types/fs-extra": "11.0.4",
-    "@types/node": "^26.2.0",
+    "@types/node": "^26.4.1",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
     "classnames": "^2.5.1",
     "clsx": "^2.1.1",
-    "fs-extra": "^11.3.6",
+    "fs-extra": "^11.4.0",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "rsbuild-plugin-open-graph": "1.1.3",

package/src/sandbox/csr-auth/src/routes/Auth-tsx.txt

@@ -1,6 +1,6 @@
 import {
   Navigate,
-  useLocation,
+  useMatch,
   useNavigate,
 } from '@modern-js/plugin-tanstack/runtime';
 import React from 'react';
@@ -52,8 +52,9 @@ export function AuthStatus() {
       Welcome {auth.user}!{' '}
       <button
         type="button"
-        onClick={() => {
-          auth.signout(() => void navigate({ to: '/' }));
+        onClick={async () => {
+          await navigate({ to: '/' });
+          auth.signout(() => {});
         }}
       >
         Sign out
@@ -62,9 +63,12 @@ export function AuthStatus() {
   );
 }
 
-export function RequireAuth({ children }: { children: JSX.Element }) {
+export function RequireAuth({ children }: { children: React.JSX.Element }) {
   const auth = useAuth();
-  const location = useLocation();
+  const pathname = useMatch({
+    strict: false,
+    select: match => match.pathname,
+  });
 
   if (!auth.user) {
     // Redirect them to the /login page, but save the current location they were
@@ -74,7 +78,7 @@ export function RequireAuth({ children }: { children: JSX.Element }) {
     return (
       <Navigate
         replace
-        search={{ redirect: location.pathname }}
+        search={{ redirect: pathname }}
         to="/login"
       />
     );

package/src/sandbox/csr-auth/src/routes/page-tsx.txt

@@ -1,4 +1,5 @@
 import { Helmet } from '@modern-js/runtime/head';
+import type { JSX } from 'react';
 import './index.css';
 
 const PublicPage = (): JSX.Element => (

package/ultramodern-preset/package.json

@@ -13,7 +13,7 @@
     "rsbuild-plugin-open-graph": "1.1.3"
   },
   "devDependencies": {
-    "@rspress/core": "2.0.17",
-    "@types/node": "^26.2.0"
+    "@rspress/core": "2.0.21",
+    "@types/node": "^26.4.1"
   }
 }