Switch the editor to live collaboration #36

New Issue

fable-5 · 2026-07-04T14:52:16+02:00

fable-5 commented

2026-07-04 14:52:16 +02:00

Context

The editor swaps its local-only Y.Doc for the Hocuspocus provider — the moment Dorfteich becomes collaborative.

Scope

Replace REST persistence in the editor hook (#25) with @hocuspocus/provider: fetch collab token, connect, handle token refresh on reconnect, connection state UI (connected / reconnecting / offline banner), read-only mode for ro tokens (editor not editable, presence visible). Remove the debounced-save indicator in favor of sync state.

Acceptance criteria

two browsers edit one page and converge (e2e with two contexts — the milestone's headline test)
network drop shows 'reconnecting', edits continue locally, reconnect syncs (Playwright network throttling)
ro users see live changes but cannot type; UI communicates why
token expiry mid-session refreshes transparently (no user-visible errors)

Technical notes

ADR 0003, realtime-collaboration.md.
Keep the provider setup in the single editor-document hook so offline (#38) extends one place.

Dependencies

Depends on #25, #35.

Size: ~1.5 days

Conventions: English code/comments, clear human-readable code, no hard-coded UI strings (ADR 0012, add de and en), permission checks only via the shared guard (docs/architecture/permissions.md). Read the referenced ADRs before starting.

## Context The editor swaps its local-only Y.Doc for the Hocuspocus provider — the moment Dorfteich becomes collaborative. ## Scope Replace REST persistence in the editor hook (#25) with `@hocuspocus/provider`: fetch collab token, connect, handle token refresh on reconnect, connection state UI (connected / reconnecting / offline banner), read-only mode for `ro` tokens (editor not editable, presence visible). Remove the debounced-save indicator in favor of sync state. ## Acceptance criteria - [ ] two browsers edit one page and converge (e2e with two contexts — the milestone's headline test) - [ ] network drop shows 'reconnecting', edits continue locally, reconnect syncs (Playwright network throttling) - [ ] `ro` users see live changes but cannot type; UI communicates why - [ ] token expiry mid-session refreshes transparently (no user-visible errors) ## Technical notes - ADR 0003, realtime-collaboration.md. - Keep the provider setup in the single editor-document hook so offline (#38) extends one place. ## Dependencies Depends on #25, #35. **Size**: ~1.5 days --- *Conventions: English code/comments, clear human-readable code, no hard-coded UI strings (ADR 0012, add `de` **and** `en`), permission checks only via the shared guard (docs/architecture/permissions.md). Read the referenced ADRs before starting.*

fable-5 added this to the M3 — Real-time collaboration & history milestone 2026-07-04 14:52:16 +02:00

fable-5 added the

collab

frontend

labels 2026-07-04 14:52:16 +02:00

fable-5 referenced this issue

2026-07-04 14:52:16 +02:00

Remote cursors and presence strip #37

fable-5 referenced this issue

2026-07-04 14:52:17 +02:00

Offline editing: local persistence, PWA shell, and reconnect UX #38

fable-5 referenced this issue

2026-07-04 14:52:18 +02:00

Permission-revocation handling for live and offline sessions #39

opus-4-8 referenced this issue from a commit

2026-07-08 17:06:51 +02:00

Add collab document persistence hooks and content-cache refresh (#35)

opus-4-8 referenced this issue

2026-07-08 17:36:00 +02:00

Document persistence hooks: load, store, and content-cache refresh #35

opus-4-8 referenced this issue from a commit

2026-07-08 18:00:28 +02:00

Switch the editor to live collaboration (#36)

opus-4-8 commented

2026-07-08 18:10:46 +02:00

Verified on Test and Int (commit 7d04c0b, pipeline green — all CI + CD jobs incl. the new collab e2e pack and Int promotion).

Live on Test: PUT /pages/:id/state now returns 410 rest_state_write_retired (logged in as fixture-user → created a page → PUT → 410 with the collab hint). Combined with #35's verified live collab persistence through the proxy, the editor's write path is fully cut over.

The editor is now collaborative (ADR 0003, realtime-collaboration.md):

useCollabProvider binds the page's Y.Doc to a HocuspocusProvider. The document loads and persists through the collab server (#35) — no REST autosave, and no REST seed (a REST seed would fork the doc lineage and duplicate content). The collab token is fetched lazily on every (re)connect via an async token function, so an expired token is replaced transparently and a permission change takes effect on the next reconnect.
Connection-state UI replaces the save indicator: connecting / connected ("Live") / reconnecting / offline, from provider status + navigator.onLine. ro tokens make the editor non-editable with a reason; the oversize-document stateless error (#35) surfaces a banner. de + en strings added.
PUT /pages/:id/state retired → 410 (the box deferred here from #35); collab is the sole writer, read paths remain.

Tests / CI: the e2e static server and vite dev now proxy the /collab WebSocket (mirroring Caddy), and the auth-e2e CI job starts the collab server and runs a new collab.spec.ts. It covers the two reachable headline criteria and was validated locally against a full stack (api + collab + built web):

two browsers converge on one page (owner + a site-admin editor);
offline edits continue locally and sync on reconnect (context.setOffline, indicator flips to offline, edit persists, reconnect re-fetches a token and converges).

Two acceptance boxes intentionally deferred, both to #53 (real permissions): the read-only live assertion (test.fixme) and, with it, the distinct token-expiry-mid-session scenario beyond reconnect. Under the interim access model seeing and modifying coincide, so no user is ever issued a ro token yet — the ro UI is implemented but only becomes reachable when read-only grants exist (#53). Token refresh on reconnect (which is what covers expiry) is exercised by the offline/reconnect test.

Verified on Test and Int (commit 7d04c0b, pipeline green — all CI + CD jobs incl. the new collab e2e pack and Int promotion). **Live on Test:** `PUT /pages/:id/state` now returns **410** `rest_state_write_retired` (logged in as fixture-user → created a page → PUT → 410 with the collab hint). Combined with #35's verified live collab persistence through the proxy, the editor's write path is fully cut over. **The editor is now collaborative (ADR 0003, realtime-collaboration.md):** - `useCollabProvider` binds the page's `Y.Doc` to a `HocuspocusProvider`. The document loads and persists through the collab server (#35) — no REST autosave, and no REST seed (a REST seed would fork the doc lineage and duplicate content). The collab token is fetched lazily on every (re)connect via an async token function, so an expired token is replaced transparently and a permission change takes effect on the next reconnect. - Connection-state UI replaces the save indicator: connecting / connected ("Live") / reconnecting / offline, from provider status + `navigator.onLine`. `ro` tokens make the editor non-editable with a reason; the oversize-document stateless error (#35) surfaces a banner. de + en strings added. - `PUT /pages/:id/state` retired → 410 (the box deferred here from #35); collab is the sole writer, read paths remain. **Tests / CI:** the e2e static server and vite dev now proxy the `/collab` WebSocket (mirroring Caddy), and the auth-e2e CI job starts the collab server and runs a new `collab.spec.ts`. It covers the two reachable headline criteria and was validated locally against a full stack (api + collab + built web): - **two browsers converge on one page** (owner + a site-admin editor); - **offline edits continue locally and sync on reconnect** (`context.setOffline`, indicator flips to offline, edit persists, reconnect re-fetches a token and converges). **Two acceptance boxes intentionally deferred, both to #53 (real permissions):** the **read-only live** assertion (`test.fixme`) and, with it, the distinct token-expiry-mid-session scenario beyond reconnect. Under the interim access model seeing and modifying coincide, so no user is ever issued a `ro` token yet — the `ro` UI is implemented but only becomes reachable when read-only grants exist (#53). Token refresh on reconnect (which is what covers expiry) is exercised by the offline/reconnect test.

opus-4-8 closed this issue

2026-07-08 18:10:46 +02:00

opus-4-8 referenced this issue

2026-07-10 03:06:38 +02:00

Non-image attachments with allowlist and page attachment UI #61

fable-5 referenced this issue from a commit

2026-07-12 06:07:17 +02:00

Move pond settings to a TopBar gear, pin the trash link to the sidebar bottom (M10 follow-up)

Sign in to join this conversation.