@beyondwork/docx-react-component 1.0.41 → 1.0.43

package/package.json

@@ -1,9 +1,8 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.41",
+  "version": "1.0.43",
   "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"
@@ -93,31 +92,6 @@
     "./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/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",
-    "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",
-    "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",
@@ -162,22 +136,29 @@
     "react-dom": "^19.2.0",
     "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",
+    "@playwright/test": "^1.59.1",
     "@types/react": "19.2.14",
     "@types/react-dom": "19.2.3",
     "@typescript/native-preview": "7.0.0-dev.20260409.1",
     "jsdom": "^29.0.1",
+    "pixelmatch": "^7.1.0",
+    "pngjs": "^7.0.0",
     "prosemirror-commands": "^1.7.1",
     "prosemirror-keymap": "^1.2.3",
     "prosemirror-model": "^1.25.4",
@@ -189,17 +170,37 @@
     "react-dom": "19.2.4",
     "tsup": "^8.3.0",
     "tsx": "^4.21.0",
+    "y-prosemirror": "^1.3.7",
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.30"
   },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild",
-      "sharp"
-    ],
-    "overrides": {
-      "react": "19.2.4",
-      "react-dom": "19.2.4"
-    }
+  "scripts": {
+    "build": "tsup",
+    "test": "bash scripts/run-workspace-tests.sh",
+    "test:repo": "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",
+    "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"
   }
-}
+}

package/src/api/awareness-identity-types.ts

@@ -0,0 +1,35 @@
+/**
+ * Typed shape carried in the Awareness `identity` field. One per
+ * connected client. Written by the local client on attach; read by
+ * every client to build `PresenceSnapshot`.
+ */
+export interface AwarenessIdentity {
+  userId: string;
+  displayName: string;
+  collabIdentity?: string;
+  role: "author" | "reviewer" | "observer";
+  authorKind: "human" | "agent" | "system";
+  /** Identifier of the story the peer is currently looking at, if any. */
+  activeStoryId?: string;
+}
+
+export interface AwarenessPeer extends AwarenessIdentity {
+  /** `Awareness`-local client id. Advisory — hosts should prefer `userId`. */
+  clientId: number;
+}
+
+export type TransportStatus = "connected" | "syncing" | "offline";
+
+export interface PresenceSnapshot {
+  peers: AwarenessPeer[];
+  transportStatus: TransportStatus;
+  /** Count of mutations queued locally while offline. */
+  queuedLocalEvents: number;
+}
+
+export interface CollabPosture {
+  role: "author" | "reviewer" | "observer";
+  transport: "none" | "attached";
+  /** Count of other connected peers (self excluded). */
+  peers: number;
+}

package/src/api/comment-negotiation-types.ts

@@ -0,0 +1,130 @@
+export type CommentNegotiationState =
+  | "proposed"
+  | "negotiating"
+  | "accepted"
+  | "rejected"
+  | "resolved";
+
+export interface NegotiationVote {
+  authorId: string;
+  verdict: "approve" | "reject" | "abstain";
+  castAt: string;
+}
+
+export interface NegotiationCounterProposal {
+  id: string;
+  authorId: string;
+  createdAt: string;
+  body: string;
+  proposedRangeEdit?: {
+    kind: "replace" | "insert" | "delete";
+    start: number;
+    end: number;
+    text?: string;
+  };
+  supersededBy?: string;
+}
+
+export type CommentNegotiationActionType =
+  | "propose-change"
+  | "counter-propose"
+  | "vote"
+  | "accept"
+  | "reject"
+  | "lock"
+  | "reopen";
+
+export interface NegotiationHistoryRow {
+  from: CommentNegotiationState;
+  to: CommentNegotiationState;
+  actorId: string;
+  at: string;
+  action: CommentNegotiationActionType;
+  reasonCode?: string;
+}
+
+export interface CommentNegotiationEntry {
+  commentId: string;
+  state: CommentNegotiationState;
+  requiredApprovers: string[];
+  votes: NegotiationVote[];
+  counterProposals: NegotiationCounterProposal[];
+  acceptedProposalId?: string;
+  lockedAt?: string;
+  lockedBy?: string;
+  history: NegotiationHistoryRow[];
+}
+
+export interface CommentNegotiationSnapshot {
+  schemaVersion: 1;
+  entries: CommentNegotiationEntry[];
+}
+
+export type CommentNegotiationAction =
+  | {
+      type: "propose-change";
+      commentId: string;
+      actorId: string;
+      counterProposalId?: string;
+    }
+  | {
+      type: "counter-propose";
+      commentId: string;
+      authorId: string;
+      proposalId: string;
+      body: string;
+      createdAt: string;
+      proposedRangeEdit?: NegotiationCounterProposal["proposedRangeEdit"];
+    }
+  | {
+      type: "vote";
+      commentId: string;
+      authorId: string;
+      verdict: NegotiationVote["verdict"];
+    }
+  | {
+      type: "accept";
+      commentId: string;
+      actorId: string;
+      acceptedProposalId?: string;
+    }
+  | {
+      type: "reject";
+      commentId: string;
+      actorId: string;
+      reasonCode?: string;
+    }
+  | {
+      type: "lock";
+      commentId: string;
+      actorId: string;
+    }
+  | {
+      type: "reopen";
+      commentId: string;
+      actorId: string;
+    };
+
+export type NegotiationRole = "author" | "reviewer" | "observer";
+
+export type NegotiationBlockReason =
+  | "negotiation_invalid_transition"
+  | "negotiation_quorum_not_met"
+  | "collab_observer_readonly"
+  | "collab_role_restricted";
+
+/**
+ * Superset of every `ok: false` reason the collab runtime surface can
+ * return. Kept in one place so hosts + agents can narrow once and
+ * handle every case.
+ *
+ * - `NegotiationBlockReason` — reducer-level role + state-machine checks.
+ * - `"metadata_tampered"` — raised by the tamper gate + external-send
+ *   pipeline when `metadataIntegrity === "tampered"`.
+ * - `"collab_not_attached"` — raised by the session facet / bridge when
+ *   callers dispatch before a `Y.Doc` is wired.
+ */
+export type CollabBlockReason =
+  | NegotiationBlockReason
+  | "metadata_tampered"
+  | "collab_not_attached";

package/src/api/comment-presentation-types.ts

@@ -0,0 +1,106 @@
+export type CommentAudience = "internal" | "external" | "shared";
+
+export interface CommentMention {
+  userId: string;
+  displayName: string;
+  offsetInBody: number;
+  entryId?: string;
+}
+
+export interface CommentAttachment {
+  id: string;
+  kind: "image" | "file" | "link";
+  displayName: string;
+  mimeType?: string;
+  relationshipId?: string;
+  href?: string;
+  byteLength?: number;
+  width?: number;
+  height?: number;
+}
+
+export interface CommentReaction {
+  emoji: string;
+  authorId: string;
+  reactedAt: string;
+}
+
+export interface CommentLabel {
+  key: string;
+  text: string;
+  color?: string;
+}
+
+export interface CommentBody {
+  format: "markdown";
+  text: string;
+  digest: string;
+  sanitized?: boolean;
+}
+
+export interface CommentPresentationReply {
+  entryId: string;
+  body: CommentBody;
+}
+
+export interface CommentPresentation {
+  commentId: string;
+  audience: CommentAudience;
+  body: CommentBody;
+  replies: CommentPresentationReply[];
+  mentions: CommentMention[];
+  attachments: CommentAttachment[];
+  reactions: CommentReaction[];
+  labels: CommentLabel[];
+}
+
+export interface CommentPresentationSnapshot {
+  schemaVersion: 1;
+  entries: CommentPresentation[];
+}
+
+export type CommentPresentationAction =
+  | {
+      type: "set-body";
+      commentId: string;
+      text: string;
+      audience?: CommentAudience;
+    }
+  | {
+      type: "set-audience";
+      commentId: string;
+      audience: CommentAudience;
+    }
+  | {
+      type: "set-reply-body";
+      commentId: string;
+      entryId: string;
+      text: string;
+    }
+  | {
+      type: "add-mention";
+      commentId: string;
+      mention: CommentMention;
+    }
+  | {
+      type: "add-attachment";
+      commentId: string;
+      attachment: CommentAttachment;
+    }
+  | {
+      type: "remove-attachment";
+      commentId: string;
+      attachmentId: string;
+    }
+  | {
+      type: "toggle-reaction";
+      commentId: string;
+      authorId: string;
+      emoji: string;
+      now: string;
+    }
+  | {
+      type: "set-labels";
+      commentId: string;
+      labels: CommentLabel[];
+    };

package/src/api/editor-state-types.ts

@@ -0,0 +1,110 @@
+/**
+ * Editor-State Persistence Channel (schema 1.2).
+ *
+ * Makes the .docx act as a load/save API for editor-level overlay
+ * state (host annotations, workflow overlay, workflow metadata, work
+ * items, and future subsystems).  Storage policy per subsystem is
+ * host-controlled across three locations:
+ *
+ * - `"in-document"`  — full blob serialized into /customXml/item1.xml
+ * - `"rowstore"`     — doc carries a key reference; host persists the blob
+ * - `"key-only"`     — doc carries only a correlation key; host rehydrates
+ *
+ * See docs/plans/editor-state-persistence.md for the full design.  1.2
+ * extends schema 1.1 additively (unknown namespaces are preserved
+ * opaquely per existing forward-compat rules).
+ */
+export type EditorStateNamespace =
+  | "hostAnnotations"
+  | "workflowOverlay"
+  | "workflowMetadata"
+  | "workItems";
+
+export type EditorStateLocation = "in-document" | "rowstore" | "key-only";
+
+export type EditorStateResolveErrorMode = "block" | "empty" | "retain-last-known";
+
+/**
+ * Host-configured per-namespace persistence policy.  Default (when
+ * absent) is {location: "in-document", onResolveError: "block",
+ * debounceMs: 250}, which preserves current behavior.
+ */
+export interface EditorStatePolicyEntry {
+  location: EditorStateLocation;
+  /** Host-provided correlation key (e.g. review_session_id). Editor generates a UUID if absent. */
+  key?: string;
+  onResolveError?: EditorStateResolveErrorMode;
+  debounceMs?: number;
+}
+
+export type EditorStatePolicy = Partial<
+  Record<EditorStateNamespace, EditorStatePolicyEntry>
+>;
+
+/**
+ * Reference stored in the docx when the subsystem is backed by a
+ * host-owned store.  The editor never interprets entryKey — it round-
+ * trips verbatim via resolver + persister callbacks.
+ */
+export interface EditorStateStorageRef {
+  namespace: EditorStateNamespace;
+  location: Exclude<EditorStateLocation, "in-document">;
+  entryKey: string;
+  schemaVersion: string;
+}
+
+/**
+ * Typed blob the resolver returns and the persister accepts.
+ * `data` is the subsystem-specific payload (e.g. a HostAnnotationOverlay
+ * for the "hostAnnotations" namespace).  Use `schemaVersion` to pin the
+ * blob shape so older hosts don't silently load newer blobs.
+ */
+export interface EditorStateBlob {
+  namespace: EditorStateNamespace;
+  schemaVersion: string;
+  data: unknown;
+}
+
+/**
+ * Host-supplied pull-resolver.  Returns `null` when the entry key is
+ * unknown or revoked.  Matches the ScopeMetadataResolver undefined
+ * convention but allows null explicitly per the design doc §5 for
+ * symmetry with Promise<T | null> idioms.  Either is acceptable as
+ * "not found"; internal code normalizes.
+ */
+export type EditorStateResolver = (
+  namespace: EditorStateNamespace,
+  entryKey: string,
+) => Promise<EditorStateBlob | null>;
+
+/**
+ * Host-supplied persister.  Called after the editor's debounce window
+ * when a subsystem's state has changed under `rowstore` or `key-only`
+ * policy.  Must be idempotent within the debounce window.
+ */
+export type EditorStatePersister = (
+  namespace: EditorStateNamespace,
+  entryKey: string,
+  blob: EditorStateBlob,
+) => Promise<void>;
+
+export interface EditorStatePolicyMigration {
+  namespace: EditorStateNamespace;
+  from: EditorStateLocation;
+  to: EditorStateLocation;
+  key?: string;
+}
+
+export interface EditorStatePartLoadFailure {
+  namespace: EditorStateNamespace;
+  entryKey?: string;
+  error: Error;
+  fallback: "empty" | "retain-last-known";
+}
+
+export interface EditorStatePartPersistFailure {
+  namespace: EditorStateNamespace;
+  entryKey: string;
+  error: Error;
+  attemptCount: number;
+}

package/src/api/external-custody-types.ts

@@ -0,0 +1,74 @@
+import type {
+  CommentNegotiationEntry,
+} from "./comment-negotiation-types.ts";
+import type {
+  CommentPresentation,
+} from "./comment-presentation-types.ts";
+import type { Participant } from "./participants-types.ts";
+
+/**
+ * Custody receipt attached to a docx when internal comments have been
+ * stripped out and sent to an external recipient (supplier). The receipt
+ * rides inside `bw:extensions/bw:externalCustody` and points at an
+ * opaque host archive that a later re-import uses to restore the
+ * stripped content.
+ *
+ * See docs/reference/bw-collab-schema-additions.md §bw:externalCustody
+ * for the normative schema.
+ */
+export interface ExternalCustody {
+  schemaVersion: 1;
+  custodyId: string;
+  originDocumentId: string;
+  originPayloadId: string;
+  /** sha256:{hex} of canonicalized word/document.xml at send time. */
+  originContentHash: string;
+  sentAt: string;
+  sentBy: string;
+  /** Opaque recipient identifier (supplier user or orgId). */
+  recipient: string;
+  /**
+   * Opaque host-owned reference the resolver uses to fetch the
+   * stripped-out internal content on re-upload. Not interpreted by
+   * this library.
+   */
+  archiveRef: string;
+  strippedCommentIds: string[];
+  strippedParticipantIds: string[];
+}
+
+/**
+ * Payload handed to the host resolver when internal content is archived
+ * during `sendToExternal`. The host persists this opaque bundle keyed
+ * by `custodyId` for later `restore` calls.
+ */
+export interface ExternalCustodyArchivePayload {
+  custodyId: string;
+  strippedPresentation: CommentPresentation[];
+  strippedNegotiation: CommentNegotiationEntry[];
+  strippedParticipants: Participant[];
+  originContentHash: string;
+}
+
+/**
+ * Content returned by the host resolver on `restore`. Same shape as
+ * what was archived, minus the custody ID.
+ */
+export interface ExternalCustodyRestoredContent {
+  presentation: CommentPresentation[];
+  negotiation: CommentNegotiationEntry[];
+  participants: Participant[];
+}
+
+/**
+ * Host-owned contract. The editor hands archive + restore calls through
+ * this so the library never directly persists internal content.
+ */
+export interface ExternalCustodyResolver {
+  archive(payload: ExternalCustodyArchivePayload): Promise<void>;
+  restore(args: {
+    custodyId: string;
+    originContentHash: string;
+  }): Promise<ExternalCustodyRestoredContent | undefined>;
+  delete?(custodyId: string): Promise<void>;
+}

package/src/api/participants-types.ts

@@ -0,0 +1,18 @@
+export type ParticipantRole = "author" | "reviewer" | "observer";
+export type AuthorKind = "human" | "agent" | "system";
+
+export interface Participant {
+  userId: string;
+  email: string;
+  displayName: string;
+  collabIdentity: string;
+  authorKind: AuthorKind;
+  role?: ParticipantRole;
+  organization?: string;
+  avatarHref?: string;
+}
+
+export interface ParticipantRoster {
+  schemaVersion: 1;
+  entries: Participant[];
+}