archy/.planning/todos/pending/2026-08-02-companion-handover-clipboard-and-qr-web-side.md

created, title, area, severity, files

created	title	area	severity	files
2026-08-02T12:10:00.000Z	Companion 0.5.27 handover — node/web-side clipboard + QR scanner work	ui	major	neode-ui/src/main.ts (:10-24 clipboard polyfill — the fake readText is the bug) neode-ui/src/utils/clipboard.ts (to create — one util for 30 call sites) neode-ui/src/views/web5/utils.ts (:39 safeClipboardWrite — best existing base) neode-ui/src/components/WalletScanModal.vue (prewarm, torch, don't re-init between panes) docs/qr-scanner-snappiness-handover.md (three factual corrections — see below)

Problem

Handover from the companion-app workstream (build 0.5.27, versionCode 47), 2026-08-02. All of it is node-repo / neode-ui/ side — none was implemented there, the companion was the only thing changed. Captured verbatim-in-substance so it is not lost.

1. Companion now shims navigator.clipboard — do not clobber it

0.5.27 adds a native ArchipelagoClipboard bridge, injected on every page load, pointing navigator.clipboard.readText/writeText at the Android clipboard. Fixes copy and paste in-app with zero web changes, in both the kiosk WebView and the in-app browser (BTCPay, LND).

Contract to preserve:

• Shim runs at onPageStarted and onPageFinished; sets window.__archyClipboardPatched = true.
• Defines navigator.clipboard as configurable if absent, then assigns readText/writeText onto whatever object is there.
• Reads return via window.__archyClipboardResult(text).
• Do not unconditionally re-define navigator.clipboard after page load. Do not Object.freeze it. Today's main.ts polyfill is safe only because it is guarded by if (!navigator.clipboard).

2. Web-side clipboard bugs — still open, affect plain browsers

Native is fixed; the same code is broken in any plain-HTTP browser (LAN/mesh — non-secure context, so navigator.clipboard is undefined).

• neode-ui/src/main.ts:10-24 — the polyfill defines async readText() { return '' }. That makes SendBitcoinModal.vue:425's canReadClipboard true, so "Paste invoice" renders, fires, gets '', and silently does nothing. Fix: drop the fake readText (or define it only when a real source exists) so the button correctly hides.
• 30 writeText call sites, three patterns:
  • ~8 duplicate their own execCommand fallback — Server.vue:762, Apps.vue:708, Credentials.vue:392, settings/AccountInfoSection.vue, settings/TwoFactorSection.vue.
  • ~10 are bare navigator.clipboard.writeText(x).catch(() => {}) — ReceiveBitcoinModal.vue:149, SendBitcoinModal.vue:326/:574, OnboardingSeedVerify.vue:201, OnboardingDid.vue:216/:223, settings/BackupSection.vue:270, PeerFiles.vue:1110/:1415 — these show "Copied!" whether or not anything reached the clipboard.
  • views/web5/utils.ts:39 safeClipboardWrite is the best existing base.
• The execCommand fallbacks are fragile: no focus(), no readonly, no setSelectionRange, and the return value is never checked, so failure is invisible.

Suggested shape: one src/utils/clipboard.ts exporting copyText() / readText() / canPaste(), preferring native bridge → async Clipboard API → hardened execCommand, toasting "Copied" only on real success. Repoint all 30 sites at it.

Paste affordances that don't exist yet (bare textareas today): WalletScanModal.vue paste field, ecash token (views/web5/Web5SendReceiveModals.vue:160), signed PSBT, federation invite code (views/federation/JoinModal.vue:16).

3. QR scanner — web-side items still open

Native items are done in 0.5.27. Remaining on the web side:

• Pre-warm the camera — start getUserMedia when the modal opens (action pane), not when the scan pane is reached; hide the preview until needed.
• Torch toggle — qr-scanner exposes hasFlash() / turnFlashOn().
• Constraints — { focusMode: 'continuous', width: { ideal: 1280 } }.
• Don't stop/start between panes — amount → scan currently re-inits the scanner; keep the paused stream alive for the modal's lifetime.
• Already done upstream: 10 scans/sec where BarcodeDetector exists.
• New optional hook: window.ArchipelagoQr?.prewarm?.() — safe to call repeatedly, safe when absent. The companion also self-prewarms on every node page load, so this is a small extra win.

4. Corrections to docs/qr-scanner-snappiness-handover.md (fix the doc)

That doc's native section assumed ML Kit and is wrong on three points — leaving it uncorrected invites someone to "optimise" the scanner backwards:

• The native scanner uses ZXing (Apache-2.0, on-device, no telemetry), not ML Kit. ML Kit was rejected as a proprietary Google/Play-Services dependency, against project dependency policy. There is therefore no model cold-start to pay.
• FORMAT_QR_CODE-only and STRATEGY_KEEP_ONLY_LATEST were already in place before this round.
• Do not drop analysis resolution to 1280×720. 1920×1080 is a deliberate 0.5.22 fix: at 720p, dense bolt11 invoice QRs were undecodable on far-focusing lenses (e.g. Pixel 9a main) while sparse address QRs still read — that was the original "scanner doesn't pick up invoices" report.

What 0.5.27 changed natively, for the record: two-tier decode (cheap centre-70% pass ~18/s plus the thorough full-frame TRY_HARDER + inverted-retry pass ~5/s, replacing a single expensive pass capped ~7/s); camera/decoder prewarm; torch toggle in wallet-scan and pairing scanners; tap-to-focus with 4s suppression of periodic centre autofocus; zoom hunt alternating 1×/1.5× after ~3s with no decode; success haptic on first hit only (so animated QRs don't buzz per frame).

5. Not a web issue, noted for completeness

The companion regained "swipe away in recents = restart": the retained kiosk WebView (kept so remote ⇄ dashboard doesn't reload) is now released when the activity finishes, because the FIPS mesh service keeps the process alive and the static WebView was surviving the swipe. A Restart card was added to the hub menu as the manual path.

Solution

Route into Phase 11 (Wallet Experience & LND UI Parity) rather than a standalone pass — §2's signed-PSBT paste affordance and §3's scanner items are the same surface as WALLET-05 (the PSBT air-gap round trip), and WalletScanModal.vue is named in both. The clipboard utility (§2) is broader than Phase 11 and can land independently; the doc corrections (§4) are a five-minute fix that should not wait for a phase.

Supersedes any overlapping assumptions in docs/qr-scanner-snappiness-handover.md — that doc is now known-wrong on the three points in §4.