@beyondwork/docx-react-component 1.0.54 → 1.0.56

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.54",
+  "version": "1.0.56",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
+  "packageManager": "pnpm@10.30.3",
   "type": "module",
   "sideEffects": [
     "**/*.css"
@@ -92,6 +93,37 @@
     "./ui-tailwind/theme/editor-theme.css": "./src/ui-tailwind/theme/editor-theme.css"
   },
   "types": "./src/index.ts",
+  "scripts": {
+    "build": "tsup",
+    "test": "bash scripts/run-workspace-tests.sh",
+    "test:repo": "node scripts/ci-check-layout-engine-version.mjs && node scripts/run-repo-tests.mjs core",
+    "test:repo:all": "node scripts/run-repo-tests.mjs all",
+    "test:repo:optional": "node scripts/run-repo-tests.mjs optional",
+    "test:repo:browser-ui": "node scripts/run-repo-tests.mjs browser-ui",
+    "test:wcag-audit": "node scripts/run-repo-tests.mjs wcag-audit",
+    "test:harness": "pnpm --filter @docx-react-component/react-word-editor-harness test",
+    "test:visual": "VISUAL_SMOKE_PROFILE=bare pnpm exec playwright test --project=chromium",
+    "test:visual:chrome": "VISUAL_SMOKE_PROFILE=chrome-cycle pnpm exec playwright test --project=chromium",
+    "visual:list-runs": "node scripts/visual-smoke-list-runs.mjs",
+    "mcp:visual-smoke": "node scripts/visual-smoke-mcp.mjs",
+    "lint": "pnpm run lint:no-authored-js && pnpm run lint:docs-contracts && pnpm run lint:tsgo && pnpm run lint:tsgo:harness",
+    "lint:docs-contracts": "bash scripts/check-reference-load-contract.sh",
+    "lint:no-authored-js": "bash scripts/check-no-authored-js.sh",
+    "lint:tsgo": "tsgo --noEmit -p tsconfig.build.json",
+    "lint:tsgo:harness": "pnpm --filter @docx-react-component/react-word-editor-harness lint:tsgo",
+    "generate:token-reference": "node scripts/generate-token-reference.mjs",
+    "check:token-reference": "node scripts/generate-token-reference.mjs --check",
+    "context7:api-check": "bash scripts/context7-export-env.sh run bash scripts/context7-api-check.sh",
+    "wave:doctor": "bash scripts/context7-export-env.sh run pnpm exec wave doctor --json",
+    "wave:dry-run": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main --dry-run --no-dashboard",
+    "wave:launch": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main",
+    "wave:launch:managed": "bash scripts/wave-launch.sh",
+    "wave:status": "bash scripts/wave-status.sh",
+    "wave:watch": "bash scripts/wave-watch.sh --follow",
+    "wave:dashboard:current": "bash scripts/wave-dashboard-attach.sh current",
+    "wave:dashboard:global": "bash scripts/wave-dashboard-attach.sh global",
+    "harness:dev": "pnpm --filter @docx-react-component/react-word-editor-harness dev"
+  },
   "keywords": [
     "docx",
     "word",
@@ -175,35 +207,14 @@
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.30"
   },
-  "scripts": {
-    "build": "tsup",
-    "test": "bash scripts/run-workspace-tests.sh",
-    "test:repo": "node scripts/ci-check-layout-engine-version.mjs && node scripts/run-repo-tests.mjs core",
-    "test:repo:all": "node scripts/run-repo-tests.mjs all",
-    "test:repo:optional": "node scripts/run-repo-tests.mjs optional",
-    "test:repo:browser-ui": "node scripts/run-repo-tests.mjs browser-ui",
-    "test:wcag-audit": "node scripts/run-repo-tests.mjs wcag-audit",
-    "test:harness": "pnpm --filter @docx-react-component/react-word-editor-harness test",
-    "test:visual": "VISUAL_SMOKE_PROFILE=bare pnpm exec playwright test --project=chromium",
-    "test:visual:chrome": "VISUAL_SMOKE_PROFILE=chrome-cycle pnpm exec playwright test --project=chromium",
-    "visual:list-runs": "node scripts/visual-smoke-list-runs.mjs",
-    "mcp:visual-smoke": "node scripts/visual-smoke-mcp.mjs",
-    "lint": "pnpm run lint:no-authored-js && pnpm run lint:docs-contracts && pnpm run lint:tsgo && pnpm run lint:tsgo:harness",
-    "lint:docs-contracts": "bash scripts/check-reference-load-contract.sh",
-    "lint:no-authored-js": "bash scripts/check-no-authored-js.sh",
-    "lint:tsgo": "tsgo --noEmit -p tsconfig.build.json",
-    "lint:tsgo:harness": "pnpm --filter @docx-react-component/react-word-editor-harness lint:tsgo",
-    "generate:token-reference": "node scripts/generate-token-reference.mjs",
-    "check:token-reference": "node scripts/generate-token-reference.mjs --check",
-    "context7:api-check": "bash scripts/context7-export-env.sh run bash scripts/context7-api-check.sh",
-    "wave:doctor": "bash scripts/context7-export-env.sh run pnpm exec wave doctor --json",
-    "wave:dry-run": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main --dry-run --no-dashboard",
-    "wave:launch": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main",
-    "wave:launch:managed": "bash scripts/wave-launch.sh",
-    "wave:status": "bash scripts/wave-status.sh",
-    "wave:watch": "bash scripts/wave-watch.sh --follow",
-    "wave:dashboard:current": "bash scripts/wave-dashboard-attach.sh current",
-    "wave:dashboard:global": "bash scripts/wave-dashboard-attach.sh global",
-    "harness:dev": "pnpm --filter @docx-react-component/react-word-editor-harness dev"
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild",
+      "sharp"
+    ],
+    "overrides": {
+      "react": "19.2.4",
+      "react-dom": "19.2.4"
+    }
   }
-}
+}

package/src/api/public-types.ts

@@ -858,6 +858,13 @@ export type SurfaceInlineSegment =
        * a text badge. Absent when the object has no cached fallback image.
        */
       previewMediaId?: string;
+      /**
+       * Stable chart ID (Stage 6). Present when the `chart_preview` node has a
+       * successfully parsed `ChartModel` (`parsedData` populated at import time).
+       * The ID keys into the module-level `chartModelStore` so `ChartNodeView`
+       * can render `ChartSurface` instead of the fallback bitmap or badge.
+       */
+      parsedChartId?: string;
       state: "locked-preserve-only";
     }
   | {
@@ -2846,6 +2853,80 @@ export interface EditorTelemetryEvent {
   detail?: Record<string, unknown>;
 }
 
+// ---------------------------------------------------------------------------
+// Chart read-model (Stage 6)
+// ---------------------------------------------------------------------------
+
+/**
+ * Structured, typed representation of a chart's data. Returned by
+ * `WordReviewEditorRef.getChartSnapshot` so agents can reason over chart
+ * content without re-parsing `rawXml`. Charts are read-only; agents must not
+ * mutate this object.
+ */
+export interface ChartSnapshot {
+  chartId: string;
+  kind: string;
+  title?: string;
+  seriesCount: number;
+  categoryCount: number;
+  data: ChartSnapshotData;
+}
+
+export type ChartSnapshotData =
+  | {
+      kind: "bar";
+      direction: "bar" | "column";
+      grouping: "clustered" | "stacked" | "percentStacked" | "standard";
+      series: ChartSnapshotSeries[];
+      categories: string[];
+    }
+  | {
+      kind: "line";
+      grouping: "standard" | "stacked" | "percentStacked";
+      series: ChartSnapshotSeries[];
+      categories: string[];
+    }
+  | {
+      kind: "pie";
+      doughnut: boolean;
+      series: ChartSnapshotSeries[];
+      categories: string[];
+    }
+  | {
+      kind: "area";
+      grouping: "standard" | "stacked" | "percentStacked";
+      series: ChartSnapshotSeries[];
+      categories: string[];
+    }
+  | { kind: "scatter"; series: ChartSnapshotScatterSeries[] }
+  | { kind: "bubble"; series: ChartSnapshotBubbleSeries[] }
+  | {
+      kind: "combo";
+      groups: Array<{ kind: "bar" | "line" | "area"; series: ChartSnapshotSeries[] }>;
+      categories: string[];
+    }
+  | { kind: "unsupported"; reason: string };
+
+export interface ChartSnapshotSeries {
+  name?: string;
+  values: Array<number | null>;
+}
+
+export interface ChartSnapshotScatterSeries {
+  name?: string;
+  xValues: Array<number | null>;
+  yValues: Array<number | null>;
+}
+
+export interface ChartSnapshotBubbleSeries {
+  name?: string;
+  xValues: Array<number | null>;
+  yValues: Array<number | null>;
+  sizes: Array<number | null>;
+}
+
+// ---------------------------------------------------------------------------
+
 /**
  * Stage 0B.1 — parameters passed to `EditorHostAdapter.renderChartPreview`
  * when the importer encounters a `c:chartSpace` that has no cached
@@ -2949,6 +3030,15 @@ export interface WordReviewEditorRef {
   getRenderSnapshot(): RuntimeRenderSnapshot;
   getCompatibilityReport(): CompatibilityReport;
   getWarnings(): EditorWarning[];
+  /**
+   * Stage 6 — structured chart data for a specific chart by ID. Returns `null`
+   * when the chart ID is not found or the chart has no parsed model (e.g. parse
+   * failed at import time, or chart type is unsupported). Use `getChartSnapshots`
+   * to enumerate all charts in the document.
+   */
+  getChartSnapshot(chartId: string): ChartSnapshot | null;
+  /** Stage 6 — all charts in the document that have a parsed model. */
+  getChartSnapshots(): ChartSnapshot[];
   getCommentSidebarSnapshot(): CommentSidebarSnapshot;
   getTrackedChangesSnapshot(): TrackedChangesSnapshot;
   getSuggestionsSnapshot(): SuggestionsSnapshot;

package/src/index.ts

@@ -122,6 +122,11 @@ export type {
   EditorSessionState,
   EditorHostAdapter,
   ChartPreviewResolveParams,
+  ChartSnapshot,
+  ChartSnapshotData,
+  ChartSnapshotSeries,
+  ChartSnapshotScatterSeries,
+  ChartSnapshotBubbleSeries,
   WordReviewEditorProps,
   WordReviewEditorChromePreset,
   WordReviewEditorChromeOptions,

package/src/io/docx-session.ts

@@ -73,6 +73,8 @@ import {
   WORKFLOW_PAYLOAD_CUSTOM_PROPS_PART_PATH,
   WORKFLOW_PAYLOAD_CUSTOM_PROPS_RELATIONSHIP_TYPE,
   WORKFLOW_PAYLOAD_ITEM_PROPS_CONTENT_TYPE,
+  WORKFLOW_PAYLOAD_ITEM_PROPS_PART_PATH,
+  WORKFLOW_PAYLOAD_PART_PATH,
   WORKFLOW_PAYLOAD_RELATIONSHIP_TYPE,
 } from "./ooxml/workflow-payload.ts";
 import {
@@ -2104,20 +2106,17 @@ function exportDocxEditorSession(
   const hasSettingsSurface =
     Boolean(state.sourceSettingsPartPath) ||
     exportedSubParts?.settings !== undefined;
-  const resolvedWorkflowPayloadPartPaths = resolveWorkflowPayloadPartPaths(
+  const workflowPayloadPartPaths = resolveWorkflowPayloadPartPaths(
     state.sourcePackage,
     sessionState.documentId,
   );
-  const internalEditorState = (
-    options as { _editorState?: import("./ooxml/workflow-payload.ts").EditorStatePayload } | undefined
-  )?._editorState;
 
   const exportSession = createExportSession(state.sourcePackage, [
     state.sourceDocumentPartPath,
     APP_PROPERTIES_PART_PATH,
     CORE_PROPERTIES_PART_PATH,
-    resolvedWorkflowPayloadPartPaths.payloadPartPath,
-    resolvedWorkflowPayloadPartPaths.itemPropsPartPath,
+    workflowPayloadPartPaths.payloadPartPath,
+    workflowPayloadPartPaths.itemPropsPartPath,
     WORKFLOW_PAYLOAD_CUSTOM_PROPS_PART_PATH,
     numberingPartPath,
     commentsPartPath,
@@ -2366,12 +2365,13 @@ function exportDocxEditorSession(
 
   ensureHostMetadataParts(exportSession, state.sourcePackage, currentDocument);
   // Schema 1.2: pass through editorState payload collected by the runtime channel.
+  const internalEditorState = (options as { _editorState?: import("./ooxml/workflow-payload.ts").EditorStatePayload } | undefined)?._editorState;
   ensureWorkflowPayloadParts(
     exportSession,
     sessionState,
     currentDocument,
     state.sourcePackage,
-    resolvedWorkflowPayloadPartPaths,
+    workflowPayloadPartPaths,
     internalEditorState,
   );
 

package/src/io/normalize/normalize-text.ts

@@ -560,6 +560,7 @@ function normalizeInlineChildren(
           children: fieldChildren,
           fieldFamily: classification.family,
           ...(classification.target ? { fieldTarget: classification.target } : {}),
+          ...(classification.switches ? { switches: classification.switches } : {}),
           refreshStatus: classification.supported ? "stale" : "preserve-only",
         });
         state.cursor += renderedLength > 0 ? renderedLength : 1;

package/src/io/ooxml/parse-field-switches.ts

@@ -0,0 +1,134 @@
+/**
+ * parse-field-switches.ts
+ *
+ * Pure tokenizer for OOXML field instruction switches.
+ * Used by parse-fields.ts to populate FieldNode.switches for REF/PAGEREF/NOTEREF/TOC.
+ *
+ * No runtime dependencies — this lives in the io layer alongside parse-fields.ts.
+ */
+
+export interface ParsedFieldSwitches {
+  /** \h — render as hyperlink */
+  hyperlink: boolean;
+  /** \p — emit relative position (above/below/on this page) */
+  relativePosition: boolean;
+  /** \n — use numeric reference */
+  numericRef: boolean;
+  /** \r — recursive */
+  recursive: boolean;
+  /** \t — suppress non-delimiter characters */
+  suppressNonDelimiter: boolean;
+  /** \w — include numbering prefix */
+  includeNumbering: boolean;
+  /** \l — include level */
+  includeLevel: boolean;
+  /** Any unrecognized switch letters (e.g. \*, \@, \#) */
+  unknownSwitches: string[];
+}
+
+/**
+ * Tokenize a field instruction string.
+ * Quoted strings (starting with ") are treated as a single token.
+ * Other tokens are split on whitespace.
+ */
+function tokenizeInstruction(s: string): string[] {
+  const tokens: string[] = [];
+  let i = 0;
+  while (i < s.length) {
+    // Skip whitespace
+    while (i < s.length && /\s/.test(s[i]!)) i += 1;
+    if (i >= s.length) break;
+
+    if (s[i] === '"') {
+      // Quoted token — scan to closing quote
+      const start = i;
+      i += 1; // skip opening quote
+      while (i < s.length && s[i] !== '"') i += 1;
+      if (i < s.length) i += 1; // skip closing quote
+      tokens.push(s.slice(start, i));
+    } else {
+      // Normal whitespace-delimited token
+      const start = i;
+      while (i < s.length && !/\s/.test(s[i]!)) i += 1;
+      tokens.push(s.slice(start, i));
+    }
+  }
+  return tokens;
+}
+
+/**
+ * Parse field switches from a raw field instruction string.
+ * Handles case-insensitive switch letters (\h, \p, \n, \r, \t, \w, \l).
+ * General-purpose switches (\*, \@, \#) each consume the next token as argument.
+ */
+export function parseFieldSwitches(instruction: string): ParsedFieldSwitches {
+  const result: ParsedFieldSwitches = {
+    hyperlink: false,
+    relativePosition: false,
+    numericRef: false,
+    recursive: false,
+    suppressNonDelimiter: false,
+    includeNumbering: false,
+    includeLevel: false,
+    unknownSwitches: [],
+  };
+
+  const tokens = tokenizeInstruction(instruction);
+  let i = 0;
+
+  // Skip leading non-switch tokens (field name, target bookmark, quoted names)
+  while (i < tokens.length && !tokens[i]!.startsWith("\\")) {
+    i += 1;
+  }
+
+  // Process switch tokens
+  while (i < tokens.length) {
+    const token = tokens[i]!;
+    i += 1;
+
+    if (!token.startsWith("\\")) {
+      // Not a switch — skip (e.g. argument to a previous switch)
+      continue;
+    }
+
+    const lower = token.toLowerCase();
+
+    switch (lower) {
+      case "\\h":
+        result.hyperlink = true;
+        break;
+      case "\\p":
+        result.relativePosition = true;
+        break;
+      case "\\n":
+        result.numericRef = true;
+        break;
+      case "\\r":
+        result.recursive = true;
+        break;
+      case "\\t":
+        result.suppressNonDelimiter = true;
+        break;
+      case "\\w":
+        result.includeNumbering = true;
+        break;
+      case "\\l":
+        result.includeLevel = true;
+        break;
+      case "\\*":
+      case "\\@":
+      case "\\#":
+        // General-purpose switches — consume next token as argument
+        result.unknownSwitches.push(token);
+        if (i < tokens.length) {
+          i += 1; // consume argument
+        }
+        break;
+      default:
+        result.unknownSwitches.push(token);
+        break;
+    }
+  }
+
+  return result;
+}

package/src/io/ooxml/parse-fields.ts

@@ -211,9 +211,10 @@ import type {
   TocEntry,
   TocStructure,
 } from "../../model/canonical-document.ts";
+import { parseFieldSwitches } from "./parse-field-switches.ts";
 
 const FIELD_FAMILY_PATTERN =
-  /^\s*(REF|PAGEREF|NOTEREF|TOC|PAGE|NUMPAGES|DATE|TIME|AUTHOR|FILENAME|MERGEFIELD|IF|SEQ|INDEX|TC|STYLEREF)\b/i;
+  /^\s*(REF|PAGEREF|NOTEREF|TOC|PAGE|NUMPAGES|DATE|TIME|AUTHOR|FILENAME|MERGEFIELD|IF|SEQ|INDEX|TC|STYLEREF|SECTIONPAGES)\b/i;
 
 const SUPPORTED_FAMILIES = new Set<string>([
   "REF",
@@ -222,16 +223,20 @@ const SUPPORTED_FAMILIES = new Set<string>([
   "TOC",
   "PAGE",
   "NUMPAGES",
+  "STYLEREF",
+  "SECTIONPAGES",
 ]);
 
 /**
  * Classify a field instruction into its field family.
  * Returns the family enum value and whether it is in the supported slice.
+ * For REF/PAGEREF/NOTEREF/TOC families, also parses field switches.
  */
 export function classifyFieldInstruction(instruction: string): {
   family: FieldFamily;
   supported: boolean;
   target?: string;
+  switches?: FieldNode["switches"];
 } {
   const trimmed = instruction.trim();
   const match = FIELD_FAMILY_PATTERN.exec(trimmed);
@@ -247,8 +252,29 @@ export function classifyFieldInstruction(instruction: string): {
     const targetMatch = /^\s*(?:REF|PAGEREF|NOTEREF)\s+(?:"([^"]+)"|(\S+))/i.exec(trimmed);
     target = (targetMatch?.[1] ?? targetMatch?.[2])?.trim();
   }
+  if (family === "STYLEREF") {
+    const styleMatch = /^\s*STYLEREF\s+(?:"([^"]+)"|(\S+))/i.exec(trimmed);
+    const extracted = styleMatch?.[1] ?? styleMatch?.[2];
+    if (extracted) target = extracted.trim();
+  }
+
+  let switches: FieldNode["switches"] | undefined;
+  if (family === "REF" || family === "PAGEREF" || family === "NOTEREF" || family === "TOC") {
+    const raw = parseFieldSwitches(trimmed);
+    const sw: FieldNode["switches"] = {};
+    if (raw.hyperlink) sw.hyperlink = true;
+    if (raw.relativePosition) sw.relativePosition = true;
+    if (raw.numericRef) sw.numericRef = true;
+    if (raw.recursive) sw.recursive = true;
+    if (raw.suppressNonDelimiter) sw.suppressNonDelimiter = true;
+    if (raw.includeNumbering) sw.includeNumbering = true;
+    if (raw.includeLevel) sw.includeLevel = true;
+    if (Object.keys(sw).length > 0) {
+      switches = sw;
+    }
+  }
 
-  return { family, supported, target };
+  return { family, supported, target, ...(switches ? { switches } : {}) };
 }
 
 /**

package/src/model/canonical-document.ts

@@ -804,7 +804,9 @@ export type SupportedFieldFamily =
   | "NOTEREF"
   | "TOC"
   | "PAGE"
-  | "NUMPAGES";
+  | "NUMPAGES"
+  | "STYLEREF"
+  | "SECTIONPAGES";
 
 /**
  * Unsupported field families that remain preserve-only.
@@ -820,7 +822,6 @@ export type PreserveOnlyFieldFamily =
   | "SEQ"
   | "INDEX"
   | "TC"
-  | "STYLEREF"
   | "FORMULA"
   | "UNKNOWN";
 
@@ -844,6 +845,16 @@ export interface FieldNode {
   fieldTarget?: string;
   /** Runtime refresh status. Undefined for legacy or preserve-only fields. */
   refreshStatus?: FieldRefreshStatus;
+  /** Parsed field switches. Present only when the instruction contains recognized switches. */
+  switches?: {
+    hyperlink?: boolean;
+    relativePosition?: boolean;
+    numericRef?: boolean;
+    recursive?: boolean;
+    suppressNonDelimiter?: boolean;
+    includeNumbering?: boolean;
+    includeLevel?: boolean;
+  };
 }
 
 // ─── Field registry ─────────────────────────────────────────────────────────

package/src/runtime/chart/chart-model-store.ts

@@ -0,0 +1,88 @@
+/**
+ * Module-level cache of parsed ChartModel instances keyed by a stable chart ID.
+ * Populated as a side effect of `surface-projection.ts` when a `chart_preview`
+ * node carries `parsedData`. Consumed by `ChartNodeView` to render `ChartSurface`.
+ *
+ * Charts are preserve-only (rawXml never mutated), so entries are stable for the
+ * lifetime of the document. `clear()` is called before repopulating on document
+ * replacement.
+ */
+
+import type { ChartModel } from "../../io/ooxml/chart/types.ts";
+import type { ResolvedTheme } from "../../model/canonical-document.ts";
+
+export interface ChartStoreEntry {
+  readonly model: ChartModel;
+  readonly widthPx: number;
+  readonly heightPx: number;
+  readonly theme: ResolvedTheme | undefined;
+}
+
+const _store = new Map<string, ChartStoreEntry>();
+
+export const chartModelStore = {
+  set(chartId: string, entry: ChartStoreEntry): void {
+    _store.set(chartId, entry);
+  },
+  get(chartId: string): ChartStoreEntry | undefined {
+    return _store.get(chartId);
+  },
+  clear(): void {
+    _store.clear();
+  },
+  size(): number {
+    return _store.size;
+  },
+  has(chartId: string): boolean {
+    return _store.has(chartId);
+  },
+  values(): IterableIterator<ChartStoreEntry> {
+    return _store.values();
+  },
+};
+
+const EMU_PER_PX = 9525;
+
+/**
+ * Extract drawing extent from rawXml and convert EMU → pixels.
+ * Tries `wp:extent` first (wp:inline/wp:anchor drawings), then `a:ext` as
+ * fallback (xfrm transforms). Falls back to a sensible 6×3.5 inch default.
+ */
+export function extractChartDimensions(rawXml: string): { widthPx: number; heightPx: number } {
+  const extentMatch = /<wp:extent\b([^/>]*)\/?>/.exec(rawXml);
+  if (extentMatch) {
+    const attrs = extentMatch[1] ?? "";
+    const cx = /\bcx="(\d+)"/.exec(attrs)?.[1];
+    const cy = /\bcy="(\d+)"/.exec(attrs)?.[1];
+    if (cx && cy) {
+      return {
+        widthPx: Math.round(parseInt(cx, 10) / EMU_PER_PX),
+        heightPx: Math.round(parseInt(cy, 10) / EMU_PER_PX),
+      };
+    }
+  }
+  const aExtMatch = /\ba:ext\s[^>]*\bcx="(\d+)"[^>]*\bcy="(\d+)"/.exec(rawXml);
+  if (aExtMatch) {
+    return {
+      widthPx: Math.round(parseInt(aExtMatch[1]!, 10) / EMU_PER_PX),
+      heightPx: Math.round(parseInt(aExtMatch[2]!, 10) / EMU_PER_PX),
+    };
+  }
+  return { widthPx: 576, heightPx: 336 };
+}
+
+/**
+ * Stable chart ID derived from rawXml content. Charts are never mutated so the
+ * ID is stable for the lifetime of the document load.
+ *
+ * Uses djb2 hash + length suffix to minimize collisions without importing a
+ * crypto dependency.
+ */
+export function stableChartId(rawXml: string): string {
+  let h = 5381;
+  for (let i = 0; i < rawXml.length; i++) {
+    h = ((h << 5) + h) ^ rawXml.charCodeAt(i);
+    h = h | 0;
+  }
+  return `chart-${(h >>> 0).toString(16)}-${rawXml.length}`;
+}