From 6ace5568004a4af7553aea64ca98f6bcf7ec854f Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 10 Jul 2026 00:59:10 +0000 Subject: [PATCH 1/4] Add stayturgid-style HANDOFF and HACKING docs. Document current v4.5.9 state, openUrl nav invariants, Hermes/IIFE constraints, and a README documentation index with cross-links. Co-authored-by: Daniel JB Clark --- CHANGELOG.md | 2 +- HACKING.md | 284 +++++++++++++++++++++++++++++++++++++++++++++++++++ HANDOFF.md | 249 ++++++++++++++++++++++++++++++++++++++++++++ OPTIONS.md | 2 + README.md | 68 +++++++++--- TESTING.md | 4 +- 6 files changed, 591 insertions(+), 18 deletions(-) create mode 100644 HACKING.md create mode 100644 HANDOFF.md diff --git a/CHANGELOG.md b/CHANGELOG.md index daba53e..992e64c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,7 +12,7 @@ Keep this file updated in the same PR/commit as the code. GitHub Releases should ## [Unreleased] -_Nothing yet._ +- Docs: add stayturgid-style `HANDOFF.md` / `HACKING.md`; README documentation index; cross-links from OPTIONS/TESTING ## 4.5.9 diff --git a/HACKING.md b/HACKING.md new file mode 100644 index 0000000..ff0a534 --- /dev/null +++ b/HACKING.md @@ -0,0 +1,284 @@ +# HACKING — RevengeQuickSwitcher Development Environment + +This document gets a developer from a clean machine to a working build, install, and debug loop for Quick Server Switcher on Revenge Discord mobile. Follow the sections in order. + +Agent cold-start / current product state: [HANDOFF.md](HANDOFF.md). User install: [README.md](README.md). Device checklist: [TESTING.md](TESTING.md). + +--- + +## What you're setting up + +| Layer | Role | +|-------|------| +| Node.js + npm | Build, typecheck, Vitest | +| `dist/index.js` | Bundled plugin Revenge evals (committed) | +| `manifest.json` | Plugin metadata + content `hash` | +| Discord + Revenge | Runtime on Android/iOS device or emulator | +| Optional: adb logcat | Native logs when Copy debug logs is not enough | + +--- + +## Tested versions + +| Tool | Version | Notes | +|------|---------|-------| +| Node.js | 18+ (20+ recommended) | CI uses current Node LTS | +| npm | bundled with Node | Lockfile committed | +| TypeScript | ^5 | `tsc --noEmit` via `tsconfig.typecheck.json` | +| esbuild | ^0.28 | `scripts/build.mjs` | +| Vitest | ^3 | 96 unit tests | +| `@revenge-mod/types` | vendetta-types 2.4.21 | Dev types only | +| Plugin | **4.5.9** | See `package.json` / `manifest.json` | + +Revenge and Discord client versions churn; always record `/debug` output when filing device bugs. + +--- + +## Part 1 — Local setup + +### 1.1 Clone and install + +```bash +git clone https://github.com/djbclark/RevengeQuickSwitcher.git +cd RevengeQuickSwitcher +make install # or: npm install +``` + +### 1.2 Verify + +```bash +make verify +``` + +Runs, in order: + +1. **Typecheck** — all `src/` modules including `index.tsx` +2. **Unit tests** — Vitest (`*.test.ts`) +3. **Build** — esbuild → `dist/index.js`, updates `manifest.json` `hash` +4. **Manifest check** — `scripts/check-manifest.mjs` + +Expected: all steps exit 0; tests **96 passed**; `manifest ok (v…)`. + +Individual targets: + +| Command | Purpose | +|---------|---------| +| `make build` | Rebuild bundle only | +| `make test` | Vitest only | +| `make typecheck` | `tsc` only | +| `make clean` | Remove `node_modules/` | +| `make clean-all` | Remove `dist/` + `node_modules/` | + +npm equivalents: `npm run build`, `npm test`, `npm run typecheck`, `npm run verify`. + +### 1.3 After editing source + +1. Change files under `src/`. +2. `make verify`. +3. Commit **`src/`**, **`dist/index.js`**, and **`manifest.json`** together when shipping (Revenge loads the committed bundle from GitHub raw). +4. If releasing: bump `version` in `package.json` **and** `manifest.json`, update `CHANGELOG.md` and OPTIONS statuses. + +--- + +## Part 2 — Bundle constraints (CRITICAL) + +Revenge loads plugins like Vendetta: the client wraps/evals the file and expects a plugin export object. This repo matches the known-good shape. + +### 2.1 IIFE + CJS + +`scripts/build.mjs` bundles `src/index.tsx` as CJS, then wraps: + +```js +(function(exports){ ...; return exports })({}) +``` + +Do not switch to ESM-only output without re-validating enable on device. + +### 2.2 Hermes / ES2015 + +Discord's Hermes historically rejects newer syntax (`??=`, some optional-chain forms) at eval time. Build **`target: ["es2015"]`**. + +Symptoms of a bad bundle: plugin installs but toggle shows **X**; smoke plugin still enables → main bundle/start bug. + +### 2.3 Version injection + +`__QSS_VERSION__` is defined from `package.json` at build time. Debug log lines are stamped `[vX.Y.Z …]`. Keep `package.json` and `manifest.json` versions in sync. + +### 2.4 No eval-time storage / `this` + +Plugin enable failed historically when touching `storage` or relying on `this` at module eval time (see CHANGELOG 4.4.3–4.4.4). Keep side effects inside `onLoad` / settings render paths. + +### 2.5 Externals + +React, React Native, and `@revenge-mod/*` stay external — provided by the client at runtime. Types live in `src/revenge-mod.d.ts`. + +--- + +## Part 3 — Install on Revenge + +### 3.1 Raw URL (not github.com HTML) + +``` +https://raw.githubusercontent.com/djbclark/RevengeQuickSwitcher/main/ +``` + +Revenge fetches `{url}/manifest.json`. Trailing slash is fine. If you paste the repo page URL, install fails with “Failed to fetch manifest”. + +### 3.2 Steps + +1. User Settings → Revenge → Plugins → Install / **+** +2. Paste raw URL; allow unproxied install if prompted +3. Reload Discord (force-quit recommended after updates) +4. Toggle plugin **on**; open wrench/settings + +### 3.3 Smoke plugin + +If main will not enable: + +``` +https://raw.githubusercontent.com/djbclark/RevengeQuickSwitcher/main/smoke/ +``` + +| Smoke | Main | Meaning | +|-------|------|---------| +| Enables | Fails | Main start/bundle bug | +| Also X | — | Broader Revenge/safe-mode/network issue | + +### 3.4 Update loop + +After pushing to `main`: plugin info → **Refetch**, or delete + reinstall. Confirm debug lines show the new `vX.Y.Z` (ring clears on upgrade). + +--- + +## Part 4 — Debugging on device + +### 4.1 In-plugin buffer (preferred for sharing) + +1. Enable **Debug Logging** in plugin settings (optional but useful). +2. Reproduce the issue (open switcher, tap server, etc.). +3. Settings → **Copy debug logs**. +4. Paste into chat/GitHub (single line, ` | `-separated). + +Every line includes the plugin version. On upgrade, the ring resets so pastes are not mixed builds. + +When reporting stuck switcher / failed jump, include: + +- Discord / Revenge versions from `/debug` +- Whether Close dismisses the panel +- Whether a jump toast appeared +- The Copy debug logs paste + +### 4.2 Revenge / system logs + +1. **Safe Mode** off (plugins do not start in safe mode). +2. Revenge Developer settings (tap version repeatedly if needed). +3. Built-in `/debug` command. +4. Android logcat: + +```bash +adb logcat | grep -iE 'revenge|vendetta|Quick|plugin|hermes' +``` + +Start failures often look like `Plugin errored whilst loading`. Switcher lines are tagged `[QuickSwitcher]`. + +### 4.3 Navigation invariants (do not regress) + +Working path (v4.5.6+): + +1. Dismiss switcher host completely. +2. `openUrl("https://discord.com/channels/{guild}/{channel}")`. + +Do **not** reintroduce for jumps: + +- Loose `findByProps("selectChannel")` +- Flux `CHANNEL_SELECT` / `GUILD_SELECT` as primary success path +- Full-screen touch scrims / nested RN `Modal` that outlive the sheet + +UI host: prefer **top-docked** alert panel so the Android keyboard does not cover the list. Bottom `ActionSheet` is fine for short menus, not the primary searchable switcher. + +--- + +## Part 5 — Development workflow + +### 5.1 Feature work + +1. Branch from `main` (cloud agents: `cursor/-db57`). +2. Implement in `src/`; add/adjust Vitest coverage for pure helpers. +3. `make verify`. +4. Update OPTIONS.md statuses / CHANGELOG when behavior ships. +5. PR → merge → device **A1** checklist in TESTING.md. + +### 5.2 What belongs in unit tests + +Pure logic: fuzzy match, aliases, excludes, recents, command branching, sidebar transform/cache, sheet paging/filter helpers. + +Not mocked end-to-end: real Metro stores, real `openUrl`, real keyboard. Those are device QA (**A1**) or future harness (**D1**). + +### 5.3 Slash command on mobile + +Type `/`, pick **servers**, fill **query** / **page** fields. Sending plain text `/servers foo` is not a slash invocation. + +### 5.4 Optional: stayturgid / Handsets + +For Mac-driven Android UI automation, see the stayturgid repo (`docs/research/mac-android-ui-automation.md`). This plugin does not vendor Handsets. If adding automation later, prefer a thin driver over Appium/Maestro as the primary stack, and keep Vitest as the default `make test`. + +--- + +## Part 6 — Verification checklist + +### Local + +```bash +make verify +# Tests 96 passed (96) +# manifest ok (v4.5.9) # or current version +``` + +### Device (short) + +1. Install/refetch raw `main/` URL; force-quit Discord. +2. Enable plugin; open settings; **Open switcher**. +3. Filter field visible **above** keyboard when typing. +4. Tap a server → lands in that guild; Discord buttons still work. +5. Copy debug logs → lines show current version + `openUrl`. +6. Smoke through TESTING.md sections you touched (search, recents, excludes, flat sidebar). + +Full plan: [TESTING.md](TESTING.md). + +--- + +## Repo structure + +``` +RevengeQuickSwitcher/ + README.md — user-facing overview + install + HACKING.md — this file + HANDOFF.md — AI / maintainer cold-start + OPTIONS.md — backlog (A/B/C/D IDs) + TESTING.md — verify + device QA + CHANGELOG.md — semver + release notes + Makefile — install / build / test / verify + package.json — version + scripts + manifest.json — Revenge metadata + hash + src/ — TypeScript / TSX sources + tests + scripts/ — build.mjs, check-manifest.mjs + smoke/ — minimal load-isolation plugin + dist/index.js — committed bundle + .github/workflows/ — CI verify +``` + +--- + +## Gotchas (quick list) + +| Symptom | Likely cause | +|---------|----------------| +| Failed to fetch manifest | Non-raw GitHub URL | +| Toggle X; smoke OK | Bundle syntax / onLoad throw | +| Toggle X; smoke X | Safe mode, Revenge, or network | +| Jump OK, taps dead | Overlay not dismissed | +| Keyboard covers list | Bottom sheet host | +| Freeze on tap | Non-`openUrl` navigation path | +| Mixed version in logs | Old ring; upgrade should clear — confirm refetch | +| `/servers` missing | Old build with `shouldHide`; update plugin | +| Flat sidebar no-op | SortedGuildStore missing — expected skip | diff --git a/HANDOFF.md b/HANDOFF.md new file mode 100644 index 0000000..7214a25 --- /dev/null +++ b/HANDOFF.md @@ -0,0 +1,249 @@ +# RevengeQuickSwitcher — AI Handoff Document + +> **Purpose:** This file is a prompt for an AI agent taking over development. Read it fully before doing anything else. It describes what the project does, the current state, the environment, the tooling rules, and what's next. +> +> **Human index:** [README.md](README.md). Full clean-install setup + Hermes/Revenge gotchas: [HACKING.md](HACKING.md). **Open work menu:** [OPTIONS.md](OPTIONS.md). Device checklist: [TESTING.md](TESTING.md). Release notes: [CHANGELOG.md](CHANGELOG.md). Git history has the detailed narrative of every change; this file is the condensed durable record. + +--- + +## What this project does + +**RevengeQuickSwitcher** (display name: **Quick Server Switcher**) is a Revenge Discord mobile plugin for fast server navigation: + +- `/servers` opens a **top-docked searchable switcher** (keyboard-safe); tap a row to jump +- Fuzzy search, aliases, excludes, recent-jump slots (`/servers recent`, `/servers rN`) +- Optional **flat sidebar** (alphabetical, folder-free) +- Bot-message list remains a **fallback** when sheet/alert APIs are missing +- Jump path: dismiss overlay → `openUrl("https://discord.com/channels/{guild}/{channel}")` (JumpTo / Stealmoji pattern) + +Install URL (raw base — not the GitHub HTML page): + +``` +https://raw.githubusercontent.com/djbclark/RevengeQuickSwitcher/main/ +``` + +Smoke plugin (load isolation): + +``` +https://raw.githubusercontent.com/djbclark/RevengeQuickSwitcher/main/smoke/ +``` + +--- + +## 🚦 Cold-start — current state (read this first) + +**As of 2026-07-10.** Released on `main`: **v4.5.9**. + +| Field | Value | +|-------|-------| +| Package / manifest version | `4.5.9` | +| Display name | Quick Server Switcher | +| Bundle | Vendetta IIFE, ES2015 target, `__QSS_VERSION__` injected | +| Unit tests | **96** Vitest tests (`make verify`) | +| Open human gate | **A1** — device QA on Revenge Android | + +**Working navigation (device-proven):** + +1. Open switcher via `/servers` or settings **Open switcher** +2. Host is **top-docked** `openAlert` panel (not bottom ActionSheet — keyboard covers bottom sheets) +3. On pick / Close: `dismissThenRun` / `hideSwitcherSheet` fully tears down the host +4. Then `openUrl` deep link to last/default channel in that guild +5. Do **not** call loose `selectChannel`, Flux `CHANNEL_SELECT` / `GUILD_SELECT`, or `selectGuild` for the jump — those froze or failed to stick on device + +**Recent landings (v4.5.x freeze / overlay saga):** + +| Ver | What landed | Device outcome | +|-----|-------------|----------------| +| 4.5.4 | Drop loose `selectChannel`; Flux CHANNEL/GUILD_SELECT | Still froze | +| 4.5.5 | Prefer `selectGuild`; version-stamp debug lines | CHANNEL_SELECT verified then freeze; selectGuild didn't stick | +| 4.5.6 | JumpTo-style `openUrl` only | Jump worked; taps dead after | +| 4.5.7 | Harder dismiss before `openUrl` | Still dead taps (leftover overlay) | +| 4.5.8 | Native `ActionSheet` + `hideActionSheet` then `openUrl` | Jump + taps OK; keyboard covered bottom sheet | +| 4.5.9 | Restore **top-docked** panel; keep dismiss-then-`openUrl`; no full-screen scrim; Filter not auto-focused | Keyboard-safe; taps OK | + +**Known device facts:** + +- `SortedGuildStore not found` → flat sidebar patch is skipped (lower priority; not a start failure) +- Debug ring persists across restarts; every line stamped `[vX.Y.Z …]`; ring clears on version upgrade +- Settings → **Copy debug logs** pastes a single `|`-separated line (Discord mobile clipboard drops newlines) +- Cloud agents **cannot** reach the phone over ADB; device QA is operator-side (**A1**) + +**Next work:** [OPTIONS.md](OPTIONS.md) — open items only. Primary gate: **A1** retest of v4.5.9 (top-dock above keyboard; taps after jump; logs show `v4.5.9` + `openUrl`). Feature backlog highlights: **C4** pins, **C2** channel jump (high risk), **C3** folder-aware sort, **D1** Metro smoke harness. + +**Verify / ship:** + +```bash +make install # once +make verify # typecheck + 96 tests + build + manifest hash +``` + +After source edits: commit updated `dist/index.js` + `manifest.json` `hash` (verify rewrites hash). Bump `package.json` + `manifest.json` `version` together; update `CHANGELOG.md`. + +--- + +## Agent conventions + +### Device preference (when operator has stayturgid fleet) + +Same order as stayturgid when a phone must be used and the choice does not matter: + +1. **s24** (Galaxy S24) — preferred +2. **hd8** (Kindle Fire HD 8) — second +3. **p7a** (Pixel 7a) — third (daily driver; avoid unless needed) + +Announce before live UI work when someone may be on the device: + +`🚨📱🚨 USING — s24 — Revenge QA — ~N min` + +When done: `✅📱✅ FREE — s24 ✅📱✅` + +Mac→Android UI automation research lives in the **stayturgid** repo (`docs/research/mac-android-ui-automation.md`). This plugin repo does **not** ship Handsets/Appium harnesses yet (**D1**). Prefer Vitest here; any future device harness should stay thin (e.g. Vitest + Handsets CLI), not Appium-first. + +### Cloud / Desktop resume + +This project's cloud-agent runs are under the same Cursor account as stayturgid work. Example resume URL for the docs/nav saga context: + +``` +https://cursor.com/agents/bc-0b0c3481-2bce-460e-a05e-55297c36db57 +``` + +Repo: `https://github.com/djbclark/RevengeQuickSwitcher` (GitHub may also show `revengequickswitcher` casing). Default base branch: **`main`**. Feature branches for cloud agents: `cursor/-db57`. + +### Do / don't + +| Do | Don't | +|----|-------| +| Keep bot-message fallback when sheet APIs missing | Call loose Metro `selectChannel` / Flux select for jumps | +| Dismiss switcher host **before** `openUrl` | Leave full-screen scrims / nested RN `Modal` hosts | +| Target ES2015 IIFE; avoid `??=` / optional-chain in output | Eval-time `storage` / top-level `this` (breaks enable) | +| Stamp debug lines with plugin version | Mix multi-version debug pastes without clearing ring | +| Update OPTIONS status + CHANGELOG in the same PR as behavior | Renumber shipped option IDs | + +--- + +## How updates work + +GitHub `main` is the source of truth. Revenge loads `manifest.json` + `main` (`dist/index.js`) from the raw URL. + +1. Edit `src/`, bump version in `package.json` + `manifest.json` when shipping behavior. +2. `make verify` (rebuilds `dist/`, refreshes `hash`). +3. Update `CHANGELOG.md` + OPTIONS statuses. +4. Commit, push, open PR → merge to `main`. +5. On device: plugin info → **Refetch**, or delete + reinstall raw URL; force-quit Discord. + +Semver policy: top of [CHANGELOG.md](CHANGELOG.md). + +--- + +## Key files + +``` +src/ + index.tsx # Plugin entry: settings, flat sidebar patch, /servers, navigateToGuild + sheets.tsx # Top-docked switcher + dismissThenRun + openSwitcherUi + command.ts # /servers logic (testable without Revenge mocks) + aliases.ts # Alias normalize / merge (clipboard export-import) + excludes.ts # Exclude-rule parse/match + recents.ts # Recent-history helpers (plugin-only recording) + sidebar.ts # Flat sidebar flatten/sort + cache + theme.ts # Settings colors + utils.ts # Fuzzy match, sanitization + revenge-mod.d.ts # @revenge-mod/* stubs + __QSS_VERSION__ + *.test.ts # Vitest unit tests +scripts/ + build.mjs # esbuild → Vendetta IIFE, ES2015, version define + check-manifest.mjs # manifest + dist hash gate +smoke/ # Tiny plugin to isolate Revenge load failures +dist/index.js # Committed bundle Revenge evals +manifest.json # name, version, hash, authors +OPTIONS.md # Living backlog (A1, B*, C*, D*) +TESTING.md # Local verify + device checklist +HACKING.md # Dev setup +HANDOFF.md # This file +``` + +--- + +## Architecture notes (durable) + +### Navigation + +`navigateToGuild` in `src/index.tsx`: + +- Resolve a channel id (last selected / default / first selectable) +- Require `findByProps("openUrl")` (or `openURL` casing) +- `openUrl("https://discord.com/channels/{guildId}/{channelId}")` +- Treat as fire-and-forget; SelectedGuildStore may update async + +Prior art: **aliernfrog/JumpTo**, **Stealmoji** (`hideActionSheet` before side effects). + +### Switcher UI + +`src/sheets.tsx`: + +- Prefer top-docked `openAlert` host (`SwitcherTopPanel`) so Android keyboard does not cover the list +- Bottom native `ActionSheet` worked for taps (4.5.8) but failed keyboard UX → reverted for primary path in 4.5.9 +- `dismissThenRun`: hide/dismiss first, then run `onPick` → `openUrl` +- Simple action sheet + bot messages as degraded paths + +### Slash command + +Revenge inverted `shouldHide` historically hid `/servers` — omit that flag and fill command metadata (see CHANGELOG 4.4.5). Replies use `sendBotMessage` when falling back to in-channel lists. Unregister-before-register avoids duplicates. + +### Bundle shape + +Revenge evals roughly: `vendetta => { return }` then `ret?.default ?? ret`. Build wraps CJS in `(function(exports){ ...; return exports })({})`. Hermes rejects some modern syntax → **ES2015** target. + +--- + +## Known issues / gotchas + +- **Paste GitHub HTML URL** → “Failed to fetch manifest”. Must use `raw.githubusercontent.com/.../main/`. +- **Safe Mode** → plugins do not start. +- **X on toggle** → start failed; try smoke plugin; check Copy debug logs / logcat. +- **Dead taps after jump** → almost always leftover overlay host, not failed `openUrl`. Dismiss harder; avoid full-screen custom scrims. +- **Keyboard covers list** → do not use bottom ActionSheet as the primary switcher host on Android. +- **Flat sidebar silent skip** → SortedGuildStore missing on some builds; log and continue. +- **Clipboard newlines** → Copy debug logs is one line on purpose. +- **Cloud VM has no phone** — never claim device QA passed from CI alone. + +--- + +## Repository & environment + +| Field | Value | +|-------|-------| +| GitHub | `github.com/djbclark/RevengeQuickSwitcher` | +| Default branch | `main` | +| Runtime | Discord mobile + Revenge (Hermes) | +| Dev machine | Node 18+ (20+ recommended), npm | +| CI | `.github/workflows/ci.yml` → `npm run verify` | +| Author Discord ID | `689173209785958424` | + +Related lab / automation context (separate repo): [stayturgid](https://github.com/djbclark/stayturgid) — fleet ADB/SSH, Handsets, ScreenControlSession. Do not conflate deploy tooling; QSS ships only the plugin + docs. + +--- + +## Changelog (condensed — see CHANGELOG.md) + +- **2026-07-10** — Docs: HANDOFF / HACKING / README index (this work). +- **4.5.9** — Top-docked switcher above keyboard; keep dismiss-then-`openUrl`. +- **4.5.8** — Native ActionSheet host (Stealmoji); fixed dead taps. +- **4.5.6–4.5.7** — `openUrl` jump; dismiss-before-navigate. +- **4.5.2–4.5.5** — Overlay/freeze iterations; Copy debug logs; version-stamped ring. +- **4.4.x** — Install URL / IIFE / Hermes enable / slash menu / bot replies. +- **4.1–4.3** — Theme settings, aliases export, recents, excludes, debug toggle. + +--- + +## Appendix — Strategic directions + +| Track | Summary | Best when… | +|-------|---------|------------| +| **A — Device QA** | Close **A1** on v4.5.9; capture Copy debug logs | Operator has Revenge phone | +| **B — Switcher polish** | Pins (**C4**), paging UX, settings entry points | A1 green; sheet path stable | +| **C — High-risk Metro** | Channel jump (**C2**), folder-aware sort (**C3**) | Explicit ask; expect client churn | +| **D — Harness** | Metro smoke / optional Handsets-driven QA (**D1**) | Repeatable device regression needed | +| **E — Docs only** | Keep HANDOFF/OPTIONS/TESTING current | After every behavior PR | + +**Rejected / avoid:** faux DM or fake server as switcher UI (**C8**); Flux/`selectChannel` jump paths; full-screen touch-blocking scrims; Appium-first automation for this small plugin. diff --git a/OPTIONS.md b/OPTIONS.md index 0678cd7..dd6272c 100644 --- a/OPTIONS.md +++ b/OPTIONS.md @@ -2,6 +2,8 @@ Living backlog of product and engineering options. Keep this file current whenever priorities change, and push updates to GitHub with the related work. +Agent cold-start: [HANDOFF.md](HANDOFF.md) · Dev setup: [HACKING.md](HACKING.md) · Device checklist: [TESTING.md](TESTING.md). + **How to reference:** each section has a letter; each option has a number. Say **A1**, **C3**, etc. Status legend: **Ready** · **Needs input** · **Done** · **Idea** diff --git a/README.md b/README.md index 714fefa..54b2bca 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,36 @@ # RevengeQuickSwitcher -A high-performance server navigation utility built natively for the **Revenge** Discord mobile client. +A high-performance server navigation utility built natively for the **Revenge** Discord mobile client (display name: **Quick Server Switcher**). + +--- + +## Documentation + +| Document | Purpose | +|----------|---------| +| [HANDOFF.md](HANDOFF.md) | Maintainer / AI cold-start — current state, nav invariants, gotchas | +| [HACKING.md](HACKING.md) | Developer setup, Hermes/IIFE constraints, debug loop | +| [OPTIONS.md](OPTIONS.md) | Living backlog (reference IDs like `A1`, `C4`) | +| [TESTING.md](TESTING.md) | Local `make verify` + Revenge device checklist | +| [CHANGELOG.md](CHANGELOG.md) | Release notes and semver policy | + +--- ## Features -- **Fuzzy-search navigation**: Jump to any server via subsequence matching (e.g. typing `wsh` finds `Wayland High School`; subsequence needs 3+ characters). +- **Switcher sheet**: `/servers` opens a top-docked searchable panel (keyboard-safe); tap to jump. Bot-message list remains a fallback when sheet APIs are missing. +- **Fuzzy-search navigation**: Jump via subsequence matching (e.g. typing `wsh` finds `Wayland High School`; subsequence needs 3+ characters). - **Recent servers**: `/servers recent` and `/servers r1` jump slots; history recorded only when this plugin navigates. - **Excluded servers**: Skip noisy or similarly named guilds in search (optional hide from list). - **Ambiguous-match pick list**: When several servers share the best score, lists them instead of guessing. - **Custom aliases**: Map shortcodes to full server names in settings (e.g. `chess=Maynard-area Chess Club`), with clipboard export/import. -- **Flat sidebar mode**: Overrides Discord's native UI to present an alphabetically sorted, folder-free guild list. -- **Smart pagination**: Pages by item count (up to 40) and character budget so responses stay under Discord's 2000-character limit, with numeric page aliases (`/servers 2`). -- **Debug logging**: Optional setting that logs Metro/patch/command diagnostics through Revenge's logger. +- **Flat sidebar mode**: Overrides Discord's native UI to present an alphabetically sorted, folder-free guild list (skipped gracefully if SortedGuildStore is missing). +- **Smart pagination**: Pages by item count (up to 40) and character budget so fallback replies stay under Discord's 2000-character limit, with numeric page aliases (`/servers 2`). +- **Debug logging**: Optional Metro/patch/command diagnostics plus **Copy debug logs** (version-stamped, clipboard-safe single line). + +Jump path uses Discord deep links (`openUrl`), matching known-good Revenge plugins (JumpTo / Stealmoji). See [HANDOFF.md](HANDOFF.md) before changing navigation. + +--- ## Installation (Revenge Client) @@ -45,14 +64,18 @@ https://raw.githubusercontent.com/djbclark/RevengeQuickSwitcher/main/smoke/ 1. **Safe Mode** — Revenge Settings → disable Safe Mode if enabled (plugins do not start in safe mode). 2. **Developer settings** — Revenge Settings → Developer (may require tapping the version repeatedly). Useful: debugger URL, React DevTools, Eval command. 3. **`/debug`** — built-in Revenge command; prints client/Revenge/React versions to chat. -4. **In-plugin debug buffer (easiest to share)** — open Quick Server Switcher settings → **Copy debug logs**, then paste into chat/GitHub. The paste is a single line (` | `-separated) because Discord mobile clipboard often drops newlines. Logs persist across restarts. +4. **In-plugin debug buffer (easiest to share)** — open Quick Server Switcher settings → **Copy debug logs**, then paste into chat/GitHub. The paste is a single line (` | `-separated) because Discord mobile clipboard often drops newlines. Logs persist across restarts and are stamped with the plugin version. 5. **Logcat (Android)** — with USB debugging: `adb logcat | grep -iE 'revenge|vendetta|Quick|plugin|hermes'`. Plugin start errors are logged as `Plugin errored whilst loading`. Switcher lines are tagged `[QuickSwitcher]`. 6. **Plugin info sheet** — the `i` icon → Refetch after a main-branch update; Delete + reinstall if the hash is stuck. When reporting a stuck switcher / failed jump, please include: Discord build (from `/debug`), whether Close dismisses the panel, whether the jump toast appeared, and the **Copy debug logs** paste. +--- + ## Development +Full setup, Hermes constraints, and device debug loop: **[HACKING.md](HACKING.md)**. Agent / maintainer cold-start: **[HANDOFF.md](HANDOFF.md)**. + ### Prerequisites - Node.js 18+ (Node 20+ recommended) @@ -71,7 +94,7 @@ make install # or: npm install | Command | Description | |---------|-------------| | `make build` | Bundle `src/` to `dist/index.js` via esbuild | -| `make test` | Run unit tests | +| `make test` | Run unit tests (96) | | `make typecheck` | Type-check all `src/` modules (including `index.tsx`) | | `make verify` | Run typecheck, tests, build, and manifest validation | | `make clean` | Remove `node_modules/` (keeps committed `dist/`) | @@ -90,7 +113,8 @@ npm run verify ``` src/ - index.tsx # Plugin entry: settings UI, flat sidebar patch, command wiring + index.tsx # Plugin entry: settings UI, flat sidebar patch, command wiring, openUrl jump + sheets.tsx # Top-docked switcher UI + dismiss-then-run excludes.ts # Exclude-rule parse/match helpers aliases.ts # Alias normalize / merge helpers for clipboard export-import recents.ts # Recent-history helpers (low-risk plugin-only recording) @@ -101,27 +125,36 @@ src/ revenge-mod.d.ts # Type stubs for @revenge-mod/* imports *.test.ts # Vitest unit tests scripts/ + build.mjs # Vendetta IIFE, ES2015, __QSS_VERSION__ inject check-manifest.mjs # Validates manifest.json and dist/index.js (run via verify) +smoke/ # Minimal plugin for load isolation dist/ index.js # Built output consumed by Revenge (commit after build) manifest.json # Revenge plugin metadata (display name: Quick Server Switcher) +HANDOFF.md # AI / maintainer handoff +HACKING.md # Developer environment OPTIONS.md # Living backlog of product/engineering options +TESTING.md # Local + device test plan CHANGELOG.md # Release notes ``` -After changing source files, run `make build` and commit the updated `dist/index.js` so the plugin loads correctly from GitHub. +After changing source files, run `make build` (or `make verify`) and commit the updated `dist/index.js` so the plugin loads correctly from GitHub. + +--- ## Usage -- `/servers` — list servers (paginated) -- `/servers query:` — fuzzy-search and jump to a server -- `/servers 2` — jump to page 2 of the server list +- `/servers` — open switcher (or bot-message list fallback) +- `/servers query:` — fuzzy-search and jump (or open filtered sheet / pick list) +- `/servers 2` — jump to page 2 of the server list (fallback pagination) - `/servers recent` — list recent jumps from this plugin - `/servers r1` — jump to recent slot 1 (also `r2`, …) -Configure **Flat Sidebar**, **Debug Logging**, **Excluded servers**, **Recent servers**, and **Custom Aliases** (with **Copy** / **Import**) under the plugin settings in Revenge. +Configure **Flat Sidebar**, **Debug Logging**, **Excluded servers**, **Recent servers**, and **Custom Aliases** (with **Copy** / **Import**) under the plugin settings. Use **Open switcher** or **Copy debug logs** from settings as needed. -See **[OPTIONS.md](OPTIONS.md)** for the product backlog (reference IDs like `A1`, `C5`) and **[CHANGELOG.md](CHANGELOG.md)** for release notes and the semver policy. +See **[OPTIONS.md](OPTIONS.md)** for the product backlog and **[CHANGELOG.md](CHANGELOG.md)** for release notes and the semver policy. + +--- ## Testing @@ -133,13 +166,16 @@ Quick pre-release check: make verify ``` -Then walk the checklist at the bottom of `TESTING.md` on your device. +Then walk the checklist at the bottom of `TESTING.md` on your device (**OPTIONS A1**). + +--- ## Contributing 1. Fork the repo and create a branch. 2. Make changes in `src/`, run `make verify`. -3. Open a pull request with a clear description of the change. +3. Update docs (`CHANGELOG.md` / `OPTIONS.md` / handoff notes) when behavior changes. +4. Open a pull request with a clear description of the change. Bug reports and feature requests are welcome via [GitHub Issues](https://github.com/djbclark/RevengeQuickSwitcher/issues). diff --git a/TESTING.md b/TESTING.md index 71f731e..90d046f 100644 --- a/TESTING.md +++ b/TESTING.md @@ -2,6 +2,8 @@ This guide covers verification before a release: automated checks on your machine, then manual validation on a Revenge Discord client. +Related: [HANDOFF.md](HANDOFF.md) (current state / nav invariants) · [HACKING.md](HACKING.md) (dev setup) · [OPTIONS.md](OPTIONS.md) (**A1** device QA). + ## Prerequisites ### Local (developer machine) @@ -46,7 +48,7 @@ This runs, in order: All steps exit with code 0. You should see: ``` -Tests 86 passed (86) +Tests 96 passed (96) dist/index.js ~18kb manifest ok (v4.5.9) ``` From 6c665d59e046642f89d6e99cf5b3cf8f034839a9 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 10 Jul 2026 00:59:44 +0000 Subject: [PATCH 2/4] Reshape OPTIONS.md to stayturgid open-work format. Open IDs only with tracks and risk; closed items summarized at the bottom. Keep stable A/C/D IDs; update HANDOFF/CHANGELOG pointers. Co-authored-by: Daniel JB Clark --- CHANGELOG.md | 1 + HANDOFF.md | 2 +- OPTIONS.md | 220 +++++++++++++++++++++++---------------------------- 3 files changed, 102 insertions(+), 121 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 992e64c..66c2027 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,7 @@ Keep this file updated in the same PR/commit as the code. GitHub Releases should ## [Unreleased] - Docs: add stayturgid-style `HANDOFF.md` / `HACKING.md`; README documentation index; cross-links from OPTIONS/TESTING +- Docs: reshape `OPTIONS.md` to stayturgid open-work format (tracks, open IDs only, closed summary) ## 4.5.9 diff --git a/HANDOFF.md b/HANDOFF.md index 7214a25..34ab527 100644 --- a/HANDOFF.md +++ b/HANDOFF.md @@ -68,7 +68,7 @@ https://raw.githubusercontent.com/djbclark/RevengeQuickSwitcher/main/smoke/ - Settings → **Copy debug logs** pastes a single `|`-separated line (Discord mobile clipboard drops newlines) - Cloud agents **cannot** reach the phone over ADB; device QA is operator-side (**A1**) -**Next work:** [OPTIONS.md](OPTIONS.md) — open items only. Primary gate: **A1** retest of v4.5.9 (top-dock above keyboard; taps after jump; logs show `v4.5.9` + `openUrl`). Feature backlog highlights: **C4** pins, **C2** channel jump (high risk), **C3** folder-aware sort, **D1** Metro smoke harness. +**Next work:** [OPTIONS.md](OPTIONS.md) — **open work only** (stayturgid-style). When asked for options, present open IDs with risk, then replace the list after shipping. Primary gate: **A1** retest of v4.5.9. Feature highlights: **C4** pins, **C2**/**C3** (high Metro — explicit ask), **D1** smoke harness, latent **C1b**. **Verify / ship:** diff --git a/OPTIONS.md b/OPTIONS.md index dd6272c..fffce16 100644 --- a/OPTIONS.md +++ b/OPTIONS.md @@ -1,171 +1,151 @@ -# Options — RevengeQuickSwitcher +# OPTIONS — open work -Living backlog of product and engineering options. Keep this file current whenever priorities change, and push updates to GitHub with the related work. +> **For agents:** When the operator asks for **options** or **next steps**, read this +> file, present the open items **with descriptions and risk**, do any requested work, +> then **replace** this list (drop completed items; keep IDs stable). **Commit and +> push** in the same turn. +> +> Session context: [HANDOFF.md](HANDOFF.md). Dev setup: [HACKING.md](HACKING.md). +> Device checklist: [TESTING.md](TESTING.md). Release notes: [CHANGELOG.md](CHANGELOG.md). +> Strategic directions: [HANDOFF.md appendix](HANDOFF.md#appendix--strategic-directions). -Agent cold-start: [HANDOFF.md](HANDOFF.md) · Dev setup: [HACKING.md](HACKING.md) · Device checklist: [TESTING.md](TESTING.md). +**Plugin snapshot (2026-07-10):** Released on `main` as **v4.5.9** — top-docked +switcher, dismiss-then-`openUrl` jump, Copy debug logs. Unit gate: `make verify` +(96 tests). Cloud agents cannot reach the phone; **A1** is the human/device gate. -**How to reference:** each section has a letter; each option has a number. Say **A1**, **C3**, etc. +**Risk scale:** **Low** = mostly our code / storage / docs · **Medium** = Metro/UI +discovery with graceful fallbacks · **High** = deep Discord internals; easy to +break on client updates · **Latent** = only act if a symptom returns. -Status legend: **Ready** · **Needs input** · **Done** · **Idea** +**Suggested agent order:** close or drive **A1** (device QA) before new features; +prefer **C4** (pins) over **C2**/**C3** (high Metro surface). Do not reintroduce +Flux/`selectChannel` jump paths or full-screen scrims (see HANDOFF). -**Risk scale:** **Low** (mostly our code / storage) · **Medium** (some Metro/UI discovery; graceful fallbacks possible) · **High** (deep Discord internals; easy to break on client updates) - -Every option below must include an explicit **Risk** value. +**How to reference:** say **A1**, **C4**, **D1**, etc. Keep IDs stable forever; +when an item ships, move it to **Closed** (do not renumber). --- -## A — Needs human input +## Pick a track -| ID | Option | Risk | Why blocked | Notes | -|----|--------|------|-------------|-------| -| **A1** | Device QA | **Low** (process) | Requires a Revenge Discord client and manual checklist | **v4.5.9**. Retest: top-docked switcher stays above keyboard; after jump, taps still work. Logs: `v4.5.9` + `openUrl`. | +| Track | Focus | Open IDs | Typical risk | +|-------|-------|----------|--------------| +| **A — Device QA** | Revenge client checklist | A1 | Low (process); blocks confidence in sheet/nav | +| **B — Switcher polish** | Pins and list UX on stable sheet | C4 | Low–Medium | +| **C — High-risk Metro** | Channels / folder-aware sidebar | C2, C3 | Medium–High | +| **D — Engineering** | Harness / smoke | D1 | Low | +| **E — Latent follow-ups** | Only if a symptom returns | C1b | Latent / Medium–High | --- -## B — Recently shipped - -| ID | Option | Status | Risk | Summary | -|----|--------|--------|------|---------| -| **B1** | Manifest author Discord ID | **Done** | **Low** | `authors[].id` set to `689173209785958424`. | -| **B2** | Search pick-list on ties | **Done** (v4.1.0) | **Low** | List tied matches instead of auto-jumping. | -| **B3** | Theme-aware settings | **Done** (v4.1.0) | **Medium** | Semantic tokens with dark fallbacks. | -| **B4** | Debug logging toggle | **Done** (v4.1.0) | **Low** | Metro/patch/command diagnostics. | -| **B5** | Versioned release | **Done** (v4.1.0) | **Low** | GitHub tag + release notes. | -| **B6** | Changelog + semver policy | **Done** | **Low** | Documented in `CHANGELOG.md`. | -| **B7** | Export / import aliases | **Done** (v4.2.0) | **Medium** | Clipboard APIs vary; toast if unavailable. | -| **B8** | Recent-servers jump (low-risk) | **Done** (v4.3.0) | **Low** | History only when this plugin navigates; no guild-select hooks. | -| **B9** | Mute / exclude servers | **Done** (v4.4.0) | **Low** | Name/id/`~partial` rules; optional hide from list. | -| **B10** | Fix Revenge install URL / polymanifest | **Done** (v4.4.1) | **Low** | Raw GitHub URL + Vendetta-compatible bundle/`hash`. | -| **B11** | Fix plugin enable / settings wrench | **Done** (v4.4.2) | **Low** | Command description + resilient onLoad/settings. | -| **B12** | Vendetta IIFE rebuild + smoke plugin | **Done** (v4.4.3) | **Low** | Match known-working bundle shape; isolate load failures. | -| **B13** | Main enable after smoke OK | **Done** (v4.4.4) | **Low** | ES2015 Hermes-safe bundle + no eval-time storage/`this`. | -| **B14** | `/servers` missing from slash menu | **Done** (v4.4.5) | **Low** | Revenge inverted `shouldHide` filter; omit it + fill command metadata. | -| **B15** | `/servers` silent + duplicate | **Done** (v4.4.7) | **Low** | `sendBotMessage` replies; unregister-before-register. | -| **B16** | `/servers query` silent no-op | **Done** (v4.4.7) | **Medium** | Jump/error bot replies + harder nav + arg unwrap. | -| **B17** | Switcher sheet + tappable picks (C5/C8) | **Done** (v4.5.9) | **Medium** | Top-docked searchable panel + simple sheet; bot-message fallback. | -| **B18** | Freeze / dead UI after jump | **Done** (v4.5.9) | **High** | dismiss-then-openUrl (Stealmoji); top-dock for keyboard; no full-screen scrim. | - ---- - -## C — Feature ideas - -### C1 — Recent-servers jump +### Track A — Device QA -**Status:** **Done** (v4.3.0, low-risk path) — see B8. +#### A1 — Device QA (human + agent assist) · Risk: **Low** (process) -**Shipped:** `/servers recent`, `/servers rN`, history size + clear in settings. History updates only when Quick Server Switcher successfully jumps. +Requires a Revenge Discord client and the checklist in [TESTING.md](TESTING.md). -**Possible follow-up (not scheduled):** auto-track via guild-select Metro hooks. +**Retest on v4.5.9:** -**Risk (follow-up):** **Medium–High** — Discord “current guild” / select modules churn. -**Risk (shipped path):** **Low** +1. Top-docked switcher stays **above** the Android keyboard while filtering. +2. After a server tap, jump lands and Discord taps still work (no dead UI). +3. Copy debug logs show `v4.5.9` and `openUrl` (not mixed older versions). +4. Close dismisses the panel; bot-message fallback still OK if sheet APIs missing. -### C2 — Channel search / jump +Close **A1** when the operator signs off (or a future harness covers the same +assertions). Agents: prepare checklists / interpret log pastes; do not claim +pass from CI alone. -**What it is:** Search and jump to channels, not only servers. - -**Complexity:** High -**Risk:** **High** — channel stores, permissions, and navigation APIs are a large Metro surface and break often across Discord versions. -**Fit:** Strong power-user feature; may deserve a separate plugin - -### C3 — Folder-aware (non-flat) sort - -**What it is:** Keep Discord folders, but sort inside them and/or sort folder nodes—modes beyond today’s all-or-nothing flat list. +--- -**Complexity:** Medium -**Risk:** **Medium** — folder node shapes vary; need defensive parsing and device tests. Wrong assumptions can scramble the sidebar. -**Fit:** Natural Flat Sidebar extension +### Track B — Switcher polish -### C4 — Favorites / pinned servers +#### C4 — Favorites / pinned servers (agent) · Risk: **Low** (list-only) / **Medium** (flat sidebar) -**What it is:** A user-chosen set of servers that always float to the top of `/servers` (and optionally the flat sidebar), independent of alphabetical order or recent activity. +User-chosen servers that always float to the top of `/servers` (and optionally +the flat sidebar), independent of A–Z order or recents. **User-facing shape:** -- Settings: list or multi-select of pinned guilds (by name/id), reorder, clear -- `/servers` list: pinned block first, then the rest A–Z (or under a “Pinned” heading) -- Optional: flat sidebar pins the same IDs to the top -- Optional later: `/servers query:p1` shortcodes like recents +- Settings: ordered pins by name/id, reorder, clear +- Switcher / list: pinned block first, then the rest A–Z +- Optional later: `/servers query:p1`-style shortcodes; export with aliases -**How it would work:** Store ordered guild IDs in plugin storage. When building the sorted guild list for the command (and optionally `transformFlatSidebar`), partition into pinned vs unpinned, preserve pin order, sort the remainder as today. Resolve names via GuildStore; drop or flag stale IDs if a server was left. +**How:** store ordered guild IDs in plugin storage; partition pinned vs +unpinned when building the list; resolve names via GuildStore; drop/flag stale +IDs after leaving a server. -**Why bother:** Aliases speed *search*. Pins change *priority and visibility*. A school server you always want first shouldn’t depend on remembering `wsh` or hoping it was recent. +**Why:** aliases speed *search*; pins change *priority*. Complements recents +(**C1** / B8) without Metro guild-select hooks. -**Vs C1:** Pins are explicit and stable; recents are automatic and change as you navigate. Many switchers offer both. +**Depends on:** sheet path stable (**A1** preferred first). Pairs with excludes +and alias export. -**Complexity:** Low–medium (command list is straightforward; sidebar pinning needs care with folders when flat mode is off) -**Risk:** **Low** for `/servers` list-only pins (pure data + existing sort pipeline). **Medium** if also rewriting flat-sidebar order (same patch path as today; must not break folder mode / cache checksums). Stale IDs after leaving a server are a mild UX risk, not a crash risk if handled. -**Fit:** High QoL; complements aliases and C1 -**Depends on / pairs with:** C1, C7 (exclude), B7 (could export pins later) - -### C5 — Interactive disambiguation UI - -**Status:** **Done** (v4.5.0) — tappable action sheet / switcher sheet on search ties; markdown pick list remains as fallback. - -**What it is:** Tappable alert/action sheet when multiple servers tie, instead of a read-only markdown pick list. +--- -**Complexity:** Medium -**Risk:** **Medium** — Revenge/Vendetta alert APIs differ by build; must keep markdown fallback (B2). -**Fit:** Direct upgrade to B2 -**Pairs with:** **C8** (full switcher sheet can absorb this) +### Track C — High-risk Metro (explicit ask only) -### C6 — Export / import aliases +#### C2 — Channel search / jump (agent) · Risk: **High** -**Status:** **Done** (v4.2.0) — see B7. -**Risk:** **Medium** (clipboard module availability) — mitigated with toasts when unavailable. +Search and jump to channels, not only servers. Large Metro surface +(permissions, channel stores, navigation); breaks often across Discord +versions. May deserve a **separate plugin**. Do not start unless the operator +explicitly picks this. -### C7 — Mute / exclude servers from search +#### C3 — Folder-aware (non-flat) sort (agent) · Risk: **Medium** -**Status:** **Done** (v4.4.0) — see B9. +Keep Discord folders, but sort inside them and/or sort folder nodes — modes +beyond today’s all-or-nothing flat list. Folder node shapes vary; wrong +assumptions scramble the sidebar. Needs defensive parsing + device tests +(**A1**-style). Natural Flat Sidebar extension; still explicit-ask preferred. -**Shipped:** Settings text rules (exact name, Discord id, or `~partial`); always skipped by fuzzy search; optional hide from `/servers` list. Recents slots still work for previously recorded ids. +--- -**Risk:** **Low** +### Track D — Engineering -### C8 — Dedicated switcher UI (not in-channel) +#### D1 — Integration smoke / Metro self-check (agent) · Risk: **Low** -**Status:** **Done** (v4.5.9) — `/servers` opens a **top-docked** searchable panel (keyboard-safe) with Stealmoji-style dismiss-then-jump; settings has **Open switcher**; bot-message list remains fallback when sheet APIs are missing. +Document expected Metro props (`openUrl`, alert/sheet hosts, GuildStore, …). +Optional runtime self-check when debug logging is on. Worst case: noisy logs, +not broken navigation. Optional later: thin Handsets-driven QA (stayturgid +research) — Vitest remains the default `make test`; do not Appium-first. -**What it is:** Open a real UI surface for `/servers` instead of posting bot messages into the current channel. +--- -**Recommendation:** **Yes, pursue a sheet/modal — not a faux DM or fake server.** +### Track E — Latent follow-ups (symptom-driven) -| Approach | Verdict | Why | -|----------|---------|-----| -| **Action sheet / custom modal** with search field + tappable server rows | **Best fit** | Matches Discord mobile patterns; no channel spam; taps can jump immediately; builds on C5 | -| **Plugin settings-style screen** pushed onto the nav stack | **Good alternate** | Same React patterns we already use for settings; slightly heavier than a sheet | -| **Faux bot / DM “person” to talk to** | **Weak** | Still chat UX; typing latency; hard to make feel native; confusing vs real DMs | -| **Faux Discord server / channel** | **Avoid** | High Metro risk (guild/channel injection), permission/UI edge cases, looks like malware to users, breaks on client updates | +#### C1b — Auto-track recents via guild-select hooks (agent) · Risk: **Latent / Medium–High** -**User-facing shape (preferred):** +Shipped recents (**C1** / B8) only record when *this* plugin navigates. A +follow-up could hook Discord “current guild” / select modules for automatic +history. **Do not start** without a clear product ask — high churn, easy to +freeze (see v4.5.x saga in HANDOFF). Trigger: operator wants sidebar-driven +recents and accepts Metro risk. -1. `/servers` (no args) → opens switcher sheet: search box, recent strip, A–Z list, tap to jump -2. `/servers query:…` → either jump immediately when unambiguous, or open the sheet pre-filtered -3. Keep a **fallback** to today’s bot-message list if the sheet API is missing on a given Revenge/Discord build -4. Optional later: entry from plugin settings (“Open switcher”) so you don’t need slash at all +--- -**Why bother:** In-channel replies clutter chat, feel like a workaround, and make search/jump harder to discover. A sheet is the natural mobile switcher UX. +**Non-goals / do-not-touch:** -**Complexity:** Medium (sheet + list + search reuse existing command/search logic) -**Risk:** **Medium** — depends on Revenge/Discord alert / action-sheet / navigation APIs that churn; must keep slash + bot-message fallback. Fake server/DM approaches are **High** risk and not worth it. -**Fit:** High — this is the long-term home for list, pick-list (C5), recents, and pins (C4) -**Depends on / pairs with:** C5, C4, A1 (device QA of sheet APIs) +- Faux DM or fake Discord server as the switcher UI (rejected in C8) +- Jump via loose `selectChannel`, Flux `CHANNEL_SELECT` / `GUILD_SELECT`, or + `selectGuild` as primary path (use dismiss-then-`openUrl`) +- Full-screen touch scrims / nested RN `Modal` hosts that outlive the sheet +- Bottom `ActionSheet` as the **primary** searchable switcher on Android + (keyboard covers it; top-dock is intentional) +- Renumbering shipped IDs; editing git history to “clean” Done items --- -## D — Engineering / maintenance +**Closed (2026-07-10):** Docs HANDOFF / HACKING / README index (PR docs branch). -| ID | Option | Status | Risk | Notes | -|----|--------|--------|------|-------| -| **D1** | Integration smoke test harness | **Idea** | **Low** | Document expected Metro props; optional runtime self-check when debug logging is on. Worst case: noisy logs, not broken navigation. | -| **D2** | Changelog discipline | **Done** | **Low** | Keep `CHANGELOG.md` in sync with tags/releases. | -| **D3** | Semantic versioning policy | **Done** | **Low** | Patch / minor / major rules live at the top of `CHANGELOG.md`. | +**Closed (v4.5.9 / B17–B18, C5, C8):** Top-docked switcher + dismiss-then-`openUrl`; +freeze/dead-tap saga; tappable disambiguation; dedicated sheet UI (not faux DM). ---- +**Closed (v4.5.2–4.5.8):** Overlay dismiss iterations; Copy debug logs; +version-stamped ring; JumpTo `openUrl`; ActionSheet host experiment. -## How to maintain this file +**Closed (v4.4.x / B9–B16, C7):** Excludes; install URL / IIFE / Hermes enable; +slash menu `shouldHide`; `sendBotMessage`; query jump replies. -1. Assign every option a stable **letter+number** ID; do not renumber shipped IDs—mark them **Done** instead. -2. Always include **Risk** (Low / Medium / High, with a short reason). -3. When finishing work, update status tables and push with the related commit. -4. Prefer short tables plus a fleshed-out subsection for non-trivial ideas. +**Closed (v4.1–4.3 / B1–B8, C1, C6, D2–D3):** Author id; pick-list; theme +settings; debug toggle; releases/changelog/semver; alias export-import; +low-risk recents. From e22806c50d950b514fc07c573e1424ce6f60799b Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 10 Jul 2026 00:59:51 +0000 Subject: [PATCH 3/4] Align README/HANDOFF/HACKING wording with open-work OPTIONS. Co-authored-by: Daniel JB Clark --- HACKING.md | 2 +- HANDOFF.md | 2 +- README.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/HACKING.md b/HACKING.md index ff0a534..9581192 100644 --- a/HACKING.md +++ b/HACKING.md @@ -205,7 +205,7 @@ UI host: prefer **top-docked** alert panel so the Android keyboard does not cove 1. Branch from `main` (cloud agents: `cursor/-db57`). 2. Implement in `src/`; add/adjust Vitest coverage for pure helpers. 3. `make verify`. -4. Update OPTIONS.md statuses / CHANGELOG when behavior ships. +4. Replace completed IDs in OPTIONS.md (keep IDs stable) and update CHANGELOG when behavior ships. 5. PR → merge → device **A1** checklist in TESTING.md. ### 5.2 What belongs in unit tests diff --git a/HANDOFF.md b/HANDOFF.md index 34ab527..cbd4996 100644 --- a/HANDOFF.md +++ b/HANDOFF.md @@ -156,7 +156,7 @@ scripts/ smoke/ # Tiny plugin to isolate Revenge load failures dist/index.js # Committed bundle Revenge evals manifest.json # name, version, hash, authors -OPTIONS.md # Living backlog (A1, B*, C*, D*) +OPTIONS.md # Open work menu (A1, C2–C4, D1, …; closed at bottom) TESTING.md # Local verify + device checklist HACKING.md # Dev setup HANDOFF.md # This file diff --git a/README.md b/README.md index 54b2bca..92368df 100644 --- a/README.md +++ b/README.md @@ -133,7 +133,7 @@ dist/ manifest.json # Revenge plugin metadata (display name: Quick Server Switcher) HANDOFF.md # AI / maintainer handoff HACKING.md # Developer environment -OPTIONS.md # Living backlog of product/engineering options +OPTIONS.md # Open work menu (tracks + risk; closed summary) TESTING.md # Local + device test plan CHANGELOG.md # Release notes ``` From e65e4b2d127f2308cbf4961d7f84797715bd90bc Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 10 Jul 2026 01:00:29 +0000 Subject: [PATCH 4/4] Finish OPTIONS open-work wording in README and HACKING. Co-authored-by: Daniel JB Clark --- HACKING.md | 2 +- README.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/HACKING.md b/HACKING.md index 9581192..713041e 100644 --- a/HACKING.md +++ b/HACKING.md @@ -254,7 +254,7 @@ RevengeQuickSwitcher/ README.md — user-facing overview + install HACKING.md — this file HANDOFF.md — AI / maintainer cold-start - OPTIONS.md — backlog (A/B/C/D IDs) + OPTIONS.md — open work menu (stable IDs) TESTING.md — verify + device QA CHANGELOG.md — semver + release notes Makefile — install / build / test / verify diff --git a/README.md b/README.md index 92368df..19fdaab 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ A high-performance server navigation utility built natively for the **Revenge** |----------|---------| | [HANDOFF.md](HANDOFF.md) | Maintainer / AI cold-start — current state, nav invariants, gotchas | | [HACKING.md](HACKING.md) | Developer setup, Hermes/IIFE constraints, debug loop | -| [OPTIONS.md](OPTIONS.md) | Living backlog (reference IDs like `A1`, `C4`) | +| [OPTIONS.md](OPTIONS.md) | Open work menu (reference IDs like `A1`, `C4`) | | [TESTING.md](TESTING.md) | Local `make verify` + Revenge device checklist | | [CHANGELOG.md](CHANGELOG.md) | Release notes and semver policy | @@ -152,7 +152,7 @@ After changing source files, run `make build` (or `make verify`) and commit the Configure **Flat Sidebar**, **Debug Logging**, **Excluded servers**, **Recent servers**, and **Custom Aliases** (with **Copy** / **Import**) under the plugin settings. Use **Open switcher** or **Copy debug logs** from settings as needed. -See **[OPTIONS.md](OPTIONS.md)** for the product backlog and **[CHANGELOG.md](CHANGELOG.md)** for release notes and the semver policy. +See **[OPTIONS.md](OPTIONS.md)** for open work (and closed IDs) and **[CHANGELOG.md](CHANGELOG.md)** for release notes and the semver policy. ---