@beyondwork/docx-react-component 1.0.31 → 1.0.33

package/README.md

@@ -126,6 +126,7 @@ For the normative API and host contract, use:
 - [`docs/reference/consumer-matrix.md`](docs/reference/consumer-matrix.md)
 - [`docs/reference/public-api.md`](docs/reference/public-api.md)
 - [`docs/reference/integration-guide.md`](docs/reference/integration-guide.md)
+- [`docs/reference/glossary.md`](docs/reference/glossary.md)
 
 ### Wrapper And Agent Path
 
@@ -137,7 +138,9 @@ For the normative API and host contract, use:
 - [`docs/reference/agent-read-models-and-snapshots.md`](docs/reference/agent-read-models-and-snapshots.md)
 - [`docs/reference/agent-workflow-and-suggestions.md`](docs/reference/agent-workflow-and-suggestions.md)
 - [`docs/reference/scope-aware-selection-tooling.md`](docs/reference/scope-aware-selection-tooling.md)
+- [`docs/reference/glossary.md`](docs/reference/glossary.md)
 - [`docs/reference/editor-integration-style.md`](docs/reference/editor-integration-style.md)
+- [`docs/reference/ui-theming-and-styling.md`](docs/reference/ui-theming-and-styling.md)
 - [`docs/reference/beyondwork-runtime-environment.md`](docs/reference/beyondwork-runtime-environment.md)
 
 Wrapper and agent docs stay on `main`, but they are downstream integration guidance rather than the canonical package contract.
@@ -151,6 +154,9 @@ Current integration honesty:
 ### Maintainer Path
 
 - [`docs/maintainers/README.md`](docs/maintainers/README.md)
+- [`docs/ccep-contract-templates/README.md`](docs/ccep-contract-templates/README.md)
+
+The CCEP corpus is kept on `main` as a maintainer-safe smoke-doc source set for agreement-heavy validation and wrapper or agent benchmarking.
 
 Maintainer prompts, operator runbooks, and proof/closure material remain important, but they are not the first reading path for package consumers.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.31",
+  "version": "1.0.33",
   "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

@@ -680,7 +680,8 @@ export type SurfaceInlineSegment =
       detail: string;
       featureKey?: string;
       blockedReasonCode?: "workflow_preserve_only" | "workflow_blocked_import";
-      presentation?: "inline-chip" | "quiet-marker";
+      presentation?: "inline-chip" | "quiet-marker" | "text-box" | "checkbox";
+      displayText?: string;
       state: "locked-preserve-only";
     }
   | {
@@ -1092,6 +1093,7 @@ export interface EditorSessionState {
   warningLog: EditorWarning[];
   protectionSnapshot?: ProtectionSnapshot;
   sourcePackage?: RuntimePersistedEditorSnapshot["sourcePackage"];
+  workflowOverlay?: WorkflowOverlay;
   workflowMetadata?: WorkflowMetadataSnapshot;
 }
 
@@ -1109,6 +1111,7 @@ export interface PersistedEditorSnapshot {
   warningLog: EditorWarning[];
   protectionSnapshot?: ProtectionSnapshot;
   sourcePackage?: RuntimePersistedEditorSnapshot["sourcePackage"];
+  workflowOverlay?: WorkflowOverlay;
   workflowMetadata?: WorkflowMetadataSnapshot;
 }
 
@@ -1218,10 +1221,22 @@ export interface WorkflowBlockedCommandReason {
   message: string;
   scopeId?: string;
   workItemId?: string;
+  fragmentId?: string;
+  label?: string;
+  detail?: string;
   anchor?: EditorAnchorProjection;
   storyTarget?: EditorStoryTarget;
 }
 
+export interface WorkflowLockedZone {
+  fragmentId: string;
+  code: "workflow_preserve_only" | "workflow_blocked_import";
+  label: string;
+  detail: string;
+  anchor: EditorAnchorProjection;
+  storyTarget?: EditorStoryTarget;
+}
+
 export interface WorkflowScopeSnapshot {
   overlayPresent: boolean;
   activeWorkItemId?: string | null;

package/src/api/session-state.ts

@@ -33,6 +33,7 @@ export function editorSessionStateFromPersistedSnapshot(
     warningLog: snapshot.warningLog,
     protectionSnapshot: snapshot.protectionSnapshot,
     sourcePackage: snapshot.sourcePackage,
+    workflowOverlay: snapshot.workflowOverlay,
     workflowMetadata: snapshot.workflowMetadata,
   });
 }
@@ -57,6 +58,7 @@ export function persistedSnapshotFromEditorSessionState(
     warningLog: sessionState.warningLog,
     protectionSnapshot: sessionState.protectionSnapshot,
     sourcePackage: sessionState.sourcePackage,
+    workflowOverlay: sessionState.workflowOverlay,
     workflowMetadata: sessionState.workflowMetadata,
   });
 }

package/src/io/docx-session.ts

@@ -46,7 +46,8 @@ import {
 import {
   buildWorkflowPayloadParts,
   getDocumentBackedWorkflowMetadata,
-  parseWorkflowPayloadFromPackage,
+  parseWorkflowPayloadEnvelopeFromPackage,
+  resolvePayloadPartPath,
   WORKFLOW_PAYLOAD_CONTENT_TYPE,
   WORKFLOW_PAYLOAD_CUSTOM_PROPS_CONTENT_TYPE,
   WORKFLOW_PAYLOAD_CUSTOM_PROPS_PART_PATH,
@@ -54,6 +55,7 @@ import {
   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 {
   classifyCorruptPackageError,
@@ -289,7 +291,9 @@ export function loadDocxEditorSession(
       }),
     );
   }
-  const embeddedWorkflowMetadata = parseWorkflowPayloadFromPackage(sourcePackage);
+  const embeddedWorkflowPayload = parseWorkflowPayloadEnvelopeFromPackage(sourcePackage);
+  const embeddedWorkflowMetadata = embeddedWorkflowPayload?.workflowMetadata;
+  const embeddedWorkflowOverlay = embeddedWorkflowPayload?.workflowOverlay;
 
   const mainDocumentPath = resolveMainDocumentPartPath(sourcePackage);
   const brokenRelationshipIssues = collectBrokenInternalRelationshipIssues(
@@ -718,6 +722,7 @@ export function loadDocxEditorSession(
       compatibility: toPublicCompatibilityReport(compatibility),
       protectionSnapshot: importedProtectionSnapshot,
       sourcePackage: createPersistedSourcePackage(sourceBytes, options.sourceLabel),
+      workflowOverlay: embeddedWorkflowOverlay,
       workflowMetadata: embeddedWorkflowMetadata,
     });
     const snapshotIssues = validatePersistedEditorSnapshot(snapshot);
@@ -828,6 +833,8 @@ function exportDocxEditorSession(
       state.initialCanonicalSignature;
   const canReuse = canReuseSourceBytesForCurrentDocument(state, currentDocument);
   const durableWorkflowMetadata = getDocumentBackedWorkflowMetadata(sessionState.workflowMetadata);
+  const hasWorkflowOverlay = Boolean(sessionState.workflowOverlay);
+  const sourceHasWorkflowPayload = resolvePayloadPartPath(state.sourcePackage) !== null;
   const commentCount = Object.keys(currentDocument.review?.comments ?? {}).length;
   const currentRevisions = toReviewRevisionRecords(currentDocument.review.revisions);
   const hasActiveImportedPreserveOnlyRevisions = currentRevisions.some(
@@ -842,7 +849,9 @@ function exportDocxEditorSession(
     signatureMatch &&
     canReuse &&
     durableWorkflowMetadata.definitions.length === 0 &&
-    durableWorkflowMetadata.entries.length === 0
+    durableWorkflowMetadata.entries.length === 0 &&
+    !hasWorkflowOverlay &&
+    !sourceHasWorkflowPayload
   ) {
     return {
       bytes: new Uint8Array(state.sourceBytes),
@@ -1048,6 +1057,7 @@ function exportDocxEditorSession(
     signatureMatch &&
     durableWorkflowMetadata.definitions.length === 0 &&
     durableWorkflowMetadata.entries.length === 0 &&
+    !hasWorkflowOverlay &&
     commentCount === 0 &&
     hasActiveImportedPreserveOnlyRevisions
       ? state.sourceDocumentXml
@@ -1644,6 +1654,7 @@ function createImportedSnapshot(input: {
   compatibility: PersistedEditorSnapshot["compatibility"];
   protectionSnapshot: ProtectionSnapshot;
   sourcePackage?: PersistedEditorSnapshot["sourcePackage"];
+  workflowOverlay?: PersistedEditorSnapshot["workflowOverlay"];
   workflowMetadata?: PersistedEditorSnapshot["workflowMetadata"];
 }): PersistedEditorSnapshot {
   return {
@@ -1660,6 +1671,7 @@ function createImportedSnapshot(input: {
     warningLog: input.compatibility.warnings,
     protectionSnapshot: input.protectionSnapshot,
     sourcePackage: input.sourcePackage,
+    workflowOverlay: input.workflowOverlay,
     workflowMetadata: input.workflowMetadata,
   };
 }
@@ -2724,6 +2736,7 @@ function ensureWorkflowPayloadParts(
   const payloadParts = buildWorkflowPayloadParts({
     sourcePackage,
     workflowMetadata: sessionState.workflowMetadata,
+    workflowOverlay: sessionState.workflowOverlay,
     documentId: sessionState.documentId,
     createdAt: document.createdAt,
     updatedAt: document.updatedAt,

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

@@ -11,6 +11,7 @@ import type {
   TableRowNode,
   TextMark,
 } from "../../model/canonical-document.ts";
+import { classifyFieldInstruction } from "./parse-fields.ts";
 import {
   readCellBorders,
   readCellShading,
@@ -220,12 +221,7 @@ function parseParagraphElement(pElement: XmlElementNode): ParagraphNode {
       activeComplexField = appendRunNodes(child, children, activeComplexField);
     } else if (name === "hyperlink") {
       if (activeComplexField && activeComplexField.instruction.trim().length > 0) {
-        children.push({
-          type: "field",
-          fieldType: "complex",
-          instruction: activeComplexField.instruction,
-          children: activeComplexField.children,
-        });
+        children.push(createFieldNode(activeComplexField.instruction, "complex", activeComplexField.children));
         activeComplexField = null;
       }
       children.push(parseHyperlinkElement(child));
@@ -235,24 +231,14 @@ function parseParagraphElement(pElement: XmlElementNode): ParagraphNode {
         activeComplexField.children.push(bookmarkNode);
       } else {
         if (activeComplexField && activeComplexField.instruction.trim().length > 0) {
-          children.push({
-            type: "field",
-            fieldType: "complex",
-            instruction: activeComplexField.instruction,
-            children: activeComplexField.children,
-          });
+          children.push(createFieldNode(activeComplexField.instruction, "complex", activeComplexField.children));
           activeComplexField = null;
         }
         children.push(bookmarkNode);
       }
     } else if (name === "fldSimple") {
       if (activeComplexField && activeComplexField.instruction.trim().length > 0) {
-        children.push({
-          type: "field",
-          fieldType: "complex",
-          instruction: activeComplexField.instruction,
-          children: activeComplexField.children,
-        });
+        children.push(createFieldNode(activeComplexField.instruction, "complex", activeComplexField.children));
         activeComplexField = null;
       }
       pushFieldNode(children, child, "simple");
@@ -260,12 +246,7 @@ function parseParagraphElement(pElement: XmlElementNode): ParagraphNode {
   }
 
   if (activeComplexField && activeComplexField.instruction.trim().length > 0) {
-    children.push({
-      type: "field",
-      fieldType: "complex",
-      instruction: activeComplexField.instruction,
-      children: activeComplexField.children,
-    });
+    children.push(createFieldNode(activeComplexField.instruction, "complex", activeComplexField.children));
   }
 
   return {
@@ -307,12 +288,7 @@ function appendRunNodes(
         activeComplexField.mode = "result";
       } else if (fldType === "end" && activeComplexField) {
         if (activeComplexField.instruction.trim().length > 0) {
-          nodes.push({
-            type: "field",
-            fieldType: "complex",
-            instruction: activeComplexField.instruction,
-            children: activeComplexField.children,
-          });
+          nodes.push(createFieldNode(activeComplexField.instruction, "complex", activeComplexField.children));
         }
         activeComplexField = null;
       }
@@ -489,12 +465,26 @@ function pushFieldNode(
     return;
   }
 
-  nodes.push({
+  const classification = classifyFieldInstruction(instruction);
+
+  nodes.push(createFieldNode(instruction, fieldType));
+}
+
+function createFieldNode(
+  instruction: string,
+  fieldType: "simple" | "complex",
+  children: InlineNode[] = [],
+): Extract<InlineNode, { type: "field" }> {
+  const classification = classifyFieldInstruction(instruction);
+  return {
     type: "field",
     fieldType,
     instruction,
-    children: [],
-  });
+    children,
+    fieldFamily: classification.family,
+    ...(classification.target ? { fieldTarget: classification.target } : {}),
+    refreshStatus: classification.supported ? "stale" : "preserve-only",
+  };
 }
 
 function readFieldInstruction(element: XmlElementNode): string | undefined {

package/src/io/ooxml/parse-headers-footers.ts

@@ -274,12 +274,7 @@ function parseParagraphElement(pElement: XmlElementNode): ParagraphNode {
       children.push(parseBookmarkElement(child));
     } else if (name === "fldSimple") {
       if (activeComplexField && activeComplexField.instruction.trim().length > 0) {
-        children.push({
-          type: "field",
-          fieldType: "complex",
-          instruction: activeComplexField.instruction,
-          children: activeComplexField.children,
-        });
+        children.push(createFieldNode(activeComplexField.instruction, "complex", activeComplexField.children));
         activeComplexField = null;
       }
       pushFieldNode(children, child, "simple");
@@ -287,12 +282,7 @@ function parseParagraphElement(pElement: XmlElementNode): ParagraphNode {
   }
 
   if (activeComplexField && activeComplexField.instruction.trim().length > 0) {
-    children.push({
-      type: "field",
-      fieldType: "complex",
-      instruction: activeComplexField.instruction,
-      children: activeComplexField.children,
-    });
+    children.push(createFieldNode(activeComplexField.instruction, "complex", activeComplexField.children));
   }
 
   return {
@@ -335,12 +325,7 @@ function appendRunNodes(
         activeComplexField.mode = "result";
       } else if (fldType === "end" && activeComplexField) {
         if (activeComplexField.instruction.trim().length > 0) {
-          nodes.push({
-            type: "field",
-            fieldType: "complex",
-            instruction: activeComplexField.instruction,
-            children: activeComplexField.children,
-          });
+          nodes.push(createFieldNode(activeComplexField.instruction, "complex", activeComplexField.children));
         }
         activeComplexField = null;
       }
@@ -609,12 +594,26 @@ function pushFieldNode(
     return;
   }
 
-  nodes.push({
+  const classification = classifyFieldInstruction(instruction);
+
+  nodes.push(createFieldNode(instruction, fieldType));
+}
+
+function createFieldNode(
+  instruction: string,
+  fieldType: "simple" | "complex",
+  children: InlineNode[] = [],
+): Extract<InlineNode, { type: "field" }> {
+  const classification = classifyFieldInstruction(instruction);
+  return {
     type: "field",
     fieldType,
     instruction,
-    children: [],
-  });
+    children,
+    fieldFamily: classification.family,
+    ...(classification.target ? { fieldTarget: classification.target } : {}),
+    refreshStatus: classification.supported ? "stale" : "preserve-only",
+  };
 }
 
 function readFieldInstruction(element: XmlElementNode): string | undefined {