@beyondwork/docx-react-component 1.0.58 → 1.0.60

package/src/ui-tailwind/chrome/tw-context-menu.tsx

@@ -11,6 +11,7 @@
 import * as React from "react";
 
 import { TwShortcutHint, type ShortcutKey } from "./tw-shortcut-hint";
+import { FOCUS_RING_CLASSES } from "../theme/tokens";
 
 // ---------------------------------------------------------------------------
 // Dedupe context
@@ -222,7 +223,7 @@ function ContextMenuRow({ item, platform }: ContextMenuRowProps): React.JSX.Elem
         "text-[13px] text-[var(--color-text-primary)] text-left",
         "hover:bg-[var(--color-bg-hover)]",
         "disabled:opacity-40 disabled:cursor-not-allowed",
-        "focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-[var(--color-accent)]",
+        FOCUS_RING_CLASSES,
       ].join(" ")}
     >
       <span className="flex items-center gap-2 min-w-0">

package/src/ui-tailwind/chrome/tw-image-context-toolbar.tsx

@@ -2,6 +2,7 @@ import React from "react";
 
 import { preserveEditorSelectionMouseDown } from "../../ui/headless/preserve-editor-selection";
 import type { ActiveImageContext } from "../../ui/headless/selection-tool-types";
+import { EMU_PER_INCH } from "../../runtime/units.ts";
 
 export interface TwImageContextToolbarProps {
   activeImage: ActiveImageContext;
@@ -17,10 +18,10 @@ export interface TwImageContextToolbarProps {
 }
 
 const IMAGE_SIZE_PRESETS = [
-  { label: "Small image", widthEmu: 1828800, heightEmu: 914400 },
-  { label: "Medium image", widthEmu: 2743200, heightEmu: 1371600 },
-  { label: "Large image", widthEmu: 3657600, heightEmu: 1828800 },
-] as const;
+  { label: "Small image", widthEmu: 2 * EMU_PER_INCH, heightEmu: 1 * EMU_PER_INCH },
+  { label: "Medium image", widthEmu: 3 * EMU_PER_INCH, heightEmu: 1.5 * EMU_PER_INCH },
+  { label: "Large image", widthEmu: 4 * EMU_PER_INCH, heightEmu: 2 * EMU_PER_INCH },
+];
 
 const NUDGE_EMU = 228600;
 

package/src/ui-tailwind/chrome/tw-mode-dock.tsx

@@ -1,5 +1,7 @@
 import React, { type ReactNode } from "react";
 
+import { FOCUS_RING_CLASSES } from "../theme/tokens";
+
 export interface TwModeDockAction {
   id: string;
   label: string;
@@ -15,8 +17,10 @@ export interface TwModeDockProps {
   className?: string;
 }
 
-const focusRingClass =
-  "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-1 focus-visible:ring-offset-canvas";
+// TwModeDock is a deprecated harness-only surface per designsystem §6.26,
+// but its focus ring still participates in the canonical §4.7 contract —
+// import the shared token constant so a future ring update cascades here.
+const focusRingClass = FOCUS_RING_CLASSES;
 
 export function TwModeDock(props: TwModeDockProps) {
   const actions = (props.actions ?? []).slice(0, 3);

package/src/ui-tailwind/chrome/use-container-breakpoint.ts

@@ -0,0 +1,111 @@
+/**
+ * useContainerBreakpoint — rAF-coalesced ResizeObserver hook that
+ * resolves to a named breakpoint based on a monitored element's
+ * `contentRect.width`.
+ *
+ * Motivation: the shipped `responsive-chrome.ts` compact-mode hook is
+ * viewport-driven (single threshold), so a toolbar inside a narrow
+ * split-pane renders at full width even when its container is small.
+ * Container-driven breakpoints fix this — the toolbar responds to its
+ * own box, not the page.
+ *
+ * Perf discipline (CLAUDE.md §Performance Invariants #1 + #7):
+ *   - The ResizeObserver callback MUST NOT call getBoundingClientRect
+ *     or any offset/client read.  It only reads `entry.contentRect.width`
+ *     (which is already laid-out and cached by the browser's observer
+ *     implementation).
+ *   - State updates are coalesced inside `requestAnimationFrame` so
+ *     multiple rapid resizes collapse into one render, and the new
+ *     measurement never drives a synchronous paint.
+ *
+ * Usage:
+ *
+ *   const ref = useRef<HTMLDivElement | null>(null);
+ *   const bp = useContainerBreakpoint(ref, { compact: 0, wide: 720 });
+ *   return <div ref={ref} data-breakpoint={bp}>...</div>;
+ *
+ * Thresholds map `width` to the highest-named breakpoint whose
+ * threshold is ≤ width.  Every map MUST include `0` as one of its
+ * thresholds so every width resolves to some name.
+ */
+
+import { useEffect, useMemo, useRef, useState } from "react";
+
+export type BreakpointMap = Readonly<Record<string, number>>;
+
+/**
+ * Resolve a width to the highest-named breakpoint whose threshold is
+ * ≤ width.  Exported for unit testing and for callers that already own
+ * the width and just want the mapping logic.
+ */
+export function resolveBreakpoint<T extends BreakpointMap>(
+  width: number,
+  thresholds: T,
+): keyof T | null {
+  let best: keyof T | null = null;
+  let bestThreshold = -Infinity;
+  for (const name of Object.keys(thresholds) as (keyof T)[]) {
+    const t = thresholds[name] as number;
+    if (width >= t && t > bestThreshold) {
+      best = name;
+      bestThreshold = t;
+    }
+  }
+  return best;
+}
+
+export function useContainerBreakpoint<T extends BreakpointMap>(
+  ref: React.RefObject<HTMLElement | null>,
+  thresholds: T,
+  initial: keyof T | null = null,
+): keyof T | null {
+  const [breakpoint, setBreakpoint] = useState<keyof T | null>(initial);
+  const rafRef = useRef<number | null>(null);
+  const latestWidthRef = useRef<number | null>(null);
+
+  // R8 — stringify thresholds into a stable deps key so inline
+  // literals (e.g. `{ compact: 0, wide: 720 }` declared in JSX) do
+  // not destroy + recreate the ResizeObserver on every render.  The
+  // stringify cost is a single pass over a ~3-key object when the
+  // caller's identity changes, which is what we want.
+  const depsKey = useMemo(() => JSON.stringify(thresholds), [thresholds]);
+  // Thresholds snapshot that the effect reads — captured at subscription
+  // time so the observer callback uses the values that corresponded to
+  // the current subscription.
+  const thresholdsRef = useRef(thresholds);
+  thresholdsRef.current = thresholds;
+
+  useEffect(() => {
+    const el = ref.current;
+    if (!el || typeof ResizeObserver === "undefined") return;
+
+    const observer = new ResizeObserver((entries) => {
+      // Read-only access to contentRect; no layout-triggering calls.
+      const entry = entries[entries.length - 1];
+      if (!entry) return;
+      latestWidthRef.current = entry.contentRect.width;
+      if (rafRef.current !== null) return;
+      rafRef.current = requestAnimationFrame(() => {
+        rafRef.current = null;
+        const w = latestWidthRef.current;
+        if (w === null) return;
+        const next = resolveBreakpoint(w, thresholdsRef.current);
+        setBreakpoint((prev) => (prev === next ? prev : next));
+      });
+    });
+
+    observer.observe(el);
+    return () => {
+      observer.disconnect();
+      if (rafRef.current !== null) {
+        cancelAnimationFrame(rafRef.current);
+        rafRef.current = null;
+      }
+    };
+    // depsKey is the stable projection of `thresholds`; `ref` is an
+    // object reference that callers typically hold stable via useRef.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [ref, depsKey]);
+
+  return breakpoint;
+}

package/src/ui-tailwind/chrome-overlay/tw-chrome-overlay.tsx

@@ -25,7 +25,6 @@ import type {
 } from "../../api/public-types";
 import { TwScopeRailLayer } from "./tw-scope-rail-layer";
 import { TwScopeCardLayer } from "./tw-scope-card-layer";
-import { TwPageStackOverlayLayer } from "./tw-page-stack-overlay-layer";
 import { TwPageStackChromeLayer, type PmPortalView } from "../page-stack/tw-page-stack-chrome-layer";
 import { TwTableGripLayer } from "../chrome/tw-table-grip-layer";
 import { TwObjectSelectionOverlay } from "./tw-object-selection-overlay";
@@ -219,14 +218,6 @@ export const TwChromeOverlay: React.FC<TwChromeOverlayProps> = ({
       data-testid={testId ?? "chrome-overlay"}
       role="presentation"
     >
-      {pageStackScrollRoot !== undefined ? (
-        <TwPageStackOverlayLayer
-          facet={facet}
-          scrollRoot={pageStackScrollRoot}
-          renderFrameRevision={renderFrameRevision ?? 0}
-          visiblePageIndexRange={visiblePageIndexRange ?? null}
-        />
-      ) : null}
       {pageStackScrollRoot !== undefined ? (
         <TwPageStackChromeLayer
           facet={facet}

package/src/ui-tailwind/chrome-overlay/tw-object-selection-overlay.tsx

@@ -102,6 +102,7 @@ export function TwObjectSelectionOverlay({
     <div
       ref={overlayRef}
       style={boxStyle}
+      data-chrome-overlay=""
       data-object-selection=""
       data-object-id={grabbedObjectId}
       aria-label="Selected object"

package/src/ui-tailwind/chrome-overlay/tw-page-stack-overlay-layer.tsx

@@ -628,13 +628,12 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
             height: `${rect.heightPx}px`,
             left: 0,
             right: 0,
-            // The overlay paints decorative paper-edge treatment (border
-            // + soft shadow) around each page's vertical slice.  It sits
-            // ABOVE the PM surface in stacking order so we deliberately
-            // leave `backgroundColor` unset — a filled overlay would
-            // occlude PM text.  Border + box-shadow alone give the
-            // 'distinct paper' perception without covering content.
-            backgroundColor: "transparent",
+            // N1 (L8 Phase D): this component is placed at z-0 BEFORE
+            // the z-10 PM wrapper inside `wre-page-surface`, so an opaque
+            // page background here sits behind PM text rather than on top
+            // of it.  White card + border + shadow gives the 'N distinct
+            // papers on a gray canvas' appearance.
+            backgroundColor: "var(--color-page-bg, white)",
             border: "1px solid var(--color-page-border, rgba(148,163,184,0.2))",
             borderRadius: "var(--radius-page, 4px)",
             boxShadow:

package/src/ui-tailwind/editor-surface/pm-schema.ts

@@ -8,6 +8,7 @@ import {
 import {
   isSupportedShapeGeometry,
   renderShapeSvg,
+  type GradientFill,
   type ShapeFill,
   type ShapeLine,
 } from "./shape-renderer.ts";
@@ -83,6 +84,16 @@ function safeHexColor(raw: string | null | undefined): string | null {
   return HEX_COLOR_RE.test(raw) ? `#${raw}` : null;
 }
 
+/** Strict CSS hex validator for inline style sinks. Accepts 3/4/6/8-digit hex with optional leading #. */
+function safeFilterHexColor(raw: string | null | undefined): string | null {
+  if (!raw || raw === "auto") return null;
+  const trimmed = raw.trim();
+  if (!/^#?(?:[0-9A-Fa-f]{3}|[0-9A-Fa-f]{4}|[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$/.test(trimmed)) {
+    return null;
+  }
+  return `#${trimmed.replace(/^#/, "").toUpperCase()}`;
+}
+
 /** Validate a CSS color value (may already include #). Returns the value or null. */
 function safeCssColor(raw: string | null | undefined): string | null {
   if (!raw) return null;
@@ -124,6 +135,20 @@ function resolveMarkerJustificationCss(raw: string | null): string {
   }
 }
 
+function resolveMarkerAlignCss(raw: string | null): string {
+  switch (raw) {
+    case "left":
+      return "left";
+    case "center":
+      return "center";
+    case "right":
+    case "both":
+    case "distribute":
+    default:
+      return "right";
+  }
+}
+
 /**
  * ProseMirror schema for the supported live surface slice.
  *
@@ -147,8 +172,10 @@ export const editorSchema = new Schema({
         numberingPrefix: { default: null },
         numberingSuffix: { default: null },
         numberingMarkerWidth: { default: null },
+        numberingMarkerStart: { default: null },
         numberingMarkerJustification: { default: null },
         numberingMarkerRunProperties: { default: null },
+        numberingPicBulletSrc: { default: null },
         alignment: { default: null },
         spacingBefore: { default: null },
         spacingAfter: { default: null },
@@ -217,7 +244,7 @@ export const editorSchema = new Schema({
         else if (lineSpacing && lineRule === "exact") styles.push(`line-height: ${lineSpacing / 20}pt`);
         else if (lineSpacing && lineRule === "atLeast") styles.push(`min-height: ${lineSpacing / 20}pt`);
         const indentLeft = node.attrs.indentLeft as number | null;
-        if (indentLeft) styles.push(`padding-left: ${indentLeft / 20}pt`);
+        if (indentLeft !== null) styles.push(`padding-left: ${indentLeft / 20}pt`);
         const indentRight = node.attrs.indentRight as number | null;
         if (indentRight) styles.push(`padding-right: ${indentRight / 20}pt`);
         const indentFirstLine = node.attrs.indentFirstLine as number | null;
@@ -271,7 +298,9 @@ export const editorSchema = new Schema({
         const numberingLevel = node.attrs.numberingLevel as number | null;
         const numberingSuffix = node.attrs.numberingSuffix as "tab" | "space" | "nothing" | null;
         const numberingMarkerWidth = node.attrs.numberingMarkerWidth as number | null;
+        const numberingMarkerStart = node.attrs.numberingMarkerStart as number | null;
         const numberingMarkerJustification = node.attrs.numberingMarkerJustification as string | null;
+        const numberingPicBulletSrc = node.attrs.numberingPicBulletSrc as string | null;
         const children: Array<string | number | readonly unknown[]> = [];
         if (pageBreak) {
           children.push([
@@ -285,10 +314,10 @@ export const editorSchema = new Schema({
             "Page break",
           ]);
         }
-        if (numberingPrefix) {
+        if (numberingPrefix || numberingPicBulletSrc) {
           const hasResolvedMarkerWidth =
             typeof numberingMarkerWidth === "number" && numberingMarkerWidth > 0;
-          const fallbackMinWidth = Math.min(Math.max(numberingPrefix.length + 1, 4), 14);
+          const fallbackMinWidth = Math.min(Math.max((numberingPrefix?.length ?? 1) + 1, 4), 14);
           const fallbackMarginRight =
             numberingSuffix === "nothing"
               ? "0.25rem"
@@ -315,7 +344,7 @@ export const editorSchema = new Schema({
 
           const prefixStyles = [
             `font-variant-numeric: tabular-nums`,
-            `justify-content: ${resolveMarkerJustificationCss(numberingMarkerJustification)}`,
+            `text-align: ${resolveMarkerAlignCss(numberingMarkerJustification)}`,
           ];
 
           if (markerRunProperties) {
@@ -344,9 +373,11 @@ export const editorSchema = new Schema({
               `width: ${markerWidthPt}pt`,
               `min-width: ${markerWidthPt}pt`,
               `flex-basis: ${markerWidthPt}pt`,
+              `margin-left: -${markerWidthPt}pt`,
               `margin-right: 0`,
               `overflow: visible`,
             );
+            void numberingMarkerStart; // consumed via paragraph padding-left geometry
           } else {
             prefixStyles.push(
               `min-width: ${fallbackMinWidth}ch`,
@@ -359,14 +390,16 @@ export const editorSchema = new Schema({
             {
               class: baseClasses.join(" "),
               contenteditable: "false",
-              "data-numbering-prefix": numberingPrefix,
+              "data-numbering-prefix": numberingPicBulletSrc ? "" : (numberingPrefix ?? ""),
               ...(typeof numberingLevel === "number"
                 ? { "data-numbering-level": String(numberingLevel) }
                 : {}),
               ...(numberingSuffix ? { "data-numbering-suffix": numberingSuffix } : {}),
               style: prefixStyles.join("; "),
             },
-            numberingPrefix,
+            numberingPicBulletSrc
+              ? (["img", { src: numberingPicBulletSrc, alt: "", "aria-hidden": "true", style: "max-width:100%;max-height:100%;object-fit:contain;display:block;" }] as readonly unknown[])
+              : (numberingPrefix ?? ""),
           ]);
         }
         children.push([
@@ -465,6 +498,8 @@ export const editorSchema = new Schema({
         wrapMode: { default: null },
         distMargins: { default: null },
         positionH: { default: null },
+        // Lane 6d N9.b — polygon clip for tight/through wrap.
+        wrapPolygon: { default: null },
         // Lane 6d N11.b — CSS filter effects (soft-edge, outer shadow, glow).
         softEdgeRadius: { default: null },
         outerShadow: { default: null },
@@ -504,22 +539,46 @@ export const editorSchema = new Schema({
           const softEdgeRadius = node.attrs.softEdgeRadius as number | null;
           const outerShadow = node.attrs.outerShadow as {
             blurRad: number; dist: number; dir: number; color: string;
+            colorType: "srgbClr" | "schemeClr";
+          } | null;
+          const glow = node.attrs.glow as {
+            radius: number; color: string;
+            colorType: "srgbClr" | "schemeClr";
           } | null;
-          const glow = node.attrs.glow as { radius: number; color: string } | null;
           const filterParts: string[] = [];
           if (softEdgeRadius) {
             filterParts.push(`blur(${(softEdgeRadius / EMU_PER_PX).toFixed(2)}px)`);
           }
+          // Defense in depth: even though parse-picture.ts validates
+          // srgbClr@val against a strict hex allowlist, re-validate here at
+          // the CSS sink so a future parser refactor or a bypass that lands
+          // attacker-controlled text in node.attrs cannot escape
+          // `drop-shadow(#…)` into arbitrary CSS (e.g. `FF0000) url(…)/*`).
+          // safeFilterHexColor returns `#RRGGBB` on valid hex input and
+          // empty string otherwise, so schemeClr tokens (e.g. "accent1")
+          // naturally skip this branch until a theme resolver runs.
+          const safeFilterHexColor = (raw: unknown): string => {
+            return typeof raw === "string" &&
+              /^[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$/.test(raw)
+              ? `#${raw.toUpperCase()}`
+              : "";
+          };
           if (glow) {
-            filterParts.push(`drop-shadow(0 0 ${(glow.radius / EMU_PER_PX).toFixed(2)}px #${glow.color})`);
+            const glowColor = safeFilterHexColor(glow.color);
+            if (glowColor) {
+              filterParts.push(`drop-shadow(0 0 ${(glow.radius / EMU_PER_PX).toFixed(2)}px ${glowColor})`);
+            }
           }
           if (outerShadow) {
-            const blurPx = (outerShadow.blurRad / EMU_PER_PX).toFixed(2);
-            const distPx = outerShadow.dist / EMU_PER_PX;
-            const dirRad = (outerShadow.dir / ROTATION_UNITS_PER_DEGREE) * (Math.PI / 180);
-            const dx = (distPx * Math.cos(dirRad)).toFixed(2);
-            const dy = (distPx * Math.sin(dirRad)).toFixed(2);
-            filterParts.push(`drop-shadow(${dx}px ${dy}px ${blurPx}px #${outerShadow.color})`);
+            const shadowColor = safeFilterHexColor(outerShadow.color);
+            if (shadowColor) {
+              const blurPx = (outerShadow.blurRad / EMU_PER_PX).toFixed(2);
+              const distPx = outerShadow.dist / EMU_PER_PX;
+              const dirRad = (outerShadow.dir / ROTATION_UNITS_PER_DEGREE) * (Math.PI / 180);
+              const dx = (distPx * Math.cos(dirRad)).toFixed(2);
+              const dy = (distPx * Math.sin(dirRad)).toFixed(2);
+              filterParts.push(`drop-shadow(${dx}px ${dy}px ${blurPx}px ${shadowColor})`);
+            }
           }
           // N9 float-wrap → CSS float + shape-outside on the wrapper span.
           const wrapMode = node.attrs.wrapMode as string | null;
@@ -527,8 +586,16 @@ export const editorSchema = new Schema({
           const distMargins = node.attrs.distMargins as
             | { top?: number; bottom?: number; left?: number; right?: number }
             | null;
+          const wrapPolygon = node.attrs.wrapPolygon as Array<{ x: number; y: number }> | null;
           const wrapperStyleParts: string[] = [];
-          if (isFloating && wrapMode === "square") {
+          if (isFloating && (wrapMode === "tight" || wrapMode === "through") && wrapPolygon?.length) {
+            // N9.b — polygon clip: OOXML wrapPolygon coords are in 21600ths-of-image units.
+            const floatSide = positionH?.align === "right" ? "right" : "left";
+            const pts = wrapPolygon
+              .map((p) => `${(p.x / 21600 * 100).toFixed(2)}% ${(p.y / 21600 * 100).toFixed(2)}%`)
+              .join(", ");
+            wrapperStyleParts.push(`float:${floatSide}`, `shape-outside:polygon(${pts})`);
+          } else if (isFloating && wrapMode === "square") {
             const floatSide = positionH?.align === "right" ? "right" : "left";
             wrapperStyleParts.push(
               `float:${floatSide}`,
@@ -898,14 +965,7 @@ export const editorSchema = new Schema({
           const geometry = node.attrs.geometry as string | null;
           const fill = node.attrs.fill as
             | ShapeFill
-            | {
-                kind: "gradient";
-                stops: Array<{ pos: number; color: string; colorType: "srgbClr" | "schemeClr" }>;
-                direction:
-                  | { kind: "linear"; angle: number; scaled?: boolean }
-                  | { kind: "path"; path: "circle" | "rect" | "shape" };
-                rotWithShape?: boolean;
-              }
+            | GradientFill
             | {
                 kind: "pattern";
                 preset: string;
@@ -917,11 +977,13 @@ export const editorSchema = new Schema({
           const heightEmu = node.attrs.heightEmu as number | null;
           const widthPx = widthEmu ? Math.max(8, Math.round(widthEmu / EMU_PER_PX)) : null;
           const heightPx = heightEmu ? Math.max(8, Math.round(heightEmu / EMU_PER_PX)) : null;
+          // N10.b — gradient fills pass through to renderShapeSvg (SVG defs path).
+          // Pattern fills remain unsupported → chip fallback.
           const svgFill =
             fill === undefined || fill === null
               ? undefined
-              : fill.kind === "solid" || fill.kind === "none"
-                ? fill
+              : fill.kind === "solid" || fill.kind === "none" || fill.kind === "gradient"
+                ? (fill as ShapeFill | GradientFill)
                 : undefined;
           // N10 — try SVG render path for supported geometries with extent.
           if (

package/src/ui-tailwind/editor-surface/pm-state-from-snapshot.ts

@@ -374,8 +374,14 @@ function buildParagraph(
         paragraphLayout.indentation.firstLine < 0
           ? Math.abs(paragraphLayout.indentation.firstLine)
           : null),
+      numberingMarkerStart: paragraphLayout.markerLane?.start ?? null,
       numberingMarkerJustification: paragraphLayout.markerJustification ?? null,
       numberingMarkerRunProperties: block.resolvedNumbering?.markerRunProperties ?? null,
+      numberingPicBulletSrc: (() => {
+        const mediaId = block.resolvedNumbering?.picBulletMediaId;
+        if (!mediaId) return null;
+        return mediaPreviews[mediaId]?.src ?? null;
+      })(),
       shadingFill: block.shading?.fill ?? cascade?.shading?.fill ?? null,
       borderTop: (block.borders as Record<string, unknown>)?.top ?? cascadeBorders?.top ?? null,
       borderBottom: (block.borders as Record<string, unknown>)?.bottom ?? cascadeBorders?.bottom ?? null,
@@ -464,6 +470,8 @@ function buildInlineContent(
           wrapMode: segment.anchor?.wrapMode ?? null,
           distMargins: segment.anchor?.distMargins ?? null,
           positionH: segment.anchor?.positionH ?? null,
+          // Lane 6d N9.b — polygon clip.
+          wrapPolygon: segment.anchor?.wrapPolygon ?? null,
           // Lane 6d N11.b — filter effects.
           softEdgeRadius: segment.pictureEffects?.softEdgeRadius ?? null,
           outerShadow: segment.pictureEffects?.outerShadow ?? null,
@@ -587,6 +595,7 @@ function buildTable(
     {
       styleId: block.styleId ?? null,
       gridColumns: block.gridColumns,
+      gridColumnsRelative: block.gridColumnsRelative ?? null,
       alignment: block.alignment ?? null,
       tblLookFirstRow: block.tblLook?.firstRow ?? false,
       tblLookLastRow: block.tblLook?.lastRow ?? false,

package/src/ui-tailwind/editor-surface/shape-renderer.ts

@@ -17,7 +17,7 @@
  * fill; `noLine: true` → `stroke: "none"`.
  */
 
-import { EMU_PER_PX } from "../../runtime/units";
+import { EMU_PER_PX, ROTATION_UNITS_PER_DEGREE } from "../../runtime/units";
 
 const SUPPORTED_GEOMETRIES = new Set(["rect", "ellipse", "roundRect"]);
 
@@ -81,9 +81,18 @@ export function resolveLineCss(line: ShapeLine | undefined): ResolvedLineCss {
   return { stroke, strokeWidth };
 }
 
+export type GradientFill = {
+  kind: "gradient";
+  stops: Array<{ pos: number; color: string; colorType: "srgbClr" | "schemeClr" }>;
+  direction:
+    | { kind: "linear"; angle: number; scaled?: boolean }
+    | { kind: "path"; path: "circle" | "rect" | "shape" };
+  rotWithShape?: boolean;
+};
+
 export interface ShapeSegmentLike {
   geometry?: string;
-  fill?: ShapeFill;
+  fill?: ShapeFill | GradientFill;
   line?: ShapeLine;
 }
 
@@ -94,6 +103,44 @@ export interface ShapeSegmentLike {
  */
 export type SvgSpec = readonly [string, Record<string, string>, ...SvgSpec[]];
 
+/**
+ * Build an SVG `<defs>` element containing a `<linearGradient>` or
+ * `<radialGradient>` for the given gradient fill.  `id` is the gradient
+ * element ID referenced via `fill="url(#id)"` on the geometry element.
+ *
+ * OOXML linear gradient angle: 60000ths of a degree, clockwise from north.
+ * Converted to SVG objectBoundingBox coordinates via:
+ *   x1 = 0.5 − 0.5·sin(θ), y1 = 0.5 + 0.5·cos(θ)
+ *   x2 = 0.5 + 0.5·sin(θ), y2 = 0.5 − 0.5·cos(θ)
+ * where θ is in radians.
+ *
+ * OOXML stop pos: 0–100000 (= 0–100%).
+ */
+function renderGradientDefs(fill: GradientFill, id: string): SvgSpec {
+  const stopEls: SvgSpec[] = fill.stops.map(
+    (s): SvgSpec => [
+      "stop",
+      {
+        offset: `${(s.pos / 1000).toFixed(2)}%`,
+        "stop-color": s.colorType === "srgbClr" ? `#${s.color}` : "currentColor",
+      },
+    ],
+  );
+
+  let gradEl: SvgSpec;
+  if (fill.direction.kind === "linear") {
+    const rad = (fill.direction.angle / ROTATION_UNITS_PER_DEGREE) * (Math.PI / 180);
+    const x1 = (0.5 - 0.5 * Math.sin(rad)).toFixed(4);
+    const y1 = (0.5 + 0.5 * Math.cos(rad)).toFixed(4);
+    const x2 = (0.5 + 0.5 * Math.sin(rad)).toFixed(4);
+    const y2 = (0.5 - 0.5 * Math.cos(rad)).toFixed(4);
+    gradEl = ["linearGradient", { id, x1, y1, x2, y2, gradientUnits: "objectBoundingBox" }, ...stopEls];
+  } else {
+    gradEl = ["radialGradient", { id, cx: "50%", cy: "50%", r: "50%", gradientUnits: "objectBoundingBox" }, ...stopEls];
+  }
+  return ["defs", {}, gradEl];
+}
+
 /**
  * Render a supported geometry into a PM-compatible DOMOutputSpec tree
  * for an inline `<svg>`.  Returns `null` when the geometry is unsupported
@@ -101,6 +148,9 @@ export type SvgSpec = readonly [string, Record<string, string>, ...SvgSpec[]];
  *
  * The SVG is sized 1:1 to its container; the wrapper span owns the
  * outer `width:Xpx; height:Ypx`.
+ *
+ * Gradient fills: emits `<defs><linearGradient>` / `<radialGradient>` and
+ * references it via `fill="url(#g0)"` on the geometry element.
  */
 export function renderShapeSvg(
   segment: ShapeSegmentLike,
@@ -111,7 +161,19 @@ export function renderShapeSvg(
   if (!segment.geometry || !SUPPORTED_GEOMETRIES.has(segment.geometry)) {
     return null;
   }
-  const fillCss = resolveFillCss(segment.fill);
+
+  let fillAttr: string;
+  let gradDefs: SvgSpec | null = null;
+  if (segment.fill && segment.fill.kind === "gradient") {
+    gradDefs = renderGradientDefs(segment.fill, "g0");
+    fillAttr = "url(#g0)";
+  } else {
+    fillAttr = resolveFillCss(segment.fill as ShapeFill | undefined).fill;
+  }
+
+  // Keep resolveFillCss call for non-gradient so the isSchemePlaceholder
+  // warning path (future) still fires when needed.
+  const fillCss = { fill: fillAttr, isSchemePlaceholder: false };
   const lineCss = resolveLineCss(segment.line);
   const sw = lineCss.strokeWidth;
   // Inset the geometry by half the stroke so the stroke paints inside
@@ -184,17 +246,17 @@ export function renderShapeSvg(
   // `xmlns` *attribute* after createElement() is meaningless — the
   // resulting node is HTMLUnknownElement and won't paint as SVG.
   // Children inherit the namespace, so the geometry tag stays bare.
-  return [
-    "http://www.w3.org/2000/svg svg",
-    {
-      viewBox: `0 0 ${widthPx} ${heightPx}`,
-      width: String(widthPx),
-      height: String(heightPx),
-      preserveAspectRatio: "none",
-      "aria-hidden": "true",
-    },
-    geometryEl,
-  ];
+  const svgAttrs = {
+    viewBox: `0 0 ${widthPx} ${heightPx}`,
+    width: String(widthPx),
+    height: String(heightPx),
+    preserveAspectRatio: "none",
+    "aria-hidden": "true",
+  };
+  if (gradDefs) {
+    return ["http://www.w3.org/2000/svg svg", svgAttrs, gradDefs, geometryEl];
+  }
+  return ["http://www.w3.org/2000/svg svg", svgAttrs, geometryEl];
 }
 
 /**