Implement clipboard and QR presentation

docs/presentation.md

@@ -0,0 +1,46 @@
+# Clipboard and QR presentation
+
+`crates/storage` owns secret-presentation lifecycle and derived QR data. The
+CLI receives an already selected `PresentationSecret` or generated password and
+only writes storage-produced status or terminal-rendering bytes. It never
+launches `xclip`, `wl-copy`, `pbcopy`, `qrencode`, an image viewer, or a shell.
+The same byte-oriented APIs are ready for pass-otp code and URI results without
+placing OTP parsing or calculation in a frontend.
+
+## Clipboard lifecycle
+
+The default clipboard lease is 45 seconds, matching upstream `pass`.
+`clipboard_timeout_seconds` may configure 1 through 300 seconds. Before copying,
+storage snapshots an existing UTF-8 clipboard value. At lease completion or
+cancellation it reads the clipboard again:
+
+- if the copied secret remains current, storage restores the previous text or
+  clears a previous empty/non-text clipboard;
+- if another application or the user supplied newer contents, storage leaves
+  those contents untouched;
+- if cleanup cannot be verified or completed, the operation returns a typed
+  cleanup failure rather than claiming success.
+
+The CLI deliberately remains alive during the lease. This lets X11 and Wayland
+serve the selection and guarantees cleanup without spawning a daemon or helper.
+Linux also marks copied text with the commonly supported password-manager hint
+to discourage clipboard-history retention. macOS uses NSPasteboard, Windows
+uses the native clipboard, and Linux uses direct X11 or Wayland data-control
+protocols through the safe `arboard` adapter. Unsupported targets return a
+typed unavailable result. Tests inject a byte-oriented backend and cover
+expiry, restore, clear, cancellation, failure, and newer-content races without
+touching the developer clipboard.
+
+## QR data
+
+`QrMatrix` encodes secret bytes with the pure-Rust `qrcode` implementation and
+returns only dimensions and dark/light module queries. Its module buffer,
+terminal rendering, and source payload all use zeroizing/redacted storage
+objects. The terminal renderer supplies the standard four-module quiet zone,
+square half-block cells, and no plaintext label or payload. Frontends can draw
+the same matrix natively without regenerating or interpreting it.
+
+Round-trip tests decode generated password, Unicode, and `otpauth://` matrices
+with the test-only `rqrr` decoder. Empty and oversized payloads are typed errors,
+and CLI tests prove `show` and `generate` clipboard/QR modes never emit their
+plaintext values.