@vcp-dev/site-edit-bridge 0.6.10 → 0.7.0

package/README.md

@@ -1,15 +1,34 @@
 # @vcp-dev/site-edit-bridge
 
-浏览器端 site edit client、自动 bootstrap 以及 Node 侧 WebSocket bridge server。
+生成站点与 VCP Designer/preview 之间的受控桥接包。它在 `@vcp-dev/site-edit-engine` 合同之上提供浏览器 client、window message codec、server/Next 开发服务器适配和调试 trace；不包含平台 UI，也不持有 VCP secret。
 
-## 安装
+## 要求
+
+- Node.js 24+
+- 由生成站点或 preview 准备流程注入与当前 runtime 匹配的包版本
+- active edit 必须通过共享 edit-engine version gate；版本不一致时刷新 runtime，不在请求中临时安装
+
+## 导出
+
+| Import                                  | 用途                                 |
+| --------------------------------------- | ------------------------------------ |
+| `@vcp-dev/site-edit-bridge`                 | 公共类型与组合入口。                 |
+| `@vcp-dev/site-edit-bridge/client`          | 浏览器端 bridge client。             |
+| `@vcp-dev/site-edit-bridge/auto-bootstrap`  | 受控的浏览器自动装配。               |
+| `@vcp-dev/site-edit-bridge/document-codec`  | 文档/消息编码与解析。                |
+| `@vcp-dev/site-edit-bridge/designer-trace`  | Designer 调试 trace 合同。           |
+| `@vcp-dev/site-edit-bridge/window-message`  | `postMessage` wire schema 与 guard。 |
+| `@vcp-dev/site-edit-bridge/server`          | Node/server 侧能力。                 |
+| `@vcp-dev/site-edit-bridge/next-dev-server` | Next preview 开发服务器适配。        |
+
+包还发布 `vcp-site-edit-next-dev-server` CLI，供受控 preview 启动流程使用。不要把它替换成浏览器可提交的任意 shell 命令。
+
+## 开发
 
 ```bash
-npm install @vcp-dev/contracts @vcp-dev/site-edit-engine @vcp-dev/site-edit-bridge
+corepack pnpm --filter @vcp-dev/site-edit-bridge typecheck
+corepack pnpm --filter @vcp-dev/site-edit-bridge test
+corepack pnpm --filter @vcp-dev/site-edit-bridge build
 ```
 
-## 用途
-
-- 浏览器 WebSocket client
-- 自动接入页面桥接
-- Node.js WebSocket bridge server
+发布必须使用仓库的 `vcp-edit-engine-package-releaser` 流程，确保 `contracts`、engine、bridge 和模板/runtime 版本关系一起验证。

package/dist/auto-bootstrap.d.ts

@@ -1,4 +1,4 @@
-import type { SiteEditRenderDocument, SiteEditRenderEntry } from "@vcp-dev/contracts";
+import type { SiteEditCompositionContext, SiteEditRenderDocument, SiteEditRenderEntry } from "@vcp-dev/contracts";
 import { type SiteEditBridgeClient, type SiteEditBridge, type SiteEditBridgeConnectionStatus, type SiteEditBridgeConnectionState } from "./client.js";
 import { type SiteEditFrameRuntimeBridgeStatus, type SiteEditFrameRuntimeRequestBody } from "./window-message.js";
 declare global {
@@ -7,6 +7,8 @@ declare global {
         __VCP_SITE_EDIT_AUTO_BOOTSTRAP__?: {
             started: boolean;
             routeId?: string;
+            composition?: SiteEditCompositionContext;
+            compositionKey?: string;
             signature?: SiteEditAutoBootstrapSignature;
             cleanup?: () => void;
             syncRoute?: () => Promise<void>;
@@ -16,8 +18,17 @@ declare global {
 }
 export declare const VCP_SITE_EDIT_ROUTE_READY_EVENT = "vcp-site-edit:route-ready";
 export declare const VCP_SITE_EDIT_BRIDGE_STATUS_EVENT = "vcp-site-edit:bridge-status";
+export declare const VCP_PAGE_TEMPLATE_CONTEXT_MARKER_ATTRIBUTE = "data-vcp-page-template-context";
+export declare const VCP_PAGE_TEMPLATE_CONTEXT_MARKER_VALUE = "1";
+export declare const VCP_PAGE_TEMPLATE_ROUTE_ID_ATTRIBUTE = "data-vcp-route-id";
+export declare const VCP_PAGE_TEMPLATE_EFFECTIVE_TEMPLATE_ID_ATTRIBUTE = "data-vcp-effective-template-id";
+export declare const VCP_PAGE_TEMPLATE_CONTEXT_MARKER_SELECTOR = "[data-vcp-page-template-context=\"1\"]";
+export declare const SITE_EDIT_COMPOSITION_MARKER_INVALID = "SITE_EDIT_COMPOSITION_MARKER_INVALID";
+export declare const SITE_EDIT_COMPOSITION_RENDER_MISMATCH = "SITE_EDIT_COMPOSITION_RENDER_MISMATCH";
 export type SiteEditRouteReadyDetail = {
-    routeId: string;
+    composition: SiteEditCompositionContext;
+    editEngineVersion: string;
+    sequence: number;
     version: number;
 };
 export type SiteEditBridgeStatusDetail = SiteEditFrameRuntimeBridgeStatus;
@@ -57,6 +68,12 @@ type BridgeFrameRuntimeRequestBody = Extract<SiteEditFrameRuntimeRequestBody, {
     kind: "bridge-initialize-session" | "bridge-get-document" | "bridge-get-history-status" | "bridge-get-style-context" | "bridge-ensure-document-version" | "bridge-acknowledge-document-version" | "bridge-get-object-edit-context" | "bridge-get-class-name-source" | "bridge-get-source-tree" | "bridge-get-source-file" | "bridge-resolve-source-location" | "bridge-execute" | "bridge-undo" | "bridge-redo" | "bridge-subscribe" | "bridge-unsubscribe";
 }>;
 export declare function resolveSiteEditRouteId(pathname: string, basePath?: string): string;
+export declare function readVcpPageTemplateContextMarker(documentLike: Pick<Document, "querySelectorAll">): SiteEditCompositionContext | null;
+export declare function resolveBrowserCompositionContext(input: {
+    pathname: string;
+    document: Pick<Document, "querySelectorAll">;
+    basePath?: string;
+}): SiteEditCompositionContext;
 export declare function resolveSiteEditWebSocketUrl(windowLike: Pick<Window, "location">, options?: {
     explicit_ws_url?: string;
     port?: string;