@docx4j/core-ts 0.6.0 → 0.7.0

package/README.md

@@ -57,6 +57,66 @@ intermediate form and a builder from it, CR-005 section 8; the HTML parser is yo
 container; nothing else in the package imports a `node:` builtin, so a browser or add-in bundle
 never sees one).
 
+### Repairs
+
+Some packages Word opens only after its repair prompt, and some it won't open at all. `LoadOptions.repair`
+(WD REQ-207, [CR-031](docs/change-requests/CR-031-the-repair-option.md)) says how a load treats them:
+
+```ts
+const pkg = await WordprocessingMLPackage.load(bytes, { repair: 'word' });
+pkg.repaired;                                       // 'none', 'word' or 'own'; a text result's metadata.repaired says the same
+```
+
+| The package | `refuse`, the default | `word` | `all` |
+|---|---|---|---|
+| Two zip entries of one name (OPC part names, without case) | `DuplicateEntryException` | The first of each read, as Word does: `package.duplicate_entry` | As `word` |
+| More than one `officeDocument` relationship | `MultipleMainPartsException` | The last one's target read, as a fresh Word does: `package.multiple_main_parts` | As `word` |
+| A relationships part in another namespace, or in none | `RelationshipsNamespaceException` | Every relationship read by its local name, as Word does: `package.relationships_namespace` | As `word` |
+| An `External` `officeDocument` relationship beside an internal one | `ExternalMainPartException` | Refused: Word refuses it even through its repair | This package's own repair: the internal part read, every `External` main relationship dropped, its URL never fetched: `package.external_main_part` |
+| An `External` `officeDocument` relationship alone | Refused: no main document part (REQ-321) | Refused | Refused |
+
+Each warning is on `pkg.warnings` and, in the text model, a warning of the same code. A save then writes the
+repaired package: one entry of each name, one main relationship, the right namespace, no `External` main
+relationship. `repair` doesn't open the save's own gate ([CR-025](docs/change-requests/CR-025-dropped-content-reported.md)):
+a changed part is written without what Word's own save drops too, such as an ignorable element Word doesn't understand,
+each listed on `pkg.lastSave.dropped`; one that would lose anything else Word keeps, or won't open, needs
+`pkg.checkLossOnSave = false`, each item then on `pkg.lastSave.lost`. Each `part.skipped` warning says which (`onSave`). The other shapes
+Word repairs, such as an undeclared `mc:Ignorable` prefix or an element the model has no place for, read the same at
+every value (CR-031 section 2.1.1).
+
+### Saving
+
+A save copies every part nothing changed byte for byte, and re-marshals only what was read. Before it writes
+anything, it checks what it would write. It refuses a file Word would refuse or repair, and a save that would lose
+content Word keeps. Each check has a switch on the package, and each records what it let through on `pkg.lastSave`:
+
+| A save that would | Throws | To write it anyway | Recorded on `pkg.lastSave` |
+|---|---|---|---|
+| Write a child its container never admits: a run straight in the body, a table in a paragraph, a string in a run ([CR-016](docs/change-requests/CR-016-misplaced-content-refused.md)) | `MisplacedContentException` (`target.misplaced`, each child with its part, path and the fix) | `pkg.checkContentOnSave = false` | `misplaced` |
+| Lose what the read skipped, where Word's save keeps it or Word won't open the file ([CR-025](docs/change-requests/CR-025-dropped-content-reported.md)) | `SaveLossException` (`save.content_lost`, each part) | `pkg.checkLossOnSave = false` | `lost` |
+| Lose what the read skipped, where Word's own save drops it too | Nothing: written without it | | `dropped` |
+
+```ts
+import { SaveLossException } from '@docx4j/core-ts';
+
+try {
+  await pkg.save();
+} catch (e) {
+  if (!(e instanceof SaveLossException)) throw e;
+  pkg.checkLossOnSave = false;                      // accept the loss: e.losses names each part
+  await pkg.save();
+  pkg.lastSave.lost;                                // what went, each a part.skipped warning
+}
+```
+
+Only a part that was read is checked, so a package loaded and saved untouched is never refused. What a load found
+is on `pkg.warnings` before any save: content the read skipped (`part.skipped`, its `onSave` saying which row it
+falls in), misplaced children, and integer values past what Word stores (`value.out_of_range`, which a save writes
+as held and lists on `lastSave.outOfRange`). `part.checkContent()` and `pkg.checkContent()` run the first check on
+request, changing nothing. Two more switches change what a save writes: `pkg.normaliseOnSave` (run properties in
+Word's normal form, on by default) and `pkg.writeTimesOnSave` (the core properties' times, off by default).
+`pkg.dateTimeZone` is the time zone every revision's and comment's date is written and read in.
+
 ### Guides
 
 | | |

package/dist/model/content/Body.mjs

@@ -18,11 +18,12 @@ import { wrappingCellOf, paragraphEndOf, endsWithParagraph, endWithParagraph, en
 import { keepCellMarkLast } from './spanEdits.mjs';
 import { expandReplacement, paragraphMarkPieces, refuseMarkReplacement, refuseWildcardMarkReplacement } from './search.mjs';
 import { commentApi } from './comments.mjs';
-import { storyLayout } from './story.mjs';
+import { storyLayout, shownInOriginalView } from './story.mjs';
 import { trackerOf, trackInsertedBlock, markHolderInserted } from './tracking.mjs';
 import { trackedChangesOfRow, trackedChangeTokensOfParagraph, groupTouching, BREAK, tablePropertiesChangeOf, cellChangeOf, bodySectionChangeOf, resolveUnlisted, holderChangeAt, resolving, resolvePieces, alternateTokens, listedListing, pairTwins } from './TrackedChange.mjs';
 import { pieceMatcher } from './trackedChangeFilter.mjs';
 import { listsOf, listLabelsOf } from './List.mjs';
+import { assignParaIds } from './paraIds.mjs';
 /**
  * A subset of Office JS `Word.Body` over any container with block-level content: the main
  * document's body, a header, a footer, a footnote, a cell or a content control. A view: the
@@ -302,7 +303,7 @@ export class Body {
         const { text } = storyLayout(this.content, (el, items) => {
             const p = new Paragraph(el, items, this);
             return view === 'original' ? p.getText({ view }) : p.text;
-        }, view === 'original' ? (p) => { var _a, _b; return ((_b = (_a = p.pPr) === null || _a === void 0 ? void 0 : _a.rPr) === null || _b === void 0 ? void 0 : _b.ins) === undefined; } : undefined);
+        }, view === 'original' ? shownInOriginalView : undefined);
         // the last paragraph's mark is not written
         return text.endsWith('\r') ? text.slice(0, -1) : text;
     }
@@ -420,8 +421,7 @@ export class Body {
         for (const el of elements) {
             linkParents(el, owner);
             const tn = typeNameOf(el);
-            if (tn === 'org_docx4j_wml.P')
-                this.assignParaId(el.value);
+            assignParaIds(this.container, [el]); // whatever it holds: a table's rows and cells, a control's paragraphs
             // everything it holds is an insertion: the runs in its links and inline controls, the rows and
             // nested tables of a table, a block control's content and the control itself (CR-002 section 37)
             if (tracker)
@@ -475,9 +475,7 @@ export class Body {
             keepCellMarkLast(new Paragraph(end.element, content, this), content);
             return;
         }
-        const appended = endWithParagraph(cell);
-        if (appended)
-            this.assignParaId(appended);
+        endWithParagraph(cell);
     }
     /** The package's DOM preprocessor (the MCE one), for fragments and incoming packages. */
     preprocessor() {
@@ -1055,16 +1053,7 @@ export class Body {
      * @internal a paragraph split (CR-014 phase 2) gives its new first half one.
      */
     assignParaId(p) {
-        if (p.paraId)
-            return;
-        const paragraphs = this.paragraphsIn('every');
-        if (!paragraphs.some((q) => q.paraId !== undefined))
-            return;
-        let id;
-        do {
-            id = Math.floor(Math.random() * 0x7fffffff).toString(16).toUpperCase().padStart(8, '0');
-        } while (paragraphs.some((q) => q.paraId === id));
-        p.paraId = id;
+        assignParaIds(this.container, [p]);
     }
     // --- comments (CR-002 phase G) ---
     /**

package/dist/model/content/Comment.d.mts

@@ -36,8 +36,8 @@ export declare class Comment {
     /**
      * When the comment was made, as Word means it (CR-002 section 29, the revision dates' rule): its
      * `w16cex:dateUtc` when the document has one for it, which is UTC; else `w:date`, which Word writes
-     * on the author's local wall clock whatever its `Z` says, read as local time. Undefined when the
-     * comment carries neither.
+     * on the author's local wall clock whatever its `Z` says, read as local time in the package's
+     * `dateTimeZone` (CR-018), else the runtime's. Undefined when the comment carries neither.
      */
     get creationDate(): Date | undefined;
     /** The comment's paragraphs as a `Body` (extension: the same content API as the document's). */

package/dist/model/content/Comment.mjs

@@ -10,7 +10,7 @@ import { Paragraph } from './Paragraph.mjs';
 import { Range } from './Range.mjs';
 import { runOf, paragraphOf, typeNameOf, selectedBranchOf, BRANCH_TYPES } from './tree.mjs';
 import { storyLayout } from './story.mjs';
-import { revisionDateOf, wordCalendarOf, copyRPr } from './tracking.mjs';
+import { revisionDateOf, wordCalendarOf, nowToTheMinute, copyRPr } from './tracking.mjs';
 import { relationshipIdsIn, queueRelationshipRemovals } from './relationships.mjs';
 import { COMMENT_REFERENCE_STYLE, COMMENT_TEXT_STYLE, commentExOf, commentIdsOf, commentPartsAccess, commentParaId, initialsOf, isDone, markersOf, markersOfParagraph, nextCommentId, paraIdTaken, randomHexId, removeMarkers, setCommentApi, } from './comments.mjs';
 /**
@@ -56,8 +56,8 @@ export class Comment {
     /**
      * When the comment was made, as Word means it (CR-002 section 29, the revision dates' rule): its
      * `w16cex:dateUtc` when the document has one for it, which is UTC; else `w:date`, which Word writes
-     * on the author's local wall clock whatever its `Z` says, read as local time. Undefined when the
-     * comment carries neither.
+     * on the author's local wall clock whatever its `Z` says, read as local time in the package's
+     * `dateTimeZone` (CR-018), else the runtime's. Undefined when the comment carries neither.
      */
     get creationDate() {
         var _a;
@@ -67,7 +67,7 @@ export class Comment {
             if (utc)
                 return utc;
         }
-        return revisionDateOf({ date: this.element.date });
+        return revisionDateOf({ date: this.element.date }, zoneOf(this.body.package_));
     }
     /** The comment's paragraphs as a `Body` (extension: the same content API as the document's). */
     get commentBody() {
@@ -551,13 +551,14 @@ function addComment(parts, body, id, paragraphs, parent, options) {
     var _a, _b, _c, _d, _e, _f;
     var _g, _h;
     const author = (_a = options === null || options === void 0 ? void 0 : options.author) !== null && _a !== void 0 ? _a : parts.author;
-    // one instant for w:date (the local wall clock, as Word writes it) and w16cex:dateUtc (UTC)
-    const made = (_b = options === null || options === void 0 ? void 0 : options.date) !== null && _b !== void 0 ? _b : new Date();
+    // one instant for w:date (the local wall clock in the package's zone, as Word writes it) and w16cex:dateUtc (UTC);
+    // a new comment is stamped to the minute, as a revision is and as Word stamps (CR-018, the date rule's point 5)
+    const made = (_b = options === null || options === void 0 ? void 0 : options.date) !== null && _b !== void 0 ? _b : nowToTheMinute();
     const paraId = randomHexId((candidate) => paraIdTaken(parts, body.container, candidate));
     paragraphs[0].value.paraId = paraId;
     const comment = wmlFactory.createCommentsComment({
         id, author: author.name, initials: (_c = options === null || options === void 0 ? void 0 : options.initials) !== null && _c !== void 0 ? _c : initialsOf(author),
-        date: wordCalendarOf(made),
+        date: wordCalendarOf(made, zoneOf(body.package_)),
         content: paragraphs,
     });
     const comments = ((_d = (_g = parts.comments).comment) !== null && _d !== void 0 ? _d : (_g.comment = []));
@@ -797,3 +798,7 @@ function unique(ids) {
     return ids.filter((id) => (seen.has(id) ? false : (seen.add(id), true)));
 }
 setCommentApi({ commentsOf, insertComment });
+/** The package's `dateTimeZone` (CR-018), read duck-typed since the package module cannot be imported here. */
+function zoneOf(pkg) {
+    return pkg === null || pkg === void 0 ? void 0 : pkg.dateTimeZone;
+}

package/dist/model/content/ContentControl.d.mts

@@ -296,7 +296,7 @@ export declare class ContentControl {
     get inBranch(): boolean;
     /** Refuses a write to a control in a branch (CR-013 D4). Internal: the control's mutators, and its kinds', call it first. */
     assertWritable(): void;
-    /** The table a row-level or cell-level control belongs to. */
+    /** The table a row-level or cell-level control belongs to, through the row-level controls around it, nested to any depth. */
     private ancestorTable;
 }
 /**

package/dist/model/content/ContentControl.mjs

@@ -19,6 +19,7 @@ import { sdtProperty, sdtKindOf } from '@docx4j/generated-objects-ts/builders/wm
 import { typeNameOf, childrenOf, runItemsOf, runsOf, linkParents, runOf, SDT_TYPES, ALTERNATE_CONTENT, BLOCK_LEVEL_TYPES, branchListsOf, inBranch, assertOutsideBranch } from './tree.mjs';
 import { Range } from './Range.mjs';
 import { Table } from './Table.mjs';
+import { assignParaIds } from './paraIds.mjs';
 /** The namespaces of the Word 2010 and 2012 content-control properties. */
 export const W14_NS = 'http://schemas.microsoft.com/office/word/2010/wordml';
 export const W15_NS = 'http://schemas.microsoft.com/office/word/2012/wordml';
@@ -223,6 +224,7 @@ export class ContentControl {
         const content = ((_a = (_b = this.sdt.sdtContent).content) !== null && _a !== void 0 ? _a : (_b.content = []));
         content.push(p);
         linkParents(p, this.sdt.sdtContent);
+        assignParaIds(this.sdt.sdtContent, [p]);
         return body.paragraphs[0];
     }
     /**
@@ -434,6 +436,7 @@ export class ContentControl {
             const p = el.p({ ...(pPr ? { pPr: deepCopy(pPr) } : {}), content: runs });
             content.splice(at++, 0, p);
             linkParents(p, this.sdt.sdtContent);
+            assignParaIds(this.sdt.sdtContent, [p]);
         }
     }
     insertTextInto(text, location) {
@@ -908,6 +911,7 @@ export class ContentControl {
                 const p = paragraphElementOf(runs);
                 content.push(p);
                 linkParents(p, sdt.sdtContent);
+                assignParaIds(sdt.sdtContent, [p]);
             }
         }
         else {
@@ -925,6 +929,7 @@ export class ContentControl {
                 const p = paragraphElementOf(runs);
                 content.push(p);
                 linkParents(p, sdt.sdtContent);
+                assignParaIds(sdt.sdtContent, [p]);
             }
             const others = blocks.filter((e) => e !== paragraph);
             if (others.length > 0)
@@ -962,8 +967,7 @@ export class ContentControl {
      */
     syncBoundNode() {
         try {
-            if (this.xmlMapping.isMapped)
-                updateFromControl(this);
+            updateFromControl(this);
         }
         catch {
             // the part is not parsed, or the engine is not ready: leave it to updateFromContentControls()
@@ -995,11 +999,11 @@ export class ContentControl {
     assertWritable() {
         assertOutsideBranch(this.element.value, 'ContentControl');
     }
-    /** The table a row-level or cell-level control belongs to. */
+    /** The table a row-level or cell-level control belongs to, through the row-level controls around it, nested to any depth. */
     ancestorTable() {
         var _a;
         let current = this.element.value.PARENT;
-        for (let guard = 0; current && guard < 8; guard++) {
+        for (let guard = 0; current && guard < 256; guard++) {
             if (typeNameOf(current) === 'org_docx4j_wml.Tbl') {
                 const tbl = current;
                 const container = childrenOf(((_a = tbl.PARENT) !== null && _a !== void 0 ? _a : {}));

package/dist/model/content/Font.d.mts

@@ -108,7 +108,10 @@ export declare class Font {
      */
     get name(): string;
     set name(v: string);
-    /** Size in points (w:sz is half-points); 0 only in a direct-formatting view with no w:sz; `null` where the runs differ. */
+    /**
+     * Size in points (w:sz is half-points); 0 only in a direct-formatting view with no w:sz; `null` where the runs differ. A
+     * size written is held to the range Word 365 stores w:sz in, 0 to 32767.5 pt (CR-002 section 65): outside it, `InvalidArgument`.
+     */
     get size(): number;
     set size(v: number);
     /**

package/dist/model/content/Font.mjs

@@ -1,4 +1,5 @@
 import { applyRunOptions, readRunOptions } from '@docx4j/generated-objects-ts/builders/wml';
+import { withinWord, WORD_STORAGE } from './wordRange.mjs';
 import { WordColors } from '../color/WordColors.mjs';
 /** A paragraph mark's run properties as a `Font` reads them: `w:pPr/w:rPr` without the mark's own revisions. */
 export function markHolderOf(p) {
@@ -134,9 +135,12 @@ export class Font {
         return all.length > 0 && all.every((n) => n === all[0]) ? all[0] : '';
     }
     set name(v) { this.apply({ name: v }); }
-    /** Size in points (w:sz is half-points); 0 only in a direct-formatting view with no w:sz; `null` where the runs differ. */
+    /**
+     * Size in points (w:sz is half-points); 0 only in a direct-formatting view with no w:sz; `null` where the runs differ. A
+     * size written is held to the range Word 365 stores w:sz in, 0 to 32767.5 pt (CR-002 section 65): outside it, `InvalidArgument`.
+     */
     get size() { return this.value('size'); }
-    set size(v) { this.apply({ size: v }); }
+    set size(v) { withinWord('Font.size', v, WORD_STORAGE.sz); this.apply({ size: v }); }
     /**
      * '#RRGGBB': in the effective view the colour Word draws, so a theme colour (`w:themeColor`, with its tint or shade)
      * through the document's theme, as Office JS reads it (check 53; CR-008 phase 2), and `#000000` for automatic; in

package/dist/model/content/List.d.mts

@@ -164,9 +164,12 @@ export declare class List {
      */
     setLevelBullet(level: number, listBullet: ListBullet, charCode?: number, fontName?: string): void;
     /**
-     * Office JS `list.setLevelIndents(level, textIndent, bulletNumberPictureIndent)`, both in
-     * points: the level's `w:ind/@w:left` is where the text sits and the label's position is the
-     * hanging indent from it (or `w:firstLine` where the label sits to the right of the text).
+     * Office JS `list.setLevelIndents(level, textIndent, bulletNumberPictureIndent)`, both in points: the level's
+     * `w:ind/@w:left` is the text indent, and the label's indent is relative to it, "the same as paragraph first line
+     * indent": a first-line indent, or a hanging indent for a negative (check 71 case 86: Word wrote (-1, 0) as
+     * `w:left="-20" w:firstLine="0"`; until CR-002 section 65.5 it was taken as the label's absolute position).
+     * Each is held to the range Word stores it in (section 65); the text indent to Word's own setter's limit, short of
+     * 1584 pt either way (check 71b, section 65.9), the label's indent to its storage, unmeasured by Word's setter.
      */
     setLevelIndents(level: number, textIndent: number, bulletNumberPictureIndent: number): void;
     /** Office JS `list.setLevelAlignment(level, alignment)`: the level's `w:lvlJc`. */

package/dist/model/content/List.mjs

@@ -7,6 +7,7 @@ import { NumberingState, storyKindOf } from '../listnumbering/state.mjs';
 import { LEVELS } from '../listnumbering/definitions.mjs';
 import { isElement, linkParents, selectedBranchOf, ALTERNATE_CONTENT } from './tree.mjs';
 import { Font } from './Font.mjs';
+import { withinWord, WORD_STORAGE } from './wordRange.mjs';
 function packageOf(body) {
     const pkg = body.package_;
     return typeof (pkg === null || pkg === void 0 ? void 0 : pkg.getMainDocumentPart) === 'function' ? pkg : undefined;
@@ -350,24 +351,30 @@ export class List {
         this.written();
     }
     /**
-     * Office JS `list.setLevelIndents(level, textIndent, bulletNumberPictureIndent)`, both in
-     * points: the level's `w:ind/@w:left` is where the text sits and the label's position is the
-     * hanging indent from it (or `w:firstLine` where the label sits to the right of the text).
+     * Office JS `list.setLevelIndents(level, textIndent, bulletNumberPictureIndent)`, both in points: the level's
+     * `w:ind/@w:left` is the text indent, and the label's indent is relative to it, "the same as paragraph first line
+     * indent": a first-line indent, or a hanging indent for a negative (check 71 case 86: Word wrote (-1, 0) as
+     * `w:left="-20" w:firstLine="0"`; until CR-002 section 65.5 it was taken as the label's absolute position).
+     * Each is held to the range Word stores it in (section 65); the text indent to Word's own setter's limit, short of
+     * 1584 pt either way (check 71b, section 65.9), the label's indent to its storage, unmeasured by Word's setter.
      */
     setLevelIndents(level, textIndent, bulletNumberPictureIndent) {
         var _a, _b;
+        // within the ranges Word 365 stores the level's w:ind in (CR-002 section 65), before anything changes
+        const left = withinWord('List.setLevelIndents (textIndent)', textIndent, WORD_STORAGE.lvlIndLeft);
+        const label = bulletNumberPictureIndent < 0
+            ? withinWord('List.setLevelIndents (a hanging bulletNumberPictureIndent)', -bulletNumberPictureIndent, WORD_STORAGE.indHanging)
+            : withinWord('List.setLevelIndents (bulletNumberPictureIndent)', bulletNumberPictureIndent, WORD_STORAGE.indFirstLine);
         const lvl = this.writableLvl(level);
         const pPr = ((_a = lvl.pPr) !== null && _a !== void 0 ? _a : (lvl.pPr = { TYPE_NAME: 'org_docx4j_wml.PPr' }));
         const ind = ((_b = pPr.ind) !== null && _b !== void 0 ? _b : (pPr.ind = f.createPPrBaseInd({})));
-        const left = Math.round(textIndent * TWIPS_PER_POINT);
-        const label = Math.round(bulletNumberPictureIndent * TWIPS_PER_POINT);
         ind.left = left;
-        if (label <= left) {
-            ind.hanging = left - label;
+        if (bulletNumberPictureIndent < 0) {
+            ind.hanging = label;
             delete ind.firstLine;
         }
         else {
-            ind.firstLine = label - left;
+            ind.firstLine = label;
             delete ind.hanging;
         }
         linkParents(pPr, lvl);

package/dist/model/content/Paragraph.d.mts

@@ -142,7 +142,11 @@ export declare class Paragraph {
      * hold for any value. Undefined without a resolver, where the value is written as asked.
      */
     private inheritedAlignment;
-    /** Indents and spacing in points, as Office JS; the effective values (CR-001 Phase B step 2). */
+    /**
+     * Indents and spacing in points, as Office JS; the effective values (CR-001 Phase B step 2). A value written is held to
+     * the range Word 365 stores its attribute in (`withinWord`, CR-002 section 65): outside it, `InvalidArgument`, before
+     * anything changes.
+     */
     get leftIndent(): number;
     set leftIndent(pt: number);
     get rightIndent(): number;
@@ -156,6 +160,11 @@ export declare class Paragraph {
     set spaceAfter(pt: number);
     /** Line spacing in points: w:line/240 lines of 12pt when the rule is auto, else w:line twips; 0 when not set. */
     get lineSpacing(): number;
+    /**
+     * Writes `w:line` as 20 × points under `w:lineRule="auto"`, as Word 365's own setter does (check 71b: 0.75 pt as
+     * `w:line="15" w:lineRule="auto"`; Office JS: "in the Word UI, this value is divided by 12", so 12 pt is single spacing),
+     * within Word's own limits, 0.75 to 1584 pt (CR-002 section 65.9). Until check 71b it wrote an exact rule.
+     */
     set lineSpacing(pt: number);
     /** w:outlineLvl + 1 (1 to 9); 10 for body text, as Office JS. A heading style supplies it. */
     get outlineLevel(): number;
@@ -242,7 +251,8 @@ export declare class Paragraph {
     /**
      * The character Office JS gives for this paragraph's mark at the end of its 'Whole' range (check 48):
      * `\t` for the last paragraph of a table cell, the cell's end; nothing for a mark tracked as deleted, which
-     * Word's default view doesn't show (CR-012 section 19, check 58); and `\r` for any other.
+     * Word's default view doesn't show (CR-012 section 19, check 58), or as moved from, as the paragraph's runs read
+     * (CR-002 section 64); and `\r` for any other.
      */
     get markText(): string;
     /**

package/dist/model/content/Paragraph.mjs

@@ -3,6 +3,8 @@ import { Docx4JException } from '../../opc/exceptions.mjs';
 import { NotSupportedError } from '../../office-js/errors.mjs';
 import { t as textItem, br as breakItem } from '@docx4j/generated-objects-ts/builders/wml';
 import { segmentsOf, runsOf, runItemsOf, inShowingPlaceholder, linkParents, typeNameOf, W_NS, runOf, paragraphOf, revisionKindOf, objectInSpan, WHOLE, isAlternateContent, selectedBranchOf, inBranch, assertOutsideBranch } from './tree.mjs';
+import { shownInDefaultView } from './story.mjs';
+import { withinWord, WORD_STORAGE } from './wordRange.mjs';
 import { relationshipIdsIn, queueRelationshipRemovals } from './relationships.mjs';
 function withRPr(run, rPr) {
     if (rPr)
@@ -229,36 +231,54 @@ export class Paragraph {
         // in a table cell what is inherited includes the table style's (CR-007)
         return alignmentOf(resolver.getEffectivePPr(rest, resolver.cellContextOf(this.p)), true);
     }
-    /** Indents and spacing in points, as Office JS; the effective values (CR-001 Phase B step 2). */
+    /**
+     * Indents and spacing in points, as Office JS; the effective values (CR-001 Phase B step 2). A value written is held to
+     * the range Word 365 stores its attribute in (`withinWord`, CR-002 section 65): outside it, `InvalidArgument`, before
+     * anything changes.
+     */
     get leftIndent() { var _a, _b; return ((_b = (_a = this.effectivePPr.ind) === null || _a === void 0 ? void 0 : _a.left) !== null && _b !== void 0 ? _b : 0) / TWIPS_PER_POINT; }
-    set leftIndent(pt) { this.ind().left = Math.round(pt * TWIPS_PER_POINT); this.settleFormatting(); }
+    set leftIndent(pt) { const v = withinWord('Paragraph.leftIndent', pt, WORD_STORAGE.indLeft); this.ind().left = v; this.settleFormatting(); }
     get rightIndent() { var _a, _b; return ((_b = (_a = this.effectivePPr.ind) === null || _a === void 0 ? void 0 : _a.right) !== null && _b !== void 0 ? _b : 0) / TWIPS_PER_POINT; }
-    set rightIndent(pt) { this.ind().right = Math.round(pt * TWIPS_PER_POINT); this.settleFormatting(); }
+    set rightIndent(pt) { const v = withinWord('Paragraph.rightIndent', pt, WORD_STORAGE.indRight); this.ind().right = v; this.settleFormatting(); }
     /** First-line indent; negative for a hanging indent, as Office JS. */
     get firstLineIndent() {
         return firstLineIndentOf(this.effectivePPr);
     }
     set firstLineIndent(pt) {
+        const v = pt < 0
+            ? withinWord('Paragraph.firstLineIndent (a hanging indent)', -pt, WORD_STORAGE.indHanging)
+            : withinWord('Paragraph.firstLineIndent', pt, WORD_STORAGE.indFirstLine);
         const ind = this.ind();
         if (pt < 0) {
-            ind.hanging = Math.round(-pt * TWIPS_PER_POINT);
+            ind.hanging = v;
             delete ind.firstLine;
         }
         else {
-            ind.firstLine = Math.round(pt * TWIPS_PER_POINT);
+            ind.firstLine = v;
             delete ind.hanging;
         }
         this.settleFormatting();
     }
     get spaceBefore() { var _a, _b; return ((_b = (_a = this.effectivePPr.spacing) === null || _a === void 0 ? void 0 : _a.before) !== null && _b !== void 0 ? _b : 0) / TWIPS_PER_POINT; }
-    set spaceBefore(pt) { this.spacing().before = Math.round(pt * TWIPS_PER_POINT); this.settleFormatting(); }
+    set spaceBefore(pt) { const v = withinWord('Paragraph.spaceBefore', pt, WORD_STORAGE.spacingBefore); this.spacing().before = v; this.settleFormatting(); }
     get spaceAfter() { var _a, _b; return ((_b = (_a = this.effectivePPr.spacing) === null || _a === void 0 ? void 0 : _a.after) !== null && _b !== void 0 ? _b : 0) / TWIPS_PER_POINT; }
-    set spaceAfter(pt) { this.spacing().after = Math.round(pt * TWIPS_PER_POINT); this.settleFormatting(); }
+    set spaceAfter(pt) { const v = withinWord('Paragraph.spaceAfter', pt, WORD_STORAGE.spacingAfter); this.spacing().after = v; this.settleFormatting(); }
     /** Line spacing in points: w:line/240 lines of 12pt when the rule is auto, else w:line twips; 0 when not set. */
     get lineSpacing() {
         return lineSpacingOf(this.effectivePPr);
     }
-    set lineSpacing(pt) { const s = this.spacing(); s.line = Math.round(pt * TWIPS_PER_POINT); s.lineRule = 'exact'; this.settleFormatting(); }
+    /**
+     * Writes `w:line` as 20 × points under `w:lineRule="auto"`, as Word 365's own setter does (check 71b: 0.75 pt as
+     * `w:line="15" w:lineRule="auto"`; Office JS: "in the Word UI, this value is divided by 12", so 12 pt is single spacing),
+     * within Word's own limits, 0.75 to 1584 pt (CR-002 section 65.9). Until check 71b it wrote an exact rule.
+     */
+    set lineSpacing(pt) {
+        const v = withinWord('Paragraph.lineSpacing', pt, WORD_STORAGE.spacingLineAuto);
+        const s = this.spacing();
+        s.line = v;
+        s.lineRule = 'auto';
+        this.settleFormatting();
+    }
     /** w:outlineLvl + 1 (1 to 9); 10 for body text, as Office JS. A heading style supplies it. */
     get outlineLevel() { return outlineLevelOf(this.effectivePPr); }
     set outlineLevel(level) { const pPr = this.pPr(); if (level >= 10 || level < 1)
@@ -528,13 +548,13 @@ export class Paragraph {
     /**
      * The character Office JS gives for this paragraph's mark at the end of its 'Whole' range (check 48):
      * `\t` for the last paragraph of a table cell, the cell's end; nothing for a mark tracked as deleted, which
-     * Word's default view doesn't show (CR-012 section 19, check 58); and `\r` for any other.
+     * Word's default view doesn't show (CR-012 section 19, check 58), or as moved from, as the paragraph's runs read
+     * (CR-002 section 64); and `\r` for any other.
      */
     get markText() {
-        var _a, _b;
         if (lastInCell(this.p))
             return '\t';
-        return ((_b = (_a = this.p.pPr) === null || _a === void 0 ? void 0 : _a.rPr) === null || _b === void 0 ? void 0 : _b.del) !== undefined ? '' : '\r';
+        return shownInDefaultView(this.p) ? '\r' : '';
     }
     /**
      * Removes the paragraph from its container. While the package tracks changes, the content

package/dist/model/content/Table.mjs

@@ -5,6 +5,8 @@ import { typeNameOf, childrenOf, linkParents, rowsOf, cellsOf, inBranch, assertO
 import { builtInOf, idOfBuiltIn, styleNameOf, styleIdOf } from './styles.mjs';
 import { trackInsertedBlocks } from './tracking.mjs';
 import { insertGridColumns, deleteGridColumns, gridRangeOf, textWidthTwips, widthTypeOf, layoutModeOf } from './tableColumns.mjs';
+import { withinWord, WORD_STORAGE } from './wordRange.mjs';
+import { assignParaIds } from './paraIds.mjs';
 /** The default table width in twips (A4 with 2.54 cm margins), as the objects package's `tbl` builder uses. */
 const DEFAULT_WIDTH = 9026;
 const TWIPS_PER_POINT = 20;
@@ -138,6 +140,7 @@ export class Table {
         container.splice(at, 0, ...added);
         for (const row of added)
             linkParents(row, this.tbl);
+        assignParaIds(this.tbl, added);
         markRowsInserted(this.changeTracker, added);
         return added.map((element) => new TableRow(element, container, this));
     }
@@ -176,6 +179,7 @@ export class Table {
         this.assertWritable();
         const at = location === 'Start' ? 0 : this.columnWidths().length;
         const inserted = insertGridColumns(this.tbl, this.textWidth(), at, columnCount, values, this.changeTracker);
+        assignParaIds(this.tbl, inserted.cells);
         return this.cellViewsOf(inserted.cells);
     }
     /**
@@ -328,6 +332,7 @@ export class TableRow {
         const owner = (_a = ownerOfArray(this.container, this.parentTable.tbl)) !== null && _a !== void 0 ? _a : this.parentTable.tbl;
         for (const row of added)
             linkParents(row, owner);
+        assignParaIds(this.parentTable.tbl, added);
         markRowsInserted(this.parentTable.changeTracker, added);
         return added.map((element) => new TableRow(element, this.container, this.parentTable));
     }
@@ -434,16 +439,14 @@ export class TableCell {
         var _a, _b;
         var _c, _d;
         this.assertWritable();
-        const twips = Math.round(points * TWIPS_PER_POINT);
+        // within the range Word 365 stores w:tcW/@w:w in, a percentage's fiftieths too (CR-002 section 65), before anything changes
+        const pct = widthTypeOf(this.tc, this.parentTable.tbl) === 'pct';
+        const w = pct
+            ? withinWord('TableCell.width', points, WORD_STORAGE.tcWPct, Math.round((Math.round(points * TWIPS_PER_POINT) * 5000) / this.parentTable.textWidth()))
+            : withinWord('TableCell.width', points, WORD_STORAGE.tcWDxa);
         const tcW = ((_b = (_d = ((_a = (_c = this.tc).tcPr) !== null && _a !== void 0 ? _a : (_c.tcPr = {}))).tcW) !== null && _b !== void 0 ? _b : (_d.tcW = {}));
-        if (widthTypeOf(this.tc, this.parentTable.tbl) === 'pct') {
-            tcW.w = Math.round((twips * 5000) / this.parentTable.textWidth());
-            tcW.type = 'pct';
-        }
-        else {
-            tcW.w = twips;
-            tcW.type = 'dxa';
-        }
+        tcW.w = w;
+        tcW.type = pct ? 'pct' : 'dxa';
     }
     /**
      * New columns before or after this cell (Office JS `TableCell.insertColumns`), the new cells
@@ -457,6 +460,7 @@ export class TableCell {
             throw new Docx4JException('This cell is not in its row');
         const table = this.parentTable;
         const inserted = insertGridColumns(table.tbl, table.textWidth(), location === 'Before' ? range.start : range.end, columnCount, values, table.changeTracker);
+        assignParaIds(table.tbl, inserted.cells);
         return table.cellViewsOf(inserted.cells);
     }
     /** Removes the grid columns this cell covers (Office JS `TableCell.deleteColumn`); tracked as `Table.deleteColumns` is. */
@@ -519,8 +523,8 @@ export function cellOf(value, parentBody) {
     }
     if (!tc)
         return undefined;
-    // a cell-level content control sits between the cell and the row
-    const tr = ancestorOf(tc, 'org_docx4j_wml.Tr', 4);
+    // cell-level content controls sit between the cell and the row, nested to any depth
+    const tr = ancestorOf(tc, 'org_docx4j_wml.Tr');
     if (!tr)
         return undefined;
     const tbl = ancestorTable(tr);
@@ -538,14 +542,20 @@ export function cellOf(value, parentBody) {
     const cell = cellsOf(tr, 'read').find((c) => c.element.value === tc);
     return cell ? new TableCell(cell.element, cell.container, rowView) : undefined;
 }
-/** The w:tbl a row is in, through a row-level content control if there is one. */
+/**
+ * The w:tbl a row is in, through the row-level content controls around it, nested to any depth: a repeating section's
+ * item inside the section puts four holders between the row and its table (the editor's finding on `invoice2013.docx`, 2026-10-26; CR-002 section 64).
+ */
 function ancestorTable(tr) {
-    return ancestorOf(tr, 'org_docx4j_wml.Tbl', 4);
+    return ancestorOf(tr, 'org_docx4j_wml.Tbl');
 }
-/** The nearest ancestor of a type, at most `depth` PARENT steps up (the sdt wrappers are steps). */
-function ancestorOf(value, typeName, depth) {
+/**
+ * The nearest ancestor of a type. Only holders stand between a cell and its row, or a row and its table (content
+ * controls, custom XML, a kept `mc:AlternateContent`'s branch), so the nearest is the one; the guard only stops a cycle.
+ */
+function ancestorOf(value, typeName) {
     let current = value.PARENT;
-    for (let guard = 0; current && guard < depth; guard++) {
+    for (let guard = 0; current && guard < 256; guard++) {
         if (typeNameOf(current) === typeName)
             return current;
         current = current.PARENT;

package/dist/model/content/TrackedChange.d.mts

@@ -195,8 +195,8 @@ export declare class TrackedChange {
     get author(): string;
     /**
      * When the change was made: `w16du:dateUtc` if the markup has it, else `w:date` read as Word writes
-     * it, local wall-clock time (`revisionDateOf`, CR-002 section 29); a group's is its first piece's,
-     * as Office JS reports it.
+     * it, local wall-clock time in the package's `dateTimeZone`, else the runtime's (`revisionDateOf`,
+     * CR-002 section 29, CR-018); a group's is its first piece's, as Office JS reports it.
      */
     get date(): Date | undefined;
     /** The annotation id (`w:id`; an extension). */

package/dist/model/content/TrackedChange.mjs

@@ -46,11 +46,12 @@ export class TrackedChange {
     }
     /**
      * When the change was made: `w16du:dateUtc` if the markup has it, else `w:date` read as Word writes
-     * it, local wall-clock time (`revisionDateOf`, CR-002 section 29); a group's is its first piece's,
-     * as Office JS reports it.
+     * it, local wall-clock time in the package's `dateTimeZone`, else the runtime's (`revisionDateOf`,
+     * CR-002 section 29, CR-018); a group's is its first piece's, as Office JS reports it.
      */
     get date() {
-        return revisionDateOf(this.target.value);
+        var _a;
+        return revisionDateOf(this.target.value, (_a = this.package_) === null || _a === void 0 ? void 0 : _a.dateTimeZone);
     }
     /** The annotation id (`w:id`; an extension). */
     get id() {
@@ -2071,6 +2072,8 @@ function tokensOfRunLevel(paragraph, items, out, listing) {
     var _a, _b, _c;
     for (let i = 0; i < items.length; i++) {
         const el = items[i];
+        if (el.value === undefined)
+            continue; // a DOM element a branch's wildcard keeps: no change in it to list (CR-026 section 4.8)
         // an inline control or custom XML element that is itself an insertion: a piece, then what is in it
         const inserted = holderChangeAt(items, i, paragraph);
         if (inserted) {