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

package/dist/internal/runtime/InternalEditEngine.js

@@ -0,0 +1,1391 @@
+// ─── Designer Engine Facade ──────────────────────────
+// 来源: docs/04-module-api-and-call-graph.md §2
+//
+// DesignerEngine 是唯一语义中枢。
+// 所有 "can-edit / how-to-edit / what-happens-after" 决策只在 engine 中发生。
+import { OperationErrorCode } from "../protocol.js";
+import { buildMultiFileRenderGraph } from "../graph/project-graph-builder.js";
+import { buildEditableTopology } from "../topology/topology.js";
+import { resolveAllCapabilities } from "../capability/capability-resolver.js";
+import { projectDetailWriteTarget, projectRenderDocument, projectRenderObjectDetail, } from "../render/render-projection.js";
+import { buildComponentSemanticDescriptor } from "../render/component-semantic.js";
+import { buildContentModel } from "../render/content-model.js";
+import { buildMediaModel } from "../render/media-model.js";
+import { buildStyleSource } from "../render/tailwind-style-model.js";
+import { applyClassNameSourceWrite, extractClassNameSource, } from "../classname-source.js";
+import { OperationPlanner } from "../planner/planner.js";
+import { resolveProvenance, resolveTextProvenance, } from "../provenance/resolve-text-provenance.js";
+import { createWritebackService } from "../writeback/writeback-service.js";
+import { createEventBus } from "../events/event-bus.js";
+const nextRouteEntryPattern = /^(?:src\/)?app\/.*\/?page\.[cm]?[jt]sx?$/;
+const nextLayoutBasenames = [
+    "layout.tsx",
+    "layout.ts",
+    "layout.jsx",
+    "layout.js",
+    "layout.mjs",
+    "layout.cjs",
+];
+const repeatItemInstanceKeyMarker = "::repeat-item#";
+const richTextBlockKeyMarker = "::rich-text-block#";
+// ── Default in-memory file system ──
+function createDefaultFileSystem() {
+    const versions = new Map();
+    return {
+        async readFile(path) {
+            const fs = await import("node:fs/promises");
+            return fs.readFile(path, "utf-8");
+        },
+        async writeFile(path, content) {
+            const fs = await import("node:fs/promises");
+            await fs.writeFile(path, content, "utf-8");
+        },
+        async exists(path) {
+            const fs = await import("node:fs/promises");
+            try {
+                await fs.access(path);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        getVersion(file) {
+            return versions.get(file) ?? 0;
+        },
+        bumpVersion(file) {
+            const v = (versions.get(file) ?? 0) + 1;
+            versions.set(file, v);
+            return v;
+        },
+    };
+}
+function toTextSourceView(result) {
+    if (!result || result.kind !== "value-binding") {
+        return null;
+    }
+    const path = "path" in result ? result.path : undefined;
+    const root = result.root;
+    const bindingName = root && (root.kind === "binding" || root.kind === "named-export")
+        ? root.name
+        : undefined;
+    return {
+        kind: result.sourceKind,
+        file: result.file,
+        expression: result.displayExpression,
+        bindingName,
+        path: path?.map((segment) => segment.kind === "property" ? segment.name : segment.index),
+    };
+}
+function toWriteTargetView(writeTarget) {
+    return {
+        kind: writeTarget.isProxy ? "component-proxy" : "jsx-node",
+        file: writeTarget.file,
+        componentName: writeTarget.componentName,
+        isProxy: writeTarget.isProxy,
+    };
+}
+/**
+ * 创建 DesignerEngine 实例。
+ */
+export function createInternalEditEngine(config) {
+    let _status = "idle";
+    const _fileSystem = config.fileSystem ?? createDefaultFileSystem();
+    const _eventBus = createEventBus();
+    const _routes = new Map();
+    let _activeRouteId = null;
+    const _pendingRebuildFiles = new Set();
+    let _rebuildLoop = null;
+    const _writebackService = createWritebackService(_fileSystem, {
+        externalAdapters: config.externalAdapters,
+    });
+    const _fileContentCache = new Map();
+    let _documentVersion = 0;
+    let _mutationsInFlight = 0;
+    // Register onEvent callback
+    if (config.onEvent) {
+        _eventBus.subscribe(config.onEvent);
+    }
+    // Register initial routes
+    if (config.routes) {
+        for (const route of config.routes) {
+            _routes.set(route.routeId, {
+                routeId: route.routeId,
+                entryFile: route.entryFile,
+                graph: null,
+                topology: null,
+                capabilities: null,
+                document: null,
+                detailProjections: null,
+                fileVersions: new Map(),
+            });
+        }
+    }
+    // ── Build route graph (async, multi-file aware) ──
+    async function buildDetailProjections(graph, topology, allSources) {
+        const detailProjections = new Map();
+        const provenanceFileCache = new Map();
+        const exists = typeof _fileSystem.exists === "function"
+            ? (path) => _fileSystem.exists(path)
+            : async () => false;
+        for (const [key, element] of graph.elements) {
+            const topNode = topology.nodes.get(key);
+            if (!topNode) {
+                continue;
+            }
+            const source = allSources.get(element.sourceFile) ??
+                _fileContentCache.get(element.sourceFile);
+            const textSources = new Map();
+            const textTargets = new Map();
+            const provenances = new Map();
+            const segmentResolutions = [];
+            for (const segment of element.textSegments) {
+                if (!source) {
+                    textSources.set(segment.index, null);
+                    continue;
+                }
+                const resolved = await resolveTextProvenance({
+                    file: element.sourceFile,
+                    source,
+                    segment,
+                    readFile: (path) => _fileSystem.readFile(path),
+                    exists,
+                    graph,
+                    externalSourceResolvers: config.externalSourceResolvers,
+                    externalAdapters: config.externalAdapters?.map(({ sourceType, adapterId, capabilities }) => ({
+                        sourceType,
+                        adapterId,
+                        capabilities,
+                    })),
+                    functionCallContracts: config.functionCallContracts,
+                    fileCache: provenanceFileCache,
+                });
+                const provenance = await resolveProvenance({
+                    file: element.sourceFile,
+                    source,
+                    target: { kind: "text-segment", segment },
+                    readFile: (path) => _fileSystem.readFile(path),
+                    exists,
+                    graph,
+                    externalSourceResolvers: config.externalSourceResolvers,
+                    externalAdapters: config.externalAdapters?.map(({ sourceType, adapterId, capabilities }) => ({
+                        sourceType,
+                        adapterId,
+                        capabilities,
+                    })),
+                    functionCallContracts: config.functionCallContracts,
+                    fileCache: provenanceFileCache,
+                });
+                const textSource = toTextSourceView(resolved);
+                textSources.set(segment.index, textSource);
+                textTargets.set(segment.index, resolved);
+                provenances.set(segment.index, provenance);
+                segmentResolutions.push({
+                    editable: segment.editable,
+                    source: textSource,
+                });
+            }
+            const writeTarget = projectDetailWriteTarget(toWriteTargetView(topNode.writeTarget), segmentResolutions);
+            const componentSemantic = buildComponentSemanticDescriptor({
+                key,
+                element,
+                graph,
+                provenances,
+            });
+            const contentModel = buildContentModel(element);
+            const mediaModel = buildMediaModel(element);
+            const styleSource = buildStyleSource(element);
+            const conditionalRegion = graph.regions.find((region) => region.kind === "conditional-region" &&
+                region.childKeys.includes(key));
+            let conditional;
+            const candidate = conditionalRegion?.sourceCandidates?.[0];
+            if (source &&
+                conditionalRegion &&
+                candidate?.kind === "conditional-branch") {
+                const provenance = await resolveProvenance({
+                    file: element.sourceFile,
+                    source,
+                    target: { kind: "conditional-branch", candidate },
+                    readFile: (path) => _fileSystem.readFile(path),
+                    exists,
+                    graph,
+                    externalSourceResolvers: config.externalSourceResolvers,
+                    externalAdapters: config.externalAdapters?.map(({ sourceType, adapterId, capabilities }) => ({
+                        sourceType,
+                        adapterId,
+                        capabilities,
+                    })),
+                    functionCallContracts: config.functionCallContracts,
+                    fileCache: provenanceFileCache,
+                });
+                const branchIndex = conditionalRegion.childKeys.indexOf(key);
+                conditional = {
+                    currentBranch: branchIndex <= 0 ? "then" : "else",
+                    availableBranches: conditionalRegion.childKeys.length > 1
+                        ? ["then", "else"]
+                        : ["then"],
+                    conditionExpression: candidate.conditionExpression,
+                    provenance: {
+                        finalSource: provenance.finalSource
+                            ? {
+                                kind: provenance.finalSource.kind,
+                                file: provenance.finalSource.file,
+                                displayPath: provenance.finalSource.displayPath,
+                            }
+                            : null,
+                        chain: provenance.chain.map((hop) => ({
+                            kind: hop.kind,
+                            file: hop.file,
+                            displayName: hop.displayName,
+                            canEditHere: hop.canEditHere,
+                        })),
+                        confidence: provenance.confidence,
+                        editMode: provenance.editMode,
+                        diagnostics: provenance.diagnostics.map((diagnostic) => ({
+                            code: diagnostic.code,
+                            message: diagnostic.message,
+                        })),
+                    },
+                };
+            }
+            detailProjections.set(key, {
+                textSources,
+                textTargets,
+                provenances,
+                writeTarget,
+                componentSemantic,
+                contentModel,
+                mediaModel,
+                styleSource,
+                conditional,
+            });
+        }
+        return detailProjections;
+    }
+    function getTrackedFileVersion(file) {
+        return typeof _fileSystem.getVersion === "function"
+            ? _fileSystem.getVersion(file)
+            : 0;
+    }
+    function getRouteVersionFloor(routeState, fileVersions) {
+        let versionFloor = 1;
+        for (const version of fileVersions.values()) {
+            versionFloor = Math.max(versionFloor, version);
+        }
+        return Math.max(versionFloor, routeState.graph?.version ?? 0);
+    }
+    async function buildRoute(routeId, source, options = {}) {
+        const routeState = _routes.get(routeId);
+        if (!routeState)
+            return;
+        const additionalEntries = await loadNextRouteLayoutEntries(routeState.entryFile);
+        // Use multi-file builder to load + merge all locally-imported files
+        const { graph, allSources } = await buildMultiFileRenderGraph(routeState.entryFile, source, (path) => _fileSystem.readFile(path), typeof _fileSystem.exists === "function"
+            ? (path) => _fileSystem.exists(path)
+            : async () => false, {
+            additionalEntries,
+            version: routeState.graph?.version ?? 1,
+        });
+        const fileVersions = new Map();
+        for (const file of allSources.keys()) {
+            fileVersions.set(file, getTrackedFileVersion(file));
+        }
+        let routeVersion = Math.max(getRouteVersionFloor(routeState, fileVersions), options.minimumVersion ?? 0);
+        if (options.changed && routeVersion <= (routeState.graph?.version ?? 0)) {
+            routeVersion = (routeState.graph?.version ?? 0) + 1;
+        }
+        graph.version = routeVersion;
+        _documentVersion = Math.max(_documentVersion, routeVersion);
+        // Cache all loaded source files for planner use
+        for (const [file, src] of allSources) {
+            _fileContentCache.set(file, src);
+        }
+        graph.routeId = routeId;
+        const topology = buildEditableTopology(graph);
+        const capabilities = resolveAllCapabilities(topology, graph);
+        const detailProjections = await buildDetailProjections(graph, topology, allSources);
+        const canUpdateTextByKey = resolveEffectiveUpdateTextCapabilities(graph, capabilities, detailProjections);
+        const document = projectRichTextBlockEntries(projectRepeatConcreteEntries(projectRenderDocument(graph, topology, capabilities, {
+            canUpdateTextByKey,
+        }), graph, detailProjections), graph, detailProjections);
+        routeState.graph = graph;
+        routeState.topology = topology;
+        routeState.capabilities = capabilities;
+        routeState.document = document;
+        routeState.detailProjections = detailProjections;
+        routeState.fileVersions = fileVersions;
+    }
+    async function loadNextRouteLayoutEntries(entryFile) {
+        const entries = [];
+        for (const file of getNextRouteLayoutCandidates(entryFile)) {
+            const exists = typeof _fileSystem.exists === "function"
+                ? await _fileSystem.exists(file)
+                : false;
+            if (!exists) {
+                continue;
+            }
+            entries.push({
+                file,
+                source: await _fileSystem.readFile(file),
+            });
+        }
+        return entries;
+    }
+    function resolveEffectiveUpdateTextCapabilities(graph, capabilities, detailProjections) {
+        const result = new Map();
+        for (const [key, element] of graph.elements) {
+            const capability = capabilities.get(key);
+            if (!capability?.canUpdateText) {
+                result.set(key, false);
+                continue;
+            }
+            const detail = detailProjections.get(key);
+            const hasWritableSegment = element.textSegments.some((segment) => {
+                if (!segment.editable) {
+                    return false;
+                }
+                const provenance = detail?.provenances.get(segment.index) ?? null;
+                return !provenance || isWritableUpdateTextProvenance(provenance);
+            });
+            result.set(key, hasWritableSegment);
+        }
+        return result;
+    }
+    function isWritableUpdateTextProvenance(provenance) {
+        return (provenance.editMode === "direct" ||
+            provenance.editMode === "proxy" ||
+            provenance.editMode === "upstream");
+    }
+    async function rebuildRoutesForFiles(files, options = {}) {
+        const uniqueFiles = new Set(files);
+        const result = {
+            rebuiltRoutes: [],
+            failedRoutes: [],
+        };
+        for (const routeState of _routes.values()) {
+            const isAffected = [...uniqueFiles].some((file) => routeState.entryFile === file ||
+                routeState.graph?.fileIndex.has(file));
+            if (!isAffected) {
+                continue;
+            }
+            try {
+                const entrySource = await _fileSystem.readFile(routeState.entryFile);
+                await buildRoute(routeState.routeId, entrySource, options);
+                if (routeState.graph) {
+                    result.rebuiltRoutes.push({
+                        routeId: routeState.routeId,
+                        version: routeState.graph.version,
+                    });
+                }
+            }
+            catch (error) {
+                result.failedRoutes.push({
+                    routeId: routeState.routeId,
+                    message: getErrorMessage(error),
+                });
+            }
+        }
+        return result;
+    }
+    function getAffectedRouteVersion(files, fallbackVersion = 0) {
+        const uniqueFiles = new Set(files);
+        let version = fallbackVersion;
+        for (const routeState of _routes.values()) {
+            const isAffected = [...uniqueFiles].some((file) => routeState.entryFile === file ||
+                routeState.graph?.fileIndex.has(file));
+            if (isAffected && routeState.graph) {
+                version = Math.max(version, routeState.graph.version);
+            }
+        }
+        return version;
+    }
+    function getAffectedRouteIds(files) {
+        const uniqueFiles = new Set(files);
+        const routeIds = new Set();
+        for (const routeState of _routes.values()) {
+            const isAffected = [...uniqueFiles].some((file) => routeState.entryFile === file ||
+                routeState.graph?.fileIndex.has(file));
+            if (isAffected) {
+                routeIds.add(routeState.routeId);
+            }
+        }
+        return [...routeIds];
+    }
+    function scheduleRouteRebuild(files) {
+        for (const file of files) {
+            _pendingRebuildFiles.add(file);
+        }
+        if (_rebuildLoop || _status === "disposed") {
+            return;
+        }
+        _rebuildLoop = (async () => {
+            _status = "building";
+            try {
+                while (_pendingRebuildFiles.size > 0) {
+                    await waitForMutationRebuilds();
+                    const filesToRebuild = [..._pendingRebuildFiles];
+                    _pendingRebuildFiles.clear();
+                    const changedFiles = await filterChangedSourceFiles(filesToRebuild);
+                    if (changedFiles.length === 0) {
+                        continue;
+                    }
+                    const affectedRouteIds = getAffectedRouteIds(changedFiles);
+                    for (const routeId of affectedRouteIds) {
+                        _eventBus.emit({ type: "graph-invalidated", routeId });
+                    }
+                    const { rebuiltRoutes, failedRoutes } = await rebuildRoutesForFiles(changedFiles, { changed: true });
+                    for (const { routeId, version } of rebuiltRoutes) {
+                        _eventBus.emit({ type: "graph-ready", routeId, version });
+                    }
+                    for (const { routeId, message } of failedRoutes) {
+                        _eventBus.emit({ type: "graph-error", routeId, message });
+                    }
+                }
+            }
+            finally {
+                _rebuildLoop = null;
+                if (_status !== "disposed") {
+                    _status = "ready";
+                }
+                if (_pendingRebuildFiles.size > 0) {
+                    scheduleRouteRebuild([]);
+                }
+            }
+        })();
+    }
+    async function waitForMutationRebuilds() {
+        while (_mutationsInFlight > 0) {
+            await new Promise((resolve) => setTimeout(resolve, 0));
+        }
+    }
+    async function filterChangedSourceFiles(files) {
+        const changedFiles = [];
+        for (const file of new Set(files)) {
+            const cachedSource = _fileContentCache.get(file);
+            if (cachedSource === undefined) {
+                changedFiles.push(file);
+                continue;
+            }
+            try {
+                const currentSource = await _fileSystem.readFile(file);
+                if (currentSource !== cachedSource) {
+                    changedFiles.push(file);
+                }
+            }
+            catch {
+                changedFiles.push(file);
+            }
+        }
+        return changedFiles;
+    }
+    // ── Ensure route is built ──
+    async function ensureRouteBuilt(routeId) {
+        const routeState = _routes.get(routeId);
+        if (!routeState)
+            throw new Error(`Route not found: ${routeId}`);
+        if (routeState.graph)
+            return; // already built
+        const source = await _fileSystem.readFile(routeState.entryFile);
+        await buildRoute(routeId, source);
+    }
+    function getRouteStateForKey(key, routeId) {
+        if (routeId) {
+            const routeState = _routes.get(routeId) ?? null;
+            if (!routeState || !routeStateHasKey(routeState, key)) {
+                return null;
+            }
+            return routeState;
+        }
+        for (const routeState of _routes.values()) {
+            if (routeStateHasKey(routeState, key)) {
+                return routeState;
+            }
+        }
+        return null;
+    }
+    function routeStateHasKey(routeState, key) {
+        if (routeState.graph?.elements.has(key)) {
+            return true;
+        }
+        const repeatInstance = parseRepeatItemInstanceKey(key);
+        if (repeatInstance) {
+            return routeState.graph?.elements.has(repeatInstance.baseKey) === true;
+        }
+        const richTextBlock = parseRichTextBlockKey(key);
+        return richTextBlock
+            ? routeState.graph?.elements.has(richTextBlock.ownerKey) === true
+            : false;
+    }
+    const engine = {
+        get status() {
+            return _status;
+        },
+        dispose() {
+            _status = "disposed";
+        },
+        registerRoute(routeId, entryFile) {
+            _routes.set(routeId, {
+                routeId,
+                entryFile,
+                graph: null,
+                topology: null,
+                capabilities: null,
+                document: null,
+                detailProjections: null,
+                fileVersions: new Map(),
+            });
+        },
+        async setActiveRoute(routeId) {
+            const routeState = _routes.get(routeId);
+            if (!routeState)
+                throw new Error(`Route not found: ${routeId}`);
+            const wasAlreadyActive = _activeRouteId === routeId;
+            _activeRouteId = routeId;
+            if (!routeState.graph) {
+                _status = "building";
+                try {
+                    const source = await _fileSystem.readFile(routeState.entryFile);
+                    await buildRoute(routeId, source);
+                    const nextVersion = _routes.get(routeId)?.graph?.version ?? 1;
+                    _status = "ready";
+                    _eventBus.emit({
+                        type: "graph-ready",
+                        routeId,
+                        version: nextVersion,
+                    });
+                }
+                catch {
+                    _status = "ready"; // degrade gracefully with empty state
+                }
+                return;
+            }
+            _status = "ready";
+            if (!wasAlreadyActive) {
+                _eventBus.emit({
+                    type: "graph-ready",
+                    routeId,
+                    version: routeState.graph.version,
+                });
+            }
+        },
+        getDocument(routeId) {
+            const routeState = _routes.get(routeId);
+            if (!routeState)
+                throw new Error(`Route not found: ${routeId}`);
+            if (!routeState.document)
+                throw new Error(`Route not built: ${routeId}`);
+            return routeState.document;
+        },
+        getObjectCapabilities(key, routeId) {
+            const routeState = getRouteStateForKey(key, routeId);
+            const richTextBlock = parseRichTextBlockKey(key);
+            if (richTextBlock) {
+                return {
+                    key,
+                    canUpdateText: false,
+                    canInsertChild: false,
+                    canMove: true,
+                    canRemove: true,
+                    boundaryKind: null,
+                    isOpaque: false,
+                };
+            }
+            const baseKey = parseRepeatItemInstanceKey(key)?.baseKey ?? key;
+            const element = routeState?.graph?.elements.get(baseKey);
+            const capability = routeState?.capabilities?.get(baseKey);
+            if (element && capability) {
+                return {
+                    key,
+                    canUpdateText: capability.canUpdateText,
+                    canInsertChild: capability.canInsertChild,
+                    canMove: capability.canMove,
+                    canRemove: capability.canRemove,
+                    boundaryKind: element.boundaryKind,
+                    isOpaque: element.isOpaque,
+                };
+            }
+            throw new Error(`Key not found: ${key}`);
+        },
+        getRenderDetail(key, routeId) {
+            const routeState = getRouteStateForKey(key, routeId);
+            const richTextBlock = parseRichTextBlockKey(key);
+            const baseKey = richTextBlock?.ownerKey ??
+                parseRepeatItemInstanceKey(key)?.baseKey ??
+                key;
+            if (routeState?.graph &&
+                routeState.topology &&
+                routeState.capabilities &&
+                routeState.detailProjections) {
+                const detailState = routeState.detailProjections.get(baseKey);
+                if (detailState) {
+                    const detail = projectRenderObjectDetail(baseKey, routeState.graph, routeState.topology, routeState.capabilities, detailState.textSources, detailState.writeTarget, detailState.provenances, detailState.conditional, detailState.componentSemantic, detailState.contentModel, detailState.mediaModel, detailState.styleSource, detailState.styleModel);
+                    return key === baseKey ? detail : { ...detail, key };
+                }
+            }
+            throw new Error(`Key not found: ${key}`);
+        },
+        getClassNameSource(key, routeId) {
+            const routeState = getRouteStateForKey(key, routeId);
+            const baseKey = parseRepeatItemInstanceKey(key)?.baseKey ?? key;
+            if (!routeState?.graph) {
+                throw new Error(`Key not found: ${key}`);
+            }
+            const element = routeState.graph.elements.get(baseKey);
+            if (!element) {
+                throw new Error(`Key not found: ${key}`);
+            }
+            const source = _fileContentCache.get(element.sourceFile);
+            if (source === undefined) {
+                throw new Error(`Source not loaded: ${element.sourceFile}`);
+            }
+            return extractClassNameSource({
+                key: baseKey,
+                route: {
+                    routeId: routeState.routeId,
+                    graph: routeState.graph,
+                    source,
+                },
+            });
+        },
+        async setClassNameSource(request) {
+            const routeState = getRouteStateForKey(request.key, request.routeId);
+            const baseKey = parseRepeatItemInstanceKey(request.key)?.baseKey ?? request.key;
+            if (!routeState?.graph) {
+                return {
+                    ok: false,
+                    reason: "node_not_found",
+                    diagnostics: [
+                        {
+                            code: "source-locator-warning",
+                            message: `Key not found: ${request.key}`,
+                        },
+                    ],
+                };
+            }
+            const element = routeState.graph.elements.get(baseKey);
+            if (!element) {
+                return {
+                    ok: false,
+                    reason: "node_not_found",
+                    diagnostics: [
+                        {
+                            code: "source-locator-warning",
+                            message: `Key not found: ${request.key}`,
+                        },
+                    ],
+                };
+            }
+            const source = _fileContentCache.get(element.sourceFile) ??
+                (await _fileSystem.readFile(element.sourceFile));
+            const current = extractClassNameSource({
+                key: baseKey,
+                route: {
+                    routeId: routeState.routeId,
+                    graph: routeState.graph,
+                    source,
+                },
+            });
+            const result = await applyClassNameSourceWrite({
+                request,
+                current,
+                source,
+                writeSource: async (nextSource) => {
+                    await _fileSystem.writeFile(element.sourceFile, nextSource);
+                    _fileSystem.bumpVersion?.(element.sourceFile);
+                    _fileContentCache.set(element.sourceFile, nextSource);
+                },
+            });
+            if (!result.ok) {
+                return result;
+            }
+            await rebuildRoutesForFiles([element.sourceFile], {
+                changed: true,
+                minimumVersion: request.expectedVersion.documentVersion + 1,
+            });
+            return {
+                ok: true,
+                source: this.getClassNameSource(baseKey, routeState.routeId),
+            };
+        },
+        async execute(request) {
+            // 1. Find route
+            let routeState = null;
+            if (request.target.kind === "node") {
+                routeState = getRouteStateForKey(request.target.key, request.routeId);
+            }
+            else {
+                routeState = _routes.get(request.target.routeId) ?? null;
+                if (routeState && !routeState.graph) {
+                    await ensureRouteBuilt(routeState.routeId);
+                }
+            }
+            if (!routeState) {
+                return {
+                    requestId: request.id,
+                    kind: request.kind,
+                    target: request.target,
+                    ok: false,
+                    resultVersion: _documentVersion,
+                    error: {
+                        code: request.target.kind === "route"
+                            ? OperationErrorCode.ROUTE_NOT_FOUND
+                            : OperationErrorCode.NODE_NOT_FOUND,
+                        message: request.target.kind === "route"
+                            ? `Route not found: ${request.target.routeId}`
+                            : `Target key not found: ${request.target.key}`,
+                    },
+                };
+            }
+            if (!routeState.graph ||
+                !routeState.topology ||
+                !routeState.capabilities) {
+                return {
+                    requestId: request.id,
+                    kind: request.kind,
+                    target: request.target,
+                    ok: false,
+                    resultVersion: _documentVersion,
+                    error: {
+                        code: request.target.kind === "route"
+                            ? OperationErrorCode.ROUTE_NOT_FOUND
+                            : OperationErrorCode.NODE_NOT_FOUND,
+                        message: request.target.kind === "route"
+                            ? `Route not ready: ${request.target.routeId}`
+                            : `Target key not found: ${request.target.key}`,
+                    },
+                };
+            }
+            // 2. Plan via OperationPlanner
+            const graphAccess = createPlannerGraphAccess(routeState, routeState.graph, routeState.capabilities, _fileContentCache, _fileSystem);
+            const planResult = await new OperationPlanner(graphAccess).plan(request);
+            if (!planResult.ok) {
+                return {
+                    requestId: request.id,
+                    kind: request.kind,
+                    target: request.target,
+                    ok: false,
+                    resultVersion: _documentVersion,
+                    error: {
+                        code: mapInternalErrorCode(planResult.errorCode),
+                        message: planResult.reason,
+                    },
+                };
+            }
+            const rewritePlan = planResult.plan;
+            if (rewritePlan.steps.length === 0) {
+                return {
+                    requestId: request.id,
+                    kind: request.kind,
+                    target: request.target,
+                    ok: false,
+                    resultVersion: _documentVersion,
+                    error: {
+                        code: OperationErrorCode.PLAN_FAILED,
+                        message: "Planner could not generate a valid execution plan",
+                    },
+                };
+            }
+            // 3. Delegate execute + snapshot + undo-stack to writeback-service
+            _mutationsInFlight += 1;
+            const internal = await _writebackService.execute(rewritePlan);
+            if (!internal.ok) {
+                _mutationsInFlight -= 1;
+                return {
+                    requestId: request.id,
+                    kind: request.kind,
+                    target: request.target,
+                    ok: false,
+                    resultVersion: _documentVersion,
+                    error: {
+                        code: mapInternalErrorCode(internal.errorCode),
+                        message: internal.reason,
+                    },
+                };
+            }
+            // 4. Rebuild graph for affected files
+            try {
+                await rebuildRoutesForFiles(internal.affectedFiles, {
+                    changed: true,
+                    minimumVersion: internal.resultVersion,
+                });
+            }
+            finally {
+                _mutationsInFlight -= 1;
+            }
+            const resultVersion = getAffectedRouteVersion(internal.affectedFiles, internal.resultVersion);
+            _documentVersion = Math.max(_documentVersion, resultVersion);
+            // 5. Emit events
+            const result = {
+                requestId: request.id,
+                kind: request.kind,
+                target: request.target,
+                ok: true,
+                resultVersion,
+            };
+            _eventBus.emit({ type: "operation-completed", result });
+            if (routeState.routeId) {
+                _eventBus.emit({
+                    type: "document-changed",
+                    routeId: routeState.routeId,
+                    version: resultVersion,
+                });
+            }
+            return result;
+        },
+        async undo() {
+            _mutationsInFlight += 1;
+            const internal = await _writebackService.undo();
+            if (!internal.ok) {
+                _mutationsInFlight -= 1;
+                return {
+                    requestId: "undo",
+                    kind: "update-text",
+                    target: { kind: "node", key: "" },
+                    ok: false,
+                    resultVersion: _documentVersion,
+                    error: {
+                        code: OperationErrorCode.INTERNAL_ERROR,
+                        message: internal.reason,
+                    },
+                };
+            }
+            try {
+                await rebuildRoutesForFiles(internal.affectedFiles, {
+                    changed: true,
+                    minimumVersion: internal.resultVersion,
+                });
+            }
+            finally {
+                _mutationsInFlight -= 1;
+            }
+            const resultVersion = getAffectedRouteVersion(internal.affectedFiles, internal.resultVersion);
+            _documentVersion = Math.max(_documentVersion, resultVersion);
+            return {
+                requestId: "undo",
+                kind: "update-text",
+                target: { kind: "node", key: "" },
+                ok: true,
+                resultVersion,
+            };
+        },
+        async redo() {
+            _mutationsInFlight += 1;
+            const internal = await _writebackService.redo();
+            if (!internal.ok) {
+                _mutationsInFlight -= 1;
+                return {
+                    requestId: "redo",
+                    kind: "update-text",
+                    target: { kind: "node", key: "" },
+                    ok: false,
+                    resultVersion: _documentVersion,
+                    error: {
+                        code: OperationErrorCode.INTERNAL_ERROR,
+                        message: internal.reason,
+                    },
+                };
+            }
+            try {
+                await rebuildRoutesForFiles(internal.affectedFiles, {
+                    changed: true,
+                    minimumVersion: internal.resultVersion,
+                });
+            }
+            finally {
+                _mutationsInFlight -= 1;
+            }
+            const resultVersion = getAffectedRouteVersion(internal.affectedFiles, internal.resultVersion);
+            _documentVersion = Math.max(_documentVersion, resultVersion);
+            return {
+                requestId: "redo",
+                kind: "update-text",
+                target: { kind: "node", key: "" },
+                ok: true,
+                resultVersion,
+            };
+        },
+        notifyFileChanged(file) {
+            const affectedFiles = new Set();
+            // Find routes affected by this file change
+            for (const routeState of _routes.values()) {
+                if (routeState.entryFile === file ||
+                    routeState.graph?.fileIndex.has(file)) {
+                    affectedFiles.add(file);
+                }
+            }
+            scheduleRouteRebuild(affectedFiles);
+        },
+        subscribe(listener) {
+            return _eventBus.subscribe(listener);
+        },
+    };
+    return engine;
+}
+// ── PlannerGraphAccess adapter ──────────────────────────────────────
+/**
+ * Creates a PlannerGraphAccess from the engine's route state + file system.
+ * Maps protocol/engine types to the shapes planner.ts expects.
+ */
+function createPlannerGraphAccess(routeState, graph, capabilities, fileContentCache, fs) {
+    const repeatRootOwners = new Map();
+    const repeatTemplateOwners = new Map();
+    const visitRepeatTemplateNode = (key, ownerKey) => {
+        if (repeatTemplateOwners.has(key)) {
+            return;
+        }
+        repeatTemplateOwners.set(key, ownerKey);
+        const element = graph.elements.get(key);
+        for (const childKey of element?.childKeys ?? []) {
+            visitRepeatTemplateNode(childKey, ownerKey);
+        }
+    };
+    for (const region of graph.regions) {
+        if (region.kind !== "repeat-region")
+            continue;
+        for (const childKey of region.childKeys) {
+            repeatRootOwners.set(childKey, region.ownerKey);
+            visitRepeatTemplateNode(childKey, region.ownerKey);
+        }
+    }
+    return {
+        getNode(key) {
+            const resolved = resolvePlannerKey(key);
+            const element = graph.elements.get(resolved.baseKey);
+            if (!element)
+                return null;
+            return toNodeInfo(key, element, resolved.repeatIndex, resolved.richTextBlock);
+        },
+        getChildNodes(key) {
+            const resolved = resolvePlannerKey(key);
+            if (resolved.richTextBlock) {
+                return [];
+            }
+            const element = graph.elements.get(resolved.baseKey);
+            if (!element)
+                return [];
+            return element.childKeys
+                .map((childKey) => {
+                const child = graph.elements.get(childKey);
+                return child ? toNodeInfo(childKey, child) : null;
+            })
+                .filter((child) => child !== null);
+        },
+        getCapability(key) {
+            const resolved = resolvePlannerKey(key);
+            if (resolved.richTextBlock) {
+                return {
+                    key,
+                    canUpdateText: false,
+                    canRemove: true,
+                    canInsertChild: false,
+                    canMove: true,
+                    constraints: [],
+                };
+            }
+            const cap = capabilities.get(resolved.baseKey);
+            if (!cap) {
+                return {
+                    key,
+                    canUpdateText: false,
+                    canRemove: false,
+                    canInsertChild: false,
+                    canMove: false,
+                    constraints: [],
+                };
+            }
+            return {
+                key,
+                canUpdateText: cap.canUpdateText,
+                canRemove: cap.canRemove,
+                canInsertChild: cap.canInsertChild,
+                canMove: cap.canMove,
+                constraints: cap.constraints.map((c) => c.message),
+            };
+        },
+        getFileContent(file) {
+            return fileContentCache.get(file) ?? "";
+        },
+        getFileVersion(file) {
+            return Math.max(routeState.fileVersions.get(file) ?? 0, graph.version);
+        },
+        getRouteEntryFile(routeId) {
+            return routeState.routeId === routeId ? routeState.entryFile : null;
+        },
+        getComponentSemantic(key) {
+            const resolved = resolvePlannerKey(key);
+            return (routeState.detailProjections?.get(resolved.baseKey)
+                ?.componentSemantic ?? null);
+        },
+        getEditableTextSegmentIndex(key) {
+            const resolved = resolvePlannerKey(key);
+            const iterator = routeState.detailProjections
+                ?.get(resolved.baseKey)
+                ?.textTargets.keys();
+            const first = iterator?.next();
+            return first && !first.done ? first.value : null;
+        },
+        async getTextWriteTarget(key, segmentIndex) {
+            const resolved = resolvePlannerKey(key);
+            return retargetRepeatTextWriteTarget(routeState.detailProjections
+                ?.get(resolved.baseKey)
+                ?.textTargets.get(segmentIndex) ?? null, resolved.repeatIndex);
+        },
+        getTextProvenance(key, segmentIndex) {
+            const resolved = resolvePlannerKey(key);
+            return (routeState.detailProjections
+                ?.get(resolved.baseKey)
+                ?.provenances.get(segmentIndex) ?? null);
+        },
+    };
+    function resolvePlannerKey(key) {
+        const richTextBlock = parseRichTextBlockKey(key);
+        if (richTextBlock) {
+            return {
+                baseKey: richTextBlock.ownerKey,
+                repeatIndex: null,
+                richTextBlock,
+            };
+        }
+        const repeatInstance = parseRepeatItemInstanceKey(key);
+        if (repeatInstance) {
+            return {
+                baseKey: repeatInstance.baseKey,
+                repeatIndex: repeatInstance.repeatIndex,
+                richTextBlock: null,
+            };
+        }
+        return { baseKey: key, repeatIndex: null, richTextBlock: null };
+    }
+    function toNodeInfo(key, element, repeatIndex = null, richTextBlock = null) {
+        const baseKey = richTextBlock?.ownerKey ??
+            parseRepeatItemInstanceKey(key)?.baseKey ??
+            key;
+        const detail = routeState.detailProjections?.get(baseKey);
+        return {
+            key,
+            file: element.sourceFile,
+            component: element.componentName,
+            tag: element.tag,
+            structuralPath: element.identity.structuralPath,
+            sourceRange: element.sourceRange,
+            parentKey: element.parentKey ?? undefined,
+            isRepeatRegion: element.boundaryKind === "repeat-region" ||
+                repeatTemplateOwners.has(baseKey),
+            isBoundary: false,
+            importedFrom: element.importedFrom,
+            exportName: element.exportName,
+            isRepeatItemRoot: repeatIndex !== null || repeatRootOwners.has(baseKey),
+            repeatOwnerKey: repeatRootOwners.get(baseKey) ?? repeatTemplateOwners.get(baseKey),
+            contentModel: detail?.contentModel,
+            richTextBlock: richTextBlock
+                ? {
+                    field: richTextBlock.field,
+                    index: richTextBlock.index,
+                }
+                : undefined,
+            attributes: element.attributes?.map((attribute) => ({
+                name: attribute.name,
+                value: attribute.value,
+                source: attribute.source
+                    ? {
+                        expression: attribute.source.expression,
+                        base: attribute.source.base,
+                        path: attribute.source.path.map((segment) => ({ ...segment })),
+                    }
+                    : null,
+                resolvedValue: attribute.resolvedValue,
+            })),
+        };
+    }
+}
+/** Maps writeback-service internal error codes to protocol OperationErrorCode. */
+function mapInternalErrorCode(code) {
+    switch (code) {
+        case "stale-version":
+            return OperationErrorCode.VERSION_STALE;
+        case "capability-denied":
+            return OperationErrorCode.CAPABILITY_REJECTED;
+        case "route-not-found":
+            return OperationErrorCode.ROUTE_NOT_FOUND;
+        case "unsupported-operation":
+            return OperationErrorCode.UNSUPPORTED_OPERATION;
+        case "invalid-target":
+            return OperationErrorCode.INVALID_TARGET;
+        case "invalid-params":
+            return OperationErrorCode.INVALID_PARAMS;
+        case "locator-miss":
+            return OperationErrorCode.LOCATOR_FAILED;
+        case "ast-error":
+            return OperationErrorCode.AST_PARSE_ERROR;
+        case "writeback-failed":
+            return OperationErrorCode.WRITE_IO_ERROR;
+        case "rollback-failed":
+            return OperationErrorCode.ROLLBACK_FAILED;
+        default:
+            return OperationErrorCode.INTERNAL_ERROR;
+    }
+}
+function getErrorMessage(error) {
+    if (error instanceof Error && error.message) {
+        return error.message;
+    }
+    return String(error);
+}
+function getNextRouteLayoutCandidates(entryFile) {
+    const normalized = normalizeRouteFile(entryFile);
+    if (!nextRouteEntryPattern.test(normalized)) {
+        return [];
+    }
+    const appRoot = normalized.startsWith("src/app/") ? "src/app" : "app";
+    const routeDirectory = normalized.slice(0, normalized.lastIndexOf("/"));
+    const directories = [];
+    let current = routeDirectory;
+    while (current === appRoot || current.startsWith(`${appRoot}/`)) {
+        directories.unshift(current);
+        if (current === appRoot) {
+            break;
+        }
+        current = current.slice(0, current.lastIndexOf("/"));
+    }
+    return directories.flatMap((directory) => nextLayoutBasenames.map((basename) => `${directory}/${basename}`));
+}
+function normalizeRouteFile(file) {
+    return file.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function makeRepeatItemInstanceKey(baseKey, index) {
+    return `${baseKey}${repeatItemInstanceKeyMarker}${index}`;
+}
+function makeRichTextBlockKey(ownerKey, field, index) {
+    return `${ownerKey}${richTextBlockKeyMarker}${encodeURIComponent(field)}#${index}`;
+}
+function parseRichTextBlockKey(key) {
+    if (typeof key !== "string") {
+        return null;
+    }
+    const markerIndex = key.lastIndexOf(richTextBlockKeyMarker);
+    if (markerIndex < 0) {
+        return null;
+    }
+    const ownerKey = key.slice(0, markerIndex);
+    const rest = key.slice(markerIndex + richTextBlockKeyMarker.length);
+    const separatorIndex = rest.lastIndexOf("#");
+    if (!ownerKey || separatorIndex <= 0) {
+        return null;
+    }
+    const field = decodeURIComponent(rest.slice(0, separatorIndex));
+    const index = Number(rest.slice(separatorIndex + 1));
+    if (!field || !Number.isInteger(index) || index < 0) {
+        return null;
+    }
+    return { ownerKey, field, index };
+}
+function parseRepeatItemInstanceKey(key) {
+    if (typeof key !== "string") {
+        return null;
+    }
+    const markerIndex = key.lastIndexOf(repeatItemInstanceKeyMarker);
+    if (markerIndex < 0) {
+        return null;
+    }
+    const baseKey = key.slice(0, markerIndex);
+    const repeatIndex = Number(key.slice(markerIndex + repeatItemInstanceKeyMarker.length));
+    if (!baseKey || !Number.isInteger(repeatIndex) || repeatIndex < 0) {
+        return null;
+    }
+    return { baseKey, repeatIndex };
+}
+function getRepeatItemCount(detail) {
+    let count = 1;
+    for (const target of detail?.textTargets.values() ?? []) {
+        if (target?.kind !== "value-binding") {
+            continue;
+        }
+        if (target.sourceKind !== "repeat-template") {
+            continue;
+        }
+        count = Math.max(count, target.collectionIndexMap?.length ?? 0, target.collectionPathMap?.length ?? 0);
+    }
+    return count;
+}
+function getRichTextBlocks(value) {
+    if (typeof value === "string") {
+        return value === "" ? [] : value.split(/\n{2,}/);
+    }
+    if (Array.isArray(value)) {
+        return value.filter(isOperationValue);
+    }
+    if (isOperationObject(value) &&
+        Array.isArray(value.content) &&
+        value.content.every(isOperationValue)) {
+        return value.content;
+    }
+    return [];
+}
+function isOperationObject(value) {
+    return !Array.isArray(value) && typeof value === "object" && value !== null;
+}
+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" && value !== null) {
+        return Object.values(value).every(isOperationValue);
+    }
+    return false;
+}
+function getAttributeValue(element, field) {
+    const attribute = element.attributes?.find((candidate) => candidate.name === field);
+    if (!attribute) {
+        return undefined;
+    }
+    if (attribute.resolvedValue !== undefined) {
+        return attribute.resolvedValue;
+    }
+    return isOperationValue(attribute.value) ? attribute.value : undefined;
+}
+function cloneValuePath(path) {
+    return path?.map((segment) => ({ ...segment }));
+}
+function retargetRepeatTextWriteTarget(target, repeatIndex) {
+    if (repeatIndex === null ||
+        target?.kind !== "value-binding" ||
+        target.sourceKind !== "repeat-template") {
+        return target;
+    }
+    const mappedIndex = target.collectionIndexMap?.[repeatIndex] ?? repeatIndex;
+    const mappedPath = cloneValuePath(target.collectionPathMap?.[repeatIndex]) ??
+        cloneValuePath(target.locator?.path);
+    if (mappedPath) {
+        for (let index = mappedPath.length - 1; index >= 0; index -= 1) {
+            const segment = mappedPath[index];
+            if (segment.kind === "index") {
+                segment.index = mappedIndex;
+                break;
+            }
+        }
+    }
+    return {
+        ...target,
+        path: cloneValuePath(target.path),
+        locator: target.locator
+            ? {
+                ...target.locator,
+                path: mappedPath,
+            }
+            : target.locator,
+        collectionIndexMap: target.collectionIndexMap
+            ? [...target.collectionIndexMap]
+            : undefined,
+        collectionPathMap: target.collectionPathMap?.map((path) => cloneValuePath(path) ?? []),
+    };
+}
+function projectRepeatConcreteEntries(document, graph, detailProjections) {
+    const repeatItemRoots = new Set();
+    for (const region of graph.regions) {
+        if (region.kind !== "repeat-region") {
+            continue;
+        }
+        for (const childKey of region.childKeys) {
+            repeatItemRoots.add(childKey);
+        }
+    }
+    if (repeatItemRoots.size === 0) {
+        return document;
+    }
+    const entryByKey = new Map(document.entries.map((entry) => [
+        entry.key,
+        { ...entry, childKeys: [...entry.childKeys] },
+    ]));
+    const entries = [];
+    for (const originalEntry of document.entries) {
+        const entry = entryByKey.get(originalEntry.key) ?? {
+            ...originalEntry,
+            childKeys: [...originalEntry.childKeys],
+        };
+        entries.push(entry);
+        if (!repeatItemRoots.has(entry.key)) {
+            continue;
+        }
+        const repeatItemCount = getRepeatItemCount(detailProjections.get(entry.key));
+        if (repeatItemCount <= 1) {
+            continue;
+        }
+        const parentEntry = entry.parentKey
+            ? entryByKey.get(entry.parentKey)
+            : null;
+        const baseChildIndex = parentEntry?.childKeys.indexOf(entry.key) ?? -1;
+        const virtualKeys = [];
+        for (let index = 1; index < repeatItemCount; index += 1) {
+            const virtualKey = makeRepeatItemInstanceKey(entry.key, index);
+            virtualKeys.push(virtualKey);
+            entries.push({
+                ...entry,
+                key: virtualKey,
+                parentKey: entry.parentKey,
+                childKeys: [...entry.childKeys],
+            });
+        }
+        if (parentEntry && baseChildIndex >= 0) {
+            parentEntry.childKeys.splice(baseChildIndex + 1, 0, ...virtualKeys);
+        }
+    }
+    return {
+        ...document,
+        rootKeys: [...document.rootKeys],
+        entries,
+    };
+}
+function projectRichTextBlockEntries(document, graph, detailProjections) {
+    const entryByKey = new Map(document.entries.map((entry) => [
+        entry.key,
+        { ...entry, childKeys: [...entry.childKeys] },
+    ]));
+    const entries = [];
+    let hasRichTextBlocks = false;
+    for (const originalEntry of document.entries) {
+        const entry = entryByKey.get(originalEntry.key) ?? {
+            ...originalEntry,
+            childKeys: [...originalEntry.childKeys],
+        };
+        entries.push(entry);
+        const contentModel = detailProjections.get(entry.key)?.contentModel;
+        if (!contentModel?.operationBoundary.includes("remove-rich-text-block")) {
+            continue;
+        }
+        const element = graph.elements.get(entry.key);
+        if (!element) {
+            continue;
+        }
+        const blocks = getRichTextBlocks(getAttributeValue(element, contentModel.field));
+        if (blocks.length === 0) {
+            continue;
+        }
+        const blockKeys = blocks.map((_, index) => makeRichTextBlockKey(entry.key, contentModel.field, index));
+        entry.childKeys.push(...blockKeys);
+        for (let index = 0; index < blockKeys.length; index += 1) {
+            entries.push({
+                key: blockKeys[index],
+                tag: "rich-text-block",
+                label: `${contentModel.field} block ${index + 1}`,
+                parentKey: entry.key,
+                childKeys: [],
+                operationSummary: {
+                    canUpdateText: false,
+                    canInsertChild: false,
+                    canMove: true,
+                    canRemove: true,
+                },
+            });
+        }
+        hasRichTextBlocks = true;
+    }
+    return hasRichTextBlocks
+        ? { ...document, rootKeys: [...document.rootKeys], entries }
+        : document;
+}