sela-core 0.1.0-alpha.1

package/dist/engine/singleton.d.ts

@@ -0,0 +1,3 @@
+import { SelaEngine } from "./SelaEngine.js";
+export declare const sharedEngine: SelaEngine;
+//# sourceMappingURL=singleton.d.ts.map

package/dist/engine/singleton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"singleton.d.ts","sourceRoot":"","sources":["../../src/engine/singleton.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,eAAO,MAAM,YAAY,YAAmB,CAAC"}

package/dist/engine/singleton.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sharedEngine = void 0;
+const SelaEngine_js_1 = require("./SelaEngine.js");
+exports.sharedEngine = new SelaEngine_js_1.SelaEngine();

package/dist/errors/SelaError.d.ts

@@ -0,0 +1,146 @@
+export type SelaSubsystem = "SafetyGuard" | "IntentAuditor" | "ASTUpdater" | "Proxy" | "LLMService" | "Registry" | "ChainValidator" | "Engine" | "Report";
+export interface SelaErrorContext {
+    filePath?: string;
+    line?: number;
+    column?: number;
+    selector?: string;
+    healedSelector?: string;
+    stableId?: string;
+    testTitle?: string;
+    testFile?: string;
+    branch?: string;
+    /** SafetyGuard verdict level when the error originated in SafetyGuard. */
+    safetyLevel?: "BLOCKED" | "FAIL_HARD" | "REQUIRES_REVIEW" | "SAFE";
+    /** Auditor verdict surfaced in the context for SafetyGuard rejections. */
+    auditorVerdict?: "CONSISTENT" | "INCONSISTENT" | "SUSPICIOUS";
+    /** Raw + adjusted LLM confidence so downstream telemetry can plot drift. */
+    aiConfidence?: number;
+    auditorConfidence?: number;
+    /** Free-form extension slot. Prefer adding a named field above when possible. */
+    [key: string]: unknown;
+}
+export interface SelaErrorJSON {
+    name: string;
+    subsystem: SelaSubsystem;
+    code: string;
+    reason: string;
+    message: string;
+    context: SelaErrorContext;
+    stack?: string;
+    cause?: string;
+}
+export interface SelaErrorInit {
+    subsystem: SelaSubsystem;
+    /**
+     * Stable machine-readable error code. Must match `[A-Z][A-Z0-9_]+`.
+     * Recommended convention: short subsystem-prefix + verb/noun.
+     * See SELA_ERROR_CODES below for the canonical catalogue.
+     */
+    code: string;
+    /** Human-readable explanation. Becomes the tail of the formatted message. */
+    reason: string;
+    context?: SelaErrorContext;
+    /** Original error wrapped by this SelaError, if any. */
+    cause?: unknown;
+}
+export declare class SelaError extends Error {
+    readonly subsystem: SelaSubsystem;
+    readonly code: string;
+    readonly reason: string;
+    readonly context: SelaErrorContext;
+    constructor(init: SelaErrorInit);
+    static formatMessage(subsystem: SelaSubsystem, code: string, reason: string): string;
+    toJSON(): SelaErrorJSON;
+}
+export declare function isSelaError(err: unknown): err is SelaError;
+export declare function isSelaErrorFrom(err: unknown, subsystem: SelaSubsystem): err is SelaError;
+export declare const SAFETY_GUARD_CODES: {
+    readonly FAIL_HARD_VISIBILITY_GHOST: "SG_FAIL_HARD_VISIBILITY_GHOST";
+    readonly FAIL_HARD_VISIBILITY_OCCLUDED: "SG_FAIL_HARD_VISIBILITY_OCCLUDED";
+    readonly BLOCKED_LOW_CONFIDENCE: "SG_BLOCKED_LOW_CONFIDENCE";
+    readonly FAIL_HARD_SEMANTIC_INVERSION: "SG_FAIL_HARD_SEMANTIC_INVERSION";
+    readonly FAIL_HARD_STATUS_INVERSION: "SG_FAIL_HARD_STATUS_INVERSION";
+    readonly BLOCKED_ROLE_SWAP_ASSERTION: "SG_BLOCKED_ROLE_SWAP_ASSERTION";
+    readonly FAIL_HARD_AUDITOR_INCONSISTENT: "SG_FAIL_HARD_AUDITOR_INCONSISTENT";
+    readonly BLOCKED_AUDITOR_SUSPICIOUS: "SG_BLOCKED_AUDITOR_SUSPICIOUS";
+    /**
+     * Heal was REQUIRES_REVIEW → quarantined (decision #1): proposed but not
+     * written to source and not executed this run, pending explicit approval.
+     * Distinct from a block so the report renders it as an amber proposal.
+     */
+    readonly HELD_FOR_REVIEW: "SG_HELD_FOR_REVIEW";
+    /** Generic dispatcher when SafetyDecision arrives without an explicit code. */
+    readonly GENERIC_REJECTION: "SG_GENERIC_REJECTION";
+};
+export type SafetyGuardCode = (typeof SAFETY_GUARD_CODES)[keyof typeof SAFETY_GUARD_CODES];
+export declare const INTENT_AUDITOR_CODES: {
+    /** Caller asked for an audit but no Anthropic client was configured. */
+    readonly DISABLED: "IA_DISABLED";
+    readonly INVALID_JSON: "IA_INVALID_JSON";
+    readonly CALL_FAILED: "IA_CALL_FAILED";
+};
+export type IntentAuditorCode = (typeof INTENT_AUDITOR_CODES)[keyof typeof INTENT_AUDITOR_CODES];
+export declare const LLM_SERVICE_CODES: {
+    readonly NO_API_KEY: "LLM_NO_API_KEY";
+    readonly INVALID_JSON: "LLM_INVALID_JSON";
+    readonly MISSING_SEGMENTS: "LLM_MISSING_SEGMENTS";
+    readonly NOT_FOUND: "LLM_NOT_FOUND";
+    readonly API_CALL_FAILED: "LLM_API_CALL_FAILED";
+};
+export type LLMServiceCode = (typeof LLM_SERVICE_CODES)[keyof typeof LLM_SERVICE_CODES];
+export declare const AST_UPDATER_CODES: {
+    readonly UNSUPPORTED_NODE: "AST_UNSUPPORTED_NODE";
+    readonly TEMPLATE_LITERAL_SKIP: "AST_TEMPLATE_LITERAL_SKIP";
+    readonly CIRCULAR_RECEIVER: "AST_CIRCULAR_RECEIVER";
+    readonly DEFINITION_NOT_FOUND: "AST_DEFINITION_NOT_FOUND";
+    readonly MAX_DEPTH_EXCEEDED: "AST_MAX_DEPTH_EXCEEDED";
+    readonly SAVE_FAILED: "AST_SAVE_FAILED";
+    /**
+     * Developer pinned the failing statement with `// sela-fail-fast`.
+     * Heal pipeline is aborted before any LLM call; FailedEvent is
+     * recorded with category "Skipped by Developer".
+     */
+    readonly HEAL_DISABLED_BY_DIRECTIVE: "AST_HEAL_DISABLED_BY_DIRECTIVE";
+};
+export type ASTUpdaterCode = (typeof AST_UPDATER_CODES)[keyof typeof AST_UPDATER_CODES];
+export declare const PROXY_CODES: {
+    readonly FRAME_SCOPED: "PRX_FRAME_SCOPED";
+    readonly REBUILD_FAILED: "PRX_REBUILD_FAILED";
+    readonly NON_LOCATOR_TARGET: "PRX_NON_LOCATOR_TARGET";
+};
+export type ProxyCode = (typeof PROXY_CODES)[keyof typeof PROXY_CODES];
+export declare const REGISTRY_CODES: {
+    readonly CONTEXT_MISMATCH: "REG_CONTEXT_MISMATCH";
+    readonly FINGERPRINT_COLLISION: "REG_FINGERPRINT_COLLISION";
+};
+export type RegistryCode = (typeof REGISTRY_CODES)[keyof typeof REGISTRY_CODES];
+export declare const REPORT_CODES: {
+    /** Event passed to the validator was null, undefined, or not an object. */
+    readonly MALFORMED_EVENT: "REP_MALFORMED_EVENT";
+    /** Event.kind is not one of HEALED|FAILED|PROTECTED. */
+    readonly UNKNOWN_KIND: "REP_UNKNOWN_KIND";
+    /** Event is missing a field declared mandatory for its kind. */
+    readonly MISSING_FIELD: "REP_MISSING_FIELD";
+    /** Event contains a field of the wrong type. */
+    readonly INVALID_FIELD_TYPE: "REP_INVALID_FIELD_TYPE";
+    /** Disk write failed during flushToDisk(). */
+    readonly FLUSH_FAILED: "REP_FLUSH_FAILED";
+    /**
+     * A prior `.sela-history.json` existed on disk but could not be parsed as
+     * a JSON array. The merge path refuses to silently overwrite it with a
+     * fresh window (which would destroy the rolling history), so it aborts.
+     */
+    readonly HISTORY_CORRUPT: "REP_HISTORY_CORRUPT";
+    /** A shard report file existed but was not valid JSON / had no events array. */
+    readonly SHARD_UNREADABLE: "REP_SHARD_UNREADABLE";
+};
+export type ReportCode = (typeof REPORT_CODES)[keyof typeof REPORT_CODES];
+export declare const CHAIN_VALIDATOR_CODES: {
+    readonly TYPE_FLOW: "CV_TYPE_FLOW";
+    readonly SCHEMA: "CV_SCHEMA";
+    readonly RECEIVER: "CV_RECEIVER";
+    readonly PLACEMENT: "CV_PLACEMENT";
+    readonly SEMANTIC_DOWNGRADE: "CV_SEMANTIC_DOWNGRADE";
+};
+export type ChainValidatorCode = (typeof CHAIN_VALIDATOR_CODES)[keyof typeof CHAIN_VALIDATOR_CODES];
+//# sourceMappingURL=SelaError.d.ts.map

package/dist/errors/SelaError.d.ts.map

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

package/dist/errors/SelaError.js

@@ -0,0 +1,168 @@
+"use strict";
+// src/errors/SelaError.ts
+//
+// Structured error hierarchy for Sela.
+//
+// Every error thrown across the heal pipeline MUST be a SelaError so that:
+//   1. Callers can branch on `err.subsystem` and `err.code` without
+//      string-parsing `err.message`.
+//   2. Telemetry / report layers get a machine-readable JSON shape.
+//   3. The canonical message format is enforced by the constructor and
+//      cannot drift over time:  `[Sela-<Subsystem>] <CODE>: <reason>`
+//
+// Public message regex (used by tests/unit/engine/error-indicativity.test.ts):
+//   /^\[Sela-(SafetyGuard|IntentAuditor|ASTUpdater|Proxy|LLMService|Registry|ChainValidator|Engine)\] [A-Z][A-Z0-9_]+: .+$/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CHAIN_VALIDATOR_CODES = exports.REPORT_CODES = exports.REGISTRY_CODES = exports.PROXY_CODES = exports.AST_UPDATER_CODES = exports.LLM_SERVICE_CODES = exports.INTENT_AUDITOR_CODES = exports.SAFETY_GUARD_CODES = exports.SelaError = void 0;
+exports.isSelaError = isSelaError;
+exports.isSelaErrorFrom = isSelaErrorFrom;
+// ───────────────────────────────────────────────────────────────────
+// SelaError - single class for the whole hierarchy.
+//
+// We intentionally avoid a tree of subclasses; `instanceof SelaError` +
+// `err.subsystem === "X"` is more flexible for callers and keeps the
+// surface area tiny.
+// ───────────────────────────────────────────────────────────────────
+const CODE_PATTERN = /^[A-Z][A-Z0-9_]+$/;
+class SelaError extends Error {
+    subsystem;
+    code;
+    reason;
+    context;
+    constructor(init) {
+        if (!CODE_PATTERN.test(init.code)) {
+            throw new Error(`[SelaError] invalid code "${init.code}" - must match ${CODE_PATTERN}`);
+        }
+        const formatted = SelaError.formatMessage(init.subsystem, init.code, init.reason);
+        super(formatted);
+        this.name = `SelaError(${init.subsystem})`;
+        this.subsystem = init.subsystem;
+        this.code = init.code;
+        this.reason = init.reason;
+        this.context = init.context ?? {};
+        if (init.cause !== undefined) {
+            this.cause = init.cause;
+        }
+        // Maintain prototype chain through transpilation (ES5 target).
+        Object.setPrototypeOf(this, new.target.prototype);
+        if (typeof Error.captureStackTrace ===
+            "function") {
+            Error.captureStackTrace(this, new.target);
+        }
+    }
+    static formatMessage(subsystem, code, reason) {
+        return `[Sela-${subsystem}] ${code}: ${reason}`;
+    }
+    toJSON() {
+        return {
+            name: this.name,
+            subsystem: this.subsystem,
+            code: this.code,
+            reason: this.reason,
+            message: this.message,
+            context: this.context,
+            stack: this.stack,
+            cause: this.cause instanceof Error
+                ? this.cause.message
+                : undefined,
+        };
+    }
+}
+exports.SelaError = SelaError;
+// ───────────────────────────────────────────────────────────────────
+// Type guards
+// ───────────────────────────────────────────────────────────────────
+function isSelaError(err) {
+    return err instanceof SelaError;
+}
+function isSelaErrorFrom(err, subsystem) {
+    return err instanceof SelaError && err.subsystem === subsystem;
+}
+// ───────────────────────────────────────────────────────────────────
+// Canonical code catalogue
+//
+// Tests assert against these constants - never hand-write code strings
+// at throw sites.  Adding a new code requires adding it here first so
+// the catalogue stays in sync with the error-indicativity contract.
+// ───────────────────────────────────────────────────────────────────
+exports.SAFETY_GUARD_CODES = {
+    FAIL_HARD_VISIBILITY_GHOST: "SG_FAIL_HARD_VISIBILITY_GHOST",
+    FAIL_HARD_VISIBILITY_OCCLUDED: "SG_FAIL_HARD_VISIBILITY_OCCLUDED",
+    BLOCKED_LOW_CONFIDENCE: "SG_BLOCKED_LOW_CONFIDENCE",
+    FAIL_HARD_SEMANTIC_INVERSION: "SG_FAIL_HARD_SEMANTIC_INVERSION",
+    FAIL_HARD_STATUS_INVERSION: "SG_FAIL_HARD_STATUS_INVERSION",
+    BLOCKED_ROLE_SWAP_ASSERTION: "SG_BLOCKED_ROLE_SWAP_ASSERTION",
+    FAIL_HARD_AUDITOR_INCONSISTENT: "SG_FAIL_HARD_AUDITOR_INCONSISTENT",
+    BLOCKED_AUDITOR_SUSPICIOUS: "SG_BLOCKED_AUDITOR_SUSPICIOUS",
+    /**
+     * Heal was REQUIRES_REVIEW → quarantined (decision #1): proposed but not
+     * written to source and not executed this run, pending explicit approval.
+     * Distinct from a block so the report renders it as an amber proposal.
+     */
+    HELD_FOR_REVIEW: "SG_HELD_FOR_REVIEW",
+    /** Generic dispatcher when SafetyDecision arrives without an explicit code. */
+    GENERIC_REJECTION: "SG_GENERIC_REJECTION",
+};
+exports.INTENT_AUDITOR_CODES = {
+    /** Caller asked for an audit but no Anthropic client was configured. */
+    DISABLED: "IA_DISABLED",
+    INVALID_JSON: "IA_INVALID_JSON",
+    CALL_FAILED: "IA_CALL_FAILED",
+};
+exports.LLM_SERVICE_CODES = {
+    NO_API_KEY: "LLM_NO_API_KEY",
+    INVALID_JSON: "LLM_INVALID_JSON",
+    MISSING_SEGMENTS: "LLM_MISSING_SEGMENTS",
+    NOT_FOUND: "LLM_NOT_FOUND",
+    API_CALL_FAILED: "LLM_API_CALL_FAILED",
+};
+exports.AST_UPDATER_CODES = {
+    UNSUPPORTED_NODE: "AST_UNSUPPORTED_NODE",
+    TEMPLATE_LITERAL_SKIP: "AST_TEMPLATE_LITERAL_SKIP",
+    CIRCULAR_RECEIVER: "AST_CIRCULAR_RECEIVER",
+    DEFINITION_NOT_FOUND: "AST_DEFINITION_NOT_FOUND",
+    MAX_DEPTH_EXCEEDED: "AST_MAX_DEPTH_EXCEEDED",
+    SAVE_FAILED: "AST_SAVE_FAILED",
+    /**
+     * Developer pinned the failing statement with `// sela-fail-fast`.
+     * Heal pipeline is aborted before any LLM call; FailedEvent is
+     * recorded with category "Skipped by Developer".
+     */
+    HEAL_DISABLED_BY_DIRECTIVE: "AST_HEAL_DISABLED_BY_DIRECTIVE",
+};
+exports.PROXY_CODES = {
+    FRAME_SCOPED: "PRX_FRAME_SCOPED",
+    REBUILD_FAILED: "PRX_REBUILD_FAILED",
+    NON_LOCATOR_TARGET: "PRX_NON_LOCATOR_TARGET",
+};
+exports.REGISTRY_CODES = {
+    CONTEXT_MISMATCH: "REG_CONTEXT_MISMATCH",
+    FINGERPRINT_COLLISION: "REG_FINGERPRINT_COLLISION",
+};
+exports.REPORT_CODES = {
+    /** Event passed to the validator was null, undefined, or not an object. */
+    MALFORMED_EVENT: "REP_MALFORMED_EVENT",
+    /** Event.kind is not one of HEALED|FAILED|PROTECTED. */
+    UNKNOWN_KIND: "REP_UNKNOWN_KIND",
+    /** Event is missing a field declared mandatory for its kind. */
+    MISSING_FIELD: "REP_MISSING_FIELD",
+    /** Event contains a field of the wrong type. */
+    INVALID_FIELD_TYPE: "REP_INVALID_FIELD_TYPE",
+    /** Disk write failed during flushToDisk(). */
+    FLUSH_FAILED: "REP_FLUSH_FAILED",
+    /**
+     * A prior `.sela-history.json` existed on disk but could not be parsed as
+     * a JSON array. The merge path refuses to silently overwrite it with a
+     * fresh window (which would destroy the rolling history), so it aborts.
+     */
+    HISTORY_CORRUPT: "REP_HISTORY_CORRUPT",
+    /** A shard report file existed but was not valid JSON / had no events array. */
+    SHARD_UNREADABLE: "REP_SHARD_UNREADABLE",
+};
+exports.CHAIN_VALIDATOR_CODES = {
+    TYPE_FLOW: "CV_TYPE_FLOW",
+    SCHEMA: "CV_SCHEMA",
+    RECEIVER: "CV_RECEIVER",
+    PLACEMENT: "CV_PLACEMENT",
+    SEMANTIC_DOWNGRADE: "CV_SEMANTIC_DOWNGRADE",
+};

package/dist/fixtures/expectProxy.d.ts

@@ -0,0 +1,12 @@
+import { Locator } from "@playwright/test";
+import { SelaEngine } from "../engine/SelaEngine";
+/**
+ * createHealingExpect - drop-in replacement for Playwright's expect().
+ *
+ * @param resolveProxy  Optional callback that unwraps a Sela proxy
+ * to its current live Locator. Supplied by
+ * fixtures/index.ts which owns proxyToActiveLocator.
+ */
+export declare function createHealingExpect(engine: SelaEngine, page: import("@playwright/test").Page, filePath: string, initialLine: number, // השורה מהפיקסצ'ר (לרוב תהיה לא מדויקת או 0)
+resolveProxy?: (value: unknown) => Locator | null): (locatorOrValue: unknown) => any;
+//# sourceMappingURL=expectProxy.d.ts.map

package/dist/fixtures/expectProxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expectProxy.d.ts","sourceRoot":"","sources":["../../src/fixtures/expectProxy.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,OAAO,EAER,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAkOlD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,OAAO,kBAAkB,EAAE,IAAI,EACrC,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EAAE,6CAA6C;AAClE,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,GAAG,IAAI,GAChD,CAAC,cAAc,EAAE,OAAO,KAAK,GAAG,CAsElC"}

package/dist/fixtures/expectProxy.js

@@ -0,0 +1,246 @@
+"use strict";
+// src/fixtures/expectProxy.ts - full replacement
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHealingExpect = createHealingExpect;
+const test_1 = require("@playwright/test");
+const HealingRegistry_1 = require("../engine/HealingRegistry");
+const proxyTag_1 = require("./proxyTag");
+const logger_1 = require("../utils/logger");
+const ELEMENT_NOT_FOUND_PATTERNS = [
+    /element.*not found/i,
+    /locator.*resolved to.*\d+ element/i,
+    /waiting for.*locator/i,
+    /timeout.*exceeded/i,
+];
+function isElementNotFoundError(err) {
+    if (!(err instanceof Error))
+        return false;
+    return ELEMENT_NOT_FOUND_PATTERNS.some((p) => p.test(err.message));
+}
+/**
+ * Returns true only for genuine Playwright Locator instances -
+ * not FrameLocator proxies or Sela proxy objects.
+ *
+ * A real Locator has _frame internally.
+ * A FrameLocator has _frameSelector instead.
+ * We must NOT intercept frame-scoped locators because we cannot
+ * safely rebuild them from a bare selector string on page.locator().
+ */
+function isRealLocator(value) {
+    if (value === null || value === undefined)
+        return false;
+    if (typeof value !== "object")
+        return false;
+    // Sela locator proxies expose `_selaSelector`. The proxy forwards
+    // `_frame` via Reflect.get so `hasFrame` would lie - explicitly reject them
+    // here. Callers should unwrap via `resolveProxy` first.
+    if (value._selaSelector !== undefined)
+        return false;
+    const hasFrame = value._frame !== undefined ||
+        value._impl?._frame !== undefined;
+    const isFrameLocator = value._frameSelector !== undefined ||
+        value._impl?._frameSelector !== undefined;
+    return hasFrame && !isFrameLocator;
+}
+/**
+ * Detect whether a locator is frame-scoped by checking its internal
+ * selector string for frame-related segments.
+ */
+function isFrameScopedLocator(locator) {
+    const sel = locator._selector ?? locator["_impl"]?._selector ?? "";
+    return (typeof sel === "string" &&
+        (sel.includes("internal:control=enter-frame") ||
+            sel.includes(">> internal:control=enter-frame")));
+}
+/**
+ * Extracts the internal Playwright selector string from a real Locator.
+ */
+function extractSelectorFromLocator(locator) {
+    const internal = locator._selector ?? locator["_impl"]?._selector;
+    return typeof internal === "string" ? internal : null;
+}
+/**
+ * Rebuild a locator from a healed selector string that may contain
+ * frame segments (e.g. "#modern-frame-container >> #status-label-v2").
+ *
+ * A plain page.locator() call with a frame >> element string is NOT
+ * a valid locator for frame content - Playwright rejects it with
+ * "toHaveText can be only used with Locator object".
+ *
+ * This function correctly chains frameLocator() calls for each frame
+ * segment, then calls .locator() for the final element segment.
+ *
+ * Convention used by SelaEngine segments:
+ *   - Frame segments look like CSS selectors for iframes (#id, .class)
+ *     but produce a FrameLocator, not a Locator.
+ *   - The last segment is always the element selector.
+ *   - "internal:control=enter-frame" segments are implicit in
+ *     Playwright's FrameLocator and should be skipped.
+ *
+ * Examples:
+ *   "#modern-frame-container >> #status-label-v2"
+ *   → page.frameLocator("#modern-frame-container").locator("#status-label-v2")
+ *
+ *   "#outer >> #inner-frame >> .button"
+ *   → page.frameLocator("#outer").frameLocator("#inner-frame").locator(".button")
+ *
+ *   "#simple-element"
+ *   → page.locator("#simple-element")
+ */
+function rebuildLocator(page, healedSelector) {
+    // --- הוספת השורה הזו ---
+    // מוודא שאנחנו עובדים עם האובייקט האמיתי של פליירייט ולא עם הפרוקסי שלנו
+    const rawPage = page._rawPage || page;
+    const segments = healedSelector
+        .split(" >> ")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0 && s !== "internal:control=enter-frame");
+    if (segments.length === 0)
+        return rawPage.locator(healedSelector);
+    if (segments.length === 1)
+        return rawPage.locator(segments[0]);
+    const frameSegments = segments.slice(0, segments.length - 1);
+    const elementSegment = segments[segments.length - 1];
+    let context = null;
+    for (const frameSel of frameSegments) {
+        if (context === null) {
+            context = rawPage.frameLocator(frameSel);
+        }
+        else {
+            context = context.frameLocator(frameSel);
+        }
+    }
+    // כאן אנחנו מחזירים לוקטור שנוצר ישירות מה-rawPage
+    return context.locator(elementSegment);
+}
+/**
+ * Wrap a single matcher so that element-not-found errors trigger the
+ * heal cycle and retry the assertion once on the correctly rebuilt locator.
+ */
+function wrapMatcher(matcher, locator, matcherName, engine, page, ctx) {
+    return (async (...args) => {
+        try {
+            return await matcher(...args);
+        }
+        catch (err) {
+            if (!isElementNotFoundError(err))
+                throw err;
+            const rawSelector = extractSelectorFromLocator(locator);
+            if (!rawSelector)
+                throw err;
+            logger_1.logger.debug(`Assertion failed for "${rawSelector}", attempting heal…`);
+            // Fast path - already healed in this test via registry
+            const resolved = HealingRegistry_1.HealingRegistry.getInstance().resolveSelector(rawSelector, ctx);
+            let healedSelector = resolved;
+            if (resolved === rawSelector) {
+                // Slow path - ask the engine + LLM.
+                // engine.heal() writes the fix to disk AND returns the canonical
+                // healedLocatorString from SourceUpdater - the exact same string
+                // that was saved to the file.  This is the handshake that guarantees
+                // disk and runtime are in sync (no "ghost failures").
+                const stableId = require("crypto")
+                    .createHash("md5")
+                    .update(rawSelector)
+                    .digest("hex");
+                try {
+                    healedSelector = await engine.heal(page, rawSelector, rawSelector, stableId, ctx.filePath, ctx.line, "assertion");
+                }
+                catch (healErr) {
+                    if (healErr instanceof Error &&
+                        healErr.message.includes("[SafetyGuard]")) {
+                        throw healErr;
+                    }
+                    throw err;
+                }
+            }
+            if (!healedSelector || healedSelector === rawSelector)
+                throw err;
+            // Rebuild the locator from the canonical selector returned by the
+            // updater.  rebuildLocator() correctly chains frameLocator() calls
+            // for each frame segment, then .locator() for the final element,
+            // ensuring page/frame/locator variables are scoped correctly at runtime.
+            const newLocator = rebuildLocator(page, healedSelector);
+            const newExpectation = (0, test_1.expect)(newLocator);
+            const retryMatcher = newExpectation[matcherName];
+            if (typeof retryMatcher !== "function")
+                throw err;
+            logger_1.logger.debug(`Retrying assertion with healed selector: "${healedSelector}"`);
+            return await retryMatcher.apply(newExpectation, args);
+        }
+    });
+}
+const WRAPPED_MATCHERS = [
+    "toBeVisible",
+    "toBeHidden",
+    "toBeEnabled",
+    "toBeDisabled",
+    "toHaveText",
+    "toContainText",
+    "toHaveValue",
+    "toHaveAttribute",
+    "toHaveCount",
+    "toBeChecked",
+    "toBeFocused",
+];
+/**
+ * createHealingExpect - drop-in replacement for Playwright's expect().
+ *
+ * @param resolveProxy  Optional callback that unwraps a Sela proxy
+ * to its current live Locator. Supplied by
+ * fixtures/index.ts which owns proxyToActiveLocator.
+ */
+function createHealingExpect(engine, page, filePath, initialLine, // השורה מהפיקסצ'ר (לרוב תהיה לא מדויקת או 0)
+resolveProxy) {
+    return function expect(locatorOrValue) {
+        // 1. חילוץ דינמי של שורת הקוד האמיתית בזמן קריאת ה-expect
+        const getCallerLine = () => {
+            const err = new Error();
+            const stack = err.stack?.split("\n") || [];
+            // מחפשים את הקריאה הראשונה בשרשרת שמגיעה מקובץ הטסט ולא מקובץ הפרוקסי
+            const specLine = stack.find((l) => l.includes(filePath) && !l.includes("expectProxy"));
+            if (specLine) {
+                const match = specLine.match(/:(\d+):(\d+)/);
+                return match ? parseInt(match[1], 10) : initialLine;
+            }
+            return initialLine;
+        };
+        const actualLine = getCallerLine(); // כאן אנחנו מקבלים את השורה הנכונה!
+        // Step 1 - unwrap Sela proxy to real active Locator
+        let resolved = locatorOrValue;
+        if (resolveProxy) {
+            const unwrapped = resolveProxy(locatorOrValue);
+            if (unwrapped)
+                resolved = unwrapped;
+        }
+        const base = (0, test_1.expect)(resolved);
+        // Defensive: if for any reason `base` is not an object, return it as-is
+        // rather than crashing inside `new Proxy(...)`.
+        if (base === null || typeof base !== "object") {
+            return base;
+        }
+        // Step 2 - only wrap matchers for genuine page-level Locator objects.
+        if (!isRealLocator(resolved)) {
+            return base;
+        }
+        const locator = resolved;
+        // משתמשים בשורה האמיתית שחילצנו עבור ה-Context שמועבר ל-Engine
+        const ctx = { filePath, line: actualLine };
+        const proxy = new Proxy(base, {
+            get(target, prop) {
+                // Sela proxy identity - honored before any string-only branch so
+                // callers can detect a Sela expect proxy via Symbol.for("sela.proxy").
+                if (prop === proxyTag_1.SELA_PROXY)
+                    return "expect";
+                if (typeof prop !== "string")
+                    return target[prop];
+                const val = target[prop];
+                if (typeof val === "function" &&
+                    WRAPPED_MATCHERS.includes(prop)) {
+                    return wrapMatcher(val.bind(target), locator, prop, engine, page, ctx);
+                }
+                return val;
+            },
+        });
+        return proxy;
+    };
+}

package/dist/fixtures/index.d.ts

@@ -0,0 +1,30 @@
+import { Locator, Page } from "@playwright/test";
+import { createHealingExpect } from "./expectProxy";
+export declare function resolveSelaProxy(value: unknown): Locator | null;
+export declare function createFrameLocatorProxy(rawFrameLocator: any, frameSelector: string, rawPage: Page, testTitle: string, actionCounter: {
+    value: number;
+}, parentChain: string): any;
+export declare function createLocatorProxy(rawLocator: Locator, selector: string, rawPage: Page, testTitle: string, actionCounter: {
+    value: number;
+}, elementSelectorOnly?: string): any;
+export declare const test: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & {
+    expect: ReturnType<typeof createHealingExpect>;
+}, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions & {
+    /**
+     * Worker-scoped lifecycle anchor. Its teardown runs EXACTLY ONCE per
+     * worker process - after every test in that worker has finished - which
+     * is the only correct place to flush the suite-wide healing report.
+     *
+     * Why a worker fixture and not the reporter's onEnd():
+     *   Playwright runs tests in worker processes; the reporter lives in the
+     *   main process. The `sharedHealReport` buffer, `HealingRegistry`, and
+     *   `sharedWorkspaceSnapshot` singletons that accumulate heal events all
+     *   live in the WORKER. The main-process reporter cannot see them, so the
+     *   flush MUST happen worker-side. The reporter's cross-process
+     *   PendingPromptLedger (written here, drained in onEnd) is what carries
+     *   the DX-review summary back to the main process.
+     */
+    _selaWorkerLifecycle: void;
+}>;
+export { createHealingExpect } from "./expectProxy";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/fixtures/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAK/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAYpD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI,CAI/D;AA2jBD,wBAAgB,uBAAuB,CACrC,eAAe,EAAE,GAAG,EACpB,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,IAAI,EACb,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,EAChC,WAAW,EAAE,MAAM,GAClB,GAAG,CAuCL;AAaD,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,OAAO,EACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,IAAI,EACb,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,EAChC,mBAAmB,CAAC,EAAE,MAAM,GAC3B,GAAG,CAkPL;AAQD,eAAO,MAAM,IAAI;YAEL,UAAU,CAAC,OAAO,mBAAmB,CAAC;;IAG9C;;;;;;;;;;;;;OAaG;0BACmB,IAAI;EAmI5B,CAAC;AAGH,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC"}