# @suaveplan/clipboard - Enterprise Clipboard API abstraction: typed errors, OTel metrics, async queue serializer, secure-context guard, image/blob copy + read, paste-event read fallback, permission change subscription, focus-aware retry, sanitizer hook. Browser-tier, zero @suaveplan/* runtime deps beyond error + opentelemetry + types.

Enterprise Clipboard API abstraction for browser-tier consumers. Wraps the
async Clipboard API with a textarea + `execCommand` fallback, a paste-event
read fallback, image / blob copy + read via `ClipboardItem`, FIFO
serialization, secure-context guard, permission change subscription,
focus-aware retry, optional HTML sanitizer, structured errors via
`@suaveplan/error`, and OpenTelemetry instrumentation.

<!-- begin:auto-docs -->
## Documentation tree

- [errors](./src/errors/errors.md) — Stable error code registry, per-code metadata, and the concrete `ClipboardError` class for the `@suaveplan/clipboard` p…
  - [errors](./src/errors/errors.md) — Stable error code registry, per-code metadata, and the concrete `ClipboardError` class for the `@suaveplan/clipboard` p…
- [fallback](./src/fallback/fallback.md) — Legacy clipboard fallback paths used when `navigator.clipboard` is unavailable or rejects. Provides a hidden-textarea +…
  - [fallback](./src/fallback/fallback.md) — Legacy clipboard fallback paths used when `navigator.clipboard` is unavailable or rejects. Provides a hidden-textarea +…
- [manager](./src/manager/manager.md) — `ClipboardManager` is the orchestrator class for `@suaveplan/clipboard`. It composes the navigator + window seams, the…
  - [helpers](./src/manager/helpers.md) — Pure helpers shared between `manager.ts` and `operations.ts`. Keeps both files under the line budget by housing the nav…
  - [manager](./src/manager/manager.md) — `ClipboardManager` is the orchestrator class for `@suaveplan/clipboard`. It composes the navigator + window seams, the…
  - [operations](./src/manager/operations.md) — Pure operation functions invoked by `ClipboardManager`. Each function takes an `OperationContext` (navigator, window, o…
- [observability](./src/observability/observability.md) — OpenTelemetry instrumentation bundle for `@suaveplan/clipboard`. Wires four counters and one histogram on a single `Met…
  - [observability](./src/observability/observability.md) — OpenTelemetry instrumentation bundle for `@suaveplan/clipboard`. Wires four counters and one histogram on a single `Met…
- [permissions](./src/permissions/permissions.md) — Probe and subscribe to clipboard permission state via the browser's Permissions API. `checkPermissions` returns a snaps…
  - [permissions](./src/permissions/permissions.md) — Probe and subscribe to clipboard permission state via the browser's Permissions API. `checkPermissions` returns a snaps…
- [queue](./src/queue/queue.md) — `AsyncQueue` is a minimal FIFO asynchronous queue that serializes operations on a single tail promise. The `ClipboardMa…
  - [queue](./src/queue/queue.md) — `AsyncQueue` is a minimal FIFO asynchronous queue that serializes operations on a single tail promise. The `ClipboardMa…
- [sanitizer](./src/sanitizer/sanitizer.md) — Sanitizer hooks applied to inbound `text/html` clipboard payloads. The package ships an identity sanitizer (pass-throug…
  - [sanitizer](./src/sanitizer/sanitizer.md) — Sanitizer hooks applied to inbound `text/html` clipboard payloads. The package ships an identity sanitizer (pass-throug…
- [security](./src/security/security.md) — Browser-side security helpers that guard clipboard operations against insecure contexts and orchestrate the focus-aware…
  - [security](./src/security/security.md) — Browser-side security helpers that guard clipboard operations against insecure contexts and orchestrate the focus-aware…
<!-- end:auto-docs -->

## Install

```bash
bun add @suaveplan/clipboard
```

## Quick start

```ts
import { ClipboardManager } from "@suaveplan/clipboard";

const clipboard = new ClipboardManager({
    useFallback: true,
    requireSecureContext: false,
    serialize: true,
});

const result = await clipboard.copyText("hello");
if (!result.success) {
    console.error("copy failed:", result.code, result.error);
}
```

## Modules

- [`manager/manager.md`](./src/manager/manager.md) — `ClipboardManager`, the orchestrator.
- [`manager/helpers.md`](./src/manager/helpers.md) — internal helpers used by the manager.
- [`manager/operations.md`](./src/manager/operations.md) — pure operation functions.
- [`errors/errors.md`](./src/errors/errors.md) — `CLIPBOARD_CODES`, `ClipboardError`, metadata.
- [`fallback/fallback.md`](./src/fallback/fallback.md) — textarea + paste-event fallback paths.
- [`observability/observability.md`](./src/observability/observability.md) — OpenTelemetry counters + histogram.
- [`permissions/permissions.md`](./src/permissions/permissions.md) — permission probe + change subscription.
- [`queue/queue.md`](./src/queue/queue.md) — `AsyncQueue` FIFO serializer.
- [`sanitizer/sanitizer.md`](./src/sanitizer/sanitizer.md) — sanitizer interface + helpers.
- [`security/security.md`](./src/security/security.md) — secure-context guards + focus utilities.

## Features

- Copy plain text, HTML, images, and arbitrary MIME blobs.
- Read plain text and rich content with optional HTML sanitization.
- Paste-event fallback when `navigator.clipboard.readText` is unavailable.
- Permission probe + live subscription (`onPermissionChange`).
- Async FIFO queue so concurrent calls execute in arrival order.
- Secure-context guard with typed error code (`CLIPBOARD.INSECURE_CONTEXT`).
- Focus-aware retry on `NotAllowedError: Document is not focused`.
- Eight stable error codes under the `CLIPBOARD.*` namespace.
- Five OpenTelemetry instruments wired into every public method.
- SSR-safe — graceful degradation when `document` / `navigator` / `window` are undefined.

## Error codes

`CLIPBOARD.API_UNAVAILABLE`, `CLIPBOARD.PERMISSION_DENIED`,
`CLIPBOARD.FALLBACK_FAILED`, `CLIPBOARD.INSECURE_CONTEXT`,
`CLIPBOARD.NO_CONTENT`, `CLIPBOARD.READ_FAILED`,
`CLIPBOARD.DOCUMENT_UNAVAILABLE`, `CLIPBOARD.QUEUE_DRAINED`.

## License

MIT