swipium 1.1.0 → 1.2.0

package/dist/automation/report.js

@@ -0,0 +1,83 @@
+// Automation Kernel V2 — Workstream 9: Automation Readiness Output. Turns an AutomationPlan into one
+// consistent response shape with natural-language messages a coding agent can repeat verbatim to the
+// user. The canonical phrases below match the plan's required wording for each backend/fallback case.
+import { isVisualStrategy } from './types.js';
+// Canonical phrases (plan Workstream 9 — "Required phrases").
+const PHRASE = {
+    iosRawSimulator: 'I can launch and inspect the app in the iOS simulator, but this backend cannot run structured taps. Attach WDA or Appium for selector-based automation.',
+    androidDirect: 'I can run this on Android using resource-id/accessibility/text selectors. Unicode text input needs a stronger backend or fixture adjustment.',
+    appiumRequired: 'This flow needs an Appium backend because it uses a WebView context or gesture that the current backend cannot perform.',
+    visualFallback: 'I can continue with visual/OCR evidence, but that is candidate-level evidence and not a structured locator proof.',
+};
+// Structured interaction/assertion kinds — the ones that produce structured-locator proof. Lifecycle
+// and control steps (openUrl, pressKey, waitForIdle, lifecycle) do NOT make a flow "ready" on their own.
+const STRUCTURED_PROOF_KINDS = new Set([
+    'tap', 'longPress', 'doubleTap', 'inputText', 'clearText', 'scrollUntilVisible',
+    'swipe', 'drag', 'pinch', 'waitForVisible', 'waitForNotVisible', 'assertVisible',
+]);
+function providesStructuredProof(step) {
+    if (step.support !== 'native' && step.support !== 'supported_with_fallback')
+        return false;
+    if (!STRUCTURED_PROOF_KINDS.has(step.action.kind))
+        return false;
+    const sel = step.action.selector;
+    if (sel && (isVisualStrategy(sel.strategy) || sel.strategy === 'coordinate'))
+        return false;
+    return true;
+}
+function statusFor(plan) {
+    if (!plan.executable)
+        return 'blocked';
+    const hasStructured = plan.steps.some(providesStructuredProof);
+    const hasVisualOnly = plan.steps.some((s) => s.support === 'visual_only');
+    if (!hasStructured && hasVisualOnly)
+        return 'candidate';
+    return 'ready';
+}
+function fallbackUsed(plan) {
+    if (plan.backend === 'ios-raw-simulator' && statusFor(plan) !== 'ready')
+        return 'ios-raw-simulator';
+    if (plan.blockers.some((b) => /appium|webview|context/i.test(`${b.detail} ${b.nextStep}`)))
+        return 'appium-required';
+    if (plan.steps.some((s) => s.support === 'visual_only'))
+        return 'visual-only';
+    return 'none';
+}
+function headlineFor(status, backend) {
+    const label = status === 'ready' ? 'Ready' : status === 'candidate' ? 'Candidate-only' : 'Blocked';
+    return `${label} on ${backend}`;
+}
+/** Build the natural-language agent message, preferring the plan's required canonical phrasing. */
+function agentMessageFor(plan, status) {
+    const fallback = fallbackUsed(plan);
+    const parts = [plan.agentMessage];
+    if (plan.backend === 'ios-raw-simulator' && status !== 'ready')
+        parts.push(PHRASE.iosRawSimulator);
+    if (plan.backend === 'android-direct')
+        parts.push(PHRASE.androidDirect);
+    if (fallback === 'appium-required')
+        parts.push(PHRASE.appiumRequired);
+    if (fallback === 'visual-only' || status === 'candidate')
+        parts.push(PHRASE.visualFallback);
+    // De-duplicate while preserving order.
+    return [...new Set(parts.filter(Boolean))].join(' ');
+}
+export function buildReadiness(plan) {
+    const status = statusFor(plan);
+    const supportedSteps = plan.steps.filter((s) => s.support !== 'unsupported').length;
+    const unsupportedSteps = plan.steps.filter((s) => s.support === 'unsupported').length;
+    return {
+        status,
+        headline: headlineFor(status, plan.backend),
+        agentMessage: agentMessageFor(plan, status),
+        developerMessage: plan.developerMessage,
+        backend: plan.backend,
+        supportedSteps,
+        unsupportedSteps,
+        blockers: plan.blockers,
+        warnings: plan.warnings,
+        fallbackUsed: fallbackUsed(plan),
+    };
+}
+export { PHRASE as READINESS_PHRASES };
+//# sourceMappingURL=report.js.map

package/dist/automation/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../src/automation/report.ts"],"names":[],"mappings":"AAAA,qGAAqG;AACrG,qGAAqG;AACrG,sGAAsG;AAGtG,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C,8DAA8D;AAC9D,MAAM,MAAM,GAAG;IACb,eAAe,EACb,yJAAyJ;IAC3J,aAAa,EACX,8IAA8I;IAChJ,cAAc,EACZ,yHAAyH;IAC3H,cAAc,EACZ,mHAAmH;CAC7G,CAAC;AAEX,qGAAqG;AACrG,yGAAyG;AACzG,MAAM,sBAAsB,GAAG,IAAI,GAAG,CAAa;IACjD,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,oBAAoB;IAC/E,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,eAAe;CACjF,CAAC,CAAC;AAEH,SAAS,uBAAuB,CAAC,IAAc;IAC7C,IAAI,IAAI,CAAC,OAAO,KAAK,QAAQ,IAAI,IAAI,CAAC,OAAO,KAAK,yBAAyB;QAAE,OAAO,KAAK,CAAC;IAC1F,IAAI,CAAC,sBAAsB,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IAChE,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC;IACjC,IAAI,GAAG,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC,QAAQ,KAAK,YAAY,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3F,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,SAAS,CAAC,IAAoB;IACrC,IAAI,CAAC,IAAI,CAAC,UAAU;QAAE,OAAO,SAAS,CAAC;IACvC,MAAM,aAAa,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;IAC/D,MAAM,aAAa,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,aAAa,CAAC,CAAC;IAC1E,IAAI,CAAC,aAAa,IAAI,aAAa;QAAE,OAAO,WAAW,CAAC;IACxD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,YAAY,CAAC,IAAoB;IACxC,IAAI,IAAI,CAAC,OAAO,KAAK,mBAAmB,IAAI,SAAS,CAAC,IAAI,CAAC,KAAK,OAAO;QAAE,OAAO,mBAAmB,CAAC;IACpG,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,yBAAyB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;QAAE,OAAO,iBAAiB,CAAC;IACrH,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,aAAa,CAAC;QAAE,OAAO,aAAa,CAAC;IAC9E,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,WAAW,CAAC,MAAwB,EAAE,OAA0B;IACvE,MAAM,KAAK,GAAG,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,SAAS,CAAC;IACnG,OAAO,GAAG,KAAK,OAAO,OAAO,EAAE,CAAC;AAClC,CAAC;AAED,mGAAmG;AACnG,SAAS,eAAe,CAAC,IAAoB,EAAE,MAAwB;IACrE,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IACpC,MAAM,KAAK,GAAa,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAE5C,IAAI,IAAI,CAAC,OAAO,KAAK,mBAAmB,IAAI,MAAM,KAAK,OAAO;QAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;IACnG,IAAI,IAAI,CAAC,OAAO,KAAK,gBAAgB;QAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;IACxE,IAAI,QAAQ,KAAK,iBAAiB;QAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;IACtE,IAAI,QAAQ,KAAK,aAAa,IAAI,MAAM,KAAK,WAAW;QAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;IAE5F,uCAAuC;IACvC,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAoB;IACjD,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,cAAc,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,aAAa,CAAC,CAAC,MAAM,CAAC;IACpF,MAAM,gBAAgB,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,aAAa,CAAC,CAAC,MAAM,CAAC;IACtF,OAAO;QACL,MAAM;QACN,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC;QAC3C,YAAY,EAAE,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC;QAC3C,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;QACvC,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,cAAc;QACd,gBAAgB;QAChB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,YAAY,EAAE,YAAY,CAAC,IAAI,CAAC;KACjC,CAAC;AACJ,CAAC;AAED,OAAO,EAAE,MAAM,IAAI,iBAAiB,EAAE,CAAC"}

package/dist/automation/selectors.js

@@ -0,0 +1,201 @@
+// Automation Kernel V2 — Workstream 2: Selector IR V2. One normalized selector model shared by
+// Flow V2, Maestro import/export, the Appium audit, and flow repair. Parses the existing Swipium
+// selector string grammar, normalizes Android resource ids, scores risk/portability, preserves
+// provenance, and refuses unsupported strategies per backend. NEVER generates XPath.
+import { selectorSupported } from './capabilities.js';
+import { isVisualStrategy } from './types.js';
+const PLATFORM_FOR_STRATEGY = {
+    resource_id: 'android',
+    ios_predicate: 'ios',
+    ios_class_chain: 'ios',
+};
+const PORTABLE_STRATEGIES = ['accessibility_id', 'text', 'ocr_text', 'image'];
+/** Normalize the many Android resource-id spellings to a bare id (last `/` segment). */
+export function normalizeResourceId(value) {
+    const trimmed = value.trim();
+    const slash = trimmed.lastIndexOf('/');
+    return slash >= 0 ? trimmed.slice(slash + 1) : trimmed;
+}
+function riskFor(strategy, value, hints) {
+    switch (strategy) {
+        case 'accessibility_id':
+        case 'resource_id':
+            return 'low';
+        case 'ios_predicate':
+        case 'ios_class_chain':
+            return 'medium';
+        case 'text': {
+            // Plain text is CI-brittle (copy/localization). Stable structural hints lower the risk.
+            const hasStableHint = !!(hints?.boundsBucket || hints?.screenSignature || hints?.className);
+            return hasStableHint ? 'medium' : 'high';
+        }
+        case 'ocr_text':
+        case 'image':
+            return 'high';
+        case 'coordinate':
+            return 'high';
+        default:
+            return 'high';
+    }
+}
+/**
+ * Parse one Swipium selector string into Selector IR. Recognizes the existing grammar:
+ *   `id=foo`, `id/foo`, `com.example:id/foo`, `accessibility id=foo`, `name=foo`,
+ *   `predicate string=...`, `class chain=...`, and bare text.
+ * OCR / image selectors come from dedicated flow steps, not this string grammar — see selectorForVisual().
+ */
+export function parseSelector(raw, opts = {}) {
+    const source = opts.source ?? 'flow';
+    const hints = opts.hints;
+    const s = raw.trim();
+    const make = (strategy, value) => ({
+        strategy,
+        value,
+        platform: opts.platform ?? PLATFORM_FOR_STRATEGY[strategy] ?? 'cross_platform',
+        source,
+        hints,
+        risk: riskFor(strategy, value, hints),
+        portable: PORTABLE_STRATEGIES.includes(strategy),
+    });
+    let m;
+    if ((m = s.match(/^id\s*=\s*(.+)$/i)))
+        return make('resource_id', normalizeResourceId(m[1]));
+    if ((m = s.match(/^accessibility id\s*=\s*(.+)$/i)))
+        return make('accessibility_id', m[1].trim());
+    if ((m = s.match(/^name\s*=\s*(.+)$/i)))
+        return make('text', m[1].trim());
+    if ((m = s.match(/^predicate string\s*=\s*(.+)$/i)))
+        return make('ios_predicate', m[1].trim());
+    if ((m = s.match(/^class chain\s*=\s*(.+)$/i)))
+        return make('ios_class_chain', m[1].trim());
+    // `com.example:id/foo` or `id/foo` without an explicit `id=` prefix is still an Android resource id.
+    if (/^[\w.]*:id\//.test(s) || /^id\//.test(s))
+        return make('resource_id', normalizeResourceId(s));
+    return make('text', s);
+}
+/** Build a visual (OCR/image) Selector IR from a dedicated visual flow step. */
+export function selectorForVisual(strategy, value, opts = {}) {
+    return {
+        strategy,
+        value,
+        platform: 'cross_platform',
+        source: opts.source ?? 'flow',
+        hints: opts.hints,
+        risk: 'high',
+        portable: true,
+    };
+}
+/** A coordinate selector (tapAt) — always last-resort, non-portable, high risk. */
+export function selectorForCoordinate(value, source = 'flow') {
+    return { strategy: 'coordinate', value, platform: 'cross_platform', source, risk: 'high', portable: false };
+}
+/** Refuse selectors a backend cannot honor (e.g. an iOS predicate on Android DirectDriver). */
+export function checkSelectorBackend(ir, caps) {
+    if (selectorSupported(caps, ir.strategy))
+        return { supported: true };
+    return {
+        supported: false,
+        code: 'BACKEND_UNSUPPORTED',
+        detail: `${ir.strategy} selector is not supported on ${caps.backend}.`,
+        nextStep: nextStepForUnsupportedSelector(ir.strategy, caps),
+    };
+}
+function nextStepForUnsupportedSelector(strategy, caps) {
+    if (strategy === 'ios_predicate' || strategy === 'ios_class_chain') {
+        return 'Use an iOS WDA or Appium XCUITest backend, or replace it with an accessibility id.';
+    }
+    if ((strategy === 'accessibility_id' || strategy === 'resource_id' || strategy === 'text') && !caps.structuredTree) {
+        return 'Attach WDA or Appium for structured selectors, or rewrite the step as a visual/OCR check.';
+    }
+    return `Attach a backend that supports ${strategy}.`;
+}
+/** CI-readiness check: plain text without stable hints is high risk and flagged. */
+export function checkSelectorCiRisk(ir) {
+    if (ir.strategy === 'text' && ir.risk === 'high') {
+        return {
+            risk: 'high',
+            code: 'HIGH_RISK_SELECTOR',
+            detail: 'Plain-text selector with no stable hints is brittle under copy/localization changes.',
+            nextStep: 'Pair it with a stable accessibility id / resource id, or add structural hints (boundsBucket, screenSignature).',
+        };
+    }
+    return { risk: ir.risk };
+}
+/**
+ * Resolve a (resource_id | accessibility_id) selector against parsed candidates. Duplicate matches
+ * are AMBIGUOUS_SELECTOR unless the IR's hints (boundsBucket / screenSignature) disambiguate to one.
+ */
+export function resolveSelector(ir, candidates) {
+    const key = (c) => ir.strategy === 'resource_id' ? (c.resourceId ? normalizeResourceId(c.resourceId) : undefined)
+        : ir.strategy === 'accessibility_id' ? c.accessibilityId
+            : ir.strategy === 'text' ? c.text
+                : undefined;
+    let matches = candidates.filter((c) => key(c) === ir.value);
+    if (matches.length === 0) {
+        return { ok: false, code: 'SELECTOR_NOT_FOUND', detail: `No element matches ${ir.strategy}=${ir.value}.`, matches: 0 };
+    }
+    if (matches.length === 1)
+        return { ok: true, match: matches[0] };
+    // Try to disambiguate by hints.
+    if (ir.hints?.boundsBucket) {
+        const narrowed = matches.filter((c) => c.boundsBucket === ir.hints.boundsBucket);
+        if (narrowed.length === 1)
+            return { ok: true, match: narrowed[0] };
+        if (narrowed.length)
+            matches = narrowed;
+    }
+    if (ir.hints?.screenSignature) {
+        const narrowed = matches.filter((c) => c.screenSignature === ir.hints.screenSignature);
+        if (narrowed.length === 1)
+            return { ok: true, match: narrowed[0] };
+    }
+    return {
+        ok: false,
+        code: 'AMBIGUOUS_SELECTOR',
+        detail: `${matches.length} elements match ${ir.strategy}=${ir.value}; add a disambiguating hint (boundsBucket/screenSignature) or a unique testID.`,
+        matches: matches.length,
+    };
+}
+/**
+ * Export a Selector IR to an Appium native locator strategy. NEVER returns XPath — visual/coordinate
+ * strategies have no Appium native locator and return null (the caller must mark them manual_review).
+ */
+export function selectorToAppium(ir) {
+    switch (ir.strategy) {
+        case 'resource_id':
+            return { using: 'id', value: ir.value };
+        case 'accessibility_id':
+            return { using: 'accessibility id', value: ir.value };
+        case 'ios_predicate':
+            return { using: '-ios predicate string', value: ir.value };
+        case 'ios_class_chain':
+            return { using: '-ios class chain', value: ir.value };
+        case 'text':
+            // Prefer a UiAutomator native text matcher over XPath for Android.
+            return { using: '-android uiautomator', value: `new UiSelector().text("${ir.value.replace(/"/g, '\\"')}")` };
+        default:
+            return null;
+    }
+}
+/** Convert a Maestro selector block (string | { id|text|... }) to Selector IR without semantic loss. */
+export function selectorFromMaestro(value, source = 'maestro_import') {
+    if (typeof value === 'string')
+        return parseSelector(value, { source });
+    if (!value || typeof value !== 'object')
+        return null;
+    const v = value;
+    if (typeof v.id === 'string')
+        return parseSelector(`id=${v.id}`, { source });
+    if (typeof v['accessibility id'] === 'string')
+        return parseSelector(`accessibility id=${v['accessibility id']}`, { source });
+    if (typeof v.label === 'string')
+        return parseSelector(`accessibility id=${v.label}`, { source });
+    if (typeof v.text === 'string')
+        return parseSelector(v.text, { source });
+    return null;
+}
+/** True when the strategy is a structured (non-visual) locator. */
+export function isStructuredSelector(ir) {
+    return !isVisualStrategy(ir.strategy) && ir.strategy !== 'coordinate';
+}
+//# sourceMappingURL=selectors.js.map

package/dist/automation/selectors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectors.js","sourceRoot":"","sources":["../../src/automation/selectors.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,iGAAiG;AACjG,+FAA+F;AAC/F,qFAAqF;AAGrF,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C,MAAM,qBAAqB,GAA8D;IACvF,WAAW,EAAE,SAAS;IACtB,aAAa,EAAE,KAAK;IACpB,eAAe,EAAE,KAAK;CACvB,CAAC;AAEF,MAAM,mBAAmB,GAAgC,CAAC,kBAAkB,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;AAE3G,wFAAwF;AACxF,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC/C,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACvC,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;AACzD,CAAC;AAED,SAAS,OAAO,CAAC,QAA0B,EAAE,KAAa,EAAE,KAAqB;IAC/E,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,kBAAkB,CAAC;QACxB,KAAK,aAAa;YAChB,OAAO,KAAK,CAAC;QACf,KAAK,eAAe,CAAC;QACrB,KAAK,iBAAiB;YACpB,OAAO,QAAQ,CAAC;QAClB,KAAK,MAAM,CAAC,CAAC,CAAC;YACZ,wFAAwF;YACxF,MAAM,aAAa,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,YAAY,IAAI,KAAK,EAAE,eAAe,IAAI,KAAK,EAAE,SAAS,CAAC,CAAC;YAC5F,OAAO,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC;QAC3C,CAAC;QACD,KAAK,UAAU,CAAC;QAChB,KAAK,OAAO;YACV,OAAO,MAAM,CAAC;QAChB,KAAK,YAAY;YACf,OAAO,MAAM,CAAC;QAChB;YACE,OAAO,MAAM,CAAC;IAClB,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAC3B,GAAW,EACX,OAA8F,EAAE;IAEhG,MAAM,MAAM,GAAmB,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC;IACrD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IACzB,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAErB,MAAM,IAAI,GAAG,CAAC,QAA0B,EAAE,KAAa,EAAc,EAAE,CAAC,CAAC;QACvE,QAAQ;QACR,KAAK;QACL,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,qBAAqB,CAAC,QAAQ,CAAC,IAAI,gBAAgB;QAC9E,MAAM;QACN,KAAK;QACL,IAAI,EAAE,OAAO,CAAC,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC;QACrC,QAAQ,EAAE,mBAAmB,CAAC,QAAQ,CAAC,QAAQ,CAAC;KACjD,CAAC,CAAC;IAEH,IAAI,CAA0B,CAAC;IAC/B,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC,aAAa,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7F,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC,kBAAkB,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAClG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAC1E,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAC/F,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,2BAA2B,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC,iBAAiB,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAC5F,qGAAqG;IACrG,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC,aAAa,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC;IAClG,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;AACzB,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,iBAAiB,CAC/B,QAA8B,EAC9B,KAAa,EACb,OAA2D,EAAE;IAE7D,OAAO;QACL,QAAQ;QACR,KAAK;QACL,QAAQ,EAAE,gBAAgB;QAC1B,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,MAAM;QAC7B,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,IAAI,EAAE,MAAM;QACZ,QAAQ,EAAE,IAAI;KACf,CAAC;AACJ,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,qBAAqB,CAAC,KAAa,EAAE,SAAyB,MAAM;IAClF,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;AAC9G,CAAC;AASD,+FAA+F;AAC/F,MAAM,UAAU,oBAAoB,CAAC,EAAc,EAAE,IAAyB;IAC5E,IAAI,iBAAiB,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC;QAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IACrE,OAAO;QACL,SAAS,EAAE,KAAK;QAChB,IAAI,EAAE,qBAAqB;QAC3B,MAAM,EAAE,GAAG,EAAE,CAAC,QAAQ,iCAAiC,IAAI,CAAC,OAAO,GAAG;QACtE,QAAQ,EAAE,8BAA8B,CAAC,EAAE,CAAC,QAAQ,EAAE,IAAI,CAAC;KAC5D,CAAC;AACJ,CAAC;AAED,SAAS,8BAA8B,CAAC,QAA0B,EAAE,IAAyB;IAC3F,IAAI,QAAQ,KAAK,eAAe,IAAI,QAAQ,KAAK,iBAAiB,EAAE,CAAC;QACnE,OAAO,oFAAoF,CAAC;IAC9F,CAAC;IACD,IAAI,CAAC,QAAQ,KAAK,kBAAkB,IAAI,QAAQ,KAAK,aAAa,IAAI,QAAQ,KAAK,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;QACnH,OAAO,2FAA2F,CAAC;IACrG,CAAC;IACD,OAAO,kCAAkC,QAAQ,GAAG,CAAC;AACvD,CAAC;AASD,oFAAoF;AACpF,MAAM,UAAU,mBAAmB,CAAC,EAAc;IAChD,IAAI,EAAE,CAAC,QAAQ,KAAK,MAAM,IAAI,EAAE,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QACjD,OAAO;YACL,IAAI,EAAE,MAAM;YACZ,IAAI,EAAE,oBAAoB;YAC1B,MAAM,EAAE,sFAAsF;YAC9F,QAAQ,EAAE,gHAAgH;SAC3H,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC;AAC3B,CAAC;AAeD;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,EAAc,EAAE,UAAoC;IAClF,MAAM,GAAG,GAAG,CAAC,CAAyB,EAAsB,EAAE,CAC5D,EAAE,CAAC,QAAQ,KAAK,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC9F,CAAC,CAAC,EAAE,CAAC,QAAQ,KAAK,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC,eAAe;YACxD,CAAC,CAAC,EAAE,CAAC,QAAQ,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI;gBACjC,CAAC,CAAC,SAAS,CAAC;IAEd,IAAI,OAAO,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC;IAC5D,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,oBAAoB,EAAE,MAAM,EAAE,sBAAsB,EAAE,CAAC,QAAQ,IAAI,EAAE,CAAC,KAAK,GAAG,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;IACzH,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;IAEjE,gCAAgC;IAChC,IAAI,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,CAAC;QAC3B,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,KAAK,EAAE,CAAC,KAAM,CAAC,YAAY,CAAC,CAAC;QAClF,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;QACnE,IAAI,QAAQ,CAAC,MAAM;YAAE,OAAO,GAAG,QAAQ,CAAC;IAC1C,CAAC;IACD,IAAI,EAAE,CAAC,KAAK,EAAE,eAAe,EAAE,CAAC;QAC9B,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,eAAe,KAAK,EAAE,CAAC,KAAM,CAAC,eAAe,CAAC,CAAC;QACxF,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;IACrE,CAAC;IACD,OAAO;QACL,EAAE,EAAE,KAAK;QACT,IAAI,EAAE,oBAAoB;QAC1B,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,mBAAmB,EAAE,CAAC,QAAQ,IAAI,EAAE,CAAC,KAAK,gFAAgF;QACnJ,OAAO,EAAE,OAAO,CAAC,MAAM;KACxB,CAAC;AACJ,CAAC;AAOD;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,EAAc;IAC7C,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC;QACpB,KAAK,aAAa;YAChB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC;QAC1C,KAAK,kBAAkB;YACrB,OAAO,EAAE,KAAK,EAAE,kBAAkB,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC;QACxD,KAAK,eAAe;YAClB,OAAO,EAAE,KAAK,EAAE,uBAAuB,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC;QAC7D,KAAK,iBAAiB;YACpB,OAAO,EAAE,KAAK,EAAE,kBAAkB,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC;QACxD,KAAK,MAAM;YACT,mEAAmE;YACnE,OAAO,EAAE,KAAK,EAAE,sBAAsB,EAAE,KAAK,EAAE,0BAA0B,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;QAC/G;YACE,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC;AAED,wGAAwG;AACxG,MAAM,UAAU,mBAAmB,CAAC,KAAc,EAAE,SAAyB,gBAAgB;IAC3F,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,aAAa,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IACvE,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACrD,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,IAAI,OAAO,CAAC,CAAC,EAAE,KAAK,QAAQ;QAAE,OAAO,aAAa,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IAC7E,IAAI,OAAO,CAAC,CAAC,kBAAkB,CAAC,KAAK,QAAQ;QAAE,OAAO,aAAa,CAAC,oBAAoB,CAAC,CAAC,kBAAkB,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IAC7H,IAAI,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ;QAAE,OAAO,aAAa,CAAC,oBAAoB,CAAC,CAAC,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IACjG,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,aAAa,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IACzE,OAAO,IAAI,CAAC;AACd,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,oBAAoB,CAAC,EAAc;IACjD,OAAO,CAAC,gBAAgB,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,QAAQ,KAAK,YAAY,CAAC;AACxE,CAAC"}

package/dist/automation/types.js

@@ -0,0 +1,13 @@
+// Automation Kernel V2 — shared types (Developer 3 lane). A backend-neutral automation model that
+// lets a Flow V2 file be compiled into a deterministic, capability-checked plan *before* a device
+// is touched. Everything here is pure data: no I/O, no driver calls. The runner, the planning
+// tools, Maestro interop, and the Appium audit all share these types so "the same flow means the
+// same thing" regardless of backend.
+//
+// See SWIPIUM-DEVELOPER-3-AUTOMATION-KERNEL-V2-PLAN-2026-05-29.md (Workstreams 1-5, 9).
+/** Visual selector strategies never claim structured-locator proof; they are candidate evidence only. */
+export const VISUAL_STRATEGIES = ['ocr_text', 'image'];
+export function isVisualStrategy(strategy) {
+    return VISUAL_STRATEGIES.includes(strategy);
+}
+//# sourceMappingURL=types.js.map

package/dist/automation/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/automation/types.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,kGAAkG;AAClG,8FAA8F;AAC9F,iGAAiG;AACjG,qCAAqC;AACrC,EAAE;AACF,wFAAwF;AA0CxF,yGAAyG;AACzG,MAAM,CAAC,MAAM,iBAAiB,GAAgC,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;AAEpF,MAAM,UAAU,gBAAgB,CAAC,QAA0B;IACzD,OAAO,iBAAiB,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAC9C,CAAC"}

package/dist/automation/waits.js

@@ -0,0 +1,91 @@
+// Automation Kernel V2 — Workstream 4: Wait and Stability Engine. Explicit wait contracts that
+// replace scattered sleeps. Assertions act as efficient condition waits (Maestro parity); idle waits
+// label their source as app_declared | backend | heuristic (Espresso parity); tap retry is explicit
+// and recorded, never a hidden loop. All executors take an injectable clock so they are deterministic
+// in tests and never block on real wall-clock during unit runs.
+export const realClock = {
+    now: () => Date.now(),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};
+/**
+ * Poll `condition` until it returns true or `timeoutMs` elapses. Exits early the instant the
+ * condition holds. Always evaluates the condition at least once.
+ */
+export async function waitForCondition(condition, opts) {
+    const clock = opts.clock ?? realClock;
+    const interval = Math.max(1, opts.intervalMs ?? 250);
+    const start = clock.now();
+    let polls = 0;
+    // First, immediate check.
+    polls += 1;
+    if (await condition())
+        return { ok: true, elapsedMs: clock.now() - start, polls, timedOut: false };
+    while (clock.now() - start < opts.timeoutMs) {
+        await clock.sleep(interval);
+        polls += 1;
+        if (await condition())
+            return { ok: true, elapsedMs: clock.now() - start, polls, timedOut: false };
+    }
+    return { ok: false, elapsedMs: clock.now() - start, polls, timedOut: true };
+}
+/** Wait until an element is visible (assertion-as-wait). */
+export async function waitForVisible(isVisible, opts) {
+    const r = await waitForCondition(isVisible, opts);
+    return { ...r, visible: r.ok };
+}
+/** Wait until an element is NOT visible — e.g. a spinner / modal disappears. */
+export async function waitForNotVisible(isVisible, opts) {
+    const r = await waitForCondition(async () => !(await isVisible()), opts);
+    return { ...r, visible: !r.ok };
+}
+/**
+ * Wait for the UI to settle. The caller declares which idle source is in play:
+ *  - app_declared: an Espresso/RN idling resource the app exposes (the only true proof)
+ *  - backend: WDA/XCTest waitForIdle or driver-level idle
+ *  - heuristic: best-effort settling (screenshot stability etc.) — labeled as NOT app proof
+ */
+export async function waitForIdle(isIdle, opts) {
+    const r = await waitForCondition(isIdle, opts);
+    const appProof = opts.source === 'app_declared' && r.ok;
+    const detail = opts.source === 'app_declared'
+        ? r.ok ? 'app-declared idling resource reported idle' : 'app-declared idling resource did not settle within timeout'
+        : opts.source === 'backend'
+            ? r.ok ? 'backend (WDA/XCTest) idle reported' : 'backend idle did not settle within timeout'
+            : r.ok ? 'heuristic settling reached (not app-declared proof)' : 'heuristic settling did not stabilize within timeout';
+    return { ok: r.ok, source: opts.source, elapsedMs: r.elapsedMs, polls: r.polls, timedOut: r.timedOut, appProof, detail };
+}
+/** waitForAnimationToEnd — on timeout, pass with a warning rather than fail. */
+export async function waitForAnimationToEnd(isAnimating, opts) {
+    const r = await waitForCondition(async () => !(await isAnimating()), opts);
+    if (r.ok)
+        return { ok: true, timedOut: false, elapsedMs: r.elapsedMs };
+    return {
+        ok: true,
+        timedOut: true,
+        elapsedMs: r.elapsedMs,
+        warning: `animation did not end within ${opts.timeoutMs}ms; continuing (pass-with-warning).`,
+    };
+}
+/**
+ * Tap with explicit `retryTapIfNoChange` semantics. Taps once; if the UI did not change AND retry is
+ * enabled, taps exactly one more time. Every attempt (with before/after signatures) is recorded so
+ * the retry is visible in the plan and evidence — never a hidden loop.
+ */
+export async function retryTapIfNoChange(doTap, screenSignature, opts) {
+    const attempts = [];
+    const before1 = await screenSignature();
+    await doTap();
+    const after1 = await screenSignature();
+    const changed1 = before1 !== after1;
+    attempts.push({ index: 0, changed: changed1, signatureBefore: before1, signatureAfter: after1 });
+    if (changed1 || !opts.enabled) {
+        return { ok: true, attempts, retried: false, changed: changed1 };
+    }
+    const before2 = after1;
+    await doTap();
+    const after2 = await screenSignature();
+    const changed2 = before2 !== after2;
+    attempts.push({ index: 1, changed: changed2, signatureBefore: before2, signatureAfter: after2 });
+    return { ok: true, attempts, retried: true, changed: changed2 };
+}
+//# sourceMappingURL=waits.js.map

package/dist/automation/waits.js.map

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

package/dist/automation/webview.js

@@ -0,0 +1,81 @@
+// Automation Kernel V2 — Workstream 7 (Stage 1): Hybrid / WebView awareness. Pure detection of
+// probable WebView / canvas / map surfaces from UI-tree element classes, plus the diagnostics that
+// tell a developer whether structured automation is possible or whether Appium context support (or a
+// native accessibility id) is required. Stage 1 is detection + read-only Appium context inventory; it
+// does NOT add arbitrary web JS execution.
+// Class/role signals. Matching is case-insensitive substring so framework-prefixed classes still hit.
+const WEBVIEW_SIGNALS = ['webview', 'wkwebview', 'uiwebview', 'org.chromium', 'xwalk', 'xcuielementtypewebview', 'rctwebview'];
+const CANVAS_SIGNALS = ['surfaceview', 'textureview', 'glsurfaceview', 'flutterview', 'unityplayer', 'canvas'];
+const MAP_SIGNALS = ['mapview', 'com.google.android.maps', 'mkmapview', 'gmsmapview'];
+function classify(value) {
+    const v = value.toLowerCase();
+    if (WEBVIEW_SIGNALS.some((s) => v.includes(s)))
+        return 'webview';
+    if (MAP_SIGNALS.some((s) => v.includes(s)))
+        return 'map';
+    if (CANVAS_SIGNALS.some((s) => v.includes(s)))
+        return 'canvas';
+    return null;
+}
+/** Detect probable hybrid surfaces from a parsed UI tree and emit the right diagnostic. */
+export function detectHybridSurface(elements, opts = {}) {
+    const surfaces = [];
+    for (const el of elements) {
+        for (const value of [el.className, el.role]) {
+            if (!value)
+                continue;
+            const kind = classify(value);
+            if (kind && !surfaces.some((s) => s.kind === kind && s.signal === value)) {
+                surfaces.push({ kind, signal: value });
+            }
+        }
+    }
+    // A high visual-fallback ratio with no structured matches is a soft hybrid/canvas signal.
+    const softHybrid = surfaces.length === 0 && (opts.visualFallbackRatio ?? 0) >= 0.5;
+    const hybrid = surfaces.length > 0 || softHybrid;
+    if (!hybrid) {
+        return { hybrid: false, surfaces, diagnostic: 'NATIVE', appiumRequired: false, agentMessage: 'This screen looks like a native UI tree; structured selectors should work.' };
+    }
+    const hasWebview = surfaces.some((s) => s.kind === 'webview') || softHybrid;
+    const nonNativeContexts = (opts.contexts ?? []).filter((c) => !/^native_app$/i.test(c));
+    const contextSwitchingPossible = !!opts.caps?.webviewContexts;
+    if (hasWebview && nonNativeContexts.length > 0) {
+        return {
+            hybrid: true,
+            surfaces,
+            diagnostic: 'WEBVIEW_CONTEXT_AVAILABLE',
+            appiumRequired: false,
+            agentMessage: `This screen is hybrid (WebView). Appium reports ${nonNativeContexts.length} web context(s) (${nonNativeContexts.join(', ')}); structural web automation is possible by switching context.`,
+        };
+    }
+    if (hasWebview && contextSwitchingPossible) {
+        return {
+            hybrid: true,
+            surfaces,
+            diagnostic: 'WEBVIEW_CONTEXT_MISSING',
+            appiumRequired: true,
+            agentMessage: 'This screen looks like a WebView. The backend can switch contexts, but none are currently reported; attach the WebView context or use a native accessibility id, otherwise only visual candidate evidence is possible.',
+        };
+    }
+    return {
+        hybrid: true,
+        surfaces,
+        diagnostic: 'WEBVIEW_VISUAL_ONLY',
+        appiumRequired: true,
+        agentMessage: 'This screen looks like a WebView. I need Appium context support or a native accessibility id to automate it structurally; otherwise I can only produce visual candidate evidence.',
+    };
+}
+/** Read-only Appium context inventory (Stage 2 deliverable — no arbitrary JS execution). */
+export function summarizeAppiumContexts(contexts, current) {
+    const webviewContexts = contexts.filter((c) => !/^native_app$/i.test(c));
+    return { current: current ?? null, available: [...contexts], webviewContexts };
+}
+/** An actionable blocker for a structured step that targets a WebView-only surface. */
+export function webviewSelectorBlocker(selector) {
+    return {
+        code: 'WEBVIEW_VISUAL_ONLY',
+        detail: `Selector ${selector.strategy}=${selector.value} targets a WebView surface that the current backend cannot reach structurally.`,
+        nextStep: 'This screen looks like a WebView. I need Appium context support or a native accessibility id to automate it structurally; otherwise I can only produce visual candidate evidence.',
+    };
+}
+//# sourceMappingURL=webview.js.map

package/dist/automation/webview.js.map

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