@helping-ai-workflow/md2doc 3.12.0 → 3.13.0

package/lib/editor/wave-store.js

@@ -14,11 +14,14 @@
  * be derived wrongly.
  *
  * `toPatch` does NOT replay the stack. It compares the current entry against
- * the parse of the original text and writes the difference; nothing about how
- * the user got there reaches the file. That is what makes an edit and its
- * inverse cost zero bytes instead of two edits that cancel, and it is why
- * `isDirty` can be a question about the two documents rather than about the
- * stack — see the note on it below.
+ * the parse of the BASE text and writes the difference; nothing about how the
+ * user got there reaches the file. The base starts as the text the store was
+ * opened on, and the editor moves it with `rebase` after every write-back that
+ * landed (Ruling R16), so a patch is planned for one gesture rather than for a
+ * whole session of them. That is what makes an edit and its inverse cost zero
+ * bytes instead of two edits that cancel, and it is why `isDirty` — which keeps
+ * measuring against the OPENING text, never the base — can be a question about
+ * two documents rather than about the stack; see the note on it below.
  *
  * Four rules this file does not get to bend:
  *
@@ -80,44 +83,30 @@ const HISTORY_LIMIT = 200;
  * than as a throw or a null: the GUI layer above has a block on screen either
  * way, and `ok` plus a refusing `toPatch` is something it can show.
  */
-function createStore(sourceText) {
-  const parsed = C.parseSource(sourceText);
-  if (parsed.ok !== true) return refusingStore(sourceText, parsed);
+function createStore(openingText) {
+  const opening = C.parseSource(openingText);
+  if (opening.ok !== true) return refusingStore(openingText, opening);
 
-  const baseDoc = deepFreeze(parsed.doc, 0);
-  const basePaths = C.lanePaths(baseDoc);
-  const history = [{ opName: null, doc: baseDoc, origins: countUp(basePaths.length) }];
+  // The BASE is what the next patch is written against: the opening text until
+  // the first write-back, then whatever `rebase` was last handed. The OPENING
+  // text and its parse stay for `isDirty`, which asks about the whole session,
+  // and as the second reading `toPatch` falls back on (Ruling R17).
+  let sourceText = openingText;
+  let parsed = opening;
+  const openingDoc = deepFreeze(opening.doc, 0);
+  const openingCtx = contextFor(opening, openingDoc, C.lanePaths(openingDoc));
+  let ctx = openingCtx;
+  // Each entry carries two answers to "which lane is which": `origins`, against
+  // the current base (re-traced by every `rebase`), and `openOrigins`, against
+  // the opening text, which nothing but `apply` ever writes.
+  const history = [{
+    opName: null,
+    doc: openingDoc,
+    origins: countUp(openingCtx.basePaths.length),
+    openOrigins: countUp(openingCtx.basePaths.length),
+  }];
   let at = 0;
 
-  /** The span of one path as a range a caller can frame, or null. */
-  function range(path) {
-    const span = parsed.spans.get(JSON.stringify(path));
-    return span === undefined
-      ? null
-      : { path: path, spanPath: path, start: span[0], end: span[1] };
-  }
-
-  /** One range covering several paths — for a refusal about more than one lane. */
-  function spanning(paths) {
-    let out = null;
-    for (const path of paths) {
-      const one = range(path);
-      if (one === null) continue;
-      if (out === null) out = one;
-      else {
-        out = {
-          path: out.path,
-          spanPath: out.spanPath,
-          start: Math.min(out.start, one.start),
-          end: Math.max(out.end, one.end),
-        };
-      }
-    }
-    return out === null ? range([]) : out;
-  }
-
-  const ctx = { baseDoc: baseDoc, basePaths: basePaths, range: range, spanning: spanning };
-
   /**
    * Run one operation and, when it changed anything, push the result.
    *
@@ -144,11 +133,13 @@ function createStore(sourceText) {
     if (next === here.doc || !isDocShape(here.doc, next)) return false;
     const adopted = adoptDocument(next, 0, new Map());
     const origins = remapOrigins(here.doc, adopted, here.origins);
+    const openOrigins = remapOrigins(here.doc, adopted, here.openOrigins);
     history.length = at + 1;
     history.push({
       opName: opName === undefined ? null : opName,
       doc: adopted,
       origins: origins,
+      openOrigins: openOrigins,
     });
     at++;
     // Cap the stack, not just its growth: apply always leaves `at` on the
@@ -209,7 +200,48 @@ function createStore(sourceText) {
    * that the patch would not write.
    */
   function isDirty() {
-    return !sameValue(baseDoc, history[at].doc, 0);
+    return !sameValue(openingDoc, history[at].doc, 0);
+  }
+
+  /**
+   * Move the base to `text`, the bytes the caller has just written back for the
+   * CURRENT document, so the next `toPatch` is planned against them and sees
+   * one gesture rather than the whole session (Ruling R16).
+   *
+   * Planning stays a comparison of two documents — the current one against the
+   * parse of the base text — and nothing is replayed. What a rebase has to
+   * carry over is lane identity: every stack entry's `origins` named lanes of
+   * the OLD base, and is re-traced to the new one, outward from the current
+   * entry, one operation at a time with the same `remapOrigins` that `apply`
+   * runs. The current entry is the new base itself, so its origins count up;
+   * an undo entry then reads as the reverse of the gesture that left it, and a
+   * redo entry as that gesture again.
+   *
+   * Refused — answering false and changing nothing — for text that does not
+   * read back as the current document: a rebase onto bytes that say something
+   * else would plan the next patch against a file that is not there. `isDirty`
+   * does not move: it measures the session against the text the editor opened.
+   *
+   * The entry also remembers `text` as what the file held for it, so an undo or
+   * redo that lands on it again writes exactly those bytes (see `toPatch`).
+   * Its `openOrigins` are left alone: they are the second reading's (R17).
+   */
+  function rebase(text) {
+    const next = C.parseSource(text);
+    if (next.ok !== true || !sameValue(next.doc, history[at].doc, 0)) return false;
+    sourceText = text;
+    parsed = next;
+    const baseDoc = deepFreeze(next.doc, 0);
+    ctx = contextFor(next, baseDoc, C.lanePaths(baseDoc));
+    history[at].origins = countUp(ctx.basePaths.length);
+    history[at].written = text;
+    for (let k = at - 1; k >= 0; k--) {
+      history[k].origins = remapOrigins(history[k + 1].doc, history[k].doc, history[k + 1].origins);
+    }
+    for (let k = at + 1; k < history.length; k++) {
+      history[k].origins = remapOrigins(history[k - 1].doc, history[k].doc, history[k - 1].origins);
+    }
+    return true;
   }
 
   /**
@@ -228,47 +260,47 @@ function createStore(sourceText) {
    */
   function toPatch() {
     const here = history[at];
-    const plan = planEdits(ctx, here.doc, here.origins);
-    if (plan.ok !== true) return plan;
-    let refused = null;
-    let mismatched = null;
-    for (const edits of plan.alternatives) {
-      const written = C.patchSource(sourceText, parsed, edits);
-      if (written.ok !== true) {
-        if (refused === null) refused = written;
-        continue;
-      }
-      const back = C.parseSource(written.text);
-      if (back.ok === true && sameValue(back.doc, here.doc, 0)) return written;
-      if (mismatched === null) mismatched = refuse(NET_REASON, range([]));
-    }
-    // Nothing reproduced the document, so this is a refusal — and WHICH refusal
-    // matters, because the candidate that refused during planning is usually the
-    // reading that was actually right. A candidate whose plan named a real
-    // structural conflict says more than "the bytes did not come back the same",
-    // so it is preferred, then the codec's own words, and only then the net.
-    //
-    // When there was more than one reading, the one being described is the first
-    // by position and not necessarily the drag the user performed, so the message
-    // says that rather than asserting a gesture nobody made. Naming the "more
-    // plausible" reading instead would be a tie-break by argument, which is the
-    // thing that shipped the wrong patch in the first place.
-    if (plan.refusals.length > 0) {
-      const first = plan.refusals[0];
-      if (plan.readings < 2) return first;
-      return refuse('the lanes were reordered in a way that has more than one reading — ' +
-        'which lane was dragged cannot be told apart from the result — and none of them ' +
-        'could be written as a local patch. One reading was refused because: ' + first.reason,
-        first.rewroteRange);
+    // Back at the document the editor opened on: the opening bytes ARE its
+    // patch. Planned against a moved base, the reverse of the last gesture can
+    // read back right and still differ in bytes (a move leaves its trailing
+    // comma), and a session that has come back to where it started must hand
+    // back the author's own text — `client.js` takes the session's ops off the
+    // document stack only when the block is byte-identical to its opening.
+    if (sourceText !== openingText && !isDirty()) return { ok: true, text: openingText };
+    // An entry the file has already held — the one an undo or a redo lands on —
+    // is written back as exactly those bytes: a reverse gesture planned against
+    // the base would say the same thing with less of the author's text in it
+    // (an undone delete comes back as a fresh value, without the comment that
+    // sat beside it), or not at all. They go through the read-back check again
+    // first (Ruling R18): they read back as this document when they were
+    // written, but a value a caller froze only at its top keeps whatever is
+    // inside it mutable, so "this document" may have moved since. On a
+    // mismatch the two planners below decide, as for any other entry.
+    if (here.written !== undefined) {
+      const back = C.parseSource(here.written);
+      if (back.ok === true && sameValue(back.doc, here.doc, 0)) return { ok: true, text: here.written };
     }
-    if (refused !== null) return refused;
-    return mismatched === null ? refuse(NET_REASON, range([])) : mismatched;
+    const first = writeAgainst(ctx, sourceText, parsed, here.doc, here.origins);
+    if (first.ok === true || sourceText === openingText) return first;
+    // Ruling R17: the plan against the rebased base refused, so the same
+    // document is planned once more against the OPENING text with the
+    // opening-relative origins — the whole-session plan that preceded R16.
+    // Some changes only that reading can say: an undo that puts a deleted lane
+    // back in front of a group at the group's own level, or behind a group's
+    // last member, or brings back a group its deletions had emptied. It is
+    // still two documents and no replay, the read-back decides, and either
+    // way the patch is the whole block text. The base reading goes first, so
+    // whatever it could write is written exactly as before; when both refuse,
+    // the base reading's refusal is the one reported.
+    const second = writeAgainst(openingCtx, openingText, opening, here.doc, here.openOrigins);
+    return second.ok === true ? second : first;
   }
 
   const store = {
     ok: true,
     error: null,
-    source: sourceText,
+    // The text the editor OPENED with — not the moving base `rebase` keeps.
+    source: openingText,
     apply: apply,
     undo: undo,
     redo: redo,
@@ -278,6 +310,7 @@ function createStore(sourceText) {
     redoName: function () { return at < history.length - 1 ? history[at + 1].opName : null; },
     isDirty: isDirty,
     toPatch: toPatch,
+    rebase: rebase,
   };
   Object.defineProperty(store, 'doc', {
     enumerable: true,
@@ -286,6 +319,80 @@ function createStore(sourceText) {
   return store;
 }
 
+/**
+ * Everything the planner reads about the text a patch is written against: its
+ * document, its lane paths, and ranges into its spans for refusals to frame.
+ */
+function contextFor(parsed, baseDoc, basePaths) {
+  function range(path) {
+    const span = parsed.spans.get(JSON.stringify(path));
+    return span === undefined
+      ? null
+      : { path: path, spanPath: path, start: span[0], end: span[1] };
+  }
+  /** One range covering several paths — for a refusal about more than one lane. */
+  function spanning(paths) {
+    let out = null;
+    for (const path of paths) {
+      const one = range(path);
+      if (one === null) continue;
+      if (out === null) out = one;
+      else {
+        out = {
+          path: out.path,
+          spanPath: out.spanPath,
+          start: Math.min(out.start, one.start),
+          end: Math.max(out.end, one.end),
+        };
+      }
+    }
+    return out === null ? range([]) : out;
+  }
+  return { baseDoc: baseDoc, basePaths: basePaths, range: range, spanning: spanning };
+}
+
+/**
+ * Plan `doc` against one text, write every reading, and hand back the first
+ * that reads back as `doc` — or the refusal that best says why none did.
+ */
+function writeAgainst(ctx, text, parsed, doc, origins) {
+  const plan = planEdits(ctx, doc, origins);
+  if (plan.ok !== true) return plan;
+  let refused = null;
+  let mismatched = null;
+  for (const edits of plan.alternatives) {
+    const written = C.patchSource(text, parsed, edits);
+    if (written.ok !== true) {
+      if (refused === null) refused = written;
+      continue;
+    }
+    const back = C.parseSource(written.text);
+    if (back.ok === true && sameValue(back.doc, doc, 0)) return written;
+    if (mismatched === null) mismatched = refuse(NET_REASON, ctx.range([]));
+  }
+  // Nothing reproduced the document, so this is a refusal — and WHICH refusal
+  // matters, because the candidate that refused during planning is usually the
+  // reading that was actually right. A candidate whose plan named a real
+  // structural conflict says more than "the bytes did not come back the same",
+  // so it is preferred, then the codec's own words, and only then the net.
+  //
+  // When there was more than one reading, the one being described is the first
+  // by position and not necessarily the drag the user performed, so the message
+  // says that rather than asserting a gesture nobody made. Naming the "more
+  // plausible" reading instead would be a tie-break by argument, which is the
+  // thing that shipped the wrong patch in the first place.
+  if (plan.refusals.length > 0) {
+    const first = plan.refusals[0];
+    if (plan.readings < 2) return first;
+    return refuse('the lanes were reordered in a way that has more than one reading — ' +
+      'which lane was dragged cannot be told apart from the result — and none of them ' +
+      'could be written as a local patch. One reading was refused because: ' + first.reason,
+      first.rewroteRange);
+  }
+  if (refused !== null) return refused;
+  return mismatched === null ? refuse(NET_REASON, ctx.range([])) : mismatched;
+}
+
 /** A store over a source that could not be read back: it refuses, it never throws. */
 function refusingStore(sourceText, parsed) {
   const why = 'the source could not be read back as WaveJSON (' + parsed.message +
@@ -302,6 +409,7 @@ function refusingStore(sourceText, parsed) {
     undoName: function () { return null; },
     redoName: function () { return null; },
     isDirty: function () { return false; },
+    rebase: function () { return false; },
     // No span table and no edit, so there is no range to frame: `rewroteRange`
     // is null on purpose here, and `error.offset` is where the trouble is.
     toPatch: function () { return refuse(why, null); },
@@ -531,6 +639,11 @@ function countUp(n) {
  * address lanes through the bridge, never by a path built here — and the
  * content half is then done pairwise between lanes that survived. That half can
  * offer more than one candidate; `toPatch` decides between them by reproduction.
+ *
+ * A third route is for the changes to the GROUPS themselves, which neither of
+ * those can say: a run of lanes wrapped into a new group, a group dissolved, a
+ * whole group moved among its siblings. See `planTree`; its readings are added
+ * to whichever of the two routes above ran, after that route's own.
  */
 function planEdits(ctx, doc, origins) {
   const common = [];
@@ -539,18 +652,28 @@ function planEdits(ctx, doc, origins) {
   const top = diffMembers(ctx, [], ctx.baseDoc, doc, skip, common);
   if (top.ok !== true) return top;
   if (!laneAware) return { ok: true, alternatives: [common], refusals: [], readings: 1 };
+  // The group-level readings (a group wrapped, unwrapped or moved as a whole)
+  // come AFTER the lane-level ones in every list below: where a lane-level plan
+  // already reproduced the document before, it still wins and writes exactly
+  // the bytes it always wrote. They only ever turn a refusal into a write.
+  const tree = planTree(ctx, doc, origins, common);
   if (origins.length === ctx.basePaths.length && isCountUp(origins)) {
-    const lanes = diffValue(ctx, ['signal'], signalOf(ctx.baseDoc), signalOf(doc), common);
+    const same = common.slice();
+    const lanes = diffValue(ctx, ['signal'], signalOf(ctx.baseDoc), signalOf(doc), same);
     if (lanes.ok !== true) return lanes;
-    return { ok: true, alternatives: [common], refusals: [], readings: 1 };
+    return { ok: true, alternatives: [same].concat(tree), refusals: [], readings: 1 + tree.length };
   }
   const structural = planStructural(ctx, doc, origins);
-  if (structural.ok !== true) return structural;
+  if (structural.ok !== true) {
+    if (tree.length === 0) return structural;
+    return { ok: true, alternatives: tree, refusals: [structural], readings: 1 + tree.length };
+  }
   return {
     ok: true,
-    alternatives: structural.alternatives.map(function (extra) { return common.concat(extra); }),
+    alternatives: structural.alternatives.map(function (extra) { return common.concat(extra); })
+      .concat(tree),
     refusals: structural.refusals,
-    readings: structural.readings,
+    readings: structural.readings + tree.length,
   };
 }
 
@@ -579,20 +702,25 @@ function planStructural(ctx, doc, origins) {
   }
 
   // A group title is not a lane, so nothing above tracks one, and a structural
-  // walk would carry a renamed title silently past the patch. No codec
-  // operation renames one — only a hand-written operation reaches this — so
-  // rather than guess which title became which, anything the current doc says
-  // that the base doc did not is refused. A title that vanished is ordinary: it
-  // went with the group its last lane emptied. (A group DISSOLVED by hand, with
-  // its lanes kept, says nothing new here — that one is caught by the
-  // read-back check in `toPatch`, because the patch would still hold the group.)
+  // walk would carry a renamed or new title silently past the patch. Titles do
+  // change — `wave-panels`' commitGroupTitle renames one, `groupLanes` writes a
+  // new one — but each is its own gesture, and after the editor rebases on a
+  // write-back this lane-level route only ever sees a title change that rode in
+  // with a lane change since the last write-back that landed (or a hand-written
+  // operation). Rather than guess which title became which, anything the
+  // current doc says that the base doc did not is refused here; the group-level
+  // route (`planTree`) still gets its chance, and covers a new group's title.
+  // A title that vanished is ordinary: it went with the group its last lane
+  // emptied. (A group DISSOLVED with its lanes kept says nothing new here —
+  // `planTree` plans that one, and the read-back check catches any other.)
   const titles = titleCensus(ctx.baseDoc);
   for (const title of titlesOf(doc)) {
     const seen = titles.get(title);
     if (seen === undefined || seen === 0) {
-      return refuse('a group title changed at the same time as the lane roster, and a ' +
-        'title is not a lane, so which one it used to be is not recoverable; apply the ' +
-        'title change and the lane change as two edits', ctx.range(['signal']));
+      return refuse('a group title changed together with the lane order since the last ' +
+        'write-back, and a title is not a lane, so which one it used to be is not ' +
+        'recoverable; undo back to the last change that was written, then make the title ' +
+        'change and the lane change one at a time', ctx.range(['signal']));
     }
     titles.set(title, seen - 1);
   }
@@ -835,6 +963,273 @@ function isLane(item) {
   return item !== null && typeof item === 'object' && !Array.isArray(item);
 }
 
+// ---------------------------------------------------------------------------
+// Group-level structure: wrap, unwrap, move a whole element
+// ---------------------------------------------------------------------------
+
+/**
+ * The candidate edit lists for a change to the lane tree's GROUPS — one list per
+ * reading, each beginning with `common` — or `[]` when there is none to offer.
+ *
+ * The lane-level planner above sees a change as lanes added, removed and moved,
+ * and every one of its destinations is a lane position. That cannot say three
+ * things the name column does: `groupLanes` and `ungroupLanes` leave every lane
+ * in its display position and change only the arrays around them, and a group
+ * moved past its neighbour looks like several lanes moving — or like one lane
+ * moving to "just before the group, at the group's own level", which no lane
+ * position resolves to (`laneInsertPath` joins a group at its head). So this
+ * plans on the tree instead, with the codec's element-level edits: `wrap`,
+ * `unwrap`, and `move` of a whole element.
+ *
+ * It plans from the two documents only, through a skeleton of each (`skeletonOf`):
+ * the arrays, the titles and other scalars with their values, and every lane as
+ * the base lane it came from — `origins`, the same identity the lane planner
+ * uses. A reading is ONE structural edit that turns the base skeleton into the
+ * current one exactly:
+ *
+ *   - unwrap: a base group whose dissolving gives the current skeleton;
+ *   - wrap: a current group whose dissolving gives the BASE skeleton — the same
+ *     test run backwards, which also hands over the new title as written;
+ *   - move: a base element (lane or group) that, lifted out, leaves the same
+ *     skeleton the current one leaves without that element.
+ *
+ * Every reading that fits is offered, not one chosen by argument — a swap of two
+ * neighbours fits "the upper one moved down" and "the lower one moved up", and
+ * those can be different patches. `toPatch` writes each and keeps the first
+ * that reads back as the document, as it does for the lane planner's readings.
+ *
+ * Only the shape is decided here; what changed INSIDE a lane is added to every
+ * reading as the ordinary per-lane diff, at the lane's base path. That is safe
+ * beside a wrap or unwrap, whose edits sit outside every member, and refused by
+ * the codec as overlapping beside a move of that same lane — which is the
+ * answer the lane planner gives for a moved lane that was also edited.
+ *
+ * Only offered when the roster is intact — every base lane present once, none
+ * new — and the skeletons differ. Lanes added or removed in the same session
+ * as a group change would need two structural edits measured against the same
+ * text, and the lane planner's own refusal is the honest answer there.
+ */
+function planTree(ctx, doc, origins, common) {
+  if (!isPermutation(origins, ctx.basePaths.length)) return [];
+  if (ctx.baseTree === undefined) ctx.baseTree = skeletonOf(ctx.baseDoc, countUp(ctx.basePaths.length));
+  const base = ctx.baseTree;
+  const now = skeletonOf(doc, origins);
+  if (base === null || now === null) return [];
+  const baseSig = sigOf(base, null);
+  const nowSig = sigOf(now, null);
+  if (baseSig === nowSig) return [];
+
+  const structural = [];
+  for (const group of groupsOf(base)) {
+    if (unwrappedSig(base, group) === nowSig) structural.push({ op: 'unwrap', path: group.path });
+  }
+  for (const group of groupsOf(now)) {
+    if (unwrappedSig(now, group) !== baseSig) continue;
+    const titled = group.items.length > 0 && group.items[0].kind === 'other' &&
+      typeof group.items[0].value === 'string';
+    const members = group.items.slice(titled ? 1 : 0);
+    if (members.length === 0 || members.some(function (m) { return m.kind === 'other'; })) continue;
+    // Dissolving it in the current tree gives the base tree, so everything in
+    // front of it — its parent's path and its own index — is the same in both.
+    const edit = { op: 'wrap', path: group.path, count: members.length };
+    if (titled) edit.title = group.items[0].value;
+    structural.push(edit);
+  }
+  const bySig = new Map();
+  for (const node of elementsOf(now)) {
+    const sig = sigOf(node, null);
+    const list = bySig.get(sig);
+    if (list === undefined) bySig.set(sig, [node]);
+    else list.push(node);
+  }
+  for (const node of elementsOf(base)) {
+    const cut = liftedOut(node);
+    const without = sigOf(base, cut);
+    for (const there of bySig.get(sigOf(node, null)) || []) {
+      if (sigOf(now, there) !== without) continue;
+      structural.push({ op: 'move', path: node.path, to: destinationIn(cut, there) });
+    }
+  }
+
+  const alternatives = [];
+  for (const edit of structural) {
+    const edits = common.concat([edit]);
+    const r = laneContent(ctx, doc, now, edits);
+    if (r.ok === true) alternatives.push(edits);
+  }
+  return alternatives;
+}
+
+/** Whether `origins` names every base lane exactly once and nothing new. */
+function isPermutation(origins, n) {
+  if (origins.length !== n) return false;
+  const seen = new Array(n).fill(false);
+  for (const o of origins) {
+    if (o === null || !(o >= 0 && o < n) || seen[o]) return false;
+    seen[o] = true;
+  }
+  return true;
+}
+
+/**
+ * The lane tree of `doc` as plain nodes: `{kind:'group', path, items}` for every
+ * array (the root is `signal` itself), `{kind:'lane', path, id}` for a lane —
+ * `id` being `origins` at its display position, so the two trees name a lane
+ * the same way — and `{kind:'other', path, value}` for a title or any other
+ * scalar. Each node knows its `parent` and its `index` there.
+ *
+ * Display positions come from the codec's own walk (`lanePaths`), not from a
+ * count kept here: a lane's number and its path are matched through the bridge,
+ * the one rule at the top of this file. `null` when the tree is deeper than the
+ * reader would go, or when the two walks disagree about where a lane is.
+ */
+function skeletonOf(doc, origins) {
+  const lanes = signalOf(doc);
+  if (!Array.isArray(lanes)) return null;
+  const display = new Map();
+  const paths = C.lanePaths(doc);
+  for (let j = 0; j < paths.length; j++) display.set(JSON.stringify(paths[j]), j);
+  let sound = true;
+  let counted = 0;
+  const walk = function (arr, path, depth, parent, index) {
+    const node = { kind: 'group', path: path, items: [], parent: parent, index: index };
+    if (depth > MAX_DEPTH) {
+      sound = false;
+      return node;
+    }
+    for (let i = 0; i < arr.length; i++) {
+      const item = arr[i];
+      const here = path.concat([i]);
+      if (Array.isArray(item)) {
+        node.items.push(walk(item, here, depth + 1, node, i));
+      } else if (isLane(item)) {
+        const j = display.get(JSON.stringify(here));
+        if (j === undefined) sound = false;
+        counted++;
+        node.items.push({ kind: 'lane', path: here, id: origins[j], parent: node, index: i });
+      } else {
+        node.items.push({ kind: 'other', path: here, value: item, parent: node, index: i });
+      }
+    }
+    return node;
+  };
+  const root = walk(lanes, ['signal'], 0, null, null);
+  return sound && counted === paths.length ? root : null;
+}
+
+/**
+ * A string that two skeletons share exactly when they are the same tree: nesting,
+ * every scalar with its value, every lane by the base lane it came from. `cut`,
+ * when given, is left out as though it were not there.
+ */
+function sigOf(node, cut) {
+  if (node === cut) return '';
+  if (node.kind === 'lane') return 'L' + node.id + ';';
+  if (node.kind === 'other') return 'S' + scalarKey(node.value) + ';';
+  let out = '[';
+  for (const item of node.items) out += sigOf(item, cut);
+  return out + ']';
+}
+
+/** `sigOf(root)` with `group` dissolved the way `ungroupLanes` dissolves one. */
+function unwrappedSig(root, group) {
+  const walk = function (node) {
+    if (node.kind !== 'group') return sigOf(node, null);
+    const items = node === group ? membersOf(node) : node.items;
+    let inner = '';
+    for (const item of items) inner += walk(item);
+    return node === group ? inner : '[' + inner + ']';
+  };
+  return walk(root);
+}
+
+/** A group's members: everything but a leading title string. */
+function membersOf(group) {
+  const titled = group.items.length > 0 && group.items[0].kind === 'other' &&
+    typeof group.items[0].value === 'string';
+  return group.items.slice(titled ? 1 : 0);
+}
+
+function scalarKey(value) {
+  return typeof value + ':' + (typeof value === 'string' ? JSON.stringify(value) : String(value));
+}
+
+/** Every group below the root, in document order. */
+function groupsOf(root) {
+  return elementsOf(root).filter(function (n) { return n.kind === 'group'; });
+}
+
+/** Every lane and group below the root, in document order (titles left out). */
+function elementsOf(root) {
+  const out = [];
+  const walk = function (node) {
+    for (const item of node.items) {
+      if (item.kind === 'other') continue;
+      out.push(item);
+      if (item.kind === 'group') walk(item);
+    }
+  };
+  walk(root);
+  return out;
+}
+
+/**
+ * What actually leaves the base tree when `node` is moved: the node, or the
+ * group it empties by leaving — the codec's `move` takes that too, by the same
+ * rule `removeLane` follows (a group left holding no lane and no group goes).
+ */
+function liftedOut(node) {
+  let cut = node;
+  while (cut.parent !== null && cut.parent.parent !== null) {
+    const stays = cut.parent.items.some(function (item) {
+      return item !== cut && item.kind !== 'other';
+    });
+    if (stays) break;
+    cut = cut.parent;
+  }
+  return cut;
+}
+
+/**
+ * Where a moved element lands, as a `move` destination in the BASE document,
+ * given the node it became in the current tree.
+ *
+ * With the element lifted out of both, the two trees are the same, so the
+ * current parent's path and index are already right for the base tree minus
+ * `cut`. Putting `cut` back shifts every position at or after it in its own
+ * array up by one — which is what turns that answer into one in the base text.
+ */
+function destinationIn(cut, there) {
+  const cutParent = cut.parent.path;
+  const at = cut.index;
+  const parent = there.parent.path.slice();
+  const depth = cutParent.length;
+  if (parent.length > depth && isPrefixPath(cutParent, parent) && parent[depth] >= at) {
+    parent[depth] += 1;
+  }
+  let index = there.index;
+  if (parent.length === depth && isPrefixPath(cutParent, parent) && index >= at) index += 1;
+  return parent.concat([index]);
+}
+
+/**
+ * Append to `edits` what changed inside each lane, at its base path. The lanes
+ * are matched by origin through the skeleton, so a lane that moved is still
+ * compared with itself.
+ */
+function laneContent(ctx, doc, now, edits) {
+  for (const node of elementsOf(now)) {
+    if (node.kind !== 'lane') continue;
+    const basePath = ctx.basePaths[node.id];
+    const was = valueAt(ctx.baseDoc, basePath);
+    const is = valueAt(doc, node.path);
+    if (was === is) continue;
+    const r = diffValue(ctx, basePath, was, is, edits);
+    if (r.ok !== true) return r;
+  }
+  return OK;
+}
+
 // ---------------------------------------------------------------------------
 // Value-level difference
 // ---------------------------------------------------------------------------