@stll/folio-core 0.0.1-placeholder.0 → 0.1.0

package/dist/ai-edits/snapshot.js

@@ -0,0 +1,195 @@
+import { deriveBlockId } from "../types/block-id.js";
+import { buildCleanBlockText } from "./clean-text.js";
+//#region src/ai-edits/snapshot.ts
+const normalizeFolioAIBlockText = (text) => text.replace(/\s+/gu, " ").trim();
+const hashFolioAIBlockText = (text) => {
+	let hash = 5381;
+	for (const character of text) hash = (hash * 33 + (character.codePointAt(0) ?? 0)) % 2147483647;
+	return `h${hash.toString(36)}`;
+};
+const createFolioAIEditSnapshot = (doc) => {
+	const draftBlocks = [];
+	const hashCounts = /* @__PURE__ */ new Map();
+	const usedBlockIds = /* @__PURE__ */ new Set();
+	let blockIndex = 0;
+	doc.descendants((node, pos) => {
+		if (!node.isTextblock) return;
+		const { text } = buildCleanBlockText(node, pos);
+		const normalizedText = normalizeFolioAIBlockText(text);
+		if (normalizedText.length === 0) return;
+		const textHash = hashFolioAIBlockText(normalizedText);
+		hashCounts.set(textHash, (hashCounts.get(textHash) ?? 0) + 1);
+		blockIndex++;
+		const paraIdAttr = node.attrs["paraId"];
+		const id = deriveBlockId({
+			paraId: typeof paraIdAttr === "string" && paraIdAttr.length > 0 ? paraIdAttr : null,
+			index: blockIndex,
+			taken: usedBlockIds
+		});
+		usedBlockIds.add(id);
+		const kind = getBlockKind(node);
+		const displayLabel = getDisplayLabel(node);
+		const styleId = getStyleId(node);
+		const previewRuns = getPreviewRuns(node);
+		draftBlocks.push({
+			block: {
+				id,
+				kind,
+				text,
+				...displayLabel !== void 0 && { displayLabel },
+				...styleId !== void 0 && { styleId },
+				...previewRuns !== void 0 && { previewRuns }
+			},
+			anchor: {
+				id,
+				from: pos,
+				to: pos + node.nodeSize,
+				text,
+				normalizedText,
+				textHash
+			}
+		});
+	});
+	const blocks = [];
+	const anchors = {};
+	for (const draft of draftBlocks) {
+		blocks.push(draft.block);
+		anchors[draft.block.id] = {
+			...draft.anchor,
+			hashOccurrenceCount: hashCounts.get(draft.anchor.textHash) ?? 0
+		};
+	}
+	return {
+		blocks,
+		anchors
+	};
+};
+const getBlockKind = (node) => {
+	const listMarker = node.attrs["listMarker"];
+	const numPr = node.attrs["numPr"];
+	if (typeof listMarker === "string" && listMarker.trim().length > 0 || numPr !== void 0 && numPr !== null) return "listItem";
+	const outlineLevel = node.attrs["outlineLevel"];
+	if (typeof outlineLevel === "number" && outlineLevel >= 0) return "heading";
+	return "paragraph";
+};
+const getDisplayLabel = (node) => {
+	const listMarker = node.attrs["listMarker"];
+	if (typeof listMarker === "string" && listMarker.trim().length > 0) return listMarker.trim();
+	const styleId = node.attrs["styleId"];
+	if (typeof styleId === "string" && /^heading/iu.test(styleId)) return styleId;
+};
+const getStyleId = (node) => {
+	const styleId = node.attrs["styleId"];
+	return typeof styleId === "string" && styleId.length > 0 ? styleId : void 0;
+};
+const DELETION_MARK = "deletion";
+const getPreviewRuns = (node) => {
+	const runs = [];
+	const defaultStyle = getDefaultPreviewRunStyle(node);
+	node.descendants((child) => {
+		if (!child.isText || child.text === void 0) return true;
+		if (child.marks.some((mark) => mark.type.name === DELETION_MARK)) return false;
+		const style = getPreviewRunStyle(child.marks, defaultStyle);
+		const previous = runs.at(-1);
+		if (previous && samePreviewRunStyle(previous, style)) {
+			previous.text += child.text;
+			return false;
+		}
+		runs.push({
+			text: child.text,
+			...style
+		});
+		return false;
+	});
+	if (runs.every(isUnstyledPreviewRun)) return;
+	return runs;
+};
+const getDefaultPreviewRunStyle = (node) => {
+	const formatting = node.attrs["defaultTextFormatting"];
+	if (typeof formatting !== "object" || formatting === null) return {};
+	return {
+		...getBooleanTextFormatting(formatting),
+		...getFontSizeTextFormatting(formatting),
+		...getFontFamilyTextFormatting(formatting),
+		...getColorTextFormatting(formatting)
+	};
+};
+const getPreviewRunStyle = (marks, defaultStyle) => {
+	const style = { ...defaultStyle };
+	for (const mark of marks) switch (mark.type.name) {
+		case "bold":
+			style.bold = true;
+			break;
+		case "italic":
+			style.italic = true;
+			break;
+		case "underline":
+			if (isUnderlineEnabled(mark.attrs["style"])) style.underline = true;
+			break;
+		case "strike":
+			style.strike = true;
+			break;
+		case "fontSize": {
+			const size = Number(mark.attrs["size"]);
+			if (Number.isFinite(size) && size > 0) style.fontSizePt = size / 2;
+			break;
+		}
+		case "fontFamily": {
+			const fontFamily = getFontFamilyFromAttrs(mark.attrs);
+			if (fontFamily !== void 0) style.fontFamily = fontFamily;
+			break;
+		}
+		case "textColor": {
+			const color = getColorFromAttrs(mark.attrs);
+			if (color !== void 0) style.color = color;
+			break;
+		}
+		default: break;
+	}
+	return style;
+};
+const getBooleanTextFormatting = (formatting) => ({
+	...Reflect.get(formatting, "bold") === true && { bold: true },
+	...Reflect.get(formatting, "italic") === true && { italic: true },
+	...isUnderlineEnabled(Reflect.get(formatting, "underline")) && { underline: true },
+	...Reflect.get(formatting, "strike") === true && { strike: true }
+});
+const isUnderlineEnabled = (underline) => {
+	if (underline === void 0 || underline === null || underline === false) return false;
+	if (underline === true) return true;
+	if (typeof underline === "string") return underline !== "none";
+	if (typeof underline !== "object") return false;
+	return Reflect.get(underline, "style") !== "none";
+};
+const getFontSizeTextFormatting = (formatting) => {
+	const fontSize = Number(Reflect.get(formatting, "fontSize"));
+	if (!Number.isFinite(fontSize) || fontSize <= 0) return {};
+	return { fontSizePt: fontSize / 2 };
+};
+const getFontFamilyTextFormatting = (formatting) => {
+	const fontFamilyValue = Reflect.get(formatting, "fontFamily");
+	if (typeof fontFamilyValue !== "object" || fontFamilyValue === null) return {};
+	const fontFamily = getFontFamilyFromAttrs(fontFamilyValue);
+	return fontFamily === void 0 ? {} : { fontFamily };
+};
+const getColorTextFormatting = (formatting) => {
+	const colorValue = Reflect.get(formatting, "color");
+	if (typeof colorValue !== "object" || colorValue === null) return {};
+	const color = getColorFromAttrs(colorValue);
+	return color === void 0 ? {} : { color };
+};
+const getFontFamilyFromAttrs = (attrs) => {
+	const ascii = Reflect.get(attrs, "ascii");
+	if (typeof ascii === "string" && ascii.length > 0) return ascii;
+	const hAnsi = Reflect.get(attrs, "hAnsi");
+	if (typeof hAnsi === "string" && hAnsi.length > 0) return hAnsi;
+};
+const getColorFromAttrs = (attrs) => {
+	const rgb = Reflect.get(attrs, "rgb") ?? Reflect.get(attrs, "val");
+	if (typeof rgb !== "string" || !/^[0-9a-fA-F]{6}$/u.test(rgb)) return;
+	return `#${rgb}`;
+};
+const samePreviewRunStyle = (run, style) => run.bold === style.bold && run.italic === style.italic && run.underline === style.underline && run.strike === style.strike && run.fontFamily === style.fontFamily && run.fontSizePt === style.fontSizePt && run.color === style.color;
+const isUnstyledPreviewRun = ({ bold, italic, underline, strike, fontFamily, fontSizePt, color }) => bold === void 0 && italic === void 0 && underline === void 0 && strike === void 0 && fontFamily === void 0 && fontSizePt === void 0 && color === void 0;
+//#endregion
+export { createFolioAIEditSnapshot, hashFolioAIBlockText, normalizeFolioAIBlockText };

package/dist/ai-edits/types.d.ts

@@ -0,0 +1,156 @@
+//#region src/ai-edits/types.d.ts
+type FolioAIBlockKind = "heading" | "listItem" | "paragraph";
+type FolioAIBlockPreviewRun = {
+  text: string;
+  bold?: boolean;
+  italic?: boolean;
+  underline?: boolean;
+  strike?: boolean;
+  fontFamily?: string;
+  fontSizePt?: number;
+  color?: string;
+};
+type FolioAIBlock = {
+  id: string;
+  kind: FolioAIBlockKind;
+  text: string;
+  displayLabel?: string;
+  styleId?: string;
+  previewRuns?: FolioAIBlockPreviewRun[];
+};
+type FolioAIEditSnapshot = {
+  blocks: FolioAIBlock[];
+  anchors: Record<string, FolioAIBlockAnchor>;
+};
+type FolioAIBlockAnchor = {
+  id: string;
+  from: number;
+  to: number;
+  text: string;
+  normalizedText: string;
+  textHash: string;
+  hashOccurrenceCount: number;
+};
+type FolioAIComment = {
+  text: string;
+};
+type FolioAIEditSeverity = "low" | "medium" | "high";
+/**
+ * Optional review metadata attached to an AI-authored operation.
+ * Set by the model when performing a structured review (e.g.
+ * `severity: "high"`, `area: "Penalty"`); absent for direct edits.
+ * Both fields are independent — either or both may be set.
+ */
+type FolioAIEditReviewMeta = {
+  severity?: FolioAIEditSeverity;
+  area?: string;
+};
+/**
+ * A party in an `insertSignatureTable` op. Mirrors the
+ * `signatureTable` helper in `docx-core/legal-source/compile.ts`:
+ * name is rendered bold; `signatory` and `title` are optional
+ * lines under the signature rule (title in italics).
+ */
+type FolioAISignatureParty = {
+  name: string;
+  signatory?: string;
+  title?: string;
+};
+type FolioAIEditOperation = FolioAIEditReviewMeta & ({
+  id: string;
+  type: "replaceInBlock";
+  blockId: string;
+  find: string;
+  replace: string;
+  comment?: FolioAIComment;
+} | {
+  id: string;
+  type: "insertAfterBlock" | "insertBeforeBlock";
+  blockId: string;
+  text: string;
+  inheritFormatting?: boolean;
+  /**
+   * When true, mark the inserted paragraph with
+   * `pageBreakBefore` so the layout engine starts it on a
+   * new page. Use for explicit page-break inserts.
+   */
+  pageBreakBefore?: boolean;
+  /**
+   * Override the paragraph `styleId` attr of the inserted
+   * block (e.g. `ClauseHeading1`). When omitted the inserted
+   * block inherits the source block's styleId via
+   * `inheritFormatting`.
+   */
+  styleId?: string;
+  comment?: FolioAIComment;
+} | {
+  id: string;
+  type: "replaceBlock";
+  blockId: string;
+  text: string;
+  preserveFormatting?: boolean;
+  styleId?: string;
+  comment?: FolioAIComment;
+} | {
+  id: string;
+  type: "deleteBlock";
+  blockId: string;
+  comment?: FolioAIComment;
+} | {
+  id: string;
+  type: "commentOnBlock";
+  blockId: string;
+  quote?: string;
+  comment: FolioAIComment;
+} | {
+  id: string;
+  type: "insertSignatureTable";
+  blockId: string;
+  /**
+   * Position the table after the anchor block (default) or
+   * before it. Always inserts as a sibling at the document
+   * level — no nested-table support.
+   */
+  position?: "after" | "before";
+  parties: FolioAISignatureParty[];
+  comment?: FolioAIComment;
+});
+type FolioAIEditApplyMode = "direct" | "tracked-changes";
+type FolioAIEditSkipReason = "missingBlock" | "changedBlock" | "ambiguousFind" | "missingFind" | "unsupportedBlock" | "emptyOperation"
+/**
+ * The operation would not change the document — find equals
+ * replace, or replaceBlock's `text` matches the live block.
+ * Filtered out so the reviewer doesn't see "X → X" cards.
+ */
+| "noopOperation";
+type FolioAIEditAppliedOperation = {
+  id: string;
+  commentId?: number;
+  /**
+   * Primary tracked-change revision id (only set when applied in
+   * `tracked-changes` mode and the operation produced at least one
+   * insertion/deletion mark). Stable identifier suitable for
+   * scroll-to and visual reference.
+   */
+  revisionId?: number;
+  /**
+   * Every revision id this operation produced. A replace allocates
+   * separate ids for the deletion and the insertion sides because
+   * fromProseDoc serialises a single id carrying both as a Word
+   * "moveTo/moveFrom" pair, not an ins/del — so the two sides must
+   * be distinct ids in the doc but conceptually one operation here.
+   * Use this list when you need to accept or reject every mark
+   * belonging to this op.
+   */
+  revisionIds?: readonly number[];
+};
+type FolioAIEditSkippedOperation = {
+  id: string;
+  reason: FolioAIEditSkipReason;
+};
+type FolioAIEditApplyResult = {
+  applied: FolioAIEditAppliedOperation[];
+  skipped: FolioAIEditSkippedOperation[];
+};
+//#endregion
+export { FolioAIBlock, FolioAIBlockAnchor, FolioAIBlockKind, FolioAIBlockPreviewRun, FolioAIComment, FolioAIEditAppliedOperation, FolioAIEditApplyMode, FolioAIEditApplyResult, FolioAIEditOperation, FolioAIEditReviewMeta, FolioAIEditSeverity, FolioAIEditSkipReason, FolioAIEditSkippedOperation, FolioAIEditSnapshot, FolioAISignatureParty };

package/dist/ai-edits/word-diff.d.ts

@@ -0,0 +1,20 @@
+//#region src/ai-edits/word-diff.d.ts
+/**
+ * Word-level diff between two strings. Tokenises on whitespace
+ * boundaries (preserving the whitespace as part of each token), runs
+ * an LCS, and returns a left-to-right ordered list of segments where
+ * shared runs render as `equal`, removed runs as `del`, and added
+ * runs as `ins`. Used by both the panel (to render minimal-change
+ * redlines) and the apply engine (so tracked changes only mark the
+ * divergent tokens, not the whole replaced span).
+ *
+ * O(n*m) on token counts; if a single replacement ever holds more
+ * than a few hundred tokens, swap for a streaming diff.
+ */
+type WordDiffSegment = {
+  type: "equal" | "del" | "ins";
+  text: string;
+};
+declare const diffWordSegments: (before: string, after: string) => WordDiffSegment[];
+//#endregion
+export { WordDiffSegment, diffWordSegments };

package/dist/ai-edits/word-diff.js

@@ -0,0 +1,77 @@
+//#region src/ai-edits/word-diff.ts
+const tokenize = (s) => s.match(/\s+|\S+/gu) ?? [];
+const diffWordSegments = (before, after) => {
+	const a = tokenize(before);
+	const b = tokenize(after);
+	if (a.length === 0 && b.length === 0) return [];
+	const m = a.length;
+	const n = b.length;
+	const dp = Array.from({ length: m + 1 }, () => Array.from({ length: n + 1 }, () => 0));
+	for (let i = 0; i < m; i++) for (let j = 0; j < n; j++) {
+		const row = dp[i + 1];
+		const prevRow = dp[i];
+		if (!row || !prevRow) continue;
+		const prev = prevRow[j] ?? 0;
+		const left = row[j] ?? 0;
+		const top = prevRow[j + 1] ?? 0;
+		row[j + 1] = a[i] === b[j] ? prev + 1 : Math.max(left, top);
+	}
+	const segments = [];
+	const push = (type, text) => {
+		if (text.length === 0) return;
+		const last = segments.at(-1);
+		if (last && last.type === type) {
+			last.text += text;
+			return;
+		}
+		segments.push({
+			type,
+			text
+		});
+	};
+	let i = m;
+	let j = n;
+	const reverse = [];
+	while (i > 0 && j > 0) {
+		if (a[i - 1] === b[j - 1]) {
+			reverse.push({
+				type: "equal",
+				text: a[i - 1] ?? ""
+			});
+			i--;
+			j--;
+			continue;
+		}
+		if ((dp[i - 1]?.[j] ?? 0) > (dp[i]?.[j - 1] ?? 0)) {
+			reverse.push({
+				type: "del",
+				text: a[i - 1] ?? ""
+			});
+			i--;
+		} else {
+			reverse.push({
+				type: "ins",
+				text: b[j - 1] ?? ""
+			});
+			j--;
+		}
+	}
+	while (i > 0) {
+		reverse.push({
+			type: "del",
+			text: a[i - 1] ?? ""
+		});
+		i--;
+	}
+	while (j > 0) {
+		reverse.push({
+			type: "ins",
+			text: b[j - 1] ?? ""
+		});
+		j--;
+	}
+	for (const seg of reverse.toReversed()) push(seg.type, seg.text);
+	return segments;
+};
+//#endregion
+export { diffWordSegments };

package/dist/ai-suggestions/apply.d.ts

@@ -0,0 +1,17 @@
+import { AISuggestion, AISuggestionApplyMode } from "./types.js";
+import { EditorView } from "prosemirror-view";
+
+//#region src/ai-suggestions/apply.d.ts
+type ApplyResult = {
+  applied: string[];
+  stale: string[];
+};
+type ApplyOptions = {
+  view: EditorView;
+  suggestions: AISuggestion[];
+  mode: AISuggestionApplyMode;
+  author: string;
+};
+declare function applySuggestions(options: ApplyOptions): ApplyResult;
+//#endregion
+export { ApplyResult, applySuggestions };

package/dist/ai-suggestions/apply.js

@@ -0,0 +1,64 @@
+import { resolveSuggestionAnchor } from "./conflict.js";
+//#region src/ai-suggestions/apply.ts
+function applySuggestions(options) {
+	const { view, suggestions, mode, author } = options;
+	const applied = [];
+	const stale = [];
+	if (suggestions.length === 0) return {
+		applied,
+		stale
+	};
+	const resolved = [];
+	for (const suggestion of suggestions) {
+		const anchor = resolveSuggestionAnchor(view.state.doc, suggestion);
+		if (!anchor) {
+			stale.push(suggestion.id);
+			continue;
+		}
+		resolved.push({
+			suggestion,
+			from: anchor.from,
+			to: anchor.to
+		});
+	}
+	if (resolved.length === 0) return {
+		applied,
+		stale
+	};
+	resolved.sort((a, b) => b.from - a.from);
+	const tr = view.state.tr;
+	if (mode === "direct") for (const { suggestion, from, to } of resolved) {
+		tr.insertText(suggestion.suggestedText, from, to);
+		applied.push(suggestion.id);
+	}
+	else {
+		const insertionType = view.state.schema.marks["insertion"];
+		const deletionType = view.state.schema.marks["deletion"];
+		if (!insertionType || !deletionType) return {
+			applied,
+			stale: [...stale, ...resolved.map((r) => r.suggestion.id)]
+		};
+		const date = (/* @__PURE__ */ new Date()).toISOString();
+		let revisionSeed = Date.now();
+		for (const { suggestion, from, to } of resolved) {
+			const attrs = {
+				revisionId: revisionSeed++,
+				author,
+				date
+			};
+			if (suggestion.suggestedText.length > 0) {
+				tr.insertText(suggestion.suggestedText, to, to);
+				tr.addMark(to, to + suggestion.suggestedText.length, insertionType.create(attrs));
+			}
+			if (to > from) tr.addMark(from, to, deletionType.create(attrs));
+			applied.push(suggestion.id);
+		}
+	}
+	if (tr.docChanged) view.dispatch(tr);
+	return {
+		applied,
+		stale
+	};
+}
+//#endregion
+export { applySuggestions };

package/dist/ai-suggestions/conflict.d.ts

@@ -0,0 +1,22 @@
+import { AISuggestion } from "./types.js";
+import { Node } from "prosemirror-model";
+
+//#region src/ai-suggestions/conflict.d.ts
+type ResolvedAnchor = {
+  from: number;
+  to: number;
+};
+/**
+ * Resolve the current PM range of a suggestion's original text.
+ *
+ * Strategy:
+ * 1. If the recorded range still contains the originalText verbatim, use it.
+ * 2. Otherwise, search a bounded window of the document for a unique
+ *    match of `contextBefore + originalText + contextAfter`.
+ * 3. If the match is missing or ambiguous, return null — the caller
+ *    treats null as a stale suggestion.
+ */
+declare function resolveSuggestionAnchor(doc: Node, suggestion: AISuggestion): ResolvedAnchor | null;
+declare function isSuggestionStale(doc: Node, suggestion: AISuggestion): boolean;
+//#endregion
+export { ResolvedAnchor, isSuggestionStale, resolveSuggestionAnchor };

package/dist/ai-suggestions/conflict.js

@@ -0,0 +1,67 @@
+import { buildPositionalText } from "./text-positions.js";
+//#region src/ai-suggestions/conflict.ts
+const ANCHOR_SEARCH_WINDOW_PM = 2e3;
+/**
+* Resolve the current PM range of a suggestion's original text.
+*
+* Strategy:
+* 1. If the recorded range still contains the originalText verbatim, use it.
+* 2. Otherwise, search a bounded window of the document for a unique
+*    match of `contextBefore + originalText + contextAfter`.
+* 3. If the match is missing or ambiguous, return null — the caller
+*    treats null as a stale suggestion.
+*/
+function resolveSuggestionAnchor(doc, suggestion) {
+	const docSize = doc.content.size;
+	const { from, to } = suggestion.range;
+	if (from >= 0 && to <= docSize && to - from === suggestion.originalText.length) {
+		if (doc.textBetween(from, to, "\n", "\n") === suggestion.originalText) return {
+			from,
+			to
+		};
+	}
+	const positional = buildPositionalText(doc, Math.max(0, from - ANCHOR_SEARCH_WINDOW_PM), Math.min(docSize, to + ANCHOR_SEARCH_WINDOW_PM));
+	const needles = [
+		{
+			needle: suggestion.contextBefore + suggestion.originalText + suggestion.contextAfter,
+			prefix: suggestion.contextBefore.length
+		},
+		{
+			needle: suggestion.originalText + suggestion.contextAfter,
+			prefix: 0
+		},
+		{
+			needle: suggestion.contextBefore + suggestion.originalText,
+			prefix: suggestion.contextBefore.length
+		},
+		{
+			needle: suggestion.originalText,
+			prefix: 0
+		}
+	];
+	for (const { needle, prefix } of needles) {
+		if (needle.length === 0) continue;
+		const firstHit = positional.text.indexOf(needle);
+		if (firstHit === -1) continue;
+		if (positional.text.indexOf(needle, firstHit + 1) !== -1) continue;
+		const originalTextStart = firstHit + prefix;
+		const originalTextEnd = originalTextStart + suggestion.originalText.length;
+		if (suggestion.originalText.length === 0) {
+			const point = positional.pmPositionAt(originalTextStart);
+			return {
+				from: point,
+				to: point
+			};
+		}
+		return {
+			from: positional.pmPositionAt(originalTextStart),
+			to: positional.pmPositionAt(originalTextEnd - 1) + 1
+		};
+	}
+	return null;
+}
+function isSuggestionStale(doc, suggestion) {
+	return resolveSuggestionAnchor(doc, suggestion) === null;
+}
+//#endregion
+export { isSuggestionStale, resolveSuggestionAnchor };

package/dist/ai-suggestions/text-positions.d.ts

@@ -0,0 +1,21 @@
+import { Node } from "prosemirror-model";
+
+//#region src/ai-suggestions/text-positions.d.ts
+type PositionalText = {
+  /** Concatenated text content, with `\n` between block nodes. */text: string;
+  /**
+   * For each character at index `i` in `text`, returns the PM position
+   * of that character (i.e., the position just before it). Block
+   * separator characters map to the position immediately after the
+   * preceding block.
+   */
+  pmPositionAt: (textIndex: number) => number;
+};
+/**
+ * Walk a slice of the document, returning its text plus a position
+ * lookup. The walk skips past block boundaries, inserting a
+ * separator character so consumers can identify line breaks.
+ */
+declare function buildPositionalText(doc: Node, from?: number, to?: number): PositionalText;
+//#endregion
+export { PositionalText, buildPositionalText };

package/dist/ai-suggestions/text-positions.js

@@ -0,0 +1,48 @@
+//#region src/ai-suggestions/text-positions.ts
+const BLOCK_SEPARATOR = "\n";
+/**
+* Walk a slice of the document, returning its text plus a position
+* lookup. The walk skips past block boundaries, inserting a
+* separator character so consumers can identify line breaks.
+*/
+function buildPositionalText(doc, from = 0, to = doc.content.size) {
+	const chunks = [];
+	const offsets = [];
+	let textLength = 0;
+	let lastBlockEnd = null;
+	doc.nodesBetween(from, to, (node, pos) => {
+		if (node.isText) {
+			const text = node.text ?? "";
+			const startInNode = Math.max(from, pos);
+			const endInNode = Math.min(to, pos + node.nodeSize);
+			if (endInNode <= startInNode) return false;
+			const sliceStart = startInNode - pos;
+			const sliceEnd = endInNode - pos;
+			const slice = text.slice(sliceStart, sliceEnd);
+			if (slice.length === 0) return false;
+			chunks.push(slice);
+			for (let i = 0; i < slice.length; i++) offsets.push(startInNode + i);
+			textLength += slice.length;
+			return false;
+		}
+		if (node.isBlock) {
+			if (lastBlockEnd !== null && textLength > 0) {
+				chunks.push(BLOCK_SEPARATOR);
+				offsets.push(lastBlockEnd);
+				textLength += 1;
+			}
+			lastBlockEnd = pos + node.nodeSize - 1;
+		}
+		return true;
+	});
+	return {
+		text: chunks.join(""),
+		pmPositionAt: (textIndex) => {
+			if (textIndex < 0) return offsets[0] ?? from;
+			if (textIndex >= offsets.length) return (offsets.at(-1) ?? from) + 1;
+			return offsets[textIndex] ?? from;
+		}
+	};
+}
+//#endregion
+export { buildPositionalText };