wordinweb 0.2.4 → 0.3.0

package/dist/collab.d.ts

@@ -1,6 +1,6 @@
 import { ReactNode } from 'react';
-import { X as XmlElement, D as DocxDocument, C as ClientMessage, S as ServerMessage, P as PresencePosition, R as RosterEntry, a as ParticipantProfile, I as Intent, b as IdSidecar, L as LineageHead, T as ToolbarFeature, c as ToolbarMode, d as DocxViewApi, W as WriteStatus, U as UndoOutcome } from './index-CGp6gVjn.js';
-export { e as bytesToB64, f as deriveEpochKeys, g as docKeyFromFragment, m as mintDocKey, s as sealCheckpoint, h as stretchShareCode } from './index-CGp6gVjn.js';
+import { X as XmlElement, D as DocxDocument, C as ClientMessage, S as ServerMessage, P as PresencePosition, R as RosterEntry, a as ParticipantProfile, I as Intent, b as IdSidecar, L as LineageHead, T as ToolbarFeature, c as ToolbarMode, d as DocxViewApi, W as WriteStatus, U as UndoOutcome } from './index-C_oyKJu0.js';
+export { e as bytesToB64, f as deriveEpochKeys, g as docKeyFromFragment, m as mintDocKey, s as sealCheckpoint, h as stretchShareCode } from './index-C_oyKJu0.js';
 
 /**
  * How much of the document an applied intent disturbed — the input to
@@ -206,6 +206,26 @@ interface ConnectionCallbacks {
     onEpochChange?: (storedGenesisId: string, currentGenesisId: string) => void;
     /** The session roster changed (join/leave/rename) — full snapshot. */
     onRoster?: (roster: RosterEntry[]) => void;
+    onAgentInviteRegistered?: (invite: {
+        inviteId: string;
+        expiresAt: number;
+    }) => void;
+    onAgentInviteRefused?: (invite: {
+        inviteId: string;
+        reason: string;
+    }) => void;
+    onAgentConnected?: (agent: {
+        inviteId: string;
+        agentClientId: string;
+        profile: ParticipantProfile;
+    }) => void;
+    onAgentChat?: (message: {
+        agentClientId: string;
+        messageId: string;
+        sender: "inviter" | "agent";
+        iv: string;
+        ciphertext: string;
+    }) => void;
     /**
      * The connection detected that the local OPTIMISTIC replica drifted from
      * the canonical document at quiescence and rebuilt it in place (encrypted
@@ -236,6 +256,22 @@ interface ConnectionCallbacks {
      * per-intent — the connection stays perfectly usable.
      */
     onSubmitDropped?: (reason: "not-ready") => void;
+    /**
+     * The QUEUED-UNDO count changed (encrypted connection only — see
+     * EncryptedCollabConnection.undoLast). An undo pressed while this client's
+     * own edits are still in flight is held until they are confirmed, so
+     * `queued` is how many presses are waiting; it drops back as they run.
+     *
+     * `expired` means the wait ran out and the held presses were DROPPED — the
+     * connection is not carrying edits to confirmation any more, and executing
+     * the undo against a stale mirror would reverse the wrong action. The
+     * consumer must show something: a press that produces nothing and says
+     * nothing is the failure this whole gate exists to remove.
+     */
+    onUndoQueue?: (state: {
+        queued: number;
+        expired: boolean;
+    }) => void;
     /**
      * Something threw on an async path that has nowhere to return an error —
      * a seal, a transport send, a persistence write. These used to die in a
@@ -338,6 +374,20 @@ interface ConnectionCallbacks {
  * ClientReplica (optimistic apply + reconciliation), and relays presence.
  * The editor layer submits local intents and reads `replica.doc`.
  */
+/**
+ * The connection surface every caller actually depends on.
+ *
+ * DERIVED from CollabConnection with Pick rather than hand-written, so it
+ * cannot drift from the plaintext implementation — adding a member here is a
+ * compile error until the real class has it.
+ *
+ * It exists because EncryptedCollabConnection extends nothing: the two classes
+ * are unrelated types that happen to offer the same members, and callers
+ * bridged that with `as unknown as CollabConnection` — a claim nothing checked.
+ * Pick also drops the private fields, which are what made the two nominally
+ * incompatible in the first place.
+ */
+type CollabConnectionLike = Pick<CollabConnection, "join" | "resume" | "submit" | "submitPreApplied" | "ready" | "pendingCount" | "doc" | "takeRenderScope" | "setPresence" | "setProfile" | "uploadMedia" | "exportBundle" | "exportBundleAsync" | "admin" | "activity" | "registerAgentInvite" | "revokeAgentInvite" | "sendAgentChat" | "mediaMaxBlobBytes" | "docEpoch" | "docVersion" | "genesisId" | "allocIds">;
 declare class CollabConnection {
     private transport;
     private clientId;
@@ -403,7 +453,14 @@ declare class CollabConnection {
         profile?: ParticipantProfile;
         codeProof?: string;
         ownerToken?: string;
+        agentInvite?: {
+            inviteId: string;
+            token: string;
+        };
     }): void;
+    registerAgentInvite(inviteId: string, token: string, expiresAt: number): void;
+    revokeAgentInvite(inviteId: string): void;
+    sendAgentChat(agentClientId: string, messageId: string, iv: string, ciphertext: string): void;
     /** Owner admin op (doc 14 §2.5): honored only if this connection proved
      * the owner token at hello — otherwise the server refuses `not-owner`. */
     admin(action: {
@@ -706,7 +763,7 @@ declare class BundlePersister {
      * every in-flight write (round-4 F8: the flush is only meaningful if it
      * durably lands the latest state before pagehide). */
     private chain;
-    constructor(conn: CollabConnection, store: BundleStore, docId: string, opts?: {
+    constructor(conn: CollabConnectionLike, store: BundleStore, docId: string, opts?: {
         throttleMs?: number;
         now?: () => number;
         setTimer?: (fn: () => void, ms: number) => unknown;
@@ -891,6 +948,18 @@ interface UseCollabOptions {
      */
     offlineTailCap?: number;
 }
+interface AgentConnectionInfo {
+    inviteId: string;
+    agentClientId: string;
+    profile: ParticipantProfile;
+}
+interface AgentChatEnvelope {
+    agentClientId: string;
+    messageId: string;
+    sender: "inviter" | "agent";
+    iv: string;
+    ciphertext: string;
+}
 interface CollabSession {
     /** The live document to render (null until the welcome arrives). */
     doc: DocxDocument | null;
@@ -1239,8 +1308,40 @@ interface CollabSession {
      * different message from having nothing to undo), and `unavailable` means
      * this connection has no collaborative undo at all — today the plaintext
      * connection, whose authority lives on the server.
+     *
+     * `queued` means the press was HELD until this user's own edits confirm,
+     * because the undo stack cannot see them yet — see {@link undoQueued}.
      */
     undoLast: () => UndoOutcome;
+    /**
+     * Undo presses waiting for this user's own edits to be confirmed. Typing
+     * and pressing Ctrl+Z before the edit round-trips would otherwise undo an
+     * OLDER action, so the press is held and runs on the drain.
+     *
+     * Nonzero is a transient, normal state — a room under load sits here for a
+     * round trip. Consumers can show that undo is on its way; they do not have
+     * to, because the undo does arrive.
+     */
+    undoQueued: number;
+    /**
+     * The held undos were DROPPED because the pending edits never confirmed —
+     * the connection stopped carrying writes, and reversing a stale action
+     * would have been worse than doing nothing.
+     *
+     * This one DOES need to be visible: the user pressed Ctrl+Z and nothing
+     * happened. It sits beside {@link writesBlocked} and {@link offline}, which
+     * carry the reason. Cleared by the next press.
+     */
+    undoExpired: boolean;
+    agentConnections: AgentConnectionInfo[];
+    agentChat: AgentChatEnvelope[];
+    agentInviteError: {
+        inviteId: string;
+        reason: string;
+    } | null;
+    registerAgentInvite: (inviteId: string, token: string, expiresAt: number) => void;
+    revokeAgentInvite: (inviteId: string) => void;
+    sendAgentChat: (agentClientId: string, messageId: string, iv: string, ciphertext: string) => void;
 }
 declare function useCollab(opts: UseCollabOptions): CollabSession;
 /**
@@ -1267,6 +1368,10 @@ declare function useCollab(opts: UseCollabOptions): CollabSession;
 declare const COLLAB_TOOLBAR_DEFAULTS: Partial<Record<ToolbarFeature, boolean>>;
 declare function CollabEditor(opts: UseCollabOptions & {
     editable?: boolean;
+    /** Author name stamped on comments and tracked suggestions. */
+    commentAuthor?: string;
+    /** Connected collaborator names offered as @mention shortcuts in comments. */
+    commentMentions?: string[];
     /** Tracked-change display. Use markup to show suggestions in the document. */
     revisions?: "final" | "markup";
     /** Render the Word-style ribbon toolbar above the page (default true). */
@@ -1297,4 +1402,4 @@ declare function CollabEditor(opts: UseCollabOptions & {
     }) => ReactNode;
 }): ReactNode;
 
-export { BundlePersister, type BundleStore, COLLAB_TOOLBAR_DEFAULTS, CollabEditor, type CollabSession, type DocBundle, InMemoryBundleStore, IndexedDbBundleStore, type CollabSession as InjectedCollabSession, type ParsedBundleKey, type StoredDocKind, type StoredDocSummary, UndoOutcome, type UseCollabOptions, docHash, draftKey, mediaAddressesOf, parseBundleKey, supersededKey, useCollab, versionKey };
+export { type AgentChatEnvelope, type AgentConnectionInfo, BundlePersister, type BundleStore, COLLAB_TOOLBAR_DEFAULTS, CollabEditor, type CollabSession, type DocBundle, InMemoryBundleStore, IndexedDbBundleStore, type CollabSession as InjectedCollabSession, type ParsedBundleKey, type StoredDocKind, type StoredDocSummary, UndoOutcome, type UseCollabOptions, docHash, draftKey, mediaAddressesOf, parseBundleKey, supersededKey, useCollab, versionKey };