doper 迁移指南

状态：M5-A 初版。面向按页面粒度从存量渲染引擎迁移到 doper 的业务团队。 存量引擎代码不在本仓库；本指南约定的是边界契约与回退操作。

1. 迁移模型

迁移以页面为最小粒度，通过 @dopejs/pingo-compat 的 mountCompatPage 建立边界：

import { mountCompatPage } from "@dopejs/pingo-compat";

const page = await mountCompatPage({
  pageId: "orders",
  container,
  render: renderOrdersPage, // 返回 doper JSX/DoperNode
  legacy: legacyOrdersRenderer, // 存量路径，必须保持可挂载
  enabled: rollout.isEnabled("orders"), // 灰度开关
  onFallback: (reason) => report(reason), // 观测钩子
});

• enabled: false 时页面完全由存量渲染器接管，doper 不初始化。
• page.enable() / page.fallback(detail) 支持运行时切换； 初始化失败与连续运行时错误（默认 3 次）自动回退到存量路径。
• shim 只依赖 @dopejs/pingo 公开 facade；删除 shim 不需要修改引擎。

2. 业务代码约束

自动扫描器（node scripts/check-migration.mjs <业务源码目录>）强制以下 约束，违规即报告并以非零码退出：

规则	说明
internal-package-import	只能 import @dopejs/pingo（含 /jsx-runtime 等子路径）与 @dopejs/pingo-compat；@dopejs/pingo-host 等内部包不属于公开契约
embed-dom-input	禁止 per-widget HTML input/textarea；caret、selection、IME、剪贴板由引擎输入桥统一托管
force-update	不存在 forceUpdate 逃生口；失效由 prop 语义驱动

3. 能力矩阵与已知限制

• 支持：TSX function component、hooks/signals、原生虚拟滚动、 EditableText/TextField/TextArea、语义树 E2E 选择器、 SAB → postMessage → 主线程 Canvas2D 降级链。
• 显式延后：bidi 视觉导航（随 bidi 文本能力）、widgets placeholder （待 overlay 布局能力）、WebGPU 后端（默认关闭，见 ADR）。
• 不做：SSR/HTML 首屏、通用 CSS 兼容、业务级富文本语义。

4. 回退操作

1. 灰度关断：把页面的 enabled 置 false 并重新加载，doper 不再初始化。
2. 运行时回退：调用 page.fallback("原因")；存量渲染器立即重新挂载。
3. 自动回退：初始化失败或连续 host 错误达到阈值时自动触发， onFallback 携带 initialization-failed / runtime-error 原因。
4. 能力降级：Worker/SAB 不可用时引擎自动退到主线程 Canvas2D， 无需业务参与（见 design.md 降级链）。

事故处置步骤见 docs/runbook.md（M5-C）。