@stocksharp/diagram 1.3.0 → 1.5.0

package/README.md

@@ -177,6 +177,89 @@ option and `setFullscreenLabels()` on `StockSharpDiagram`. With neither the
 attribute nor the option, the wording comes from the bundle, so a page that has
 already been translated needs no per-diagram markup at all.
 
+Two more attributes change what a host is rather than what it says:
+`data-diagram-kind="document"` marks a generic diagram document (see
+*Architecture diagrams* below), and `data-diagram-export="off"` removes the
+download button and the export entries for that one diagram, the same as the
+`allowExport: false` option.
+
+### Architecture diagrams: generic documents
+
+The same engine draws pictures that are not strategies - a system architecture,
+a data flow, a deployment - from a generic diagram document. Such a document
+names its own nodes, colours and zones, so it needs no palette:
+
+```ts
+import { createDiagramDocument, renderDocument } from '@stocksharp/diagram';
+
+const drawing = createDiagramDocument({
+  nodes: [
+    {
+      id: 'gate', name: 'Gateway', subtitle: 'FIX / REST / WebSocket',
+      description: 'Shown as the hover tooltip',
+      color: 'var(--ss-red, #c0392b)', border: 'var(--ss-red-dark, #7a1f16)',
+      x: 0, y: 0, outPorts: [{ id: 'out', name: 'Orders' }],
+    },
+    { id: 'core', name: 'Matching engine', x: 420, y: 0, inPorts: [{ id: 'in', name: 'Orders' }] },
+  ],
+  links: [{
+    from: { nodeId: 'gate', portId: 'out' },
+    to: { nodeId: 'core', portId: 'in' },
+    label: 'SBE',          // short text at the middle of the routed wire
+    style: 'dashed',       // 'solid' (default) or 'dashed'
+  }],
+  zones: [{ id: 'colo', name: 'Colocation', x: -60, y: -60, width: 760, height: 200, color: 'var(--ss-gold)' }],
+});
+
+const handle = renderDocument(document.querySelector<HTMLElement>('#architecture')!, drawing);
+```
+
+- `subtitle` is an optional second line under the node name, smaller and
+  muted; the node grows to fit it. `label` is an optional short text drawn on a
+  plate of the canvas colour at the middle of the link. Both are left out of a
+  saved document when empty, so documents written before them keep their shape.
+- Zones count as content: `zoomToFit()` and `takeScreenshot` / `takeSvg` with
+  `scope: 'content'` frame every zone and its caption, not only the nodes.
+- Node `color` / `border` and zone `color` may name a page token -
+  `var(--ss-red)`, with or without a fallback. It is resolved against the element
+  the diagram is mounted in on every repaint, so the picture follows the page's
+  theme; the saved document keeps the reference, and an SVG export carries the
+  resolved colour. A token that is unset and has no fallback gets the default
+  node, border or zone colour.
+
+`renderDocument(div, document, options)` mounts a read-only viewer: no minimap,
+no link validation, the canvas and grid colours read from `--diagram-bg` /
+`--diagram-grid` on the page (repainted when `data-theme` changes on `<html>`,
+which also re-reads every token colour), and a `ResizeObserver` that keeps the
+drawing fitted. It accepts a saved document or one written by hand, leaving out
+whatever has a default, and throws `DiagramDocumentError` for anything else. It
+takes the same `onFullscreenRequested`, `onExportRequested` and `onDestroyed`
+hooks as `renderScheme`, plus:
+
+- `pageScroll` - on by default for a document: a plain wheel scrolls the page and
+  only Ctrl/Meta+wheel (and a trackpad pinch) zooms; on touch screens a
+  one-finger vertical swipe scrolls the page (`touch-action: pan-y`), while a
+  horizontal drag pans the diagram and a two-finger pinch zooms it. Pass `false`
+  to keep every gesture in the diagram. `StockSharpDiagram` has the same switch
+  as the `pageScroll` option and `setPageScroll()`; it is off there by default.
+- `allowExport: false` - no download button and no export entries in the menu,
+  even when `onExportRequested` is passed (`StockSharpDiagram.setExportEnabled()`
+  underneath).
+
+Pages that use `renderAll()` mark such a host with `data-diagram-kind="document"`
+and give it the document inline or through `data-diagram-src`. A host without
+the attribute is still recognised when its JSON has a numeric `version` and a
+`nodes` array at the root, which a saved strategy never has; strategy hosts are
+drawn exactly as before.
+
+```html
+<div class="ss-diagram-host" data-diagram-kind="document" data-diagram-export="off">
+  <script type="application/json">
+    { "nodes": [{ "id": "a", "name": "Client", "subtitle": "FIX" }], "links": [] }
+  </script>
+</div>
+```
+
 ### Node actions and errors
 
 Double-click handling is opt-in. Give only the node types controlled by the
@@ -354,7 +437,7 @@ The component has one document model and a separate rendering layer:
 | Document core | `src/core/*` | Versioned document serialization plus independent runtime, view and selection state |
 | Public component API | `src/diagram/stocksharp-diagram.ts` | `StockSharpDiagram`: catalog-aware nodes, ports, validation, events, persistence, history and theming |
 | Models and palette | `src/diagram/{types,catalog,palette}.ts` | Public data model and draggable HTML element palette |
-| Web embed | `src/embed.ts` | Self-contained read-only rendering for web applications |
+| Web embed | `src/embed.ts` | Self-contained read-only rendering of strategy schemes and generic documents for web applications |
 | Canvas renderer | `src/canvas-renderer.ts` | Internal drawing, routing, selection, editing, zoom, touch and overview |
 
 Applications use `StockSharpDiagram` or the read-only embed. The renderer is

package/dist/esm/canvas-renderer.js

@@ -1,5 +1,5 @@
 import { SvgSurface } from './svg-surface.js';
-import { readableOutlineOn, readableTextOn } from './color.js';
+import { cappedLightness, legibleOn, readableOutlineOn, readableTextOn, resolveCssVariables } from './color.js';
 // Internal dependency-free canvas renderer used by StockSharpDiagram.
 //
 // Dependency-free, pure 2D canvas. Demonstrates the hard parts: typed
@@ -104,6 +104,7 @@ export class NodeModel {
         this.id = id;
         this.typeId = init.typeId ?? id;
         this.name = init.name;
+        this.subtitle = init.subtitle ?? '';
         this.description = init.description ?? '';
         this.groupName = init.groupName ?? 'Common';
         this.color = init.color ?? '#d7d7d7';
@@ -129,6 +130,7 @@ export class NodeModel {
             id: this.id,
             typeId: this.typeId,
             name: this.name,
+            ...(this.subtitle === '' ? {} : { subtitle: this.subtitle }),
             description: this.description,
             groupName: this.groupName,
             color: this.color,
@@ -151,12 +153,13 @@ export class NodeModel {
     }
 }
 export class LinkModel {
-    constructor(from, fromPort, to, toPort, id = '', metadata, style = 'solid') {
+    constructor(from, fromPort, to, toPort, id = '', metadata, style = 'solid', label = '') {
         this.from = from;
         this.fromPort = fromPort;
         this.to = to;
         this.toPort = toPort;
         this.style = style;
+        this.label = label;
         this.id = id;
         this.metadata = copyJsonObject(metadata);
     }
@@ -169,6 +172,7 @@ export class LinkModel {
             to: this.to,
             toPort: this.toPort,
             style: this.style,
+            ...(this.label === '' ? {} : { label: this.label }),
             metadata: copyJsonObject(this.metadata),
         };
     }
@@ -189,6 +193,15 @@ const INTRO_MS = 520; // entrance animation duration
 const INTRO_RISE = 70; // px the scheme rises from below
 const ERROR_FLASH_MS = 1100;
 const ERROR_RED = '#f6465d';
+const DEFAULT_NODE_COLOR = '#d7d7d7';
+const DEFAULT_NODE_BORDER = '#8c8c8c';
+const DEFAULT_ZONE_TINT = '#8a8f98';
+const TITLE_FONT = '600 12px Segoe UI, Tahoma, sans-serif';
+const SUBTITLE_FONT = '11px Segoe UI, Tahoma, sans-serif';
+const SUBTITLE_MIN_H = 62; // body height that fits a name and a subtitle line
+const LINK_LABEL_FONT = '600 10px Segoe UI, Tahoma, sans-serif';
+const ZONE_CAPTION_TOP = 9; // caption offset inside the zone's top-left corner
+const ZONE_CAPTION_H = 14;
 const ERROR_BACKGROUND = '#7d2632';
 const clamp = (v, lo, hi) => Math.min(hi, Math.max(lo, v));
 function hashHue(s) {
@@ -202,10 +215,7 @@ function hashHue(s) {
 // wash out; a light theme passes a low ceiling to darken the links just enough to stay readable
 // while keeping each hue distinct. Non-hsl inputs are returned untouched.
 function clampLightness(color, maxL) {
-    const m = color.match(/^hsl\(\s*([\d.]+)\s*,\s*([\d.]+)%\s*,\s*([\d.]+)%\s*\)$/i);
-    if (m === null)
-        return color;
-    return `hsl(${m[1]}, ${m[2]}%, ${Math.min(+m[3], maxL * 100)}%)`;
+    return cappedLightness(color, maxL);
 }
 function colorLuminance(color) {
     if (color === undefined)
@@ -293,6 +303,9 @@ export class Diagram {
         this.ovGeo = null;
         this.validator = null;
         this.handlers = new Map();
+        // Computed style of the host, read at most once per frame: colours written as var(--token)
+        // resolve against it, so a frame drawn after a theme switch picks up the new values.
+        this.hostStyle = null;
         this.opts = opts;
         // Same normalization setTypeColors applies, so a palette handed in at construction is
         // keyed like one handed in later.
@@ -300,6 +313,7 @@ export class Diagram {
             this.setTypeColorsInternal(opts.typeColors);
         this.host = opts.host;
         this.gridSnapEnabled = opts.gridSnap ?? false;
+        this.pageScroll = opts.pageScroll ?? false;
         this.gridSize = this.normalizeGridSize(opts.gridSize ?? DEFAULT_GRID_SIZE);
         this.history = new DiagramCommandHistory(() => {
             // The gated values, not the raw stack: setInteractionPermissions and setReadOnly
@@ -311,9 +325,9 @@ export class Diagram {
         this.canvas.style.display = 'block';
         this.canvas.tabIndex = 0; // focusable → key events
         this.canvas.style.outline = 'none';
-        // Eat browser-native touch gestures (page scroll / pinch-zoom) so
-        // fingers actually drive our pan/zoom on mobile instead of the page.
-        this.canvas.style.touchAction = 'none';
+        // Eat browser-native touch gestures (page scroll / pinch-zoom) so fingers actually drive our
+        // pan/zoom on mobile instead of the page - unless the page asked to keep its scrolling.
+        this.applyTouchAction();
         // No OS text-selection on long-press (would pop the iOS magnifier
         // and select node/link captions instead of firing our menu).
         this.canvas.style.userSelect = 'none';
@@ -371,6 +385,17 @@ export class Diagram {
         this.gridSize = nextSize;
         this.scheduleDraw();
     }
+    /** See DiagramOptions.pageScroll. */
+    setPageScroll(enabled) {
+        this.pageScroll = enabled;
+        this.applyTouchAction();
+    }
+    isPageScrollEnabled() { return this.pageScroll; }
+    // pan-y hands a vertical swipe to the browser, which scrolls the page; a horizontal one and a
+    // two-finger pinch still reach the canvas.
+    applyTouchAction() {
+        this.canvas.style.touchAction = this.pageScroll ? 'pan-y' : 'none';
+    }
     getGridSnap() {
         return { enabled: this.gridSnapEnabled, size: this.gridSize };
     }
@@ -604,7 +629,7 @@ export class Diagram {
             if (!validation.allowed)
                 return false;
         }
-        const link = new LinkModel(init.from, init.fromPort, init.to, init.toPort, init.id ?? this.nextLinkId(), init.metadata, init.style ?? 'solid');
+        const link = new LinkModel(init.from, init.fromPort, init.to, init.toPort, init.id ?? this.nextLinkId(), init.metadata, init.style ?? 'solid', init.label ?? '');
         if (this.links.some((l) => l.id === link.id))
             return false;
         this.links.splice(clamp(Math.trunc(index), 0, this.links.length), 0, link);
@@ -924,6 +949,8 @@ export class Diagram {
         return this.updateNodeState(nodeId, 'update node', (node) => {
             if (patch.name !== undefined)
                 node.name = patch.name;
+            if (patch.subtitle !== undefined)
+                node.subtitle = patch.subtitle;
             if (patch.description !== undefined)
                 node.description = patch.description;
             if (patch.color !== undefined)
@@ -976,6 +1003,7 @@ export class Diagram {
         const restored = new NodeModel(snapshot, nodeId);
         node.typeId = restored.typeId;
         node.name = restored.name;
+        node.subtitle = restored.subtitle;
         node.description = restored.description;
         node.groupName = restored.groupName;
         node.color = restored.color;
@@ -1009,6 +1037,10 @@ export class Diagram {
         return true;
     }
     load(nodes, links) {
+        this.loadModel(nodes, links, []);
+    }
+    // Zones are placed before the view is fitted, so the first frame frames them too.
+    loadModel(nodes, links, zones) {
         this.clear();
         this.idSeq = 1;
         this.linkSeq = 1;
@@ -1046,10 +1078,11 @@ export class Diagram {
             if (this.links.some((existing) => existing.id === id)) {
                 throw new Error(`ssdiagram: duplicate link id "${id}"`);
             }
-            const model = new LinkModel(link.from, link.fromPort, link.to, link.toPort, id, link.metadata, link.style ?? 'solid');
+            const model = new LinkModel(link.from, link.fromPort, link.to, link.toPort, id, link.metadata, link.style ?? 'solid', link.label ?? '');
             if (!this.links.some((existing) => existing.key() === model.key()))
                 this.links.push(model);
         }
+        this.zones = zones.map((zone) => ({ ...zone, metadata: copyJsonObject(zone.metadata) }));
         for (const node of this.nodes) {
             if (node.loadError.length === 0)
                 continue;
@@ -1074,22 +1107,23 @@ export class Diagram {
                 to: l.to,
                 toPort: l.toPort,
                 style: l.style,
+                ...(l.label === '' ? {} : { label: l.label }),
                 metadata: copyJsonObject(l.metadata),
             })),
         };
     }
     loadDocument(source) {
         const document = parseDiagramDocument(source);
-        this.load(document.nodes, document.links.map((link) => ({
+        this.loadModel(document.nodes, document.links.map((link) => ({
             id: link.id,
             from: link.from.nodeId,
             fromPort: link.from.portId,
             to: link.to.nodeId,
             toPort: link.to.portId,
             style: link.style,
+            label: link.label,
             metadata: link.metadata,
-        })));
-        this.zones = document.zones.map((zone) => ({ ...zone, metadata: copyJsonObject(zone.metadata) }));
+        })), document.zones);
         this.documentMetadata = copyJsonObject(document.metadata);
     }
     saveDocument() {
@@ -1100,6 +1134,7 @@ export class Diagram {
                 from: { nodeId: link.from, portId: link.fromPort },
                 to: { nodeId: link.to, portId: link.toPort },
                 style: link.style,
+                label: link.label,
                 metadata: link.metadata,
             })),
             zones: this.zones.map((zone) => ({ ...zone, metadata: copyJsonObject(zone.metadata) })),
@@ -1574,8 +1609,10 @@ export class Diagram {
             this.opts.overviewViewportFill = t.overviewViewportFill;
         this.scheduleDraw();
     }
+    // Zones count: fitting or exporting only the nodes cut off the places they sit in, captions
+    // included. A caption that is taller than its zone still has to fit.
     graphBounds() {
-        if (this.nodes.length === 0)
+        if (this.nodes.length === 0 && this.zones.length === 0)
             return null;
         let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
         for (const n of this.nodes) {
@@ -1584,6 +1621,15 @@ export class Diagram {
             maxX = Math.max(maxX, n.x + n.w);
             maxY = Math.max(maxY, n.y + n.h);
         }
+        for (const zone of this.zones) {
+            const bottom = zone.name.length > 0
+                ? Math.max(zone.height, ZONE_CAPTION_TOP + ZONE_CAPTION_H)
+                : zone.height;
+            minX = Math.min(minX, zone.x - 1);
+            minY = Math.min(minY, zone.y - 1);
+            maxX = Math.max(maxX, zone.x + zone.width + 1);
+            maxY = Math.max(maxY, zone.y + bottom + 1);
+        }
         return { minX, minY, maxX, maxY };
     }
     resize(w, h) {
@@ -1640,12 +1686,17 @@ export class Diagram {
     // ---- geometry ---------------------------------------------------
     layoutNode(n) {
         const ctx = this.ctx;
-        ctx.font = '600 12px Segoe UI, Tahoma, sans-serif';
+        ctx.font = TITLE_FONT;
         const titleW = ctx.measureText(n.name).width;
+        let subtitleW = 0;
+        if (n.subtitle.length > 0) {
+            ctx.font = SUBTITLE_FONT;
+            subtitleW = ctx.measureText(n.subtitle).width;
+        }
         const rows = Math.max(n.inPorts.length, n.outPorts.length, 1);
-        // Node sizing: min 170 wide, height grows by rows.
-        n.w = Math.max(170, Math.ceil(titleW) + 28);
-        n.h = Math.max(48, rows * PORT_ROW_H + 16);
+        // Node sizing: min 170 wide, height grows by rows; a subtitle adds a second text line.
+        n.w = Math.max(170, Math.ceil(titleW) + 28, Math.ceil(subtitleW) + 28);
+        n.h = Math.max(n.subtitle.length > 0 ? SUBTITLE_MIN_H : 48, rows * PORT_ROW_H + 16);
         // Each side's port stack is vertically centred; the socket
         // square sits OUTSIDE the body (its inner edge flush with the
         // node border).
@@ -1691,6 +1742,15 @@ export class Diagram {
             return p.type;
         return this.portFeed.get(p) ?? p.type;
     }
+    /// A type's colour as a wire.
+    ///
+    /// The same colour a socket of that type is filled with, moved into the band the canvas
+    /// leaves room for. A socket can afford the host's exact colour because it is a filled
+    /// square with an outline; a wire is a thin line with nothing behind it, and one drawn in
+    /// #000000 on a dark canvas is not there at all.
+    linkColor(type) {
+        return legibleOn(this.portColor(type), this.opts.background ?? '#1b1b1f');
+    }
     portColor(type) {
         const maxL = this.opts.linkMaxLightness;
         const light = maxL !== undefined && maxL < 0.5;
@@ -2032,6 +2092,7 @@ export class Diagram {
                         // The clipboard is built from saveDocument(), so it carries the style;
                         // rebuilding without it silently turned every pasted dashed link solid.
                         style: l.style,
+                        label: l.label,
                         metadata: l.metadata,
                     });
             }
@@ -2500,6 +2561,9 @@ export class Diagram {
         this.listen(window, 'pointerup', finish);
         this.listen(window, 'pointercancel', finish);
         this.listen(this.canvas, 'wheel', (e) => {
+            // Ctrl+wheel is also what a trackpad pinch arrives as, so zoom stays one gesture away.
+            if (this.pageScroll && !e.ctrlKey && !e.metaKey)
+                return;
             e.preventDefault();
             const [sx, sy] = localXY(e);
             const [wx, wy] = this.toWorld(sx, sy);
@@ -2672,6 +2736,7 @@ export class Diagram {
     }
     draw(options = SCREEN_RENDER_OPTIONS) {
         const ctx = this.ctx;
+        this.hostStyle = null;
         ctx.clearRect(0, 0, this.width, this.height);
         const background = this.opts.background ?? '#1b1b1f';
         ctx.fillStyle = background;
@@ -2702,6 +2767,7 @@ export class Diagram {
         // Links next. Each link jumps over the verticals of the links
         // drawn before it (deterministic bridge — Link.JumpOver parity).
         const prior = []; // segments of links already drawn
+        const labels = [];
         const hoveredNode = this.hoverPort?.node ?? this.hoverNode;
         for (const l of this.links) {
             const a = this.endpoint(l, 'from');
@@ -2710,7 +2776,7 @@ export class Diagram {
                 continue;
             const fp = this.nodes.find((n) => n.id === l.from)?.outPorts.find((p) => p.id === l.fromPort);
             const baseColor = (this.opts.typedLinkColors ?? false) && fp !== undefined
-                ? this.portColor(fp.type)
+                ? this.linkColor(fp.type)
                 : this.portColor('');
             const state = options.selection && l === this.selectedLink
                 ? 'sel'
@@ -2723,6 +2789,8 @@ export class Diagram {
             const pts = this.routeLink(a, b, new Set([l.from, l.to]));
             this.strokeRoute(pts, color, width, prior, l.style);
             this.drawArrow(pts, color);
+            if (l.label.length > 0)
+                labels.push({ pts, text: l.label, color });
             for (let k = 1; k < pts.length; k += 1) {
                 const [x1, y1] = pts[k - 1];
                 const [x2, y2] = pts[k];
@@ -2732,6 +2800,9 @@ export class Diagram {
                     prior.push({ h: true, c: y1, a: Math.min(x1, x2), b: Math.max(x1, x2) });
             }
         }
+        // After every wire, so no later wire runs across a label; before the nodes, which stay on top.
+        for (const label of labels)
+            this.drawLinkLabel(label.pts, label.text, label.color, background);
         if (options.transient && (this.linking !== null || this.relinking !== null))
             this.drawPendingLink();
         this.portFeed = this.feedTypes();
@@ -2899,8 +2970,9 @@ export class Diagram {
         if (this.zones.length === 0)
             return;
         const ctx = this.ctx;
+        const defaultTint = this.resolveColor(this.opts.zoneColor ?? DEFAULT_ZONE_TINT, DEFAULT_ZONE_TINT);
         for (const zone of this.zones) {
-            const tint = zone.color.length > 0 ? zone.color : (this.opts.zoneColor ?? '#8a8f98');
+            const tint = zone.color.length > 0 ? this.resolveColor(zone.color, defaultTint) : defaultTint;
             ctx.save();
             roundRect(ctx, zone.x, zone.y, zone.width, zone.height, 10);
             ctx.globalAlpha = 0.12;
@@ -2917,12 +2989,12 @@ export class Diagram {
             ctx.save();
             ctx.globalAlpha = 0.75;
             ctx.fillStyle = tint;
-            ctx.font = '600 12px Segoe UI, Tahoma, sans-serif';
+            ctx.font = TITLE_FONT;
             ctx.textAlign = 'left';
             ctx.textBaseline = 'top';
             // Inside the top-left corner: a caption outside the box would collide with whatever
             // sits above it, and the corner is the one spot a rectangle always has to spare.
-            ctx.fillText(zone.name, zone.x + 12, zone.y + 9, Math.max(0, zone.width - 24));
+            ctx.fillText(zone.name, zone.x + 12, zone.y + ZONE_CAPTION_TOP, Math.max(0, zone.width - 24));
             ctx.restore();
         }
     }
@@ -2965,11 +3037,12 @@ export class Diagram {
         const runtime = options.runtime ? getJsonKey(this.runtimeState.nodes, n.id) : undefined;
         const active = options.runtime
             && (this.runtimeState.activeNodeId === n.id || runtime?.active === true);
+        const fill = this.resolveColor(n.color, DEFAULT_NODE_COLOR);
         roundRect(ctx, n.x, n.y, n.w, n.h, 6);
-        ctx.fillStyle = hasLoadError ? ERROR_BACKGROUND : active ? '#ffd1dc' : n.color;
+        ctx.fillStyle = hasLoadError ? ERROR_BACKGROUND : active ? '#ffd1dc' : fill;
         ctx.fill();
         ctx.lineWidth = selected ? 2 : 1.5;
-        ctx.strokeStyle = selected ? this.selectionColor() : n.border;
+        ctx.strokeStyle = selected ? this.selectionColor() : this.resolveColor(n.border, DEFAULT_NODE_BORDER);
         ctx.stroke();
         if (hasLoadError || hasRuntimeError) {
             let alpha = 1;
@@ -3007,13 +3080,26 @@ export class Diagram {
         // takes its colour from the fill it sits on: that fill comes from the
         // scheme, so a node may well be darker than the title used to assume.
         const titleShift = n.icon ? iconW + 4 : 0;
+        const textX = n.x + titleShift + (n.w - titleShift) / 2;
+        const textWidth = n.w - titleShift - 14;
         ctx.fillStyle = hasLoadError
             ? '#ffffff'
-            : readableTextOn(active ? '#ffd1dc' : n.color);
-        ctx.font = '600 12px Segoe UI, Tahoma, sans-serif';
+            : readableTextOn(active ? '#ffd1dc' : fill);
+        ctx.font = TITLE_FONT;
         ctx.textAlign = 'center';
         ctx.textBaseline = 'middle';
-        ctx.fillText(n.name, n.x + titleShift + (n.w - titleShift) / 2, n.y + n.h / 2, n.w - titleShift - 14);
+        if (n.subtitle.length === 0) {
+            ctx.fillText(n.name, textX, n.y + n.h / 2, textWidth);
+        }
+        else {
+            // Two lines centred as a pair: the name above, the subtitle smaller and muted below.
+            ctx.fillText(n.name, textX, n.y + n.h / 2 - 8, textWidth);
+            ctx.save();
+            ctx.globalAlpha *= 0.72;
+            ctx.font = SUBTITLE_FONT;
+            ctx.fillText(n.subtitle, textX, n.y + n.h / 2 + 9, textWidth);
+            ctx.restore();
+        }
         for (const p of n.inPorts)
             this.drawPort(n, p, options);
         for (const p of n.outPorts)
@@ -3157,6 +3243,48 @@ export class Diagram {
         ctx.fill();
         ctx.restore();
     }
+    // A plate of the canvas colour under the text, edged in the wire's colour: the label reads the same
+    // whatever the wire crosses, and still says which wire it belongs to.
+    drawLinkLabel(pts, text, color, background) {
+        const [x, y] = pathMidpoint(pts);
+        const ctx = this.ctx;
+        ctx.save();
+        ctx.font = LINK_LABEL_FONT;
+        const w = Math.ceil(ctx.measureText(text).width) + 12;
+        const h = 16;
+        roundRect(ctx, x - w / 2, y - h / 2, w, h, h / 2);
+        ctx.fillStyle = background;
+        ctx.fill();
+        ctx.lineWidth = 1;
+        ctx.strokeStyle = color;
+        ctx.stroke();
+        ctx.fillStyle = readableTextOn(background);
+        ctx.textAlign = 'center';
+        ctx.textBaseline = 'middle';
+        ctx.fillText(text, x, y);
+        ctx.restore();
+    }
+    // Scheme colours may name a custom property of the page, var(--token), which a canvas cannot
+    // paint. They resolve against the host element; one that resolves to nothing and has no
+    // fallback of its own gets the renderer's default for that slot.
+    resolveColor(value, fallback) {
+        if (!value.includes('var('))
+            return value;
+        return resolveCssVariables(value, (name) => this.hostProperty(name)) ?? fallback;
+    }
+    hostProperty(name) {
+        if (this.hostStyle === null) {
+            if (typeof getComputedStyle !== 'function')
+                return '';
+            try {
+                this.hostStyle = getComputedStyle(this.host);
+            }
+            catch {
+                return '';
+            }
+        }
+        return this.hostStyle.getPropertyValue(name);
+    }
     drawSelectedLinkEndpoints() {
         if (this.selectedLink === null)
             return;
@@ -3225,7 +3353,7 @@ export class Diagram {
         if (snapped !== null)
             excludedNodes.add(snapped.node.id);
         const points = this.routeLink(a, b, excludedNodes);
-        ctx.strokeStyle = this.portColor(colorType);
+        ctx.strokeStyle = this.linkColor(colorType);
         if (snapped !== null) {
             ctx.setLineDash([]);
             ctx.lineWidth = 2.6;
@@ -3290,9 +3418,9 @@ export class Diagram {
         ctx.stroke();
         ctx.clip();
         for (const n of this.nodes) {
-            ctx.fillStyle = n.color;
+            ctx.fillStyle = this.resolveColor(n.color, DEFAULT_NODE_COLOR);
             ctx.fillRect(mx(n.x), my(n.y), Math.max(2, n.w * s), Math.max(2, n.h * s));
-            ctx.strokeStyle = n.border;
+            ctx.strokeStyle = this.resolveColor(n.border, DEFAULT_NODE_BORDER);
             ctx.lineWidth = 1;
             ctx.strokeRect(mx(n.x), my(n.y), Math.max(2, n.w * s), Math.max(2, n.h * s));
         }
@@ -3340,6 +3468,25 @@ function roundRect(ctx, x, y, w, h, r) {
 // a 3-segment mid-X elbow. Backward/too-close: a 5-segment detour that
 // leaves the source rightward and re-enters the target from the left
 // (AvoidsNodes-style, never a diagonal).
+/** The point halfway along a polyline, measured by length rather than by vertex count. */
+function pathMidpoint(pts) {
+    let total = 0;
+    for (let i = 1; i < pts.length; i += 1)
+        total += Math.hypot(pts[i][0] - pts[i - 1][0], pts[i][1] - pts[i - 1][1]);
+    let remaining = total / 2;
+    for (let i = 1; i < pts.length; i += 1) {
+        const [x1, y1] = pts[i - 1];
+        const [x2, y2] = pts[i];
+        const length = Math.hypot(x2 - x1, y2 - y1);
+        if (length > 0 && remaining <= length) {
+            const t = remaining / length;
+            return [x1 + (x2 - x1) * t, y1 + (y2 - y1) * t];
+        }
+        remaining -= length;
+    }
+    const last = pts[pts.length - 1];
+    return [last[0], last[1]];
+}
 function route(a, b) {
     const [ax, ay] = a;
     const [bx, by] = b;