@beyondwork/docx-react-component 1.0.40 → 1.0.42

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.40",
+  "version": "1.0.42",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
   "packageManager": "pnpm@10.30.3",
   "type": "module",
@@ -102,6 +102,10 @@
     "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",
@@ -162,22 +166,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,6 +200,7 @@
     "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"
   },

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/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[];
+}