PR Lens glossary: lens, lane, delta, blast radius, walkthrough, canvas

Everything PR Lens draws comes out of one typed JSON document, so the vocabulary is small and each term means exactly one thing. This page defines all of it: the parts of a diagram, the two lenses, the words for what a change did to something, and the surfaces the diagrams end up on. Where a term is also a field in the document, I have said so, and the PR Lens graph document explained has the field limits. If you want the product before the vocabulary, start at what is PR Lens.

Lens: how a document gets drawn

A lens is one way of drawing a single document. PR Lens ships two, architecture and data-flow, and a document declares which of them it carries enough detail to render. A lens changes how a document is drawn, never what it says. The enum is deliberately additive, so a surface meeting a lens it does not recognise skips that view instead of failing.

Architecture lens: the blast radius

The architecture lens draws lanes of cards with the change written into them: a coloured outline and a badge per delta, removed elements ghosted and struck through, edges tinted by their own delta, and a travelling pulse on anything the document marked animated. It answers the question a reviewer asks first, which is what this touched and what sits next to it.

Data flow lens: the ordered sequence

The data flow lens draws a flow as a sequence: participant columns, lifelines, activation bars, return arrows and self-messages. The animated steps share one cycle and take it in turn, one dot crossing one arrow at a time, in the order the steps happen. A turn is spent entirely on its crossing, so the next arrow lights as the last dot lands.

Lane: a band of the diagram

A lane is a horizontal grouping band, and every node sits in exactly one. A document has between one and sixteen. Lanes are meant to be the reader's mental model of the system, a runtime, a tier or a boundary, rather than a mirror of the folder tree. A lane has an id, a label, and an optional subtitle for the platform it runs on.

Node: one card in the diagram

A node is a single card: a service, a route, a worker, a store, a package. It carries an id, a label, a kind, a delta, the lane it sits in, and usually the files backing it, which is what makes the card's diff permalink work. Between one and 256 of them make a document.

Node kind: what a card looks like

The kind picks the card's icon and shape and feeds nothing else. There are fifteen: service, app, module, function, route, job, queue, datastore, cache, external, ui, config, test, package, and other. The list is coarse on purpose, and anything that does not fit is other, which still renders.

Edge: a connection between two nodes

An edge is a directed connection with its own kind (call, http, rpc, event, queue, data, dependency, render, other) and its own delta, so a new arrow between two unchanged components is drawn as new. An edge may carry a label, such as a payload size or a protocol, and may be marked animated to give it a travelling pulse.

Hero edge: the connection the change is about

One edge per diagram can be marked hero, and the renderer gives it a glow. It is the connection the change is really about: the new call, the rerouted queue, the dependency that moved. Two at the outside. Past that the emphasis stops meaning anything, which is the same reason a document with everything bolded reads as a document with nothing bolded.

Delta: what the change did to an element

Every node, edge and flow step declares one of four values: added, modified, removed, unchanged. Green is new, amber is changed, red is gone. Removed elements stay in the picture, ghosted and struck through, because a reader needs to see what left as much as what arrived.

Unchanged: the context that stays on the page

unchanged is the delta most diagram formats have no word for, and the one that does the most work. A pull request touches one part and moves several; the parts it did not touch stay on the page so you build a model of the system rather than a model of a patch. Filtering them out would leave a picture that says nothing about consequences.

Blast radius: what a change reaches

The blast radius is what a change touches, drawn against the system around it, with the calls between the components. It is the architecture lens's whole job. A list of changed files is not a blast radius, because a file list cannot tell you that the one modified route is the only caller of a service three lanes away. There is a longer treatment in blast radius diagrams.

Flow: an ordered sequence

A flow is a named sequence with two to twelve participants, each of them a node already in the document, and one to 64 ordered messages between them. A document can carry up to sixteen. Flows are what the data flow lens draws, and a document carrying any must declare that lens.

Message: one step in a flow

A message is one step: a from, a to, a label, a delta, and a kind of sync, async, return or self. Order is the array position rather than a number on the step, so a document can never have an animation order that disagrees with its own message list. A step may declare a repeat count, which is how "four batched requests" is stated once instead of drawn four times.

View: one drill-down section

A view is one section of the nested disclosure tree in the pull request comment, with its own title, its own lens, and a scope that is either the whole document or a named selection of lanes, nodes, edges and flows. The comment opens with the whole blast radius and drills into the new path and what was retired. The whole tree ships pre-rendered, so opening a section costs no round trip.

Walkthrough: a guided tour of the diagrams

A walkthrough is an ordered tour of a document's own diagrams: two steps minimum, twelve maximum. It is optional, and it is authored alongside the diagrams rather than generated from them. A stored map never carries one, because a map describes a system and a walkthrough tells the story of one change.

Step: one stop on a walkthrough

A step is a heading of at most 48 characters, a required one-line body of at most 140, a stage naming which diagram to show, and a focus naming what stays lit while everything else dims. The caps are contract rather than advice: the rail shows one line per step, so no producer can pad its way past them. What a good one reads like is in what a good pull request walkthrough looks like.

Canvas: the diagrams full size

The canvas is the page where the diagrams are shown at full size, with pan, zoom, and a light or dark theme. GitHub cannot zoom an image inside a comment, so every comment links out to it. Press play, or the W key, and the canvas walks the change one step at a time. The CLI can push a document to a canvas of its own and print the link.

Graph document: the file everything speaks

The graph document is the typed JSON every part of PR Lens passes around: extraction writes it, the renderer consumes it, and the CLI, the Action, the agent skill and the hosted App all move it between them. It carries kind: "graph", a contract version, and the lanes, nodes, edges, flows, views and walkthrough above. If it parses, it renders.

Baseline: the stored map of the system

A baseline is a stored graph document describing the repository as it stands, rather than a change to it. The hosted App keeps one so that a pull request can be drawn against the system rather than against nothing, and tracks it across commits. Everything in a baseline is unchanged and its base commit equals its head, which the parser enforces.

Sticky comment: one comment per pull request

The sticky comment is the single PR Lens comment on a pull request, updated in place on every push rather than replaced by a new one. Its state travels in a hidden HTML marker in the body, which is how a checkbox toggle redraws the diagrams without re-running any analysis. The mechanism is written up in how PR Lens keeps exactly one comment per pull request.

Renderer: the pure function that draws

The renderer is @coldtea/pr-lens-renderer: a schema-valid document in, a self-contained animated SVG out. It has no dependency beyond the schema it validates against, no network, no filesystem and no clock, and it measures text from an embedded table rather than a font engine. The same document renders to the same bytes on any machine, which is what lets a diagram be addressed by the hash of itself.

Atlas: where everything landed

Every render also returns an atlas: the box each lane, node, edge and flow step occupies, in the same viewBox units as the file beside it. A surface playing a walkthrough has to put a rim around what a step points at, and a step names its elements by id and nothing else, so the geometry travels with the picture rather than being measured back out of it.

Correction: an overlay on the inferred map

A correction is a rule in .github/pr-lens.yml that renames, excludes, re-lanes or groups nodes. Corrections are an overlay applied over fresh inference on every run, and inference never writes back into the file, so a rule keyed to a path keeps holding after the model renames the node. The full list is in configuring PR Lens.

Content-hashed key: why a render URL is a hash

Rendered SVGs are stored and served at keys derived from a hash of the SVG itself. GitHub serves comment images through a proxy that caches a URL effectively forever, so a stable filename would pin the first version of a diagram in place for good. Hashing the bytes means a redraw is a new URL and a redraw that changed nothing is the old one.