superdoc 2.4.0-next.62 → 2.4.0-next.64

package/dist/chunks/{create-super-doc-ui-DNtHxzz_.cjs → create-super-doc-ui-Bom7oDPv.cjs}

@@ -1874,6 +1874,23 @@ INLINE_PROPERTY_REGISTRY.filter((entry) => entry.storage === "mark").map((entry)
 * `false` when the surface is unavailable (view mode, a pre-ready editor, or a
 * host that has not exposed a Document API facade) rather than throwing.
 */
+function uiBenchNowMs() {
+	return typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
+}
+function readUiBenchRuntime() {
+	const benchGlobal = globalThis;
+	return {
+		sink: typeof benchGlobal.__superdocV2BenchPipelineTiming === "function" ? benchGlobal.__superdocV2BenchPipelineTiming : null,
+		workerContext: benchGlobal.__superdocV2BenchWorkerMessageContext ?? null
+	};
+}
+function emitUiBenchTiming(event) {
+	const { sink } = readUiBenchRuntime();
+	if (!sink) return;
+	try {
+		sink(event);
+	} catch {}
+}
 var sharedUiTrackedChangesCatalogByHost = /* @__PURE__ */ new WeakMap();
 function acquireSharedUiTrackedChangesCatalog(host) {
 	let state = sharedUiTrackedChangesCatalogByHost.get(host);
@@ -3716,12 +3733,13 @@ function createSuperDocUI(options) {
 	let foregroundAsyncRetryTimer = null;
 	let pendingSelectionSeedValidationToken = null;
 	let typingContentInvalidationTimer = null;
+	const pendingAsyncReadSettlements = [];
 	const scheduleAsyncRefresh = () => {
 		if (asyncRefreshScheduled || disposed) return;
 		asyncRefreshScheduled = true;
 		const run = () => {
 			asyncRefreshScheduled = false;
-			if (!disposed) recompute();
+			if (!disposed) recompute("async-read-settled");
 		};
 		if (typeof queueMicrotask === "function") queueMicrotask(run);
 		else Promise.resolve().then(run);
@@ -4275,6 +4293,24 @@ function createSuperDocUI(options) {
 				failureCount: 0,
 				retryAtMs: 0
 			});
+			const { sink, workerContext } = readUiBenchRuntime();
+			if (sink) {
+				const settledAtMs = uiBenchNowMs();
+				pendingAsyncReadSettlements.push({
+					key,
+					settledAtMs,
+					commandId: workerContext?.commandId ?? null,
+					commandKind: workerContext?.commandKind ?? null
+				});
+				emitUiBenchTiming({
+					stage: "superdoc-ui-async-read-settled",
+					atMs: settledAtMs,
+					key,
+					settledAtMs,
+					commandId: workerContext?.commandId ?? null,
+					commandKind: workerContext?.commandKind ?? null
+				});
+			}
 			scheduleAsyncRefresh();
 		}, () => {
 			const entry = asyncReads.get(key);
@@ -6535,31 +6571,57 @@ function createSuperDocUI(options) {
 			diagnostics
 		};
 	};
-	const computeState = () => {
-		const documentMode = readDocumentMode();
-		const selection = computeSelection();
+	const computeState = (reason = "direct") => {
+		const { sink } = readUiBenchRuntime();
+		const startedAtMs = sink ? uiBenchNowMs() : 0;
+		const phaseMs = {};
+		const measure = (phase, run) => {
+			if (!sink) return run();
+			const phaseStartedAtMs = uiBenchNowMs();
+			try {
+				return run();
+			} finally {
+				phaseMs[phase] = uiBenchNowMs() - phaseStartedAtMs;
+			}
+		};
+		const documentMode = measure("documentMode", readDocumentMode);
+		const selection = measure("selection", computeSelection);
 		if (selection.status === "ready") pruneSelectionScopedAsyncReads(selection);
 		reconcilePendingInlineFormat(selection);
 		const selectionSignature = selectionInlineValueSignature(selection);
 		for (const [commandId, optimistic] of optimisticInlineToggles) if (!selectionSignature || optimistic.selectionSignature !== selectionSignature) optimisticInlineToggles.delete(commandId);
 		else if (optimistic.settled && selection.status === "ready") optimisticInlineToggles.delete(commandId);
-		return {
+		const nextState = {
 			ready: getEditor() != null,
 			documentMode,
-			document: computeDocument(),
+			document: measure("document", computeDocument),
 			selection,
 			toolbar: {
 				context: documentMode,
-				commands: computeCommandStates(selection),
+				commands: measure("toolbarCommands", () => computeCommandStates(selection)),
 				copyFormatActive: painter.mode !== "idle"
 			},
-			comments: computeComments(selection),
-			trackChanges: computeTrackChanges(selection),
-			contentControls: computeContentControls(selection),
-			zoom: computeZoom(),
-			fonts: computeFonts(),
-			styles: computeStyles(selection)
-		};
+			comments: measure("comments", () => computeComments(selection)),
+			trackChanges: measure("trackChanges", () => computeTrackChanges(selection)),
+			contentControls: measure("contentControls", () => computeContentControls(selection)),
+			zoom: measure("zoom", computeZoom),
+			fonts: measure("fonts", computeFonts),
+			styles: measure("styles", () => computeStyles(selection))
+		};
+		if (sink) {
+			const completedAtMs = uiBenchNowMs();
+			emitUiBenchTiming({
+				stage: "superdoc-ui-compute-state",
+				atMs: completedAtMs,
+				reason,
+				startedAtMs,
+				completedAtMs,
+				durationMs: completedAtMs - startedAtMs,
+				phaseMs,
+				asyncReadSettlements: pendingAsyncReadSettlements.splice(0)
+			});
+		}
+		return nextState;
 	};
 	const syncOptimisticInlineSelection = (selection) => {
 		const nextSignature = selectionInlineValueSignature(selection);
@@ -6644,7 +6706,7 @@ function createSuperDocUI(options) {
 			const unsubscribe = next.subscribe((snapshot) => {
 				selectionEpoch += 1;
 				seedCaretSelectionFromHost(snapshot);
-				recompute();
+				recompute("host-selection");
 			});
 			if (typeof unsubscribe === "function") detachHostSelection = unsubscribe;
 		} catch {
@@ -6752,7 +6814,7 @@ function createSuperDocUI(options) {
 	};
 	syncCoordinatorEditor();
 	syncTrackedChangeFocusFromHostReviewTarget(readHostActiveReviewTarget(readHostReviewSource()));
-	state = computeState();
+	state = computeState("initial");
 	lastOptimisticInlineSelectionSignature = selectionInlineValueSignature(state.selection);
 	const syncHostEventsSubscription = () => {
 		const events = (getEditor()?.host)?.events;
@@ -6820,8 +6882,10 @@ function createSuperDocUI(options) {
 			currentHostEventsSource = null;
 		}
 	};
-	const recompute = () => {
+	const recompute = (reason = "unspecified") => {
 		if (disposed) return;
+		const { sink } = readUiBenchRuntime();
+		const startedAtMs = sink ? uiBenchNowMs() : 0;
 		editCommandsRecomputeQueued = false;
 		syncCoordinatorEditor();
 		syncHostSelectionSubscription();
@@ -6830,10 +6894,36 @@ function createSuperDocUI(options) {
 		syncHostReviewSubscription();
 		syncDocumentSelectionFallbackSubscription();
 		syncHostEventsSubscription();
-		const nextState = computeState();
+		const nextState = computeState(reason);
 		syncOptimisticInlineSelection(nextState.selection);
 		state = nextState;
-		for (const listener of [...listeners]) listener(state);
+		let listenerTotalMs = 0;
+		let listenerMaxMs = 0;
+		for (const listener of [...listeners]) {
+			if (!sink) {
+				listener(state);
+				continue;
+			}
+			const listenerStartedAtMs = uiBenchNowMs();
+			listener(state);
+			const listenerMs = uiBenchNowMs() - listenerStartedAtMs;
+			listenerTotalMs += listenerMs;
+			listenerMaxMs = Math.max(listenerMaxMs, listenerMs);
+		}
+		if (sink) {
+			const completedAtMs = uiBenchNowMs();
+			emitUiBenchTiming({
+				stage: "superdoc-ui-recompute",
+				atMs: completedAtMs,
+				reason,
+				startedAtMs,
+				completedAtMs,
+				durationMs: completedAtMs - startedAtMs,
+				listenerCount: listeners.size,
+				listenerTotalMs,
+				listenerMaxMs
+			});
+		}
 	};
 	/**
 	* Work that is bound to one specific active editor and cannot survive a swap.
@@ -7423,7 +7513,7 @@ function createSuperDocUI(options) {
 		if (options && options.success === false) return options;
 		if (!selection.selectionTarget) return options ? op(input, options) : op(input);
 		return op(input, {
-			...options ?? {},
+			...options,
 			offsetSpace: "selection"
 		});
 	};

package/dist/chunks/{create-super-doc-ui-B_1l545i.es.js → create-super-doc-ui-DbzVC0rr.es.js}

@@ -1874,6 +1874,23 @@ INLINE_PROPERTY_REGISTRY.filter((entry) => entry.storage === "mark").map((entry)
 * `false` when the surface is unavailable (view mode, a pre-ready editor, or a
 * host that has not exposed a Document API facade) rather than throwing.
 */
+function uiBenchNowMs() {
+	return typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
+}
+function readUiBenchRuntime() {
+	const benchGlobal = globalThis;
+	return {
+		sink: typeof benchGlobal.__superdocV2BenchPipelineTiming === "function" ? benchGlobal.__superdocV2BenchPipelineTiming : null,
+		workerContext: benchGlobal.__superdocV2BenchWorkerMessageContext ?? null
+	};
+}
+function emitUiBenchTiming(event) {
+	const { sink } = readUiBenchRuntime();
+	if (!sink) return;
+	try {
+		sink(event);
+	} catch {}
+}
 var sharedUiTrackedChangesCatalogByHost = /* @__PURE__ */ new WeakMap();
 function acquireSharedUiTrackedChangesCatalog(host) {
 	let state = sharedUiTrackedChangesCatalogByHost.get(host);
@@ -3716,12 +3733,13 @@ function createSuperDocUI(options) {
 	let foregroundAsyncRetryTimer = null;
 	let pendingSelectionSeedValidationToken = null;
 	let typingContentInvalidationTimer = null;
+	const pendingAsyncReadSettlements = [];
 	const scheduleAsyncRefresh = () => {
 		if (asyncRefreshScheduled || disposed) return;
 		asyncRefreshScheduled = true;
 		const run = () => {
 			asyncRefreshScheduled = false;
-			if (!disposed) recompute();
+			if (!disposed) recompute("async-read-settled");
 		};
 		if (typeof queueMicrotask === "function") queueMicrotask(run);
 		else Promise.resolve().then(run);
@@ -4275,6 +4293,24 @@ function createSuperDocUI(options) {
 				failureCount: 0,
 				retryAtMs: 0
 			});
+			const { sink, workerContext } = readUiBenchRuntime();
+			if (sink) {
+				const settledAtMs = uiBenchNowMs();
+				pendingAsyncReadSettlements.push({
+					key,
+					settledAtMs,
+					commandId: workerContext?.commandId ?? null,
+					commandKind: workerContext?.commandKind ?? null
+				});
+				emitUiBenchTiming({
+					stage: "superdoc-ui-async-read-settled",
+					atMs: settledAtMs,
+					key,
+					settledAtMs,
+					commandId: workerContext?.commandId ?? null,
+					commandKind: workerContext?.commandKind ?? null
+				});
+			}
 			scheduleAsyncRefresh();
 		}, () => {
 			const entry = asyncReads.get(key);
@@ -6535,31 +6571,57 @@ function createSuperDocUI(options) {
 			diagnostics
 		};
 	};
-	const computeState = () => {
-		const documentMode = readDocumentMode();
-		const selection = computeSelection();
+	const computeState = (reason = "direct") => {
+		const { sink } = readUiBenchRuntime();
+		const startedAtMs = sink ? uiBenchNowMs() : 0;
+		const phaseMs = {};
+		const measure = (phase, run) => {
+			if (!sink) return run();
+			const phaseStartedAtMs = uiBenchNowMs();
+			try {
+				return run();
+			} finally {
+				phaseMs[phase] = uiBenchNowMs() - phaseStartedAtMs;
+			}
+		};
+		const documentMode = measure("documentMode", readDocumentMode);
+		const selection = measure("selection", computeSelection);
 		if (selection.status === "ready") pruneSelectionScopedAsyncReads(selection);
 		reconcilePendingInlineFormat(selection);
 		const selectionSignature = selectionInlineValueSignature(selection);
 		for (const [commandId, optimistic] of optimisticInlineToggles) if (!selectionSignature || optimistic.selectionSignature !== selectionSignature) optimisticInlineToggles.delete(commandId);
 		else if (optimistic.settled && selection.status === "ready") optimisticInlineToggles.delete(commandId);
-		return {
+		const nextState = {
 			ready: getEditor() != null,
 			documentMode,
-			document: computeDocument(),
+			document: measure("document", computeDocument),
 			selection,
 			toolbar: {
 				context: documentMode,
-				commands: computeCommandStates(selection),
+				commands: measure("toolbarCommands", () => computeCommandStates(selection)),
 				copyFormatActive: painter.mode !== "idle"
 			},
-			comments: computeComments(selection),
-			trackChanges: computeTrackChanges(selection),
-			contentControls: computeContentControls(selection),
-			zoom: computeZoom(),
-			fonts: computeFonts(),
-			styles: computeStyles(selection)
-		};
+			comments: measure("comments", () => computeComments(selection)),
+			trackChanges: measure("trackChanges", () => computeTrackChanges(selection)),
+			contentControls: measure("contentControls", () => computeContentControls(selection)),
+			zoom: measure("zoom", computeZoom),
+			fonts: measure("fonts", computeFonts),
+			styles: measure("styles", () => computeStyles(selection))
+		};
+		if (sink) {
+			const completedAtMs = uiBenchNowMs();
+			emitUiBenchTiming({
+				stage: "superdoc-ui-compute-state",
+				atMs: completedAtMs,
+				reason,
+				startedAtMs,
+				completedAtMs,
+				durationMs: completedAtMs - startedAtMs,
+				phaseMs,
+				asyncReadSettlements: pendingAsyncReadSettlements.splice(0)
+			});
+		}
+		return nextState;
 	};
 	const syncOptimisticInlineSelection = (selection) => {
 		const nextSignature = selectionInlineValueSignature(selection);
@@ -6644,7 +6706,7 @@ function createSuperDocUI(options) {
 			const unsubscribe = next.subscribe((snapshot) => {
 				selectionEpoch += 1;
 				seedCaretSelectionFromHost(snapshot);
-				recompute();
+				recompute("host-selection");
 			});
 			if (typeof unsubscribe === "function") detachHostSelection = unsubscribe;
 		} catch {
@@ -6752,7 +6814,7 @@ function createSuperDocUI(options) {
 	};
 	syncCoordinatorEditor();
 	syncTrackedChangeFocusFromHostReviewTarget(readHostActiveReviewTarget(readHostReviewSource()));
-	state = computeState();
+	state = computeState("initial");
 	lastOptimisticInlineSelectionSignature = selectionInlineValueSignature(state.selection);
 	const syncHostEventsSubscription = () => {
 		const events = (getEditor()?.host)?.events;
@@ -6820,8 +6882,10 @@ function createSuperDocUI(options) {
 			currentHostEventsSource = null;
 		}
 	};
-	const recompute = () => {
+	const recompute = (reason = "unspecified") => {
 		if (disposed) return;
+		const { sink } = readUiBenchRuntime();
+		const startedAtMs = sink ? uiBenchNowMs() : 0;
 		editCommandsRecomputeQueued = false;
 		syncCoordinatorEditor();
 		syncHostSelectionSubscription();
@@ -6830,10 +6894,36 @@ function createSuperDocUI(options) {
 		syncHostReviewSubscription();
 		syncDocumentSelectionFallbackSubscription();
 		syncHostEventsSubscription();
-		const nextState = computeState();
+		const nextState = computeState(reason);
 		syncOptimisticInlineSelection(nextState.selection);
 		state = nextState;
-		for (const listener of [...listeners]) listener(state);
+		let listenerTotalMs = 0;
+		let listenerMaxMs = 0;
+		for (const listener of [...listeners]) {
+			if (!sink) {
+				listener(state);
+				continue;
+			}
+			const listenerStartedAtMs = uiBenchNowMs();
+			listener(state);
+			const listenerMs = uiBenchNowMs() - listenerStartedAtMs;
+			listenerTotalMs += listenerMs;
+			listenerMaxMs = Math.max(listenerMaxMs, listenerMs);
+		}
+		if (sink) {
+			const completedAtMs = uiBenchNowMs();
+			emitUiBenchTiming({
+				stage: "superdoc-ui-recompute",
+				atMs: completedAtMs,
+				reason,
+				startedAtMs,
+				completedAtMs,
+				durationMs: completedAtMs - startedAtMs,
+				listenerCount: listeners.size,
+				listenerTotalMs,
+				listenerMaxMs
+			});
+		}
 	};
 	/**
 	* Work that is bound to one specific active editor and cannot survive a swap.
@@ -7423,7 +7513,7 @@ function createSuperDocUI(options) {
 		if (options && options.success === false) return options;
 		if (!selection.selectionTarget) return options ? op(input, options) : op(input);
 		return op(input, {
-			...options ?? {},
+			...options,
 			offsetSpace: "selection"
 		});
 	};

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.62",
+	superdocVersion: "2.4.0-next.64",
 	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.62",
+	superdocVersion: "2.4.0-next.64",
 	roomSchemaVersion: Object.freeze({ ...PRIVATE_ENGINE_INFO.roomSchemaVersion }),
 	supportedBundleVersions: SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS,
 	supportedV1ReaderContractVersions: SUPPORTED_V1_READER_CONTRACT_VERSIONS

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

@@ -318,6 +318,8 @@ export type RunMarks = {
      * Rendering normalizes a shift of zero to "no explicit shift".
      */
     baselineShift?: number;
+    /** Paint-only Word 2010+ text effects (`w14:textFill`, outline, shadow, reflection). */
+    textEffects?: TextEffects;
 };
 export type PageReferenceRelativePositionText = 'above' | 'below';
 export type FieldResultFormat = 'charformat' | 'mergeformat';
@@ -473,6 +475,18 @@ export type ImageHyperlink = {
  *   baseline next to the surrounding text instead of floating above it.
  */
 export type ImageRunVerticalAlign = 'top' | 'bottom' | 'baseline';
+/**
+ * Explicit fail-closed rendering metadata for content that keeps its authored
+ * layout box but cannot be painted faithfully.
+ *
+ * The producer owns the diagnostic identity; painters only expose it on the
+ * visible, accessible placeholder. This keeps support decisions out of the DOM
+ * layer and makes degraded output observable in browser regression proofs.
+ */
+export type RenderPlaceholder = {
+    diagnosticIds: string[];
+    accessibleName: string;
+};
 /**
  * Inline image run for images that flow with text on the same line.
  * Unlike ImageBlock (anchored/floating images), ImageRun is part of the paragraph's run array
@@ -499,10 +513,16 @@ export type ImageRun = {
     width: number;
     /** Image height in pixels. */
     height: number;
+    /** Font family of the owning OOXML run, used to compose an image-only line box. */
+    fontFamily?: string;
+    /** Font size of the owning OOXML run, used to compose an image-only line box. */
+    fontSize?: number;
     /** Alternative text for accessibility. */
     alt?: string;
     /** Image title (tooltip). */
     title?: string;
+    /** Visible fail-closed replacement when the image source cannot be painted. */
+    placeholder?: RenderPlaceholder;
     /** DrawingML docPr/@id of the picture (used to target the Document API for interactive resize). */
     imageId?: string;
     /** Clip-path value for cropped images. */
@@ -891,6 +911,8 @@ export type ImageBlock = {
     height?: number;
     alt?: string;
     title?: string;
+    /** Visible fail-closed replacement when the image source cannot be painted. */
+    placeholder?: RenderPlaceholder;
     /** DrawingML docPr/@id of the picture (used to target the Document API for interactive resize). */
     imageId?: string;
     objectFit?: 'contain' | 'cover' | 'fill' | 'scale-down';
@@ -986,6 +1008,52 @@ export type TextFormatting = {
     fontSize?: number;
     fontFamily?: string;
     letterSpacing?: number;
+    /** Paint-only Word 2010+ text effects shared with ordinary text runs. */
+    textEffects?: TextEffects;
+};
+/** Solid color used by a text effect, with optional opacity. */
+export type TextEffectColor = {
+    color: string;
+    alpha?: number;
+};
+/** Word 2010+ text outline (`w14:textOutline`). */
+export type TextOutlineEffect = {
+    /** Outline width converted from EMU to CSS pixels. */
+    width: number;
+    fill: FillColor;
+};
+/** Word 2010+ outer text shadow (`w14:shadow`). */
+export type TextShadowEffect = {
+    color: TextEffectColor;
+    /** Blur radius converted from EMU to CSS pixels. */
+    blurRadius: number;
+    /** Shadow distance converted from EMU to CSS pixels. */
+    distance: number;
+    /** Direction in DrawingML degrees (`0` points right, `90` points down). */
+    direction: number;
+};
+/** Word 2010+ reflected-text mask (`w14:reflection`). */
+export type TextReflectionEffect = {
+    blurRadius: number;
+    distance: number;
+    direction: number;
+    startAlpha: number;
+    startPosition: number;
+    endAlpha: number;
+    endPosition: number;
+    scaleX: number;
+    scaleY: number;
+};
+/**
+ * Paint-only text effects shared by paragraph runs and flattened shape text.
+ * These effects do not change glyph advances, so layout measurement continues
+ * to use the run's ordinary typography contract.
+ */
+export type TextEffects = {
+    fill?: FillColor;
+    outline?: TextOutlineEffect;
+    shadow?: TextShadowEffect;
+    reflection?: TextReflectionEffect;
 };
 /** A single text part with optional formatting. */
 export type TextPart = {
@@ -1041,6 +1109,20 @@ export type ShapeTextContent = {
     /** Horizontal text alignment within the shape. */
     horizontalAlign?: 'left' | 'center' | 'right';
 };
+/** DrawingML textbox flow/overflow semantics from `a:bodyPr`. */
+export type ShapeTextLayout = {
+    /** `a:bodyPr/@wrap`; `none` keeps authored paragraphs on explicit lines only. */
+    wrap?: 'square' | 'none';
+    /** `a:bodyPr/@horzOverflow`. */
+    horizontalOverflow?: 'overflow' | 'clip';
+    /** `a:bodyPr/@vertOverflow`. */
+    verticalOverflow?: 'overflow' | 'clip' | 'ellipsis';
+};
+/** Resolve the line-breaking width for DrawingML textbox content. */
+export declare function resolveShapeTextContentMeasureWidth(shapeWidth: number, insets: {
+    left: number;
+    right: number;
+}, layout: ShapeTextLayout | undefined, autoFitBoundaryWidth?: number): number;
 export type LineEnd = {
     type?: string;
     width?: string;
@@ -1056,8 +1138,38 @@ export type EffectExtent = {
     right: number;
     bottom: number;
 };
+/**
+ * DrawingML relative rectangle in the source 1000ths-of-a-percent units.
+ * Values may be negative: ECMA-376 allows an outset as well as an inset.
+ */
+export type ShapeImageFillRect = {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+};
+/** DrawingML `a:tile` parameters, preserved without painter-specific conversion. */
+export type ShapeImageFillTile = {
+    offsetX?: number;
+    offsetY?: number;
+    scaleX?: number;
+    scaleY?: number;
+    flip?: string;
+    alignment?: string;
+};
+/** Resolved bitmap used as the fill paint for vector geometry. */
+export type ShapeImageFill = {
+    src: string;
+    mode: 'stretch' | 'tile';
+    sourceRect?: ShapeImageFillRect;
+    fillRect?: ShapeImageFillRect;
+    tile?: ShapeImageFillTile;
+    dpi?: number;
+    rotateWithShape?: boolean;
+};
 export type VectorShapeStyle = {
     fillColor?: FillColor;
+    imageFill?: ShapeImageFill;
     strokeColor?: StrokeColor;
     strokeWidth?: number;
     /** Physical CSS-pixel dash/gap lengths resolved from the source stroke. */
@@ -1068,6 +1180,7 @@ export type VectorShapeStyle = {
     borders?: CellBorders;
     lineEnds?: LineEnds;
     textContent?: ShapeTextContent;
+    textLayout?: ShapeTextLayout;
     textAlign?: string;
     textVerticalAlign?: 'top' | 'center' | 'bottom';
     /** Legacy VML textbox text-flow semantics. */
@@ -1129,6 +1242,8 @@ export type DrawingBlockBase = {
     drawingContent?: DrawingContentSnapshot;
     attrs?: Record<string, unknown>;
     sourceAnchor?: SourceAnchor;
+    /** Visible fail-closed replacement metadata owned by the projection layer. */
+    placeholder?: RenderPlaceholder;
 };
 /**
  * Custom geometry path data extracted from a:custGeom/a:pathLst.
@@ -1150,6 +1265,7 @@ export type VectorShapeDrawing = DrawingBlockBase & {
     shapeKind?: string;
     customGeometry?: CustomGeometryData;
     fillColor?: FillColor;
+    imageFill?: ShapeImageFill;
     strokeColor?: StrokeColor;
     strokeWidth?: number;
     strokeDashArray?: number[];
@@ -1158,6 +1274,7 @@ export type VectorShapeDrawing = DrawingBlockBase & {
     lineEnds?: LineEnds;
     effectExtent?: EffectExtent;
     textContent?: ShapeTextContent;
+    textLayout?: ShapeTextLayout;
     textAlign?: string;
     textVerticalAlign?: 'top' | 'center' | 'bottom';
     textFlow?: 'horizontal' | 'vertical' | 'vertical-ideographic' | 'horizontal-ideographic' | 'bottom-to-top';
@@ -1176,6 +1293,7 @@ export type TextboxDrawing = DrawingBlockBase & {
     shapeKind?: string;
     customGeometry?: CustomGeometryData;
     fillColor?: FillColor;
+    imageFill?: ShapeImageFill;
     strokeColor?: StrokeColor;
     strokeWidth?: number;
     strokeDashArray?: number[];
@@ -1184,6 +1302,7 @@ export type TextboxDrawing = DrawingBlockBase & {
     lineEnds?: LineEnds;
     effectExtent?: EffectExtent;
     textContent?: ShapeTextContent;
+    textLayout?: ShapeTextLayout;
     textAlign?: string;
     textVerticalAlign?: 'top' | 'center' | 'bottom';
     textFlow?: 'horizontal' | 'vertical' | 'vertical-ideographic' | 'horizontal-ideographic' | 'bottom-to-top';

package/dist/layout-engine/painters/dom/src/chart-renderer.d.ts

@@ -1,13 +1,13 @@
-import { ChartModel, DrawingGeometry } from '../../../contracts/src/index.js';
+import { ChartModel, DrawingGeometry, RenderPlaceholder } from '../../../contracts/src/index.js';
 /**
  * Create a chart element from a ChartDrawing block.
  * Routes to the correct renderer based on chart type, with placeholder fallback.
  */
-export declare function createChartElement(doc: Document, chartData: ChartModel | undefined, geometry: DrawingGeometry): HTMLElement;
+export declare function createChartElement(doc: Document, chartData: ChartModel | undefined, geometry: DrawingGeometry, placeholder?: RenderPlaceholder): HTMLElement;
 /**
  * Create a placeholder for charts with missing data or unsupported types.
  * Preserves layout dimensions and is print-visible.
  */
-export declare function createChartPlaceholder(doc: Document, container: HTMLElement, label: string): HTMLElement;
+export declare function createChartPlaceholder(doc: Document, container: HTMLElement, label: string, placeholder?: RenderPlaceholder): HTMLElement;
 /** Format a numeric tick value for chart axis labels. */
 export declare function formatTickValue(value: number): string;

package/dist/layout-engine/painters/dom/src/images/render-placeholder.d.ts

@@ -0,0 +1,12 @@
+import { RenderPlaceholder } from '../../../../contracts/src/index.js';
+export type CreateRenderPlaceholderOptions = {
+    doc: Document;
+    placeholder: RenderPlaceholder;
+};
+/** Stamp the shared diagnostic and accessibility contract on a placeholder. */
+export declare const applyRenderPlaceholderSemantics: (element: HTMLElement, placeholder: RenderPlaceholder) => void;
+/**
+ * Paint an observable, print-visible replacement for content that the
+ * projection layer deliberately kept fail-closed.
+ */
+export declare const createRenderPlaceholder: ({ doc, placeholder }: CreateRenderPlaceholderOptions) => HTMLSpanElement;