smartrte-core 0.2.1 → 1.0.0-beta.1

package/dist/foundation/collab/rebase.js

@@ -0,0 +1,82 @@
+import { FoundationTransactionMap } from "../mapping.js";
+import { transformOperation } from "./transform.js";
+/**
+ * Deterministic total order for the exact-tie case (see mapOperation's own
+ * tieBreakBias doc comment) - lexicographic authorId comparison, computed
+ * once per (local, remote) transaction pair so every operation pair within
+ * that pairing agrees. Falls back to `1` (mapOperation's existing default)
+ * when either side has no authorId, matching this codebase's convention
+ * that authorId is optional (single-writer/no-transport usage never sets
+ * it, and never hits a real tie to begin with).
+ */
+const tieBreakBias = (localAuthorId, remoteAuthorId) => {
+    if (!localAuthorId || !remoteAuthorId || localAuthorId === remoteAuthorId)
+        return 1;
+    return localAuthorId < remoteAuthorId ? -1 : 1;
+};
+/**
+ * Rebases `transaction` (whose `baseRevision` is behind the current
+ * revision) through every transaction committed since, in commit order.
+ * Each of `transaction`'s own operations is threaded through every
+ * operation of every missed transaction in sequence - the standard
+ * single-step operational-transform composition, built on `mapOperation`/
+ * `transformOperation`.
+ *
+ * Atomic per transaction: if any one operation conflicts, the whole
+ * transaction is rejected as a conflict rather than partially applied -
+ * matching `applyTransactionAtomic`'s own existing all-or-nothing
+ * semantics, and avoiding a confusing state where only part of a user's
+ * intent materializes.
+ *
+ * Does not check retention/resync - `missed` is whatever the caller
+ * supplies; a caller backed by a bounded revision log is responsible for
+ * returning `resync-required` itself before ever calling this when the
+ * requested history has already been evicted (see editor.ts's dispatch).
+ *
+ * `newBaseRevision` is the revision the rebased transaction should be
+ * stamped with (i.e. the live revision the caller is about to apply
+ * against) - taken explicitly from the caller rather than inferred from
+ * `missed`'s own entries, so a gap or reordering bug in how the caller
+ * assembled `missed` can't silently produce a wrong revision stamp here.
+ */
+export const rebaseTransaction = (transaction, missed, newBaseRevision) => {
+    if (!missed.length)
+        return { kind: "ok", transaction: { ...transaction, baseRevision: newBaseRevision } };
+    const conflicts = [];
+    const rebasedOperations = transaction.operations.map((operation, operationIndex) => {
+        let current = operation;
+        for (const remote of missed) {
+            if (current === null)
+                break;
+            const bias = tieBreakBias(transaction.metadata.authorId, remote.metadata.authorId);
+            for (const through of remote.operations) {
+                if (current === null)
+                    break;
+                const result = transformOperation(current, through, { tieBreakBias: bias });
+                if (result.kind === "conflict") {
+                    conflicts.push({ operationIndex, reason: result.reason });
+                    current = null;
+                }
+                else {
+                    current = result.kind === "dropped" ? null : result.operation;
+                }
+            }
+        }
+        return current;
+    });
+    if (conflicts.length)
+        return { kind: "conflict", reasons: conflicts };
+    const survivors = rebasedOperations.filter((operation) => operation !== null);
+    if (!survivors.length)
+        return { kind: "dropped" };
+    const missedOperations = missed.flatMap((remote) => remote.operations);
+    const selectionMap = new FoundationTransactionMap(missedOperations);
+    const rebased = {
+        ...transaction,
+        baseRevision: newBaseRevision,
+        operations: survivors,
+        selectionBefore: selectionMap.mapSelection(transaction.selectionBefore),
+        selectionAfter: selectionMap.mapSelection(transaction.selectionAfter),
+    };
+    return { kind: "ok", transaction: rebased };
+};

package/dist/foundation/collab/transform.d.ts

@@ -0,0 +1,73 @@
+import type { SmartOperation } from "../types.js";
+import type { TransformResult } from "./types.js";
+/**
+ * Transforms `operation` through a single concurrent `through` operation,
+ * classifying the small number of shapes this codebase's operation model
+ * cannot safely auto-resolve rather than silently deferring to
+ * `mapOperation`'s uniform `null` for all of them (see this module's
+ * `types.ts` doc comment on `TransformResult`).
+ *
+ * Two conflict shapes, both decided explicitly (2026-08-27, product
+ * decision) rather than attempted automatically:
+ *
+ * 1. **Concurrent moveNode vs. *any* structural operation touching the same
+ *    parent array as its `from` or `to`.** `moveNode.to` is defined
+ *    relative to "the array with this move's own source already removed"
+ *    (operations.ts's applyToSession) - a convention with no well-defined
+ *    composition once a concurrent structural change *also* touches that
+ *    same array, even one that doesn't touch the moved node itself.
+ *    Confirmed empirically via property tests, in increasing generality:
+ *    two moves of *different* nodes to nearby destinations produced
+ *    different final orders depending on transform direction; a move
+ *    composed with a same-node remove crashed outright; and - the broadest
+ *    case - a moveNode transformed through a plain removeNode of a
+ *    *completely unrelated* node in the same array still diverged (moving
+ *    "to offset 6" means different things depending on whether that offset
+ *    is read before or after the unrelated removal is accounted for).
+ *    Fixing this in general means redefining `to` for every existing
+ *    moveNode caller (table row/column reorder, list item reorder) - out of
+ *    scope for this phase. Flagged as a conflict for *any* concurrent
+ *    structural operation (insertNode/removeNode/replaceNode/moveNode) on
+ *    the same parent array, not narrowed to same-node cases only.
+ * 2. **Concurrent edit to content a `removeNode.mergedInto`/
+ *    `replaceNode.retiredInto` operation absorbed.** `mapOperation` already
+ *    ignores these fields entirely (by design - see the SmartOperation type
+ *    comment; they were built in Phase 12a only for `rebaseAnnotationRange`,
+ *    a different, ID-keyed mechanism). Auto-redirecting an *operation*
+ *    (rather than an annotation range's endpoint) to the survivor has its
+ *    own correctness risk even for whole-node-targeting ops - e.g. a
+ *    concurrent `setNodeAttributes` redirected to the survivor would carry
+ *    a `before` payload captured against the *retired* node's attrs, which
+ *    `applyOperation`'s strict before-check would then reject against the
+ *    survivor's actual attrs. Flagged as a conflict, consistent with
+ *    decision 1, rather than attempting a redirect whose correctness isn't
+ *    established.
+ * 3. **Concurrent mergeNode vs. anything occupying its left (survivor) or
+ *    right (retired) slot** (2026-08-28, required follow-up to finding #1
+ *    in mapoperation-position-arithmetic-gaps.md). `applyOperation`'s own
+ *    mergeNode handling validates `splitOffset === left.children.length`
+ *    and that left/right are structurally compatible - both checks depend
+ *    on the actual identity of whatever occupies those two slots.
+ *    `mapPosThroughOperation`'s mergeNode-as-through branch only tracks a
+ *    single explicit position (`operation.pos`/`.from`/`.to`), so an
+ *    ordinary sibling-index shift correctly keeps a *retiring* target
+ *    reachable but has no way to notice that a node's *identity* changed
+ *    underneath an *implicit* left-neighbor reference. Confirmed
+ *    empirically: two mergeNode ops retiring adjacent siblings (A retires
+ *    node N into its left neighbor, B retires N's *next* sibling into N)
+ *    crashed in one transform direction and silently produced a different
+ *    document in the other; a mergeNode composed with a concurrent
+ *    `removeNode` of its own left/survivor node crashed both ways. A
+ *    concurrent `splitNode` targeting the *exact* node a mergeNode retires
+ *    was checked and found *not* to need this treatment - it already gets
+ *    `mapPosThroughOperation`'s explicit "this position IS the retired
+ *    node, redirect into the survivor" case, which correctly recomputes an
+ *    in-bounds position rather than carrying a stale content-derived
+ *    payload the way `mergeNode.splitOffset` does. Same reasoning as
+ *    finding 1 above: not narrowed further, since fixing this generally
+ *    would mean giving `mapOperation` document access it deliberately
+ *    doesn't have.
+ */
+export declare const transformOperation: (operation: SmartOperation, through: SmartOperation, options?: {
+    tieBreakBias?: -1 | 1;
+}) => TransformResult;

package/dist/foundation/collab/transform.js

@@ -0,0 +1,251 @@
+import { mapOperation } from "../operations.js";
+import { samePath } from "../positions.js";
+/** `[...pos.path, pos.offset]` - the full path to whatever slot/child `pos` addresses, for whole-node operations (insertNode/removeNode/replaceNode/setNodeAttributes/setNodeType). */
+const slotPath = (pos) => [...pos.path, pos.offset];
+/** True when `pos` (a container-relative position, e.g. an insertText/deleteText/addMark endpoint) sits at-or-within the subtree rooted at `subtreeRoot`'s slot. Mirrors the removeNode-vs-descendant check already established in mapPosThroughOperation. */
+const isWithinSubtree = (pos, subtreeRoot) => {
+    const root = slotPath(subtreeRoot);
+    return samePath(pos.path.slice(0, root.length), root);
+};
+/** True when `pos` addresses the exact same slot as `subtreeRoot` (a whole-node operation targeting that node directly, not something inside it). */
+const isExactlyAtSlot = (pos, subtreeRoot) => samePath(pos.path, subtreeRoot.path) && pos.offset === subtreeRoot.offset;
+/**
+ * The two "occupied slot" references a mergeNode operation cares about:
+ * the surviving left sibling (`pos.offset - 1`) and the retired right
+ * sibling (`pos` itself). `applyOperation`'s own mergeNode handling
+ * validates `splitOffset === left.children.length` and that left/right are
+ * structurally compatible - both checks depend on the *actual identity* of
+ * whatever currently occupies these two slots, not just their positions.
+ */
+const mergeNodeSlots = (op) => [
+    { path: op.pos.path, offset: op.pos.offset - 1 },
+    { path: op.pos.path, offset: op.pos.offset },
+];
+/**
+ * The exact-slot reference for operation types that identify a node by
+ * "parent + child index" (the same convention mergeNode's own slots use) -
+ * restricted to the types where an exact offset match genuinely means "the
+ * same node," which excludes insertNode (a *gap* reference, not an
+ * occupied slot - two different conventions sharing the same {path,
+ * offset} shape, the same distinction already established for the
+ * removeNode/replaceNode exact-match fix in mapOperation) and excludes
+ * splitNode/setNodeAttributes/insertText/deleteText/addMark (deeper or
+ * differently-conventioned references that `mapPosThroughOperation`'s own
+ * mergeNode-as-through branch already redirects safely - confirmed via a
+ * property test that a splitNode targeting the exact node a concurrent
+ * mergeNode retires converges correctly without needing to be flagged
+ * here).
+ */
+const occupiedSlotsOf = (op) => {
+    if (op.type === "removeNode" || op.type === "replaceNode")
+        return [op.pos];
+    if (op.type === "mergeNode")
+        return mergeNodeSlots(op);
+    // moveNode.from/.to use the same "occupied slot" convention, but any
+    // moveNode paired with a mergeNode already shares a parent array (the
+    // merge's own path) and is caught unconditionally by the broader moveNode
+    // conflict rule above, before this function is reached - listing it here
+    // too would be redundant, not incorrect.
+    return null;
+};
+const operationTouchesSubtree = (operation, subtreeRoot) => {
+    if (operation.type === "insertNode" || operation.type === "removeNode" || operation.type === "replaceNode"
+        || operation.type === "setNodeAttributes" || operation.type === "setNodeType"
+        || operation.type === "splitNode" || operation.type === "mergeNode"
+        || operation.type === "insertText" || operation.type === "deleteText") {
+        return { exact: isExactlyAtSlot(operation.pos, subtreeRoot), within: isWithinSubtree(operation.pos, subtreeRoot) };
+    }
+    if (operation.type === "moveNode") {
+        return {
+            exact: isExactlyAtSlot(operation.from, subtreeRoot) || isExactlyAtSlot(operation.to, subtreeRoot),
+            within: isWithinSubtree(operation.from, subtreeRoot) || isWithinSubtree(operation.to, subtreeRoot),
+        };
+    }
+    // addMark / removeMark
+    return {
+        exact: false,
+        within: isWithinSubtree(operation.range.from, subtreeRoot) || isWithinSubtree(operation.range.to, subtreeRoot),
+    };
+};
+/**
+ * Transforms `operation` through a single concurrent `through` operation,
+ * classifying the small number of shapes this codebase's operation model
+ * cannot safely auto-resolve rather than silently deferring to
+ * `mapOperation`'s uniform `null` for all of them (see this module's
+ * `types.ts` doc comment on `TransformResult`).
+ *
+ * Two conflict shapes, both decided explicitly (2026-08-27, product
+ * decision) rather than attempted automatically:
+ *
+ * 1. **Concurrent moveNode vs. *any* structural operation touching the same
+ *    parent array as its `from` or `to`.** `moveNode.to` is defined
+ *    relative to "the array with this move's own source already removed"
+ *    (operations.ts's applyToSession) - a convention with no well-defined
+ *    composition once a concurrent structural change *also* touches that
+ *    same array, even one that doesn't touch the moved node itself.
+ *    Confirmed empirically via property tests, in increasing generality:
+ *    two moves of *different* nodes to nearby destinations produced
+ *    different final orders depending on transform direction; a move
+ *    composed with a same-node remove crashed outright; and - the broadest
+ *    case - a moveNode transformed through a plain removeNode of a
+ *    *completely unrelated* node in the same array still diverged (moving
+ *    "to offset 6" means different things depending on whether that offset
+ *    is read before or after the unrelated removal is accounted for).
+ *    Fixing this in general means redefining `to` for every existing
+ *    moveNode caller (table row/column reorder, list item reorder) - out of
+ *    scope for this phase. Flagged as a conflict for *any* concurrent
+ *    structural operation (insertNode/removeNode/replaceNode/moveNode) on
+ *    the same parent array, not narrowed to same-node cases only.
+ * 2. **Concurrent edit to content a `removeNode.mergedInto`/
+ *    `replaceNode.retiredInto` operation absorbed.** `mapOperation` already
+ *    ignores these fields entirely (by design - see the SmartOperation type
+ *    comment; they were built in Phase 12a only for `rebaseAnnotationRange`,
+ *    a different, ID-keyed mechanism). Auto-redirecting an *operation*
+ *    (rather than an annotation range's endpoint) to the survivor has its
+ *    own correctness risk even for whole-node-targeting ops - e.g. a
+ *    concurrent `setNodeAttributes` redirected to the survivor would carry
+ *    a `before` payload captured against the *retired* node's attrs, which
+ *    `applyOperation`'s strict before-check would then reject against the
+ *    survivor's actual attrs. Flagged as a conflict, consistent with
+ *    decision 1, rather than attempting a redirect whose correctness isn't
+ *    established.
+ * 3. **Concurrent mergeNode vs. anything occupying its left (survivor) or
+ *    right (retired) slot** (2026-08-28, required follow-up to finding #1
+ *    in mapoperation-position-arithmetic-gaps.md). `applyOperation`'s own
+ *    mergeNode handling validates `splitOffset === left.children.length`
+ *    and that left/right are structurally compatible - both checks depend
+ *    on the actual identity of whatever occupies those two slots.
+ *    `mapPosThroughOperation`'s mergeNode-as-through branch only tracks a
+ *    single explicit position (`operation.pos`/`.from`/`.to`), so an
+ *    ordinary sibling-index shift correctly keeps a *retiring* target
+ *    reachable but has no way to notice that a node's *identity* changed
+ *    underneath an *implicit* left-neighbor reference. Confirmed
+ *    empirically: two mergeNode ops retiring adjacent siblings (A retires
+ *    node N into its left neighbor, B retires N's *next* sibling into N)
+ *    crashed in one transform direction and silently produced a different
+ *    document in the other; a mergeNode composed with a concurrent
+ *    `removeNode` of its own left/survivor node crashed both ways. A
+ *    concurrent `splitNode` targeting the *exact* node a mergeNode retires
+ *    was checked and found *not* to need this treatment - it already gets
+ *    `mapPosThroughOperation`'s explicit "this position IS the retired
+ *    node, redirect into the survivor" case, which correctly recomputes an
+ *    in-bounds position rather than carrying a stale content-derived
+ *    payload the way `mergeNode.splitOffset` does. Same reasoning as
+ *    finding 1 above: not narrowed further, since fixing this generally
+ *    would mean giving `mapOperation` document access it deliberately
+ *    doesn't have.
+ */
+export const transformOperation = (operation, through, options = {}) => {
+    const structuralParentPaths = (candidate) => {
+        if (candidate.type === "insertNode" || candidate.type === "removeNode" || candidate.type === "replaceNode")
+            return [candidate.pos.path];
+        if (candidate.type === "moveNode")
+            return [candidate.from.path, candidate.to.path];
+        return [];
+    };
+    if (operation.type === "moveNode" || through.type === "moveNode") {
+        const moveOperation = operation.type === "moveNode" ? operation : through.type === "moveNode" ? through : null;
+        const other = moveOperation === operation ? through : operation;
+        if (moveOperation) {
+            const moveParents = structuralParentPaths(moveOperation);
+            const otherParents = structuralParentPaths(other);
+            const sharesArray = otherParents.some((otherPath) => moveParents.some((movePath) => samePath(otherPath, movePath)));
+            if (sharesArray) {
+                return { kind: "conflict", reason: `Concurrent structural change shares an array with moveNode of "${moveOperation.nodeId}".` };
+            }
+        }
+    }
+    if (operation.type === "mergeNode" || through.type === "mergeNode") {
+        const mergeOperation = operation.type === "mergeNode" ? operation : through.type === "mergeNode" ? through : null;
+        const other = mergeOperation === operation ? through : operation;
+        if (mergeOperation) {
+            const mergeSlots = mergeNodeSlots(mergeOperation);
+            const otherSlots = occupiedSlotsOf(other);
+            const overlaps = otherSlots?.some((otherSlot) => mergeSlots.some((mergeSlot) => isExactlyAtSlot(otherSlot, mergeSlot)));
+            if (overlaps) {
+                return { kind: "conflict", reason: "Concurrent operation occupies the same slot a mergeNode's left or right side depends on." };
+            }
+        }
+    }
+    if (through.type === "removeNode" && through.mergedInto) {
+        const touch = operationTouchesSubtree(operation, through.pos);
+        if (touch.within) {
+            return { kind: "conflict", reason: `Concurrent operation targets content merged into "${through.mergedInto}".` };
+        }
+    }
+    if (through.type === "replaceNode" && through.retiredInto?.length) {
+        const touch = operationTouchesSubtree(operation, through.pos);
+        if (touch.within) {
+            return { kind: "conflict", reason: "Concurrent operation targets content retired by a merge." };
+        }
+    }
+    // Symmetric case: `operation` (not `through`) is the merge - e.g.
+    // rebasing a table-cell-merge transaction through a concurrent edit to
+    // the cell it's about to absorb, the reverse pairing of the two checks
+    // above. Naively letting this "succeed" would silently discard the
+    // concurrent edit the instant the merge's removeNode/replaceNode
+    // actually applies, with nothing in the result signaling that happened.
+    if (operation.type === "removeNode" && operation.mergedInto) {
+        const touch = operationTouchesSubtree(through, operation.pos);
+        if (touch.within) {
+            return { kind: "conflict", reason: `A concurrent operation targets content this merge would absorb into "${operation.mergedInto}".` };
+        }
+    }
+    if (operation.type === "replaceNode" && operation.retiredInto?.length) {
+        const touch = operationTouchesSubtree(through, operation.pos);
+        if (touch.within) {
+            return { kind: "conflict", reason: "A concurrent operation targets content this merge would retire." };
+        }
+    }
+    // A deleteText operation carries the exact text it expects to remove, as
+    // a self-check (operations.ts's applyToSession rejects it if the live
+    // document doesn't match). If a concurrent insertText lands strictly
+    // inside that span, the stored text is now stale relative to what's
+    // actually there - mapOperation only shifts positions, it never touches
+    // this payload (it has no document access to recompute it from), so
+    // naively shifting the position and reapplying the original text would
+    // either fail this self-check outright or, worse, delete the wrong
+    // characters if the lengths happened to still line up. Flagged as a
+    // conflict, consistent with the move/merge decisions above, rather than
+    // guessing whether the new content should be swept into the deletion or
+    // preserved. Deliberately excludes the boundary case (insert exactly at
+    // the deletion's start or end) - only a strictly-interior insert is
+    // ambiguous.
+    if (operation.type === "deleteText" && through.type === "insertText" && samePath(operation.pos.path, through.pos.path)) {
+        const deleteEnd = operation.pos.offset + operation.text.length;
+        if (through.pos.offset > operation.pos.offset && through.pos.offset < deleteEnd) {
+            return { kind: "conflict", reason: "Concurrent insertion lands inside a deleted range." };
+        }
+    }
+    if (operation.type === "insertText" && through.type === "deleteText" && samePath(operation.pos.path, through.pos.path)) {
+        const deleteEnd = through.pos.offset + through.text.length;
+        if (operation.pos.offset > through.pos.offset && operation.pos.offset < deleteEnd) {
+            return { kind: "conflict", reason: "Insertion lands inside a concurrently deleted range." };
+        }
+    }
+    // Two overlapping deleteText ranges - same staleness problem as above:
+    // whichever one is transformed second no longer has an accurate `.text`
+    // payload for however much of its range the other one already removed
+    // (found via a property test: two concurrent deletes of "45" and "4" at
+    // the same offset - applying one first makes the other's stored text
+    // immediately wrong). An *identical* delete (same offset, same text - two
+    // authors deleting the exact same span) has no real ambiguity - the
+    // second one's intent is already satisfied, so it's dropped as an
+    // ordinary no-op rather than surfaced as a conflict. mapOperation itself
+    // has no such exact-match handling for deleteText (confirmed via the same
+    // property test - it left the position untouched, causing the identical
+    // no-op case to crash too), so this is handled explicitly here, not
+    // deferred.
+    if (operation.type === "deleteText" && through.type === "deleteText" && samePath(operation.pos.path, through.pos.path)) {
+        const opEnd = operation.pos.offset + operation.text.length;
+        const throughEnd = through.pos.offset + through.text.length;
+        const overlaps = operation.pos.offset < throughEnd && through.pos.offset < opEnd;
+        const identical = operation.pos.offset === through.pos.offset && operation.text === through.text;
+        if (identical)
+            return { kind: "dropped" };
+        if (overlaps)
+            return { kind: "conflict", reason: "Concurrent deletions overlap." };
+    }
+    const mapped = mapOperation(operation, through, options);
+    return mapped ? { kind: "ok", operation: mapped } : { kind: "dropped" };
+};

package/dist/foundation/collab/types.d.ts

@@ -0,0 +1,52 @@
+import type { SmartOperation, SmartTransaction } from "../types.js";
+export type MoveNodeOperation = Extract<SmartOperation, {
+    type: "moveNode";
+}>;
+export type RemoveNodeOperation = Extract<SmartOperation, {
+    type: "removeNode";
+}>;
+export type ReplaceNodeOperation = Extract<SmartOperation, {
+    type: "replaceNode";
+}>;
+/**
+ * Result of transforming one operation through a single concurrent
+ * "through" operation - `mapOperation` (operations.ts) only ever returns
+ * `SmartOperation | null`, collapsing "target no longer exists, this
+ * operation is now a harmless no-op" and "target was folded into something
+ * else and this operation cannot be safely, precisely redirected" into the
+ * same `null`. Concurrent rebase needs to tell those apart: the first is
+ * routine and silent, the second must be surfaced (per this phase's stop
+ * condition 4 - a rebase must never silently corrupt state or silently
+ * drop a conflicting edit without saying so).
+ */
+export type TransformResult = {
+    kind: "ok";
+    operation: SmartOperation;
+} | {
+    kind: "dropped";
+} | {
+    kind: "conflict";
+    reason: string;
+};
+/** Rebasing a whole transaction through everything committed since its baseRevision. */
+export type RebaseResult = {
+    kind: "ok";
+    transaction: SmartTransaction;
+}
+/** Every operation in the transaction turned out to be a no-op against the current state (e.g. it only edited content someone else already deleted outright). Nothing to apply; the transaction is simply dropped. */
+ | {
+    kind: "dropped";
+}
+/** At least one operation could not be safely transformed - see `reasons` for which operation (by index) and why. The transaction as a whole is rejected; the caller decides what happens to the user's edit (see rebaseTransaction's own doc comment). */
+ | {
+    kind: "conflict";
+    reasons: readonly {
+        operationIndex: number;
+        reason: string;
+    }[];
+}
+/** `sinceRevision` predates what this client has retained - a transform can't be attempted at all without the missing history. The caller must resync (reload the full document at the current revision) rather than attempt a partial rebase. */
+ | {
+    kind: "resync-required";
+    atRevision: number;
+};

package/dist/foundation/collab/types.js

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

package/dist/foundation/comments/fromSelection.d.ts

@@ -0,0 +1,16 @@
+import type { SmartDocument, SmartSelection } from "../types.js";
+import type { AnnotationRange } from "../annotations/types.js";
+/**
+ * Builds the AnnotationRange a new comment thread should anchor to from the
+ * editor's current selection - the reverse direction of
+ * `resolveAnnotationRange` (AnnotationRange -> SmartRange). `resolvePos`'s
+ * `nodeId` is exactly the id `resolveAnnotationRange`'s `resolveEndpoint`
+ * expects for an offset-bearing endpoint (the owning node, not a text
+ * node), so no separate id-lookup mechanism is needed here.
+ *
+ * Returns null for a collapsed selection (nothing to attach a comment to)
+ * or a "none" selection (nothing selected at all). Every other selection
+ * type - text, node, cell - resolves the same way, since `SmartPos`/
+ * `resolvePos` already treat structural and inline owners uniformly.
+ */
+export declare const commentRangeFromSelection: (document: SmartDocument, selection: SmartSelection) => AnnotationRange | null;

package/dist/foundation/comments/fromSelection.js

@@ -0,0 +1,24 @@
+import { comparePos, resolvePos, selectionRange } from "../positions.js";
+/**
+ * Builds the AnnotationRange a new comment thread should anchor to from the
+ * editor's current selection - the reverse direction of
+ * `resolveAnnotationRange` (AnnotationRange -> SmartRange). `resolvePos`'s
+ * `nodeId` is exactly the id `resolveAnnotationRange`'s `resolveEndpoint`
+ * expects for an offset-bearing endpoint (the owning node, not a text
+ * node), so no separate id-lookup mechanism is needed here.
+ *
+ * Returns null for a collapsed selection (nothing to attach a comment to)
+ * or a "none" selection (nothing selected at all). Every other selection
+ * type - text, node, cell - resolves the same way, since `SmartPos`/
+ * `resolvePos` already treat structural and inline owners uniformly.
+ */
+export const commentRangeFromSelection = (document, selection) => {
+    if (selection.type === "none")
+        return null;
+    const { from, to } = selectionRange(selection);
+    if (comparePos(from, to) === 0)
+        return null;
+    const start = resolvePos(document, from);
+    const end = resolvePos(document, to);
+    return { startId: start.nodeId, startOffset: from.offset, endId: end.nodeId, endOffset: to.offset };
+};

package/dist/foundation/comments/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./rebase.js";
+export * from "./fromSelection.js";

package/dist/foundation/comments/index.js

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./rebase.js";
+export * from "./fromSelection.js";

package/dist/foundation/comments/rebase.d.ts

@@ -0,0 +1,31 @@
+import type { SmartDocument, SmartSchema, SmartTransaction } from "../types.js";
+import type { MergeOrphanPolicy } from "../annotations/types.js";
+import type { CommentThread } from "./types.js";
+/**
+ * Comments must never silently disappear from a merge the way a caller
+ * might reasonably choose for some other annotation consumer - a lost
+ * comment is lost user-authored text, not just a lost position. Tries the
+ * standard snap-to-survivor policy first; if there's genuinely no
+ * preceding sibling to snap to (a real edge case `defaultMergeOrphanPolicy`
+ * itself can return null for), keeps the range's ids exactly as they were
+ * rather than dropping it. That range will simply fail to resolve once
+ * the retired id is gone from the document - the same "orphaned, not
+ * lost" state a `removeNode` with no `mergedInto` already produces
+ * naturally - so the thread's data survives and the UI can detect and
+ * surface "comment on deleted content" by the standard resolve-and-check
+ * pattern, not a special stored flag.
+ */
+export declare const neverOrphanCommentPolicy: (document: SmartDocument) => MergeOrphanPolicy;
+/**
+ * Rebases every thread's range through one committed transaction, in
+ * operation order. `rebaseAnnotationRange`/`rebaseAnnotationRangeThroughOperations`
+ * need a fresh `PositionLookup` resolved against the document as it
+ * existed immediately before each individual operation (not the whole
+ * transaction) - since a caller subscribing to a runtime's transaction
+ * stream only receives the transaction after it has fully committed, this
+ * reconstructs those intermediate states itself by replaying operations
+ * one at a time against a running copy, starting from `beforeDocument`
+ * (whatever the document was immediately before this transaction, i.e.
+ * exactly what the caller already had from the previous change event).
+ */
+export declare const rebaseCommentThreadsThroughTransaction: (threads: readonly CommentThread[], beforeDocument: SmartDocument, transaction: SmartTransaction, schema: SmartSchema) => readonly CommentThread[];

package/dist/foundation/comments/rebase.js

@@ -0,0 +1,43 @@
+import { applyOperation } from "../operations.js";
+import { createScopeIndex } from "../scope/resolveScope.js";
+import { defaultMergeOrphanPolicy, rebaseAnnotationRange } from "../annotations/range.js";
+/**
+ * Comments must never silently disappear from a merge the way a caller
+ * might reasonably choose for some other annotation consumer - a lost
+ * comment is lost user-authored text, not just a lost position. Tries the
+ * standard snap-to-survivor policy first; if there's genuinely no
+ * preceding sibling to snap to (a real edge case `defaultMergeOrphanPolicy`
+ * itself can return null for), keeps the range's ids exactly as they were
+ * rather than dropping it. That range will simply fail to resolve once
+ * the retired id is gone from the document - the same "orphaned, not
+ * lost" state a `removeNode` with no `mergedInto` already produces
+ * naturally - so the thread's data survives and the UI can detect and
+ * surface "comment on deleted content" by the standard resolve-and-check
+ * pattern, not a special stored flag.
+ */
+export const neverOrphanCommentPolicy = (document) => (range, operation, positions) => defaultMergeOrphanPolicy(document)(range, operation, positions) ?? range;
+/**
+ * Rebases every thread's range through one committed transaction, in
+ * operation order. `rebaseAnnotationRange`/`rebaseAnnotationRangeThroughOperations`
+ * need a fresh `PositionLookup` resolved against the document as it
+ * existed immediately before each individual operation (not the whole
+ * transaction) - since a caller subscribing to a runtime's transaction
+ * stream only receives the transaction after it has fully committed, this
+ * reconstructs those intermediate states itself by replaying operations
+ * one at a time against a running copy, starting from `beforeDocument`
+ * (whatever the document was immediately before this transaction, i.e.
+ * exactly what the caller already had from the previous change event).
+ */
+export const rebaseCommentThreadsThroughTransaction = (threads, beforeDocument, transaction, schema) => {
+    if (!threads.length || !transaction.operations.length)
+        return threads;
+    let runningDocument = beforeDocument;
+    let ranges = threads.map((thread) => thread.range);
+    for (const operation of transaction.operations) {
+        const positions = createScopeIndex().positions(runningDocument, schema);
+        const onOrphan = neverOrphanCommentPolicy(runningDocument);
+        ranges = ranges.map((range) => rebaseAnnotationRange(range, operation, positions, onOrphan) ?? range);
+        runningDocument = applyOperation(runningDocument, operation);
+    }
+    return threads.map((thread, index) => ranges[index] === thread.range ? thread : { ...thread, range: ranges[index] });
+};

package/dist/foundation/comments/types.d.ts

@@ -0,0 +1,37 @@
+import type { AnnotationRange } from "../annotations/types.js";
+/**
+ * One message in a comment thread. The first reply (index 0) is the
+ * thread's opening comment, not a distinct "comment" type layered on top -
+ * a thread with exactly one reply is what most people mean by "a comment,"
+ * and every subsequent reply is a normal continuation of the same
+ * conversation. Modeling it as one list, not "comment + replies[]", means
+ * there is exactly one code path for "add a message to a thread" instead
+ * of two slightly-different ones.
+ */
+export interface CommentReply {
+    readonly id: string;
+    readonly authorId: string;
+    readonly text: string;
+    readonly createdAt: number;
+}
+/**
+ * A comment thread anchored to a Phase 8c `AnnotationRange`. Threaded
+ * replies (single flat list, see `CommentReply`'s own doc comment);
+ * resolution is thread-level state (`resolved: true`), not deletion - a
+ * resolved thread's replies remain in `list()` for a host that wants to
+ * show a resolved-comments history, and only an explicit `remove()` call
+ * (a distinct, more destructive action) actually discards a thread.
+ *
+ * `range` is always a well-formed `AnnotationRange` - never null, even
+ * once the ids it names no longer exist in the document (see
+ * `rebase.ts`'s orphan handling). Whether a thread is currently anchored
+ * to real content is derived on demand via `resolveAnnotationRange`,
+ * exactly like every other `AnnotationRange` consumer - not stored as a
+ * separate flag that could drift out of sync with the document.
+ */
+export interface CommentThread {
+    readonly id: string;
+    readonly range: AnnotationRange;
+    readonly resolved: boolean;
+    readonly replies: readonly CommentReply[];
+}

package/dist/foundation/comments/types.js

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

package/dist/foundation/diff/documentDiff.d.ts

@@ -0,0 +1,12 @@
+import type { SmartDocument, SmartSchema } from "../types.js";
+import type { DocumentDiff } from "./types.js";
+/**
+ * Every `SmartElementNode` keeps a stable id across split/merge/move/type-
+ * change/undo (Phase 8c collab-readiness gate, assertion 1). That turns the
+ * structural half of a document diff into a hash-map join - id present in
+ * both/only-before/only-after - instead of a generic tree-alignment problem
+ * a Myers/patience-style algorithm would otherwise be needed to solve.
+ * `SmartTextNode` has no id, so text content is the one place a real
+ * (word-level, see textDiff.ts) diff algorithm is still needed.
+ */
+export declare const diffDocuments: (before: SmartDocument, after: SmartDocument, schema: SmartSchema) => DocumentDiff;