@beyondwork/docx-react-component 1.0.47 → 1.0.49

package/src/io/docx-session.ts

@@ -44,8 +44,9 @@ import {
   normalizeParsedTextDocument,
   normalizeParsedTextDocumentAsync,
 } from "./normalize/normalize-text.ts";
-import { resolveChartPreviewsForDocument } from "./chart-preview-resolver.ts";
+import { createChartPartLookup, resolveChartPreviewsForDocument } from "./chart-preview-resolver.ts";
 import { type LoadScheduler } from "./load-scheduler.ts";
+import type { CacheEnvelope } from "../runtime/prerender/cache-envelope.ts";
 import {
   CONTENT_TYPES_PATH,
   PACKAGE_RELATIONSHIPS_PATH,
@@ -59,12 +60,14 @@ import {
   getDocumentBackedWorkflowMetadata,
   parseWorkflowPayloadEnvelopeFromPackage,
   resolvePayloadPartPath,
-  resolveWorkflowPayloadPartPaths,
   WORKFLOW_PAYLOAD_CONTENT_TYPE,
   WORKFLOW_PAYLOAD_CUSTOM_PROPS_CONTENT_TYPE,
   WORKFLOW_PAYLOAD_CUSTOM_PROPS_PART_PATH,
   WORKFLOW_PAYLOAD_CUSTOM_PROPS_RELATIONSHIP_TYPE,
   WORKFLOW_PAYLOAD_ITEM_PROPS_CONTENT_TYPE,
+  WORKFLOW_PAYLOAD_ITEM_PROPS_PART_PATH,
+  WORKFLOW_PAYLOAD_PART_PATH,
+  WORKFLOW_PAYLOAD_RELATIONSHIP_TYPE,
 } from "./ooxml/workflow-payload.ts";
 import {
   classifyCorruptPackageError,
@@ -74,6 +77,10 @@ import {
 import { buildAppPropertiesXml } from "./export/build-app-properties-xml.ts";
 import { createExportSession } from "./export/export-session.ts";
 import { serializeMainDocument } from "./export/serialize-main-document.ts";
+import {
+  serializeSettingsXml,
+  WORD_SETTINGS_CONTENT_TYPE,
+} from "./export/serialize-settings.ts";
 import {
   parseRevisionsFromDocumentXml,
   parseRevisionsFromStoryXml,
@@ -262,6 +269,21 @@ interface ImportedDocxState {
   sourceDocumentAttributes: Record<string, string>;
   sourceNumberingPartPath?: string;
   sourceNumberingRelationshipId?: string;
+  /**
+   * Resolved `/word/settings.xml` part path when the source package carried
+   * one. Threaded through to the export path so the settings serializer can
+   * call `replaceOwnedPart` with the right relationship target.
+   */
+  sourceSettingsPartPath?: string;
+  /**
+   * Original settings.xml bytes decoded as UTF-8. Passed to
+   * `serializeSettingsXml(settings, sourceXml)` as the graft source so
+   * unmodelled top-level children (`<w:defaultTabStop>`,
+   * `<w:documentProtection>`, mail-merge state, etc.) survive verbatim
+   * through round-trip. Undefined when the source package lacked a
+   * settings part.
+   */
+  sourceSettingsXml?: string;
   sourceCommentsPartPath?: string;
   sourceCommentsRelationshipId?: string;
   sourceCommentsRootTag?: string;
@@ -426,11 +448,17 @@ export function loadDocxEditorSession(
         )
       : createEmptyNumberingCatalog();
     const mediaParts = collectInlineMediaParts(sourcePackage);
+    const chartPartLookup = createChartPartLookup(
+      sourcePackage,
+      mainDocumentPath,
+      documentPart.relationships,
+    );
     const parsedDocument = parseMainDocumentXml(
       sourceDocumentXml,
       documentPart.relationships,
       mediaParts,
       mainDocumentPath,
+      chartPartLookup,
     );
     const protectionRanges = extractProtectionRanges(parsedDocument.blocks);
     const normalizedDocument = normalizeParsedTextDocument(
@@ -829,6 +857,9 @@ export function loadDocxEditorSession(
           relationship.type === NUMBERING_RELATIONSHIP_TYPE &&
           relationship.targetMode === "internal",
       )?.id,
+      sourceSettingsPartPath: settingsPartPath,
+      sourceSettingsXml:
+        settingsXmlForProtection.length > 0 ? settingsXmlForProtection : undefined,
       sourceCommentsPartPath: commentsPartPath,
       sourceCommentsRelationshipId: documentPart.relationships.find(
         (relationship) =>
@@ -896,7 +927,7 @@ export function loadDocxEditorSession(
   }
 }
 
-interface LoadDocxEditorSessionAsyncOptions extends LoadDocxEditorSessionOptions {
+export interface LoadDocxEditorSessionAsyncOptions extends LoadDocxEditorSessionOptions {
   /**
    * Scheduler that the async loader awaits between parse stages. Callers
    * in DOM environments should construct this with `createLoadScheduler()`
@@ -907,6 +938,27 @@ interface LoadDocxEditorSessionAsyncOptions extends LoadDocxEditorSessionOptions
    * behaves like the sync path from the test harness POV.
    */
   scheduler: LoadScheduler;
+  /**
+   * L7 Phase 2.5 Plan B B.6b — optional laycache envelope. When supplied,
+   * `loadDocxEditorSessionAsync` still performs the cheap OPC read +
+   * workflow-payload parse (needed for `initialEditorStatePayload`,
+   * `workflowOverlay`, and `workflowMetadata`), then skips the five
+   * expensive stages — `parseMainDocumentXml`,
+   * `normalizeParsedTextDocumentAsync`, `parseCommentsFromOoxml`,
+   * `parseStylesXml`, and `createImportedCanonicalDocument` — and uses
+   * `envelope.canonicalDocument` directly (reference-equal, no clone).
+   *
+   * Callers obtain a validated envelope by calling
+   * `tryReadLaycacheEnvelope(bytes)` before invoking this function; when
+   * the probe returns `null`, omit this field and the loader runs the
+   * full parse.
+   *
+   * Async-only — the sync `loadDocxEditorSession` does not honor this
+   * option. `buildCompatibilityReport` and
+   * `resolveChartPreviewsForDocument` still run on the short-circuit
+   * path because their outputs are required by downstream consumers.
+   */
+  laycacheEnvelope?: CacheEnvelope;
 }
 
 /**
@@ -1006,6 +1058,137 @@ export async function loadDocxEditorSessionAsync(
   }
 
   try {
+    // L7 Phase 2.5 Plan B B.6b — loader short-circuit. Hand
+    // `envelope.canonicalDocument` through reference-equal and skip the
+    // five expensive parse stages. The four `onLoadStage` callbacks still
+    // fire in order — `body` and `styles-numbering-comments` emit with
+    // near-zero duration — so host progress bars are unaffected.
+    if (options.laycacheEnvelope) {
+      stages.emit("body");
+      stages.emit("styles-numbering-comments");
+
+      const canonicalDocument = options.laycacheEnvelope.canonicalDocument;
+
+      // `extractProtectionRanges` needs `parsedDocument.blocks` (which we
+      // are skipping), so the short-circuit uses an empty ranges list;
+      // document-level `editType` / `enforcement` still come from
+      // settings.xml so read-only docs stay read-only.
+      const settingsPartPath = resolveDocumentRelatedPartPath(
+        sourcePackage,
+        mainDocumentPath,
+        documentPart.relationships,
+        SETTINGS_RELATIONSHIP_TYPE,
+        SETTINGS_PART_PATH,
+      );
+      const settingsXml =
+        settingsPartPath && sourcePackage.parts.has(settingsPartPath)
+          ? decodeUtf8(
+              sourcePackage.parts.get(settingsPartPath)?.bytes ?? new Uint8Array(),
+            )
+          : "";
+      const documentProtection = extractDocumentProtection(settingsXml);
+      const protectionSnapshot = buildProtectionSnapshot(documentProtection, []);
+
+      // Chart previews (`previewMediaId` is host-dependent) aren't cached
+      // in the envelope, so we still resolve them on the short-circuit.
+      const documentWithChartPreviews = (await resolveChartPreviewsForDocument(
+        canonicalDocument,
+        sourcePackage,
+        options.hostAdapter,
+      )) as CanonicalDocumentEnvelope;
+
+      const timestamp = new Date().toISOString();
+      const compatibility = buildCompatibilityReport({
+        document: documentWithChartPreviews,
+        generatedAt: timestamp,
+      });
+      await scheduler.yield();
+
+      const snapshot = createImportedSnapshot({
+        documentId: options.documentId,
+        editorBuild,
+        timestamp,
+        document: documentWithChartPreviews,
+        compatibility: toPublicCompatibilityReport(compatibility),
+        protectionSnapshot,
+        sourcePackage: createPersistedSourcePackage(sourceBytes, options.sourceLabel),
+        workflowOverlay: embeddedWorkflowOverlay,
+        workflowMetadata: embeddedWorkflowMetadata,
+      });
+      const snapshotIssues = validatePersistedEditorSnapshot(snapshot);
+      if (snapshotIssues.length > 0) {
+        const firstIssue = snapshotIssues[0];
+        return createDiagnosticsSession(
+          options,
+          createValidationImportDiagnostics({
+            message: `DOCX import produced an invalid editor state during validation${firstIssue ? ` (${firstIssue.path}: ${firstIssue.message})` : "."}`,
+            source: "import",
+            details: {
+              issueCount: snapshotIssues.length,
+              firstIssuePath: firstIssue?.path,
+            },
+          }),
+        );
+      }
+
+      // Build `initialSessionState` inline — bypassing
+      // `editorSessionStateFromPersistedSnapshot`'s structuredClone so
+      // `session.initialSessionState.canonicalDocument` is reference-equal
+      // to `envelope.canonicalDocument` (cloning a large canonical document
+      // defeats part of the cache gain).
+      const sessionState: EditorSessionState = {
+        sessionVersion: "editor-session-state/1",
+        schemaVersion: snapshot.schemaVersion,
+        documentId: snapshot.documentId,
+        docId: snapshot.docId,
+        createdAt: snapshot.createdAt,
+        updatedAt: snapshot.updatedAt,
+        editorBuild: snapshot.editorBuild,
+        canonicalDocument: snapshot.canonicalDocument,
+        compatibility: snapshot.compatibility,
+        warningLog: snapshot.warningLog,
+        protectionSnapshot: snapshot.protectionSnapshot,
+        sourcePackage: snapshot.sourcePackage,
+        workflowOverlay: snapshot.workflowOverlay,
+        workflowMetadata: snapshot.workflowMetadata,
+      };
+
+      // The short-circuit path does not carry an `ImportedDocxState`, so
+      // `exportDocx` lazily re-runs the cold path on first invocation and
+      // memoizes. Keeps the warm-load fast while preserving byte-exact
+      // export correctness.
+      let lazyColdExport: LoadedDocxEditorSession["exportDocx"] | undefined;
+      const exportDocx: LoadedDocxEditorSession["exportDocx"] = async (
+        nextSessionStateOrSnapshot,
+        exportOptions,
+      ) => {
+        if (!lazyColdExport) {
+          const { laycacheEnvelope: _unused, ...coldOptions } = options;
+          void _unused;
+          const coldSession = await loadDocxEditorSessionAsync(coldOptions);
+          if (coldSession.fatalError) {
+            throw new Error(
+              `DOCX export via short-circuit fallback failed cold load: ${coldSession.fatalError.message ?? "fatal error"}`,
+            );
+          }
+          lazyColdExport = coldSession.exportDocx;
+        }
+        return lazyColdExport(nextSessionStateOrSnapshot, exportOptions);
+      };
+
+      stages.emit("skeleton-ready");
+      return {
+        initialSessionState: sessionState,
+        initialSnapshot: snapshot,
+        readOnly: false,
+        protectionSnapshot,
+        exportDocx,
+        ...(embeddedWorkflowPayload?.editorState
+          ? { initialEditorStatePayload: embeddedWorkflowPayload.editorState }
+          : {}),
+      };
+    }
+
     const sourceDocumentXml = decodeUtf8(documentPart.bytes);
     const importedRevisions = parseRevisionsFromDocumentXml(sourceDocumentXml);
     const numberingPartPath = resolveDocumentRelatedPartPath(
@@ -1021,11 +1204,17 @@ export async function loadDocxEditorSessionAsync(
         )
       : createEmptyNumberingCatalog();
     const mediaParts = collectInlineMediaParts(sourcePackage);
+    const chartPartLookup = createChartPartLookup(
+      sourcePackage,
+      mainDocumentPath,
+      documentPart.relationships,
+    );
     const parsedDocument = parseMainDocumentXml(
       sourceDocumentXml,
       documentPart.relationships,
       mediaParts,
       mainDocumentPath,
+      chartPartLookup,
     );
     await scheduler.yield();
     const protectionRanges = extractProtectionRanges(parsedDocument.blocks);
@@ -1440,6 +1629,9 @@ export async function loadDocxEditorSessionAsync(
           relationship.type === NUMBERING_RELATIONSHIP_TYPE &&
           relationship.targetMode === "internal",
       )?.id,
+      sourceSettingsPartPath: settingsPartPath,
+      sourceSettingsXml:
+        settingsXmlForProtection.length > 0 ? settingsXmlForProtection : undefined,
       sourceCommentsPartPath: commentsPartPath,
       sourceCommentsRelationshipId: documentPart.relationships.find(
         (relationship) =>
@@ -1734,23 +1926,29 @@ function exportDocxEditorSession(
     }
   }
 
-  const workflowPayloadPartPaths = resolveWorkflowPayloadPartPaths(
-    state.sourcePackage,
-    sessionState.documentId,
-  );
+  // Settings.xml is owned when the source package carried one OR the canonical
+  // model carries settings we need to re-emit. The `canReuse && signatureMatch`
+  // short-circuit above already skips re-export entirely for no-edit sessions,
+  // so every path that reaches here is willing to emit a rebuilt settings.xml.
+  const settingsPartPath =
+    state.sourceSettingsPartPath ?? SETTINGS_PART_PATH;
+  const hasSettingsSurface =
+    Boolean(state.sourceSettingsPartPath) ||
+    exportedSubParts?.settings !== undefined;
 
   const exportSession = createExportSession(state.sourcePackage, [
     state.sourceDocumentPartPath,
     APP_PROPERTIES_PART_PATH,
     CORE_PROPERTIES_PART_PATH,
-    workflowPayloadPartPaths.payloadPartPath,
-    workflowPayloadPartPaths.itemPropsPartPath,
+    WORKFLOW_PAYLOAD_PART_PATH,
+    WORKFLOW_PAYLOAD_ITEM_PROPS_PART_PATH,
     WORKFLOW_PAYLOAD_CUSTOM_PROPS_PART_PATH,
     numberingPartPath,
     commentsPartPath,
     commentsExtendedPartPath,
     commentsIdsPartPath,
     peoplePartPath,
+    ...(hasSettingsSurface ? [settingsPartPath] : []),
     ...subPartOwnedPaths,
   ]);
 
@@ -1784,6 +1982,22 @@ function exportDocxEditorSession(
     });
   }
 
+  if (hasSettingsSurface) {
+    // Canonical settings ∅ + no source settings → omit the owned-part write
+    // (hasSettingsSurface is already false in that case). Otherwise route
+    // through the graft serializer so unmodelled children round-trip via
+    // source bytes while canonical mutations land.
+    const canonicalSettings = exportedSubParts?.settings ?? {};
+    const settingsXml = serializeSettingsXml(canonicalSettings, state.sourceSettingsXml);
+    exportSession.replaceOwnedPart({
+      path: settingsPartPath,
+      bytes: new TextEncoder().encode(settingsXml),
+      contentType:
+        state.sourcePackage.parts.get(settingsPartPath)?.contentType ??
+        WORD_SETTINGS_CONTENT_TYPE,
+    });
+  }
+
   if (serializedComments.serializedCommentIds.length > 0 || state.sourceCommentsPartPath) {
     exportSession.replaceOwnedPart({
       path: commentsPartPath,
@@ -1977,14 +2191,7 @@ function exportDocxEditorSession(
   ensureHostMetadataParts(exportSession, state.sourcePackage, currentDocument);
   // Schema 1.2: pass through editorState payload collected by the runtime channel.
   const internalEditorState = (options as { _editorState?: import("./ooxml/workflow-payload.ts").EditorStatePayload } | undefined)?._editorState;
-  ensureWorkflowPayloadParts(
-    exportSession,
-    sessionState,
-    currentDocument,
-    state.sourcePackage,
-    internalEditorState,
-    workflowPayloadPartPaths,
-  );
+  ensureWorkflowPayloadParts(exportSession, sessionState, currentDocument, state.sourcePackage, internalEditorState);
 
   return {
     bytes: exportSession.serialize(),
@@ -3711,7 +3918,6 @@ function ensureWorkflowPayloadParts(
   document: CanonicalDocumentEnvelope,
   sourcePackage: OpcPackage,
   editorState?: import("./ooxml/workflow-payload.ts").EditorStatePayload,
-  precomputedPartPaths?: { payloadPartPath: string; itemPropsPartPath: string },
 ): void {
   const payloadParts = buildWorkflowPayloadParts({
     sourcePackage,
@@ -3727,37 +3933,19 @@ function ensureWorkflowPayloadParts(
     return;
   }
 
-  // Export ownership is resolved before session creation, so any precomputed
-  // paths must stay in lockstep with buildWorkflowPayloadParts for the same
-  // source package and documentId.
-  if (precomputedPartPaths) {
-    if (
-      precomputedPartPaths.payloadPartPath !== payloadParts.payloadPartPath ||
-      precomputedPartPaths.itemPropsPartPath !== payloadParts.itemPropsPartPath
-    ) {
-      throw new Error(
-        `ensureWorkflowPayloadParts: precomputed payload part paths `
-          + `(${precomputedPartPaths.payloadPartPath} / ${precomputedPartPaths.itemPropsPartPath}) `
-          + `do not match buildWorkflowPayloadParts output `
-          + `(${payloadParts.payloadPartPath} / ${payloadParts.itemPropsPartPath}). `
-          + `This is a bug in the export orchestration.`,
-      );
-    }
-  }
-
   const payloadPart = sourcePackage.parts.get(payloadParts.payloadPartPath);
   const itemPropsPart = sourcePackage.parts.get(payloadParts.itemPropsPartPath);
   const customPropsPart = sourcePackage.parts.get(WORKFLOW_PAYLOAD_CUSTOM_PROPS_PART_PATH);
 
   exportSession.replaceOwnedPart({
-    path: precomputedPartPaths?.payloadPartPath ?? payloadParts.payloadPartPath,
+    path: payloadParts.payloadPartPath,
     bytes: new TextEncoder().encode(payloadParts.payloadPartXml),
     contentType: payloadPart?.contentType ?? WORKFLOW_PAYLOAD_CONTENT_TYPE,
     relationships: payloadParts.payloadRelationships,
     compression: payloadPart?.compression,
   });
   exportSession.replaceOwnedPart({
-    path: precomputedPartPaths?.itemPropsPartPath ?? payloadParts.itemPropsPartPath,
+    path: payloadParts.itemPropsPartPath,
     bytes: new TextEncoder().encode(payloadParts.itemPropsXml),
     contentType: itemPropsPart?.contentType ?? WORKFLOW_PAYLOAD_ITEM_PROPS_CONTENT_TYPE,
     compression: itemPropsPart?.compression,

package/src/io/export/serialize-main-document.ts

@@ -15,6 +15,7 @@ import type {
 } from "../../model/canonical-document.ts";
 import type { OpcRelationship } from "../ooxml/part-manifest.ts";
 import type { RevisionParagraphBoundary } from "../ooxml/revision-boundaries.ts";
+import { SCOPE_MARKER_BOOKMARK_PREFIX } from "../ooxml/parse-scope-markers.ts";
 import { getOpaqueFragment } from "../../preservation/store.ts";
 import { retainRelationshipsForFragment } from "../../preservation/relationship-retention.ts";
 import { serializeParagraphNumberingProperties } from "./serialize-numbering.ts";
@@ -25,6 +26,7 @@ import {
 } from "./table-properties-xml.ts";
 import { twip } from "./twip.ts";
 import { escapeXmlAttribute } from "./escape-xml-attribute.ts";
+import { emitPropertyGrabBag } from "../ooxml/property-grab-bag.ts";
 
 const HYPERLINK_RELATIONSHIP_TYPE =
   "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink";
@@ -571,6 +573,21 @@ function serializeTableInlineNode(
       );
     case "bookmark_end":
       return `<w:bookmarkEnd w:id="${escapeXmlAttribute(node.bookmarkId)}"/>`;
+    case "scope_marker_start": {
+      // S1 — scope markers export as w:bookmarkStart with the reserved
+      // `bw:scope:` name prefix. The synthetic w:id is keyed on scopeId so
+      // the matching end element references the same id.
+      const bkId = `scope-${node.scopeId}`;
+      const name = `${SCOPE_MARKER_BOOKMARK_PREFIX}${node.scopeId}`;
+      return (
+        `<w:bookmarkStart w:id="${escapeXmlAttribute(bkId)}"` +
+        ` w:name="${escapeXmlAttribute(name)}"/>`
+      );
+    }
+    case "scope_marker_end": {
+      const bkId = `scope-${node.scopeId}`;
+      return `<w:bookmarkEnd w:id="${escapeXmlAttribute(bkId)}"/>`;
+    }
     case "footnote_ref": {
       const refElement =
         node.noteKind === "footnote"
@@ -1060,6 +1077,27 @@ function serializeInlineNode(
       boundaries.set(cursor, xmlOffset + xml.length);
       return { xml, cursor, boundaries };
     }
+    case "scope_marker_start": {
+      // S1 — mirror the bookmark_start shape with the reserved `bw:scope:`
+      // name prefix. See serializeInline() above for the same convention.
+      const bkId = `scope-${node.scopeId}`;
+      const name = `${SCOPE_MARKER_BOOKMARK_PREFIX}${node.scopeId}`;
+      const xml =
+        `<w:bookmarkStart w:id="${escapeXmlAttribute(bkId)}"` +
+        ` w:name="${escapeXmlAttribute(name)}"/>`;
+      const boundaries = new Map<number, number>();
+      boundaries.set(cursor, xmlOffset);
+      boundaries.set(cursor, xmlOffset + xml.length);
+      return { xml, cursor, boundaries };
+    }
+    case "scope_marker_end": {
+      const bkId = `scope-${node.scopeId}`;
+      const xml = `<w:bookmarkEnd w:id="${escapeXmlAttribute(bkId)}"/>`;
+      const boundaries = new Map<number, number>();
+      boundaries.set(cursor, xmlOffset);
+      boundaries.set(cursor, xmlOffset + xml.length);
+      return { xml, cursor, boundaries };
+    }
     case "footnote_ref": {
       const refElement =
         node.noteKind === "footnote"
@@ -1570,6 +1608,14 @@ export function serializeSectionPropertiesXml(props: SectionProperties): string
     }
   }
 
+  // O2 Slice 4 grab-bag: unmodelled sectPr children preserved verbatim
+  // from import. Emitted last so the modelled body stays ECMA-376 canonical
+  // and extension-namespace properties land at the tail of <w:sectPr>.
+  const grabBagXml = emitPropertyGrabBag(props.unknownPropertyChildren);
+  if (grabBagXml.length > 0) {
+    children.push(grabBagXml);
+  }
+
   if (children.length === 0) {
     return "<w:sectPr/>";
   }

package/src/io/export/serialize-paragraph-formatting.ts

@@ -12,6 +12,7 @@ import type {
   ParagraphSpacing,
   TabStop,
 } from "../../model/canonical-document.ts";
+import { emitPropertyGrabBag } from "../ooxml/property-grab-bag.ts";
 import { buildRunPropertiesXml } from "./serialize-run-formatting.ts";
 
 function escXml(value: string): string {
@@ -147,6 +148,13 @@ export function buildParagraphPropertiesXml(
     if (markXml) parts.push(markXml);
   }
 
+  // 16. Grab-bag: unmodelled pPr children preserved verbatim from import.
+  // Emitted last so the typed emit order above stays ECMA-376 canonical and
+  // any extension-namespace properties land after the modelled set. Word
+  // tolerates extra trailing children inside <w:pPr> better than it
+  // tolerates interleaving them with the typed set.
+  parts.push(emitPropertyGrabBag(pPr.unknownPropertyChildren));
+
   const body = parts.filter(Boolean).join("");
   return body.length > 0 ? `<w:pPr>${body}</w:pPr>` : "";
 }

package/src/io/export/serialize-run-formatting.ts

@@ -8,6 +8,7 @@
  */
 
 import type { CanonicalRunFormatting } from "../../model/canonical-document.ts";
+import { emitPropertyGrabBag } from "../ooxml/property-grab-bag.ts";
 
 function escXml(value: string): string {
   return value
@@ -57,10 +58,12 @@ export function buildRunPropertiesXml(rPr: CanonicalRunFormatting | undefined):
   parts.push(toggleEl("vanish", rPr.vanish));
 
   // 8. color
-  if (rPr.colorHex || rPr.colorThemeSlot) {
+  if (rPr.colorHex || rPr.colorThemeSlot || rPr.colorThemeTint || rPr.colorThemeShade) {
     const attrs: string[] = [];
     if (rPr.colorHex) attrs.push(`w:val="${escXml(rPr.colorHex)}"`);
     if (rPr.colorThemeSlot) attrs.push(`w:themeColor="${escXml(rPr.colorThemeSlot)}"`);
+    if (rPr.colorThemeTint) attrs.push(`w:themeTint="${escXml(rPr.colorThemeTint)}"`);
+    if (rPr.colorThemeShade) attrs.push(`w:themeShade="${escXml(rPr.colorThemeShade)}"`);
     parts.push(`<w:color ${attrs.join(" ")}/>`);
   }
 
@@ -85,6 +88,12 @@ export function buildRunPropertiesXml(rPr: CanonicalRunFormatting | undefined):
   if (rPr.fontSizeHalfPoints !== undefined) parts.push(`<w:sz w:val="${rPr.fontSizeHalfPoints}"/>`);
   if (rPr.fontSizeCsHalfPoints !== undefined) parts.push(`<w:szCs w:val="${rPr.fontSizeCsHalfPoints}"/>`);
 
+  // 15. Grab-bag: unmodelled rPr children preserved verbatim from import
+  // (extension-namespace properties like <w14:textOutline>, Word-internal
+  // knobs like <w:em>, <w:kern>). Emitted last so the typed body stays
+  // ECMA-376 canonical and Word tolerates extras at the tail of <w:rPr>.
+  parts.push(emitPropertyGrabBag(rPr.unknownPropertyChildren));
+
   const body = parts.filter(Boolean).join("");
   return body.length > 0 ? `<w:rPr>${body}</w:rPr>` : "";
 }