@abraca/dabra 1.9.1 → 2.0.1

package/dist/index.d.ts

@@ -232,6 +232,23 @@ declare class DocumentCache {
 }
 //#endregion
 //#region packages/provider/src/AbracadabraClient.d.ts
+/**
+ * Reason classifications surfaced to `onAuthFailed`. Consumers can decide
+ * whether to silently re-register the keypair (`user_not_found`) or
+ * surface a hard block (`account_revoked`, `forbidden`).
+ */
+type AuthFailureReason = "user_not_found" | "account_revoked" | "forbidden" | "unauthorized";
+interface AuthFailureContext {
+  /** HTTP status code from the failed request. */
+  status: number;
+  /** Server-provided error message verbatim. */
+  message: string;
+  /** Best-guess classification from the message text. */
+  reason: AuthFailureReason;
+  /** Method + path of the failed request, useful for debugging. */
+  method: string;
+  path: string;
+}
 interface AbracadabraClientConfig {
   /** Server base URL (http or https). WebSocket URL is derived automatically. */
   url: string;
@@ -250,6 +267,19 @@ interface AbracadabraClientConfig {
    * cache entries automatically.
    */
   cache?: DocumentCache;
+  /**
+   * Called whenever a REST call returns 401/403 with a recoverable reason
+   * (typically "user not found" — server's DB was wiped or repointed).
+   * Consumers wire this to their reauth path (in cou-sh: `_reauthFn`)
+   * so silently-failing background fetches still trigger key re-registration
+   * without waiting for the next WS action to surface the problem.
+   *
+   * The callback runs OUT-OF-BAND of the failing request — the original
+   * Promise still rejects so callers handle their own error path.
+   * Long-running auth handlers should debounce or short-circuit duplicate
+   * concurrent invocations.
+   */
+  onAuthFailed?: (ctx: AuthFailureContext) => void;
 }
 declare class AbracadabraClient {
   private _token;
@@ -258,6 +288,7 @@ declare class AbracadabraClient {
   private readonly storageKey;
   private readonly _fetch;
   readonly cache: DocumentCache | null;
+  private readonly _onAuthFailed;
   constructor(config: AbracadabraClientConfig);
   get token(): string | null;
   set token(value: string | null);
@@ -397,8 +428,89 @@ declare class AbracadabraClient {
     seq: number;
     data: Uint8Array;
   }[]>;
-  /** Clear token from memory and storage. */
+  /**
+   * Clear token from memory and storage. Local-only; does NOT notify the
+   * server. Use {@link logoutServer} or {@link logoutAll} when you also
+   * want the JWT to land in the server's revocation cache.
+   */
   logout(): void;
+  /**
+   * Revoke the current JWT server-side and clear local state. Adds the
+   * token's `jti` to the server's revocation cache so subsequent requests
+   * with this token return 401, even if the JWT signature still verifies
+   * and `exp` hasn't passed. Safe to call when no token is set — degrades
+   * to a local clear.
+   *
+   * Network errors are swallowed (the local state is always cleared) so
+   * a sign-out flow can't get stuck on a flaky connection. The endpoint
+   * itself is idempotent.
+   */
+  logoutServer(): Promise<void>;
+  /**
+   * Bump the user's `tokens_invalid_before` watermark, revoking every
+   * outstanding JWT for this user — every device, every browser, every
+   * pending background tab. The current token is required (this is the
+   * user's "I am who I say I am" assertion). After the call returns,
+   * future authenticated requests with any pre-existing token return 401.
+   */
+  logoutAll(): Promise<void>;
+  /**
+   * Request an email verification message be sent to the current user's
+   * registered email address. Requires authentication. Server enforces a
+   * per-user rate limit (1/min, 10/day). Returns 404 if email
+   * verification is disabled in `[auth.email_verification]`.
+   */
+  requestEmailVerification(): Promise<void>;
+  /**
+   * Confirm an email verification token (typically opened from a link in
+   * the verification email). On success the server sets
+   * `users.email_verified_at`. No auth required — the token itself is
+   * the proof.
+   */
+  confirmEmailVerification(token: string): Promise<void>;
+  /**
+   * Initiate a password reset for a user identified by username or
+   * email. The server always returns 202 to avoid leaking whether the
+   * identifier exists; a real reset email is only sent if the lookup
+   * matched. Heavily rate-limited per-identifier and per-IP.
+   */
+  requestPasswordReset(opts: {
+    identifier: string;
+  }): Promise<void>;
+  /**
+   * Complete a password reset using the token from the reset email.
+   * On success the user's password is updated and every existing JWT for
+   * the account is invalidated (the `tokens_invalid_before` watermark
+   * bumps). The caller is NOT auto-logged-in — call {@link login} after.
+   */
+  confirmPasswordReset(opts: {
+    token: string;
+    newPassword: string;
+  }): Promise<void>;
+  /**
+   * Change the current user's password. Requires the current password —
+   * a stolen JWT alone can't pivot to "I now own this account forever"
+   * because the lockout counter (shared with `/auth/login`) trips after
+   * a few wrong tries. The endpoint also bumps `tokens_invalid_before`,
+   * so other sessions are forced to re-auth.
+   */
+  changePassword(opts: {
+    currentPassword: string;
+    newPassword: string;
+  }): Promise<void>;
+  /**
+   * Add a password to an account that doesn't have one yet — for example,
+   * a key-based soft identity opting into a recovery credential. Requires
+   * the caller to be authenticated. The server checks
+   * `users.password_hash IS NULL` and returns 409 if a password is already
+   * set — use {@link changePassword} in that case.
+   *
+   * Setting a password does not bump `tokens_invalid_before`: it adds an
+   * orthogonal credential rather than rotating an existing one. Other
+   * devices keep their sessions; this just unlocks the password-login
+   * code path for future logins on new devices.
+   */
+  setPassword(newPassword: string): Promise<void>;
   /** Get the current user's profile. */
   getMe(): Promise<UserProfile>;
   /** Update the current user's display name. */
@@ -413,13 +525,51 @@ declare class AbracadabraClient {
   getDoc(docId: string): Promise<DocumentMeta>;
   /** Delete a document (requires Owner role). Cascades to children and uploads. */
   deleteDoc(docId: string): Promise<void>;
-  /** List immediate child documents. */
-  listChildren(docId: string): Promise<string[]>;
-  /** Create a child document under a parent (requires write permission). */
+  /**
+   * Restore a soft-deleted document (and its descendants). Requires the
+   * same `manage` permission as {@link deleteDoc}, and works even when
+   * the doc currently has `deleted_at` set — the cascade resolver walks
+   * the ancestor chain regardless of soft-delete state. Returns the
+   * number of restored rows in the audit log; the SDK call returns
+   * `void` because the wire response is 204.
+   */
+  restoreDoc(docId: string): Promise<void>;
+  /**
+   * Full-text search over document labels via `GET /docs/search`. The
+   * server filters each candidate hit through the cascade resolver, so
+   * results only include docs the caller can read at viewer or above.
+   * Anonymous callers are permitted but only see public docs.
+   *
+   * `limit` is clamped to `[1, 50]` server-side; the default is 20.
+   * Hits arrive in best-first order. `snippet` is HTML with `<mark>`
+   * markers around matched tokens — sanitize before injecting.
+   */
+  searchDocs(query: string, opts?: {
+    limit?: number;
+  }): Promise<DocSearchHit[]>;
+  /**
+   * List the direct children of a document, returning full metadata. Pass
+   * no argument to list the children of the server root — what the
+   * dashboard renders as the Spaces sidebar.
+   *
+   * The cache (when configured) stores the bare `id[]` topology used by
+   * recursive tree walks; callers that need it can read `meta.id` from
+   * the returned metas.
+   */
+  listChildren(parentId?: string): Promise<DocumentMeta[]>;
+  /**
+   * Create a child document under a parent (requires write permission).
+   *
+   * `kind` is the well-known tag (`Kind.Channel`, `Kind.Page`, etc.); the
+   * server stores it in `documents.kind` but does not enforce semantics.
+   * `description` is freeform metadata.
+   */
   createChild(docId: string, opts?: {
     child_id?: string;
     doc_type?: string;
     label?: string;
+    kind?: string;
+    description?: string;
   }): Promise<DocumentMeta>;
   /** Broadcast a stateless message to all connected clients on a document (requires manage permission). */
   broadcast(docId: string, payload: string): Promise<void>;
@@ -456,10 +606,6 @@ declare class AbracadabraClient {
   revokeInvite(code: string): Promise<void>;
   /** Redeem an invite code for the currently authenticated user. */
   redeemInvite(code: string): Promise<void>;
-  /** List root documents (replaces listSpaces for new code). */
-  listRootDocuments(): Promise<DocumentMeta[]>;
-  /** Get the hub document, or null if none is configured. */
-  getHubDocument(): Promise<DocumentMeta | null>;
   /** Set the public_access level for a document. Pass null to inherit from parent. */
   setDocumentAccess(docId: string, publicAccess: string | null): Promise<void>;
   /** Get the public_access info for a document. */
@@ -467,47 +613,77 @@ declare class AbracadabraClient {
     public_access: string | null;
     effective_public_access: string | null;
   }>;
-  /** Update document metadata (label, description, is_hub). Requires manage permission. */
+  /** Update document metadata (label, description, kind). Requires manage permission. */
   updateDocumentMeta(docId: string, opts: {
-    label?: string;
+    label?: string | null;
     description?: string | null;
-    is_hub?: boolean;
+    kind?: string | null;
   }): Promise<void>;
   /**
-   * List spaces visible to the caller. No auth required for public spaces.
-   * @deprecated Use {@link listRootDocuments} instead.
+   * List Spaces visible to the caller — top-level docs (children of the
+   * server root) tagged with `kind: "space"`. Authenticated users see
+   * spaces resolving to any role; anonymous users see public ones.
    */
-  listSpaces(): Promise<SpaceMeta[]>;
+  listSpaces(): Promise<DocumentMeta[]>;
   /**
-   * Get a single space by ID.
-   * @deprecated Use {@link getDoc} instead.
-   */
-  getSpace(spaceId: string): Promise<SpaceMeta>;
-  /**
-   * Get the hub space, or null if none is configured.
-   * @deprecated Use {@link getHubDocument} instead.
-   */
-  getHubSpace(): Promise<SpaceMeta | null>;
-  /**
-   * Create a new space (auth required).
-   * @deprecated Use {@link createDoc} + {@link updateDocumentMeta} instead.
+   * Create a new top-level Space. Equivalent to a `POST /docs` with
+   * `kind: "space"` plus the supplied metadata in one round trip.
+   *
+   * `visibility: "public"` sets `public_access = "observer"` (anonymous
+   * read, no awareness or writes). `"private"` (the default) leaves
+   * `public_access` unset so only explicit grants apply.
    */
   createSpace(opts: {
     name: string;
     description?: string;
-    visibility?: SpaceMeta["visibility"];
+    visibility?: "public" | "private";
     id?: string;
-  }): Promise<SpaceMeta>;
+  }): Promise<DocumentMeta>;
   /**
-   * Update an existing space (Owner or admin required).
-   * @deprecated Use {@link updateDocumentMeta} + {@link setDocumentAccess} instead.
+   * Update a Space's metadata. `visibility` flips `public_access` between
+   * `"observer"` (public) and `"none"` (private). To leave visibility
+   * untouched, omit it. Pass any property as `null` to clear it.
+   */
+  updateSpace(docId: string, opts: {
+    name?: string | null;
+    description?: string | null;
+    visibility?: "public" | "private";
+  }): Promise<void>;
+  /** Delete a Space (and every doc nested under it). Requires manage permission. */
+  deleteSpace(docId: string): Promise<void>;
+  /**
+   * Look up the DM doc between the calling user and `otherUserPk`, or
+   * create it if none exists. The doc id is deterministically derived from
+   * the sorted pubkey pair (see {@link deriveDmDocId}) so both sides
+   * compute the same target — race-tolerant by construction. The created
+   * doc has `kind = "dm"`, `public_access = "none"`, and explicit Editor
+   * permissions for both participants.
+   *
+   * The cascade resolver enforces that no other user can read the DM,
+   * because:
+   *   - `public_access = "none"` blocks anonymous + falls through to the
+   *     server-wide `[access].authenticated` floor for everyone else;
+   *   - the explicit Editor rows only exist for the two participants, so
+   *     non-participants get only the (capped) authenticated floor;
+   *   - the doc lives at server root, so there's no ancestor that could
+   *     leak via a higher cascade grant.
+   *
+   * Note: when `[access].authenticated >= "viewer"` is set server-wide,
+   * non-participants would still be able to *read* the DM via the
+   * authenticated floor. That's the documented "private docs need
+   * authenticated=none" caveat from REDESIGN.md §9 — operators wanting
+   * sealed DMs configure the server accordingly.
+   *
+   * @param otherUserPk Base64url-encoded Ed25519 public key of the other party.
+   * @returns The DM doc's id (existing or newly created).
    */
-  updateSpace(spaceId: string, opts: Partial<Pick<SpaceMeta, "name" | "description" | "visibility" | "is_hub">>): Promise<SpaceMeta>;
+  findOrCreateDmDoc(otherUserPk: string): Promise<string>;
   /**
-   * Delete a space and its root document (Owner or admin required).
-   * @deprecated Use {@link deleteDoc} instead.
+   * The reserved server root document id. Convenience accessor for the
+   * client; identical to {@link SERVER_ROOT_ID}. Use this as the parent for
+   * top-level docs / Spaces.
    */
-  deleteSpace(spaceId: string): Promise<void>;
+  get rootDocId(): string;
   /** List all users (requires elevated role: admin or service). */
   adminListUsers(): Promise<{
     users: (UserProfile & {
@@ -528,13 +704,87 @@ declare class AbracadabraClient {
     refCountsRepaired: number;
     blobsSwept: number;
   }>;
+  /**
+   * Clear the lockout state on a user account: zeroes the failed-login
+   * counter and `locked_until`. Requires elevated role (Admin or
+   * Service). The action is recorded in the audit log under
+   * `admin.user_unlock`.
+   */
+  adminUnlockUser(userId: string): Promise<void>;
+  /**
+   * Page through the audit log. Filters AND-combine; `limit` defaults to
+   * 100 server-side. Requires elevated role.
+   */
+  adminAuditList(opts?: AuditQueryOpts): Promise<AuditLogEntry[]>;
+  /**
+   * Stream the audit log as NDJSON (one JSON object per line) for SIEM
+   * ingestion. Filters mirror {@link adminAuditList} minus `limit`/`offset`.
+   * The server pages internally so memory usage is bounded; this method
+   * buffers the full response into a string and is therefore best for
+   * moderate exports — large dumps should consume `/admin/audit/export`
+   * directly with a streaming HTTP client.
+   */
+  adminAuditExport(opts?: Omit<AuditQueryOpts, "limit" | "offset">): Promise<string>;
+  /**
+   * Verify the integrity of the audit-log hash chain. Returns the result
+   * unchanged: `status: "ok"` when the chain is intact, `status: "broken"`
+   * with a `break` payload identifying the first divergent row when
+   * tampering is detected. Wraps `GET /admin/audit/verify`. Requires
+   * elevated role.
+   *
+   * Note: the server returns HTTP 409 on a broken chain — this method
+   * special-cases the 409 status and returns the body as a successful
+   * result rather than throwing, because "broken" is a valid answer
+   * from the verifier, not an error.
+   */
+  adminAuditVerify(): Promise<AuditVerifyResult>;
+  /**
+   * Download a tar archive of the schema-meaningful tables (users,
+   * documents, permissions, invites, optionally audit log). Requires
+   * elevated role. The server gzips the response when the client sends
+   * `Accept-Encoding: gzip` — `fetch` handles that transparently, so
+   * the returned Blob is the raw tar bytes.
+   */
+  adminBackupDump(opts?: {
+    includeAudit?: boolean;
+  }): Promise<Blob>;
+  /**
+   * List every registered config field with current value + origin
+   * (`default` / `env` / `global_override` / `route_override`). Requires
+   * elevated role.
+   */
+  adminConfigList(): Promise<AdminConfigField[]>;
+  /** Read a single config field by dotted path (e.g. `"access.authenticated"`). */
+  adminConfigGet(path: string): Promise<AdminConfigField>;
+  /**
+   * Set a runtime override on a config field. The field must be marked
+   * `runtime_mutable = true` in the registry; immutable fields return a
+   * schema error. Persists to the `settings_overrides` table.
+   */
+  adminConfigSet(path: string, value: unknown): Promise<AdminConfigField>;
+  /**
+   * Clear a runtime override and revert the field to its env/TOML/default
+   * base value. Returns `true` when an override was actually removed.
+   */
+  adminConfigUnset(path: string): Promise<boolean>;
+  /**
+   * Diagnostic dump of every `ABRA_*` env var the running process saw at
+   * boot, mapped to its config path. Use this to debug
+   * "I set this in `.env` but the server reports a different value".
+   * Secrets are redacted (`value: null`, `redacted: true`).
+   */
+  adminConfigEnvSnapshot(): Promise<EnvSnapshotResponse>;
   /** List snapshot metadata for a document. */
   listSnapshots(docId: string, opts?: {
     limit?: number;
     offset?: number;
   }): Promise<SnapshotMeta[]>;
-  /** Fetch a single snapshot including its base64-encoded data blob. */
-  getSnapshot(docId: string, version: number): Promise<SnapshotData>;
+  /** Fetch a single snapshot including its base64-encoded data blob.
+   *  Pass `{ include: "files" }` to also receive the joined upload list
+   *  (each `fileBlock` / `coverUploadId` resolved against `uploads`). */
+  getSnapshot(docId: string, version: number, opts?: {
+    include?: "files" | string;
+  }): Promise<SnapshotData>;
   /** Create a manual snapshot of the current document state. */
   createSnapshot(docId: string, opts?: {
     label?: string;
@@ -548,7 +798,18 @@ declare class AbracadabraClient {
   /** Health check — no auth required. */
   health(): Promise<HealthStatus>;
   /**
-   * Fetch server metadata including the optional `index_doc_id` entry point.
+   * Readiness probe — pings the database. Returns 200 with
+   * `status: "ready"` only when the server can serve traffic, 503 with
+   * `status: "unready"` otherwise (load balancers / Kubernetes probes
+   * use the status code; the body is informational).
+   *
+   * The 503 case is special-cased here: instead of throwing, the method
+   * returns the unready body so callers can react to the state without
+   * try/catch boilerplate.
+   */
+  readyz(): Promise<ReadyzStatus>;
+  /**
+   * Fetch server metadata including `root_doc_id` and the `[access]` policy.
    * No auth required.
    */
   serverInfo(): Promise<ServerInfo>;
@@ -782,6 +1043,14 @@ interface AbracadabraProviderConfiguration extends Omit<AbracadabraBaseProviderC
    * sharing one local store.  Used for the identity doc.
    */
   serverAgnostic?: boolean;
+  /**
+   * Maximum number of simultaneously cached child providers before LRU
+   * eviction reclaims the least-recently-used unpinned ones. Default 20.
+   * Apps that legitimately need more docs alive (e.g. background-sync of
+   * a working set) should raise this; pin individual children with
+   * `pinChild()` to make them eviction-immune regardless of cap.
+   */
+  maxChildren?: number;
 }
 /**
  * AbracadabraProvider extends AbracadabraBaseProvider with:
@@ -815,8 +1084,9 @@ declare class AbracadabraProvider extends AbracadabraBaseProvider {
   private childAccessTimes;
   /** Pinned children that must not be evicted (e.g. actively viewed docs) */
   private pinnedChildren;
-  /** Max simultaneously cached child providers before LRU eviction kicks in */
-  private static readonly MAX_CHILDREN;
+  /** Default cap on simultaneously cached child providers; configurable per-instance via `maxChildren`. */
+  private static readonly DEFAULT_MAX_CHILDREN;
+  private readonly maxChildren;
   private abracadabraConfig;
   private readonly boundHandleYSubdocsChange;
   /**
@@ -937,7 +1207,7 @@ declare class AbracadabraProvider extends AbracadabraBaseProvider {
   destroy(): void;
 }
 //#endregion
-//#region packages/provider/node_modules/lib0/encoding.d.ts
+//#region node_modules/lib0/encoding.d.ts
 /**
  * A BinaryEncoder handles the encoding to an Uint8Array.
  */
@@ -981,7 +1251,7 @@ declare const Forbidden: CloseEvent;
  */
 declare const ConnectionTimeout: CloseEvent;
 //#endregion
-//#region packages/provider/node_modules/lib0/decoding.d.ts
+//#region node_modules/lib0/decoding.d.ts
 /**
  * A Decoder handles the decoding of an Uint8Array.
  * @template {ArrayBufferLike} [Buf=ArrayBufferLike]
@@ -1208,18 +1478,57 @@ interface UserProfile {
   role: string;
   /** Account-level Ed25519 public key (base64url). Canonical user identity. */
   publicKey: string | null;
+  /**
+   * Whether the user has a password set. `false` for key-based soft
+   * identities until they opt in via {@link AbracadabraClient.setPassword}.
+   * Drives the UI's "Set password" vs "Change password" branching.
+   */
+  hasPassword?: boolean;
 }
 interface DocumentMeta {
   id: string;
   parent_id: string | null;
+  /**
+   * Renderer hint — `"kanban"`, `"checklist"`, `"outline"`, `"graph"`,
+   * `"sheet"`, `"mindmap"`, `"doc"`, etc. Drives the dashboard's choice of
+   * Vue component for this doc. Orthogonal to {@link kind}.
+   */
   doc_type?: string | null;
   label?: string | null;
   description?: string | null;
   public_access?: string | null;
   owner_id?: string | null;
-  is_hub?: boolean;
+  /**
+   * Structural role hint — `"server"` for the reserved server-root doc,
+   * `"space"` for top-level workspace containers, `null`/absent otherwise.
+   * Distinct from {@link doc_type}: a Space (`kind: "space"`) can contain
+   * many Kanban boards (each `doc_type: "kanban"`).
+   */
+  kind?: string | null;
   updated_at?: number | null;
 }
+/**
+ * Well-known structural roles for the {@link DocumentMeta.kind} field. These
+ * are conventions only — the server treats `kind` as an opaque string. Use
+ * these constants instead of string literals to avoid typos.
+ */
+declare const Kind: {
+  /** The reserved server root document. There is exactly one per server. */readonly Server: "server"; /** A top-level workspace container — what the dashboard calls a "Space". */
+  readonly Space: "space"; /** A regular content page rendered by the editor. */
+  readonly Page: "page"; /** A group chat container under a Space. */
+  readonly Channel: "channel"; /** A direct-message container at the server root with two-member permissions. */
+  readonly Dm: "dm"; /** A child of channel/dm holding the messages Y.Array. */
+  readonly ChannelPeriod: "channel-period"; /** A per-user inbox doc holding inbox entries; child of server root. */
+  readonly Inbox: "inbox";
+};
+type Kind = typeof Kind[keyof typeof Kind];
+/**
+ * Hardcoded UUID of the reserved server root document. Every doc in the tree
+ * chains up to this row, so a permission grant on this doc cascades into
+ * every descendant. Mirrors the constant in the Rust crate
+ * (`crate::types::SERVER_ROOT_ID_STR`).
+ */
+declare const SERVER_ROOT_ID = "00000000-0000-0000-0000-000000000000";
 interface UploadMeta {
   id: string;
   doc_id: string;
@@ -1265,9 +1574,28 @@ interface SnapshotMeta {
   label?: string | null;
   created_by?: string | null;
   created_at: number;
+  /** Number of uploads referenced by this snapshot's CRDT state.
+   *  Always 0 on servers older than the `snapshot_files` migration, or for
+   *  snapshots created before that migration ran (until the operator runs
+   *  `POST /admin/snapshots/backfill-refs`). */
+  file_count?: number;
+  /** Signed byte delta vs. the previous-version snapshot for this doc.
+   *  `null` for the first snapshot of a doc (or when the previous version
+   *  has been pruned). Lets the UI render `+12 KB` / `−3 KB`. */
+  delta_bytes?: number | null;
+}
+interface SnapshotFileEntry {
+  id: string;
+  doc_id: string;
+  filename: string;
+  mime_type?: string | null;
+  size?: number | null;
 }
 interface SnapshotData extends SnapshotMeta {
   data: string;
+  /** Populated only when fetched with `?include=files`. Each entry is an
+   *  upload referenced by this snapshot's CRDT state. */
+  files?: SnapshotFileEntry[];
 }
 interface SnapshotCreateResult {
   version: number;
@@ -1297,10 +1625,21 @@ interface ServerInfo {
   version?: string;
   /** Hocuspocus wire protocol version (currently 2). */
   protocol_version?: number;
-  /** Entry-point document ID advertised by the server, if configured. */
-  index_doc_id?: string;
-  /** Default role assigned to users without explicit permissions. */
-  default_role?: string;
+  /**
+   * The reserved server root document id. Every doc in the tree chains up
+   * to this row; granting Admin here cascades to every doc. Hardcoded by
+   * the server — clients can also use {@link SERVER_ROOT_ID} directly.
+   */
+  root_doc_id?: string;
+  /**
+   * Server-wide access policy. Drives client-side decisions like "show the
+   * sign-up CTA?" (anonymous mode) or "warn before publishing?" (anonymous
+   * grants).
+   */
+  access?: {
+    /** `"none"` rejects unauthenticated requests; `"observer"` allows public read. */anonymous?: "none" | "observer"; /** Server-wide floor for authed users with no explicit grant. */
+    authenticated?: "none" | "observer" | "viewer" | "editor";
+  };
   /** Enabled auth methods (e.g. ["crypto", "jwt"]). */
   auth_methods?: string[];
   /** Whether open registration is enabled. */
@@ -1312,23 +1651,143 @@ interface ServerInfo {
     default_mode?: string;
     minimum_mode?: string;
   };
+  /**
+   * Ed25519 public key (base64url, no padding) the server uses to sign every
+   * accepted `messages:*` record (`server_sig`). Clients can verify message
+   * placement / ordering by checking each record's `server_sig` against this
+   * key over the canonical `{ msg_id, period_id, ts, client_sig }` payload.
+   */
+  messages_signer_pubkey?: string;
 }
 interface SearchResult {
   docId: string;
   /** Number of matching trigrams — higher is better. */
   score: number;
 }
-interface SpaceMeta {
-  id: string;
+/**
+ * A single hit returned by the server's full-text search endpoint
+ * (`GET /docs/search`). Distinct from {@link SearchResult}, which is the
+ * client-side trigram index in `SearchIndex.ts`.
+ *
+ * `snippet` is server-rendered HTML with `<mark>` wrappers around the
+ * matched tokens — safe to inject after standard sanitization. `rank` is
+ * a backend-specific score (SQLite bm25 vs Postgres ts_rank); the only
+ * guarantee is that hits arrive in best-first order.
+ */
+interface DocSearchHit {
   doc_id: string;
-  name: string;
-  description: string | null;
-  visibility: "public" | "private" | "invite";
-  is_hub: boolean;
-  owner_id: string | null;
-  created_at: number;
-  updated_at: number;
-  public_access?: string | null;
+  parent_id: string | null;
+  label: string | null;
+  kind: string | null;
+  /** HTML-safe snippet with `<mark>` markers around the matched tokens. */
+  snippet: string;
+  rank: number;
+}
+/**
+ * A single row from `GET /admin/audit`. Mirrors the server's audit log
+ * row format (see `audit::AuditLogRow`). `metadata` is the parsed JSON
+ * object the server stored, or `null` if the row had no metadata. Each
+ * row carries an internal `prev_hash` / `row_hash` chain that admins
+ * verify with {@link AuditVerifyResult}.
+ */
+interface AuditLogEntry {
+  id: string;
+  ts: number;
+  event_type: string;
+  actor_user_id: string | null;
+  actor_ip: string | null;
+  request_id: string | null;
+  target_type: string | null;
+  target_id: string | null;
+  metadata: Record<string, unknown> | null;
+  outcome: string;
+}
+/** Filters for `GET /admin/audit`. All optional and AND-combined. */
+interface AuditQueryOpts {
+  event_type?: string;
+  actor_user_id?: string;
+  target_type?: string;
+  target_id?: string;
+  since_ts?: number;
+  until_ts?: number;
+  limit?: number;
+  offset?: number;
+}
+/** Response of `GET /admin/audit/verify`. `status: "broken"` carries `break`. */
+interface AuditVerifyResult {
+  status: "ok" | "broken";
+  message?: string;
+  break?: {
+    rows_checked: number;
+    row_id: string;
+    reason: string;
+  };
+}
+/**
+ * Where the current value of a config field came from.
+ *
+ *   * `default` — compiled-in default; nobody touched it.
+ *   * `env` — set at startup by an `ABRA_*` env var.
+ *   * `global_override` — admin runtime override via `/admin/config`.
+ *   * `route_override` — per-route override (Phase 3).
+ */
+type AdminConfigOriginKind = "default" | "env" | "global_override" | "route_override";
+/** One entry returned by `GET /admin/config` and `GET /admin/config/fields/:path`. */
+interface AdminConfigField {
+  path: string;
+  section: string;
+  description: string;
+  env_var: string;
+  runtime_mutable: boolean;
+  value: unknown;
+  origin_kind: AdminConfigOriginKind;
+  /** Provenance — present only when origin_kind is a `*_override`. */
+  set_at?: number;
+  set_by?: string;
+  route?: string;
+}
+/**
+ * One row from `GET /admin/config/env-snapshot.items[]`. Reports whether
+ * each registry-known `ABRA_*` env var was set in the running process at
+ * boot, with secrets reported as `value: null` and `redacted: true`.
+ */
+interface EnvSnapshotItem {
+  env_var: string;
+  path: string;
+  section: string;
+  present: boolean;
+  /** Verbatim env value, or `null` for redacted (secrets) or unset. */
+  value: string | null;
+  redacted: boolean;
+}
+/**
+ * One row from `GET /admin/config/env-snapshot.extensions[]`. Extension
+ * overrides (`ABRA_EXT_<name>_<field>`) sit outside the registry and are
+ * reported by name with values inline.
+ */
+interface EnvSnapshotExtension {
+  env_var: string;
+  value: string;
+}
+/**
+ * `GET /admin/config/env-snapshot` response.
+ *
+ * `unknown` lists `ABRA_*` env vars present in the process that don't map
+ * to any registered field — i.e. typos. Operators that see their tweak
+ * land here instead of in `items` know they misspelled the var.
+ */
+interface EnvSnapshotResponse {
+  items: EnvSnapshotItem[];
+  extensions: EnvSnapshotExtension[];
+  unknown: string[];
+}
+/** Response of `GET /readyz`. HTTP 200 when ready, 503 when not. */
+interface ReadyzStatus {
+  status: "ready" | "unready";
+  version: string;
+  checks: {
+    database: "ok" | "error";
+  };
 }
 interface InviteRow {
   code: string;
@@ -1567,6 +2026,193 @@ declare const HocuspocusProviderWebsocket: typeof AbracadabraWS;
 /** @deprecated Use AbracadabraWS */
 type HocuspocusProviderWebsocket = AbracadabraWS;
 //#endregion
+//#region packages/provider/src/RpcClient.d.ts
+/**
+ * RPC v1 — request/response over `MSG_STATELESS`.
+ *
+ * Mirrors `docs/rpc-v1.md` in the abracadabra-rs server. Frames travel as
+ * `MSG_STATELESS` payloads with the literal prefix `rpc:v1:` followed by a
+ * JSON envelope. The provider's existing `sendStateless` / `stateless` event
+ * stream is the only transport surface this layer touches; everything else
+ * (state machine, deadlines, handler registry, dedupe of self-replies) lives
+ * here.
+ */
+declare const RPC_PREFIX = "rpc:v1:";
+type RpcKind = "req" | "ack" | "nack" | "progress" | "result" | "cancel" | "hb" | "register" | "unregister";
+interface RpcFrame {
+  kind: RpcKind;
+  id: string;
+  ts?: number;
+  from?: string;
+  to?: string;
+  method?: string;
+  args?: unknown;
+  deadline_ms?: number;
+  data?: unknown;
+  error?: RpcErrorPayload;
+  by?: "server" | "runner";
+  runner_id?: string;
+  seq?: number;
+  methods?: string[];
+}
+interface RpcErrorPayload {
+  code: string;
+  message: string;
+  details?: unknown;
+}
+type RpcErrorCode = "NO_HANDLER" | "HANDLER_GONE" | "TIMEOUT" | "CANCELLED" | "RATE_LIMITED" | "UNAUTHORIZED" | "SCHEMA" | "INTERNAL" | "APP" | string;
+/** Thrown by `rpc.call(...)` on terminal nack / error / timeout. */
+declare class RpcError extends Error {
+  code: RpcErrorCode;
+  details?: unknown;
+  constructor(code: RpcErrorCode, message: string, details?: unknown);
+}
+/**
+ * Minimal provider surface RpcClient needs. The base provider already
+ * satisfies it; the indirection is here so handlers can be tested against
+ * a stub without booting a Y.Doc.
+ */
+interface RpcTransport {
+  sendStateless(payload: string): void;
+  on(event: string, fn: Function): unknown;
+  off(event: string, fn?: Function): unknown;
+}
+type RpcTarget = {
+  kind: "role";
+  role: "service";
+} | {
+  kind: "user";
+  userId: string;
+} | {
+  kind: "runner";
+  sessionId: string;
+};
+interface RpcCallOptions {
+  /** Defaults to `{ kind: "role", role: "service" }`. */
+  target?: RpcTarget;
+  /** Wall-clock deadline in ms. Server clamps to its own ceiling. */
+  deadline?: number;
+  /** Abort the call (sends `rpc:cancel` to the runner). */
+  signal?: AbortSignal;
+  /** Fired when a runner claims the call (after the server ack). */
+  onClaim?: (runnerId: string) => void;
+  /** Fired for every `rpc:progress` frame the runner emits. */
+  onProgress?: (data: unknown, seq: number) => void;
+}
+interface RpcCallHandle<T = unknown> extends Promise<T> {
+  /** RPC id (UUID v7) — useful for log correlation. */
+  readonly id: string;
+  /** Runner session id, populated once a runner has claimed the call. */
+  readonly claimedBy: string | undefined;
+  /** Cancel the call. Equivalent to `signal.abort()` if a signal was passed. */
+  cancel(reason?: string): void;
+}
+/**
+ * Handler signature for a runner-side RPC handler.
+ *
+ * Returning a value emits `rpc:result(ok)`. Throwing emits
+ * `rpc:result(err)` — `RpcError` instances pass through their `code` and
+ * `details`; any other thrown value becomes `INTERNAL`.
+ *
+ * Returning an async generator turns each `yield` into a `rpc:progress`
+ * frame (with monotonic `seq`); the generator's return value is the final
+ * `result.data`.
+ */
+type RpcHandler = (args: unknown, ctx: RpcHandlerContext) => unknown | Promise<unknown> | AsyncGenerator<unknown, unknown, void>;
+interface RpcHandlerContext {
+  id: string;
+  method: string;
+  /** Server-stamped caller user id. Trusted. */
+  from: string;
+  /** Aborted when the caller cancels or the deadline is reached. */
+  signal: AbortSignal;
+}
+/**
+ * Per-provider RPC layer. Construct one and attach by passing the provider
+ * (or any `RpcTransport`). Disposes on `destroy()`.
+ *
+ * Caller side: `rpc.call('ai.summarize@1', { docId }, { onProgress })`.
+ *
+ * Runner side: `rpc.handle('ai.summarize@1', async (args, ctx) => …)`.
+ */
+declare class RpcClient extends EventEmitter {
+  private readonly transport;
+  private readonly pending;
+  private readonly handlers;
+  /** Tracks live runner-side invocations so we can route `rpc:cancel`. */
+  private readonly runningHandlers;
+  /** Pending register frames awaiting server ack — resolved by id. */
+  private readonly pendingRegistrations;
+  /** Grace timer armed on `disconnect`; cancelled on `connect`. Fires
+   * `HANDLER_GONE` on every pending RPC if the WS is still down after
+   * the grace window. v1 used to wait `deadline + 5s` which could be
+   * 35s on default deadlines — way too long for a definitively-dead
+   * connection. */
+  private disconnectGrace;
+  private static readonly DISCONNECT_GRACE_MS;
+  private readonly onStatelessBound;
+  /**
+   * Replays all live `register` frames whenever the underlying provider
+   * (re)syncs — covers WebSocket reconnects where the server allocated a
+   * new session id and the old capability entries were freed.
+   */
+  private readonly onSyncedBound;
+  private readonly onDisconnectBound;
+  private readonly onConnectBound;
+  private destroyed;
+  constructor(transport: RpcTransport);
+  private armDisconnectGrace;
+  private cancelDisconnectGrace;
+  /**
+   * Called when the WS has been down for the full grace window. Every
+   * in-flight call is dead from the server's perspective (its `close_session`
+   * already fired `HANDLER_GONE` to a now-disconnected caller; on reconnect
+   * the server-side session is fresh, so any cached cancel/result frames
+   * the server tried to deliver were lost). Fail pending immediately.
+   */
+  private failPendingOnDisconnect;
+  /**
+   * Re-emit a `register` frame for every locally-known handler. Called on
+   * every `synced` event from the provider, since a reconnected WS gets a
+   * fresh server-side session with empty capability state.
+   */
+  private replayRegistrations;
+  destroy(): void;
+  /**
+   * Send an RPC and return a handle that resolves with the runner's result.
+   * Throws `RpcError` on nack / handler error / timeout / cancellation.
+   */
+  call<T = unknown>(method: string, args?: unknown, options?: RpcCallOptions): RpcCallHandle<T>;
+  private abortInFlight;
+  /**
+   * Register a handler for `method` and advertise it to the server so
+   * incoming `to: role:service` calls resolve here. Returns an unsubscribe
+   * function. Calling `register` twice for the same method replaces the
+   * handler and re-advertises.
+   *
+   * The advertise is fire-and-forget; if you need to wait until the server
+   * has acknowledged registration (typical in tests with a separate caller
+   * connection), `await rpc.ready()` after registering all handlers.
+   */
+  handle(method: string, handler: RpcHandler): () => void;
+  /**
+   * Resolve once every outstanding `register` frame has been acknowledged
+   * by the server. Useful when a separate connection is about to issue
+   * `rpc.call(...)` and you need the capability registry to be live first.
+   * Resolves immediately if there's nothing pending.
+   */
+  ready(): Promise<void>;
+  private send;
+  private receive;
+  private onAck;
+  private onProgress;
+  private onResult;
+  private onNack;
+  private settle;
+  private onReq;
+  private onCancel;
+}
+//#endregion
 //#region packages/provider/src/AbracadabraBaseProvider.d.ts
 type AbracadabraBaseProviderConfiguration = Required<Pick<CompleteAbracadabraBaseProviderConfiguration, "name">> & Partial<CompleteAbracadabraBaseProviderConfiguration> & ((Required<Pick<CompleteAbracadabraWSConfiguration, "url">> & Partial<Pick<CompleteAbracadabraWSConfiguration, "preserveTrailingSlash">>) | Required<Pick<CompleteAbracadabraBaseProviderConfiguration, "websocketProvider">>);
 /** @deprecated Use AbracadabraBaseProviderConfiguration */
@@ -1637,6 +2283,13 @@ declare class AbracadabraBaseProvider extends EventEmitter {
   intervals: {
     forceSync: ReturnType<typeof setInterval> | null;
   };
+  /**
+   * Lazily-constructed RPC v1 client. See `RpcClient`/`docs/rpc-v1.md`.
+   * Bound to this provider's stateless transport, so calls and handlers
+   * ride the doc this provider is subscribed to.
+   */
+  private _rpc;
+  get rpc(): RpcClient;
   constructor(configuration: AbracadabraBaseProviderConfiguration);
   boundDocumentUpdateHandler: (update: Uint8Array, origin: any) => void;
   boundAwarenessUpdateHandler: ({
@@ -1732,7 +2385,7 @@ declare const awarenessStatesToArray: (states: Map<number, Record<string, any>>)
 declare class SubdocMessage extends OutgoingMessage {
   type: MessageType;
   description: string;
-  get(args: Partial<OutgoingMessageArguments>): Encoder;
+  get(args: Partial<AbracadabraOutgoingMessageArguments>): Encoder;
 }
 //#endregion
 //#region packages/provider/src/SearchIndex.d.ts
@@ -1986,18 +2639,15 @@ declare function makeEncryptedYText(ydoc: Y.Doc, fieldName: string, docKey: Cryp
  * Attach an observer that writes `updatedAt` to the root doc-tree entry for
  * `childDocId` whenever the child doc receives a non-offline update.
  *
- * Writes are throttled: the first qualifying update records the timestamp;
- * a trailing-edge timer flushes it to the tree map after `throttleMs`.
- *
  * @param treeMap       The root doc's "doc-tree" Y.Map.
  * @param childDocId    The child document's UUID (key in treeMap).
  * @param childDoc      The child Y.Doc to observe.
  * @param offlineStore  The child provider's OfflineStore (used to detect
  *                      offline-replay origins and skip them). Pass null when
  *                      the offline store is disabled.
- * @param options       Optional config. `throttleMs` controls the write
- *                      interval (default 5000).
- * @returns             Cleanup function — call on provider destroy.  Flushes
+ * @param options       Optional config. `throttleMs` controls the throttle
+ *                      window (default 5000).
+ * @returns             Cleanup function — call on provider destroy. Flushes
  *                      any pending write before detaching.
  */
 declare function attachUpdatedAtObserver(treeMap: Y.Map<any>, childDocId: string, childDoc: Y.Doc, offlineStore: OfflineStore | null, options?: {
@@ -2375,6 +3025,10 @@ declare class FileTransferHandle extends EventEmitter {
   _setProgress(p: number): void;
   /** @internal */
   _setStatus(s: FileTransferStatus): void;
+  /** @internal — public alias for the protected emit so the parent
+   * `FileTransferChannel` (a different class instance) can dispatch events
+   * on this handle. Protected access is by-class, not by-hierarchy. */
+  _emit(event: string, ...args: unknown[]): void;
 }
 /**
  * Chunked binary file transfer over a dedicated WebRTC data channel.
@@ -2988,7 +3642,6 @@ declare class DeviceRegistrationService {
 //#region packages/provider/src/ChatClient.d.ts
 /**
  * Minimal provider surface ChatClient needs. Matches `AbracadabraBaseProvider`.
- * Kept as an interface so consumers can pass any compatible transport.
  */
 interface ChatClientTransport {
   sendStateless(payload: string): void;
@@ -2996,98 +3649,305 @@ interface ChatClientTransport {
   off(event: string, fn?: Function): unknown;
 }
 /**
- * Typed client for the Abracadabra chat feature.
+ * Send a chat message into a channel doc.
+ *
+ * `channel_doc_id` is the UUID of the channel/dm doc — `documents.id` for
+ * a row with `kind = "channel"` or `kind = "dm"`. Group channels under a
+ * Space pass the channel doc's id; DMs pass the DM doc's id (callers
+ * resolve "the DM doc between user A and user B" via their own path —
+ * typically `client.listChildren(serverRootId)` filtered by `kind === "dm"`
+ * with both pubkeys in `permissions`).
+ */
+interface SendMessageInput {
+  channel_doc_id: string;
+  content: string;
+  /** Cleartext recipient pubkeys for server-side mention fan-out. */
+  mentions?: string[];
+  /** Message id this is a reply to. */
+  reply_to?: string;
+  /**
+   * Optional Ed25519 signature over the canonical envelope, base64url. When
+   * server config `[messages].require_client_sig = true`, sends without a
+   * sig are rejected. Default-config servers accept unsigned sends — the
+   * threat model relies on JWT-bound session auth + the server's own
+   * `server_sig` over `(msg_id, period_id, ts, sig)`.
+   */
+  sig?: string;
+  /** Client-side timestamp (ms) for skew-tolerance check. Optional. */
+  ts_hint?: number;
+}
+interface SendMessageResult {
+  message_id: string;
+  period_id: string;
+  ts: number;
+  server_sig: string;
+}
+interface EditMessageInput {
+  channel_doc_id: string;
+  message_id: string;
+  content: string;
+  sig?: string;
+}
+interface DeleteMessageInput {
+  channel_doc_id: string;
+  message_id: string;
+}
+interface MarkReadInput {
+  channel_doc_id: string;
+  period_id: string;
+  message_id: string;
+  /** Unix milliseconds. Defaults to server time. */
+  ts?: number;
+}
+/**
+ * Thin façade over the `messages:*` stateless protocol.
  *
- * Wraps a connected provider (or base provider) and translates JSON envelopes
- * on the stateless channel into typed method calls and events.
+ * The unified messages model stores chat history as Y.Array entries on
+ * `kind = "channel-period"` child docs of channel/dm docs (and notifications
+ * as entries on a per-user `kind = "inbox"` doc). Reading history, listing
+ * channels, observing real-time messages, and tracking read cursors are all
+ * Y.Doc-shaped operations that the SDK consumer performs via
+ * `AbracadabraClient` + `AbracadabraProvider` directly — not through this
+ * façade. ChatClient handles only the *write-and-validate* path (sends,
+ * edits, deletes, typing, mark-read), where the server is the sole authority
+ * over the channel-period Y.Array.
  *
  * Events emitted:
- *   - `message`      → ChatMessage       (new message broadcast)
- *   - `typing`       → ChatTypingEvent   (typing indicator broadcast)
- *   - `readReceipt`  → ChatReadReceipt   (mark_read broadcast)
+ *   - `typing` → ChatTypingEvent (typing broadcast on the channel doc)
+ *
+ * For incoming-message observation, the consumer opens an
+ * `AbracadabraProvider` on the active period doc and observes its
+ * `messages` Y.Array directly. The dashboard's `useChat` composable does
+ * this; the integration tests do this; external consumers should mirror
+ * the pattern.
  */
 declare class ChatClient extends EventEmitter {
   private readonly provider;
   private readonly responseTimeoutMs;
   private readonly pending;
   private readonly boundOnStateless;
+  private readonly boundOnServerError;
   constructor(provider: ChatClientTransport, options?: {
     responseTimeoutMs?: number;
   });
-  /** Stop listening for chat messages. Does not disconnect the underlying provider. */
   destroy(): void;
-  /** Send a chat message on a channel. Fire-and-forget (the server broadcasts). */
-  sendMessage(input: SendChatMessageInput): void;
-  /** Fetch historical messages for a channel. Resolves with the server response. */
-  getHistory(input: GetChatHistoryInput): Promise<{
-    channel: string;
-    messages: ChatMessage[];
-  }>;
-  /** Broadcast a typing indicator on a channel. */
-  sendTyping(channel: string): void;
-  /** List the current user's channels (ordered by last activity). */
-  listChannels(): Promise<{
-    channels: ChatChannel[];
-  }>;
-  /** Mark a channel read up to `timestamp` (unix ms). */
-  markRead(channel: string, timestamp: number): void;
-  /** Fetch per-user read cursors for a channel. */
-  getReadCursors(channel: string): Promise<{
-    channel: string;
-    cursors: ChatReadCursor[];
-  }>;
-  onMessage(fn: (m: ChatMessage) => void): this;
+  /** Send a chat message. Resolves with the server-assigned id, ts, and signatures. */
+  send(input: SendMessageInput): Promise<SendMessageResult>;
+  /** Edit a previously-sent message. Append-only — server records an `edit` entry. */
+  edit(input: EditMessageInput): Promise<void>;
+  /** Delete a message. Append-only — server records a `tombstone` entry. */
+  delete(input: DeleteMessageInput): Promise<void>;
+  /** Broadcast a typing indicator on a channel. Fire-and-forget. */
+  typing(channel_doc_id: string): void;
+  /** Mark a (period, message) position as read for the calling user. Fire-and-forget. */
+  markRead(input: MarkReadInput): void;
+  /** Observe typing broadcasts. */
   onTyping(fn: (e: ChatTypingEvent) => void): this;
-  onReadReceipt(fn: (e: ChatReadReceipt) => void): this;
   private enqueue;
   private removePending;
   private resolveNext;
+  private rejectNext;
   private handleStateless;
+  private handleServerError;
+}
+//#endregion
+//#region packages/provider/src/EncryptedChatClient.d.ts
+/**
+ * Returns true if `content` is wrapped by this module (i.e. an `e2e:1:`
+ * envelope). Cleartext content always returns false.
+ */
+declare function isEncryptedContent(content: string): boolean;
+/**
+ * Decrypt an `e2e:1:` envelope back to cleartext using the channel's
+ * DocKey. Returns null if the envelope is malformed (don't surface
+ * partial decryption — show the user a placeholder instead).
+ */
+declare function decryptChatContent(content: string, docKey: CryptoKey): Promise<string | null>;
+/**
+ * Encrypt cleartext into an `e2e:1:` envelope ready to send as the
+ * stateless `messages:send` `content` field.
+ */
+declare function encryptChatContent(content: string, docKey: CryptoKey): Promise<string>;
+/**
+ * Per-channel encryption-mode + DocKey resolver. Caches the encryption
+ * mode lookup for `cacheTtlMs`; the DocKey itself is cached inside
+ * `DocKeyManager`. Returns `null` for non-E2E channels.
+ */
+declare class ChannelKeyResolver {
+  private readonly client;
+  private readonly docKeys;
+  private readonly keystore;
+  private readonly options;
+  private modeCache;
+  private static readonly DEFAULT_TTL_MS;
+  constructor(client: AbracadabraClient, docKeys: DocKeyManager, keystore: CryptoIdentityKeystore, options?: {
+    cacheTtlMs?: number;
+  });
+  modeFor(channelDocId: string): Promise<"none" | "cse" | "e2e">;
+  /**
+   * Returns the DocKey for an E2E channel, or null for cleartext channels
+   * (no envelope to fetch). Throws if the channel is E2E but no envelope
+   * exists for the current user — the caller should let the send fail
+   * loudly rather than fall back to cleartext, which would silently
+   * downgrade the threat model.
+   */
+  docKeyFor(channelDocId: string): Promise<CryptoKey | null>;
+  /** Drop the cached encryption mode for `channelDocId` (or all). */
+  clearCache(channelDocId?: string): void;
+}
+/**
+ * Drop-in wrapper around an existing ChatClient that intercepts the
+ * write side (`send` / `edit`) and encrypts content for E2E channels.
+ * Reading is handled separately — the consumer pumps the period's Y.Array
+ * directly and calls `decryptChatContent` per record.
+ *
+ * Channels in `none` or `cse` mode are passed through untouched.
+ */
+declare class EncryptedChatClient {
+  private readonly inner;
+  private readonly resolver;
+  constructor(inner: ChatClient, resolver: ChannelKeyResolver);
+  send(input: SendMessageInput): Promise<SendMessageResult>;
+  edit(input: EditMessageInput): Promise<void>;
+  delete(...args: Parameters<ChatClient["delete"]>): Promise<void>;
+  markRead(...args: Parameters<ChatClient["markRead"]>): void;
+  typing(...args: Parameters<ChatClient["typing"]>): void;
+  destroy(): void;
+}
+//#endregion
+//#region packages/provider/src/messageRecord.d.ts
+/**
+ * Decode + fold message records from a period doc's `messages` Y.Array
+ * into the flat `ChatMessage[]` shape the dashboard renders.
+ *
+ * The server appends three kinds of records to the array (see
+ * `abracadabra-rs/crates/abracadabra/src/messages.rs`):
+ *
+ *   - `record_kind: "message"`     — a real message (default kind).
+ *   - `record_kind: "edit"`        — an updated version of `target_id`.
+ *   - `record_kind: "tombstone"`   — `target_id` is deleted.
+ *
+ * Folding rules:
+ *   - For each `target_id`, apply edits in `ts` order; the *last* edit's
+ *     content wins. The original message's id, sender_id, and ts stay.
+ *     `editedAt` is the latest edit's ts.
+ *   - Any target_id with a tombstone is dropped from the output entirely.
+ *   - Records without record_kind default to "message" (back-compat).
+ *
+ * Cross-period folding: edits and tombstones can in principle target a
+ * message in a *prior* period (e.g. user edits a message that lived on
+ * the previous period after rollover). Callers that paginate across
+ * periods should fold the joined list, not each period independently.
+ */
+interface MessageRecord {
+  record_kind?: 'message' | 'edit' | 'tombstone';
+  id: string;
+  target_id?: string;
+  sender_id: string;
+  channel_doc_id: string;
+  period_id: string;
+  ts: number;
+  content: string;
+  mentions?: string[];
+  reply_to?: string | null;
+  sig?: string;
+  server_sig?: string;
+}
+interface FoldedMessage {
+  id: string;
+  channel: string;
+  senderId: string;
+  senderName?: string;
+  content: string;
+  createdAt: number;
+  /** Set if the message has been edited at least once. */
+  editedAt?: number;
+  /** Reply target message id, if any. */
+  replyTo?: string;
 }
+/**
+ * Fold an ordered list of records (oldest-first) into the visible
+ * messages a UI should render. Records may come from one period or
+ * across multiple periods concatenated in time order.
+ */
+declare function foldRecords(records: MessageRecord[]): FoldedMessage[];
+/**
+ * Decode whatever the Y.Array stored for an entry into a MessageRecord.
+ * Note: the server stamps `ts` server-side via `Any::BigInt(now_ts_ms())`,
+ * so on the wire it round-trips as a JS BigInt — `typeof` is `'bigint'`,
+ * not `'number'`. Accept both and coerce.
+ */
+declare function recordFromYAny(any: unknown): MessageRecord | null;
 //#endregion
 //#region packages/provider/src/NotificationsClient.d.ts
+/** Per-user inbox doc entry. Mirrors `InboxEntry` on the server. */
+interface InboxEntry {
+  id: string;
+  /** "mention" | "reply" | "dm" | "system". */
+  kind: string;
+  channel_doc_id: string;
+  message_id?: string | null;
+  sender_id?: string | null;
+  sender_name?: string | null;
+  /** Empty for E2E channels (server can't read body). Filled otherwise. */
+  preview?: string | null;
+  ts: number;
+  /** Synthesized client-side from the inbox doc's `read` Y.Map. */
+  read: boolean;
+}
+interface FetchInboxInput {
+  before?: number;
+  limit?: number;
+  unread_only?: boolean;
+}
+interface MarkReadInput$1 {
+  id?: string;
+  ids?: string[];
+  source_id?: string;
+  all?: boolean;
+}
 /**
- * Typed client for the Abracadabra notifications feature.
+ * Thin façade over the `messages:inbox_*` stateless protocol.
+ *
+ * Per-user notifications live as Y.Array entries on the user's inbox doc
+ * (`kind = "inbox"`, owned by the user, child of the server root, server-only
+ * writer). Real-time observation of new entries is a Y.Array observer the
+ * consumer attaches via `AbracadabraProvider` on the inbox doc.
+ *
+ * This client handles only the request/response layer:
+ *   - `fetch()` issues `messages:inbox_fetch`, returns the entry list.
+ *   - `markRead()` issues `messages:inbox_mark_read` (id / ids / source_id /
+ *     all variants).
  *
- * Emits:
- *   - `new`        → NotificationRecord      (incoming notify:new broadcast)
- *   - `readUpdate` → NotificationReadUpdate  (broadcast after mark_read / mark_all_read)
+ * For incoming notification observation, open an AbracadabraProvider on the
+ * inbox doc and observe its `entries` Y.Array directly. The dashboard's
+ * `useNotifications` composable does this.
  */
 declare class NotificationsClient extends EventEmitter {
   private readonly provider;
   private readonly responseTimeoutMs;
   private readonly pending;
   private readonly boundOnStateless;
+  private readonly boundOnServerError;
   constructor(provider: ChatClientTransport, options?: {
     responseTimeoutMs?: number;
   });
   destroy(): void;
+  /** Fetch a slice of the calling user's inbox. Resolves with the entries. */
+  fetch(input?: FetchInboxInput): Promise<{
+    entries: InboxEntry[];
+  }>;
   /**
-   * Create a notification targeting a specific recipient. Requires elevated role
-   * (service or admin); a `server:error` event with code `forbidden` is emitted
-   * by the underlying provider if the caller lacks permission.
+   * Mark inbox entries read. One of `id`, `ids`, `source_id`, or `all`.
+   * Returns when the server has acked.
    */
-  create(input: CreateNotificationInput): void;
-  /** Fetch notification history for the current user. */
-  fetch(input?: FetchNotificationsInput): Promise<{
-    notifications: NotificationRecord[];
-  }>;
-  /** Mark a single notification, or a batch, as read. */
-  markRead(target: {
-    id: string;
-  } | {
-    ids: string[];
-  }): void;
-  /** Mark every notification for the current user as read. */
-  markAllRead(): void;
-  /** Mark all notifications generated by the given source (e.g. a chat channel) as read. */
-  markReadBySource(sourceId: string): void;
-  onNew(fn: (n: NotificationRecord) => void): this;
-  onReadUpdate(fn: (u: NotificationReadUpdate) => void): this;
+  markRead(input: MarkReadInput$1): Promise<void>;
   private enqueue;
   private removePending;
   private resolveNext;
+  private rejectNext;
   private handleStateless;
+  private handleServerError;
 }
 //#endregion
 //#region node_modules/@scure/bip39/esm/wordlists/english.d.ts
@@ -3157,4 +4017,536 @@ declare function wrapSeed(seed: Uint8Array, wrappingKeyBytes: Uint8Array): Promi
  */
 declare function unwrapSeed(ciphertext: ArrayBuffer, iv: Uint8Array, wrappingKeyBytes: Uint8Array): Promise<Uint8Array>;
 //#endregion
-export { AbracadabraBaseProvider, AbracadabraBaseProviderConfiguration, AbracadabraClient, AbracadabraClientConfig, AbracadabraOutgoingMessageArguments, AbracadabraProvider, AbracadabraProviderConfiguration, AbracadabraWS, AbracadabraWSConfiguration, AbracadabraWebRTC, type AbracadabraWebRTCConfiguration, AbracadabraWebSocketConn, AuthMessageType, AuthorizedScope, AwarenessError, BackgroundSyncManager, type BackgroundSyncManagerOptions, BackgroundSyncPersistence, BroadcastChannelSync, CHANNEL_NAMES, type ChatChannel, ChatClient, type ChatClientTransport, type ChatMessage, type ChatReadCursor, type ChatReadReceipt, type ChatTypingEvent, CloseEvent, CompleteAbracadabraBaseProviderConfiguration, CompleteAbracadabraWSConfiguration, CompleteHocuspocusProviderConfiguration, CompleteHocuspocusProviderWebsocketConfiguration, ConnectionTimeout, Constructable, ConstructableOutgoingMessage, type CreateNotificationInput, CryptoIdentity, CryptoIdentityKeystore, DEFAULT_FILE_CHUNK_SIZE, DEFAULT_ICE_SERVERS, DataChannelRouter, DevicePairingChannel, type DevicePairingConfig, DeviceRegistrationService, type DeviceServerStatus, type DeviceTier, type DocEncryptionInfo, DocKeyManager, type DocSyncState, DocumentCache, type DocumentCacheOptions, DocumentMeta, E2EAbracadabraProvider, E2EEChannel, type E2EEIdentity, E2EOfflineStore, EffectivePermissionEntry, EffectivePermissionsResponse, EffectiveRole, EncryptedYMap, EncryptedYText, type FetchNotificationsInput, FileBlobStore, FileTransferChannel, FileTransferHandle, type FileTransferMeta, type FileTransferStatus, Forbidden, type GetChatHistoryInput, HealthStatus, HocusPocusWebSocket, HocuspocusProvider, HocuspocusProviderConfiguration, HocuspocusProviderWebsocket, HocuspocusProviderWebsocketConfiguration, HocuspocusWebSocket, type IdentityDeviceEntry, type IdentityDocConfiguration, IdentityDocProvider, type IdentityProfile, type IdentityServerEntry, type IdentitySpaceEntry, InviteRow, KEY_EXCHANGE_CHANNEL, ManualSignaling, type ManualSignalingBlob, MessageTooBig, MessageType, type NotificationReadUpdate, type NotificationRecord, NotificationsClient, OfflineStore, OutgoingMessageArguments, OutgoingMessageInterface, type PairingRequest, type PairingResult, PeerConnection, type PeerInfo, type PeerState, PendingSubdoc, PermissionEntry, PublicKeyInfo, ResetConnection, SearchIndex, SearchResult, type SendChatMessageInput, ServerInfo, type SignalingIncoming, type SignalingOutgoing, SignalingSocket, SnapshotCreateResult, SnapshotData, SnapshotForkResult, SnapshotMeta, SnapshotRestoreResult, SpaceMeta, StatesArray, SubdocMessage, SubdocRegisteredEvent, Unauthorized, UploadInfo, UploadMeta, UploadQueueEntry, UploadQueueStatus, UserProfile, WebSocketStatus, WsReadyStates, YjsDataChannel, attachUpdatedAtObserver, awarenessStatesToArray, wordlist as bip39Wordlist, decryptField, deriveIdentityDocId, deriveSeedWrappingKey, encryptField, generateMnemonic, makeEncryptedYMap, makeEncryptedYText, mnemonicToEd25519Seed, mnemonicToKeyPair, onAuthenticatedParameters, onAuthenticationFailedParameters, onAwarenessChangeParameters, onAwarenessUpdateParameters, onCloseParameters, onCompactedParameters, onDisconnectParameters, onMessageParameters, onOpenParameters, onOutgoingMessageParameters, onServerErrorParameters, onStatelessParameters, onStatusParameters, onSubdocLoadedParameters, onSubdocRegisteredParameters, onSyncedParameters, onUnsyncedChangesParameters, readAuthMessage, unwrapSeed, validateMnemonic, wrapSeed, writeAuthenticated, writeAuthentication, writePermissionDenied, writeTokenSyncRequest };
+//#region packages/provider/src/DocTypes.d.ts
+/**
+ * Canonical type definitions for Abracadabra document tree entries, page
+ * metadata, and the static page-type catalog.
+ *
+ * These types were previously scattered across `mcp/converters/types.ts` and
+ * `mcp/converters/page-types.ts`.  By living in the provider package they
+ * become first-class SDK types that any consumer (`@abraca/dabra`) can import
+ * directly, removing the need for fragile relative-path re-exports.
+ */
+type MetaFieldType = 'datetimerange' | 'daterange' | 'timerange' | 'datetime' | 'date' | 'time' | 'slider' | 'number' | 'toggle' | 'select' | 'multiselect' | 'colorPreset' | 'colorPicker' | 'location' | 'icon' | 'textarea' | 'url' | 'rating' | 'tags' | 'members';
+interface UserMetaField {
+  id: string;
+  type: string;
+  label?: string;
+  key?: string;
+  latKey?: string;
+  lngKey?: string;
+  startKey?: string;
+  endKey?: string;
+  allDayKey?: string;
+  presets?: string[];
+  options?: string[];
+  min?: number;
+  max?: number;
+  step?: number;
+  unit?: string;
+  default?: boolean;
+}
+interface PageMeta extends Record<string, unknown> {
+  color?: string;
+  icon?: string;
+  subtitle?: string;
+  note?: string;
+  datetimeStart?: string;
+  datetimeEnd?: string;
+  allDay?: boolean;
+  dateStart?: string;
+  dateEnd?: string;
+  timeStart?: string;
+  timeEnd?: string;
+  dateTaken?: string;
+  checked?: boolean;
+  priority?: number;
+  status?: string;
+  taskProgress?: number;
+  rating?: number;
+  tags?: string[];
+  members?: {
+    id: string;
+    label: string;
+  }[];
+  url?: string;
+  email?: string;
+  phone?: string;
+  number?: number;
+  unit?: string;
+  coverUploadId?: string;
+  coverDocId?: string;
+  coverMimeType?: string;
+  geoType?: 'marker' | 'line' | 'measure';
+  geoLat?: number;
+  geoLng?: number;
+  geoDescription?: string;
+  deskX?: number;
+  deskY?: number;
+  deskZ?: number;
+  deskMode?: string;
+  mmX?: number;
+  mmY?: number;
+  graphX?: number;
+  graphY?: number;
+  graphPinned?: boolean;
+  spShape?: string;
+  spOpacity?: number;
+  spX?: number;
+  spY?: number;
+  spZ?: number;
+  spRX?: number;
+  spRY?: number;
+  spRZ?: number;
+  spSX?: number;
+  spSY?: number;
+  spSZ?: number;
+  spModelUploadId?: string;
+  spModelDocId?: string;
+  slidesTransition?: string;
+  slidesTheme?: string;
+  mediaDuration?: number;
+  mediaWidth?: number;
+  mediaHeight?: number;
+  mediaCamera?: string;
+  mediaLens?: string;
+  mediaIso?: number;
+  mediaFocalLength?: number;
+  mediaAperture?: number;
+  mediaShutterSpeed?: string;
+  mediaArtist?: string;
+  mediaAlbum?: string;
+  mediaGenre?: string;
+  mediaYear?: number;
+  bold?: boolean;
+  italic?: boolean;
+  textColor?: string;
+  bgColor?: string;
+  align?: string;
+  formula?: string;
+  fileType?: string;
+  entry?: boolean;
+  kanbanColumnWidth?: string;
+  galleryColumns?: number;
+  galleryAspect?: string;
+  galleryCardStyle?: string;
+  galleryShowLabels?: boolean;
+  gallerySortBy?: string;
+  calendarView?: string;
+  calendarWeekStart?: string;
+  calendarShowWeekNumbers?: boolean;
+  tableMode?: string;
+  tableSortKey?: string;
+  tableSortDir?: string;
+  tableColumns?: any[];
+  tableColumnWidths?: Record<string, number>;
+  tableColumnOrder?: string[];
+  timelineZoom?: string;
+  timelinePixelsPerDay?: number;
+  timelineCenterDate?: string;
+  checklistFilter?: string;
+  checklistSort?: string;
+  mapShowLabels?: boolean;
+  spatialGridVisible?: boolean;
+  graphSpacing?: string;
+  graphShowLabels?: boolean;
+  graphEdgeThickness?: string;
+  mmSpacing?: string;
+  showRefEdges?: boolean;
+  chartType?: string;
+  chartMetric?: string;
+  chartColorScheme?: string;
+  chartLimit?: number;
+  chartShowLegend?: boolean;
+  chartShowValues?: boolean;
+  mediaRepeat?: string;
+  mediaShuffle?: boolean;
+  sheetsDefaultColWidth?: number;
+  sheetsDefaultRowHeight?: number;
+  sheetsShowGridlines?: boolean;
+  sheetsColumnWidths?: Record<string, number>;
+  sheetsRowHeights?: Record<string, number>;
+  sheetsFreezeRows?: number;
+  sheetsFreezeCols?: number;
+  _metaFields?: UserMetaField[];
+  _metaInitialized?: boolean;
+}
+interface TreeEntry {
+  id: string;
+  label: string;
+  parentId: string | null;
+  order: number;
+  type?: string;
+  meta?: PageMeta;
+  createdAt?: number;
+  updatedAt?: number;
+}
+interface TreeNode {
+  id: string;
+  label: string;
+  type?: string;
+  meta?: PageMeta;
+  order: number;
+  children: TreeNode[];
+}
+interface TreeSearchResult {
+  id: string;
+  label: string;
+  type?: string;
+  meta?: PageMeta;
+  /** Ancestor labels from root → parent. */
+  path: string[];
+}
+interface PageTypeMetaField {
+  type: MetaFieldType;
+  label?: string;
+  /** single-value fields */
+  key?: string;
+  /** location */
+  latKey?: string;
+  lngKey?: string;
+  /** ranges */
+  startKey?: string;
+  endKey?: string;
+  allDayKey?: string;
+  /** color preset */
+  presets?: string[];
+  /** icon / select / tags */
+  options?: string[];
+  /** slider / number */
+  min?: number;
+  max?: number;
+  step?: number;
+  unit?: string;
+  /** toggle default */
+  default?: boolean;
+}
+interface PageTypeInfo {
+  key: string;
+  label: string;
+  icon: string;
+  description?: string;
+  /** true = core type (always available); false = requires plugin */
+  core: boolean;
+  plugin?: string;
+  supportsChildren: boolean;
+  childLabel?: string;
+  grandchildLabel?: string;
+  /** -1 = unlimited depth */
+  defaultDepth?: number;
+  /** Fields that apply to this doc's descendants (children, grandchildren, ...) */
+  metaSchema?: PageTypeMetaField[];
+  /** Fields written to this doc's own meta on first render (renderer config) */
+  defaultMetaFields?: PageTypeMetaField[];
+}
+declare const GEO_TYPE_META_SCHEMAS: Record<string, PageTypeMetaField[]>;
+declare const PAGE_TYPES: Record<string, PageTypeInfo>;
+declare const TYPE_ALIASES: Record<string, string>;
+declare function resolvePageType(key: string | undefined): PageTypeInfo | undefined;
+//#endregion
+//#region packages/provider/src/TreeManager.d.ts
+declare class TreeManager {
+  private dm;
+  constructor(dm: DocumentManager);
+  /** Read all tree entries as plain objects. */
+  readEntries(): TreeEntry[];
+  /** Get immediate children of a parent (sorted by order). */
+  childrenOf(parentId: string | null): TreeEntry[];
+  /** Get all descendants recursively. */
+  descendantsOf(parentId: string | null): TreeEntry[];
+  /** Build nested tree JSON. */
+  buildTree(rootId?: string | null, maxDepth?: number): TreeNode[];
+  private _buildTree;
+  /** Find a single entry by ID. */
+  get(docId: string): TreeEntry | null;
+  /** Search by label (case-insensitive substring match). */
+  find(query: string, rootId?: string | null): TreeSearchResult[];
+  /** Create a new document in the tree. Returns the new entry. */
+  create(opts: {
+    parentId?: string | null;
+    label: string;
+    type?: string;
+    meta?: Partial<PageMeta>;
+  }): TreeEntry;
+  /**
+   * Create a document and auto-apply renderer defaults from the page type's
+   * `defaultMetaFields` (toggle fields with `default` values).
+   */
+  createWithTypeDefaults(opts: {
+    parentId?: string | null;
+    label: string;
+    type: string;
+    extraMeta?: Partial<PageMeta>;
+  }): TreeEntry;
+  /** Rename a document. */
+  rename(docId: string, label: string): void;
+  /** Move a document to a new parent. */
+  move(docId: string, newParentId?: string | null, order?: number): void;
+  /** Change the page type of a document. */
+  changeType(docId: string, type: string): void;
+  /**
+   * Soft-delete a document and descendants (move to trash).
+   * @returns count of deleted documents
+   */
+  delete(docId: string): number;
+  /** Duplicate a document (shallow clone). Returns the new entry. */
+  duplicate(docId: string): TreeEntry;
+  /** Restore a document from trash back into the tree. */
+  restore(docId: string): void;
+  /** List trashed documents. */
+  listTrash(): TreeEntry[];
+  /** Get enabled plugin names from space-plugins map. */
+  getEnabledPlugins(): string[];
+  private _descendantIds;
+}
+//#endregion
+//#region packages/provider/src/DocConverters.d.ts
+/**
+ * Converts a Y.XmlFragment (TipTap document) to markdown.
+ * Extracts the title from the documentHeader element.
+ *
+ * @returns `{ title, markdown }` where title is the H1/header text
+ */
+declare function yjsToMarkdown(fragment: Y.XmlFragment): {
+  title: string;
+  markdown: string;
+};
+declare function filenameToLabel(raw: string): string;
+interface FrontmatterResult {
+  title?: string;
+  meta: Partial<PageMeta>;
+  body: string;
+}
+declare function parseFrontmatter(markdown: string): FrontmatterResult;
+declare function populateYDocFromMarkdown(fragment: Y.XmlFragment, markdown: string, fallbackTitle?: string): void;
+declare function buildHeadingElement(text: string, level?: 1 | 2 | 3 | 4 | 5 | 6): Y.XmlElement;
+declare function buildParagraphElement(text: string): Y.XmlElement;
+declare function buildBulletListElement(items: string[]): Y.XmlElement;
+declare function buildOrderedListElement(items: string[]): Y.XmlElement;
+declare function buildTaskListElement(items: Array<{
+  text: string;
+  checked?: boolean;
+}>): Y.XmlElement;
+declare function buildCodeBlockElement(code: string, language?: string): Y.XmlElement;
+declare function buildBlockquoteElement(text: string): Y.XmlElement;
+declare function buildHorizontalRuleElement(): Y.XmlElement;
+/** Parse markdown into block Y.XmlElements (no header/meta). */
+declare function buildBlocksFromMarkdown(markdown: string): Y.XmlElement[];
+interface DocumentBlock {
+  type: string;
+  attrs: Record<string, unknown>;
+  text: string;
+  items?: string[];
+  children?: DocumentBlock[];
+}
+declare function readBlocksFromFragment(fragment: Y.XmlFragment): DocumentBlock[];
+//#endregion
+//#region packages/provider/src/ContentManager.d.ts
+interface DocumentContent {
+  label: string;
+  type?: string;
+  meta?: PageMeta;
+  title: string;
+  markdown: string;
+  children: Array<{
+    id: string;
+    label: string;
+    type?: string;
+    meta?: PageMeta;
+  }>;
+}
+declare class ContentManager {
+  private dm;
+  constructor(dm: DocumentManager);
+  /**
+   * Read document content as markdown.
+   * Returns the title extracted from the TipTap documentHeader, the markdown
+   * body, tree metadata, and immediate children.
+   */
+  read(docId: string): Promise<DocumentContent>;
+  /**
+   * Write markdown content to a document.
+   * Supports optional YAML frontmatter for title and metadata.
+   *
+   * @param mode - "replace" clears existing content first (default),
+   *               "append" adds to the end.
+   */
+  write(docId: string, markdown: string, mode?: "replace" | "append"): Promise<void>;
+  private _appendElements;
+  appendHeading(docId: string, text: string, opts?: {
+    level?: 1 | 2 | 3 | 4 | 5 | 6;
+  }): Promise<void>;
+  appendParagraph(docId: string, text: string): Promise<void>;
+  appendBulletList(docId: string, items: string[]): Promise<void>;
+  appendOrderedList(docId: string, items: string[]): Promise<void>;
+  appendTaskList(docId: string, items: Array<{
+    text: string;
+    checked?: boolean;
+  }>): Promise<void>;
+  appendCodeBlock(docId: string, code: string, opts?: {
+    language?: string;
+  }): Promise<void>;
+  appendBlockquote(docId: string, text: string): Promise<void>;
+  appendHorizontalRule(docId: string): Promise<void>;
+  appendMarkdown(docId: string, markdown: string): Promise<void>;
+  getBlocks(docId: string): Promise<DocumentBlock[]>;
+  /**
+   * Get the raw Y.XmlFragment for a document (the 'default' fragment
+   * that TipTap uses for document content).
+   */
+  getFragment(docId: string): Promise<Y.XmlFragment>;
+  /**
+   * Get the raw Y.Doc for a document (synced).
+   */
+  getDoc(docId: string): Promise<Y.Doc>;
+}
+//#endregion
+//#region packages/provider/src/MetaManager.d.ts
+interface DocumentMetaInfo {
+  id: string;
+  label: string;
+  type?: string;
+  meta: PageMeta;
+}
+declare class MetaManager {
+  private dm;
+  constructor(dm: DocumentManager);
+  /** Read metadata for a document. Returns null if not found. */
+  get(docId: string): DocumentMetaInfo | null;
+  /**
+   * Merge fields into a document's metadata.
+   * Existing keys not in the update are preserved.
+   */
+  update(docId: string, meta: Partial<PageMeta>): void;
+  /**
+   * Replace all metadata on a document.
+   * This overwrites the entire meta object.
+   */
+  set(docId: string, meta: PageMeta): void;
+  /**
+   * Clear specific metadata keys (set them to null/undefined).
+   */
+  clear(docId: string, keys: string[]): void;
+}
+//#endregion
+//#region packages/provider/src/DocumentManager.d.ts
+interface DocumentManagerConfig {
+  /** Server base URL (http or https). */
+  url: string;
+  /** Display name for awareness (cursor labels, presence). */
+  name?: string;
+  /** Cursor / awareness color. */
+  color?: string;
+  /** Invite code for first-time registration. */
+  inviteCode?: string;
+  /** Suppress stderr logging. */
+  quiet?: boolean;
+  /** Disable IndexedDB offline persistence. */
+  disableOfflineStore?: boolean;
+  /** Custom fetch for Node.js environments. */
+  fetch?: typeof globalThis.fetch;
+  /**
+   * Pre-configured AbracadabraClient instance.
+   * When provided, the `url` and `fetch` fields are ignored — the client's
+   * configuration is used instead. This is useful when the consumer has
+   * already authenticated or configured the client externally.
+   */
+  client?: AbracadabraClient;
+  /**
+   * Shared WebSocket connection. Required in Node.js environments — pass an
+   * AbracadabraWS constructed with WebSocketPolyfill set to the `ws` package.
+   * When omitted, each provider creates its own connection from client.wsUrl.
+   * The caller owns this instance and must destroy it after dm.destroy().
+   */
+  websocketProvider?: AbracadabraWS;
+  /**
+   * Known root document ID. When provided, connect() skips server discovery
+   * and connects directly to this document. Useful in tests or CLIs where
+   * the entry-point docId is already known.
+   */
+  rootDocId?: string;
+}
+declare class DocumentManager {
+  readonly client: AbracadabraClient;
+  /** Tree CRUD operations. */
+  readonly tree: TreeManager;
+  /** Document content read/write. */
+  readonly content: ContentManager;
+  /** Document metadata read/write. */
+  readonly meta: MetaManager;
+  private _config;
+  private _serverInfo;
+  private _rootDocId;
+  private _spaces;
+  private _rootDoc;
+  private _rootProvider;
+  private childCache;
+  constructor(config: DocumentManagerConfig);
+  get displayName(): string;
+  get displayColor(): string;
+  get serverInfo(): ServerInfo | null;
+  get rootDocId(): string | null;
+  get rootDocument(): Y.Doc | null;
+  get rootProvider(): AbracadabraProvider | null;
+  /**
+   * Spaces visible to the caller — direct children of the server root with
+   * `kind === "space"`. Populated by {@link connect}.
+   */
+  get spaces(): DocumentMeta[];
+  get isConnected(): boolean;
+  /** Get the root doc-tree Y.Map. */
+  getTreeMap(): Y.Map<any> | null;
+  /** Get the root doc-trash Y.Map. */
+  getTrashMap(): Y.Map<any> | null;
+  /** Get the root space-plugins Y.Map. */
+  getPluginsMap(): Y.Map<any> | null;
+  /**
+   * Connect to the server: discover the entry-point document, sync the root
+   * Y.Doc, and set awareness.
+   *
+   * **Authentication must be done before calling connect().**
+   * Call `dm.client.loginWithKey(publicKey, signFn)` or `dm.client.login()`
+   * to authenticate first.
+   *
+   * When `rootDocId` is set in the config, server discovery is skipped and
+   * the manager connects directly to that document.
+   */
+  connect(): Promise<void>;
+  /** Switch active space to a different root document. */
+  switchSpace(docId: string): Promise<void>;
+  /** Create, sync, and set awareness on a root provider for the given docId. */
+  private _connectToRoot;
+  /** Graceful shutdown. */
+  destroy(): Promise<void>;
+  /** Get or create a child provider for a document (synced). */
+  getChildProvider(docId: string): Promise<AbracadabraProvider>;
+  private log;
+}
+//#endregion
+//#region packages/provider/src/DocUtils.d.ts
+/**
+ * Wait for a provider's `synced` event with a timeout.
+ * Resolves immediately if the provider is already synced.
+ */
+declare function waitForSync(provider: {
+  isSynced?: boolean;
+  on(event: string, cb: () => void): void;
+  off(event: string, cb: () => void): void;
+}, timeoutMs?: number): Promise<void>;
+/**
+ * Wrap a promise with a timeout.
+ */
+declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, message?: string): Promise<T>;
+/**
+ * Normalize a document ID so the hub/root doc ID is treated as the tree root
+ * (null). This lets callers pass the hub doc_id from list_spaces as
+ * parentId/rootId and get the expected root-level results instead of an empty
+ * set.
+ */
+declare function normalizeRootId(id: string | null | undefined, rootDocId: string | null): string | null;
+/**
+ * Safely read a tree map value, converting Y.Map to plain object if needed.
+ */
+declare function toPlain(val: unknown): unknown;
+//#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, 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 DeviceTier, type DocEncryptionInfo, DocKeyManager, DocSearchHit, type DocSyncState, type DocumentBlock, DocumentCache, type DocumentCacheOptions, type DocumentContent, DocumentManager, type DocumentManagerConfig, DocumentMeta, type DocumentMetaInfo, 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, ManualSignaling, type ManualSignalingBlob, type MessageRecord, MessageTooBig, MessageType, MetaFieldType, MetaManager, 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, 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, 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, TreeEntry, TreeManager, TreeNode, TreeSearchResult, 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, mnemonicToEd25519Seed, mnemonicToKeyPair, normalizeRootId, onAuthenticatedParameters, onAuthenticationFailedParameters, onAwarenessChangeParameters, onAwarenessUpdateParameters, onCloseParameters, onCompactedParameters, onDisconnectParameters, onMessageParameters, onOpenParameters, onOutgoingMessageParameters, onServerErrorParameters, onStatelessParameters, onStatusParameters, onSubdocLoadedParameters, onSubdocRegisteredParameters, onSyncedParameters, onUnsyncedChangesParameters, parseFrontmatter, populateYDocFromMarkdown, readAuthMessage, readBlocksFromFragment, recordFromYAny, resolvePageType, toPlain, unwrapSeed, validateMnemonic, waitForSync, withTimeout, wrapSeed, writeAuthenticated, writeAuthentication, writePermissionDenied, writeTokenSyncRequest, yjsToMarkdown };