@stll/folio-core 0.45.0 → 0.46.0

package/dist/prosemirror/replacedAnnotations.d.ts

@@ -0,0 +1,59 @@
+import { Fragment, Mark, Node, Schema } from "prosemirror-model";
+//#region src/prosemirror/replacedAnnotations.d.ts
+/**
+ * What a replacement does with each mark the schema declares
+ * `inclusive: false`. Boundary inheritance already handles every other mark,
+ * so this table is exactly the set that needs a decision; a new
+ * non-inclusive mark that is missing from it fails
+ * `replacedAnnotations.test.ts` rather than silently following the text.
+ */
+declare const NON_INCLUSIVE_MARK_DISPOSITION: {
+  readonly comment: "carry";
+  readonly hyperlink: "carry";
+  readonly footnoteRef: "followsTheText";
+  readonly pageBreakRunOwner: "followsTheText";
+  readonly insertion: "followsTheText";
+  readonly deletion: "followsTheText";
+  readonly runPropertyChange: "followsTheText";
+  readonly inlineWrapper: "followsTheText";
+};
+/** The mark names in the schema that a replacement must not silently drop. */
+declare const nonInclusiveMarkNames: (schema: Schema) => string[];
+type ReplacedAnnotations = {
+  /** Marks the replacement must carry, in document order. */
+  carried: readonly Mark[];
+  /** Anchors restored before the replacement, in their original order. */
+  leading: readonly Node[];
+  /** Anchors restored after the replacement, in their original order. */
+  trailing: readonly Node[];
+};
+declare const hasReplacedAnnotations: ({ carried, leading, trailing }: ReplacedAnnotations) => boolean;
+/**
+ * The annotations carried by `[from, to)`. An anchor counts only when the
+ * range covers it whole: a partially covered atom is not deleted by the
+ * replacement either.
+ */
+declare const surveyReplacedAnnotations: (doc: Node, from: number, to: number) => ReplacedAnnotations;
+type AnnotatedReplacementOptions = {
+  annotations: ReplacedAnnotations;
+  /** The replacement's own inline content, already carrying its formatting. */
+  content: Fragment;
+};
+type AnnotatedReplacement = {
+  fragment: Fragment;
+  /** Size of the anchors restored before the replacement's own content. */
+  leadingSize: number;
+  /** Size of the replacement's own content, once the marks are on it. */
+  contentSize: number;
+};
+/** `marks` with the carried marks added, each type's exclusions respected. */
+declare const addCarriedMarks: (marks: readonly Mark[], carried: readonly Mark[]) => readonly Mark[];
+/** `content` with the surveyed marks on it and the surveyed anchors around it. */
+declare const annotatedReplacement: ({ annotations: { carried, leading, trailing }, content }: AnnotatedReplacementOptions) => AnnotatedReplacement;
+/**
+ * The marks a replacement inherits at `[from, to)`, exactly as
+ * `Transaction.insertText` would compute them.
+ */
+declare const inheritedReplacementMarks: (doc: Node, from: number, to: number) => readonly Mark[];
+//#endregion
+export { NON_INCLUSIVE_MARK_DISPOSITION, ReplacedAnnotations, addCarriedMarks, annotatedReplacement, hasReplacedAnnotations, inheritedReplacementMarks, nonInclusiveMarkNames, surveyReplacedAnnotations };

package/dist/prosemirror/replacedAnnotations.js

@@ -0,0 +1,165 @@
+import { BOOKMARK_BOUNDARY_NODE_NAME } from "./extensions/nodes/BookmarkBoundaryExtension.js";
+import { COMMENT_REFERENCE_NODE_NAME } from "./extensions/nodes/CommentReferenceExtension.js";
+import { TEXT_BOX_ANCHOR_NODE_NAME } from "./extensions/nodes/TextBoxAnchorExtension.js";
+import { Fragment, Mark } from "prosemirror-model";
+//#region src/prosemirror/replacedAnnotations.ts
+/**
+* What survives when an edit replaces a span of inline content.
+*
+* ProseMirror gives a replacement the marks it inherits at the boundary, and
+* drops any mark declared `inclusive: false` once the span reaches the end of
+* what that mark covers. For formatting that is right. For a mark that names
+* something outside itself — the comment this text is commented by, the
+* address this text links to — it is not: the target survives the edit, and
+* only the mark saying so is lost. A comment loses the range start that lived
+* on the replaced text, so the save emits a `commentRangeEnd` with no
+* `commentRangeStart`, invalid OOXML and a comment anchored to nothing; a
+* hyperlink simply stops being a link. Zero-width anchors fare worse still: a
+* plain replace deletes them outright.
+*
+* Word moves a range start that sits inside a replaced span to the beginning
+* of the replacement and lets the range keep covering the new text; it keeps
+* a link across a replacement of its display text. A range wholly inside the
+* span collapses onto the replacement, and disappears only when every
+* character it covered is gone. One rule per marker kind, and that is the
+* whole contract:
+*
+* - `comment` mark: the replacement carries every comment the span covered, so
+*   a range that started inside it starts at the replacement instead.
+* - `hyperlink` mark: the replacement carries the first link the span held, so
+*   replacing a link's display text leaves the link on the new text. A span
+*   crossing two links keeps the one it opens in, because the mark excludes
+*   itself and a replacement is one run of text with one address.
+* - `footnoteRef` mark (footnotes and endnotes alike): not carried. It marks
+*   the reference's own number, not prose around it, and it serializes as a
+*   bare `w:footnoteReference` run, so carrying it onto a replacement would
+*   discard the new text. Replacing a reference's text deletes the reference,
+*   as deleting that text does.
+* - `pageBreakRunOwner` mark: not carried. It is editor-only identity for one
+*   authored run, not a target, and carrying it would fuse the replacement
+*   into a run it was never part of.
+* - tracked-change marks (`insertion`, `deletion`, `runPropertyChange`): not
+*   carried. The applier decides them per edit mode and writes them itself.
+* - `inlineWrapper` mark: not carried. Every wrapper kind states something
+*   about the text under it and names nothing outside itself, so boundary
+*   inheritance is the right rule: a replacement inside a bidirectional
+*   override is still inside it, and one that replaces the whole of it is not.
+* - `commentReference` node: kept after the replacement, where the comment's
+*   last covered position now is.
+* - `bookmarkBoundary` node: a start kept before the replacement, an end after
+*   it, so the bookmark still covers the new text.
+* - `textBoxAnchor` node: kept after the replacement; the shape it anchors
+*   outlives the sentence it was typed into.
+* - `renderedPageBreak` node: dropped with the text. It is Word's cached
+*   pagination, re-derived on layout, and nothing else names it.
+* - every other mark: formatting, and left to boundary inheritance, which
+*   already gives the replacement the formatting of the text it replaces.
+*
+* Deleting the whole of a comment's span leaves it no mark anywhere, so
+* `CommentReferenceExtension` drops the orphan reference and the save drops
+* the comment: the one case where a range is meant to disappear.
+*/
+/**
+* What a replacement does with each mark the schema declares
+* `inclusive: false`. Boundary inheritance already handles every other mark,
+* so this table is exactly the set that needs a decision; a new
+* non-inclusive mark that is missing from it fails
+* `replacedAnnotations.test.ts` rather than silently following the text.
+*/
+const NON_INCLUSIVE_MARK_DISPOSITION = {
+	comment: "carry",
+	hyperlink: "carry",
+	footnoteRef: "followsTheText",
+	pageBreakRunOwner: "followsTheText",
+	insertion: "followsTheText",
+	deletion: "followsTheText",
+	runPropertyChange: "followsTheText",
+	inlineWrapper: "followsTheText"
+};
+/** The mark names in the schema that a replacement must not silently drop. */
+const nonInclusiveMarkNames = (schema) => Object.entries(schema.marks).filter(([, type]) => type.spec.inclusive === false).map(([name]) => name);
+const isCarried = (mark) => NON_INCLUSIVE_MARK_DISPOSITION[mark.type.name] === "carry";
+/** Anchors an edit must put back, and where relative to the replacement. */
+const ANCHOR_PLACEMENT = {
+	[COMMENT_REFERENCE_NODE_NAME]: "after",
+	[TEXT_BOX_ANCHOR_NODE_NAME]: "after",
+	[BOOKMARK_BOUNDARY_NODE_NAME]: "byBoundaryType"
+};
+const anchorPlacement = (node) => ANCHOR_PLACEMENT[node.type.name];
+const NOTHING_REPLACED = {
+	carried: [],
+	leading: [],
+	trailing: []
+};
+const hasReplacedAnnotations = ({ carried, leading, trailing }) => carried.length > 0 || leading.length > 0 || trailing.length > 0;
+/**
+* The annotations carried by `[from, to)`. An anchor counts only when the
+* range covers it whole: a partially covered atom is not deleted by the
+* replacement either.
+*/
+const surveyReplacedAnnotations = (doc, from, to) => {
+	if (to <= from) return NOTHING_REPLACED;
+	const carried = [];
+	const leading = [];
+	const trailing = [];
+	doc.nodesBetween(from, to, (node, position) => {
+		if (!node.isInline) return true;
+		for (const mark of node.marks) if (isCarried(mark) && !alreadyCarried(mark, carried)) carried.push(mark);
+		const placement = anchorPlacement(node);
+		if (placement === void 0 || position < from || position + node.nodeSize > to) return false;
+		(placement === "byBoundaryType" && node.attrs["type"] === "start" ? leading : trailing).push(node);
+		return false;
+	});
+	return {
+		carried,
+		leading,
+		trailing
+	};
+};
+/**
+* Whether the span already contributed this mark, or one the mark would evict.
+* Comments do not exclude each other, so every comment is collected; a
+* hyperlink excludes its own type, so the first address in the span wins
+* rather than the last silently overwriting it.
+*/
+const alreadyCarried = (mark, carried) => carried.some((other) => other.eq(mark) || mark.type.excludes(other.type));
+const anchorsSize = (anchors) => {
+	let size = 0;
+	for (const node of anchors) size += node.nodeSize;
+	return size;
+};
+/** `marks` with the carried marks added, each type's exclusions respected. */
+const addCarriedMarks = (marks, carried) => {
+	let next = marks;
+	for (const mark of carried) next = mark.addToSet(next);
+	return next;
+};
+const withCarriedMarks = (node, carried) => node.mark(addCarriedMarks(node.marks, carried));
+/** `content` with the surveyed marks on it and the surveyed anchors around it. */
+const annotatedReplacement = ({ annotations: { carried, leading, trailing }, content }) => {
+	const inline = [];
+	content.forEach((child) => {
+		inline.push(carried.length === 0 ? child : withCarriedMarks(child, carried));
+	});
+	const fragment = Fragment.fromArray([
+		...leading,
+		...inline,
+		...trailing
+	]);
+	const leadingSize = anchorsSize(leading);
+	return {
+		fragment,
+		leadingSize,
+		contentSize: fragment.size - leadingSize - anchorsSize(trailing)
+	};
+};
+/**
+* The marks a replacement inherits at `[from, to)`, exactly as
+* `Transaction.insertText` would compute them.
+*/
+const inheritedReplacementMarks = (doc, from, to) => {
+	const $from = doc.resolve(from);
+	return (to === from ? $from.marks() : $from.marksAcross(doc.resolve(to))) ?? Mark.none;
+};
+//#endregion
+export { NON_INCLUSIVE_MARK_DISPOSITION, addCarriedMarks, annotatedReplacement, hasReplacedAnnotations, inheritedReplacementMarks, nonInclusiveMarkNames, surveyReplacedAnnotations };

package/dist/prosemirror/runFormattingInlineCarriers.d.ts

@@ -1,7 +1,7 @@
 import { Transaction } from "prosemirror-state";
 import { Mark, Node } from "prosemirror-model";
 //#region src/prosemirror/runFormattingInlineCarriers.d.ts
-type RunFormattingInlineAtomDisposition = "break-run" | "field-run" | "not-a-run" | "page-break-carrier" | "structured-field" | "symbol-run" | "tab-run" | "text-run";
+type RunFormattingInlineAtomDisposition = "break-run" | "field-run" | "not-a-run" | "page-break-carrier" | "preserved-xml-run" | "structured-field" | "symbol-run" | "tab-run" | "text-run";
 /**
  * How every inline atom maps to a serialized run-formatting carrier.
  *
@@ -12,11 +12,13 @@ type RunFormattingInlineAtomDisposition = "break-run" | "field-run" | "not-a-run
  */
 declare const RUN_FORMATTING_INLINE_ATOM_DISPOSITIONS: Readonly<{
   readonly bookmarkBoundary: "not-a-run";
+  readonly commentReference: "not-a-run";
   readonly field: "field-run";
   readonly hardBreak: "break-run";
   readonly image: "not-a-run";
   readonly math: "not-a-run";
   readonly pageBreakRun: "page-break-carrier";
+  readonly preservedXml: "preserved-xml-run";
   readonly renderedPageBreak: "not-a-run";
   readonly shape: "not-a-run";
   readonly structuredField: "structured-field";

package/dist/prosemirror/runFormattingInlineCarriers.js

@@ -1,5 +1,5 @@
 import { decodeOoxmlSymbolCharacter } from "../utils/ooxmlSymbol.js";
-import { expectFieldAttrs, expectSymbolAttrs } from "./attrs/index.js";
+import { expectFieldAttrs, expectPreservedXmlAttrs, expectSymbolAttrs } from "./attrs/index.js";
 import { panic } from "better-result";
 import { Mark } from "prosemirror-model";
 //#region src/prosemirror/runFormattingInlineCarriers.ts
@@ -13,11 +13,13 @@ import { Mark } from "prosemirror-model";
 */
 const RUN_FORMATTING_INLINE_ATOM_DISPOSITIONS = Object.freeze({
 	bookmarkBoundary: "not-a-run",
+	commentReference: "not-a-run",
 	field: "field-run",
 	hardBreak: "break-run",
 	image: "not-a-run",
 	math: "not-a-run",
 	pageBreakRun: "page-break-carrier",
+	preservedXml: "preserved-xml-run",
 	renderedPageBreak: "not-a-run",
 	shape: "not-a-run",
 	structuredField: "structured-field",
@@ -32,6 +34,7 @@ const CONTROL_CHARACTER_BY_DISPOSITION = Object.freeze({
 	"field-run": null,
 	"not-a-run": null,
 	"page-break-carrier": null,
+	"preserved-xml-run": null,
 	"structured-field": null,
 	"symbol-run": null,
 	"tab-run": "	",
@@ -162,6 +165,7 @@ const runFormattingCarrierReviewText = (carrier) => {
 			const { char } = expectSymbolAttrs(carrier.node);
 			return decodeOoxmlSymbolCharacter(char) ?? "�";
 		}
+		case "preserved-xml-run": return expectPreservedXmlAttrs(carrier.node).text;
 		case "field-run":
 		case "structured-field": return expectFieldAttrs(carrier.node).displayText ?? carrier.node.textContent;
 	}

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

@@ -1,5 +1,5 @@
-import { CharacterSpacingAttrs, CharacterStyleAttrs, CommentAttrs, EmphasisMarkAttrs, FontFamilyAttrs, FontSizeAttrs, FootnoteRefAttrs, HighlightAttrs, HyperlinkAttrs, LanguageAttrs, PageBreakRunOwnerMarkAttrs, RunFormattingOverrideAttrs, RunPropertyChangeMarkAttrs, RunShadingAttrs, StrikeAttrs, TextColorAttrs, TextEffectAttrs, TrackedChangeMarkAttrs, UnderlineAttrs } from "./marks.js";
-import { BlockSdtAttrs, BookmarkBoundaryAttrs, FieldAttrs, HardBreakAttrs, ImageAttrs, ImagePositionAttrs, MathAttrs, PageBreakRunAttrs, ParagraphAttrs, ParagraphPropertyChangeAttrs, SdtAttrs, ShapeAttrs, SymbolAttrs, TabAttrs, TableAttrs, TableCellAttrs, TableRowAttrs, TextBoxAttrs } from "./nodes.js";
+import { CharacterSpacingAttrs, CharacterStyleAttrs, CommentAttrs, EmphasisMarkAttrs, FontFamilyAttrs, FontSizeAttrs, FootnoteRefAttrs, HighlightAttrs, HyperlinkAttrs, InlineWrapperAttrs, InlineWrapperKind, InlineWrapperLayer, LanguageAttrs, PageBreakRunOwnerMarkAttrs, RunFormattingOverrideAttrs, RunPropertyChangeMarkAttrs, RunShadingAttrs, StrikeAttrs, TextColorAttrs, TextEffectAttrs, TrackedChangeMarkAttrs, UnderlineAttrs } from "./marks.js";
+import { BlockSdtAttrs, BookmarkBoundaryAttrs, FieldAttrs, HardBreakAttrs, ImageAttrs, ImagePositionAttrs, MathAttrs, PageBreakRunAttrs, ParagraphAttrs, ParagraphPropertyChangeAttrs, PreservedBlockAttrs, PreservedXmlAttrs, PreservedXmlLevel, SdtAttrs, ShapeAttrs, SymbolAttrs, TabAttrs, TableAttrs, TableCellAttrs, TableRowAttrs, TextBoxAttrs } from "./nodes.js";
 import { ExtensionManager } from "../extensions/ExtensionManager.js";
 //#region src/prosemirror/schema/index.d.ts
 declare const singletonManager: ExtensionManager;
@@ -11,4 +11,4 @@ type DocxSchema = typeof schema;
 type DocxNode = ReturnType<typeof schema.node>;
 type DocxMark = ReturnType<typeof schema.mark>;
 //#endregion
-export { type BlockSdtAttrs, type BookmarkBoundaryAttrs, type CharacterSpacingAttrs, type CharacterStyleAttrs, type CommentAttrs, DocxMark, DocxNode, DocxSchema, type EmphasisMarkAttrs, type FieldAttrs, type FontFamilyAttrs, type FontSizeAttrs, type FootnoteRefAttrs, type HardBreakAttrs, type HighlightAttrs, type HyperlinkAttrs, type ImageAttrs, type ImagePositionAttrs, type LanguageAttrs, type MathAttrs, type PageBreakRunAttrs, type PageBreakRunOwnerMarkAttrs, type ParagraphAttrs, type ParagraphPropertyChangeAttrs, type RunFormattingOverrideAttrs, type RunPropertyChangeMarkAttrs, type RunShadingAttrs, type SdtAttrs, type ShapeAttrs, type StrikeAttrs, type SymbolAttrs, type TabAttrs, type TableAttrs, type TableCellAttrs, type TableRowAttrs, type TextBoxAttrs, type TextColorAttrs, type TextEffectAttrs, type TrackedChangeMarkAttrs, type UnderlineAttrs, schema, singletonManager };
+export { type BlockSdtAttrs, type BookmarkBoundaryAttrs, type CharacterSpacingAttrs, type CharacterStyleAttrs, type CommentAttrs, DocxMark, DocxNode, DocxSchema, type EmphasisMarkAttrs, type FieldAttrs, type FontFamilyAttrs, type FontSizeAttrs, type FootnoteRefAttrs, type HardBreakAttrs, type HighlightAttrs, type HyperlinkAttrs, type ImageAttrs, type ImagePositionAttrs, type InlineWrapperAttrs, type InlineWrapperKind, type InlineWrapperLayer, type LanguageAttrs, type MathAttrs, type PageBreakRunAttrs, type PageBreakRunOwnerMarkAttrs, type ParagraphAttrs, type ParagraphPropertyChangeAttrs, type PreservedBlockAttrs, type PreservedXmlAttrs, type PreservedXmlLevel, type RunFormattingOverrideAttrs, type RunPropertyChangeMarkAttrs, type RunShadingAttrs, type SdtAttrs, type ShapeAttrs, type StrikeAttrs, type SymbolAttrs, type TabAttrs, type TableAttrs, type TableCellAttrs, type TableRowAttrs, type TextBoxAttrs, type TextColorAttrs, type TextEffectAttrs, type TrackedChangeMarkAttrs, type UnderlineAttrs, schema, singletonManager };

package/dist/prosemirror/schema/marks.d.ts

@@ -127,6 +127,30 @@ type RunPropertyChangeMarkAttrs = {
 type PageBreakRunOwnerMarkAttrs = {
   id: number;
 };
+/**
+ * One transparent wrapper a leaf sits inside, minus the content ProseMirror
+ * now holds instead.
+ *
+ * Distributed over the model's union rather than written out beside it: a
+ * wrapper kind exists in both places or in neither, and the fields a kind
+ * carries are stated once. A smart tag cannot gain a `control` this way, and
+ * a kind added to the model reaches the editor as a compile error at every
+ * site that decides per kind.
+ */
+type WrapperLayer<Wrapper> = Wrapper extends unknown ? Omit<Wrapper, "type" | "content"> : never;
+type InlineWrapperLayer = WrapperLayer<document_d_exports.InlineWrapper>;
+type InlineWrapperKind = InlineWrapperLayer["kind"];
+/**
+ * The wrappers a leaf sits inside, outermost first.
+ *
+ * Multiplicity lives here rather than in the mark set: ProseMirror marks are
+ * unordered across types and a mark excludes its own type, so nesting a
+ * wrapper inside another cannot be spelled as two marks. `null` is no
+ * wrapper; an empty stack is never stored.
+ */
+type InlineWrapperAttrs = {
+  stack: readonly InlineWrapperLayer[];
+};
 declare const COMPLEX_SCRIPT_RUN_PROPERTY_KEYS: readonly ["boldCs", "italicCs", "fontSizeCs"];
 type ComplexScriptRunPropertyKey = (typeof COMPLEX_SCRIPT_RUN_PROPERTY_KEYS)[number];
 declare const RUN_FORMATTING_BOOLEAN_PROPERTIES: readonly ["bold", "boldCs", "italic", "italicCs", "strike", "doubleStrike", "smallCaps", "allCaps", "hidden", "noProof", "emboss", "imprint", "outline", "shadow", "rtl", "cs"];
@@ -231,4 +255,4 @@ type HyperlinkAttrs = {
   _docxHyperlinkIndex?: number;
 };
 //#endregion
-export { AuthoredRunFormattingValues, COMPLEX_SCRIPT_RUN_PROPERTY_KEYS, CharacterSpacingAttrs, CharacterStyleAttrs, CommentAttrs, ComplexScriptRunPropertyKey, EmphasisMarkAttrs, FontFamilyAttrs, FontSizeAttrs, FootnoteRefAttrs, HighlightAttrs, HyperlinkAttrs, LanguageAttrs, PageBreakRunOwnerMarkAttrs, RUN_FORMATTING_BOOLEAN_PROPERTIES, RUN_FORMATTING_PROPERTY_SPECS, RUN_FORMATTING_VALUE_PROPERTIES, RunFormattingBooleanProperty, RunFormattingOverrideAttrs, RunFormattingValueProperty, RunPropertyChangeMarkAttrs, RunShadingAttrs, StrikeAttrs, TRACKED_CHANGE_PROVENANCE_VALUES, TextColorAttrs, TextEffectAttrs, TrackedChangeMarkAttrs, TrackedChangeProvenance, UnderlineAttrs };
+export { AuthoredRunFormattingValues, COMPLEX_SCRIPT_RUN_PROPERTY_KEYS, CharacterSpacingAttrs, CharacterStyleAttrs, CommentAttrs, ComplexScriptRunPropertyKey, EmphasisMarkAttrs, FontFamilyAttrs, FontSizeAttrs, FootnoteRefAttrs, HighlightAttrs, HyperlinkAttrs, InlineWrapperAttrs, InlineWrapperKind, InlineWrapperLayer, LanguageAttrs, PageBreakRunOwnerMarkAttrs, RUN_FORMATTING_BOOLEAN_PROPERTIES, RUN_FORMATTING_PROPERTY_SPECS, RUN_FORMATTING_VALUE_PROPERTIES, RunFormattingBooleanProperty, RunFormattingOverrideAttrs, RunFormattingValueProperty, RunPropertyChangeMarkAttrs, RunShadingAttrs, StrikeAttrs, TRACKED_CHANGE_PROVENANCE_VALUES, TextColorAttrs, TextEffectAttrs, TrackedChangeMarkAttrs, TrackedChangeProvenance, UnderlineAttrs };

package/dist/prosemirror/schema/nodes.d.ts

@@ -21,6 +21,35 @@ type SymbolAttrs = {
   font: string;
   char: string;
 };
+/** A run child folio does not model, carried through the editor untouched. */
+/**
+ * Which container the captured markup came out of, and goes back into.
+ *
+ * `w:ruby` is a run child and has to be written back inside a `w:r`;
+ * `w:permStart` is a paragraph child and the schema admits none inside a run,
+ * so writing one there would produce a package Word repairs. One atom serves
+ * both because the editor treats them identically — opaque, zero-width unless
+ * the markup shows text, carrying whatever marks surround it — and only the
+ * save path has to tell them apart.
+ */
+declare const PRESERVED_XML_LEVELS: {
+  readonly run: "run";
+  readonly inline: "inline";
+};
+type PreservedXmlLevel = (typeof PRESERVED_XML_LEVELS)[keyof typeof PRESERVED_XML_LEVELS];
+/** A run or inline child folio does not model, carried through the editor untouched. */
+type PreservedXmlAttrs = {
+  /** Replayable markup, as `captureVerbatimXml` wrote it. */
+  xml: string;
+  /** The visible text the markup puts on the line, empty when it shows none. */
+  text: string;
+  level: PreservedXmlLevel;
+};
+/** A block child folio does not model, carried through the editor untouched. */
+type PreservedBlockAttrs = {
+  /** Replayable markup, as `captureVerbatimXml` wrote it. */
+  xml: string;
+};
 type BookmarkBoundaryAttrs = {
   type: "start";
   id: number;
@@ -33,6 +62,14 @@ type BookmarkBoundaryAttrs = {
   id: number;
   displacedByCustomXml?: document_d_exports.DisplacedByCustomXml;
 };
+/**
+ * The position of a comment's `w:commentReference`: the run that paints the
+ * visible comment mark. It is authored data, not a consequence of where the
+ * range ends, so the editor carries it as a node of its own.
+ */
+type CommentReferenceAttrs = {
+  commentId: number;
+};
 /**
  * Paragraph node attributes - maps to ParagraphFormatting
  */
@@ -213,6 +250,17 @@ type ParagraphAttrs = {
   /** Full section properties for paragraphs that end a section.
    *  Used by layout engine for per-section column/page config and round-trip. */
   _sectionProperties?: document_d_exports.SectionProperties;
+  /**
+   * Attributes the authored `w:p` carried and the model has no field for
+   * (`w:rsidR` and its family), carried opaquely so an edit does not rewrite
+   * the document's revision history.
+   *
+   * The remainder follows the record. ProseMirror copies a node's attrs to
+   * both halves of a split, so `fromProseDoc` gives it to the first paragraph
+   * that carries it and to no other: a paragraph the editor created never had
+   * those attributes and must not inherit them from a neighbour.
+   */
+  _preservedAttributes?: document_d_exports.PreservedAttribute[];
   /** Paragraph-property-change tracking entries (`w:pPrChange`).
    *  Preserved opaquely through ProseMirror — the editor does not surface
    *  them in UI today, but stripping them on every edit would corrupt the
@@ -302,13 +350,23 @@ type ImageAttrs = {
   displayMode?: "inline" | "float" | "block";
   /** CSS float direction for floating images */
   cssFloat?: "left" | "right" | "none";
-  /** CSS transform string (rotation, flip) */
+  /** CSS transform string, derived from the authored transform below. */
   transform?: string;
+  /** Authored `a:xfrm@rot` in degrees; `null` when the drawing states none. */
+  docxRotation?: number | null;
+  /** Authored `a:xfrm@flipH`; `null` when the drawing states none. */
+  docxFlipH?: boolean | null;
+  /** Authored `a:xfrm@flipV`; `null` when the drawing states none. */
+  docxFlipV?: boolean | null;
   /**
    * Opacity in [0, 1] from `<a:alphaModFix amt>`. Undefined / 1 means fully
    * opaque (no CSS `opacity` emitted). eigenpal #424.
    */
   opacity?: number;
+  /** DrawingML `a:lum@bright` as a signed percentage in [-100, 100]. */
+  brightness?: number;
+  /** DrawingML `a:lum@contrast` as a signed percentage in [-100, 100]. */
+  contrast?: number;
   /** Distance from text above (pixels) */
   distTop?: number;
   /** Distance from text below (pixels) */
@@ -537,8 +595,14 @@ type ShapeAttrs = {
   outlineHeadEnd?: NonNullable<document_d_exports.ShapeOutline["headEnd"]>;
   /** Tail arrow/end marker */
   outlineTailEnd?: NonNullable<document_d_exports.ShapeOutline["tailEnd"]>;
-  /** CSS transform */
+  /** CSS transform, derived from the authored transform below. */
   transform?: string;
+  /** Authored `a:xfrm@rot` in degrees; `null` when the drawing states none. */
+  docxRotation?: number | null;
+  /** Authored `a:xfrm@flipH`; `null` when the drawing states none. */
+  docxFlipH?: boolean | null;
+  /** Authored `a:xfrm@flipV`; `null` when the drawing states none. */
+  docxFlipV?: boolean | null;
   /** Display mode */
   displayMode?: "inline" | "float" | "block";
   /** CSS float */
@@ -618,6 +682,12 @@ type TextBoxAttrs = {
   outlineStyle?: OutlineStyleAttr;
   /** DrawingML rotation and/or flips, serialized as CSS transform functions. */
   transform?: string;
+  /** Authored `a:xfrm@rot` in degrees; `null` when the drawing states none. */
+  docxRotation?: number | null;
+  /** Authored `a:xfrm@flipH`; `null` when the drawing states none. */
+  docxFlipH?: boolean | null;
+  /** Authored `a:xfrm@flipV`; `null` when the drawing states none. */
+  docxFlipV?: boolean | null;
   /** Internal margin top in pixels */
   marginTop?: number;
   /** Internal margin bottom in pixels */
@@ -674,6 +744,17 @@ type TextBoxAttrs = {
   };
   /** Original inline content-control ancestry for save-path reconstruction. */
   _docxInlineSdts?: SdtAttrs[];
+  /**
+   * The attribute remainder of the `w:p` this node was lifted out of.
+   *
+   * A paragraph whose only content was an anchored drawing has no paragraph
+   * node in the editor: this node stands in for it, so it carries the host's
+   * remainder the way `ParagraphAttrs._preservedAttributes` carries a
+   * paragraph's own. Only a `"standalone"` placement has a host to speak for;
+   * an `"inlineWithPrevious"` text box sits in a paragraph that is projected
+   * itself and keeps its own.
+   */
+  _preservedAttributes?: document_d_exports.PreservedAttribute[];
 };
 /** Internal inline position marker for an extracted text box block. */
 type TextBoxAnchorAttrs = {
@@ -748,6 +829,12 @@ type TableRowAttrs = {
   _originalFormatting?: document_d_exports.TableRowFormatting;
   /** Tracked row property changes (w:trPrChange) for round-trip + accept/reject */
   trPrChange?: document_d_exports.TableRowPropertyChange[];
+  /**
+   * Attributes the authored `w:tr` carried and the model has no field for
+   * (`w:rsidR`, `w:rsidDel`, `w:rsidTr`, `w:rsidRPr`), carried opaquely for
+   * the reason `ParagraphAttrs._preservedAttributes` gives.
+   */
+  _preservedAttributes?: document_d_exports.PreservedAttribute[];
 } & ({
   /**
    * Tracked structural row insertion (w:trPr/w:ins). A `"suggested"`
@@ -885,4 +972,4 @@ type TableCellAttrs = {
   _docxVMergeContinuationCells?: unknown;
 };
 //#endregion
-export { AuthoredEmuAttrs, BlockSdtAttrs, BookmarkBoundaryAttrs, FieldAttrs, HardBreakAttrs, ImageAttrs, ImagePositionAttrs, MathAttrs, PageBreakRunAttrs, ParagraphAttrs, ParagraphPropertyChangeAttrs, SdtAttrs, ShapeAttrs, SuggestedStructuralMarker, SymbolAttrs, TEXT_BOX_TEXT_BODY_CONTENT_STATE_TYPES, TabAttrs, TableAttrs, TableCellAttrs, TableRowAttrs, TextBoxAnchorAttrs, TextBoxAttrs, TextBoxTextBodyContentState };
+export { AuthoredEmuAttrs, BlockSdtAttrs, BookmarkBoundaryAttrs, CommentReferenceAttrs, FieldAttrs, HardBreakAttrs, ImageAttrs, ImagePositionAttrs, MathAttrs, PRESERVED_XML_LEVELS, PageBreakRunAttrs, ParagraphAttrs, ParagraphPropertyChangeAttrs, PreservedBlockAttrs, PreservedXmlAttrs, PreservedXmlLevel, SdtAttrs, ShapeAttrs, SuggestedStructuralMarker, SymbolAttrs, TEXT_BOX_TEXT_BODY_CONTENT_STATE_TYPES, TabAttrs, TableAttrs, TableCellAttrs, TableRowAttrs, TextBoxAnchorAttrs, TextBoxAttrs, TextBoxTextBodyContentState };

package/dist/prosemirror/schema/nodes.js

@@ -1,7 +1,22 @@
 //#region src/prosemirror/schema/nodes.ts
+/** A run child folio does not model, carried through the editor untouched. */
+/**
+* Which container the captured markup came out of, and goes back into.
+*
+* `w:ruby` is a run child and has to be written back inside a `w:r`;
+* `w:permStart` is a paragraph child and the schema admits none inside a run,
+* so writing one there would produce a package Word repairs. One atom serves
+* both because the editor treats them identically — opaque, zero-width unless
+* the markup shows text, carrying whatever marks surround it — and only the
+* save path has to tell them apart.
+*/
+const PRESERVED_XML_LEVELS = {
+	run: "run",
+	inline: "inline"
+};
 /**
 * Text box node attributes
 */
 const TEXT_BOX_TEXT_BODY_CONTENT_STATE_TYPES = Object.freeze(["source-empty", "authored"]);
 //#endregion
-export { TEXT_BOX_TEXT_BODY_CONTENT_STATE_TYPES };
+export { PRESERVED_XML_LEVELS, TEXT_BOX_TEXT_BODY_CONTENT_STATE_TYPES };

package/dist/prosemirror/trackedRunInlineAtoms.d.ts

@@ -11,11 +11,13 @@ type TrackedRunInlineAtomDisposition = "carry" | "field-carrier" | "outside-wrap
  */
 declare const TRACKED_RUN_INLINE_ATOM_DISPOSITIONS: Readonly<{
   readonly bookmarkBoundary: "carry";
+  readonly commentReference: "transparent";
   readonly field: "field-carrier";
   readonly hardBreak: "carry";
   readonly image: "carry";
   readonly math: "carry";
   readonly pageBreakRun: "page-break-carrier";
+  readonly preservedXml: "carry";
   readonly renderedPageBreak: "transparent";
   readonly shape: "carry";
   readonly structuredField: "carry";

package/dist/prosemirror/trackedRunInlineAtoms.js

@@ -10,11 +10,13 @@ import { panic } from "better-result";
 */
 const TRACKED_RUN_INLINE_ATOM_DISPOSITIONS = Object.freeze({
 	bookmarkBoundary: "carry",
+	commentReference: "transparent",
 	field: "field-carrier",
 	hardBreak: "carry",
 	image: "carry",
 	math: "carry",
 	pageBreakRun: "page-break-carrier",
+	preservedXml: "carry",
 	renderedPageBreak: "transparent",
 	shape: "carry",
 	structuredField: "carry",

package/dist/prosemirror/validation.js

@@ -1,5 +1,6 @@
-import { readBlockSdtAttrs, readCharacterSpacingMarkAttrs, readCharacterStyleMarkAttrs, readCommentMarkAttrs, readEmphasisMarkAttrs, readFieldAttrs, readFontFamilyMarkAttrs, readFontSizeMarkAttrs, readFootnoteRefMarkAttrs, readHardBreakAttrs, readHighlightMarkAttrs, readHyperlinkMarkAttrs, readImageAttrs, readLanguageMarkAttrs, readMathAttrs, readPageBreakRunAttrs, readPageBreakRunOwnerMarkAttrs, readParagraphAttrs, readRunFormattingOverrideMarkAttrs, readRunPropertyChangeMarkAttrs, readRunShadingMarkAttrs, readSdtAttrs, readShapeAttrs, readStrikeMarkAttrs, readSymbolAttrs, readTabAttrs, readTableAttrs, readTableCellAttrs, readTableRowAttrs, readTextBoxAttrs, readTextColorMarkAttrs, readTextEffectMarkAttrs, readTrackedChangeMarkAttrs, readUnderlineMarkAttrs } from "./attrs/index.js";
+import { readBlockSdtAttrs, readCharacterSpacingMarkAttrs, readCharacterStyleMarkAttrs, readCommentMarkAttrs, readEmphasisMarkAttrs, readFieldAttrs, readFontFamilyMarkAttrs, readFontSizeMarkAttrs, readFootnoteRefMarkAttrs, readHardBreakAttrs, readHighlightMarkAttrs, readHyperlinkMarkAttrs, readImageAttrs, readInlineWrapperMarkAttrs, readLanguageMarkAttrs, readMathAttrs, readPageBreakRunAttrs, readPageBreakRunOwnerMarkAttrs, readParagraphAttrs, readPreservedBlockAttrs, readPreservedXmlAttrs, readRunFormattingOverrideMarkAttrs, readRunPropertyChangeMarkAttrs, readRunShadingMarkAttrs, readSdtAttrs, readShapeAttrs, readStrikeMarkAttrs, readSymbolAttrs, readTabAttrs, readTableAttrs, readTableCellAttrs, readTableRowAttrs, readTextBoxAttrs, readTextColorMarkAttrs, readTextEffectMarkAttrs, readTrackedChangeMarkAttrs, readUnderlineMarkAttrs } from "./attrs/index.js";
 import { readBookmarkBoundaryAttrs } from "./bookmarkBoundaryAttrs.js";
+import { readCommentReferenceAttrs } from "./commentReferenceAttrs.js";
 import { readTextBoxAnchorAttrs } from "./textBoxAnchorAttrs.js";
 //#region src/prosemirror/validation.ts
 var ProseMirrorDocumentValidationError = class extends Error {
@@ -142,12 +143,21 @@ const validateNodeAttrs = (node, path, issues) => {
 		case "bookmarkBoundary":
 			appendAttrIssues(path, readBookmarkBoundaryAttrs(node), issues);
 			return;
+		case "commentReference":
+			appendAttrIssues(path, readCommentReferenceAttrs(node), issues);
+			return;
 		case "tab":
 			appendAttrIssues(path, readTabAttrs(node), issues);
 			return;
 		case "symbol":
 			appendAttrIssues(path, readSymbolAttrs(node), issues);
 			return;
+		case "preservedXml":
+			appendAttrIssues(path, readPreservedXmlAttrs(node), issues);
+			return;
+		case "preservedBlock":
+			appendAttrIssues(path, readPreservedBlockAttrs(node), issues);
+			return;
 		case "hardBreak":
 			appendAttrIssues(path, readHardBreakAttrs(node), issues);
 			return;
@@ -184,6 +194,7 @@ const validateNodeAttrs = (node, path, issues) => {
 				if (fieldAttrs.ok) {
 					const hasStructuredHyperlink = node.content.content.some((child) => child.marks.some((mark) => mark.type.name === "hyperlink"));
 					const hasPageBreakCarrier = node.content.content.some((child) => child.type.name === "pageBreakRun");
+					const hasPreservedCapture = node.content.content.some((child) => child.type.name === "preservedXml");
 					if (fieldAttrs.value.fieldKind === "complex" && !hasPageBreakCarrier) issues.push({
 						path: `${path}.content`,
 						message: "Complex fields cannot contain structured result children."
@@ -192,7 +203,7 @@ const validateNodeAttrs = (node, path, issues) => {
 						path: `${path}.content`,
 						message: "Complex field results cannot contain hyperlink content."
 					});
-					else if (!hasStructuredHyperlink && !hasPageBreakCarrier) issues.push({
+					else if (!hasStructuredHyperlink && !hasPageBreakCarrier && !hasPreservedCapture) issues.push({
 						path: `${path}.content`,
 						message: "Structured simple fields require hyperlink content."
 					});
@@ -314,6 +325,9 @@ const validateMarks = (marks, path, issues) => {
 			case "hyperlink":
 				appendAttrIssues(markPath, readHyperlinkMarkAttrs(mark), issues);
 				continue;
+			case "inlineWrapper":
+				appendAttrIssues(markPath, readInlineWrapperMarkAttrs(mark), issues);
+				continue;
 			default: issues.push({
 				path: `${markPath}.type.name`,
 				message: `Unsupported ProseMirror mark type ${mark.type.name}.`