@beyondwork/docx-react-component 1.0.53 → 1.0.55

package/package.json

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

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;
@@ -3058,12 +3148,16 @@ export interface WordReviewEditorRef {
   setWorkflowOverlay(overlay: WorkflowOverlay): void;
   clearWorkflowOverlay(): void;
   /**
-   * Read the current runtime-backed `WorkflowOverlay`, or `null` when no
-   * overlay is active.  Hosts use this for read-modify-write flows against
-   * `setWorkflowOverlay(...)` — notably to preserve engine-authored scopes
-   * minted via `addScope(...)` when updating candidates / work items.
-   * Returns a defensive clone; mutating the returned object does not affect
-   * runtime state.
+   * Return a structural clone of the currently-registered workflow
+   * overlay, or `null` when no overlay has been set (or
+   * `clearWorkflowOverlay` has been called). Intended for the canonical
+   * host read-before-write pattern — read current, merge host-owned
+   * fields (e.g. `candidates`), write back via `setWorkflowOverlay`
+   * without clobbering engine-authored `scopes`, `workItems`, or the
+   * overlay-level `metadataPersistence` default. `setWorkflowOverlay`
+   * replaces the overlay wholesale; passing `scopes: []` will drop
+   * every scope registered via `addScope` and cause subsequent
+   * `replaceText` calls to block with `workflow_comment_only`.
    */
   getWorkflowOverlay(): WorkflowOverlay | null;
   setSharedWorkflowState(state: SharedWorkflowState | null): void;
@@ -3304,7 +3398,31 @@ export interface WordReviewEditorProps {
   suggestionsEnabled?: boolean;
   chromePreset?: WordReviewEditorChromePreset;
   chromeOptions?: Partial<WordReviewEditorChromeOptions>;
-  markupDisplay?: "clean" | "simple" | "all";
+  /**
+   * Controls how tracked changes and comments render.  Accepts Word's
+   * 4-mode grammar (`"all-markup" | "simple-markup" | "no-markup" | "original"`)
+   * or the legacy triple (`"all" | "simple" | "clean"`), which maps 1:1
+   * onto the first three canonical names.  `"original"` is new in 6d.N2:
+   * insertions are hidden, deletions render as plain body text so the
+   * reviewer sees the pre-change state.
+   */
+  markupDisplay?:
+    | "all-markup"
+    | "simple-markup"
+    | "no-markup"
+    | "original"
+    | "clean"
+    | "simple"
+    | "all";
+  /**
+   * L6d.N2 — invoked when the user picks a different display mode from
+   * the in-chrome selector.  Values are always emitted in the canonical
+   * Word grammar (`"all-markup" | "simple-markup" | "no-markup" | "original"`),
+   * not the legacy aliases.
+   */
+  onMarkupDisplayChange?: (
+    value: "all-markup" | "simple-markup" | "no-markup" | "original",
+  ) => void;
   /**
    * @internal HARNESS-ONLY debug-ports token.
    *

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

@@ -67,6 +67,7 @@ import {
   getDocumentBackedWorkflowMetadata,
   parseWorkflowPayloadEnvelopeFromPackage,
   resolvePayloadPartPath,
+  resolveWorkflowPayloadPartPaths,
   WORKFLOW_PAYLOAD_CONTENT_TYPE,
   WORKFLOW_PAYLOAD_CUSTOM_PROPS_CONTENT_TYPE,
   WORKFLOW_PAYLOAD_CUSTOM_PROPS_PART_PATH,
@@ -2105,13 +2106,17 @@ function exportDocxEditorSession(
   const hasSettingsSurface =
     Boolean(state.sourceSettingsPartPath) ||
     exportedSubParts?.settings !== undefined;
+  const workflowPayloadPartPaths = resolveWorkflowPayloadPartPaths(
+    state.sourcePackage,
+    sessionState.documentId,
+  );
 
   const exportSession = createExportSession(state.sourcePackage, [
     state.sourceDocumentPartPath,
     APP_PROPERTIES_PART_PATH,
     CORE_PROPERTIES_PART_PATH,
-    WORKFLOW_PAYLOAD_PART_PATH,
-    WORKFLOW_PAYLOAD_ITEM_PROPS_PART_PATH,
+    workflowPayloadPartPaths.payloadPartPath,
+    workflowPayloadPartPaths.itemPropsPartPath,
     WORKFLOW_PAYLOAD_CUSTOM_PROPS_PART_PATH,
     numberingPartPath,
     commentsPartPath,
@@ -2361,7 +2366,14 @@ 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, internalEditorState);
+  ensureWorkflowPayloadParts(
+    exportSession,
+    sessionState,
+    currentDocument,
+    state.sourcePackage,
+    workflowPayloadPartPaths,
+    internalEditorState,
+  );
 
   return {
     bytes: exportSession.serialize(),
@@ -4087,6 +4099,10 @@ function ensureWorkflowPayloadParts(
   sessionState: EditorSessionState,
   document: CanonicalDocumentEnvelope,
   sourcePackage: OpcPackage,
+  resolvedPartPaths: {
+    payloadPartPath: string;
+    itemPropsPartPath: string;
+  },
   editorState?: import("./ooxml/workflow-payload.ts").EditorStatePayload,
 ): void {
   const payloadParts = buildWorkflowPayloadParts({
@@ -4102,6 +4118,14 @@ function ensureWorkflowPayloadParts(
   if (!payloadParts) {
     return;
   }
+  if (
+    payloadParts.payloadPartPath !== resolvedPartPaths.payloadPartPath ||
+    payloadParts.itemPropsPartPath !== resolvedPartPaths.itemPropsPartPath
+  ) {
+    throw new Error(
+      "Workflow payload export resolved inconsistent customXml paths; export session ownership no longer matches payload serialization.",
+    );
+  }
 
   const payloadPart = sourcePackage.parts.get(payloadParts.payloadPartPath);
   const itemPropsPart = sourcePackage.parts.get(payloadParts.itemPropsPartPath);

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}`;
+}