@helping-ai-workflow/md2doc 3.3.0 → 3.4.0

package/lib/editor/inline-md.js

@@ -115,29 +115,128 @@
       unsupported.push('A');
       return '';
     }
-    const label = walkChildren(node.childNodes, unsupported);
+    const label = walkChildren(node.childNodes, unsupported).md;
     return '[' + label + '](' + (href || '') + ')';
   }
 
+  // v3.4.0 / backlog 3 (Ruling T6-7, then a fix-round regression): STRONG
+  // and EM each emit a fixed, context-blind '*'-based delimiter for their
+  // own tag — '**'/'**' or '*'/'*' — with no awareness of what the
+  // accumulated sibling output already ends with. CommonMark scans the
+  // *raw character stream*, not the DOM/AST, and a "delimiter run" is a
+  // maximal span of identical adjacent characters: when one node's closing
+  // '*' is directly followed (no separating character) by the next
+  // sibling's opening '*', the two independent single-char delimiter
+  // EVENTS silently fuse into one length-2+ RUN in the emitted text, which
+  // marked's own flanking/pairing algorithm then matches on its own terms
+  // — not necessarily the pairing the DOM implied. Measured (task-8
+  // report): DOM `<em><code>code</code></em><em>text</em>` serialized to
+  // `*`code`**text*` — the merged `**` is grabbed by marked as its own
+  // delimiter run, and the FIRST <em> is dropped entirely, reappearing as
+  // two literal '*' characters around the code span on reload.
+  //
+  // The first version of this fix guarded on ANY trailing '*', which
+  // regressed a real journey scenario: `<em>it</em>` immediately followed
+  // by `<strong><em>al</em> bold</strong>` — EM's closing 1 star touching
+  // STRONG's opening 2+1 stars — serializes WITHOUT any guard to
+  // `*it****al* bold**`, which marked already parses correctly as-is
+  // (`<em>it</em><strong><em>al</em> bold</strong>`); inserting a comment
+  // there changed already-correct bytes for no reason, and
+  // editor-journey.test.js caught it. A 100-context sweep (reviewer-built:
+  // 5 front contexts × 5 back contexts × the 4 direct EM/STRONG pairings)
+  // measured the actual split: SAME-tag adjacency (EM-then-EM,
+  // STRONG-then-STRONG) breaks 50/50; CROSS-tag adjacency (EM-then-STRONG,
+  // STRONG-then-EM) is correct 50/50 — `*a*` immediately followed by
+  // `**b**` is exactly 3 touching stars, which CommonMark's own delimiter
+  // matching splits correctly without any help.
+  //
+  // Fix (task-8 report has the re-measured matrix): guard on the TAG of
+  // whichever STRONG/EM most recently closed at THIS sibling level, not on
+  // the trailing character. `lastMarkTag` (below) tracks it; a STRONG/EM
+  // node inserts `<!-- -->` only when `lastMarkTag` equals its OWN tag.
+  // `<!-- -->` contains no '*', so when it does fire it always ends the
+  // preceding run and starts a fresh one, regardless of what characters
+  // sit on either side — unlike switching to `_`/`__`, which was tried and
+  // rejected: `_`-based emphasis carries CommonMark's intraword
+  // restriction, and a switched closing `_` glued directly to a following
+  // word character (no space) fails to close at all (verified:
+  // `*`code`*_text_word` leaves `_text_word` unparsed, while the
+  // HTML-comment form parses `text` as EM in the same shape). The comment
+  // is inert on read-back too: `walkChildren` only handles nodeType 3
+  // (text) and 1 (element) and silently skips anything else (comment nodes
+  // are nodeType 8), so it never leaks into canWysiwyg's `unsupported`
+  // list or into a later re-serialize — a reparsed document with the
+  // comment still in the DOM just re-triggers this same guard on the next
+  // save, it does not accumulate.
+  //
+  // `lastMarkTag` also fixes review Minor 1 (a false trigger on a literal,
+  // already-escaped asterisk) as a side effect, with no regex needed: a
+  // TEXT node resets `lastMarkTag` to null whenever it contributes any
+  // characters at all, because escapeText() unconditionally escapes every
+  // literal '*' a user types — a text node's own trailing character is
+  // therefore NEVER a live, still-open '*' that a following STRONG/EM
+  // could collide with, so there is nothing to compare tags against. The
+  // text "a*" (typed literally, no italics intent) followed by an EM was a
+  // MORE common false trigger than the real bug under the old last-char
+  // check: it inserted a needless `<!-- -->` even though "a\*<em>x</em>"
+  // already round-trips correctly on its own.
+  //
+  // Every OTHER node type that contributes real, non-empty output (CODE,
+  // A, BR, DEL/S, U) also resets `lastMarkTag` to null: none of them ever
+  // end their own output in a live '*' (backtick, ')'/']]', '>', '~~'
+  // respectively), so nothing after them can be touching a star run.
+  // Nodes that contribute NOTHING to `out` (an empty text node, a
+  // `<span>` carrying attributes, an unrecognized tag pushed to
+  // `unsupported`) leave `lastMarkTag` untouched — correctly preserving
+  // whatever WAS touching before them, since they added no separating
+  // character.
+  //
+  // DIV and transparent (attribute-less) SPAN are genuine passthroughs —
+  // browsers wrap plain runs in bare <span>s, and a top-level <div> line
+  // splices its children inline rather than nesting — so `EM` immediately
+  // followed by `<span><em>x</em></span>` (or wrapped in a <div>) must
+  // still be treated as touching, same-tag EM adjacency: this is exactly
+  // the "透明節點覆蓋一點都沒少" requirement the coordinator called out.
+  // Both branches therefore propagate the RECURSIVE call's own
+  // `lastMarkTag` outward whenever that recursive call actually
+  // contributed characters (`inner.md.length`); if it contributed nothing,
+  // the DIV/SPAN itself contributed nothing either (SPAN) or only its own
+  // leading `<br>` (DIV, non-first segment) — a `<br>` is real, `*`-free
+  // output, so it resets to null; truly nothing added at all leaves the
+  // incoming `lastMarkTag` untouched, same as any other zero-output node.
+
   // Walk a sibling list. A top-level <div> is a contenteditable line-break
   // artifact (browsers split lines with <div> rather than <br>), so each
   // <div> boundary after the first emits a <br> and its children are
-  // spliced inline, never nested further.
+  // spliced inline, never nested further. Returns `{ md, lastMarkTag }` —
+  // `lastMarkTag` is this call's OWN trailing-star-boundary state (see
+  // above), needed by DIV/SPAN passthrough and by nothing else: a caller
+  // that wraps its own delimiter around a recursive call's content (EM,
+  // STRONG, DEL/S, U, the citation label) only ever needs `.md`, because
+  // its own outer delimiter is a fixed, known tag regardless of what's
+  // nested inside.
   function walkChildren(nodes, unsupported) {
     let out = '';
     let firstSegment = true;
+    let lastMarkTag = null;
     for (let i = 0; i < nodes.length; i++) {
       const node = nodes[i];
       if (node.nodeType === 3) {
-        out += escapeText(node.textContent);
+        const text = escapeText(node.textContent);
+        out += text;
+        if (text.length) lastMarkTag = null;
         firstSegment = false;
         continue;
       }
       if (node.nodeType !== 1) continue;
       const name = node.nodeName;
       if (name === 'DIV') {
-        if (!firstSegment) out += '<br>';
-        out += walkChildren(node.childNodes, unsupported);
+        let added = '';
+        if (!firstSegment) added += '<br>';
+        const inner = walkChildren(node.childNodes, unsupported);
+        added += inner.md;
+        out += added;
+        if (added.length) lastMarkTag = inner.md.length ? inner.lastMarkTag : null;
         firstSegment = false;
         continue;
       }
@@ -145,18 +244,24 @@
         if (spanHasAttributes(node)) {
           unsupported.push(name);
         } else {
-          out += walkChildren(node.childNodes, unsupported);
+          const inner = walkChildren(node.childNodes, unsupported);
+          out += inner.md;
+          if (inner.md.length) lastMarkTag = inner.lastMarkTag;
         }
         firstSegment = false;
         continue;
       }
       if (name === 'STRONG' || name === 'B') {
-        out += '**' + walkChildren(node.childNodes, unsupported) + '**';
+        out += (lastMarkTag === 'STRONG' ? '<!-- -->' : '') +
+          '**' + walkChildren(node.childNodes, unsupported).md + '**';
+        lastMarkTag = 'STRONG';
         firstSegment = false;
         continue;
       }
       if (name === 'EM' || name === 'I') {
-        out += '*' + walkChildren(node.childNodes, unsupported) + '*';
+        out += (lastMarkTag === 'EM' ? '<!-- -->' : '') +
+          '*' + walkChildren(node.childNodes, unsupported).md + '*';
+        lastMarkTag = 'EM';
         firstSegment = false;
         continue;
       }
@@ -166,7 +271,8 @@
         // accepted on input (some contenteditable/paste paths produce it)
         // but the toolbar/serializer always speak DEL, matching what marked
         // itself emits.
-        out += '~~' + walkChildren(node.childNodes, unsupported) + '~~';
+        out += '~~' + walkChildren(node.childNodes, unsupported).md + '~~';
+        lastMarkTag = null;
         firstSegment = false;
         continue;
       }
@@ -181,17 +287,20 @@
         // backtick, literal `<u>` typed as plain text is already escaped by
         // the `<` -> `&lt;` rule above, so it can never collide with a real
         // toolbar-made underline.
-        out += '<u>' + walkChildren(node.childNodes, unsupported) + '</u>';
+        out += '<u>' + walkChildren(node.childNodes, unsupported).md + '</u>';
+        lastMarkTag = null;
         firstSegment = false;
         continue;
       }
       if (name === 'CODE') {
         out += serializeCode(node);
+        lastMarkTag = null;
         firstSegment = false;
         continue;
       }
       if (name === 'A') {
         out += serializeAnchor(node, unsupported);
+        lastMarkTag = null;
         firstSegment = false;
         continue;
       }
@@ -221,18 +330,19 @@
         const hardBreak = typeof node.getAttribute === 'function' &&
           node.getAttribute('data-hard-break') === '1';
         out += hardBreak ? '\\\n' : '<br>';
+        lastMarkTag = null;
         firstSegment = false;
         continue;
       }
       unsupported.push(name);
       firstSegment = false;
     }
-    return out;
+    return { md: out, lastMarkTag };
   }
 
   function serializeInline(rootEl) {
     const unsupported = [];
-    const md = walkChildren(rootEl.childNodes, unsupported);
+    const md = walkChildren(rootEl.childNodes, unsupported).md;
     return { md, unsupported };
   }
 

package/lib/editor/lineops.js

@@ -23,12 +23,48 @@
     );
   }
 
+  // ── v3.4.0 batch3 Task 7 fix 2: what "saved" is allowed to mean ──────────
+  //
+  // `_savedDepth` marks WHERE ON `_done` the bytes that are on disk were
+  // reached. It was an unconditional index, and an index into a stack that can
+  // be rewound is not a fact about the document — it is a second record of one,
+  // and it drifts.
+  //
+  // MEASURED on the shipped v3.3.0 behaviour, with no wave editor anywhere near
+  // it: type into a paragraph, commit, Ctrl+S, Ctrl+Z, then make one more
+  // ordinary edit. `_done.length` is 1 again and `_savedDepth` is still 1, so
+  // `dirtyDepth` is 0 — `documentIsDirty()` answers false, the title dot goes
+  // out, the save button greys, `beforeunload` does not fire, and the conflict
+  // banner's Reload discards BOTH the undone save and the new edit without
+  // asking. The depth arithmetic said "you are standing where you saved"; the
+  // user was standing somewhere else entirely, because the branch that led to
+  // the save point had been replaced.
+  //
+  // The invariant this restores is the only one that is worth anything here:
+  // **"not dirty" means what is in memory equals what is on disk.** A counter
+  // that can pass through zero from below cannot express it, so the marker is
+  // INVALIDATED — set to null — the moment history diverges past it, which is
+  // exactly the moment a `push()` happens below it. From then on the saved
+  // state is not reachable anywhere on this stack and the honest answer to "are
+  // we standing on it" is no, until `markSaved()` establishes a new one.
+  //
+  // Undo alone does NOT invalidate: undo then redo puts the same ops back and
+  // the marker still names the same state, which is why the rewind itself is
+  // not the divergence — the push that replaces the rewound branch is.
   function UndoStack() {
     this._done = [];
     this._undone = [];
+    // null = "the saved state is not on this stack any more". Callers must not
+    // read it as a number; ask `isDirty()`.
     this._savedDepth = 0;
   }
   UndoStack.prototype.push = function (op) {
+    if (this._savedDepth !== null && this._done.length < this._savedDepth) {
+      // History has been rewound past the save point and is now growing a
+      // different branch: the ops that produced the saved bytes are gone from
+      // this stack and no sequence of undo/redo can get back to them.
+      this._savedDepth = null;
+    }
     this._done.push(op);
     this._undone.length = 0;
   };
@@ -60,11 +96,162 @@
     const span = { startLine: op.startLine, endLine: op.startLine + op.after.length - 1 };
     return { lines: replaceLines(lines, span.startLine, span.endLine, op.before).lines, op };
   };
+  // v3.4.0 batch3 Task 7 fix 1 (F3) — read and write the REDO tail.
+  //
+  // `push()` clears `_undone`, and that is correct for an ordinary edit: once
+  // the document has moved forward, the branch that was undone is gone. It is
+  // NOT correct for an edit that is later withdrawn as if it had never
+  // happened — `discardTop()` can put the bytes and the depth back, but it has
+  // no way to put the branch back, so a caller that discards its own ops
+  // silently consumes a redo the user had before it started. MEASURED on the
+  // wave editor: type into a paragraph, commit, Ctrl+Z (the edit is redoable),
+  // open the wave editor, paint, Escape — and Ctrl+Y then brings nothing back,
+  // over a document that is byte-identical to the one that had the redo.
+  //
+  // So the tail is a value a caller can take before it starts and hand back
+  // when it withdraws. Deliberately two plain accessors rather than a
+  // "transaction" API: the only caller is `finishWaveSession()`, the copies
+  // keep `_undone` unaliased, and an ordinary push still clears it exactly as
+  // before.
+  UndoStack.prototype.redoTail = function () {
+    return this._undone.slice();
+  };
+  UndoStack.prototype.setRedoTail = function (tail) {
+    this._undone = Array.isArray(tail) ? tail.slice() : [];
+  };
+  // Does memory differ from disk? The one question the product actually asks,
+  // and a boolean rather than a distance precisely because a distance is what
+  // walked through zero. `documentIsDirty()` in client.js reads this.
+  UndoStack.prototype.isDirty = function () {
+    return this._savedDepth === null || this._done.length !== this._savedDepth;
+  };
+  // How far the stack has moved since the save point, for diagnostics and for
+  // tests that want to see the shape of a sequence. When the marker has been
+  // invalidated there IS no distance — the state it named is not on the stack —
+  // so this answers with a value that is deliberately never 0, and callers that
+  // only want the yes/no must ask `isDirty()` instead of comparing this.
   Object.defineProperty(UndoStack.prototype, 'dirtyDepth', {
-    get() { return this._done.length - this._savedDepth; },
+    get() {
+      if (this._savedDepth === null) return this._done.length + 1;
+      return this._done.length - this._savedDepth;
+    },
+  });
+  // How many ops are on the done-stack. Exposed so a caller that pushed N ops
+  // can check that the top N are still its own — a question about the STACK,
+  // with no premise about the save marker, which is what makes it composable
+  // with `savedDepth` below rather than entangled with it.
+  Object.defineProperty(UndoStack.prototype, 'depth', {
+    get() { return this._done.length; },
+  });
+  // WHERE the marker is, or null when the saved state is not on this stack any
+  // more. A caller that needs to reason about a range of the stack — "would
+  // removing my own N ops destroy the state disk was written from?" — needs the
+  // position, not the distance. It is deliberately nullable rather than a
+  // sentinel number: arithmetic on it is exactly the mistake this whole rework
+  // is about, and `null` makes that arithmetic loud instead of plausible.
+  Object.defineProperty(UndoStack.prototype, 'savedDepth', {
+    get() { return this._savedDepth; },
   });
-  UndoStack.prototype.markSaved = function () {
-    this._savedDepth = this._done.length;
+  /**
+   * A receipt for "these are the bytes I am about to write to disk".
+   *
+   * Taken BEFORE the save request leaves, and handed back to `markSaved()` when
+   * the response lands. See markSaved() for the measured race this closes.
+   *
+   * The receipt is a depth plus the IDENTITY of the op at that depth's
+   * boundary. The depth alone is not enough: the user can undo and re-edit
+   * during a round trip, and the stack is then back at the same depth holding a
+   * different op — measured, that combination marked bytes as saved that disk
+   * had never held. Op objects are created fresh by each commit, so identity is
+   * an exact fingerprint and costs a reference.
+   *
+   * ── Why ONE boundary op is enough (fix 4 / R5) ─────────────────────────
+   *
+   * It looks like an under-check: the receipt fingerprints a single op, yet it
+   * is trusted to mean "the whole prefix `_done[0 .. depth-1]` is unchanged".
+   * It holds, and the argument is worth having in one place rather than
+   * reconstructed from four:
+   *
+   *   1. The timeline is only ever edited at its TOP. `push()` appends,
+   *      `undo()` moves the top entry onto `_undone`, `redo()` moves it back,
+   *      and `discardTop()` drops it. Nothing in this file writes at an
+   *      interior index — there is no splice, no sort, no assignment to
+   *      `_done[i]`. So a prefix can only change by first being exposed, i.e.
+   *      by everything above it coming off.
+   *   2. Therefore, if the op at index `depth-1` is still that same object,
+   *      nothing ever popped BELOW `depth-1` in between — had it, that op would
+   *      have come off too, and the only way an identical object returns is
+   *      `redo()`, which also restores every entry below it unchanged (it pops
+   *      `_undone` in the exact reverse order `undo()` pushed it).
+   *   3. Identity, not equality: a commit builds a fresh `{startLine, endLine,
+   *      before, after}` literal every time, so two different edits can never
+   *      share an object, and a re-edit that happens to produce the same bytes
+   *      is still a different object — which is the conservative direction.
+   *   4. `setRedoTail()` is the one place `_undone` is replaced wholesale, and
+   *      it is handed back exactly the array `redoTail()` copied out, so the
+   *      objects in it are the same objects. A wave session's withdrawal
+   *      therefore restores the timeline, it does not fabricate one.
+   *
+   * The check is conservative where it is imperfect: anything it cannot prove
+   * unchanged reads as changed, and a refused receipt leaves the document
+   * DIRTY. Its failure direction is over-warning.
+   */
+  UndoStack.prototype.saveToken = function () {
+    return {
+      depth: this._done.length,
+      op: this._done.length === 0 ? null : this._done[this._done.length - 1],
+    };
+  };
+
+  /**
+   * Where on the timeline `token.depth - 1` now lives, whether it has since been
+   * undone or not — `undefined` when that index is off the end of both stacks.
+   *
+   * An op that was undone during a save round trip is still the same op and can
+   * still be redone back into place, so it must NOT read as a divergence; it
+   * has merely moved from `_done` onto `_undone`, which is a LIFO, hence the
+   * mirrored index.
+   */
+  function timelineOpAt(stack, index) {
+    if (index < 0) return null;
+    if (index < stack._done.length) return stack._done[index];
+    const j = stack._done.length + stack._undone.length - 1 - index;
+    if (j < 0 || j >= stack._undone.length) return undefined;
+    return stack._undone[j];
+  }
+
+  /**
+   * Record that disk now holds the bytes the given receipt describes.
+   *
+   * MEASURED before the receipt existed, with no wave editor involved: type,
+   * commit, Ctrl+S, then press Ctrl+Z while the request is still in flight. The
+   * 200 arrived and marked whatever depth happened to exist AT THAT MOMENT —
+   * the post-undo one — as the saved point, so `isDirty()` answered false over a
+   * document that differs from disk. All three nets failed together there: the
+   * title dot, the unload guard, AND the conflict check (the response had just
+   * advanced `mtimeMs`, so the next save would not 409 either). Closing the tab
+   * left on disk an edit the user had explicitly undone.
+   *
+   * With a receipt the marker is established against the depth the bytes were
+   * taken from, not the depth the reply happened to find — and only if the
+   * timeline at that boundary is still the same one. Where it is not, the saved
+   * state is not reachable on this stack at all and the marker is invalidated,
+   * which is the same answer `push()` gives for the same reason.
+   *
+   * No argument still means "right here, right now", which is what every
+   * synchronous caller and every test wants.
+   */
+  UndoStack.prototype.markSaved = function (token) {
+    if (token === undefined || token === null) {
+      this._savedDepth = this._done.length;
+      return true;
+    }
+    if (timelineOpAt(this, token.depth - 1) !== token.op) {
+      this._savedDepth = null;
+      return false;
+    }
+    this._savedDepth = token.depth;
+    return true;
   };
 
   return { replaceLines, insertLines, shiftBlocks, UndoStack };