@syncfusion/ej2-docx 0.0.0-stage → 35.1.40

package/src/features/ole-object/index.js

@@ -0,0 +1,1421 @@
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __values = (this && this.__values) || function (o) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator], i = 0;
+    if (m) return m.call(o);
+    return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+};
+var __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    return ar;
+};
+var __spread = (this && this.__spread) || function () {
+    for (var ar = [], i = 0; i < arguments.length; i++) ar = ar.concat(__read(arguments[i]));
+    return ar;
+};
+export * from './catalog';
+export * from './relationship';
+export * from './typed-dom';
+import { pointToTwips } from '../document/length';
+import { Paragraph } from '../document/paragraph';
+import { FeatureRunParagraphItem } from '../document/text-range';
+import { isWml } from '../document/wml';
+import { DocxError } from '../../core/errors/index';
+import { registerFeatureMaterializeHandler, registerFeatureMultiPartHandler, featureId, registerFeature, registerFeatureRunLeafHandler, } from '../../core/registry/index';
+import { sniffImageContentType } from '../images/image-sniff';
+import { loadOleObjectCatalog, OleObjectCatalog, OLE_OBJECT_DEFAULT_CONTENT_TYPE } from './catalog';
+import { OFFICE_OLE_NAMESPACE, OleDrawAspect, OleLinkType, OleUpdateMode, applyOleDomMutations, oleAttributeValue, parseOleObjectDomState, readDrawAspect, readFieldCodes, readLinkType, readLinkTypeDescription, readLockedField, readObjectId, readOriginalHeight, readOriginalWidth, readProgId, readShapeId, readUpdateMode, resolveOleChild } from './typed-dom';
+/**
+ * @private
+ */
+/**
+ * Feature id for the optional OLE-object module.
+ *
+ * @private
+ */
+export var OLE_OBJECT = featureId('ole-object');
+/**
+ * Transitional relationship type for an embedded/linked OLE object part.
+ * Defined in {@link ./relationship}; re-exported by `export *` above.
+ *
+ * @private
+ */
+import { OLE_OBJECT_RELATIONSHIP_TYPE } from './relationship';
+/**
+ * Typed, editable view over a WordprocessingML embedded/linked OLE object
+ * (`w:object` containing an `o:OLEObject`, `w:objectEmbed`, or
+ * `w:objectLink` child).
+ *
+ * @remarks
+ * **Security — never execute.** The library must never activate, open,
+ * automate, or execute OLE, ActiveX, VBA, scripts, or external content.
+ * Binary payload parts (`word/embeddings/*`) are opaque caller data: the
+ * {@link OleObject.payloadBytes} accessor moves bytes in and out verbatim
+ * and nothing in the module inspects, parses, or launches them. Link
+ * targets are stored strings and are never fetched, resolved, or probed.
+ *
+ * One semantic model over two schema-backed wire encodings (fixed at load;
+ * edits never convert forms):
+ * - `office` — `o:OLEObject` (transitional `vml-officeDrawing.xsd`
+ *   `CT_OLEObject`, ECMA-376-4 §19.2.2.20)
+ * - `wml` — `w:objectEmbed` / `w:objectLink` (transitional `wml.xsd`
+ *   `CT_ObjectEmbed`/`CT_ObjectLink`, ECMA-376-1 §17.3.3.20/§17.3.3.21)
+ *
+ * Setters patch only the modeled attribute/child on the stored element;
+ * every unmodeled sibling attribute/child survives verbatim. `undefined`
+ * clears the modeled member (three-state semantics).
+ *
+ * Schema citations: `w:object` (`CT_Object`, transitional `wml.xsd` line
+ * 1167; ECMA-376-1 §17.3.3.19), `CT_OLEObject` + `ST_OLEType` /
+ * `ST_OLEDrawAspect` / `ST_OLEUpdateMode` / `ST_OLELinkType`
+ * (`vml-officeDrawing.xsd` lines 291/475–493), Office behavior
+ * [MS-OI29500] §2.1.1834 (`ObjectID` unsupported on links, regenerated per
+ * save). Relationship type: `OLE_OBJECT_RELATIONSHIP_TYPE`.
+ *
+ * @private
+ */
+var OleObject = /** @class */ (function () {
+    /** @private */
+    function OleObject(objectElement, oleElement) {
+        /**
+         * @private True when link authoring registered a pending external target
+         * (TASK-8055) that still awaits save-time materialization.
+         */
+        this.pendingLink = false;
+        /**
+         * @private True when icon/preview media authoring registered pending
+         * image bytes (TASK-8056) that still await save-time materialization.
+         */
+        this.pendingIcon = false;
+        var resolved = resolveOleChild(objectElement);
+        if (resolved === undefined || resolved.oleElement !== oleElement) {
+            // Fallback for direct construction (legacy tests): derive the form
+            // from the child element itself.
+            var wireForm = oleElement.namespaceUri === OFFICE_OLE_NAMESPACE ? 'office' : 'wml';
+            this.state = parseOleObjectDomState(objectElement, oleElement, wireForm);
+        }
+        else {
+            this.state = parseOleObjectDomState(objectElement, resolved.oleElement, resolved.wireForm);
+        }
+        this.relationshipIdValue = oleAttributeValue(oleElement, 'http://schemas.openxmlformats.org/officeDocument/2006/relationships', 'id');
+        // TASK-8056: bind icon media from VML `v:imagedata/@r:id` when present
+        // (ECMA-376-4 §19.2.2.20; ECMA-376-1 §15.2.14).
+        this.imageRelationshipIdValue = readImageDataRelationshipId(objectElement);
+    }
+    Object.defineProperty(OleObject.prototype, "wireForm", {
+        /**
+         * Which schema encoding this object's `w:object` carries.
+         *
+         * @private
+         */
+        get: function () {
+            return this.state.wireForm;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(OleObject.prototype, "linkType", {
+        /**
+         * Kind of OLE connection — `embed` (storage part) or `link` (external
+         * target). `undefined` when the stored `@Type` token is unknown
+         * (residual); the WML-native form derives this from
+         * `w:objectEmbed` vs `w:objectLink`.
+         *
+         * @private
+         */
+        get: function () {
+            return readLinkType(this.state);
+        },
+        set: function (value) {
+            this.mutate({ type: value });
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(OleObject.prototype, "progId", {
+        /**
+         * Programmatic identifier (`@ProgID` / `@progId`), e.g.
+         * `'Excel.Sheet.12'` or `'Acrobat.WordDocument.DC'`.
+         *
+         * @private
+         */
+        get: function () {
+            return readProgId(this.state);
+        },
+        set: function (value) {
+            this.mutate({ progId: value });
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(OleObject.prototype, "shapeId", {
+        /**
+         * Placeholder shape id (`@ShapeID` / `@shapeId`) — the `v:shape` this
+         * object is visually bound to.
+         *
+         * @private
+         */
+        get: function () {
+            return readShapeId(this.state);
+        },
+        set: function (value) {
+            this.mutate({ shapeId: value });
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(OleObject.prototype, "drawAspect", {
+        /**
+         * Visual representation (`@DrawAspect` / `@drawAspect`): `content`
+         * (render object content) or `icon` (placeholder icon).
+         * `undefined` = not set / unparseable residual.
+         *
+         * @private
+         */
+        get: function () {
+            return readDrawAspect(this.state);
+        },
+        set: function (value) {
+            this.mutate({ drawAspect: value });
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(OleObject.prototype, "objectId", {
+        /**
+         * Embedded-object unique id (`@ObjectID`, office form only — the
+         * WML-native form has no counterpart). Office regenerates this per save
+         * and does not support it on linked objects ([MS-OI29500] §2.1.1834).
+         *
+         * @private
+         */
+        get: function () {
+            return readObjectId(this.state);
+        },
+        set: function (value) {
+            this.mutate({ objectId: value });
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(OleObject.prototype, "updateMode", {
+        /**
+         * Link refresh mode (`@UpdateMode` / `@updateMode`): `always` or
+         * `onCall`. Meaningful for linked objects.
+         *
+         * @private
+         */
+        get: function () {
+            return readUpdateMode(this.state);
+        },
+        set: function (value) {
+            this.mutate({ updateMode: value });
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(OleObject.prototype, "lockedField", {
+        /**
+         * Whether the linked object's appearance is locked
+         * (`o:LockedField` child / `@lockedField`). `undefined` = absent.
+         *
+         * @private
+         */
+        get: function () {
+            return readLockedField(this.state);
+        },
+        set: function (value) {
+            this.mutate({ lockedField: value });
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(OleObject.prototype, "linkTypeDescription", {
+        /**
+         * `o:LinkType` child value (office form only) — e.g.
+         * `'EnhancedMetaFile'`, `'Bitmap'` (`ST_OLELinkType` is an open string).
+         *
+         * @private
+         */
+        get: function () {
+            return readLinkTypeDescription(this.state);
+        },
+        set: function (value) {
+            this.mutate({ linkTypeDescription: value });
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(OleObject.prototype, "fieldCodes", {
+        /**
+         * Stored LINK-field switches (`o:FieldCodes` child / `@fieldCodes`),
+         * e.g. `'\\f 0'`. Stored verbatim; never interpreted.
+         *
+         * @private
+         */
+        get: function () {
+            return readFieldCodes(this.state);
+        },
+        set: function (value) {
+            this.mutate({ fieldCodes: value });
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(OleObject.prototype, "originalWidth", {
+        /**
+         * Original placeholder width from `w:object/@dxaOrig` (points;
+         * wire is `ST_TwipsMeasure`).
+         *
+         * @private
+         */
+        get: function () {
+            return readOriginalWidth(this.state);
+        },
+        set: function (value) {
+            this.mutate({
+                originalWidth: value,
+            });
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(OleObject.prototype, "originalHeight", {
+        /**
+         * Original placeholder height from `w:object/@dyaOrig` (points;
+         * wire is `ST_TwipsMeasure`).
+         *
+         * @private
+         */
+        get: function () {
+            return readOriginalHeight(this.state);
+        },
+        set: function (value) {
+            this.mutate({
+                originalHeight: value,
+            });
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(OleObject.prototype, "linked", {
+        /**
+         * `true` when the object is linked (`@Type` = `Link`, or the WML-native
+         * `w:objectLink` form); otherwise treated as embedded.
+         *
+         * @private
+         */
+        get: function () {
+            return readLinkType(this.state) === OleLinkType.Link;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(OleObject.prototype, "linkTarget", {
+        /**
+         * External link target string for linked objects (Main-WordDocument oleObject
+         * relationship with `TargetMode="External"`).
+         *
+         * **Get** returns the pending target registered by
+         * {@link Paragraph.appendOleObject} before the first save, otherwise the
+         * catalog target bound to `relationshipId`. `undefined` for embeds and
+         * when no external relationship is bound.
+         *
+         * **Security — strings only.** The value is a stored path/URI string and is
+         * never fetched, resolved, probed, opened, or executed
+         * (`.agent/policies/security.md`). Callers that need network or filesystem
+         * access must do so outside this library.
+         *
+         * @private
+         */
+        get: function () {
+            if (readLinkType(this.state) !== OleLinkType.Link) {
+                return undefined;
+            }
+            var relationshipIdValue = this.relationshipIdValue;
+            var catalog = this.lookUpCatalog();
+            if (relationshipIdValue !== undefined &&
+                relationshipIdValue.length > 0 &&
+                catalog !== undefined) {
+                var target = catalog.targetForRelationship(relationshipIdValue);
+                if (target !== undefined) {
+                    return target;
+                }
+            }
+            if (this.pendingLink && catalog !== undefined) {
+                return catalog.pendingTargetFor(this);
+            }
+            return undefined;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(OleObject.prototype, "relationshipId", {
+        /**
+         * Raw relationship id from `@r:id`, when present. Empty until a pending
+         * authored embed or link is materialized at save (images `Image`
+         * pattern).
+         *
+         * @private
+         */
+        get: function () {
+            return this.relationshipIdValue;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(OleObject.prototype, "imageRelationshipId", {
+        /**
+         * Image relationship id from `v:imagedata/@r:id` (TASK-8056 icon/preview
+         * media). Empty until a pending authored icon is materialized at save.
+         *
+         * @private
+         */
+        get: function () {
+            return this.imageRelationshipIdValue;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(OleObject.prototype, "previewImageBytes", {
+        /**
+         * Icon/preview image bytes (TASK-8056) — PNG or JPEG only.
+         *
+         * **Get** returns pending icon bytes registered by
+         * {@link Paragraph.appendOleObject} before the first save, otherwise the
+         * catalog icon bytes bound to `imageRelationshipId`. `undefined` when no
+         * icon/preview media is attached. Bytes are copied defensively. The library
+         * never renders, executes, or activates the image
+         * (`.agent/policies/security.md`).
+         *
+         * @private
+         */
+        get: function () {
+            var catalog = this.lookUpCatalog();
+            if (this.pendingIcon && catalog !== undefined) {
+                var pending_1 = catalog.pendingIconBytesFor(this);
+                if (pending_1 !== undefined) {
+                    return copyBytes(pending_1);
+                }
+            }
+            var imageRelationshipIdValue = this.imageRelationshipIdValue;
+            if (imageRelationshipIdValue !== undefined &&
+                imageRelationshipIdValue.length > 0 &&
+                catalog !== undefined) {
+                var bytes = catalog.iconBytesForRelationship(imageRelationshipIdValue);
+                if (bytes !== undefined) {
+                    return copyBytes(bytes);
+                }
+            }
+            return undefined;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(OleObject.prototype, "payloadBytes", {
+        /**
+         * Embedded payload bytes — GO program decision Q1 (option A).
+         *
+         * **Get** returns the embedded object's stored bytes: the pending bytes
+         * registered by {@link Paragraph.appendOleObject} before the first save,
+         * otherwise the catalog bytes bound to `relationshipId`. `undefined` for
+         * linked objects (no part exists) and when the embedding part is missing.
+         * The library never interprets these bytes — they are caller data
+         * (`.agent/policies/security.md`); any sandboxing decision is the caller's.
+         *
+         * **Set** replaces the payload bytes byte-for-byte: on pending embeds
+         * (registered bytes swap) and on loaded embeddings (catalog entry marked
+         * dirty; save rewrites the part). Removing bytes (`undefined`) is not
+         * supported — detach by removing the owning run instead. The bytes are
+         * copied defensively on both paths.
+         *
+         * @throws DocxError `content/invalid-ole-object` when setting empty bytes
+         * or bytes on a linked object, or when the owning document (and therefore
+         * its catalog) is unavailable for a loaded-object write.
+         *
+         * @private
+         */
+        get: function () {
+            if (readLinkType(this.state) === OleLinkType.Link) {
+                return undefined;
+            }
+            // Catalog-authoritative for materialized objects; pending registration
+            // covers the pre-save window (allocated bytes may differ from what the
+            // catalog ends up writing — the catalog entry is the source of truth).
+            var relationshipIdValue = this.relationshipIdValue;
+            var catalog = this.lookUpCatalog();
+            if (relationshipIdValue !== undefined &&
+                relationshipIdValue.length > 0 &&
+                catalog !== undefined) {
+                var bytes = catalog.bytesForRelationship(relationshipIdValue);
+                if (bytes !== undefined) {
+                    return copyBytes(bytes);
+                }
+            }
+            if (this.pendingPayload !== undefined) {
+                return copyBytes(this.pendingPayload.bytes);
+            }
+            return undefined;
+        },
+        set: function (value) {
+            if (value === undefined) {
+                throw new DocxError('content/invalid-ole-object', 'OleObject payloadBytes cannot be cleared; remove the owning run instead');
+            }
+            if (value.byteLength === 0) {
+                throw new DocxError('content/invalid-ole-object', 'OleObject payload bytes must not be empty');
+            }
+            if (readLinkType(this.state) === OleLinkType.Link) {
+                throw new DocxError('content/invalid-ole-object', 'OleObject payloadBytes is only available on embedded objects');
+            }
+            var copy = copyBytes(value);
+            if (this.pendingPayload !== undefined) {
+                this.pendingPayload = __assign({}, this.pendingPayload, { bytes: copy });
+                // Mirror into the catalog registration so materialization writes the
+                // replacement bytes (catalog entry is the save-time source of truth).
+                var catalog_1 = this.lookUpCatalog();
+                if (catalog_1 !== undefined) {
+                    catalog_1.updatePendingBytes(this, copy);
+                }
+                return;
+            }
+            var relationshipIdValue = this.relationshipIdValue;
+            var catalog = this.lookUpCatalog();
+            if (relationshipIdValue === undefined ||
+                relationshipIdValue.length === 0 ||
+                catalog === undefined) {
+                throw new DocxError('content/invalid-ole-object', 'OleObject has no embedding part to replace (not yet saved and no pending payload)');
+            }
+            catalog.replaceBytes(relationshipIdValue, copy);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    /**
+     * Returns the original `w:object` element with modeled edits applied
+     * (unmodeled attributes/children stay byte-identical).
+     *
+     * @private
+     */
+    OleObject.prototype.toOpenXml = function () {
+        return this.state.element;
+    };
+    /**
+     * Whether the authored embed or link still awaits save-time
+     * materialization. True between {@link Paragraph.appendOleObject} and the
+     * first {@link WordDocument.saveSync} (or {@link WordDocument.save}).
+     *
+     * @private
+     */
+    OleObject.prototype.isPendingRelationship = function () {
+        return this.pendingPayload !== undefined || this.pendingLink;
+    };
+    /**
+     * Bind the materialized relationship id after catalog allocation.
+     * Patches `@r:id` on the stored `o:OLEObject`/`w:object*` element
+     * (patch-in-place: only the id value changes; prefix/position preserved).
+     *
+     * @private
+     */
+    OleObject.prototype.resolveRelationshipId = function (relationshipId) {
+        this.relationshipIdValue = relationshipId;
+        this.pendingPayload = undefined;
+        this.pendingLink = false;
+        // Patch r:id without disturbing anything else on the element.
+        this.state = withRelationshipId(this.state, relationshipId);
+    };
+    /**
+     * Register pending embed bytes + content type (authoring path).
+     *
+     * @private
+     */
+    OleObject.prototype.registerPendingPayload = function (bytes, contentType) {
+        this.pendingPayload = { bytes: copyBytes(bytes), contentType: contentType };
+        this.pendingLink = false;
+    };
+    /**
+     * Mark this object as a pending external link (authoring path).
+     * The target string lives on the catalog registration.
+     *
+     * @private
+     */
+    OleObject.prototype.registerPendingLinkTarget = function () {
+        this.pendingLink = true;
+        this.pendingPayload = undefined;
+    };
+    /**
+     * Whether authored icon/preview media still awaits save-time
+     * materialization (TASK-8056; {@link PendingIconHost}).
+     *
+     * @private
+     */
+    OleObject.prototype.isPendingIcon = function () {
+        return this.pendingIcon;
+    };
+    /**
+     * Bind the materialized image relationship id after catalog icon
+     * allocation. Patches `v:imagedata/@r:id` (TASK-8056).
+     *
+     * @private
+     */
+    OleObject.prototype.resolveIconRelationshipId = function (relationshipId) {
+        this.imageRelationshipIdValue = relationshipId;
+        this.pendingIcon = false;
+        this.state = withImageDataRelationshipId(this.state, relationshipId);
+    };
+    /**
+     * Mark this object as carrying pending icon/preview media (authoring
+     * path). Bytes live on the catalog registration.
+     *
+     * @private
+     */
+    OleObject.prototype.registerPendingIconMedia = function () {
+        this.pendingIcon = true;
+    };
+    /** Pending content type for catalog mirroring. @private */
+    OleObject.prototype.pendingContentType = function () {
+        return this.pendingPayload == null ? undefined : this.pendingPayload.contentType;
+    };
+    /**
+     * Look up the owning document's OLE catalog, `undefined` when detached or
+     * the feature was not registered at load (authored documents always have
+     * it because `appendOleObject` resolved one to register the payload).
+     *
+     * @private
+     */
+    OleObject.prototype.lookUpCatalog = function () {
+        var document = this.owningDocumentOf();
+        if (document === undefined) {
+            return undefined;
+        }
+        var part = document.featurePart(OLE_OBJECT);
+        return part instanceof OleObjectCatalog ? part : undefined;
+    };
+    /**
+     * Resolve the owning document through the stored element's host run —
+     * tracked by the module when the leaf was bound to a run (authoring) or
+     * parsed under a catalog-active load. Walks up nothing structural: the
+     * catalog contact point is registered at load/append time (see
+     * `bindHostDocument`).
+     *
+     * @private
+     */
+    OleObject.prototype.owningDocumentOf = function () {
+        return hostDocumentOf(this);
+    };
+    /**
+     * Apply one modeled mutation in a single structural pass (patch-in-place).
+     * Invalid enum values throw `DocxError('content/invalid-ole-object')`;
+     * non-positive sizes likewise.
+     */
+    OleObject.prototype.mutate = function (mutations) {
+        var __ts33_0;
+        this.state = applyOleDomMutations(this.state, mutations);
+        this.relationshipIdValue = ((__ts33_0 = oleAttributeValue(this.state.oleElement, 'http://schemas.openxmlformats.org/officeDocument/2006/relationships', 'id')), __ts33_0 != null ? __ts33_0 : this.relationshipIdValue);
+    };
+    return OleObject;
+}());
+export { OleObject };
+/** Defensive byte copy (spec: payloadBytes copies on get/set). */
+function copyBytes(bytes) {
+    var out = new Uint8Array(bytes.byteLength);
+    out.set(bytes);
+    return out;
+}
+/**
+ * Replace `@r:id` on the OLE child of a state, cloning once and keeping
+ * every other attribute/child byte-identical (materialization-time patch;
+ * the attribute exists from authoring with an empty value).
+ */
+function withRelationshipId(state, relationshipId) {
+    var R_NAMESPACE = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships';
+    var element = state.element;
+    var oleIndex = element.children.findIndex(function (c) { return c.kind === 'element' &&
+        (c === state.oleElement ||
+            (c.namespaceUri === state.oleElement.namespaceUri &&
+                c.localName === state.oleElement.localName)); });
+    if (oleIndex < 0) {
+        return state;
+    }
+    var ole = element.children[oleIndex];
+    if (ole === undefined || ole.kind !== 'element') {
+        return state;
+    }
+    var attributes = ole.attributes.map(function (a) { return a.namespaceUri === R_NAMESPACE && a.localName === 'id'
+        ? __assign({}, a, { value: relationshipId }) : a; });
+    var nextOle = __assign({}, ole, { attributes: attributes });
+    var nextElement = __assign({}, element, { children: element.children.map(function (c, i) { return (i === oleIndex ? nextOle : c); }) });
+    return { element: nextElement, oleElement: nextOle, wireForm: state.wireForm };
+}
+/** VML namespace for `v:shape` / `v:imagedata` (ECMA-376-4 Part 4). */
+var VML_NAMESPACE_URI = 'urn:schemas-microsoft-com:vml';
+/** Relationships namespace used by `r:id` on OLE and imagedata. */
+var R_NAMESPACE_URI = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships';
+/**
+ * Read `v:imagedata/@r:id` from a `w:object` element when present
+ * (TASK-8056 load path).
+ */
+function readImageDataRelationshipId(objectElement) {
+    var e_1, _a, e_2, _b;
+    try {
+        for (var _c = __values(objectElement.children), _d = _c.next(); !_d.done; _d = _c.next()) {
+            var child = _d.value;
+            if (child.kind !== 'element' ||
+                child.namespaceUri !== VML_NAMESPACE_URI ||
+                child.localName !== 'shape') {
+                continue;
+            }
+            try {
+                for (var _e = __values(child.children), _f = _e.next(); !_f.done; _f = _e.next()) {
+                    var shapeChild = _f.value;
+                    if (shapeChild.kind !== 'element' ||
+                        shapeChild.namespaceUri !== VML_NAMESPACE_URI ||
+                        shapeChild.localName !== 'imagedata') {
+                        continue;
+                    }
+                    var id = oleAttributeValue(shapeChild, R_NAMESPACE_URI, 'id');
+                    if (id !== undefined && id.length > 0) {
+                        return id;
+                    }
+                }
+            }
+            catch (e_2_1) { e_2 = { error: e_2_1 }; }
+            finally {
+                try {
+                    if (_f && !_f.done && (_b = _e.return)) _b.call(_e);
+                }
+                finally { if (e_2) throw e_2.error; }
+            }
+        }
+    }
+    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+    finally {
+        try {
+            if (_d && !_d.done && (_a = _c.return)) _a.call(_c);
+        }
+        finally { if (e_1) throw e_1.error; }
+    }
+    return undefined;
+}
+/**
+ * Replace `v:imagedata/@r:id` on the shape child of a state, cloning once
+ * and keeping every other attribute/child byte-identical (materialization-
+ * time icon patch; the attribute exists from authoring with an empty value
+ * when icon bytes were supplied).
+ */
+function withImageDataRelationshipId(state, relationshipId) {
+    var e_3, _a;
+    var element = state.element;
+    var shapeIndex = -1;
+    var shape;
+    for (var i = 0; i < element.children.length; i++) {
+        var child = element.children[i];
+        if (child !== undefined &&
+            child.kind === 'element' &&
+            child.namespaceUri === VML_NAMESPACE_URI &&
+            child.localName === 'shape') {
+            shapeIndex = i;
+            shape = child;
+            break;
+        }
+    }
+    if (shape === undefined) {
+        return state;
+    }
+    var imageDataIndex = -1;
+    var imageData;
+    for (var i = 0; i < shape.children.length; i++) {
+        var child = shape.children[i];
+        if (child !== undefined &&
+            child.kind === 'element' &&
+            child.namespaceUri === VML_NAMESPACE_URI &&
+            child.localName === 'imagedata') {
+            imageDataIndex = i;
+            imageData = child;
+            break;
+        }
+    }
+    if (imageData === undefined) {
+        return state;
+    }
+    var hasId = imageData.attributes.some(function (a) { return a.namespaceUri === R_NAMESPACE_URI && a.localName === 'id'; });
+    var attributes = hasId
+        ? imageData.attributes.map(function (a) { return a.namespaceUri === R_NAMESPACE_URI && a.localName === 'id'
+            ? __assign({}, a, { value: relationshipId }) : a; })
+        : __spread(imageData.attributes, [
+            {
+                namespaceUri: R_NAMESPACE_URI,
+                prefix: 'r',
+                localName: 'id',
+                value: relationshipId,
+            },
+        ]);
+    var nextImageData = __assign({}, imageData, { attributes: attributes });
+    var nextShape = __assign({}, shape, { children: shape.children.map(function (c, i) { return (i === imageDataIndex ? nextImageData : c); }) });
+    var nextElement = __assign({}, element, { children: element.children.map(function (c, i) { return (i === shapeIndex ? nextShape : c); }) });
+    // oleElement reference stays valid when it is not the shape index.
+    var nextOle = state.oleElement;
+    if (state.oleElement === shape) {
+        nextOle = nextShape;
+    }
+    else {
+        try {
+            for (var _b = __values(nextElement.children), _c = _b.next(); !_c.done; _c = _b.next()) {
+                var child = _c.value;
+                if (child.kind === 'element' &&
+                    child.namespaceUri === state.oleElement.namespaceUri &&
+                    child.localName === state.oleElement.localName) {
+                    nextOle = child;
+                    break;
+                }
+            }
+        }
+        catch (e_3_1) { e_3 = { error: e_3_1 }; }
+        finally {
+            try {
+                if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+            }
+            finally { if (e_3) throw e_3.error; }
+        }
+    }
+    return { element: nextElement, oleElement: nextOle, wireForm: state.wireForm };
+}
+/**
+ * Host-document contact point for OLE leaves. Authored leaves bind their
+ * owning document at append; loaded leaves bind during body parse while the
+ * document's feature parts are visible (module-level WeakMap, keyed by the
+ * leaf instance).
+ */
+var hostDocuments = new WeakMap();
+/** @private Bind a leaf to its owning document (load + authoring paths). */
+function bindHostDocument(object, document) {
+    hostDocuments.set(object, document);
+}
+/** @private Host document of a leaf, when bound. */
+function hostDocumentOf(object) {
+    return hostDocuments.get(object);
+}
+function parseOleObject(element) {
+    if (!isWml(element, 'object')) {
+        return undefined;
+    }
+    var resolved = resolveOleChild(element);
+    if (resolved === undefined) {
+        return undefined;
+    }
+    return new OleObject(element, resolved.oleElement);
+}
+var registered = false;
+/** @private Test hook */
+export function resetOleObjectFeatureForTests() {
+    registered = false;
+}
+/**
+ * Register the OLE-object run-leaf handler. Idempotent.
+ *
+ * @private
+ */
+export function registerOleObjectFeature() {
+    if (registered) {
+        return;
+    }
+    registered = true;
+    registerFeature({ id: OLE_OBJECT });
+    registerFeatureMultiPartHandler({
+        featureId: OLE_OBJECT,
+        relationshipTypes: [OLE_OBJECT_RELATIONSHIP_TYPE],
+        loadParts: function (pkg, ctx) {
+            return loadOleObjectCatalog(pkg, ctx.mainPartName);
+        },
+    });
+    registerFeatureMaterializeHandler({
+        featureId: OLE_OBJECT,
+        materialize: function (document) {
+            var part = document.featurePart(OLE_OBJECT);
+            if (part instanceof OleObjectCatalog) {
+                part.materializePending(document, oleObjectsInDocument(document));
+            }
+        },
+    });
+    registerFeatureRunLeafHandler({
+        featureId: OLE_OBJECT,
+        wmlLocalName: 'object',
+        tryParse: parseOleObject,
+    });
+}
+/**
+ * Whether a run leaf is a modeled OLE object from this module.
+ *
+ * @private
+ */
+export function isOleObjectLeaf(item) {
+    return item instanceof FeatureRunParagraphItem && item.featureId === OLE_OBJECT && item.value instanceof OleObject;
+}
+function oleObjectsFromLeaves(items) {
+    var e_4, _a;
+    var found = [];
+    try {
+        for (var items_1 = __values(items), items_1_1 = items_1.next(); !items_1_1.done; items_1_1 = items_1.next()) {
+            var item = items_1_1.value;
+            if (isOleObjectLeaf(item)) {
+                found.push(item.value);
+            }
+        }
+    }
+    catch (e_4_1) { e_4 = { error: e_4_1 }; }
+    finally {
+        try {
+            if (items_1_1 && !items_1_1.done && (_a = items_1.return)) _a.call(items_1);
+        }
+        finally { if (e_4) throw e_4.error; }
+    }
+    return found;
+}
+/**
+ * OLE objects in a paragraph, in document order. Also refreshes the
+ * host-document binding used by {@link OleObject.payloadBytes}.
+ *
+ * @private
+ */
+export function oleObjectsInParagraph(paragraph) {
+    return oleObjectsFromLeaves(paragraph.items.toArray());
+}
+/**
+ * OLE objects in the Main Document body, in document order. Also refreshes
+ * the host-document binding used by {@link OleObject.payloadBytes}.
+ *
+ * @private
+ */
+export function oleObjectsInDocument(document) {
+    var e_5, _a, e_6, _b;
+    var found = [];
+    try {
+        for (var _c = __values(document.listBlocks()), _d = _c.next(); !_d.done; _d = _c.next()) {
+            var block = _d.value;
+            if (block.type !== 'paragraph') {
+                continue;
+            }
+            try {
+                for (var _e = __values(oleObjectsInParagraph(block.paragraph)), _f = _e.next(); !_f.done; _f = _e.next()) {
+                    var object = _f.value;
+                    bindHostDocument(object, document);
+                    found.push(object);
+                }
+            }
+            catch (e_6_1) { e_6 = { error: e_6_1 }; }
+            finally {
+                try {
+                    if (_f && !_f.done && (_b = _e.return)) _b.call(_e);
+                }
+                finally { if (e_6) throw e_6.error; }
+            }
+        }
+    }
+    catch (e_5_1) { e_5 = { error: e_5_1 }; }
+    finally {
+        try {
+            if (_d && !_d.done && (_a = _c.return)) _a.call(_c);
+        }
+        finally { if (e_5) throw e_5.error; }
+    }
+    return found;
+}
+// ---------------------------------------------------------------------------
+// Authoring (TASK-8054): appendOleObject embed path
+// ---------------------------------------------------------------------------
+/** ObjectID upper bound ([MS-OI29500] §2.1.1834: `_<0..2147483647>`). */
+var OBJECT_ID_MAX = 2147483647;
+/** Shape id counter (module-local; Word uses `_x0000_i1026`-style tokens). */
+var nextShapeIndex = 1026;
+/** Anchor id counter (`w14:anchorId`, drawing-module precedent). */
+var nextAnchorId = 0x5fe19563;
+/**
+ * Validate one authoring option set and resolve the modeled values.
+ *
+ * @throws DocxError `content/invalid-ole-object` on any invalid input
+ * (missing/empty `progId`, missing payload/target, link-only fields on
+ * embed, non-positive size, non-finite numbers).
+ */
+function resolveAuthoringInput(options) {
+    var progId = options.progId;
+    if (typeof progId !== 'string' || progId.length === 0) {
+        throw new DocxError('content/invalid-ole-object', 'appendOleObject requires a non-empty progId (e.g. "Excel.Sheet.12")');
+    }
+    var hasBytes = options.bytes !== undefined;
+    var hasLinkTarget = typeof options.linkTarget === 'string' && options.linkTarget.length > 0;
+    var linkOnlySupplied = options.updateMode !== undefined ||
+        options.lockedField !== undefined ||
+        options.fieldCodes !== undefined ||
+        options.linkTypeDescription !== undefined;
+    var kind;
+    if (options.linkType === OleLinkType.Link) {
+        kind = 'link';
+    }
+    else if (options.linkType === OleLinkType.Embed) {
+        kind = 'embed';
+    }
+    else if (hasLinkTarget && !hasBytes) {
+        kind = 'link';
+    }
+    else {
+        kind = 'embed';
+    }
+    if (kind === 'embed' && linkOnlySupplied) {
+        throw new DocxError('content/invalid-ole-object', 'updateMode, lockedField, fieldCodes, and linkTypeDescription apply only to linked OLE objects');
+    }
+    if (kind === 'embed' && hasLinkTarget) {
+        throw new DocxError('content/invalid-ole-object', 'linkTarget applies only to linked OLE objects');
+    }
+    if (kind === 'link' && hasBytes) {
+        throw new DocxError('content/invalid-ole-object', 'payload bytes apply only to embedded OLE objects; linked objects store an external target string only');
+    }
+    var width = positivePointsOrThrow('width', options.width != null ? options.width : 72);
+    var height = positivePointsOrThrow('height', options.height != null ? options.height : 72);
+    // DrawAspect follows displayAsIcon only (program GO Q3) — iconBytes alone
+    // never forces Icon.
+    var drawAspect = options.displayAsIcon === true ? OleDrawAspect.Icon : OleDrawAspect.Content;
+    var iconBytes;
+    var iconContentType;
+    if (options.iconBytes !== undefined) {
+        var rawIcon = options.iconBytes;
+        if (!(rawIcon instanceof Uint8Array) || rawIcon.byteLength === 0) {
+            throw new DocxError('content/invalid-ole-object', 'appendOleObject iconBytes must be a non-empty PNG or JPEG byte sequence');
+        }
+        var sniffed = sniffImageContentType(rawIcon);
+        if (sniffed === undefined) {
+            throw new DocxError('content/invalid-ole-object', 'appendOleObject iconBytes must sniff as image/png or image/jpeg');
+        }
+        iconBytes = copyBytes(rawIcon);
+        iconContentType = sniffed;
+    }
+    var common = {
+        progId: progId,
+        width: width,
+        height: height,
+        drawAspect: drawAspect,
+        name: options.name,
+        description: options.description,
+        iconBytes: iconBytes,
+        iconContentType: iconContentType,
+    };
+    if (kind === 'link') {
+        var linkTarget = options.linkTarget;
+        if (typeof linkTarget !== 'string' || linkTarget.length === 0) {
+            throw new DocxError('content/invalid-ole-object', 'appendOleObject link path requires a non-empty linkTarget string');
+        }
+        // Typed as OleUpdateMode; only Always | OnCall are valid public values.
+        var updateMode = options.updateMode === OleUpdateMode.OnCall
+            ? OleUpdateMode.OnCall
+            : OleUpdateMode.Always;
+        return __assign({ kind: 'link' }, common, { linkTarget: linkTarget,
+            updateMode: updateMode, lockedField: options.lockedField, fieldCodes: options.fieldCodes, linkTypeDescription: options.linkTypeDescription });
+    }
+    var bytes = options.bytes;
+    if (!(bytes instanceof Uint8Array) || bytes.byteLength === 0) {
+        throw new DocxError('content/invalid-ole-object', 'appendOleObject embed requires non-empty bytes for the embedded object');
+    }
+    return __assign({ kind: 'embed' }, common, { bytes: bytes, contentType: options.contentType != null ? options.contentType : OLE_OBJECT_DEFAULT_CONTENT_TYPE });
+}
+/** Validate a positive finite point measure for authoring (wire convert later). */
+function positivePointsOrThrow(name, value) {
+    var asNumber = value;
+    if (typeof asNumber !== 'number' || !Number.isFinite(asNumber)) {
+        throw new DocxError('content/invalid-ole-object', "OleObject " + name + " must be a finite point value");
+    }
+    if (asNumber < 0) {
+        throw new DocxError('content/invalid-ole-object', "OleObject " + name + " must be a positive point value");
+    }
+    // Reject values that would serialize to a non-positive twips measure.
+    if (pointToTwips(value) <= 0) {
+        throw new DocxError('content/invalid-ole-object', "OleObject " + name + " must be a positive point value");
+    }
+    return value;
+}
+/** Next `_<0..2147483647>` ObjectID ([MS-OI29500] §2.1.1834 format). */
+function allocateObjectId() {
+    // Deterministic-per-process counter in the Word format; Office regenerates
+    // this value on every save, so stability across runs is not required.
+    nextObjectIdValue = (nextObjectIdValue + 1) % (OBJECT_ID_MAX + 1);
+    return "_" + String(nextObjectIdValue);
+}
+var nextObjectIdValue = 1850929220 % OBJECT_ID_MAX;
+/** Next `_x0000_i{N}` shape id token (Word's conventional VML naming). */
+function allocateShapeId() {
+    var id = "_x0000_i" + String(nextShapeIndex);
+    nextShapeIndex += 1;
+    return id;
+}
+/** Next `w14:anchorId` token (8 uppercase hex digits, drawing precedent). */
+function allocateAnchorId() {
+    nextAnchorId = (nextAnchorId + 1) % 0xffffffff;
+    var hex = nextAnchorId.toString(16).toUpperCase();
+    return hex.length >= 8 ? hex : new Array(8 - hex.length + 1).join('0') + hex;
+}
+/** `style="width:{pt}pt;height:{pt}pt"` for the authored `v:shape` (points in, points out). */
+function shapeStyle(widthPoints, heightPoints) {
+    return "width:" + formatPointsForStyle(widthPoints) + "pt;height:" + formatPointsForStyle(heightPoints) + "pt";
+}
+/** Points → VML style number text (2-decimal round, drop trailing .0). */
+function formatPointsForStyle(points) {
+    var rounded = Math.round(points * 100) / 100;
+    return Number.isInteger(rounded) ? String(rounded) : String(rounded);
+}
+/** Element in a namespace with a prefix. */
+function el(namespaceUri, prefix, localName, attributes, children, namespaceDeclarations) {
+    if (children === void 0) { children = []; }
+    if (namespaceDeclarations === void 0) { namespaceDeclarations = []; }
+    return {
+        kind: 'element',
+        namespaceUri: namespaceUri,
+        prefix: prefix,
+        localName: localName,
+        attributes: attributes,
+        namespaceDeclarations: __spread(namespaceDeclarations),
+        children: children,
+    };
+}
+/**
+ * Build the authored `w:object` subtree per the ECMA-376-4 §19.2.2.20
+ * example-2 template (program GO decision Q2: always the VML
+ * `o:OLEObject` form — Word's current output):
+ *
+ * ```xml
+ * <w:object w:dxaOrig="…" w:dyaOrig="…" w14:anchorId="…">
+ *   <v:shape id="_x0000_iNNNN" type="#_x0000_t75" style="width:…pt;height:…pt"
+ *            o:ole="" alt="…">
+ *     <v:imagedata/>  <!-- only when icon bytes exist (TASK-8056) -->
+ *   </v:shape>
+ *   <o:OLEObject Type="Embed|Link" ProgID="…" ShapeID="…" DrawAspect="…"
+ *                [UpdateMode="Always|OnCall"] [ObjectID="_…"] r:id="rIdN">
+ *     [o:LinkType][o:LockedField][o:FieldCodes]  <!-- link children order -->
+ *   </o:OLEObject>
+ * </w:object>
+ * ```
+ *
+ * `ShapeID` is shared between `v:shape/@id` and `o:OLEObject/@ShapeID`;
+ * the placeholder shape carries the `o:ole=""` marker. Embeds carry the
+ * Office-required minimum attribute set (`r:id`/`ObjectID`/`ProgID`/
+ * `ShapeID`, [MS-OI29500] §2.1.1834). Links omit `ObjectID` (same clause —
+ * unsupported on linked objects) and emit required `UpdateMode`. `r:id` is
+ * empty here and written at materialization.
+ */
+function buildAuthoredOleObjectElement(resolved) {
+    var shapeId = allocateShapeId();
+    var VML_NAMESPACE = 'urn:schemas-microsoft-com:vml';
+    var W14_NAMESPACE = 'http://schemas.microsoft.com/office/word/2010/wordml';
+    var R_NAMESPACE = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships';
+    // TS 3.3 does not narrow discriminated unions through a boolean local.
+    var shapeAttributes = [
+        { namespaceUri: '', prefix: '', localName: 'id', value: shapeId },
+        { namespaceUri: '', prefix: '', localName: 'type', value: '#_x0000_t75' },
+        {
+            namespaceUri: '',
+            prefix: '',
+            localName: 'style',
+            value: shapeStyle(resolved.width, resolved.height),
+        },
+        // The OLE placeholder marker (§19.2.2.20 example 2: `o:ole=""`).
+        { namespaceUri: OFFICE_OLE_NAMESPACE, prefix: 'o', localName: 'ole', value: '' },
+    ];
+    if (resolved.name !== undefined) {
+        shapeAttributes.push({ namespaceUri: '', prefix: '', localName: 'alt', value: resolved.name });
+    }
+    if (resolved.description !== undefined) {
+        shapeAttributes.push({
+            namespaceUri: '',
+            prefix: '',
+            localName: 'title',
+            value: resolved.description,
+        });
+    }
+    // v:imagedata only when icon bytes exist (TASK-8056; ECMA-376-4 §19.2.2.20).
+    // r:id is empty here and patched at materialization (same pattern as OLE r:id).
+    var shapeChildren = [];
+    if (resolved.iconBytes !== undefined && resolved.iconContentType !== undefined) {
+        var imageDataAttributes = [
+            { namespaceUri: R_NAMESPACE, prefix: 'r', localName: 'id', value: '' },
+        ];
+        if (resolved.description !== undefined) {
+            imageDataAttributes.push({
+                namespaceUri: OFFICE_OLE_NAMESPACE,
+                prefix: 'o',
+                localName: 'title',
+                value: resolved.description,
+            });
+        }
+        shapeChildren.push(el(VML_NAMESPACE, 'v', 'imagedata', imageDataAttributes));
+    }
+    var shape = el(VML_NAMESPACE, 'v', 'shape', shapeAttributes, shapeChildren);
+    // o:OLEObject attributes in schema declaration order: Type, ProgID,
+    // ShapeID, DrawAspect, ObjectID (embed), UpdateMode (link), r:id.
+    var oleAttributes = [
+        { namespaceUri: '', prefix: '', localName: 'Type', value: resolved.kind === 'link' ? 'Link' : 'Embed' },
+        { namespaceUri: '', prefix: '', localName: 'ProgID', value: resolved.progId },
+        { namespaceUri: '', prefix: '', localName: 'ShapeID', value: shapeId },
+        {
+            namespaceUri: '',
+            prefix: '',
+            localName: 'DrawAspect',
+            value: resolved.drawAspect === OleDrawAspect.Icon ? 'Icon' : 'Content',
+        },
+    ];
+    if (resolved.kind === 'link') {
+        // CT_ObjectLink / CT_OLEObject required UpdateMode on linked objects.
+        oleAttributes.push({
+            namespaceUri: '',
+            prefix: '',
+            localName: 'UpdateMode',
+            value: resolved.updateMode === OleUpdateMode.OnCall ? 'OnCall' : 'Always',
+        });
+    }
+    else {
+        // ObjectID is embed-only ([MS-OI29500] §2.1.1834 — unsupported on links).
+        oleAttributes.push({
+            namespaceUri: '',
+            prefix: '',
+            localName: 'ObjectID',
+            value: allocateObjectId(),
+        });
+    }
+    oleAttributes.push({ namespaceUri: R_NAMESPACE, prefix: 'r', localName: 'id', value: '' });
+    // Office children in CT_OLEObject sequence: LinkType → LockedField → FieldCodes.
+    var oleChildren = [];
+    if (resolved.kind === 'link') {
+        if (typeof resolved.linkTypeDescription === 'string') {
+            oleChildren.push(el(OFFICE_OLE_NAMESPACE, 'o', 'LinkType', [], [
+                { kind: 'text', value: resolved.linkTypeDescription },
+            ]));
+        }
+        if (resolved.lockedField !== undefined) {
+            oleChildren.push(el(OFFICE_OLE_NAMESPACE, 'o', 'LockedField', [], [
+                { kind: 'text', value: resolved.lockedField ? 't' : 'f' },
+            ]));
+        }
+        if (typeof resolved.fieldCodes === 'string') {
+            oleChildren.push(el(OFFICE_OLE_NAMESPACE, 'o', 'FieldCodes', [], [
+                { kind: 'text', value: resolved.fieldCodes },
+            ]));
+        }
+    }
+    var oleElement = el(OFFICE_OLE_NAMESPACE, 'o', 'OLEObject', oleAttributes, oleChildren);
+    var element = el(WML_TRANSITIONAL, 'w', 'object', [
+        {
+            namespaceUri: WML_TRANSITIONAL,
+            prefix: 'w',
+            localName: 'dxaOrig',
+            value: String(pointToTwips(resolved.width)),
+        },
+        {
+            namespaceUri: WML_TRANSITIONAL,
+            prefix: 'w',
+            localName: 'dyaOrig',
+            value: String(pointToTwips(resolved.height)),
+        },
+        {
+            namespaceUri: W14_NAMESPACE,
+            prefix: 'w14',
+            localName: 'anchorId',
+            value: allocateAnchorId(),
+        },
+    ], [shape, oleElement], 
+    // The authored tree declares the namespaces it uses (Word writes these
+    // on the root; a local declaration keeps the subtree well-formed when
+    // the host document lacks them).
+    [
+        { prefix: 'w14', namespaceUri: W14_NAMESPACE },
+        { prefix: 'v', namespaceUri: VML_NAMESPACE },
+        { prefix: 'o', namespaceUri: OFFICE_OLE_NAMESPACE },
+        { prefix: 'r', namespaceUri: R_NAMESPACE },
+    ]);
+    return { element: element, oleElement: oleElement, shapeId: shapeId };
+}
+/** Transitional WML namespace (local constant to avoid a core cycle). */
+var WML_TRANSITIONAL = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
+/**
+ * Resolve the owning document's OLE catalog for authoring.
+ *
+ * @throws DocxError `feature/not-registered` when the OLE module was not
+ * registered before the document was loaded/created (authored path is
+ * impossible without the catalog).
+ */
+function catalogForAuthoring(paragraph) {
+    var document = paragraph.owningDocument();
+    var part = document.featurePart(OLE_OBJECT);
+    if (part === undefined || !(part instanceof OleObjectCatalog)) {
+        throw new DocxError('feature/not-registered', 'OLE object catalog was not loaded; call registerOleObjectFeature() before WordDocument.open');
+    }
+    return part;
+}
+/**
+ * Author one embedded or linked OLE object and append it to the paragraph
+ * (receiver-owns R2.1; one statement R3.2).
+ *
+ * **Embed path (TASK-8054):** registers payload bytes with the document
+ * catalog at append (pending-relationship pattern, images/ink precedent);
+ * the embedding part `word/embeddings/oleObject{N}.bin`, its main-document
+ * relationship, and the content-type Override are allocated at save.
+ *
+ * **Link path (TASK-8055):** registers an external target string only —
+ * no package part. Save allocates a Main-WordDocument oleObject relationship
+ * with `TargetMode="External"` using the transitional relationship type
+ * (never the Office 2019 long-path type). The target is **never fetched
+ * or opened** (`.agent/policies/security.md`).
+ *
+ * Returns the created {@link OleObject} view (`relationshipId` empty until
+ * the first save materializes it).
+ *
+ * @example
+ * ```ts
+ * // Embed
+ * const embedded = paragraph.appendOleObject({
+ *   progId: 'Excel.Sheet.12',
+ *   bytes: workbookBytes,
+ *   width: (75.35),
+ *   height: (49.4),
+ *   displayAsIcon: true,
+ * });
+ *
+ * // Link (external target string only — never fetched)
+ * const linked = paragraph.appendOleObject({
+ *   progId: 'Excel.Sheet.12',
+ *   linkTarget: 'C:\\\\Data\\\\report.xlsx',
+ *   updateMode: OleUpdateMode.OnCall,
+ *   lockedField: true,
+ *   fieldCodes: '\\\\f 0',
+ *   displayAsIcon: true,
+ * });
+ * ```
+ *
+ * @throws DocxError `content/invalid-ole-object` on invalid options
+ * (missing `progId`, missing payload/target, link-only fields on embed,
+ * non-positive size).
+ * @throws DocxError `feature/not-registered` when the module is not
+ * registered before load.
+ * @throws DetachedObjectError when the paragraph is not in a document.
+ *
+ * @private
+ */
+export function appendOleObjectToParagraph(paragraph, options) {
+    var resolved = resolveAuthoringInput(options);
+    var catalog = catalogForAuthoring(paragraph);
+    var authored = buildAuthoredOleObjectElement(resolved);
+    var object = new OleObject(authored.element, authored.oleElement);
+    bindHostDocument(object, paragraph.owningDocument());
+    if (resolved.kind === 'link') {
+        // Target is a stored string only — catalog never fetches or opens it.
+        object.registerPendingLinkTarget();
+        catalog.registerPendingLink(object, resolved.linkTarget);
+    }
+    else {
+        object.registerPendingPayload(resolved.bytes, resolved.contentType);
+        catalog.registerPendingEmbed(object, resolved.bytes, resolved.contentType);
+    }
+    // TASK-8056: pending icon media (PNG/JPEG only; already sniffed).
+    if (resolved.iconBytes !== undefined && resolved.iconContentType !== undefined) {
+        object.registerPendingIconMedia();
+        catalog.registerPendingIcon(object, resolved.iconBytes, resolved.iconContentType);
+    }
+    paragraph.appendFeatureRunItem(OLE_OBJECT, object);
+    return object;
+}
+/**
+ * Remove an OLE object run from its paragraph and drop the embedding part
+ * or external link relationship on the next save (GC parity with
+ * `paragraph.appendFeatureRunItem(OLE_OBJECT, object
+ * this paragraph.
+ *
+ * @private
+ */
+export function removeOleObject(document, paragraph, object) {
+    var e_7, _a;
+    try {
+        for (var _b = __values(paragraph.items), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var item = _c.value;
+            if (isOleObjectLeaf(item) && item.value === object) {
+                paragraph.removeFeatureRunItem(object);
+                var catalog = documentOleCatalog(document);
+                if (catalog !== undefined) {
+                    if (object.isPendingRelationship()) {
+                        if (object.linked) {
+                            catalog.discardPendingLink(object);
+                        }
+                        else {
+                            catalog.discardPendingEmbed(object);
+                        }
+                    }
+                    else if (object.relationshipId !== undefined && object.relationshipId.length > 0) {
+                        catalog.removeEntry(object.relationshipId);
+                    }
+                    // TASK-8056: drop pending or materialized icon media with the object.
+                    if (object.isPendingIcon()) {
+                        catalog.discardPendingIcon(object);
+                    }
+                    else {
+                        var imageRelationshipId = object.imageRelationshipId;
+                        if (imageRelationshipId !== undefined && imageRelationshipId.length > 0) {
+                            catalog.removeIconEntry(imageRelationshipId);
+                        }
+                    }
+                }
+                return;
+            }
+        }
+    }
+    catch (e_7_1) { e_7 = { error: e_7_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+        }
+        finally { if (e_7) throw e_7.error; }
+    }
+    throw new DocxError('content/invalid-ole-object', 'OLE object is not in this paragraph');
+}
+/** Catalog of a loaded document, `undefined` when the feature is absent. */
+function documentOleCatalog(document) {
+    var part = document.featurePart(OLE_OBJECT);
+    return part instanceof OleObjectCatalog ? part : undefined;
+}
+/**
+ * Package catalog for a loaded document.
+ *
+ * @throws DocxError `feature/not-registered` when the module was not
+ * registered before load.
+ *
+ * @private
+ */
+export function oleObjectCatalog(document) {
+    var catalog = documentOleCatalog(document);
+    if (catalog === undefined) {
+        throw new DocxError('feature/not-registered', 'OLE object catalog was not loaded; call registerOleObjectFeature() before WordDocument.open');
+    }
+    return catalog;
+}
+Paragraph.prototype.appendOleObject = function (options) {
+    return appendOleObjectToParagraph(this, options);
+};
+registerOleObjectFeature();