Merge pull request #3444 from superdoc-dev/luccas/sd-3237-bug-sdt-hover-and-click-to-place-cursor-interactions-are

fix(sdt): correct cursor placement and label interactions for structured content (SD-3237)

Author: caio-pizzol

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

@@ -299,6 +299,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.
@@ -351,6 +355,8 @@ export type TextRun = RunMarks & {
    */
   dataAttrs?: Record<string, string>;
   sdt?: SdtMetadata;
+  /** Layout-only placeholder for visual affordances that do not represent document text. */
+  visualPlaceholder?: SdtVisualPlaceholder;
   link?: FlowRunLink;
   /** Token annotations for dynamic content (page numbers, etc.). */
   token?: 'pageNumber' | 'totalPageCount' | 'pageReference';
@@ -467,10 +473,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;
@@ -2224,6 +2230,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, 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 => ({
@@ -136,4 +136,34 @@ describe('sliceRunsForLine', () => {
     const line = makeLine({ fromRun: 0, fromChar: 2, toRun: 0, toChar: 2 });
     expect(sliceRunsForLine(block, line)).toEqual([]);
   });
+
+  it('preserves empty inline SDT visual placeholders', () => {
+    const run: TextRun = {
+      kind: 'text',
+      text: '',
+      fontFamily: 'Arial',
+      fontSize: 12,
+      pmStart: 10,
+      pmEnd: 10,
+      visualPlaceholder: 'emptyInlineSdt',
+      sdt: { type: 'structuredContent', scope: 'inline', id: 'sdt-1' },
+    };
+    const block = makeParagraph([run]);
+    const line = makeLine({ fromRun: 0, fromChar: 0, toRun: 0, toChar: 0 });
+
+    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,6 +9,20 @@
 
 import type { FlowBlock, Line, Run, TextRun } from './index.js';
 
+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 === '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.
  *
@@ -82,6 +96,11 @@ export function sliceRunsForLine(block: FlowBlock, line: Line): Run[] {
     }
 
     const text = run.text ?? '';
+    if (isEmptySdtPlaceholderRun(run)) {
+      result.push(run);
+      continue;
+    }
+
     const isFirstRun = runIndex === line.fromRun;
     const isLastRun = runIndex === line.toRun;
 

packages/layout-engine/dom-contract/src/class-names.ts

@@ -27,9 +27,15 @@ export const DOM_CLASS_NAMES = {
    */
   INLINE_SDT_WRAPPER: 'superdoc-structured-content-inline',
 
+  /** Inline structured-content label chrome. */
+  INLINE_SDT_LABEL: 'superdoc-structured-content-inline__label',
+
   /** Block-level structured-content container. */
   BLOCK_SDT: 'superdoc-structured-content-block',
 
+  /** Block-level structured-content label chrome. */
+  BLOCK_SDT_LABEL: 'superdoc-structured-content__label',
+
   /** Table fragment container (resize overlay and click-mapping target). */
   TABLE_FRAGMENT: 'superdoc-table-fragment',
 
@@ -66,3 +72,9 @@ export const DOM_CLASS_NAMES = {
 
 /** Union of all DOM contract class name values. */
 export type DomClassName = (typeof DOM_CLASS_NAMES)[keyof typeof DOM_CLASS_NAMES];
+
+/** Structured-content chrome labels that should not drive text-position mapping. */
+export const STRUCTURED_CONTENT_CHROME_LABEL_CLASS_NAMES = [
+  DOM_CLASS_NAMES.INLINE_SDT_LABEL,
+  DOM_CLASS_NAMES.BLOCK_SDT_LABEL,
+] as const;

packages/layout-engine/dom-contract/src/index.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest';
 
 import {
   DOM_CLASS_NAMES,
+  STRUCTURED_CONTENT_CHROME_LABEL_CLASS_NAMES,
   DATA_ATTRS,
   DATASET_KEYS,
   buildImagePmSelector,
@@ -24,7 +25,9 @@ describe('@superdoc/dom-contract', () => {
       FRAGMENT: 'superdoc-fragment',
       LINE: 'superdoc-line',
       INLINE_SDT_WRAPPER: 'superdoc-structured-content-inline',
+      INLINE_SDT_LABEL: 'superdoc-structured-content-inline__label',
       BLOCK_SDT: 'superdoc-structured-content-block',
+      BLOCK_SDT_LABEL: 'superdoc-structured-content__label',
       TABLE_FRAGMENT: 'superdoc-table-fragment',
       DOCUMENT_SECTION: 'superdoc-document-section',
       SDT_GROUP_HOVER: 'sdt-group-hover',
@@ -38,6 +41,13 @@ describe('@superdoc/dom-contract', () => {
     });
   });
 
+  it('exports the structured content chrome label class set', () => {
+    expect(STRUCTURED_CONTENT_CHROME_LABEL_CLASS_NAMES).toEqual([
+      DOM_CLASS_NAMES.INLINE_SDT_LABEL,
+      DOM_CLASS_NAMES.BLOCK_SDT_LABEL,
+    ]);
+  });
+
   it('exports the stable data attribute names and dataset keys', () => {
     expect(DATA_ATTRS).toEqual({
       PM_START: 'data-pm-start',

packages/layout-engine/dom-contract/src/index.ts

@@ -13,7 +13,7 @@
  * implementation details.
  */
 
-export { DOM_CLASS_NAMES } from './class-names.js';
+export { DOM_CLASS_NAMES, STRUCTURED_CONTENT_CHROME_LABEL_CLASS_NAMES } from './class-names.js';
 export type { DomClassName } from './class-names.js';
 
 export { DATA_ATTRS, DATASET_KEYS, encodeLayoutStoryDataset, decodeLayoutStoryDataset } from './data-attrs.js';

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/dom-mapping.ts

@@ -24,7 +24,7 @@
  * @deprecated Use DomPointerMapping from super-editor/dom-observer instead.
  */
 
-import { DOM_CLASS_NAMES } from '@superdoc/dom-contract';
+import { DOM_CLASS_NAMES, STRUCTURED_CONTENT_CHROME_LABEL_CLASS_NAMES } from '@superdoc/dom-contract';
 
 // Debug logging for click-to-position pipeline (disabled - enable for debugging)
 const DEBUG_CLICK_MAPPING = false;
@@ -90,6 +90,10 @@ function isVisibleRect(rect: DOMRect): boolean {
   return rect.width > 0 && rect.height > 0;
 }
 
+function isStructuredContentChromeLabel(el: HTMLElement): boolean {
+  return STRUCTURED_CONTENT_CHROME_LABEL_CLASS_NAMES.some((className) => el.classList.contains(className));
+}
+
 /**
  * Maps a click coordinate to a ProseMirror document position using DOM data attributes.
  *
@@ -384,7 +388,8 @@ function processFragment(fragmentEl: HTMLElement, viewX: number, viewY: number):
     (el) =>
       el.dataset.pmStart !== undefined &&
       el.dataset.pmEnd !== undefined &&
-      !el.classList.contains(DOM_CLASS_NAMES.INLINE_SDT_WRAPPER),
+      !el.classList.contains(DOM_CLASS_NAMES.INLINE_SDT_WRAPPER) &&
+      !isStructuredContentChromeLabel(el),
   );
 
   log(
@@ -462,7 +467,8 @@ function processLineElement(lineEl: HTMLElement, viewX: number): number | null {
     (el) =>
       el.dataset.pmStart !== undefined &&
       el.dataset.pmEnd !== undefined &&
-      !el.classList.contains(DOM_CLASS_NAMES.INLINE_SDT_WRAPPER),
+      !el.classList.contains(DOM_CLASS_NAMES.INLINE_SDT_WRAPPER) &&
+      !isStructuredContentChromeLabel(el),
   );
 
   log(

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') {