@vcp-dev/site-edit-engine 0.4.9 → 0.6.1

package/dist/internal/protocol/boundary.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 边界种类 —— 标记节点所处的语义边界。
+ *
+ * - component-boundary: 组件调用边界
+ * - repeat-region: .map() / repeat 区域
+ * - conditional-region: 条件渲染区域
+ * - fragment-region: Fragment 包裹
+ * - opaque-region: 不透明 / 外部组件
+ */
+export type BoundaryKind = "component-boundary" | "repeat-region" | "conditional-region" | "fragment-region" | "opaque-region";

package/dist/internal/protocol/capability.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 节点能力快照 —— 描述该节点支持的操作及约束。
+ *
+ * 重要：canMove = true 意味着支持 reorder / reparent / cross-file move，
+ * 不能被收窄为 "只能同级上下移动"。
+ * canInsertChild = true 意味着支持 native-tag 和 component-call 插入，
+ * 不能被收窄为 "只能插入 button"。
+ */
+export interface NodeCapabilitySnapshot {
+    key: string;
+    canUpdateText: boolean;
+    canInsertChild: boolean;
+    canMove: boolean;
+    canRemove: boolean;
+    editModes?: {
+        updateText?: CapabilityModeView;
+        insertChild?: CapabilityModeView;
+        move?: CapabilityModeView;
+        remove?: CapabilityModeView;
+    };
+    constraints: CapabilityConstraint[];
+}
+export interface CapabilityModeView {
+    mode: "direct" | "proxy" | "upstream" | "readonly" | "unsupported";
+    reasonCode?: string;
+}
+/**
+ * 能力约束 —— 描述为什么某个操作受限。
+ */
+export interface CapabilityConstraint {
+    kind: ConstraintKind;
+    message: string;
+}
+/**
+ * 约束种类枚举。
+ *
+ * 每个 kind 对应一种语义限制：
+ * - component-boundary: 跨组件边界操作需要特殊处理
+ * - repeat-region: repeat/map 区域内的限制
+ * - conditional-region: 条件渲染区域限制
+ * - opaque-region: 不透明组件内部不可编辑
+ * - void-element: 自闭合元素不能有子节点
+ * - read-only: 只读数据源
+ * - cross-file-required: 操作需要跨文件协调
+ * - import-required: 组件插入需要添加 import
+ */
+export type ConstraintKind = "component-boundary" | "repeat-region" | "conditional-region" | "opaque-region" | "void-element" | "read-only" | "cross-file-required" | "import-required";

package/dist/internal/protocol/error.d.ts

@@ -0,0 +1,69 @@
+import type { SiteEditOperationErrorCode } from "@vcp-dev/contracts";
+/**
+ * 操作错误码 —— 覆盖从节点查找到写回的所有失败路径。
+ *
+ * 值域以 @vcp-dev/contracts 的 SiteEditOperationErrorCode 为唯一权威源；这里
+ * 保留对象形式，供 engine 内部继续使用 OperationErrorCode.NODE_NOT_FOUND
+ * 这类可读访问方式。
+ */
+export declare const OperationErrorCode: {
+    /** 目标节点 key 在 graph 中不存在 */
+    readonly NODE_NOT_FOUND: "NODE_NOT_FOUND";
+    /** 目标路由不存在 */
+    readonly ROUTE_NOT_FOUND: "ROUTE_NOT_FOUND";
+    /** capability 检查拒绝（如 canMove = false） */
+    readonly CAPABILITY_REJECTED: "CAPABILITY_REJECTED";
+    /** 约束违反（如试图往 void element 插入子节点） */
+    readonly CONSTRAINT_VIOLATED: "CONSTRAINT_VIOLATED";
+    /** 请求参数不合法 */
+    readonly INVALID_PARAMS: "INVALID_PARAMS";
+    /** planner 无法生成合法执行计划 */
+    readonly PLAN_FAILED: "PLAN_FAILED";
+    readonly TRANSACTION_PREFLIGHT_FAILED: "TRANSACTION_PREFLIGHT_FAILED";
+    readonly ROUTE_REBUILD_FAILED: "ROUTE_REBUILD_FAILED";
+    readonly HISTORY_COMMIT_FAILED: "HISTORY_COMMIT_FAILED";
+    readonly MATERIALIZATION_CONFLICT: "MATERIALIZATION_CONFLICT";
+    readonly MATERIALIZATION_REJECTED: "MATERIALIZATION_REJECTED";
+    readonly MUTATION_ASSERTION_REQUIRED: "MUTATION_ASSERTION_REQUIRED";
+    readonly MUTATION_ASSERTION_INVALID: "MUTATION_ASSERTION_INVALID";
+    /** documentVersion 过期 */
+    readonly VERSION_STALE: "VERSION_STALE";
+    /** AST 解析失败 */
+    readonly AST_PARSE_ERROR: "AST_PARSE_ERROR";
+    /** 操作在当前受支持语法形状外 */
+    readonly UNSUPPORTED_OPERATION: "UNSUPPORTED_OPERATION";
+    /** NodeLocator 定位失败 */
+    readonly LOCATOR_FAILED: "LOCATOR_FAILED";
+    /** 目标关系非法，例如无效父子关系或自闭合元素插子节点 */
+    readonly INVALID_TARGET: "INVALID_TARGET";
+    /** 文件写入 I/O 错误 */
+    readonly WRITE_IO_ERROR: "WRITE_IO_ERROR";
+    /** 并发修改冲突 */
+    readonly CONCURRENT_MODIFIED: "CONCURRENT_MODIFIED";
+    /** 回滚失败 */
+    readonly ROLLBACK_FAILED: "ROLLBACK_FAILED";
+    /** 文件/路由/历史状态需要显式恢复后才能继续写入 */
+    readonly RECOVERY_REQUIRED: "RECOVERY_REQUIRED";
+    readonly RECOVERY_PERSIST_FAILED: "RECOVERY_PERSIST_FAILED";
+    /** 写请求缺少设计器会话上下文 */
+    readonly MUTATION_SESSION_REQUIRED: "MUTATION_SESSION_REQUIRED";
+    /** 租约断言格式、签名或验证器配置无效 */
+    readonly LEASE_ASSERTION_INVALID: "LEASE_ASSERTION_INVALID";
+    /** 租约断言已经过期 */
+    readonly LEASE_ASSERTION_EXPIRED: "LEASE_ASSERTION_EXPIRED";
+    /** 租约断言与当前写作用域不匹配 */
+    readonly LEASE_ASSERTION_SCOPE_MISMATCH: "LEASE_ASSERTION_SCOPE_MISMATCH";
+    /** 页面级移动试图跨 route */
+    readonly CROSS_PAGE_MOVE_UNSUPPORTED: "CROSS_PAGE_MOVE_UNSUPPORTED";
+    /** 内部错误 */
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+};
+export type OperationErrorCode = SiteEditOperationErrorCode;
+/**
+ * 操作错误 —— 附带错误码、消息和可选详情。
+ */
+export interface OperationError {
+    code: OperationErrorCode;
+    message: string;
+    details?: Record<string, unknown>;
+}

package/dist/internal/protocol/event.d.ts

@@ -0,0 +1,39 @@
+import type { OperationResult } from "./operation.js";
+import type { OperationError } from "./error.js";
+/**
+ * 设计器事件联合类型 —— engine 向 client 推送的所有事件。
+ *
+ * - document-changed: 文档树结构或内容发生变更
+ * - operation-completed: 操作执行成功
+ * - operation-failed: 操作执行失败
+ * - graph-invalidated: graph 需要重建（如文件变更）
+ * - graph-ready: graph 重建完成
+ * - graph-error: graph 重建失败，但保留最近一次成功结果
+ * - capability-changed: 部分节点的 capability 发生变化
+ */
+export type DesignerEvent = {
+    type: "document-changed";
+    routeId: string;
+    version: number;
+} | {
+    type: "operation-completed";
+    result: OperationResult;
+} | {
+    type: "operation-failed";
+    requestId: string;
+    error: OperationError;
+} | {
+    type: "graph-invalidated";
+    routeId: string;
+} | {
+    type: "graph-ready";
+    routeId: string;
+    version: number;
+} | {
+    type: "graph-error";
+    routeId: string;
+    message: string;
+} | {
+    type: "capability-changed";
+    keys: string[];
+};

package/dist/internal/protocol/identity.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 唯一身份标识，贯穿 DOM → protocol → engine → bridge 全链路。
+ *
+ * key 是唯一语义 key，由 file / component / structuralPath 确定性生成。
+ * 不得携带 SourceRange —— 那是 engine 内部实现细节。
+ */
+export interface SourceIdentity {
+    /** 源文件相对路径，如 "src/app/page.tsx" */
+    file: string;
+    /** 所属组件名，如 "HomePage" */
+    component: string;
+    /** 结构化路径，如 "div#0/span#1" */
+    structuralPath: string;
+    /** 唯一 key = "{file}::{component}::{structuralPath}" */
+    key: string;
+}
+/**
+ * 生成稳定的 SourceIdentity.key。
+ */
+export declare function computeSourceIdentityKey(file: string, component: string, structuralPath: string): string;
+/**
+ * 解析 SourceIdentity.key。
+ *
+ * structuralPath 允许包含分隔符，所以只切前两个段，余下部分全部并回 structuralPath。
+ */
+export declare function parseSourceIdentityKey(key: string): Pick<SourceIdentity, "file" | "component" | "structuralPath"> | null;

package/dist/internal/protocol/operation.d.ts

@@ -0,0 +1,77 @@
+import type { SiteEditInsertNodeSpec, SiteEditMoveTarget, SiteEditOperationParams, SiteEditOperationRequest, SiteEditOperationTarget, SiteEditOperationType, SiteEditOperationValue, SiteEditStyleBreakpoint, SiteEditStyleProperty, SiteEditStyleStateMode } from "@vcp-dev/contracts";
+import type { OperationError } from "./error.js";
+/** caller-facing 操作类型 */
+export type OperationType = SiteEditOperationType;
+export type OperationValue = SiteEditOperationValue;
+export type OperationTarget = SiteEditOperationTarget;
+export type StyleProperty = SiteEditStyleProperty;
+export type StyleStateMode = SiteEditStyleStateMode;
+export type StyleBreakpoint = SiteEditStyleBreakpoint;
+/**
+ * 操作请求 —— 由 client 发起，发送至 engine 执行。
+ */
+export type OperationRequest = SiteEditOperationRequest;
+/**
+ * 移动/插入目标位置。
+ *
+ * 支持四种 relation:
+ * - before / after: 以 anchorKey 为锚点的前后位置
+ * - prepend / append: 以 parentKey 为容器的首尾位置
+ *
+ * 关键：anchorKey / parentKey 可以跨组件、跨文件，
+ * 展开为多步 RewritePlan 是 engine/planner 的责任。
+ */
+export type MoveTarget = SiteEditMoveTarget;
+/**
+ * 可插入的 HTML 标签集合。
+ *
+ * 使用 string 联合 + 品牌扩展，允许任意合法 HTML 标签。
+ */
+export type InsertableTag = Extract<SiteEditInsertNodeSpec, {
+    kind: "native-tag";
+}>["tag"];
+/**
+ * 插入节点规格。
+ *
+ * 支持两种模式：
+ * - native-tag: 插入 HTML 原生标签（可带文本）
+ * - component-call: 插入组件调用（需要 source + exportName + optional props）
+ *
+ * 关键：不能退化成 native-tag-only，component-call 是正式能力。
+ */
+export type InsertNodeSpec = SiteEditInsertNodeSpec;
+/**
+ * 操作参数联合类型 —— 按 kind 区分。
+ *
+ * - update-text: 更新文本段落（segmentIndex + value）
+ * - remove-node: 移除节点（无额外参数）
+ * - insert-child: 插入子节点（node 规格 + position）
+ * - move-node: 移动节点（target 位置 + preserveBindings）
+ */
+export type OperationParams = SiteEditOperationParams;
+/**
+ * 操作结果 —— engine 执行完成后返回。
+ */
+export interface OperationSelectionRef {
+    key: string;
+    instanceIndex?: number;
+    instanceCount?: number;
+}
+export interface OperationResult {
+    /** 对应的请求 ID */
+    requestId: string;
+    /** 操作类型 */
+    kind: OperationType;
+    /** 操作目标 */
+    target: OperationTarget;
+    /** 是否成功 */
+    ok: boolean;
+    /** 操作后的 document version */
+    resultVersion: number;
+    /** 失败时的错误信息 */
+    error?: OperationError;
+    /** 本次操作实际影响的文件路径 */
+    affectedFiles?: string[];
+    /** 操作完成后建议恢复/选中的节点；move-node 会在 structural key 改变时返回新 key。 */
+    selectionRef?: OperationSelectionRef;
+}

package/dist/internal/protocol/render.d.ts

@@ -0,0 +1,203 @@
+import type { SiteEditClassNameSourceStyleContext, SiteEditPageComposition } from "@vcp-dev/contracts";
+import type { NodeCapabilitySnapshot } from "./capability.js";
+import type { BoundaryKind } from "./boundary.js";
+import type { OperationType } from "./operation.js";
+export type ExternalSourceKind = "api-field" | "cms-field" | "i18n-message" | "config-entry";
+export interface ExternalSourceView {
+    sourceType: ExternalSourceKind;
+    sourceId: string;
+    adapterId?: string;
+}
+/**
+ * 轻量级文档树 —— 一个路由对应一棵 RenderDocument。
+ * 由 engine 从 graph 投影而来，client 用于构建大纲 / 画布。
+ */
+export interface RenderDocument {
+    routeId: string;
+    version: number;
+    rootKeys: string[];
+    entries: RenderEntry[];
+    styleContext?: SiteEditClassNameSourceStyleContext;
+    pageComposition: SiteEditPageComposition;
+}
+/**
+ * 单个渲染条目 —— 描述一个节点在树中的位置与概要能力。
+ */
+export interface RenderEntry {
+    key: string;
+    tag: string;
+    label: string;
+    parentKey: string | null;
+    childKeys: string[];
+    pageCompositionUnitKey?: string;
+    operationSummary: OperationSummary;
+}
+/**
+ * 能力概要 —— 标记该节点支持的四个核心操作。
+ * 用于大纲 / 画布的快速渲染，详细约束见 NodeCapabilitySnapshot。
+ */
+export interface OperationSummary {
+    canUpdateText: boolean;
+    canInsertChild: boolean;
+    canMove: boolean;
+    canRemove: boolean;
+}
+/**
+ * 选中节点的详细信息 —— 按需加载。
+ * 包含完整 capability、text segments、boundary 信息、邻接关系。
+ */
+export interface RenderObjectDetail {
+    key: string;
+    tag: string;
+    componentName: string;
+    sourceFile: string;
+    sourceLocator?: SourceLocatorView;
+    label: string;
+    capabilities: NodeCapabilitySnapshot;
+    writeTarget: WriteTargetView;
+    effectiveWriteTarget?: EffectiveWriteTargetView;
+    provenanceChain?: ProvenanceChainView;
+    componentSemantic?: ComponentSemanticDescriptor;
+    contentModel?: ContentModelView;
+    mediaModel?: MediaModelView;
+    styleSource?: StyleSourceView;
+    conditional?: ConditionalDetailView;
+    textSegments: TextSegmentView[];
+    boundaryKind: BoundaryKind | null;
+    isOpaque: boolean;
+    ancestors: RenderEntryRef[];
+    children: RenderEntryRef[];
+    siblings: RenderEntryRef[];
+}
+export interface SourceLocatorRangeView {
+    startLine: number;
+    startColumn: number;
+    endLine: number;
+    endColumn: number;
+}
+export interface SourceLocatorView {
+    sourceFile: string;
+    componentName: string;
+    openingElementRange: SourceLocatorRangeView;
+    structuralPath: string;
+    textPreview?: string;
+}
+/**
+ * 写回目标视图 —— 描述该节点的语义写回落点。
+ */
+export interface WriteTargetView {
+    kind: "jsx-node" | "component-proxy" | "value-binding" | "route-export";
+    file: string;
+    componentName: string;
+    isProxy: boolean;
+}
+export interface EffectiveWriteTargetView {
+    kind: "jsx-node" | "value-path" | "route-export" | "external-entry";
+    file?: string;
+    isProxy: boolean;
+    displayPath?: string;
+    sourceType?: ExternalSourceKind;
+    sourceId?: string;
+}
+/**
+ * 文本段落视图 —— 表示一个可编辑 / 只读的文本片段。
+ */
+export interface TextSegmentView {
+    index: number;
+    value: string;
+    editable: boolean;
+    source: TextSourceView | null;
+}
+/**
+ * 文本来源视图 —— 描述文本片段来自字面量、绑定或模板。
+ */
+export interface TextSourceView {
+    kind: "literal" | "binding" | "imported-binding" | "repeat-template";
+    file: string;
+    expression: string;
+    bindingName?: string;
+    path?: Array<string | number>;
+}
+export interface ProvenanceChainView {
+    finalSource: SemanticSourceView | null;
+    chain: ProvenanceHopView[];
+    confidence: "exact" | "safe-derived" | "partial" | "unknown";
+    editMode: "direct" | "proxy" | "upstream" | "readonly" | "unsupported";
+    diagnostics: Array<{
+        code: string;
+        message: string;
+    }>;
+}
+export interface SemanticSourceView {
+    kind: "jsx-literal" | "component-prop" | "binding" | "imported-binding" | "object-field" | "array-item" | "repeat-template" | "conditional-branch" | ExternalSourceKind;
+    file: string;
+    displayPath: string;
+    externalSource?: ExternalSourceView;
+}
+export interface ProvenanceHopView {
+    kind: "jsx-literal" | "component-prop" | "binding" | "imported-binding" | "object-field" | "array-item" | "repeat-template" | "conditional-branch" | ExternalSourceKind;
+    file: string;
+    displayName: string;
+    canEditHere: boolean;
+}
+export interface ComponentSemanticDescriptor {
+    componentName: string;
+    instanceKey: string;
+    templateOwner?: string;
+    variantKeys?: string[];
+    slotKeys?: string[];
+    editableStrategy: "instance" | "template" | "upstream";
+    impactScope?: "current-instance" | "component-template" | "upstream-source";
+    alternativeStrategies?: Array<"instance" | "template" | "upstream">;
+}
+export type ContentModelOperation = never;
+export type MediaModelOperation = never;
+export type StyleSourceOperation = Extract<OperationType, "set-class-name-source" | "apply-style-draft">;
+export interface ModelDiagnosticView {
+    code: "unsupported-schema" | "unsupported-field";
+    field?: string;
+    message: string;
+}
+export interface ContentModelView {
+    kind: "markdown" | "rich-text-json";
+    field: string;
+    valuePath?: string;
+    schema?: string;
+    operationBoundary: ContentModelOperation[];
+    diagnostics?: ModelDiagnosticView[];
+}
+export interface MediaModelView {
+    kind: "image" | "video" | "media";
+    sourceType: "asset-id" | "cms-media-field" | "local-file-reference";
+    fields: string[];
+    editableFields: Array<"src" | "alt" | "poster" | "caption" | "width" | "height">;
+    operationBoundary: MediaModelOperation[];
+    valuePaths?: Record<string, string>;
+    diagnostics?: ModelDiagnosticView[];
+}
+export interface StyleSourceView {
+    kind: "class-name-source";
+    className: string;
+    sourceKind: "missing" | "static-attribute" | "static-expression" | "dynamic-expression";
+    editable: boolean;
+    operationBoundary: StyleSourceOperation[];
+    sourcePath?: string;
+    diagnostics?: Array<{
+        code: "missing-class-name" | "dynamic-binding" | "non-string-binding";
+        message: string;
+    }>;
+}
+export interface ConditionalDetailView {
+    currentBranch: "then" | "else";
+    availableBranches: Array<"then" | "else">;
+    conditionExpression: string;
+    provenance?: ProvenanceChainView;
+}
+/**
+ * 轻量级条目引用 —— 用于邻接关系列表。
+ */
+export interface RenderEntryRef {
+    key: string;
+    tag: string;
+    label: string;
+}

package/dist/internal/protocol.d.ts

@@ -0,0 +1,9 @@
+export { computeSourceIdentityKey, parseSourceIdentityKey, } from "./protocol/identity.js";
+export { OperationErrorCode } from "./protocol/error.js";
+export type { BoundaryKind } from "./protocol/boundary.js";
+export type { CapabilityConstraint, CapabilityModeView, ConstraintKind, NodeCapabilitySnapshot, } from "./protocol/capability.js";
+export type { DesignerEvent } from "./protocol/event.js";
+export type { OperationError } from "./protocol/error.js";
+export type { SourceIdentity } from "./protocol/identity.js";
+export type { InsertableTag, InsertNodeSpec, MoveTarget, OperationParams, OperationRequest, OperationResult, OperationSelectionRef, OperationTarget, OperationType, OperationValue, StyleBreakpoint, StyleProperty, StyleStateMode, } from "./protocol/operation.js";
+export type { ComponentSemanticDescriptor, ConditionalDetailView, ContentModelView, EffectiveWriteTargetView, MediaModelView, OperationSummary, ProvenanceChainView, ProvenanceHopView, RenderDocument, RenderEntry, RenderEntryRef, RenderObjectDetail, SemanticSourceView, SourceLocatorRangeView, SourceLocatorView, StyleSourceOperation, StyleSourceView, TextSegmentView, TextSourceView, WriteTargetView, } from "./protocol/render.js";

package/dist/materialization-style-policy.d.ts

@@ -0,0 +1,16 @@
+export type SiteEditColorMixPolicy = "always" | "raw-literal-only";
+export interface SiteEditThemeStyleScanOptions {
+    colorMixPolicy: SiteEditColorMixPolicy;
+    includeExtendedColorFunctions?: boolean;
+    includeRgbBackgroundImage?: boolean;
+    rejectAnyRawColorLiteral?: boolean;
+    rejectPrivateTokens?: boolean;
+    rejectTailwindPalette?: boolean;
+}
+export interface SiteEditThemeStyleViolations {
+    hardCodedSurfaceHits: string[];
+    rawColorHits: string[];
+    privateTokenHits: string[];
+}
+export declare const SITE_EDIT_RAW_COLOR_LITERAL_RE: RegExp;
+export declare function scanSiteEditThemeStyleViolations(content: string, options: SiteEditThemeStyleScanOptions): SiteEditThemeStyleViolations;