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

package/dist/internal/planner/planner.js

@@ -0,0 +1,2533 @@
+// ── OperationPlanner 骨架 ──────────────────────────────────────
+// 职责：把 OperationRequest 展开成 RewritePlan。
+// 根文档 03 §4 / 04 §4 定义：
+//   - planner 展开 MoveTarget / InsertNodeSpec 为可执行步骤
+//   - plan 阶段就解析好 locator / jsx / import 变更
+//   - cross-file move = remove + import + insert (+ remove-import)
+//   - component insert = import + insert
+import { resolveLocator, } from "../ast/index.js";
+import { resolveLocatorPath } from "../ast/locators/index.js";
+import * as parser from "@babel/parser";
+import _traverse from "@babel/traverse";
+import * as t from "@babel/types";
+import * as nodePath from "node:path";
+import { updateStylePropertyInClassName } from "../render/tailwind-style-model.js";
+import { evaluateCrossFileMovePolicy, evaluateInsertChildPolicy, } from "../provenance/capability-policy.js";
+const traverse = (typeof _traverse === "function" ? _traverse : _traverse.default);
+/* ------------------------------------------------------------------ */
+/*  Locator helpers                                                    */
+/* ------------------------------------------------------------------ */
+/**
+ * 创建 structural-path 定位器 — 对行号偏移（如 add-import 追加 import 行）
+ * 有更好的鲁棒性；source-range 作为提示（expectedRange）辅助验证。
+ */
+function makeLocator(node) {
+    if (node.structuralPath.includes("#repeat:") ||
+        node.isRepeatItemRoot ||
+        node.isRepeatRegion) {
+        return {
+            kind: "jsx-node",
+            strategy: "source-range",
+            sourceRange: node.sourceRange,
+        };
+    }
+    return {
+        kind: "jsx-node",
+        strategy: "structural-path",
+        file: node.file,
+        component: node.component,
+        structuralPath: node.structuralPath,
+    };
+}
+function makeAttributeLocator(node, name) {
+    return {
+        kind: "jsx-attribute",
+        element: makeLocator(node),
+        name,
+    };
+}
+function getNodeTargetKey(request) {
+    return request.target.kind === "node" ? request.target.key : null;
+}
+function getRouteTargetId(request) {
+    return request.target.kind === "route" ? request.target.routeId : null;
+}
+function computeRelativeSpecifier(fromFile, toFile) {
+    const fromDir = nodePath.dirname(fromFile);
+    const toFileNoExt = toFile.replace(/\.(tsx|ts|jsx|js)$/, "");
+    let rel = nodePath.relative(fromDir, toFileNoExt);
+    rel = rel.replace(/\\/g, "/");
+    if (!rel.startsWith("."))
+        rel = `./${rel}`;
+    return rel;
+}
+function findKnownDirective(source) {
+    const clientMatch = source.match(/^\s*['"]use client['"];?/m);
+    if (clientMatch) {
+        return "use client";
+    }
+    const serverMatch = source.match(/^\s*['"]use server['"];?/m);
+    if (serverMatch) {
+        return "use server";
+    }
+    return null;
+}
+function extractNodeJsx(graph, node) {
+    const source = graph.getFileContent(node.file);
+    if (!source) {
+        return undefined;
+    }
+    const match = resolveLocator(source, makeLocator(node));
+    if (!match.ok) {
+        return undefined;
+    }
+    return source.slice(match.match.start, match.match.end);
+}
+function resolveInsertComponentLocalName(node) {
+    if (node.component.exportName !== "default") {
+        return node.component.exportName;
+    }
+    const normalized = node.component.source
+        .replace(/\\/g, "/")
+        .replace(/\/$/, "");
+    const rawSegment = normalized.split("/").pop() || "Component";
+    const baseName = rawSegment === "index"
+        ? normalized.split("/").slice(-2, -1)[0] || "Component"
+        : rawSegment;
+    const sanitized = baseName.replace(/\.[^.]+$/, "");
+    const tokens = sanitized.split(/[^A-Za-z0-9]+/).filter(Boolean);
+    if (tokens.length === 0) {
+        return "Component";
+    }
+    return tokens
+        .map((token) => token.charAt(0).toUpperCase() + token.slice(1))
+        .join("");
+}
+function parseModuleSource(source) {
+    try {
+        return parser.parse(source, {
+            sourceType: "module",
+            plugins: ["jsx", "typescript"],
+        });
+    }
+    catch {
+        return null;
+    }
+}
+function getNodeRange(node) {
+    return typeof node.start === "number" && typeof node.end === "number"
+        ? { start: node.start, end: node.end }
+        : null;
+}
+function isNodeInsideRange(node, range) {
+    const nodeRange = getNodeRange(node);
+    return Boolean(nodeRange && nodeRange.start >= range.start && nodeRange.end <= range.end);
+}
+function getJsxTagBindingName(name) {
+    if (t.isJSXIdentifier(name)) {
+        return /^[A-Z]/.test(name.name) ? name.name : null;
+    }
+    if (t.isJSXMemberExpression(name)) {
+        let current = name;
+        while (t.isJSXMemberExpression(current)) {
+            current = current.object;
+        }
+        return current.name;
+    }
+    return null;
+}
+function collectEscapingBindingNames(sourcePath, targetScopePath) {
+    const sourceRange = getNodeRange(sourcePath.node);
+    if (!sourceRange) {
+        return [];
+    }
+    const escapingNames = new Set();
+    const checkBinding = (name, referencePath) => {
+        const binding = referencePath.scope.getBinding(name);
+        if (!binding || isNodeInsideRange(binding.path.node, sourceRange)) {
+            return;
+        }
+        const targetBinding = targetScopePath.scope.getBinding(name);
+        if (targetBinding !== binding) {
+            escapingNames.add(name);
+        }
+    };
+    sourcePath.traverse({
+        ReferencedIdentifier(path) {
+            checkBinding(path.node.name, path);
+        },
+        JSXOpeningElement(path) {
+            const tagBinding = getJsxTagBindingName(path.node.name);
+            if (tagBinding) {
+                checkBinding(tagBinding, path);
+            }
+        },
+    });
+    return [...escapingNames].sort();
+}
+function checkSameFileMovePreservesLexicalBindings(source, sourceNode, targetParent) {
+    const ast = parseModuleSource(source);
+    if (!ast) {
+        return { ok: true };
+    }
+    const sourceMatch = resolveLocatorPath(ast, makeLocator(sourceNode));
+    if (!sourceMatch.ok || !sourceMatch.match.path.isJSXElement()) {
+        return { ok: true };
+    }
+    const targetParentMatch = resolveLocatorPath(ast, makeLocator(targetParent));
+    if (!targetParentMatch.ok || !targetParentMatch.match.path.isJSXElement()) {
+        return { ok: true };
+    }
+    if (crossesConditionalBoundary(sourceMatch.match.path, targetParentMatch.match.path)) {
+        return {
+            ok: false,
+            bindingNames: [],
+            reason: "Cannot move node out of its conditional branch",
+        };
+    }
+    const bindingNames = collectEscapingBindingNames(sourceMatch.match.path, targetParentMatch.match.path);
+    return bindingNames.length > 0 ? { ok: false, bindingNames } : { ok: true };
+}
+function crossesConditionalBoundary(sourcePath, targetParentPath) {
+    const conditionalPath = sourcePath.findParent((path) => path.isConditionalExpression());
+    if (!conditionalPath?.isConditionalExpression()) {
+        return false;
+    }
+    return !targetParentPath.findParent((path) => path.node === conditionalPath.node);
+}
+const STRICT_NATIVE_CHILDREN = {
+    table: new Set(["caption", "colgroup", "thead", "tbody", "tfoot", "tr"]),
+    thead: new Set(["tr"]),
+    tbody: new Set(["tr"]),
+    tfoot: new Set(["tr"]),
+    tr: new Set(["th", "td"]),
+    ul: new Set(["li"]),
+    ol: new Set(["li"]),
+    select: new Set(["option", "optgroup"]),
+    optgroup: new Set(["option"]),
+};
+function validateNativeInsertNesting(parent, node) {
+    if (node.kind !== "native-tag") {
+        return null;
+    }
+    const parentTag = parent.tag?.toLowerCase();
+    if (!parentTag ||
+        parentTag !== parent.tag ||
+        parentTag.startsWith("component:")) {
+        return null;
+    }
+    const allowedChildren = STRICT_NATIVE_CHILDREN[parentTag];
+    if (!allowedChildren) {
+        return null;
+    }
+    const childTag = node.tag.toLowerCase();
+    return allowedChildren.has(childTag)
+        ? null
+        : `Cannot insert <${node.tag}> into <${parent.tag}>; expected ${[...allowedChildren].map((tag) => `<${tag}>`).join(", ")}`;
+}
+function findExistingDefaultImportLocal(ast, moduleSpecifier) {
+    for (const statement of ast.program.body) {
+        if (!t.isImportDeclaration(statement) ||
+            statement.source.value !== moduleSpecifier) {
+            continue;
+        }
+        const defaultImport = statement.specifiers.find((specifier) => t.isImportDefaultSpecifier(specifier));
+        if (defaultImport && t.isImportDefaultSpecifier(defaultImport)) {
+            return defaultImport.local.name;
+        }
+    }
+    return null;
+}
+function collectProgramBindingNames(ast) {
+    const names = new Set();
+    traverse(ast, {
+        Program(path) {
+            for (const bindingName of Object.keys(path.scope.bindings)) {
+                names.add(bindingName);
+            }
+            path.stop();
+        },
+    });
+    return names;
+}
+function chooseAvailableComponentLocalName(preferred, usedNames) {
+    if (!usedNames.has(preferred)) {
+        return preferred;
+    }
+    let suffix = 2;
+    while (usedNames.has(`${preferred}${suffix}`)) {
+        suffix += 1;
+    }
+    return `${preferred}${suffix}`;
+}
+function planComponentInsert(node, fileSource) {
+    const preferredLocalName = resolveInsertComponentLocalName(node);
+    if (node.component.exportName !== "default") {
+        return {
+            localName: preferredLocalName,
+            importStep: buildComponentImport(node, preferredLocalName),
+        };
+    }
+    const ast = parseModuleSource(fileSource);
+    if (!ast) {
+        return {
+            localName: preferredLocalName,
+            importStep: buildComponentImport(node, preferredLocalName),
+        };
+    }
+    const existingLocal = findExistingDefaultImportLocal(ast, node.component.source);
+    if (existingLocal) {
+        return { localName: existingLocal };
+    }
+    const localName = chooseAvailableComponentLocalName(preferredLocalName, collectProgramBindingNames(ast));
+    return {
+        localName,
+        importStep: buildComponentImport(node, localName),
+    };
+}
+function buildJsxFromSpec(node, componentLocalName) {
+    if (node.kind === "native-tag") {
+        return node.text
+            ? `<${node.tag}>${node.text}</${node.tag}>`
+            : `<${node.tag} />`;
+    }
+    const tag = componentLocalName ?? resolveInsertComponentLocalName(node);
+    if (node.props && Object.keys(node.props).length > 0) {
+        const propsStr = Object.entries(node.props)
+            .map(([key, value]) => typeof value === "string"
+            ? `${key}="${value}"`
+            : `${key}={${JSON.stringify(value)}}`)
+            .join(" ");
+        return `<${tag} ${propsStr} />`;
+    }
+    return `<${tag} />`;
+}
+function insertNodeSpecToOperationValue(node) {
+    if (node.kind === "native-tag") {
+        return node.text === undefined
+            ? { kind: node.kind, tag: node.tag }
+            : { kind: node.kind, tag: node.tag, text: node.text };
+    }
+    const props = node.props ? toOperationValueRecord(node.props) : undefined;
+    return {
+        kind: node.kind,
+        component: {
+            source: node.component.source,
+            exportName: node.component.exportName,
+        },
+        ...(props ? { props } : {}),
+    };
+}
+function toOperationValueRecord(value) {
+    return Object.fromEntries(Object.entries(value).filter((entry) => isOperationValue(entry[1])));
+}
+function isOperationValue(value) {
+    if (value === null ||
+        typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean") {
+        return true;
+    }
+    if (Array.isArray(value)) {
+        return value.every(isOperationValue);
+    }
+    if (typeof value === "object") {
+        return Object.values(value).every(isOperationValue);
+    }
+    return false;
+}
+function countJsxTagReferences(source, tag) {
+    const ast = parseModuleSource(source);
+    if (!ast) {
+        return Number.POSITIVE_INFINITY;
+    }
+    let count = 0;
+    traverse(ast, {
+        JSXOpeningElement(path) {
+            const name = path.node.name;
+            if (t.isJSXIdentifier(name) && name.name === tag) {
+                count += 1;
+            }
+        },
+    });
+    return count;
+}
+function buildComponentImport(node, localName = resolveInsertComponentLocalName(node)) {
+    return {
+        moduleSpecifier: node.component.source,
+        imports: node.component.exportName === "default"
+            ? [{ kind: "default", local: localName }]
+            : [{ kind: "named", imported: node.component.exportName }],
+    };
+}
+function resolveTargetRelation(target, graph) {
+    if ("parentKey" in target) {
+        return {
+            parentNode: graph.getNode(target.parentKey),
+            anchorNode: null,
+            placement: target.relation,
+        };
+    }
+    const anchorNode = graph.getNode(target.anchorKey);
+    const parentNode = anchorNode?.parentKey
+        ? (graph.getNode(anchorNode.parentKey) ?? anchorNode)
+        : anchorNode;
+    return {
+        parentNode,
+        anchorNode,
+        placement: target.relation,
+    };
+}
+function isSameOrDescendant(key, ancestorKey, graph) {
+    let currentKey = key;
+    while (currentKey) {
+        if (currentKey === ancestorKey) {
+            return true;
+        }
+        currentKey = graph.getNode(currentKey)?.parentKey;
+    }
+    return false;
+}
+function invalidParamsReason(expectedKind, actualKind) {
+    return `Operation kind '${expectedKind}' does not match params.kind '${actualKind}'`;
+}
+function cloneValueLocator(locator, path = locator.path) {
+    return {
+        kind: "value",
+        root: locator.root,
+        path: path && path.length > 0 ? path : undefined,
+        expectedRange: locator.expectedRange,
+    };
+}
+function getLastPathSegment(locator) {
+    const path = locator.path ?? [];
+    return path.length > 0 ? path[path.length - 1] : null;
+}
+function getParentObjectLocator(locator) {
+    const last = getLastPathSegment(locator);
+    if (!last || last.kind !== "property") {
+        return null;
+    }
+    return cloneValueLocator(locator, locator.path?.slice(0, -1));
+}
+function getNearestCollectionLocator(locator) {
+    const path = locator.path ?? [];
+    for (let i = path.length - 1; i >= 0; i -= 1) {
+        const segment = path[i];
+        if (segment.kind === "index") {
+            return {
+                locator: cloneValueLocator(locator, path.slice(0, i)),
+                index: segment.index,
+            };
+        }
+    }
+    return null;
+}
+function buildRepeatInsertValueFromLocator(locator, text) {
+    const path = locator.path ?? [];
+    const collectionIndex = path.findLastIndex((segment) => segment.kind === "index");
+    if (collectionIndex === -1) {
+        return undefined;
+    }
+    const itemPath = path.slice(collectionIndex + 1);
+    if (itemPath.length === 0) {
+        return text;
+    }
+    return buildObjectValueFromPath(itemPath, text);
+}
+function buildObjectValueFromPath(path, value) {
+    const [head, ...rest] = path;
+    if (!head) {
+        return value;
+    }
+    if (head.kind !== "property") {
+        return undefined;
+    }
+    const nested = buildObjectValueFromPath(rest, value);
+    return nested === undefined ? undefined : { [head.name]: nested };
+}
+function getUpstreamNodeEditReason(node, textTarget, provenance) {
+    const finalKind = provenance?.finalSource?.kind;
+    if (finalKind === "component-prop") {
+        return "Cannot edit prop-backed node structure with a generic node operation";
+    }
+    if (textTarget?.kind === "value-binding" &&
+        textTarget.sourceKind === "repeat-template" &&
+        !node.isRepeatItemRoot) {
+        return "Cannot edit repeat-backed child node structure with a generic node operation";
+    }
+    if (textTarget?.kind === "value-binding" &&
+        textTarget.file !== node.file &&
+        textTarget.sourceKind !== "repeat-template") {
+        return "Cannot edit upstream-bound node structure with a generic node operation";
+    }
+    return null;
+}
+function replaceNearestCollectionIndex(locator, index) {
+    const path = locator.path ?? [];
+    for (let i = path.length - 1; i >= 0; i -= 1) {
+        const segment = path[i];
+        if (segment.kind === "index") {
+            const nextPath = [...path];
+            nextPath[i] = { kind: "index", index };
+            return cloneValueLocator(locator, nextPath);
+        }
+    }
+    return null;
+}
+function mapCollectionItemIndex(index, indexMap) {
+    return indexMap?.[index] ?? index;
+}
+function mapCollectionInsertionIndex(index, indexMap) {
+    if (!indexMap || indexMap.length === 0) {
+        return index;
+    }
+    if (index <= 0) {
+        return indexMap[0] ?? 0;
+    }
+    if (index >= indexMap.length) {
+        return (indexMap[indexMap.length - 1] ?? indexMap.length - 1) + 1;
+    }
+    return indexMap[index] ?? index;
+}
+function sameValueLocator(left, right) {
+    return (sameValueRoot(left.root, right.root) &&
+        sameValuePath(left.path ?? [], right.path ?? []));
+}
+function sameValueRoot(left, right) {
+    if (left.kind !== right.kind) {
+        return false;
+    }
+    switch (left.kind) {
+        case "binding":
+        case "hook-state":
+        case "named-export":
+            return "name" in right && left.name === right.name;
+        case "default-export":
+            return true;
+        case "expression":
+            return ("sourceRange" in right &&
+                sameSourceRange(left.sourceRange, right.sourceRange));
+    }
+}
+function sameSourceRange(left, right) {
+    return (left.startLine === right.startLine &&
+        left.startColumn === right.startColumn &&
+        left.endLine === right.endLine &&
+        left.endColumn === right.endColumn);
+}
+function findJsxElementBySourceRange(ast, node) {
+    let found = null;
+    traverse(ast, {
+        JSXElement(path) {
+            const loc = path.node.loc;
+            if (!loc) {
+                return;
+            }
+            if (loc.start.line === node.sourceRange.startLine &&
+                loc.start.column === node.sourceRange.startColumn &&
+                loc.end.line === node.sourceRange.endLine &&
+                loc.end.column === node.sourceRange.endColumn) {
+                found = path;
+                path.stop();
+            }
+        },
+    });
+    return found;
+}
+function sameValuePath(left, right) {
+    if (left.length !== right.length) {
+        return false;
+    }
+    for (let index = 0; index < left.length; index += 1) {
+        const leftSegment = left[index];
+        const rightSegment = right[index];
+        if (leftSegment.kind !== rightSegment.kind) {
+            return false;
+        }
+        if (leftSegment.kind === "property") {
+            if (rightSegment.kind !== "property" ||
+                leftSegment.name !== rightSegment.name) {
+                return false;
+            }
+            continue;
+        }
+        if (rightSegment.kind !== "index" ||
+            leftSegment.index !== rightSegment.index) {
+            return false;
+        }
+    }
+    return true;
+}
+const MEDIA_FIELD_NAMES = new Set([
+    "src",
+    "alt",
+    "poster",
+    "caption",
+    "width",
+    "height",
+]);
+function resolveAttributeTarget(node, field) {
+    const attribute = node.attributes?.find((candidate) => candidate.name === field) ?? null;
+    const source = attribute?.source;
+    return {
+        attribute,
+        attributeLocator: makeAttributeLocator(node, field),
+        valueLocator: source &&
+            (attribute?.resolvedValue !== undefined ||
+                attribute.value !== source.expression)
+            ? {
+                kind: "value",
+                root: { kind: "binding", name: source.base },
+                path: source.path.length > 0 ? source.path : [],
+            }
+            : null,
+    };
+}
+function isPlainObjectRecord(value) {
+    return !Array.isArray(value) && typeof value === "object" && value !== null;
+}
+function detectContentSchema(value) {
+    if (typeof value === "string") {
+        return "markdown";
+    }
+    if (Array.isArray(value) &&
+        value.every((item) => isPlainObjectRecord(item))) {
+        return "node-array";
+    }
+    if (isPlainObjectRecord(value) &&
+        value.type === "doc" &&
+        Array.isArray(value.content)) {
+        return "prosemirror-doc";
+    }
+    return null;
+}
+function cloneOperationValue(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function splitMarkdownBlocks(markdown) {
+    return markdown === "" ? [] : markdown.split(/\n{2,}/);
+}
+function applyMarkdownBlockInsert(current, index, block) {
+    if (typeof block !== "string") {
+        return null;
+    }
+    const blocks = splitMarkdownBlocks(current);
+    if (index < 0 || index > blocks.length) {
+        return null;
+    }
+    blocks.splice(index, 0, block);
+    return blocks.join("\n\n");
+}
+function applyMarkdownBlockRemoval(current, index) {
+    const blocks = splitMarkdownBlocks(current);
+    if (index < 0 || index >= blocks.length) {
+        return null;
+    }
+    blocks.splice(index, 1);
+    return blocks.join("\n\n");
+}
+function applyMarkdownBlockMove(current, fromIndex, toIndex) {
+    const blocks = splitMarkdownBlocks(current);
+    if (fromIndex < 0 ||
+        fromIndex >= blocks.length ||
+        toIndex < 0 ||
+        toIndex >= blocks.length) {
+        return null;
+    }
+    const [block] = blocks.splice(fromIndex, 1);
+    blocks.splice(toIndex, 0, block);
+    return blocks.join("\n\n");
+}
+function applyRichTextBlockInsert(schema, current, index, block) {
+    if (!isPlainObjectRecord(block)) {
+        return null;
+    }
+    if (schema === "node-array") {
+        if (!Array.isArray(current)) {
+            return null;
+        }
+        const next = cloneOperationValue(current);
+        if (index < 0 || index > next.length) {
+            return null;
+        }
+        next.splice(index, 0, cloneOperationValue(block));
+        return next;
+    }
+    if (!isPlainObjectRecord(current) || !Array.isArray(current.content)) {
+        return null;
+    }
+    const next = cloneOperationValue(current);
+    if (!isPlainObjectRecord(next) || !Array.isArray(next.content)) {
+        return null;
+    }
+    if (index < 0 || index > next.content.length) {
+        return null;
+    }
+    next.content.splice(index, 0, cloneOperationValue(block));
+    return next;
+}
+function applyRichTextBlockRemoval(schema, current, index) {
+    if (schema === "node-array") {
+        if (!Array.isArray(current) || index < 0 || index >= current.length) {
+            return null;
+        }
+        const next = cloneOperationValue(current);
+        next.splice(index, 1);
+        return next;
+    }
+    if (!isPlainObjectRecord(current) ||
+        !Array.isArray(current.content) ||
+        index < 0 ||
+        index >= current.content.length) {
+        return null;
+    }
+    const next = cloneOperationValue(current);
+    if (!isPlainObjectRecord(next) || !Array.isArray(next.content)) {
+        return null;
+    }
+    next.content.splice(index, 1);
+    return next;
+}
+function applyRichTextBlockMove(schema, current, fromIndex, toIndex) {
+    const blocks = schema === "node-array"
+        ? Array.isArray(current)
+            ? cloneOperationValue(current)
+            : null
+        : isPlainObjectRecord(current) && Array.isArray(current.content)
+            ? cloneOperationValue(current.content)
+            : null;
+    if (!blocks ||
+        fromIndex < 0 ||
+        fromIndex >= blocks.length ||
+        toIndex < 0 ||
+        toIndex >= blocks.length) {
+        return null;
+    }
+    const [block] = blocks.splice(fromIndex, 1);
+    blocks.splice(toIndex, 0, block);
+    if (schema === "node-array") {
+        return blocks;
+    }
+    const next = cloneOperationValue(current);
+    next.content = blocks;
+    return next;
+}
+function getRichTextBlockCount(schema, current) {
+    if (schema === "markdown") {
+        return typeof current === "string"
+            ? splitMarkdownBlocks(current).length
+            : 0;
+    }
+    if (schema === "node-array") {
+        return Array.isArray(current) ? current.length : 0;
+    }
+    return isPlainObjectRecord(current) && Array.isArray(current.content)
+        ? current.content.length
+        : 0;
+}
+function getRichTextInsertionIndex(target, anchorNode, field, blockCount) {
+    if (target.relation === "prepend") {
+        return 0;
+    }
+    if (target.relation === "append") {
+        return blockCount;
+    }
+    if (!anchorNode?.richTextBlock || anchorNode.richTextBlock.field !== field) {
+        return null;
+    }
+    return target.relation === "before"
+        ? anchorNode.richTextBlock.index
+        : anchorNode.richTextBlock.index + 1;
+}
+function getRichTextMoveTargetIndex(target, resolved, source, blockCount) {
+    if (target.relation === "prepend") {
+        return 0;
+    }
+    if (target.relation === "append") {
+        return blockCount - 1;
+    }
+    const anchor = resolved.anchorNode?.richTextBlock;
+    if (!anchor || anchor.field !== source.field) {
+        return null;
+    }
+    return target.relation === "before"
+        ? anchor.index - (source.index < anchor.index ? 1 : 0)
+        : anchor.index + (source.index < anchor.index ? 0 : 1);
+}
+function getCurrentAttributeValue(attribute) {
+    if (attribute.resolvedValue !== undefined) {
+        return attribute.resolvedValue;
+    }
+    if (attribute.source && attribute.value === attribute.source.expression) {
+        return undefined;
+    }
+    return attribute.value;
+}
+function resolveEditableStyleClassTarget(node) {
+    const target = resolveAttributeTarget(node, "className");
+    if (!target.attribute) {
+        return {
+            ok: true,
+            target,
+            value: "",
+        };
+    }
+    if (target.attribute.source) {
+        return {
+            ok: false,
+            result: {
+                ok: false,
+                errorCode: "unsupported-operation",
+                reason: "Style editing requires a static className string",
+            },
+        };
+    }
+    const currentValue = getCurrentAttributeValue(target.attribute);
+    if (typeof currentValue !== "string") {
+        return {
+            ok: false,
+            result: {
+                ok: false,
+                errorCode: "unsupported-operation",
+                reason: target.attribute.source
+                    ? "Style binding must resolve to a static className string before it can be edited"
+                    : "Style editing currently only supports string-backed className values",
+            },
+        };
+    }
+    return {
+        ok: true,
+        target,
+        value: currentValue,
+    };
+}
+/* ------------------------------------------------------------------ */
+/*  OperationPlanner                                                  */
+/* ------------------------------------------------------------------ */
+let operationCounter = 0;
+export class OperationPlanner {
+    constructor(graph) {
+        this.graph = graph;
+    }
+    async plan(request) {
+        const operationId = `op-${++operationCounter}-${Date.now()}`;
+        switch (request.kind) {
+            case "update-text": {
+                if (request.params.kind !== "update-text") {
+                    return {
+                        ok: false,
+                        errorCode: "unknown",
+                        reason: invalidParamsReason(request.kind, request.params.kind),
+                    };
+                }
+                const typedRequest = request;
+                const resolvedNode = this.resolveNodeRequest(request);
+                if (!resolvedNode.ok) {
+                    return resolvedNode.result;
+                }
+                const targetNode = resolvedNode.node;
+                const currentVersion = this.graph.getFileVersion(targetNode.file);
+                if (request.documentVersion < currentVersion) {
+                    return {
+                        ok: false,
+                        errorCode: "stale-version",
+                        reason: `Document version ${request.documentVersion} is stale (current: ${currentVersion})`,
+                    };
+                }
+                return this.planUpdateText(operationId, typedRequest, targetNode, this.graph.getCapability(targetNode.key), await this.graph.getTextWriteTarget(targetNode.key, typedRequest.params.segmentIndex));
+            }
+            case "remove-node": {
+                if (request.params.kind !== "remove-node") {
+                    return {
+                        ok: false,
+                        errorCode: "unknown",
+                        reason: invalidParamsReason(request.kind, request.params.kind),
+                    };
+                }
+                const typedRequest = request;
+                const resolvedNode = this.resolveNodeRequest(request);
+                if (!resolvedNode.ok) {
+                    return resolvedNode.result;
+                }
+                const targetNode = resolvedNode.node;
+                const currentVersion = this.graph.getFileVersion(targetNode.file);
+                if (request.documentVersion < currentVersion) {
+                    return {
+                        ok: false,
+                        errorCode: "stale-version",
+                        reason: `Document version ${request.documentVersion} is stale (current: ${currentVersion})`,
+                    };
+                }
+                return this.planRemoveNode(operationId, typedRequest, targetNode, this.graph.getCapability(targetNode.key));
+            }
+            case "insert-child": {
+                if (request.params.kind !== "insert-child") {
+                    return {
+                        ok: false,
+                        errorCode: "unknown",
+                        reason: invalidParamsReason(request.kind, request.params.kind),
+                    };
+                }
+                const typedRequest = request;
+                const resolved = resolveTargetRelation(typedRequest.params.position, this.graph);
+                if (!resolved.parentNode) {
+                    return {
+                        ok: false,
+                        errorCode: "locator-miss",
+                        reason: `Insert target parent for request '${request.id}' not found in graph`,
+                    };
+                }
+                const currentVersion = this.graph.getFileVersion(resolved.parentNode.file);
+                if (request.documentVersion < currentVersion) {
+                    return {
+                        ok: false,
+                        errorCode: "stale-version",
+                        reason: `Document version ${request.documentVersion} is stale (current: ${currentVersion})`,
+                    };
+                }
+                return this.planInsertChild(operationId, typedRequest, resolved.parentNode, this.graph.getCapability(resolved.parentNode.key), resolved.anchorNode);
+            }
+            case "move-node": {
+                if (request.params.kind !== "move-node") {
+                    return {
+                        ok: false,
+                        errorCode: "unknown",
+                        reason: invalidParamsReason(request.kind, request.params.kind),
+                    };
+                }
+                const typedRequest = request;
+                const resolvedNode = this.resolveNodeRequest(request);
+                if (!resolvedNode.ok) {
+                    return resolvedNode.result;
+                }
+                const targetNode = resolvedNode.node;
+                const currentVersion = this.graph.getFileVersion(targetNode.file);
+                if (request.documentVersion < currentVersion) {
+                    return {
+                        ok: false,
+                        errorCode: "stale-version",
+                        reason: `Document version ${request.documentVersion} is stale (current: ${currentVersion})`,
+                    };
+                }
+                return this.planMoveNode(operationId, typedRequest, targetNode, this.graph.getCapability(targetNode.key));
+            }
+            case "replace-rich-text-content":
+            case "insert-rich-text-block":
+            case "remove-rich-text-block":
+            case "set-media-field": {
+                const resolvedNode = this.resolveNodeRequest(request);
+                if (!resolvedNode.ok) {
+                    return resolvedNode.result;
+                }
+                const targetNode = resolvedNode.node;
+                const currentVersion = this.graph.getFileVersion(targetNode.file);
+                if (request.documentVersion < currentVersion) {
+                    return {
+                        ok: false,
+                        errorCode: "stale-version",
+                        reason: `Document version ${request.documentVersion} is stale (current: ${currentVersion})`,
+                    };
+                }
+                switch (request.kind) {
+                    case "replace-rich-text-content":
+                        if (request.params.kind !== "replace-rich-text-content") {
+                            return {
+                                ok: false,
+                                errorCode: "unknown",
+                                reason: invalidParamsReason(request.kind, request.params.kind),
+                            };
+                        }
+                        return this.planRichTextOperation(operationId, request, targetNode);
+                    case "insert-rich-text-block":
+                        if (request.params.kind !== "insert-rich-text-block") {
+                            return {
+                                ok: false,
+                                errorCode: "unknown",
+                                reason: invalidParamsReason(request.kind, request.params.kind),
+                            };
+                        }
+                        return this.planRichTextOperation(operationId, request, targetNode);
+                    case "remove-rich-text-block":
+                        if (request.params.kind !== "remove-rich-text-block") {
+                            return {
+                                ok: false,
+                                errorCode: "unknown",
+                                reason: invalidParamsReason(request.kind, request.params.kind),
+                            };
+                        }
+                        return this.planRichTextOperation(operationId, request, targetNode);
+                    case "set-media-field":
+                        if (request.params.kind !== "set-media-field") {
+                            return {
+                                ok: false,
+                                errorCode: "unknown",
+                                reason: invalidParamsReason(request.kind, request.params.kind),
+                            };
+                        }
+                        return this.planMediaFieldOperation(operationId, request, targetNode);
+                }
+            }
+            case "set-component-slot-content": {
+                const resolvedNode = this.resolveNodeRequest(request);
+                if (!resolvedNode.ok) {
+                    return resolvedNode.result;
+                }
+                switch (request.kind) {
+                    case "set-component-slot-content":
+                        if (request.params.kind !== "set-component-slot-content") {
+                            return {
+                                ok: false,
+                                errorCode: "unknown",
+                                reason: invalidParamsReason(request.kind, request.params.kind),
+                            };
+                        }
+                        return this.planComponentSlotOperation(operationId, request, resolvedNode.node);
+                }
+            }
+            case "set-object-field":
+            case "insert-object-field":
+            case "remove-object-field":
+            case "update-array-item":
+            case "insert-array-item":
+            case "remove-array-item":
+            case "move-array-item": {
+                const resolvedNode = this.resolveNodeRequest(request);
+                if (!resolvedNode.ok) {
+                    return resolvedNode.result;
+                }
+                const targetNode = resolvedNode.node;
+                const currentVersion = this.graph.getFileVersion(targetNode.file);
+                if (request.documentVersion < currentVersion) {
+                    return {
+                        ok: false,
+                        errorCode: "stale-version",
+                        reason: `Document version ${request.documentVersion} is stale (current: ${currentVersion})`,
+                    };
+                }
+                return this.planValueCollectionOperation(operationId, request, targetNode);
+            }
+            case "replace-conditional-expression":
+            case "set-conditional-branch-content": {
+                const resolvedNode = this.resolveNodeRequest(request);
+                if (!resolvedNode.ok) {
+                    return resolvedNode.result;
+                }
+                const targetNode = resolvedNode.node;
+                const currentVersion = this.graph.getFileVersion(targetNode.file);
+                if (request.documentVersion < currentVersion) {
+                    return {
+                        ok: false,
+                        errorCode: "stale-version",
+                        reason: `Document version ${request.documentVersion} is stale (current: ${currentVersion})`,
+                    };
+                }
+                return this.planConditionalOperation(operationId, request, targetNode);
+            }
+            case "set-jsx-prop":
+            case "remove-jsx-prop":
+            case "set-class-name":
+            case "add-class-token":
+            case "remove-class-token":
+            case "set-style-property":
+            case "set-style-properties":
+            case "set-css-module-class": {
+                const resolvedNode = this.resolveNodeRequest(request);
+                if (!resolvedNode.ok) {
+                    return resolvedNode.result;
+                }
+                const currentVersion = this.graph.getFileVersion(resolvedNode.node.file);
+                if (request.documentVersion < currentVersion) {
+                    return {
+                        ok: false,
+                        errorCode: "stale-version",
+                        reason: `Document version ${request.documentVersion} is stale (current: ${currentVersion})`,
+                    };
+                }
+                return this.planNodeAttributeOperation(operationId, request, resolvedNode.node);
+            }
+            case "set-directive":
+            case "remove-directive":
+            case "set-route-export":
+            case "set-metadata-field":
+            case "set-generate-metadata": {
+                const resolvedRoute = this.resolveRouteRequest(request);
+                if (!resolvedRoute.ok) {
+                    return resolvedRoute.result;
+                }
+                const currentVersion = this.graph.getFileVersion(resolvedRoute.file);
+                if (request.documentVersion < currentVersion) {
+                    return {
+                        ok: false,
+                        errorCode: "stale-version",
+                        reason: `Document version ${request.documentVersion} is stale (current: ${currentVersion})`,
+                    };
+                }
+                return this.planRouteOperation(operationId, request, resolvedRoute.file);
+            }
+            default:
+                return {
+                    ok: false,
+                    errorCode: "unknown",
+                    reason: `Unknown operation kind: ${request.kind}`,
+                };
+        }
+    }
+    planConditionalOperation(operationId, request, node) {
+        const capability = this.graph.getCapability(node.key);
+        const locator = makeLocator(node);
+        switch (request.kind) {
+            case "replace-conditional-expression":
+                return this.buildPlan(operationId, request, [
+                    {
+                        order: 0,
+                        file: node.file,
+                        type: "replace-conditional-expression",
+                        locator,
+                        nextExpression: request.params.nextExpression,
+                    },
+                ], capability);
+            case "set-conditional-branch-content":
+                return this.buildPlan(operationId, request, [
+                    {
+                        order: 0,
+                        file: node.file,
+                        type: "set-conditional-branch-content",
+                        locator,
+                        branch: request.params.branch,
+                        content: request.params.content,
+                    },
+                ], capability);
+        }
+    }
+    planRichTextOperation(operationId, request, node) {
+        const capability = this.graph.getCapability(node.key);
+        const target = resolveAttributeTarget(node, request.params.field);
+        if (!target.attribute) {
+            return {
+                ok: false,
+                errorCode: "invalid-params",
+                reason: `Rich text field '${request.params.field}' was not found on the target node`,
+            };
+        }
+        const currentValue = getCurrentAttributeValue(target.attribute);
+        const schema = detectContentSchema(currentValue);
+        if (!schema) {
+            return {
+                ok: false,
+                errorCode: "unsupported-operation",
+                reason: `Rich text field '${request.params.field}' is only editable for markdown strings, top-level node arrays, or { type: 'doc', content: [] } documents`,
+            };
+        }
+        let nextValue = null;
+        switch (request.kind) {
+            case "replace-rich-text-content":
+                if (schema === "markdown" && typeof request.params.value !== "string") {
+                    return {
+                        ok: false,
+                        errorCode: "invalid-params",
+                        reason: "Markdown rich text replacement requires a string value",
+                    };
+                }
+                if (schema !== "markdown" &&
+                    detectContentSchema(request.params.value) !== schema) {
+                    return {
+                        ok: false,
+                        errorCode: "invalid-params",
+                        reason: `Rich text replacement must preserve the '${schema}' schema`,
+                    };
+                }
+                nextValue = request.params.value;
+                break;
+            case "insert-rich-text-block":
+                nextValue =
+                    schema === "markdown"
+                        ? applyMarkdownBlockInsert(currentValue, request.params.index, request.params.block)
+                        : applyRichTextBlockInsert(schema, currentValue, request.params.index, request.params.block);
+                if (nextValue === null) {
+                    return {
+                        ok: false,
+                        errorCode: "invalid-params",
+                        reason: schema === "markdown"
+                            ? "Markdown insert-rich-text-block requires a string block and an in-range block index"
+                            : "Rich text insert-rich-text-block requires a supported block payload and an in-range block index",
+                    };
+                }
+                break;
+            case "remove-rich-text-block":
+                nextValue =
+                    schema === "markdown"
+                        ? applyMarkdownBlockRemoval(currentValue, request.params.index)
+                        : applyRichTextBlockRemoval(schema, currentValue, request.params.index);
+                if (nextValue === null) {
+                    return {
+                        ok: false,
+                        errorCode: "invalid-params",
+                        reason: "remove-rich-text-block requires an in-range block index",
+                    };
+                }
+                break;
+        }
+        return this.buildPlan(operationId, request, [this.buildAttributeRewriteStep(node, target, nextValue)], capability);
+    }
+    planRichTextBlockInsert(operationId, request, node, capability, anchorNode) {
+        const contentModel = node.contentModel;
+        if (!contentModel?.operationBoundary.includes("insert-rich-text-block") ||
+            request.params.node.kind !== "native-tag" ||
+            request.params.node.text === undefined) {
+            return null;
+        }
+        const target = resolveAttributeTarget(node, contentModel.field);
+        if (!target.attribute) {
+            return null;
+        }
+        const currentValue = getCurrentAttributeValue(target.attribute);
+        const schema = detectContentSchema(currentValue);
+        if (!schema) {
+            return null;
+        }
+        const block = schema === "markdown"
+            ? request.params.node.text
+            : { type: "paragraph", text: request.params.node.text };
+        const blockCount = getRichTextBlockCount(schema, currentValue);
+        const insertionIndex = getRichTextInsertionIndex(request.params.position, anchorNode, contentModel.field, blockCount);
+        if (insertionIndex === null) {
+            return null;
+        }
+        const nextValue = schema === "markdown"
+            ? applyMarkdownBlockInsert(currentValue, insertionIndex, block)
+            : applyRichTextBlockInsert(schema, currentValue, insertionIndex, block);
+        if (nextValue === null) {
+            return {
+                ok: false,
+                errorCode: "invalid-params",
+                reason: "insert-child could not insert into the rich text field",
+            };
+        }
+        return this.buildPlan(operationId, request, [this.buildAttributeRewriteStep(node, target, nextValue)], capability);
+    }
+    planRichTextBlockRemoval(operationId, request, node, capability) {
+        const block = node.richTextBlock;
+        if (!block) {
+            return {
+                ok: false,
+                errorCode: "invalid-target",
+                reason: "remove-node target is not a rich text block",
+            };
+        }
+        const target = resolveAttributeTarget(node, block.field);
+        if (!target.attribute) {
+            return {
+                ok: false,
+                errorCode: "invalid-params",
+                reason: `Rich text field '${block.field}' was not found on the target node`,
+            };
+        }
+        const currentValue = getCurrentAttributeValue(target.attribute);
+        const schema = detectContentSchema(currentValue);
+        if (!schema) {
+            return {
+                ok: false,
+                errorCode: "unsupported-operation",
+                reason: `Rich text field '${block.field}' is not editable`,
+            };
+        }
+        const nextValue = schema === "markdown"
+            ? applyMarkdownBlockRemoval(currentValue, block.index)
+            : applyRichTextBlockRemoval(schema, currentValue, block.index);
+        if (nextValue === null) {
+            return {
+                ok: false,
+                errorCode: "invalid-params",
+                reason: "remove-node requires an in-range rich text block index",
+            };
+        }
+        return this.buildPlan(operationId, request, [this.buildAttributeRewriteStep(node, target, nextValue)], capability);
+    }
+    planRichTextBlockMove(operationId, request, node, capability, resolved) {
+        const block = node.richTextBlock;
+        if (!block) {
+            return {
+                ok: false,
+                errorCode: "invalid-target",
+                reason: "move-node target is not a rich text block",
+            };
+        }
+        const target = resolveAttributeTarget(node, block.field);
+        if (!target.attribute) {
+            return {
+                ok: false,
+                errorCode: "invalid-params",
+                reason: `Rich text field '${block.field}' was not found on the target node`,
+            };
+        }
+        const currentValue = getCurrentAttributeValue(target.attribute);
+        const schema = detectContentSchema(currentValue);
+        if (!schema) {
+            return {
+                ok: false,
+                errorCode: "unsupported-operation",
+                reason: `Rich text field '${block.field}' is not editable`,
+            };
+        }
+        const toIndex = getRichTextMoveTargetIndex(request.params.target, resolved, block, getRichTextBlockCount(schema, currentValue));
+        if (toIndex === null) {
+            return {
+                ok: false,
+                errorCode: "unsupported-operation",
+                reason: "move-node requires a target in the same rich text field",
+            };
+        }
+        const nextValue = schema === "markdown"
+            ? applyMarkdownBlockMove(currentValue, block.index, toIndex)
+            : applyRichTextBlockMove(schema, currentValue, block.index, toIndex);
+        if (nextValue === null) {
+            return {
+                ok: false,
+                errorCode: "invalid-params",
+                reason: "move-node requires in-range rich text block indexes",
+            };
+        }
+        return this.buildPlan(operationId, request, [this.buildAttributeRewriteStep(node, target, nextValue)], capability);
+    }
+    planMediaFieldOperation(operationId, request, node) {
+        const capability = this.graph.getCapability(node.key);
+        if (!MEDIA_FIELD_NAMES.has(request.params.field)) {
+            return {
+                ok: false,
+                errorCode: "unsupported-operation",
+                reason: `Media field '${request.params.field}' is not supported`,
+            };
+        }
+        const target = resolveAttributeTarget(node, request.params.field);
+        return this.buildPlan(operationId, request, [this.buildAttributeRewriteStep(node, target, request.params.value)], capability);
+    }
+    buildAttributeRewriteStep(node, target, value) {
+        if (target.valueLocator) {
+            return {
+                order: 0,
+                file: node.file,
+                type: "update-value",
+                locator: target.valueLocator,
+                value,
+            };
+        }
+        return {
+            order: 0,
+            file: node.file,
+            type: "set-jsx-prop",
+            locator: target.attributeLocator,
+            value,
+        };
+    }
+    async planComponentSlotOperation(operationId, request, node) {
+        const semantic = this.graph.getComponentSemantic(node.key);
+        const slotKeys = semantic?.slotKeys ?? [];
+        if (!slotKeys.includes(request.params.slotName)) {
+            return {
+                ok: false,
+                errorCode: "unsupported-operation",
+                reason: `Slot '${request.params.slotName}' is not declared for this component`,
+            };
+        }
+        const capability = this.graph.getCapability(node.key);
+        const segmentIndex = this.graph.getEditableTextSegmentIndex(node.key);
+        const textTarget = segmentIndex === null
+            ? null
+            : await this.graph.getTextWriteTarget(node.key, segmentIndex);
+        if (request.params.slotName === "children") {
+            if (!capability.canUpdateText || segmentIndex === null) {
+                return {
+                    ok: false,
+                    errorCode: "capability-denied",
+                    reason: "Children slot content requires an editable text segment",
+                };
+            }
+            const textValue = this.toTextContent(request.params.value);
+            if (textValue === null) {
+                return {
+                    ok: false,
+                    errorCode: "unsupported-operation",
+                    reason: "Children slot content currently only supports primitive text values",
+                };
+            }
+            const files = textTarget?.kind === "value-binding"
+                ? [node.file, textTarget.file]
+                : [node.file];
+            const stale = this.checkDocumentVersion(request.documentVersion, files);
+            if (stale) {
+                return stale;
+            }
+            return this.buildPlan(operationId, request, this.buildTextRewriteSteps(node, segmentIndex, textValue, textTarget), capability);
+        }
+        if (semantic?.editableStrategy === "upstream" &&
+            capability.canUpdateText &&
+            segmentIndex !== null) {
+            const textValue = this.toTextContent(request.params.value);
+            if (textValue === null) {
+                return {
+                    ok: false,
+                    errorCode: "unsupported-operation",
+                    reason: "Prop-backed slot content currently only supports primitive text values",
+                };
+            }
+            const files = textTarget?.kind === "value-binding"
+                ? [node.file, textTarget.file]
+                : [node.file];
+            const stale = this.checkDocumentVersion(request.documentVersion, files);
+            if (stale) {
+                return stale;
+            }
+            return this.buildPlan(operationId, request, this.buildTextRewriteSteps(node, segmentIndex, textValue, textTarget), capability);
+        }
+        const instanceNode = semantic?.instanceKey
+            ? this.graph.getNode(semantic.instanceKey)
+            : node;
+        if (!instanceNode) {
+            return {
+                ok: false,
+                errorCode: "locator-miss",
+                reason: "Component instance for semantic slot edit was not found",
+            };
+        }
+        const stale = this.checkDocumentVersion(request.documentVersion, [
+            node.file,
+            instanceNode.file,
+        ]);
+        if (stale) {
+            return stale;
+        }
+        return this.buildPlan(operationId, request, [
+            {
+                order: 0,
+                file: instanceNode.file,
+                type: "set-jsx-prop",
+                locator: makeAttributeLocator(instanceNode, request.params.slotName),
+                value: request.params.value,
+            },
+        ], capability);
+    }
+    async planValueCollectionOperation(operationId, request, node) {
+        const capability = this.graph.getCapability(node.key);
+        if (!capability.canUpdateText) {
+            return {
+                ok: false,
+                errorCode: "capability-denied",
+                reason: "Cannot update bound value on this node",
+            };
+        }
+        const valueTarget = await this.graph.getTextWriteTarget(node.key, request.params.segmentIndex);
+        if (!valueTarget ||
+            valueTarget.kind !== "value-binding" ||
+            !valueTarget.locator) {
+            return {
+                ok: false,
+                errorCode: "unsupported-operation",
+                reason: "Node does not resolve to a writable value path",
+            };
+        }
+        const locator = valueTarget.locator;
+        switch (request.kind) {
+            case "set-object-field": {
+                const last = getLastPathSegment(locator);
+                if (!last || last.kind !== "property") {
+                    return {
+                        ok: false,
+                        errorCode: "invalid-params",
+                        reason: "set-object-field requires an object-field value target",
+                    };
+                }
+                return this.buildPlan(operationId, request, [
+                    {
+                        order: 0,
+                        file: valueTarget.file,
+                        type: "set-object-field",
+                        locator,
+                        value: request.params.value,
+                    },
+                ], capability);
+            }
+            case "insert-object-field": {
+                const parentLocator = getParentObjectLocator(locator);
+                if (!parentLocator) {
+                    return {
+                        ok: false,
+                        errorCode: "invalid-params",
+                        reason: "insert-object-field requires an object-field value target",
+                    };
+                }
+                return this.buildPlan(operationId, request, [
+                    {
+                        order: 0,
+                        file: valueTarget.file,
+                        type: "insert-object-field",
+                        locator: parentLocator,
+                        field: request.params.field,
+                        value: request.params.value,
+                    },
+                ], capability);
+            }
+            case "remove-object-field": {
+                const last = getLastPathSegment(locator);
+                const field = request.params.field ??
+                    (last?.kind === "property" ? last.name : null);
+                const parentLocator = getParentObjectLocator(locator);
+                if (!field || !parentLocator) {
+                    return {
+                        ok: false,
+                        errorCode: "invalid-params",
+                        reason: "remove-object-field requires an object-field value target",
+                    };
+                }
+                return this.buildPlan(operationId, request, [
+                    {
+                        order: 0,
+                        file: valueTarget.file,
+                        type: "remove-object-field",
+                        locator: parentLocator,
+                        field,
+                    },
+                ], capability);
+            }
+            case "update-array-item": {
+                const collection = getNearestCollectionLocator(locator);
+                if (!collection) {
+                    return {
+                        ok: false,
+                        errorCode: "invalid-params",
+                        reason: "update-array-item requires an array-backed value target",
+                    };
+                }
+                const itemLocator = request.params.index === undefined
+                    ? locator
+                    : valueTarget.collectionPathMap?.[request.params.index]
+                        ? cloneValueLocator(locator, valueTarget.collectionPathMap[request.params.index])
+                        : replaceNearestCollectionIndex(locator, mapCollectionItemIndex(request.params.index, valueTarget.collectionIndexMap));
+                if (!itemLocator) {
+                    return {
+                        ok: false,
+                        errorCode: "invalid-params",
+                        reason: "update-array-item requires an array-backed value target",
+                    };
+                }
+                return this.buildPlan(operationId, request, [
+                    {
+                        order: 0,
+                        file: valueTarget.file,
+                        type: "update-array-item",
+                        locator: itemLocator,
+                        value: request.params.value,
+                    },
+                ], capability);
+            }
+            case "insert-array-item": {
+                const collection = getNearestCollectionLocator(locator);
+                if (!collection) {
+                    return {
+                        ok: false,
+                        errorCode: "invalid-params",
+                        reason: "insert-array-item requires an array-backed value target",
+                    };
+                }
+                return this.buildPlan(operationId, request, [
+                    {
+                        order: 0,
+                        file: valueTarget.file,
+                        type: "insert-array-item",
+                        locator: collection.locator,
+                        index: mapCollectionInsertionIndex(request.params.index, valueTarget.collectionIndexMap),
+                        value: request.params.value,
+                    },
+                ], capability);
+            }
+            case "remove-array-item": {
+                const collection = getNearestCollectionLocator(locator);
+                if (!collection) {
+                    return {
+                        ok: false,
+                        errorCode: "invalid-params",
+                        reason: "remove-array-item requires an array-backed value target",
+                    };
+                }
+                return this.buildPlan(operationId, request, [
+                    {
+                        order: 0,
+                        file: valueTarget.file,
+                        type: "remove-array-item",
+                        locator: collection.locator,
+                        index: request.params.index === undefined
+                            ? collection.index
+                            : mapCollectionItemIndex(request.params.index, valueTarget.collectionIndexMap),
+                    },
+                ], capability);
+            }
+            case "move-array-item": {
+                const collection = getNearestCollectionLocator(locator);
+                if (!collection) {
+                    return {
+                        ok: false,
+                        errorCode: "invalid-params",
+                        reason: "move-array-item requires an array-backed value target",
+                    };
+                }
+                return this.buildPlan(operationId, request, [
+                    {
+                        order: 0,
+                        file: valueTarget.file,
+                        type: "move-array-item",
+                        locator: collection.locator,
+                        fromIndex: request.params.fromIndex === undefined
+                            ? collection.index
+                            : mapCollectionItemIndex(request.params.fromIndex, valueTarget.collectionIndexMap),
+                        toIndex: mapCollectionInsertionIndex(request.params.toIndex, valueTarget.collectionIndexMap),
+                    },
+                ], capability);
+            }
+        }
+    }
+    resolveNodeRequest(request) {
+        const targetKey = getNodeTargetKey(request);
+        if (!targetKey) {
+            return {
+                ok: false,
+                result: {
+                    ok: false,
+                    errorCode: "invalid-target",
+                    reason: `Operation '${request.kind}' requires a node target`,
+                },
+            };
+        }
+        const node = this.graph.getNode(targetKey);
+        if (!node) {
+            return {
+                ok: false,
+                result: {
+                    ok: false,
+                    errorCode: "locator-miss",
+                    reason: `Target key '${targetKey}' not found in graph`,
+                },
+            };
+        }
+        return { ok: true, node };
+    }
+    resolveRouteRequest(request) {
+        const routeId = getRouteTargetId(request);
+        if (!routeId) {
+            return {
+                ok: false,
+                result: {
+                    ok: false,
+                    errorCode: "invalid-target",
+                    reason: `Operation '${request.kind}' requires a route target`,
+                },
+            };
+        }
+        const file = this.graph.getRouteEntryFile(routeId);
+        if (!file) {
+            return {
+                ok: false,
+                result: {
+                    ok: false,
+                    errorCode: "route-not-found",
+                    reason: `Route '${routeId}' is not registered`,
+                },
+            };
+        }
+        return { ok: true, file };
+    }
+    planNodeAttributeOperation(operationId, request, node) {
+        const file = node.file;
+        const capability = this.graph.getCapability(node.key);
+        switch (request.kind) {
+            case "set-jsx-prop":
+                return this.buildPlan(operationId, request, [
+                    {
+                        order: 0,
+                        file,
+                        type: "set-jsx-prop",
+                        locator: makeAttributeLocator(node, request.params.name),
+                        value: request.params.value,
+                    },
+                ], capability);
+            case "remove-jsx-prop":
+                return this.buildPlan(operationId, request, [
+                    {
+                        order: 0,
+                        file,
+                        type: "remove-jsx-prop",
+                        locator: makeAttributeLocator(node, request.params.name),
+                    },
+                ], capability);
+            case "set-class-name":
+                return this.buildPlan(operationId, request, [
+                    {
+                        order: 0,
+                        file,
+                        type: "set-class-name",
+                        locator: makeAttributeLocator(node, "className"),
+                        value: request.params.value,
+                    },
+                ], capability);
+            case "add-class-token":
+                return this.buildPlan(operationId, request, [
+                    {
+                        order: 0,
+                        file,
+                        type: "add-class-token",
+                        locator: makeAttributeLocator(node, "className"),
+                        token: request.params.token,
+                    },
+                ], capability);
+            case "remove-class-token":
+                return this.buildPlan(operationId, request, [
+                    {
+                        order: 0,
+                        file,
+                        type: "remove-class-token",
+                        locator: makeAttributeLocator(node, "className"),
+                        token: request.params.token,
+                    },
+                ], capability);
+            case "set-style-property":
+                return this.planStyleClassNameOperation(operationId, request, node, {
+                    [request.params.property]: request.params.value,
+                });
+            case "set-style-properties":
+                return this.planStyleClassNameOperation(operationId, request, node, request.params.properties);
+            case "set-css-module-class":
+                return this.buildPlan(operationId, request, [
+                    {
+                        order: 0,
+                        file,
+                        type: "set-css-module-class",
+                        locator: makeAttributeLocator(node, "className"),
+                        from: request.params.from,
+                        to: request.params.to,
+                    },
+                ], capability);
+        }
+    }
+    planStyleClassNameOperation(operationId, request, node, properties) {
+        const resolvedTarget = resolveEditableStyleClassTarget(node);
+        if (!resolvedTarget.ok) {
+            return resolvedTarget.result;
+        }
+        let nextClassName = resolvedTarget.value;
+        for (const [property, value] of Object.entries(properties)) {
+            const updated = updateStylePropertyInClassName(nextClassName, property, value);
+            if (updated === null) {
+                return {
+                    ok: false,
+                    errorCode: "invalid-params",
+                    reason: `CSS style property '${property}' received a value that cannot be mapped to Tailwind`,
+                };
+            }
+            nextClassName = updated;
+        }
+        return this.buildPlan(operationId, request, [
+            {
+                order: 0,
+                file: node.file,
+                type: "set-class-name",
+                locator: makeAttributeLocator(node, "className"),
+                value: nextClassName,
+            },
+        ], this.graph.getCapability(node.key));
+    }
+    planRouteOperation(operationId, request, file) {
+        const source = this.graph.getFileContent(file);
+        switch (request.kind) {
+            case "set-directive": {
+                const currentValue = findKnownDirective(source);
+                return this.buildPlan(operationId, request, [
+                    {
+                        order: 0,
+                        file,
+                        type: "set-directive",
+                        mode: currentValue ? "update" : "add",
+                        currentValue: currentValue ?? undefined,
+                        value: request.params.value,
+                    },
+                ]);
+            }
+            case "remove-directive":
+                return this.buildPlan(operationId, request, [
+                    {
+                        order: 0,
+                        file,
+                        type: "remove-directive",
+                        value: request.params.value,
+                    },
+                ]);
+            case "set-route-export":
+                return this.buildPlan(operationId, request, [
+                    {
+                        order: 0,
+                        file,
+                        type: "set-route-export",
+                        name: request.params.name,
+                        value: request.params.value,
+                    },
+                ]);
+            case "set-metadata-field":
+                return this.buildPlan(operationId, request, [
+                    {
+                        order: 0,
+                        file,
+                        type: "set-metadata-field",
+                        field: request.params.field,
+                        value: request.params.value,
+                    },
+                ]);
+            case "set-generate-metadata":
+                return this.buildPlan(operationId, request, [
+                    {
+                        order: 0,
+                        file,
+                        type: "set-generate-metadata",
+                        field: request.params.field,
+                        value: request.params.value,
+                    },
+                ]);
+        }
+    }
+    buildTextRewriteSteps(node, segmentIndex, value, textTarget) {
+        return textTarget?.kind === "value-binding" && textTarget.locator
+            ? [
+                {
+                    order: 0,
+                    file: textTarget.file,
+                    type: "update-value",
+                    locator: textTarget.locator,
+                    value,
+                },
+            ]
+            : textTarget?.kind === "external-entry"
+                ? [
+                    {
+                        order: 0,
+                        file: `external:${textTarget.sourceId}`,
+                        type: "invoke-external-adapter",
+                        sourceType: textTarget.sourceType,
+                        sourceId: textTarget.sourceId,
+                        adapterId: textTarget.adapterId,
+                        capability: "write-text",
+                        value,
+                    },
+                ]
+                : [
+                    {
+                        order: 0,
+                        file: node.file,
+                        type: "update-text",
+                        locator: makeLocator(node),
+                        segmentIndex,
+                        newText: value,
+                    },
+                ];
+    }
+    checkDocumentVersion(documentVersion, files) {
+        for (const file of new Set(files)) {
+            const currentVersion = this.graph.getFileVersion(file);
+            if (documentVersion < currentVersion) {
+                return {
+                    ok: false,
+                    errorCode: "stale-version",
+                    reason: `Document version ${documentVersion} is stale (current: ${currentVersion})`,
+                };
+            }
+        }
+        return null;
+    }
+    toTextContent(value) {
+        if (typeof value === "string") {
+            return value;
+        }
+        if (typeof value === "number" || typeof value === "boolean") {
+            return String(value);
+        }
+        return null;
+    }
+    /* ---------------------------------------------------------------- */
+    /*  update-text                                                      */
+    /* ---------------------------------------------------------------- */
+    planUpdateText(operationId, request, node, capability, textTarget) {
+        if (!capability.canUpdateText) {
+            return {
+                ok: false,
+                errorCode: "capability-denied",
+                reason: "Cannot update text on this node",
+            };
+        }
+        return this.buildPlan(operationId, request, this.buildTextRewriteSteps(node, request.params.segmentIndex, request.params.value, textTarget), capability);
+    }
+    /* ---------------------------------------------------------------- */
+    /*  remove-node                                                      */
+    /* ---------------------------------------------------------------- */
+    async planRemoveNode(operationId, request, node, capability) {
+        if (!capability.canRemove) {
+            return {
+                ok: false,
+                errorCode: "capability-denied",
+                reason: "Cannot remove this node",
+            };
+        }
+        if (node.richTextBlock) {
+            return this.planRichTextBlockRemoval(operationId, request, node, capability);
+        }
+        const primaryTextTarget = await this.graph.getTextWriteTarget(node.key, 0);
+        if (primaryTextTarget?.kind === "external-entry") {
+            return this.buildPlan(operationId, request, [
+                {
+                    order: 0,
+                    file: `external:${primaryTextTarget.sourceId}`,
+                    type: "invoke-external-adapter",
+                    sourceType: primaryTextTarget.sourceType,
+                    sourceId: primaryTextTarget.sourceId,
+                    adapterId: primaryTextTarget.adapterId,
+                    capability: "remove-node",
+                    value: { operation: "remove-node" },
+                },
+            ], capability);
+        }
+        if (node.isRepeatItemRoot) {
+            const valueTarget = primaryTextTarget;
+            if (valueTarget?.kind === "value-binding" && valueTarget.locator) {
+                const collection = getNearestCollectionLocator(valueTarget.locator);
+                if (collection) {
+                    return this.buildPlan(operationId, request, [
+                        {
+                            order: 0,
+                            file: valueTarget.file,
+                            type: "remove-array-item",
+                            locator: collection.locator,
+                            index: collection.index,
+                        },
+                    ], capability);
+                }
+            }
+            return {
+                ok: false,
+                errorCode: "unsupported-operation",
+                reason: "Repeat-backed node removal requires a writable array target",
+            };
+        }
+        const upstreamReason = getUpstreamNodeEditReason(node, primaryTextTarget, this.graph.getTextProvenance?.(node.key, 0) ?? null);
+        if (upstreamReason) {
+            return {
+                ok: false,
+                errorCode: "unsupported-operation",
+                reason: upstreamReason,
+            };
+        }
+        const repeatTemplateReason = this.getRepeatBackedTemplateStructureReason(node);
+        if (repeatTemplateReason) {
+            return {
+                ok: false,
+                errorCode: "unsupported-operation",
+                reason: repeatTemplateReason,
+            };
+        }
+        const upstreamDescendantReason = await this.getUpstreamBackedDescendantReason(node);
+        if (upstreamDescendantReason) {
+            return {
+                ok: false,
+                errorCode: "unsupported-operation",
+                reason: upstreamDescendantReason,
+            };
+        }
+        const steps = [
+            {
+                order: 0,
+                file: node.file,
+                type: "remove-node",
+                locator: makeLocator(node),
+                removeWhitespace: true,
+            },
+        ];
+        const removeImportStep = this.buildRemoveComponentImportStep(node);
+        if (removeImportStep) {
+            steps.push({ ...removeImportStep, order: steps.length });
+        }
+        return this.buildPlan(operationId, request, steps, capability);
+    }
+    buildRemoveComponentImportStep(node) {
+        if (!node.importedFrom || !node.exportName || !node.tag) {
+            return null;
+        }
+        if (countJsxTagReferences(this.graph.getFileContent(node.file), node.tag) > 1) {
+            return null;
+        }
+        const moduleSpecifier = computeRelativeSpecifier(node.file, node.importedFrom);
+        return {
+            order: 0,
+            file: node.file,
+            type: "remove-import",
+            moduleSpecifier,
+            imports: node.exportName === "default"
+                ? [{ kind: "default" }]
+                : [{ kind: "named", imported: node.exportName }],
+        };
+    }
+    /* ---------------------------------------------------------------- */
+    /*  insert-child                                                     */
+    /* ---------------------------------------------------------------- */
+    async planInsertChild(operationId, request, node, capability, anchorNode) {
+        const richTextInsertPlan = this.planRichTextBlockInsert(operationId, request, node, capability, anchorNode);
+        if (richTextInsertPlan) {
+            return richTextInsertPlan;
+        }
+        if (!capability.canInsertChild) {
+            return {
+                ok: false,
+                errorCode: "capability-denied",
+                reason: "Cannot insert child into this node",
+            };
+        }
+        const parentTextSegmentIndex = this.graph.getEditableTextSegmentIndex(node.key);
+        const parentTextTarget = parentTextSegmentIndex !== null
+            ? await this.graph.getTextWriteTarget(node.key, parentTextSegmentIndex)
+            : null;
+        const upstreamReason = getUpstreamNodeEditReason(node, parentTextTarget, parentTextSegmentIndex !== null
+            ? (this.graph.getTextProvenance?.(node.key, parentTextSegmentIndex) ??
+                null)
+            : null);
+        if (upstreamReason) {
+            return {
+                ok: false,
+                errorCode: "unsupported-operation",
+                reason: upstreamReason,
+            };
+        }
+        const upstreamDescendantReason = await this.getUpstreamBackedDescendantReason(node);
+        if (upstreamDescendantReason) {
+            return {
+                ok: false,
+                errorCode: "unsupported-operation",
+                reason: upstreamDescendantReason,
+            };
+        }
+        const externalInsertPlan = await this.planExternalBackedInsertChild(operationId, request, node, capability, anchorNode, parentTextTarget);
+        if (externalInsertPlan) {
+            return externalInsertPlan;
+        }
+        const repeatInsertPlan = await this.planRepeatBackedInsertChild(operationId, request, node, capability);
+        if (repeatInsertPlan) {
+            return repeatInsertPlan;
+        }
+        const repeatTemplateReason = this.getRepeatBackedTemplateStructureReason(node);
+        if (repeatTemplateReason) {
+            return {
+                ok: false,
+                errorCode: "unsupported-operation",
+                reason: repeatTemplateReason,
+            };
+        }
+        const insertPolicy = evaluateInsertChildPolicy(this.graph.getFileContent(node.file), node);
+        if (!insertPolicy.allowed) {
+            return {
+                ok: false,
+                errorCode: "unsupported-operation",
+                reason: insertPolicy.reason ?? "Cannot insert child into this node",
+            };
+        }
+        const invalidNestingReason = validateNativeInsertNesting(node, request.params.node);
+        if (invalidNestingReason) {
+            return {
+                ok: false,
+                errorCode: "unsupported-operation",
+                reason: invalidNestingReason,
+            };
+        }
+        const steps = [];
+        let order = 0;
+        const plannedComponentInsert = request.params.node.kind === "component-call"
+            ? planComponentInsert(request.params.node, this.graph.getFileContent(node.file))
+            : undefined;
+        const componentImport = plannedComponentInsert?.importStep;
+        if (componentImport) {
+            steps.push({
+                order: order++,
+                file: node.file,
+                type: "add-import",
+                moduleSpecifier: componentImport.moduleSpecifier,
+                imports: componentImport.imports,
+            });
+        }
+        steps.push({
+            order: order++,
+            file: node.file,
+            type: "insert-child",
+            parentLocator: makeLocator(node),
+            node: {
+                jsx: buildJsxFromSpec(request.params.node, plannedComponentInsert?.localName),
+            },
+            placement: request.params.position.relation,
+            anchorLocator: anchorNode ? makeLocator(anchorNode) : undefined,
+        });
+        return this.buildPlan(operationId, request, steps, capability);
+    }
+    async planExternalBackedInsertChild(operationId, request, node, capability, anchorNode, parentTextTarget) {
+        const externalTarget = parentTextTarget?.kind === "external-entry"
+            ? parentTextTarget
+            : await this.findExternalInsertContext(node, anchorNode);
+        if (!externalTarget) {
+            return null;
+        }
+        const anchorTarget = anchorNode
+            ? await this.graph.getTextWriteTarget(anchorNode.key, 0)
+            : null;
+        return this.buildPlan(operationId, request, [
+            {
+                order: 0,
+                file: `external:${externalTarget.sourceId}`,
+                type: "invoke-external-adapter",
+                sourceType: externalTarget.sourceType,
+                sourceId: externalTarget.sourceId,
+                adapterId: externalTarget.adapterId,
+                capability: "insert-child",
+                value: {
+                    operation: "insert-child",
+                    relation: request.params.position.relation,
+                    parentKey: node.key,
+                    anchorSourceId: anchorTarget?.kind === "external-entry"
+                        ? anchorTarget.sourceId
+                        : null,
+                    node: insertNodeSpecToOperationValue(request.params.node),
+                },
+            },
+        ], capability);
+    }
+    async findExternalInsertContext(node, anchorNode) {
+        if (anchorNode) {
+            const anchorTarget = await this.graph.getTextWriteTarget(anchorNode.key, 0);
+            if (anchorTarget?.kind === "external-entry") {
+                return anchorTarget;
+            }
+        }
+        if (!this.graph.getChildNodes) {
+            return null;
+        }
+        const stack = [...this.graph.getChildNodes(node.key)];
+        while (stack.length > 0) {
+            const child = stack.shift();
+            if (!child) {
+                continue;
+            }
+            const target = await this.graph.getTextWriteTarget(child.key, 0);
+            if (target?.kind === "external-entry") {
+                return target;
+            }
+            const externalSource = this.graph.getTextProvenance?.(child.key, 0)
+                ?.finalSource?.externalSource;
+            if (externalSource) {
+                return {
+                    kind: "external-entry",
+                    file: `external:${externalSource.sourceId}`,
+                    sourceType: externalSource.sourceType,
+                    sourceId: externalSource.sourceId,
+                    adapterId: externalSource.adapterId,
+                    displayExpression: externalSource.sourceId,
+                };
+            }
+            stack.push(...this.graph.getChildNodes(child.key));
+        }
+        return null;
+    }
+    async planRepeatBackedInsertChild(operationId, request, node, capability) {
+        if (request.params.position.relation !== "append" &&
+            request.params.position.relation !== "prepend") {
+            return null;
+        }
+        const insertNode = request.params.node;
+        if (insertNode.kind !== "native-tag" ||
+            insertNode.text === undefined ||
+            !this.graph.getChildNodes) {
+            return null;
+        }
+        const repeatChild = this.graph
+            .getChildNodes(node.key)
+            .find((child) => child.isRepeatItemRoot &&
+            child.tag?.toLowerCase() === insertNode.tag.toLowerCase());
+        if (!repeatChild) {
+            return null;
+        }
+        const valueTarget = await this.graph.getTextWriteTarget(repeatChild.key, 0);
+        if (!valueTarget ||
+            valueTarget.kind !== "value-binding" ||
+            !valueTarget.locator) {
+            return {
+                ok: false,
+                errorCode: "unsupported-operation",
+                reason: "Repeat-backed insert-child requires a writable value target",
+            };
+        }
+        const collection = getNearestCollectionLocator(valueTarget.locator);
+        if (!collection) {
+            return {
+                ok: false,
+                errorCode: "unsupported-operation",
+                reason: "Repeat-backed insert-child requires an array-backed target",
+            };
+        }
+        const value = buildRepeatInsertValueFromLocator(valueTarget.locator, insertNode.text);
+        if (value === undefined) {
+            return {
+                ok: false,
+                errorCode: "unsupported-operation",
+                reason: "Repeat-backed insert-child could not infer an item shape from the template",
+            };
+        }
+        const insertionIndex = request.params.position.relation === "prepend"
+            ? mapCollectionInsertionIndex(0, valueTarget.collectionIndexMap)
+            : mapCollectionInsertionIndex(valueTarget.collectionIndexMap?.length ?? collection.index + 1, valueTarget.collectionIndexMap);
+        return this.buildPlan(operationId, request, [
+            {
+                order: 0,
+                file: valueTarget.file,
+                type: "insert-array-item",
+                locator: collection.locator,
+                index: insertionIndex,
+                value,
+            },
+        ], capability);
+    }
+    async getUpstreamBackedDescendantReason(node) {
+        if (!this.graph.getChildNodes) {
+            return null;
+        }
+        const stack = [...this.graph.getChildNodes(node.key)];
+        while (stack.length > 0) {
+            const child = stack.shift();
+            if (!child) {
+                continue;
+            }
+            const segmentIndex = this.graph.getEditableTextSegmentIndex(child.key);
+            const textTarget = segmentIndex !== null
+                ? await this.graph.getTextWriteTarget(child.key, segmentIndex)
+                : null;
+            const reason = getUpstreamNodeEditReason(child, textTarget, segmentIndex !== null
+                ? (this.graph.getTextProvenance?.(child.key, segmentIndex) ?? null)
+                : null);
+            if (reason) {
+                return reason;
+            }
+            stack.push(...this.graph.getChildNodes(child.key));
+        }
+        return null;
+    }
+    getRepeatBackedTemplateStructureReason(node) {
+        if (node.isRepeatItemRoot) {
+            return "Cannot edit repeat-backed item template structure with a generic node operation";
+        }
+        if (node.structuralPath.includes("#repeat:")) {
+            return "Cannot edit repeat-backed child node structure with a generic node operation";
+        }
+        if (this.isInsideMapCallback(node)) {
+            return "Cannot edit repeat-backed child node structure with a generic node operation";
+        }
+        let parentKey = node.parentKey;
+        while (parentKey) {
+            const parent = this.graph.getNode(parentKey);
+            if (!parent) {
+                return null;
+            }
+            if (parent.isRepeatItemRoot || parent.isRepeatRegion) {
+                return "Cannot edit repeat-backed child node structure with a generic node operation";
+            }
+            parentKey = parent.parentKey;
+        }
+        return null;
+    }
+    isInsideMapCallback(node) {
+        const ast = parseModuleSource(this.graph.getFileContent(node.file));
+        if (!ast) {
+            return false;
+        }
+        const match = resolveLocatorPath(ast, makeLocator(node));
+        const nodePath = match.ok && match.match.path.isJSXElement()
+            ? match.match.path
+            : findJsxElementBySourceRange(ast, node);
+        if (!nodePath) {
+            return false;
+        }
+        return Boolean(nodePath.findParent((path) => {
+            if (!path.isCallExpression()) {
+                return false;
+            }
+            const callee = path.node.callee;
+            return (t.isMemberExpression(callee) &&
+                t.isIdentifier(callee.property) &&
+                callee.property.name === "map");
+        }));
+    }
+    /* ---------------------------------------------------------------- */
+    /*  move-node                                                        */
+    /* ---------------------------------------------------------------- */
+    async planMoveNode(operationId, request, node, capability) {
+        if (!capability.canMove) {
+            return {
+                ok: false,
+                errorCode: "capability-denied",
+                reason: "Cannot move this node",
+            };
+        }
+        const resolved = resolveTargetRelation(request.params.target, this.graph);
+        const targetParent = resolved.parentNode;
+        if (!targetParent) {
+            return {
+                ok: false,
+                errorCode: "locator-miss",
+                reason: `Target parent for request '${request.id}' not found in graph`,
+            };
+        }
+        if (node.richTextBlock) {
+            return this.planRichTextBlockMove(operationId, request, node, capability, resolved);
+        }
+        if (isSameOrDescendant(targetParent.key, node.key, this.graph)) {
+            return {
+                ok: false,
+                errorCode: "capability-denied",
+                reason: "Cannot move node into its own subtree",
+            };
+        }
+        if (node.isRepeatRegion && targetParent.isBoundary) {
+            return {
+                ok: false,
+                errorCode: "capability-denied",
+                reason: "Cannot move repeat-region node across boundary",
+            };
+        }
+        if (!this.graph.getCapability(targetParent.key).canInsertChild) {
+            return {
+                ok: false,
+                errorCode: "capability-denied",
+                reason: "Cannot move node into this parent",
+            };
+        }
+        const primaryTextTarget = await this.graph.getTextWriteTarget(node.key, 0);
+        if (primaryTextTarget?.kind === "external-entry") {
+            const placement = request.params.target.relation;
+            const anchorTarget = resolved.anchorNode && (placement === "before" || placement === "after")
+                ? await this.graph.getTextWriteTarget(resolved.anchorNode.key, 0)
+                : null;
+            return this.buildPlan(operationId, request, [
+                {
+                    order: 0,
+                    file: `external:${primaryTextTarget.sourceId}`,
+                    type: "invoke-external-adapter",
+                    sourceType: primaryTextTarget.sourceType,
+                    sourceId: primaryTextTarget.sourceId,
+                    adapterId: primaryTextTarget.adapterId,
+                    capability: "move-node",
+                    value: {
+                        operation: "move-node",
+                        relation: placement,
+                        anchorSourceId: anchorTarget?.kind === "external-entry"
+                            ? anchorTarget.sourceId
+                            : null,
+                        parentKey: "parentKey" in request.params.target
+                            ? request.params.target.parentKey
+                            : null,
+                    },
+                },
+            ], capability);
+        }
+        const upstreamReason = getUpstreamNodeEditReason(node, primaryTextTarget, this.graph.getTextProvenance?.(node.key, 0) ?? null);
+        if (upstreamReason) {
+            return {
+                ok: false,
+                errorCode: "unsupported-operation",
+                reason: upstreamReason,
+            };
+        }
+        const isCrossFile = node.file !== targetParent.file;
+        const placement = request.params.target.relation;
+        const anchorNode = resolved.anchorNode;
+        if (node.isRepeatItemRoot &&
+            anchorNode?.isRepeatItemRoot &&
+            node.repeatOwnerKey &&
+            node.repeatOwnerKey === anchorNode.repeatOwnerKey &&
+            (placement === "before" || placement === "after")) {
+            const sourceTarget = primaryTextTarget;
+            const anchorTarget = await this.graph.getTextWriteTarget(anchorNode.key, 0);
+            if (sourceTarget?.kind === "value-binding" &&
+                anchorTarget?.kind === "value-binding" &&
+                sourceTarget.locator &&
+                anchorTarget.locator) {
+                const sourceCollection = getNearestCollectionLocator(sourceTarget.locator);
+                const anchorCollection = getNearestCollectionLocator(anchorTarget.locator);
+                if (sourceCollection &&
+                    anchorCollection &&
+                    sourceTarget.file === anchorTarget.file &&
+                    sameValueLocator(sourceCollection.locator, anchorCollection.locator)) {
+                    const fromIndex = sourceCollection.index;
+                    const anchorIndex = anchorCollection.index;
+                    const toIndex = placement === "before"
+                        ? anchorIndex - (fromIndex < anchorIndex ? 1 : 0)
+                        : anchorIndex + (fromIndex < anchorIndex ? 0 : 1);
+                    return this.buildPlan(operationId, request, [
+                        {
+                            order: 0,
+                            file: sourceTarget.file,
+                            type: "move-array-item",
+                            locator: sourceCollection.locator,
+                            fromIndex,
+                            toIndex,
+                        },
+                    ], capability);
+                }
+            }
+        }
+        if (node.isRepeatItemRoot) {
+            return {
+                ok: false,
+                errorCode: "unsupported-operation",
+                reason: "Cannot move repeat-backed item outside its collection",
+            };
+        }
+        const repeatTemplateReason = this.getRepeatBackedTemplateStructureReason(node);
+        if (repeatTemplateReason) {
+            return {
+                ok: false,
+                errorCode: "unsupported-operation",
+                reason: repeatTemplateReason,
+            };
+        }
+        const upstreamDescendantReason = await this.getUpstreamBackedDescendantReason(node);
+        if (upstreamDescendantReason) {
+            return {
+                ok: false,
+                errorCode: "unsupported-operation",
+                reason: upstreamDescendantReason,
+            };
+        }
+        if (isCrossFile) {
+            return this.planCrossFileMove(operationId, request, node, targetParent, capability, placement, anchorNode);
+        }
+        const scopeCheck = checkSameFileMovePreservesLexicalBindings(this.graph.getFileContent(node.file), node, targetParent);
+        if (!scopeCheck.ok) {
+            return {
+                ok: false,
+                errorCode: "unsupported-operation",
+                reason: scopeCheck.reason ??
+                    `Cannot move node because it depends on bindings outside the target scope: ${scopeCheck.bindingNames.join(", ")}`,
+            };
+        }
+        const steps = [
+            {
+                order: 0,
+                file: node.file,
+                type: "move-node",
+                locator: makeLocator(node),
+                targetParentLocator: makeLocator(targetParent),
+                placement,
+                anchorLocator: anchorNode ? makeLocator(anchorNode) : undefined,
+            },
+        ];
+        return this.buildPlan(operationId, request, steps, capability);
+    }
+    /* ---------------------------------------------------------------- */
+    /*  cross-file move 展开                                             */
+    /* ---------------------------------------------------------------- */
+    planCrossFileMove(operationId, request, sourceNode, targetParent, capability, placement, anchorNode) {
+        const steps = [];
+        let order = 0;
+        const sourceContent = this.graph.getFileContent(sourceNode.file);
+        const sourceJsx = extractNodeJsx(this.graph, sourceNode) ?? `<${sourceNode.component} />`;
+        const movePolicy = evaluateCrossFileMovePolicy(sourceContent, sourceNode);
+        if (!movePolicy.allowed) {
+            return {
+                ok: false,
+                errorCode: "unsupported-operation",
+                reason: movePolicy.reason ?? "Cannot move subtree across files",
+            };
+        }
+        steps.push({
+            order: order++,
+            file: sourceNode.file,
+            type: "remove-node",
+            locator: makeLocator(sourceNode),
+            removeWhitespace: true,
+        });
+        if (sourceNode.importedFrom && sourceNode.exportName) {
+            const localComponentName = sourceNode.tag ?? sourceNode.component;
+            const targetModuleSpecifier = computeRelativeSpecifier(targetParent.file, sourceNode.importedFrom);
+            const sourceModuleSpecifier = computeRelativeSpecifier(sourceNode.file, sourceNode.importedFrom);
+            const componentImport = {
+                moduleSpecifier: targetModuleSpecifier,
+                imports: sourceNode.exportName === "default"
+                    ? [{ kind: "default", local: localComponentName }]
+                    : [
+                        {
+                            kind: "named",
+                            imported: sourceNode.exportName,
+                            local: localComponentName === sourceNode.exportName
+                                ? undefined
+                                : localComponentName,
+                        },
+                    ],
+            };
+            steps.push({
+                order: order++,
+                file: targetParent.file,
+                type: "add-import",
+                moduleSpecifier: componentImport.moduleSpecifier,
+                imports: componentImport.imports,
+            });
+            steps.push({
+                order: order++,
+                file: targetParent.file,
+                type: "insert-child",
+                parentLocator: makeLocator(targetParent),
+                node: { jsx: sourceJsx },
+                placement,
+                anchorLocator: anchorNode ? makeLocator(anchorNode) : undefined,
+            });
+            steps.push({
+                order: order++,
+                file: sourceNode.file,
+                type: "remove-import",
+                moduleSpecifier: sourceModuleSpecifier,
+                imports: componentImport.imports.map((item) => item.kind === "default"
+                    ? { kind: "default" }
+                    : { kind: "named", imported: item.imported }),
+            });
+        }
+        else {
+            steps.push({
+                order: order++,
+                file: targetParent.file,
+                type: "insert-child",
+                parentLocator: makeLocator(targetParent),
+                node: { jsx: sourceJsx },
+                placement,
+                anchorLocator: anchorNode ? makeLocator(anchorNode) : undefined,
+            });
+        }
+        return this.buildPlan(operationId, request, steps, capability);
+    }
+    /* ---------------------------------------------------------------- */
+    /*  通用 plan 构建                                                    */
+    /* ---------------------------------------------------------------- */
+    buildPlan(operationId, request, steps, capability) {
+        const files = new Set(steps.map((step) => step.file));
+        const preSnapshots = [...files].map((file) => ({
+            file,
+            content: this.graph.getFileContent(file),
+            version: this.graph.getFileVersion(file),
+        }));
+        return {
+            ok: true,
+            plan: {
+                operationId,
+                kind: request.kind,
+                target: request.target,
+                documentVersion: request.documentVersion,
+                steps,
+                preSnapshots,
+                validatedCapability: capability,
+            },
+        };
+    }
+}