fix(sdt): block image resize inside locked SDTs and align chrome to content (SD-3258)

packages/layout-engine/contracts/src/index.ts

@@ -290,6 +290,10 @@ export type FlowRunLink = {
   history?: boolean;
 };
 
+export const EMPTY_SDT_PLACEHOLDER_TEXT = 'Click or tap here to enter text';
+
+export type SdtVisualPlaceholder = 'emptyInlineSdt' | 'emptyBlockSdt';
+
 /**
  * Common formatting marks that can be applied to any run type.
  * Used by TextRun, TabRun, and other run types that support inline formatting.
@@ -343,7 +347,7 @@ export type TextRun = RunMarks & {
   dataAttrs?: Record<string, string>;
   sdt?: SdtMetadata;
   /** Layout-only placeholder for visual affordances that do not represent document text. */
-  visualPlaceholder?: 'emptyInlineSdt';
+  visualPlaceholder?: SdtVisualPlaceholder;
   link?: FlowRunLink;
   /** Token annotations for dynamic content (page numbers, etc.). */
   token?: 'pageNumber' | 'totalPageCount' | 'pageReference';
@@ -458,10 +462,10 @@ export type ImageRun = {
 
   /**
    * Vertical alignment of image relative to text baseline.
-   * Currently only 'bottom' is supported (image sits on baseline).
-   * Future: 'top', 'middle', 'baseline', 'text-top', 'text-bottom'.
+   * 'top' keeps the image box inside the measured line height; 'bottom'
+   * preserves legacy baseline alignment for existing callers.
    */
-  verticalAlign?: 'bottom';
+  verticalAlign?: 'top' | 'bottom';
 
   /** Absolute ProseMirror position (inclusive) of this image run. */
   pmStart?: number;
@@ -2199,6 +2203,11 @@ export { isResolvedTableItem, isResolvedImageItem, isResolvedDrawingItem } from
 
 // Pure transformations on inline-run shapes (used by pm-adapter, layout-bridge,
 // and painter-dom). Located in contracts to avoid reverse stage dependencies.
-export { expandRunsForInlineNewlines, isEmptyInlineSdtPlaceholderRun, sliceRunsForLine } from './run-helpers.js';
+export {
+  expandRunsForInlineNewlines,
+  isEmptyInlineSdtPlaceholderRun,
+  isEmptySdtPlaceholderRun,
+  sliceRunsForLine,
+} from './run-helpers.js';
 
 export * as Engines from './engines/index.js';

packages/layout-engine/contracts/src/pm-range.ts

@@ -1,4 +1,5 @@
 import type { FlowBlock, Line, ParagraphBlock, ParagraphMeasure } from './index.js';
+import { isEmptySdtPlaceholderRun } from './run-helpers.js';
 
 /**
  * Represents a ProseMirror position range for a line or fragment.
@@ -93,6 +94,15 @@ export function computeLinePmRange(block: FlowBlock, line: Line): LinePmRange {
     const runPmStart = coercePmStart(run);
     if (runPmStart == null) continue;
 
+    if (isEmptySdtPlaceholderRun(run)) {
+      const runPmEnd = coercePmEnd(run) ?? runPmStart;
+      if (pmStart == null) {
+        pmStart = runPmStart;
+      }
+      pmEnd = runPmEnd;
+      continue;
+    }
+
     if (isAtomicRunKind((run as { kind?: unknown }).kind) || isImageLikeRun(run)) {
       const runPmEnd = coercePmEnd(run) ?? runPmStart + 1;
       if (pmStart == null) {

packages/layout-engine/contracts/src/run-helpers.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest';
 import type { FlowBlock, Line, ParagraphBlock, Run, TabRun, TextRun, TrackedChangeMeta } from './index.js';
-import { expandRunsForInlineNewlines, sliceRunsForLine } from './run-helpers.js';
+import { expandRunsForInlineNewlines, isEmptySdtPlaceholderRun, sliceRunsForLine } from './run-helpers.js';
 
 describe('expandRunsForInlineNewlines', () => {
   const makeRun = (text: string, pmStart = 0): TextRun => ({
@@ -153,4 +153,17 @@ describe('sliceRunsForLine', () => {
 
     expect(sliceRunsForLine(block, line)).toEqual([run]);
   });
+
+  it('recognizes block SDT visual placeholders', () => {
+    const run: TextRun = {
+      kind: 'text',
+      text: '',
+      fontFamily: 'Arial',
+      fontSize: 12,
+      visualPlaceholder: 'emptyBlockSdt',
+      sdt: { type: 'structuredContent', scope: 'block', id: 'sdt-block-1' },
+    };
+
+    expect(isEmptySdtPlaceholderRun(run)).toBe(true);
+  });
 });

packages/layout-engine/contracts/src/run-helpers.ts

@@ -9,14 +9,20 @@
 
 import type { FlowBlock, Line, Run, TextRun } from './index.js';
 
-export function isEmptyInlineSdtPlaceholderRun(run: Run): run is TextRun & { visualPlaceholder: 'emptyInlineSdt' } {
+export function isEmptySdtPlaceholderRun(
+  run: Run,
+): run is TextRun & { visualPlaceholder: 'emptyInlineSdt' | 'emptyBlockSdt' } {
   return (
     (run.kind === 'text' || run.kind === undefined) &&
     'text' in run &&
-    (run as TextRun).visualPlaceholder === 'emptyInlineSdt'
+    ((run as TextRun).visualPlaceholder === 'emptyInlineSdt' || (run as TextRun).visualPlaceholder === 'emptyBlockSdt')
   );
 }
 
+export function isEmptyInlineSdtPlaceholderRun(run: Run): run is TextRun & { visualPlaceholder: 'emptyInlineSdt' } {
+  return isEmptySdtPlaceholderRun(run) && run.visualPlaceholder === 'emptyInlineSdt';
+}
+
 /**
  * Expands text runs that contain inline newlines into multiple runs.
  *
@@ -90,7 +96,7 @@ export function sliceRunsForLine(block: FlowBlock, line: Line): Run[] {
     }
 
     const text = run.text ?? '';
-    if (isEmptyInlineSdtPlaceholderRun(run)) {
+    if (isEmptySdtPlaceholderRun(run)) {
       result.push(run);
       continue;
     }

packages/layout-engine/layout-bridge/src/diff.ts

@@ -3,6 +3,7 @@ import type {
   ImageBlock,
   DrawingBlock,
   ImageDrawing,
+  ImageRun,
   BoxSpacing,
   ImageAnchor,
   ImageWrap,
@@ -419,6 +420,12 @@ const paragraphBlocksEqual = (a: FlowBlock & { kind: 'paragraph' }, b: FlowBlock
   for (let i = 0; i < a.runs.length; i += 1) {
     const runA = a.runs[i];
     const runB = b.runs[i];
+    if (runA.kind === 'image' || runB.kind === 'image') {
+      if (runA.kind !== 'image' || runB.kind !== 'image') return false;
+      if (!imageRunsEqual(runA, runB)) return false;
+      continue;
+    }
+
     // MathRun: compare textContent (derived from OMML) to detect equation changes
     if (runA.kind === 'math' || runB.kind === 'math') {
       if (runA.kind !== runB.kind) return false;
@@ -449,6 +456,32 @@ const paragraphBlocksEqual = (a: FlowBlock & { kind: 'paragraph' }, b: FlowBlock
   return true;
 };
 
+const imageRunsEqual = (a: ImageRun, b: ImageRun): boolean => {
+  return (
+    a.src === b.src &&
+    a.width === b.width &&
+    a.height === b.height &&
+    a.alt === b.alt &&
+    a.title === b.title &&
+    a.clipPath === b.clipPath &&
+    a.distTop === b.distTop &&
+    a.distBottom === b.distBottom &&
+    a.distLeft === b.distLeft &&
+    a.distRight === b.distRight &&
+    a.verticalAlign === b.verticalAlign &&
+    a.rotation === b.rotation &&
+    a.flipH === b.flipH &&
+    a.flipV === b.flipV &&
+    a.gain === b.gain &&
+    a.blacklevel === b.blacklevel &&
+    a.grayscale === b.grayscale &&
+    jsonEqual(a.lum, b.lum) &&
+    jsonEqual(a.hyperlink, b.hyperlink) &&
+    jsonEqual(a.sdt, b.sdt) &&
+    shallowRecordEqual(a.dataAttrs, b.dataAttrs)
+  );
+};
+
 const imageBlocksEqual = (a: ImageBlock | ImageDrawing, b: ImageBlock | ImageDrawing): boolean => {
   return (
     a.src === b.src &&

packages/layout-engine/layout-bridge/src/remeasure.ts

@@ -10,7 +10,7 @@ import type {
   ParagraphIndent,
   LeaderDecoration,
 } from '@superdoc/contracts';
-import { Engines } from '@superdoc/contracts';
+import { EMPTY_SDT_PLACEHOLDER_TEXT, Engines, isEmptySdtPlaceholderRun } from '@superdoc/contracts';
 import type { WordParagraphLayoutOutput } from '@superdoc/word-layout';
 import {
   LIST_MARKER_GAP as _LIST_MARKER_GAP,
@@ -126,6 +126,10 @@ function fontString(run: Run): string {
  * @returns Text content of the run, or empty string for non-text runs
  */
 function runText(run: Run): string {
+  if (isEmptySdtPlaceholderRun(run)) {
+    return run.sdt?.type === 'structuredContent' && run.sdt.appearance === 'hidden' ? '' : EMPTY_SDT_PLACEHOLDER_TEXT;
+  }
+
   return 'src' in run ||
     run.kind === 'lineBreak' ||
     run.kind === 'break' ||
@@ -1380,6 +1384,17 @@ export function remeasureParagraph(
       if (text.length > 0 && isTextRun(run)) {
         lineMaxTextFontSize = Math.max(lineMaxTextFontSize, run.fontSize ?? 16);
       }
+      if (isEmptySdtPlaceholderRun(run)) {
+        const placeholderWidth = text.length > 0 ? measureRunSliceWidth(run, 0, text.length) : 0;
+        if (width > 0 && width + placeholderWidth > effectiveMaxWidth - WIDTH_FUDGE_PX) {
+          didBreakInThisLine = true;
+          break;
+        }
+        width += placeholderWidth;
+        endRun = r;
+        endChar = text.length > 0 ? text.length : start + 1;
+        continue;
+      }
       for (let c = start; c < text.length; c += 1) {
         const ch = text[c];
         if (ch === '\t') {

packages/layout-engine/layout-bridge/test/diff.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import type { VectorShapeDrawing } from '@superdoc/contracts';
+import type { ImageRun, ParagraphBlock, VectorShapeDrawing } from '@superdoc/contracts';
 import { computeDirtyRegions } from '../src/diff';
 
 const block = (id: string, text: string) => ({
@@ -8,6 +8,19 @@ const block = (id: string, text: string) => ({
   runs: [{ text, fontFamily: 'Arial', fontSize: 16 }],
 });
 
+const imageRun = (src: string, width: number, height: number): ImageRun => ({
+  kind: 'image',
+  src,
+  width,
+  height,
+});
+
+const paragraphWithRuns = (id: string, runs: ParagraphBlock['runs']) => ({
+  kind: 'paragraph' as const,
+  id,
+  runs,
+});
+
 const drawing = (overrides?: Partial<VectorShapeDrawing>): VectorShapeDrawing => ({
   kind: 'drawing',
   id: 'drawing-0',
@@ -181,6 +194,112 @@ describe('computeDirtyRegions', () => {
     expect(result.firstDirtyIndex).toBe(0);
   });
 
+  it('detects inline image height changes inside paragraphs', () => {
+    const prev = [paragraphWithRuns('0-paragraph', [imageRun('img.png', 100, 50)])];
+    const next = [paragraphWithRuns('0-paragraph', [imageRun('img.png', 100, 60)])];
+    const result = computeDirtyRegions(prev, next);
+    expect(result.firstDirtyIndex).toBe(0);
+    expect(result.stableBlockIds.has('0-paragraph')).toBe(false);
+  });
+
+  it('detects inline image width changes inside paragraphs', () => {
+    const prev = [paragraphWithRuns('0-paragraph', [imageRun('img.png', 100, 50)])];
+    const next = [paragraphWithRuns('0-paragraph', [imageRun('img.png', 120, 50)])];
+    const result = computeDirtyRegions(prev, next);
+    expect(result.firstDirtyIndex).toBe(0);
+    expect(result.stableBlockIds.has('0-paragraph')).toBe(false);
+  });
+
+  it('treats identical inline image dimensions as stable', () => {
+    const prev = [paragraphWithRuns('0-paragraph', [imageRun('img.png', 100, 50)])];
+    const next = [paragraphWithRuns('0-paragraph', [imageRun('img.png', 100, 50)])];
+    const result = computeDirtyRegions(prev, next);
+    expect(result.firstDirtyIndex).toBe(next.length);
+    expect(result.stableBlockIds.has('0-paragraph')).toBe(true);
+  });
+
+  it.each([
+    ['src', { src: 'other.png' }],
+    ['alt', { alt: 'Diagram' }],
+    ['title', { title: 'Title' }],
+    ['clipPath', { clipPath: 'inset(1px)' }],
+    ['distTop', { distTop: 1 }],
+    ['distBottom', { distBottom: 2 }],
+    ['distLeft', { distLeft: 3 }],
+    ['distRight', { distRight: 4 }],
+    ['verticalAlign', { verticalAlign: 'top' as const }],
+    ['rotation', { rotation: 90 }],
+    ['flipH', { flipH: true }],
+    ['flipV', { flipV: true }],
+    ['gain', { gain: '50000' }],
+    ['blacklevel', { blacklevel: '20000' }],
+    ['grayscale', { grayscale: true }],
+    ['lum', { lum: { bright: 10000, contrast: -10000 } }],
+    ['hyperlink', { hyperlink: { url: 'https://example.com', tooltip: 'Example' } }],
+    ['dataAttrs', { dataAttrs: { 'data-example': '1' } }],
+  ] satisfies Array<[string, Partial<ImageRun>]>)(
+    'detects inline image %s changes inside paragraphs',
+    (_field, overrides) => {
+      const prev = [paragraphWithRuns('0-paragraph', [imageRun('img.png', 100, 50)])];
+      const next = [paragraphWithRuns('0-paragraph', [{ ...imageRun('img.png', 100, 50), ...overrides }])];
+
+      const result = computeDirtyRegions(prev, next);
+
+      expect(result.firstDirtyIndex).toBe(0);
+      expect(result.stableBlockIds.has('0-paragraph')).toBe(false);
+    },
+  );
+
+  it('detects inline image SDT metadata changes inside paragraphs', () => {
+    const prev = [paragraphWithRuns('0-paragraph', [imageRun('img.png', 100, 50)])];
+    const next = [
+      paragraphWithRuns('0-paragraph', [
+        {
+          ...imageRun('img.png', 100, 50),
+          sdt: {
+            type: 'structuredContent',
+            scope: 'inline',
+            id: 'image-sdt',
+            lockMode: 'contentLocked',
+          },
+        },
+      ]),
+    ];
+
+    const result = computeDirtyRegions(prev, next);
+
+    expect(result.firstDirtyIndex).toBe(0);
+    expect(result.stableBlockIds.has('0-paragraph')).toBe(false);
+  });
+
+  it('detects inline image resize in mixed text and image paragraphs', () => {
+    const prev = [
+      paragraphWithRuns('0-paragraph', [
+        { text: 'Before ', fontFamily: 'Arial', fontSize: 16 },
+        imageRun('img.png', 100, 50),
+        { text: ' after', fontFamily: 'Arial', fontSize: 16 },
+      ]),
+    ];
+    const next = [
+      paragraphWithRuns('0-paragraph', [
+        { text: 'Before ', fontFamily: 'Arial', fontSize: 16 },
+        imageRun('img.png', 100, 60),
+        { text: ' after', fontFamily: 'Arial', fontSize: 16 },
+      ]),
+    ];
+    const result = computeDirtyRegions(prev, next);
+    expect(result.firstDirtyIndex).toBe(0);
+    expect(result.stableBlockIds.has('0-paragraph')).toBe(false);
+  });
+
+  it('detects changes to later inline image runs', () => {
+    const prev = [paragraphWithRuns('0-paragraph', [imageRun('img1.png', 100, 50), imageRun('img2.png', 80, 40)])];
+    const next = [paragraphWithRuns('0-paragraph', [imageRun('img1.png', 100, 50), imageRun('img2.png', 80, 60)])];
+    const result = computeDirtyRegions(prev, next);
+    expect(result.firstDirtyIndex).toBe(0);
+    expect(result.stableBlockIds.has('0-paragraph')).toBe(false);
+  });
+
   it('treats unchanged drawing blocks as stable', () => {
     const prev = [drawing()];
     const next = [drawing()];