svedit 0.8.0 → 0.10.0

package/dist/Svedit.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Svedit.svelte.d.ts","sourceRoot":"","sources":["../src/lib/Svedit.svelte.js"],"names":[],"mappings":";;;;;;;AA60CA;;eAAqD;iCAhzC1C,cAAc"}
+{"version":3,"file":"Svedit.svelte.d.ts","sourceRoot":"","sources":["../src/lib/Svedit.svelte.js"],"names":[],"mappings":";;;;;;;AAigDA;;eAAqD;iCAh+C1C,cAAc"}

package/dist/Transaction.svelte.d.ts

@@ -34,6 +34,12 @@ export default class Transaction {
     /** @type {Record<string, any>[]} */
     inverse_ops: Record<string, any>[];
     selection_before: Selection;
+    /** @type {NodeId[]} */
+    created_node_ids: NodeId[];
+    /** @type {NodeId[]} */
+    modified_node_ids: NodeId[];
+    /** @type {NodeId[]} */
+    deleted_node_ids: NodeId[];
     /**
      * Gets a value from the document at the specified path.
      *
@@ -107,6 +113,12 @@ export default class Transaction {
      * @private
      */
     private _apply_op;
+    /**
+     * @param {NodeId[]} node_ids
+     * @param {NodeId} node_id
+     * @private
+     */
+    private _track_node_id;
     /**
      * Sets a property of a node to a new value.
      *
@@ -129,9 +141,9 @@ export default class Transaction {
      * Creates a new node in the document.
      *
      * The node must have a valid id and must not already exist in the document.
-     * The node is validated against the document schema before creation.
+     * Omitted properties with schema defaults are filled before validation.
      *
-     * @param {any} node - The node object to create (must include id, type, and other properties)
+     * @param {any} node - The node object to create (must include id, type, and required properties)
      * @returns {Transaction} This transaction instance for method chaining
      * @throws {Error} If the node ID is invalid or if the node already exists
      *
@@ -150,6 +162,13 @@ export default class Transaction {
      *
      * The node's current state is captured for undo support before deletion.
      *
+     * NOTE: This is a force-delete and intentionally does NOT check whether
+     * the node is still referenced from elsewhere — callers (e.g.
+     * `annotate_text`) sometimes need to remove a node while a stale
+     * reference to it still exists in the property they are about to update.
+     * For ref-count-aware cleanup, see how `set` calls
+     * `_cascade_delete_unreferenced_nodes`.
+     *
      * @param {any} id - The ID of the node to delete
      * @returns {Transaction} This transaction instance for method chaining
      *
@@ -197,13 +216,13 @@ export default class Transaction {
      */
     annotate_text(annotation_type: any, annotation_properties: any): Transaction;
     /**
-     * Deletes the currently selected text or nodes.
+     * Deletes the currently selected text, node, or property.
      *
      * Behavior depends on selection type:
      * - For node selections: Removes selected nodes and cascades deletion of unreferenced nodes
      * - For text selections: Removes selected text and adjusts annotations accordingly
      * - For collapsed selections: Deletes the previous character/node (backward) or next character/node (forward)
-     * - Property selections are ignored: Those are best handled handled via commands + keyboard shortcuts.
+     * - For property selections: Delegates to the config's handle_property_deletion hook
      *
      * @param {'backward' | 'forward'} [direction] - Direction of deletion for collapsed selections
      * @returns {Transaction} This transaction instance for method chaining
@@ -259,8 +278,8 @@ export default class Transaction {
 }
 import type { DocumentSchema } from './types.d.js';
 import type { Selection } from './types.d.js';
-import type { DocumentPath } from './types.d.js';
 import type { NodeId } from './types.d.js';
+import type { DocumentPath } from './types.d.js';
 import type { Annotation } from './types.d.js';
 import type { Document } from './types.d.js';
 //# sourceMappingURL=Transaction.svelte.d.ts.map

package/dist/Transaction.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Transaction.svelte.d.ts","sourceRoot":"","sources":["../src/lib/Transaction.svelte.js"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;;GAcG;AACH;IACC;;;;;;;OAOG;IACH,oBALW,cAAc,OACd,QAAQ,aACR,SAAS,GAAG,IAAI,UAChB,MAAM,EAgBhB;IAbA,uBAAoB;IACpB,qBAAqB;IACrB,KADW,MAAM,CACH;IACd,wBAAwB;IACxB,WADW,SAAS,CACM;IAC1B,YAAoB;IAEpB,oCAAoC;IACpC,KADW,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CACnB;IACb,oCAAoC;IACpC,aADW,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CACX;IAErB,4BAAiC;IAGlC;;;;;OAKG;IACH,UAHW,YAAY,GAAC,MAAM,GACjB,GAAG,CAIf;IAED;;;;;;OAMG;IACH,oBAJW,MAAM,YACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;OAKG;IACH,WAHW,GAAG,GACD,OAAO,GAAC,MAAM,GAAC,YAAY,CAIvC;IAED;;;;;OAKG;IACH,cAHW,YAAY,GACV;QAAC,IAAI,EAAE,UAAU,GAAC,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;KAAC,CAIzD;IAED;;;;OAIG;IACH,eAFa,MAAM,CAIlB;IAED;;;;;OAKG;IACH,oBAHW,GAAG,QAKb;IAED;;;;;OAKG;IACH,8BAHW,MAAM,GACJ,MAAM,EAAE,CAKpB;IAED;;;;OAIG;IACH,kCAFa,MAAM,EAAE,CAOpB;IAED;;;;;;OAMG;IACH,oCAHW,MAAM,GACJ,UAAU,GAAC,IAAI,CAI3B;IAED;;;;;OAKG;IACH,kBAEC;IAED;;;;;;;;;;;;;;;OAeG;IACH,UAVW,YAAY,SACZ,GAAG,GACD,WAAW,CAmDvB;IAKD,qCAsDC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAbW,GAAG,GACD,WAAW,CAyBvB;IAED;;;;;;;;;;;;OAYG;IACH,WARW,GAAG,GACD,WAAW,CAsBvB;IAED;;;;;;OAMG;IACH,yBAJW,SAAS,GACP,WAAW,CAOvB;IAED;;;;;;OAMG;IACH,4BAEC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,+BAbW,GAAG,yBACH,GAAG,GACD,WAAW,CA+DvB;IAED;;;;;;;;;;;OAWG;IACH,6BAHW,UAAU,GAAG,SAAS,GACpB,WAAW,CA0IvB;IAED;;;;;;;;OAQG;IACH,uBAHW,MAAM,EAAE,GACN,WAAW,CA2BvB;IAED;;;;;;;;;;;;OAYG;IACH,2BALW,MAAM,+BAEN,MAAM,GACJ,WAAW,CA2FvB;IAED;;;;;;;;;OASG;IACH,2CAgCC;IAED;;;;;;;;;;OAUG;IACH,4CAOC;CACD;oCAlyByF,cAAc;+BAAd,cAAc;kCAAd,cAAc;4BAAd,cAAc;gCAAd,cAAc;8BAAd,cAAc"}
+{"version":3,"file":"Transaction.svelte.d.ts","sourceRoot":"","sources":["../src/lib/Transaction.svelte.js"],"names":[],"mappings":"AA0BA;;;;;;;;;;;;;;GAcG;AACH;IACC;;;;;;;OAOG;IACH,oBALW,cAAc,OACd,QAAQ,aACR,SAAS,GAAG,IAAI,UAChB,MAAM,EAuBhB;IApBA,uBAAoB;IACpB,qBAAqB;IACrB,KADW,MAAM,CACH;IACd,wBAAwB;IACxB,WADW,SAAS,CACM;IAC1B,YAAoB;IAEpB,oCAAoC;IACpC,KADW,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CACnB;IACb,oCAAoC;IACpC,aADW,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CACX;IAErB,4BAAiC;IAEjC,uBAAuB;IACvB,kBADW,MAAM,EAAE,CACO;IAC1B,uBAAuB;IACvB,mBADW,MAAM,EAAE,CACQ;IAC3B,uBAAuB;IACvB,kBADW,MAAM,EAAE,CACO;IAG3B;;;;;OAKG;IACH,UAHW,YAAY,GAAC,MAAM,GACjB,GAAG,CAIf;IAED;;;;;;OAMG;IACH,oBAJW,MAAM,YACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;OAKG;IACH,WAHW,GAAG,GACD,OAAO,GAAC,MAAM,GAAC,YAAY,CAIvC;IAED;;;;;OAKG;IACH,cAHW,YAAY,GACV;QAAC,IAAI,EAAE,UAAU,GAAC,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;KAAC,CAIzD;IAED;;;;OAIG;IACH,eAFa,MAAM,CAIlB;IAED;;;;;OAKG;IACH,oBAHW,GAAG,QAKb;IAGD;;;;;OAKG;IACH,8BAHW,MAAM,GACJ,MAAM,EAAE,CAKpB;IAED;;;;OAIG;IACH,kCAFa,MAAM,EAAE,CAOpB;IAED;;;;;;OAMG;IACH,oCAHW,MAAM,GACJ,UAAU,GAAC,IAAI,CAI3B;IAED;;;;;OAKG;IACH,kBAEC;IAED;;;;OAIG;IACH,uBAEC;IAED;;;;;;;;;;;;;;;OAeG;IACH,UAVW,YAAY,SACZ,GAAG,GACD,WAAW,CA8DvB;IAKD,qCAkCC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAbW,GAAG,GACD,WAAW,CA4BvB;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,WARW,GAAG,GACD,WAAW,CAuBvB;IAED;;;;;;OAMG;IACH,yBAJW,SAAS,GACP,WAAW,CAOvB;IAED;;;;;;OAMG;IACH,4BAEC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,+BAbW,GAAG,yBACH,GAAG,GACD,WAAW,CA+EvB;IAED;;;;;;;;;;;OAWG;IACH,6BAHW,UAAU,GAAG,SAAS,GACpB,WAAW,CA8IvB;IAED;;;;;;;;OAQG;IACH,uBAHW,MAAM,EAAE,GACN,WAAW,CA2BvB;IAED;;;;;;;;;;;;OAYG;IACH,2BALW,MAAM,+BAEN,MAAM,GACJ,WAAW,CA2FvB;IAED;;;;;;;;;OASG;IACH,2CAiCC;IAED;;;;;;;;;;OAUG;IACH,4CAOC;CACD;oCA50ByF,cAAc;+BAAd,cAAc;4BAAd,cAAc;kCAAd,cAAc;gCAAd,cAAc;8BAAd,cAAc"}

package/dist/Transaction.svelte.js

@@ -18,8 +18,10 @@ import {
 	apply_op,
 	count_references_excluding_deleted,
 	validate_node,
+	fill_node_defaults,
 	get_active_annotation,
-	validate_selection
+	validate_selection,
+	can_switch_annotation_type
 } from './doc_utils.js';
 
 /**
@@ -60,6 +62,13 @@ export default class Transaction {
 		this.inverse_ops = [];
 		// Remember the selection before the transaction started
 		this.selection_before = selection;
+
+		/** @type {NodeId[]} */
+		this.created_node_ids = [];
+		/** @type {NodeId[]} */
+		this.modified_node_ids = [];
+		/** @type {NodeId[]} */
+		this.deleted_node_ids = [];
 	}
 
 	/**
@@ -119,9 +128,10 @@ export default class Transaction {
 	 * @throws {Error} Throws if the node is invalid
 	 */
 	validate_node(node) {
-		validate_node(node, this.schema, this.doc.nodes);
+		validate_node(node, this.schema, this.doc.nodes, { require_references: false });
 	}
 
+
 	/**
 	 * Gets all nodes referenced by a given node (recursively).
 	 *
@@ -166,6 +176,15 @@ export default class Transaction {
 		this.doc = apply_op(this.doc, op);
 	}
 
+	/**
+	 * @param {NodeId[]} node_ids
+	 * @param {NodeId} node_id
+	 * @private
+	 */
+	_track_node_id(node_ids, node_id) {
+		if (!node_ids.includes(node_id)) node_ids.push(node_id);
+	}
+
 	/**
 	 * Sets a property of a node to a new value.
 	 *
@@ -183,6 +202,13 @@ export default class Transaction {
 	 * ```
 	 */
 	set(path, value) {
+		const path_info = this.inspect(path);
+		if (path_info?.kind !== 'property') {
+			throw new Error(
+				`Transaction.set requires a path that points to a property, got ${JSON.stringify(path)}`
+			);
+		}
+
 		const node = this.get(path.slice(0, -1));
 
 		// Turns ["page_1", "body", "0", "description"]
@@ -192,9 +218,6 @@ export default class Transaction {
 
 		// Just to be sure, make a deep copy of the old value
 		const property_key = path.at(-1);
-		if (property_key === undefined) {
-			throw new Error('Invalid path: cannot get property key');
-		}
 		const property_key_str = String(property_key);
 		const previous_value = structuredClone($state.snapshot(node[property_key_str]));
 
@@ -218,10 +241,17 @@ export default class Transaction {
 		this.ops.push(op);
 		this.inverse_ops.push(['set', normalized_path, previous_value]);
 		this._apply_op(op);
-
-		for (const removed_node_id of removed_node_ids) {
-			// NOTE: This implicitly deletes childnodes as well, given that they are no longer referenced.
-			this.delete(removed_node_id);
+		this._track_node_id(this.modified_node_ids, node.id);
+
+		// Garbage-collect nodes whose only reference was via this property.
+		// We must use a ref-count-aware sweep instead of unconditional deletion
+		// because a node ID removed from this array may still be referenced
+		// elsewhere — either from a pre-existing reference (e.g. shared nodes)
+		// or from a node created earlier in the same transaction (the
+		// wrap-in-group pattern: create a wrapper that points at the children,
+		// then set the parent array to drop them).
+		if (removed_node_ids.length > 0) {
+			this._cascade_delete_unreferenced_nodes(removed_node_ids);
 		}
 
 		return this;
@@ -238,48 +268,28 @@ export default class Transaction {
 		for (const node of depth_first_nodes) {
 			const new_id = this.generate_id();
 			id_map[node.id] = new_id;
-			const new_node = { ...node, id: new_id };
+			let new_node = { ...node, id: new_id };
 			const node_schema = this.schema[node.type];
 
 			// Update all property references to use new IDs
 			for (const [property_name, property_definition] of Object.entries(node_schema.properties)) {
 				const prop_type = property_definition.type;
-				const value = node[property_name];
-
-				// Apply default values
-				if (prop_type === 'node_array') {
-					// [] is the default value for node arrays
-					new_node[property_name] = Array.isArray(value)
-						? value.map((ref_id) => id_map[ref_id])
-						: [];
-				} else if (prop_type === 'node') {
-					// null is the default value for node references
-					new_node[property_name] = typeof value === 'string' ? id_map[value] : null;
-				} else if (prop_type === 'annotated_text') {
-					if (value) {
-						const annotations = value.annotations.map((annotation) => {
-							const { start_offset, end_offset, node_id } = annotation;
-							return { start_offset, end_offset, node_id: id_map[node_id] || node_id };
-						});
-						new_node[property_name] = { text: value.text, annotations };
-					} else {
-						new_node[property_name] = { text: '', annotations: [] };
-					}
-				} else if (prop_type === 'string') {
-					new_node[property_name] = value ?? property_definition.default ?? '';
-				} else if (prop_type === 'integer') {
-					new_node[property_name] = value ?? property_definition.default ?? 0;
-				} else if (prop_type === 'number') {
-					new_node[property_name] = value ?? property_definition.default ?? 0;
-				} else if (prop_type === 'boolean') {
-					new_node[property_name] = value ?? property_definition.default ?? false;
-				} else if (['integer_array', 'number_array'].includes(prop_type)) {
-					new_node[property_name] = value ?? property_definition.default ?? [];
-				} else if (prop_type === 'string_array') {
-					new_node[property_name] = value ?? property_definition.default ?? [];
+				const value = new_node[property_name];
+
+				if (prop_type === 'node_array' && Array.isArray(value)) {
+					new_node[property_name] = value.map((ref_id) => id_map[ref_id]);
+				} else if (prop_type === 'node' && typeof value === 'string') {
+					new_node[property_name] = id_map[value];
+				} else if (prop_type === 'annotated_text' && value) {
+					const annotations = value.annotations.map((annotation) => {
+						const { start_offset, end_offset, node_id } = annotation;
+						return { start_offset, end_offset, node_id: id_map[node_id] || node_id };
+					});
+					new_node[property_name] = { text: value.text, annotations };
 				}
 			}
 
+			new_node = fill_node_defaults(new_node, this.schema);
 			this.create(new_node);
 		}
 
@@ -290,9 +300,9 @@ export default class Transaction {
 	 * Creates a new node in the document.
 	 *
 	 * The node must have a valid id and must not already exist in the document.
-	 * The node is validated against the document schema before creation.
+	 * Omitted properties with schema defaults are filled before validation.
 	 *
-	 * @param {any} node - The node object to create (must include id, type, and other properties)
+	 * @param {any} node - The node object to create (must include id, type, and required properties)
 	 * @returns {Transaction} This transaction instance for method chaining
 	 * @throws {Error} If the node ID is invalid or if the node already exists
 	 *
@@ -306,17 +316,20 @@ export default class Transaction {
 	 * ```
 	 */
 	create(node) {
+		const node_with_defaults = fill_node_defaults(node, this.schema);
+
 		// Validate node against schema
-		this.validate_node(node);
+		this.validate_node(node_with_defaults);
 
-		if (this.get(node.id)) {
-			throw new Error('Node with id ' + node.id + ' already exists');
+		if (this.get(node_with_defaults.id)) {
+			throw new Error('Node with id ' + node_with_defaults.id + ' already exists');
 		}
 
-		const op = ['create', node];
+		const op = ['create', node_with_defaults];
 		this.ops.push(op);
-		this.inverse_ops.push(['delete', node.id]);
+		this.inverse_ops.push(['delete', node_with_defaults.id]);
 		this._apply_op(op);
+		this._track_node_id(this.created_node_ids, node_with_defaults.id);
 		return this;
 	}
 
@@ -325,6 +338,13 @@ export default class Transaction {
 	 *
 	 * The node's current state is captured for undo support before deletion.
 	 *
+	 * NOTE: This is a force-delete and intentionally does NOT check whether
+	 * the node is still referenced from elsewhere — callers (e.g.
+	 * `annotate_text`) sometimes need to remove a node while a stale
+	 * reference to it still exists in the property they are about to update.
+	 * For ref-count-aware cleanup, see how `set` calls
+	 * `_cascade_delete_unreferenced_nodes`.
+	 *
 	 * @param {any} id - The ID of the node to delete
 	 * @returns {Transaction} This transaction instance for method chaining
 	 *
@@ -345,6 +365,7 @@ export default class Transaction {
 		this.ops.push(op);
 		this.inverse_ops.push(['create', previous_value]);
 		this._apply_op(op);
+		this._track_node_id(this.deleted_node_ids, id);
 		// Cascade delete any nodes that are now orphaned after removing this node
 		this._cascade_delete_unreferenced_nodes(referenced_nodes);
 		return this;
@@ -402,6 +423,8 @@ export default class Transaction {
 		const annotations = annotated_text.annotations;
 		const existing_annotation = this.active_annotation();
 		const existing_annotation_same_type = this.active_annotation(annotation_type);
+		const has_annotation_properties =
+			annotation_properties && Object.keys(annotation_properties).length > 0;
 
 		if (existing_annotation) {
 			// If there's an existing annotation of the same type, remove it
@@ -417,16 +440,30 @@ export default class Transaction {
 					annotations.splice(index, 1);
 				}
 			} else {
-				// If there's an annotation of a different type, don't add a new one
+				const existing_annotation_node = this.get(existing_annotation.node_id);
+				const can_switch_annotation =
+					!has_annotation_properties &&
+					this.available_annotation_types.includes(annotation_type) &&
+					can_switch_annotation_type(
+						this.schema,
+						existing_annotation_node,
+						annotation_type
+					);
+
+				if (can_switch_annotation) {
+					this.set([existing_annotation.node_id, 'type'], annotation_type);
+					return this;
+				}
+
+				// If there's an annotation of a different incompatible type, don't add a new one
 				return this;
 			}
 		} else {
 			if (is_selection_collapsed(this.selection)) {
-				console.log('Annotations can only be added to expanded text selections.');
 				return this;
 			}
 			if (!this.available_annotation_types.includes(annotation_type)) {
-				console.log(`Annotation type ${annotation_type} is not allowed here.`);
+				console.warn(`Annotation type ${annotation_type} is not allowed here.`);
 				return this;
 			}
 			const new_annotation_node = {
@@ -449,19 +486,25 @@ export default class Transaction {
 	}
 
 	/**
-	 * Deletes the currently selected text or nodes.
+	 * Deletes the currently selected text, node, or property.
 	 *
 	 * Behavior depends on selection type:
 	 * - For node selections: Removes selected nodes and cascades deletion of unreferenced nodes
 	 * - For text selections: Removes selected text and adjusts annotations accordingly
 	 * - For collapsed selections: Deletes the previous character/node (backward) or next character/node (forward)
-	 * - Property selections are ignored: Those are best handled handled via commands + keyboard shortcuts.
+	 * - For property selections: Delegates to the config's handle_property_deletion hook
 	 *
 	 * @param {'backward' | 'forward'} [direction] - Direction of deletion for collapsed selections
 	 * @returns {Transaction} This transaction instance for method chaining
 	 */
 	delete_selection(direction = 'backward') {
-		if (!this.selection || this.selection.type === 'property') return this;
+		if (!this.selection) return this;
+
+		if (this.selection.type === 'property') {
+			this.config.handle_property_deletion?.(this, this.selection.path);
+			return this;
+		}
+
 		const path = this.selection.path;
 
 		// Get the start and end indices for the selection
@@ -579,13 +622,11 @@ export default class Transaction {
 
 			text.annotations = new_annotations;
 
-			// Delete marked annotation nodes
-			for (const node_id of _deleted_nodes) {
-				this.delete(node_id);
-			}
-
 			this.set(path, text);
 
+			// Delete marked annotation nodes only if no other references remain.
+			this._cascade_delete_unreferenced_nodes(_deleted_nodes);
+
 			// Update the selection to the new caret position
 			this.selection = {
 				type: 'text',
@@ -778,6 +819,7 @@ export default class Transaction {
 				this.ops.push(op);
 				this.inverse_ops.push(['create', previous_value]);
 				this._apply_op(op);
+				this._track_node_id(this.deleted_node_ids, node_id);
 			}
 		}
 	}

package/dist/doc_utils.d.ts

@@ -3,10 +3,10 @@
  * Similar to your define_schema pattern but for document schemas.
  *
  * @template {Record<string, NodeSchema>} S
- * @param {S} schema - The document schema to validate
+ * @param {S & ValidateDocumentSchema<S>} schema - The document schema to validate
  * @returns {S} The same schema, but with type information preserved
  */
-export function define_document_schema<S extends Record<string, NodeSchema>>(schema: S): S;
+export function define_document_schema<S extends Record<string, NodeSchema>>(schema: S & ValidateDocumentSchema<S>): S;
 /**
  * Check if a string represents a valid primitive type.
  * @param {string} type - The type string to check
@@ -19,20 +19,61 @@ export function is_primitive_type(type: string): type is PrimitiveType;
  * @returns {string | null} The default node type, or null if none specified
  */
 export function get_default_node_type(property_definition: NodeProperty | NodeArrayProperty): string | null;
+/**
+ * Fill omitted properties with schema defaults and Svedit's built-in type defaults.
+ *
+ * This is a convenience helper for schema evolution, not a complete document
+ * migration system. Callers are still responsible for proper migrations when
+ * schema changes cannot be represented by defaults, such as property renames or
+ * data transformations.
+ *
+ * @param {any} node - The node to fill defaults for
+ * @param {DocumentSchema} schema - The document schema
+ * @returns {any} A shallow copy of the node with cloned default values filled in
+ */
+export function fill_node_defaults(node: any, schema: DocumentSchema): any;
+/**
+ * Fill omitted properties with schema defaults and Svedit's built-in type defaults across a document.
+ *
+ * This does not infer values, rename fields, or make an invalid migration valid
+ * by itself. Call this as one step in an explicit document migration when it is
+ * appropriate.
+ *
+ * @param {Document} doc - The document to fill defaults for
+ * @param {DocumentSchema} schema - The document schema
+ * @returns {Document} A document copy with cloned default values filled in
+ */
+export function fill_document_defaults(doc: Document, schema: DocumentSchema): Document;
 /**
  * Validate a document schema to ensure all referenced node types exist.
  * @param {DocumentSchema} document_schema - The document schema to validate
  * @throws {Error} Throws if the document schema is invalid
  */
 export function validate_document_schema(document_schema: DocumentSchema): void;
+/**
+ * @param {string} id
+ * @returns {boolean}
+ */
+export function is_id_valid(id: string): boolean;
 /**
  * Validate a node against its schema.
  * @param {any} node - The node to validate
  * @param {DocumentSchema} schema - The document schema
  * @param {Record<string, any>} all_nodes - All nodes in the document to check references
+ * @param {{ require_references?: boolean }} [options] - Validation options
  * @throws {Error} Throws if the node is invalid
  */
-export function validate_node(node: any, schema: DocumentSchema, all_nodes?: Record<string, any>): void;
+export function validate_node(node: any, schema: DocumentSchema, all_nodes?: Record<string, any>, options?: {
+    require_references?: boolean;
+}): void;
+/**
+ * Validate a document against its schema.
+ *
+ * @param {Document} doc - The document to validate
+ * @param {DocumentSchema} schema - The document schema
+ * @throws {Error} Throws if the document is invalid
+ */
+export function validate_document(doc: Document, schema: DocumentSchema): void;
 /**
  * Gets a value from the document at the specified path.
  *
@@ -59,6 +100,16 @@ export function property_type(schema: object, type: string, property: string): s
  * @returns {'block'|'text'|'annotation'} The node kind
  */
 export function kind(schema: object, node: any): "block" | "text" | "annotation";
+/**
+ * Checks whether an annotation node can be switched to another annotation type
+ * without losing data.
+ *
+ * @param {DocumentSchema} schema - The document schema
+ * @param {any} annotation_node - The annotation node to switch
+ * @param {string} target_annotation_type - The target annotation type
+ * @returns {boolean} True if the annotation can be switched safely
+ */
+export function can_switch_annotation_type(schema: DocumentSchema, annotation_node: any, target_annotation_type: string): boolean;
 /**
  * Inspects a path to get metadata about the value at that location.
  *
@@ -114,6 +165,15 @@ export function get_active_annotation(schema: DocumentSchema, doc: Document, sel
  * @returns {number} The number of references excluding deleted nodes
  */
 export function count_references_excluding_deleted(schema: DocumentSchema, doc: Document, target_node_id: NodeId, nodes_to_delete: Record<NodeId, boolean>): number;
+/**
+ * Gets ids of nodes that reference any of the target nodes.
+ *
+ * @param {DocumentSchema} schema - The document schema
+ * @param {Document} doc - The document containing nodes
+ * @param {Iterable<NodeId>} target_node_ids - Node IDs to find referrers for
+ * @returns {NodeId[]} IDs of nodes with references to any target node
+ */
+export function get_referencing_node_ids(schema: DocumentSchema, doc: Document, target_node_ids: Iterable<NodeId>): NodeId[];
 /**
  * Validates a selection against the current document state.
  * Works with any object that implements get() and inspect() (Session or Transaction).
@@ -127,6 +187,7 @@ export function validate_selection(selection: Selection, session_or_transaction:
     inspect: Function;
 }): void;
 import type { NodeSchema } from './types';
+import type { ValidateDocumentSchema } from './types';
 import type { PrimitiveType } from './types';
 import type { NodeProperty } from './types';
 import type { NodeArrayProperty } from './types';

package/dist/doc_utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doc_utils.d.ts","sourceRoot":"","sources":["../src/lib/doc_utils.js"],"names":[],"mappings":"AAWA;;;;;;;GAOG;AACH,uCAJ0C,CAAC,SAA7B,MAAM,CAAC,MAAM,EAAE,UAAU,CAAE,UAC9B,CAAC,GACC,CAAC,CAIb;AAED;;;;GAIG;AACH,wCAHW,MAAM,GACJ,IAAI,IAAI,aAAa,CAejC;AAED;;;;GAIG;AACH,2DAHW,YAAY,GAAG,iBAAiB,GAC9B,MAAM,GAAG,IAAI,CAWzB;AAED;;;;GAIG;AACH,0DAHW,cAAc,QAmBxB;AAgDD;;;;;;GAMG;AACH,oCALW,GAAG,UACH,cAAc,cACd,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,QA6D7B;AAED;;;;;;;GAOG;AACH,4BALW,cAAc,OACd,QAAQ,QACR,YAAY,GAAC,MAAM,GACjB,GAAG,CA4Ef;AAED;;;;;;;GAOG;AACH,sCALW,MAAM,QACN,MAAM,YACN,MAAM,GACJ,MAAM,CAclB;AAED;;;;;;GAMG;AACH,6BAJW,MAAM,QACN,GAAG,GACD,OAAO,GAAC,MAAM,GAAC,YAAY,CAIvC;AAED;;;;;;;GAOG;AACH,gCALW,cAAc,OACd,QAAQ,QACR,YAAY,GACV;IAAC,IAAI,EAAE,UAAU,GAAC,MAAM,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CAAC,CAoBzD;AAED;;;;;;;GAOG;AACH,8BAJW,QAAQ,cAEN,QAAQ,CAkCpB;AAED;;;;;;;GAOG;AACH,yCALW,cAAc,OACd,QAAQ,WACR,MAAM,GACJ,MAAM,CAoBlB;AAED;;;;;;;;;;;;;GAaG;AACH,8CANW,cAAc,OACd,QAAQ,cACR,SAAS,oBACT,MAAM,GACJ,UAAU,GAAG,IAAI,CAwB7B;AAED;;;;;;;;GAQG;AACH,2DANW,cAAc,OACd,QAAQ,kBACR,MAAM,mBACN,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACrB,MAAM,CA0BlB;AAED;;;;;;;GAOG;AACH,8CAJW,SAAS,0BACT;IAAE,GAAG,WAAW;IAAC,OAAO,WAAU;CAAE,QAoD9C;gCAthBqJ,SAAS;mCAAT,SAAS;kCAAT,SAAS;uCAAT,SAAS;oCAAT,SAAS;8BAAT,SAAS;kCAAT,SAAS;4BAAT,SAAS;+BAAT,SAAS;gCAAT,SAAS"}
+{"version":3,"file":"doc_utils.d.ts","sourceRoot":"","sources":["../src/lib/doc_utils.js"],"names":[],"mappings":"AAiBA;;;;;;;GAOG;AACH,uCAJ0C,CAAC,SAA7B,MAAM,CAAC,MAAM,EAAE,UAAU,CAAE,UAC9B,CAAC,GAAG,uBAAuB,CAAC,CAAC,GAC3B,CAAC,CAIb;AAED;;;;GAIG;AACH,wCAHW,MAAM,GACJ,IAAI,IAAI,aAAa,CAejC;AAED;;;;GAIG;AACH,2DAHW,YAAY,GAAG,iBAAiB,GAC9B,MAAM,GAAG,IAAI,CAWzB;AA2BD;;;;;;;;;;;GAWG;AACH,yCAJW,GAAG,UACH,cAAc,GACZ,GAAG,CAgBf;AAED;;;;;;;;;;GAUG;AACH,4CAJW,QAAQ,UACR,cAAc,GACZ,QAAQ,CAcpB;AAED;;;;GAIG;AACH,0DAHW,cAAc,QAoBxB;AAoHD;;;GAGG;AACH,gCAHW,MAAM,GACJ,OAAO,CAInB;AAED;;;;;;;GAOG;AACH,oCANW,GAAG,UACH,cAAc,cACd,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,YACnB;IAAE,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAAE,QAwF1C;AAED;;;;;;GAMG;AACH,uCAJW,QAAQ,UACR,cAAc,QAUxB;AAED;;;;;;;GAOG;AACH,4BALW,cAAc,OACd,QAAQ,QACR,YAAY,GAAC,MAAM,GACjB,GAAG,CA4Ef;AAED;;;;;;;GAOG;AACH,sCALW,MAAM,QACN,MAAM,YACN,MAAM,GACJ,MAAM,CAclB;AAED;;;;;;GAMG;AACH,6BAJW,MAAM,QACN,GAAG,GACD,OAAO,GAAC,MAAM,GAAC,YAAY,CAIvC;AAED;;;;;;;;GAQG;AACH,mDALW,cAAc,mBACd,GAAG,0BACH,MAAM,GACJ,OAAO,CAgBnB;AAED;;;;;;;GAOG;AACH,gCALW,cAAc,OACd,QAAQ,QACR,YAAY,GACV;IAAC,IAAI,EAAE,UAAU,GAAC,MAAM,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CAAC,CAoBzD;AAED;;;;;;;GAOG;AACH,8BAJW,QAAQ,cAEN,QAAQ,CAkCpB;AAED;;;;;;;GAOG;AACH,yCALW,cAAc,OACd,QAAQ,WACR,MAAM,GACJ,MAAM,CAoBlB;AAED;;;;;;;;;;;;;GAaG;AACH,8CANW,cAAc,OACd,QAAQ,cACR,SAAS,oBACT,MAAM,GACJ,UAAU,GAAG,IAAI,CAwB7B;AAED;;;;;;;;GAQG;AACH,2DANW,cAAc,OACd,QAAQ,kBACR,MAAM,mBACN,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACrB,MAAM,CA0BlB;AAED;;;;;;;GAOG;AACH,iDALW,cAAc,OACd,QAAQ,mBACR,QAAQ,CAAC,MAAM,CAAC,GACd,MAAM,EAAE,CA4BpB;AAED;;;;;;;GAOG;AACH,8CAJW,SAAS,0BACT;IAAE,GAAG,WAAW;IAAC,OAAO,WAAU;CAAE,QAoD9C;gCAhyBmN,SAAS;4CAAT,SAAS;mCAAT,SAAS;kCAAT,SAAS;uCAAT,SAAS;oCAAT,SAAS;8BAAT,SAAS;kCAAT,SAAS;4BAAT,SAAS;+BAAT,SAAS;gCAAT,SAAS"}