pearcord/pearcord-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document Phase 297 completion and plan Phase 298 (v0.8.259).

Browse Source 
Roadmap, logging spans, companion progress, protocol settings URLs, and IPC meta fields.

Co-authored-by: Cursor <[email protected]>
This commit is contained in:
Raven Scott
2026-05-23 06:53:10 -04:00
co-authored by Cursor
parent d447ca5cc2
commit 0e7fe69543
5 changed files with 72 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files
COMPANION.md
+2
View File
@@ -50,3 +50,5 @@ Runs `smoke-companion-boot.cjs`, verifies `/companion/index.js` is staged, then
**v0.8.96:** **Scan with camera** uses `getUserMedia` + live `BarcodeDetector` on `#companion-qr-video` (Pear/Electron camera permission). Stop via **Stop camera**. Photo upload still available as fallback.
**v0.8.238:** Companion mirrors desktop **session-ready** and **guild-loading** gates: main layout stays hidden until `view.sessionReady`, guild rail shows a loading overlay during `loadGuild`, and **theme/density** apply from `user-prefs` with the same `localStorage` cache as desktop. Worker listens for `user-prefs`, `guild-loading`, and `session-ready`. Smoke: `test:companion-session-ready-gate`.
**v0.8.259:** Guild-loading overlay shows an indeterminate progress bar after **3 seconds** (same threshold as desktop `#guild-loading-overlay`). Session boot card shows `#companion-session-boot-progress` after **3 seconds** while `sessionReady` is false. Elapsed seconds appear in the guild loading label after **6 seconds**. Smokes: `test:companion-guild-loading-progress`, `test:companion-guild-loading-notif-defer`.
IPC.md
+1 -1
View File
@@ -129,7 +129,7 @@ Smokes: `test:guild-channel-pick-order` (IPC + platform source), `test:guild-unr
| `start-screen-share` / `stop-screen-share` | `channelId?` | Screen share signaling |
| `voice-capture-chunk` / `display-capture-frame` | binary chunks | UI → sidecar media feeds |
| `set-compose-draft` | `channelId`, `draft` | Per-channel compose draft in prefs |
| `export-diagnostics-jsonl` | `lines: string[]`, `meta?` | Write filtered diagnostics JSONL under storage; optional first-line `diagnostics-meta` with `composerTraceCount`; reply `diagnostics-jsonl-exported` (v0.8.254, meta v0.8.258) |
| `export-diagnostics-jsonl` | `lines: string[]`, `meta?` | Write filtered diagnostics JSONL under storage; optional first-line `diagnostics-meta` with `composerTraceCount`, `devLogLineCount`, `logFile`; reply `diagnostics-jsonl-exported` (v0.8.254, meta v0.8.258–259) |
### Automation, hooks, audit (v0.8.x)
LOGGING.md
+4 -2
View File
@@ -128,9 +128,9 @@ When `view.sessionError` is set on the boot card, an **Open diagnostics** button
**Clear composer** removes only buffered lines with `scope: composer` from the diagnostics panel (v0.8.257); the header `composer ×N` badge updates immediately.
**Save** (v0.8.258) prepends a `diagnostics-meta` JSON line with `composerTraceCount` and the active filter before the filtered records.
**Save** (v0.8.258+) prepends a `diagnostics-meta` JSON line with `composerTraceCount`, `devLogLineCount`, `logFile` (absolute path to `pearcord.log` under storage), and the active filter before the filtered records (v0.8.259).
Light `view()` polls log `view.light.listChannels` and `view.light.listMembers` spans when the guild mesh is active (v0.8.258).
Light `view()` polls log `view.light.listChannels` and `view.light.listMembers` spans when the guild mesh is active (v0.8.258). Guild open also logs `guild.open.selectChannel` around the default channel pick (v0.8.259).
## Smoke tests
@@ -147,6 +147,8 @@ cd apps/pearcord && npm run test:leave-voice-noop
cd apps/pearcord && npm run test:session-boot-progress
cd apps/pearcord && npm run test:guild-loading-progress
cd apps/pearcord && npm run test:settings-prefs-nav-debounce
cd apps/pearcord && npm run test:diagnostics-jsonl-meta
cd apps/pearcord && npm run test:view-light-list-spans
```
`select-guild` IPC spans log **INFO** (not WARN) when the guild mesh flush was bounded (`PEARCORD_GUILD_SWARM_FLUSH_MS`). `session.startup` uses the same rule: slow startup after a bounded initial guild load stays **INFO**.
PEARCORD_PROTOCOL.md
+9 -1
View File
@@ -13,7 +13,15 @@ See [MESSAGE_DEEP_LINKS.md](./MESSAGE_DEEP_LINKS.md) and [INVITE_DEEP_LINKS.md](
| DM | `pearcord://dm/c/{channelId}/m/{messageId}` |
| Invite | `pearcord://invite/pcd_…` |
| Guild / channel | `pearcord://g/{guildId}` · `pearcord://g/{guildId}/c/{channelId}` |
| Settings (desktop) | `pearcord://settings` · `pearcord://settings?section=appearance&scope=user` (v0.8.255) |
| Settings (desktop) | `pearcord://settings` · `pearcord://settings?section=appearance&scope=user` · `pearcord://settings?section=channels&scope=guild&guildId={guildId}` (v0.8.259) |
### Settings query parameters
| Param | Values | Notes |
|-------|--------|-------|
| `scope` | `user` (default), `guild` | Guild scope requires an active or loadable server |
| `section` | User: `account`, `appearance`, `notifications`, … · Guild: panel id (`overview`, `channels`, …) | Invalid user sections fall back to `account`; guild sections validated when the modal opens |
| `guildId` | HyperDB guild id | When set with `scope=guild`, UI calls `select-guild` if needed then opens server settings |
## Runtime flow
PLATFORM_ROADMAP.md
+56 -26
View File
@@ -2628,7 +2628,7 @@ Fix guild switching, session boot gating, and theme/prefs application before mic
| P292-19 | Boot: chain Phase 292 smokes | [x] |
| P292-20 | Phase 293 production polish sprint (v0.8.255) | [x] |
**Next:** Phase 296 complete · Phase 297 active.
**Next:** Phase 297 complete · Phase 298 active.
---
@@ -2657,7 +2657,7 @@ Fix guild switching, session boot gating, and theme/prefs application before mic
| P293-19 | Settings modal: responsive narrow viewport stack (P292-16) | [x] |
| P293-20 | Phase 294 production polish sprint (v0.8.256) | [x] |
**Next:** Phase 296 complete · Phase 297 active.
**Next:** Phase 297 complete · Phase 298 active.
---
@@ -2686,7 +2686,7 @@ Fix guild switching, session boot gating, and theme/prefs application before mic
| P294-19 | Boot: chain Phase 294 smokes (+6) | [x] |
| P294-20 | Phase 295 production polish sprint (v0.8.257) | [x] |
**Next:** Phase 296 complete · Phase 297 active.
**Next:** Phase 297 complete · Phase 298 active.
---
@@ -2715,7 +2715,7 @@ Fix guild switching, session boot gating, and theme/prefs application before mic
| P295-19 | Boot: chain Phase 295 smokes (+6) | [x] |
| P295-20 | Phase 296 production polish sprint (v0.8.258) | [x] |
**Next:** Phase 296 complete · Phase 297 active.
**Next:** Phase 297 complete · Phase 298 active.
---
@@ -2742,9 +2742,9 @@ Fix guild switching, session boot gating, and theme/prefs application before mic
| P296-17 | Docs: `USER_SETTINGS.md` deep links + copy link | [x] |
| P296-18 | Docs: `pearcord-agentctl` README scenario table update | [x] |
| P296-19 | Boot: chain Phase 296 smokes (+8) | [x] |
| P296-20 | Phase 297 production polish sprint (v0.8.259) | [ ] |
| P296-20 | Phase 297 production polish sprint (v0.8.259) | [x] |
**Next:** Phase 297.
**Next:** Phase 297 complete · Phase 298 active.
---
@@ -2752,28 +2752,57 @@ Fix guild switching, session boot gating, and theme/prefs application before mic
| ID | Item | Status |
|----|------|--------|
| P297-1 | Guild settings deep link: validate `section` against known panel ids | [ ] |
| P297-2 | User settings: deep link opens notifications from bell prefs hint | [ ] |
| P297-3 | Diagnostics Save: include `devLogLineCount` + `logFile` path in meta line | [ ] |
| P297-4 | Platform: `guild.load` child span for `_selectGuildChannelWithUnread` | [ ] |
| P297-5 | Composer: Tab cycles mention picker without submitting form | [ ] |
| P297-6 | Message search: highlight query in guild search hits | [ ] |
| P297-7 | Thread panel: unread badge when archived threads have mentions | [ ] |
| P297-8 | Voice roster: filter self from sidebar when not in channel | [ ] |
| P297-9 | Agentctl: guild settings deep link with `guildId` headless roundtrip | [ ] |
| P297-10 | Agentctl: mesh two-peer `@channel` delivery | [ ] |
| P297-11 | Companion: session boot progress bar (mirror desktop) | [ ] |
| P297-12 | Smoke: `test:diagnostics-jsonl-meta` | [ ] |
| P297-13 | Smoke: `test:view-light-list-spans` | [ ] |
| P297-14 | Smoke: `test:companion-guild-loading-progress` | [ ] |
| P297-15 | Smoke: `test:settings-guild-deep-link-load` | [ ] |
| P297-16 | Docs: `LOGGING.md` view.light spans + diagnostics-meta | [ ] |
| P297-17 | Docs: `COMPANION.md` guild loading progress | [ ] |
| P297-18 | Docs: `PEARCORD_PROTOCOL.md` settings URL table | [ ] |
| P297-19 | Boot: chain Phase 297 smokes | [ ] |
| P297-1 | Guild settings deep link: validate `section` against known panel ids | [x] |
| P297-2 | User settings: deep link opens notifications from bell prefs hint | [x] |
| P297-3 | Diagnostics Save: include `devLogLineCount` + `logFile` path in meta line | [x] |
| P297-4 | Platform: `guild.open.selectChannel` span for `_selectGuildChannelWithUnread` | [x] |
| P297-5 | Composer: Tab cycles mention picker without submitting form | [x] |
| P297-6 | Message search: highlight query in guild search hits | [x] |
| P297-7 | Thread panel: unread badge when archived threads have mentions | [x] |
| P297-8 | Voice roster: filter self from sidebar when not in channel | [x] |
| P297-9 | Agentctl: guild settings deep link with `guildId` headless roundtrip | [x] |
| P297-10 | Agentctl: mesh two-peer `@channel` delivery | [x] |
| P297-11 | Companion: session boot progress bar (mirror desktop) | [x] |
| P297-12 | Smoke: `test:diagnostics-jsonl-meta` | [x] |
| P297-13 | Smoke: `test:view-light-list-spans` | [x] |
| P297-14 | Smoke: `test:companion-guild-loading-progress` | [x] |
| P297-15 | Smoke: `test:settings-guild-deep-link-load` | [x] |
| P297-16 | Docs: `LOGGING.md` view.light spans + diagnostics-meta | [x] |
| P297-17 | Docs: `COMPANION.md` guild loading progress | [x] |
| P297-18 | Docs: `PEARCORD_PROTOCOL.md` settings URL table | [x] |
| P297-19 | Boot: chain Phase 297 smokes (+6) | [x] |
| P297-20 | Phase 298 production polish sprint (v0.8.260) | [ ] |
**Next:** P297-1–P297-19.
**Next:** Phase 298.
---
### Phase 298 — Guild search depth & diagnostics XIX (v0.8.260)
| ID | Item | Status |
|----|------|--------|
| P298-1 | Guild message search: debounce query input (300ms) before platform fetch | [ ] |
| P298-2 | Search hits: preserve scroll position when toggling highlight-only filter | [ ] |
| P298-3 | Thread panel: sort archived rows with mentions above plain archived | [ ] |
| P298-4 | Open archived thread with mention: auto-scroll to first self-mention in thread | [ ] |
| P298-5 | Composer: `@everyone` / `@here` gated on `MENTION_EVERYONE` permission | [ ] |
| P298-6 | Voice roster: deafen icon on sidebar peers when `deaf` state set | [ ] |
| P298-7 | Notifications: mark channel read when jumping from thread mention alert | [ ] |
| P298-8 | Platform: `guild.search` span around message search IPC | [ ] |
| P298-9 | Diagnostics export: include `sessionError` + `guildLoading` snapshot in meta | [ ] |
| P298-10 | Guild load: abort stale `loadGuild` when rail switches server rapidly | [ ] |
| P298-11 | Agentctl: headless guild message search scenario | [ ] |
| P298-12 | Agentctl: create thread + reply mesh two-peer sync | [ ] |
| P298-13 | Companion: session error card with Open diagnostics deep link | [ ] |
| P298-14 | Smoke: `test:guild-search-debounce` | [ ] |
| P298-15 | Smoke: `test:thread-archived-mention-sort` | [ ] |
| P298-16 | Smoke: `test:voice-roster-deafen-icon` | [ ] |
| P298-17 | Docs: `SEARCH.md` highlight + debounce behavior | [ ] |
| P298-18 | Docs: `THREADS.md` archived mention badges | [ ] |
| P298-19 | Boot: chain Phase 298 smokes | [ ] |
| P298-20 | Phase 299 production polish sprint (v0.8.261) | [ ] |
**Next:** P298-1–P298-19.
---
@@ -4219,6 +4248,7 @@ Absorbed into Phase 273 (P273-5–P273-8, P273-11–P273-12). See Phase 274 for
### Changelog
- **2026-05-23** — v0.8.259: Phase 297 — settings section validation + bell→notifications deep link; diagnostics meta `devLogLineCount`/`logFile`; `guild.open.selectChannel` span; Tab mention cycle; search highlight marks; archived thread mention badges; voice roster self filter; companion session boot progress; agentctl guild settings + mesh `@channel`; +6 smokes. Phase 298 planned.
- **2026-05-23** — v0.8.258: Phase 296 — guild/server settings copy links + `guildId` deep links; diagnostics JSONL meta + auto-open on boot error; guild load elapsed label; view.light list spans; mention picker Escape + swatches; companion guild progress; agentctl settings navigate + @channel; +8 smokes. Phase 297 planned.
- **2026-05-23** — v0.8.257: Phase 295 — guild loading progress; settings section prefs debounce; Shift+@ channel mention; mention scroll + inbox highlight; clear composer diagnostics; session error diagnostics button; `guild.open.listChannels/Members` spans; agentctl leave-voice + settings deep link scenarios; +6 smokes. Phase 296 planned.
- **2026-05-23** — v0.8.256: Phase 294 — leave-voice noop log; session boot progress bar; composer `@` button; `.mention-self` highlight; settings copy link IPC; diagnostics composer badge; companion settings hint; +6 smokes. Phase 295 planned.