@helping-ai-workflow/md2doc 3.4.2 → 3.6.0

package/lib/editor/wave-geometry.js

@@ -44,6 +44,64 @@
 
 const codec = require('./wave-codec.js');
 
+/**
+ * MEASURED against `node_modules/wavedrom` 3.5.0 (`node_modules/wavedrom/package.json`
+ * `"version"`), by reading its `waveSkin` object directly in Node:
+ *
+ *   - socket: `["g",{"id":"socket"},["rect",{"y":"15","x":"6","height":"20","width":"20"}]]`.
+ *     A brick is `width` wide (20), a cycle is two bricks (40), and the engine
+ *     anchors a `node` marker at the socket rect's `x` — so `anchorRatio` is
+ *     `6 / 40 = 0.15`.
+ *   - transition brick `0m1` — a REAL 0->1 change. Measure the ramp from
+ *     THIS brick, not from `0m0`: the id looks similar, but `0m0` is a
+ *     same-LEVEL blip (a down-and-back notch that never changes level) and
+ *     is not a transition at all.
+ *     `["g",{"id":"0m1"},["path",{"d":"M0,20 3,20 9,0 20,0", …}]]`, i.e.
+ *     absolute points `(0,20)->(3,20)->(9,0)->(20,0)`. The flat lead-in at
+ *     the old level ends at x=3, so `slewStartRatio` is `3 / 40 = 0.075`;
+ *     the diagonal reaches the new level at x=9, so `slewEndRatio` is
+ *     `9 / 40 = 0.225`. Cross-checked against `1m0` (1->0):
+ *     `["g",{"id":"1m0"},["path",{"d":"m0,0 3,0 6,20 11,0", …}]]` (relative
+ *     coordinates, resolving to `(0,0)->(3,0)->(9,20)->(20,20)`) — the same
+ *     3-to-9 span, mirrored.
+ *   - `anchorRatio` (0.15, x=6) is neither ramp endpoint — it is the ramp's
+ *     MIDPOINT: `(slewStartRatio + slewEndRatio) / 2 === (0.075+0.225)/2
+ *     === 0.15`. That is the transition's 50% crossing, which is why the
+ *     engine anchors an annotation there rather than at either edge of the
+ *     ramp.
+ *   - Cross-checked end-to-end: rendering `{signal:[{wave:'0.1.0...',node:'a.b.c...'}],
+ *     edge:['a-b']}` through `wavedrom.renderAny` puts the `gmark_a_b` path's
+ *     endpoints at `cycle * 40 + 0.15 * 40` for both cycle 0 (`a`) and cycle 2
+ *     (`b`) — see `test/wave-geometry.test.js`'s SKIN_METRICS block, which
+ *     re-derives these same three ratios from `waveSkin` (from `0m1`,
+ *     cross-checked against `1m0` — not from `0m0`) and re-runs this exact
+ *     render, so a wavedrom bump that moves the skin turns that test red and
+ *     names the number to re-pin.
+ *
+ * v3.6.0 Task 7 fix round 1 (ruling R23): `slewEndRatio` was originally
+ * pinned at 0.15 (`=== anchorRatio`) on the belief that the ramp finishes
+ * exactly where the anchor sits. It does not: that belief was measured
+ * against `0m0`, whose down-and-back peak coincidentally lands on the same
+ * x as the anchor while telling you nothing about where a REAL transition's
+ * ramp ends. Repinned to the measured 0.225 above once `0m1`/`1m0` (the
+ * actual transition bricks) were read instead.
+ *
+ * Pinned rather than derived at module load: this file cannot pull in the
+ * `wavedrom` package itself. In the browser, `lib/editor/server.js`'s CommonJS
+ * shim resolves that same import against a page-global registry keyed by module
+ * basename, and the shipped `wavedrom.min.js` bundle only attaches `ProcessAll` /
+ * `RenderWaveForm` / `EditorRefresh` / `eva` / `version` to that page global — no
+ * `waveSkin` — so a page-time derivation would read `undefined` on every real
+ * page, not just as a rare fallback. The tests, which run in Node against the
+ * real npm package, are where the derivation actually happens and where a
+ * version bump would be caught.
+ */
+const SKIN_METRICS = Object.freeze({
+  anchorRatio: 0.15,
+  slewStartRatio: 0.075,
+  slewEndRatio: 0.225,
+});
+
 /**
  * Sizes to use when the caller has nothing better, read out of the engine's own
  * `lane` module after a render rather than inferred: `lane.yo` (row pitch) is
@@ -59,6 +117,47 @@ const codec = require('./wave-codec.js');
  */
 const DEFAULTS = { laneHeight: 30, cycleWidth: 40, nameColWidth: 40 };
 
+/**
+ * v3.6.0 Task 6: the decorated bands above lane 0 — a ruler (always), an
+ * optional head-title band, and an optional foot-tick band below the last
+ * lane.
+ *
+ * v3.6.0 Task 9 fix round 1 (ruling R29): foot now gets a SECOND stacked
+ * band too, mirroring head's own two — `parse-config.js` sets `yf0 = 20`
+ * for a foot `tick`/`tock` and `yf1 = 46` for a foot `text`, the exact
+ * mirror of `yh0`/`yh1` for head, and both are legal at once in real
+ * WaveJSON. Before this fix `footHeight` was one band shared by text AND
+ * ticks, so a document setting both drew them on top of each other.
+ *
+ * 22 / 20 are layout constants, not derived from the engine: the engine's own
+ * canvas carries its own margin for this, and this editor's canvas only needs
+ * to reserve enough room to paint a row of 11px numerals (ruler) or a title
+ * (head text) without clipping it. `RULER_HEIGHT` and `FOOT_HEIGHT` are the
+ * same 22 because a foot band draws the same kind of tick row the ruler does,
+ * just below the last lane instead of above the first, and `FOOT_TEXT_HEIGHT`
+ * matches `HEAD_TEXT_HEIGHT` (20) for the same reason. It is the STRUCTURE —
+ * two stacked bands per side, not one shared band — that has to mirror the
+ * engine, never the pixel counts: the engine's own 46 for a text band is not
+ * a target to hit here, do not "correct" 20 to it.
+ */
+const RULER_HEIGHT = 22;
+const HEAD_TEXT_HEIGHT = 20;
+const FOOT_HEIGHT = 22;
+const FOOT_TEXT_HEIGHT = 20;
+
+/**
+ * Whether `doc[which]` (`'head'` or `'foot'`) is a WaveJSON banner object —
+ * any of the four keys the engine draws something for. A banner with none of
+ * these keys draws nothing, so it does not reserve a band either.
+ */
+function hasBanner(doc, which) {
+  if (doc === null || typeof doc !== 'object') return false;
+  const b = doc[which];
+  if (b === null || typeof b !== 'object') return false;
+  return b.text !== undefined || b.tick !== undefined ||
+    b.tock !== undefined || b.every !== undefined;
+}
+
 /**
  * How many lanes are laid out before the rest are dropped.
  *
@@ -185,42 +284,190 @@ function cyclesOf(lane) {
  * overflow `width` to Infinity. Both are outside anything `getBoundingClientRect`
  * can report, and neither is defended against here.
  */
+/**
+ * `config.hscale`, normalized exactly the way the pinned engine's own
+ * `parseConfig` does it (`node_modules/wavedrom/lib/parse-config.js:4-21`,
+ * measured this session): `tonumber(x) = x > 0 ? Math.round(x) : 1`, rounded
+ * a second time, then clamped to 100. So `hscale: 2.5` renders as **3** in
+ * the engine, not 2.5, and `hscale: 250` clamps to **100** — a caller that
+ * skipped this and used the raw value would draw a canvas that disagrees
+ * with the engine's own preview, which is the exact defect class v3.6.0
+ * exists to remove (v3.6.0 Task 4 fix round 1, R15).
+ *
+ * A value that rounds to 0 or below (the engine's own `tonumber` maps every
+ * non-positive input to 1, and `Math.round(0.4)` is 0) is the engine's
+ * default of 1, same as a missing or non-numeric `hscale` — this is not an
+ * error, `config` is user data and a hand-edited stray value must still lay
+ * out rather than take the editor down.
+ */
+function hscaleOf(cfg) {
+  if (cfg === null || typeof cfg.hscale !== 'number' || !isFinite(cfg.hscale) ||
+      cfg.hscale <= 0) {
+    return 1;
+  }
+  const rounded = Math.round(cfg.hscale);
+  if (rounded <= 0) return 1;
+  return rounded > 100 ? 100 : rounded;
+}
+
 function layoutOf(doc, opts) {
   const o = options(opts);
   const laneHeight = size(o.laneHeight, DEFAULTS.laneHeight, 'laneHeight', false);
   const cycleWidth = size(o.cycleWidth, DEFAULTS.cycleWidth, 'cycleWidth', false);
   const nameColWidth = size(o.nameColWidth, DEFAULTS.nameColWidth, 'nameColWidth', true);
 
+  // `config.hscale` scales every lane's cycle width the same way the engine's
+  // own `lane.hscale` does — see `hscaleOf` for the exact rounding/clamping
+  // this mirrors.
+  const cfg = (doc !== null && typeof doc === 'object' &&
+    doc.config !== null && typeof doc.config === 'object') ? doc.config : null;
+  const hscale = hscaleOf(cfg);
+
+  // v3.6.0 Task 6: the ruler band always reserves room; a head.text banner
+  // adds a title band above it; lane 0 starts below both.
+  const headTextHeight = (doc !== null && typeof doc === 'object' &&
+    doc.head !== null && typeof doc.head === 'object' &&
+    doc.head.text !== undefined) ? HEAD_TEXT_HEIGHT : 0;
+  const originY = headTextHeight + RULER_HEIGHT;
+  const footHeight = hasBanner(doc, 'foot') ? FOOT_HEIGHT : 0;
+  // v3.6.0 Task 9 fix round 1 (R29): stacked BELOW `footHeight`, mirroring
+  // `headTextHeight` stacked ABOVE `RULER_HEIGHT` — `footHeight` alone still
+  // covers a foot with only `tick`/`tock`/`every` (untouched: a document
+  // that sets none of those keeps `footTextHeight` at 0 and its `height`
+  // pin does not move), and this adds the second band only when `foot.text`
+  // is actually present, exactly the condition `headTextHeight` already
+  // uses for `head.text`.
+  const footTextHeight = (doc !== null && typeof doc === 'object' &&
+    doc.foot !== null && typeof doc.foot === 'object' &&
+    doc.foot.text !== undefined) ? FOOT_TEXT_HEIGHT : 0;
+
   const found = enumerateLanes(doc);
   const lanes = [];
   let cycles = 0;
   for (let i = 0; i < found.lanes.length; i++) {
     const laneCycles = cyclesOf(found.lanes[i].lane);
     if (laneCycles > cycles) cycles = laneCycles;
+    const lane = found.lanes[i].lane;
+    // A wave character spans `period` diagram cycles, and the whole lane is
+    // then scaled by `hscale`. `phase` only shifts the origin, and by the
+    // BASE cycle width, not the effective one — the engine's own expression
+    // is `xs * (2*i*period*hscale - phase)`, and that `phase` term is never
+    // multiplied by hscale (measured in node_modules/wavedrom/lib/render-arcs.js).
+    const laneObj = (lane !== null && typeof lane === 'object') ? lane : {};
+    // Deliberate divergence from the engine (R15): the engine's own
+    // `element.period ? element.period : 1` passes a negative value straight
+    // through, which the renderer then turns into a negative pixel width.
+    // Here a non-positive `period` normalizes to 1 instead — a negative
+    // `cycleWidth` would make `reachOf`'s width bound run backwards and
+    // break R14(b) (`cellRect`/`cellAt` inverting each other), not just
+    // look wrong. Do not "fix" this back to match the engine bit-for-bit;
+    // the engine's own behaviour here is the bug, not this file's.
+    const period = (typeof laneObj.period === 'number' && isFinite(laneObj.period) &&
+      laneObj.period > 0) ? laneObj.period : 1;
+    const phase = (typeof laneObj.phase === 'number' && isFinite(laneObj.phase)) ?
+      laneObj.phase : 0;
     lanes.push({
       index: i,
-      y: i * laneHeight,
+      y: originY + i * laneHeight,
       height: laneHeight,
       cycles: laneCycles,
       depth: found.lanes[i].path.length - 2,
       path: found.lanes[i].path,
-      lane: found.lanes[i].lane,
+      lane: lane,
+      cycleWidth: cycleWidth * period * hscale,
+      originX: nameColWidth - cycleWidth * phase,
     });
   }
   if (lanes.length > 0 && cycles === 0) cycles = 1;
 
+  // Each lane can now have its own cycleWidth/originX, so the diagram's width
+  // is the widest lane's own right edge, not a single global expression. A
+  // lane with zero cycles of its own (an empty or wave-less lane) still
+  // reserves the same one-cycle floor documented above `layoutOf` — the
+  // engine renders a placeholder cycle for it too, so width must not collapse
+  // to the name column just because THAT lane happens to be the widest one.
+  let width = nameColWidth;
+  for (const row of lanes) {
+    const rowCycles = row.cycles > 0 ? row.cycles : 1;
+    const right = row.originX + rowCycles * row.cycleWidth;
+    if (right > width) width = right;
+  }
+  if (lanes.length === 0) width = nameColWidth;
+
   return {
     laneHeight: laneHeight,
     cycleWidth: cycleWidth,
     nameColWidth: nameColWidth,
+    hscale: hscale,
     lanes: lanes,
     cycles: cycles,
     truncated: found.truncated,
-    width: nameColWidth + cycles * cycleWidth,
-    height: lanes.length * laneHeight,
+    width: width,
+    // v3.6.0 Task 6: originY / rulerHeight / headTextHeight / footHeight —
+    // the vertical bands lane 0 and the last lane now sit between.
+    // v3.6.0 Task 9 fix round 1 (R29): footTextHeight — the second, outer
+    // foot band, present only when `foot.text` is set. `footHeight` stays
+    // the inner band (adjacent to the last lane), same as before this fix.
+    originY: originY,
+    rulerHeight: RULER_HEIGHT,
+    headTextHeight: headTextHeight,
+    footHeight: footHeight,
+    footTextHeight: footTextHeight,
+    height: originY + lanes.length * laneHeight + footHeight + footTextHeight,
   };
 }
 
+/**
+ * The group titles in the lane tree, each with the span of display rows it
+ * covers.
+ *
+ * A group title occupies NO ROW — measured in Task 2 against the pinned
+ * engine, and `wave-geometry` is built on it. What it occupies is horizontal
+ * space in the name column, so that is where this puts it: a label in the
+ * lane list's rail, spanning its lanes' rows. Drawing it as a row of its own
+ * would put the lane list one row out of step with the waveform beside it for
+ * every lane below the group, which is exactly the class of silent
+ * disagreement this batch keeps producing.
+ *
+ * The span is derived from the lanes' own paths — `layout.lanes[i].path` is
+ * the codec's — so a group with no lanes under it has no span and is not
+ * shown here; it is not addressable through the bridge either.
+ *
+ * v3.6.0 Task 2: moved here from `lib/editor/wave-ui.js` per ruling R9 — both
+ * `wave-panels.js` (the lane rail) and `wave-draw.js` (the canvas) need it,
+ * and this file is the one place both already depend on. Behaviour
+ * unchanged; it now reads this file's own `valueAt` instead of a copy that
+ * used to live in `wave-ui.js`.
+ */
+function groupSpansOf(doc, layout) {
+  const byKey = new Map();
+  for (let i = 0; i < layout.lanes.length; i++) {
+    const path = layout.lanes[i].path;
+    // Every proper ancestor between `signal` and the lane itself is a group.
+    for (let cut = 2; cut < path.length; cut++) {
+      const prefix = path.slice(0, cut);
+      const key = JSON.stringify(prefix);
+      const seen = byKey.get(key);
+      if (seen === undefined) {
+        byKey.set(key, { path: prefix, depth: cut - 1, from: i, to: i });
+      } else {
+        seen.to = i;
+      }
+    }
+  }
+  const out = [];
+  for (const span of byKey.values()) {
+    const container = valueAt(doc, span.path);
+    const title = Array.isArray(container) && typeof container[0] === 'string'
+      ? container[0] : null;
+    if (title === null) continue;   // an untitled group has nothing to show
+    out.push({ path: span.path, title: title, depth: span.depth,
+      from: span.from, to: span.to });
+  }
+  out.sort(function (a, b) { return a.from - b.from || a.depth - b.depth; });
+  return out;
+}
+
 /** A real, finite coordinate — `'70'` and `NaN` are not one. */
 function isCoord(n) {
   return typeof n === 'number' && isFinite(n);
@@ -258,6 +505,35 @@ function indexAt(pos, origin, step, count) {
   return i + 0;  // `Math.floor(-0.2)` is -0, and -0 fails deepStrictEqual against 0
 }
 
+/**
+ * How many cells of `step` width, starting at `origin`, fit before `limit` —
+ * the largest `n >= 0` with `origin + n * step <= limit`.
+ *
+ * v3.6.0 Task 4 fix round 1 (Critical, ruling R14): once every lane can carry
+ * its own `cycleWidth` (via `period`/`hscale`), the "paint one past a short
+ * lane" affordance can no longer borrow the DIAGRAM's overall cycle count
+ * (`layout.cycles`) and multiply it by THIS lane's pixel width — that was
+ * exactly the bug: the two only ever agreed while every lane shared one
+ * `cycleWidth`, and diverged the moment `period` did not. `layout.width` is
+ * itself built from this same per-lane `originX + n * cycleWidth` expression
+ * (see `layoutOf`), so asking "how many of THIS lane's own cells fit inside
+ * that width" is the one bound guaranteed never to exceed it — R14(a).
+ *
+ * A floor-division estimate is only a proposal, for the identical reason
+ * `indexAt` above does not trust its own division: subtraction and division
+ * round differently, so the answer is snapped against the exact expression
+ * `cellRect` builds a cell with (`origin + n * step`), not derived from it
+ * algebraically. This is the same technique, run at the boundary between
+ * "reachable" and "not", instead of between one cell and the next.
+ */
+function reachOf(origin, step, limit) {
+  let n = Math.floor((limit - origin) / step);
+  if (n < 0) n = 0;
+  while (n > 0 && origin + n * step > limit) n--;
+  while (origin + (n + 1) * step <= limit) n++;
+  return n;
+}
+
 /**
  * Which cell a point is in, or `null` for the name column, outside the diagram,
  * or a coordinate that is not a number.
@@ -269,21 +545,40 @@ function indexAt(pos, origin, step, count) {
  *
  * A cycle past the end of that particular lane still hits: the lane is shorter
  * than the diagram, painting there is how a lane gets extended, and the caller
- * can see it went past from `layout.lanes[laneIndex].cycles`.
+ * can see it went past from `layout.lanes[laneIndex].cycles`. How far past is
+ * bounded by `reachOf` against THIS lane's own `originX`/`cycleWidth` and
+ * `layout.width` (v3.6.0 Task 4 fix round 1, R14) — never by reusing another
+ * lane's cycle count against this lane's pixel width, which is what let a
+ * short, wide-`period` lane hand out cells entirely outside the canvas.
+ *
+ * A lane whose `phase` shifts it left of the diagram's own x=0 has that many
+ * of its leading cycles entirely off-canvas; per R14(a) a cell only counts as
+ * hit if its WHOLE rect is inside `[0, layout.width]`, so those leading
+ * cycles are excluded the same way cycles past `layout.width` are.
  */
 function cellAt(layout, x, y) {
   if (layout === null || typeof layout !== 'object' || !Array.isArray(layout.lanes)) {
     return null;
   }
   if (!isCoord(x) || !isCoord(y)) return null;
-  if (x < layout.nameColWidth || x >= layout.width) return null;
-  if (y < 0 || y >= layout.height) return null;
+  if (x < 0) return null;
+  // v3.6.0 Task 6: lane 0 no longer starts at y=0 — the ruler band (and an
+  // optional head-title band) sits above it, and a press there must land on
+  // NOTHING, not fall through to lane 0 the way a naive `y < 0` guard would.
+  if (y < layout.originY || y >= layout.originY + layout.lanes.length * layout.laneHeight) {
+    return null;
+  }
   if (layout.lanes.length === 0 || layout.cycles === 0) return null;
 
-  return {
-    laneIndex: indexAt(y, 0, layout.laneHeight, layout.lanes.length),
-    cycle: indexAt(x, layout.nameColWidth, layout.cycleWidth, layout.cycles),
-  };
+  const laneIndex = indexAt(y, layout.originY, layout.laneHeight, layout.lanes.length);
+  const row = layout.lanes[laneIndex];
+  const reach = reachOf(row.originX, row.cycleWidth, layout.width);
+  if (reach === 0) return null;
+  if (x < row.originX || x >= row.originX + reach * row.cycleWidth) return null;
+
+  const cycle = indexAt(x, row.originX, row.cycleWidth, reach);
+  if (row.originX + cycle * row.cycleWidth < 0) return null;   // R14(a): left edge off-canvas
+  return { laneIndex: laneIndex, cycle: cycle };
 }
 
 /**
@@ -294,27 +589,365 @@ function cellAt(layout, x, y) {
  * top-left corner. A cycle past the diagram's width has no box, so extending a
  * lane is an edit the caller makes and then lays out again, not a rectangle it
  * can ask for in advance.
+ *
+ * v3.6.0 Task 4 fix round 1 (Critical, R14): "past the diagram's width" is now
+ * judged against THIS lane's own `originX`/`cycleWidth` via `reachOf`, not
+ * against `layout.cycles` (the diagram-wide cycle COUNT) — see `reachOf`'s own
+ * comment for why those two stopped being interchangeable the moment `period`
+ * could differ per lane. R14(a): every non-null rect returned here lies
+ * entirely within `[0, layout.width]`, both edges — a lane shifted left of
+ * x=0 by `phase` has that many of its own leading cycles return `null` too.
  */
 function cellRect(layout, laneIndex, cycle) {
   if (layout === null || typeof layout !== 'object' || !Array.isArray(layout.lanes)) {
     return null;
   }
   if (!isIndex(laneIndex) || laneIndex < 0 || laneIndex >= layout.lanes.length) return null;
-  if (!isIndex(cycle) || cycle < 0 || cycle >= layout.cycles) return null;
+  if (!isIndex(cycle) || cycle < 0) return null;
 
   const row = layout.lanes[laneIndex];
+  const reach = reachOf(row.originX, row.cycleWidth, layout.width);
+  if (cycle >= reach) return null;
+  const x = row.originX + cycle * row.cycleWidth;
+  if (x < 0) return null;   // R14(a): left edge off-canvas (a large positive `phase`)
+
   return {
-    x: layout.nameColWidth + cycle * layout.cycleWidth,
+    x: x,
     y: row.y,
-    width: layout.cycleWidth,
+    width: row.cycleWidth,
     height: row.height,
   };
 }
 
+/** 端點把手的邊長（px）。夠大到手指按得到，小到不會蓋住相鄰格。 */
+const EDGE_HANDLE = 12;
+
+/**
+ * 一格的錨點——引擎畫 `node` 字母的那一點。
+ *
+ * 不是格子中心。使用者回報「連線應該要頭尾相接」，量到的病因是：v3.5.0 的畫布
+ * 把 edge 端點放在格子正中央，引擎的 `render-arcs.js` 卻把錨點放在
+ * `lane.xlabel`，也就是 skin 的 `socket.x`——`SKIN_METRICS.anchorRatio` 那個
+ * 比例——而轉態磚的斜坡正好在那一點跨過一半（`anchorRatio === (slewStartRatio +
+ * slewEndRatio) / 2`，是斜坡的中點、50% 跨越點，不是斜坡的終點——
+ * `SKIN_METRICS` 上方註解已經逐值對過引擎，R23 修正過這裡的舊說法）。MEASURED（pinned wavedrom
+ * 3.5.0）：cycle 寬 40 時 a（cycle 0）的錨點在 x=6、b（cycle 2）在 x=86，
+ * 格線在 0/40/80。v3.5.0 用格子中心，於是畫布的線比引擎的右移了
+ * `(0.5 - anchorRatio)` 個 cycle。v3.6.0 Task 18 重算了這個偏移：引擎自己的
+ * 40px cycle 上是 **14px**（20 − 6），而使用者看到的是編輯器畫布的 48px cycle
+ * （`wave-ui.js` 的 `SIZES`），也就是 **16.8px**——先前這裡寫的「17px＠40px
+ * cycle」把量到的距離（48px 尺度）配了錯的尺度名。一條標注上升緣的線因此
+ * 肉眼可見地沒有接上那個緣。
+ *
+ * 沿用 `cellRect` 而不是自己重算一次格子的位置——那一格「在不在圖裡」只有
+ * 一個答案，`cellRect`／`reachOf` 已經是它，錨點只是在那個答案上再加一個
+ * 固定比例的偏移。
+ */
+function anchorOfCell(layout, laneIndex, cell) {
+  const r = cellRect(layout, laneIndex, cell);
+  if (r === null) return null;
+  return {
+    x: r.x + SKIN_METRICS.anchorRatio * r.width,
+    y: r.y + r.height / 2,
+  };
+}
+
+/**
+ * `(x, y)` 最接近哪一個 cell 的錨點。
+ *
+ * 用 round 而不是 `cellAt` 的 floor：`cellAt` 回答「滑鼠現在壓在哪一格上」，
+ * 目標是游標底下那一格，floor 是對的——格子的左緣屬於自己是 `cellAt` 存在的
+ * 理由。`boundaryAt` 回答的是另一個問題：使用者想把 edge 端點釘在哪一個
+ * 「線」上，那條線畫在錨點，不是格子邊界，使用者的眼睛瞄準的是那個點，往左
+ * 偏一點點不該跳到前一格的錨點去。兩個函式故意不同，不是選了兩種寫法裡的
+ * 一種將就，統一成同一個以後有人「簡化」掉這個差異，行為就會跟著壞掉。
+ *
+ * 上界跟 `cellRect` 用的是同一顆 `reachOf`，不是 `layout.cycles`（整張圖的
+ * cycle 數）——v3.6.0 Task 4 fix round 1（R14）已經證明過後者在每條 lane
+ * 自己的 `period`／`hscale` 不同時會跟這條 lane 自己的像素寬度對不上，
+ * `boundaryAt` 若另外相信 `layout.cycles`，就是同一個「兩處定義，中間那層
+ * 假設它們一致」的錯誤又長出一次：這裡要保證的不變量是「`boundaryAt` 回傳
+ * 的 cell，`cellRect` 對它永遠不是 null」，兩個函式各自的上界只能有一份。
+ *
+ * v3.6.0 Task 5 fix round 1（Critical）：`reachOf` 只是 `cellRect` 兩道關卡的
+ * 右邊那一道，左邊那一道（`phase` 把 `originX` 推成負值時，這一格的左緣整個
+ * 在畫面外——R14(a)）先前這裡漏掉了，於是 `boundaryAt` 對著一條大 `phase` 的
+ * lane 會把左邊那幾格也算進可觸及範圍，回傳一個 `cellRect` 判成 null 的
+ * cell，UI 拿著它去編輯會寫到不存在的地方。修法不是另外發明一個左界算式，
+ * 是照抄 `cellRect` 自己判左緣的那一行（`row.originX + cell * row.cycleWidth
+ * < 0`）——兩個函式判斷「這一格在不在畫面裡」只能有一份答案，`reachOf` 判
+ * 右邊、這一行判左邊，加起來才是 `cellRect` 的完整兩道關卡。
+ */
+function boundaryAt(layout, x, y) {
+  if (layout === null || typeof layout !== 'object' || !Array.isArray(layout.lanes)) {
+    return null;
+  }
+  if (!isCoord(x) || !isCoord(y)) return null;
+  // v3.6.0 Task 6: same vertical origin shift as `cellAt` — a press in the
+  // ruler/head band must not resolve to lane 0. `boundaryAt` picks the
+  // NEAREST boundary rather than floor-dividing, but it still has to agree
+  // with `cellAt` on where lane 0's own row starts; two different vertical
+  // origins in the same file is exactly the "two definitions, one layer
+  // assumes they agree" defect class this codebase has already paid for.
+  if (y < layout.originY || y >= layout.originY + layout.lanes.length * layout.laneHeight) {
+    return null;
+  }
+  if (layout.lanes.length === 0 || layout.cycles === 0) return null;
+  const laneIndex = indexAt(y, layout.originY, layout.laneHeight, layout.lanes.length);
+  const row = layout.lanes[laneIndex];
+  const reach = reachOf(row.originX, row.cycleWidth, layout.width);
+  if (reach === 0) return null;
+  const raw = (x - row.originX - SKIN_METRICS.anchorRatio * row.cycleWidth) / row.cycleWidth;
+  let cell = Math.round(raw);
+  if (cell < 0) cell = 0;
+  if (cell > reach - 1) cell = reach - 1;
+  if (row.originX + cell * row.cycleWidth < 0) return null;   // R14(a): same left-edge exclusion as cellRect
+  return { laneIndex: laneIndex, cell: cell + 0 };  // `+0` folds a possible -0, same reason as `indexAt`
+}
+
+/**
+ * 一條 lane 的轉態 cell。
+ *
+ * v3.6.0 Task 11 fix round 3：這裡原本寫「一個 cycle 若電位跟前一個 cycle
+ * 不同（或是文件第一拍本身），使用者才會想把 edge 端點釘在那裡」——那句話
+ * 描述的是另一支函式，不是下面這支。真正的規則是「引擎會在那一格畫出東西
+ * 的那些格」：wave 字串裡每一個顯式宣告電位的字元（不是 `.`、不是 `|`），
+ * 包含跟前一格同值的顯式重複，因為引擎在那裡照樣畫出東西——一般電位在
+ * 顯式重複處是 `0m0`／`1m1` 的凹痕，bus 是 `vmv-*` 的接縫，`.`（延續上一格）
+ * 才是真正「什麼都不畫」的那一種。MEASURED（pinned wavedrom 3.5.0，逐
+ * half-brick 讀出來的）：
+ *
+ *     '0011' -> 000, 000, 0m0, 000, 0m1, 111, 1m1, 111   顯式重複處也有凹痕
+ *     '0.1.' -> 000, 000, 000, 000, 0m1, 111, 111, 111   用 `.` 的地方什麼都沒有
+ *     '22'   -> vvv-2, vvv-2, vmv-2-2, vvv-2             bus 顯式重複也有接縫
+ *
+ * 「跟前一個 cycle 電位不同」不是這條規則、也不能拿來當判斷式：`0011` 的
+ * 第二格是顯式 `0`、跟前一格同值，量到的 `0m0` 證明它依然是引擎會畫出東西
+ * 的一格，是真的轉態。若照著那句錯的舊註解把這支函式「修」成比對前後電位
+ * 是否相同，會把這一格漏掉——這正是這次要防的那個方向的錯，不是要修的
+ * 方向。
+ *
+ * （我們自己的畫布不畫這些凹痕——`brickPath` 在 `prevLevel === level`
+ * 時回傳一條平線，見 `wave-draw.js`——所以一顆轉態標記有可能落在畫布上什麼
+ * 都沒畫的地方。這是畫磚層本身的真實落差，v3.5.0 就已經如此，不在這個
+ * function 的職責範圍內，這裡只負責如實描述 `transitionsOf` 自己做的事。）
+ *
+ * 資料問的是 `codec.expandWave`，跟畫布展開波形用的是同一份：另寫一份展開
+ * 邏輯會跟它漂移，那正是這個版本要清掉的病。`held`（來源寫的是 `.`）不算
+ * 轉態；`|`（斷點）本身也不算，但它後面那格算——斷點之後電位重新宣告，即使
+ * 值沒變，那正是「不算 `.`」的同一條規則自然帶出來的結果。
+ *
+ * 走訪順序是 codec 攤平後的顯示序，跟 `layoutOf`／`enumerateLanes` 問
+ * `codec.lanePaths` 是同一份列舉：直接問它，而不是先 `layoutOf` 整份文件只
+ * 為了讀一個欄位——`layoutOf` 的列舉是 O(N)、量到的成本見上方 `MAX_LANES`
+ * 的註解，但它同時算版面的每一格座標、每條 lane 的 cycles，這裡只需要一條
+ * lane 的 `wave` 字串，兩者要做的工不同，沒有理由把後者的工都做一遍。
+ * `MAX_LANES` 這條線在這裡也照樣守：超過上限的 lane 對 `layoutOf` 是截斷、
+ * 不可觸及，`transitionsOf` 問同一個 lane 也該是同一個「不可觸及」的答案，
+ * 不能因為抄了近路就多看見一條 `layoutOf` 看不到的 lane。
+ */
+function transitionsOf(doc, laneIndex) {
+  if (doc === null || typeof doc !== 'object') return [];
+  const paths = codec.lanePaths(doc);
+  const n = paths.length < MAX_LANES ? paths.length : MAX_LANES;
+  if (!isIndex(laneIndex) || laneIndex < 0 || laneIndex >= n) return [];
+  const lane = valueAt(doc, paths[laneIndex]);
+  const wave = (lane !== null && typeof lane === 'object' && typeof lane.wave === 'string') ?
+    lane.wave : '';
+  const cells = codec.expandWave(wave);
+  const out = [];
+  for (let i = 0; i < cells.length; i += 1) {
+    if (cells[i].held === true) continue;
+    if (cells[i].ch === '|') continue;
+    out.push(i);
+  }
+  return out;
+}
+
+/**
+ * 每條 edge 的兩個端點座標、SVG path 與標籤錨點。
+ *
+ * 字母的位置問 `codec.nodesOf(doc)`，不自己走樹——`layoutOf` 已經立下這個規矩
+ * （它問 `codec.lanePaths`），第二份走樹邏輯會跟它漂移。用的是本檔案頂端那顆
+ * 模組層級的 `codec`（`enumerateLanes`/`cyclesOf` 也是同一顆）：這個檔案已經
+ * 對 `wave-codec.js` 有一份 `require`，purity guard 也只准這一份，injected 參數
+ * 不會讓檔案更「純」，只會讓同名綁定的讀者分不清是哪一顆、也讓少傳一個參數的
+ * 改動悄悄落回外層而不報錯。
+ *
+ * 引用到不存在字母的 edge 直接跳過：那是一份使用者手寫壞掉的文件，畫不出那條線
+ * 是對的，讓整張圖倒掉不是。
+ */
+/**
+ * `edgeLayout`'s three `continue`s, WITH the reason each one fired —
+ * final review finding 3. `edgeLayout` itself stays a thin wrapper around
+ * this (`.drawn`), so every existing caller keeps its array-of-drawn-edges
+ * shape; a caller that also needs to explain a gap (`renderUnmodelled` in
+ * `wave-ui.js`) asks this one instead of re-deriving any of the three checks
+ * from scratch — there is exactly one walk of `doc.edge`, and exactly one
+ * place that decides whether an entry counts as drawn.
+ *
+ * `skipped[i].reason` is one of:
+ *   - `'unparseable'` — `codec.parseEdge` returned `null` (the shape is not
+ *     one of `EDGE_SHAPES`, or the entry does not have `<letter><shape><letter>`
+ *     to begin with). `edge` is `null`; there is no `from`/`to` to report.
+ *   - `'dangling'` — the shape parsed, but `from` or `to` names a letter
+ *     `codec.nodesOf` never placed anywhere in the document (a hand-edited or
+ *     half-finished `edge:` array). This is the one case the pinned engine
+ *     ALSO refuses to draw — measured against `node_modules/wavedrom`, an
+ *     edge naming an absent letter renders nothing, same as here.
+ *   - `'out-of-range'` — the shape parsed and both letters resolve to a real
+ *     `{lane, cell}`, but that cell has no box in this layout: `anchorOfCell`
+ *     returned `null`, which happens when a lane's `node` string outlives the
+ *     lane itself (`insertCycles`/`deleteCycles` narrow `wave` but do not
+ *     reindex `node`, so a deleted cycle can leave an anchor past the lane's
+ *     new length). Measured against the pinned engine, THIS case is the
+ *     opposite of `'dangling'`: the engine draws a line for it anyway, so a
+ *     silent skip here is exactly the canvas/preview divergence this version
+ *     exists to prevent.
+ *
+ * Anything reaching this file only through `doc.edge` being non-empty but
+ * `layout` being unusable, or `doc` itself not carrying an `edge` array,
+ * still returns `{drawn: [], skipped: []}` — there is nothing to classify,
+ * not a fourth reason.
+ */
+function edgeLayoutDetail(doc, layout) {
+  const drawn = [];
+  const skipped = [];
+  if (doc === null || typeof doc !== 'object' || !Array.isArray(doc.edge)) {
+    return { drawn: drawn, skipped: skipped };
+  }
+  if (layout === null || typeof layout !== 'object') {
+    return { drawn: drawn, skipped: skipped };
+  }
+  const nodes = codec.nodesOf(doc);
+  for (let i = 0; i < doc.edge.length; i += 1) {
+    const edge = codec.parseEdge(doc.edge[i]);
+    if (edge === null) {
+      skipped.push({ index: i, edge: null, reason: 'unparseable' });
+      continue;
+    }
+    const a = nodes[edge.from];
+    const b = nodes[edge.to];
+    if (a === undefined || b === undefined) {
+      skipped.push({ index: i, edge: edge, reason: 'dangling' });
+      continue;
+    }
+    const from = anchorOfCell(layout, a.at, a.cell);
+    const to = anchorOfCell(layout, b.at, b.cell);
+    if (from === null || to === null) {
+      skipped.push({ index: i, edge: edge, reason: 'out-of-range' });
+      continue;
+    }
+    from.at = a.at; from.cell = a.cell;
+    to.at = b.at; to.cell = b.cell;
+    drawn.push({
+      index: i,
+      edge: edge,
+      from: from,
+      to: to,
+      d: pathFor(edge.shape, from, to),
+      labelPos: { x: (from.x + to.x) / 2, y: (from.y + to.y) / 2 },
+    });
+  }
+  return { drawn: drawn, skipped: skipped };
+}
+
+function edgeLayout(doc, layout) {
+  return edgeLayoutDetail(doc, layout).drawn;
+}
+
+/**
+ * 折線（`-|` 系）三種轉角次序，抄自 pin 住的
+ * node_modules/wavedrom/lib/arc-shape.js 的三組 case（座標系裡的 `m` 相對位移
+ * 換成這裡的絕對 `L`）：
+ *
+ *   - MID：先橫走半程、再直走全程、再橫走半程——轉角在 `(from.x+to.x)/2`。
+ *   - VERT_FIRST：先直（`from.x, to.y`）再橫——`|-` 系，垂直先行。
+ *   - 其餘（HORIZ_FIRST）：先橫（`to.x, from.y`）再直——`-|` 系，水平先行。
+ *
+ * 三個陣列各自窮舉 EDGE_SHAPES 裡屬於這族的每個成員（含箭頭與雙箭頭變體），
+ * 用精確字串比對而非子字串——shape 一律來自 `codec.parseEdge` 收斂過的
+ * EDGE_SHAPES 集合，不會有夾雜字元，子字串比對（舊寫法 `has('|')`）分不出
+ * `-|` 與 `|-` 誰先誰後，是這裡曾經量到的缺陷。
+ */
+const ELBOW_MID = ['-|-', '-|->', '<-|->'];
+const ELBOW_VERT_FIRST = ['|-', '|->'];
+const ELBOW_HORIZ_FIRST = ['-|', '-|>', '<-|>'];
+
+/**
+ * 形狀 → SVG path。
+ *
+ * 三族：直線（`-` 系）、曲線（`~` 系）、折線（`-|` 系）。箭頭本身不在 path 裡，
+ * 由 UI 掛 marker——這裡只負責「線走哪裡」。
+ */
+function pathFor(shape, from, to) {
+  if (ELBOW_MID.indexOf(shape) !== -1) {
+    const midX = (from.x + to.x) / 2;
+    return 'M' + from.x + ',' + from.y + ' L' + midX + ',' + from.y +
+      ' L' + midX + ',' + to.y + ' L' + to.x + ',' + to.y;
+  }
+  if (ELBOW_VERT_FIRST.indexOf(shape) !== -1) {
+    return 'M' + from.x + ',' + from.y + ' L' + from.x + ',' + to.y +
+      ' L' + to.x + ',' + to.y;
+  }
+  if (ELBOW_HORIZ_FIRST.indexOf(shape) !== -1) {
+    return 'M' + from.x + ',' + from.y + ' L' + to.x + ',' + from.y +
+      ' L' + to.x + ',' + to.y;
+  }
+  const has = function (s) { return shape.indexOf(s) !== -1; };
+  if (has('~')) {
+    const dx = (to.x - from.x) / 2;
+    return 'M' + from.x + ',' + from.y +
+      ' C' + (from.x + dx) + ',' + from.y + ' ' + (to.x - dx) + ',' + to.y +
+      ' ' + to.x + ',' + to.y;
+  }
+  return 'M' + from.x + ',' + from.y + ' L' + to.x + ',' + to.y;
+}
+
+/** 端點把手的矩形，以端點為中心。 */
+function edgeHandleRect(point) {
+  return {
+    x: point.x - EDGE_HANDLE / 2,
+    y: point.y - EDGE_HANDLE / 2,
+    width: EDGE_HANDLE,
+    height: EDGE_HANDLE,
+  };
+}
+
+/**
+ * `(x, y)` 命中哪一個端點把手。
+ *
+ * 用的是 `edgeHandleRect` 產生的同一個矩形——命中與繪製共用一個運算式，
+ * 就像 `cellAt` 是 `cellRect` 的構造反函數。另寫一份圓形碰撞會慢慢跟畫面分家。
+ */
+function edgeHandleAt(edges, x, y) {
+  if (!Array.isArray(edges)) return null;
+  for (let i = edges.length - 1; i >= 0; i -= 1) {
+    for (const end of ['to', 'from']) {
+      const r = edgeHandleRect(edges[i][end]);
+      if (x >= r.x && x < r.x + r.width && y >= r.y && y < r.y + r.height) {
+        return { index: edges[i].index, end: end };
+      }
+    }
+  }
+  return null;
+}
+
 module.exports = {
   layoutOf: layoutOf,
+  valueAt: valueAt,
+  groupSpansOf: groupSpansOf,
   cellAt: cellAt,
   cellRect: cellRect,
+  anchorOfCell: anchorOfCell,
+  boundaryAt: boundaryAt,
+  transitionsOf: transitionsOf,
+  edgeLayout: edgeLayout,
+  edgeLayoutDetail: edgeLayoutDetail,
+  edgeHandleRect: edgeHandleRect,
+  edgeHandleAt: edgeHandleAt,
+  EDGE_HANDLE: EDGE_HANDLE,
   DEFAULTS: DEFAULTS,
   MAX_LANES: MAX_LANES,
+  SKIN_METRICS: SKIN_METRICS,
 };