@docx4j/core-ts 0.1.5 → 0.2.1

package/dist/office-js/run.d.mts

@@ -1,17 +1,27 @@
 import type { WordprocessingMLPackage } from '../packages/WordprocessingMLPackage.mjs';
 import { Document, type RunOptions } from './document.mjs';
 import { type PendingSink } from './proxy.mjs';
+import type { Shimmed } from './shimmed.mjs';
 export type { RunOptions };
+/** The `Document` as the shim presents it (CR-002 section 22.1): `context.document`'s type. */
+export type ShimmedDocument = Shimmed<Document>;
 /** Office JS's `context.trackedObjects`: object lifetime is the garbage collector's business here. */
 export interface TrackedObjects {
     add<T>(object: T): T;
     remove<T>(object: T): T;
 }
-/** A subset of Office JS `Word.RequestContext` over a package. */
+/**
+ * A subset of Office JS `Word.RequestContext` over a package.
+ *
+ * `document` is typed `ShimmedDocument`, which is what the proxies actually present: every array a
+ * `Collection` with `items` and `getFirst`, every object `load`able (CR-002 section 22.1). The
+ * runtime object is the same either way; the type is what lets an add-in script type-check against
+ * this package exactly as it does against Office JS.
+ */
 export declare class RequestContext implements PendingSink {
     /** The package this context is over (extension: Office JS has a host document). */
     readonly package_: WordprocessingMLPackage;
-    readonly document: Document;
+    readonly document: ShimmedDocument;
     /** Tracking is a no-op: nothing here is a remote proxy. */
     readonly trackedObjects: TrackedObjects;
     private pending;

package/dist/office-js/run.mjs

@@ -7,7 +7,14 @@
 import { Document } from './document.mjs';
 import { EXTRA_MEMBERS } from './extras.mjs';
 import { Wrapper, unwrap } from './proxy.mjs';
-/** A subset of Office JS `Word.RequestContext` over a package. */
+/**
+ * A subset of Office JS `Word.RequestContext` over a package.
+ *
+ * `document` is typed `ShimmedDocument`, which is what the proxies actually present: every array a
+ * `Collection` with `items` and `getFirst`, every object `load`able (CR-002 section 22.1). The
+ * runtime object is the same either way; the type is what lets an add-in script type-check against
+ * this package exactly as it does against Office JS.
+ */
 export class RequestContext {
     constructor(
     /** The package this context is over (extension: Office JS has a host document). */

package/dist/office-js/shimmed.d.mts

@@ -0,0 +1,46 @@
+import type { ClientResult, Collection } from './proxy.mjs';
+/** Office JS's `load` / `track` / `untrack`, which every proxy answers and which return the object. */
+export interface Loadable<T> {
+    /**
+     * Office JS's `load`: a no-op here, since the tree is in memory and nothing is a remote proxy
+     * (CR-002 section 3.10). Returns the object, so `body.load('text')` chains as it does in Word.
+     */
+    load(option?: string | string[] | Record<string, unknown>): T;
+    track(): T;
+    untrack(): T;
+}
+/**
+ * What the shim presents for a value of type `T`:
+ *
+ * - a function becomes a function whose result is shimmed in turn (a method call on a proxy hands
+ *   back another proxy), except that a promise stays a promise and a `ClientResult` stays one;
+ * - an array becomes a `Collection` of shimmed items - Office JS's `items`, `getFirst`,
+ *   `getFirstOrNullObject`, `getLast`, `getLastOrNullObject` and `getCount`;
+ * - any other object becomes itself with its members shimmed, plus `load`, `track` and `untrack`;
+ * - a primitive is itself.
+ *
+ * Deliberately **not** distributive over unions of objects beyond the array case: a `Range | undefined`
+ * shims to `Shimmed<Range> | undefined`, which is what a caller wants, and the conditional's natural
+ * distribution gives that.
+ */
+export type Shimmed<T> = T extends ClientResult<unknown> ? T : T extends Promise<unknown> ? T : T extends (...args: infer A) => infer R ? ((...args: A) => Shimmed<R>) & Loadable<T> : T extends readonly (infer I)[] ? ShimmedCollection<I> : T extends object ? ShimmedObject<T> : T;
+/** A collection of shimmed items, as the proxies wrap an array. */
+export type ShimmedCollection<I> = Collection<Shimmed<I>> & Loadable<Collection<Shimmed<I>>>;
+/**
+ * An object with every member shimmed, and Office JS's `load` / `track` / `untrack` beside them.
+ *
+ * `T &` matters and is not redundant: a mapped type keeps only the public members, so without it a
+ * shimmed `Body` is not assignable to `Body` and a consumer cannot pass `context.document.body` to
+ * its own function typed on the plain view - which is exactly what an add-in that shares one `edit`
+ * between Word and the shim does (`examples/office-addin/taskpane.ts`). Intersecting keeps that
+ * assignable while the mapped half still narrows an array member to a `Collection`.
+ *
+ * The **order** matters too, and is the subtler half: an intersection of two call signatures is an
+ * overload set, and TypeScript picks the first that matches. With `T` first, `getRange()` resolves
+ * to `T`'s own signature and hands back a plain `Range`, so `paragraph.getRange().font.load(...)`
+ * is rejected although the shim allows it. The mapped half therefore comes first, so the shimmed
+ * return type wins, and `T` follows to keep assignability.
+ */
+export type ShimmedObject<T> = {
+    [K in keyof T]: Shimmed<T[K]>;
+} & T & Loadable<T>;

package/dist/office-js/shimmed.mjs

@@ -0,0 +1 @@
+export {};

package/dist/opc/exceptions.d.mts

@@ -45,3 +45,28 @@ export declare class Xlsx4jException extends Docx4JException {
 export declare class PartUnrecognisedException extends Docx4JException {
     constructor(message: string);
 }
+/**
+ * An XML part that could not be unmarshalled, naming the part (CR-002 section 27, item 9 of the
+ * E4 release). The runtime's own message is specific about *what* is wrong and, since
+ * `@docx4j/jsonix` 3.4.0, *where* - `w:sz/@w:val (line 12): Argument [NaN] must be an integer` -
+ * but it cannot know which part it was reading, and a person editing a part's XML in an editor needs
+ * that first. The location fields are lifted off the runtime's error so a caller does not have to
+ * parse the message.
+ */
+export declare class PartUnmarshalException extends Docx4JException {
+    /** The part being unmarshalled: `/word/styles.xml`. */
+    readonly partName: string;
+    constructor(message: string, 
+    /** The part being unmarshalled: `/word/styles.xml`. */
+    partName: string, options?: {
+        cause?: unknown;
+        /** The element or attribute the runtime was on, when it said. */
+        location?: string | undefined;
+        /** Its line in the source, when the parser supplied one (Node only: xmldom's locator). */
+        line?: number | undefined;
+        column?: number | undefined;
+    });
+    readonly location: string | undefined;
+    readonly line: number | undefined;
+    readonly column: number | undefined;
+}

package/dist/opc/exceptions.mjs

@@ -58,3 +58,23 @@ export class PartUnrecognisedException extends Docx4JException {
         this.name = 'PartUnrecognisedException';
     }
 }
+/**
+ * An XML part that could not be unmarshalled, naming the part (CR-002 section 27, item 9 of the
+ * E4 release). The runtime's own message is specific about *what* is wrong and, since
+ * `@docx4j/jsonix` 3.4.0, *where* - `w:sz/@w:val (line 12): Argument [NaN] must be an integer` -
+ * but it cannot know which part it was reading, and a person editing a part's XML in an editor needs
+ * that first. The location fields are lifted off the runtime's error so a caller does not have to
+ * parse the message.
+ */
+export class PartUnmarshalException extends Docx4JException {
+    constructor(message, 
+    /** The part being unmarshalled: `/word/styles.xml`. */
+    partName, options) {
+        super(message, { cause: options === null || options === void 0 ? void 0 : options.cause });
+        this.partName = partName;
+        this.name = 'PartUnmarshalException';
+        this.location = options === null || options === void 0 ? void 0 : options.location;
+        this.line = options === null || options === void 0 ? void 0 : options.line;
+        this.column = options === null || options === void 0 ? void 0 : options.column;
+    }
+}

package/dist/opc/index.d.mts

@@ -8,5 +8,5 @@ export { loadPackage, type LoadOptions } from './Load.mjs';
 export { savePackage } from './Save.mjs';
 export { mcePreprocess, createMcePreprocessor, resolveAlternateContent, MCE_NS, type McePreprocessOptions } from './mce/preprocessor.mjs';
 export { UNDERSTOOD_NAMESPACES } from './mce/understood.mjs';
-export { Docx4JException, InvalidFormatException, PartUnrecognisedException, CyclicStylesException, PropertyResolverNotCreatedException } from './exceptions.mjs';
+export { Docx4JException, InvalidFormatException, PartUnrecognisedException, PartUnmarshalException, CyclicStylesException, PropertyResolverNotCreatedException } from './exceptions.mjs';
 export { parseXml, serializeXml, serializeXmlPart, createDocument, encodeText, decodeXmlText, stripXmlDeclaration, base64Encode, base64Decode, childElements, XML_DECLARATION } from '../xml/dom.mjs';

package/dist/opc/index.mjs

@@ -9,5 +9,5 @@ export { loadPackage } from './Load.mjs';
 export { savePackage } from './Save.mjs';
 export { mcePreprocess, createMcePreprocessor, resolveAlternateContent, MCE_NS } from './mce/preprocessor.mjs';
 export { UNDERSTOOD_NAMESPACES } from './mce/understood.mjs';
-export { Docx4JException, InvalidFormatException, PartUnrecognisedException, CyclicStylesException, PropertyResolverNotCreatedException } from './exceptions.mjs';
+export { Docx4JException, InvalidFormatException, PartUnrecognisedException, PartUnmarshalException, CyclicStylesException, PropertyResolverNotCreatedException } from './exceptions.mjs';
 export { parseXml, serializeXml, serializeXmlPart, createDocument, encodeText, decodeXmlText, stripXmlDeclaration, base64Encode, base64Decode, childElements, XML_DECLARATION } from '../xml/dom.mjs';

package/dist/opc/mce/understood.mjs

@@ -1,17 +1,21 @@
-// The namespaces the object model has modules for: what "understanding" an mc:Choice means here.
-// Mirrors the defaultElementNamespaceURI of every generated module of @docx4j/generated-objects-ts
-// (0.1.0); regenerate when modules are added. Word takes the first mc:Choice whose Requires
-// prefixes it all understands (ECMA-376 Part 3, 10.2.1), and so does this preprocessor.
+// What "understanding" an mc:Choice means here: the namespaces whose content survives a load and
+// a save. Word takes the first mc:Choice whose Requires prefixes it all understands (ECMA-376
+// Part 3, 10.2.1), and so does this preprocessor.
+//
+// It is the defaultElementNamespaceURI of every generated module of @docx4j/generated-objects-ts
+// (0.3.0), which `mce.test.mjs` asserts so that the next regeneration announces an addition, plus
+// two groups of hand-kept entries, each marked below: namespaces no module *defaults* to but which
+// the model binds anyway (attributes, or elements a module of another namespace declares), and the
+// slicer namespaces of CR-004 phase B, whose content the model does not bind at all but carries
+// through as DOM.
 export const UNDERSTOOD_NAMESPACES = new Set([
     'http://schemas.openxmlformats.org/wordprocessingml/2006/main',
-    'http://schemas.openxmlformats.org/officeDocument/2006/relationships',
     'http://schemas.openxmlformats.org/package/2006/relationships',
     'http://schemas.openxmlformats.org/markup-compatibility/2006',
     'http://schemas.openxmlformats.org/officeDocument/2006/math',
     'http://schemas.openxmlformats.org/officeDocument/2006/bibliography',
     'http://schemas.openxmlformats.org/officeDocument/2006/customXml',
     'http://schemas.openxmlformats.org/schemaLibrary/2006/main',
-    'http://schemas.openxmlformats.org/officeDocument/2006/custom-properties',
     'http://schemas.openxmlformats.org/officeDocument/2006/extended-properties',
     'http://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes',
     'http://schemas.openxmlformats.org/package/2006/metadata/core-properties',
@@ -36,7 +40,6 @@ export const UNDERSTOOD_NAMESPACES = new Set([
     'http://schemas.microsoft.com/office/drawing/2010/diagram',
     'http://schemas.microsoft.com/office/drawing/2012/main',
     'http://schemas.microsoft.com/office/drawing/2012/chart',
-    'http://schemas.microsoft.com/office/drawing/2012/chartStyle',
     'http://schemas.microsoft.com/office/drawing/2013/main/command',
     'http://schemas.microsoft.com/office/drawing/2014/main',
     'http://schemas.microsoft.com/office/drawing/2014/chart',
@@ -44,7 +47,6 @@ export const UNDERSTOOD_NAMESPACES = new Set([
     'http://schemas.microsoft.com/office/drawing/2014/chartex',
     'http://schemas.microsoft.com/office/drawing/2016/11/main',
     'http://schemas.microsoft.com/office/drawing/2016/12/diagram',
-    'http://schemas.microsoft.com/office/drawing/2016/ink',
     'http://schemas.microsoft.com/office/drawing/2016/SVG/main',
     'http://schemas.microsoft.com/office/drawing/2017/03/chart',
     'http://schemas.microsoft.com/office/drawing/2017/decorative',
@@ -68,6 +70,9 @@ export const UNDERSTOOD_NAMESPACES = new Set([
     'http://schemas.microsoft.com/office/word/2012/wordprocessingDrawing',
     'http://schemas.microsoft.com/office/word/2015/wordml/symex',
     'http://schemas.microsoft.com/office/word/2016/wordml/cid',
+    'http://schemas.microsoft.com/office/word/2018/wordml',
+    'http://schemas.microsoft.com/office/word/2018/wordml/cex',
+    'http://schemas.microsoft.com/office/word/2026/wordml/cei',
     'http://schemas.microsoft.com/office/webextensions/taskpanes/2010/11',
     'http://schemas.microsoft.com/office/webextensions/webextension/2010/11',
     'http://schemas.microsoft.com/office/powerpoint/2010/main',
@@ -89,10 +94,34 @@ export const UNDERSTOOD_NAMESPACES = new Set([
     'http://schemas.microsoft.com/office/excel/2006/main',
     'http://schemas.microsoft.com/office/excel/2008/2/main',
     'http://schemas.microsoft.com/office/excel/2010/spreadsheetDrawing',
+    'http://schemas.microsoft.com/office/spreadsheetml/2009/9/main',
+    'http://schemas.microsoft.com/office/spreadsheetml/2010/11/main',
+    'http://schemas.microsoft.com/office/spreadsheetml/2010/11/ac',
+    'http://schemas.microsoft.com/office/spreadsheetml/2011/1/ac',
+    'http://schemas.microsoft.com/office/spreadsheetml/2014/11/main',
+    'http://schemas.microsoft.com/office/spreadsheetml/2014/revision',
+    'http://schemas.microsoft.com/office/spreadsheetml/2018/calcfeatures',
     'http://schemas.microsoft.com/ink/2010/main',
     'http://www.w3.org/1998/Math/MathML',
     'http://www.w3.org/2003/InkML',
     'http://schemas.microsoft.com/office/2006/encryption',
     'http://schemas.microsoft.com/office/2006/keyEncryptor/certificate',
     'http://schemas.microsoft.com/office/2006/keyEncryptor/password',
+    // Bound by the model without being any module's default element namespace (so the check in
+    // mce.test.mjs does not reach them): relationship ids and the custom document properties are
+    // attributes and elements other modules' types carry, chartStyle has a module that defaults to
+    // the DrawingML main namespace, and the 2016 ink one a module with no default at all.
+    'http://schemas.openxmlformats.org/officeDocument/2006/relationships',
+    'http://schemas.openxmlformats.org/officeDocument/2006/custom-properties',
+    'http://schemas.microsoft.com/office/drawing/2012/chartStyle',
+    'http://schemas.microsoft.com/office/drawing/2016/ink',
+    // Excel's slicer and timeline drawings (CR-004 phase B). Nothing binds these - docx4j has not
+    // bound the schemas either - but the Choice they gate is an xdr:graphicFrame whose a:graphicData
+    // holds the one unbound element, and that wildcard is lax (docx4j 8e8f6ea83), so it loads as DOM
+    // and re-marshals unchanged. Taking the Choice therefore keeps the slicer or timeline; leaving
+    // it would take the Fallback, an "Excel 2010 or higher" placeholder box, and lose the slicer for
+    // good. A Choice is only worth taking when everything in it round-trips (docx4j CR-021 8.9).
+    'http://schemas.microsoft.com/office/drawing/2010/slicer',
+    'http://schemas.microsoft.com/office/drawing/2012/slicer',
+    'http://schemas.microsoft.com/office/drawing/2012/timeslicer',
 ]);

package/dist/packages/WordprocessingMLPackage.d.mts

@@ -1,18 +1,21 @@
 import { OpcPackage, type PackageSource } from './OpcPackage.mjs';
 import type { LoadOptions } from '../opc/Load.mjs';
 import type { Part } from '../parts/Part.mjs';
-import { MainDocumentPart, type NumberingDefinitionsPart } from '../parts/wml/index.mjs';
+import { MainDocumentPart, StyleDefinitionsPart, type NumberingDefinitionsPart } from '../parts/wml/index.mjs';
 import { type FontSettings, type DefaultThemeValue } from '../model/fonts/defaultTheme.mjs';
 import type { Body, Address, Outline, OutlineParagraph, OutlineTable } from '../model/content/Body.mjs';
 import type { Paragraph } from '../model/content/Paragraph.mjs';
 import type { Author } from '../model/content/comments.mjs';
 import { CustomXmlPartCollection } from '../model/customxml/CustomXmlPartCollection.mjs';
 import { type XPathEngine } from '../model/customxml/xpath.mjs';
-import { ChangeTracker, type ChangeTrackingMode, type TrackingHost } from '../model/content/tracking.mjs';
+import { ChangeTracker, type ChangeTrackingMode, type TrackingHost, type TrackingScope } from '../model/content/tracking.mjs';
 import { NumberingFacade } from '../model/content/List.mjs';
+import { StylesFacade } from '../model/content/stylesFacade.mjs';
+import type { Bound } from '../model/content/binder.mjs';
 import { PropertyResolver } from '../model/properties/PropertyResolver.mjs';
 import type { Emulator } from '../model/listnumbering/Emulator.mjs';
 import type { TrackedChange } from '../model/content/TrackedChange.mjs';
+import { XmlPart } from '../parts/XmlPart.mjs';
 import type { PartSink } from '../opc/PartStore.mjs';
 import '../parts/wml/comments.mjs';
 /** The outline of a document: the body's paragraphs and tables, then each header's and footer's (loaded ones only). */
@@ -59,6 +62,31 @@ export declare class WordprocessingMLPackage extends OpcPackage implements Track
     private tracker;
     /** Set when `changeTrackingMode` was written but the settings part was not unmarshalled yet. */
     private trackingPending;
+    /**
+     * `withTracking`'s mode for the duration of one call: read by the getter before everything else
+     * and **never** written by the setter, so it touches neither the settings part, `trackingPending`
+     * nor the cached `trackingMode` (CR-002 section 28.1).
+     */
+    private trackingOverride;
+    /**
+     * The `withTracking` calls still running, oldest first, and what the package said before the
+     * first of them. The latest call's markup applies; when it ends, the latest one still running
+     * applies again, and when none is left the package is as it was (CR-002 section 31).
+     */
+    private trackingScopes;
+    private beforeScopes;
+    /**
+     * Style ids a synchronous setter has given runs, to be defined in the styles part by the time the
+     * package is saved: `Range.hyperlink` writes `w:rStyle w:val="Hyperlink"` and cannot await
+     * `styles.ensure` (CR-002 section 25). `saveTo` ensures them; nothing is read before then.
+     */
+    private requiredStyles;
+    /**
+     * The parts `seedAnnotationIds()` has read, with what it read: `true` for a part still holding its
+     * source, whose bytes cannot change, and otherwise the bytes that were set, which stay the same
+     * array until they are set again.
+     */
+    private seededParts;
     /**
      * The package's font settings (CR-001 Phase B step 4), docx4j's `docx4j.fonts.*` properties
      * scoped to one package: `defaultTheme` says which Office theme a font reference resolves
@@ -131,6 +159,30 @@ export declare class WordprocessingMLPackage extends OpcPackage implements Track
      */
     get changeTrackingMode(): ChangeTrackingMode;
     set changeTrackingMode(mode: ChangeTrackingMode);
+    /**
+     * Runs `fn` with revisions recorded as `markup` says, and the document's own setting untouched:
+     * nothing is written to `w:trackRevisions`, no settings part is created, and the mode a later read
+     * reports is the one that was there before (CR-002 section 28.1, for an editor whose agent must
+     * record its edits as a named author in a room whose tracking setting belongs to the document).
+     *
+     * The author, the date and the mode are restored in a `finally`, so a throw from `fn` cannot leave
+     * the package tracking. It is asynchronous for one reason: it awaits `seedAnnotationIds()` before
+     * running `fn`, so a revision written inside it cannot reuse an id from a part nobody has read
+     * (section 28.2). `fn` itself may be synchronous.
+     *
+     * Calls nest, and calls that overlap in time end in whatever order they end without leaving the
+     * package tracking. But the markup is the package's for as long as a call runs, not the call's:
+     * while two are running, **the later one's author and mode apply to every edit**, the earlier
+     * one's included, because nothing here can tell which asynchronous call an edit came from. Await
+     * one before starting another when they must be recorded as different authors (section 31).
+     */
+    withTracking<T>(markup: TrackingScope, fn: () => T | Promise<T>): Promise<T>;
+    /**
+     * One `withTracking` call's markup made the package's. The tracker is left alone: the getter makes
+     * another when the mode differs, and the id counter it reads is the package's, so a tracker kept
+     * across the call cannot reissue an id given out inside it (section 31).
+     */
+    private applyTrackingScope;
     /** The mode as the settings part has it, unmarshalling the part (docx4j's async counterpart of the getter). */
     getChangeTrackingMode(): Promise<ChangeTrackingMode>;
     /** Writes `w:trackRevisions`, unmarshalling the settings part, or creating it when there is none. */
@@ -145,9 +197,50 @@ export declare class WordprocessingMLPackage extends OpcPackage implements Track
     getTrackedChanges(): TrackedChange[];
     /** The tracker every content-API mutation asks for; undefined while the mode is `Off`. */
     get changeTracker(): ChangeTracker | undefined;
+    /**
+     * The objects an XPath selects in a part of this document, through the package's engine
+     * (CR-006; docx4j `MainDocumentPart.getJAXBNodesViaXPath`). The part defaults to the main
+     * document part, which is what a `//w:p[...]` expression means.
+     */
+    selectObjects(xpath: string, options?: {
+        part?: XmlPart<unknown>;
+        namespaces?: Record<string, string>;
+    }): Promise<Bound[]>;
+    /**
+     * TrackingHost: a floor for the annotation id, from the WordprocessingML parts that were **not**
+     * unmarshalled; `seedAnnotationIds()` fills it. 0 until then (CR-002 section 28.2).
+     */
+    annotationIdFloor: number;
+    /**
+     * TrackingHost: the last annotation id issued, shared by every tracker this package makes (CR-002
+     * section 31). Forgotten when the mode is set, as the tracker used to be, so that the next id is
+     * found by a fresh scan of whatever has arrived since by other routes (`insertOoxml`, `setContents`).
+     */
+    annotationIdCounter: number | undefined;
+    /**
+     * Raises `annotationIdFloor` above every annotation id in the WordprocessingML parts that are not
+     * unmarshalled, reading each **privately** (`readContents`, CR-001 Phase D's device), so that a
+     * part nobody has touched keeps its byte-for-byte round trip and still cannot have its ids reused.
+     *
+     * Awaited by `setChangeTrackingMode()` and by `withTracking()`, which is where tracking is turned
+     * on; a caller that uses the synchronous `changeTrackingMode` setter on a document with unread
+     * parts should await this itself, since `nextId()` cannot (the content API's setters are
+     * synchronous, which is why the floor exists at all rather than the scan being made async).
+     *
+     * A part is read once for the bytes it holds: an agent that wraps every edit in `withTracking`
+     * would otherwise re-read every header, footer and note part each time (section 31). Its source
+     * bytes cannot change; bytes that were set are read again when they are set again.
+     */
+    seedAnnotationIds(): Promise<number>;
     /** TrackingHost: the trees a new revision id must be above, which is every part already unmarshalled. */
     markupRoots(): object[];
-    /** A clone carries the identity, the tracking date, the theme setting and the XPath engine. */
+    /**
+     * Asks for style definitions a synchronous setter has referenced; they are ensured on save, as
+     * `pkg.styles.ensure(ids)` would, and a document that already has them keeps its styles part
+     * byte for byte (CR-002 section 25). Await `styles.ensure` instead to have them at once.
+     */
+    requireStyles(ids: Iterable<string>): void;
+    /** A clone carries the identity, the tracking date, the theme setting, the XPath engine and the styles still to ensure. */
     protected copyPackageSettingsTo(target: OpcPackage): void;
     saveTo<R>(sink: PartSink<R>): Promise<R>;
     /** The paragraph at an address anywhere in the document: 'body/3', 'header:rId5/0', a paraId, or a text match. */
@@ -162,6 +255,15 @@ export declare class WordprocessingMLPackage extends OpcPackage implements Track
      * `customXmlParts.load()`; every node call is synchronous afterwards.
      */
     xpathEngine: XPathEngine;
+    /**
+     * The document's style definitions as a verb that needs no `Body`: `ensure(ids)` splices in a
+     * style the document lacks, out of the same defaults `createPackage()` writes, with what it is
+     * based on and linked to (CR-002 section 22.2).
+     */
+    get styles(): StylesFacade;
+    private stylesFacade;
+    /** The styles part, created with the defaults when the document has none (CR-002 section 22.2). */
+    ensureStyleDefinitionsPart(): StyleDefinitionsPart;
     /**
      * The document's list definitions as verbs that need no paragraph: `newList()` and
      * `restart(numId)` (CR-002 section 19). `Paragraph.startNewList()` and `List.restart()` are