@beyondwork/docx-react-component 1.0.46 → 1.0.48

package/src/core/schema/text-schema.ts

@@ -26,6 +26,7 @@ export type StoryUnit =
   | ImageUnit
   | OpaqueInlineUnit
   | OpaqueBlockUnit
+  | ScopeMarkerUnit
   | ParagraphBreakUnit;
 
 export interface TextCharacterUnit {
@@ -69,6 +70,18 @@ export interface ParagraphBreakUnit {
   nextParagraph: ParagraphProperties;
 }
 
+/**
+ * Zero-width inline unit that preserves S1 scope-marker nodes through text
+ * transactions. Without this unit, scope markers would be silently dropped
+ * during `parseTextStory` / `serializeTextStory`, and any `text.insert` /
+ * `text.delete-*` dispatch would vaporize the structural scope anchors.
+ */
+export interface ScopeMarkerUnit {
+  kind: "scope_marker";
+  boundary: "start" | "end";
+  scopeId: string;
+}
+
 export function parseTextStory(content: unknown): TextStory {
   const root = normalizeDocumentRoot(content);
   const firstParagraphNode = root.children.find(isParagraphNode);
@@ -111,10 +124,60 @@ export function parseTextStory(content: unknown): TextStory {
   return {
     firstParagraph,
     units,
-    size: units.length,
+    size: countLogicalPositions(units),
   };
 }
 
+/**
+ * Story positions are logical — scope-marker units are preserved in the
+ * `units` array for round-trip fidelity but they do NOT consume a position.
+ * This matches the surface-projection treatment (markers = 0 width, same as
+ * bookmark_start / bookmark_end) so a position 3 set via `selection.set`
+ * resolves to the same character in both views.
+ */
+export function countLogicalPositions(units: StoryUnit[]): number {
+  let size = 0;
+  for (const unit of units) {
+    if (unit.kind !== "scope_marker") size += 1;
+  }
+  return size;
+}
+
+/**
+ * Translate a logical (scope-marker-skipping) position into a unit-array
+ * index. Walks units and increments the unit cursor once per non-marker unit;
+ * scope markers are passed over transparently. Returns `units.length` when
+ * the logical position is at or beyond end-of-story.
+ *
+ * When `startBias === "after"` (default), the returned unit index is the
+ * first position AFTER any scope markers that sit exactly at the logical
+ * boundary — useful when slicing units as "...before this cursor". When
+ * `startBias === "before"`, markers at the boundary are included in the
+ * "after" slice.
+ */
+export function logicalPositionToUnitIndex(
+  units: StoryUnit[],
+  logicalPos: number,
+  startBias: "before" | "after" = "after",
+): number {
+  let logicalCursor = 0;
+  let unitIndex = 0;
+  while (unitIndex < units.length) {
+    if (logicalCursor === logicalPos && startBias === "before") {
+      return unitIndex;
+    }
+    const unit = units[unitIndex]!;
+    if (unit.kind !== "scope_marker") {
+      if (logicalCursor === logicalPos && startBias === "after") {
+        return unitIndex;
+      }
+      logicalCursor += 1;
+    }
+    unitIndex += 1;
+  }
+  return unitIndex;
+}
+
 export function serializeTextStory(story: TextStory): DocumentRootNode {
   const blocks: Array<ParagraphNode | OpaqueBlockNode> = [];
   let currentParagraph: ParagraphNode | undefined = createParagraph(story.firstParagraph);
@@ -272,6 +335,15 @@ export function serializeTextStory(story: TextStory): DocumentRootNode {
           warningId: unit.warningId,
         });
         break;
+      case "scope_marker":
+        pushInlineNode({
+          type:
+            unit.boundary === "start"
+              ? "scope_marker_start"
+              : "scope_marker_end",
+          scopeId: unit.scopeId,
+        });
+        break;
     }
   }
 
@@ -305,6 +377,8 @@ export function createPlainText(story: TextStory): string {
           return "\uFFF9";
         case "opaque_block":
           return "\uFFFA";
+        case "scope_marker":
+          return "";
       }
     })
     .join("");
@@ -355,6 +429,12 @@ export function cloneStoryUnit(unit: StoryUnit): StoryUnit {
         kind: "paragraph_break",
         nextParagraph: cloneParagraphProperties(unit.nextParagraph),
       };
+    case "scope_marker":
+      return {
+        kind: "scope_marker",
+        boundary: unit.boundary,
+        scopeId: unit.scopeId,
+      };
   }
 }
 
@@ -442,6 +522,20 @@ function flattenInlineNodes(
           warningId: node.warningId,
         });
         break;
+      case "scope_marker_start":
+        units.push({
+          kind: "scope_marker",
+          boundary: "start",
+          scopeId: node.scopeId,
+        });
+        break;
+      case "scope_marker_end":
+        units.push({
+          kind: "scope_marker",
+          boundary: "end",
+          scopeId: node.scopeId,
+        });
+        break;
     }
   }
 

package/src/core/state/text-transaction.ts

@@ -3,7 +3,9 @@ import type { TransactionMapping } from "../selection/mapping.ts";
 import {
   cloneParagraphProperties,
   cloneStoryUnit,
+  countLogicalPositions,
   createPlainText,
+  logicalPositionToUnitIndex,
   parseTextStory,
   serializeTextStory,
   type ParagraphProperties,
@@ -117,12 +119,18 @@ function applyLinearTextTransaction(
   const normalizedRange = resolveRange(selection, story.size, intent);
   const insertionUnits = createInsertionUnits(intent, story, normalizedRange.from);
 
-  ensureEditableRange(story.units.slice(normalizedRange.from, normalizedRange.to));
+  // `normalizedRange.{from,to}` are logical positions (scope markers = 0 width,
+  // matching surface-projection). Translate to unit-array indices so scope
+  // marker units preserved at the boundary stay intact on either side.
+  const unitFrom = logicalPositionToUnitIndex(story.units, normalizedRange.from, "before");
+  const unitTo = logicalPositionToUnitIndex(story.units, normalizedRange.to, "after");
+
+  ensureEditableRange(story.units.slice(unitFrom, unitTo));
 
   const nextUnits = [
-    ...story.units.slice(0, normalizedRange.from).map(cloneStoryUnit),
+    ...story.units.slice(0, unitFrom).map(cloneStoryUnit),
     ...insertionUnits.map(cloneStoryUnit),
-    ...story.units.slice(normalizedRange.to).map(cloneStoryUnit),
+    ...story.units.slice(unitTo).map(cloneStoryUnit),
   ];
 
   const nextStory: TextStory = {
@@ -130,9 +138,13 @@ function applyLinearTextTransaction(
     units: normalizeStoryUnits(nextUnits),
     size: 0,
   };
-  nextStory.size = nextStory.units.length;
+  nextStory.size = countLogicalPositions(nextStory.units);
 
-  const caret = normalizedRange.from + insertionUnits.length;
+  // `normalizedRange.from` is the logical insertion point; count the logical
+  // positions added by `insertionUnits` (skipping any scope markers) to derive
+  // the post-insert caret.
+  const logicalInsertionSize = countLogicalPositions(insertionUnits);
+  const caret = normalizedRange.from + logicalInsertionSize;
 
   return {
     document: {

package/src/io/chart-preview-resolver.ts

@@ -214,6 +214,33 @@ function extractPartTextFromPackage(pkg: OpcPackage, path: string): string | und
   }
 }
 
+/**
+ * Build a chart-part lookup callback suitable for
+ * `parseMainDocumentXml(..., chartPartLookup)`.
+ *
+ * The callback is called synchronously during parsing with a chart
+ * relationship id (the `r:id` on a `<c:chart>` reference). It resolves
+ * the id to a chart-part target path via the document's relationship
+ * table, then decodes the matching package part's bytes as UTF-8. Unknown
+ * ids and missing parts return undefined, in which case the parser
+ * proceeds without a typed `ChartModel` (the drawing still produces a
+ * `ChartPreviewNode` with `rawXml`).
+ */
+export function createChartPartLookup(
+  pkg: OpcPackage,
+  documentPartPath: string,
+  documentRelationships: readonly import("./ooxml/part-manifest.ts").OpcRelationship[],
+): (rId: string) => string | undefined {
+  const relById = new Map(documentRelationships.map((r) => [r.id, r]));
+  return (rId: string): string | undefined => {
+    const rel = relById.get(rId);
+    if (!rel) return undefined;
+    const target = resolveRelationshipTarget(documentPartPath, rel);
+    if (!target) return undefined;
+    return extractPartTextFromPackage(pkg, normalizePartPath(target));
+  };
+}
+
 /**
  * Produce a new CanonicalDocument with the resolved chart_preview
  * nodes carrying previewMediaId + corresponding MediaCatalog entries.

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,
@@ -76,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,
@@ -264,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;
@@ -428,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(
@@ -831,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) =>
@@ -898,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()`
@@ -909,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;
 }
 
 /**
@@ -1008,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(
@@ -1023,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);
@@ -1442,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) =>
@@ -1736,6 +1926,16 @@ function exportDocxEditorSession(
     }
   }
 
+  // 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,
@@ -1748,6 +1948,7 @@ function exportDocxEditorSession(
     commentsExtendedPartPath,
     commentsIdsPartPath,
     peoplePartPath,
+    ...(hasSettingsSurface ? [settingsPartPath] : []),
     ...subPartOwnedPaths,
   ]);
 
@@ -1781,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,

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";
@@ -571,6 +572,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 +1076,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"