@helping-ai-workflow/md2doc 3.5.0 → 3.6.0

package/lib/editor/client.js

@@ -17542,7 +17542,8 @@
     // An older cached page that predates the injection must degrade to "the
     // button does nothing visible", never to a throw out of a click handler.
     if (!ui || !mods || !mods['wave-store.js'] || !mods['wave-codec.js'] ||
-        !mods['wave-geometry.js']) return;
+        !mods['wave-geometry.js'] || !mods['wave-draw.js'] ||
+        !mods['wave-panels.js']) return;
     if (waveEditor !== null) return;
     hideWaveEditBtn();
 
@@ -17603,8 +17604,27 @@
         document: document,
         host: document.body,
         source: body.text,
+        // v3.6.0 Task 15: which block in this document the editor is over,
+        // for the 匯出 filename (`exportName()` in wave-ui.js). The editor
+        // cannot derive it — it is handed one block's TEXT and nothing about
+        // where that text came from — and two diagrams in one document
+        // exporting under the same filename is a silent overwrite in the
+        // user's downloads folder.
+        blockIndex: id,
+        // …and the document's own name for the other half of that filename.
+        // `baseTitle`, NOT `document.title`: this file owns the page title
+        // while a session is open and writes the dirty marker into it
+        // (`(documentIsDirty() ? '● ' : '') + baseTitle`, above). Handing over
+        // the decorated title would land a user who has actually edited with
+        // `●-doc-wave-1.svg`, and a user who has not with the clean name —
+        // i.e. it would look right in exactly the case nobody exports in.
+        // `baseTitle` is the title as it was before this file touched it,
+        // which is md2doc's `path.basename(src, '.md')`.
+        fileLabel: baseTitle,
         codec: mods['wave-codec.js'],
         geometry: mods['wave-geometry.js'],
+        draw: mods['wave-draw.js'],
+        panels: mods['wave-panels.js'],
         createStore: mods['wave-store.js'].createStore,
         // The store's own answer to「哪一條 lane 是哪一條」across one operation,
         // handed over rather than re-derived: the editor's cell cursor and its
@@ -17760,10 +17780,29 @@
 
   /** One refusal, recorded and raised. The only producer of `waveUnwrittenEdit`. */
   function waveRefuseGesture(seam, reason) {
-    // A refusal is not papered over and not rolled back. wave-ui has already
-    // said so on the status line, which is where the user's eyes are, but a
-    // status line is not a decision — this raises it as a banner naming the
-    // lines it could not write and waits for the user to acknowledge it.
+    // A refusal is not papered over and not rolled back. This raises it as a
+    // banner naming the lines it could not write, and waits for the user to
+    // acknowledge it.
+    //
+    // v3.6.0 Task 16 fix round 2 (N1) withdraws the reason that used to stand
+    // here — "wave-ui has already said so on the status line, which is where
+    // the user's eyes are, but a status line is not a decision". wave-ui does
+    // write the reason there (`afterStoreMoved`'s
+    // `這個改動沒辦法只改幾個位元組寫回去：…`), but that line is ONE
+    // `role="status"` string and the next thing the same gesture says
+    // replaces it. MEASURED on the journey fixture: the fourth Alt+↑ of the
+    // Task 16 scenario refuses — "the value at [\"signal\"] is or contains an
+    // object, so replacing it would re-serialise part of the document's
+    // structure…" — and `moveSelectedLane`'s landing line
+    // (`搬動的 lane 落在群組「bus」裡`) is written straight after it, so the
+    // sentence the user is left looking at reads like success.
+    //
+    // That is a FAMILY, not one caller: `addLaneFromToolbar` and 複製 have
+    // written over the same refusal since before Task 16, and the rail's drag
+    // drop announces nothing at all. Re-ordering those says is behaviour, and
+    // it is parked as a next-version follow-up rather than done here. So the
+    // banner below is not a nicety layered on a status line that already said
+    // it — it is the only part of the refusal that cannot be clobbered.
     seam.unwritten = true;
     waveUnwrittenEdit = true;
     setDirty();

package/lib/editor/server.js

@@ -56,7 +56,7 @@ const TURNDOWN_SRC = fs.readFileSync(
   require.resolve('turndown/lib/turndown.browser.umd.js'), 'utf8');
 const PASTE_MD_SRC = fs.readFileSync(path.join(__dirname, 'paste-md.js'), 'utf8');
 
-// v3.4.0 batch3 Task 6: the wavedrom GUI's four modules.
+// v3.4.0 batch3 Task 6: the wavedrom GUI's modules.
 //
 // wave-codec.js / wave-geometry.js / wave-store.js are plain CommonJS ON
 // PURPOSE, and rewriting them into the UMD header every other module here uses
@@ -67,11 +67,28 @@ const PASTE_MD_SRC = fs.readFileSync(path.join(__dirname, 'paste-md.js'), 'utf8'
 // the browser gets them through the small CommonJS shim below instead —
 // the module text itself is inlined byte for byte.
 //
+// v3.6.0 Task 1: wave-draw.js joins them, plain CommonJS too — a pure
+// extraction out of wave-ui.js, not test-guarded like the other three, but
+// needing the identical shim for a different reason: wave-ui.js itself is
+// injected as a bare <script> with no `require()` of its own (see its own
+// header comment), so it cannot resolve `require('./wave-draw.js')` in the
+// browser any more than the page around it could. `createWaveEditor()` takes
+// it in as `opts.draw` instead, the same way it already takes `opts.codec`
+// and `opts.geometry`.
+//
+// v3.6.0 Task 2: wave-panels.js joins them for the identical reason —
+// another pure extraction out of wave-ui.js (the toolbar, the right-hand
+// panels and the lane rail this time), needing the same shim because
+// wave-ui.js still cannot `require()` anything in the browser. Taken in as
+// `opts.panels`.
+//
 // wave-ui.js is UMD like its neighbours and needs no shim; in the page it
-// defines `window.md2docWaveUi` and takes the other three as parameters.
+// defines `window.md2docWaveUi` and takes the other five as parameters.
 const WAVE_CODEC_SRC = fs.readFileSync(path.join(__dirname, 'wave-codec.js'), 'utf8');
 const WAVE_GEOMETRY_SRC = fs.readFileSync(path.join(__dirname, 'wave-geometry.js'), 'utf8');
 const WAVE_STORE_SRC = fs.readFileSync(path.join(__dirname, 'wave-store.js'), 'utf8');
+const WAVE_DRAW_SRC = fs.readFileSync(path.join(__dirname, 'wave-draw.js'), 'utf8');
+const WAVE_PANELS_SRC = fs.readFileSync(path.join(__dirname, 'wave-panels.js'), 'utf8');
 const WAVE_UI_SRC = fs.readFileSync(path.join(__dirname, 'wave-ui.js'), 'utf8');
 
 // One CommonJS module, wrapped so a plain <script> can carry it.
@@ -585,6 +602,8 @@ async function createEditorServer({
           waveModuleTag('wave-codec.js', WAVE_CODEC_SRC) +
           waveModuleTag('wave-geometry.js', WAVE_GEOMETRY_SRC) +
           waveModuleTag('wave-store.js', WAVE_STORE_SRC) +
+          waveModuleTag('wave-draw.js', WAVE_DRAW_SRC) +
+          waveModuleTag('wave-panels.js', WAVE_PANELS_SRC) +
           `<script>${WAVE_UI_SRC}</script>\n` +
           `<script>${clientJs}</script>\n`;
         // Splice at the LAST "</body>" — the document's real closing tag.

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.
  *
@@ -2838,8 +2917,10 @@ function groupLanes(doc, ats, label) {
  * 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 (see wave-ui.js's
- * own comment on `directFirstLaneOf`).
+ * 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.
@@ -2919,6 +3000,82 @@ function setBannerField(doc, which, key, value) {
   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 清單、
@@ -3240,7 +3397,7 @@ module.exports = {
   dataSlotOf, setDataAt,
   addLane, removeLane, moveLane, duplicateLane, renameLane, groupLanes, ungroupLanes,
   lanePath, lanePaths, laneInsertPath, laneRemovePath, laneRemovePaths,
-  setBannerField,
+  setBannerField, setConfigField, setLaneField,
   parseEdge, formatEdge, EDGE_SHAPES,
   nodesOf, ensureNode, pruneNodes,
   addEdge, updateEdge, removeEdge, moveEdgeEnd,