chore: version bump 4.0.2 → 4.0.3 + build — desktop helper pairing; trash integrated DESKTOP-PAIRING drafts (v4.0.3)

@@ -1,151 +0,0 @@1-# Change 1 — Add `vault_id` to the PAIR_IDENTITY frame2-3-> **DRAFT.** Conforms to `_GROUND-TRUTH.md`. Target file:4-> `/Users/june/projects/peach-browser/src/shared/chirp-handshake.ts`.5-6-## Goal7-Have the extension **send** `vault_id` in the `PAIR_IDENTITY` frame so the8-desktop helper can persist which vault it was paired to. peach-sync already9-accepts `vault_id` as an **optional** field10-(`peach-sync/src/pairing.zig:54`, tolerated/ignored when absent), so this is11-purely additive and backwards-compatible.12-13-## Backwards-compatibility statement14-- `vault_id` is `?[]const u8 = null` in peach-sync and parsed with15-  `ignore_unknown_fields` (`pairing.zig:54,57,167`); it is consumed defensively16-  (`orelse ""`, persisted only when non-empty — `pairing.zig:209,212-214`).17-- Existing chirp peers (mobile Android/iOS) that **omit** `vault_id` keep18-  working unchanged — the field is optional on both the TS interface and the19-  helper struct.20-- The helper does not send `vault_id` back (`pairing.zig:173-180`), so the21-  extension's `decodeFrame` does not require it on receive. The patch below only22-  affects the OUTBOUND frame.23-24-## Privacy consideration (carry the existing note forward)25-`vault_id` is the same stable, LAN-broadcast identifier documented at26-`src/shared/sync-identity.ts:62-74` (PRIVACY NOTE / PCH-02-006): it is stable27-across sessions and lets a passive LAN observer link every device sharing a28-vault. Putting it in `PAIR_IDENTITY` keeps it inside the **encrypted** NK29-transport, so this change does not add network exposure beyond what mDNS sync30-discovery already leaks. The patch comment references that note rather than31-restating it.32-33-## Threading: where `vault_id` enters the handshake34-`computeVaultId` is async and needs the in-memory `masterKey`35-(`sync-identity.ts:75-82`), neither of which is in scope inside36-`runPairingInitiator`/`runPairingResponder`. The clean seam is the existing37-`LocalIdentity` argument already passed into both functions: add an optional38-`vaultId` field, computed by the caller that already holds the master key (the39-pairing-flow entry point in the popup/background that builds `LocalIdentity`).40-No master key is introduced into `chirp-handshake.ts`.41-42-- Caller obligation (documented, not patched here): the code that constructs43-  `LocalIdentity` for pairing must call44-  `vaultId = await computeVaultId(masterKey)` (`sync-identity.ts:75`) and set it45-  on the identity. If the caller has no master key (locked vault), it leaves46-  `vaultId` undefined and the field is omitted — still valid.47-48----49-50-## Patch (apply to `src/shared/chirp-handshake.ts`)51-52-### Hunk A — extend `LocalIdentity` with optional `vaultId`53-Context: lines 43-51.54-```diff55- export interface LocalIdentity {56-   deviceId: string;57-   deviceName: string;58-   deviceType: DeviceType;59-   longTermPublicKeyHex: string;60-   signingPublicKeyHex?: string;61-   /** Server-only field — Android/iOS/desktop sync hosts announce their port. */62-   wsPort?: number;63-+  /**64-+   * Stable per-vault id (`computeVaultId`, sync-identity.ts). Sent in the65-+   * outbound PAIR_IDENTITY so a desktop helper can record which vault it66-+   * paired to. Optional: the caller omits it when the vault is locked (no67-+   * master key). Privacy: this is the LAN-linkable id — see the PRIVACY NOTE68-+   * at sync-identity.ts:62 (PCH-02-006).69-+   */70-+  vaultId?: string;71- }72-```73-74-### Hunk B — add `vault_id` to the `PairingFrame` interface75-Context: lines 53-61.76-```diff77- interface PairingFrame {78-   type: "PAIR_IDENTITY";79-   device_id: string;80-   device_name: string;81-   device_type: DeviceType;82-   long_term_public_key_hex: string;83-   signing_public_key_hex?: string;84-   ws_port?: number;85-+  // Optional: present only when the sender knows its vault id. peach-sync86-+  // treats this as optional (pairing.zig:54); chirp mobile peers omit it.87-+  vault_id?: string;88- }89-```90-91-### Hunk C — emit `vault_id` from the INITIATOR frame92-Context: lines 106-114 (`runPairingInitiator`).93-```diff94-   const ourFrame = encodeFrame({95-     type: "PAIR_IDENTITY",96-     device_id: ourIdentity.deviceId,97-     device_name: ourIdentity.deviceName,98-     device_type: ourIdentity.deviceType,99-     long_term_public_key_hex: ourIdentity.longTermPublicKeyHex,100-     signing_public_key_hex: ourIdentity.signingPublicKeyHex,101-     ws_port: ourIdentity.wsPort,102-+    vault_id: ourIdentity.vaultId,103-   });104-```105-106-### Hunk D — emit `vault_id` from the RESPONDER frame107-Context: lines 209-217 (`runPairingResponder`).108-```diff109-   const ourFrame = encodeFrame({110-     type: "PAIR_IDENTITY",111-     device_id: ourIdentity.deviceId,112-     device_name: ourIdentity.deviceName,113-     device_type: ourIdentity.deviceType,114-     long_term_public_key_hex: ourIdentity.longTermPublicKeyHex,115-     signing_public_key_hex: ourIdentity.signingPublicKeyHex,116-     ws_port: ourIdentity.wsPort,117-+    vault_id: ourIdentity.vaultId,118-   });119-```120-121-> `encodeFrame` is `JSON.stringify` (line 63-65): when `vaultId` is `undefined`,122-> `JSON.stringify` **drops the key entirely**, so the omitted-field123-> backwards-compat behaviour is automatic — no extra guard needed.124-125-### (Optional) Hunk E — validate `vault_id` on decode if present126-`decodeFrame` (lines 67-85) currently ignores extra fields. The helper never127-sends `vault_id`, so receive-side validation is **not required** for desktop128-pairing. If a future symmetric flow has the peer send it, add a lenient guard:129-```diff130-   if (131-     parsed.signing_public_key_hex !== undefined &&132-     !/^[0-9a-f]{64}$/.test(parsed.signing_public_key_hex)133-   ) {134-     throw new Error("signing_public_key_hex is not 32-byte hex");135-   }136-+  // vault_id, when present, is a 64-char lowercase hex BLAKE3 digest137-+  // (computeVaultId). Lenient: only validate shape if the peer sent one.138-+  if (parsed.vault_id !== undefined && !/^[0-9a-f]{64}$/.test(parsed.vault_id)) {139-+    throw new Error("vault_id is not 32-byte hex");140-+  }141-   return parsed as PairingFrame;142-```143-**Recommendation:** ship Hunks A–D only for the desktop-pairing milestone; defer144-Hunk E until a peer actually sends `vault_id`, to avoid over-constraining.145-146-## Notes for the implementer147-- `vault_id` format is the 64-char lowercase hex BLAKE3 output of148-  `computeVaultId` (`sync-identity.ts:28,81`). Keep it lowercase hex to match149-  `SYNC_HELLO`'s `vaultId` so the helper's later vault check150-  (`sync_coordinator.zig:141`) compares equal.151-- Do not log `vault_id`. It is the LAN-linkable id (privacy note above).

@@ -1,66 +0,0 @@1-# Change 2 — Add `"desktop"` DeviceType2-3-> **DRAFT.** Conforms to `_GROUND-TRUTH.md`.4-5-## VERDICT: already done. This change is a NO-OP against current source.6-7-The brief assumed `"desktop"` was missing from `DeviceType` and that the type8-"likely" lives in `src/shared/types.ts`. **Both assumptions are wrong against the9-ground-truth source:**10-11-1. `DeviceType` is defined in **`src/shared/sync-types.ts:11`**, not `types.ts`12-   (`types.ts` has no `DeviceType` symbol). `chirp-handshake.ts:29` and13-   `paired-devices.ts:23` both import device types from `./sync-types`.14-15-2. `"desktop"` is **already a member**:16-   ```ts17-   // src/shared/sync-types.ts:1118-   export type DeviceType = "extension" | "android" | "ios" | "desktop";19-   ```20-21-3. The full desktop plumbing already exists:22-   - `DEVICE_TYPE_DESKTOP = 0x04` chirp byte tag (`sync-types.ts:19`)23-   - `DeviceTypeByte` includes it (`sync-types.ts:25`)24-   - `deviceTypeFromByte(0x04) → "desktop"` (`sync-types.ts:36`)25-   - `deviceTypeToByte("desktop") → 0x04` (`sync-types.ts:45`)26-   - `chirp-payload.ts` accepts byte `0x04` on the wire (`chirp-payload.ts:5,89`)27-28-4. peach-sync announces exactly this string: `.device_type = "desktop"`29-   (`peach-sync/src/pairing.zig:177`), which lands on the existing union member.30-31-**No edit to the type union is required.** If a downstream pass "adds" it again32-it will be a redundant no-op.33-34----35-36-## What ACTUALLY needs verifying: the storage gate (`paired-devices.ts`)37-38-The real question is whether the paired-device registry rejects a `"desktop"`39-device. **It does not — there is no enum gate.**40-41-`upsertPairedDevice` (`src/background/paired-devices.ts:56-70`) validates only42-*presence*, never membership against the `DeviceType` union:43-```ts44-// paired-devices.ts:6045-if (!device.deviceType) throw new Error("device.deviceType is required");46-```47-It checks the field is truthy, not that it equals a known literal. `"desktop"`48-(or any non-empty string) passes. Storage round-trips it verbatim49-(`isPairedDevice`, `paired-devices.ts:174-180`, only checks `deviceId` is a50-non-empty string and `pairedAt` is a number — `deviceType` is not gated).51-52-`PairedDevice.deviceType` is `DeviceType | undefined` (`sync-types.ts:89`), so53-`"desktop"` is statically valid; nothing to extend.54-55-### Conclusion / action for implementer56-- **No code change for Change 2.** Optionally, add a regression test asserting a57-  `"desktop"` device upserts and round-trips through `paired-devices.ts`58-  (kept minimal; the registry already supports it).59-- If the brief's reviewer insists on a literal "edit", the only honest one is a60-  doc/comment — there is no missing union member and no gate to widen.61-62-## Discrepancy summary (for the report)63-- Brief said: add `"desktop"` to `DeviceType` in `src/shared/types.ts`.64-- Source truth: `"desktop"` already present in `src/shared/sync-types.ts:11`;65-  `types.ts` is the wrong file; the storage layer already accepts it. **Change is66-  unnecessary.**

@@ -1,435 +0,0 @@1-# Change 3 — Desktop helper pairing handler2-3-> **DRAFT.** Conforms to `_GROUND-TRUTH.md`. Proposed new module:4-> `/Users/june/projects/peach-browser/src/background/desktop-pairing.ts`.5-> Reuses Change 1 (`vault_id` in `PAIR_IDENTITY`) and Change 5 (plain6-> port probe). Nothing here is applied — it is an apply-ready draft.7-8-## What this change adds9-10-A net-new browser-side **code pairing** client. The existing11-`chirp-handshake.ts` only implements the *audio chirp* NK flow where the12-**extension is the NK responder**. Desktop pairing is the OPPOSITE: the13-**browser is the NK initiator** against the helper's ephemeral key learned14-from `PEACH_HELLO_ACK` (`_GROUND-TRUTH.md` §3).15-16-## Verified dependencies (real exported symbols)17-18-| Need | Symbol | Location |19-| --- | --- | --- |20-| NK initiator primitive | `noiseNKInitiator(responderStaticPublicKey, send, receive)` | `src/shared/noise-js.ts:71` |21-| SAS derivation (REUSE) | `derivePairingSAS(handshakeHash: Uint8Array): string` | `src/shared/chirp-handshake.ts:171` |22-| Persist paired device | `upsertPairedDevice(device: PairedDevice)` | `src/background/paired-devices.ts:56` |23-| Cache peer IP (optional) | `setLastKnownIp(pubkeyHex, ip)` | `src/background/paired-devices.ts:120` |24-| Build local identity | `buildLocalIdentity(masterKey): Promise<LocalChirpIdentity>` | `src/background/chirp-identity.ts:79` |25-| Vault id for `vault_id` | `computeVaultId(masterKey): Promise<string>` | `src/shared/sync-identity.ts:75` |26-| Root key (for masterKey) | `getRootKeyHex()` / `isUnlocked()` | `src/background/vault.ts` (used at `messages.ts:1324`) |27-| Plain port probe (Change 5) | `probeSubnetForPort(subnet, port, opts?)` | `src/background/desktop-pairing-probe.ts` (NEW — see `05-subnet-probe.md`) |28-| PairedDevice / DeviceType | `PairedDevice`, `DeviceType` | `src/shared/sync-types.ts:86,11` (`"desktop"` already a member) |29-30-> **Why not reuse `probeSubnetForPeer`?** It is already port-parameterized31-> (`chirp-sync-transport.ts:238`), BUT it runs a full **Noise XX** handshake32-> against an *expected long-term pubkey* per host. In code pairing we have no33-> long-term pubkey yet (we only get the helper's *ephemeral* key, after the34-> plaintext HELLO). So Change 5 supplies a lighter "is there a WebSocket35-> server on this port" probe. See `05-subnet-probe.md`.36-37-## The PEACH_HELLO / PEACH_HELLO_ACK frames (PINNED, see §6 of ground truth)38-39-```ts40-interface PeachHelloFrame { type: "PEACH_HELLO"; code: string; }41-interface PeachHelloAck   { type: "PEACH_HELLO_ACK"; ephemeralPublicKeyHex: string; }42-```43-44-There is **no** error/OK frame. After sending `PEACH_HELLO`, the browser45-expects EITHER a `PEACH_HELLO_ACK` binary frame OR the socket to close.46-Socket close before an ACK ⇒ wrong/expired code ⇒ `onError("invalid_code")`.47-48-## Transport notes (from ground truth §1)49-50-- Port **49142** (pairing). The persistent sync port arrives inside the51-  encrypted `PAIR_IDENTITY` as `ws_port` (helper always announces `8765`).52-- WebSocket over TCP, **binary frames only**, one Noise (or one JSON) frame53-  per WS binary message. The browser `WebSocket` client masks frames54-  automatically — no manual masking needed on this side.55-- Pre-handshake HELLO/ACK frames are PLAINTEXT JSON, sent as binary WS56-  messages (`new TextEncoder().encode(JSON.stringify(...))`).57-58----59-60-## Apply-ready module — `src/background/desktop-pairing.ts`61-62-```ts63-// Desktop helper code-pairing client (Change 3).64-//65-// Pairs the extension with the `peach-sync` desktop helper:66-//   1. probe the /24 for a host accepting WebSocket on the pairing port67-//   2. open ws://<host>:4914268-//   3. send PEACH_HELLO { code } in PLAINTEXT69-//   4. await PEACH_HELLO_ACK { ephemeralPublicKeyHex } OR socket close70-//        (socket close before ACK == wrong/expired code — peach-sync sends71-//         NO error frame; it silently closes and rotates the code)72-//   5. run Noise NK as INITIATOR against the helper's ephemeral key73-//   6. exchange PAIR_IDENTITY (send ours incl. vault_id, then read theirs)74-//   7. derive the SAS, surface it for user confirmation75-//   8. on confirm -> persist the PairedDevice (deviceType "desktop"); on76-//        reject -> abort without persisting77-//78-// ROLE: the BROWSER is the NK INITIATOR here — the OPPOSITE of the audio79-// chirp flow (chirp-handshake.ts), where the extension is the responder.80-// The helper's `ephemeralPublicKeyHex` is the NK responder static `s`.81-82-import { noiseNKInitiator } from "../shared/noise-js";83-import { derivePairingSAS } from "../shared/chirp-handshake";84-import type { LocalIdentity } from "../shared/chirp-handshake";85-import type { DeviceType, PairedDevice } from "../shared/sync-types";86-87-/** The pairing-only port peach-sync listens on while `peach-sync pair` runs. */88-export const DESKTOP_PAIRING_PORT = 49142;89-/** Default sync port the helper announces; used when ws_port is absent. */90-const DEFAULT_SYNC_PORT = 8765;91-92-export type DesktopPairingError =93-  | "invalid_code"      // socket closed before PEACH_HELLO_ACK (wrong/expired)94-  | "no_host_found"     // no WebSocket server answered on the pairing port95-  | "handshake_failed"  // Noise NK / PAIR_IDENTITY decode failed96-  | "sas_mismatch"      // user rejected the SAS97-  | "vault_locked";     // no master key available98-99-/**100- * Minimal binary WebSocket transport seam. Production wires the real101- * `WebSocket`; tests inject a fake. One binary message per frame.102- */103-export interface DesktopPairingSocket {104-  send(bytes: Uint8Array): void;105-  /** Resolves with the next inbound binary frame, or rejects on close. */106-  receive(): Promise<Uint8Array>;107-  close(): void;108-  /** Resolves true if the socket closed before the next frame arrived. */109-  closedBeforeFrame(): boolean;110-}111-112-export interface DesktopPairingDeps {113-  /** Change 5 — find a host answering WebSocket on the pairing port. */114-  findHost(port: number): Promise<string | null>;115-  /** Open a binary WebSocket to ws://<ip>:<port>/ . */116-  openSocket(ip: string, port: number): Promise<DesktopPairingSocket>;117-  /** Public identity for our outbound PAIR_IDENTITY (incl. vaultId). */118-  getLocalIdentity(): Promise<LocalIdentity>;119-  /** Persist on user confirm. */120-  persistDevice(device: PairedDevice): Promise<void>;121-  /** Optional fast-path cache for the next sync round. */122-  cacheLastKnownIp?(pubkeyHex: string, ip: string): Promise<void>;123-}124-125-export interface PairWithDesktopCallbacks {126-  /** Show the 6-digit SAS; the popup must compare against the helper's. */127-  onSasReady(sas: string): void;128-  /** Pairing succeeded and the device was persisted. */129-  onComplete(device: PairedDevice): void;130-  /** Pairing failed at some stage. */131-  onError(error: DesktopPairingError): void;132-}133-134-interface PairingFrame {135-  type: "PAIR_IDENTITY";136-  device_id: string;137-  device_name: string;138-  device_type: DeviceType;139-  long_term_public_key_hex: string;140-  signing_public_key_hex?: string;141-  ws_port?: number;142-  vault_id?: string; // Change 1 — additive, optional143-}144-145-function encodeJson(obj: unknown): Uint8Array {146-  return new TextEncoder().encode(JSON.stringify(obj));147-}148-149-function decodeJson<T>(bytes: Uint8Array): T {150-  return JSON.parse(new TextDecoder().decode(bytes)) as T;151-}152-153-function hexToBytes(hex: string): Uint8Array {154-  if (!/^[0-9a-f]{64}$/.test(hex)) throw new Error("expected 64-char lowercase hex");155-  const out = new Uint8Array(32);156-  for (let i = 0; i < 32; i++) out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);157-  return out;158-}159-160-function decodePairIdentity(bytes: Uint8Array): PairingFrame {161-  const p = decodeJson<Record<string, unknown>>(bytes);162-  if (p?.type !== "PAIR_IDENTITY") throw new Error("expected PAIR_IDENTITY");163-  if (typeof p.device_id !== "string" || !p.device_id) throw new Error("device_id missing");164-  if (typeof p.device_name !== "string") throw new Error("device_name missing");165-  if (typeof p.device_type !== "string") throw new Error("device_type missing");166-  if (typeof p.long_term_public_key_hex !== "string" ||167-      !/^[0-9a-f]{64}$/.test(p.long_term_public_key_hex)) {168-    throw new Error("long_term_public_key_hex is not 32-byte hex");169-  }170-  return p as unknown as PairingFrame;171-}172-173-/**174- * Drive a complete desktop-helper code pairing.175- *176- * `confirm` is a function the caller resolves AFTER the user has compared177- * the SAS shown here against the SAS the helper displays. Resolving false178- * (or rejecting) aborts before any device is persisted — this is the179- * out-of-band MITM defence (see SECURITY note in chirp-handshake.ts).180- */181-export async function pairWithDesktopHelper(182-  code: string,183-  cb: PairWithDesktopCallbacks,184-  deps: DesktopPairingDeps,185-  confirm: (sas: string) => Promise<boolean>,186-): Promise<void> {187-  // The helper compares the code byte-for-byte against a [6]u8. Normalise to188-  // exactly 6 ASCII digits, zero-padded, no separators (ground truth §2).189-  const normalizedCode = String(code).replace(/\D/g, "").padStart(6, "0").slice(-6);190-191-  let identity: LocalIdentity;192-  try {193-    identity = await deps.getLocalIdentity();194-  } catch {195-    cb.onError("vault_locked");196-    return;197-  }198-199-  // 1) Find a host on the pairing port.200-  const host = await deps.findHost(DESKTOP_PAIRING_PORT);201-  if (!host) {202-    cb.onError("no_host_found");203-    return;204-  }205-206-  // 2) Open the WebSocket.207-  let sock: DesktopPairingSocket;208-  try {209-    sock = await deps.openSocket(host, DESKTOP_PAIRING_PORT);210-  } catch {211-    cb.onError("no_host_found");212-    return;213-  }214-215-  try {216-    // 3) Send PEACH_HELLO (PLAINTEXT binary frame).217-    sock.send(encodeJson({ type: "PEACH_HELLO", code: normalizedCode }));218-219-    // 4) Await PEACH_HELLO_ACK OR socket close.220-    //    peach-sync sends NO error frame; a wrong/expired code closes the221-    //    socket. So "receive() rejected / closed before a frame" == invalid_code.222-    let ackBytes: Uint8Array;223-    try {224-      ackBytes = await sock.receive();225-    } catch {226-      cb.onError("invalid_code");227-      return;228-    }229-    if (sock.closedBeforeFrame() || ackBytes.length === 0) {230-      cb.onError("invalid_code");231-      return;232-    }233-234-    let ephemeralPublicKeyHex: string;235-    try {236-      const ack = decodeJson<{ type?: string; ephemeralPublicKeyHex?: string }>(ackBytes);237-      if (ack.type !== "PEACH_HELLO_ACK" || typeof ack.ephemeralPublicKeyHex !== "string") {238-        // A non-ACK frame on a matching code should not happen; treat the239-        // missing ACK exactly like a wrong code.240-        cb.onError("invalid_code");241-        return;242-      }243-      ephemeralPublicKeyHex = ack.ephemeralPublicKeyHex;244-    } catch {245-      cb.onError("invalid_code");246-      return;247-    }248-249-    // 5) Noise NK as INITIATOR against the helper's ephemeral static key.250-    const responderStatic = hexToBytes(ephemeralPublicKeyHex);251-    const session = await noiseNKInitiator(252-      responderStatic,253-      async (msg) => sock.send(msg),254-      () => sock.receive(),255-    );256-257-    // 6) Exchange PAIR_IDENTITY — initiator (browser) sends FIRST, then reads.258-    const ourFrame: PairingFrame = {259-      type: "PAIR_IDENTITY",260-      device_id: identity.deviceId,261-      device_name: identity.deviceName,262-      device_type: identity.deviceType,263-      long_term_public_key_hex: identity.longTermPublicKeyHex,264-      signing_public_key_hex: identity.signingPublicKeyHex,265-      ws_port: identity.wsPort,266-      vault_id: identity.vaultId, // Change 1267-    };268-    sock.send(session.encrypt(encodeJson(ourFrame)));269-270-    const theirCipher = await sock.receive();271-    const theirFrame = decodePairIdentity(session.decrypt(theirCipher));272-273-    // 7) Derive the SAS (REUSED — same value the helper computes from the274-    //    shared handshake hash) and surface it for user confirmation.275-    const sas = derivePairingSAS(session.handshakeHash);276-    cb.onSasReady(sas);277-278-    const confirmed = await confirm(sas);279-    if (!confirmed) {280-      cb.onError("sas_mismatch");281-      return;282-    }283-284-    // 8) Persist. deviceType "desktop"; ws_port from the helper frame,285-    //    defaulting to 8765 (the helper always announces 8765, but guard it).286-    const device: PairedDevice = {287-      deviceId: theirFrame.device_id,288-      deviceName: theirFrame.device_name,289-      deviceType: (theirFrame.device_type as DeviceType) || "desktop",290-      longTermPublicKeyHex: theirFrame.long_term_public_key_hex,291-      signingPublicKeyHex: theirFrame.signing_public_key_hex,292-      trustSource: "direct",293-      wsPort: typeof theirFrame.ws_port === "number" ? theirFrame.ws_port : DEFAULT_SYNC_PORT,294-      pairedAt: Date.now(),295-    };296-    await deps.persistDevice(device);297-    if (deps.cacheLastKnownIp && device.longTermPublicKeyHex) {298-      await deps.cacheLastKnownIp(device.longTermPublicKeyHex, host).catch(() => undefined);299-    }300-    cb.onComplete(device);301-  } catch {302-    cb.onError("handshake_failed");303-  } finally {304-    sock.close();305-  }306-}307-```308-309-### Production deps factory (sketch — lives alongside or in the wiring layer)310-311-```ts312-import { upsertPairedDevice, setLastKnownIp } from "./paired-devices";313-import { buildLocalIdentity } from "./chirp-identity";314-import { computeVaultId } from "../shared/sync-identity";315-import { getRootKeyHex, isUnlocked } from "./vault";316-import { probeSubnetForPort } from "./desktop-pairing-probe"; // Change 5317-import { getLocalSubnet } from "../shared/local-network";318-319-export function productionDesktopPairingDeps(): DesktopPairingDeps {320-  return {321-    async findHost(port) {322-      const subnet = await getLocalSubnet();323-      if (!subnet) return null;324-      return probeSubnetForPort(subnet, port);325-    },326-    async openSocket(ip, port) {327-      return openBinaryWebSocket(ip, port); // small wrapper around WebSocket328-    },329-    async getLocalIdentity() {330-      if (!isUnlocked()) throw new Error("vault_locked");331-      const masterKeyHex = getRootKeyHex();332-      if (!masterKeyHex) throw new Error("vault_locked");333-      const masterKey = hexToBytesLocal(masterKeyHex);334-      try {335-        const base = await buildLocalIdentity(masterKey);   // chirp-identity.ts:79336-        const vaultId = await computeVaultId(masterKey);     // sync-identity.ts:75337-        return { ...base, vaultId };                          // LocalIdentity + Change-1 field338-      } finally {339-        masterKey.fill(0);340-      }341-    },342-    persistDevice: (d) => upsertPairedDevice(d),343-    cacheLastKnownIp: (pubkeyHex, ip) => setLastKnownIp(pubkeyHex, ip),344-  };345-}346-```347-348----349-350-## Threading note — where new state comes from (mirrors Change 1)351-352-`LocalIdentity.vaultId` (added in Change 1) is **not** populated by353-`buildLocalIdentity` (`chirp-identity.ts:79` returns no `vaultId`). The354-production deps factory above threads it in:355-356-- `masterKey` is obtained the same way `CHIRP_GET_LOCAL_IDENTITY` does it357-  (`messages.ts:1324-1326`): `getRootKeyHex()` → `unhexBytes` → `masterKey.fill(0)`358-  in `finally`. **Use the stable ROOT key, not the password-derived key**359-  (SEV-2-B), so pairing survives a master-password change.360-- `vaultId = await computeVaultId(masterKey)` (`sync-identity.ts:75`).361-- Both are zeroed after use.362-363-**INTEGRATOR TODO:** `buildLocalIdentity` returns `LocalChirpIdentity`, whose364-shape matches `LocalIdentity` minus `vaultId`/`wsPort`. Confirm the two types365-are assignable, or add `vaultId?` to `LocalChirpIdentity` directly so the366-spread is type-clean. The extension has no `wsPort` (it is never a sync host),367-so leaving `wsPort` undefined is correct.368-369----370-371-## Wiring — popup ⇄ background372-373-The handshake needs `getUserMedia`-free crypto only, so it CAN run entirely374-in the background service worker (unlike the audio chirp flow, which must run375-in the popup). Recommended split: **the background runs the whole pairing**,376-the popup drives the UI and the SAS confirmation round-trip.377-378-### New message types (propose)379-380-| Direction | `type` | Payload | Response |381-| --- | --- | --- | --- |382-| popup → bg | `PAIR_WITH_DESKTOP` | `{ code: string }` | `{ ok: true }` (started) or `{ ok:false, error }` |383-| bg → popup | `DESKTOP_PAIR_SAS` | `{ sas: string }` | — (push via `chrome.runtime.sendMessage`) |384-| popup → bg | `DESKTOP_PAIR_CONFIRM` | `{ confirmed: boolean }` | `{ ok: true }` |385-| bg → popup | `DESKTOP_PAIR_RESULT` | `{ status:"complete", device } \| { status:"error", error }` | — (push) |386-387-### SAS / confirm round-trip388-389-Because `pairWithDesktopHelper` takes a `confirm(sas) => Promise<boolean>`390-callback that must block on the user, the background handler bridges it to a391-message round-trip:392-393-1. `PAIR_WITH_DESKTOP` handler calls `pairWithDesktopHelper(code, cb, deps, confirm)`.394-2. `cb.onSasReady(sas)` and the `confirm` callback both fire `DESKTOP_PAIR_SAS`395-   to the popup and then **await a deferred Promise** that a later396-   `DESKTOP_PAIR_CONFIRM` message resolves.397-3. The popup shows the SAS, the user compares it to the helper's display,398-   taps confirm/reject, and the popup sends `DESKTOP_PAIR_CONFIRM { confirmed }`.399-4. The handler resolves the deferred Promise with `confirmed`, completing the400-   `confirm()` call inside `pairWithDesktopHelper`.401-5. `cb.onComplete`/`cb.onError` push `DESKTOP_PAIR_RESULT` to the popup.402-403-Keep one in-flight pairing per worker (store the pending `confirm` resolver404-in a module-level variable, cleared on completion/error). This mirrors how405-`chirp-pair.ts`'s `confirmSAS(sas): Promise<boolean>` dep gates persistence406-(`chirp-pair.ts` `confirmSAS` doc, lines ~62-71), just relocated to the407-background since no microphone is involved.408-409-**INTEGRATOR TODO (handler placement):** add the three `case` blocks to the410-`switch` in `messages.ts` (alongside `CHIRP_*` at lines 1318-1384). Gate on411-`vault.isUnlocked()` and `requirePro("sync")` exactly like412-`CHIRP_GET_LOCAL_IDENTITY` (`messages.ts:1319-1321`). Validate the persisted413-device with the same shape check `CHIRP_COMPLETE_PAIRING` uses414-(`messages.ts:1344-1360`) — except here the background builds the415-`PairedDevice` itself, so the validation can be skipped (the device comes from416-our own decode path, not from the popup).417-418----419-420-## Open integration TODOs421-422-1. **`openBinaryWebSocket` helper** — a small adapter producing a423-   `DesktopPairingSocket` from `WebSocket` (set `binaryType="arraybuffer"`,424-   queue inbound frames, expose `closedBeforeFrame()`). Pattern already exists425-   in `chirp-sync-transport.ts:58-121` (inbox/readers + onclose); extract a426-   trimmed version. Critically, `closedBeforeFrame()` must distinguish "socket427-   closed with no ACK" from "ACK received" — this is the `invalid_code` signal.428-2. **`LocalChirpIdentity` vs `LocalIdentity`** type reconciliation (see429-   threading note).430-3. **Pro gating + lock checks** in the new `messages.ts` cases.431-4. **Single-flight guard** for the pending-confirm resolver in the background.432-5. **Timeout** — wrap `findHost`/`receive` in a ceiling (e.g. 10s probe, 5s433-   per receive) so a stalled helper surfaces `no_host_found`/`handshake_failed`434-   instead of hanging the popup. `connectWebSocket` in435-   `chirp-sync-transport.ts:174` already shows the timeout idiom.

@@ -1,495 +0,0 @@1-# Change 4 — Desktop helper pairing UI2-3-> **DRAFT.** Conforms to `_GROUND-TRUTH.md` and `03-desktop-pairing-handler.md`.4-> Proposed new component:5-> `/Users/june/projects/peach-browser/src/popup/components/DesktopPairingFlow.tsx`.6-> Nothing here is applied — apply-ready draft only.7-8-This is the popup-side counterpart to the background pairing client in Change 3.9-It is a **sibling of `ChirpPairingFlow.tsx`** — same file layout (a top-level10-`Component`, a small phase state machine, a SAS-confirmation gate, friendly error11-copy, an `aria-live` region) — but driven by a typed **code** the user reads off12-their computer instead of an audio chirp.13-14----15-16-## 0. Reality vs the brief (READ FIRST)17-18-The brief was written against React idioms. This repo is **Solid.js**. The draft19-below uses Solid, not React. Concrete deviations:20-21-| Brief said | Reality in this repo | What the draft uses |22-| --- | --- | --- |23-| React, `.tsx` with hooks (`useState`/`useEffect`) | Solid.js (`solid-js`) | `createSignal`, `createEffect`, `<Show>`, `onCleanup`, `Component` |24-| `OutlinedTextField` | No such component; Peach has no Material inputs | `peach-underline-input` `<input>` (the real "PeachField") |25-| `PeachField` component | **No component named `PeachField` exists** (verified — `grep -rl PeachField src` returns nothing). The underline-style field the brief means is a plain `<input class="peach-underline-input …">` | `peach-underline-input` class |26-| `@solidjs/testing-library` for tests | Repo does **not** use it. Component tests use a tiny local helper `renderView` from `src/popup/views/view-test-utils.tsx` + raw jsdom | `renderView`, `inputText`, real DOM queries |27-28-### The "PeachField" underline input — what it actually is29-30-There is no `PeachField` component. The underline-style input the brief calls for31-is a bare `<input>` carrying the `peach-underline-input` class, defined at32-`src/popup/styles/popup.css:1006`:33-34-```css35-.peach-underline-input {36-  width: 100%; border: 0; border-bottom: 1px solid var(--peach-t3);37-  padding: 6px 0; background: transparent; color: var(--peach-t0);38-  outline: none;39-  font-family: "IBM Plex Mono", "SFMono-Regular", Menlo, monospace;40-  font-size: 0.8125rem;41-  caret-color: var(--peach-accent);42-}43-```44-45-It is used as a single class on a native `<input>` — see `Lock.tsx:326`,46-`Lock.tsx:452`, `Lock.tsx:487`, and `RecoveryWordEntry.tsx:297,314`. The47-big-glyph variant (`peach-unlock-input`, `popup.css:1014`) gives `font-size:22px;48-letter-spacing:0.24em`, which is the right look for a 6-digit code. The draft49-reuses `peach-underline-input` + a code-specific class `peach-code-input`.50-51-> A **single** field (not 6 auto-advancing boxes) is correct here. The repo's52-> existing 6-digit SAS surface (`ChirpSync.tsx:445-472`) renders the code as one53-> mono string, and the master-password/recovery entry uses one underline field.54-> There is **no** existing auto-advance multi-box pattern to mirror, so a single55-> `inputmode="numeric"` `maxlength=6` field matches Peach's form style and is56-> simpler. (Documented per brief.)57-58----59-60-## 1. Message-name adjustments vs file 0361-62-File 03 §"New message types" defines four messages. The brief named three63-(`PAIR_WITH_DESKTOP`, `DESKTOP_PAIR_SAS`, `DESKTOP_PAIR_CONFIRM`). This UI uses64-**all four from 03**, because the popup needs the terminal push to know whether65-pairing finished or failed. Reconciliation:66-67-| Brief name | 03 name | Used here | Notes |68-| --- | --- | --- | --- |69-| `PAIR_WITH_DESKTOP` (popup→bg) | `PAIR_WITH_DESKTOP` | yes | payload `{ code }`; resp `{ ok }` or `{ ok:false, error }` |70-| `DESKTOP_PAIR_SAS` (bg→popup push) | `DESKTOP_PAIR_SAS` | yes | payload `{ sas }` |71-| `DESKTOP_PAIR_CONFIRM` (popup→bg) | `DESKTOP_PAIR_CONFIRM` | yes | **payload `{ confirmed: boolean }`** — 03 uses `confirmed`, the brief wrote `{accept:true}`. The draft follows 03 (`confirmed`). |72-| — | `DESKTOP_PAIR_RESULT` (bg→push) | yes | 03-only; payload `{ status:"complete", device } \| { status:"error", error }`. The brief had no terminal push; without it the popup can't distinguish "Paired!" from a late error, so it is required. |73-74-**Net adjustment:** brief's `{accept:true}` → `{confirmed:true}` (match 03);75-brief's three messages → 03's four (add `DESKTOP_PAIR_RESULT`). Names otherwise76-identical to both 03 and the brief.77-78-### Error-code mapping (per ground truth §0.3 and 03 `DesktopPairingError`)79-80-The background's `DesktopPairingError` union (03, lines ~92-97) maps to copy:81-82-| Background error | Friendly copy |83-| --- | --- |84-| `invalid_code` | **"Code not found or expired"** |85-| `no_host_found` | "Couldn't find your computer" |86-| `handshake_failed` | "Pairing failed — try again" |87-| `sas_mismatch` | "Codes don't match" |88-| `vault_locked` | "Unlock Peach first, then pair" |89-90-> **invalid_code = "not found or expired", combined on purpose.** Ground truth91-> §0.3 / §2: peach-sync sends **no error frame** — a wrong *or* expired code both92-> surface identically as a socket close before `PEACH_HELLO_ACK`. The wire cannot93-> distinguish them, so the background collapses both to `invalid_code` and the UI94-> shows a **single** "Code not found or expired" message. The brief's separate95-> "Code not found" (invalid_code) and "Code expired" (expired) cannot be told96-> apart on this wire and are merged. If a future protocol revision adds an97-> explicit expiry frame, split the copy then.98-99----100-101-## 2. Where this slots into the Add-Device UI102-103-### Parent file and exact spot104-105-The existing pairing entry point is **`src/popup/views/ChirpSync.tsx`** — the106-Settings → Sync surface. Its `restView()` (`ChirpSync.tsx:300-426`) is the107-"rest" mode that lists paired devices and offers pairing. The single pairing CTA108-is the **"Pair a device" button block** at `ChirpSync.tsx:412-423`:109-110-```tsx111-<div class="peach-chirp-action">112-  <p class="peach-chirp-mic-notice">…</p>113-  <button class="peach-chirp-pair-start" onClick={() => void handleStartPairing()}>114-    …<span>{devices().length === 0 ? "Pair a device" : "Pair another device"}</span>115-  </button>116-</div>117-```118-119-Today that button is the *only* "Add Device" affordance and it goes straight into120-the chirp flow. The Desktop Helper option slots in here as a **second choice121-alongside the chirp button**, inside this same `peach-chirp-action` block. Two122-ways to wire it (pick one at integration):123-124-- **(A) Two buttons.** Keep "Pair a device" (chirp) and add a second125-  `peach-chirp-pair-start`-styled button labelled **"Desktop Helper (enter126-  code)"** directly beneath it. Cheapest, matches the brief's "mode select127-  entry point … alongside the existing Chirp option".128-- **(B) Mode select.** Replace the single button with a tiny chooser (chirp vs129-  code) that sets a `pairKind` signal. More work; same UX.130-131-The draft component `DesktopPairingFlow` itself **also includes a built-in132-mode-select header** (chirp vs desktop) so it can be the whole surface if the133-integrator routes "Pair a device" into it. Either way, the **insertion point is134-`ChirpSync.tsx` `restView()` action block (lines 412-423)**, and the135-**rendering point is `ChirpSync.tsx` `pairingView()` (lines 428-474)**, which136-already does `<Show when={sasCode()} fallback={<ChirpPairingFlow .../>}>`. The137-desktop flow is rendered the same way: when the user picks Desktop Helper,138-`pairingView()` renders `<DesktopPairingFlow .../>` instead of (or in addition139-to) `<ChirpPairingFlow .../>`.140-141-### Wiring sketch in ChirpSync.tsx (integration TODO — NOT applied)142-143-```tsx144-// new signal alongside the others (ChirpSync.tsx ~line 51)145-const [pairKind, setPairKind] = createSignal<"chirp" | "desktop">("chirp");146-147-// in restView()'s action block (ChirpSync.tsx 412-423), add beneath the148-// existing chirp button:149-<button150-  class="peach-chirp-pair-start peach-chirp-pair-start--desktop"151-  onClick={() => { setPairKind("desktop"); setMode("pairing"); }}152->153-  <span>Desktop Helper (enter code)</span>154-</button>155-156-// in the render switch (ChirpSync.tsx 482-493), when mode()==="pairing" and157-// pairKind()==="desktop", render <DesktopPairingFlow/> instead of the chirp view:158-<Show when={pairKind() === "desktop"} fallback={pairingView()}>159-  <DesktopPairingFlow onCancel={() => setMode("rest")} onDone={() => { setMode("rest"); void refresh(); }} />160-</Show>161-```162-163-`DesktopPairingFlow` is **self-contained** for the message round-trip: it sends164-`PAIR_WITH_DESKTOP`, listens for `DESKTOP_PAIR_SAS` / `DESKTOP_PAIR_RESULT`165-pushes via `chrome.runtime.onMessage`, and replies `DESKTOP_PAIR_CONFIRM`. It166-does **not** reuse ChirpSync's `sasResolve` plumbing (that one is in-popup; this167-SAS arrives as a push from the background, per 03's split where the background168-runs the whole pairing).169-170----171-172-## 3. Popup ⇄ background message contract (must match 03)173-174-```ts175-// popup → bg : start pairing with the typed code176-{ type: "PAIR_WITH_DESKTOP", payload: { code: string } }177-//   resp: { ok: true } | { ok: false, error: DesktopPairingError }178-179-// bg → popup (push) : SAS ready, show confirm gate180-{ type: "DESKTOP_PAIR_SAS", payload: { sas: string } }181-182-// popup → bg : user accepted/rejected the SAS183-{ type: "DESKTOP_PAIR_CONFIRM", payload: { confirmed: boolean } }184-//   resp: { ok: true }185-186-// bg → popup (push) : terminal result187-{ type: "DESKTOP_PAIR_RESULT",188-  payload: { status: "complete", device: PairedDevice }189-         | { status: "error", error: DesktopPairingError } }190-```191-192-`sendMessage` is the existing bridge (`src/shared/bridge.ts:13`); pushes are193-received with `chrome.runtime.onMessage.addListener` exactly as `App.tsx:601`194-does. `DesktopPairingError` is defined in 03 (`desktop-pairing.ts`).195-196----197-198-## 4. Apply-ready component — `src/popup/components/DesktopPairingFlow.tsx`199-200-```tsx201-// DesktopPairingFlow — the desktop-helper *code* pairing screen.202-//203-// Sibling of ChirpPairingFlow.tsx, but driven by a 6-digit code the user204-// reads off their computer rather than an audio chirp. The whole pairing205-// runs in the BACKGROUND (03); this component:206-//   1. takes a 6-digit code in a single underline field (the "PeachField"),207-//   2. on Connect -> sends PAIR_WITH_DESKTOP, shows "Searching for helper…",208-//   3. on the DESKTOP_PAIR_SAS push -> shows the SAS + Confirm / Cancel,209-//   4. on Confirm -> DESKTOP_PAIR_CONFIRM { confirmed:true } -> "Paired!",210-//      on Cancel  -> DESKTOP_PAIR_CONFIRM { confirmed:false } -> error,211-//   5. maps background errors (DESKTOP_PAIR_RESULT) to friendly copy.212-//213-// Wire contract: _GROUND-TRUTH.md §6 + 03-desktop-pairing-handler.md.214-215-import { Component, Show, createEffect, createSignal, onCleanup, onMount } from "solid-js";216-import { sendMessage } from "../../shared/bridge";217-import type { PairedDevice } from "../../shared/sync-types";218-219-// Mirrors DesktopPairingError in 03 (src/background/desktop-pairing.ts).220-type DesktopPairingError =221-  | "invalid_code"222-  | "no_host_found"223-  | "handshake_failed"224-  | "sas_mismatch"225-  | "vault_locked";226-227-// Local UI phase machine (the analogue of PairingPhase for the chirp flow).228-type DesktopPhase =229-  | "enter"        // user is typing the code230-  | "searching"    // PAIR_WITH_DESKTOP sent, awaiting SAS/result231-  | "confirm"      // DESKTOP_PAIR_SAS received, awaiting user confirm232-  | "paired"       // DESKTOP_PAIR_RESULT status:complete233-  | "error";       // DESKTOP_PAIR_RESULT status:error (or a start failure)234-235-export interface DesktopPairingFlowProps {236-  /** Back/cancel out of the desktop flow (return to the device list). */237-  onCancel: () => void;238-  /** Pairing finished and the device was persisted; dismiss the surface. */239-  onDone: (device?: PairedDevice) => void;240-}241-242-const PAIRED_DISMISS_MS = 2_000;243-const CODE_LEN = 6;244-245-function errorCopy(error: DesktopPairingError | "unknown"): { headline: string; sub: string } {246-  switch (error) {247-    case "invalid_code":248-      // Ground truth §0.3: wrong vs expired is indistinguishable on the wire.249-      return { headline: "Code not found or expired", sub: "Check the code on your computer and try again. Codes rotate, so grab a fresh one if it's been a while." };250-    case "no_host_found":251-      return { headline: "Couldn't find your computer", sub: "Make sure the Peach helper is running and both devices are on the same Wi-Fi." };252-    case "sas_mismatch":253-      return { headline: "Codes don't match", sub: "For your safety, pairing was stopped. Start over and compare the two codes carefully." };254-    case "vault_locked":255-      return { headline: "Unlock Peach first", sub: "Your vault needs to be unlocked before you can pair a device." };256-    case "handshake_failed":257-    default:258-      return { headline: "Pairing failed", sub: "Something went wrong while connecting. Please try again." };259-  }260-}261-262-export const DesktopPairingFlow: Component<DesktopPairingFlowProps> = (props) => {263-  const [phase, setPhase] = createSignal<DesktopPhase>("enter");264-  const [code, setCode] = createSignal("");265-  const [sas, setSas] = createSignal<string | null>(null);266-  const [error, setError] = createSignal<DesktopPairingError | "unknown">("unknown");267-  const [device, setDevice] = createSignal<PairedDevice | undefined>(undefined);268-  const [busy, setBusy] = createSignal(false);269-270-  const codeReady = () => /^\d{6}$/.test(code());271-272-  // Listen for the two background pushes (mirrors App.tsx:601 idiom).273-  onMount(() => {274-    const handler = (msg: { type?: string; payload?: unknown }) => {275-      if (msg?.type === "DESKTOP_PAIR_SAS") {276-        const p = msg.payload as { sas?: string } | undefined;277-        if (typeof p?.sas === "string") { setSas(p.sas); setPhase("confirm"); }278-      } else if (msg?.type === "DESKTOP_PAIR_RESULT") {279-        const p = msg.payload as280-          | { status: "complete"; device: PairedDevice }281-          | { status: "error"; error: DesktopPairingError }282-          | undefined;283-        if (p?.status === "complete") { setDevice(p.device); setPhase("paired"); }284-        else if (p?.status === "error") { setError(p.error); setPhase("error"); }285-      }286-    };287-    chrome.runtime.onMessage.addListener(handler);288-    onCleanup(() => chrome.runtime.onMessage.removeListener(handler));289-  });290-291-  // Auto-dismiss after the paired state settles, like ChirpPairingFlow.292-  createEffect(() => {293-    if (phase() !== "paired") return;294-    const t = setTimeout(() => props.onDone(device()), PAIRED_DISMISS_MS);295-    onCleanup(() => clearTimeout(t));296-  });297-298-  async function handleConnect(): Promise<void> {299-    if (!codeReady() || busy()) return;300-    setBusy(true);301-    setPhase("searching");302-    try {303-      const res = (await sendMessage({304-        type: "PAIR_WITH_DESKTOP",305-        payload: { code: code() },306-      })) as { ok: boolean; error?: DesktopPairingError };307-      // A synchronous failure (e.g. vault_locked) comes back here; the SAS and308-      // terminal result arrive later as pushes.309-      if (!res.ok) { setError(res.error ?? "unknown"); setPhase("error"); }310-    } catch {311-      setError("unknown");312-      setPhase("error");313-    } finally {314-      setBusy(false);315-    }316-  }317-318-  async function respondConfirm(confirmed: boolean): Promise<void> {319-    if (busy()) return;320-    setBusy(true);321-    // Optimistically move on; the terminal DESKTOP_PAIR_RESULT push decides the322-    // final phase (paired vs sas_mismatch error).323-    if (confirmed) setPhase("searching"); else { setError("sas_mismatch"); setPhase("error"); }324-    try {325-      await sendMessage({ type: "DESKTOP_PAIR_CONFIRM", payload: { confirmed } });326-    } finally {327-      setBusy(false);328-    }329-  }330-331-  function reset(): void {332-    setPhase("enter");333-    setSas(null);334-    setDevice(undefined);335-    setError("unknown");336-  }337-338-  function onCodeInput(value: string): void {339-    setCode(value.replace(/\D/g, "").slice(0, CODE_LEN));340-  }341-342-  return (343-    <div class="peach-chirp-pair peach-desktop-pair" data-phase={phase()} role="dialog" aria-label="Pair a desktop helper">344-      <header class="peach-chirp-head">345-        <button class="peach-chirp-back" aria-label="Back" onClick={() => props.onCancel()}>346-          <svg viewBox="0 0 16 16" width="14" height="14" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">347-            <path d="M10 3 L5 8 L10 13" />348-          </svg>349-        </button>350-        <div class="peach-chirp-title">Desktop Helper</div>351-        <div class="peach-chirp-head-spacer" />352-      </header>353-354-      {/* ---- enter: 6-digit code field ---- */}355-      <Show when={phase() === "enter"}>356-        <div class="peach-desktop-enter">357-          <div class="peach-chirp-headline">Enter the code from your computer</div>358-          <div class="peach-chirp-sub">359-            Open the Peach helper on your computer and type the 6-digit code it shows.360-          </div>361-          <label class="peach-label" for="desktop-pair-code">pairing code</label>362-          <input363-            id="desktop-pair-code"364-            class="peach-underline-input peach-unlock-input peach-code-input"365-            type="text"366-            inputmode="numeric"367-            autocomplete="one-time-code"368-            maxlength={CODE_LEN}369-            placeholder="000000"370-            aria-label="6-digit pairing code"371-            value={code()}372-            ref={(el) => setTimeout(() => el.focus(), 80)}373-            onInput={(e) => onCodeInput((e.target as HTMLInputElement).value)}374-            onKeyDown={(e) => { if (e.key === "Enter") void handleConnect(); }}375-          />376-          <div class="peach-chirp-action">377-            <button class="peach-chirp-cancel peach-btn peach-btn-ghost" onClick={() => props.onCancel()}>378-              Cancel379-            </button>380-            <button381-              class="peach-btn peach-btn-primary peach-desktop-connect"382-              disabled={!codeReady() || busy()}383-              onClick={() => void handleConnect()}384-            >385-              Connect386-            </button>387-          </div>388-        </div>389-      </Show>390-391-      {/* ---- searching ---- */}392-      <Show when={phase() === "searching"}>393-        <div class="peach-desktop-searching">394-          <div class="peach-chirp-headline">Searching for helper…</div>395-          <div class="peach-chirp-sub">Connecting to the Peach helper on your computer.</div>396-          <div class="peach-chirp-action-handshake">397-            <div class="peach-chirp-meter"><span class="peach-chirp-meter-bar" /></div>398-            <span class="peach-chirp-meter-label">connecting · noise NK</span>399-          </div>400-        </div>401-      </Show>402-403-      {/* ---- confirm: SAS gate ---- */}404-      <Show when={phase() === "confirm"}>405-        <div class="peach-desktop-confirm" style="display:flex;flex-direction:column;align-items:center;gap:12px;padding:16px 18px;text-align:center;">406-          <div class="peach-chirp-headline">Confirm this code matches on your computer:</div>407-          <div408-            class="peach-desktop-sas"409-            style="font-size:30px;font-weight:700;letter-spacing:0.32em;font-family:'IBM Plex Mono',monospace;color:var(--peach-accent);padding:6px 0 2px;"410-          >411-            {sas()}412-          </div>413-          <div class="peach-chirp-sub" style="max-width:240px;">414-            Only continue if this 6-digit code is identical on both screens.415-          </div>416-          <div style="display:flex;flex-direction:column;gap:8px;width:100%;max-width:240px;">417-            <button class="peach-btn peach-btn-primary" disabled={busy()} onClick={() => void respondConfirm(true)}>418-              Confirm419-            </button>420-            <button class="peach-btn peach-btn-ghost" disabled={busy()} onClick={() => void respondConfirm(false)}>421-              Cancel422-            </button>423-          </div>424-        </div>425-      </Show>426-427-      {/* ---- paired ---- */}428-      <Show when={phase() === "paired"}>429-        <div class="peach-desktop-paired">430-          <div class="peach-chirp-headline">Paired!</div>431-          <div class="peach-chirp-sub">432-            {device()?.deviceName ? `Connected to ${device()!.deviceName}` : "Connected to your computer"}433-          </div>434-          <div class="peach-chirp-action">435-            <button class="peach-btn peach-btn-primary" onClick={() => props.onDone(device())}>Done</button>436-          </div>437-        </div>438-      </Show>439-440-      {/* ---- error ---- */}441-      <Show when={phase() === "error"}>442-        <div class="peach-desktop-error">443-          <div class="peach-chirp-headline">{errorCopy(error()).headline}</div>444-          <div class="peach-chirp-sub">{errorCopy(error()).sub}</div>445-          <div class="peach-chirp-action">446-            <button class="peach-btn peach-btn-ghost" onClick={() => props.onCancel()}>Cancel</button>447-            <button class="peach-btn peach-btn-primary" onClick={() => reset()}>Try again</button>448-          </div>449-        </div>450-      </Show>451-452-      {/* Polite live region so phase changes reach assistive tech. */}453-      <div class="peach-sr-only" aria-live="polite">{liveText(phase(), error())}</div>454-    </div>455-  );456-};457-458-function liveText(phase: DesktopPhase, error: DesktopPairingError | "unknown"): string {459-  switch (phase) {460-    case "enter": return "Enter the pairing code from your computer";461-    case "searching": return "Searching for the helper";462-    case "confirm": return "Confirm the code matches on your computer";463-    case "paired": return "Paired";464-    case "error": return errorCopy(error).headline;465-  }466-}467-```468-469-> Reused class hooks (`peach-chirp-pair`, `peach-chirp-head`, `peach-chirp-back`,470-> `peach-chirp-headline`, `peach-chirp-sub`, `peach-chirp-action`,471-> `peach-chirp-meter*`, `peach-btn*`, `peach-sr-only`, `peach-underline-input`,472-> `peach-unlock-input`, `peach-label`) all already exist in `popup.css`. New473-> hooks (`peach-desktop-pair`, `peach-code-input`, `peach-desktop-*`) are474-> additive and need a small CSS block at integration (out of scope for this475-> draft — drafts touch only this folder).476-477----478-479-## 5. Integration TODOs (NOT applied — flagged for the integrator)480-481-1. **Add the three message cases to `messages.ts`** per 03 §"Wiring" (the482-   background side). This component assumes those handlers exist.483-2. **Insert the Desktop Helper affordance** into `ChirpSync.tsx` `restView()`484-   action block (lines 412-423) and render `<DesktopPairingFlow/>` from485-   `pairingView()` — see §2.486-3. **CSS** for the new `peach-desktop-*` / `peach-code-input` hooks in487-   `popup.css` (inline styles cover the load-bearing SAS/confirm layout in the488-   meantime, matching ChirpSync's inline-styled SAS gate at lines 445-472).489-4. **Pro gate + lock check.** ChirpSync already gates on `props.isPro`; the490-   desktop button should live behind the same gate, and `vault_locked` from the491-   background is surfaced as friendly copy here.492-5. **Single in-flight pairing.** 03 keeps one pairing per worker; if the user493-   backs out mid-flow (`onCancel`), the integrator may want a494-   `DESKTOP_PAIR_CONFIRM { confirmed:false }` or a cancel message to release the495-   background resolver. Left as a TODO since 03 owns that lifecycle.