fn_registry/dev/flows/0010-matrix-client-pc.md

name, id, status, created, updated, priority, risk, related_issues, related_flows, apps, projects, vaults, capability_groups, trigger, schedule, expected_runtime_s, tags

name	id	status	created	updated	priority	risk	related_issues	related_flows	apps	projects	vaults	capability_groups	trigger	schedule	expected_runtime_s	tags
matrix-client-pc	0010	pending	2026-05-24	2026-05-24	high	medium	0147 0148 0149 0150 0151 0152 0153 0162 0163	0009 0011	matrix_client_pc	element_agents		matrix-client livekit-calls e2ee widgets	manual		0	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).