@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/{esm/modules/word/writers → browser/modules/word/writer}/parts-writer.js

@@ -5,6 +5,7 @@
  * Renders various auxiliary parts of the DOCX package.
  */
 import { NS_W, NS_R, NS_M, NS_V, NS_O, NS_W14, NS_DC, NS_DCTERMS, NS_DCMITYPE, NS_CP, NS_EP, NS_VT, NS_XSI, NS_CUSTOM, STD_DOC_ATTRIBUTES } from "../constants.js";
+import { DocxRawXmlPolicyError } from "../errors.js";
 /** Render footnote/endnote properties in settings. */
 function renderSettingsNoteProperties(xml, tagName, props) {
     xml.openNode(tagName);
@@ -26,7 +27,7 @@ function renderSettingsNoteProperties(xml, tagName, props) {
 // Settings
 // =============================================================================
 /** Render word/settings.xml. */
-export function renderSettings(xml, settings) {
+export function renderSettings(xml, settings, rawXmlPolicy) {
     xml.openXml(STD_DOC_ATTRIBUTES);
     xml.openNode("w:settings", {
         "xmlns:w": NS_W,
@@ -141,10 +142,34 @@ export function renderSettings(xml, settings) {
     // Document protection
     if (settings?.documentProtection) {
         const dp = settings.documentProtection;
-        const attrs = { "w:edit": dp.type };
+        const attrs = {};
+        if (dp.type) {
+            attrs["w:edit"] = dp.type;
+        }
+        else if (dp.edit) {
+            attrs["w:edit"] = dp.edit;
+        }
         if (dp.enforcement !== undefined) {
             attrs["w:enforcement"] = dp.enforcement ? "1" : "0";
         }
+        if (dp.formatting !== undefined) {
+            attrs["w:formatting"] = dp.formatting ? "1" : "0";
+        }
+        if (dp.hashAlgorithm) {
+            attrs["w:cryptAlgorithmClass"] = "hash";
+            attrs["w:cryptAlgorithmType"] = "typeAny";
+            attrs["w:cryptAlgorithmSid"] = hashAlgorithmToSid(dp.hashAlgorithm);
+            attrs["w:cryptProviderType"] = "rsaAES";
+        }
+        if (dp.hashValue) {
+            attrs["w:hash"] = dp.hashValue;
+        }
+        if (dp.saltValue) {
+            attrs["w:salt"] = dp.saltValue;
+        }
+        if (dp.spinCount !== undefined) {
+            attrs["w:cryptSpinCount"] = String(dp.spinCount);
+        }
         xml.leafNode("w:documentProtection", attrs);
     }
     // Display background shape
@@ -172,7 +197,12 @@ export function renderSettings(xml, settings) {
     }
     // Mail merge (round-trip preservation)
     if (settings?.mailMergeRawXml) {
-        xml.writeRaw(settings.mailMergeRawXml);
+        if (rawXmlPolicy === "reject") {
+            throw new DocxRawXmlPolicyError("settings.mailMergeRawXml");
+        }
+        if (rawXmlPolicy !== "strip") {
+            xml.writeRaw(settings.mailMergeRawXml);
+        }
     }
     // Write protection
     if (settings?.writeProtection) {
@@ -207,14 +237,25 @@ export function renderSettings(xml, settings) {
             xml.leafNode(`w:${flag.name}`, attrs);
         }
     }
+    // Resolve compatibilityMode value: prefer an explicit entry in
+    // settings.compatSettings, then settings.compatibilityMode, then 15.
+    // Then emit every additional compatSetting (skipping the duplicate
+    // compatibilityMode entry to avoid two w:compatSetting elements with
+    // the same name — Word treats the first as authoritative, which would
+    // hide a user-supplied mode behind the default 15).
+    const explicitMode = settings?.compatSettings?.find(s => s.name === "compatibilityMode");
+    const compatibilityModeVal = explicitMode?.val ?? String(settings?.compatibilityMode ?? 15);
     xml.leafNode("w:compatSetting", {
         "w:name": "compatibilityMode",
         "w:uri": "http://schemas.microsoft.com/office/word",
-        "w:val": String(settings?.compatibilityMode ?? 15)
+        "w:val": compatibilityModeVal
     });
-    // Additional compatSettings
+    // Additional compatSettings (excluding compatibilityMode — already written)
     if (settings?.compatSettings) {
         for (const cs of settings.compatSettings) {
+            if (cs.name === "compatibilityMode") {
+                continue;
+            }
             xml.leafNode("w:compatSetting", {
                 "w:name": cs.name,
                 "w:uri": cs.uri,
@@ -472,7 +513,7 @@ export function renderCustomProperties(xml, properties) {
 // Theme (minimal default theme)
 // =============================================================================
 /** Render word/theme/theme1.xml (minimal theme). */
-export function renderTheme(xml, theme) {
+export function renderTheme(xml, theme, rawXmlPolicy) {
     const NS_A_LOCAL = "http://schemas.openxmlformats.org/drawingml/2006/main";
     xml.openXml(STD_DOC_ATTRIBUTES);
     xml.openNode("a:theme", { "xmlns:a": NS_A_LOCAL, name: theme?.name ?? "Office Theme" });
@@ -530,9 +571,19 @@ export function renderTheme(xml, theme) {
     xml.closeNode(); // a:fontScheme
     // Format scheme - preserve raw XML if provided, otherwise minimal default
     if (theme?.formatScheme?.rawXml) {
-        xml.openNode("a:fmtScheme", { name: theme.formatScheme.name });
-        xml.writeRaw(theme.formatScheme.rawXml);
-        xml.closeNode();
+        if (rawXmlPolicy === "reject") {
+            throw new DocxRawXmlPolicyError("theme.formatScheme.rawXml");
+        }
+        if (rawXmlPolicy === "strip") {
+            // Fall back to a minimal default rather than emitting an empty
+            // a:fmtScheme — Word treats an empty format scheme as malformed.
+            renderDefaultFormatScheme(xml);
+        }
+        else {
+            xml.openNode("a:fmtScheme", { name: theme.formatScheme.name });
+            xml.writeRaw(theme.formatScheme.rawXml);
+            xml.closeNode();
+        }
     }
     else {
         renderDefaultFormatScheme(xml);
@@ -540,7 +591,12 @@ export function renderTheme(xml, theme) {
     xml.closeNode(); // a:themeElements
     // Extension list (round-trip preservation)
     if (theme?.extLstXml) {
-        xml.writeRaw(theme.extLstXml);
+        if (rawXmlPolicy === "reject") {
+            throw new DocxRawXmlPolicyError("theme.extLstXml");
+        }
+        if (rawXmlPolicy !== "strip") {
+            xml.writeRaw(theme.extLstXml);
+        }
     }
     xml.closeNode(); // a:theme
 }
@@ -599,7 +655,7 @@ function renderDefaultFormatScheme(xml) {
 // Web Settings
 // =============================================================================
 /** Render word/webSettings.xml. */
-export function renderWebSettings(xml, ws) {
+export function renderWebSettings(xml, ws, rawXmlPolicy) {
     xml.openXml(STD_DOC_ATTRIBUTES);
     xml.openNode("w:webSettings", { "xmlns:w": NS_W });
     if (ws?.optimizeForBrowser) {
@@ -628,7 +684,12 @@ export function renderWebSettings(xml, ws) {
         xml.leafNode("w:useTargetMachineType");
     }
     if (ws?.rawXml) {
-        xml.writeRaw(ws.rawXml);
+        if (rawXmlPolicy === "reject") {
+            throw new DocxRawXmlPolicyError("webSettings.rawXml");
+        }
+        if (rawXmlPolicy !== "strip") {
+            xml.writeRaw(ws.rawXml);
+        }
     }
     xml.closeNode();
 }
@@ -658,3 +719,21 @@ export function renderPeople(xml, people) {
     }
     xml.closeNode();
 }
+// =============================================================================
+// Internal Helpers
+// =============================================================================
+/** Convert hash algorithm name to OOXML cryptAlgorithmSid value. */
+function hashAlgorithmToSid(algorithm) {
+    switch (algorithm) {
+        case "SHA-1":
+            return "4";
+        case "SHA-256":
+            return "12";
+        case "SHA-384":
+            return "13";
+        case "SHA-512":
+            return "14";
+        default:
+            return "4"; // Default to SHA-1
+    }
+}

package/dist/browser/modules/word/writer/reference-scanners.d.ts

@@ -0,0 +1,42 @@
+/**
+ * DOCX Module - Reference Scanners
+ *
+ * Shared helpers for scanning the document model for image / hyperlink /
+ * chart references that need to be registered against a part-level .rels
+ * file. Used by both the bulk packager and the streaming writer to avoid
+ * behaviour drift in how header/footer/notes/comments parts collect their
+ * own relationships.
+ */
+import type { ChartContent, HeaderFooterContent, Hyperlink, Paragraph, ParagraphChild } from "../types.js";
+/**
+ * Recursively collect image rIds referenced inside a list of paragraph
+ * children. Descends into track-change wrappers (`InsertedRun`,
+ * `MovedToRun`, etc.) so an image embedded inside `<w:ins>...</w:ins>` is
+ * not silently lost.
+ */
+export declare function scanChildrenForImages(children: readonly ParagraphChild[], out: Set<string>): void;
+/**
+ * Recursively collect external-URL hyperlinks from a list of paragraph
+ * children. Descends into track-change wrappers so an inserted hyperlink
+ * isn't dropped.
+ *
+ * Always emits hyperlinks that carry a `url`, regardless of whether the
+ * model already has an `rId`. Reader-supplied `rId`s are stale once the
+ * package is repackaged because the relationship table is rebuilt from
+ * scratch — the packager assigns its own canonical `rId<N>` and exposes
+ * it via the `hyperlinkRIds` WeakMap, which the renderer consults.
+ */
+export declare function scanChildrenForHyperlinks(children: readonly ParagraphChild[], out: Hyperlink[]): void;
+/** Collect all image rIds referenced in header/footer content. */
+export declare function collectImageRidsFromContent(content: HeaderFooterContent): Set<string>;
+/** Collect hyperlinks from header/footer content. */
+export declare function collectHyperlinksFromHeaderFooter(content: HeaderFooterContent): Hyperlink[];
+/** Collect all chart contents inside header/footer content. */
+export declare function collectChartsFromHeaderFooter(content: HeaderFooterContent, out: ChartContent[]): void;
+/** Collect image rIds and hyperlinks from a notes/comments collection. */
+export declare function collectImageRidsFromNotes(notes: readonly {
+    content: readonly Paragraph[];
+}[] | undefined): Set<string>;
+export declare function collectHyperlinksFromNotes(notes: readonly {
+    content: readonly Paragraph[];
+}[] | undefined): Hyperlink[];

package/dist/browser/modules/word/writer/reference-scanners.js

@@ -0,0 +1,111 @@
+/**
+ * DOCX Module - Reference Scanners
+ *
+ * Shared helpers for scanning the document model for image / hyperlink /
+ * chart references that need to be registered against a part-level .rels
+ * file. Used by both the bulk packager and the streaming writer to avoid
+ * behaviour drift in how header/footer/notes/comments parts collect their
+ * own relationships.
+ */
+import { walkBlocks } from "../core/walker.js";
+/** Scan a Run for image rIds. */
+function scanRunForImages(run, out) {
+    for (const rc of run.content) {
+        if (rc.type === "image" && rc.rId) {
+            out.add(rc.rId);
+        }
+    }
+}
+/**
+ * Recursively collect image rIds referenced inside a list of paragraph
+ * children. Descends into track-change wrappers (`InsertedRun`,
+ * `MovedToRun`, etc.) so an image embedded inside `<w:ins>...</w:ins>` is
+ * not silently lost.
+ */
+export function scanChildrenForImages(children, out) {
+    walkBlocks([{ type: "paragraph", children }], {
+        enterRun(run) {
+            scanRunForImages(run, out);
+        }
+    });
+}
+/**
+ * Recursively collect external-URL hyperlinks from a list of paragraph
+ * children. Descends into track-change wrappers so an inserted hyperlink
+ * isn't dropped.
+ *
+ * Always emits hyperlinks that carry a `url`, regardless of whether the
+ * model already has an `rId`. Reader-supplied `rId`s are stale once the
+ * package is repackaged because the relationship table is rebuilt from
+ * scratch — the packager assigns its own canonical `rId<N>` and exposes
+ * it via the `hyperlinkRIds` WeakMap, which the renderer consults.
+ */
+export function scanChildrenForHyperlinks(children, out) {
+    walkBlocks([{ type: "paragraph", children }], {
+        enterHyperlink(h) {
+            if (h.url) {
+                out.push(h);
+            }
+        }
+    });
+}
+/**
+ * Walk paragraphs in a block list (recursing through tables, SDTs, TOC
+ * cached paragraphs, text boxes) and visit each paragraph.
+ */
+function walkParagraphs(blocks, onParagraph) {
+    walkBlocks(blocks, {
+        enterParagraph(p) {
+            onParagraph(p);
+        }
+    });
+}
+/** Collect all image rIds referenced in header/footer content. */
+export function collectImageRidsFromContent(content) {
+    const rIds = new Set();
+    walkParagraphs(content.children, p => {
+        scanChildrenForImages(p.children, rIds);
+    });
+    return rIds;
+}
+/** Collect hyperlinks from header/footer content. */
+export function collectHyperlinksFromHeaderFooter(content) {
+    const links = [];
+    walkParagraphs(content.children, p => {
+        scanChildrenForHyperlinks(p.children, links);
+    });
+    return links;
+}
+/** Collect all chart contents inside header/footer content. */
+export function collectChartsFromHeaderFooter(content, out) {
+    walkBlocks(content.children, {
+        visitChart(chart) {
+            out.push(chart);
+        }
+    });
+}
+/** Collect image rIds and hyperlinks from a notes/comments collection. */
+export function collectImageRidsFromNotes(notes) {
+    const rIds = new Set();
+    if (!notes) {
+        return rIds;
+    }
+    for (const note of notes) {
+        for (const p of note.content) {
+            scanChildrenForImages(p.children, rIds);
+        }
+    }
+    return rIds;
+}
+export function collectHyperlinksFromNotes(notes) {
+    const links = [];
+    if (!notes) {
+        return links;
+    }
+    for (const note of notes) {
+        for (const p of note.content) {
+            scanChildrenForHyperlinks(p.children, links);
+        }
+    }
+    return links;
+}

package/dist/browser/modules/word/writer/relationships.d.ts

@@ -0,0 +1,52 @@
+/**
+ * DOCX Module - Relationship Manager
+ *
+ * Manages OPC relationships for the DOCX package.
+ * Generates .rels files for package-level and part-level relationships.
+ *
+ * Provides both an object-oriented RelationshipsState interface and
+ * backward-compatible free functions (addRelationship, renderRelationships, etc.).
+ */
+import type { XmlSink } from "../../xml/types.js";
+/** A single OPC relationship. */
+export interface Relationship {
+    readonly id: string;
+    readonly type: string;
+    readonly target: string;
+    /**
+     * OPC TargetMode. Standard values are `"External"` and `"Internal"`
+     * (with `"Internal"` typically omitted on the wire). Internally we accept
+     * any string so that round-tripped relationships preserve non-standard
+     * values verbatim; new relationships emitted by the writer's own helpers
+     * still pass `"External"` or `undefined`.
+     */
+    readonly targetMode?: string;
+}
+/** Rich relationship set with validation and dedup capabilities. */
+export interface RelationshipsState {
+    readonly rels: readonly Relationship[];
+    /** Add a relationship. If a matching (type, target, targetMode) already exists, returns its ID. */
+    add(type: string, target: string, targetMode?: string): string;
+    /** Add with a specific ID. Throws if ID already exists. */
+    addWithId(id: string, type: string, target: string, targetMode?: string): void;
+    /** Find existing relationship by type and target. */
+    findByTypeAndTarget(type: string, target: string): Relationship | undefined;
+    /** Check if an rId is already used. */
+    hasId(id: string): boolean;
+    /** Get count. */
+    count(): number;
+    /** Validate all relationships. Returns error messages (empty = valid). */
+    validate(): string[];
+    /** Render to XML. */
+    render(sink: XmlSink): void;
+}
+/** Create a new empty RelationshipsState. */
+export declare function createRelationships(): RelationshipsState;
+/** Add a relationship and return its assigned rId (free function alias). */
+export declare function addRelationship(state: RelationshipsState, type: string, target: string, targetMode?: string): string;
+/** Add a relationship with a specific ID (free function alias). */
+export declare function addRelationshipWithId(state: RelationshipsState, id: string, type: string, target: string, targetMode?: string): void;
+/** Get the number of relationships (free function alias). */
+export declare function getRelationshipCount(state: RelationshipsState): number;
+/** Render the relationships XML to a sink (free function alias). */
+export declare function renderRelationships(state: RelationshipsState, xml: XmlSink): void;

package/dist/browser/modules/word/writer/relationships.js

@@ -0,0 +1,117 @@
+/**
+ * DOCX Module - Relationship Manager
+ *
+ * Manages OPC relationships for the DOCX package.
+ * Generates .rels files for package-level and part-level relationships.
+ *
+ * Provides both an object-oriented RelationshipsState interface and
+ * backward-compatible free functions (addRelationship, renderRelationships, etc.).
+ */
+import { NS_PKG_RELS, STD_DOC_ATTRIBUTES } from "../constants.js";
+import { DocxWriteError } from "../errors.js";
+/** Create a new empty RelationshipsState. */
+export function createRelationships() {
+    const internal = { _rels: [], _nextId: 1 };
+    const state = {
+        get rels() {
+            return internal._rels;
+        },
+        add(type, target, targetMode) {
+            // Dedup: reuse existing (type, target, targetMode) if found
+            const existing = internal._rels.find(r => r.type === type && r.target === target && r.targetMode === targetMode);
+            if (existing) {
+                return existing.id;
+            }
+            // Generate the next id but skip any value already taken by a
+            // previously registered non-standard id (e.g. round-tripped models
+            // sometimes carry rIds in formats other than "rId<n>", or the same
+            // numeric value was claimed by addWithId before this call).
+            let id = `rId${internal._nextId++}`;
+            while (internal._rels.some(r => r.id === id)) {
+                id = `rId${internal._nextId++}`;
+            }
+            internal._rels.push({ id, type, target, targetMode });
+            return id;
+        },
+        addWithId(id, type, target, targetMode) {
+            if (internal._rels.some(r => r.id === id)) {
+                throw new DocxWriteError(`Relationship ID "${id}" already exists`);
+            }
+            internal._rels.push({ id, type, target, targetMode });
+            // Keep nextId above any manually-assigned numeric IDs. This works for
+            // the common "rId<n>" form; non-standard formats (e.g. "R8") simply
+            // don't advance the counter, but the `add()` path above still skips
+            // collisions defensively.
+            const num = parseInt(id.replace("rId", ""), 10);
+            if (!isNaN(num) && num >= internal._nextId) {
+                internal._nextId = num + 1;
+            }
+        },
+        findByTypeAndTarget(type, target) {
+            return internal._rels.find(r => r.type === type && r.target === target);
+        },
+        hasId(id) {
+            return internal._rels.some(r => r.id === id);
+        },
+        count() {
+            return internal._rels.length;
+        },
+        validate() {
+            const errors = [];
+            // Check duplicate IDs
+            const idSet = new Set();
+            for (const rel of internal._rels) {
+                if (idSet.has(rel.id)) {
+                    errors.push(`Duplicate relationship ID: "${rel.id}"`);
+                }
+                idSet.add(rel.id);
+            }
+            // Check external targets without TargetMode
+            for (const rel of internal._rels) {
+                if ((rel.target.startsWith("http://") ||
+                    rel.target.startsWith("https://") ||
+                    rel.target.startsWith("mailto:")) &&
+                    !rel.targetMode) {
+                    errors.push(`Relationship "${rel.id}" has external target "${rel.target}" but no TargetMode="External"`);
+                }
+            }
+            return errors;
+        },
+        render(sink) {
+            renderRelationships(state, sink);
+        }
+    };
+    return state;
+}
+// =============================================================================
+// Backward-Compatible Free Functions
+// =============================================================================
+/** Add a relationship and return its assigned rId (free function alias). */
+export function addRelationship(state, type, target, targetMode) {
+    return state.add(type, target, targetMode);
+}
+/** Add a relationship with a specific ID (free function alias). */
+export function addRelationshipWithId(state, id, type, target, targetMode) {
+    state.addWithId(id, type, target, targetMode);
+}
+/** Get the number of relationships (free function alias). */
+export function getRelationshipCount(state) {
+    return state.count();
+}
+/** Render the relationships XML to a sink (free function alias). */
+export function renderRelationships(state, xml) {
+    xml.openXml(STD_DOC_ATTRIBUTES);
+    xml.openNode("Relationships", { xmlns: NS_PKG_RELS });
+    for (const rel of state.rels) {
+        const attrs = {
+            Id: rel.id,
+            Type: rel.type,
+            Target: rel.target
+        };
+        if (rel.targetMode) {
+            attrs.TargetMode = rel.targetMode;
+        }
+        xml.leafNode("Relationship", attrs);
+    }
+    xml.closeNode();
+}

package/dist/browser/modules/word/writer/render-context.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Unified rendering context for DOCX XML serialization.
+ * Passed to all writer functions to provide shared state.
+ */
+import type { WordSecurityPolicy } from "../security/policy.js";
+/**
+ * A fully-qualified part name within the package (e.g. "/word/document.xml").
+ * Type alias kept for documentation; functionally identical to `string`.
+ */
+type PartName = string;
+/** ID generators for various document elements. */
+export interface IdGenerators {
+    nextDrawingId(): number;
+    nextSdtId(): number;
+    nextBookmarkId(): number;
+    nextDocPrId(): number;
+    nextChartId(): number;
+    nextImagePartId(): number;
+}
+/**
+ * Lightweight, content-renderer-facing subset of WordRenderContext.
+ *
+ * Most leaf renderers (run/paragraph/table/image) only need the rId remap and
+ * the hyperlink rId map; passing the full WordRenderContext would couple them
+ * to chartRIds/securityPolicy/etc. They take this `RenderHelpers` instead.
+ */
+export interface RenderHelpers {
+    /** See WordRenderContext.imageRIdRemap. */
+    readonly imageRemap?: ReadonlyMap<string, string>;
+    /** See WordRenderContext.hyperlinkRIds. */
+    readonly hyperlinkRIds?: ReadonlyWeakMap<object, string>;
+    /**
+     * Raw XML output policy. Controls how preserved/opaque rawXml fragments
+     * (opaqueRun, opaqueParagraphChild, opaqueDrawing, _advancedFillXml, …)
+     * are emitted. Defaults to `"preserve"` when undefined for backwards
+     * compatibility with callers that built helpers without a context.
+     */
+    readonly rawXmlPolicy?: "preserve" | "strip" | "reject";
+}
+/**
+ * Apply the `rawXmlPolicy` to a single `xml.writeRaw(...)` operation.
+ *
+ * - `"preserve"` (or undefined): write the fragment verbatim.
+ * - `"strip"`: skip writing — the surrounding wrapper element (if any) is
+ *   left empty. This is intentionally conservative: it preserves ZIP/relationship
+ *   integrity even though it may produce a structurally-incomplete element.
+ * - `"reject"`: throw `DocxRawXmlPolicyError` so the caller learns about the
+ *   opaque content instead of silently producing degraded output.
+ *
+ * Importing the error class lazily would create an import cycle; callers that
+ * need to throw should do so themselves. This helper just resolves the action.
+ */
+export type RawXmlAction = "write" | "skip" | "throw";
+export declare function resolveRawXmlAction(policy: "preserve" | "strip" | "reject" | undefined): RawXmlAction;
+/**
+ * Read-only WeakMap projection.
+ * (TS lib doesn't ship one; we mirror the readonly subset of WeakMap.)
+ */
+interface ReadonlyWeakMap<K extends WeakKey, V> {
+    get(key: K): V | undefined;
+    has(key: K): boolean;
+}
+/** Render context passed to all writer functions. */
+export interface WordRenderContext {
+    /** Current part being rendered. */
+    readonly partName: PartName;
+    /** Security policy controlling raw XML, external targets, etc. */
+    readonly securityPolicy: WordSecurityPolicy;
+    /** ID generators (shared across all parts for a single document render). */
+    readonly ids: IdGenerators;
+    /** Raw XML output policy. If "reject", opaque content throws instead of being written. */
+    readonly rawXmlPolicy: "preserve" | "strip" | "reject";
+    /** Chart/ChartEx object → rId mapping. Populated by packager before rendering. */
+    readonly chartRIds: Map<object, string>;
+    /**
+     * Optional remap for image relationship IDs that the packager had to rewrite
+     * (e.g. when the model's image rId collided with a non-image relationship in
+     * the same .rels file). Writers that emit `r:embed` look up this map first
+     * and fall back to the original rId stored on the model. The map is keyed by
+     * the original (model-side) rId.
+     */
+    readonly imageRIdRemap: Map<string, string>;
+    /**
+     * External hyperlink object → rId mapping. The packager registers a
+     * relationship for each hyperlink with a `url` and stores the assigned rId
+     * here, keyed by the hyperlink object identity. The paragraph writer reads
+     * this when emitting `<w:hyperlink r:id="...">` so the model itself is
+     * never mutated.
+     */
+    readonly hyperlinkRIds: WeakMap<object, string>;
+    /**
+     * AltChunk object → rId mapping. Populated by the packager when registering
+     * the relationship for each `w:altChunk`. Renderers prefer this map over
+     * `AltChunk.rId` so the caller's model is never mutated, including when
+     * the altChunk is nested inside a table cell or SDT and was therefore not
+     * cloned by the shallow body copy.
+     */
+    readonly altChunkRIds: WeakMap<object, string>;
+}
+/** Create ID generators with given starting values. */
+export declare function createIdGenerators(startValues?: {
+    drawingId?: number;
+    sdtId?: number;
+    bookmarkId?: number;
+    docPrId?: number;
+    chartId?: number;
+    imagePartId?: number;
+}): IdGenerators;
+/** Create a default render context. */
+export declare function createRenderContext(options?: {
+    partName?: PartName;
+    securityPolicy?: WordSecurityPolicy;
+    chartRIds?: Map<object, string>;
+    imageRIdRemap?: Map<string, string>;
+    hyperlinkRIds?: WeakMap<object, string>;
+    altChunkRIds?: WeakMap<object, string>;
+    /**
+     * Pre-built ID generators. When provided, the caller is responsible for
+     * seeding them (e.g. with the maximum existing SDT id in the document so
+     * auto-assigned IDs don't collide with author-supplied ones).
+     */
+    ids?: IdGenerators;
+}): WordRenderContext;
+export {};

package/dist/browser/modules/word/writer/render-context.js

@@ -0,0 +1,46 @@
+/**
+ * Unified rendering context for DOCX XML serialization.
+ * Passed to all writer functions to provide shared state.
+ */
+import { DEFAULT_SECURITY_POLICY } from "../security/policy.js";
+export function resolveRawXmlAction(policy) {
+    switch (policy) {
+        case "strip":
+            return "skip";
+        case "reject":
+            return "throw";
+        default:
+            return "write";
+    }
+}
+/** Create ID generators with given starting values. */
+export function createIdGenerators(startValues) {
+    let drawingId = startValues?.drawingId ?? 1;
+    let sdtId = startValues?.sdtId ?? 1;
+    let bookmarkId = startValues?.bookmarkId ?? 0;
+    let docPrId = startValues?.docPrId ?? 1;
+    let chartId = startValues?.chartId ?? 1;
+    let imagePartId = startValues?.imagePartId ?? 1;
+    return {
+        nextDrawingId: () => drawingId++,
+        nextSdtId: () => sdtId++,
+        nextBookmarkId: () => bookmarkId++,
+        nextDocPrId: () => docPrId++,
+        nextChartId: () => chartId++,
+        nextImagePartId: () => imagePartId++
+    };
+}
+/** Create a default render context. */
+export function createRenderContext(options) {
+    const securityPolicy = options?.securityPolicy ?? DEFAULT_SECURITY_POLICY;
+    return {
+        partName: options?.partName ?? "/word/document.xml",
+        securityPolicy,
+        ids: options?.ids ?? createIdGenerators(),
+        rawXmlPolicy: securityPolicy.rawXmlPolicy ?? "preserve",
+        chartRIds: options?.chartRIds ?? new Map(),
+        imageRIdRemap: options?.imageRIdRemap ?? new Map(),
+        hyperlinkRIds: options?.hyperlinkRIds ?? new WeakMap(),
+        altChunkRIds: options?.altChunkRIds ?? new WeakMap()
+    };
+}