@abraca/dabra 2.16.0 → 2.17.0

package/dist/index.d.ts

@@ -1616,6 +1616,18 @@ type onAuthenticatedParameters = {
 type onOpenParameters = {
   event: Event;
 };
+/**
+ * Fired when a socket re-establishes after having previously been open at
+ * least once on this provider — i.e. an actual reconnect, not the first
+ * connect. Consumers use this to re-run a reconciliation pass (e.g. re-scan a
+ * watched column) after a drop. The provider's Y.Doc is never replaced, so any
+ * `observe`/`observeDeep` listeners are still attached and fire on their own as
+ * the post-reconnect sync delivers updates — this event is a belt-and-braces
+ * "we're live again" signal, not a requirement for observers to keep working.
+ */
+type onReconnectedParameters = {
+  event: Event;
+};
 type onMessageParameters = {
   event: MessageEvent;
   message: IncomingMessage;
@@ -2244,6 +2256,22 @@ declare class AbracadabraWS extends EventEmitter {
   get serverUrl(): string;
   get url(): string;
   disconnect(): void;
+  /**
+   * Force a fresh socket on the SAME WS manager: drop the current connection
+   * (if any) and reconnect immediately.
+   *
+   * Unlike {@link disconnect} (which clears `shouldConnect` and gives up) this
+   * re-arms `shouldConnect`, so it also revives a socket that a permanent
+   * permission-denial turned off (see `AbracadabraBaseProvider.permissionDeniedHandler`).
+   * The WS manager and its `providerMap` are preserved, so every attached
+   * provider — and every Y.Doc + observer riding this socket — survives
+   * untouched; only the transport is recycled.
+   *
+   * The existing socket is torn down silently (handlers removed first), so no
+   * `close` event fires and no second reconnect is scheduled — `connect()`
+   * below is the single path that re-opens. Returns the `connect()` promise.
+   */
+  reconnect(): Promise<unknown>;
   send(message: any): void;
   onClose({
     event
@@ -2587,6 +2615,7 @@ interface CompleteAbracadabraBaseProviderConfiguration {
   onAuthenticationFailed: (data: onAuthenticationFailedParameters) => void;
   onRateLimited: () => void;
   onOpen: (data: onOpenParameters) => void;
+  onReconnected: (data: onReconnectedParameters) => void;
   onConnect: () => void;
   onStatus: (data: onStatusParameters) => void;
   onMessage: (data: onMessageParameters) => void;
@@ -2620,6 +2649,13 @@ declare class AbracadabraBaseProvider extends EventEmitter {
    * Reset on close.
    */
   private _hasEverAuthenticated;
+  /**
+   * True once this provider's socket has opened at least once. Used to fire
+   * the `reconnected` event on every *subsequent* open (an actual reconnect)
+   * but not the very first connect. Persists across closes — a reconnect is
+   * still a reconnect even after the socket dropped.
+   */
+  private _hasOpenedBefore;
   /** Current WebSocket connection status. */
   get connectionStatus(): WebSocketStatus;
   authorizedScope: AuthorizedScope | undefined;
@@ -2695,6 +2731,25 @@ declare class AbracadabraBaseProvider extends EventEmitter {
   receiveStateless(payload: string): void;
   connect(): Promise<unknown>;
   disconnect(): void;
+  /**
+   * Force the underlying socket to drop and reconnect on the SAME Y.Doc.
+   *
+   * Unlike destroying and re-creating the provider, the document is never
+   * replaced — so every `observe`/`observeDeep` listener attached to it (and
+   * its subdocs) keeps firing once the socket comes back. This also revives a
+   * socket that a permanent permission-denial gave up on (see
+   * {@link permissionDeniedHandler}). Pair it with a freshly-minted token (the
+   * `token` callback is re-invoked on every reconnect) when healing a drop that
+   * was caused by an expired JWT.
+   *
+   * Every provider multiplexed onto this socket is marked unsynced so a
+   * subsequent `waitForSync` actually waits for the post-reconnect handshake
+   * instead of short-circuiting on the stale `isSynced` flag.
+   *
+   * No-op (with a warning) for a provider on a shared, externally-managed
+   * socket — reconnect the owning `websocketProvider` directly in that case.
+   */
+  reconnect(): Promise<unknown> | undefined;
   onOpen(event: Event): Promise<void>;
   getToken(): Promise<string | null>;
   startSync(): void;
@@ -5349,4 +5404,26 @@ declare function patchEntry(treeMap: Y.Map<unknown>, id: string, patch: Record<s
   allowLabelClear?: boolean;
 }): void;
 //#endregion
-export { AbracadabraBaseProvider, AbracadabraBaseProviderConfiguration, AbracadabraClient, AbracadabraClientConfig, AbracadabraOutgoingMessageArguments, AbracadabraProvider, AbracadabraProviderConfiguration, AbracadabraWS, AbracadabraWSConfiguration, AbracadabraWebRTC, type AbracadabraWebRTCConfiguration, AbracadabraWebSocketConn, AdminConfigField, AdminConfigOriginKind, AuditLogEntry, AuditQueryOpts, AuditVerifyResult, AuthFailureContext, AuthFailureReason, AuthMessageType, AuthorizedScope, AwarenessError, BackgroundSyncManager, type BackgroundSyncManagerOptions, BackgroundSyncPersistence, BroadcastChannelSync, CHANNEL_NAMES, ChannelKeyResolver, type ChatChannel, ChatClient, type ChatClientTransport, type MarkReadInput as ChatMarkReadInput, type ChatMessage, type ChatReadCursor, type ChatReadReceipt, type ChatTypingEvent, type ChildrenPage, CloseEvent, CompleteAbracadabraBaseProviderConfiguration, CompleteAbracadabraWSConfiguration, CompleteHocuspocusProviderConfiguration, CompleteHocuspocusProviderWebsocketConfiguration, ConnectionTimeout, Constructable, ConstructableOutgoingMessage, ContentManager, type CreateNotificationInput, CryptoIdentity, CryptoIdentityKeystore, DEFAULT_FILE_CHUNK_SIZE, DEFAULT_ICE_SERVERS, DataChannelRouter, type DeleteMessageInput, DevicePairingChannel, type DevicePairingConfig, DeviceRegistrationService, type DeviceServerStatus, type DeviceSessionRecord, type DeviceSessionStorage, type DeviceTier, type DocEncryptionInfo, DocKeyManager, DocSearchHit, type DocSyncState, type DocSyncStatus, type DocumentBlock, DocumentCache, type DocumentCacheOptions, type DocumentContent, DocumentManager, type DocumentManagerConfig, DocumentMeta, type DocumentMetaInfo, type DocumentMetaWire, E2EAbracadabraProvider, E2EEChannel, type E2EEIdentity, E2EOfflineStore, type EditMessageInput, EffectivePermissionEntry, EffectivePermissionsResponse, EffectiveRole, EncryptedChatClient, EncryptedYMap, EncryptedYText, EnvSnapshotExtension, EnvSnapshotItem, EnvSnapshotResponse, type FetchInboxInput, type FetchNotificationsInput, FileBlobStore, FileTransferChannel, FileTransferHandle, type FileTransferMeta, type FileTransferStatus, type FoldedMessage, Forbidden, GEO_TYPE_META_SCHEMAS, type GetChatHistoryInput, HealthStatus, HocusPocusWebSocket, HocuspocusProvider, HocuspocusProviderConfiguration, HocuspocusProviderWebsocket, HocuspocusProviderWebsocketConfiguration, HocuspocusWebSocket, type IdentityDeviceEntry, type IdentityDocConfiguration, IdentityDocProvider, type IdentityProfile, type IdentityServerEntry, type IdentitySpaceEntry, type InboxEntry, type MarkReadInput$1 as InboxMarkReadInput, InviteRow, KEY_EXCHANGE_CHANNEL, Kind, LocalStorageDeviceSessionStorage, ManualSignaling, type ManualSignalingBlob, type MessageRecord, MessageTooBig, MessageType, MetaFieldType, MetaManager, MetaValidationError, type NotificationReadUpdate, type NotificationRecord, NotificationsClient, OfflineStore, OutgoingMessageArguments, OutgoingMessageInterface, PAGE_TYPES, PageMeta, PageTypeInfo, PageTypeMetaField, type PairingRequest, type PairingResult, PeerConnection, type PeerInfo, type PeerState, PendingSubdoc, PermissionEntry, PublicKeyInfo, QUERY_PREFIX, QueryClient, QueryError, type QueryFrame, type QueryKind, type QuerySpec, type QuerySubscriptionHandle, type QuerySubscriptionHandlers, type QueryTransport, RPC_PREFIX, ReadyzStatus, ResetConnection, type RpcCallHandle, type RpcCallOptions, RpcClient, RpcError, type RpcErrorCode, type RpcErrorPayload, type RpcFrame, type RpcHandler, type RpcHandlerContext, type RpcKind, type RpcTarget, type RpcTransport, SERVER_ROOT_ID, type SchemaDocTypeName, type SchemaMetaOf, type SchemaRegistryLike, type SchemaValidatorLike, SearchIndex, SearchResult, type SendChatMessageInput, type SendMessageInput, type SendMessageResult, ServerInfo, type SignalingIncoming, type SignalingOutgoing, SignalingSocket, SnapshotCreateResult, SnapshotData, SnapshotFileEntry, SnapshotForkResult, SnapshotMeta, SnapshotRestoreResult, StatesArray, SubdocMessage, SubdocRegisteredEvent, TYPE_ALIASES, TokenManager, type TokenManagerOptions, TreeEntry, TreeManager, TreeNode, TreeSearchResult, TypedDocTypeMismatchError, type TypedDocsClient, type TypedTreeEntry, Unauthorized, UploadInfo, UploadMeta, UploadQueueEntry, UploadQueueStatus, UserMetaField, UserProfile, WebSocketStatus, WsReadyStates, YjsDataChannel, attachUpdatedAtObserver, awarenessStatesToArray, wordlist as bip39Wordlist, buildBlockquoteElement, buildBlocksFromMarkdown, buildBulletListElement, buildCodeBlockElement, buildHeadingElement, buildHorizontalRuleElement, buildOrderedListElement, buildParagraphElement, buildTaskListElement, decryptChatContent, decryptField, deriveIdentityDocId, deriveSeedWrappingKey, encryptChatContent, encryptField, filenameToLabel, foldRecords, generateMnemonic, isEncryptedContent, isPlaceholderLabel, makeEncryptedYMap, makeEncryptedYText, makeEntryMap, mnemonicToEd25519Seed, mnemonicToKeyPair, normalizeRootId, onAuthenticatedParameters, onAuthenticationFailedParameters, onAwarenessChangeParameters, onAwarenessUpdateParameters, onCloseParameters, onCompactedParameters, onDisconnectParameters, onMessageParameters, onOpenParameters, onOutgoingMessageParameters, onServerErrorParameters, onStatelessParameters, onStatusParameters, onSubdocLoadedParameters, onSubdocRegisteredParameters, onSyncedParameters, onUnsyncedChangesParameters, parseFrontmatter, patchEntry, populateYDocFromMarkdown, readAuthMessage, readBlocksFromFragment, recordFromYAny, resolvePageType, toPlain, unwrapSeed, validateMnemonic, waitForSync, withTimeout, wrapSeed, writeAuthenticated, writeAuthentication, writePermissionDenied, writeTokenSyncRequest, yjsToMarkdown };
+//#region packages/provider/src/CoverReconcile.d.ts
+interface MediaFileBlock {
+  uploadId: string;
+  docId: string;
+  mimeType: string;
+}
+/**
+ * Recursively collect image/video `fileBlock` nodes from a Y.XmlFragment (or
+ * element subtree), in document order. Mirrors the TipTap
+ * `doc.descendants()` walk used by cou-sh — fileBlocks may be nested inside
+ * other block nodes, so this recurses rather than scanning only top level.
+ */
+declare function collectMediaFileBlocks(root: Y.XmlFragment | Y.XmlElement): MediaFileBlock[];
+/**
+ * Reconcile the cover metadata of `docId`'s tree entry against the media file
+ * blocks currently present in `fragment`. No-op when the entry is missing or
+ * the cover is already valid, so it is safe (and cheap) to call after every
+ * content write. The `treeMap` is the root doc-tree Y.Map; the cover lives on
+ * the doc's OWN self-entry (`treeMap.get(docId).meta`).
+ */
+declare function reconcileDocCover(treeMap: Y.Map<unknown>, docId: string, fragment: Y.XmlFragment | Y.XmlElement): void;
+//#endregion
+export { AbracadabraBaseProvider, AbracadabraBaseProviderConfiguration, AbracadabraClient, AbracadabraClientConfig, AbracadabraOutgoingMessageArguments, AbracadabraProvider, AbracadabraProviderConfiguration, AbracadabraWS, AbracadabraWSConfiguration, AbracadabraWebRTC, type AbracadabraWebRTCConfiguration, AbracadabraWebSocketConn, AdminConfigField, AdminConfigOriginKind, AuditLogEntry, AuditQueryOpts, AuditVerifyResult, AuthFailureContext, AuthFailureReason, AuthMessageType, AuthorizedScope, AwarenessError, BackgroundSyncManager, type BackgroundSyncManagerOptions, BackgroundSyncPersistence, BroadcastChannelSync, CHANNEL_NAMES, ChannelKeyResolver, type ChatChannel, ChatClient, type ChatClientTransport, type MarkReadInput as ChatMarkReadInput, type ChatMessage, type ChatReadCursor, type ChatReadReceipt, type ChatTypingEvent, type ChildrenPage, CloseEvent, CompleteAbracadabraBaseProviderConfiguration, CompleteAbracadabraWSConfiguration, CompleteHocuspocusProviderConfiguration, CompleteHocuspocusProviderWebsocketConfiguration, ConnectionTimeout, Constructable, ConstructableOutgoingMessage, ContentManager, type CreateNotificationInput, CryptoIdentity, CryptoIdentityKeystore, DEFAULT_FILE_CHUNK_SIZE, DEFAULT_ICE_SERVERS, DataChannelRouter, type DeleteMessageInput, DevicePairingChannel, type DevicePairingConfig, DeviceRegistrationService, type DeviceServerStatus, type DeviceSessionRecord, type DeviceSessionStorage, type DeviceTier, type DocEncryptionInfo, DocKeyManager, DocSearchHit, type DocSyncState, type DocSyncStatus, type DocumentBlock, DocumentCache, type DocumentCacheOptions, type DocumentContent, DocumentManager, type DocumentManagerConfig, DocumentMeta, type DocumentMetaInfo, type DocumentMetaWire, E2EAbracadabraProvider, E2EEChannel, type E2EEIdentity, E2EOfflineStore, type EditMessageInput, EffectivePermissionEntry, EffectivePermissionsResponse, EffectiveRole, EncryptedChatClient, EncryptedYMap, EncryptedYText, EnvSnapshotExtension, EnvSnapshotItem, EnvSnapshotResponse, type FetchInboxInput, type FetchNotificationsInput, FileBlobStore, FileTransferChannel, FileTransferHandle, type FileTransferMeta, type FileTransferStatus, type FoldedMessage, Forbidden, GEO_TYPE_META_SCHEMAS, type GetChatHistoryInput, HealthStatus, HocusPocusWebSocket, HocuspocusProvider, HocuspocusProviderConfiguration, HocuspocusProviderWebsocket, HocuspocusProviderWebsocketConfiguration, HocuspocusWebSocket, type IdentityDeviceEntry, type IdentityDocConfiguration, IdentityDocProvider, type IdentityProfile, type IdentityServerEntry, type IdentitySpaceEntry, type InboxEntry, type MarkReadInput$1 as InboxMarkReadInput, InviteRow, KEY_EXCHANGE_CHANNEL, Kind, LocalStorageDeviceSessionStorage, ManualSignaling, type ManualSignalingBlob, type MediaFileBlock, type MessageRecord, MessageTooBig, MessageType, MetaFieldType, MetaManager, MetaValidationError, type NotificationReadUpdate, type NotificationRecord, NotificationsClient, OfflineStore, OutgoingMessageArguments, OutgoingMessageInterface, PAGE_TYPES, PageMeta, PageTypeInfo, PageTypeMetaField, type PairingRequest, type PairingResult, PeerConnection, type PeerInfo, type PeerState, PendingSubdoc, PermissionEntry, PublicKeyInfo, QUERY_PREFIX, QueryClient, QueryError, type QueryFrame, type QueryKind, type QuerySpec, type QuerySubscriptionHandle, type QuerySubscriptionHandlers, type QueryTransport, RPC_PREFIX, ReadyzStatus, ResetConnection, type RpcCallHandle, type RpcCallOptions, RpcClient, RpcError, type RpcErrorCode, type RpcErrorPayload, type RpcFrame, type RpcHandler, type RpcHandlerContext, type RpcKind, type RpcTarget, type RpcTransport, SERVER_ROOT_ID, type SchemaDocTypeName, type SchemaMetaOf, type SchemaRegistryLike, type SchemaValidatorLike, SearchIndex, SearchResult, type SendChatMessageInput, type SendMessageInput, type SendMessageResult, ServerInfo, type SignalingIncoming, type SignalingOutgoing, SignalingSocket, SnapshotCreateResult, SnapshotData, SnapshotFileEntry, SnapshotForkResult, SnapshotMeta, SnapshotRestoreResult, StatesArray, SubdocMessage, SubdocRegisteredEvent, TYPE_ALIASES, TokenManager, type TokenManagerOptions, TreeEntry, TreeManager, TreeNode, TreeSearchResult, TypedDocTypeMismatchError, type TypedDocsClient, type TypedTreeEntry, Unauthorized, UploadInfo, UploadMeta, UploadQueueEntry, UploadQueueStatus, UserMetaField, UserProfile, WebSocketStatus, WsReadyStates, YjsDataChannel, attachUpdatedAtObserver, awarenessStatesToArray, wordlist as bip39Wordlist, buildBlockquoteElement, buildBlocksFromMarkdown, buildBulletListElement, buildCodeBlockElement, buildHeadingElement, buildHorizontalRuleElement, buildOrderedListElement, buildParagraphElement, buildTaskListElement, collectMediaFileBlocks, decryptChatContent, decryptField, deriveIdentityDocId, deriveSeedWrappingKey, encryptChatContent, encryptField, filenameToLabel, foldRecords, generateMnemonic, isEncryptedContent, isPlaceholderLabel, makeEncryptedYMap, makeEncryptedYText, makeEntryMap, mnemonicToEd25519Seed, mnemonicToKeyPair, normalizeRootId, onAuthenticatedParameters, onAuthenticationFailedParameters, onAwarenessChangeParameters, onAwarenessUpdateParameters, onCloseParameters, onCompactedParameters, onDisconnectParameters, onMessageParameters, onOpenParameters, onOutgoingMessageParameters, onReconnectedParameters, onServerErrorParameters, onStatelessParameters, onStatusParameters, onSubdocLoadedParameters, onSubdocRegisteredParameters, onSyncedParameters, onUnsyncedChangesParameters, parseFrontmatter, patchEntry, populateYDocFromMarkdown, readAuthMessage, readBlocksFromFragment, reconcileDocCover, recordFromYAny, resolvePageType, toPlain, unwrapSeed, validateMnemonic, waitForSync, withTimeout, wrapSeed, writeAuthenticated, writeAuthentication, writePermissionDenied, writeTokenSyncRequest, yjsToMarkdown };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abraca/dabra",
-  "version": "2.16.0",
+  "version": "2.17.0",
   "description": "abracadabra provider",
   "keywords": [
     "abracadabra",
@@ -41,7 +41,7 @@
     "yjs": "^13.6.8"
   },
   "devDependencies": {
-    "@abraca/schema": "2.16.0"
+    "@abraca/schema": "2.17.0"
   },
   "scripts": {
     "test": "node --no-warnings --conditions=source --experimental-transform-types --test 'tests/*.test.ts'"

package/src/AbracadabraBaseProvider.ts

@@ -29,6 +29,7 @@ import type {
   onMessageParameters,
   onOpenParameters,
   onOutgoingMessageParameters,
+  onReconnectedParameters,
   onServerErrorParameters,
   onStatelessParameters,
   onStatusParameters,
@@ -89,6 +90,7 @@ export interface CompleteAbracadabraBaseProviderConfiguration {
   onAuthenticationFailed: (data: onAuthenticationFailedParameters) => void;
   onRateLimited: () => void;
   onOpen: (data: onOpenParameters) => void;
+  onReconnected: (data: onReconnectedParameters) => void;
   onConnect: () => void;
   onStatus: (data: onStatusParameters) => void;
   onMessage: (data: onMessageParameters) => void;
@@ -124,6 +126,7 @@ export class AbracadabraBaseProvider extends EventEmitter {
     onAuthenticationFailed: () => null,
     onRateLimited: () => null,
     onOpen: () => null,
+    onReconnected: () => null,
     onConnect: () => null,
     onMessage: () => null,
     onOutgoingMessage: () => null,
@@ -155,6 +158,14 @@ export class AbracadabraBaseProvider extends EventEmitter {
    */
   private _hasEverAuthenticated = false;
 
+  /**
+   * True once this provider's socket has opened at least once. Used to fire
+   * the `reconnected` event on every *subsequent* open (an actual reconnect)
+   * but not the very first connect. Persists across closes — a reconnect is
+   * still a reconnect even after the socket dropped.
+   */
+  private _hasOpenedBefore = false;
+
   /** Current WebSocket connection status. */
   get connectionStatus(): WebSocketStatus {
     return this.configuration.websocketProvider.status;
@@ -230,6 +241,7 @@ export class AbracadabraBaseProvider extends EventEmitter {
     }
 
     this.on("open", this.configuration.onOpen);
+    this.on("reconnected", this.configuration.onReconnected);
     this.on("message", this.configuration.onMessage);
     this.on("outgoingMessage", this.configuration.onOutgoingMessage);
     this.on("synced", this.configuration.onSynced);
@@ -485,10 +497,55 @@ export class AbracadabraBaseProvider extends EventEmitter {
     );
   }
 
+  /**
+   * Force the underlying socket to drop and reconnect on the SAME Y.Doc.
+   *
+   * Unlike destroying and re-creating the provider, the document is never
+   * replaced — so every `observe`/`observeDeep` listener attached to it (and
+   * its subdocs) keeps firing once the socket comes back. This also revives a
+   * socket that a permanent permission-denial gave up on (see
+   * {@link permissionDeniedHandler}). Pair it with a freshly-minted token (the
+   * `token` callback is re-invoked on every reconnect) when healing a drop that
+   * was caused by an expired JWT.
+   *
+   * Every provider multiplexed onto this socket is marked unsynced so a
+   * subsequent `waitForSync` actually waits for the post-reconnect handshake
+   * instead of short-circuiting on the stale `isSynced` flag.
+   *
+   * No-op (with a warning) for a provider on a shared, externally-managed
+   * socket — reconnect the owning `websocketProvider` directly in that case.
+   */
+  reconnect() {
+    if (!this.manageSocket) {
+      console.warn(
+        "AbracadabraBaseProvider::reconnect() — this provider shares an externally-managed socket; call reconnect() on the websocketProvider instead.",
+      );
+      return;
+    }
+
+    // Reset the synced flag of every provider on this socket BEFORE recycling
+    // it. `cleanupWebSocket` tears the socket down silently (no close event),
+    // so the providers' own `onClose` won't run to flip `synced` — do it here.
+    for (const provider of this.configuration.websocketProvider.configuration.providerMap.values()) {
+      provider.synced = false;
+      provider.isAuthenticated = false;
+    }
+
+    return this.configuration.websocketProvider.reconnect();
+  }
+
   async onOpen(event: Event) {
+    const isReopen = this._hasOpenedBefore;
+    this._hasOpenedBefore = true;
     this.isAuthenticated = false;
 
     this.emit("open", { event });
+    // A subsequent open means the socket dropped and came back — let consumers
+    // re-reconcile. Observers on `document` survive regardless (the doc is
+    // never replaced); this is the explicit signal for catch-up work.
+    if (isReopen) {
+      this.emit("reconnected", { event });
+    }
     await this.sendToken();
     this.startSync();
   }

package/src/AbracadabraWS.ts

@@ -578,6 +578,45 @@ export class AbracadabraWS extends EventEmitter {
     }
   }
 
+  /**
+   * Force a fresh socket on the SAME WS manager: drop the current connection
+   * (if any) and reconnect immediately.
+   *
+   * Unlike {@link disconnect} (which clears `shouldConnect` and gives up) this
+   * re-arms `shouldConnect`, so it also revives a socket that a permanent
+   * permission-denial turned off (see `AbracadabraBaseProvider.permissionDeniedHandler`).
+   * The WS manager and its `providerMap` are preserved, so every attached
+   * provider — and every Y.Doc + observer riding this socket — survives
+   * untouched; only the transport is recycled.
+   *
+   * The existing socket is torn down silently (handlers removed first), so no
+   * `close` event fires and no second reconnect is scheduled — `connect()`
+   * below is the single path that re-opens. Returns the `connect()` promise.
+   */
+  reconnect() {
+    this.shouldConnect = true;
+
+    // Cancel any in-flight retryer so we don't stack two connection attempts.
+    if (this.cancelWebsocketRetry) {
+      this.cancelWebsocketRetry();
+      this.cancelWebsocketRetry = undefined;
+    }
+
+    // Silently drop the current socket (cleanupWebSocket removes our handlers
+    // before closing, so onClose never runs → no auto-reschedule).
+    if (this.webSocket) {
+      this.cleanupWebSocket();
+    }
+
+    // connect() early-returns when status is Connected; force Disconnected so
+    // it always builds a fresh socket. Surface the transition so status
+    // listeners (and the providers' synced reset) see the drop.
+    this.status = WebSocketStatus.Disconnected;
+    this.emit("status", { status: WebSocketStatus.Disconnected });
+
+    return this.connect();
+  }
+
   send(message: any) {
     if (this.webSocket?.readyState === WsReadyStates.Open) {
       this.webSocket.send(message);

package/src/ContentManager.ts

@@ -6,6 +6,7 @@
 import * as Y from "yjs";
 import type { PageMeta } from "./DocTypes.ts";
 import { toPlain, patchEntry } from "./DocUtils.ts";
+import { reconcileDocCover } from "./CoverReconcile.ts";
 import {
 	yjsToMarkdown,
 	populateYDocFromMarkdown,
@@ -167,6 +168,13 @@ export class ContentManager {
 		const contentToWrite = body || markdown;
 		const fallbackTitle = title || "Untitled";
 		populateYDocFromMarkdown(fragment, contentToWrite, fallbackTitle);
+
+		// Reconcile the cover against the media blocks now in the body, so a
+		// write that removed (or added) the cover's image keeps the persisted
+		// cover metadata honest — the editor is no longer the only path that
+		// does this. Cheap no-op when the cover is already valid.
+		const reconcileTree = this.dm.getTreeMap();
+		if (reconcileTree) reconcileDocCover(reconcileTree, docId, fragment);
 	}
 
 	private async _appendElements(docId: string, els: Y.XmlElement[]): Promise<void> {

package/src/CoverReconcile.ts

@@ -0,0 +1,129 @@
+/**
+ * CoverReconcile — keep a document's cover-image metadata in sync with the
+ * image/video file blocks that actually live in its content.
+ *
+ * The cover (`meta.coverUploadId` / `coverDocId` / `coverMimeType` on the
+ * doc's own tree entry) is *persisted* metadata, not derived live — the
+ * kanban/gallery/table views read it without loading each card's content.
+ * Historically the only thing that reconciled it was cou-sh's TipTap editor
+ * (`reconcileCover` in DocRenderer.vue), so any write that did NOT go through
+ * that editor — MCP `write_document`, `@abraca/convert`, the CLI, another SDK
+ * — could leave an orphaned cover pointing at an image the body no longer
+ * contains. This is the shared, write-path-level reconciliation so every
+ * content write through the SDK keeps the cover honest.
+ *
+ * Semantics mirror cou-sh's editor reconciler exactly:
+ *  - cover set + still references a present image/video → leave it (a
+ *    user-chosen cover is preserved as long as its image is in the doc);
+ *  - cover set + its image is gone, others remain → swap to the first;
+ *  - cover set + no image/video remains → clear the three cover keys;
+ *  - no cover + at least one image/video → adopt the first as the cover.
+ */
+import * as Y from "yjs";
+import { toPlain, patchEntry } from "./DocUtils.ts";
+
+export interface MediaFileBlock {
+	uploadId: string;
+	docId: string;
+	mimeType: string;
+}
+
+/**
+ * Recursively collect image/video `fileBlock` nodes from a Y.XmlFragment (or
+ * element subtree), in document order. Mirrors the TipTap
+ * `doc.descendants()` walk used by cou-sh — fileBlocks may be nested inside
+ * other block nodes, so this recurses rather than scanning only top level.
+ */
+export function collectMediaFileBlocks(
+	root: Y.XmlFragment | Y.XmlElement,
+): MediaFileBlock[] {
+	const out: MediaFileBlock[] = [];
+	const visit = (node: Y.AbstractType<unknown>): void => {
+		if (node instanceof Y.XmlElement && node.nodeName === "fileBlock") {
+			const mimeType = node.getAttribute("mimeType");
+			if (
+				typeof mimeType === "string" &&
+				(mimeType.startsWith("image/") || mimeType.startsWith("video/"))
+			) {
+				const uploadId = node.getAttribute("uploadId");
+				if (typeof uploadId === "string" && uploadId) {
+					const docId = node.getAttribute("docId");
+					out.push({
+						uploadId,
+						docId: typeof docId === "string" ? docId : "",
+						mimeType,
+					});
+				}
+			}
+		}
+		if (node instanceof Y.XmlElement || node instanceof Y.XmlFragment) {
+			for (let i = 0; i < node.length; i++) {
+				visit(node.get(i) as Y.AbstractType<unknown>);
+			}
+		}
+	};
+	visit(root as unknown as Y.AbstractType<unknown>);
+	return out;
+}
+
+/**
+ * Reconcile the cover metadata of `docId`'s tree entry against the media file
+ * blocks currently present in `fragment`. No-op when the entry is missing or
+ * the cover is already valid, so it is safe (and cheap) to call after every
+ * content write. The `treeMap` is the root doc-tree Y.Map; the cover lives on
+ * the doc's OWN self-entry (`treeMap.get(docId).meta`).
+ */
+export function reconcileDocCover(
+	treeMap: Y.Map<unknown>,
+	docId: string,
+	fragment: Y.XmlFragment | Y.XmlElement,
+): void {
+	const raw = treeMap.get(docId);
+	if (!raw) return;
+
+	const entry = toPlain(raw) as Record<string, unknown>;
+	const meta = ((entry.meta as Record<string, unknown>) ?? {}) as Record<
+		string,
+		unknown
+	>;
+	const currentCoverId = meta.coverUploadId as string | undefined;
+
+	const media = collectMediaFileBlocks(fragment);
+
+	// Cover already references a present image/video → nothing to do.
+	if (currentCoverId && media.some((b) => b.uploadId === currentCoverId)) {
+		return;
+	}
+
+	if (media.length > 0) {
+		// Adopt (no cover) or swap (stale cover) to the first media block.
+		const best = media[0]!;
+		if (
+			currentCoverId === best.uploadId &&
+			meta.coverDocId === (best.docId || docId) &&
+			meta.coverMimeType === best.mimeType
+		) {
+			return;
+		}
+		patchEntry(treeMap, docId, {
+			meta: {
+				...meta,
+				coverUploadId: best.uploadId,
+				coverDocId: best.docId || docId,
+				coverMimeType: best.mimeType,
+			},
+			updatedAt: Date.now(),
+		});
+		return;
+	}
+
+	// No media remains. Clear the cover keys only if one was set.
+	if (!currentCoverId && !meta.coverDocId && !meta.coverMimeType) return;
+	const {
+		coverUploadId: _cu,
+		coverDocId: _cd,
+		coverMimeType: _cm,
+		...rest
+	} = meta;
+	patchEntry(treeMap, docId, { meta: rest, updatedAt: Date.now() });
+}

package/src/index.ts

@@ -157,6 +157,11 @@ export {
 	patchEntry,
 	isPlaceholderLabel,
 } from "./DocUtils.ts";
+export {
+	reconcileDocCover,
+	collectMediaFileBlocks,
+} from "./CoverReconcile.ts";
+export type { MediaFileBlock } from "./CoverReconcile.ts";
 export {
 	yjsToMarkdown,
 	populateYDocFromMarkdown,

package/src/types.ts

@@ -83,6 +83,19 @@ export type onOpenParameters = {
   event: Event;
 };
 
+/**
+ * Fired when a socket re-establishes after having previously been open at
+ * least once on this provider — i.e. an actual reconnect, not the first
+ * connect. Consumers use this to re-run a reconciliation pass (e.g. re-scan a
+ * watched column) after a drop. The provider's Y.Doc is never replaced, so any
+ * `observe`/`observeDeep` listeners are still attached and fire on their own as
+ * the post-reconnect sync delivers updates — this event is a belt-and-braces
+ * "we're live again" signal, not a requirement for observers to keep working.
+ */
+export type onReconnectedParameters = {
+  event: Event;
+};
+
 export type onMessageParameters = {
   event: MessageEvent;
   message: IncomingMessage;