@beyondwork/docx-react-component 1.0.41 → 1.0.43

package/src/runtime/collab-session-bridge.ts

@@ -0,0 +1,157 @@
+import type * as Y from "yjs";
+
+import type {
+  CommentNegotiationAction,
+  CommentNegotiationSnapshot,
+} from "../api/comment-negotiation-types.ts";
+import type {
+  CommentPresentationAction,
+  CommentPresentationSnapshot,
+} from "../api/comment-presentation-types.ts";
+import type {
+  Participant,
+  ParticipantRoster,
+} from "../api/participants-types.ts";
+import {
+  createCollabSessionFacet,
+  type CollabSessionFacet,
+  type DispatchContext,
+  type DispatchResult,
+} from "./collab-session-facet.ts";
+
+/**
+ * Event stream emitted by the collab session bridge. Hosts (or
+ * `DocumentRuntime` in a later slice) subscribe via
+ * `bridge.subscribe(fn)` and re-broadcast into their own event bus.
+ *
+ * Intentionally additive — this does NOT extend `DocumentRuntimeEvent`.
+ * That lets the bridge land today without perturbing the already-
+ * sealed `WordReviewEditorEvent` union. When the public-types surface
+ * opens up for collab extensions (P8d / P8e), these variants flow
+ * through by union.
+ */
+export type CollabSessionEvent =
+  | { type: "comment_negotiation_changed"; commentIds: string[] }
+  | { type: "comment_presentation_changed"; commentIds: string[] }
+  | { type: "participants_changed"; userIds: string[] }
+  | { type: "collab_attached" }
+  | { type: "collab_detached" };
+
+export interface CollabSessionBridge {
+  isAttached(): boolean;
+  attach(ydoc: Y.Doc): void;
+  detach(): void;
+  destroy(): void;
+
+  subscribe(listener: (event: CollabSessionEvent) => void): () => void;
+
+  getCommentNegotiationSnapshot(): CommentNegotiationSnapshot;
+  getCommentPresentationSnapshot(): CommentPresentationSnapshot;
+  getParticipantRoster(): ParticipantRoster;
+
+  dispatchCommentNegotiation(
+    action: CommentNegotiationAction,
+    ctx: DispatchContext,
+  ): DispatchResult;
+
+  dispatchCommentPresentation(
+    action: CommentPresentationAction,
+  ): Promise<DispatchResult>;
+
+  upsertParticipant(entry: Participant): Participant | undefined;
+}
+
+export interface CreateCollabSessionBridgeOptions {
+  ydoc?: Y.Doc;
+  /**
+   * Optional pre-built facet. Primarily for tests. When omitted the
+   * bridge creates its own via `createCollabSessionFacet`.
+   */
+  facet?: CollabSessionFacet;
+}
+
+export function createCollabSessionBridge(
+  options: CreateCollabSessionBridgeOptions = {},
+): CollabSessionBridge {
+  const facet = options.facet ?? createCollabSessionFacet(options.ydoc);
+  const listeners = new Set<(event: CollabSessionEvent) => void>();
+  const facetSubs = new Set<() => void>();
+
+  const emit = (event: CollabSessionEvent): void => {
+    for (const fn of [...listeners]) fn(event);
+  };
+
+  const wireFacetSubscriptions = (): void => {
+    if (!facet.isAttached()) return;
+    facetSubs.add(
+      facet.subscribe("negotiation", (commentIds) =>
+        emit({ type: "comment_negotiation_changed", commentIds }),
+      ),
+    );
+    facetSubs.add(
+      facet.subscribe("presentation", (commentIds) =>
+        emit({ type: "comment_presentation_changed", commentIds }),
+      ),
+    );
+    facetSubs.add(
+      facet.subscribe("participants", (userIds) =>
+        emit({ type: "participants_changed", userIds }),
+      ),
+    );
+  };
+
+  const unwireFacetSubscriptions = (): void => {
+    for (const off of facetSubs) off();
+    facetSubs.clear();
+  };
+
+  if (facet.isAttached()) wireFacetSubscriptions();
+
+  return {
+    isAttached: () => facet.isAttached(),
+
+    attach(ydoc) {
+      const wasAttached = facet.isAttached();
+      unwireFacetSubscriptions();
+      facet.attach(ydoc);
+      wireFacetSubscriptions();
+      if (!wasAttached) emit({ type: "collab_attached" });
+    },
+
+    detach() {
+      if (!facet.isAttached()) return;
+      unwireFacetSubscriptions();
+      facet.detach();
+      emit({ type: "collab_detached" });
+    },
+
+    destroy() {
+      unwireFacetSubscriptions();
+      facet.destroy();
+      listeners.clear();
+    },
+
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+
+    getCommentNegotiationSnapshot: () => facet.getCommentNegotiationSnapshot(),
+    getCommentPresentationSnapshot: () => facet.getCommentPresentationSnapshot(),
+    getParticipantRoster: () => facet.getParticipantRoster(),
+
+    dispatchCommentNegotiation(action, ctx) {
+      return facet.dispatchCommentNegotiation(action, ctx);
+    },
+
+    async dispatchCommentPresentation(action) {
+      return facet.dispatchCommentPresentation(action);
+    },
+
+    upsertParticipant(entry) {
+      return facet.upsertParticipant(entry);
+    },
+  };
+}

package/src/runtime/collab-session-facet.ts

@@ -0,0 +1,193 @@
+import * as Y from "yjs";
+
+import type {
+  CommentNegotiationAction,
+  CommentNegotiationSnapshot,
+} from "../api/comment-negotiation-types.ts";
+import type {
+  CommentPresentationAction,
+  CommentPresentationSnapshot,
+} from "../api/comment-presentation-types.ts";
+import type {
+  Participant,
+  ParticipantRoster,
+} from "../api/participants-types.ts";
+import {
+  createNegotiationSync,
+  type NegotiationSyncHandle,
+} from "./comment-negotiation-sync.ts";
+import {
+  createInitialEntry,
+  reduceNegotiation,
+} from "./comment-negotiation.ts";
+import type {
+  CollabBlockReason,
+  NegotiationRole,
+} from "../api/comment-negotiation-types.ts";
+import {
+  createPresentationStore,
+  type PresentationStoreHandle,
+} from "./comment-presentation.ts";
+import {
+  createParticipantRoster,
+  type ParticipantRosterStore,
+} from "./participants.ts";
+
+/**
+ * Bundle of the three Y.Map-backed collab stores.
+ *
+ * Lazy: if no `Y.Doc` is attached the facet is "detached" — every
+ * snapshot returns an empty shape and every dispatch is a no-op that
+ * resolves without mutating anything. This lets `DocumentRuntime`
+ * expose the surface unconditionally without forcing hosts that don't
+ * want collab to supply a `Y.Doc`.
+ *
+ * Connect / disconnect is idempotent. Reconnecting with a different
+ * `Y.Doc` tears down the existing subscriptions first.
+ */
+export interface CollabSessionFacet {
+  isAttached(): boolean;
+
+  getCommentNegotiationSnapshot(): CommentNegotiationSnapshot;
+  getCommentPresentationSnapshot(): CommentPresentationSnapshot;
+  getParticipantRoster(): ParticipantRoster;
+
+  dispatchCommentNegotiation(
+    action: CommentNegotiationAction,
+    ctx: DispatchContext,
+  ): DispatchResult;
+
+  dispatchCommentPresentation(
+    action: CommentPresentationAction,
+  ): Promise<DispatchResult>;
+
+  upsertParticipant(entry: Participant): Participant | undefined;
+
+  subscribe(
+    kind: "negotiation" | "presentation" | "participants",
+    fn: (changedIds: string[]) => void,
+  ): () => void;
+
+  attach(ydoc: Y.Doc): void;
+  detach(): void;
+  destroy(): void;
+}
+
+export interface DispatchContext {
+  role: NegotiationRole;
+  now: string;
+}
+
+export type DispatchResult =
+  | { ok: true }
+  | { ok: false; reason: CollabBlockReason };
+
+const EMPTY_NEGOTIATION: CommentNegotiationSnapshot = {
+  schemaVersion: 1,
+  entries: [],
+};
+
+const EMPTY_PRESENTATION: CommentPresentationSnapshot = {
+  schemaVersion: 1,
+  entries: [],
+};
+
+const EMPTY_ROSTER: ParticipantRoster = {
+  schemaVersion: 1,
+  entries: [],
+};
+
+interface AttachedStores {
+  ydoc: Y.Doc;
+  negotiation: NegotiationSyncHandle;
+  presentation: PresentationStoreHandle;
+  participants: ParticipantRosterStore;
+}
+
+export function createCollabSessionFacet(
+  initialYdoc?: Y.Doc,
+): CollabSessionFacet {
+  let stores: AttachedStores | null = null;
+  let destroyed = false;
+
+  const unwire = (): void => {
+    if (!stores) return;
+    stores.negotiation.destroy();
+    stores.presentation.destroy();
+    stores.participants.destroy();
+    stores = null;
+  };
+
+  const wire = (ydoc: Y.Doc): void => {
+    if (destroyed) return;
+    unwire();
+    stores = {
+      ydoc,
+      negotiation: createNegotiationSync(ydoc),
+      presentation: createPresentationStore(ydoc),
+      participants: createParticipantRoster(ydoc),
+    };
+  };
+
+  if (initialYdoc) wire(initialYdoc);
+
+  return {
+    isAttached: () => stores !== null,
+
+    getCommentNegotiationSnapshot: () =>
+      stores ? stores.negotiation.snapshot() : EMPTY_NEGOTIATION,
+
+    getCommentPresentationSnapshot: () =>
+      stores ? stores.presentation.snapshot() : EMPTY_PRESENTATION,
+
+    getParticipantRoster: () =>
+      stores ? stores.participants.snapshot() : EMPTY_ROSTER,
+
+    dispatchCommentNegotiation(action, ctx) {
+      if (!stores) return { ok: false, reason: "collab_not_attached" };
+      const prev =
+        stores.negotiation.readEntry(action.commentId) ??
+        createInitialEntry(action.commentId);
+      const result = reduceNegotiation(prev, action, ctx);
+      if (!result.ok) return { ok: false, reason: result.reason };
+      stores.negotiation.writeEntry(result.entry);
+      return { ok: true };
+    },
+
+    async dispatchCommentPresentation(action) {
+      if (!stores) return { ok: false, reason: "collab_not_attached" };
+      await stores.presentation.apply(action);
+      return { ok: true };
+    },
+
+    upsertParticipant(entry) {
+      if (!stores) return undefined;
+      return stores.participants.upsert(entry);
+    },
+
+    subscribe(kind, fn) {
+      if (!stores) return () => {};
+      switch (kind) {
+        case "negotiation":
+          return stores.negotiation.subscribe(fn);
+        case "presentation":
+          return stores.presentation.subscribe(fn);
+        case "participants":
+          return stores.participants.subscribe(fn);
+      }
+    },
+
+    attach(ydoc) {
+      wire(ydoc);
+    },
+
+    detach() {
+      unwire();
+    },
+
+    destroy() {
+      destroyed = true;
+      unwire();
+    },
+  };
+}

package/src/runtime/collab-session.ts

@@ -0,0 +1,273 @@
+import type * as Y from "yjs";
+import type { Awareness } from "y-protocols/awareness";
+
+import type {
+  AwarenessIdentity,
+  CollabPosture,
+  PresenceSnapshot,
+  TransportStatus,
+} from "../api/awareness-identity-types.ts";
+import type {
+  ExternalCustodyResolver,
+} from "../api/external-custody-types.ts";
+import type {
+  PayloadSignature,
+  PayloadSigner,
+  PayloadVerifier,
+} from "../io/ooxml/payload-signature.ts";
+import {
+  clearLocalIdentity,
+  getCollabPosture,
+  getPresenceSnapshot,
+  setLocalIdentity,
+} from "./awareness-identity.ts";
+import {
+  createCollabSessionBridge,
+  type CollabSessionBridge,
+  type CollabSessionEvent,
+} from "./collab-session-bridge.ts";
+import type { CommentNegotiationAction } from "../api/comment-negotiation-types.ts";
+import type { Participant } from "../api/participants-types.ts";
+import type {
+  RuntimeSendToExternalArgs,
+  RuntimeSendToExternalResult,
+} from "./external-send-runtime.ts";
+import { runtimeSendToExternal } from "./external-send-runtime.ts";
+import {
+  createTamperGate,
+  type MetadataIntegrity,
+  type TamperGate,
+  type TamperGateEvent,
+} from "./tamper-gate.ts";
+
+/**
+ * Event union emitted by the session. Merges the bridge's event
+ * stream with the tamper-gate stream into a single typed channel so
+ * hosts subscribe once.
+ */
+export type CollabSessionEventOrIntegrity =
+  | CollabSessionEvent
+  | TamperGateEvent;
+
+export interface CollabSessionOptions {
+  ydoc?: Y.Doc;
+  awareness?: Awareness;
+  identity?: AwarenessIdentity;
+  signer: PayloadSigner;
+  verifier?: PayloadVerifier;
+}
+
+export interface AttachPayloadArgs {
+  payloadXml: string;
+  signature: PayloadSignature | undefined;
+}
+
+export type SendToExternalCallArgs = Omit<
+  RuntimeSendToExternalArgs,
+  "bridge" | "tamperGate" | "signer" | "role" | "resolver"
+> & {
+  role?: "author" | "reviewer" | "observer";
+};
+
+/**
+ * Unified collab session — composes the P8a–P8f slices so hosts call
+ * `createCollabSession(...)` instead of wiring the bridge, tamper
+ * gate, resolver and identity channel by hand.
+ */
+export interface CollabSession {
+  readonly bridge: CollabSessionBridge;
+  readonly tamperGate: TamperGate;
+
+  isAttached(): boolean;
+  getMetadataIntegrity(): MetadataIntegrity;
+
+  attach(args: {
+    ydoc?: Y.Doc;
+    awareness?: Awareness;
+    identity?: AwarenessIdentity;
+    payload?: AttachPayloadArgs;
+  }): Promise<void>;
+  detach(): void;
+  destroy(): void;
+
+  // Negotiation + presentation + roster
+  dispatchCommentNegotiation: CollabSessionBridge["dispatchCommentNegotiation"];
+  dispatchCommentPresentation: CollabSessionBridge["dispatchCommentPresentation"];
+  upsertParticipant(entry: Participant): Participant | undefined;
+
+  getCommentNegotiationSnapshot: CollabSessionBridge["getCommentNegotiationSnapshot"];
+  getCommentPresentationSnapshot: CollabSessionBridge["getCommentPresentationSnapshot"];
+  getParticipantRoster: CollabSessionBridge["getParticipantRoster"];
+
+  // Presence + posture
+  setLocalIdentity(identity: AwarenessIdentity): void;
+  clearLocalIdentity(): void;
+  getPresenceSnapshot(opts?: {
+    transportStatus?: TransportStatus;
+    queuedLocalEvents?: number;
+    activeStoryFilter?: string;
+  }): PresenceSnapshot;
+  getCollabPosture(opts?: { transportStatus?: TransportStatus }): CollabPosture;
+
+  // Tamper gate
+  acknowledgeMetadataTampering(): void;
+
+  // External-send
+  registerExternalCustodyResolver(resolver: ExternalCustodyResolver | undefined): void;
+  sendToExternal(args: SendToExternalCallArgs): Promise<RuntimeSendToExternalResult>;
+
+  subscribe(listener: (event: CollabSessionEventOrIntegrity) => void): () => void;
+}
+
+type NegotiationAction = CommentNegotiationAction;
+
+export function createCollabSession(
+  options: CollabSessionOptions,
+): CollabSession {
+  const bridge = createCollabSessionBridge(
+    options.ydoc ? { ydoc: options.ydoc } : {},
+  );
+  const tamperGate = createTamperGate(
+    options.verifier ? { verifier: options.verifier } : {},
+  );
+
+  let awareness: Awareness | undefined = options.awareness;
+  let resolver: ExternalCustodyResolver | undefined;
+  let destroyed = false;
+
+  const listeners = new Set<(event: CollabSessionEventOrIntegrity) => void>();
+  const emit = (event: CollabSessionEventOrIntegrity): void => {
+    for (const fn of [...listeners]) fn(event);
+  };
+  bridge.subscribe(emit);
+  tamperGate.subscribe(emit);
+
+  if (options.identity && awareness) {
+    setLocalIdentity(awareness, options.identity);
+  }
+
+  return {
+    bridge,
+    tamperGate,
+
+    isAttached: () => bridge.isAttached(),
+    getMetadataIntegrity: () => tamperGate.state,
+
+    async attach(args) {
+      if (destroyed) return;
+      if (args.ydoc) bridge.attach(args.ydoc);
+      if (args.awareness) awareness = args.awareness;
+      if (args.identity && awareness) {
+        setLocalIdentity(awareness, args.identity);
+      }
+      if (args.payload) {
+        await tamperGate.attach(args.payload);
+      }
+    },
+
+    detach() {
+      bridge.detach();
+      if (awareness) clearLocalIdentity(awareness);
+      tamperGate.detach();
+    },
+
+    destroy() {
+      destroyed = true;
+      bridge.destroy();
+      tamperGate.destroy();
+      listeners.clear();
+    },
+
+    dispatchCommentNegotiation(action: NegotiationAction, ctx) {
+      return bridge.dispatchCommentNegotiation(action, ctx);
+    },
+
+    async dispatchCommentPresentation(action) {
+      return bridge.dispatchCommentPresentation(action);
+    },
+
+    upsertParticipant(entry) {
+      return bridge.upsertParticipant(entry);
+    },
+
+    getCommentNegotiationSnapshot: () => bridge.getCommentNegotiationSnapshot(),
+    getCommentPresentationSnapshot: () => bridge.getCommentPresentationSnapshot(),
+    getParticipantRoster: () => bridge.getParticipantRoster(),
+
+    setLocalIdentity(identity) {
+      if (!awareness) {
+        throw new Error("collab session: no awareness attached");
+      }
+      setLocalIdentity(awareness, identity);
+    },
+
+    clearLocalIdentity() {
+      if (!awareness) return;
+      clearLocalIdentity(awareness);
+    },
+
+    getPresenceSnapshot(opts = {}) {
+      const args: Parameters<typeof getPresenceSnapshot>[0] = {};
+      if (awareness) args.awareness = awareness;
+      if (opts.transportStatus) args.transportStatus = opts.transportStatus;
+      if (opts.queuedLocalEvents !== undefined) {
+        args.queuedLocalEvents = opts.queuedLocalEvents;
+      }
+      if (opts.activeStoryFilter !== undefined) {
+        args.activeStoryFilter = opts.activeStoryFilter;
+      }
+      return getPresenceSnapshot(args);
+    },
+
+    getCollabPosture(opts = {}) {
+      const args: Parameters<typeof getCollabPosture>[0] = {};
+      if (awareness) args.awareness = awareness;
+      if (opts.transportStatus) args.transportStatus = opts.transportStatus;
+      return getCollabPosture(args);
+    },
+
+    acknowledgeMetadataTampering() {
+      tamperGate.acknowledge();
+    },
+
+    registerExternalCustodyResolver(next) {
+      resolver = next;
+    },
+
+    async sendToExternal(args) {
+      if (!resolver) {
+        throw new Error(
+          "collab session: registerExternalCustodyResolver(...) not called",
+        );
+      }
+      const resolvedRole =
+        args.role ??
+        (awareness
+          ? getCollabPosture({ awareness }).role
+          : "author");
+      return runtimeSendToExternal({
+        bridge,
+        tamperGate,
+        signer: options.signer,
+        payloadXml: args.payloadXml,
+        role: resolvedRole,
+        originDocumentId: args.originDocumentId,
+        originPayloadId: args.originPayloadId,
+        originContentHash: args.originContentHash,
+        resolver,
+        recipient: args.recipient,
+        sentBy: args.sentBy,
+        archiveRef: args.archiveRef,
+        ...(args.custodyId !== undefined ? { custodyId: args.custodyId } : {}),
+        ...(args.now !== undefined ? { now: args.now } : {}),
+      });
+    },
+
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+  };
+}

package/src/runtime/comment-negotiation-sync.ts

@@ -0,0 +1,91 @@
+import * as Y from "yjs";
+
+import type {
+  CommentNegotiationEntry,
+  CommentNegotiationSnapshot,
+} from "../api/comment-negotiation-types.ts";
+
+export interface NegotiationSyncHandle {
+  readEntry(commentId: string): CommentNegotiationEntry | undefined;
+  writeEntry(entry: CommentNegotiationEntry): void;
+  snapshot(): CommentNegotiationSnapshot;
+  subscribe(fn: (changedIds: string[]) => void): () => void;
+  destroy(): void;
+}
+
+const MAP_KEY = "commentNegotiation";
+
+export function createNegotiationSync(ydoc: Y.Doc): NegotiationSyncHandle {
+  const yMap = ydoc.getMap<CommentNegotiationEntry>(MAP_KEY);
+  const listeners = new Set<(ids: string[]) => void>();
+
+  const onChange = (event: Y.YMapEvent<CommentNegotiationEntry>): void => {
+    if (listeners.size === 0) return;
+    const ids = Array.from(event.keysChanged);
+    for (const fn of listeners) fn(ids);
+  };
+  yMap.observe(onChange);
+
+  return {
+    readEntry(commentId) {
+      const entry = yMap.get(commentId);
+      return entry ? cloneEntry(entry) : undefined;
+    },
+    writeEntry(entry) {
+      yMap.set(entry.commentId, cloneEntry(entry));
+    },
+    snapshot() {
+      return {
+        schemaVersion: 1,
+        entries: Array.from(yMap.values()).map(cloneEntry),
+      };
+    },
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => {
+        listeners.delete(fn);
+      };
+    },
+    destroy() {
+      yMap.unobserve(onChange);
+      listeners.clear();
+    },
+  };
+}
+
+function cloneEntry(entry: CommentNegotiationEntry): CommentNegotiationEntry {
+  const clone: CommentNegotiationEntry = {
+    commentId: entry.commentId,
+    state: entry.state,
+    requiredApprovers: [...entry.requiredApprovers],
+    votes: entry.votes.map((v) => ({ ...v })),
+    counterProposals: entry.counterProposals.map((p) => {
+      const copy: CommentNegotiationEntry["counterProposals"][number] = {
+        id: p.id,
+        authorId: p.authorId,
+        createdAt: p.createdAt,
+        body: p.body,
+      };
+      if (p.proposedRangeEdit) copy.proposedRangeEdit = { ...p.proposedRangeEdit };
+      if (p.supersededBy !== undefined) copy.supersededBy = p.supersededBy;
+      return copy;
+    }),
+    history: entry.history.map((h) => {
+      const row: CommentNegotiationEntry["history"][number] = {
+        from: h.from,
+        to: h.to,
+        actorId: h.actorId,
+        at: h.at,
+        action: h.action,
+      };
+      if (h.reasonCode !== undefined) row.reasonCode = h.reasonCode;
+      return row;
+    }),
+  };
+  if (entry.acceptedProposalId !== undefined) {
+    clone.acceptedProposalId = entry.acceptedProposalId;
+  }
+  if (entry.lockedAt !== undefined) clone.lockedAt = entry.lockedAt;
+  if (entry.lockedBy !== undefined) clone.lockedBy = entry.lockedBy;
+  return clone;
+}