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

package/dist/prosemirror/plugins/suggestionMode.js

@@ -0,0 +1,489 @@
+import { splitBlockClearBorders } from "../extensions/features/BaseKeymapExtension.js";
+import { Plugin, PluginKey, TextSelection } from "prosemirror-state";
+import { isHistoryTransaction } from "prosemirror-history";
+//#region src/prosemirror/plugins/suggestionMode.ts
+/**
+* Suggestion Mode Plugin
+*
+* When active, intercepts all text insertions and deletions,
+* wrapping them in tracked change marks (insertion/deletion)
+* instead of modifying the document directly.
+*
+* - Typed text is marked as insertion (green underline)
+* - Deleted text is NOT removed — it's marked as deletion (red strikethrough)
+* - Text already marked as insertion by the current author is deleted normally
+*   (retracting your own suggestion)
+*/
+const suggestionModeKey = new PluginKey("suggestionMode");
+const SUGGESTION_META = "suggestionModeApplied";
+const SUGGESTION_BYPASS_META = "suggestionModeBypass";
+let nextRevisionId = Date.now();
+function makeMarkAttrs(pluginState) {
+	return {
+		revisionId: nextRevisionId++,
+		author: pluginState.author,
+		date: (/* @__PURE__ */ new Date()).toISOString()
+	};
+}
+function makeRevisionInfo(state) {
+	const pluginState = suggestionModeKey.getState(state);
+	if (!pluginState?.active) return null;
+	const attrs = makeMarkAttrs(pluginState);
+	return {
+		id: attrs.revisionId,
+		author: attrs.author,
+		date: attrs.date
+	};
+}
+function makeParagraphMarkInfo(pluginState) {
+	const attrs = makeMarkAttrs(pluginState);
+	return {
+		id: attrs.revisionId,
+		author: attrs.author,
+		date: attrs.date
+	};
+}
+/**
+* Find an adjacent mark of the same type by the same author.
+* Reuses its revisionId so consecutive edits group into one change.
+*/
+function findAdjacentRevision(doc, pos, markTypeName, author) {
+	try {
+		const $pos = doc.resolve(pos);
+		for (const node of [$pos.nodeBefore, $pos.nodeAfter]) if (node?.isText) {
+			const mark = node.marks.find((m) => m.type.name === markTypeName && m.attrs["author"] === author);
+			if (mark) return mark.attrs;
+		}
+	} catch {}
+	return null;
+}
+/**
+* Find an adjacent revision at either edge of a range.
+* This keeps consecutive backspaces grouped even though the cursor moves left.
+*/
+function findAdjacentRevisionForRange(doc, from, to, markTypeName, author) {
+	return findAdjacentRevision(doc, from, markTypeName, author) ?? findAdjacentRevision(doc, to, markTypeName, author);
+}
+/**
+* Walk a text range and either mark as deletion or retract own insertions.
+* Processes in reverse order to maintain position validity.
+*/
+function markRangeAsDeleted(tr, doc, from, to, insertionType, deletionType, pluginState) {
+	const ranges = [];
+	doc.nodesBetween(from, to, (node, pos) => {
+		if (!node.isText && !(node.isInline && node.type.allowsMarkType(deletionType))) return;
+		const start = Math.max(pos, from);
+		const end = Math.min(pos + node.nodeSize, to);
+		if (start >= end) return;
+		const isOwnInsert = node.marks.some((m) => m.type === insertionType && m.attrs["author"] === pluginState.author);
+		ranges.push({
+			from: start,
+			to: end,
+			isOwnInsert
+		});
+	});
+	if (ranges.length === 0) return;
+	const delAttrs = findAdjacentRevisionForRange(doc, from, to, "deletion", pluginState.author) || makeMarkAttrs(pluginState);
+	for (let i = ranges.length - 1; i >= 0; i--) {
+		const range = ranges[i];
+		if (range.isOwnInsert) tr.delete(range.from, range.to);
+		else tr.addMark(range.from, range.to, deletionType.create(delAttrs));
+	}
+}
+/**
+* Add the insertion mark to every inline node in `[from, to)` that can carry
+* it and does not already carry a tracked-change mark. Mirrors the catch-all's
+* node-by-node walk: a leaf text node's own `markSet` is empty so
+* `allowsMarkType` is false, hence the explicit `isText` arm; content already
+* carrying an insertion/deletion is left untouched so another author's revision
+* isn't overwritten. eigenpal/docx-editor#784.
+*/
+function markRangeAsInserted(tr, doc, from, to, insertionType, deletionType, attrs) {
+	doc.nodesBetween(from, to, (node, pos) => {
+		if (!node.isText && !(node.isInline && node.type.allowsMarkType(insertionType))) return;
+		if (node.marks.some((m) => m.type === insertionType || m.type === deletionType)) return;
+		const start = Math.max(pos, from);
+		const end = Math.min(pos + node.nodeSize, to);
+		if (start >= end) return;
+		tr.addMark(start, end, insertionType.create(attrs));
+	});
+}
+/**
+* With track changes on, pasting over a non-empty text selection marks the
+* replaced text as a tracked deletion and the pasted slice as a tracked
+* insertion (so they read as one replacement), matching typing over a
+* selection. Returns false for a collapsed cursor or non-text selection so the
+* default paste + the `appendTransaction` catch-all marks a plain insertion
+* (eigenpal/docx-editor#784).
+*/
+function handleSuggestionPaste(view, slice, pluginState) {
+	const { selection } = view.state;
+	if (!(selection instanceof TextSelection) || selection.empty) return false;
+	const insertionType = view.state.schema.marks["insertion"];
+	const deletionType = view.state.schema.marks["deletion"];
+	if (!insertionType || !deletionType) return false;
+	const { from, to } = selection;
+	const tr = view.state.tr;
+	tr.setMeta(SUGGESTION_META, true);
+	markRangeAsDeleted(tr, view.state.doc, from, to, insertionType, deletionType, pluginState);
+	const insertFrom = tr.mapping.map(to);
+	const sizeBefore = tr.doc.content.size;
+	tr.replaceRange(insertFrom, insertFrom, slice);
+	const insertTo = insertFrom + (tr.doc.content.size - sizeBefore);
+	tr.removeMark(insertFrom, insertTo, deletionType);
+	const insertAttrs = findAdjacentRevision(view.state.doc, from, "insertion", pluginState.author) || makeMarkAttrs(pluginState);
+	markRangeAsInserted(tr, tr.doc, insertFrom, insertTo, insertionType, deletionType, insertAttrs);
+	tr.setSelection(TextSelection.near(tr.doc.resolve(insertTo)));
+	view.dispatch(tr.scrollIntoView());
+	return true;
+}
+/**
+* Insert text as a tracked insertion, optionally marking replaced selection as deletion.
+*/
+function applySuggestionInsert(view, from, to, text, pluginState) {
+	const insertionType = view.state.schema.marks["insertion"];
+	if (!insertionType) return false;
+	const tr = view.state.tr;
+	tr.setMeta(SUGGESTION_META, true);
+	const insertAttrs = findAdjacentRevision(view.state.doc, from, "insertion", pluginState.author) || makeMarkAttrs(pluginState);
+	if (from !== to) {
+		const deletionType = view.state.schema.marks["deletion"];
+		if (deletionType) markRangeAsDeleted(tr, view.state.doc, from, to, insertionType, deletionType, pluginState);
+	}
+	const insertAt = tr.mapping.map(to);
+	tr.insertText(text, insertAt, insertAt);
+	const deletionType = view.state.schema.marks["deletion"];
+	if (deletionType) tr.removeMark(insertAt, insertAt + text.length, deletionType);
+	tr.addMark(insertAt, insertAt + text.length, insertionType.create(insertAttrs));
+	view.dispatch(tr.scrollIntoView());
+	return true;
+}
+/**
+* Track-changes Enter: split the paragraph and stamp `pPrMark = 'ins'` on the
+* FIRST half of the split (the upper paragraph), per ECMA-376 §17.13.5. The
+* actual splitting reuses `splitBlockClearBorders` so border/style/stored-mark
+* behavior stays identical to ordinary editing.
+*
+* If the source paragraph already carries a `pPrMark`, leave it alone — a
+* prior author's revision must not be silently overwritten.
+*/
+function handleSuggestionEnter(view, pluginState) {
+	const { $from } = view.state.selection;
+	if ($from.parent.type.name !== "paragraph") return false;
+	const sourcePos = $from.before();
+	const sourceAttrs = $from.parent.attrs;
+	const captured = { tr: null };
+	if (!splitBlockClearBorders(view.state, (tr) => {
+		captured.tr = tr;
+	}, view) || !captured.tr) return false;
+	const tr = captured.tr;
+	if (sourceAttrs["pPrMark"] == null) {
+		if (tr.doc.nodeAt(sourcePos)?.type.name === "paragraph") {
+			const markInfo = {
+				kind: "ins",
+				info: makeParagraphMarkInfo(pluginState)
+			};
+			tr.setNodeAttribute(sourcePos, "pPrMark", markInfo);
+		}
+	}
+	view.dispatch(tr.scrollIntoView());
+	return true;
+}
+/**
+* Detect a caret-at-paragraph-boundary scenario where Backspace/Delete should
+* record a tracked paragraph-mark deletion instead of joining paragraphs.
+*
+* Returns the position of the paragraph whose `pPrMark` should be set, or
+* `null` if the caret is mid-paragraph (let the normal text-delete path run).
+*
+* - Backspace-at-paragraph-start → previous sibling paragraph.
+* - Delete-at-paragraph-end     → current paragraph.
+*
+* Returns `null` when there is no adjacent sibling paragraph (the join would
+* not produce paragraph-mark merging — e.g. doc start, doc end, or sibling
+* is a table). The default merge path then runs unchanged.
+*/
+function paragraphBoundaryTarget(state, direction) {
+	const { $from, empty } = state.selection;
+	if (!empty) return null;
+	if ($from.parent.type.name !== "paragraph") return null;
+	const paragraphStart = $from.before();
+	const paragraphEnd = $from.after();
+	if (direction === "backward") {
+		if ($from.parentOffset !== 0) return null;
+		if (paragraphStart === 0) return null;
+		const prev = state.doc.resolve(paragraphStart).nodeBefore;
+		if (!prev || prev.type.name !== "paragraph") return null;
+		return paragraphStart - prev.nodeSize;
+	}
+	if ($from.parentOffset !== $from.parent.content.size) return null;
+	if (paragraphEnd >= state.doc.content.size) return null;
+	const next = state.doc.resolve(paragraphEnd).nodeAfter;
+	if (!next || next.type.name !== "paragraph") return null;
+	return paragraphStart;
+}
+/**
+* Mark a paragraph break as a tracked deletion. `target` is the position of
+* the paragraph whose closing mark is being deleted (per OOXML, that's the
+* previous paragraph for Backspace-at-start and the current paragraph for
+* Delete-at-end). If the existing mark is the current author's insertion,
+* retract it by joining the paragraphs back together.
+*/
+function applyPPrDel(view, targetParagraphPos, pluginState) {
+	const targetNode = view.state.doc.nodeAt(targetParagraphPos);
+	if (!targetNode || targetNode.type.name !== "paragraph") return false;
+	const existingMark = targetNode.attrs["pPrMark"];
+	if (isCurrentAuthorParagraphInsertion(existingMark, pluginState.author)) {
+		const tr = view.state.tr;
+		tr.setMeta(SUGGESTION_META, true);
+		const joinPos = targetParagraphPos + targetNode.nodeSize;
+		try {
+			tr.join(joinPos);
+			tr.setNodeAttribute(targetParagraphPos, "pPrMark", null);
+			view.dispatch(tr.scrollIntoView());
+		} catch {
+			return true;
+		}
+		return true;
+	}
+	if (existingMark != null) return true;
+	const tr = view.state.tr;
+	tr.setMeta(SUGGESTION_META, true);
+	const markInfo = {
+		kind: "del",
+		info: makeParagraphMarkInfo(pluginState)
+	};
+	tr.setNodeAttribute(targetParagraphPos, "pPrMark", markInfo);
+	view.dispatch(tr.scrollIntoView());
+	return true;
+}
+function isCurrentAuthorParagraphInsertion(value, author) {
+	if (typeof value !== "object" || value === null) return false;
+	const mark = value;
+	if (mark.kind !== "ins" || typeof mark.info !== "object" || mark.info === null) return false;
+	return mark.info.author === author;
+}
+/**
+* Handle delete (forward or backward) in suggestion mode.
+*/
+function handleSuggestionDelete(state, dispatch, direction) {
+	const pluginState = suggestionModeKey.getState(state);
+	if (!pluginState?.active) return false;
+	const { $from, $to, empty } = state.selection;
+	const insertionType = state.schema.marks["insertion"];
+	const deletionType = state.schema.marks["deletion"];
+	if (!insertionType || !deletionType) return false;
+	if (!dispatch) return true;
+	const tr = state.tr;
+	tr.setMeta(SUGGESTION_META, true);
+	if (!empty) {
+		markRangeAsDeleted(tr, state.doc, $from.pos, $to.pos, insertionType, deletionType, pluginState);
+		const cursorPos = tr.mapping.map($to.pos);
+		tr.setSelection(TextSelection.near(tr.doc.resolve(cursorPos)));
+		dispatch(tr.scrollIntoView());
+		return true;
+	}
+	const isBackward = direction === "backward";
+	const deletePos = isBackward ? $from.pos - 1 : $from.pos;
+	const deleteEnd = isBackward ? $from.pos : $from.pos + 1;
+	if (deletePos < 0 || deleteEnd > state.doc.content.size) return true;
+	const nodeAfter = state.doc.resolve(deletePos).nodeAfter;
+	if (!nodeAfter || !(nodeAfter.isText || nodeAfter.isInline && nodeAfter.type.allowsMarkType(deletionType))) return false;
+	const hasOwnInsertion = nodeAfter.marks.some((m) => m.type === insertionType && m.attrs["author"] === pluginState.author);
+	if (nodeAfter.marks.some((m) => m.type === deletionType)) {
+		const newPos = isBackward ? deletePos : deleteEnd;
+		tr.setSelection(TextSelection.near(tr.doc.resolve(newPos)));
+	} else if (hasOwnInsertion) tr.delete(deletePos, deleteEnd);
+	else {
+		const delAttrs = findAdjacentRevisionForRange(state.doc, deletePos, deleteEnd, "deletion", pluginState.author) || makeMarkAttrs(pluginState);
+		tr.addMark(deletePos, deleteEnd, deletionType.create(delAttrs));
+		const newPos = isBackward ? deletePos : deleteEnd;
+		tr.setSelection(TextSelection.near(tr.doc.resolve(newPos)));
+	}
+	dispatch(tr.scrollIntoView());
+	return true;
+}
+/**
+* Mark the text committed by an IME composition as a tracked insertion.
+*
+* Invoked from `compositionend` (deferred to a microtask) rather than from the
+* `appendTransaction` catch-all. ProseMirror commits composed text as part of
+* its own composition-end flush; adding the insertion mark *synchronously*
+* during that flush re-wraps the very text node the IME just finalized, which
+* corrupts CJK (Japanese / Chinese / Korean) input — characters duplicate or
+* garble. Running one tick later, after the composition has settled, wraps the
+* committed range safely. `markRangeAsInserted` skips nodes that already carry a
+* tracked-change mark, so this is idempotent. eigenpal/docx-editor#938.
+*/
+function markComposedAsInsertion(view, from, pluginState) {
+	const insertionType = view.state.schema.marks["insertion"];
+	const deletionType = view.state.schema.marks["deletion"];
+	if (!insertionType || !deletionType) return;
+	const to = view.state.selection.to;
+	if (to <= from) return;
+	const tr = view.state.tr;
+	tr.setMeta(SUGGESTION_META, true);
+	const markAttrs = findAdjacentRevisionForRange(view.state.doc, from, to, "insertion", pluginState.author) || makeMarkAttrs(pluginState);
+	markRangeAsInserted(tr, view.state.doc, from, to, insertionType, deletionType, markAttrs);
+	if (tr.steps.length === 0) return;
+	const caret = tr.mapping.map(to);
+	tr.setSelection(TextSelection.create(tr.doc, caret));
+	view.dispatch(tr);
+}
+/**
+* Create the suggestion mode plugin.
+* When active, text edits become tracked changes.
+*/
+function createSuggestionModePlugin(initialActive = false, author = "User") {
+	let composing = false;
+	let compositionFrom = null;
+	return new Plugin({
+		key: suggestionModeKey,
+		state: {
+			init() {
+				return {
+					active: initialActive,
+					author
+				};
+			},
+			apply(tr, state) {
+				const meta = tr.getMeta(suggestionModeKey);
+				if (meta) return {
+					...state,
+					...meta
+				};
+				return state;
+			}
+		},
+		props: {
+			handleDOMEvents: {
+				compositionstart(view) {
+					const pluginState = suggestionModeKey.getState(view.state);
+					if (!pluginState?.active) return false;
+					composing = true;
+					const { from, to } = view.state.selection;
+					if (from !== to) {
+						const insertionType = view.state.schema.marks["insertion"];
+						const deletionType = view.state.schema.marks["deletion"];
+						if (insertionType && deletionType) {
+							const tr = view.state.tr;
+							tr.setMeta(SUGGESTION_META, true);
+							markRangeAsDeleted(tr, view.state.doc, from, to, insertionType, deletionType, pluginState);
+							const caret = tr.mapping.map(to);
+							tr.setSelection(TextSelection.create(tr.doc, caret));
+							view.dispatch(tr);
+							compositionFrom = caret;
+							return false;
+						}
+					}
+					compositionFrom = from;
+					return false;
+				},
+				compositionend(view) {
+					const pluginState = suggestionModeKey.getState(view.state);
+					const from = compositionFrom;
+					compositionFrom = null;
+					if (!pluginState?.active || from == null) {
+						composing = false;
+						return false;
+					}
+					queueMicrotask(() => {
+						try {
+							const current = suggestionModeKey.getState(view.state);
+							if (current?.active) markComposedAsInsertion(view, from, current);
+						} finally {
+							composing = false;
+						}
+					});
+					return false;
+				},
+				beforeinput(view, event) {
+					const pluginState = suggestionModeKey.getState(view.state);
+					if (!pluginState?.active) return false;
+					if (composing || event.isComposing) return false;
+					if (event.inputType === "insertText" && event.data) {
+						event.preventDefault();
+						const { from, to } = view.state.selection;
+						return applySuggestionInsert(view, from, to, event.data, pluginState);
+					}
+					return false;
+				}
+			},
+			handleKeyDown(view, event) {
+				const pluginState = suggestionModeKey.getState(view.state);
+				if (!pluginState?.active) return false;
+				if (event.key === "Enter") return handleSuggestionEnter(view, pluginState);
+				if (event.key === "Backspace" || event.key === "Delete") {
+					const boundaryTarget = paragraphBoundaryTarget(view.state, event.key === "Backspace" ? "backward" : "forward");
+					if (boundaryTarget !== null) return applyPPrDel(view, boundaryTarget, pluginState);
+					const direction = event.key === "Backspace" ? "backward" : "forward";
+					return handleSuggestionDelete(view.state, view.dispatch, direction);
+				}
+				return false;
+			},
+			handleTextInput(view, from, to, text) {
+				const pluginState = suggestionModeKey.getState(view.state);
+				if (!pluginState?.active) return false;
+				if (composing || view.composing) return false;
+				return applySuggestionInsert(view, from, to, text, pluginState);
+			},
+			handlePaste(view, _event, slice) {
+				const pluginState = suggestionModeKey.getState(view.state);
+				if (!pluginState?.active) return false;
+				return handleSuggestionPaste(view, slice, pluginState);
+			}
+		},
+		appendTransaction(transactions, _oldState, newState) {
+			const pluginState = suggestionModeKey.getState(newState);
+			if (!pluginState?.active) return null;
+			if (composing) return null;
+			const userTr = transactions.find((tr) => tr.docChanged && !tr.getMeta("suggestionModeApplied") && !tr.getMeta("suggestionModeBypass") && !isHistoryTransaction(tr));
+			if (!userTr) return null;
+			const insertionType = newState.schema.marks["insertion"];
+			if (!insertionType) return null;
+			const markAttrs = makeMarkAttrs(pluginState);
+			const tr = newState.tr;
+			tr.setMeta(SUGGESTION_META, true);
+			const deletionType = newState.schema.marks["deletion"];
+			for (const step of userTr.steps) step.getMap().forEach((_oldFrom, _oldTo, newFrom, newTo) => {
+				if (newTo > newFrom) newState.doc.nodesBetween(newFrom, newTo, (node, pos) => {
+					if (!node.isText && !(node.isInline && node.type.allowsMarkType(insertionType))) return;
+					if (!node.marks.some((m) => m.type === insertionType || deletionType && m.type === deletionType)) {
+						const nodeStart = Math.max(pos, newFrom);
+						const nodeEnd = Math.min(pos + node.nodeSize, newTo);
+						tr.addMark(nodeStart, nodeEnd, insertionType.create(markAttrs));
+					}
+				});
+			});
+			return tr.steps.length > 0 ? tr : null;
+		}
+	});
+}
+/**
+* Toggle suggestion mode on/off.
+*/
+function toggleSuggestionMode(state, dispatch) {
+	const current = suggestionModeKey.getState(state);
+	if (!current) return false;
+	if (dispatch) dispatch(state.tr.setMeta(suggestionModeKey, { active: !current.active }));
+	return true;
+}
+/**
+* Set suggestion mode active state and author.
+*/
+function setSuggestionMode(active, state, dispatch, author) {
+	if (dispatch) {
+		const meta = { active };
+		if (author !== void 0) meta.author = author;
+		dispatch(state.tr.setMeta(suggestionModeKey, meta));
+	}
+	return true;
+}
+/**
+* Check if suggestion mode is currently active.
+*/
+function isSuggestionModeActive(state) {
+	return suggestionModeKey.getState(state)?.active ?? false;
+}
+//#endregion
+export { SUGGESTION_BYPASS_META, SUGGESTION_META, createSuggestionModePlugin, handleSuggestionEnter, handleSuggestionPaste, isSuggestionModeActive, makeRevisionInfo, paragraphBoundaryTarget, setSuggestionMode, suggestionModeKey, toggleSuggestionMode };

package/dist/prosemirror/plugins/templateDirectives.d.ts

@@ -0,0 +1,25 @@
+import { DocScanState } from "./createDocScanPlugin.js";
+import { EditorState, PluginKey } from "prosemirror-state";
+import { Node } from "prosemirror-model";
+import { DirectiveKind } from "@stll/template-conditions";
+
+//#region src/prosemirror/plugins/templateDirectives.d.ts
+type DirectiveRange = {
+  /** Inclusive PM doc position of the marker start. */from: number; /** Exclusive PM doc position of the marker end. */
+  to: number;
+  kind: DirectiveKind; /** Field path, clause name, or condition/loop expression. */
+  expr: string; /** Clause-slot version selector, e.g. "v3" or "latest". */
+  clauseVersion?: string; /** True for block directives that occupy their own paragraph. */
+  block: boolean;
+};
+declare const scanDirectives: (doc: Node) => DirectiveRange[];
+declare const templateDirectivesKey: PluginKey<DocScanState<undefined, DirectiveRange>>;
+type TemplateDirectivesPluginOptions = {
+  onRangesChange?: (ranges: readonly DirectiveRange[]) => void;
+};
+declare const createTemplateDirectivesPlugin: ({
+  onRangesChange
+}?: TemplateDirectivesPluginOptions) => import("prosemirror-state").Plugin<DocScanState<undefined, DirectiveRange>>;
+declare const getTemplateDirectives: (state: EditorState) => readonly DirectiveRange[];
+//#endregion
+export { type DirectiveKind, DirectiveRange, TemplateDirectivesPluginOptions, createTemplateDirectivesPlugin, getTemplateDirectives, scanDirectives, templateDirectivesKey };

package/dist/prosemirror/plugins/templateDirectives.js

@@ -0,0 +1,67 @@
+import { collectBlockChunks, joinChunks, offsetToDocPos } from "./pmTextScan.js";
+import { createDocScanPlugin, getDocScanRanges } from "./createDocScanPlugin.js";
+import { PluginKey } from "prosemirror-state";
+import { assertNever, isBlockDirectiveKind, scanMarkers } from "@stll/template-conditions";
+//#region src/prosemirror/plugins/templateDirectives.ts
+/** The display expression for a marker (field path, clause name, key, condition). */
+const directiveExpr = (meta) => {
+	switch (meta.kind) {
+		case "placeholder": return meta.expr;
+		case "clause": return meta.name;
+		case "num":
+		case "ref": return meta.key;
+		case "if":
+		case "elseif":
+		case "each": return meta.expr;
+		case "index":
+		case "count":
+		case "else":
+		case "endif":
+		case "endeach": return "";
+		default: return assertNever(meta);
+	}
+};
+const scanDirectives = (doc) => {
+	const ranges = [];
+	for (const chunks of collectBlockChunks(doc)) {
+		const joined = joinChunks(chunks);
+		const trimmed = joined.trim();
+		const lineMarkers = scanMarkers(trimmed);
+		const sole = lineMarkers.length === 1 ? lineMarkers[0] : void 0;
+		if (sole && sole.raw === trimmed && isBlockDirectiveKind(sole.meta.kind)) {
+			const last = chunks.at(-1);
+			ranges.push({
+				from: chunks[0]?.start ?? 0,
+				to: last ? last.start + last.text.length : 0,
+				kind: sole.meta.kind,
+				expr: directiveExpr(sole.meta),
+				block: true
+			});
+			continue;
+		}
+		for (const marker of scanMarkers(joined)) {
+			const clauseVersion = marker.meta.kind === "clause" ? marker.meta.version : void 0;
+			ranges.push({
+				from: offsetToDocPos(chunks, marker.start),
+				to: offsetToDocPos(chunks, marker.end),
+				kind: marker.meta.kind,
+				expr: directiveExpr(marker.meta),
+				block: false,
+				...clauseVersion !== void 0 ? { clauseVersion } : {}
+			});
+		}
+	}
+	return ranges;
+};
+const KEY_HOLDER_SYMBOL = Symbol.for("stll.folio.templateDirectivesKey");
+const keyHolder = globalThis;
+const templateDirectivesKey = keyHolder[KEY_HOLDER_SYMBOL] ?? (keyHolder[KEY_HOLDER_SYMBOL] = new PluginKey("templateDirectives"));
+const createTemplateDirectivesPlugin = ({ onRangesChange } = {}) => createDocScanPlugin({
+	key: templateDirectivesKey,
+	initialConfig: void 0,
+	scan: (doc) => scanDirectives(doc),
+	...onRangesChange ? { onRangesChange } : {}
+});
+const getTemplateDirectives = (state) => getDocScanRanges(templateDirectivesKey, state);
+//#endregion
+export { createTemplateDirectivesPlugin, getTemplateDirectives, scanDirectives, templateDirectivesKey };

package/dist/prosemirror/plugins/templatePreviewValues.d.ts

@@ -0,0 +1,49 @@
+import { Plugin, PluginKey } from "prosemirror-state";
+import { DecorationSet, EditorView } from "prosemirror-view";
+
+//#region src/prosemirror/plugins/templatePreviewValues.d.ts
+/** One formatted span of a rich preview value. The flags layer over the
+ *  marker's host formatting: a host-bold marker keeps its bold, a span's
+ *  own bold/italic ORs in on top. */
+type TemplatePreviewSpan = {
+  text: string;
+  bold?: boolean;
+  italic?: boolean;
+};
+/** A preview value: plain text, or formatted spans when the value carries
+ *  its own bold/italic (e.g. a registry lookup's formatted rendering). */
+type TemplatePreviewValue = string | {
+  runs: TemplatePreviewSpan[];
+};
+/** Concatenated plain text of a preview value. */
+declare const templatePreviewValueText: (value: TemplatePreviewValue) => string;
+/** Stable identity of a preview value (text + formatting), for decoration
+ *  keys and change detection. Distinguishes a plain string from a rich
+ *  value with the same text. */
+declare const templatePreviewValueFingerprint: (value: TemplatePreviewValue) => string;
+type TemplatePreviewValues = {
+  /** Field path → value to display in place of `{{path}}` markers. */values: Record<string, TemplatePreviewValue>; /** `highlighted` marks substitutions with the preview accent. */
+  mode: "highlighted" | "plain";
+};
+/**
+ * One `{{path}}` marker matched by an active preview value. Exposed on
+ * the plugin state so the paged editor (whose visible pages never see
+ * PM decorations) can project the same substitutions onto its overlay.
+ */
+type TemplatePreviewEntry = {
+  /** Inclusive PM doc position of the marker start. */from: number; /** Exclusive PM doc position of the marker end. */
+  to: number; /** Field path the marker resolves to. */
+  expr: string; /** The typed value displayed in place of the marker. */
+  value: TemplatePreviewValue;
+};
+type TemplatePreviewState = {
+  preview: TemplatePreviewValues | null;
+  entries: TemplatePreviewEntry[];
+  decorationSet: DecorationSet;
+};
+declare const templatePreviewValuesKey: PluginKey<TemplatePreviewState>;
+declare function createTemplatePreviewValuesPlugin(): Plugin<TemplatePreviewState>;
+/** Push (or clear, with `null`) the live fill preview into the editor. */
+declare const setTemplatePreviewValues: (view: EditorView, preview: TemplatePreviewValues | null) => void;
+//#endregion
+export { TemplatePreviewEntry, TemplatePreviewSpan, TemplatePreviewValue, TemplatePreviewValues, createTemplatePreviewValuesPlugin, setTemplatePreviewValues, templatePreviewValueFingerprint, templatePreviewValueText, templatePreviewValuesKey };