@abraca/dabra 2.7.0 → 2.8.0

package/dist/index.d.ts

@@ -5264,6 +5264,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 +5288,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.8.0",
   "description": "abracadabra provider",
   "keywords": [
     "abracadabra",
@@ -41,7 +41,7 @@
     "yjs": "^13.6.8"
   },
   "devDependencies": {
-    "@abraca/schema": "2.7.0"
+    "@abraca/schema": "2.8.0"
   },
   "scripts": {
     "test": "node --no-warnings --conditions=source --experimental-transform-types --test 'tests/*.test.ts'"

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,