docxmlater 11.0.10 → 12.1.0

package/src/processors/SelectiveRevisionAcceptor.ts

@@ -15,10 +15,11 @@
 import type { Document } from '../core/Document.js';
 import type { Paragraph, ParagraphContent } from '../elements/Paragraph.js';
 import { Revision, RevisionType } from '../elements/Revision.js';
-import type { Run } from '../elements/Run.js';
+import type { Run, RunFormatting } from '../elements/Run.js';
 import { isRunContent, isHyperlinkContent } from '../elements/RevisionContent.js';
 import { ChangeCategory } from './ChangelogGenerator.js';
 import { SelectionCriteria } from './RevisionAwareProcessor.js';
+import { mergeParagraphsWithDeletedMarks } from './InMemoryRevisionAcceptor.js';
 
 /**
  * Result of selective revision acceptance.
@@ -62,9 +63,23 @@ export class SelectiveRevisionAcceptor {
     const hasFullApi = typeof (doc as any).getAllParagraphs === 'function';
 
     if (hasFullApi) {
+      const acceptedMarkDeletions: Paragraph[] = [];
       this.walkAllParagraphs(doc, (paragraph) => {
-        this.processSelectiveParagraph(paragraph, criteria, 'accept', accepted, remaining);
+        this.processSelectiveParagraph(
+          paragraph,
+          criteria,
+          'accept',
+          accepted,
+          remaining,
+          acceptedMarkDeletions
+        );
       });
+      // Accepted paragraph-mark deletions combine the paragraph with its
+      // following sibling (ECMA-376 §17.13.5.15) — same merge the all-or-
+      // nothing acceptor performs.
+      if (acceptedMarkDeletions.length > 0) {
+        mergeParagraphsWithDeletedMarks(doc, new Set(acceptedMarkDeletions));
+      }
     } else {
       // Fallback: Filter revisions from RevisionManager only (for backward compatibility)
       const revisionManager = doc.getRevisionManager();
@@ -257,7 +272,8 @@ export class SelectiveRevisionAcceptor {
     criteria: SelectionCriteria,
     action: 'accept' | 'reject',
     processedIds: string[],
-    remainingIds: string[]
+    remainingIds: string[],
+    acceptedMarkDeletions?: Paragraph[]
   ): void {
     const content = paragraph.getContent();
     const newContent: ParagraphContent[] = [];
@@ -267,15 +283,18 @@ export class SelectiveRevisionAcceptor {
         const revisionId = item.getId().toString();
 
         if (this.matchesCriteria(item, criteria)) {
-          // This revision matches the criteria - process it
-          processedIds.push(revisionId);
-
           if (action === 'accept') {
             // Accept: Transform based on revision type
+            processedIds.push(revisionId);
             this.acceptRevisionItem(item, newContent);
-          } else {
+          } else if (this.rejectRevisionItem(item, newContent, paragraph)) {
             // Reject: Transform opposite of accept
-            this.rejectRevisionItem(item, newContent);
+            processedIds.push(revisionId);
+          } else {
+            // The revision was kept in place (its previous-property
+            // snapshot could not be restored), so report it as remaining
+            // rather than rejected — it must stay in the RevisionManager.
+            remainingIds.push(revisionId);
           }
         } else {
           // This revision doesn't match - keep it
@@ -291,13 +310,18 @@ export class SelectiveRevisionAcceptor {
     // Replace paragraph content with the transformed content
     paragraph.setContent(newContent);
 
-    // Handle paragraph mark revision markers (w:del/w:ins in w:pPr/w:rPr)
-    // Both accept and reject clear the marker — these are metadata-only markers (no content),
-    // so there is no content to add or remove, only the marker itself to clear.
+    // Handle paragraph mark revision markers (w:del/w:ins in w:pPr/w:rPr).
+    // Rejecting a mark deletion just restores the mark (clear the marker);
+    // ACCEPTING one means the paragraph's contents combine with the following
+    // paragraph (ECMA-376 §17.13.5.15), so the paragraph is recorded for the
+    // post-walk merge pass in addition to clearing the marker.
     const formatting = paragraph.getFormatting();
     if (formatting.paragraphMarkDeletion) {
       const del = formatting.paragraphMarkDeletion;
       if (this.matchesMarkerCriteria(del, criteria)) {
+        if (action === 'accept') {
+          acceptedMarkDeletions?.push(paragraph);
+        }
         paragraph.clearParagraphMarkDeletion();
         processedIds.push(del.id.toString());
       } else {
@@ -415,8 +439,17 @@ export class SelectiveRevisionAcceptor {
    * Reject a single revision item (opposite of accept).
    * - Rejecting an insertion removes the content
    * - Rejecting a deletion keeps the content (unwraps it)
+   * - Rejecting a run/paragraph property change restores the previous
+   *   properties snapshot (ECMA-376 §17.13.5.30/§17.13.5.31)
+   *
+   * @returns true if the revision was rejected, false if it was kept in
+   *   place because its previous-property snapshot could not be restored
    */
-  private static rejectRevisionItem(revision: Revision, newContent: ParagraphContent[]): void {
+  private static rejectRevisionItem(
+    revision: Revision,
+    newContent: ParagraphContent[],
+    paragraph: Paragraph
+  ): boolean {
     const revisionType = revision.getType();
     const childContent = revision.getContent();
 
@@ -424,7 +457,7 @@ export class SelectiveRevisionAcceptor {
       case 'insert':
       case 'moveTo':
         // Reject insertion: Remove the inserted content entirely
-        break;
+        return true;
 
       case 'delete':
       case 'moveFrom':
@@ -436,19 +469,46 @@ export class SelectiveRevisionAcceptor {
             newContent.push(child);
           }
         }
-        break;
+        return true;
+
+      case 'runPropertiesChange': {
+        const previous = revision.getPreviousProperties();
+        if (!previous) {
+          // No snapshot to restore from — keep the tracked change so the
+          // prior formatting is not silently lost.
+          newContent.push(revision);
+          return false;
+        }
+        for (const child of childContent) {
+          if (isRunContent(child)) {
+            const run = child as Run;
+            // w:rPrChange carries the complete pre-change run properties,
+            // so rejecting replaces (not merges) the run's formatting.
+            // Run.formatting is private; written directly the same way
+            // DocumentParser populates parsed properties.
+            (run as unknown as { formatting: RunFormatting }).formatting = {
+              ...(previous as RunFormatting),
+            };
+            newContent.push(run);
+          } else if (isHyperlinkContent(child)) {
+            newContent.push(child);
+          }
+        }
+        return true;
+      }
 
-      case 'runPropertiesChange':
-      case 'paragraphPropertiesChange':
-      case 'tablePropertiesChange':
-      case 'tableExceptionPropertiesChange':
-      case 'tableRowPropertiesChange':
-      case 'tableCellPropertiesChange':
-      case 'sectionPropertiesChange':
-      case 'numberingChange':
-        // Rejecting property changes: Would need to restore old properties
-        // For now, just keep content without the change metadata
-        // (Full implementation would restore previousProperties)
+      case 'paragraphPropertiesChange': {
+        const previous = revision.getPreviousProperties();
+        if (!previous) {
+          newContent.push(revision);
+          return false;
+        }
+        // The snapshot uses the same key names as ParagraphFormatting
+        // (see Revision.PROPERTY_KEY_TO_ELEMENT), so the recorded values
+        // are written back onto the containing paragraph. Only recorded
+        // keys are touched: internal bookkeeping fields (revision markers,
+        // paraId) are not part of a w:pPrChange snapshot.
+        Object.assign(paragraph.formatting, previous);
         for (const child of childContent) {
           if (isRunContent(child)) {
             newContent.push(child as Run);
@@ -456,11 +516,26 @@ export class SelectiveRevisionAcceptor {
             newContent.push(child);
           }
         }
-        break;
+        return true;
+      }
+
+      case 'tablePropertiesChange':
+      case 'tableExceptionPropertiesChange':
+      case 'tableRowPropertiesChange':
+      case 'tableCellPropertiesChange':
+      case 'sectionPropertiesChange':
+      case 'numberingChange':
+        // The element these snapshots belong to (table/row/cell/section/
+        // numbering definition) is not reachable from paragraph content,
+        // so the previous properties cannot be restored here. Keep the
+        // revision in place rather than discarding the snapshot.
+        newContent.push(revision);
+        return false;
 
       default:
         // Unknown type - keep the revision as-is for safety
         newContent.push(revision);
+        return true;
     }
   }
 
@@ -477,8 +552,69 @@ export class SelectiveRevisionAcceptor {
     criteria: SelectionCriteria,
     action: 'accept' | 'reject'
   ): SelectiveAcceptResult {
-    // Preview is the same as the actual operation but without side effects
-    return action === 'accept' ? this.accept(doc, criteria) : this.reject(doc, criteria);
+    const processed: string[] = [];
+    const remaining: string[] = [];
+
+    // Delegating to accept()/reject() would mutate paragraph content and
+    // splice revisions out of the RevisionManager, so preview classifies
+    // with the same traversal and criteria but never transforms anything.
+    const hasFullApi = typeof (doc as any).getAllParagraphs === 'function';
+
+    if (hasFullApi) {
+      this.walkAllParagraphs(doc, (paragraph) => {
+        for (const item of paragraph.getContent()) {
+          if (item instanceof Revision) {
+            if (this.matchesCriteria(item, criteria)) {
+              processed.push(item.getId().toString());
+            } else {
+              remaining.push(item.getId().toString());
+            }
+          }
+        }
+
+        const formatting = paragraph.getFormatting();
+        if (formatting.paragraphMarkDeletion) {
+          const del = formatting.paragraphMarkDeletion;
+          if (this.matchesMarkerCriteria(del, criteria)) {
+            processed.push(del.id.toString());
+          } else {
+            remaining.push(del.id.toString());
+          }
+        }
+        if (formatting.paragraphMarkInsertion) {
+          const ins = formatting.paragraphMarkInsertion;
+          if (this.matchesMarkerCriteria(ins, criteria)) {
+            processed.push(ins.id.toString());
+          } else {
+            remaining.push(ins.id.toString());
+          }
+        }
+      });
+    } else {
+      // Fallback: Filter revisions from RevisionManager only (for backward compatibility)
+      const revisionManager = doc.getRevisionManager();
+      if (revisionManager) {
+        for (const rev of revisionManager.getAllRevisions()) {
+          if (this.matchesCriteria(rev, criteria)) {
+            processed.push(rev.getId().toString());
+          } else {
+            remaining.push(rev.getId().toString());
+          }
+        }
+      }
+    }
+
+    return {
+      accepted: action === 'accept' ? processed : [],
+      rejected: action === 'reject' ? processed : [],
+      remaining,
+      summary: {
+        totalProcessed: processed.length + remaining.length,
+        acceptedCount: action === 'accept' ? processed.length : 0,
+        rejectedCount: action === 'reject' ? processed.length : 0,
+        remainingCount: remaining.length,
+      },
+    };
   }
 
   /**

package/src/processors/acceptRevisions.ts

@@ -5,16 +5,19 @@ import { RevisionWalker } from './RevisionWalker.js';
 /**
  * Markers covered: w:ins, w:del, w:moveFrom, w:moveTo,
  * w:rPrChange, w:pPrChange, w:tblPrChange, w:tblPrExChange,
- * w:trPrChange, w:tcPrChange, w:sectPrChange, w:numberingChange,
- * w:cellIns, w:cellDel, w:cellMerge, and any *RangeStart/End markers.
+ * w:trPrChange, w:tcPrChange, w:sectPrChange, w:tblGridChange,
+ * w:numberingChange, w:cellIns, w:cellDel, w:cellMerge, and any
+ * *RangeStart/End markers.
  */
 const REVISION_MARKER_PATTERN =
-  /<w:(?:ins|del|moveFrom|moveTo|rPrChange|pPrChange|tblPrChange|tblPrExChange|trPrChange|tcPrChange|sectPrChange|numberingChange|cellIns|cellDel|cellMerge|moveFromRangeStart|moveFromRangeEnd|moveToRangeStart|moveToRangeEnd|customXmlInsRangeStart|customXmlInsRangeEnd|customXmlDelRangeStart|customXmlDelRangeEnd|customXmlMoveFromRangeStart|customXmlMoveFromRangeEnd|customXmlMoveToRangeStart|customXmlMoveToRangeEnd)\b/;
+  /<w:(?:ins|del|moveFrom|moveTo|rPrChange|pPrChange|tblPrChange|tblPrExChange|trPrChange|tcPrChange|sectPrChange|tblGridChange|numberingChange|cellIns|cellDel|cellMerge|moveFromRangeStart|moveFromRangeEnd|moveToRangeStart|moveToRangeEnd|customXmlInsRangeStart|customXmlInsRangeEnd|customXmlDelRangeStart|customXmlDelRangeEnd|customXmlMoveFromRangeStart|customXmlMoveFromRangeEnd|customXmlMoveToRangeStart|customXmlMoveToRangeEnd)\b/;
 
 /**
- * Accepts all tracked changes in a Word document per Microsoft's OpenXML SDK pattern
+ * Applies tracked changes in a Word document per Microsoft's OpenXML SDK
+ * pattern, in either direction (see `mode`).
  *
- * This implementation uses DOM-based tree walking for reliability:
+ * This implementation uses DOM-based tree walking for reliability. In 'accept'
+ * mode (the post-edit document):
  * 1. Insertions (<w:ins>): Keep content, remove wrapper tags
  * 2. Deletions (<w:del>): Remove entirely (content and tags)
  * 3. Move From (<w:moveFrom>): Remove entirely (source of move)
@@ -22,17 +25,27 @@ const REVISION_MARKER_PATTERN =
  * 5. Property changes: Remove all *Change elements
  * 6. Range markers: Remove all boundary markers
  *
+ * In 'reject' mode every content decision is inverted and property changes
+ * restore the previous formatting (see RevisionWalker).
+ *
  * Also cleans up metadata in people.xml, settings.xml, and core.xml
  *
  * @see https://learn.microsoft.com/en-us/office/open-xml/how-to-accept-all-revisions
  */
-class RevisionAcceptor {
+class RevisionProcessor {
   private zipHandler: ZipHandler;
   /** Feature flag for DOM-based processing (default: true) */
   private useDomBasedProcessing = true;
+  /**
+   * Processing direction. 'accept' yields the post-edit document; 'reject'
+   * reverts to the original pre-edit document (the exact inverse). Reject is
+   * DOM-only — the regex fallback cannot restore previous formatting.
+   */
+  private mode: 'accept' | 'reject';
 
-  constructor(zipHandler: ZipHandler) {
+  constructor(zipHandler: ZipHandler, mode: 'accept' | 'reject' = 'accept') {
     this.zipHandler = zipHandler;
+    this.mode = mode;
   }
 
   /**
@@ -43,9 +56,10 @@ class RevisionAcceptor {
   }
 
   /**
-   * Main method to accept all revisions in the document
+   * Main entry point: apply every tracked change in the document in the
+   * configured direction (accept or reject).
    */
-  public async acceptAllRevisions(): Promise<void> {
+  public async process(): Promise<void> {
     // Process document.xml
     await this.processDocumentPart('word/document.xml');
 
@@ -91,11 +105,13 @@ class RevisionAcceptor {
     // byte-for-byte passthrough preservation in downstream consumers
     // (e.g., comments.xml round-trip with no tracked changes inside).
     const xml = this.zipHandler.getFileAsString(partPath);
-    if (!xml || !RevisionAcceptor.containsRevisionMarkup(xml)) {
+    if (!xml || !RevisionProcessor.containsRevisionMarkup(xml)) {
       return;
     }
 
-    if (this.useDomBasedProcessing) {
+    // Reject must restore previous formatting from *Change snapshots, which the
+    // regex fallback cannot do — always take the DOM path when rejecting.
+    if (this.useDomBasedProcessing || this.mode === 'reject') {
       return this.processDocumentPartDOM(partPath);
     }
     return this.processDocumentPartRegex(partPath);
@@ -126,14 +142,22 @@ class RevisionAcceptor {
 
     // Step 2: Process revisions using DOM walker
     const processed = RevisionWalker.processTree(parsed, {
+      mode: this.mode,
       acceptInsertions: true,
       acceptDeletions: true,
       acceptMoves: true,
       acceptPropertyChanges: true,
     });
 
-    // Step 3: Handle image relationship ID remapping
-    this.remapImageRelationshipsInTree(processed);
+    // Step 3: Handle image relationship ID remapping.
+    // Only relevant when accepting: unwrapping an inserted image can surface a
+    // relationship ID that Word reused across tracked-change contexts, so a
+    // fresh unique ID is assigned. Rejecting discards insertions and restores
+    // the original content, whose relationship IDs are already unique, so
+    // remapping would needlessly rewrite valid references.
+    if (this.mode === 'accept') {
+      this.remapImageRelationshipsInTree(processed);
+    }
 
     // Step 4: Convert back to XML
     const outputXml =
@@ -768,8 +792,34 @@ class RevisionAcceptor {
  * Convenience function to accept all revisions in a document
  */
 export async function acceptAllRevisions(zipHandler: ZipHandler): Promise<void> {
-  const acceptor = new RevisionAcceptor(zipHandler);
-  await acceptor.acceptAllRevisions();
+  const acceptor = new RevisionProcessor(zipHandler);
+  await acceptor.process();
+}
+
+/**
+ * Convenience function to reject all revisions in a document, reverting it to
+ * its original pre-edit state (the exact inverse of {@link acceptAllRevisions}):
+ *
+ * 1. Insertions (`w:ins`): removed — inserted content is discarded
+ * 2. Deletions (`w:del`): unwrapped and `w:delText` restored to `w:t` — deleted
+ *    content reappears
+ * 3. MoveFrom (`w:moveFrom`): unwrapped — the original source content is restored
+ * 4. MoveTo (`w:moveTo`): removed — the moved-to destination is discarded
+ * 5. Property changes (`w:rPrChange`, `w:pPrChange`, ...): previous formatting
+ *    stored inside the change is restored, then the marker is removed
+ * 6. Inserted rows/tables are removed; deleted rows/tables are kept
+ * 7. Range markers are removed and revision metadata is cleaned up
+ *
+ * Limitations (shared with {@link acceptAllRevisions}): cell-level markers
+ * (`w:cellIns`/`w:cellDel`/`w:cellMerge`) are left in place, and the legacy
+ * `w:numberingChange` is dropped rather than reverted (it embeds no recoverable
+ * previous value).
+ *
+ * @param zipHandler - The ZipHandler containing the DOCX package
+ */
+export async function rejectAllRevisions(zipHandler: ZipHandler): Promise<void> {
+  const rejector = new RevisionProcessor(zipHandler, 'reject');
+  await rejector.process();
 }
 
 /**
@@ -786,6 +836,6 @@ export async function acceptAllRevisions(zipHandler: ZipHandler): Promise<void>
  * @param zipHandler - The ZipHandler containing the DOCX package
  */
 export function cleanupRevisionMetadata(zipHandler: ZipHandler): void {
-  const acceptor = new RevisionAcceptor(zipHandler);
-  acceptor.cleanupMetadata();
+  const processor = new RevisionProcessor(zipHandler);
+  processor.cleanupMetadata();
 }

package/src/processors/cnfStyleDecoder.ts

@@ -78,25 +78,31 @@ const BIT_POSITIONS: Record<keyof CnfStyleFlags, number> = {
 
 /**
  * Priority order for conditional formatting resolution
- * More specific conditions (corners) override less specific (edges, banding)
- * Per ECMA-376, this is the order in which conditionals should be applied
+ *
+ * ECMA-376 §17.7.6.6 applies conditional formats in sequence (banding, then
+ * first/last row, first/last column, then corners top-left through
+ * bottom-right) with subsequent formats overriding earlier ones. First-match
+ * consumers need the opposite: the last-applied (winning) member of each
+ * group listed first, so when two conditionals in the same group co-apply
+ * (e.g. firstRow + lastRow in a single-row table) resolution picks the one
+ * Word actually renders.
  */
 export const CONDITIONAL_PRIORITY_ORDER: (keyof CnfStyleFlags)[] = [
-  // Corner cells (most specific)
-  'nwCell',
-  'neCell',
-  'swCell',
+  // Corner cells (most specific; spec applies nw, ne, sw, se — se wins)
   'seCell',
-  // Edge rows/columns
-  'firstRow',
+  'swCell',
+  'neCell',
+  'nwCell',
+  // Edge rows/columns (within each pair, last is applied after first)
   'lastRow',
-  'firstCol',
+  'firstRow',
   'lastCol',
-  // Banding (least specific)
-  'band1Horz',
+  'firstCol',
+  // Banding (least specific; even banding is applied after odd)
   'band2Horz',
-  'band1Vert',
+  'band1Horz',
   'band2Vert',
+  'band1Vert',
 ];
 
 /**

package/src/processors/stripTrackedChanges.ts

@@ -67,19 +67,30 @@ class TrackedChangesStripper {
     // STEP 2: Process insertions - keep content, remove wrapper
     content = this.processInsertions(content);
 
-    // STEP 3: Process deletions - remove entirely
+    // STEP 3: Remove rows whose w:trPr carries a row-deletion marker
+    // (self-closing <w:del/> per ECMA-376 §17.13.5.14 marks the ENTIRE
+    // row as deleted). Must run before the marker itself is stripped in
+    // STEP 4, otherwise the row would silently survive as un-deleted.
+    content = this.removeDeletedRows(content);
+
+    // STEP 4: Remove self-closing revision markers (paragraph-mark
+    // deletions in w:pPr/w:rPr per ECMA-376 §17.13.5.15, etc.). Must run
+    // BEFORE the block-removal steps: their [^>]* also matches the
+    // trailing '/' of `<w:del .../>`, which would turn the marker into an
+    // opening tag and swallow everything up to the next closing tag,
+    // corrupting the part.
+    content = this.removeSelfClosingRevisionTags(content);
+
+    // STEP 5: Process deletions - remove entirely
     content = this.processDeletions(content);
 
-    // STEP 4: Process move operations
+    // STEP 6: Process move operations
     content = this.processMoveFrom(content);
     content = this.processMoveTo(content);
 
-    // STEP 5: Remove all property change tracking elements
+    // STEP 7: Remove all property change tracking elements
     content = this.removePropertyChanges(content);
 
-    // STEP 6: Remove any remaining self-closing revision tags
-    content = this.removeSelfClosingRevisionTags(content);
-
     // Update the file in the zip
     this.zipHandler.updateFile(partPath, content);
   }
@@ -160,6 +171,30 @@ class TrackedChangesStripper {
     return result;
   }
 
+  /**
+   * Remove entire <w:tr> rows marked as tracked deletions.
+   *
+   * Per ECMA-376 Part 1 §17.13.5.14, a self-closing `<w:del/>` inside
+   * `<w:trPr>` marks the whole row as deleted — stripping just the marker
+   * would resurrect the row instead of removing it. Mirrors the row-level
+   * pass in acceptRevisions.ts: the negative lookaheads keep the match
+   * anchored to a single row (it cannot slip past a cell boundary or a
+   * nested-table row and latch onto a later row's trPr-with-del).
+   */
+  private removeDeletedRows(xml: string): string {
+    const rowDelPattern =
+      /<w:tr\b[^>]*>(?:(?!<w:tc\b|<w:tr\b|<\/w:tr>)[\s\S])*?<w:trPr\b(?:\s[^>]*)?>(?:(?!<\/w:trPr>)[\s\S])*?<w:del\b[^>]*\/>(?:(?!<\/w:trPr>)[\s\S])*?<\/w:trPr>(?:(?!<w:tr\b|<\/w:tr>)[\s\S])*?<\/w:tr>/g;
+
+    let result = xml;
+    let previousLength = 0;
+    while (result.length !== previousLength) {
+      previousLength = result.length;
+      result = result.replace(rowDelPattern, '');
+    }
+
+    return result;
+  }
+
   /**
    * Process <w:del> elements - remove entire element
    * Uses iterative replacement to handle nested deletions
@@ -241,13 +276,15 @@ class TrackedChangesStripper {
 
   /**
    * Remove self-closing revision tags
+   * `\b` (not `\s+`) so attribute-less markers like `<w:del/>` are also
+   * caught while `<w:delText>` is not.
    */
   private removeSelfClosingRevisionTags(xml: string): string {
     const patterns = [
-      /<w:ins\s+[^>]*\/>/g,
-      /<w:del\s+[^>]*\/>/g,
-      /<w:moveFrom\s+[^>]*\/>/g,
-      /<w:moveTo\s+[^>]*\/>/g,
+      /<w:ins\b[^>]*\/>/g,
+      /<w:del\b[^>]*\/>/g,
+      /<w:moveFrom\b[^>]*\/>/g,
+      /<w:moveTo\b[^>]*\/>/g,
     ];
 
     let result = xml;

package/src/utils/deepClone.ts

@@ -10,6 +10,12 @@
  * For simple objects (like formatting options), this is more efficient
  * than JSON.parse(JSON.stringify()) and doesn't lose non-serializable values.
  *
+ * Cyclic and shared references are handled via an internal seen-cache: an
+ * object encountered more than once during a single clone is cloned exactly
+ * once, so circular graphs cannot overflow the stack and shared sub-objects
+ * (including shared Date and RegExp instances) retain a single shared identity
+ * in the result.
+ *
  * @param obj - Object to clone
  * @returns Deep cloned copy of the object
  *
@@ -23,21 +29,50 @@
  * ```
  */
 export function deepClone<T>(obj: T): T {
+  // Map of already-cloned source objects to their clones, scoped to this call.
+  // Guards against infinite recursion on cyclic input and preserves the
+  // identity of references shared by multiple parents within the same graph.
+  return cloneInternal(obj, new WeakMap<object, unknown>());
+}
+
+function cloneInternal<T>(obj: T, seen: WeakMap<object, unknown>): T {
   // Handle primitive types and null
   if (obj === null || typeof obj !== 'object') {
     return obj;
   }
 
-  // Handle Date
+  // Return the existing clone for any object already seen in this call. Placed
+  // before the Date/RegExp branches so a single Date/RegExp instance shared by
+  // multiple nodes resolves to one shared clone (the JSDoc shared-identity
+  // guarantee), not a fresh copy per reference.
+  const existing = seen.get(obj as object);
+  if (existing !== undefined) {
+    return existing as T;
+  }
+
+  // Handle Date (immutable value copy; cannot form a cycle). Registered in
+  // `seen` so repeat references to the same instance share this clone.
   if (obj instanceof Date) {
-    return new Date(obj.getTime()) as T;
+    const dateCopy = new Date(obj.getTime());
+    seen.set(obj as object, dateCopy);
+    return dateCopy as T;
+  }
+
+  // Handle RegExp (immutable value copy; cannot form a cycle). Registered in
+  // `seen` so repeat references to the same instance share this clone.
+  if (obj instanceof RegExp) {
+    const regexpCopy = new RegExp(obj.source, obj.flags);
+    seen.set(obj as object, regexpCopy);
+    return regexpCopy as T;
   }
 
   // Handle Array
   if (Array.isArray(obj)) {
     const arrCopy: unknown[] = [];
+    // Register before recursing so self/back references resolve to this clone.
+    seen.set(obj as object, arrCopy);
     for (let i = 0; i < obj.length; i++) {
-      arrCopy[i] = deepClone(obj[i]);
+      arrCopy[i] = cloneInternal(obj[i], seen);
     }
     return arrCopy as T;
   }
@@ -45,8 +80,9 @@ export function deepClone<T>(obj: T): T {
   // Handle Map
   if (obj instanceof Map) {
     const mapCopy = new Map();
+    seen.set(obj, mapCopy);
     obj.forEach((value, key) => {
-      mapCopy.set(deepClone(key), deepClone(value));
+      mapCopy.set(cloneInternal(key, seen), cloneInternal(value, seen));
     });
     return mapCopy as T;
   }
@@ -54,23 +90,21 @@ export function deepClone<T>(obj: T): T {
   // Handle Set
   if (obj instanceof Set) {
     const setCopy = new Set();
+    seen.set(obj, setCopy);
     obj.forEach((value) => {
-      setCopy.add(deepClone(value));
+      setCopy.add(cloneInternal(value, seen));
     });
     return setCopy as T;
   }
 
-  // Handle RegExp
-  if (obj instanceof RegExp) {
-    return new RegExp(obj.source, obj.flags) as T;
-  }
-
   // Handle plain objects
   const objCopy = Object.create(Object.getPrototypeOf(obj)) as Record<string, unknown>;
-  for (const key in obj) {
-    if (obj.hasOwnProperty(key)) {
-      objCopy[key] = deepClone((obj as Record<string, unknown>)[key]);
-    }
+  seen.set(obj as object, objCopy);
+  // Object.keys avoids the prototype-builtins shadowing risk of
+  // obj.hasOwnProperty(key) (matches sibling deepEqual.ts) and yields the same
+  // own-enumerable string keys the previous for..in + hasOwnProperty loop did.
+  for (const key of Object.keys(obj as object)) {
+    objCopy[key] = cloneInternal((obj as Record<string, unknown>)[key], seen);
   }
 
   return objCopy as T;