@beyondwork/docx-react-component 1.0.56 → 1.0.57

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.56",
+  "version": "1.0.57",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
   "packageManager": "pnpm@10.30.3",
   "type": "module",

package/src/api/public-types.ts

@@ -717,11 +717,17 @@ export type SnapshotRefreshChangeKind =
   | "structure"
   | "checkpoint";
 
+export interface TocRefreshTrigger {
+  headingContentChanged: boolean;
+  headingStructureChanged: boolean;
+}
+
 export interface SnapshotRefreshHints {
   invalidate: SnapshotRefreshInvalidateTarget[];
   staleTargets: SnapshotRefreshStaleTarget[];
   changeKinds: SnapshotRefreshChangeKind[];
   checkpointType?: "session" | "snapshot" | "export";
+  tocRefreshTrigger?: TocRefreshTrigger;
 }
 
 export interface StyleCatalogEntrySnapshot {
@@ -798,6 +804,45 @@ export type SurfaceTextMark =
   | "smallCaps"
   | "allCaps";
 
+/**
+ * V2c.4 / V2c.5 — DrawingFrame anchor geometry projected onto image + shape
+ * segments. Mirrors the canonical `AnchorGeometry` shape (defined in
+ * `src/model/canonical-document.ts`) with the fields chrome consumers need
+ * for float-wrap (Lane 6d N9), object-selection chrome (N6), and frame
+ * positioning. EMU values are kept verbatim — converters that need px
+ * apply 9525 EMU = 1 px at 96 dpi.
+ */
+export interface SurfaceDrawingAnchor {
+  display: "inline" | "floating";
+  wrapMode: "none" | "square" | "tight" | "through" | "topAndBottom";
+  extent: { widthEmu: number; heightEmu: number };
+  positionH?: { relativeFrom: string; align?: string; offset?: number };
+  positionV?: { relativeFrom: string; align?: string; offset?: number };
+  distMargins?: { top?: number; bottom?: number; left?: number; right?: number };
+  relativeHeight?: number;
+  behindDoc?: boolean;
+  layoutInCell?: boolean;
+  allowOverlap?: boolean;
+  simplePos?: boolean;
+  /** docPr.id / .name / .descr — used for accessibility chrome and selection labels. */
+  docPr?: { id: string; name?: string; descr?: string };
+}
+
+/**
+ * V2c.4 — Picture-effect data (crop, rotation, flip, preset clip geometry).
+ * `srcRect` percentages match OOXML's `a:srcRect` semantics: 0 = no crop,
+ * 100 000 = fully cropped from that edge.  `rotation` is in 60 000ths of a
+ * degree (OOXML `a:xfrm a:rot`).
+ */
+export interface SurfacePictureEffects {
+  srcRect?: { top: number; bottom: number; left: number; right: number };
+  rotation?: number;
+  flipH?: boolean;
+  flipV?: boolean;
+  presetGeom?: string;
+  stretch?: boolean;
+}
+
 export type SurfaceInlineSegment =
   | {
       segmentId: string;
@@ -836,6 +881,19 @@ export type SurfaceInlineSegment =
       state: "editable" | "missing";
       display?: "inline" | "floating";
       detail?: string;
+      /**
+       * V2c.4 — DrawingFrame anchor geometry surfaced for Lane 6d float-wrap
+       * (P7) and chrome consumers. Present only when the canonical model
+       * carries non-trivial anchor metadata; inline pictures with default
+       * positioning omit it so the simple-image path stays cheap.
+       */
+      anchor?: SurfaceDrawingAnchor;
+      /**
+       * V2c.4 — Picture-effect data (crop, rotation, flip, preset geometry).
+       * Absent when none of the underlying `PictureContent` effect fields
+       * are set, so consumers can fast-path image rendering when undefined.
+       */
+      pictureEffects?: SurfacePictureEffects;
     }
   | {
       segmentId: string;
@@ -886,6 +944,44 @@ export type SurfaceInlineSegment =
       instruction: string;
       refreshStatus: FieldRefreshStatus;
       label: string;
+    }
+  | {
+      /**
+       * V2c.5 — DrawingFrame shape segment.  Replaces the `complex_preview`
+       * fallback that used to swallow `wps:wsp` shapes.  Carries the
+       * geometry preset, fill/line, optional textbox flag + first-paragraph
+       * preview, and (for floating shapes) anchor geometry.  Lane 6d's N10
+       * shape rendering consumes this segment.
+       */
+      segmentId: string;
+      kind: "shape";
+      from: number;
+      to: number;
+      label: string;
+      detail: string;
+      anchor?: SurfaceDrawingAnchor;
+      geometry?: string;
+      fill?:
+        | { kind: "solid"; color: string; colorType: "srgbClr" | "schemeClr" }
+        | { kind: "none" }
+        | {
+            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;
+          }
+        | {
+            kind: "pattern";
+            preset: string;
+            fg?: { color: string; colorType: "srgbClr" | "schemeClr" };
+            bg?: { color: string; colorType: "srgbClr" | "schemeClr" };
+          };
+      line?: { color?: string; widthEmu?: number; noLine?: boolean };
+      isTextBox?: boolean;
+      /** First-paragraph plain-text preview when `isTextBox` is true. */
+      txbxText?: string;
     };
 
 export interface SurfaceTableCellSnapshot {
@@ -2563,6 +2659,12 @@ export type WordReviewEditorEvent =
       documentId: string;
       activeStory: EditorStoryTarget;
     }
+  | {
+      type: "toc_auto_refreshed";
+      documentId: string;
+      entryCount: number;
+      trigger: TocRefreshTrigger;
+    }
   | {
       type: "warning_added";
       documentId: string;
@@ -3060,6 +3162,61 @@ export interface WordReviewEditorRef {
    * add merge-intent + richer caret placement as paste parsers come online.
    */
   insertFragment(fragment: CanonicalDocumentFragment, target?: EditorAnchorProjection): void;
+  /**
+   * I2 Tier B Slice 4b — serialize `target` (or the current selection) to a
+   * `CanonicalDocumentFragment` and store it in the editor's internal
+   * clipboard buffer. No document mutation.
+   */
+  copy(target?: EditorAnchorProjection): void;
+  /**
+   * I2 Tier B Slice 4b — `copy(target)` + delete the range.
+   */
+  cut(target?: EditorAnchorProjection): void;
+  /**
+   * I2 Tier B Slice 4b — return the last fragment written by `cut` / `copy`,
+   * or `null` if none has been captured yet. Hosts pair this with
+   * `insertFragment` to implement paste while Slice 4b's async-Clipboard-API
+   * write lands with Slice 5.
+   */
+  getClipboardBuffer(): CanonicalDocumentFragment | null;
+  /**
+   * v5 close-out — return the current clipboard buffer serialized to the
+   * wire formats browsers/Word accept, or `null` when no clipboard op has
+   * been performed. Hosts use this inside their own DOM `copy`/`cut` event
+   * handler to feed `navigator.clipboard.write` (the editor does not
+   * install the DOM handler itself).
+   */
+  getClipboardWireFormats(): { wordml: string; html: string; plainText: string } | null;
+  /**
+   * R.3 ObjectGrabLayer — grab an inline / floating object (image, shape)
+   * by its stable id. Single-select; replaces any previously grabbed
+   * object. Lane 6 P11 chrome reads the grab state to paint handles.
+   */
+  selectObject(objectId: string): void;
+  /**
+   * R.3 — release the grabbed object, if any. Safe to call when nothing
+   * is grabbed.
+   */
+  deselectObject(): void;
+  /**
+   * R.3 — return the grabbed object's id, or `null` when nothing is
+   * grabbed.
+   */
+  getGrabbedObject(): string | null;
+  /**
+   * R.5.a — open an action bracket. Hosts wrap compound edits (paste,
+   * cut+paste, agent suggestion-apply) so snapshot emission + collab
+   * broadcast + undo grouping see them as a single action.
+   *
+   * Phase 1: opt-in. Existing commands do not auto-bracket. Hosts that
+   * want single-undo paste call `startAction("paste")` →
+   * `insertFragment(fragment)` → `endAction()`.
+   */
+  startAction(name: string): void;
+  /** R.5.a — close one level of action bracketing. Unbalanced calls are no-ops. */
+  endAction(): void;
+  /** R.5.a — `true` when the runtime is inside one or more action brackets. */
+  isInAction(): boolean;
   toggleBulletedList(): void;
   toggleNumberedList(): void;
   toggleBold(): void;

package/src/compare/diff-engine.ts

@@ -522,6 +522,7 @@ function getInlineLength(node: InlineNode): number {
     case "shape":
     case "wordart":
     case "vml_shape":
+    case "drawing_frame":
       return 1;
   }
 }
@@ -581,6 +582,8 @@ function getInlineDisplayText(node: InlineNode): string {
       return node.text;
     case "vml_shape":
       return node.text ?? "[VML Shape]";
+    case "drawing_frame":
+      return node.content.type === "picture" ? "[Image]" : "[Drawing]";
   }
 }
 

package/src/core/commands/formatting-commands.ts

@@ -1040,6 +1040,7 @@ function inlineNodeLength(node: InlineNode): number {
     case "shape":
     case "wordart":
     case "vml_shape":
+    case "drawing_frame":
       return 1;
     case "field":
       return node.children.reduce<number>(

package/src/core/commands/index.ts

@@ -89,7 +89,8 @@ import {
   setHeaderFooterLinkAtSectionIndex,
 } from "./section-layout-commands.ts";
 import { insertPageBreak, insertTable } from "./text-commands.ts";
-import { applyFragmentInsert } from "../../runtime/structure-ops/fragment-insert.ts";
+import { editLayer } from "../../runtime/edit-ops/index.ts";
+import { structureLayer } from "../../runtime/structure-ops/index.ts";
 import type { TableSelectionDescriptor } from "../../runtime/table-commands.ts";
 
 export type ContentChildrenPatch =
@@ -575,8 +576,10 @@ export function executeEditorCommand(
         ? applySuggestingInsert(state, command.text, context)
         : undefined;
       if (suggestingResult) return suggestingResult;
+      // R.2 — dispatch via the named EditLayer entry point so the seam is the
+      // single site where R.5.a/b hooks will attach.
       return applyTextCommand(state, context.timestamp, (document, selection) =>
-        insertText(document, selection, command.text, context, command.formatting),
+        editLayer.applyTextInsert(document, selection, command.text, context, command.formatting),
       );
     }
     case "text.delete-backward": {
@@ -585,7 +588,7 @@ export function executeEditorCommand(
         : undefined;
       if (suggestingResult) return suggestingResult;
       return applyTextCommand(state, context.timestamp, (document, selection) =>
-        deleteSelectionOrBackward(document, selection, context),
+        editLayer.applyDeleteBackward(document, selection, context),
       );
     }
     case "text.delete-forward": {
@@ -594,7 +597,7 @@ export function executeEditorCommand(
         : undefined;
       if (suggestingResult) return suggestingResult;
       return applyTextCommand(state, context.timestamp, (document, selection) =>
-        deleteSelectionOrForward(document, selection, context),
+        editLayer.applyDeleteForward(document, selection, context),
       );
     }
     case "text.insert-tab": {
@@ -603,7 +606,7 @@ export function executeEditorCommand(
         : undefined;
       if (suggestingResult) return suggestingResult;
       return applyTextCommand(state, context.timestamp, (document, selection) =>
-        insertTab(document, selection, context),
+        editLayer.applyInsertTab(document, selection, context),
       );
     }
     case "text.outdent-tab": {
@@ -632,7 +635,7 @@ export function executeEditorCommand(
         : undefined;
       if (suggestingResult) return suggestingResult;
       return applyTextCommand(state, context.timestamp, (document, selection) =>
-        insertHardBreak(document, selection, context),
+        editLayer.applyInsertHardBreak(document, selection, context),
       );
     }
     case "paragraph.split":
@@ -641,15 +644,18 @@ export function executeEditorCommand(
         if (suggestingResult) return suggestingResult;
       }
       return applyTextCommand(state, context.timestamp, (document, selection) =>
-        splitParagraph(document, selection, context),
+        editLayer.applySplitParagraph(document, selection, context),
       );
     case "fragment.insert": {
-      // I2 Tier B Slice 1 — route through the structure-ops splicer. No
+      // I2 Tier B Slice 1 + R.3 — route through the StructureLayer seam. No
       // suggesting-mode branch yet; fragment insertion always lands as a direct
       // edit. Future slices will gate behind track-changes when a fixture needs it.
-      const result = applyFragmentInsert(state.document, state.selection, command.fragment, {
-        timestamp: context.timestamp,
-      });
+      const result = structureLayer.applyFragmentInsert(
+        state.document,
+        state.selection,
+        command.fragment,
+        { timestamp: context.timestamp },
+      );
       return buildDocumentReplaceTransaction(state, context, result);
     }
     case "runtime.set-read-only":

package/src/core/selection/mapping.ts

@@ -31,7 +31,24 @@ export interface DetachedAnchor {
   reason: "deleted" | "invalidatedByStructureChange" | "importAmbiguity";
 }
 
-export type EditorAnchorProjection = RangeAnchor | NodeAnchor | DetachedAnchor;
+/**
+ * Internal representation of an anchor projection — uses `DocRange` so
+ * mapping helpers compose ranges independently of assoc semantics. The
+ * public-facing shape lives at `src/api/public-types.ts` (same simple name
+ * `EditorAnchorProjection`) and is flat (`{ kind: "range", from, to, assoc }`).
+ * Conversion between the two goes through `src/core/selection/anchor-conversion.ts`.
+ */
+export type InternalEditorAnchorProjection = RangeAnchor | NodeAnchor | DetachedAnchor;
+
+/**
+ * @deprecated X3 Phase 5 — prefer `InternalEditorAnchorProjection` to avoid
+ * name-collision with the public `EditorAnchorProjection` from
+ * `src/api/public-types.ts`. Internal call-sites have migrated (via
+ * `import type { EditorAnchorProjection as InternalEditorAnchorProjection }`
+ * aliasing in `document-runtime.ts`). This alias stays for one release cycle
+ * so third-party internal consumers don't break. Remove in v2.1+.
+ */
+export type EditorAnchorProjection = InternalEditorAnchorProjection;
 
 export interface MappingStep {
   from: Position;

package/src/core/selection/review-anchors.ts

@@ -104,17 +104,22 @@ export function rangeStaysWithinSingleParagraph(
 }
 
 /**
- * I8 — "mid-run-near-table" guard. Comment anchors whose endpoints
- * land strictly inside a paragraph that sits adjacent to a table
- * block are rejected: the serializer's per-paragraph offset walker
- * (Lane 3 §O8) produces invalid OOXML for these anchors. Removed
- * once O8 ships.
+ * Width of the paragraph-to-table proximity window used by
+ * `snapCommentAnchorAwayFromTable` to decide when to nudge endpoints to
+ * paragraph boundaries. Originally the I8 rejection threshold before Lane 3b
+ * §O8 shipped; now used only by the (opt-in) snap helper for hosts that
+ * prefer clean anchors.
  */
 export const TABLE_ADJACENT_WINDOW = 1;
 
-export type CommentAnchorRejectionReason =
-  | "invalid_comment_anchor"
-  | "comment_anchor_table_adjacent";
+/**
+ * I8 guard removal (post-O8) — the `comment_anchor_table_adjacent` rejection
+ * reason has been retired now that Lane 3b §O8 fixed the serializer's
+ * per-paragraph offset walker. The type alias remains as a deprecated union
+ * stub so existing host code that narrows on it keeps compiling; new code
+ * should simply check against `"invalid_comment_anchor"`.
+ */
+export type CommentAnchorRejectionReason = "invalid_comment_anchor";
 
 export function canCreateDocxCommentAnchor(
   content: unknown,
@@ -140,17 +145,18 @@ export function commentAnchorRejectionReason(
     return "invalid_comment_anchor";
   }
 
-  if (rangeLandsMidRunNearTableBoundary(content, normalized)) {
-    return "comment_anchor_table_adjacent";
-  }
-
+  // I8 branch removed — mid-run-near-table anchors now serialize cleanly
+  // via Lane 3b §O8's `walkInlineNodeForBoundaries` fix.
   return null;
 }
 
 /**
- * I8.3 — Snap a rejected mid-run-near-table anchor to paragraph
- * boundaries so downstream serialization stays safe. Returns `null`
- * if the anchor cannot be rescued (e.g. crosses an opaque block).
+ * Snap a mid-run-near-table anchor to paragraph boundaries when a host opts
+ * into `snapToSafeBoundary`. Originally a defensive workaround for the pre-O8
+ * serializer bug; now a boundary-preference convenience for hosts that dislike
+ * mid-run comment anchors on principle. Returns `null` if the anchor cannot
+ * be rescued (e.g. crosses an opaque block); returns the input unchanged if
+ * it doesn't need snapping.
  */
 export function snapCommentAnchorAwayFromTable(
   content: unknown,
@@ -161,9 +167,14 @@ export function snapCommentAnchorAwayFromTable(
   const normalized = normalizeRange(anchor.range);
   if (normalized.from === normalized.to) return null;
 
-  const reason = commentAnchorRejectionReason(content, anchor);
-  if (reason === null) return anchor;
-  if (reason !== "comment_anchor_table_adjacent") return null;
+  // If the anchor is already flagged invalid for other reasons (crosses an
+  // opaque block, etc.) we can't rescue it by snapping.
+  if (commentAnchorRejectionReason(content, anchor) !== null) return null;
+
+  // Detect mid-run-near-table via structural check directly (independent of
+  // rejection reason — the rejection branch is gone post-O8). If the anchor
+  // doesn't need snapping, pass it through unchanged.
+  if (!rangeLandsMidRunNearTableBoundary(content, normalized)) return anchor;
 
   const surfaceBlocks = readSurfaceBlocks(content);
   if (!surfaceBlocks) return null;

package/src/io/chart-preview-resolver.ts

@@ -74,7 +74,8 @@ interface PendingResolution {
   readonly heightEmu: number;
 }
 
-type Pointer = Array<number>;
+type PointerStep = number | { rowIndex: number; cellIndex: number };
+type Pointer = PointerStep[];
 
 export async function resolveChartPreviewsForDocument(
   doc: CanonicalDocument,
@@ -189,30 +190,92 @@ export function scheduleChartPreviewResolution(
 function collectUnresolvedChartPreviews(doc: CanonicalDocument, pkg: OpcPackage): PendingResolution[] {
   const out: PendingResolution[] = [];
   const documentRels = collectDocumentPartRelationships(pkg);
+  collectUnresolvedChartPreviewsFromBlocks(
+    doc.content.children,
+    [],
+    documentRels,
+    pkg,
+    out,
+  );
+  return out;
+}
 
-  const paragraphs = doc.content.children;
-  for (let i = 0; i < paragraphs.length; i++) {
-    const block = paragraphs[i]!;
-    if (block.type !== "paragraph") continue;
-    const paragraph = block as ParagraphNode;
-    for (let j = 0; j < paragraph.children.length; j++) {
-      const child = paragraph.children[j];
-      if (!child || child.type !== "chart_preview") continue;
-      const chartNode = child as ChartPreviewNode;
-      if (chartNode.previewMediaId) continue;
-      const resolved = resolveChartPart(chartNode, documentRels, pkg);
-      if (!resolved) continue;
-      out.push({
-        pointer: [i, j],
-        node: chartNode,
-        chartPartPath: resolved.chartPartPath,
-        chartXml: resolved.chartXml,
-        widthEmu: resolved.widthEmu,
-        heightEmu: resolved.heightEmu,
-      });
+function collectUnresolvedChartPreviewsFromBlocks(
+  blocks: readonly BlockNode[],
+  pointerPrefix: Pointer,
+  documentRels: Map<string, string>,
+  pkg: OpcPackage,
+  out: PendingResolution[],
+): void {
+  for (let blockIndex = 0; blockIndex < blocks.length; blockIndex += 1) {
+    const block = blocks[blockIndex];
+    if (!block) continue;
+    switch (block.type) {
+      case "paragraph":
+        collectUnresolvedChartPreviewsFromParagraph(
+          block,
+          [...pointerPrefix, blockIndex],
+          documentRels,
+          pkg,
+          out,
+        );
+        break;
+      case "table":
+        for (let rowIndex = 0; rowIndex < block.rows.length; rowIndex += 1) {
+          const row = block.rows[rowIndex];
+          if (!row) continue;
+          for (let cellIndex = 0; cellIndex < row.cells.length; cellIndex += 1) {
+            const cell = row.cells[cellIndex];
+            if (!cell) continue;
+            collectUnresolvedChartPreviewsFromBlocks(
+              cell.children,
+              [...pointerPrefix, blockIndex, { rowIndex, cellIndex }],
+              documentRels,
+              pkg,
+              out,
+            );
+          }
+        }
+        break;
+      case "sdt":
+      case "custom_xml":
+        collectUnresolvedChartPreviewsFromBlocks(
+          block.children,
+          [...pointerPrefix, blockIndex],
+          documentRels,
+          pkg,
+          out,
+        );
+        break;
+      default:
+        break;
     }
   }
-  return out;
+}
+
+function collectUnresolvedChartPreviewsFromParagraph(
+  paragraph: ParagraphNode,
+  pointerPrefix: Pointer,
+  documentRels: Map<string, string>,
+  pkg: OpcPackage,
+  out: PendingResolution[],
+): void {
+  for (let childIndex = 0; childIndex < paragraph.children.length; childIndex += 1) {
+    const child = paragraph.children[childIndex];
+    if (!child || child.type !== "chart_preview") continue;
+    const chartNode = child as ChartPreviewNode;
+    if (chartNode.previewMediaId) continue;
+    const resolved = resolveChartPart(chartNode, documentRels, pkg);
+    if (!resolved) continue;
+    out.push({
+      pointer: [...pointerPrefix, childIndex],
+      node: chartNode,
+      chartPartPath: resolved.chartPartPath,
+      chartXml: resolved.chartXml,
+      widthEmu: resolved.widthEmu,
+      heightEmu: resolved.heightEmu,
+    });
+  }
 }
 
 function collectDocumentPartRelationships(pkg: OpcPackage): Map<string, string> {
@@ -323,7 +386,7 @@ function applyResolutions(
   resolutions: Array<{ entry: PendingResolution; bytes: Uint8Array }>,
 ): CanonicalDocument {
   const newMediaItems: Record<string, MediaItem> = { ...doc.media.items };
-  const updates = new Map<string, { previewMediaId: string }>();
+  let newBlocks = doc.content.children;
 
   let seq = 0;
   for (const { entry, bytes } of resolutions) {
@@ -340,31 +403,102 @@ function applyResolutions(
       widthEmu: entry.widthEmu,
       heightEmu: entry.heightEmu,
     };
-    const pointerKey = entry.pointer.join(",");
-    updates.set(pointerKey, { previewMediaId: mediaId });
+    newBlocks = updateChartPreviewAtPointer(newBlocks, entry.pointer, mediaId);
   }
 
-  if (updates.size === 0) return doc;
-
-  // Clone the content tree along pointer paths only — everything else
-  // keeps object identity so downstream React memoization stays stable.
-  const newParagraphs: BlockNode[] = doc.content.children.slice();
-  for (const [pointerKey, update] of updates) {
-    const [pi, ci] = pointerKey.split(",").map((s) => parseInt(s, 10)) as [number, number];
-    const paragraph = newParagraphs[pi];
-    if (!paragraph || paragraph.type !== "paragraph") continue;
-    const newChildren: InlineNode[] = (paragraph as ParagraphNode).children.slice();
-    const existing = newChildren[ci];
-    if (!existing || existing.type !== "chart_preview") continue;
-    newChildren[ci] = { ...(existing as ChartPreviewNode), previewMediaId: update.previewMediaId };
-    newParagraphs[pi] = { ...(paragraph as ParagraphNode), children: newChildren };
-  }
+  if (newBlocks === doc.content.children) return doc;
 
-  const newContent: DocumentRootNode = { ...doc.content, children: newParagraphs };
+  const newContent: DocumentRootNode = { ...doc.content, children: newBlocks };
   const newMedia = { items: newMediaItems };
   return { ...doc, content: newContent, media: newMedia };
 }
 
+function updateChartPreviewAtPointer(
+  blocks: readonly BlockNode[],
+  pointer: Pointer,
+  previewMediaId: string,
+): BlockNode[] {
+  if (pointer.length < 2) return blocks as BlockNode[];
+  const [head, ...rest] = pointer;
+  if (typeof head !== "number") return blocks as BlockNode[];
+  const targetBlock = blocks[head];
+  if (!targetBlock) return blocks as BlockNode[];
+
+  switch (targetBlock.type) {
+    case "paragraph": {
+      if (rest.length !== 1 || typeof rest[0] !== "number") {
+        return blocks as BlockNode[];
+      }
+      const inlineIndex = rest[0];
+      const child = targetBlock.children[inlineIndex];
+      if (!child || child.type !== "chart_preview") return blocks as BlockNode[];
+      const nextChildren: InlineNode[] = targetBlock.children.slice();
+      nextChildren[inlineIndex] = {
+        ...(child as ChartPreviewNode),
+        previewMediaId,
+      };
+      const nextBlocks = blocks.slice();
+      nextBlocks[head] = {
+        ...targetBlock,
+        children: nextChildren,
+      };
+      return nextBlocks;
+    }
+    case "table": {
+      const [cellPointer, ...nested] = rest;
+      if (
+        !cellPointer ||
+        typeof cellPointer === "number" ||
+        nested.length === 0
+      ) {
+        return blocks as BlockNode[];
+      }
+      const row = targetBlock.rows[cellPointer.rowIndex];
+      const cell = row?.cells[cellPointer.cellIndex];
+      if (!row || !cell) return blocks as BlockNode[];
+      const nextChildren = updateChartPreviewAtPointer(
+        cell.children,
+        nested,
+        previewMediaId,
+      );
+      if (nextChildren === cell.children) return blocks as BlockNode[];
+      const nextCells = row.cells.slice();
+      nextCells[cellPointer.cellIndex] = {
+        ...cell,
+        children: nextChildren,
+      };
+      const nextRows = targetBlock.rows.slice();
+      nextRows[cellPointer.rowIndex] = {
+        ...row,
+        cells: nextCells,
+      };
+      const nextBlocks = blocks.slice();
+      nextBlocks[head] = {
+        ...targetBlock,
+        rows: nextRows,
+      };
+      return nextBlocks;
+    }
+    case "sdt":
+    case "custom_xml": {
+      const nextChildren = updateChartPreviewAtPointer(
+        targetBlock.children,
+        rest,
+        previewMediaId,
+      );
+      if (nextChildren === targetBlock.children) return blocks as BlockNode[];
+      const nextBlocks = blocks.slice();
+      nextBlocks[head] = {
+        ...targetBlock,
+        children: nextChildren,
+      };
+      return nextBlocks;
+    }
+    default:
+      return blocks as BlockNode[];
+  }
+}
+
 /**
  * Content-type sniff from the first bytes of the rendered preview.
  * PNG magic is 0x89 0x50 0x4E 0x47; everything else is assumed to be