myxelium
e49b3ec112
- `LIVE_RELOAD=false npm run dev` keeps the renderer alive across a machine suspend; the reload client otherwise destroys the session under test. - `dev-peer.sh` plus a separate userdata dir runs a second local peer. - `tools/voice-probe.js` samples peer state and RTP counters from a live window, persisting to localStorage so a renderer reload cannot erase it. - e2e helpers for voice pairs, peer-role election, and a TURN relay. - Electron single-instance and dev-client-load decisions move into rules files with colocated specs.
75 lines
4.6 KiB
Markdown
75 lines
4.6 KiB
Markdown
# Emergency Fix Pack — MetoYou / Toju
|
||
|
||
> **Purpose:** Give other agents a single, user-first map of what this app is, how critical features are supposed to work, where the code lies, and the exact order to fix failures.
|
||
>
|
||
> **Constraint for this pack:** Analysis and planning only. Product code was not changed when this pack was authored (2026-08-12).
|
||
>
|
||
> **Primary surface:** `toju-app/` + targeted `electron/` (auth secret store / IPC). Expand to `server/` / `e2e/` only when a packet says so.
|
||
|
||
---
|
||
|
||
## How to use this pack
|
||
|
||
1. Read **this file** + `01-product-overview.md`.
|
||
2. Pick a work packet from `12-agent-work-packets.md` (do not invent parallel scope).
|
||
3. Open the matching issue file (`04`–`09`) for user story, intended behavior, failure modes, code paths, and proof.
|
||
4. Follow priority order in `11-fix-priority-plan.md` unless the user overrides.
|
||
5. Before coding: run the repo **interview-before-implement** ritual (choices A/B/C) unless the user says “just fix it” / “no interview” or an active handoff already records approved decisions.
|
||
6. When a packet finishes: update `11-fix-priority-plan.md` status checkboxes and clear or rewrite `agents-docs/HANDOFF.md` per `.cursor/rules/handoff.mdc`.
|
||
|
||
---
|
||
|
||
## File index
|
||
|
||
| File | Contents |
|
||
|------|----------|
|
||
| `00-README.md` | This index and rules of engagement |
|
||
| `01-product-overview.md` | What MetoYou/Toju is (user + architecture) |
|
||
| `02-user-journeys.md` | End-to-end journeys: login → rooms → chat → voice → multi-server |
|
||
| `03-architecture-map.md` | Domains, transports, identity model, key paths |
|
||
| `04-auth-login-bugs.md` | Login / authorize / silent provision failures |
|
||
| `05-signaling-multi-server.md` | Signal servers, WS drops, room affinity, presence |
|
||
| `06-voice-webrtc-bugs.md` | Voice, camera, screen-share, peer negotiation |
|
||
| `07-data-channel-drops.md` | Control-plane DC failures and recovery gaps |
|
||
| `08-messaging-visibility.md` | “Messages not seen” / sync / fallback |
|
||
| `09-identity-cross-signal.md` | Home vs foreign actor ids (calls, DMs, voice routing) |
|
||
| `10-code-lies-doc-debt.md` | Docs/lessons that disagree with the tree |
|
||
| `11-fix-priority-plan.md` | Ordered waves, acceptance, proof |
|
||
| `12-agent-work-packets.md` | Copy-paste packets for new chats |
|
||
| `13-validated-findings-fable-5-handoff.md` | Code-validated findings, corrected priorities, E2E limits, and implementation handoff |
|
||
| `e2e-failures/` | Latest full Playwright e2e run baseline (errors + slow tests) |
|
||
|
||
---
|
||
|
||
## Product in one paragraph (user view)
|
||
|
||
MetoYou (product client **Toju**) is a **desktop-first P2P chat app**: you log in once to a **signal server**, join **chat-servers** (communities with text + voice channels), talk in text, join voice, share screen/camera, and DM / call people. Media and most chat go **peer-to-peer over WebRTC**. The signal server only authenticates you, tracks who is in which room, and relays WebRTC offers / narrow chat & DM fallbacks. You may use **many signal servers**; the app is supposed to create a linked account on each new host **silently** after the first home login.
|
||
|
||
---
|
||
|
||
## Critical bug themes (user language)
|
||
|
||
1. **“It keeps asking me to log in”** even though I’m already signed in (especially when joining something on another signal server).
|
||
2. **“Voice doesn’t work / one-way / connecting forever”** — often after reconnect or when people registered on different signal servers.
|
||
3. **“Connection / data channel drops”** — chat, attachments, emoji, and sometimes voice die; recovery is silent or tears everything down.
|
||
4. **“I sent a message but they don’t see it”** (or only some devices see it) — presence missing, P2P sync dead, or wrong identity.
|
||
5. **“Call rings nobody / I’m In Voice alone”** — cross-signal identity mismatch on outbound or inbound paths.
|
||
6. **Different signal servers** make all of the above worse because **home user id ≠ foreign provisioned actor id**, and signaling is **not federated**.
|
||
|
||
---
|
||
|
||
## Related existing research (do not redo)
|
||
|
||
- Active research story: `agents-docs/user-stories/silent-cross-signal-server-auth.md`
|
||
- Feature contracts: `agents-docs/features/{authentication,signaling,voice-webrtc,messaging,server-directory}.md`
|
||
- Realtime deep dive: `toju-app/src/app/infrastructure/realtime/README.md`
|
||
- Lessons index: `agents-docs/LESSONS-INDEX.md` — tags `[auth] [realtime] [direct-call] [direct-message] [identity] [signaling]`
|
||
|
||
---
|
||
|
||
## Non-goals of this pack
|
||
|
||
- Implementing fixes (separate chats / packets).
|
||
- Rewriting the whole monorepo.
|
||
- Treating unit-green alone as “done” — each packet lists user-visible proof.
|