@abraca/dabra 2.6.0 → 2.8.0

package/dist/index.d.ts

@@ -4985,8 +4985,13 @@ declare class ContentManager {
   constructor(dm: DocumentManager);
   /**
    * Read document content as markdown.
-   * Returns the title extracted from the TipTap documentHeader, the markdown
-   * body, tree metadata, and immediate children.
+   *
+   * Returns the markdown body, tree-derived label/type/meta, and immediate
+   * children. `title` mirrors `label` (the tree entry's display name) — it
+   * is *not* derived from a TipTap `documentHeader`, and the markdown body
+   * does NOT include YAML frontmatter. Callers that want frontmatter-style
+   * round-tripping should serialise `meta`/`type` themselves on top of the
+   * returned markdown.
    */
   read(docId: string): Promise<DocumentContent>;
   /**
@@ -5259,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
@@ -5274,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.6.0",
+  "version": "2.8.0",
   "description": "abracadabra provider",
   "keywords": [
     "abracadabra",
@@ -41,7 +41,7 @@
     "yjs": "^13.6.8"
   },
   "devDependencies": {
-    "@abraca/schema": "2.6.0"
+    "@abraca/schema": "2.8.0"
   },
   "scripts": {
     "test": "node --no-warnings --conditions=source --experimental-transform-types --test 'tests/*.test.ts'"

package/src/AbracadabraBaseProvider.ts

@@ -14,6 +14,7 @@ import { StatelessMessage } from "./OutgoingMessages/StatelessMessage.ts";
 import { RpcClient } from "./RpcClient.ts";
 import { QueryClient } from "./QueryClient.ts";
 import type { QuerySpec, QuerySubscriptionHandlers, QuerySubscriptionHandle } from "./QueryClient.ts";
+import { QueryAwarenessMessage } from "./OutgoingMessages/QueryAwarenessMessage.ts";
 import { SyncStepOneMessage } from "./OutgoingMessages/SyncStepOneMessage.ts";
 import { UpdateMessage } from "./OutgoingMessages/UpdateMessage.ts";
 import type {
@@ -516,6 +517,20 @@ export class AbracadabraBaseProvider extends EventEmitter {
         documentName: this.configuration.name,
       });
     }
+
+    // Pull existing peers' awareness on (re)connect. The server keeps no
+    // awareness cache and never replays presence to a fresh joiner, so without
+    // this a late-joining client only learns about a peer once that peer next
+    // *changes* its own awareness — producing asymmetric presence ("A sees B
+    // but B can't see A"). The server re-broadcasts this query to all peers,
+    // who answer with their full state (MessageReceiver.applyQueryAwareness),
+    // and those replies fan back to us. Matches stock y-websocket on-open
+    // behaviour. Only meaningful when an awareness instance exists.
+    if (this.awareness) {
+      this.send(QueryAwarenessMessage, {
+        documentName: this.configuration.name,
+      });
+    }
   }
 
   send(message: ConstructableOutgoingMessage, args: any) {

package/src/ContentManager.ts

@@ -44,8 +44,13 @@ export class ContentManager {
 
 	/**
 	 * Read document content as markdown.
-	 * Returns the title extracted from the TipTap documentHeader, the markdown
-	 * body, tree metadata, and immediate children.
+	 *
+	 * Returns the markdown body, tree-derived label/type/meta, and immediate
+	 * children. `title` mirrors `label` (the tree entry's display name) — it
+	 * is *not* derived from a TipTap `documentHeader`, and the markdown body
+	 * does NOT include YAML frontmatter. Callers that want frontmatter-style
+	 * round-tripping should serialise `meta`/`type` themselves on top of the
+	 * returned markdown.
 	 */
 	async read(docId: string): Promise<DocumentContent> {
 		const provider = await this.dm.getChildProvider(docId);
@@ -95,10 +100,7 @@ export class ContentManager {
 			meta,
 		}));
 
-		// yjsToMarkdown returns a string and takes the resolved label/meta/type
-		// so frontmatter round-trips. (Older code destructured an object and
-		// passed only the fragment — that silently produced `undefined`.)
-		const markdown = yjsToMarkdown(fragment, label, meta, type);
+		const { markdown } = yjsToMarkdown(fragment);
 		const title = label;
 
 		return { label, type, meta, title, markdown, children };

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,