docxmlater 10.4.0 → 11.0.4

package/dist/esm/core/RelationshipManager.js

@@ -0,0 +1,202 @@
+import { Relationship, RelationshipType } from './Relationship.js';
+import { XMLParser } from '../xml/XMLParser.js';
+import { sanitizeHyperlinkUrl } from '../utils/validation.js';
+import { InvalidDocxError, CorruptedArchiveError } from '../zip/errors.js';
+export class RelationshipManager {
+    relationships;
+    nextId;
+    constructor() {
+        this.relationships = new Map();
+        this.nextId = 1;
+    }
+    addRelationship(relationship) {
+        this.relationships.set(relationship.getId(), relationship);
+        const idMatch = /^rId(\d+)$/.exec(relationship.getId());
+        if (idMatch?.[1]) {
+            const idNum = parseInt(idMatch[1], 10);
+            if (idNum >= this.nextId) {
+                this.nextId = idNum + 1;
+            }
+        }
+        return relationship;
+    }
+    getRelationship(id) {
+        return this.relationships.get(id);
+    }
+    getAllRelationships() {
+        return Array.from(this.relationships.values());
+    }
+    getRelationshipsByType(type) {
+        return this.getAllRelationships().filter((rel) => rel.getType() === type);
+    }
+    hasRelationship(id) {
+        return this.relationships.has(id);
+    }
+    removeRelationship(id) {
+        return this.relationships.delete(id);
+    }
+    getCount() {
+        return this.relationships.size;
+    }
+    clear() {
+        this.relationships.clear();
+        this.nextId = 1;
+        return this;
+    }
+    generateId() {
+        return `rId${this.nextId++}`;
+    }
+    addStyles() {
+        const id = this.generateId();
+        return this.addRelationship(Relationship.createStyles(id));
+    }
+    addNumbering() {
+        const id = this.generateId();
+        return this.addRelationship(Relationship.createNumbering(id));
+    }
+    addFontTable() {
+        const id = this.generateId();
+        return this.addRelationship(Relationship.createFontTable(id));
+    }
+    addSettings() {
+        const id = this.generateId();
+        return this.addRelationship(Relationship.createSettings(id));
+    }
+    addWebSettings() {
+        const id = this.generateId();
+        return this.addRelationship(Relationship.createWebSettings(id));
+    }
+    addTheme() {
+        const id = this.generateId();
+        return this.addRelationship(Relationship.createTheme(id));
+    }
+    addImage(target) {
+        const id = this.generateId();
+        return this.addRelationship(Relationship.createImage(id, target));
+    }
+    addHeader(target) {
+        const id = this.generateId();
+        return this.addRelationship(Relationship.createHeader(id, target));
+    }
+    addFooter(target) {
+        const id = this.generateId();
+        return this.addRelationship(Relationship.createFooter(id, target));
+    }
+    addHyperlink(url) {
+        const id = this.generateId();
+        return this.addRelationship(Relationship.createHyperlink(id, url));
+    }
+    updateHyperlinkTarget(relationshipId, newUrl) {
+        const relationship = this.getRelationship(relationshipId);
+        if (!relationship) {
+            return false;
+        }
+        if (relationship.getType() !== RelationshipType.HYPERLINK) {
+            throw new InvalidDocxError(`Relationship ${relationshipId} is not a hyperlink relationship. ` +
+                `Type is ${relationship.getType()}, expected ${RelationshipType.HYPERLINK}`);
+        }
+        relationship.setTarget(newUrl);
+        return true;
+    }
+    findHyperlinkByTarget(targetUrl) {
+        return this.getAllRelationships().find((rel) => rel.getType() === RelationshipType.HYPERLINK && rel.getTarget() === targetUrl);
+    }
+    getOrCreateHyperlink(url) {
+        const existing = this.findHyperlinkByTarget(url);
+        if (existing) {
+            return existing;
+        }
+        return this.addHyperlink(url);
+    }
+    removeOrphanedHyperlinks(referencedIds) {
+        let removed = 0;
+        const toRemove = [];
+        for (const rel of this.getAllRelationships()) {
+            if (rel.getType() === RelationshipType.HYPERLINK && !referencedIds.has(rel.getId())) {
+                toRemove.push(rel.getId());
+            }
+        }
+        for (const id of toRemove) {
+            if (this.removeRelationship(id)) {
+                removed++;
+            }
+        }
+        return removed;
+    }
+    addComments() {
+        const id = this.generateId();
+        return this.addRelationship(Relationship.createComments(id));
+    }
+    addFootnotes() {
+        const id = this.generateId();
+        return this.addRelationship(Relationship.createFootnotes(id));
+    }
+    addEndnotes() {
+        const id = this.generateId();
+        return this.addRelationship(Relationship.createEndnotes(id));
+    }
+    addPeople() {
+        const id = this.generateId();
+        return this.addRelationship(Relationship.createPeople(id));
+    }
+    generateXml() {
+        const relationships = this.getAllRelationships();
+        let xml = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n';
+        xml += '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">\n';
+        for (const rel of relationships) {
+            xml += rel.toXML() + '\n';
+        }
+        xml += '</Relationships>';
+        return xml;
+    }
+    static createForDocument() {
+        const manager = new RelationshipManager();
+        manager.addStyles();
+        manager.addNumbering();
+        manager.addFontTable();
+        manager.addSettings();
+        manager.addWebSettings();
+        manager.addTheme();
+        return manager;
+    }
+    static create() {
+        return new RelationshipManager();
+    }
+    static fromXml(xml) {
+        const manager = new RelationshipManager();
+        if (xml.length > 10000000) {
+            throw new CorruptedArchiveError('Relationships XML file too large (>10MB). Possible malicious input or corrupted file.');
+        }
+        const relationshipElements = XMLParser.extractElements(xml, 'Relationship');
+        if (relationshipElements.length > 1000) {
+            throw new CorruptedArchiveError('Too many relationships in XML file (>1000). Possible malicious input.');
+        }
+        for (const relationshipElement of relationshipElements) {
+            const id = XMLParser.extractAttribute(relationshipElement, 'Id');
+            const type = XMLParser.extractAttribute(relationshipElement, 'Type');
+            const target = XMLParser.extractAttribute(relationshipElement, 'Target');
+            const targetMode = XMLParser.extractAttribute(relationshipElement, 'TargetMode');
+            if (id && type && target) {
+                const validatedTargetMode = targetMode === 'Internal' || targetMode === 'External' || targetMode === undefined
+                    ? targetMode
+                    : undefined;
+                let sanitizedTarget = target;
+                if (type.endsWith('/hyperlink')) {
+                    const result = sanitizeHyperlinkUrl(target);
+                    if (result) {
+                        sanitizedTarget = result.url;
+                    }
+                }
+                const relationship = Relationship.create({
+                    id,
+                    type,
+                    target: sanitizedTarget,
+                    targetMode: validatedTargetMode || 'Internal',
+                });
+                manager.addRelationship(relationship);
+            }
+        }
+        return manager;
+    }
+}
+//# sourceMappingURL=RelationshipManager.js.map

package/dist/esm/core/RelationshipManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RelationshipManager.js","sourceRoot":"","sources":["../../../src/core/RelationshipManager.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * RelationshipManager - Manages collections of relationships\n *\n * Handles relationship creation, tracking, and XML generation for various\n * document parts (document.xml, header.xml, footer.xml, etc.)\n */\n\nimport { Relationship, RelationshipType } from './Relationship.js';\nimport { XMLParser } from '../xml/XMLParser.js';\nimport { sanitizeHyperlinkUrl } from '../utils/validation.js';\nimport { InvalidDocxError, CorruptedArchiveError } from '../zip/errors.js';\n\n/**\n * Manages relationships for a document or document part\n */\nexport class RelationshipManager {\n  private relationships: Map<string, Relationship>;\n  private nextId: number;\n\n  /**\n   * Creates a new relationship manager\n   */\n  constructor() {\n    this.relationships = new Map();\n    this.nextId = 1;\n  }\n\n  /**\n   * Adds a relationship\n   * @param relationship The relationship to add\n   * @returns The relationship that was added\n   */\n  addRelationship(relationship: Relationship): Relationship {\n    this.relationships.set(relationship.getId(), relationship);\n\n    // Update next ID if necessary\n    const idMatch = /^rId(\\d+)$/.exec(relationship.getId());\n    if (idMatch?.[1]) {\n      const idNum = parseInt(idMatch[1], 10);\n      if (idNum >= this.nextId) {\n        this.nextId = idNum + 1;\n      }\n    }\n\n    return relationship;\n  }\n\n  /**\n   * Gets a relationship by ID\n   * @param id The relationship ID\n   */\n  getRelationship(id: string): Relationship | undefined {\n    return this.relationships.get(id);\n  }\n\n  /**\n   * Gets all relationships\n   */\n  getAllRelationships(): Relationship[] {\n    return Array.from(this.relationships.values());\n  }\n\n  /**\n   * Gets relationships of a specific type\n   * @param type The relationship type\n   */\n  getRelationshipsByType(type: string | RelationshipType): Relationship[] {\n    return this.getAllRelationships().filter((rel) => rel.getType() === type);\n  }\n\n  /**\n   * Checks if a relationship exists\n   * @param id The relationship ID\n   */\n  hasRelationship(id: string): boolean {\n    return this.relationships.has(id);\n  }\n\n  /**\n   * Removes a relationship\n   * @param id The relationship ID\n   * @returns True if removed, false if not found\n   */\n  removeRelationship(id: string): boolean {\n    return this.relationships.delete(id);\n  }\n\n  /**\n   * Gets the number of relationships\n   */\n  getCount(): number {\n    return this.relationships.size;\n  }\n\n  /**\n   * Clears all relationships\n   */\n  clear(): this {\n    this.relationships.clear();\n    this.nextId = 1;\n    return this;\n  }\n\n  /**\n   * Generates a new unique relationship ID\n   * @returns New relationship ID (e.g., 'rId1', 'rId2')\n   */\n  generateId(): string {\n    return `rId${this.nextId++}`;\n  }\n\n  /**\n   * Adds a styles relationship\n   * @returns The created relationship\n   */\n  addStyles(): Relationship {\n    const id = this.generateId();\n    return this.addRelationship(Relationship.createStyles(id));\n  }\n\n  /**\n   * Adds a numbering relationship\n   * @returns The created relationship\n   */\n  addNumbering(): Relationship {\n    const id = this.generateId();\n    return this.addRelationship(Relationship.createNumbering(id));\n  }\n\n  /**\n   * Adds a fontTable relationship\n   * @returns The created relationship\n   */\n  addFontTable(): Relationship {\n    const id = this.generateId();\n    return this.addRelationship(Relationship.createFontTable(id));\n  }\n\n  /**\n   * Adds a settings relationship\n   * @returns The created relationship\n   */\n  addSettings(): Relationship {\n    const id = this.generateId();\n    return this.addRelationship(Relationship.createSettings(id));\n  }\n\n  /**\n   * Adds a webSettings relationship\n   * @returns The created relationship\n   */\n  addWebSettings(): Relationship {\n    const id = this.generateId();\n    return this.addRelationship(Relationship.createWebSettings(id));\n  }\n\n  /**\n   * Adds a theme relationship\n   * @returns The created relationship\n   */\n  addTheme(): Relationship {\n    const id = this.generateId();\n    return this.addRelationship(Relationship.createTheme(id));\n  }\n\n  /**\n   * Adds an image relationship\n   * @param target Image path relative to the part (e.g., 'media/image1.png')\n   * @returns The created relationship\n   */\n  addImage(target: string): Relationship {\n    const id = this.generateId();\n    return this.addRelationship(Relationship.createImage(id, target));\n  }\n\n  /**\n   * Adds a header relationship\n   * @param target Header file path (e.g., 'header1.xml')\n   * @returns The created relationship\n   */\n  addHeader(target: string): Relationship {\n    const id = this.generateId();\n    return this.addRelationship(Relationship.createHeader(id, target));\n  }\n\n  /**\n   * Adds a footer relationship\n   * @param target Footer file path (e.g., 'footer1.xml')\n   * @returns The created relationship\n   */\n  addFooter(target: string): Relationship {\n    const id = this.generateId();\n    return this.addRelationship(Relationship.createFooter(id, target));\n  }\n\n  /**\n   * Adds a hyperlink relationship\n   * @param url The hyperlink URL\n   * @returns The created relationship\n   */\n  addHyperlink(url: string): Relationship {\n    const id = this.generateId();\n    return this.addRelationship(Relationship.createHyperlink(id, url));\n  }\n\n  /**\n   * Updates the target URL of an existing hyperlink relationship\n   *\n   * This method modifies an existing relationship's target in-place, maintaining\n   * the same relationship ID. This is crucial for proper OpenXML compliance\n   * per ECMA-376 §17.16.22, as it prevents orphaned relationships.\n   *\n   * @param relationshipId The ID of the relationship to update\n   * @param newUrl The new URL to set\n   * @returns True if updated, false if relationship not found\n   */\n  updateHyperlinkTarget(relationshipId: string, newUrl: string): boolean {\n    const relationship = this.getRelationship(relationshipId);\n    if (!relationship) {\n      return false;\n    }\n\n    // Verify this is a hyperlink relationship\n    if (relationship.getType() !== RelationshipType.HYPERLINK) {\n      throw new InvalidDocxError(\n        `Relationship ${relationshipId} is not a hyperlink relationship. ` +\n          `Type is ${relationship.getType()}, expected ${RelationshipType.HYPERLINK}`\n      );\n    }\n\n    // Update the target URL\n    relationship.setTarget(newUrl);\n    return true;\n  }\n\n  /**\n   * Finds a hyperlink relationship by its target URL\n   *\n   * @param targetUrl The URL to search for\n   * @returns The matching relationship, or undefined if not found\n   */\n  findHyperlinkByTarget(targetUrl: string): Relationship | undefined {\n    return this.getAllRelationships().find(\n      (rel) => rel.getType() === RelationshipType.HYPERLINK && rel.getTarget() === targetUrl\n    );\n  }\n\n  /**\n   * Gets or creates a hyperlink relationship for the given URL\n   *\n   * This method ensures we don't create duplicate relationships for the same URL.\n   * If a relationship already exists for the URL, it returns the existing one.\n   * Otherwise, it creates a new relationship.\n   *\n   * @param url The hyperlink URL\n   * @returns The existing or newly created relationship\n   */\n  getOrCreateHyperlink(url: string): Relationship {\n    // Check if relationship already exists for this URL\n    const existing = this.findHyperlinkByTarget(url);\n    if (existing) {\n      return existing;\n    }\n\n    // Create new relationship\n    return this.addHyperlink(url);\n  }\n\n  /**\n   * Removes orphaned hyperlink relationships\n   *\n   * This method removes hyperlink relationships that are no longer referenced\n   * by any hyperlink in the document. Call this after updating URLs to clean\n   * up any orphaned relationships.\n   *\n   * @param referencedIds Set of relationship IDs that are still in use\n   * @returns Number of relationships removed\n   */\n  removeOrphanedHyperlinks(referencedIds: Set<string>): number {\n    let removed = 0;\n    const toRemove: string[] = [];\n\n    // Find orphaned relationships\n    for (const rel of this.getAllRelationships()) {\n      if (rel.getType() === RelationshipType.HYPERLINK && !referencedIds.has(rel.getId())) {\n        toRemove.push(rel.getId());\n      }\n    }\n\n    // Remove orphaned relationships\n    for (const id of toRemove) {\n      if (this.removeRelationship(id)) {\n        removed++;\n      }\n    }\n\n    return removed;\n  }\n\n  /**\n   * Adds a comments relationship\n   * @returns The created relationship\n   */\n  addComments(): Relationship {\n    const id = this.generateId();\n    return this.addRelationship(Relationship.createComments(id));\n  }\n\n  /**\n   * Adds a footnotes relationship\n   * @returns The created relationship\n   */\n  addFootnotes(): Relationship {\n    const id = this.generateId();\n    return this.addRelationship(Relationship.createFootnotes(id));\n  }\n\n  /**\n   * Adds an endnotes relationship\n   * @returns The created relationship\n   */\n  addEndnotes(): Relationship {\n    const id = this.generateId();\n    return this.addRelationship(Relationship.createEndnotes(id));\n  }\n\n  /**\n   * Adds a people relationship (track changes authors)\n   * @returns The created relationship\n   */\n  addPeople(): Relationship {\n    const id = this.generateId();\n    return this.addRelationship(Relationship.createPeople(id));\n  }\n\n  /**\n   * Generates the relationships XML file content\n   * @returns Complete XML string for .rels file\n   */\n  generateXml(): string {\n    const relationships = this.getAllRelationships();\n\n    let xml = '<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\\n';\n    xml += '<Relationships xmlns=\"http://schemas.openxmlformats.org/package/2006/relationships\">\\n';\n\n    for (const rel of relationships) {\n      xml += rel.toXML() + '\\n';\n    }\n\n    xml += '</Relationships>';\n\n    return xml;\n  }\n\n  /**\n   * Creates a new relationship manager with common document relationships\n   * @returns RelationshipManager with styles, numbering, fontTable, settings, and theme relationships\n   */\n  static createForDocument(): RelationshipManager {\n    const manager = new RelationshipManager();\n    manager.addStyles();\n    manager.addNumbering();\n    manager.addFontTable();\n    manager.addSettings();\n    manager.addWebSettings();\n    manager.addTheme();\n    return manager;\n  }\n\n  /**\n   * Creates an empty relationship manager\n   * @returns Empty RelationshipManager\n   */\n  static create(): RelationshipManager {\n    return new RelationshipManager();\n  }\n\n  /**\n   * Parses relationships from XML string and creates a populated manager\n   * @param xml The relationships XML content (.rels file)\n   * @returns RelationshipManager with parsed relationships\n   */\n  static fromXml(xml: string): RelationshipManager {\n    const manager = new RelationshipManager();\n\n    // Prevent ReDoS: validate input size (typical .rels files are < 10KB, max 10MB)\n    if (xml.length > 10000000) {\n      throw new CorruptedArchiveError(\n        'Relationships XML file too large (>10MB). Possible malicious input or corrupted file.'\n      );\n    }\n\n    // Use XMLParser to extract all Relationship elements\n    const relationshipElements = XMLParser.extractElements(xml, 'Relationship');\n\n    // Prevent infinite loops: check relationship count\n    if (relationshipElements.length > 1000) {\n      throw new CorruptedArchiveError(\n        'Too many relationships in XML file (>1000). Possible malicious input.'\n      );\n    }\n\n    // Process each relationship element\n    for (const relationshipElement of relationshipElements) {\n      // Extract attributes using XMLParser\n      const id = XMLParser.extractAttribute(relationshipElement, 'Id');\n      const type = XMLParser.extractAttribute(relationshipElement, 'Type');\n      const target = XMLParser.extractAttribute(relationshipElement, 'Target');\n      const targetMode = XMLParser.extractAttribute(relationshipElement, 'TargetMode');\n\n      // Only create relationship if all required attributes present\n      if (id && type && target) {\n        // Validate targetMode before type assertion\n        const validatedTargetMode =\n          targetMode === 'Internal' || targetMode === 'External' || targetMode === undefined\n            ? targetMode\n            : undefined;\n\n        // Sanitize hyperlink URLs (strip browser extension prefixes)\n        let sanitizedTarget = target;\n        if (type.endsWith('/hyperlink')) {\n          const result = sanitizeHyperlinkUrl(target);\n          if (result) {\n            sanitizedTarget = result.url;\n          }\n        }\n\n        // Create and add relationship\n        const relationship = Relationship.create({\n          id,\n          type,\n          target: sanitizedTarget,\n          targetMode: validatedTargetMode || 'Internal',\n        });\n\n        manager.addRelationship(relationship);\n      }\n    }\n\n    return manager;\n  }\n}\n"]}

package/dist/esm/elements/AlternateContent.js

@@ -0,0 +1,19 @@
+export class AlternateContent {
+    rawXml;
+    constructor(rawXml) {
+        this.rawXml = rawXml;
+    }
+    toXML() {
+        return {
+            name: '__rawXml',
+            rawXml: this.rawXml,
+        };
+    }
+    getRawXml() {
+        return this.rawXml;
+    }
+    getType() {
+        return 'alternateContent';
+    }
+}
+//# sourceMappingURL=AlternateContent.js.map

package/dist/esm/elements/AlternateContent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AlternateContent.js","sourceRoot":"","sources":["../../../src/elements/AlternateContent.ts"],"names":[],"mappings":"AAWA,MAAM,OAAO,gBAAgB;IACnB,MAAM,CAAS;IAEvB,YAAY,MAAc;QACxB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAKD,KAAK;QACH,OAAO;YACL,IAAI,EAAE,UAAU;YAChB,MAAM,EAAE,IAAI,CAAC,MAAM;SACN,CAAC;IAClB,CAAC;IAKD,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAKD,OAAO;QACL,OAAO,kBAAkB,CAAC;IAC5B,CAAC;CACF","sourcesContent":["/**\n * AlternateContent - Represents mc:AlternateContent block element\n *\n * Per ECMA-376 Part 3 §11.4, mc:AlternateContent provides markup compatibility.\n * Word uses this for newer features (Word 2010+ shapes as Choice, VML as Fallback).\n *\n * Stored as raw XML for round-trip fidelity since the internal structure varies widely.\n */\n\nimport { XMLElement } from '../xml/XMLBuilder.js';\n\nexport class AlternateContent {\n  private rawXml: string;\n\n  constructor(rawXml: string) {\n    this.rawXml = rawXml;\n  }\n\n  /**\n   * Returns the raw XML for round-trip serialization\n   */\n  toXML(): XMLElement {\n    return {\n      name: '__rawXml',\n      rawXml: this.rawXml,\n    } as XMLElement;\n  }\n\n  /**\n   * Gets the raw XML string\n   */\n  getRawXml(): string {\n    return this.rawXml;\n  }\n\n  /**\n   * Returns the element type identifier\n   */\n  getType(): string {\n    return 'alternateContent';\n  }\n}\n"]}

package/dist/esm/elements/Bookmark.js

@@ -0,0 +1,115 @@
+export class Bookmark {
+    id;
+    name;
+    colFirst;
+    colLast;
+    displacedByCustomXml;
+    constructor(properties) {
+        this.id = properties.id ?? 0;
+        this.name = properties.skipNormalization
+            ? properties.name
+            : this.normalizeName(properties.name);
+        this.colFirst = properties.colFirst;
+        this.colLast = properties.colLast;
+        this.displacedByCustomXml = properties.displacedByCustomXml;
+    }
+    normalizeName(name) {
+        let normalized = name.replace(/[^a-zA-Z0-9_]/g, '_');
+        if (normalized.length > 0 && /^\d/.test(normalized)) {
+            normalized = '_' + normalized;
+        }
+        if (normalized.length > 40) {
+            normalized = normalized.substring(0, 40);
+        }
+        if (normalized.length === 0) {
+            normalized = '_bookmark';
+        }
+        return normalized;
+    }
+    getId() {
+        return this.id;
+    }
+    setId(id) {
+        this.id = id;
+    }
+    getName() {
+        return this.name;
+    }
+    setName(name) {
+        this.name = this.normalizeName(name);
+        return this;
+    }
+    setRawName(name) {
+        this.name = name;
+        return this;
+    }
+    getColFirst() {
+        return this.colFirst;
+    }
+    getColLast() {
+        return this.colLast;
+    }
+    setColumnRange(colFirst, colLast) {
+        this.colFirst = colFirst;
+        this.colLast = colLast;
+        return this;
+    }
+    getDisplacedByCustomXml() {
+        return this.displacedByCustomXml;
+    }
+    setDisplacedByCustomXml(value) {
+        this.displacedByCustomXml = value;
+        return this;
+    }
+    toStartXML() {
+        const attrs = {
+            'w:id': this.id.toString(),
+            'w:name': this.name,
+        };
+        if (this.colFirst !== undefined)
+            attrs['w:colFirst'] = this.colFirst.toString();
+        if (this.colLast !== undefined)
+            attrs['w:colLast'] = this.colLast.toString();
+        if (this.displacedByCustomXml) {
+            attrs['w:displacedByCustomXml'] = this.displacedByCustomXml;
+        }
+        return {
+            name: 'w:bookmarkStart',
+            attributes: attrs,
+            selfClosing: true,
+        };
+    }
+    toEndXML() {
+        const attrs = {
+            'w:id': this.id.toString(),
+        };
+        if (this.displacedByCustomXml) {
+            attrs['w:displacedByCustomXml'] = this.displacedByCustomXml;
+        }
+        return {
+            name: 'w:bookmarkEnd',
+            attributes: attrs,
+            selfClosing: true,
+        };
+    }
+    toXML() {
+        return [this.toStartXML(), this.toEndXML()];
+    }
+    static create(name) {
+        return new Bookmark({ name });
+    }
+    static createForHeading(headingText) {
+        const name = headingText
+            .trim()
+            .replace(/[^a-zA-Z0-9]+/g, '_')
+            .substring(0, 40);
+        return new Bookmark({ name: name || '_heading' });
+    }
+    static createAuto(prefix = 'bookmark') {
+        const timestamp = Date.now().toString(36);
+        const random = Math.random().toString(36).substring(2, 7);
+        const name = `${prefix}_${timestamp}_${random}`;
+        return new Bookmark({ name });
+    }
+}
+//# sourceMappingURL=Bookmark.js.map

package/dist/esm/elements/Bookmark.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Bookmark.js","sourceRoot":"","sources":["../../../src/elements/Bookmark.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Bookmark - Represents a bookmark in a Word document\n *\n * Bookmarks mark specific locations in a document for internal navigation.\n * They consist of a start marker and an end marker with matching IDs.\n */\n\nimport { XMLElement } from '../xml/XMLBuilder.js';\n\n/**\n * `w:displacedByCustomXml` attribute value per ECMA-376 CT_MarkupRange —\n * ST_DisplacedByCustomXml enum: \"next\" | \"prev\". Indicates which side of\n * a custom-XML boundary the marker semantically belongs to when the\n * marker had to be displaced because a custom-XML node boundary fell at\n * the same position.\n */\nexport type DisplacedByCustomXml = 'next' | 'prev';\n\n/**\n * Bookmark properties\n */\nexport interface BookmarkProperties {\n  /** Unique bookmark ID (generated automatically if not provided) */\n  id?: number;\n  /** Bookmark name (must be unique within document) */\n  name: string;\n  /** Skip name normalization (used when loading from existing documents) */\n  skipNormalization?: boolean;\n  /** First column in table bookmark range (ECMA-376 §17.16.5) */\n  colFirst?: number;\n  /** Last column in table bookmark range (ECMA-376 §17.16.5) */\n  colLast?: number;\n  /**\n   * `w:displacedByCustomXml` per ECMA-376 CT_MarkupRange / CT_Bookmark.\n   * Valid on both `<w:bookmarkStart>` (CT_Bookmark) and `<w:bookmarkEnd>`\n   * (CT_MarkupRange). Preserves the custom-XML boundary disambiguator\n   * that Word emits when a bookmark was displaced by a custom-XML node.\n   */\n  displacedByCustomXml?: DisplacedByCustomXml;\n}\n\n/**\n * Represents a bookmark location in a document\n */\nexport class Bookmark {\n  private id: number;\n  private name: string;\n  private colFirst?: number;\n  private colLast?: number;\n  private displacedByCustomXml?: DisplacedByCustomXml;\n\n  /**\n   * Creates a new Bookmark\n   * @param properties - Bookmark properties\n   */\n  constructor(properties: BookmarkProperties) {\n    this.id = properties.id ?? 0; // ID will be assigned by BookmarkManager\n    // Preserve exact bookmark names when loading from documents (Word allows =, ., etc.)\n    // Only normalize when creating new bookmarks programmatically\n    this.name = properties.skipNormalization\n      ? properties.name\n      : this.normalizeName(properties.name);\n    this.colFirst = properties.colFirst;\n    this.colLast = properties.colLast;\n    this.displacedByCustomXml = properties.displacedByCustomXml;\n  }\n\n  /**\n   * Normalizes a bookmark name to be valid\n   * - Must start with a letter or underscore\n   * - Can only contain letters, numbers, and underscores\n   * - Maximum 40 characters\n   * - Case-insensitive (Word converts to lowercase)\n   * @param name - Raw bookmark name\n   * @returns Normalized bookmark name\n   */\n  private normalizeName(name: string): string {\n    // Remove invalid characters\n    let normalized = name.replace(/[^a-zA-Z0-9_]/g, '_');\n\n    // Ensure it starts with a letter or underscore\n    if (normalized.length > 0 && /^\\d/.test(normalized)) {\n      normalized = '_' + normalized;\n    }\n\n    // Limit to 40 characters\n    if (normalized.length > 40) {\n      normalized = normalized.substring(0, 40);\n    }\n\n    // Default if empty\n    if (normalized.length === 0) {\n      normalized = '_bookmark';\n    }\n\n    return normalized;\n  }\n\n  /**\n   * Gets the bookmark ID\n   */\n  getId(): number {\n    return this.id;\n  }\n\n  /**\n   * Sets the bookmark ID (used by BookmarkManager)\n   * @internal\n   */\n  setId(id: number): void {\n    this.id = id;\n  }\n\n  /**\n   * Gets the bookmark name\n   */\n  getName(): string {\n    return this.name;\n  }\n\n  /**\n   * Sets the bookmark name (normalizes the name)\n   *\n   * The name will be normalized:\n   * - Invalid characters replaced with underscores\n   * - Leading digits prefixed with underscore\n   * - Limited to 40 characters\n   *\n   * @param name - New bookmark name\n   * @returns This bookmark for chaining\n   */\n  setName(name: string): this {\n    this.name = this.normalizeName(name);\n    return this;\n  }\n\n  /**\n   * Sets the bookmark name without normalization\n   *\n   * Use this method when:\n   * - Preserving exact names from imported documents\n   * - Setting names with special characters that Word allows (=, ., etc.)\n   * - Round-trip fidelity is required\n   *\n   * **Warning:** Setting invalid bookmark names may cause issues in Word.\n   * Only use this if you know the name is valid or needs to match an existing document.\n   *\n   * @param name - Raw bookmark name (not normalized)\n   * @returns This bookmark for chaining\n   *\n   * @example\n   * ```typescript\n   * // Preserve exact name from Word document\n   * bookmark.setRawName('SECTION=II.MNKE7E8NA385_');\n   *\n   * // For new bookmarks, prefer setName() which normalizes\n   * bookmark.setName('My Heading'); // Becomes 'My_Heading'\n   * ```\n   */\n  setRawName(name: string): this {\n    this.name = name;\n    return this;\n  }\n\n  /**\n   * Gets the first column in a table bookmark range\n   */\n  getColFirst(): number | undefined {\n    return this.colFirst;\n  }\n\n  /**\n   * Gets the last column in a table bookmark range\n   */\n  getColLast(): number | undefined {\n    return this.colLast;\n  }\n\n  /**\n   * Sets the column range for a table bookmark (ECMA-376 §17.16.5)\n   */\n  setColumnRange(colFirst: number, colLast: number): this {\n    this.colFirst = colFirst;\n    this.colLast = colLast;\n    return this;\n  }\n\n  /**\n   * Gets the `w:displacedByCustomXml` attribute value.\n   * Preserved on both bookmarkStart and bookmarkEnd per ECMA-376\n   * CT_MarkupRange (§17.13.5) / CT_Bookmark (§17.16.5).\n   */\n  getDisplacedByCustomXml(): DisplacedByCustomXml | undefined {\n    return this.displacedByCustomXml;\n  }\n\n  /**\n   * Sets the `w:displacedByCustomXml` attribute value.\n   * @param value \"next\" | \"prev\" | undefined\n   */\n  setDisplacedByCustomXml(value: DisplacedByCustomXml | undefined): this {\n    this.displacedByCustomXml = value;\n    return this;\n  }\n\n  /**\n   * Generates XML for the bookmark start marker\n   * @returns XMLElement for bookmarkStart\n   */\n  toStartXML(): XMLElement {\n    const attrs: Record<string, string | number> = {\n      'w:id': this.id.toString(),\n      'w:name': this.name,\n    };\n    // Table bookmark column range per ECMA-376 §17.16.5\n    if (this.colFirst !== undefined) attrs['w:colFirst'] = this.colFirst.toString();\n    if (this.colLast !== undefined) attrs['w:colLast'] = this.colLast.toString();\n    // Custom-XML displacement marker per CT_MarkupRange (§17.13.5) —\n    // the same attribute also carried by the RangeMarker sibling class.\n    if (this.displacedByCustomXml) {\n      attrs['w:displacedByCustomXml'] = this.displacedByCustomXml;\n    }\n    return {\n      name: 'w:bookmarkStart',\n      attributes: attrs,\n      selfClosing: true,\n    };\n  }\n\n  /**\n   * Generates XML for the bookmark end marker\n   * @returns XMLElement for bookmarkEnd\n   */\n  toEndXML(): XMLElement {\n    const attrs: Record<string, string | number> = {\n      'w:id': this.id.toString(),\n    };\n    // bookmarkEnd is CT_MarkupRange per ECMA-376 §17.13.6.1 — w:displacedByCustomXml\n    // is valid here too (the BookmarkRange column attributes are NOT, so those\n    // stay scoped to toStartXML above).\n    if (this.displacedByCustomXml) {\n      attrs['w:displacedByCustomXml'] = this.displacedByCustomXml;\n    }\n    return {\n      name: 'w:bookmarkEnd',\n      attributes: attrs,\n      selfClosing: true,\n    };\n  }\n\n  /**\n   * Generates both start and end XML elements as an array\n   * @returns Array of XMLElements [start, end]\n   */\n  toXML(): [XMLElement, XMLElement] {\n    return [this.toStartXML(), this.toEndXML()];\n  }\n\n  /**\n   * Creates a new Bookmark\n   * @param name - Bookmark name\n   * @returns New Bookmark instance\n   */\n  static create(name: string): Bookmark {\n    return new Bookmark({ name });\n  }\n\n  /**\n   * Creates a bookmark for a heading\n   * Useful for table of contents internal links\n   * @param headingText - The text of the heading\n   * @returns New Bookmark instance with normalized name\n   */\n  static createForHeading(headingText: string): Bookmark {\n    // Create a bookmark name from heading text\n    // Example: \"Chapter 1: Introduction\" -> \"_Chapter_1_Introduction\"\n    const name = headingText\n      .trim()\n      .replace(/[^a-zA-Z0-9]+/g, '_')\n      .substring(0, 40);\n    return new Bookmark({ name: name || '_heading' });\n  }\n\n  /**\n   * Creates a bookmark with an auto-generated unique name\n   * @param prefix - Optional prefix for the name (default: 'bookmark')\n   * @returns New Bookmark instance\n   */\n  static createAuto(prefix = 'bookmark'): Bookmark {\n    const timestamp = Date.now().toString(36);\n    const random = Math.random().toString(36).substring(2, 7);\n    const name = `${prefix}_${timestamp}_${random}`;\n    return new Bookmark({ name });\n  }\n}\n"]}

package/dist/esm/elements/BookmarkManager.js

@@ -0,0 +1,99 @@
+import { Bookmark } from './Bookmark.js';
+import { InvalidDocxError } from '../zip/errors.js';
+export class BookmarkManager {
+    bookmarks = new Map();
+    nextId = 0;
+    idProvider = null;
+    idExistsNotifier = null;
+    setIdProvider(provider, existsNotifier) {
+        this.idProvider = provider;
+        this.idExistsNotifier = existsNotifier || null;
+    }
+    register(bookmark) {
+        const name = bookmark.getName();
+        if (this.bookmarks.has(name)) {
+            throw new InvalidDocxError(`Bookmark with name "${name}" already exists. Bookmark names must be unique within a document.`);
+        }
+        const id = this.idProvider ? this.idProvider() : this.nextId++;
+        bookmark.setId(id);
+        this.bookmarks.set(name, bookmark);
+        return bookmark;
+    }
+    registerExisting(bookmark) {
+        const name = bookmark.getName();
+        const existingId = bookmark.getId();
+        if (this.bookmarks.has(name)) {
+            throw new InvalidDocxError(`Bookmark with name "${name}" already exists. Bookmark names must be unique within a document.`);
+        }
+        if (this.idExistsNotifier) {
+            this.idExistsNotifier(existingId);
+        }
+        if (existingId >= this.nextId) {
+            this.nextId = existingId + 1;
+        }
+        this.bookmarks.set(name, bookmark);
+        return bookmark;
+    }
+    getBookmark(name) {
+        return this.bookmarks.get(name);
+    }
+    hasBookmark(name) {
+        return this.bookmarks.has(name);
+    }
+    getAllBookmarks() {
+        return Array.from(this.bookmarks.values());
+    }
+    getCount() {
+        return this.bookmarks.size;
+    }
+    removeBookmark(name) {
+        return this.bookmarks.delete(name);
+    }
+    clear() {
+        this.bookmarks.clear();
+        this.nextId = 0;
+    }
+    setNextId(id) {
+        this.nextId = id;
+    }
+    getUniqueName(baseName) {
+        const maxLength = 40;
+        if (!this.hasBookmark(baseName)) {
+            return baseName;
+        }
+        let counter = 1;
+        while (counter <= 1000) {
+            const suffix = `_${counter}`;
+            const maxBase = maxLength - suffix.length;
+            const truncatedBase = baseName.length > maxBase ? baseName.substring(0, maxBase) : baseName;
+            const uniqueName = `${truncatedBase}${suffix}`;
+            if (!this.hasBookmark(uniqueName)) {
+                return uniqueName;
+            }
+            counter++;
+        }
+        throw new InvalidDocxError(`Could not generate unique bookmark name from base "${baseName}"`);
+    }
+    createBookmark(name) {
+        const uniqueName = this.getUniqueName(name);
+        const bookmark = Bookmark.create(uniqueName);
+        return this.register(bookmark);
+    }
+    createHeadingBookmark(headingText) {
+        const bookmark = Bookmark.createForHeading(headingText);
+        const uniqueName = this.getUniqueName(bookmark.getName());
+        bookmark.setName(uniqueName);
+        return this.register(bookmark);
+    }
+    getStats() {
+        return {
+            total: this.bookmarks.size,
+            nextId: this.nextId,
+            names: Array.from(this.bookmarks.keys()),
+        };
+    }
+    static create() {
+        return new BookmarkManager();
+    }
+}
+//# sourceMappingURL=BookmarkManager.js.map

package/dist/esm/elements/BookmarkManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BookmarkManager.js","sourceRoot":"","sources":["../../../src/elements/BookmarkManager.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * BookmarkManager - Manages bookmarks in a document\n *\n * Tracks all bookmarks, assigns unique IDs, and ensures name uniqueness.\n *\n * Per ECMA-376, bookmark IDs must be unique across ALL annotation types\n * in a document. Use setIdProvider() to connect to a centralized ID allocator.\n */\n\nimport { Bookmark } from './Bookmark.js';\nimport { InvalidDocxError } from '../zip/errors.js';\n\n/**\n * Type for the centralized ID provider callback.\n * Returns the next available annotation ID from a shared counter.\n */\nexport type IdProviderCallback = () => number;\n\n/**\n * Type for callback to notify of existing IDs (for synchronization).\n * Called when registering an existing bookmark to keep the central counter in sync.\n */\nexport type IdExistsCallback = (existingId: number) => void;\n\n/**\n * Manages document bookmarks\n */\nexport class BookmarkManager {\n  private bookmarks = new Map<string, Bookmark>();\n  private nextId = 0;\n  private idProvider: IdProviderCallback | null = null;\n  private idExistsNotifier: IdExistsCallback | null = null;\n\n  /**\n   * Sets the centralized ID provider callback.\n   * When set, IDs will be allocated from the centralized DocumentIdManager\n   * instead of the local nextId counter.\n   *\n   * @param provider - Callback that returns the next available ID\n   * @param existsNotifier - Optional callback to notify when existing IDs are found\n   */\n  setIdProvider(provider: IdProviderCallback, existsNotifier?: IdExistsCallback): void {\n    this.idProvider = provider;\n    this.idExistsNotifier = existsNotifier || null;\n  }\n\n  /**\n   * Registers a bookmark with the manager\n   * Assigns a unique ID and ensures name uniqueness\n   * @param bookmark - Bookmark to register\n   * @returns The registered bookmark (same instance)\n   * @throws Error if a bookmark with the same name already exists\n   */\n  register(bookmark: Bookmark): Bookmark {\n    const name = bookmark.getName();\n\n    // Check for duplicate names\n    if (this.bookmarks.has(name)) {\n      throw new InvalidDocxError(\n        `Bookmark with name \"${name}\" already exists. Bookmark names must be unique within a document.`\n      );\n    }\n\n    // Assign unique ID - use centralized provider if available\n    const id = this.idProvider ? this.idProvider() : this.nextId++;\n    bookmark.setId(id);\n\n    // Store bookmark\n    this.bookmarks.set(name, bookmark);\n\n    return bookmark;\n  }\n\n  /**\n   * Registers an existing bookmark, preserving its ID\n   * Used when loading documents to preserve original bookmark IDs and avoid collisions\n   * @param bookmark - Bookmark with existing ID to register\n   * @returns The registered bookmark (same instance)\n   * @throws Error if a bookmark with the same name already exists\n   */\n  registerExisting(bookmark: Bookmark): Bookmark {\n    const name = bookmark.getName();\n    const existingId = bookmark.getId();\n\n    // Check for duplicate names\n    if (this.bookmarks.has(name)) {\n      throw new InvalidDocxError(\n        `Bookmark with name \"${name}\" already exists. Bookmark names must be unique within a document.`\n      );\n    }\n\n    // Notify centralized ID manager about this existing ID\n    if (this.idExistsNotifier) {\n      this.idExistsNotifier(existingId);\n    }\n\n    // Also update local nextId to avoid collisions (for fallback)\n    if (existingId >= this.nextId) {\n      this.nextId = existingId + 1;\n    }\n\n    // Store bookmark (keep its existing ID)\n    this.bookmarks.set(name, bookmark);\n\n    return bookmark;\n  }\n\n  /**\n   * Gets a bookmark by name\n   * @param name - Bookmark name\n   * @returns The bookmark, or undefined if not found\n   */\n  getBookmark(name: string): Bookmark | undefined {\n    return this.bookmarks.get(name);\n  }\n\n  /**\n   * Checks if a bookmark exists\n   * @param name - Bookmark name\n   * @returns True if the bookmark exists\n   */\n  hasBookmark(name: string): boolean {\n    return this.bookmarks.has(name);\n  }\n\n  /**\n   * Gets all bookmarks\n   * @returns Array of all bookmarks\n   */\n  getAllBookmarks(): Bookmark[] {\n    return Array.from(this.bookmarks.values());\n  }\n\n  /**\n   * Gets the number of bookmarks\n   * @returns Number of bookmarks\n   */\n  getCount(): number {\n    return this.bookmarks.size;\n  }\n\n  /**\n   * Removes a bookmark\n   * @param name - Bookmark name\n   * @returns True if the bookmark was removed\n   */\n  removeBookmark(name: string): boolean {\n    return this.bookmarks.delete(name);\n  }\n\n  /**\n   * Clears all bookmarks\n   */\n  clear(): void {\n    this.bookmarks.clear();\n    this.nextId = 0;\n  }\n\n  /**\n   * Sets the next ID to be assigned\n   * Used when loading documents to avoid ID collisions with existing bookmarks\n   * @param id - The next ID value to use\n   */\n  setNextId(id: number): void {\n    this.nextId = id;\n  }\n\n  /**\n   * Gets a unique bookmark name by adding a suffix if needed\n   * Ensures the returned name is always within the 40-character limit\n   * @param baseName - Base name for the bookmark\n   * @returns A unique bookmark name (max 40 characters)\n   */\n  getUniqueName(baseName: string): string {\n    const maxLength = 40;\n\n    if (!this.hasBookmark(baseName)) {\n      return baseName;\n    }\n\n    // Try adding numbers until we find a unique name\n    let counter = 1;\n    while (counter <= 1000) {\n      const suffix = `_${counter}`;\n\n      // Truncate base name to leave room for suffix within 40-char limit\n      const maxBase = maxLength - suffix.length;\n      const truncatedBase = baseName.length > maxBase ? baseName.substring(0, maxBase) : baseName;\n\n      const uniqueName = `${truncatedBase}${suffix}`;\n\n      if (!this.hasBookmark(uniqueName)) {\n        return uniqueName;\n      }\n      counter++;\n    }\n\n    throw new InvalidDocxError(`Could not generate unique bookmark name from base \"${baseName}\"`);\n  }\n\n  /**\n   * Creates and registers a new bookmark with a unique name\n   * @param name - Desired bookmark name\n   * @returns The created and registered bookmark\n   */\n  createBookmark(name: string): Bookmark {\n    const uniqueName = this.getUniqueName(name);\n    const bookmark = Bookmark.create(uniqueName);\n    return this.register(bookmark);\n  }\n\n  /**\n   * Creates and registers a bookmark for a heading\n   * Automatically generates a unique name from the heading text\n   * @param headingText - The text of the heading\n   * @returns The created and registered bookmark\n   */\n  createHeadingBookmark(headingText: string): Bookmark {\n    const bookmark = Bookmark.createForHeading(headingText);\n    const uniqueName = this.getUniqueName(bookmark.getName());\n    bookmark.setName(uniqueName);\n    return this.register(bookmark);\n  }\n\n  /**\n   * Gets statistics about bookmarks\n   * @returns Object with bookmark statistics\n   */\n  getStats(): {\n    total: number;\n    nextId: number;\n    names: string[];\n  } {\n    return {\n      total: this.bookmarks.size,\n      nextId: this.nextId,\n      names: Array.from(this.bookmarks.keys()),\n    };\n  }\n\n  /**\n   * Creates a new BookmarkManager\n   * @returns New BookmarkManager instance\n   */\n  static create(): BookmarkManager {\n    return new BookmarkManager();\n  }\n}\n"]}