@midscene/computer 1.12.5 → 1.12.6-beta-20260909033030.0

package/dist/lib/index.js

@@ -68,6 +68,207 @@ const img_namespaceObject = require("@midscene/shared/img");
 const logger_namespaceObject = require("@midscene/shared/logger");
 const external_screenshot_desktop_namespaceObject = require("screenshot-desktop");
 var external_screenshot_desktop_default = /*#__PURE__*/ __webpack_require__.n(external_screenshot_desktop_namespaceObject);
+const US_SHIFTED_CHARACTER_KEYS = new Map([
+    [
+        '~',
+        '`'
+    ],
+    [
+        '!',
+        '1'
+    ],
+    [
+        '@',
+        '2'
+    ],
+    [
+        '#',
+        '3'
+    ],
+    [
+        '$',
+        '4'
+    ],
+    [
+        '%',
+        '5'
+    ],
+    [
+        '^',
+        '6'
+    ],
+    [
+        '&',
+        '7'
+    ],
+    [
+        '*',
+        '8'
+    ],
+    [
+        '(',
+        '9'
+    ],
+    [
+        ')',
+        '0'
+    ],
+    [
+        '_',
+        '-'
+    ],
+    [
+        '+',
+        '='
+    ],
+    [
+        '{',
+        '['
+    ],
+    [
+        '}',
+        ']'
+    ],
+    [
+        '|',
+        '\\'
+    ],
+    [
+        ':',
+        ';'
+    ],
+    [
+        '"',
+        "'"
+    ],
+    [
+        '<',
+        ','
+    ],
+    [
+        '>',
+        '.'
+    ],
+    [
+        '?',
+        '/'
+    ]
+]);
+function resolveUSShiftedKey(character) {
+    if (/^[A-Z]$/.test(character)) return character.toLowerCase();
+    return US_SHIFTED_CHARACTER_KEYS.get(character);
+}
+const debugKeyboard = (0, logger_namespaceObject.getDebug)('computer:keyboard');
+const APPLE_SCRIPT_KEY_CODES = {
+    return: 36,
+    enter: 36,
+    tab: 48,
+    space: 49,
+    backspace: 51,
+    delete: 51,
+    escape: 53,
+    forwarddelete: 117,
+    left: 123,
+    right: 124,
+    down: 125,
+    up: 126,
+    home: 115,
+    end: 119,
+    pageup: 116,
+    pagedown: 121,
+    f1: 122,
+    f2: 120,
+    f3: 99,
+    f4: 118,
+    f5: 96,
+    f6: 97,
+    f7: 98,
+    f8: 100,
+    f9: 101,
+    f10: 109,
+    f11: 103,
+    f12: 111
+};
+const APPLE_SCRIPT_MODIFIER_KEYS = {
+    command: 'command',
+    cmd: 'command',
+    control: 'control',
+    ctrl: 'control',
+    shift: 'shift',
+    alt: 'option',
+    option: 'option',
+    meta: 'command'
+};
+function buildKeyCommand(key) {
+    const keyCode = APPLE_SCRIPT_KEY_CODES[key.toLowerCase()];
+    if (void 0 !== keyCode) return `key code ${keyCode}`;
+    const escapedKey = key.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    return `keystroke "${escapedKey}"`;
+}
+function resolveModifierKeys(modifiers) {
+    return modifiers.map((modifier)=>APPLE_SCRIPT_MODIFIER_KEYS[modifier.toLowerCase()]).filter((modifier)=>void 0 !== modifier);
+}
+function buildLogicalKeyPress(key, modifiers) {
+    const modifierKeys = resolveModifierKeys(modifiers);
+    const modifierClause = modifierKeys.length ? ` using {${modifierKeys.map((modifier)=>`${modifier} down`).join(', ')}}` : '';
+    return `tell application "System Events" to ${buildKeyCommand(key)}${modifierClause}`;
+}
+function resolvePhysicalKey(key, modifiers) {
+    const resolvedModifiers = [
+        ...modifiers
+    ];
+    const shiftedBaseKey = resolveUSShiftedKey(key);
+    if (void 0 !== shiftedBaseKey) {
+        resolvedModifiers.push('shift');
+        return {
+            key: shiftedBaseKey,
+            modifiers: resolvedModifiers
+        };
+    }
+    return {
+        key,
+        modifiers: resolvedModifiers
+    };
+}
+function buildPhysicalKeyPress(key, modifiers) {
+    const resolved = resolvePhysicalKey(key, modifiers);
+    const modifierKeys = [
+        ...new Set(resolveModifierKeys(resolved.modifiers))
+    ];
+    const keyCommand = buildKeyCommand(resolved.key);
+    if (0 === modifierKeys.length) return `tell application "System Events" to ${keyCommand}`;
+    const releaseCommands = [
+        ...modifierKeys
+    ].reverse().map((modifier)=>`key up ${modifier}`);
+    return [
+        'tell application "System Events"',
+        'try',
+        ...modifierKeys.map((modifier)=>`key down ${modifier}`),
+        keyCommand,
+        'on error errorMessage number errorNumber',
+        ...releaseCommands,
+        'error errorMessage number errorNumber',
+        'end try',
+        ...releaseCommands,
+        'end tell'
+    ].join('\n');
+}
+function buildAppleScriptKeyPress(key, modifiers = [], eventMode = 'logical') {
+    return 'physical' === eventMode ? buildPhysicalKeyPress(key, modifiers) : buildLogicalKeyPress(key, modifiers);
+}
+function sendKeyViaAppleScript(key, modifiers = [], eventMode = 'logical') {
+    const script = buildAppleScriptKeyPress(key, modifiers, eventMode);
+    debugKeyboard('sendKeyViaAppleScript', {
+        key,
+        modifiers,
+        eventMode,
+        script
+    });
+    (0, external_node_child_process_namespaceObject.execFileSync)("osascript", [
+        '-e',
+        script
+    ]);
+}
 const external_node_assert_namespaceObject = require("node:assert");
 var external_node_assert_default = /*#__PURE__*/ __webpack_require__.n(external_node_assert_namespaceObject);
 function _define_property(obj, key, value) {
@@ -142,6 +343,29 @@ class ComputerInputDriver {
         if (void 0 !== modifiers) lib.keyTap(key, modifiers);
         else lib.keyTap(key);
     }
+    keyToggle(key, state, modifiers) {
+        const lib = this.getLibnutOrThrow('keyToggle');
+        if (void 0 !== modifiers) lib.keyToggle(key, state, modifiers);
+        else lib.keyToggle(key, state);
+    }
+    async keyTapWithExplicitModifiers(key, modifiers, delayMs) {
+        const uniqueModifiers = [
+            ...new Set(modifiers)
+        ];
+        if (0 === uniqueModifiers.length) return void this.keyTap(key);
+        const pressedModifiers = [];
+        try {
+            for (const modifier of uniqueModifiers){
+                this.keyToggle(modifier, 'down');
+                pressedModifiers.push(modifier);
+            }
+            await this.delay(delayMs);
+            this.keyTap(key);
+            await this.delay(delayMs);
+        } finally{
+            for (const modifier of pressedModifiers.reverse())this.releaseKey(modifier);
+        }
+    }
     typeString(text) {
         this.getLibnutOrThrow('typeString').typeString(text);
     }
@@ -214,6 +438,15 @@ class ComputerInputDriver {
             this.options.debug(`Failed to release mouse button ${button}: ${error}`);
         }
     }
+    releaseKey(key) {
+        try {
+            const libnut = this.options.getLibnut();
+            external_node_assert_default()(libnut, 'libnut not initialized');
+            libnut.keyToggle(key, 'up');
+        } catch (error) {
+            this.options.debug(`Failed to release key ${key}: ${error}`);
+        }
+    }
     rejectPendingInputDelays() {
         const error = this.createDestroyedError('in-flight input');
         for (const waitRef of this.pendingInputDelayWaits){
@@ -595,92 +828,6 @@ const LIBNUT_FALLBACK_PIXELS_PER_DETENT = 100;
 const LIBNUT_FALLBACK_TICK_DELAY_MS = 30;
 const LIBNUT_FALLBACK_MAX_DETENTS = 200;
 const LIBNUT_FALLBACK_DETENT_AMOUNT = 'win32' === process.platform ? 120 : 1;
-const LINUX_SHIFTED_CHARACTER_KEYS = new Map([
-    [
-        '~',
-        '`'
-    ],
-    [
-        '!',
-        '1'
-    ],
-    [
-        '@',
-        '2'
-    ],
-    [
-        '#',
-        '3'
-    ],
-    [
-        '$',
-        '4'
-    ],
-    [
-        '%',
-        '5'
-    ],
-    [
-        '^',
-        '6'
-    ],
-    [
-        '&',
-        '7'
-    ],
-    [
-        '*',
-        '8'
-    ],
-    [
-        '(',
-        '9'
-    ],
-    [
-        ')',
-        '0'
-    ],
-    [
-        '_',
-        '-'
-    ],
-    [
-        '+',
-        '='
-    ],
-    [
-        '{',
-        '['
-    ],
-    [
-        '}',
-        ']'
-    ],
-    [
-        '|',
-        '\\'
-    ],
-    [
-        ':',
-        ';'
-    ],
-    [
-        '"',
-        "'"
-    ],
-    [
-        '<',
-        ','
-    ],
-    [
-        '>',
-        '.'
-    ],
-    [
-        '?',
-        '/'
-    ]
-]);
 const LIBNUT_FALLBACK_EDGE_DETENTS = Math.min(LIBNUT_FALLBACK_MAX_DETENTS, Math.max(1, Math.ceil(EDGE_SCROLL_TOTAL_PX / LIBNUT_FALLBACK_PIXELS_PER_DETENT)));
 const DEFAULT_SCROLL_VIEWPORT_RATIO = 0.7;
 const EDGE_SCROLL_SPEC = {
@@ -717,67 +864,6 @@ const EDGE_SCROLL_SPEC = {
         ]
     }
 };
-const APPLESCRIPT_KEY_CODE_MAP = {
-    return: 36,
-    enter: 36,
-    tab: 48,
-    space: 49,
-    backspace: 51,
-    delete: 51,
-    escape: 53,
-    forwarddelete: 117,
-    left: 123,
-    right: 124,
-    down: 125,
-    up: 126,
-    home: 115,
-    end: 119,
-    pageup: 116,
-    pagedown: 121,
-    f1: 122,
-    f2: 120,
-    f3: 99,
-    f4: 118,
-    f5: 96,
-    f6: 97,
-    f7: 98,
-    f8: 100,
-    f9: 101,
-    f10: 109,
-    f11: 103,
-    f12: 111
-};
-const APPLESCRIPT_MODIFIER_MAP = {
-    command: 'command down',
-    cmd: 'command down',
-    control: 'control down',
-    ctrl: 'control down',
-    shift: 'shift down',
-    alt: 'option down',
-    option: 'option down',
-    meta: 'command down'
-};
-function sendKeyViaAppleScript(key, modifiers = []) {
-    const lowerKey = key.toLowerCase();
-    const keyCode = APPLESCRIPT_KEY_CODE_MAP[lowerKey];
-    const modifierParts = modifiers.map((m)=>APPLESCRIPT_MODIFIER_MAP[m.toLowerCase()]).filter(Boolean);
-    const modifierStr = modifierParts.length > 0 ? ` using {${modifierParts.join(', ')}}` : '';
-    let script;
-    if (void 0 !== keyCode) script = `tell application "System Events" to key code ${keyCode}${modifierStr}`;
-    else {
-        const escapedKey = key.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-        script = `tell application "System Events" to keystroke "${escapedKey}"${modifierStr}`;
-    }
-    debugDevice('sendKeyViaAppleScript', {
-        key,
-        modifiers,
-        script
-    });
-    (0, external_node_child_process_namespaceObject.execFileSync)("osascript", [
-        '-e',
-        script
-    ]);
-}
 function escapePowershellSingleQuoted(value) {
     return value.replace(/'/g, "''");
 }
@@ -1205,7 +1291,7 @@ Available Displays: ${displays.length > 0 ? displays.map((d)=>d.name).join(', ')
     }
     async healthCheck(displays) {
         console.log('[HealthCheck] Starting health check...');
-        console.log("[HealthCheck] @midscene/computer v1.12.5");
+        console.log("[HealthCheck] @midscene/computer v1.12.6-beta-20260909033030.0");
         console.log('[HealthCheck] Taking screenshot...');
         const screenshotTimeout = 15000;
         let timeoutId;
@@ -1382,7 +1468,7 @@ $g.Dispose(); $bmp.Dispose(); $ms.Dispose()
             ]);
             else {
                 const modifier = 'darwin' === process.platform ? 'command' : 'control';
-                this.inputDriver.keyTap('v', [
+                await this.sendLocalModifiedKey('v', [
                     modifier
                 ]);
             }
@@ -1399,12 +1485,16 @@ $g.Dispose(); $bmp.Dispose(); $ms.Dispose()
     }
     async typeStringWithDelay(text, keyboardTypeDelay) {
         await (0, device_namespaceObject.sendTextSequentially)(text.replace(/\r\n?/g, '\n'), {
-            sendCharacter: (character)=>{
-                const linuxShiftedKey = 'linux' === process.platform ? LINUX_SHIFTED_CHARACTER_KEYS.get(character) : void 0;
+            sendCharacter: async (character)=>{
+                const linuxShiftedKey = 'linux' === process.platform ? US_SHIFTED_CHARACTER_KEYS.get(character) : void 0;
+                const pacedShiftedKey = !this.useAppleScript && (this.options?.keyboardShortcutDelay ?? 0) > 0 ? resolveUSShiftedKey(character) : void 0;
                 if ('\n' === character) this.inputDriver.sendKey('return');
                 else if ('\t' === character) this.inputDriver.sendKey('tab');
                 else if (' ' === character) this.inputDriver.sendKey('space');
                 else if (this.useAppleScript) this.inputDriver.sendKeyViaAppleScript(character);
+                else if (void 0 !== pacedShiftedKey) await this.sendLocalModifiedKey(pacedShiftedKey, [
+                    'shift'
+                ]);
                 else if (void 0 !== linuxShiftedKey) this.inputDriver.keyTap(linuxShiftedKey, [
                     'shift'
                 ]);
@@ -1425,12 +1515,17 @@ $g.Dispose(); $bmp.Dispose(); $ms.Dispose()
             return;
         }
         const modifier = 'darwin' === process.platform ? 'command' : 'control';
-        this.inputDriver.keyTap('a', [
+        await this.sendLocalModifiedKey('a', [
             modifier
         ]);
         await this.inputDriver.delay(50);
         this.inputDriver.keyTap('backspace');
     }
+    async sendLocalModifiedKey(key, modifiers) {
+        const shortcutDelay = this.options?.keyboardShortcutDelay ?? 0;
+        if (modifiers.length > 0 && shortcutDelay > 0) return void await this.inputDriver.keyTapWithExplicitModifiers(key, modifiers, shortcutDelay);
+        this.inputDriver.keyTap(key, modifiers);
+    }
     async pressKeyboardShortcut(keyName) {
         const keys = keyName.split('+');
         const modifiers = keys.slice(0, -1).map(normalizeKeyName);
@@ -1441,6 +1536,7 @@ $g.Dispose(); $bmp.Dispose(); $ms.Dispose()
             modifiers,
             driver: this.useAppleScript ? "applescript" : 'libnut'
         });
+        if (!this.useAppleScript && modifiers.length > 0 && (this.options?.keyboardShortcutDelay ?? 0) > 0) return void await this.sendLocalModifiedKey(key, modifiers);
         this.inputDriver.sendKey(key, modifiers);
     }
     resolveUntargetedScrollPoint(screenSize) {
@@ -1594,7 +1690,7 @@ $g.Dispose(); $bmp.Dispose(); $ms.Dispose()
         device_define_property(this, "inputDriver", new ComputerInputDriver({
             getLibnut: ()=>device_libnut,
             useAppleScript: ()=>this.useAppleScript,
-            sendKeyViaAppleScript,
+            sendKeyViaAppleScript: (key, modifiers)=>sendKeyViaAppleScript(key, modifiers, this.options?.keyboardEventMode ?? 'logical'),
             runPhasedScroll,
             debug: (message)=>debugDevice(message)
         }));
@@ -1720,6 +1816,7 @@ $g.Dispose(); $bmp.Dispose(); $ms.Dispose()
                 }
             }
         });
+        if (options?.keyboardShortcutDelay !== void 0 && (!Number.isFinite(options.keyboardShortcutDelay) || options.keyboardShortcutDelay < 0)) throw new Error('keyboardShortcutDelay must be a finite non-negative number');
         this.options = options;
         this.displayId = options?.displayId;
         this.useAppleScript = 'darwin' === process.platform && options?.keyboardDriver !== 'libnut';
@@ -2467,6 +2564,8 @@ function createLocalComputerDevice(opts) {
         keyboardTypeDelay: opts?.keyboardTypeDelay,
         inputStrategy: opts?.inputStrategy,
         keyboardDriver: opts?.keyboardDriver,
+        keyboardEventMode: opts?.keyboardEventMode,
+        keyboardShortcutDelay: opts?.keyboardShortcutDelay,
         headless: opts?.headless,
         xvfbResolution: opts?.xvfbResolution,
         keepXvfbAliveUntilProcessExit: opts?.keepXvfbAliveUntilProcessExit
@@ -2527,6 +2626,11 @@ const computerInitArgShape = {
     headless: core_namespaceObject.z.boolean().optional().describe('Start virtual display via Xvfb (Linux local mode only). Ignored when host is set.'),
     keyboardTypeDelay: core_namespaceObject.z.number().finite().nonnegative().optional().describe('Finite non-negative delay in milliseconds between keystrokes. In "legacy" mode, positive values enable key-by-key input; zero or omitted uses clipboard input.'),
     inputStrategy: core_namespaceObject.z["enum"](device_namespaceObject.inputStrategies).optional().describe('Text input strategy. "legacy" (default) preserves current Computer behavior, "sequential" sends one Unicode code point at a time, and "bulk" uses one backend input operation. "bulk" requires keyboardTypeDelay to be omitted or set to 0.'),
+    keyboardEventMode: core_namespaceObject.z["enum"]([
+        'logical',
+        'physical'
+    ]).optional().describe('macOS AppleScript keyboard event mode for local control. "logical" (default) uses a compact keystroke command; "physical" sends explicit modifier transitions for foreground apps that require separate key state changes. Both modes use AppleScript, and "physical" is not hardware input. It assumes an en-US layout for shifted punctuation and requires sequential text input or a positive keyboardTypeDelay. Ignored in RDP mode and outside the macOS AppleScript driver.'),
+    keyboardShortcutDelay: core_namespaceObject.z.number().finite().nonnegative().optional().describe('Finite non-negative delay in milliseconds around modifier transitions for local libnut keyboard events. Positive values pace shortcuts and the implicit Shift used by uppercase or en-US punctuation during sequential input. Ignored in RDP mode and by the macOS AppleScript driver.'),
     host: core_namespaceObject.z.string().optional().describe('RDP host (FQDN or IP). Set this to switch into RDP mode.'),
     port: core_namespaceObject.z.number().optional().describe('RDP port (default 3389). Requires host.'),
     username: core_namespaceObject.z.string().optional().describe('RDP username. Requires host.'),
@@ -2543,7 +2647,7 @@ const computerInitArgShape = {
 function adaptComputerInitArgs(extracted) {
     if (!extracted || 0 === Object.keys(extracted).length) return;
     if (extracted.host) {
-        const { displayId: _d, headless: _h, ...rdpFields } = extracted;
+        const { displayId: _d, headless: _h, keyboardEventMode: _k, keyboardShortcutDelay: _s, ...rdpFields } = extracted;
         const host = normalizeRdpHost(extracted.host);
         return {
             mode: 'rdp',
@@ -2557,6 +2661,8 @@ function adaptComputerInitArgs(extracted) {
         headless: extracted.headless,
         keyboardTypeDelay: extracted.keyboardTypeDelay,
         inputStrategy: extracted.inputStrategy,
+        keyboardEventMode: extracted.keyboardEventMode,
+        keyboardShortcutDelay: extracted.keyboardShortcutDelay,
         ...(0, agent_behavior_init_args_namespaceObject.extractAgentBehaviorInitArgs)(extracted) ?? {}
     };
 }
@@ -2608,6 +2714,8 @@ class ComputerMidsceneTools extends base_tools_namespaceObject.BaseMidsceneTools
         const headless = opts?.mode === 'local' ? opts.headless : void 0;
         const keyboardTypeDelay = opts?.keyboardTypeDelay;
         const inputStrategy = opts?.inputStrategy;
+        const keyboardEventMode = opts?.mode === 'local' ? opts.keyboardEventMode : void 0;
+        const keyboardShortcutDelay = opts?.mode === 'local' ? opts.keyboardShortcutDelay : void 0;
         agent_tools_debug('Creating Computer agent with displayId:', displayId || 'primary');
         const agentOpts = {
             ...displayId ? {
@@ -2622,6 +2730,12 @@ class ComputerMidsceneTools extends base_tools_namespaceObject.BaseMidsceneTools
             ...void 0 !== inputStrategy ? {
                 inputStrategy
             } : {},
+            ...void 0 !== keyboardEventMode ? {
+                keyboardEventMode
+            } : {},
+            ...void 0 !== keyboardShortcutDelay ? {
+                keyboardShortcutDelay
+            } : {},
             ...this.options.keepXvfbAliveUntilProcessExit ? {
                 keepXvfbAliveUntilProcessExit: true
             } : {},
@@ -2703,7 +2817,7 @@ class ComputerMidsceneTools extends base_tools_namespaceObject.BaseMidsceneTools
 }
 const env_namespaceObject = require("@midscene/shared/env");
 function version() {
-    const currentVersion = "1.12.5";
+    const currentVersion = "1.12.6-beta-20260909033030.0";
     console.log(`@midscene/computer v${currentVersion}`);
     return currentVersion;
 }

package/dist/types/index.d.ts

@@ -139,6 +139,7 @@ export declare class ComputerDevice implements AbstractInterface {
     private smartTypeString;
     private typeStringWithDelay;
     private selectAllAndDelete;
+    private sendLocalModifiedKey;
     private pressKeyboardShortcut;
     private resolveUntargetedScrollPoint;
     private moveMouseToScrollTarget;
@@ -177,6 +178,32 @@ export declare interface ComputerDeviceOpt extends ComputerDeviceInputOpt {
      * - 'libnut': Use libnut's keyTap (faster but may not work with some TUI apps)
      */
     keyboardDriver?: 'applescript' | 'libnut';
+    /**
+     * How the macOS AppleScript keyboard driver represents modifier keys.
+     * `logical` keeps the default compact `keystroke ... using` behavior.
+     * `physical` emits explicit modifier key-down/key-up transitions for
+     * foreground apps that require separate modifier state changes, including
+     * some remote-control clients and virtual machine consoles. Both modes use
+     * AppleScript System Events; `physical` does not emit hardware events.
+     * Physical mode assumes an en-US layout for shifted punctuation and may type
+     * base keys in native macOS applications. Text input must use sequential
+     * input or a positive `keyboardTypeDelay` to emit individual keys.
+     *
+     * Ignored outside macOS and when `keyboardDriver` is `libnut`.
+     * @default 'logical'
+     */
+    keyboardEventMode?: KeyboardEventMode;
+    /**
+     * Delay in milliseconds around explicit modifier transitions for local
+     * libnut keyboard events. A positive value changes modified shortcuts and
+     * shifted en-US text characters into modifier-down, main-key, and
+     * modifier-up phases. This can help foreground clients whose full-screen
+     * keyboard capture misses rapidly synthesized modifier state changes.
+     *
+     * Ignored by the macOS AppleScript driver and RDP mode.
+     * @default 0
+     */
+    keyboardShortcutDelay?: number;
     /**
      * Headless mode via Xvfb (Linux only).
      * - true: start Xvfb virtual display
@@ -210,7 +237,7 @@ export declare type ComputerInterface = ComputerDevice | RDPDevice;
 /** Init args for the local desktop agent (macOS/Windows/Linux). */
 declare type ComputerLocalInitArgs = {
     mode: 'local';
-} & Pick<ComputerDeviceOpt, 'displayId' | 'headless'> & Pick<ComputerDeviceOpt, 'inputStrategy' | 'keyboardTypeDelay'> & AgentBehaviorInitArgs;
+} & Pick<ComputerDeviceOpt, 'displayId' | 'headless'> & Pick<ComputerDeviceOpt, 'inputStrategy' | 'keyboardTypeDelay' | 'keyboardEventMode' | 'keyboardShortcutDelay'> & AgentBehaviorInitArgs;
 
 /**
  * Computer-specific tools manager
@@ -297,6 +324,17 @@ export declare class HelperProcessRDPBackendClient implements RDPBackendClient {
     private shutdownHelper;
 }
 
+/**
+ * Modifier delivery mode for the macOS AppleScript keyboard backend.
+ *
+ * `logical` uses the compact `keystroke ... using` form. `physical` emits
+ * explicit modifier transitions for foreground applications that require
+ * separate key state changes. Both modes use AppleScript System Events;
+ * `physical` does not emit hardware events. It assumes an en-US mapping for
+ * shifted punctuation and should be enabled only when needed.
+ */
+export declare type KeyboardEventMode = 'logical' | 'physical';
+
 export declare type LocalComputerAgentOpt = BaseComputerAgentOpt & Omit<ComputerDeviceOpt, keyof ComputerAgentSharedDeviceOpt>;
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midscene/computer",
-  "version": "1.12.5",
+  "version": "1.12.6-beta-20260909033030.0",
   "description": "Midscene.js Computer Desktop Automation",
   "license": "MIT",
   "repository": {
@@ -33,8 +33,8 @@
     "@computer-use/libnut": "^4.2.0",
     "clipboardy": "^4.0.0",
     "screenshot-desktop": "^1.15.3",
-    "@midscene/core": "1.12.5",
-    "@midscene/shared": "1.12.5"
+    "@midscene/core": "1.12.6-beta-20260909033030.0",
+    "@midscene/shared": "1.12.6-beta-20260909033030.0"
   },
   "optionalDependencies": {
     "node-mac-permissions": "2.5.0"