openwriter 0.13.0 → 0.15.0

package/dist/server/node-blocks.js

@@ -0,0 +1,274 @@
+/**
+ * TipTap node tree → walker-style block list.
+ *
+ * The matcher and fingerprint operate on a flat ordered block list (one entry
+ * per block, pre-order traversal, with parentPosition pointing back). This
+ * adapter converts the TipTap document tree into that shape so the matcher
+ * operates on the SAME structural view as the editor — not on a separately
+ * re-parsed markdown body.
+ *
+ * Avoiding a second parse is the architectural defense against walker-vs-
+ * parser drift: one block tree feeds both TipTap rendering and node identity
+ * tracking.
+ *
+ * adr: adr/node-identity-matcher.md
+ */
+/**
+ * Flatten a TipTap document tree into a walker-style block list.
+ *
+ * Container blocks (lists, blockquotes, listItems) get an entry AND their
+ * children get separate entries with parentPosition pointing back. Container
+ * text is the first direct paragraph's content only (no recursive roll-up).
+ */
+export function tiptapToBlocks(doc) {
+    const blocks = [];
+    walkNodes(doc.content || [], blocks, null);
+    return blocks;
+}
+const CONTAINER_TYPES = new Set([
+    'bulletList',
+    'orderedList',
+    'taskList',
+    'blockquote',
+    'table',
+    'listItem',
+    'taskItem',
+    'tableRow',
+    'tableCell',
+    'tableHeader',
+]);
+function walkNodes(nodes, blocks, parentPosition) {
+    let ordinalInParent = 0;
+    for (const node of nodes) {
+        if (node.type === 'heading') {
+            const level = node.attrs?.level || 1;
+            const text = extractInlineText(node.content || []);
+            blocks.push({
+                position: blocks.length,
+                type: 'heading',
+                level,
+                text,
+                parentPosition,
+                ordinalInParent: ordinalInParent++,
+                inlineMarks: countInlineMarks(node.content || []),
+                id: node.attrs?.id,
+            });
+        }
+        else if (node.type === 'paragraph') {
+            const text = extractInlineText(node.content || []);
+            blocks.push({
+                position: blocks.length,
+                type: 'paragraph',
+                text,
+                parentPosition,
+                ordinalInParent: ordinalInParent++,
+                inlineMarks: countInlineMarks(node.content || []),
+                id: node.attrs?.id,
+            });
+        }
+        else if (node.type === 'bulletList' || node.type === 'orderedList' || node.type === 'taskList') {
+            const containerPosition = blocks.length;
+            blocks.push({
+                position: containerPosition,
+                type: node.type,
+                text: '',
+                parentPosition,
+                ordinalInParent: ordinalInParent++,
+                id: node.attrs?.id,
+            });
+            walkNodes(node.content || [], blocks, containerPosition);
+        }
+        else if (node.type === 'listItem' || node.type === 'taskItem') {
+            const itemPosition = blocks.length;
+            // listItem's identity text = first direct paragraph child only.
+            // Avoids cascading fingerprint changes when nested children are edited.
+            const firstParaText = firstParagraphText(node.content || []);
+            blocks.push({
+                position: itemPosition,
+                type: node.type,
+                text: firstParaText,
+                parentPosition,
+                ordinalInParent: ordinalInParent++,
+                id: node.attrs?.id,
+            });
+            walkNodes(node.content || [], blocks, itemPosition);
+        }
+        else if (node.type === 'blockquote') {
+            const bqPosition = blocks.length;
+            blocks.push({
+                position: bqPosition,
+                type: 'blockquote',
+                text: '',
+                parentPosition,
+                ordinalInParent: ordinalInParent++,
+                id: node.attrs?.id,
+            });
+            walkNodes(node.content || [], blocks, bqPosition);
+        }
+        else if (node.type === 'codeBlock') {
+            const text = extractInlineText(node.content || []);
+            blocks.push({
+                position: blocks.length,
+                type: 'codeBlock',
+                language: node.attrs?.language || '',
+                text,
+                parentPosition,
+                ordinalInParent: ordinalInParent++,
+                id: node.attrs?.id,
+            });
+        }
+        else if (node.type === 'horizontalRule') {
+            blocks.push({
+                position: blocks.length,
+                type: 'horizontalRule',
+                text: '',
+                parentPosition,
+                ordinalInParent: ordinalInParent++,
+                id: node.attrs?.id,
+            });
+        }
+        else if (node.type === 'table') {
+            const tablePosition = blocks.length;
+            blocks.push({
+                position: tablePosition,
+                type: 'table',
+                text: extractTableText(node),
+                parentPosition,
+                ordinalInParent: ordinalInParent++,
+                id: node.attrs?.id,
+            });
+            // Don't descend into table internals — the walker treats tables as opaque.
+        }
+        else if (node.type === 'image') {
+            blocks.push({
+                position: blocks.length,
+                type: 'image',
+                text: node.attrs?.alt || '',
+                parentPosition,
+                ordinalInParent: ordinalInParent++,
+                id: node.attrs?.id,
+            });
+        }
+        else if (CONTAINER_TYPES.has(node.type)) {
+            // Generic container — emit entry, descend
+            const containerPosition = blocks.length;
+            blocks.push({
+                position: containerPosition,
+                type: node.type,
+                text: '',
+                parentPosition,
+                ordinalInParent: ordinalInParent++,
+                id: node.attrs?.id,
+            });
+            walkNodes(node.content || [], blocks, containerPosition);
+        }
+        else if (node.content) {
+            // Unknown wrapper — descend without emitting
+            walkNodes(node.content, blocks, parentPosition);
+        }
+    }
+}
+/** Get plain text from a node's inline children. */
+function extractInlineText(nodes) {
+    return nodes.map((n) => n.text || '').join('');
+}
+/** Find the first paragraph child (direct or via nested ordering) and return its text. */
+function firstParagraphText(nodes) {
+    for (const n of nodes) {
+        if (n.type === 'paragraph')
+            return extractInlineText(n.content || []);
+    }
+    return '';
+}
+/** Sum inline marks across all inline children. */
+function countInlineMarks(nodes) {
+    let bold = 0, italic = 0, links = 0, code = 0;
+    for (const n of nodes) {
+        if (n.type !== 'text')
+            continue;
+        for (const mark of n.marks || []) {
+            if (mark.type === 'bold')
+                bold++;
+            else if (mark.type === 'italic')
+                italic++;
+            else if (mark.type === 'link')
+                links++;
+            else if (mark.type === 'code')
+                code++;
+        }
+    }
+    return { bold, italic, links, code };
+}
+/** Flatten table cell text — table is treated as an opaque block for fingerprinting. */
+function extractTableText(table) {
+    const parts = [];
+    function walk(nodes) {
+        if (!nodes)
+            return;
+        for (const n of nodes) {
+            if (n.type === 'text')
+                parts.push(n.text || '');
+            else if (n.content)
+                walk(n.content);
+        }
+    }
+    walk(table.content);
+    return parts.join(' ');
+}
+/**
+ * Apply pinned IDs from a matcher result back onto the TipTap node tree.
+ * Walks the tree in the same pre-order the adapter used and assigns
+ * attrs.id from the corresponding pinned entry.
+ */
+export function applyIdsToTiptap(doc, pinnedByPosition) {
+    let position = 0;
+    function walk(nodes) {
+        for (const node of nodes) {
+            const isBlock = node.type === 'heading' ||
+                node.type === 'paragraph' ||
+                node.type === 'bulletList' ||
+                node.type === 'orderedList' ||
+                node.type === 'taskList' ||
+                node.type === 'listItem' ||
+                node.type === 'taskItem' ||
+                node.type === 'blockquote' ||
+                node.type === 'codeBlock' ||
+                node.type === 'horizontalRule' ||
+                node.type === 'table' ||
+                node.type === 'image' ||
+                CONTAINER_TYPES.has(node.type);
+            if (isBlock) {
+                const id = pinnedByPosition.get(position);
+                if (id) {
+                    if (!node.attrs)
+                        node.attrs = {};
+                    node.attrs.id = id;
+                }
+                position++;
+                // Descend into container children, MIRRORING `walkNodes`/`tiptapToBlocks`.
+                // CRITICAL: tables are opaque to the walker (see `tiptapToBlocks` —
+                // emits one Block per table, doesn't descend). `applyIdsToTiptap` MUST
+                // use the same descent rule, otherwise position counters diverge and a
+                // matcher pin meant for a top-level node gets applied to a node inside
+                // a table. That's exactly the table-row-stole-the-paragraph-id
+                // corruption pattern (e.g. `tr:3141ee2a` where 3141ee2a was the
+                // target-total paragraph's ID).
+                //
+                // Descend ONLY into types `walkNodes` recursively descends into.
+                // adr: adr/node-identity-matcher.md
+                const isContainer = node.type === 'bulletList' ||
+                    node.type === 'orderedList' ||
+                    node.type === 'taskList' ||
+                    node.type === 'listItem' ||
+                    node.type === 'taskItem' ||
+                    node.type === 'blockquote';
+                if (isContainer && node.content)
+                    walk(node.content);
+            }
+            else if (node.content) {
+                walk(node.content);
+            }
+        }
+    }
+    walk(doc.content || []);
+}

package/dist/server/node-fingerprint.js

@@ -0,0 +1,264 @@
+/**
+ * Per-block fingerprint computation for node identity tracking.
+ *
+ * The math-first signal hierarchy (push math before words):
+ *
+ *   MATH SIGNALS (exact integers and chars):
+ *     - type, charCount, sentenceCount, wordCount, level, language, structureSig
+ *     - sentences[]: per-sentence tuples {c, f, l, t, wls, w}
+ *         c   = char count (excluding terminator + trailing space)
+ *         f   = first PREFIX_LEN chars of sentence (3-char prefix)
+ *         l   = last PREFIX_LEN chars before terminator (3-char suffix)
+ *         t   = terminator type ('D'|'E'|'Q'|'-')
+ *         wls = word length sequence (array of integers)
+ *         w   = word array — defense-in-depth disambiguator when math collides
+ *
+ *   CONTEXT SIGNALS:
+ *     - prevType, nextType, parentType
+ *
+ *   FALLBACK WORD SIGNALS (only when math is ambiguous):
+ *     - firstWords, lastWords (sequence of strings)
+ *
+ * Two sentences match deterministically if their tuples are equal (math + words).
+ * Two blocks match deterministically if their sentence arrays are equal.
+ * Splits/merges are detected via array prefix/suffix/concatenation of sentence tuples.
+ *
+ * Prefix/suffix length 3 is chosen because:
+ *   - 1 char (single first/last) collided too easily — "Bee ate the deck" vs
+ *     "Bug ate the desk" hashed identically.
+ *   - 3 chars captures the first/last whole short word in most sentences and
+ *     reduces realistic collisions to near zero.
+ *   - Longer prefixes (5+) approach "encoding the first word" rather than
+ *     a math signal; we get diminishing returns past 3.
+ *
+ * adr: adr/node-identity-matcher.md
+ */
+const WORD_FALLBACK_WINDOW = 5;
+const PREFIX_LEN = 3;
+const CONTAINER_TYPES = new Set([
+    'bulletList',
+    'orderedList',
+    'taskList',
+    'blockquote',
+    'table',
+    'listItem',
+    'taskItem',
+]);
+/** Compute a fingerprint for a single block, given its position in the block list. */
+export function fingerprint(block, allBlocks) {
+    const text = block.text || '';
+    const sentences = splitSentences(text);
+    const words = tokenizeWords(text);
+    const fp = {
+        type: block.type,
+        position: block.position,
+        parentPosition: block.parentPosition,
+        ordinalInParent: block.ordinalInParent,
+        charCount: text.length,
+        sentenceCount: sentences.length,
+        wordCount: words.length,
+        sentences: sentences.map(sentenceTuple),
+        structureSig: block.inlineMarks || { bold: 0, italic: 0, links: 0, code: 0 },
+        prevType: allBlocks[block.position - 1]?.type || null,
+        nextType: allBlocks[block.position + 1]?.type || null,
+        parentType: block.parentPosition != null ? allBlocks[block.parentPosition]?.type ?? null : null,
+        firstWords: words.slice(0, WORD_FALLBACK_WINDOW),
+        lastWords: words.slice(-WORD_FALLBACK_WINDOW),
+    };
+    if (block.type === 'heading')
+        fp.level = block.level;
+    if (block.type === 'codeBlock') {
+        fp.language = block.language || '';
+        fp.contentHash = simpleHash(block.text);
+    }
+    if (CONTAINER_TYPES.has(block.type)) {
+        const children = allBlocks.filter((b) => b.parentPosition === block.position);
+        fp.childCount = children.length;
+        fp.childTypes = children.map((c) => c.type);
+    }
+    return fp;
+}
+/**
+ * Build the per-sentence tuple. Math fields (c, f, l, t, wls) form the primary
+ * fingerprint. Prefix/suffix `f` and `l` are PREFIX_LEN chars each. Words (`w`)
+ * are defense-in-depth for the rare case where math still collides under
+ * richer prefixes.
+ */
+function sentenceTuple(sentence) {
+    const t = sentence.text;
+    const words = tokenizeWords(t);
+    return {
+        c: t.length,
+        f: t.slice(0, PREFIX_LEN),
+        l: t.slice(-PREFIX_LEN),
+        t: sentence.terminator,
+        wls: words.map((w) => w.length),
+        w: words,
+    };
+}
+export function fingerprintAll(blocks) {
+    return blocks.map((b) => fingerprint(b, blocks));
+}
+/**
+ * Split text into sentences. Each sentence carries its terminator type:
+ *   'D' = declarative (.)
+ *   'E' = exclamation (!)
+ *   'Q' = question (?)
+ *   '-' = no terminator (last fragment with no punctuation)
+ */
+export function splitSentences(text) {
+    if (!text)
+        return [];
+    const sentences = [];
+    const re = /([^.!?]+?)([.!?]+)(\s+|$)/g;
+    let lastIdx = 0;
+    let m;
+    while ((m = re.exec(text)) !== null) {
+        const sentenceText = m[1].trim();
+        const term = m[2][0];
+        const terminator = term === '.' ? 'D' : term === '!' ? 'E' : term === '?' ? 'Q' : '-';
+        sentences.push({ text: sentenceText, terminator });
+        lastIdx = re.lastIndex;
+    }
+    if (lastIdx < text.length) {
+        const remaining = text.slice(lastIdx).trim();
+        if (remaining)
+            sentences.push({ text: remaining, terminator: '-' });
+    }
+    return sentences;
+}
+export function tokenizeWords(text) {
+    if (!text)
+        return [];
+    return text
+        .split(/\s+/)
+        .map((w) => w.replace(/^[^\w]+|[^\w]+$/g, ''))
+        .filter((w) => w.length > 0);
+}
+export function simpleHash(s) {
+    let h = 0;
+    for (let i = 0; i < s.length; i++) {
+        h = ((h << 5) - h) + s.charCodeAt(i);
+        h |= 0;
+    }
+    return h.toString(16);
+}
+/**
+ * The strongest possible match: every math dimension equal AND word arrays
+ * equal. Pure determinism — adversaries cannot fake exact match without
+ * literally using the same content.
+ */
+export function isExactMatch(a, b) {
+    if (a.type !== b.type)
+        return false;
+    if (a.level !== b.level)
+        return false;
+    if (a.language !== b.language)
+        return false;
+    if (a.charCount !== b.charCount)
+        return false;
+    if (a.sentenceCount !== b.sentenceCount)
+        return false;
+    if (a.wordCount !== b.wordCount)
+        return false;
+    if (!sentenceArraysEqual(a.sentences, b.sentences))
+        return false;
+    if (!structureEqual(a.structureSig, b.structureSig))
+        return false;
+    if (a.childCount != null || b.childCount != null) {
+        if (a.childCount !== b.childCount)
+            return false;
+        if (!arraysEqual(a.childTypes, b.childTypes))
+            return false;
+    }
+    return true;
+}
+/** Identical content but possibly different types — used by type-change rule. */
+export function isSameContent(a, b) {
+    const aIsContainer = a.childCount != null;
+    const bIsContainer = b.childCount != null;
+    if (aIsContainer !== bIsContainer)
+        return false;
+    if (aIsContainer) {
+        return a.childCount === b.childCount && arraysEqual(a.childTypes, b.childTypes);
+    }
+    if (a.sentences != null && b.sentences != null) {
+        if (!sentenceArraysEqual(a.sentences, b.sentences))
+            return false;
+        return structureEqual(a.structureSig, b.structureSig);
+    }
+    return false;
+}
+export function sentenceArraysEqual(a, b) {
+    if (!Array.isArray(a) || !Array.isArray(b))
+        return false;
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (!sentenceTuplesEqual(a[i], b[i]))
+            return false;
+    }
+    return true;
+}
+/** Math + words full equality. The disambiguator for math collisions. */
+export function sentenceTuplesEqual(a, b) {
+    return (a.c === b.c &&
+        a.f === b.f &&
+        a.l === b.l &&
+        a.t === b.t &&
+        arraysEqual(a.wls, b.wls) &&
+        arraysEqual(a.w, b.w));
+}
+export function isSentencePrefix(short, long) {
+    if (!Array.isArray(short) || !Array.isArray(long))
+        return false;
+    if (short.length === 0 || short.length > long.length)
+        return false;
+    for (let i = 0; i < short.length; i++) {
+        if (!sentenceTuplesEqual(short[i], long[i]))
+            return false;
+    }
+    return true;
+}
+export function isSentenceSuffix(short, long) {
+    if (!Array.isArray(short) || !Array.isArray(long))
+        return false;
+    if (short.length === 0 || short.length > long.length)
+        return false;
+    const offset = long.length - short.length;
+    for (let i = 0; i < short.length; i++) {
+        if (!sentenceTuplesEqual(short[i], long[i + offset]))
+            return false;
+    }
+    return true;
+}
+export function isSentenceConcat(combined, first, second) {
+    if (!Array.isArray(combined) || !Array.isArray(first) || !Array.isArray(second))
+        return false;
+    if (combined.length !== first.length + second.length)
+        return false;
+    for (let i = 0; i < first.length; i++) {
+        if (!sentenceTuplesEqual(combined[i], first[i]))
+            return false;
+    }
+    for (let i = 0; i < second.length; i++) {
+        if (!sentenceTuplesEqual(combined[first.length + i], second[i]))
+            return false;
+    }
+    return true;
+}
+function arraysEqual(a, b) {
+    if (!Array.isArray(a) || !Array.isArray(b))
+        return false;
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+function structureEqual(a, b) {
+    if (!a || !b)
+        return false;
+    return a.bold === b.bold && a.italic === b.italic && a.links === b.links && a.code === b.code;
+}