sela-core 0.1.0-alpha.1

package/dist/services/Sanitizer.js

@@ -0,0 +1,142 @@
+"use strict";
+// src/services/Sanitizer.ts
+//
+// PII / secrets masking (T3). Pure, dependency-free string transforms — no
+// SDK, no config, no I/O — so it is trivially unit-testable in isolation.
+//
+// DESIGN: mask high-precision patterns + sensitive input VALUES only, never
+// blanket structural text. The healer locates elements by their anchors
+// (tag/role/id/class/data-testid/labels/headings/button text); masking those
+// would destroy the very signal the LLM needs. Credit cards, emails, tokens,
+// etc. essentially never serve as a meaningful element-locating anchor, so
+// masking them keeps false-positives near zero.
+//
+// Placeholders are DETERMINISTIC so the local healing cache key (computed on
+// pre-sanitization content) and LLM retry behavior stay reproducible.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REDACTIONS = void 0;
+exports.sanitizeText = sanitizeText;
+exports.compileCustomPatterns = compileCustomPatterns;
+const logger_1 = require("../utils/logger");
+exports.REDACTIONS = {
+    EMAIL: "[EMAIL_REDACTED]",
+    CREDIT_CARD: "[CC_REDACTED]",
+    CVV: "[CVV_REDACTED]",
+    PHONE: "[PHONE_REDACTED]",
+    PASSWORD: "[PASSWORD_REDACTED]",
+    BEARER: "[BEARER_REDACTED]",
+    TOKEN: "[TOKEN_REDACTED]",
+    GENERIC: "[REDACTED]",
+};
+// ── Luhn check — keeps credit-card masking precise (rejects random digit
+//    runs like timestamps / ids that merely look card-shaped). ───────────
+function luhnValid(digits) {
+    let sum = 0;
+    let alt = false;
+    for (let i = digits.length - 1; i >= 0; i--) {
+        let d = digits.charCodeAt(i) - 48;
+        if (d < 0 || d > 9)
+            return false;
+        if (alt) {
+            d *= 2;
+            if (d > 9)
+                d -= 9;
+        }
+        sum += d;
+        alt = !alt;
+    }
+    return sum % 10 === 0;
+}
+// ── Pattern table. ORDER MATTERS: most specific first so a broad pattern
+//    (phone) never swallows a more specific one (credit card). ───────────
+// Bearer auth header value.
+const BEARER_RE = /\bBearer\s+[A-Za-z0-9._~+/-]+=*/gi;
+// JSON Web Token (header.payload.signature).
+const JWT_RE = /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g;
+// Common API key prefixes (OpenAI sk-, Anthropic sk-ant-, GitHub ghp_/gho_…).
+const APIKEY_RE = /\b(?:sk-(?:ant-)?[A-Za-z0-9_-]{16,}|gh[pousr]_[A-Za-z0-9]{20,})\b/g;
+// Email address.
+const EMAIL_RE = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g;
+// Credit-card-shaped run of 13–19 digits, separators only BETWEEN digits
+// (never leading/trailing, so adjacent whitespace is preserved).
+const CC_RE = /\b\d(?:[ -]?\d){12,18}\b/g;
+// Labeled CVV/CVC (avoids masking every 3–4 digit number).
+const CVV_RE = /\b(cvv2?|cvc2?|cid)\b(\s*[:=]?\s*)(\d{3,4})\b/gi;
+// Phone number: optional +cc, optional area code, then 2+ separated groups.
+// No leading \b (a "+" prefix has no word boundary). Applied LAST.
+const PHONE_RE = /(?:\+\d{1,3}[\s.-]?)?(?:\(\d{1,4}\)[\s.-]?)?\d{2,4}(?:[\s.-]\d{2,4}){1,3}/g;
+/** Strip a leading "+" then non-digits, returning just the digit run. */
+function digitsOnly(s) {
+    return s.replace(/\D/g, "");
+}
+/**
+ * Mask PII/secrets in a single string. Pure — returns a new string; the input
+ * is never mutated. Safe to call on already-sanitized text (idempotent on the
+ * placeholders, which contain no maskable patterns).
+ */
+function sanitizeText(input, opts = {}) {
+    if (!input)
+        return input;
+    let out = input;
+    // 1. Input VALUES by type (structural) — run first so a password field
+    //    holding an email-looking value becomes [PASSWORD_REDACTED], not
+    //    [EMAIL_REDACTED]. Default on.
+    if (opts.redactInputValues !== false) {
+        out = maskInputValues(out);
+    }
+    // 2. Secrets / tokens (most specific).
+    out = out.replace(BEARER_RE, exports.REDACTIONS.BEARER);
+    out = out.replace(JWT_RE, exports.REDACTIONS.TOKEN);
+    out = out.replace(APIKEY_RE, exports.REDACTIONS.TOKEN);
+    // 3. Email.
+    out = out.replace(EMAIL_RE, exports.REDACTIONS.EMAIL);
+    // 4. Credit cards (Luhn-validated to avoid false positives).
+    out = out.replace(CC_RE, (m) => {
+        const d = digitsOnly(m);
+        return d.length >= 13 && d.length <= 19 && luhnValid(d)
+            ? exports.REDACTIONS.CREDIT_CARD
+            : m;
+    });
+    // 5. Labeled CVV — keep the label, mask the digits.
+    out = out.replace(CVV_RE, (_m, label, sep) => `${label}${sep}${exports.REDACTIONS.CVV}`);
+    // 6. Phone numbers (broadest among digit patterns — last).
+    out = out.replace(PHONE_RE, (m) => {
+        return digitsOnly(m).length >= 7 ? exports.REDACTIONS.PHONE : m;
+    });
+    // 7. Caller-supplied custom patterns.
+    for (const re of opts.customPatterns ?? []) {
+        out = out.replace(re, exports.REDACTIONS.GENERIC);
+    }
+    return out;
+}
+// ── <input> value masking by type ───────────────────────────────────────
+const INPUT_TAG_RE = /<input\b[^>]*>/gi;
+const TYPE_ATTR_RE = /\btype\s*=\s*["']?(password|tel|email)["']?/i;
+const VALUE_ATTR_RE = /(\bvalue\s*=\s*)(["'])(.*?)\2/i;
+const TYPE_TO_REDACTION = {
+    password: exports.REDACTIONS.PASSWORD,
+    tel: exports.REDACTIONS.PHONE,
+    email: exports.REDACTIONS.EMAIL,
+};
+function maskInputValues(html) {
+    return html.replace(INPUT_TAG_RE, (tag) => {
+        const typeMatch = TYPE_ATTR_RE.exec(tag);
+        if (!typeMatch)
+            return tag;
+        const redaction = TYPE_TO_REDACTION[typeMatch[1].toLowerCase()];
+        return tag.replace(VALUE_ATTR_RE, (_m, prefix, quote) => `${prefix}${quote}${redaction}${quote}`);
+    });
+}
+/** Compile customPatterns (regex source strings) → RegExp[]; skip invalid. */
+function compileCustomPatterns(sources) {
+    const out = [];
+    for (const src of sources) {
+        try {
+            out.push(new RegExp(src, "g"));
+        }
+        catch (e) {
+            logger_1.logger.warn(`Skipping invalid customPattern ${JSON.stringify(src)}: ${e.message}`);
+        }
+    }
+    return out;
+}

package/dist/services/SanitizingAnthropic.d.ts

@@ -0,0 +1,19 @@
+import Anthropic from "@anthropic-ai/sdk";
+import type { ResolvedSanitization } from "../config/SelaConfig";
+export interface CreateSanitizingAnthropicOptions {
+    /** API key for the underlying client (ignored when `inner` is supplied). */
+    apiKey?: string;
+    /** Pre-built client to wrap (tests / advanced callers). */
+    inner?: Anthropic;
+    /**
+     * Sanitization config. Defaults to `ConfigLoader.getInstance().sanitization`.
+     * When `enabled` is false the bare client is returned unwrapped.
+     */
+    sanitization?: ResolvedSanitization;
+}
+/**
+ * Returns an Anthropic client whose `messages.create` sanitizes outbound text.
+ * When sanitization is disabled, returns the underlying client unchanged.
+ */
+export declare function createSanitizingAnthropic(opts?: CreateSanitizingAnthropicOptions): Anthropic;
+//# sourceMappingURL=SanitizingAnthropic.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SanitizingAnthropic.d.ts","sourceRoot":"","sources":["../../src/services/SanitizingAnthropic.ts"],"names":[],"mappings":"AAYA,OAAO,SAAS,MAAM,mBAAmB,CAAC;AAE1C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAGjE,MAAM,WAAW,gCAAgC;IAC/C,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;;OAGG;IACH,YAAY,CAAC,EAAE,oBAAoB,CAAC;CACrC;AAmCD;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,GAAE,gCAAqC,GAC1C,SAAS,CA+BX"}

package/dist/services/SanitizingAnthropic.js

@@ -0,0 +1,84 @@
+"use strict";
+// src/services/SanitizingAnthropic.ts
+//
+// The single PII/secrets chokepoint (T3). Wraps an Anthropic client so EVERY
+// outbound `messages.create` has its `system` prompt and all message text
+// scrubbed before the HTTPS request — regardless of which service made the
+// call. This guarantees 100% coverage structurally instead of relying on each
+// call site (LLMService, IntentAuditor, future callers) remembering to mask.
+//
+// Both LLMService and IntentAuditor construct their client here. Tests that
+// inject a mock client via `opts.anthropic` bypass this factory entirely, so
+// they are unaffected; the wrapper itself is unit-tested in isolation.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSanitizingAnthropic = createSanitizingAnthropic;
+const sdk_1 = __importDefault(require("@anthropic-ai/sdk"));
+const ConfigLoader_1 = require("../config/ConfigLoader");
+const Sanitizer_1 = require("./Sanitizer");
+function readSanitization() {
+    try {
+        return ConfigLoader_1.ConfigLoader.getInstance().sanitization;
+    }
+    catch {
+        // Fail SECURE: if config can't load, default to masking on.
+        return { enabled: true, redactInputValues: true, customPatterns: [] };
+    }
+}
+/**
+ * Scrub a single `messages[].content` entry. Content may be a plain string or
+ * an array of content blocks; only text blocks are touched. Non-text blocks
+ * (images, tool_use, …) pass through untouched.
+ */
+function scrubContent(content, scrub) {
+    if (typeof content === "string")
+        return scrub(content);
+    if (Array.isArray(content)) {
+        return content.map((block) => {
+            if (block && block.type === "text" && typeof block.text === "string") {
+                return { ...block, text: scrub(block.text) };
+            }
+            return block;
+        });
+    }
+    return content;
+}
+/** Scrub the `system` field (string or array of text blocks). */
+function scrubSystem(system, scrub) {
+    if (system === undefined)
+        return system;
+    return scrubContent(system, scrub);
+}
+/**
+ * Returns an Anthropic client whose `messages.create` sanitizes outbound text.
+ * When sanitization is disabled, returns the underlying client unchanged.
+ */
+function createSanitizingAnthropic(opts = {}) {
+    const client = opts.inner ?? new sdk_1.default({ apiKey: opts.apiKey });
+    const cfg = opts.sanitization ?? readSanitization();
+    if (!cfg.enabled)
+        return client;
+    const customPatterns = (0, Sanitizer_1.compileCustomPatterns)(cfg.customPatterns ?? []);
+    const scrub = (s) => (0, Sanitizer_1.sanitizeText)(s, {
+        redactInputValues: cfg.redactInputValues,
+        customPatterns,
+    });
+    const messages = client.messages;
+    const original = messages.create.bind(messages);
+    messages.create = (params, requestOptions) => {
+        const scrubbed = {
+            ...params,
+            system: scrubSystem(params?.system, scrub),
+            messages: Array.isArray(params?.messages)
+                ? params.messages.map((m) => ({
+                    ...m,
+                    content: scrubContent(m?.content, scrub),
+                }))
+                : params?.messages,
+        };
+        return original(scrubbed, requestOptions);
+    };
+    return client;
+}

package/dist/services/SelectorSanitizer.d.ts

@@ -0,0 +1,52 @@
+/**
+ * True when `value` is (or contains, in a `>>` chain) a Playwright internal
+ * engine selector. These start with the `internal:` engine prefix.
+ */
+export declare function isInternalEngineSelector(value: string): boolean;
+interface MethodDescriptor {
+    method: string;
+    primaryArg: string;
+    options?: Record<string, string | boolean | number>;
+}
+/**
+ * Parse a SINGLE internal selector segment into a method descriptor, or null
+ * when it is not a recognised internal form (so callers REFUSE rather than
+ * guess). Mirrors the engine→public mapping used by ASTSourceUpdater.
+ */
+export declare function parseInternalSelector(selector: string): MethodDescriptor | null;
+export declare function buildMethodCall(receiver: string, desc: MethodDescriptor): string;
+/**
+ * Translate an internal selector string into an idiomatic Playwright method
+ * expression rooted at `receiver`. Handles `>>` chains by chaining each
+ * segment. Returns null when ANY segment is an unrecognised internal form
+ * (frame `internal:control=…` plumbing, unknown engines) — the caller must
+ * then refuse rather than emit something fragile.
+ */
+export declare function internalToMethodExpression(selector: string, receiver?: string): string | null;
+/**
+ * Convert an internal engine selector into a VALID PUBLIC `.locator()` string,
+ * preserving `>>` chaining. Returns null when ANY internal segment has no
+ * public string engine (so the caller must method-shift or refuse instead of
+ * stuffing an unusable string into a constant).
+ *
+ * Example: `internal:role=button[name="Update System"i]`
+ *        → `role=button[name="Update System"]`
+ */
+export declare function internalToPublicSelectorString(selector: string): string | null;
+export interface SanitizeResult {
+    /** The (possibly rewritten) expression text. */
+    text: string;
+    /** True when the original contained an internal selector that was rewritten. */
+    sanitized: boolean;
+    /** False when an internal selector remained that could NOT be translated. */
+    safe: boolean;
+}
+/**
+ * Rewrite any `recv.locator("internal:…")` / `recv.frameLocator("internal:…")`
+ * inside `expr` to its idiomatic method form. Returns `safe:false` when an
+ * internal selector remains that cannot be translated, so the caller refuses
+ * to write it.
+ */
+export declare function sanitizeLocatorExpression(expr: string): SanitizeResult;
+export {};
+//# sourceMappingURL=SelectorSanitizer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SelectorSanitizer.d.ts","sourceRoot":"","sources":["../../src/services/SelectorSanitizer.ts"],"names":[],"mappings":"AAoCA;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAK/D;AAMD,UAAU,gBAAgB;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC,CAAC;CACrD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CA6D/E;AAWD,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAyBhF;AAMD;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,MAAM,EAChB,QAAQ,SAAS,GAChB,MAAM,GAAG,IAAI,CAmBf;AAgDD;;;;;;;;GAQG;AACH,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAkB9E;AAMD,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,SAAS,EAAE,OAAO,CAAC;IACnB,6EAA6E;IAC7E,IAAI,EAAE,OAAO,CAAC;CACf;AAID;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAgEtE"}

package/dist/services/SelectorSanitizer.js

@@ -0,0 +1,318 @@
+"use strict";
+// src/services/SelectorSanitizer.ts
+//
+// THE ABSOLUTE RULE (Ticket #2 hardening):
+// Playwright's `internal:` engine selectors (e.g.
+// `internal:role=button[name="Update System"i]`) are a PRIVATE runtime
+// serialization. They must NEVER be written verbatim into user source — not
+// as a `.locator()` string argument, and not into a string-literal constant
+// consumed by `.locator()`. Although the engine happens to accept them at
+// runtime, they are undocumented, version-fragile, and leak internals into
+// the developer's clean code (bad DX, the exact bug this module prevents).
+//
+// This module is the single source of truth for:
+//   1. DETECTING an internal engine selector (`isInternalEngineSelector`).
+//   2. TRANSLATING it to the idiomatic public method form
+//      (`internalToMethodExpression`) — `getByRole(...)`, `getByText(...)`, …
+//   3. SANITIZING a full locator expression (`sanitizeLocatorExpression`):
+//      rewriting `recv.locator("internal:…")` → `recv.getByRole(…)`, and
+//      reporting whether anything internal remains (unconvertible ⇒ unsafe).
+//
+// Pure, dependency-light (ts-morph only for expression rewriting). Every
+// write-head (InitializerUpdater, MutationApplier, SourceUpdater regex gate)
+// consults this so the invariant holds across all heal paths.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isInternalEngineSelector = isInternalEngineSelector;
+exports.parseInternalSelector = parseInternalSelector;
+exports.buildMethodCall = buildMethodCall;
+exports.internalToMethodExpression = internalToMethodExpression;
+exports.internalToPublicSelectorString = internalToPublicSelectorString;
+exports.sanitizeLocatorExpression = sanitizeLocatorExpression;
+const ts_morph_1 = require("ts-morph");
+// ═══════════════════════════════════════════════════════════════════
+// DETECTION
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * True when `value` is (or contains, in a `>>` chain) a Playwright internal
+ * engine selector. These start with the `internal:` engine prefix.
+ */
+function isInternalEngineSelector(value) {
+    if (!value)
+        return false;
+    return value
+        .split(">>")
+        .some((seg) => seg.trim().toLowerCase().startsWith("internal:"));
+}
+/**
+ * Parse a SINGLE internal selector segment into a method descriptor, or null
+ * when it is not a recognised internal form (so callers REFUSE rather than
+ * guess). Mirrors the engine→public mapping used by ASTSourceUpdater.
+ */
+function parseInternalSelector(selector) {
+    // Match against the raw (trimmed) selector. The case-insensitivity `i` flag
+    // is significant per-pattern (trailing for text/label, inside `[…]` for
+    // role), so it must NOT be stripped globally up front.
+    const s = selector.trim();
+    // internal:role=button[name="X"i][level=2]
+    const roleMatch = s.match(/^internal:role=([a-zA-Z]+)(\[.*\])?$/);
+    if (roleMatch) {
+        const desc = {
+            method: "getByRole",
+            primaryArg: roleMatch[1],
+        };
+        const attrs = roleMatch[2] ?? "";
+        const nameMatch = attrs.match(/name="([^"]*)"(i)?/);
+        const options = {};
+        if (nameMatch) {
+            options.name = nameMatch[1];
+            if (!nameMatch[2])
+                options.exact = true; // no `i` flag → exact match
+        }
+        const levelMatch = attrs.match(/level=(\d+)/);
+        if (levelMatch)
+            options.level = Number(levelMatch[1]);
+        if (Object.keys(options).length)
+            desc.options = options;
+        return desc;
+    }
+    // internal:label="X"i  |  internal:label=X
+    const labelQuoted = s.match(/^internal:label="([^"]*)"(i)?$/);
+    if (labelQuoted) {
+        return labelQuoted[2]
+            ? { method: "getByLabel", primaryArg: labelQuoted[1] }
+            : { method: "getByLabel", primaryArg: labelQuoted[1], options: { exact: true } };
+    }
+    const labelBare = s.match(/^internal:label=([^[]+)$/);
+    if (labelBare) {
+        return { method: "getByLabel", primaryArg: labelBare[1].trim() };
+    }
+    // internal:text="X"i
+    const textMatch = s.match(/^internal:text="([^"]*)"(i)?$/);
+    if (textMatch) {
+        return textMatch[2]
+            ? { method: "getByText", primaryArg: textMatch[1] }
+            : { method: "getByText", primaryArg: textMatch[1], options: { exact: true } };
+    }
+    // internal:attr=[placeholder="X"] / [alt="X"] / [title="X"]
+    const placeholder = s.match(/^internal:attr=\[placeholder="([^"]*)"\]$/);
+    if (placeholder)
+        return { method: "getByPlaceholder", primaryArg: placeholder[1] };
+    const alt = s.match(/^internal:attr=\[alt="([^"]*)"\]$/);
+    if (alt)
+        return { method: "getByAltText", primaryArg: alt[1] };
+    const title = s.match(/^internal:attr=\[title="([^"]*)"\]$/);
+    if (title)
+        return { method: "getByTitle", primaryArg: title[1] };
+    // internal:testid=X  |  internal:attr=[data-testid="X"]
+    const testId = s.match(/^internal:testid=(.+)$/) ||
+        s.match(/^internal:attr=\[data-testid="([^"]*)"\]$/);
+    if (testId)
+        return { method: "getByTestId", primaryArg: testId[1].trim() };
+    return null; // unrecognised internal form → caller must refuse
+}
+// ═══════════════════════════════════════════════════════════════════
+// BUILD  (method descriptor → idiomatic call text)
+// ═══════════════════════════════════════════════════════════════════
+function q(s) {
+    // Prefer double quotes, escaping any embedded ones.
+    return `"${s.replace(/"/g, '\\"')}"`;
+}
+function buildMethodCall(receiver, desc) {
+    switch (desc.method) {
+        case "getByRole": {
+            const opts = [];
+            if (desc.options?.name !== undefined)
+                opts.push(`name: ${q(String(desc.options.name))}`);
+            if (desc.options?.exact === true)
+                opts.push(`exact: true`);
+            if (desc.options?.level !== undefined)
+                opts.push(`level: ${desc.options.level}`);
+            const optStr = opts.length ? `, { ${opts.join(", ")} }` : "";
+            return `${receiver}.getByRole(${q(desc.primaryArg)}${optStr})`;
+        }
+        case "getByText":
+        case "getByLabel": {
+            const exact = desc.options?.exact === true ? `, { exact: true }` : "";
+            return `${receiver}.${desc.method}(${q(desc.primaryArg)}${exact})`;
+        }
+        case "getByPlaceholder":
+        case "getByAltText":
+        case "getByTitle":
+        case "getByTestId":
+            return `${receiver}.${desc.method}(${q(desc.primaryArg)})`;
+        default:
+            return `${receiver}.locator(${q(desc.primaryArg)})`;
+    }
+}
+// ═══════════════════════════════════════════════════════════════════
+// TRANSLATE  (full internal selector string → method expression)
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * Translate an internal selector string into an idiomatic Playwright method
+ * expression rooted at `receiver`. Handles `>>` chains by chaining each
+ * segment. Returns null when ANY segment is an unrecognised internal form
+ * (frame `internal:control=…` plumbing, unknown engines) — the caller must
+ * then refuse rather than emit something fragile.
+ */
+function internalToMethodExpression(selector, receiver = "page") {
+    const segments = selector
+        .split(">>")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    if (segments.length === 0)
+        return null;
+    let expr = receiver;
+    for (const seg of segments) {
+        if (seg.toLowerCase().startsWith("internal:")) {
+            const desc = parseInternalSelector(seg);
+            if (!desc)
+                return null; // unconvertible internal form
+            expr = buildMethodCall(expr, desc);
+        }
+        else {
+            // Plain CSS / text segment — stays a public .locator() string.
+            expr = `${expr}.locator(${q(seg)})`;
+        }
+    }
+    return expr;
+}
+// ═══════════════════════════════════════════════════════════════════
+// TRANSLATE  (internal selector → valid PUBLIC .locator() string)
+// ═══════════════════════════════════════════════════════════════════
+function escAttr(s) {
+    return s.replace(/"/g, '\\"');
+}
+/**
+ * Convert a single internal segment to a valid PUBLIC `.locator()` selector
+ * string (the documented selector engines: `role=`, `text=`, css attribute).
+ * Returns null for forms that have NO public string engine (label is an
+ * associative relationship, not an attribute — only `getByLabel(...)` works).
+ */
+function segmentToPublicSelector(seg) {
+    const desc = parseInternalSelector(seg);
+    if (!desc)
+        return null;
+    switch (desc.method) {
+        case "getByRole": {
+            const attrs = [];
+            if (desc.options?.name !== undefined)
+                attrs.push(`name="${escAttr(String(desc.options.name))}"`);
+            if (desc.options?.level !== undefined)
+                attrs.push(`level=${desc.options.level}`);
+            const attrStr = attrs.length ? `[${attrs.join("][")}]` : "";
+            return `role=${desc.primaryArg}${attrStr}`;
+        }
+        case "getByText":
+            // Quoted text engine = exact-ish; unquoted = substring (i-flag default).
+            return desc.options?.exact
+                ? `text="${escAttr(desc.primaryArg)}"`
+                : `text=${desc.primaryArg}`;
+        case "getByPlaceholder":
+            return `[placeholder="${escAttr(desc.primaryArg)}"]`;
+        case "getByAltText":
+            return `[alt="${escAttr(desc.primaryArg)}"]`;
+        case "getByTitle":
+            return `[title="${escAttr(desc.primaryArg)}"]`;
+        case "getByTestId":
+            return `[data-testid="${escAttr(desc.primaryArg)}"]`;
+        case "getByLabel":
+        default:
+            return null; // no public string-engine equivalent
+    }
+}
+/**
+ * Convert an internal engine selector into a VALID PUBLIC `.locator()` string,
+ * preserving `>>` chaining. Returns null when ANY internal segment has no
+ * public string engine (so the caller must method-shift or refuse instead of
+ * stuffing an unusable string into a constant).
+ *
+ * Example: `internal:role=button[name="Update System"i]`
+ *        → `role=button[name="Update System"]`
+ */
+function internalToPublicSelectorString(selector) {
+    const segments = selector
+        .split(">>")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    if (segments.length === 0)
+        return null;
+    const out = [];
+    for (const seg of segments) {
+        if (seg.toLowerCase().startsWith("internal:")) {
+            const pub = segmentToPublicSelector(seg);
+            if (!pub)
+                return null;
+            out.push(pub);
+        }
+        else {
+            out.push(seg); // already a public css/text segment
+        }
+    }
+    return out.join(" >> ");
+}
+let probeCounter = 0;
+/**
+ * Rewrite any `recv.locator("internal:…")` / `recv.frameLocator("internal:…")`
+ * inside `expr` to its idiomatic method form. Returns `safe:false` when an
+ * internal selector remains that cannot be translated, so the caller refuses
+ * to write it.
+ */
+function sanitizeLocatorExpression(expr) {
+    // Fast path: nothing internal anywhere.
+    if (!expr.includes("internal:")) {
+        return { text: expr, sanitized: false, safe: true };
+    }
+    const project = new ts_morph_1.Project({
+        useInMemoryFileSystem: true,
+        compilerOptions: { allowJs: true, noEmit: true, skipLibCheck: true, noResolve: true },
+    });
+    let current = expr;
+    let sanitized = false;
+    // Iteratively rewrite the first internal locator call until none remain.
+    // replaceWithText invalidates nodes, so we re-parse each pass.
+    for (let pass = 0; pass < 32; pass++) {
+        let sf;
+        try {
+            sf = project.createSourceFile(`__san${probeCounter++}.ts`, `const __x = ${current};`, {
+                overwrite: true,
+            });
+        }
+        catch {
+            return { text: expr, sanitized, safe: false };
+        }
+        const call = sf
+            .getDescendantsOfKind(ts_morph_1.SyntaxKind.CallExpression)
+            .find((c) => {
+            const callee = c.getExpression();
+            if (!ts_morph_1.Node.isPropertyAccessExpression(callee))
+                return false;
+            const m = callee.getName();
+            if (m !== "locator" && m !== "frameLocator")
+                return false;
+            const arg = c.getArguments()[0];
+            if (!arg)
+                return false;
+            const lit = ts_morph_1.Node.isStringLiteral(arg) || ts_morph_1.Node.isNoSubstitutionTemplateLiteral(arg)
+                ? arg.getLiteralValue()
+                : null;
+            return lit !== null && isInternalEngineSelector(lit);
+        });
+        if (!call)
+            break; // no more internal locator calls
+        const callee = call.getExpression();
+        const receiver = callee.getExpression().getText();
+        const arg = call.getArguments()[0];
+        const internalSel = arg.getLiteralValue();
+        const methodExpr = internalToMethodExpression(internalSel, receiver);
+        if (!methodExpr) {
+            // Unconvertible — leave as-is and report unsafe.
+            return { text: current, sanitized, safe: false };
+        }
+        call.replaceWithText(methodExpr);
+        current = sf.getVariableDeclaration("__x").getInitializer().getText();
+        sanitized = true;
+    }
+    // Final integrity check: nothing internal must survive.
+    const safe = !isInternalEngineSelector(current) && !current.includes("internal:");
+    return { text: current, sanitized, safe };
+}

package/dist/services/SnapshotService.d.ts

@@ -0,0 +1,11 @@
+import { Page } from "@playwright/test";
+import { ElementSnapshot, ElementSnapshotV2 } from "../types";
+export declare class SnapshotService {
+    private baseDir;
+    constructor();
+    save(key: string, data: ElementSnapshot): Promise<void>;
+    load(key: string): Promise<ElementSnapshotV2 | null>;
+    captureElement(page: Page, selector: string, framePath?: string[]): Promise<ElementSnapshotV2 | null>;
+    private migrateToV2;
+}
+//# sourceMappingURL=SnapshotService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SnapshotService.d.ts","sourceRoot":"","sources":["../../src/services/SnapshotService.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAkB,MAAM,UAAU,CAAC;AAI9E,qBAAa,eAAe;IAC1B,OAAO,CAAC,OAAO,CAAS;;IASlB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAcvD,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAsBpD,cAAc,CAClB,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,MAAM,EAChB,SAAS,GAAE,MAAM,EAAO,GACvB,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAoRpC,OAAO,CAAC,WAAW;CAsBpB"}