@coldtea/pr-lens-renderer 0.1.2 → 0.2.0

package/README.md

@@ -58,6 +58,24 @@ pnpm test                 # compares against the goldens
 UPDATE_GOLDENS=1 pnpm test  # records them, for a human to read the diff of
 ```
 
+## The atlas
+
+Every render comes back with an `atlas`: where each lane, node, edge and flow step of that picture landed, in the same viewBox units the file is written in.
+
+```ts
+const { svg, atlas } = render(doc, { lens: "architecture", theme: "dark" });
+atlas.nodes["send-broadcast-bulk"]; // { x, y, width, height }
+atlas.messages["send-pipeline"]?.["batch-post"];
+```
+
+A surface that plays a document's walkthrough has to put a rim around what a step points at, and a step names its elements by id and nothing else. Only the renderer knows where any of them ended up, so the geometry travels beside the picture rather than being measured back out of it by a reader that would have to guess.
+
+Flow steps are keyed by flow first, because a step's id is unique only inside its own flow: two flows may each carry one called `retry`, and neither document is wrong for it.
+
+The atlas is as deterministic as the SVG. Same document, same boxes, in the same key order, each coordinate rounded exactly as the one written into the file beside it, so a box and the rectangle it stands for cannot disagree in the last place. The theme never moves anything, so one atlas answers for both halves of a `<picture>` pair.
+
+Each lens fills in what it draws. The architecture lens places lanes, cards and edges and no flow step; the data-flow lens places the cards heading its columns and the steps of each flow, and no lane or edge. A node the same render draws twice, heading a column in two stacked flows, gets the box covering both of them: a reader sent to that node is being sent to all of it. A card's box is the card, not the badge strip above it, which is context a veil may dim.
+
 ## Corrections
 
 A repository's `.github/pr-lens.yml` is an overlay, applied here before layout and never written back into inference, so a correction keeps holding as the code moves:
@@ -68,7 +86,7 @@ render(doc, { lens: "architecture", theme: "dark", config });
 
 `rename`, `lane` and `group` address nodes by `id:<node-id>` or by a glob over the paths backing them. A `lane` correction may name a band the document never declared; it gets created, with the id for a label, so write `lane: infrastructure` rather than `lane: l3`.
 
-`exclude` takes with it every edge and flow step that touched what it removed, every view that pointed at nothing else, and every layout hint left naming something that is gone. Half an arrow is worse than none, and the corrected document is a document like any other, so it still parses.
+`exclude` takes with it every edge and flow step that touched what it removed, every view that pointed at nothing else, every layout hint left naming something that is gone, and every walkthrough step whose diagram or last focused element went with it. A walkthrough cut below two steps goes too, because one step is a caption. Half an arrow is worse than none, and the corrected document is a document like any other, so it still parses.
 
 ## Addresses
 

package/dist/version.d.ts

@@ -5,5 +5,5 @@
  * not otherwise need.
  */
 export declare const RENDERER_NAME = "@coldtea/pr-lens-renderer";
-export declare const RENDERER_VERSION = "0.1.2";
+export declare const RENDERER_VERSION = "0.1.3";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -5,5 +5,5 @@
  * not otherwise need.
  */
 export const RENDERER_NAME = "@coldtea/pr-lens-renderer";
-export const RENDERER_VERSION = "0.1.2";
+export const RENDERER_VERSION = "0.1.3";
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coldtea/pr-lens-renderer",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "The PR Lens renderer: a schema-valid graph document in, a self-contained animated SVG out.",
   "license": "MIT",
   "author": "Coldtea AI",
@@ -40,7 +40,7 @@
     "node": ">=20.11"
   },
   "dependencies": {
-    "@coldtea/pr-lens-schema": "0.1.2"
+    "@coldtea/pr-lens-schema": "0.2.0"
   },
   "devDependencies": {
     "@types/node": "^20.19.0",

package/src/atlas.ts

@@ -0,0 +1,56 @@
+import { covering, type Canvas } from "./bounds.js";
+import { roundCoord, type Box } from "./geometry.js";
+
+/**
+ * Where everything a render drew ended up, in the viewBox units of the file
+ * beside it.
+ *
+ * A surface that plays a walkthrough has to put a rim around what a step
+ * points at, and a step points at lanes, nodes, edges and flow steps by id
+ * alone. Only the renderer knows where any of them landed, and it knows it
+ * while it is drawing them, so the geometry travels with the picture rather
+ * than being measured back out of it by something that would have to guess.
+ */
+export type RenderAtlas = {
+  lanes: Record<string, Box>;
+  nodes: Record<string, Box>;
+  edges: Record<string, Box>;
+  /** Keyed by flow, then by step: a flow step's id is unique only inside its own flow. */
+  messages: Record<string, Record<string, Box>>;
+};
+
+/** An atlas for a drawing that has placed nothing. */
+export const emptyAtlas = (): RenderAtlas => ({ lanes: {}, nodes: {}, edges: {}, messages: {} });
+
+export type AtlasEntry = { id: string; box: Box };
+
+/**
+ * Boxes onto the canvas and into a record, in the order they were drawn.
+ *
+ * Each coordinate is rounded on its own, exactly as the one written into the
+ * file beside it is, so a box here and the rectangle it stands for cannot
+ * disagree in the last place. An id drawn more than once — a participant
+ * heading a column in two stacked flows — keeps the box covering every
+ * drawing of it, because a reader sent to that node is being sent to all of
+ * them.
+ */
+export const atlasBoxes = (
+  entries: readonly AtlasEntry[],
+  canvas: Canvas,
+): Record<string, Box> => {
+  const grown = new Map<string, Box>();
+  for (const { id, box } of entries) {
+    const current = grown.get(id);
+    grown.set(id, current === undefined ? box : covering(current, box));
+  }
+
+  const boxes: Record<string, Box> = {};
+  for (const [id, box] of grown)
+    boxes[id] = {
+      x: roundCoord(box.x + canvas.shiftX),
+      y: roundCoord(box.y + canvas.shiftY),
+      width: roundCoord(box.width),
+      height: roundCoord(box.height),
+    };
+  return boxes;
+};

package/src/bounds.ts

@@ -1,25 +1,22 @@
 import type { Box } from "./geometry.js";
 
-/** The smallest box containing all of them, or nothing when there are none. */
-export const union = (boxes: readonly Box[]): Box | undefined => {
-  const first = boxes[0];
-  if (first === undefined) return undefined;
-
-  let left = first.x;
-  let top = first.y;
-  let right = first.x + first.width;
-  let bottom = first.y + first.height;
-
-  for (const box of boxes) {
-    left = Math.min(left, box.x);
-    top = Math.min(top, box.y);
-    right = Math.max(right, box.x + box.width);
-    bottom = Math.max(bottom, box.y + box.height);
-  }
+/** The smallest box containing both of them. */
+export const covering = (a: Box, b: Box): Box => {
+  const left = Math.min(a.x, b.x);
+  const top = Math.min(a.y, b.y);
+  const right = Math.max(a.x + a.width, b.x + b.width);
+  const bottom = Math.max(a.y + a.height, b.y + b.height);
 
   return { x: left, y: top, width: right - left, height: bottom - top };
 };
 
+/** The smallest box containing all of them, or nothing when there are none. */
+export const union = (boxes: readonly Box[]): Box | undefined =>
+  boxes.reduce<Box | undefined>(
+    (grown, box) => (grown === undefined ? box : covering(grown, box)),
+    undefined,
+  );
+
 export type Canvas = { width: number; height: number; shiftX: number; shiftY: number };
 
 /**

package/src/corrections.ts

@@ -9,7 +9,7 @@ import type {
   View,
   ViewScope,
 } from "@coldtea/pr-lens-schema";
-import { assertNever } from "@coldtea/pr-lens-schema";
+import { assertNever, pruneWalkthrough } from "@coldtea/pr-lens-schema";
 import { PrLensRenderError } from "./errors.js";
 import { matchesGlob } from "./glob.js";
 
@@ -129,13 +129,20 @@ export const applyCorrections = (doc: GraphDoc, corrections: MapCorrections): Gr
     flow: (id: string) => flows.some((flow) => flow.id === id),
   };
 
+  const views = narrowViews(doc.views, survives);
+
   return {
     ...doc,
     lanes,
     nodes,
     edges,
     flows,
-    views: narrowViews(doc.views, survives),
+    views,
+    /**
+     * Narrowed against the document that came through, views included: a step
+     * can play over a view the overlay has just emptied out.
+     */
+    walkthrough: pruneWalkthrough(doc.walkthrough, { lanes, nodes, edges, flows, views }),
     layout: narrowLayout(doc.layout, survives),
   };
 };

package/src/geometry.ts

@@ -10,12 +10,13 @@ export type Side = "top" | "right" | "bottom" | "left";
  * arithmetic that differs in the last bit would otherwise change the bytes of
  * the document without changing the picture, and the render hash with it.
  */
-export const coord = (value: number): string => {
+export const roundCoord = (value: number): number => {
   const rounded = Math.round(value * 100) / 100;
-  const normalised = Object.is(rounded, -0) ? 0 : rounded;
-  return String(normalised);
+  return Object.is(rounded, -0) ? 0 : rounded;
 };
 
+export const coord = (value: number): string => String(roundCoord(value));
+
 export const boxCentre = (box: Box): Point => ({
   x: box.x + box.width / 2,
   y: box.y + box.height / 2,

package/src/index.ts

@@ -10,8 +10,12 @@ export {
   type RenderOptions,
 } from "./render.js";
 
+export { emptyAtlas, type RenderAtlas } from "./atlas.js";
+
 export { PrLensRenderError, type RenderErrorCode } from "./errors.js";
 
+export type { Box } from "./geometry.js";
+
 export { paletteFor, THEMES, type Palette, type Theme } from "./theme.js";
 
 export {

package/src/layout/dataflow.ts

@@ -85,7 +85,7 @@ export type DataFlowLayout = {
   slotCount: number;
 };
 
-const messagePitch = (message: FlowMessage): number =>
+export const messagePitch = (message: FlowMessage): number =>
   message.kind === "self" ? SELF_MESSAGE_PITCH : MESSAGE_PITCH;
 
 /**

package/src/render.ts

@@ -1,5 +1,6 @@
 import type { Config, GraphDoc, Lens, RenderAsset, RenderManifest, View, ViewScope } from "@coldtea/pr-lens-schema";
 import { assertNever, MAX_RENDER_ASSETS } from "@coldtea/pr-lens-schema";
+import type { RenderAtlas } from "./atlas.js";
 import { applyCorrections } from "./corrections.js";
 import { PrLensRenderError } from "./errors.js";
 import { buildManifest, contentHash, renderAssetFileName, renderAssetId } from "./manifest.js";
@@ -26,6 +27,8 @@ export type RenderedSvg = {
   theme: Theme;
   view: string | undefined;
   animated: boolean;
+  /** Where every lane, node, edge and flow step of this picture landed. */
+  atlas: RenderAtlas;
 };
 
 const WHOLE_DOCUMENT: ViewScope = { kind: "all" };
@@ -38,7 +41,7 @@ const paint = (
   graph: ScopedGraph,
   doc: GraphDoc,
   theme: Theme,
-): { width: number; height: number; body: string; animated: boolean } => {
+): { width: number; height: number; body: string; animated: boolean; atlas: RenderAtlas } => {
   const palette = paletteFor(theme);
 
   switch (lens) {
@@ -84,7 +87,12 @@ export const render = (doc: GraphDoc, options: RenderOptions): RenderedSvg => {
   const scope = view?.scope ?? WHOLE_DOCUMENT;
   const graph = resolveScope(prepared, scope);
 
-  const { width, height, body, animated } = paint(options.lens, graph, prepared, options.theme);
+  const { width, height, body, animated, atlas } = paint(
+    options.lens,
+    graph,
+    prepared,
+    options.theme,
+  );
 
   const svg = svgDocument({
     width,
@@ -95,7 +103,16 @@ export const render = (doc: GraphDoc, options: RenderOptions): RenderedSvg => {
     body,
   });
 
-  return { svg, width, height, lens: options.lens, theme: options.theme, view: view?.id, animated };
+  return {
+    svg,
+    width,
+    height,
+    lens: options.lens,
+    theme: options.theme,
+    view: view?.id,
+    animated,
+    atlas,
+  };
 };
 
 const requireView = (views: readonly View[], id: string): View => {

package/src/svg/architecture.ts

@@ -16,6 +16,7 @@ import {
   LANE_RADIUS,
   SUBTITLE_SIZE,
 } from "../design.js";
+import { atlasBoxes, emptyAtlas, type RenderAtlas } from "../atlas.js";
 import { canvasFor, union } from "../bounds.js";
 import { DIAGRAM_MARGIN } from "../design.js";
 import { coord, type Box } from "../geometry.js";
@@ -228,7 +229,12 @@ export const paintLabelPill = (text: string, box: Box, tone: Tone): string =>
       ),
   );
 
-export type ArchitecturePainting = { width: number; height: number; body: string };
+export type ArchitecturePainting = {
+  width: number;
+  height: number;
+  body: string;
+  atlas: RenderAtlas;
+};
 
 export const paintArchitecture = (
   graph: ScopedGraph,
@@ -290,5 +296,21 @@ export const paintArchitecture = (
     width: canvas.width,
     height: canvas.height,
     body: shifted(canvas, painted),
+    atlas: {
+      ...emptyAtlas(),
+      lanes: atlasBoxes(
+        layout.lanes.map(({ lane, box }) => ({ id: lane.id, box })),
+        canvas,
+      ),
+      /** The card, not the badge strip above it: a badge is context the veil may dim. */
+      nodes: atlasBoxes(
+        layout.nodes.map(({ node, box }) => ({ id: node.id, box })),
+        canvas,
+      ),
+      edges: atlasBoxes(
+        routed.map(({ edge, curve }) => ({ id: edge.id, box: curveBounds(curve) })),
+        canvas,
+      ),
+    },
   };
 };

package/src/svg/dataflow.ts

@@ -12,7 +12,8 @@ import {
   PILL_TEXT_SIZE,
   TITLE_SIZE,
 } from "../design.js";
-import { canvasFor, union } from "../bounds.js";
+import { atlasBoxes, emptyAtlas, type RenderAtlas } from "../atlas.js";
+import { canvasFor, covering, union, type Canvas } from "../bounds.js";
 import type { Box } from "../geometry.js";
 import { measure } from "../text.js";
 import { coord } from "../geometry.js";
@@ -22,6 +23,7 @@ import {
   FLOW_BAND_PAD_Y,
   layoutDataFlow,
   MARKER_INSET,
+  messagePitch,
   PARTICIPANT_TOP,
   SELF_LOOP_CORNER,
   SELF_LOOP_DROP,
@@ -378,7 +380,68 @@ const flowBounds = (layout: FlowLayout, columnWidth: number): Box[] => {
   return [...bands, ...pills, ...loops];
 };
 
-export type DataFlowPainting = { width: number; height: number; body: string };
+/**
+ * The row a step owns: what it draws, grown to the pitch the layout gave it.
+ *
+ * An arrow is a line and a loop is barely taller, so the tight bounds of
+ * either make a poor thing to put a rim around. The row is the honest unit —
+ * it is the space the layout set aside for this step and no other, so two
+ * neighbouring steps can never claim the same band. The label comes with it:
+ * a step lit without its own words is a step a reader cannot name.
+ */
+const messageBox = (placed: PlacedMessage, activeAt: ActiveAt): Box => {
+  const direction = travelDirection(placed.message.kind, placed.fromX, placed.toX);
+
+  const drawn =
+    direction === 0
+      ? selfDrawn(placed, activeAt(placed.message.from, placed.y))
+      : covering(straightDrawn(placed), pillBox(placed, endsFor(placed, activeAt, direction)));
+
+  const pitch = messagePitch(placed.message);
+  return {
+    x: drawn.x,
+    y: drawn.y + drawn.height / 2 - pitch / 2,
+    width: drawn.width,
+    height: pitch,
+  };
+};
+
+const straightDrawn = (placed: PlacedMessage): Box => ({
+  x: Math.min(placed.fromX, placed.toX),
+  y: placed.y,
+  width: Math.abs(placed.toX - placed.fromX),
+  height: 0,
+});
+
+const selfDrawn = (placed: PlacedMessage, activated: boolean): Box =>
+  covering(
+    {
+      x: placed.fromX,
+      y: placed.y,
+      width:
+        (activated ? ACTIVATION_HALF_WIDTH : 0) + SELF_LOOP_REACH + SELF_LOOP_CORNER,
+      height: SELF_LOOP_EXTENT,
+    },
+    selfPillBox(placed, activated),
+  );
+
+const flowAtlas = (layout: FlowLayout, canvas: Canvas): Record<string, Box> => {
+  const activeAt = activationLookup(layout);
+  return atlasBoxes(
+    layout.messages.map((placed) => ({
+      id: placed.message.id,
+      box: messageBox(placed, activeAt),
+    })),
+    canvas,
+  );
+};
+
+export type DataFlowPainting = {
+  width: number;
+  height: number;
+  body: string;
+  atlas: RenderAtlas;
+};
 
 export const paintDataFlow = (
   flows: readonly Flow[],
@@ -404,5 +467,21 @@ export const paintDataFlow = (
         ),
       ),
     ),
+    atlas: {
+      ...emptyAtlas(),
+      /** The card heading a column, which is where this lens draws a node. */
+      nodes: atlasBoxes(
+        layout.flows.flatMap((flow) =>
+          flow.participants.map((participant) => ({
+            id: participant.node.id,
+            box: participant.card,
+          })),
+        ),
+        canvas,
+      ),
+      messages: Object.fromEntries(
+        layout.flows.map((flow) => [flow.flow.id, flowAtlas(flow, canvas)]),
+      ),
+    },
   };
 };

package/src/version.ts

@@ -6,4 +6,4 @@
  */
 export const RENDERER_NAME = "@coldtea/pr-lens-renderer";
 
-export const RENDERER_VERSION = "0.1.2";
+export const RENDERER_VERSION = "0.2.0";