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

package/dist/prosemirror/plugins/autocompleteSuggestion.js

@@ -0,0 +1,283 @@
+import { Plugin, PluginKey } from "prosemirror-state";
+import { Decoration, DecorationSet } from "prosemirror-view";
+//#region src/prosemirror/plugins/autocompleteSuggestion.ts
+const IDLE = {
+	status: "idle",
+	anchor: null,
+	text: "",
+	requestId: null
+};
+const KEY_HOLDER_SYMBOL = Symbol.for("stll.folio.autocompleteSuggestionKey");
+const keyHolder = globalThis;
+const autocompleteSuggestionKey = keyHolder[KEY_HOLDER_SYMBOL] ?? (keyHolder[KEY_HOLDER_SYMBOL] = new PluginKey("autocompleteSuggestion"));
+const buildAnchorWidget = () => {
+	const el = document.createElement("span");
+	el.dataset["folioAutocompleteAnchor"] = "true";
+	el.style.cssText = "display:inline-block;width:0;height:0;";
+	return el;
+};
+const buildInlineGhost = (text, isStreaming) => {
+	const ghost = document.createElement("span");
+	ghost.className = "folio-autocomplete-ghost";
+	ghost.append(document.createTextNode(text));
+	const caret = document.createElement("span");
+	caret.className = isStreaming ? "folio-autocomplete-caret folio-autocomplete-caret--streaming" : "folio-autocomplete-caret";
+	caret.setAttribute("aria-hidden", "true");
+	caret.append(document.createTextNode("stella"));
+	ghost.append(caret);
+	return ghost;
+};
+const buildDecorations = (state, doc, options) => {
+	if (state.status === "idle") return DecorationSet.empty;
+	const anchor = Math.max(0, Math.min(state.anchor, doc.content.size));
+	const isStreaming = state.status === "streaming";
+	const render = options.renderInline ? () => buildInlineGhost(state.text, isStreaming) : buildAnchorWidget;
+	return DecorationSet.create(doc, [Decoration.widget(anchor, render, {
+		side: 1,
+		ignoreSelection: true,
+		key: `stll-autocomplete:${state.text.length}:${state.requestId}`
+	})]);
+};
+const reduce = (prev, meta) => {
+	if (meta.type === "clear") return IDLE;
+	if (meta.type === "start") return {
+		status: "streaming",
+		anchor: meta.anchor,
+		text: "",
+		requestId: meta.requestId
+	};
+	if (meta.type === "token") {
+		if (prev.status === "idle" || prev.requestId !== meta.requestId) return prev;
+		return {
+			...prev,
+			status: "streaming",
+			text: prev.text + meta.delta
+		};
+	}
+	if (meta.type === "consume") {
+		if (prev.status === "idle" || prev.requestId !== meta.requestId) return prev;
+		if (meta.consumed.length >= prev.text.length) return IDLE;
+		return {
+			...prev,
+			anchor: prev.anchor + meta.consumed.length,
+			text: prev.text.slice(meta.consumed.length)
+		};
+	}
+	if (prev.status === "idle" || prev.requestId !== meta.requestId) return prev;
+	if (prev.text.length === 0) return IDLE;
+	return {
+		...prev,
+		status: "shown"
+	};
+};
+const autocompleteSuggestionPlugin = (options = {}) => {
+	const resolved = {
+		renderInline: options.renderInline ?? false,
+		keymap: options.keymap ?? false
+	};
+	return new Plugin({
+		key: autocompleteSuggestionKey,
+		state: {
+			init: (_config, instance) => ({
+				suggestion: IDLE,
+				decorations: buildDecorations(IDLE, instance.doc, resolved)
+			}),
+			apply: (tr, value, _oldState, newState) => {
+				const meta = tr.getMeta(autocompleteSuggestionKey);
+				if (!meta) {
+					if (tr.docChanged && value.suggestion.status !== "idle") return {
+						suggestion: IDLE,
+						decorations: DecorationSet.empty
+					};
+					return value;
+				}
+				const nextSuggestion = reduce(value.suggestion, meta);
+				return {
+					suggestion: nextSuggestion,
+					decorations: buildDecorations(nextSuggestion, newState.doc, resolved)
+				};
+			}
+		},
+		props: {
+			decorations(state) {
+				return autocompleteSuggestionKey.getState(state)?.decorations ?? null;
+			},
+			...resolved.keymap ? { handleKeyDown: (view, event) => {
+				const current = autocompleteSuggestionKey.getState(view.state)?.suggestion ?? IDLE;
+				if (current.status !== "shown" && current.status !== "streaming") return false;
+				const isMod = event.metaKey || event.ctrlKey;
+				if (event.key === "Tab" && !event.shiftKey && !isMod) {
+					if (acceptAutocompleteSuggestion(view.state, view.dispatch).accepted) {
+						event.preventDefault();
+						return true;
+					}
+					return false;
+				}
+				if (event.key === "ArrowRight" && isMod && !event.shiftKey) {
+					if (acceptAutocompleteWord(view.state, view.dispatch).accepted) {
+						event.preventDefault();
+						return true;
+					}
+					return false;
+				}
+				if (event.key === "Escape" && !isMod && !event.shiftKey) {
+					view.dispatch(clearAutocompleteSuggestion(view.state.tr));
+					event.preventDefault();
+					return true;
+				}
+				return false;
+			} } : {}
+		}
+	});
+};
+const getAutocompleteSuggestion = (state) => autocompleteSuggestionKey.getState(state)?.suggestion ?? IDLE;
+const startAutocompleteSuggestion = (tr, anchor, requestId) => tr.setMeta(autocompleteSuggestionKey, {
+	type: "start",
+	anchor,
+	requestId
+});
+const appendAutocompleteToken = (tr, requestId, delta) => tr.setMeta(autocompleteSuggestionKey, {
+	type: "token",
+	requestId,
+	delta
+});
+const finishAutocompleteSuggestion = (tr, requestId) => tr.setMeta(autocompleteSuggestionKey, {
+	type: "finish",
+	requestId
+});
+const clearAutocompleteSuggestion = (tr) => tr.setMeta(autocompleteSuggestionKey, { type: "clear" });
+/**
+* Commit the current suggestion as a real text insertion at its
+* anchor. Returns metadata so the caller can record the accept
+* event (for telemetry / future training feedback) without
+* re-reading plugin state after the dispatch.
+*
+* Single transaction: insert text + clear suggestion state, so
+* undo restores both the doc and the (now-gone) ghost atomically.
+*/
+const acceptAutocompleteSuggestion = (state, dispatch) => {
+	const current = getAutocompleteSuggestion(state);
+	if (current.status !== "shown" && current.status !== "streaming") return { accepted: false };
+	if (current.text.length === 0) return { accepted: false };
+	if (dispatch) {
+		const tr = state.tr.insertText(current.text, current.anchor);
+		clearAutocompleteSuggestion(tr);
+		dispatch(tr);
+	}
+	return {
+		accepted: true,
+		from: current.anchor,
+		to: current.anchor + current.text.length,
+		text: current.text
+	};
+};
+/**
+* Consume the next "word" from the suggestion: insert it at the
+* anchor in a single transaction and shrink the remaining ghost
+* text. Lets the user "graze" through a long suggestion one word
+* at a time with ⌘→ / Ctrl→ instead of accept-all-or-discard.
+*
+* A word here is "leading whitespace + the next non-whitespace
+* run + an optional trailing space" — so successive calls eat the
+* suggestion cleanly without leaving stray spaces. When the
+* remaining suggestion is shorter than one word, this falls
+* through to {@link acceptAutocompleteSuggestion}.
+*/
+const acceptAutocompleteWord = (state, dispatch) => {
+	const current = getAutocompleteSuggestion(state);
+	if (current.status !== "shown" && current.status !== "streaming") return { accepted: false };
+	if (current.text.length === 0) return { accepted: false };
+	const match = /^(?<word>\s*\S+\s?)/u.exec(current.text);
+	const word = match === null ? current.text : match.groups?.["word"];
+	if (word === void 0 || word.length === 0) return { accepted: false };
+	if (word.length >= current.text.length) return acceptAutocompleteSuggestion(state, dispatch);
+	if (dispatch) {
+		const tr = state.tr.insertText(word, current.anchor);
+		tr.setMeta(autocompleteSuggestionKey, {
+			type: "consume",
+			requestId: current.requestId,
+			consumed: word
+		});
+		dispatch(tr);
+	}
+	return {
+		accepted: true,
+		from: current.anchor,
+		to: current.anchor + word.length,
+		text: word
+	};
+};
+/**
+* Node type names that should suppress autocomplete entirely. The
+* defaults cover prose-adjacent zones across ProseMirror schemas
+* we encounter in folio + bare playgrounds. Pass a custom list via
+* options to extend (citations, math, frontmatter, etc.).
+*/
+const DEFAULT_AUTOCOMPLETE_DEAD_ZONE_NODES = [
+	"heading",
+	"title",
+	"code",
+	"code_block",
+	"codeBlock",
+	"horizontal_rule",
+	"horizontalRule",
+	"math_block",
+	"math_inline",
+	"inline_math",
+	"inlineMath",
+	"equation",
+	"citation",
+	"citationPreview",
+	"pendingCitation",
+	"image",
+	"imageBlock"
+];
+const WORD_CONTINUATION_CHAR = /[\p{L}\p{N}_'-]/u;
+/**
+* Decide whether autocomplete should fire at the current cursor.
+* Designed to be called from a debounced trigger in the host app
+* before sending a request to the model. Returns a structured
+* skip reason rather than a bare boolean so callers (and debug
+* UIs) can explain why no suggestion appeared.
+*
+* Gates applied:
+*  - selection must be a collapsed caret (no range selection)
+*  - the cursor must not be inside a dead-zone node (heading,
+*    code, citation, math, etc.) anywhere in the ancestor chain
+*  - the character immediately before the cursor must not be a
+*    word-continuation char — if it is, the model would be
+*    completing a partial token and almost always misreads intent
+*/
+const shouldTriggerAutocomplete = (state, options) => {
+	const sel = state.selection;
+	if (!sel.empty) return {
+		ok: false,
+		reason: "selection-non-empty"
+	};
+	if (state.doc.content.size === 0) return {
+		ok: false,
+		reason: "empty-doc"
+	};
+	const $cursor = sel.$from;
+	const deadZones = /* @__PURE__ */ new Set([...DEFAULT_AUTOCOMPLETE_DEAD_ZONE_NODES, ...options?.extraDeadZoneNodes ?? []]);
+	for (let depth = $cursor.depth; depth >= 0; depth--) {
+		const nodeName = $cursor.node(depth).type.name;
+		if (deadZones.has(nodeName)) return {
+			ok: false,
+			reason: "deadzone",
+			detail: nodeName
+		};
+	}
+	const parentOffset = $cursor.parentOffset;
+	if (parentOffset > 0) {
+		const before = $cursor.parent.textBetween(parentOffset - 1, parentOffset, "\n", "\n");
+		if (before.length > 0 && WORD_CONTINUATION_CHAR.test(before)) return {
+			ok: false,
+			reason: "midword",
+			detail: before
+		};
+	}
+	return { ok: true };
+};
+//#endregion
+export { DEFAULT_AUTOCOMPLETE_DEAD_ZONE_NODES, acceptAutocompleteSuggestion, acceptAutocompleteWord, appendAutocompleteToken, autocompleteSuggestionKey, autocompleteSuggestionPlugin, clearAutocompleteSuggestion, finishAutocompleteSuggestion, getAutocompleteSuggestion, shouldTriggerAutocomplete, startAutocompleteSuggestion };

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

@@ -0,0 +1,56 @@
+import { ContentControlLockedError, ContentControlTypeError } from "../../content-controls/errors.js";
+import { Plugin, PluginKey } from "prosemirror-state";
+import { EditorView } from "prosemirror-view";
+
+//#region src/prosemirror/plugins/contentControlWidgets.d.ts
+type ContentControlWidgetEvent = {
+  kind: "dropdownOpen";
+  tag: string; /** PM position of the clicked SDT instance — disambiguates duplicates. */
+  pmPos: number;
+  sdtType: "dropdown" | "comboBox";
+  anchor: HTMLElement;
+  listItemsJson: string | undefined;
+} | {
+  kind: "datePick";
+  tag: string;
+  pmPos: number;
+  anchor: HTMLElement;
+  currentValue: string | undefined;
+} | {
+  /**
+   * The plugin refused a click because the control's `w:lock` or type
+   * forbade the interaction. The shell decides how to surface this —
+   * toast, telemetry, or no-op. The plugin itself never logs.
+   */
+  kind: "refused";
+  tag: string;
+  pmPos: number;
+  sdtType: string;
+  anchor: HTMLElement;
+  error: ContentControlLockedError | ContentControlTypeError;
+};
+type ContentControlWidgetCallback = (event: ContentControlWidgetEvent) => void;
+declare const contentControlWidgetsPluginKey: PluginKey<unknown>;
+/**
+ * CustomEvent name dispatched on the editor view DOM whenever the plugin
+ * needs to surface a `ContentControlWidgetEvent` to the React shell. The
+ * shell subscribes via `addEventListener` and renders the matching chrome.
+ *
+ * Using a CustomEvent keeps the plugin from owning a React reference and
+ * makes the host's responsibility explicit: receive event → render UI →
+ * call dispatchDropdownPick / dispatchDatePick.
+ */
+declare const CONTENT_CONTROL_WIDGET_EVENT_NAME = "folio:content-control-widget";
+declare function createContentControlWidgetsPlugin(onEvent?: ContentControlWidgetCallback): Plugin;
+/**
+ * Stable resolver helpers exposed for the UI shell so a popover menu or
+ * date picker can dispatch the same transaction the plugin would.
+ *
+ * Both take the PM `pmPos` of the clicked SDT (from the widget event's
+ * `pmPos` field) so the dispatch lands on the exact instance the user
+ * interacted with — duplicate-tag SDTs are no longer ambiguous.
+ */
+declare function dispatchDropdownPick(view: EditorView, pmPos: number, value: string): boolean;
+declare function dispatchDatePick(view: EditorView, pmPos: number, date: string): boolean;
+//#endregion
+export { CONTENT_CONTROL_WIDGET_EVENT_NAME, ContentControlWidgetCallback, ContentControlWidgetEvent, contentControlWidgetsPluginKey, createContentControlWidgetsPlugin, dispatchDatePick, dispatchDropdownPick };

package/dist/prosemirror/plugins/contentControlWidgets.js

@@ -0,0 +1,192 @@
+import { ContentControlLockedError, ContentControlTypeError } from "../../content-controls/errors.js";
+import { findBlockSdtMatch, setContentControlValueTr } from "../commands/contentControls.js";
+import { Plugin, PluginKey } from "prosemirror-state";
+//#region src/prosemirror/plugins/contentControlWidgets.ts
+/**
+* Interactive content-control widget delegation.
+*
+* Painted blocks inside a typed SDT carry `data-sdt-type` (checkbox /
+* dropdown / date) and `data-sdt-tag` thanks to `applySdtDataAttrs`. This
+* plugin watches editor-region clicks: when the user clicks inside a typed
+* control it dispatches the appropriate `setContentControlValueTr` so the
+* mutation goes through the normal undo stack.
+*
+* The checkbox path is fully wired (a click toggles the modeled state and
+* the rendered glyph). Dropdown and date paths emit the dispatch hook so the
+* higher-level UI (a popover menu / date picker rendered by the editor
+* shell) can subscribe; the plugin does not own the menu/picker chrome.
+*/
+const contentControlWidgetsPluginKey = new PluginKey("contentControlWidgets");
+/**
+* CustomEvent name dispatched on the editor view DOM whenever the plugin
+* needs to surface a `ContentControlWidgetEvent` to the React shell. The
+* shell subscribes via `addEventListener` and renders the matching chrome.
+*
+* Using a CustomEvent keeps the plugin from owning a React reference and
+* makes the host's responsibility explicit: receive event → render UI →
+* call dispatchDropdownPick / dispatchDatePick.
+*/
+const CONTENT_CONTROL_WIDGET_EVENT_NAME = "folio:content-control-widget";
+function findSdtAncestor(target) {
+	if (!(target instanceof Element)) return null;
+	return target.closest("[data-sdt-type]");
+}
+function createContentControlWidgetsPlugin(onEvent = () => void 0) {
+	const emit = (view, payload) => {
+		onEvent(payload);
+		view.dom.dispatchEvent(new CustomEvent(CONTENT_CONTROL_WIDGET_EVENT_NAME, {
+			detail: payload,
+			bubbles: true
+		}));
+	};
+	return new Plugin({
+		key: contentControlWidgetsPluginKey,
+		props: { handleDOMEvents: { click(view, event) {
+			const anchor = findSdtAncestor(event.target);
+			if (!anchor) return false;
+			const tag = anchor.dataset["sdtTag"] ?? "";
+			const sdtType = anchor.dataset["sdtType"];
+			const pmPosRaw = anchor.dataset["sdtPmPos"];
+			const pmPos = pmPosRaw ? Number.parseInt(pmPosRaw, 10) : NaN;
+			if (!sdtType || Number.isNaN(pmPos)) return false;
+			try {
+				if (sdtType === "checkbox") {
+					const current = anchor.dataset["sdtChecked"] === "true";
+					const tr = setContentControlValueTr(view.state, { pmPos }, {
+						kind: "checkbox",
+						checked: !current
+					});
+					if (tr) {
+						view.dispatch(tr);
+						event.preventDefault();
+						return true;
+					}
+				} else if (sdtType === "dropdown" || sdtType === "comboBox") {
+					const refusal = lockRefusalFor(view, pmPos);
+					if (refusal) {
+						emit(view, {
+							kind: "refused",
+							tag,
+							pmPos,
+							sdtType,
+							anchor,
+							error: refusal
+						});
+						event.preventDefault();
+						return true;
+					}
+					emit(view, {
+						kind: "dropdownOpen",
+						tag,
+						pmPos,
+						sdtType,
+						anchor,
+						listItemsJson: anchor.dataset["sdtListItems"]
+					});
+					event.preventDefault();
+					return true;
+				} else if (sdtType === "date") {
+					const refusal = lockRefusalFor(view, pmPos);
+					if (refusal) {
+						emit(view, {
+							kind: "refused",
+							tag,
+							pmPos,
+							sdtType,
+							anchor,
+							error: refusal
+						});
+						event.preventDefault();
+						return true;
+					}
+					emit(view, {
+						kind: "datePick",
+						tag,
+						pmPos,
+						anchor,
+						currentValue: void 0
+					});
+					event.preventDefault();
+					return true;
+				}
+			} catch (error) {
+				if (error instanceof ContentControlLockedError || error instanceof ContentControlTypeError) {
+					emit(view, {
+						kind: "refused",
+						tag,
+						pmPos,
+						sdtType,
+						anchor,
+						error
+					});
+					return true;
+				}
+				throw error;
+			}
+			return false;
+		} } },
+		view() {
+			return {};
+		}
+	});
+}
+/**
+* Stable resolver helpers exposed for the UI shell so a popover menu or
+* date picker can dispatch the same transaction the plugin would.
+*
+* Both take the PM `pmPos` of the clicked SDT (from the widget event's
+* `pmPos` field) so the dispatch lands on the exact instance the user
+* interacted with — duplicate-tag SDTs are no longer ambiguous.
+*/
+function dispatchDropdownPick(view, pmPos, value) {
+	if (!findBlockSdtMatch(view.state.doc, { pmPos })) return false;
+	try {
+		const tr = setContentControlValueTr(view.state, { pmPos }, {
+			kind: "dropdown",
+			value
+		});
+		if (!tr) return false;
+		view.dispatch(tr);
+		return true;
+	} catch (error) {
+		if (error instanceof ContentControlLockedError || error instanceof ContentControlTypeError) return false;
+		throw error;
+	}
+}
+function dispatchDatePick(view, pmPos, date) {
+	try {
+		const tr = setContentControlValueTr(view.state, { pmPos }, {
+			kind: "date",
+			date
+		});
+		if (!tr) return false;
+		view.dispatch(tr);
+		return true;
+	} catch (error) {
+		if (error instanceof ContentControlLockedError || error instanceof ContentControlTypeError) return false;
+		throw error;
+	}
+}
+/**
+* Look up the clicked SDT by pmPos and return a typed refusal when the
+* lock state forbids content mutation (`contentLocked`,
+* `sdtContentLocked`). Returning `null` means "go ahead and open the
+* picker." Preflight at click time so locked dropdowns / date pickers
+* don't flash open just to close again when the user makes a selection.
+*/
+function lockRefusalFor(view, pmPos) {
+	const match = findBlockSdtMatch(view.state.doc, { pmPos });
+	if (!match) return null;
+	const lock = match.node.attrs["lock"];
+	if (lock !== "contentLocked" && lock !== "sdtContentLocked") return null;
+	const tag = match.node.attrs["tag"];
+	const alias = match.node.attrs["alias"];
+	return new ContentControlLockedError({
+		message: `Control "${tag ?? alias ?? "(unnamed)"}" has w:lock=${lock}.`,
+		lock,
+		...typeof tag === "string" ? { tag } : {},
+		...typeof alias === "string" ? { alias } : {}
+	});
+}
+//#endregion
+export { CONTENT_CONTROL_WIDGET_EVENT_NAME, contentControlWidgetsPluginKey, createContentControlWidgetsPlugin, dispatchDatePick, dispatchDropdownPick };

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

@@ -0,0 +1,37 @@
+import { EditorState, Plugin, PluginKey } from "prosemirror-state";
+import { Node } from "prosemirror-model";
+
+//#region src/prosemirror/plugins/createDocScanPlugin.d.ts
+declare const SET_META = "set";
+type DocScanState<TConfig, TRange> = {
+  config: TConfig;
+  ranges: readonly TRange[];
+};
+type DocScanPluginOptions<TConfig, TRange> = {
+  key: PluginKey<DocScanState<TConfig, TRange>>;
+  initialConfig: TConfig; /** Recompute the ranges from the current doc + config. */
+  scan: (doc: Node, config: TConfig) => TRange[];
+  /**
+   * Push-side bridge for hosts that mirror the current range list
+   * outside the PM state tree (counters, inspector facets). Called
+   * on init, after every transaction that changes the range set,
+   * and on teardown (with an empty list).
+   */
+  onRangesChange?: (ranges: readonly TRange[]) => void;
+};
+declare const createDocScanPlugin: <TConfig, TRange>({
+  key,
+  initialConfig,
+  scan,
+  onRangesChange
+}: DocScanPluginOptions<TConfig, TRange>) => Plugin<DocScanState<TConfig, TRange>>;
+declare const setDocScanConfigMeta: <TConfig, TRange>(key: PluginKey<DocScanState<TConfig, TRange>>, config: TConfig) => {
+  key: PluginKey<DocScanState<TConfig, TRange>>;
+  payload: {
+    type: typeof SET_META;
+    config: TConfig;
+  };
+};
+declare const getDocScanRanges: <TConfig, TRange>(key: PluginKey<DocScanState<TConfig, TRange>>, state: EditorState) => readonly TRange[];
+//#endregion
+export { DocScanPluginOptions, DocScanState, createDocScanPlugin, getDocScanRanges, setDocScanConfigMeta };

package/dist/prosemirror/plugins/createDocScanPlugin.js

@@ -0,0 +1,55 @@
+import { Plugin } from "prosemirror-state";
+//#region src/prosemirror/plugins/createDocScanPlugin.ts
+const SET_META = "set";
+const createDocScanPlugin = ({ key, initialConfig, scan, onRangesChange }) => {
+	const spec = {
+		key,
+		state: {
+			init(_config, instance) {
+				return {
+					config: initialConfig,
+					ranges: scan(instance.doc, initialConfig)
+				};
+			},
+			apply(tr, prev, _oldState, newState) {
+				const setMeta = tr.getMeta(key);
+				if (setMeta?.type === SET_META) return {
+					config: setMeta.config,
+					ranges: scan(newState.doc, setMeta.config)
+				};
+				if (tr.docChanged) return {
+					config: prev.config,
+					ranges: scan(newState.doc, prev.config)
+				};
+				return prev;
+			}
+		}
+	};
+	if (onRangesChange) spec.view = (view) => {
+		let last = key.getState(view.state)?.ranges;
+		if (last) onRangesChange(last);
+		return {
+			update(updatedView) {
+				const next = key.getState(updatedView.state)?.ranges;
+				if (next && next !== last) {
+					last = next;
+					onRangesChange(next);
+				}
+			},
+			destroy() {
+				onRangesChange([]);
+			}
+		};
+	};
+	return new Plugin(spec);
+};
+const setDocScanConfigMeta = (key, config) => ({
+	key,
+	payload: {
+		type: SET_META,
+		config
+	}
+});
+const getDocScanRanges = (key, state) => key.getState(state)?.ranges ?? [];
+//#endregion
+export { createDocScanPlugin, getDocScanRanges, setDocScanConfigMeta };

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

@@ -0,0 +1,18 @@
+import { document_d_exports } from "../../types/document.js";
+import { StyleResolver } from "../styles/styleResolver.js";
+import { EditorState, Plugin, PluginKey } from "prosemirror-state";
+
+//#region src/prosemirror/plugins/documentStyles.d.ts
+declare const documentStylesKey: PluginKey<StyleResolver | null>;
+/**
+ * Create the plugin holding a StyleResolver for the document's `styles` for
+ * the lifetime of the EditorState. The resolver is fixed per document load;
+ * loading a new document recreates the state (and thus this plugin) with a
+ * fresh resolver. Accepts a pre-built resolver too, for callers that already
+ * have one.
+ */
+declare function createDocumentStylesPlugin(styles: document_d_exports.StyleDefinitions | StyleResolver | null | undefined): Plugin;
+/** Read the document's StyleResolver, or null when the plugin isn't installed. */
+declare function getDocumentStyleResolver(state: EditorState): StyleResolver | null;
+//#endregion
+export { createDocumentStylesPlugin, documentStylesKey, getDocumentStyleResolver };

package/dist/prosemirror/plugins/documentStyles.js

@@ -0,0 +1,46 @@
+import { StyleResolver, createStyleResolver } from "../styles/styleResolver.js";
+import { Plugin, PluginKey } from "prosemirror-state";
+//#region src/prosemirror/plugins/documentStyles.ts
+/**
+* documentStyles plugin — makes the document's StyleResolver reachable from
+* ProseMirror commands.
+*
+* Styles otherwise flow one way (Document → PM) at load time: `toProseDoc`
+* bakes resolved formatting into nodes and discards the resolver. Some
+* commands need the live style table though — the Enter handler looks up a
+* paragraph style's `w:next` to switch to body text after a heading. This
+* plugin parks the resolver in plugin state so those commands can read it
+* via `getDocumentStyleResolver(state)`.
+*
+* The host (HiddenProseMirror / HiddenHeaderFooterPMs) passes the same
+* styles it hands to `toProseDoc` and adds this plugin when creating the
+* EditorState. When absent, style-aware commands fall back to their
+* style-agnostic behavior.
+*/
+const documentStylesKey = new PluginKey("documentStyles");
+/**
+* Create the plugin holding a StyleResolver for the document's `styles` for
+* the lifetime of the EditorState. The resolver is fixed per document load;
+* loading a new document recreates the state (and thus this plugin) with a
+* fresh resolver. Accepts a pre-built resolver too, for callers that already
+* have one.
+*/
+function createDocumentStylesPlugin(styles) {
+	let resolver;
+	if (styles instanceof StyleResolver) resolver = styles;
+	else if (styles) resolver = createStyleResolver(styles);
+	else resolver = null;
+	return new Plugin({
+		key: documentStylesKey,
+		state: {
+			init: () => resolver,
+			apply: (_tr, value) => value
+		}
+	});
+}
+/** Read the document's StyleResolver, or null when the plugin isn't installed. */
+function getDocumentStyleResolver(state) {
+	return documentStylesKey.getState(state) ?? null;
+}
+//#endregion
+export { createDocumentStylesPlugin, documentStylesKey, getDocumentStyleResolver };

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

@@ -0,0 +1,3 @@
+import { SelectionChangeCallback, SelectionContext, createSelectionTrackerPlugin, extractSelectionContext, getSelectionContext, selectionTrackerKey } from "./selectionTracker.js";
+import { createDocumentStylesPlugin, documentStylesKey, getDocumentStyleResolver } from "./documentStyles.js";
+export { type SelectionChangeCallback, type SelectionContext, createDocumentStylesPlugin, createSelectionTrackerPlugin, documentStylesKey, extractSelectionContext, getDocumentStyleResolver, getSelectionContext, selectionTrackerKey };