@vcp-prod/site-edit-engine 0.3.14

package/README.md

@@ -0,0 +1,85 @@
+# `@vcp-prod/site-edit-engine`
+
+VCP 的源码级 site edit 引擎。它读取 snapshot 或项目文件，构建 render
+document / object detail，并把高层编辑操作规划为 patch plan 或直接执行到预览工作区。
+
+## 环境要求
+
+- Node.js `>=24`
+
+## 安装
+
+```bash
+npm install @vcp-prod/contracts @vcp-prod/site-edit-engine
+```
+
+## 主入口能力
+
+主入口 `@vcp-prod/site-edit-engine` 只暴露稳定 runtime facade：
+
+- `createSiteEditEngineRuntime`
+- `SnapshotSiteEditEngineRuntime`
+- `createPreviewSiteEditEngineRuntime`
+- `PreviewFileSystemSiteEditEngineRuntime`
+- 相关 runtime public types
+
+## 子路径
+
+- `@vcp-prod/site-edit-engine/next-app-router`
+  Next App Router 路由扫描与 routeId 解析工具。
+- `@vcp-prod/site-edit-engine/source-watcher`
+  预览场景使用的源码监听器。
+- `@vcp-prod/site-edit-engine/webpack-loader`
+  仅用于 preview / instrumentation 的 webpack loader。
+
+## Snapshot runtime 示例
+
+```ts
+import { createSiteEditEngineRuntime } from "@vcp-prod/site-edit-engine";
+
+const runtime = createSiteEditEngineRuntime({
+  siteId: "site_123",
+  snapshotId: "snapshot_123",
+  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 示例
+
+```ts
+import { createPreviewSiteEditEngineRuntime } from "@vcp-prod/site-edit-engine";
+
+const runtime = createPreviewSiteEditEngineRuntime({
+  siteId: "site_123",
+  snapshotId: "snapshot_123",
+  projectRoot: "/tmp/site",
+  routes: [{ routeId: "/", entryFile: "app/page.tsx" }],
+});
+
+await runtime.setActiveRoute("/");
+runtime.dispose();
+```
+
+## `webpack-loader` 说明
+
+`@vcp-prod/site-edit-engine/webpack-loader` 只用于开发态 preview instrumentation，
+负责给 JSX / TSX 注入 VCP 编辑运行时属性。它不是通用的 Webpack / Next.js 插件平台，
+也不承诺覆盖 preview instrumentation 之外的构建场景。
+
+## 非目标
+
+`@vcp-prod/site-edit-engine` 不负责：
+
+- 持久化 snapshot 或管理数据库记录
+- 启动或管理 sandbox 生命周期
+- 直接执行生产发布
+- 暴露 `site-edit-bridge` 的 transport / WebSocket server API

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createSiteEditEngineRuntime, SnapshotSiteEditEngineRuntime, } from "./runtime.js";
+export { createPreviewSiteEditEngineRuntime, PreviewFileSystemSiteEditEngineRuntime, } from "./preview-runtime.js";
+export type { PreviewSiteEditEngineRuntime, PreviewSiteEditEngineRuntimeOptions, SiteEditProjectFileSystem, SiteEditEngineRoute, SiteEditEngineRuntime, SiteEditEngineRuntimeOptions, SiteEditPlanOperationResult, SiteEditSnapshotFile, } from "./types.js";