@vcp-dev/site-edit-engine

VCP 的源码级 site edit 引擎。它读取 snapshot 或项目文件，构建 render document / object detail，并把高层编辑操作规划为 patch plan 或直接执行到预览工作区。

环境要求

• Node.js >=24

安装

npm install @vcp-dev/contracts @vcp-dev/site-edit-engine

主入口能力

主入口 @vcp-dev/site-edit-engine 暴露 runtime facade，以及 runtime 真正复用的样式策略扫描和 文件历史原语：

• createSiteEditEngineRuntime
• SnapshotSiteEditEngineRuntime
• createPreviewSiteEditEngineRuntime
• PreviewFileSystemSiteEditEngineRuntime
• scanSiteEditThemeStyleViolations / SITE_EDIT_RAW_COLOR_LITERAL_RE
• openFileHistoryStore / FileHistoryStoreError
• 相关 runtime、style policy 与 file history public types

子路径

• @vcp-dev/site-edit-engine/next-app-router Next App Router 路由扫描与 routeId 解析工具。
• @vcp-dev/site-edit-engine/source-watcher 预览场景使用的源码监听器。
• @vcp-dev/site-edit-engine/site-edit-instrumentation-loader 仅用于 preview / instrumentation 的 bundler-neutral loader。
• @vcp-dev/site-edit-engine/webpack-loader 兼容旧 Webpack 接入的 legacy alias，复用同一 instrumentation loader 实现。

Snapshot runtime 示例

import { createSiteEditEngineRuntime } from "@vcp-dev/site-edit-engine";

const runtime = createSiteEditEngineRuntime({
  siteId: "018f6f4d-a9b8-7401-8401-0123456789ab",
  snapshotId: "018f6f4d-a9b8-7402-8402-0123456789ab",
  files: [
    {
      path: "app/page.tsx",
      content: "export default function Page(){return <main>Hello</main>}",
    },
  ],
  routes: [{ routeId: "/", entryFile: "app/page.tsx" }],
});

const document = runtime.getDocument("/");
runtime.dispose();

Preview runtime 示例

import { createPreviewSiteEditEngineRuntime } from "@vcp-dev/site-edit-engine";

const runtime = createPreviewSiteEditEngineRuntime({
  siteId: "018f6f4d-a9b8-7401-8401-0123456789ab",
  snapshotId: "018f6f4d-a9b8-7402-8402-0123456789ab",
  projectRoot: "/tmp/site",
  routes: [{ routeId: "/", entryFile: "app/page.tsx" }],
});

await runtime.setActiveRoute("/");
runtime.dispose();

site-edit-instrumentation-loader 说明

@vcp-dev/site-edit-engine/site-edit-instrumentation-loader 只用于开发态 preview instrumentation，负责给 JSX / TSX 注入 VCP 编辑运行时属性。它不是通用的 Next.js 插件平台，也不承诺覆盖 preview instrumentation 之外的构建场景。

旧版 Webpack 配置可继续引用 @vcp-dev/site-edit-engine/webpack-loader。该子路径只是 site-edit-instrumentation-loader 的兼容别名，不维护第二套转换逻辑；新接入建议优先使用 bundler-neutral 子路径。

内部职责边界

内部组织遵循 Site Edit 核心复杂度合同 #71，不改变公开入口、Bridge 协议、operation 或 History/Recovery 语义。

| 职责 | 内部 owner | | ------------------------------------------------------------------- | -------------------------------------------- | | Component identity、alias、namespace、re-export 与引用事实 | planner/component-reference-analysis.ts | | 项目源码/route 可见性与跨文件唯一使用证明 | planner/cross-file-component-analysis.ts | | Repeat callback、collection 与 template-root 结构 | planner/repeat-template-analysis.ts | | Repeat hoist 的 callback/collection 特殊安全规则 | planner/repeat-hoist-safety.ts | | 保留 Repeat 语义的 wrapper 构造 | planner/repeat-template-construction.ts | | Conditional branch/range 与 boundary 识别 | planner/conditional-structure-analysis.ts | | 共享 lexical binding visibility 与 component call-site render scope | planner/scope-safety-analysis.ts | | 静态表达式 normalize、evaluate、follow path | provenance/static-expression-evaluator.ts | | Repeat collection、filter/slice/sort 与实例来源映射 | provenance/repeat-collection-provenance.ts | | Local/imported binding、component prop 与 hook state 来源 | provenance/binding-provenance.ts | | Repeat 实例 document/detail/context/write-target 纯投影 | runtime/repeat-runtime-projection.ts |

以上路径相对于 src/internal/。OperationPlanner 保留 operation 路线和 RewritePlan 组合；prop-backed collection 映射、cross-file collection import 收集及条件源码构造继续由它负责。Cross-file analysis 依赖 Component analysis；Repeat hoist 依赖共享 Scope Safety；analysis/construction 不反向依赖 Planner。

resolve-text-provenance.ts 保留唯一 facade、顶层 resolver 编排、pure/safe-derived helper 与 write-target projection。内部 resolver 通过无请求状态的 factory 和窄回调维持递归，原 visited、file cache 与参数转发保持不变；source helper 只负责解析、AST 查询和原有缓存，下层不反向导入 facade。既有 external/CMS/i18n/API resolver 职责不复制。

createInternalEditEngine() 继续持有 route、mutation、transaction、history/recovery 和事件编排状态。Repeat 投影仅接收 document、graph 和所需 target 的只读视图，不持有 Engine 或生命周期状态。内部 TypeScript 文件与对应测试使用 kebab-case，类和函数符号名保持不变。

每个职责迁移分别运行受影响测试和 Engine typecheck 后提交；最终手动运行 corepack pnpm test:site-edit:coverage。文件长度不作为治理指标。

非目标

@vcp-dev/site-edit-engine 不负责：

• 持久化 snapshot 或管理数据库记录
• 启动或管理 sandbox 生命周期
• 直接执行生产发布
• 暴露 site-edit-bridge 的 transport / WebSocket server API