The canvas and its trust boundary

A GitHub comment is useful for a quick orientation, but a complex graph may need more space, navigation, and time than a static comment can provide. PR Lens’s canvas is the surface for that case: this chapter traces how a graph document becomes an interactive, shareable object, and what new trust assumptions appear when a service stores it. The reader’s practical task is to distinguish a public view capability from an editing capability, handle revisions deliberately, and separate the documented protocol from claims about the hosted service behind it.

A canvas stores the graph, not a picture

The canvas command sends the graph document to a PR Lens-compatible server. It does not upload the SVGs that the local renderer already produced. That choice follows from what the canvas needs to do. The document contains all the views, flows, deltas, and walkthrough references; a server can draw the page from that source, expose several diagrams as tiles, and keep the interactive reading experience tied to one graph. Uploading only a finished image would preserve the pixels but lose the structure that lets the page navigate and play the walkthrough.

The lifecycle starts with an empty canvas. A mint request creates an id and a write token and returns a view link, an edit link, and an embed link. The initial revision is zero and there is no document to fetch until the first push. The id is a read capability: anyone who has it can request the canvas. The write token is a write capability: it authorizes pushing a new document, rotating the token, or deleting the canvas. These capabilities are intentionally different. Sharing the view link lets someone read the diagram; it does not have to give them the power to replace it.

The edit link carries the write token in the URL fragment rather than in the path or query. A browser does not send the fragment to the server or include it in an HTTP referrer, which limits accidental disclosure during ordinary navigation. The fragment is still a secret in practice. Anyone who receives the complete edit link can write over the canvas until the token is rotated. The CLI therefore tells users to share the view link and keep the edit link private.

A push carries the graph document and the revision the caller last saw in an If-Match header. On the first push, the expected revision is zero. If it matches, the server stores the document as the next revision and can draw its tiles. The response returns the new revision, view and embed links, and the images or handles for the diagrams the server drew. The client records the revision locally so the next push can state which version it is based on.

The server does not merge two graph documents. If two writers both read revision three, the first successful push creates revision four. The second still says If-Match: 3, so it receives a revision conflict and nothing changes.