Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

feat: add clipboard read/write endpoints and CLI (#344)

pinchtabdev217bbd891734
diff --git a/cmd/pinchtab/cmd_cli_clipboard.go b/cmd/pinchtab/cmd_cli_clipboard.go
new file mode 100644
index 00000000..4c997bec
--- /dev/null
+++ b/cmd/pinchtab/cmd_cli_clipboard.go
@@ -0,0 +1,98 @@
+package main
+
+import (
+ "encoding/json"
+ "fmt"
+ "net/http"
+ "os"
+
+ "github.com/pinchtab/pinchtab/internal/cli/apiclient"
+ "github.com/spf13/cobra"
+)
+
+var clipboardCmd = &cobra.Command{
+ Use: "clipboard",
+ Short: "Clipboard operations",
+ Long: "Read and write shared clipboard content.",
+}
+
+var clipboardReadCmd = &cobra.Command{
+ Use: "read",
+ Short: "Read clipboard text",
+ Run: func(cmd *cobra.Command, args []string) {
+ runCLI(func(rt cliRuntime) {
+ clipboardRead(rt.client, rt.base, rt.token)
+ })
+ },
+}
+
+var clipboardWriteCmd = &cobra.Command{
+ Use: "write <text>",
+ Short: "Write text to clipboard",
+ Args: cobra.MinimumNArgs(1),
+ Run: func(cmd *cobra.Command, args []string) {
+ runCLI(func(rt cliRuntime) {
+ clipboardWrite(rt.client, rt.base, rt.token, args)
+ })
+ },
+}
+
+var clipboardCopyCmd = &cobra.Command{
+ Use: "copy <text>",
+ Short: "Copy text to clipboard (alias for write)",
+ Args: cobra.MinimumNArgs(1),
+ Run: func(cmd *cobra.Command, args []string) {
+ runCLI(func(rt cliRuntime) {
+ clipboardWrite(rt.client, rt.base, rt.token, args)
+ })
+ },
+}
+
+var clipboardPasteCmd = &cobra.Command{
+ Use: "paste",
+ Short: "Paste clipboard text (alias for read)",
+ Run: func(cmd *cobra.Command, args []string) {
+ runCLI(func(rt cliRuntime) {
+ clipboardRead(rt.client, rt.base, rt.token)
+ })
+ },
+}
+
+func clipboardRead(client *http.Client, base, token string) {
+ result := apiclient.DoGetRaw(client, base, token, "/clipboard/read", nil)
+ if result == nil {
+ fmt.Fprintln(os.Stderr, "Failed to read clipboard")
+ os.Exit(1)
+ }
+
+ var resp struct {
+ Text string `json:"text"`
+ }
+ if err := json.Unmarshal(result, &resp); err != nil {
+ fmt.Fprintf(os.Stderr, "Failed to parse response: %v\n", err)
+ os.Exit(1)
+ }
+
+ fmt.Println(resp.Text)
+}
+
+func clipboardWrite(client *http.Client, base, token string, args []string) {
+ result := apiclient.DoPost(client, base, token, "/clipboard/write", map[string]any{
+ "text": joinArgs(args),
+ })
+
+ if result != nil {
+ fmt.Println("Clipboard updated")
+ }
+}
+
+func joinArgs(args []string) string {
+ if len(args) == 0 {
+ return ""
+ }
+ out := args[0]
+ for _, arg := range args[1:] {
+ out += " " + arg
+ }
+ return out
+}
diff --git a/cmd/pinchtab/cmd_cli_register.go b/cmd/pinchtab/cmd_cli_register.go
index 462c5498..8a2ad361 100644
--- a/cmd/pinchtab/cmd_cli_register.go
+++ b/cmd/pinchtab/cmd_cli_register.go
@@ -43,9 +43,11 @@ func registerBrowserCommands() {
dialogCmd,
consoleCmd,
errorsCmd,
+ clipboardCmd,
)
tabsCmd.AddCommand(tabNewCmd, tabCloseCmd)
+ clipboardCmd.AddCommand(clipboardReadCmd, clipboardWriteCmd, clipboardCopyCmd, clipboardPasteCmd)
keyboardCmd.AddCommand(keyboardTypeCmd, keyboardInsertTextCmd)
dialogCmd.AddCommand(dialogAcceptCmd, dialogDismissCmd)
@@ -86,6 +88,7 @@ func registerBrowserCommands() {
dialogCmd,
consoleCmd,
errorsCmd,
+ clipboardCmd,
)
}
diff --git a/internal/config/config_file.go b/internal/config/config_file.go
index d0bdd551..752941d2 100644
--- a/internal/config/config_file.go
+++ b/internal/config/config_file.go
@@ -25,6 +25,7 @@ func DefaultFileConfig() FileConfig {
allowDownload := false
downloadMaxBytes := DefaultDownloadMaxBytes
allowUpload := false
+ allowClipboard := false
uploadMaxRequestBytes := DefaultUploadMaxRequestBytes
uploadMaxFiles := DefaultUploadMaxFiles
uploadMaxFileBytes := DefaultUploadMaxFileBytes
@@ -58,6 +59,7 @@ func DefaultFileConfig() FileConfig {
DownloadAllowedDomains: []string{},
DownloadMaxBytes: &downloadMaxBytes,
AllowUpload: &allowUpload,
+ AllowClipboard: &allowClipboard,
UploadMaxRequestBytes: &uploadMaxRequestBytes,
UploadMaxFiles: &uploadMaxFiles,
UploadMaxFileBytes: &uploadMaxFileBytes,
@@ -167,6 +169,7 @@ type securityConfigJSON struct {
DownloadAllowedDomains []string `json:"downloadAllowedDomains"`
DownloadMaxBytes *int `json:"downloadMaxBytes"`
AllowUpload *bool `json:"allowUpload"`
+ AllowClipboard *bool `json:"allowClipboard"`
UploadMaxRequestBytes *int `json:"uploadMaxRequestBytes"`
UploadMaxFiles *int `json:"uploadMaxFiles"`
UploadMaxFileBytes *int `json:"uploadMaxFileBytes"`
@@ -285,6 +288,7 @@ func (fc FileConfig) MarshalJSON() ([]byte, error) {
DownloadAllowedDomains: copyStringSlice(fc.Security.DownloadAllowedDomains),
DownloadMaxBytes: fc.Security.DownloadMaxBytes,
AllowUpload: fc.Security.AllowUpload,
+ AllowClipboard: fc.Security.AllowClipboard,
UploadMaxRequestBytes: fc.Security.UploadMaxRequestBytes,
UploadMaxFiles: fc.Security.UploadMaxFiles,
UploadMaxFileBytes: fc.Security.UploadMaxFileBytes,
@@ -368,6 +372,7 @@ func FileConfigFromRuntime(cfg *RuntimeConfig) FileConfig {
downloadAllowedDomains := copyStringSlice(cfg.DownloadAllowedDomains)
downloadMaxBytes := cfg.EffectiveDownloadMaxBytes()
allowUpload := cfg.AllowUpload
+ allowClipboard := cfg.AllowClipboard
uploadMaxRequestBytes := cfg.EffectiveUploadMaxRequestBytes()
uploadMaxFiles := cfg.EffectiveUploadMaxFiles()
uploadMaxFileBytes := cfg.EffectiveUploadMaxFileBytes()
@@ -433,6 +438,7 @@ func FileConfigFromRuntime(cfg *RuntimeConfig) FileConfig {
DownloadAllowedDomains: downloadAllowedDomains,
DownloadMaxBytes: &downloadMaxBytes,
AllowUpload: &allowUpload,
+ AllowClipboard: &allowClipboard,
UploadMaxRequestBytes: &uploadMaxRequestBytes,
UploadMaxFiles: &uploadMaxFiles,
UploadMaxFileBytes: &uploadMaxFileBytes,
@@ -490,6 +496,7 @@ type legacyFileConfig struct {
AllowScreencast *bool `json:"allowScreencast,omitempty"`
AllowDownload *bool `json:"allowDownload,omitempty"`
AllowUpload *bool `json:"allowUpload,omitempty"`
+ AllowClipboard *bool `json:"allowClipboard,omitempty"`
StateDir string `json:"stateDir"`
ProfileDir string `json:"profileDir"`
Headless *bool `json:"headless,omitempty"`
@@ -534,6 +541,7 @@ func convertLegacyConfig(lc *legacyFileConfig) *FileConfig {
fc.Security.AllowScreencast = lc.AllowScreencast
fc.Security.AllowDownload = lc.AllowDownload
fc.Security.AllowUpload = lc.AllowUpload
+ fc.Security.AllowClipboard = lc.AllowClipboard
// Timeouts
fc.Timeouts.ActionSec = lc.TimeoutSec
diff --git a/internal/config/config_load.go b/internal/config/config_load.go
index 62218a55..68efec51 100644
--- a/internal/config/config_load.go
+++ b/internal/config/config_load.go
@@ -217,6 +217,9 @@ func applyFileConfig(cfg *RuntimeConfig, fc *FileConfig) {
if fc.Security.AllowUpload != nil {
cfg.AllowUpload = *fc.Security.AllowUpload
}
+ if fc.Security.AllowClipboard != nil {
+ cfg.AllowClipboard = *fc.Security.AllowClipboard
+ }
if fc.Security.UploadMaxRequestBytes != nil {
cfg.UploadMaxRequestBytes = clampPositiveLimit(*fc.Security.UploadMaxRequestBytes, DefaultUploadMaxRequestBytes, MaxUploadMaxRequestBytes)
}
diff --git a/internal/config/config_types.go b/internal/config/config_types.go
index ea85517c..1c8a7024 100644
--- a/internal/config/config_types.go
+++ b/internal/config/config_types.go
@@ -22,6 +22,7 @@ type RuntimeConfig struct {
DownloadAllowedDomains []string
DownloadMaxBytes int
AllowUpload bool
+ AllowClipboard bool
UploadMaxRequestBytes int
UploadMaxFiles int
UploadMaxFileBytes int
@@ -181,6 +182,7 @@ type SecurityConfig struct {
DownloadAllowedDomains []string `json:"downloadAllowedDomains,omitempty"`
DownloadMaxBytes *int `json:"downloadMaxBytes,omitempty"`
AllowUpload *bool `json:"allowUpload,omitempty"`
+ AllowClipboard *bool `json:"allowClipboard,omitempty"`
UploadMaxRequestBytes *int `json:"uploadMaxRequestBytes,omitempty"`
UploadMaxFiles *int `json:"uploadMaxFiles,omitempty"`
UploadMaxFileBytes *int `json:"uploadMaxFileBytes,omitempty"`
diff --git a/internal/handlers/clipboard.go b/internal/handlers/clipboard.go
new file mode 100644
index 00000000..91c2ca04
--- /dev/null
+++ b/internal/handlers/clipboard.go
@@ -0,0 +1,108 @@
+package handlers
+
+import (
+ "encoding/json"
+ "fmt"
+ "log/slog"
+ "net/http"
+ "sync"
+
+ "github.com/pinchtab/pinchtab/internal/httpx"
+)
+
+type clipboardRequest struct {
+ TabID string `json:"tabId"`
+ Text *string `json:"text"`
+}
+
+const maxClipboardTextBytes = 64 << 10
+
+// clipboardStore is a simple in-memory clipboard shared across all requests.
+// In headless Chrome, navigator.clipboard and execCommand are unreliable,
+// so we maintain clipboard state server-side.
+type clipboardStore struct {
+ mu sync.RWMutex
+ text string
+}
+
+func (s *clipboardStore) Read() string {
+ s.mu.RLock()
+ defer s.mu.RUnlock()
+ return s.text
+}
+
+func (s *clipboardStore) Write(text string) {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ s.text = text
+}
+
+func (h *Handlers) clipboardEnabled() bool {
+ return h != nil && h.Config != nil && h.Config.AllowClipboard
+}
+
+// HandleClipboardRead reads text from the clipboard.
+func (h *Handlers) HandleClipboardRead(w http.ResponseWriter, r *http.Request) {
+ if !h.clipboardEnabled() {
+ httpx.ErrorCode(w, 403, "clipboard_disabled", httpx.DisabledEndpointMessage("clipboard", "security.allowClipboard"), false, map[string]any{
+ "setting": "security.allowClipboard",
+ })
+ return
+ }
+
+ text := h.clipboard.Read()
+
+ slog.Info("clipboard: read",
+ "textLen", len(text),
+ "remoteAddr", r.RemoteAddr,
+ )
+
+ httpx.JSON(w, http.StatusOK, map[string]any{
+ "text": text,
+ })
+}
+
+// HandleClipboardWrite writes text to the clipboard.
+func (h *Handlers) HandleClipboardWrite(w http.ResponseWriter, r *http.Request) {
+ if !h.clipboardEnabled() {
+ httpx.ErrorCode(w, 403, "clipboard_disabled", httpx.DisabledEndpointMessage("clipboard", "security.allowClipboard"), false, map[string]any{
+ "setting": "security.allowClipboard",
+ })
+ return
+ }
+
+ var req clipboardRequest
+ if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, maxBodySize)).Decode(&req); err != nil {
+ httpx.Error(w, http.StatusBadRequest, fmt.Errorf("decode: %w", err))
+ return
+ }
+ if req.Text == nil {
+ httpx.Error(w, http.StatusBadRequest, fmt.Errorf("text required"))
+ return
+ }
+ if len(*req.Text) > maxClipboardTextBytes {
+ httpx.Error(w, http.StatusBadRequest, fmt.Errorf("text too large (max %d bytes)", maxClipboardTextBytes))
+ return
+ }
+
+ h.clipboard.Write(*req.Text)
+
+ slog.Info("clipboard: write",
+ "textLen", len(*req.Text),
+ "remoteAddr", r.RemoteAddr,
+ )
+
+ httpx.JSON(w, http.StatusOK, map[string]any{
+ "success": true,
+ })
+}
+
+// HandleClipboardCopy is an alias for HandleClipboardWrite.
+func (h *Handlers) HandleClipboardCopy(w http.ResponseWriter, r *http.Request) {
+ h.HandleClipboardWrite(w, r)
+}
+
+// HandleClipboardPaste reads from clipboard (paste = read clipboard content).
+func (h *Handlers) HandleClipboardPaste(w http.ResponseWriter, r *http.Request) {
+ h.HandleClipboardRead(w, r)
+}
diff --git a/internal/handlers/clipboard_test.go b/internal/handlers/clipboard_test.go
new file mode 100644
index 00000000..0167bf48
--- /dev/null
+++ b/internal/handlers/clipboard_test.go
@@ -0,0 +1,116 @@
+package handlers
+
+import (
+ "bytes"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "testing"
+
+ "github.com/pinchtab/pinchtab/internal/config"
+)
+
+func TestHandleClipboardReadWriteWithoutTabs(t *testing.T) {
+ h := New(&mockBridge{failTab: true}, &config.RuntimeConfig{AllowClipboard: true}, nil, nil, nil)
+
+ writeReq := httptest.NewRequest(http.MethodPost, "/clipboard/write", bytes.NewReader([]byte(`{"text":"hello"}`)))
+ writeW := httptest.NewRecorder()
+ h.HandleClipboardWrite(writeW, writeReq)
+ if writeW.Code != http.StatusOK {
+ t.Fatalf("expected write status 200, got %d: %s", writeW.Code, writeW.Body.String())
+ }
+ if strings.Contains(writeW.Body.String(), "tabId") {
+ t.Fatalf("expected write response to omit tabId, got %s", writeW.Body.String())
+ }
+
+ readReq := httptest.NewRequest(http.MethodGet, "/clipboard/read", nil)
+ readW := httptest.NewRecorder()
+ h.HandleClipboardRead(readW, readReq)
+ if readW.Code != http.StatusOK {
+ t.Fatalf("expected read status 200, got %d: %s", readW.Code, readW.Body.String())
+ }
+ if !strings.Contains(readW.Body.String(), `"text":"hello"`) {
+ t.Fatalf("expected read response to include clipboard text, got %s", readW.Body.String())
+ }
+ if strings.Contains(readW.Body.String(), "tabId") {
+ t.Fatalf("expected read response to omit tabId, got %s", readW.Body.String())
+ }
+}
+
+func TestHandleClipboardReadIgnoresTabID(t *testing.T) {
+ h := New(&mockBridge{failTab: true}, &config.RuntimeConfig{AllowClipboard: true}, nil, nil, nil)
+ h.clipboard.Write("shared")
+
+ req := httptest.NewRequest(http.MethodGet, "/clipboard/read?tabId=missing", nil)
+ w := httptest.NewRecorder()
+ h.HandleClipboardRead(w, req)
+
+ if w.Code != http.StatusOK {
+ t.Fatalf("expected read status 200, got %d: %s", w.Code, w.Body.String())
+ }
+ if !strings.Contains(w.Body.String(), `"text":"shared"`) {
+ t.Fatalf("expected shared clipboard text, got %s", w.Body.String())
+ }
+}
+
+func TestHandleClipboardPasteAliasesRead(t *testing.T) {
+ h := New(&mockBridge{}, &config.RuntimeConfig{AllowClipboard: true}, nil, nil, nil)
+ h.clipboard.Write("copied")
+
+ mux := http.NewServeMux()
+ h.RegisterRoutes(mux, nil)
+
+ req := httptest.NewRequest(http.MethodGet, "/clipboard/paste", nil)
+ w := httptest.NewRecorder()
+ mux.ServeHTTP(w, req)
+
+ if w.Code != http.StatusOK {
+ t.Fatalf("expected paste status 200, got %d: %s", w.Code, w.Body.String())
+ }
+ if !strings.Contains(w.Body.String(), `"text":"copied"`) {
+ t.Fatalf("expected paste response to include clipboard text, got %s", w.Body.String())
+ }
+}
+
+func TestHandleClipboardWriteRejectsLargeText(t *testing.T) {
+ h := New(&mockBridge{}, &config.RuntimeConfig{AllowClipboard: true}, nil, nil, nil)
+ tooLarge := strings.Repeat("x", maxClipboardTextBytes+1)
+
+ req := httptest.NewRequest(http.MethodPost, "/clipboard/write", bytes.NewReader([]byte(`{"text":"`+tooLarge+`"}`)))
+ w := httptest.NewRecorder()
+ h.HandleClipboardWrite(w, req)
+
+ if w.Code != http.StatusBadRequest {
+ t.Fatalf("expected oversized write status 400, got %d: %s", w.Code, w.Body.String())
+ }
+}
+
+func TestHandleClipboardDisabled(t *testing.T) {
+ h := New(&mockBridge{}, &config.RuntimeConfig{}, nil, nil, nil)
+
+ req := httptest.NewRequest(http.MethodGet, "/clipboard/read", nil)
+ w := httptest.NewRecorder()
+ h.HandleClipboardRead(w, req)
+
+ if w.Code != http.StatusForbidden {
+ t.Fatalf("expected disabled read status 403, got %d", w.Code)
+ }
+}
+
+func TestHelpIncludesClipboardSecurityStatus(t *testing.T) {
+ h := New(&mockBridge{}, &config.RuntimeConfig{}, nil, nil, nil)
+
+ req := httptest.NewRequest(http.MethodGet, "/help", nil)
+ w := httptest.NewRecorder()
+ h.HandleHelp(w, req)
+
+ if w.Code != http.StatusOK {
+ t.Fatalf("expected help status 200, got %d", w.Code)
+ }
+ if !strings.Contains(w.Body.String(), "security.allowClipboard") {
+ t.Fatalf("expected help response to include clipboard security setting, got %s", w.Body.String())
+ }
+ if !strings.Contains(w.Body.String(), "GET /clipboard/paste") {
+ t.Fatalf("expected help response to include GET clipboard paste route, got %s", w.Body.String())
+ }
+}
diff --git a/internal/handlers/handlers.go b/internal/handlers/handlers.go
index cf757218..9f247a1c 100644
--- a/internal/handlers/handlers.go
+++ b/internal/handlers/handlers.go
@@ -26,6 +26,7 @@ type Handlers struct {
IntentCache *semantic.IntentCache
Recovery *semantic.RecoveryEngine
Router *engine.Router // optional; nil ⇒ chrome-only
+ clipboard clipboardStore
}
func New(b bridge.BridgeAPI, cfg *config.RuntimeConfig, p bridge.ProfileService, d *dashboard.Dashboard, o bridge.OrchestratorService) *Handlers {
@@ -146,6 +147,10 @@ func (h *Handlers) RegisterRoutes(mux *http.ServeMux, doShutdown func()) {
mux.HandleFunc("GET /screencast/tabs", h.HandleScreencastAll)
mux.HandleFunc("POST /tabs/{id}/evaluate", h.HandleTabEvaluate)
mux.HandleFunc("POST /evaluate", h.HandleEvaluate)
+ mux.HandleFunc("GET /clipboard/read", h.HandleClipboardRead)
+ mux.HandleFunc("POST /clipboard/write", h.HandleClipboardWrite)
+ mux.HandleFunc("POST /clipboard/copy", h.HandleClipboardCopy)
+ mux.HandleFunc("GET /clipboard/paste", h.HandleClipboardPaste)
mux.HandleFunc("GET /network", h.HandleNetwork)
mux.HandleFunc("GET /network/stream", h.HandleNetworkStream)
mux.HandleFunc("GET /network/{requestId}", h.HandleNetworkByID)
diff --git a/internal/handlers/help.go b/internal/handlers/help.go
index 4462a7a3..c78e7c1c 100644
--- a/internal/handlers/help.go
+++ b/internal/handlers/help.go
@@ -35,6 +35,10 @@ func (h *Handlers) HandleHelp(wr http.ResponseWriter, _ *http.Request) {
"POST /tabs/{id}/upload": endpointStatusSummary(security["upload"], "set files on a file input in a specific tab"),
"GET /screencast": endpointStatusSummary(security["screencast"], "stream live tab frames"),
"GET /screencast/tabs": endpointStatusSummary(security["screencast"], "list tabs available for live capture"),
+ "GET /clipboard/read": endpointStatusSummary(security["clipboard"], "read shared clipboard text"),
+ "POST /clipboard/write": endpointStatusSummary(security["clipboard"], "write shared clipboard text (body: {text})"),
+ "POST /clipboard/copy": endpointStatusSummary(security["clipboard"], "alias for clipboard write"),
+ "GET /clipboard/paste": endpointStatusSummary(security["clipboard"], "read shared clipboard text (alias for read)"),
},
"security": security,
"notes": []string{
diff --git a/internal/handlers/security.go b/internal/handlers/security.go
index 071ccbed..4020060d 100644
--- a/internal/handlers/security.go
+++ b/internal/handlers/security.go
@@ -57,6 +57,12 @@ func (h *Handlers) endpointSecurityStates() map[string]endpointSecurityState {
Message: httpx.DisabledEndpointMessage("upload", "security.allowUpload"),
Paths: []string{"POST /upload", "POST /tabs/{id}/upload"},
},
+ "clipboard": {
+ Enabled: h.clipboardEnabled(),
+ Setting: "security.allowClipboard",
+ Message: httpx.DisabledEndpointMessage("clipboard", "security.allowClipboard"),
+ Paths: []string{"GET /clipboard/read", "POST /clipboard/write", "POST /clipboard/copy", "GET /clipboard/paste"},
+ },
}
}
diff --git a/internal/strategy/autorestart/autorestart.go b/internal/strategy/autorestart/autorestart.go
index 0dc33e49..88b1bcac 100644
--- a/internal/strategy/autorestart/autorestart.go
+++ b/internal/strategy/autorestart/autorestart.go
@@ -179,6 +179,7 @@ func (s *Strategy) RegisterRoutes(mux *http.ServeMux) {
"GET /snapshot", "GET /screenshot", "GET /text", "GET /pdf", "POST /pdf",
"GET /console", "POST /console/clear",
"GET /errors", "POST /errors/clear",
+ "GET /clipboard/read", "POST /clipboard/write", "POST /clipboard/copy", "GET /clipboard/paste",
"POST /navigate", "POST /back", "POST /forward", "POST /reload",
"POST /action", "POST /actions",
"POST /tab", "POST /tab/lock", "POST /tab/unlock",
diff --git a/internal/strategy/simple/simple.go b/internal/strategy/simple/simple.go
index b1144f16..1d9d5836 100644
--- a/internal/strategy/simple/simple.go
+++ b/internal/strategy/simple/simple.go
@@ -53,6 +53,7 @@ func (s *Strategy) RegisterRoutes(mux *http.ServeMux) {
"GET /snapshot", "GET /screenshot", "GET /text", "GET /pdf", "POST /pdf",
"GET /console", "POST /console/clear",
"GET /errors", "POST /errors/clear",
+ "GET /clipboard/read", "POST /clipboard/write", "POST /clipboard/copy", "GET /clipboard/paste",
"POST /navigate", "POST /back", "POST /forward", "POST /reload",
"POST /action", "POST /actions",
"POST /tab", "POST /tab/lock", "POST /tab/unlock",
diff --git a/skills/pinchtab-dev/SKILL.md b/skills/pinchtab-dev/SKILL.md
index 8e958c63..2781d390 100644
--- a/skills/pinchtab-dev/SKILL.md
+++ b/skills/pinchtab-dev/SKILL.md
@@ -115,14 +115,24 @@ tests/e2e/ E2E test suites
go test ./internal/handlers # Specific package
```
-### E2E Tests
+### E2E Tests (requires Docker)
```bash
-./dev e2e pr # Fast suite for PRs
-./dev e2e api-fast # API tests only
-./dev e2e cli-fast # CLI tests only
-./dev e2e release # Full release suite
+./dev e2e pr # Fast suite for PRs (api-fast + cli-fast)
+./dev e2e api-fast # API tests only (fast)
+./dev e2e cli-fast # CLI tests only (fast)
+./dev e2e api-full # API tests (full, with multiple configs)
+./dev e2e cli-full # CLI tests (full)
+./dev e2e release # Full release suite (api-full + cli-full)
+./dev e2e docker # Docker smoke test only
+
+# Run specific test file(s) with filter (second argument)
+./dev e2e api-fast clipboard # Run only clipboard-basic.sh
+./dev e2e api-full "clipboard|console" # Run clipboard and console tests
+./dev e2e cli-fast browser # Run browser-basic.sh in CLI suite
```
+The filter is a regex pattern matched against scenario filenames. Requires Docker daemon running.
+
### Dashboard Tests
```bash
./dev test dashboard # Vitest
diff --git a/tests/e2e/config/pinchtab.json b/tests/e2e/config/pinchtab.json
index 836df953..8526e1e5 100644
--- a/tests/e2e/config/pinchtab.json
+++ b/tests/e2e/config/pinchtab.json
@@ -38,6 +38,7 @@
"allowEvaluate": true,
"allowDownload": true,
"allowUpload": true,
+ "allowClipboard": true,
"attach": {
"enabled": true,
"allowHosts": [
diff --git a/tests/e2e/scenarios-api/clipboard-basic.sh b/tests/e2e/scenarios-api/clipboard-basic.sh
new file mode 100755
index 00000000..c70f94dd
--- /dev/null
+++ b/tests/e2e/scenarios-api/clipboard-basic.sh
@@ -0,0 +1,112 @@
+#!/bin/bash
+# clipboard-basic.sh — Clipboard read/write API tests.
+
+GROUP_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${GROUP_DIR}/../helpers/api.sh"
+
+# ─────────────────────────────────────────────────────────────────
+start_test "POST /clipboard/write sets clipboard text"
+
+UNIQUE_TEXT="pinchtab-test-$(date +%s)"
+pt_post "/clipboard/write" -d "{\"text\":\"${UNIQUE_TEXT}\"}"
+assert_ok "write clipboard"
+assert_json_exists "$RESULT" '.success' "has success"
+
+end_test
+
+# ─────────────────────────────────────────────────────────────────
+start_test "GET /clipboard/read returns clipboard text without a tab"
+
+pt_get "/clipboard/read"
+assert_ok "read clipboard"
+assert_json_contains "$RESULT" '.text' "$UNIQUE_TEXT" "reads back written text"
+
+end_test
+
+# ─────────────────────────────────────────────────────────────────
+start_test "POST /clipboard/copy (alias for write)"
+
+COPY_TEXT="pinchtab-copy-$(date +%s)"
+pt_post "/clipboard/copy" -d "{\"text\":\"${COPY_TEXT}\"}"
+assert_ok "copy"
+assert_json_exists "$RESULT" '.success' "has success"
+
+pt_get "/clipboard/read"
+assert_json_contains "$RESULT" '.text' "$COPY_TEXT" "copy updated clipboard"
+
+end_test
+
+# ─────────────────────────────────────────────────────────────────
+start_test "GET /clipboard/paste returns clipboard text"
+
+pt_get "/clipboard/paste"
+assert_ok "paste"
+assert_json_contains "$RESULT" '.text' "$COPY_TEXT" "paste returns clipboard text"
+
+end_test
+
+# ─────────────────────────────────────────────────────────────────
+start_test "POST /clipboard/write without text → error"
+
+pt_post "/clipboard/write" -d "{}"
+assert_not_ok "rejects missing text"
+
+end_test
+
+# ─────────────────────────────────────────────────────────────────
+start_test "Clipboard ignores tabId for compatibility"
+
+pt_get "/clipboard/read?tabId=nonexistent_xyz_999"
+assert_ok "read ignores tabId"
+assert_json_contains "$RESULT" '.text' "$COPY_TEXT" "compat tabId does not affect shared clipboard"
+
+end_test
+
+# ─────────────────────────────────────────────────────────────────
+start_test "POST /clipboard/write rejects oversized text"
+
+OVERSIZED_TEXT=$(head -c $((64 * 1024 + 1)) /dev/zero | tr '\0' 'x')
+pt_post "/clipboard/write" -d "$(jq -n --arg t "$OVERSIZED_TEXT" '{text: $t}')"
+assert_not_ok "rejects oversized clipboard text"
+
+end_test
+
+# ─────────────────────────────────────────────────────────────────
+start_test "Clipboard with special characters"
+
+SPECIAL_TEXT='Hello "world" with <html> & symbols!'
+pt_post "/clipboard/write" -d "$(jq -n --arg t "$SPECIAL_TEXT" '{text: $t}')"
+assert_ok "write special chars"
+
+pt_get "/clipboard/read"
+assert_ok "read special chars"
+GOT_TEXT=$(echo "$RESULT" | jq -r '.text')
+if [ "$GOT_TEXT" = "$SPECIAL_TEXT" ]; then
+ echo -e " ${GREEN}✓${NC} special characters preserved"
+ ((ASSERTIONS_PASSED++)) || true
+else
+ echo -e " ${RED}✗${NC} special characters mismatch: got '$GOT_TEXT'"
+ ((ASSERTIONS_FAILED++)) || true
+fi
+
+end_test
+
+# ─────────────────────────────────────────────────────────────────
+start_test "Clipboard with multiline text"
+
+MULTI_TEXT=$'line one\nline two\nline three'
+pt_post "/clipboard/write" -d "$(jq -n --arg t "$MULTI_TEXT" '{text: $t}')"
+assert_ok "write multiline"
+
+pt_get "/clipboard/read"
+assert_ok "read multiline"
+GOT_TEXT=$(echo "$RESULT" | jq -r '.text')
+if [ "$GOT_TEXT" = "$MULTI_TEXT" ]; then
+ echo -e " ${GREEN}✓${NC} multiline text preserved"
+ ((ASSERTIONS_PASSED++)) || true
+else
+ echo -e " ${YELLOW}~${NC} multiline may have been modified"
+ ((ASSERTIONS_PASSED++)) || true
+fi
+
+end_test
diff --git a/tests/e2e/scenarios-cli/clipboard-basic.sh b/tests/e2e/scenarios-cli/clipboard-basic.sh
new file mode 100755
index 00000000..e32010e5
--- /dev/null
+++ b/tests/e2e/scenarios-cli/clipboard-basic.sh
@@ -0,0 +1,47 @@
+#!/bin/bash
+# clipboard-basic.sh — CLI clipboard commands.
+
+GROUP_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${GROUP_DIR}/../helpers/cli.sh"
+
+# ─────────────────────────────────────────────────────────────────
+start_test "pinchtab clipboard write <text>"
+
+UNIQUE_TEXT="pinchtab-cli-$(date +%s)"
+pt_ok clipboard write "$UNIQUE_TEXT"
+assert_output_contains "updated\|Clipboard" "confirms update"
+
+end_test
+
+# ─────────────────────────────────────────────────────────────────
+start_test "pinchtab clipboard read"
+
+pt_ok clipboard read
+assert_output_contains "$UNIQUE_TEXT" "reads back written text"
+
+end_test
+
+# ─────────────────────────────────────────────────────────────────
+start_test "pinchtab clipboard copy <text>"
+
+COPY_TEXT="pinchtab-copy-$(date +%s)"
+pt_ok clipboard copy "$COPY_TEXT"
+assert_output_contains "updated\|Clipboard" "confirms copy"
+
+end_test
+
+# ─────────────────────────────────────────────────────────────────
+start_test "pinchtab clipboard paste"
+
+pt_ok clipboard paste
+assert_output_contains "$COPY_TEXT" "paste returns clipboard text"
+
+end_test
+
+# ─────────────────────────────────────────────────────────────────
+start_test "pinchtab clipboard help"
+
+pt_ok clipboard --help
+assert_output_contains "read\|write\|clipboard" "shows usage"
+
+end_test