@beyondwork/docx-react-component 1.0.41 → 1.0.43

package/src/ui-tailwind/editor-surface/tw-page-block-view.helpers.ts

@@ -0,0 +1,265 @@
+import type React from "react";
+
+import type {
+  SurfaceBlockSnapshot,
+  SurfaceTextMark,
+} from "../../api/public-types.ts";
+import type { CanonicalRunFormatting } from "../../model/canonical-document.ts";
+
+// ---------------------------------------------------------------------------
+// Pure helpers shared by `tw-page-block-view` (body) and `tw-region-block-
+// renderer` (header / footer / footnote / endnote bands).  Extracted in P8.4
+// so per-page regions reuse body typography verbatim — indent/margin/line-
+// height/marker geometry stay identical across all regions.
+// ---------------------------------------------------------------------------
+
+export const HEX_COLOR_RE = /^[0-9A-Fa-f]{3,8}$/;
+export const SAFE_FONT_RE = /^[A-Za-z0-9 ,\-'"]+$/;
+export const SAFE_ALIGNMENT = new Set([
+  "left",
+  "center",
+  "right",
+  "justify",
+  "start",
+  "end",
+]);
+
+export function safeHexColor(raw: string | null | undefined): string | null {
+  if (!raw || raw === "auto") return null;
+  return HEX_COLOR_RE.test(raw) ? `#${raw}` : null;
+}
+
+/** Resolve heading level from styleId or outlineLevel (outlineLevel 0 = Heading 1). */
+export function resolveHeadingLevel(
+  styleId?: string,
+  outlineLevel?: number,
+): number | null {
+  if (styleId) {
+    const normalized = styleId.toLowerCase();
+    const compact = normalized.replace(/[\s_-]+/g, "");
+    const headingMatch = /^heading([1-6])$/.exec(compact);
+    if (headingMatch) {
+      return Number.parseInt(headingMatch[1], 10);
+    }
+    if (compact === "title") return 1;
+    if (compact === "subtitle") return 2;
+    if (compact === "tocheading") return 1;
+    if (/^(appendix|schedule|annex|exhibit|attachment)(heading|title)$/.test(compact)) return 2;
+  }
+  if (
+    typeof outlineLevel === "number" &&
+    Number.isInteger(outlineLevel) &&
+    outlineLevel >= 0 &&
+    outlineLevel <= 5
+  ) {
+    return outlineLevel + 1;
+  }
+  return null;
+}
+
+export function resolveMarkerJustificationCss(raw: string | undefined): string {
+  switch (raw) {
+    case "left":
+      return "flex-start";
+    case "center":
+      return "center";
+    case "right":
+    case "both":
+    case "distribute":
+    default:
+      return "flex-end";
+  }
+}
+
+/** Build CSSProperties for a paragraph block from spacing/indent/alignment. */
+export function buildParagraphStyle(
+  block: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>,
+): React.CSSProperties {
+  const style: React.CSSProperties = {};
+
+  // Alignment — direct takes precedence over resolvedParagraphFormatting
+  const rawAlignment = block.alignment ?? block.resolvedParagraphFormatting?.alignment;
+  const safeAlign = rawAlignment === "both" ? "justify" : rawAlignment;
+  if (safeAlign && SAFE_ALIGNMENT.has(safeAlign)) {
+    style.textAlign = safeAlign as React.CSSProperties["textAlign"];
+  }
+
+  // Spacing
+  const spacingBefore =
+    block.spacing?.before ?? block.resolvedParagraphFormatting?.spacing?.before;
+  const spacingAfter =
+    block.spacing?.after ?? block.resolvedParagraphFormatting?.spacing?.after;
+  const lineSpacing =
+    block.spacing?.line ?? block.resolvedParagraphFormatting?.spacing?.line;
+  const lineRule =
+    block.spacing?.lineRule ?? block.resolvedParagraphFormatting?.spacing?.lineRule;
+
+  if (spacingBefore != null) {
+    style.marginTop = `${spacingBefore / 20}pt`;
+  }
+  if (spacingAfter != null) {
+    style.marginBottom = `${spacingAfter / 20}pt`;
+  }
+  if (lineSpacing && lineRule === "auto") {
+    style.lineHeight = String(lineSpacing / 240);
+  } else if (lineSpacing && lineRule === "exact") {
+    style.lineHeight = `${lineSpacing / 20}pt`;
+  } else if (lineSpacing && lineRule === "atLeast") {
+    style.minHeight = `${lineSpacing / 20}pt`;
+  }
+
+  // Indentation
+  const indentLeft =
+    block.indentation?.left ?? block.resolvedParagraphFormatting?.indentation?.left;
+  const indentRight =
+    block.indentation?.right ?? block.resolvedParagraphFormatting?.indentation?.right;
+  const indentFirstLine =
+    block.indentation?.firstLine ?? block.resolvedParagraphFormatting?.indentation?.firstLine;
+  const indentHanging =
+    block.indentation?.hanging ?? block.resolvedParagraphFormatting?.indentation?.hanging;
+
+  if (indentLeft) style.paddingLeft = `${indentLeft / 20}pt`;
+  if (indentRight) style.paddingRight = `${indentRight / 20}pt`;
+  if (indentHanging) style.textIndent = `-${indentHanging / 20}pt`;
+  else if (indentFirstLine) style.textIndent = `${indentFirstLine / 20}pt`;
+
+  // Shading
+  const shadingFill = block.shading?.fill;
+  const shadingColor = safeHexColor(shadingFill);
+  if (shadingColor) style.backgroundColor = shadingColor;
+
+  // Page break visual indicator
+  if (block.pageBreakBefore) {
+    style.borderTop = "2px dashed rgba(0,0,0,0.1)";
+    style.paddingTop = "8px";
+    style.marginTop = "16px";
+  }
+
+  return style;
+}
+
+/** Build CSSProperties for the numbering marker span. */
+export function buildMarkerStyle(
+  prefix: string,
+  suffix: "tab" | "space" | "nothing" | undefined,
+  markerRunProperties: CanonicalRunFormatting | undefined,
+  markerWidth: number | undefined,
+  markerJustification: string | undefined,
+): React.CSSProperties {
+  const style: React.CSSProperties = {
+    fontVariantNumeric: "tabular-nums",
+    justifyContent: resolveMarkerJustificationCss(markerJustification),
+  };
+
+  if (markerRunProperties) {
+    if (markerRunProperties.bold) style.fontWeight = "bold";
+    if (markerRunProperties.italic) style.fontStyle = "italic";
+    if (markerRunProperties.underline && markerRunProperties.underline !== "none") {
+      style.textDecoration = "underline";
+    }
+    if (typeof markerRunProperties.fontSizeHalfPoints === "number") {
+      style.fontSize = `${markerRunProperties.fontSizeHalfPoints / 2}pt`;
+    }
+    const colorHex = markerRunProperties.colorHex;
+    if (colorHex && colorHex !== "auto") {
+      style.color = `#${colorHex.toLowerCase()}`;
+    }
+    const family = markerRunProperties.fontFamilyAscii ?? markerRunProperties.fontFamily;
+    if (family && SAFE_FONT_RE.test(family)) {
+      style.fontFamily = family;
+    }
+  } else {
+    style.color = "var(--color-text-tertiary)";
+    style.fontFamily = "var(--font-legal-sans)";
+  }
+
+  const hasResolvedMarkerWidth = typeof markerWidth === "number" && markerWidth > 0;
+  if (hasResolvedMarkerWidth) {
+    // P13.a: emit marker geometry in pt so it self-scales under CSS `zoom`.
+    const markerWidthPt = Math.max(1, markerWidth! / 20);
+    style.width = `${markerWidthPt}pt`;
+    style.minWidth = `${markerWidthPt}pt`;
+    style.flexBasis = `${markerWidthPt}pt`;
+    style.marginRight = 0;
+    style.overflow = "visible";
+  } else {
+    const fallbackMinWidth = Math.min(Math.max(prefix.length + 1, 4), 14);
+    const fallbackMarginRight =
+      suffix === "nothing" ? "0.25rem" : suffix === "space" ? "0.5rem" : "0.75rem";
+    style.minWidth = `${fallbackMinWidth}ch`;
+    style.marginRight = fallbackMarginRight;
+  }
+
+  return style;
+}
+
+/** Build CSSProperties for a text segment from marks and markAttrs. */
+export function buildSegmentStyle(
+  marks: SurfaceTextMark[] | undefined,
+  markAttrs?: {
+    fontSize?: number;
+    textColor?: string;
+    fontFamily?: string;
+    backgroundColor?: string;
+    charSpacing?: number;
+  },
+): React.CSSProperties {
+  const style: React.CSSProperties = {};
+
+  if (marks) {
+    if (marks.includes("bold")) style.fontWeight = "bold";
+    if (marks.includes("italic")) style.fontStyle = "italic";
+    if (marks.includes("underline")) style.textDecoration = "underline";
+    if (marks.includes("strikethrough") || marks.includes("doubleStrikethrough")) {
+      style.textDecoration = marks.includes("underline")
+        ? "underline line-through"
+        : "line-through";
+    }
+    if (marks.includes("superscript")) {
+      style.verticalAlign = "super";
+      style.fontSize = "smaller";
+    }
+    if (marks.includes("subscript")) {
+      style.verticalAlign = "sub";
+      style.fontSize = "smaller";
+    }
+    if (marks.includes("allCaps")) style.textTransform = "uppercase";
+    if (marks.includes("smallCaps")) style.fontVariant = "small-caps";
+    if (marks.includes("vanish")) style.display = "none";
+  }
+
+  if (markAttrs) {
+    if (markAttrs.fontSize) style.fontSize = `${markAttrs.fontSize}pt`;
+    if (markAttrs.textColor) style.color = markAttrs.textColor;
+    if (markAttrs.fontFamily && SAFE_FONT_RE.test(markAttrs.fontFamily)) {
+      style.fontFamily = markAttrs.fontFamily;
+    }
+    if (markAttrs.backgroundColor) style.backgroundColor = markAttrs.backgroundColor;
+    if (markAttrs.charSpacing) style.letterSpacing = `${markAttrs.charSpacing}px`;
+  }
+
+  return style;
+}
+
+export function hasStyleEntries(style: React.CSSProperties): boolean {
+  return Object.keys(style).length > 0;
+}
+
+export function headingClassList(level: number): string[] {
+  switch (level) {
+    case 1:
+      return ["text-3xl", "font-semibold", "tracking-tight", "leading-tight"];
+    case 2:
+      return ["text-2xl", "font-semibold", "tracking-tight"];
+    case 3:
+      return ["text-xl", "font-medium"];
+    case 4:
+      return ["text-lg", "font-medium"];
+    case 5:
+      return ["text-base", "font-semibold", "uppercase", "tracking-[0.12em]"];
+    case 6:
+      return ["text-sm", "font-semibold", "uppercase", "tracking-[0.16em]"];
+    default:
+      return [];
+  }
+}

package/src/ui-tailwind/editor-surface/tw-page-block-view.tsx

@@ -3,242 +3,15 @@ import React from "react";
 import type {
   SurfaceBlockSnapshot,
   SurfaceInlineSegment,
-  SurfaceTextMark,
 } from "../../api/public-types.ts";
-import type { CanonicalRunFormatting } from "../../model/canonical-document.ts";
-
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-const HEX_COLOR_RE = /^[0-9A-Fa-f]{3,8}$/;
-const SAFE_FONT_RE = /^[A-Za-z0-9 ,\-'"]+$/;
-const SAFE_ALIGNMENT = new Set(["left", "center", "right", "justify", "start", "end"]);
-
-// ---------------------------------------------------------------------------
-// Helper utilities (mirror pm-schema.ts helpers)
-// ---------------------------------------------------------------------------
-
-function safeHexColor(raw: string | null | undefined): string | null {
-  if (!raw || raw === "auto") return null;
-  return HEX_COLOR_RE.test(raw) ? `#${raw}` : null;
-}
-
-/** Resolve heading level from styleId or outlineLevel (outlineLevel 0 = Heading 1). */
-function resolveHeadingLevel(styleId?: string, outlineLevel?: number): number | null {
-  if (styleId) {
-    const normalized = styleId.toLowerCase();
-    const compact = normalized.replace(/[\s_-]+/g, "");
-    const headingMatch = /^heading([1-6])$/.exec(compact);
-    if (headingMatch) {
-      return Number.parseInt(headingMatch[1], 10);
-    }
-    if (compact === "title") return 1;
-    if (compact === "subtitle") return 2;
-    if (compact === "tocheading") return 1;
-    if (/^(appendix|schedule|annex|exhibit|attachment)(heading|title)$/.test(compact)) return 2;
-  }
-  if (
-    typeof outlineLevel === "number" &&
-    Number.isInteger(outlineLevel) &&
-    outlineLevel >= 0 &&
-    outlineLevel <= 5
-  ) {
-    return outlineLevel + 1;
-  }
-  return null;
-}
-
-function resolveMarkerJustificationCss(raw: string | undefined): string {
-  switch (raw) {
-    case "left":
-      return "flex-start";
-    case "center":
-      return "center";
-    case "right":
-    case "both":
-    case "distribute":
-    default:
-      return "flex-end";
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Style builders
-// ---------------------------------------------------------------------------
-
-/** Build CSSProperties for a paragraph block from spacing/indent/alignment. */
-function buildParagraphStyle(
-  block: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>,
-): React.CSSProperties {
-  const style: React.CSSProperties = {};
-
-  // Alignment — direct takes precedence over resolvedParagraphFormatting
-  const rawAlignment = block.alignment ?? block.resolvedParagraphFormatting?.alignment;
-  const safeAlign = rawAlignment === "both" ? "justify" : rawAlignment;
-  if (safeAlign && SAFE_ALIGNMENT.has(safeAlign)) {
-    style.textAlign = safeAlign as React.CSSProperties["textAlign"];
-  }
-
-  // Spacing
-  const spacingBefore =
-    block.spacing?.before ?? block.resolvedParagraphFormatting?.spacing?.before;
-  const spacingAfter =
-    block.spacing?.after ?? block.resolvedParagraphFormatting?.spacing?.after;
-  const lineSpacing =
-    block.spacing?.line ?? block.resolvedParagraphFormatting?.spacing?.line;
-  const lineRule =
-    block.spacing?.lineRule ?? block.resolvedParagraphFormatting?.spacing?.lineRule;
-
-  if (spacingBefore != null) {
-    style.marginTop = `${spacingBefore / 20}px`;
-  }
-  if (spacingAfter != null) {
-    style.marginBottom = `${spacingAfter / 20}px`;
-  }
-  if (lineSpacing && lineRule === "auto") {
-    style.lineHeight = String(lineSpacing / 240);
-  } else if (lineSpacing && lineRule === "exact") {
-    style.lineHeight = `${lineSpacing / 20}px`;
-  } else if (lineSpacing && lineRule === "atLeast") {
-    style.minHeight = `${lineSpacing / 20}px`;
-  }
-
-  // Indentation
-  const indentLeft =
-    block.indentation?.left ?? block.resolvedParagraphFormatting?.indentation?.left;
-  const indentRight =
-    block.indentation?.right ?? block.resolvedParagraphFormatting?.indentation?.right;
-  const indentFirstLine =
-    block.indentation?.firstLine ?? block.resolvedParagraphFormatting?.indentation?.firstLine;
-  const indentHanging =
-    block.indentation?.hanging ?? block.resolvedParagraphFormatting?.indentation?.hanging;
-
-  if (indentLeft) style.paddingLeft = `${indentLeft / 20}px`;
-  if (indentRight) style.paddingRight = `${indentRight / 20}px`;
-  if (indentHanging) style.textIndent = `-${indentHanging / 20}px`;
-  else if (indentFirstLine) style.textIndent = `${indentFirstLine / 20}px`;
-
-  // Shading
-  const shadingFill = block.shading?.fill;
-  const shadingColor = safeHexColor(shadingFill);
-  if (shadingColor) style.backgroundColor = shadingColor;
-
-  // Page break visual indicator
-  if (block.pageBreakBefore) {
-    style.borderTop = "2px dashed rgba(0,0,0,0.1)";
-    style.paddingTop = "8px";
-    style.marginTop = "16px";
-  }
-
-  return style;
-}
-
-/** Build CSSProperties for the numbering marker span. */
-function buildMarkerStyle(
-  prefix: string,
-  suffix: "tab" | "space" | "nothing" | undefined,
-  markerRunProperties: CanonicalRunFormatting | undefined,
-  markerWidth: number | undefined,
-  markerJustification: string | undefined,
-): React.CSSProperties {
-  const style: React.CSSProperties = {
-    fontVariantNumeric: "tabular-nums",
-    justifyContent: resolveMarkerJustificationCss(markerJustification),
-  };
-
-  if (markerRunProperties) {
-    if (markerRunProperties.bold) style.fontWeight = "bold";
-    if (markerRunProperties.italic) style.fontStyle = "italic";
-    if (markerRunProperties.underline && markerRunProperties.underline !== "none") {
-      style.textDecoration = "underline";
-    }
-    if (typeof markerRunProperties.fontSizeHalfPoints === "number") {
-      style.fontSize = `${markerRunProperties.fontSizeHalfPoints / 2}pt`;
-    }
-    const colorHex = markerRunProperties.colorHex;
-    if (colorHex && colorHex !== "auto") {
-      style.color = `#${colorHex.toLowerCase()}`;
-    }
-    const family = markerRunProperties.fontFamilyAscii ?? markerRunProperties.fontFamily;
-    if (family && SAFE_FONT_RE.test(family)) {
-      style.fontFamily = family;
-    }
-  } else {
-    style.color = "var(--color-text-tertiary)";
-    style.fontFamily = "var(--font-legal-sans)";
-  }
-
-  const hasResolvedMarkerWidth = typeof markerWidth === "number" && markerWidth > 0;
-  if (hasResolvedMarkerWidth) {
-    const markerWidthPx = Math.max(1, Math.round(markerWidth! / 20));
-    style.width = `${markerWidthPx}px`;
-    style.minWidth = `${markerWidthPx}px`;
-    style.flexBasis = `${markerWidthPx}px`;
-    style.marginRight = 0;
-    style.overflow = "visible";
-  } else {
-    const fallbackMinWidth = Math.min(Math.max(prefix.length + 1, 4), 14);
-    const fallbackMarginRight =
-      suffix === "nothing" ? "0.25rem" : suffix === "space" ? "0.5rem" : "0.75rem";
-    style.minWidth = `${fallbackMinWidth}ch`;
-    style.marginRight = fallbackMarginRight;
-  }
-
-  return style;
-}
-
-/** Build CSSProperties for a text segment from marks and markAttrs. */
-function buildSegmentStyle(
-  marks: SurfaceTextMark[] | undefined,
-  markAttrs?: {
-    fontSize?: number;
-    textColor?: string;
-    fontFamily?: string;
-    backgroundColor?: string;
-    charSpacing?: number;
-  },
-): React.CSSProperties {
-  const style: React.CSSProperties = {};
-
-  if (marks) {
-    if (marks.includes("bold")) style.fontWeight = "bold";
-    if (marks.includes("italic")) style.fontStyle = "italic";
-    if (marks.includes("underline")) style.textDecoration = "underline";
-    if (marks.includes("strikethrough") || marks.includes("doubleStrikethrough")) {
-      style.textDecoration = marks.includes("underline")
-        ? "underline line-through"
-        : "line-through";
-    }
-    if (marks.includes("superscript")) {
-      style.verticalAlign = "super";
-      style.fontSize = "smaller";
-    }
-    if (marks.includes("subscript")) {
-      style.verticalAlign = "sub";
-      style.fontSize = "smaller";
-    }
-    if (marks.includes("allCaps")) style.textTransform = "uppercase";
-    if (marks.includes("smallCaps")) style.fontVariant = "small-caps";
-    if (marks.includes("vanish")) style.display = "none";
-  }
-
-  if (markAttrs) {
-    if (markAttrs.fontSize) style.fontSize = `${markAttrs.fontSize}pt`;
-    if (markAttrs.textColor) style.color = markAttrs.textColor;
-    if (markAttrs.fontFamily && SAFE_FONT_RE.test(markAttrs.fontFamily)) {
-      style.fontFamily = markAttrs.fontFamily;
-    }
-    if (markAttrs.backgroundColor) style.backgroundColor = markAttrs.backgroundColor;
-    if (markAttrs.charSpacing) style.letterSpacing = `${markAttrs.charSpacing}px`;
-  }
-
-  return style;
-}
-
-function hasStyleEntries(style: React.CSSProperties): boolean {
-  return Object.keys(style).length > 0;
-}
+import {
+  buildMarkerStyle,
+  buildParagraphStyle,
+  buildSegmentStyle,
+  hasStyleEntries,
+  headingClassList,
+  resolveHeadingLevel,
+} from "./tw-page-block-view.helpers.ts";
 
 // ---------------------------------------------------------------------------
 // Segment renderer
@@ -408,25 +181,6 @@ function ParagraphBlock({
   );
 }
 
-function headingClassList(level: number): string[] {
-  switch (level) {
-    case 1:
-      return ["text-3xl", "font-semibold", "tracking-tight", "leading-tight"];
-    case 2:
-      return ["text-2xl", "font-semibold", "tracking-tight"];
-    case 3:
-      return ["text-xl", "font-medium"];
-    case 4:
-      return ["text-lg", "font-medium"];
-    case 5:
-      return ["text-base", "font-semibold", "uppercase", "tracking-[0.12em]"];
-    case 6:
-      return ["text-sm", "font-semibold", "uppercase", "tracking-[0.16em]"];
-    default:
-      return [];
-  }
-}
-
 /** Render a table block as <table>. */
 function TableBlock({
   block,
@@ -450,9 +204,9 @@ function TableBlock({
             key={rowIdx}
             style={
               row.height != null && row.heightRule === "exact"
-                ? { height: `${row.height / 20}px` }
+                ? { height: `${row.height / 20}pt` }
                 : row.height != null && row.heightRule === "atLeast"
-                  ? { minHeight: `${row.height / 20}px` }
+                  ? { minHeight: `${row.height / 20}pt` }
                   : undefined
             }
           >

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

@@ -188,6 +188,11 @@ export interface TwProseMirrorSurfaceProps {
   onUndo?: () => void;
   onRedo?: () => void;
   onBlockedInput?: (command: "paste" | "drop", message: string) => void;
+  onPasteApplied?: (meta: {
+    segmentCount: number;
+    charCount: number;
+    source: "paste" | "drop";
+  }) => void;
   onCommentActivated?: (commentId: string) => void;
   onRevisionActivated?: (revisionId: string) => void;
   onSelectionToolbarAnchorChange?: (anchor: SelectionToolbarAnchor | null) => void;
@@ -321,6 +326,9 @@ export const TwProseMirrorSurface = forwardRef<
     onBlockedInput: (command, message) => {
       props.onBlockedInput?.(command, message);
     },
+    onPasteApplied: (meta) => {
+      props.onPasteApplied?.(meta);
+    },
     onSelectionChange: (sel) => {
       pendingSelectionProbeRef.current = startPerfProbe("selection");
       props.onSelectionChange?.(
@@ -448,6 +456,7 @@ export const TwProseMirrorSurface = forwardRef<
       onUndo: () => callbacksRef.current?.onUndo(),
       onRedo: () => callbacksRef.current?.onRedo(),
       onBlockedInput: (command, message) => callbacksRef.current?.onBlockedInput?.(command, message),
+      onPasteApplied: (meta) => callbacksRef.current?.onPasteApplied?.(meta),
       onCompositionChange: (composing) => {
         sessionRef.current?.setComposing(composing);
       },

package/src/ui-tailwind/editor-surface/tw-table-node-view.tsx

@@ -294,6 +294,72 @@ function applyTableAttrs(table: HTMLTableElement, node: PMNode): void {
   } else if (alignment === "right") {
     table.style.marginLeft = "auto";
   }
+  syncColgroup(table, node);
+}
+
+/**
+ * P6.a: real `<colgroup>` driven by the table's canonical `gridColumns`.
+ *
+ * Pre-P6 tables relied on per-row padding cells (`data-row-padding`) to
+ * approximate column widths.  That produced correct-looking tables on
+ * simple CCEP fixtures but broke as soon as a row used `w:gridBefore` /
+ * `w:gridAfter` or a cell spanned multiple logical columns with
+ * non-uniform widths.  HTML's `<colgroup>` is the canonical place to
+ * declare per-column widths; every browser honors it exactly and we
+ * avoid the padding-cell trick entirely for width purposes.
+ *
+ * Each `<col>` uses its twips width converted to `pt` via `twips / 20`
+ * (the same unit the row-padding helper already uses for its
+ * `style.width`).  Keeping `pt` units avoids tying the NodeView to a
+ * pxPerTwip value — the CSS `zoom` applied at the workspace root
+ * rescales `pt` alongside every other length, so the columns follow
+ * zoom automatically.
+ *
+ * When `gridColumns` is empty (malformed input, or a table built
+ * programmatically without a declared grid), the colgroup is removed
+ * so the browser falls back to auto-sizing.
+ */
+function syncColgroup(table: HTMLTableElement, node: PMNode): void {
+  const gridColumns = Array.isArray(node.attrs.gridColumns)
+    ? (node.attrs.gridColumns as number[])
+    : [];
+  const existing = Array.from(table.children).find(
+    (child): child is HTMLTableColElement =>
+      child instanceof (table.ownerDocument?.defaultView?.HTMLTableColElement ??
+        HTMLTableColElement) && child.tagName === "COLGROUP",
+  ) as HTMLElement | undefined;
+
+  if (gridColumns.length === 0) {
+    existing?.remove();
+    return;
+  }
+
+  const owner = table.ownerDocument ?? document;
+  const colgroup = existing ?? owner.createElement("colgroup");
+  colgroup.setAttribute("data-pm-table-colgroup", "true");
+  // Reuse existing <col> children where possible; add/remove tail cols.
+  const desired = gridColumns.length;
+  const actual = colgroup.childElementCount;
+  for (let i = actual; i < desired; i += 1) {
+    colgroup.appendChild(owner.createElement("col"));
+  }
+  while (colgroup.childElementCount > desired) {
+    colgroup.lastElementChild?.remove();
+  }
+  for (let i = 0; i < desired; i += 1) {
+    const col = colgroup.children[i] as HTMLTableColElement;
+    const twips = gridColumns[i] ?? 0;
+    col.setAttribute("data-col-index", String(i));
+    col.setAttribute("data-col-twips", String(twips));
+    col.style.width = twips > 0 ? `${twips / 20}pt` : "";
+  }
+
+  if (!existing) {
+    // Colgroup must be the first child of <table> per HTML spec so the
+    // column widths propagate to every row.  `insertBefore(first)`
+    // handles both empty and populated tables uniformly.
+    table.insertBefore(colgroup, table.firstChild);
+  }
 }
 
 function applyRowAttrs(row: HTMLTableRowElement, node: PMNode): void {