superdoc 2.27.0-next.1 → 2.27.0-next.11

package/dist/document-api/src/index.d.ts

@@ -64,7 +64,7 @@ import { CaptionsApi, CaptionsAdapter } from './captions/captions.js';
 import { FieldsApi, FieldsAdapter } from './fields/fields.js';
 import { CitationsApi, CitationsAdapter } from './citations/citations.js';
 import { AuthoritiesApi, AuthoritiesAdapter } from './authorities/authorities.js';
-export type { TemporaryMutationInput, TemporaryMutationHandleInput, TemporaryMutationCommitInput, TemporaryMutationReplaceInput, TemporaryMutationReceipt, TemporaryMutationMetadata, TemporaryMutationOperation, } from './types/temporary-mutation.js';
+export type { TemporaryMutationInput, TemporaryMutationHandleInput, TemporaryMutationCommitInput, TemporaryMutationReplaceInput, TemporaryMutationReceipt, TemporaryMutationMetadata, TemporaryMutationOperation, TemporaryOperationResultTarget, } from './types/temporary-mutation.js';
 export * from './types/index.js';
 export * from './contract/index.js';
 export * from './capabilities/capabilities.js';
@@ -116,10 +116,10 @@ export type { FormatReadSelectionAdapter, FormatReadSelectionInput, FormatReadSe
 export type { InlineRunPatch, InlineRunPatchKey, InlinePropertyStorage, InlinePropertyType, InlinePropertyCarrier, InlinePropertyRegistryEntry, UnderlinePatch, ShadingPatch, BorderPatch, FitTextPatch, LangPatch, RFontsPatch, EastAsianLayoutPatch, StylisticSetPatch, } from './format/inline-run-patch.js';
 export { CLEAR_INLINE_FORMATTING_KEYS, INLINE_PROPERTY_REGISTRY, INLINE_PROPERTY_KEY_SET, INLINE_PROPERTY_BY_KEY, INLINE_PROPERTY_KEYS_BY_STORAGE, validateInlineRunPatch, buildInlineRunPatchSchema, } from './format/inline-run-patch.js';
 export { PROPERTY_REGISTRY, EXCLUDED_KEYS, ALLOWED_KEYS_BY_CHANNEL, getPropertyDefinition, toJsonSchema, buildPatchSchema, buildStateSchema, } from './styles/index.js';
-export type { ValueSchema, MergeStrategy, PropertyDefinition, StylesAdapter, StylesApplyInput, StylesApplyRunInput, StylesApplyParagraphInput, StylesApplyOptions, StylesApplyReceipt, StylesBooleanState, StylesNumberState, StylesEnumState, StylesObjectState, StylesArrayState, StylesStateMap, StylesChannel, StylesRunPatch, StylesParagraphPatch, StylesTargetResolution, StylesApplyReceiptSuccess, StylesApplyReceiptFailure, NormalizedStylesApplyOptions, StyleCatalogView, StyleCatalogItemType, StyleCatalogFilterType, StyleProvenance, StyleCatalogDiagnosticSeverity, StyleSourcePartStatus, StyleCatalogUsageStatus, StyleCatalogPreviewStatus, StyleCatalogViewStatus, StyleCatalogItemVisibility, StyleCatalogItemUsage, StyleCatalogItemPreview, StyleCatalogPreviewFontSource, StyleCatalogPreviewColorSource, StyleCatalogPreviewSources, StyleCatalogItem, StyleCatalogDefaults, StyleCatalogDiagnostic, StyleCatalogSourceStatus, StylesGetCatalogInput, StylesGetCatalogResult, StylesGetCatalogAdapter, StylesGetThemeInput, StylesThemeSourceStatus, StylesGetThemeResult, StylesGetThemeAdapter, } from './styles/index.js';
+export type { ValueSchema, MergeStrategy, PropertyDefinition, StylesAdapter, StylesApplyInput, StylesApplyRunInput, StylesApplyParagraphInput, StylesApplyStyleRunInput, StylesStyleRunPatch, StylesDocDefaultsResolution, StylesStyleResolution, StylesApplyOptions, StylesApplyReceipt, StylesBooleanState, StylesNumberState, StylesEnumState, StylesObjectState, StylesArrayState, StylesStateMap, StylesChannel, StylesRunPatch, StylesParagraphPatch, StylesTargetResolution, StylesApplyReceiptSuccess, StylesApplyReceiptFailure, NormalizedStylesApplyOptions, StyleCatalogView, StyleCatalogItemType, StyleCatalogFilterType, StyleProvenance, StyleCatalogDiagnosticSeverity, StyleSourcePartStatus, StyleCatalogUsageStatus, StyleCatalogPreviewStatus, StyleCatalogViewStatus, StyleCatalogItemVisibility, StyleCatalogItemUsage, StyleCatalogItemPreview, StyleCatalogPreviewFontSource, StyleCatalogPreviewColorSource, StyleCatalogPreviewSources, StyleCatalogItem, StyleCatalogDefaults, StyleCatalogDiagnostic, StyleCatalogSourceStatus, StylesGetCatalogInput, StylesGetCatalogResult, StylesGetCatalogAdapter, StylesGetThemeInput, StylesThemeSourceStatus, StylesGetThemeResult, StylesGetThemeAdapter, } from './styles/index.js';
 export { STYLE_CATALOG_VIEWS, STYLE_CATALOG_FILTER_TYPES, executeStylesGetCatalog, validateStylesGetCatalogInput, executeStylesGetTheme, validateStylesGetThemeInput, } from './styles/index.js';
 export type { StylesScope, StyleRunPatch, StyleConflictPolicy, StyleChannelState, StylesCreateAdapter, StylesCreateApi, StylesCreateInput, StylesCreateParagraphInput, StylesCreateCharacterInput, StylesCreateOptions, NormalizedStylesCreateOptions, StylesCreateResolution, StylesCreateReceipt, StylesCreateReceiptSuccess, StylesCreateReceiptFailure, } from './styles/index.js';
-export { STYLE_EXCLUDED_KEYS, EXCLUDED_KEYS_BY_SCOPE, SCOPE_LABEL, STYLE_XML_PATH, executeStylesCreate, validateStylesCreateInput, validateStylesCreateOptions, validatePatchObject, } from './styles/index.js';
+export { STYLE_EXCLUDED_KEYS, EXCLUDED_KEYS_BY_SCOPE, SCOPE_LABEL, STYLE_XML_PATH, STYLE_RUN_XML_PATH, validateStylesApplyInput, executeStylesCreate, validateStylesCreateInput, validateStylesCreateOptions, validatePatchObject, } from './styles/index.js';
 export type { TemplatesAdapter, TemplatesApi, TemplatesApplyInput, TemplatesApplyOptions, TemplatesApplySource, TemplatesApplySourcePath, TemplatesApplySourceBase64, TemplateBodyPolicy, TemplateScope, NormalizedTemplatesApplyOptions, TemplateScopeReport, TemplateSkipReason, TemplateScopeSkip, TemplateUnsupportedItem, TemplateChangeKind, TemplateChangedPart, TemplateIdMapping, TemplateApplyWarning, TemplatesApplySourceInfo, TemplatesApplyReceiptSuccess, TemplatesApplyFailureCode, TemplatesApplyReceiptFailure, TemplatesApplyReceipt, } from './templates/index.js';
 export { executeTemplatesApply } from './templates/index.js';
 export type { CreateAdapter, CreateApi } from './create/create.js';
@@ -169,7 +169,7 @@ export type { ParagraphsAdapter, ParagraphFormatApi, ParagraphStylesApi } from '
 export type { ParagraphTarget, ParagraphBlockType, ParagraphMutationResult, ParagraphMutationSuccess, ParagraphMutationFailure, MutationResolution, ParagraphAlignment, TabStopAlignment, TabStopLeader, BorderSide, ClearBorderSide, LineRule, ParagraphsSetStyleInput, ParagraphSemanticStyleRole, ParagraphsSetStyleRefInput, ParagraphsClearStyleInput, ParagraphsResetDirectFormattingInput, ParagraphsSetAlignmentInput, ParagraphsClearAlignmentInput, ParagraphsSetIndentationInput, ParagraphsClearIndentationInput, ParagraphsSetSpacingInput, ParagraphsClearSpacingInput, ParagraphsSetKeepOptionsInput, ParagraphsSetOutlineLevelInput, ParagraphsSetFlowOptionsInput, ParagraphsSetTabStopInput, ParagraphsClearTabStopInput, ParagraphsClearAllTabStopsInput, ParagraphsSetBorderInput, ParagraphsClearBorderInput, ParagraphsSetShadingInput, ParagraphsClearShadingInput, ParagraphsSetMarkRunPropsInput, ParagraphsSetDirectionInput, ParagraphsClearDirectionInput, ParagraphsSetNumberingInput, ParagraphDirection, AlignmentPolicy, } from './paragraphs/paragraphs.js';
 export { PARAGRAPH_ALIGNMENTS, TAB_STOP_ALIGNMENTS, TAB_STOP_LEADERS, BORDER_SIDES, CLEAR_BORDER_SIDES, LINE_RULES, PARAGRAPH_DIRECTIONS, ALIGNMENT_POLICIES, } from './paragraphs/paragraphs.js';
 export type { BlockAddress, BlockRange, CanContinueReason, CanJoinReason, JoinDirection, ListInsertInput, ListItemAddress, ListItemInfo, ListKind, ListsAttachInput, ListsCanContinuePreviousInput, ListsCanContinuePreviousResult, ListsCanJoinInput, ListsCanJoinResult, ListsConvertToTextInput, ListsConvertToTextResult, ListsContinuePreviousInput, ListsCreateInput, ListsCreateResult, ListsDetachInput, ListsDetachResult, ListsDeleteInput, ListsDeleteResult, ListsFailureCode, ListsGetInput, ListsInsertResult, ListsJoinInput, ListsJoinResult, ListsListQuery, ListsListResult, ListsMutateItemResult, ListsSeparateInput, ListsSeparateResult, ListsMergeInput, ListsMergeResult, ListsSplitInput, ListsSplitResult, ListsSetLevelInput, ListsSetLevelRestartInput, ListsSetValueInput, ListTargetInput, MutationScope, LevelAlignment, TrailingCharacter, ListPresetId, ListPresetMarker, ListLevelTemplate, ListTemplate, ListsApplyTemplateInput, ListsApplyPresetInput, ListsCaptureTemplateInput, ListsCaptureTemplateResult, ListsCaptureTemplateSuccessResult, ListsSetLevelNumberingInput, ListsSetLevelBulletInput, ListsSetLevelPictureBulletInput, ListsSetLevelAlignmentInput, ListsSetLevelIndentsInput, ListsSetLevelTrailingCharacterInput, ListsSetLevelMarkerFontInput, ListsClearLevelOverridesInput, ListsSetTypeInput, ListStyle, ListLevelStyle, ListLevelLayout, ListsGetStyleInput, ListsGetStyleResult, ListsGetStyleSuccessResult, ListsApplyStyleInput, ListsRestartAtInput, ListsSetLevelNumberStyleInput, ListsSetLevelTextInput, ListsSetLevelStartInput, ListsSetLevelLayoutInput, ListsGetStateInput, ListsGetStateResult, ListsApplyInput, ListsContinueV2Input, ListsRestartV2Input, ListsRemoveV2Input, } from './lists/lists.types.js';
-export { LIST_KINDS, LIST_INSERT_POSITIONS, JOIN_DIRECTIONS, MUTATION_SCOPES, LEVEL_ALIGNMENTS, TRAILING_CHARACTERS, LIST_PRESET_IDS, LIST_PRESET_MARKERS, } from './lists/lists.types.js';
+export { LIST_KINDS, LIST_INSERT_POSITIONS, JOIN_DIRECTIONS, MUTATION_SCOPES, LEVEL_ALIGNMENTS, TRAILING_CHARACTERS, LIST_PRESET_IDS, LIST_PRESET_MARKERS, LIST_CUSTOM_NUMBERING_FORMATS, } from './lists/lists.types.js';
 export type { CreateSectionBreakInput, CreateSectionBreakResult, DocumentMutationResult, SectionAddress, SectionBorderSpec, SectionBreakCreateLocation, SectionBreakRepresentation, SectionBreakType, SectionColumns, SectionDirection, SectionDomain, SectionHeaderFooterKind, SectionHeaderFooterMargins, SectionHeaderFooterRefs, SectionHeaderFooterVariant, SectionInfo, SectionLineNumbering, SectionLineNumberRestart, SectionMutationResult, SectionOrientation, SectionPageBorders, SectionPageMargins, SectionPageNumbering, SectionPageNumberingChapterSeparator, SectionPageNumberingFormat, SectionPageSetup, SectionRangeDomain, SectionTargetInput, SectionVerticalAlign, SectionsClearHeaderFooterRefInput, SectionsClearPageBordersInput, SectionsGetInput, SectionsListQuery, SectionsListResult, SectionsSetBreakTypeInput, SectionsSetColumnsInput, SectionsSetHeaderFooterMarginsInput, SectionsSetHeaderFooterRefInput, SectionsSetLineNumberingInput, SectionsSetLinkToPreviousInput, SectionsSetOddEvenHeadersFootersInput, SectionsSetPageBordersInput, SectionsSetPageMarginsInput, SectionsSetPageNumberingInput, SectionsSetPageSetupInput, SectionsSetSectionDirectionInput, SectionsSetTitlePageInput, SectionsSetVerticalAlignInput, } from './sections/sections.types.js';
 export type { CommentsCreateReceipt, CommentsCreateInput, CommentCreateAttributionInput, CommentsPatchInput, CommentsDeleteInput, CommentsAdapter, CommentsApi, GetCommentInput, TrackedChangeCommentTarget, TrackedChangeCommentTargetSide, TextSearchCommentTarget, AddCommentInput, EditCommentInput, ReplyToCommentInput, MoveCommentInput, ResolveCommentInput, ReopenCommentInput, RemoveCommentInput, SetCommentInternalInput, GoToCommentInput, SetCommentActiveInput, } from './comments/comments.js';
 export { executeCommentsCreate, executeCommentsPatch, executeCommentsDelete, executeGetComment, executeListComments, } from './comments/comments.js';

package/dist/document-api/src/lists/lists.types.d.ts

@@ -206,10 +206,12 @@ export interface ListsConvertToTextInput {
     target: ListItemAddress;
     includeMarker?: boolean;
 }
+export declare const LIST_CUSTOM_NUMBERING_FORMATS: readonly ["01, 02, 03, ...", "001, 002, 003, ...", "0001, 0002, 0003, ..."];
 /** A captured snapshot of one level's formatting properties. */
 export interface ListLevelTemplate {
     level: number;
     numFmt?: string;
+    customFormat?: string;
     lvlText?: string;
     start?: number;
     alignment?: LevelAlignment;
@@ -274,6 +276,7 @@ export interface ListsSetLevelNumberingInput {
     target: ListItemAddress;
     level: number;
     numFmt: string;
+    customFormat?: string;
     lvlText: string;
     start?: number;
     /** Format numeric placeholders as decimal. False removes legal numbering; omit to preserve it. */

package/dist/document-api/src/styles/apply.d.ts

@@ -1,6 +1,7 @@
 import { ReceiptFailure } from '../types/receipt.js';
 import { StylesChannel } from './registry.js';
 import { StylesGetCatalogInput, StylesGetCatalogResult } from './catalog.js';
+import { StyleRunPatch } from './create.js';
 import { StylesGetThemeInput, StylesGetThemeResult } from './theme.js';
 /** Tri-state for OOXML boolean style properties. */
 export type StylesBooleanState = 'on' | 'off' | 'inherit';
@@ -78,12 +79,22 @@ export interface StylesParagraphPatch {
     borders?: Record<string, unknown>;
     tabStops?: unknown[];
 }
-export interface StylesTargetResolution {
+export interface StylesDocDefaultsResolution {
     scope: 'docDefaults';
     channel: StylesChannel;
     xmlPart: string;
     xmlPath: string;
 }
+export interface StylesStyleResolution {
+    scope: 'style';
+    styleId: string;
+    channel: 'run';
+    xmlPart: string;
+    xmlPath: typeof STYLE_RUN_XML_PATH;
+    linkedStyleId?: string;
+}
+export type StylesTargetResolution = StylesDocDefaultsResolution | StylesStyleResolution;
+export declare const STYLE_RUN_XML_PATH = "w:styles/w:style/w:rPr";
 export interface StylesApplyRunInput {
     target: {
         scope: 'docDefaults';
@@ -98,7 +109,18 @@ export interface StylesApplyParagraphInput {
     };
     patch: StylesParagraphPatch;
 }
-export type StylesApplyInput = StylesApplyRunInput | StylesApplyParagraphInput;
+export type StylesStyleRunPatch = {
+    [K in keyof StyleRunPatch]?: StyleRunPatch[K] | null;
+};
+export interface StylesApplyStyleRunInput {
+    target: {
+        scope: 'style';
+        styleId: string;
+        channel: 'run';
+    };
+    patch: StylesStyleRunPatch;
+}
+export type StylesApplyInput = StylesApplyRunInput | StylesApplyParagraphInput | StylesApplyStyleRunInput;
 export interface StylesApplyOptions {
     dryRun?: boolean;
     expectedRevision?: string;
@@ -121,6 +143,7 @@ export type StylesApplyReceipt = StylesApplyReceiptSuccess | StylesApplyReceiptF
 export interface StylesAdapter {
     apply(input: StylesApplyRunInput, options: NormalizedStylesApplyOptions): StylesApplyReceipt;
     apply(input: StylesApplyParagraphInput, options: NormalizedStylesApplyOptions): StylesApplyReceipt;
+    apply(input: StylesApplyStyleRunInput, options: NormalizedStylesApplyOptions): StylesApplyReceipt;
     apply(input: StylesApplyInput, options: NormalizedStylesApplyOptions): StylesApplyReceipt;
     /** Read the normalized style catalogue. See `styles/catalog.ts`. */
     getCatalog?(input?: StylesGetCatalogInput): StylesGetCatalogResult;
@@ -134,6 +157,7 @@ export interface NormalizedStylesApplyOptions {
 export interface StylesApi {
     apply(input: StylesApplyRunInput, options?: StylesApplyOptions): StylesApplyReceipt;
     apply(input: StylesApplyParagraphInput, options?: StylesApplyOptions): StylesApplyReceipt;
+    apply(input: StylesApplyStyleRunInput, options?: StylesApplyOptions): StylesApplyReceipt;
     apply(input: StylesApplyInput, options?: StylesApplyOptions): StylesApplyReceipt;
     /** Read the normalized style catalogue for discovery and quick-gallery UI. */
     getCatalog(input?: StylesGetCatalogInput): StylesGetCatalogResult;

package/dist/document-api/src/styles/index.d.ts

@@ -6,8 +6,8 @@
 export type { ValueSchema, StylesChannel, StylesScope, MergeStrategy, PropertyDefinition } from './registry.js';
 export { PROPERTY_REGISTRY, ALLOWED_KEYS_BY_CHANNEL, EXCLUDED_KEYS, STYLE_EXCLUDED_KEYS, EXCLUDED_KEYS_BY_SCOPE, SCOPE_LABEL, XML_PATH_BY_CHANNEL, getPropertyDefinition, ST_VERTICAL_ALIGN_RUN, ST_EM, ST_TEXT_ALIGNMENT, ST_TEXT_DIRECTION, ST_TEXTBOX_TIGHT_WRAP, ST_TEXT_TRANSFORM, ST_JUSTIFICATION, } from './registry.js';
 export { toJsonSchema, buildPatchSchema, buildStateSchema } from './schema.js';
-export type { StylesBooleanState, StylesNumberState, StylesEnumState, StylesObjectState, StylesArrayState, StylesRunPatch, StylesParagraphPatch, StylesTargetResolution, StylesApplyRunInput, StylesApplyParagraphInput, StylesApplyInput, StylesApplyOptions, StylesStateMap, StylesApplyReceiptSuccess, StylesApplyReceiptFailure, StylesApplyReceipt, StylesAdapter, NormalizedStylesApplyOptions, StylesApi, } from './apply.js';
-export { executeStylesApply } from './apply.js';
+export type { StylesBooleanState, StylesNumberState, StylesEnumState, StylesObjectState, StylesArrayState, StylesRunPatch, StylesParagraphPatch, StylesTargetResolution, StylesApplyRunInput, StylesApplyParagraphInput, StylesApplyStyleRunInput, StylesStyleRunPatch, StylesDocDefaultsResolution, StylesStyleResolution, StylesApplyInput, StylesApplyOptions, StylesStateMap, StylesApplyReceiptSuccess, StylesApplyReceiptFailure, StylesApplyReceipt, StylesAdapter, NormalizedStylesApplyOptions, StylesApi, } from './apply.js';
+export { STYLE_RUN_XML_PATH, executeStylesApply } from './apply.js';
 export type { StyleRunPatch, StyleConflictPolicy, StyleChannelState, StylesCreateParagraphInput, StylesCreateCharacterInput, StylesCreateInput, StylesCreateOptions, NormalizedStylesCreateOptions, StylesCreateResolution, StylesCreateReceiptSuccess, StylesCreateReceiptFailure, StylesCreateReceipt, StylesCreateAdapter, StylesCreateApi, } from './create.js';
 export { STYLE_XML_PATH, executeStylesCreate, validateStylesCreateInput, validateStylesCreateOptions, } from './create.js';
 export type { StyleCatalogView, StyleCatalogItemType, StyleCatalogFilterType, StyleProvenance, StyleCatalogDiagnosticSeverity, StyleSourcePartStatus, StyleCatalogUsageStatus, StyleCatalogPreviewStatus, StyleCatalogViewStatus, StyleCatalogItemVisibility, StyleCatalogItemUsage, StyleCatalogItemPreview, StyleCatalogPreviewFontSource, StyleCatalogPreviewColorSource, StyleCatalogPreviewSources, StyleCatalogItem, StyleCatalogDefaults, StyleCatalogDiagnostic, StyleCatalogSourceStatus, StylesGetCatalogInput, StylesGetCatalogResult, StylesGetCatalogAdapter, } from './catalog.js';
@@ -15,4 +15,4 @@ export { STYLE_CATALOG_VIEWS, STYLE_CATALOG_FILTER_TYPES, executeStylesGetCatalo
 export type { StylesGetThemeInput, StylesThemeSourceStatus, StylesGetThemeResult, StylesGetThemeAdapter, } from './theme.js';
 export { executeStylesGetTheme, validateStylesGetThemeInput } from './theme.js';
 export type { PatchKeyClassification } from './validation.js';
-export { validateValue, classifyPatchKey, validatePatchObject } from './validation.js';
+export { validateValue, classifyPatchKey, validatePatchObject, validateStylesApplyInput } from './validation.js';

package/dist/document-api/src/styles/schema.d.ts

@@ -10,7 +10,9 @@ export declare function toJsonSchema(schema: ValueSchema): JsonSchema;
  * a schema that advertised them on `docDefaults` would describe an input the
  * validator rejects.
  */
-export declare function buildPatchSchema(channel: StylesChannel, scope?: StylesScope): JsonSchema;
+export declare function buildPatchSchema(channel: StylesChannel, scope?: StylesScope, options?: {
+    nullable?: boolean;
+}): JsonSchema;
 /**
  * Builds a JSON Schema for the before/after state map of a given scope.
  *

package/dist/document-api/src/styles/validation.d.ts

@@ -13,6 +13,13 @@ export type StylesApplyInputShape = {
         channel: StylesChannel;
     };
     patch: Record<string, unknown>;
+} | {
+    target: {
+        scope: 'style';
+        styleId: string;
+        channel: 'run';
+    };
+    patch: Record<string, unknown>;
 };
 export declare function validateStylesApplyInput(input: unknown): asserts input is StylesApplyInputShape;
 export declare function validateStylesApplyOptions(options: unknown): void;
@@ -36,12 +43,6 @@ export type PatchKeyClassification = {
  * cross-channel lookups.
  */
 export declare function classifyPatchKey(key: string, channel: StylesChannel, scope?: StylesScope): PatchKeyClassification;
-/**
- * Validates the keys and values of a patch object against one channel.
- *
- * Shared by `styles.apply` (scope `docDefaults`) and `styles.create` (scope
- * `style`); `field` names the caller's own input path so the error points at
- * `patch` or at `run` / `paragraph` rather than at whichever one happened to
- * write this code.
- */
-export declare function validatePatchObject(patch: Record<string, unknown>, channel: StylesChannel, scope: StylesScope, field: string): void;
+export declare function validatePatchObject(patch: Record<string, unknown>, channel: StylesChannel, scope: StylesScope, field: string, options?: {
+    allowNull?: boolean;
+}): void;

package/dist/document-api/src/types/receipt.d.ts

@@ -1,4 +1,4 @@
-import { BlockNavigationAddress, EntityAddress, SelectionTarget, TextAddress, TrackedChangeAddress } from './address.js';
+import { BlockNavigationAddress, EntityAddress, SelectionTarget, TextAddress, TextTarget, TrackedChangeAddress } from './address.js';
 import { BlockNodeAddress } from './base.js';
 import { BookmarkAddress } from '../bookmarks/bookmarks.types.js';
 import { StoryLocator } from './story.types.js';
@@ -131,6 +131,7 @@ export interface ReceiptEffects {
     insertedText?: TextMutationEffect[];
     /** Blocks created by the mutation, in document order. */
     insertedBlocks?: BlockMutationEffect[];
+    resultText?: TextTarget;
 }
 export type ReceiptSuccess = {
     /** Caller correlation for this commit. Never replayed as the original edit on Undo/Redo. */

package/dist/document-api/src/types/temporary-mutation.d.ts

@@ -1,12 +1,47 @@
 import { DocumentApiSurface } from '../index.js';
-import { ReceiptSuccess } from './receipt.js';
+import { ReceiptFailureResult, ReceiptSuccess } from './receipt.js';
+import { PlainTextInsertInput } from '../insert/insert.js';
+import { ParagraphTextReplaceInput, ReplaceMutationOptions, TextReplaceInput } from '../replace/replace.js';
+import { MutationOptions, TrackedTextMutationOptions } from '../write/write.js';
+import { BodyStoryLocator } from './story.types.js';
 type TemporaryCall<Name extends string, Method extends (...args: never[]) => unknown> = {
     operation: Name;
     input: Parameters<Method>[0];
     options?: Parameters<Method>[1];
 };
+type TemporaryText<Name extends 'insert' | 'replace', Input> = {
+    operation: Name;
+    input: Input;
+    options?: MutationOptions & {
+        author?: never;
+    };
+} | {
+    operation: Name;
+    input: Exclude<Input, {
+        target: BodyStoryLocator;
+    }>;
+    options: TrackedTextMutationOptions;
+};
+export interface TemporaryOperationResultTarget {
+    kind: 'operationResult';
+    operationId: string;
+}
+type CommentsCreate = DocumentApiSurface['comments']['create'];
+type TemporaryCommentInput = Omit<Parameters<CommentsCreate>[0], 'target'> & {
+    target?: Parameters<CommentsCreate>[0]['target'] | TemporaryOperationResultTarget;
+};
 /** Operations run in order against the temporary document, as one atomic update. */
-export type TemporaryMutationOperation = TemporaryCall<'insert', DocumentApiSurface['insert']> | TemporaryCall<'replace', DocumentApiSurface['replace']> | TemporaryCall<'delete', DocumentApiSurface['delete']> | TemporaryCall<'blocks.delete', DocumentApiSurface['blocks']['delete']> | TemporaryCall<'trackChanges.decide', DocumentApiSurface['trackChanges']['decide']> | TemporaryCall<'comments.create', DocumentApiSurface['comments']['create']>;
+export type TemporaryMutationOperation = {
+    id?: string;
+} & (TemporaryText<'insert', PlainTextInsertInput> | TemporaryText<'replace', TextReplaceInput> | {
+    operation: 'replace';
+    input: ParagraphTextReplaceInput;
+    options?: ReplaceMutationOptions;
+} | TemporaryCall<'delete', DocumentApiSurface['delete']> | TemporaryCall<'blocks.delete', DocumentApiSurface['blocks']['delete']> | TemporaryCall<'trackChanges.decide', DocumentApiSurface['trackChanges']['decide']> | {
+    operation: 'comments.create';
+    input: TemporaryCommentInput;
+    options?: Parameters<CommentsCreate>[1];
+});
 export interface TemporaryMutationInput {
     /** Host tag echoed on every temporary mutation and its rollback/commit receipt. */
     tag: string;
@@ -39,11 +74,11 @@ export interface TemporaryMutationMetadata {
     tag: string;
     onNativeEdit?: 'cancel' | 'preserve';
 }
-export type TemporaryMutationReceipt = ReceiptSuccess & {
+export type TemporaryMutationReceipt = (ReceiptSuccess & {
     temporary: TemporaryMutationMetadata;
     revision: {
         before: string;
         after: string;
     };
-};
+}) | ReceiptFailureResult;
 export {};

package/dist/layout-engine/contracts/src/direction-context.d.ts

@@ -197,8 +197,7 @@ export declare function getParagraphInlineDirection(attrs: {
  *
  * Prefers the resolved {@link TableDirectionContext} when present, falls
  * back to the legacy `tableProperties.rightToLeft` (or `bidiVisual` alias)
- * for compatibility. The AIDEV-NOTE on the fallback branch names the
- * retirement signal.
+ * for compatibility.
  *
  * Per ECMA-376 §17.4.1, `w:bidiVisual` affects only cell ordering and
  * table-visual properties. Cell paragraph inline direction is independent;

package/dist/layout-engine/contracts/src/resolved-layout.d.ts

@@ -111,8 +111,6 @@ export type ResolvedGroupItem = {
 /**
  * A resolved fragment wrapper item.
  * Carries positioning and metadata needed to create the fragment's DOM wrapper.
- * Inner content rendering is delegated to the Fragment-based render path via
- * fragmentIndex; see the compat-fallback note on that field.
  */
 export type ResolvedFragmentItem = {
     kind: 'fragment';
@@ -138,14 +136,6 @@ export type ResolvedFragmentItem = {
     fragment: Fragment;
     /** Block ID. Written to data-block-id. */
     blockId: string;
-    /**
-     * Index back into page.fragments.
-     *
-     * AIDEV-NOTE: compat-fallback. The painter currently reads inner content from
-     * Fragment via this index because ResolvedFragmentItem does not carry full
-     * content yet. Becomes unused once paint items are self-describing; do not
-     * promote this to a permanent API surface.
-     */
     fragmentIndex: number;
     /** ProseMirror start position for click-to-position mapping. */
     pmStart?: number;
@@ -280,14 +270,6 @@ export type ResolvedTableItem = {
     zIndex?: number;
     /** Block ID — written to data-block-id. */
     blockId: string;
-    /**
-     * Index back into page.fragments.
-     *
-     * AIDEV-NOTE: compat-fallback. The painter currently reads inner content from
-     * Fragment via this index because ResolvedFragmentItem does not carry full
-     * content yet. Becomes unused once paint items are self-describing; do not
-     * promote this to a permanent API surface.
-     */
     fragmentIndex: number;
     /** Source TableFragment back-pointer (see ResolvedFragmentItem.fragment). */
     fragment: Fragment;
@@ -357,14 +339,6 @@ export type ResolvedImageItem = {
     zIndex?: number;
     /** Block ID — written to data-block-id. */
     blockId: string;
-    /**
-     * Index back into page.fragments.
-     *
-     * AIDEV-NOTE: compat-fallback. The painter currently reads inner content from
-     * Fragment via this index because ResolvedFragmentItem does not carry full
-     * content yet. Becomes unused once paint items are self-describing; do not
-     * promote this to a permanent API surface.
-     */
     fragmentIndex: number;
     /** Source ImageFragment back-pointer (see ResolvedFragmentItem.fragment). */
     fragment: Fragment;
@@ -426,14 +400,6 @@ export type ResolvedDrawingItem = {
     zIndex?: number;
     /** Block ID — written to data-block-id. */
     blockId: string;
-    /**
-     * Index back into page.fragments.
-     *
-     * AIDEV-NOTE: compat-fallback. The painter currently reads inner content from
-     * Fragment via this index because ResolvedFragmentItem does not carry full
-     * content yet. Becomes unused once paint items are self-describing; do not
-     * promote this to a permanent API surface.
-     */
     fragmentIndex: number;
     /** Source DrawingFragment back-pointer (see ResolvedFragmentItem.fragment). */
     fragment: Fragment;

package/dist/layout-engine/layout-bridge/src/neutral-hit.d.ts

@@ -35,13 +35,6 @@ export type LayoutHit = {
     sourceAnchor?: SourceAnchor;
     /** Diagnostics for partially supported or rejected hits. */
     diagnostics?: LayoutHitDiagnostic[];
-    /**
-     * Legacy PM-shaped position hit.
-     *
-     * AIDEV-NOTE: compat-fallback - callers may still consume `pmPosition`.
-     * Retire once providers stop relying on PM positions to map this hit back to
-     * a document ref. Do not gate new editor-neutral behavior on this field.
-     */
     legacyPm?: PositionHit;
 };
 export type LayoutHitDiagnostic = {

package/dist/layout-engine/layout-engine/src/index.d.ts

@@ -302,7 +302,6 @@ export type LayoutDocumentContinuation = {
     }): Promise<LayoutContinuationBatch>;
     dispose(): void;
 };
-/** AIDEV-NOTE: The handle owns one live paginator; advancing never replays a stopped prefix. */
 export declare function createLayoutDocumentContinuation(blocks: FlowBlock[], measures: Measure[], options?: LayoutOptions, execution?: LayoutExecutionControl): LayoutDocumentContinuation;
 export type LayoutRangeBoundaryPolicy = 'conservative-context' | 'overscan' | 'degraded-on-incomplete-state';
 export type LayoutRangeExactness = 'exact' | 'pending-layout' | 'degraded-unsupported' | 'stale';

package/dist/layout-engine/painters/dom/src/features/inline-direction/run-direction.d.ts

@@ -26,9 +26,6 @@ export declare const RTL_DATE_LIKE_TOKEN_RE: RegExp;
  * FE70-FEFF Arabic-B). The block range covers Hebrew, Arabic, Syriac, NKo,
  * etc.; the Script properties add presentation forms without including
  * noncharacters (FDD0-FDEF) or the BOM (FEFF).
- *
- * AIDEV-NOTE: also used by editing/runtime mixed-bidi handling. Consolidating
- * crosses a layer boundary; tracked under SD-3169 follow-ups.
  */
 export declare const STRONG_RTL_CHAR_RE: RegExp;
 /**

package/dist/public/ui-react.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-DK14sCrT.cjs");
+const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-D1eOhAjv.cjs");
 const require_slice_source = require("../chunks/slice-source-CFaqq0Vo.cjs");
 let react = require("react");
 let use_sync_external_store_shim = require("use-sync-external-store/shim");

package/dist/public/ui-react.es.js

@@ -1,4 +1,4 @@
-import { t as createSuperDocUI } from "../chunks/create-super-doc-ui-BCQ5RHxy.es.js";
+import { t as createSuperDocUI } from "../chunks/create-super-doc-ui-B29zw5qD.es.js";
 import { t as toSliceSource } from "../chunks/slice-source-gfOhG2MW.es.js";
 import { createContext, createElement, useCallback, useContext, useEffect, useRef, useState } from "react";
 import { useSyncExternalStore } from "use-sync-external-store/shim";

package/dist/public/ui-vue.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-DK14sCrT.cjs");
+const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-D1eOhAjv.cjs");
 const require_slice_source = require("../chunks/slice-source-CFaqq0Vo.cjs");
 let superdoc_entry_vue = require("vue");
 //#region src/public/ui/vue.ts

package/dist/public/ui-vue.es.js

@@ -1,4 +1,4 @@
-import { t as createSuperDocUI } from "../chunks/create-super-doc-ui-BCQ5RHxy.es.js";
+import { t as createSuperDocUI } from "../chunks/create-super-doc-ui-B29zw5qD.es.js";
 import { t as toSliceSource } from "../chunks/slice-source-gfOhG2MW.es.js";
 import { computed, inject, onScopeDispose, provide, shallowRef, toRaw, toValue, watch } from "vue";
 //#region src/public/ui/vue.ts

package/dist/public/ui.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-DK14sCrT.cjs");
+const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-D1eOhAjv.cjs");
 //#region ../document-api/src/types/receipt.ts
 /** Read a known failure.details.reason without assuming every failure has one. */
 function getDocumentApiRejectionReason(details) {

package/dist/public/ui.es.js

@@ -1,4 +1,4 @@
-import { f as shallowEqual, o as BUILT_IN_COMMAND_IDS, t as createSuperDocUI } from "../chunks/create-super-doc-ui-BCQ5RHxy.es.js";
+import { f as shallowEqual, o as BUILT_IN_COMMAND_IDS, t as createSuperDocUI } from "../chunks/create-super-doc-ui-B29zw5qD.es.js";
 //#region ../document-api/src/types/receipt.ts
 /** Read a known failure.details.reason without assuming every failure has one. */
 function getDocumentApiRejectionReason(details) {