capdag 1.426.27 → 1.457.27

package/cap-fab-renderer.js

@@ -28,7 +28,7 @@
 //   * cytoscape-elk extension (registers itself on `cytoscape`)
 //   * elkjs (via cytoscape-elk)
 //   * TaggedUrn (from tagged-urn browser build)
-//   * CapUrn, MediaUrn, Cap, createCap, CapFab (from capdag.js)
+//   * CapUrn, MediaUrn, Cap, CapFab (from capdag.js)
 //
 // The renderer owns its own theme observer (<html data-theme>) so hosts do
 // nothing to drive theme sync. It owns its own tooltip element and its own
@@ -41,7 +41,7 @@
 // uses a different name for the same concept, the fix is at the producer,
 // not here.
 
-import { CapUrn, CapFab, MediaUrn, createCap } from './capdag.js';
+import { Cap, CapUrn, CapFab, MediaUrn } from './capdag.js';
 
 // =============================================================================
 // Host dependencies — the page's: cytoscape and cytoscape-elk, loaded as
@@ -72,10 +72,27 @@ function cardinalityLabel(input_is_sequence, output_is_sequence) {
   return `${lhs}\u2192${rhs}`;
 }
 
+// The main output of a cap as it appears in the /api/capabilities JSON: the
+// one of its `outputs` whose media URN is the cap URN's `out=`, compared as
+// media URNs. Null for a cap that declares none (its `out=` is media:void).
+function mainOutputOf(cap) {
+  const outputs = cap.outputs || [];
+  if (!Array.isArray(outputs)) {
+    throw new Error('CapFabRenderer: a cap\'s outputs are a list');
+  }
+  if (outputs.length === 0) return null;
+  const outSpec = MediaUrn.fromString(CapUrn.fromString(cap.urn).getOutSpec());
+  const main = outputs.find(output =>
+    output && typeof output.media_urn === 'string' &&
+    MediaUrn.fromString(output.media_urn).isEquivalent(outSpec)
+  );
+  return main || null;
+}
+
 // Compute the cardinality marker for a cap as it appears in the
 // /api/capabilities JSON. The main input arg is the one whose sources
-// include a stdin source. Matches core Rust `CapArg.is_sequence` and
-// `CapOutput.is_sequence` names exactly.
+// include a stdin source; the output is the cap's MAIN output. Matches core
+// Rust `CapArg.is_sequence` and `CapOutput.is_sequence` names exactly.
 function cardinalityFromCap(cap) {
   if (!cap || typeof cap !== 'object') {
     throw new Error('CapFabRenderer: cardinalityFromCap requires a cap object');
@@ -85,7 +102,8 @@ function cardinalityFromCap(cap) {
     arg && arg.sources && arg.sources.some(src => src && src.stdin !== undefined)
   );
   const input_is_sequence = mainArg ? (mainArg.is_sequence === true) : false;
-  const output_is_sequence = (cap.output && cap.output.is_sequence === true) || false;
+  const mainOutput = mainOutputOf(cap);
+  const output_is_sequence = mainOutput !== null && mainOutput.is_sequence === true;
   return cardinalityLabel(input_is_sequence, output_is_sequence);
 }
 
@@ -126,6 +144,84 @@ function getCssVar(name) {
   return getComputedStyle(document.documentElement).getPropertyValue(name).trim();
 }
 
+// The graph's typeface: the host's (--graph-font-family) where it gives one. Labels are
+// measured in it as they are drawn in it.
+const DEFAULT_GRAPH_FONT = '"JetBrains Mono", ui-monospace, monospace';
+function graphFontFamily() {
+  if (typeof document === 'undefined') return DEFAULT_GRAPH_FONT;
+  return getCssVar('--graph-font-family') || DEFAULT_GRAPH_FONT;
+}
+
+// An ELK edge section as cytoscape draws a 'segments' edge: its points as weights along, and
+// distances across, the line between the two node centres, and its two ends as offsets from
+// those centres. A spline's control points (start, then three per cubic) are sampled into a
+// polyline fine enough to read as the curve.
+function routeFromSection(section, source, target) {
+  const control = [section.startPoint, ...(section.bendPoints || []), section.endPoint];
+  let points = control;
+  if (control.length >= 4 && (control.length - 1) % 3 === 0) {
+    points = [control[0]];
+    for (let i = 0; i + 3 < control.length; i += 3) {
+      const [p0, p1, p2, p3] = control.slice(i, i + 4);
+      // a straight run needs no points between its ends; a bend, one every 12 units of the
+      // control polygon (its length bounds the curve's), so a curve reads smooth at any zoom
+      const hull = Math.hypot(p1.x - p0.x, p1.y - p0.y) + Math.hypot(p2.x - p1.x, p2.y - p1.y) + Math.hypot(p3.x - p2.x, p3.y - p2.y);
+      const chord = Math.hypot(p3.x - p0.x, p3.y - p0.y);
+      const steps = hull - chord < 0.5 ? 1 : Math.min(16, Math.max(4, Math.ceil((hull - chord) / 2)));
+      for (let k = 1; k <= steps; k++) {
+        const t = k / steps, u = 1 - t;
+        points.push({
+          x: u * u * u * p0.x + 3 * u * u * t * p1.x + 3 * u * t * t * p2.x + t * t * t * p3.x,
+          y: u * u * u * p0.y + 3 * u * u * t * p1.y + 3 * u * t * t * p2.y + t * t * t * p3.y,
+        });
+      }
+    }
+  }
+  const dx = target.x - source.x, dy = target.y - source.y;
+  const lengthSquared = dx * dx + dy * dy || 1;
+  const length = Math.sqrt(lengthSquared);
+  const weightsOf = (pts) => pts.map((p) => ((p.x - source.x) * dx + (p.y - source.y) * dy) / lengthSquared);
+  const distancesOf = (pts) => pts.map((p) => ((p.y - source.y) * dx - (p.x - source.x) * dy) / length);
+  const inner = points.slice(1, -1);
+  const start = points[0], end = points[points.length - 1];
+
+  // In the overview a node is a dot at its box's centre: each end of the route is carried on
+  // from the box's side to the dot by a curve that leaves the route in its own direction and
+  // meets the dot level, rather than by a straight piece at another angle
+  const blend = (from, along, to, fromSide) => {
+    const reach = Math.hypot(to.x - from.x, to.y - from.y) / 3;
+    const norm = Math.hypot(along.x, along.y) || 1;
+    const c1 = { x: from.x + (along.x / norm) * reach, y: from.y + (along.y / norm) * reach };
+    const c2 = { x: to.x + (fromSide ? -reach : reach), y: to.y };
+    const out = [];
+    for (let k = 1; k < 8; k++) {
+      const t = k / 8, u = 1 - t;
+      out.push({
+        x: u * u * u * from.x + 3 * u * u * t * c1.x + 3 * u * t * t * c2.x + t * t * t * to.x,
+        y: u * u * u * from.y + 3 * u * u * t * c1.y + 3 * u * t * t * c2.y + t * t * t * to.y,
+      });
+    }
+    return out;
+  };
+  let overviewInner = inner;
+  if (points.length >= 2) {
+    const first = points[0], second = points[1];
+    const last = points[points.length - 1], before = points[points.length - 2];
+    // from the target's side back toward the target's centre, and from the source's centre out
+    const tail = blend(last, { x: last.x - before.x, y: last.y - before.y }, target, true);
+    const head = blend(first, { x: first.x - second.x, y: first.y - second.y }, source, false).reverse();
+    overviewInner = [...head, first, ...inner, last, ...tail];
+  }
+  return {
+    weights: weightsOf(inner),
+    distances: distancesOf(inner),
+    overviewWeights: weightsOf(overviewInner),
+    overviewDistances: distancesOf(overviewInner),
+    source: { dx: start.x - source.x, dy: start.y - source.y },
+    target: { dx: end.x - target.x, dy: end.y - target.y },
+  };
+}
+
 function cssVarNumber(name, fallback) {
   const raw = getCssVar(name);
   if (raw === '') return fallback;
@@ -301,8 +397,9 @@ function shapeLabelsInElements(elements) {
   // style at render time; we shape against the renderer's static node
   // font (defined in `buildStylesheet`). Kept in sync manually — bump
   // both together.
-  const nodeFont = '500 9px "JetBrains Mono", ui-monospace, monospace';
-  const edgeFont = '500 8px "JetBrains Mono", ui-monospace, monospace';
+  const family = graphFontFamily();
+  const nodeFont = `500 9px ${family}`;
+  const edgeFont = `500 8px ${family}`;
   let maxEdgeLabelPx = 0;
   let maxNodeLabelPx = 0;
   const reshaped = new Array(elements.length);
@@ -424,11 +521,17 @@ function layoutForMode(mode) {
 // =============================================================================
 
 function buildStylesheet() {
+  const fontFamily = graphFontFamily();
   const nodeText = getCssVar('--graph-node-text');
   const nodeBg = getCssVar('--graph-node-bg');
   const nodeBorder = getCssVar('--graph-node-border');
   const nodeBorderHighlighted = getCssVar('--graph-node-border-highlighted');
   const nodeBorderActive = getCssVar('--graph-node-border-active');
+  // The solid fill of a node in the browse overview (see `_applyLevelOfDetail`); a host
+  // that does not set it gets its highlighted border colour.
+  const nodeOverview = getCssVar('--graph-node-overview') || nodeBorderHighlighted;
+  // and of a chosen one there (a filled dot, where the labelled graph draws a border)
+  const nodeOverviewActive = getCssVar('--graph-node-overview-active') || nodeBorderActive;
   const edgeTextBg = getCssVar('--graph-edge-text-bg');
   const edgeTextBgOpacity = cssVarNumber('--graph-edge-text-bg-opacity', 0.9);
   const fadedOpacity = cssVarNumber('--graph-faded-opacity', 0.15);
@@ -440,8 +543,8 @@ function buildStylesheet() {
 
   // Machine mode uses a dedicated palette exposed by the notation
   // editor's CSS (`--graph-node-color`, `--graph-loop-color`,
-  // `--graph-edge-color`, `--graph-text`, `--graph-muted`). Caps
-  // are collapsed into edges so there's no cap-node color.
+  // `--graph-edge-color`, `--graph-text`, `--graph-muted`). A step
+  // node of the resolved machine is outlined in the edge color.
   const machineNodeColor = getCssVar('--graph-node-color');
   const machineLoopColor = getCssVar('--graph-loop-color');
   const machineEdgeColor = getCssVar('--graph-edge-color');
@@ -463,7 +566,7 @@ function buildStylesheet() {
         // node fit its actual shaped text.
         'text-wrap': 'wrap',
         'line-height': 1.3,
-        'font-family': '"JetBrains Mono", ui-monospace, monospace',
+        'font-family': fontFamily,
         'font-size': '9px',
         'font-weight': '500',
         'color': nodeText,
@@ -479,6 +582,22 @@ function buildStylesheet() {
         'transition-duration': '0.2s',
       },
     },
+    // Browse overview: below the zoom at which labels can be read, a node is a solid dot
+    // and an edge a plain line in its capability's colour, both of a constant size on
+    // screen (`lodSize`, `lodWidth`: screen pixels divided by the zoom, kept current by
+    // `_applyLevelOfDetail`). The graph reads as structure; labels return on zooming in.
+    {
+      selector: 'node.lod-overview',
+      style: {
+        'label': '',
+        'shape': 'ellipse',
+        'width': 'data(lodSize)',
+        'height': 'data(lodSize)',
+        'padding': 0,
+        'background-color': nodeOverview,
+        'border-width': 0,
+      },
+    },
     {
       selector: 'node.highlighted',
       style: { 'border-width': '3px', 'border-color': nodeBorderHighlighted },
@@ -487,9 +606,11 @@ function buildStylesheet() {
       selector: 'node.active',
       style: { 'border-width': '3px', 'border-color': nodeBorderActive, 'z-index': 999 },
     },
+    // A faded element says where the rest of the graph is; its words would only be noise
+    // behind the chosen one's
     {
       selector: 'node.faded',
-      style: { 'opacity': fadedOpacity },
+      style: { 'opacity': fadedOpacity, 'text-opacity': 0 },
     },
     {
       selector: 'node.body-success',
@@ -516,7 +637,7 @@ function buildStylesheet() {
       selector: 'edge',
       style: {
         'label': 'data(label)',
-        'font-family': '"JetBrains Mono", ui-monospace, monospace',
+        'font-family': fontFamily,
         // Slightly smaller than the node label font (9px) so edge
         // labels read as secondary metadata rather than primary
         // identity. Kept in sync with the `edgeFont` constant in
@@ -552,10 +673,143 @@ function buildStylesheet() {
         'control-point-weights': 'data(controlPointWeights)',
       },
     },
+    // A capability whose output is its input (a format conversion, a filter) is a loop. Its
+    // loops stand straight up from the node, nested, unnamed: a loop's name would lie across
+    // the loops around it. It is in the tooltip and the panel, and a chosen loop is named,
+    // level, on its background (browse mode; its routes do not draw loops)
+    {
+      selector: 'edge.browse-loop',
+      style: {
+        'curve-style': 'bezier',
+        'loop-direction': '0deg',
+        'loop-sweep': '-30deg',
+        // the first loop clears the node's box; each next one stands a little above it
+        'control-point-step-size': 26,
+        'text-opacity': 0,
+        'text-background-opacity': 0,
+      },
+    },
+    {
+      selector: 'edge.browse-loop.active',
+      style: {
+        'text-opacity': 1,
+        'text-background-opacity': 1,
+        'text-rotation': 'none',
+        'text-margin-y': -14,
+      },
+    },
+    {
+      selector: 'edge.browse-loop.lod-overview',
+      style: {
+        'control-point-step-size': 'data(lodLoopStep)',
+        'loop-sweep': '-30deg',
+      },
+    },
+    // A capability's name that would overlap another's or a media type's is not written
+    // (`_placeEdgeLabels`); it is in the tooltip, and the panel, and comes back when what
+    // covered it is faded or the view moves
+    {
+      selector: 'edge.label-crowded',
+      style: { 'text-opacity': 0, 'text-background-opacity': 0 },
+    },
+    {
+      selector: 'edge.lod-overview',
+      style: {
+        'label': '',
+        'width': 'data(lodWidth)',
+        'target-arrow-shape': 'none',
+        'curve-style': 'bezier',
+      },
+    },
+    // An edge laid along its ELK route (browse mode): a polyline through the route's points,
+    // from where it leaves its source's box to where it enters its target's; in the overview,
+    // where a node is a dot at the box's centre, carried on to the dot. The route is the edge's
+    // data (`_routeWithElk`), so a change of detail is a change of class, not of each edge's style.
+    {
+      selector: 'edge.routed',
+      style: {
+        'curve-style': 'segments',
+        'edge-distances': 'node-position',
+        'segment-weights': 'data(routeWeights)',
+        'segment-distances': 'data(routeDistances)',
+        'source-endpoint': 'data(routeSource)',
+        'target-endpoint': 'data(routeTarget)',
+      },
+    },
+    {
+      selector: 'edge.routed.lod-overview',
+      style: {
+        'segment-weights': 'data(routeWeightsOverview)',
+        'segment-distances': 'data(routeDistancesOverview)',
+        'source-endpoint': '0px 0px',
+        'target-endpoint': '0px 0px',
+      },
+    },
     {
       selector: 'edge.highlighted',
       style: { 'width': 2.5, 'z-index': 999 },
     },
+    // A chosen capability stands out in the overview too: its nodes in the active colour and
+    // named, at a constant size on screen, its edges twice as wide, so that where the view is
+    // too small for the labelled graph (a phone) the choice still reads. The capability
+    // itself is named by the host's panel, not along its edge, where a long name would not
+    // fit a small view.
+    {
+      selector: 'node.lod-overview.highlighted, node.lod-overview.active, node.lod-overview.path-highlighted',
+      style: {
+        'background-color': nodeOverviewActive,
+        'z-index': 999,
+      },
+    },
+    // ... and named where its name has room (`_placeOverviewNames`)
+    {
+      selector: 'node.lod-overview.lod-named',
+      style: {
+        'label': 'data(label)',
+        'font-size': 'data(lodFont)',
+        'text-valign': 'bottom',
+        'text-margin-y': 'data(lodGap)',
+        'color': nodeText,
+        'text-background-color': edgeTextBg,
+        'text-background-opacity': edgeTextBgOpacity,
+        'text-background-padding': 'data(lodGap)',
+        'text-background-shape': 'roundrectangle',
+        'z-index': 1000,
+      },
+    },
+    {
+      selector: 'edge.lod-overview.highlighted, edge.lod-overview.active, edge.lod-overview.path-highlighted',
+      style: {
+        'width': 'data(lodWidthStrong)',
+        'z-index': 998,
+      },
+    },
+    // ... and a chosen capability named along the middle of its route, level, where it has
+    // room (`_placeOverviewNames`)
+    // a name that would run past the view's edge is set to the side of its dot instead
+    {
+      selector: 'node.lod-overview.lod-named.lod-name-above',
+      style: { 'text-valign': 'top', 'text-margin-y': 'data(lodGapNeg)' },
+    },
+    {
+      selector: 'node.lod-overview.lod-named.lod-name-left',
+      style: { 'text-halign': 'left', 'text-margin-x': 'data(lodGap)' },
+    },
+    {
+      selector: 'node.lod-overview.lod-named.lod-name-right',
+      style: { 'text-halign': 'right', 'text-margin-x': 'data(lodGapNeg)' },
+    },
+    {
+      selector: 'edge.lod-overview.lod-named',
+      style: {
+        'label': 'data(label)',
+        'font-size': 'data(lodFontEdge)',
+        'text-rotation': 'none',
+        'text-margin-y': 'data(lodLift)',
+        'text-background-padding': 'data(lodGap)',
+        'z-index': 1000,
+      },
+    },
     {
       selector: 'edge.active',
       style: { 'width': 3, 'z-index': 1000 },
@@ -594,7 +848,7 @@ function buildStylesheet() {
     },
     {
       selector: 'edge.faded',
-      style: { 'opacity': fadedEdgeOpacity },
+      style: { 'opacity': fadedEdgeOpacity, 'text-opacity': 0, 'text-background-opacity': 0 },
     },
     {
       selector: 'edge.body-success',
@@ -622,15 +876,25 @@ function buildStylesheet() {
       selector: 'edge.path-highlighted',
       style: { 'width': 3, 'z-index': 999, 'line-style': 'solid' },
     },
+    // in the overview a path is drawn as a chosen capability is: strong lines, filled dots
+    {
+      selector: 'edge.lod-overview.path-highlighted',
+      style: { 'width': 'data(lodWidthStrong)' },
+    },
+    {
+      selector: 'node.lod-overview.path-highlighted',
+      style: { 'border-width': 0 },
+    },
 
     // -------- Machine / editor-graph mode ------------------------------
     // Shared between the resolved-machine view (`mode: 'machine'`,
     // canonical `Machine::to_render_payload_json`) and the notation
-    // editor's live graph (`mode: 'editor-graph'`, ast-driven). Both
-    // collapse each cap application into a single labeled edge
-    // between its input and output data slots — caps do NOT appear
-    // as separate nodes. Only data slots are nodes; cap semantics
-    // are carried on edges.
+    // editor's live graph (`mode: 'editor-graph'`, ast-driven). Data
+    // slots are `machine-node`s. The editor graph collapses each cap
+    // application into labeled edges between its data slots; the
+    // resolved machine draws each step as a `machine-step` node, and a
+    // constant it is given as a `machine-constant` node, with an edge
+    // per binding and per output taken.
     //
     // Reads the editor's dedicated palette so nodes, edges and
     // loop markers match the text theme.
@@ -660,6 +924,34 @@ function buildStylesheet() {
         'line-style': 'dashed',
       },
     },
+    {
+      selector: 'node.machine-step',
+      style: {
+        'shape': 'rectangle',
+        'background-color': nodeBg,
+        'border-color': machineEdgeColor || 'data(color)',
+        'color': machineText || nodeText,
+        'border-opacity': 1,
+      },
+    },
+    {
+      selector: 'node.machine-step-loop',
+      style: {
+        'border-color': machineLoopColor || nodeBorderActive,
+        'border-style': 'dashed',
+      },
+    },
+    {
+      selector: 'node.machine-constant',
+      style: {
+        'shape': 'tag',
+        'padding': '6px',
+        'border-width': '1px',
+        'background-color': nodeBg,
+        'border-color': machineMuted || nodeBorder,
+        'color': machineMuted || nodeText,
+      },
+    },
   ];
 }
 
@@ -670,21 +962,23 @@ function buildStylesheet() {
 function createTooltipElement() {
   const el = document.createElement('div');
   el.className = 'graph-tooltip';
+  // Its look is the host's where the host gives one (--graph-tooltip-*), these otherwise
   el.style.cssText = [
     'position: fixed',
     'display: none',
-    'background: var(--bg-elevated)',
-    'border: 1px solid var(--border-primary)',
-    'border-radius: 6px',
-    'padding: 6px 10px',
+    'background: var(--graph-tooltip-bg, var(--bg-elevated))',
+    'border: 1px solid var(--graph-tooltip-border, var(--border-primary))',
+    'border-radius: var(--graph-tooltip-radius, 6px)',
+    'padding: var(--graph-tooltip-padding, 6px 10px)',
     'font-family: var(--font-mono, ui-monospace, monospace)',
-    'font-size: 11px',
+    'font-size: var(--graph-tooltip-font-size, 11px)',
+    'line-height: var(--graph-tooltip-line-height, normal)',
     'color: var(--text-secondary)',
     'max-width: 400px',
     'word-break: break-all',
     'z-index: 10000',
     'pointer-events: none',
-    'box-shadow: 0 4px 12px rgba(0, 0, 0, 0.3)',
+    'box-shadow: var(--graph-tooltip-shadow, 0 4px 12px rgba(0, 0, 0, 0.3))',
   ].join('; ') + ';';
   document.body.appendChild(el);
   return el;
@@ -974,73 +1268,115 @@ function validateEditorGraphPayload(data) {
   });
 }
 
-// `validateResolvedMachinePayload` checks the canonical machine
-// render payload produced by Rust `Machine::to_render_payload_json`.
+// `validateResolvedMachinePayload` checks the canonical machine render
+// payload every capdag library writes (`Machine.to_render_payload_json`).
 // Shape:
 //   {
 //     "strands": [
 //       {
-//         "nodes": [{"id": "n0", "urn": "media:ext=pdf"}, ...],
+//         "nodes": [{"id": "n0", "urn": "media:document;ext=pdf", "title": "PDF"}, ...],
 //         "edges": [{
 //           "alias": "edge_0",
 //           "cap_urn": "...",
+//           "title": "Extract Text",
 //           "is_loop": false,
-//           "assignment": [{"cap_arg_media_urn": "media:ext=pdf", "source_node": "n0"}, ...],
-//           "target_node": "n1"
+//           "retry": 0,
+//           "on_error": "fail",
+//           "included_as": [],
+//           "assignment": [
+//             {"cap_arg_media_urn": "media:document;ext=pdf", "arg_name": "input", "source_node": "n0"},
+//             {"cap_arg_media_urn": "media:integer;window", "arg_name": "window", "constant": 20}
+//           ],
+//           "outputs": [{"output_media_urn": "media:...", "output_name": "output", "node": "n1"}]
 //         }, ...],
 //         "input_anchor_nodes": ["n0"],
-//         "output_anchor_nodes": ["n2"]
+//         "output_anchor_nodes": ["n1"]
 //       },
 //       ...
 //     ]
 //   }
+//
+// A binding is fed by a node of its strand or by a constant, never both and
+// never neither. A step with no binding is a source, one with no output a
+// sink. Every node a binding, an output or an anchor names is a node of the
+// strand.
 function validateResolvedMachinePayload(data) {
   if (!data || typeof data !== 'object') {
     throw new Error('CapFabRenderer machine mode: data must be an object');
   }
   assertArray(data.strands, 'machine mode data.strands');
   data.strands.forEach((strand, sIdx) => {
+    const at = `machine mode data.strands[${sIdx}]`;
     if (!strand || typeof strand !== 'object') {
-      throw new Error(`CapFabRenderer machine mode: data.strands[${sIdx}] is not an object`);
+      throw new Error(`CapFabRenderer ${at} is not an object`);
     }
-    assertArray(strand.nodes, `machine mode data.strands[${sIdx}].nodes`);
+    assertArray(strand.nodes, `${at}.nodes`);
+    const nodeIds = new Set();
     strand.nodes.forEach((n, nIdx) => {
       if (!n || typeof n !== 'object') {
-        throw new Error(`CapFabRenderer machine mode: data.strands[${sIdx}].nodes[${nIdx}] is not an object`);
+        throw new Error(`CapFabRenderer ${at}.nodes[${nIdx}] is not an object`);
       }
-      assertString(n.id, `machine mode data.strands[${sIdx}].nodes[${nIdx}].id`);
-      assertString(n.urn, `machine mode data.strands[${sIdx}].nodes[${nIdx}].urn`);
-      assertString(n.title, `machine mode data.strands[${sIdx}].nodes[${nIdx}].title`);
+      assertString(n.id, `${at}.nodes[${nIdx}].id`);
+      assertString(n.urn, `${at}.nodes[${nIdx}].urn`);
+      assertString(n.title, `${at}.nodes[${nIdx}].title`);
+      nodeIds.add(n.id);
     });
-    assertArray(strand.edges, `machine mode data.strands[${sIdx}].edges`);
+    const assertNode = (id, path) => {
+      assertString(id, path);
+      if (!nodeIds.has(id)) {
+        throw new Error(`CapFabRenderer ${path} names "${id}", which is no node of the strand`);
+      }
+    };
+    assertArray(strand.edges, `${at}.edges`);
     strand.edges.forEach((e, eIdx) => {
+      const edgeAt = `${at}.edges[${eIdx}]`;
       if (!e || typeof e !== 'object') {
-        throw new Error(`CapFabRenderer machine mode: data.strands[${sIdx}].edges[${eIdx}] is not an object`);
+        throw new Error(`CapFabRenderer ${edgeAt} is not an object`);
       }
-      assertString(e.alias, `machine mode data.strands[${sIdx}].edges[${eIdx}].alias`);
-      assertString(e.cap_urn, `machine mode data.strands[${sIdx}].edges[${eIdx}].cap_urn`);
-      assertString(e.title, `machine mode data.strands[${sIdx}].edges[${eIdx}].title`);
+      assertString(e.alias, `${edgeAt}.alias`);
+      assertString(e.cap_urn, `${edgeAt}.cap_urn`);
+      assertString(e.title, `${edgeAt}.title`);
       if (typeof e.is_loop !== 'boolean') {
-        throw new Error(`CapFabRenderer machine mode: data.strands[${sIdx}].edges[${eIdx}].is_loop must be boolean`);
+        throw new Error(`CapFabRenderer ${edgeAt}.is_loop must be boolean`);
+      }
+      if (!Number.isInteger(e.retry) || e.retry < 0) {
+        throw new Error(`CapFabRenderer ${edgeAt}.retry must be a whole number of further attempts`);
       }
-      assertArray(e.assignment, `machine mode data.strands[${sIdx}].edges[${eIdx}].assignment`);
+      if (e.on_error !== 'fail' && e.on_error !== 'absent') {
+        throw new Error(`CapFabRenderer ${edgeAt}.on_error must be "fail" or "absent"`);
+      }
+      assertArray(e.included_as, `${edgeAt}.included_as`);
+      e.included_as.forEach((step, iIdx) => assertString(step, `${edgeAt}.included_as[${iIdx}]`));
+      assertArray(e.assignment, `${edgeAt}.assignment`);
       e.assignment.forEach((b, bIdx) => {
+        const bindingAt = `${edgeAt}.assignment[${bIdx}]`;
         if (!b || typeof b !== 'object') {
-          throw new Error(`CapFabRenderer machine mode: data.strands[${sIdx}].edges[${eIdx}].assignment[${bIdx}] is not an object`);
+          throw new Error(`CapFabRenderer ${bindingAt} is not an object`);
+        }
+        assertString(b.cap_arg_media_urn, `${bindingAt}.cap_arg_media_urn`);
+        assertString(b.arg_name, `${bindingAt}.arg_name`);
+        const byNode = Object.prototype.hasOwnProperty.call(b, 'source_node');
+        const byConstant = Object.prototype.hasOwnProperty.call(b, 'constant');
+        if (byNode === byConstant) {
+          throw new Error(`CapFabRenderer ${bindingAt} must have exactly one of source_node and constant`);
         }
-        assertString(b.cap_arg_media_urn, `machine mode data.strands[${sIdx}].edges[${eIdx}].assignment[${bIdx}].cap_arg_media_urn`);
-        assertString(b.source_node, `machine mode data.strands[${sIdx}].edges[${eIdx}].assignment[${bIdx}].source_node`);
+        if (byNode) assertNode(b.source_node, `${bindingAt}.source_node`);
+      });
+      assertArray(e.outputs, `${edgeAt}.outputs`);
+      e.outputs.forEach((o, oIdx) => {
+        const outputAt = `${edgeAt}.outputs[${oIdx}]`;
+        if (!o || typeof o !== 'object') {
+          throw new Error(`CapFabRenderer ${outputAt} is not an object`);
+        }
+        assertString(o.output_media_urn, `${outputAt}.output_media_urn`);
+        assertString(o.output_name, `${outputAt}.output_name`);
+        assertNode(o.node, `${outputAt}.node`);
       });
-      assertString(e.target_node, `machine mode data.strands[${sIdx}].edges[${eIdx}].target_node`);
-    });
-    assertArray(strand.input_anchor_nodes, `machine mode data.strands[${sIdx}].input_anchor_nodes`);
-    strand.input_anchor_nodes.forEach((id, iIdx) => {
-      assertString(id, `machine mode data.strands[${sIdx}].input_anchor_nodes[${iIdx}]`);
-    });
-    assertArray(strand.output_anchor_nodes, `machine mode data.strands[${sIdx}].output_anchor_nodes`);
-    strand.output_anchor_nodes.forEach((id, oIdx) => {
-      assertString(id, `machine mode data.strands[${sIdx}].output_anchor_nodes[${oIdx}]`);
     });
+    assertArray(strand.input_anchor_nodes, `${at}.input_anchor_nodes`);
+    strand.input_anchor_nodes.forEach((id, iIdx) => assertNode(id, `${at}.input_anchor_nodes[${iIdx}]`));
+    assertArray(strand.output_anchor_nodes, `${at}.output_anchor_nodes`);
+    strand.output_anchor_nodes.forEach((id, oIdx) => assertNode(id, `${at}.output_anchor_nodes[${oIdx}]`));
   });
 }
 
@@ -1173,10 +1509,11 @@ function buildBrowseGraphData(capabilities) {
     const edgeId = `edge-${edges.length}`;
     const title = capData.title || '';
 
-    // Parsing the URN canonicalizes it and validates it — fail hard on
-    // malformed registry data.
-    const parsedUrn = CapUrn.fromString(capData.urn);
-    const cap = createCap(parsedUrn, title, capData.aliases || []);
+    // The cap as the fabric defines it — its args and outputs with their
+    // names — so a path through the graph is a machine its caps resolve.
+    // Reading it validates the URN and the record: malformed registry data
+    // fails hard.
+    const cap = Cap.fromJSON(capData);
     const capFabEdgeIndex = capFab.edges.length;
     capFab.addCap(cap, 'registry');
 
@@ -2239,7 +2576,7 @@ function buildRunGraphData(data) {
   // labels the anchor→entry edge on the first body.
   //
   // Without such a preceding sequence cap, the source itself is
-  // already a list (e.g. `media:ext=pdf;list` source_media_urn) and the
+  // already a list (e.g. `media:document;ext=pdf;list` source_media_urn) and the
   // ForEach iterates it directly.
   let seqProducerStepIdx = -1;
   let seqProducerStep = null;
@@ -2707,17 +3044,21 @@ function editorGraphSignature(data) {
 // so we can pass them straight through to cytoscape without name
 // collisions.
 //
-// Each cap edge is rendered as one cytoscape edge per
-// (assignment.source_node, target_node) pair. The common
-// single-input cap produces exactly one rendered edge; multi-input
-// (fan-in) caps produce one edge per source-arg slot, all sharing
-// the cap title and color so they read as a single fan-in.
+// Each step is a node of its own, between the data it is given and the
+// data it makes: an edge into it per binding, labelled with the arg's name,
+// and an edge out of it per output it is taken from, labelled with the
+// output's name. A step may be given nothing (a source) or have nothing taken
+// (a sink), and a binding may be a constant, which is drawn as a small node of
+// its own: none of these has a single input-to-output edge to be drawn on. A
+// step that runs once per item draws its node and its edges in the loop style.
 function buildResolvedMachineGraphData(data) {
   validateResolvedMachinePayload(data);
 
   const nodes = [];
   const edges = [];
   const seenNodeIds = new Set();
+  let stepCounter = 0;
+  let constantCounter = 0;
   let edgeCounter = 0;
 
   data.strands.forEach((strand, strandIdx) => {
@@ -2725,10 +3066,8 @@ function buildResolvedMachineGraphData(data) {
     const outputAnchorSet = new Set(strand.output_anchor_nodes);
 
     for (const node of strand.nodes) {
-      // Each node id is unique across the whole machine; the
-      // Rust side guarantees this via its global counter. If a
-      // duplicate appears it indicates a malformed payload, so
-      // fail hard rather than silently dropping.
+      // Node ids are unique across the whole machine: every library names
+      // them from one counter. A duplicate is a malformed payload.
       if (seenNodeIds.has(node.id)) {
         throw new Error(
           `CapFabRenderer machine mode: duplicate node id "${node.id}" in strand ${strandIdx}`
@@ -2753,36 +3092,86 @@ function buildResolvedMachineGraphData(data) {
     }
 
     for (const edge of strand.edges) {
-      const cardinality = edge.is_loop ? 'n\u21921' : '1\u21921';
-      const capUrn = edge.cap_urn;
-      const capTitle = edge.title;
-      const label = cardinality === '1\u21921'
-        ? edge.alias
-        : `${edge.alias} (${cardinality})`;
-
+      const stepId = `machine-step-${stepCounter}`;
+      stepCounter++;
+      const policy = [];
+      if (edge.retry > 0) policy.push(`retry=${edge.retry}`);
+      if (edge.on_error === 'absent') policy.push('on_error=absent');
       const color = edge.is_loop
         ? 'var(--graph-loop-color)'
-        : edgeHueColor(edgeCounter);
-      const baseClasses = edge.is_loop
-        ? 'machine-edge machine-loop'
-        : 'machine-edge';
+        : edgeHueColor(stepCounter - 1);
+      const edgeClasses = edge.is_loop ? 'machine-edge machine-loop' : 'machine-edge';
+
+      nodes.push({
+        group: 'nodes',
+        data: {
+          id: stepId,
+          label: policy.length > 0 ? `${edge.title}\n{${policy.join(', ')}}` : edge.title,
+          fullUrn: edge.cap_urn,
+          alias: edge.alias,
+          strandIndex: strandIdx,
+          isLoop: edge.is_loop,
+          retry: edge.retry,
+          onError: edge.on_error,
+          includedAs: edge.included_as.slice(),
+          color,
+        },
+        classes: edge.is_loop ? 'machine-step machine-step-loop' : 'machine-step',
+      });
 
       for (const binding of edge.assignment) {
+        let source = binding.source_node;
+        if (source === undefined) {
+          source = `machine-constant-${constantCounter}`;
+          constantCounter++;
+          nodes.push({
+            group: 'nodes',
+            data: {
+              id: source,
+              label: JSON.stringify(binding.constant),
+              fullUrn: binding.cap_arg_media_urn,
+              strandIndex: strandIdx,
+            },
+            classes: 'machine-constant',
+          });
+        }
         edges.push({
           group: 'edges',
           data: {
             id: `machine-edge-${edgeCounter}`,
-            source: binding.source_node,
-            target: edge.target_node,
-            label,
-            title: `${capTitle} (${binding.cap_arg_media_urn})`,
-            fullUrn: capUrn,
+            source,
+            target: stepId,
+            label: binding.arg_name,
+            title: `${edge.title}: ${binding.arg_name} (${binding.cap_arg_media_urn})`,
+            fullUrn: binding.cap_arg_media_urn,
             color,
             strandIndex: strandIdx,
+            argName: binding.arg_name,
             capArgMediaUrn: binding.cap_arg_media_urn,
             isLoop: edge.is_loop,
           },
-          classes: baseClasses,
+          classes: edgeClasses,
+        });
+        edgeCounter++;
+      }
+
+      for (const output of edge.outputs) {
+        edges.push({
+          group: 'edges',
+          data: {
+            id: `machine-edge-${edgeCounter}`,
+            source: stepId,
+            target: output.node,
+            label: output.output_name,
+            title: `${edge.title}: ${output.output_name} (${output.output_media_urn})`,
+            fullUrn: output.output_media_urn,
+            color,
+            strandIndex: strandIdx,
+            outputName: output.output_name,
+            outputMediaUrn: output.output_media_urn,
+            isLoop: edge.is_loop,
+          },
+          classes: edgeClasses,
         });
         edgeCounter++;
       }
@@ -2852,6 +3241,13 @@ class CapFabRenderer {
     this.bottomExcludedRegion = typeof options.bottomExcludedRegion === 'function'
       ? options.bottomExcludedRegion
       : () => 0;
+    // How a capability's name is written (browse mode): the host may set it in its own case
+    // (the website writes titles in sentence case); by default as the registry gives it
+    this.elkWorkerUrl = typeof options.elkWorkerUrl === 'string' ? options.elkWorkerUrl : null;
+    this.onReady = typeof options.onReady === 'function' ? options.onReady : null;
+    this.formatCapTitle = typeof options.formatCapTitle === 'function'
+      ? options.formatCapTitle
+      : (title) => title;
 
     // State — shared fields.
     this.cy = null;
@@ -2869,6 +3265,7 @@ class CapFabRenderer {
     this.capabilitiesByEdgeId = new Map();
     this._mediaTitles = new Map();
     this._pendingFocusCap = null;
+    this._pendingFocusCaps = null;
     this.pathMode = null;
 
     // Strand/run state.
@@ -2993,7 +3390,7 @@ class CapFabRenderer {
     // labels. Both the per-node label width and the per-graph edge
     // label width are recorded on the renderer so the zoom-backstop
     // logic can reason about them after layout-stop.
-    const labelMetrics = shapeLabelsInElements(rawElements);
+    const labelMetrics = shapeLabelsInElements(this.mode === 'browse' ? this._formatCapTitles(rawElements) : rawElements);
     const elements = labelMetrics.elements;
     this._labelMaxNodeWidthPx = labelMetrics.maxNodeLabelPx;
     this._labelMaxEdgeWidthPx = labelMetrics.maxEdgeLabelPx;
@@ -3011,62 +3408,19 @@ class CapFabRenderer {
       this.cy = null;
     }
 
+    // Browse mode lays the graph out itself when the host has loaded ELK (`_routeWithElk`):
+    // ELK places the nodes AND routes the edges, leaving room for their names, and the routes
+    // are drawn as ELK gives them. Otherwise, and in every other mode, cytoscape-elk places the
+    // nodes and cytoscape draws its own curves between them.
+    const routed = this.mode === 'browse' && typeof globalThis.ELK === 'function';
     this.cy = this._cytoscape({
       container: this.container,
       elements,
-      layout: Object.assign(
-        { name: 'elk', elk: layoutForMode(this.mode) },
+      layout: routed ? { name: 'null' } : Object.assign(
+        { name: 'elk', elk: this._layoutOptions() },
         {
           stop: function () {
-            self.cy.resize();
-            self._layoutReady = true;
-            // Per-edge stretch FIRST (mutates node x-coordinates so
-            // each edge has the horizontal room its own label needs),
-            // THEN lock the cytoscape wheel-zoom limits to the
-            // dynamic per-graph values, THEN fit the (possibly
-            // stretched) bounding box to the viewport so the user
-            // always opens at a fully-visible padded fit. Order
-            // matters: `_recomputeZoomLimits` needs the final
-            // post-stretch bounding box; `fitToVisibleViewport` needs
-            // the relaxed minZoom (it sits above the tight-fit zoom)
-            // so its padding actually shows.
-            self._stretchLayersForEdgeLabels();
-            self._recomputeZoomLimits();
-            const hadPendingFocus = !!self._pendingFocusCap;
-            if (hadPendingFocus) {
-              const pending = self._pendingFocusCap;
-              self._pendingFocusCap = null;
-              self.highlightCapability(pending);
-            }
-            // First paint with no preselected focus: snap (no
-            // animation) to a centered fit of the full, post-stretch
-            // graph. Going through `_centerOnGraphInitial` rather
-            // than `refitCurrentSelection` guarantees three things
-            // on the bootstrap pass that the selection-aware refit
-            // can't:
-            //   - never animate, so the user never sees a transient
-            //     un-centered state on the way to the final fit;
-            //   - always operate on the entire element set, so
-            //     per-edge stretching can't push the centered focus
-            //     off-viewport;
-            //   - reapply on every post-paint resize tick (see
-            //     `resizeAndRefit` below) until the user first
-            //     interacts, absorbing late WebKit container-size
-            //     settling without surprising a user who's already
-            //     scrolled or zoomed.
-            //
-            // If a focus cap WAS pending (browse-mode deep link from
-            // capdag-dot-com), defer to the selection-aware refit so
-            // the linked element lands centered instead.
-            if (hadPendingFocus) {
-              self.refitCurrentSelection();
-              // Treat the deep-link landing as the user's chosen
-              // viewport — late resize ticks shouldn't yank them
-              // back to a fit-of-all.
-              self._markInitialFitDone();
-            } else {
-              self._centerOnGraphInitial();
-            }
+            self._afterLayout({ stretch: true });
           },
         }
       ),
@@ -3085,6 +3439,9 @@ class CapFabRenderer {
     const resizeAndRefit = () => {
       if (!this.cy) return;
       this.cy.resize();
+      // The registry (browse) is laid out in a worker: until it is, there is no graph to measure
+      // or to centre, and _afterLayout does both when it lands
+      if (this.mode === 'browse' && !this._layoutReady) return;
       // Container size may have changed — recompute the zoom limits
       // so "fit the entire graph" still corresponds to actual pixel
       // capacity, not the size we had at first paint.
@@ -3107,16 +3464,210 @@ class CapFabRenderer {
       }
     };
     this.cy.on('ready', resizeAndRefit);
-    this.cy.on('resize', () => this._recomputeZoomLimits());
+    this.cy.on('resize', () => {
+      if (this.mode === 'browse' && !this._layoutReady) return;
+      this._recomputeZoomLimits();
+    });
     requestAnimationFrame(resizeAndRefit);
     setTimeout(resizeAndRefit, 100);
     setTimeout(resizeAndRefit, 300);
 
     this._setupEventHandlers();
     this._installZoomBackstop();
+    if (this.mode === 'browse') this.cy.edges().filter((edge) => edge.source().same(edge.target())).addClass('browse-loop');
+    // until ELK returns, every node of a routed graph stands at the origin: the canvas is
+    // hidden meanwhile (the host's loading state shows), and shown laid out
+    // Until ELK returns, every node of a routed graph stands at the origin: cytoscape's own
+    // drawing layer is hidden meanwhile (the container, and any loading state the host draws
+    // on it, stay), and shown laid out
+    if (routed) {
+      // (laid over the whole container meanwhile, so it neither takes a host's loading
+      // layout from it nor is measured at another size than the one it is shown at)
+      const layer = this.container.firstElementChild;
+      if (layer) Object.assign(layer.style, { visibility: 'hidden', position: 'absolute', inset: '0' });
+      this._routeWithElk().finally(() => {
+        if (layer) Object.assign(layer.style, { visibility: '', position: '', inset: '' });
+      });
+    }
     return this;
   }
 
+  // ELK's layered layout with spline routing for the registry: names are given to ELK as edge
+  // labels, so each layer gap is as wide as the names that cross it and every name has a
+  // straight stretch of its edge to itself.
+  _routedLayoutOptions() {
+    const options = {
+      'elk.algorithm': 'layered',
+      'elk.direction': 'RIGHT',
+      'elk.edgeRouting': 'SPLINES',
+      'elk.edgeLabels.placement': 'CENTER',
+      'elk.layered.spacing.nodeNodeBetweenLayers': '100',
+      'elk.layered.spacing.edgeNodeBetweenLayers': '20',
+      'elk.layered.spacing.edgeEdgeBetweenLayers': '12',
+      'elk.spacing.nodeNode': '60',
+      'elk.spacing.edgeNode': '20',
+      'elk.spacing.edgeEdge': '10',
+      'elk.spacing.edgeLabel': '4',
+      'elk.layered.crossingMinimization.strategy': 'LAYER_SWEEP',
+      'elk.layered.nodePlacement.strategy': 'NETWORK_SIMPLEX',
+      'elk.layered.considerModelOrder.strategy': 'NODES_AND_EDGES',
+    };
+    const aspect = this._layoutOptions()['elk.aspectRatio'];
+    if (aspect) options['elk.aspectRatio'] = String(aspect);
+    return options;
+  }
+
+  // ELK, in a worker where the host names ELK's worker script (`elkWorkerUrl`): laying out
+  // the registry takes a second or two, which on the page's own thread would freeze it. A
+  // cross-origin script cannot start a worker itself, so the worker is a small one of the
+  // page's origin that imports it. Without the option, or where a worker cannot start, ELK
+  // runs on the page's thread.
+  _createElk() {
+    const ELK = globalThis.ELK;
+    if (this.elkWorkerUrl && typeof Worker === 'function' && typeof Blob === 'function') {
+      try {
+        // the factory alone, not the URL too: given a URL, elkjs's bundle warns that a worker was
+        // asked for but cannot be made, although it then uses this factory
+        const script = this.elkWorkerUrl;
+        return new ELK({
+          workerFactory: () => new Worker(URL.createObjectURL(
+            new Blob([`importScripts(${JSON.stringify(script)});`], { type: 'application/javascript' })
+          )),
+        });
+      } catch (error) {
+        console.error('CapFabRenderer: ELK worker could not start; laying out on the page', error);
+      }
+    }
+    return new ELK();
+  }
+
+  async _routeWithElk() {
+    const cy = this.cy;
+    const graph = {
+      id: 'registry',
+      layoutOptions: this._routedLayoutOptions(),
+      children: cy.nodes().map((node) => ({ id: node.id(), width: node.outerWidth(), height: node.outerHeight() })),
+      edges: cy.edges().map((edge) => {
+        const label = edge.data('label');
+        return {
+          id: edge.id(),
+          sources: [edge.source().id()],
+          targets: [edge.target().id()],
+          // the name's box as cytoscape draws it: its text and background padding (4px)
+          labels: label ? [{ id: `${edge.id()}:label`, text: label, width: (edge.data('_labelPx') || 0) + 8, height: 8 * 1.3 + 8 }] : [],
+        };
+      }),
+    };
+    let laid;
+    try {
+      this._elk = this._elk || this._createElk();
+      laid = await this._elk.layout(graph);
+    } catch (error) {
+      console.error('CapFabRenderer: ELK routing failed; laying out without routes', error);
+      if (this.cy !== cy) return;
+      cy.layout({ name: 'elk', elk: this._layoutOptions(), stop: () => this._afterLayout({ stretch: true }) }).run();
+      return;
+    }
+    // a newer render replaced this graph while ELK was working
+    if (this.cy !== cy) return;
+
+    const centres = new Map(laid.children.map((c) => [c.id, { x: c.x + c.width / 2, y: c.y + c.height / 2 }]));
+    // marking the routed edges is not a change the names need placing again for
+    this._placingNames = true;
+    cy.batch(() => {
+      cy.nodes().forEach((node) => node.position(centres.get(node.id())));
+      (laid.edges || []).forEach((laidEdge) => {
+        const section = laidEdge.sections && laidEdge.sections[0];
+        if (!section) return;
+        const edge = cy.getElementById(laidEdge.id);
+        // a self-loop's route is cytoscape's own loop: its points would all lie on one node
+        if (edge.source().same(edge.target())) return;
+        const route = routeFromSection(section, centres.get(edge.source().id()), centres.get(edge.target().id()));
+        // a route with no bend is one point on the straight line between the ends
+        const weightsOf = (weights) => (weights.length ? weights.join(' ') : '0.5');
+        const distancesOf = (distances) => (distances.length ? distances.join(' ') : '0');
+        edge.data({
+          routeWeights: weightsOf(route.weights),
+          routeDistances: distancesOf(route.distances),
+          routeWeightsOverview: weightsOf(route.overviewWeights),
+          routeDistancesOverview: distancesOf(route.overviewDistances),
+          routeSource: `${route.source.dx}px ${route.source.dy}px`,
+          routeTarget: `${route.target.dx}px ${route.target.dy}px`,
+        });
+        edge.addClass('routed');
+      });
+    });
+    this._placingNames = false;
+    this._afterLayout({ stretch: false });
+  }
+
+  // What follows a layout, however it was made: the per-edge stretch (cytoscape-elk's
+  // layout only: a routed layout has left room for the names already), the zoom limits for
+  // the final box, a pending focus, the first fit, and the level of detail.
+  _afterLayout({ stretch }) {
+    if (!this.cy) return;
+    if (!this._readyReported) {
+      this._readyReported = true;
+      // the host learns the graph is laid out (`onReady`) before it is fitted: a loading
+      // state it ends there may change the container's size, which the fit then measures
+      if (typeof this.onReady === 'function') this.onReady();
+    }
+    this.cy.resize();
+    this._layoutReady = true;
+    // Per-edge stretch FIRST (mutates node x-coordinates so
+    // each edge has the horizontal room its own label needs),
+    // THEN lock the cytoscape wheel-zoom limits to the
+    // dynamic per-graph values, THEN fit the (possibly
+    // stretched) bounding box to the viewport so the user
+    // always opens at a fully-visible padded fit. Order
+    // matters: `_recomputeZoomLimits` needs the final
+    // post-stretch bounding box; `fitToVisibleViewport` needs
+    // the relaxed minZoom (it sits above the tight-fit zoom)
+    // so its padding actually shows.
+    if (stretch) this._stretchLayersForEdgeLabels();
+    this._recomputeZoomLimits();
+    const hadPendingFocus = !!this._pendingFocusCap;
+    if (hadPendingFocus) {
+      const pending = this._pendingFocusCap;
+      this._pendingFocusCap = null;
+      this.highlightCapability(pending);
+    } else if (this._pendingFocusCaps) {
+      const pending = this._pendingFocusCaps;
+      this._pendingFocusCaps = null;
+      this.highlightCapabilities(pending);
+    }
+    // First paint with no preselected focus: snap (no
+    // animation) to a centered fit of the full, post-stretch
+    // graph. Going through `_centerOnGraphInitial` rather
+    // than `refitCurrentSelection` guarantees three things
+    // on the bootstrap pass that the selection-aware refit
+    // can't:
+    //   - never animate, so the user never sees a transient
+    //     un-centered state on the way to the final fit;
+    //   - always operate on the entire element set, so
+    //     per-edge stretching can't push the centered focus
+    //     off-viewport;
+    //   - reapply on every post-paint resize tick (see
+    //     `resizeAndRefit` below) until the user first
+    //     interacts, absorbing late WebKit container-size
+    //     settling without surprising a user who's already
+    //     scrolled or zoomed.
+    //
+    // If a focus cap WAS pending (browse-mode deep link from
+    // capdag-dot-com), defer to the selection-aware refit so
+    // the linked element lands centered instead.
+    if (hadPendingFocus) {
+      this.refitCurrentSelection();
+      // Treat the deep-link landing as the user's chosen
+      // viewport — late resize ticks shouldn't yank them
+      // back to a fit-of-all.
+      this._markInitialFitDone();
+    } else {
+      this._centerOnGraphInitial();
+    }
+    this._applyLevelOfDetail();
+  }
+
   // ===========================================================================
   // Zoom backstop — dynamic per-graph minimum and maximum zoom levels.
   //
@@ -3145,6 +3696,264 @@ class CapFabRenderer {
   // viewport (≈15% slack at 800×600).
   static get ZOOM_OUT_FIT_SLACK() { return 0.15; }
 
+  // Browse mode draws the labelled graph only where its labels can be read: the 9px node
+  // labels at no less than 10px on screen. Below that zoom it draws the overview (see the
+  // `lod-overview` styles): a dot per media type, sized by its connections, and a line per
+  // capability, at constant on-screen sizes.
+  static get LOD_LABEL_ZOOM() { return 10 / 9; }
+
+  // The mode's layout, and in browse mode the shape of the part of the canvas that can be
+  // seen: ELK packs the registry's separate pieces side by side to that aspect ratio, so a
+  // wide, short view is filled across rather than with a tall column in its middle.
+  _layoutOptions() {
+    const options = layoutForMode(this.mode);
+    if (this.mode !== 'browse') return options;
+    const w = this.container.clientWidth;
+    const h = this.container.clientHeight - Math.max(0, this.bottomExcludedRegion() | 0);
+    if (w > 0 && h > 0) options['elk.aspectRatio'] = w / h;
+    return options;
+  }
+
+  // In the overview, the chosen elements' names are written where they have room: in order
+  // of importance (the chosen node, then the most connected), a name is placed under its dot
+  // unless it would overlap one already placed or another chosen dot. A name left out is one
+  // hover or a closer zoom away.
+  _placeOverviewNames() {
+    if (this.mode !== 'browse' || !this.cy) return;
+    const cy = this.cy;
+    const named = cy.elements('.lod-named');
+    if (!this._lodOverview) {
+      this._placingNames = true;
+      named.removeClass('lod-named');
+      this._placingNames = false;
+      return;
+    }
+    const chosen = cy.nodes('.highlighted, .active, .path-highlighted');
+    const font = `500 11px ${graphFontFamily()}`;
+    const lineHeight = 11 * 1.3;
+    const gap = 3;
+    const placed = [];
+    const overlaps = (a, b) => a.x1 < b.x2 && b.x1 < a.x2 && a.y1 < b.y2 && b.y1 < a.y2;
+    // every chosen dot is an obstacle a name must not cover
+    chosen.forEach((node) => {
+      const p = node.renderedPosition();
+      const r = node.renderedWidth() / 2 + 1;
+      placed.push({ x1: p.x - r, x2: p.x + r, y1: p.y - r, y2: p.y + r });
+    });
+    const order = chosen.sort((a, b) => {
+      const rank = (n) => (n.hasClass('active') ? 2 : 0) + (this.selectedElement && this.selectedElement.element && this.selectedElement.element.id && this.selectedElement.element.id() === n.id() ? 2 : 0);
+      return (rank(b) - rank(a)) || (b.degree() - a.degree());
+    });
+    // a name is written only where it can be read whole: inside the visible view
+    const view = { x1: 0, y1: 0, x2: cy.width(), y2: cy.height() - Math.max(0, this.bottomExcludedRegion() | 0) };
+    const inside = (b) => b.x1 >= view.x1 && b.x2 <= view.x2 && b.y1 >= view.y1 && b.y2 <= view.y2;
+    const keep = new Set();
+    const sides = new Map();
+    // the chosen capability's name first: centred on its route's middle, above the line
+    cy.edges('.active').forEach((edge) => {
+      const label = String(edge.data('label') || '');
+      if (!label) return;
+      const mid = edge.renderedMidpoint();
+      const width = measureTextWidth(label, font) + gap * 2;
+      const height = lineHeight + gap * 2;
+      const box = { x1: mid.x - width / 2, x2: mid.x + width / 2, y1: mid.y - 12 - height / 2, y2: mid.y - 12 + height / 2 };
+      if (!inside(box) || placed.some((other) => overlaps(box, other))) return;
+      placed.push(box);
+      keep.add(edge.id());
+    });
+    order.forEach((node) => {
+      const lines = String(node.data('label') || '').split('\n');
+      const width = Math.max(...lines.map((line) => measureTextWidth(line, font))) + gap * 2;
+      const height = lines.length * lineHeight + gap * 2;
+      const p = node.renderedPosition();
+      const r = node.renderedWidth() / 2;
+      // under the dot, then over it; each centred, else ending at the dot (to its left), else
+      // starting at it
+      const options = [];
+      for (const above of [false, true]) {
+        const y1 = above ? p.y - r - gap - height : p.y + r + gap;
+        const y2 = y1 + height;
+        options.push(
+          { above, side: '', box: { x1: p.x - width / 2, x2: p.x + width / 2, y1, y2 } },
+          { above, side: 'left', box: { x1: p.x + r - width, x2: p.x + r, y1, y2 } },
+          { above, side: 'right', box: { x1: p.x - r, x2: p.x - r + width, y1, y2 } },
+        );
+      }
+      const fit = options.find((o) => inside(o.box) && !placed.some((other) => overlaps(o.box, other)));
+      if (!fit) return;
+      placed.push(fit.box);
+      keep.add(node.id());
+      sides.set(node.id(), fit);
+    });
+    // its own class changes must not schedule it again
+    this._placingNames = true;
+    cy.batch(() => {
+      named.forEach((node) => { if (!keep.has(node.id())) node.removeClass('lod-named'); });
+      keep.forEach((id) => {
+        const element = cy.getElementById(id);
+        if (!element.hasClass('lod-named')) element.addClass('lod-named');
+        const fit = sides.get(id) || { side: '', above: false };
+        element.toggleClass('lod-name-left', fit.side === 'left');
+        element.toggleClass('lod-name-right', fit.side === 'right');
+        element.toggleClass('lod-name-above', !!fit.above);
+      });
+    });
+    this._placingNames = false;
+  }
+
+  _scheduleOverviewNames() {
+    if (this._namesQueued) return;
+    this._namesQueued = true;
+    requestAnimationFrame(() => {
+      this._namesQueued = false;
+      this._placeOverviewNames();
+      this._placeEdgeLabels();
+    });
+  }
+
+  // In the labelled graph, a capability's name is written where it has room: in order of
+  // importance (the chosen one, the highlighted, then the rest in the view, nearest its
+  // centre first), a name is drawn unless its rotated box would overlap a name already drawn
+  // or a media type. The geometry is cytoscape's own (the label's centre, angle and size,
+  // in graph units, so the choice holds at any zoom); without it every name is drawn.
+  _placeEdgeLabels() {
+    if (this.mode !== 'browse' || !this.cy) return;
+    const cy = this.cy;
+    const crowded = cy.edges('.label-crowded');
+    const clear = () => {
+      this._placingNames = true;
+      crowded.removeClass('label-crowded');
+      this._placingNames = false;
+    };
+    if (this._lodOverview) { clear(); return; }
+
+    const ext = cy.extent();
+    const centre = { x: (ext.x1 + ext.x2) / 2, y: (ext.y1 + ext.y2) / 2 };
+    const pad = 4;
+    const boxOf = (edge) => {
+      const r = edge._private && edge._private.rscratch;
+      if (!r || !Number.isFinite(r.labelX) || !Number.isFinite(r.labelWidth) || !r.labelWidth) return null;
+      return {
+        x: r.labelX, y: r.labelY, angle: r.labelAngle || 0,
+        hw: r.labelWidth / 2 + pad, hh: (r.labelHeight || 8) / 2 + pad,
+      };
+    };
+    const corners = (b) => {
+      const c = Math.cos(b.angle), s = Math.sin(b.angle);
+      return [[-b.hw, -b.hh], [b.hw, -b.hh], [b.hw, b.hh], [-b.hw, b.hh]]
+        .map(([x, y]) => [b.x + x * c - y * s, b.y + x * s + y * c]);
+    };
+    // two convex boxes overlap unless an edge of one separates them (separating axes)
+    const separated = (pa, pb) => [pa, pb].some((poly) => poly.some((p, i) => {
+      const q = poly[(i + 1) % poly.length];
+      const nx = q[1] - p[1], ny = p[0] - q[0];
+      const project = (pts) => pts.map(([x, y]) => x * nx + y * ny);
+      const a = project(pa), b = project(pb);
+      return Math.max(...a) < Math.min(...b) || Math.max(...b) < Math.min(...a);
+    }));
+
+    const placed = [];
+    cy.nodes().forEach((node) => {
+      if (node.hasClass('faded')) return;
+      const bb = node.boundingBox({ includeLabels: false });
+      placed.push([[bb.x1, bb.y1], [bb.x2, bb.y1], [bb.x2, bb.y2], [bb.x1, bb.y2]]);
+    });
+
+    const inView = (b) => b.x >= ext.x1 && b.x <= ext.x2 && b.y >= ext.y1 && b.y <= ext.y2;
+    const rank = (edge) => (edge.hasClass('active') ? 2 : 0) + (edge.hasClass('highlighted') ? 1 : 0);
+    const candidates = [];
+    let measured = true;
+    cy.edges().forEach((edge) => {
+      if (edge.hasClass('faded') || !edge.data('label')) return;
+      // a loop is unnamed unless chosen (see the browse-loop styles)
+      if (edge.hasClass('browse-loop') && !edge.hasClass('active')) return;
+      const b = boxOf(edge);
+      if (!b) { measured = false; return; }
+      candidates.push({ edge, b, rank: rank(edge), view: inView(b) ? 1 : 0, d: Math.hypot(b.x - centre.x, b.y - centre.y) });
+    });
+    if (!measured) { clear(); return; }
+    candidates.sort((a, b) => (b.rank - a.rank) || (b.view - a.view) || (a.d - b.d));
+
+    const hide = new Set();
+    candidates.forEach(({ edge, b }) => {
+      const poly = corners(b);
+      if (placed.some((other) => !separated(poly, other))) { hide.add(edge.id()); return; }
+      placed.push(poly);
+    });
+
+    this._placingNames = true;
+    cy.batch(() => {
+      crowded.forEach((edge) => { if (!hide.has(edge.id())) edge.removeClass('label-crowded'); });
+      hide.forEach((id) => {
+        const edge = cy.getElementById(id);
+        if (!edge.hasClass('label-crowded')) edge.addClass('label-crowded');
+      });
+    });
+    this._placingNames = false;
+  }
+
+  // The capabilities' names (the edges' labels and titles) in the host's case
+  _formatCapTitles(elements) {
+    return elements.map((element) => {
+      const data = element && element.data;
+      if (!data || !data.source || !data.target) return element;
+      const next = Object.assign({}, data);
+      if (typeof data.label === 'string') next.label = this.formatCapTitle(data.label);
+      if (typeof data.title === 'string') next.title = this.formatCapTitle(data.title);
+      return Object.assign({}, element, { data: next });
+    });
+  }
+
+  // The box a fit measures: the elements with their labels, except in the overview, whose
+  // labels are a constant size on screen (larger in the graph the further out it is) and
+  // would make every fit zoom out further than the one before
+  _fitBox(eles) {
+    return eles.boundingBox({ includeLabels: !this._lodOverview, includeOverlays: false });
+  }
+
+  _applyLevelOfDetail() {
+    if (this.mode !== 'browse' || !this.cy) return;
+    const cy = this.cy;
+    const zoom = cy.zoom();
+    const overview = zoom < CapFabRenderer.LOD_LABEL_ZOOM;
+    if (!overview && !this._lodOverview) return;
+    // Drawn very small (the whole registry on a phone), the dots would run into each other:
+    // they shrink with the zoom below a tenth, to no less than half their size
+    const scale = Math.min(1, Math.max(0.5, zoom / 0.1));
+    cy.batch(() => {
+      if (overview) {
+        cy.nodes().forEach((node) => {
+          // 8px for a leaf, growing with the square root of its connections (UTF-8, the
+          // hub every text capability meets, about 20px)
+          node.data({
+            lodSize: scale * (6 + 2.2 * Math.sqrt(node.degree())) / zoom,
+            lodFont: 11 / zoom,
+            lodGap: 3 / zoom,
+            lodGapNeg: -3 / zoom,
+          });
+        });
+        cy.edges().data({
+          lodWidth: scale * 1.25 / zoom,
+          lodWidthStrong: 2.5 / zoom,
+          lodFontEdge: 11 / zoom,
+          lodGap: 3 / zoom,
+          lodLift: -12 / zoom,
+          lodLoopStep: 3 / zoom,
+        });
+        // a loop stands clear of its dot: cytoscape cannot draw one whose step lies inside the
+        // node (most of the overview's loops went undrawn), so a loop's step is half its dot's
+        // size and a little more, the loops on a hub nested low under the dots above it
+        cy.edges('.browse-loop').forEach((edge) => {
+          edge.data('lodLoopStep', edge.source().data('lodSize') * 0.5 + 3 / zoom);
+        });
+        cy.elements().addClass('lod-overview');
+      } else {
+        cy.elements().removeClass('lod-overview');
+      }
+    });
+    this._lodOverview = overview;
+  }
+
   // Fit padding must scale down in very short viewports. The compact
   // machine-select graph pane is only ~100px tall; a fixed 50px inset
   // leaves no vertical room, so the bootstrap fit degenerates and the
@@ -3183,7 +3992,7 @@ class CapFabRenderer {
     if (containerWidth <= 0 || containerHeight <= 0) return;
     const elements = cy.elements();
     if (elements.length === 0) return;
-    const bb = elements.boundingBox({ includeLabels: true, includeOverlays: false });
+    const bb = this._fitBox(elements);
     if (bb.w === 0 && bb.h === 0) return;
 
     const excluded = Math.max(0, this.bottomExcludedRegion() | 0);
@@ -3255,10 +4064,15 @@ class CapFabRenderer {
     // that sits comfortably above this relaxed minimum, so opening
     // the view shows the graph centred with margin rather than
     // bleeding to all four edges.
-    const bb = this.cy.elements().boundingBox({ includeLabels: true, includeOverlays: false });
+    const bb = this._fitBox(this.cy.elements());
+    // The graph has to fit what can be seen: the canvas less the region the host covers
+    // at its bottom (`bottomExcludedRegion`), as the fits measure it. Measured against the
+    // whole canvas, the floor sat above the zoom a fit needs, and a graph taller than the
+    // visible part could never be fitted into it.
+    const visibleH = Math.max(1, h - Math.max(0, this.bottomExcludedRegion() | 0));
     let zoomMin;
     if (bb.w > 0 && bb.h > 0) {
-      const strictFit = Math.min(w / bb.w, h / bb.h);
+      const strictFit = Math.min(w / bb.w, visibleH / bb.h);
       zoomMin = strictFit * (1 - CapFabRenderer.ZOOM_OUT_FIT_SLACK);
     } else {
       // Empty / degenerate graph — leave the min loose; there's
@@ -3486,6 +4300,11 @@ class CapFabRenderer {
     this.cy.on('zoom pan', function () {
       if (!self._internalPanZoom) self._markInitialFitDone();
     });
+    this.cy.on('zoom', function () { self._applyLevelOfDetail(); });
+    // names follow the view and the choice: every zoom or pan, and every change of what is
+    // highlighted, places them again (once a frame)
+    this.cy.on('viewport', function () { self._scheduleOverviewNames(); });
+    this.cy.on('class', function () { if (!self._placingNames) self._scheduleOverviewNames(); });
 
     this.cy.on('tap', 'node', function (evt) {
       evt.stopPropagation();
@@ -3559,13 +4378,20 @@ class CapFabRenderer {
       const bodyTitle = node.data('bodyTitle');
       if (bodyTitle) return `${bodyTitle}: ${node.data('fullUrn') || node.id()}`;
     }
-    return node.data('fullUrn') || node.id();
+    const urn = node.data('fullUrn') || node.id();
+    const title = node.data('mediaTitle');
+    if (this.mode === 'browse' && title && title !== urn) return { title, detail: urn };
+    return urn;
   }
 
   _tooltipTextForEdge(edge) {
     const full = edge.data('fullUrn');
-    if (typeof full === 'string' && full.length > 0) return full;
-    return edge.data('title') || '';
+    const title = edge.data('title');
+    if (typeof full === 'string' && full.length > 0) {
+      if (this.mode === 'browse' && title && title !== full) return { title, detail: full };
+      return full;
+    }
+    return title || '';
   }
 
   _handleNodeTap(node) {
@@ -3648,6 +4474,37 @@ class CapFabRenderer {
     }
   }
 
+  // A set of capabilities picked out of the registry (the host's choice of tags: coerce, its 22):
+  // their edges and the types they join stand out, the rest is faded. Nothing is selected and
+  // the view stays where it is: the choice is a filter, not a destination. An empty set clears
+  // the emphasis. Capabilities are matched by their canonical URN, as the registry writes it.
+  highlightCapabilities(caps) {
+    if (this.mode !== 'browse') {
+      throw new Error(`CapFabRenderer: highlightCapabilities is only valid in browse mode (current: ${this.mode})`);
+    }
+    if (!Array.isArray(caps)) {
+      throw new Error('CapFabRenderer: highlightCapabilities takes an array of capabilities');
+    }
+    if (!this.cy || !this._layoutReady) {
+      this._pendingFocusCaps = caps;
+      return;
+    }
+    const urns = new Set(caps.map((cap) => this._capUrnString(cap)));
+    const cy = this.cy;
+    cy.batch(() => {
+      cy.elements().removeClass('highlighted active faded');
+      if (urns.size === 0) return;
+      const chosen = cy.edges().filter((edge) => {
+        const edgeCap = this.capabilitiesByEdgeId.get(edge.id());
+        return !!edgeCap && urns.has(edgeCap.urn);
+      });
+      if (chosen.length === 0) return;
+      cy.elements().addClass('faded');
+      chosen.removeClass('faded').addClass('highlighted');
+      chosen.connectedNodes().removeClass('faded').addClass('highlighted');
+    });
+  }
+
   _capUrnString(cap) {
     if (!cap || typeof cap !== 'object') {
       throw new Error('CapFabRenderer: cap must be an object');
@@ -3957,15 +4814,19 @@ class CapFabRenderer {
     this.cy.stop(true);
     if (!eles || eles.length === 0) eles = this.cy.elements();
 
-    const bb = eles.boundingBox({ includeLabels: true, includeOverlays: false });
+    const bb = this._fitBox(eles);
     if (bb.w === 0 && bb.h === 0) return;
 
     const containerWidth = this.cy.width();
     const containerHeight = this.cy.height();
     const excluded = Math.max(0, this.bottomExcludedRegion() | 0);
     padding = this._resolvedFitPadding(padding, containerWidth, containerHeight, excluded);
+    // The overview's names are not in the measured box (see `_fitBox`) and sit centred under
+    // their dots: room is kept for half a typical name at either side, whatever the height
+    // allows the padding to be
+    const paddingX = this._lodOverview ? Math.max(padding, Math.min(containerWidth / 4, 90)) : padding;
 
-    const visibleWidth = containerWidth - padding * 2;
+    const visibleWidth = containerWidth - paddingX * 2;
     const visibleHeight = containerHeight - excluded - padding * 2;
     if (visibleWidth <= 0 || visibleHeight <= 0) return;
 
@@ -4004,10 +4865,21 @@ class CapFabRenderer {
   // Tooltip helpers.
   // ===========================================================================
 
+  // `text` is a string, or { title, detail }: a name over the URN it stands for (browse mode,
+  // where a crowded name may not be drawn in the graph and the tooltip is where it is read)
   _showTooltip(text, mouseEvent) {
     if (!this.tooltip) return;
     if (!text) return;
-    this.tooltip.textContent = text;
+    if (typeof text === 'string') {
+      this.tooltip.textContent = text;
+    } else {
+      const title = document.createElement('div');
+      title.textContent = text.title;
+      title.style.cssText = 'color: var(--text-primary); font-family: var(--font-family, inherit); font-size: var(--graph-tooltip-title-size, 12px); font-weight: 600; word-break: normal; margin-bottom: 2px;';
+      const detail = document.createElement('div');
+      detail.textContent = text.detail;
+      this.tooltip.replaceChildren(title, detail);
+    }
     this.tooltip.style.display = 'block';
     const x = mouseEvent ? mouseEvent.clientX : 0;
     const y = mouseEvent ? mouseEvent.clientY : 0;