@helping-ai-workflow/md2doc 3.12.1 → 3.13.1

package/lib/theme/runtime.js

@@ -12,7 +12,16 @@
   btn.hidden = false;
   var data = JSON.parse(dataEl.textContent);
   var listeners = [];
-  function onTheme(fn) { listeners.push(fn); }
+  // Returns the unsubscribe: a page that draws and discards its own svgs (the
+  // wave editor's canvas, once per open) must not leave a listener behind
+  // holding what it drew.
+  function onTheme(fn) {
+    listeners.push(fn);
+    return function () {
+      var at = listeners.indexOf(fn);
+      if (at !== -1) listeners.splice(at, 1);
+    };
+  }
   function notify(dark) { for (var i = 0; i < listeners.length; i++) listeners[i](dark); }
   function isDark() { return root.getAttribute('data-md2doc-theme') === 'dark'; }
   function save(dark) {
@@ -29,6 +38,9 @@
   }
   btn.addEventListener('click', function () {
     var dark = !isDark();
+    // Measured while the light layout is still clean: see prepareGeometry. A
+    // failure there only costs that speed-up; the toggle must still work.
+    if (dark) { try { prepareGeometry(); } catch (e) { /* recolourSvg measures lazily instead */ } }
     if (dark) root.setAttribute('data-md2doc-theme', 'dark'); else root.removeAttribute('data-md2doc-theme');
     save(dark);
     paint();
@@ -268,9 +280,208 @@
     return /^rect$/i.test(el.tagName) && next !== null && /^text$/i.test(next.tagName) &&
       el.closest('[id^="wavearcs"]') !== null;
   }
-  function recolourSvg(svg, dark) {
+  function contrast(a, b) {
+    var x = lum(a), y = lum(b);
+    return (Math.max(x, y) + 0.05) / (Math.min(x, y) + 0.05);
+  }
+  // ── Where a text sits (R7 option A) ──
+  // Geometry is kept apart from colour: a text's STACK is every shape before it in
+  // document order (= paint order) whose fill AREA covers the text's centre, bottom
+  // to top, whatever its fill. That is the same in light and dark, so the toggle
+  // measures it BEFORE the theme attribute flips, while the page layout is still
+  // clean (prepareGeometry), and keeps it per svg; a read after the flip would force
+  // a synchronous layout of the whole restyled page. Colour is applied afterwards:
+  // the stack's FINAL fills are composited (fill alpha x fill-opacity x opacity of
+  // the shape and its ancestors) over the page, so a semi-transparent cell counts as
+  // the colour it really shows.
+  var PAINTED = 'polygon, ellipse, path, rect, circle';
+  var NOT_PAINTED = 'defs, marker, clipPath, mask, pattern, symbol, foreignObject';
+  var geoCache = typeof WeakMap === 'function' ? new WeakMap() : null;
+  // A mermaid XHTML label is measured by its foreignObject.
+  function geoOf(el) { return el.namespaceURI === XHTML ? el.closest('foreignObject') : el; }
+  function centreOf(g) {
+    if (!g || typeof g.getBBox !== 'function') return null;
+    var b, m;
+    try { b = g.getBBox(); m = g.getCTM(); } catch (e) { return null; }
+    if (!m || (!b.width && !b.height)) return null;
+    return new DOMPoint(b.x + b.width / 2, b.y + b.height / 2).matrixTransform(m);
+  }
+  function geomShapes(svg) {
+    var all = svg.querySelectorAll(PAINTED), list = [];
+    for (var i = 0; i < all.length; i++) {
+      var s = all[i], b, m;
+      if (s.closest(NOT_PAINTED) || typeof s.isPointInFill !== 'function') continue;
+      try { b = s.getBBox(); m = s.getCTM(); } catch (e) { continue; }
+      if (!m) continue;
+      // Its box in viewport units, for a cheap reject before isPointInFill.
+      var xs = [], ys = [], cs = [[b.x, b.y], [b.x + b.width, b.y], [b.x, b.y + b.height], [b.x + b.width, b.y + b.height]];
+      for (var c = 0; c < 4; c++) { var q = new DOMPoint(cs[c][0], cs[c][1]).matrixTransform(m); xs.push(q.x); ys.push(q.y); }
+      list.push({ el: s, m: m, vp: s.nearestViewportElement,
+        box: [Math.min.apply(null, xs), Math.min.apply(null, ys), Math.max.apply(null, xs), Math.max.apply(null, ys)] });
+    }
+    return list;
+  }
+  // null when the element has no geometry (detached, display:none).
+  function stackAt(g, shapes) {
+    var p = centreOf(g);
+    if (!p) return null;
+    var vp = g.nearestViewportElement, stack = [];
+    for (var i = 0; i < shapes.length; i++) {
+      var s = shapes[i];
+      if (s.vp !== vp || p.x < s.box[0] || p.x > s.box[2] || p.y < s.box[1] || p.y > s.box[3]) continue;
+      if (!(s.el.compareDocumentPosition(g) & 4)) break; // document order: every later shape follows g too
+      if (s.el.isPointInFill(p.matrixTransform(s.m.inverse()))) stack.push(s.el);
+    }
+    return stack;
+  }
+  // A mermaid svg is rebuilt from markup on every theme swap (new elements, same
+  // drawing), so its stacks are ALSO kept per host and per render kind (light / live
+  // dark) as indices: the n-th text or foreignObject over the m-th shapes. A swapped-in
+  // svg with the same counts adopts them without reading geometry.
+  var GEO_EL = 'text, tspan, foreignObject';
+  var hostGeo = typeof WeakMap === 'function' ? new WeakMap() : null;
+  function hostEntry(svg, make) {
+    var host = hostGeo && svg.closest('.mermaid');
+    if (!host) return null;
+    var kind = svg.hasAttribute('data-md2doc-live') ? 'live' : 'light';
+    var all = hostGeo.get(host) || {};
+    var nT = svg.querySelectorAll(GEO_EL).length, nS = svg.querySelectorAll(PAINTED).length, e = all[kind];
+    if (!e || e.nT !== nT || e.nS !== nS) {
+      if (!make) return null;
+      e = all[kind] = { nT: nT, nS: nS, map: {} };
+      hostGeo.set(host, all);
+    }
+    return e;
+  }
+  function adopt(svg) {
+    var e = geoCache && hostEntry(svg, false);
+    if (!e) return;
+    var keep = geoCache.get(svg) || new Map(), gl = svg.querySelectorAll(GEO_EL), sl = svg.querySelectorAll(PAINTED);
+    for (var t in e.map) {
+      var g = gl[+t];
+      if (g && !keep.has(g)) keep.set(g, e.map[t].map(function (n) { return sl[n]; }));
+    }
+    if (keep.size) geoCache.set(svg, keep);
+  }
+  // An element with no geometry (empty label, display:none) is remembered for the
+  // current toggle only (geoGen): it may be shown before the next one.
+  var noGeo = typeof WeakMap === 'function' ? new WeakMap() : null, geoGen = 0;
+  // Measures the given geometry elements of one svg and remembers each stack.
+  function measure(svg, gs) {
+    var shapes = null, keep = geoCache ? geoCache.get(svg) || new Map() : new Map(), out = new Map();
+    for (var i = 0; i < gs.length; i++) {
+      var g = gs[i];
+      if (!g || out.has(g)) continue;
+      if (shapes === null) shapes = geomShapes(svg);
+      var st = stackAt(g, shapes);
+      out.set(g, st);
+      if (st) keep.set(g, st); else if (noGeo) noGeo.set(g, geoGen);
+    }
+    if (geoCache && keep.size) geoCache.set(svg, keep);
+    var e = keep.size ? hostEntry(svg, true) : null;
+    if (e) {
+      var gl = [].slice.call(svg.querySelectorAll(GEO_EL)), sl = [].slice.call(svg.querySelectorAll(PAINTED));
+      out.forEach(function (st, g) {
+        if (st) e.map[gl.indexOf(g)] = st.map(function (s) { return sl.indexOf(s); });
+      });
+    }
+    return out;
+  }
+  // Called by the toggle before it flips to dark. A light-drawn mermaid svg is
+  // measured too (it is recoloured until the live dark render arrives) unless that
+  // dark render is cached: then the swap replaces it before anything is recoloured.
+  function prepareGeometry() {
+    if (!geoCache) return;
+    geoGen++;
+    var swapsNow = hasMermaid && !inFlight && cached('dark');
+    var svgs = document.querySelectorAll(RECOLOUR);
+    for (var i = 0; i < svgs.length; i++) {
+      var svg = svgs[i], gs = [];
+      if (swapsNow && svg.closest('.mermaid')) continue;
+      adopt(svg);
+      var known = geoCache.get(svg), ts = svg.querySelectorAll('text, tspan, foreignObject *');
+      for (var k = 0; k < ts.length; k++) {
+        var g = geoOf(ts[k]);
+        // Every text, not only the dark ones: an inherited colour can turn dark (or
+        // light) with the page once the theme flips.
+        if (g && !(known && known.has(g)) && !(noGeo && noGeo.get(g) === geoGen)) gs.push(g);
+      }
+      if (gs.length) measure(svg, gs);
+    }
+  }
+  function num(v) { var n = parseFloat(v); return isNaN(n) ? 1 : n; }
+  // A shape's final paint as [r, g, b, alpha], or null when it shows nothing.
+  function paintOf(s, svg, memo) {
+    if (memo.has(s)) return memo.get(s);
+    var cs = getComputedStyle(s), f = rgba(cs.fill), out = null;
+    if (f) {
+      var a = f[3] * num(cs.fillOpacity) * num(cs.opacity);
+      for (var p = s.parentNode; a > 0 && p && p !== svg && p.nodeType === 1; p = p.parentNode) a *= num(getComputedStyle(p).opacity);
+      if (a > 0) out = [f[0], f[1], f[2], Math.min(a, 1)];
+    }
+    memo.set(s, out);
+    return out;
+  }
+  // The colour under a text: its stack composited over the page; null when nothing
+  // in the stack paints (the text then keeps the old rule).
+  function composite(stack, page, svg, memo) {
+    var c = null;
+    for (var i = 0; i < stack.length; i++) {
+      var p = paintOf(stack[i], svg, memo);
+      if (!p) continue;
+      if (!c) c = page.slice(0, 3);
+      c = [p[0] * p[3] + c[0] * (1 - p[3]), p[1] * p[3] + c[1] * (1 - p[3]), p[2] * p[3] + c[2] * (1 - p[3])];
+    }
+    return c ? [c[0], c[1], c[2], 1] : null;
+  }
+  // No geometry at recolour time (a diagram hidden while the theme flips): the text
+  // could sit on any shape of its own node or cluster, so it is judged against all
+  // of them: each shape's paint composited over the page, or the page where a shape
+  // paints nothing (a table cell without a bgcolor). Text in no node keeps the old rule.
+  function nodeFallback(el, page, svg, memo) {
+    var n = el.closest('g.node, g.cluster');
+    if (!n) return null;
+    var pg = [page[0], page[1], page[2], 1], all = n.querySelectorAll(PAINTED), out = [], seen = {};
+    for (var i = 0; i < all.length; i++) {
+      if (all[i].closest('foreignObject')) continue;
+      var c = composite([all[i]], page, svg, memo) || pg;
+      if (!seen[c.join()]) { seen[c.join()] = 1; out.push(c); }
+    }
+    return out.length ? out : [pg];
+  }
+  // R7 option A: a dark text keeps its author colour unless the rule's replacement
+  // (a toned colour for saturated text) or #e3e3e3 reads better on what is under it.
+  // `unders` is the colour under it (one entry) or, with no geometry, every colour it
+  // might sit on: each option is scored by its WORST contrast over them, the best
+  // score wins, ties keep the author's then the toned colour. null = keep the
+  // author's colour. Over no shape (unders null): the old rule (the replacement).
+  // Shapes are never changed here.
+  function textFor(own, unders) {
+    var cand = hsl(own)[1] > 0.25 ? tone(own, 0.78, 0.7) : TEXT;
+    if (!unders) return cand;
+    var opts = cand === TEXT ? [null, TEXT] : [null, cand, TEXT], best = null, bestC = -1;
+    for (var i = 0; i < opts.length; i++) {
+      var col = opts[i] === null ? own : rgba(opts[i]), worst = Infinity;
+      for (var u = 0; u < unders.length; u++) worst = Math.min(worst, contrast(col, unders[u]));
+      if (worst > bestC) { best = opts[i]; bestC = worst; }
+    }
+    return best;
+  }
+  function decide(own, unders, memo) {
+    var key = own.join() + '|' + (unders ? unders.map(function (u) { return u.join(); }).join(';') : '');
+    if (!(key in memo)) memo[key] = textFor(own, unders);
+    return memo[key];
+  }
+  function restyle(el, ov) {
+    if (!ov) return;
+    var base = el.getAttribute('data-md2doc-style');
+    el.setAttribute('style', (base ? base.replace(/;?\s*$/, ';') : '') + ov);
+  }
+  function recolourSvg(svg, dark, opts) {
+    var backing = (opts && opts.backing) || 'var(--md-bg)';
     var els = svg.querySelectorAll('polygon, ellipse, path, polyline, rect, line, circle, text, tspan, foreignObject *');
     var live = svg.hasAttribute('data-md2doc-live');
+    var texts = [];
     for (var i = 0; i < els.length; i++) {
       var el = els[i];
       if (el.hasAttribute('data-md2doc-style')) {
@@ -287,43 +498,94 @@
         el.setAttribute('data-md2doc-style', el.getAttribute('style') || '');
       }
       if (!dark) continue;
+      // Texts and mermaid's XHTML labels wait for the second pass, so each one
+      // is paired with the FINAL fill of its own shape whatever the document order.
+      if (el.namespaceURI === XHTML || /^(text|tspan)$/i.test(el.tagName)) { texts.push(el); continue; }
       var cs = getComputedStyle(el);
       var ov = '';
-      if (el.namespaceURI === XHTML) {
-        // Mermaid flowchart labels: HTML inside foreignObject, coloured by CSS.
-        var fg = rgba(cs.color), bgc = rgba(cs.backgroundColor);
-        if (fg && fg[3] > 0 && lum(fg) < 0.35) ov += 'color:' + (hsl(fg)[1] > 0.25 ? tone(fg, 0.78, 0.7) : TEXT) + ' !important;';
-        if (bgc && bgc[3] > 0) {
-          var BL = lum(bgc);
-          if (BL > 0.85) ov += 'background-color:transparent !important;';
-          else if (BL > 0.3) ov += 'background-color:' + tone(bgc, 0.26, 0.55) + ' !important;';
-        }
-        if (ov) {
-          var hb = el.getAttribute('data-md2doc-style');
-          el.setAttribute('style', (hb ? hb.replace(/;?\s*$/, ';') : '') + ov);
-        }
-        continue;
-      }
       var fill = rgba(cs.fill), stroke = rgba(cs.stroke);
       // Overrides are written once, as attribute text, never through el.style:
       // setProperty leaves style="" on the element after the restore removes
       // the attribute (Chromium re-serialises it), so light would not be
       // byte-exact.
-      if (/^(text|tspan)$/i.test(el.tagName)) {
-        if (fill && fill[3] > 0 && lum(fill) < 0.35) ov += 'fill:' + (hsl(fill)[1] > 0.25 ? tone(fill, 0.78, 0.7) : TEXT) + ' !important;';
-      } else {
-        if (fill && fill[3] > 0) {
-          var L = lum(fill);
-          if (L > 0.85) ov += isWaveLabelBacking(el) ? 'fill:var(--md-bg) !important;' : 'fill:transparent !important;';
-          else if (L > 0.3) ov += 'fill:' + tone(fill, 0.26, 0.55) + ' !important;';
-          else if (el.closest('g.edge, marker')) ov += 'fill:' + lineColour(fill) + ' !important;';
+      if (fill && fill[3] > 0) {
+        var L = lum(fill);
+        if (L > 0.85) ov += isWaveLabelBacking(el) ? 'fill:' + backing + ' !important;' : 'fill:transparent !important;';
+        else if (L > 0.3) ov += 'fill:' + tone(fill, 0.26, 0.55) + ' !important;';
+        else if (el.closest('g.edge, marker')) ov += 'fill:' + lineColour(fill) + ' !important;';
+      }
+      if (stroke && stroke[3] > 0 && lum(stroke) < 0.35) ov += 'stroke:' + lineColour(stroke) + ' !important;';
+      restyle(el, ov);
+    }
+    // Only a dark text has a choice to make. It uses the stack measured before the
+    // toggle flipped the theme when there is one. Otherwise geometry is read only
+    // when the choice can differ between what the text might sit on (each opaque
+    // paint, or none; any translucent paint always measures): reading it forces a
+    // synchronous layout, which a freshly drawn svg (the wave editor redraws on every
+    // edit) has not had yet. An svg text's own fill is read here once and reused
+    // below: the writes below would otherwise force a style recalc before every read.
+    var memo = {}, paints = new Map(), unders = [], owns = [], need = [], fills = null, translucent = false;
+    if (dark) adopt(svg);
+    var known = geoCache && geoCache.get(svg), page = null;
+    function pageColour() {
+      if (page) return page;
+      var bk = opts && opts.backing;
+      page = (bk && /^rgba?\(/.test(bk) ? rgba(bk) : null) || rgba(getComputedStyle(document.body).backgroundColor) || [255, 255, 255, 1];
+      return page;
+    }
+    for (var k = 0; k < texts.length; k++) {
+      var kc = owns[k] = rgba(texts[k].namespaceURI === XHTML ? getComputedStyle(texts[k]).color : getComputedStyle(texts[k]).fill);
+      if (!kc || kc[3] === 0 || lum(kc) >= 0.35) continue;
+      var st = known && known.get(geoOf(texts[k]));
+      if (st && st.every(function (s) { return svg.contains(s); })) { var cu = composite(st, pageColour(), svg, paints); unders[k] = cu ? [cu] : null; continue; }
+      var kg = geoOf(texts[k]);
+      if (noGeo && kg && noGeo.get(kg) === geoGen) { unders[k] = nodeFallback(texts[k], pageColour(), svg, paints); continue; }
+      if (fills === null) {
+        fills = [];
+        var all = svg.querySelectorAll(PAINTED), seen = {};
+        for (var q = 0; q < all.length; q++) {
+          if (all[q].closest(NOT_PAINTED)) continue;
+          var pq = paintOf(all[q], svg, paints);
+          if (!pq) continue;
+          if (pq[3] < 1) translucent = true;
+          else if (!seen[pq.join()]) { seen[pq.join()] = 1; fills.push(pq); }
         }
-        if (stroke && stroke[3] > 0 && lum(stroke) < 0.35) ov += 'stroke:' + lineColour(stroke) + ' !important;';
       }
-      if (ov) {
-        var base = el.getAttribute('data-md2doc-style');
-        el.setAttribute('style', (base ? base.replace(/;?\s*$/, ';') : '') + ov);
+      var first = decide(kc, null, memo), differs = translucent;
+      for (var w = 0; w < fills.length && !differs; w++) differs = decide(kc, [fills[w]], memo) !== first;
+      if (differs) need.push(k);
+    }
+    if (need.length) {
+      var got = measure(svg, need.map(function (n) { return geoOf(texts[n]); }));
+      for (var r = 0; r < need.length; r++) {
+        var ns = got.get(geoOf(texts[need[r]]));
+        var nc = ns ? composite(ns, pageColour(), svg, paints) : null;
+        unders[need[r]] = ns ? (nc ? [nc] : null) : nodeFallback(texts[need[r]], pageColour(), svg, paints);
+      }
+    }
+    for (var j = 0; j < texts.length; j++) {
+      var t = texts[j], tov = '';
+      if (t.namespaceURI === XHTML) {
+        // Mermaid flowchart labels: HTML inside foreignObject, coloured by CSS.
+        // Read again: a label inherits the colour its parent was just given.
+        var tcs = getComputedStyle(t), fg = rgba(tcs.color), bgc = rgba(tcs.backgroundColor);
+        if (fg && fg[3] > 0 && lum(fg) < 0.35) {
+          var fc = decide(fg, unders[j], memo);
+          if (fc) tov += 'color:' + fc + ' !important;';
+        }
+        if (bgc && bgc[3] > 0) {
+          var BL = lum(bgc);
+          if (BL > 0.85) tov += 'background-color:transparent !important;';
+          else if (BL > 0.3) tov += 'background-color:' + tone(bgc, 0.26, 0.55) + ' !important;';
+        }
+      } else {
+        var tf = owns[j];
+        if (tf && tf[3] > 0 && lum(tf) < 0.35) {
+          var tc = decide(tf, unders[j], memo);
+          if (tc) tov += 'fill:' + tc + ' !important;';
+        }
       }
+      restyle(t, tov);
     }
     if (dark) svg.setAttribute('data-md2doc-recoloured', ''); else svg.removeAttribute('data-md2doc-recoloured');
   }
@@ -352,4 +614,9 @@
     }).observe(content, { childList: true, subtree: true });
   }
   if (isDark()) recolourAll(true);
+  // Public surface for pages that draw their own SVG outside .content (the wave editor canvas).
+  // `__listenerCount` is a test hook (test/editor-click.test.js): the wave
+  // editor subscribes once per open and must unsubscribe on close.
+  window.md2docTheme = { isDark: isDark, onTheme: onTheme, recolourSvg: recolourSvg,
+    __listenerCount: function () { return listeners.length; } };
 })();

package/lib/theme/tokens.js

@@ -163,6 +163,9 @@ function themeCss() {
     '    ' + D + ' .content a:not(.heading-anchor), ' + D + ' .content a:not(.heading-anchor):visited { color: ' + LINK_DARK + '; }',
     '    ' + D + ' .content img { background: #ffffff; border-radius: 4px; box-shadow: 0 0 0 10px #ffffff; }',
     '    ' + D + ' .content .drawio { background: #ffffff; border-radius: 6px; box-shadow: 0 0 0 10px #ffffff; }',
+    // R7 甲: a Markdown-native inline svg (wrapped in .inline-svg by the renderer) gets the
+    // same white plate; its ink stays the light text colour because the plate is always white.
+    '    ' + D + ' .content .inline-svg > svg { background: #ffffff; color: #1f2328; border-radius: 4px; box-shadow: 0 0 0 10px #ffffff; }',
     '    ' + D + ' .lightbox-canvas > svg[data-md2doc-recoloured] { background: var(--md-bg); }',
     '  }',
     '  .md2doc-theme-toggle { position: fixed; right: 20px; bottom: 20px; z-index: 60; width: 40px; height: 40px;',

package/lib/wave-overflow.js

@@ -0,0 +1,107 @@
+'use strict';
+
+/**
+ * wave-overflow — estimate how wide a WaveDrom data label is and find the ones
+ * wider than the segment they sit in.
+ *
+ * UMD: node `module.exports`. The edit page loads it through lib/editor/server.js
+ * `waveModuleTag`, whose CommonJS shim supplies `module`, so in the browser it
+ * lands at `window.__md2docWave['wave-overflow.js']` (wave-ui.js receives it as
+ * `opts.waveOverflow`). Segments come from wave-codec (`expandWave`,
+ * `dataSlotOf`), never from a second parser of the wave string.
+ *
+ * Widths are the standard Helvetica AFM advances (1/1000 em) for ASCII 32-126;
+ * anything else counts one em. The reader draws data labels in Helvetica at
+ * 14.6667px, which measured 107px for twelve F and 149px for
+ * "D2 (client FCS last 4B)"; this table reproduces both within 2px.
+ */
+(function (root, factory) {
+  if (typeof module === 'object' && module.exports) {
+    module.exports = factory(require('./editor/wave-codec.js'));
+  } else {
+    // Only a bare <script> with no shim reaches this branch; nothing ships it
+    // that way today.
+    root.md2docWaveOverflow = factory(root.__md2docWave['wave-codec.js']);
+  }
+}(typeof self !== 'undefined' ? self : this, function (codec) {
+  // Index 0 is code 32 (space).
+  const AFM = [
+    278, 278, 355, 556, 556, 889, 667, 191, 333, 333, 389, 584, 278, 333, 278, 278,
+    556, 556, 556, 556, 556, 556, 556, 556, 556, 556, 278, 278, 584, 584, 584, 556,
+    1015, 667, 667, 722, 722, 667, 611, 778, 722, 278, 500, 667, 556, 833, 722, 778,
+    667, 778, 722, 667, 611, 722, 667, 944, 667, 667, 611, 278, 278, 278, 469, 556,
+    333, 556, 556, 500, 556, 556, 278, 556, 556, 222, 222, 500, 222, 833, 556, 556,
+    556, 556, 333, 500, 278, 556, 500, 722, 500, 500, 500, 334, 260, 334, 584,
+  ];
+  const DEFAULT_FONT_PX = 14.6667;
+  const CYCLE_UNITS = 40;
+  const PAD = 6;   // breathing room kept on top of the text
+
+  function estimateTextWidth(text, fontPx) {
+    const px = typeof fontPx === 'number' ? fontPx : DEFAULT_FONT_PX;
+    let em = 0;
+    for (const ch of String(text)) {
+      const c = ch.codePointAt(0);
+      em += (c >= 32 && c <= 126 ? AFM[c - 32] : 1000) / 1000;
+    }
+    return em * px;
+  }
+
+  // WaveDrom's own rule (parse-config.js): rounded, <=0 -> 1, capped at 100.
+  function hscaleOf(doc) {
+    const h = doc && doc.config && doc.config.hscale;
+    if (!h) return 1;
+    const n = Math.round(h > 0 ? Math.round(h) : 1);
+    return n > 0 ? Math.min(n, 100) : 1;
+  }
+
+  function lanesOf(list, out) {
+    for (const item of list) {
+      if (Array.isArray(item)) lanesOf(item, out);
+      else if (item && typeof item === 'object') out.push(item);
+    }
+    return out;
+  }
+
+  function dataList(lane) {
+    if (Array.isArray(lane.data)) return lane.data.map(String);
+    if (typeof lane.data === 'string') return lane.data.split(/\s+/).filter(Boolean);
+    return [];
+  }
+
+  function overflowOf(doc) {
+    const out = [];
+    if (!doc || !Array.isArray(doc.signal)) return out;
+    const hscale = hscaleOf(doc);
+    lanesOf(doc.signal, []).forEach(function (lane, laneIndex) {
+      if (typeof lane.wave !== 'string') return;
+      const cells = codec.expandWave(lane.wave);
+      const data = dataList(lane);
+      const p = Number(lane.period);
+      const period = p > 0 ? p : 1;
+      for (let i = 0; i < cells.length; i++) {
+        const slot = codec.dataSlotOf(lane, i);
+        if (slot === null || slot >= data.length) continue;
+        let n = 1;
+        while (i + n < cells.length && cells[i + n].held) n++;
+        const label = data[slot];
+        const need = estimateTextWidth(label) + PAD;
+        const unit = n * CYCLE_UNITS * period;
+        if (need <= unit * hscale) continue;
+        out.push({
+          laneIndex: laneIndex, name: typeof lane.name === 'string' ? lane.name : '',
+          slot: slot, label: label, cells: n, needScale: Math.ceil(need / unit),
+        });
+      }
+    });
+    return out;
+  }
+
+  function suggestScale(list, current) {
+    let k = 0;
+    for (const o of list || []) if (o.needScale > k) k = o.needScale;
+    return k || (typeof current === 'number' ? current : 1);
+  }
+
+  return { estimateTextWidth: estimateTextWidth, overflowOf: overflowOf, suggestScale: suggestScale };
+}));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helping-ai-workflow/md2doc",
-  "version": "3.12.1",
+  "version": "3.13.1",
   "description": "Markdown → HTML / PDF renderer with WaveDrom, Mermaid, Graphviz, and draw.io support",
   "keywords": [
     "markdown",
@@ -46,8 +46,8 @@
   },
   "scripts": {
     "preinstall": "node scripts/preinstall.js",
-    "test": "node test/md2doc.test.js && node test/highlight.test.js && node test/blockmap.test.js && node test/drawio.test.js && node test/images.test.js && node test/scroll-anchor.test.js && node test/lightbox.test.js && node test/lightbox-anno.test.js && node test/lightbox-anno-style.test.js && node test/reader-panels.test.js && node test/cli.test.js && node test/code-operator.test.js && node test/convert-md.test.js && node test/render-api.test.js && node test/lineops.test.js && node test/indent-clamp.test.js && node test/selection.test.js && node test/cell-range.test.js && node test/editmode-render.test.js && node test/editmode-wavedrom-reinit.test.js && node test/editor-server.test.js && node test/cli-edit.test.js && node test/open-viewer.test.js && node test/editor-client.test.js && node test/editor-client-runtime.test.js && node test/roundtrip.test.js && node test/byte-stability.test.js && node test/editor-server-throw.test.js && node test/editor-reader-rebind.test.js && node test/inline-md.test.js && node test/table-md.test.js && node test/table-anchor-recovery.test.js && node test/gate-compat.test.js && node test/history.test.js && node test/list-md.test.js && node test/table-width.test.js && node test/toolbar-model.test.js && node test/asset.test.js && node test/paste-md.test.js && node test/patchmap.test.js && node test/wave-codec.test.js && node test/wave-draw.test.js && node test/wave-geometry.test.js && node test/wave-store.test.js && node test/wave-rail-clearance.test.js && node test/editor-journey.test.js && node test/detach-census.test.js && node test/editor-arrow-nav.test.js && node test/editor-cell-range.test.js && node test/reader-design.test.js && node test/theme.test.js",
-    "test:browser": "node test/reader-click.test.js && node test/editor-click.test.js"
+    "test": "node test/md2doc.test.js && node test/highlight.test.js && node test/blockmap.test.js && node test/drawio.test.js && node test/images.test.js && node test/scroll-anchor.test.js && node test/lightbox.test.js && node test/lightbox-anno.test.js && node test/lightbox-anno-style.test.js && node test/reader-panels.test.js && node test/cli.test.js && node test/code-operator.test.js && node test/convert-md.test.js && node test/render-api.test.js && node test/lineops.test.js && node test/indent-clamp.test.js && node test/selection.test.js && node test/cell-range.test.js && node test/editmode-render.test.js && node test/editmode-wavedrom-reinit.test.js && node test/editor-server.test.js && node test/cli-edit.test.js && node test/open-viewer.test.js && node test/editor-client.test.js && node test/editor-client-runtime.test.js && node test/roundtrip.test.js && node test/byte-stability.test.js && node test/editor-server-throw.test.js && node test/editor-reader-rebind.test.js && node test/inline-md.test.js && node test/table-md.test.js && node test/table-anchor-recovery.test.js && node test/gate-compat.test.js && node test/history.test.js && node test/list-md.test.js && node test/table-width.test.js && node test/toolbar-model.test.js && node test/asset.test.js && node test/paste-md.test.js && node test/patchmap.test.js && node test/wave-codec.test.js && node test/wave-draw.test.js && node test/wave-geometry.test.js && node test/wave-store.test.js && node test/editor-journey.test.js && node test/detach-census.test.js && node test/editor-arrow-nav.test.js && node test/editor-cell-range.test.js && node test/reader-design.test.js && node test/theme.test.js && node test/release-check.test.js && node test/wave-overflow.test.js",
+    "test:browser": "node test/reader-click.test.js && node test/editor-click.test.js && node test/wave-canvas.test.js"
   },
   "repository": {
     "type": "git",

package/scripts/release-check.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+'use strict';
+
+// Release gate for .github/workflows/publish.yml.
+//
+// The test suites run once, on the pull request. Branch protection on `main`
+// requires those checks to be green and the branch to be up to date before a
+// merge, so every commit on main is a tree that already passed them; running
+// `npm test` again on the tag only repeated a 40-minute job (v3.12.1: four
+// `npm test` runs for one release). What the tag job still has to prove is that
+// the release metadata agrees:
+//   - the tag is vX.Y.Z and equals package.json's version;
+//   - the top `## vX.Y.Z — YYYY-MM-DD` heading of CHANGELOG.md is that version;
+//   - (CLI, --on-main) the tagged commit is reachable from origin/main.
+//
+// Usage: node scripts/release-check.js <tag> [--on-main]
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const HEADING = /^## v(\d+\.\d+\.\d+) — \d{4}-\d{2}-\d{2}\s*$/m;
+
+function checkRelease({ tag, pkgVersion, changelog }) {
+  const errors = [];
+  if (!/^v\d+\.\d+\.\d+$/.test(tag)) {
+    errors.push(`tag "${tag}" is not of the form vX.Y.Z`);
+  } else if (tag !== 'v' + pkgVersion) {
+    errors.push(`tag ${tag} does not match package.json version ${pkgVersion}`);
+  }
+  const m = HEADING.exec(changelog);
+  if (m === null) {
+    errors.push('CHANGELOG.md has no "## vX.Y.Z — YYYY-MM-DD" heading');
+  } else if ('v' + m[1] !== tag) {
+    errors.push(`CHANGELOG.md top section is v${m[1]}, not ${tag}`);
+  }
+  return errors;
+}
+
+function main(argv) {
+  const tag = argv[0];
+  if (!tag) { console.error('usage: node scripts/release-check.js <tag> [--on-main]'); return 2; }
+  const root = path.join(__dirname, '..');
+  const pkgVersion = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).version;
+  const changelog = fs.readFileSync(path.join(root, 'CHANGELOG.md'), 'utf8');
+  const errors = checkRelease({ tag, pkgVersion, changelog });
+  if (argv.includes('--on-main')) {
+    try {
+      execFileSync('git', ['merge-base', '--is-ancestor', 'HEAD', 'origin/main'], { cwd: root, stdio: 'ignore' });
+    } catch (e) {
+      errors.push(`the tagged commit is not on origin/main (tag only merge commits on main)`);
+    }
+  }
+  for (const e of errors) console.error('release-check: ' + e);
+  if (errors.length === 0) console.log(`release-check: ${tag} ok (package.json ${pkgVersion}, CHANGELOG top section ${tag})`);
+  return errors.length === 0 ? 0 : 1;
+}
+
+module.exports = { checkRelease };
+if (require.main === module) process.exit(main(process.argv.slice(2)));