fix(vscode): bridge clipboard and forward keystrokes in webview (#970)

The Plannotator app runs in a nested cross-origin iframe inside the VS Code
webview, where two input paths break:

- Clipboard: the iframe document never holds focus, so the async Clipboard
  API is rejected ("Document is not focused") and native copy/cut/paste
  events never fire. Copy, cut, and paste all silently fail.
- Keybindings: keydown events don't cross the iframe boundary, so VS Code
  never sees global shortcuts (Cmd+P, etc.) while a Plannotator tab is focused.

Fix both off the one input signal the iframe still receives — keydown:

- Route clipboard reads/writes through the extension host, which owns the
  system clipboard via vscode.env.clipboard. The injected script overrides
  navigator.clipboard and handles Cmd+C/X/V, relaying through the wrapper to
  an onDidReceiveMessage handler and back.
- Forward all other keystrokes to the wrapper, which re-dispatches a synthetic
  KeyboardEvent on the webview document so VS Code can resolve its keybindings.
  Undo/redo/select-all stay native.

Fixes #864
Fixes #969

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: rushelex

apps/vscode-extension/mocks/vscode.ts

@@ -74,8 +74,14 @@ export const commands = {
   async executeCommand(_command: string, ..._args: unknown[]) {},
 };
 
+export interface Webview {
+  html: string;
+  onDidReceiveMessage(listener: (message: unknown) => void): { dispose(): void };
+  postMessage(message: unknown): Thenable<boolean>;
+}
+
 export interface WebviewPanel {
-  webview: { html: string };
+  webview: Webview;
   iconPath?: Uri;
   reveal(viewColumn?: number): void;
   dispose(): void;
@@ -105,11 +111,15 @@ export const window = {
     _viewType: string,
     _title: string,
     _showOptions: number,
-    _options?: { enableScripts?: boolean },
+    _options?: { enableScripts?: boolean; retainContextWhenHidden?: boolean },
   ): WebviewPanel {
     let disposeListener: (() => void) | null = null;
     return {
-      webview: { html: "" },
+      webview: {
+        html: "",
+        onDidReceiveMessage() { return { dispose() {} }; },
+        postMessage() { return Promise.resolve(true); },
+      },
       reveal() {},
       dispose() {
         disposeListener?.();
@@ -138,6 +148,12 @@ export const env = {
   async asExternalUri(uri: Uri): Promise<Uri> {
     return uri;
   },
+  clipboard: {
+    async readText(): Promise<string> {
+      return "";
+    },
+    async writeText(_value: string): Promise<void> {},
+  },
 };
 
 export const comments = {

apps/vscode-extension/src/cookie-proxy.test.ts

@@ -105,6 +105,9 @@ describe("createCookieProxy", () => {
       // Should contain the virtual cookie store with saved cookies
       expect(html).toContain('"plannotator-identity":"tater-42"');
       expect(html).toContain('"other-cookie":"ignore"');
+      // Should forward keystrokes to the parent for VS Code keybindings
+      expect(html).toContain('type:"plannotator-keydown"');
+      expect(html).toContain('window.addEventListener("keydown"');
       // Should still contain original content
       expect(html).toContain("<title>Test</title>");
       expect(html).toContain("Hello");

apps/vscode-extension/src/cookie-proxy.ts

@@ -182,6 +182,50 @@ function injectScript(html: string, savedCookies: string): string {
       setTimeout(sc,500);setInterval(sc,2000);
       var ci=setInterval(function(){if(document.body&&document.body.textContent.indexOf("Your response has been sent")!==-1){clearInterval(ci);sc();fetch("/___ext/close",{method:"POST"});}},500);
       try{window.parent.postMessage("plannotator-ready","*");}catch(e){}
+      // Clipboard bridge: inside a nested cross-origin webview iframe the
+      // document never holds focus, so the async Clipboard API is rejected and
+      // native copy/cut/paste events never fire. Route reads and writes through
+      // the extension host (which owns the system clipboard) and drive them off
+      // keydown, the only input signal the iframe still receives.
+      var readSeq=0,readPending={};
+      function bridgeWrite(text){window.parent.postMessage({type:"plannotator-clipboard-write",text:String(text==null?"":text)},"*");}
+      function bridgeRead(){return new Promise(function(resolve){var id=++readSeq;readPending[id]=resolve;window.parent.postMessage({type:"plannotator-clipboard-read",id:id},"*");});}
+      try{Object.defineProperty(navigator,"clipboard",{configurable:true,value:{
+        writeText:function(t){bridgeWrite(t);return Promise.resolve();},
+        readText:function(){return bridgeRead();}
+      }});}catch(err){}
+      function fieldSelection(el){
+        if(el&&(el.tagName==="INPUT"||el.tagName==="TEXTAREA")&&el.selectionStart!=null&&el.selectionEnd>el.selectionStart){
+          return el.value.slice(el.selectionStart,el.selectionEnd);
+        }
+        return (window.getSelection&&window.getSelection().toString())||"";
+      }
+      window.addEventListener("message",function(e){var d=e.data;if(d&&d.type==="plannotator-clipboard-data"){var cb=readPending[d.id];if(cb){delete readPending[d.id];cb(d.text||"");}}});
+      window.addEventListener("keydown",function(e){
+        var k=(e.key||"").toLowerCase();
+        if((e.metaKey||e.ctrlKey)&&!e.altKey){
+          if(k==="c"||k==="x"){
+            var sel=fieldSelection(document.activeElement);
+            if(sel){
+              e.preventDefault();
+              bridgeWrite(sel);
+              if(k==="x")document.execCommand("delete");
+            }
+            return;
+          }
+          if(k==="v"){
+            e.preventDefault();
+            bridgeRead().then(function(text){if(text)document.execCommand("insertText",false,text);});
+            return;
+          }
+          // Undo/redo/select-all stay native; forwarding them would hijack them.
+          if(k==="a"||k==="z"||k==="y")return;
+        }
+        try{window.parent.postMessage({type:"plannotator-keydown",event:{
+          key:e.key,code:e.code,keyCode:e.keyCode,which:e.which,location:e.location,
+          ctrlKey:e.ctrlKey,shiftKey:e.shiftKey,altKey:e.altKey,metaKey:e.metaKey,repeat:e.repeat
+        }},"*");}catch(err){}
+      });
     })();</script>`;
 
   const headMatch = html.match(/<head(\s[^>]*)?>/) ;

apps/vscode-extension/src/panel-manager.test.ts

@@ -15,15 +15,19 @@ describe("PanelManager", () => {
     spies.length = 0;
   });
 
-  it("sets iframe src in webview html", async () => {
-    let capturedHtml = "";
+  // Stubs createWebviewPanel and returns a handle whose `.html` reflects the
+  // HTML the manager assigns to the panel's webview.
+  function stubWebviewPanel(): { html: string } {
+    const captured = { html: "" };
     const spy = spyOn(vscode.window, "createWebviewPanel");
     spy.mockImplementation((() => {
       let disposeListener: (() => void) | null = null;
       return {
         webview: {
-          get html() { return capturedHtml; },
-          set html(v: string) { capturedHtml = v; },
+          get html() { return captured.html; },
+          set html(v: string) { captured.html = v; },
+          onDidReceiveMessage() { return { dispose() {} }; },
+          postMessage() { return Promise.resolve(true); },
         },
         reveal() {},
         dispose() { disposeListener?.(); },
@@ -34,46 +38,53 @@ describe("PanelManager", () => {
       } as unknown as vscode.WebviewPanel;
     }) as typeof vscode.window.createWebviewPanel);
     spies.push(spy);
+    return captured;
+  }
+
+  it("sets iframe src in webview html", async () => {
+    const captured = stubWebviewPanel();
 
     await manager.open("http://127.0.0.1:9999/review?id=42");
 
-    expect(capturedHtml).toContain(
+    expect(captured.html).toContain(
       'src="http://127.0.0.1:9999/review?id=42"',
     );
   });
 
+  it("re-dispatches keystrokes forwarded from the app iframe", async () => {
+    const captured = stubWebviewPanel();
+
+    await manager.open("http://127.0.0.1:9999/review?id=42");
+
+    expect(captured.html).toContain('d.type === "plannotator-keydown"');
+    expect(captured.html).toContain('new KeyboardEvent("keydown", d.event)');
+  });
+
+  it("relays clipboard messages between the app iframe and the extension host", async () => {
+    const captured = stubWebviewPanel();
+
+    await manager.open("http://127.0.0.1:9999/review?id=42");
+
+    expect(captured.html).toContain("acquireVsCodeApi()");
+    expect(captured.html).toContain('"plannotator-clipboard-write"');
+    expect(captured.html).toContain('"plannotator-clipboard-data"');
+  });
+
   it("uses asExternalUri resolved URL in iframe and CSP", async () => {
     const envSpy = spyOn(vscode.env, "asExternalUri");
     envSpy.mockImplementation(async (_uri: vscode.Uri) => {
       return vscode.Uri.parse("https://localhost:8443/review?id=42");
     });
     spies.push(envSpy);
 
-    let capturedHtml = "";
-    const panelSpy = spyOn(vscode.window, "createWebviewPanel");
-    panelSpy.mockImplementation((() => {
-      let disposeListener: (() => void) | null = null;
-      return {
-        webview: {
-          get html() { return capturedHtml; },
-          set html(v: string) { capturedHtml = v; },
-        },
-        reveal() {},
-        dispose() { disposeListener?.(); },
-        onDidDispose(listener: () => void) {
-          disposeListener = listener;
-          return { dispose() {} };
-        },
-      } as unknown as vscode.WebviewPanel;
-    }) as typeof vscode.window.createWebviewPanel);
-    spies.push(panelSpy);
+    const captured = stubWebviewPanel();
 
     await manager.open("http://127.0.0.1:9999/review?id=42");
 
     expect(envSpy).toHaveBeenCalled();
-    expect(capturedHtml).toContain(
+    expect(captured.html).toContain(
       'src="https://localhost:8443/review?id=42"',
     );
-    expect(capturedHtml).toContain("frame-src https://localhost:8443;");
+    expect(captured.html).toContain("frame-src https://localhost:8443;");
   });
 });

apps/vscode-extension/src/panel-manager.ts

@@ -2,6 +2,12 @@ import * as vscode from "vscode";
 import * as path from "path";
 import { buildWrapperThemeScript } from "./vscode-theme";
 
+// Messages the app iframe sends up to the extension host (see the clipboard
+// bridge injected in cookie-proxy.ts).
+type ClipboardWriteMessage = { type: "plannotator-clipboard-write"; text: string };
+type ClipboardReadMessage = { type: "plannotator-clipboard-read"; id: number };
+type WebviewMessage = ClipboardWriteMessage | ClipboardReadMessage;
+
 export class PanelManager {
   private panels: Set<vscode.WebviewPanel> = new Set();
   private extensionPath: string = "";
@@ -25,8 +31,20 @@ export class PanelManager {
     );
     const origin = `${resolved.scheme}://${resolved.authority}`;
     panel.webview.html = getHtml(resolvedUrl, origin);
+
+    const messageSub = panel.webview.onDidReceiveMessage(async (raw: unknown) => {
+      const msg = raw as WebviewMessage;
+      if (msg.type === "plannotator-clipboard-write") {
+        await vscode.env.clipboard.writeText(msg.text ?? "");
+      } else if (msg.type === "plannotator-clipboard-read") {
+        const text = await vscode.env.clipboard.readText();
+        panel.webview.postMessage({ type: "plannotator-clipboard-data", id: msg.id, text });
+      }
+    });
+
     this.panels.add(panel);
     panel.onDidDispose(() => {
+      messageSub.dispose();
       this.panels.delete(panel);
     });
     return panel;
@@ -60,8 +78,27 @@ function getHtml(url: string, origin: string): string {
     (function() {
       var ready = false;
       var reloads = 0;
+      var vscodeApi = acquireVsCodeApi();
       window.addEventListener("message", function(e) {
-        if (e.data === "plannotator-ready") { ready = true; }
+        var d = e.data;
+        if (d === "plannotator-ready") { ready = true; return; }
+        if (d && d.type === "plannotator-keydown") {
+          // Re-dispatch keystrokes forwarded from the nested app iframe so VS
+          // Code's keybinding service (which listens on the webview document)
+          // can resolve global shortcuts like Cmd+P while the app is focused.
+          window.dispatchEvent(new KeyboardEvent("keydown", d.event));
+          return;
+        }
+        // Relay clipboard requests up to the extension host (owns the system
+        // clipboard) and responses back down to the app iframe.
+        if (d && (d.type === "plannotator-clipboard-write" || d.type === "plannotator-clipboard-read")) {
+          vscodeApi.postMessage(d);
+          return;
+        }
+        if (d && d.type === "plannotator-clipboard-data") {
+          var f = document.getElementById("pn-frame");
+          if (f && f.contentWindow) f.contentWindow.postMessage(d, "*");
+        }
       });
       setTimeout(function() {
         if (!ready && reloads < 1) {