@cj-tech-master/excelts 9.6.0 → 9.6.1

package/dist/browser/modules/word/security/encryption.js

@@ -20,7 +20,7 @@
  *   - MS-OFFCRYPTO: Office Document Cryptography Structure
  *   - ECMA-376 Part 3: Markup Compatibility and Extensibility
  */
-import { aesCbcDecrypt as aesCbcDecryptPkcs7Sync, aesCbcDecryptRaw as aesCbcDecryptRawSync, aesCbcEncrypt as aesCbcEncryptPkcs7Sync, aesCbcEncryptRaw as aesCbcEncryptRawSync, hash as hashSyncMaybe, hashAsync } from "../../../utils/crypto.browser.js";
+import { aesCbcDecryptRaw as aesCbcDecryptRawSync, aesCbcEncryptRaw as aesCbcEncryptRawSync, hash as hashSyncMaybe, hashAsync } from "../../../utils/crypto.browser.js";
 import { base64ToBytes, bytesToBase64, randomBytes, utf8Decoder, utf8Encoder } from "../core/internal-utils.js";
 import { DocxDecryptionError } from "../errors.js";
 import { readCfb, writeCfb } from "./cfb-reader.js";
@@ -139,15 +139,19 @@ export async function verifyPassword(password, info) {
     try {
         // Derive verifier hash input key
         const verifierInputKey = await deriveEncryptionKey(password, info, AGILE_BLOCK_KEYS.verifierHashInput);
-        // Decrypt the verifier hash input (PKCS#7 padded by encryption write path)
-        const verifierInput = aesCbcPkcs7Decrypt(info.encryptedVerifierHashInput, verifierInputKey, info.keySalt);
-        // Hash the verifier input
+        // Decrypt the verifier hash input. MS-OFFCRYPTO §2.3.4.13 specifies
+        // these blobs are AES-CBC with the plaintext zero-padded to the block
+        // boundary — NOT PKCS#7. Using a PKCS#7 decrypt would mis-strip bytes
+        // and break interop with Word / msoffcrypto.
+        const verifierInput = aesCbcRawDecrypt(info.encryptedVerifierHashInput, verifierInputKey, info.keySalt);
+        // Hash the verifier input. The plaintext is exactly 16 bytes (saltSize),
+        // so trim any zero padding before hashing.
         const hashAlg = mapHashName(info.hashAlgorithm);
-        const computedHash = await hashAsync(hashAlg, verifierInput);
+        const computedHash = await hashAsync(hashAlg, verifierInput.slice(0, info.blockSize));
         // Derive verifier hash value key
         const verifierValueKey = await deriveEncryptionKey(password, info, AGILE_BLOCK_KEYS.verifierHashValue);
-        // Decrypt the verifier hash value (PKCS#7 padded by encryption write path)
-        const expectedHash = aesCbcPkcs7Decrypt(info.encryptedVerifierHashValue, verifierValueKey, info.keySalt);
+        // Decrypt the verifier hash value (zero-padded AES-CBC, see above).
+        const expectedHash = aesCbcRawDecrypt(info.encryptedVerifierHashValue, verifierValueKey, info.keySalt);
         // Compare (truncate to hashSize in case of padding)
         return bytesEqual(computedHash.slice(0, info.hashSize), expectedHash.slice(0, info.hashSize));
     }
@@ -170,8 +174,9 @@ export async function verifyPassword(password, info) {
 export async function decryptPackage(encryptedPackage, info, password, maxDecryptedSize = 512 * 1024 * 1024) {
     // Derive key encryption key
     const keyEncryptionKey = await deriveEncryptionKey(password, info, AGILE_BLOCK_KEYS.encryptedKey);
-    // Decrypt the actual package key (PKCS#7 padded by encryption write path)
-    const packageKey = aesCbcPkcs7Decrypt(info.encryptedKeyValue, keyEncryptionKey, info.keySalt);
+    // Decrypt the actual package key. Zero-padded AES-CBC per MS-OFFCRYPTO
+    // §2.3.4.13 (NOT PKCS#7); the key is exactly keyBits/8 bytes.
+    const packageKey = aesCbcRawDecrypt(info.encryptedKeyValue, keyEncryptionKey, info.keySalt).slice(0, info.keyBits / 8);
     if (encryptedPackage.length < 8) {
         throw new DocxDecryptionError("EncryptedPackage too small (missing 8-byte size header)");
     }
@@ -255,25 +260,18 @@ function getHashSizeFor(hashName) {
     }
 }
 /**
- * Decrypt an AES-CBC blob whose plaintext was written with PKCS#7 padding.
- * Used for the encryptedKeyValue / encryptedVerifierHashInput /
- * encryptedVerifierHashValue blobs. The IV is truncated/extended to 16
- * bytes per the OOXML spec.
+ * Decrypt an AES-CBC blob written with zero padding (no PKCS#7). Used for
+ * the encryptedKeyValue / encryptedVerifierHashInput / encryptedVerifierHashValue
+ * blobs, per MS-OFFCRYPTO §2.3.4.13. The IV is truncated/extended to 16 bytes.
  */
-function aesCbcPkcs7Decrypt(data, key, iv) {
-    return aesCbcDecryptPkcs7Sync(data, key, ivToBlockSize(iv));
-}
-/**
- * Encrypt with AES-CBC + PKCS#7 padding — the Agile spec's standard
- * choice for verifier blobs and the encrypted package key.
- */
-function aesCbcPkcs7Encrypt(data, key, iv) {
-    return aesCbcEncryptPkcs7Sync(data, key, ivToBlockSize(iv));
+function aesCbcRawDecrypt(data, key, iv) {
+    return aesCbcDecryptRawSync(data, key, ivToBlockSize(iv));
 }
 /**
  * Encrypt with AES-CBC and zero-padding (no PKCS#7). Used by package
- * segment encryption: data is already padded to a 16-byte boundary by
- * the caller, and the on-disk format does not include a PKCS#7 trailer.
+ * segment encryption and the verifier / key blobs: data is already padded
+ * to a 16-byte boundary by the caller, and the on-disk format does not
+ * include a PKCS#7 trailer.
  */
 function aesCbcZeroPadEncrypt(data, key, iv) {
     return aesCbcEncryptRawSync(data, key, ivToBlockSize(iv));
@@ -287,12 +285,51 @@ function ivToBlockSize(iv) {
     out.set(iv.slice(0, 16));
     return out;
 }
+/** Right-pad data with zeros so its length is a multiple of `blockSize`. */
+function padToBlock(data, blockSize) {
+    if (data.length % blockSize === 0) {
+        return data;
+    }
+    const out = new Uint8Array(Math.ceil(data.length / blockSize) * blockSize);
+    out.set(data);
+    return out;
+}
 function concat(a, b) {
     const result = new Uint8Array(a.length + b.length);
     result.set(a, 0);
     result.set(b, a.length);
     return result;
 }
+/** HMAC block size (in bytes) for the supported hash algorithms. */
+function hmacBlockSize(hashName) {
+    // SHA-1 / SHA-256 use a 512-bit (64-byte) block; SHA-384 / SHA-512 use a
+    // 1024-bit (128-byte) block.
+    return hashName === "SHA-384" || hashName === "SHA-512" ? 128 : 64;
+}
+/**
+ * Compute HMAC(hashName, key, message) using the generic hash primitive.
+ * Implemented here (rather than in @utils/crypto, which only ships
+ * hmacSha256) so agile encryption can use SHA-512 etc. for the data
+ * integrity HMAC that Word verifies on open.
+ */
+async function hmac(hashName, key, message) {
+    const blockSize = hmacBlockSize(hashName);
+    // Keys longer than the block size are hashed down first.
+    let k = key.length > blockSize ? await hashAsync(hashName, key) : key;
+    if (k.length < blockSize) {
+        const padded = new Uint8Array(blockSize);
+        padded.set(k);
+        k = padded;
+    }
+    const ipad = new Uint8Array(blockSize);
+    const opad = new Uint8Array(blockSize);
+    for (let i = 0; i < blockSize; i++) {
+        ipad[i] = k[i] ^ 0x36;
+        opad[i] = k[i] ^ 0x5c;
+    }
+    const inner = await hashAsync(hashName, concat(ipad, message));
+    return hashAsync(hashName, concat(opad, inner));
+}
 function stringToUtf16LE(s) {
     const buf = new Uint8Array(s.length * 2);
     for (let i = 0; i < s.length; i++) {
@@ -592,17 +629,33 @@ export async function encryptDocx(zipBytes, password, options) {
     const packageKey = randomBytes(keyBytes);
     // 2. Generate key encryption key (for encrypting the package key)
     const keyEncryptionKey = await deriveEncryptionKey(password, { keySalt, spinCount, hashAlgorithm, keyBits }, AGILE_BLOCK_KEYS.encryptedKey);
-    // 3. Encrypt the package key
-    const encryptedKeyValue = aesCbcPkcs7Encrypt(packageKey, keyEncryptionKey, keySalt);
+    // 3. Encrypt the package key. MS-OFFCRYPTO §2.3.4.13: these blobs use
+    //    zero-padded AES-CBC (no PKCS#7). packageKey is already block-aligned.
+    const encryptedKeyValue = aesCbcZeroPadEncrypt(padToBlock(packageKey, blockSize), keyEncryptionKey, keySalt);
     // 4. Generate verifier: random 16 bytes, hash them, encrypt both
     const verifierInput = randomBytes(16);
     const verifierHash = await hashAsync(hashName, verifierInput);
     const verifierInputKey = await deriveEncryptionKey(password, { keySalt, spinCount, hashAlgorithm, keyBits }, AGILE_BLOCK_KEYS.verifierHashInput);
-    const encryptedVerifierHashInput = aesCbcPkcs7Encrypt(verifierInput, verifierInputKey, keySalt);
+    const encryptedVerifierHashInput = aesCbcZeroPadEncrypt(padToBlock(verifierInput, blockSize), verifierInputKey, keySalt);
     const verifierValueKey = await deriveEncryptionKey(password, { keySalt, spinCount, hashAlgorithm, keyBits }, AGILE_BLOCK_KEYS.verifierHashValue);
-    const encryptedVerifierHashValue = aesCbcPkcs7Encrypt(verifierHash, verifierValueKey, keySalt);
+    const encryptedVerifierHashValue = aesCbcZeroPadEncrypt(padToBlock(verifierHash, blockSize), verifierValueKey, keySalt);
     // 5. Encrypt the ZIP data in 4096-byte segments
     const encryptedPackage = await encryptPackageData(zipBytes, packageKey, keySalt, hashName, blockSize);
+    // 5b. Data integrity (MS-OFFCRYPTO §2.3.4.14). Word verifies this HMAC on
+    //     open; an empty or missing value makes it report the file as corrupt.
+    //       - hmacKey: random, hashSize bytes (padded to block size).
+    //       - encryptedHmacKey  = AES-CBC(packageKey, IV0, hmacKey)
+    //       - hmacValue = HMAC(hashAlg, hmacKey, encryptedPackage)  (entire
+    //         stream including the 8-byte size prefix)
+    //       - encryptedHmacValue = AES-CBC(packageKey, IV1, hmacValue)
+    //     IV0 = H(keySalt + blockKeyDataIntegrityKey)[:blockSize]
+    //     IV1 = H(keySalt + blockKeyDataIntegrityValue)[:blockSize]
+    const hmacKey = randomBytes(hashSize);
+    const ivHmacKey = (await hashAsync(hashName, concat(keySalt, AGILE_BLOCK_KEYS.dataIntegrityKey))).slice(0, blockSize);
+    const ivHmacValue = (await hashAsync(hashName, concat(keySalt, AGILE_BLOCK_KEYS.dataIntegrityValue))).slice(0, blockSize);
+    const encryptedHmacKey = aesCbcZeroPadEncrypt(padToBlock(hmacKey, blockSize), packageKey, ivHmacKey);
+    const hmacValue = await hmac(hashName, hmacKey, encryptedPackage);
+    const encryptedHmacValue = aesCbcZeroPadEncrypt(padToBlock(hmacValue, blockSize), packageKey, ivHmacValue);
     // 6. Generate EncryptionInfo XML
     const encInfoXml = buildEncryptionInfoXml({
         keyBits,
@@ -613,7 +666,9 @@ export async function encryptDocx(zipBytes, password, options) {
         keySalt,
         encryptedVerifierHashInput,
         encryptedVerifierHashValue,
-        encryptedKeyValue
+        encryptedKeyValue,
+        encryptedHmacKey,
+        encryptedHmacValue
     });
     // Prepend 8-byte version header: version 4.4 + flags 0x40
     const xmlBytes = utf8Encoder.encode(encInfoXml);
@@ -623,8 +678,12 @@ export async function encryptDocx(zipBytes, password, options) {
     encInfoView.setUint16(2, 4, true); // version minor
     encInfoView.setUint32(4, 0x40, true); // flags (agile)
     encInfoStream.set(xmlBytes, 8);
-    // 7. Package into CFB
+    // 7. Package into CFB.
+    //    Office requires the \x06DataSpaces structure (MS-OFFCRYPTO §2.3.2)
+    //    in addition to EncryptionInfo + EncryptedPackage; without it Word
+    //    rejects the file as corrupt even when the password is correct.
     const cfbBytes = writeCfb([
+        ...buildDataSpacesStreams(),
         { name: "EncryptionInfo", data: encInfoStream },
         { name: "EncryptedPackage", data: encryptedPackage }
     ]);
@@ -633,6 +692,107 @@ export async function encryptDocx(zipBytes, password, options) {
 // =============================================================================
 // Encrypt Helpers
 // =============================================================================
+// -----------------------------------------------------------------------------
+// \x06DataSpaces structure (MS-OFFCRYPTO §2.3.2)
+//
+// Office encrypted documents wrap the EncryptedPackage in a DataSpaces map so
+// the consumer knows which transform (StrongEncryption) was applied. The four
+// streams below are byte-for-byte what Office writes for password-based agile
+// encryption. Word validates this structure on open; omitting it makes the
+// file "corrupt" even with the correct password.
+// -----------------------------------------------------------------------------
+/** Encode a UTF-8 length-prefixed unicode string (UNICODE-LP-P4):
+ *  [4-byte LE byte length of UTF-16LE payload][UTF-16LE chars][pad to 4-byte boundary]. */
+function lengthPrefixedUtf16(str) {
+    const chars = stringToUtf16LE(str);
+    const padded = Math.ceil(chars.length / 4) * 4;
+    const out = new Uint8Array(4 + padded);
+    new DataView(out.buffer).setUint32(0, chars.length, true);
+    out.set(chars, 4);
+    return out;
+}
+/** Concatenate several byte arrays. */
+function concatAll(...parts) {
+    const total = parts.reduce((s, p) => s + p.length, 0);
+    const out = new Uint8Array(total);
+    let off = 0;
+    for (const p of parts) {
+        out.set(p, off);
+        off += p.length;
+    }
+    return out;
+}
+/** Build the four \x06DataSpaces streams Office requires for agile encryption. */
+function buildDataSpacesStreams() {
+    const DATASPACES = "\u0006DataSpaces";
+    // --- Version stream (DataSpaceVersionInfo) ---
+    // FeatureIdentifier "Microsoft.Container.DataSpaces" + reader/updater/writer
+    // version (each major=1, minor=0).
+    const versionStream = concatAll(lengthPrefixedUtf16("Microsoft.Container.DataSpaces"), u16le(1), u16le(0), // reader version
+    u16le(1), u16le(0), // updater version
+    u16le(1), u16le(0) // writer version
+    );
+    // --- DataSpaceMap stream ---
+    // Header: HeaderLength(8) + EntryCount(1) followed by one MapEntry.
+    // MapEntry: EntryLength + ReferenceComponentCount(1) +
+    //           [ReferenceComponent: type(0=stream) + LP name "EncryptedPackage"] +
+    //           LP DataSpaceName "StrongEncryptionDataSpace".
+    const refName = lengthPrefixedUtf16("EncryptedPackage");
+    const dsName = lengthPrefixedUtf16("StrongEncryptionDataSpace");
+    const refComponent = concatAll(u32le(0), refName); // 0 = stream component
+    const mapEntryBody = concatAll(u32le(1), refComponent, dsName); // 1 reference component
+    const entryLength = 4 + mapEntryBody.length; // include the EntryLength field itself
+    const mapEntry = concatAll(u32le(entryLength), mapEntryBody);
+    const dataSpaceMap = concatAll(u32le(8), u32le(1), mapEntry); // headerLen=8, entryCount=1
+    // --- DataSpaceInfo/StrongEncryptionDataSpace stream (DataSpaceDefinition) ---
+    // HeaderLength(8) + TransformReferenceCount(1) + LP transform name.
+    const transformName = lengthPrefixedUtf16("StrongEncryptionTransform");
+    const dataSpaceDefinition = concatAll(u32le(8), u32le(1), transformName);
+    // --- TransformInfo/StrongEncryptionTransform/\x06Primary stream ---
+    // TransformInfoHeader:
+    //   TransformLength + TransformType(1) + LP TransformId +
+    //   LP TransformName + reader/updater/writer versions.
+    // Followed by EncryptionTransformInfo:
+    //   LP EncryptionName + EncryptionBlockSize(4) + CipherMode(4).
+    const transformId = lengthPrefixedUtf16("{FF9A3F03-56EF-4613-BDD5-5A41C1D07246}");
+    const transformNamePrimary = lengthPrefixedUtf16("Microsoft.Container.EncryptionTransform");
+    const headerBody = concatAll(u32le(1), // TransformType = 1
+    transformId, transformNamePrimary, u16le(1), u16le(0), // reader version
+    u16le(1), u16le(0), // updater version
+    u16le(1), u16le(0) // writer version
+    );
+    const transformLength = 4 + headerBody.length; // include the length field itself
+    const transformHeader = concatAll(u32le(transformLength), headerBody);
+    const encryptionTransformInfo = concatAll(lengthPrefixedUtf16(""), // EncryptionName (empty for agile)
+    u32le(0), // EncryptionBlockSize
+    u32le(0) // CipherMode
+    );
+    const primary = concatAll(transformHeader, encryptionTransformInfo);
+    return [
+        { name: "Version", path: [DATASPACES], data: versionStream },
+        { name: "DataSpaceMap", path: [DATASPACES], data: dataSpaceMap },
+        {
+            name: "StrongEncryptionDataSpace",
+            path: [DATASPACES, "DataSpaceInfo"],
+            data: dataSpaceDefinition
+        },
+        {
+            name: "\u0006Primary",
+            path: [DATASPACES, "TransformInfo", "StrongEncryptionTransform"],
+            data: primary
+        }
+    ];
+}
+function u16le(n) {
+    const b = new Uint8Array(2);
+    new DataView(b.buffer).setUint16(0, n, true);
+    return b;
+}
+function u32le(n) {
+    const b = new Uint8Array(4);
+    new DataView(b.buffer).setUint32(0, n, true);
+    return b;
+}
 /**
  * Encrypt the package data in 4096-byte segments.
  *
@@ -674,11 +834,13 @@ async function encryptPackageData(data, packageKey, keySalt, hashName, blockSize
 }
 /** Build the Agile EncryptionInfo XML document. */
 function buildEncryptionInfoXml(params) {
-    const { keyBits, hashAlgorithm, hashSize, spinCount, blockSize, keySalt, encryptedVerifierHashInput, encryptedVerifierHashValue, encryptedKeyValue } = params;
+    const { keyBits, hashAlgorithm, hashSize, spinCount, blockSize, keySalt, encryptedVerifierHashInput, encryptedVerifierHashValue, encryptedKeyValue, encryptedHmacKey, encryptedHmacValue } = params;
     const saltB64 = bytesToBase64(keySalt);
     const vhiB64 = bytesToBase64(encryptedVerifierHashInput);
     const vhvB64 = bytesToBase64(encryptedVerifierHashValue);
     const ekvB64 = bytesToBase64(encryptedKeyValue);
+    const hmacKeyB64 = bytesToBase64(encryptedHmacKey);
+    const hmacValB64 = bytesToBase64(encryptedHmacValue);
     return ('<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\r\n' +
         '<encryption xmlns="http://schemas.microsoft.com/office/2006/encryption" ' +
         'xmlns:p="http://schemas.microsoft.com/office/2006/keyEncryptor/password" ' +
@@ -686,7 +848,7 @@ function buildEncryptionInfoXml(params) {
         `<keyData saltSize="16" blockSize="${blockSize}" keyBits="${keyBits}" ` +
         `hashSize="${hashSize}" cipherAlgorithm="AES" cipherChaining="ChainingModeCBC" ` +
         `hashAlgorithm="${hashAlgorithm}" saltValue="${saltB64}"/>\r\n` +
-        '<dataIntegrity encryptedHmacKey="" encryptedHmacValue=""/>\r\n' +
+        `<dataIntegrity encryptedHmacKey="${hmacKeyB64}" encryptedHmacValue="${hmacValB64}"/>\r\n` +
         "<keyEncryptors>\r\n" +
         '<keyEncryptor uri="http://schemas.microsoft.com/office/2006/keyEncryptor/password">\r\n' +
         `<p:encryptedKey spinCount="${spinCount}" saltSize="16" blockSize="${blockSize}" ` +

package/dist/browser/modules/word/types.d.ts

@@ -991,6 +991,17 @@ export interface TableProperties {
     readonly indent?: Twips;
     /** Table look (conditional formatting). */
     readonly look?: TableLook;
+    /**
+     * Number of rows in a single horizontal banding stripe (`w:tblStyleRowBandSize`).
+     * Defaults to 1 in Word. Set on table styles so the `band1Horz`/`band2Horz`
+     * conditional formats render as visible row banding.
+     */
+    readonly rowBandSize?: number;
+    /**
+     * Number of columns in a single vertical banding stripe (`w:tblStyleColBandSize`).
+     * Defaults to 1 in Word.
+     */
+    readonly colBandSize?: number;
     /** Floating table properties. */
     readonly float?: TableFloat;
     /** Cell spacing in twips. */
@@ -1450,6 +1461,8 @@ export interface DrawingShape {
     readonly noOutline?: boolean;
     /** Text content inside the shape. */
     readonly textContent?: readonly Paragraph[];
+    /** Vertical anchoring of the text body inside the shape (a:bodyPr/@anchor). */
+    readonly textBodyAnchor?: "t" | "ctr" | "b" | "just" | "dist";
     /** Alternative text. */
     readonly altText?: string;
     /** Shape name. */
@@ -1475,6 +1488,10 @@ export interface DrawingShape {
     readonly behindDoc?: boolean;
     /** Rotation in 60,000ths of a degree. */
     readonly rotation?: number;
+    /** Flip the shape horizontally (a:xfrm/@flipH). */
+    readonly flipHorizontal?: boolean;
+    /** Flip the shape vertically (a:xfrm/@flipV). */
+    readonly flipVertical?: boolean;
     /** Raw XML string (for preserving unrecognized shape details on round-trip). */
     readonly rawXml?: string;
     /**

package/dist/browser/modules/word/units.d.ts

@@ -7,10 +7,16 @@
 export declare const TWIPS_PER_INCH = 1440;
 /** Twips per point. */
 export declare const TWIPS_PER_POINT = 20;
-/** Twips per centimeter (approximate). */
-export declare const TWIPS_PER_CM = 567;
-/** Twips per millimeter (approximate). */
-export declare const TWIPS_PER_MM = 56.7;
+/**
+ * Twips per centimeter, derived exactly from 1 inch = 2.54 cm = 1440 twips
+ * (= 566.9291…). Using the exact factor — rather than the rounded 567 — keeps
+ * metric page sizes aligned with their canonical twip values, e.g.
+ * `cmToTwips(21)` → 11906 and `cmToTwips(29.7)` → 16838 (A4), matching
+ * `A4_PAGE_WIDTH` / `A4_PAGE_HEIGHT` in constants.ts.
+ */
+export declare const TWIPS_PER_CM: number;
+/** Twips per millimeter, derived exactly from {@link TWIPS_PER_CM}. */
+export declare const TWIPS_PER_MM: number;
 /** EMU (English Metric Units) per inch — DrawingML coordinate space. */
 export declare const EMU_PER_INCH = 914400;
 /** EMU per centimeter. */

package/dist/browser/modules/word/units.js

@@ -10,10 +10,16 @@
 export const TWIPS_PER_INCH = 1440;
 /** Twips per point. */
 export const TWIPS_PER_POINT = 20;
-/** Twips per centimeter (approximate). */
-export const TWIPS_PER_CM = 567;
-/** Twips per millimeter (approximate). */
-export const TWIPS_PER_MM = 56.7;
+/**
+ * Twips per centimeter, derived exactly from 1 inch = 2.54 cm = 1440 twips
+ * (= 566.9291…). Using the exact factor — rather than the rounded 567 — keeps
+ * metric page sizes aligned with their canonical twip values, e.g.
+ * `cmToTwips(21)` → 11906 and `cmToTwips(29.7)` → 16838 (A4), matching
+ * `A4_PAGE_WIDTH` / `A4_PAGE_HEIGHT` in constants.ts.
+ */
+export const TWIPS_PER_CM = TWIPS_PER_INCH / 2.54;
+/** Twips per millimeter, derived exactly from {@link TWIPS_PER_CM}. */
+export const TWIPS_PER_MM = TWIPS_PER_CM / 10;
 /** EMU (English Metric Units) per inch — DrawingML coordinate space. */
 export const EMU_PER_INCH = 914400;
 /** EMU per centimeter. */

package/dist/browser/modules/word/writer/document-writer.js

@@ -42,6 +42,7 @@ export function renderSdt(xml, sdt, ctx, helpers) {
             ? {
                 imageRemap: ctx.imageRIdRemap,
                 hyperlinkRIds: ctx.hyperlinkRIds,
+                nextDocPrId: ctx.ids.nextDocPrId,
                 rawXmlPolicy: ctx.rawXmlPolicy
             }
             : undefined;
@@ -78,6 +79,7 @@ export function renderBodyContent(xml, content, ctx) {
     const helpers = {
         imageRemap: renderCtx.imageRIdRemap,
         hyperlinkRIds: renderCtx.hyperlinkRIds,
+        nextDocPrId: renderCtx.ids.nextDocPrId,
         rawXmlPolicy: renderCtx.rawXmlPolicy
     };
     switch (content.type) {
@@ -88,7 +90,7 @@ export function renderBodyContent(xml, content, ctx) {
             renderTable(xml, content, helpers);
             break;
         case "floatingImage":
-            renderFloatingImage(xml, content, renderCtx.imageRIdRemap);
+            renderFloatingImage(xml, content, renderCtx.imageRIdRemap, renderCtx.ids.nextDocPrId);
             break;
         case "tableOfContents":
             renderTableOfContents(xml, content);
@@ -103,7 +105,13 @@ export function renderBodyContent(xml, content, ctx) {
             renderSdt(xml, content, renderCtx);
             break;
         case "checkBox":
+            // A checkbox renders as an inline (run-level) SDT whose sdtContent holds
+            // a run. At block level that run would be an illegal child of
+            // CT_SdtContentBlock, so wrap it in a paragraph — making it a valid
+            // run-level SDT inside a block-level paragraph.
+            xml.openNode("w:p");
             renderCheckBox(xml, content);
+            xml.closeNode();
             break;
         case "drawingShape":
             renderDrawingShape(xml, content, renderCtx);
@@ -290,7 +298,17 @@ function renderDrawingShape(xml, shape, ctx) {
     // Shape properties
     xml.openNode("wps:spPr");
     // Transform
-    xml.openNode("a:xfrm", shape.rotation ? { rot: String(shape.rotation) } : {});
+    const xfrmAttrs = {};
+    if (shape.rotation) {
+        xfrmAttrs["rot"] = String(shape.rotation);
+    }
+    if (shape.flipHorizontal) {
+        xfrmAttrs["flipH"] = "1";
+    }
+    if (shape.flipVertical) {
+        xfrmAttrs["flipV"] = "1";
+    }
+    xml.openNode("a:xfrm", Object.keys(xfrmAttrs).length > 0 ? xfrmAttrs : {});
     xml.leafNode("a:off", { x: "0", y: "0" });
     xml.leafNode("a:ext", { cx: String(shape.width), cy: String(shape.height) });
     xml.closeNode(); // a:xfrm
@@ -366,6 +384,7 @@ function renderDrawingShape(xml, shape, ctx) {
             ? {
                 imageRemap: ctx.imageRIdRemap,
                 hyperlinkRIds: ctx.hyperlinkRIds,
+                nextDocPrId: ctx.ids.nextDocPrId,
                 rawXmlPolicy: ctx.rawXmlPolicy
             }
             : undefined;
@@ -375,8 +394,13 @@ function renderDrawingShape(xml, shape, ctx) {
         xml.closeNode(); // w:txbxContent
         xml.closeNode(); // wps:txbx
     }
-    // Body properties (required)
-    xml.leafNode("wps:bodyPr");
+    // Body properties (required). The vertical text anchor lives on a:bodyPr/@anchor.
+    if (shape.textBodyAnchor) {
+        xml.leafNode("wps:bodyPr", { anchor: shape.textBodyAnchor });
+    }
+    else {
+        xml.leafNode("wps:bodyPr");
+    }
     xml.closeNode(); // wps:wsp
     xml.closeNode(); // a:graphicData
     xml.closeNode(); // a:graphic

package/dist/browser/modules/word/writer/docx-packager.js

@@ -91,6 +91,24 @@ function collectHyperlinks(body) {
     });
     return links;
 }
+/**
+ * A minimal valid 1×1 transparent PNG.
+ *
+ * Used as an automatic raster fallback for SVG images that ship without an
+ * explicit `fallbackData`. In OOXML, `a:blip/@r:embed` must reference a raster
+ * image — Microsoft Word does not rasterize an SVG referenced directly by
+ * `a:blip`, so an SVG without a raster fallback renders as a broken/empty
+ * picture. By always pairing the SVG (`asvg:svgBlip`) with a raster blip we
+ * guarantee the drawing is renderable everywhere: SVG-aware Word shows the
+ * vector, older readers show the raster placeholder.
+ */
+const SVG_RASTER_FALLBACK_PNG = Uint8Array.from([
+    0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44, 0x52,
+    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01, 0x08, 0x06, 0x00, 0x00, 0x00, 0x1f, 0x15, 0xc4,
+    0x89, 0x00, 0x00, 0x00, 0x0d, 0x49, 0x44, 0x41, 0x54, 0x78, 0x9c, 0x63, 0x60, 0x00, 0x02, 0x00,
+    0x00, 0x05, 0x00, 0x01, 0xe2, 0x26, 0x05, 0x9b, 0x00, 0x00, 0x00, 0x00, 0x49, 0x45, 0x4e, 0x44,
+    0xae, 0x42, 0x60, 0x82
+]);
 /** Infer a content type for an opaque part based on its file extension. */
 function inferContentType(ext) {
     const map = {
@@ -343,7 +361,12 @@ async function _packageDocxInner(doc, options) {
         };
         for (const img of doc.images) {
             const oldRid = img.rId;
-            if (img.mediaType === "svg" && img.fallbackData) {
+            if (img.mediaType === "svg") {
+                // SVG must always be paired with a raster fallback that `a:blip`
+                // references; Word cannot rasterize an SVG referenced directly by
+                // a:blip. If the caller did not provide one, synthesize a minimal
+                // transparent PNG so the drawing is still valid and renderable.
+                const fallbackData = img.fallbackData ?? SVG_RASTER_FALLBACK_PNG;
                 // Main rId points at the PNG fallback (the raster image consumed by
                 // a:blip).
                 const baseName = img.fileName.replace(/\.[^.]+$/, "");
@@ -359,7 +382,7 @@ async function _packageDocxInner(doc, options) {
                 if (ext) {
                     imageExtensions.add(ext);
                 }
-                svgFallbacks.push({ fallbackFileName, data: img.fallbackData });
+                svgFallbacks.push({ fallbackFileName, data: fallbackData });
             }
             else {
                 registerImageRel(oldRid, `media/${img.fileName}`);
@@ -1164,14 +1187,24 @@ async function _packageDocxInner(doc, options) {
         archive.add(PartPath.Footnotes, 
         // Footnotes are an independent OPC part — their r:id values must
         // resolve against word/_rels/footnotes.xml.rels, not document.xml.rels.
-        renderXml(xml => renderFootnotes(xml, doc.footnotes, { imageRemap: new Map(), hyperlinkRIds, rawXmlPolicy })));
+        renderXml(xml => renderFootnotes(xml, doc.footnotes, {
+            imageRemap: new Map(),
+            hyperlinkRIds,
+            nextDocPrId: renderCtx.ids.nextDocPrId,
+            rawXmlPolicy
+        })));
         if (getRelationshipCount(footnoteRels) > 0) {
             archive.add("word/_rels/footnotes.xml.rels", renderXml(xml => renderRelationships(footnoteRels, xml)));
         }
     }
     // word/endnotes.xml + endnotes.xml.rels
     if (hasEndnotes) {
-        archive.add(PartPath.Endnotes, renderXml(xml => renderEndnotes(xml, doc.endnotes, { imageRemap: new Map(), hyperlinkRIds, rawXmlPolicy })));
+        archive.add(PartPath.Endnotes, renderXml(xml => renderEndnotes(xml, doc.endnotes, {
+            imageRemap: new Map(),
+            hyperlinkRIds,
+            nextDocPrId: renderCtx.ids.nextDocPrId,
+            rawXmlPolicy
+        })));
         if (getRelationshipCount(endnoteRels) > 0) {
             archive.add("word/_rels/endnotes.xml.rels", renderXml(xml => renderRelationships(endnoteRels, xml)));
         }
@@ -1182,7 +1215,12 @@ async function _packageDocxInner(doc, options) {
         // Comments live in their own OPC part; pass helpers so embedded
         // hyperlinks/images render with the right r:id (the rels manager
         // below registered them under their model-original id).
-        renderXml(xml => renderComments(xml, doc.comments, { imageRemap: new Map(), hyperlinkRIds, rawXmlPolicy })));
+        renderXml(xml => renderComments(xml, doc.comments, {
+            imageRemap: new Map(),
+            hyperlinkRIds,
+            nextDocPrId: renderCtx.ids.nextDocPrId,
+            rawXmlPolicy
+        })));
         if (getRelationshipCount(commentRels) > 0) {
             archive.add("word/_rels/comments.xml.rels", renderXml(xml => renderRelationships(commentRels, xml)));
         }
@@ -1207,6 +1245,7 @@ async function _packageDocxInner(doc, options) {
             renderXml(xml => renderHeader(xml, headerDef.content, {
                 imageRemap: new Map(),
                 hyperlinkRIds,
+                nextDocPrId: renderCtx.ids.nextDocPrId,
                 rawXmlPolicy
             })));
             // Header .rels file
@@ -1230,6 +1269,7 @@ async function _packageDocxInner(doc, options) {
             renderXml(xml => renderFooter(xml, footerDef.content, {
                 imageRemap: new Map(),
                 hyperlinkRIds,
+                nextDocPrId: renderCtx.ids.nextDocPrId,
                 rawXmlPolicy
             })));
             // Footer .rels file

package/dist/browser/modules/word/writer/image-writer.d.ts

@@ -7,4 +7,4 @@
 import type { XmlSink } from "../../xml/types.js";
 import type { FloatingImage } from "../types.js";
 /** Render a floating image as a standalone paragraph with wp:anchor. */
-export declare function renderFloatingImage(xml: XmlSink, img: FloatingImage, imageRemap?: ReadonlyMap<string, string>): void;
+export declare function renderFloatingImage(xml: XmlSink, img: FloatingImage, imageRemap?: ReadonlyMap<string, string>, nextDocPrId?: () => number): void;

package/dist/browser/modules/word/writer/image-writer.js

@@ -7,8 +7,8 @@
 import { NS_A, NS_PIC, URI_PIC, NS_ASVG, GUID_SVG } from "../constants.js";
 import { DEFAULT_RELATIVE_HEIGHT, DEFAULT_WRAP_MARGIN_EMU } from "../units.js";
 /** Render a floating image as a standalone paragraph with wp:anchor. */
-export function renderFloatingImage(xml, img, imageRemap) {
-    const drawingId = img.drawingId ?? 1;
+export function renderFloatingImage(xml, img, imageRemap, nextDocPrId) {
+    const drawingId = nextDocPrId?.() ?? img.drawingId ?? 1;
     const name = img.name ?? "Picture";
     // Resolve relationship id used in r:embed via packager-provided remap.
     const embedRId = imageRemap?.get(img.rId) ?? img.rId;

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

@@ -29,6 +29,21 @@ export interface RenderHelpers {
     readonly imageRemap?: ReadonlyMap<string, string>;
     /** See WordRenderContext.hyperlinkRIds. */
     readonly hyperlinkRIds?: ReadonlyWeakMap<object, string>;
+    /**
+     * Allocates the next document-wide unique drawing object id, used for
+     * `wp:docPr/@id` (and the matching `pic:cNvPr/@id` / `wps:cNvPr/@id`).
+     *
+     * Word requires every drawing object id to be a unique positive integer
+     * across the entire document — including body, headers, footers, footnotes,
+     * endnotes, comments and text boxes. The packager seeds a single counter on
+     * the render context and exposes it here so every drawing renderer draws
+     * from the same id space, regardless of what (possibly duplicate or unset)
+     * `drawingId` the model carries.
+     *
+     * When undefined (e.g. a standalone renderer call without a context),
+     * renderers fall back to the model's `drawingId` or `1`.
+     */
+    readonly nextDocPrId?: () => number;
     /**
      * Raw XML output policy. Controls how preserved/opaque rawXml fragments
      * (opaqueRun, opaqueParagraphChild, opaqueDrawing, _advancedFillXml, …)