@ycheung5/pi-computer-use 0.0.0-stage → 0.1.1

package/assets/capture.cs

@@ -0,0 +1,215 @@
+using System;
+using System.Collections.Generic;
+using System.Drawing;
+using System.Drawing.Drawing2D;
+using System.Drawing.Imaging;
+using System.IO;
+using System.Runtime.InteropServices;
+using System.Windows.Forms;
+
+partial class WindowsBridge {
+  [DllImport("user32.dll")] static extern bool PrintWindow(IntPtr window, IntPtr dc, uint flags);
+  [DllImport("dwmapi.dll")] static extern int DwmGetWindowAttribute(IntPtr window, int attribute, out Rect bounds, int bytes);
+
+  static IntPtr ResolveCaptureWindow(Dictionary<string, object> args) {
+    WindowReference bound=ResolveWindowReference(args);
+    object value;
+    long requested = bound!=null?bound.Window.ToInt64():args.TryGetValue("nativeWindowHandle", out value) ? Convert.ToInt64(value) : 0;
+    uint process = args.TryGetValue("processId", out value) ? Convert.ToUInt32(value) : 0;
+    string title = args.TryGetValue("windowTitle", out value) ? Convert.ToString(value) : null;
+    if (requested != 0) {
+      IntPtr handle = new IntPtr(requested);
+      uint actual;
+      GetWindowThreadProcessId(handle, out actual);
+      if (!IsWindow(handle) || actual == 0 || (process != 0 && actual != process)) throw new InvalidOperationException("WINDOW_IDENTITY_CHANGED: refresh window observations");
+      if (title != null) {
+        System.Text.StringBuilder text = new System.Text.StringBuilder(2048);
+        GetWindowText(handle, text, text.Capacity);
+        if (text.ToString().IndexOf(title, StringComparison.OrdinalIgnoreCase) < 0) throw new InvalidOperationException("WINDOW_TARGET_MISMATCH");
+      }
+      return handle;
+    }
+    if (process == 0 && title == null) {
+      IntPtr foreground = GetForegroundWindow();
+      if (foreground == IntPtr.Zero) throw new InvalidOperationException("WINDOW_NOT_FOUND: no foreground window");
+      return foreground;
+    }
+    List<IntPtr> matches = new List<IntPtr>();
+    EnumWindows(delegate(IntPtr handle, IntPtr unused) {
+      uint actual;
+      GetWindowThreadProcessId(handle, out actual);
+      if (!IsWindowVisible(handle) || (process != 0 && actual != process)) return true;
+      System.Text.StringBuilder text = new System.Text.StringBuilder(2048);
+      GetWindowText(handle, text, text.Capacity);
+      if (title == null || text.ToString().IndexOf(title, StringComparison.OrdinalIgnoreCase) >= 0) matches.Add(handle);
+      return true;
+    }, IntPtr.Zero);
+    if (matches.Count == 0) throw new InvalidOperationException("WINDOW_NOT_FOUND");
+    if (matches.Count > 1) throw new InvalidOperationException("WINDOW_TARGET_AMBIGUOUS: use nativeWindowHandle and processId");
+    return matches[0];
+  }
+
+  static Rectangle WindowCaptureBounds(IntPtr window) {
+    Rect bounds;
+    if (DwmGetWindowAttribute(window, 9, out bounds, Marshal.SizeOf(typeof(Rect))) != 0 || bounds.Right <= bounds.Left || bounds.Bottom <= bounds.Top) {
+      if (!GetWindowRect(window, out bounds)) throw new InvalidOperationException("WINDOW_BOUNDS_UNAVAILABLE");
+    }
+    return Rectangle.FromLTRB(bounds.Left, bounds.Top, bounds.Right, bounds.Bottom);
+  }
+
+  static bool ClearCaptureRegion(IntPtr window, Rectangle bounds, Rectangle desktop) {
+    if (GetForegroundWindow() != window || !IsWindowVisible(window) || IsIconic(window) || !desktop.Contains(bounds)) return false;
+    bool found = false, clear = true;
+    EnumWindows(delegate(IntPtr other, IntPtr unused) {
+      if (other == window) { found = true; return false; }
+      if (!IsWindowVisible(other) || IsIconic(other)) return true;
+      Rect box;
+      if (!GetWindowRect(other, out box)) { clear = false; return false; }
+      if (Rectangle.FromLTRB(box.Left, box.Top, box.Right, box.Bottom).IntersectsWith(bounds)) { clear = false; return false; }
+      return true;
+    }, IntPtr.Zero);
+    return found && clear;
+  }
+
+  static Bitmap CopyCaptureRegion(Rectangle bounds) {
+    if (bounds.Width <= 0 || bounds.Height <= 0 || (long)bounds.Width * bounds.Height > 40000000) throw new InvalidOperationException("CAPTURE_BOUNDS_UNAVAILABLE: region is empty or exceeds 40 million pixels");
+    Bitmap image = new Bitmap(bounds.Width, bounds.Height, PixelFormat.Format32bppArgb);
+    try {
+      using (Graphics graphics = Graphics.FromImage(image)) graphics.CopyFromScreen(bounds.Location, Point.Empty, bounds.Size);
+      return image;
+    } catch { image.Dispose(); throw; }
+  }
+
+  static bool CaptureIsBlank(Bitmap image) {
+    for (int y = 0; y < image.Height; y += Math.Max(1, image.Height / 32)) {
+      for (int x = 0; x < image.Width; x += Math.Max(1, image.Width / 32)) {
+        Color color = image.GetPixel(x, y);
+        if (color.R > 10 || color.G > 10 || color.B > 10) return false;
+      }
+    }
+    return true;
+  }
+
+  static Bitmap PrintCapture(IntPtr window, Rectangle wanted) {
+    Rect windowBox;
+    if (!GetWindowRect(window, out windowBox)) return null;
+    Rectangle full = Rectangle.FromLTRB(windowBox.Left, windowBox.Top, windowBox.Right, windowBox.Bottom);
+    if (full.Width <= 0 || full.Height <= 0 || (long)full.Width * full.Height > 40000000 || !full.Contains(wanted)) return null;
+    using (Bitmap entire = new Bitmap(full.Width, full.Height, PixelFormat.Format32bppArgb)) {
+      bool rendered;
+      using (Graphics graphics = Graphics.FromImage(entire)) {
+        IntPtr dc = graphics.GetHdc();
+        try { rendered = PrintWindow(window, dc, 2); }
+        finally { graphics.ReleaseHdc(dc); }
+      }
+      if (!rendered) return null;
+      Bitmap cropped = entire.Clone(new Rectangle(wanted.X - full.X, wanted.Y - full.Y, wanted.Width, wanted.Height), PixelFormat.Format32bppArgb);
+      if (CaptureIsBlank(cropped)) { cropped.Dispose(); return null; }
+      return cropped;
+    }
+  }
+
+  static object CaptureScreenshot(Dictionary<string, object> args) {
+    if(args.ContainsKey("windowRef") && TextOption(args,"scope","active_window")=="desktop")throw new InvalidOperationException("WINDOW_REFERENCE_CONFLICT: desktop capture cannot use a window reference");
+    bool desktopScope = Convert.ToString(args["scope"]) == "desktop";
+    bool windowOnly = args.ContainsKey("windowOnly") && Convert.ToBoolean(args["windowOnly"]);
+    if(windowOnly && desktopScope)throw new InvalidOperationException("INVALID_ARGUMENTS: windowOnly requires window scope");
+    int maximum = Convert.ToInt32(args["maxWidth"]);
+    Rectangle desktop = SystemInformation.VirtualScreen;
+    Rectangle bounds = desktop;
+    Bitmap image = null;
+    string method = "screen";
+    string pixelFailure = null;
+    bool occluded = false, failed = false;
+    List<string> warnings = new List<string>();
+    IntPtr target = IntPtr.Zero;
+    uint owner = 0;
+    var referenceMetadata=new Dictionary<string,object>();
+    try {
+    if (!desktopScope) {
+      target = ResolveCaptureWindow(args);
+      WindowReference binding=ObserveWindowReference(target,referenceMetadata);if(binding!=null){currentReference=binding;referenceMetadata["windowRef"]=binding.Id;}
+      GetWindowThreadProcessId(target, out owner);CheckWindowReference(target);
+      object requestedActivation;
+      if (args.TryGetValue("activate", out requestedActivation) && Convert.ToBoolean(requestedActivation)){BeginWindowDispatch();if(!SetForegroundWindow(target))warnings.Add("WINDOW_ACTIVATION_REFUSED: Windows did not bring the target to foreground");}
+      bounds = WindowCaptureBounds(target);
+      if (!IsIconic(target) && IsWindowVisible(target) && bounds.Width > 0 && bounds.Height > 0) {
+        if (!windowOnly && ClearCaptureRegion(target, bounds, desktop)) {
+          Bitmap candidate = null;
+          try {
+            candidate = CopyCaptureRegion(bounds);
+            if (WindowCaptureBounds(target) == bounds && ClearCaptureRegion(target, bounds, desktop)) { image = candidate; candidate = null; method = "screen-region"; }
+          } catch (Exception error) { warnings.Add("SCREEN_REGION_RETRY: " + error.Message); }
+          finally { if (candidate != null) candidate.Dispose(); }
+        }
+        if (image == null) { image = PrintCapture(target, bounds); method = "printwindow"; }
+        if (image == null) {
+          warnings.Add("PRINTWINDOW_FAILED_OR_BLANK");
+          Rectangle visible = Rectangle.Intersect(bounds, desktop);
+          if (!windowOnly && visible.Width > 0 && visible.Height > 0) {
+            Rectangle windowBounds = bounds;
+            bounds = visible; method = "screen-region"; occluded = true;
+            try { image = CopyCaptureRegion(bounds); }
+            catch (System.ComponentModel.Win32Exception error) {
+              // Only this failed pixel stage may hand off without a native image.
+              if (!IsWindowVisible(target) || IsIconic(target) || WindowCaptureBounds(target) != windowBounds) throw new InvalidOperationException("WINDOW_MOVED_DURING_CAPTURE: observe the target again");
+              pixelFailure = "SCREEN_REGION_CAPTURE_FAILED: " + error.Message;
+            }
+          }
+        }
+      }
+      if (image == null && pixelFailure == null) {
+        if(windowOnly)pixelFailure="WINDOW_CAPTURE_UNAVAILABLE: target is hidden, minimized or PrintWindow failed/blank; screen fallback refused";
+        else {
+          failed = true; bounds = desktop; method = "screen";
+          warnings.Add("WINDOW_CAPTURE_FAILED: returning desktop pixels instead of the unavailable target surface");
+        }
+      }
+    }
+      if (image == null && pixelFailure == null) image = CopyCaptureRegion(bounds);
+      if (target != IntPtr.Zero) {
+        CheckWindowReference(target);
+        uint ownerAfter;
+        GetWindowThreadProcessId(target, out ownerAfter);
+        if (!IsWindow(target) || owner != ownerAfter) throw new InvalidOperationException("WINDOW_IDENTITY_CHANGED_DURING_CAPTURE");
+        if (!failed && WindowCaptureBounds(target) != bounds && !occluded) throw new InvalidOperationException("WINDOW_MOVED_DURING_CAPTURE: observe the target again");
+      }
+      if (pixelFailure != null) {
+        Dictionary<string, object> unavailable = Result(false, "screenshot");
+        unavailable["error"] = windowOnly?"WINDOW_CAPTURE_UNAVAILABLE":"SCREEN_REGION_CAPTURE_FAILED";
+        unavailable["nativeCaptureError"] = pixelFailure;
+        unavailable["captureWarnings"] = warnings;
+        foreach(var pair in referenceMetadata)unavailable[pair.Key]=pair.Value;
+        if(!windowOnly || (IsWindowVisible(target) && !IsIconic(target)))unavailable["wgcTarget"] = new Dictionary<string, object> { { "nativeWindowHandle", target.ToInt64() }, { "processId", owner }, { "_windowMarker", WindowReferenceDescriptor(target) } };
+        return unavailable;
+      }
+      if (maximum > 0 && image.Width > maximum) {
+        int height = Math.Max(1, (int)Math.Round((double)image.Height * maximum / image.Width));
+        Bitmap resized = new Bitmap(maximum, height, PixelFormat.Format32bppArgb);
+        using (Graphics graphics = Graphics.FromImage(resized)) {
+          graphics.InterpolationMode = InterpolationMode.HighQualityBicubic;
+          graphics.DrawImage(image, new Rectangle(0, 0, resized.Width, resized.Height));
+        }
+        image.Dispose(); image = resized;
+      }
+      byte[] png;
+      using (MemoryStream bytes = new MemoryStream()) { image.Save(bytes, ImageFormat.Png); png = bytes.ToArray(); }
+      Dictionary<string, object> metadata = new Dictionary<string, object> {
+        { "mimeType", "image/png" }, { "base64", Convert.ToBase64String(png) }, { "bytes", png.Length },
+        { "width", image.Width }, { "height", image.Height }, { "method", method },
+        { "bounds", new Dictionary<string, object> { { "x", bounds.X }, { "y", bounds.Y }, { "width", bounds.Width }, { "height", bounds.Height } } },
+        { "origin", new Dictionary<string, object> { { "x", bounds.X }, { "y", bounds.Y } } },
+        { "imageScale", (double)image.Width / bounds.Width },
+        { "imageScaleY", (double)image.Height / bounds.Height },
+        { "occludedPossible", occluded }, { "windowCaptureFailed", failed }, { "captureWarnings", warnings }
+      };
+      Dictionary<string, object> result = Result(true, "screenshot");
+      metadata["source"]=desktopScope?"desktop":"window";
+      foreach(var pair in referenceMetadata){result[pair.Key]=pair.Value;metadata[pair.Key]=pair.Value;}
+      result["screenshot"] = metadata;
+      if(target!=IntPtr.Zero && !failed){RememberPointerOrigin(target);RememberPointerTitle(args,target);}
+      if (target != IntPtr.Zero && !failed && occluded) result["wgcTarget"] = new Dictionary<string, object> { { "nativeWindowHandle", target.ToInt64() }, { "processId", owner }, {"_windowMarker",WindowReferenceDescriptor(target)} };
+      return result;
+    } finally { if (image != null) image.Dispose(); }
+  }
+}

package/assets/clipboard.cs

@@ -0,0 +1,197 @@
+using System;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.Runtime.InteropServices;
+using System.Runtime.InteropServices.ComTypes;
+using System.Text;
+using System.Threading;
+using System.Web.Script.Serialization;
+
+// Isolated STA process. Snapshot is a separate protocol phase: it can be killed
+// on a delayed-render/provider timeout before any clipboard mutation is allowed.
+class ClipboardBridge {
+  [DllImport("user32.dll",CharSet=CharSet.Unicode)] static extern IntPtr CreateWindowEx(uint extended,string name,string title,uint style,int x,int y,int width,int height,IntPtr parent,IntPtr menu,IntPtr instance,IntPtr parameter);
+  [DllImport("user32.dll")] static extern bool DestroyWindow(IntPtr window);
+  [DllImport("user32.dll",CharSet=CharSet.Unicode)] static extern int GetClipboardFormatName(uint format,StringBuilder name,int count);
+  [StructLayout(LayoutKind.Sequential)] struct Message {public IntPtr Hwnd;public uint Id;public UIntPtr W;public IntPtr L;public uint Time;public int X,Y;public uint Private;}
+  [DllImport("user32.dll")] static extern bool PeekMessage(out Message message,IntPtr window,uint first,uint last,uint remove);
+  [DllImport("user32.dll")] static extern bool TranslateMessage(ref Message message);
+  [DllImport("user32.dll")] static extern IntPtr DispatchMessage(ref Message message);
+  static void Pump() {Message message;while(PeekMessage(out message,IntPtr.Zero,0,0,1)){TranslateMessage(ref message);DispatchMessage(ref message);}}
+  static IntPtr clipboardOwner;
+  [DllImport("user32.dll",SetLastError=true)] static extern bool OpenClipboard(IntPtr owner);
+  [DllImport("user32.dll")] static extern bool CloseClipboard();
+  [DllImport("user32.dll",SetLastError=true)] static extern bool EmptyClipboard();
+  [DllImport("user32.dll",SetLastError=true)] static extern uint EnumClipboardFormats(uint format);
+  [DllImport("user32.dll",SetLastError=true)] static extern IntPtr GetClipboardData(uint format);
+  [DllImport("user32.dll",SetLastError=true)] static extern IntPtr SetClipboardData(uint format,IntPtr data);
+  [DllImport("user32.dll",CharSet=CharSet.Unicode)] static extern uint RegisterClipboardFormat(string name);
+  [DllImport("user32.dll")] static extern uint GetClipboardSequenceNumber();
+  [DllImport("user32.dll")] static extern IntPtr GetClipboardOwner();
+  [DllImport("ole32.dll")] static extern int OleInitialize(IntPtr reserved);
+  [DllImport("ole32.dll")] static extern void OleUninitialize();
+  [DllImport("ole32.dll")] static extern int OleGetClipboard(out IDataObject data);
+  [DllImport("ole32.dll")] static extern IntPtr OleDuplicateData(IntPtr data,ushort format,uint flags);
+  [DllImport("kernel32.dll",SetLastError=true)] static extern IntPtr GlobalAlloc(uint flags,UIntPtr size);
+  [DllImport("kernel32.dll")] static extern IntPtr GlobalLock(IntPtr data);
+  [DllImport("kernel32.dll")] static extern UIntPtr GlobalSize(IntPtr data);
+  [DllImport("kernel32.dll")] static extern bool GlobalUnlock(IntPtr data);
+  [DllImport("kernel32.dll")] static extern IntPtr GlobalFree(IntPtr data);
+  [DllImport("kernel32.dll")] static extern void SetLastError(uint code);
+  [DllImport("gdi32.dll")] static extern bool DeleteObject(IntPtr data);
+  [DllImport("gdi32.dll",CharSet=CharSet.Unicode)] static extern IntPtr CopyEnhMetaFile(IntPtr data,string filename);
+  [DllImport("gdi32.dll")] static extern bool DeleteEnhMetaFile(IntPtr data);
+  [DllImport("gdi32.dll")] static extern bool DeleteMetaFile(IntPtr data);
+  [StructLayout(LayoutKind.Sequential)] struct MetaPicture {public int Mode,X,Y;public IntPtr Meta;}
+  sealed class Item {public uint Format;public IntPtr Data;}
+  static readonly List<Item> snapshot=new List<Item>();
+  static readonly object phaseGate=new object();static bool mayMutate;
+  static uint transactionFormat;static readonly byte[] transactionToken=Guid.NewGuid().ToByteArray();
+  static uint sequence;static bool changed;static bool replaced;static bool restoring;static int oleMetadataExcluded,oleFormatsValidated;static string restoreOutcome="unchanged";
+  static readonly JavaScriptSerializer json=new JavaScriptSerializer {MaxJsonLength=8*1024*1024};
+  static void Reply(string phase,bool ok,string error) {Console.WriteLine(json.Serialize(new Dictionary<string,object>{{"phase",phase},{"ok",ok},{"error",error},{"formats",snapshot.Count},{"restored",!changed},{"oleMetadataExcluded",oleMetadataExcluded},{"oleFormatsValidated",oleFormatsValidated},{"restoreOutcome",restoreOutcome}}));Console.Out.Flush();}
+  static void Open() {Stopwatch watch=Stopwatch.StartNew();while(!OpenClipboard(clipboardOwner)){if(watch.ElapsedMilliseconds>=500)throw new InvalidOperationException("CLIPBOARD_BUSY: could not acquire clipboard");Thread.Sleep(10);}}
+  static void Free(Item item) {
+    if(item.Data==IntPtr.Zero)return;
+    if(item.Format==2 || item.Format==9 || item.Format==0x82)DeleteObject(item.Data);
+    else if(item.Format==14 || item.Format==0x8E)DeleteEnhMetaFile(item.Data);
+    else {if(item.Format==3 || item.Format==0x83){IntPtr memory=GlobalLock(item.Data);if(memory!=IntPtr.Zero){MetaPicture picture=(MetaPicture)Marshal.PtrToStructure(memory,typeof(MetaPicture));DeleteMetaFile(picture.Meta);GlobalUnlock(item.Data);}}GlobalFree(item.Data);}
+    item.Data=IntPtr.Zero;
+  }
+  static IntPtr Duplicate(IntPtr data,uint format) {return format==14 || format==0x8E?CopyEnhMetaFile(data,null):OleDuplicateData(data,(ushort)(format==0x82?2:format==0x83?3:format),0);}
+  static string FormatName(uint format) {StringBuilder name=new StringBuilder(256);GetClipboardFormatName(format,name,name.Capacity);return name.ToString();}
+  static bool OleTransportFormat(uint format) {string name=FormatName(format);return name.Equals("DataObject",StringComparison.OrdinalIgnoreCase) || name.Equals("Ole Private Data",StringComparison.OrdinalIgnoreCase);}
+  static HashSet<uint> ValidateOleFormats() {
+    IDataObject data=null;IEnumFORMATETC iterator=null;HashSet<uint> formats=new HashSet<uint>();
+    try {
+      Marshal.ThrowExceptionForHR(OleGetClipboard(out data));
+      if(data==null)throw new InvalidOperationException("CLIPBOARD_SNAPSHOT_UNSUPPORTED: missing OLE object; unchanged");
+      iterator=data.EnumFormatEtc(DATADIR.DATADIR_GET);FORMATETC[] item=new FORMATETC[1];int[] fetched=new int[1];
+      for(int count=0;;count++) {
+        fetched[0]=0;int result=iterator.Next(1,item,fetched);if(result==1 && fetched[0]==0)break;
+        if(result!=0 || fetched[0]!=1 || count>=1000)throw new InvalidOperationException("CLIPBOARD_SNAPSHOT_UNSUPPORTED: incomplete OLE format enumeration; unchanged");
+        FORMATETC format=item[0];
+        try {
+          uint id=unchecked((ushort)format.cfFormat);
+          uint medium=id==2 || id==9 || id==0x82?16U:id==3 || id==0x83?32U:id==14 || id==0x8E?64U:1U;
+          if(format.lindex!=-1 || format.dwAspect!=DVASPECT.DVASPECT_CONTENT || format.ptd!=IntPtr.Zero || ((uint)format.tymed & medium)==0 || OleTransportFormat(id) || FormatName(id).Equals("FileContents",StringComparison.OrdinalIgnoreCase))
+            throw new InvalidOperationException("CLIPBOARD_SNAPSHOT_UNSUPPORTED: indexed, device-specific or unsupported OLE data; unchanged");
+          formats.Add(id);
+        }finally {if(format.ptd!=IntPtr.Zero)Marshal.FreeCoTaskMem(format.ptd);}
+      }
+      if(formats.Count==0)throw new InvalidOperationException("CLIPBOARD_SNAPSHOT_UNSUPPORTED: no preservable OLE formats; unchanged");
+      return formats;
+    }catch(COMException){throw new InvalidOperationException("CLIPBOARD_SNAPSHOT_UNSUPPORTED: OLE formats could not be validated; unchanged");}
+    finally {if(iterator!=null)Marshal.ReleaseComObject(iterator);if(data!=null)Marshal.ReleaseComObject(data);}
+  }
+  static void Snapshot() {
+    List<uint> formats=new List<uint>();HashSet<uint> metadata=new HashSet<uint>();uint before;
+    Open();try {
+      before=GetClipboardSequenceNumber();uint format=0;SetLastError(0);
+      while((format=EnumClipboardFormats(format))!=0) {
+        if(formats.Count>=1000 || format>65535)throw new InvalidOperationException("CLIPBOARD_SNAPSHOT_UNSUPPORTED: too many or invalid formats");
+        if(FormatName(format).Equals("FileContents",StringComparison.OrdinalIgnoreCase))throw new InvalidOperationException("CLIPBOARD_SNAPSHOT_UNSUPPORTED: indexed file contents cannot be preserved; unchanged");
+        formats.Add(format);if(OleTransportFormat(format))metadata.Add(format);SetLastError(0);
+      }
+      if(Marshal.GetLastWin32Error()!=0)throw new InvalidOperationException("CLIPBOARD_SNAPSHOT_FAILED: enumeration incomplete");
+    }finally {CloseClipboard();}
+    // OLE bookkeeping is not transferable payload. Validate the actual advertised
+    // formats before omitting it; never copy stale process/interface handles.
+    if(metadata.Count>0) {
+      HashSet<uint> advertised=ValidateOleFormats();
+      foreach(uint id in advertised)if(!formats.Contains(id))throw new InvalidOperationException("CLIPBOARD_SNAPSHOT_UNSUPPORTED: OLE format is not available through native clipboard storage; unchanged");
+      oleFormatsValidated=advertised.Count;
+    }
+    Open();try {
+      if(GetClipboardSequenceNumber()!=before)throw new InvalidOperationException("CLIPBOARD_CHANGED: clipboard changed while validating snapshot; nothing replaced");
+      foreach(uint format in formats) {
+        if(metadata.Contains(format)){oleMetadataExcluded++;continue;}
+        IntPtr data=GetClipboardData(format);
+        if(data==IntPtr.Zero)throw new InvalidOperationException("CLIPBOARD_SNAPSHOT_UNSUPPORTED: format "+format+" could not be materialized; clipboard unchanged");
+        IntPtr copy=Duplicate(data,format);
+        if(copy==IntPtr.Zero)throw new InvalidOperationException("CLIPBOARD_SNAPSHOT_UNSUPPORTED: cannot preserve format "+format+"; clipboard unchanged");
+        snapshot.Add(new Item {Format=format,Data=copy});
+      }
+      sequence=GetClipboardSequenceNumber();
+    }finally {CloseClipboard();}
+  }
+  static Item Bytes(uint format,byte[] bytes) {
+    IntPtr data=GlobalAlloc(0x42,new UIntPtr((uint)bytes.Length));if(data==IntPtr.Zero)throw new OutOfMemoryException();
+    IntPtr memory=GlobalLock(data);if(memory==IntPtr.Zero){GlobalFree(data);throw new InvalidOperationException("CLIPBOARD_ALLOC_FAILED");}
+    try {Marshal.Copy(bytes,0,memory,bytes.Length);}finally {GlobalUnlock(data);}return new Item {Format=format,Data=data};
+  }
+  static void Replace(string text) {
+    List<Item> payload=new List<Item>();
+    try {
+      // Publish exclusion flags first, before text can be seen by monitors.
+      foreach(string name in new string[]{"ExcludeClipboardContentFromMonitorProcessing","CanIncludeInClipboardHistory","CanUploadToCloudClipboard"}) {uint format=RegisterClipboardFormat(name);if(format==0)throw new InvalidOperationException("CLIPBOARD_FORMAT_FAILED");payload.Add(Bytes(format,new byte[4]));}
+      transactionFormat=RegisterClipboardFormat("PiComputerUseClipboardTransaction");if(transactionFormat==0)throw new InvalidOperationException("CLIPBOARD_FORMAT_FAILED");
+      payload.Add(Bytes(transactionFormat,transactionToken));
+      payload.Add(Bytes(13,Encoding.Unicode.GetBytes(text+"\0")));
+      Open();try {
+        if(GetClipboardSequenceNumber()!=sequence)throw new InvalidOperationException("CLIPBOARD_CHANGED: user changed clipboard since snapshot; nothing replaced");
+        if(!EmptyClipboard())throw new InvalidOperationException("CLIPBOARD_REPLACE_FAILED");changed=true;replaced=true;restoreOutcome="pending";
+        foreach(Item item in payload){if(SetClipboardData(item.Format,item.Data)==IntPtr.Zero)throw new InvalidOperationException("CLIPBOARD_REPLACE_FAILED: partial replacement must restore");item.Data=IntPtr.Zero;}
+        sequence=GetClipboardSequenceNumber();replaced=true;
+      }finally {if(changed)sequence=GetClipboardSequenceNumber();CloseClipboard();}
+    }finally {foreach(Item item in payload)Free(item);}
+  }
+  static bool OwnsReplacement() {
+    if(GetClipboardOwner()!=clipboardOwner || transactionFormat==0)return false;
+    IntPtr data=GetClipboardData(transactionFormat);if(data==IntPtr.Zero || GlobalSize(data).ToUInt64()<(ulong)transactionToken.Length)return false;
+    IntPtr memory=GlobalLock(data);if(memory==IntPtr.Zero)return false;
+    try {byte[] actual=new byte[transactionToken.Length];Marshal.Copy(memory,actual,0,actual.Length);for(int index=0;index<actual.Length;index++)if(actual[index]!=transactionToken[index])return false;return true;}
+    finally {GlobalUnlock(data);}
+  }
+  static void Restore(bool keep) {
+    if(!changed)return;
+    Open();try {
+      // Synthesized formats can advance the sequence without a new copy. Only
+      // our hidden owner AND transaction nonce allow restoration across that change.
+      // A failed partial restore has removed the nonce; retain its private owner
+      // identity while retrying, but still yield if another window takes ownership.
+      if(replaced && GetClipboardSequenceNumber()!=sequence && !OwnsReplacement() && !(restoring && GetClipboardOwner()==clipboardOwner)){changed=false;restoring=false;restoreOutcome="newer-copy-preserved";return;}
+      if(keep){changed=false;restoreOutcome="kept";return;}
+      List<Item> copies=new List<Item>();bool attempted=false;
+      try {
+        foreach(Item item in snapshot) {IntPtr copy=Duplicate(item.Data,item.Format);if(copy==IntPtr.Zero)throw new InvalidOperationException("CLIPBOARD_RESTORE_FAILED: cannot duplicate snapshot");copies.Add(new Item{Format=item.Format,Data=copy});}
+        if(!EmptyClipboard())throw new InvalidOperationException("CLIPBOARD_RESTORE_FAILED");attempted=true;restoring=true;
+        foreach(Item item in copies){if(SetClipboardData(item.Format,item.Data)==IntPtr.Zero)throw new InvalidOperationException("CLIPBOARD_RESTORE_FAILED: retained snapshot still needs restoration");item.Data=IntPtr.Zero;}
+        changed=false;restoring=false;restoreOutcome="restored";
+      }finally {if(attempted)sequence=GetClipboardSequenceNumber();foreach(Item item in copies)Free(item);}
+    }finally {CloseClipboard();}
+  }
+  [STAThread] static void Main() {
+    Console.InputEncoding=new UTF8Encoding(false);Console.OutputEncoding=new UTF8Encoding(false);
+    clipboardOwner=CreateWindowEx(0,"STATIC","Pi clipboard transaction",0,0,0,0,0,new IntPtr(-3),IntPtr.Zero,IntPtr.Zero,IntPtr.Zero);
+    if(clipboardOwner==IntPtr.Zero)throw new InvalidOperationException("CLIPBOARD_OWNER_FAILED");
+    EventWaitHandle cancel=null;Process parent=null;int ole=-1;
+    try {
+      ole=OleInitialize(IntPtr.Zero);Marshal.ThrowExceptionForHR(ole);
+      var args=json.Deserialize<Dictionary<string,object>>(Console.ReadLine());
+      cancel=EventWaitHandle.OpenExisting(Convert.ToString(args["cancelEvent"]));parent=Process.GetProcessById(Convert.ToInt32(args["parentProcessId"]));IntPtr retained=parent.Handle;
+      Stopwatch snapshotDeadline=Stopwatch.StartNew();
+      Thread watchdog=new Thread(delegate(){while(true){Thread.Sleep(20);lock(phaseGate){if(mayMutate)return;if(cancel.WaitOne(0) || parent.HasExited || snapshotDeadline.ElapsedMilliseconds>5000){Process.GetCurrentProcess().Kill();return;}}}});watchdog.IsBackground=true;watchdog.Start();
+      Snapshot();Reply("snapshot",true,null);
+      string command=Console.ReadLine();
+      if(command!="replace" || cancel.WaitOne(0) || parent.HasExited){Reply("replaced",false,"COMPUTER_USE_STOPPED");Reply("restored",true,null);return;}
+      lock(phaseGate){mayMutate=true;}
+      Replace(Convert.ToString(args["text"]));Reply("replaced",true,null);
+      string next=null;bool received=false;
+      Thread reader=new Thread(delegate(){next=Console.ReadLine();Volatile.Write(ref received,true);});reader.IsBackground=true;reader.Start();
+      Stopwatch lifetime=Stopwatch.StartNew();
+      while(!Volatile.Read(ref received) && !cancel.WaitOne(20) && !parent.HasExited && lifetime.ElapsedMilliseconds<30000){Pump();}
+      bool keep=received && next=="keep" && !cancel.WaitOne(0);
+      Restore(keep);Reply("restored",true,null);
+    }catch(Exception error){
+      Reply(changed?"restore_needed":"failed",false,error.Message);
+    }finally {
+      // Restoration never calls an app's rendering provider. Retry bounded lock
+      // acquisition rather than losing the only retained nontext snapshot.
+      while(changed)try {Restore(false);Reply("restored",true,null);}catch(Exception error){Console.Error.WriteLine("CLIPBOARD_RESTORE_FAILED: "+error.Message);Pump();Thread.Sleep(100);}
+      foreach(Item item in snapshot)Free(item);
+      DestroyWindow(clipboardOwner);
+      if(cancel!=null)cancel.Dispose();if(parent!=null)parent.Dispose();if(ole>=0)OleUninitialize();
+    }
+  }
+}