@helping-ai-workflow/md2doc 3.12.1 → 3.13.0

package/lib/editor/client.js

@@ -650,6 +650,12 @@
   // v3.4.0 batch3 Task 7 fix 2 (MUST-FIX 1) — may a wave session's own commits
   // simply be popped off the document stack?
   //
+  // Since wave redesign Task 11 its one caller is the net-zero unwind
+  // (unwindWaveOps(), when a session's drawing is back at its opening bytes):
+  // closing the editor never pops anything any more. The MEASURED sequences
+  // below that end in an Escape were taken on the retired Escape discard,
+  // which asked these same two questions.
+  //
   // Two questions, asked separately, each answered by the stack itself rather
   // than by arithmetic over a quantity that can be wrong:
   //
@@ -707,8 +713,36 @@
     return stack.savedDepth === null || stack.savedDepth <= seam.baseDepth;
   }
 
+  // Wave redesign Task 11 — does a whole-session undo (or its Ctrl+Y) offer
+  // still describe the document? `now` is `{ lines, depth, burstOpen }`. The
+  // offer holds only while `lines` is the very array it was made over (every
+  // edit, undo, redo and reload replaces it — equal bytes in a new array still
+  // mean something happened), the stack is at the same depth, and no burst
+  // holds typing `lines` has not seen yet. Pure, so test/editor-client.test.js
+  // drives it; waveUndoOfferValid() / waveRedoOfferValid() feed it the live
+  // state.
+  function waveOfferHolds(offer, now) {
+    return offer !== null && offer !== undefined && now.lines === offer.lines &&
+      now.depth === offer.depth && now.burstOpen !== true;
+  }
+
+  // Task 11 fix round 1 (Ruling R24) — may Ctrl+Y re-apply a whole-session undo
+  // as one step? `ro` is `{ baseDepth, ops }`, `ops` the entries the undo
+  // popped, in pop order; `now` is `{ depth, tail, burstOpen }`, `tail` the
+  // stack's redo branch (redoTail(), top last). It holds while the stack is at
+  // the session's opening depth with exactly those op OBJECTS on top of the
+  // redo branch — what an ordinary undo and redo of something else leaves
+  // standing, and what any new edit (which clears the branch) does not.
+  function waveRedoHolds(ro, now) {
+    if (ro === null || ro === undefined || now.burstOpen === true || now.depth !== ro.baseDepth) return false;
+    const n = ro.ops.length;
+    if (n === 0 || now.tail.length < n) return false;
+    const top = now.tail.slice(now.tail.length - n);
+    return top.every((op, i) => op === ro.ops[i]);
+  }
+
   if (typeof module === 'object' && module.exports) {
-    module.exports = { pasteIsAllListLines, LIST_LINE_RE, extractBlockSource, commitEdit, commitRangeEdit, commitRangeRemoval, commitListBlockRemoval, commitBlockInsertion, planBlockMove, commitBlockMove, reorderSpanRange, spanMoveRange, spanIndentsAreAnchored, blockMoveSeamRefusal, rollbackFailedRender, headingDepthOf, withHeadingDepth, resolveDrawioLanding, shiftBlocksAfterBodyEdit, waveDiscardIsSafe };
+    module.exports = { pasteIsAllListLines, LIST_LINE_RE, extractBlockSource, commitEdit, commitRangeEdit, commitRangeRemoval, commitListBlockRemoval, commitBlockInsertion, planBlockMove, commitBlockMove, reorderSpanRange, spanMoveRange, spanIndentsAreAnchored, blockMoveSeamRefusal, rollbackFailedRender, headingDepthOf, withHeadingDepth, resolveDrawioLanding, shiftBlocksAfterBodyEdit, waveDiscardIsSafe, waveOfferHolds, waveRedoHolds };
     return; // node: pure core only
   }
 
@@ -888,44 +922,51 @@
     discardedRawEdit = null;
   }
 
-  // v3.4.0 batch3 Task 7 — the wave-editor member of the same family as the
-  // two stashes above. Escape out of the wave overlay still DISCARDS, and this
-  // is what makes the discard recoverable by exactly one document-level
-  // Ctrl+Z, the same one-shot contract `discardedBurst` spells out.
-  //
-  // Which of discardedBurst's rules are reused here, and which cannot be:
-  //
-  //   REUSED — the one-shot window (the only Ctrl+Z it answers is the one
-  //   right after the Escape that created it), the drop-on-any-render rule
-  //   (rerenderAll() clears all three at its top), mutual exclusivity with the
-  //   other two, and a staleness guard that refuses rather than applying a
-  //   restore over a document that moved underneath it.
-  //
-  //   NOT APPLICABLE — parking a live `history` object keyed on the burst's
-  //   own DOM node. discardedBurst can do that because the burst's
-  //   contenteditable survives its own Escape; the wave overlay is mounted on
-  //   `document.body` and `close()` REMOVES it (and every document listener it
-  //   installed) before onClose ever runs, so there is no node and no live
-  //   store left to park. Nor is `editEl`/`burstBaselineHtml()` meaningful:
-  //   nothing the wave editor produces was ever HTML in `.content`.
-  //
-  //   NOT APPLICABLE — "the burst never committed, so `lines` never saw it".
-  //   The wave editor writes back PER GESTURE, so by the time Escape is
-  //   pressed `lines` has seen every one of them and the document stack is
-  //   carrying them. That inverts what Escape has to do: it is the one stash
-  //   in this file whose creation REMOVES ops from the stack (see
-  //   finishWaveSession()) rather than never having put any there.
-  //
-  // So this parks a plain VALUE pair — the block body as it stood before the
-  // session (`source`, which is what `lines` holds again once the Escape has
-  // run) and as it stood at the moment of the Escape (`painted`) — plus enough
-  // addressing to prove nothing else moved. Ctrl+Z's job is to put `painted`
-  // back through an ordinary commit and RE-OPEN the editor over it.
-  let discardedWaveEdit = null; // { blockId, blockStartLine, blockEndLine, startLine, endLine, source, painted } | null
-
-  function dropDiscardedWaveEdit() {
-    discardedWaveEdit = null;
-  }
+  // Wave redesign Task 11 (spec section 4.8) — the first Ctrl+Z after the
+  // wave editor closes takes that whole session back as ONE user step.
+  //
+  // Closing always keeps (✕, 完成 and Esc are all only "close"): every gesture
+  // was written into `lines` as it was drawn, so there is nothing to throw
+  // away. What the user may want instead is to take the whole drawing back,
+  // and one Ctrl+Z per gesture is the wrong size for that. So the close leaves
+  // an offer, made by finishWaveSession() once its render is done:
+  //
+  //   { blockId, startLine, endLine, baseSource, baseDepth, lines, depth, count }
+  //
+  //   blockId    the block, found again by id in the CURRENT `blocks` when the
+  //              offer is used — never by the line numbers it had at the close
+  //   startLine, endLine  the body range at the close (a record, not used to
+  //              address anything)
+  //   baseSource the block body when the editor OPENED: the seam's own copy,
+  //              never the store's source, which rebases on every write-back
+  //              (Rulings R16/R17)
+  //   lines      the `lines` ARRAY at the close, by reference, and
+  //   depth      `stack.depth` at the close. Together they are the whole
+  //              validity contract (waveUndoOfferValid()): every edit, undo,
+  //              redo and reload replaces `lines`, so an offer whose array is
+  //              no longer the live one belongs to a document that has moved
+  //              on, even when the bytes happen to be equal again
+  //   baseDepth  the stack depth when the editor opened (seam.baseDepth); the
+  //              offer is only made when the close finds the stack exactly
+  //              `baseDepth + count` deep, i.e. the session's own entries on top
+  //   count      how many gestures the session wrote (seam.ops): the toast's N,
+  //              and how many entries the revert pops (Ruling R24)
+  //
+  // It is spent by the Ctrl+Z that asks it, whether or not it still held. The
+  // step itself (undoWaveSession(), Ruling R24) pops the session's `count`
+  // entries off the stack and renders once. It is not the old Escape discard's
+  // unwind: that one ran before any render, never rendered, and threw the
+  // entries away (discardTop); this keeps them on the redo branch.
+  //
+  // `waveRedoOffer` is the other half (spec: 可再被 Ctrl+Y 取消): made when
+  // the revert lands, `{ baseDepth, ops, offer }` (`ops` the popped entries),
+  // and Ctrl+Y while the stack still stands there (waveRedoOfferValid())
+  // re-applies them as one step and re-makes the undo offer.
+  //
+  // Declared up here, beside the stashes, for the same temporal-dead-zone
+  // reason as `waveUnwrittenEdit` below.
+  let waveUndoOffer = null;
+  let waveRedoOffer = null;
 
   // v3.4.0 batch3 Task 7 — a wave gesture whose patch was REFUSED, i.e. work
   // the user can see in the overlay that `lines` does not hold and cannot be
@@ -942,6 +983,14 @@
   // definition nothing reached `lines`.
   let waveUnwrittenEdit = false;
 
+  // wave redesign Task 6b: the open wave editor's `setSaveStatus`, or null.
+  // The editor's title bar shows the FILE's save state (spec section 4.8),
+  // so setDirty() pushes every change to it. Kept up here rather than read
+  // off `waveEditor` for the same reason as `waveUnwrittenEdit` above:
+  // setDirty() is reachable before the wave wiring's own `let`s far below
+  // have left their temporal dead zone.
+  let waveSaveStatusSink = null;
+
   // §10-gap fix (review): the block insertBlockBelow() most recently
   // inserted, tracked from the moment its edit surface is first focused
   // until its FIRST resolution (blur, Escape, explicit commit, or Ctrl+Z) —
@@ -1147,6 +1196,7 @@
   function setDirty() {
     document.title = (documentIsDirty() ? '● ' : '') + baseTitle;
     paintSaveStatus(documentIsDirty() ? 'dirty' : 'clean');
+    if (waveSaveStatusSink !== null) waveSaveStatusSink(documentIsDirty());
   }
 
   // setDirty() is push-driven: something has to call it. MEASURED by keeping
@@ -1323,6 +1373,33 @@
   }
   function showError(message, actionLabel, onAction) { return showBanner(message, actionLabel, onAction, 'error'); }
   function showNotice(message) { return showBanner(message, null, null, 'notice'); }
+  // Wave redesign Task 6b fix round 1 (spec E2): the wave editor's notices
+  // must never take the place of a red card that is still up — a write-back
+  // refusal, a failed save, the disk-conflict card with 重新載入. With one
+  // banner on the page, showBanner() would replace it, and that card is the
+  // only record of the problem. The notice is dropped instead (the editor
+  // still keeps it in its own data-wave-status). Scoped to the wave editor's
+  // messages rather than changed inside showNotice() for every caller: the
+  // global change could only be verified by the long editor-journey suite,
+  // which this phase of the redesign does not run.
+  //
+  // Task 11: while the editor is open the toast sits just above its hint bar
+  // (spec section 4.8: 編輯器內底部置中) rather than at the viewport's
+  // `bottom: 28px`. MEASURED at 1366x768 before this: the toast spanned
+  // y 696-740 and the hint bar 697-729, so the toast covered the middle of
+  // the bar the user reads for the next step. Measured off the bar itself, so
+  // any panel size or bar height lands it right.
+  function showWaveNotice(message, actionLabel, onAction) {
+    if (activeBanner !== null && document.contains(activeBanner) &&
+        activeBanner.getAttribute('data-level') === 'error') return null;
+    const el = showBanner(message, actionLabel, onAction, 'notice');
+    const hintBar = waveEditorIsModal() ? document.querySelector('.ed-wave-overlay .ed-wave-hint') : null;
+    if (el !== null && hintBar !== null) {
+      const top = hintBar.getBoundingClientRect().top;
+      el.style.bottom = Math.max(8, Math.round(window.innerHeight - top + 8)) + 'px';
+    }
+    return el;
+  }
 
   // Task 9 review I3: MEASURED AT THE TIME — `.ed-conflict` was
   // `position:fixed; top:0; z-index:999` against `.ed-toolbar`'s
@@ -1554,9 +1631,6 @@
     // twin — this render is about to replace `lines`' rendering of whatever
     // discardedRawEdit's stashed `source` names.
     dropDiscardedRawEdit();
-    // v3.4.0 batch3 Task 7: and the wave twin — its staleness guard compares
-    // `lines` at a span, which this render is about to repaint from.
-    dropDiscardedWaveEdit();
     const scrollY = window.scrollY;
     // S3 Task 5 (§4.4 step 2): the line range this render's operation declared
     // for the rebuilt selection. Consumed HERE, before the first failure exit,
@@ -3021,8 +3095,6 @@
         // own comment for why only the more recent of the two stashes may
         // ever answer the next Ctrl+Z.
         dropDiscardedBurst();
-        // …and with the wave twin, for the same reason.
-        dropDiscardedWaveEdit();
         discardedRawEdit = {
           blockId, range, startLine, endLine, source,
           value: ta.value, caret: ta.selectionStart,
@@ -7271,8 +7343,6 @@
     // discardedRawEdit's own comment for why the two stashes must stay
     // mutually exclusive.
     dropDiscardedRawEdit();
-    // v3.4.0 batch3 Task 7: …and the wave twin, same rule, three stashes.
-    dropDiscardedWaveEdit();
     const blockEl = editEl.closest('.ed-block');
     if (!blockEl) return;
     const blockId = Number(blockEl.getAttribute('data-block-id'));
@@ -8548,7 +8618,6 @@
     // v3.4.0 (Task 7 item 5): mutual exclusivity with the raw-editor twin —
     // see discardedRawEdit's own comment.
     dropDiscardedRawEdit();
-    dropDiscardedWaveEdit();
     discardedBurst = {
       history: burst.history, editEl, blockType: burst.blockType, cellIdx: -1,
       reverted: burstBaselineHtml(editEl),
@@ -8570,7 +8639,6 @@
     // v3.4.0 (Task 7 item 5): mutual exclusivity with the raw-editor twin —
     // see discardedRawEdit's own comment.
     dropDiscardedRawEdit();
-    dropDiscardedWaveEdit();
     discardedBurst = {
       history: burst.history, editEl: tableEl, blockType: 'table', cellIdx,
       reverted: burstBaselineHtml(tableEl),
@@ -10002,7 +10070,6 @@
     dropDiscardedBurst();
     // v3.4.0 (Task 7 item 5): see startBurst()'s own comment just above.
     dropDiscardedRawEdit();
-    dropDiscardedWaveEdit();
     const tableEl = cellEl.closest('table');
     const blockEl = tableEl && tableEl.closest('.ed-block');
     if (!blockEl) return;
@@ -15451,6 +15518,10 @@
       mtimeMs = j.mtimeMs;
       stack.markSaved(token);
       setDirty();
+      // Spec section 4.8: Ctrl+S inside the wave editor saves the whole file
+      // and leaves the editor open; the toolbar's status slot is behind the
+      // modal, so the result is said at the bottom as well.
+      if (waveSaveStatusSink !== null) showWaveNotice('已儲存', null, null);
       // v3.4.0 §3: markSaved() just moved documentIsDirty() from true to
       // false, and the `save` button's own lit/grey state is read off
       // exactly that value (toolbarContext()'s `dirty` field) — without this
@@ -15622,11 +15693,6 @@
     // discardedRawEdit's own comment), so checking both in sequence never
     // answers a stale one while the other substrate holds the fresher discard.
     if (await restoreDiscardedRawEdit()) return;
-    // v3.4.0 batch3 Task 7: the wave twin. Third in the sequence for no reason
-    // other than that it is the newest; all three are mutually exclusive by
-    // construction (one editing session at a time) and each nulls its own slot
-    // before deciding, so order cannot make a stale one answer.
-    if (await restoreDiscardedWaveEdit()) return;
     // Resolve any open editor BEFORE the .content-replacing swap below —
     // see the `activeEditor` / switchAwayFrom() comments near its
     // declaration for why this is required (undo/redo silently detaching an
@@ -15635,6 +15701,24 @@
     // first), so the undo that follows targets whatever is now the newest
     // op — which, if an auto-commit just happened, IS that commit.
     if (!(await switchAwayFrom())) return;
+    // Wave redesign Task 11 (spec section 4.8): the first Ctrl+Z after the wave
+    // editor closed takes that whole session back as one step, while nothing
+    // else has changed the document since. After the two stashes above on
+    // purpose: either of them can only exist because something was opened and
+    // discarded AFTER the close, so it is the newer thing to undo. And after
+    // switchAwayFrom() (Ruling R25): typing still sitting in an open editor is
+    // newer than the close too, and its commit replaces `lines`, which expires
+    // the offer. Spent here whether or not it held — an offer that did not
+    // hold now never will.
+    if (waveUndoOffer !== null) {
+      const held = waveUndoOfferValid();
+      const offer = waveUndoOffer;
+      waveUndoOffer = null;
+      if (held) {
+        const done = await undoWaveSession(offer);
+        if (done !== 'missing') return;
+      }
+    }
     const prevLines = lines;
     const r = stack.undo(lines);
     if (!r) return;
@@ -15679,6 +15763,19 @@
 
   async function redo() {
     if (!(await switchAwayFrom())) return;
+    // Wave redesign Task 11 (spec section 4.8: 可再被 Ctrl+Y 取消): while the
+    // stack stands where the whole-session undo left it, Ctrl+Y re-applies the
+    // session as one step (Ruling R24). A stack question, not an identity of
+    // `lines`: an ordinary Ctrl+Z / Ctrl+Y over an earlier edit comes back to
+    // the same stack, and the drawing still comes back whole after it. So the
+    // offer is NOT spent when it does not hold; it simply stops holding for
+    // good once a new edit clears the redo branch.
+    if (waveRedoOffer !== null && waveRedoOfferValid()) {
+      const ro = waveRedoOffer;
+      waveRedoOffer = null;
+      await redoWaveSession(ro);
+      return;
+    }
     const prevLines = lines;
     const r = stack.redo(lines);
     if (!r) return;
@@ -18760,16 +18857,18 @@
   //
   // Task 7's own fields, and why each is here rather than derived:
   //   ops        how many commits this session has pushed onto the document
-  //              stack. Escape reverses exactly this many — see
-  //              finishWaveSession().
+  //              stack since it last stood at its opening bytes. The net-zero
+  //              unwind (unwindWaveOps()) reverses exactly this many, and the
+  //              close's toast counts them (spec 4.8: N 處修改).
   //   baseLines  `lines` as it stood when the editor opened, and
-  //   baseBlocks `blocks` likewise. Escape restores both BY VALUE instead of
-  //              trusting the reversal's arithmetic to land back where it
-  //              started; the two are the same answer, and one of them cannot
-  //              be off by a line.
-  //   baseSource the block body the store was opened over, i.e. what `lines`
-  //              holds again once an Escape has run. The stash's staleness
-  //              guard compares against it.
+  //   baseBlocks `blocks` likewise. The net-zero unwind restores both BY
+  //              VALUE instead of trusting the reversal's arithmetic to land
+  //              back where it started; the two are the same answer, and one
+  //              of them cannot be off by a line.
+  //   baseSource the block body the store was opened over: what the net-zero
+  //              unwind compares against, and what the whole-session undo
+  //              after closing writes back (waveUndoOffer). The seam's own
+  //              copy, never the store's rebased source (Rulings R16/R17).
   //   unwritten  this session has a gesture the file could not express (the
   //              document-level flag `waveUnwrittenEdit` is the same fact; the
   //              flag is what documentIsDirty() reads, this is what the
@@ -18780,8 +18879,8 @@
   //              killed the arithmetic it replaces (fix 2 / MUST-FIX 1).
   //   baseRedoTail  the redo branch that existed before the session (fix 1 /
   //              F3). The session's first commit clears it like any other edit;
-  //              a session that is DISCARDED has to hand it back, or the user
-  //              silently loses a redo to a document that ends up
+  //              a session that is unwound to nothing has to hand it back, or
+  //              the user silently loses a redo to a document that ends up
   //              byte-identical.
   let waveSeam = null;
   // Gestures that arrived with no editor left to own them. Zero is the
@@ -18966,9 +19065,16 @@
     // 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'] || !mods['wave-draw.js'] ||
-        !mods['wave-panels.js']) return;
+        !mods['wave-panels.js'] || !mods['wave-canvas.js']) return;
     if (waveEditor !== null) return;
     hideWaveEditBtn();
+    // Spec section 6: no engine, no editor — a red card, never a blank canvas
+    // and never a fallback drawing of our own (the engine IS the canvas).
+    if (typeof WaveDrom === 'undefined' || WaveDrom === null ||
+        typeof WaveDrom.RenderWaveForm !== 'function') {
+      showError('波形引擎沒有載入，無法編輯', null, null);
+      return;
+    }
 
     // Settle the document BEFORE reading a single line out of it. An open
     // burst or block editor is committed here, deliberately in front of the
@@ -19048,6 +19154,13 @@
         geometry: mods['wave-geometry.js'],
         draw: mods['wave-draw.js'],
         panels: mods['wave-panels.js'],
+        // The engine canvas (wave redesign Task 6a) and the theme API it
+        // recolours with in dark (lib/theme/runtime.js).
+        canvas: mods['wave-canvas.js'],
+        theme: window.md2docTheme || null,
+        // Task 10: the overflow rule's `suggestScale` (lib/wave-overflow.js),
+        // for ⚙'s and the canvas chip's 「改每拍 K×」.
+        waveOverflow: mods['wave-overflow.js'] || null,
         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
@@ -19057,12 +19170,24 @@
         // another.
         laneTrace: mods['wave-store.js'].laneTrace,
         wavedrom: (typeof WaveDrom !== 'undefined') ? WaveDrom : null,
+        // Spec section 4.8's two message levels, on this page's own banner:
+        // 'error' is the red card that stays, 'notice' the 4-second toast.
+        notify: (level, text, action) => {
+          const label = action && action.label ? action.label : null;
+          const run = action && typeof action.run === 'function' ? action.run : null;
+          if (level === 'error') showError(text, label, run);
+          else showWaveNotice(text, label !== null && run !== null ? label : null, run);
+        },
+        // The file's save state for the editor's title bar; later changes
+        // arrive through `waveSaveStatusSink` (setDirty()).
+        saveStatus: () => ({ dirty: documentIsDirty() }),
+        saveKeyHint: SAVE_KEY_HINT,
         onGesture: (info) => {
           if (waveSeam === null) { waveStrayGestures++; return; }
           waveSeam.lastGesture = info;
           writeWaveGestureBack(info);
         },
-        onClose: (reason) => {
+        onClose: () => {
           // Read the seam out and null BOTH before doing anything slow: the
           // predicate every global listener asks (`waveEditorIsModal()`) has to
           // answer "no" from this instant, and finishWaveSession() below awaits
@@ -19071,7 +19196,8 @@
           const seam = waveSeam;
           waveEditor = null;
           waveSeam = null;
-          finishWaveSession(seam, reason)
+          waveSaveStatusSink = null;
+          finishWaveSession(seam)
             // …and only then the keyboard, because the commit path RE-RENDERS
             // `.content` and every block element that existed when the overlay
             // was up is gone by the time that resolves. Focusing before the
@@ -19087,9 +19213,11 @@
     } catch (err) {
       waveEditor = null;
       waveSeam = null;
+      waveSaveStatusSink = null;
       throw err;
     }
     waveEditor = editor;
+    waveSaveStatusSink = typeof editor.setSaveStatus === 'function' ? editor.setSaveStatus : null;
     waveSeam = { blockId: id, startLine: body.startLine, endLine: body.endLine,
                  lastGesture: null, ops: 0, unwritten: false,
                  blockStartLine: block.startLine, blockEndLine: block.endLine,
@@ -19099,6 +19227,10 @@
     // A fresh session cannot inherit the previous one's unwritten work: that
     // session is over, and whatever it could not express went with it.
     waveUnwrittenEdit = false;
+    // Nor the previous session's whole-session undo: a new session takes over
+    // the block, and a Ctrl+Z after IT closes is about it alone.
+    waveUndoOffer = null;
+    waveRedoOffer = null;
   }
 
   // ── Task 7: one gesture, one write-back ────────────────────────────────
@@ -19119,16 +19251,15 @@
   // written directly. Two things fall out of that for free and are load-
   // bearing, not incidental: `stack.dirtyDepth` counts the waveform (so the
   // title dot, the save button and the beforeunload guard all see it without
-  // knowing what a waveform is), and Escape can take the session back off the
-  // stack rather than needing a stash of its own for the part that committed.
+  // knowing what a waveform is), and a session that comes back to its opening
+  // bytes can take its own ops back off the stack (unwindWaveOps()).
   //
   // What is deliberately NOT done here: re-rendering `.content`. The overlay
   // covers the document, a render replaces `.content` wholesale, and doing it
   // per paint would tear down and re-run WaveDrom on every gesture for a
   // picture nobody can see. `.content` therefore lags `lines` for exactly as
-  // long as the modal is up, and the session's close settles it — a commit by
-  // rendering, an Escape by putting `lines` back to what `.content` is still
-  // showing.
+  // long as the modal is up, and the session's close settles it by rendering
+  // (every route out of the editor keeps the drawing — spec section 4.8).
   function writeWaveGestureBack(info) {
     const seam = waveSeam;
     if (seam === null || !info || !info.patch) return;
@@ -19222,7 +19353,8 @@
     //
     // 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
+    // drop announced nothing at all (since v3.13 the ⠿ grip's drop goes
+    // through `moveLaneTo`, which says where the lane landed). 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.
@@ -19357,12 +19489,6 @@
       });
   }
 
-  /**
-   * Settle a wave session that has just gone off screen.
-   *
-   * `reason` is wave-ui's, not inferred here: 'escape' means the user asked for
-   * the session to be thrown away, anything else means they kept it.
-   */
   /**
    * Give the keyboard back to the block the editor was opened over.
    *
@@ -19397,60 +19523,16 @@
     setBlockSelection({ anchorLine: b.startLine, focusLine: b.startLine });
   }
 
-  async function finishWaveSession(seam, reason) {
+  /**
+   * Settle a wave session that has just gone off screen.
+   *
+   * Every route out of the editor — ✕, 完成, Esc — keeps the session (spec
+   * section 4.8): each gesture was committed as it was drawn, so all that is
+   * left is the one render `.content` has been waiting for, and the offer
+   * that lets the next Ctrl+Z take the whole session back at once.
+   */
+  async function finishWaveSession(seam) {
     if (seam === null) return;
-    if (reason === 'escape') {
-      // Escape DISCARDS — the same word it means everywhere else in v3.3.0 —
-      // and here that has to reach the document stack, because the session has
-      // been committing all along.
-      const painted = bodyNow(seam);
-      const hadOps = seam.ops > 0;
-      if (!unwindWaveOps(seam)) {
-        // A Ctrl+S landed inside this session, so its commits cannot simply be
-        // popped — see unwindWaveOps() for the measured failure that produces.
-        // A revert COMMIT is the honest answer instead: the document goes back
-        // to where the session found it, and the stack only ever grows, so
-        // `dirtyDepth` stays strictly positive and can never walk back through
-        // zero over a document that differs from disk. The cost is a `●` the
-        // user clears with one Ctrl+S — which is TRUE, because disk is still
-        // holding the drawing they just discarded.
-        const result = commitRangeEdit({ lines, blocks, stack },
-          seam.startLine, seam.endLine, seam.baseSource);
-        if (result.op !== null) lines = result.lines;
-        blocks = seam.baseBlocks;
-        seam.endLine = seam.startLine + seam.baseSource.split('\n').length - 1;
-        // fix 2 (R1): the redo branch, on THIS path too. Both Escape branches
-        // end with `lines` byte-identical to `seam.baseLines` — only the seam
-        // range is ever written during a session — so the pre-session redo ops
-        // still address the document they were recorded against, and a user who
-        // lands here is otherwise in exactly F3's position: a byte-identical
-        // document with their redo silently eaten. AFTER the commit, because
-        // `push()` is what cleared it.
-        stack.setRedoTail(seam.baseRedoTail);
-      }
-      if (hadOps && painted !== seam.baseSource) {
-        // …and the discard is recoverable by exactly one Ctrl+Z. See
-        // discardedWaveEdit's own comment for which of discardedBurst's rules
-        // this reuses and which of them cannot apply here.
-        dropDiscardedBurst();
-        dropDiscardedRawEdit();
-        discardedWaveEdit = {
-          blockId: seam.blockId,
-          blockStartLine: seam.blockStartLine, blockEndLine: seam.blockEndLine,
-          startLine: seam.startLine, endLine: seam.endLine,
-          source: seam.baseSource, painted: painted,
-        };
-      }
-      // Work the file could not hold goes with the session it belonged to.
-      // The banner that said so is deliberately NOT dismissed here: it is the
-      // only record the user has that something did not survive.
-      waveUnwrittenEdit = false;
-      setDirty();
-      // No render. `.content` was never repainted while the overlay was up, so
-      // it is still showing exactly the base document just restored — rendering
-      // would be a round trip to say nothing.
-      return;
-    }
     if (seam.unwritten) {
       // Kept, with a hole in it. The user is told once more on the way out,
       // because the status line they were reading has just been removed from
@@ -19463,6 +19545,8 @@
       waveUnwrittenEdit = false;
       setDirty();
     }
+    // Nothing written (or the drawing came back to its opening bytes, which
+    // unwound the ops): no render, no toast, no offer.
     if (seam.ops === 0) return;
     // fix 1 (F2): `blocks` is settled from the session's own arithmetic BEFORE
     // the render, not instead of it. A successful render overwrites it with the
@@ -19497,61 +19581,150 @@
         '畫面沒有重畫成功，但你畫的波形還在文件裡（按 Ctrl+S 可以存檔，' +
         'Ctrl+Z 可以撤銷）。', null, null);
     }
+    // Wave redesign Task 11: the whole-session undo offer (see waveUndoOffer's
+    // own comment). Made AFTER the render rather than before it: an offer used
+    // while the close render is still in flight would start a second render
+    // racing this one. `lines` does not move across a render, so this is the
+    // array the close left either way. The keyboard's way in is Ctrl+Z (spec
+    // section 7.3: the keyboard goes back to the block, not to the toast); the
+    // toast's 整段復原 is the pointer's.
+    //
+    // Ruling R24: the offer pops the session's own entries, so it is made only
+    // when they are exactly the top `ops` of the stack. When they are not
+    // (nothing known reaches that today), the close still says what changed,
+    // without promising a one-step undo it could not keep.
+    waveRedoOffer = null;
+    if (stack.depth === seam.baseDepth + seam.ops) {
+      waveUndoOffer = { blockId: seam.blockId, startLine: seam.startLine, endLine: seam.endLine,
+                        baseSource: seam.baseSource, baseDepth: seam.baseDepth,
+                        lines: lines, depth: stack.depth, count: seam.ops };
+      showWaveNotice('波形已更新（' + seam.ops + ' 處修改）· Ctrl+Z 整段復原', '整段復原',
+        () => { revertWaveSessionFromToast(); });
+    } else {
+      showWaveNotice('波形已更新（' + seam.ops + ' 處修改）', null, null);
+    }
+  }
+
+  /** Whether the closed session's whole-session undo still describes the document. */
+  function waveUndoOfferValid() {
+    return waveOfferHolds(waveUndoOffer, { lines: lines, depth: stack.depth, burstOpen: burstHasUncommittedEdit() });
+  }
+  /** Whether the stack still stands where the whole-session undo left it, so
+   *  Ctrl+Y can re-apply the session as one step. */
+  function waveRedoOfferValid() {
+    return waveRedoHolds(waveRedoOffer, { depth: stack.depth, tail: stack.redoTail(), burstOpen: burstHasUncommittedEdit() });
+  }
+
+  /**
+   * The toast's 整段復原: the same step as Ctrl+Z, but only while the offer
+   * still holds. A press on a toast that outlived its offer must not fall
+   * through to an ordinary undo of somebody else's edit. An open editor is
+   * committed first, exactly as undo() does (Ruling R25).
+   */
+  async function revertWaveSessionFromToast() {
+    if (!(await switchAwayFrom())) return;
+    if (!waveUndoOfferValid()) {
+      waveUndoOffer = null;
+      showNotice('文件在關閉後又改過了，整段復原已經失效；請用 Ctrl+Z 一步一步退');
+      return;
+    }
+    const offer = waveUndoOffer;
+    waveUndoOffer = null;
+    await undoWaveSession(offer);
   }
 
   /**
-   * Ctrl+Z straight after an Escape out of the wave editor: put the discarded
-   * drawing back and re-open the editor over it.
+   * Spec section 4.8 / Ruling R24: take the closed session back as ONE user
+   * step by popping its own `count` entries off the document stack, then
+   * render once.
    *
-   * The restore is an ordinary commit, not a special case — so the reopened
-   * session opens over a document that already holds the drawing, one more
-   * Ctrl+Z steps back over the restore itself, and Ctrl+S saves it. That is
-   * the difference from restoreDiscardedRawEdit(), whose stashed value lives
-   * in a textarea until a later blur commits it: there is no "uncommitted
-   * surface" shape available here, because the wave editor's surface IS the
-   * document.
+   * A pop, not a commit. The first cut wrote the opening body back as an
+   * ordinary commit, and the stack then ping-ponged: the next Ctrl+Z popped
+   * that commit and the whole drawing came back, so an edit made before the
+   * session was count + 3 presses away. Popping keeps the stack linear (the
+   * next Ctrl+Z is whatever came before the session), the save marker honest,
+   * and Ctrl+Y re-applies the same entries (redoWaveSession()).
    *
-   * Staleness is asked at the `lines`/`blocks` level, the same level
-   * restoreDiscardedRawEdit() asks at and for the same reason — the overlay
-   * was removed from the DOM by `close()`, so there is no node whose presence
-   * could answer it.
+   * Why popping exactly `count` entries is the session: the caller has checked
+   * the offer holds (`lines` is still the array the close left and the stack
+   * the depth it left), and the offer was only made when that depth was
+   * `baseDepth + ops`. The opening body is still checked after the pops — a
+   * gesture that ever wrote other than one entry would show up there — and a
+   * mismatch puts the entries back and says so instead of writing anything.
+   *
+   * Returns 'done', 'refused' (nothing changed; already said) or 'missing'
+   * (the block is not in the map; said, and the caller undoes one step as
+   * usual).
    */
-  async function restoreDiscardedWaveEdit() {
-    const d = discardedWaveEdit;
-    discardedWaveEdit = null;
-    if (!d) return false;
-    const b = blocks.find((x) => x.id === d.blockId);
-    if (!b || b.startLine !== d.blockStartLine || b.endLine !== d.blockEndLine) return false;
-    if (lines.slice(d.startLine - 1, d.endLine).join('\n') !== d.source) return false;
+  async function undoWaveSession(offer) {
+    const b = blocks.find((x) => x.id === offer.blockId);
+    if (!b) {
+      showNotice('找不到剛才編輯的那張波形，沒辦法整段退回；這一下 Ctrl+Z 照常退一步');
+      return 'missing';
+    }
     const prevLines = lines;
-    const result = commitRangeEdit({ lines, blocks, stack },
-      d.startLine, d.endLine, d.painted);
-    if (result.op === null) return false;
-    lines = result.lines;
-    // `blocks` deliberately not reassigned — the same shape every other
-    // commit-then-render site in this file has: the render that follows is what
-    // replaces it, and rollbackFailedRender() below restores `lines` only, so
-    // an assignment here would survive a failed render as the one value nothing
-    // puts back.
-    setDirty();
-    const ok = await safeRerenderAll({
-      startLine: d.startLine,
-      endLine: d.startLine + d.painted.split('\n').length - 1,
-      delta: result.op.after.length - result.op.before.length,
+    const popped = [];
+    while (popped.length < offer.count) {
+      const r = stack.undo(lines);
+      if (!r) break;
+      lines = r.lines;
+      popped.push(r.op);
+    }
+    // `b` is from the map the close render made: the fence line has not moved
+    // (every gesture rewrote the body only), so the body starts right after it.
+    const n = offer.baseSource.split('\n').length;
+    const back = popped.length === offer.count &&
+      lines.slice(b.startLine, b.startLine + n).join('\n') === offer.baseSource;
+    if (back) setDirty();
+    const ok = back && await safeRerenderAll({
+      startLine: b.startLine + 1, endLine: b.startLine + n, delta: lines.length - prevLines.length,
     });
     if (!ok) {
-      lines = rollbackFailedRender({ lines, stack }, result, prevLines);
+      for (let i = 0; i < popped.length; i++) lines = stack.redo(lines).lines;
+      setDirty();
+      if (!back) {
+        showNotice('這次的波形修改沒辦法整段退回（文件的復原紀錄跟關閉時對不上），所以沒有動；' +
+          '請用 Ctrl+Z 一步一步退');
+      }
+      return 'refused';
+    }
+    waveRedoOffer = { baseDepth: offer.baseDepth, ops: popped, offer: offer };
+    showWaveNotice('已退回這次的波形修改', null, null);
+    return 'done';
+  }
+
+  /**
+   * Ctrl+Y while the stack stands where undoWaveSession() left it: re-apply
+   * the session's entries with stack.redo(), as one step, and render once. The
+   * document is then exactly where the close left it, so the whole-session
+   * undo is on offer again. waveRedoHolds() has checked that the top of the
+   * redo branch is those very entries, so the redos cannot come up short; if
+   * the render fails they are undone again.
+   */
+  async function redoWaveSession(ro) {
+    const prevLines = lines;
+    let done = 0;
+    while (done < ro.ops.length) {
+      const r = stack.redo(lines);
+      if (!r) break;
+      lines = r.lines;
+      done++;
+    }
+    let ok = done === ro.ops.length;
+    if (ok) {
+      setDirty();
+      const b = blocks.find((x) => x.id === ro.offer.blockId);
+      ok = await safeRerenderAll(b ? { startLine: b.startLine + 1, endLine: b.startLine + 1,
+        delta: lines.length - prevLines.length } : undefined);
+    }
+    if (!ok) {
+      for (let i = 0; i < done; i++) lines = stack.undo(lines).lines;
       setDirty();
       return false;
     }
-    // Re-open over the block the render just rebuilt. `openWaveEditor()` wants
-    // something INSIDE the block and resolves the block with `closest()`, and
-    // `closest()` matches the element itself — so the block element is a valid
-    // argument and does not depend on WaveDrom having finished painting a
-    // `.wavedrom-diagram` into it yet.
-    const blockEl = blockElById(d.blockId);
-    if (!blockEl) return true; // the drawing is back in the document either way
-    await openWaveEditor(blockEl);
+    waveUndoOffer = Object.assign({}, ro.offer, { lines: lines, depth: stack.depth });
+    showWaveNotice('波形修改已恢復 · Ctrl+Z 整段復原', '整段復原',
+      () => { revertWaveSessionFromToast(); });
     return true;
   }
 
@@ -19564,13 +19737,16 @@
     return {
       open: waveEditor !== null,
       stray: waveStrayGestures,
-      // Task 7's three: whether the document currently believes it has
+      // Task 7's two: whether the document currently believes it has
       // anything unsaved (the thing the Reload button's beforeunload guard
-      // asks), whether this session has work the file could not hold, and
-      // whether a discarded session is sitting there waiting for a Ctrl+Z.
+      // asks) and whether this session has work the file could not hold.
+      // Task 11's two: whether a closed session's whole-session undo is on
+      // offer and would hold now, and the same for its Ctrl+Y.
       dirty: documentIsDirty(),
       unwritten: waveUnwrittenEdit,
-      stashed: discardedWaveEdit !== null,
+      undoOffer: waveUndoOffer === null ? null
+        : { count: waveUndoOffer.count, blockId: waveUndoOffer.blockId, holds: waveUndoOfferValid() },
+      redoOffer: waveRedoOffer === null ? null : { holds: waveRedoOfferValid() },
       seam: waveSeam === null ? null : {
         blockId: waveSeam.blockId,
         startLine: waveSeam.startLine,