@bleedingdev/modern-js-main-doc 3.5.0-ultramodern.0 → 3.5.0-ultramodern.10

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

@@ -45,6 +45,13 @@ import EnableBFFCaution from "@site-docs-en/components/enable-bff-caution";
 
 `bff.effect` is only effective when `bff.runtimeFramework` is set to `'effect'`.
 
+Generated UltraModern workspaces use this runtime as the only generated HTTP API
+path. The API contract lives at `shared/api.ts`, the server runtime lives at
+`api/index.ts`, clients live under `src/api/*-client.ts`, and generated checks
+reject `api/effect`, `api/lambda`, `shared/effect`, `src/effect`, Hono server
+imports, raw request handlers, manual request parsing, and manual `Response`
+construction in API modules.
+
 For Effect v4, TypeScript should use export-map aware module resolution.
 
 ```json title="tsconfig.json"
@@ -186,3 +193,109 @@ export default defineConfig({
 `batch.flushIntervalMs` controls the client-side micro-batch window in the generated Effect client. `maxConcurrency` and `requestTimeoutMs` are applied by the server batch gateway when dispatching items.
 
 The generated `api.client.*` API only exists for loader-materialized `@api/index` imports. Directly importing the server entry (`api/index`) exposes the Effect BFF definition; its `client` property is a placeholder that fails on operation access.
+
+## Effect cohort
+
+UltraModern-generated workspaces pin the framework-compatible Effect cohort
+through `pnpm-workspace.yaml` overrides. For `3.5.0-ultramodern.10`, generated
+apps use:
+
+```yaml
+minimumReleaseAgeExclude:
+  - 'effect@4.0.0-beta.91'
+  - '@effect/opentelemetry@4.0.0-beta.91'
+
+trustPolicyExclude:
+  - 'effect@4.0.0-beta.91'
+  - '@effect/opentelemetry@4.0.0-beta.91'
+
+overrides:
+  '@effect/vitest': 4.0.0-beta.91
+  effect: 4.0.0-beta.91
+```
+
+Do not add a different direct `effect` version in an app package. A mismatched
+Effect beta can fail while building layers or HTTP middleware because runtime
+services come from different package instances. Keep the generated
+policy exclusion entries with the same Effect cohort; they handle the
+framework-selected Effect beta versions before the 24-hour maturity window and
+the `effect`/`@effect/opentelemetry` trusted-publisher to provenance metadata
+transition without weakening UltraModern API architecture checks.
+
+## Contract tests
+
+Strict Effect APIs should test the declared `HttpApi` contract, not a raw
+request handler. Edge-compatible tests can use the framework helper:
+
+```ts
+import { createEffectBffTestHandler } from '@modern-js/plugin-bff/effect-edge';
+import apiModule from '../api/index';
+
+const testApi = await createEffectBffTestHandler({
+  module: apiModule,
+  prefix: '/api',
+});
+
+const response = await testApi.handler(new Request('http://localhost/api/ping'));
+```
+
+If you manually compose an Effect web handler in a low-level proof, provide the
+platform services explicitly:
+
+```ts
+import {
+  HttpApiBuilder,
+  HttpRouter,
+  HttpServer,
+  Layer,
+} from '@modern-js/plugin-bff/effect-server';
+
+const handler = HttpRouter.toWebHandler(
+  HttpApiBuilder.layer(api).pipe(
+    Layer.provide(apiGroupLayer),
+    Layer.provide(HttpServer.layerServices),
+  ),
+).handler;
+```
+
+Prefer the generated helper unless the test needs to inspect the low-level
+Effect router composition.
+
+## Dynamic CORS
+
+For dynamic origin predicates, use Effect HTTP middleware as a layer. In the
+current Effect v4 beta cohort, `HttpRouter.middleware(...)` returns a `Layer`
+directly:
+
+```ts
+import {
+  Effect,
+  HttpApiBuilder,
+  HttpMiddleware,
+  HttpRouter,
+  Layer,
+} from '@modern-js/plugin-bff/effect-server';
+
+const corsLayer = HttpRouter.middleware(
+  Effect.succeed(
+    HttpMiddleware.cors({
+      allowedOrigins: origin =>
+        origin.endsWith('.example.com') ? origin : undefined,
+    }),
+  ),
+);
+
+const layer = HttpApiBuilder.layer(api).pipe(
+  Layer.provide(apiGroupLayer),
+  Layer.provide(corsLayer),
+);
+```
+
+Do not read a `.layer` property from `HttpRouter.middleware(...)`.
+
+## Other transports
+
+`strictEffectApproach` governs generated HTTP API modules. Effect RPC,
+WebSockets, and other transports remain valid when they are modeled as explicit
+transport surfaces with typed Effect programs. They do not make raw HTTP
+request handlers valid inside generated UltraModern API modules.

package/docs/en/configure/app/performance/build-cache.mdx

@@ -28,6 +28,11 @@ type BuildCacheConfig =
 
 Controls the caching behavior during the build process.
 
+When persistent Rspack cache is enabled, Modern.js treats `cacheDirectory` as a
+base directory and stores each Rsbuild/Rspack environment in its own child
+directory, such as `client`, `server`, or `workerSSR`. This avoids concurrent
+environment compilers writing to the same filesystem cache root.
+
 Modern.js will enable build cache by default to improve the compile speed. You can disable the build cache by setting it to `false`:
 
 ```js

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

@@ -78,12 +78,39 @@ mise exec -- pnpm check
 mise exec -- pnpm build
 ```
 
-Strict generated API migration requires `3.5.0-ultramodern.0` or newer.
+Strict generated API migration requires `3.5.0-ultramodern.10` or newer.
 `3.4.0-ultramodern.20` and earlier cohorts do not include this full direct
-`api/index.ts` generator, generated `.mts` checks, and strict Oxlint boundary
-rule set. Agents that cannot install that BleedingDev cohort yet should use the
-local Modern.js workspace for migration validation; otherwise pin
-`3.5.0-ultramodern.0` or newer with `--ultramodern-package-version`.
+`api/index.ts` generator, generated `.mts` checks, strict Oxlint boundary rule
+set, Effect cohort overrides, and strict Effect migration command. Agents that
+cannot install that BleedingDev cohort yet should use the local Modern.js
+workspace for migration validation; otherwise pin `3.5.0-ultramodern.10` or
+newer with `--ultramodern-package-version`.
+
+Before hand-editing package aliases or generated metadata, run the framework
+migration command from the target workspace:
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create@3.5.0-ultramodern.10 ultramodern \
+  migrate-strict-effect --version 3.5.0-ultramodern.10
+pnpm api:check
+pnpm contract:check
+```
+
+The command updates `.modernjs/ultramodern.json`, root
+`modernjs.packageSource`, generated Modern package aliases, framework-owned
+toolchain pins, direct topology API metadata, strict Effect pnpm
+overrides/trust policy, and the pnpm lockfile. Remaining failures are source
+migration work: move code to `shared/api.ts`, `api/index.ts`, and
+`src/api/*-client.ts`, then delete `api/effect`, `api/lambda`, `shared/effect`,
+and `src/effect`.
+
+Generated strict Effect workspaces pin the compatible Effect cohort with pnpm
+overrides: `effect@4.0.0-beta.91` and `@effect/vitest@4.0.0-beta.91`. Do not
+add app-local direct Effect versions that disagree with those overrides. They
+also carry generated pnpm policy exclusions for `effect@4.0.0-beta.91` and
+`@effect/opentelemetry@4.0.0-beta.91` so the framework-selected Effect beta
+cohort is not blocked by the 24-hour age gate or trusted-publisher to
+provenance metadata transition.
 
 Gradual migration means old, unmigrated Modern.js apps can keep their existing
 runtime until they are converted. Once a surface is generated or migrated as
@@ -122,6 +149,17 @@ Effect RPC, WebSockets, and other transports should be added as explicit
 transport surfaces when needed. They do not make raw request handlers valid
 inside generated HTTP API modules.
 
+Strict API tests should exercise the `HttpApi` contract. Use
+`createEffectBffTestHandler` from `@modern-js/plugin-bff/effect-edge` for
+edge-compatible proof tests; if you manually compose a web handler, provide
+`HttpServer.layerServices` beside your API group layer before calling
+`HttpRouter.toWebHandler`.
+
+For dynamic origin CORS predicates inside strict Effect HTTP APIs, prefer
+`HttpRouter.middleware(Effect.succeed(HttpMiddleware.cors(...)))`.
+`HttpRouter.middleware(...)` returns a `Layer` directly in the pinned Effect
+cohort; do not read a `.layer` property from it.
+
 Use one package-source strategy per repo. The published BleedingDev create
 package defaults to `--ultramodern-package-source=install` and records the
 exact cohort in `.modernjs/ultramodern.json`. Keep `--workspace` only for local
@@ -148,6 +186,13 @@ manual edits. Fix topology, ownership, package-source, local overlay, generated
 contract, Tailwind prefix, or Module Federation conflicts in the owning files
 instead of patching generated output by hand.
 
+Cloudflare D1 bindings are first-class on `deploy.worker.d1Databases`; use that
+config instead of app-local postprocessing when a generated app owns D1
+migrations. Cloudflare public output excludes server-only `api` and `shared`
+directories by default, and generated Modern/Rspack caches are isolated per app,
+build target, and Rspack environment so local `build`, `cloudflare:build`, and
+multi-environment compilers do not share the same filesystem cache directory.
+
 ## Human Workflow
 
 The public BleedingDev create package has one supported generated product. The

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

@@ -45,6 +45,12 @@ import EnableBFFCaution from "@site-docs/components/enable-bff-caution";
 
 仅当 `bff.runtimeFramework` 设置为 `'effect'` 时，`bff.effect` 才会生效。
 
+生成的 UltraModern workspace 只把这个运行时作为生成 HTTP API 路径。API 契约固定在
+`shared/api.ts`，服务端运行时固定在 `api/index.ts`，客户端固定在
+`src/api/*-client.ts`。生成检查会拒绝 `api/effect`、`api/lambda`、
+`shared/effect`、`src/effect`、Hono server import、原始 request handler、手写
+request parsing，以及 API 模块里的手写 `Response`。
+
 对于 Effect v4，TypeScript 需要使用支持 `exports` 映射的模块解析方式。
 
 ```json title="tsconfig.json"
@@ -185,3 +191,103 @@ export default defineConfig({
 `batch.flushIntervalMs` 用于控制生成的 Effect 客户端微批处理窗口；`maxConcurrency` 与 `requestTimeoutMs` 由服务端批处理网关用于内部请求分发。
 
 生成的 `api.client.*` API 只存在于 loader 物化后的 `@api/index` 导入中。直接导入服务端入口（`api/index`）时拿到的是 Effect BFF 定义；其中的 `client` 属性只是占位，并会在访问具体操作时报错。
+
+## Effect 版本组
+
+UltraModern 生成的 workspace 会通过 `pnpm-workspace.yaml` overrides 锁定与框架兼容的
+Effect 版本组。`3.5.0-ultramodern.10` 使用：
+
+```yaml
+minimumReleaseAgeExclude:
+  - 'effect@4.0.0-beta.91'
+  - '@effect/opentelemetry@4.0.0-beta.91'
+
+trustPolicyExclude:
+  - 'effect@4.0.0-beta.91'
+  - '@effect/opentelemetry@4.0.0-beta.91'
+
+overrides:
+  '@effect/vitest': 4.0.0-beta.91
+  effect: 4.0.0-beta.91
+```
+
+不要在应用包里添加不同版本的直接 `effect` 依赖。Effect beta 不一致时，Layer 或 HTTP
+middleware 构建可能因为运行时 service 来自不同包实例而失败。保留生成的 policy
+exclusion 条目并让它跟随同一个 Effect 版本组；它用于处理框架选定 Effect beta 版本在
+24 小时成熟期内的安装，以及 `effect` 和 `@effect/opentelemetry` 从 trusted-publisher
+metadata 迁移到 provenance attestation 时的 pnpm no-downgrade 检查。
+
+## 契约测试
+
+严格 Effect API 测试应当测试声明的 `HttpApi` 契约，而不是原始 request handler。
+Edge 兼容测试可以使用框架 helper：
+
+```ts
+import { createEffectBffTestHandler } from '@modern-js/plugin-bff/effect-edge';
+import apiModule from '../api/index';
+
+const testApi = await createEffectBffTestHandler({
+  module: apiModule,
+  prefix: '/api',
+});
+
+const response = await testApi.handler(new Request('http://localhost/api/ping'));
+```
+
+如果低层 proof 必须手动组合 web handler，需要在调用 `HttpRouter.toWebHandler` 前提供
+`HttpServer.layerServices`：
+
+```ts
+import {
+  HttpApiBuilder,
+  HttpRouter,
+  HttpServer,
+  Layer,
+} from '@modern-js/plugin-bff/effect-server';
+
+const handler = HttpRouter.toWebHandler(
+  HttpApiBuilder.layer(api).pipe(
+    Layer.provide(apiGroupLayer),
+    Layer.provide(HttpServer.layerServices),
+  ),
+).handler;
+```
+
+优先使用生成 helper，除非测试必须检查底层 Effect router 组合。
+
+## 动态 CORS
+
+需要动态 origin predicate 时，使用 Effect HTTP middleware 作为 Layer。在当前锁定的
+Effect v4 beta 版本组中，`HttpRouter.middleware(...)` 直接返回 `Layer`：
+
+```ts
+import {
+  Effect,
+  HttpApiBuilder,
+  HttpMiddleware,
+  HttpRouter,
+  Layer,
+} from '@modern-js/plugin-bff/effect-server';
+
+const corsLayer = HttpRouter.middleware(
+  Effect.succeed(
+    HttpMiddleware.cors({
+      allowedOrigins: origin =>
+        origin.endsWith('.example.com') ? origin : undefined,
+    }),
+  ),
+);
+
+const layer = HttpApiBuilder.layer(api).pipe(
+  Layer.provide(apiGroupLayer),
+  Layer.provide(corsLayer),
+);
+```
+
+不要从 `HttpRouter.middleware(...)` 读取 `.layer` 属性。
+
+## 其他传输
+
+`strictEffectApproach` 约束生成的 HTTP API 模块。Effect RPC、WebSocket 和其他传输在
+建模为显式传输 surface、并使用类型化 Effect 程序时仍然有效。它们不让生成的
+UltraModern API 模块中的原始 HTTP request handler 变得有效。

package/docs/zh/configure/app/performance/build-cache.mdx

@@ -28,6 +28,10 @@ type BuildCacheConfig =
 
 控制 Modern.js 在构建过程中的缓存行为。
 
+启用 Rspack 持久化缓存时，Modern.js 会把 `cacheDirectory` 视为基础目录，并为每个
+Rsbuild/Rspack environment 写入独立子目录，例如 `client`、`server` 或
+`workerSSR`。这样可以避免并发 environment compiler 写入同一个文件系统 cache 根目录。
+
 在构建时，Modern.js 默认会开启构建缓存来提升二次构建的速度。如果不希望缓存，你可以将 `buildCache` 置为 `false` 将其禁用掉：
 
 ```js

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

@@ -71,11 +71,34 @@ mise exec -- pnpm check
 mise exec -- pnpm build
 ```
 
-严格生成 API 迁移要求 `3.5.0-ultramodern.0` 或更新版本。
+严格生成 API 迁移要求 `3.5.0-ultramodern.10` 或更新版本。
 `3.4.0-ultramodern.20` 及更早 cohort 还没有这套完整的直接
-`api/index.ts` 生成器、生成的 `.mts` 检查和严格 Oxlint 边界规则。还不能安装该
-BleedingDev cohort 的 agent 应使用本地 Modern.js workspace 做迁移校验；否则用
-`--ultramodern-package-version` 固定 `3.5.0-ultramodern.0` 或更新版本。
+`api/index.ts` 生成器、生成的 `.mts` 检查、严格 Oxlint 边界规则、Effect 版本组
+overrides 和严格 Effect 迁移命令。还不能安装该 BleedingDev cohort 的 agent 应使用本地
+Modern.js workspace 做迁移校验；否则用 `--ultramodern-package-version` 固定
+`3.5.0-ultramodern.10` 或更新版本。
+
+手写 package alias 或生成 metadata 之前，先在目标 workspace 运行框架迁移命令：
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create@3.5.0-ultramodern.10 ultramodern \
+  migrate-strict-effect --version 3.5.0-ultramodern.10
+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-beta.91` 和 `@effect/vitest@4.0.0-beta.91`。不要添加与这些
+overrides 冲突的 app 本地直接 Effect 版本。生成的 pnpm policy 还会为
+`effect@4.0.0-beta.91` 和 `@effect/opentelemetry@4.0.0-beta.91` 添加例外，避免框架选定的
+Effect beta 版本组被 24 小时成熟期检查，或从 trusted-publisher metadata 迁移到
+provenance attestation 时被 no-downgrade 检查误拦截。
 
 渐进迁移意味着尚未迁移的旧 Modern.js app 可以保留现有 runtime，直到被转换为
 UltraModern。一个 surface 一旦生成为或迁移为 UltraModern HTTP API，就只能使用
@@ -110,6 +133,15 @@ shim 来让旧布局通过。
 Effect RPC、WebSockets 和其他传输方式应在需要时作为显式 transport surface 增加。
 它们不能作为在生成 HTTP API 模块中重新引入原始 request handler 的理由。
 
+严格 API 测试应执行 `HttpApi` 契约。Edge 兼容 proof 测试使用
+`@modern-js/plugin-bff/effect-edge` 的 `createEffectBffTestHandler`；如果必须手动组合
+web handler，在调用 `HttpRouter.toWebHandler` 前要把 `HttpServer.layerServices` 和
+API group layer 一起提供。
+
+动态 origin CORS predicate 使用
+`HttpRouter.middleware(Effect.succeed(HttpMiddleware.cors(...)))`。在固定的 Effect
+版本组中，`HttpRouter.middleware(...)` 直接返回 `Layer`；不要读取 `.layer` 属性。
+
 每个仓库只使用一种 package-source 策略。已发布的 BleedingDev create 包默认使用
 `--ultramodern-package-source=install`，并把精确 cohort 记录到
 `.modernjs/ultramodern.json`。`--workspace` 只用于本地 monorepo
@@ -127,6 +159,12 @@ CommonJS，同时生成的 app package 继续为 Module Federation DTS 保留稳
 ownership、package-source、本地 overlay、生成契约、Tailwind prefix 或 Module
 Federation 冲突，都应在对应归属文件中修复，不要手写补丁覆盖生成结果。
 
+Cloudflare D1 绑定使用一等配置 `deploy.worker.d1Databases`；生成 app 拥有 D1
+migration 时不要再用 app 本地 postprocess。Cloudflare public output 默认排除服务端
+`api` 和 `shared` 目录，并且生成的 Modern/Rspack cache 会按 app、构建目标和 Rspack
+environment 隔离，避免本地 `build`、`cloudflare:build` 以及多 environment compiler
+共享同一个文件系统 cache 目录。
+
 ## 人类工作流
 
 公开的 BleedingDev create 包只有一个受支持的生成产品。默认命令会创建一个

package/package.json

@@ -19,24 +19,24 @@
     "modern.js",
     "ultramodern.js"
   ],
-  "version": "3.5.0-ultramodern.0",
+  "version": "3.5.0-ultramodern.10",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "dependencies": {
-    "mermaid": "^11.15.0",
-    "@modern-js/sandpack-react": "npm:@bleedingdev/modern-js-sandpack-react@3.5.0-ultramodern.0"
+    "mermaid": "^11.16.0",
+    "@modern-js/sandpack-react": "npm:@bleedingdev/modern-js-sandpack-react@3.5.0-ultramodern.10"
   },
   "devDependencies": {
     "@rsbuild/plugin-sass": "2.0.0",
-    "@rspress/core": "2.0.14",
-    "@rspress/plugin-llms": "2.0.14",
-    "@rspress/shared": "2.0.14",
+    "@rspress/core": "2.0.15",
+    "@rspress/plugin-llms": "2.0.15",
+    "@rspress/shared": "2.0.15",
     "@shikijs/transformers": "^4.3.0",
     "@types/fs-extra": "11.0.4",
     "@types/node": "^26.0.1",
-    "@typescript/native-preview": "7.0.0-dev.20260624.1",
+    "@typescript/native-preview": "7.0.0-dev.20260628.1",
     "classnames": "^2.5.1",
     "clsx": "^2.1.1",
     "fs-extra": "^11.3.5",