@helping-ai-workflow/md2doc 3.4.2 → 3.5.0

package/lib/editor/wave-geometry.js

@@ -311,10 +311,193 @@ function cellRect(layout, laneIndex, cycle) {
   };
 }
 
+/** 端點把手的邊長（px）。夠大到手指按得到，小到不會蓋住相鄰格。 */
+const EDGE_HANDLE = 12;
+
+function centerOfCell(layout, laneIndex, cell) {
+  const r = cellRect(layout, laneIndex, cell);
+  if (r === null) return null;
+  return { x: r.x + r.width / 2, y: r.y + r.height / 2 };
+}
+
+/**
+ * 每條 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: `centerOfCell`
+ *     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 = centerOfCell(layout, a.at, a.cell);
+    const to = centerOfCell(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,
   cellAt: cellAt,
   cellRect: cellRect,
+  edgeLayout: edgeLayout,
+  edgeLayoutDetail: edgeLayoutDetail,
+  edgeHandleRect: edgeHandleRect,
+  edgeHandleAt: edgeHandleAt,
+  EDGE_HANDLE: EDGE_HANDLE,
   DEFAULTS: DEFAULTS,
   MAX_LANES: MAX_LANES,
 };

package/lib/editor/wave-store.js

@@ -41,7 +41,6 @@
  *     about it — rewrite the block, cancel, edit by hand — belongs to the
  *     layer that can ask them, and re-serialising the block behind their back
  *     is the one answer this file may never give.
-" PLACEHOLDER 
  *
  * A throw inside an `apply` callback is NOT caught. The store's own state is
  * untouched when one happens (nothing is pushed until the new document is in
@@ -63,6 +62,17 @@ const C = require('./wave-codec.js');
  */
 const MAX_DEPTH = C.MAX_DEPTH;
 
+/**
+ * The undo stack's cap, in entries.
+ *
+ * Every entry holds a whole frozen document, so an unbounded stack grows with
+ * the length of the editing session rather than with anything about the
+ * document. 200 is a ruling, not a measurement of any observed cost — there is
+ * no profiling behind the number, just a decision that a session's undo depth
+ * stops mattering well before 200 steps back.
+ */
+const HISTORY_LIMIT = 200;
+
 /**
  * Open a store over one wavedrom block's source text.
  *
@@ -141,6 +151,23 @@ function createStore(sourceText) {
       origins: origins,
     });
     at++;
+    // Cap the stack, not just its growth: apply always leaves `at` on the
+    // entry it just pushed (the truncation above already dropped any redo
+    // tail), so history.length is always at + 1 here. Dropping the oldest
+    // entry when the cap is exceeded means `at` has to move down with it, or
+    // every canUndo/undoName/redo answer after the drop would be off by one —
+    // pointing one entry short of the one actually current.
+    // `while`, not `if`: apply today only ever pushes one entry per call, so
+    // the stack is never more than one over the cap and `if` is provably
+    // enough — but that "one entry per call" fact lives in this function, not
+    // in the invariant. A future batch-push (or a cap lowered at runtime)
+    // would leave history silently one-or-more over HISTORY_LIMIT forever,
+    // since nothing after this point ever re-checks. `while` costs nothing
+    // today and stops correctness depending on a fact this loop cannot see.
+    while (history.length > HISTORY_LIMIT) {
+      history.shift();
+      at--;
+    }
     return true;
   }