@beyondwork/docx-react-component 1.0.60 → 1.0.61

package/src/io/ooxml/parse-paragraph-formatting.ts

@@ -132,11 +132,35 @@ function readShading(node: XmlElementNode): ParagraphShading | undefined {
   const val = node.attributes["w:val"] ?? node.attributes.val;
   const fill = node.attributes["w:fill"] ?? node.attributes.fill;
   const color = node.attributes["w:color"] ?? node.attributes.color;
-  if (!val && !fill && !color) return undefined;
+  const themeFill = node.attributes["w:themeFill"] ?? node.attributes.themeFill;
+  const themeFillTint = node.attributes["w:themeFillTint"] ?? node.attributes.themeFillTint;
+  const themeFillShade = node.attributes["w:themeFillShade"] ?? node.attributes.themeFillShade;
+  const themeColor = node.attributes["w:themeColor"] ?? node.attributes.themeColor;
+  const themeColorTint = node.attributes["w:themeColorTint"] ?? node.attributes.themeColorTint;
+  const themeColorShade = node.attributes["w:themeColorShade"] ?? node.attributes.themeColorShade;
+  if (
+    !val &&
+    !fill &&
+    !color &&
+    !themeFill &&
+    !themeFillTint &&
+    !themeFillShade &&
+    !themeColor &&
+    !themeColorTint &&
+    !themeColorShade
+  ) {
+    return undefined;
+  }
   return {
     ...(val ? { val } : {}),
     ...(fill ? { fill } : {}),
     ...(color ? { color } : {}),
+    ...(themeFill ? { themeFill } : {}),
+    ...(themeFillTint ? { themeFillTint } : {}),
+    ...(themeFillShade ? { themeFillShade } : {}),
+    ...(themeColor ? { themeColor } : {}),
+    ...(themeColorTint ? { themeColorTint } : {}),
+    ...(themeColorShade ? { themeColorShade } : {}),
   };
 }
 

package/src/io/ooxml/parse-settings.ts

@@ -3,6 +3,7 @@ import type {
   ClrSchemeMapping,
   ClrSchemeMappingSlot,
   DocumentSettings,
+  FootnoteProperties,
   ThemeColorSlot,
 } from "../../model/canonical-document.ts";
 import { parseXml } from "./xml-parser.ts";
@@ -51,6 +52,13 @@ export function parseSettingsXml(xml: string): DocumentSettings {
   const compatPartition = compat ? partitionCompat(compat) : undefined;
   const rootCompatFlags = readRootCompatFlags(settingsElement);
   const themeFontLangElement = findChildElementOptional(settingsElement, "themeFontLang");
+  const defaultTabStop = readDefaultTabStop(settingsElement);
+  const footnotePr = readFootnoteLikeProperties(
+    findChildElementOptional(settingsElement, "footnotePr"),
+  );
+  const endnotePr = readFootnoteLikeProperties(
+    findChildElementOptional(settingsElement, "endnotePr"),
+  );
   const clrSchemeMapping = parseClrSchemeMapping(settingsElement);
   const unmodelled = readUnmodelledSettingsChildren(settingsElement);
 
@@ -71,6 +79,9 @@ export function parseSettingsXml(xml: string): DocumentSettings {
     ...(themeFontLangElement
       ? { themeFontLang: { ...themeFontLangElement.attributes } }
       : {}),
+    ...(defaultTabStop !== undefined ? { defaultTabStop } : {}),
+    ...(footnotePr ? { footnotePr } : {}),
+    ...(endnotePr ? { endnotePr } : {}),
     ...(clrSchemeMapping !== undefined ? { clrSchemeMapping } : {}),
     ...(unmodelled.length > 0 ? { unmodelledSettingsChildren: unmodelled } : {}),
   };
@@ -86,6 +97,9 @@ const MODELLED_SETTINGS_CHILD_NAMES = new Set<string>([
   "zoom",
   "compat",
   "themeFontLang",
+  "defaultTabStop",
+  "footnotePr",
+  "endnotePr",
   "clrSchemeMapping",
 ]);
 
@@ -130,6 +144,83 @@ function readRootCompatFlags(
   return flags;
 }
 
+function readDefaultTabStop(
+  settingsElement: XmlElementNode,
+): number | undefined {
+  const element = findChildElementOptional(settingsElement, "defaultTabStop");
+  if (!element) return undefined;
+  const rawValue = element.attributes["w:val"] ?? element.attributes.val;
+  if (!rawValue) return undefined;
+  const parsed = Number.parseInt(rawValue, 10);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function readFootnoteLikeProperties(
+  element: XmlElementNode | undefined,
+): FootnoteProperties | undefined {
+  if (!element) return undefined;
+
+  const result: FootnoteProperties = {};
+  for (const child of element.children) {
+    if (child.type !== "element") continue;
+    const name = localName(child.name);
+    const val = child.attributes["w:val"] ?? child.attributes.val;
+
+    if (name === "pos") {
+      if (
+        val === "pageBottom" ||
+        val === "beneathText" ||
+        val === "sectEnd" ||
+        val === "docEnd"
+      ) {
+        result.pos = val;
+      }
+      continue;
+    }
+
+    if (name === "numFmt") {
+      if (
+        val === "decimal" ||
+        val === "upperRoman" ||
+        val === "lowerRoman" ||
+        val === "upperLetter" ||
+        val === "lowerLetter" ||
+        val === "ordinal" ||
+        val === "cardinalText" ||
+        val === "ordinalText" ||
+        val === "hex" ||
+        val === "chicago" ||
+        val === "bullet" ||
+        val === "ideographDigital" ||
+        val === "japaneseCounting" ||
+        val === "arabicAbjad" ||
+        val === "arabicAlpha" ||
+        val === "none"
+      ) {
+        result.numFmt = val;
+      }
+      continue;
+    }
+
+    if (name === "numStart") {
+      const parsed = Number.parseInt(val ?? "", 10);
+      if (Number.isFinite(parsed)) {
+        result.numStart = Math.max(1, parsed);
+      }
+      continue;
+    }
+
+    if (
+      name === "numRestart" &&
+      (val === "continuous" || val === "eachSect" || val === "eachPage")
+    ) {
+      result.numRestart = val;
+    }
+  }
+
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
 interface CompatPartition {
   compatSettings: CompatSetting[];
   compatFlags: Record<string, boolean>;
@@ -218,4 +309,3 @@ function readZoomLevel(
 
   return { zoomLevel: parsed };
 }
-

package/src/model/canonical-document.ts

@@ -346,14 +346,20 @@ export interface FootnoteDefinition {
  * footnote/endnote entries with `w:type="separator"` and
  * `w:type="continuationSeparator"`.
  *
- * Content is stored as raw inner XML (the run children of the <w:p>) so
- * Lane 3a page-chrome can render the horizontal rule without re-parsing.
+ * The canonical model keeps both the legacy run-only payload and the full
+ * first-paragraph XML. The paragraph form closes round-trip fidelity for
+ * imported separator paragraph properties, while the run form remains for
+ * back-compat with the current note-separator runtime helpers.
  */
 export interface FootnoteSeparators {
   /** Raw XML of the <w:r> children inside the separator paragraph. */
   separatorContent?: string;
+  /** Full XML of the first separator paragraph. */
+  separatorParagraphXml?: string;
   /** Raw XML of the <w:r> children inside the continuationSeparator paragraph. */
   continuationSeparatorContent?: string;
+  /** Full XML of the first continuation-separator paragraph. */
+  continuationSeparatorParagraphXml?: string;
 }
 
 export interface FootnoteCollection {
@@ -399,6 +405,22 @@ export interface CompatSetting {
 export interface DocumentSettings {
   evenAndOddHeaders?: boolean;
   zoomLevel?: "pageWidth" | "onePage" | number;
+  /**
+   * Document-wide default tab stop interval from `<w:defaultTabStop w:val>`.
+   * Value is stored in twips and feeds layout measurement whenever a paragraph
+   * does not declare an explicit next tab stop.
+   */
+  defaultTabStop?: number;
+  /**
+   * Settings-level default footnote configuration from `<w:footnotePr>`.
+   * Section-level `SectionProperties.footnotePr` overrides this when present.
+   */
+  footnotePr?: FootnoteProperties;
+  /**
+   * Settings-level default endnote configuration from `<w:endnotePr>`.
+   * Section-level `SectionProperties.endnotePr` overrides this when present.
+   */
+  endnotePr?: EndnoteProperties;
   /**
    * Ordered list of <w:compatSetting> entries inside <w:compat>. Insertion
    * order is preserved for serializer diff stability.
@@ -606,6 +628,18 @@ export interface ParagraphShading {
   fill?: string;
   color?: string;
   val?: string;
+  /**
+   * Theme shading references (§17.3.5). When `themeFill` is set and `fill`
+   * is absent or `"auto"`, render-time shading resolves through the theme
+   * color resolver. The raw theme attrs remain on the canonical model so
+   * export can round-trip the original `<w:shd>` byte-for-byte.
+   */
+  themeFill?: string;
+  themeFillTint?: string;
+  themeFillShade?: string;
+  themeColor?: string;
+  themeColorTint?: string;
+  themeColorShade?: string;
 }
 
 /** Body of an OOXML `<w:rPr>` (run properties). All fields optional; absence = "not specified at this level". */

package/src/runtime/document-runtime.ts

@@ -23,6 +23,7 @@ import type {
   AddCommentResult,
   AddScopeParams,
   AddScopeResult,
+  ClearHighlightOptions,
   CommentSidebarSnapshot,
   CommentSidebarThreadSnapshot,
   CompatibilityReport,
@@ -159,6 +160,7 @@ import {
   insertScopeMarkers,
   removeScopeMarkers,
 } from "../core/commands/add-scope.ts";
+import { applyFormattingOperationToDocument } from "../core/commands/formatting-commands.ts";
 import { buildCompatibilityReport } from "../validation/compatibility-engine.ts";
 import { mergeCompatibilityReports } from "../validation/compatibility-report.ts";
 import { createEditorSurfaceSnapshot } from "./surface-projection.ts";
@@ -481,6 +483,22 @@ export interface DocumentRuntime {
   rejectChange(changeId: string): void;
   acceptAllChanges(): void;
   rejectAllChanges(): void;
+  /**
+   * Clears the highlight (background color) on a range in the currently
+   * active story. The caller's selection is NOT moved.
+   *
+   * When `options.range` is omitted, the current document selection is used.
+   *
+   * Tracked-changes / suggesting mode is honored: in suggesting mode the
+   * clear is recorded as an `rPrChange` property-change suggestion when the
+   * resolved range is a single bounded text segment, and is reported via
+   * `command_blocked` when the range spans multiple segments.
+   *
+   * When `options.expandToFullHighlight` is `true`, the resolved range is
+   * grown outward before clearing to cover the entire contiguous highlighted
+   * span it touches. Expansion stops at paragraph and table-cell boundaries.
+   */
+  clearHighlight(options?: ClearHighlightOptions): void;
   openStory(target: EditorStoryTarget): boolean;
   closeStory(): void;
   getActiveStory(): EditorStoryTarget;
@@ -3705,6 +3723,143 @@ export function createDocumentRuntime(
         origin: createOrigin("api", clock()),
       });
     },
+    clearHighlight(options) {
+      const resolvedRange = resolveClearHighlightRange(
+        options?.range,
+        state.selection,
+      );
+      if (!resolvedRange) {
+        return;
+      }
+      if (viewState.documentMode === "viewing") {
+        this.emitBlockedCommand("clearHighlight", [{
+          code: "document_viewing_mode",
+          message: "Cannot clear highlight in viewing mode.",
+        }]);
+        return;
+      }
+
+      const surfaceBlocks = getActiveStorySurfaceBlocks();
+      if (!surfaceBlocks) {
+        return;
+      }
+
+      const inputFrom = Math.min(resolvedRange.from, resolvedRange.to);
+      const inputTo = Math.max(resolvedRange.from, resolvedRange.to);
+      let targetFrom = inputFrom;
+      let targetTo = inputTo;
+      if (options?.expandToFullHighlight === true) {
+        const expanded = expandRangeToHighlightExtent(
+          surfaceBlocks,
+          inputFrom,
+          inputTo,
+        );
+        targetFrom = expanded.from;
+        targetTo = expanded.to;
+      }
+      if (targetFrom === targetTo) {
+        return;
+      }
+
+      const activeStoryDocument =
+        activeStory.kind === "main"
+          ? state.document
+          : {
+              ...state.document,
+              content: {
+                type: "doc" as const,
+                children: [...getStoryBlocks(state.document, activeStory)],
+              },
+            };
+      const syntheticSnapshot: RuntimeRenderSnapshot = {
+        ...cachedRenderSnapshot,
+        ...(activeStory.kind === "main" ? {} : { activeStory: MAIN_STORY_TARGET }),
+        selection: {
+          anchor: targetFrom,
+          head: targetTo,
+          isCollapsed: false,
+          activeRange: {
+            kind: "range",
+            from: targetFrom,
+            to: targetTo,
+            assoc: { start: -1, end: 1 },
+          },
+        },
+      };
+
+      const suggesting =
+        getEffectiveDocumentMode(state.selection) === "suggesting";
+      if (suggesting) {
+        if (activeStory.kind !== "main") {
+          this.emitBlockedCommand("clearHighlight", [{
+            code: "suggesting_unsupported",
+            message: `"clearHighlight" is not supported in suggesting mode for this story.`,
+          }]);
+          return;
+        }
+        const segment = findSingleSelectedTextSegment(syntheticSnapshot);
+        if (!segment) {
+          this.emitBlockedCommand("clearHighlight", [{
+            code: "suggesting_unsupported",
+            message: `"clearHighlight" requires one bounded text segment in suggesting mode.`,
+          }]);
+          return;
+        }
+        const beforeXml = buildRunPropertyBeforeXml(segment);
+        const mutation = applyFormattingOperationToDocument(
+          activeStoryDocument,
+          syntheticSnapshot,
+          { type: "set-highlight-color", color: null },
+        );
+        if (!mutation.changed) {
+          return;
+        }
+        const timestamp = clock();
+        const nextDocument = appendPropertyChangeSuggestion(
+          mutation.document,
+          { from: segment.from, to: segment.to },
+          {
+            originalRevisionType: "rPrChange",
+            xmlTag: "rPrChange",
+            beforeXml,
+            semanticKind: "formatting-change",
+            storyTarget: activeStory,
+            authorId: defaultAuthorId ?? undefined,
+          },
+          timestamp,
+        );
+        this.dispatch({
+          type: "document.replace",
+          document: nextDocument,
+          mapping: createEmptyMapping(),
+          origin: createOrigin("api", timestamp),
+        });
+        return;
+      }
+
+      const result = applyFormattingOperationToDocument(
+        activeStoryDocument,
+        syntheticSnapshot,
+        { type: "set-highlight-color", color: null },
+      );
+      if (!result.changed) {
+        return;
+      }
+      const nextDocument =
+        activeStory.kind === "main"
+          ? result.document
+          : replaceStoryBlocks(
+              state.document,
+              activeStory,
+              result.document.content.children,
+            );
+      this.dispatch({
+        type: "document.replace",
+        document: nextDocument,
+        mapping: createEmptyMapping(),
+        origin: createOrigin("api", clock()),
+      });
+    },
     openStory(target) {
       const normalizedTarget =
         target.kind === "header" || target.kind === "footer"
@@ -3815,6 +3970,7 @@ export function createDocumentRuntime(
         collection,
         collectSectionPropertiesInOrder(state.document),
         state.document,
+        state.document.subParts?.settings,
       );
     },
     layout: layoutFacet,
@@ -7468,3 +7624,271 @@ async function upgradeMeasurementProvider(
     // fall through — the empirical backend remains in place
   }
 }
+
+function rangesOverlap(
+  leftFrom: number,
+  leftTo: number,
+  rightFrom: number,
+  rightTo: number,
+): boolean {
+  return leftFrom < rightTo && rightFrom < leftTo;
+}
+
+function resolveClearHighlightRange(
+  inputRange: EditorAnchorProjection | undefined,
+  selection: import("../core/state/editor-state.ts").SelectionSnapshot,
+): { from: number; to: number } | null {
+  if (inputRange !== undefined) {
+    if (inputRange.kind !== "range") return null;
+    return { from: inputRange.from, to: inputRange.to };
+  }
+  const active = selection.activeRange;
+  if (active.kind !== "range") return null;
+  return { from: active.range.from, to: active.range.to };
+}
+
+function expandRangeToHighlightExtent(
+  blocks: readonly SurfaceBlockSnapshot[],
+  inputFrom: number,
+  inputTo: number,
+): { from: number; to: number } {
+  let from = inputFrom;
+  let to = inputTo;
+  forEachParagraphBlock(blocks, (paragraph) => {
+    if (!rangesOverlap(from, to, paragraph.from, paragraph.to)) {
+      return;
+    }
+    const textSegments = paragraph.segments.filter(
+      (segment): segment is Extract<SurfaceInlineSegment, { kind: "text" }> =>
+        segment.kind === "text",
+    );
+    const expanded = expandRangeWithinParagraph(textSegments, inputFrom, inputTo);
+    if (expanded.from < from) from = expanded.from;
+    if (expanded.to > to) to = expanded.to;
+  });
+  return { from, to };
+}
+
+function expandRangeWithinParagraph(
+  segments: Array<Extract<SurfaceInlineSegment, { kind: "text" }>>,
+  inputFrom: number,
+  inputTo: number,
+): { from: number; to: number } {
+  let from = inputFrom;
+  let to = inputTo;
+  let touchedLeftIndex = -1;
+  let touchedRightIndex = -1;
+  for (let i = 0; i < segments.length; i += 1) {
+    const segment = segments[i]!;
+    if (!isHighlightedSegment(segment)) continue;
+    if (rangesOverlap(inputFrom, inputTo, segment.from, segment.to)) {
+      if (touchedLeftIndex === -1) touchedLeftIndex = i;
+      touchedRightIndex = i;
+    }
+  }
+  if (touchedLeftIndex === -1) {
+    return { from, to };
+  }
+  for (let i = touchedLeftIndex; i >= 0; i -= 1) {
+    const segment = segments[i]!;
+    if (!isHighlightedSegment(segment)) break;
+    if (segment.to < from) break;
+    if (segment.from < from) from = segment.from;
+  }
+  for (let i = touchedRightIndex; i < segments.length; i += 1) {
+    const segment = segments[i]!;
+    if (!isHighlightedSegment(segment)) break;
+    if (segment.from > to) break;
+    if (segment.to > to) to = segment.to;
+  }
+  return { from, to };
+}
+
+function isHighlightedSegment(
+  segment: Extract<SurfaceInlineSegment, { kind: "text" }>,
+): boolean {
+  const bg = segment.markAttrs?.backgroundColor;
+  return typeof bg === "string" && bg.length > 0;
+}
+
+function forEachParagraphBlock(
+  blocks: readonly SurfaceBlockSnapshot[],
+  visit: (paragraph: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>) => void,
+): void {
+  for (const block of blocks) {
+    if (block.kind === "paragraph") {
+      visit(block);
+      continue;
+    }
+    if (block.kind === "table") {
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          forEachParagraphBlock(cell.content, visit);
+        }
+      }
+      continue;
+    }
+    if (block.kind === "sdt_block") {
+      forEachParagraphBlock(block.children, visit);
+    }
+  }
+}
+
+function findSingleSelectedTextSegment(
+  snapshot: Pick<RuntimeRenderSnapshot, "surface" | "selection">,
+): Extract<SurfaceInlineSegment, { kind: "text" }> | null {
+  if (
+    !snapshot.surface ||
+    snapshot.selection.activeRange.kind !== "range" ||
+    snapshot.selection.isCollapsed
+  ) {
+    return null;
+  }
+  const selectionFrom = Math.min(snapshot.selection.anchor, snapshot.selection.head);
+  const selectionTo = Math.max(snapshot.selection.anchor, snapshot.selection.head);
+  const segments = collectSelectedTextSegments(
+    snapshot.surface.blocks,
+    selectionFrom,
+    selectionTo,
+  );
+  if (segments.length !== 1) {
+    return null;
+  }
+  const [segment] = segments;
+  if (!segment || segment.from !== selectionFrom || segment.to !== selectionTo) {
+    return null;
+  }
+  return segment;
+}
+
+function collectSelectedTextSegments(
+  blocks: readonly SurfaceBlockSnapshot[],
+  selectionFrom: number,
+  selectionTo: number,
+  output: Array<Extract<SurfaceInlineSegment, { kind: "text" }>> = [],
+): Array<Extract<SurfaceInlineSegment, { kind: "text" }>> {
+  for (const block of blocks) {
+    if (block.kind === "paragraph") {
+      for (const segment of block.segments) {
+        if (
+          segment.kind === "text" &&
+          rangesOverlap(selectionFrom, selectionTo, segment.from, segment.to)
+        ) {
+          output.push(segment);
+        }
+      }
+      continue;
+    }
+    if (block.kind === "table") {
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          collectSelectedTextSegments(cell.content, selectionFrom, selectionTo, output);
+        }
+      }
+      continue;
+    }
+    if (block.kind === "sdt_block") {
+      collectSelectedTextSegments(block.children, selectionFrom, selectionTo, output);
+    }
+  }
+  return output;
+}
+
+function buildRunPropertyBeforeXml(
+  segment: Extract<SurfaceInlineSegment, { kind: "text" }>,
+): string {
+  const parts: string[] = [];
+  const marks = new Set(segment.marks ?? []);
+  if (marks.has("bold")) parts.push("<w:b/>");
+  if (marks.has("italic")) parts.push("<w:i/>");
+  if (marks.has("underline")) parts.push("<w:u w:val=\"single\"/>");
+  if (marks.has("strikethrough")) parts.push("<w:strike/>");
+  if (marks.has("superscript")) parts.push("<w:vertAlign w:val=\"superscript\"/>");
+  if (marks.has("subscript")) parts.push("<w:vertAlign w:val=\"subscript\"/>");
+  if (segment.markAttrs?.fontFamily) {
+    parts.push(
+      `<w:rFonts w:ascii="${escapeAttributeXml(segment.markAttrs.fontFamily)}" w:hAnsi="${escapeAttributeXml(segment.markAttrs.fontFamily)}"/>`,
+    );
+  }
+  if (segment.markAttrs?.fontSize !== undefined) {
+    parts.push(`<w:sz w:val="${segment.markAttrs.fontSize}"/>`);
+  }
+  if (segment.markAttrs?.textColor) {
+    parts.push(`<w:color w:val="${escapeAttributeXml(segment.markAttrs.textColor)}"/>`);
+  }
+  if (segment.markAttrs?.backgroundColor) {
+    parts.push(
+      `<w:shd w:val="clear" w:color="auto" w:fill="${escapeAttributeXml(segment.markAttrs.backgroundColor)}"/>`,
+    );
+  }
+  return `<w:rPr>${parts.join("")}</w:rPr>`;
+}
+
+function escapeAttributeXml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+function appendPropertyChangeSuggestion(
+  document: CanonicalDocumentEnvelope,
+  anchor: { from: number; to: number },
+  input: {
+    originalRevisionType: "rPrChange" | "pPrChange";
+    xmlTag: "rPrChange" | "pPrChange";
+    beforeXml: string;
+    semanticKind: "formatting-change" | "paragraph-property-change";
+    storyTarget: EditorStoryTarget;
+    authorId?: string;
+  },
+  timestamp: string,
+): CanonicalDocumentEnvelope {
+  const existing = document.review.revisions;
+  const changeId = createRuntimeSuggestionChangeId(existing, timestamp);
+  const resolvedAuthorId = input.authorId ?? "unknown";
+  return {
+    ...document,
+    review: {
+      ...document.review,
+      revisions: {
+        ...existing,
+        [changeId]: {
+          changeId,
+          kind: "property-change",
+          anchor: createRangeAnchor(anchor.from, anchor.to, { start: 1, end: -1 }),
+          authorId: resolvedAuthorId,
+          createdAt: timestamp,
+          warningIds: [],
+          metadata: {
+            source: "runtime",
+            storyTarget: input.storyTarget,
+            suggestionId: changeId,
+            semanticKind: input.semanticKind,
+            originalRevisionType: input.originalRevisionType,
+            propertyChangeData: {
+              xmlTag: input.xmlTag,
+              beforeXml: input.beforeXml,
+            },
+          },
+          status: "open",
+        },
+      },
+    },
+  };
+}
+
+function createRuntimeSuggestionChangeId(
+  existing: CanonicalDocumentEnvelope["review"]["revisions"],
+  timestamp: string,
+): string {
+  const base = `change-${timestamp.replace(/[^0-9]/gu, "")}`;
+  let counter = Object.keys(existing).length + 1;
+  let candidate = `${base}-p${counter}`;
+  while (existing[candidate]) {
+    counter += 1;
+    candidate = `${base}-p${counter}`;
+  }
+  return candidate;
+}