@webpieces/nx-webpieces-rules 0.4.528 → 0.4.530

package/src/lib/runtime-visualizer.js

@@ -16,7 +16,11 @@
  * Shape says what a node IS and line style says what a call IS. Solid = rpc: the
  * request follows the arrow and the response flows back. Dashed = event: it flows
  * in the arrow's direction and returns once it is queued. A queue is a sideways
- * cylinder, a datastore an upright one.
+ * cylinder, a datastore an upright one. A queue box lists ONE LINE PER QUEUE: the
+ * unit underneath is still the METHOD (what Terraform creates, and what
+ * runtime-dependencies.json records), but queues of one contract sharing the same
+ * producers and consumers are drawn together instead of as adjacent near-identical
+ * boxes — every queue is still named, only the node count drops.
  *
  * Calls that leave the repo (a contract NOTHING in-repo implements — firestore,
  * gmail, ...) are drawn as terminal nodes, so the vendor systems that actually
@@ -26,9 +30,11 @@
  * derivation, levels and cycle detection never see them.
  *
  * The same is true in the other direction for endpoints nothing in-repo CALLS: a
- * `cron` method hangs off a clock and an `external` method off a dashed inbound
- * box. Those are the entry points that wake a service up at 3am, and a graph
- * built only from in-repo callers cannot show them at all.
+ * `cron` method hangs off a clock and an `external` method off a box naming the
+ * CALLER that posts to it (`twilio`), in the same id space as the outbound
+ * systems, so a vendor we both call and are called by is ONE box. Those are the
+ * entry points that wake a service up at 3am, and a graph built only from in-repo
+ * callers cannot show them at all.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RuntimeVizOptions = void 0;
@@ -38,64 +44,7 @@ const tslib_1 = require("tslib");
 const fs = tslib_1.__importStar(require("fs"));
 const path = tslib_1.__importStar(require("path"));
 const dot_syntax_1 = require("./dot-syntax");
-const LEVEL_COLORS = {
-    0: '#E8F5E9',
-    1: '#E3F2FD',
-    2: '#FFF3E0',
-    3: '#FCE4EC',
-};
-const QUEUE_FILL = '#FFF3E0';
-/**
- * The queue node is an `Mrecord` whose FIRST field is empty, which draws a rounded outline with a
- * vertical cap line near one end — a cylinder lying on its side, distinguishing a queue from the
- * upright cylinder that now means a database.
- *
- * Two things here are load-bearing and easy to break:
- *
- * 1. NO surrounding `{}`. Record fields lay out along the rank direction, and this graph is
- *    `rankdir=TB` (see {@link generateRuntimeDot}), where the default is horizontal — which is what
- *    we want. Adding braces TOGGLES that, turning the cap line into a band across the top.
- * 2. The leading space is the empty field. The record parser trims it to nothing, which is the
- *    point; it must survive as its own field, so the `|` cannot be dropped.
- *
- * Graphviz has no sideways cylinder and never has: `orientation=` is documented as rotating POLYGON
- * shapes, and `cylinder` is drawn with beziers, so it silently ignores the attribute (graphviz issue
- * #2244, open since 2022 and still reproducible on 13.0.0). This is the closest native shape.
- */
-const QUEUE_SHAPE = 'Mrecord';
-const QUEUE_LABEL_PREFIX = ' |';
-/**
- * Marker class stamped on every queue node. Graphviz copies `class` straight into the rendered
- * `<g class="node wp_queue">`, which is how runtime-visualizer.client.js finds these nodes and
- * redraws them as true horizontal cylinders in the browser.
- *
- * A CLASS rather than an id prefix, because queue-kind EXTERNAL systems are queues too and share the
- * `system__` id space with databases — which must stay upright. Underscored, not hyphenated: DOT
- * emits a hyphen as `&#45;`, which is harmless but needlessly surprising to anyone reading the SVG.
- */
-const QUEUE_CLASS = 'wp_queue';
-/** Fill for the upright cylinder standing for an external DATASTORE (firestore, postgres, ...). */
-const DATABASE_FILL = '#E1F5FE';
-/** Shape per external-system kind. Anything unrecognised falls back to the generic dashed box. */
-const EXTERNAL_SHAPES = {
-    database: 'cylinder',
-    cache: 'cylinder',
-    queue: 'Mrecord',
-    storage: 'folder',
-};
-/** Fill per external-system kind, paired with {@link EXTERNAL_SHAPES}. */
-const EXTERNAL_FILLS = {
-    database: DATABASE_FILL,
-    cache: DATABASE_FILL,
-    queue: QUEUE_FILL,
-    storage: '#F3E5F5',
-};
-/** Fill + border for the dashed terminal node standing for a system outside this repo. */
-const EXTERNAL_FILL = '#FAFAFA';
-const EXTERNAL_BORDER = '#9E9E9E';
-/** Fill + border for the clock node standing for a scheduler-driven endpoint. */
-const CRON_FILL = '#FFF9C4';
-const CRON_BORDER = '#F9A825';
+const runtime_viz_theme_1 = require("./runtime-viz-theme");
 /** Apis per line inside a node label — beyond this the box grows wider than it is readable. */
 const APIS_PER_LABEL_LINE = 3;
 /** Separator for the (service, external-library) grouping key; illegal in both project names. */
@@ -166,43 +115,171 @@ function nodeLabel(name, svc) {
     return label;
 }
 /**
- * DOT for ONE runtime edge. rpc → a direct labeled SOLID arrow (producer calls consumer, response
- * comes back). pubsub → the producer enqueues and the consumer is delivered later, so we draw
- * producer → QUEUE → consumer through a sideways-cylinder queue node with DASHED arrows.
+ * DOT for ONE NON-QUEUED runtime edge: a direct labeled SOLID arrow (producer calls consumer, the
+ * response comes back). Queued (pubsub) hops are drawn by {@link queuesDot} instead, because they
+ * are merged across methods and therefore cannot be emitted one edge at a time.
  *
  * Solid vs dashed is the graph's one line-level distinction: solid is a call that returns a
  * response, dashed is an event that returns as soon as it is queued.
  */
 // webpieces-disable no-function-outside-class -- DOT string builder, matching getShortName in this file
-function edgeDot(edge, queues) {
+function edgeDot(edge) {
     const from = (0, dot_syntax_1.dotValue)(getShortName(edge.from));
     const to = (0, dot_syntax_1.dotValue)(getShortName(edge.to));
-    // Kept RAW: an ordinary edge label needs dotValue, the record-mode queue label needs
-    // recordValue, and recordValue already applies dotValue — escaping here would double it.
     const viaRaw = edge.via.map((v) => getShortName(v)).join(', ');
-    if (edge.type !== 'pubsub') {
-        return `  "${from}" -> "${to}" [label="${(0, dot_syntax_1.dotValue)(viaRaw)}"];\n`;
+    return `  "${from}" -> "${to}" [label="${(0, dot_syntax_1.dotValue)(viaRaw)}"];\n`;
+}
+/** The VISIBLE producers and consumers of one queue, gathered from the edges that survived hiding. */
+class QueueEndpoints {
+    producers = new Set();
+    consumers = new Set();
+}
+/**
+ * One drawn queue BOX: the queue keys (`Api.method`) it shows, and the endpoints they all share.
+ * Several keys land in one box only when they agree on all three of contract, producers and
+ * consumers — see {@link queuesDot}.
+ */
+class QueueGroup {
+    members;
+    producers;
+    consumers;
+    constructor(members, producers, consumers) {
+        this.members = members;
+        this.producers = producers;
+        this.consumers = consumers;
     }
-    // The queue node is identified by the METHOD, not by the (from,to) pair, so every producer and
-    // consumer of one queue converges on ONE box — including a service that enqueues to itself,
-    // which then renders as a visible loop through its queue instead of vanishing.
-    const queueId = edge.queue === undefined ? `queue__${from}__${to}` : `queue__${dotId(edge.queue)}`;
-    const queueName = edge.queue === undefined ? undefined : queues[edge.queue]?.queueName;
+}
+/**
+ * The label line for ONE queue inside a box: `Api.method`, and the Terraform queue name ONLY when it
+ * is not the derived `${Api}-${method}`.
+ *
+ * Printing a derived name was pure restatement — the line above it already said `Api.method`, so
+ * every queue box carried a second line that added nothing and doubled its height. A `@Queue(...)`
+ * OVERRIDE is the opposite: that string appears nowhere else on the graph, and it is the one string
+ * Terraform must match, so it stays.
+ */
+// webpieces-disable no-function-outside-class -- DOT label builder, matching getShortName in this file
+function queueLine(key, queue) {
+    const line = (0, dot_syntax_1.recordValue)(key);
+    if (queue === undefined)
+        return line;
+    if (queue.queueName === `${queue.api}-${queue.method}`)
+        return line;
+    return `${line}\\nqueue: ${(0, dot_syntax_1.recordValue)(queue.queueName)}`;
+}
+/** The node statement + enqueue/deliver arrows for one queue box. Names arrive pre-escaped. */
+// webpieces-disable no-function-outside-class -- DOT string builder, matching getShortName in this file
+function queueBoxDot(id, body, producers, consumers) {
     // Record-mode label: the text must clear recordValue(), and QUEUE_LABEL_PREFIX supplies the
-    // empty leading field that draws the cylinder's end cap.
-    const body = edge.queue === undefined
-        ? `${(0, dot_syntax_1.recordValue)(viaRaw)}\\nqueue`
-        : `${(0, dot_syntax_1.recordValue)(edge.queue)}\\nqueue: ${(0, dot_syntax_1.recordValue)(queueName ?? edge.queue)}`;
-    return (`  "${queueId}" [shape=${QUEUE_SHAPE}, style="filled", fillcolor="${QUEUE_FILL}", ` +
-        `class="${QUEUE_CLASS}", label="${QUEUE_LABEL_PREFIX}${body}"];\n` +
-        `  "${from}" -> "${queueId}" [label="enqueue", style=dashed];\n` +
-        `  "${queueId}" -> "${to}" [label="deliver", style=dashed];\n`);
+    // empty leading field that draws the cylinder's end cap. Drop it and the node silently
+    // degrades to a plain box.
+    let dot = `  "${id}" [shape=${runtime_viz_theme_1.QUEUE_SHAPE}, style="filled", fillcolor="${runtime_viz_theme_1.QUEUE_FILL}", ` +
+        `class="${runtime_viz_theme_1.QUEUE_CLASS}", label="${runtime_viz_theme_1.QUEUE_LABEL_PREFIX}${body}"];\n`;
+    for (const producer of producers)
+        dot += `  "${producer}" -> "${id}" [label="enqueue", style=dashed];\n`;
+    for (const consumer of consumers)
+        dot += `  "${id}" -> "${consumer}" [label="deliver", style=dashed];\n`;
+    return dot;
+}
+/**
+ * Group the queued hops into boxes. The key is (contract, producer SET, consumer SET) — NOT the
+ * (from,to) pair of some edge.
+ *
+ * A queue node converges EVERY producer and consumer of its method onto one box, so keying by a
+ * service PAIR would re-split a two-producer queue into two boxes and invent topology nobody wrote.
+ * Only queues of the same contract whose producer and consumer sets are IDENTICAL may share a box;
+ * anything else stays separate, because merging it would assert a routing that does not exist.
+ */
+// webpieces-disable no-function-outside-class -- DOT string builder, matching getShortName in this file
+function groupQueues(byQueue, graph) {
+    const groups = new Map();
+    // Sorted keys → the first member of every group, and therefore its node id, is deterministic.
+    for (const key of [...byQueue.keys()].sort()) {
+        const ends = byQueue.get(key);
+        const producers = [...ends.producers].sort();
+        const consumers = [...ends.consumers].sort();
+        const api = graph.queues[key]?.api ?? key.split('.')[0];
+        const mergeKey = [api, producers.join(','), consumers.join(',')].join(PAIR_SEP);
+        const existing = groups.get(mergeKey);
+        if (existing === undefined)
+            groups.set(mergeKey, new QueueGroup([key], producers, consumers));
+        else
+            existing.members.push(key);
+    }
+    return [...groups.values()];
+}
+/**
+ * The queued half of the graph: producer → QUEUE → consumer, drawn with a sideways-cylinder node and
+ * DASHED arrows (an event returns as soon as it is queued).
+ *
+ * One BOX may list several queues, one per line. The unit Cloud Tasks and Terraform create is still
+ * the METHOD — that is what runtime-dependencies.json records and this render never changes it — but
+ * two methods of one contract flowing between exactly the same producers and consumers drew two
+ * adjacent boxes whose only difference was the method name, and each carried a `queue:` line that
+ * merely restated it. Listing them inside ONE box keeps every queue named (you can still see which
+ * one is stuck) at a fraction of the node count.
+ */
+// webpieces-disable no-function-outside-class -- DOT string builder, matching getShortName in this file
+function queuesDot(graph, hidden) {
+    const queued = graph.runtimeEdges.filter((e) => e.type === 'pubsub' && !hidden.has(e.from) && !hidden.has(e.to));
+    if (queued.length === 0)
+        return '';
+    let dot = '\n  // Queued hops. Each LINE in a box is one Cloud Tasks queue; queues of one contract\n' +
+        '  // sharing the same producers AND consumers are drawn in a single box.\n';
+    // A contract with no committed method table (a dependencies.json predating apiContracts) has no
+    // per-method queue at all, so it keeps the historical unnamed per-pair box.
+    const byQueue = new Map();
+    for (const edge of queued) {
+        const from = (0, dot_syntax_1.dotValue)(getShortName(edge.from));
+        const to = (0, dot_syntax_1.dotValue)(getShortName(edge.to));
+        if (edge.queue === undefined) {
+            // Kept RAW: recordValue already applies dotValue, so escaping here would double it.
+            const viaRaw = edge.via.map((v) => getShortName(v)).join(', ');
+            dot += queueBoxDot(`queue__${from}__${to}`, `${(0, dot_syntax_1.recordValue)(viaRaw)}\\nqueue`, [from], [to]);
+            continue;
+        }
+        if (!byQueue.has(edge.queue))
+            byQueue.set(edge.queue, new QueueEndpoints());
+        byQueue.get(edge.queue).producers.add(from);
+        byQueue.get(edge.queue).consumers.add(to);
+    }
+    for (const group of groupQueues(byQueue, graph)) {
+        const body = group.members
+            .map((key) => queueLine(key, graph.queues[key]))
+            .join('\\n');
+        dot += queueBoxDot(`queue__${dotId(group.members[0])}`, body, group.producers, group.consumers);
+    }
+    return dot;
 }
 /** A DOT-safe node-id fragment: anything but letters, digits and `_` becomes `_`. */
 // webpieces-disable no-function-outside-class -- DOT id builder, matching getShortName in this file
 function dotId(raw) {
     return raw.replace(/[^A-Za-z0-9_]/g, '_');
 }
+/**
+ * ONE external-system node statement: the shape/fill of what the system IS, its label, and a
+ * parenthesised subtitle saying which way it faces.
+ *
+ * Shared by the OUTBOUND systems ({@link externalSystemsDot}) and the INBOUND callers
+ * ({@link triggerDot}) on purpose. They emit into the SAME `system__<identity>` id space, so a
+ * vendor this repo both calls and is called by is one box with arrows in both directions — and a
+ * copy-pasted attribute string would have let the two drift until they stopped being one box.
+ */
+// webpieces-disable no-function-outside-class -- DOT string builder, matching getShortName in this file
+function externalSystemNodeDot(identity, kind, label, subtitle) {
+    const shape = runtime_viz_theme_1.EXTERNAL_SHAPES[kind] ?? 'box';
+    const fill = runtime_viz_theme_1.EXTERNAL_FILLS[kind] ?? runtime_viz_theme_1.EXTERNAL_FILL;
+    // An Mrecord-shaped system needs the same empty leading field as a queue node, or it renders as
+    // a plain box and silently loses the sideways-cylinder read.
+    const isQueue = shape === runtime_viz_theme_1.QUEUE_SHAPE;
+    const prefix = isQueue ? runtime_viz_theme_1.QUEUE_LABEL_PREFIX : '';
+    const text = isQueue ? (0, dot_syntax_1.recordValue)(label) : (0, dot_syntax_1.dotValue)(label);
+    // Only a queue-kind system is marked: a database here is an UPRIGHT cylinder and must not be
+    // caught by the browser-side reshaping that lays queues on their side.
+    const marker = isQueue ? `class="${runtime_viz_theme_1.QUEUE_CLASS}", ` : '';
+    return (`  "system__${dotId(identity)}" [shape=${shape}, style="filled", fillcolor="${fill}", ` +
+        `${marker}label="${prefix}${text}\\n(${subtitle})"];\n`);
+}
 /**
  * The clock and outside-system nodes for endpoints NOTHING in-repo calls.
  *
@@ -211,12 +288,26 @@ function dotId(raw) {
  * absent — a server's most operationally interesting endpoint could be invisible on its own graph.
  * Both are drawn pointing INTO the service that serves them, the opposite direction from
  * {@link externalDot}'s outbound vendor calls.
+ *
+ * The inbound box names the CALLER (`twilio`), never the contract. Naming the contract was the whole
+ * bug: it restated what the service box directly below already says, while the one fact the box
+ * exists to convey — which vendor is posting to us — appeared nowhere. The contract keeps its place
+ * on the EDGE label, where `WhatsAppApi.inbound` reads as "…posts to this method".
+ *
+ * Identity is the caller's label in the SAME `system__` space {@link externalSystemsDot} uses, which
+ * buys three things at once: two vendors hitting one contract are two boxes, one vendor hitting three
+ * methods is one box with three arrows, and a vendor this repo also CALLS is that same single box.
+ * `options` is passed in for the last of those — when that outbound half will be drawn, this half
+ * must not restate the node statement.
  */
 // webpieces-disable no-function-outside-class -- DOT string builder, matching getShortName in this file
-function triggerDot(graph, hidden) {
+function triggerDot(graph, hidden, options) {
     const triggers = graph.triggers.filter((t) => !hidden.has(t.service));
     if (triggers.length === 0)
         return '';
+    // Identities externalSystemsDot is about to draw; skipped here so the node is stated ONCE.
+    const drawnOutbound = new Set(options.showExternalNodes ? Object.keys(graph.externalSystems ?? {}) : []);
+    const emitted = new Set();
     let dot = '\n  // Entry points nothing in this repo calls: a clock, or a system outside the repo.\n';
     for (const trigger of triggers) {
         const service = (0, dot_syntax_1.dotValue)(getShortName(trigger.service));
@@ -225,16 +316,27 @@ function triggerDot(graph, hidden) {
             const id = `cron__${dotId(`${trigger.api}_${trigger.method}`)}`;
             const schedule = (0, dot_syntax_1.dotValue)(trigger.queueName ?? `${trigger.api}-${trigger.method}`);
             dot +=
-                `  "${id}" [shape=circle, style="filled", fillcolor="${CRON_FILL}", ` +
-                    `color="${CRON_BORDER}", label="⏰\\ncron"];\n` +
-                    `  "${id}" -> "${service}" [label="${label}\\n${schedule}", color="${CRON_BORDER}"];\n`;
+                `  "${id}" [shape=circle, style="filled", fillcolor="${runtime_viz_theme_1.CRON_FILL}", ` +
+                    `color="${runtime_viz_theme_1.CRON_BORDER}", label="⏰\\ncron"];\n` +
+                    `  "${id}" -> "${service}" [label="${label}\\n${schedule}", color="${runtime_viz_theme_1.CRON_BORDER}"];\n`;
             continue;
         }
-        const id = `inbound__${dotId(trigger.api)}`;
-        dot +=
-            `  "${id}" [shape=box, style="dashed,filled", fillcolor="${EXTERNAL_FILL}", ` +
-                `color="${EXTERNAL_BORDER}", label="${(0, dot_syntax_1.dotValue)(trigger.api)}\\n(external caller)"];\n` +
-                `  "${id}" -> "${service}" [label="${label}", style=dashed, color="${EXTERNAL_BORDER}"];\n`;
+        const caller = trigger.caller;
+        // Undeclared: only possible for a graph generated BEFORE the caller was required (generation
+        // now fails instead). DOTTED and question-marked, so "we were never told who this is" cannot
+        // be mistaken for a named vendor.
+        const id = caller === undefined
+            ? `inbound__${dotId(trigger.api)}`
+            : `system__${dotId(caller.label)}`;
+        if (!emitted.has(id) && !(caller !== undefined && drawnOutbound.has(caller.label))) {
+            emitted.add(id);
+            dot +=
+                caller === undefined
+                    ? `  "${id}" [shape=box, style="dotted,filled", fillcolor="${runtime_viz_theme_1.EXTERNAL_FILL}", ` +
+                        `color="${runtime_viz_theme_1.EXTERNAL_BORDER}", label="${(0, dot_syntax_1.dotValue)(trigger.api)}\\n? unknown caller"];\n`
+                    : externalSystemNodeDot(caller.label, caller.kind, caller.label, 'external caller');
+        }
+        dot += `  "${id}" -> "${service}" [label="${label}", style=dashed, color="${runtime_viz_theme_1.EXTERNAL_BORDER}"];\n`;
     }
     return dot;
 }
@@ -257,19 +359,7 @@ function externalSystemsDot(graph, hidden) {
     let dot = '\n  // Declared external systems — drawn with the shape of what they actually are.\n';
     for (const id of ids) {
         const system = systems[id];
-        const shape = EXTERNAL_SHAPES[system.kind] ?? 'box';
-        const fill = EXTERNAL_FILLS[system.kind] ?? EXTERNAL_FILL;
-        // An Mrecord-shaped system needs the same empty leading field as a queue node, or it
-        // renders as a plain box and silently loses the sideways-cylinder read.
-        const isQueue = shape === QUEUE_SHAPE;
-        const prefix = isQueue ? QUEUE_LABEL_PREFIX : '';
-        const text = isQueue ? (0, dot_syntax_1.recordValue)(system.label) : (0, dot_syntax_1.dotValue)(system.label);
-        // Only a queue-kind system is marked: a database here is an UPRIGHT cylinder and must not be
-        // caught by the browser-side reshaping that lays queues on their side.
-        const marker = isQueue ? `class="${QUEUE_CLASS}", ` : '';
-        dot +=
-            `  "system__${dotId(id)}" [shape=${shape}, style="filled", fillcolor="${fill}", ` +
-                `${marker}label="${prefix}${text}\\n(external ${(0, dot_syntax_1.dotValue)(system.kind)})"];\n`;
+        dot += externalSystemNodeDot(id, system.kind, system.label, `external ${(0, dot_syntax_1.dotValue)(system.kind)}`);
     }
     for (const id of ids) {
         const system = systems[id];
@@ -317,8 +407,8 @@ function externalDot(graph, hidden) {
     const externals = new Set([...apisByPair.keys()].map((key) => key.split(PAIR_SEP)[1]));
     for (const external of [...externals].sort()) {
         dot +=
-            `  "external__${external}" [shape=box, style="dashed,filled", fillcolor="${EXTERNAL_FILL}", ` +
-                `color="${EXTERNAL_BORDER}", label="${external}\\n(external)"];\n`;
+            `  "external__${external}" [shape=box, style="dashed,filled", fillcolor="${runtime_viz_theme_1.EXTERNAL_FILL}", ` +
+                `color="${runtime_viz_theme_1.EXTERNAL_BORDER}", label="${external}\\n(external)"];\n`;
     }
     for (const key of [...apisByPair.keys()].sort()) {
         const parts = key.split(PAIR_SEP);
@@ -329,7 +419,7 @@ function externalDot(graph, hidden) {
         // "outside the repo" is already said by the node's dashed border.
         dot +=
             `  "${(0, dot_syntax_1.dotValue)(getShortName(service))}" -> "external__${external}" ` +
-                `[label="${via}", color="${EXTERNAL_BORDER}"];\n`;
+                `[label="${via}", color="${runtime_viz_theme_1.EXTERNAL_BORDER}"];\n`;
     }
     return dot;
 }
@@ -347,16 +437,20 @@ function generateRuntimeDot(graph, title = 'WebPieces Runtime Architecture', opt
         if (hidden.has(name))
             continue;
         const svc = graph.services[name];
-        const color = LEVEL_COLORS[svc.level] || '#F5F5F5';
+        const color = runtime_viz_theme_1.LEVEL_COLORS[svc.level] || '#F5F5F5';
         dot += `  "${(0, dot_syntax_1.dotValue)(getShortName(name))}" [fillcolor="${color}", label="${nodeLabel(name, svc)}"];\n`;
     }
     dot += '\n';
     for (const edge of graph.runtimeEdges) {
         if (hidden.has(edge.from) || hidden.has(edge.to))
             continue;
-        dot += edgeDot(edge, graph.queues);
+        // Queued hops are merged across methods, so they cannot be emitted one edge at a time.
+        if (edge.type === 'pubsub')
+            continue;
+        dot += edgeDot(edge);
     }
-    dot += triggerDot(graph, hidden);
+    dot += queuesDot(graph, hidden);
+    dot += triggerDot(graph, hidden, options);
     if (options.showExternalNodes) {
         dot += externalSystemsDot(graph, hidden);
         dot += externalDot(graph, hidden);
@@ -377,68 +471,6 @@ function generateRuntimeDot(graph, title = 'WebPieces Runtime Architecture', opt
  * make writing the HTML depend on a `dot` binary being installed — a dependency this tool does not
  * otherwise have, since rendering happens in the browser.
  */
-class LegendSwatches {
-    service = '<svg width="46" height="26"><rect x="1" y="3" width="44" height="20" rx="7" fill="#E8F5E9" stroke="#333"/></svg>';
-    /**
-     * A cylinder on its side — the SAME geometry runtime-visualizer.client.js draws on the real
-     * node, so the legend cannot drift from the picture it explains.
-     */
-    queue = `<svg width="46" height="26"><path d="M9,5 H37 A8,8 0 0 1 37,21 H9 A8,8 0 0 1 9,5 Z" fill="${QUEUE_FILL}" stroke="#333"/>` +
-        '<path d="M9,5 A8,8 0 0 1 9,21" fill="none" stroke="#333"/></svg>';
-    database = `<svg width="46" height="26"><path d="M8,7 a15,4 0 0 1 30,0 v12 a15,4 0 0 1 -30,0 z" fill="${DATABASE_FILL}" stroke="#333"/>` +
-        '<path d="M8,7 a15,4 0 0 0 30,0" fill="none" stroke="#333"/></svg>';
-    storage = '<svg width="46" height="26"><path d="M2,22 V6 H16 l3,3 H44 V22 Z" fill="#F3E5F5" stroke="#333"/></svg>';
-    external = `<svg width="46" height="26"><rect x="1" y="3" width="44" height="20" fill="${EXTERNAL_FILL}" ` +
-        `stroke="${EXTERNAL_BORDER}" stroke-dasharray="4,3"/></svg>`;
-    cron = `<svg width="46" height="26"><circle cx="23" cy="13" r="11" fill="${CRON_FILL}" stroke="${CRON_BORDER}"/>` +
-        '<text x="23" y="18" font-size="12" text-anchor="middle">&#9200;</text></svg>';
-    solid = '<svg width="60" height="20"><line x1="2" y1="10" x2="48" y2="10" stroke="#333" stroke-width="1.5"/>' +
-        '<path d="M48,6 L57,10 L48,14 Z" fill="#333"/></svg>';
-    dashed = '<svg width="60" height="20"><line x1="2" y1="10" x2="48" y2="10" stroke="#333" stroke-width="1.5" ' +
-        'stroke-dasharray="5,4"/><path d="M48,6 L57,10 L48,14 Z" fill="#333"/></svg>';
-    scheduled = `<svg width="60" height="20"><line x1="2" y1="10" x2="48" y2="10" stroke="${CRON_BORDER}" stroke-width="1.5"/>` +
-        `<path d="M48,6 L57,10 L48,14 Z" fill="${CRON_BORDER}"/></svg>`;
-}
-/**
- * The legend. Three columns — what a box IS, what a line MEANS, how to read a box — replacing the
- * three paragraphs of prose that used to restate the picture in words. Styled after
- * {@link GraphVisualizer}'s legend so the two graphs in this repo look like one tool.
- */
-// webpieces-disable no-function-outside-class -- HTML builder, matching the sibling builders in this file
-function legendHtml() {
-    const sw = new LegendSwatches();
-    const item = (swatch, text) => `<div class="legend-item"><span class="sw">${swatch}</span><span>${text}</span></div>`;
-    return `<div class="legend">
-        <h2>Legend</h2>
-        <div class="legend-columns">
-            <div class="legend-col">
-                <h3>Node shapes &mdash; <em>what a box is</em></h3>
-                ${item(sw.service, '<strong>service</strong> &mdash; a deployable in this repo; fill is its dependency level')}
-                ${item(sw.queue, '<strong>queue</strong> &mdash; one box <em>per method</em>, the unit Cloud Tasks and Terraform actually create')}
-                ${item(sw.database, '<strong>database</strong> &mdash; a datastore outside this repo')}
-                ${item(sw.storage, '<strong>object storage</strong> &mdash; a bucket outside this repo')}
-                ${item(sw.external, '<strong>external system</strong> &mdash; outside this repo; nothing here implements it. Pointing <strong>OUT</strong> = a system this repo calls (firestore, gmail). Pointing <strong>IN</strong> = an endpoint driven from outside (a Pub/Sub push, a Gmail or Twilio webhook).')}
-                ${item(sw.cron, '<strong>cron</strong> &mdash; a scheduler fires this endpoint')}
-            </div>
-            <div class="legend-col">
-                <h3>Lines &mdash; <em>what a call is</em></h3>
-                ${item(sw.solid, '<strong>solid = rpc</strong> &mdash; the request follows the arrow, the response flows back')}
-                ${item(sw.dashed, '<strong>dashed = event</strong> &mdash; asynchronous: the event flows in the direction of the arrow and returns once it is in the queue')}
-                ${item(sw.scheduled, '<strong>scheduled</strong> &mdash; a cron invocation')}
-                <div class="legend-note"><em>Every line is labeled with the contract the call flows over. A service that enqueues to itself loops through its own queue &mdash; a queue decouples the two sides, so it is not a dependency cycle.</em></div>
-            </div>
-            <div class="legend-col">
-                <h3>Reading a box</h3>
-                <pre class="legend-box-anatomy">name
-(server|client, L#)
-implements: &lt;contracts it serves&gt;
-</pre>
-                <div class="legend-note">A box lists only what it <strong>serves</strong>. What it <em>calls</em> is on its outgoing arrows.</div>
-                <div class="legend-note"><code>(via &lt;lib&gt;)</code> = served through an embedded library, not its own source.</div>
-            </div>
-        </div>
-    </div>`;
-}
 function generateRuntimeHtml(dot, title) {
     // The browser half lives in a plain .js asset (matching graph-visualizer.client.js) rather than
     // in a template literal here: it renders with @viz-js/viz v3 AND redraws every queue node as a
@@ -494,7 +526,7 @@ function generateRuntimeHtml(dot, title) {
 <body>
     <h1>${title}</h1>
     <div id="graph"></div>
-    ${legendHtml()}
+    ${(0, runtime_viz_theme_1.legendHtml)()}
     <script>${script}</script>
 </body>
 </html>`;