Live Rooms V1 + Agent Direct-Client

.github/workflows/deploy.yml

@@ -8,6 +8,7 @@ on:
       - 'apps/marketing/**'
       - 'apps/portal/**'
       - 'apps/paste-service/**'
+      - 'apps/room-service/**'
       - 'apps/waitlist-service/**'
       - 'packages/**'
   workflow_dispatch:
@@ -22,6 +23,7 @@ on:
           - marketing
           - portal
           - paste
+          - room
           - waitlist
 
 permissions:
@@ -34,6 +36,7 @@ jobs:
       marketing: ${{ steps.changes.outputs.marketing }}
       portal: ${{ steps.changes.outputs.portal }}
       paste: ${{ steps.changes.outputs.paste }}
+      room: ${{ steps.changes.outputs.room }}
       waitlist: ${{ steps.changes.outputs.waitlist }}
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
@@ -57,6 +60,11 @@ jobs:
             else
               echo "paste=false" >> $GITHUB_OUTPUT
             fi
+            if [[ "${{ inputs.target }}" == "all" || "${{ inputs.target }}" == "room" ]]; then
+              echo "room=true" >> $GITHUB_OUTPUT
+            else
+              echo "room=false" >> $GITHUB_OUTPUT
+            fi
             if [[ "${{ inputs.target }}" == "all" || "${{ inputs.target }}" == "waitlist" ]]; then
               echo "waitlist=true" >> $GITHUB_OUTPUT
             else
@@ -69,6 +77,7 @@ jobs:
             MARKETING_CHANGED=$(git diff --name-only ${{ github.event.before }} ${{ github.sha }} 2>/dev/null | grep -E '^(apps/marketing/|packages/)' || true)
             PORTAL_CHANGED=$(git diff --name-only ${{ github.event.before }} ${{ github.sha }} 2>/dev/null | grep -E '^(apps/portal/|packages/)' || true)
             PASTE_CHANGED=$(git diff --name-only ${{ github.event.before }} ${{ github.sha }} 2>/dev/null | grep -E '^apps/paste-service/' || true)
+            ROOM_CHANGED=$(git diff --name-only ${{ github.event.before }} ${{ github.sha }} 2>/dev/null | grep -E '^(apps/room-service/|packages/shared/collab/|packages/editor/|packages/ui/)' || true)
             WAITLIST_CHANGED=$(git diff --name-only ${{ github.event.before }} ${{ github.sha }} 2>/dev/null | grep -E '^apps/waitlist-service/' || true)
 
             if [[ -n "$MARKETING_CHANGED" ]]; then
@@ -89,6 +98,12 @@ jobs:
               echo "paste=false" >> $GITHUB_OUTPUT
             fi
 
+            if [[ -n "$ROOM_CHANGED" ]]; then
+              echo "room=true" >> $GITHUB_OUTPUT
+            else
+              echo "room=false" >> $GITHUB_OUTPUT
+            fi
+
             if [[ -n "$WAITLIST_CHANGED" ]]; then
               echo "waitlist=true" >> $GITHUB_OUTPUT
             else
@@ -194,6 +209,31 @@ jobs:
           CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
           CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
 
+  deploy-room:
+    needs: detect-changes
+    if: needs.detect-changes.outputs.room == 'true'
+    runs-on: ubuntu-latest
+    environment: production
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Build browser shell
+        run: bun run --cwd apps/room-service build:shell
+
+      - name: Deploy to Cloudflare
+        working-directory: apps/room-service
+        run: npx wrangler deploy
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+
   deploy-waitlist:
     needs: detect-changes
     if: needs.detect-changes.outputs.waitlist == 'true'

.github/workflows/release.yml

@@ -41,7 +41,9 @@ jobs:
         run: bun run typecheck
 
       - name: Run tests
-        run: bun test
+        # See .github/workflows/test.yml for why this is `bun run test`
+        # and not raw `bun test`.
+        run: bun run test
 
   build:
     needs: test

.github/workflows/test.yml

@@ -29,7 +29,12 @@ jobs:
         run: bun run typecheck
 
       - name: Run tests
-        run: bun test
+        # Use the root `test` script (splits non-UI + UI-cwd) so the
+        # packages/ui/bunfig.toml happy-dom preload is loaded. Raw
+        # `bun test` from the repo root doesn't pick up that package-
+        # scoped preload, so UI hook tests would hit "document is not
+        # defined".
+        run: bun run test
 
   pi-extension-ai-runtime-windows:
     # Exercises the Pi extension's Node/jiti server mirror on Windows with an

.gitignore

@@ -57,6 +57,11 @@ plannotator-local
 /goals/
 *.bun-build
 
+.wrangler/
+apps/room-service/public/
+.claude/scheduled_tasks.lock
+specs/
+
 # Local meta notes (not upstream)
 /meta/
 

AGENTS.md

@@ -38,6 +38,16 @@ plannotator/
 │   │   ├── index.html
 │   │   ├── index.tsx
 │   │   └── vite.config.ts
+│   ├── room-service/             # Live collaboration rooms (Cloudflare Worker + Durable Object)
+│   │   ├── core/                 # Handler, DO class, validation, CORS, log, types, csp
+│   │   ├── targets/cloudflare.ts # Worker entry + DO re-export
+│   │   ├── entry.tsx             # Browser shell entry — path switch: / → LandingPage, /c/:roomId → AppRoot
+│   │   ├── index.html            # Vite template; produces hashed chunks under /assets/
+│   │   ├── vite.config.ts        # Browser shell build (bun run build:shell)
+│   │   ├── tsconfig.browser.json # DOM-lib tsconfig for the shell
+│   │   ├── static/               # Root-level static assets copied into public/ by build:shell (favicon.svg)
+│   │   ├── scripts/smoke.ts      # Integration test against wrangler dev
+│   │   └── wrangler.toml         # SQLite-backed DO binding + ASSETS binding (run_worker_first, html_handling=none)
 │   ├── vscode-extension/         # VS Code extension — opens plans in editor tabs
 │   │   ├── bin/                   # Router scripts (open-in-vscode, xdg-open)
 │   │   ├── src/                   # extension.ts, cookie-proxy.ts, ipc-server.ts, panel-manager.ts, editor-annotations.ts, vscode-theme.ts
@@ -68,24 +78,37 @@ plannotator/
 │   │   ├── components/           # Viewer, Toolbar, Settings, etc.
 │   │   │   ├── icons/            # Shared SVG icon components (themeIcons, etc.)
 │   │   │   ├── plan-diff/        # PlanDiffBadge, PlanDiffViewer, clean/raw diff views
-│   │   │   └── sidebar/          # SidebarContainer, SidebarTabs, VersionBrowser, ArchiveBrowser
+│   │   │   ├── sidebar/          # SidebarContainer, SidebarTabs, VersionBrowser, ArchiveBrowser
+│   │   │   └── collab/           # RoomStatusBadge, ParticipantAvatars, RoomHeaderControls, RoomMenu, RoomUnavailableScreen, JoinRoomGate, StartRoomModal, RemoteCursorLayer, ImageStripNotice, LandingPage, LandingPreview
 │   │   ├── shortcuts/            # Keyboard shortcut registry (see Keyboard Shortcuts section below)
 │   │   │   ├── core.ts           # Engine: parser, formatter, dispatcher, validator
 │   │   │   ├── runtime.ts        # Engine: useShortcutScope, useDoubleTapShortcuts hooks
 │   │   │   ├── index.ts          # Barrel — re-exports engine + scopes from both subfolders
 │   │   │   ├── plan-review/      # Scopes for plan-editor surfaces (annotationToolbar, annotationPanel, commentPopover, imageAnnotator, inputMethod, viewer)
 │   │   │   └── code-review/      # Scopes for review-editor surfaces (ai, allFilesDiff, annotationToolbar, fileTree, prComments, suggestionModal, tourDialog)
 │   │   ├── shortcuts.test.ts     # Registry unit tests (parser, dispatcher, validator)
-│   │   ├── utils/                # parser.ts, sharing.ts, storage.ts, planSave.ts, agentSwitch.ts, planDiffEngine.ts, planAgentInstructions.ts
+│   │   ├── utils/                # parser.ts, sharing.ts, storage.ts, planSave.ts, agentSwitch.ts, planDiffEngine.ts, planAgentInstructions.ts, adminSecretStorage.ts, blockTargeting.ts
 │   │   ├── hooks/                # useAnnotationHighlighter.ts, useSharing.ts, usePlanDiff.ts, useSidebar.ts, useLinkedDoc.ts, useAnnotationDraft.ts, useCodeAnnotationDraft.ts, useArchive.ts
+│   │   │   └── collab/           # useCollabRoom.ts, useCollabRoomSession.ts, useLandingCreateRoom.ts, usePresenceThrottle.ts, useRoomMode.ts, useRoomAdminActions.ts, useStartLiveRoom.ts
 │   │   └── types.ts
 │   ├── ai/                       # Provider-agnostic AI backbone (providers, sessions, endpoints)
 │   ├── shared/                   # Shared types, utilities, and cross-runtime logic
 │   │   ├── storage.ts            # Plan saving, version history, archive listing (node:fs only)
 │   │   ├── draft.ts              # Annotation draft persistence (node:fs only)
-│   │   └── project.ts            # Pure string helpers (sanitizeTag, extractRepoName, extractDirName)
-│   ├── editor/                   # Plan review app
-│   │   ├── App.tsx               # Main plan review app
+│   │   ├── project.ts            # Pure string helpers (sanitizeTag, extractRepoName, extractDirName)
+│   │   └── collab/               # Live Rooms protocol, crypto, validators, client runtime, React hook
+│   │       ├── types.ts          # Protocol types + runtime validators
+│   │       ├── crypto.ts         # HKDF key derivation, HMAC proofs, AES-GCM payload encrypt/decrypt
+│   │       ├── ids.ts            # roomId/secret/opId/clientId generators
+│   │       ├── url.ts            # parseRoomUrl / buildRoomJoinUrl / buildAdminRoomUrl (client-only)
+│   │       ├── constants.ts      # ROOM_SECRET_LENGTH_BYTES, ADMIN_SECRET_LENGTH_BYTES, WS_CLOSE_*
+│   │       ├── strip-images.ts   # toRoomAnnotation, stripRoomAnnotationImages
+│   │       ├── redact-url.ts     # redactRoomSecrets (scrub #key=/#admin= from telemetry/logs)
+│   │       └── client-runtime/   # CollabRoomClient class, createRoom, joinRoom, apply-event reducer
+│   ├── editor/                   # Plan review app (App.tsx) + room-mode shell
+│   │   ├── App.tsx               # Plan review editor (local + room-mode prop)
+│   │   ├── AppRoot.tsx           # Mode fork (local | room | invalid-room); package default export
+│   │   └── RoomApp.tsx           # Room-mode shell — identity gate, session, overlays, delete/expired fallbacks
 │   │   └── shortcuts.ts          # planReviewSurface + annotateSurface — composes plan-review scopes into per-surface registries
 │   └── review-editor/            # Code review UI
 │       ├── App.tsx               # Main review app
@@ -353,6 +376,39 @@ All servers use random ports locally or fixed port (`19432`) in remote mode.
 
 Runs as a separate service on port `19433` (self-hosted) or as a Cloudflare Worker (hosted).
 
+### Room Service (`apps/room-service/`)
+
+Live-collaboration rooms for encrypted multi-user annotation. Zero-knowledge: the Worker + Durable Object stores and relays ciphertext only. Clients hold the room secret in the URL fragment and derive `authKey`/`eventKey`/`presenceKey`/`adminKey` locally.
+
+| Endpoint              | Method | Purpose                                    |
+| --------------------- | ------ | ------------------------------------------ |
+| `/`                   | GET    | Landing page for room creation from uploaded document. Serves the same `index.html` shell; `entry.tsx` path switch renders `LandingPage` (lazy-loaded). |
+| `/health`             | GET    | Worker liveness probe                      |
+| `/c/:roomId`          | GET    | Room SPA shell — serves the built editor bundle. Response carries CSP, `Cache-Control: no-store`, `Referrer-Policy: no-referrer`. |
+| `/api/rooms`          | POST   | Create room. Body: `{ roomId, roomVerifier, adminVerifier, initialSnapshotCiphertext, expiresInDays? }`. Returns `201` on success; `409` on duplicate. |
+| `/api/fetch-markdown`  | POST   | URL-to-markdown proxy. Body: `{ url }`. Returns `{ markdown, source }`. |
+| `/ws/:roomId`         | GET    | WebSocket upgrade into the room Durable Object. |
+
+Protocol contract lives in `packages/shared/collab/`; the Worker/DO never imports client-only URL helpers.
+
+#### Multi-Document Rooms
+
+Rooms can carry multiple documents via `contentType: 'markdown-multi'`. The snapshot shape extends with:
+
+- `docs: Record<string, string>` — relative path → content (markdown or raw HTML).
+- `primaryDoc?: string` — path to auto-open on join (must be a key in `docs`).
+- `htmlDocPaths?: string[]` — paths in `docs` whose content is raw HTML (rendered via HtmlViewer). Absent paths are markdown.
+
+Each `RoomAnnotation` in a multi-doc room carries `docPath: string` matching a key in `docs`. The cross-field invariant is enforced in `isRoomSnapshot` (every annotation's `docPath` must resolve to a real doc) and at inbound-event time in `CollabRoomClient` (rejects `annotation.add` events with missing or unknown `docPath`). `docPath` is forbidden in annotation patches — annotations cannot be moved between documents.
+
+`PresenceState` carries `activeDoc?: string` so remote cursors are filtered per-document and the sidebar file list shows per-doc presence avatars.
+
+**Compression.** All room snapshots are deflate-compressed before encryption. The compressed plaintext is prefixed with `c1:` inside the encrypted envelope so `decryptSnapshot` knows to decompress. Legacy uncompressed rooms (no prefix) are supported permanently — never-expiring rooms created before compression can live indefinitely. Compression lives in `packages/shared/collab/crypto.ts` (`encryptSnapshot` / `decryptSnapshot`), reusing `compress` / `decompress` from `packages/shared/compress.ts`.
+
+**Size budget.** The picker enforces a 5 MB plaintext hard cap (submit disabled above it). The server's ciphertext hard cap is 1.5 MB (`MAX_SNAPSHOT_CIPHERTEXT_LENGTH` in `apps/room-service/core/validation.ts`), grounded in the Cloudflare SQLite-backed Durable Object 2 MB max row size. Compression bridges the gap — typical markdown compresses 3–5× and fits comfortably. Content that compresses poorly can still fail with a clean 413; the picker surfaces file-level guidance.
+
+**Server changes: none.** The Worker/DO only sees ciphertext. Multi-doc routing is entirely client-side.
+
 ## Plan Version History
 
 Every plan is automatically saved to `~/.plannotator/history/{project}/{slug}/` on arrival, before the user sees the UI. Versions are numbered sequentially (`001.md`, `002.md`, etc.). The slug is derived from the plan's first `# Heading` + today's date via `generateSlug()`, scoped by project name (git repo or cwd). Same heading on the same day = same slug = same plan being iterated on. Identical resubmissions are deduplicated (no new file if content matches the latest version).