@stll/folio-core 0.59.0 → 0.61.0

package/dist/prosemirror/extensions/features/AutoBidiDetectionExtension.js

@@ -2,11 +2,47 @@ import { setProseParagraphMarkupWithPropertySource } from "../../../docx/paragra
 import { getTransactionDirtyRange } from "../../../paged-layout/transactionDirtyRange.js";
 import { detectBaseDirection } from "../../../utils/baseDirection.js";
 import { directionIsAutoManaged } from "../../paragraphDirection.js";
+import { createPluginKeyOwner } from "../../pluginKeyOwner.js";
 import { createExtension } from "../create.js";
 import { ignoreTrackedChanges } from "./ParagraphChangeTrackerExtension.js";
-import { Plugin, PluginKey } from "prosemirror-state";
+import { Plugin } from "prosemirror-state";
 //#region src/prosemirror/extensions/features/AutoBidiDetectionExtension.ts
-const autoBidiDetectionKey = new PluginKey("autoBidiDetection");
+/**
+* AutoBidiDetection — sets the paragraph `direction` (to `{ source: "auto" }`)
+* on RTL-led paragraphs that arrived without an explicit direction decision.
+*
+* Why: Folio only ever rendered/exported RTL when a paragraph already carried
+* `w:bidi` (from a Word import) or the user toggled it by hand. Content that
+* never had a flag — AI-generated text, Markdown/HTML/plain-text imports, paste,
+* or just typing Arabic without the shortcut — stayed left-to-right both in the
+* editor and in the exported `.docx`. The ProseMirror doc is the single source
+* of truth for both the layout painter (`toFlowBlocks`) and the serializer
+* (`fromProseDoc`), so writing the attribute here fixes the editor and the Word
+* export from one place.
+*
+* Detection uses the first-strong-character rule (`detectBaseDirection`), the
+* same logic the layout painter uses for base direction.
+*
+* Auto vs. explicit: only "auto-managed" paragraphs are (re-)evaluated — those
+* whose `direction` is undecided (absent) or was set by this detector
+* (`source: "auto"`). A manual user toggle or imported `w:bidi`
+* (`source: "manual"`) is authoritative and never touched. Because the detector
+* re-evaluates its own decisions, replacing an auto-RTL paragraph's text with
+* Latin clears it again (no stale "sticky" RTL).
+*
+* The `direction` discriminated union is editor-runtime state. Its `"auto"`
+* source is a *rendering* aid only — `directionToAuthoredBidi` maps it to
+* `undefined`, so an auto-detected paragraph never serializes `w:bidi` on its
+* own; only a manual decision (an explicit user toggle, or `w:bidi` the
+* source document already carried) is authored content. This keeps a no-edit
+* save byte-identical on direction, while the editor and layout painter still
+* treat `"auto"` as RTL (`directionToBidi` / `directionIsRtl`) so detected
+* text displays correctly before the user ever makes it explicit.
+*
+* Mirrors the appendTransaction + ensure-in-state pattern of
+* `ParaIdAllocatorExtension`.
+*/
+const autoBidiDetectionKey = createPluginKeyOwner("autoBidiDetection");
 const paragraphDirectionalText = (node) => {
 	let text = "";
 	node.descendants((child) => {
@@ -95,7 +131,7 @@ const ensureBaseDirectionInState = (state) => {
 	return state.apply(applyBidiUpdates(state, updates));
 };
 const createAutoBidiDetectionPlugin = () => new Plugin({
-	key: autoBidiDetectionKey,
+	key: autoBidiDetectionKey.createKey(),
 	appendTransaction(transactions, _oldState, newState) {
 		if (!transactions.some((t) => t.docChanged)) return null;
 		const [first, ...rest] = transactions;

package/dist/prosemirror/extensions/features/EmptyParagraphFormatExtension.d.ts

@@ -1,7 +1,13 @@
 import { Extension } from "../types.js";
-import { PluginKey } from "prosemirror-state";
+import { Plugin } from "prosemirror-state";
 //#region src/prosemirror/extensions/features/EmptyParagraphFormatExtension.d.ts
-declare const emptyParagraphFormatKey: PluginKey<any>;
+declare const emptyParagraphFormatKey: Readonly<{
+  key: string;
+  createKey: () => import("prosemirror-state").PluginKey<unknown>;
+  owns: (plugin: Plugin<unknown>) => boolean;
+  get: (state: import("prosemirror-state").EditorState) => Plugin<unknown> | undefined;
+  getState: (state: import("prosemirror-state").EditorState) => unknown;
+}>;
 declare const EmptyParagraphFormatExtension: (options?: Partial<Record<string, unknown>> | undefined) => Extension;
 //#endregion
 export { EmptyParagraphFormatExtension, emptyParagraphFormatKey };

package/dist/prosemirror/extensions/features/EmptyParagraphFormatExtension.js

@@ -1,6 +1,7 @@
+import { createPluginKeyOwner } from "../../pluginKeyOwner.js";
 import { createExtension } from "../create.js";
 import { textFormattingToMarks } from "../marks/markUtils.js";
-import { Plugin, PluginKey } from "prosemirror-state";
+import { Plugin } from "prosemirror-state";
 //#region src/prosemirror/extensions/features/EmptyParagraphFormatExtension.ts
 /**
 * EmptyParagraphFormat — re-establishes stored marks for an empty styled
@@ -22,7 +23,7 @@ import { Plugin, PluginKey } from "prosemirror-state";
 * (bold/italic/color/…). Plain body paragraphs (font + size only) are left
 * untouched so ordinary typed text stays mark-free and serializes cleanly.
 */
-const emptyParagraphFormatKey = new PluginKey("emptyParagraphFormat");
+const emptyParagraphFormatKey = createPluginKeyOwner("emptyParagraphFormat");
 /**
 * Run-formatting properties the painter does NOT reproduce from
 * `defaultTextFormatting` on its own (it forwards only font family + size).
@@ -37,7 +38,7 @@ function hasNonFontDefaults(dtf) {
 }
 function createEmptyParagraphFormatPlugin() {
 	return new Plugin({
-		key: emptyParagraphFormatKey,
+		key: emptyParagraphFormatKey.createKey(),
 		appendTransaction(transactions, _oldState, newState) {
 			if (!transactions.some((t) => t.selectionSet || t.docChanged)) return null;
 			const { selection } = newState;

package/dist/prosemirror/extensions/features/ImageDragExtension.js

@@ -1,5 +1,6 @@
+import { createPluginKeyOwner } from "../../pluginKeyOwner.js";
 import { createExtension } from "../create.js";
-import { NodeSelection, Plugin, PluginKey } from "prosemirror-state";
+import { NodeSelection, Plugin } from "prosemirror-state";
 //#region src/prosemirror/extensions/features/ImageDragExtension.ts
 /**
 * Image Drag Extension — handles drag-to-reposition for images
@@ -10,12 +11,12 @@ import { NodeSelection, Plugin, PluginKey } from "prosemirror-state";
 * - Inline images: reorder within text flow via ProseMirror's default drag
 * - Custom drag initiation from mousedown on selected images
 */
-const imageDragKey = new PluginKey("imageDrag");
+const imageDragKey = createPluginKeyOwner("imageDrag");
 const ImageDragExtension = createExtension({
 	name: "imageDrag",
 	onSchemaReady(_ctx) {
 		return { plugins: [new Plugin({
-			key: imageDragKey,
+			key: imageDragKey.createKey(),
 			props: { handleDOMEvents: {
 				dragstart(view, event) {
 					const { selection } = view.state;

package/dist/prosemirror/extensions/features/JoinedRunStyleExtension.js

@@ -1,5 +1,6 @@
+import { createPluginKeyOwner } from "../../pluginKeyOwner.js";
 import { createExtension } from "../create.js";
-import { Plugin, PluginKey } from "prosemirror-state";
+import { Plugin } from "prosemirror-state";
 //#region src/prosemirror/extensions/features/JoinedRunStyleExtension.ts
 /**
 * Runs that a join moves into another paragraph take that paragraph's style.
@@ -16,7 +17,7 @@ import { Plugin, PluginKey } from "prosemirror-state";
 * {@link JOINED_RUNS_RESTYLED_META}, and is left as it is.
 */
 const JOINED_RUNS_RESTYLED_META = "joinedRunsRestyled";
-const pastedTableEndKey = new PluginKey("pastedTableEnd");
+const pastedTableEndKey = createPluginKeyOwner("pastedTableEnd");
 /**
 * A table pasted over a story's last paragraph leaves that paragraph, emptied,
 * after it: a story ends with a paragraph, and the paste replaced the words,
@@ -24,7 +25,7 @@ const pastedTableEndKey = new PluginKey("pastedTableEnd");
 * paragraph, so the empty one is put back.
 */
 const createPastedTableEndPlugin = () => new Plugin({
-	key: pastedTableEndKey,
+	key: pastedTableEndKey.createKey(),
 	appendTransaction(transactions, oldState, newState) {
 		if (!transactions.some((transaction) => transaction.docChanged && transaction.getMeta("uiEvent") === "paste")) return null;
 		if (newState.doc.lastChild?.type.spec["tableRole"] !== "table" || oldState.doc.lastChild?.type.name !== "paragraph") return null;

package/dist/prosemirror/extensions/features/ParaIdAllocatorExtension.d.ts

@@ -1,12 +1,18 @@
 import { Extension } from "../types.js";
 import { Node } from "prosemirror-model";
-import { EditorState, PluginKey, Transaction } from "prosemirror-state";
+import { EditorState, Plugin, Transaction } from "prosemirror-state";
 //#region src/prosemirror/extensions/features/ParaIdAllocatorExtension.d.ts
 type ParagraphPropertySourceSeed = {
   contract: string | null;
   tokens: ReadonlySet<string>;
 };
-declare const paraIdAllocatorKey: PluginKey<ParagraphPropertySourceSeed>;
+declare const paraIdAllocatorKey: Readonly<{
+  key: string;
+  createKey: () => import("prosemirror-state").PluginKey<ParagraphPropertySourceSeed>;
+  owns: (plugin: Plugin<ParagraphPropertySourceSeed>) => boolean;
+  get: (state: EditorState) => Plugin<ParagraphPropertySourceSeed> | undefined;
+  getState: (state: EditorState) => ParagraphPropertySourceSeed | undefined;
+}>;
 /**
  * Transaction meta asking this plugin to derive the ids it mints from a
  * caller-supplied seed instead of `Math.random()`.
@@ -17,7 +23,7 @@ declare const paraIdAllocatorKey: PluginKey<ParagraphPropertySourceSeed>;
  * be deterministic, so it says so on its own transaction rather than leaving
  * the plugin to guess.
  */
-declare const deterministicParaIdSeedKey: PluginKey<string>;
+declare const deterministicParaIdSeedKey = "stll.folio.meta.deterministicParaIdSeed";
 /** Ask the allocator to mint reproducible ids for the paragraphs `tr` creates. */
 declare const requestDeterministicParaIds: (tr: Transaction, seed: string) => Transaction;
 type ParagraphPropertySourceKeeper = {

package/dist/prosemirror/extensions/features/ParaIdAllocatorExtension.js

@@ -1,11 +1,12 @@
 import { PROSE_PARAGRAPH_SOURCE_TOKEN_ATTR, getExplicitParagraphPropertySourceTransfers, getProseDocumentParagraphPropertySourceContract, getProseParagraphPropertySourceToken, paragraphPropertySourceTokenMatchesContract, recreateProseNodeWithParagraphPropertySource, setProseParagraphMarkupWithPropertySource, transferProseParagraphPropertySource } from "../../../docx/paragraphPropertySource.js";
 import { deterministicHexId, generateHexId } from "../../../utils/hexId.js";
+import { createPluginKeyOwner } from "../../pluginKeyOwner.js";
 import { sweepPositions } from "../../positionSweep.js";
 import { createExtension } from "../create.js";
 import { ignoreTrackedChanges } from "./ParagraphChangeTrackerExtension.js";
 import { panic } from "better-result";
 import { Fragment } from "prosemirror-model";
-import { Plugin, PluginKey } from "prosemirror-state";
+import { Plugin } from "prosemirror-state";
 //#region src/prosemirror/extensions/features/ParaIdAllocatorExtension.ts
 /**
 * ParaIdAllocator — assigns a stable `w14:paraId` to every paragraph.
@@ -44,7 +45,7 @@ import { Plugin, PluginKey } from "prosemirror-state";
 *   split therefore restores the same allocated id instead of minting
 *   another one.
 */
-const paraIdAllocatorKey = new PluginKey("paraIdAllocator");
+const paraIdAllocatorKey = createPluginKeyOwner("paraIdAllocator");
 /**
 * Transaction meta asking this plugin to derive the ids it mints from a
 * caller-supplied seed instead of `Math.random()`.
@@ -55,7 +56,7 @@ const paraIdAllocatorKey = new PluginKey("paraIdAllocator");
 * be deterministic, so it says so on its own transaction rather than leaving
 * the plugin to guess.
 */
-const deterministicParaIdSeedKey = new PluginKey("deterministicParaIdSeed");
+const deterministicParaIdSeedKey = "stll.folio.meta.deterministicParaIdSeed";
 /** Ask the allocator to mint reproducible ids for the paragraphs `tr` creates. */
 const requestDeterministicParaIds = (tr, seed) => tr.setMeta(deterministicParaIdSeedKey, seed);
 /**
@@ -297,7 +298,7 @@ const ensureParaIdsInState = (state) => {
 	return state.apply(tr);
 };
 const createParaIdAllocatorPlugin = () => new Plugin({
-	key: paraIdAllocatorKey,
+	key: paraIdAllocatorKey.createKey(),
 	state: {
 		init: (_config, state) => collectParagraphPropertySourceSeed(state.doc),
 		apply: (_transaction, seed) => seed
@@ -307,7 +308,7 @@ const createParaIdAllocatorPlugin = () => new Plugin({
 		const paragraphSourceSeed = paraIdAllocatorKey.getState(oldState);
 		if (!paragraphSourceSeed) panic("ParaId allocator lost its paragraph-property source seed");
 		const keeperPositions = mapParagraphKeepers(oldState.doc, transactions, paragraphSourceSeed);
-		const deterministicSeed = transactions.map((transaction) => transaction.getMeta(deterministicParaIdSeedKey)).find((value) => typeof value === "string") ?? null;
+		const deterministicSeed = transactions.map((transaction) => transaction.getMeta("stll.folio.meta.deterministicParaIdSeed")).find((value) => typeof value === "string") ?? null;
 		const census = collectParagraphCensus(newState.doc, paragraphSourceSeed);
 		const updates = collectParaIdUpdatesFromCensus(census, keeperPositions.paraIds, deterministicSeed);
 		const paragraphSourceUpdates = collectParagraphPropertySourceUpdates(census, keeperPositions.sourceTokens, transactions);

package/dist/prosemirror/extensions/features/ParagraphChangeTrackerExtension.d.ts

@@ -2,9 +2,15 @@ import { document_d_exports } from "../../../types/document.js";
 import { Extension } from "../types.js";
 import { RemovedSectionReference, TrackedSectionEndpointRemoval } from "../../../internal/sectionEndpointResolution.js";
 import { Node } from "prosemirror-model";
-import { EditorState, Plugin, PluginKey, Transaction } from "prosemirror-state";
+import { EditorState, Plugin, Transaction } from "prosemirror-state";
 //#region src/prosemirror/extensions/features/ParagraphChangeTrackerExtension.d.ts
-declare const paragraphChangeTrackerKey: PluginKey<InternalParagraphChangeTrackerState>;
+declare const paragraphChangeTrackerKey: Readonly<{
+  key: string;
+  createKey: () => import("prosemirror-state").PluginKey<InternalParagraphChangeTrackerState>;
+  owns: (plugin: Plugin<InternalParagraphChangeTrackerState>) => boolean;
+  get: (state: EditorState) => Plugin<InternalParagraphChangeTrackerState> | undefined;
+  getState: (state: EditorState) => InternalParagraphChangeTrackerState | undefined;
+}>;
 type ParagraphChangeTrackerState = {
   /** Set of paraIds that were modified since last clear */
   changedParaIds: Set<string>;

package/dist/prosemirror/extensions/features/ParagraphChangeTrackerExtension.js

@@ -1,15 +1,23 @@
 import { withTrackedSectionEndpointRemoval } from "../../../internal/sectionEndpointResolution.js";
 import { canonicalJson } from "../../../utils/canonicalJson.js";
 import { enclosingParagraphIndexed, nodeAtIndexed, nodesBetweenIndexed } from "../../indexedNodeLookup.js";
+import { createPluginKeyOwner } from "../../pluginKeyOwner.js";
 import { sweepPositions } from "../../positionSweep.js";
 import { sectionPropertiesOf } from "../../sectionCarrier.js";
 import { sectionMarkEditsOf } from "../../sectionMarkEdits.js";
 import { createExtension } from "../create.js";
 import { AddMarkStep, AddNodeMarkStep, AttrStep, RemoveMarkStep, RemoveNodeMarkStep } from "prosemirror-transform";
-import { Plugin, PluginKey } from "prosemirror-state";
+import { Plugin } from "prosemirror-state";
 import { isHistoryTransaction } from "prosemirror-history";
 //#region src/prosemirror/extensions/features/ParagraphChangeTrackerExtension.ts
-const paragraphChangeTrackerKey = new PluginKey("paragraphChangeTracker");
+/**
+* Paragraph Change Tracker Extension
+*
+* Watches ProseMirror transactions and records which paragraph IDs (paraId)
+* were modified. Also detects paragraph and block-structure changes.
+* Used by the selective save system to patch only changed paragraphs in document.xml.
+*/
+const paragraphChangeTrackerKey = createPluginKeyOwner("paragraphChangeTracker");
 const CLEAR_META = "clear";
 const IGNORE_META = "ignore";
 const STRUCTURAL_META = "structural";
@@ -196,7 +204,7 @@ const mapStepTouches = (tr, batches) => {
 };
 function createParagraphChangeTrackerPlugin() {
 	return new Plugin({
-		key: paragraphChangeTrackerKey,
+		key: paragraphChangeTrackerKey.createKey(),
 		state: {
 			init(_config, state) {
 				const counts = countDocumentStructure(state.doc);

package/dist/prosemirror/extensions/marks/RunIdentityExtension.js

@@ -1,9 +1,10 @@
 import { expectRunIdentityMarkAttrs } from "../../attrs/index.js";
 import { nodesBetweenIndexed } from "../../indexedNodeLookup.js";
+import { createPluginKeyOwner } from "../../pluginKeyOwner.js";
 import { sweepPositions } from "../../positionSweep.js";
 import { RUN_IDENTITY_ATTRIBUTE, RUN_IDENTITY_MARK_NAME, runIdentityAttrs } from "../../runIdentity.js";
 import { createMarkExtension } from "../create.js";
-import { Plugin, PluginKey } from "prosemirror-state";
+import { Plugin } from "prosemirror-state";
 import { isHistoryTransaction, undoDepth } from "prosemirror-history";
 //#region src/prosemirror/extensions/marks/RunIdentityExtension.ts
 /**
@@ -28,7 +29,7 @@ import { isHistoryTransaction, undoDepth } from "prosemirror-history";
 * supplies the session the format itself says such a run belongs to.
 */
 const CANONICAL_RUN_IDENTITY_ID = /^(?:0|[1-9]\d*)$/u;
-const runIdentityStripKey = new PluginKey("runIdentityStrip");
+const runIdentityStripKey = createPluginKeyOwner("runIdentityStrip");
 /**
 * Every range `transactions` inserted, in the document they produced.
 *
@@ -87,7 +88,7 @@ const insertedRanges = (transactions, skip = () => false) => {
 * collaborative apply all arrive here and nowhere else in common.
 */
 const createRunIdentityStripPlugin = () => new Plugin({
-	key: runIdentityStripKey,
+	key: runIdentityStripKey.createKey(),
 	appendTransaction(transactions, oldState, newState) {
 		if (!transactions.some((transaction) => transaction.docChanged)) return null;
 		const markType = newState.schema.marks[RUN_IDENTITY_MARK_NAME];

package/dist/prosemirror/extensions/marks/markUtils.js

@@ -409,7 +409,7 @@ function isMarkActive(state, type, attrs) {
 	});
 	let hasMark = false;
 	state.doc.nodesBetween(from, to, (node) => {
-		if (node.isText) {
+		if (node.isText && !(RUN_FORMATTING_MARK_NAMES.has(markType.name) && node.marks.some((mark) => mark.type.name === "footnoteRef"))) {
 			const mark = markType.isInSet(node.marks);
 			if (mark) {
 				if (!attrs) {

package/dist/prosemirror/extensions/nodes/CommentReferenceExtension.js

@@ -1,6 +1,7 @@
 import { readCommentReferenceAttrs } from "../../commentReferenceAttrs.js";
 import { planCommentReferenceRepairs } from "../../commentReferenceIntegrity.js";
 import { readRangeAnchorAttrs } from "../../rangeAnchorAttrs.js";
+import { trackedRunInlineAtomDisposition } from "../../trackedRunInlineAtoms.js";
 import { createNodeExtension } from "../create.js";
 import "./RangeAnchorExtension.js";
 import { Plugin } from "prosemirror-state";
@@ -10,7 +11,16 @@ const COMMENT_REFERENCE_NODE_NAME = "commentReference";
 const surveyCommentReferences = (doc) => {
 	const references = [];
 	const markEnds = /* @__PURE__ */ new Map();
+	const unanchoredMarks = [];
 	doc.descendants((node, position) => {
+		const transparent = trackedRunInlineAtomDisposition(node) === "transparent";
+		if (transparent) {
+			for (const mark of node.marks) if (mark.type.name === "comment") unanchoredMarks.push({
+				position,
+				size: node.nodeSize,
+				mark
+			});
+		}
 		if (node.type.name === "commentReference") {
 			const attrs = readCommentReferenceAttrs(node);
 			references.push(attrs.ok ? {
@@ -33,6 +43,7 @@ const surveyCommentReferences = (doc) => {
 			}
 			return false;
 		}
+		if (transparent) return false;
 		if (!node.isInline) return true;
 		for (const mark of node.marks) {
 			if (mark.type.name !== "comment") continue;
@@ -44,6 +55,7 @@ const surveyCommentReferences = (doc) => {
 	});
 	return {
 		references,
+		unanchoredMarks,
 		markExtents: [...markEnds].map(([commentId, end]) => ({
 			commentId,
 			end
@@ -84,9 +96,11 @@ const CommentReferenceExtension = createNodeExtension({
 		if (!transactions.some(({ docChanged }) => docChanged)) return null;
 		const referenceType = newState.schema.nodes[COMMENT_REFERENCE_NODE_NAME];
 		if (!referenceType) return null;
-		const repairs = planCommentReferenceRepairs(surveyCommentReferences(newState.doc));
-		if (repairs.length === 0) return null;
+		const survey = surveyCommentReferences(newState.doc);
+		const repairs = planCommentReferenceRepairs(survey);
+		if (repairs.length === 0 && survey.unanchoredMarks.length === 0) return null;
 		const transaction = newState.tr;
+		for (const { position, size, mark } of survey.unanchoredMarks) transaction.removeMark(position, position + size, mark);
 		for (const repair of repairs) {
 			if (repair.type === "delete") {
 				transaction.delete(repair.position, repair.position + repair.size);

package/dist/prosemirror/findReplaceSelection.d.ts

@@ -1,5 +1,7 @@
+import { DisplayMode } from "../managers/EditorModeManager.js";
 import { FindOptions } from "../utils/findReplace.js";
 import { Node } from "prosemirror-model";
+import { EditorState } from "prosemirror-state";
 //#region src/prosemirror/findReplaceSelection.d.ts
 /**
  * Positional fields of a document search match that the range resolver needs.
@@ -26,5 +28,13 @@ type ProseMirrorFindMatch = FindMatchPosition & FindMatchRange & {
 };
 declare function resolveFindMatchRange(doc: Node, match: FindMatchPosition): FindMatchRange | null;
 declare function findInProseMirrorDocument(doc: Node, searchText: string, options: FindOptions): ProseMirrorFindMatch[];
+type FindInMarkupViewOptions = {
+  state: EditorState;
+  markupView: DisplayMode;
+  searchText: string;
+  options: FindOptions;
+};
+/** Search the displayed story; returned ranges address the authored editor document. */
+declare const findInMarkupView: ({ state, markupView, searchText, options }: FindInMarkupViewOptions) => ProseMirrorFindMatch[];
 //#endregion
-export { FindMatchPosition, FindMatchRange, ProseMirrorFindMatch, findInProseMirrorDocument, resolveFindMatchRange };
+export { FindMatchPosition, FindMatchRange, ProseMirrorFindMatch, findInMarkupView, findInProseMirrorDocument, resolveFindMatchRange };

package/dist/prosemirror/findReplaceSelection.js

@@ -1,6 +1,7 @@
 import { findAllMatches } from "../utils/findReplace.js";
 import { decodeOoxmlSymbolCharacter } from "../utils/ooxmlSymbol.js";
 import { expectSymbolAttrs } from "./attrs/index.js";
+import { projectMarkupView } from "./markupViewProjection.js";
 //#region src/prosemirror/findReplaceSelection.ts
 function resolveFindMatchRange(doc, match) {
 	let resolved = null;
@@ -40,6 +41,19 @@ function findInProseMirrorDocument(doc, searchText, options) {
 	});
 	return matches;
 }
+/** Search the displayed story; returned ranges address the authored editor document. */
+const findInMarkupView = ({ state, markupView, searchText, options }) => {
+	const projection = projectMarkupView(state, markupView);
+	if (projection.type === "authored") return findInProseMirrorDocument(state.doc, searchText, options);
+	return findInProseMirrorDocument(projection.doc, searchText, options).map((match) => ({
+		paragraphIndex: match.paragraphIndex,
+		startOffset: match.startOffset,
+		endOffset: match.endOffset,
+		text: match.text,
+		from: projection.toEditor(match.from, 1),
+		to: projection.toEditor(match.to, -1)
+	}));
+};
 function forEachSearchParagraph(doc, visit) {
 	let paragraphIndex = 0;
 	const walkBlocks = (container, contentStart) => {
@@ -139,4 +153,4 @@ function getSearchableParagraphText(paragraph) {
 	return text;
 }
 //#endregion
-export { findInProseMirrorDocument, resolveFindMatchRange };
+export { findInMarkupView, findInProseMirrorDocument, resolveFindMatchRange };

package/dist/prosemirror/markupViewProjection.d.ts

@@ -1,3 +1,4 @@
+import { document_d_exports } from "../types/document.js";
 import { DisplayMode } from "../managers/EditorModeManager.js";
 import { RemovedSectionReference } from "../internal/sectionEndpointResolution.js";
 import { indexedPositionMap } from "../internal/indexedPositionMap.js";
@@ -93,5 +94,13 @@ declare const projectMarkupView: (state: EditorState, view: DisplayMode) => Mark
  * of text it cannot enter.
  */
 declare const visibleCaretPosition: (projection: MarkupViewProjection, position: number) => number;
+type ProjectStoryMarkupViewOptions = {
+  doc: Node;
+  markupView: DisplayMode;
+  styles?: document_d_exports.StyleDefinitions | null | undefined;
+  numbering?: document_d_exports.NumberingDefinitions | undefined;
+};
+/** Detached stories use the same state-aware projection owner as the body. */
+declare const projectStoryMarkupView: ({ doc, markupView, styles, numbering }: ProjectStoryMarkupViewOptions) => MarkupViewProjection;
 //#endregion
-export { MarkupViewProjection, markupViewResolutionMode, projectMarkupView, resolveStateStory, visibleCaretPosition };
+export { MarkupViewProjection, markupViewResolutionMode, projectMarkupView, projectStoryMarkupView, resolveStateStory, visibleCaretPosition };

package/dist/prosemirror/markupViewProjection.js

@@ -1,9 +1,10 @@
 import { indexedPositionMap } from "../internal/indexedPositionMap.js";
 import { finalRevisionParagraphRanges } from "../internal/revisionResolutionTracking.js";
 import { resolveWholeStory } from "../internal/wholeStoryRevisionResolution.js";
-import { getDocumentNumbering } from "./plugins/documentNumbering.js";
+import { createDocumentNumberingPlugin, getDocumentNumbering } from "./plugins/documentNumbering.js";
 import { getDocumentStyleResolver } from "./plugins/documentStyleState.js";
-import { Selection } from "prosemirror-state";
+import { createDocumentStyleContextPlugin } from "./plugins/documentStyles.js";
+import { EditorState, Selection } from "prosemirror-state";
 //#region src/prosemirror/markupViewProjection.ts
 /** Resolve every revision in the state's story with the state's own styles and numbering. */
 const resolveStateStory = (state, mode) => resolveWholeStory({
@@ -84,5 +85,22 @@ const visibleCaretPosition = (projection, position) => {
 	const near = Selection.near(projection.doc.resolve(bounded), -1);
 	return projection.toEditor(near.head, -1);
 };
+const storyProjectionStates = /* @__PURE__ */ new WeakMap();
+/** Detached stories use the same state-aware projection owner as the body. */
+const projectStoryMarkupView = ({ doc, markupView, styles, numbering }) => {
+	if (markupView === "all-markup") return AUTHORED;
+	const cached = storyProjectionStates.get(doc);
+	if (cached && cached.styles === styles && cached.numbering === numbering) return projectMarkupView(cached.state, markupView);
+	const state = EditorState.create({
+		doc,
+		plugins: [createDocumentStyleContextPlugin(styles), createDocumentNumberingPlugin(numbering)]
+	});
+	storyProjectionStates.set(doc, {
+		styles,
+		numbering,
+		state
+	});
+	return projectMarkupView(state, markupView);
+};
 //#endregion
-export { markupViewResolutionMode, projectMarkupView, resolveStateStory, visibleCaretPosition };
+export { markupViewResolutionMode, projectMarkupView, projectStoryMarkupView, resolveStateStory, visibleCaretPosition };

package/dist/prosemirror/pluginKeyOwner.d.ts

@@ -0,0 +1,13 @@
+import { EditorState, Plugin, PluginKey } from "prosemirror-state";
+//#region src/prosemirror/pluginKeyOwner.d.ts
+type PluginKeyOwner<State> = Readonly<{
+  key: string;
+  createKey: () => PluginKey<State>;
+  owns: (plugin: Plugin<State>) => boolean;
+  get: (state: EditorState) => Plugin<State> | undefined;
+  getState: (state: EditorState) => State | undefined;
+}>;
+/** An immutable plugin family descriptor; each plugin owns its actual key. */
+declare const createPluginKeyOwner: <State = unknown>(name: string) => PluginKeyOwner<State>;
+//#endregion
+export { PluginKeyOwner, createPluginKeyOwner };

package/dist/prosemirror/pluginKeyOwner.js

@@ -0,0 +1,35 @@
+import { panic } from "better-result";
+import { PluginKey } from "prosemirror-state";
+//#region src/prosemirror/pluginKeyOwner.ts
+const PLUGIN_KEY_PREFIX = "stll.folio.plugin.";
+const METADATA_KEY_PREFIX = "stll.folio.meta.";
+const PLUGIN_OWNER_BRAND = Symbol.for("stll.folio.plugin.owner");
+/** An immutable plugin family descriptor; each plugin owns its actual key. */
+const createPluginKeyOwner = (name) => {
+	const pluginsByState = /* @__PURE__ */ new WeakMap();
+	const owns = (plugin) => plugin.spec.key !== void 0 && PLUGIN_OWNER_BRAND in plugin.spec.key && plugin.spec.key[PLUGIN_OWNER_BRAND] === name;
+	const get = (state) => {
+		if (pluginsByState.has(state)) return pluginsByState.get(state);
+		let found;
+		for (const plugin of state.plugins) {
+			if (!owns(plugin)) continue;
+			if (found) panic(`Multiple plugins belong to ${name} in one editor state`);
+			found = plugin;
+		}
+		pluginsByState.set(state, found);
+		return found;
+	};
+	return Object.freeze({
+		key: `${METADATA_KEY_PREFIX}${name}`,
+		createKey: () => {
+			const key = new PluginKey(`${PLUGIN_KEY_PREFIX}${name}`);
+			Object.defineProperty(key, PLUGIN_OWNER_BRAND, { value: name });
+			return key;
+		},
+		owns,
+		get,
+		getState: (state) => get(state)?.getState(state)
+	});
+};
+//#endregion
+export { createPluginKeyOwner };

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

@@ -1,7 +1,14 @@
-import { Plugin, PluginKey } from "prosemirror-state";
+import { PluginKeyOwner } from "../pluginKeyOwner.js";
+import { Plugin } from "prosemirror-state";
 import { DecorationSet } from "prosemirror-view";
 //#region src/prosemirror/plugins/aiCitationDecorations.d.ts
-declare const aiCitationDecorationsKey: PluginKey<AICitationDecorationState>;
+declare const aiCitationDecorationsKey: Readonly<{
+  key: string;
+  createKey: () => import("prosemirror-state").PluginKey<AICitationDecorationState>;
+  owns: (plugin: Plugin<AICitationDecorationState>) => boolean;
+  get: (state: import("prosemirror-state").EditorState) => Plugin<AICitationDecorationState> | undefined;
+  getState: (state: import("prosemirror-state").EditorState) => AICitationDecorationState | undefined;
+}>;
 declare const SET_META = "set";
 declare const ACTIVE_META = "active";
 type AICitationRange = {
@@ -23,14 +30,14 @@ type AICitationDecorationState = {
  */
 declare function createAICitationDecorationsPlugin(): Plugin<AICitationDecorationState>;
 declare function setAICitationsMeta(citations: AICitationRange[]): {
-  key: PluginKey<AICitationDecorationState>;
+  key: PluginKeyOwner<AICitationDecorationState>;
   payload: {
     type: typeof SET_META;
     citations: AICitationRange[];
   };
 };
 declare function setActiveCitationMeta(activeId: string | null): {
-  key: PluginKey<AICitationDecorationState>;
+  key: PluginKeyOwner<AICitationDecorationState>;
   payload: {
     type: typeof ACTIVE_META;
     activeId: string | null;

package/dist/prosemirror/plugins/aiCitationDecorations.js

@@ -1,7 +1,20 @@
-import { Plugin, PluginKey } from "prosemirror-state";
+import { createPluginKeyOwner } from "../pluginKeyOwner.js";
+import { Plugin } from "prosemirror-state";
 import { Decoration, DecorationSet } from "prosemirror-view";
 //#region src/prosemirror/plugins/aiCitationDecorations.ts
-const aiCitationDecorationsKey = new PluginKey("aiCitationDecorations");
+/**
+* AI Citation Decorations Plugin
+*
+* Renders pointer-back-to-source highlights on Folio (DOCX) ranges
+* cited by an AI answer. Distinct from the suggestion-decoration
+* plugin: citations are read-only pointers (no edit semantics) and
+* usually appear briefly when the user clicks a citation chip in the
+* thread.
+*
+* The host pushes updates via the `setAICitationsMeta` /
+* `setActiveCitationMeta` helpers below.
+*/
+const aiCitationDecorationsKey = createPluginKeyOwner("aiCitationDecorations");
 const SET_META = "set";
 const ACTIVE_META = "active";
 function buildDecorationSet(doc, citations, activeId) {
@@ -31,7 +44,7 @@ function buildDecorationSet(doc, citations, activeId) {
 */
 function createAICitationDecorationsPlugin() {
 	return new Plugin({
-		key: aiCitationDecorationsKey,
+		key: aiCitationDecorationsKey.createKey(),
 		state: {
 			init(_, state) {
 				return {