@trojanbox-vcp-test/site-edit-engine 0.1.0

package/dist/internal/capability/capability-resolver.js

@@ -0,0 +1,127 @@
+// ─── Capability Resolver ─────────────────────────────
+// 来源: docs/06-development-checklist.md §5
+//
+// 关键约束:
+//   canMove 不能被误算成 same-file only
+//   canInsertChild 不能被误算成 native-tag only
+//   repeat / boundary / opaque 限制必须显式通过 constraint 返回
+const VOID_ELEMENT_TAGS = new Set([
+    "area",
+    "base",
+    "br",
+    "col",
+    "embed",
+    "hr",
+    "img",
+    "input",
+    "link",
+    "meta",
+    "param",
+    "source",
+    "track",
+    "wbr",
+]);
+const CONTAINER_ELEMENT_TAGS = new Set([
+    "article",
+    "aside",
+    "div",
+    "footer",
+    "form",
+    "header",
+    "li",
+    "main",
+    "nav",
+    "ol",
+    "table",
+    "tbody",
+    "tfoot",
+    "thead",
+    "tr",
+    "select",
+    "section",
+    "ul",
+]);
+/**
+ * 为指定节点计算能力快照。
+ *
+ * 规则:
+ *   - canMove = true 意味着支持全部 MoveTarget 位置（含跨文件）
+ *   - canInsertChild = true 意味着支持 native-tag + component-call
+ *   - 限制通过 constraints 显式返回
+ */
+export function resolveCapability(key, topology, graph) {
+    const topologyNode = topology.nodes.get(key);
+    const element = graph.elements.get(key);
+    if (!topologyNode || !element) {
+        return {
+            key,
+            canUpdateText: false,
+            canInsertChild: false,
+            canMove: false,
+            canRemove: false,
+            constraints: [
+                { kind: "opaque-region", message: "Node not found in graph" },
+            ],
+        };
+    }
+    // Collect constraints from topology
+    const constraints = topologyNode.constraints.map((c) => ({
+        kind: c.kind,
+        message: c.reason,
+    }));
+    // Determine capabilities based on element properties and constraints
+    const isOpaque = element.isOpaque;
+    const isRoot = topologyNode.parentKey === null;
+    const isRouteComponentRoot = isRoot && element.componentName === "Page";
+    const tagName = element.tag.toLowerCase();
+    const isComponentElement = element.tag !== tagName;
+    const isVoidElement = !isComponentElement && VOID_ELEMENT_TAGS.has(tagName);
+    const isContainerElement = isComponentElement || CONTAINER_ELEMENT_TAGS.has(tagName);
+    const isComponentSlotContainer = isComponentElement && element.childKeys.length > 0;
+    const hasText = element.textSegments.length > 0 &&
+        element.textSegments.some((s) => s.editable);
+    if (isVoidElement &&
+        !constraints.some((constraint) => constraint.kind === "void-element")) {
+        constraints.push({
+            kind: "void-element",
+            message: `Element '${element.tag}' is void: children cannot be inserted`,
+        });
+    }
+    if (!isVoidElement &&
+        !isContainerElement &&
+        !constraints.some((constraint) => constraint.kind === "void-element")) {
+        constraints.push({
+            kind: "void-element",
+            message: `Element '${element.tag}' cannot contain structured children`,
+        });
+    }
+    // canUpdateText: has editable text segments and not opaque
+    const canUpdateText = hasText && !isOpaque;
+    // canInsertChild edits the call-site children for component slots; it does
+    // not imply access to the component implementation internals.
+    const canInsertChild = !isVoidElement &&
+        isContainerElement &&
+        (!isOpaque || isComponentSlotContainer);
+    // canMove: root nodes cannot be reparented, other nodes keep full move semantics
+    const canMove = !isRouteComponentRoot;
+    // canRemove: root nodes are structural entry points and cannot be removed
+    const canRemove = !isRouteComponentRoot;
+    return {
+        key,
+        canUpdateText,
+        canInsertChild,
+        canMove,
+        canRemove,
+        constraints,
+    };
+}
+/**
+ * 批量计算所有节点的能力快照。
+ */
+export function resolveAllCapabilities(topology, graph) {
+    const result = new Map();
+    for (const key of topology.nodes.keys()) {
+        result.set(key, resolveCapability(key, topology, graph));
+    }
+    return result;
+}

package/dist/internal/classname-source.d.ts

@@ -0,0 +1,24 @@
+import type { SiteEditClassNameSource, SiteEditClassNameSourceRange, SiteEditSetClassNameSourceRequest, SiteEditSetClassNameSourceResult } from "@trojanbox-vcp-test/contracts";
+import type { RenderSourceGraph } from "./graph/types.js";
+export declare const classNameSourceParserVersion = "site-edit-classname-source@1";
+export type ClassNameSourceRouteContext = {
+    routeId: string;
+    graph: RenderSourceGraph;
+    source: string;
+};
+export declare function extractClassNameSource(input: {
+    key: string;
+    route: ClassNameSourceRouteContext;
+}): SiteEditClassNameSource;
+export declare function applyClassNameSourceWrite(input: {
+    request: SiteEditSetClassNameSourceRequest;
+    current: SiteEditClassNameSource;
+    source: string;
+    writeSource: (nextSource: string) => Promise<void>;
+}): Promise<SiteEditSetClassNameSourceResult>;
+export declare function replaceClassNameAttributeSource(input: {
+    source: string;
+    oldAttrRange: SiteEditClassNameSourceRange | null;
+    openingElementRange: SiteEditClassNameSourceRange;
+    newAttrRaw: string | null;
+}): string;

package/dist/internal/classname-source.js

@@ -0,0 +1,220 @@
+import { resolveLocatorPath } from "./ast/locators/resolve-locator.js";
+import { detectParserProfile, parseWithProfile } from "./ast/parser/index.js";
+import { sha256ContentHash } from "../snapshot-file-system.js";
+export const classNameSourceParserVersion = "site-edit-classname-source@1";
+export function extractClassNameSource(input) {
+    const element = input.route.graph.elements.get(input.key);
+    if (!element) {
+        throw new Error(`Key not found: ${input.key}`);
+    }
+    const match = locateElementInSource(input.route.source, element);
+    const openingElement = match.openingElement;
+    const classNameAttr = openingElement.attributes.find((attribute) => attribute.type === "JSXAttribute" &&
+        attribute.name.type === "JSXIdentifier" &&
+        attribute.name.name === "className");
+    const base = {
+        key: input.key,
+        routeId: input.route.routeId,
+        filePath: element.sourceFile,
+        componentName: element.componentName,
+        openingElementRange: toContractRange(openingElement),
+        version: {
+            documentVersion: input.route.graph.version,
+            contentHash: sha256ContentHash(input.route.source),
+            parserVersion: classNameSourceParserVersion,
+        },
+    };
+    if (!classNameAttr) {
+        return {
+            ...base,
+            sourceKind: "missing",
+            attrRaw: null,
+            valueRaw: null,
+            attrRange: null,
+            valueRange: null,
+            diagnostics: [
+                {
+                    code: "missing-class-name",
+                    message: "No className attribute is present on this element.",
+                },
+            ],
+        };
+    }
+    const value = classNameAttr.value;
+    const sourceKind = value?.type === "StringLiteral" ? "stringLiteral" : "expression";
+    return {
+        ...base,
+        sourceKind,
+        attrRaw: sliceNode(input.route.source, classNameAttr),
+        valueRaw: value ? sliceNode(input.route.source, value) : null,
+        attrRange: toContractRange(classNameAttr),
+        valueRange: value ? toContractRange(value) : null,
+        diagnostics: [],
+    };
+}
+export async function applyClassNameSourceWrite(input) {
+    const { request, current, source } = input;
+    if (request.expectedVersion.documentVersion !== current.version.documentVersion) {
+        return failure("document_version_stale", current, {
+            code: "version-conflict",
+            message: "The document version changed before className save.",
+        });
+    }
+    if (request.expectedVersion.contentHash !== current.version.contentHash) {
+        return failure("file_hash_mismatch", current, {
+            code: "version-conflict",
+            message: "The source file changed before className save.",
+        });
+    }
+    if (!sameRange(request.openingElementRange, current.openingElementRange)) {
+        return failure("range_mismatch", current, {
+            code: "version-conflict",
+            message: "The target opening element range no longer matches.",
+        });
+    }
+    if (!sameNullableRange(request.oldAttrRange, current.attrRange)) {
+        return failure("range_mismatch", current, {
+            code: "version-conflict",
+            message: "The className attribute range no longer matches.",
+        });
+    }
+    if (request.oldAttrRaw !== current.attrRaw) {
+        return failure("old_attr_mismatch", current, {
+            code: "version-conflict",
+            message: "The className attribute changed before save.",
+        });
+    }
+    if (request.newAttrRaw !== null &&
+        !isValidClassNameAttribute(request.newAttrRaw)) {
+        return failure("invalid_new_attr", current, {
+            code: "invalid-new-attr",
+            message: "newAttrRaw must be a valid JSX className attribute.",
+        });
+    }
+    const nextSource = replaceClassNameAttributeSource({
+        source,
+        oldAttrRange: request.oldAttrRange,
+        openingElementRange: request.openingElementRange,
+        newAttrRaw: request.newAttrRaw,
+    });
+    try {
+        await input.writeSource(nextSource);
+    }
+    catch {
+        return failure("write_failed", current, {
+            code: "write-failed",
+            message: "Failed to write className source.",
+        });
+    }
+    return { ok: true, source: current };
+}
+export function replaceClassNameAttributeSource(input) {
+    const { source, oldAttrRange, openingElementRange, newAttrRaw } = input;
+    if (oldAttrRange) {
+        const start = oldAttrRange.start > 0 && /\s/.test(source[oldAttrRange.start - 1] ?? "")
+            ? oldAttrRange.start - 1
+            : oldAttrRange.start;
+        const replacement = newAttrRaw
+            ? `${start < oldAttrRange.start ? " " : ""}${newAttrRaw}`
+            : "";
+        return (source.slice(0, start) + replacement + source.slice(oldAttrRange.end));
+    }
+    if (!newAttrRaw) {
+        return source;
+    }
+    const openingEnd = openingElementRange.end;
+    const insertAt = source.slice(Math.max(0, openingEnd - 2), openingEnd) === "/>"
+        ? openingEnd - 2
+        : openingEnd - 1;
+    return source.slice(0, insertAt) + ` ${newAttrRaw}` + source.slice(insertAt);
+}
+function locateElementInSource(source, element) {
+    const parsed = parseWithProfile({
+        source,
+        profile: detectParserProfile({
+            filePath: element.sourceFile,
+            source,
+        }),
+    });
+    if (!parsed.ok) {
+        throw new Error(parsed.diagnostic.message);
+    }
+    const result = resolveLocatorPath(parsed.ast, {
+        kind: "jsx-node",
+        strategy: "structural-path",
+        file: element.identity.file,
+        component: element.identity.component,
+        structuralPath: element.identity.structuralPath,
+        expectedRange: toInternalRange(element.sourceRange),
+    });
+    if (!result.ok || result.match.node.type !== "JSXElement") {
+        throw new Error(`Unable to locate JSX element for key ${element.identity.key}`);
+    }
+    return result.match.node;
+}
+function isValidClassNameAttribute(attrRaw) {
+    const parsed = parseWithProfile({
+        source: `const __v = <div ${attrRaw} />;`,
+        profile: "tsx-module",
+    });
+    if (!parsed.ok) {
+        return false;
+    }
+    const statement = parsed.ast.program.body[0];
+    const declaration = statement?.type === "VariableDeclaration"
+        ? statement.declarations[0]
+        : null;
+    const init = declaration?.init;
+    if (init?.type !== "JSXElement") {
+        return false;
+    }
+    const attrs = init.openingElement.attributes;
+    return (attrs.length === 1 &&
+        attrs[0]?.type === "JSXAttribute" &&
+        attrs[0].name.type === "JSXIdentifier" &&
+        attrs[0].name.name === "className");
+}
+function failure(reason, current, diagnostic) {
+    return {
+        ok: false,
+        reason,
+        current,
+        diagnostics: [diagnostic],
+    };
+}
+function sliceNode(source, node) {
+    if (node.start == null || node.end == null) {
+        return "";
+    }
+    return source.slice(node.start, node.end);
+}
+function toContractRange(node) {
+    if (node.start == null || node.end == null) {
+        throw new Error("AST node does not include offsets.");
+    }
+    return {
+        start: node.start,
+        end: node.end,
+        startLine: node.loc?.start.line,
+        startColumn: node.loc?.start.column,
+        endLine: node.loc?.end.line,
+        endColumn: node.loc?.end.column,
+    };
+}
+function toInternalRange(range) {
+    return {
+        startLine: range.startLine,
+        startColumn: range.startColumn,
+        endLine: range.endLine,
+        endColumn: range.endColumn,
+    };
+}
+function sameNullableRange(left, right) {
+    if (left === null || right === null) {
+        return left === right;
+    }
+    return sameRange(left, right);
+}
+function sameRange(left, right) {
+    return left.start === right.start && left.end === right.end;
+}

package/dist/internal/contracts/IEditEngineRuntime.d.ts

@@ -0,0 +1,18 @@
+import type { SiteEditGetClassNameSourceResult, SiteEditObjectCapabilities, SiteEditSetClassNameSourceRequest, SiteEditSetClassNameSourceResult } from "@trojanbox-vcp-test/contracts";
+import type { DesignerEvent, OperationRequest, OperationResult, RenderDocument, RenderObjectDetail } from "../protocol.js";
+export interface IEditEngineRuntime {
+    readonly status: "idle" | "building" | "ready" | "error" | "disposed";
+    registerRoute(routeId: string, entryFile: string): void;
+    setActiveRoute(routeId: string): Promise<void>;
+    getDocument(routeId: string): RenderDocument;
+    getObjectCapabilities(key: string, routeId?: string): SiteEditObjectCapabilities;
+    getRenderDetail(key: string, routeId?: string): RenderObjectDetail;
+    getClassNameSource(key: string, routeId?: string): SiteEditGetClassNameSourceResult;
+    setClassNameSource(request: SiteEditSetClassNameSourceRequest): Promise<SiteEditSetClassNameSourceResult>;
+    execute(request: OperationRequest): Promise<OperationResult>;
+    undo(): Promise<OperationResult>;
+    redo(): Promise<OperationResult>;
+    notifyFileChanged(file: string): void;
+    subscribe(listener: (event: DesignerEvent) => void): () => void;
+    dispose(): void;
+}

package/dist/internal/contracts/IEditEngineRuntime.js

@@ -0,0 +1 @@
+export {};

package/dist/internal/domain/EditDiagnostic.d.ts

@@ -0,0 +1,38 @@
+/**
+ * EditDiagnostic - 结构化诊断信息创建工具。
+ *
+ * 提供统一的诊断对象创建函数，用于表示解析失败、定位失败、
+ * 不支持的语法等错误场景。
+ */
+export type EditDiagnosticCode = "parse-failed" | "locator-miss" | "unsupported-syntax" | "write-failed" | "printer-failed";
+export interface EditDiagnostic {
+    code: EditDiagnosticCode;
+    message: string;
+    details?: Record<string, unknown>;
+}
+export interface PrimitiveSuccessResult {
+    ok: true;
+    source: string;
+}
+export interface PrimitiveFailureResult {
+    ok: false;
+    source: string;
+    diagnostic: EditDiagnostic;
+}
+export type PrimitiveResult = PrimitiveSuccessResult | PrimitiveFailureResult;
+/**
+ * 创建诊断对象。
+ */
+export declare function createDiagnostic(code: EditDiagnosticCode, message: string, details?: Record<string, unknown>): EditDiagnostic;
+/**
+ * 创建 primitive 失败结果（返回原始 source + 诊断）。
+ */
+export declare function primitiveFailure(source: string, code: EditDiagnosticCode, message: string, details?: Record<string, unknown>): PrimitiveFailureResult;
+/**
+ * 创建定位失败结果。
+ */
+export declare function locatorFailure(source: string, message: string, details?: Record<string, unknown>): PrimitiveFailureResult;
+/**
+ * 创建解析失败结果。
+ */
+export declare function parseFailure(source: string, message: string): PrimitiveFailureResult;

package/dist/internal/domain/EditDiagnostic.js

@@ -0,0 +1,43 @@
+/**
+ * EditDiagnostic - 结构化诊断信息创建工具。
+ *
+ * 提供统一的诊断对象创建函数，用于表示解析失败、定位失败、
+ * 不支持的语法等错误场景。
+ */
+/**
+ * 创建诊断对象。
+ */
+export function createDiagnostic(code, message, details) {
+    return details === undefined
+        ? {
+            code,
+            message,
+        }
+        : {
+            code,
+            message,
+            details,
+        };
+}
+/**
+ * 创建 primitive 失败结果（返回原始 source + 诊断）。
+ */
+export function primitiveFailure(source, code, message, details) {
+    return {
+        ok: false,
+        source,
+        diagnostic: createDiagnostic(code, message, details),
+    };
+}
+/**
+ * 创建定位失败结果。
+ */
+export function locatorFailure(source, message, details) {
+    return primitiveFailure(source, "locator-miss", message, details);
+}
+/**
+ * 创建解析失败结果。
+ */
+export function parseFailure(source, message) {
+    return primitiveFailure(source, "parse-failed", message);
+}

package/dist/internal/events/event-bus.d.ts

@@ -0,0 +1,14 @@
+import type { DesignerEvent } from "../protocol.js";
+/**
+ * 事件总线 —— engine 内部事件分发。
+ */
+export interface EventBus {
+    /** 发射事件 */
+    emit(event: DesignerEvent): void;
+    /** 订阅事件，返回取消订阅函数 */
+    subscribe(listener: (event: DesignerEvent) => void): () => void;
+}
+/**
+ * 创建事件总线。
+ */
+export declare function createEventBus(): EventBus;

package/dist/internal/events/event-bus.js

@@ -0,0 +1,21 @@
+// ─── Event Bus ───────────────────────────────────────
+// 来源: docs/06-development-checklist.md §7
+/**
+ * 创建事件总线。
+ */
+export function createEventBus() {
+    const listeners = new Set();
+    return {
+        emit(event) {
+            for (const listener of listeners) {
+                listener(event);
+            }
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+}

package/dist/internal/graph/graph-builder.d.ts

@@ -0,0 +1,12 @@
+import type { RenderSourceGraph } from "./types.js";
+export declare function buildGraphFromSource(file: string, source: string): RenderSourceGraph;
+export declare function buildGraphWithLocalImportsFromSource(file: string, source: string): {
+    graph: RenderSourceGraph;
+    localImports: string[];
+};
+export { buildGraphFromSource as buildProjectSourceGraph };
+/**
+ * 从项目源图中提取单路由的渲染源图。
+ * 当前阶段直接返回单文件构建结果。
+ */
+export declare function extractRenderSourceGraph(graph: RenderSourceGraph, _routeId: string, _entryFile: string): RenderSourceGraph;