--- path: /studio/real-time-collaboration-substrate surface: studio domain: collaboration auth: signed-in + studio entitlement source: apps/oshun/web/src/app/studio/real-time-collaboration-substrate/page.tsx status: walked last_walked: '2026-06-30 crdt-merge real-BFF addendum — Playwright now covers the admin-scoped route render, real CRDT catalog GET, default replica operation merge POST/result, LWW add-biased tie semantics, element table, quick-action targets, catalog loading/error state, malformed JSON client block, live BFF 400 detail, non-admin fail-closed, and anonymous redirect-before-render. Evidence: WALKTHROUGH/results/v1-real-infra-run-2026-06-22.md §246; spec: apps/oshun/web/e2e/studio-real-time-collaboration-substrate.spec.ts. 2026-05-29 automated runtime walk (Playwright headless) — render, /v1 data (2xx), console/page-errors, expected content, screenshot verified; live screen-reader, touch, offline, and telemetry-delivery checks pending a manual AT pass. Evidence: WALKTHROUGH/results/runtime-sweep-2026-05-29.md; content re-verified 2026-06-03 against current source' --- # Studio · Real-Time Collaboration Substrate ## Purpose Operate the real-time collaboration substrate as a live, admin-scoped BFF console. The workspace (`StudioRealTimeCollaborationSubstrateWorkspace`) wires a single **CRDT Merge Lane** to the real LWW-Element-Set (Last-Writer-Wins Element-Set) CRDT via `/v1/admin/studio/crdt-merge`: it folds replica operation logs into the convergent shared state. Each element is present when its latest `add` is not superseded by a later `remove`, and the converged state is the same regardless of operation order. This is a real domain computation, not a simulation. ## Entry points - **Studio root** (`/studio`) — discoverable as a collaboration workspace - **Quick-action links** from sibling collaboration workspaces (presence, commenting, review/approval, activity/change feeds, notification center, audit/compliance surfaces) - **Direct URL / bookmark** — yes ## Layout regions `page.tsx` mounts `ShellLayout active="studio"`, renders `StudioRealTimeCollaborationSubstrateWorkspace`, then a single `panel` containing 6 sibling `quickAction` links. There is no Route Map panel on this page. - **Shell header** — from `ShellLayout` - **Workspace `

`** — "Studio Real-Time Collaboration Substrate" (`WorkspaceHeading`), followed by a `data-realtime-collaboration-summary` paragraph describing the merge semantics - **CRDT Merge Lane** (`

` `data-cr-lane-heading` "CRDT Merge Lane") — the catalog/loading/unauthorized/error states, the merge form, and the result - **Quick-actions panel** — `panel` with 6 `quickAction` links to sibling workspaces (no self-link, no Route Map) ## States - [x] **Loading** — `data-cr-loading` "Loading CRDT merger…" while the GET catalog request is in flight (`outcome === null`) - [x] **Unauthorized** — `data-cr-unauthorized` "Access restricted." when the catalog GET returns 401/403 (admin scope required); shows the BFF message or "Studio admin scope required to merge CRDT state." - [x] **Error** — `data-cr-error` "Could not load the CRDT merger." on any non-OK catalog response or network failure - [x] **Ready (form)** — catalog loaded; `data-cr-enums` shows `{crdtType} · {opKinds.length} op kinds`, and the `data-cr-form` merge form renders - [x] **Result** — after a successful POST, `data-cr-result` renders the converged headline + per-element table - [x] **Merge validation error** — `data-cr-merge-error` for invalid JSON, network unavailable, or a non-200 POST (shows the POST `detail`) - [x] **Anonymous user** — redirected to `/welcome?redirect=%2Fstudio%2Freal-time-collaboration-substrate` before the workspace root renders ## Interactions ### CRDT Merge Lane form - [x] **Operations** (`textarea` `data-cr-payload`, aria-label `operations json`) — JSON `{ operations[{ replicaId, element, op, timestamp }] }`; seeded with a default payload - [x] **Merge replicas** (`button` `data-cr-submit`, `type="submit"`) — `submitMerge` parses the JSON (rejecting invalid JSON with `data-cr-merge-error`) and POSTs to `/v1/admin/studio/crdt-merge/merge` - [x] **Client-side malformed JSON block** — invalid JSON surfaces "Payload must be valid JSON." and does not send a POST - [x] **Live BFF invalid payload branch** — valid JSON with `operations: []` reaches the BFF and surfaces detail "operations must be a non-empty array" - [x] **LWW tie semantics** — a shuffled payload where `tie` has add/remove at timestamp `7` renders `data-present="true"`, proving the add-biased tie-breaker over the real BFF merge route ### Result - [x] **Headline** (`data-cr-headline`) — renders: `converged: ` plus `{presentCount} present` and `{removedCount} removed` - [x] **Elements table** (`data-cr-elements`) — one `data-cr-element-row` per element with `data-element`, `data-present`, plus `data-cr-add-ts` / `data-cr-remove-ts` cells ### Quick actions - [x] Open Presence and Cursor Systems workspace - [x] Open Commenting and Annotation System workspace - [x] Open Review and Approval Workflows workspace - [x] Back to Activity and Change Feeds workspace - [x] Back to Notification Center workspace - [x] Back to Audit and Compliance Surfaces workspace ## Data & contracts - **GET catalog**: `/v1/admin/studio/crdt-merge` — fetched on mount with `buildBffAuthHeaders()` and `cache: 'no-store'`; returns `{ opKinds[], crdtType }` - **POST verb**: `/v1/admin/studio/crdt-merge/merge` with body `{ operations[{ replicaId, element, op, timestamp }] }` → `{ result: { elements[], converged[], summary{ presentCount, removedCount } } }` (200) or a `detail` error - **Realtime**: none — request/response only - **Client fetch**: direct `fetch` with `cache: 'no-store'`; no client-side caching - **Auth/role check**: admin-scoped, fail-closed at the BFF (`admin:*` | `admin:studio`; 401 missing auth, 403 missing scope); reached through the signed-in + studio route gate ## Cross-references - Parent: [`../studio-overview.md`](../studio-overview.md) - Sibling: [`studio-presence-cursor-systems.md`](./studio-presence-cursor-systems.md), [`studio-commenting-annotation-system.md`](./studio-commenting-annotation-system.md), [`studio-review-approval-workflows.md`](./studio-review-approval-workflows.md) - Component: `apps/oshun/web/src/components/studio/StudioRealTimeCollaborationSubstrateWorkspace.tsx` - BFF route: `apps/oshun/bff/src/routes/admin-studio-crdt-merge.ts` - BFF store: `apps/oshun/bff/src/studio/crdt-lww-store.ts` ## E2E coverage - [`apps/oshun/web/e2e/studio-real-time-collaboration-substrate.spec.ts`](../../../apps/oshun/web/e2e/studio-real-time-collaboration-substrate.spec.ts) — signed-in admin `/studio/real-time-collaboration-substrate` render; real CRDT catalog GET with admin bearer; default operation-log merge POST through the live BFF; converged headline and `x`/`y`/`z` element timestamp/presence rows; shuffled-payload add-biased LWW tie proof; six sibling quick-action links; catalog loading/error; client-side malformed JSON zero-POST; live BFF 400 invalid-payload detail; non-admin 403 fail-closed; anonymous redirect-before-render. - [`apps/oshun/web/e2e/studio-route-render-smoke.spec.ts`](../../../apps/oshun/web/e2e/studio-route-render-smoke.spec.ts) — broad Studio route render and accessibility smoke coverage includes this route, but does not replace the focused real-BFF CRDT spec above. ## Open questions / known gaps - [ ] Confirm whether a future revision will persist merged CRDT state, or whether the lane stays a stateless merge console - [ ] Document op-kind extensibility (`OP_KINDS`) if kinds beyond add/remove are introduced - [ ] Live screen-reader and touch-device manual passes remain outside the automated route spec