@usejunior/odf-core 0.9.1

package/dist/compare/inline_diff.js

@@ -0,0 +1,102 @@
+/**
+ * Pure intra-paragraph diff for ODF comparison (issue #356).
+ *
+ * Token-level LCS over a single paragraph pair's visible text, returning char-offset spans.
+ * Tokens are maximal runs of whitespace or non-whitespace — a partition of the string — so
+ * every token boundary maps losslessly back to a character offset and the emitted spans land
+ * on clean word boundaries (no ragged mid-word matches). Common token prefix/suffix are
+ * trimmed before the O(N·M) DP, so the dominant case — one edited word in a long clause —
+ * costs close to the edit size, not the paragraph size.
+ *
+ * Order convention mirrors `diffParagraphs`: at a mismatch the deletion branch wins, so a
+ * replaced word surfaces as a `delete` immediately followed by an `insert` sharing `revStart`.
+ * The emitter relies on that ordering when both anchor at the same offset.
+ */
+/** Split into maximal whitespace / non-whitespace runs (a partition: tokens concat to the input). */
+function tokenizeRuns(text) {
+    return text.match(/\s+|\S+/g) ?? [];
+}
+/**
+ * Diff two visible-text strings into an ordered span script.
+ * Adjacent same-kind spans are coalesced; zero-length spans are never emitted.
+ */
+export function diffInline(original, revised) {
+    const origTokens = tokenizeRuns(original);
+    const revTokens = tokenizeRuns(revised);
+    // Trim the common token prefix/suffix; the DP only sees the differing middle window.
+    let prefix = 0;
+    const maxPrefix = Math.min(origTokens.length, revTokens.length);
+    while (prefix < maxPrefix && origTokens[prefix] === revTokens[prefix])
+        prefix++;
+    let suffix = 0;
+    const maxSuffix = Math.min(origTokens.length, revTokens.length) - prefix;
+    while (suffix < maxSuffix &&
+        origTokens[origTokens.length - 1 - suffix] === revTokens[revTokens.length - 1 - suffix]) {
+        suffix++;
+    }
+    const midOrig = origTokens.slice(prefix, origTokens.length - suffix);
+    const midRev = revTokens.slice(prefix, revTokens.length - suffix);
+    // dp[i][j] = LCS length of midOrig[i..] and midRev[j..] (same shape as diffParagraphs).
+    const n = midOrig.length;
+    const m = midRev.length;
+    const dp = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+    for (let i = n - 1; i >= 0; i--) {
+        for (let j = m - 1; j >= 0; j--) {
+            dp[i][j] =
+                midOrig[i] === midRev[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
+        }
+    }
+    // Walk tokens emitting per-token kinds, tracking char cursors in both strings.
+    const ops = [];
+    let origPos = 0;
+    let revPos = 0;
+    const push = (kind, origLen, revLen) => {
+        if (origLen === 0 && revLen === 0)
+            return;
+        const last = ops[ops.length - 1];
+        if (last && last.kind === kind) {
+            last.origEnd += origLen;
+            last.revEnd += revLen;
+        }
+        else {
+            ops.push({
+                kind,
+                origStart: origPos,
+                origEnd: origPos + origLen,
+                revStart: revPos,
+                revEnd: revPos + revLen,
+            });
+        }
+        origPos += origLen;
+        revPos += revLen;
+    };
+    for (let k = 0; k < prefix; k++)
+        push('equal', origTokens[k].length, revTokens[k].length);
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (midOrig[i] === midRev[j]) {
+            push('equal', midOrig[i].length, midRev[j].length);
+            i++;
+            j++;
+        }
+        else if (dp[i + 1][j] >= dp[i][j + 1]) {
+            // Prefer deletion at a tie so a replaced word surfaces as delete-then-insert.
+            push('delete', midOrig[i].length, 0);
+            i++;
+        }
+        else {
+            push('insert', 0, midRev[j].length);
+            j++;
+        }
+    }
+    while (i < n)
+        push('delete', midOrig[i++].length, 0);
+    while (j < m)
+        push('insert', 0, midRev[j++].length);
+    for (let k = suffix; k > 0; k--) {
+        push('equal', origTokens[origTokens.length - k].length, revTokens[revTokens.length - k].length);
+    }
+    return ops;
+}
+//# sourceMappingURL=inline_diff.js.map

package/dist/compare/inline_diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inline_diff.js","sourceRoot":"","sources":["../../src/compare/inline_diff.ts"],"names":[],"mappings":"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"}

package/dist/compare/inline_map.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Visible-offset → DOM mapping for the intra-paragraph compare emitter (issue #356).
+ *
+ * `resolveOffset` turns a visible-text offset in a block into a concrete DOM insertion point,
+ * splitting a `#text` node or a `text:s` run when the offset falls strictly inside one.
+ * `extractVisibleRange` clones a visible range's inline content (preserving `text:span` /
+ * hyperlink structure) for out-of-line storage in a `text:deletion` changed-region.
+ *
+ * Contract for callers that mutate: `resolveOffset` re-segments the block on every call and
+ * never trusts a previously computed `Segment[]`. Marker insertion (zero visible width) at an
+ * offset never changes the visible offsets BELOW it, so emitters processing offsets in
+ * DESCENDING order stay correct across splits. `#text` splits are done manually (truncate
+ * `.data` + insert a sibling) — `Text.splitText` is not assumed to exist in xmldom.
+ */
+/** A visible offset could not be mapped onto the block's DOM. The emitter degrades the pair. */
+export declare class OdfMapError extends Error {
+}
+/** A DOM insertion point: `parent.insertBefore(node, before)`. */
+export type DomPoint = {
+    parent: Node;
+    before: Node | null;
+};
+/**
+ * Resolve visible offset `vis` in `block` to a DOM insertion point at the offset's natural
+ * nesting depth (inside a `text:span` when the offset is inside one — the LibreOffice-authored
+ * placement). Offsets 0 and `visible.length` resolve to block-level prepend/append. An offset
+ * strictly inside a `#text` node splits it; strictly inside a `text:s` run splits the run,
+ * rebalancing `text:c`. Throws `OdfMapError` when `vis` is out of range.
+ */
+export declare function resolveOffset(block: Element, vis: number): DomPoint;
+/**
+ * Clone the inline content of `block`'s visible range [start, end) as nodes owned by
+ * `targetDoc`, for storage inside a `text:deletion` changed-region. Ancestor inline elements
+ * (`text:span`, hyperlinks) of covered content are shallow-cloned with their attributes;
+ * `#text` is trimmed at the edges; a partially covered `text:s` is rebalanced to the covered
+ * count; `text:tab` / `text:line-break` are copied whole (length 1 — never split). Pure with
+ * respect to `block`. Throws `OdfMapError` on an empty or out-of-range span.
+ */
+export declare function extractVisibleRange(block: Element, start: number, end: number, targetDoc: Document): Node[];
+//# sourceMappingURL=inline_map.d.ts.map

package/dist/compare/inline_map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inline_map.d.ts","sourceRoot":"","sources":["../../src/compare/inline_map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAWH,gGAAgG;AAChG,qBAAa,WAAY,SAAQ,KAAK;CAAG;AAEzC,kEAAkE;AAClE,MAAM,MAAM,QAAQ,GAAG;IAAE,MAAM,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,IAAI,GAAG,IAAI,CAAA;CAAE,CAAC;AAkB7D;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,QAAQ,CA8CnE;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,GAAG,IAAI,EAAE,CAkD3G"}

package/dist/compare/inline_map.js

@@ -0,0 +1,153 @@
+/**
+ * Visible-offset → DOM mapping for the intra-paragraph compare emitter (issue #356).
+ *
+ * `resolveOffset` turns a visible-text offset in a block into a concrete DOM insertion point,
+ * splitting a `#text` node or a `text:s` run when the offset falls strictly inside one.
+ * `extractVisibleRange` clones a visible range's inline content (preserving `text:span` /
+ * hyperlink structure) for out-of-line storage in a `text:deletion` changed-region.
+ *
+ * Contract for callers that mutate: `resolveOffset` re-segments the block on every call and
+ * never trusts a previously computed `Segment[]`. Marker insertion (zero visible width) at an
+ * offset never changes the visible offsets BELOW it, so emitters processing offsets in
+ * DESCENDING order stay correct across splits. `#text` splits are done manually (truncate
+ * `.data` + insert a sibling) — `Text.splitText` is not assumed to exist in xmldom.
+ */
+import { ODF_NS } from '../shared/odf/namespaces.js';
+import { ELEMENT_NODE, TEXT_NODE, buildSegments, isAnnotationSubtree, isTrackedChangesSubtree, } from '../shared/odf/text_segments.js';
+/** A visible offset could not be mapped onto the block's DOM. The emitter degrades the pair. */
+export class OdfMapError extends Error {
+}
+/** Read a `text:s` run length the way `buildSegments` does. */
+function spaceCount(el) {
+    const countRaw = el.getAttributeNS(ODF_NS.TEXT, 'c') ?? el.getAttribute('text:c');
+    return Math.max(1, Number.parseInt(countRaw ?? '1', 10) || 1);
+}
+/** Set a `text:s` run length, omitting the attribute for the default count of 1. */
+function setSpaceCount(el, count) {
+    if (count === 1) {
+        el.removeAttributeNS(ODF_NS.TEXT, 'c');
+        el.removeAttribute('text:c');
+    }
+    else {
+        el.setAttributeNS(ODF_NS.TEXT, 'text:c', String(count));
+    }
+}
+/**
+ * Resolve visible offset `vis` in `block` to a DOM insertion point at the offset's natural
+ * nesting depth (inside a `text:span` when the offset is inside one — the LibreOffice-authored
+ * placement). Offsets 0 and `visible.length` resolve to block-level prepend/append. An offset
+ * strictly inside a `#text` node splits it; strictly inside a `text:s` run splits the run,
+ * rebalancing `text:c`. Throws `OdfMapError` when `vis` is out of range.
+ */
+export function resolveOffset(block, vis) {
+    const { segments, visible } = buildSegments(block);
+    if (vis < 0 || vis > visible.length) {
+        throw new OdfMapError(`offset ${vis} outside visible range 0..${visible.length}`);
+    }
+    if (vis === 0)
+        return { parent: block, before: block.firstChild };
+    if (vis === visible.length)
+        return { parent: block, before: null };
+    // A boundary between segments: insert before the segment that starts at `vis`, at its depth.
+    const startingHere = segments.find((s) => s.visStart === vis);
+    if (startingHere) {
+        const host = startingHere.kind === 'text' ? startingHere.node : startingHere.node;
+        const parent = host.parentNode;
+        if (!parent)
+            throw new OdfMapError(`segment host at offset ${vis} has no parent`);
+        return { parent, before: host };
+    }
+    const seg = segments.find((s) => s.visStart < vis && vis < s.visStart + s.length);
+    if (!seg)
+        throw new OdfMapError(`offset ${vis} maps to no segment`);
+    const off = vis - seg.visStart;
+    if (seg.kind === 'text') {
+        const textNode = seg.node;
+        const parent = textNode.parentNode;
+        const doc = textNode.ownerDocument;
+        if (!parent || !doc)
+            throw new OdfMapError(`text node at offset ${vis} is detached`);
+        const tail = doc.createTextNode(textNode.data.slice(off));
+        textNode.data = textNode.data.slice(0, off);
+        parent.insertBefore(tail, textNode.nextSibling);
+        return { parent, before: tail };
+    }
+    if (seg.virtual === 'space') {
+        const run = seg.node;
+        const parent = run.parentNode;
+        const doc = run.ownerDocument;
+        if (!parent || !doc)
+            throw new OdfMapError(`text:s at offset ${vis} is detached`);
+        const tail = doc.importNode(run, false);
+        setSpaceCount(run, off);
+        setSpaceCount(tail, seg.length - off);
+        parent.insertBefore(tail, run.nextSibling);
+        return { parent, before: tail };
+    }
+    // tab / line-break are length 1 — an offset strictly inside one cannot exist.
+    throw new OdfMapError(`offset ${vis} falls inside an atomic ${seg.virtual} element`);
+}
+/**
+ * Clone the inline content of `block`'s visible range [start, end) as nodes owned by
+ * `targetDoc`, for storage inside a `text:deletion` changed-region. Ancestor inline elements
+ * (`text:span`, hyperlinks) of covered content are shallow-cloned with their attributes;
+ * `#text` is trimmed at the edges; a partially covered `text:s` is rebalanced to the covered
+ * count; `text:tab` / `text:line-break` are copied whole (length 1 — never split). Pure with
+ * respect to `block`. Throws `OdfMapError` on an empty or out-of-range span.
+ */
+export function extractVisibleRange(block, start, end, targetDoc) {
+    const { visible } = buildSegments(block);
+    if (!(start >= 0 && start < end && end <= visible.length)) {
+        throw new OdfMapError(`range [${start}, ${end}) invalid for visible length ${visible.length}`);
+    }
+    let pos = 0;
+    const out = [];
+    const walk = (node, sink) => {
+        for (let child = node.firstChild; child; child = child.nextSibling) {
+            if (child.nodeType === TEXT_NODE) {
+                const data = child.data ?? '';
+                const from = Math.max(start, pos);
+                const to = Math.min(end, pos + data.length);
+                if (to > from)
+                    sink.push(targetDoc.createTextNode(data.slice(from - pos, to - pos)));
+                pos += data.length;
+                continue;
+            }
+            if (child.nodeType !== ELEMENT_NODE)
+                continue;
+            const el = child;
+            if (isAnnotationSubtree(el) || isTrackedChangesSubtree(el))
+                continue;
+            if (el.namespaceURI === ODF_NS.TEXT && el.localName === 's') {
+                const count = spaceCount(el);
+                const covered = Math.min(end, pos + count) - Math.max(start, pos);
+                if (covered > 0) {
+                    const clone = targetDoc.importNode(el, false);
+                    setSpaceCount(clone, covered);
+                    sink.push(clone);
+                }
+                pos += count;
+                continue;
+            }
+            if (el.namespaceURI === ODF_NS.TEXT && (el.localName === 'tab' || el.localName === 'line-break')) {
+                if (start <= pos && pos < end)
+                    sink.push(targetDoc.importNode(el, false));
+                pos += 1;
+                continue;
+            }
+            // Container element (text:span, text:a, …): recurse; shallow-clone it only when it
+            // actually contributes covered content, so uncovered formatting never leaks into storage.
+            const sub = [];
+            walk(el, sub);
+            if (sub.length > 0) {
+                const clone = targetDoc.importNode(el, false);
+                for (const n of sub)
+                    clone.appendChild(n);
+                sink.push(clone);
+            }
+        }
+    };
+    walk(block, out);
+    return out;
+}
+//# sourceMappingURL=inline_map.js.map

package/dist/compare/inline_map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inline_map.js","sourceRoot":"","sources":["../../src/compare/inline_map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AACrD,OAAO,EACL,YAAY,EACZ,SAAS,EACT,aAAa,EACb,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,gCAAgC,CAAC;AAExC,gGAAgG;AAChG,MAAM,OAAO,WAAY,SAAQ,KAAK;CAAG;AAKzC,+DAA+D;AAC/D,SAAS,UAAU,CAAC,EAAW;IAC7B,MAAM,QAAQ,GAAG,EAAE,CAAC,cAAc,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;IAClF,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,QAAQ,IAAI,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;AAChE,CAAC;AAED,oFAAoF;AACpF,SAAS,aAAa,CAAC,EAAW,EAAE,KAAa;IAC/C,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;QAChB,EAAE,CAAC,iBAAiB,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACvC,EAAE,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC;IAC/B,CAAC;SAAM,CAAC;QACN,EAAE,CAAC,cAAc,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAC1D,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc,EAAE,GAAW;IACvD,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IACnD,IAAI,GAAG,GAAG,CAAC,IAAI,GAAG,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;QACpC,MAAM,IAAI,WAAW,CAAC,UAAU,GAAG,6BAA6B,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACpF,CAAC;IACD,IAAI,GAAG,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC;IAClE,IAAI,GAAG,KAAK,OAAO,CAAC,MAAM;QAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAEnE,6FAA6F;IAC7F,MAAM,YAAY,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,GAAG,CAAC,CAAC;IAC9D,IAAI,YAAY,EAAE,CAAC;QACjB,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAE,YAAY,CAAC,IAAwB,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC;QACvG,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC;QAC/B,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,WAAW,CAAC,0BAA0B,GAAG,gBAAgB,CAAC,CAAC;QAClF,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAClC,CAAC;IAED,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,GAAG,IAAI,GAAG,GAAG,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC;IAClF,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,WAAW,CAAC,UAAU,GAAG,qBAAqB,CAAC,CAAC;IACpE,MAAM,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC,QAAQ,CAAC;IAE/B,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QACxB,MAAM,QAAQ,GAAG,GAAG,CAAC,IAA0C,CAAC;QAChE,MAAM,MAAM,GAAG,QAAQ,CAAC,UAAU,CAAC;QACnC,MAAM,GAAG,GAAI,QAAiB,CAAC,aAAa,CAAC;QAC7C,IAAI,CAAC,MAAM,IAAI,CAAC,GAAG;YAAE,MAAM,IAAI,WAAW,CAAC,uBAAuB,GAAG,cAAc,CAAC,CAAC;QACrF,MAAM,IAAI,GAAG,GAAG,CAAC,cAAc,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QAC1D,QAAQ,CAAC,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QAC5C,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;QAChD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAClC,CAAC;IAED,IAAI,GAAG,CAAC,OAAO,KAAK,OAAO,EAAE,CAAC;QAC5B,MAAM,GAAG,GAAG,GAAG,CAAC,IAAI,CAAC;QACrB,MAAM,MAAM,GAAG,GAAG,CAAC,UAAU,CAAC;QAC9B,MAAM,GAAG,GAAG,GAAG,CAAC,aAAa,CAAC;QAC9B,IAAI,CAAC,MAAM,IAAI,CAAC,GAAG;YAAE,MAAM,IAAI,WAAW,CAAC,oBAAoB,GAAG,cAAc,CAAC,CAAC;QAClF,MAAM,IAAI,GAAG,GAAG,CAAC,UAAU,CAAC,GAAG,EAAE,KAAK,CAAY,CAAC;QACnD,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACxB,aAAa,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC;QACtC,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,GAAG,CAAC,WAAW,CAAC,CAAC;QAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAClC,CAAC;IAED,8EAA8E;IAC9E,MAAM,IAAI,WAAW,CAAC,UAAU,GAAG,2BAA2B,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC;AACvF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAc,EAAE,KAAa,EAAE,GAAW,EAAE,SAAmB;IACjG,MAAM,EAAE,OAAO,EAAE,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IACzC,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,IAAI,KAAK,GAAG,GAAG,IAAI,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1D,MAAM,IAAI,WAAW,CAAC,UAAU,KAAK,KAAK,GAAG,gCAAgC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACjG,CAAC;IAED,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,MAAM,GAAG,GAAW,EAAE,CAAC;IACvB,MAAM,IAAI,GAAG,CAAC,IAAU,EAAE,IAAY,EAAQ,EAAE;QAC9C,KAAK,IAAI,KAAK,GAAG,IAAI,CAAC,UAAU,EAAE,KAAK,EAAE,KAAK,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;YACnE,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;gBACjC,MAAM,IAAI,GAAI,KAAqC,CAAC,IAAI,IAAI,EAAE,CAAC;gBAC/D,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;gBAClC,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;gBAC5C,IAAI,EAAE,GAAG,IAAI;oBAAE,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,GAAG,EAAE,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;gBACrF,GAAG,IAAI,IAAI,CAAC,MAAM,CAAC;gBACnB,SAAS;YACX,CAAC;YACD,IAAI,KAAK,CAAC,QAAQ,KAAK,YAAY;gBAAE,SAAS;YAC9C,MAAM,EAAE,GAAG,KAAgB,CAAC;YAC5B,IAAI,mBAAmB,CAAC,EAAE,CAAC,IAAI,uBAAuB,CAAC,EAAE,CAAC;gBAAE,SAAS;YACrE,IAAI,EAAE,CAAC,YAAY,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC,SAAS,KAAK,GAAG,EAAE,CAAC;gBAC5D,MAAM,KAAK,GAAG,UAAU,CAAC,EAAE,CAAC,CAAC;gBAC7B,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,GAAG,KAAK,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;gBAClE,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;oBAChB,MAAM,KAAK,GAAG,SAAS,CAAC,UAAU,CAAC,EAAE,EAAE,KAAK,CAAY,CAAC;oBACzD,aAAa,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;oBAC9B,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;gBACnB,CAAC;gBACD,GAAG,IAAI,KAAK,CAAC;gBACb,SAAS;YACX,CAAC;YACD,IAAI,EAAE,CAAC,YAAY,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,EAAE,CAAC,SAAS,KAAK,KAAK,IAAI,EAAE,CAAC,SAAS,KAAK,YAAY,CAAC,EAAE,CAAC;gBACjG,IAAI,KAAK,IAAI,GAAG,IAAI,GAAG,GAAG,GAAG;oBAAE,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC;gBAC1E,GAAG,IAAI,CAAC,CAAC;gBACT,SAAS;YACX,CAAC;YACD,mFAAmF;YACnF,0FAA0F;YAC1F,MAAM,GAAG,GAAW,EAAE,CAAC;YACvB,IAAI,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;YACd,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACnB,MAAM,KAAK,GAAG,SAAS,CAAC,UAAU,CAAC,EAAE,EAAE,KAAK,CAAY,CAAC;gBACzD,KAAK,MAAM,CAAC,IAAI,GAAG;oBAAE,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;gBAC1C,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACnB,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IACF,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACjB,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/document.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Minimal ODF (.odt) document view over `content.xml`.
+ *
+ * Phase 1 scope: enumerate block-level text elements (`text:p` / `text:h`) in
+ * document order — including those nested in `table:table-cell` — with deterministic
+ * structural paragraph IDs, read a paragraph's visible text, and replace text within
+ * a paragraph when the match lies in a single `#text` node. See the `add-odf-core`
+ * OpenSpec change for the full rationale.
+ *
+ * Namespaces: ODF is heavily namespaced and prefixes are not guaranteed, so all
+ * element matching is by `namespaceURI` + `localName`, never by prefixed tag name.
+ */
+import { type OdfComment } from './comments.js';
+export type OdfParagraph = {
+    /** Deterministic structural ID (document-order ordinal), stable for identical bytes. */
+    id: string;
+    /** Visible text with `text:s` expanded to spaces and `text:tab` to a tab. */
+    text: string;
+};
+export type ReplaceResult = {
+    ok: true;
+} | {
+    ok: false;
+    code: 'ANCHOR_NOT_FOUND' | 'TEXT_NOT_FOUND' | 'MATCH_SPANS_MULTIPLE_NODES';
+    message: string;
+};
+export type InsertResult = {
+    ok: true;
+    newIds: string[];
+} | {
+    ok: false;
+    code: 'ANCHOR_NOT_FOUND';
+    message: string;
+};
+/** Parameters for {@link OdfDocument.addComment}. A `start`/`end` range is optional; omit for whole-paragraph. */
+export type AddCommentParams = {
+    paragraphId: string;
+    start?: number;
+    end?: number;
+    author: string;
+    text: string;
+    initials?: string;
+};
+export type AddCommentResult = {
+    ok: true;
+    commentId: number;
+} | {
+    ok: false;
+    code: 'ANCHOR_NOT_FOUND' | 'MATCH_SPANS_MULTIPLE_NODES' | 'INVALID_RANGE';
+    message: string;
+};
+export declare class OdfDocument {
+    private doc;
+    /** Block-level text elements in document order; index is the structural ID ordinal. */
+    private blocks;
+    private constructor();
+    /** Parse a `content.xml` string into a document view. */
+    static fromContentXml(contentXml: string): OdfDocument;
+    private idForIndex;
+    private blockForId;
+    /** All paragraphs in document order. */
+    getParagraphs(): OdfParagraph[];
+    /** Visible text of a paragraph by ID, or null if the ID does not resolve. */
+    getParagraphTextById(id: string): string | null;
+    /**
+     * Replace `findText` with `replaceWith` in the paragraph identified by `id`.
+     * Phase 1 only edits when the match lies entirely within a single `#text` node.
+     */
+    replaceTextById(id: string, findText: string, replaceWith: string): ReplaceResult;
+    /**
+     * Insert one or more paragraphs relative to the anchor paragraph identified by `id`.
+     *
+     * `text` is split on blank lines (`\n{2,}`) into separate `text:p` blocks (parity with
+     * the DOCX `insert_paragraph` tool); a single `\n` within a block becomes a
+     * `text:line-break`. Inserted blocks inherit the anchor's `text:style-name` ONLY when
+     * the anchor is itself a `text:p` — inserting after a heading (`text:h`) produces
+     * default body paragraphs, never more headings.
+     *
+     * Paragraph IDs are positional ordinals, so every ID at or after the insertion point
+     * shifts by the number of inserted blocks. Returns the inserted blocks' freshly
+     * recomputed IDs in document order; callers must re-read before issuing further edits
+     * that target IDs near or after the insertion point.
+     */
+    insertParagraph(id: string, text: string, position: 'BEFORE' | 'AFTER'): InsertResult;
+    /**
+     * Insert an `office:annotation` comment on the paragraph identified by `paragraphId`.
+     * Omit `start`/`end` to bracket the whole paragraph (structural insertion, independent of
+     * text segmentation); supply a visible `start`/`end` range to bracket a substring (which must
+     * lie within a single `#text` node, else `MATCH_SPANS_MULTIPLE_NODES`). Annotations are inline
+     * children, so positional paragraph IDs do NOT shift.
+     */
+    addComment(params: AddCommentParams): AddCommentResult;
+    /** All `office:annotation` comments in document order. */
+    getComments(): OdfComment[];
+    /** Serialize the (possibly edited) document back to a `content.xml` string. */
+    toXml(): string;
+}
+//# sourceMappingURL=document.d.ts.map

package/dist/document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../src/document.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,OAAO,EAA4D,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAE1G,MAAM,MAAM,YAAY,GAAG;IACzB,wFAAwF;IACxF,EAAE,EAAE,MAAM,CAAC;IACX,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,aAAa,GACrB;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACZ;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,kBAAkB,GAAG,gBAAgB,GAAG,4BAA4B,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/G,MAAM,MAAM,YAAY,GACpB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,GAC9B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,kBAAkB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7D,kHAAkH;AAClH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GACxB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,kBAAkB,GAAG,4BAA4B,GAAG,eAAe,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9G,qBAAa,WAAW;IACtB,OAAO,CAAC,GAAG,CAAW;IACtB,uFAAuF;IACvF,OAAO,CAAC,MAAM,CAAY;IAE1B,OAAO;IAKP,yDAAyD;IACzD,MAAM,CAAC,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,WAAW;IAOtD,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,UAAU;IAOlB,wCAAwC;IACxC,aAAa,IAAI,YAAY,EAAE;IAO/B,6EAA6E;IAC7E,oBAAoB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAM/C;;;OAGG;IACH,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,aAAa;IA+BjF;;;;;;;;;;;;;OAaG;IACH,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,GAAG,YAAY;IA4CrF;;;;;;OAMG;IACH,UAAU,CAAC,MAAM,EAAE,gBAAgB,GAAG,gBAAgB;IAgBtD,0DAA0D;IAC1D,WAAW,IAAI,UAAU,EAAE;IAI3B,+EAA+E;IAC/E,KAAK,IAAI,MAAM;CAGhB"}

package/dist/document.js

@@ -0,0 +1,172 @@
+/**
+ * Minimal ODF (.odt) document view over `content.xml`.
+ *
+ * Phase 1 scope: enumerate block-level text elements (`text:p` / `text:h`) in
+ * document order — including those nested in `table:table-cell` — with deterministic
+ * structural paragraph IDs, read a paragraph's visible text, and replace text within
+ * a paragraph when the match lies in a single `#text` node. See the `add-odf-core`
+ * OpenSpec change for the full rationale.
+ *
+ * Namespaces: ODF is heavily namespaced and prefixes are not guaranteed, so all
+ * element matching is by `namespaceURI` + `localName`, never by prefixed tag name.
+ */
+import { parseXml, serializeXml } from '@usejunior/docx-core';
+import { ODF_NS } from './shared/odf/namespaces.js';
+import { buildSegments } from './shared/odf/text_segments.js';
+import { collectBlocks } from './shared/odf/blocks.js';
+import { addAnnotation, readAnnotations } from './comments.js';
+export class OdfDocument {
+    doc;
+    /** Block-level text elements in document order; index is the structural ID ordinal. */
+    blocks;
+    constructor(doc, blocks) {
+        this.doc = doc;
+        this.blocks = blocks;
+    }
+    /** Parse a `content.xml` string into a document view. */
+    static fromContentXml(contentXml) {
+        const doc = parseXml(contentXml);
+        const blocks = [];
+        collectBlocks(doc.documentElement, blocks);
+        return new OdfDocument(doc, blocks);
+    }
+    idForIndex(index) {
+        return `p${index}`;
+    }
+    blockForId(id) {
+        const m = /^p(\d+)$/.exec(id);
+        if (!m)
+            return null;
+        const idx = Number.parseInt(m[1], 10);
+        return this.blocks[idx] ?? null;
+    }
+    /** All paragraphs in document order. */
+    getParagraphs() {
+        return this.blocks.map((el, i) => ({
+            id: this.idForIndex(i),
+            text: buildSegments(el).visible,
+        }));
+    }
+    /** Visible text of a paragraph by ID, or null if the ID does not resolve. */
+    getParagraphTextById(id) {
+        const el = this.blockForId(id);
+        if (!el)
+            return null;
+        return buildSegments(el).visible;
+    }
+    /**
+     * Replace `findText` with `replaceWith` in the paragraph identified by `id`.
+     * Phase 1 only edits when the match lies entirely within a single `#text` node.
+     */
+    replaceTextById(id, findText, replaceWith) {
+        const el = this.blockForId(id);
+        if (!el) {
+            return { ok: false, code: 'ANCHOR_NOT_FOUND', message: `Paragraph not found: ${id}` };
+        }
+        const { segments, visible } = buildSegments(el);
+        const matchStart = visible.indexOf(findText);
+        if (matchStart < 0) {
+            return { ok: false, code: 'TEXT_NOT_FOUND', message: `Text not found in paragraph ${id}: ${JSON.stringify(findText)}` };
+        }
+        const matchEnd = matchStart + findText.length;
+        const host = segments.find((seg) => seg.kind === 'text' && matchStart >= seg.visStart && matchEnd <= seg.visStart + seg.length);
+        if (!host || host.kind !== 'text') {
+            return {
+                ok: false,
+                code: 'MATCH_SPANS_MULTIPLE_NODES',
+                message: `Match for ${JSON.stringify(findText)} in paragraph ${id} crosses node boundaries ` +
+                    `(spans, spaces, or tabs). Phase 1 only replaces matches contained in a single text run.`,
+            };
+        }
+        const localStart = matchStart - host.visStart;
+        const localEnd = matchEnd - host.visStart;
+        host.node.data = host.node.data.slice(0, localStart) + replaceWith + host.node.data.slice(localEnd);
+        return { ok: true };
+    }
+    /**
+     * Insert one or more paragraphs relative to the anchor paragraph identified by `id`.
+     *
+     * `text` is split on blank lines (`\n{2,}`) into separate `text:p` blocks (parity with
+     * the DOCX `insert_paragraph` tool); a single `\n` within a block becomes a
+     * `text:line-break`. Inserted blocks inherit the anchor's `text:style-name` ONLY when
+     * the anchor is itself a `text:p` — inserting after a heading (`text:h`) produces
+     * default body paragraphs, never more headings.
+     *
+     * Paragraph IDs are positional ordinals, so every ID at or after the insertion point
+     * shifts by the number of inserted blocks. Returns the inserted blocks' freshly
+     * recomputed IDs in document order; callers must re-read before issuing further edits
+     * that target IDs near or after the insertion point.
+     */
+    insertParagraph(id, text, position) {
+        const anchor = this.blockForId(id);
+        if (!anchor) {
+            return { ok: false, code: 'ANCHOR_NOT_FOUND', message: `Paragraph not found: ${id}` };
+        }
+        const parent = anchor.parentNode;
+        if (!parent) {
+            return { ok: false, code: 'ANCHOR_NOT_FOUND', message: `Paragraph ${id} has no parent element` };
+        }
+        // Inherit the anchor's paragraph style only when the anchor is a body paragraph.
+        // Inserting relative to a heading must not produce another heading.
+        const inheritStyle = anchor.localName === 'p'
+            ? anchor.getAttributeNS(ODF_NS.TEXT, 'style-name') ?? anchor.getAttribute('text:style-name')
+            : null;
+        const blockTexts = text.replace(/\r\n/g, '\n').split(/\n{2,}/);
+        const newEls = blockTexts.map((blockText) => {
+            const p = this.doc.createElementNS(ODF_NS.TEXT, 'text:p');
+            if (inheritStyle)
+                p.setAttributeNS(ODF_NS.TEXT, 'text:style-name', inheritStyle);
+            const lines = blockText.split('\n');
+            lines.forEach((line, i) => {
+                if (i > 0)
+                    p.appendChild(this.doc.createElementNS(ODF_NS.TEXT, 'text:line-break'));
+                if (line.length > 0)
+                    p.appendChild(this.doc.createTextNode(line));
+            });
+            return p;
+        });
+        // `insertBefore(el, null)` appends, so AFTER on the last child appends correctly.
+        const refNode = position === 'AFTER' ? anchor.nextSibling : anchor;
+        for (const el of newEls) {
+            parent.insertBefore(el, refNode);
+        }
+        // Rebuild the structural block index; positional IDs shift accordingly.
+        const blocks = [];
+        collectBlocks(this.doc.documentElement, blocks);
+        this.blocks = blocks;
+        const newIds = newEls.map((el) => this.idForIndex(blocks.indexOf(el)));
+        return { ok: true, newIds };
+    }
+    /**
+     * Insert an `office:annotation` comment on the paragraph identified by `paragraphId`.
+     * Omit `start`/`end` to bracket the whole paragraph (structural insertion, independent of
+     * text segmentation); supply a visible `start`/`end` range to bracket a substring (which must
+     * lie within a single `#text` node, else `MATCH_SPANS_MULTIPLE_NODES`). Annotations are inline
+     * children, so positional paragraph IDs do NOT shift.
+     */
+    addComment(params) {
+        const block = this.blockForId(params.paragraphId);
+        if (!block) {
+            return { ok: false, code: 'ANCHOR_NOT_FOUND', message: `Paragraph not found: ${params.paragraphId}` };
+        }
+        const result = addAnnotation(this.doc, block, {
+            start: params.start,
+            end: params.end,
+            author: params.author,
+            text: params.text,
+            initials: params.initials,
+        });
+        if (!result.ok)
+            return result;
+        return { ok: true, commentId: result.commentId };
+    }
+    /** All `office:annotation` comments in document order. */
+    getComments() {
+        return readAnnotations(this.blocks);
+    }
+    /** Serialize the (possibly edited) document back to a `content.xml` string. */
+    toXml() {
+        return serializeXml(this.doc);
+    }
+}
+//# sourceMappingURL=document.js.map

package/dist/document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.js","sourceRoot":"","sources":["../src/document.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { OdfArchive } from './shared/odf/OdfArchive.js';
+export { OdfDocument, type OdfParagraph, type ReplaceResult, type InsertResult, type AddCommentParams, type AddCommentResult, } from './document.js';
+export { type OdfComment } from './comments.js';
+export { compareOdf, OdfEmitError, type OdfCompareResult, type OdfCompareStats, type OdfCompareOptions, } from './compare/index.js';
+export { validateOdfArchiveSafety, type OdfArchiveSafetyResult } from './odf_archive_safety.js';
+export { ODF_NS, ODF_PATHS, ODT_MIMETYPE } from './shared/odf/namespaces.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EACL,WAAW,EACX,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,GACtB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EACL,UAAU,EACV,YAAY,EACZ,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,iBAAiB,GACvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,wBAAwB,EAAE,KAAK,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAChG,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { OdfArchive } from './shared/odf/OdfArchive.js';
+export { OdfDocument, } from './document.js';
+export { compareOdf, OdfEmitError, } from './compare/index.js';
+export { validateOdfArchiveSafety } from './odf_archive_safety.js';
+export { ODF_NS, ODF_PATHS, ODT_MIMETYPE } from './shared/odf/namespaces.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EACL,WAAW,GAMZ,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,UAAU,EACV,YAAY,GAIb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,wBAAwB,EAA+B,MAAM,yBAAyB,CAAC;AAChG,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC"}