@beyondwork/docx-react-component 1.0.96 → 1.0.97

package/src/ui-tailwind/editor-surface/runtime-decoration-plugin.ts

@@ -0,0 +1,190 @@
+// Refactor/11b Slice B — runtime decoration plugin (Option B fast-path).
+//
+// Before this slice, `tw-prosemirror-surface.tsx` rebuilt the entire
+// `DecorationSet` from scratch on every commit via a React effect:
+//
+//   view.setProps({ decorations: () => buildDecorations(...) });
+//
+// `buildDecorations` walks the whole PM doc + every comment thread + every
+// revision + every workflow scope + every candidate + every locked zone.
+// On a 500-page doc toggling "Show tracked changes" this was ~200–300 ms
+// (documented residual in `docs/wiki/performance.md §Context-Analytics Hot
+// Path`). On every keystroke it rebuilt the full set even when only the
+// caret + a few characters moved.
+//
+// This plugin shifts the strategy to the idiomatic PM pattern:
+//
+//   1. Plugin state holds `{ inputs, set }` — the currently-authoritative
+//      decoration inputs and the computed DecorationSet.
+//   2. On a transaction with `tr.setMeta(pluginKey, { inputs })`: inputs
+//      changed, rebuild the set once.
+//   3. On a transaction without that meta: inputs are stable. Map the
+//      existing set through `tr.mapping` (O(decorations), not O(doc)).
+//
+// Runtime-origin doc replacements — where PM state is swapped wholesale
+// via `view.updateState(state)` because the runtime produced a new
+// snapshot — can't be handled by `tr.mapping`, so the consumer dispatches
+// a meta to force a rebuild on those paths. Pure typing transactions
+// (the `onInsertText` fast-text-edit-lane commit that `view.dispatch`es a
+// local step) go through the no-meta branch and pay O(decorations) only.
+//
+// Scope of this slice: wraps the existing `buildDecorations` +
+// `buildPageBreakDecorationsFromProps` unchanged. No restructuring of
+// the 14 decoration sources inside `buildDecorations` — that's a
+// follow-up that would split per-source subsets to let single-source
+// updates skip untouched subsets.
+
+import { type EditorState, type Transaction, Plugin, PluginKey } from "prosemirror-state";
+import { type Decoration, type EditorView, DecorationSet } from "prosemirror-view";
+import type { Node as PMNode } from "prosemirror-model";
+
+import type {
+  EditorStoryTarget,
+  WorkflowBlockedCommandReason,
+  WorkflowCandidateRange,
+  WorkflowLockedZone,
+  WorkflowMetadataMarkup,
+  WorkflowScope,
+} from "../../api/public-types";
+import type { CommentDecorationModel, MarkupDisplay } from "../../ui/headless/comment-decoration-model";
+import type {
+  RevisionDecorationModel,
+  RevisionDisplayFlags,
+} from "../../ui/headless/revision-decoration-model";
+import { buildDecorations } from "./pm-decorations";
+import type { PositionMap } from "./pm-position-map";
+
+/** Inputs that drive every call to `buildDecorations`, plus an opaque
+ *  callback that supplies any additional decorations layered on top
+ *  (today: page-break chrome widgets).  Keeping page-break inputs inside
+ *  the callback keeps this module decoupled from its current dependency
+ *  graph — the caller captures whatever it needs in the closure. */
+export interface RuntimeDecorationInputs {
+  positionMap: PositionMap;
+  commentModel: CommentDecorationModel | undefined;
+  revisionModel: RevisionDecorationModel | undefined;
+  markupDisplay: MarkupDisplay;
+  showTrackedChanges: boolean;
+  suggestionsEnabled: boolean;
+  workflowScopes: readonly WorkflowScope[] | undefined;
+  activeStory: EditorStoryTarget;
+  workflowCandidates: readonly WorkflowCandidateRange[] | undefined;
+  workflowBlockedReasons: readonly WorkflowBlockedCommandReason[] | undefined;
+  workflowLockedZones: readonly WorkflowLockedZone[] | undefined;
+  activeWorkflowWorkItemId: string | null | undefined;
+  activeWorkflowScopeIds: readonly string[] | undefined;
+  workflowMetadata: readonly WorkflowMetadataMarkup[] | undefined;
+  revisionDisplayByOffset: ReadonlyMap<number, RevisionDisplayFlags> | undefined;
+  /** Extra decorations layered on top of the base `buildDecorations`
+   *  result.  Today the page-break chrome widgets flow through here —
+   *  their inputs + helper live in `tw-prosemirror-surface.tsx` so the
+   *  consumer captures them in the closure and returns built
+   *  decorations.  `null`/empty returns are fine. */
+  extraDecorations?: (doc: PMNode) => readonly Decoration[];
+}
+
+interface DecorationState {
+  inputs: RuntimeDecorationInputs | null;
+  set: DecorationSet;
+}
+
+/** Key for the plugin. Consumers dispatch via
+ *  `view.state.tr.setMeta(runtimeDecorationPluginKey, { inputs })`. */
+export const runtimeDecorationPluginKey = new PluginKey<DecorationState>(
+  "wre-runtime-decorations",
+);
+
+/** Module-level counters — mirror the style used by the L1 identity cache.
+ *  Read via `getRuntimeDecorationCounters()`.  Useful for perf benches +
+ *  tests that assert the fast-path actually runs. */
+let fullRebuilds = 0;
+let mappedTransactions = 0;
+let noOpTransactions = 0;
+
+export function getRuntimeDecorationCounters(): {
+  fullRebuilds: number;
+  mappedTransactions: number;
+  noOpTransactions: number;
+} {
+  return { fullRebuilds, mappedTransactions, noOpTransactions };
+}
+
+export function __resetRuntimeDecorationCountersForTests(): void {
+  fullRebuilds = 0;
+  mappedTransactions = 0;
+  noOpTransactions = 0;
+}
+
+function rebuildSet(doc: PMNode, inputs: RuntimeDecorationInputs): DecorationSet {
+  const base = buildDecorations(
+    doc,
+    inputs.positionMap,
+    inputs.commentModel,
+    inputs.revisionModel,
+    inputs.markupDisplay,
+    inputs.showTrackedChanges,
+    inputs.suggestionsEnabled,
+    inputs.workflowScopes,
+    inputs.activeStory,
+    inputs.workflowCandidates,
+    inputs.workflowBlockedReasons,
+    inputs.workflowLockedZones,
+    inputs.activeWorkflowWorkItemId,
+    inputs.activeWorkflowScopeIds,
+    inputs.workflowMetadata,
+    inputs.revisionDisplayByOffset,
+  );
+  const extras = inputs.extraDecorations ? inputs.extraDecorations(doc) : [];
+  if (extras.length === 0) return base;
+  // Layer extras on top of the base set. `DecorationSet.add` is the
+  // supported join that keeps the base set's structure and adds new
+  // decorations to it.
+  return base.add(doc, [...extras]);
+}
+
+export function createRuntimeDecorationPlugin(): Plugin<DecorationState> {
+  return new Plugin<DecorationState>({
+    key: runtimeDecorationPluginKey,
+    state: {
+      init: () => ({ inputs: null, set: DecorationSet.empty }),
+      apply(tr, prev, _oldState, newState): DecorationState {
+        const meta = tr.getMeta(runtimeDecorationPluginKey) as
+          | { inputs: RuntimeDecorationInputs }
+          | null
+          | undefined;
+        if (meta) {
+          fullRebuilds += 1;
+          return { inputs: meta.inputs, set: rebuildSet(newState.doc, meta.inputs) };
+        }
+        if (tr.docChanged) {
+          mappedTransactions += 1;
+          return {
+            inputs: prev.inputs,
+            set: prev.set.map(tr.mapping, newState.doc),
+          };
+        }
+        noOpTransactions += 1;
+        return prev;
+      },
+    },
+    props: {
+      decorations(state: EditorState): DecorationSet {
+        return runtimeDecorationPluginKey.getState(state)?.set ?? DecorationSet.empty;
+      },
+    },
+  });
+}
+
+/** Convenience for consumers — dispatches a meta transaction that
+ *  triggers a full rebuild.  Call whenever any `RuntimeDecorationInputs`
+ *  field changes identity or when the underlying doc was replaced
+ *  wholesale (runtime-origin `view.updateState(state)` path). */
+export function applyRuntimeDecorationInputs(
+  view: EditorView,
+  inputs: RuntimeDecorationInputs,
+): void {
+  const tr: Transaction = view.state.tr.setMeta(runtimeDecorationPluginKey, {
+    inputs,
+  });
+  view.dispatch(tr);
+}

package/src/ui-tailwind/editor-surface/tw-prosemirror-surface.tsx

@@ -53,6 +53,11 @@ import { buildDecorations } from "./pm-decorations";
 import { buildPageBreakDecorations } from "./pm-page-break-decorations";
 import { findBlockIndexRangeForPage } from "./page-slice-util.ts";
 import { DecorationSet } from "prosemirror-view";
+import {
+  applyRuntimeDecorationInputs,
+  createRuntimeDecorationPlugin,
+  type RuntimeDecorationInputs,
+} from "./runtime-decoration-plugin.ts";
 import type { WordReviewEditorLayoutFacet } from "../../api/public-types.ts";
 import { buildPagePreviewMaps } from "../../api/public-types";
 import { createContextualInteractionPlugin } from "./pm-contextual-ui";
@@ -670,52 +675,61 @@ export const TwProseMirrorSurface = forwardRef<
         onRevisionHovered: (revisionId) => props.onRevisionHovered?.(revisionId),
       }),
       createSearchPlugin(),
+      // Refactor/11b Slice B — runtime decorations as PM plugin state.
+      // Non-meta transactions map the existing set through `tr.mapping`
+      // in O(decorations); meta-tagged transactions rebuild from inputs.
+      // Registered LAST so its `props.decorations(state)` is the
+      // runtime-authoritative set the view renders. Search-plugin
+      // decorations compose at the view level — PM merges `decorations`
+      // returned by each plugin's `props.decorations`.
+      createRuntimeDecorationPlugin(),
     ];
   }, [props.awareness, props.onCommentActivated, props.onRevisionActivated, props.onRevisionHovered]);
 
   const applyDecorationProps = useCallback(
     (view: EditorView, positionMap: PositionMap): void => {
-      const baseDecorations = buildDecorations(
-        view.state.doc,
+      // Refactor/11b Slice B — dispatch inputs into the runtime decoration
+      // plugin instead of imperatively calling `view.setProps({decorations})`
+      // on every effect fire. The plugin holds the computed DecorationSet
+      // in its state; non-meta transactions (typing, selection) map the
+      // existing set through `tr.mapping` in O(decorations) rather than
+      // re-walking the doc + every comment thread / revision / workflow
+      // scope / candidate / locked zone from scratch.
+      const inputs: RuntimeDecorationInputs = {
         positionMap,
         commentModel,
         revisionModel,
         markupDisplay,
         showTrackedChanges,
         suggestionsEnabled,
-        props.workflowScopes,
-        snapshot.activeStory,
-        props.workflowCandidates,
-        props.workflowBlockedReasons,
-        props.workflowLockedZones,
-        props.activeWorkflowWorkItemId,
-        props.activeWorkflowScopeIds,
-        props.workflowMetadata,
+        workflowScopes: props.workflowScopes,
+        activeStory: snapshot.activeStory,
+        workflowCandidates: props.workflowCandidates,
+        workflowBlockedReasons: props.workflowBlockedReasons,
+        workflowLockedZones: props.workflowLockedZones,
+        activeWorkflowWorkItemId: props.activeWorkflowWorkItemId ?? null,
+        activeWorkflowScopeIds: props.activeWorkflowScopeIds,
+        workflowMetadata: props.workflowMetadata,
         revisionDisplayByOffset,
-      );
-      const pageBreakDecos = buildPageBreakDecorationsFromProps(
-        props.geometryFacet,
-        snapshot.activeStory.kind === "main",
-        positionMap,
-        props.isPageWorkspace ? "page" : "canvas",
-        props.canonicalDocument,
-        {
-          headerBandPx: props.pageChromeHeaderBandPx,
-          footerBandPx: props.pageChromeFooterBandPx,
-          interGapPx: props.pageChromeInterGapPx,
-        },
-        snapshot.surface?.blocks,
-      );
-      const decorations = pageBreakDecos.length > 0
-        ? DecorationSet.create(view.state.doc, [
-            ...pageBreakDecos,
-            ...extractDecorations(baseDecorations, view.state.doc),
-          ])
-        : baseDecorations;
-      view.setProps({
-        editable: () => canEdit,
-        decorations: () => decorations,
-      });
+        extraDecorations: (_doc) =>
+          buildPageBreakDecorationsFromProps(
+            props.geometryFacet,
+            snapshot.activeStory.kind === "main",
+            positionMap,
+            props.isPageWorkspace ? "page" : "canvas",
+            props.canonicalDocument,
+            {
+              headerBandPx: props.pageChromeHeaderBandPx,
+              footerBandPx: props.pageChromeFooterBandPx,
+              interGapPx: props.pageChromeInterGapPx,
+            },
+            snapshot.surface?.blocks,
+          ),
+      };
+      applyRuntimeDecorationInputs(view, inputs);
+      // `editable` is not decoration-shaped; keep the existing setProps
+      // path for it so the plugin-state swap stays scoped to decorations.
+      view.setProps({ editable: () => canEdit });
       decorationBuildKeyRef.current = decorationBuildKey;
       recordPerfSample("pm.decorations");
       incrementInvalidationCounter("pm.laneB.decorationUpdates");
@@ -914,24 +928,11 @@ export const TwProseMirrorSurface = forwardRef<
       props.isPageWorkspace,
     );
     positionMapRef.current = positionMap;
-    const decorations = buildDecorations(
-      state.doc,
-      positionMap,
-      commentModel,
-      revisionModel,
-      markupDisplay,
-      showTrackedChanges,
-      suggestionsEnabled,
-      props.workflowScopes,
-      snapshot.activeStory,
-      props.workflowCandidates,
-      props.workflowBlockedReasons,
-      props.workflowLockedZones,
-      props.activeWorkflowWorkItemId,
-      props.activeWorkflowScopeIds,
-      props.workflowMetadata,
-      revisionDisplayByOffset,
-    );
+    // Slice B — the runtime decoration plugin (registered in the plugin
+    // list) now owns the decoration set. The fresh-mount path dispatches
+    // inputs into the plugin via `applyDecorationProps` below; PM reads
+    // the set via the plugin's `props.decorations(state)` hook. No
+    // pre-mount `buildDecorations` call is needed.
     recordPerfSample("pm.rebuild");
     incrementInvalidationCounter("pm.laneA.rebuilds");
 
@@ -940,7 +941,6 @@ export const TwProseMirrorSurface = forwardRef<
         state,
         nodeViews: { ...tableNodeViews, ...chartNodeViews },
         editable: () => canEdit,
-        decorations: () => decorations,
       });
       viewRef.current = view;
       recordPerfSample("pm.mount");

package/src/ui-tailwind/page-stack/floating-image-overlay-model.ts

@@ -5,6 +5,7 @@ import type {
   SurfaceBlockSnapshot,
   SurfaceDrawingAnchor,
   SurfaceInlineSegment,
+  SurfacePictureEffects,
 } from "../../api/public-types.ts";
 import type { WordReviewEditorLayoutFacet } from "../../api/public-types.ts";
 import {
@@ -44,22 +45,31 @@ export interface FloatingImageOverlayItem {
   leftPx: number;
   widthPx: number;
   heightPx: number;
+  zIndex?: number;
   behindDoc: boolean;
   src: string | null;
   altText: string | null;
   detail: string | null;
+  pictureEffects?: SurfacePictureEffects;
+  shape?: {
+    label: string;
+    text: string;
+    fill?: Extract<Extract<SurfaceInlineSegment, { kind: "shape" }>["fill"], object>;
+    line?: Extract<SurfaceInlineSegment, { kind: "shape" }>["line"];
+    body?: Extract<SurfaceInlineSegment, { kind: "shape" }>["textBoxBody"];
+    marks?: Extract<SurfaceInlineSegment, { kind: "shape" }>["txbxMarks"];
+    markAttrs?: Extract<SurfaceInlineSegment, { kind: "shape" }>["txbxMarkAttrs"];
+  };
 }
 
 const SUPPORTED_HORIZONTAL_RELATIVE_FROM = new Set(["page", "margin"]);
-const SUPPORTED_VERTICAL_RELATIVE_FROM = new Set(["page", "margin"]);
+const SUPPORTED_VERTICAL_RELATIVE_FROM = new Set(["page", "margin", "paragraph"]);
+const SUPPORTED_FLOAT_WRAP_MODES = new Set(["none", "square", "topAndBottom"]);
 
 export function shouldRenderAbsoluteFloatingImageInPageOverlay(
   anchor: SurfaceDrawingAnchor | undefined,
 ): boolean {
-  if (!anchor || anchor.display !== "floating" || anchor.wrapMode !== "none") {
-    return false;
-  }
-  if (anchor.layoutInCell) {
+  if (!anchor || anchor.display !== "floating" || !SUPPORTED_FLOAT_WRAP_MODES.has(anchor.wrapMode)) {
     return false;
   }
   if (!anchor.positionH || !anchor.positionV) {
@@ -106,10 +116,13 @@ export function collectFloatingImageOverlayItems(input: {
     storyTarget: EditorStoryTarget,
   ) => {
     walkSurfaceBlocks(blocks, (segment) => {
-      if (
-        segment.kind !== "image" ||
-        !shouldRenderAbsoluteFloatingImageInPageOverlay(segment.anchor)
-      ) {
+      if (!isOverlaySegment(segment)) {
+        return;
+      }
+      if (!shouldRenderAbsoluteFloatingImageInPageOverlay(segment.anchor)) {
+        return;
+      }
+      if (isMicrosoftSensitivityLabelOverlay(segment)) {
         return;
       }
 
@@ -119,14 +132,14 @@ export function collectFloatingImageOverlayItems(input: {
         if (!pageRect) {
           continue;
         }
-        const localRect = resolveFloatingImageLocalRect(page, storyTarget, segment, pxPerTwip);
+        const localRect = resolveFloatingDrawingLocalRect(page, storyTarget, segment.anchor, pxPerTwip);
         if (!localRect) {
           continue;
         }
-        const preview = input.mediaPreviews?.[segment.mediaId];
+        const preview = segment.kind === "image" ? input.mediaPreviews?.[segment.mediaId] : undefined;
         items.push({
           key: `${segment.segmentId}:${page.pageId}`,
-          mediaId: segment.mediaId,
+          mediaId: segment.kind === "image" ? segment.mediaId : `shape:${segment.segmentId}`,
           from: segment.from,
           to: segment.to,
           pageId: page.pageId,
@@ -135,10 +148,29 @@ export function collectFloatingImageOverlayItems(input: {
           leftPx: localRect.leftPx,
           widthPx: localRect.widthPx,
           heightPx: localRect.heightPx,
+          ...(segment.anchor?.relativeHeight !== undefined
+            ? { zIndex: segment.anchor.relativeHeight }
+            : {}),
           behindDoc: Boolean(segment.anchor?.behindDoc),
           src: preview?.src ?? null,
-          altText: segment.altText ?? null,
+          altText: segment.kind === "image" ? segment.altText ?? null : null,
           detail: segment.detail ?? null,
+          ...(segment.kind === "image" && segment.pictureEffects
+            ? { pictureEffects: segment.pictureEffects }
+            : {}),
+          ...(segment.kind === "shape"
+            ? {
+                shape: {
+                  label: segment.label,
+                  text: segment.txbxText ?? segment.label,
+                  ...(segment.fill ? { fill: segment.fill } : {}),
+                  ...(segment.line ? { line: segment.line } : {}),
+                  ...(segment.textBoxBody ? { body: segment.textBoxBody } : {}),
+                  ...(segment.txbxMarks ? { marks: segment.txbxMarks } : {}),
+                  ...(segment.txbxMarkAttrs ? { markAttrs: segment.txbxMarkAttrs } : {}),
+                },
+              }
+            : {}),
         });
       }
     });
@@ -157,7 +189,36 @@ export function collectFloatingImageOverlayItems(input: {
     collectFromStory(secondary.blocks, secondary.target);
   }
 
-  return items;
+  return items.sort(compareOverlayItems);
+}
+
+function isMicrosoftSensitivityLabelOverlay(
+  segment: Extract<SurfaceInlineSegment, { kind: "image" | "shape" }>,
+): boolean {
+  if (segment.kind !== "shape") return false;
+  const name = segment.anchor?.docPr?.name ?? "";
+  const descr = segment.anchor?.docPr?.descr ?? "";
+  if (/^MSIPCM/i.test(name)) {
+    return true;
+  }
+  return /"Placement"\s*:\s*"Footer"/.test(descr) &&
+    /"Index"\s*:\s*"FirstPage"/.test(descr) &&
+    /classification/i.test(segment.txbxText ?? "");
+}
+
+function compareOverlayItems(a: FloatingImageOverlayItem, b: FloatingImageOverlayItem): number {
+  if (a.pageIndex !== b.pageIndex) return a.pageIndex - b.pageIndex;
+  const aZ = a.zIndex ?? 0;
+  const bZ = b.zIndex ?? 0;
+  if (aZ !== bZ) return aZ - bZ;
+  return a.key.localeCompare(b.key);
+}
+
+function isOverlaySegment(
+  segment: SurfaceInlineSegment,
+): segment is Extract<SurfaceInlineSegment, { kind: "image" | "shape" }> {
+  if (segment.kind === "image") return true;
+  return segment.kind === "shape" && Boolean(segment.isTextBox && segment.anchor);
 }
 
 function walkSurfaceBlocks(
@@ -205,10 +266,10 @@ function resolveTargetPages(
   });
 }
 
-function resolveFloatingImageLocalRect(
+function resolveFloatingDrawingLocalRect(
   page: PublicPageNode,
   activeStory: EditorStoryTarget,
-  segment: Extract<SurfaceInlineSegment, { kind: "image" }>,
+  anchor: SurfaceDrawingAnchor | undefined,
   pxPerTwip: number,
 ): {
   topPx: number;
@@ -216,7 +277,6 @@ function resolveFloatingImageLocalRect(
   widthPx: number;
   heightPx: number;
 } | null {
-  const anchor = segment.anchor;
   if (!anchor) {
     return null;
   }
@@ -245,12 +305,13 @@ function resolveHorizontalSpace(
   pxPerTwip: number,
 ): { startPx: number; sizePx: number } | null {
   const pageWidthPx = twipsToPx(page.layout.pageWidth, pxPerTwip);
+  const pageMarginLeftPx = twipsToPx(page.layout.marginLeft, pxPerTwip);
   const storyHost = resolveStoryHostSpace(page, activeStory, pxPerTwip);
   switch (anchor.positionH?.relativeFrom) {
     case "page":
-      return { startPx: 0, sizePx: pageWidthPx };
+      return { startPx: -pageMarginLeftPx, sizePx: pageWidthPx };
     case "margin":
-      return storyHost ? { startPx: storyHost.leftPx, sizePx: storyHost.widthPx } : null;
+      return storyHost ? { startPx: 0, sizePx: storyHost.widthPx } : null;
     default:
       return null;
   }
@@ -269,6 +330,8 @@ function resolveVerticalSpace(
       return { startPx: 0, sizePx: pageHeightPx };
     case "margin":
       return storyHost ? { startPx: storyHost.topPx, sizePx: storyHost.heightPx } : null;
+    case "paragraph":
+      return storyHost ? { startPx: storyHost.topPx, sizePx: storyHost.heightPx } : null;
     default:
       return null;
   }
@@ -339,7 +402,7 @@ function alignAxisPosition(
   page: PublicPageNode,
   orientation: "horizontal" | "vertical",
 ): number {
-  const remainder = Math.max(0, space.sizePx - objectSizePx);
+  const remainder = space.sizePx - objectSizePx;
   switch (align) {
     case "left":
     case "top":