sela-core 1.0.0

package/dist/services/TemplateDiffService.d.ts

@@ -0,0 +1,25 @@
+import { TemplateExpression } from "ts-morph";
+export type DiffPatchResult = {
+    ok: true;
+    /** Full patched template string, backtick-wrapped, ready for replaceWithText(). */
+    patchedTemplate: string;
+    /** Zero-based indices of static segments that changed. */
+    changedSegmentIndices: number[];
+} | {
+    ok: false;
+    reason: string;
+    /**
+     * Populated when alignWithNew fails due to structural simplification:
+     * what each span expression needs to evaluate to satisfy resolvedNew.
+     * Use for span-tracing fallback (resolve each span's source independently).
+     */
+    newSpanValues?: string[];
+};
+export declare class TemplateDiffService {
+    static diffAndPatch(templateText: string, resolvedOld: string, resolvedNew: string): DiffPatchResult;
+    static computeNodePatch(templateNode: TemplateExpression, resolvedOld: string, resolvedNew: string): DiffPatchResult;
+    static extractNodeSpanValues(templateNode: TemplateExpression, resolved: string): string[] | null;
+}
+/** Escape characters that would break a template literal. */
+export declare function escapeForTemplate(text: string): string;
+//# sourceMappingURL=TemplateDiffService.d.ts.map

package/dist/services/TemplateDiffService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TemplateDiffService.d.ts","sourceRoot":"","sources":["../../src/services/TemplateDiffService.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,kBAAkB,EAAc,MAAM,UAAU,CAAC;AAMhE,MAAM,MAAM,eAAe,GACvB;IACE,EAAE,EAAE,IAAI,CAAC;IACT,mFAAmF;IACnF,eAAe,EAAE,MAAM,CAAC;IACxB,0DAA0D;IAC1D,qBAAqB,EAAE,MAAM,EAAE,CAAC;CACjC,GACD;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B,CAAC;AA6BN,qBAAa,mBAAmB;IAW9B,MAAM,CAAC,YAAY,CACjB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,eAAe;IA6GlB,MAAM,CAAC,gBAAgB,CACrB,YAAY,EAAE,kBAAkB,EAChC,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,eAAe;IAoFlB,MAAM,CAAC,qBAAqB,CAC1B,YAAY,EAAE,kBAAkB,EAChC,QAAQ,EAAE,MAAM,GACf,MAAM,EAAE,GAAG,IAAI;CASnB;AAgJD,6DAA6D;AAC7D,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKtD"}

package/dist/services/TemplateDiffService.js

@@ -0,0 +1,331 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TemplateDiffService = void 0;
+exports.escapeForTemplate = escapeForTemplate;
+// ═══════════════════════════════════════════════════════════════════
+// TemplateDiffService
+//
+// T-8: String-based API — diffAndPatch()
+//   Given a template source like `input[data-role="${role}_legacy"]`,
+//   its resolved old string, and an AI-proposed new string, compute
+//   the patched template that preserves ${...} spans while updating
+//   only the changed static segments.
+//
+// T-8.1: Node-based API — computeNodePatch()
+//   Wraps diffAndPatch() using the TemplateExpression AST node as the
+//   source of truth (avoids text-parsing ambiguity). Returns the full
+//   patched template text for use with templateNode.replaceWithText().
+// ═══════════════════════════════════════════════════════════════════
+class TemplateDiffService {
+    // ─────────────────────────────────────────────────────────────────
+    // T-8: String-based API
+    //
+    // templateText: the template source (backticks optional), e.g.
+    //   `input[data-role="${role}_legacy"]`  or
+    //    input[data-role="${role}_legacy"]
+    // resolvedOld: what the template evaluates to at the failing call site
+    // resolvedNew: the AI-proposed replacement string (flat, no ${...})
+    // ─────────────────────────────────────────────────────────────────
+    static diffAndPatch(templateText, resolvedOld, resolvedNew) {
+        const segments = parseTemplateSource(templateText);
+        const staticSegs = segments
+            .filter((s) => s.type === "static")
+            .map((s) => s.text);
+        const exprSegs = segments
+            .filter((s) => s.type === "expr")
+            .map((s) => s.text);
+        // No spans — the "template" is just a plain string.
+        if (exprSegs.length === 0) {
+            if (resolvedOld !== resolvedNew) {
+                return {
+                    ok: true,
+                    patchedTemplate: "`" + escapeForTemplate(resolvedNew) + "`",
+                    changedSegmentIndices: [0],
+                };
+            }
+            return { ok: false, reason: "resolvedOld === resolvedNew — no change needed" };
+        }
+        // Extract span values from resolvedOld using static segments as anchors.
+        const spanValues = extractSpanValues(staticSegs, resolvedOld);
+        if (!spanValues) {
+            return {
+                ok: false,
+                reason: "template static segments don't align with resolvedOld — possible desync. " +
+                    `template="${templateText}", resolvedOld="${resolvedOld}"`,
+            };
+        }
+        // Verify reconstruction — extractSpanValues already guarantees this
+        // implicitly, but an explicit check catches any edge-case bugs early.
+        {
+            let check = "";
+            for (let i = 0; i < staticSegs.length; i++) {
+                check += staticSegs[i];
+                if (i < spanValues.length)
+                    check += spanValues[i];
+            }
+            if (check !== resolvedOld) {
+                return {
+                    ok: false,
+                    reason: `reconstruction mismatch: expected "${resolvedOld}", got "${check}"`,
+                };
+            }
+        }
+        // Align resolvedNew against the extracted span values.
+        const newStaticSegs = alignWithNew(spanValues, resolvedNew);
+        if (!newStaticSegs) {
+            return {
+                ok: false,
+                reason: `dynamic span value(s) [${spanValues.map((v) => `"${v}"`).join(", ")}] ` +
+                    `not found in resolvedNew="${resolvedNew}" — structural change, manual review required`,
+            };
+        }
+        if (newStaticSegs.length !== staticSegs.length) {
+            return {
+                ok: false,
+                reason: "static segment count mismatch after alignment — structural change",
+            };
+        }
+        // Diff: find which static segments changed.
+        const changedIndices = [];
+        for (let i = 0; i < staticSegs.length; i++) {
+            if (staticSegs[i] !== newStaticSegs[i])
+                changedIndices.push(i);
+        }
+        if (changedIndices.length === 0) {
+            return {
+                ok: false,
+                reason: "no static segment changed — the difference is in a dynamic span. " +
+                    "Update the argument passed to the function instead.",
+            };
+        }
+        if (changedIndices.length > 1) {
+            return {
+                ok: false,
+                reason: `${changedIndices.length} static segments changed simultaneously — ` +
+                    "ambiguous, manual review required",
+            };
+        }
+        // Build the patched template.
+        const patchedStatics = [...staticSegs];
+        patchedStatics[changedIndices[0]] = newStaticSegs[changedIndices[0]];
+        return {
+            ok: true,
+            patchedTemplate: buildTemplate(segments, patchedStatics),
+            changedSegmentIndices: changedIndices,
+        };
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // T-8.1: Node-based API
+    //
+    // Uses the TemplateExpression AST node as the authoritative source
+    // of static/expr segments (avoids text-parsing edge cases).
+    // Returns `patchedText` — pass directly to templateNode.replaceWithText().
+    // ─────────────────────────────────────────────────────────────────
+    static computeNodePatch(templateNode, resolvedOld, resolvedNew) {
+        // Extract static segments and expr texts directly from the AST.
+        const head = templateNode.getHead();
+        const spans = templateNode.getTemplateSpans();
+        const staticSegs = [head.getLiteralText()];
+        const exprTexts = [];
+        for (const span of spans) {
+            exprTexts.push(span.getExpression().getText());
+            staticSegs.push(span.getLiteral().getLiteralText());
+        }
+        // Rebuild equivalent segments array for buildTemplate().
+        const segments = [];
+        for (let i = 0; i < staticSegs.length; i++) {
+            segments.push({ type: "static", text: staticSegs[i] });
+            if (i < exprTexts.length) {
+                segments.push({ type: "expr", text: exprTexts[i] });
+            }
+        }
+        // No spans case.
+        if (exprTexts.length === 0) {
+            return {
+                ok: true,
+                patchedTemplate: "`" + escapeForTemplate(resolvedNew) + "`",
+                changedSegmentIndices: [0],
+            };
+        }
+        const spanValues = extractSpanValues(staticSegs, resolvedOld);
+        if (!spanValues) {
+            return {
+                ok: false,
+                reason: `template AST doesn't reconstruct to "${resolvedOld}"`,
+            };
+        }
+        const newStaticSegs = alignWithNew(spanValues, resolvedNew);
+        if (!newStaticSegs) {
+            const newSpanFromNew = extractSpanValues(staticSegs, resolvedNew);
+            return {
+                ok: false,
+                reason: `span values [${spanValues.map((v) => `"${v}"`).join(", ")}] ` +
+                    `not found in new selector "${resolvedNew}"`,
+                ...(newSpanFromNew ? { newSpanValues: newSpanFromNew } : {}),
+            };
+        }
+        const changedIndices = [];
+        for (let i = 0; i < staticSegs.length; i++) {
+            if (staticSegs[i] !== newStaticSegs[i])
+                changedIndices.push(i);
+        }
+        if (changedIndices.length === 0) {
+            return {
+                ok: false,
+                reason: "difference is in dynamic span — update call-site argument",
+            };
+        }
+        if (changedIndices.length > 1) {
+            return {
+                ok: false,
+                reason: `${changedIndices.length} static segments changed — ambiguous`,
+            };
+        }
+        const patchedStatics = [...staticSegs];
+        patchedStatics[changedIndices[0]] = newStaticSegs[changedIndices[0]];
+        return {
+            ok: true,
+            patchedTemplate: buildTemplate(segments, patchedStatics),
+            changedSegmentIndices: changedIndices,
+        };
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Extract span values from a TemplateExpression node and a resolved string.
+    // Public so callers can derive old/new span values for span tracing.
+    // ─────────────────────────────────────────────────────────────────
+    static extractNodeSpanValues(templateNode, resolved) {
+        const head = templateNode.getHead();
+        const spans = templateNode.getTemplateSpans();
+        const staticSegs = [head.getLiteralText()];
+        for (const span of spans) {
+            staticSegs.push(span.getLiteral().getLiteralText());
+        }
+        return extractSpanValues(staticSegs, resolved);
+    }
+}
+exports.TemplateDiffService = TemplateDiffService;
+// ═══════════════════════════════════════════════════════════════════
+// Private helpers
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * Parse a template literal source string into alternating static/expr segments.
+ * Strips surrounding backticks if present.
+ *
+ * `` `head${role}_tail` `` → [static:"head", expr:"role", static:"_tail"]
+ */
+function parseTemplateSource(text) {
+    let src = text.trim();
+    if (src.startsWith("`") && src.endsWith("`")) {
+        src = src.slice(1, -1);
+    }
+    const segments = [];
+    const exprPattern = /\$\{([^}]+)\}/g;
+    let lastIndex = 0;
+    let match;
+    while ((match = exprPattern.exec(src)) !== null) {
+        // Static segment before this expression.
+        segments.push({ type: "static", text: src.slice(lastIndex, match.index) });
+        segments.push({ type: "expr", text: match[1].trim() });
+        lastIndex = match.index + match[0].length;
+    }
+    // Trailing static segment (may be empty).
+    segments.push({ type: "static", text: src.slice(lastIndex) });
+    return segments;
+}
+/**
+ * Given the static segments of a template and a resolved string,
+ * extract the dynamic span values by matching statics as anchors.
+ *
+ * Algorithm: iterate over all static segments in order. After consuming
+ * each static segment, find the next static as the delimiter for the
+ * span value — then advance pos to the start of that next static so
+ * the following iteration can consume it. This ensures pos is always
+ * consistent at the start of each static segment.
+ *
+ * Returns null if alignment fails (desync or ambiguous adjacent spans).
+ */
+function extractSpanValues(staticSegments, resolved) {
+    const spanValues = [];
+    let pos = 0;
+    for (let i = 0; i < staticSegments.length; i++) {
+        // Consume static[i].
+        const s = staticSegments[i];
+        if (resolved.slice(pos, pos + s.length) !== s)
+            return null;
+        pos += s.length;
+        // If this is the last static segment, we're done.
+        if (i === staticSegments.length - 1)
+            break;
+        // Find span[i] value: delimited by static[i+1].
+        const nextStatic = staticSegments[i + 1];
+        if (nextStatic === "" && i + 1 === staticSegments.length - 1) {
+            // Empty trailing static: span value extends to end of string.
+            spanValues.push(resolved.slice(pos));
+            pos = resolved.length;
+            break;
+        }
+        if (nextStatic === "") {
+            // Empty non-trailing static: adjacent spans — boundary is ambiguous.
+            return null;
+        }
+        const delimIdx = resolved.indexOf(nextStatic, pos);
+        if (delimIdx === -1)
+            return null;
+        spanValues.push(resolved.slice(pos, delimIdx));
+        // Advance pos to start of nextStatic so the next iteration consumes it.
+        pos = delimIdx;
+    }
+    if (pos !== resolved.length)
+        return null;
+    return spanValues;
+}
+/**
+ * Given known span values (anchors) and a new resolved string,
+ * extract what the static segments should be in the patched template.
+ *
+ * Uses each span value as a positional anchor, in order.
+ * Returns null if any span value is missing from resolvedNew.
+ */
+function alignWithNew(spanValues, resolvedNew) {
+    const newStatics = [];
+    let pos = 0;
+    for (const spanVal of spanValues) {
+        if (spanVal.length === 0) {
+            // Can't anchor on empty span value.
+            return null;
+        }
+        const spanPos = resolvedNew.indexOf(spanVal, pos);
+        if (spanPos === -1)
+            return null;
+        newStatics.push(resolvedNew.slice(pos, spanPos));
+        pos = spanPos + spanVal.length;
+    }
+    // Last static segment: everything remaining in resolvedNew.
+    newStatics.push(resolvedNew.slice(pos));
+    return newStatics;
+}
+/**
+ * Reconstruct a full template literal string (with backticks) from
+ * alternating segments and new static values.
+ */
+function buildTemplate(segments, newStaticValues) {
+    let result = "`";
+    let staticIdx = 0;
+    for (const seg of segments) {
+        if (seg.type === "static") {
+            result += escapeForTemplate(newStaticValues[staticIdx++]);
+        }
+        else {
+            result += "${" + seg.text + "}";
+        }
+    }
+    result += "`";
+    return result;
+}
+/** Escape characters that would break a template literal. */
+function escapeForTemplate(text) {
+    return text
+        .replace(/\\/g, "\\\\")
+        .replace(/`/g, "\\`")
+        .replace(/\$\{/g, "\\${");
+}

package/dist/services/types.d.ts

@@ -0,0 +1,59 @@
+export interface DnaRecord {
+    key: string;
+    filePath: string;
+    testTitle: string;
+    sourceFile: string;
+    sourceLine: number;
+    selector: string;
+    tagName: string;
+    text: string | null;
+    lastHealed: string | null;
+    schemaVersion: number;
+    isOrphaned: boolean;
+    /** 'healed' = AI auto-fixed, pending human verification. 'broken' = AI failed. undefined = healthy/verified. */
+    status?: 'healed' | 'broken';
+}
+export interface DnaIndex {
+    generatedAt: string;
+    snapshotDir: string;
+    records: DnaRecord[];
+    stats: {
+        total: number;
+        orphaned: number;
+        healedLast7Days: number;
+        healedAllTime: number;
+    };
+}
+export interface DnaEditPatch {
+    key: string;
+    field: 'selector' | 'text' | 'tagName' | 'attributes' | 'anchors';
+    oldValue: unknown;
+    newValue: unknown;
+    applySourceUpdate: boolean;
+    locatorIndex: number;
+}
+export interface BulkUpdateJob {
+    oldSelector: string;
+    newSelector: string;
+    dryRun: boolean;
+    targets: DnaRecord[];
+    results: Array<{
+        key: string;
+        success: boolean;
+        reason: string;
+    }>;
+}
+export interface HealthReport {
+    generatedAt: string;
+    snapshotDir: string;
+    total: number;
+    orphaned: DnaRecord[];
+    unverifiedHeals: DnaRecord[];
+    recentlyHealed: DnaRecord[];
+    neverHealed: DnaRecord[];
+    topHealedFiles: Array<{
+        sourceFile: string;
+        count: number;
+    }>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/services/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/services/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,OAAO,CAAC;IACpB,gHAAgH;IAChH,MAAM,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;CAC9B;AAED,MAAM,WAAW,QAAQ;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,KAAK,EAAE;QACL,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,eAAe,EAAE,MAAM,CAAC;QACxB,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,CAAC;IAClE,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,OAAO,EAAE,KAAK,CAAC;QACb,GAAG,EAAE,MAAM,CAAC;QACZ,OAAO,EAAE,OAAO,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,SAAS,EAAE,CAAC;IACtB,eAAe,EAAE,SAAS,EAAE,CAAC;IAC7B,cAAc,EAAE,SAAS,EAAE,CAAC;IAC5B,WAAW,EAAE,SAAS,EAAE,CAAC;IACzB,cAAc,EAAE,KAAK,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC9D"}

package/dist/services/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/storage/SnapshotManager.d.ts

@@ -0,0 +1,5 @@
+export declare class SnapshotManager {
+    static save(filePath: string, data: any): Promise<void>;
+    static load(filePath: string): Promise<any>;
+}
+//# sourceMappingURL=SnapshotManager.d.ts.map

package/dist/storage/SnapshotManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SnapshotManager.d.ts","sourceRoot":"","sources":["../../src/storage/SnapshotManager.ts"],"names":[],"mappings":"AAIA,qBAAa,eAAe;WACb,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG;WAUhC,IAAI,CAAC,QAAQ,EAAE,MAAM;CAQnC"}

package/dist/storage/SnapshotManager.js

@@ -0,0 +1,31 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SnapshotManager = void 0;
+// src/storage/SnapshotManager.ts
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+class SnapshotManager {
+    static async save(filePath, data) {
+        try {
+            const dir = path_1.default.dirname(filePath);
+            await promises_1.default.mkdir(dir, { recursive: true });
+            await promises_1.default.writeFile(filePath, JSON.stringify(data, null, 2));
+        }
+        catch (error) {
+            console.error(`[Fixwright] Failed to save snapshot: ${error}`);
+        }
+    }
+    static async load(filePath) {
+        try {
+            const content = await promises_1.default.readFile(filePath, "utf-8");
+            return JSON.parse(content);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+exports.SnapshotManager = SnapshotManager;

package/dist/types/index.d.ts

@@ -0,0 +1,95 @@
+export interface AncestorNode {
+    tag: string;
+    id: string | null;
+    classes: string[];
+    /** "{tag}#{id}[{classes_sorted_asc}]" — stable fingerprint for drift comparison */
+    fingerprint: string;
+}
+export type GhostCondition = "G1_DISPLAY_NONE" | "G2_VISIBILITY_HIDDEN" | "G3_OPACITY_ZERO" | "G4_POINTER_EVENTS_NONE" | "G5_ZERO_AREA" | "G6_CONTENT_VISIBILITY_HIDDEN";
+export interface VisibilityInfo {
+    isGhost: boolean;
+    ghostReason: GhostCondition | null;
+    isOccluded: boolean;
+    /** Computed opacity at capture time (0–1). Ghost threshold: < 0.05. */
+    opacity: number;
+}
+export interface AnchorInfo {
+    /** Resolved via: aria-labelledby → aria-label → label[for] → implicit label → preceding sibling */
+    closestLabel: string | null;
+    /** Longest unique sibling cell text when element lives in a table row; null otherwise */
+    rowAnchor: string | null;
+    /** Up to 5 direct-sibling texts (< 100 chars each). Stored for inspection; not scored in v2. */
+    neighborTexts: string[];
+}
+/**
+ * Disk format for element snapshots.
+ *
+ * v1 snapshots (no schemaVersion field) carry only the original fields.
+ * v2 snapshots (schemaVersion: 2) add ancestry, visibility, anchors, and
+ * isInShadowDom.  v1 snapshots are migrated to v2 on load by SnapshotService.
+ */
+export interface ElementSnapshot {
+    tagName: string;
+    id: string | null;
+    text: string | null;
+    classes: string[];
+    attributes: Record<string, string>;
+    role: string | null;
+    parentContext: string;
+    timestamp: string;
+    rect?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    schemaVersion?: 1 | 2;
+    ancestry?: AncestorNode[];
+    visibility?: VisibilityInfo;
+    anchors?: AnchorInfo;
+    isInShadowDom?: boolean;
+}
+/** Narrowed type asserting that all v2 fields are present. */
+export type ElementSnapshotV2 = ElementSnapshot & {
+    schemaVersion: 2;
+    ancestry: AncestorNode[];
+    visibility: VisibilityInfo;
+    anchors: AnchorInfo;
+    isInShadowDom: boolean;
+};
+export declare function isSnapshotV2(s: ElementSnapshot): s is ElementSnapshotV2;
+export interface FixRequest {
+    targetIntent: string;
+    failedSelector: string;
+    previousState: object;
+    currentDom: string;
+}
+export interface FixResponse {
+    status: "FIXED" | "NOT_FOUND";
+    new_selector: string | null;
+    confidence: number;
+    explanation: string;
+}
+export interface ElementDNA {
+    tagName: string;
+    text: string;
+    attributes: Record<string, string>;
+    styles: {
+        backgroundColor: string;
+        color: string;
+        display: string;
+        visibility: string;
+    };
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    hierarchy: {
+        parentTag: string;
+        parentClass: string;
+        neighborTexts: string[];
+    };
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"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"}

package/dist/types/index.js

@@ -0,0 +1,7 @@
+"use strict";
+// ── DNA v2 Sub-types ─────────────────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSnapshotV2 = isSnapshotV2;
+function isSnapshotV2(s) {
+    return s.schemaVersion === 2 && Array.isArray(s.ancestry);
+}

package/dist/utils/DOMUtils.d.ts

@@ -0,0 +1,33 @@
+import { Page } from "@playwright/test";
+import { ElementDNA } from "../types";
+export declare class DOMUtils {
+    /**
+     * Sanitizes a Playwright selector (which may contain `>>`) into a CSS-safe
+     * selector by extracting only the last segment. Returns the last meaningful
+     * CSS part so querySelector can be used inside the correct context.
+     */
+    static sanitizeSelector(selector: string): string;
+    /**
+     * Given a Playwright `>>` selector, returns each segment in order.
+     * e.g. "#my-iframe >> #shadow-host >> #btn"
+     *   → ["#my-iframe", "#shadow-host", "#btn"]
+     */
+    static parseSegments(selector: string): string[];
+    static getNeighborhoodDom(page: Page, fullSelector: string): Promise<{
+        dom: string;
+        successfulPath: string[];
+    }>;
+    /**
+     * When a selector has multiple ">>" segments, the first segments are
+     * typically iframe selectors. This helper drills into the correct frame
+     * before running the DOM extraction.
+     */
+    private static _getNeighborhoodFromFrame;
+    /**
+     * Runs the neighborhood-DOM extraction script inside the given execution
+     * context (either a Page or a Frame).
+     */
+    private static _evaluateNeighborhood;
+    static getElementDNA: (page: Page, selector: string) => Promise<ElementDNA>;
+}
+//# sourceMappingURL=DOMUtils.d.ts.map

package/dist/utils/DOMUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DOMUtils.d.ts","sourceRoot":"","sources":["../../src/utils/DOMUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAEtC,qBAAa,QAAQ;IACnB;;;;OAIG;IACH,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAKjD;;;;OAIG;IACH,MAAM,CAAC,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE;WAM5B,kBAAkB,CACpC,IAAI,EAAE,IAAI,EACV,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAerD;;;;OAIG;mBACkB,yBAAyB;IAoD9C;;;OAGG;mBACkB,qBAAqB;IAmF1C,MAAM,CAAC,aAAa,GAClB,MAAM,IAAI,EACV,UAAU,MAAM,KACf,OAAO,CAAC,UAAU,CAAC,CAqCpB;CACH"}