esoul-sdk 0.7.0 → 0.16.0

package/dist/editor-sync.d.ts

@@ -0,0 +1,130 @@
+/**
+ * EDITOR SYNC — how a MOUNTED editor takes a change that arrived from elsewhere (another device, another
+ * tab, an agent) while the person may be typing. The pure half: one decision and the merges. SINGLE SOURCE:
+ * the platform re-exports this file (src/lib/editor-sync/reconcile.ts), so an app built with the SDK and a
+ * built-in app decide identically. The hook is `useRemoteReconcile` in `esoul-sdk/react`; the guide is
+ * docs/17-editing-and-merging.md (platform design: .cursor/rules/docs/editor-sync.md).
+ *
+ * Before this, each editor carried its own copy of the rules, and each copy had its own holes. The UI
+ * harness found three in block-notes alone:
+ *   B1  the save's diff base was moved to the whole editor document after a merge, absorbing unsaved
+ *       typing — the save then removed the other writer's content;
+ *   B2  a merge offered to one editor instance was applied by the NEXT instance, over fresher content;
+ *   B3  a fold that raced our own save was adopted, putting older text in front of the user.
+ * and the survey of the other editors found a fourth everywhere:
+ *   B4  a remote change skipped while the user types (or while a save is pending) is overwritten by the
+ *       next local snapshot save, and — because that save's causal base is the STORE's newest, not what
+ *       the editor showed — the write fence accepts it silently.
+ *
+ * The rules, in order (decideReconcile):
+ *   1. incoming equals what the editor last knew (its base)  → nothing to do (an echo);
+ *   2. incoming equals what the editor shows now             → converged, the base moves;
+ *   3. the store holds an OLDER write of this session        → a fold that raced our save: ignore (B3);
+ *   4. the editor can merge (base, mine, theirs)              → merge now, keep typing, re-issue any
+ *                                                                pending save with the merged document
+ *                                                                (B1: the base becomes THEIRS, never
+ *                                                                the editor doc);
+ *   5. a local save is still pending                          → look again once it has gone out;
+ *   6. the user is editing and a merge is impossible          → wait for idle, and until then every save
+ *                                                                is stamped with the base the editor
+ *                                                                really built on, so the fence marks a
+ *                                                                conflict instead of silently winning (B4);
+ *   7. otherwise                                               → adopt.
+ * B2 is structural: all state lives in the editor instance (the hook's refs); nothing is offered across
+ * instances.
+ */
+/** The write fence's per-item bookkeeping this module reads (apply-app-event.ts `ItemRevMeta`). */
+export interface FenceItemMeta {
+    tip?: string;
+    ts?: number;
+    sess?: string;
+}
+/** The fence record of `itemKey` in an app state (`__itemRevs`), if any. */
+export declare function fenceMetaOf(state: unknown, itemKey: string): FenceItemMeta | undefined;
+/**
+ * Does the store hold a write of THIS session that is older than our last save? Then it is a fold that
+ * raced that save (a late poll, a collapse-merge read), not a remote change. Compared on this session's
+ * own clock only.
+ */
+export declare function isOlderOwnWrite(meta: FenceItemMeta | undefined, sessionId: string, lastOwnSaveAt: number | null | undefined): boolean;
+export type ReconcileDecision = {
+    kind: "echo";
+} | {
+    kind: "converged";
+} | {
+    kind: "stale-own";
+} | {
+    kind: "wait-save";
+} | {
+    kind: "merge";
+} | {
+    kind: "wait-idle";
+} | {
+    kind: "adopt";
+};
+/**
+ * What a mounted editor should do with the value the store now holds for the item it edits: echo, converged,
+ * stale-own, merge, wait-save, wait-idle or adopt (the rules above, in that order). Pure. `useRemoteReconcile`
+ * in esoul-sdk/react calls it for you; call it directly only to test your own adapter.
+ */
+export declare function decideReconcile<T>(args: {
+    incoming: T;
+    /** What the editor last knew the server to hold (its merge base). */
+    base: T | undefined;
+    /** What the editor shows right now. */
+    current: T;
+    equal: (a: T, b: T) => boolean;
+    /** A local save is scheduled and not yet dispatched. */
+    pending: boolean;
+    /** The user is in the middle of editing (focus, an open field). */
+    editing: boolean;
+    /** isOlderOwnWrite(...) for the incoming state. */
+    olderOwn: boolean;
+    /** The editor supplies a three-way merge. */
+    canMerge: boolean;
+    /** May a merge be applied while the person is editing? Default true. An editor that can only apply by
+     *  replacing its whole surface (an input in progress would be lost) sets false: it merges once idle. */
+    mergeWhileEditing?: boolean;
+}): ReconcileDecision;
+/** Structural equality over JSON values, object key order ignored. */
+export declare function jsonEqual(a: unknown, b: unknown): boolean;
+/**
+ * Three-way merge of a list of records addressed by id (blocks, pages, nodes, edges, tabs).
+ *
+ * A record changed on one side only takes that side; unchanged on both keeps base. Added on one side is
+ * kept; deleted on one side is dropped unless the OTHER side changed it (then the change survives).
+ * Changed differently on both sides is a real conflict → `null` (the caller falls back to waiting, and
+ * the fence records the conflict). Order: mine, with their inserts placed after their predecessor.
+ */
+export declare function mergeRecordsById<R>(base: readonly R[], mine: readonly R[], theirs: readonly R[], idOf: (r: R) => string | undefined, equal?: (a: R, b: R) => boolean, 
+/** Both sides changed one record: merge the record itself (e.g. its text by lines); null = conflict. */
+mergeRecord?: (base: R, mine: R, theirs: R) => R | null): R[] | null;
+/**
+ * Three-way merge of a flat record of fields (a form: to/cc/subject/body; a node's config). A field
+ * changed differently on both sides is a conflict → `null`.
+ */
+export declare function mergeFields<F extends Record<string, unknown>>(base: F, mine: F, theirs: F, equal?: (a: unknown, b: unknown) => boolean): F | null;
+/**
+ * Three-way merge of a text by lines. Keeps both sides when they touched different lines; any overlap
+ * (the same base line range changed on both sides) is a conflict → `null`.
+ */
+export declare function mergeLines(base: string, mine: string, theirs: string): string | null;
+/**
+ * Three-way merge of any SEQUENCE (lines, paragraphs, list items without ids): the two sides' changed regions
+ * against the base are found by longest common subsequence on `keyOf`; regions that do not overlap are both
+ * applied (two inserts at the same point both stay, ordered by content so every side agrees), overlapping ones are a
+ * conflict → `null`. Long common heads and tails are trimmed first, so a large document with local edits stays
+ * cheap. Pure.
+ *
+ * `unify(a, b)`: when two inserts land at the same point, items that are VERSIONS of one item (a paragraph one
+ * side copied while it was still being typed) come out as one — return the item to keep, or null when a and b
+ * are different items. It must be symmetric (the same answer for (a, b) and (b, a)) so every side converges.
+ */
+export declare function mergeSequences<T>(base: readonly T[], mine: readonly T[], theirs: readonly T[], keyOf: (item: T) => string, unify?: (a: T, b: T) => T | null): T[] | null;
+/**
+ * Where a caret (or selection edge) belongs after the text it sat in was replaced by a merge: unchanged when
+ * the change is entirely after it, shifted by the length difference when the change is before it. Pure. Use it
+ * when your editor is a controlled textarea — otherwise React puts the caret at the end and the rest of the
+ * person's typing lands after the other writer's text.
+ */
+export declare function mapCaretThroughEdit(prev: string, next: string, pos: number): number;

package/dist/editor-sync.js

@@ -0,0 +1,413 @@
+/**
+ * EDITOR SYNC — how a MOUNTED editor takes a change that arrived from elsewhere (another device, another
+ * tab, an agent) while the person may be typing. The pure half: one decision and the merges. SINGLE SOURCE:
+ * the platform re-exports this file (src/lib/editor-sync/reconcile.ts), so an app built with the SDK and a
+ * built-in app decide identically. The hook is `useRemoteReconcile` in `esoul-sdk/react`; the guide is
+ * docs/17-editing-and-merging.md (platform design: .cursor/rules/docs/editor-sync.md).
+ *
+ * Before this, each editor carried its own copy of the rules, and each copy had its own holes. The UI
+ * harness found three in block-notes alone:
+ *   B1  the save's diff base was moved to the whole editor document after a merge, absorbing unsaved
+ *       typing — the save then removed the other writer's content;
+ *   B2  a merge offered to one editor instance was applied by the NEXT instance, over fresher content;
+ *   B3  a fold that raced our own save was adopted, putting older text in front of the user.
+ * and the survey of the other editors found a fourth everywhere:
+ *   B4  a remote change skipped while the user types (or while a save is pending) is overwritten by the
+ *       next local snapshot save, and — because that save's causal base is the STORE's newest, not what
+ *       the editor showed — the write fence accepts it silently.
+ *
+ * The rules, in order (decideReconcile):
+ *   1. incoming equals what the editor last knew (its base)  → nothing to do (an echo);
+ *   2. incoming equals what the editor shows now             → converged, the base moves;
+ *   3. the store holds an OLDER write of this session        → a fold that raced our save: ignore (B3);
+ *   4. the editor can merge (base, mine, theirs)              → merge now, keep typing, re-issue any
+ *                                                                pending save with the merged document
+ *                                                                (B1: the base becomes THEIRS, never
+ *                                                                the editor doc);
+ *   5. a local save is still pending                          → look again once it has gone out;
+ *   6. the user is editing and a merge is impossible          → wait for idle, and until then every save
+ *                                                                is stamped with the base the editor
+ *                                                                really built on, so the fence marks a
+ *                                                                conflict instead of silently winning (B4);
+ *   7. otherwise                                               → adopt.
+ * B2 is structural: all state lives in the editor instance (the hook's refs); nothing is offered across
+ * instances.
+ */
+/** The fence record of `itemKey` in an app state (`__itemRevs`), if any. */
+export function fenceMetaOf(state, itemKey) {
+    const revs = state?.__itemRevs;
+    return revs?.[itemKey];
+}
+/**
+ * Does the store hold a write of THIS session that is older than our last save? Then it is a fold that
+ * raced that save (a late poll, a collapse-merge read), not a remote change. Compared on this session's
+ * own clock only.
+ */
+export function isOlderOwnWrite(meta, sessionId, lastOwnSaveAt) {
+    return (!!meta &&
+        meta.sess === sessionId &&
+        typeof meta.ts === "number" &&
+        typeof lastOwnSaveAt === "number" &&
+        meta.ts < lastOwnSaveAt);
+}
+/**
+ * What a mounted editor should do with the value the store now holds for the item it edits: echo, converged,
+ * stale-own, merge, wait-save, wait-idle or adopt (the rules above, in that order). Pure. `useRemoteReconcile`
+ * in esoul-sdk/react calls it for you; call it directly only to test your own adapter.
+ */
+export function decideReconcile(args) {
+    const { incoming, base, current, equal } = args;
+    if (base !== undefined && equal(incoming, base))
+        return { kind: "echo" };
+    if (equal(incoming, current))
+        return { kind: "converged" };
+    if (args.olderOwn)
+        return { kind: "stale-own" };
+    // A mergeable editor merges now, pending save or not: the merged document carries the unsaved edits and
+    // the save is re-issued with it.
+    if (args.canMerge && base !== undefined && !(args.editing && args.mergeWhileEditing === false))
+        return { kind: "merge" };
+    if (args.pending)
+        return { kind: "wait-save" };
+    if (args.editing)
+        return { kind: "wait-idle" };
+    return { kind: "adopt" };
+}
+/* ─────────────────────────────── merges ─────────────────────────────── */
+/** Structural equality over JSON values, object key order ignored. */
+export function jsonEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b || a === null || b === null || typeof a !== "object")
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    if (Array.isArray(a)) {
+        const bb = b;
+        if (a.length !== bb.length)
+            return false;
+        for (let i = 0; i < a.length; i++)
+            if (!jsonEqual(a[i], bb[i]))
+                return false;
+        return true;
+    }
+    const ao = a;
+    const bo = b;
+    const ak = Object.keys(ao).filter((k) => ao[k] !== undefined);
+    const bk = Object.keys(bo).filter((k) => bo[k] !== undefined);
+    if (ak.length !== bk.length)
+        return false;
+    for (const k of ak)
+        if (!jsonEqual(ao[k], bo[k]))
+            return false;
+    return true;
+}
+/**
+ * Three-way merge of a list of records addressed by id (blocks, pages, nodes, edges, tabs).
+ *
+ * A record changed on one side only takes that side; unchanged on both keeps base. Added on one side is
+ * kept; deleted on one side is dropped unless the OTHER side changed it (then the change survives).
+ * Changed differently on both sides is a real conflict → `null` (the caller falls back to waiting, and
+ * the fence records the conflict). Order: mine, with their inserts placed after their predecessor.
+ */
+export function mergeRecordsById(base, mine, theirs, idOf, equal = jsonEqual, 
+/** Both sides changed one record: merge the record itself (e.g. its text by lines); null = conflict. */
+mergeRecord) {
+    const map = (list) => {
+        const m = new Map();
+        for (const r of list) {
+            const id = idOf(r);
+            if (id === undefined)
+                return null;
+            m.set(id, r);
+        }
+        return m;
+    };
+    const b = map(base), m = map(mine), t = map(theirs);
+    if (!b || !m || !t)
+        return null;
+    const out = new Map();
+    const ids = new Set([...m.keys(), ...t.keys(), ...b.keys()]);
+    for (const id of ids) {
+        const bv = b.get(id), mv = m.get(id), tv = t.get(id);
+        const mChanged = bv === undefined ? mv !== undefined : mv === undefined || !equal(bv, mv);
+        const tChanged = bv === undefined ? tv !== undefined : tv === undefined || !equal(bv, tv);
+        if (!mChanged && !tChanged) {
+            if (bv !== undefined)
+                out.set(id, bv);
+            continue;
+        }
+        if (mChanged && !tChanged) {
+            if (mv !== undefined)
+                out.set(id, mv);
+            continue;
+        }
+        if (!mChanged && tChanged) {
+            if (tv !== undefined)
+                out.set(id, tv);
+            continue;
+        }
+        // Both changed.
+        if (mv !== undefined && tv !== undefined && equal(mv, tv)) {
+            out.set(id, mv);
+            continue;
+        }
+        if (mergeRecord && bv !== undefined && mv !== undefined && tv !== undefined) {
+            const merged = mergeRecord(bv, mv, tv);
+            if (merged !== null) {
+                out.set(id, merged);
+                continue;
+            }
+        }
+        return null;
+    }
+    // Order: mine's order for what survives, then theirs' records inserted after their predecessor.
+    const order = [];
+    const placed = new Set();
+    for (const r of mine) {
+        const id = idOf(r);
+        if (out.has(id) && !placed.has(id)) {
+            order.push(id);
+            placed.add(id);
+        }
+    }
+    const theirIds = theirs.map((r) => idOf(r));
+    theirIds.forEach((id, i) => {
+        if (!out.has(id) || placed.has(id))
+            return;
+        let at = 0;
+        for (let j = i - 1; j >= 0; j--) {
+            const k = order.indexOf(theirIds[j]);
+            if (k >= 0) {
+                at = k + 1;
+                break;
+            }
+        }
+        order.splice(at, 0, id);
+        placed.add(id);
+    });
+    for (const id of out.keys())
+        if (!placed.has(id))
+            order.push(id);
+    return order.map((id) => out.get(id));
+}
+/**
+ * Three-way merge of a flat record of fields (a form: to/cc/subject/body; a node's config). A field
+ * changed differently on both sides is a conflict → `null`.
+ */
+export function mergeFields(base, mine, theirs, equal = jsonEqual) {
+    const out = {};
+    const keys = new Set([...Object.keys(base), ...Object.keys(mine), ...Object.keys(theirs)]);
+    for (const k of keys) {
+        const bv = base[k], mv = mine[k], tv = theirs[k];
+        const mChanged = !equal(bv, mv), tChanged = !equal(bv, tv);
+        if (mChanged && tChanged && !equal(mv, tv))
+            return null;
+        const v = mChanged ? mv : tv;
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return out;
+}
+/**
+ * Three-way merge of a text by lines. Keeps both sides when they touched different lines; any overlap
+ * (the same base line range changed on both sides) is a conflict → `null`.
+ */
+export function mergeLines(base, mine, theirs) {
+    if (mine === theirs)
+        return mine;
+    if (base === mine)
+        return theirs;
+    if (base === theirs)
+        return mine;
+    const out = mergeSequences(base.split("\n"), mine.split("\n"), theirs.split("\n"), (l) => l);
+    return out === null ? null : out.join("\n");
+}
+/**
+ * Three-way merge of any SEQUENCE (lines, paragraphs, list items without ids): the two sides' changed regions
+ * against the base are found by longest common subsequence on `keyOf`; regions that do not overlap are both
+ * applied (two inserts at the same point both stay, ordered by content so every side agrees), overlapping ones are a
+ * conflict → `null`. Long common heads and tails are trimmed first, so a large document with local edits stays
+ * cheap. Pure.
+ *
+ * `unify(a, b)`: when two inserts land at the same point, items that are VERSIONS of one item (a paragraph one
+ * side copied while it was still being typed) come out as one — return the item to keep, or null when a and b
+ * are different items. It must be symmetric (the same answer for (a, b) and (b, a)) so every side converges.
+ */
+export function mergeSequences(base, mine, theirs, keyOf, unify) {
+    const B = base.map(keyOf), M = mine.map(keyOf), Tk = theirs.map(keyOf);
+    const same = (a, b) => a.length === b.length && a.every((x, i) => x === b[i]);
+    if (same(M, Tk))
+        return [...mine];
+    if (same(B, M))
+        return [...theirs];
+    if (same(B, Tk))
+        return [...mine];
+    const hm = hunks(B, M), ht = hunks(B, Tk);
+    // A real collision: two replaced ranges that intersect, or an insert strictly INSIDE a range the other side
+    // replaced. An insert right before or right after the other side's replaced range is unambiguous and merges
+    // (typing in the last paragraph while another device appends one after it). Two inserts at the SAME point
+    // both stay, in an order fixed by their content — every device and the server fold pick the same one — because
+    // refusing them lost one side's text outright (harness word-sync tabs: two tabs appending at the end).
+    const collide = (a, c) => {
+        const aIns = a.bStart === a.bEnd, cIns = c.bStart === c.bEnd;
+        if (aIns && cIns)
+            return false;
+        if (aIns)
+            return c.bStart < a.bStart && a.bStart < c.bEnd;
+        if (cIns)
+            return a.bStart < c.bStart && c.bStart < a.bEnd;
+        return a.bStart < c.bEnd && c.bStart < a.bEnd;
+    };
+    // The same change made on both sides (same base range, same new content) is one change, not a collision.
+    const sameChange = (a, c) => a.bStart === c.bStart && a.bEnd === c.bEnd && M.slice(a.sStart, a.sEnd).join("\u0000") === Tk.slice(c.sStart, c.sEnd).join("\u0000");
+    const dupT = new Set();
+    // With `unify`: both sides replaced the SAME base range with runs that share versions of one item (the paragraph
+    // one side copied mid-typing and the other finished) — one replacement, reconciled item by item.
+    const unifiedRuns = new Map();
+    for (const a of hm)
+        for (const c of ht) {
+            if (sameChange(a, c)) {
+                dupT.add(c);
+                continue;
+            }
+            if (unify && a.bStart === c.bStart && a.bEnd === c.bEnd && a.bEnd > a.bStart) {
+                const x = mine.slice(a.sStart, a.sEnd), y = theirs.slice(c.sStart, c.sEnd);
+                const xk = M.slice(a.sStart, a.sEnd).join("\u0000"), yk = Tk.slice(c.sStart, c.sEnd).join("\u0000");
+                const [first, second] = xk <= yk ? [x, y] : [y, x];
+                const joined = interleaveRuns(first, second, keyOf, unify);
+                if (joined.length < x.length + y.length) {
+                    unifiedRuns.set(a, joined);
+                    dupT.add(c);
+                    continue;
+                }
+            }
+            if (collide(a, c))
+                return null;
+        }
+    const htKept = ht.filter((c) => !dupT.has(c));
+    const keysOfHunk = (h, src) => src.slice(h.sStart, h.sEnd).join("\u0000");
+    // Order by base position; at a tie an insert goes before the range that starts there, and two inserts by content.
+    const all = [...hm.map((h) => ({ ...h, src: mine, k: keysOfHunk(h, M) })), ...htKept.map((h) => ({ ...h, src: theirs, k: keysOfHunk(h, Tk) }))].sort((x, y) => x.bStart - y.bStart || (x.bEnd - x.bStart) - (y.bEnd - y.bStart) || (x.k < y.k ? -1 : x.k > y.k ? 1 : 0));
+    const out = [];
+    let i = 0;
+    for (let n = 0; n < all.length; n++) {
+        const h = all[n];
+        while (i < h.bStart)
+            out.push(base[i++]);
+        const next = all[n + 1];
+        if (h.bStart === h.bEnd && next && next.bStart === next.bEnd && next.bStart === h.bStart && next.src !== h.src) {
+            // Two inserts at one point: the same run is one insert; with `unify`, versions of one item are one item.
+            const x = h.src.slice(h.sStart, h.sEnd), y = next.src.slice(next.sStart, next.sEnd);
+            if (h.k === next.k)
+                out.push(...x);
+            else
+                out.push(...interleaveRuns(x, y, keyOf, unify));
+            n++;
+            continue;
+        }
+        const unified = h.src === mine ? unifiedRuns.get(hm.find((x) => x.bStart === h.bStart && x.bEnd === h.bEnd && x.sStart === h.sStart)) : undefined;
+        if (unified)
+            out.push(...unified);
+        else
+            for (let k = h.sStart; k < h.sEnd; k++)
+                out.push(h.src[k]);
+        i = Math.max(i, h.bEnd);
+    }
+    while (i < base.length)
+        out.push(base[i++]);
+    return out;
+}
+/** Two runs inserted at one point, x first (content order): items equal by key, or unified, appear once. */
+function interleaveRuns(x, y, keyOf, unify) {
+    const match = (a, b) => (keyOf(a) === keyOf(b) ? a : unify ? unify(a, b) : null);
+    const n = x.length, m = y.length;
+    if (n * m > 250_000)
+        return [...x, ...y];
+    const dp = Array.from({ length: n + 1 }, () => new Uint32Array(m + 1));
+    for (let i = n - 1; i >= 0; i--)
+        for (let j = m - 1; j >= 0; j--) {
+            dp[i][j] = match(x[i], y[j]) !== null ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
+        }
+    const out = [];
+    let i = 0, j = 0;
+    while (i < n || j < m) {
+        const u = i < n && j < m ? match(x[i], y[j]) : null;
+        if (u !== null && dp[i][j] === dp[i + 1][j + 1] + 1) {
+            out.push(u);
+            i++;
+            j++;
+        }
+        else if (i < n && (j >= m || dp[i + 1][j] >= dp[i][j + 1]))
+            out.push(x[i++]);
+        else
+            out.push(y[j++]);
+    }
+    return out;
+}
+/** Changed regions of `s` against base `b`: base [bStart,bEnd) replaced by s [sStart,sEnd). LCS-based, with the
+ *  common head and tail trimmed first. */
+function hunks(b, s) {
+    let head = 0;
+    while (head < b.length && head < s.length && b[head] === s[head])
+        head++;
+    let tail = 0;
+    while (tail < b.length - head && tail < s.length - head && b[b.length - 1 - tail] === s[s.length - 1 - tail])
+        tail++;
+    const bm = b.slice(head, b.length - tail), sm = s.slice(head, s.length - tail);
+    const n = bm.length, m = sm.length;
+    if (n === 0 && m === 0)
+        return [];
+    // LCS table over the changed middle (bail out to one whole hunk when it is huge).
+    if (n * m > 4_000_000)
+        return [{ bStart: head, bEnd: head + n, sStart: head, sEnd: head + m }];
+    const dp = Array.from({ length: n + 1 }, () => new Uint32Array(m + 1));
+    for (let i = n - 1; i >= 0; i--)
+        for (let j = m - 1; j >= 0; j--) {
+            dp[i][j] = bm[i] === sm[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
+        }
+    const out = [];
+    let i = 0, j = 0;
+    let open = null;
+    const close = () => { if (open) {
+        out.push({ bStart: head + open.bStart, bEnd: head + i, sStart: head + open.sStart, sEnd: head + j });
+        open = null;
+    } };
+    while (i < n || j < m) {
+        if (i < n && j < m && bm[i] === sm[j]) {
+            close();
+            i++;
+            j++;
+            continue;
+        }
+        if (!open)
+            open = { bStart: i, sStart: j };
+        if (j < m && (i >= n || dp[i][j + 1] >= dp[i + 1][j]))
+            j++;
+        else
+            i++;
+    }
+    close();
+    return out;
+}
+/**
+ * Where a caret (or selection edge) belongs after the text it sat in was replaced by a merge: unchanged when
+ * the change is entirely after it, shifted by the length difference when the change is before it. Pure. Use it
+ * when your editor is a controlled textarea — otherwise React puts the caret at the end and the rest of the
+ * person's typing lands after the other writer's text.
+ */
+export function mapCaretThroughEdit(prev, next, pos) {
+    let p = 0;
+    const n = Math.min(prev.length, next.length);
+    while (p < n && prev.charCodeAt(p) === next.charCodeAt(p))
+        p++;
+    if (pos <= p)
+        return pos;
+    let q = 0;
+    while (q < n - p && prev.charCodeAt(prev.length - 1 - q) === next.charCodeAt(next.length - 1 - q))
+        q++;
+    // pos inside the unchanged tail → keep its distance from the end; inside the changed region → end of the change.
+    if (prev.length - pos <= q)
+        return next.length - (prev.length - pos);
+    return next.length - q;
+}

package/dist/files.d.ts

@@ -38,11 +38,14 @@ export interface FileEntry {
     path?: string;
 }
 export type FileSourceErrorKind = "not_declared" | "source_unavailable" | "not_found" | "too_large" | "read_only" | "disabled" | "bad_ref";
+/** A files call refused — `kind` says why: not_declared (the manifest has no `files` grant for it), source_unavailable, not_found, too_large, read_only, disabled, bad_ref. */
 export declare class FileSourceError extends Error {
     readonly kind: FileSourceErrorKind;
     constructor(kind: FileSourceErrorKind, message: string);
 }
+/** The default most `FilesApi.read` returns (25 MB); pass `capBytes` to raise it. */
 export declare const FILE_READ_CAP_BYTES: number;
+/** The ceiling `capBytes` may raise a read to (100 MB). */
 export declare const FILE_READ_HARD_CAP_BYTES: number;
 export type ParsedSourceId = {
     kind: "workspace";
@@ -56,4 +59,71 @@ export type ParsedSourceId = {
     providerKey: string;
     connectionId: string;
 };
+/** A file source id as its parts: the workspace, Google Drive, a local mount, or an app's own provider. */
 export declare function parseSourceId(sourceId: string): ParsedSourceId;
+/** Narrow a listing at the SOURCE — a folder of 5,000 files is filtered by Drive, not by your UI. */
+export interface FileListOptions {
+    /** Only folders (a path autocomplete) or only files. */
+    only?: "file" | "folder";
+    /** Case-insensitive substring of the name. */
+    nameContains?: string;
+    /** "name" = natural name order (frame_2 before frame_10); "modified" = newest first. Default: the provider's own. */
+    orderBy?: "name" | "modified";
+    /** Entries per page, 1–1000 (default 100). */
+    pageSize?: number;
+}
+/** The most one page of a listing holds. */
+export declare const FILE_LIST_PAGE_MAX = 1000;
+/** The most `listAll` gathers before it answers `truncated: true`. */
+export declare const FILE_LIST_ALL_MAX = 20000;
+/** The most `readMany` reads in one call, in files and in bytes. */
+export declare const FILE_READ_MANY_MAX = 200;
+/** …and the most bytes it gathers in one call (64 MB); past it the remaining rows answer `too_large`. */
+export declare const FILE_READ_MANY_TOTAL_BYTES: number;
+/** The longest a read grant lives (24 h); the default is one hour. */
+export declare const FILE_GRANT_MAX_TTL_SECONDS: number;
+/** How long a read grant lives when `ttlSeconds` is not given: one hour. */
+export declare const FILE_GRANT_DEFAULT_TTL_SECONDS: number;
+/** What `write` answers: the file as it now stands, and whether it was made or replaced. */
+export interface FileWriteResult {
+    entry: FileEntry;
+    created: boolean;
+}
+/** One answer of `readMany` — flat: `ok` true carries the bytes, false carries `kind` and `error`. */
+export interface FileReadManyItem {
+    ref: FileRef;
+    ok: boolean;
+    name?: string;
+    contentType?: string;
+    /** The file's bytes as UTF-8 text (`as: "text"`, the default) … */
+    text?: string;
+    /** … or base64 (`as: "base64"`). */
+    base64?: string;
+    kind?: FileSourceErrorKind;
+    error?: string;
+}
+/**
+ * A READ GRANT: a signed, expiring permission to fetch files of ONE source of ONE
+ * workspace by URL, with no session — for an `<img>` in a preview, and for a machine
+ * (the person's computer downloading a training set). Build each file's URL with
+ * `fileGrantUrl`. Treat it like a password until it expires.
+ */
+export interface FileReadGrant {
+    sourceId: FileSourceId;
+    /** Everything but the file: `…/api/file-sources/raw?ws=…&src=…&t=…`. */
+    urlBase: string;
+    /** Epoch ms. */
+    expiresAt: number;
+}
+/** The URL of one file under a grant. `width` asks for a downsized image (a thumbnail), 16–2048 px. */
+export declare function fileGrantUrl(grant: Pick<FileReadGrant, "urlBase">, ref: FileRef | string, opts?: {
+    width?: number;
+}): string;
+/** Does an entry pass these listing options? The one rule every provider's listing is held to. */
+export declare function matchesListOptions(entry: Pick<FileEntry, "name" | "kind">, opts?: FileListOptions | null): boolean;
+/** `pageSize` as a provider may use it: a whole number from 1 to FILE_LIST_PAGE_MAX, default 100. */
+export declare function listPageSize(opts?: FileListOptions | null): number;
+/** "sheets/quality_dataset/Type5" → its segments. Leading "/", a source's own label and empty parts are dropped. */
+export declare function splitFilePath(path: string): string[];
+/** Natural name order: "frame_2" before "frame_10". */
+export declare function compareFileNames(a: string, b: string): number;