mirror of
https://github.com/PerpetualSoftware/pad.git
synced 2026-09-23 19:06:33 +00:00
xarmian
54203087d0
* feat(web): leader-elected SSE + cross-tab BroadcastChannel (TASK-1359) Multiple tabs of the same workspace now share a single SSE connection via navigator.locks. Per DOC-1342 design decision #2: one leader holds the EventSource, peer tabs receive deltas via BroadcastChannel. - Each connecting tab opens a BroadcastChannel `pad-sync-{ws}` and races for an exclusive Web Lock on `pad-sse-leader-{ws}`. - The lock-holder opens the EventSource and forwards every event to local callbacks AND broadcasts to peer tabs. The browser's own-message filter keeps the leader from re-dispatching its own messages on the way back. - Peer tabs subscribe to the channel and dispatch leader-forwarded events to their local callbacks. They don't open EventSources while a leader exists, so the browser sees ONE /api/v1/events connection per workspace per browser regardless of tab count. - On leader-tab close, navigator.locks releases the lock automatically and a queued peer takes over (opens its own EventSource) without manual intervention. - Connection status is also broadcast so peer tabs surface the same connected / reconnecting / unauthorized indicator the leader sees. Fallback: browsers without navigator.locks (very old / non-browser environments) skip the election and every tab opens its own EventSource — N× traffic but correct. The public API (onItemEvent, onSyncRequired, status, etc.) is unchanged, so existing callers — sync.svelte, collection page — just work. Parent: PLAN-1343. See DOC-1342 design decision #2. * fix(web): gate BroadcastChannel on navigator.locks support (Codex round 1) [P1] When BroadcastChannel is available but navigator.locks is not, every tab falls back to per-tab EventSource AND opens the same shared channel. Each tab handles its local SSE event AND receives its peers' broadcasts — item callbacks fire N times across N tabs, producing duplicate toasts and refetches. Gate BC opening on `leaderElectionSupported()` (which checks for navigator.locks). Without leader election, the per-tab EventSource still delivers events locally; we just don't fan out — correct and avoids the N× duplication. Parent: PLAN-1343. * fix(web): leader promotion sync + BC close on fallback (Codex round 2) - [P1] When a peer tab is promoted to leader (the old leader's tab closed), the new EventSource opens with no Last-Event-ID so the server can't replay events from the gap. Query navigator.locks BEFORE requesting the lock; if the slot is already held, classify ourselves as a future "promotion" and fire sync_required on grant so consumers (syncService, the collection page) backfill via /items-changes. First leaders on fresh page loads don't fire — bootstrap already runs a sync — and any mis-classification is idempotent + cheap. - [P2] The lock-rejection fallback path now closes the BroadcastChannel before opening per-tab SSE. Without this, two tabs that both reject the lock would each open their own EventSource AND keep receiving each other's broadcasts, firing callbacks N times. Also triggers sync_required since we may have missed events while the rejection landed. Parent: PLAN-1343. * fix(web): grant-delay fallback for promoted-leader classification (round 3) [P1] Two tabs starting simultaneously can both query the lock state and see "no holder", so both set queryPromoted=false. One wins the request, the other queues. When the queued tab eventually gets promoted, queryPromoted=false would skip the sync_required, missing events from the gap between the old leader's close and the new EventSource. Add a grant-delay signal: record `performance.now()` before requesting, and treat any callback that fires more than 100ms later as a promotion. Uncontested lock grants are sub-millisecond; a queued tab takes at least the previous leader's full session. Final `promoted` is `queryPromoted || grantDelay > 100`, catching both the "slot-already-held-at-query-time" case AND the "simultaneous-startup-race" case. Parent: PLAN-1343. * fix(web): defer promoted-leader sync until EventSource connects (round 4) [P1] Promoted/fallback leaders called dispatchSyncRequired immediately after `new EventSource(...)`, before the replacement SSE stream was actually subscribed server-side. A mutation between the /items-changes snapshot (triggered by the sync) and the new stream's first received event could be missed by BOTH paths. Defer via a `pendingSyncOnConnect` flag set in the promotion / fallback paths; the EventSource's onopen and `connected` listeners fire the sync only after the stream is live. Whichever event arrives first claims the pending flag. Parent: PLAN-1343.
Pad Web UI
SvelteKit 2 + Svelte 5 frontend for Pad, compiled to static files and embedded into the Go binary.
Development
npm install
npm run dev # Dev server at localhost:5173 (proxies API to localhost:7777)
npm run build # Production build to build/
npm run check # Type checking with svelte-check
When developing, run the Go backend separately with make dev from the project root.
Building for Production
Do not build in isolation. Always use make build from the project root — this builds the web frontend, then compiles the Go binary with the build output embedded via //go:embed.
Stack
- Svelte 5 with runes (
$state,$derived,$effect) - SvelteKit 2 with
adapter-static(SPA mode) - Tiptap block editor with markdown round-trip
- svelte-dnd-action for drag-and-drop in board/list views
- SSE for real-time updates
- TypeScript throughout
Structure
src/
routes/ SvelteKit pages
+layout.svelte App shell (sidebar + main)
+page.svelte Landing/redirect
[workspace]/
+page.svelte Dashboard (collections, phases, activity)
+layout.svelte SSE connection per workspace
[collection]/
+page.svelte Collection view (board/list)
[collection]/[item]/
+page.svelte Item detail + editor
conventions/ Purpose-built conventions page
playbooks/ Purpose-built playbooks page
settings/ Workspace settings
lib/
api/client.ts HTTP API client
components/
layout/ Sidebar, navigation
editor/ Tiptap editor, raw markdown editor
fields/ FieldEditor, relation picker
items/ ItemCard, ItemDetail
collections/ BoardView, ListView
common/ StatusBadge, badges, modals
search/ CommandPalette
activity/ ActivityFeed
stores/ Svelte 5 reactive stores
workspace.svelte.ts Workspace state
collections.svelte.ts Collection + item state
ui.svelte.ts Sidebar, mobile state
types/index.ts TypeScript types and constants
app.css Global styles and design tokens