sela-core 0.1.0-alpha.1

package/dist/services/ASTSourceUpdater.js

@@ -0,0 +1,3514 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ASTSourceUpdater = void 0;
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const ts_morph_1 = require("ts-morph");
+const DryRunGuard_1 = require("../config/DryRunGuard");
+const PathScopeGuard_1 = require("../config/PathScopeGuard");
+const WorkspaceSnapshotService_1 = require("./WorkspaceSnapshotService");
+const SelaError_1 = require("../errors/SelaError");
+const HealingRegistry_1 = require("../engine/HealingRegistry");
+const ArgumentTypeAnalyzer_1 = require("./ArgumentTypeAnalyzer");
+const BlastRadiusAnalyzer_1 = require("./BlastRadiusAnalyzer");
+const DefinitionTracer_1 = require("./DefinitionTracer");
+const TemplateDiffService_1 = require("./TemplateDiffService");
+const InitializerUpdater_1 = require("./InitializerUpdater");
+const CrossFileHealer_1 = require("./CrossFileHealer");
+const HealingAdvisory_1 = require("./HealingAdvisory");
+const ChainValidator_1 = require("./ChainValidator");
+const TraceBackEngine_1 = require("./TraceBackEngine");
+const DecisionEngine_1 = require("./DecisionEngine");
+const MutationApplier_1 = require("./MutationApplier");
+const SelectorSanitizer_1 = require("./SelectorSanitizer");
+const logger_1 = require("../utils/logger");
+// ═══════════════════════════════════════════════════════════════════
+// FIX #1 - normalizeSelector utility
+// ═══════════════════════════════════════════════════════════════════
+function normalizeSelector(s) {
+    return s
+        .replace(/['"``]/g, "")
+        .replace(/\s*>>\s*internal:control=[^\s>]*/g, "")
+        .replace(/\s+/g, "")
+        .toLowerCase()
+        .trim();
+}
+// ═══════════════════════════════════════════════════════════════════
+// SCOPE DETECTION  ← THE CORE FIX
+//
+// Determines whether a CallExpression node lives inside the
+// VariableDeclaration initializer of a named variable.
+//
+// Returns the VariableDeclaration if the call is inside the initializer
+// of "varName", or null otherwise.
+//
+// Why this matters:
+//   const shadowBtn = shadowBtn.getByRole(…)   ← CIRCULAR - must be caught
+//   const shadowBtn = page.getByRole(…)        ← CORRECT
+//
+// We walk UP the ancestor chain from the call node looking for a
+// VariableDeclaration.  If we find one whose name matches varName AND
+// the call is inside its initializer subtree, we return it.
+// ═══════════════════════════════════════════════════════════════════
+function getEnclosingVariableDeclaration(node) {
+    let current = node.getParent();
+    while (current) {
+        if (ts_morph_1.Node.isVariableDeclaration(current)) {
+            return current;
+        }
+        // Stop climbing past statement boundaries - we only want the immediate
+        // enclosing declaration, not a declaration somewhere further up the tree.
+        if (ts_morph_1.Node.isBlock(current) ||
+            ts_morph_1.Node.isSourceFile(current) ||
+            ts_morph_1.Node.isArrowFunction(current) ||
+            ts_morph_1.Node.isFunctionDeclaration(current) ||
+            ts_morph_1.Node.isFunctionExpression(current)) {
+            return null;
+        }
+        current = current.getParent();
+    }
+    return null;
+}
+/**
+ * Returns true when `callNode` is inside the initializer of the variable
+ * named `varName`.  This is the exact condition that would produce a
+ * circular reference if we used `varName` as the receiver.
+ */
+function isInsideOwnInitializer(callNode, varName) {
+    const enclosingDecl = getEnclosingVariableDeclaration(callNode);
+    if (!enclosingDecl)
+        return false;
+    return enclosingDecl.getName() === varName;
+}
+/**
+ * Given a forced receiver (e.g. "shadowBtn") and the call node being
+ * replaced, decide the safe receiver to use:
+ *
+ *   • If the call is inside shadowBtn's own initializer → use rootReceiver
+ *     (typically "page") to avoid circular reference.
+ *   • Otherwise → use the forced receiver as-is.
+ *
+ * `rootReceiver` is the leftmost identifier in the original chain
+ * (resolved by climbToChainTop), which is always a stable root like "page".
+ */
+function resolveSafeReceiver(proposedReceiver, rootReceiver, callNode) {
+    if (isInsideOwnInitializer(callNode, proposedReceiver)) {
+        logger_1.logger.debug(`Circular reference prevented: ` +
+            `"${proposedReceiver}" is being initialized - ` +
+            `falling back to root receiver "${rootReceiver}"`);
+        return rootReceiver;
+    }
+    return proposedReceiver;
+}
+function parseInternalSelector(selector) {
+    const normalized = selector.replace(/\s*i\s*$/, "").trim();
+    const roleMatch = normalized.match(/^internal:role=([a-zA-Z]+)(?:\[name="([^"]+)"(?:i)?\])?/);
+    if (roleMatch) {
+        const result = {
+            method: "getByRole",
+            primaryArg: roleMatch[1],
+            isSemantic: true,
+        };
+        if (roleMatch[2])
+            result.options = { name: roleMatch[2] };
+        return result;
+    }
+    const labelMatch = normalized.match(/^internal:label="([^"]+)"$/);
+    if (labelMatch) {
+        return {
+            method: "getByLabel",
+            primaryArg: labelMatch[1],
+            isSemantic: true,
+        };
+    }
+    const labelNoQuote = normalized.match(/^internal:label=([^[]+)$/);
+    if (labelNoQuote) {
+        return {
+            method: "getByLabel",
+            primaryArg: labelNoQuote[1].trim(),
+            isSemantic: true,
+        };
+    }
+    const textMatch = normalized.match(/^internal:text="([^"]+)"(i)?$/);
+    if (textMatch) {
+        const result = {
+            method: "getByText",
+            primaryArg: textMatch[1],
+            isSemantic: true,
+        };
+        if (!textMatch[2])
+            result.options = { exact: true };
+        return result;
+    }
+    const placeholderMatch = normalized.match(/^internal:attr=\[placeholder="([^"]+)"\]$/);
+    if (placeholderMatch) {
+        return {
+            method: "getByPlaceholder",
+            primaryArg: placeholderMatch[1],
+            isSemantic: true,
+        };
+    }
+    const altMatch = normalized.match(/^internal:attr=\[alt="([^"]+)"\]$/);
+    if (altMatch) {
+        return {
+            method: "getByAltText",
+            primaryArg: altMatch[1],
+            isSemantic: true,
+        };
+    }
+    const titleMatch = normalized.match(/^internal:attr=\[title="([^"]+)"\]$/);
+    if (titleMatch) {
+        return {
+            method: "getByTitle",
+            primaryArg: titleMatch[1],
+            isSemantic: true,
+        };
+    }
+    const testIdMatch = normalized.match(/^\[data-testid="([^"]+)"\]$/);
+    if (testIdMatch) {
+        return {
+            method: "getByTestId",
+            primaryArg: testIdMatch[1],
+            isSemantic: true,
+        };
+    }
+    return { method: "locator", primaryArg: selector, isSemantic: false };
+}
+function buildCallText(receiver, sem) {
+    const safeArg = sem.primaryArg.replace(/"/g, "'");
+    switch (sem.method) {
+        case "getByRole":
+            if (sem.options?.name) {
+                return `${receiver}.getByRole("${safeArg}", { name: "${sem.options.name}" })`;
+            }
+            return `${receiver}.getByRole("${safeArg}")`;
+        case "getByLabel":
+            return `${receiver}.getByLabel("${safeArg}")`;
+        case "getByPlaceholder":
+            return `${receiver}.getByPlaceholder("${safeArg}")`;
+        case "getByTestId":
+            return `${receiver}.getByTestId("${safeArg}")`;
+        case "getByText":
+            if (sem.options?.exact)
+                return `${receiver}.getByText("${safeArg}", { exact: true })`;
+            return `${receiver}.getByText("${safeArg}")`;
+        case "getByAltText":
+            return `${receiver}.getByAltText("${safeArg}")`;
+        case "getByTitle":
+            return `${receiver}.getByTitle("${safeArg}")`;
+        case "locator":
+        default:
+            return `${receiver}.locator("${sem.primaryArg.replace(/"/g, "'")}")`;
+    }
+}
+function extractSemanticFromCall(callExpr) {
+    const expr = callExpr.getExpression();
+    if (!ts_morph_1.Node.isPropertyAccessExpression(expr))
+        return null;
+    const method = expr.getName();
+    if (!ALL_SELECTOR_METHODS.has(method))
+        return null;
+    const args = callExpr.getArguments();
+    if (args.length === 0)
+        return null;
+    const firstArg = args[0];
+    let primaryArg = null;
+    if (ts_morph_1.Node.isStringLiteral(firstArg)) {
+        primaryArg = firstArg.getLiteralValue();
+    }
+    else if (ts_morph_1.Node.isNoSubstitutionTemplateLiteral(firstArg)) {
+        primaryArg = firstArg.getLiteralValue();
+    }
+    if (primaryArg === null)
+        return null;
+    const options = {};
+    if (args.length >= 2 && ts_morph_1.Node.isObjectLiteralExpression(args[1])) {
+        for (const prop of args[1].getProperties()) {
+            if (ts_morph_1.Node.isPropertyAssignment(prop)) {
+                const key = prop.getName();
+                const val = prop.getInitializer();
+                if (val && ts_morph_1.Node.isStringLiteral(val))
+                    options[key] = val.getLiteralValue();
+                else if (val && ts_morph_1.Node.isTrueLiteral(val))
+                    options[key] = true;
+                else if (val && ts_morph_1.Node.isFalseLiteral(val))
+                    options[key] = false;
+            }
+        }
+    }
+    const isSemantic = method !== "locator" && method !== "frameLocator";
+    return {
+        method,
+        primaryArg,
+        options: Object.keys(options).length > 0 ? options : undefined,
+        isSemantic,
+    };
+}
+function semanticMatch(callSemantic, oldSelector, allowRelated = false) {
+    const leaf = oldSelector.split(">>").pop().trim();
+    const normalizedLeaf = leaf.replace(/\s*i\s*$/, "").trim();
+    const oldSem = parseInternalSelector(normalizedLeaf);
+    if (callSemantic.method === "getByRole" && oldSem.method === "getByRole") {
+        if (!isRoleCompatible(callSemantic.primaryArg, oldSem.primaryArg))
+            return false;
+    }
+    if (callSemantic.method === oldSem.method &&
+        callSemantic.primaryArg === oldSem.primaryArg) {
+        return true;
+    }
+    if (allowRelated) {
+        const textualMethods = new Set([
+            "getByLabel",
+            "getByPlaceholder",
+            "getByText",
+            "getByAltText",
+            "getByTitle",
+        ]);
+        if (textualMethods.has(callSemantic.method) &&
+            textualMethods.has(oldSem.method)) {
+            const a = callSemantic.primaryArg.toLowerCase();
+            const b = oldSem.primaryArg.toLowerCase();
+            if (a === b || a.includes(b) || b.includes(a))
+                return true;
+        }
+    }
+    if (oldSem.isSemantic && callSemantic.isSemantic) {
+        const oldLeafArg = oldSem.primaryArg.toLowerCase();
+        const callArg = callSemantic.primaryArg.toLowerCase();
+        if (oldLeafArg === callArg)
+            return true;
+        if (callArg.includes(oldLeafArg) || oldLeafArg.includes(callArg))
+            return true;
+    }
+    if (allowRelated) {
+        const textualMethods = new Set([
+            "getByLabel",
+            "getByPlaceholder",
+            "getByText",
+            "getByAltText",
+            "getByTitle",
+        ]);
+        if (textualMethods.has(callSemantic.method) &&
+            textualMethods.has(oldSem.method) &&
+            callSemantic.method !== oldSem.method) {
+            const lower_a = callSemantic.primaryArg.toLowerCase();
+            const lower_b = oldSem.primaryArg.toLowerCase();
+            const CONCEPT_DICTIONARY = new Map([
+                ["email", new Set(["email", "e-mail", "mail", "inbox", "@"])],
+                [
+                    "password",
+                    new Set(["password", "passwd", "passcode", "pin", "secret"]),
+                ],
+                [
+                    "username",
+                    new Set(["username", "user name", "login", "account name", "handle"]),
+                ],
+                ["phone", new Set(["phone", "mobile", "cell", "tel", "telephone"])],
+                ["address", new Set(["address", "street", "city", "zip", "postal"])],
+                ["name", new Set(["first name", "last name", "full name", "surname"])],
+                ["search", new Set(["search", "query", "find", "filter", "keyword"])],
+                [
+                    "submit",
+                    new Set(["submit", "send", "confirm", "execute", "proceed", "save"]),
+                ],
+                ["cancel", new Set(["cancel", "dismiss", "close", "abort", "back"])],
+                ["date", new Set(["date", "day", "month", "year", "time"])],
+            ]);
+            for (const [, keywords] of CONCEPT_DICTIONARY) {
+                let aMatch = false, bMatch = false;
+                for (const kw of keywords) {
+                    if (lower_a.includes(kw))
+                        aMatch = true;
+                    if (lower_b.includes(kw))
+                        bMatch = true;
+                }
+                if (aMatch && bMatch)
+                    return true;
+            }
+        }
+    }
+    const oldLeaf = oldSelector.split(">>").pop().trim();
+    const oldLeafSem = parseInternalSelector(oldLeaf);
+    if (callSemantic.method === oldLeafSem.method &&
+        callSemantic.primaryArg === oldLeafSem.primaryArg) {
+        return true;
+    }
+    return false;
+}
+function absoluteNodeMatch(callExpr, oldSelector) {
+    const callSem = extractSemanticFromCall(callExpr);
+    if (!callSem)
+        return false;
+    const leaf = oldSelector.split(">>").pop().trim();
+    const normalizedLeaf = leaf.replace(/\s*i\s*$/, "").trim();
+    const oldSem = parseInternalSelector(normalizedLeaf);
+    if (callSem.method === oldSem.method &&
+        callSem.primaryArg === oldSem.primaryArg) {
+        return true;
+    }
+    if (callSem.method === oldSem.method && oldSem.method !== "locator") {
+        const a = normalize(callSem.primaryArg);
+        const b = normalize(oldSem.primaryArg);
+        if (a === b || a.includes(b) || b.includes(a))
+            return true;
+    }
+    if (callSem.method !== "locator" &&
+        callSem.method !== "frameLocator" &&
+        oldSem.method !== "locator" &&
+        oldSem.method !== "frameLocator") {
+        const a = normalize(callSem.primaryArg);
+        const b = normalize(oldSem.primaryArg);
+        const minLen = Math.min(a.length, b.length);
+        if (minLen >= 4 && (a.includes(b) || b.includes(a)))
+            return true;
+    }
+    if (oldSem.method === "locator" && callSem.method !== "locator") {
+        const rawValueMatch = normalizedLeaf.match(/"([^"]{3,})"/);
+        if (rawValueMatch) {
+            const rawValue = normalize(rawValueMatch[1]);
+            const astArg = normalize(callSem.primaryArg);
+            if (astArg.includes(rawValue) || rawValue.includes(astArg))
+                return true;
+        }
+    }
+    return false;
+}
+function normalize(s) {
+    return s
+        .toLowerCase()
+        .replace(/^[-_\s]+|[-_\s]+$/g, "")
+        .trim();
+}
+function isRoleCompatible(roleA, roleB) {
+    const interactive = new Set([
+        "button",
+        "textbox",
+        "checkbox",
+        "radio",
+        "combobox",
+        "listbox",
+        "link",
+        "menuitem",
+    ]);
+    const structural = new Set([
+        "heading",
+        "banner",
+        "main",
+        "navigation",
+        "complementary",
+        "contentinfo",
+    ]);
+    if (interactive.has(roleA.toLowerCase()) &&
+        structural.has(roleB.toLowerCase()))
+        return false;
+    if (structural.has(roleA.toLowerCase()) &&
+        interactive.has(roleB.toLowerCase()))
+        return false;
+    return true;
+}
+// ═══════════════════════════════════════════════════════════════════
+// METHOD SETS
+// ═══════════════════════════════════════════════════════════════════
+const SEMANTIC_METHODS = new Set([
+    "getByRole",
+    "getByLabel",
+    "getByText",
+    "getByTestId",
+    "getByPlaceholder",
+    "getByAltText",
+    "getByTitle",
+]);
+const ALL_SELECTOR_METHODS = new Set([
+    "locator",
+    "frameLocator",
+    ...SEMANTIC_METHODS,
+]);
+const CHAIN_CONTINUATION_METHODS = new Set([
+    ...ALL_SELECTOR_METHODS,
+    "filter",
+    "first",
+    "last",
+    "nth",
+]);
+// ═══════════════════════════════════════════════════════════════════
+// MethodMapper
+// ═══════════════════════════════════════════════════════════════════
+class MethodMapper {
+    static build(receiver, seg) {
+        const q = (s) => `"${s.replace(/"/g, "'")}"`;
+        switch (seg.type) {
+            case "locator": {
+                const opts = MethodMapper.buildLocatorOptions(seg);
+                return opts
+                    ? `${receiver}.locator(${q(seg.selector)}, { ${opts} })`
+                    : `${receiver}.locator(${q(seg.selector)})`;
+            }
+            case "frameLocator":
+                return `${receiver}.frameLocator(${q(seg.selector)})`;
+            case "getByRole": {
+                const opts = [];
+                if (seg.name !== undefined && seg.name !== "")
+                    opts.push(`name: ${q(seg.name)}`);
+                if (seg.exact !== undefined)
+                    opts.push(`exact: ${seg.exact}`);
+                if (seg.level !== undefined)
+                    opts.push(`level: ${seg.level}`);
+                if (seg.checked !== undefined)
+                    opts.push(`checked: ${seg.checked}`);
+                if (seg.pressed !== undefined)
+                    opts.push(`pressed: ${seg.pressed}`);
+                if (seg.expanded !== undefined)
+                    opts.push(`expanded: ${seg.expanded}`);
+                if (seg.selected !== undefined)
+                    opts.push(`selected: ${seg.selected}`);
+                if (seg.disabled !== undefined)
+                    opts.push(`disabled: ${seg.disabled}`);
+                const optStr = opts.length > 0 ? `, { ${opts.join(", ")} }` : "";
+                return `${receiver}.getByRole(${q(seg.role)}${optStr})`;
+            }
+            case "getByLabel":
+                return `${receiver}.getByLabel(${q(seg.text)}${seg.exact !== undefined ? `, { exact: ${seg.exact} }` : ""})`;
+            case "getByText":
+                return `${receiver}.getByText(${q(seg.text)}${seg.exact !== undefined ? `, { exact: ${seg.exact} }` : ""})`;
+            case "getByPlaceholder":
+                return `${receiver}.getByPlaceholder(${q(seg.text)}${seg.exact !== undefined ? `, { exact: ${seg.exact} }` : ""})`;
+            case "getByAltText":
+                return `${receiver}.getByAltText(${q(seg.text)}${seg.exact !== undefined ? `, { exact: ${seg.exact} }` : ""})`;
+            case "getByTitle":
+                return `${receiver}.getByTitle(${q(seg.text)}${seg.exact !== undefined ? `, { exact: ${seg.exact} }` : ""})`;
+            case "getByTestId":
+                return `${receiver}.getByTestId(${q(seg.testId)})`;
+            case "filter":
+                return `${receiver}.filter(${MethodMapper.buildFilterOptions(seg)})`;
+            case "first":
+                return `${receiver}.first()`;
+            case "last":
+                return `${receiver}.last()`;
+            case "nth":
+                return `${receiver}.nth(${seg.index})`;
+            default:
+                logger_1.logger.warn(`Unknown segment type: ${seg.type}`);
+                return null;
+        }
+    }
+    static buildFilterOptions(seg) {
+        const opts = [];
+        if (seg.hasText !== undefined) {
+            const ht = seg.hasText;
+            if (typeof ht === "string")
+                opts.push(`hasText: "${ht.replace(/"/g, "'")}"`);
+            else if (ht instanceof RegExp)
+                opts.push(`hasText: ${ht.toString()}`);
+        }
+        if (seg.hasNotText !== undefined) {
+            const hnt = seg.hasNotText;
+            if (typeof hnt === "string")
+                opts.push(`hasNotText: "${hnt.replace(/"/g, "'")}"`);
+        }
+        return opts.length === 0 ? "{}" : `{ ${opts.join(", ")} }`;
+    }
+    static buildLocatorOptions(seg) {
+        const opts = [];
+        if (seg.hasText !== undefined) {
+            opts.push(`hasText: "${seg.hasText.replace(/"/g, "'")}"`);
+        }
+        if (seg.hasNotText !== undefined) {
+            opts.push(`hasNotText: "${seg.hasNotText.replace(/"/g, "'")}"`);
+        }
+        return opts.length > 0 ? opts.join(", ") : null;
+    }
+    static buildChain(receiver, segments, originalText) {
+        if (segments.length === 0)
+            return null;
+        const baseIndent = MethodMapper.detectIndent(originalText);
+        const innerIndent = baseIndent + "  ";
+        const calls = [];
+        let currentReceiver = receiver;
+        for (const seg of segments) {
+            const callText = MethodMapper.build(currentReceiver, seg);
+            if (callText === null) {
+                logger_1.logger.warn(`Cannot build segment type "${seg.type}" - aborting chain`);
+                return null;
+            }
+            const methodPart = callText.slice(currentReceiver.length);
+            calls.push(methodPart);
+            currentReceiver = callText;
+        }
+        if (segments.length >= 3) {
+            return [receiver, ...calls.map((c) => `${innerIndent}${c}`)].join("\n");
+        }
+        return receiver + calls.join("");
+    }
+    static detectIndent(text) {
+        if (!text)
+            return "";
+        const match = text.match(/^(\s+)/);
+        return match ? match[1] : "";
+    }
+}
+// ═══════════════════════════════════════════════════════════════════
+// CHAIN DEDUPLICATION & VARIABLE RESOLUTION ENGINE
+// ═══════════════════════════════════════════════════════════════════
+function normalizeSegmentSelector(s) {
+    return normalizeSelector(s);
+}
+function segmentsStructurallyEqual(ctx, ai) {
+    if (ctx.type !== ai.type)
+        return false;
+    if ("selector" in ctx && "selector" in ai) {
+        const a = normalizeSelector(ctx.selector);
+        const b = normalizeSelector(ai.selector);
+        return a === b || a.includes(b) || b.includes(a);
+    }
+    if ("text" in ctx && "text" in ai) {
+        const a = normalizeSelector(ctx.text);
+        const b = normalizeSelector(ai.text);
+        return a === b;
+    }
+    if ("role" in ctx && "role" in ai) {
+        return ctx.role === ai.role;
+    }
+    if ("testId" in ctx && "testId" in ai) {
+        return (normalizeSelector(ctx.testId) ===
+            normalizeSelector(ai.testId));
+    }
+    return false;
+}
+function deduplicateChainSegments(aiSegments, contextSegments) {
+    if (contextSegments.length === 0)
+        return { deduped: aiSegments, stripped: 0 };
+    let overlap = 0;
+    const maxCheck = Math.min(contextSegments.length, aiSegments.length);
+    for (let i = 0; i < maxCheck; i++) {
+        if (segmentsStructurallyEqual(contextSegments[i], aiSegments[i])) {
+            overlap++;
+        }
+        else {
+            break;
+        }
+    }
+    if (overlap === 0)
+        return { deduped: aiSegments, stripped: 0 };
+    logger_1.logger.debug(`Stripping ${overlap}/${contextSegments.length} duplicate leading ` +
+        `segment(s) - context already encodes them`);
+    return { deduped: aiSegments.slice(overlap), stripped: overlap };
+}
+const PAGE_ROOT_NAMES = new Set([
+    "page",
+    "context",
+    "browser",
+    "playwright",
+    "request",
+]);
+function semToSegment(sem) {
+    switch (sem.method) {
+        case "frameLocator":
+            return { type: "frameLocator", selector: sem.primaryArg };
+        case "locator":
+            return { type: "locator", selector: sem.primaryArg };
+        case "getByText":
+            return {
+                type: "getByText",
+                text: sem.primaryArg,
+                exact: sem.options?.exact,
+            };
+        case "getByLabel":
+            return {
+                type: "getByLabel",
+                text: sem.primaryArg,
+                exact: sem.options?.exact,
+            };
+        case "getByPlaceholder":
+            return { type: "getByPlaceholder", text: sem.primaryArg };
+        case "getByRole":
+            return {
+                type: "getByRole",
+                role: sem.primaryArg,
+                name: sem.options?.name,
+            };
+        case "getByTestId":
+            return { type: "getByTestId", testId: sem.primaryArg };
+        case "getByAltText":
+            return { type: "getByAltText", text: sem.primaryArg };
+        case "getByTitle":
+            return { type: "getByTitle", text: sem.primaryArg };
+        default:
+            return null;
+    }
+}
+function resolveVariableToSegments(sourceFile, varName, beforeLine, depth = 0) {
+    const empty = {
+        segments: [],
+        rootName: varName,
+        varName,
+        bestReceiverVar: null,
+    };
+    if (depth > 10)
+        return empty;
+    if (PAGE_ROOT_NAMES.has(varName)) {
+        return { segments: [], rootName: varName, varName, bestReceiverVar: null };
+    }
+    const decl = jumpToDefinitionInFile(sourceFile, varName, beforeLine + 5);
+    if (!decl)
+        return empty;
+    const init = decl.getInitializer();
+    if (!init || !ts_morph_1.Node.isCallExpression(init))
+        return empty;
+    const calls = collectChainCalls(init);
+    calls.reverse();
+    const segments = [];
+    let rootName = varName;
+    let receiverVarForRecursion = null;
+    for (let ci = 0; ci < calls.length; ci++) {
+        const call = calls[ci];
+        const sem = extractSemanticFromCall(call);
+        if (!sem)
+            continue;
+        if (ci === 0) {
+            const expr = call.getExpression();
+            const receiverNode = ts_morph_1.Node.isPropertyAccessExpression(expr)
+                ? expr.getExpression()
+                : null;
+            const receiverName = receiverNode
+                ?.getText()
+                .replace(/^await\s+/, "")
+                .trim() ?? null;
+            if (receiverName && !PAGE_ROOT_NAMES.has(receiverName)) {
+                receiverVarForRecursion = receiverName;
+                const parentRes = resolveVariableToSegments(sourceFile, receiverName, decl.getStartLineNumber(), depth + 1);
+                segments.push(...parentRes.segments);
+                rootName = parentRes.rootName;
+            }
+            else if (receiverName) {
+                rootName = receiverName;
+            }
+        }
+        const seg = semToSegment(sem);
+        if (seg)
+            segments.push(seg);
+    }
+    logger_1.logger.debug(`Variable: ${varName}, Resolved Segments: ${JSON.stringify(segments)}`);
+    logger_1.logger.debug(`'${varName}' → root:'${rootName}' ` +
+        `via:'${receiverVarForRecursion ?? "direct"}' ` +
+        `segs:[${segments.map((s) => s.type).join(",")}]`);
+    return {
+        segments,
+        rootName,
+        varName,
+        bestReceiverVar: receiverVarForRecursion,
+    };
+}
+// ═══════════════════════════════════════════════════════════════════
+// SHARED PERSISTENCE HOOK
+//
+// Module-level write gate shared between `ASTSourceUpdater` and the
+// internal `NodeTransformationStrategy`. Centralises three concerns
+// every `saveSync` call site needs:
+//   1. `DryRunGuard.active()` short-circuit - keeps the mutation in
+//      memory but suppresses the on-disk write under SELA_DRY_RUN.
+//   2. `sharedWorkspaceSnapshot.preWrite()` - captures `contentBefore`
+//      so the Clean-Room ledger / Local DX rollback can rewind.
+//   3. `sharedWorkspaceSnapshot.postWrite()` - refreshes `contentAfter`
+//      so `getMutatedSnapshots()` (driving the pending-prompts ledger
+//      and the interactive CLI prompt) sees the new disk state.
+//
+// Strategies do NOT receive the persistence service via DI - they call
+// this helper directly. Same singleton, zero coupling, one code path.
+// ═══════════════════════════════════════════════════════════════════
+function persistSourceFile(sourceFile) {
+    // Safe path scoping (T1): block mutations of files outside allowedPaths.
+    if (!PathScopeGuard_1.PathScopeGuard.enforce(sourceFile.getFilePath())) {
+        return;
+    }
+    if (DryRunGuard_1.DryRunGuard.active()) {
+        DryRunGuard_1.DryRunGuard.logSkippedWrite("saveSync", sourceFile.getFilePath());
+        return;
+    }
+    const fp = sourceFile.getFilePath();
+    WorkspaceSnapshotService_1.sharedWorkspaceSnapshot.preWrite(fp);
+    sourceFile.saveSync();
+    WorkspaceSnapshotService_1.sharedWorkspaceSnapshot.postWrite(fp);
+}
+// ═══════════════════════════════════════════════════════════════════
+// NODE TRANSFORMATION STRATEGY - Scope-Aware, Zero-Redundancy
+// ═══════════════════════════════════════════════════════════════════
+class NodeTransformationStrategy {
+    chainValidator;
+    constructor(chainValidator) {
+        this.chainValidator = chainValidator;
+    }
+    replaceLocatorNode(sourceFile, caller, oldSelector, newSegments, originalChainHint, suspectIdentifier, searchWindow) {
+        logger_1.logger.debug(`Absolute node search for: "${oldSelector}"`);
+        // ── Phase A: Variable-Aware Strip-and-Force ─────────────────────
+        //
+        // Two-pass deduplication, now with scope-aware receiver selection.
+        // After dedup we defer the actual receiver safety check to Phase E,
+        // where we have the concrete call node and can call resolveSafeReceiver().
+        let workingSegments = newSegments;
+        let forcedReceiver = null;
+        // Track the AST root (page / root var) so Phase E can fall back to it
+        // if the proposed receiver turns out to be the variable being initialized.
+        let resolvedRootReceiver = "page";
+        const tryDedupAgainst = (varName, label) => {
+            if (!varName || PAGE_ROOT_NAMES.has(varName))
+                return null;
+            const resolution = resolveVariableToSegments(sourceFile, varName, caller.line);
+            if (resolution.segments.length === 0)
+                return null;
+            logger_1.logger.debug(`(${label}) AI Segments: ${JSON.stringify(workingSegments)} ` +
+                `vs Resolved Var Segments for '${varName}': ${JSON.stringify(resolution.segments)}`);
+            const { deduped, stripped } = deduplicateChainSegments(workingSegments, resolution.segments);
+            if (stripped === 0)
+                return null;
+            // Determine the best intermediate receiver
+            let receiver = varName;
+            if (resolution.bestReceiverVar) {
+                const intermRes = resolveVariableToSegments(sourceFile, resolution.bestReceiverVar, caller.line);
+                const { stripped: interStripped } = deduplicateChainSegments(newSegments, intermRes.segments);
+                if (interStripped === stripped) {
+                    receiver = resolution.bestReceiverVar;
+                }
+            }
+            logger_1.logger.debug(`Strip-and-Force (${label}): stripped=${stripped}, ` +
+                `receiver="${receiver}" ` +
+                `remaining=[${deduped.map((s) => s.type).join(",")}]`);
+            return { receiver, deduped, rootName: resolution.rootName };
+        };
+        // Pass 1: suspectIdentifier
+        if (suspectIdentifier && !PAGE_ROOT_NAMES.has(suspectIdentifier)) {
+            const r = tryDedupAgainst(suspectIdentifier, "suspectId");
+            if (r) {
+                forcedReceiver = r.receiver;
+                workingSegments = r.deduped;
+                resolvedRootReceiver = r.rootName;
+            }
+        }
+        // Pass 2: AST root receiver (catches cases where astRoot != suspectIdentifier)
+        let discoveredAstRoot = null;
+        if (!forcedReceiver) {
+            discoveredAstRoot = this.discoverAstRootReceiver(sourceFile, oldSelector, searchWindow, suspectIdentifier, caller.line);
+            if (discoveredAstRoot && !PAGE_ROOT_NAMES.has(discoveredAstRoot)) {
+                const r = tryDedupAgainst(discoveredAstRoot, "astRoot");
+                if (r) {
+                    forcedReceiver = r.receiver;
+                    workingSegments = r.deduped;
+                    resolvedRootReceiver = r.rootName;
+                }
+            }
+        }
+        // ── Pass 3: Type-Collision Guard ─────────────────────────────────
+        // When AI's first segment TYPE matches the receiver variable's defining type
+        // but with a different selector, the AI is replacing the receiver context.
+        // Strategy: update the receiver variable's definition, then use remaining
+        // segments with the receiver var - preserving developer's variable structure.
+        if (!forcedReceiver &&
+            discoveredAstRoot &&
+            !PAGE_ROOT_NAMES.has(discoveredAstRoot)) {
+            const typeCheckRes = resolveVariableToSegments(sourceFile, discoveredAstRoot, caller.line);
+            if (typeCheckRes.segments.length > 0 && workingSegments.length > 0) {
+                const receiverDefType = typeCheckRes.segments[typeCheckRes.segments.length - 1].type;
+                const aiLeadType = workingSegments[0].type;
+                if (receiverDefType === aiLeadType) {
+                    const pageRoot = typeCheckRes.rootName || "page";
+                    const newReceiverSelector = workingSegments[0].selector;
+                    const remainingSegments = workingSegments.slice(1);
+                    logger_1.logger.debug(`TypeCollision: "${discoveredAstRoot}" IS ${receiverDefType}, ` +
+                        `AI leads with ${aiLeadType}`);
+                    if (newReceiverSelector && remainingSegments.length > 0) {
+                        const defUpdated = this.updateReceiverDefinition(sourceFile, discoveredAstRoot, receiverDefType, newReceiverSelector, caller.line);
+                        if (defUpdated) {
+                            logger_1.logger.debug(`TypeCollision: updated "${discoveredAstRoot}" def → ` +
+                                `${receiverDefType}("${newReceiverSelector}")`);
+                            forcedReceiver = discoveredAstRoot;
+                            workingSegments = remainingSegments;
+                            resolvedRootReceiver = pageRoot;
+                        }
+                        else {
+                            logger_1.logger.debug(`TypeCollision: def update failed → page root fallback`);
+                            forcedReceiver = pageRoot;
+                            resolvedRootReceiver = pageRoot;
+                        }
+                    }
+                    else {
+                        forcedReceiver = pageRoot;
+                        resolvedRootReceiver = pageRoot;
+                    }
+                }
+            }
+        }
+        // ── Phase B: Semantic-First Enforcement ─────────────────────────
+        workingSegments = workingSegments.map((seg) => {
+            if (seg.type !== "locator")
+                return seg;
+            const m = seg.selector.match(/^:has-text\(['"](.+)['"]\)$/);
+            if (m) {
+                logger_1.logger.debug(`:has-text → getByText("${m[1]}")`);
+                return { type: "getByText", text: m[1], exact: false };
+            }
+            return seg;
+        });
+        // ── Phase C: ChainValidator ─────────────────────────────────────
+        const validation = this.chainValidator.validate({
+            segments: workingSegments,
+            originalRootReceiver: forcedReceiver ?? "page",
+            proposedRootReceiver: forcedReceiver ?? "page",
+            rootType: "unknown",
+            applySemanticUpgrade: true,
+        });
+        if (!validation.valid) {
+            logger_1.logger.warn(`ChainValidator rejected: ${validation.reason}`);
+            return null;
+        }
+        const resolvedSegments = (validation.segments ??
+            workingSegments);
+        // ── Phase D: Find AST candidate nodes ──────────────────────────
+        const strictCandidates = this.findCandidateNodes(sourceFile, oldSelector, searchWindow);
+        const identityCandidates = suspectIdentifier
+            ? this.findCandidatesInDeclaration(sourceFile, suspectIdentifier, oldSelector, caller.line)
+            : [];
+        const seenNodes = new WeakSet();
+        const candidates = [];
+        for (const c of strictCandidates) {
+            if (!seenNodes.has(c.call)) {
+                seenNodes.add(c.call);
+                candidates.push({ ...c, identityConfidence: false });
+            }
+        }
+        for (const c of identityCandidates) {
+            if (!seenNodes.has(c.call)) {
+                seenNodes.add(c.call);
+                candidates.push(c);
+            }
+        }
+        if (candidates.length === 0) {
+            logger_1.logger.debug(`No absolute matches found`);
+            return null;
+        }
+        candidates.sort((a, b) => {
+            if (a.identityConfidence !== b.identityConfidence) {
+                return a.identityConfidence ? 1 : -1;
+            }
+            return (Math.abs(a.call.getStartLineNumber() - caller.line) -
+                Math.abs(b.call.getStartLineNumber() - caller.line));
+        });
+        // ── Phase E: Build + Validate + Write ──────────────────────────
+        for (const { call, chainTop, rootReceiver: astRoot, chainDepth, identityConfidence, } of candidates) {
+            // ── Identifier/PropertyAccess guard ────────────────────────────
+            // NT must never rewrite a call whose first argument is an Identifier
+            // or PropertyAccessExpression (e.g. locator(SUBMIT_SELECTOR) or
+            // locator(SELS.submit)).  Replacing the whole chain would substitute
+            // a hardcoded string literal for the reference, which is exactly the
+            // definition-site mutation bug the semantic dispatch gate was built
+            // to prevent.  Skip the candidate; the semantic gate owns this case.
+            const firstArg = call.getArguments()[0];
+            if (firstArg &&
+                (ts_morph_1.Node.isIdentifier(firstArg) ||
+                    ts_morph_1.Node.isPropertyAccessExpression(firstArg))) {
+                logger_1.logger.debug(`skip - first arg is ${firstArg.getKindName()} ` +
+                    `"${firstArg.getText()}" (semantic dispatch owns definition-site mutations)`);
+                continue;
+            }
+            const callLine = call.getStartLineNumber();
+            const originalText = chainTop.getText();
+            // ══════════════════════════════════════════════════════════════
+            // SCOPE-AWARE RECEIVER RESOLUTION  ← THE CORE FIX
+            //
+            // Before we build code, we must verify that the proposed receiver
+            // does not create a circular self-reference.
+            //
+            // Case A - forcedReceiver is set (strip-and-force path):
+            //   Check if the chainTop lives inside the initializer of that var.
+            //   If yes, fall back to the actual AST root (e.g. "page").
+            //
+            // Case B - no forced receiver:
+            //   Use astRoot directly - it was walked up from the call node and
+            //   is always either "page" or a stable variable reference.
+            // ══════════════════════════════════════════════════════════════
+            let effectiveReceiver;
+            if (forcedReceiver) {
+                // resolveSafeReceiver checks isInsideOwnInitializer and falls back
+                // to resolvedRootReceiver ("page" etc.) when needed.
+                effectiveReceiver = resolveSafeReceiver(forcedReceiver, resolvedRootReceiver || astRoot, chainTop);
+            }
+            else {
+                effectiveReceiver = astRoot;
+            }
+            // ── Additional safety: if effectiveReceiver still matches the variable
+            //    name being declared (possible through deep var chains), force page.
+            if (suspectIdentifier &&
+                effectiveReceiver === suspectIdentifier &&
+                isInsideOwnInitializer(chainTop, suspectIdentifier)) {
+                logger_1.logger.debug(`Secondary circular guard: ` +
+                    `effectiveReceiver "${effectiveReceiver}" == suspectIdentifier ` +
+                    `inside own initializer → forcing root "${astRoot}"`);
+                effectiveReceiver = astRoot;
+            }
+            logger_1.logger.debug(`Receiver: forced=${forcedReceiver ?? "none"} ` +
+                `ast=${astRoot} → "${effectiveReceiver}" ` +
+                `(scopeSafe=${effectiveReceiver !== forcedReceiver ? "fallback" : "ok"})`);
+            const hintForPartial = originalChainHint &&
+                originalChainHint.length === resolvedSegments.length
+                ? originalChainHint
+                : undefined;
+            if (!identityConfidence && hintForPartial) {
+                const partial = this.attemptPartialHeal(sourceFile, call, chainTop, effectiveReceiver, hintForPartial, resolvedSegments, callLine);
+                if (partial)
+                    return partial;
+            }
+            const newCode = MethodMapper.buildChain(effectiveReceiver, resolvedSegments, originalText);
+            if (!newCode) {
+                logger_1.logger.warn(`MethodMapper failed for receiver "${effectiveReceiver}"`);
+                continue;
+            }
+            if (!this.validateGeneratedCode(newCode, sourceFile)) {
+                logger_1.logger.warn(`Validation failed for:\n${newCode}`);
+                continue;
+            }
+            const tag = identityConfidence ? "identity" : "strict full replace";
+            logger_1.logger.debug(`${tag} @line ${callLine} receiver="${effectiveReceiver}":\n` +
+                `  ${newCode.split("\n")[0]}`);
+            try {
+                chainTop.replaceWithText(newCode);
+                persistSourceFile(sourceFile);
+                return {
+                    success: true,
+                    reason: `scope-aware transform [${effectiveReceiver}]: ${resolvedSegments.length} segments`,
+                    strategy: identityConfidence ? "NT-identity" : "NT",
+                    lineUpdated: callLine - 1,
+                };
+            }
+            catch (e) {
+                logger_1.logger.warn(`replaceWithText failed: ${e.message}`);
+            }
+        }
+        return null;
+    }
+    discoverAstRootReceiver(sourceFile, oldSelector, window, suspectIdentifier, callerLine) {
+        const allCandidates = [];
+        for (const call of sourceFile.getDescendantsOfKind(ts_morph_1.SyntaxKind.CallExpression)) {
+            const line = call.getStartLineNumber();
+            if (line < window.start || line > window.end)
+                continue;
+            const args = call.getArguments();
+            if (args.length > 0 && ts_morph_1.Node.isTemplateExpression(args[0]))
+                continue;
+            if (!absoluteNodeMatch(call, oldSelector))
+                continue;
+            const { rootReceiver } = climbToChainTop(call);
+            if (rootReceiver && !PAGE_ROOT_NAMES.has(rootReceiver)) {
+                allCandidates.push({
+                    receiver: rootReceiver,
+                    distance: Math.abs(line - callerLine),
+                });
+            }
+        }
+        if (suspectIdentifier && !PAGE_ROOT_NAMES.has(suspectIdentifier)) {
+            const decl = jumpToDefinitionInFile(sourceFile, suspectIdentifier, callerLine + 5);
+            if (decl) {
+                const init = decl.getInitializer();
+                if (init && ts_morph_1.Node.isCallExpression(init)) {
+                    for (const call of decl.getDescendantsOfKind(ts_morph_1.SyntaxKind.CallExpression)) {
+                        const args = call.getArguments();
+                        if (args.length > 0 && ts_morph_1.Node.isTemplateExpression(args[0]))
+                            continue;
+                        if (!absoluteNodeMatch(call, oldSelector))
+                            continue;
+                        const { rootReceiver } = climbToChainTop(call);
+                        if (rootReceiver && !PAGE_ROOT_NAMES.has(rootReceiver)) {
+                            allCandidates.push({ receiver: rootReceiver, distance: 0 });
+                        }
+                    }
+                }
+            }
+        }
+        if (allCandidates.length === 0)
+            return null;
+        allCandidates.sort((a, b) => a.distance - b.distance);
+        const result = allCandidates[0].receiver;
+        logger_1.logger.debug(`Discovered AST root receiver: "${result}"`);
+        return result;
+    }
+    findCandidateNodes(sourceFile, oldSelector, window) {
+        const results = [];
+        for (const call of sourceFile.getDescendantsOfKind(ts_morph_1.SyntaxKind.CallExpression)) {
+            const line = call.getStartLineNumber();
+            if (line < window.start || line > window.end)
+                continue;
+            const args = call.getArguments();
+            if (args.length > 0 && ts_morph_1.Node.isTemplateExpression(args[0]))
+                continue;
+            if (!absoluteNodeMatch(call, oldSelector))
+                continue;
+            const { chainTop, rootReceiver, chainDepth } = climbToChainTop(call);
+            results.push({ call, chainTop, rootReceiver, chainDepth });
+        }
+        return results;
+    }
+    findCandidatesInDeclaration(sourceFile, varName, oldSelector, beforeLine) {
+        const results = [];
+        const decl = jumpToDefinitionInFile(sourceFile, varName, beforeLine + 5);
+        if (!decl)
+            return results;
+        for (const call of decl.getDescendantsOfKind(ts_morph_1.SyntaxKind.CallExpression)) {
+            const args = call.getArguments();
+            if (args.length > 0 && ts_morph_1.Node.isTemplateExpression(args[0]))
+                continue;
+            if (!absoluteNodeMatch(call, oldSelector))
+                continue;
+            const { chainTop, rootReceiver, chainDepth } = climbToChainTop(call);
+            results.push({
+                call,
+                chainTop,
+                rootReceiver,
+                chainDepth,
+                identityConfidence: false,
+            });
+        }
+        const init = decl.getInitializer();
+        if (init &&
+            ts_morph_1.Node.isCallExpression(init) &&
+            absoluteNodeMatch(init, oldSelector)) {
+            const { chainTop, rootReceiver, chainDepth } = climbToChainTop(init);
+            results.push({
+                call: init,
+                chainTop,
+                rootReceiver,
+                chainDepth,
+                identityConfidence: false,
+            });
+        }
+        if (results.length === 0 && init && ts_morph_1.Node.isCallExpression(init)) {
+            if (this.isPlaywrightLocatorCall(init)) {
+                logger_1.logger.debug(`Identity override: '${varName}' @ line ${decl.getStartLineNumber()}`);
+                const { chainTop, rootReceiver, chainDepth } = climbToChainTop(init);
+                results.push({
+                    call: init,
+                    chainTop,
+                    rootReceiver,
+                    chainDepth,
+                    identityConfidence: true,
+                });
+            }
+            else {
+                const pwCalls = decl
+                    .getDescendantsOfKind(ts_morph_1.SyntaxKind.CallExpression)
+                    .filter((c) => {
+                    const args = c.getArguments();
+                    if (args.length > 0 && ts_morph_1.Node.isTemplateExpression(args[0]))
+                        return false;
+                    return this.isPlaywrightLocatorCall(c);
+                });
+                if (pwCalls.length > 0) {
+                    const innermost = pwCalls[pwCalls.length - 1];
+                    const { chainTop, rootReceiver, chainDepth } = climbToChainTop(innermost);
+                    results.push({
+                        call: innermost,
+                        chainTop,
+                        rootReceiver,
+                        chainDepth,
+                        identityConfidence: true,
+                    });
+                }
+            }
+        }
+        return results;
+    }
+    isPlaywrightLocatorCall(callExpr) {
+        const expr = callExpr.getExpression();
+        if (!ts_morph_1.Node.isPropertyAccessExpression(expr))
+            return false;
+        return ALL_SELECTOR_METHODS.has(expr.getName());
+    }
+    attemptPartialHeal(sourceFile, leafCall, chainTop, effectiveReceiver, originalSegments, newSegments, callLine) {
+        if (JSON.stringify(originalSegments) === JSON.stringify(newSegments))
+            return null;
+        const changedIndices = [];
+        for (let i = 0; i < originalSegments.length; i++) {
+            if (JSON.stringify(originalSegments[i]) !== JSON.stringify(newSegments[i])) {
+                changedIndices.push(i);
+            }
+        }
+        if (changedIndices.length !== 1)
+            return null;
+        const changedIdx = changedIndices[0];
+        const newSeg = newSegments[changedIdx];
+        const chainCalls = collectChainCalls(chainTop);
+        if (chainCalls.length <= changedIdx)
+            return null;
+        const targetCall = chainCalls[chainCalls.length - 1 - changedIdx];
+        if (!targetCall)
+            return null;
+        const callReceiver = (() => {
+            const expr = targetCall.getExpression();
+            return ts_morph_1.Node.isPropertyAccessExpression(expr)
+                ? expr.getExpression().getText()
+                : effectiveReceiver;
+        })();
+        const currentMethodName = (() => {
+            const expr = targetCall.getExpression();
+            return ts_morph_1.Node.isPropertyAccessExpression(expr) ? expr.getName() : "?";
+        })();
+        const newCallText = MethodMapper.build(callReceiver, newSeg);
+        if (!newCallText)
+            return null;
+        if (!this.validateGeneratedCode(newCallText, sourceFile))
+            return null;
+        logger_1.logger.debug(`Partial: segment[${changedIdx}] .${currentMethodName}() → ${newCallText}`);
+        try {
+            targetCall.replaceWithText(newCallText);
+            persistSourceFile(sourceFile);
+            return {
+                success: true,
+                reason: `partial: seg[${changedIdx}] .${currentMethodName}() → .${newSeg.type}()`,
+                strategy: "NT-partial",
+                lineUpdated: callLine - 1,
+            };
+        }
+        catch (e) {
+            logger_1.logger.warn(`Partial failed: ${e.message}`);
+            return null;
+        }
+    }
+    updateReceiverDefinition(sourceFile, varName, segType, newSelector, callerLine) {
+        // Collect all matching declarations, then pick the closest one that
+        // appears strictly BEFORE callerLine - prevents accidentally updating
+        // a same-named variable in a different test block that happens to be
+        // within the 100-line distance window.
+        const declarations = sourceFile.getDescendantsOfKind(ts_morph_1.SyntaxKind.VariableDeclaration);
+        let bestDecl = null;
+        let bestDistance = Infinity;
+        for (const decl of declarations) {
+            if (decl.getName() !== varName)
+                continue;
+            const declLine = decl.getStartLineNumber();
+            if (declLine >= callerLine)
+                continue; // must be before caller
+            const dist = callerLine - declLine;
+            if (dist < bestDistance) {
+                bestDistance = dist;
+                bestDecl = decl;
+            }
+        }
+        if (!bestDecl)
+            return false;
+        const initializer = bestDecl.getInitializer();
+        if (!initializer)
+            return false;
+        const allCalls = [
+            ...(ts_morph_1.Node.isCallExpression(initializer) ? [initializer] : []),
+            ...initializer.getDescendantsOfKind(ts_morph_1.SyntaxKind.CallExpression),
+        ];
+        for (const call of allCalls) {
+            const expr = call.getExpression();
+            if (!ts_morph_1.Node.isPropertyAccessExpression(expr))
+                continue;
+            if (expr.getName() !== segType)
+                continue;
+            const args = call.getArguments();
+            if (args.length === 0)
+                continue;
+            const firstArg = args[0];
+            if (!ts_morph_1.Node.isStringLiteral(firstArg))
+                continue;
+            firstArg.replaceWithText(`"${newSelector}"`);
+            persistSourceFile(sourceFile);
+            return true;
+        }
+        return false;
+    }
+    validateGeneratedCode(code, _sourceFile) {
+        const receiverPattern = /\b([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\./g;
+        const mockCandidates = new Set();
+        const JS_KEYWORDS = new Set([
+            "const",
+            "let",
+            "var",
+            "function",
+            "return",
+            "await",
+            "async",
+            "new",
+            "this",
+            "typeof",
+            "instanceof",
+            "true",
+            "false",
+            "null",
+            "undefined",
+            "if",
+            "else",
+            "for",
+            "while",
+            "do",
+            "switch",
+            "case",
+            "break",
+            "continue",
+        ]);
+        let m;
+        while ((m = receiverPattern.exec(code)) !== null) {
+            const name = m[1];
+            if (!JS_KEYWORDS.has(name) && !ALL_SELECTOR_METHODS.has(name)) {
+                mockCandidates.add(name);
+            }
+        }
+        PAGE_ROOT_NAMES.forEach((n) => mockCandidates.add(n));
+        const bareIdentifierMatch = code.match(/^([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\./);
+        if (bareIdentifierMatch) {
+            mockCandidates.add(bareIdentifierMatch[1]);
+        }
+        const mockPreamble = [...mockCandidates]
+            .map((id) => `const ${id}: any = {} as any;`)
+            .join("\n");
+        const wrappedCode = `${mockPreamble}\nconst __val = ${code.trim()};`;
+        try {
+            const testProject = new ts_morph_1.Project({
+                useInMemoryFileSystem: true,
+                compilerOptions: { noEmit: true, skipLibCheck: true, noResolve: true },
+            });
+            const testFile = testProject.createSourceFile(`tv_${Date.now()}.ts`, wrappedCode, { overwrite: true });
+            const diags = testFile.getPreEmitDiagnostics();
+            const ALLOWED_CODES = new Set([
+                2304, 2339, 2345, 2554, 2571, 7006, 7016, 7031, 18004,
+            ]);
+            const syntaxErrors = diags.filter((d) => {
+                if (d.getCategory() !== 1)
+                    return false;
+                return !ALLOWED_CODES.has(d.getCode());
+            });
+            if (syntaxErrors.length > 0) {
+                logger_1.logger.warn(`Syntax errors: ` +
+                    syntaxErrors
+                        .map((d) => `[TS${d.getCode()}] ${d.getMessageText()}`)
+                        .join(", "));
+                if (/\.(getBy\w+|frameLocator)\s*\(/.test(code)) {
+                    logger_1.logger.warn(`Semantic method detected - bypassing validation`);
+                    return true;
+                }
+                return false;
+            }
+            if (testFile.getStatements().length === 0)
+                return false;
+            return true;
+        }
+        catch (e) {
+            logger_1.logger.warn(`Validation exception: ${e.message}, using heuristic`);
+            return /\.(getBy\w+|locator|frameLocator)\s*\(/.test(code);
+        }
+    }
+}
+// ═══════════════════════════════════════════════════════════════════
+// CHAIN ANALYSIS UTILITIES
+// ═══════════════════════════════════════════════════════════════════
+function climbToChainTop(startCall) {
+    let chainTop = startCall;
+    let chainDepth = 0;
+    let cursor = startCall;
+    while (true) {
+        const parent = cursor.getParent();
+        if (!parent)
+            break;
+        if (ts_morph_1.Node.isPropertyAccessExpression(parent)) {
+            cursor = parent;
+            continue;
+        }
+        if (ts_morph_1.Node.isCallExpression(parent)) {
+            const parentExpr = parent.getExpression();
+            if (ts_morph_1.Node.isPropertyAccessExpression(parentExpr)) {
+                const methodName = parentExpr.getName();
+                if (CHAIN_CONTINUATION_METHODS.has(methodName)) {
+                    chainTop = parent;
+                    chainDepth++;
+                    cursor = parent;
+                    continue;
+                }
+            }
+            break;
+        }
+        break;
+    }
+    const findLeftmost = (n) => {
+        if (ts_morph_1.Node.isCallExpression(n)) {
+            const e = n.getExpression();
+            if (ts_morph_1.Node.isPropertyAccessExpression(e))
+                return findLeftmost(e.getExpression());
+        }
+        if (ts_morph_1.Node.isPropertyAccessExpression(n))
+            return findLeftmost(n.getExpression());
+        if (ts_morph_1.Node.isAwaitExpression(n))
+            return findLeftmost(n.getExpression());
+        return n
+            .getText()
+            .replace(/^await\s+/, "")
+            .trim();
+    };
+    return { chainTop, rootReceiver: findLeftmost(chainTop), chainDepth };
+}
+function collectChainCalls(chainTop) {
+    const calls = [];
+    let current = chainTop;
+    while (ts_morph_1.Node.isCallExpression(current)) {
+        calls.push(current);
+        const expr = current.getExpression();
+        if (ts_morph_1.Node.isPropertyAccessExpression(expr)) {
+            current = expr.getExpression();
+        }
+        else {
+            break;
+        }
+    }
+    return calls;
+}
+function isLeafOfChain(call) {
+    const expr = call.getExpression();
+    if (!ts_morph_1.Node.isPropertyAccessExpression(expr))
+        return false;
+    const receiver = expr.getExpression();
+    if (ts_morph_1.Node.isCallExpression(receiver))
+        return true;
+    if (ts_morph_1.Node.isPropertyAccessExpression(receiver)) {
+        return ts_morph_1.Node.isCallExpression(receiver.getExpression());
+    }
+    return false;
+}
+function analyzeVariableInitializerChain(decl) {
+    const initializer = decl.getInitializer();
+    if (!initializer)
+        return null;
+    if (!ts_morph_1.Node.isCallExpression(initializer))
+        return null;
+    const countChainDepth = (n, depth) => {
+        if (ts_morph_1.Node.isCallExpression(n)) {
+            const e = n.getExpression();
+            if (ts_morph_1.Node.isPropertyAccessExpression(e)) {
+                const methodName = e.getName();
+                if (CHAIN_CONTINUATION_METHODS.has(methodName)) {
+                    return countChainDepth(e.getExpression(), depth + 1);
+                }
+            }
+        }
+        if (ts_morph_1.Node.isPropertyAccessExpression(n))
+            return countChainDepth(n.getExpression(), depth);
+        return {
+            depth,
+            root: n
+                .getText()
+                .replace(/^await\s+/, "")
+                .trim(),
+        };
+    };
+    const { depth, root } = countChainDepth(initializer, 0);
+    if (depth === 0)
+        return null;
+    return { fullChainNode: initializer, rootReceiver: root, chainDepth: depth };
+}
+function jumpToDefinitionInFile(sourceFile, varName, beforeLine) {
+    const text = sourceFile.getFullText();
+    const lines = text.split("\n");
+    let beforeOffset = 0;
+    for (let i = 0; i < Math.min(beforeLine - 1, lines.length); i++) {
+        beforeOffset += lines[i].length + 1;
+    }
+    let best = null;
+    let bestOffset = -1;
+    for (const decl of sourceFile.getDescendantsOfKind(ts_morph_1.SyntaxKind.VariableDeclaration)) {
+        if (decl.getName() !== varName)
+            continue;
+        const offset = decl.getStart();
+        if (offset < beforeOffset && offset > bestOffset) {
+            best = decl;
+            bestOffset = offset;
+        }
+    }
+    if (best) {
+        logger_1.logger.debug(`JumpToDef: '${varName}' @ line ${best.getStartLineNumber()}`);
+    }
+    return best;
+}
+// ═══════════════════════════════════════════════════════════════════
+// ChainValidator integration
+// ═══════════════════════════════════════════════════════════════════
+const chainValidator = new ChainValidator_1.ChainValidator();
+const nodeTransformer = new NodeTransformationStrategy(chainValidator);
+function buildSmartChainCode(receiver, smartSegments, originalReceiver, rootType = "unknown", originalText) {
+    const segments = smartSegments;
+    const result = chainValidator.validate({
+        segments,
+        originalRootReceiver: originalReceiver,
+        proposedRootReceiver: receiver,
+        rootType,
+        applySemanticUpgrade: true,
+    });
+    if (!result.valid) {
+        logger_1.logger.warn(`ChainValidator rejected segments: ${result.reason}`);
+        return null;
+    }
+    const finalSegments = (result.segments ??
+        segments);
+    const code = MethodMapper.buildChain(receiver, finalSegments, originalText);
+    if (code)
+        return code;
+    const multiLine = finalSegments.length >= 3;
+    return (0, ChainValidator_1.segmentsToCode)(receiver, result.segments ?? segments, multiLine);
+}
+const TEXT_MATCHERS = new Set([
+    "toHaveText",
+    "toContainText",
+    "toHaveValue",
+    "toHaveAttribute",
+    "toHaveTitle",
+    "toHaveLabel",
+]);
+function findAssertionsInWindow(sourceFile, locatorVarName, callerLine, windowLines) {
+    const results = [];
+    const scanStart = Math.max(1, callerLine - 2);
+    const scanEnd = Math.min(sourceFile.getEndLineNumber(), callerLine + windowLines);
+    for (const call of sourceFile.getDescendantsOfKind(ts_morph_1.SyntaxKind.CallExpression)) {
+        const line = call.getStartLineNumber();
+        if (line < scanStart || line > scanEnd)
+            continue;
+        const expr = call.getExpression();
+        if (!ts_morph_1.Node.isPropertyAccessExpression(expr))
+            continue;
+        if (!TEXT_MATCHERS.has(expr.getName()))
+            continue;
+        let expectCallNode = null;
+        let cur = expr.getExpression();
+        for (let i = 0; i < 8; i++) {
+            if (ts_morph_1.Node.isCallExpression(cur)) {
+                const inner = cur.getExpression();
+                if (ts_morph_1.Node.isIdentifier(inner) && inner.getText() === "expect") {
+                    expectCallNode = cur;
+                    break;
+                }
+                if (ts_morph_1.Node.isPropertyAccessExpression(inner)) {
+                    const nm = inner.getName();
+                    if (nm === "not" || nm === "soft" || nm === "poll") {
+                        cur = inner.getExpression();
+                        continue;
+                    }
+                }
+            }
+            if (ts_morph_1.Node.isPropertyAccessExpression(cur)) {
+                cur = cur.getExpression();
+                continue;
+            }
+            break;
+        }
+        if (!expectCallNode)
+            continue;
+        const expectArgs = expectCallNode.getArguments();
+        if (expectArgs.length === 0)
+            continue;
+        const argText = expectArgs[0].getText();
+        if (locatorVarName !== null) {
+            const matches = argText === locatorVarName ||
+                argText.startsWith(locatorVarName + ".") ||
+                argText.startsWith(locatorVarName + " ");
+            if (!matches)
+                continue;
+        }
+        const matcherArgs = call.getArguments();
+        if (matcherArgs.length === 0)
+            continue;
+        const firstMatcherArg = matcherArgs[0];
+        if (ts_morph_1.Node.isRegularExpressionLiteral(firstMatcherArg))
+            continue;
+        let currentValue = null;
+        if (ts_morph_1.Node.isStringLiteral(firstMatcherArg)) {
+            currentValue = firstMatcherArg.getLiteralValue();
+        }
+        if (currentValue === null)
+            continue;
+        results.push({
+            expectCall: expectCallNode,
+            matcherCall: call,
+            matcherName: expr.getName(),
+            currentValue,
+            line,
+        });
+    }
+    return results;
+}
+/**
+ * Build a locator EXPRESSION from a raw healed selector + chain root.
+ * Internal engine selectors become their idiomatic method form
+ * (`page.getByRole(...)`); otherwise a `root.locator("selector")` call.
+ */
+function buildLocatorExpr(rawSelector, rootReceiver) {
+    const root = rootReceiver || "page";
+    if (!rawSelector)
+        return `${root}.locator("")`;
+    if ((0, SelectorSanitizer_1.isInternalEngineSelector)(rawSelector)) {
+        const method = (0, SelectorSanitizer_1.internalToMethodExpression)(rawSelector, root);
+        if (method)
+            return method;
+        const publicStr = (0, SelectorSanitizer_1.internalToPublicSelectorString)(rawSelector);
+        return `${root}.locator(${JSON.stringify(publicStr ?? rawSelector)})`;
+    }
+    return `${root}.locator(${JSON.stringify(rawSelector)})`;
+}
+/** 0-based column of the first non-whitespace char on a 1-based line. */
+function firstNonWhitespaceColumn(text, line1Based) {
+    const lines = text.split(/\r?\n/);
+    const idx = line1Based - 1;
+    if (idx < 0 || idx >= lines.length)
+        return 0;
+    const m = lines[idx].match(/^(\s*)/);
+    return m ? m[1].length : 0;
+}
+class ASTSourceUpdater {
+    project;
+    advisoryBuffer = new HealingAdvisory_1.AdvisoryBuffer();
+    flushAdvisories() {
+        this.advisoryBuffer.flush();
+    }
+    // ═══════════════════════════════════════════════════════════════════
+    // STAGE 4 — end-to-end trace → decide → apply (Stages 1-3 wired in)
+    //
+    // Additive entry point. The legacy heal paths below are untouched; this
+    // is the new write-disciplined pipeline that composes AnchorResolver,
+    // TraceBackEngine, DecisionEngine and MutationApplier.
+    // ═══════════════════════════════════════════════════════════════════
+    /**
+     * Trace the failing call-site back to its source declaration, decide the
+     * mutation strategy (in-place / fork / prompt), and — when `apply` is set —
+     * write it to disk through the type-safety gate.
+     */
+    static composeHeal(input) {
+        const original = fs.readFileSync(input.filePath, "utf8");
+        const project = new ts_morph_1.Project({
+            useInMemoryFileSystem: true,
+            compilerOptions: {
+                allowJs: true,
+                noEmit: true,
+                skipLibCheck: true,
+                noResolve: true,
+            },
+        });
+        const sf = project.createSourceFile(input.filePath, original, {
+            overwrite: true,
+        });
+        // Resolve a robust position: when no explicit column is given, use the
+        // first non-whitespace char of the line (avoids landing on indentation).
+        const column = input.column ?? firstNonWhitespaceColumn(original, input.line);
+        const trace = TraceBackEngine_1.TraceBackEngine.traceFromPosition(sf, input.line, column);
+        if (trace.status !== "target") {
+            return { kind: "abort", trace };
+        }
+        // Re-resolve the node at the failing position for fork test-block lookup.
+        let failingNode;
+        try {
+            failingNode = sf.getDescendantAtPos(sf.compilerNode.getPositionOfLineAndCharacter(input.line - 1, column));
+        }
+        catch {
+            failingNode = undefined;
+        }
+        if (!failingNode)
+            failingNode = trace.target.targetNode;
+        // Build the replacement EXPRESSION. Explicit newLocatorExpr wins; else
+        // synthesise it from the raw healed selector + the traced root receiver,
+        // translating internal engine selectors to their idiomatic method form.
+        const newLocatorExpr = input.newLocatorExpr ??
+            buildLocatorExpr(input.newSelector ?? "", trace.target.rootReceiver);
+        const decision = DecisionEngine_1.DecisionEngine.decide({
+            target: trace.target,
+            failingCallSite: failingNode,
+            newLocatorExpr,
+            contextSpecific: input.contextSpecific ?? false,
+            globalCorrect: input.globalCorrect ?? false,
+        });
+        const batch = ASTSourceUpdater.decisionToBatch(input.filePath, decision);
+        const result = {
+            kind: "decision",
+            trace,
+            decision,
+            batch,
+            writtenLine: trace.target.targetNode.getStartLineNumber(),
+        };
+        if (input.apply && batch.edits.length > 0) {
+            result.outcome = MutationApplier_1.MutationApplier.applyFileBatch(batch, input.applyOptions ?? {});
+        }
+        return result;
+    }
+    /** Drain-loop entry: apply pre-built batches through the write gate. */
+    static applyMutationBatches(batches, opts = {}) {
+        return MutationApplier_1.MutationApplier.applyBatches(batches, opts);
+    }
+    /** Convert a DecisionEngine result into an anchored MutationApplier batch. */
+    static decisionToBatch(filePath, decision) {
+        const edits = decision.edits.map((e) => {
+            if (e.kind === "insert") {
+                return {
+                    kind: "insert",
+                    replacement: e.replacement,
+                    span: e.span,
+                    requireLocator: false,
+                };
+            }
+            // MUTATE_IN_PLACE replace → anchor-resolved + Locator-type-gated.
+            if (decision.strategy === "MUTATE_IN_PLACE") {
+                return {
+                    kind: "replace",
+                    replacement: e.replacement,
+                    anchor: decision.anchor,
+                    requireLocator: true,
+                };
+            }
+            // FORK call-site receiver rewrite → identifier, not a locator.
+            return {
+                kind: "replace",
+                replacement: e.replacement,
+                span: e.span,
+                requireLocator: false,
+            };
+        });
+        return { filePath, edits };
+    }
+    /**
+     * Centralised write hook for every ts-morph `saveSync` call in this class.
+     * When `SELA_DRY_RUN` is active the AST mutation stays in memory but the
+     * on-disk file is left untouched - the heal pipeline can still compute a
+     * candidate diff via `sourceFile.getFullText()` and the report layer
+     * tags the event with `dryRun: true`.
+     */
+    _persistChanges(sourceFile) {
+        persistSourceFile(sourceFile);
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // FAIL-FAST DIRECTIVE SCAN
+    //
+    // Walks the leading comment ranges of the failing statement (and the
+    // CallExpression node when it differs) looking for the directive
+    // `// sela-fail-fast`.  When found, throws `SelaError(ASTUpdater,
+    // AST_HEAL_DISABLED_BY_DIRECTIVE)` so SelaEngine can short-circuit
+    // BEFORE the LLM call and record a FailedEvent in the "Skipped by
+    // Developer" category.
+    //
+    // Implementation note - ts-morph's `Node.getLeadingCommentRanges()`
+    // returns `ts.CommentRange[]` (offsets, not text). We slice the full
+    // source text by `(pos, end)` to recover the raw comment for each
+    // range, matching both `//` line comments and `/* */` block comments
+    // with either `sela-fail-fast` or `@sela-fail-fast` spelling.
+    // ─────────────────────────────────────────────────────────────────
+    scanFailFastDirective(caller) {
+        const filePath = this.resolveFilePath(caller.filePath);
+        if (!filePath)
+            return { failFast: false };
+        let sourceFile = this.project.getSourceFile(filePath);
+        if (sourceFile) {
+            sourceFile.refreshFromFileSystemSync();
+        }
+        else {
+            sourceFile = this.project.addSourceFileAtPath(filePath);
+        }
+        if (caller.line <= 0)
+            return { failFast: false };
+        const failureNode = this.findNodeAtLine(sourceFile, caller.line);
+        if (!failureNode)
+            return { failFast: false };
+        const statement = this.getEnclosingStatement(failureNode);
+        // Collect candidate comment-owning nodes: enclosing statement (catches
+        // pre-statement comments) AND the failure node itself (catches inline
+        // pre-CallExpression comments inside multi-line chains). De-dup by
+        // offset to avoid double-matching.
+        const fullText = sourceFile.getFullText();
+        const seen = new Set();
+        const nodes = [];
+        if (statement)
+            nodes.push(statement);
+        if (failureNode !== statement)
+            nodes.push(failureNode);
+        const DIRECTIVE_RE = /\/[\/*]\s*@?sela-fail-fast\b/i;
+        for (const node of nodes) {
+            let ranges = [];
+            try {
+                ranges = node.getLeadingCommentRanges() ?? [];
+            }
+            catch {
+                ranges = [];
+            }
+            for (const r of ranges) {
+                const pos = r.getPos();
+                const end = r.getEnd();
+                const key = `${pos}:${end}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                const text = fullText.slice(pos, end);
+                if (DIRECTIVE_RE.test(text)) {
+                    const lineNum = sourceFile.getLineAndColumnAtPos(pos).line;
+                    return {
+                        failFast: true,
+                        matchedComment: text.trim(),
+                        matchedLine: lineNum,
+                    };
+                }
+            }
+        }
+        return { failFast: false };
+    }
+    /**
+     * Convenience helper - runs `scanFailFastDirective` and throws the
+     * canonical SelaError when the directive is present. Used by SelaEngine
+     * as the very first gate inside `heal()`.
+     */
+    enforceFailFastDirective(caller) {
+        const result = this.scanFailFastDirective(caller);
+        if (!result.failFast)
+            return;
+        throw new SelaError_1.SelaError({
+            subsystem: "ASTUpdater",
+            code: SelaError_1.AST_UPDATER_CODES.HEAL_DISABLED_BY_DIRECTIVE,
+            reason: `Heal disabled by developer directive at ${path.basename(caller.filePath)}` +
+                (result.matchedLine ? `:${result.matchedLine}` : ""),
+            context: {
+                filePath: caller.filePath,
+                line: caller.line,
+                directiveLine: result.matchedLine,
+                directiveText: result.matchedComment,
+                category: "Skipped by Developer",
+            },
+        });
+    }
+    constructor() {
+        this.project = new ts_morph_1.Project({
+            useInMemoryFileSystem: false,
+            skipAddingFilesFromTsConfig: true,
+            compilerOptions: {
+                allowJs: true,
+                noEmit: true,
+                skipLibCheck: true,
+                noResolve: true,
+            },
+        });
+    }
+    WRAPPER_IDENTIFIERS = new Set([
+        "test",
+        "it",
+        "describe",
+        "beforeEach",
+        "afterEach",
+        "beforeAll",
+        "afterAll",
+        "expect",
+        "page",
+        "await",
+        "step",
+        "context",
+        "suite",
+    ]);
+    STRUCTURAL_ROLES = new Set([
+        "heading",
+        "banner",
+        "main",
+        "navigation",
+        "nav",
+        "complementary",
+        "aside",
+        "contentinfo",
+        "footer",
+        "region",
+        "landmark",
+        "article",
+        "section",
+        "list",
+        "listitem",
+        "term",
+        "definition",
+        "figure",
+        "img",
+        "presentation",
+        "none",
+        "separator",
+        "scrollbar",
+        "log",
+        "marquee",
+        "status",
+        "timer",
+        "alert",
+        "alertdialog",
+    ]);
+    INTERACTIVE_ROLES = new Set([
+        "textbox",
+        "searchbox",
+        "spinbutton",
+        "button",
+        "checkbox",
+        "radio",
+        "switch",
+        "combobox",
+        "listbox",
+        "option",
+        "menuitem",
+        "menuitemcheckbox",
+        "menuitemradio",
+        "link",
+        "tab",
+        "slider",
+        "progressbar",
+        "grid",
+        "gridcell",
+        "row",
+        "rowheader",
+        "columnheader",
+    ]);
+    // ─────────────────────────────────────────────────────────────────
+    // PUBLIC ENTRY POINT
+    // ─────────────────────────────────────────────────────────────────
+    update(caller, oldSelector, newSelector, aiSegments, fullSelectorContext, contentChange, smartChainSegments, originalChainHint) {
+        const filePath = this.resolveFilePath(caller.filePath);
+        if (!filePath) {
+            return {
+                success: false,
+                reason: `File not found: ${caller.filePath}`,
+                strategy: "none",
+            };
+        }
+        logger_1.logger.debug(`═══════════════════════════════`);
+        logger_1.logger.debug(`${path.basename(filePath)} @ line ${caller.line}`);
+        logger_1.logger.debug(`old: "${oldSelector}"`);
+        logger_1.logger.debug(` → new: "${newSelector}"`);
+        if (smartChainSegments) {
+            logger_1.logger.debug(`smart chain segments: ${JSON.stringify(smartChainSegments)}`);
+        }
+        if (contentChange) {
+            logger_1.logger.debug(`content change: "${contentChange.oldText}" → "${contentChange.newText}"`);
+        }
+        logger_1.logger.debug(`═══════════════════════════════`);
+        const oldSem = parseInternalSelector(oldSelector
+            .split(">>")
+            .pop()
+            .trim()
+            .replace(/\s*i\s*$/, ""));
+        const newSem = parseInternalSelector(newSelector
+            .split(">>")
+            .pop()
+            .trim()
+            .replace(/\s*i\s*$/, ""));
+        logger_1.logger.debug(`old sem: ${oldSem.method}("${oldSem.primaryArg}")`);
+        logger_1.logger.debug(`new sem: ${newSem.method}("${newSem.primaryArg}")`);
+        let sourceFile = this.project.getSourceFile(filePath);
+        if (sourceFile) {
+            sourceFile.refreshFromFileSystemSync();
+        }
+        else {
+            sourceFile = this.project.addSourceFileAtPath(filePath);
+        }
+        if (caller.line <= 0) {
+            logger_1.logger.debug(`line ${caller.line} invalid - Attempting Global Template Strategy`);
+            const globalResult = this.strategyTemplateLiteral(sourceFile, caller, oldSelector, newSelector);
+            if (globalResult && globalResult.success) {
+                if (contentChange)
+                    this.runStrategyG(sourceFile, null, null, contentChange);
+                return this.broadcastAndReturn(globalResult, oldSelector, newSelector, caller);
+            }
+            if (contentChange)
+                this.runStrategyG(sourceFile, null, null, contentChange);
+            return {
+                success: false,
+                reason: "invalid line number (≤0) and global fallback failed",
+                strategy: "none",
+            };
+        }
+        const failureNode = this.findNodeAtLine(sourceFile, caller.line);
+        const statement = failureNode
+            ? this.getEnclosingStatement(failureNode)
+            : undefined;
+        // ─── Developer fail-fast directive ─────────────────────────────
+        // Scan leading comments on the enclosing statement (and the failure
+        // node when they differ) for `// sela-fail-fast`. When present, abort
+        // all heal work with SelaError(AST_HEAL_DISABLED_BY_DIRECTIVE) so the
+        // engine records a FailedEvent in the "Skipped by Developer" bucket.
+        // Defense-in-depth - SelaEngine also calls this at the very start of
+        // heal() to skip the LLM round-trip entirely.
+        this.enforceFailFastDirective(caller);
+        const suspectIdentifier = statement
+            ? this.identifySuspectIdentifier(statement, caller.line)
+            : null;
+        if (suspectIdentifier) {
+            logger_1.logger.debug(`Primary suspect: '${suspectIdentifier}'`);
+        }
+        // ─── T-10: Semantic Dispatch Gate ──────────────────────────────
+        // HARD EXIT: any non-null result (success OR failure) stops all
+        // subsequent AST strategies.  When the locator argument is an
+        // Identifier, PropertyAccess, or TemplateLiteral, the gate owns
+        // the mutation - NT/H must never override the symbolic reference.
+        const semanticResult = this.semanticDispatch(sourceFile, caller, oldSelector, newSelector);
+        if (semanticResult !== null) {
+            if (semanticResult.success) {
+                if (contentChange) {
+                    this.runStrategyG(sourceFile, caller, suspectIdentifier, contentChange);
+                }
+                return this.broadcastAndReturn(semanticResult, oldSelector, newSelector, caller);
+            }
+            // Failure (blast-radius block, trace failed, syntax error) - hard stop.
+            logger_1.logger.debug(`Hard stop (${semanticResult.strategy}): ${semanticResult.reason}`);
+            return semanticResult;
+        }
+        // ───────────────────────────────────────────────────────────────
+        const startLine = Math.max(1, caller.line - 40);
+        const endLine = Math.min(sourceFile.getEndLineNumber(), caller.line + 5);
+        const structuralStrategies = [
+            () => smartChainSegments && smartChainSegments.length > 0
+                ? nodeTransformer.replaceLocatorNode(sourceFile, caller, oldSelector, smartChainSegments, originalChainHint, suspectIdentifier, { start: startLine, end: endLine })
+                : null,
+            () => smartChainSegments && smartChainSegments.length > 0
+                ? this.strategySmartChain(sourceFile, caller, oldSelector, oldSem, smartChainSegments, originalChainHint, suspectIdentifier)
+                : null,
+            () => aiSegments && aiSegments.length > 0 && fullSelectorContext
+                ? this.strategyFrameUpstream(sourceFile, caller, oldSelector, aiSegments, fullSelectorContext)
+                : null,
+            () => this.strategyChainCollapse(sourceFile, caller, oldSelector, newSelector, oldSem, newSem),
+            () => statement
+                ? this.strategyDeepSymbolResolution(sourceFile, caller, oldSelector, newSelector, oldSem, newSem, suspectIdentifier)
+                : null,
+            () => this.strategyInlineSemanticFix(sourceFile, caller, oldSelector, newSelector, oldSem, newSem),
+            () => this.strategyTemplateLiteral(sourceFile, caller, oldSelector, newSelector),
+            () => this.strategySemanticFragmentScan(sourceFile, caller, oldSelector, newSelector, oldSem, newSem),
+        ];
+        for (const strategyFn of structuralStrategies) {
+            const result = strategyFn();
+            if (result && result.success) {
+                if (contentChange) {
+                    this.runStrategyG(sourceFile, caller, suspectIdentifier, contentChange);
+                }
+                return this.broadcastAndReturn(result, oldSelector, newSelector, caller);
+            }
+        }
+        if (contentChange) {
+            this.runStrategyG(sourceFile, caller, suspectIdentifier, contentChange);
+            return {
+                success: false,
+                reason: "Assertion drift detected - manual review required",
+                strategy: "G",
+            };
+        }
+        return {
+            success: false,
+            reason: "All AST strategies exhausted",
+            strategy: "none",
+        };
+    }
+    // ═══════════════════════════════════════════════════════════════
+    // STRATEGY H - Smart Chain (Legacy fallback)
+    // ═══════════════════════════════════════════════════════════════
+    strategySmartChain(sourceFile, caller, oldSelector, oldSem, smartSegments, originalChainHint, suspectIdentifier) {
+        logger_1.logger.debug(`Strategy H v2: Smart Chain (${smartSegments.length} segments)`);
+        const validationResult = chainValidator.validate({
+            segments: smartSegments,
+            originalRootReceiver: "page",
+            proposedRootReceiver: "page",
+            rootType: "unknown",
+            applySemanticUpgrade: true,
+        });
+        if (!validationResult.valid) {
+            logger_1.logger.warn(`H: ChainValidator pre-check failed: ${validationResult.reason}`);
+            return null;
+        }
+        const resolvedSegments = (validationResult.segments ??
+            smartSegments);
+        const startLine = Math.max(1, caller.line - 40);
+        const endLine = Math.min(sourceFile.getEndLineNumber(), caller.line + 5);
+        const candidates = [];
+        for (const call of sourceFile.getDescendantsOfKind(ts_morph_1.SyntaxKind.CallExpression)) {
+            const callLine = call.getStartLineNumber();
+            if (callLine < startLine || callLine > endLine)
+                continue;
+            const expr = call.getExpression();
+            if (!ts_morph_1.Node.isPropertyAccessExpression(expr))
+                continue;
+            const args = call.getArguments();
+            if (args.length > 0 && ts_morph_1.Node.isTemplateExpression(args[0]))
+                continue;
+            const callSem = extractSemanticFromCall(call);
+            if (!callSem)
+                continue;
+            if (!semanticMatch(callSem, oldSelector, true))
+                continue;
+            const { chainTop, rootReceiver, chainDepth } = climbToChainTop(call);
+            const isChained = chainDepth > 0 || isLeafOfChain(call);
+            const effectiveDepth = chainDepth > 0 ? chainDepth : isChained ? 1 : 0;
+            candidates.push({
+                leafCall: call,
+                chainTop,
+                rootReceiver,
+                chainDepth: effectiveDepth,
+                distance: Math.abs(callLine - caller.line),
+                originalText: chainTop.getText(),
+            });
+        }
+        if (suspectIdentifier && candidates.length === 0) {
+            const decl = jumpToDefinitionInFile(sourceFile, suspectIdentifier, caller.line);
+            if (decl) {
+                const initChain = analyzeVariableInitializerChain(decl);
+                if (initChain) {
+                    const { chainTop, rootReceiver } = climbToChainTop(initChain.fullChainNode);
+                    candidates.push({
+                        leafCall: initChain.fullChainNode,
+                        chainTop,
+                        rootReceiver,
+                        chainDepth: initChain.chainDepth,
+                        distance: Math.abs(decl.getStartLineNumber() - caller.line),
+                        originalText: chainTop.getText(),
+                    });
+                }
+            }
+        }
+        if (candidates.length === 0) {
+            logger_1.logger.debug(`H: no matching candidates found`);
+            return null;
+        }
+        candidates.sort((a, b) => {
+            if (a.distance !== b.distance)
+                return a.distance - b.distance;
+            return b.chainDepth - a.chainDepth;
+        });
+        for (const { leafCall, chainTop, rootReceiver, chainDepth, originalText, } of candidates) {
+            // Identifier/PropertyAccess guard - mirrors the NT guard.
+            // Strategy H must never substitute a hardcoded string for a symbolic
+            // reference; the semantic dispatch gate owns definition-site mutations.
+            const firstArgH = leafCall.getArguments()[0];
+            if (firstArgH &&
+                (ts_morph_1.Node.isIdentifier(firstArgH) ||
+                    ts_morph_1.Node.isPropertyAccessExpression(firstArgH))) {
+                logger_1.logger.debug(`skip - first arg is ${firstArgH.getKindName()} ` +
+                    `"${firstArgH.getText()}" (semantic dispatch owns definition-site mutations)`);
+                continue;
+            }
+            const callLine = leafCall.getStartLineNumber();
+            if (originalChainHint &&
+                originalChainHint.length === resolvedSegments.length) {
+                const partialResult = this.attemptPartialChainHeal(sourceFile, caller, chainTop, rootReceiver, originalChainHint, resolvedSegments, callLine);
+                if (partialResult && partialResult.success)
+                    return partialResult;
+            }
+            // ── Scope safety for Strategy H ─────────────────────────────────
+            // If this candidate's chainTop lives inside the own initializer of
+            // suspectIdentifier, we must use rootReceiver (page), not the var.
+            const safeRootReceiver = suspectIdentifier && isInsideOwnInitializer(chainTop, suspectIdentifier)
+                ? (() => {
+                    logger_1.logger.debug(`Circular guard: rootReceiver adjusted from ` +
+                        `"${rootReceiver}" (inside '${suspectIdentifier}' init) → using AST root`);
+                    return rootReceiver; // rootReceiver from climbToChainTop is always page/root
+                })()
+                : rootReceiver;
+            const newCode = buildSmartChainCode(safeRootReceiver, resolvedSegments, safeRootReceiver, "unknown", originalText);
+            if (!newCode) {
+                logger_1.logger.warn(`H: MethodMapper/ChainValidator produced no code`);
+                continue;
+            }
+            logger_1.logger.debug(`H: full replace (depth=${chainDepth}) →\n${newCode}`);
+            try {
+                chainTop.replaceWithText(newCode);
+                this._persistChanges(sourceFile);
+                return {
+                    success: true,
+                    reason: `smart chain applied (${resolvedSegments.length} segments, depth=${chainDepth})`,
+                    strategy: "H",
+                    lineUpdated: callLine - 1,
+                };
+            }
+            catch (e) {
+                logger_1.logger.warn(`H: replaceWithText failed: ${e.message}`);
+            }
+        }
+        logger_1.logger.debug(`H: all candidates exhausted`);
+        return null;
+    }
+    attemptPartialChainHeal(sourceFile, caller, chainTop, rootReceiver, originalSegments, newSegments, callLine) {
+        if (JSON.stringify(originalSegments) === JSON.stringify(newSegments))
+            return null;
+        const changedIndices = [];
+        for (let i = 0; i < originalSegments.length; i++) {
+            if (JSON.stringify(originalSegments[i]) !== JSON.stringify(newSegments[i])) {
+                changedIndices.push(i);
+            }
+        }
+        if (changedIndices.length === 0 || changedIndices.length > 1)
+            return null;
+        const changedIdx = changedIndices[0];
+        const oldSeg = originalSegments[changedIdx];
+        const newSeg = newSegments[changedIdx];
+        logger_1.logger.debug(`H partial: segment[${changedIdx}] changed: ` +
+            `${JSON.stringify(oldSeg)} → ${JSON.stringify(newSeg)}`);
+        const chainCalls = collectChainCalls(chainTop);
+        if (chainCalls.length <= changedIdx)
+            return null;
+        const targetCallIdx = chainCalls.length - 1 - changedIdx;
+        const targetCall = chainCalls[targetCallIdx];
+        if (!targetCall)
+            return null;
+        // Block H-partial from substituting a literal for an Identifier/PropertyAccess arg.
+        const targetFirstArg = targetCall.getArguments()[0];
+        if (targetFirstArg &&
+            (ts_morph_1.Node.isIdentifier(targetFirstArg) ||
+                ts_morph_1.Node.isPropertyAccessExpression(targetFirstArg))) {
+            logger_1.logger.debug(`H-partial: skip - arg is ${targetFirstArg.getKindName()} ` +
+                `"${targetFirstArg.getText()}" (semantic dispatch owns this)`);
+            return null;
+        }
+        const callReceiver = (() => {
+            const expr = targetCall.getExpression();
+            if (ts_morph_1.Node.isPropertyAccessExpression(expr))
+                return expr.getExpression().getText();
+            return rootReceiver;
+        })();
+        const currentMethodName = (() => {
+            const expr = targetCall.getExpression();
+            if (ts_morph_1.Node.isPropertyAccessExpression(expr))
+                return expr.getName();
+            return "?";
+        })();
+        const newCallText = MethodMapper.build(callReceiver, newSeg);
+        if (newCallText === null)
+            return null;
+        logger_1.logger.debug(`H partial: .${currentMethodName}() → ${newCallText}`);
+        try {
+            targetCall.replaceWithText(newCallText);
+            this._persistChanges(sourceFile);
+            return {
+                success: true,
+                reason: `partial chain heal: segment[${changedIdx}] .${currentMethodName}() → .${newSeg.type}()`,
+                strategy: "H-partial",
+                lineUpdated: callLine - 1,
+            };
+        }
+        catch (e) {
+            logger_1.logger.warn(`H partial: replaceWithText failed: ${e.message}`);
+            return null;
+        }
+    }
+    // ─────────────────────────────────────────────────────────────
+    // STRATEGY F - Chain Collapse
+    // ─────────────────────────────────────────────────────────────
+    strategyChainCollapse(sourceFile, caller, oldSelector, newSelector, oldSem, newSem) {
+        logger_1.logger.debug(`Strategy F: Chain Collapse (upward traversal)`);
+        const startLine = Math.max(1, caller.line - 40);
+        const endLine = Math.min(sourceFile.getEndLineNumber(), caller.line + 5);
+        const candidates = [];
+        for (const call of sourceFile.getDescendantsOfKind(ts_morph_1.SyntaxKind.CallExpression)) {
+            const callLine = call.getStartLineNumber();
+            if (callLine < startLine || callLine > endLine)
+                continue;
+            const callSem = extractSemanticFromCall(call);
+            if (!callSem)
+                continue;
+            if (!semanticMatch(callSem, oldSelector, false))
+                continue;
+            if (this.isBlockedByStructuralWall(call, newSem))
+                continue;
+            const { chainTop, rootReceiver, chainDepth } = climbToChainTop(call);
+            const isChained = chainDepth > 0 || isLeafOfChain(call);
+            if (!isChained)
+                continue;
+            const effectiveDepth = chainDepth > 0 ? chainDepth : 1;
+            candidates.push({
+                leafCall: call,
+                chainTop,
+                rootReceiver,
+                chainDepth: effectiveDepth,
+                distance: Math.abs(callLine - caller.line),
+            });
+        }
+        if (candidates.length === 0) {
+            return {
+                success: false,
+                reason: "no chained candidates found",
+                strategy: "F",
+            };
+        }
+        candidates.sort((a, b) => {
+            if (b.chainDepth !== a.chainDepth)
+                return b.chainDepth - a.chainDepth;
+            return a.distance - b.distance;
+        });
+        for (const { leafCall, chainTop, rootReceiver, chainDepth } of candidates) {
+            const newCallText = buildCallText(rootReceiver, newSem);
+            try {
+                chainTop.replaceWithText(newCallText);
+                this._persistChanges(sourceFile);
+                return {
+                    success: true,
+                    reason: `chain collapsed atomically (depth=${chainDepth})`,
+                    strategy: "F",
+                    lineUpdated: leafCall.getStartLineNumber() - 1,
+                };
+            }
+            catch (e) {
+                logger_1.logger.warn(`F: replaceWithText failed: ${e.message}`);
+            }
+        }
+        return {
+            success: false,
+            reason: "chain collapse: all candidates threw",
+            strategy: "F",
+        };
+    }
+    // ─────────────────────────────────────────────────────────────
+    // STRATEGY G - Assertion Healing
+    // ─────────────────────────────────────────────────────────────
+    runStrategyG(sourceFile, caller, locatorVarName, contentChange) {
+        if (!contentChange)
+            return null;
+        const callerLine = caller && caller.line > 0 ? caller.line : 1;
+        const windowLines = caller === null || caller.line <= 0 ? 99999 : 40;
+        const assertions = findAssertionsInWindow(sourceFile, locatorVarName || null, callerLine, windowLines);
+        if (assertions.length === 0)
+            return null;
+        for (const assertion of assertions) {
+            if (assertion.currentValue.includes(contentChange.oldText)) {
+                const lineNum = assertion.line;
+                const filePath = sourceFile.getFilePath();
+                logger_1.logger.warn(`\n${"=".repeat(60)}`);
+                logger_1.logger.warn(`⚠️  ASSERTION DRIFT DETECTED (Manual Review Required)`);
+                logger_1.logger.warn(`📍 Location: ${path.basename(filePath)}:${lineNum}`);
+                logger_1.logger.warn(`❌ Current:   .toHaveText("${contentChange.oldText}")`);
+                logger_1.logger.warn(`✅ Suggested: .toHaveText("${contentChange.newText}")`);
+                logger_1.logger.warn(`💡 Reason: The element was found, but its content differs.`);
+                logger_1.logger.warn(`${"=".repeat(60)}\n`);
+                return {
+                    success: false,
+                    reason: `Assertion review required at line ${lineNum}`,
+                    strategy: "G",
+                    lineUpdated: undefined,
+                };
+            }
+        }
+        return null;
+    }
+    // ─────────────────────────────────────────────────────────────
+    // STRATEGY A - Frame Upstream Healing
+    // ─────────────────────────────────────────────────────────────
+    strategyFrameUpstream(sourceFile, caller, oldElementSelector, aiSegments, fullSelectorContext) {
+        logger_1.logger.debug(`Strategy A: Frame Upstream`);
+        const originalSegments = fullSelectorContext
+            .split(" >> ")
+            .map((s) => s.trim());
+        const frameSegments = aiSegments.filter((s) => s.type === "frame");
+        const changedFrames = [];
+        frameSegments.forEach((aiSeg, i) => {
+            const orig = originalSegments[i];
+            if (orig && aiSeg.selector !== orig) {
+                changedFrames.push({ old: orig, new: aiSeg.selector });
+            }
+        });
+        if (changedFrames.length === 0) {
+            return { success: false, reason: "no frame changes", strategy: "A" };
+        }
+        const lines = sourceFile.getFullText().split(/\r?\n/);
+        const failureLine = lines[caller.line - 1] ?? "";
+        const varMatch = failureLine.match(/^\s*(?:await\s+)?([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\.\s*(?:locator|getBy)/);
+        const varName = varMatch?.[1];
+        if (varName && varName !== "page") {
+            const varDecl = jumpToDefinitionInFile(sourceFile, varName, caller.line);
+            if (varDecl) {
+                const declLine = varDecl.getStartLineNumber();
+                let anyFixed = false;
+                for (const change of changedFrames) {
+                    if (this.replaceFrameLocatorArg(varDecl, change.old, change.new)) {
+                        anyFixed = true;
+                    }
+                }
+                if (anyFixed) {
+                    this._persistChanges(sourceFile);
+                    return {
+                        success: true,
+                        reason: `upstream variable '${varName}' fixed`,
+                        strategy: "A",
+                        lineUpdated: declLine - 1,
+                    };
+                }
+                for (const change of changedFrames) {
+                    const result = this.replaceStringLiteralInRange(sourceFile, change.old, change.new, declLine, Math.min(sourceFile.getEndLineNumber(), declLine + 8));
+                    if (result !== null) {
+                        this._persistChanges(sourceFile);
+                        return {
+                            success: true,
+                            reason: "multi-line frame fixed",
+                            strategy: "A",
+                            lineUpdated: result,
+                        };
+                    }
+                }
+            }
+        }
+        else {
+            for (const change of changedFrames) {
+                const result = this.replaceStringLiteralInRange(sourceFile, change.old, change.new, Math.max(1, caller.line - 15), caller.line);
+                if (result !== null) {
+                    this._persistChanges(sourceFile);
+                    return {
+                        success: true,
+                        reason: "inline frame fixed",
+                        strategy: "A",
+                        lineUpdated: result,
+                    };
+                }
+            }
+        }
+        return {
+            success: false,
+            reason: "frame upstream: no fix applied",
+            strategy: "A",
+        };
+    }
+    // ─────────────────────────────────────────────────────────────
+    // STRATEGY B - Deep Symbol Resolution
+    // ─────────────────────────────────────────────────────────────
+    strategyDeepSymbolResolution(sourceFile, caller, oldSelector, newSelector, oldSem, newSem, suspectIdentifier) {
+        logger_1.logger.debug(`Strategy B: Deep Symbol Resolution`);
+        const failureNode = this.findNodeAtLine(sourceFile, caller.line);
+        if (!failureNode)
+            return {
+                success: false,
+                reason: "no node at failure line",
+                strategy: "B",
+            };
+        const statement = this.getEnclosingStatement(failureNode);
+        if (!statement)
+            return {
+                success: false,
+                reason: "no enclosing statement",
+                strategy: "B",
+            };
+        const usedVarNames = new Set();
+        statement.getDescendantsOfKind(ts_morph_1.SyntaxKind.Identifier).forEach((id) => {
+            const text = id.getText();
+            if (text !== "page" &&
+                text !== "await" &&
+                text !== "expect" &&
+                /^[a-zA-Z_$]/.test(text) &&
+                !ALL_SELECTOR_METHODS.has(text) &&
+                !this.WRAPPER_IDENTIFIERS.has(text)) {
+                usedVarNames.add(text);
+            }
+        });
+        const sortedVars = [...usedVarNames].sort((a, b) => {
+            if (a === suspectIdentifier)
+                return -1;
+            if (b === suspectIdentifier)
+                return 1;
+            return 0;
+        });
+        for (const varName of sortedVars) {
+            const declaration = jumpToDefinitionInFile(sourceFile, varName, caller.line);
+            if (!declaration)
+                continue;
+            const declLine = declaration.getStartLineNumber();
+            const isSuspect = varName === suspectIdentifier;
+            logger_1.logger.debug(`JumpToDef: '${varName}' → line ${declLine} (suspect=${isSuspect})`);
+            const initChain = analyzeVariableInitializerChain(declaration);
+            if (initChain) {
+                const initCalls = initChain.fullChainNode.getDescendantsOfKind(ts_morph_1.SyntaxKind.CallExpression);
+                const hasMatch = initCalls.some((c) => {
+                    const cs = extractSemanticFromCall(c);
+                    return cs ? semanticMatch(cs, oldSelector, false) : false;
+                });
+                const outerSem = extractSemanticFromCall(initChain.fullChainNode);
+                const outerMatch = outerSem
+                    ? semanticMatch(outerSem, oldSelector, false)
+                    : false;
+                if (hasMatch || outerMatch) {
+                    if (!isSuspect &&
+                        this.isBlockedByStructuralWall(initChain.fullChainNode, newSem))
+                        continue;
+                    const { chainTop, rootReceiver } = climbToChainTop(initChain.fullChainNode);
+                    const effectiveReceiver = rootReceiver || initChain.rootReceiver;
+                    const newCallText = buildCallText(effectiveReceiver, newSem);
+                    try {
+                        chainTop.replaceWithText(newCallText);
+                        this._persistChanges(sourceFile);
+                        const cascadePairs = this.performCascadeHeal(sourceFile, oldSelector, newSelector, oldSem, newSem);
+                        if (cascadePairs.length > 0) {
+                            this._persistChanges(sourceFile);
+                            HealingRegistry_1.HealingRegistry.getInstance().broadcastCascade({ filePath: caller.filePath, line: caller.line }, cascadePairs);
+                        }
+                        return {
+                            success: true,
+                            reason: `initializer chain collapsed in '${varName}' at line ${declLine}`,
+                            strategy: "B",
+                            lineUpdated: declLine - 1,
+                            cascadeFixed: cascadePairs.length,
+                        };
+                    }
+                    catch (e) {
+                        logger_1.logger.warn(`B initializer-collapse failed: ${e.message}`);
+                    }
+                }
+            }
+            const chainResult = this.findMatchingChainTail(declaration, oldSelector, oldSem);
+            if (!chainResult)
+                continue;
+            const { tailCall } = chainResult;
+            const callSem = extractSemanticFromCall(tailCall);
+            if (!isSuspect && this.isBlockedByStructuralWall(tailCall, newSem))
+                continue;
+            if (!isSuspect && callSem) {
+                const exactMethodMatch = callSem.method === oldSem.method &&
+                    callSem.primaryArg === oldSem.primaryArg;
+                const leafMatch = (() => {
+                    const oldLeaf = oldSelector.split(">>").pop().trim();
+                    const oldLeafSem = parseInternalSelector(oldLeaf);
+                    return (callSem.method === oldLeafSem.method &&
+                        callSem.primaryArg === oldLeafSem.primaryArg);
+                })();
+                if (!exactMethodMatch && !leafMatch)
+                    continue;
+            }
+            if (isLeafOfChain(tailCall)) {
+                const { chainTop: tailChainTop, rootReceiver } = climbToChainTop(tailCall);
+                try {
+                    tailChainTop.replaceWithText(buildCallText(rootReceiver, newSem));
+                    this._persistChanges(sourceFile);
+                    const cascadePairs = this.performCascadeHeal(sourceFile, oldSelector, newSelector, oldSem, newSem);
+                    if (cascadePairs.length > 0) {
+                        this._persistChanges(sourceFile);
+                        HealingRegistry_1.HealingRegistry.getInstance().broadcastCascade({ filePath: caller.filePath, line: caller.line }, cascadePairs);
+                    }
+                    return {
+                        success: true,
+                        reason: `tail chain collapsed in '${varName}' at line ${declLine}`,
+                        strategy: "B",
+                        lineUpdated: tailCall.getStartLineNumber() - 1,
+                        cascadeFixed: cascadePairs.length,
+                    };
+                }
+                catch (e) {
+                    logger_1.logger.warn(`B tail-chain-collapse failed: ${e.message}`);
+                }
+            }
+            const fixed = this.replaceChainTailOnly(tailCall, newSem, newSelector);
+            if (fixed) {
+                this._persistChanges(sourceFile);
+                const cascadePairs = this.performCascadeHeal(sourceFile, oldSelector, newSelector, oldSem, newSem);
+                if (cascadePairs.length > 0) {
+                    this._persistChanges(sourceFile);
+                    HealingRegistry_1.HealingRegistry.getInstance().broadcastCascade({ filePath: caller.filePath, line: caller.line }, cascadePairs);
+                }
+                return {
+                    success: true,
+                    reason: `chain tail replaced in '${varName}' at line ${declLine}`,
+                    strategy: "B",
+                    lineUpdated: tailCall.getStartLineNumber() - 1,
+                    cascadeFixed: cascadePairs.length,
+                };
+            }
+        }
+        for (const call of statement.getDescendantsOfKind(ts_morph_1.SyntaxKind.CallExpression)) {
+            const callSem = extractSemanticFromCall(call);
+            if (!callSem || !semanticMatch(callSem, oldSelector, false))
+                continue;
+            if (this.isBlockedByStructuralWall(call, newSem))
+                continue;
+            const { chainTop: stmtChainTop, rootReceiver, chainDepth, } = climbToChainTop(call);
+            if (chainDepth > 0 || isLeafOfChain(call)) {
+                try {
+                    stmtChainTop.replaceWithText(buildCallText(rootReceiver, newSem));
+                    this._persistChanges(sourceFile);
+                    return {
+                        success: true,
+                        reason: "direct statement chain collapse",
+                        strategy: "B",
+                        lineUpdated: caller.line - 1,
+                    };
+                }
+                catch { }
+            }
+            if (this.replaceChainTailOnly(call, newSem, newSelector)) {
+                this._persistChanges(sourceFile);
+                const cascadePairs = this.performCascadeHeal(sourceFile, oldSelector, newSelector, oldSem, newSem);
+                if (cascadePairs.length > 0) {
+                    this._persistChanges(sourceFile);
+                    HealingRegistry_1.HealingRegistry.getInstance().broadcastCascade({ filePath: caller.filePath, line: caller.line }, cascadePairs);
+                }
+                return {
+                    success: true,
+                    reason: "direct statement fix",
+                    strategy: "B",
+                    lineUpdated: caller.line - 1,
+                    cascadeFixed: cascadePairs.length,
+                };
+            }
+        }
+        return {
+            success: false,
+            reason: "symbol not resolved (semantic-aware)",
+            strategy: "B",
+        };
+    }
+    // ─────────────────────────────────────────────────────────────
+    // STRATEGY C - Inline Semantic Fix
+    // ─────────────────────────────────────────────────────────────
+    strategyInlineSemanticFix(sourceFile, caller, oldSelector, newSelector, oldSem, newSem) {
+        logger_1.logger.debug(`Strategy C: Inline Semantic Fix`);
+        const startLine = Math.max(1, caller.line - 8);
+        const endLine = Math.min(sourceFile.getEndLineNumber(), caller.line + 2);
+        for (const call of this.findCallExpressionsInRange(sourceFile, startLine, endLine, ALL_SELECTOR_METHODS)) {
+            const callSem = extractSemanticFromCall(call);
+            if (!callSem || !semanticMatch(callSem, oldSelector))
+                continue;
+            const { chainTop, rootReceiver, chainDepth } = climbToChainTop(call);
+            if (chainDepth > 0 || isLeafOfChain(call)) {
+                try {
+                    chainTop.replaceWithText(buildCallText(rootReceiver, newSem));
+                    const fixLine = chainTop.getStartLineNumber();
+                    this._persistChanges(sourceFile);
+                    const cascadePairs = this.performCascadeHeal(sourceFile, oldSelector, newSelector, oldSem, newSem);
+                    if (cascadePairs.length > 0) {
+                        this._persistChanges(sourceFile);
+                        HealingRegistry_1.HealingRegistry.getInstance().broadcastCascade({ filePath: caller.filePath, line: caller.line }, cascadePairs);
+                    }
+                    return {
+                        success: true,
+                        reason: `inline chain collapse at line ${fixLine}`,
+                        strategy: "C",
+                        lineUpdated: fixLine - 1,
+                        cascadeFixed: cascadePairs.length,
+                    };
+                }
+                catch { }
+            }
+            if (this.applySemanticFix(call, newSem, newSelector)) {
+                const fixLine = call.getStartLineNumber();
+                this._persistChanges(sourceFile);
+                const cascadePairs = this.performCascadeHeal(sourceFile, oldSelector, newSelector, oldSem, newSem);
+                if (cascadePairs.length > 0) {
+                    this._persistChanges(sourceFile);
+                    HealingRegistry_1.HealingRegistry.getInstance().broadcastCascade({ filePath: caller.filePath, line: caller.line }, cascadePairs);
+                }
+                return {
+                    success: true,
+                    reason: `inline fix at line ${fixLine}`,
+                    strategy: "C",
+                    lineUpdated: fixLine - 1,
+                    cascadeFixed: cascadePairs.length,
+                };
+            }
+        }
+        const propAccessResult = this.fixPropertyAccessDefinition(sourceFile, caller, oldSelector, newSelector, oldSem, newSem);
+        if (propAccessResult.success)
+            return propAccessResult;
+        return {
+            success: false,
+            reason: "no inline semantic match",
+            strategy: "C",
+        };
+    }
+    // ─────────────────────────────────────────────────────────────
+    // STRATEGY D - Template Literal
+    // ─────────────────────────────────────────────────────────────
+    strategyTemplateLiteral(sourceFile, caller, oldSelector, newSelector) {
+        logger_1.logger.debug(`Strategy D: Template Literal`);
+        const oldAttrMatch = oldSelector.match(/\[([a-zA-Z-]+)="([^"]*)"\]/);
+        if (!oldAttrMatch)
+            return {
+                success: false,
+                reason: "oldSelector has no attribute",
+                strategy: "D",
+            };
+        const [, attrName, attrValue] = oldAttrMatch;
+        const newLeaf = newSelector.split(">>").pop().trim();
+        const newAttrMatch = newLeaf.match(/\[([a-zA-Z-]+)="([^"]*)"\]/);
+        if (!newAttrMatch || newAttrMatch[1] !== attrName) {
+            return {
+                success: false,
+                reason: "attribute name mismatch",
+                strategy: "D",
+            };
+        }
+        for (const tmpl of sourceFile.getDescendantsOfKind(ts_morph_1.SyntaxKind.TemplateExpression)) {
+            const fullText = tmpl.getFullText();
+            if (!fullText.includes(attrName))
+                continue;
+            const staticSuffixMatch = fullText.match(/\$\{[^}]+\}([^"'`\]]*)\]/);
+            if (!staticSuffixMatch)
+                continue;
+            const oldStaticPart = staticSuffixMatch[1];
+            const varPart = attrValue.replace(new RegExp(oldStaticPart + "$"), "");
+            const newAttrValue = newAttrMatch[2];
+            const newStaticPart = newAttrValue.startsWith(varPart)
+                ? newAttrValue.slice(varPart.length)
+                : "_" + newAttrValue.split("_").pop();
+            if (oldStaticPart === newStaticPart)
+                continue;
+            const escapedOld = oldStaticPart.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+            const newText = fullText.replace(new RegExp(`(\\\$\\{[^}]+\\})${escapedOld}(\\])`), `$1${newStaticPart}$2`);
+            if (newText !== fullText) {
+                tmpl.replaceWithText(newText.trim());
+                const line = tmpl.getStartLineNumber();
+                this._persistChanges(sourceFile);
+                return {
+                    success: true,
+                    reason: "template literal suffix updated",
+                    strategy: "D",
+                    lineUpdated: line - 1,
+                };
+            }
+        }
+        return {
+            success: false,
+            reason: "no matching template literal",
+            strategy: "D",
+        };
+    }
+    // ─────────────────────────────────────────────────────────────
+    // STRATEGY E - Semantic Fragment Scan
+    // ─────────────────────────────────────────────────────────────
+    strategySemanticFragmentScan(sourceFile, caller, oldSelector, newSelector, oldSem, newSem) {
+        logger_1.logger.debug(`Strategy E: Semantic Fragment Scan`);
+        const candidates = [];
+        for (const call of sourceFile.getDescendantsOfKind(ts_morph_1.SyntaxKind.CallExpression)) {
+            const callSem = extractSemanticFromCall(call);
+            if (!callSem || !semanticMatch(callSem, oldSelector, true))
+                continue;
+            candidates.push({
+                call,
+                callSem,
+                distance: Math.abs(call.getStartLineNumber() - caller.line),
+            });
+        }
+        if (candidates.length === 0)
+            return {
+                success: false,
+                reason: "no fragment candidates",
+                strategy: "E",
+            };
+        candidates.sort((a, b) => a.distance - b.distance);
+        for (const { call, callSem } of candidates) {
+            if (this.isBlockedByStructuralWall(call, newSem))
+                continue;
+            const { chainTop, rootReceiver, chainDepth } = climbToChainTop(call);
+            if (chainDepth > 0 || isLeafOfChain(call)) {
+                try {
+                    chainTop.replaceWithText(buildCallText(rootReceiver, newSem));
+                    this._persistChanges(sourceFile);
+                    return {
+                        success: true,
+                        reason: `fragment scan chain collapse .${callSem.method}() @ line ${call.getStartLineNumber()}`,
+                        strategy: "E",
+                        lineUpdated: call.getStartLineNumber() - 1,
+                    };
+                }
+                catch { }
+            }
+            if (this.replaceChainTailOnly(call, newSem, newSelector)) {
+                this._persistChanges(sourceFile);
+                return {
+                    success: true,
+                    reason: `fragment scan fixed .${callSem.method}() @ line ${call.getStartLineNumber()}`,
+                    strategy: "E",
+                    lineUpdated: call.getStartLineNumber() - 1,
+                };
+            }
+        }
+        return {
+            success: false,
+            reason: "fragment scan: all candidates blocked",
+            strategy: "E",
+        };
+    }
+    // ═══════════════════════════════════════════════════════════════
+    // CHAIN HELPERS
+    // ═══════════════════════════════════════════════════════════════
+    findMatchingChainTail(decl, oldSelector, oldSem) {
+        for (const call of decl.getDescendantsOfKind(ts_morph_1.SyntaxKind.CallExpression)) {
+            const callSem = extractSemanticFromCall(call);
+            if (!callSem || !semanticMatch(callSem, oldSelector, false))
+                continue;
+            let outerCall = call;
+            let parent = call.getParent();
+            while (parent) {
+                if (ts_morph_1.Node.isCallExpression(parent)) {
+                    outerCall = parent;
+                    parent = parent.getParent();
+                }
+                else if (ts_morph_1.Node.isPropertyAccessExpression(parent) ||
+                    ts_morph_1.Node.isAwaitExpression(parent)) {
+                    parent = parent.getParent();
+                }
+                else {
+                    break;
+                }
+            }
+            return { outerCall, tailCall: call };
+        }
+        return null;
+    }
+    replaceChainTailOnly(tailCall, newSem, _newSelector) {
+        const expr = tailCall.getExpression();
+        if (!ts_morph_1.Node.isPropertyAccessExpression(expr))
+            return false;
+        const receiver = expr.getExpression().getText();
+        const newCallText = buildCallText(receiver, newSem);
+        try {
+            tailCall.replaceWithText(newCallText);
+            return true;
+        }
+        catch (e) {
+            logger_1.logger.warn(`replaceChainTailOnly failed: ${e.message}`);
+            return false;
+        }
+    }
+    // ═══════════════════════════════════════════════════════════════
+    // SEMANTIC CORE OPERATIONS
+    // ═══════════════════════════════════════════════════════════════
+    applySemanticFix(callExpr, newSem, newSelector) {
+        const expr = callExpr.getExpression();
+        if (!ts_morph_1.Node.isPropertyAccessExpression(expr))
+            return false;
+        const currentMethod = expr.getName();
+        const receiver = expr.getExpression().getText();
+        if (currentMethod === newSem.method)
+            return this.replaceCallArgument(callExpr, newSem);
+        const newCallText = buildCallText(receiver, newSem);
+        try {
+            callExpr.replaceWithText(newCallText);
+            return true;
+        }
+        catch (e) {
+            logger_1.logger.warn(`applySemanticFix failed: ${e.message}`);
+            return false;
+        }
+    }
+    /**
+     * Guard: returns false when replacing oldNode with proposedNewText would
+     * substitute a hardcoded string literal for an Identifier or
+     * PropertyAccessExpression - which is the definition-site mutation bug.
+     * All other replacements are allowed.
+     */
+    static isSafeReplacement(oldNode, proposedNewText) {
+        if (ts_morph_1.Node.isIdentifier(oldNode) ||
+            ts_morph_1.Node.isPropertyAccessExpression(oldNode)) {
+            return !/^["'`]/.test(proposedNewText.trim());
+        }
+        return true;
+    }
+    replaceCallArgument(callExpr, newSem) {
+        try {
+            const args = callExpr.getArguments();
+            if (args.length === 0)
+                return false;
+            const firstArg = args[0];
+            const safe = newSem.primaryArg.replace(/"/g, "'");
+            if (ts_morph_1.Node.isStringLiteral(firstArg)) {
+                firstArg.setLiteralValue(safe);
+            }
+            else if (ASTSourceUpdater.isSafeReplacement(firstArg, `"${safe}"`)) {
+                firstArg.replaceWithText(`"${safe}"`);
+            }
+            else {
+                logger_1.logger.warn(`replaceCallArgument: blocked unsafe replacement - ` +
+                    `arg is ${firstArg.getKindName()}, not a string literal. ` +
+                    `Heal at definition site instead.`);
+                return false;
+            }
+            if (newSem.options && Object.keys(newSem.options).length > 0) {
+                const optionsStr = Object.entries(newSem.options)
+                    .map(([k, v]) => typeof v === "string" ? `${k}: "${v}"` : `${k}: ${v}`)
+                    .join(", ");
+                if (args.length >= 2)
+                    args[1].replaceWithText(`{ ${optionsStr} }`);
+                else
+                    callExpr.addArgument(`{ ${optionsStr} }`);
+            }
+            return true;
+        }
+        catch (e) {
+            logger_1.logger.warn(`replaceCallArgument failed: ${e.message}`);
+            return false;
+        }
+    }
+    semanticToInternal(sem) {
+        switch (sem.method) {
+            case "getByLabel":
+                return `internal:label=${JSON.stringify(sem.primaryArg)}`;
+            case "getByRole": {
+                const namePart = sem.options?.name
+                    ? `[name="${sem.options.name}"i]`
+                    : "";
+                return `internal:role=${sem.primaryArg}${namePart}`;
+            }
+            case "getByPlaceholder":
+                return `internal:attr=[placeholder=${JSON.stringify(sem.primaryArg)}]`;
+            case "getByText": {
+                const exact = sem.options?.exact ? "" : "i";
+                return `internal:text=${JSON.stringify(sem.primaryArg)}${exact}`;
+            }
+            case "getByAltText":
+                return `internal:attr=[alt=${JSON.stringify(sem.primaryArg)}]`;
+            case "getByTitle":
+                return `internal:attr=[title=${JSON.stringify(sem.primaryArg)}]`;
+            case "getByTestId":
+                return `[data-testid="${sem.primaryArg}"]`;
+            default:
+                return sem.primaryArg;
+        }
+    }
+    performCascadeHeal(sourceFile, oldSelector, newSelector, oldSem, newSem) {
+        const fixed = [];
+        for (const call of sourceFile.getDescendantsOfKind(ts_morph_1.SyntaxKind.CallExpression)) {
+            try {
+                const callSem = extractSemanticFromCall(call);
+                if (!callSem || !semanticMatch(callSem, oldSelector, true))
+                    continue;
+                const callInternal = this.semanticToInternal(callSem);
+                if (this.applySemanticFix(call, newSem, newSelector)) {
+                    fixed.push({ oldSelector: callInternal ?? oldSelector, newSelector });
+                }
+            }
+            catch { }
+        }
+        return fixed;
+    }
+    fixPropertyAccessDefinition(sourceFile, caller, oldSelector, newSelector, oldSem, newSem) {
+        for (const callExpr of this.findCallExpressionsInRange(sourceFile, Math.max(1, caller.line - 5), caller.line + 2, ALL_SELECTOR_METHODS)) {
+            const firstArg = callExpr.getArguments()[0];
+            if (!firstArg || !ts_morph_1.Node.isPropertyAccessExpression(firstArg))
+                continue;
+            const objName = firstArg.getExpression().getText();
+            const propName = firstArg.getName();
+            const result = this.updateObjectProperty(sourceFile, objName, propName, oldSem.primaryArg, newSem.primaryArg);
+            if (result !== null) {
+                this._persistChanges(sourceFile);
+                return {
+                    success: true,
+                    reason: `'${objName}.${propName}' updated`,
+                    strategy: "C",
+                    lineUpdated: result,
+                };
+            }
+        }
+        return { success: false, reason: "no property access", strategy: "C" };
+    }
+    isBlockedByStructuralWall(currentCall, newSem) {
+        const newIsInteractive = (newSem.method === "getByRole" &&
+            this.INTERACTIVE_ROLES.has(newSem.primaryArg.toLowerCase())) ||
+            newSem.method === "getByLabel" ||
+            newSem.method === "getByPlaceholder" ||
+            (newSem.method === "locator" &&
+                (newSem.primaryArg.startsWith("#") ||
+                    newSem.primaryArg.includes("input") ||
+                    newSem.primaryArg.includes("textarea")));
+        if (!newIsInteractive)
+            return false;
+        const callSem = extractSemanticFromCall(currentCall);
+        if (!callSem)
+            return false;
+        if (callSem.method === "getByRole" &&
+            this.STRUCTURAL_ROLES.has(callSem.primaryArg.toLowerCase())) {
+            logger_1.logger.warn(`Structural Wall BLOCKED: ` +
+                `.getByRole("${callSem.primaryArg}") is structural, ` +
+                `refusing to replace with ${newSem.method}("${newSem.primaryArg}")`);
+            return true;
+        }
+        return false;
+    }
+    // ═══════════════════════════════════════════════════════════════
+    // AST NAVIGATION HELPERS
+    // ═══════════════════════════════════════════════════════════════
+    identifySuspectIdentifier(statement, line) {
+        const callsOnLine = statement
+            .getDescendantsOfKind(ts_morph_1.SyntaxKind.CallExpression)
+            .filter((c) => c.getStartLineNumber() <= line && c.getEndLineNumber() >= line);
+        if (callsOnLine.length === 0)
+            return null;
+        let bestIdentifier = null;
+        let bestDepth = -1;
+        for (const call of callsOnLine) {
+            const expr = call.getExpression();
+            if (!ts_morph_1.Node.isPropertyAccessExpression(expr))
+                continue;
+            let current = expr.getExpression();
+            let depth = 0;
+            while (ts_morph_1.Node.isCallExpression(current)) {
+                const inner = current.getExpression();
+                if (!ts_morph_1.Node.isPropertyAccessExpression(inner))
+                    break;
+                current = inner.getExpression();
+                depth++;
+            }
+            while (ts_morph_1.Node.isPropertyAccessExpression(current)) {
+                current = current.getExpression();
+                depth++;
+            }
+            if (!ts_morph_1.Node.isIdentifier(current))
+                continue;
+            const name = current.getText();
+            if (this.WRAPPER_IDENTIFIERS.has(name))
+                continue;
+            if (!/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name))
+                continue;
+            if (depth > bestDepth) {
+                bestDepth = depth;
+                bestIdentifier = name;
+            }
+        }
+        return bestIdentifier;
+    }
+    getEnclosingStatement(node) {
+        return (node.getFirstAncestorByKind(ts_morph_1.SyntaxKind.ExpressionStatement) ??
+            node.getFirstAncestorByKind(ts_morph_1.SyntaxKind.VariableStatement) ??
+            node.getParentWhile((n) => !ts_morph_1.Node.isBlock(n) && !ts_morph_1.Node.isSourceFile(n)));
+    }
+    findNodeAtLine(sourceFile, line) {
+        const targetOffset = this.lineToOffset(sourceFile, line);
+        const endOffset = this.lineToOffset(sourceFile, line + 1);
+        return sourceFile.getDescendants().find((n) => {
+            const start = n.getStart();
+            return start >= targetOffset && start < endOffset;
+        });
+    }
+    findCallExpressionsInRange(sourceFile, startLine, endLine, methodNames) {
+        return sourceFile
+            .getDescendantsOfKind(ts_morph_1.SyntaxKind.CallExpression)
+            .filter((call) => {
+            const line = call.getStartLineNumber();
+            if (line < startLine || line > endLine)
+                return false;
+            const expr = call.getExpression();
+            return (ts_morph_1.Node.isPropertyAccessExpression(expr) &&
+                methodNames.has(expr.getName()));
+        });
+    }
+    replaceFrameLocatorArg(varDecl, oldFrame, newFrame) {
+        for (const call of varDecl.getDescendantsOfKind(ts_morph_1.SyntaxKind.CallExpression)) {
+            const expr = call.getExpression();
+            if (!ts_morph_1.Node.isPropertyAccessExpression(expr) ||
+                expr.getName() !== "frameLocator")
+                continue;
+            const arg = call.getArguments()[0];
+            if (arg &&
+                ts_morph_1.Node.isStringLiteral(arg) &&
+                arg.getLiteralValue() === oldFrame) {
+                arg.setLiteralValue(newFrame);
+                return true;
+            }
+        }
+        return false;
+    }
+    replaceStringLiteralInRange(sourceFile, oldVal, newVal, startLine, endLine) {
+        const startOffset = this.lineToOffset(sourceFile, startLine);
+        const endOffset = this.lineToOffset(sourceFile, endLine + 1);
+        for (const node of [
+            ...sourceFile.getDescendantsOfKind(ts_morph_1.SyntaxKind.StringLiteral),
+            ...sourceFile.getDescendantsOfKind(ts_morph_1.SyntaxKind.NoSubstitutionTemplateLiteral),
+        ]) {
+            const offset = node.getStart();
+            if (offset < startOffset || offset > endOffset)
+                continue;
+            const val = node.getLiteralValue?.() ??
+                node.getLiteralValue?.() ??
+                "";
+            if (val === oldVal) {
+                if (ts_morph_1.Node.isStringLiteral(node)) {
+                    node.setLiteralValue(newVal.replace(/"/g, "'"));
+                }
+                else {
+                    node.replaceWithText(`\`${newVal}\``);
+                }
+                return node.getStartLineNumber() - 1;
+            }
+        }
+        return null;
+    }
+    updateObjectProperty(sourceFile, objName, propName, oldValue, newValue) {
+        for (const decl of sourceFile.getDescendantsOfKind(ts_morph_1.SyntaxKind.VariableDeclaration)) {
+            if (decl.getName() !== objName)
+                continue;
+            const init = decl.getInitializer();
+            if (!init || !ts_morph_1.Node.isObjectLiteralExpression(init))
+                continue;
+            for (const prop of init.getProperties()) {
+                if (!ts_morph_1.Node.isPropertyAssignment(prop) || prop.getName() !== propName)
+                    continue;
+                const valueNode = prop.getInitializer();
+                if (!valueNode || !ts_morph_1.Node.isStringLiteral(valueNode))
+                    continue;
+                if (valueNode.getLiteralValue() === oldValue) {
+                    valueNode.setLiteralValue(newValue.replace(/"/g, "'"));
+                    return valueNode.getStartLineNumber() - 1;
+                }
+            }
+        }
+        return null;
+    }
+    lineToOffset(sourceFile, line) {
+        const text = sourceFile.getFullText();
+        const lines = text.split("\n");
+        let offset = 0;
+        for (let i = 0; i < Math.min(line - 1, lines.length); i++) {
+            offset += lines[i].length + 1;
+        }
+        return offset;
+    }
+    resolveFilePath(raw) {
+        if (!raw || typeof raw !== "string")
+            return null;
+        let clean = raw
+            .replace(/^.*?at\s+/, "")
+            .replace(/:\d+:\d+.*$/, "")
+            .trim();
+        if (!clean)
+            return null;
+        if (!path.isAbsolute(clean))
+            clean = path.resolve(process.cwd(), clean);
+        if (!fs.existsSync(clean))
+            return null;
+        const stat = fs.statSync(clean);
+        if (!stat.isFile())
+            return null;
+        return clean;
+    }
+    // ═══════════════════════════════════════════════════════════════════
+    // T-10 / T-11: Semantic Dispatch Gate + handlers
+    // ═══════════════════════════════════════════════════════════════════
+    semanticDispatch(sourceFile, caller, oldSelector, newSelector) {
+        try {
+            // Expand window: the failure site (caller.line) is often .click()/.fill()
+            // AFTER the locator assignment. Search up to 5 lines back so we catch
+            // page.locator(IDENTIFIER) even when it lives on the previous line.
+            const calls = this.findCallExpressionsInRange(sourceFile, Math.max(1, caller.line - 5), caller.line, ALL_SELECTOR_METHODS);
+            for (const call of calls) {
+                const analysis = ArgumentTypeAnalyzer_1.ArgumentTypeAnalyzer.classify(call);
+                if (!analysis)
+                    continue;
+                const { shape, node } = analysis;
+                if (shape === "STRING_LITERAL" || shape === "COMPLEX")
+                    continue;
+                let result = null;
+                if (shape === "IDENTIFIER") {
+                    result = this.handleIdentifierArg(node, sourceFile, caller, newSelector);
+                }
+                else if (shape === "PROPERTY_ACCESS") {
+                    result = this.handlePropertyAccessArg(node, sourceFile, caller, newSelector);
+                }
+                else if (shape === "TEMPLATE_LITERAL") {
+                    result = this.handleTemplateLiteralArg(node, sourceFile, caller, oldSelector, newSelector);
+                }
+                else if (shape === "CALL_EXPRESSION") {
+                    result = this.handleCallExpressionArg(node, sourceFile, oldSelector, newSelector);
+                }
+                // Hard exit: any result (success OR failure) from a definition-site shape
+                // stops all subsequent strategies.  Returning non-null prevents NT, H, and
+                // H-partial from touching the call site when the arg is a symbolic reference.
+                if (result !== null)
+                    return result;
+                // Handler returned null (could not trace).  For definition-site shapes,
+                // return a hard-block failure so NT/H cannot overwrite the identifier.
+                if (shape === "IDENTIFIER" ||
+                    shape === "PROPERTY_ACCESS" ||
+                    shape === "TEMPLATE_LITERAL") {
+                    logger_1.logger.debug(`hard-block: "${node.getText()}" is ${shape} ` +
+                        `but trace failed - preserving call site`);
+                    return {
+                        success: false,
+                        reason: `semantic guard: could not trace "${node.getText()}" - call site preserved`,
+                        strategy: "semantic-guard",
+                    };
+                }
+            }
+            return null;
+        }
+        catch (e) {
+            logger_1.logger.warn(`fell through: ${e.message}`);
+            return null;
+        }
+    }
+    // ═══════════════════════════════════════════════════════════════════
+    // DEFINITION-SITE WRITE (with internal→public Method-Shift fallback)
+    //
+    // A `const X = "selector"` consumed by `.locator(X)` cannot hold a semantic
+    // locator (page.getByRole(...) would reference `page` out of scope at the
+    // declaration). So when the AI heals to an internal engine selector
+    // (`internal:role=…`), we DON'T abort and we DON'T leak the engine string:
+    // we translate it to a VALID PUBLIC selector string (`role=button[name="…"]`)
+    // and write THAT into the constant — keeping the developer's architecture
+    // intact — while surfacing the cleaner semantic method form (getByRole) as
+    // a suggested upgrade in the advisory/report.
+    // ═══════════════════════════════════════════════════════════════════
+    applyDefinitionSiteHeal(targetNode, targetFile, newSelector, strategy, blastRadius) {
+        const wasInternal = (0, SelectorSanitizer_1.isInternalEngineSelector)(newSelector);
+        let writeValue = newSelector;
+        if (wasInternal) {
+            const publicStr = (0, SelectorSanitizer_1.internalToPublicSelectorString)(newSelector);
+            if (!publicStr) {
+                // No public string engine (e.g. label association) → a .locator()
+                // string constant genuinely cannot express it. Preserve the call site.
+                return {
+                    success: false,
+                    reason: `semantic guard: internal selector "${newSelector.slice(0, 48)}" has no public ` +
+                        `.locator() string form - call site preserved (method-shift required)`,
+                    strategy: "semantic-guard",
+                };
+            }
+            writeValue = publicStr;
+            logger_1.logger.debug(`Method-Shift fallback: internal selector → public string "${writeValue}"`);
+        }
+        const result = InitializerUpdater_1.InitializerUpdater.apply(targetNode, targetFile, writeValue);
+        if (!result)
+            return null;
+        if (!this.validateFileSyntax(targetFile)) {
+            return {
+                success: false,
+                reason: "post-mutation syntax validation failed - reverted",
+                strategy,
+            };
+        }
+        if (wasInternal) {
+            const methodExpr = (0, SelectorSanitizer_1.internalToMethodExpression)(newSelector, "page");
+            this.advisoryBuffer.push({
+                code: HealingAdvisory_1.AdvisoryCode.SEMANTIC_UPGRADE_SUGGESTED,
+                message: `Healed constant to public selector string "${writeValue}". ` +
+                    `Cleaner semantic form: ${methodExpr ?? "a getBy* method"}.`,
+                affectedFile: targetFile.getFilePath(),
+                affectedLine: result.lineUpdated,
+                suggestedAction: `For more resilient code, rewrite the call site to ${methodExpr ?? "the semantic locator"} ` +
+                    `instead of the string constant.`,
+            });
+        }
+        return {
+            success: true,
+            reason: `definition-site heal via ${strategy} trace` +
+                (wasInternal ? " (internal→public string; semantic upgrade suggested)" : ""),
+            strategy,
+            lineUpdated: result.lineUpdated,
+            healedLocatorString: result.healedLocatorString,
+            definitionSite: {
+                file: targetFile.getFilePath(),
+                line: result.lineUpdated,
+            },
+            blastRadius,
+        };
+    }
+    handleIdentifierArg(node, sourceFile, caller, newSelector) {
+        const traceResult = DefinitionTracer_1.DefinitionTracer.traceIdentifier(node, sourceFile, caller.line);
+        if (traceResult.found) {
+            const { targetNode, targetFile, declarationNode } = traceResult;
+            const blastNode = declarationNode ?? targetNode;
+            const blast = BlastRadiusAnalyzer_1.BlastRadiusAnalyzer.analyze(blastNode, sourceFile, this.project);
+            logger_1.logger.debug(`BlastRadius IDENTIFIER: risk=${blast.risk} ` +
+                `(${blast.testFunctionCount} tests, ${blast.affectedFiles.length} files)`);
+            if (blast.risk === "high") {
+                this.advisoryBuffer.push({
+                    code: HealingAdvisory_1.AdvisoryCode.BLAST_RADIUS_BLOCKED,
+                    message: `Mutation blocked - ${blast.testFunctionCount} tests reference this constant.`,
+                    affectedFile: targetFile.getFilePath(),
+                    affectedLine: targetNode.getStartLineNumber() - 1,
+                    suggestedAction: "Review all referencing tests before changing this constant.",
+                });
+                return {
+                    success: false,
+                    reason: `BlastRadius BLOCKED: ${blast.testFunctionCount} tests reference this constant - manual review required`,
+                    strategy: "semantic-identifier",
+                };
+            }
+            if (blast.risk === "medium") {
+                this.advisoryBuffer.push({
+                    code: HealingAdvisory_1.AdvisoryCode.BLAST_RADIUS_WARNING,
+                    message: `Mutated constant used in ${blast.testFunctionCount} tests - verify no regressions.`,
+                    affectedFile: targetFile.getFilePath(),
+                    affectedLine: targetNode.getStartLineNumber() - 1,
+                    suggestedAction: "Run the full test suite to confirm all references still pass.",
+                });
+            }
+            return this.applyDefinitionSiteHeal(targetNode, targetFile, newSelector, "semantic-identifier", blast.testFunctionCount);
+        }
+        if (!traceResult.found && traceResult.crossFile) {
+            const xResult = CrossFileHealer_1.CrossFileHealer.heal(traceResult.modulePath, traceResult.symbolName, newSelector, caller.filePath, this.project);
+            if (xResult.success) {
+                this.advisoryBuffer.push({
+                    code: HealingAdvisory_1.AdvisoryCode.CROSS_FILE_MUTATION,
+                    message: `Definition-site mutation crossed file boundary to "${traceResult.modulePath}".`,
+                    affectedFile: caller.filePath,
+                    suggestedAction: "Verify no other callers of this symbol were affected.",
+                });
+            }
+            return xResult;
+        }
+        return null;
+    }
+    handlePropertyAccessArg(node, sourceFile, caller, newSelector) {
+        const traceResult = DefinitionTracer_1.DefinitionTracer.tracePropertyAccess(node, sourceFile, caller.line);
+        if (traceResult.found) {
+            const { targetNode, targetFile, declarationNode } = traceResult;
+            const blastNode = declarationNode ?? targetNode;
+            const blast = BlastRadiusAnalyzer_1.BlastRadiusAnalyzer.analyze(blastNode, sourceFile, this.project);
+            logger_1.logger.debug(`BlastRadius PROPERTY_ACCESS: risk=${blast.risk} ` +
+                `(${blast.testFunctionCount} tests, ${blast.affectedFiles.length} files)`);
+            if (blast.risk === "high") {
+                this.advisoryBuffer.push({
+                    code: HealingAdvisory_1.AdvisoryCode.BLAST_RADIUS_BLOCKED,
+                    message: `Mutation blocked - ${blast.testFunctionCount} tests reference this property.`,
+                    affectedFile: targetFile.getFilePath(),
+                    affectedLine: targetNode.getStartLineNumber() - 1,
+                    suggestedAction: "Review all referencing tests before changing this property.",
+                });
+                return {
+                    success: false,
+                    reason: `BlastRadius BLOCKED: ${blast.testFunctionCount} tests reference this property - manual review required`,
+                    strategy: "semantic-property-access",
+                };
+            }
+            if (blast.risk === "medium") {
+                this.advisoryBuffer.push({
+                    code: HealingAdvisory_1.AdvisoryCode.BLAST_RADIUS_WARNING,
+                    message: `Mutated property used in ${blast.testFunctionCount} tests - verify no regressions.`,
+                    affectedFile: targetFile.getFilePath(),
+                    affectedLine: targetNode.getStartLineNumber() - 1,
+                    suggestedAction: "Run the full test suite to confirm all references still pass.",
+                });
+            }
+            return this.applyDefinitionSiteHeal(targetNode, targetFile, newSelector, "semantic-property-access", blast.testFunctionCount);
+        }
+        if (!traceResult.found && traceResult.crossFile) {
+            const xResult = CrossFileHealer_1.CrossFileHealer.heal(traceResult.modulePath, traceResult.symbolName, newSelector, caller.filePath, this.project);
+            if (xResult.success) {
+                this.advisoryBuffer.push({
+                    code: HealingAdvisory_1.AdvisoryCode.CROSS_FILE_MUTATION,
+                    message: `Definition-site mutation crossed file boundary to "${traceResult.modulePath}".`,
+                    affectedFile: caller.filePath,
+                    suggestedAction: "Verify no other callers of this symbol were affected.",
+                });
+            }
+            return xResult;
+        }
+        return null;
+    }
+    handleTemplateLiteralArg(node, sourceFile, caller, oldSelector, newSelector) {
+        if (!ts_morph_1.Node.isTemplateExpression(node))
+            return null;
+        const patchResult = TemplateDiffService_1.TemplateDiffService.computeNodePatch(node, oldSelector, newSelector);
+        if (!patchResult.ok) {
+            logger_1.logger.debug(`TemplateDiff failed: ${patchResult.reason}`);
+            // Structural simplification fallback: AI proposed a selector that dropped
+            // or rewrote a dynamic span entirely.  Try to derive what each span
+            // expression needs to evaluate to, then trace that span back to its
+            // definition and apply the sub-heal there.
+            if (patchResult.newSpanValues) {
+                const templateNode = node;
+                const oldSpanValues = TemplateDiffService_1.TemplateDiffService.extractNodeSpanValues(templateNode, oldSelector);
+                const spans = templateNode.getTemplateSpans();
+                if (oldSpanValues &&
+                    oldSpanValues.length === patchResult.newSpanValues.length &&
+                    spans.length === oldSpanValues.length) {
+                    logger_1.logger.debug(`Template structural fallback: tracing ${spans.length} span(s)`);
+                    for (let i = 0; i < spans.length; i++) {
+                        const spanExpr = spans[i].getExpression();
+                        const traced = this.traceSpanExpression(spanExpr, sourceFile, caller.line, oldSpanValues[i], patchResult.newSpanValues[i]);
+                        if (traced)
+                            return traced;
+                    }
+                }
+            }
+            if (patchResult.reason.includes("structural") ||
+                patchResult.reason.includes("not found")) {
+                this.advisoryBuffer.push({
+                    code: HealingAdvisory_1.AdvisoryCode.MANUAL_REVIEW_TEMPLATE_COMPLEX,
+                    message: `Template literal requires structural change - automated patch skipped.`,
+                    affectedFile: sourceFile.getFilePath(),
+                    affectedLine: node.getStartLineNumber() - 1,
+                    suggestedAction: "Manually update the template literal and its callers.",
+                });
+            }
+            return null;
+        }
+        const lineUpdated = node.getStartLineNumber() - 1;
+        node.replaceWithText(patchResult.patchedTemplate);
+        this._persistChanges(sourceFile);
+        if (!this.validateFileSyntax(sourceFile)) {
+            return {
+                success: false,
+                reason: "post-mutation syntax validation failed - reverted",
+                strategy: "semantic-template",
+            };
+        }
+        return {
+            success: true,
+            reason: `surgical template patch (segments ${patchResult.changedSegmentIndices.join(",")})`,
+            strategy: "semantic-template",
+            lineUpdated,
+            healedLocatorString: newSelector,
+            definitionSite: { file: sourceFile.getFilePath(), line: lineUpdated },
+        };
+    }
+    traceSpanExpression(spanExpr, sourceFile, callerLine, oldSpanVal, newSpanVal) {
+        if (!ts_morph_1.Node.isIdentifier(spanExpr))
+            return null;
+        const symbol = spanExpr.getSymbol();
+        if (!symbol)
+            return null;
+        for (const decl of symbol.getDeclarations()) {
+            if (!ts_morph_1.Node.isVariableDeclaration(decl))
+                continue;
+            const init = decl.getInitializer();
+            if (!init)
+                continue;
+            if (ts_morph_1.Node.isCallExpression(init)) {
+                return this.handleCallExpressionArg(init, sourceFile, oldSpanVal, newSpanVal);
+            }
+            if (ts_morph_1.Node.isStringLiteral(init) ||
+                ts_morph_1.Node.isNoSubstitutionTemplateLiteral(init)) {
+                const result = InitializerUpdater_1.InitializerUpdater.apply(init, sourceFile, newSpanVal);
+                if (!result)
+                    return null;
+                this._persistChanges(sourceFile);
+                return {
+                    success: true,
+                    reason: `span literal updated via trace`,
+                    strategy: "semantic-template",
+                    lineUpdated: result.lineUpdated,
+                    healedLocatorString: result.healedLocatorString,
+                    definitionSite: {
+                        file: sourceFile.getFilePath(),
+                        line: result.lineUpdated,
+                    },
+                };
+            }
+            if (ts_morph_1.Node.isTemplateExpression(init)) {
+                return this.handleTemplateLiteralArg(init, sourceFile, { filePath: sourceFile.getFilePath(), line: callerLine }, oldSpanVal, newSpanVal);
+            }
+        }
+        return null;
+    }
+    handleCallExpressionArg(node, sourceFile, oldSelector, newSelector) {
+        const fnAnalysis = DefinitionTracer_1.FunctionalReturnAnalyzer.analyze(node, sourceFile);
+        if (fnAnalysis.kind === "complex") {
+            this.advisoryBuffer.push({
+                code: HealingAdvisory_1.AdvisoryCode.MANUAL_REVIEW_CONDITIONAL_RETURN,
+                message: `Function has conditional/complex return - automated patch skipped. Reason: ${fnAnalysis.reason}`,
+                affectedFile: sourceFile.getFilePath(),
+                suggestedAction: "Manually update the function's return expression.",
+            });
+            return null;
+        }
+        if (fnAnalysis.kind === "literal") {
+            const result = InitializerUpdater_1.InitializerUpdater.apply(fnAnalysis.literalNode, fnAnalysis.functionFile, newSelector);
+            if (!result)
+                return null;
+            if (!this.validateFileSyntax(fnAnalysis.functionFile)) {
+                return {
+                    success: false,
+                    reason: "post-mutation syntax validation failed - reverted",
+                    strategy: "semantic-call-expression",
+                };
+            }
+            return {
+                success: true,
+                reason: `function return literal patched @ line ${fnAnalysis.functionLine}`,
+                strategy: "semantic-call-expression",
+                lineUpdated: result.lineUpdated,
+                healedLocatorString: result.healedLocatorString,
+                definitionSite: {
+                    file: fnAnalysis.functionFile.getFilePath(),
+                    line: result.lineUpdated,
+                },
+            };
+        }
+        if (fnAnalysis.kind === "template") {
+            const patchResult = TemplateDiffService_1.TemplateDiffService.computeNodePatch(fnAnalysis.templateNode, oldSelector, newSelector);
+            if (!patchResult.ok) {
+                logger_1.logger.debug(`TemplateDiff (call) failed: ${patchResult.reason}`);
+                if (patchResult.reason.includes("structural")) {
+                    this.advisoryBuffer.push({
+                        code: HealingAdvisory_1.AdvisoryCode.MANUAL_REVIEW_TEMPLATE_COMPLEX,
+                        message: `Function template return requires structural change - automated patch skipped.`,
+                        affectedFile: fnAnalysis.functionFile.getFilePath(),
+                        affectedLine: fnAnalysis.functionLine - 1,
+                        suggestedAction: "Manually update the function's template literal.",
+                    });
+                }
+                return null;
+            }
+            const lineUpdated = fnAnalysis.templateNode.getStartLineNumber() - 1;
+            fnAnalysis.templateNode.replaceWithText(patchResult.patchedTemplate);
+            this._persistChanges(fnAnalysis.functionFile);
+            if (!this.validateFileSyntax(fnAnalysis.functionFile)) {
+                return {
+                    success: false,
+                    reason: "post-mutation syntax validation failed - reverted",
+                    strategy: "semantic-call-expression",
+                };
+            }
+            return {
+                success: true,
+                reason: `function return template patched @ line ${fnAnalysis.functionLine}`,
+                strategy: "semantic-call-expression",
+                lineUpdated,
+                healedLocatorString: newSelector,
+                definitionSite: {
+                    file: fnAnalysis.functionFile.getFilePath(),
+                    line: lineUpdated,
+                },
+            };
+        }
+        return null;
+    }
+    validateFileSyntax(sourceFile) {
+        const ALLOWED_CODES = new Set([
+            2304, 2307, 2339, 2345, 2554, 2571, 7006, 7016, 7031, 18004,
+        ]);
+        const diags = sourceFile.getPreEmitDiagnostics();
+        const syntaxErrors = diags.filter((d) => {
+            if (d.getCategory() !== 1)
+                return false;
+            return !ALLOWED_CODES.has(d.getCode());
+        });
+        if (syntaxErrors.length > 0) {
+            const msgs = syntaxErrors
+                .map((d) => String(d.getMessageText()))
+                .join("; ");
+            logger_1.logger.warn(`syntax errors after mutation: ${msgs} - reverting`);
+            this.advisoryBuffer.push({
+                code: HealingAdvisory_1.AdvisoryCode.POST_MUTATION_TYPE_ERROR,
+                message: `Post-mutation type errors detected - mutation reverted. Errors: ${msgs}`,
+                affectedFile: sourceFile.getFilePath(),
+                suggestedAction: "Manually inspect and fix the type errors introduced by this heal.",
+            });
+            sourceFile.refreshFromFileSystemSync();
+            return false;
+        }
+        return true;
+    }
+    broadcastAndReturn(result, oldSelector, newSelector, caller) {
+        if (result.success) {
+            HealingRegistry_1.HealingRegistry.getInstance().broadcast({ filePath: caller.filePath, line: caller.line }, oldSelector, newSelector);
+            return { ...result, healedLocatorString: newSelector };
+        }
+        return result;
+    }
+}
+exports.ASTSourceUpdater = ASTSourceUpdater;