@betteroffice/docx 0.3.0 → 0.4.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.
Files changed (82) hide show
  1. package/README.md +66 -1
  2. package/dist/chunk-2HLVVQIL.mjs +1 -0
  3. package/dist/chunk-2QHGQA3V.mjs +1 -0
  4. package/dist/{chunk-ACGKK7IB.mjs → chunk-3CYO46ML.mjs} +1 -1
  5. package/dist/chunk-3OWET2KZ.mjs +1 -0
  6. package/dist/chunk-4GEXNR7A.mjs +1 -0
  7. package/dist/chunk-4QHAMEAS.mjs +1 -0
  8. package/dist/chunk-6CHGYCFU.mjs +1 -0
  9. package/dist/chunk-7DDF4RHB.mjs +16 -0
  10. package/dist/chunk-AOWJ4WDE.mjs +1 -0
  11. package/dist/chunk-C5BX34CG.mjs +2 -0
  12. package/dist/chunk-DKWD4P4J.mjs +1 -0
  13. package/dist/chunk-DLXIZBB6.mjs +1 -0
  14. package/dist/chunk-EIPVFGIC.mjs +1 -0
  15. package/dist/{chunk-NT2OYIJ4.mjs → chunk-FMOSOX5V.mjs} +1 -1
  16. package/dist/chunk-HPZFJGGM.mjs +0 -0
  17. package/dist/chunk-LT2GCWZ3.mjs +0 -0
  18. package/dist/chunk-NVN26RHH.mjs +1 -0
  19. package/dist/{chunk-QE4ZDRKV.mjs → chunk-YLFKV2NT.mjs} +1 -1
  20. package/dist/collaboration/index.d.mts +6 -4
  21. package/dist/compareDocx-QX2YF3EF.mjs +1 -0
  22. package/dist/computeLayout-4MNWHE2T.mjs +1 -0
  23. package/dist/core.d.mts +4 -4
  24. package/dist/core.mjs +1 -1
  25. package/dist/{displayListQueries-BYFrBkw5.d.mts → displayListQueries-DnHmHUPY.d.mts} +23 -5
  26. package/dist/docx/index.d.mts +2 -2
  27. package/dist/docx/index.mjs +1 -1
  28. package/dist/editor/index.d.mts +16 -7
  29. package/dist/editor/index.mjs +1 -1
  30. package/dist/{fontLoader-CkXcPB1C.d.mts → fontLoader-BNSs0E8K.d.mts} +54 -1
  31. package/dist/{frameDelta-CVt5FAXT.d.mts → frameDelta-ByU7HBuB.d.mts} +21 -1
  32. package/dist/generated/edit/docx_edit_bg.wasm +0 -0
  33. package/dist/generated/layout/docx_layout_bg.wasm +0 -0
  34. package/dist/generated/opc/ooxml_opc_bg.wasm +0 -0
  35. package/dist/generated/parse/docx_parse_bg.wasm +0 -0
  36. package/dist/{index-BbZwdkPz.d.mts → index-yOtBET85.d.mts} +769 -16
  37. package/dist/layout/index.d.mts +2 -2
  38. package/dist/layout/index.mjs +1 -1
  39. package/dist/layout/pagination/index.d.mts +2 -2
  40. package/dist/layout/render/index.d.mts +140 -32
  41. package/dist/layout/render/index.mjs +1 -1
  42. package/dist/loadWasmAsset-Cr95TImt.d.mts +25 -0
  43. package/dist/{pagedExport-D3E4jZ-B.d.mts → pagedExport-BmSlEhoP.d.mts} +1 -1
  44. package/dist/parseWasm-NLAG22EU.mjs +1 -0
  45. package/dist/plugin-api/RenderedDomContext.d.mts +6 -4
  46. package/dist/plugin-api/RenderedDomContext.mjs +1 -1
  47. package/dist/{rustDisplayList-CwOoUn3t.d.mts → rustDisplayList-DcaA5iok.d.mts} +12 -4
  48. package/dist/{rustMeasureSource-CyBMcy1x.d.mts → rustMeasureSource-BkCx1FDx.d.mts} +2 -0
  49. package/dist/types/document.d.mts +3 -0
  50. package/dist/{types-B4jD0rrc.d.mts → types-Buyw6dFd.d.mts} +32 -3
  51. package/dist/utils/index.d.mts +14 -2
  52. package/dist/utils/index.mjs +1 -1
  53. package/dist/wasm-6WSIEYWC.mjs +1 -0
  54. package/dist/wasm-GSI2XMOH.mjs +1 -0
  55. package/dist/{wasm-G62X4WRW.mjs → wasm-IBCLSJQU.mjs} +1 -1
  56. package/dist/wasm-edit.d.mts +191 -18
  57. package/dist/wasm-edit.mjs +1 -1
  58. package/dist/wasm-layout.d.mts +1 -1
  59. package/dist/wasm-layout.mjs +1 -1
  60. package/dist/wasm-opc.d.mts +1 -1
  61. package/dist/wasm-opc.mjs +1 -1
  62. package/dist/wasm-parse.d.mts +1 -1
  63. package/dist/wasm-parse.mjs +1 -1
  64. package/dist/yrs/index.d.mts +5 -3
  65. package/dist/yrs/index.mjs +1 -1
  66. package/dist/yrs/residentEngineWorker.mjs +1 -1
  67. package/package.json +2 -2
  68. package/dist/chunk-5B4VMUXM.mjs +0 -16
  69. package/dist/chunk-5F6DLQZP.mjs +0 -1
  70. package/dist/chunk-5JEQC76K.mjs +0 -1
  71. package/dist/chunk-7GJG6LLU.mjs +0 -1
  72. package/dist/chunk-FE6FWGBJ.mjs +0 -1
  73. package/dist/chunk-H5YYCN42.mjs +0 -1
  74. package/dist/chunk-HLDJMU3R.mjs +0 -1
  75. package/dist/chunk-J7LNO6SM.mjs +0 -1
  76. package/dist/chunk-PGMXWI5X.mjs +0 -1
  77. package/dist/chunk-VQXNED2P.mjs +0 -2
  78. package/dist/chunk-Z4HZIPBS.mjs +0 -1
  79. package/dist/compareDocx-XXTZV4CG.mjs +0 -1
  80. package/dist/computeLayout-LWLAJWYA.mjs +0 -1
  81. package/dist/loadWasmAsset-CMvnVkfA.d.mts +0 -3
  82. package/dist/wasm-US6R7SWN.mjs +0 -1
@@ -1,8 +1,11 @@
1
1
  import { C as ColorValue } from './formatting-gqLFeJ9X.mjs';
2
- import { Document } from './types/document.mjs';
3
- import { a0 as DocxReadParagraphsRequest, a1 as DocxReadParagraphsResult, a2 as DocxFindTextRequest, a3 as DocxFindTextResult, a4 as DocxEditRequest, a5 as DocxValidationResult, a6 as DocxEditResult, a7 as DocxTextTarget, a8 as DocxEditRefusal, a as DocxExportOptions, H as DocxExportResult, c as DocxStructuredContent, b as DocxMarkdownContent, d as DocxPageExportOptions, f as DocxPagedStructuredContent, i as DocxLayoutMap, g as DocxSnapshotLayoutMap, D as DocxExportFailure, V as DocxParagraphHeading, m as DocxContentControlsOptions, w as DocxContentControlsResult, l as DocxContentControlQuery } from './pagedExport-D3E4jZ-B.mjs';
4
- import { R as RetainedFrame } from './frameDelta-CVt5FAXT.mjs';
2
+ import { Document, CompatibilityFlags } from './types/document.mjs';
3
+ import { a0 as DocxEditSuggestion, a1 as DocxEditFailure, a2 as DocxEditFailureCode, a3 as DocxTextRange, a4 as DocxReadParagraphsRequest, a5 as DocxReadParagraphsResult, a6 as DocxFindTextRequest, a7 as DocxFindTextResult, a8 as DocxEditRequest, a9 as DocxValidationResult, aa as DocxEditResult, ab as DocxTextTarget, ac as DocxEditRefusal, a as DocxExportOptions, H as DocxExportResult, c as DocxStructuredContent, b as DocxMarkdownContent, d as DocxPageExportOptions, f as DocxPagedStructuredContent, i as DocxLayoutMap, g as DocxSnapshotLayoutMap, D as DocxExportFailure, V as DocxParagraphHeading, m as DocxContentControlsOptions, w as DocxContentControlsResult, l as DocxContentControlQuery } from './pagedExport-BmSlEhoP.mjs';
4
+ import { R as RetainedFrame } from './frameDelta-ByU7HBuB.mjs';
5
+ import { a as WasmModuleMemory } from './loadWasmAsset-Cr95TImt.mjs';
5
6
  import { R as RepackOptions } from './rezip-Bxiq4Z_R.mjs';
7
+ import { e as Comment } from './content-BzoC6bSz.mjs';
8
+ import { PointPosition } from './plugin-api/index.mjs';
6
9
 
7
10
  type CollaborationUpdateOrigin = 'local' | 'remote';
8
11
  interface CollaborationReplica {
@@ -241,6 +244,96 @@ type DocxParagraphAnchorResult = {
241
244
  /** The paragraph IDs a session save applies, as the package writer's `paragraphIds`. @internal */
242
245
  type DocxParagraphSavePlan = RustParagraphIds;
243
246
 
247
+ /**
248
+ * Host proposals: tracked changes a host proposes by paragraph anchor and search, grouped by the
249
+ * host's proposal ids. A round resolves against one version and applies as one atomic batch
250
+ * outside undo history. Decisions only change how the proposals' revisions render: the
251
+ * revisions stay in the document, and the document version and history are untouched until the
252
+ * host withdraws the proposals.
253
+ */
254
+
255
+ type DocxProposalState = 'proposed' | 'accepted' | 'rejected';
256
+ /** Which non-overlapping matches of a search a proposal replaces; numbers count from 1. */
257
+ type DocxOccurrence = 'first' | 'all' | number;
258
+ /**
259
+ * One proposal. `replaceText` with `replaceWith: ''` deletes; with `search: ''` it fills a
260
+ * paragraph whose accepted text is empty (an inline atom counts as text), where the empty search
261
+ * matches once, at offset 0. `insertText` offsets are UTF-16 units of the paragraph's accepted
262
+ * text.
263
+ */
264
+ type DocxProposalInput = {
265
+ id: string;
266
+ paragraph: DocxParagraphAnchor;
267
+ suggest: DocxEditSuggestion;
268
+ } & ({
269
+ op: 'replaceText';
270
+ search: string;
271
+ replaceWith: string;
272
+ occurrence?: DocxOccurrence;
273
+ } | {
274
+ op: 'insertText';
275
+ at: 'start' | 'end' | {
276
+ offset: number;
277
+ };
278
+ text: string;
279
+ });
280
+ interface DocxProposalRequest {
281
+ expectVersion: string;
282
+ proposals: readonly DocxProposalInput[];
283
+ }
284
+ interface DocxProposalRecord {
285
+ id: string;
286
+ state: DocxProposalState;
287
+ paragraph: DocxSessionParagraphAnchor;
288
+ revisionIds: readonly string[];
289
+ changed: boolean;
290
+ }
291
+ interface DocxProposalSnapshot {
292
+ version: string;
293
+ /** Increments whenever a decision changes. */
294
+ previewVersion: number;
295
+ proposals: readonly DocxProposalRecord[];
296
+ }
297
+ /** @internal */
298
+ interface DocxProposalRegistryState {
299
+ previewVersion: number;
300
+ entries: {
301
+ record: DocxProposalRecord;
302
+ key: string;
303
+ suggest: {
304
+ author: string;
305
+ date: string;
306
+ };
307
+ }[];
308
+ }
309
+ type DocxProposalFailure = Omit<DocxEditFailure, 'code'> & {
310
+ code: DocxEditFailureCode | 'stale-preview' | 'unknown-proposal' | 'proposal-id-conflict';
311
+ proposalId?: string;
312
+ };
313
+ type DocxProposalResult = {
314
+ ok: true;
315
+ snapshot: DocxProposalSnapshot;
316
+ } | {
317
+ ok: false;
318
+ version: string;
319
+ failure: DocxProposalFailure;
320
+ };
321
+ /** Ids that name no proposal are ignored, so a retried withdrawal changes nothing. */
322
+ interface DocxProposalWithdrawRequest {
323
+ expectVersion: string;
324
+ ids: readonly string[];
325
+ }
326
+ interface DocxProposalStateRequest {
327
+ expectVersion: string;
328
+ expectPreviewVersion: number;
329
+ changes: readonly {
330
+ id: string;
331
+ state: DocxProposalState;
332
+ }[];
333
+ }
334
+ /** The revision decisions a snapshot shows, for `YrsRenderEnv.revisionPreview`. */
335
+ declare function proposalRevisionPreview(snapshot: DocxProposalSnapshot): Readonly<Record<string, 'accepted' | 'rejected'>> | undefined;
336
+
244
337
  /** One native paragraph in the yrs-backed display-position projection. */
245
338
  interface YrsInputParagraphSpan {
246
339
  paraId: string;
@@ -288,12 +381,197 @@ declare function residentCaretDeviceRect(rect: Pick<YrsResidentCaretRect, 'x' |
288
381
  };
289
382
  declare function residentCaretSnapshotForFrame(snapshot: YrsResidentCaretSnapshot, frame: RetainedFrame): YrsResidentCaretSnapshot | null;
290
383
 
384
+ /** @internal */
385
+ interface AnchorResolutionFailure {
386
+ ok: false;
387
+ failure: {
388
+ code: 'stale-version' | 'missing-target' | 'ambiguous-target' | 'layout-unavailable' | 'unsupported' | 'unknown-proposal';
389
+ message: string;
390
+ };
391
+ }
392
+ /** @internal */
393
+ type AnchorReader = Pick<YrsSession, 'resolveParagraphAnchor' | 'hasStory' | 'paragraphSpans' | 'storySegments' | 'findText' | 'listRevisions'>;
394
+ /** @internal */
395
+ type ProposalGeometryReader = AnchorReader & Pick<YrsSession, 'storyIds' | 'paragraphs' | 'paragraphIdCount' | 'locateParagraph' | 'version'>;
396
+ /** @internal */
397
+ type AnchorGeometryTarget = {
398
+ kind: 'proposal';
399
+ id: string;
400
+ } | {
401
+ kind: 'revision';
402
+ revisionId: string;
403
+ } | {
404
+ kind: 'paragraph';
405
+ paragraph: DocxParagraphAnchor;
406
+ } | {
407
+ kind: 'search';
408
+ paragraph: DocxParagraphAnchor;
409
+ text: string;
410
+ occurrence?: DocxOccurrence;
411
+ } | {
412
+ kind: 'range';
413
+ version: string;
414
+ range: DocxTextRange;
415
+ };
416
+ /** @internal */
417
+ interface RawAnchorRange {
418
+ start: YrsLoc;
419
+ end: YrsLoc;
420
+ }
421
+ type AnchorResolution = {
422
+ ok: true;
423
+ ranges: RawAnchorRange[];
424
+ paragraph: YrsLoc;
425
+ } | AnchorResolutionFailure;
426
+ /** @internal */
427
+ declare function anchorFailure(code: AnchorResolutionFailure['failure']['code'], message: string): AnchorResolutionFailure;
428
+ /** @internal */
429
+ declare function isBodyStory(story: string): boolean;
430
+ /** @internal */
431
+ declare function textRangeToRaw(segments: readonly YrsStorySegment[], range: DocxTextRange): {
432
+ ok: true;
433
+ range: RawAnchorRange;
434
+ } | AnchorResolutionFailure;
435
+ /** @internal */
436
+ declare function hiddenRanges(session: AnchorReader, version: string, snapshot: DocxProposalSnapshot | null): RawAnchorRange[];
437
+ /** @internal */
438
+ declare function resolveAnchorTarget(session: AnchorReader, target: AnchorGeometryTarget, version: string, snapshot?: DocxProposalSnapshot | null): AnchorResolution;
439
+ /** @internal */
440
+ interface ProposalDisplayTarget {
441
+ ranges: {
442
+ from: number;
443
+ to: number;
444
+ }[];
445
+ paragraph: number | null;
446
+ }
447
+ /** @internal */
448
+ type ProposalGeometryTarget = ({
449
+ ok: true;
450
+ } & ProposalDisplayTarget) | AnchorResolutionFailure;
451
+ /** @internal */
452
+ interface ProposalGeometryMirror {
453
+ version: string;
454
+ previewVersion: number;
455
+ proposals: string;
456
+ targets: Record<string, ProposalGeometryTarget>;
457
+ hidden: {
458
+ from: number;
459
+ to: number;
460
+ }[];
461
+ }
462
+ /** @internal */
463
+ declare function proposalSetIdentity(snapshot: DocxProposalSnapshot): string;
464
+ /** @internal */
465
+ declare function computeProposalGeometryMirror(reader: ProposalGeometryReader, snapshot: DocxProposalSnapshot): ProposalGeometryMirror;
466
+ /** @internal */
467
+ declare function resolveNavigationTarget(reader: ProposalGeometryReader, story: string, paraId: string): {
468
+ loc: YrsLoc;
469
+ position: number;
470
+ } | 'missing-target' | 'ambiguous-target' | 'unsupported';
471
+
472
+ /** @internal */
473
+ type ResidentProposalOperation = {
474
+ kind: 'propose';
475
+ request: DocxProposalRequest;
476
+ } | {
477
+ kind: 'setStates';
478
+ request: DocxProposalStateRequest;
479
+ } | {
480
+ kind: 'withdraw';
481
+ request: DocxProposalWithdrawRequest;
482
+ } | {
483
+ kind: 'snapshot';
484
+ };
485
+ /** @internal */
486
+ interface ResidentProposalResponse {
487
+ result?: DocxProposalResult;
488
+ mirror: {
489
+ version: string;
490
+ proposals: DocxProposalRegistryState;
491
+ };
492
+ changedStories: string[];
493
+ updates: ArrayBuffer[];
494
+ stateVector: ArrayBuffer;
495
+ geometry: ProposalGeometryMirror;
496
+ }
497
+ /** @internal */
498
+ type ResidentDocumentRead = {
499
+ kind: 'paragraphIdentities';
500
+ } | {
501
+ kind: 'resolveParagraphAnchors';
502
+ anchors: DocxParagraphAnchor[];
503
+ } | {
504
+ kind: 'readParagraphs';
505
+ request: DocxReadParagraphsRequest;
506
+ } | {
507
+ kind: 'navigationTarget';
508
+ story: string;
509
+ paraId: string;
510
+ };
511
+ /** @internal */
512
+ interface ResidentDocumentReadValues {
513
+ paragraphIdentities: DocxParagraphIdentitySnapshot;
514
+ resolveParagraphAnchors: {
515
+ results: DocxParagraphAnchorResult[];
516
+ };
517
+ readParagraphs: DocxReadParagraphsResult;
518
+ navigationTarget: ReturnType<typeof resolveNavigationTarget>;
519
+ }
291
520
  type ResidentEngineWorkerRequest = {
521
+ id: number;
522
+ type: 'warm';
523
+ } | {
292
524
  id: number;
293
525
  type: 'bootstrap';
294
526
  snapshot: YrsResidentWorkerSnapshot;
295
527
  extras: string;
296
528
  expectedFrameEpoch: number;
529
+ layoutExtras?: string;
530
+ /** Pages `[start, end)` a full build compiles; the rest stay unbuilt. */
531
+ displayWindow?: [number, number];
532
+ retainBuiltPages?: boolean;
533
+ /**
534
+ * Lay out only as much of the body as fills this many pages; a reply
535
+ * marked `layoutProvisional` is finished by `completeLayout`.
536
+ */
537
+ provisionalPages?: number;
538
+ /**
539
+ * The document replaces the one this worker showed, which the host
540
+ * hands over from: keep the attached page surfaces for its pages.
541
+ */
542
+ keepSurfaces?: boolean;
543
+ /** Lay out the document `open` seeded here, not the snapshot's state. */
544
+ opened?: boolean;
545
+ /** The most the worker's editing core may allocate at once. */
546
+ heapLimitBytes?: number;
547
+ } | {
548
+ id: number;
549
+ type: 'open';
550
+ /** The DOCX package, parsed and seeded in a fresh session here. */
551
+ bytes: ArrayBuffer;
552
+ /** The package's SHA-256, when the caller already took it. */
553
+ digest?: string;
554
+ generation?: string;
555
+ /** The most the worker's editing core may allocate at once. */
556
+ heapLimitBytes?: number;
557
+ } | {
558
+ id: number;
559
+ type: 'fontRequirements';
560
+ layoutInput: string;
561
+ } | {
562
+ id: number;
563
+ type: 'encodeState';
564
+ } | {
565
+ id: number;
566
+ type: 'revisionCount';
567
+ } | {
568
+ id: number;
569
+ type: 'proposal';
570
+ operation: ResidentProposalOperation;
571
+ } | {
572
+ id: number;
573
+ type: 'documentRead';
574
+ read: ResidentDocumentRead;
297
575
  } | {
298
576
  id: number;
299
577
  type: 'sync';
@@ -301,12 +579,38 @@ type ResidentEngineWorkerRequest = {
301
579
  extras: string;
302
580
  expectedFrameEpoch: number;
303
581
  paintCaret: boolean;
582
+ /**
583
+ * Display extras without the header/footer payload. When present, the
584
+ * snapshot's layout is authoritative: the worker completes the extras
585
+ * from the layout it runs and returns that layout as `layoutJson`.
586
+ */
587
+ layoutExtras?: string;
588
+ displayWindow?: [number, number];
589
+ retainBuiltPages?: boolean;
590
+ } | {
591
+ id: number;
592
+ type: 'buildPages';
593
+ pages: number[];
594
+ expectedFrameEpoch: number;
595
+ paintCaret: boolean;
596
+ } | {
597
+ id: number;
598
+ type: 'completeLayout';
599
+ expectedFrameEpoch: number;
600
+ paintCaret: boolean;
601
+ /**
602
+ * Measure the rest this many body blocks a step to start with, letting
603
+ * requests that arrive meanwhile run between steps; absent, in one step.
604
+ */
605
+ sliceBlocks?: number;
304
606
  } | {
305
607
  id: number;
306
608
  type: 'buildFrame';
307
609
  extras: string;
308
610
  expectedFrameEpoch: number;
309
611
  paintCaret: boolean;
612
+ displayWindow?: [number, number];
613
+ retainBuiltPages?: boolean;
310
614
  } | {
311
615
  id: number;
312
616
  type: 'applyInput';
@@ -315,14 +619,19 @@ type ResidentEngineWorkerRequest = {
315
619
  expectedFrameEpoch: number;
316
620
  profile: boolean;
317
621
  paintCaret: boolean;
622
+ displayWindow?: [number, number];
623
+ retainBuiltPages?: boolean;
318
624
  } | {
319
625
  id: number;
320
626
  type: 'applyDelete';
321
627
  direction: 'backward' | 'forward';
628
+ count: number;
322
629
  selection: YrsSelection;
323
630
  expectedFrameEpoch: number;
324
631
  profile: boolean;
325
632
  paintCaret: boolean;
633
+ displayWindow?: [number, number];
634
+ retainBuiltPages?: boolean;
326
635
  } | {
327
636
  id: number;
328
637
  type: 'applyUpdate';
@@ -346,7 +655,7 @@ type ResidentEngineWorkerRequest = {
346
655
  id: number;
347
656
  type: 'destroy';
348
657
  };
349
- type ResidentEngineWorkerResponse = {
658
+ type ResidentEngineWorkerResponse = ({
350
659
  id: number;
351
660
  ok: true;
352
661
  frame?: ArrayBuffer;
@@ -361,9 +670,33 @@ type ResidentEngineWorkerResponse = {
361
670
  replayMs?: number;
362
671
  replayedPages?: number;
363
672
  layoutRevision?: number;
673
+ /** Characters an applyDelete removed. */
674
+ deletedUnits?: number;
364
675
  /** The worker replica's yrs state vector after this operation, so the
365
676
  * next sync can ship a diff instead of the whole document state. */
366
677
  stateVector?: ArrayBuffer;
678
+ /** The region layout the worker ran, for a request carrying `layoutExtras`. */
679
+ layoutJson?: string;
680
+ /** `layoutJson` covers only the first pages of the body. */
681
+ layoutProvisional?: boolean;
682
+ /** An `open` reply: the opened package's host metadata JSON. */
683
+ hostJson?: string;
684
+ /** A `fontRequirements` reply. */
685
+ requirementsJson?: string;
686
+ /** An `encodeState` reply: the document state as one yrs v1 update. */
687
+ state?: ArrayBuffer;
688
+ revisionCount?: number;
689
+ /** @internal */
690
+ proposals?: DocxProposalRegistryState;
691
+ /** @internal */
692
+ version?: string;
693
+ /** @internal */
694
+ proposal?: ResidentProposalResponse;
695
+ /** @internal */
696
+ read?: {
697
+ version: string;
698
+ value: unknown;
699
+ };
367
700
  } | {
368
701
  id: number;
369
702
  ok: false;
@@ -371,8 +704,18 @@ type ResidentEngineWorkerResponse = {
371
704
  residentUnavailable?: boolean;
372
705
  /** A wasm trap poisoned the worker; it refuses every later request. */
373
706
  terminal?: boolean;
707
+ /** The trap followed an allocation the worker's memory could not satisfy. */
708
+ outOfMemory?: boolean;
709
+ }) & {
710
+ /** The worker's wasm memories as the reply left. */
711
+ memory?: WasmModuleMemory[];
374
712
  };
375
713
 
714
+ /** @internal */
715
+ interface ResidentProposalReply extends Omit<ResidentProposalResponse, 'updates' | 'stateVector'> {
716
+ updates: Uint8Array[];
717
+ stateVector: Uint8Array;
718
+ }
376
719
  interface ResidentEngineWorkerFrame {
377
720
  frame: Uint8Array;
378
721
  updates: Uint8Array[];
@@ -386,6 +729,42 @@ interface ResidentEngineWorkerFrame {
386
729
  replayMs: number;
387
730
  replayedPages: number;
388
731
  layoutRevision: number;
732
+ /** Characters an applyDelete removed. */
733
+ deletedUnits: number;
734
+ /** The region layout the worker ran, when the request handed it the layout. */
735
+ layoutJson?: string;
736
+ /** `layoutJson` covers only the first pages; `completeLayout` finishes it. */
737
+ layoutProvisional?: boolean;
738
+ }
739
+ /** A bootstrap/sync whose snapshot layout the worker runs as the only layout. */
740
+ interface ResidentEngineWorkerLayoutOptions {
741
+ /** Display extras minus the header/footer payload the worker's layout supplies. */
742
+ layoutExtras?: string;
743
+ /** The host state vector the snapshot brings the worker to. */
744
+ stateVector?: Uint8Array;
745
+ /** Bootstrap only: lay out just the body's first pages before replying. */
746
+ provisionalPages?: number;
747
+ /** Bootstrap only: lay out the document {@link ResidentEngineWorkerClient.open} opened. */
748
+ opened?: boolean;
749
+ /** Bootstrap only: the epoch of the frame the host shows; the worker's frames follow it. */
750
+ frameEpoch?: number;
751
+ /**
752
+ * Bootstrap only: the most the worker's editing core may allocate at once.
753
+ * An allocation past it stops the worker with {@link ResidentWorkerOutOfMemoryError}.
754
+ */
755
+ heapLimitBytes?: number;
756
+ }
757
+ /** What an {@link ResidentEngineWorkerClient.open} seeded in the worker. */
758
+ interface ResidentEngineWorkerOpened {
759
+ /** The package's host metadata JSON, for `decodeDocxHostJson`. */
760
+ hostJson: string;
761
+ /** The worker replica's state vector once seeded. */
762
+ stateVector: Uint8Array;
763
+ }
764
+ /** How a bootstrap or sync builds its frame. */
765
+ interface ResidentEngineWorkerSnapshotOptions {
766
+ /** Pages `[start, end)` the frame builds; the rest stay unbuilt. */
767
+ displayWindow?: [number, number];
389
768
  }
390
769
  interface ResidentEngineOffscreenPage {
391
770
  pageId: string;
@@ -405,26 +784,94 @@ interface ResidentEngineWorkerPort {
405
784
  declare class ResidentEngineWorkerClient {
406
785
  private readonly worker;
407
786
  private readonly pending;
787
+ private watchdog;
408
788
  private nextId;
409
789
  private terminalError;
410
790
  private ready;
411
791
  private revision;
412
792
  private remoteVector;
413
793
  private appliedFontsRevision;
794
+ private bootstrapped;
795
+ /** Set once `open` is sent, with the heap limit it opened under. */
796
+ private openedHeapLimit;
797
+ private bootstraps;
798
+ /** Id of the last snapshot request sent; replies to earlier requests must
799
+ * not replace the state it recorded. */
800
+ private lastSnapshotId;
801
+ private keepSurfaces;
802
+ private lastMemory;
803
+ private answeredFrameEpoch;
804
+ private retainBuiltPages;
414
805
  constructor(worker?: ResidentEngineWorkerPort);
415
806
  isReady(): boolean;
807
+ /** @internal */
808
+ hasFailed(): boolean;
809
+ /** The worker's wasm memories as of its latest reply; null before one. */
810
+ memory(): WasmModuleMemory[] | null;
416
811
  layoutRevision(): number;
812
+ /** @internal The newest frame epoch a reply carried; 0 before any frame. */
813
+ answeredFrame(): number;
814
+ /** @internal */
815
+ setRetainBuiltPages(retain: boolean): void;
816
+ /** @internal Whether a frame request other than `buildPages` awaits its reply. */
817
+ frameRequestPending(): boolean;
417
818
  /** The worker replica's last reported yrs state vector (null before any). */
418
819
  remoteStateVector(): Uint8Array | null;
419
820
  /** The fonts revision this worker last applied (null before bootstrap). */
420
821
  syncedFontsRevision(): number | null;
421
- bootstrap(snapshot: YrsResidentWorkerSnapshot, extras: string): Promise<ResidentEngineWorkerFrame>;
422
- sync(snapshot: YrsResidentWorkerSnapshot, extras: string, expectedFrameEpoch: number, paintCaret?: boolean): Promise<ResidentEngineWorkerFrame>;
423
- buildFrame(extras: string, expectedFrameEpoch: number, paintCaret?: boolean): Promise<ResidentEngineWorkerFrame>;
424
- applyInput(text: string, selection: YrsSelection, expectedFrameEpoch: number, profile?: boolean, paintCaret?: boolean): Promise<ResidentEngineWorkerApplyResult | {
822
+ /** A bootstrap was sent; later snapshots go as syncs queued behind it. */
823
+ bootstrapSent(): boolean;
824
+ /**
825
+ * Starts over with another document in the same worker: the next request
826
+ * is a bootstrap, which keeps the page surfaces already attached so the
827
+ * new document's pages paint where the old ones were.
828
+ */
829
+ rebootstrap(): void;
830
+ /**
831
+ * Parses and seeds a DOCX in the worker, which then holds the document:
832
+ * its first layout is a bootstrap with `opened`, and the main replica loads
833
+ * {@link encodeState}. A copy of `bytes` is transferred.
834
+ */
835
+ open(bytes: Uint8Array, options?: {
836
+ digest?: string;
837
+ generation?: string;
838
+ heapLimitBytes?: number;
839
+ }): Promise<ResidentEngineWorkerOpened>;
840
+ /** The font requirements of a region layout request, read from the opened document. */
841
+ fontRequirements(layoutInput: string): Promise<string>;
842
+ /** @internal */
843
+ proposal(operation: ResidentProposalOperation): Promise<ResidentProposalReply>;
844
+ /** @internal */
845
+ documentRead<K extends ResidentDocumentRead['kind']>(read: ResidentDocumentRead & {
846
+ kind: K;
847
+ }): Promise<{
848
+ version: string;
849
+ value: ResidentDocumentReadValues[K];
850
+ }>;
851
+ /** @internal */
852
+ handOver(): Promise<{
853
+ state: Uint8Array;
854
+ version: string;
855
+ proposals: DocxProposalRegistryState;
856
+ }>;
857
+ /** The worker's whole document state as one yrs v1 update. */
858
+ encodeState(): Promise<Uint8Array>;
859
+ revisionCount(): Promise<number>;
860
+ warm(): Promise<void>;
861
+ bootstrap(snapshot: YrsResidentWorkerSnapshot, extras: string, options?: ResidentEngineWorkerLayoutOptions & ResidentEngineWorkerSnapshotOptions): Promise<ResidentEngineWorkerFrame>;
862
+ sync(snapshot: YrsResidentWorkerSnapshot, extras: string, expectedFrameEpoch: number, paintCaret?: boolean, options?: ResidentEngineWorkerLayoutOptions & ResidentEngineWorkerSnapshotOptions): Promise<ResidentEngineWorkerFrame>;
863
+ /**
864
+ * Lay out the rest of a provisional bootstrap layout: its frame and full
865
+ * layout, or null when a later snapshot already replaced it.
866
+ */
867
+ completeLayout(expectedFrameEpoch: number, paintCaret?: boolean, sliceBlocks?: number): Promise<ResidentEngineWorkerFrame | null>;
868
+ buildFrame(extras: string, expectedFrameEpoch: number, paintCaret?: boolean, displayWindow?: [number, number]): Promise<ResidentEngineWorkerFrame>;
869
+ /** Build unbuilt display pages; the reply frame carries them. */
870
+ buildPages(pages: number[], expectedFrameEpoch: number, paintCaret?: boolean): Promise<ResidentEngineWorkerFrame>;
871
+ applyInput(text: string, selection: YrsSelection, expectedFrameEpoch: number, profile?: boolean, paintCaret?: boolean, displayWindow?: [number, number]): Promise<ResidentEngineWorkerApplyResult | {
425
872
  applied: false;
426
873
  }>;
427
- applyDelete(direction: 'backward' | 'forward', selection: YrsSelection, expectedFrameEpoch: number, profile?: boolean, paintCaret?: boolean): Promise<ResidentEngineWorkerApplyResult | {
874
+ applyDelete(direction: 'backward' | 'forward', selection: YrsSelection, expectedFrameEpoch: number, profile?: boolean, paintCaret?: boolean, count?: number, displayWindow?: [number, number]): Promise<ResidentEngineWorkerApplyResult | {
428
875
  applied: false;
429
876
  }>;
430
877
  /** Drop the worker-painted caret line by re-presenting the caret page's
@@ -434,15 +881,46 @@ declare class ResidentEngineWorkerClient {
434
881
  attachCanvases(pages: ResidentEngineOffscreenPage[], activePageIds: string[], devicePixelRatio: number, zoom: number, caretStyle: ResidentCaretPaintStyle): Promise<void>;
435
882
  destroy(): void;
436
883
  private request;
884
+ /**
885
+ * Requests run in order, so once a snapshot is sent every later request
886
+ * finds its state and fonts in the worker: the next sync can diff against
887
+ * them before this one answers.
888
+ */
889
+ private recordSent;
890
+ /** Restarted by every message, so a queue of slow but answered requests never trips it. */
891
+ private armWatchdog;
892
+ private disarmWatchdog;
437
893
  /** Record a successfully applied bootstrap/sync payload's fonts revision.
438
894
  * The state vector is tracked centrally in `onmessage`. */
439
895
  private recordSync;
440
896
  private fail;
441
897
  }
898
+ declare class ResidentWorkerUnavailableError extends Error {
899
+ }
442
900
  /** The worker itself failed (crash, timeout, torn-down, corrupt reply). */
443
901
  declare class ResidentWorkerFailureError extends Error {
444
902
  }
903
+ /** The worker trapped because its wasm memory could not grow any further. */
904
+ declare class ResidentWorkerOutOfMemoryError extends ResidentWorkerUnavailableError {
905
+ /** The worker's wasm memories when it trapped. */
906
+ readonly memory: WasmModuleMemory[];
907
+ constructor(message: string,
908
+ /** The worker's wasm memories when it trapped. */
909
+ memory: WasmModuleMemory[]);
910
+ }
445
911
  declare function canUseResidentEngineWorker(): boolean;
912
+ /** @internal */
913
+ declare function preloadResidentEngineWorker(): Promise<void>;
914
+ /** @internal */
915
+ declare function retainPreloadedResidentEngineWorker(): () => void;
916
+ /** @internal */
917
+ declare function takePreloadedResidentEngineWorker(): ResidentEngineWorkerClient | null;
918
+
919
+ /**
920
+ * Preload the editing engine and one spare resident worker. Opt-in.
921
+ * @experimental
922
+ */
923
+ declare function preloadDocxEngine(): Promise<void>;
446
924
 
447
925
  /** Direct Document-to-yrs load projection. */
448
926
 
@@ -515,7 +993,7 @@ declare function captureSessionSave(session: YrsSession): DocxSessionSave;
515
993
  * it selects none unless `originalBuffer` is the session's source package.
516
994
  * @internal
517
995
  */
518
- declare function writeSessionSave(session: YrsSession, document: Document, capture: DocxSessionSave, originalBuffer: ArrayBuffer, options?: RepackOptions, patches?: (part: string) => boolean): Promise<DocxSavedDocument>;
996
+ declare function writeSessionSave(session: YrsSession, document: Document, capture: DocxSessionSave, originalBuffer: ArrayBuffer, options?: RepackOptions, patches?: (part: string) => boolean, skipMutations?: boolean): Promise<DocxSavedDocument>;
519
997
  /**
520
998
  * Saves a session opened from DOCX bytes and reports each saved paragraph's
521
999
  * persisted anchor, read from the same projection the bytes are written
@@ -531,9 +1009,101 @@ declare function writeSessionSave(session: YrsSession, document: Document, captu
531
1009
  */
532
1010
  declare function saveYrsDocx(session: YrsSession, options?: RepackOptions): Promise<DocxSavedDocument>;
533
1011
 
1012
+ /** @internal */
1013
+ declare function editorSaveKeys(document: Document, comments?: readonly Comment[]): {
1014
+ metadata: string;
1015
+ comments: string;
1016
+ commentIds: number[];
1017
+ };
1018
+
1019
+ /** Engine operations the package runs on sessions it creates itself; not public API. */
1020
+
1021
+ /** Returns the session's opened source package when available. @internal */
1022
+ declare function sessionSourcePackage(session: YrsSession): {
1023
+ buffer: ArrayBuffer;
1024
+ keys: ReturnType<typeof editorSaveKeys>;
1025
+ } | null;
1026
+
1027
+ type PositionReader = Pick<YrsSession, 'hasStory' | 'storySegments'>;
1028
+ /** @internal */
1029
+ interface YrsProjectedNode {
1030
+ kind: string;
1031
+ start: number;
1032
+ nodeSize: number;
1033
+ attrs: Record<string, unknown>;
1034
+ story: string;
1035
+ }
1036
+ /** @internal */
1037
+ interface YrsProjectedTable extends YrsProjectedNode {
1038
+ kind: 'table';
1039
+ tableIndex: number;
1040
+ widthsTwips: number[];
1041
+ rowCount: number;
1042
+ cells: YrsProjectedCell[];
1043
+ }
1044
+ /** @internal */
1045
+ interface YrsProjectedCell {
1046
+ row: number;
1047
+ column: number;
1048
+ rowspan: number;
1049
+ colspan: number;
1050
+ story: string;
1051
+ start: number;
1052
+ contentStart: number;
1053
+ nodeSize: number;
1054
+ attrs: Record<string, unknown>;
1055
+ }
1056
+ /** @internal */
1057
+ interface YrsPointerProjectionTarget {
1058
+ story: string;
1059
+ displayPosition: number;
1060
+ cell?: YrsCellLoc;
1061
+ }
1062
+ /** @internal */
1063
+ interface YrsStorySegmentSource {
1064
+ segments(story: string): YrsStorySegment[];
1065
+ }
1066
+ /** @internal */
1067
+ declare function createYrsPositionProjection(session: PositionReader, rootStory: string, source?: YrsStorySegmentSource): YrsPositionProjection | null;
1068
+ /** @internal */
1069
+ declare function projectYrsDisplayPosition(position: number | PointPosition, getProjection: (rootStory: string) => YrsPositionProjection | null): YrsPointerProjectionTarget | null;
1070
+ /** @internal */
1071
+ declare class YrsPositionProjection {
1072
+ readonly rootStory: string;
1073
+ private readonly stories;
1074
+ private readonly nodes;
1075
+ private readonly tables;
1076
+ private readonly source;
1077
+ private readonly paragraphsById;
1078
+ constructor(session: Pick<YrsSession, 'storySegments'>, rootStory: string, source?: YrsStorySegmentSource);
1079
+ get size(): number;
1080
+ nodeAt(position: number): YrsProjectedNode | null;
1081
+ tableAtPosition(position: number): YrsProjectedTable | null;
1082
+ tableAtStart(start: number): YrsProjectedTable | null;
1083
+ tableStartForLoc(at: YrsCellLoc): number | null;
1084
+ cellPosition(tableStart: number, row: number, column: number): number | null;
1085
+ targetAt(position: number): YrsPointerProjectionTarget;
1086
+ positionForLoc(loc: YrsLoc): number | null;
1087
+ /** First paragraph for each paraId. */
1088
+ private paragraphIndex;
1089
+ bookmarkPosition(name: string): number | null;
1090
+ private buildStory;
1091
+ private inputPositionAt;
1092
+ private buildTable;
1093
+ }
1094
+ /** @internal */
1095
+ declare function yrsLocToProjectedDisplayPosition(reader: Pick<YrsSession, 'hasStory' | 'paragraphSpans'>, projectionFor: (rootStory: string) => YrsPositionProjection | null, loc: YrsLoc, activeRootStory?: string, inputMap?: (story: string) => YrsInputPositionMap | null): number | null;
1096
+
534
1097
  interface YrsDocxHost {
535
1098
  document: Document;
536
1099
  referencedFonts: string[];
1100
+ /**
1101
+ * The `referencedFonts` a document seeded from its package names only for
1102
+ * East Asian or complex-script text it does not contain, so no text is
1103
+ * measured or drawn with them. Empty when its stories were not seeded; a
1104
+ * preview's cover only its own first pages.
1105
+ */
1106
+ unusedScriptFonts?: string[];
537
1107
  embeddedFonts: Map<string, ArrayBuffer>;
538
1108
  fontTableRelationshipsXml?: string;
539
1109
  }
@@ -651,7 +1221,23 @@ interface YrsOpeningOptions {
651
1221
  * as one session. Each opening mints a fresh one by default.
652
1222
  */
653
1223
  generation?: string;
1224
+ /**
1225
+ * Seeds images as `media:{n}` tokens naming their part of the package,
1226
+ * instead of `data:` URLs, keeping them out of the document state. Only a
1227
+ * replica opened from the same package on a version that reads tokens
1228
+ * shows them, so every client of a shared room must be one. Off by default.
1229
+ */
1230
+ mediaTokens?: boolean;
654
1231
  }
1232
+ /**
1233
+ * A copy of `bytes` whose SHA-256 the platform takes off the calling thread,
1234
+ * where it has Web Crypto. Opening that copy unchanged skips hashing the
1235
+ * package on the calling thread; any other bytes open as before.
1236
+ * @internal
1237
+ */
1238
+ declare function prepareDocxBytes(bytes: Uint8Array): Promise<Uint8Array>;
1239
+ /** The SHA-256 {@link prepareDocxBytes} took of `bytes`, if it took one. @internal */
1240
+ declare function preparedDocxDigest(bytes: Uint8Array): string | undefined;
655
1241
  /** Snapshot of one paragraph from {@link YrsSession.paragraphs}. */
656
1242
  interface YrsParagraph {
657
1243
  /** Session key; not the paragraph's Word `w14:paraId`. */
@@ -821,6 +1407,10 @@ interface YrsParagraphReceipt {
821
1407
  interface YrsRevisionReceipt {
822
1408
  revisionId: string | null;
823
1409
  }
1410
+ /** Where the replacement text landed; after the struck-out text when suggesting. */
1411
+ interface YrsReplaceReceipt extends YrsRevisionReceipt {
1412
+ range?: YrsStoryRange;
1413
+ }
824
1414
  /**
825
1415
  * Receipt of {@link YrsSession.splitParagraph}. The first half keeps the
826
1416
  * original paraId and the second half is re-minted; suggesting
@@ -876,6 +1466,7 @@ type YrsRawOp = {
876
1466
  };
877
1467
  /** Host context for {@link YrsSession.yrsBlocksForStory} (theme + list numbering). */
878
1468
  interface YrsRenderEnv {
1469
+ compatibilityFlags?: Partial<CompatibilityFlags>;
879
1470
  tocStyleIds?: string[];
880
1471
  paragraphSpacingLinePx?: number;
881
1472
  /** Section document-grid snap pitch in px (w:docGrid). The engine derives this from sections; hosts may omit it. */
@@ -891,6 +1482,13 @@ interface YrsRenderEnv {
891
1482
  numericIds?: Record<string, number>;
892
1483
  /** Include hidden text in visible layout without changing the document. */
893
1484
  showHiddenText?: boolean;
1485
+ /** Revision id → decision shown in layout; unlisted revisions render as tracked changes. */
1486
+ revisionPreview?: Readonly<Record<string, 'accepted' | 'rejected'>>;
1487
+ /**
1488
+ * Lay the opened package's images out as `media:{n}` tokens, which a
1489
+ * resolver given the session's `mediaSource` reads. @internal
1490
+ */
1491
+ mediaTokens?: boolean;
894
1492
  }
895
1493
  /** Receipt of {@link YrsSession.addComment}. */
896
1494
  interface YrsCommentReceipt {
@@ -939,6 +1537,13 @@ interface YrsResidentCaretSnapshot {
939
1537
  selection?: YrsSelection | null;
940
1538
  }
941
1539
  declare function sameYrsSelection(left: YrsSelection | null, right: YrsSelection | null): boolean;
1540
+ /** How far a region layout begun with {@link YrsSession.beginRegionLayout} has come. */
1541
+ interface YrsRegionLayoutProgress {
1542
+ measuredBlocks: number;
1543
+ bodyBlocks: number;
1544
+ /** The retained region layout reply, once the pass is complete. */
1545
+ layoutJson?: string;
1546
+ }
942
1547
  /** Opt-in internal stage timings for one resident engine input. @internal */
943
1548
  interface YrsEngineApplyProfile {
944
1549
  selectionMs: number;
@@ -972,6 +1577,8 @@ type YrsResidentFontRegistration = Uint8Array | {
972
1577
  family: string;
973
1578
  };
974
1579
  interface YrsResidentWorkerSnapshot {
1580
+ /** @internal */
1581
+ workerAuthoritative?: true;
975
1582
  clientId: number;
976
1583
  /** Full document state, or a state-vector diff when the caller supplied
977
1584
  * the worker's known vector — both apply through the same merge path. */
@@ -990,6 +1597,10 @@ interface YrsResidentWorkerSnapshot {
990
1597
  layoutInput: string;
991
1598
  layoutWithRegions: boolean;
992
1599
  layoutRevision: number;
1600
+ /** The document is a preview's cut of a package: its layouts render NUMPAGES empty. */
1601
+ partialDocument?: boolean;
1602
+ /** Which seeded `data:` image sources lay out as `media:{n}` tokens. @internal */
1603
+ mediaSources?: string;
993
1604
  }
994
1605
  /**
995
1606
  * What the sync target already holds, so a snapshot can ship deltas instead
@@ -1165,6 +1776,16 @@ interface YrsSelectionText {
1165
1776
  * One live replica of the yrs editing model. Thin typed wrapper over the
1166
1777
  * wasm `EditSession` — no editing logic on this side of the boundary.
1167
1778
  */
1779
+ /** An embedded image's bytes, as its `media:{n}` source displays them. */
1780
+ interface YrsMediaSource {
1781
+ bytes: Uint8Array;
1782
+ mimeType: string;
1783
+ }
1784
+ /** @internal */
1785
+ interface YrsWorkerDocumentMirror {
1786
+ version: string;
1787
+ proposals: DocxProposalRegistryState;
1788
+ }
1168
1789
  interface YrsSession extends CollaborationReplica {
1169
1790
  /** The yrs client id this replica writes with. */
1170
1791
  readonly clientId: number;
@@ -1189,25 +1810,59 @@ interface YrsSession extends CollaborationReplica {
1189
1810
  /** Same pass, but the reply omits the measured arena (fetch it on demand
1190
1811
  * through {@link YrsSession.retainedKernelInputsJson}). */
1191
1812
  layoutDocumentWithRegionsRetainedJson(input: string): string;
1813
+ /**
1814
+ * {@link YrsSession.layoutDocumentWithRegionsRetainedJson} a step at a time:
1815
+ * this lowers the body, and each {@link YrsSession.resumeRegionLayout}
1816
+ * measures up to `blocks` more body blocks. `layoutJson` arrives with the
1817
+ * step that completes the pass, equal to the one-call reply. A document
1818
+ * change, a font registration or another layout in between abandons the
1819
+ * pass, and resuming it then throws.
1820
+ */
1821
+ beginRegionLayout(input: string): YrsRegionLayoutProgress;
1822
+ resumeRegionLayout(blocks: number): YrsRegionLayoutProgress;
1192
1823
  /** Retained `{ measured, options }` for the main-thread display fallback. */
1193
1824
  retainedKernelInputsJson(expectedLayoutRevision: number): string;
1825
+ /**
1826
+ * Record region layout `input` as the resident layout without running it
1827
+ * here: a resident worker replica runs it, and snapshots carry it there.
1828
+ * Returns the new layout revision. @internal
1829
+ */
1830
+ adoptResidentWorkerLayout?(input: string): number;
1831
+ /** The current resident layout ran only in a worker replica. @internal */
1832
+ residentLayoutInWorker?(): boolean;
1194
1833
  /** Build display primitives against the session's resident font store. */
1195
1834
  buildDisplayListJson(input: string): string;
1196
1835
  /** Build a binary FrameDelta v1 against the last host-applied frame. */
1197
1836
  buildDisplayListFrame(input: string, expectedFrameEpoch: number): Uint8Array;
1837
+ /**
1838
+ * Limit full display builds to pages `start..end` plus the pages already
1839
+ * built; the rest stay unbuilt placeholders carrying their geometry. @internal
1840
+ */
1841
+ setDisplayWindow(start: number, end: number): void;
1842
+ /** Keep every previously built page while windowed builds are on. @internal */
1843
+ setDisplayRetainBuiltPages(retain: boolean): void;
1844
+ /** Build the listed unbuilt pages into a FrameDelta v1. @internal */
1845
+ buildDisplayPagesFrame(pages: readonly number[], expectedFrameEpoch: number): Uint8Array;
1846
+ /** Make the next frame a full one, for a host taking over from another engine; no-op once destroyed. */
1847
+ resetFrameBase(): void;
1198
1848
  /** Caret geometry from the current resident display frame. */
1199
1849
  residentCaretSnapshot(): YrsResidentCaretSnapshot;
1200
1850
  /** Apply a collapsed plain-text insertion and return its resident FrameDelta. */
1201
1851
  applyInput(text: string, expectedFrameEpoch: number): Uint8Array;
1202
- /** Apply a collapsed character deletion/paragraph merge and return its resident FrameDelta. */
1203
- applyDelete(direction: 'backward' | 'forward', expectedFrameEpoch: number): Uint8Array;
1852
+ /**
1853
+ * Apply up to `count` (default 1) collapsed character deletions/paragraph
1854
+ * merges, lay out once, and return the resident FrameDelta.
1855
+ */
1856
+ applyDelete(direction: 'backward' | 'forward', expectedFrameEpoch: number, count?: number): Uint8Array;
1857
+ /** Characters the last resident deletion removed; fewer than asked at a document boundary. */
1858
+ residentDeletedUnits(): number;
1204
1859
  /** Instrumented apply used only by opt-in browser performance traces. */
1205
1860
  applyInputProfiled(text: string, expectedFrameEpoch: number): {
1206
1861
  frame: Uint8Array;
1207
1862
  profile: YrsEngineApplyProfile;
1208
1863
  };
1209
1864
  /** Instrumented deletion used only by opt-in browser performance traces. */
1210
- applyDeleteProfiled(direction: 'backward' | 'forward', expectedFrameEpoch: number): {
1865
+ applyDeleteProfiled(direction: 'backward' | 'forward', expectedFrameEpoch: number, count?: number): {
1211
1866
  frame: Uint8Array;
1212
1867
  profile: YrsEngineApplyProfile;
1213
1868
  };
@@ -1239,14 +1894,51 @@ interface YrsSession extends CollaborationReplica {
1239
1894
  * one seeded alike by the same client; see {@link beginOpening}.
1240
1895
  */
1241
1896
  openDocx(bytes: Uint8Array, seedStories: boolean, options?: YrsOpeningOptions): YrsDocxHost;
1897
+ /**
1898
+ * Opens a DOCX for display only, from the body's first `blocks` blocks:
1899
+ * enough to lay out its first pages with a prefix pass before the whole
1900
+ * document is opened. The session cannot save. `null`, opening nothing,
1901
+ * for a document with a float placed from outside the text or a section
1902
+ * with columns, which no cut of the body lays out like the whole: open it
1903
+ * with {@link openDocx}. @internal
1904
+ */
1905
+ openDocxPreview(bytes: Uint8Array, blocks: number): YrsDocxHost | null;
1906
+ /** Opened by {@link openDocxPreview}: its document refuses every change. @internal */
1907
+ isDisplayOnly(): boolean;
1908
+ /**
1909
+ * Marks whether the document is a preview's, as a replica of one is: its
1910
+ * layouts render NUMPAGES empty. @internal
1911
+ */
1912
+ setPartialDocument(partial: boolean): void;
1913
+ /**
1914
+ * The region layout of only as much of the body as fills `pages` pages;
1915
+ * a reply marked `provisional` covers a prefix. @internal
1916
+ */
1917
+ layoutDocumentWithRegionsPrefixRetainedJson(input: string, pages: number): string;
1242
1918
  /**
1243
1919
  * Starts a new opening of the document: its generation, replicated to
1244
1920
  * every replica, becomes part of every session anchor. Every seeding entry
1245
1921
  * point calls it; call it after building a document another way.
1246
1922
  */
1247
1923
  beginOpening(generation?: string): void;
1924
+ /** Unions seeded opaque sequence names into document state. @internal */
1925
+ seedOpaqueSequences(names: readonly string[]): void;
1248
1926
  /** Materializes the retained canonical package for compatibility APIs. */
1249
1927
  materializeDocx(): Document | null;
1928
+ /**
1929
+ * The displayed bytes and media type of the package part a `media:{n}`
1930
+ * image source names, or `null` for any other source or a destroyed session.
1931
+ */
1932
+ mediaSource(token: string): YrsMediaSource | null;
1933
+ /** Changes on package opening and session destruction. */
1934
+ mediaScope(): number;
1935
+ /** The `data:` URL a token stands for, or `null` when unavailable or destroyed. */
1936
+ mediaDataUrl(token: string): string | null;
1937
+ /**
1938
+ * Lays this replica's `data:` image sources out as the `media:{n}` tokens a
1939
+ * snapshot's `mediaSources` names. @internal
1940
+ */
1941
+ loadMediaSources(json: string): void;
1250
1942
  /**
1251
1943
  * Seeds stories and returns paragraph IDs in document order. Seeding a
1252
1944
  * document that has no opening yet starts one; see {@link beginOpening}.
@@ -1262,6 +1954,8 @@ interface YrsSession extends CollaborationReplica {
1262
1954
  applyUpdate(update: Uint8Array): CollaborationTextInsertion | null;
1263
1955
  /** Apply a same-user worker update under the local undo origin. @internal */
1264
1956
  applyLocalUpdate(update: Uint8Array): void;
1957
+ /** Adopt another replica's host batch outside undo history. @internal */
1958
+ applyHostUpdate(update: Uint8Array, stories?: readonly string[]): void;
1265
1959
  /**
1266
1960
  * Subscribes to every committed transaction's v1 update (local AND
1267
1961
  * applied-remote). Returns an unsubscribe function.
@@ -1342,7 +2036,7 @@ interface YrsSession extends CollaborationReplica {
1342
2036
  */
1343
2037
  deleteRange(range: YrsStoryRange, suggesting?: YrsAuthor): YrsRevisionReceipt;
1344
2038
  /** Replaces a range with text in one transaction (one shared revision when suggesting). */
1345
- replaceRange(range: YrsStoryRange, text: string, suggesting?: YrsAuthor): YrsRevisionReceipt;
2039
+ replaceRange(range: YrsStoryRange, text: string, suggesting?: YrsAuthor): YrsReplaceReceipt;
1346
2040
  /**
1347
2041
  * Splits a paragraph by inserting one pilcrow. The FIRST half keeps the
1348
2042
  * original paraId; the SECOND half is re-minted (`secondParaId`).
@@ -1396,7 +2090,10 @@ interface YrsSession extends CollaborationReplica {
1396
2090
  * promotes an editor-only paragraph they author into.
1397
2091
  */
1398
2092
  applyRawOps(story: string, ops: readonly YrsRawOp[]): void;
1399
- /** Applies seed raw operations with deterministic item ordering. */
2093
+ /**
2094
+ * Applies seed raw operations with deterministic item ordering. A
2095
+ * `setComment` for a comment already seeded adds its ranges to it.
2096
+ */
1400
2097
  applySeedRawOps(story: string, ops: readonly YrsRawOp[]): void;
1401
2098
  /** Sets one paragraph property (any JSON value). `paraId` is reserved. */
1402
2099
  setParagraphAttr(paraId: string, key: string, value: unknown): void;
@@ -1428,6 +2125,8 @@ interface YrsSession extends CollaborationReplica {
1428
2125
  listComments(): YrsCommentInfo[];
1429
2126
  /** Story ids in the document, sorted. */
1430
2127
  storyIds(): string[];
2128
+ /** Whether the document has a story with this id, without listing them all. */
2129
+ hasStory(story: string): boolean;
1431
2130
  /** Story length in UTF-16 units (every embed, pilcrows included, counts 1). */
1432
2131
  storyLength(story: string): number;
1433
2132
  /** Returns the story's canonical-stream checksum. */
@@ -1442,8 +2141,31 @@ interface YrsSession extends CollaborationReplica {
1442
2141
  paragraphSpans(story: string): YrsParagraphLength[];
1443
2142
  /** The raw formatted-segment view (the render bridge's input). */
1444
2143
  storySegments(story: string): YrsStorySegment[];
2144
+ /**
2145
+ * The current story revision and the sorted ids of the stories created,
2146
+ * edited, or deleted after revision `since` (0 lists every story).
2147
+ */
2148
+ storiesChangedSince(since: number): {
2149
+ revision: number;
2150
+ stories: string[];
2151
+ };
2152
+ /**
2153
+ * One digest per unit of {@link YrsSession.storySegments}, split after each
2154
+ * pilcrow. Equal digests mean equal segments.
2155
+ */
2156
+ storySegmentUnitDigests(story: string): string[];
2157
+ /** The segments of the listed units, each as {@link YrsSession.storySegments} gives them. */
2158
+ storySegmentUnits(story: string, units: readonly number[]): YrsStorySegment[][];
2159
+ /**
2160
+ * The payload of the story's `tableIndex`-th table embed, as
2161
+ * {@link YrsSession.storySegments} gives it, or null when there is no such
2162
+ * table. Reads the one table rather than the whole story.
2163
+ */
2164
+ tablePayload(story: string, tableIndex: number): Record<string, unknown> | null;
1445
2165
  /** A paragraph's story span (start unit, pilcrow index). */
1446
2166
  locateParagraph(story: string, paraId: string): YrsParagraphSpan;
2167
+ /** How many paragraphs of `story` carry `paraId`: 0, 1, or 2 for two or more. */
2168
+ paragraphIdCount(story: string, paraId: string): number;
1447
2169
  /**
1448
2170
  * Session, persisted and source anchors of every paragraph, including the
1449
2171
  * source package's paragraphs outside the stories, and the Word paragraph ID
@@ -1501,6 +2223,32 @@ interface YrsSession extends CollaborationReplica {
1501
2223
  }): YrsTargetEditResult;
1502
2224
  /** Accepted-view texts around a paragraph-keyed selection. @internal */
1503
2225
  selectionText(range: YrsStoryRange): YrsSelectionText;
2226
+ /**
2227
+ * Proposes a round of tracked changes: every new proposal resolves against `expectVersion` and
2228
+ * the round applies as one batch outside undo history, or nothing changes. A retried id with
2229
+ * the same edit is a no-op; the same id with another edit refuses. Opening another document
2230
+ * forgets every proposal.
2231
+ */
2232
+ proposeChanges(request: DocxProposalRequest): DocxProposalResult;
2233
+ /**
2234
+ * Sets how proposals render. Decisions change neither the document, its version nor undo
2235
+ * history; each call that changes one increments `previewVersion`.
2236
+ */
2237
+ setProposalStates(request: DocxProposalStateRequest): DocxProposalResult;
2238
+ /**
2239
+ * Withdraws proposals, settling each as its decision previews it: accepted ones apply for good,
2240
+ * rejected and undecided ones are removed. The settlement is one change against `expectVersion`
2241
+ * outside undo history, so a later round resolves against the text the preview showed.
2242
+ */
2243
+ withdrawProposals(request: DocxProposalWithdrawRequest): DocxProposalResult;
2244
+ /** The proposals in the order they were made. */
2245
+ getProposals(): DocxProposalSnapshot;
2246
+ /** @internal */
2247
+ mirrorWorkerDocument(mirror: YrsWorkerDocumentMirror | null): void;
2248
+ /** @internal */
2249
+ workerDocumentMirrored(): boolean;
2250
+ /** Listens for new proposals, decisions and a forgotten registry. Returns the unsubscribe. */
2251
+ onProposalChange(listener: (snapshot: DocxProposalSnapshot) => void): () => void;
1504
2252
  /**
1505
2253
  * Exports the committed document as read-only structured content with the version it was read
1506
2254
  * at; anchors resolve against that version. Nothing is committed, flushed or published.
@@ -1560,6 +2308,11 @@ interface CreateYrsSessionOptions {
1560
2308
  */
1561
2309
  clientId?: number;
1562
2310
  }
2311
+ /**
2312
+ * Decodes the host metadata a resident worker's `open` replied with, for the
2313
+ * package `source` it opened. @internal
2314
+ */
2315
+ declare function decodeDocxHostJson(json: string, source: Uint8Array): YrsDocxHost;
1563
2316
  /**
1564
2317
  * Creates a yrs editing replica. The first call dynamically imports and
1565
2318
  * initializes the embedded docx-edit wasm (~440KB base64) — callers must
@@ -1567,4 +2320,4 @@ interface CreateYrsSessionOptions {
1567
2320
  */
1568
2321
  declare function createYrsSession(options?: CreateYrsSessionOptions): Promise<YrsSession>;
1569
2322
 
1570
- export { type YrsCellLoc as $, type DocxParagraphIdOrigin as A, type DocxParagraphIdRefusal as B, type CollaborationReplica as C, type DocxParagraphAnchor as D, type DocxParagraphIdentity as E, type DocxParagraphIdentityReceipt as F, type DocxParagraphIdentitySnapshot as G, type DocxParagraphOrigin as H, type DocxParagraphRef as I, type DocxParagraphSavePlan as J, type DocxPersistedParagraphAnchor as K, type DocxSavedDocument as L, type DocxSavedParagraph as M, type DocxSessionParagraphAnchor as N, type DocxSessionSave as O, type DocxSourceParagraphAnchor as P, type DocxSourceStory as Q, type ResidentCaretPaintStyle as R, type ResidentEngineOffscreenPage as S, type ResidentEngineWorkerApplyResult as T, ResidentEngineWorkerClient as U, type ResidentEngineWorkerFrame as V, ResidentWorkerFailureError as W, type YrsAuthor as X, type YrsSession as Y, type YrsCellBorder as Z, type YrsCellBorders as _, type YrsRenderEnv as a, type YrsChangeTarget as a0, type YrsCommentInfo as a1, type YrsCommentReceipt as a2, type YrsContentControlValue as a3, type YrsDocxHost as a4, type YrsEngineApplyProfile as a5, type YrsHyperlinkAttrs as a6, type YrsImageGeometry as a7, type YrsInlineFormatDelta as a8, type YrsInputParagraphSeed as a9, type YrsStoryRange as aA, type YrsStorySeed as aB, type YrsStorySegment as aC, type YrsTableLoc as aD, type YrsTableRange as aE, type YrsTableReceipt as aF, type YrsTargetEditResult as aG, type YrsTextColor as aH, type YrsTextMatch as aI, type YrsTextSearchOptions as aJ, type YrsTriState as aK, type YrsUndoCaptureMode as aL, type YrsWatermark as aM, canUseResidentEngineWorker as aN, captureSessionSave as aO, compareYrsLocs as aP, createYrsInputPositionMap as aQ, createYrsSession as aR, displayPositionToYrsLoc as aS, documentToYrs as aT, residentCaretDeviceRect as aU, residentCaretSnapshotForFrame as aV, sameYrsSelection as aW, saveYrsDocx as aX, writeSessionSave as aY, yrsLocToDisplayPosition as aZ, yrsToDocument as a_, type YrsInputParagraphSpan as aa, type YrsInputPositionMap as ab, type YrsNumberingProperties as ac, type YrsOpeningOptions as ad, type YrsParaOffset as ae, type YrsParagraph as af, type YrsParagraphAttrs as ag, type YrsParagraphLength as ah, type YrsParagraphReceipt as ai, type YrsParagraphSeed as aj, type YrsParagraphSpan as ak, type YrsParagraphTabStop as al, type YrsRawOp as am, type YrsResidentCaretRect as an, type YrsResidentCaretSnapshot as ao, type YrsResidentFontRegistration as ap, type YrsResidentWorkerSnapshot as aq, type YrsResidentWorkerSyncOptions as ar, type YrsResolveReceipt as as, type YrsResolvedCommentAnchor as at, type YrsRevisionReceipt as au, type YrsRunMark as av, type YrsSelectionContext as aw, type YrsSelectionText as ax, type YrsSplitReceipt as ay, type YrsStickyPosition as az, type CollaborationTransport as b, type CollaborationProviderOptions as c, type CollaborationStatus as d, type CollaborationPeer as e, type CollaborationCursor as f, type CollaborationPeerListener as g, type CollaborationStatusListener as h, type CollaborationErrorListener as i, type YrsSelection as j, type CollaborationAwarenessState as k, CollaborationError as l, type CollaborationErrorCode as m, type CollaborationPresence as n, type CollaborationResolvedUser as o, type CollaborationStatusChange as p, type CollaborationTextInsertion as q, type CollaborationTransportEvent as r, type CollaborationUpdateOrigin as s, type CollaborationUser as t, type YrsLoc as u, type YrsRevisionInfo as v, type CreateYrsSessionOptions as w, type DocxParagraphAnchorResult as x, type DocxParagraphIdAssignment as y, type DocxParagraphIdDiagnostic as z };
2323
+ export { type DocxSavedDocument as $, type AnchorGeometryTarget as A, type DocxParagraphAnchor as B, type CollaborationReplica as C, type DocxOccurrence as D, type DocxParagraphAnchorResult as E, type DocxParagraphIdAssignment as F, type DocxParagraphIdDiagnostic as G, type DocxParagraphIdOrigin as H, type DocxParagraphIdRefusal as I, type DocxParagraphIdentity as J, type DocxParagraphIdentityReceipt as K, type DocxParagraphIdentitySnapshot as L, type DocxParagraphOrigin as M, type DocxParagraphRef as N, type DocxParagraphSavePlan as O, type DocxPersistedParagraphAnchor as P, type DocxProposalFailure as Q, type DocxProposalInput as R, type DocxProposalRecord as S, type DocxProposalRegistryState as T, type DocxProposalRequest as U, type DocxProposalResult as V, type DocxProposalSnapshot as W, type DocxProposalState as X, type YrsSession as Y, type DocxProposalStateRequest as Z, type DocxProposalWithdrawRequest as _, type YrsRenderEnv as a, type YrsSelectionContext as a$, type DocxSavedParagraph as a0, type DocxSessionParagraphAnchor as a1, type DocxSessionSave as a2, type DocxSourceParagraphAnchor as a3, type DocxSourceStory as a4, type ProposalDisplayTarget as a5, type ProposalGeometryMirror as a6, type ProposalGeometryReader as a7, type ProposalGeometryTarget as a8, type RawAnchorRange as a9, type YrsNumberingProperties as aA, type YrsOpeningOptions as aB, type YrsParaOffset as aC, type YrsParagraph as aD, type YrsParagraphAttrs as aE, type YrsParagraphLength as aF, type YrsParagraphReceipt as aG, type YrsParagraphSeed as aH, type YrsParagraphSpan as aI, type YrsParagraphTabStop as aJ, type YrsPointerProjectionTarget as aK, YrsPositionProjection as aL, type YrsProjectedCell as aM, type YrsProjectedNode as aN, type YrsProjectedTable as aO, type YrsRawOp as aP, type YrsRegionLayoutProgress as aQ, type YrsReplaceReceipt as aR, type YrsResidentCaretRect as aS, type YrsResidentCaretSnapshot as aT, type YrsResidentFontRegistration as aU, type YrsResidentWorkerSnapshot as aV, type YrsResidentWorkerSyncOptions as aW, type YrsResolveReceipt as aX, type YrsResolvedCommentAnchor as aY, type YrsRevisionReceipt as aZ, type YrsRunMark as a_, type ResidentCaretPaintStyle as aa, type ResidentEngineOffscreenPage as ab, type ResidentEngineWorkerApplyResult as ac, ResidentEngineWorkerClient as ad, type ResidentEngineWorkerFrame as ae, type ResidentEngineWorkerOpened as af, type ResidentProposalReply as ag, ResidentWorkerFailureError as ah, ResidentWorkerOutOfMemoryError as ai, type YrsAuthor as aj, type YrsCellBorder as ak, type YrsCellBorders as al, type YrsCellLoc as am, type YrsChangeTarget as an, type YrsCommentInfo as ao, type YrsCommentReceipt as ap, type YrsContentControlValue as aq, type YrsDocxHost as ar, type YrsEngineApplyProfile as as, type YrsHyperlinkAttrs as at, type YrsImageGeometry as au, type YrsInlineFormatDelta as av, type YrsInputParagraphSeed as aw, type YrsInputParagraphSpan as ax, type YrsInputPositionMap as ay, type YrsMediaSource as az, type CollaborationTransport as b, type YrsSelectionText as b0, type YrsSplitReceipt as b1, type YrsStickyPosition as b2, type YrsStoryRange as b3, type YrsStorySeed as b4, type YrsStorySegmentSource as b5, type YrsTableLoc as b6, type YrsTableRange as b7, type YrsTableReceipt as b8, type YrsTargetEditResult as b9, proposalRevisionPreview as bA, proposalSetIdentity as bB, residentCaretDeviceRect as bC, residentCaretSnapshotForFrame as bD, resolveAnchorTarget as bE, resolveNavigationTarget as bF, retainPreloadedResidentEngineWorker as bG, sameYrsSelection as bH, saveYrsDocx as bI, sessionSourcePackage as bJ, takePreloadedResidentEngineWorker as bK, textRangeToRaw as bL, writeSessionSave as bM, yrsLocToDisplayPosition as bN, yrsLocToProjectedDisplayPosition as bO, yrsToDocument as bP, type YrsTextColor as ba, type YrsTextMatch as bb, type YrsTextSearchOptions as bc, type YrsTriState as bd, type YrsUndoCaptureMode as be, type YrsWatermark as bf, type YrsWorkerDocumentMirror as bg, anchorFailure as bh, canUseResidentEngineWorker as bi, captureSessionSave as bj, compareYrsLocs as bk, computeProposalGeometryMirror as bl, createYrsInputPositionMap as bm, createYrsPositionProjection as bn, createYrsSession as bo, decodeDocxHostJson as bp, displayPositionToYrsLoc as bq, documentToYrs as br, editorSaveKeys as bs, hiddenRanges as bt, isBodyStory as bu, preloadDocxEngine as bv, preloadResidentEngineWorker as bw, prepareDocxBytes as bx, preparedDocxDigest as by, projectYrsDisplayPosition as bz, type CollaborationProviderOptions as c, type CollaborationStatus as d, type CollaborationPeer as e, type CollaborationCursor as f, type CollaborationPeerListener as g, type CollaborationStatusListener as h, type CollaborationErrorListener as i, type YrsSelection as j, type CollaborationAwarenessState as k, CollaborationError as l, type CollaborationErrorCode as m, type CollaborationPresence as n, type CollaborationResolvedUser as o, type CollaborationStatusChange as p, type CollaborationTextInsertion as q, type CollaborationTransportEvent as r, type CollaborationUpdateOrigin as s, type CollaborationUser as t, type YrsLoc as u, type YrsStorySegment as v, type YrsRevisionInfo as w, type AnchorReader as x, type AnchorResolutionFailure as y, type CreateYrsSessionOptions as z };