@eigenpal/docx-js-editor 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,2216 @@
1
+ /**
2
+ * Comprehensive TypeScript types for full DOCX document representation
3
+ *
4
+ * These types represent all elements that can appear in a DOCX file,
5
+ * supporting full Microsoft Word fidelity including:
6
+ * - Text and paragraph formatting
7
+ * - Tables, images, shapes
8
+ * - Hyperlinks, bookmarks, fields
9
+ * - Lists, headers/footers, footnotes
10
+ * - Themes, styles, page layout
11
+ */
12
+ /**
13
+ * Theme color slots from theme1.xml
14
+ */
15
+ type ThemeColorSlot = 'dk1' | 'lt1' | 'dk2' | 'lt2' | 'accent1' | 'accent2' | 'accent3' | 'accent4' | 'accent5' | 'accent6' | 'hlink' | 'folHlink' | 'background1' | 'text1' | 'background2' | 'text2';
16
+ /**
17
+ * Color value - can be direct RGB, theme reference, or auto
18
+ */
19
+ interface ColorValue {
20
+ /** RGB hex value without # (e.g., "FF0000") */
21
+ rgb?: string;
22
+ /** Theme color slot reference */
23
+ themeColor?: ThemeColorSlot;
24
+ /** Tint modifier (0-255 as hex string, e.g., "80") - makes color lighter */
25
+ themeTint?: string;
26
+ /** Shade modifier (0-255 as hex string) - makes color darker */
27
+ themeShade?: string;
28
+ /** Auto color - context-dependent (usually black for text) */
29
+ auto?: boolean;
30
+ }
31
+ /**
32
+ * Border specification for any border (paragraph, table, page)
33
+ */
34
+ interface BorderSpec {
35
+ /** Border style */
36
+ style: 'none' | 'single' | 'double' | 'dotted' | 'dashed' | 'thick' | 'triple' | 'thinThickSmallGap' | 'thickThinSmallGap' | 'thinThickMediumGap' | 'thickThinMediumGap' | 'thinThickLargeGap' | 'thickThinLargeGap' | 'wave' | 'doubleWave' | 'dashSmallGap' | 'dashDotStroked' | 'threeDEmboss' | 'threeDEngrave' | 'outset' | 'inset' | 'nil';
37
+ /** Color of the border */
38
+ color?: ColorValue;
39
+ /** Width in eighths of a point (1/8 pt) */
40
+ size?: number;
41
+ /** Spacing from text in points */
42
+ space?: number;
43
+ /** Shadow effect */
44
+ shadow?: boolean;
45
+ /** Frame effect */
46
+ frame?: boolean;
47
+ }
48
+ /**
49
+ * Shading/background properties
50
+ */
51
+ interface ShadingProperties {
52
+ /** Pattern fill color */
53
+ color?: ColorValue;
54
+ /** Background fill color */
55
+ fill?: ColorValue;
56
+ /** Shading pattern type */
57
+ pattern?: 'clear' | 'solid' | 'horzStripe' | 'vertStripe' | 'reverseDiagStripe' | 'diagStripe' | 'horzCross' | 'diagCross' | 'thinHorzStripe' | 'thinVertStripe' | 'thinReverseDiagStripe' | 'thinDiagStripe' | 'thinHorzCross' | 'thinDiagCross' | 'pct5' | 'pct10' | 'pct12' | 'pct15' | 'pct20' | 'pct25' | 'pct30' | 'pct35' | 'pct37' | 'pct40' | 'pct45' | 'pct50' | 'pct55' | 'pct60' | 'pct62' | 'pct65' | 'pct70' | 'pct75' | 'pct80' | 'pct85' | 'pct87' | 'pct90' | 'pct95' | 'nil';
58
+ }
59
+ /**
60
+ * Underline style options
61
+ */
62
+ type UnderlineStyle = 'none' | 'single' | 'words' | 'double' | 'thick' | 'dotted' | 'dottedHeavy' | 'dash' | 'dashedHeavy' | 'dashLong' | 'dashLongHeavy' | 'dotDash' | 'dashDotHeavy' | 'dotDotDash' | 'dashDotDotHeavy' | 'wave' | 'wavyHeavy' | 'wavyDouble';
63
+ /**
64
+ * Text effect animations
65
+ */
66
+ type TextEffect = 'none' | 'blinkBackground' | 'lights' | 'antsBlack' | 'antsRed' | 'shimmer' | 'sparkle';
67
+ /**
68
+ * Emphasis mark type
69
+ */
70
+ type EmphasisMark = 'none' | 'dot' | 'comma' | 'circle' | 'underDot';
71
+ /**
72
+ * Complete text formatting properties (w:rPr)
73
+ */
74
+ interface TextFormatting {
75
+ /** Bold (w:b) */
76
+ bold?: boolean;
77
+ /** Bold complex script (w:bCs) */
78
+ boldCs?: boolean;
79
+ /** Italic (w:i) */
80
+ italic?: boolean;
81
+ /** Italic complex script (w:iCs) */
82
+ italicCs?: boolean;
83
+ /** Underline style and color (w:u) */
84
+ underline?: {
85
+ style: UnderlineStyle;
86
+ color?: ColorValue;
87
+ };
88
+ /** Strikethrough (w:strike) */
89
+ strike?: boolean;
90
+ /** Double strikethrough (w:dstrike) */
91
+ doubleStrike?: boolean;
92
+ /** Superscript/subscript (w:vertAlign) */
93
+ vertAlign?: 'baseline' | 'superscript' | 'subscript';
94
+ /** Small caps (w:smallCaps) */
95
+ smallCaps?: boolean;
96
+ /** All caps (w:caps) */
97
+ allCaps?: boolean;
98
+ /** Hidden text (w:vanish) */
99
+ hidden?: boolean;
100
+ /** Text color (w:color) */
101
+ color?: ColorValue;
102
+ /** Highlight/background color (w:highlight) */
103
+ highlight?: 'black' | 'blue' | 'cyan' | 'darkBlue' | 'darkCyan' | 'darkGray' | 'darkGreen' | 'darkMagenta' | 'darkRed' | 'darkYellow' | 'green' | 'lightGray' | 'magenta' | 'none' | 'red' | 'white' | 'yellow';
104
+ /** Character shading (w:shd) */
105
+ shading?: ShadingProperties;
106
+ /** Font size in half-points (w:sz) - e.g., 24 = 12pt */
107
+ fontSize?: number;
108
+ /** Font size complex script (w:szCs) */
109
+ fontSizeCs?: number;
110
+ /** Font family (w:rFonts) */
111
+ fontFamily?: {
112
+ ascii?: string;
113
+ hAnsi?: string;
114
+ eastAsia?: string;
115
+ cs?: string;
116
+ /** Theme font reference */
117
+ asciiTheme?: 'majorAscii' | 'majorHAnsi' | 'majorEastAsia' | 'majorBidi' | 'minorAscii' | 'minorHAnsi' | 'minorEastAsia' | 'minorBidi';
118
+ hAnsiTheme?: string;
119
+ eastAsiaTheme?: string;
120
+ csTheme?: string;
121
+ };
122
+ /** Character spacing in twips (w:spacing) */
123
+ spacing?: number;
124
+ /** Raised/lowered text position in half-points (w:position) */
125
+ position?: number;
126
+ /** Horizontal text scale percentage (w:w) */
127
+ scale?: number;
128
+ /** Kerning threshold in half-points (w:kern) */
129
+ kerning?: number;
130
+ /** Text effect animation (w:effect) */
131
+ effect?: TextEffect;
132
+ /** Emphasis mark (w:em) */
133
+ emphasisMark?: EmphasisMark;
134
+ /** Emboss effect (w:emboss) */
135
+ emboss?: boolean;
136
+ /** Imprint/engrave effect (w:imprint) */
137
+ imprint?: boolean;
138
+ /** Outline effect (w:outline) */
139
+ outline?: boolean;
140
+ /** Shadow effect (w:shadow) */
141
+ shadow?: boolean;
142
+ /** Right-to-left text (w:rtl) */
143
+ rtl?: boolean;
144
+ /** Complex script formatting (w:cs) */
145
+ cs?: boolean;
146
+ /** Character style ID (w:rStyle) */
147
+ styleId?: string;
148
+ }
149
+ /**
150
+ * Tab stop alignment
151
+ */
152
+ type TabStopAlignment = 'left' | 'center' | 'right' | 'decimal' | 'bar' | 'clear' | 'num';
153
+ /**
154
+ * Tab leader character
155
+ */
156
+ type TabLeader = 'none' | 'dot' | 'hyphen' | 'underscore' | 'heavy' | 'middleDot';
157
+ /**
158
+ * Tab stop definition
159
+ */
160
+ interface TabStop {
161
+ /** Position in twips from left margin */
162
+ position: number;
163
+ /** Alignment at tab stop */
164
+ alignment: TabStopAlignment;
165
+ /** Leader character */
166
+ leader?: TabLeader;
167
+ }
168
+ /**
169
+ * Line spacing rule
170
+ */
171
+ type LineSpacingRule = 'auto' | 'exact' | 'atLeast';
172
+ /**
173
+ * Paragraph alignment/justification
174
+ */
175
+ type ParagraphAlignment = 'left' | 'center' | 'right' | 'both' | 'distribute' | 'mediumKashida' | 'highKashida' | 'lowKashida' | 'thaiDistribute';
176
+ /**
177
+ * Complete paragraph formatting properties (w:pPr)
178
+ */
179
+ interface ParagraphFormatting {
180
+ /** Paragraph alignment (w:jc) */
181
+ alignment?: ParagraphAlignment;
182
+ /** Text direction (w:bidi) */
183
+ bidi?: boolean;
184
+ /** Spacing before in twips (w:spacing/@w:before) */
185
+ spaceBefore?: number;
186
+ /** Spacing after in twips (w:spacing/@w:after) */
187
+ spaceAfter?: number;
188
+ /** Line spacing value (w:spacing/@w:line) */
189
+ lineSpacing?: number;
190
+ /** Line spacing rule (w:spacing/@w:lineRule) */
191
+ lineSpacingRule?: LineSpacingRule;
192
+ /** Auto space before (w:spacing/@w:beforeAutospacing) */
193
+ beforeAutospacing?: boolean;
194
+ /** Auto space after (w:spacing/@w:afterAutospacing) */
195
+ afterAutospacing?: boolean;
196
+ /** Left indent in twips (w:ind/@w:left) */
197
+ indentLeft?: number;
198
+ /** Right indent in twips (w:ind/@w:right) */
199
+ indentRight?: number;
200
+ /** First line indent in twips - positive for indent, negative for hanging (w:ind/@w:firstLine or @w:hanging) */
201
+ indentFirstLine?: number;
202
+ /** Whether first line is hanging indent */
203
+ hangingIndent?: boolean;
204
+ /** Paragraph borders (w:pBdr) */
205
+ borders?: {
206
+ top?: BorderSpec;
207
+ bottom?: BorderSpec;
208
+ left?: BorderSpec;
209
+ right?: BorderSpec;
210
+ between?: BorderSpec;
211
+ bar?: BorderSpec;
212
+ };
213
+ /** Paragraph shading (w:shd) */
214
+ shading?: ShadingProperties;
215
+ /** Custom tab stops (w:tabs) */
216
+ tabs?: TabStop[];
217
+ /** Keep with next paragraph (w:keepNext) */
218
+ keepNext?: boolean;
219
+ /** Keep lines together (w:keepLines) */
220
+ keepLines?: boolean;
221
+ /** Widow/orphan control (w:widowControl) */
222
+ widowControl?: boolean;
223
+ /** Page break before (w:pageBreakBefore) */
224
+ pageBreakBefore?: boolean;
225
+ /** Numbering properties (w:numPr) */
226
+ numPr?: {
227
+ /** Numbering definition ID (w:numId) */
228
+ numId?: number;
229
+ /** List level (0-8) (w:ilvl) */
230
+ ilvl?: number;
231
+ };
232
+ /** Outline level 0-9 (w:outlineLvl) */
233
+ outlineLevel?: number;
234
+ /** Paragraph style ID (w:pStyle) */
235
+ styleId?: string;
236
+ /** Text frame properties (w:framePr) */
237
+ frame?: {
238
+ width?: number;
239
+ height?: number;
240
+ hAnchor?: 'text' | 'margin' | 'page';
241
+ vAnchor?: 'text' | 'margin' | 'page';
242
+ x?: number;
243
+ y?: number;
244
+ xAlign?: 'left' | 'center' | 'right' | 'inside' | 'outside';
245
+ yAlign?: 'top' | 'center' | 'bottom' | 'inside' | 'outside' | 'inline';
246
+ wrap?: 'around' | 'auto' | 'none' | 'notBeside' | 'through' | 'tight';
247
+ };
248
+ /** Suppress line numbers (w:suppressLineNumbers) */
249
+ suppressLineNumbers?: boolean;
250
+ /** Suppress auto hyphens (w:suppressAutoHyphens) */
251
+ suppressAutoHyphens?: boolean;
252
+ /** Run properties to apply to all runs (w:rPr) */
253
+ runProperties?: TextFormatting;
254
+ }
255
+ /**
256
+ * Plain text content
257
+ */
258
+ interface TextContent {
259
+ type: 'text';
260
+ /** The text string */
261
+ text: string;
262
+ /** Preserve whitespace (xml:space="preserve") */
263
+ preserveSpace?: boolean;
264
+ }
265
+ /**
266
+ * Tab character
267
+ */
268
+ interface TabContent {
269
+ type: 'tab';
270
+ }
271
+ /**
272
+ * Line break
273
+ */
274
+ interface BreakContent {
275
+ type: 'break';
276
+ /** Break type */
277
+ breakType?: 'page' | 'column' | 'textWrapping';
278
+ /** Clear type for text wrapping break */
279
+ clear?: 'none' | 'left' | 'right' | 'all';
280
+ }
281
+ /**
282
+ * Symbol character (special font character)
283
+ */
284
+ interface SymbolContent {
285
+ type: 'symbol';
286
+ /** Font name */
287
+ font: string;
288
+ /** Character code */
289
+ char: string;
290
+ }
291
+ /**
292
+ * Footnote or endnote reference
293
+ */
294
+ interface NoteReferenceContent {
295
+ type: 'footnoteRef' | 'endnoteRef';
296
+ /** Note ID */
297
+ id: number;
298
+ }
299
+ /**
300
+ * Field character (begin/separate/end)
301
+ */
302
+ interface FieldCharContent {
303
+ type: 'fieldChar';
304
+ /** Field character type */
305
+ charType: 'begin' | 'separate' | 'end';
306
+ /** Field is locked */
307
+ fldLock?: boolean;
308
+ /** Field is dirty (needs update) */
309
+ dirty?: boolean;
310
+ }
311
+ /**
312
+ * Field instruction text
313
+ */
314
+ interface InstrTextContent {
315
+ type: 'instrText';
316
+ /** Field instruction */
317
+ text: string;
318
+ }
319
+ /**
320
+ * Soft hyphen
321
+ */
322
+ interface SoftHyphenContent {
323
+ type: 'softHyphen';
324
+ }
325
+ /**
326
+ * Non-breaking hyphen
327
+ */
328
+ interface NoBreakHyphenContent {
329
+ type: 'noBreakHyphen';
330
+ }
331
+ /**
332
+ * Drawing/image reference
333
+ */
334
+ interface DrawingContent {
335
+ type: 'drawing';
336
+ /** Image data */
337
+ image: Image;
338
+ }
339
+ /**
340
+ * Shape reference
341
+ */
342
+ interface ShapeContent {
343
+ type: 'shape';
344
+ /** Shape data */
345
+ shape: Shape;
346
+ }
347
+ /**
348
+ * All possible run content types
349
+ */
350
+ type RunContent = TextContent | TabContent | BreakContent | SymbolContent | NoteReferenceContent | FieldCharContent | InstrTextContent | SoftHyphenContent | NoBreakHyphenContent | DrawingContent | ShapeContent;
351
+ /**
352
+ * A run is a contiguous region of text with the same formatting
353
+ */
354
+ interface Run {
355
+ type: 'run';
356
+ /** Text formatting properties */
357
+ formatting?: TextFormatting;
358
+ /** Run content (text, tabs, breaks, etc.) */
359
+ content: RunContent[];
360
+ }
361
+ /**
362
+ * Hyperlink (w:hyperlink)
363
+ */
364
+ interface Hyperlink {
365
+ type: 'hyperlink';
366
+ /** Relationship ID for external link */
367
+ rId?: string;
368
+ /** Resolved URL (from relationships) */
369
+ href?: string;
370
+ /** Internal bookmark anchor */
371
+ anchor?: string;
372
+ /** Tooltip text */
373
+ tooltip?: string;
374
+ /** Target frame */
375
+ target?: string;
376
+ /** Link history tracking */
377
+ history?: boolean;
378
+ /** Document location */
379
+ docLocation?: string;
380
+ /** Child runs */
381
+ children: (Run | BookmarkStart | BookmarkEnd)[];
382
+ }
383
+ /**
384
+ * Bookmark start marker (w:bookmarkStart)
385
+ */
386
+ interface BookmarkStart {
387
+ type: 'bookmarkStart';
388
+ /** Bookmark ID */
389
+ id: number;
390
+ /** Bookmark name */
391
+ name: string;
392
+ /** Column index for table bookmarks */
393
+ colFirst?: number;
394
+ colLast?: number;
395
+ }
396
+ /**
397
+ * Bookmark end marker (w:bookmarkEnd)
398
+ */
399
+ interface BookmarkEnd {
400
+ type: 'bookmarkEnd';
401
+ /** Bookmark ID */
402
+ id: number;
403
+ }
404
+ /**
405
+ * Known field types
406
+ */
407
+ type FieldType = 'PAGE' | 'NUMPAGES' | 'NUMWORDS' | 'NUMCHARS' | 'DATE' | 'TIME' | 'CREATEDATE' | 'SAVEDATE' | 'PRINTDATE' | 'AUTHOR' | 'TITLE' | 'SUBJECT' | 'KEYWORDS' | 'COMMENTS' | 'FILENAME' | 'FILESIZE' | 'TEMPLATE' | 'DOCPROPERTY' | 'DOCVARIABLE' | 'REF' | 'PAGEREF' | 'NOTEREF' | 'HYPERLINK' | 'TOC' | 'TOA' | 'INDEX' | 'SEQ' | 'STYLEREF' | 'AUTONUM' | 'AUTONUMLGL' | 'AUTONUMOUT' | 'IF' | 'MERGEFIELD' | 'NEXT' | 'NEXTIF' | 'ASK' | 'SET' | 'QUOTE' | 'INCLUDETEXT' | 'INCLUDEPICTURE' | 'SYMBOL' | 'ADVANCE' | 'EDITTIME' | 'REVNUM' | 'SECTION' | 'SECTIONPAGES' | 'USERADDRESS' | 'USERNAME' | 'USERINITIALS' | 'UNKNOWN';
408
+ /**
409
+ * Simple field (w:fldSimple)
410
+ */
411
+ interface SimpleField {
412
+ type: 'simpleField';
413
+ /** Field instruction (e.g., "PAGE \\* MERGEFORMAT") */
414
+ instruction: string;
415
+ /** Parsed field type */
416
+ fieldType: FieldType;
417
+ /** Current display value */
418
+ content: (Run | Hyperlink)[];
419
+ /** Field is locked */
420
+ fldLock?: boolean;
421
+ /** Field is dirty */
422
+ dirty?: boolean;
423
+ }
424
+ /**
425
+ * Complex field (w:fldChar begin/separate/end with w:instrText)
426
+ */
427
+ interface ComplexField {
428
+ type: 'complexField';
429
+ /** Field instruction */
430
+ instruction: string;
431
+ /** Parsed field type */
432
+ fieldType: FieldType;
433
+ /** Field code runs */
434
+ fieldCode: Run[];
435
+ /** Display result runs */
436
+ fieldResult: Run[];
437
+ /** Field is locked */
438
+ fldLock?: boolean;
439
+ /** Field is dirty */
440
+ dirty?: boolean;
441
+ }
442
+ type Field = SimpleField | ComplexField;
443
+ /**
444
+ * Image size specification
445
+ */
446
+ interface ImageSize {
447
+ /** Width in EMUs (English Metric Units) */
448
+ width: number;
449
+ /** Height in EMUs */
450
+ height: number;
451
+ }
452
+ /**
453
+ * Image wrap type for floating images
454
+ */
455
+ interface ImageWrap {
456
+ type: 'inline' | 'square' | 'tight' | 'through' | 'topAndBottom' | 'behind' | 'inFront';
457
+ /** Wrap text direction */
458
+ wrapText?: 'bothSides' | 'left' | 'right' | 'largest';
459
+ /** Distance from text */
460
+ distT?: number;
461
+ distB?: number;
462
+ distL?: number;
463
+ distR?: number;
464
+ }
465
+ /**
466
+ * Position for floating images
467
+ */
468
+ interface ImagePosition {
469
+ /** Horizontal positioning */
470
+ horizontal: {
471
+ relativeTo: 'character' | 'column' | 'insideMargin' | 'leftMargin' | 'margin' | 'outsideMargin' | 'page' | 'rightMargin';
472
+ alignment?: 'left' | 'right' | 'center' | 'inside' | 'outside';
473
+ posOffset?: number;
474
+ };
475
+ /** Vertical positioning */
476
+ vertical: {
477
+ relativeTo: 'insideMargin' | 'line' | 'margin' | 'outsideMargin' | 'page' | 'paragraph' | 'topMargin' | 'bottomMargin';
478
+ alignment?: 'top' | 'bottom' | 'center' | 'inside' | 'outside';
479
+ posOffset?: number;
480
+ };
481
+ }
482
+ /**
483
+ * Image transformation
484
+ */
485
+ interface ImageTransform {
486
+ /** Rotation in degrees */
487
+ rotation?: number;
488
+ /** Flip horizontal */
489
+ flipH?: boolean;
490
+ /** Flip vertical */
491
+ flipV?: boolean;
492
+ }
493
+ /**
494
+ * Image padding/margins
495
+ */
496
+ interface ImagePadding {
497
+ top?: number;
498
+ bottom?: number;
499
+ left?: number;
500
+ right?: number;
501
+ }
502
+ /**
503
+ * Embedded image (w:drawing)
504
+ */
505
+ interface Image {
506
+ type: 'image';
507
+ /** Unique ID */
508
+ id?: string;
509
+ /** Relationship ID for the image data */
510
+ rId: string;
511
+ /** Resolved image data (base64 or blob URL) */
512
+ src?: string;
513
+ /** Image MIME type */
514
+ mimeType?: string;
515
+ /** Original filename */
516
+ filename?: string;
517
+ /** Alt text for accessibility */
518
+ alt?: string;
519
+ /** Title/description */
520
+ title?: string;
521
+ /** Image size */
522
+ size: ImageSize;
523
+ /** Original size before any transforms */
524
+ originalSize?: ImageSize;
525
+ /** Wrap settings */
526
+ wrap: ImageWrap;
527
+ /** Position for floating images */
528
+ position?: ImagePosition;
529
+ /** Image transformations */
530
+ transform?: ImageTransform;
531
+ /** Padding around image */
532
+ padding?: ImagePadding;
533
+ /** Whether this is a decorative image */
534
+ decorative?: boolean;
535
+ /** Image effects */
536
+ effects?: {
537
+ brightness?: number;
538
+ contrast?: number;
539
+ saturation?: number;
540
+ };
541
+ }
542
+ /**
543
+ * Shape types
544
+ */
545
+ type ShapeType = 'rect' | 'roundRect' | 'ellipse' | 'triangle' | 'rtTriangle' | 'parallelogram' | 'trapezoid' | 'pentagon' | 'hexagon' | 'heptagon' | 'octagon' | 'decagon' | 'dodecagon' | 'star4' | 'star5' | 'star6' | 'star7' | 'star8' | 'star10' | 'star12' | 'star16' | 'star24' | 'star32' | 'line' | 'straightConnector1' | 'bentConnector2' | 'bentConnector3' | 'bentConnector4' | 'bentConnector5' | 'curvedConnector2' | 'curvedConnector3' | 'curvedConnector4' | 'curvedConnector5' | 'rightArrow' | 'leftArrow' | 'upArrow' | 'downArrow' | 'leftRightArrow' | 'upDownArrow' | 'quadArrow' | 'leftRightUpArrow' | 'bentArrow' | 'uturnArrow' | 'leftUpArrow' | 'bentUpArrow' | 'curvedRightArrow' | 'curvedLeftArrow' | 'curvedUpArrow' | 'curvedDownArrow' | 'stripedRightArrow' | 'notchedRightArrow' | 'homePlate' | 'chevron' | 'rightArrowCallout' | 'downArrowCallout' | 'leftArrowCallout' | 'upArrowCallout' | 'leftRightArrowCallout' | 'quadArrowCallout' | 'circularArrow' | 'flowChartProcess' | 'flowChartAlternateProcess' | 'flowChartDecision' | 'flowChartInputOutput' | 'flowChartPredefinedProcess' | 'flowChartInternalStorage' | 'flowChartDocument' | 'flowChartMultidocument' | 'flowChartTerminator' | 'flowChartPreparation' | 'flowChartManualInput' | 'flowChartManualOperation' | 'flowChartConnector' | 'flowChartOffpageConnector' | 'flowChartPunchedCard' | 'flowChartPunchedTape' | 'flowChartSummingJunction' | 'flowChartOr' | 'flowChartCollate' | 'flowChartSort' | 'flowChartExtract' | 'flowChartMerge' | 'flowChartOnlineStorage' | 'flowChartDelay' | 'flowChartMagneticTape' | 'flowChartMagneticDisk' | 'flowChartMagneticDrum' | 'flowChartDisplay' | 'wedgeRectCallout' | 'wedgeRoundRectCallout' | 'wedgeEllipseCallout' | 'cloudCallout' | 'borderCallout1' | 'borderCallout2' | 'borderCallout3' | 'accentCallout1' | 'accentCallout2' | 'accentCallout3' | 'callout1' | 'callout2' | 'callout3' | 'accentBorderCallout1' | 'accentBorderCallout2' | 'accentBorderCallout3' | 'actionButtonBlank' | 'actionButtonHome' | 'actionButtonHelp' | 'actionButtonInformation' | 'actionButtonBackPrevious' | 'actionButtonForwardNext' | 'actionButtonBeginning' | 'actionButtonEnd' | 'actionButtonReturn' | 'actionButtonDocument' | 'actionButtonSound' | 'actionButtonMovie' | 'irregularSeal1' | 'irregularSeal2' | 'frame' | 'halfFrame' | 'corner' | 'diagStripe' | 'chord' | 'arc' | 'bracketPair' | 'bracePair' | 'leftBracket' | 'rightBracket' | 'leftBrace' | 'rightBrace' | 'can' | 'cube' | 'bevel' | 'donut' | 'noSmoking' | 'blockArc' | 'foldedCorner' | 'smileyFace' | 'heart' | 'lightningBolt' | 'sun' | 'moon' | 'cloud' | 'snip1Rect' | 'snip2SameRect' | 'snip2DiagRect' | 'snipRoundRect' | 'round1Rect' | 'round2SameRect' | 'round2DiagRect' | 'plaque' | 'teardrop' | 'mathPlus' | 'mathMinus' | 'mathMultiply' | 'mathDivide' | 'mathEqual' | 'mathNotEqual' | 'gear6' | 'gear9' | 'funnel' | 'pieWedge' | 'pie' | 'leftCircularArrow' | 'leftRightCircularArrow' | 'swooshArrow' | 'textBox';
546
+ /**
547
+ * Shape fill type
548
+ */
549
+ interface ShapeFill {
550
+ type: 'none' | 'solid' | 'gradient' | 'pattern' | 'picture';
551
+ /** Solid fill color */
552
+ color?: ColorValue;
553
+ /** Gradient stops for gradient fill */
554
+ gradient?: {
555
+ type: 'linear' | 'radial' | 'rectangular' | 'path';
556
+ angle?: number;
557
+ stops: Array<{
558
+ position: number;
559
+ color: ColorValue;
560
+ }>;
561
+ };
562
+ }
563
+ /**
564
+ * Shape outline/stroke
565
+ */
566
+ interface ShapeOutline {
567
+ /** Line width in EMUs */
568
+ width?: number;
569
+ /** Line color */
570
+ color?: ColorValue;
571
+ /** Line style */
572
+ style?: 'solid' | 'dot' | 'dash' | 'lgDash' | 'dashDot' | 'lgDashDot' | 'lgDashDotDot' | 'sysDot' | 'sysDash' | 'sysDashDot' | 'sysDashDotDot';
573
+ /** Line cap */
574
+ cap?: 'flat' | 'round' | 'square';
575
+ /** Line join */
576
+ join?: 'bevel' | 'miter' | 'round';
577
+ /** Head arrow */
578
+ headEnd?: {
579
+ type: 'none' | 'triangle' | 'stealth' | 'diamond' | 'oval' | 'arrow';
580
+ width?: 'sm' | 'med' | 'lg';
581
+ length?: 'sm' | 'med' | 'lg';
582
+ };
583
+ /** Tail arrow */
584
+ tailEnd?: {
585
+ type: 'none' | 'triangle' | 'stealth' | 'diamond' | 'oval' | 'arrow';
586
+ width?: 'sm' | 'med' | 'lg';
587
+ length?: 'sm' | 'med' | 'lg';
588
+ };
589
+ }
590
+ /**
591
+ * Text body inside a shape
592
+ */
593
+ interface ShapeTextBody {
594
+ /** Text direction */
595
+ vertical?: boolean;
596
+ /** Rotation */
597
+ rotation?: number;
598
+ /** Anchor/vertical alignment */
599
+ anchor?: 'top' | 'middle' | 'bottom' | 'distributed' | 'justified';
600
+ /** Anchor center */
601
+ anchorCenter?: boolean;
602
+ /** Auto fit */
603
+ autoFit?: 'none' | 'normal' | 'shape';
604
+ /** Text margins */
605
+ margins?: {
606
+ top?: number;
607
+ bottom?: number;
608
+ left?: number;
609
+ right?: number;
610
+ };
611
+ /** Paragraphs inside the shape */
612
+ content: Paragraph[];
613
+ }
614
+ /**
615
+ * Shape/drawing object (wps:wsp)
616
+ */
617
+ interface Shape {
618
+ type: 'shape';
619
+ /** Shape type preset */
620
+ shapeType: ShapeType;
621
+ /** Unique ID */
622
+ id?: string;
623
+ /** Name */
624
+ name?: string;
625
+ /** Size in EMUs */
626
+ size: ImageSize;
627
+ /** Position for floating shapes */
628
+ position?: ImagePosition;
629
+ /** Wrap settings */
630
+ wrap?: ImageWrap;
631
+ /** Fill */
632
+ fill?: ShapeFill;
633
+ /** Outline/stroke */
634
+ outline?: ShapeOutline;
635
+ /** Transform */
636
+ transform?: ImageTransform;
637
+ /** Text content inside the shape */
638
+ textBody?: ShapeTextBody;
639
+ /** Custom geometry points */
640
+ customGeometry?: string;
641
+ }
642
+ /**
643
+ * Text box (floating text container)
644
+ */
645
+ interface TextBox {
646
+ type: 'textBox';
647
+ /** Unique ID */
648
+ id?: string;
649
+ /** Size */
650
+ size: ImageSize;
651
+ /** Position */
652
+ position?: ImagePosition;
653
+ /** Wrap settings */
654
+ wrap?: ImageWrap;
655
+ /** Fill */
656
+ fill?: ShapeFill;
657
+ /** Outline */
658
+ outline?: ShapeOutline;
659
+ /** Text content */
660
+ content: Paragraph[];
661
+ /** Internal margins */
662
+ margins?: {
663
+ top?: number;
664
+ bottom?: number;
665
+ left?: number;
666
+ right?: number;
667
+ };
668
+ }
669
+ /**
670
+ * Table width type
671
+ */
672
+ type TableWidthType = 'auto' | 'dxa' | 'nil' | 'pct';
673
+ /**
674
+ * Table measurement (width or height)
675
+ */
676
+ interface TableMeasurement {
677
+ /** Value in twips (for dxa) or fifths of a percent (for pct) */
678
+ value: number;
679
+ /** Measurement type */
680
+ type: TableWidthType;
681
+ }
682
+ /**
683
+ * Table borders
684
+ */
685
+ interface TableBorders {
686
+ top?: BorderSpec;
687
+ bottom?: BorderSpec;
688
+ left?: BorderSpec;
689
+ right?: BorderSpec;
690
+ insideH?: BorderSpec;
691
+ insideV?: BorderSpec;
692
+ }
693
+ /**
694
+ * Cell margins
695
+ */
696
+ interface CellMargins {
697
+ top?: TableMeasurement;
698
+ bottom?: TableMeasurement;
699
+ left?: TableMeasurement;
700
+ right?: TableMeasurement;
701
+ }
702
+ /**
703
+ * Table look flags (for table styles)
704
+ */
705
+ interface TableLook {
706
+ firstColumn?: boolean;
707
+ firstRow?: boolean;
708
+ lastColumn?: boolean;
709
+ lastRow?: boolean;
710
+ noHBand?: boolean;
711
+ noVBand?: boolean;
712
+ }
713
+ /**
714
+ * Floating table properties
715
+ */
716
+ interface FloatingTableProperties {
717
+ /** Horizontal anchor */
718
+ horzAnchor?: 'margin' | 'page' | 'text';
719
+ /** Vertical anchor */
720
+ vertAnchor?: 'margin' | 'page' | 'text';
721
+ /** Horizontal position */
722
+ tblpX?: number;
723
+ tblpXSpec?: 'left' | 'center' | 'right' | 'inside' | 'outside';
724
+ /** Vertical position */
725
+ tblpY?: number;
726
+ tblpYSpec?: 'top' | 'center' | 'bottom' | 'inside' | 'outside' | 'inline';
727
+ /** Distance from surrounding text */
728
+ topFromText?: number;
729
+ bottomFromText?: number;
730
+ leftFromText?: number;
731
+ rightFromText?: number;
732
+ }
733
+ /**
734
+ * Table formatting properties (w:tblPr)
735
+ */
736
+ interface TableFormatting {
737
+ /** Table width */
738
+ width?: TableMeasurement;
739
+ /** Table justification */
740
+ justification?: 'left' | 'center' | 'right';
741
+ /** Cell spacing */
742
+ cellSpacing?: TableMeasurement;
743
+ /** Table indent from left margin */
744
+ indent?: TableMeasurement;
745
+ /** Table borders */
746
+ borders?: TableBorders;
747
+ /** Default cell margins */
748
+ cellMargins?: CellMargins;
749
+ /** Table layout */
750
+ layout?: 'fixed' | 'autofit';
751
+ /** Table style ID */
752
+ styleId?: string;
753
+ /** Table look (conditional formatting flags) */
754
+ look?: TableLook;
755
+ /** Shading/background */
756
+ shading?: ShadingProperties;
757
+ /** Overlap for floating tables */
758
+ overlap?: 'never' | 'overlap';
759
+ /** Floating table properties */
760
+ floating?: FloatingTableProperties;
761
+ /** Right to left table */
762
+ bidi?: boolean;
763
+ }
764
+ /**
765
+ * Table row formatting properties (w:trPr)
766
+ */
767
+ interface TableRowFormatting {
768
+ /** Row height */
769
+ height?: TableMeasurement;
770
+ /** Height rule */
771
+ heightRule?: 'auto' | 'atLeast' | 'exact';
772
+ /** Header row (repeats on each page) */
773
+ header?: boolean;
774
+ /** Allow row to break across pages */
775
+ cantSplit?: boolean;
776
+ /** Row justification */
777
+ justification?: 'left' | 'center' | 'right';
778
+ /** Hidden row */
779
+ hidden?: boolean;
780
+ }
781
+ /**
782
+ * Conditional format style
783
+ */
784
+ interface ConditionalFormatStyle {
785
+ /** First row */
786
+ firstRow?: boolean;
787
+ /** Last row */
788
+ lastRow?: boolean;
789
+ /** First column */
790
+ firstColumn?: boolean;
791
+ /** Last column */
792
+ lastColumn?: boolean;
793
+ /** Odd horizontal band */
794
+ oddHBand?: boolean;
795
+ /** Even horizontal band */
796
+ evenHBand?: boolean;
797
+ /** Odd vertical band */
798
+ oddVBand?: boolean;
799
+ /** Even vertical band */
800
+ evenVBand?: boolean;
801
+ /** Northwest corner */
802
+ nwCell?: boolean;
803
+ /** Northeast corner */
804
+ neCell?: boolean;
805
+ /** Southwest corner */
806
+ swCell?: boolean;
807
+ /** Southeast corner */
808
+ seCell?: boolean;
809
+ }
810
+ /**
811
+ * Table cell formatting properties (w:tcPr)
812
+ */
813
+ interface TableCellFormatting {
814
+ /** Cell width */
815
+ width?: TableMeasurement;
816
+ /** Cell borders */
817
+ borders?: TableBorders;
818
+ /** Cell margins (override table default) */
819
+ margins?: CellMargins;
820
+ /** Cell shading/background */
821
+ shading?: ShadingProperties;
822
+ /** Vertical alignment */
823
+ verticalAlign?: 'top' | 'center' | 'bottom';
824
+ /** Text direction */
825
+ textDirection?: 'lr' | 'lrV' | 'rl' | 'rlV' | 'tb' | 'tbV' | 'tbRl' | 'tbRlV' | 'btLr';
826
+ /** Grid span (horizontal merge) */
827
+ gridSpan?: number;
828
+ /** Vertical merge */
829
+ vMerge?: 'restart' | 'continue';
830
+ /** Fit text to cell width */
831
+ fitText?: boolean;
832
+ /** Wrap text */
833
+ noWrap?: boolean;
834
+ /** Hide cell marker */
835
+ hideMark?: boolean;
836
+ /** Conditional format style */
837
+ conditionalFormat?: ConditionalFormatStyle;
838
+ }
839
+ /**
840
+ * Table cell
841
+ */
842
+ interface TableCell {
843
+ type: 'tableCell';
844
+ /** Cell formatting */
845
+ formatting?: TableCellFormatting;
846
+ /** Cell content (paragraphs, tables, etc.) */
847
+ content: (Paragraph | Table)[];
848
+ }
849
+ /**
850
+ * Table row
851
+ */
852
+ interface TableRow {
853
+ type: 'tableRow';
854
+ /** Row formatting */
855
+ formatting?: TableRowFormatting;
856
+ /** Cells in this row */
857
+ cells: TableCell[];
858
+ }
859
+ /**
860
+ * Table (w:tbl)
861
+ */
862
+ interface Table {
863
+ type: 'table';
864
+ /** Table formatting */
865
+ formatting?: TableFormatting;
866
+ /** Column widths in twips */
867
+ columnWidths?: number[];
868
+ /** Table rows */
869
+ rows: TableRow[];
870
+ }
871
+ /**
872
+ * Number format type
873
+ */
874
+ type NumberFormat = 'decimal' | 'upperRoman' | 'lowerRoman' | 'upperLetter' | 'lowerLetter' | 'ordinal' | 'cardinalText' | 'ordinalText' | 'hex' | 'chicago' | 'ideographDigital' | 'japaneseCounting' | 'aiueo' | 'iroha' | 'decimalFullWidth' | 'decimalHalfWidth' | 'japaneseLegal' | 'japaneseDigitalTenThousand' | 'decimalEnclosedCircle' | 'decimalFullWidth2' | 'aiueoFullWidth' | 'irohaFullWidth' | 'decimalZero' | 'bullet' | 'ganada' | 'chosung' | 'decimalEnclosedFullstop' | 'decimalEnclosedParen' | 'decimalEnclosedCircleChinese' | 'ideographEnclosedCircle' | 'ideographTraditional' | 'ideographZodiac' | 'ideographZodiacTraditional' | 'taiwaneseCounting' | 'ideographLegalTraditional' | 'taiwaneseCountingThousand' | 'taiwaneseDigital' | 'chineseCounting' | 'chineseLegalSimplified' | 'chineseCountingThousand' | 'koreanDigital' | 'koreanCounting' | 'koreanLegal' | 'koreanDigital2' | 'vietnameseCounting' | 'russianLower' | 'russianUpper' | 'none' | 'numberInDash' | 'hebrew1' | 'hebrew2' | 'arabicAlpha' | 'arabicAbjad' | 'hindiVowels' | 'hindiConsonants' | 'hindiNumbers' | 'hindiCounting' | 'thaiLetters' | 'thaiNumbers' | 'thaiCounting';
875
+ /**
876
+ * Multi-level suffix (what follows the number)
877
+ */
878
+ type LevelSuffix = 'tab' | 'space' | 'nothing';
879
+ /**
880
+ * List level definition
881
+ */
882
+ interface ListLevel {
883
+ /** Level index (0-8) */
884
+ ilvl: number;
885
+ /** Starting number */
886
+ start?: number;
887
+ /** Number format */
888
+ numFmt: NumberFormat;
889
+ /** Level text (e.g., "%1." or "•") */
890
+ lvlText: string;
891
+ /** Justification */
892
+ lvlJc?: 'left' | 'center' | 'right';
893
+ /** Suffix after number */
894
+ suffix?: LevelSuffix;
895
+ /** Paragraph properties for this level */
896
+ pPr?: ParagraphFormatting;
897
+ /** Run properties for the number/bullet */
898
+ rPr?: TextFormatting;
899
+ /** Restart numbering from higher level */
900
+ lvlRestart?: number;
901
+ /** Is legal numbering style */
902
+ isLgl?: boolean;
903
+ /** Legacy settings */
904
+ legacy?: {
905
+ legacy?: boolean;
906
+ legacySpace?: number;
907
+ legacyIndent?: number;
908
+ };
909
+ }
910
+ /**
911
+ * Abstract numbering definition (w:abstractNum)
912
+ */
913
+ interface AbstractNumbering {
914
+ /** Abstract numbering ID */
915
+ abstractNumId: number;
916
+ /** Multi-level type */
917
+ multiLevelType?: 'hybridMultilevel' | 'multilevel' | 'singleLevel';
918
+ /** Numbering style link */
919
+ numStyleLink?: string;
920
+ /** Style link */
921
+ styleLink?: string;
922
+ /** Level definitions */
923
+ levels: ListLevel[];
924
+ /** Name */
925
+ name?: string;
926
+ }
927
+ /**
928
+ * Numbering instance (w:num)
929
+ */
930
+ interface NumberingInstance {
931
+ /** Numbering ID (referenced by paragraphs) */
932
+ numId: number;
933
+ /** Reference to abstract numbering */
934
+ abstractNumId: number;
935
+ /** Level overrides */
936
+ levelOverrides?: Array<{
937
+ ilvl: number;
938
+ startOverride?: number;
939
+ lvl?: ListLevel;
940
+ }>;
941
+ }
942
+ /**
943
+ * Computed list rendering info
944
+ */
945
+ interface ListRendering {
946
+ /** Computed marker text (e.g., "1.", "a)", "•") */
947
+ marker: string;
948
+ /** List level (0-8) */
949
+ level: number;
950
+ /** Numbering ID */
951
+ numId: number;
952
+ /** Whether this is a bullet or numbered list */
953
+ isBullet: boolean;
954
+ /** Number format type (decimal, lowerRoman, upperRoman, etc.) */
955
+ numFmt?: NumberFormat;
956
+ }
957
+ /**
958
+ * Complete numbering definitions
959
+ */
960
+ interface NumberingDefinitions {
961
+ /** Abstract numbering definitions */
962
+ abstractNums: AbstractNumbering[];
963
+ /** Numbering instances */
964
+ nums: NumberingInstance[];
965
+ }
966
+ /**
967
+ * Header/footer type
968
+ */
969
+ type HeaderFooterType = 'default' | 'first' | 'even';
970
+ /**
971
+ * Header or footer reference
972
+ */
973
+ interface HeaderReference {
974
+ type: HeaderFooterType;
975
+ rId: string;
976
+ }
977
+ interface FooterReference {
978
+ type: HeaderFooterType;
979
+ rId: string;
980
+ }
981
+ /**
982
+ * Header or footer content
983
+ */
984
+ interface HeaderFooter {
985
+ type: 'header' | 'footer';
986
+ /** Header/footer type */
987
+ hdrFtrType: HeaderFooterType;
988
+ /** Content (paragraphs, tables, etc.) */
989
+ content: (Paragraph | Table)[];
990
+ }
991
+ /**
992
+ * Footnote position
993
+ */
994
+ type FootnotePosition = 'pageBottom' | 'beneathText' | 'sectEnd' | 'docEnd';
995
+ /**
996
+ * Endnote position
997
+ */
998
+ type EndnotePosition = 'sectEnd' | 'docEnd';
999
+ /**
1000
+ * Number restart type
1001
+ */
1002
+ type NoteNumberRestart = 'continuous' | 'eachSect' | 'eachPage';
1003
+ /**
1004
+ * Footnote properties
1005
+ */
1006
+ interface FootnoteProperties {
1007
+ position?: FootnotePosition;
1008
+ numFmt?: NumberFormat;
1009
+ numStart?: number;
1010
+ numRestart?: NoteNumberRestart;
1011
+ }
1012
+ /**
1013
+ * Endnote properties
1014
+ */
1015
+ interface EndnoteProperties {
1016
+ position?: EndnotePosition;
1017
+ numFmt?: NumberFormat;
1018
+ numStart?: number;
1019
+ numRestart?: NoteNumberRestart;
1020
+ }
1021
+ /**
1022
+ * Footnote (w:footnote)
1023
+ */
1024
+ interface Footnote {
1025
+ type: 'footnote';
1026
+ /** Footnote ID */
1027
+ id: number;
1028
+ /** Special footnote type */
1029
+ noteType?: 'normal' | 'separator' | 'continuationSeparator' | 'continuationNotice';
1030
+ /** Content */
1031
+ content: Paragraph[];
1032
+ }
1033
+ /**
1034
+ * Endnote (w:endnote)
1035
+ */
1036
+ interface Endnote {
1037
+ type: 'endnote';
1038
+ /** Endnote ID */
1039
+ id: number;
1040
+ /** Special endnote type */
1041
+ noteType?: 'normal' | 'separator' | 'continuationSeparator' | 'continuationNotice';
1042
+ /** Content */
1043
+ content: Paragraph[];
1044
+ }
1045
+ /**
1046
+ * Paragraph content types
1047
+ */
1048
+ type ParagraphContent = Run | Hyperlink | BookmarkStart | BookmarkEnd | SimpleField | ComplexField;
1049
+ /**
1050
+ * Paragraph (w:p)
1051
+ */
1052
+ interface Paragraph {
1053
+ type: 'paragraph';
1054
+ /** Unique paragraph ID */
1055
+ paraId?: string;
1056
+ /** Text ID */
1057
+ textId?: string;
1058
+ /** Paragraph formatting */
1059
+ formatting?: ParagraphFormatting;
1060
+ /** Paragraph content */
1061
+ content: ParagraphContent[];
1062
+ /** Computed list rendering (if this is a list item) */
1063
+ listRendering?: ListRendering;
1064
+ /** Section properties (if this paragraph ends a section) */
1065
+ sectionProperties?: SectionProperties;
1066
+ }
1067
+ /**
1068
+ * Page orientation
1069
+ */
1070
+ type PageOrientation = 'portrait' | 'landscape';
1071
+ /**
1072
+ * Section start type
1073
+ */
1074
+ type SectionStart = 'continuous' | 'nextPage' | 'oddPage' | 'evenPage' | 'nextColumn';
1075
+ /**
1076
+ * Vertical alignment
1077
+ */
1078
+ type VerticalAlign = 'top' | 'center' | 'both' | 'bottom';
1079
+ /**
1080
+ * Line number restart type
1081
+ */
1082
+ type LineNumberRestart = 'continuous' | 'newPage' | 'newSection';
1083
+ /**
1084
+ * Column definition
1085
+ */
1086
+ interface Column {
1087
+ /** Column width in twips */
1088
+ width?: number;
1089
+ /** Space after column in twips */
1090
+ space?: number;
1091
+ }
1092
+ /**
1093
+ * Section properties (w:sectPr)
1094
+ */
1095
+ interface SectionProperties {
1096
+ /** Page width in twips */
1097
+ pageWidth?: number;
1098
+ /** Page height in twips */
1099
+ pageHeight?: number;
1100
+ /** Page orientation */
1101
+ orientation?: PageOrientation;
1102
+ /** Top margin in twips */
1103
+ marginTop?: number;
1104
+ /** Bottom margin in twips */
1105
+ marginBottom?: number;
1106
+ /** Left margin in twips */
1107
+ marginLeft?: number;
1108
+ /** Right margin in twips */
1109
+ marginRight?: number;
1110
+ /** Header distance from top in twips */
1111
+ headerDistance?: number;
1112
+ /** Footer distance from bottom in twips */
1113
+ footerDistance?: number;
1114
+ /** Gutter margin in twips */
1115
+ gutter?: number;
1116
+ /** Number of columns */
1117
+ columnCount?: number;
1118
+ /** Space between columns in twips */
1119
+ columnSpace?: number;
1120
+ /** Equal width columns */
1121
+ equalWidth?: boolean;
1122
+ /** Separator line between columns */
1123
+ separator?: boolean;
1124
+ /** Individual column definitions */
1125
+ columns?: Column[];
1126
+ /** Section start type */
1127
+ sectionStart?: SectionStart;
1128
+ /** Vertical alignment of text */
1129
+ verticalAlign?: VerticalAlign;
1130
+ /** Right-to-left section */
1131
+ bidi?: boolean;
1132
+ /** Header references */
1133
+ headerReferences?: HeaderReference[];
1134
+ /** Footer references */
1135
+ footerReferences?: FooterReference[];
1136
+ /** Different first page header/footer */
1137
+ titlePg?: boolean;
1138
+ /** Different odd/even page headers/footers */
1139
+ evenAndOddHeaders?: boolean;
1140
+ /** Line numbering settings */
1141
+ lineNumbers?: {
1142
+ start?: number;
1143
+ countBy?: number;
1144
+ distance?: number;
1145
+ restart?: LineNumberRestart;
1146
+ };
1147
+ /** Page borders */
1148
+ pageBorders?: {
1149
+ top?: BorderSpec;
1150
+ bottom?: BorderSpec;
1151
+ left?: BorderSpec;
1152
+ right?: BorderSpec;
1153
+ /** Display setting */
1154
+ display?: 'allPages' | 'firstPage' | 'notFirstPage';
1155
+ /** Offset from */
1156
+ offsetFrom?: 'page' | 'text';
1157
+ /** Z-order */
1158
+ zOrder?: 'front' | 'back';
1159
+ };
1160
+ /** Page background */
1161
+ background?: {
1162
+ color?: ColorValue;
1163
+ themeColor?: ThemeColorSlot;
1164
+ themeTint?: string;
1165
+ themeShade?: string;
1166
+ };
1167
+ /** Footnote properties for this section */
1168
+ footnotePr?: FootnoteProperties;
1169
+ /** Endnote properties for this section */
1170
+ endnotePr?: EndnoteProperties;
1171
+ /** Document grid */
1172
+ docGrid?: {
1173
+ type?: 'default' | 'lines' | 'linesAndChars' | 'snapToChars';
1174
+ linePitch?: number;
1175
+ charSpace?: number;
1176
+ };
1177
+ /** First page paper source */
1178
+ paperSrcFirst?: number;
1179
+ /** Other pages paper source */
1180
+ paperSrcOther?: number;
1181
+ }
1182
+ /**
1183
+ * Block-level content types
1184
+ */
1185
+ type BlockContent = Paragraph | Table;
1186
+ /**
1187
+ * Section (implicit or explicit based on sectPr)
1188
+ */
1189
+ interface Section {
1190
+ /** Section properties */
1191
+ properties: SectionProperties;
1192
+ /** Content in this section */
1193
+ content: BlockContent[];
1194
+ /** Headers for this section */
1195
+ headers?: Map<HeaderFooterType, HeaderFooter>;
1196
+ /** Footers for this section */
1197
+ footers?: Map<HeaderFooterType, HeaderFooter>;
1198
+ }
1199
+ /**
1200
+ * Document body (w:body)
1201
+ */
1202
+ interface DocumentBody {
1203
+ /** All content (paragraphs, tables) */
1204
+ content: BlockContent[];
1205
+ /** Sections (derived from sectPr in paragraphs and final sectPr) */
1206
+ sections?: Section[];
1207
+ /** Final section properties (from body's sectPr) */
1208
+ finalSectionProperties?: SectionProperties;
1209
+ }
1210
+ /**
1211
+ * Style type
1212
+ */
1213
+ type StyleType = 'paragraph' | 'character' | 'numbering' | 'table';
1214
+ /**
1215
+ * Style definition
1216
+ */
1217
+ interface Style {
1218
+ /** Style ID */
1219
+ styleId: string;
1220
+ /** Style type */
1221
+ type: StyleType;
1222
+ /** Display name */
1223
+ name?: string;
1224
+ /** Based on style ID */
1225
+ basedOn?: string;
1226
+ /** Next style after Enter (for paragraph styles) */
1227
+ next?: string;
1228
+ /** Linked style (paragraph/character pair) */
1229
+ link?: string;
1230
+ /** UI sort priority */
1231
+ uiPriority?: number;
1232
+ /** Hidden from UI */
1233
+ hidden?: boolean;
1234
+ /** Semi-hidden from UI */
1235
+ semiHidden?: boolean;
1236
+ /** Unhide when used */
1237
+ unhideWhenUsed?: boolean;
1238
+ /** Quick format in gallery */
1239
+ qFormat?: boolean;
1240
+ /** Is default style */
1241
+ default?: boolean;
1242
+ /** Personal style (custom) */
1243
+ personal?: boolean;
1244
+ /** Paragraph properties (for paragraph/table styles) */
1245
+ pPr?: ParagraphFormatting;
1246
+ /** Run properties */
1247
+ rPr?: TextFormatting;
1248
+ /** Table properties (for table styles) */
1249
+ tblPr?: TableFormatting;
1250
+ /** Table row properties */
1251
+ trPr?: TableRowFormatting;
1252
+ /** Table cell properties */
1253
+ tcPr?: TableCellFormatting;
1254
+ /** Conditional table style parts */
1255
+ tblStylePr?: Array<{
1256
+ type: 'band1Horz' | 'band1Vert' | 'band2Horz' | 'band2Vert' | 'firstCol' | 'firstRow' | 'lastCol' | 'lastRow' | 'neCell' | 'nwCell' | 'seCell' | 'swCell';
1257
+ pPr?: ParagraphFormatting;
1258
+ rPr?: TextFormatting;
1259
+ tblPr?: TableFormatting;
1260
+ trPr?: TableRowFormatting;
1261
+ tcPr?: TableCellFormatting;
1262
+ }>;
1263
+ }
1264
+ /**
1265
+ * Document defaults (w:docDefaults)
1266
+ */
1267
+ interface DocDefaults {
1268
+ /** Default run properties */
1269
+ rPr?: TextFormatting;
1270
+ /** Default paragraph properties */
1271
+ pPr?: ParagraphFormatting;
1272
+ }
1273
+ /**
1274
+ * Style definitions from styles.xml
1275
+ */
1276
+ interface StyleDefinitions {
1277
+ /** Document defaults */
1278
+ docDefaults?: DocDefaults;
1279
+ /** Latent styles */
1280
+ latentStyles?: {
1281
+ defLockedState?: boolean;
1282
+ defUIPriority?: number;
1283
+ defSemiHidden?: boolean;
1284
+ defUnhideWhenUsed?: boolean;
1285
+ defQFormat?: boolean;
1286
+ count?: number;
1287
+ };
1288
+ /** Style definitions */
1289
+ styles: Style[];
1290
+ }
1291
+ /**
1292
+ * Theme color scheme (a:clrScheme)
1293
+ */
1294
+ interface ThemeColorScheme {
1295
+ /** Dark 1 color (usually black) */
1296
+ dk1?: string;
1297
+ /** Light 1 color (usually white) */
1298
+ lt1?: string;
1299
+ /** Dark 2 color */
1300
+ dk2?: string;
1301
+ /** Light 2 color */
1302
+ lt2?: string;
1303
+ /** Accent colors 1-6 */
1304
+ accent1?: string;
1305
+ accent2?: string;
1306
+ accent3?: string;
1307
+ accent4?: string;
1308
+ accent5?: string;
1309
+ accent6?: string;
1310
+ /** Hyperlink color */
1311
+ hlink?: string;
1312
+ /** Followed hyperlink color */
1313
+ folHlink?: string;
1314
+ }
1315
+ /**
1316
+ * Theme font (with script variants)
1317
+ */
1318
+ interface ThemeFont {
1319
+ /** Latin font */
1320
+ latin?: string;
1321
+ /** East Asian font */
1322
+ ea?: string;
1323
+ /** Complex script font */
1324
+ cs?: string;
1325
+ /** Script-specific fonts */
1326
+ fonts?: Record<string, string>;
1327
+ }
1328
+ /**
1329
+ * Theme font scheme (a:fontScheme)
1330
+ */
1331
+ interface ThemeFontScheme {
1332
+ /** Major font (headings) */
1333
+ majorFont?: ThemeFont;
1334
+ /** Minor font (body text) */
1335
+ minorFont?: ThemeFont;
1336
+ }
1337
+ /**
1338
+ * Theme (from theme1.xml)
1339
+ */
1340
+ interface Theme {
1341
+ /** Theme name */
1342
+ name?: string;
1343
+ /** Color scheme */
1344
+ colorScheme?: ThemeColorScheme;
1345
+ /** Font scheme */
1346
+ fontScheme?: ThemeFontScheme;
1347
+ /** Format scheme (fills, lines, effects) - simplified */
1348
+ formatScheme?: {
1349
+ name?: string;
1350
+ };
1351
+ }
1352
+ /**
1353
+ * Font info from fontTable.xml
1354
+ */
1355
+ interface FontInfo {
1356
+ /** Font name */
1357
+ name: string;
1358
+ /** Alternate names */
1359
+ altName?: string;
1360
+ /** Panose-1 classification */
1361
+ panose1?: string;
1362
+ /** Character set */
1363
+ charset?: string;
1364
+ /** Font family type */
1365
+ family?: 'decorative' | 'modern' | 'roman' | 'script' | 'swiss' | 'auto';
1366
+ /** Pitch (fixed or variable) */
1367
+ pitch?: 'default' | 'fixed' | 'variable';
1368
+ /** Signature */
1369
+ sig?: {
1370
+ usb0?: string;
1371
+ usb1?: string;
1372
+ usb2?: string;
1373
+ usb3?: string;
1374
+ csb0?: string;
1375
+ csb1?: string;
1376
+ };
1377
+ /** Embedded font data reference */
1378
+ embedRegular?: string;
1379
+ embedBold?: string;
1380
+ embedItalic?: string;
1381
+ embedBoldItalic?: string;
1382
+ }
1383
+ /**
1384
+ * Font table from fontTable.xml
1385
+ */
1386
+ interface FontTable {
1387
+ fonts: FontInfo[];
1388
+ }
1389
+ /**
1390
+ * Relationship type
1391
+ */
1392
+ type RelationshipType = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/image' | 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink' | 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/header' | 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/footer' | 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/footnotes' | 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/endnotes' | 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles' | 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/numbering' | 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/fontTable' | 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme' | 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/settings' | 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/webSettings' | 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/oleObject' | 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/chart' | 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/diagramData' | string;
1393
+ /**
1394
+ * Relationship entry
1395
+ */
1396
+ interface Relationship {
1397
+ /** Relationship ID (e.g., "rId1") */
1398
+ id: string;
1399
+ /** Relationship type URI */
1400
+ type: RelationshipType;
1401
+ /** Target path or URL */
1402
+ target: string;
1403
+ /** Target mode */
1404
+ targetMode?: 'External' | 'Internal';
1405
+ }
1406
+ /**
1407
+ * Relationship map (keyed by rId)
1408
+ */
1409
+ type RelationshipMap = Map<string, Relationship>;
1410
+ /**
1411
+ * Media file from word/media/
1412
+ */
1413
+ interface MediaFile {
1414
+ /** File path in ZIP */
1415
+ path: string;
1416
+ /** Original filename */
1417
+ filename?: string;
1418
+ /** MIME type */
1419
+ mimeType: string;
1420
+ /** Binary data */
1421
+ data: ArrayBuffer;
1422
+ /** Base64 encoded data for rendering */
1423
+ base64?: string;
1424
+ /** Data URL for direct use in src attributes */
1425
+ dataUrl?: string;
1426
+ }
1427
+ /**
1428
+ * Complete DOCX package structure
1429
+ */
1430
+ interface DocxPackage {
1431
+ /** Document body */
1432
+ document: DocumentBody;
1433
+ /** Style definitions */
1434
+ styles?: StyleDefinitions;
1435
+ /** Theme */
1436
+ theme?: Theme;
1437
+ /** Numbering definitions */
1438
+ numbering?: NumberingDefinitions;
1439
+ /** Font table */
1440
+ fontTable?: FontTable;
1441
+ /** Footnotes */
1442
+ footnotes?: Footnote[];
1443
+ /** Endnotes */
1444
+ endnotes?: Endnote[];
1445
+ /** Headers by relationship ID */
1446
+ headers?: Map<string, HeaderFooter>;
1447
+ /** Footers by relationship ID */
1448
+ footers?: Map<string, HeaderFooter>;
1449
+ /** Document relationships */
1450
+ relationships?: RelationshipMap;
1451
+ /** Media files */
1452
+ media?: Map<string, MediaFile>;
1453
+ /** Document properties */
1454
+ properties?: {
1455
+ title?: string;
1456
+ subject?: string;
1457
+ creator?: string;
1458
+ keywords?: string;
1459
+ description?: string;
1460
+ lastModifiedBy?: string;
1461
+ revision?: number;
1462
+ created?: Date;
1463
+ modified?: Date;
1464
+ };
1465
+ }
1466
+ /**
1467
+ * Complete parsed DOCX document
1468
+ */
1469
+ interface Document {
1470
+ /** DOCX package with all parsed content */
1471
+ package: DocxPackage;
1472
+ /** Original ArrayBuffer for round-trip */
1473
+ originalBuffer?: ArrayBuffer;
1474
+ /** Detected template variables ({{...}}) */
1475
+ templateVariables?: string[];
1476
+ /** Parsing warnings/errors */
1477
+ warnings?: string[];
1478
+ }
1479
+
1480
+ /**
1481
+ * Agent API Types
1482
+ *
1483
+ * TypeScript interfaces for the agent API:
1484
+ * - Position and Range types
1485
+ * - Command types for document manipulation
1486
+ * - Context types for AI agents
1487
+ */
1488
+
1489
+ /**
1490
+ * Position within a document
1491
+ */
1492
+ interface Position {
1493
+ /** Index of the paragraph (0-indexed) */
1494
+ paragraphIndex: number;
1495
+ /** Offset within the paragraph in characters */
1496
+ offset: number;
1497
+ /** Optional: Content index within paragraph (run, hyperlink, etc.) */
1498
+ contentIndex?: number;
1499
+ /** Optional: Section index */
1500
+ sectionIndex?: number;
1501
+ }
1502
+ /**
1503
+ * Range within a document
1504
+ */
1505
+ interface Range {
1506
+ /** Start position */
1507
+ start: Position;
1508
+ /** End position */
1509
+ end: Position;
1510
+ /** Whether the range is collapsed (cursor position) */
1511
+ collapsed?: boolean;
1512
+ }
1513
+ /**
1514
+ * Create a collapsed range (cursor) at a position
1515
+ */
1516
+ declare function createCollapsedRange(position: Position): Range;
1517
+ /**
1518
+ * Create a range from two positions
1519
+ */
1520
+ declare function createRange(start: Position, end: Position): Range;
1521
+ /**
1522
+ * Check if a position is within a range
1523
+ */
1524
+ declare function isPositionInRange(position: Position, range: Range): boolean;
1525
+ /**
1526
+ * Compare two positions
1527
+ * Returns: -1 if a < b, 0 if equal, 1 if a > b
1528
+ */
1529
+ declare function comparePositions(a: Position, b: Position): -1 | 0 | 1;
1530
+ /**
1531
+ * Base command interface
1532
+ */
1533
+ interface BaseCommand {
1534
+ /** Command type */
1535
+ type: string;
1536
+ /** Unique command ID (for undo tracking) */
1537
+ id?: string;
1538
+ }
1539
+ /**
1540
+ * Insert text at a position
1541
+ */
1542
+ interface InsertTextCommand extends BaseCommand {
1543
+ type: 'insertText';
1544
+ /** Position to insert at */
1545
+ position: Position;
1546
+ /** Text to insert */
1547
+ text: string;
1548
+ /** Optional formatting for the inserted text */
1549
+ formatting?: TextFormatting;
1550
+ }
1551
+ /**
1552
+ * Replace text in a range
1553
+ */
1554
+ interface ReplaceTextCommand extends BaseCommand {
1555
+ type: 'replaceText';
1556
+ /** Range to replace */
1557
+ range: Range;
1558
+ /** Replacement text */
1559
+ text: string;
1560
+ /** Optional formatting for the new text */
1561
+ formatting?: TextFormatting;
1562
+ }
1563
+ /**
1564
+ * Delete text in a range
1565
+ */
1566
+ interface DeleteTextCommand extends BaseCommand {
1567
+ type: 'deleteText';
1568
+ /** Range to delete */
1569
+ range: Range;
1570
+ }
1571
+ /**
1572
+ * Apply formatting to a range
1573
+ */
1574
+ interface FormatTextCommand extends BaseCommand {
1575
+ type: 'formatText';
1576
+ /** Range to format */
1577
+ range: Range;
1578
+ /** Formatting to apply */
1579
+ formatting: Partial<TextFormatting>;
1580
+ }
1581
+ /**
1582
+ * Apply paragraph formatting
1583
+ */
1584
+ interface FormatParagraphCommand extends BaseCommand {
1585
+ type: 'formatParagraph';
1586
+ /** Paragraph index */
1587
+ paragraphIndex: number;
1588
+ /** Formatting to apply */
1589
+ formatting: Partial<ParagraphFormatting>;
1590
+ }
1591
+ /**
1592
+ * Apply a named style to a paragraph
1593
+ */
1594
+ interface ApplyStyleCommand extends BaseCommand {
1595
+ type: 'applyStyle';
1596
+ /** Paragraph index */
1597
+ paragraphIndex: number;
1598
+ /** Style ID to apply */
1599
+ styleId: string;
1600
+ }
1601
+ /**
1602
+ * Insert a table at a position
1603
+ */
1604
+ interface InsertTableCommand extends BaseCommand {
1605
+ type: 'insertTable';
1606
+ /** Position to insert at */
1607
+ position: Position;
1608
+ /** Number of rows */
1609
+ rows: number;
1610
+ /** Number of columns */
1611
+ columns: number;
1612
+ /** Optional table data */
1613
+ data?: string[][];
1614
+ /** Optional header row */
1615
+ hasHeader?: boolean;
1616
+ }
1617
+ /**
1618
+ * Insert an image at a position
1619
+ */
1620
+ interface InsertImageCommand extends BaseCommand {
1621
+ type: 'insertImage';
1622
+ /** Position to insert at */
1623
+ position: Position;
1624
+ /** Image source (base64 or URL) */
1625
+ src: string;
1626
+ /** Image width in pixels */
1627
+ width?: number;
1628
+ /** Image height in pixels */
1629
+ height?: number;
1630
+ /** Alt text */
1631
+ alt?: string;
1632
+ }
1633
+ /**
1634
+ * Insert a hyperlink at a range
1635
+ */
1636
+ interface InsertHyperlinkCommand extends BaseCommand {
1637
+ type: 'insertHyperlink';
1638
+ /** Range to make into a hyperlink */
1639
+ range: Range;
1640
+ /** URL of the hyperlink */
1641
+ url: string;
1642
+ /** Display text (replaces range text if provided) */
1643
+ displayText?: string;
1644
+ /** Tooltip */
1645
+ tooltip?: string;
1646
+ }
1647
+ /**
1648
+ * Remove a hyperlink but keep the text
1649
+ */
1650
+ interface RemoveHyperlinkCommand extends BaseCommand {
1651
+ type: 'removeHyperlink';
1652
+ /** Range containing the hyperlink */
1653
+ range: Range;
1654
+ }
1655
+ /**
1656
+ * Insert a paragraph break
1657
+ */
1658
+ interface InsertParagraphBreakCommand extends BaseCommand {
1659
+ type: 'insertParagraphBreak';
1660
+ /** Position to break at */
1661
+ position: Position;
1662
+ }
1663
+ /**
1664
+ * Merge paragraphs
1665
+ */
1666
+ interface MergeParagraphsCommand extends BaseCommand {
1667
+ type: 'mergeParagraphs';
1668
+ /** First paragraph index */
1669
+ paragraphIndex: number;
1670
+ /** Number of paragraphs to merge with */
1671
+ count: number;
1672
+ }
1673
+ /**
1674
+ * Split a paragraph
1675
+ */
1676
+ interface SplitParagraphCommand extends BaseCommand {
1677
+ type: 'splitParagraph';
1678
+ /** Position to split at */
1679
+ position: Position;
1680
+ }
1681
+ /**
1682
+ * Set template variable value
1683
+ */
1684
+ interface SetVariableCommand extends BaseCommand {
1685
+ type: 'setVariable';
1686
+ /** Variable name */
1687
+ name: string;
1688
+ /** Variable value */
1689
+ value: string;
1690
+ }
1691
+ /**
1692
+ * Apply all template variables
1693
+ */
1694
+ interface ApplyVariablesCommand extends BaseCommand {
1695
+ type: 'applyVariables';
1696
+ /** Variable values */
1697
+ values: Record<string, string>;
1698
+ }
1699
+ /**
1700
+ * Union of all command types
1701
+ */
1702
+ type AgentCommand = InsertTextCommand | ReplaceTextCommand | DeleteTextCommand | FormatTextCommand | FormatParagraphCommand | ApplyStyleCommand | InsertTableCommand | InsertImageCommand | InsertHyperlinkCommand | RemoveHyperlinkCommand | InsertParagraphBreakCommand | MergeParagraphsCommand | SplitParagraphCommand | SetVariableCommand | ApplyVariablesCommand;
1703
+ /**
1704
+ * Document context for AI agents
1705
+ */
1706
+ interface AgentContext {
1707
+ /** Total paragraph count */
1708
+ paragraphCount: number;
1709
+ /** Total word count (approximate) */
1710
+ wordCount: number;
1711
+ /** Total character count */
1712
+ characterCount: number;
1713
+ /** Detected template variables */
1714
+ variables: string[];
1715
+ /** Variable count */
1716
+ variableCount: number;
1717
+ /** Available styles */
1718
+ availableStyles: StyleInfo[];
1719
+ /** Content outline (first N chars per paragraph) */
1720
+ outline: ParagraphOutline[];
1721
+ /** Document sections info */
1722
+ sections: SectionInfo[];
1723
+ /** Has tables */
1724
+ hasTables: boolean;
1725
+ /** Has images */
1726
+ hasImages: boolean;
1727
+ /** Has hyperlinks */
1728
+ hasHyperlinks: boolean;
1729
+ /** Document language */
1730
+ language?: string;
1731
+ }
1732
+ /**
1733
+ * Style information for context
1734
+ */
1735
+ interface StyleInfo {
1736
+ /** Style ID */
1737
+ id: string;
1738
+ /** Display name */
1739
+ name: string;
1740
+ /** Style type */
1741
+ type: 'paragraph' | 'character' | 'table';
1742
+ /** Is built-in style */
1743
+ builtIn?: boolean;
1744
+ }
1745
+ /**
1746
+ * Paragraph outline for context
1747
+ */
1748
+ interface ParagraphOutline {
1749
+ /** Paragraph index */
1750
+ index: number;
1751
+ /** First N characters */
1752
+ preview: string;
1753
+ /** Paragraph style */
1754
+ style?: string;
1755
+ /** Is heading */
1756
+ isHeading?: boolean;
1757
+ /** Heading level (1-9) */
1758
+ headingLevel?: number;
1759
+ /** Is list item */
1760
+ isListItem?: boolean;
1761
+ /** Is empty paragraph */
1762
+ isEmpty?: boolean;
1763
+ }
1764
+ /**
1765
+ * Section information
1766
+ */
1767
+ interface SectionInfo {
1768
+ /** Section index */
1769
+ index: number;
1770
+ /** Number of paragraphs */
1771
+ paragraphCount: number;
1772
+ /** Page size */
1773
+ pageSize?: {
1774
+ width: number;
1775
+ height: number;
1776
+ };
1777
+ /** Is landscape */
1778
+ isLandscape?: boolean;
1779
+ /** Has header */
1780
+ hasHeader?: boolean;
1781
+ /** Has footer */
1782
+ hasFooter?: boolean;
1783
+ }
1784
+ /**
1785
+ * Context about the current selection
1786
+ */
1787
+ interface SelectionContext {
1788
+ /** Selected text */
1789
+ selectedText: string;
1790
+ /** Selection range */
1791
+ range: Range;
1792
+ /** Current formatting of selection */
1793
+ formatting: Partial<TextFormatting>;
1794
+ /** Current paragraph formatting */
1795
+ paragraphFormatting: Partial<ParagraphFormatting>;
1796
+ /** Text before selection (context) */
1797
+ textBefore: string;
1798
+ /** Text after selection (context) */
1799
+ textAfter: string;
1800
+ /** Paragraph containing selection */
1801
+ paragraph: ParagraphContext;
1802
+ /** Is selection within a table */
1803
+ inTable?: boolean;
1804
+ /** Is selection within a hyperlink */
1805
+ inHyperlink?: boolean;
1806
+ /** Suggested actions based on selection */
1807
+ suggestedActions?: SuggestedAction[];
1808
+ }
1809
+ /**
1810
+ * Paragraph context for selection
1811
+ */
1812
+ interface ParagraphContext {
1813
+ /** Paragraph index */
1814
+ index: number;
1815
+ /** Full paragraph text */
1816
+ fullText: string;
1817
+ /** Paragraph style */
1818
+ style?: string;
1819
+ /** Word count */
1820
+ wordCount: number;
1821
+ }
1822
+ /**
1823
+ * Suggested action for context menu
1824
+ */
1825
+ interface SuggestedAction {
1826
+ /** Action ID */
1827
+ id: string;
1828
+ /** Display label */
1829
+ label: string;
1830
+ /** Description */
1831
+ description?: string;
1832
+ /** Icon name */
1833
+ icon?: string;
1834
+ /** Priority (higher = more prominent) */
1835
+ priority?: number;
1836
+ }
1837
+ /**
1838
+ * Response from an agent action
1839
+ */
1840
+ interface AgentResponse {
1841
+ /** Success status */
1842
+ success: boolean;
1843
+ /** New text to insert (for rewrite/expand/etc.) */
1844
+ newText?: string;
1845
+ /** New formatted content */
1846
+ newContent?: AgentContent[];
1847
+ /** Commands to execute */
1848
+ commands?: AgentCommand[];
1849
+ /** Error message if failed */
1850
+ error?: string;
1851
+ /** Warning messages */
1852
+ warnings?: string[];
1853
+ /** Metadata about the response */
1854
+ metadata?: Record<string, unknown>;
1855
+ }
1856
+ /**
1857
+ * Content block in agent response
1858
+ */
1859
+ interface AgentContent {
1860
+ /** Content type */
1861
+ type: 'text' | 'paragraph' | 'table' | 'image';
1862
+ /** Text content */
1863
+ text?: string;
1864
+ /** Formatting */
1865
+ formatting?: Partial<TextFormatting>;
1866
+ /** Paragraph formatting */
1867
+ paragraphFormatting?: Partial<ParagraphFormatting>;
1868
+ /** Table data (for table type) */
1869
+ tableData?: string[][];
1870
+ /** Image src (for image type) */
1871
+ imageSrc?: string;
1872
+ }
1873
+ /**
1874
+ * AI action types for context menu
1875
+ */
1876
+ type AIAction = 'askAI' | 'rewrite' | 'expand' | 'summarize' | 'translate' | 'explain' | 'fixGrammar' | 'makeFormal' | 'makeCasual' | 'custom';
1877
+ /**
1878
+ * AI action request
1879
+ */
1880
+ interface AIActionRequest {
1881
+ /** Action type */
1882
+ action: AIAction;
1883
+ /** Selection context */
1884
+ context: SelectionContext;
1885
+ /** Custom prompt (for 'custom' action) */
1886
+ customPrompt?: string;
1887
+ /** Target language (for 'translate' action) */
1888
+ targetLanguage?: string;
1889
+ /** Additional options */
1890
+ options?: Record<string, unknown>;
1891
+ }
1892
+ /**
1893
+ * Get action label
1894
+ */
1895
+ declare function getActionLabel(action: AIAction): string;
1896
+ /**
1897
+ * Get action description
1898
+ */
1899
+ declare function getActionDescription(action: AIAction): string;
1900
+ /**
1901
+ * Default AI actions for context menu
1902
+ */
1903
+ declare const DEFAULT_AI_ACTIONS: AIAction[];
1904
+ /**
1905
+ * Create a command with generated ID
1906
+ */
1907
+ declare function createCommand<T extends AgentCommand>(command: Omit<T, 'id'>): T;
1908
+
1909
+ /**
1910
+ * Core Plugin System Types
1911
+ *
1912
+ * Defines the interfaces for headless plugins that work in Node.js
1913
+ * without React/DOM dependencies. These plugins extend DocumentAgent
1914
+ * with additional commands and expose MCP tools for AI integration.
1915
+ */
1916
+
1917
+ /**
1918
+ * Core plugin interface - headless, works in Node.js
1919
+ *
1920
+ * Plugins can:
1921
+ * - Register command handlers that DocumentAgent dispatches to
1922
+ * - Declare MCP tools that the MCP server exposes to AI clients
1923
+ * - Have optional initialization logic
1924
+ * - Declare dependencies on other plugins
1925
+ */
1926
+ interface CorePlugin {
1927
+ /** Unique plugin identifier */
1928
+ id: string;
1929
+ /** Human-readable plugin name */
1930
+ name: string;
1931
+ /** Plugin version (semver) */
1932
+ version?: string;
1933
+ /** Plugin description */
1934
+ description?: string;
1935
+ /**
1936
+ * Command handlers this plugin provides.
1937
+ * DocumentAgent dispatches commands to these handlers.
1938
+ *
1939
+ * @example
1940
+ * ```ts
1941
+ * commandHandlers: {
1942
+ * 'insertTemplateVariable': (doc, cmd) => {
1943
+ * // Transform document
1944
+ * return modifiedDoc;
1945
+ * },
1946
+ * }
1947
+ * ```
1948
+ */
1949
+ commandHandlers?: Record<string, CommandHandler>;
1950
+ /**
1951
+ * MCP tools this plugin exposes.
1952
+ * MCP server collects these from all plugins.
1953
+ */
1954
+ mcpTools?: McpToolDefinition[];
1955
+ /**
1956
+ * Optional setup when plugin is registered.
1957
+ * Called once during plugin registration.
1958
+ */
1959
+ initialize?: () => void | Promise<void>;
1960
+ /**
1961
+ * Optional cleanup when plugin is unregistered.
1962
+ */
1963
+ destroy?: () => void | Promise<void>;
1964
+ /**
1965
+ * Dependencies on other plugins (by ID).
1966
+ * The registry ensures dependencies are loaded first.
1967
+ */
1968
+ dependencies?: string[];
1969
+ }
1970
+ /**
1971
+ * Command handler function type
1972
+ *
1973
+ * Receives a document and a command, returns a modified document.
1974
+ * Must be pure/immutable - always return a new document.
1975
+ */
1976
+ type CommandHandler = (doc: Document, command: PluginCommand) => Document;
1977
+ /**
1978
+ * Extended command type for plugins
1979
+ *
1980
+ * Plugins can define custom command types beyond the built-in AgentCommand types.
1981
+ */
1982
+ interface PluginCommand {
1983
+ /** Command type identifier */
1984
+ type: string;
1985
+ /** Unique command ID (for undo tracking) */
1986
+ id?: string;
1987
+ /** Position for positional commands */
1988
+ position?: Position;
1989
+ /** Range for range-based commands */
1990
+ range?: Range;
1991
+ /** Additional command-specific data */
1992
+ [key: string]: unknown;
1993
+ }
1994
+ /**
1995
+ * Result of command execution
1996
+ */
1997
+ interface CommandResult {
1998
+ /** The modified document */
1999
+ document: Document;
2000
+ /** Whether the command succeeded */
2001
+ success: boolean;
2002
+ /** Error message if failed */
2003
+ error?: string;
2004
+ /** Metadata about the operation */
2005
+ metadata?: Record<string, unknown>;
2006
+ }
2007
+ /**
2008
+ * MCP tool definition
2009
+ *
2010
+ * Describes a tool that can be called by AI clients through the MCP server.
2011
+ */
2012
+ interface McpToolDefinition {
2013
+ /** Tool name (used in MCP protocol) */
2014
+ name: string;
2015
+ /** Human-readable description for AI */
2016
+ description: string;
2017
+ /**
2018
+ * JSON Schema for tool input validation.
2019
+ * Can be a Zod schema or plain JSON Schema object.
2020
+ */
2021
+ inputSchema: JsonSchema | ZodSchemaLike;
2022
+ /**
2023
+ * Handler function for the tool.
2024
+ * Receives validated input and returns a result.
2025
+ */
2026
+ handler: McpToolHandler;
2027
+ /**
2028
+ * Optional annotations for the tool
2029
+ */
2030
+ annotations?: McpToolAnnotations;
2031
+ }
2032
+ /**
2033
+ * MCP tool handler function
2034
+ */
2035
+ type McpToolHandler = (input: unknown, context: McpToolContext) => Promise<McpToolResult> | McpToolResult;
2036
+ /**
2037
+ * Context passed to MCP tool handlers
2038
+ */
2039
+ interface McpToolContext {
2040
+ /** Current document (if loaded) */
2041
+ document?: Document;
2042
+ /** Document buffer (if loaded) */
2043
+ documentBuffer?: ArrayBuffer;
2044
+ /** Session state */
2045
+ session: McpSession;
2046
+ /** Logger for debugging */
2047
+ log: (message: string, data?: unknown) => void;
2048
+ }
2049
+ /**
2050
+ * MCP session state
2051
+ *
2052
+ * Maintains state across tool calls within a session.
2053
+ */
2054
+ interface McpSession {
2055
+ /** Session ID */
2056
+ id: string;
2057
+ /** Loaded documents by ID */
2058
+ documents: Map<string, LoadedDocument>;
2059
+ /** Custom session data */
2060
+ data: Map<string, unknown>;
2061
+ }
2062
+ /**
2063
+ * A loaded document in the session
2064
+ */
2065
+ interface LoadedDocument {
2066
+ /** Document ID */
2067
+ id: string;
2068
+ /** Parsed document */
2069
+ document: Document;
2070
+ /** Original buffer (for repacking) */
2071
+ buffer?: ArrayBuffer;
2072
+ /** Source filename or path */
2073
+ source?: string;
2074
+ /** Last modified timestamp */
2075
+ lastModified: number;
2076
+ }
2077
+ /**
2078
+ * MCP tool result
2079
+ */
2080
+ interface McpToolResult {
2081
+ /** Result content */
2082
+ content: McpToolContent[];
2083
+ /** Whether this is an error result */
2084
+ isError?: boolean;
2085
+ }
2086
+ /**
2087
+ * MCP tool content types
2088
+ */
2089
+ type McpToolContent = {
2090
+ type: 'text';
2091
+ text: string;
2092
+ } | {
2093
+ type: 'image';
2094
+ data: string;
2095
+ mimeType: string;
2096
+ } | {
2097
+ type: 'resource';
2098
+ uri: string;
2099
+ mimeType?: string;
2100
+ text?: string;
2101
+ };
2102
+ /**
2103
+ * MCP tool annotations
2104
+ */
2105
+ interface McpToolAnnotations {
2106
+ /** Tool category for organization */
2107
+ category?: string;
2108
+ /** Whether this tool modifies the document */
2109
+ readOnly?: boolean;
2110
+ /** Estimated cost/complexity */
2111
+ complexity?: 'low' | 'medium' | 'high';
2112
+ /** Example usage */
2113
+ examples?: McpToolExample[];
2114
+ }
2115
+ /**
2116
+ * MCP tool example
2117
+ */
2118
+ interface McpToolExample {
2119
+ /** Example description */
2120
+ description: string;
2121
+ /** Example input */
2122
+ input: unknown;
2123
+ /** Expected output description */
2124
+ output?: string;
2125
+ }
2126
+ /**
2127
+ * JSON Schema definition (subset)
2128
+ */
2129
+ interface JsonSchema {
2130
+ type?: string | string[];
2131
+ properties?: Record<string, JsonSchema>;
2132
+ items?: JsonSchema;
2133
+ required?: string[];
2134
+ description?: string;
2135
+ enum?: unknown[];
2136
+ default?: unknown;
2137
+ minimum?: number;
2138
+ maximum?: number;
2139
+ minLength?: number;
2140
+ maxLength?: number;
2141
+ pattern?: string;
2142
+ format?: string;
2143
+ additionalProperties?: boolean | JsonSchema;
2144
+ anyOf?: JsonSchema[];
2145
+ oneOf?: JsonSchema[];
2146
+ allOf?: JsonSchema[];
2147
+ $ref?: string;
2148
+ }
2149
+ /**
2150
+ * Zod-like schema interface for compatibility
2151
+ */
2152
+ interface ZodSchemaLike {
2153
+ _def?: unknown;
2154
+ parse?: (data: unknown) => unknown;
2155
+ safeParse?: (data: unknown) => {
2156
+ success: boolean;
2157
+ data?: unknown;
2158
+ error?: unknown;
2159
+ };
2160
+ }
2161
+ /**
2162
+ * Check if a schema is Zod-like
2163
+ */
2164
+ declare function isZodSchema(schema: unknown): schema is ZodSchemaLike;
2165
+ /**
2166
+ * Plugin lifecycle events
2167
+ */
2168
+ type PluginEvent = {
2169
+ type: 'registered';
2170
+ plugin: CorePlugin;
2171
+ } | {
2172
+ type: 'unregistered';
2173
+ pluginId: string;
2174
+ } | {
2175
+ type: 'error';
2176
+ pluginId: string;
2177
+ error: Error;
2178
+ };
2179
+ /**
2180
+ * Plugin event listener
2181
+ */
2182
+ type PluginEventListener = (event: PluginEvent) => void;
2183
+ /**
2184
+ * Extract command type from a union
2185
+ */
2186
+ type ExtractCommand<T extends AgentCommand, Type extends string> = T extends {
2187
+ type: Type;
2188
+ } ? T : never;
2189
+ /**
2190
+ * Create a typed command handler
2191
+ */
2192
+ type TypedCommandHandler<T extends PluginCommand> = (doc: Document, command: T) => Document;
2193
+ /**
2194
+ * Plugin configuration options
2195
+ */
2196
+ interface PluginOptions {
2197
+ /** Enable debug logging */
2198
+ debug?: boolean;
2199
+ /** Custom configuration */
2200
+ config?: Record<string, unknown>;
2201
+ }
2202
+ /**
2203
+ * Result of plugin registration
2204
+ */
2205
+ interface PluginRegistrationResult {
2206
+ /** Whether registration succeeded */
2207
+ success: boolean;
2208
+ /** Registered plugin (if successful) */
2209
+ plugin?: CorePlugin;
2210
+ /** Error message (if failed) */
2211
+ error?: string;
2212
+ /** Warning messages */
2213
+ warnings?: string[];
2214
+ }
2215
+
2216
+ export { type RunContent as $, type AIAction as A, type BlockContent as B, type CorePlugin as C, type DocumentBody as D, type Endnote as E, type Footnote as F, type McpToolContent as G, type Hyperlink as H, type Image as I, type JsonSchema as J, type McpToolContext as K, type ListLevel as L, type McpToolDefinition as M, type McpToolHandler as N, type McpToolResult as O, type PluginOptions as P, type NumberingDefinitions as Q, type Run as R, type ParagraphContext as S, type TextFormatting as T, type ParagraphFormatting as U, type ParagraphOutline as V, type PluginCommand as W, type PluginEvent as X, type Range as Y, type Relationship as Z, type ReplaceTextCommand as _, type PluginRegistrationResult as a, type SectionInfo as a0, type SectionProperties as a1, type SelectionContext as a2, type SetVariableCommand as a3, type Style as a4, type StyleDefinitions as a5, type StyleInfo as a6, type SuggestedAction as a7, type TableCell as a8, type TableRow as a9, type ThemeColorScheme as aA, type ThemeFont as aB, type ThemeFontScheme as aC, type ExtractCommand as aD, type McpToolExample as aE, type TypedCommandHandler as aF, type TextContent as aa, type Theme as ab, type ZodSchemaLike as ac, comparePositions as ad, createCollapsedRange as ae, createCommand as af, createRange as ag, getActionDescription as ah, getActionLabel as ai, isPositionInRange as aj, isZodSchema as ak, type ColorValue as al, type ThemeColorSlot as am, type HeaderFooter as an, type ParagraphAlignment as ao, type StyleType as ap, type BorderSpec as aq, type ShadingProperties as ar, type BreakContent as as, type BookmarkEnd as at, type BookmarkStart as au, type Field as av, type FooterReference as aw, type HeaderReference as ax, type Shape as ay, type TextBox as az, type CommandHandler as b, type PluginEventListener as c, type McpSession as d, type Paragraph as e, type Table as f, type Position as g, type Document as h, type AIActionRequest as i, type AgentCommand as j, type AgentContext as k, type AgentResponse as l, type ApplyStyleCommand as m, type ApplyVariablesCommand as n, type CommandResult as o, DEFAULT_AI_ACTIONS as p, type DeleteTextCommand as q, type DocxPackage as r, type FormatParagraphCommand as s, type FormatTextCommand as t, type InsertHyperlinkCommand as u, type InsertImageCommand as v, type InsertTableCommand as w, type InsertTextCommand as x, type LoadedDocument as y, type McpToolAnnotations as z };