@stll/folio-core 0.61.0 → 0.63.0

package/dist/display-list/types.d.ts

@@ -37,14 +37,14 @@
  * in 0..1; a producer that emits a fractional channel produces CSS a backend
  * cannot serialize.
  */
-type DisplayColor = {
+export type DisplayColor = {
   readonly r: number;
   readonly g: number;
   readonly b: number;
   readonly a: number;
 };
 /** A rectangle in page coordinates. */
-type DisplayRect = {
+export type DisplayRect = {
   readonly xPx: number;
   readonly yPx: number;
   readonly widthPx: number;
@@ -56,14 +56,14 @@ type DisplayRect = {
  * what the other did. Dash and gap lengths live in `primitives.ts` and are
  * imported by both backends, so neither invents a period of its own.
  */
-type DisplayStrokePattern = "solid" | "dashed" | "dotted" | "double" | "wavy";
+export type DisplayStrokePattern = "solid" | "dashed" | "dotted" | "double" | "wavy";
 /**
  * A stroke is centred on its path: half the thickness falls on each side.
  * Stated because the backends default differently (a CSS border sits inside
  * its box, a PDF stroke is centred), and an unstated default is a divergence
  * that a reader finds rather than a test.
  */
-type DisplayStroke = {
+export type DisplayStroke = {
   readonly color: DisplayColor;
   readonly thicknessPx: number;
   readonly pattern: DisplayStrokePattern;
@@ -75,7 +75,7 @@ type DisplayStroke = {
  * a backend cannot obtain is exactly the divergence this carries bytes to
  * prevent.
  */
-type DisplayEmbeddedFont = {
+export type DisplayEmbeddedFont = {
   readonly id: string;
   /** Deobfuscated sfnt or WOFF bytes. */
   readonly bytes: Uint8Array;
@@ -85,7 +85,7 @@ type DisplayEmbeddedFont = {
  * the measurement was taken against, not the authored OOXML name, so a
  * backend embedding a face embeds the face the widths came from.
  */
-type DisplayFontFace = {
+export type DisplayFontFace = {
   readonly family: string;
   /** CSS weight; folio paints 400 and 700 only. */
   readonly weight: number;
@@ -119,16 +119,16 @@ type DisplayFontFace = {
   readonly embedded?: DisplayEmbeddedFont;
 };
 /** Index into {@link DisplayList.fonts}. */
-type DisplayFontRef = number;
+export type DisplayFontRef = number;
 /** Index into {@link DisplayList.images}. */
-type DisplayImageRef = number;
+export type DisplayImageRef = number;
 /**
  * Raw image bytes plus the format they are already in. `png` and `jpeg`
- * pass through to PDF unchanged; every other source format is transcoded by
- * the producer, so a backend never owns a codec.
+ * pass through to PDF unchanged. SVG is retained for vector previews in the
+ * DOM backend; PDF reports it as unsupported rather than silently rasterizing.
  */
-type DisplayImageSource = {
-  readonly format: "png" | "jpeg";
+export type DisplayImageSource = {
+  readonly format: "png" | "jpeg" | "svg";
   readonly bytes: Uint8Array;
   readonly pixelWidth: number;
   readonly pixelHeight: number;
@@ -143,7 +143,7 @@ type DisplayImageSource = {
  * to drop the others and the painter used to strip them; naming the story is
  * what lets an editing surface route a click into the story it landed in.
  */
-type DisplayStoryRef = {
+export type DisplayStoryRef = {
   readonly kind: "body";
 } |
 /** `rId` is the relationship that names the part, as the section selects it. */
@@ -156,7 +156,7 @@ type DisplayStoryRef = {
   readonly kind: "footnote" | "endnote";
   readonly id: number;
 };
-type DisplayModelRange = {
+export type DisplayModelRange = {
   readonly start: number;
   readonly end: number;
   readonly story: DisplayStoryRef;
@@ -196,7 +196,11 @@ type DisplayModelRange = {
  * `horizontalScale`. A backend that applies the scale as a transform divides by
  * it first, because a transform scales the spacing it is given.
  */
-type DisplayRunAdjustments = {
+export type DisplayRunAdjustments = {
+  readonly automaticTextSpacingGaps?: readonly {
+    readonly offset: number;
+    readonly advancePx: number;
+  }[];
   /** Added after every code point of the run but the last. */
   readonly letterSpacingPx: number;
   /** Multiplies every advance. 1 when the run carries no `w:w`. */
@@ -204,7 +208,7 @@ type DisplayRunAdjustments = {
   /** Added to each compressible space, negative on a contracted line. */
   readonly wordSpacingPx: number;
 };
-type DisplayGlyphRun = {
+export type DisplayGlyphRun = {
   readonly kind: "glyphRun";
   readonly font: DisplayFontRef;
   readonly fontSizePx: number;
@@ -278,9 +282,13 @@ type DisplayGlyphRun = {
    * substituted field value, a tab leader.
    */
   readonly pmRange?: DisplayModelRange;
+  /** Source atom for view-only decorations; never used for editing positions. */
+  readonly decorationRange?: DisplayModelRange & {
+    readonly textOffset: number;
+  };
 };
 /** An axis-aligned rectangle, filled and/or stroked. At least one is set. */
-type DisplayRectPrimitive = {
+export type DisplayRectPrimitive = {
   readonly kind: "rect";
   readonly rect: DisplayRect;
   readonly fill?: DisplayColor;
@@ -291,7 +299,7 @@ type DisplayRectPrimitive = {
  * text decorations are all this one primitive, so a dashed underline and a
  * dashed cell border cannot be drawn by two different rules.
  */
-type DisplayLine = {
+export type DisplayLine = {
   readonly kind: "line";
   readonly x1Px: number;
   readonly y1Px: number;
@@ -299,7 +307,25 @@ type DisplayLine = {
   readonly y2Px: number;
   readonly stroke: DisplayStroke;
 };
-type DisplayImagePrimitive = {
+/** A closed, solid-filled polygon. */
+export type DisplayPolygon = {
+  readonly kind: "polygon";
+  readonly points: readonly {
+    readonly xPx: number;
+    readonly yPx: number;
+  }[];
+  readonly fill: DisplayColor;
+};
+/** An open, stroked path through two or more points. */
+export type DisplayPolyline = {
+  readonly kind: "polyline";
+  readonly points: readonly {
+    readonly xPx: number;
+    readonly yPx: number;
+  }[];
+  readonly stroke: DisplayStroke;
+};
+export type DisplayImagePrimitive = {
   readonly kind: "image";
   readonly image: DisplayImageRef;
   /** Destination box, after cropping and rotation have been resolved. */
@@ -318,7 +344,7 @@ type DisplayImagePrimitive = {
   readonly contrast?: number;
 };
 /** Clips its children to `rect`. Used for cropped images and cell overflow. */
-type DisplayClipGroup = {
+export type DisplayClipGroup = {
   readonly kind: "clipGroup";
   readonly rect: DisplayRect;
   readonly children: readonly DisplayPrimitive[];
@@ -331,7 +357,7 @@ type DisplayClipGroup = {
  * table text are all this. A scale of `-1` is a DrawingML flip; the scale is
  * applied before the rotation, matching CSS and OOXML transform order.
  */
-type DisplayRotateGroup = {
+export type DisplayRotateGroup = {
   readonly kind: "rotateGroup";
   readonly degrees: number;
   readonly originXPx: number;
@@ -343,23 +369,23 @@ type DisplayRotateGroup = {
   readonly children: readonly DisplayPrimitive[];
 };
 /** Uniform alpha over a subtree, for watermark washout and image opacity. */
-type DisplayOpacityGroup = {
+export type DisplayOpacityGroup = {
   readonly kind: "opacityGroup";
   readonly opacity: number;
   readonly children: readonly DisplayPrimitive[];
 };
-type DisplayPrimitive = DisplayGlyphRun | DisplayRectPrimitive | DisplayLine | DisplayImagePrimitive | DisplayClipGroup | DisplayRotateGroup | DisplayOpacityGroup;
+export type DisplayPrimitive = DisplayGlyphRun | DisplayRectPrimitive | DisplayLine | DisplayPolygon | DisplayPolyline | DisplayImagePrimitive | DisplayClipGroup | DisplayRotateGroup | DisplayOpacityGroup;
 /**
  * A clickable region. Annotations are not paint: they sit beside the
  * primitive list so a backend that cannot express them (a raster) drops them
  * without silently losing a drawing instruction.
  */
-type DisplayLink = {
+export type DisplayLink = {
   readonly rect: DisplayRect;
   readonly target: DisplayLinkTarget;
   readonly tooltip?: string;
 };
-type DisplayLinkTarget = {
+export type DisplayLinkTarget = {
   readonly kind: "external";
   readonly href: string;
 } |
@@ -381,7 +407,7 @@ type DisplayLinkTarget = {
  * retained. Raster backends use those rectangles for the highlight; PDF uses
  * the final one as the location of its single text annotation.
  */
-type DisplayCommentAnnotation = {
+export type DisplayCommentAnnotation = {
   readonly commentId: number;
   readonly rects: readonly DisplayRect[];
   readonly contents: string;
@@ -396,7 +422,7 @@ type DisplayCommentAnnotation = {
  * every reader learned that structure; naming them here makes the answer a
  * property of the page rather than of the markup that happened to paint it.
  */
-type DisplayHitRegionKind =
+export type DisplayHitRegionKind =
 /** The page's content area, inside its margins. */
 "pageContent" | "headerSlot" | "footerSlot" |
 /** One note's body in the band at the foot of the page. */
@@ -414,7 +440,7 @@ type DisplayHitRegionKind =
  * attribute the painter wrote. They are optional because they are properties of
  * particular kinds: a cell has a column index and a paragraph does not.
  */
-type DisplayHitRegionModel = {
+export type DisplayHitRegionModel = {
   /** Model range and story, for a region a caret can land in. */
   readonly pmRange?: DisplayModelRange;
   /** The story a slot or note region *is*, whether or not it has a range. */
@@ -440,7 +466,7 @@ type DisplayHitRegionModel = {
  * borders, a watermark. Nothing about them is editable, so nothing has to
  * resolve them.
  */
-type DisplayHitRegion = {
+export type DisplayHitRegion = {
   readonly kind: DisplayHitRegionKind;
   readonly rect: DisplayRect;
   /** First primitive of this region, as an index into the page's list. */
@@ -450,7 +476,7 @@ type DisplayHitRegion = {
   readonly children: readonly DisplayHitRegion[];
   readonly model?: DisplayHitRegionModel;
 };
-type DisplayPage = {
+export type DisplayPage = {
   /** Physical 1-based page number, as the layout engine numbered it. */
   readonly pageNumber: number;
   readonly widthPx: number;
@@ -471,14 +497,14 @@ type DisplayPage = {
   readonly comments: readonly DisplayCommentAnnotation[];
 };
 /** One heading, for a document outline. `pageIndex` is 0-based. */
-type DisplayOutlineEntry = {
+export type DisplayOutlineEntry = {
   readonly title: string;
   /** OOXML outline level, 0 for Heading 1. */
   readonly level: number;
   readonly pageIndex: number;
   readonly yPx: number;
 };
-type DisplayMetadata = {
+export type DisplayMetadata = {
   readonly title?: string;
   readonly author?: string;
   readonly subject?: string;
@@ -491,12 +517,12 @@ type DisplayMetadata = {
  * `unsupported`: a page that is missing paint must say so, because a backend
  * cannot tell an empty region from an unimplemented one.
  */
-type DisplayUnsupported = {
+export type DisplayUnsupported = {
   readonly construct: string;
   readonly pageIndex: number;
   readonly detail: string;
 };
-type DisplayList = {
+export type DisplayList = {
   readonly pages: readonly DisplayPage[];
   readonly fonts: readonly DisplayFontFace[];
   readonly images: readonly DisplayImageSource[];
@@ -504,5 +530,4 @@ type DisplayList = {
   readonly metadata: DisplayMetadata;
   readonly unsupported: readonly DisplayUnsupported[];
 };
-//#endregion
-export { DisplayClipGroup, DisplayColor, DisplayCommentAnnotation, DisplayEmbeddedFont, DisplayFontFace, DisplayFontRef, DisplayGlyphRun, DisplayHitRegion, DisplayHitRegionKind, DisplayHitRegionModel, DisplayImagePrimitive, DisplayImageRef, DisplayImageSource, DisplayLine, DisplayLink, DisplayLinkTarget, DisplayList, DisplayMetadata, DisplayModelRange, DisplayOpacityGroup, DisplayOutlineEntry, DisplayPage, DisplayPrimitive, DisplayRect, DisplayRectPrimitive, DisplayRotateGroup, DisplayRunAdjustments, DisplayStoryRef, DisplayStroke, DisplayStrokePattern, DisplayUnsupported };
+//#endregion

package/dist/document-operations.d.ts

@@ -3,17 +3,17 @@ import { FolioTableTemplates } from "./ai-edits/table-template.js";
 import { FolioAIEditAppliedOperation, FolioAIEditApplyMode, FolioAIEditNormalization, FolioAIEditOperation, FolioAIEditPrecondition, FolioAIEditSkippedOperation, FolioAIEditSnapshot, FolioAITextRangeHandle } from "./ai-edits/types.js";
 import { FolioAIEditView, FolioReplacementBackground, FolioRevisionStamp, FolioUndefinedReferencePolicy, FolioWordDiffOptions } from "./ai-edits/apply.js";
 //#region src/document-operations.d.ts
-declare const FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION: 1;
+export declare const FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION: 1;
 /** Direct paragraph-alignment values accepted by the operation contract. */
-declare const FOLIO_PARAGRAPH_ALIGNMENT_VALUES: readonly document_d_exports.ParagraphAlignment[];
+export declare const FOLIO_PARAGRAPH_ALIGNMENT_VALUES: readonly document_d_exports.ParagraphAlignment[];
 /** `w:spacing/@w:lineRule` values accepted by the operation contract. */
-declare const FOLIO_LINE_SPACING_RULE_VALUES: readonly document_d_exports.LineSpacingRule[];
+export declare const FOLIO_LINE_SPACING_RULE_VALUES: readonly document_d_exports.LineSpacingRule[];
 /** `w:br/@w:clear` values accepted on an authored hard page break. */
-declare const FOLIO_PAGE_BREAK_CLEAR_VALUES: readonly ["none", "left", "right", "all"];
-declare const FOLIO_DOCUMENT_OPERATION_TYPES: readonly ["replaceInBlock", "replaceRange", "commentOnRange", "formatRange", "insertAfterBlock", "insertBeforeBlock", "replaceBlock", "deleteBlock", "splitBlock", "mergeBlockWithNext", "setBlockParagraphProperties", "insertTable", "deleteTable", "commentOnBlock", "insertSignatureTable", "insertTableRow", "deleteTableRow", "insertTableColumn", "deleteTableColumn", "mergeTableCells", "splitTableCell"];
-declare const FOLIO_DOCUMENT_OPERATION_MODES: readonly ["direct", "tracked-changes", "suggested"];
-declare const FOLIO_DOCUMENT_OPERATION_STORIES: readonly ["main", "header", "footer", "footnote", "endnote"];
-declare const FOLIO_DOCUMENT_OPERATION_PRECONDITIONS: readonly ["blockTextHash"];
+export declare const FOLIO_PAGE_BREAK_CLEAR_VALUES: readonly ["none", "left", "right", "all"];
+export declare const FOLIO_DOCUMENT_OPERATION_TYPES: readonly ["replaceInBlock", "replaceRange", "commentOnRange", "formatRange", "insertAfterBlock", "insertBeforeBlock", "replaceBlock", "deleteBlock", "splitBlock", "mergeBlockWithNext", "setBlockParagraphProperties", "insertTable", "deleteTable", "commentOnBlock", "insertSignatureTable", "insertTableRow", "deleteTableRow", "insertTableColumn", "deleteTableColumn", "mergeTableCells", "splitTableCell"];
+export declare const FOLIO_DOCUMENT_OPERATION_MODES: readonly ["direct", "tracked-changes", "suggested"];
+export declare const FOLIO_DOCUMENT_OPERATION_STORIES: readonly ["main", "header", "footer", "footnote", "endnote"];
+export declare const FOLIO_DOCUMENT_OPERATION_PRECONDITIONS: readonly ["blockTextHash"];
 /**
  * Batch-level preconditions. `documentVersion` is an opaque host token (an
  * entity version id, a collaboration checkpoint) pinning the document the
@@ -22,13 +22,13 @@ declare const FOLIO_DOCUMENT_OPERATION_PRECONDITIONS: readonly ["blockTextHash"]
  * batch with `documentVersionMismatch` when it differs. The core apply path
  * preserves the token but has no version to compare it to.
  */
-declare const FOLIO_DOCUMENT_OPERATION_BATCH_PRECONDITIONS: readonly ["documentVersion"];
-declare const FOLIO_DOCUMENT_OPERATION_BATCH_MODES: readonly ["best-effort", "atomic"];
-type FolioDocumentOperation = FolioAIEditOperation;
-type FolioDocumentOperationMode = FolioAIEditApplyMode;
-type FolioDocumentOperationPrecondition = FolioAIEditPrecondition;
-type FolioDocumentOperationType = FolioDocumentOperation["type"];
-declare const FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE: Readonly<{
+export declare const FOLIO_DOCUMENT_OPERATION_BATCH_PRECONDITIONS: readonly ["documentVersion"];
+export declare const FOLIO_DOCUMENT_OPERATION_BATCH_MODES: readonly ["best-effort", "atomic"];
+export type FolioDocumentOperation = FolioAIEditOperation;
+export type FolioDocumentOperationMode = FolioAIEditApplyMode;
+export type FolioDocumentOperationPrecondition = FolioAIEditPrecondition;
+export type FolioDocumentOperationType = FolioDocumentOperation["type"];
+export declare const FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE: Readonly<{
   readonly replaceInBlock: readonly ["direct", "tracked-changes", "suggested"];
   readonly replaceRange: readonly ["direct", "tracked-changes", "suggested"];
   readonly commentOnRange: readonly ["direct", "tracked-changes"];
@@ -51,7 +51,7 @@ declare const FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE: Readonly<{
   readonly mergeTableCells: readonly ["direct", "tracked-changes"];
   readonly splitTableCell: readonly ["direct", "tracked-changes"];
 }>;
-type FolioDocumentOperationCapabilities = {
+export type FolioDocumentOperationCapabilities = {
   readonly version: typeof FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION;
   readonly operationTypes: typeof FOLIO_DOCUMENT_OPERATION_TYPES;
   readonly modes: typeof FOLIO_DOCUMENT_OPERATION_MODES;
@@ -62,26 +62,26 @@ type FolioDocumentOperationCapabilities = {
   readonly batchPreconditions: typeof FOLIO_DOCUMENT_OPERATION_BATCH_PRECONDITIONS;
   readonly stories: typeof FOLIO_DOCUMENT_OPERATION_STORIES;
 };
-declare const getFolioDocumentOperationCapabilities: () => FolioDocumentOperationCapabilities;
-declare const isFolioDocumentOperationModeSupported: (operationType: FolioDocumentOperationType, mode: FolioDocumentOperationMode) => boolean;
-declare const isSupportedFolioDocumentOperationVersion: (value: unknown) => value is typeof FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION;
+export declare const getFolioDocumentOperationCapabilities: () => FolioDocumentOperationCapabilities;
+export declare const isFolioDocumentOperationModeSupported: (operationType: FolioDocumentOperationType, mode: FolioDocumentOperationMode) => boolean;
+export declare const isSupportedFolioDocumentOperationVersion: (value: unknown) => value is typeof FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION;
 declare const UnsupportedFolioDocumentOperationVersionError_base: import("better-result").TaggedErrorClass<"UnsupportedFolioDocumentOperationVersionError">;
-declare class UnsupportedFolioDocumentOperationVersionError extends UnsupportedFolioDocumentOperationVersionError_base<{
+export declare class UnsupportedFolioDocumentOperationVersionError extends UnsupportedFolioDocumentOperationVersionError_base<{
   message: string;
   receivedVersion: unknown;
 }> {}
 declare const InvalidFolioDocumentOperationBatchError_base: import("better-result").TaggedErrorClass<"InvalidFolioDocumentOperationBatchError">;
-declare class InvalidFolioDocumentOperationBatchError extends InvalidFolioDocumentOperationBatchError_base<{
+export declare class InvalidFolioDocumentOperationBatchError extends InvalidFolioDocumentOperationBatchError_base<{
   message: string;
   path: string;
   reason: string;
 }> {}
-declare const assertSupportedFolioDocumentOperationVersion: (value: unknown) => typeof FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION;
+export declare const assertSupportedFolioDocumentOperationVersion: (value: unknown) => typeof FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION;
 /** Batch-level guard; see {@link FOLIO_DOCUMENT_OPERATION_BATCH_PRECONDITIONS}. */
-type FolioDocumentOperationBatchPrecondition = {
+export type FolioDocumentOperationBatchPrecondition = {
   readonly documentVersion: string;
 };
-type FolioDocumentOperationBatch = {
+export type FolioDocumentOperationBatch = {
   readonly version: typeof FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION;
   readonly operations: readonly FolioDocumentOperation[];
   readonly mode?: FolioDocumentOperationMode;
@@ -95,7 +95,7 @@ type FolioDocumentOperationBatch = {
  * decoder) can strip stray keys with the same knowledge instead of
  * guessing, and so tool schemas can be derived from the contract.
  */
-declare const FOLIO_DOCUMENT_OPERATION_KEYS_BY_TYPE: Readonly<{
+export declare const FOLIO_DOCUMENT_OPERATION_KEYS_BY_TYPE: Readonly<{
   readonly replaceInBlock: readonly string[];
   readonly replaceRange: readonly string[];
   readonly commentOnRange: readonly string[];
@@ -118,14 +118,14 @@ declare const FOLIO_DOCUMENT_OPERATION_KEYS_BY_TYPE: Readonly<{
   readonly mergeTableCells: readonly string[];
   readonly splitTableCell: readonly string[];
 }>;
-declare const parseFolioDocumentOperationBatch: (value: unknown) => FolioDocumentOperationBatch;
+export declare const parseFolioDocumentOperationBatch: (value: unknown) => FolioDocumentOperationBatch;
 /**
  * `queued` is reported by a surface that routes the batch into a host-owned
  * review queue instead of applying it; the core apply path never produces it.
  */
-type FolioDocumentOperationStatus = "committed" | "previewed" | "rejected" | "queued";
-type FolioDocumentOperationRecovery = "refreshDocument" | "narrowMatch" | "changeMode" | "changeTarget" | "removeOperation" | "inspectBatch" | "resolveTrackedChange" | "retryLater";
-type FolioDocumentOperationIssue = {
+export type FolioDocumentOperationStatus = "committed" | "previewed" | "rejected" | "queued";
+export type FolioDocumentOperationRecovery = "refreshDocument" | "narrowMatch" | "changeMode" | "changeTarget" | "removeOperation" | "inspectBatch" | "resolveTrackedChange" | "retryLater";
+export type FolioDocumentOperationIssue = {
   operationId: string;
   operationIndex: number;
   path: `$.operations[${number}]`;
@@ -136,7 +136,7 @@ type FolioDocumentOperationIssue = {
   /** The skip's detail, when it has one; see {@link FolioAIEditSkippedOperation.message}. */
   message?: string;
 };
-type FolioDocumentOperationStory = "main" | {
+export type FolioDocumentOperationStory = "main" | {
   type: "header";
   relationshipId: string;
 } | {
@@ -150,7 +150,7 @@ type FolioDocumentOperationStory = "main" | {
   noteId: number;
 };
 /** One typed target affected by a successfully applied document operation. */
-type FolioDocumentOperationAffectedTarget = {
+export type FolioDocumentOperationAffectedTarget = {
   type: "block";
   story: FolioDocumentOperationStory;
   blockId: string;
@@ -197,18 +197,18 @@ type FolioDocumentOperationAffectedTarget = {
   effect: "split";
 };
 /** Input-ordered effect receipt for one successfully applied operation. */
-type FolioDocumentOperationReceipt = {
+export type FolioDocumentOperationReceipt = {
   operationId: string;
   operationIndex: number;
   affected: FolioDocumentOperationAffectedTarget[];
 };
 /** Opaque handle for undoing one committed document-operation batch. */
-type FolioDocumentOperationUndoHandle = {
+export type FolioDocumentOperationUndoHandle = {
   type: "documentOperationUndo";
   id: string;
 };
-type FolioDocumentOperationUndoFailureReason = "unknownHandle" | "notLatest" | "documentChanged";
-type FolioDocumentOperationUndoResult = {
+export type FolioDocumentOperationUndoFailureReason = "unknownHandle" | "notLatest" | "documentChanged";
+export type FolioDocumentOperationUndoResult = {
   status: "undone";
   undoHandle: FolioDocumentOperationUndoHandle;
 } | {
@@ -217,7 +217,7 @@ type FolioDocumentOperationUndoResult = {
   reason: FolioDocumentOperationUndoFailureReason;
 };
 /** One operation a host surface accepted into its own review queue rather than applying. */
-type FolioDocumentOperationQueuedOperation = {
+export type FolioDocumentOperationQueuedOperation = {
   id: string;
 };
 /**
@@ -225,7 +225,7 @@ type FolioDocumentOperationQueuedOperation = {
  * so the public API report shows these fields rather than a name it cannot
  * resolve.
  */
-type FolioDocumentOperationResultBase = {
+export type FolioDocumentOperationResultBase = {
   version: typeof FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION;
   applied: FolioAIEditAppliedOperation[];
   skipped: FolioAIEditSkippedOperation[];
@@ -254,7 +254,7 @@ type FolioDocumentOperationResultBase = {
  * `"queued"`, and only that branch carries the `queued` list, so a consumer
  * narrowing on the status can never meet a contradictory payload.
  */
-type FolioDocumentOperationResult = (FolioDocumentOperationResultBase & {
+export type FolioDocumentOperationResult = (FolioDocumentOperationResultBase & {
   status: "queued";
   /** Operations parked in the host review queue instead of applied. */
   queued: FolioDocumentOperationQueuedOperation[];
@@ -262,16 +262,16 @@ type FolioDocumentOperationResult = (FolioDocumentOperationResultBase & {
   status: Exclude<FolioDocumentOperationStatus, "queued">;
   queued?: never;
 });
-declare const getFolioDocumentOperationIssues: (operations: readonly FolioDocumentOperation[], skipped: readonly FolioAIEditSkippedOperation[]) => FolioDocumentOperationIssue[];
+export declare const getFolioDocumentOperationIssues: (operations: readonly FolioDocumentOperation[], skipped: readonly FolioAIEditSkippedOperation[]) => FolioDocumentOperationIssue[];
 /** Build deterministic affected-target receipts from operations and their applied entries. */
-declare const getFolioDocumentOperationReceipts: (operations: readonly FolioDocumentOperation[], applied: readonly FolioAIEditAppliedOperation[]) => FolioDocumentOperationReceipt[];
+export declare const getFolioDocumentOperationReceipts: (operations: readonly FolioDocumentOperation[], applied: readonly FolioAIEditAppliedOperation[]) => FolioDocumentOperationReceipt[];
 type GetFolioDocumentOperationReceiptsForStoryOptions = {
   operations: readonly FolioDocumentOperation[];
   applied: readonly FolioAIEditAppliedOperation[];
   story: FolioDocumentOperationStory;
 };
-declare const getFolioDocumentOperationReceiptsForStory: ({ operations, applied, story }: GetFolioDocumentOperationReceiptsForStoryOptions) => FolioDocumentOperationReceipt[];
-type ApplyFolioDocumentOperationsOptions = {
+export declare const getFolioDocumentOperationReceiptsForStory: ({ operations, applied, story }: GetFolioDocumentOperationReceiptsForStoryOptions) => FolioDocumentOperationReceipt[];
+export type ApplyFolioDocumentOperationsOptions = {
   view: FolioAIEditView;
   snapshot: FolioAIEditSnapshot;
   batch: FolioDocumentOperationBatch;
@@ -300,7 +300,19 @@ type ApplyFolioDocumentOperationsOptions = {
   replacementBackground?: FolioReplacementBackground;
   /** Required policy for undefined style and numbering references. */
   undefinedReferences: FolioUndefinedReferencePolicy;
+  /**
+   * Suggestion ids pending in the document's other stories. A suggested
+   * operation without a `suggestionId` whose id names a pending suggestion
+   * (in this story or one of these) gets a distinct suggestion id, reported
+   * in its receipt, so it never folds into that earlier suggestion.
+   */
+  pendingSuggestionIds?: ReadonlySet<string>;
+  /**
+   * Keep every operation's suggestion id as given: the batch restages
+   * suggestions that already carry their ids.
+   */
+  restagesSuggestions?: boolean;
 };
-declare const applyFolioDocumentOperations: ({ view, snapshot, batch, story, author, createCommentId, createUndoHandle, revisionStamp, wordDiff, tableTemplates, replacementBackground, undefinedReferences }: ApplyFolioDocumentOperationsOptions) => FolioDocumentOperationResult;
+export declare const applyFolioDocumentOperations: ({ view, snapshot, batch, story, author, createCommentId, createUndoHandle, revisionStamp, wordDiff, tableTemplates, replacementBackground, undefinedReferences, pendingSuggestionIds, restagesSuggestions }: ApplyFolioDocumentOperationsOptions) => FolioDocumentOperationResult;
 //#endregion
-export { ApplyFolioDocumentOperationsOptions, FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_BATCH_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_KEYS_BY_TYPE, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, FOLIO_LINE_SPACING_RULE_VALUES, FOLIO_PAGE_BREAK_CLEAR_VALUES, FOLIO_PARAGRAPH_ALIGNMENT_VALUES, FolioDocumentOperation, FolioDocumentOperationAffectedTarget, FolioDocumentOperationBatch, FolioDocumentOperationBatchPrecondition, FolioDocumentOperationCapabilities, FolioDocumentOperationIssue, FolioDocumentOperationMode, FolioDocumentOperationPrecondition, FolioDocumentOperationQueuedOperation, FolioDocumentOperationReceipt, FolioDocumentOperationRecovery, FolioDocumentOperationResult, FolioDocumentOperationResultBase, FolioDocumentOperationStatus, FolioDocumentOperationStory, FolioDocumentOperationType, FolioDocumentOperationUndoFailureReason, FolioDocumentOperationUndoHandle, FolioDocumentOperationUndoResult, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioDocumentOperationReceiptsForStory, isFolioDocumentOperationModeSupported, isSupportedFolioDocumentOperationVersion, parseFolioDocumentOperationBatch };
+export {};

package/dist/document-operations.js

@@ -1,6 +1,7 @@
 import { applyFolioAIEditOperations, previewFolioAIEditOperationsWithResult } from "./ai-edits/apply.js";
 import { describeModelError, findIntroducedModelErrors } from "./ai-edits/result-validation.js";
 import { LIST_KINDS } from "./docx/listNumberingInstances.js";
+import { getSuggestions } from "./prosemirror/commands/comments.js";
 import { completeNumberingForDoc } from "./prosemirror/listInstanceReferences.js";
 import { outlineLevelFromAttrValue } from "./prosemirror/outlineLevelAttr.js";
 import { getStatedDocumentNumbering } from "./prosemirror/plugins/documentNumbering.js";
@@ -1248,14 +1249,48 @@ const getFolioDocumentOperationReceiptsForStory = ({ operations, applied, story
 	});
 	return receipts;
 };
+/**
+* A suggested operation without a `suggestionId` is its own suggestion, named
+* by its id. An id a still pending suggestion already carries would fold the
+* two into one (accepted, rejected and exported together), so such an
+* operation gets a distinct id, and an operation of the batch grouping with it
+* by that id follows it.
+*/
+const withDistinctSuggestionIds = (batch, pending) => {
+	if (batch.mode !== "suggested" || pending.size === 0) return batch;
+	const taken = new Set(pending);
+	for (const operation of batch.operations) if ("suggestionId" in operation && operation.suggestionId !== void 0) taken.add(operation.suggestionId);
+	const renamed = /* @__PURE__ */ new Map();
+	for (const operation of batch.operations) {
+		if (operation.type === "commentOnRange" || "suggestionId" in operation && operation.suggestionId !== void 0 || !pending.has(operation.id)) continue;
+		let ordinal = 2;
+		while (taken.has(`${operation.id}#${String(ordinal)}`)) ordinal += 1;
+		const suggestionId = `${operation.id}#${String(ordinal)}`;
+		taken.add(suggestionId);
+		renamed.set(operation.id, suggestionId);
+	}
+	if (renamed.size === 0) return batch;
+	return {
+		...batch,
+		operations: batch.operations.map((operation) => {
+			if (operation.type === "commentOnRange") return operation;
+			const grouped = "suggestionId" in operation && operation.suggestionId !== void 0 ? renamed.get(operation.suggestionId) : renamed.get(operation.id);
+			return grouped === void 0 ? operation : {
+				...operation,
+				suggestionId: grouped
+			};
+		})
+	};
+};
 const NO_COMMIT = () => {};
 /** Skips reported in the order of the operations they belong to. */
 const inOperationOrder = (operations, skipped) => {
 	const indexById = new Map(operations.map(({ id }, index) => [id, index]));
 	return [...skipped].sort((left, right) => (indexById.get(left.id) ?? -1) - (indexById.get(right.id) ?? -1));
 };
-const applyFolioDocumentOperations = ({ view, snapshot, batch, story = "main", author, createCommentId, createUndoHandle, revisionStamp, wordDiff, tableTemplates, replacementBackground, undefinedReferences }) => {
-	const parsedBatch = parseFolioDocumentOperationBatch(batch);
+const applyFolioDocumentOperations = ({ view, snapshot, batch, story = "main", author, createCommentId, createUndoHandle, revisionStamp, wordDiff, tableTemplates, replacementBackground, undefinedReferences, pendingSuggestionIds, restagesSuggestions }) => {
+	const validatedBatch = parseFolioDocumentOperationBatch(batch);
+	const parsedBatch = restagesSuggestions === true ? validatedBatch : withDistinctSuggestionIds(validatedBatch, /* @__PURE__ */ new Set([...getSuggestions(view.state).map(({ suggestionId }) => suggestionId), ...pendingSuggestionIds ?? []]));
 	const isAtomic = parsedBatch.atomic === true;
 	const beforeDoc = view.state.doc;
 	const packageNumbering = getStatedDocumentNumbering(view.state);

package/dist/document-stories.d.ts

@@ -1,6 +1,6 @@
 import { FolioDocumentStoryHandle } from "./ai-edits/headless.js";
 //#region src/document-stories.d.ts
-type FolioDocumentStoryPair = {
+export type FolioDocumentStoryPair = {
   baseStory: FolioDocumentStoryHandle | null;
   revisedStory: FolioDocumentStoryHandle | null;
 };
@@ -20,6 +20,5 @@ type FolioDocumentStoryPair = {
  * other, and a document with more of them than the other leaves its surplus
  * unpaired rather than pairing a first-page header against a default one.
  */
-declare const pairFolioDocumentStories: (baseStories: readonly FolioDocumentStoryHandle[], revisedStories: readonly FolioDocumentStoryHandle[]) => FolioDocumentStoryPair[];
-//#endregion
-export { FolioDocumentStoryPair, pairFolioDocumentStories };
+export declare const pairFolioDocumentStories: (baseStories: readonly FolioDocumentStoryHandle[], revisedStories: readonly FolioDocumentStoryHandle[]) => FolioDocumentStoryPair[];
+//#endregion

package/dist/docx/altChunk.d.ts

@@ -1,8 +1,7 @@
 //#region src/docx/altChunk.d.ts
-declare const ALT_CHUNK_READER_DIAGNOSTIC = "[Unsupported w:altChunk content]";
-declare const ALT_CHUNK_PLAIN_TEXT_LIMIT_BYTES = 1000000;
+export declare const ALT_CHUNK_READER_DIAGNOSTIC = "[Unsupported w:altChunk content]";
+export declare const ALT_CHUNK_PLAIN_TEXT_LIMIT_BYTES = 1000000;
 /** The captured fragment's expanded name, not its source prefix, identifies w:altChunk. */
-declare const isAltChunkMarkup: (xml: string) => boolean;
-declare const getAltChunkRelationshipId: (xml: string) => string | undefined;
-//#endregion
-export { ALT_CHUNK_PLAIN_TEXT_LIMIT_BYTES, ALT_CHUNK_READER_DIAGNOSTIC, getAltChunkRelationshipId, isAltChunkMarkup };
+export declare const isAltChunkMarkup: (xml: string) => boolean;
+export declare const getAltChunkRelationshipId: (xml: string) => string | undefined;
+//#endregion

package/dist/docx/appVersionNormalization.d.ts

@@ -7,7 +7,7 @@ declare const AppVersionSchemaError_base: import("better-result").TaggedErrorCla
  * throws this rather than letting the package go out carrying a version a
  * consumer refuses.
  */
-declare class AppVersionSchemaError extends AppVersionSchemaError_base<{
+export declare class AppVersionSchemaError extends AppVersionSchemaError_base<{
   message: string;
   appVersion: string;
 }> {}
@@ -18,7 +18,7 @@ declare class AppVersionSchemaError extends AppVersionSchemaError_base<{
  * clock, not folio's own version — so two saves of one document state the same
  * application version.
  */
-declare const appVersionInSchemaForm: (value: string) => string;
+export declare const appVersionInSchemaForm: (value: string) => string;
 /**
  * Rewrite the application version an extended-properties part states.
  *
@@ -26,6 +26,6 @@ declare const appVersionInSchemaForm: (value: string) => string;
  * states no version at all, so a save of a document that never carried a
  * malformed one is byte-identical.
  */
-declare const normalizeAppVersionInExtendedProperties: (xml: string) => string;
+export declare const normalizeAppVersionInExtendedProperties: (xml: string) => string;
 //#endregion
-export { AppVersionSchemaError, appVersionInSchemaForm, normalizeAppVersionInExtendedProperties };
+export {};