@stocksharp/diagram 1.3.0 → 1.5.0

package/dist/ssdiagram.js

@@ -53,6 +53,7 @@ var SSDiagram = (() => {
     parseDiagramViewState: () => parseDiagramViewState,
     renderAll: () => renderAll,
     renderDiagramSvg: () => renderDiagramSvg,
+    renderDocument: () => renderDocument,
     renderFromInline: () => renderFromInline,
     renderFromSource: () => renderFromSource,
     renderScheme: () => renderScheme,
@@ -162,10 +163,12 @@ var SSDiagram = (() => {
   function normalizeNode(value, path) {
     const input = requireStructure(value, path);
     const id = requireIdentifier(input.id, `${path}.id`);
+    const subtitle = requireOptionalText(input.subtitle, `${path}.subtitle`);
     return {
       id,
       typeId: requireIdentifier(input.typeId ?? id, `${path}.typeId`),
       name: requireString(input.name, `${path}.name`),
+      ...subtitle === "" ? {} : { subtitle },
       description: requireString(input.description ?? "", `${path}.description`),
       groupName: requireString(input.groupName ?? "Common", `${path}.groupName`),
       x: requireFiniteNumber(input.x ?? 0, `${path}.x`),
@@ -216,14 +219,19 @@ var SSDiagram = (() => {
   }
   function normalizeLink(value, path) {
     const input = requireStructure(value, path);
+    const label2 = requireOptionalText(input.label, `${path}.label`);
     return {
       id: requireIdentifier(input.id, `${path}.id`),
       from: normalizeEndpoint(input.from, `${path}.from`),
       to: normalizeEndpoint(input.to, `${path}.to`),
       style: requireLinkStyle(input.style, `${path}.style`),
+      ...label2 === "" ? {} : { label: label2 },
       metadata: cloneJsonObject(input.metadata ?? {}, `${path}.metadata`)
     };
   }
+  function requireOptionalText(value, path) {
+    return value === void 0 || value === null ? "" : requireString(value, path);
+  }
   function requireLinkStyle(value, path) {
     if (value === void 0 || value === null) return "solid";
     if (value !== "solid" && value !== "dashed") {
@@ -263,6 +271,7 @@ var SSDiagram = (() => {
       id: requireString(node.id, `${path}.id`),
       typeId: requireString(node.typeId, `${path}.typeId`),
       name: requireString(node.name, `${path}.name`),
+      subtitle: node.subtitle,
       description: requireString(node.description, `${path}.description`),
       groupName: requireString(node.groupName, `${path}.groupName`),
       x: requireNumber(node.x, `${path}.x`),
@@ -318,6 +327,7 @@ var SSDiagram = (() => {
       from: parseEndpoint(link.from, `${path}.from`),
       to: parseEndpoint(link.to, `${path}.to`),
       style: link.style === void 0 ? void 0 : requireLinkStyle(link.style, `${path}.style`),
+      label: link.label,
       metadata: cloneJsonObject(link.metadata, `${path}.metadata`)
     }, path);
   }
@@ -873,6 +883,82 @@ var SSDiagram = (() => {
       return DARK_OUTLINE;
     return contrast(background, relativeLuminance(LIGHT_OUTLINE)) > contrast(background, relativeLuminance(DARK_OUTLINE)) ? LIGHT_OUTLINE : DARK_OUTLINE;
   }
+  function toHsl(color) {
+    const hsl = color.trim().match(/^hsl\(\s*([\d.]+)\s*,\s*([\d.]+)%\s*,\s*([\d.]+)%\s*\)$/i);
+    if (hsl !== null)
+      return [+hsl[1], +hsl[2] / 100, +hsl[3] / 100];
+    const rgb = parseRgb(color);
+    if (rgb === null)
+      return null;
+    const [r, g, b] = rgb.map((channel) => channel / 255);
+    const max = Math.max(r, g, b);
+    const min = Math.min(r, g, b);
+    const lightness = (max + min) / 2;
+    if (max === min)
+      return [0, 0, lightness];
+    const span = max - min;
+    const saturation = lightness > 0.5 ? span / (2 - max - min) : span / (max + min);
+    const hue = max === r ? (g - b) / span + (g < b ? 6 : 0) : max === g ? (b - r) / span + 2 : (r - g) / span + 4;
+    return [hue * 60, saturation, lightness];
+  }
+  var DARK_CANVAS_FLOOR = 0.42;
+  var LIGHT_CANVAS_CEILING = 0.45;
+  function legibleOn(color, background) {
+    const hsl = toHsl(color);
+    if (hsl === null)
+      return color;
+    const canvas = relativeLuminance(background);
+    const [hue, saturation, lightness] = hsl;
+    const moved = canvas < 0 ? lightness : canvas > 0.18 ? Math.min(lightness, LIGHT_CANVAS_CEILING) : Math.max(lightness, DARK_CANVAS_FLOOR);
+    if (moved === lightness && /^hsl/i.test(color.trim()))
+      return color;
+    return `hsl(${Math.round(hue * 10) / 10}, ${Math.round(saturation * 1e3) / 10}%, ${Math.round(moved * 1e3) / 10}%)`;
+  }
+  function cappedLightness(color, maxLightness) {
+    const hsl = toHsl(color);
+    if (hsl === null)
+      return color;
+    const [hue, saturation, lightness] = hsl;
+    if (lightness <= maxLightness)
+      return color;
+    return `hsl(${Math.round(hue * 10) / 10}, ${Math.round(saturation * 1e3) / 10}%, ${Math.round(maxLightness * 1e3) / 10}%)`;
+  }
+  function resolveCssVariables(value, lookup) {
+    return resolveAt(value, lookup, 0);
+  }
+  function resolveAt(value, lookup, depth) {
+    const start = value.indexOf("var(");
+    if (start < 0)
+      return value;
+    if (depth > 8)
+      return null;
+    let level = 0;
+    let end = -1;
+    for (let i = start + 3; i < value.length; i += 1) {
+      if (value[i] === "(")
+        level += 1;
+      else if (value[i] === ")" && --level === 0) {
+        end = i;
+        break;
+      }
+    }
+    if (end < 0)
+      return null;
+    const inner = value.slice(start + 4, end);
+    const comma = inner.indexOf(",");
+    const name = (comma < 0 ? inner : inner.slice(0, comma)).trim();
+    const fallback = comma < 0 ? "" : inner.slice(comma + 1).trim();
+    let replacement = name.startsWith("--") ? lookup(name).trim() : "";
+    if (replacement === "")
+      replacement = fallback;
+    if (replacement === "")
+      return null;
+    const resolved = resolveAt(replacement, lookup, depth + 1);
+    const rest = resolveAt(value.slice(end + 1), lookup, depth);
+    if (resolved === null || rest === null)
+      return null;
+    return value.slice(0, start) + resolved + rest;
+  }
 
   // src/core/history.ts
   var DiagramCommandHistory = class {
@@ -1162,6 +1248,7 @@ var SSDiagram = (() => {
       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";
@@ -1187,6 +1274,7 @@ var SSDiagram = (() => {
         id: this.id,
         typeId: this.typeId,
         name: this.name,
+        ...this.subtitle === "" ? {} : { subtitle: this.subtitle },
         description: this.description,
         groupName: this.groupName,
         color: this.color,
@@ -1208,12 +1296,13 @@ var SSDiagram = (() => {
     }
   };
   var LinkModel = class {
-    constructor(from, fromPort, to, toPort, id = "", metadata, style = "solid") {
+    constructor(from, fromPort, to, toPort, id = "", metadata, style = "solid", label2 = "") {
       this.from = from;
       this.fromPort = fromPort;
       this.to = to;
       this.toPort = toPort;
       this.style = style;
+      this.label = label2;
       this.id = id;
       this.metadata = copyJsonObject(metadata);
     }
@@ -1228,6 +1317,7 @@ var SSDiagram = (() => {
         to: this.to,
         toPort: this.toPort,
         style: this.style,
+        ...this.label === "" ? {} : { label: this.label },
         metadata: copyJsonObject(this.metadata)
       };
     }
@@ -1248,6 +1338,15 @@ var SSDiagram = (() => {
   var INTRO_RISE = 70;
   var ERROR_FLASH_MS = 1100;
   var ERROR_RED = "#f6465d";
+  var DEFAULT_NODE_COLOR = "#d7d7d7";
+  var DEFAULT_NODE_BORDER = "#8c8c8c";
+  var DEFAULT_ZONE_TINT = "#8a8f98";
+  var TITLE_FONT = "600 12px Segoe UI, Tahoma, sans-serif";
+  var SUBTITLE_FONT = "11px Segoe UI, Tahoma, sans-serif";
+  var SUBTITLE_MIN_H = 62;
+  var LINK_LABEL_FONT = "600 10px Segoe UI, Tahoma, sans-serif";
+  var ZONE_CAPTION_TOP = 9;
+  var ZONE_CAPTION_H = 14;
   var ERROR_BACKGROUND = "#7d2632";
   var clamp = (v, lo, hi) => Math.min(hi, Math.max(lo, v));
   function hashHue(s) {
@@ -1256,9 +1355,7 @@ var SSDiagram = (() => {
     return (h % 360 + 360) % 360;
   }
   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 === void 0) return 0;
@@ -1347,10 +1444,14 @@ var SSDiagram = (() => {
       this.ovGeo = null;
       this.validator = null;
       this.handlers = /* @__PURE__ */ 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;
       if (opts.typeColors !== void 0) 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(() => {
         this.emit("undoStackChanged", { canUndo: this.canUndo(), canRedo: this.canRedo() });
@@ -1359,7 +1460,7 @@ var SSDiagram = (() => {
       this.canvas.style.display = "block";
       this.canvas.tabIndex = 0;
       this.canvas.style.outline = "none";
-      this.canvas.style.touchAction = "none";
+      this.applyTouchAction();
       this.canvas.style.userSelect = "none";
       this.canvas.style.webkitUserSelect = "none";
       this.canvas.style.webkitTouchCallout = "none";
@@ -1413,6 +1514,19 @@ var SSDiagram = (() => {
       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 };
     }
@@ -1628,7 +1742,7 @@ var SSDiagram = (() => {
         this.emit("linkValidation", { fromNode: fn, from: fp, toNode: tn, to: tp, ...validation });
         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);
       this.emit("linkAdded", { link });
@@ -1900,6 +2014,7 @@ var SSDiagram = (() => {
     updateNode(nodeId, patch) {
       return this.updateNodeState(nodeId, "update node", (node) => {
         if (patch.name !== void 0) node.name = patch.name;
+        if (patch.subtitle !== void 0) node.subtitle = patch.subtitle;
         if (patch.description !== void 0) node.description = patch.description;
         if (patch.color !== void 0) node.color = patch.color;
         if (patch.border !== void 0) node.border = patch.border;
@@ -1945,6 +2060,7 @@ var SSDiagram = (() => {
       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;
@@ -1975,6 +2091,10 @@ var SSDiagram = (() => {
       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;
@@ -2001,9 +2121,10 @@ var SSDiagram = (() => {
         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;
         const state = createDiagramNodeRuntimeState();
@@ -2026,13 +2147,14 @@ var SSDiagram = (() => {
           to: l.to,
           toPort: l.toPort,
           style: l.style,
+          ...l.label === "" ? {} : { label: l.label },
           metadata: copyJsonObject(l.metadata)
         }))
       };
     }
     loadDocument(source) {
       const document2 = parseDiagramDocument(source);
-      this.load(
+      this.loadModel(
         document2.nodes,
         document2.links.map((link) => ({
           id: link.id,
@@ -2041,10 +2163,11 @@ var SSDiagram = (() => {
           to: link.to.nodeId,
           toPort: link.to.portId,
           style: link.style,
+          label: link.label,
           metadata: link.metadata
-        }))
+        })),
+        document2.zones
       );
-      this.zones = document2.zones.map((zone) => ({ ...zone, metadata: copyJsonObject(zone.metadata) }));
       this.documentMetadata = copyJsonObject(document2.metadata);
     }
     saveDocument() {
@@ -2055,6 +2178,7 @@ var SSDiagram = (() => {
           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) })),
@@ -2481,8 +2605,10 @@ var SSDiagram = (() => {
       if (t2.overviewViewportFill !== void 0) this.opts.overviewViewportFill = t2.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) return null;
+      if (this.nodes.length === 0 && this.zones.length === 0) return null;
       let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
       for (const n2 of this.nodes) {
         minX = Math.min(minX, n2.x);
@@ -2490,6 +2616,13 @@ var SSDiagram = (() => {
         maxX = Math.max(maxX, n2.x + n2.w);
         maxY = Math.max(maxY, n2.y + n2.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) {
@@ -2541,11 +2674,16 @@ var SSDiagram = (() => {
     // ---- geometry ---------------------------------------------------
     layoutNode(n2) {
       const ctx = this.ctx;
-      ctx.font = "600 12px Segoe UI, Tahoma, sans-serif";
+      ctx.font = TITLE_FONT;
       const titleW = ctx.measureText(n2.name).width;
+      let subtitleW = 0;
+      if (n2.subtitle.length > 0) {
+        ctx.font = SUBTITLE_FONT;
+        subtitleW = ctx.measureText(n2.subtitle).width;
+      }
       const rows = Math.max(n2.inPorts.length, n2.outPorts.length, 1);
-      n2.w = Math.max(170, Math.ceil(titleW) + 28);
-      n2.h = Math.max(48, rows * PORT_ROW_H + 16);
+      n2.w = Math.max(170, Math.ceil(titleW) + 28, Math.ceil(subtitleW) + 28);
+      n2.h = Math.max(n2.subtitle.length > 0 ? SUBTITLE_MIN_H : 48, rows * PORT_ROW_H + 16);
       const off = PORT_SQ / 2;
       const place = (ports, x) => {
         const stack = ports.some(isGrowAnchor) ? [...ports.filter((p) => !isGrowAnchor(p)), ...ports.filter(isGrowAnchor)] : ports;
@@ -2587,6 +2725,15 @@ var SSDiagram = (() => {
       if (p.direction !== "in" || p.type === "" || !isWildcardPortType(p.type)) 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 !== void 0 && maxL < 0.5;
@@ -2895,6 +3042,7 @@ var SSDiagram = (() => {
               // 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
             });
         }
@@ -3280,6 +3428,7 @@ var SSDiagram = (() => {
       this.listen(window, "pointerup", finish);
       this.listen(window, "pointercancel", finish);
       this.listen(this.canvas, "wheel", (e) => {
+        if (this.pageScroll && !e.ctrlKey && !e.metaKey) return;
         e.preventDefault();
         const [sx, sy] = localXY(e);
         const [wx, wy] = this.toWorld(sx, sy);
@@ -3425,6 +3574,7 @@ var SSDiagram = (() => {
     }
     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;
@@ -3452,19 +3602,21 @@ var SSDiagram = (() => {
       );
       this.drawZones();
       const prior = [];
+      const labels = [];
       const hoveredNode = this.hoverPort?.node ?? this.hoverNode;
       for (const l of this.links) {
         const a = this.endpoint(l, "from");
         const b = this.endpoint(l, "to");
         if (a === null || b === null) continue;
         const fp = this.nodes.find((n2) => n2.id === l.from)?.outPorts.find((p) => p.id === l.fromPort);
-        const baseColor = (this.opts.typedLinkColors ?? false) && fp !== void 0 ? this.portColor(fp.type) : this.portColor("");
+        const baseColor = (this.opts.typedLinkColors ?? false) && fp !== void 0 ? this.linkColor(fp.type) : this.portColor("");
         const state = options.selection && l === this.selectedLink ? "sel" : options.transient && (l === this.hoveredLink || hoveredNode !== null && (l.from === hoveredNode.id || l.to === hoveredNode.id)) ? "hov" : "norm";
         const color = state === "sel" ? this.selectionColor() : state === "hov" ? this.linkHoverColor() : baseColor;
         const width = state === "sel" ? 3 : state === "hov" ? 2.6 : 2;
         const pts = this.routeLink(a, b, /* @__PURE__ */ 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];
@@ -3472,6 +3624,7 @@ var SSDiagram = (() => {
           else if (y1 === y2 && x1 !== x2) prior.push({ h: true, c: y1, a: Math.min(x1, x2), b: Math.max(x1, x2) });
         }
       }
+      for (const label2 of labels) this.drawLinkLabel(label2.pts, label2.text, label2.color, background);
       if (options.transient && (this.linking !== null || this.relinking !== null)) this.drawPendingLink();
       this.portFeed = this.feedTypes();
       for (const n2 of this.nodes) this.drawNode(n2, options.selection && this.selectedNodes.has(n2), options);
@@ -3626,8 +3779,9 @@ ${runtime.error}`;
     drawZones() {
       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;
@@ -3643,10 +3797,10 @@ ${runtime.error}`;
         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";
-        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();
       }
     }
@@ -3691,11 +3845,12 @@ ${runtime.error}`;
       const hasRuntimeError = options.runtime && n2.runtimeError.length > 0;
       const runtime = options.runtime ? getJsonKey(this.runtimeState.nodes, n2.id) : void 0;
       const active = options.runtime && (this.runtimeState.activeNodeId === n2.id || runtime?.active === true);
+      const fill = this.resolveColor(n2.color, DEFAULT_NODE_COLOR);
       roundRect(ctx, n2.x, n2.y, n2.w, n2.h, 6);
-      ctx.fillStyle = hasLoadError ? ERROR_BACKGROUND : active ? "#ffd1dc" : n2.color;
+      ctx.fillStyle = hasLoadError ? ERROR_BACKGROUND : active ? "#ffd1dc" : fill;
       ctx.fill();
       ctx.lineWidth = selected ? 2 : 1.5;
-      ctx.strokeStyle = selected ? this.selectionColor() : n2.border;
+      ctx.strokeStyle = selected ? this.selectionColor() : this.resolveColor(n2.border, DEFAULT_NODE_BORDER);
       ctx.stroke();
       if (hasLoadError || hasRuntimeError) {
         let alpha = 1;
@@ -3728,11 +3883,22 @@ ${runtime.error}`;
         }
       }
       const titleShift = n2.icon ? iconW + 4 : 0;
-      ctx.fillStyle = hasLoadError ? "#ffffff" : readableTextOn(active ? "#ffd1dc" : n2.color);
-      ctx.font = "600 12px Segoe UI, Tahoma, sans-serif";
+      const textX = n2.x + titleShift + (n2.w - titleShift) / 2;
+      const textWidth = n2.w - titleShift - 14;
+      ctx.fillStyle = hasLoadError ? "#ffffff" : readableTextOn(active ? "#ffd1dc" : fill);
+      ctx.font = TITLE_FONT;
       ctx.textAlign = "center";
       ctx.textBaseline = "middle";
-      ctx.fillText(n2.name, n2.x + titleShift + (n2.w - titleShift) / 2, n2.y + n2.h / 2, n2.w - titleShift - 14);
+      if (n2.subtitle.length === 0) {
+        ctx.fillText(n2.name, textX, n2.y + n2.h / 2, textWidth);
+      } else {
+        ctx.fillText(n2.name, textX, n2.y + n2.h / 2 - 8, textWidth);
+        ctx.save();
+        ctx.globalAlpha *= 0.72;
+        ctx.font = SUBTITLE_FONT;
+        ctx.fillText(n2.subtitle, textX, n2.y + n2.h / 2 + 9, textWidth);
+        ctx.restore();
+      }
       for (const p of n2.inPorts) this.drawPort(n2, p, options);
       for (const p of n2.outPorts) this.drawPort(n2, p, options);
     }
@@ -3849,6 +4015,45 @@ ${runtime.error}`;
       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;
       const ctx = this.ctx;
@@ -3906,7 +4111,7 @@ ${runtime.error}`;
       }
       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;
@@ -3964,9 +4169,9 @@ ${runtime.error}`;
       ctx.stroke();
       ctx.clip();
       for (const n2 of this.nodes) {
-        ctx.fillStyle = n2.color;
+        ctx.fillStyle = this.resolveColor(n2.color, DEFAULT_NODE_COLOR);
         ctx.fillRect(mx(n2.x), my(n2.y), Math.max(2, n2.w * s), Math.max(2, n2.h * s));
-        ctx.strokeStyle = n2.border;
+        ctx.strokeStyle = this.resolveColor(n2.border, DEFAULT_NODE_BORDER);
         ctx.lineWidth = 1;
         ctx.strokeRect(mx(n2.x), my(n2.y), Math.max(2, n2.w * s), Math.max(2, n2.h * s));
       }
@@ -4007,6 +4212,23 @@ ${runtime.error}`;
     ctx.arcTo(x, y, x + w, y, rr);
     ctx.closePath();
   }
+  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 t2 = remaining / length;
+        return [x1 + (x2 - x1) * t2, y1 + (y2 - y1) * t2];
+      }
+      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;
@@ -4991,6 +5213,7 @@ ${runtime.error}`;
       this.fullscreen = false;
       this.fullscreenButtonVisible = true;
       this.downloadButtonVisible = false;
+      this.exportEnabled = true;
       this.downloadLabel = null;
       // null means the host never named the button, so its wording comes from the shared bundle.
       // Keeping the two apart is what lets an explicit label win while an untouched control still
@@ -5007,7 +5230,8 @@ ${runtime.error}`;
         host: this.div,
         typeColors: this.portTypeColors(),
         gridSnap: options.gridSnap ?? true,
-        gridSize: options.gridSize
+        gridSize: options.gridSize,
+        pageScroll: options.pageScroll ?? false
       });
       this.fullscreenButtonVisible = options.showFullscreenButton ?? true;
       this.fullscreenLabels = options.fullscreenLabels ?? null;
@@ -5085,6 +5309,13 @@ ${runtime.error}`;
     getGridSnap() {
       return this.canvas.getGridSnap();
     }
+    /** See DiagramOptions.pageScroll. */
+    setPageScroll(enabled) {
+      this.canvas.setPageScroll(enabled);
+    }
+    isPageScrollEnabled() {
+      return this.canvas.isPageScrollEnabled();
+    }
     nudgeSelection(dx, dy) {
       return this.canvas.nudgeSelection(dx, dy);
     }
@@ -5266,6 +5497,17 @@ ${runtime.error}`;
       this.downloadButton.hidden = false;
       this.downloadButton.style.display = "inline-flex";
     }
+    /**
+     * Turns the export commands of the context menu on or off. Off, the menu offers them greyed out and
+     * `executeContextCommand` refuses them, for a page that does not want its diagram saved. The
+     * download button is separate: hide it with `setDownloadButtonVisible(false)`.
+     */
+    setExportEnabled(enabled) {
+      this.exportEnabled = enabled;
+    }
+    isExportEnabled() {
+      return this.exportEnabled;
+    }
     isDownloadButtonVisible() {
       return this.downloadButtonVisible;
     }
@@ -5767,15 +6009,15 @@ ${runtime.error}`;
         // picture, and an empty diagram has none to give. They stay on in read-only mode,
         // which forbids changing the diagram, not looking at it.
         exportDocument: {
-          canExecute: ({ document: document2 }) => document2.nodes.length > 0,
+          canExecute: ({ document: document2 }) => this.exportEnabled && document2.nodes.length > 0,
           execute: () => this.emit("exportRequested", { format: "document" })
         },
         exportPng: {
-          canExecute: ({ document: document2 }) => document2.nodes.length > 0,
+          canExecute: ({ document: document2 }) => this.exportEnabled && document2.nodes.length > 0,
           execute: () => this.emit("exportRequested", { format: "png" })
         },
         exportSvg: {
-          canExecute: ({ document: document2 }) => document2.nodes.length > 0,
+          canExecute: ({ document: document2 }) => this.exportEnabled && document2.nodes.length > 0,
           execute: () => this.emit("exportRequested", { format: "svg" })
         },
         // Always available: it shows the overview as readily as it hides it, and an empty
@@ -6411,17 +6653,62 @@ ${runtime.error}`;
     if (renderRevisions.get(div) !== revision)
       return null;
     const catalog = buildCatalog(palette);
+    return mountDiagram(div, catalog, options, false, (diagram) => {
+      const missingTypeTemplate = div.dataset.diagramMissingElement ?? t("embedMissingElement", 'Element type "{typeId}" is missing from the palette.');
+      const converted = toDiagramNodes(
+        scheme,
+        catalog,
+        (typeId) => missingTypeTemplate.replace("{typeId}", typeId || "(empty)")
+      );
+      diagram.load(
+        converted.nodes,
+        scheme.links.map((link) => new Link({
+          outNode: link.from,
+          outPort: link.fromPort,
+          inNode: link.to,
+          inPort: link.toPort
+        })),
+        { nodeErrors: converted.nodeErrors }
+      );
+    });
+  }
+  function renderDocument(div, source, options = {}) {
+    const parsed = readDocument(source);
+    beginRender(div);
+    return mountDocument(div, parsed, options);
+  }
+  function readDocument(source) {
+    let value = source;
+    if (typeof source === "string") {
+      try {
+        value = JSON.parse(source);
+      } catch (error) {
+        throw new DiagramDocumentError(error instanceof Error ? error.message : "invalid JSON");
+      }
+    }
+    if (!isRecord(value))
+      throw new DiagramDocumentError("expected an object");
+    if (value.version !== void 0 && value.version !== DIAGRAM_DOCUMENT_VERSION)
+      throw new DiagramDocumentError(`unsupported document version ${String(value.version)}`, "$.version");
+    return createDiagramDocument(value);
+  }
+  function mountDocument(div, source, options) {
+    return mountDiagram(div, new StockSharpCatalog(), options, true, (diagram) => diagram.loadDocument(source));
+  }
+  function mountDiagram(div, catalog, options, pageScrollByDefault, populate) {
     disposeActiveRender(div);
     div.classList.remove("ss-diagram-error");
     div.replaceChildren();
     const [enterLabel, exitLabel] = (div.dataset.diagramFullscreen ?? "").split("|");
     const downloadLabel = div.dataset.diagramDownload;
-    const showDownloadButton = options.onExportRequested !== void 0;
+    const exportAllowed = options.allowExport !== false && div.dataset.diagramExport !== "off";
+    const showDownloadButton = exportAllowed && options.onExportRequested !== void 0;
     let diagram;
     try {
       diagram = new StockSharpDiagram({
         div,
         catalog,
+        pageScroll: options.pageScroll ?? pageScrollByDefault,
         ...enterLabel && exitLabel ? { fullscreenLabels: { enter: enterLabel, exit: exitLabel } } : {},
         ...showDownloadButton ? { showDownloadButton: true } : {},
         ...downloadLabel ? { downloadLabel } : {}
@@ -6471,7 +6758,9 @@ ${runtime.error}`;
     activeRenders.set(div, handle);
     connectedRenders.add(handle);
     ensureDisconnectedHostObserver();
-    if (options.onExportRequested !== void 0) {
+    if (!exportAllowed) {
+      diagram.setExportEnabled(false);
+    } else if (options.onExportRequested !== void 0) {
       const notifyHost = options.onExportRequested;
       cleanups.push(diagram.on("exportRequested", (request) => notifyHost(request, handle)));
     }
@@ -6498,22 +6787,7 @@ ${runtime.error}`;
       diagram.setReadOnly(true);
       diagram.setLinkValidator(() => true);
       diagram.setOverviewVisible(false);
-      const missingTypeTemplate = div.dataset.diagramMissingElement ?? t("embedMissingElement", 'Element type "{typeId}" is missing from the palette.');
-      const converted = toDiagramNodes(
-        scheme,
-        catalog,
-        (typeId) => missingTypeTemplate.replace("{typeId}", typeId || "(empty)")
-      );
-      diagram.load(
-        converted.nodes,
-        scheme.links.map((link) => new Link({
-          outNode: link.from,
-          outPort: link.fromPort,
-          inNode: link.to,
-          inPort: link.toPort
-        })),
-        { nodeErrors: converted.nodeErrors }
-      );
+      populate(diagram);
       const fit = () => {
         if (!div.isConnected) {
           handle.destroy();
@@ -6610,6 +6884,8 @@ ${runtime.error}`;
       note(div, errors.load, revision);
       return null;
     }
+    if (holdsDocument(div, raw))
+      return drawDocumentAtRevision(div, raw, revision, options, errors);
     const scheme = parseRawScheme(raw);
     if (scheme.nodes.length === 0) {
       note(div, errors.empty, revision);
@@ -6632,6 +6908,8 @@ ${runtime.error}`;
       note(div, errors.empty, revision);
       return null;
     }
+    if (holdsDocument(div, raw))
+      return drawDocumentAtRevision(div, raw, revision, options, errors);
     const scheme = parseRawScheme(raw);
     if (scheme.nodes.length === 0) {
       note(div, errors.empty, revision);
@@ -6644,6 +6922,32 @@ ${runtime.error}`;
       return null;
     }
   }
+  function holdsDocument(div, raw) {
+    if (div.dataset.diagramKind === "document")
+      return true;
+    return isRecord(raw) && typeof raw.version === "number" && Array.isArray(raw.nodes);
+  }
+  function drawDocumentAtRevision(div, raw, revision, options, errors) {
+    if (renderRevisions.get(div) !== revision)
+      return null;
+    let parsed;
+    try {
+      parsed = readDocument(raw);
+    } catch {
+      note(div, errors.empty, revision);
+      return null;
+    }
+    if (parsed.nodes.length === 0 && parsed.zones.length === 0) {
+      note(div, errors.empty, revision);
+      return null;
+    }
+    try {
+      return mountDocument(div, parsed, options);
+    } catch {
+      note(div, errors.draw, revision);
+      return null;
+    }
+  }
   function renderAll(root = document, options = {}) {
     root.querySelectorAll(".ss-diagram-host").forEach((host) => {
       if (host.dataset.rendered === "1")