fix(terminal): OSC 52 clipboard writes over plain HTTP (#516)

When Kolu is served over plain HTTP to a non-loopback host, selecting
text inside a terminal pane (or any program that emits OSC 52) produced
a silent `TypeError: Cannot read properties of undefined (reading
'writeText')` and nothing reached the system clipboard. xterm's
`ClipboardAddon` calls `navigator.clipboard.writeText` directly, and
`navigator.clipboard` *itself* is undefined outside a secure context —
https, localhost, or 127.0.0.1.

This PR ships a **`SafeClipboardProvider`** that hands xterm a writer
which tries `navigator.clipboard` first and falls back to a hidden
textarea plus `document.execCommand("copy")` when the API is missing or
rejects. The same helper replaces the now-duplicate fallback block that
`handleCopyTerminalText` already carried in `useTerminalCrud.ts`.

Coverage lands two new e2e scenarios in `osc52-clipboard.feature`: one
asserts the happy path writes through `navigator.clipboard`, the other
stubs `writeText` to reject and verifies the fallback still lands the
text on the clipboard with no page errors.

### Test plan

- [x] `just check` passes
- [x] `just test-quick features/osc52-clipboard.feature` — 2/2 scenarios
pass
- [x] `just test-quick features/copy-pane-text.feature
features/clipboard.feature` — existing suites unaffected
- [x] `just ci` — all 12 contexts green on 6e09d92

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: srid

packages/client/src/terminal/Terminal.tsx

@@ -22,6 +22,7 @@ import { WebglAddon } from "@xterm/addon-webgl";
 import { WebLinksAddon } from "@xterm/addon-web-links";
 import { SearchAddon } from "@xterm/addon-search";
 import { ClipboardAddon } from "@xterm/addon-clipboard";
+import { SafeClipboardProvider } from "./clipboard";
 import { Unicode11Addon } from "@xterm/addon-unicode11";
 import { ImageAddon } from "@xterm/addon-image";
 import { SerializeAddon } from "@xterm/addon-serialize";
@@ -237,7 +238,7 @@ const Terminal: Component<{
     const search = new SearchAddon();
     term.loadAddon(search);
     setSearchAddon(search);
-    term.loadAddon(new ClipboardAddon());
+    term.loadAddon(new ClipboardAddon(undefined, new SafeClipboardProvider()));
     term.loadAddon(new Unicode11Addon());
     term.unicode.activeVersion = "11";
     term.loadAddon(new ImageAddon());

packages/client/src/terminal/clipboard.ts

@@ -0,0 +1,62 @@
+/**
+ * Clipboard write with a fallback for non-secure contexts.
+ *
+ * `navigator.clipboard` is only defined in secure contexts (https, localhost,
+ * 127.0.0.1). On plain http to any other host it is undefined, so both
+ * direct `navigator.clipboard.writeText` calls and xterm's `ClipboardAddon`
+ * OSC 52 handler throw `TypeError: Cannot read properties of undefined`.
+ *
+ * The fallback selects a hidden textarea and runs `document.execCommand("copy")`,
+ * which works in any browsing context at the cost of a brief focus steal.
+ */
+
+import type {
+  IClipboardProvider,
+  ClipboardSelectionType,
+} from "@xterm/addon-clipboard";
+
+/** Write `text` to the system clipboard, falling back to execCommand when
+ *  navigator.clipboard is unavailable or throws. Throws if both paths fail. */
+export async function writeTextToClipboard(text: string): Promise<void> {
+  if (navigator.clipboard?.writeText) {
+    try {
+      await navigator.clipboard.writeText(text);
+      return;
+    } catch {
+      // Fall through to execCommand — navigator.clipboard can reject for
+      // reasons other than missing secure context (permission denied, etc.).
+    }
+  }
+  const textarea = document.createElement("textarea");
+  textarea.value = text;
+  textarea.style.position = "fixed";
+  textarea.style.opacity = "0";
+  document.body.appendChild(textarea);
+  try {
+    textarea.select();
+    const ok = document.execCommand("copy");
+    if (!ok) throw new Error("clipboard access blocked");
+  } finally {
+    document.body.removeChild(textarea);
+  }
+}
+
+/** xterm `IClipboardProvider` that uses `writeTextToClipboard` for writes
+ *  (survives non-secure contexts) and returns empty on reads when
+ *  navigator.clipboard is unavailable. OSC 52 read queries (`?`) are rare
+ *  and have no safe fallback. */
+export class SafeClipboardProvider implements IClipboardProvider {
+  public async readText(selection: ClipboardSelectionType): Promise<string> {
+    if (selection !== "c") return "";
+    if (!navigator.clipboard?.readText) return "";
+    return navigator.clipboard.readText();
+  }
+
+  public async writeText(
+    selection: ClipboardSelectionType,
+    text: string,
+  ): Promise<void> {
+    if (selection !== "c") return;
+    await writeTextToClipboard(text);
+  }
+}

packages/client/src/terminal/useTerminalCrud.ts

@@ -7,6 +7,7 @@ import { toast } from "solid-sonner";
 import { availableThemes } from "../theme";
 import { client } from "../rpc/rpc";
 import { useSubPanel } from "./useSubPanel";
+import { writeTextToClipboard } from "./clipboard";
 import { useTips } from "../settings/useTips";
 import { useServerState } from "../settings/useServerState";
 import { CONTEXTUAL_TIPS } from "../settings/tips";
@@ -149,24 +150,7 @@ export function useTerminalCrud(deps: {
     if (id === null) return;
     try {
       const text = await client.terminal.screenText({ id });
-      if (navigator.clipboard?.writeText) {
-        await navigator.clipboard.writeText(text);
-      } else {
-        // Fallback for non-secure contexts (HTTP on non-localhost)
-        // where navigator.clipboard is undefined.
-        const textarea = document.createElement("textarea");
-        textarea.value = text;
-        textarea.style.position = "fixed";
-        textarea.style.opacity = "0";
-        document.body.appendChild(textarea);
-        try {
-          textarea.select();
-          const ok = document.execCommand("copy");
-          if (!ok) throw new Error("clipboard access blocked");
-        } finally {
-          document.body.removeChild(textarea);
-        }
-      }
+      await writeTextToClipboard(text);
       toast.success("Copied terminal text to clipboard");
     } catch (err) {
       console.error("Failed to copy terminal text:", err);

packages/tests/features/osc52-clipboard.feature

@@ -0,0 +1,19 @@
+Feature: OSC 52 clipboard writes
+  xterm's OSC 52 handler decodes the base64 payload and writes it to the
+  system clipboard. Works in secure contexts via navigator.clipboard and
+  falls back to document.execCommand when navigator.clipboard is unavailable
+  (non-secure HTTP contexts) or rejects.
+
+  Background:
+    Given the terminal is ready
+
+  Scenario: OSC 52 writes to the clipboard via navigator.clipboard
+    When I run "printf '\x1b]52;c;aGVsbG8tc2VjdXJl\x07'"
+    Then the clipboard should contain "hello-secure"
+    And there should be no page errors
+
+  Scenario: OSC 52 falls back to execCommand when navigator.clipboard is unavailable
+    When I disable navigator.clipboard.writeText
+    And I run "printf '\x1b]52;c;aGVsbG8tZmFsbGJhY2s=\x07'"
+    Then the clipboard should contain "hello-fallback"
+    And there should be no page errors

packages/tests/step_definitions/osc52_steps.ts

@@ -0,0 +1,21 @@
+import { When } from "@cucumber/cucumber";
+import { KoluWorld } from "../support/world.ts";
+
+/** Force navigator.clipboard.writeText to reject so the ClipboardAddon provider
+ *  exercises the execCommand fallback path. Leaves readText intact so the
+ *  clipboard-contents assertion can still read the system clipboard after
+ *  the fallback writes to it. */
+When(
+  "I disable navigator.clipboard.writeText",
+  async function (this: KoluWorld) {
+    // Pass evaluate a string to sidestep tsx/esbuild's `__name` helper
+    // injection, which breaks when the serialized function is evaluated
+    // in the browser (see playwright/playwright#31105).
+    await this.page.evaluate(`
+      Object.defineProperty(navigator.clipboard, "writeText", {
+        configurable: true,
+        value: () => Promise.reject(new Error("clipboard disabled for test"))
+      });
+    `);
+  },
+);