@beyondwork/docx-react-component 1.0.33 → 1.0.35

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.33",
+  "version": "1.0.35",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
   "type": "module",
   "sideEffects": [
@@ -130,7 +130,21 @@
     "prosemirror-view": "^1.41.7",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
-    "tailwindcss": "^4.2.2"
+    "tailwindcss": "^4.2.2",
+    "yjs": "^13.6.0",
+    "y-prosemirror": "^1.2.0",
+    "y-protocols": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "yjs": {
+      "optional": true
+    },
+    "y-prosemirror": {
+      "optional": true
+    },
+    "y-protocols": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@chllming/wave-orchestration": "^0.9.15",
@@ -148,7 +162,10 @@
     "react": "19.2.4",
     "react-dom": "19.2.4",
     "tsup": "^8.3.0",
-    "tsx": "^4.21.0"
+    "tsx": "^4.21.0",
+    "y-prosemirror": "^1.3.7",
+    "y-protocols": "^1.0.7",
+    "yjs": "^13.6.30"
   },
   "scripts": {
     "build": "tsup",

package/src/api/public-types.ts

@@ -1,13 +1,8 @@
 import type { PersistedEditorSnapshot as RuntimePersistedEditorSnapshot } from "../core/state/editor-state.ts";
-import type {
-  FieldFamily as FieldFamilyType,
-  FieldRefreshStatus as FieldRefreshStatusType,
-  SupportedFieldFamily as SupportedFieldFamilyType,
-} from "../model/canonical-document.ts";
 
-export type FieldFamily = FieldFamilyType;
-export type FieldRefreshStatus = FieldRefreshStatusType;
-export type SupportedFieldFamily = SupportedFieldFamilyType;
+export type FieldFamily = import("../model/canonical-document.ts").FieldFamily;
+export type FieldRefreshStatus = import("../model/canonical-document.ts").FieldRefreshStatus;
+export type SupportedFieldFamily = import("../model/canonical-document.ts").SupportedFieldFamily;
 
 export type ExternalDocumentSource =
   | {
@@ -1150,6 +1145,7 @@ export interface WorkflowCandidateRange {
 
 export interface WorkflowScope {
   scopeId: string;
+  version?: number;
   mode: WorkflowScopeMode;
   anchor: EditorAnchorProjection;
   storyTarget?: EditorStoryTarget;
@@ -1157,6 +1153,13 @@ export interface WorkflowScope {
   label?: string;
   domain?: "legal" | "commercial" | "finance" | "other";
   metadataRefs?: string[];
+  metadata?: WorkflowScopeMetadataField[];
+}
+
+export interface WorkflowScopeMetadataField {
+  key: string;
+  valueType?: "string" | "number" | "boolean" | "json";
+  value?: string | number | boolean | Record<string, unknown>;
 }
 
 export interface WorkflowWorkItem {
@@ -1930,6 +1933,8 @@ export interface WordReviewEditorChromeOptions {
 export interface WordReviewEditorProps {
   documentId: string;
   currentUser: EditorUser;
+  ydoc?: import('yjs').Doc;
+  awareness?: import("y-protocols/awareness").Awareness;
   initialDocx?: Uint8Array | ArrayBuffer;
   initialSessionState?: EditorSessionState;
   initialSnapshot?: PersistedEditorSnapshot;

package/src/api/session-state.ts

@@ -2,6 +2,10 @@ import type {
   EditorSessionState,
   PersistedEditorSnapshot,
 } from "./public-types.ts";
+import {
+  assertPersistedEditorSnapshot,
+  validatePersistedEditorSnapshot,
+} from "../model/snapshot.ts";
 
 export const EDITOR_SESSION_STATE_VERSION = "editor-session-state/1" as const;
 
@@ -62,3 +66,23 @@ export function persistedSnapshotFromEditorSessionState(
     workflowMetadata: sessionState.workflowMetadata,
   });
 }
+
+export function validateEditorSessionState(
+  sessionState: EditorSessionState,
+): ReturnType<typeof validatePersistedEditorSnapshot> {
+  return validatePersistedEditorSnapshot(
+    persistedSnapshotFromEditorSessionState(sessionState, {
+      savedAt: sessionState.updatedAt,
+    }),
+  );
+}
+
+export function assertEditorSessionState(
+  sessionState: EditorSessionState,
+): void {
+  assertPersistedEditorSnapshot(
+    persistedSnapshotFromEditorSessionState(sessionState, {
+      savedAt: sessionState.updatedAt,
+    }),
+  );
+}

package/src/core/commands/index.ts

@@ -1365,6 +1365,59 @@ function applySuggestingInsert(
       result.mapping,
     );
 
+    // Extend an existing adjacent insertion revision if the cursor is right at its end.
+    // After remapping, a prior insertion revision's `to` stays at `insertedFrom` (assoc.end = -1),
+    // so consecutive keystrokes coalesce into one revision instead of one per character.
+    const existingInsertion = findAdjacentInsertionRevision(
+      reviewState.document.review.revisions,
+      insertedFrom,
+      authorId,
+    );
+
+    if (existingInsertion && existingInsertion.anchor.kind === "range") {
+      const updatedRevision: CanonicalRevisionRecord = {
+        ...existingInsertion,
+        anchor: {
+          kind: "range",
+          range: { from: existingInsertion.anchor.range.from, to: insertedTo },
+          assoc: { start: 1, end: -1 },
+        },
+      };
+
+      const finalDocument: CanonicalDocumentEnvelope = {
+        ...reviewState.document,
+        review: {
+          ...reviewState.document.review,
+          revisions: {
+            ...reviewState.document.review.revisions,
+            [updatedRevision.changeId]: updatedRevision,
+          },
+        },
+      };
+
+      return createTransaction(
+        {
+          ...state,
+          document: finalDocument,
+          selection: result.selection,
+          warnings: reviewState.warnings,
+          runtime: {
+            ...state.runtime,
+            activeCommentId: reviewState.activeCommentId,
+          },
+        },
+        {
+          historyBoundary: "push",
+          markDirty: true,
+          mapping: result.mapping,
+          effects: {
+            ...reviewState.effects,
+            revisionAuthored: { changeId: updatedRevision.changeId, kind: "insertion" },
+          },
+        },
+      );
+    }
+
     // Create the revision with pre-mapping positions — it refers to content
     // that was just inserted, so its anchors are already correct in the new document
     const revision = createAuthoredRevision(
@@ -1850,6 +1903,26 @@ function applySuggestingParagraphSplit(
   );
 }
 
+function findAdjacentInsertionRevision(
+  revisions: Record<string, CanonicalRevisionRecord>,
+  cursorPos: number,
+  authorId: string,
+): CanonicalRevisionRecord | undefined {
+  for (const revision of Object.values(revisions)) {
+    if (
+      revision.kind === "insertion" &&
+      revision.status === "open" &&
+      revision.metadata?.source === "runtime" &&
+      revision.anchor.kind === "range" &&
+      revision.anchor.range.to === cursorPos &&
+      revision.authorId === authorId
+    ) {
+      return revision;
+    }
+  }
+  return undefined;
+}
+
 function findOverlappingAuthoredDeletion(
   revisions: Record<string, CanonicalRevisionRecord>,
   from: number,

package/src/index.ts

@@ -1,8 +1,10 @@
 export { WordReviewEditor } from "./ui/WordReviewEditor.tsx";
 export {
   createEditorSessionState,
+  assertEditorSessionState,
   editorSessionStateFromPersistedSnapshot,
   persistedSnapshotFromEditorSessionState,
+  validateEditorSessionState,
   EDITOR_SESSION_STATE_VERSION,
 } from "./api/session-state.ts";
 export type {

package/src/io/docx-session.ts

@@ -9,6 +9,11 @@ import type {
   PersistedEditorSnapshot,
   ProtectionRange,
   ProtectionSnapshot,
+  WorkflowMetadataSnapshot,
+  WorkflowOverlay,
+  WorkflowScope,
+  WorkflowScopeMetadataField,
+  WorkflowWorkItem,
 } from "../api/public-types.ts";
 import { editorSessionStateFromPersistedSnapshot } from "../api/session-state.ts";
 import type {
@@ -655,6 +660,12 @@ export function loadDocxEditorSession(
         : undefined;
 
     const timestamp = new Date().toISOString();
+    const translatedWorkflowState = translateClmCommentsToWorkflow({
+      comments: normalizedComments.threads,
+      workflowOverlay: embeddedWorkflowOverlay,
+      workflowMetadata: embeddedWorkflowMetadata,
+      timestamp,
+    });
     const document = createImportedCanonicalDocument({
       documentId: options.documentId,
       timestamp,
@@ -703,7 +714,7 @@ export function loadDocxEditorSession(
         errors: [],
       },
       review: {
-        comments: toRuntimeCommentRecords(normalizedComments.threads),
+        comments: toRuntimeCommentRecords(translatedWorkflowState.comments),
         revisions: toRuntimeRevisionRecords([
           ...normalizedRevisions.revisions,
           ...importedStoryRevisions,
@@ -722,8 +733,8 @@ export function loadDocxEditorSession(
       compatibility: toPublicCompatibilityReport(compatibility),
       protectionSnapshot: importedProtectionSnapshot,
       sourcePackage: createPersistedSourcePackage(sourceBytes, options.sourceLabel),
-      workflowOverlay: embeddedWorkflowOverlay,
-      workflowMetadata: embeddedWorkflowMetadata,
+      workflowOverlay: translatedWorkflowState.workflowOverlay,
+      workflowMetadata: translatedWorkflowState.workflowMetadata,
     });
     const snapshotIssues = validatePersistedEditorSnapshot(snapshot);
     if (snapshotIssues.length > 0) {
@@ -1940,6 +1951,252 @@ function normalizeImportedCommentThreads(
   };
 }
 
+function translateClmCommentsToWorkflow(input: {
+  comments: readonly CommentThread[];
+  workflowOverlay?: WorkflowOverlay;
+  workflowMetadata?: WorkflowMetadataSnapshot;
+  timestamp: string;
+}): {
+  comments: CommentThread[];
+  workflowOverlay?: WorkflowOverlay;
+  workflowMetadata?: WorkflowMetadataSnapshot;
+} {
+  const nextComments = input.comments.map((thread) => structuredClone(thread));
+  let nextOverlay = input.workflowOverlay ? structuredClone(input.workflowOverlay) : undefined;
+  let overlayChanged = false;
+
+  for (const [index, thread] of nextComments.entries()) {
+    const directive = parseClmCommentDirective(thread);
+    if (!directive || thread.anchor.kind !== "range") {
+      continue;
+    }
+
+    if (!nextOverlay) {
+      nextOverlay = {
+        overlayVersion: "workflow-overlay/1",
+        scopes: [],
+      };
+    }
+
+    const existingScope = findExistingClmScope(nextOverlay.scopes, directive);
+    if (!existingScope) {
+      const version = getNextClmScopeVersion(nextOverlay.scopes, thread.anchor);
+      const scopeId = `clm-scope-${thread.commentId}-v${version}`;
+      const workItem = directive.tag === "TASK"
+        ? createClmWorkflowWorkItem(thread, directive.description, scopeId)
+        : undefined;
+      const scope = createClmWorkflowScope(thread, directive, version, scopeId, workItem?.workItemId);
+
+      nextOverlay.scopes = [...nextOverlay.scopes, scope];
+      if (workItem) {
+        nextOverlay.workItems = [...(nextOverlay.workItems ?? []), workItem];
+        if (!nextOverlay.activeWorkItemId) {
+          nextOverlay.activeWorkItemId = workItem.workItemId;
+        }
+      }
+      overlayChanged = true;
+    }
+
+    nextComments[index] = resolveImportedCommentThreadOnTranslation(thread, input.timestamp);
+  }
+
+  return {
+    comments: nextComments,
+    workflowOverlay: overlayChanged || input.workflowOverlay ? nextOverlay : undefined,
+    workflowMetadata: input.workflowMetadata,
+  };
+}
+
+function parseClmCommentDirective(
+  thread: CommentThread,
+): { tag: "TASK" | "READ" | "COMMENT" | "EDIT"; description: string; sourceCommentId: string; sourceCommentDurableId?: string; sourceCommentParaId?: string; mode: WorkflowScope["mode"] } | undefined {
+  if (thread.metadata?.rootParaId === undefined && thread.entries[0]?.metadata?.parentParaId) {
+    return undefined;
+  }
+  const firstMeaningfulLine = thread.entries
+    .flatMap((entry) => entry.body.split(/\r?\n/u))
+    .map((line) => line.trim())
+    .find((line) => line.length > 0);
+  if (!firstMeaningfulLine) {
+    return undefined;
+  }
+  const match = /^CLM:([A-Z]+):(.*)$/u.exec(firstMeaningfulLine);
+  if (!match) {
+    return undefined;
+  }
+  const tag = match[1] as "TASK" | "READ" | "COMMENT" | "EDIT";
+  const description = (match[2] ?? "").trim();
+  const mode = getClmWorkflowScopeMode(tag);
+  if (!mode || description.length === 0) {
+    return undefined;
+  }
+  return {
+    tag,
+    description,
+    sourceCommentId: thread.metadata?.rootOoxmlCommentId ?? thread.commentId,
+    sourceCommentDurableId: thread.entries[0]?.metadata?.durableId,
+    sourceCommentParaId: thread.metadata?.rootParaId ?? thread.entries[0]?.metadata?.paraId,
+    mode,
+  };
+}
+
+function getClmWorkflowScopeMode(tag: string): WorkflowScope["mode"] | undefined {
+  switch (tag) {
+    case "TASK":
+      return "suggest";
+    case "READ":
+      return "view";
+    case "COMMENT":
+      return "comment";
+    case "EDIT":
+      return "edit";
+    default:
+      return undefined;
+  }
+}
+
+function createClmWorkflowWorkItem(
+  thread: CommentThread,
+  description: string,
+  scopeId: string,
+): WorkflowWorkItem {
+  return {
+    workItemId: `clm-task-${thread.commentId}`,
+    title: description,
+    description,
+    status: "pending",
+    scopeIds: [scopeId],
+  };
+}
+
+function createClmWorkflowScope(
+  thread: CommentThread,
+  directive: NonNullable<ReturnType<typeof parseClmCommentDirective>>,
+  version: number,
+  scopeId: string,
+  workItemId?: string,
+): WorkflowScope {
+  if (workItemId) {
+    return {
+      scopeId,
+      version,
+      mode: directive.mode,
+      anchor: toPublicAnchorProjection(thread.anchor),
+      storyTarget: { kind: "main" },
+      workItemId,
+      label: directive.description,
+      metadata: createClmScopeMetadata(directive),
+    };
+  }
+  return {
+    scopeId,
+    version,
+    mode: directive.mode,
+    anchor: toPublicAnchorProjection(thread.anchor),
+    storyTarget: { kind: "main" },
+    label: directive.description,
+    metadata: createClmScopeMetadata(directive),
+  };
+}
+
+function createClmScopeMetadata(
+  directive: NonNullable<ReturnType<typeof parseClmCommentDirective>>,
+): WorkflowScopeMetadataField[] {
+  return [
+    {
+      key: "workblock.clm.tag",
+      valueType: "string",
+      value: directive.tag,
+    },
+    {
+      key: "workblock.clm.description",
+      valueType: "string",
+      value: directive.description,
+    },
+    {
+      key: "workblock.sourceCommentId",
+      valueType: "string",
+      value: directive.sourceCommentId,
+    },
+    ...(directive.sourceCommentDurableId
+      ? [{
+          key: "workblock.sourceCommentDurableId",
+          valueType: "string" as const,
+          value: directive.sourceCommentDurableId,
+        }]
+      : []),
+    ...(directive.sourceCommentParaId
+      ? [{
+          key: "workblock.sourceCommentParaId",
+          valueType: "string" as const,
+          value: directive.sourceCommentParaId,
+        }]
+      : []),
+  ];
+}
+
+function findExistingClmScope(
+  scopes: readonly WorkflowScope[],
+  directive: NonNullable<ReturnType<typeof parseClmCommentDirective>>,
+): WorkflowScope | undefined {
+  return scopes.find((scope) => {
+    const sourceCommentId = getWorkflowScopeMetadataValue(scope.metadata, "workblock.sourceCommentId");
+    const sourceCommentDurableId = getWorkflowScopeMetadataValue(
+      scope.metadata,
+      "workblock.sourceCommentDurableId",
+    );
+    return (
+      sourceCommentId === directive.sourceCommentId ||
+      (directive.sourceCommentDurableId !== undefined &&
+        sourceCommentDurableId === directive.sourceCommentDurableId)
+    );
+  });
+}
+
+function getWorkflowScopeMetadataValue(
+  metadata: WorkflowScope["metadata"] | undefined,
+  key: string,
+): string | undefined {
+  const field = metadata?.find((entry) => entry.key === key);
+  return typeof field?.value === "string" ? field.value : undefined;
+}
+
+function getNextClmScopeVersion(
+  scopes: readonly WorkflowScope[],
+  anchor: Extract<CommentThread["anchor"], { kind: "range" }>,
+): number {
+  const anchorRange = {
+    from: anchor.range.from,
+    to: anchor.range.to,
+  };
+  const overlappingVersions = scopes.flatMap((scope) => {
+    if (scope.anchor.kind !== "range") {
+      return [];
+    }
+    return rangesIntersect(scope.anchor, anchorRange) && typeof scope.version === "number"
+      ? [scope.version]
+      : [];
+  });
+  return overlappingVersions.length > 0 ? Math.max(...overlappingVersions) + 1 : 1;
+}
+
+function resolveImportedCommentThreadOnTranslation(
+  thread: CommentThread,
+  timestamp: string,
+): CommentThread {
+  if (thread.status === "resolved") {
+    return thread;
+  }
+  return {
+    ...thread,
+    status: thread.status === "detached" ? "detached" : "resolved",
+    resolution: thread.resolution ?? {
+      resolvedAt: timestamp,
+      resolvedBy: thread.entries[thread.entries.length - 1]?.authorId ?? thread.createdBy,
+    },
+  };
+}
+
 function resolveDefinitionRootCommentId(
   definition: ImportedCommentDefinition,
   definitions: readonly ImportedCommentDefinition[],

package/src/io/ooxml/workflow-payload.ts

@@ -371,19 +371,46 @@ function buildWorkblockExtensionXml(workflowOverlay: WorkflowOverlay | undefined
 }
 
 function buildWorkflowScopeXml(scope: WorkflowScope): string {
+  const scopeMetadataXml = buildWorkflowScopeMetadataXml(scope.metadata);
   return [
     `<bw:scope`,
     ` id="${escapeXml(scope.scopeId)}"`,
+    typeof scope.version === "number" ? ` version="${String(scope.version)}"` : "",
     ` mode="${escapeXml(scope.mode)}"`,
     scope.workItemId ? ` workItemRef="${escapeXml(scope.workItemId)}"` : "",
     scope.label ? ` label="${escapeXml(scope.label)}"` : "",
     scope.domain ? ` domain="${escapeXml(scope.domain)}"` : "",
     `>`,
     indentLines(buildWorkflowAnchorXml(scope.anchor, scope.storyTarget), 2),
+    scopeMetadataXml ? indentLines(scopeMetadataXml, 2) : "",
     `</bw:scope>`,
   ].join("");
 }
 
+function buildWorkflowScopeMetadataXml(scopeMetadata: WorkflowScope["metadata"]): string {
+  if (!scopeMetadata || scopeMetadata.length === 0) {
+    return "";
+  }
+  return [
+    `<bw:scopeMetadata>`,
+    indentLines(
+      scopeMetadata
+        .map((field) => {
+          const serialized = serializeWorkflowScopeMetadataValue(field.valueType, field.value);
+          return [
+            `<bw:field`,
+            ` key="${escapeXml(field.key)}"`,
+            serialized.valueType ? ` type="${escapeXml(serialized.valueType)}"` : "",
+            `>${escapeXml(serialized.text)}</bw:field>`,
+          ].join("");
+        })
+        .join("\n"),
+      2,
+    ),
+    `</bw:scopeMetadata>`,
+  ].join("\n");
+}
+
 function buildWorkflowAnchorXml(
   anchor: EditorAnchorProjection,
   storyTarget: WorkflowScope["storyTarget"],
@@ -563,15 +590,110 @@ function parseWorkflowScope(attributesSource: string, body: string): WorkflowSco
     : createDefaultRangeAnchor(0, 0);
   return {
     scopeId: attributes.id,
+    version: attributes.version !== undefined ? Number(attributes.version) : undefined,
     mode: attributes.mode as WorkflowScope["mode"],
     anchor,
     storyTarget: anchorMatch ? parseOverlayStoryTarget(parseAttributes(anchorMatch[1] ?? "")) : { kind: "main" },
     workItemId: attributes.workItemRef,
     label: attributes.label,
     domain: attributes.domain as WorkflowScope["domain"],
+    metadata: parseWorkflowScopeMetadata(body),
+  };
+}
+
+function parseWorkflowScopeMetadata(body: string): WorkflowScope["metadata"] | undefined {
+  const metadataMatch = body.match(/<bw:scopeMetadata\b[^>]*>([\s\S]*?)<\/bw:scopeMetadata>/u);
+  if (!metadataMatch) {
+    return undefined;
+  }
+  const fields = [...(metadataMatch[1] ?? "").matchAll(/<bw:field\b([^>]*)>([\s\S]*?)<\/bw:field>/gu)]
+    .map((match) => parseWorkflowScopeMetadataField(match[1] ?? "", match[2] ?? ""))
+    .filter((field): field is NonNullable<WorkflowScope["metadata"]>[number] => field !== null);
+  return fields.length > 0 ? fields : undefined;
+}
+
+function parseWorkflowScopeMetadataField(
+  attributesSource: string,
+  body: string,
+): NonNullable<WorkflowScope["metadata"]>[number] | null {
+  const attributes = parseAttributes(attributesSource);
+  if (!attributes.key) {
+    return null;
+  }
+  const valueType = attributes.type as NonNullable<WorkflowScope["metadata"]>[number]["valueType"] | undefined;
+  return {
+    key: attributes.key,
+    ...(valueType ? { valueType } : {}),
+    value: parseWorkflowScopeMetadataValue(valueType, body),
+  };
+}
+
+function serializeWorkflowScopeMetadataValue(
+  valueType: NonNullable<WorkflowScope["metadata"]>[number]["valueType"],
+  value: NonNullable<WorkflowScope["metadata"]>[number]["value"],
+): { valueType?: "string" | "number" | "boolean" | "json"; text: string } {
+  const resolvedValueType =
+    valueType ??
+    (typeof value === "number"
+      ? "number"
+      : typeof value === "boolean"
+        ? "boolean"
+        : typeof value === "string"
+          ? "string"
+          : value && typeof value === "object"
+            ? "json"
+            : undefined);
+
+  if (resolvedValueType === "json") {
+    return {
+      valueType: "json",
+      text: JSON.stringify(value ?? {}),
+    };
+  }
+  if (resolvedValueType === "number") {
+    return {
+      valueType: "number",
+      text: typeof value === "number" ? String(value) : "0",
+    };
+  }
+  if (resolvedValueType === "boolean") {
+    return {
+      valueType: "boolean",
+      text: String(value === true),
+    };
+  }
+  return {
+    valueType: resolvedValueType,
+    text: typeof value === "string" ? value : value === undefined ? "" : String(value),
   };
 }
 
+function parseWorkflowScopeMetadataValue(
+  valueType: NonNullable<WorkflowScope["metadata"]>[number]["valueType"],
+  payloadText: string,
+): NonNullable<WorkflowScope["metadata"]>[number]["value"] {
+  const decodedText = decodeXmlEntities(payloadText);
+  if (valueType === "json") {
+    try {
+      const parsed = JSON.parse(decodedText) as unknown;
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        return parsed as Record<string, unknown>;
+      }
+      return { value: parsed };
+    } catch {
+      return { value: decodedText };
+    }
+  }
+  if (valueType === "number") {
+    const numericValue = Number(decodedText);
+    return Number.isFinite(numericValue) ? numericValue : 0;
+  }
+  if (valueType === "boolean") {
+    return decodedText === "true" || decodedText === "1";
+  }
+  return decodedText;
+}
+
 function parseWorkflowWorkItem(attributesSource: string, body: string): WorkflowWorkItem | null {
   const attributes = parseAttributes(attributesSource);
   if (!attributes.id || !attributes.title) {