167 lines
5.3 KiB
Markdown
167 lines
5.3 KiB
Markdown
# OpenSpec Change: enterprise-browser-clipboard
|
|
|
|
- **Change ID**: enterprise-browser-clipboard
|
|
- **Package**: `@suaveplan/clipboard`
|
|
- **Category**: browser
|
|
- **Target path**: `browser/platform/clipboard`
|
|
- **Status**: IN PROGRESS
|
|
- **Date**: 2026-04-24
|
|
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/clipboard.md`
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Deliver `@suaveplan/clipboard` on the genesis branch at enterprise quality. The package provides `ClipboardManager` with injectable `ClipboardNavigator` seam, plain-text and rich copy/read, permission probing, and `execCommand` fallback. Genesis adds image and arbitrary-blob clipboard I/O, typed errors via `@suaveplan/error`, secure-context guard, paste-event fallback, permission-change subscription, async queue for concurrent operations, OTel counters/histograms, and Playwright E2E across Chromium/WebKit/Firefox.
|
|
|
|
---
|
|
|
|
## Current-state audit (genesis)
|
|
|
|
Fresh build — does not exist on genesis yet.
|
|
|
|
---
|
|
|
|
## Available workspace deps on genesis
|
|
|
|
| Package | Role |
|
|
|---|---|
|
|
| `@suaveplan/error` (`workspace:^`) | `CLIPBOARD_API_UNAVAILABLE`, `CLIPBOARD_PERMISSION_DENIED`, etc. |
|
|
| `@suaveplan/logger` (`workspace:^`) | Structured logging |
|
|
| `@suaveplan/schema-registry` (`workspace:^`) | `ClipboardOptions` schema |
|
|
| `zod` (`catalog:forms`) | `ClipboardOptions` Zod schema |
|
|
| `@opentelemetry/api` (`catalog:observability`) | Copy/read/fallback metrics |
|
|
| `tslib` (`catalog:build`) | Runtime helpers |
|
|
|
|
Dev: `vitest`, `@vitest/coverage-istanbul`, `happy-dom`, `@playwright/test`, `@suaveplan/testing`.
|
|
|
|
---
|
|
|
|
## Preserved public API surface
|
|
|
|
```ts
|
|
class ClipboardManager {
|
|
constructor(navigator?: ClipboardNavigator)
|
|
copyText(text: string, options?: ClipboardOptions): Promise<ClipboardResult>
|
|
readText(options?: ClipboardOptions): Promise<ClipboardResult>
|
|
copyRichContent(data: ClipboardData, options?: ClipboardOptions): Promise<ClipboardResult>
|
|
readRichContent(options?: ClipboardOptions): Promise<ClipboardResult>
|
|
checkPermission(name: 'clipboard-read' | 'clipboard-write'): Promise<PermissionResult>
|
|
onPermissionChange(name: 'clipboard-read' | 'clipboard-write', cb: (s: PermissionState) => void): () => void
|
|
}
|
|
|
|
// Types
|
|
interface ClipboardData {
|
|
text?: string
|
|
html?: string
|
|
image?: Blob // new
|
|
blobs?: Record<string, Blob> // new — arbitrary MIME
|
|
}
|
|
interface ClipboardResult { success: boolean; method: 'api' | 'fallback'; payload?: ClipboardData; error?: SuaveplanError }
|
|
interface PermissionResult { state: PermissionState; supported: boolean }
|
|
```
|
|
|
|
Subpath exports: `"."`, `"./types"`.
|
|
|
|
---
|
|
|
|
## New additions for genesis
|
|
|
|
### 1. Image and arbitrary-blob clipboard I/O
|
|
|
|
`copyRichContent` and `readRichContent` accept/return `image?: Blob` and `blobs?: Record<string, Blob>` via `ClipboardItem` for modern Clipboard API.
|
|
|
|
### 2. Typed errors
|
|
|
|
`CLIPBOARD_API_UNAVAILABLE`, `CLIPBOARD_PERMISSION_DENIED`, `CLIPBOARD_FALLBACK_FAILED`, `CLIPBOARD_INSECURE_CONTEXT` — all extend `@suaveplan/error`.
|
|
|
|
### 3. Secure-context guard
|
|
|
|
`requireSecureContext()` probes `window.isSecureContext`; throws `CLIPBOARD_INSECURE_CONTEXT` outside HTTPS/localhost before attempting clipboard access.
|
|
|
|
### 4. Paste-event fallback
|
|
|
|
`readText` in non-API contexts orchestrates focus + `paste` event capture as best-effort fallback.
|
|
|
|
### 5. Permission-change subscription
|
|
|
|
`onPermissionChange(name, cb)` using `PermissionStatus.onchange`; returns unsubscribe function.
|
|
|
|
### 6. Async operation queue
|
|
|
|
Concurrent `copy`/`read` calls are serialized via an internal queue to prevent "Document is not focused" races.
|
|
|
|
### 7. Focus-aware retry
|
|
|
|
When `Document is not focused` error fires, waits for the next focus event and retries once.
|
|
|
|
### 8. Error codes
|
|
|
|
`CLIPBOARD_API_UNAVAILABLE`, `CLIPBOARD_PERMISSION_DENIED`, `CLIPBOARD_FALLBACK_FAILED`, `CLIPBOARD_INSECURE_CONTEXT`.
|
|
|
|
### 9. OTel metrics
|
|
|
|
Counter `clipboard.copy_total{method}`, counter `clipboard.read_total{method}`, counter `clipboard.fallback_used_total`, counter `clipboard.error_total{code}`, histogram `clipboard.op_latency_ms`.
|
|
|
|
---
|
|
|
|
## File layout
|
|
|
|
```text
|
|
browser/platform/clipboard/
|
|
package.json
|
|
tsconfig.json
|
|
vitest.config.ts
|
|
src/
|
|
index.ts
|
|
error-codes.ts
|
|
clipboard/
|
|
clipboard/
|
|
clipboard.ts (ClipboardManager, ≤250 lines)
|
|
clipboard.test.ts
|
|
clipboard.md
|
|
clipboard.types.ts
|
|
index.ts
|
|
queue/
|
|
queue.ts (async operation serializer)
|
|
queue.test.ts
|
|
queue.md
|
|
index.ts
|
|
fallback/
|
|
fallback.ts (execCommand + paste-event fallback)
|
|
fallback.test.ts
|
|
fallback.md
|
|
index.ts
|
|
telemetry/
|
|
metrics/
|
|
metrics.ts
|
|
metrics.md
|
|
index.ts
|
|
types/
|
|
types/
|
|
types.ts
|
|
types.md
|
|
index.ts
|
|
schema/
|
|
clipboard-schema/
|
|
clipboard-schema.ts
|
|
clipboard-schema.md
|
|
index.ts
|
|
constants/
|
|
index.ts
|
|
tests/
|
|
integration.test.ts
|
|
e2e/
|
|
clipboard.spec.ts (Chromium/WebKit/Firefox: text, image, permissions)
|
|
```
|
|
|
|
---
|
|
|
|
## Impact
|
|
|
|
**Downstream**: any Suaveplan browser app using clipboard operations.
|
|
|
|
**Breaking changes**: None — all additions are additive. Error types changed from bare strings to `SuaveplanError` (structured), but result shape is unchanged.
|
|
|
|
**Prerequisites**: `@suaveplan/error`, `@suaveplan/logger` on Verdaccio.
|