@helping-ai-workflow/md2doc 3.5.0 → 3.6.1

package/lib/md2doc.js

@@ -1639,8 +1639,21 @@ ${itemsHtml}
     position: fixed; inset: 0; z-index: 998; background: rgba(0,0,0,.45);
     display: flex; align-items: center; justify-content: center;
   }
+  /* v3.6.0 Task 13: width cap raised from 1200px to 1920px — MEASURED
+     (createEditorServer, four real viewports): at 1200px the cap itself
+     was the binding constraint at 1280/1600/1920 alike (94vw there is
+     1203/1504/1805px, all above the old 1200px cap), so every screen from a
+     1280 laptop up to a 1920 monitor got the IDENTICAL canvas width — the
+     exact complaint that opened this version ("a bigger monitor buys the
+     user nothing"). 1920px is chosen so 94vw is the actual governor at
+     every one of those four measured sizes (94% of 1920 is 1804.8, still
+     under the new cap) — this number is a ceiling for a screen wider than
+     that, not a value that binds within the measured range. At 800x600,
+     94vw (752px) was already narrower than either cap, so that viewport is
+     unchanged by this. See task-13-report.md for the re-measured
+     toolbar/canvas table. */
   .ed-wave-panel {
-    background: #fff; border-radius: 6px; width: min(1200px, 94vw);
+    background: #fff; border-radius: 6px; width: min(1920px, 94vw);
     height: min(760px, 90vh); display: flex; flex-direction: column;
     box-shadow: 0 6px 28px rgba(0,0,0,.35); overflow: hidden;
   }
@@ -1664,15 +1677,49 @@ ${itemsHtml}
     display: flex; flex-wrap: wrap; gap: 12px; align-items: center;
     padding: 8px 12px; border-bottom: 1px solid #e2e2e2; background: #fafafa;
   }
-  .ed-wave-brushes, .ed-wave-cycleops, .ed-wave-meta {
+  /* v3.6.0 Task 12: the eight captioned sections themselves. .ed-wave-tools
+     is the row that holds them (the SAME element as .ed-wave-toolbar
+     above -- that class still owns the bar's padding/border/background,
+     this one owns only the group row's own gap). Each .ed-wave-tool-group
+     is a bordered chip so eight adjacent sections read as eight things, not
+     one longer wall of buttons; the caption sits to its buttons' LEFT (see
+     wave-panels.js's toolGroup() for why not above). */
+  .ed-wave-tools { display: flex; flex-wrap: wrap; gap: 10px; align-items: center; }
+  .ed-wave-tool-group {
+    display: flex; align-items: center; gap: 4px;
+    padding: 2px 6px; border: 1px solid #ececec; border-radius: 6px;
+  }
+  .ed-wave-tool-caption {
+    font-size: 10px; color: #8a8a8a; letter-spacing: .5px;
+    white-space: nowrap; margin-right: 2px;
+  }
+  .ed-wave-brushes, .ed-wave-meta {
     display: flex; flex-wrap: wrap; gap: 4px; align-items: center;
   }
-  .ed-wave-brush {
-    width: 28px; height: 28px; border: 1px solid #c4c4c4; border-radius: 4px;
-    background: #fff; font-family: monospace; font-size: 14px; cursor: pointer;
+  /* v3.6.0 Task 10: widened from a 28x28 bare-character square to a small
+     column (glyph on top, the character kept as a caption underneath) so
+     the 22-brush palette says what each brush paints instead of relying on
+     the letter alone -- nine of those 22 (P, N, u, d, h, l, 2, 6-9) have no
+     obvious on-canvas picture from the character by itself. */
+  /* '.ed-wave-brushes .ed-wave-brush', not the bare class: '.ed-wave-toolbar
+     button' below outranks a single class on specificity (class+type beats
+     class alone) and would otherwise win the padding fight and squeeze the
+     24px-wide icon into a content box narrower than it is. */
+  .ed-wave-brushes .ed-wave-brush {
+    width: 34px; height: 40px; border: 1px solid #c4c4c4; border-radius: 4px;
+    background: #fff; font-family: monospace; cursor: pointer;
+    display: flex; flex-direction: column; align-items: center;
+    justify-content: center; gap: 1px; padding: 2px 0; box-sizing: border-box;
   }
   .ed-wave-brush.is-on { background: #1a73e8; color: #fff; border-color: #1a73e8; }
-  .ed-wave-cycleops button, .ed-wave-toolbar button {
+  .ed-wave-brush-char { font-size: 11px; line-height: 1; }
+  /* The glyph itself. Its shapes are drawn by wave-draw.js's levelIcon,
+     which reuses renderCanvas's own drawing functions (bandOf, brickPath,
+     the bus/clock/gap helpers) -- never a second hand-drawn set, so a
+     change to how a brush paints on the real canvas cannot leave the
+     toolbar showing the old picture. */
+  .ed-wave-level-icon { display: block; overflow: visible; }
+  .ed-wave-toolbar button {
     border: 1px solid #c4c4c4; border-radius: 4px; background: #fff;
     padding: 3px 8px; font-size: 12px; cursor: pointer;
   }
@@ -1681,20 +1728,18 @@ ${itemsHtml}
      treatment as .ed-wave-brush.is-on above — a picked tool reads the same
      way whichever toolbar it lives in. */
   .ed-wave-edge-arm.is-on { background: #1a73e8; color: #fff; border-color: #1a73e8; }
+  /* v3.6.0 Task 13: the fixed 110px input width that used to live here moved
+     into .ed-wave-section-body input below — every .ed-wave-metafield
+     now lives inside a right-hand panel (關聯線/文件/Lane), not the toolbar,
+     and a panel field should fill the ~340px column rather than sit at a
+     width chosen for the old horizontal toolbar row. */
   .ed-wave-metafield { display: flex; align-items: center; gap: 4px; font-size: 12px; }
-  .ed-wave-metafield input { width: 110px; font-size: 12px; padding: 2px 4px; }
-  /* v3.5.0 Task 6 fix round 2: with no rule at all this is a flex item inside
-     .ed-wave-toolbar (display:flex; flex-wrap:wrap) that sizes to content, so
-     its three controls squeeze against whichever control precedes them
-     instead of forming their own row. The two property groups below are not
-     new values invented for this rule: display/flex-wrap/gap/align-items are
-     copied from .ed-wave-brushes, .ed-wave-cycleops, .ed-wave-meta above (the
-     shared flex-row rule its own children need), and flex:1 1 100% is copied
-     from .ed-wave-unmodelled below (what makes THAT sibling claim its own row
-     instead of sitting beside the control before it) — this row needs both at
-     once: it lays out its own children AND has to stop sharing a line with
-     whatever toolbar control precedes it. */
-  .ed-wave-edgebar { display: flex; flex-wrap: wrap; gap: 4px; align-items: center; flex: 1 1 100%; }
+  /* v3.6.0 Task 13: the 關聯線 panel's own content, stacked vertically now
+     that it lives in a narrow side column rather than a wide flex-wrap
+     toolbar row (the old 'flex: 1 1 100%' here was what made it claim a
+     full row of THAT row; a panel body has no siblings to share a row
+     with). */
+  .ed-wave-edgebar { display: flex; flex-direction: column; gap: 4px; }
   /* The "this drawing is not showing you everything" notice. period / phase /
      config.hscale all change what the ENGINE paints and none of them is
      modelled by the hand drawing, so a document carrying one says so instead
@@ -1709,14 +1754,33 @@ ${itemsHtml}
      Same shape as its neighbour so the two read as one family, one step
      louder because the information gap is bigger. */
   .ed-wave-nolanes { color: #7a1f00; background: #ffe9e0; border-color: #e8a987; }
-  .ed-wave-body { display: flex; flex: 1 1 auto; min-height: 0; }
-  /* Widths chosen so the DRAWING still gets room at the narrowest viewport this
-     repo's browser tests use (800x600 -> panel 752): 752 - 200 - 160 = 392px,
-     which is 8 cycles at .ed-wave-canvas's 48px pitch. The canvas is a scroll
-     container, so a wider diagram scrolls rather than pushing the preview off —
-     but a canvas column narrower than a couple of cycles would make the drag
-     gesture unusable, and that was the first thing measured to go wrong here
-     (a press landed on the preview column, 116px past the canvas's clip). */
+  /* v3.6.0 Task 13 fix round 1 (Critical 2): position: relative added.
+     .ed-wave-side[data-expanded] below is position: absolute, and neither
+     .ed-wave-panel nor (until this line) this element had a position of
+     their own — so its containing block was .ed-wave-overlay
+     (position: fixed; inset: 0), the WHOLE viewport, not the dialog.
+     .ed-wave-panel's own overflow: hidden did not clip it either: clipping
+     follows the containing-block chain, not DOM nesting, so the rail
+     rendered against viewport corners at a narrow window and covered
+     .ed-wave-head's 關閉 button — the only discoverable way to close the
+     dialog (a hit-test at 關閉's own rectangle returned the edge panel's
+     delete button instead; Escape still worked but was not discoverable).
+     Anchoring the rail to THIS element rather than to .ed-wave-panel itself
+     is deliberate, not incidental: .ed-wave-body sits below .ed-wave-head
+     and above .ed-wave-status, so top: 0 / bottom: 0 on the rail now lands
+     at body's own top/bottom — never over the header (關閉) or the status
+     line — without this rule having to know either one's height. */
+  .ed-wave-body { display: flex; flex: 1 1 auto; min-height: 0; position: relative; }
+  /* v3.6.0 Task 13: the old comment here hand-computed the canvas's leftover
+     width from the (now gone) .ed-wave-preview column's own flex-basis;
+     that arithmetic no longer applies — the third column is .ed-wave-side
+     below, which collapses to a 28px rail under 1100px specifically so the
+     canvas is not squeezed the way a fixed 160px minimum used to squeeze it
+     at 800x600 (MEASURED before this task: canvas width there was only
+     282px). Re-measured after this task at four real viewports; see
+     task-13-report.md rather than a formula here — a number derived by hand
+     drifts the moment any sibling column's own width changes, which is
+     exactly what this task did. */
   .ed-wave-lanes {
     flex: 0 0 200px; border-right: 1px solid #e2e2e2; overflow: auto;
     padding: 8px 0 8px 0;
@@ -1727,27 +1791,37 @@ ${itemsHtml}
      the rail spanning its lanes' rows instead, which is the shape the engine
      itself gives it (horizontal space in the name column, no vertical space). */
   .ed-wave-lane-rows { position: relative; }
+  /* v3.6.0 Task 14: a row is a drag handle, a name field and (on a {}
+     spacer) a badge. It used to be six buttons plus the field, and the six
+     did not fit: flexed into what was left of 200px the field measured
+     45px on the most crowded row, and a browser given a 24px box and a
+     three-character Chinese caption lays that caption out VERTICALLY — the
+     editor shipped columns of stacked glyphs where labels were meant.
+     Those six are toolbar buttons now (the 訊號 / 群組 sections), acting
+     on the one selection. */
   .ed-wave-lane-row {
     position: absolute; left: 0; right: 0; display: flex; align-items: center;
-    gap: 3px; padding-right: 6px; box-sizing: border-box;
+    gap: 6px; padding-right: 6px; box-sizing: border-box;
   }
   .ed-wave-lane-row.is-selected { background: #eaf2fe; }
-  /* v3.5.0 Task 12: Shift+click multi-select for group creation — a
-     distinct tint from .is-selected above (that one is the CYCLE selection
-     the brush/cycle-ops toolbar acts on; this one is a SET of whole lanes
-     the group buttons act on, and a user with both standing at once — a
-     cycle range selected on a lane that is also multi-selected for
-     grouping — needs to tell which is which at a glance). A lane can carry
-     both classes together, so this is additive (a left border) rather than
-     a second background that would just overwrite .is-selected's. */
-  .ed-wave-lane-row.is-multi-selected { border-left: 3px solid #7c3aed; }
-  .ed-wave-lane-name { flex: 1 1 auto; min-width: 0; font-size: 12px; padding: 2px 4px; }
-  .ed-wave-lane-row button {
-    border: 1px solid #cfcfcf; border-radius: 3px; background: #fff;
-    font-size: 11px; line-height: 1; padding: 3px 4px; cursor: pointer;
-  }
-  .ed-wave-lane-row button:disabled { opacity: .4; cursor: default; }
-  .ed-wave-lane-add-tail { position: absolute; left: 6px; }
+  .ed-wave-lane-handle {
+    flex: 0 0 auto; cursor: grab; color: #aaa; user-select: none; font-size: 13px;
+  }
+  .ed-wave-lane-handle:active { cursor: grabbing; }
+  /* min-width, not just flex-grow: min-width is what a flex item will not
+     shrink past, and shrinking past it is the vertical-text failure above.
+     MEASURED after this change (real page, 800x600, the journey suite's own
+     wave fixture): rail 201px, handle 9.5px, badge 36px, and the field comes
+     out 178.5px ungrouped, 162.5px one group deep, 136.5px on the {} spacer
+     row that also carries the badge — writing-mode horizontal-tb on all six.
+     So 120 is slack at every depth this fixture reaches, NOT a computed
+     exact fit. Deeper nesting spends 16px a level and would eventually hit
+     the floor; there the field stops shrinking and .ed-wave-lanes scrolls,
+     which is the trade this rule chooses on purpose. */
+  .ed-wave-lane-name {
+    flex: 1 1 auto; min-width: 120px; font-size: 12px; padding: 2px 4px;
+  }
+  .ed-wave-lane-badge { flex: 0 0 auto; font-size: 10px; color: #888; }
   .ed-wave-group, .ed-wave-group-input {
     position: absolute; width: 14px; padding: 0; font-size: 11px;
     writing-mode: vertical-rl; text-orientation: mixed; overflow: hidden;
@@ -1775,6 +1849,14 @@ ${itemsHtml}
   }
   .ed-wave-grid { stroke: #ececec; stroke-width: 1; }
   .ed-wave-line, .ed-wave-edge { stroke: #111; stroke-width: 2; fill: none; }
+  /* v3.6.0 Task 10: the toolbar glyph's plain-level backbone (0/1/h/l/z/u/d
+     only -- bus/clock/x/gap glyphs draw their own shape with their own
+     fixed canvas colour instead, further down). Declared after the rule
+     above on purpose: both are single-class selectors, so source order is
+     what lets currentColor win over the fixed #111 for this one case,
+     turning the icon white together with the rest of the button's text
+     under .ed-wave-brush.is-on. */
+  .ed-wave-level-icon-path { stroke: currentColor; }
   .ed-wave-weak { stroke-dasharray: 4 3; }
   /* v3.5.0 Task 10: the P/N explicit-edge arrowhead — see wave-ui.js's
      drawLane isClock branch for the measurement behind its shape and
@@ -1885,6 +1967,38 @@ ${itemsHtml}
      untouched no matter what class it shares. */
   text.ed-wave-edge-label { pointer-events: none; }
   .ed-wave-edge-label { font-size: 11px; fill: #333; }
+  /* v3.6.0 Task 8: the canvas's own name column — a mirror of the rail's
+     .ed-wave-lane-name / .ed-wave-group (see the comment above
+     .ed-wave-lane-rows). Unlike .ed-wave-edge-label these two class names
+     are not shared with any non-SVG control, so pointer-events: none goes
+     straight on the class rather than needing the element-scoped selector
+     that rule uses. MEASURED (task-8-report.md): the longest lane name in
+     this repo's fixtures is 12 chars ("he said \"hi\""), which at 11px in
+     both the app's default sans-serif and the worst case (monospace)
+     measures well under the 110px a top-level name has to fit in
+     (nameColWidth 120 - NAME_GAP 10), so SIZES.nameColWidth stays 120. */
+  .ed-wave-lane-label, .ed-wave-group-label { pointer-events: none; }
+  .ed-wave-lane-label { font-size: 11px; fill: #333; }
+  .ed-wave-group-label {
+    font-size: 11px; fill: #555; writing-mode: vertical-rl; text-orientation: mixed;
+  }
+  /* v3.6.0 Task 9: the cycle ruler and the head/foot bands — see
+     wave-draw.js's drawRuler()/drawBand() comment for the geometry (tick on
+     boundaries, tock at centres, both filtered by every) and why this is
+     read-only with respect to the document. Purely decorative like the name
+     column above it, so pointer-events: none on the same principle. The
+     ruler's own fill matches the pinned engine's own muted class (fill
+     #aaa, node_modules/wavedrom's waveSkin CSS) so a tick/tock painted here
+     reads the same shade as the identical mark in the WaveDrom preview
+     beside it; the head/foot titles use the darker ed-wave-lane-label shade
+     instead, matching the engine's own plain black fill for head.text /
+     foot.text closely enough at this scale without introducing a third
+     grey. */
+  .ed-wave-ruler-tick, .ed-wave-ruler-tock, .ed-wave-head-text, .ed-wave-foot-text {
+    pointer-events: none;
+  }
+  .ed-wave-ruler-tick, .ed-wave-ruler-tock { font-size: 11px; fill: #aaa; }
+  .ed-wave-head-text, .ed-wave-foot-text { font-size: 11px; fill: #333; }
   .ed-wave-edge-handle { fill: #1a73e8; stroke: #ffffff; }
   .ed-wave-edge-arrow { fill: #0041c4; }
   .ed-wave-edge-tee { stroke: #0041c4; }
@@ -1897,11 +2011,113 @@ ${itemsHtml}
     stroke: #1a73e8; stroke-width: 2; stroke-dasharray: 5 4; fill: none;
     pointer-events: none;
   }
-  .ed-wave-preview {
-    flex: 0 1 340px; min-width: 160px; border-left: 1px solid #e2e2e2;
-    overflow: auto; padding: 8px;
-  }
+  /* v3.6.0 Task 11: the transition dots wave-draw.js's drawTransitions()
+     paints while edge-creation is armed -- the visual answer to "where can
+     I aim". pointer-events: none for the same reason ed-wave-selection and
+     the other UI-state marks above are: the actual hit-testing runs through
+     geometry.boundaryAt against the pointer's raw coordinates
+     (wave-ui.js's cellFromEvent/onCanvasHover), never through this circle
+     as a DOM target, so it must never itself swallow the press it exists
+     to help aim. The [data-hot] variant is the same dot, larger and
+     filled solid, for the one nearest the pointer right now
+     (state.hoverBoundary in drawTransitions). */
+  .ed-wave-transition {
+    fill: #ffffff; stroke: #1a73e8; stroke-width: 1.5; pointer-events: none;
+  }
+  .ed-wave-transition[data-hot] { fill: #1a73e8; stroke: #0041c4; }
+  /* v3.6.0 Task 13: the old flex-basis/border/padding here were for
+     .ed-wave-preview as a direct flex child of .ed-wave-body; it now
+     lives inside .ed-wave-section-body (the 預覽 panel), which already
+     supplies the column width and padding, so only its own scroll behaviour
+     is left to set — a wide diagram's preview SVG must scroll within the
+     panel rather than stretching the whole 340px column. */
+  .ed-wave-preview { overflow: auto; max-height: 260px; }
   .ed-wave-preview-label { font-size: 11px; color: #666; margin-bottom: 6px; }
+  /* v3.6.0 Task 13: the right-hand column — five collapsible panels
+     (關聯線/文件/Lane/預覽/原始碼) replacing the old direct
+     .ed-wave-preview column. 'flex: 0 0 340px' (not '0 1'): unlike the
+     old preview column, this one does not shrink when the canvas wants
+     more room — width-budget wins go through .ed-wave-panel's own cap
+     above, not by starving this column, because starving it re-introduces
+     the exact 160px-minimum squeeze this task's own .ed-wave-lanes
+     comment measured as the 800x600 defect. Below 1100px it collapses to a
+     28px rail instead (media query below) for the identical reason. */
+  /* v3.6.0 Task 13 fix round 4: box-sizing: border-box added. wave-ui.js's
+     clearSelectedEdgeOfSide() sets an inline width (in border-box, i.e.
+     rendered, pixels — the same unit getBoundingClientRect() reports
+     everywhere else it measures this element) to keep the selected edge's
+     own handle clear of this panel when expanded. Under the default
+     content-box sizing, width excludes padding (16px) and the border
+     (1px), so a JS-computed width landed 17px narrower on screen than
+     intended — MEASURED, not assumed: an inline width of 310px rendered at
+     327px. border-box makes width mean the same thing in CSS and in
+     getBoundingClientRect(), so the two agree without wave-ui.js having to
+     hardcode this rule's own padding/border numbers into its arithmetic. */
+  .ed-wave-side {
+    box-sizing: border-box; flex: 0 0 340px; border-left: 1px solid #e2e2e2;
+    overflow: auto; padding: 8px; display: flex; flex-direction: column; gap: 8px;
+  }
+  .ed-wave-section { border: 1px solid #ececec; border-radius: 6px; }
+  .ed-wave-section-title {
+    display: block; width: 100%; text-align: left; border: 0; background: #fafafa;
+    font: inherit; font-size: 11px; letter-spacing: .5px; color: #555;
+    padding: 5px 8px; cursor: pointer; border-radius: 6px 6px 0 0;
+  }
+  .ed-wave-section-body { display: none; padding: 8px; }
+  /* v3.6.0 Task 13 fix round 3: data-open is this SECTION's own toggle
+     state (wave-panels.js's section()) and says NOTHING about whether the
+     RAIL is currently showing it — those are two independent attributes on
+     two different elements. A section can report data-open with a
+     zero-size, unhittable body the whole time .ed-wave-side itself is
+     collapsed to its <1100px 28px rail (below): 關聯線/文件/Lane all default
+     data-open, and none of that changes just because the rail hides them.
+     Left deliberately this way rather than making data-open track actual
+     visibility — that would conflate "this section is open" with "the rail
+     happens to be showing right now", and toggling ONE section would then
+     have to silently relabel every OTHER already-open section's own state
+     too. What actually closes the gap this could otherwise leave (a control
+     that LOOKS reachable in the DOM but is not) is wave-ui.js's render()
+     expanding the rail on the one transition that matters (selecting an
+     edge) rather than this attribute pretending to mean something it does
+     not. */
+  .ed-wave-section[data-open] .ed-wave-section-body { display: block; }
+  .ed-wave-section-body label { display: flex; align-items: center; gap: 6px; margin: 4px 0; }
+  .ed-wave-section-body label span { flex: 0 0 96px; font-size: 12px; color: #555; }
+  .ed-wave-section-body input {
+    flex: 1 1 auto; min-width: 0; font-size: 12px; padding: 2px 4px;
+  }
+  .ed-wave-source {
+    margin: 0; font-size: 11px; line-height: 1.45; white-space: pre;
+    overflow: auto; max-height: 260px;
+  }
+  /* 視窗窄於這條線時右欄收成一條直立標籤，展開時覆蓋在畫布上 —— 否則
+     800x600 的測試視窗下畫布會被 340px 固定寬的側欄吃掉大半，拖曳手勢會
+     不可用（v3.6.0 Task 13 自己的 .ed-wave-lanes 註解量到的舊值：只剩
+     282px）。收起時仍是普通文件流寬度（28px），展開時疊在畫布上方而不擠
+     壓它。data-expanded 有三個來源：wave-panels.js 的 section() 點擊 title、
+     同檔案的 collapseBtn 反過來移除它、以及 fix round 3 新增的
+     wave-panels.js 的 expandSide()（由 wave-ui.js 的 render() 在
+     selectedEdge 從 null 變成有值的那一拍呼叫——選取一條 edge 之後，
+     整個回饋只長在這個側欄的關聯線面板裡，窄視窗下不展開就等於使用者
+     什麼都看不到、也按不到）。 */
+  /* v3.6.0 Task 13 fix round 1: the collapse-back button. Hidden everywhere
+     except the one state it exists for — the <1100px rail, expanded — so it
+     never shows, and never sits in the tab order, at a wide viewport or in
+     the rail's own default collapsed state. */
+  .ed-wave-side-collapse { display: none; }
+  @media (max-width: 1100px) {
+    .ed-wave-side { flex: 0 0 28px; padding: 4px 2px; }
+    .ed-wave-side:not([data-expanded]) .ed-wave-section-body { display: none; }
+    .ed-wave-side[data-expanded] {
+      position: absolute; right: 0; top: 0; bottom: 0; width: 340px;
+      background: #ffffff; z-index: 3; flex: 0 0 340px; padding: 8px;
+    }
+    .ed-wave-side[data-expanded] .ed-wave-side-collapse {
+      display: block; width: 100%; text-align: right; border: 0;
+      background: transparent; font-size: 12px; color: #555; cursor: pointer;
+      padding: 2px 4px 6px;
+    }
+  }
   .ed-wave-status {
     border-top: 1px solid #e2e2e2; padding: 6px 12px; font-size: 12px;
     color: #444; min-height: 18px;
@@ -2532,6 +2748,32 @@ ${usesDrawio ? `  /* v3.4.0 §4: a document with no drawio reference must not pa
     height: auto;
     margin: 0 auto;
   }
+  /* A diagram wide enough that fitting it makes its own labels unreadable is
+     drawn at natural size in a scroll box instead. The verdict is never "is
+     this a waveform" -- it is "how small does fitting make the smallest
+     glyph", because the damage is proportional to the aspect ratio. MEASURED,
+     918px column: an 8-node flowchart fits at 0.71 and still draws 11.4px
+     labels, while a 60-cycle waveform fits at 0.37 and draws 5.4px ones.
+     applyDiagramScale() in the reader runtime below measures that and is the
+     only thing that adds this class. The margin override is there because the
+     ".content svg" rule centres with auto margins, which has nothing to
+     centre once the svg is wider than the box.
+     Source order is load-bearing: ".diagram-scroll > svg" and the
+     ".content svg" rule above are both (0,1,1), so this wins only by coming
+     after it. The child combinator matches the JS, which looks for the host's
+     own ":scope > svg" -- one rule, stated twice, deliberately identically.
+     One thing this rule does that it does not say: setting ONE axis to
+     something other than visible promotes the OTHER axis to auto as well, per
+     the CSS overflow spec, so every host here is a clipping block formatting
+     context in BOTH directions. MEASURED on the three-engine fixture: all
+     three scrolling hosts report a computed overflow-y of "auto" although only
+     overflow-x is written, and all three have scrollHeight === clientHeight,
+     so nothing is being clipped today. Recorded because a diagram that one day
+     overflows VERTICALLY inside its host would be silently cut rather than
+     overhanging, and neither this rule nor the tests would say why.
+     (No backticks in this comment: it lives inside a JS template literal.) */
+  .diagram-scroll { overflow-x: auto; }
+  .diagram-scroll > svg { max-width: none; margin: 0; }
   /* Anything the reader can pop out. The click handler uses the same
      selectors, so this cursor and that behaviour cannot drift apart. */
   .content img,
@@ -2723,6 +2965,20 @@ ${usesDrawio ? `  /* v3.4.0 §4: a document with no drawio reference must not pa
   }
   @media print {
     body { font-size: 11pt; }
+    /* No scrollbars in a PDF, so an unscaled diagram there is not a
+       scrollable one -- it is a clipped one, and half a waveform is worse
+       than a small one. Hand it back to shrink-to-fit. Same (0,1,1) tie as
+       the base rule, won the same way: source order.
+       The !important is not decoration and was MEASURED: mermaid writes its
+       own style="max-width: <natural>px" onto the svg element, and an inline
+       declaration beats any rule in here regardless of specificity, so the
+       plain version of this line clamped nothing and the first PDF built from
+       it came out with a 16-stage flowchart cut off after Stage 3.
+       applyDiagramScale's inline width is clamped by the same declaration --
+       a max-width always beats a width -- so the runtime needs no print
+       branch of its own. */
+    .diagram-scroll { overflow-x: visible; }
+    .diagram-scroll > svg { max-width: 100% !important; height: auto; }
     .page-layout {
       display: block;
       max-width: 100%;
@@ -4258,9 +4514,223 @@ ${usesDrawioMultiPage ? `  // v3.4.0 batch2 Task 6: wired through a NAMED, reusa
 ` : ''}
   // ── Diagram / image lightbox ──────────────────────────────────────────────
   // Specs are read at 100% but their block diagrams and waveforms are drawn far
-  // wider than the column, so the inline copy is unreadably small. Clicking one
-  // pops it into a modal stage that zooms and scrolls.
+  // wider than the column, so the inline copy is shrunk to fit. Clicking one
+  // pops it into a modal stage that zooms and scrolls. Past a point shrinking
+  // stops being an acceptable inline copy at all -- that floor, and what the
+  // inline copy does instead below it, is the block right after this one, and
+  // the two share LIGHTBOX_TARGETS so they can never disagree about what
+  // counts as a diagram.
   var LIGHTBOX_TARGETS = 'img, .mermaid, .graphviz, .drawio, [id^="WaveDrom_Display_"], .wavedrom-diagram';
+
+  // ── Readability floor ─────────────────────────────────────────────────────
+  //
+  // The lightbox above is the escape hatch for a diagram drawn wider than the
+  // column. This is the other half: the inline copy has to be worth reading in
+  // the first place. ".content svg { max-width: 100% }" shrinks to fit and
+  // never looks at how small it is making the text, and the damage grows with
+  // the aspect ratio, so past some width the reader is handed a picture of a
+  // waveform rather than a waveform.
+  //
+  // MEASURED on this branch, 1280x900 viewport, .content clientWidth 918, the
+  // waveform skin's own labels at 11pt = 14.667px: a 60-cycle waveform is
+  // 2480px natural, fits at scale 0.370, and its labels land at 5.43px, where
+  // "clk" and "data" are smudges. The identical expression leaves an 8-node
+  // flowchart alone (1287px natural, fits at 0.714, labels at 11.41px), which
+  // is the whole point -- the trigger is the measured glyph size, not which
+  // engine drew the diagram.
+  //
+  // This block ships in EVERY document, including diagram-free ones, and
+  // test/md2doc.test.js asserts that such a document carries no diagram-engine
+  // runtime. So engines may be named here in prose only, never by the global,
+  // skin or probe identifiers the engines themselves define -- that guard
+  // greps for those, and it cannot tell a comment from code.
+  //
+  // The floor was measured, not estimated. Eight widths were rendered and
+  // screenshotted one per row at deviceScaleFactor 1 and read: 9.35px was the
+  // last comfortable row, 8.86px was where lowercase labels start breaking up.
+  // The full table lives in test/reader-panels.test.js section 5, beside the
+  // assertions that bracket this number from both sides.
+  var DIAGRAM_FONT_FLOOR = 9;
+
+  // The width the diagram was drawn at, in the SAME units diagramMinFontPx
+  // reports -- the svg's own user units. The pairing is the whole point: the
+  // rendered size of a glyph is its computed font-size times (rendered width /
+  // this), so the two must not be measured in different coordinate systems.
+  //
+  // That is why the viewBox comes first and the width attribute is only the
+  // fallback for an svg that has none (where user units are CSS px anyway).
+  // MEASURED, three engines, three different width attributes for the same
+  // idea: the waveform engine writes width="2480" (equal to its viewBox, so
+  // the order does not matter), mermaid writes width="100%" and keeps the real
+  // number in the viewBox ("0 0 6838.25 70" for a 40-node flowchart), and the
+  // graph engine writes width="4069pt" against a 4069-unit viewBox. Reading
+  // the attribute first gives 100 for every mermaid diagram -- which reads as
+  // "already fits", so the floor silently never applies to any of them -- and
+  // mixes points into a ratio of pixels for the graph one.
+  function diagramNaturalWidth(svg) {
+    var viewBox = svg.getAttribute('viewBox');
+    if (viewBox) {
+      // The doubled backslashes are not a typo and node --check will not miss
+      // them for you: this whole runtime is emitted from a JS template
+      // literal, where "\\s" is an unrecognised escape that collapses to a
+      // bare "s". This split really did ship as /[s,]+/ once, which parsed
+      // "0 0 6838.25 70" as a single token, returned 0, and turned the
+      // non-waveform half of this feature into a silent no-op. Precedent: the
+      // normaliseText helper above spells the same thing /\\s+/g.
+      var vw = parseFloat(viewBox.split(/[\\s,]+/)[2]);
+      if (vw > 0) return vw;
+    }
+    var attr = svg.getAttribute('width');
+    if (attr && /^\\s*[0-9.]+(px)?\\s*$/.test(attr)) {
+      var px = parseFloat(attr);
+      if (px > 0) return px;
+    }
+    return 0;
+  }
+
+  // The smallest glyph the diagram draws, in those same user units -- an svg's
+  // computed font-size does not move when its viewBox is scaled, so the size
+  // on screen is this times the fit scale.
+  //
+  // Also MEASURED rather than assumed: mermaid's default label is not an svg
+  // <text> at all, it is an html <span> inside a <foreignObject> (79 of them
+  // in the flowchart above, and zero <text> nodes), so a text-only query
+  // returns Infinity for a mermaid diagram and hands it the same free pass.
+  // Only a node that really carries a text node is counted; the font-size of
+  // an empty wrapper is a number nobody can see.
+  function diagramMinFontPx(svg) {
+    var min = Infinity;
+    var nodes = svg.querySelectorAll('text, tspan, foreignObject *');
+    for (var i = 0; i < nodes.length; i++) {
+      var node = nodes[i];
+      var carriesText = false;
+      for (var child = node.firstChild; child; child = child.nextSibling) {
+        // .trim() rather than a /\\S/ test: one less escape to get wrong in a
+        // template literal, and it says the same thing.
+        if (child.nodeType === 3 && child.nodeValue.trim()) { carriesText = true; break; }
+      }
+      if (!carriesText) continue;
+      var size = parseFloat(window.getComputedStyle(node).fontSize);
+      if (isFinite(size) && size > 0 && size < min) min = size;
+    }
+    return min;
+  }
+
+  function applyDiagramScale() {
+    var nodes = document.querySelectorAll(LIGHTBOX_TARGETS);
+    for (var i = 0; i < nodes.length; i++) {
+      var host = nodes[i];
+      // ":scope > svg" is the same relationship ".diagram-scroll > svg" in the
+      // stylesheet asks for -- one rule, written twice, deliberately
+      // identically. An <img> target has no svg and no text to measure, and
+      // neither do the empty duplicate display divs the waveform engine's
+      // repeated render passes leave behind.
+      var svg = host.querySelector ? host.querySelector(':scope > svg') : null;
+      if (!svg) continue;
+      var natural = diagramNaturalWidth(svg);
+      if (!natural) continue;
+      // Always measure the FITTED geometry, never geometry a previous pass
+      // produced. Clearing the inline width is half of that and matters on its
+      // own: a mermaid svg is width="100%", so lifting max-width would leave it
+      // exactly as wide as the column it is supposed to be escaping.
+      host.classList.remove('diagram-scroll');
+      svg.style.width = '';
+      var avail = host.clientWidth;
+      if (!avail) continue;
+      var scale = avail / natural;
+      if (scale >= 1) continue;
+      var minFont = diagramMinFontPx(svg);
+      if (!isFinite(minFont)) continue;
+      if (minFont * scale >= DIAGRAM_FONT_FLOOR) continue;
+      host.classList.add('diagram-scroll');
+      // max-width alone is enough for a diagram that states its width in px
+      // and not enough for one that states it in percent, so both get the
+      // number explicitly. @media print is unaffected: a max-width always
+      // beats a width, which is what lets the print rule hand these back to
+      // shrink-to-fit without this line having to know about it.
+      svg.style.width = natural + 'px';
+    }
+  }
+
+  // When to re-run. Two inputs move after this script executes: whether the
+  // diagram exists yet, and how wide the column is.
+  //
+  // The waveform engine's own render pass is scheduled four times
+  // (DOMContentLoaded, load, +250ms, +1000ms) and mermaid renders on its own
+  // clock, so an svg can appear long after this line. The MutationObserver is
+  // deliberately not a copy of those timings -- a copy goes stale the first
+  // time either engine changes its schedule, and silently: a pass that runs
+  // before the svg exists looks exactly like a pass that decided to do
+  // nothing. It only wakes for an
+  // insertion that actually brought an svg, so edit-mode typing does not pay
+  // for it, and it cannot self-trigger because adding the class is an
+  // attribute mutation, not a childList one.
+  //
+  // The column width moves on a window resize, on crossing the 1080px drawer
+  // breakpoint and on a sidebar-splitter drag. A ResizeObserver on .content
+  // sees all three; a window resize listener sees only the first, which is why
+  // there is no hand-placed call at the end of the sidebar handlers. Toggling
+  // the class changes the host's HEIGHT (a scrollbar appears) and that feeds
+  // back into the same observer, so a pass only runs when the width moved.
+  var diagramScaleFrame = 0;
+  function scheduleDiagramScale() {
+    if (diagramScaleFrame) return;
+    diagramScaleFrame = window.requestAnimationFrame(function () {
+      diagramScaleFrame = 0;
+      applyDiagramScale();
+    });
+  }
+  applyDiagramScale();
+  window.addEventListener('DOMContentLoaded', scheduleDiagramScale);
+  window.addEventListener('load', scheduleDiagramScale);
+  if (contentEl && typeof MutationObserver === 'function') {
+    new MutationObserver(function (records) {
+      for (var r = 0; r < records.length; r++) {
+        var added = records[r].addedNodes;
+        for (var a = 0; a < added.length; a++) {
+          var node = added[a];
+          if (!node || node.nodeType !== 1) continue;
+          if (node.tagName.toLowerCase() === 'svg' ||
+              (node.querySelector && node.querySelector('svg'))) {
+            scheduleDiagramScale();
+            return;
+          }
+        }
+      }
+    }).observe(contentEl, { childList: true, subtree: true });
+  }
+  if (contentEl && typeof ResizeObserver === 'function') {
+    // KNOWN RISK, and honestly not measurable in this environment.
+    //
+    // On a platform with CLASSIC (space-taking) scrollbars rather than overlay
+    // ones, adding the class makes the page taller -- the svg goes to natural
+    // size and keeps height: auto -- and a page that gains a vertical
+    // scrollbar loses about 15px of column width to it. That re-runs the
+    // verdict at a narrower width, which can flip a diagram sitting close to
+    // the floor back the other way, which makes the page shorter again. The
+    // guard below is "the width changed", and the width is exactly what moves
+    // in that loop, so the guard does not damp it.
+    //
+    // Not reproducible here: this environment only ever produces overlay
+    // scrollbars (clientHeight === offsetHeight on a scrolling host, and
+    // launching with the overlay-scrollbar features disabled changes nothing),
+    // so neither the oscillation nor a fix for it can be observed -- and an
+    // unmeasurable fix is how a worse bug gets shipped. Left alone on purpose.
+    // The worst case is a busy loop rather than a hang, because
+    // scheduleDiagramScale coalesces onto one animation frame. If it is ever
+    // reproduced, the damping to reach for is hysteresis on the decision (two
+    // thresholds instead of one), not a looser equality test on the width.
+    var lastDiagramColW = -1;
+    new ResizeObserver(function () {
+      var w = contentEl.clientWidth;
+      if (w === lastDiagramColW) return;
+      lastDiagramColW = w;
+      scheduleDiagramScale();
+    }).observe(contentEl);
+  } else {
+    window.addEventListener('resize', scheduleDiagramScale);
+  }
+
   var LIGHTBOX_MIN_ZOOM = 0.05;
   var LIGHTBOX_MAX_ZOOM = 8;
   var LIGHTBOX_STEP = 1.25;