@beyondwork/docx-react-component 1.0.41 → 1.0.42

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"
+> & {
+  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;
+}

package/src/runtime/comment-negotiation.ts

@@ -0,0 +1,158 @@
+import type {
+  CommentNegotiationAction,
+  CommentNegotiationActionType,
+  CommentNegotiationEntry,
+  CommentNegotiationState,
+  NegotiationBlockReason,
+  NegotiationHistoryRow,
+  NegotiationRole,
+} from "../api/comment-negotiation-types.ts";
+
+export interface ReduceContext {
+  role: NegotiationRole;
+  now: string;
+}
+
+export type ReduceResult =
+  | { ok: true; entry: CommentNegotiationEntry }
+  | { ok: false; reason: NegotiationBlockReason };
+
+export function createInitialEntry(commentId: string): CommentNegotiationEntry {
+  return {
+    commentId,
+    state: "proposed",
+    requiredApprovers: [],
+    votes: [],
+    counterProposals: [],
+    history: [],
+  };
+}
+
+const ALLOWED_BY_STATE: Record<
+  CommentNegotiationState,
+  ReadonlyArray<CommentNegotiationActionType>
+> = {
+  proposed: ["propose-change", "counter-propose", "reject"],
+  negotiating: ["counter-propose", "vote", "accept", "reject"],
+  accepted: ["lock"],
+  rejected: ["lock"],
+  resolved: ["reopen"],
+};
+
+export function reduceNegotiation(
+  entry: CommentNegotiationEntry,
+  action: CommentNegotiationAction,
+  ctx: ReduceContext,
+): ReduceResult {
+  if (ctx.role === "observer") {
+    return { ok: false, reason: "collab_observer_readonly" };
+  }
+  if (
+    ctx.role === "reviewer" &&
+    (action.type === "accept" || action.type === "lock")
+  ) {
+    return { ok: false, reason: "collab_role_restricted" };
+  }
+  if (!ALLOWED_BY_STATE[entry.state].includes(action.type)) {
+    return { ok: false, reason: "negotiation_invalid_transition" };
+  }
+  if (action.type === "accept" && !quorumMet(entry)) {
+    return { ok: false, reason: "negotiation_quorum_not_met" };
+  }
+  return { ok: true, entry: applyAction(entry, action, ctx) };
+}
+
+export function quorumMet(entry: CommentNegotiationEntry): boolean {
+  if (entry.requiredApprovers.length > 0) {
+    return entry.requiredApprovers.every(
+      (userId) =>
+        entry.votes.find((v) => v.authorId === userId)?.verdict === "approve",
+    );
+  }
+  const approves = entry.votes.filter((v) => v.verdict === "approve").length;
+  const rejects = entry.votes.filter((v) => v.verdict === "reject").length;
+  return approves >= 1 && rejects === 0;
+}
+
+function applyAction(
+  entry: CommentNegotiationEntry,
+  action: CommentNegotiationAction,
+  ctx: ReduceContext,
+): CommentNegotiationEntry {
+  const from = entry.state;
+  let next: CommentNegotiationEntry = { ...entry };
+
+  switch (action.type) {
+    case "propose-change":
+      next.state = "negotiating";
+      break;
+
+    case "counter-propose": {
+      next.state = from === "proposed" ? "negotiating" : from;
+      next.counterProposals = [
+        ...entry.counterProposals,
+        {
+          id: action.proposalId,
+          authorId: action.authorId,
+          createdAt: action.createdAt,
+          body: action.body,
+          proposedRangeEdit: action.proposedRangeEdit,
+        },
+      ];
+      break;
+    }
+
+    case "vote":
+      next.votes = [
+        ...entry.votes.filter((v) => v.authorId !== action.authorId),
+        {
+          authorId: action.authorId,
+          verdict: action.verdict,
+          castAt: ctx.now,
+        },
+      ];
+      break;
+
+    case "accept":
+      next.state = "accepted";
+      next.acceptedProposalId = action.acceptedProposalId;
+      break;
+
+    case "reject":
+      next.state = "rejected";
+      break;
+
+    case "lock":
+      next.state = "resolved";
+      next.lockedAt = ctx.now;
+      next.lockedBy = action.actorId;
+      break;
+
+    case "reopen":
+      next.state = "negotiating";
+      next.lockedAt = undefined;
+      next.lockedBy = undefined;
+      break;
+  }
+
+  if (next.state !== from) {
+    const row: NegotiationHistoryRow = {
+      from,
+      to: next.state,
+      actorId: actorOf(action),
+      at: ctx.now,
+      action: action.type,
+    };
+    if (action.type === "reject" && action.reasonCode !== undefined) {
+      row.reasonCode = action.reasonCode;
+    }
+    next.history = [...entry.history, row];
+  }
+
+  return next;
+}
+
+function actorOf(action: CommentNegotiationAction): string {
+  if ("actorId" in action) return action.actorId;
+  return action.authorId;
+}