Files
Marcos Paulo 7920b7a5a0 feat(sync): presence for shared projects, and pause an external agent from the canvas
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
2026-11-07 10:36:37 -03:00

5.1 KiB
Raw Permalink Blame History

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)

  1. Server store. papercraft-relay --data <dir> keeps shared projects on disk. Without the flag the feature is off and every /p/ route answers 404.

  2. 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>.

  3. 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.

  4. 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, over crate::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.

  5. 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.

  6. Presence. Each device PUTs {id,label,page,cursor,sel,idle,leave} to /p/{token}/presence about 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 on leave. 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 --data is 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