---
name: matrix-client-pc
id: 0010
status: pending
created: 2026-05-24
updated: 2026-05-24
priority: high
risk: medium
related_issues: [0147, 0148, 0149, 0150, 0151, 0152, 0153, 0162, 0163]
related_flows: [0009, 0011]
apps: [matrix_client_pc]
projects: [element_agents]
vaults: []
capability_groups: [matrix-client, livekit-calls, e2ee, widgets]
trigger: manual
schedule: ""
expected_runtime_s: 0
tags: [matrix, element, wails, react, mantine, livekit, e2ee, widgets, agents]
---

## Goal

Cliente Matrix propio para PC (Win/Linux/macOS) construido con Wails (Go backend) + React+Mantine+`@fn_library` frontend. Replica capacidades actuales de Element Web (chat, E2EE, calls LiveKit) y se abre a mejoras propias: mini-webapps embebidas en conversaciones gestionadas por agentes del project `element_agents`, paneles especiales para llamadas, integracion directa con `agents_and_robots` + `agents_dashboard` + `device_agent` + futuro mesh WireGuard (flow 0009).

## Pre-requisitos

- Synapse + MAS + LiveKit funcionando en `organic-machine.com` (app `element_matrix_chat` ya desplegada, 5+ semanas uptime).
- `livekit-jwt` container vivo para generar tokens (ver `docker-compose.livekit.yml`).
- Sygnal push gateway (Synapse) — TBD si no existe, anadir container para push notifs PC + Android.
- Cuenta Matrix de test (`@dev-pc:matrix-af2f3d.organic-machine.com`) registrada via MAS.
- Go 1.22+ + Wails CLI v2 instalado (`go install github.com/wailsapp/wails/v2/cmd/wails@latest`).
- pnpm + Node 20+ (ya en el repo para `frontend/`).

## Funciones del registry recomendadas

| Rol | Funcion candidata | Estado |
|---|---|---|
| Matrix client init (Go) | `matrix_client_init_go_infra` | FALTA: wrapper sobre `mautrix-go` (login MAS OIDC, sync, store SQLite) |
| LiveKit token gen (Go) | `livekit_token_gen_go_infra` | FALTA: JWT con `livekit-server-sdk-go` |
| Matrix room subscribe SSE (Go) | `matrix_room_subscribe_go_infra` | FALTA: stream eventos Synapse -> frontend Wails via SSE/IPC |
| Matrix message send (Go) | `matrix_message_send_go_infra` | FALTA: text + markdown + reply + edit + reaction |
| Matrix E2EE bootstrap (Go) | `matrix_e2ee_bootstrap_go_infra` | FALTA: cross-signing keys, recovery passphrase |
| Matrix device verify (Go) | `matrix_device_verify_go_infra` | FALTA: SAS verification flow |
| LiveKit room hook (TS) | `livekit_room_ts_ui` | FALTA: hook React wrapper sobre `livekit-client` |
| Widget host iframe (TS) | `widget_host_ts_ui` | FALTA: iframe sandbox + postMessage Matrix Widget API v2 |
| Matrix timeline hook (TS) | `useMatrixTimeline_ts_ui` | FALTA: hook React con pagination, dedupe, optimistic UI |
| Markdown render (TS) | reuse existing `markdown_render_ts_ui` si existe, sino crear | check |
| HTTP client (Go) | `http_json_client_go_infra` | OK (reusar) |
| SQLite open (Go) | `sqlite_open_go_infra` | OK (reusar) |
| HTTP server SSE | `http_sse_server_go_infra` | OK (reusar) |
| Notify (impure) | `notify_desktop_go_infra` | FALTA: Win/Linux/mac notifications nativas |

## Apps tocadas

- `projects/element_agents/apps/matrix_client_pc` (nueva — Wails + React).
- `projects/element_agents/apps/element_matrix_chat` (backend ya activo; quiza anadir sygnal container).
- `projects/element_agents/apps/agents_and_robots` (consumidor — el cliente PC dialoga con agentes via rooms Matrix).
- `projects/element_agents/apps/agents_dashboard` (referencia UI — algunos paneles se reusan).

## Projects relacionados

- `element_agents` (root project — agrupa todo).

## Vaults / storage

- Local del PC: `~/.matrix_client_pc/store.db` (sync state + crypto store SQLite).
- Cache media: `~/.matrix_client_pc/media/`.

## Capability groups consultados

- `matrix-client` (a crear: documenta wrappers `mautrix-go`).
- `livekit-calls` (a crear: token gen + room join + UI calls).
- `e2ee` (a crear: bootstrap + verification + recovery).
- `widgets` (a crear: Matrix Widget API v2 host + sandbox + permisos).

## Flow

Pasos numerados. Cada paso = issue propio (ver `related_issues`).

1. **0147 — Scaffold Wails + login MAS.** Crear app `matrix_client_pc/` con Wails init, conectar a Synapse via MAS OIDC, mostrar perfil del usuario logueado. Persistencia tokens en `pass` o keychain del SO.
2. **0148 — Rooms list + timeline.** Sidebar con rooms (DMs + spaces + grupos), panel central timeline con pagination scroll-up, dedupe, optimistic UI. Reusar layout `AppShell` Mantine.
3. **0149 — Composer + interacciones.** Composer markdown, replies, edits, reactions, threads, upload media (imagenes, files, voice msg). Drag&drop. Slash commands placeholder.
4. **0150 — E2EE.** `mautrix-go` con crypto store SQLite. Cross-signing setup, recovery passphrase, SAS verification de devices, key backup. UI para verificar otros usuarios.
5. **0151 — Calls LiveKit.** Boton call en room -> token JWT desde Go backend -> join LiveKit room -> UI con tiles participantes, mute/cam/screen/hangup. 1:1 + grupales hasta 16 (limite actual del config).
6. **0152 — Mini-webapps embebidas.** Implementar Matrix Widget API v2: iframe sandbox + postMessage handshake + permisos (capabilities `m.always_on_screen`, `org.matrix.msc2762.send.event`, etc.). Lanzar webapps desde slash command `/widget <url>` o desde state event `m.widget`. Agentes pueden publicar widgets en su room (ej. dashboard de telemetria, formulario, kanban inline).
7. **0153 — Agent integration.** Paneles especiales para rooms operados por agentes de `agents_and_robots`: timeline + panel lateral con estado del agente (uptime, cola de tasks, last_error). Reusar SSE del `agents_dashboard`.

## Acceptance

- [ ] App Wails compila y arranca en Win+Linux con binario standalone.
- [ ] Login MAS OIDC completo, token persistido entre arranques.
- [ ] Sync incremental con Synapse funciona; reconexion automatica tras red caida.
- [ ] E2EE: enviar/recibir mensajes cifrados con otro cliente (Element Web o Android).
- [ ] Call 1:1 con video+audio funcional via LiveKit.
- [ ] Widget de prueba (HTML estatico servido por `agents_and_robots`) se carga en iframe sandbox y postMessage handshake completa.

## Definition of Done

### Mecanica (pre-requisito)

- `go build -tags wails` verde para Win + Linux.
- `pnpm build` frontend verde.
- `fn doctor cpp-apps` no aplica; `fn doctor services` confirma backend Matrix sano.
- `app.md` con `uses_functions` declarando todas las dependencias del registry.

### Cobertura de comportamiento

| Escenario | Tipo | Comando / evidencia | Resultado esperado |
|---|---|---|---|
| Golden: login + recibir mensaje E2EE | e2e | `e2e/test_login_and_receive.sh` | mensaje aparece en timeline en <2s, descifrado OK |
| Edge: red cae 30s, vuelve | e2e | `e2e/test_reconnect.sh` | sync se reanuda sin perder mensajes |
| Edge: 2000 mensajes en 1 room | e2e | `e2e/test_perf_timeline.sh` | scroll a 60fps, memoria <500MB |
| Edge: device nuevo no verificado envia msg | e2e | `e2e/test_unverified_device.sh` | warning visible en UI, msg cifra a este device solo si user confirma |
| Error: token MAS expira | e2e | `e2e/test_token_refresh.sh` | refresh automatico, sin logout visible |
| Error: LiveKit SFU caido | e2e | `e2e/test_livekit_down.sh` | error claro en UI, no crash de la app |

### Vida util validada (>=7 dias uso real)

| Metrica | Umbral | Donde se observa | Ventana |
|---|---|---|---|
| Crashes proceso PC | `0` | `journalctl --user -u matrix_client_pc` (Linux) / Event Viewer (Win) | 7 dias |
| Latencia send msg | `p95 < 500ms` | panel propio de la app + `call_monitor` | 7 dias |
| Calls fallidas | `< 5%` | counter en app + logs LiveKit | 7 dias |
| Uso real diario | `>= 4 dias/semana` | `last_active_at` en store local | 7 dias |
| Onboarding nuevo usuario | `< 5min hasta primer msg E2EE` | screencast operador | 1 sesion |

### Anti-criterios

- NO marcar done si E2EE se silent-falla (mensajes no se descifran y la UI no lo dice).
- NO marcar done si la app solo funciona en `home-wsl` y peta en `aurgi-pc`.
- NO marcar done si widget host carga `javascript:` URLs (XSS).
- NO marcar done si calls grupales >3 participantes lagean con audio cortado.

## Notas

**Onboarding rapido:**
1. `cd projects/element_agents/apps/matrix_client_pc`
2. `wails dev` para desarrollo con hot-reload.
3. `wails build -platform linux/amd64,windows/amd64` para release.
4. Tokens MAS guardados via `keyring` (Go bindings al keychain del SO).
5. Para probar E2EE: crear segundo usuario en Synapse Admin, abrir Element Web como segundo cliente, intercambiar verifications.

**Camino futuro (post-DoD):**
- Push notifs nativas via `sygnal` + APNs/FCM-equivalent desktop (Win Action Center, Linux notify-send).
- Mini-webapp catalog: registry de widgets internos (`projects/element_agents/widgets/`) publicables a rooms con un comando.
- Threads UI mejorado (vs Element que es plano).
- Integracion `agents_and_robots`: panel embebido que muestra logs del agente del room actual.
- Cuando flow 0009 (mesh wireguard) este vivo: este cliente PC habla con `device_agent` de cada PC del mesh via su room Matrix.

**Decisiones clave (justificacion en hilo Claude 2026-05-24):**
- Wails > Tauri: Go es stack principal del registry, reusa funciones existentes, `mautrix-go` es el SDK Matrix mas maduro en Go.
- React+Vite+Mantine+`@fn_library`: defaults del proyecto, ver `frontend_theming.md`.
- 2 codebases (PC Wails + Android Kotlin nativo): tradeoff aceptado por calidad nativa Android + reuso Go en PC. Contrato compartido en `docs/client_contract.md` (TBD).

## Capability growth log

- v0.1.0 (2026-05-24) — baseline (flow creado).