mirror of
https://github.com/PerpetualSoftware/pad.git
synced 2026-09-22 02:23:46 +00:00
xarmian
07e47eba57
* fix(web): subscribe item detail page to live SSE updates (TASK-1243)
The item detail page (+page.svelte under [collection]/[slug]) never
called sseService.onItemEvent, so live changes to the parent item's
title / fields / archive state didn't propagate from the server
until a manual refresh. Comments, reactions, timeline events, and
child-item updates all worked because their respective child
components (CommentThread, ItemTimeline, ChildItems) carry their
own SSE subscriptions — the gap was only on the parent item itself.
Discovered while manually verifying TASK-1242 (callback inversion):
two tabs on the same item showed divergent state until refresh.
Fix mirrors the existing onSync handler that lives a few lines below:
• Subscribe to sseService.onItemEvent in onMount, store the
unsubscriber alongside unsubscribeSync / unsubscribeBeforePrint
• Filter to event.item_id === item.id so cross-item navigation
inside the same component instance is handled cleanly (the
handler reads the *current* $state value of `item` on each fire,
no stale-closure bug)
• Same edit-conflict guards (saveStatus === 'saving' || editingTitle)
so SSE pushes don't clobber in-flight edits
• Same content-preservation pattern (`content: item.content`) — the
Tiptap editor owns the document state; replacing item.content
while it's mounted would clobber the user's local edits. Title,
fields, and metadata propagate; content stays put. This is a
deliberate conservative behavior identical to onSync's behavior
for the same reason.
• Handle item_archived (bounce back to collection list, matches
onSync's deletion path) and item_restored
• Tear down in onDestroy alongside the existing unsubscribers
Lifecycle: SvelteKit reuses the +page.svelte component instance when
navigating between items in the same collection, so onMount runs
once per route entry and onDestroy runs once per route exit. The
single subscription handles cross-item navigation correctly via the
`event.item_id !== item.id` filter; closure reads of $state /
$derived values pick up the new item on each event fire. No
re-subscription per navigation needed (collection page does that
because its closure captures wsSlug/collSlug as `const`s — different
pattern, same correctness).
KNOWN LIMITATION: live content sync is intentionally NOT handled.
For Pad's current "snapshot save on debounce" model, replacing the
editor's mounted document mid-edit would either drop user keystrokes
or fight the editor's internal state machine. A proper fix needs
either editor-dirty-state integration (acceptable for the "I'm
editing my own doc on two tabs" case) or a true CRDT-based collab-
edit refactor (Yjs + @tiptap/extension-collaboration) for the
"two users typing simultaneously" case. The CRDT direction is the
forward-looking plan; tracked separately.
* fix(web): guard SSE/sync handlers against stale-resolution race
Per Codex review on PR #446. The SSE handler I added in the previous
commit checks `event.item_id === item.id` *before* `await
api.items.get(...)`, but assigns to `item` *after* the resolution
without re-checking. If the user navigates to a different item while
the fetch is in flight, the resolved old-item data clobbers the
newly-loaded current item.
Same latent bug exists in the existing `onSync` handler's full-
refresh path, and Codex correctly flagged it as the same shape. The
loadData() function already guards against this same race in its
catch-block (TASK-754 round-2 race guard, see comment at line 224).
Fix mirrors that established pattern:
• Capture `item.id`, `wsSlug`, `itemSlug` into `reqItemId` /
`reqWsSlug` / `reqItemSlug` before the first await
• After every await (api.items.get, api.links.list), bail with
`if (!item || item.id !== reqItemId) return` before assigning
• Use the captured values for the requests themselves so cross-
navigation can't change which item we're fetching mid-flight
Applied to:
• SSE handler — item_updated and item_restored cases (item_archived
has no await, so it's already safe)
• onSync handler — incremental path (api.links.list was unguarded)
and full-refresh path (api.items.get was unguarded)
* fix(web): exempt destructive events from edit-conflict guard
Per Codex review round 2 on PR #446. The edit-conflict guard
(saveStatus === 'saving' || editingTitle) was placed BEFORE the
event-type switch, which meant `item_archived` (SSE) and the
`changes.deleted` branch (onSync) were also gated. Result: if
another client archived the item while the user was editing,
the destructive event was dropped and the user kept editing a
non-existent item until the next event or tab-resume sync.
Fix: hoist the destructive cases above the edit-conflict guard.
The user's in-flight save will fail against the archived row
anyway, so silently keeping them on a deleted item is strictly
worse than discarding the edit and bouncing them to the
collection list.
Applied to both handlers:
• SSE: `item_archived` runs before `saveStatus`/`editingTitle`
guard, exits early after `goto()`
• onSync: `result.changes.deleted.includes(item.id)` checked
before the guard for the same reason
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