@ycheung5/pi-computer-use 0.1.0 → 0.1.1

package/README.md

@@ -33,7 +33,7 @@ Use your existing Pi installation. Another computer-use extension is not require
 
 ### From npm
 
-Install the published package with:
+Install [@ycheung5/pi-computer-use](https://www.npmjs.com/package/@ycheung5/pi-computer-use) from npm:
 
 ```sh
 pi install npm:@ycheung5/pi-computer-use
@@ -57,11 +57,11 @@ To retain the built checkout as a local Pi package, run `pi install .` from that
 
 ### Install a built archive
 
-For a prebuilt `ycheung5-pi-computer-use-0.1.0.tgz` produced by `npm pack`:
+For a prebuilt `ycheung5-pi-computer-use-0.1.1.tgz` produced by `npm pack`:
 
 ```sh
 mkdir pi-computer-use
-tar -xzf ycheung5-pi-computer-use-0.1.0.tgz -C pi-computer-use --strip-components=1
+tar -xzf ycheung5-pi-computer-use-0.1.1.tgz -C pi-computer-use --strip-components=1
 cd pi-computer-use
 npm install --omit=dev --omit=peer --ignore-scripts
 pi install .
@@ -128,12 +128,12 @@ Settings are shared across projects and native Windows/WSL2 Pi in `%LOCALAPPDATA
 
 ## Tested scope and known limits
 
-The release audit recorded **187 passing portable tests**, one opt-in historical-reference skip, and checks of the built distribution. Named native/browser agent workflows and human control/display checks have separate [acceptance receipts](docs/validation.md#capability-coverage). CI is not a claim that every application or desktop state works.
+The input-timing update passed **214 portable tests**, with one opt-in historical-reference skip, plus native compilation and built-distribution checks. Named native/browser agent workflows and human control/display checks have separate [acceptance receipts](docs/validation.md#capability-coverage). CI is not a claim that every application or desktop state works.
 
 - Second-computer WSL installation and desktop actions were user-confirmed. Fresh native-Windows installation, broken-prerequisite handling and shutdown in that clean environment remain accepted, unverified first-release test limitations.
 - Display mapping was exercised at **100%, 150% and 175%**, including a changed negative-origin layout. Other configurations, including 200%, remain unverified.
 - Windows may refuse foreground activation or access to elevated/protected interfaces. The extension reports refusal rather than bypassing Windows protections.
-- Explicit Unicode SendInput retains a **50 ms per-unit delay**. Clipboard preservation has format-dependent limits; installed Firefox support is experimental.
+- Explicit Unicode SendInput defaults to a **50 ms per-unit delay**; explicit native pacing and per-call deadlines are [configurable](docs/text.md#sendinput-pacing-and-deadlines). Clipboard preservation has format-dependent limits; installed Firefox support is experimental.
 - Arm64, genuine same-HWND/PID reuse, verified UIPI denial and additional recorder/remote/capture variants remain unverified.
 
 See the [release scope](docs/validation.md#first-release-preparation) for the accepted limits and their evidence.

package/assets/input-timing.cs

@@ -0,0 +1,42 @@
+using System;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.Threading;
+
+partial class WindowsBridge {
+  // One call's budget and guarded waits; no held-input state or scheduling policy.
+  sealed class InputTiming {
+    internal readonly long TimeoutMs;
+    internal readonly string DeadlinePolicy;
+    readonly Stopwatch elapsed=Stopwatch.StartNew();
+    internal static long Milliseconds(Dictionary<string,object> args,string name,long fallback) {
+      object raw;if(!args.TryGetValue(name,out raw))return fallback;
+      if(!(raw is byte || raw is short || raw is int || raw is long || raw is float || raw is double || raw is decimal))throw new InvalidOperationException("INVALID_ARGUMENTS: "+name+" must be non-negative safe whole milliseconds");
+      double value=Convert.ToDouble(raw);
+      if(Double.IsNaN(value) || Double.IsInfinity(value) || value<0 || value>9007199254740991D || Math.Floor(value)!=value)throw new InvalidOperationException("INVALID_ARGUMENTS: "+name+" must be non-negative safe whole milliseconds");
+      return (long)value;
+    }
+    internal InputTiming(Dictionary<string,object> args,long requestedDuration,bool explicitDuration,long ordinaryTimeoutMs) {
+      if(args.ContainsKey("timeoutMs")){TimeoutMs=Milliseconds(args,"timeoutMs",0);DeadlinePolicy=TimeoutMs==0?"disabled":"explicit";}
+      else {
+        if(requestedDuration>9007199254740991L-ordinaryTimeoutMs)throw new InvalidOperationException("INVALID_ARGUMENTS: derived execution duration is not representable");
+        TimeoutMs=ordinaryTimeoutMs+requestedDuration;DeadlinePolicy=explicitDuration?"derived":"default";
+      }
+    }
+    internal void Check() {
+      if(TimeoutMs!=0 && elapsed.ElapsedMilliseconds>=TimeoutMs)throw new InvalidOperationException("WORKER_TIMEOUT: input exceeded the execution deadline; input was not replayed");
+    }
+    internal void Wait(long milliseconds,EventWaitHandle cancel,Action check) {
+      Stopwatch wait=Stopwatch.StartNew();
+      for(;;) {
+        Check();check();
+        long remaining=milliseconds-wait.ElapsedMilliseconds;
+        if(remaining<=0)return;
+        long interval=Math.Min(25L,remaining);
+        if(TimeoutMs!=0)interval=Math.Min(interval,Math.Max(1L,TimeoutMs-elapsed.ElapsedMilliseconds));
+        if(cancel.WaitOne((int)interval))throw new InvalidOperationException("COMPUTER_USE_STOPPED");
+      }
+    }
+    internal Dictionary<string,object> Describe() {return new Dictionary<string,object>{{"timeoutMs",TimeoutMs},{"deadlinePolicy",DeadlinePolicy}};}
+  }
+}

package/assets/pointer.cs

@@ -118,11 +118,18 @@ partial class WindowsBridge {
     Dictionary<string,object> result=Result(true,action);result["cleanupConfirmed"]=true;
     IntPtr window=IntPtr.Zero,before=IntPtr.Zero;uint owner=0;
     ControlPoint original=new ControlPoint(),last=original;
-    bool moved=false,held=false,releaseFailed=false,activated=false;uint up=4;
+    bool moved=false,held=false,releaseFailed=false,activated=false,inputDispatched=false;uint up=4;
+    long holdMs=0;InputTiming timing=null;
     AutomationElement element=null;HashSet<long> popups=new HashSet<long>();
     InteractionGuard interaction=null;
     EventWaitHandle cancel=null;
     try {
+      if(action=="click") {
+        holdMs=InputTiming.Milliseconds(args,"holdMs",0);
+        timing=new InputTiming(args,holdMs,args.ContainsKey("holdMs"),40000);
+        var policy=timing.Describe();policy["holdMs"]=holdMs;result["timing"]=policy;
+        if((args.ContainsKey("holdMs") || args.ContainsKey("timeoutMs")) && (TextOption(args,"dispatch","auto")=="background" || (args.ContainsKey("activate") && !Option(args,"activate",false))))throw new InvalidOperationException("TIMING_UNSUPPORTED: click timing requires native foreground dispatch without explicit activate: false");
+      }
       interaction=new InteractionGuard(TextOption(args,"_cancelEvent",""),NumberOption(args,"_stopProcessId",0));before=GetForegroundWindow();GetCursorPos(out original);last=original;
       // Resolve without activation: validate identity and point before any takeover.
       Dictionary<string,object> quiet=new Dictionary<string,object>(args);quiet["activate"]=false;
@@ -139,7 +146,7 @@ partial class WindowsBridge {
       string button=TextOption(args,"button","left"),dispatch=TextOption(args,"dispatch","auto");
       if(action=="click" || action=="double_click" || action=="drag")ForgetTextFocus();
       if(element!=null && !element.Current.IsEnabled)throw new InvalidOperationException("ELEMENT_DISABLED");
-      bool useBackground=dispatch=="background" || (action=="click" && element!=null && button=="left" && dispatch=="auto" && !Option(args,"activate",false));
+      bool useBackground=dispatch=="background" || (action=="click" && !args.ContainsKey("holdMs") && !args.ContainsKey("timeoutMs") && element!=null && button=="left" && dispatch=="auto" && !Option(args,"activate",false));
       if(useBackground && element!=null) {
         if(action=="click" && button=="left") {
           Dictionary<string,object> controlArgs=new Dictionary<string,object>(args);controlArgs["fallbackClick"]=true;
@@ -181,7 +188,7 @@ partial class WindowsBridge {
       int repetitions=action=="double_click"?2:1;
       for(int iteration=0;iteration<repetitions;iteration++) {
         for(int i=0;i<path.Count;i++) {
-          interaction.Check();
+          if(timing!=null)timing.Check();interaction.Check();
           ControlPoint p=path[i],current;GetCursorPos(out current);
           if(moved && (current.X!=last.X || current.Y!=last.Y))throw new InvalidOperationException("USER_INPUT_CHANGED: pointer moved during automation");
           if(action=="drag" && i>0) {
@@ -197,9 +204,13 @@ partial class WindowsBridge {
           } else PointerCheck(cancel,window,owner,p,true,action!="move" || Option(args,"activate",false));
           if(action=="click" || action=="double_click" || (action=="drag" && i==0)) {
             // Set held before the down attempt: uncertain dispatch still requires an up.
-            held=true;PointerSend(down,0);
+            held=true;inputDispatched=true;PointerSend(down,0);
             if(cancel.WaitOne(0))throw new InvalidOperationException("COMPUTER_USE_STOPPED");
           }
+          if(action=="click" && holdMs>0)timing.Wait(holdMs,cancel,delegate {
+            interaction.Check();PointerCheck(cancel,window,owner,p,true);
+            ControlPoint currentPointer;if(!GetCursorPos(out currentPointer) || currentPointer.X!=last.X || currentPointer.Y!=last.Y)throw new InvalidOperationException("USER_INPUT_CHANGED: pointer moved during automation");
+          });
           if(action=="click" || action=="double_click") {PointerSend(up,0);held=false;}
           if(action=="scroll") {int y=NumberOption(args,"deltaY",480),x=NumberOption(args,"deltaX",0);if(y!=0)PointerSend(0x800,-y);if(x!=0){PointerCheck(cancel,window,owner,p,true,action!="move" || Option(args,"activate",false));PointerSend(0x1000,x);}}
           if(action=="drag" && i<path.Count-1 && cancel.WaitOne(10))throw new InvalidOperationException("COMPUTER_USE_STOPPED");
@@ -212,6 +223,7 @@ partial class WindowsBridge {
     finally {
       if(held)try {PointerSend(up,0);held=false;}catch(Exception error){releaseFailed=true;result["ok"]=false;result["error"]="INPUT_CLEANUP_UNCONFIRMED: "+error.Message;}
       result["cleanupConfirmed"]=!releaseFailed;
+      if(action=="click"){result["inputDispatched"]=inputDispatched;result["interrupted"]=!Convert.ToBoolean(result["ok"]);}
       if(cancel!=null)cancel.Dispose();
       if(pointerListener!=null){pointerListener.Dispose();pointerListener=null;}
       ControlPoint now;bool same=CurrentReferenceIntact() && GetCursorPos(out now) && now.X==last.X && now.Y==last.Y;

package/assets/text.cs

@@ -12,6 +12,7 @@ using System.Windows.Automation;
 partial class WindowsBridge {
   [StructLayout(LayoutKind.Sequential)] struct KeyboardInput {public ushort Key,Scan;public uint Flags,Time;public UIntPtr Extra;}
   const int UnicodeInputDelayMs=50;
+  static bool textInputDispatched;
   sealed class HeldKey {public ushort Key,Scan;public uint Flags;}
   [DllImport("user32.dll")] static extern IntPtr GetKeyboardLayout(uint thread);
   [DllImport("user32.dll",CharSet=CharSet.Unicode)] static extern short VkKeyScanEx(char value,IntPtr layout);
@@ -100,6 +101,7 @@ partial class WindowsBridge {
     if(!release){BeginWindowDispatch();NotifyPhysicalInput(true);}
     PointerInput input=new PointerInput{Type=1,Data=new InputUnion{Keyboard=new KeyboardInput{Key=key.Key,Scan=key.Scan,Flags=key.Flags | (release?2U:0U),Extra=OwnedInputMarker}}};
     if(SendInput(1,new PointerInput[]{input},Marshal.SizeOf(typeof(PointerInput)))!=1)throw new InvalidOperationException("KEY_DISPATCH_UNCONFIRMED: partial input must not be replayed");
+    if(!release)textInputDispatched=true;
   }
   static void Down(List<HeldKey> held,HeldKey key) {held.Add(key);KeyEvent(key,false);}
   static void Up(List<HeldKey> held,HeldKey key) {KeyEvent(key,true);held.Remove(key);}
@@ -107,22 +109,29 @@ partial class WindowsBridge {
     switch(key){case "enter":case "return":return 13;case "tab":return 9;case "esc":case "escape":return 27;case "backspace":return 8;case "delete":case "del":return 46;case "home":return 36;case "end":return 35;case "pageup":case "pgup":return 33;case "pagedown":case "pgdn":return 34;case "up":return 38;case "down":return 40;case "left":return 37;case "right":return 39;case "space":return 32;case "insert":case "ins":return 45;case "pause":return 19;case "capslock":return 20;case "numlock":return 144;case "scrolllock":return 145;}
     int number;if(key.StartsWith("f") && Int32.TryParse(key.Substring(1),out number) && number>=1 && number<=24)return (ushort)(111+number);return 0;
   }
-  static void Chord(IEnumerable values,EventWaitHandle cancel,Process listener,IntPtr window,uint owner,List<HeldKey> held,InteractionGuard interaction) {
+  static void Chord(IEnumerable values,EventWaitHandle cancel,Process listener,IntPtr window,uint owner,List<HeldKey> held,InteractionGuard interaction,long holdMs=0,InputTiming timing=null) {
+    Action holdCheck=delegate {
+      TextCheck(cancel,listener,window,owner,IntPtr.Zero,false,interaction);
+    };
+    if(timing!=null)timing.Check();
     List<ushort> modifiers=new List<ushort>();string main=null;
     foreach(object item in values) {string key=Convert.ToString(item),name=key.Trim().ToLowerInvariant();if(name=="ctrl" || name=="control")modifiers.Add(17);else if(name=="alt" || name=="option")modifiers.Add(18);else if(name=="shift")modifiers.Add(16);else if(name=="win" || name=="windows" || name=="cmd" || name=="meta")throw new InvalidOperationException("KEY_BLOCKED");else if(main!=null)throw new InvalidOperationException("INVALID_ARGUMENTS: exactly one non-modifier key required");else main=key;}
-    if(main==null)throw new InvalidOperationException("INVALID_ARGUMENTS: non-modifier key required");
-    ushort code=SpecialKey(main.Trim().ToLowerInvariant());
-    if(code==0) {
+    if(main==null && modifiers.Count!=1)throw new InvalidOperationException("INVALID_ARGUMENTS: one main key or standalone modifier required");
+    ushort code=main==null?(ushort)0:SpecialKey(main.Trim().ToLowerInvariant());
+    if(main!=null && code==0) {
       if(main.Length!=1)throw new InvalidOperationException("INVALID_ARGUMENTS: unsupported key");
       uint ignored;uint thread=GetWindowThreadProcessId(window,out ignored);short mapping=VkKeyScanEx(main[0],GetKeyboardLayout(thread));
-      if(mapping==-1) {if(modifiers.Count>0)throw new InvalidOperationException("KEY_LAYOUT_UNSUPPORTED: chord cannot represent this character");TextCheck(cancel,listener,window,owner,IntPtr.Zero,false,interaction);HeldKey unicode=new HeldKey{Scan=main[0],Flags=4};Down(held,unicode);Up(held,unicode);return;}
+      if(mapping==-1) {if(modifiers.Count>0)throw new InvalidOperationException("KEY_LAYOUT_UNSUPPORTED: chord cannot represent this character");TextCheck(cancel,listener,window,owner,IntPtr.Zero,false,interaction);HeldKey unicode=new HeldKey{Scan=main[0],Flags=4};Down(held,unicode);if(timing!=null && holdMs>0)timing.Wait(holdMs,cancel,holdCheck);Up(held,unicode);return;}
       code=(ushort)(mapping & 255);
       // A named shortcut letter is layout-mapped without adding implicit Shift.
       if(modifiers.Count==0){if((mapping & 0x100)!=0)modifiers.Add(16);if((mapping & 0x200)!=0)modifiers.Add(17);if((mapping & 0x400)!=0)modifiers.Add(18);}
     }
     foreach(ushort modifier in modifiers){TextCheck(cancel,listener,window,owner,IntPtr.Zero,false,interaction);Down(held,new HeldKey{Key=modifier});}
     TextCheck(cancel,listener,window,owner,IntPtr.Zero,false,interaction);
-    HeldKey primary=new HeldKey{Key=code,Flags=(code>=33 && code<=46)?1U:0U};Down(held,primary);Up(held,primary);
+    if(main!=null){HeldKey primary=new HeldKey{Key=code,Flags=(code>=33 && code<=46)?1U:0U};Down(held,primary);}
+    if(timing!=null && holdMs>0)timing.Wait(holdMs,cancel,holdCheck);
+    // Immediate presses release without post-dispatch checks: their effect may move focus.
+    // Positive holds retain the existing keypress target/protection checks during the wait.
     // Release modifiers regardless of target/focus changes caused by the chord.
     for(int i=held.Count-1;i>=0;i--){HeldKey key=held[i];Up(held,key);}
   }
@@ -148,13 +157,34 @@ partial class WindowsBridge {
     throw new InvalidOperationException("CLIPBOARD_RESTORE_UNCONFIRMED");
   }
   static object ExecuteText(string action,Dictionary<string,object> args) {
-    Dictionary<string,object> result=Result(true,action);result["cleanupConfirmed"]=true;
+    Dictionary<string,object> result=Result(true,action);result["cleanupConfirmed"]=true;textInputDispatched=false;
     IntPtr before=IntPtr.Zero,window=IntPtr.Zero;ControlPoint pointer=new ControlPoint();
     List<HeldKey> held=new List<HeldKey>();HashSet<long> popups=new HashSet<long>();
     EventWaitHandle cancel=null;Process listener=null,clipboard=null;bool clipboardMayChange=false,clipboardReplaced=false;
     InteractionGuard interaction=null;
     AutomationElement main=null;bool cleanup=true;
     try {
+      long holdMs=0,inputDelayMs=UnicodeInputDelayMs;InputTiming timing=null;
+      string text=TextOption(args,"text",""),method=TextOption(args,"method","auto");
+      if(text.IndexOf('\0')>=0)throw new InvalidOperationException("INVALID_ARGUMENTS: NUL text cannot be entered safely");
+      if(action=="type_text") {
+        inputDelayMs=InputTiming.Milliseconds(args,"inputDelayMs",UnicodeInputDelayMs);
+        if((args.ContainsKey("inputDelayMs") || args.ContainsKey("timeoutMs")) && (method!="sendinput" || args.ContainsKey("browserTab")))throw new InvalidOperationException("TIMING_UNSUPPORTED: text timing requires explicit native sendinput");
+        if(method=="sendinput") {
+          long units=text.Replace("\r\n","\n").Length;
+          if(inputDelayMs!=0 && units>9007199254740991L/inputDelayMs)throw new InvalidOperationException("INVALID_ARGUMENTS: requested pacing duration is not representable");
+          long duration=args.ContainsKey("inputDelayMs")?units*inputDelayMs:0;
+          timing=new InputTiming(args,duration,args.ContainsKey("inputDelayMs"),40000);
+          var policy=timing.Describe();policy["inputDelayMs"]=inputDelayMs;result["timing"]=policy;
+          result["inputDelayMs"]=inputDelayMs;result["inputUnitsDispatched"]=0;
+        }
+      }
+      if(action=="keypress") {
+        holdMs=InputTiming.Milliseconds(args,"holdMs",0);
+        timing=new InputTiming(args,holdMs,args.ContainsKey("holdMs"),40000);
+        var policy=timing.Describe();policy["holdMs"]=holdMs;result["timing"]=policy;
+        if((args.ContainsKey("holdMs") || args.ContainsKey("timeoutMs")) && TextOption(args,"dispatch","foreground")=="background")throw new InvalidOperationException("TIMING_UNSUPPORTED: keypress timing requires native foreground dispatch");
+      }
       interaction=new InteractionGuard(TextOption(args,"_cancelEvent",""),NumberOption(args,"_stopProcessId",0));before=GetForegroundWindow();GetCursorPos(out pointer);
       Dictionary<string,object> quiet=new Dictionary<string,object>(args);quiet["activate"]=false;
       if(args.ContainsKey("_elementId")) {
@@ -165,15 +195,13 @@ partial class WindowsBridge {
       ApplyVisibleIntent(args,window);
       if(textFocus.Count>0 && !textFocus.ContainsKey(PointerOriginKey(window)))ForgetTextFocus();
       uint owner=WindowOwner(window);popups=ControlPopups(owner,window);
-      string text=TextOption(args,"text",""),method=TextOption(args,"method","auto");
-      if(text.IndexOf('\0')>=0)throw new InvalidOperationException("INVALID_ARGUMENTS: NUL text cannot be entered safely");
-      if(action=="type_text" && method=="auto" && TextOption(args,"focusMode","preserve")=="preserve" && !Option(args,"activate",false) && BackgroundEdit(window,text,result)) {result["inputTargetHandle"]=window.ToInt64();result["inputTargetProcessId"]=owner;return result;}
+      if(action=="type_text" && method=="auto" && TextOption(args,"focusMode","preserve")=="preserve" && !Option(args,"activate",false) && BackgroundEdit(window,text,result)) {textInputDispatched=true;result["inputTargetHandle"]=window.ToInt64();result["inputTargetProcessId"]=owner;return result;}
       bool background=action=="type_text"?method=="background":TextOption(args,"dispatch","foreground")=="background";
       if(background) {
         if(!args.ContainsKey("windowRef") && !args.ContainsKey("windowTitle") && !args.ContainsKey("processId") && !args.ContainsKey("nativeWindowHandle"))throw new InvalidOperationException("BACKGROUND_TARGET_REQUIRED");
         string characters=action=="type_text"?text:Convert.ToString(((IList)args["keys"])[0]);
         IntPtr recipient=TextFocus(window);if(recipient==IntPtr.Zero)recipient=window;AssertWritableText(recipient);
-        foreach(char character in characters) {CheckWindowReference(window);if(!IsWindow(window) || WindowOwner(window)!=owner || WindowOwner(recipient)!=owner)throw new InvalidOperationException("TARGET_IDENTITY_CHANGED");BeginWindowDispatch();if(!ControlPost(recipient,0x102,new IntPtr(character),new IntPtr(1)))throw new InvalidOperationException("TEXT_DISPATCH_UNCONFIRMED: some WM_CHAR messages may have been delivered; never replay");}
+        foreach(char character in characters) {CheckWindowReference(window);if(!IsWindow(window) || WindowOwner(window)!=owner || WindowOwner(recipient)!=owner)throw new InvalidOperationException("TARGET_IDENTITY_CHANGED");BeginWindowDispatch();if(!ControlPost(recipient,0x102,new IntPtr(character),new IntPtr(1)))throw new InvalidOperationException("TEXT_DISPATCH_UNCONFIRMED: some WM_CHAR messages may have been delivered; never replay");textInputDispatched=true;}
         result["method"]="postmessage-wmchar";result["verification"]="unconfirmed";result["verified"]=false;result["inputTargetHandle"]=window.ToInt64();result["inputTargetProcessId"]=owner;return result;
       }
       if(TextOption(args,"_cancelEvent","").Length==0)throw new InvalidOperationException("WCU_NEEDS_INPUT: physical text/key input requires independent stopping");
@@ -192,19 +220,20 @@ partial class WindowsBridge {
       IntPtr expectedFocus=main!=null?ConfirmTextFocus(main,cancel,listener,window,owner,interaction):TextFocus(window,false);if(main!=null){result["focusConfirmed"]=true;result["inputFocusHandle"]=expectedFocus.ToInt64();}if(action=="type_text")AssertWritableText(expectedFocus);
       TextCheck(cancel,listener,window,owner,expectedFocus,action=="type_text",interaction);
       if(action=="type_text")RememberTextFocus(window,expectedFocus);
-      if(action=="keypress") {Chord((IEnumerable)args["keys"],cancel,listener,window,owner,held,interaction);result["method"]="sendinput-keychord";}
+      if(action=="keypress") {Chord((IEnumerable)args["keys"],cancel,listener,window,owner,held,interaction,holdMs,timing);result["method"]="sendinput-keychord";}
       else if(method=="sendinput") {
-        // Modern Notepad also corrupts seeded/appended text with a 10 ms gap.
-        // Keep complete pairs paced and cancellable; dispatch is still not verification.
+        // Preserve complete UTF-16 pairs and newline/tab handling at the selected pace.
+        // Dispatch is still not application verification.
         for(int index=0;index<text.Length;index++) {
           char character=text[index];
           if(character=='\r' && index+1<text.Length && text[index+1]=='\n')index++;
-          TextCheck(cancel,listener,window,owner,expectedFocus,true,interaction);
+          timing.Check();TextCheck(cancel,listener,window,owner,expectedFocus,true,interaction);
           HeldKey key=character=='\r' || character=='\n'?new HeldKey{Key=13}:character=='\t'?new HeldKey{Key=9}:new HeldKey{Scan=character,Flags=4};
           Down(held,key);Up(held,key);
-          if(cancel.WaitOne(UnicodeInputDelayMs))throw new InvalidOperationException("COMPUTER_USE_STOPPED");
+          result["inputUnitsDispatched"]=Convert.ToInt32(result["inputUnitsDispatched"])+1;
+          timing.Wait(inputDelayMs,cancel,delegate {TextCheck(cancel,listener,window,owner,expectedFocus,true,interaction);});
         }
-        result["method"]="sendinput-unicode";result["inputDelayMs"]=UnicodeInputDelayMs;
+        result["method"]="sendinput-unicode";
       }else {
         // All UIA focus/provider calls finish BEFORE clipboard replacement.
         ProcessStartInfo info=new ProcessStartInfo{FileName=TextOption(args,"_clipboardExecutable",""),UseShellExecute=false,CreateNoWindow=true,RedirectStandardInput=true,RedirectStandardOutput=true,RedirectStandardError=true,StandardOutputEncoding=Encoding.UTF8,StandardErrorEncoding=Encoding.UTF8};
@@ -239,6 +268,7 @@ partial class WindowsBridge {
       }
       if(cancel!=null)cancel.Dispose();if(listener!=null)listener.Dispose();
       result["cleanupConfirmed"]=cleanup;
+      if(action=="keypress" || action=="type_text"){result["inputDispatched"]=textInputDispatched;result["interrupted"]=!Convert.ToBoolean(result["ok"]); }
       // No potentially blocked UIA verification is permitted before clipboard cleanup.
       if(cleanup)RestoreControlState(result,before,pointer,window,popups,Option(args,"activate",false),interaction);
       else {result["pointer"]="left: cleanup unconfirmed";result["foreground"]="left: cleanup unconfirmed";}

package/dist/browser-actions.d.ts

@@ -17,5 +17,6 @@ export declare const browserActionTools: {
         additionalProperties: boolean;
     };
 }[];
+export declare function browserActionRefusal(action: string, args: Record<string, unknown>): string | undefined;
 export declare function normalizeBrowserAction(action: string, args: Record<string, unknown>): Record<string, unknown> | undefined;
 export {};

package/dist/browser-actions.js

@@ -1,3 +1,4 @@
+import { timingMilliseconds } from "./input-timing.js";
 // Shared reference-compatible tool schemas; browser execution stays in browser.ts.
 const target = {
     windowRef: { type: "string", minLength: 1 },
@@ -29,7 +30,16 @@ const dispatch = {
 };
 const definitions = {
     click: {
-        properties: { ...target, ...view, ...element, ...point, button, dispatch },
+        properties: {
+            ...target,
+            ...view,
+            ...element,
+            ...point,
+            button,
+            dispatch,
+            holdMs: timingMilliseconds,
+            timeoutMs: timingMilliseconds,
+        },
     },
     double_click: {
         properties: { ...target, ...view, ...element, ...point, button, dispatch },
@@ -63,11 +73,15 @@ const definitions = {
                 default: "preserve",
             },
             restoreClipboard: { type: "boolean", default: true },
+            inputDelayMs: timingMilliseconds,
+            timeoutMs: timingMilliseconds,
         },
     },
     keypress: {
         required: ["keys"],
         properties: {
+            holdMs: timingMilliseconds,
+            timeoutMs: timingMilliseconds,
             ...target,
             ...tab,
             keys: {
@@ -153,7 +167,26 @@ export const browserActionTools = Object.entries(definitions).map(([action, defi
     action,
     parameters: { type: "object", additionalProperties: false, ...definition },
 }));
+export function browserActionRefusal(action, args) {
+    if (action === "click" &&
+        (args.holdMs !== undefined || args.timeoutMs !== undefined))
+        return "TIMING_UNSUPPORTED: click timing requires native foreground dispatch";
+    if (action === "keypress" &&
+        (args.holdMs !== undefined ||
+            args.timeoutMs !== undefined ||
+            (Array.isArray(args.keys) &&
+                args.keys.length === 1 &&
+                /^(ctrl|control|alt|option|shift)$/i.test(String(args.keys[0]).trim()))))
+        return "TIMING_UNSUPPORTED: keypress timing and standalone modifiers require native foreground dispatch";
+    if (action === "type_text" &&
+        (args.inputDelayMs !== undefined || args.timeoutMs !== undefined))
+        return "TIMING_UNSUPPORTED: text timing requires explicit native sendinput";
+    return undefined;
+}
 export function normalizeBrowserAction(action, args) {
+    const refusal = browserActionRefusal(action, args);
+    if (refusal)
+        throw new Error(refusal);
     const definition = definitions[action];
     if (!definition)
         return undefined;

package/dist/client.d.ts

@@ -27,6 +27,7 @@ export declare class WorkerClient {
     private shutdownChanged;
     private readonly lifetime;
     private queue;
+    private readonly deadlineCleanup;
     constructor(options: WorkerClientOptions);
     private start;
     private fail;

package/dist/client.js

@@ -1,7 +1,11 @@
 import { spawn } from "node:child_process";
-function abortable(operation, signal) {
+import { executionDeadline, pressTiming, textTiming } from "./input-timing.js";
+function abortable(operation, signal, retain) {
     return new Promise((resolve, reject) => {
-        const abort = () => reject(signal.reason);
+        const abort = () => {
+            if (!retain?.())
+                reject(signal.reason);
+        };
         signal.addEventListener("abort", abort, { once: true });
         if (signal.aborted)
             abort();
@@ -24,6 +28,7 @@ export class WorkerClient {
     shutdownChanged;
     lifetime = new AbortController();
     queue = Promise.resolve();
+    deadlineCleanup = new Set();
     constructor(options) {
         this.options = options;
     }
@@ -180,31 +185,63 @@ export class WorkerClient {
             return this.executeNow(action, args, callSignal, operationId);
         });
         this.queue = result.catch(() => undefined);
-        return abortable(result, callSignal);
+        return abortable(result, callSignal, () => this.deadlineCleanup.has(callSignal));
     }
     async executeNow(action, args, signal, operationId) {
+        let inputPolicy;
+        if (action === "keypress" || action === "click" || action === "type_text") {
+            try {
+                inputPolicy = (action === "type_text" ? textTiming : pressTiming)(args, this.options.timeoutMs ?? 30_000);
+            }
+            catch (error) {
+                return {
+                    ok: false,
+                    action,
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        }
         const child = await this.start(signal);
         if (this.disposed)
             throw new Error("WORKER_DISPOSED: session has closed");
         signal?.throwIfAborted();
         const id = ++this.nextId;
         return new Promise((resolve, reject) => {
-            const timer = setTimeout(() => {
+            let expired = false;
+            let cleanupTimer;
+            const timeoutError = () => new Error(`WORKER_TIMEOUT: ${action} exceeded the execution deadline; input was not replayed`);
+            const timer = executionDeadline(inputPolicy?.timeoutMs ??
+                Math.max(1, this.options.timeoutMs ?? 30_000, action === "wait" &&
+                    Number.isSafeInteger(args.milliseconds ?? 500) &&
+                    Number(args.milliseconds ?? 500) >= 1 &&
+                    Number(args.milliseconds ?? 500) <= 30000
+                    ? Number(args.milliseconds ?? 500) + 2000
+                    : 0, action === "wait_for" &&
+                    Number.isSafeInteger(args.timeoutMs ?? 5000) &&
+                    Number(args.timeoutMs ?? 5000) >= 100 &&
+                    Number(args.timeoutMs ?? 5000) <= 60000
+                    ? Number(args.timeoutMs ?? 5000) + 10000
+                    : 0), () => {
+                if (inputPolicy) {
+                    expired = true;
+                    if (signal)
+                        this.deadlineCleanup.add(signal);
+                    // Keep the request and its owner until cooperative release is acknowledged.
+                    child.stdin.write(`${JSON.stringify({ cancel: id })}\n`);
+                    cleanupTimer = setTimeout(() => {
+                        this.fail(child, timeoutError());
+                        if (!this.inputActive && this.options.canTerminate?.() !== false)
+                            child.kill();
+                    }, 5000);
+                    return;
+                }
                 this.fail(child, new Error(`WORKER_TIMEOUT: ${action} exceeded the execution deadline; input was not replayed`));
                 if (!this.inputActive && this.options.canTerminate?.() !== false)
                     child.kill();
-            }, Math.max(this.options.timeoutMs ?? 30_000, action === "wait" &&
-                Number.isSafeInteger(args.milliseconds ?? 500) &&
-                Number(args.milliseconds ?? 500) >= 1 &&
-                Number(args.milliseconds ?? 500) <= 30000
-                ? Number(args.milliseconds ?? 500) + 2000
-                : 0, action === "wait_for" &&
-                Number.isSafeInteger(args.timeoutMs ?? 5000) &&
-                Number(args.timeoutMs ?? 5000) >= 100 &&
-                Number(args.timeoutMs ?? 5000) <= 60000
-                ? Number(args.timeoutMs ?? 5000) + 10000
-                : 0));
+            });
             const abort = () => {
+                if (expired)
+                    return;
                 const pending = this.pending.get(id);
                 if (!pending)
                     return;
@@ -216,10 +253,26 @@ export class WorkerClient {
             };
             this.pending.set(id, {
                 operationId,
-                resolve,
+                resolve: (result) => resolve(expired
+                    ? {
+                        ...result,
+                        ok: false,
+                        error: result.cleanupConfirmed === false ||
+                            /CLEANUP_UNCONFIRMED/.test(String(result.error))
+                            ? (result.error ??
+                                "INPUT_CLEANUP_UNCONFIRMED: deadline expired before release was confirmed")
+                            : timeoutError().message,
+                        executionDeadlineExpired: true,
+                        interrupted: true,
+                        timing: inputPolicy,
+                    }
+                    : result),
                 reject,
                 cleanup: () => {
-                    clearTimeout(timer);
+                    timer();
+                    if (signal)
+                        this.deadlineCleanup.delete(signal);
+                    clearTimeout(cleanupTimer);
                     signal?.removeEventListener("abort", abort);
                 },
             });

package/dist/extension.js

@@ -18,13 +18,13 @@ const actionDescriptions = {
     accessibility_tree: "Read a bounded UIA tree or browser page outline with element IDs. Partial trees do not establish absence.",
     find: "Find UIA or page controls; sparse UIA searches may add OCR. OCR hits use physical screen coordinates, not element IDs.",
     element_info: "Inspect a fresh UIA or page element ID, or a physical screen point.",
-    click: "Click a control or physical screen point; background delivery is unverified. Browser page IDs act inside the page. Observe effects before retrying.",
+    click: "Click a control or physical screen point. Native foreground holdMs presses and releases left/right/middle in this call; timeoutMs: 0 disables only its execution deadline. Explicit timing refuses browser/background and activate: false routes. Omitted timing preserves defaults; background delivery is unverified. Observe effects before retrying.",
     double_click: "Double-click a control or physical screen point; background delivery is unverified. Browser page IDs act inside the page. Observe effects before retrying.",
     move: "Move the pointer to a control or physical screen point; browser page IDs act inside the page. Observe hover effects.",
     drag: "Drag a path of physical screen coordinates using guarded foreground input. Observe the drop and cleanup before retrying.",
     scroll: "Scroll a control or physical screen point; native element scrolling tries background first. Positive deltaY scrolls down. Browser tabs scroll inside the page.",
-    type_text: "Type into the focused control. Native auto tries a background edit then clipboard paste; clipboard restoration is requested by default. Background WM_CHAR is unverified.",
-    keypress: 'Send a key or chord, for example ["ctrl","a"]. Windows keys are blocked; native background dispatch supports one printable character only.',
+    type_text: "Type into the focused control. Native auto tries a background edit then clipboard paste; clipboard restoration is requested by default. Explicit native sendinput supports inputDelayMs (default 50; zero adds no delay) and timeoutMs (zero disables execution deadline). Other routes refuse timing fields. Partial input is never replayed; observe text to verify it. Background WM_CHAR is unverified.",
+    keypress: "Send a key/chord or standalone Ctrl, Alt or Shift. Native foreground holdMs completes and releases in this call; timeoutMs: 0 disables only its execution deadline. Omitted timing preserves defaults. Timing and modifier taps refuse browser/background routes; Windows keys remain blocked. Observe effects before retrying.",
     focus: "Focus a fresh UIA or browser page element; observe the intended focus before typing.",
     invoke: "Invoke, toggle or select a control, or request expand, collapse or scroll-into-view. Optional native click fallback is guarded; verify its effect.",
     set_value: 'Set a native or browser field value with guarded fallback. Browser "new-tab" opens a dedicated automation tab only when that workspace is explicitly requested; "<tab>:address" navigates it.',

package/dist/input-timing.d.ts

@@ -0,0 +1,24 @@
+/** Shared per-call timing policy; durations are milliseconds, zero disables only a deadline. */
+export declare const timingMilliseconds: {
+    type: string;
+    minimum: number;
+    maximum: number;
+};
+export declare function milliseconds(value: unknown, name: string): number;
+export declare function inputTiming(args: Record<string, unknown>, requestedDurationMs: number, ordinaryTimeoutMs: number): {
+    timeoutMs: number;
+    deadlinePolicy: "disabled" | "explicit" | "derived" | "default";
+};
+export declare function pressTiming(args: Record<string, unknown>, ordinaryTimeoutMs: number): {
+    timeoutMs: number;
+    deadlinePolicy: "disabled" | "explicit" | "derived" | "default";
+    holdMs: number;
+};
+/** Count dispatched UTF-16 units, treating CRLF as the existing single Enter. */
+export declare function textTiming(args: Record<string, unknown>, ordinaryTimeoutMs: number): {
+    timeoutMs: number;
+    deadlinePolicy: "disabled" | "explicit" | "derived" | "default";
+    inputDelayMs: number;
+};
+/** Node timers accept signed 32-bit intervals; chain monotonic chunks without wrapping. */
+export declare function executionDeadline(milliseconds: number, expired: () => void): () => void;

package/dist/input-timing.js

@@ -0,0 +1,70 @@
+/** Shared per-call timing policy; durations are milliseconds, zero disables only a deadline. */
+export const timingMilliseconds = {
+    type: "integer",
+    minimum: 0,
+    maximum: Number.MAX_SAFE_INTEGER,
+};
+export function milliseconds(value, name) {
+    if (!Number.isSafeInteger(value) || Number(value) < 0)
+        throw new Error(`INVALID_ARGUMENTS: ${name} must be non-negative safe whole milliseconds`);
+    return Number(value);
+}
+export function inputTiming(args, requestedDurationMs, ordinaryTimeoutMs) {
+    milliseconds(requestedDurationMs, "requested duration");
+    if (args.timeoutMs !== undefined) {
+        const timeoutMs = milliseconds(args.timeoutMs, "timeoutMs");
+        return {
+            timeoutMs,
+            deadlinePolicy: timeoutMs === 0 ? "disabled" : "explicit",
+        };
+    }
+    const timeoutMs = ordinaryTimeoutMs + requestedDurationMs;
+    if (!Number.isSafeInteger(timeoutMs))
+        throw new Error("INVALID_ARGUMENTS: derived execution duration is not representable");
+    return {
+        timeoutMs,
+        deadlinePolicy: args.holdMs !== undefined || args.inputDelayMs !== undefined
+            ? "derived"
+            : "default",
+    };
+}
+export function pressTiming(args, ordinaryTimeoutMs) {
+    const holdMs = args.holdMs === undefined ? 0 : milliseconds(args.holdMs, "holdMs");
+    return { holdMs, ...inputTiming(args, holdMs, ordinaryTimeoutMs) };
+}
+/** Count dispatched UTF-16 units, treating CRLF as the existing single Enter. */
+export function textTiming(args, ordinaryTimeoutMs) {
+    const inputDelayMs = args.inputDelayMs === undefined
+        ? 50
+        : milliseconds(args.inputDelayMs, "inputDelayMs");
+    if (args.inputDelayMs !== undefined || args.timeoutMs !== undefined) {
+        if (args.method !== "sendinput" || args.browserTab !== undefined)
+            throw new Error("TIMING_UNSUPPORTED: text timing requires explicit native sendinput");
+    }
+    const units = typeof args.text === "string" ? args.text.replace(/\r\n/g, "\n").length : 0;
+    const requestedDuration = args.inputDelayMs === undefined ? 0 : units * inputDelayMs;
+    if (!Number.isSafeInteger(requestedDuration))
+        throw new Error("INVALID_ARGUMENTS: requested pacing duration is not representable");
+    return {
+        inputDelayMs,
+        ...inputTiming(args, requestedDuration, ordinaryTimeoutMs),
+    };
+}
+/** Node timers accept signed 32-bit intervals; chain monotonic chunks without wrapping. */
+export function executionDeadline(milliseconds, expired) {
+    let timer;
+    let remaining = milliseconds;
+    let previous = performance.now();
+    const arm = () => {
+        const now = performance.now();
+        remaining -= now - previous;
+        previous = now;
+        if (remaining <= 0)
+            expired();
+        else
+            timer = setTimeout(arm, Math.min(remaining, 2_147_483_647));
+    };
+    if (milliseconds !== 0)
+        arm();
+    return () => clearTimeout(timer);
+}

package/dist/native.js

@@ -127,6 +127,7 @@ export const nativeDesktop = new NativeDesktopClient({
             "pointer.cs",
             "browser-indicators.cs",
             "text.cs",
+            "input-timing.cs",
         ];
         const framework = join(process.env.WINDIR ?? "", "Microsoft.NET", "Framework64", "v4.0.30319");
         return compileNative(names, [