superdoc 2.4.0-next.21 → 2.4.0-next.22

package/dist/collaboration-upgrade-engine.cjs

@@ -19,7 +19,7 @@ var COLLABORATION_UPGRADE_ENGINE_MINIMUM_NODE_MAJOR = 20;
 var PRIVATE_ENGINE_INFO = (0, _superdoc_docx_engine_collaboration_upgrade_engine.getCollaborationUpgradeEngineInfo)();
 var ENGINE_INFO = Object.freeze({
 	...PRIVATE_ENGINE_INFO,
-	superdocVersion: "2.4.0-next.21",
+	superdocVersion: "2.4.0-next.22",
 	roomSchemaVersion: Object.freeze({ ...PRIVATE_ENGINE_INFO.roomSchemaVersion }),
 	supportedBundleVersions: SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS,
 	supportedV1ReaderContractVersions: SUPPORTED_V1_READER_CONTRACT_VERSIONS

package/dist/collaboration-upgrade-engine.es.js

@@ -18,7 +18,7 @@ var COLLABORATION_UPGRADE_ENGINE_MINIMUM_NODE_MAJOR = 20;
 var PRIVATE_ENGINE_INFO = getCollaborationUpgradeEngineInfo$1();
 var ENGINE_INFO = Object.freeze({
 	...PRIVATE_ENGINE_INFO,
-	superdocVersion: "2.4.0-next.21",
+	superdocVersion: "2.4.0-next.22",
 	roomSchemaVersion: Object.freeze({ ...PRIVATE_ENGINE_INFO.roomSchemaVersion }),
 	supportedBundleVersions: SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS,
 	supportedV1ReaderContractVersions: SUPPORTED_V1_READER_CONTRACT_VERSIONS

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

@@ -1,5 +1,6 @@
 import { InlineAnchor } from '../types/base.js';
 import { TextTarget } from '../types/address.js';
+import { StoryLocator } from '../types/story.types.js';
 import { AdapterMutationFailure } from '../types/adapter-result.js';
 import { DiscoveryOutput } from '../types/discovery.js';
 import { TocCreateLocation } from '../toc/toc.types.js';
@@ -7,6 +8,14 @@ export interface CitationAddress {
     kind: 'inline';
     nodeType: 'citation';
     anchor: InlineAnchor;
+    /** Story containing this citation. Omit for body (backward compatible). */
+    story?: StoryLocator;
+    /** Session-stable story identity used by the v2 runtime with `fieldId`. */
+    storyId?: string;
+    /** Session-stable identity of the citation's backing OOXML field. */
+    fieldId?: string;
+    /** Field occurrence fallback for collocated citations with identical anchors. */
+    occurrenceIndex?: number;
 }
 export interface CitationSourceAddress {
     kind: 'entity';

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

@@ -42,22 +42,26 @@ export type ReviewWarning = {
  * operation. Callers maintain their own held-ref state by applying these
  * deltas:
  *
- * - Any caller-held text address whose `range.start` is `>= atChar` in the
- *   same `story` gets `range.start += delta` (and similarly `range.end`).
- * - Any caller-held text address whose range straddles `atChar` is
- *   *invalidated* — the kernel already lists those in `invalidatedRefs`.
+ * `atChar` is story-absolute. When `blockId` and `atCharInBlock` are both
+ * present, they identify the same shift in block-local visible coordinates.
+ * Consumers that store block-local ranges must fail closed when that pair is
+ * absent rather than interpreting `atChar` as a block offset.
  *
  * Negative `delta` describes a deletion. Positive `delta` describes an
  * insertion (e.g. when a `<w:del>` is rejected and its content is restored
  * to the visible flow).
  *
- * One entry per story. Cross-story shifts are reported as separate entries.
+ * One entry is emitted per story. Cross-story shifts are reported separately.
  */
 export interface TextRangeShift {
     /** The story whose text was shifted. */
     story: StoryLocator;
     /** Character offset in the story's flattened text where the shift begins. */
     atChar: number;
+    /** Block containing the shift, when the producer can prove one. */
+    blockId?: string;
+    /** Visible character offset within `blockId`, paired with `blockId`. */
+    atCharInBlock?: number;
     /** Net change in characters. Negative for deletions, positive for insertions. */
     delta: number;
 }

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

@@ -120,7 +120,7 @@ export type DocPartMetadata = {
  * - Doc parts: special objects like tables of contents
  */
 export type SdtMetadata = FieldAnnotationMetadata | StructuredContentMetadata | DocumentSectionMetadata | DocPartMetadata;
-export declare const CONTRACTS_VERSION = "1.1.0";
+export declare const CONTRACTS_VERSION = "1.2.0";
 /** Unique identifier for a block in the document. Format: `${pos}-${type}`. */
 export type BlockId = string;
 /**
@@ -655,12 +655,58 @@ export type MathRun = {
     sdt?: SdtMetadata;
 };
 export type Run = TextRun | TabRun | ImageRun | LineBreakRun | BreakRun | FieldAnnotationRun | MathRun;
+/** Layout-affecting inline-box values, resolved to logical CSS pixel sides. */
+export type ResolvedInlineBoxLayout = {
+    paddingInlineStart: number;
+    paddingInlineEnd: number;
+    paddingBlockStart: number;
+    paddingBlockEnd: number;
+    gapBefore: number;
+    gapAfter: number;
+    borderWidth: number;
+};
+/** Sanitized, paint-only inline-box appearance. */
+export type ResolvedInlineBoxAppearance = {
+    backgroundColor?: string;
+    borderColor?: string;
+    borderStyle?: 'solid' | 'dashed' | 'dotted';
+    borderRadius?: number;
+    color?: string;
+};
+/** Paint-ready inline-box style emitted on measured line slices. */
+export type ResolvedInlineBoxStyle = ResolvedInlineBoxLayout & ResolvedInlineBoxAppearance;
+/**
+ * An internal, layout-aware presentation over a paragraph-visible text range.
+ *
+ * The proof uses leaf styling (D1): measurement creates box-edge segment
+ * boundaries and the painter styles the canonical text leaves. The fallback
+ * sibling layer was not needed. Extension-authored boxes reach this internal
+ * layout contract through the v2 host bridge. RTL input is ignored (D12), and
+ * the synchronous paragraph remeasurer does not consume this field (D14).
+ */
+export type InlineBoxSpan = {
+    id: string;
+    /**
+     * UTF-16 offsets over the paragraph's flattened visible text. Every
+     * non-text run contributes one placeholder character. These offsets never
+     * alter run PM ranges, run indices, source anchors, or document identity.
+     */
+    from: number;
+    to: number;
+    layout: ResolvedInlineBoxLayout;
+    appearance: ResolvedInlineBoxAppearance;
+    className?: string;
+    data?: Record<string, string>;
+    cursor?: 'default' | 'pointer' | 'text' | 'help';
+};
 export type ParagraphBlock = {
     kind: 'paragraph';
     id: BlockId;
     runs: Run[];
     attrs?: ParagraphAttrs;
     sourceAnchor?: SourceAnchor;
+    /** @internal Layout-aware presentation projected from the extension API by the v2 host. */
+    inlineBoxes?: InlineBoxSpan[];
 };
 /** Border style (subset of OOXML ST_Border). */
 export type BorderStyle = 'none' | 'single' | 'double' | 'dashed' | 'dotted' | 'thick' | 'triple' | 'dotDash' | 'dotDotDash' | 'wave' | 'doubleWave';
@@ -1813,6 +1859,28 @@ export type LineInlineImageAlignment = {
     runIndex: number;
     verticalAlign: ImageRunVerticalAlign;
 };
+/**
+ * Paint-ready geometry for one inline-box slice on a measured line.
+ *
+ * Measurement owns the slice geometry and resolved style. The painter consumes
+ * these values directly and never normalizes logical sides or measures the DOM.
+ */
+export type LineInlineBox = {
+    id: string;
+    /** Line-relative UTF-16 offsets covered by this slice. */
+    from: number;
+    to: number;
+    x: number;
+    width: number;
+    top: number;
+    height: number;
+    startsRange: boolean;
+    endsRange: boolean;
+    style: ResolvedInlineBoxStyle;
+    className?: string;
+    data?: Record<string, string>;
+    cursor?: 'default' | 'pointer' | 'text' | 'help';
+};
 export type Line = {
     fromRun: number;
     fromChar: number;
@@ -1843,6 +1911,8 @@ export type Line = {
      * wins over the entry here.
      */
     inlineImageAlignments?: LineInlineImageAlignment[];
+    /** Paint-ready inline-box slices emitted by measurement. */
+    inlineBoxes?: LineInlineBox[];
     /**
      * Measured tab widths keyed by tab run `pmStart`, stored alongside the
      * `ParagraphMeasure` so the painter can read them even after FlowBlock
@@ -2455,5 +2525,7 @@ export declare const extractHeaderFooterSpace: (margins?: PageMargins | null) =>
 export type { ResolvedLayout, ResolvedPage, ResolvedPaintItem, ResolvedGroupItem, ResolvedFragmentItem, ResolvedParagraphContent, ResolvedTextLineItem, ResolvedDropCapItem, ResolvedListMarkerItem, ResolvedTableItem, ResolvedImageItem, ResolvedDrawingItem, ResolvedHeaderFooterPage, ResolvedHeaderFooterLayout, } from './resolved-layout.js';
 export { isResolvedTableItem, isResolvedImageItem, isResolvedDrawingItem } from './resolved-layout.js';
 export { expandRunsForInlineNewlines, isEmptyInlineSdtPlaceholderRun, isEmptySdtPlaceholderRun, sliceRunsForLine, } from './run-helpers.js';
+export { INLINE_OBJECT_REPLACEMENT_CHARACTER, flattenParagraphVisibleText, mapVisibleRangeToRunSlices, type ParagraphVisibleRunSlice, } from './paragraph-visible-text.js';
+export { inlineBoxStyleSignature, isFiniteNonNegativeInteger, normalizeInlineBoxLogicalSides, type InlineBoxLogicalSides, type ResolvedInlineBoxLogicalSides, } from './inline-box.js';
 export { PAGE_CHECKPOINT_DEPENDENCY_CLASSES, areValidPageCheckpointDependencyClasses, type NonFlowingPageRelativeAnchorDependencyProof, type PageCheckpointDependencyClass, } from './incremental-dependency.js';
 export * as Engines from './engines/index.js';

package/dist/layout-engine/contracts/src/inline-box.d.ts

@@ -0,0 +1,19 @@
+import { ResolvedInlineBoxStyle } from './index.js';
+export type InlineBoxLogicalSides = number | {
+    start: number;
+    end: number;
+};
+export type ResolvedInlineBoxLogicalSides = {
+    start: number;
+    end: number;
+};
+/** True for finite, non-negative integer CSS pixel values. */
+export declare const isFiniteNonNegativeInteger: (value: unknown) => value is number;
+/**
+ * Expands a scalar logical value into explicit start/end values.
+ *
+ * Undefined resolves to zero. Invalid or non-integer input fails closed.
+ */
+export declare const normalizeInlineBoxLogicalSides: (value: InlineBoxLogicalSides | undefined) => ResolvedInlineBoxLogicalSides | null;
+/** Stable signature for every metric and appearance value consumed by paint. */
+export declare const inlineBoxStyleSignature: (style: ResolvedInlineBoxStyle) => string;

package/dist/layout-engine/contracts/src/paragraph-visible-text.d.ts

@@ -0,0 +1,19 @@
+import { ParagraphBlock } from './index.js';
+export declare const INLINE_OBJECT_REPLACEMENT_CHARACTER = "\uFFFC";
+export type ParagraphVisibleRunSlice = {
+    runIndex: number;
+    fromChar: number;
+    toChar: number;
+};
+/**
+ * Flattens a paragraph into Document API visible-text coordinates.
+ *
+ * Text is preserved verbatim in UTF-16. Every non-text run contributes one
+ * U+FFFC object-replacement character, regardless of its rendered label.
+ */
+export declare const flattenParagraphVisibleText: (block: ParagraphBlock) => string;
+/**
+ * Maps a validated visible-text range to slices in the paragraph's run space.
+ * Returns null for non-integer, reversed, negative, or out-of-bounds ranges.
+ */
+export declare const mapVisibleRangeToRunSlices: (block: ParagraphBlock, from: number, to: number) => ParagraphVisibleRunSlice[] | null;

package/dist/layout-engine/layout-bridge/src/inline-box-key.d.ts

@@ -0,0 +1,3 @@
+import { InlineBoxSpan } from '../../contracts/src/index.js';
+/** Shared inline-box identity for measure-cache and dirty-region decisions. */
+export declare const inlineBoxKey: (box: InlineBoxSpan) => string;

package/dist/layout-engine/layout-bridge/src/run-visual-marks.d.ts

@@ -5,6 +5,8 @@ import { Run } from '../../contracts/src/index.js';
  * Include every run property that affects text measurement or painted output but is not
  * covered elsewhere (e.g. tracked-change / comment keys). When adding a new visual
  * property, update this function only — `cache.ts` and `diff.ts` both depend on it.
+ * Paragraph-scoped inline boxes are deliberately keyed by `inline-box-key.ts`,
+ * not by this run-scoped helper.
  *
  * @param run - Flow run (text, tab, image, etc.); unknown fields are ignored safely.
  * @returns Stable string encoding bold/italic/underline/strike/color/font/highlight/link.

package/dist/layout-engine/layout-bridge/src/text-measurement.d.ts

@@ -7,18 +7,6 @@ import { FontMeasureContext } from '../../../shared/font-system/src/index.js';
  * @returns CSS font string (e.g., "italic bold 16px Arial")
  */
 export declare function getRunFontString(run: Run, fontContext?: FontMeasureContext): string;
-/**
- * Measure the X position for a specific character offset within a line.
- * Uses Canvas measureText for pixel-perfect accuracy.
- *
- * @param block - The paragraph block containing the line
- * @param line - The line to measure within
- * @param charOffset - Character offset from the start of the line (0-based)
- * @param availableWidthOverride - Optional override for available width
- * @param alignmentOverride - Optional override for text alignment (e.g., 'left' for list items
- *   which are always rendered left-aligned in the DOM regardless of paragraph alignment)
- * @returns The X coordinate (in pixels) from the start of the line
- */
 export declare function measureCharacterX(block: FlowBlock, line: Line, charOffset: number, availableWidthOverride?: number, alignmentOverride?: string, fontContext?: FontMeasureContext): number;
 /**
  * Convert a character offset within a line back to a ProseMirror position.

package/dist/layout-engine/painters/dom/src/runs/inline-box.d.ts

@@ -0,0 +1,8 @@
+import { Line, LineInlineBox, ParagraphBlock, Run, TextRun } from '../../../../contracts/src/index.js';
+export declare const markInlineBoxRun: (run: TextRun, lineFrom: number, lineTo: number) => TextRun;
+/** Splits text runs at the segment boundaries emitted for inline-box edges. */
+export declare const splitInlineBoxRuns: (block: ParagraphBlock, line: Line) => Run[] | null;
+/** Returns the resolved inline advance preceding an explicitly positioned text segment. */
+export declare const inlineBoxAdvanceBeforeOffset: (boxes: readonly LineInlineBox[] | undefined, offset: number) => number;
+/** Paints measured LTR inline-box slices on the canonical text leaves. */
+export declare const paintInlineBoxes: (boxes: readonly LineInlineBox[] | undefined, lineElement: HTMLElement, isRtl: boolean) => void;

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-jSJQis_0.cjs");
+const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-CqGmoMMA.cjs");
 let react = require("react");
 //#region src/public/ui/react.ts
 /**

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

@@ -1,4 +1,4 @@
-import { t as createSuperDocUI } from "../chunks/create-super-doc-ui-CFsY0uxw.es.js";
+import { t as createSuperDocUI } from "../chunks/create-super-doc-ui-CmOSA_lN.es.js";
 import { createContext, createElement, useCallback, useContext, useEffect, useRef, useState } from "react";
 //#region src/public/ui/react.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-jSJQis_0.cjs");
+const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-CqGmoMMA.cjs");
 exports.BUILT_IN_COMMAND_IDS = require_create_super_doc_ui.BUILT_IN_COMMAND_IDS;
 exports.createSuperDocUI = require_create_super_doc_ui.createSuperDocUI;
 exports.shallowEqual = require_create_super_doc_ui.shallowEqual;

package/dist/public/ui.es.js

@@ -1,2 +1,2 @@
-import { n as shallowEqual, r as BUILT_IN_COMMAND_IDS, t as createSuperDocUI } from "../chunks/create-super-doc-ui-CFsY0uxw.es.js";
+import { n as shallowEqual, r as BUILT_IN_COMMAND_IDS, t as createSuperDocUI } from "../chunks/create-super-doc-ui-CmOSA_lN.es.js";
 export { BUILT_IN_COMMAND_IDS, createSuperDocUI, shallowEqual };