mobile-debug-mcp 0.33.0 → 0.35.0

package/dist/interact/adjustment/adjustment-resolution.js

@@ -0,0 +1,127 @@
+import { _normalizeBounds, _isAdjustableControl, _findFirstMatchingElement, _isAdjustableActionable } from '../targeting/element-helpers.js';
+import { planAdjustment } from './adjustment-plan.js';
+import { failAdjustment, recordAdjustment, succeedAdjustment } from './adjustment-context.js';
+function fallbackBounds(fallback) {
+    const bounds = fallback?.bounds;
+    if (Array.isArray(bounds))
+        return _normalizeBounds(bounds);
+    return bounds && typeof bounds === 'object' ? _normalizeBounds([Number(bounds.left), Number(bounds.top), Number(bounds.right), Number(bounds.bottom)]) : null;
+}
+function findFallback(elements, fallback) {
+    const bounds = fallbackBounds(fallback);
+    if (!bounds)
+        return null;
+    let index = elements.findIndex(el => {
+        const current = _normalizeBounds(el.bounds);
+        return !!current && current.every((value, i) => value === bounds[i]);
+    });
+    if (index === -1)
+        index = nearestControl(elements, bounds);
+    return index >= 0 && elements[index] ? { el: elements[index], idx: index } : null;
+}
+function nearestControl(elements, bounds) {
+    const x = Math.floor((bounds[0] + bounds[2]) / 2), y = Math.floor((bounds[1] + bounds[3]) / 2);
+    let best = Infinity, index = -1;
+    for (let i = 0; i < elements.length; i++) {
+        const el = elements[i];
+        if (!_isAdjustableControl(el))
+            continue;
+        const current = _normalizeBounds(el.bounds);
+        if (!current)
+            continue;
+        const distance = Math.abs(Math.floor((current[0] + current[2]) / 2) - x) + Math.abs(Math.floor((current[1] + current[3]) / 2) - y);
+        if (distance < best) {
+            best = distance;
+            index = i;
+        }
+    }
+    return index;
+}
+export async function resolveControl(s, deps) {
+    const tree = await deps.observe(s.platform, s.deviceId);
+    s.platform = tree?.device?.platform === 'ios' ? 'ios' : s.platform;
+    s.deviceId = tree?.device?.id || s.deviceId;
+    const elements = Array.isArray(tree?.elements) ? tree.elements : [];
+    let match = null;
+    if (s.input.element_id) {
+        const stored = deps.getHandle(s.input.element_id);
+        if (!stored)
+            return null;
+        const current = deps.currentHandle(elements, s.platform, s.deviceId, stored);
+        if (!current)
+            return null;
+        match = { el: current.el, idx: current.index };
+    }
+    else {
+        if (s.fallback)
+            match = findFallback(elements, s.fallback);
+        if (!match && s.input.selector)
+            match = _findFirstMatchingElement(elements, s.input.selector);
+    }
+    return match ? { tree, device: tree?.device, match, resolvedTarget: deps.target(s.platform, s.deviceId, match) } : null;
+}
+export async function initializeControl(s, deps) {
+    const { selector, element_id } = s.input;
+    if ((!selector && !element_id) || (selector && element_id)) {
+        return failAdjustment(s, 'ELEMENT_NOT_FOUND', 'exactly one of selector or element_id is required', false, null, undefined, null, 0, 'gesture');
+    }
+    if (!selector || element_id)
+        return null;
+    const wait = await deps.wait({ selector, condition: 'clickable', timeout_ms: 5000, poll_interval_ms: 300, platform: s.platform, deviceId: s.deviceId });
+    if (wait?.status === 'success' && wait?.element?.elementId) {
+        s.input.element_id = wait.element.elementId;
+        s.fallback = null;
+        return null;
+    }
+    return initializeFallback(s, deps, wait, selector);
+}
+async function initializeFallback(s, deps, wait, selector) {
+    const query = selector.text ?? selector.resource_id ?? selector.accessibility_id ?? '';
+    if (!query)
+        return failAdjustment(s, wait?.error?.code === 'ELEMENT_NOT_FOUND' ? 'ELEMENT_NOT_FOUND' : 'TIMEOUT', wait?.error?.message ?? 'adjustable control not found', wait?.error?.code === 'ELEMENT_NOT_FOUND', null, wait?.device, null, 0, 'gesture');
+    const fallback = await deps.find({ query, exact: false, timeoutMs: 3000, platform: s.platform, deviceId: s.deviceId });
+    if (!fallback.found || !fallback.element)
+        return failAdjustment(s, 'ELEMENT_NOT_FOUND', wait?.error?.message ?? 'adjustable control not found', true, null, wait?.device, null, 0, 'gesture');
+    s.fallback = fallback.element;
+    return null;
+}
+export async function prepareIteration(s, deps) {
+    const resolved = s.cached ? { tree: null, device: s.device, match: s.cached, resolvedTarget: deps.target(s.platform, s.deviceId, s.cached) } : await resolveControl(s, deps);
+    if (!resolved?.match || !resolved.resolvedTarget)
+        return failAdjustment(s, 'STALE_REFERENCE', 'adjustable control could not be resolved', true);
+    s.device = resolved.device;
+    s.target = resolved.resolvedTarget;
+    s.cached = resolved.match;
+    const element = resolved.match.el;
+    const actionable = _isAdjustableActionable(element, s.stored?.stable_id);
+    if (!actionable.actionable)
+        return failAdjustment(s, actionable.failureCode ?? 'ELEMENT_NOT_INTERACTABLE', actionable.reason ?? 'adjustable control is not actionable', true);
+    const elements = Array.isArray(resolved.tree?.elements) ? resolved.tree.elements : s.cached ? [s.cached.el] : [element];
+    const plan = planAdjustment(element, elements, s.input.targetValue, s.input.property, s.tolerance);
+    s.observed = plan.actualState;
+    if (!s.trace.some(step => step.stage === 'resolve'))
+        recordAdjustment(s, 'resolve', 'success', { resolved_target: s.target, current_value: plan.currentValue, adjustment_mode: s.mode });
+    const iteration = { ...plan, element, index: resolved.match.idx, actionDevice: s.device, observed: plan.actualState,
+        verification: { verification: null, observedState: plan.actualState, withinTolerance: false } };
+    const invalid = validateControl(s, iteration);
+    if (invalid)
+        return invalid;
+    if (plan.currentValue !== null && Math.abs(plan.currentValue - plan.normalizedTargetValue) <= plan.effectiveTolerance) {
+        recordAdjustment(s, 'verify', 'success', { property: s.input.property, target_value: plan.normalizedTargetValue, actual_state: plan.actualState, reason: 'control already within tolerance' });
+        return succeedAdjustment(s, iteration, deps, 'control already within tolerance', 'semantic', s.device);
+    }
+    if (!plan.bounds)
+        return failAdjustment(s, 'ELEMENT_NOT_INTERACTABLE', 'adjustable control has no bounds');
+    return iteration;
+}
+function validateControl(s, p) {
+    if (s.input.property !== 'value' && s.input.property !== 'raw_value')
+        return failAdjustment(s, 'ELEMENT_NOT_INTERACTABLE', 'adjust_control currently supports numeric value and raw_value properties only');
+    if (!_isAdjustableControl(p.element) && !p.inferredSliderState)
+        return failAdjustment(s, 'ELEMENT_NOT_INTERACTABLE', 'target is not an adjustable control');
+    if (p.currentValue === null)
+        return failAdjustment(s, 'UNKNOWN', 'current numeric value is unavailable');
+    if (p.valueRange && (s.input.targetValue < p.valueRange.min || s.input.targetValue > p.valueRange.max))
+        return failAdjustment(s, 'CONTROL_CONVERGENCE_FAILED', `targetValue ${s.input.targetValue} is outside the control range ${p.valueRange.min}..${p.valueRange.max}`);
+    return null;
+}

package/dist/interact/adjustment/adjustment-result.js

@@ -0,0 +1,19 @@
+import { buildActionExecutionResult } from '../../runtime/action-results.js';
+/** Keep the action envelope and top-level control result in agreement. */
+export function completeAdjustment(input) {
+    const base = buildActionExecutionResult(input);
+    const details = input.details;
+    return {
+        ...base,
+        target_state: {
+            property: details.property,
+            target_value: details.target_value,
+            tolerance: details.tolerance
+        },
+        actual_state: details.actual_state,
+        within_tolerance: true,
+        converged: true,
+        attempts: details.attempts,
+        adjustment_mode: details.adjustment_mode
+    };
+}

package/dist/interact/adjustment/adjustment-semantic.js

@@ -0,0 +1,64 @@
+import { _hasDirectAdjustmentAction, _adjustmentDirections } from './control-values.js';
+import { verifyAdjustment } from './adjustment-verification.js';
+import { recordAdjustment, succeedAdjustment } from './adjustment-context.js';
+export async function verifyControl(s, p, deps, fallback) {
+    p.verification = await verifyAdjustment({ labeled: !!p.inferredSliderState, currentEl: p.element, actualState: p.actualState,
+        property: s.input.property, target: p.normalizedTargetValue, tolerance: p.effectiveTolerance,
+        expectation: { element_id: s.target?.elementId ?? s.input.element_id, selector: s.input.selector ?? undefined,
+            property: s.input.property, expected: p.normalizedTargetValue, platform: s.platform, deviceId: s.deviceId }
+    }, { observe: () => deps.observe(s.platform, s.deviceId), expectState: deps.expectState });
+    p.observed = p.verification.observedState;
+    s.observed = p.observed;
+    recordAdjustment(s, 'verify', p.verification.withinTolerance ? 'success' : 'retry', {
+        attempt: s.attempts, property: s.input.property, target_value: p.normalizedTargetValue,
+        actual_state: p.observed, reason: p.verification.verification?.reason ?? fallback
+    });
+}
+export async function directAdjustment(s, p, deps) {
+    if (!_hasDirectAdjustmentAction(p.element) || s.attempts >= s.limit)
+        return 'next';
+    const { interact, resolved } = await deps.service(s.platform, s.deviceId);
+    if (typeof interact.setAdjustableValue !== 'function')
+        return 'next';
+    s.mode = 'semantic';
+    recordAdjustment(s, 'execute', 'retry', { attempt: s.attempts + 1, mode: 'semantic', strategy: 'direct_set_value', target_value: p.normalizedTargetValue });
+    const action = await interact.setAdjustableValue({ deviceId: resolved.id, target: s.target, property: s.input.property, value: p.normalizedTargetValue });
+    s.attempts++;
+    p.actionDevice = action?.device ?? p.actionDevice;
+    if (action?.success === false)
+        return 'next';
+    await verifyControl(s, p, deps, 'direct adjustment did not converge yet');
+    if (p.verification.withinTolerance)
+        return succeedAdjustment(s, p, deps, p.verification.verification?.reason ?? 'control converged to target value');
+    s.cached = null;
+    return s.attempts < s.limit ? 'retry' : 'next';
+}
+export async function incrementalAdjustment(s, p, deps) {
+    const directions = _adjustmentDirections(p.element);
+    if ((!directions.increment && !directions.decrement) || s.attempts >= s.limit)
+        return 'next';
+    const { interact, resolved } = await deps.service(s.platform, s.deviceId);
+    const adjust = typeof interact.adjustAccessibleValue === 'function' ? interact.adjustAccessibleValue.bind(interact) : null;
+    while (adjust && s.attempts < s.limit) {
+        const direction = p.normalizedTargetValue > (p.observed?.value ?? p.currentValue) ? 'increment' : 'decrement';
+        if (!directionAllowed(direction, directions))
+            break;
+        s.mode = 'semantic';
+        recordAdjustment(s, 'execute', 'retry', { attempt: s.attempts + 1, mode: 'semantic', strategy: 'accessibility_increment_decrement', direction });
+        const action = await adjust({ deviceId: resolved.id, target: s.target, property: s.input.property, direction });
+        s.attempts++;
+        p.actionDevice = action?.device ?? p.actionDevice;
+        if (action?.success === false)
+            break;
+        await verifyControl(s, p, deps, 'incremental adjustment did not converge yet');
+        if (p.verification.withinTolerance)
+            return succeedAdjustment(s, p, deps, p.verification.verification?.reason ?? 'control converged to target value');
+        s.cached = null;
+        if (s.attempts < s.limit)
+            return 'retry';
+    }
+    return 'next';
+}
+function directionAllowed(direction, directions) {
+    return !((direction === 'increment' && !directions.increment) || (direction === 'decrement' && !directions.decrement));
+}

package/dist/interact/adjustment/adjustment-verification.js

@@ -0,0 +1,35 @@
+import { _inferLabeledSliderState } from './slider-labels.js';
+import { _parseNumericControlValue } from './control-values.js';
+/** Every verification obtains fresh evidence through its supplied observation boundary. */
+export async function verifyAdjustment(input, dependencies) {
+    if (input.labeled)
+        return verifyLabeledControl(input, dependencies);
+    const verification = await dependencies.expectState(input.expectation);
+    const observedValue = _parseNumericControlValue(verification?.observed_state?.value) ??
+        _parseNumericControlValue(verification?.observed_state?.raw_value);
+    const observedState = observedValue !== null ? {
+        property: input.property, value: observedValue,
+        raw_value: typeof verification?.observed_state?.raw_value === 'number' ? verification.observed_state.raw_value : undefined
+    } : input.actualState;
+    return { verification, observedState, withinTolerance: withinTolerance(observedValue, input) };
+}
+async function verifyLabeledControl(input, dependencies) {
+    const tree = await dependencies.observe();
+    const elements = Array.isArray(tree?.elements) ? tree.elements : [];
+    const refreshed = _inferLabeledSliderState(elements, input.currentEl);
+    const observedValue = refreshed?.current ?? null;
+    const observedState = observedValue !== null ? {
+        property: input.property, value: observedValue, raw_value: observedValue
+    } : input.actualState;
+    const matched = withinTolerance(observedValue, input);
+    return {
+        verification: {
+            success: matched, observed_state: observedState,
+            reason: observedValue !== null ? 'visible labeled value read from nearby slider labels' : 'visible labeled value unavailable'
+        },
+        observedState, withinTolerance: matched
+    };
+}
+function withinTolerance(value, input) {
+    return value !== null && Math.abs(value - input.target) <= input.tolerance;
+}

package/dist/interact/adjustment/adjustment.js

@@ -0,0 +1,52 @@
+import { createAdjustment, failAdjustment, recordAdjustment, succeedAdjustment } from './adjustment-context.js';
+import { initializeControl, prepareIteration } from './adjustment-resolution.js';
+import { directAdjustment, incrementalAdjustment } from './adjustment-semantic.js';
+import { coordinateAdjustment, gestureAdjustment } from './adjustment-gestures.js';
+function cacheObservation(s, p) {
+    s.cached = p.inferredSliderState ? null : {
+        el: { ...p.element, state: { ...(p.element.state ?? null), ...(p.observed ? {
+                    [p.observed.property]: p.observed.value, raw_value: p.observed.raw_value ?? p.observed.value
+                } : {}) } }, idx: p.index
+    };
+}
+async function attempt(s, p, deps) {
+    for (const strategy of [directAdjustment, incrementalAdjustment]) {
+        const outcome = await strategy(s, p, deps);
+        if (outcome !== 'next')
+            return outcome;
+    }
+    if (!p.bounds)
+        return failAdjustment(s, 'ELEMENT_NOT_INTERACTABLE', 'adjustable control has no bounds');
+    if (!p.valueRange)
+        return failAdjustment(s, 'UNKNOWN', 'value_range unavailable');
+    for (const strategy of [coordinateAdjustment, gestureAdjustment]) {
+        const outcome = await strategy(s, p, deps);
+        if (outcome !== 'next')
+            return outcome;
+    }
+    s.observed = p.observed;
+    if (p.verification.withinTolerance) {
+        const reason = p.verification.verification?.reason ?? 'control converged to target value';
+        recordAdjustment(s, 'verify', 'success', { attempt: s.attempts, property: s.input.property,
+            target_value: p.normalizedTargetValue, actual_state: p.observed, reason });
+        return succeedAdjustment(s, p, deps, reason);
+    }
+    cacheObservation(s, p);
+    return 'next';
+}
+export async function adjustControl(input, deps) {
+    const state = await createAdjustment(input, deps);
+    const invalid = await initializeControl(state, deps);
+    if (invalid)
+        return invalid;
+    for (let index = 0; index < state.limit && state.attempts < state.limit; index++) {
+        const prepared = await prepareIteration(state, deps);
+        if ('success' in prepared)
+            return prepared;
+        const outcome = await attempt(state, prepared, deps);
+        if (outcome !== 'retry' && outcome !== 'next')
+            return outcome;
+    }
+    const after = await deps.fingerprint(state.platform, state.deviceId);
+    return failAdjustment(state, 'CONTROL_CONVERGENCE_FAILED', 'control did not converge within the allotted attempts', true, state.target, state.device, state.observed, state.attempts, state.mode, after);
+}

package/dist/interact/adjustment/control-geometry.js

@@ -0,0 +1,87 @@
+import { _normalize } from '../targeting/element-helpers.js';
+export function _buildControlPoint(bounds, ratio, axis) {
+    const clampedRatio = Math.max(0, Math.min(1, ratio));
+    const [left, top, right, bottom] = bounds;
+    const width = Math.max(1, right - left);
+    const height = Math.max(1, bottom - top);
+    const insetX = Math.max(8, Math.floor(width * 0.08));
+    const insetY = Math.max(8, Math.floor(height * 0.08));
+    if (axis === 'vertical') {
+        const usableHeight = Math.max(1, height - (insetY * 2));
+        return {
+            x: Math.floor((left + right) / 2),
+            y: Math.floor(bottom - insetY - (usableHeight * clampedRatio))
+        };
+    }
+    const usableWidth = Math.max(1, width - (insetX * 2));
+    return {
+        x: Math.floor(left + insetX + (usableWidth * clampedRatio)),
+        y: Math.floor((top + bottom) / 2)
+    };
+}
+export function _buildConservativeControlPoint(bounds, targetValue, currentValue, min, max, axis) {
+    const range = Math.max(1, max - min);
+    const targetRatio = (targetValue - min) / range;
+    const stepRatio = 1 / range;
+    const centerBias = stepRatio / 2;
+    const direction = currentValue === null ? 0 : Math.sign(targetValue - currentValue);
+    const controlLengthPx = axis === 'vertical' ? Math.max(1, bounds[3] - bounds[1]) : Math.max(1, bounds[2] - bounds[0]);
+    const edgeWindow = Math.max(3, Math.floor(range * 0.1));
+    const isNearLowEdge = targetValue - min <= edgeWindow;
+    const isNearHighEdge = max - targetValue <= edgeWindow;
+    const directionBias = direction > 0
+        ? -stepRatio * 0.15
+        : direction < 0
+            ? stepRatio * 0.65
+            : 0;
+    const pixelBasedMargin = Math.min(0.03, Math.max(0.005, 2 / controlLengthPx));
+    const endpointMargin = Math.max(stepRatio * 0.5, pixelBasedMargin);
+    const edgeBias = isNearLowEdge
+        ? endpointMargin
+        : isNearHighEdge
+            ? Math.max(stepRatio * 0.4, endpointMargin * 0.75)
+            : 0;
+    const safeRatio = Math.min(1 - (endpointMargin * 0.25), Math.max(endpointMargin, targetRatio + centerBias + directionBias + edgeBias));
+    return _buildControlPoint(bounds, safeRatio, axis);
+}
+export function _buildAdjustmentProbePoints(bounds, targetValue, currentValue, min, max, axis) {
+    const targetPoint = _buildConservativeControlPoint(bounds, targetValue, currentValue, min, max, axis);
+    const currentPoint = currentValue !== null
+        ? _buildControlPoint(bounds, (currentValue - min) / (max - min), axis)
+        : _buildControlPoint(bounds, 0.5, axis);
+    const [left, top, right, bottom] = bounds;
+    const width = Math.max(1, right - left);
+    const height = Math.max(1, bottom - top);
+    const crossAxisBumps = axis === 'horizontal'
+        ? [Math.max(24, Math.floor(height * 0.75)), Math.max(40, Math.floor(height * 1.5))]
+        : [Math.max(24, Math.floor(width * 0.75)), Math.max(40, Math.floor(width * 1.5))];
+    const clampPoint = (point) => ({
+        x: axis === 'horizontal'
+            ? Math.max(left, Math.min(right, point.x))
+            : Math.max(left, Math.min(right + Math.max(width, height), point.x)),
+        y: axis === 'vertical'
+            ? Math.max(top, Math.min(bottom, point.y))
+            : Math.max(top, Math.min(bottom + Math.max(height, width), point.y))
+    });
+    const probes = [targetPoint, currentPoint];
+    for (const bump of crossAxisBumps) {
+        if (axis === 'horizontal') {
+            probes.push({ x: targetPoint.x, y: bottom + bump }, { x: currentPoint.x, y: bottom + bump });
+        }
+        else {
+            probes.push({ x: right + bump, y: targetPoint.y }, { x: right + bump, y: currentPoint.y });
+        }
+    }
+    return Array.from(new Map(probes
+        .map(clampPoint)
+        .map((point) => [`${point.x}:${point.y}`, point])).values());
+}
+export function _controlAxis(el, bounds) {
+    const type = _normalize(el.type ?? el.class ?? '');
+    const role = _normalize(el.role ?? '');
+    if (/vertical/.test(type) || /vertical/.test(role))
+        return 'vertical';
+    if (/horizontal/.test(type) || /horizontal/.test(role))
+        return 'horizontal';
+    return (bounds[3] - bounds[1]) > (bounds[2] - bounds[0]) ? 'vertical' : 'horizontal';
+}

package/dist/interact/adjustment/control-values.js

@@ -0,0 +1,136 @@
+import { _normalize } from '../targeting/element-helpers.js';
+export function _readNumericControlValue(el, property) {
+    if (!el?.state)
+        return null;
+    const stateValue = el.state[property];
+    if (typeof stateValue === 'number' && Number.isFinite(stateValue))
+        return stateValue;
+    const parsedStateValue = _parseNumericControlValue(stateValue);
+    if (parsedStateValue !== null)
+        return parsedStateValue;
+    if (property === 'value' || property === 'raw_value') {
+        const fallback = el.state.raw_value ?? el.state.value;
+        if (typeof fallback === 'number' && Number.isFinite(fallback))
+            return fallback;
+        return _parseNumericControlValue(fallback);
+    }
+    return null;
+}
+export function _parseNumericControlValue(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return null;
+    const percent = trimmed.match(/^([-+]?\d+(?:\.\d+)?)\s*%$/);
+    if (percent)
+        return Number(percent[1]);
+    const fraction = trimmed.match(/^([-+]?\d+(?:\.\d+)?)\s+of\s+[-+]?\d+(?:\.\d+)?$/i);
+    if (fraction)
+        return Number(fraction[1]);
+    const plain = Number(trimmed);
+    if (Number.isFinite(plain))
+        return plain;
+    const trailing = trimmed.match(/,\s*([-+]?\d+(?:\.\d+)?)$/);
+    if (trailing)
+        return Number(trailing[1]);
+    return null;
+}
+export function _readNumericControlRange(el) {
+    const range = el?.state?.value_range;
+    const min = typeof range?.min === 'number' ? range.min : null;
+    const max = typeof range?.max === 'number' ? range.max : null;
+    if (min !== null && max !== null && Number.isFinite(min) && Number.isFinite(max) && max > min) {
+        return { min, max };
+    }
+    return rangeFromFraction(el?.state?.value ?? el?.state?.raw_value);
+}
+function rangeFromFraction(value) {
+    if (typeof value === 'string') {
+        const fraction = value.trim().match(/^[-+]?\d+(?:\.\d+)?\s+of\s+([-+]?\d+(?:\.\d+)?)$/i);
+        if (fraction) {
+            const parsedMax = Number(fraction[1]);
+            if (Number.isFinite(parsedMax) && parsedMax > 0)
+                return { min: 0, max: parsedMax };
+        }
+    }
+    return null;
+}
+export function _readControlStep(el) {
+    const candidates = [
+        el?.state?.step,
+        el?.state?.value_range?.step
+    ];
+    for (const candidate of candidates) {
+        if (typeof candidate === 'number' && Number.isFinite(candidate) && candidate > 0)
+            return candidate;
+    }
+    return null;
+}
+export function _quantizeTargetValue(targetValue, min, max, step) {
+    if (!step)
+        return targetValue;
+    const quantized = min + (Math.round((targetValue - min) / step) * step);
+    const bounded = Math.max(min, Math.min(max, quantized));
+    const precision = _decimalPrecisionForStep(step);
+    return Number(bounded.toFixed(precision));
+}
+export function _decimalPrecisionForStep(step) {
+    const normalized = String(step).toLowerCase();
+    const [coefficient, exponentPart] = normalized.split('e');
+    const coefficientDecimals = coefficient.includes('.')
+        ? coefficient.split('.')[1]?.length ?? 0
+        : 0;
+    const exponent = exponentPart !== undefined ? Number(exponentPart) : 0;
+    const precision = exponent < 0
+        ? coefficientDecimals + Math.abs(exponent)
+        : Math.max(0, coefficientDecimals - exponent);
+    return Math.max(0, Math.min(12, precision));
+}
+export function _defaultAdjustTolerance(range, step) {
+    if (step)
+        return 0;
+    if (!range)
+        return 0;
+    return Math.max(0, 0.01 * Math.abs(range.max - range.min));
+}
+export function _runtimeActionSet(el) {
+    const values = [
+        ...(Array.isArray(el?.actions) ? el.actions : []),
+        ...(Array.isArray(el?.accessibilityActions) ? el.accessibilityActions : []),
+        ...(Array.isArray(el?.runtimeActions) ? el.runtimeActions : []),
+        ...(Array.isArray(el?.platformActions) ? el.platformActions : [])
+    ];
+    return new Set(values.map((value) => _normalize(value)).filter(Boolean));
+}
+export function _hasDirectAdjustmentAction(el) {
+    const actions = _runtimeActionSet(el);
+    return [
+        'action_set_progress',
+        'set_progress',
+        'setprogress',
+        'semanticsactions.setprogress',
+        'set_value',
+        'setvalue',
+        'direct_set_value'
+    ].some((action) => actions.has(action));
+}
+export function _adjustmentDirections(el) {
+    const actions = _runtimeActionSet(el);
+    return {
+        increment: ['increment', 'accessibility_increment', 'action_increment'].some((action) => actions.has(action)),
+        decrement: ['decrement', 'accessibility_decrement', 'action_decrement'].some((action) => actions.has(action))
+    };
+}
+export function _textFromElement(el) {
+    return String(el?.text ?? el?.contentDescription ?? el?.contentDesc ?? el?.accessibilityLabel ?? el?.value ?? '').trim();
+}
+export function _parseLeadingNumber(text) {
+    const match = text.trim().match(/^([-+]?\d+(?:\.\d+)?)(?:\s*[a-zA-Z%]+)?$/);
+    if (!match)
+        return null;
+    const value = Number(match[1]);
+    return Number.isFinite(value) ? value : null;
+}

package/dist/interact/adjustment/slider-labels.js

@@ -0,0 +1,84 @@
+import { _normalize, _normalizeBounds } from '../targeting/element-helpers.js';
+import { _textFromElement, _parseLeadingNumber } from './control-values.js';
+export function _inferLabeledSliderState(elements, track) {
+    const trackBounds = _normalizeBounds(track?.bounds);
+    if (!track || !trackBounds)
+        return null;
+    const type = _normalize(track.type ?? track.class ?? '');
+    const role = _normalize(track.role ?? '');
+    const width = trackBounds[2] - trackBounds[0];
+    const height = trackBounds[3] - trackBounds[1];
+    const wideTrackLike = width >= 240 && height <= 220;
+    const knownTrackLike = /slider|seekbar|range/.test(type) || /slider|range/.test(role);
+    if (!wideTrackLike && !knownTrackLike)
+        return null;
+    const trackTop = trackBounds[1];
+    const trackBottom = trackBounds[3];
+    const trackCenterX = (trackBounds[0] + trackBounds[2]) / 2;
+    const labels = elements
+        .map((el, index) => {
+        const bounds = _normalizeBounds(el.bounds);
+        const text = _textFromElement(el);
+        const value = _parseLeadingNumber(text);
+        return bounds && text && value !== null
+            ? {
+                index,
+                el,
+                text,
+                value,
+                bounds,
+                centerX: (bounds[0] + bounds[2]) / 2,
+                centerY: (bounds[1] + bounds[3]) / 2,
+                hasUnit: /[a-zA-Z%]/.test(text)
+            }
+            : null;
+    })
+        .filter((label) => !!label);
+    const rangeLabels = labels
+        .filter((label) => {
+        const verticallyNearTrack = label.centerY >= trackTop - 520 && label.centerY <= trackBottom + 260;
+        const horizontallyNearTrack = label.centerX >= trackBounds[0] - 120 && label.centerX <= trackBounds[2] + 120;
+        return verticallyNearTrack && horizontallyNearTrack && label.hasUnit;
+    })
+        .sort((a, b) => a.centerX - b.centerX);
+    if (rangeLabels.length < 2)
+        return null;
+    const minLabel = rangeLabels[0];
+    const maxLabel = rangeLabels[rangeLabels.length - 1];
+    if (!minLabel || !maxLabel || maxLabel.value <= minLabel.value)
+        return null;
+    const currentCandidates = labels
+        .filter((label) => {
+        if (label.index === minLabel.index || label.index === maxLabel.index)
+            return false;
+        if (label.value < minLabel.value || label.value > maxLabel.value)
+            return false;
+        if (label.centerY < trackTop - 950 || label.centerY > minLabel.centerY - 20)
+            return false;
+        return label.centerX >= trackCenterX - 80;
+    })
+        .sort((a, b) => {
+        const yDistance = Math.abs((trackTop - 420) - a.centerY) - Math.abs((trackTop - 420) - b.centerY);
+        if (yDistance !== 0)
+            return yDistance;
+        return b.centerX - a.centerX;
+    });
+    const currentLabel = currentCandidates[0];
+    if (!currentLabel)
+        return null;
+    const candidateBelowRangeLabels = minLabel.centerY < trackTop && maxLabel.centerY < trackTop;
+    const labelDerivedBounds = [
+        Math.min(minLabel.bounds[0], trackBounds[0]),
+        Math.max(currentLabel.bounds[3] + 12, Math.min(minLabel.bounds[1], maxLabel.bounds[1]) - 160),
+        Math.max(maxLabel.bounds[2], trackBounds[2]),
+        Math.max(currentLabel.bounds[3] + 80, Math.min(minLabel.bounds[1], maxLabel.bounds[1]) - 32)
+    ];
+    return {
+        current: currentLabel.value,
+        min: minLabel.value,
+        max: maxLabel.value,
+        value_range: { min: minLabel.value, max: maxLabel.value },
+        touch_bounds: candidateBelowRangeLabels ? labelDerivedBounds : trackBounds,
+        source: 'nearby_labels'
+    };
+}

package/dist/interact/assertions/screen-assertion.js

@@ -0,0 +1,37 @@
+import { buildObservationTrace } from '../interaction-trace.js';
+function compareScreen(input, observed, label) {
+    const { fingerprint, screen } = input;
+    if (fingerprint) {
+        const success = observed.fingerprint === fingerprint;
+        return { success, basis: 'fingerprint', reason: success ? `observed fingerprint matches expected fingerprint ${fingerprint}` : `expected fingerprint ${fingerprint} but observed ${observed.fingerprint ?? 'null'}` };
+    }
+    if (screen) {
+        const candidates = new Set();
+        if (observed.screen)
+            candidates.add(observed.screen);
+        if (label)
+            candidates.add(label);
+        const success = candidates.has(screen);
+        return { success, basis: 'screen', reason: success ? `observed screen matches expected screen ${screen}` : `expected screen ${screen} but observed ${label ?? observed.screen ?? 'null'}` };
+    }
+    return { success: false, basis: 'none', reason: 'No fingerprint or screen expectation provided' };
+}
+export async function expectScreen(input, deps) {
+    const observed = await deps.fingerprint({ platform: input.platform, deviceId: input.deviceId });
+    const screen = { fingerprint: observed?.fingerprint ?? null, screen: observed?.activity ?? null };
+    let label = screen.screen;
+    if (!input.fingerprint && input.screen && input.platform !== 'ios') {
+        try {
+            const current = await deps.current({ deviceId: input.deviceId });
+            label = current?.shortActivity || current?.activity || label;
+        }
+        catch { /* Keep the fingerprint-derived activity if current-screen lookup is unavailable. */ }
+    }
+    const comparison = compareScreen(input, screen, label);
+    const expected = { fingerprint: input.fingerprint ?? null, screen: input.screen ?? null };
+    const observedScreen = { fingerprint: screen.fingerprint, screen: label };
+    return { success: comparison.success, observed_screen: observedScreen, expected_screen: expected,
+        confidence: comparison.success ? 1 : 0, comparison: { basis: comparison.basis, matched: comparison.success, reason: comparison.reason },
+        trace: buildObservationTrace({ actionType: 'expect_screen', stage: 'verify', success: comparison.success, attempts: 1,
+            metadata: { expected_screen: expected, observed_screen: observedScreen, comparison: { basis: comparison.basis, matched: comparison.success } } }) };
+}