1 +#
Clipboard Popup Redesign — Design Spec 4 +**Status:** Approved (owner-delegated, autonomous)
5 +**Goal:** Turn the text-only, alphabetically-sorted clipboard list into a fast, graphical history with image thumbnails, content-type awareness, recency-correct ordering, and icon action rails — same architecture as the system/caldav work.
9 +##
1. Problems with the current popup 11 +- **Loses recency.** `filteredRows` sorts pinned-first then `a.title.localeCompare(b.title)` — alphabetical. The most recent copy is not at the top. Wrong for a clipboard.
12 +- **Text-only.** Images are captured as `/tmp/...png` paths and rendered as the string "PNG clipboard item". No thumbnail.
13 +- **Cryptic actions.** Action rail shows `cp` / `ps` / `pin` / `del` text; always visible, no icons.
14 +- **No content typing.** A URL, a hex color, a file path, and a paragraph all look identical.
15 +- **Narration bloat.** `clipboardPanelContract()` and `scrollableListChrome()` serialize large self-describing metadata blobs that the view reads back to decide chrome. Dead weight — delete.
16 +- **Logic tangled in QML.** `normalize`/`isReadableText`/`hashText`/`firstLine`/`rowTitle`/`filteredRows`/kind-detection are pure functions stuck in `Clipboard.qml`, untested.
20 +##
2. Decisions (locked) 24 +| Architecture | Pure `clip.js` (node-tested, dual-mode export, no I/O) + thin `Clipboard.qml` (wl-paste watch, FileView persist, wl-copy/wtype actions) + pure view — mirrors `sysinfo.js`/`caldav.js`. |
25 +| Sort | **pinned first, then recency** (`createdAt` desc). The fix. |
26 +| Content kinds | `detectKind(text) → {kind, icon}`: `image`, `color`, `url`, `path`, `text`. Each kind gets a Nerd Font icon; color also yields a swatch. |
27 +| Image thumbnails | Image rows render a real `Image` (`source: "file://"+path`, `sourceSize` capped, `asynchronous`) instead of a label. Detect via temp-image path / image extension. |
28 +| Color swatch | Hex (`#rgb`/`#rgba`/`#rrggbb`/`#rrggbbaa`) and `rgb()/rgba()` items show a filled swatch using the parsed color. |
29 +| Action rail | Nerd Font icon buttons (copy / paste / pin / delete), revealed on row hover (keyboard-reachable stays), pin icon filled when pinned, delete tinted error. |
30 +| Row layout | rounded card: leading thumbnail/type-icon (or color swatch) · title (first line) · muted `kind · age` meta · hover action rail. Pinned rows tinted + pin badge. |
31 +| Search + private | Keep the search field and private-mode chip; restyle to the dark-card aesthetic (ghost/solid, theme tokens). |
32 +| Removed | `clipboardPanelContract()`, `scrollableListChrome()`, the state-driven edge-fade chrome, `cp/ps/pin/del` text. Replace fades with a simple clipped Flickable. |
33 +| Persistence | Keep durable `clipboard-history.json` via FileView (atomicWrites). Keep `maxRows` cap. |
34 +| IPC contract | Keep `stateJson()`, `search(q)`, `copy(id)`, `paste(id)`, `togglePin(id)`, `deleteRow(id)`, `setPrivateMode(b)`, and **`launcherRows(q)`** (the Launcher consumes it — do not break the row shape: `id,title,body,pinned,provider,route,subtitle,keyboard`). Add `selfTest()`. |
35 +| Capture | Keep `wl-paste --type text/plain --watch`. (Image capture stays as-is — wl-paste text watch already yields temp-image paths from the existing flow; no new helper.) |
41 +###
3.1 `clip.js` (new — pure, node-tested) 42 +- `normalize(text)`, `isReadableText(text)`, `hashText(text)`, `firstLine(text)`, `rowTitle(text)`.
43 +- `isImagePath(text)`, `parseColor(text) → "#rrggbb"|null`, `detectKind(text) → {kind, icon}`.
44 +- `sortRows(rows) → rows` — pinned first, then `createdAt` desc.
45 +- `filterRows(rows, query) → rows` — substring match on title+body, then `sortRows`.
46 +- `cloneRow(row)` / `persistedRow(row)` shapers (pure; the view + launcher row shape).
47 +- `ageLabel(createdAt, now) → "just now" | "3m" | "2h" | "5d"`.
48 +- Dual-mode export tail (guarded `module.exports`), identical to `caldav.js`.
50 +###
3.2 `clip.test.js` (new — node) 51 +Assert every parser/detector (each kind, color parsing incl. shorthand, image-path), `sortRows` (pinned-first + recency), `filterRows`, `ageLabel` buckets, `isReadableText` rejects binary. Prints `ALL PASS`.
53 +###
3.3 `Clipboard.qml` (reworked — thin) 54 +- Imports `clip.js`; delegates all parsing/sort/detect.
55 +- Keeps: `wl-paste --watch` Process, history FileView, `wl-copy`/`wtype` actions via `Quickshell.execDetached`, `privateMode`, `maxRows`, `historyPath`.
56 +- `captureClipboard`, `togglePin`, `copy`, `paste`, `deleteRow`, `setPrivateMode` keep behavior; `stateObject` trimmed to `{ privateMode, rows, lastAction }` (rows already carry `kind`/`icon`/`isImage`/`swatch`/`age`).
57 +- Adds `selfTest()` (parse fixtures through clip.js, sort, detect) returning `{pass,fail,cases}`.
58 +- Deletes `clipboardPanelContract`, `scrollableListChrome`, `rowsById`, and narration fields.
60 +###
3.4 `PopoutHost.qml` `ClipboardPanel` (rewrite) 61 +- Search row (field + private chip) restyled.
62 +- Rounded panel → clipped `Flickable` of row cards (no state-driven edge fades).
63 +- Inline `ClipRow`: leading 36px slot = image thumbnail / color swatch / type icon; title + `kind · age` meta; hover-revealed icon action rail.
64 +- Pinned styling + sort already handled by the service.
66 +###
3.5 `SurfaceManager.qml` 67 +- Resize the `"clipboard"` popup for the richer rows (taller list); drop the `clipboard-history` catalog narration to match the others.
72 +- Non-readable / oversized capture ignored (keep `isReadableText`).
73 +- Image thumbnail load failure → fall back to the image type icon.
74 +- Malformed history JSON → empty list, rebuild file (keep current guard).
75 +- `parseColor` returns null on anything not a valid color → row is `text`, no swatch.
78 +- `node clip.test.js` → `ALL PASS`.
79 +- `qs ipc call clipboard selfTest` → pass counts (after restart).
80 +- Manual: restart, open clip popup, screenshot — verify recency order, an image row shows a thumbnail, a hex item shows a swatch, a URL shows the link icon, hover reveals the icon rail.
83 +- Rich capture of non-text MIME beyond the existing temp-image-path flow.
84 +- Multi-select / bulk actions.
85 +- Syncing history across machines.