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

package/dist/internal/provenance/types.d.ts

@@ -0,0 +1,89 @@
+import type { ValueLocator, ValuePathSegment, ValueRootSelector } from "../ast/types.js";
+import type { NodePath } from "@babel/traverse";
+import type * as t from "@babel/types";
+import type { RenderSourceGraph } from "../graph/types.js";
+export type ExternalSourceKind = "api-field" | "cms-field" | "i18n-message" | "config-entry";
+export type ExternalAdapterCapability = "write-text" | "insert-child" | "remove-node" | "move-node";
+export interface ExternalSourceDescriptor {
+    sourceType: ExternalSourceKind;
+    sourceId: string;
+    adapterId?: string;
+}
+export interface ExternalAdapterRegistration {
+    sourceType: ExternalSourceKind;
+    adapterId?: string;
+    capabilities?: ExternalAdapterCapability[];
+}
+export interface ExternalSourceMatch {
+    sourceType: ExternalSourceKind;
+    sourceId: string;
+    file: string;
+    displayPath: string;
+    adapterId?: string;
+}
+export interface ExternalSourceResolverContext {
+    currentFile: string;
+    expressionPath: NodePath<t.Expression>;
+    readFile: (file: string) => Promise<string>;
+    exists: (file: string) => Promise<boolean>;
+    graph?: RenderSourceGraph;
+}
+export interface ExternalSourceResolution {
+    match: ExternalSourceMatch;
+    editMode?: "readonly";
+    diagnostics?: ProvenanceDiagnostic[];
+}
+export type ExternalSourceResolverResult = ExternalSourceMatch | ExternalSourceResolution;
+export interface ExternalSourceResolver {
+    helperNames?: string[];
+    resolve(params: ExternalSourceResolverContext): Promise<ExternalSourceResolverResult | null> | ExternalSourceResolverResult | null;
+}
+export interface FunctionCallContract {
+    helperName: string;
+    purity: "pure" | "side-effect";
+    sourceArgIndex?: number;
+}
+export type ResolvedTextWriteTarget = {
+    kind: "value-binding";
+    file: string;
+    locator: ValueLocator | null;
+    root?: ValueRootSelector;
+    path?: ValuePathSegment[];
+    displayExpression: string;
+    sourceKind: "literal" | "binding" | "imported-binding" | "repeat-template";
+    collectionIndexMap?: number[];
+    collectionPathMap?: ValuePathSegment[][];
+} | {
+    kind: "external-entry";
+    file: string;
+    sourceType: ExternalSourceKind;
+    sourceId: string;
+    adapterId?: string;
+    displayExpression: string;
+};
+export interface SemanticSource {
+    kind: "jsx-literal" | "component-prop" | "binding" | "imported-binding" | "object-field" | "array-item" | "repeat-template" | "conditional-branch" | ExternalSourceKind;
+    file: string;
+    locator: ValueLocator | null;
+    root?: ValueRootSelector;
+    path?: ValuePathSegment[];
+    displayPath: string;
+    externalSource?: ExternalSourceDescriptor;
+}
+export interface ProvenanceHop {
+    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 ProvenanceDiagnostic {
+    code: "unsupported-expression" | "dynamic-key" | "conditional-branch-unresolved" | "component-prop-unresolved" | "ambiguous-prop-binding" | "external-source-readonly" | "missing-adapter";
+    message: string;
+}
+export interface ProvenanceResolution {
+    finalSource: SemanticSource | null;
+    chain: ProvenanceHop[];
+    confidence: "exact" | "safe-derived" | "partial" | "unknown";
+    editMode: "direct" | "proxy" | "upstream" | "readonly" | "unsupported";
+    diagnostics: ProvenanceDiagnostic[];
+}

package/dist/internal/provenance/types.js

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

package/dist/internal/render/component-semantic.d.ts

@@ -0,0 +1,11 @@
+import type { ComponentSemanticDescriptor } from "../protocol.js";
+import type { ElementNode, RenderSourceGraph } from "../graph/types.js";
+import type { ProvenanceResolution } from "./provenance-types.js";
+interface BuildComponentSemanticDescriptorParams {
+    key: string;
+    element: ElementNode;
+    graph: RenderSourceGraph;
+    provenances: Map<number, ProvenanceResolution | null>;
+}
+export declare function buildComponentSemanticDescriptor(params: BuildComponentSemanticDescriptorParams): ComponentSemanticDescriptor;
+export {};

package/dist/internal/render/component-semantic.js

@@ -0,0 +1,141 @@
+export function buildComponentSemanticDescriptor(params) {
+    const { key, element, graph, provenances } = params;
+    const instanceElement = resolveInstanceElement(key, element, graph);
+    const componentName = instanceElement?.tag ??
+        (isComponentTag(element.tag) ? element.tag : element.componentName);
+    const instanceKey = instanceElement?.identity.key ??
+        resolveComponentCallerKey(element, graph) ??
+        key;
+    const variantKeys = resolveVariantKeys(instanceElement);
+    const slotKeys = resolveSlotKeys(key, element, graph, provenances, instanceElement);
+    const editableStrategy = resolveEditableStrategy(key, element, graph, provenances, instanceKey);
+    return {
+        componentName,
+        instanceKey,
+        templateOwner: resolveTemplateOwner(instanceElement ?? element, componentName),
+        ...(variantKeys.length > 0 ? { variantKeys } : {}),
+        ...(slotKeys.length > 0 ? { slotKeys } : {}),
+        editableStrategy,
+        impactScope: resolveImpactScope(editableStrategy),
+        alternativeStrategies: resolveAlternativeStrategies(editableStrategy),
+    };
+}
+function resolveEditableStrategy(key, element, graph, provenances, instanceKey) {
+    for (const provenance of provenances.values()) {
+        if (provenance?.editMode === "upstream") {
+            return "upstream";
+        }
+    }
+    if (findNearestComponentAncestor(key, graph)) {
+        return "instance";
+    }
+    if (!isComponentTag(element.tag) &&
+        element.sourceFile !== graph.routeId &&
+        instanceKey !== key) {
+        return "template";
+    }
+    return "instance";
+}
+function resolveComponentCallerKey(element, graph) {
+    if (isComponentTag(element.tag)) {
+        return element.identity.key;
+    }
+    const callers = [...graph.elements.values()].filter((candidate) => candidate.importedFrom === element.sourceFile &&
+        matchesComponentExport(candidate, element.componentName));
+    if (callers.length !== 1) {
+        return null;
+    }
+    return callers[0].identity.key;
+}
+function resolveInstanceElement(key, element, graph) {
+    if (isComponentTag(element.tag)) {
+        return element;
+    }
+    const parentComponent = findNearestComponentAncestor(key, graph);
+    if (parentComponent) {
+        return parentComponent;
+    }
+    const callerKey = resolveComponentCallerKey(element, graph);
+    return callerKey ? (graph.elements.get(callerKey) ?? null) : null;
+}
+function matchesComponentExport(candidate, componentName) {
+    return (candidate.exportName === componentName ||
+        candidate.tag === componentName ||
+        candidate.exportName === "default");
+}
+function resolveTemplateOwner(element, componentName) {
+    if (isComponentTag(element.tag) && element.importedFrom) {
+        return `${element.importedFrom}#${componentName}`;
+    }
+    return `${element.sourceFile}#${componentName}`;
+}
+function resolveVariantKeys(instanceElement) {
+    if (!instanceElement?.attributes) {
+        return [];
+    }
+    const variantNames = new Set(["variant", "size", "tone"]);
+    return instanceElement.attributes
+        .filter((attribute) => variantNames.has(attribute.name))
+        .map((attribute) => attribute.name);
+}
+function resolveSlotKeys(key, element, graph, provenances, instanceElement) {
+    const slotKeys = new Set();
+    const parentComponent = findNearestComponentAncestor(key, graph);
+    if (parentComponent &&
+        instanceElement?.identity.key === parentComponent.identity.key) {
+        slotKeys.add("children");
+    }
+    for (const provenance of provenances.values()) {
+        const propHop = provenance?.chain.find((hop) => hop.kind === "component-prop");
+        if (!propHop) {
+            continue;
+        }
+        const propName = propHop.displayName.split(".").pop();
+        if (propName) {
+            slotKeys.add(propName);
+        }
+    }
+    if (slotKeys.size === 0 &&
+        isComponentTag(element.tag) &&
+        element.childKeys.length > 0) {
+        slotKeys.add("children");
+    }
+    return [...slotKeys];
+}
+function findNearestComponentAncestor(key, graph) {
+    let currentKey = graph.elements.get(key)?.parentKey ?? null;
+    while (currentKey) {
+        const current = graph.elements.get(currentKey);
+        if (!current) {
+            break;
+        }
+        if (isComponentTag(current.tag)) {
+            return current;
+        }
+        currentKey = current.parentKey;
+    }
+    return null;
+}
+function isComponentTag(tag) {
+    return /^[A-Z]/.test(tag);
+}
+function resolveImpactScope(editableStrategy) {
+    switch (editableStrategy) {
+        case "template":
+            return "component-template";
+        case "upstream":
+            return "upstream-source";
+        default:
+            return "current-instance";
+    }
+}
+function resolveAlternativeStrategies(editableStrategy) {
+    switch (editableStrategy) {
+        case "template":
+            return ["instance"];
+        case "upstream":
+            return ["template"];
+        default:
+            return ["template"];
+    }
+}

package/dist/internal/render/content-model.d.ts

@@ -0,0 +1,3 @@
+import type { ContentModelView } from "../protocol.js";
+import type { ElementNode } from "../graph/types.js";
+export declare function buildContentModel(element: ElementNode): ContentModelView | undefined;

package/dist/internal/render/content-model.js

@@ -0,0 +1,89 @@
+const RICH_TEXT_FIELD_NAMES = new Set([
+    "markdown",
+    "body",
+    "content",
+    "value",
+    "document",
+]);
+const CONTENT_OPERATIONS = [
+    "replace-rich-text-content",
+    "insert-rich-text-block",
+    "remove-rich-text-block",
+];
+export function buildContentModel(element) {
+    if (!isComponentTag(element.tag) || !element.attributes) {
+        return undefined;
+    }
+    for (const attribute of element.attributes) {
+        if (!RICH_TEXT_FIELD_NAMES.has(attribute.name)) {
+            continue;
+        }
+        if (isMarkdownField(attribute)) {
+            return {
+                kind: "markdown",
+                field: attribute.name,
+                schema: "markdown",
+                valuePath: attribute.source?.expression,
+                operationBoundary: CONTENT_OPERATIONS,
+            };
+        }
+        const richTextSchema = detectRichTextSchema(attribute.resolvedValue);
+        if (richTextSchema === "prosemirror-doc" ||
+            richTextSchema === "node-array") {
+            return {
+                kind: "rich-text-json",
+                field: attribute.name,
+                valuePath: attribute.source?.expression,
+                schema: richTextSchema,
+                operationBoundary: CONTENT_OPERATIONS,
+            };
+        }
+        if (richTextSchema === "unsupported-json-tree") {
+            return {
+                kind: "rich-text-json",
+                field: attribute.name,
+                valuePath: attribute.source?.expression,
+                schema: "unsupported-json-tree",
+                operationBoundary: [],
+                diagnostics: [
+                    {
+                        code: "unsupported-schema",
+                        field: attribute.name,
+                        message: 'Only top-level node arrays and { type: "doc", content: [] } rich-text JSON are editable in stage D',
+                    },
+                ],
+            };
+        }
+    }
+    return undefined;
+}
+function detectRichTextSchema(value) {
+    if (!value) {
+        return undefined;
+    }
+    if (Array.isArray(value) && value.every((item) => isObjectRecord(item))) {
+        return "node-array";
+    }
+    if (!isObjectRecord(value)) {
+        return undefined;
+    }
+    if (value.type === "doc" && Array.isArray(value.content)) {
+        return "prosemirror-doc";
+    }
+    if (Array.isArray(value.content) || Array.isArray(value.children)) {
+        return "unsupported-json-tree";
+    }
+    return undefined;
+}
+function isObjectRecord(value) {
+    return !Array.isArray(value) && typeof value === "object" && value !== null;
+}
+function isMarkdownField(attribute) {
+    if (attribute.name === "markdown") {
+        return true;
+    }
+    return false;
+}
+function isComponentTag(tag) {
+    return /^[A-Z]/.test(tag);
+}

package/dist/internal/render/media-model.d.ts

@@ -0,0 +1,3 @@
+import type { MediaModelView } from "../protocol.js";
+import type { ElementNode } from "../graph/types.js";
+export declare function buildMediaModel(element: ElementNode): MediaModelView | undefined;

package/dist/internal/render/media-model.js

@@ -0,0 +1,45 @@
+const MEDIA_FIELDS = [
+    "src",
+    "alt",
+    "poster",
+    "caption",
+    "width",
+    "height",
+];
+export function buildMediaModel(element) {
+    const attributes = element.attributes?.filter((attribute) => MEDIA_FIELDS.includes(attribute.name)) ?? [];
+    if (attributes.length === 0) {
+        return undefined;
+    }
+    const fields = attributes.map((attribute) => attribute.name);
+    const valuePaths = Object.fromEntries(attributes
+        .filter((attribute) => attribute.source?.expression)
+        .map((attribute) => [attribute.name, attribute.source.expression]));
+    const sourceType = resolveMediaSourceType(attributes.map((attribute) => attribute.value));
+    return {
+        kind: resolveMediaKind(element.tag, fields),
+        sourceType,
+        fields,
+        editableFields: [...fields],
+        operationBoundary: ["set-media-field"],
+        ...(Object.keys(valuePaths).length > 0 ? { valuePaths } : {}),
+    };
+}
+function resolveMediaKind(tag, fields) {
+    if (tag === "img") {
+        return "image";
+    }
+    if (tag === "video" || fields.includes("poster")) {
+        return "video";
+    }
+    return "media";
+}
+function resolveMediaSourceType(values) {
+    if (values.some((value) => value.startsWith("cms:"))) {
+        return "cms-media-field";
+    }
+    if (values.some((value) => /^(\.?\/|\/)/.test(value))) {
+        return "local-file-reference";
+    }
+    return "asset-id";
+}

package/dist/internal/render/provenance-types.d.ts

@@ -0,0 +1,33 @@
+import type { ValueLocator, ValuePathSegment, ValueRootSelector } from "../ast/index.js";
+export type ExternalSourceKind = "api-field" | "cms-field" | "i18n-message" | "config-entry";
+export interface ExternalSourceDescriptor {
+    sourceType: ExternalSourceKind;
+    sourceId: string;
+    adapterId?: string;
+}
+export interface SemanticSource {
+    kind: "jsx-literal" | "component-prop" | "binding" | "imported-binding" | "object-field" | "array-item" | "repeat-template" | "conditional-branch" | ExternalSourceKind;
+    file: string;
+    locator: ValueLocator | null;
+    root?: ValueRootSelector;
+    path?: ValuePathSegment[];
+    displayPath: string;
+    externalSource?: ExternalSourceDescriptor;
+}
+export interface ProvenanceHop {
+    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 ProvenanceDiagnostic {
+    code: "unsupported-expression" | "dynamic-key" | "conditional-branch-unresolved" | "component-prop-unresolved" | "ambiguous-prop-binding" | "external-source-readonly" | "missing-adapter";
+    message: string;
+}
+export interface ProvenanceResolution {
+    finalSource: SemanticSource | null;
+    chain: ProvenanceHop[];
+    confidence: "exact" | "safe-derived" | "partial" | "unknown";
+    editMode: "direct" | "proxy" | "upstream" | "readonly" | "unsupported";
+    diagnostics: ProvenanceDiagnostic[];
+}

package/dist/internal/render/provenance-types.js

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

package/dist/internal/render/render-projection.d.ts

@@ -0,0 +1,24 @@
+import type { ComponentSemanticDescriptor, ContentModelView, MediaModelView, StyleModelView, StyleSourceView, ConditionalDetailView, RenderDocument, RenderObjectDetail, TextSourceView, WriteTargetView, NodeCapabilitySnapshot } from "../protocol.js";
+import type { RenderSourceGraph } from "../graph/types.js";
+import type { EditableTopology } from "../topology/types.js";
+import type { ProvenanceResolution } from "./provenance-types.js";
+/**
+ * 投影 RenderDocument —— 从 graph + topology + capabilities 构建。
+ */
+export declare function projectRenderDocument(graph: RenderSourceGraph, _topology: EditableTopology, capabilities: Map<string, NodeCapabilitySnapshot>, options?: {
+    canUpdateTextByKey?: ReadonlyMap<string, boolean>;
+}): RenderDocument;
+/**
+ * 投影 RenderObjectDetail —— 按需加载单个节点的详细信息。
+ */
+export declare function projectRenderObjectDetail(key: string, graph: RenderSourceGraph, topology: EditableTopology, capabilities: Map<string, NodeCapabilitySnapshot>, textSources: Map<number, TextSourceView | null>, writeTarget: WriteTargetView, provenances?: Map<number, ProvenanceResolution | null>, conditional?: ConditionalDetailView, componentSemantic?: ComponentSemanticDescriptor, contentModel?: ContentModelView, mediaModel?: MediaModelView, styleSource?: StyleSourceView, styleModel?: StyleModelView): RenderObjectDetail;
+export interface DetailTextSegmentProjection {
+    editable: boolean;
+    source: TextSourceView | null;
+}
+/**
+ * 选择 detail 的写回目标。
+ * 只有可编辑 segment 解析到 value target 时，才升级为 value-binding。
+ * 否则保持 jsx-node，并保留上游传入的 file / isProxy 元数据。
+ */
+export declare function projectDetailWriteTarget(topWriteTarget: WriteTargetView, segments: DetailTextSegmentProjection[]): WriteTargetView;