@vcp-prod/site-edit-engine 0.3.14

package/dist/next-app-router-fs.d.ts

@@ -0,0 +1,2 @@
+import type { SiteEditNextRouteConfig } from "./next-app-router.js";
+export declare function scanNextAppRouterRoutes(projectRoot: string): SiteEditNextRouteConfig[];

package/dist/next-app-router.d.ts

@@ -0,0 +1,11 @@
+export type SiteEditNextRouteConfig = {
+    routeId: string;
+    entryFile: string;
+};
+export { scanNextAppRouterRoutes } from "./next-app-router-fs.js";
+export type SiteEditRouteSourceFile = {
+    path: string;
+};
+export declare function scanNextAppRouterRoutesFromFiles(files: SiteEditRouteSourceFile[]): SiteEditNextRouteConfig[];
+export declare function resolveNextAppRouteId(pathname: string | null | undefined, routes: SiteEditNextRouteConfig[], basePath?: string): string | undefined;
+export declare function normalizeNextRoutePath(pathname: string | null | undefined, basePath?: string): string;

package/dist/next-app-router.js

@@ -0,0 +1 @@
+import u from"node:fs";import a from"node:path";var R=/^page\.(?:tsx|ts|jsx|js|mjs|cjs)$/;function x(t){let r=P(t);return r?l(r).map(e=>({routeId:I(r,e),entryFile:p(a.relative(t,e))})).sort((e,n)=>e.routeId.localeCompare(n.routeId)):[]}function P(t){for(let r of["app","src/app"]){let e=a.join(t,r);if(u.existsSync(e)&&u.statSync(e).isDirectory())return e}return null}function l(t){let r=[];for(let e of u.readdirSync(t,{withFileTypes:!0})){let n=a.join(t,e.name);if(e.isDirectory()){if(e.name==="node_modules"||e.name.startsWith(".")||e.name.startsWith("_"))continue;r.push(...l(n));continue}e.isFile()&&R.test(e.name)&&r.push(n)}return r}function I(t,r){let e=p(a.relative(t,a.dirname(r))),n=e?e.split("/").map(W).filter(i=>!!i):[];return n.length===0?"/":`/${n.join("/")}`}function $(t){return t.startsWith("(")&&t.endsWith(")")}function W(t){return!t||t.startsWith("@")||t.startsWith("_")||$(t)?null:g(t)}function g(t){return t.replace(/^\((?:\.|\.\.|\.\.\.)\)/,"")}function p(t){return t.replace(/\\/g,"/")}var S=/^page\.(?:tsx|ts|jsx|js|mjs|cjs)$/,h=/^\[[^\]]+\]$/,d=/^\[\.\.\.[^\]]+\]$/,m=/^\[\[\.\.\.[^\]]+\]\]$/;function E(t){let r=t.map(n=>C(n.path)),e=A(r);return e?r.filter(n=>j(e,n)).map(n=>({routeId:v(e,n),entryFile:n})).sort((n,i)=>n.routeId.localeCompare(i.routeId)):[]}function G(t,r,e=""){let n=y(t,e);return r.some(o=>o.routeId===n)?n:[...r].sort((o,s)=>f(s.routeId)-f(o.routeId)||s.routeId.length-o.routeId.length||o.routeId.localeCompare(s.routeId)).find(o=>w(o.routeId).test(n))?.routeId}function y(t,r=""){let n=((t??"/").trim()||"/").split(/[?#]/,1)[0]||"/",i=n.startsWith("/")?n:`/${n}`,o=N(r),s=o&&(i===o||i.startsWith(`${o}/`))?i.slice(o.length)||"/":i,c=s.startsWith("/")?s:`/${s}`;return c==="/"?"/":c.replace(/\/+$/,"")}function A(t){return t.some(n=>n.startsWith("app/"))?"app":t.some(n=>n.startsWith("src/app/"))?"src/app":null}function j(t,r){if(!r.startsWith(`${t}/`))return!1;let e=r.slice(r.lastIndexOf("/")+1);return S.test(e)?r.slice(t.length+1,-e.length-1).split("/").filter(Boolean).every(n=>!n.startsWith("_")):!1}function v(t,r){let e=r.slice(t.length+1).split("/").slice(0,-1).map(z).filter(n=>!!n);return e.length===0?"/":`/${e.join("/")}`}function F(t){return t.startsWith("(")&&t.endsWith(")")}function z(t){return!t||t.startsWith("@")||t.startsWith("_")||F(t)?null:B(t)}function B(t){return t.replace(/^\((?:\.|\.\.|\.\.\.)\)/,"")}function w(t){if(t==="/")return/^\/$/;let r=t.split("/").filter(Boolean).map(e=>m.test(e)?"(?:/.*)?":d.test(e)?"/.+":h.test(e)?"/[^/]+":`/${_(e)}`).join("");return new RegExp(`^${r}$`)}function f(t){return t.split("/").filter(Boolean).reduce((r,e)=>m.test(e)?r+1:d.test(e)?r+2:h.test(e)?r+3:r+4,0)}function N(t){let r=t.trim();return!r||r==="/"?"":(r.startsWith("/")?r:`/${r}`).replace(/\/+$/,"")}function _(t){return t.replace(/[.*+?^${}()|[\]\\]/g,"\\$&")}function C(t){return t.replace(/\\/g,"/").replace(/^\.\//,"")}export{y as normalizeNextRoutePath,G as resolveNextAppRouteId,x as scanNextAppRouterRoutes,E as scanNextAppRouterRoutesFromFiles};

package/dist/preview-runtime.d.ts

@@ -0,0 +1,318 @@
+import type { SiteEditOperationCommandResult } from "@vcp-prod/contracts";
+import type { PreviewSiteEditEngineRuntime, PreviewSiteEditEngineRuntimeOptions } from "./types.js";
+export declare class PreviewFileSystemSiteEditEngineRuntime implements PreviewSiteEditEngineRuntime {
+    private readonly options;
+    private readonly engine;
+    private readonly listeners;
+    constructor(options: PreviewSiteEditEngineRuntimeOptions);
+    get status(): PreviewSiteEditEngineRuntime["status"];
+    registerRoute(routeId: string, entryFile: string): void;
+    unregisterRoute(routeId: string): void;
+    setActiveRoute(routeId: string): Promise<void>;
+    getDocument(routeId: string): {
+        ok: true;
+        data: {
+            siteId: string;
+            snapshotId: string;
+            routeId: string;
+            version: number;
+            rootKeys: string[];
+            entries: {
+                key: string;
+                tag: string;
+                label: string;
+                parentKey: string | null;
+                childKeys: string[];
+                operationSummary: {
+                    canUpdateText: boolean;
+                    canInsertChild: boolean;
+                    canMove: boolean;
+                    canRemove: boolean;
+                };
+            }[];
+        };
+    };
+    getObjectSummary(key: string, routeId?: string): {
+        readonly ok: true;
+        readonly data: {
+            key: string;
+            tag: string;
+            label: string;
+            capabilities: {
+                constraints: {
+                    kind: "component-boundary" | "repeat-region" | "conditional-region" | "opaque-region" | "void-element" | "read-only" | "cross-file-required" | "import-required";
+                    message: string;
+                }[];
+            };
+            isOpaque: boolean;
+            ancestors: {
+                key: string;
+                label: string;
+                tag: string;
+            }[];
+            sourceLocator?: {
+                sourceFile: string;
+                componentName: string;
+                openingElementRange: {
+                    startLine: number;
+                    startColumn: number;
+                    endLine: number;
+                    endColumn: number;
+                };
+                structuralPath: string;
+                textPreview?: string | undefined;
+            } | undefined;
+            provenanceChain?: {
+                editMode: "direct" | "proxy" | "upstream" | "readonly" | "unsupported";
+                diagnostics: {
+                    code: string;
+                    message: string;
+                }[];
+            } | undefined;
+        };
+    };
+    getObjectEditContext(key: string, routeId?: string): {
+        readonly ok: true;
+        readonly data: {
+            key: string;
+            componentName: string;
+            sourceFile: string;
+            capabilities: {
+                key: string;
+                canUpdateText: boolean;
+                canInsertChild: boolean;
+                canMove: boolean;
+                canRemove: boolean;
+                constraints: {
+                    kind: "component-boundary" | "repeat-region" | "conditional-region" | "opaque-region" | "void-element" | "read-only" | "cross-file-required" | "import-required";
+                    message: string;
+                }[];
+                editModes?: {
+                    updateText?: {
+                        mode: "direct" | "proxy" | "upstream" | "readonly" | "unsupported";
+                        reasonCode?: string | undefined;
+                    } | undefined;
+                    insertChild?: {
+                        mode: "direct" | "proxy" | "upstream" | "readonly" | "unsupported";
+                        reasonCode?: string | undefined;
+                    } | undefined;
+                    move?: {
+                        mode: "direct" | "proxy" | "upstream" | "readonly" | "unsupported";
+                        reasonCode?: string | undefined;
+                    } | undefined;
+                    remove?: {
+                        mode: "direct" | "proxy" | "upstream" | "readonly" | "unsupported";
+                        reasonCode?: string | undefined;
+                    } | undefined;
+                } | undefined;
+            };
+            writeTarget: {
+                kind: "jsx-node" | "component-proxy" | "value-binding" | "route-export";
+                file: string;
+                componentName: string;
+                isProxy: boolean;
+            };
+            textSegments: {
+                index: number;
+                value: string;
+                editable: boolean;
+                source: {
+                    kind: "literal" | "binding" | "imported-binding" | "repeat-template";
+                    file: string;
+                    expression: string;
+                    bindingName?: string | undefined;
+                    path?: (string | number)[] | undefined;
+                } | null;
+            }[];
+            boundaryKind: "component-boundary" | "repeat-region" | "conditional-region" | "fragment-region" | "opaque-region" | null;
+            children: {
+                key: string;
+                label: string;
+                tag: string;
+            }[];
+            siblings: {
+                key: string;
+                label: string;
+                tag: string;
+            }[];
+            effectiveWriteTarget?: {
+                kind: "jsx-node" | "route-export" | "value-path" | "external-entry";
+                isProxy: boolean;
+                file?: string | undefined;
+                displayPath?: string | undefined;
+                sourceType?: "api-field" | "cms-field" | "i18n-message" | "config-entry" | undefined;
+                sourceId?: string | undefined;
+            } | undefined;
+            provenanceChain?: {
+                finalSource: {
+                    kind: "api-field" | "cms-field" | "i18n-message" | "config-entry" | "binding" | "imported-binding" | "repeat-template" | "jsx-literal" | "component-prop" | "object-field" | "array-item" | "conditional-branch";
+                    file: string;
+                    displayPath: string;
+                    externalSource?: {
+                        sourceType: "api-field" | "cms-field" | "i18n-message" | "config-entry";
+                        sourceId: string;
+                        adapterId?: string | undefined;
+                    } | undefined;
+                } | null;
+                chain: {
+                    kind: "api-field" | "cms-field" | "i18n-message" | "config-entry" | "binding" | "imported-binding" | "repeat-template" | "jsx-literal" | "component-prop" | "object-field" | "array-item" | "conditional-branch";
+                    file: string;
+                    displayName: string;
+                    canEditHere: boolean;
+                }[];
+                confidence: "exact" | "safe-derived" | "partial" | "unknown";
+                editMode: "direct" | "proxy" | "upstream" | "readonly" | "unsupported";
+                diagnostics: {
+                    code: string;
+                    message: string;
+                }[];
+            } | undefined;
+            componentSemantic?: Record<string, unknown> | undefined;
+        };
+    };
+    getClassNameSource(key: string, routeId?: string): {
+        readonly ok: true;
+        readonly data: {
+            key: string;
+            routeId: string;
+            filePath: string;
+            componentName: string;
+            sourceKind: "missing" | "expression" | "stringLiteral";
+            attrRaw: string | null;
+            valueRaw: string | null;
+            attrRange: {
+                start: number;
+                end: number;
+                startLine?: number | undefined;
+                startColumn?: number | undefined;
+                endLine?: number | undefined;
+                endColumn?: number | undefined;
+            } | null;
+            valueRange: {
+                start: number;
+                end: number;
+                startLine?: number | undefined;
+                startColumn?: number | undefined;
+                endLine?: number | undefined;
+                endColumn?: number | undefined;
+            } | null;
+            openingElementRange: {
+                start: number;
+                end: number;
+                startLine?: number | undefined;
+                startColumn?: number | undefined;
+                endLine?: number | undefined;
+                endColumn?: number | undefined;
+            };
+            version: {
+                documentVersion: number;
+                contentHash: string;
+                parserVersion: string;
+            };
+            diagnostics: {
+                code: "missing-class-name" | "unsupported-attribute-name" | "source-locator-warning" | "invalid-new-attr" | "version-conflict" | "write-failed";
+                message: string;
+            }[];
+            styleContext?: {
+                revision: string;
+                entryCss: {
+                    path: string;
+                    content: string;
+                    hash?: string | undefined;
+                };
+                stylesheets: {
+                    path: string;
+                    content: string;
+                    hash?: string | undefined;
+                }[];
+                computedStyle?: Record<string, string> | undefined;
+            } | undefined;
+        };
+    };
+    refreshSourceForKey(key: string, routeId?: string): Promise<void>;
+    executeOperation(request: Parameters<PreviewSiteEditEngineRuntime["executeOperation"]>[0]): Promise<SiteEditOperationCommandResult>;
+    undo(): Promise<{
+        ok: false;
+        error: {
+            code: "NODE_NOT_FOUND" | "ROUTE_NOT_FOUND" | "CAPABILITY_REJECTED" | "CONSTRAINT_VIOLATED" | "INVALID_PARAMS" | "PLAN_FAILED" | "VERSION_STALE" | "AST_PARSE_ERROR" | "UNSUPPORTED_OPERATION" | "LOCATOR_FAILED" | "INVALID_TARGET" | "WRITE_IO_ERROR" | "CONCURRENT_MODIFIED" | "ROLLBACK_FAILED" | "INTERNAL_ERROR";
+            message: string;
+        };
+        data: {
+            requestId: string;
+            kind: "update-text" | "remove-node" | "insert-child" | "move-node" | "set-class-name-source" | "set-props" | "apply-style-draft";
+            target: {
+                kind: "node";
+                key: string;
+            } | {
+                kind: "route";
+                routeId: string;
+            };
+            resultVersion: number;
+        };
+    } | {
+        ok: true;
+        data: {
+            requestId: string;
+            kind: "update-text" | "remove-node" | "insert-child" | "move-node" | "set-class-name-source" | "set-props" | "apply-style-draft";
+            target: {
+                kind: "node";
+                key: string;
+            } | {
+                kind: "route";
+                routeId: string;
+            };
+            resultVersion: number;
+            affectedFiles?: string[] | undefined;
+            selectionRef?: {
+                key: string;
+                instanceIndex?: number | undefined;
+                instanceCount?: number | undefined;
+            } | undefined;
+        };
+        error?: undefined;
+    }>;
+    redo(): Promise<{
+        ok: false;
+        error: {
+            code: "NODE_NOT_FOUND" | "ROUTE_NOT_FOUND" | "CAPABILITY_REJECTED" | "CONSTRAINT_VIOLATED" | "INVALID_PARAMS" | "PLAN_FAILED" | "VERSION_STALE" | "AST_PARSE_ERROR" | "UNSUPPORTED_OPERATION" | "LOCATOR_FAILED" | "INVALID_TARGET" | "WRITE_IO_ERROR" | "CONCURRENT_MODIFIED" | "ROLLBACK_FAILED" | "INTERNAL_ERROR";
+            message: string;
+        };
+        data: {
+            requestId: string;
+            kind: "update-text" | "remove-node" | "insert-child" | "move-node" | "set-class-name-source" | "set-props" | "apply-style-draft";
+            target: {
+                kind: "node";
+                key: string;
+            } | {
+                kind: "route";
+                routeId: string;
+            };
+            resultVersion: number;
+        };
+    } | {
+        ok: true;
+        data: {
+            requestId: string;
+            kind: "update-text" | "remove-node" | "insert-child" | "move-node" | "set-class-name-source" | "set-props" | "apply-style-draft";
+            target: {
+                kind: "node";
+                key: string;
+            } | {
+                kind: "route";
+                routeId: string;
+            };
+            resultVersion: number;
+            affectedFiles?: string[] | undefined;
+            selectionRef?: {
+                key: string;
+                instanceIndex?: number | undefined;
+                instanceCount?: number | undefined;
+            } | undefined;
+        };
+        error?: undefined;
+    }>;
+    notifyFileChanged(file: string): void;
+    subscribe(listener: Parameters<PreviewSiteEditEngineRuntime["subscribe"]>[0]): () => void;
+    dispose(): void;
+}
+export declare function createPreviewSiteEditEngineRuntime(options: PreviewSiteEditEngineRuntimeOptions): PreviewSiteEditEngineRuntime;

package/dist/public-file-system.d.ts

@@ -0,0 +1,8 @@
+export interface SiteEditProjectFileSystem {
+    readFile(file: string): Promise<string>;
+    writeFile(file: string, content: string): Promise<void>;
+    deleteFile(file: string): Promise<void>;
+    exists(file: string): Promise<boolean>;
+    getVersion(file: string): number;
+    bumpVersion(file: string): number;
+}

package/dist/runtime-sync.d.ts

@@ -0,0 +1,97 @@
+import type { SiteEditOperationRequest, SiteEditOperationResult, SiteEditOperationType, SiteEditRenderDocument } from "@vcp-prod/contracts";
+export declare const DEFAULT_SITE_EDIT_RUNTIME_READY_TIMEOUT_MS = 1500;
+export declare const SITE_EDIT_RUNTIME_READY_POLL_INTERVAL_MS = 16;
+export declare const SITE_EDIT_RUNTIME_ATTRIBUTES: {
+    readonly key: "data-vcp-edit-key";
+    readonly parentKey: "data-vcp-edit-parent-key";
+    readonly movable: "data-vcp-movable";
+    readonly removable: "data-vcp-removable";
+    readonly flags: "data-vcp-flags";
+    readonly publicUiComponent: "data-vcp-ui-component";
+};
+export type SiteEditRuntimeAttributes = {
+    readonly [key in keyof typeof SITE_EDIT_RUNTIME_ATTRIBUTES]: string;
+};
+export type SiteEditRenderDocumentDiff = {
+    addedKeys: string[];
+    removedKeys: string[];
+    retainedKeys: string[];
+    changed_parentKeys: string[];
+    changedChildOrderKeys: string[];
+};
+export type SiteEditRuntimeElementSnapshot = {
+    key: string;
+    instance_index?: number;
+    instance_count?: number;
+    tagName: string;
+    sourceKind?: string;
+    componentName?: string;
+    sourceFile?: string;
+    parentKey?: string;
+    text_preview?: string;
+    attributes: Record<string, string>;
+    runtimeFlags: {
+        editable: boolean;
+        movable: boolean;
+        removable: boolean;
+        text_editable: boolean;
+        container: boolean;
+    };
+};
+export type SiteEditRuntimeElementRef = {
+    key: string;
+    instance_index?: number;
+    instance_count?: number;
+};
+export type SiteEditQueryDocument = Pick<Document, "querySelector"> & Partial<Pick<Document, "querySelectorAll">>;
+export type SiteEditRuntimeReadySuccess = {
+    ok: true;
+    version: number;
+    observed_keys: string[];
+    check: string;
+};
+export type SiteEditRuntimeReadyFailure = {
+    ok: false;
+    version: number;
+    reason: "missing-root" | "missing-target" | "removed-target-still-present" | "missing-added-key" | "missing-selected-key" | "text-mismatch" | "order-mismatch" | "unsupported-operation" | "timeout";
+    check: string;
+    message: string;
+    observed_keys?: string[];
+};
+export type SiteEditRuntimeReadyResult = SiteEditRuntimeReadySuccess | SiteEditRuntimeReadyFailure;
+export type SiteEditRuntimeReadyInput = {
+    routeId: string;
+    previous_document: SiteEditRenderDocument;
+    next_document: SiteEditRenderDocument;
+    request?: SiteEditOperationRequest;
+    result: SiteEditOperationResult;
+    selectedKey?: string | null;
+    timeout_ms?: number;
+};
+export declare function diffSiteEditRenderDocuments(previous_document: SiteEditRenderDocument, next_document: SiteEditRenderDocument): SiteEditRenderDocumentDiff;
+export declare function isSiteEditRuntimeSyncedOperation(kind: SiteEditOperationType): boolean;
+export declare class SiteEditRuntimeDomAdapter {
+    private readonly documentLike;
+    private readonly attributes;
+    constructor(documentLike?: SiteEditQueryDocument | null, attributes?: SiteEditRuntimeAttributes);
+    getKeyFromElement(element: Element): string | null;
+    findEditableElement(element: Element | null): Element | null;
+    findElementByKey(key: string, document?: SiteEditRenderDocument | null): Element | null;
+    findElementByRef(ref: SiteEditRuntimeElementRef, document?: SiteEditRenderDocument | null): Element | null;
+    snapshot(element: Element): SiteEditRuntimeElementSnapshot;
+    private resolveInstancePosition;
+    private getKeySelector;
+}
+export declare class SiteEditRuntimeReadyProbe {
+    private readonly dom;
+    constructor(documentLike: SiteEditQueryDocument, attributes?: SiteEditRuntimeAttributes);
+    probe(input: SiteEditRuntimeReadyInput, diff?: SiteEditRenderDocumentDiff): SiteEditRuntimeReadyResult;
+    private checkOperationProjection;
+    private checkTextProjection;
+    private checkMovedNodeProjection;
+    private checkGenericDiffProjection;
+    private checkAddedKeys;
+    private isChildOrderReady;
+}
+export declare function getSiteEditNodeTargetKey(input?: Pick<SiteEditOperationRequest | SiteEditOperationResult, "target">): string | null;
+export declare function hasSiteEditDocumentKey(document: SiteEditRenderDocument, key: string): boolean;

package/dist/runtime.d.ts

@@ -0,0 +1,222 @@
+import type { SiteEditEngineRuntime, SiteEditEngineRuntimeOptions, SiteEditPlanOperationResult } from "./types.js";
+export declare class SnapshotSiteEditEngineRuntime implements SiteEditEngineRuntime {
+    private readonly options;
+    private readonly engine;
+    private readonly fileSystem;
+    constructor(options: SiteEditEngineRuntimeOptions);
+    get status(): SiteEditEngineRuntime["status"];
+    setActiveRoute(routeId: string): Promise<void>;
+    getDocument(routeId: string): {
+        siteId: string;
+        snapshotId: string;
+        routeId: string;
+        version: number;
+        rootKeys: string[];
+        entries: {
+            key: string;
+            tag: string;
+            label: string;
+            parentKey: string | null;
+            childKeys: string[];
+            operationSummary: {
+                canUpdateText: boolean;
+                canInsertChild: boolean;
+                canMove: boolean;
+                canRemove: boolean;
+            };
+        }[];
+    };
+    getObjectSummary(key: string, routeId?: string): {
+        key: string;
+        tag: string;
+        label: string;
+        capabilities: {
+            constraints: {
+                kind: "component-boundary" | "repeat-region" | "conditional-region" | "opaque-region" | "void-element" | "read-only" | "cross-file-required" | "import-required";
+                message: string;
+            }[];
+        };
+        isOpaque: boolean;
+        ancestors: {
+            key: string;
+            label: string;
+            tag: string;
+        }[];
+        sourceLocator?: {
+            sourceFile: string;
+            componentName: string;
+            openingElementRange: {
+                startLine: number;
+                startColumn: number;
+                endLine: number;
+                endColumn: number;
+            };
+            structuralPath: string;
+            textPreview?: string | undefined;
+        } | undefined;
+        provenanceChain?: {
+            editMode: "direct" | "proxy" | "upstream" | "readonly" | "unsupported";
+            diagnostics: {
+                code: string;
+                message: string;
+            }[];
+        } | undefined;
+    };
+    getObjectEditContext(key: string, routeId?: string): {
+        key: string;
+        componentName: string;
+        sourceFile: string;
+        capabilities: {
+            key: string;
+            canUpdateText: boolean;
+            canInsertChild: boolean;
+            canMove: boolean;
+            canRemove: boolean;
+            constraints: {
+                kind: "component-boundary" | "repeat-region" | "conditional-region" | "opaque-region" | "void-element" | "read-only" | "cross-file-required" | "import-required";
+                message: string;
+            }[];
+            editModes?: {
+                updateText?: {
+                    mode: "direct" | "proxy" | "upstream" | "readonly" | "unsupported";
+                    reasonCode?: string | undefined;
+                } | undefined;
+                insertChild?: {
+                    mode: "direct" | "proxy" | "upstream" | "readonly" | "unsupported";
+                    reasonCode?: string | undefined;
+                } | undefined;
+                move?: {
+                    mode: "direct" | "proxy" | "upstream" | "readonly" | "unsupported";
+                    reasonCode?: string | undefined;
+                } | undefined;
+                remove?: {
+                    mode: "direct" | "proxy" | "upstream" | "readonly" | "unsupported";
+                    reasonCode?: string | undefined;
+                } | undefined;
+            } | undefined;
+        };
+        writeTarget: {
+            kind: "jsx-node" | "component-proxy" | "value-binding" | "route-export";
+            file: string;
+            componentName: string;
+            isProxy: boolean;
+        };
+        textSegments: {
+            index: number;
+            value: string;
+            editable: boolean;
+            source: {
+                kind: "literal" | "binding" | "imported-binding" | "repeat-template";
+                file: string;
+                expression: string;
+                bindingName?: string | undefined;
+                path?: (string | number)[] | undefined;
+            } | null;
+        }[];
+        boundaryKind: "component-boundary" | "repeat-region" | "conditional-region" | "fragment-region" | "opaque-region" | null;
+        children: {
+            key: string;
+            label: string;
+            tag: string;
+        }[];
+        siblings: {
+            key: string;
+            label: string;
+            tag: string;
+        }[];
+        effectiveWriteTarget?: {
+            kind: "jsx-node" | "route-export" | "value-path" | "external-entry";
+            isProxy: boolean;
+            file?: string | undefined;
+            displayPath?: string | undefined;
+            sourceType?: "api-field" | "cms-field" | "i18n-message" | "config-entry" | undefined;
+            sourceId?: string | undefined;
+        } | undefined;
+        provenanceChain?: {
+            finalSource: {
+                kind: "api-field" | "cms-field" | "i18n-message" | "config-entry" | "binding" | "imported-binding" | "repeat-template" | "jsx-literal" | "component-prop" | "object-field" | "array-item" | "conditional-branch";
+                file: string;
+                displayPath: string;
+                externalSource?: {
+                    sourceType: "api-field" | "cms-field" | "i18n-message" | "config-entry";
+                    sourceId: string;
+                    adapterId?: string | undefined;
+                } | undefined;
+            } | null;
+            chain: {
+                kind: "api-field" | "cms-field" | "i18n-message" | "config-entry" | "binding" | "imported-binding" | "repeat-template" | "jsx-literal" | "component-prop" | "object-field" | "array-item" | "conditional-branch";
+                file: string;
+                displayName: string;
+                canEditHere: boolean;
+            }[];
+            confidence: "exact" | "safe-derived" | "partial" | "unknown";
+            editMode: "direct" | "proxy" | "upstream" | "readonly" | "unsupported";
+            diagnostics: {
+                code: string;
+                message: string;
+            }[];
+        } | undefined;
+        componentSemantic?: Record<string, unknown> | undefined;
+    };
+    getClassNameSource(key: string, routeId?: string): {
+        key: string;
+        routeId: string;
+        filePath: string;
+        componentName: string;
+        sourceKind: "missing" | "expression" | "stringLiteral";
+        attrRaw: string | null;
+        valueRaw: string | null;
+        attrRange: {
+            start: number;
+            end: number;
+            startLine?: number | undefined;
+            startColumn?: number | undefined;
+            endLine?: number | undefined;
+            endColumn?: number | undefined;
+        } | null;
+        valueRange: {
+            start: number;
+            end: number;
+            startLine?: number | undefined;
+            startColumn?: number | undefined;
+            endLine?: number | undefined;
+            endColumn?: number | undefined;
+        } | null;
+        openingElementRange: {
+            start: number;
+            end: number;
+            startLine?: number | undefined;
+            startColumn?: number | undefined;
+            endLine?: number | undefined;
+            endColumn?: number | undefined;
+        };
+        version: {
+            documentVersion: number;
+            contentHash: string;
+            parserVersion: string;
+        };
+        diagnostics: {
+            code: "missing-class-name" | "unsupported-attribute-name" | "source-locator-warning" | "invalid-new-attr" | "version-conflict" | "write-failed";
+            message: string;
+        }[];
+        styleContext?: {
+            revision: string;
+            entryCss: {
+                path: string;
+                content: string;
+                hash?: string | undefined;
+            };
+            stylesheets: {
+                path: string;
+                content: string;
+                hash?: string | undefined;
+            }[];
+            computedStyle?: Record<string, string> | undefined;
+        } | undefined;
+    };
+    planOperation(request: Parameters<SiteEditEngineRuntime["planOperation"]>[0]): Promise<SiteEditPlanOperationResult>;
+    dispose(): void;
+    private createEngine;
+    private getChangedRouteIds;
+}
+export declare function createSiteEditEngineRuntime(options: SiteEditEngineRuntimeOptions): SiteEditEngineRuntime;