@dogsbay/tree-diff 0.0.0-stage → 0.2.0-beta.131

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# @dogsbay/tree-diff
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`diffTrees(oldTree, newTree)` — identity-driven version diffing over
+`TreeNode[]`, producing one **DiffTree** that every view renders:
+comparison pages (side-by-side or merged), PR review, the
+version-switcher compare mode, the IDE's change review, and
+`@dogsbay/render`'s `compareWith` (the artifact viewer's Changes view).
+
+```ts
+import { diffTrees } from "@dogsbay/tree-diff";
+import { dogsbayMdToTree } from "@dogsbay/format-dogsbay-md";
+
+const oldTree = dogsbayMdToTree(oldMarkdown).tree;
+const newTree = dogsbayMdToTree(newMarkdown).tree;
+const { tree, stats, unchanged } = diffTrees(oldTree, newTree);
+```
+
+The output is the union tree in new-side order (removed content
+spliced at its old anchors). Nodes carry optional marks a
+mark-unaware renderer simply ignores:
+
+| Field | Meaning |
+|---|---|
+| `diff` | `added` / `removed` / `changed` / `moved` — set on subtree roots for added/removed |
+| `diffInline` | merged word-level `eq/ins/del` segments on changed prose (render all = merged view; filter by op = either side) |
+| `diffPeer` | the other side's node for changed pairs (code samples, table rows) |
+| `diffMovedFrom` | old heading path for moved sections |
+
+Identity drives matching: sections by heading **path** (which gives
+`## POST /path` endpoint sections `(method, path)` identity for
+free), code samples by `(language, title, occurrence)`, table rows by
+first cell, containers/lists by `(type, occurrence)` with recursive
+children, prose by position + token similarity. Relocated sections
+are **moves**, never delete+add — the reorg-vs-removal discipline,
+enforced in the renderer layer.
+
+Golden reference: the real better-auth `plugins/2fa.md` across the
+hand-reviewed v1.5.6 → v1.6.23 transition (fixtures in `tests/`),
+including the known `password` required→optional drift surfacing as
+word-level marks.
+
+## License
+
+MIT

package/dist/diff.d.ts

@@ -0,0 +1,46 @@
+/**
+ * diffTrees — identity-driven diff over two parsed pages
+ * (plans/tree-diff-rendering.md §1).
+ *
+ * The parsed page is FLAT (headings are siblings of content), so the
+ * differ first sectionizes both sides by heading level, then matches:
+ *
+ *   sections   → heading PATH (text within parent — not text alone:
+ *                the Addendum-7 lesson; `## POST /path` endpoint
+ *                sections get (method, path) identity for free)
+ *   moves      → unmatched removed+added sections with equal heading
+ *                text or equal content — marked, never delete+add
+ *                (the reorg-vs-removal discipline, in the renderer)
+ *   code       → (language, title, occurrence) within the section —
+ *                the chunk-identity fields whose page/headingPath
+ *                components are equal inside a matched section
+ *   containers → (type, occurrence); children recurse as block lists
+ *   table rows → first-cell text within the matched table
+ *   prose      → position + token-similarity fallback, with
+ *                word-level ins/del segments on changed nodes
+ *
+ * Output is the union tree in NEW-side order with removed content
+ * spliced at its old anchor; marks are `diff` / `diffInline` /
+ * `diffPeer` / `diffMovedFrom` fields a mark-unaware renderer simply
+ * ignores.
+ */
+import type { TreeNode } from "@dogsbay/types";
+import type { DiffResult } from "./types.js";
+interface Section {
+    /** Heading texts from the page root to this section. */
+    path: string[];
+    heading: TreeNode | null;
+    level: number;
+    blocks: TreeNode[];
+    children: Section[];
+    /** Set when an added section elsewhere claims this one as a MOVE. */
+    claimedAsMove?: boolean;
+}
+/** Group a flat page into a section tree by heading level. */
+export declare function sectionize(nodes: TreeNode[]): Section;
+/**
+ * Diff two parsed pages. `oldTree`/`newTree` are page bodies as any
+ * dogsbay format loader produces them (flat heading structure).
+ */
+export declare function diffTrees(oldTree: TreeNode[], newTree: TreeNode[]): DiffResult;
+export {};

package/dist/diff.js

@@ -0,0 +1,556 @@
+import { decodeNumericEntities, inlineText, nodeText, similarity, wordDiff } from "./text.js";
+/** Prose blocks whose change renders as word-level inline marks. */
+const PROSE_TYPES = new Set(["paragraph", "blockquote", "list-item", "li"]);
+/** Containers whose children are matched recursively as block lists. */
+const CONTAINER_TYPES = new Set([
+    "callout",
+    "tabs",
+    "tab",
+    "steps",
+    "step",
+    "details",
+    "blockquote",
+    // lists recurse so their ITEMS prose-diff individually — the
+    // endpoint request-body rows (`- \`password\` … — required`) are
+    // list items, and the required→optional drift must surface as
+    // word-level marks, not an opaque changed list.
+    "unordered-list",
+    "ordered-list",
+]);
+const SIMILARITY_THRESHOLD = 0.5;
+function headingText(node) {
+    return nodeText(node);
+}
+/** Group a flat page into a section tree by heading level. */
+export function sectionize(nodes) {
+    const root = { path: [], heading: null, level: 0, blocks: [], children: [] };
+    const stack = [root];
+    for (const node of nodes) {
+        if (node.type === "heading") {
+            const level = Number(node.props?.level ?? 1);
+            while (stack.length > 1 && stack[stack.length - 1].level >= level)
+                stack.pop();
+            const parent = stack[stack.length - 1];
+            const section = {
+                path: [...parent.path, headingText(node)],
+                heading: node,
+                level,
+                blocks: [],
+                children: [],
+            };
+            parent.children.push(section);
+            stack.push(section);
+        }
+        else {
+            stack[stack.length - 1].blocks.push(node);
+        }
+    }
+    return root;
+}
+/**
+ * Whether two nodes have the same content. A node's source line (`meta.line`, from a parser's `sourceLines`)
+ * says where it is, not what it is: compared, every block below an edit would show as changed.
+ */
+const withoutLines = (key, value) => {
+    if (key !== "meta" || !value || typeof value !== "object" || !("line" in value))
+        return value;
+    const { line: _line, ...rest } = value;
+    return Object.keys(rest).length ? rest : undefined;
+};
+const sameContent = (a, b) => JSON.stringify(a, withoutLines) === JSON.stringify(b, withoutLines);
+/** Stable content fingerprint of a section (its own blocks + subtree). */
+function sectionFingerprint(s) {
+    const parts = [s.blocks.map(nodeText).join("
")];
+    for (const c of s.children)
+        parts.push(c.path[c.path.length - 1] ?? "", sectionFingerprint(c));
+    return parts.join("");
+}
+const mark = (node, diff, extra) => ({
+    ...node,
+    diff,
+    ...extra,
+});
+/** Deep: does this node or any descendant carry a diff mark? */
+const hasAnyMark = (node) => Boolean(node.diff || node.diffInline) ||
+    (node.children ?? []).some(hasAnyMark);
+/** Containers whose content is hidden until interacted with. */
+const HIDDEN_CONTAINERS = new Set(["tabs", "tab", "details"]);
+/**
+ * Callout interior: drop the block bar where it merely duplicates
+ * word-level marks (the container's own mark covers the box); KEEP
+ * code marks — they drive before/after pair rendering, which is
+ * content, not a bar.
+ */
+const stripBlockMarks = (node) => {
+    const keep = node.type === "code" || !node.diffInline;
+    const out = {
+        ...node,
+        ...(node.children ? { children: node.children.map(stripBlockMarks) } : {}),
+    };
+    if (!keep && out.diff === "changed")
+        delete out.diff;
+    return out;
+};
+class Differ {
+    stats = {
+        sectionsAdded: 0,
+        sectionsRemoved: 0,
+        sectionsChanged: 0,
+        sectionsMoved: 0,
+        blocksChanged: 0,
+    };
+    /** Removed old-side sections, indexed for move detection. */
+    removedByFingerprint = new Map();
+    /** heading text → ALL removed sections with that heading (no last-writer-wins). */
+    removedByHeading = new Map();
+    /** added new-side section → the old-side section it relocates. */
+    moveClaims = new Map();
+    diff(oldTree, newTree) {
+        const oldRoot = sectionize(oldTree);
+        const newRoot = sectionize(newTree);
+        this.indexRemoved(oldRoot, newRoot);
+        this.claimMoves(oldRoot, newRoot);
+        return this.diffSectionInto(oldRoot, newRoot);
+    }
+    /**
+     * Sibling keys are occurrence-disambiguated (`name#n`, mirroring
+     * blockKeys) — duplicate heading texts among siblings must not
+     * collapse in a Map (a page diffed against itself must be
+     * unchanged).
+     */
+    childKeys(sec) {
+        const seen = new Map();
+        const out = new Map();
+        for (const c of sec.children) {
+            const name = c.path[c.path.length - 1] ?? "";
+            const n = seen.get(name) ?? 0;
+            seen.set(name, n + 1);
+            out.set(`${name}#${n}`, c);
+        }
+        return out;
+    }
+    /**
+     * Pre-pass 2: added new-side sections claim removed old-side
+     * sections as MOVES — globally, before any emission, so a parent's
+     * removed loop can't emit a section that relocates deeper in the
+     * tree. Guards (review findings 1–2):
+     *  - claims require identical content (fingerprint) OR same heading
+     *    text WITH similar content — a coincidental name never claims;
+     *  - claims never recurse INTO an unclaimed added subtree, because
+     *    emitSection renders added subtrees whole and a claim there
+     *    would silently swallow the removed section's content.
+     */
+    claimMoves(oldSec, newSec) {
+        const oldKeys = this.childKeys(oldSec);
+        const newKeys = this.childKeys(newSec);
+        for (const [key, newChild] of newKeys) {
+            const match = oldKeys.get(key);
+            if (match) {
+                this.claimMoves(match, newChild);
+                continue;
+            }
+            const name = newChild.path[newChild.path.length - 1] ?? "";
+            const fp = sectionFingerprint(newChild);
+            let moved = this.removedByFingerprint.get(fp);
+            if (moved?.claimedAsMove)
+                moved = undefined;
+            if (!moved) {
+                // same heading text: pick the best UNCLAIMED candidate whose
+                // content is actually similar
+                let best;
+                let bestScore = 0;
+                for (const cand of this.removedByHeading.get(name) ?? []) {
+                    if (cand.claimedAsMove)
+                        continue;
+                    const score = similarity(sectionFingerprint(cand), fp);
+                    if (score > bestScore) {
+                        best = cand;
+                        bestScore = score;
+                    }
+                }
+                if (best && bestScore >= SIMILARITY_THRESHOLD)
+                    moved = best;
+            }
+            if (moved) {
+                moved.claimedAsMove = true;
+                this.moveClaims.set(newChild, moved);
+                // nested claims are safe within a claimed (rendered) pair
+                this.claimMoves(moved, newChild);
+            }
+            // unclaimed added subtree: do NOT recurse — see guard note above
+        }
+    }
+    /**
+     * Pre-pass: find sections present only on the old side and index
+     * them, so additions elsewhere can claim them as MOVES.
+     */
+    indexRemoved(oldSec, newSec) {
+        const oldKeys = this.childKeys(oldSec);
+        const newKeys = this.childKeys(newSec);
+        for (const [key, oldChild] of oldKeys) {
+            const match = newKeys.get(key);
+            if (match)
+                this.indexRemoved(oldChild, match);
+            else {
+                const name = oldChild.path[oldChild.path.length - 1] ?? "";
+                this.removedByFingerprint.set(sectionFingerprint(oldChild), oldChild);
+                const list = this.removedByHeading.get(name) ?? [];
+                list.push(oldChild);
+                this.removedByHeading.set(name, list);
+            }
+        }
+    }
+    /** Union of one matched section pair, marks applied. */
+    diffSectionInto(oldSec, newSec) {
+        const out = [];
+        const blocksBefore = this.stats.blocksChanged;
+        out.push(...this.diffBlocks(oldSec.blocks, newSec.blocks));
+        // Captured BEFORE child recursion: sectionsChanged counts the
+        // section whose OWN blocks changed — once, at the deepest level,
+        // not once per ancestor (review finding 5). Structure events
+        // (child add/remove/move) have their own stats.
+        if (this.stats.blocksChanged !== blocksBefore)
+            this.stats.sectionsChanged++;
+        const oldKeys = this.childKeys(oldSec);
+        const newKeys = this.childKeys(newSec);
+        // removed child sections splice in old-side order after the blocks
+        // of the section they lived in.
+        for (const [key, oldChild] of oldKeys) {
+            if (newKeys.has(key))
+                continue;
+            if (oldChild.claimedAsMove)
+                continue; // rendered at its new home
+            this.stats.sectionsRemoved++;
+            out.push(...this.emitSection(oldChild, "removed"));
+        }
+        for (const [key, newChild] of newKeys) {
+            const oldChild = oldKeys.get(key);
+            if (oldChild) {
+                const body = this.diffSectionInto(oldChild, newChild);
+                // render-trail mark on the heading when ANYTHING inside changed
+                const changedInside = body.some(hasAnyMark);
+                if (newChild.heading) {
+                    out.push(changedInside ? mark(newChild.heading, "changed") : { ...newChild.heading });
+                }
+                out.push(...body);
+            }
+            else {
+                const moved = this.moveClaims.get(newChild);
+                if (moved) {
+                    this.stats.sectionsMoved++;
+                    if (newChild.heading) {
+                        out.push(mark(newChild.heading, "moved", { diffMovedFrom: moved.path }));
+                    }
+                    // content may ALSO have changed across the move
+                    out.push(...this.diffSectionInto(moved, newChild));
+                }
+                else {
+                    this.stats.sectionsAdded++;
+                    out.push(...this.emitSection(newChild, "added"));
+                }
+            }
+        }
+        return out;
+    }
+    /** Emit a whole section subtree under one mark (root-marked). */
+    emitSection(sec, diff) {
+        const out = [];
+        if (sec.heading)
+            out.push(mark(sec.heading, diff));
+        for (const block of sec.blocks)
+            out.push(mark(block, diff));
+        for (const child of sec.children)
+            out.push(...this.emitSection(child, diff));
+        return out;
+    }
+    /**
+     * Merge consecutive raw-HTML siblings into one block on BOTH sides
+     * before matching. Markdown parsers split one HTML structure (a
+     * hand-written table) into fragments at internal blank lines, and
+     * a blank line added upstream would otherwise shard the diff into
+     * "1 changed + N added" pieces of the same table (found via
+     * better-auth adapters/mysql). Joining with the original separator
+     * renders identically.
+     */
+    coalesceHtml(blocks) {
+        const out = [];
+        for (const b of blocks) {
+            const prev = out[out.length - 1];
+            if (b.type === "html" && prev?.type === "html") {
+                out[out.length - 1] = { ...prev, html: `${prev.html ?? ""}\n${b.html ?? ""}` };
+            }
+            else {
+                out.push(b);
+            }
+        }
+        return out;
+    }
+    /** Match the non-heading blocks of one matched section pair. */
+    diffBlocks(oldBlocksIn, newBlocksIn) {
+        const oldBlocks = this.coalesceHtml(oldBlocksIn);
+        const newBlocks = this.coalesceHtml(newBlocksIn);
+        const out = [];
+        const usedOld = new Set();
+        // identity pass: code by (language, title, occurrence); containers
+        // and tables by (type, occurrence)
+        const oldKey = this.blockKeys(oldBlocks);
+        const newKey = this.blockKeys(newBlocks);
+        const oldByKey = new Map();
+        oldKey.forEach((k, i) => {
+            if (k && !oldByKey.has(k))
+                oldByKey.set(k, i);
+        });
+        const matchedPairs = new Map(); // new index → old index
+        newKey.forEach((k, j) => {
+            if (!k)
+                return;
+            const i = oldByKey.get(k);
+            if (i !== undefined && !usedOld.has(i)) {
+                matchedPairs.set(j, i);
+                usedOld.add(i);
+            }
+        });
+        // positional prose pass over the leftovers, in order (texts cached
+        // once per block — nodeText recurses whole subtrees)
+        const oldText = oldBlocks.map((b) => nodeText(b));
+        const newText = newBlocks.map((b) => nodeText(b));
+        const oldLeft = oldBlocks.map((_, i) => i).filter((i) => !usedOld.has(i) && !oldKey[i]);
+        const newLeft = newBlocks.map((_, j) => j).filter((j) => !matchedPairs.has(j) && !newKey[j]);
+        let ol = 0;
+        for (const j of newLeft) {
+            // find the next sufficiently-similar old block at or after ol
+            for (let k = ol; k < oldLeft.length; k++) {
+                const i = oldLeft[k];
+                if (oldBlocks[i].type === newBlocks[j].type &&
+                    similarity(oldText[i], newText[j]) >= SIMILARITY_THRESHOLD) {
+                    matchedPairs.set(j, i);
+                    usedOld.add(i);
+                    // removed blocks skipped over are emitted at this anchor
+                    ol = k + 1;
+                    break;
+                }
+            }
+        }
+        // emit: new order, removed old blocks spliced before their next
+        // matched old sibling's pair
+        const removedBefore = new Map(); // old index → removed nodes before it
+        let pending = [];
+        for (let i = 0; i < oldBlocks.length; i++) {
+            if (usedOld.has(i)) {
+                if (pending.length)
+                    removedBefore.set(i, pending);
+                pending = [];
+            }
+            else {
+                pending.push(oldBlocks[i]);
+            }
+        }
+        const removedAtEnd = pending;
+        for (let j = 0; j < newBlocks.length; j++) {
+            const i = matchedPairs.get(j);
+            if (i !== undefined) {
+                for (const r of removedBefore.get(i) ?? []) {
+                    this.stats.blocksChanged++;
+                    out.push(mark(r, "removed"));
+                }
+                out.push(this.diffMatchedBlock(oldBlocks[i], newBlocks[j]));
+            }
+            else {
+                this.stats.blocksChanged++;
+                out.push(mark(newBlocks[j], "added"));
+            }
+        }
+        for (const r of removedAtEnd) {
+            this.stats.blocksChanged++;
+            out.push(mark(r, "removed"));
+        }
+        return out;
+    }
+    /** Identity keys per block; empty string = positional/prose block. */
+    blockKeys(blocks) {
+        const seen = new Map();
+        return blocks.map((b) => {
+            let base = "";
+            if (b.type === "code") {
+                base = `code
${b.props?.language ?? ""}
${b.props?.title ?? ""}`;
+            }
+            else if (b.type === "table") {
+                base = "table";
+            }
+            else if (CONTAINER_TYPES.has(b.type)) {
+                base = `container
${b.type}
${b.props?.type ?? ""}`;
+            }
+            else {
+                return "";
+            }
+            const n = seen.get(base) ?? 0;
+            seen.set(base, n + 1);
+            return `${base}
#${n}`;
+        });
+    }
+    /** Same-identity pair: unchanged, or changed with the right marks. */
+    diffMatchedBlock(oldB, newB) {
+        if (sameContent(oldB, newB))
+            return { ...newB };
+        if (newB.type === "code") {
+            this.stats.blocksChanged++;
+            return mark(newB, "changed", { diffPeer: oldB });
+        }
+        if (newB.type === "table") {
+            return this.diffTable(oldB, newB);
+        }
+        if (CONTAINER_TYPES.has(newB.type)) {
+            const children = this.diffBlocks(oldB.children ?? [], newB.children ?? []);
+            const propsChanged = JSON.stringify(oldB.props ?? {}) !== JSON.stringify(newB.props ?? {});
+            const childChanged = children.some(hasAnyMark);
+            // A container that carries its OWN prose (a `step` keeps its text in
+            // `inline`, children usually empty) must diff that text too — otherwise
+            // an edit to a step is a silent false negative (review 2026-08-18).
+            const ownOld = oldB.inline ? inlineText(oldB.inline) : "";
+            const ownNew = newB.inline ? inlineText(newB.inline) : "";
+            if (ownOld !== ownNew) {
+                this.stats.blocksChanged++;
+                const segments = wordDiff(ownOld, ownNew);
+                return { ...newB, diff: "changed", ...(segments ? { diffInline: segments } : {}), diffPeer: oldB, children };
+            }
+            // Visibility-aware container marking (user feedback 2026-07-13):
+            //  - HIDDEN-content containers (tabs, details): an inner change
+            //    is invisible until opened — the container MUST carry the
+            //    mark so the closed state signals it; inner marks stay for
+            //    when it opens.
+            //  - Small bounded boxes (callout): one outer mark reads
+            //    cleaner than bars inside a colored box — mark the
+            //    container, strip inner BLOCK bars, keep word-level marks.
+            //  - Always-visible sequences (lists, steps, blockquote): the
+            //    item marks ARE the diff; a container bar spanning a long
+            //    list is noise. Container marks only for its own props.
+            if (HIDDEN_CONTAINERS.has(newB.type) && (childChanged || propsChanged)) {
+                this.stats.blocksChanged++;
+                return { ...newB, diff: "changed", children };
+            }
+            if (newB.type === "callout" && (childChanged || propsChanged)) {
+                this.stats.blocksChanged++;
+                return {
+                    ...newB,
+                    diff: "changed",
+                    children: children.map(stripBlockMarks),
+                };
+            }
+            if (propsChanged) {
+                this.stats.blocksChanged++;
+                return { ...newB, diff: "changed", children };
+            }
+            return { ...newB, children };
+        }
+        if (newB.type === "html") {
+            // Render-equivalent markup is NOT a change: entity-form flips
+            // (&#9989; ↔ ✅) and whitespace-run differences (HTML collapses
+            // them outside <pre>). Anything else is opaque markup: block
+            // mark + peer.
+            const comparable = (s) => {
+                const decoded = decodeNumericEntities(s);
+                return decoded.includes("<pre") ? decoded : decoded.replace(/\s+/g, " ").trim();
+            };
+            if (comparable(String(oldB.html ?? "")) === comparable(String(newB.html ?? ""))) {
+                return { ...newB };
+            }
+            this.stats.blocksChanged++;
+            return mark(newB, "changed", { diffPeer: oldB });
+        }
+        if (PROSE_TYPES.has(newB.type) || newB.inline) {
+            this.stats.blocksChanged++;
+            // wordDiff returns null over its size cap — fall back to a plain
+            // changed mark with diffPeer (views render before/after blocks)
+            const segments = wordDiff(nodeText(oldB), nodeText(newB));
+            return mark(newB, "changed", {
+                ...(segments ? { diffInline: segments } : {}),
+                diffPeer: oldB,
+            });
+        }
+        this.stats.blocksChanged++;
+        return mark(newB, "changed", { diffPeer: oldB });
+    }
+    /**
+     * Row-level table diff. Rows are keyed by section (thead/tbody) +
+     * first-cell text + occurrence, so duplicate first cells never
+     * collapse (a deleted duplicate row MUST surface — silent
+     * false-negatives are the worst failure class here).
+     */
+    diffTable(oldT, newT) {
+        const keyRows = (t) => {
+            const seen = new Map();
+            const out = new Map();
+            for (const part of t.children ?? []) {
+                if (part.type !== "tbody" && part.type !== "thead")
+                    continue;
+                for (const tr of part.children ?? []) {
+                    const base = `${part.type}:${nodeText((tr.children ?? [])[0] ?? tr)}`;
+                    const n = seen.get(base) ?? 0;
+                    seen.set(base, n + 1);
+                    out.set(`${base}#${n}`, tr);
+                }
+            }
+            return out;
+        };
+        const oldRows = keyRows(oldT);
+        const newRowKeys = keyRows(newT);
+        const keyOfNew = new Map();
+        for (const [k, tr] of newRowKeys)
+            keyOfNew.set(tr, k);
+        let changed = false;
+        const mapPart = (part) => {
+            if (part.type !== "tbody" && part.type !== "thead")
+                return { ...part };
+            const children = (part.children ?? []).map((tr) => {
+                const key = keyOfNew.get(tr);
+                const old = oldRows.get(key);
+                if (!old) {
+                    changed = true;
+                    return mark(tr, "added");
+                }
+                oldRows.delete(key);
+                if (!sameContent(old, tr)) {
+                    changed = true;
+                    return mark(tr, "changed", { diffPeer: old });
+                }
+                return { ...tr };
+            });
+            return { ...part, children };
+        };
+        let parts = (newT.children ?? []).map(mapPart);
+        // rows that vanished (keys left in oldRows) render as removed —
+        // in the last tbody, or a synthesized one when the new table has
+        // none (a removed row must never be dropped).
+        const leftover = [...oldRows.values()];
+        if (leftover.length) {
+            changed = true;
+            let lastBody = [...parts].reverse().find((p) => p.type === "tbody");
+            if (!lastBody) {
+                lastBody = { type: "tbody", children: [] };
+                parts = [...parts, lastBody];
+            }
+            lastBody.children = [
+                ...(lastBody.children ?? []),
+                ...leftover.map((r) => mark(r, "removed")),
+            ];
+        }
+        if (changed)
+            this.stats.blocksChanged++;
+        return changed ? { ...newT, diff: "changed", children: parts } : { ...newT, children: parts };
+    }
+}
+/**
+ * Diff two parsed pages. `oldTree`/`newTree` are page bodies as any
+ * dogsbay format loader produces them (flat heading structure).
+ */
+export function diffTrees(oldTree, newTree) {
+    const differ = new Differ();
+    const tree = differ.diff(oldTree, newTree);
+    const stats = differ.stats;
+    const unchanged = stats.sectionsAdded === 0 &&
+        stats.sectionsRemoved === 0 &&
+        stats.sectionsChanged === 0 &&
+        stats.sectionsMoved === 0 &&
+        stats.blocksChanged === 0;
+    return { tree, stats, unchanged };
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @dogsbay/tree-diff — version diffing as a core renderer capability.
+ *
+ * `diffTrees(oldTree, newTree)` produces one DiffTree that every view
+ * renders: comparison pages (side-by-side or merged), PR review, the
+ * version-switcher compare mode, and the IDE's change review.
+ * See plans/tree-diff-rendering.md.
+ */
+export { diffTrees, sectionize } from "./diff.js";
+export { foldUnchangedSections, type FoldResult } from "./views.js";
+export { wordDiff, similarity, nodeText, inlineText } from "./text.js";
+export type { DiffKind, DiffNode, DiffResult, DiffStats, InlineDiffSegment, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * @dogsbay/tree-diff — version diffing as a core renderer capability.
+ *
+ * `diffTrees(oldTree, newTree)` produces one DiffTree that every view
+ * renders: comparison pages (side-by-side or merged), PR review, the
+ * version-switcher compare mode, and the IDE's change review.
+ * See plans/tree-diff-rendering.md.
+ */
+export { diffTrees, sectionize } from "./diff.js";
+export { foldUnchangedSections } from "./views.js";
+export { wordDiff, similarity, nodeText, inlineText } from "./text.js";

package/dist/text.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Text utilities: plain-text extraction from TreeNode/inline spans,
+ * tokenization, and a compact LCS word-differ producing the merged
+ * ins/del/eq segments prose nodes carry as `diffInline`.
+ */
+import type { InlineNode, TreeNode } from "@dogsbay/types";
+import type { InlineDiffSegment } from "./types.js";
+/**
+ * Decode numeric character references so `✅` and `✅` compare
+ * equal — upstream docs flip between entity and literal forms without
+ * any semantic change (found via better-auth adapters/mysql).
+ */
+export declare function decodeNumericEntities(s: string): string;
+/** Plain text of a node's inline spans (or html fallback), recursively. */
+export declare function nodeText(node: TreeNode): string;
+export declare function inlineText(spans: InlineNode[]): string;
+/**
+ * Guard for the quadratic LCS table: beyond this many tokens PER SIDE
+ * the differ returns null and the caller falls back to a block-level
+ * changed mark with diffPeer (a 10k-word pair would allocate ~800 MB;
+ * corpus pages are untrusted-size upstream input).
+ */
+export declare const WORD_DIFF_MAX_TOKENS = 1500;
+/**
+ * Merged word-level diff (classic LCS over word tokens). Adjacent
+ * same-op runs are coalesced; output order is old-side for deletions
+ * interleaved at their anchors — i.e. the "merged reading view".
+ * Returns null when either side exceeds WORD_DIFF_MAX_TOKENS.
+ */
+export declare function wordDiff(oldText: string, newText: string): InlineDiffSegment[] | null;
+/**
+ * Token-set similarity in [0, 1] — the positional prose matcher's
+ * "same block, edited" test.
+ */
+export declare function similarity(a: string, b: string): number;

package/dist/text.js

@@ -0,0 +1,124 @@
+/**
+ * Decode numeric character references so `✅` and `✅` compare
+ * equal — upstream docs flip between entity and literal forms without
+ * any semantic change (found via better-auth adapters/mysql).
+ */
+export function decodeNumericEntities(s) {
+    return s
+        .replace(/&#(\d+);/g, (m, d) => {
+        const cp = Number(d);
+        return cp <= 0x10ffff ? String.fromCodePoint(cp) : m;
+    })
+        .replace(/&#x([0-9a-f]+);/gi, (m, h) => {
+        const cp = parseInt(h, 16);
+        return cp <= 0x10ffff ? String.fromCodePoint(cp) : m;
+    });
+}
+/** Plain text of a node's inline spans (or html fallback), recursively. */
+export function nodeText(node) {
+    const parts = [];
+    if (node.inline)
+        parts.push(inlineText(node.inline));
+    else if (typeof node.html === "string") {
+        parts.push(decodeNumericEntities(node.html.replace(/<[^>]+>/g, "")));
+    }
+    for (const child of node.children ?? [])
+        parts.push(nodeText(child));
+    return parts.join(" ").replace(/\s+/g, " ").trim();
+}
+export function inlineText(spans) {
+    return spans
+        .map((s) => {
+        switch (s.type) {
+            case "text":
+            case "code":
+                return s.text ?? "";
+            case "link":
+                return inlineText(s.children ?? []);
+            default:
+                return s.text ?? "";
+        }
+    })
+        .join("");
+}
+/** Word tokens with attached trailing whitespace, so joins reconstruct. */
+function tokenize(text) {
+    return text.match(/\S+\s*/g) ?? [];
+}
+/**
+ * Guard for the quadratic LCS table: beyond this many tokens PER SIDE
+ * the differ returns null and the caller falls back to a block-level
+ * changed mark with diffPeer (a 10k-word pair would allocate ~800 MB;
+ * corpus pages are untrusted-size upstream input).
+ */
+export const WORD_DIFF_MAX_TOKENS = 1500;
+/**
+ * Merged word-level diff (classic LCS over word tokens). Adjacent
+ * same-op runs are coalesced; output order is old-side for deletions
+ * interleaved at their anchors — i.e. the "merged reading view".
+ * Returns null when either side exceeds WORD_DIFF_MAX_TOKENS.
+ */
+export function wordDiff(oldText, newText) {
+    const a = tokenize(oldText);
+    const b = tokenize(newText);
+    const m = a.length;
+    const n = b.length;
+    if (m > WORD_DIFF_MAX_TOKENS || n > WORD_DIFF_MAX_TOKENS)
+        return null;
+    const lcs = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+    for (let i = m - 1; i >= 0; i--) {
+        for (let j = n - 1; j >= 0; j--) {
+            lcs[i][j] =
+                a[i].trim() === b[j].trim()
+                    ? lcs[i + 1][j + 1] + 1
+                    : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+        }
+    }
+    const segments = [];
+    const push = (op, text) => {
+        const last = segments[segments.length - 1];
+        if (last && last.op === op)
+            last.text += text;
+        else
+            segments.push({ op, text });
+    };
+    let i = 0;
+    let j = 0;
+    while (i < m && j < n) {
+        if (a[i].trim() === b[j].trim()) {
+            push("eq", b[j]); // new side's whitespace wins for reconstruction
+            i++;
+            j++;
+        }
+        else if (lcs[i + 1][j] >= lcs[i][j + 1]) {
+            push("del", a[i]);
+            i++;
+        }
+        else {
+            push("ins", b[j]);
+            j++;
+        }
+    }
+    while (i < m)
+        push("del", a[i++]);
+    while (j < n)
+        push("ins", b[j++]);
+    return segments;
+}
+/**
+ * Token-set similarity in [0, 1] — the positional prose matcher's
+ * "same block, edited" test.
+ */
+export function similarity(a, b) {
+    if (a === b)
+        return 1;
+    const ta = new Set(a.toLowerCase().split(/\s+/).filter(Boolean));
+    const tb = new Set(b.toLowerCase().split(/\s+/).filter(Boolean));
+    if (ta.size === 0 && tb.size === 0)
+        return 1;
+    let common = 0;
+    for (const t of ta)
+        if (tb.has(t))
+            common++;
+    return common / Math.max(ta.size, tb.size);
+}

package/dist/types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * DiffTree — the annotated union tree `diffTrees` produces
+ * (plans/tree-diff-rendering.md). A DiffNode IS a TreeNode plus diff
+ * marks; renderers that don't know the marks render it unchanged,
+ * which is the design's core property: one transform, normal
+ * renderers, many views.
+ */
+import type { TreeNode } from "@dogsbay/types";
+export type DiffKind = "added" | "removed" | "changed" | "moved";
+/** One run of the merged word-level diff of a prose node's text. */
+export interface InlineDiffSegment {
+    op: "eq" | "ins" | "del";
+    text: string;
+}
+export interface DiffNode extends TreeNode {
+    /**
+     * The node's diff mark. Set on the ROOT of an added/removed subtree
+     * (children are implied), and on individual changed/moved nodes.
+     * Absent = unchanged.
+     */
+    diff?: DiffKind;
+    /**
+     * Word-level merged diff of a changed prose node's plain text.
+     * Render all segments for the merged view; filter `ins` for the
+     * old side / `del` for the new side in side-by-side.
+     */
+    diffInline?: InlineDiffSegment[];
+    /**
+     * For changed leaf PAIRS (code samples, table rows): the other
+     * side's node, so views can render before/after.
+     */
+    diffPeer?: TreeNode;
+    /** For moved sections: the heading path on the other side. */
+    diffMovedFrom?: string[];
+    children?: DiffNode[];
+}
+/**
+ * Summary counts a comparison page's docs-ops view reports.
+ * Added/removed count subtree ROOTS: a new section with three
+ * subsections is ONE added section (its children are implied by the
+ * root mark), matching how the marks render.
+ */
+export interface DiffStats {
+    sectionsAdded: number;
+    sectionsRemoved: number;
+    sectionsChanged: number;
+    sectionsMoved: number;
+    blocksChanged: number;
+}
+export interface DiffResult {
+    /** Union tree in new-side order; removed content spliced at anchors. */
+    tree: DiffNode[];
+    stats: DiffStats;
+    /** True when the two inputs are identical (no marks anywhere). */
+    unchanged: boolean;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/views.d.ts

@@ -0,0 +1,7 @@
+import type { DiffNode } from "./types.js";
+/** Number of foldable (level ≥ 2) sections that were folded. */
+export interface FoldResult {
+    tree: DiffNode[];
+    folded: number;
+}
+export declare function foldUnchangedSections(tree: DiffNode[]): FoldResult;

package/dist/views.js

@@ -0,0 +1,46 @@
+import { sectionize } from "./diff.js";
+import { nodeText } from "./text.js";
+const hasAnyMark = (node) => Boolean(node.diff || node.diffInline) ||
+    (node.children ?? []).some(hasAnyMark);
+const sectionNodes = (sec) => [
+    ...(sec.heading ? [sec.heading] : []),
+    ...sec.blocks,
+    ...sec.children.flatMap(sectionNodes),
+];
+const sectionUnchanged = (sec) => !sectionNodes(sec).some(hasAnyMark);
+export function foldUnchangedSections(tree) {
+    const root = sectionize(tree);
+    let folded = 0;
+    const emitSection = (sec) => {
+        if (sec.level >= 2 && sec.heading && sectionUnchanged(sec)) {
+            folded++;
+            return [
+                {
+                    type: "details",
+                    props: {
+                        title: `Unchanged: ${nodeText(sec.heading)}`,
+                        // `plain` = chrome, not content: a fold is collapsed
+                        // CONTEXT, not a note, so it gets no alert semantics, no
+                        // icon, and no ARIA role (the previous `note` variant put
+                        // role="note" on a <details>, which axe rejects — details
+                        // has an implicit `group` role that ARIA won't let you
+                        // override). Styled as dashed/dimmed chrome by DIFF_CSS.
+                        variant: "plain",
+                        class: "db-diff-fold",
+                    },
+                    children: sectionNodes(sec),
+                },
+            ];
+        }
+        return [
+            ...(sec.heading ? [sec.heading] : []),
+            ...sec.blocks,
+            ...sec.children.flatMap(emitSection),
+        ];
+    };
+    const out = [
+        ...root.blocks, // page lead never folds
+        ...root.children.flatMap(emitSection),
+    ];
+    return { tree: out, folded };
+}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@dogsbay/tree-diff",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0-beta.131",
+  "license": "MIT",
+  "description": "diffTrees: identity-driven version diffing over TreeNode — one DiffTree, many views (comparison pages, PR review, version-switcher compare, IDE change review)",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@types/node": "^25.9.5",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10",
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.131"
+  },
+  "dependencies": {
+    "@dogsbay/types": "0.2.0-beta.131"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dogsbay/dogsbay.git",
+    "directory": "packages/tree-diff"
+  },
+  "homepage": "https://github.com/dogsbay/dogsbay/tree/main/packages/tree-diff",
+  "bugs": {
+    "url": "https://github.com/dogsbay/dogsbay/issues"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
 }