Devices on a shared project see each other's cursor and selection through a new
PUT /p/{token}/presence on the relay (memory only, TTL, bounded, rate limited).
A client pauses an external MCP client's editing calls from a canvas chip; calls wait,
reads go on, a timeout answers 'paused by the user'.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01J9PiVCQxc2QYmArFq9VBUX
5.1 KiB
Shared projects on the relay
Why
On the web build a project lives in one browser's IndexedDB: it cannot be opened from another device, survives only while the browser keeps its storage, and cannot be edited by two people. The relay already hosts the app, so it can also host the project files.
Scope (v1)
-
Server store.
papercraft-relay --data <dir>keeps shared projects on disk. Without the flag the feature is off and every/p/route answers 404. -
Share a project. On the home screen a project card's menu has "Share…"; the app uploads the project's files and gets a share link
https://host/?share=<token>. -
Open a shared project. Opening a share link downloads the project into the tab's vfs and remembers the token, so the project appears on the home screen like any other.
-
Sync, file granularity. Each shared project polls the relay every 2 s, from the browser and from the native app alike (one engine,
src/sync.rs, overcrate::vfs). It compares the server's file list, the folder, and the last synced state (kept in the project's.share): folder changes go up, server changes come down and the open project reloads unless it has unsaved edits. Conflicts: whole file, the folder wins a simultaneous change (last write wins). An offline client catches up on its next poll. -
Native too. The desktop app shares a project to any relay (
Share…asks for the server) and joins by link, exactly like the browser; both can edit the same project. -
Presence. Each device
PUTs{id,label,page,cursor,sel,idle,leave}to/p/{token}/presenceabout every 0.7 s while active (4 s idle) and gets the other devices' reports back. The relay keeps them in memory for 20 s, bounds sizes and rate, and never writes them to disk; devices draw them as cursors and selection outlines in a colour derived from the device id, fading after 5 s idle and gone after 60 s or onleave. An older relay answers 404 and the device stops asking; an older device never reports and is just not shown; unknown JSON fields are ignored both ways.
Out of scope: per-object merging (CRDT), accounts, per-user permissions, history. The share token is the credential: anyone with the link can read and edit.
Protocol
Token: 32–64 lowercase hex characters, generated by the tab (same rules as the agent token). A different token from the agent link, so sharing a project never exposes the MCP endpoint.
| Route | Meaning |
|---|---|
GET /p/{token}/files |
JSON [{"path": "project.json", "size": 425, "mtime": <ns>}] (all files, relative paths) |
GET /p/{token}/f/{path} |
file bytes, 404 if absent |
PUT /p/{token}/f/{path} |
write bytes; creates the project on first write; answers the file's mtime; optional header x-client: <id> |
DELETE /p/{token}/f/{path} |
remove a file |
GET /p/{token}/ws |
WebSocket; server pushes {"op":"put"|"del","path":"…","rev":N,"client":"<id>"} |
The websocket is served but the clients poll /files (simpler, same code on both targets);
it is there for a later push-based client.
Rules: paths are relative, no .., no absolute, no empty segment; a bad path or token is a plain
404 (same text as unknown links). rev is a per-project counter the relay bumps on every
change. Body cap 64 MiB. Origin is not checked (the web app is served from the relay or another
origin). The writer's client id is echoed so a tab ignores its own events.
Storage layout: <data>/<token>/<path>; rev is kept in memory and restarts at the file count
after a relay restart (tabs resync from /files on reconnect, so a lower rev is harmless).
Acceptance
- Relay tests: put/get/list/delete round trip; path traversal refused; unknown token and bad
token are 404; a second websocket sees the first client's put and delete, the writer does not
see its own echo; routes 404 when
--datais absent. - Web: sharing uploads every file under the project dir; opening
?share=recreates the project locally; editing a page in tab A shows up in tab B without a manual reload. Wasm check builds clean and native tests stay green. - Local (non-shared) projects behave exactly as before.
Where it lives
| Concern | Code |
|---|---|
Server store, /p/ routes, path and token checks |
src/mcp/store.rs, merged into the relay router in src/mcp/relay.rs (spawn_with_data); --data flag in src/bin/papercraft-relay.rs |
Sync engine (both targets), .share file, link parsing, server-path sanitising |
src/sync.rs (HTTP: reqwest native, fetch wasm) |
| Reload of the open project, status, join/share entry points | src/session.rs (sync_poll, share_project, join_shared) |
| Home screen: Share…, Join shared…, status badge, copy link | src/ui/home.rs; actions handled in src/app.rs and src/web.rs; ?share= auto-join in src/web.rs |
| Presence (wire types, relay book, client loop) | src/presence.rs; route in src/mcp/store.rs; drawing in src/ui/peers.rs |
| Tests | tests/presence.rs (relay, old relay, bad input), tests/relay.rs (store routes), tests/sync.rs (two folders through a real relay), unit tests in src/sync.rs and src/mcp/store.rs |