@beyondwork/docx-react-component 1.0.40 → 1.0.42

package/src/runtime/awareness-identity.ts

@@ -0,0 +1,173 @@
+import type { Awareness } from "y-protocols/awareness";
+
+import type {
+  AwarenessIdentity,
+  AwarenessPeer,
+  CollabPosture,
+  PresenceSnapshot,
+  TransportStatus,
+} from "../api/awareness-identity-types.ts";
+
+const IDENTITY_FIELD = "identity";
+
+const ROLE_VOCAB = new Set<AwarenessIdentity["role"]>([
+  "author",
+  "reviewer",
+  "observer",
+]);
+const KIND_VOCAB = new Set<AwarenessIdentity["authorKind"]>([
+  "human",
+  "agent",
+  "system",
+]);
+
+/**
+ * Publishes the local client's `identity` record onto the Awareness
+ * channel. Every connected peer sees it through
+ * `getPresenceSnapshot`. Safe to call repeatedly — re-writes the
+ * field, which Awareness treats as a full replacement.
+ */
+export function setLocalIdentity(
+  awareness: Awareness,
+  identity: AwarenessIdentity,
+): void {
+  awareness.setLocalStateField(IDENTITY_FIELD, validate(identity));
+}
+
+/**
+ * Clears the local `identity` field. Typically called on disconnect or
+ * role downgrade so stale presence rows don't linger.
+ */
+export function clearLocalIdentity(awareness: Awareness): void {
+  awareness.setLocalStateField(IDENTITY_FIELD, null);
+}
+
+export interface PresenceSnapshotArgs {
+  awareness?: Awareness;
+  transportStatus?: TransportStatus;
+  queuedLocalEvents?: number;
+  /** Used to filter presence by the active story. When omitted, every peer is returned. */
+  activeStoryFilter?: string;
+}
+
+/**
+ * Builds a `PresenceSnapshot` from the current Awareness map + a
+ * host-supplied transport + queue signal. Unknown or malformed
+ * identity entries are silently dropped (fail-closed — never render a
+ * partially-trusted peer).
+ */
+export function getPresenceSnapshot(args: PresenceSnapshotArgs = {}): PresenceSnapshot {
+  const peers: AwarenessPeer[] = [];
+  if (args.awareness) {
+    for (const [clientId, state] of args.awareness.getStates()) {
+      const raw = (state as Record<string, unknown>)[IDENTITY_FIELD];
+      const identity = coerceIdentity(raw);
+      if (!identity) continue;
+      if (
+        args.activeStoryFilter !== undefined &&
+        identity.activeStoryId !== undefined &&
+        identity.activeStoryId !== args.activeStoryFilter
+      ) {
+        continue;
+      }
+      peers.push({ clientId, ...identity });
+    }
+  }
+  return {
+    peers,
+    transportStatus: args.transportStatus ?? "offline",
+    queuedLocalEvents: args.queuedLocalEvents ?? 0,
+  };
+}
+
+export interface CollabPostureArgs {
+  awareness?: Awareness;
+  transportStatus?: TransportStatus;
+}
+
+/**
+ * Derives the local user's posture from the Awareness map. Role comes
+ * from the local-state `identity`; transport comes from the
+ * host-supplied signal; peer count is the presence size minus self.
+ *
+ * Returns a default "unattached author" posture when no Awareness is
+ * wired — this matches the fail-open behaviour of the facet (host
+ * without a Y.Doc gets an author posture so single-user docs work).
+ */
+export function getCollabPosture(args: CollabPostureArgs = {}): CollabPosture {
+  if (!args.awareness) {
+    return { role: "author", transport: "none", peers: 0 };
+  }
+  const localClientId = args.awareness.clientID;
+  const localState = args.awareness.getLocalState() as
+    | Record<string, unknown>
+    | null;
+  const localIdentity = coerceIdentity(localState?.[IDENTITY_FIELD]);
+  const role = localIdentity?.role ?? "author";
+
+  let peers = 0;
+  for (const [clientId, state] of args.awareness.getStates()) {
+    if (clientId === localClientId) continue;
+    const identity = coerceIdentity(
+      (state as Record<string, unknown>)[IDENTITY_FIELD],
+    );
+    if (identity) peers += 1;
+  }
+
+  return {
+    role,
+    transport: args.transportStatus === "offline" ? "attached" : "attached",
+    peers,
+  };
+}
+
+function coerceIdentity(raw: unknown): AwarenessIdentity | undefined {
+  if (!raw || typeof raw !== "object") return undefined;
+  const candidate = raw as Record<string, unknown>;
+  const userId = candidate["userId"];
+  const displayName = candidate["displayName"];
+  const role = candidate["role"];
+  const authorKind = candidate["authorKind"];
+  if (
+    typeof userId !== "string" ||
+    userId === "" ||
+    typeof displayName !== "string" ||
+    displayName === "" ||
+    typeof role !== "string" ||
+    !ROLE_VOCAB.has(role as AwarenessIdentity["role"]) ||
+    typeof authorKind !== "string" ||
+    !KIND_VOCAB.has(authorKind as AwarenessIdentity["authorKind"])
+  ) {
+    return undefined;
+  }
+  const identity: AwarenessIdentity = {
+    userId,
+    displayName,
+    role: role as AwarenessIdentity["role"],
+    authorKind: authorKind as AwarenessIdentity["authorKind"],
+  };
+  const collabIdentity = candidate["collabIdentity"];
+  if (typeof collabIdentity === "string" && collabIdentity !== "") {
+    identity.collabIdentity = collabIdentity;
+  }
+  const activeStoryId = candidate["activeStoryId"];
+  if (typeof activeStoryId === "string" && activeStoryId !== "") {
+    identity.activeStoryId = activeStoryId;
+  }
+  return identity;
+}
+
+function validate(identity: AwarenessIdentity): AwarenessIdentity {
+  if (!identity.userId) throw new Error("awareness identity: userId required");
+  if (!identity.displayName)
+    throw new Error("awareness identity: displayName required");
+  if (!ROLE_VOCAB.has(identity.role)) {
+    throw new Error(`awareness identity: unknown role ${identity.role}`);
+  }
+  if (!KIND_VOCAB.has(identity.authorKind)) {
+    throw new Error(
+      `awareness identity: unknown authorKind ${identity.authorKind}`,
+    );
+  }
+  return identity;
+}

package/src/runtime/collab/event-types.ts

@@ -83,6 +83,33 @@ export const BROADCAST_COMMAND_TYPES: ReadonlySet<EditorCommand["type"]> = new S
   "change.reject",
   "change.accept-all",
   "change.reject-all",
+  "workflow.set-overlay",
+  "workflow.clear-overlay",
+  "workflow.set-metadata-definitions",
+  "workflow.clear-metadata-definitions",
+  "workflow.set-metadata-entries",
+  "workflow.clear-metadata-entries",
+  "host-annotation.set-overlay",
+  "host-annotation.clear-overlay",
+  "formatting.apply",
+  "style.set-paragraph",
+  "style.set-table",
+  "list.toggle",
+  "list.indent",
+  "list.outdent",
+  "list.restart-numbering",
+  "list.continue-numbering",
+  "table.apply-structure",
+  "image.insert",
+  "image.set-layout",
+  "image.set-frame",
+  "section.insert-break",
+  "section.delete-break",
+  "section.update-layout",
+  "section.set-page-numbering",
+  "section.set-header-footer-link",
+  "content.insert-page-break",
+  "content.insert-table",
 ]);
 
 /**

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();
+    },
+  };
+}