From 885e64ff8566cd74737fcd941f71c3681dc796ff Mon Sep 17 00:00:00 2001 From: Eduard Tolosa Date: Wed, 27 May 2026 00:24:42 -0500 Subject: [PATCH] docs: add a Features section to the README Document the supported content types (text, URLs, colors, images, files), full-history FTS search, automatic light/dark theming, lazy loading, dedup, reliability and privacy behavior, and the panel controls. Co-Authored-By: Claude Opus 4.7 --- README.md | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 67 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 386cfd0..9d0f4cc 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,72 @@ All heavy work (hashing, decoding, storage, search, thumbnails) lives in a Rust daemon. The GNOME Shell extension only renders UI and forwards events over D-Bus, so the compositor is never blocked, even with thousands of items. +## Features + +**Content types.** Strata captures and previews: + +- **Text** (UTF-8). When an app offers both rich and plain text, Strata stores + the plain text rather than styled HTML. +- **URLs** are shown link-styled, with the hostname as a subtitle. +- **Colors**: hex values (`#rgb` / `#rrggbb`) get a color swatch. +- **Images**: PNG, JPEG, GIF, WebP, BMP, TIFF, ICO, shown as thumbnails. + Decoding and resizing happen once, in the daemon, at copy time. +- **Files**: file-manager copy/cut (URI lists, e.g. from Nautilus). + +Unknown MIME types are ignored (a strict allowlist). + +**Search.** + +- Full-text search over the entire stored history, backed by SQLite FTS5. +- Prefix matching, diacritic-insensitive (`cafe` matches `café`). +- Text only; images and binaries are not indexed. + +**Appearance.** + +- Automatic light/dark theme: `Auto` follows the system color scheme; `Light` + and `Dark` force one. +- Configurable panel position (top/center/bottom by left/center/right), width, + and maximum height. +- Optional "move an item to the top" when you paste it. + +**Performance.** + +- All hashing, decoding, storage, search, and thumbnailing run in the Rust + daemon, off the compositor's main loop. +- Lazy loading: the panel loads one page of history at a time and fetches more + on scroll; thumbnails are fetched on demand and cached on disk; search + renders a page at a time. The full table never sits in memory. +- Deduplication: copying the same content twice moves the existing entry to the + top (blake3 content hash) instead of adding a duplicate. + +**Reliability.** + +- SQLite in WAL mode with atomic upserts; history survives a crash. +- The extension supervises the daemon, respawning it with exponential backoff. + Only one daemon runs at a time; a second exits rather than contend for the + bus name. +- Configurable history limit (default 200, up to 2000); oldest items are pruned + automatically. + +**Privacy and safety.** + +- Password-manager aware: entries marked sensitive (the + `x-kde-passwordManagerHint` used by KeePassXC and others) are never stored. +- App exclusions: items copied while a listed app has focus are skipped. The + default list covers common password managers (1Password, KeePassXC, + Bitwarden, and others). +- Size caps: text and image payloads larger than a configurable limit (1 MB and + 5 MB by default) are not stored. +- Never executes clipboard content: no shell exec, no `launch_uri`, no markup + parsing; paste-back only writes to the clipboard. + +**Controls.** + +- Top-bar icon and popup panel, opened with a configurable shortcut (default + `Super+Shift+V`). +- Keyboard navigation (arrow keys, `Esc` to close), click-outside to dismiss, + per-row delete, and "Clear all". + ## Architecture Strata is **two components**, and you need **both** for it to work: @@ -28,7 +94,7 @@ GNOME Shell (GJS) ──D-Bus──▶ strata-daemon ──▶ SQLite (~/.lo ## Requirements -- GNOME Shell 50 (tested). May work on 45–49 but untested — if you try it and it works, please open an issue to let us know. +- GNOME Shell 50 (tested). May work on 45-49 but is untested; if it works for you, please open an issue to let us know. - `strata-daemon` binary in `$PATH` (see Install below) - Rust 1.74+ (build only) - `glib-compile-schemas` (from `glib2-devel` / `libglib2.0-dev-bin`)