@helping-ai-workflow/md2doc 3.4.2 → 3.6.0

package/lib/editor/wave-codec.js

@@ -602,6 +602,10 @@ function resolveEdit(ctx, edit) {
   const op = edit.op === undefined ? 'set' : edit.op;
   if (op === 'set') return resolveSet(ctx, edit);
   if (op === 'insert') return resolveInsert(ctx, edit);
+  // v3.6.0 Task 13 fix round 1: several new members on one object, in a
+  // single local edit — see `wave-store.js`'s `diffMembers` for why one
+  // `insert` per key is not safe once a session can add more than one.
+  if (op === 'insert-members') return resolveInsertMembers(ctx, edit);
   if (op === 'remove') return resolveRemove(ctx, edit);
   if (op === 'move') return resolveMove(ctx, edit);
   if (op === 'replace') return resolveReplace(ctx, edit);
@@ -900,6 +904,81 @@ function resolveInsertMember(ctx, edit) {
   return appendAfterMember(ctx, path, last, body);
 }
 
+/**
+ * v3.6.0 Task 13 fix round 1 (Critical 1): `resolveInsertMember` above,
+ * generalised to SEVERAL new keys on the same object in one edit —
+ * `edit = {op: 'insert-members', path: <parent path>, entries: [[key,
+ * value], …]}`, produced by `wave-store.js`'s `diffMembers` whenever a
+ * session added more than one new field to the same object. See that
+ * function's own comment for why one `insert` per key is not safe once
+ * there can be more than one: every one of them would anchor at the SAME
+ * "object's last existing member" and `patchSource`'s "two edits land at
+ * the same place" guard would refuse the batch.
+ *
+ * This resolves to exactly ONE edit at exactly ONE anchor — the object's
+ * last existing member, same as `resolveInsertMember` — with every new
+ * key's `key: value` joined into one body. Each entry gets its own
+ * duplicate-key and serialization checks, same as `resolveInsertMember`
+ * gives its one key, so a batch that only has ONE new key refuses (or
+ * succeeds) identically either way; `diffMembers` never actually calls this
+ * with fewer than two entries, but nothing here depends on that.
+ */
+function resolveInsertMembers(ctx, edit) {
+  const path = edit.path;
+  const parentSpan = ctx.parsed.spans.get(JSON.stringify(path));
+  const parent = lookup(ctx.parsed.doc, path);
+  if (!parentSpan || !parent.found || parent.value === null ||
+      typeof parent.value !== 'object' || Array.isArray(parent.value)) {
+    return refuse('insert-members needs an object at ' + JSON.stringify(path),
+      nearestRange(ctx, path));
+  }
+  if (touchesDuplicateKey(ctx, path)) {
+    return refuse(duplicateWhy(path), rangeOf(path, path, parentSpan));
+  }
+  if (!Array.isArray(edit.entries) || edit.entries.length === 0) {
+    return refuse('insert-members needs at least one [key, value] entry',
+      rangeOf(path, path, parentSpan));
+  }
+  const parts = [];
+  for (const entry of edit.entries) {
+    const key = entry[0];
+    const value = entry[1];
+    const memberPath = path.concat([key]);
+    if (Object.prototype.hasOwnProperty.call(parent.value, key)) {
+      return refuse(JSON.stringify(memberPath) + ' already has a member there, so this is a ' +
+        'set rather than an insert', rangeOf(memberPath, path, parentSpan));
+    }
+    const ser = serialize(value, dominantQuote(ctx), MAX_DEPTH - path.length - 1);
+    if (ser.ok !== true) return refuse(ser.why, rangeOf(memberPath, path, parentSpan));
+    parts.push(renderKey(key, '"') + ': ' + ser.text);
+  }
+  const keys = Object.keys(parent.value);
+  if (keys.length === 0) {
+    const at = parentSpan[0] + 1;
+    const close = lineIndentBefore(ctx.text, parentSpan[1] - 1);
+    if (close !== null) {
+      const eol = lineBreakBefore(ctx.text, parentSpan[1] - 1);
+      return { ok: true, path: path, start: at, end: at, text: eol + close + '  ' + parts.join(', ') };
+    }
+    return { ok: true, path: path, start: at, end: at, text: parts.join(', ') };
+  }
+  const lastPath = path.concat([keys[keys.length - 1]]);
+  const last = ctx.parsed.members.get(JSON.stringify(lastPath));
+  if (!last) {
+    return refuse('no member span for ' + JSON.stringify(lastPath),
+      rangeOf(path, path, parentSpan));
+  }
+  // The same comma-plus-gap `appendAfterMember` puts between what was
+  // already there and this edit's own body is used AGAIN here, between the
+  // new members joined into that one body — the indent/line-break come from
+  // the same anchor (`last[0]`) either way, so a multi-key insert reads on
+  // the page exactly like the same keys inserted one at a time would have,
+  // had that been safe to do.
+  const indent = lineIndentBefore(ctx.text, last[0]);
+  const gap = indent === null ? ' ' : lineBreakBefore(ctx.text, last[0]) + indent;
+  return appendAfterMember(ctx, path, last, parts.join(',' + gap));
+}
+
 /**
  * Move one array element, bytes and all.
  *
@@ -1786,6 +1865,83 @@ function copyObject(obj) {
   return out;
 }
 
+/**
+ * Which entry of a lane's `data` list a display cycle draws, or `null` for a
+ * cycle that draws none of its own.
+ *
+ * Only `=` and `2`-`9` written out explicitly consume a slot; `.` (a held
+ * continuation) and `|` (a gap) do not — measured against the pinned wavedrom
+ * 3.5.0, the same rule `readLane`'s slot counter already applies while it
+ * folds labels into cells. This is that same count exposed as a standalone
+ * lookup, so a caller who only has a cycle index — a click, a keyboard
+ * cursor — can ask "which array index is this" before it needs anything else
+ * about the lane. It reads the wave string directly through `expandWave`
+ * rather than through `readLane`, because the question here never touches a
+ * label value, only the shape of the wave.
+ */
+function dataSlotOf(lane, cell) {
+  if (lane === null || typeof lane !== 'object') return null;
+  const cells = expandWave(typeof lane.wave === 'string' ? lane.wave : '');
+  if (!isIndex(cell, cells.length)) return null;
+  let slot = 0;
+  for (let i = 0; i < cells.length; i++) {
+    const c = cells[i];
+    const consumes = !c.held && isValueChar(c.ch);
+    if (i === cell) return consumes ? slot : null;
+    if (consumes) slot++;
+  }
+  return null;
+}
+
+/**
+ * Write one entry of a lane's `data` list by array index, on the lane at
+ * display position `at`. Never addressed by cycle — a caller who has a cycle
+ * gets the index from `dataSlotOf` first, so the counting `data` is an ARRAY
+ * and only some cycles consume a slot from it never has to happen twice.
+ *
+ * A slot that lands on one of the wave's own value cycles goes in through the
+ * same `readLane` / `writeLane` round trip every other label edit already
+ * uses, so text-vs-array spelling and the whitespace `readLane` preserved
+ * come through untouched. A slot past the last consuming cycle — one the wave
+ * itself never reaches, which wavedrom ignores and the picture never shows —
+ * extends `spare` instead, padded with `''` so nothing in between is left a
+ * hole.
+ *
+ * `slot` must be a non-negative integer and `text` a string; anything else,
+ * or an `at` outside the document, answers the same doc unchanged, and so
+ * does a `text` equal to what is already there — `mapLane` catches that on
+ * its own by comparing the lane it gets back.
+ */
+function setDataAt(doc, at, slot, text) {
+  if (!Number.isInteger(slot) || slot < 0) return doc;
+  if (typeof text !== 'string') return doc;
+  return mapLane(doc, at, function (lane) {
+    const model = readLane(lane);
+    const cells = model.cells;
+    let total = 0;
+    let hit = -1;
+    for (let i = 0; i < cells.length; i++) {
+      const cell = cells[i];
+      if (cell.held || !isValueChar(cell.ch)) continue;
+      if (total === slot) hit = i;
+      total++;
+    }
+    if (hit !== -1) {
+      const next = cells.slice();
+      next[hit] = { ch: cells[hit].ch, held: cells[hit].held, label: text };
+      model.cells = next;
+    } else {
+      const spare = model.spare.slice();
+      const pos = slot - total;
+      while (spare.length <= pos) spare.push('');
+      spare[pos] = text;
+      model.spare = spare;
+    }
+    model.hasLabels = true;
+    return writeLane(lane, model);
+  });
+}
+
 /**
  * A copy all the way down, for a value arriving from a caller who keeps their
  * own reference to it. A shallow copy leaves the arrays shared, so a caller
@@ -2349,6 +2505,51 @@ function moveLane(doc, from, to) {
   return insertAtPath(reduced, path, lane);
 }
 
+/**
+ * Copy the lane at display position `at` and put the copy immediately after
+ * it, at display position `at + 1` — a full deep copy, `data` / any other key
+ * included, not a name-and-wave reconstruction that would silently drop the
+ * rest. Built on `addLane`, which already does that deep copy
+ * (`copyValue(lane, MAX_DEPTH)`) for a caller-owned object.
+ *
+ * `node` IS THE ONE EXCEPTION and is stripped before the copy is built —
+ * final review finding 2. `node` is a map of anchor LETTERS to cell indices
+ * (§1's invariant: a letter resolves to exactly one `{lane, cell}`), and it
+ * names the ORIGINAL lane, not the wave shape being copied. Carrying it over
+ * verbatim gives two lanes the same letters; `nodesOf` resolves each letter to
+ * whichever lane it saw last, so every edge anchored on the original lane
+ * silently relocates onto the fresh duplicate, and `pruneNodes` cannot repair
+ * it — it only asks whether a letter is referenced *somewhere*, and after the
+ * duplication it still is. A brand-new lane starts with no edge pointing at
+ * it, which is what "no `node`" means; the user can draw new anchors once
+ * they decide what this copy is for. This was PINNED the other way — a
+ * `test/wave-codec.test.js` assertion whose comment said every field
+ * including `node` was copied, and the duplicate button's tooltip in
+ * `wave-ui.js` promised the same — both were reversed alongside this fix.
+ *
+ * `at + 1` goes through `laneInsertPath` exactly as every other insert does,
+ * so it inherits the one asymmetry that function documents: duplicating a
+ * group's LAST lane lands the copy just outside the group (append to `signal`
+ * itself), while duplicating any other lane in the group — including its
+ * first — keeps the copy inside. That is not a special case written for
+ * duplication; it is the same rule the rail's own insert button already
+ * surfaces to the user, reached through the same door.
+ */
+function duplicateLane(doc, at) {
+  const flat = flattenLanes(doc);
+  if (!isIndex(at, flat.length)) return doc;
+  const lane = flat[at].lane;
+  let toCopy = lane;
+  if (lane !== null && typeof lane === 'object' && !Array.isArray(lane) &&
+      Object.prototype.hasOwnProperty.call(lane, 'node')) {
+    toCopy = {};
+    for (const key of Object.keys(lane)) {
+      if (key !== 'node') toCopy[key] = lane[key];
+    }
+  }
+  return addLane(doc, at + 1, toCopy);
+}
+
 /**
  * Where the lane at display position `index` lives, as a path the patching half
  * of this file addresses members by — `['signal', 1, 2]` for the second lane of
@@ -2611,6 +2812,18 @@ function replaceSegment(node, seg, child) {
   return out;
 }
 
+/**
+ * A new document with the whole member at `path` swapped for `value`, sharing
+ * everything else — the third of this trio alongside `withoutPath` and
+ * `insertAtPath`, for the one shape neither of those two says: "this exact
+ * container becomes a different array", which is what dissolving a group is.
+ * `path` must not be empty; there is no member to replace at the root.
+ */
+function setAtPath(node, path, value) {
+  if (path.length === 1) return replaceSegment(node, path[0], value);
+  return replaceSegment(node, path[0], setAtPath(node[path[0]], path.slice(1), value));
+}
+
 /** Rename the lane at display position `at`. */
 function renameLane(doc, at, name) {
   if (typeof name !== 'string') return doc;
@@ -2621,11 +2834,572 @@ function renameLane(doc, at, name) {
   });
 }
 
+/**
+ * Wrap the CONTIGUOUS run of lanes at display positions `ats` into one new
+ * named group — WaveJSON's only shape for one, an array whose first element
+ * is `label` and whose rest are the lanes it names, nested inside `signal`.
+ * That shape is why the run has to be contiguous: a group is a slice of ONE
+ * array, and lanes that are not next to each other in display order cannot
+ * become elements of the same slice without an author reading the result as
+ * lanes that silently changed place. So a selection that is not contiguous —
+ * `ats` sorted does not read `k, k+1, k+2, …` — is refused, the same doc back,
+ * rather than grouping the SPAN between the gaps and silently carrying along
+ * lanes the caller never selected.
+ *
+ * `ats` may name lanes that live under different existing groups, or none —
+ * the members of the new group are found by `laneRemovePaths`, which already
+ * answers the one question this needs: what has to come OUT of the document
+ * for this set of lanes to leave it, taking an existing group with them when
+ * every one of ITS lanes is in the set (the same rule `removeLane` applies to
+ * a single lane, batched the way multi-select needs). Two things follow from
+ * reusing that answer rather than re-deriving it: the topmost members it
+ * names are always siblings of ONE array — display-contiguous lanes cannot
+ * collapse into removals that live in two different containers without a
+ * non-selected lane or an un-consumed sub-group sitting between them, and
+ * either one would have broken the display-contiguity check above first —
+ * and the new group lands exactly where that array's first survivor used to
+ * be, which is what makes the edit read as "these lanes became a group" and
+ * not as "these lanes moved somewhere else and a group appeared".
+ *
+ * The lane objects themselves are carried over as the SAME objects, the same
+ * promise `moveLane` makes and for the identical reason: `wave-store`'s
+ * `remapOrigins` matches lanes across an edit by identity, and a copy here
+ * would make an ordinary re-grouping look like every one of those lanes was
+ * deleted and a new one added in its place.
+ *
+ * `label` must be a string (an empty one is fine — the caller can rename the
+ * group afterwards, same as a newly added lane starts with an empty name).
+ * Anything else, an `ats` that is not an array, an empty one, an index out of
+ * range, or a defensive shape the removal set does not turn out to have —
+ * more than one parent among the topmost removals, or gaps between their
+ * positions in it — answers the document unchanged rather than guessing.
+ */
+function groupLanes(doc, ats, label) {
+  if (typeof label !== 'string') return doc;
+  if (!Array.isArray(ats) || ats.length === 0) return doc;
+  const flat = flattenLanes(doc);
+  const sorted = ats.slice().sort(function (a, b) { return a - b; });
+  for (let i = 0; i < sorted.length; i++) {
+    if (!isIndex(sorted[i], flat.length)) return doc;
+    if (i > 0 && sorted[i] !== sorted[i - 1] + 1) return doc; // non-contiguous, or a duplicate
+  }
+  const lanes = sorted.map(function (i) { return flat[i].lane; });
+
+  const removals = laneRemovePaths(doc, sorted);
+  if (removals === null || removals.length === 0) return doc;
+  const parentKey = JSON.stringify(removals[0].slice(0, -1));
+  const positions = [];
+  for (const path of removals) {
+    if (JSON.stringify(path.slice(0, -1)) !== parentKey) return doc; // not one array — refuse
+    positions.push(path[path.length - 1]);
+  }
+  positions.sort(function (a, b) { return a - b; });
+  for (let i = 1; i < positions.length; i++) {
+    if (positions[i] !== positions[i - 1] + 1) return doc; // a gap in that array — refuse
+  }
+  const parent = removals[0].slice(0, -1);
+  const insertIndex = positions[0];
+
+  let next = doc;
+  for (let i = positions.length - 1; i >= 0; i--) {
+    next = withoutPath(next, parent.concat([positions[i]]));
+  }
+  return insertAtPath(next, parent.concat([insertIndex]), [label].concat(lanes));
+}
+
+/**
+ * Dissolve the group that lane `at` is a DIRECT member of, keeping its lanes
+ * (and any sub-groups it holds) exactly where that group was and dropping
+ * only the wrapping array and its title.
+ *
+ * "Direct" is load-bearing for a caller addressing a nested group: `at` is a
+ * lane's display position, and a lane has exactly one immediate parent, so
+ * ungrouping always names one group unambiguously. It also means a group made
+ * of nothing but sub-groups — no lane of its own anywhere in it — cannot be
+ * named this way; there is no lane whose immediate parent IS that group. The
+ * UI does not offer the control there for the same reason: v3.6.0 Task 14's
+ * 解散群組 button is enabled only when the SELECTED lane is a direct member
+ * of some group (`laneIsInGroup` in `wave-ui.js`), and a group made only of
+ * sub-groups has no such lane to select.
+ *
+ * `at` outside the document, or a lane that is not inside any group (`signal`
+ * is not one), answers the document unchanged.
+ */
+function ungroupLanes(doc, at) {
+  const path = lanePath(doc, at);
+  if (path === null || path.length < 3) return doc;
+  const groupPath = path.slice(0, -1);
+  const found = lookup(doc, groupPath);
+  if (!found.found || !Array.isArray(found.value)) return doc;
+  const group = found.value;
+  const members = group.length > 0 && typeof group[0] === 'string' ? group.slice(1) : group.slice();
+
+  const parentPath = groupPath.slice(0, -1);
+  const parentFound = lookup(doc, parentPath);
+  if (!parentFound.found || !Array.isArray(parentFound.value)) return doc;
+  const idx = groupPath[groupPath.length - 1];
+  const parentArr = parentFound.value;
+  const nextParentArr = parentArr.slice(0, idx).concat(members, parentArr.slice(idx + 1));
+  return setAtPath(doc, parentPath, nextParentArr);
+}
+
+// ── v3.5.0 Task 13 fix round 2: doc.head / doc.foot banner fields ─────────
+
+/**
+ * Write, or clear, one field of `doc.head` / `doc.foot` — the six ruler
+ * fields (`text`/`tick`/`tock`/`every` under each of `head`/`foot`) the wave
+ * editor's meta bar exposes through `commitBanner`.
+ *
+ * Setting a non-empty `value` writes it under `doc[which][key]`, creating
+ * `doc[which]` if it did not exist yet. Clearing — `value === ''` — DELETES
+ * the key rather than leaving an empty string in its place: for
+ * `tick`/`tock`/`every` an empty string is NOT the same thing to the pinned
+ * engine as an absent key. `ticktock` in
+ * `node_modules/wavedrom/lib/render-marks.js` only skips a field that is
+ * `=== undefined`; an empty string instead reaches its array branch,
+ * `Number('')` is `0`, `isNaN(0)` is `false`, and the engine draws a full
+ * default 0-based ruler nobody asked for — measured, not assumed. (`.text`
+ * happens to be safe either way, since `captext`'s own guard is a plain
+ * truthy check — but this function does not special-case it, so the same
+ * correct clear applies uniformly across all six fields rather than one
+ * being correct by accident.)
+ *
+ * If deleting the key leaves `doc[which]` with no keys of its own, `which`
+ * itself is deleted too — a document that has had every one of its fields
+ * cleared is byte-identical to one that never carried `which` at all, not
+ * left holding a stray `{}` (the same "no leftover empty container" rule
+ * `withEdgeList` already keeps for `doc.edge`).
+ *
+ * Returns the SAME `doc` (`===`), like every other op in this file, when
+ * nothing changes: clearing a key that was never set, or writing the value
+ * already there.
+ */
+function setBannerField(doc, which, key, value) {
+  if (doc === null || typeof doc !== 'object') return doc;
+  if (which !== 'head' && which !== 'foot') return doc;
+  if (typeof key !== 'string' || key === '') return doc;
+
+  const had = doc[which];
+  const hadObj = (had !== null && typeof had === 'object') ? had : null;
+
+  if (value === '') {
+    if (hadObj === null || hadObj[key] === undefined || hadObj[key] === null) return doc;
+    const nextObj = copyObject(hadObj);
+    delete nextObj[key];
+    const next = copyObject(doc);
+    if (Object.keys(nextObj).length === 0) delete next[which];
+    else next[which] = nextObj;
+    return next;
+  }
+
+  if (hadObj !== null && hadObj[key] === value) return doc;
+  const nextObj = copyObject(hadObj || {});
+  nextObj[key] = value;
+  const next = copyObject(doc);
+  next[which] = nextObj;
+  return next;
+}
+
+// ── v3.6.0 Task 13: doc.config.<key> / a lane's own <key> ─────────────────
+
+/**
+ * Write, or clear, one field of `doc.config` — today only `hscale`, the
+ * document-wide field the right-hand 文件 panel's ninth input exposes.
+ *
+ * Same clear-deletes-key discipline as `setBannerField` just above, and for
+ * the identical reason: `value === undefined` deletes the key (and `config`
+ * itself, if that empties it) instead of leaving `''` behind. `undefined`
+ * rather than `''` is the delete sentinel here — unlike the six banner
+ * fields, this field is meant to hold a NUMBER
+ * (`wave-geometry.hscaleOf` gates on `typeof cfg.hscale === 'number'`), and
+ * the caller (`wave-panels.js`'s `commitConfigField`) already turns a
+ * well-formed numeral into a real `number` before this ever runs — an empty
+ * string would be a legitimate thing to want to write if `''` meant
+ * "clear", so the sentinel is moved to a value JSON can never actually hold.
+ *
+ * Returns the SAME `doc` (`===`) when nothing changes, like every other op
+ * in this file.
+ */
+function setConfigField(doc, key, value) {
+  if (doc === null || typeof doc !== 'object') return doc;
+  if (typeof key !== 'string' || key === '') return doc;
+
+  const had = doc.config;
+  const hadObj = (had !== null && typeof had === 'object') ? had : null;
+
+  if (value === undefined) {
+    if (hadObj === null || hadObj[key] === undefined) return doc;
+    const nextObj = copyObject(hadObj);
+    delete nextObj[key];
+    const next = copyObject(doc);
+    if (Object.keys(nextObj).length === 0) delete next.config;
+    else next.config = nextObj;
+    return next;
+  }
+
+  if (hadObj !== null && hadObj[key] === value) return doc;
+  const nextObj = copyObject(hadObj || {});
+  nextObj[key] = value;
+  const next = copyObject(doc);
+  next.config = nextObj;
+  return next;
+}
+
+/**
+ * Write, or clear, one field of the lane at display position `at` — today
+ * `period`/`phase`, the two fields the right-hand Lane panel exposes for
+ * whichever lane the cycle selection currently names.
+ *
+ * Built on `mapLane` (the same bridge `renameLane` above uses), so this
+ * inherits its refusal for good measure: an out-of-range `at` hands the same
+ * `doc` back rather than throwing. `value === undefined` deletes the key,
+ * same sentinel and same reason as `setConfigField` just above —
+ * `wave-geometry.layoutOf` also gates `period`/`phase` on `typeof … ===
+ * 'number'`, so the caller commits a real `number` for a well-formed
+ * numeral, and `''` stays available as an ordinary (if odd) string value
+ * rather than being overloaded to mean "clear".
+ */
+function setLaneField(doc, at, key, value) {
+  if (key !== 'period' && key !== 'phase') return doc;
+  return mapLane(doc, at, function (lane) {
+    const laneObj = isLane(lane) ? lane : {};
+    if (value === undefined) {
+      if (laneObj[key] === undefined) return lane;
+      const next = copyObject(laneObj);
+      delete next[key];
+      return next;
+    }
+    if (laneObj[key] === value) return lane;
+    const next = copyObject(laneObj);
+    next[key] = value;
+    return next;
+  });
+}
+
+// ── v3.5.0 Task 1: edge 字串 ↔ 物件 ────────────────────────────────────────
+// 形狀清單與切字串的方式都是從 pin 住的 wavedrom 3.5.0 原始碼量到的
+// (node_modules/wavedrom/lib/arc-shape.js 的 case 清單、
+//  node_modules/wavedrom/lib/render-arcs.js 的 words[0] 切法)，不是憑記憶。
+/**
+ * 引擎自己認得的 20 種形狀。抄自 pin 住的
+ * node_modules/wavedrom/lib/arc-shape.js 的 case 清單，順序無意義（是集合）。
+ * 不在這份清單裡的形狀我們拒收：畫得出來但引擎畫不出來的線，兩張圖就會不一致。
+ */
+const EDGE_SHAPES = Object.freeze([
+  '-', '~', '-~', '~-', '-|', '|-', '-|-',
+  '->', '~>', '-~>', '~->', '-|>', '|->', '-|->',
+  '<->', '<~>', '<-~>', '<-|>', '<-|->', '+',
+]);
+
+function isNodeLetter(ch) {
+  return typeof ch === 'string' && ch.length === 1 && /[A-Za-z]/.test(ch);
+}
+
+/**
+ * 一條 `edge` entry → `{from, to, shape, label}`，認不得就回 null。
+ *
+ * 切法跟引擎一致（render-arcs.js）：第一個以空白分隔的 token 就是
+ * `<from><shape><to>`，其餘是標籤。差別只有一個，而且是刻意的：引擎用**未
+ * trim** 的原字串配 trim 後算出的長度取標籤位移，所以 '  a~>b hello' 在它那邊
+ * 會得到 'b hello'。我們對 trim 過的字串取，於是前導空白的 entry 也讀得對；
+ * 而 formatEdge 從不產生前導空白，所以我們寫出去的東西引擎一定讀得對。
+ */
+function parseEdge(entry) {
+  if (typeof entry !== 'string') return null;
+  const text = entry.trim();
+  if (text === '') return null;
+  const head = text.split(/\s+/)[0];
+  if (head.length < 3) return null;
+  const from = head.charAt(0);
+  const to = head.charAt(head.length - 1);
+  const shape = head.slice(1, -1);
+  if (!isNodeLetter(from) || !isNodeLetter(to)) return null;
+  if (EDGE_SHAPES.indexOf(shape) === -1) return null;
+  const rest = text.slice(head.length);
+  return { from: from, to: to, shape: shape, label: rest === '' ? '' : rest.slice(1) };
+}
+
+/** `{from, to, shape, label}` → 一條 entry，不合法回 null。 */
+function formatEdge(edge) {
+  if (edge === null || typeof edge !== 'object') return null;
+  if (!isNodeLetter(edge.from) || !isNodeLetter(edge.to)) return null;
+  if (EDGE_SHAPES.indexOf(edge.shape) === -1) return null;
+  const label = typeof edge.label === 'string' ? edge.label.trim() : '';
+  return edge.from + edge.shape + edge.to + (label === '' ? '' : ' ' + label);
+}
+
+// ── v3.5.0 Task 2: node 字母 ────────────────────────────────────────────
+// 釘死的不變量：node 字串的索引是 CELL、不是 cycle——跟 data 陣列的消費規則
+// 同一套座標系，`.` 與 `|` 都各佔一格。
+
+/** 一條 lane 的 `node` 字串 → `{letter: cell}`。 */
+function nodeMapOfLane(lane) {
+  const out = {};
+  const s = (lane !== null && typeof lane === 'object' && typeof lane.node === 'string')
+    ? lane.node : '';
+  for (let i = 0; i < s.length; i += 1) {
+    const ch = s.charAt(i);
+    if (isNodeLetter(ch)) out[ch] = i;
+  }
+  return out;
+}
+
+/**
+ * 全文件的字母表：`letter -> {at, cell}`，`at` 是 display position。
+ *
+ * 走的是 `flattenLanes(doc)`——這個檔案裡唯一一份「哪些是 lane、順序為何」的
+ * 真相（`lanePaths` 本身也是靠它算出來的），第二份會跟它漂移。
+ */
+function nodesOf(doc) {
+  const out = {};
+  const flat = flattenLanes(doc);
+  for (let at = 0; at < flat.length; at += 1) {
+    const map = nodeMapOfLane(flat[at].lane);
+    for (const letter in map) {
+      if (Object.prototype.hasOwnProperty.call(map, letter)) {
+        out[letter] = { at: at, cell: map[letter] };
+      }
+    }
+  }
+  return out;
+}
+
+const NODE_LETTER_POOL =
+  'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ';
+
+/**
+ * 保證 `(at, cell)` 這一格有一個 anchor 字母。
+ *
+ * 已經有就回既有的那個字母與**原本那個 doc**（`===` 相同），呼叫端才分得出
+ * 「什麼都沒發生」。字母池用完（52 個都被佔）回 `{doc, letter: null}`，跟這個
+ * 檔案其餘的 op 一樣，不丟例外。
+ *
+ * `cell` 的上界是這條 lane 實際的 wave 長度（`readLane(lane).cells.length`）—
+ * 跟 `paint`/`setCell`/`setCellRange` 判斷 `lo`/`hi` 合法性用的是同一個
+ * `isIndex(_, n)`，不算第二個「這條 lane 有幾格」的答案。超界跟其他 op 一樣
+ * 回原 doc：畫得出字母的格子但引擎的 timeline 沒畫到那裡，anchor 會落在畫面
+ * 外面（`node_modules/wavedrom/lib/render-arcs.js` 的 labeler 直接拿字串
+ * index 算 x，不會自己夾住範圍）。
+ */
+function ensureNode(doc, at, cell) {
+  const flat = flattenLanes(doc);
+  if (!isIndex(at, flat.length)) return { doc: doc, letter: null };
+  const lane = flat[at].lane;
+  const model = readLane(lane);
+  if (!isIndex(cell, model.cells.length)) return { doc: doc, letter: null };
+  const existing = (typeof lane.node === 'string' && cell < lane.node.length)
+    ? lane.node.charAt(cell) : '';
+  if (isNodeLetter(existing)) return { doc: doc, letter: existing };
+
+  const used = nodesOf(doc);
+  let letter = null;
+  for (let i = 0; i < NODE_LETTER_POOL.length; i += 1) {
+    const c = NODE_LETTER_POOL.charAt(i);
+    if (!Object.prototype.hasOwnProperty.call(used, c)) { letter = c; break; }
+  }
+  if (letter === null) return { doc: doc, letter: null };
+
+  const old = typeof lane.node === 'string' ? lane.node : '';
+  const padded = old.length >= cell ? old : old + new Array(cell - old.length + 1).join('.');
+  const next = padded.slice(0, cell) + letter + padded.slice(cell + 1);
+  return {
+    doc: mapLane(doc, at, function (l) {
+      const copy = copyObject(l);
+      copy.node = next;
+      return copy;
+    }),
+    letter: letter,
+  };
+}
+
+/** 清掉沒有任何 edge 引用的字母；沒有可清的就回原 doc（`===` 相同）。 */
+function pruneNodes(doc) {
+  const referenced = {};
+  const list = (doc !== null && typeof doc === 'object' && Array.isArray(doc.edge))
+    ? doc.edge : [];
+  for (let i = 0; i < list.length; i += 1) {
+    const e = parseEdge(list[i]);
+    if (e !== null) { referenced[e.from] = true; referenced[e.to] = true; }
+  }
+
+  const flat = flattenLanes(doc);
+  let next = doc;
+  for (let at = 0; at < flat.length; at += 1) {
+    const lane = flat[at].lane;
+    if (lane === null || typeof lane !== 'object' || typeof lane.node !== 'string') continue;
+    let changed = false;
+    let s = '';
+    for (let i = 0; i < lane.node.length; i += 1) {
+      const ch = lane.node.charAt(i);
+      if (isNodeLetter(ch) && !referenced[ch]) { s += '.'; changed = true; } else { s += ch; }
+    }
+    if (!changed) continue;
+    const trimmed = s.replace(/\.+$/, '');
+    next = mapLane(next, at, function (l) {
+      const copy = copyObject(l);
+      if (trimmed === '') { delete copy.node; } else { copy.node = trimmed; }
+      return copy;
+    });
+  }
+  return next;
+}
+
+// ── v3.5.0 Task 3: edge 陣列的三個 op ────────────────────────────────────
+
+function edgeListOf(doc) {
+  return (doc !== null && typeof doc === 'object' && Array.isArray(doc.edge)) ? doc.edge : [];
+}
+
+function withEdgeList(doc, list) {
+  const next = copyObject(doc);
+  if (list.length === 0) { delete next.edge; } else { next.edge = list; }
+  return next;
+}
+
+/** 附一條 edge 在陣列尾端；形狀不合法就回原 doc。 */
+function addEdge(doc, edge) {
+  const entry = formatEdge(edge);
+  if (entry === null) return doc;
+  return withEdgeList(doc, edgeListOf(doc).concat([entry]));
+}
+
+/** 換掉第 `index` 條；越界或不合法回原 doc。 */
+function updateEdge(doc, index, edge) {
+  const list = edgeListOf(doc);
+  if (!Number.isInteger(index) || index < 0 || index >= list.length) return doc;
+  const entry = formatEdge(edge);
+  if (entry === null) return doc;
+  const next = list.slice();
+  next[index] = entry;
+  return withEdgeList(doc, next);
+}
+
+/** 刪掉第 `index` 條；越界回原 doc。刪到空陣列時把 `edge` 鍵一起拿掉。 */
+function removeEdge(doc, index) {
+  const list = edgeListOf(doc);
+  if (!Number.isInteger(index) || index < 0 || index >= list.length) return doc;
+  const next = list.slice();
+  next.splice(index, 1);
+  return withEdgeList(doc, next);
+}
+
+// ── v3.5.0 Task 4: moveEdgeEnd ───────────────────────────────────────────
+
+/**
+ * 把第 `index` 條 edge 的某一端重新指到 `(at, cell)`。
+ *
+ * 兩條路，差別在那個字母**還有沒有別人在用**：
+ *
+ *   - 有人共用 → **分岔**：在目標格配一個新字母，只有這一條 entry 改綁。原字母
+ *     留在原處，別條 edge 的 entry 位元組不變。直接搬會把別人的線一起拖走。
+ *   - 只有自己用 → **原地搬移**：字母不換，只是換一格。使用者可能已經把那個名字
+ *     寫進標籤或註解裡，換名字是沒必要的破壞。
+ *
+ * 「有人共用」數的是**端點**（`from` 跟 `to` 各算一次），不是「數到幾條別的
+ * edge」——一條 self-loop（`b~>b`）自己的 from 跟 to 就佔掉兩個端點，所以永遠
+ * 落在分岔路，即使沒有任何別條 edge 引用同一個字母。這是故意的：原地搬移會把
+ * self-loop 的兩端一起拖走，那正是這個函式存在的目的要擋下的事。如果哪天有人
+ * 把判斷「簡化」成數「有幾條別的 edge 引用這個字母」，self-loop 會被悄悄改判成
+ * 原地搬移，重新引進同一個 bug——所以數端點，不要數 edge。
+ *
+ * 目標格如果已經被**另一個**字母佔走（不是 movingLetter 自己現在的格子，也不是
+ * 另一端的格子——那兩種是下面兩個 no-op），原地搬移絕不能覆寫它：那會把佔著那
+ * 格的字母原本掛著的別條 edge 無聲拔線。這種情況併進分岔路，重用已經在那裡的
+ * 字母（`ensureNode` 本來就會這麼做），而不是發明第三種行為。
+ *
+ * 三種 no-op 回**原本那個 doc**（`===` 相同），呼叫端據此決定不推 undo：拖回原格、
+ * 拖到自己另一端（會變成 `a~>a`）、目標不存在（lane 越界，或 cell 超過那條 lane
+ * 實際的長度——跟 `ensureNode` 同一顆 `isIndex(_, readLane(lane).cells.length)`
+ * 上界，不是第二個「這條 lane 有幾格」的答案）。
+ */
+function moveEdgeEnd(doc, index, end, at, cell) {
+  if (end !== 'from' && end !== 'to') return doc;
+  const list = edgeListOf(doc);
+  if (!Number.isInteger(index) || index < 0 || index >= list.length) return doc;
+  const edge = parseEdge(list[index]);
+  if (edge === null) return doc;
+
+  const flat = flattenLanes(doc);
+  if (!isIndex(at, flat.length)) return doc;
+  if (!Number.isInteger(cell) || cell < 0) return doc;
+  // 跟 ensureNode 用同一顆上界（readLane(...).cells.length），不是第二個「這條
+  // lane 有幾格」的答案：畫得出字母的格子但引擎的 timeline 沒畫到那裡，anchor
+  // 會落在畫面外面。原地搬移這條路先前漏了這一段，讓 cell 可以超出 lane 長度。
+  const targetModel = readLane(flat[at].lane);
+  if (!isIndex(cell, targetModel.cells.length)) return doc;
+
+  const nodes = nodesOf(doc);
+  const movingLetter = edge[end];
+  const otherLetter = edge[end === 'from' ? 'to' : 'from'];
+
+  const here = nodes[movingLetter];
+  if (here !== undefined && here.at === at && here.cell === cell) return doc; // 拖回原格
+  const there = nodes[otherLetter];
+  if (there !== undefined && there.at === at && there.cell === cell) return doc; // a~>a
+
+  let sharers = 0;
+  for (let i = 0; i < list.length; i += 1) {
+    const e = parseEdge(list[i]);
+    if (e === null) continue;
+    if (e.from === movingLetter) sharers += 1;
+    if (e.to === movingLetter) sharers += 1;
+  }
+
+  // 目標格是不是已經有別的字母佔著（跟 movingLetter/otherLetter 都不同——那兩種
+  // 情況上面兩個 no-op 已經攔下來了）。原地搬移絕不能覆寫別人的 anchor，佔著就
+  // 併進下面的分岔路，讓 ensureNode 重用那個已經在那裡的字母。
+  let occupant = null;
+  for (const letter in nodes) {
+    if (Object.prototype.hasOwnProperty.call(nodes, letter)) {
+      const pos = nodes[letter];
+      if (pos.at === at && pos.cell === cell) { occupant = letter; break; }
+    }
+  }
+
+  const exclusive = sharers <= 1 && occupant === null;
+
+  if (exclusive && here !== undefined) {
+    // 原地搬移：把字母從舊格拿掉，放到新格。entry 不動。
+    // 這兩次 mapLane 必須依序執行、不能合併成一次：第二次 map 讀到的 `copy.node`
+    // 是「第一次已經把舊格清成 '.' 之後」的 lane 狀態。同一條 lane 內搬移（`here.at
+    // === at`）靠的正是這個先後關係——先清舊格、再往（可能同一個）新格寫——才不會
+    // 用到清格前的 stale node 字串、或把新舊兩個位置同時留著字母。
+    let next = mapLane(doc, here.at, function (l) {
+      const copy = copyObject(l);
+      const s = typeof copy.node === 'string' ? copy.node : '';
+      const cleared = s.slice(0, here.cell) + '.' + s.slice(here.cell + 1);
+      const trimmed = cleared.replace(/\.+$/, '');
+      if (trimmed === '') { delete copy.node; } else { copy.node = trimmed; }
+      return copy;
+    });
+    next = mapLane(next, at, function (l) {
+      const copy = copyObject(l);
+      const s = typeof copy.node === 'string' ? copy.node : '';
+      const padded = s.length >= cell ? s : s + new Array(cell - s.length + 1).join('.');
+      copy.node = padded.slice(0, cell) + movingLetter + padded.slice(cell + 1);
+      return copy;
+    });
+    return next;
+  }
+
+  // 分岔：目標格配一個字母（那一格已經有字母就用它），只有這一條改綁。
+  const ensured = ensureNode(doc, at, cell);
+  if (ensured.letter === null) return doc;
+  const nextEdge = copyObject(edge);
+  nextEdge[end] = ensured.letter;
+  return pruneNodes(updateEdge(ensured.doc, index, nextEdge));
+}
+
 module.exports = {
   parseSource, patchSource,
   expandWave, collapseWave, levelsOf,
   setCell, setCellRange, insertCycles, deleteCycles, copyCycles, pasteCycles,
-  addLane, removeLane, moveLane, renameLane,
+  dataSlotOf, setDataAt,
+  addLane, removeLane, moveLane, duplicateLane, renameLane, groupLanes, ungroupLanes,
   lanePath, lanePaths, laneInsertPath, laneRemovePath, laneRemovePaths,
+  setBannerField, setConfigField, setLaneField,
+  parseEdge, formatEdge, EDGE_SHAPES,
+  nodesOf, ensureNode, pruneNodes,
+  addEdge, updateEdge, removeEdge, moveEdgeEnd,
   MAX_DEPTH,
 };