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

package/dist/content-controls/mutateContentControls.js

@@ -0,0 +1,377 @@
+import { formatDate } from "../docx/fieldParser.js";
+import { ContentControlBoundError, ContentControlLockedError, ContentControlTypeError } from "./errors.js";
+//#region src/content-controls/mutateContentControls.ts
+/**
+* Pure (immutable) write helpers for block-level content controls.
+*
+* Each helper returns a brand-new `Document` with the requested mutation
+* applied; the original document is never touched. Locked controls and
+* type-incompatible operations throw a tagged error unless `{ force: true }`
+* is passed. `w15:repeatingSection` controls cannot be unwrapped — doing so
+* would orphan their w15 row items.
+*/
+/**
+* Format an ISO 8601 date string using the SDT's modeled `dateFormat`. The
+* w:dateFormat tokens (yyyy/MM/dd/MMMM/HH/mm/ss/AM/PM, etc.) match what
+* `formatDate` already implements for the fields engine; reusing it keeps
+* both surfaces consistent.
+*
+* Returns the ISO input unchanged if the input does not parse as a date or
+* the format is missing — degrading gracefully is better than corrupting
+* the body.
+*/
+function formatDateForSdtBody(isoDate, dateFormat) {
+	if (!dateFormat) return isoDate;
+	const parsed = parseSdtDate(isoDate);
+	if (!parsed) return isoDate;
+	return formatDate(parsed, dateFormat);
+}
+/**
+* Parse an OOXML SDT date string. `new Date(iso)` parses the input as UTC
+* (a Pacific user would see the previous calendar day via local
+* accessors), so we instead read the ISO components into a local-midnight
+* Date so `formatDate`'s local-time accessors return the same calendar
+* date / wall-clock time in every timezone.
+*
+* Supports date-only (`YYYY-MM-DD`) and date+time (`YYYY-MM-DDTHH:mm[:ss]`)
+* inputs. The trailing `Z` / offset is intentionally ignored — for a date
+* SDT, what the user picked is the displayed wall time, not a moment in
+* UTC.
+*/
+const SDT_DATE_RE = /^(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})(?:[Tt](?<hours>\d{2}):(?<minutes>\d{2})(?::(?<seconds>\d{2})(?:\.\d+)?)?)?(?:[Zz]|[+-]\d{2}:?\d{2})?$/u;
+function parseSdtDate(iso) {
+	const match = SDT_DATE_RE.exec(iso);
+	if (match?.groups) {
+		const groups = match.groups;
+		const year = Number(groups["year"]);
+		const month = Number(groups["month"]);
+		const day = Number(groups["day"]);
+		const hours = groups["hours"] ? Number(groups["hours"]) : 0;
+		const minutes = groups["minutes"] ? Number(groups["minutes"]) : 0;
+		const seconds = groups["seconds"] ? Number(groups["seconds"]) : 0;
+		const candidate = new Date(year, month - 1, day, hours, minutes, seconds);
+		if (candidate.getFullYear() !== year || candidate.getMonth() !== month - 1 || candidate.getDate() !== day || candidate.getHours() !== hours || candidate.getMinutes() !== minutes || candidate.getSeconds() !== seconds) return null;
+		return candidate;
+	}
+	const parsed = new Date(iso);
+	return Number.isNaN(parsed.getTime()) ? null : parsed;
+}
+function throwLocked(control, lock) {
+	throw new ContentControlLockedError({
+		message: `Control "${control.properties.tag ?? control.properties.alias ?? "(unnamed)"}" has w:lock=${lock}.`,
+		lock,
+		...control.properties.tag !== void 0 ? { tag: control.properties.tag } : {},
+		...control.properties.alias !== void 0 ? { alias: control.properties.alias } : {}
+	});
+}
+/**
+* Refuse content mutations (setContentControlContent /
+* setContentControlValue) when `w:lock` forbids them.
+*
+* Per OOXML §17.5.2.16:
+* - `contentLocked` blocks content edits but allows the container to be
+*   removed.
+* - `sdtContentLocked` blocks both.
+* - `sdtLocked` blocks only container removal, NOT content edits.
+*/
+function ensureContentNotLocked(control, force) {
+	if (force) return;
+	const lock = control.properties.lock;
+	if (lock === "contentLocked" || lock === "sdtContentLocked") throwLocked(control, lock);
+}
+/**
+* Refuse container removal (removeContentControl) when `w:lock` forbids it.
+*
+* - `sdtLocked` blocks container removal but allows content edits.
+* - `sdtContentLocked` blocks both.
+* - `contentLocked` blocks only content edits, NOT container removal.
+*/
+function ensureSdtNotLocked(control, force) {
+	if (force) return;
+	const lock = control.properties.lock;
+	if (lock === "sdtLocked" || lock === "sdtContentLocked") throwLocked(control, lock);
+}
+function isRepeatingSection(control) {
+	const raw = control.properties.rawPropertiesXml;
+	return raw !== void 0 && REPEATING_SECTION_RE.test(raw);
+}
+const REPEATING_SECTION_RE = /<\w+:repeatingSection\b/u;
+const DATA_BINDING_RE = /<\w+:dataBinding\b(?<attrs>[^>]*)\/?>/iu;
+/**
+* Detect a `<w:dataBinding w:xpath="…"/>` (or alt-prefix variant) inside
+* the captured rawPropertiesXml + extract the xpath / storeItemID for
+* the error payload. Returns null when no binding is present.
+*/
+function readDataBinding(control) {
+	const raw = control.properties.rawPropertiesXml;
+	if (raw === void 0) return null;
+	const match = DATA_BINDING_RE.exec(raw);
+	if (!match) return null;
+	const attrs = match.groups?.["attrs"] ?? "";
+	const xpathMatch = /\bxpath="(?<xpath>[^"]*)"/iu.exec(attrs);
+	if (!xpathMatch) return null;
+	const xpath = xpathMatch.groups?.["xpath"] ?? "";
+	const storeMatch = /\bstoreItemID="(?<storeItemID>[^"]*)"/iu.exec(attrs);
+	if (storeMatch) return {
+		xpath,
+		storeItemID: storeMatch.groups?.["storeItemID"] ?? ""
+	};
+	return { xpath };
+}
+/**
+* Refuse content mutations on bound SDTs unless the caller passes
+* `{ force: true }`. When force is set, return the rawPropertiesXml
+* with the `<w:dataBinding>` element stripped so the caller's write
+* actually sticks on next Word open. See `ContentControlBoundError`
+* for the rationale.
+*/
+function ensureContentNotBound(control, force) {
+	const binding = readDataBinding(control);
+	if (!binding) return { strippedRawPropertiesXml: void 0 };
+	if (!force) throw new ContentControlBoundError({
+		message: `Control "${control.properties.tag ?? control.properties.alias ?? "(unnamed)"}" is bound to ${binding.xpath}. Word regenerates the body from the bound XML on open; pass { force: true } to strip the binding inline, or remove it explicitly before writing.`,
+		xpath: binding.xpath,
+		...binding.storeItemID !== void 0 ? { storeItemID: binding.storeItemID } : {},
+		...control.properties.tag !== void 0 ? { tag: control.properties.tag } : {},
+		...control.properties.alias !== void 0 ? { alias: control.properties.alias } : {}
+	});
+	const raw = control.properties.rawPropertiesXml;
+	if (raw === void 0) return { strippedRawPropertiesXml: void 0 };
+	return { strippedRawPropertiesXml: raw.replaceAll(/<\w+:dataBinding\b[^>]*\/?>(?:[\s\S]*?<\/\w+:dataBinding>)?/giu, "") };
+}
+function mapBlock(block, match) {
+	if (block.type === "blockSdt") {
+		const replaced = match(block);
+		if (replaced !== void 0) return replaced;
+		const nextContent = transformBlocks(block.content, match);
+		const guarded = nextContent.length === 0 && block.content.length > 0 ? [makeParagraphFromText("")] : nextContent;
+		return {
+			...block,
+			content: guarded
+		};
+	}
+	if (block.type === "table") {
+		const rows = block.rows.map((row) => ({
+			...row,
+			cells: row.cells.map((cell) => {
+				const transformed = transformBlocks(cell.content, match);
+				const cellContent = [];
+				for (const child of transformed) if (child.type === "paragraph" || child.type === "table") cellContent.push(child);
+				return {
+					...cell,
+					content: cellContent
+				};
+			})
+		}));
+		return {
+			...block,
+			rows
+		};
+	}
+	return block;
+}
+function transformBlocks(blocks, match) {
+	const out = [];
+	for (const block of blocks) {
+		const mapped = mapBlock(block, match);
+		if (mapped === null) continue;
+		if (Array.isArray(mapped)) out.push(...mapped);
+		else out.push(mapped);
+	}
+	return out;
+}
+/**
+* Apply the same SDT match callback to every footnote and endnote body
+* and return the updated note arrays. Without this, citation slots and
+* bound metadata inside notes can't be reached through `setContentControl*`
+* by tag / alias / id even though `findContentControls` surfaces them.
+*/
+function applyMatchToNotes(doc, match) {
+	const result = {};
+	if (doc.package.footnotes) result.footnotes = doc.package.footnotes.map((note) => ({
+		...note,
+		content: transformBlocks(note.content, match)
+	}));
+	if (doc.package.endnotes) result.endnotes = doc.package.endnotes.map((note) => ({
+		...note,
+		content: transformBlocks(note.content, match)
+	}));
+	return result;
+}
+function withUpdatedBodyAndNotes(doc, content, notes) {
+	return {
+		...doc,
+		package: {
+			...doc.package,
+			document: {
+				...doc.package.document,
+				content
+			},
+			...notes.footnotes !== void 0 ? { footnotes: notes.footnotes } : {},
+			...notes.endnotes !== void 0 ? { endnotes: notes.endnotes } : {}
+		}
+	};
+}
+function controlMatchesFilter(control, filter) {
+	if (filter.pmPos !== void 0) return false;
+	if (filter.tag !== void 0 && control.properties.tag !== filter.tag) return false;
+	if (filter.alias !== void 0 && control.properties.alias !== filter.alias) return false;
+	if (filter.id !== void 0 && control.properties.id !== filter.id) return false;
+	if (filter.sdtType !== void 0 && control.properties.sdtType !== filter.sdtType) return false;
+	return true;
+}
+function makeParagraphFromText(text) {
+	return {
+		type: "paragraph",
+		content: text.length === 0 ? [] : [{
+			type: "run",
+			content: [{
+				type: "text",
+				text
+			}]
+		}]
+	};
+}
+function cloneBlock(block) {
+	return structuredClone(block);
+}
+/**
+* Replace a control's inner content. Plain text becomes one paragraph; an
+* explicit `BlockContent[]` is deep-cloned to preserve immutability. The
+* `showingPlcHdr` flag is cleared so the new content is not styled as
+* placeholder.
+*
+* Applies to SDTs in the main body AND inside `doc.package.footnotes` /
+* `doc.package.endnotes`. NOTE: save-path propagation for note SDTs is a
+* known follow-up — `repackDocxFromRaw` currently replays
+* `word/footnotes.xml` and `word/endnotes.xml` verbatim from the source
+* zip, so changes to note SDTs land on the in-memory model but the
+* saved DOCX still contains the original note text. Read APIs
+* (`findContentControls`, `getFootnoteText`) reflect the update in the
+* same session; persisting requires extending the selective-save layer
+* to re-serialize note parts.
+*/
+function setContentControlContent(doc, filter, input, options = {}) {
+	const match = (control) => {
+		if (!controlMatchesFilter(control, filter)) return;
+		ensureContentNotLocked(control, options.force);
+		const { strippedRawPropertiesXml } = ensureContentNotBound(control, options.force);
+		const blocks = typeof input === "string" ? [makeParagraphFromText(input)] : input.map(cloneBlock);
+		const properties = { ...control.properties };
+		properties.showingPlaceholder = false;
+		if (strippedRawPropertiesXml !== void 0) properties.rawPropertiesXml = strippedRawPropertiesXml;
+		return {
+			...control,
+			properties,
+			content: blocks
+		};
+	};
+	return withUpdatedBodyAndNotes(doc, transformBlocks(doc.package.document.content, match), applyMatchToNotes(doc, match));
+}
+/**
+* Set a structured value on a typed control. Dropdown / checkbox / date
+* each get their own input shape so the input is type-checked at the
+* call site.
+*/
+function setContentControlValue(doc, filter, input, options = {}) {
+	const match = (control) => {
+		if (!controlMatchesFilter(control, filter)) return;
+		ensureContentNotLocked(control, options.force);
+		const { strippedRawPropertiesXml } = ensureContentNotBound(control, options.force);
+		const sdtType = control.properties.sdtType;
+		if (input.kind === "dropdown") {
+			if (sdtType !== "dropdown" && sdtType !== "comboBox") throw new ContentControlTypeError({
+				message: `Cannot set dropdown value on a ${sdtType} control.`,
+				sdtType,
+				reason: "kind=dropdown requires sdtType=dropdown|comboBox",
+				...control.properties.tag !== void 0 ? { tag: control.properties.tag } : {},
+				...control.properties.alias !== void 0 ? { alias: control.properties.alias } : {}
+			});
+			const item = (control.properties.listItems ?? []).find((i) => i.value === input.value);
+			if (!item && !options.force) throw new ContentControlTypeError({
+				message: `Value "${input.value}" not in the control's list items.`,
+				sdtType,
+				reason: "value not in listItems",
+				...control.properties.tag !== void 0 ? { tag: control.properties.tag } : {},
+				...control.properties.alias !== void 0 ? { alias: control.properties.alias } : {}
+			});
+			const display = item?.displayText ?? input.value;
+			return {
+				...control,
+				properties: {
+					...control.properties,
+					dropdownLastValue: input.value,
+					showingPlaceholder: false,
+					...strippedRawPropertiesXml !== void 0 ? { rawPropertiesXml: strippedRawPropertiesXml } : {}
+				},
+				content: [makeParagraphFromText(display)]
+			};
+		}
+		if (input.kind === "checkbox") {
+			if (sdtType !== "checkbox") throw new ContentControlTypeError({
+				message: `Cannot toggle checkbox on a ${sdtType} control.`,
+				sdtType,
+				reason: "kind=checkbox requires sdtType=checkbox",
+				...control.properties.tag !== void 0 ? { tag: control.properties.tag } : {},
+				...control.properties.alias !== void 0 ? { alias: control.properties.alias } : {}
+			});
+			const glyph = input.checked ? "☒" : "☐";
+			return {
+				...control,
+				properties: {
+					...control.properties,
+					checked: input.checked,
+					showingPlaceholder: false,
+					...strippedRawPropertiesXml !== void 0 ? { rawPropertiesXml: strippedRawPropertiesXml } : {}
+				},
+				content: [makeParagraphFromText(glyph)]
+			};
+		}
+		if (sdtType !== "date") throw new ContentControlTypeError({
+			message: `Cannot set date on a ${sdtType} control.`,
+			sdtType,
+			reason: "kind=date requires sdtType=date",
+			...control.properties.tag !== void 0 ? { tag: control.properties.tag } : {},
+			...control.properties.alias !== void 0 ? { alias: control.properties.alias } : {}
+		});
+		const display = formatDateForSdtBody(input.date, control.properties.dateFormat);
+		return {
+			...control,
+			properties: {
+				...control.properties,
+				dateValueISO: input.date,
+				showingPlaceholder: false,
+				...strippedRawPropertiesXml !== void 0 ? { rawPropertiesXml: strippedRawPropertiesXml } : {}
+			},
+			content: [makeParagraphFromText(display)]
+		};
+	};
+	return withUpdatedBodyAndNotes(doc, transformBlocks(doc.package.document.content, match), applyMatchToNotes(doc, match));
+}
+/**
+* Remove a control. With `{ keepContent: true }` the inner blocks survive
+* in-place; otherwise the control and its children are dropped. Refuses to
+* unwrap a `w15:repeatingSection` (would orphan w15 row items).
+*/
+function removeContentControl(doc, filter, options = {}) {
+	const match = (control) => {
+		if (!controlMatchesFilter(control, filter)) return;
+		ensureSdtNotLocked(control, options.force);
+		if (options.keepContent) {
+			if (isRepeatingSection(control) && !options.force) throw new ContentControlTypeError({
+				message: "Refusing to unwrap a w15:repeatingSection — would orphan its w15 row items.",
+				sdtType: control.properties.sdtType,
+				reason: "repeatingSection unwrap orphans items",
+				...control.properties.tag !== void 0 ? { tag: control.properties.tag } : {},
+				...control.properties.alias !== void 0 ? { alias: control.properties.alias } : {}
+			});
+			return control.content;
+		}
+		return null;
+	};
+	const nextContent = transformBlocks(doc.package.document.content, match);
+	if (nextContent.length === 0) nextContent.push(makeParagraphFromText(""));
+	return withUpdatedBodyAndNotes(doc, nextContent, applyMatchToNotes(doc, match));
+}
+//#endregion
+export { removeContentControl, setContentControlContent, setContentControlValue };

package/dist/controller/folioEditor.d.ts

@@ -0,0 +1,21 @@
+import { Layout } from "../layout-engine/types.js";
+import { FolioEditorEmitter } from "./folioEditorEvents.js";
+import { HiddenEditorApi } from "./hiddenEditorApi.js";
+import { LayoutRunOptions } from "./layoutScheduler.js";
+import { EditorState } from "prosemirror-state";
+
+//#region src/controller/folioEditor.d.ts
+type FolioEditorDeps = {
+  getEditorApi: () => HiddenEditorApi | null;
+  getLayout: () => Layout | null;
+  runLayout: (state: EditorState, options: LayoutRunOptions) => void;
+  emitter: FolioEditorEmitter;
+};
+type FolioEditor = HiddenEditorApi & {
+  getLayout: () => Layout | null; /** Re-run layout for the current editor state (no-op if there is no view). */
+  relayout: () => void;
+  on: FolioEditorEmitter["on"];
+};
+declare const createFolioEditor: (deps: FolioEditorDeps) => FolioEditor;
+//#endregion
+export { FolioEditor, FolioEditorDeps, createFolioEditor };

package/dist/controller/folioEditor.js

@@ -0,0 +1,29 @@
+//#region src/controller/folioEditor.ts
+const createFolioEditor = (deps) => ({
+	ensureView: () => deps.getEditorApi()?.ensureView(),
+	isViewRequested: () => deps.getEditorApi()?.isViewRequested() ?? false,
+	getState: () => deps.getEditorApi()?.getState() ?? null,
+	getView: () => deps.getEditorApi()?.getView() ?? null,
+	getDocument: () => deps.getEditorApi()?.getDocument() ?? null,
+	focus: () => deps.getEditorApi()?.focus(),
+	blur: () => deps.getEditorApi()?.blur(),
+	isFocused: () => deps.getEditorApi()?.isFocused() ?? false,
+	dispatch: (tr) => deps.getEditorApi()?.dispatch(tr),
+	executeCommand: (command) => deps.getEditorApi()?.executeCommand(command) ?? false,
+	undo: () => deps.getEditorApi()?.undo() ?? false,
+	redo: () => deps.getEditorApi()?.redo() ?? false,
+	canUndo: () => deps.getEditorApi()?.canUndo() ?? false,
+	canRedo: () => deps.getEditorApi()?.canRedo() ?? false,
+	setSelection: (anchor, head) => deps.getEditorApi()?.setSelection(anchor, head),
+	setNodeSelection: (pos) => deps.getEditorApi()?.setNodeSelection(pos),
+	setCellSelection: (anchorCellPos, headCellPos) => deps.getEditorApi()?.setCellSelection(anchorCellPos, headCellPos),
+	scrollToSelection: () => deps.getEditorApi()?.scrollToSelection(),
+	getLayout: () => deps.getLayout(),
+	relayout: () => {
+		const state = deps.getEditorApi()?.getState();
+		if (state) deps.runLayout(state, { reason: "manual" });
+	},
+	on: (event, listener) => deps.emitter.on(event, listener)
+});
+//#endregion
+export { createFolioEditor };

package/dist/controller/folioEditorEvents.d.ts

@@ -0,0 +1,23 @@
+import { document_d_exports } from "../types/document.js";
+import { Layout } from "../layout-engine/types.js";
+
+//#region src/controller/folioEditorEvents.d.ts
+type FolioSelectionEvent = {
+  from: number;
+  to: number;
+};
+type FolioEditorEventMap = {
+  selectionChange: FolioSelectionEvent;
+  docChange: document_d_exports.Document;
+  layoutComplete: Layout;
+};
+type FolioEditorEventName = keyof FolioEditorEventMap;
+type FolioEditorEventListener<K extends FolioEditorEventName> = (payload: FolioEditorEventMap[K]) => void;
+type FolioEditorEmitter = {
+  /** Subscribe to an event. Returns an unsubscribe function. */on: <K extends FolioEditorEventName>(event: K, listener: FolioEditorEventListener<K>) => () => void; /** Emit an event to all current listeners. */
+  emit: <K extends FolioEditorEventName>(event: K, payload: FolioEditorEventMap[K]) => void; /** Drop all listeners (call on controller teardown). */
+  clear: () => void;
+};
+declare const createFolioEditorEmitter: () => FolioEditorEmitter;
+//#endregion
+export { FolioEditorEmitter, FolioEditorEventListener, FolioEditorEventMap, FolioEditorEventName, FolioSelectionEvent, createFolioEditorEmitter };

package/dist/controller/folioEditorEvents.js

@@ -0,0 +1,24 @@
+//#region src/controller/folioEditorEvents.ts
+const createFolioEditorEmitter = () => {
+	const channels = {
+		selectionChange: /* @__PURE__ */ new Set(),
+		docChange: /* @__PURE__ */ new Set(),
+		layoutComplete: /* @__PURE__ */ new Set()
+	};
+	return {
+		on: (event, listener) => {
+			channels[event].add(listener);
+			return () => {
+				channels[event].delete(listener);
+			};
+		},
+		emit: (event, payload) => {
+			for (const listener of [...channels[event]]) listener(payload);
+		},
+		clear: () => {
+			for (const channel of Object.values(channels)) channel.clear();
+		}
+	};
+};
+//#endregion
+export { createFolioEditorEmitter };

package/dist/controller/hiddenEditorApi.d.ts

@@ -0,0 +1,35 @@
+import { document_d_exports } from "../types/document.js";
+import { Command, EditorState, Transaction } from "prosemirror-state";
+import { EditorView } from "prosemirror-view";
+
+//#region src/controller/hiddenEditorApi.d.ts
+type HiddenEditorApi = {
+  /** Request the off-screen EditorView (idempotent; creates it when possible). */ensureView: () => void; /** Whether view creation has been requested. */
+  isViewRequested: () => boolean; /** Get the ProseMirror EditorState */
+  getState: () => EditorState | null; /** Get the ProseMirror EditorView */
+  getView: () => EditorView | null; /** Get the current Document from PM state */
+  getDocument: () => document_d_exports.Document | null; /** Focus the hidden editor */
+  focus: () => void; /** Blur the hidden editor */
+  blur: () => void; /** Check if focused */
+  isFocused: () => boolean; /** Dispatch a transaction */
+  dispatch: (tr: Transaction) => void; /** Execute a ProseMirror command */
+  executeCommand: (command: Command) => boolean; /** Undo */
+  undo: () => boolean; /** Redo */
+  redo: () => boolean; /** Check if undo is available */
+  canUndo: () => boolean; /** Check if redo is available */
+  canRedo: () => boolean; /** Set selection by PM position */
+  setSelection: (anchor: number, head?: number) => void; /** Set node selection at a PM position (for images, etc.) */
+  setNodeSelection: (pos: number) => void; /** Set cell selection between two positions inside table cells */
+  setCellSelection: (anchorCellPos: number, headCellPos: number) => void; /** Scroll the PM view to selection (no-op since hidden) */
+  scrollToSelection: () => void;
+};
+type HiddenEditorApiDeps = {
+  getView: () => EditorView | null;
+  getDocumentContext: () => document_d_exports.Document | null;
+  isDestroying: () => boolean;
+  ensureView: () => void;
+  isViewRequested: () => boolean;
+};
+declare const createHiddenEditorApi: (deps: HiddenEditorApiDeps) => HiddenEditorApi;
+//#endregion
+export { HiddenEditorApi, HiddenEditorApiDeps, createHiddenEditorApi };

package/dist/controller/hiddenEditorApi.js

@@ -0,0 +1,112 @@
+import { fromProseDoc } from "../prosemirror/conversion/fromProseDoc.js";
+import { NodeSelection, Selection, TextSelection } from "prosemirror-state";
+import { redo, undo } from "prosemirror-history";
+import { CellSelection } from "prosemirror-tables";
+//#region src/controller/hiddenEditorApi.ts
+/**
+* Hidden-editor imperative API
+*
+* Framework-agnostic method surface for the off-screen ProseMirror editor.
+* Operates on an injected view accessor plus the document context and
+* destruction guard, so the same imperative handle can be driven from the
+* React component or a headless controller without depending on React.
+*/
+/**
+* Convert PM state to Document
+*/
+const stateToDocument = (state, originalDoc) => {
+	if (!originalDoc) return null;
+	return fromProseDoc(state.doc, originalDoc);
+};
+const createHiddenEditorApi = (deps) => {
+	const dispatchTr = (view, tr) => {
+		if (!deps.isDestroying()) view.dispatch(tr);
+	};
+	const setSelection = (anchor, head) => {
+		const view = deps.getView();
+		if (!view) return;
+		const { state } = view;
+		const docEnd = state.doc.content.size;
+		const clampedAnchor = Math.max(0, Math.min(anchor, docEnd));
+		const clampedHead = head === void 0 ? clampedAnchor : Math.max(0, Math.min(head, docEnd));
+		const $anchor = state.doc.resolve(clampedAnchor);
+		const $head = state.doc.resolve(clampedHead);
+		const selection = head === void 0 ? Selection.near($anchor) : TextSelection.between($anchor, $head);
+		dispatchTr(view, state.tr.setSelection(selection));
+	};
+	return {
+		ensureView: deps.ensureView,
+		isViewRequested: deps.isViewRequested,
+		getState: () => deps.getView()?.state ?? null,
+		getView: () => deps.getView() ?? null,
+		getDocument: () => {
+			const view = deps.getView();
+			if (!view) return null;
+			return stateToDocument(view.state, deps.getDocumentContext());
+		},
+		focus: () => {
+			deps.getView()?.focus();
+		},
+		blur: () => {
+			const view = deps.getView();
+			const dom = view?.dom;
+			if (view?.hasFocus() && dom instanceof HTMLElement) dom.blur();
+		},
+		isFocused: () => deps.getView()?.hasFocus() ?? false,
+		dispatch: (tr) => {
+			const view = deps.getView();
+			if (view) dispatchTr(view, tr);
+		},
+		executeCommand: (command) => {
+			const view = deps.getView();
+			if (!view) return false;
+			return command(view.state, (tr) => dispatchTr(view, tr), view);
+		},
+		undo: () => {
+			const view = deps.getView();
+			if (!view) return false;
+			return undo(view.state, (tr) => dispatchTr(view, tr));
+		},
+		redo: () => {
+			const view = deps.getView();
+			if (!view) return false;
+			return redo(view.state, (tr) => dispatchTr(view, tr));
+		},
+		canUndo: () => {
+			const view = deps.getView();
+			if (!view) return false;
+			return undo(view.state);
+		},
+		canRedo: () => {
+			const view = deps.getView();
+			if (!view) return false;
+			return redo(view.state);
+		},
+		setSelection,
+		setNodeSelection: (pos) => {
+			const view = deps.getView();
+			if (!view) return;
+			const { state } = view;
+			try {
+				const selection = NodeSelection.create(state.doc, pos);
+				dispatchTr(view, state.tr.setSelection(selection));
+			} catch {
+				setSelection(pos);
+			}
+		},
+		setCellSelection: (anchorCellPos, headCellPos) => {
+			const view = deps.getView();
+			if (!view) return;
+			const { state } = view;
+			try {
+				const cellSel = CellSelection.create(state.doc, anchorCellPos, headCellPos);
+				dispatchTr(view, state.tr.setSelection(cellSel));
+			} catch {
+				setSelection(anchorCellPos, headCellPos);
+			}
+		},
+		scrollToSelection: () => {}
+	};
+};
+//#endregion
+export { createHiddenEditorApi };