@bleedingdev/modern-js-main-doc 3.8.2-ultramodern.8 → 3.8.3-ultramodern.1

package/docs/en/components/prerequisites.mdx

@@ -9,7 +9,7 @@ import NodeVersion from '@site-docs-en/components/nodeVersion.mdx';
 It is recommended to use [pnpm](https://pnpm.io/installation) to manage dependencies:
 
 ```bash
-mise use pnpm@11.21.0
+mise use pnpm@11.24.0
 ```
 
 :::note

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

@@ -54,7 +54,7 @@ would give your app a second Effect identity. Before setting
 `/effect-server`, `/effect-edge` or `/effect-client`, install the exact cohort:
 
 ```bash
-pnpm add effect@4.0.0-beta.107 @effect/opentelemetry@4.0.0-beta.107
+pnpm add effect@4.0.0-rc.112 @effect/opentelemetry@4.0.0-rc.112
 ```
 
 The pin is exact because UltraModern ships Effect as one lockstep cohort. Apps
@@ -219,17 +219,17 @@ generated apps use:
 
 ```yaml
 trustPolicyExclude:
-  - 'effect@4.0.0-beta.107'
-  - '@effect/opentelemetry@4.0.0-beta.107'
+  - 'effect@4.0.0-rc.112'
+  - '@effect/opentelemetry@4.0.0-rc.112'
 
 overrides:
-  '@effect/opentelemetry': 4.0.0-beta.107
-  '@effect/vitest': 4.0.0-beta.107
-  effect: 4.0.0-beta.107
+  '@effect/opentelemetry': 4.0.0-rc.112
+  '@effect/vitest': 4.0.0-rc.112
+  effect: 4.0.0-rc.112
 ```
 
 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
+Effect prerelease can fail while building layers or HTTP middleware because runtime
 services come from different package instances. The strict 24-hour release-age
 gate applies to installed packages; the current cohort has no Effect age
 exemption, and override-only `@effect/vitest` is not an installed approval

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

@@ -146,8 +146,8 @@ migration work: move code to `shared/api.ts`, `api/index.ts`, and
 and `src/effect`.
 
 Generated strict Effect workspaces pin the compatible Effect cohort with pnpm
-overrides: `effect@4.0.0-beta.107`, `@effect/opentelemetry@4.0.0-beta.107`,
-and `@effect/vitest@4.0.0-beta.107`. Do not add app-local direct Effect
+overrides: `effect@4.0.0-rc.112`, `@effect/opentelemetry@4.0.0-rc.112`,
+and `@effect/vitest@4.0.0-rc.112`. Do not add app-local direct Effect
 versions that disagree with those overrides. The strict 24-hour release-age
 gate applies to installed packages; this cohort carries no Effect age
 exemption, and override-only `@effect/vitest` is not an installed approval
@@ -159,12 +159,21 @@ metadata transition; they are not release-age approvals.
 
 | Surface | Pin |
 | --- | --- |
-| Effect runtime and test cohort | `effect`, `@effect/opentelemetry`, and `@effect/vitest`: `4.0.0-beta.107` |
-| Effect compiler | `@effect/tsgo@0.36.2` |
-| TanStack Router | `@tanstack/react-router@1.170.25`, `@tanstack/router-core@1.171.21`, `@tanstack/history@1.162.1` |
-| Module Federation | `bridge-react`, `manifest`, `modern-js-v3`, and `rspack`: `2.8.2`; `@module-federation/node@2.7.49` |
-| React Router | `react-router@7.18.2` |
-| Node and package tooling | Node `26.7.0`, `@types/node@^26.2.0`, pnpm `11.21.0` |
+| Effect runtime and test cohort | `effect`, `@effect/opentelemetry`, and `@effect/vitest`: `4.0.0-rc.112` |
+| Effect compiler | `@effect/tsgo@0.37.0` |
+| Oxc and 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` |
+| Module Federation | `bridge-react`, `manifest`, `modern-js-v3`, and `rspack`: `2.9.0`; `@module-federation/node@2.7.50` |
+| Tailwind CSS | `tailwindcss@4.3.3` |
+| Node and package tooling | Node `26.7.0`, `@types/node@^26.2.0`, pnpm `11.24.0` |
+
+Generated workspaces default to Module Federation bridge-react's router-free
+base entry (`bridge.enableBridgeRouter: false`), with TanStack Router as the
+application router. Declaring `react-router` (or `react-router-dom`) as a
+direct dependency of an app marks it a React Router consumer: the
+generator/migration then emit `enableBridgeRouter: true` for that app's
+federation config, the workspace validator accepts it, and the UltraModern
+preset aliases `react-router`'s entrypoints for the app's own routing.
 
 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
@@ -248,6 +257,94 @@ directories, and caches are isolated per app, build target, and Rspack
 environment so local `build`, `cloudflare:build`, and multi-environment
 compilers do not share mutable build state.
 
+## Configure the public preset
+
+Use `presetUltramodern(appConfig, presetOptions)` inside the normal Modern.js
+`defineConfig` call:
+
+```ts title="modern.config.ts"
+import { defineConfig, presetUltramodern } from '@modern-js/app-tools';
+
+export default defineConfig(
+  presetUltramodern(
+    {
+      output: {
+        precompress: false,
+      },
+      server: {
+        telemetry: {
+          failLoudStartup: true,
+        },
+      },
+    },
+    {
+      appId: 'catalog',
+      enableModuleFederationSSR: false,
+      enableTelemetryExporters: false,
+    },
+  ),
+);
+```
+
+The first argument is ordinary `AppUserConfig`. It contains app-owned config
+and wins where it supplies an override. The second argument controls the
+preset itself. Use its typed options, such as `enableBffRequestId: false`,
+`enableTelemetry: false`, `enableTelemetryExporters: false`, and
+`enableModuleFederationSSR: false`, to turn preset features off.
+
+Composition follows the Modern.js config merge rules:
+
+- Nested records merge, so changing one nested field keeps its preset
+  siblings.
+- Scalars and `false` supplied by the app override preset values. Omitting a
+  field, or leaving it `undefined`, keeps the preset value.
+- Arrays and config hooks compose in preset-first order. Non-function array
+  entries are deduplicated by deep equality, while function entries are all
+  retained. An empty array or empty record does not clear values already
+  supplied by the preset.
+
+There is no generic reset sentinel. Use a typed preset option for preset-owned
+behavior and a normal app config override for app-owned behavior.
+
+`createPresetUltramodernConfig(options)` is an advanced API for inspecting or
+materializing a fresh preset config. Do not spread its result into another
+config object. Object spread is shallow, so replacing `server`, `output`, or
+another nested record can silently discard preset siblings. Use
+`presetUltramodern(...)` for authoring `modern.config.ts`.
+
+### Bare preset and generated workspace policy
+
+The preset and the workspace generator own different parts of the config:
+
+| Source | Identity | Remaining config |
+| --- | --- | --- |
+| Bare `createPresetUltramodernConfig()` result | Uses `appId: 'app'` and has no `deliveryUnit` | Uses the preset defaults. Telemetry stays enabled, but no exporter is configured until its endpoint is set. |
+| Generated app | Supplies the app-specific `appId` and stamped `deliveryUnit` | Inherits the other strict defaults from `presetUltramodern(...)`. |
+| Application | Supplies the first `appConfig` argument | Overrides app-owned fields through the normal Modern.js merge. |
+
+Keep the generated `appId` and `deliveryUnit` options intact. To change
+preset-owned behavior, use typed options such as
+`enableTelemetryExporters: false`,
+`enableTelemetry: false`, `enableBffRequestId: false`, or
+`enableModuleFederationSSR: false`. To change an app-owned field, put the
+override in the first argument, as in the example above.
+
+Telemetry exporter endpoints are unset by default:
+
+- `MODERN_TELEMETRY_OTLP_ENDPOINT` enables only the OTLP exporter.
+- `MODERN_TELEMETRY_VICTORIA_ENDPOINT` enables only the VictoriaMetrics
+  exporter.
+- Setting both enables both. Leaving both unset keeps the telemetry pipeline
+  enabled without configuring an exporter.
+
+The typed `otlpEndpoint` and `victoriaMetricsEndpoint` preset options provide
+the same per-exporter behavior without environment variables.
+
+```bash
+MODERN_TELEMETRY_OTLP_ENDPOINT=https://otel.example.com/v1/logs \
+  mise exec -- pnpm dev
+```
+
 ## Human Workflow
 
 The public BleedingDev create package has one supported generated product. The
@@ -426,18 +523,6 @@ BleedingDev packages are published through GitHub Actions trusted publishing.
 The public workflow is tokenless; do not publish packages manually from a
 developer machine.
 
-## Baseline Switches (Opt-out)
-
-The generated `presetUltramodern(...)` starter enables strict platform contracts. Use these env switches to opt out per app or per environment:
-
-- `MODERN_BASELINE_ENABLE_MF_SSR` (default: `true`): Enables app-level MF SSR baseline contract (`server.ssr.mode: 'stream'` + `moduleFederationAppSSR`). Disable when the app does not use app-level MF SSR, or when you need plain SSR/CSR behavior first.
-- `MODERN_BASELINE_ENABLE_BFF_REQUEST_ID` (default: `true`): Enables default BFF producer identity contract (`bff.requestId`). Disable when the app does not need cross-project producer isolation.
-- `MODERN_BASELINE_ENABLE_TELEMETRY_EXPORTERS` (default: `true`): Enables telemetry exporters in baseline config. Disable when the environment has no telemetry backend yet.
-- `MODERN_BASELINE_APP_ID` (default: `basename(process.cwd())`): Overrides baseline `bff.requestId` identity. Set this when you need a fixed platform-wide producer ID convention.
-- `MODERN_TELEMETRY_OTLP_ENDPOINT` (default: `http://127.0.0.1:4318/v1/logs`): OTLP exporter endpoint. Override when you route telemetry through a different collector endpoint.
-- `MODERN_TELEMETRY_VICTORIA_ENDPOINT` (default: `http://127.0.0.1:8428/api/v1/import/prometheus`): VictoriaMetrics exporter endpoint. Override when you use a different VM ingress endpoint.
-- `MODERN_TELEMETRY_FAIL_LOUD_STARTUP` (default: `true`): Fails startup if configured exporters fail startup health checks. Disable in local/dev environments where temporary telemetry outage should not block boot.
-
 ## Related Docs
 
 - [BFF Runtime Frameworks](/guides/advanced-features/bff/frameworks)

package/docs/zh/components/prerequisites.mdx

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

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

@@ -53,7 +53,7 @@ import EnableBFFCaution from "@site-docs/components/enable-bff-caution";
 `/effect-client` 之前，请安装精确版本的依赖组：
 
 ```bash
-pnpm add effect@4.0.0-beta.107 @effect/opentelemetry@4.0.0-beta.107
+pnpm add effect@4.0.0-rc.112 @effect/opentelemetry@4.0.0-rc.112
 ```
 
 采用精确版本是因为 UltraModern 以锁步依赖组的方式发布 Effect。只使用
@@ -214,16 +214,16 @@ Effect 版本组。当前 UltraModern 版本组使用：
 
 ```yaml
 trustPolicyExclude:
-  - 'effect@4.0.0-beta.107'
-  - '@effect/opentelemetry@4.0.0-beta.107'
+  - 'effect@4.0.0-rc.112'
+  - '@effect/opentelemetry@4.0.0-rc.112'
 
 overrides:
-  '@effect/opentelemetry': 4.0.0-beta.107
-  '@effect/vitest': 4.0.0-beta.107
-  effect: 4.0.0-beta.107
+  '@effect/opentelemetry': 4.0.0-rc.112
+  '@effect/vitest': 4.0.0-rc.112
+  effect: 4.0.0-rc.112
 ```
 
-不要在应用包里添加不同版本的直接 `effect` 依赖。Effect beta 不一致时，Layer 或 HTTP
+不要在应用包里添加不同版本的直接 `effect` 依赖。Effect 预发布版本不一致时，Layer 或 HTTP
 middleware 构建可能因为运行时 service 来自不同包实例而失败。严格的 24 小时发布年龄
 门禁适用于实际安装的包；当前版本组没有 Effect 年龄豁免，且仅用于 override 的
 `@effect/vitest` 不是已安装的审批目标。

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

@@ -128,8 +128,8 @@ pnpm overrides/trust policy 和 pnpm lockfile。剩余失败就是源码迁移
 `api/lambda`、`shared/effect` 和 `src/effect`。
 
 严格 Effect 生成 workspace 会通过 pnpm overrides 固定兼容版本组：
-`effect@4.0.0-beta.107`、`@effect/opentelemetry@4.0.0-beta.107` 和
-`@effect/vitest@4.0.0-beta.107`。不要添加与这些 overrides 冲突的 app 本地直接
+`effect@4.0.0-rc.112`、`@effect/opentelemetry@4.0.0-rc.112` 和
+`@effect/vitest@4.0.0-rc.112`。不要添加与这些 overrides 冲突的 app 本地直接
 Effect 版本。严格的 24 小时发布年龄门禁适用于实际安装的包；当前版本组不包含 Effect
 年龄豁免，仅用于 override 的 `@effect/vitest` 也不是已安装的审批目标。
 `trustPolicyExclude` 是独立策略，仅为 `effect` 和
@@ -140,12 +140,21 @@ provenance attestation 的迁移；它不属于 release-age 审批。
 
 | 范围 | 固定版本 |
 | --- | --- |
-| Effect runtime 与测试版本组 | `effect`、`@effect/opentelemetry`、`@effect/vitest`：`4.0.0-beta.107` |
-| Effect compiler | `@effect/tsgo@0.36.2` |
-| TanStack Router | `@tanstack/react-router@1.170.25`、`@tanstack/router-core@1.171.21`、`@tanstack/history@1.162.1` |
-| Module Federation | `bridge-react`、`manifest`、`modern-js-v3`、`rspack`：`2.8.2`；`@module-federation/node@2.7.49` |
-| React Router | `react-router@7.18.2` |
-| Node 与包管理工具 | Node `26.7.0`、`@types/node@^26.2.0`、pnpm `11.21.0` |
+| 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` |
+| 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` |
+
+生成的 workspace 默认使用 `@module-federation/bridge-react` 的
+router-free base entry（`bridge.enableBridgeRouter: false`），应用路由由
+TanStack Router 承担；某个 app 的 package.json 直接依赖中声明了
+`react-router`（或 `react-router-dom`），该 app 就会被标记为 React Router
+consumer：generator/migration 会为该 app 的 federation 配置生成
+`enableBridgeRouter: true`，workspace validator 也会接受这个值，UltraModern
+preset 会为该 app 自身的路由 alias `react-router` 的入口。
 
 渐进迁移意味着尚未迁移的旧 Modern.js app 可以保留现有 runtime，直到被转换为
 UltraModern。一个 surface 一旦生成为或迁移为 UltraModern HTTP API，就只能使用
@@ -212,6 +221,87 @@ migration 时不要再用 app 本地 postprocess。Cloudflare public output 默
 会按 app、构建目标和 Rspack environment 隔离，避免本地 `build`、`cloudflare:build`
 以及多 environment compiler 共享可变构建状态。
 
+## 配置公开预设
+
+在标准 Modern.js `defineConfig` 调用中使用
+`presetUltramodern(appConfig, presetOptions)`：
+
+```ts title="modern.config.ts"
+import { defineConfig, presetUltramodern } from '@modern-js/app-tools';
+
+export default defineConfig(
+  presetUltramodern(
+    {
+      output: {
+        precompress: false,
+      },
+      server: {
+        telemetry: {
+          failLoudStartup: true,
+        },
+      },
+    },
+    {
+      appId: 'catalog',
+      enableModuleFederationSSR: false,
+      enableTelemetryExporters: false,
+    },
+  ),
+);
+```
+
+第一个参数是普通的 `AppUserConfig`，用于应用自己拥有的配置，并在提供覆盖值时胜出。
+第二个参数控制预设本身。关闭预设能力时，使用它提供的类型化选项，例如
+`enableBffRequestId: false`、`enableTelemetry: false`、
+`enableTelemetryExporters: false` 和 `enableModuleFederationSSR: false`。
+
+组合过程遵循 Modern.js 配置合并规则：
+
+- 嵌套对象会递归合并。修改一个嵌套字段时，预设中的同级字段会保留。
+- 应用提供的标量和 `false` 会覆盖预设值。省略字段或将其保留为 `undefined` 时，
+  预设值会保留。
+- 数组和配置 hook 按预设优先的顺序组合。非函数数组项按深度相等去重，函数项则全部
+  保留。空数组或空对象不会清除预设已经提供的值。
+
+这里没有通用的 reset sentinel。预设拥有的行为应使用类型化预设选项控制，应用拥有的
+行为应使用普通应用配置覆盖。
+
+`createPresetUltramodernConfig(options)` 是用于检查或生成一份全新预设配置的高级 API。
+不要把它的结果展开进另一个配置对象。对象展开是浅层操作，替换 `server`、`output`
+或其他嵌套对象时，会无提示地丢弃预设中的同级字段。编写 `modern.config.ts` 时应使用
+`presetUltramodern(...)`。
+
+### 裸预设与生成 workspace 的策略
+
+预设和 workspace 生成器分别负责不同的配置：
+
+| 来源 | 身份配置 | 其他配置 |
+| --- | --- | --- |
+| 裸 `createPresetUltramodernConfig()` 的结果 | 使用 `appId: 'app'`，不设置 `deliveryUnit` | 使用预设默认值。Telemetry 保持启用，但只有设置具体端点后才会配置对应导出器。 |
+| 生成的应用 | 提供应用专属的 `appId` 和生成时写入的 `deliveryUnit` | 其他严格默认值继承自 `presetUltramodern(...)`。 |
+| 应用 | 通过第一个 `appConfig` 参数提供配置 | 按 Modern.js 的正常合并规则覆盖应用拥有的字段。 |
+
+应保留生成的 `appId` 和 `deliveryUnit` 选项。修改预设拥有的行为时，使用类型化选项，
+例如
+`enableTelemetryExporters: false`、`enableTelemetry: false`、
+`enableBffRequestId: false` 或 `enableModuleFederationSSR: false`。修改应用拥有的
+字段时，应像上面的示例一样，把覆盖值放在第一个参数中。
+
+Telemetry 导出端点默认不设置：
+
+- `MODERN_TELEMETRY_OTLP_ENDPOINT` 只启用 OTLP 导出器。
+- `MODERN_TELEMETRY_VICTORIA_ENDPOINT` 只启用 VictoriaMetrics 导出器。
+- 同时设置两个变量会启用两个导出器。两个变量都未设置时，telemetry 管线保持启用，
+  但不会配置导出器。
+
+类型化的 `otlpEndpoint` 和 `victoriaMetricsEndpoint` 预设选项也能提供同样的
+逐导出器行为，无需使用环境变量。
+
+```bash
+MODERN_TELEMETRY_OTLP_ENDPOINT=https://otel.example.com/v1/logs \
+  mise exec -- pnpm dev
+```
+
 ## 人类工作流
 
 公开的 BleedingDev create 包只有一个受支持的生成产品。默认命令会创建一个
@@ -377,18 +467,6 @@ Live Cloudflare 与 Zephyr 证明需要公开 Worker URL 和 Zephyr 凭据。没
 BleedingDev 包通过 GitHub Actions trusted publishing 发布。公开发布 workflow 不使用
 长期 npm token；不要从开发机器手动发布包。
 
-## 基线开关（可按需关闭）
-
-生成的 `presetUltramodern(...)` 脚手架会开启更严格的平台契约。以下环境变量会在生成的 `modern.config.ts` 中读取，可按应用或按环境关闭/覆盖：
-
-- `MODERN_BASELINE_ENABLE_MF_SSR`（默认：`true`）：开启应用级 MF SSR 基线契约（`server.ssr.mode: 'stream'` + `moduleFederationAppSSR`）。应用不使用 app-level MF SSR 或希望先走普通 SSR/CSR 路径时可关闭。
-- `MODERN_BASELINE_ENABLE_BFF_REQUEST_ID`（默认：`true`）：开启默认 BFF producer 身份契约（`bff.requestId`）。应用不需要跨项目 producer 隔离时可关闭。
-- `MODERN_BASELINE_ENABLE_TELEMETRY_EXPORTERS`（默认：`true`）：在基线配置中启用 telemetry 导出器。当前环境还没有 telemetry 后端时可关闭。
-- `MODERN_BASELINE_APP_ID`（默认：`basename(process.cwd())`）：覆盖基线 `bff.requestId` 身份。需要固定、可治理的统一 producer ID 命名时建议设置。
-- `MODERN_TELEMETRY_OTLP_ENDPOINT`（默认：`http://127.0.0.1:4318/v1/logs`）：OTLP 导出端点。接入其他 OTLP collector 地址时覆盖。
-- `MODERN_TELEMETRY_VICTORIA_ENDPOINT`（默认：`http://127.0.0.1:8428/api/v1/import/prometheus`）：VictoriaMetrics 导出端点。接入其他 VM 写入地址时覆盖。
-- `MODERN_TELEMETRY_FAIL_LOUD_STARTUP`（默认：`true`）：导出器健康检查失败时启动即失败（fail-loud）。本地/开发环境希望 telemetry 故障不阻断启动时可关闭。
-
 ## 相关文档
 
 - [BFF 运行时框架](/guides/advanced-features/bff/frameworks)

package/package.json

@@ -19,12 +19,12 @@
     "modern.js",
     "ultramodern.js"
   ],
-  "version": "3.8.2-ultramodern.8",
+  "version": "3.8.3-ultramodern.1",
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@modern-js/sandpack-react": "npm:@bleedingdev/modern-js-sandpack-react@3.8.2-ultramodern.8",
+    "@modern-js/sandpack-react": "npm:@bleedingdev/modern-js-sandpack-react@3.8.3-ultramodern.1",
     "mermaid": "^11.16.0"
   },
   "devDependencies": {