xc-mcp/dist/utils/coordinate-transform.d.ts

MCP server that wraps Xcode command-line tools for iOS/macOS development workflows

/**
 * Coordinate transformation for screenshot → device mapping
 *
 * <architecture>
 * Screenshots may be resized for token efficiency (e.g., 256×512 from 1179×2556).
 * User identifies elements at screenshot coordinates (100, 200).
 * IDB requires absolute device coordinates (200, 400).
 * This utility transforms between coordinate spaces.
 * </architecture>
 */
export interface CoordinateTransform {
    scaleX: number;
    scaleY: number;
    originalDimensions: {
        width: number;
        height: number;
    };
    displayDimensions: {
        width: number;
        height: number;
    };
}
export interface TransformToDeviceOptions {
    screenshotX: number;
    screenshotY: number;
    transform: CoordinateTransform;
}
export interface DeviceCoordinates {
    x: number;
    y: number;
}
export interface DeviceDimensions {
    width: number;
    height: number;
}
/**
 * Transform screenshot coordinates to device coordinates
 *
 * Why: Screenshots are resized for token efficiency, but IDB needs absolute device coordinates.
 * This function applies the scale transformation to convert between coordinate spaces.
 *
 * @param options - Screenshot coordinates and transformation parameters
 * @returns Device coordinates ready for IDB tap/swipe operations
 */
export declare function transformToDevice(options: TransformToDeviceOptions): DeviceCoordinates;
/**
 * Transform device coordinates back to screenshot coordinates
 *
 * Why: For debugging and verification, convert device coordinates back to screenshot space.
 * Enables agents to verify "did I tap the right place on the screenshot?"
 *
 * @param deviceX - Device X coordinate
 * @param deviceY - Device Y coordinate
 * @param transform - Coordinate transformation parameters
 * @returns Screenshot coordinates
 */
export declare function transformToScreenshot(deviceX: number, deviceY: number, transform: CoordinateTransform): DeviceCoordinates;
/**
 * Validate coordinates are within device bounds
 *
 * Why: Prevent taps outside screen boundaries (causes IDB errors).
 * Better to fail fast with clear error than pass invalid coords to IDB.
 *
 * @param x - Device X coordinate
 * @param y - Device Y coordinate
 * @param deviceDimensions - Device screen dimensions
 * @throws McpError if coordinates are outside device bounds
 */
export declare function validateDeviceCoordinates(x: number, y: number, deviceDimensions: DeviceDimensions): void;
/**
 * Create coordinate transform from screenshot size metadata
 *
 * Why: Convenience helper to create transform from screenshot-inline response.
 * Agents can pass coordinateTransform directly without manual calculation.
 *
 * @param originalWidth - Device screen width
 * @param originalHeight - Device screen height
 * @param displayWidth - Screenshot width
 * @param displayHeight - Screenshot height
 * @returns CoordinateTransform ready for transformToDevice()
 */
export declare function createCoordinateTransform(originalWidth: number, originalHeight: number, displayWidth: number, displayHeight: number): CoordinateTransform;
//# sourceMappingURL=coordinate-transform.d.ts.map