@abraca/dabra 2.7.0 → 2.9.0

package/dist/index.d.ts

@@ -2212,7 +2212,19 @@ declare class AbracadabraWS extends EventEmitter {
     resolve: (value?: any) => void;
     reject: (reason?: any) => void;
   } | null;
+  private onlineListener;
+  private offlineListener;
   constructor(configuration: AbracadabraWSConfiguration);
+  /**
+   * Whether the device currently believes it has network connectivity.
+   *
+   * Treats "unknown" as online: in Node and other non-browser environments
+   * `navigator` (or `navigator.onLine`) is absent, and we must not gate
+   * reconnection there — only the browser exposes a trustworthy signal.
+   */
+  get isOnline(): boolean;
+  handleOnline(): void;
+  handleOffline(): void;
   receivedOnOpenPayload?: Event | undefined;
   onOpen(event: Event): Promise<void>;
   attach(provider: AbracadabraBaseProvider): void;
@@ -5264,6 +5276,15 @@ declare function toPlain(val: unknown): unknown;
  * omitted; `null` is kept (a real value, e.g. top-level `parentId`).
  */
 declare function makeEntryMap(fields: Record<string, unknown>): Y.Map<unknown>;
+/**
+ * A label is a "placeholder" — i.e. carries no real user title — when it is
+ * empty/whitespace, null/undefined, or the literal `"Untitled"` sentinel
+ * (case-insensitive, so `"untitled"` from a `labelToFilename` round-trip is
+ * caught too). The whole tree-label corruption class boils down to a
+ * placeholder being allowed to overwrite a real title; `patchEntry` refuses
+ * exactly that. Mirrors cou-sh's `isEmptyTreeLabel`.
+ */
+declare function isPlaceholderLabel(label: unknown): boolean;
 /**
  * Patch an EXISTING entry's fields per-key on its nested `Y.Map`, so a
  * concurrent edit to a *different* field by a peer is preserved instead
@@ -5279,7 +5300,21 @@ declare function makeEntryMap(fields: Record<string, unknown>): Y.Map<unknown>;
  * Self-transacting: it batches its writes in one `Y.Doc` transaction
  * (a safe reentrant no-op join when already inside one), so callers
  * don't need to pass or own a transaction.
+ *
+ * ── NO-DESTROY LABEL INVARIANT ──────────────────────────────────────────
+ * A `label` patch that is a placeholder (empty/whitespace/"Untitled") is
+ * DROPPED when the entry already holds a real (non-placeholder) label —
+ * regardless of which consumer (cou-sh title-sync, fs-sync rename
+ * detection, MCP, table renderers, a stale snapshot) tried it. This is the
+ * source-of-truth guard against the "card title silently becomes Untitled
+ * / files renamed to untitled.md" corruption: a placeholder must never win
+ * over a real title. Creating a brand-new entry with an empty label (e.g.
+ * a fresh kanban card) is still allowed — the guard only fires when a real
+ * label already exists. Pass `{ allowLabelClear: true }` to override (the
+ * single legitimate "user explicitly cleared it" path).
  */
-declare function patchEntry(treeMap: Y.Map<unknown>, id: string, patch: Record<string, unknown>, removeKeys?: string[]): void;
+declare function patchEntry(treeMap: Y.Map<unknown>, id: string, patch: Record<string, unknown>, removeKeys?: string[], opts?: {
+  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 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, 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 };
+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 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 };

package/package.json

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

package/src/AbracadabraWS.ts

@@ -182,6 +182,12 @@ export class AbracadabraWS extends EventEmitter {
     reject: (reason?: any) => void;
   } | null = null;
 
+  // Bound `online`/`offline` listeners, retained so we can detach them in
+  // destroy(). Only registered in browser-like environments (see constructor).
+  private onlineListener: (() => void) | null = null;
+
+  private offlineListener: (() => void) | null = null;
+
   constructor(configuration: AbracadabraWSConfiguration) {
     super();
     this.setConfiguration(configuration);
@@ -210,11 +216,57 @@ export class AbracadabraWS extends EventEmitter {
       this.configuration.messageReconnectTimeout / 10,
     );
 
+    // Offline-first reconnect gating. When the device reports it is offline we
+    // stop hammering the socket (failed attempts just flip status
+    // disconnected↔connecting and light up every connection indicator) and
+    // wait for the `online` event to resume immediately — no backoff wait.
+    if (typeof window !== "undefined" && typeof window.addEventListener === "function") {
+      this.onlineListener = this.handleOnline.bind(this);
+      this.offlineListener = this.handleOffline.bind(this);
+      window.addEventListener("online", this.onlineListener);
+      window.addEventListener("offline", this.offlineListener);
+    }
+
     if (this.shouldConnect) {
       this.connect();
     }
   }
 
+  /**
+   * Whether the device currently believes it has network connectivity.
+   *
+   * Treats "unknown" as online: in Node and other non-browser environments
+   * `navigator` (or `navigator.onLine`) is absent, and we must not gate
+   * reconnection there — only the browser exposes a trustworthy signal.
+   */
+  get isOnline(): boolean {
+    return typeof navigator === "undefined" || navigator.onLine !== false;
+  }
+
+  handleOnline() {
+    // Network came back — resume immediately if we still want a connection
+    // and aren't already connected. Bypasses the backoff that a pending
+    // retryer would otherwise wait out.
+    if (this.shouldConnect && this.status !== WebSocketStatus.Connected) {
+      this.connect();
+    }
+  }
+
+  handleOffline() {
+    // Stop attempting while offline, but preserve `shouldConnect` so intent
+    // survives — `handleOnline`/attach will resume once connectivity returns.
+    if (this.cancelWebsocketRetry) {
+      this.cancelWebsocketRetry();
+      this.cancelWebsocketRetry = undefined;
+    }
+    try {
+      this.webSocket?.close();
+      this.messageQueue = [];
+    } catch (e) {
+      console.error(e);
+    }
+  }
+
   receivedOnOpenPayload?: Event | undefined = undefined;
 
   async onOpen(event: Event) {
@@ -271,6 +323,14 @@ export class AbracadabraWS extends EventEmitter {
       return;
     }
 
+    // Don't attempt while the device is offline — record the intent and let
+    // the `online` event drive the resume. Avoids the reconnect storm of
+    // instantly-failing socket attempts against a known-dead network.
+    if (!this.isOnline) {
+      this.shouldConnect = true;
+      return;
+    }
+
     // Always cancel any previously initiated connection retryer instances
     if (this.cancelWebsocketRetry) {
       this.cancelWebsocketRetry();
@@ -548,8 +608,11 @@ export class AbracadabraWS extends EventEmitter {
       this.emit("rateLimited");
     }
 
-    // trigger connect if no retry is running and we want to have a connection
-    if (!this.cancelWebsocketRetry && this.shouldConnect) {
+    // trigger connect if no retry is running and we want to have a connection.
+    // Skip scheduling entirely while offline — `handleOnline` resumes the
+    // moment connectivity returns, so there's no point burning a timer (and a
+    // failed attempt) against a dead network.
+    if (!this.cancelWebsocketRetry && this.shouldConnect && this.isOnline) {
       // Apply a much longer delay for rate-limited closes to let the server window reset.
       const delay = isRateLimited ? 60_000 : this.configuration.delay;
       setTimeout(() => {
@@ -565,6 +628,13 @@ export class AbracadabraWS extends EventEmitter {
 
     this.emit("destroy");
 
+    if (typeof window !== "undefined" && typeof window.removeEventListener === "function") {
+      if (this.onlineListener) window.removeEventListener("online", this.onlineListener);
+      if (this.offlineListener) window.removeEventListener("offline", this.offlineListener);
+    }
+    this.onlineListener = null;
+    this.offlineListener = null;
+
     clearInterval(this.intervals.connectionChecker);
 
     // If there is still a connection attempt outstanding then we should stop

package/src/DocUtils.ts

@@ -104,6 +104,20 @@ export function makeEntryMap(
 	return m;
 }
 
+/**
+ * A label is a "placeholder" — i.e. carries no real user title — when it is
+ * empty/whitespace, null/undefined, or the literal `"Untitled"` sentinel
+ * (case-insensitive, so `"untitled"` from a `labelToFilename` round-trip is
+ * caught too). The whole tree-label corruption class boils down to a
+ * placeholder being allowed to overwrite a real title; `patchEntry` refuses
+ * exactly that. Mirrors cou-sh's `isEmptyTreeLabel`.
+ */
+export function isPlaceholderLabel(label: unknown): boolean {
+	if (typeof label !== "string") return label == null;
+	const t = label.trim();
+	return t === "" || t.toLowerCase() === "untitled";
+}
+
 /**
  * Patch an EXISTING entry's fields per-key on its nested `Y.Map`, so a
  * concurrent edit to a *different* field by a peer is preserved instead
@@ -119,17 +133,62 @@ export function makeEntryMap(
  * Self-transacting: it batches its writes in one `Y.Doc` transaction
  * (a safe reentrant no-op join when already inside one), so callers
  * don't need to pass or own a transaction.
+ *
+ * ── NO-DESTROY LABEL INVARIANT ──────────────────────────────────────────
+ * A `label` patch that is a placeholder (empty/whitespace/"Untitled") is
+ * DROPPED when the entry already holds a real (non-placeholder) label —
+ * regardless of which consumer (cou-sh title-sync, fs-sync rename
+ * detection, MCP, table renderers, a stale snapshot) tried it. This is the
+ * source-of-truth guard against the "card title silently becomes Untitled
+ * / files renamed to untitled.md" corruption: a placeholder must never win
+ * over a real title. Creating a brand-new entry with an empty label (e.g.
+ * a fresh kanban card) is still allowed — the guard only fires when a real
+ * label already exists. Pass `{ allowLabelClear: true }` to override (the
+ * single legitimate "user explicitly cleared it" path).
  */
 export function patchEntry(
 	treeMap: Y.Map<unknown>,
 	id: string,
 	patch: Record<string, unknown>,
 	removeKeys: string[] = [],
+	opts: { allowLabelClear?: boolean } = {},
 ): void {
 	const apply = (): void => {
 		const raw = treeMap.get(id);
+
+		// NO-DESTROY label guard: strip a placeholder `label` from the patch
+		// when a real label already exists on the entry. The existing-label
+		// read is DUCK-TYPED (not `instanceof Y.Map`): under a host that
+		// resolves a second physical yjs (cou-sh's local file-link), a
+		// foreign Y.Map fails `instanceof` and would read `undefined` —
+		// disabling the guard in the very environment that needs it. `.get`
+		// / `.toJSON` work regardless of which yjs constructed the map.
+		let effectivePatch = patch;
+		if (
+			!opts.allowLabelClear &&
+			Object.hasOwn(patch, "label") &&
+			isPlaceholderLabel(patch.label)
+		) {
+			let existingLabel: unknown;
+			if (raw != null && typeof (raw as { get?: unknown }).get === "function") {
+				existingLabel = (raw as Y.Map<unknown>).get("label");
+			} else if (
+				raw != null &&
+				typeof (raw as { toJSON?: unknown }).toJSON === "function"
+			) {
+				existingLabel = ((raw as { toJSON: () => Record<string, unknown> }).toJSON())
+					?.label;
+			} else if (raw != null && typeof raw === "object") {
+				existingLabel = (raw as Record<string, unknown>).label;
+			}
+			if (!isPlaceholderLabel(existingLabel)) {
+				const { label: _dropped, ...rest } = patch;
+				effectivePatch = rest;
+			}
+		}
+
 		if (raw instanceof Y.Map) {
-			for (const [k, v] of Object.entries(patch)) {
+			for (const [k, v] of Object.entries(effectivePatch)) {
 				if (v === undefined) raw.delete(k);
 				else raw.set(k, v);
 			}
@@ -138,8 +197,8 @@ export function patchEntry(
 		}
 		const base =
 			raw == null ? {} : (toPlain(raw) as Record<string, unknown>);
-		const merged: Record<string, unknown> = { ...base, ...patch };
-		for (const [k, v] of Object.entries(patch)) {
+		const merged: Record<string, unknown> = { ...base, ...effectivePatch };
+		for (const [k, v] of Object.entries(effectivePatch)) {
 			if (v === undefined) delete merged[k];
 		}
 		for (const k of removeKeys) delete merged[k];

package/src/index.ts

@@ -152,6 +152,7 @@ export {
 	toPlain,
 	makeEntryMap,
 	patchEntry,
+	isPlaceholderLabel,
 } from "./DocUtils.ts";
 export {
 	yjsToMarkdown,