@voithos-labs/aragonite 0.10.3 → 0.10.7

package/dist/tree-operations/unshare.d.ts

@@ -1,9 +1,8 @@
 /**
- * Copy-path-on-write for structural-sharing undo: unshare the root→target spine before
- * any in-place write — undo entries still reference shared nodes. Copies are SHALLOW, so
- * unshare deeper wherever you write. Write-then-re-read: after assigning a copy into the
- * live tree, re-read it through the tree — the `$state` proxy wrapper is canonical, not
- * the copy you held. Also the one sanctioned view→mutable door (`core/node-views.ts`).
+ * Copy before write: undo entries reference the live tree's nodes, so every node from the root
+ * down to the target is copied before an in-place write, and the functions here are the only way
+ * from a read-only view to a writable node. Copies are shallow, so copy deeper wherever you write,
+ * and re-read a copy through the tree after assigning it, since the `$state` proxy is the node.
  */
 import type { CstNode } from '../core/nodes';
 import type { NodeParentView, NodeView } from '../core/node-views';
@@ -11,29 +10,26 @@ import type { SharingState } from './sharing';
 import type { NodeParent } from './node-primitives';
 import type { ChildRawChange } from '../schema/child-spans';
 /**
- * The copy-on-write spine walk, returning the owned chain outermost-first. `assertInRange`
- * fires G1.22 for the strict `ensureUnsharedPath` caller and stays silent for tolerant rebuild
- * passes, which legitimately hand short paths; the walk stops at the first gap either way.
+ * The copy-on-write walk down `path`, outermost first. `assertInRange` fails an index off the end
+ * (G1.22); rebuild passes turn it off because they hand in short paths on purpose.
  */
 export declare function walkUnsharing(root: NodeParentView, path: number[], sharing: SharingState, assertInRange: boolean): CstNode[];
 /**
  * Unshare every node along `path` from `root`; returns the chain outermost-first. The caller
- * owns `root.children` (live document, or a commit ceremony's array copy).
+ * owns `root.children` (the live document, or a commit sequence's array copy).
  */
 export declare function ensureUnsharedPath(root: NodeParentView, path: number[], sharing: SharingState): CstNode[];
 /** Unshare one direct child of an already-unshared parent, or of a caller-owned `{ children }`. */
 export declare function ensureUnsharedChild(parent: CstNode | NodeParent, index: number, sharing: SharingState): CstNode;
 /**
- * Standalone copy for a node being MOVED out of a parent the snapshot keeps: the caller attaches
- * the copy, the original stays put. An unshared input passes through as live-tree-owned.
+ * A standalone copy of a node moving out of a parent the snapshot keeps, for the caller to attach;
+ * a node no snapshot shares passes through as it is.
  */
 export declare function ensureUnsharedNode(node: NodeView, sharing: SharingState): CstNode;
 /** Unshare every direct child of an owned parent (e.g. table rows before a whole-table rebuild). */
 export declare function ensureUnsharedChildren(parent: CstNode, sharing: SharingState): void;
 /** Deep-unshare an owned node's subtree, for small bounded subtrees written at arbitrary depth. */
 export declare function ensureUnsharedSubtree(node: CstNode, sharing: SharingState): void;
-/**
- * Rebuild one owned container's raw. A grid rebuild rewrites its children's raw, so a grid's
- * children are unshared first, keyed off `containerContract` rather than a `table` kind test.
- */
+/** Rebuild one owned container's raw. A grid rebuild rewrites its children's raw, so a grid's
+ *  children are unshared first. */
 export declare function rebuildOwnedContainer(node: CstNode, sharing: SharingState, changed?: ChildRawChange): void;

package/dist/tree-operations/unshare.js

@@ -1,7 +1,7 @@
 import { assertInvariant } from '../assert';
 import { checkCloneSafeMetadata } from '../invariants/node-shape';
 import { rebuildContainerRawIfContainer } from '../schema/container-raw';
-import { getBlockKindDescriptor } from '../schema/block-kind-descriptor';
+import { getBlockKindDescriptor, isGridDescriptor } from '../schema/block-kind-descriptor';
 import { cloneMetadata } from './clone';
 function copyNode(node, sharing) {
     const copy = { ...node };
@@ -20,13 +20,13 @@ function copyNode(node, sharing) {
     return copy;
 }
 /**
- * The copy-on-write spine walk, returning the owned chain outermost-first. `assertInRange`
- * fires G1.22 for the strict `ensureUnsharedPath` caller and stays silent for tolerant rebuild
- * passes, which legitimately hand short paths; the walk stops at the first gap either way.
+ * The copy-on-write walk down `path`, outermost first. `assertInRange` fails an index off the end
+ * (G1.22); rebuild passes turn it off because they hand in short paths on purpose.
  */
 export function walkUnsharing(root, path, sharing, assertInRange) {
     const chain = [];
-    // Root is the live document or a ceremony-owned array — writable by contract (file header).
+    // The root is the live document or an array the commit sequence owns, writable by contract
+    // (file header).
     let parentChildren = root.children;
     for (const index of path) {
         let node = parentChildren[index];
@@ -37,7 +37,7 @@ export function walkUnsharing(root, path, sharing, assertInRange) {
             break;
         if (sharing.isShared(node)) {
             parentChildren[index] = copyNode(node, sharing);
-            // Write-then-re-read (file header).
+            // Write, then re-read through the tree (file header).
             node = parentChildren[index];
         }
         chain.push(node);
@@ -47,7 +47,7 @@ export function walkUnsharing(root, path, sharing, assertInRange) {
 }
 /**
  * Unshare every node along `path` from `root`; returns the chain outermost-first. The caller
- * owns `root.children` (live document, or a commit ceremony's array copy).
+ * owns `root.children` (the live document, or a commit sequence's array copy).
  */
 export function ensureUnsharedPath(root, path, sharing) {
     return walkUnsharing(root, path, sharing, true);
@@ -55,18 +55,18 @@ export function ensureUnsharedPath(root, path, sharing) {
 /** Unshare one direct child of an already-unshared parent, or of a caller-owned `{ children }`. */
 export function ensureUnsharedChild(parent, index, sharing) {
     const child = parent.children[index];
-    // G1.22: an index off the end is a caller bug, failed here rather than epoch-dependently
-    // inside `isShared`.
+    // An index off the end is a caller bug (G1.22), failed here rather than inside `isShared`,
+    // where it would depend on the generation counter.
     assertInvariant('unshare-path-in-range', () => child ? null : { code: 'unshare-path', message: `child index ${index} out of range` });
     if (!child || !sharing.isShared(child))
         return child;
     parent.children[index] = copyNode(child, sharing);
-    // Write-then-re-read (file header).
+    // Write, then re-read through the tree (file header).
     return parent.children[index];
 }
 /**
- * Standalone copy for a node being MOVED out of a parent the snapshot keeps: the caller attaches
- * the copy, the original stays put. An unshared input passes through as live-tree-owned.
+ * A standalone copy of a node moving out of a parent the snapshot keeps, for the caller to attach;
+ * a node no snapshot shares passes through as it is.
  */
 export function ensureUnsharedNode(node, sharing) {
     return sharing.isShared(node) ? copyNode(node, sharing) : node;
@@ -85,12 +85,10 @@ export function ensureUnsharedSubtree(node, sharing) {
     }
 }
 // ── Sharing-aware raw rebuild ───────────────────────────────────────────────
-/**
- * Rebuild one owned container's raw. A grid rebuild rewrites its children's raw, so a grid's
- * children are unshared first, keyed off `containerContract` rather than a `table` kind test.
- */
+/** Rebuild one owned container's raw. A grid rebuild rewrites its children's raw, so a grid's
+ *  children are unshared first. */
 export function rebuildOwnedContainer(node, sharing, changed) {
-    if (getBlockKindDescriptor(node.kind).containerContract === 'grid') {
+    if (isGridDescriptor(getBlockKindDescriptor(node.kind))) {
         ensureUnsharedChildren(node, sharing);
     }
     rebuildContainerRawIfContainer(node, changed);

package/dist/undo/manager.js

@@ -4,7 +4,7 @@ export function createUndoManager() {
     const redoStack = [];
     return {
         push(entry) {
-            // Stored as-is: the caller builds entries safe to hold.
+            // Stored as is: the caller builds entries that are safe to keep.
             undoStack.push(entry);
             if (undoStack.length > MAX_UNDO)
                 undoStack.shift();

package/dist/undo/types.d.ts

@@ -16,9 +16,9 @@ export declare function isGapSelection(selection: EditorSelection | GapCaretSele
 export interface UndoEntry {
     snapshot: Document;
     blockIds: string[];
-    /** Effective selection at push. See docs/design/editor.md § Undo / redo. */
+    /** Effective selection at push (`docs/design/editor.md` § Undo / redo). */
     selection: EditorSelection | GapCaretSelection;
-    /** DEV-only digest of `snapshot` at push; restore verifies no mutation wrote through a shared node. */
+    /** Dev-only digest of `snapshot` at push; restore verifies no mutation wrote through a shared node. */
     integrity?: number;
 }
 export interface UndoManager {