@beyondwork/docx-react-component 1.0.55 → 1.0.57

package/src/ui/WordReviewEditor.tsx

@@ -52,6 +52,7 @@ import type {
   SurfaceBlockSnapshot,
   SurfaceInlineSegment,
   TableOp,
+  CanonicalDocumentFragment,
   TableOpResult,
   PublicTableEvent,
   PublicTableRenderPlan,
@@ -480,6 +481,50 @@ function collectChartSnapshots(doc: CanonicalDocType): import("../api/public-typ
   return results;
 }
 
+/**
+ * Walk the canonical document, compute each chart_preview's stableChartId,
+ * and project a snapshot for the first matching id. Short-circuits on
+ * match so the happy path is O(k) in blocks-until-match rather than the
+ * O(N) the `collect().find()` fallback incurred for every ref call. For
+ * hosts that call `getChartSnapshot` in a tight loop over many chartIds,
+ * this reduces the cost from O(N²) to O(N·k).
+ */
+function lookupChartSnapshot(
+  doc: CanonicalDocType,
+  chartId: string,
+): import("../api/public-types").ChartSnapshot | null {
+  return lookupChartSnapshotInBlocks(doc.content.children, chartId);
+}
+
+function lookupChartSnapshotInBlocks(
+  blocks: CanonicalDocType["content"]["children"],
+  chartId: string,
+): import("../api/public-types").ChartSnapshot | null {
+  for (const block of blocks) {
+    if (block.type === "paragraph") {
+      for (const inline of block.children) {
+        if (inline.type === "chart_preview" && inline.parsedData) {
+          const id = stableChartId(inline.rawXml);
+          if (id === chartId) {
+            return projectChartSnapshot(id, inline.parsedData);
+          }
+        }
+      }
+    } else if (block.type === "table") {
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          const found = lookupChartSnapshotInBlocks(cell.children, chartId);
+          if (found) return found;
+        }
+      }
+    } else if (block.type === "sdt" || block.type === "custom_xml") {
+      const found = lookupChartSnapshotInBlocks(block.children, chartId);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
 function collectChartSnapshotsFromBlocks(
   blocks: CanonicalDocType["content"]["children"],
   results: import("../api/public-types").ChartSnapshot[],
@@ -528,6 +573,16 @@ export function __createWordReviewEditorRefBridge(
     redo: () => runtime.redo(),
     replaceText: (text, target, formatting) => runtime.replaceText(text, target, formatting),
     insertFragment: (fragment, target) => runtime.insertFragment(fragment, target),
+    copy: (target) => runtime.copy(target),
+    cut: (target) => runtime.cut(target),
+    getClipboardBuffer: () => runtime.getClipboardBuffer(),
+    getClipboardWireFormats: () => runtime.getClipboardWireFormats(),
+    selectObject: (objectId) => runtime.selectObject(objectId),
+    deselectObject: () => runtime.deselectObject(),
+    getGrabbedObject: () => runtime.getGrabbedObject(),
+    startAction: (name) => runtime.startAction(name),
+    endAction: () => runtime.endAction(),
+    isInAction: () => runtime.isInAction(),
     addComment: (params) => runtime.addComment(params),
     openComment: (commentId) => runtime.openComment(commentId),
     resolveComment: (commentId) => runtime.resolveComment(commentId),
@@ -554,11 +609,7 @@ export function __createWordReviewEditorRefBridge(
     getRenderSnapshot: () => clonePublicValue(runtime.getRenderSnapshot()),
     getCompatibilityReport: () => runtime.getCompatibilityReport(),
     getWarnings: () => runtime.getWarnings(),
-    getChartSnapshot: (chartId) => {
-      return collectChartSnapshots(runtime.getCanonicalDocument()).find(
-        (s) => s.chartId === chartId,
-      ) ?? null;
-    },
+    getChartSnapshot: (chartId) => lookupChartSnapshot(runtime.getCanonicalDocument(), chartId),
     getChartSnapshots: () => collectChartSnapshots(runtime.getCanonicalDocument()),
     getCommentSidebarSnapshot: () =>
       clonePublicValue(runtime.getRenderSnapshot().comments),
@@ -1528,6 +1579,16 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         redo: () => activeRuntime.redo(),
         replaceText: (text, target, formatting) => activeRuntime.replaceText(text, target, formatting),
         insertFragment: (fragment, target) => activeRuntime.insertFragment(fragment, target),
+        copy: (target) => activeRuntime.copy(target),
+        cut: (target) => activeRuntime.cut(target),
+        getClipboardBuffer: () => activeRuntime.getClipboardBuffer(),
+        getClipboardWireFormats: () => activeRuntime.getClipboardWireFormats(),
+        selectObject: (objectId) => activeRuntime.selectObject(objectId),
+        deselectObject: () => activeRuntime.deselectObject(),
+        getGrabbedObject: () => activeRuntime.getGrabbedObject(),
+        startAction: (name) => activeRuntime.startAction(name),
+        endAction: () => activeRuntime.endAction(),
+        isInAction: () => activeRuntime.isInAction(),
         addComment: (params) =>
           activeRuntime.addComment({
             ...params,
@@ -1584,9 +1645,7 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         getCompatibilityReport: () => activeRuntime.getCompatibilityReport(),
         getWarnings: () => activeRuntime.getWarnings(),
         getChartSnapshot: (chartId) =>
-          collectChartSnapshots(activeRuntime.getCanonicalDocument()).find(
-            (s) => s.chartId === chartId,
-          ) ?? null,
+          lookupChartSnapshot(activeRuntime.getCanonicalDocument(), chartId),
         getChartSnapshots: () => collectChartSnapshots(activeRuntime.getCanonicalDocument()),
         getCommentSidebarSnapshot: () =>
           clonePublicValue(activeRuntime.getRenderSnapshot().comments),
@@ -2777,10 +2836,84 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       onBlur: handleSurfaceBlur,
       onSelectionChange: dispatchSelection,
       onInsertText: (text: string) => dispatchTextCommand(activeRuntime, { type: "insert-text", text }, DISPATCH_CONTEXT),
-      onDeleteBackward: () => dispatchTextCommand(activeRuntime, { type: "delete-backward" }, DISPATCH_CONTEXT),
-      onDeleteForward: () => dispatchTextCommand(activeRuntime, { type: "delete-forward" }, DISPATCH_CONTEXT),
+      // v5 follow-up — Delete/Backspace when a grab is active (R.3
+      // ObjectGrabLayer). LO reference: `SwFEShell::DeleteSelection()` is
+      // grab-aware; without grab-awareness, Delete would run
+      // paragraph-delete on whichever paragraph the text caret happened to
+      // be in — a silent data-loss footgun.
+      //
+      // Minimum safe behavior until a proper `object.delete` runtime
+      // command + Lane 6 P11 chrome land: swallow the key (don't run
+      // paragraph-delete) and deselect the grab so the user can see that
+      // the key was recognized. The actual object removal follows when
+      // chrome wires resize/delete drag handles; this gate just prevents
+      // the paragraph-delete footgun.
+      onDeleteBackward: () => {
+        const grabbed = activeRuntime.getGrabbedObject();
+        if (grabbed) {
+          activeRuntime.deselectObject();
+          return;
+        }
+        dispatchTextCommand(activeRuntime, { type: "delete-backward" }, DISPATCH_CONTEXT);
+      },
+      onDeleteForward: () => {
+        const grabbed = activeRuntime.getGrabbedObject();
+        if (grabbed) {
+          activeRuntime.deselectObject();
+          return;
+        }
+        dispatchTextCommand(activeRuntime, { type: "delete-forward" }, DISPATCH_CONTEXT);
+      },
       onInsertTab: () => dispatchTextCommand(activeRuntime, { type: "insert-tab" }, DISPATCH_CONTEXT),
       onOutdentTab: () => dispatchTextCommand(activeRuntime, { type: "outdent-tab" }, DISPATCH_CONTEXT),
+      // I3 widening tail — Tab at last cell: dispatch `add-row-after` via the
+      // same table-structure-operation path every other row-insert caller uses
+      // (toolbar, context menu, ref method), so track-changes + collab replay
+      // stay consistent. See src/ui-tailwind/editor-surface/pm-command-bridge.ts
+      // `isAtLastCellOfTable` for the detection criterion.
+      onTableInsertRowBelow: () =>
+        applyRuntimeTableStructureOperation(activeRuntime, surfaceRef.current, {
+          type: "add-row-after",
+        }),
+      // I2 Tier B Slice 5 — drag-to-move / drag-to-copy.
+      // v5 close-out: bridge now emits `dragstart`/`dragend` so same-editor
+      // drag-to-move gets `sourceRange` populated. On move-effect drops we
+      // insert the fragment AND delete the source range — the full Word
+      // behavior. Both ops are wrapped in one action bracket via the
+      // auto-bracketing in insertFragment + our explicit startAction around
+      // the delete, so the undo history sees a single atomic action.
+      onDropFragment: (meta: {
+        fragment: CanonicalDocumentFragment;
+        effect: "move" | "copy";
+        sourceRange?: { from: number; to: number };
+      }) => {
+        if (meta.effect === "move" && meta.sourceRange) {
+          // Delete source FIRST, then insert at the drop position. This order
+          // is correctness-critical: if the drop was AFTER the source, the
+          // insertion would shift the source offsets forward and a subsequent
+          // delete would target the wrong (post-insertion) positions. By
+          // deleting first and letting `insertFragment` land on the current
+          // selection, both orderings behave correctly. The runtime's
+          // selection validator (R.5.b) clamps the drop-site selection if
+          // the source delete shifted it. Word degenerates move to copy
+          // when drop is inside source; we pass through unchanged.
+          activeRuntime.startAction("drag-move");
+          try {
+            activeRuntime.replaceText("", {
+              kind: "range",
+              from: meta.sourceRange.from,
+              to: meta.sourceRange.to,
+              assoc: { start: -1, end: 1 },
+            });
+            activeRuntime.insertFragment(meta.fragment);
+          } finally {
+            activeRuntime.endAction();
+          }
+        } else {
+          // Copy-effect OR external drag (no sourceRange) — just insert.
+          activeRuntime.insertFragment(meta.fragment);
+        }
+      },
       onInsertHardBreak: () => dispatchTextCommand(activeRuntime, { type: "insert-hard-break" }, DISPATCH_CONTEXT),
       onSplitParagraph: () => dispatchTextCommand(activeRuntime, { type: "split-paragraph" }, DISPATCH_CONTEXT),
       onUndo: () => activeRuntime.undo(),
@@ -2803,6 +2936,31 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
           source: meta.source,
         });
       },
+      // v5 close-out: wire rich-paste fragment routing to insertFragment so
+      // Office / HTML clipboard payloads land in the mounted editor. The
+      // insertFragment auto-bracket (R.5.a Phase 2) makes the paste a
+      // single-undo action.
+      onPasteFragment: (meta: {
+        fragment: CanonicalDocumentFragment;
+        source: "wordml" | "html";
+      }) => {
+        activeRuntime.insertFragment(meta.fragment);
+      },
+      // v5 close-out: image paste via existing insertImage ref method.
+      // Width/height are omitted so the renderer picks sensible defaults
+      // based on the decoded bitmap dimensions (existing insertImage
+      // behavior); hosts that need specific dimensions can intercept this
+      // callback on their own CommandBridgeCallbacks override.
+      onPasteImage: (meta: {
+        data: Uint8Array;
+        mimeType: string;
+        source: "paste" | "drop";
+      }) => {
+        applyRuntimeInsertImage(activeRuntime, {
+          data: meta.data,
+          mimeType: meta.mimeType,
+        });
+      },
     };
 
     const reviewCallbacks = {

package/src/ui/editor-runtime-boundary.ts

@@ -122,6 +122,12 @@ export interface WordReviewEditorRuntime extends DocumentRuntime {
   ): void;
 }
 
+type InternalWordReviewEditorRuntime = WordReviewEditorRuntime & {
+  hydrateChartPreviews?: (
+    resolvedDocument: EditorSessionState["canonicalDocument"],
+  ) => boolean;
+};
+
 type PackageBackedDocxSession = ReturnType<typeof loadDocxEditorSession>;
 
 interface SnapshotExportBarrier {
@@ -313,6 +319,9 @@ export function useEditorRuntimeBoundary(
   progressiveSurfaceRef.current = progressiveSurface;
   const runtimeRef = useRef<WordReviewEditorRuntime | null>(null);
   const pendingReadySourceRef = useRef<"docx" | "session" | "snapshot" | null>(null);
+  const activeLoadTokenRef = useRef<symbol | null>(null);
+  const pendingChartPreviewDocRef =
+    useRef<EditorSessionState["canonicalDocument"] | null>(null);
   const autosaveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const lastSavedRevisionTokenRef = useRef<string | null>(null);
   // Fastload P6: scheduler used by the DOM-side async docx loader. Held
@@ -386,6 +395,9 @@ export function useEditorRuntimeBoundary(
     async function loadRuntime(): Promise<void> {
       setLoadError(null);
       pendingReadySourceRef.current = null;
+      pendingChartPreviewDocRef.current = null;
+      const loadToken = Symbol(documentId);
+      activeLoadTokenRef.current = loadToken;
       if (autosaveTimerRef.current) {
         clearTimeout(autosaveTimerRef.current);
         autosaveTimerRef.current = null;
@@ -448,12 +460,34 @@ export function useEditorRuntimeBoundary(
             return;
           }
           recordPerfSample("loadSession.laycacheProbe");
+          const handleChartPreviewsReady = (
+            resolvedDocument: EditorSessionState["canonicalDocument"],
+          ): void => {
+            if (cancelled || activeLoadTokenRef.current !== loadToken) {
+              return;
+            }
+            pendingChartPreviewDocRef.current = resolvedDocument;
+            if (source.preloadedDocxSession) {
+              source.preloadedDocxSession.initialSessionState = {
+                ...source.preloadedDocxSession.initialSessionState,
+                canonicalDocument: resolvedDocument,
+              };
+              source.preloadedDocxSession.initialSnapshot = {
+                ...source.preloadedDocxSession.initialSnapshot,
+                canonicalDocument: resolvedDocument,
+              };
+            }
+            (
+              runtimeRef.current as InternalWordReviewEditorRuntime | null
+            )?.hydrateChartPreviews?.(resolvedDocument);
+          };
           const preloaded = await loadDocxEditorSessionAsync({
             documentId,
             sourceLabel: source.sourceLabel,
             bytes: source.initialDocx,
             editorBuild: "dev",
             scheduler,
+            onChartPreviewsReady: handleChartPreviewsReady,
             ...(probeResult ? { laycacheEnvelope: probeResult.envelope } : {
               // C2c: on the cold path (no cached envelope), emit the first
               // viewport surface as soon as body-normalize completes so the
@@ -475,6 +509,16 @@ export function useEditorRuntimeBoundary(
             return;
           }
           source.preloadedDocxSession = preloaded;
+          if (pendingChartPreviewDocRef.current) {
+            source.preloadedDocxSession.initialSessionState = {
+              ...source.preloadedDocxSession.initialSessionState,
+              canonicalDocument: pendingChartPreviewDocRef.current,
+            };
+            source.preloadedDocxSession.initialSnapshot = {
+              ...source.preloadedDocxSession.initialSnapshot,
+              canonicalDocument: pendingChartPreviewDocRef.current,
+            };
+          }
           if (probeResult) {
             source.preloadedLaycacheGraph = probeResult.envelope.graph;
           }
@@ -499,6 +543,11 @@ export function useEditorRuntimeBoundary(
         );
         recordPerfSample("runtime.create");
         runtimeRef.current = nextRuntime;
+        if (pendingChartPreviewDocRef.current) {
+          (
+            nextRuntime as InternalWordReviewEditorRuntime
+          ).hydrateChartPreviews?.(pendingChartPreviewDocRef.current);
+        }
         pendingReadySourceRef.current = source.source;
         // C2c: clear the transient progressive surface — the full runtime
         // snapshot supersedes it. No need for startTransition here since
@@ -530,6 +579,8 @@ export function useEditorRuntimeBoundary(
 
     return () => {
       cancelled = true;
+      pendingChartPreviewDocRef.current = null;
+      activeLoadTokenRef.current = null;
     };
   }, [
     documentId,
@@ -753,6 +804,11 @@ function createRuntime(
     defaultAuthorId: args.currentUserId,
     onCommandApplied: args.commandAppliedBridge?.onCommandApplied,
   });
+  const internalBaseRuntime = baseRuntime as DocumentRuntime & {
+    hydrateCanonicalDocumentInternally?: (
+      document: EditorSessionState["canonicalDocument"],
+    ) => boolean;
+  };
 
   // Schema 1.2: drive load-path hydration from the parsed envelope.
   if (docxSession?.initialEditorStatePayload) {
@@ -784,7 +840,7 @@ function createRuntime(
     });
   }
 
-  const runtime: WordReviewEditorRuntime = Object.assign(baseRuntime, {
+  const runtime: InternalWordReviewEditorRuntime = Object.assign(baseRuntime, {
     drainBootstrapEvents: () => bootstrapEvents.splice(0, bootstrapEvents.length),
     emitBlockedCommand: (
       command: string,
@@ -802,6 +858,25 @@ function createRuntime(
         },
       });
     },
+    hydrateChartPreviews: (
+      resolvedDocument: EditorSessionState["canonicalDocument"],
+    ): boolean => {
+      if (docxSession) {
+        docxSession.initialSessionState = {
+          ...docxSession.initialSessionState,
+          canonicalDocument: resolvedDocument,
+        };
+        docxSession.initialSnapshot = {
+          ...docxSession.initialSnapshot,
+          canonicalDocument: resolvedDocument,
+        };
+      }
+      return (
+        internalBaseRuntime.hydrateCanonicalDocumentInternally?.(
+          resolvedDocument,
+        ) ?? false
+      );
+    },
   });
 
   return runtime;
@@ -947,8 +1022,21 @@ function createLoadingRuntimeBridge(input: {
     },
     getCanonicalDocument: () => input.sessionState.canonicalDocument,
     getSourcePackage: () => input.sessionState.sourcePackage,
+    getFontTable: () => input.sessionState.canonicalDocument.fontTable,
+    getFontEntry: (name: string) =>
+      input.sessionState.canonicalDocument.fontTable?.fonts[name],
     replaceText: () => undefined,
     insertFragment: () => undefined,
+    copy: () => undefined,
+    cut: () => undefined,
+    getClipboardBuffer: () => null,
+    getClipboardWireFormats: () => null,
+    selectObject: () => undefined,
+    deselectObject: () => undefined,
+    getGrabbedObject: () => null,
+    startAction: () => undefined,
+    endAction: () => undefined,
+    isInAction: () => false,
     applyActiveStoryTextCommand: () => ({
       kind: "rejected",
       newRevisionToken: "",
@@ -1016,6 +1104,11 @@ function createLoadingRuntimeBridge(input: {
       changeKinds: ["content"],
     }),
     getFieldSnapshot: () => emptyFieldSnapshot,
+    getFieldResolver: () => ({
+      resolve: () => undefined,
+      cacheKey: "loading",
+    }),
+    getFootnoteResolver: () => undefined,
     updateFields: () => emptyFieldResult,
     updateTableOfContents: () => emptyTocResult,
     getSessionState: () => {

package/src/ui/editor-shell-view.tsx

@@ -154,7 +154,7 @@ export function EditorShellView(props: EditorShellViewProps) {
       aria-describedby={`${accessibilityInstructionsId} ${accessibilityStatusId}${
         diagnosticsModeMessage ? ` ${accessibilityAlertId}` : ""
       }`}
-      className="relative h-full"
+      className="wre-editor relative h-full"
       onKeyDownCapture={onShellKeyDownCapture}
     >
       <p id={accessibilityInstructionsId} style={visuallyHiddenStyles}>

package/src/ui/runtime-shortcut-dispatch.ts

@@ -19,6 +19,14 @@ export interface ShellShortcutContext {
 
 export interface SurfaceShortcutContext {
   inTable: boolean;
+  /**
+   * I3 widening tail — when the caret is in the last cell of the last row of
+   * a table, Tab (without shift) triggers implicit row-insert-below instead
+   * of cell navigation. Matches Word's Tab-at-table-tail behavior. Flag is
+   * computed by the PM bridge at dispatch time (bridge knows cell position);
+   * defaults to false for callers that don't supply it.
+   */
+  isAtTableTail?: boolean;
 }
 
 export type ShellShortcutResolution =
@@ -46,6 +54,7 @@ export type SurfaceShortcutResolution =
   | { kind: "insert-tab" }
   | { kind: "outdent-tab" }
   | { kind: "navigate-table-cell"; direction: 1 | -1 }
+  | { kind: "table-insert-row-below" }
   | { kind: "history"; history: "undo" | "redo" };
 
 export function resolveShellShortcut(
@@ -190,9 +199,14 @@ export function resolveSurfaceShortcut(
   }
 
   if (key === "tab" && !hasAnyModifiers(input)) {
-    return context.inTable
-      ? { kind: "navigate-table-cell", direction: 1 }
-      : { kind: "insert-tab" };
+    if (context.inTable) {
+      // I3 widening tail — Tab at the last cell inserts a new row below
+      // (Word behavior). Shift+Tab continues to navigate regardless.
+      return context.isAtTableTail
+        ? { kind: "table-insert-row-below" }
+        : { kind: "navigate-table-cell", direction: 1 };
+    }
+    return { kind: "insert-tab" };
   }
 
   return { kind: "none" };

package/src/ui-tailwind/chart/ChartSurface.tsx

@@ -24,7 +24,7 @@
 import React from "react";
 import type { ChartModel } from "../../io/ooxml/chart/types.ts";
 import type { ResolvedTheme } from "../../model/canonical-document.ts";
-import { layoutPlotArea, type PlotAreaLayout } from "./layout/plot-area.ts";
+import { layoutPlotArea, CHROME_PAINTED_DEFAULT, type PlotAreaLayout } from "./layout/plot-area.ts";
 import { AreaChart } from "./render/area.tsx";
 import { BarColumnChart } from "./render/bar-column.tsx";
 import { BubbleChart } from "./render/bubble.tsx";
@@ -63,7 +63,15 @@ function ChartSurfaceImpl({
   resolveMediaUrl,
   previewMediaId,
 }: ChartSurfaceProps): React.ReactElement {
-  const resolvedLayout = layout ?? layoutPlotArea({ w: width, h: height }, model, theme);
+  // Graceful degradation: pass CHROME_PAINTED_DEFAULT so title / legend /
+  // axis bands are NOT reserved by the layout pass. No component paints
+  // them today (documented gap in docs/wiki/images-and-media.md §"Known
+  // gaps"), so reserving space would leave empty margins around the plot.
+  // When Stage-C chrome wire-up lands, flip the matching flag here.
+  const resolvedLayout =
+    layout ?? layoutPlotArea({ w: width, h: height }, model, theme, {
+      paintedChrome: CHROME_PAINTED_DEFAULT,
+    });
   const defs = new DefsRegistry();
 
   const body = dispatchBody({
@@ -187,20 +195,38 @@ function renderDefs(defs: DefsRegistry): React.ReactElement[] {
 
 /**
  * Convert a gradient angle (degrees, OOXML clockwise-from-horizontal)
- * to SVG `x1/y1/x2/y2` percentage values. 0° = left-to-right,
- * 90° = top-to-bottom.
+ * to SVG `x1/y1/x2/y2` percentage values on the object bounding box.
+ * 0° = left-to-right, 90° = top-to-bottom. Returned percentages are
+ * continuous in the angle rather than snapped to the four corners —
+ * non-cardinal gradients (45°, 60°, 120°, …) render with the correct
+ * direction instead of collapsing to the nearest corner-pair.
  */
 function angleToCoords(angleDeg: number): {
   x1: string; y1: string; x2: string; y2: string;
 } {
-  const rad = (angleDeg * Math.PI) / 180;
+  const normalized = ((angleDeg % 360) + 360) % 360;
+  const rad = (normalized * Math.PI) / 180;
   const dx = Math.cos(rad);
   const dy = Math.sin(rad);
-  const x1 = dx < 0 ? "100%" : "0%";
-  const x2 = dx < 0 ? "0%" : "100%";
-  const y1 = dy < 0 ? "100%" : "0%";
-  const y2 = dy < 0 ? "0%" : "100%";
-  return { x1, y1, x2, y2 };
+
+  // Center + half-length projection onto the [0,1]² bounding box. Scale
+  // so the dominant component reaches 0.5 (half the box side), keeping
+  // the gradient within the object bbox and edge-to-edge along the axis.
+  const cx = 0.5;
+  const cy = 0.5;
+  const absDx = Math.abs(dx);
+  const absDy = Math.abs(dy);
+  const scale = absDx === 0 && absDy === 0 ? 0 : 0.5 / Math.max(absDx, absDy);
+  const hx = dx * scale;
+  const hy = dy * scale;
+
+  const fmtPct = (n: number): string => `${(n * 100).toFixed(2)}%`;
+  return {
+    x1: fmtPct(cx - hx),
+    y1: fmtPct(cy - hy),
+    x2: fmtPct(cx + hx),
+    y2: fmtPct(cy + hy),
+  };
 }
 
 // ---------------------------------------------------------------------------