@drakkar.software/octospaces-sdk 0.1.0 → 0.4.3

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { WrappedKeyEntry } from '@drakkar.software/starfish-keyring';
+import * as _drakkar_software_starfish_client from '@drakkar.software/starfish-client';
 import { StarfishClient, Encryptor, StarfishCapProvider, PullCache } from '@drakkar.software/starfish-client';
 import { CapCert, Base64Provider } from '@drakkar.software/starfish-protocol';
 import { BootstrapOrigin, ScopePreset } from '@drakkar.software/starfish-identities';
@@ -89,19 +90,23 @@ declare function capProviderFor(cap: unknown, devEdPrivHex: string): StarfishCap
  */
 declare function makeClient(cap: unknown, devEdPrivHex: string, namespaceOverride?: string): StarfishClient;
 /**
- * Open a SPACE's decryptor, throwing a descriptive error per failure mode
+ * Open a node's decryptor, throwing a descriptive error per failure mode
  * (unreachable server / no keyring yet / not a recipient).
  *
- * A `SpaceAccessError` is a hard access denial; any other thrown error is a
- * transient offline state.
+ * `keyringPullPath` is the full `/pull/.../_keyring` path (e.g. from
+ * `keyringPull(spaceId)`). A `SpaceAccessError` is a hard access
+ * denial; any other thrown error is a transient offline state.
  */
-declare function openEncryptor(client: StarfishClient, keys: DeviceKeys, spaceId: string, trustedAdders: string[]): Promise<Encryptor>;
+declare function openEncryptor(client: StarfishClient, keys: DeviceKeys, keyringPullPath: string, trustedAdders: string[]): Promise<Encryptor>;
 /** Soft variant of {@link openEncryptor}: returns null instead of throwing. */
-declare function buildEncryptor(client: StarfishClient, keys: DeviceKeys, spaceId: string, trustedAdders: string[]): Promise<Encryptor | null>;
+declare function buildEncryptor(client: StarfishClient, keys: DeviceKeys, keyringPullPath: string, trustedAdders: string[]): Promise<Encryptor | null>;
 /**
- * Owner-side: create the SPACE keyring if missing, return an encryptor.
+ * Owner-side: create a per-node keyring if missing, return an encryptor.
+ *
+ * `keyringPullPath` / `keyringPushPath` are the full `/pull|push/.../_keyring`
+ * paths (e.g. from `keyringPull`/`keyringPush`).
  */
-declare function ownerEnsureKeyring(client: StarfishClient, keys: DeviceKeys, spaceId: string, trustedAdders?: string[]): Promise<Encryptor>;
+declare function ownerEnsureKeyring(client: StarfishClient, keys: DeviceKeys, keyringPullPath: string, keyringPushPath: string, trustedAdders?: string[]): Promise<Encryptor>;
 /** A user's public profile: display pseudo + optional inline avatar + public identity keys. */
 interface PublicProfile {
     pseudo: string | null;
@@ -297,16 +302,19 @@ declare function sealToRecipient(session: Session, recipientKemPub: string, plai
 declare function unsealFromRecipient(session: Session, blob: SealedBlob): Promise<string>;
 
 type ID = string;
-/** Maps a joined private space's id → its owner-issued member cap-cert (serialized
- *  JSON). Persisted both in device-local kv (`member-caps.ts`) and, for durability,
- *  in the user's own synced `_spaces` doc so a fresh device re-hydrates it. */
+/** A user's presence indicator. The theme maps each to a color (app-side). */
+type PresenceStatus = 'online' | 'away' | 'dnd' | 'offline';
+/** A security item's verification state. The theme maps each to a color (app-side).
+ *  `none` = unknown / not yet verified; maps to a neutral/muted color in the theme. */
+type VerificationLevel = 'verified' | 'pending' | 'unverified' | 'none';
+/** Maps a joined space's id → its owner-issued member cap-cert (serialized JSON).
+ *  Persisted both in device-local kv and, for durability, in the user's own synced
+ *  `_spaces` doc so a fresh device re-hydrates it. */
 type CapMap = Record<string, string>;
-/** Maps a joined PUBLIC space's id → its invitation credential (the owner-signed cap
- *  plus the link's ephemeral private key) SEALED to the account's own key. Unlike a
- *  member cap (safe in the clear — see {@link CapMap}), a public-join credential
- *  embeds a bearer secret, so it is sealed before riding in the plaintext `_spaces`
- *  doc. Recovered on any device with the same seed. See `account-seal.ts` and
- *  `space-access-store.ts`. */
+/** Maps a joined link-access key → its sealed invitation credential (cap + ephemeral
+ *  private key) SEALED to the account's own key. Keys are either `spaceId` (space-level
+ *  link) or `${spaceId}:${nodeId}` (per-node invite link). Sealed because it embeds a
+ *  bearer secret; recovered on any device with the same seed. */
 type PubAccessMap = Record<string, SealedBlob>;
 /** Maps a DM peer's userId → the private DM-space id shared with them. */
 type DmMap = Record<string, string>;
@@ -325,8 +333,8 @@ type ReadValue = number;
 interface ReadPrefs {
     rooms: Record<string, ReadValue>;
 }
-/** Whether a space encrypts its content client-side. */
-type SpaceVisibility = 'private' | 'public';
+/** A joined or listed space. Visibility and encryption are per-node (see ObjectNode),
+ *  not per-space — a space is a neutral container. */
 interface Space {
     id: ID;
     name: string;
@@ -336,93 +344,51 @@ interface Space {
     image?: string;
     members: number;
     unread?: number;
-    /** 'private' (E2EE keyring, the default) or 'public' (plaintext, joined via a
-     *  space-wide invitation link). Absent ⇒ treat as 'private' (back-compat). */
-    visibility?: SpaceVisibility;
-    /** Public spaces only: the owner's userId (derived from the cap issuer). */
-    ownerId?: string;
-    /** Public spaces only (joiner side): whether this identity's invite link grants write. */
-    write?: boolean;
-}
-/** Legacy room kind — used while apps migrate their content onto objects.
- *  New code should use {@link RoomSubtype} directly. */
-type RoomKind = 'channel' | 'dm' | 'automated';
-/** Scheduled-fetch cadence for automated rooms. */
-type AutomationSchedule = {
-    kind: 'interval';
-    everyMin: number;
-} | {
-    kind: 'daily';
-    hour: number;
-    minute: number;
-} | {
-    kind: 'weekly';
-    weekday: number;
-    hour: number;
-    minute: number;
-} | {
-    kind: 'cron';
-    expression: string;
-};
-/** Stored, synced configuration of an `automated` room. */
-interface AutomationMeta {
-    providerId: string;
-    params: Record<string, unknown>;
-    intervalMin: number;
-    schedule?: AutomationSchedule;
-    onOpen?: boolean;
-    enabled: boolean;
-    credential: SealedBlob;
-    botUserId?: string;
-    runOnDeviceId: string | null;
-    lastRunAt: number | null;
-    lastFetchHash?: string | null;
-    lastError: string | null;
-}
-/** A transitional Room shape (used while apps migrate onto the object model). */
-interface Room {
-    id: ID;
-    spaceId: ID;
-    category: string;
-    name: string;
-    kind: RoomKind;
-    topic?: string;
-    unread?: number;
-    mention?: boolean;
-    avatar?: string;
-    automation?: AutomationMeta;
-}
-/** The builtin object types. Custom types ride the same `string` field. */
-type BuiltinObjectType = 'room' | 'category' | 'automation' | 'doc' | 'project' | 'task';
-type ObjectType = BuiltinObjectType | (string & {});
-/** Runtime set of builtin type strings for renderer branching. */
-declare const BUILTIN_OBJECT_TYPES: readonly BuiltinObjectType[];
-/** How an object's content syncs. Builtins infer this; custom types set it explicitly. */
+}
+/** Any string an app assigns as an object's type. No builtins are defined here —
+ *  each app declares its own type strings in its local SDK. */
+type ObjectType = string;
+/** How an object's content syncs. Apps may set this per-type explicitly. */
 type ObjectContentKind = 'merge' | 'append' | 'none';
-/** When `type === 'room'`, the room flavour. */
-type RoomSubtype = 'channel' | 'dm' | 'automation';
+/** Who may read a node's content (independent from whether it is E2EE):
+ *  - `'public'`  — world-readable; anonymous users may access the content. The node
+ *                  is listed in the global object directory (`_index/objects/{shard}`).
+ *  - `'space'`   — any member of the parent space. The default for new nodes.
+ *  - `'invite'`  — only members explicitly invited to this node (via its own per-node
+ *                  keyring for E2EE nodes, or via a per-node cap for plaintext nodes).
+ *                  Non-invited space members see a placeholder row (no title/emoji). */
+type NodeAccess = 'public' | 'space' | 'invite';
 /**
  * One entry in a space's object index (`spaces/{spaceId}/objects/_index`).
  * Identity + tree position + light metadata ONLY — heavy content (messages, doc
- * blocks, project event log) lives in a per-object content doc keyed by `id`.
+ * blocks, event logs) lives in per-object content docs keyed by `id`.
+ *
+ * The index doc is always **plaintext** (member-gated). For `invite` nodes the
+ * `title` and `emoji` fields are stored empty in the index — only invited members
+ * can recover the real title from the node's content doc or encrypted keyring entry.
  */
 interface ObjectNode {
     id: ID;
     type: ObjectType;
-    subtype?: RoomSubtype;
     parentId: ID | null;
     order: number;
     title: string;
     emoji?: string;
     updatedAt: number;
     archived?: boolean;
-    automation?: AutomationMeta;
     contentKind?: ObjectContentKind;
+    /** Who may access this node's content. Absent ⇒ `'space'`. */
+    access?: NodeAccess;
+    /** True ⇒ this node's content is E2EE under the SPACE-WIDE keyring at
+     *  `spaces/{spaceId}/_keyring`. All `enc` nodes in a space share one CEK.
+     *  The combination `public + enc` is invalid. */
+    enc?: boolean;
+    /** App-specific fields. Apps store type-specific metadata here. */
     meta?: Record<string, unknown>;
 }
-/** The object-index doc: the union-merged list of every object in a space. */
+/** The object-index doc stored at `spaces/{spaceId}/objects/_index`. */
 interface ObjectsIndex {
-    v: 1;
+    v: 1 | 2;
     objects: ObjectNode[];
     updatedAt: number;
 }
@@ -443,7 +409,7 @@ declare function randomId(): string;
 declare function roomSlug(name: string): string;
 
 /**
- * Collection path + cap-scope helpers (merged from OctoChat + OctoVault).
+ * Collection path + cap-scope helpers for OctoSpaces.
  *
  * Paths are signed relative to SYNC_BASE; the server mounts the sync router at
  * root, so they start with /pull or /push. Everything for a space is nested under
@@ -452,42 +418,72 @@ declare function roomSlug(name: string): string;
  * covers a whole space.
  *
  * **Generic object collections** — scopes use the `obj*` collection names (the
- * domain-neutral storage layer both apps migrate onto). App-specific collection
- * names like `'chat'` are left for the consumer's own `paths.ts` extension until
- * that app finishes migrating.
+ * domain-neutral storage layer). The access record lives at
+ * `spaces/{spaceId}/_access` (collection `spaceregistry`); the space-wide keyring at
+ * `spaces/{spaceId}/_keyring` (collection `spacekeyring`). ONE keyring per space
+ * encrypts ALL the space's `enc` nodes.
+ *
+ * Note: `objinv` (invite-plaintext content) is intentionally EXCLUDED from
+ * OBJECT_COLLECTIONS / spaceMemberScope — only a per-node cap can reach it.
  */
 
+/** A room id is `sp-<rand>-<name>`; the space is its first two `-` segments. */
+declare const spaceIdFromRoomId: (roomId: string) => string;
+/** Base name used as the `collectionName` arg to `addCollectionRecipient`.
+ *  Appending `/_keyring` gives the full storage path. */
 declare const keyringName: (spaceId: string) => string;
 declare const keyringPull: (spaceId: string) => string;
 declare const keyringPush: (spaceId: string) => string;
+/** Storage path of one attachment blob — also the AAD bound into its seal. */
+declare const attachmentName: (roomId: string, blobId: string) => string;
 declare const attachmentPull: (roomId: string, blobId: string) => string;
 declare const attachmentPush: (roomId: string, blobId: string) => string;
 declare const profilePull: (userId: string) => string;
 declare const profilePush: (userId: string) => string;
 declare const spacesPull: (userId: string) => string;
 declare const spacesPush: (userId: string) => string;
-declare const roomsRegistryPull: (spaceId: string) => string;
-declare const roomsRegistryPush: (spaceId: string) => string;
+declare const spaceAccessPull: (spaceId: string) => string;
+declare const spaceAccessPush: (spaceId: string) => string;
+declare const objIndexName: (spaceId: string) => string;
 declare const objIndexPull: (spaceId: string) => string;
 declare const objIndexPush: (spaceId: string) => string;
+declare const objLogName: (spaceId: string, objectId: string) => string;
 declare const objLogPull: (spaceId: string, objectId: string) => string;
 declare const objLogPush: (spaceId: string, objectId: string) => string;
+declare const objDocName: (spaceId: string, objectId: string) => string;
 declare const objDocPull: (spaceId: string, objectId: string) => string;
 declare const objDocPush: (spaceId: string, objectId: string) => string;
+/** Storage path of one sealed object blob — also the AAD bound into its seal. */
+declare const objectBlobName: (spaceId: string, blobId: string) => string;
 declare const objectBlobPull: (spaceId: string, blobId: string) => string;
 declare const objectBlobPush: (spaceId: string, blobId: string) => string;
+declare const objPubName: (spaceId: string, nodeId: string) => string;
+declare const objPubPull: (spaceId: string, nodeId: string) => string;
+declare const objPubPush: (spaceId: string, nodeId: string) => string;
+declare const objInvName: (spaceId: string, nodeId: string) => string;
+declare const objInvPull: (spaceId: string, nodeId: string) => string;
+declare const objInvPush: (spaceId: string, nodeId: string) => string;
+declare const typesIndexName: (spaceId: string) => string;
 declare const typesIndexPull: (spaceId: string) => string;
 declare const typesIndexPush: (spaceId: string) => string;
-declare const spaceIndexPull: (shard: "public") => string;
+declare const objectDirName: (shard?: string) => string;
+declare const objectDirPull: (shard?: string) => string;
 declare const OBJECT_COLLECTIONS: string[];
 /** Full owner/device access to every space the identity owns. */
 declare function ownerScope(): ScopePreset;
 /**
- * Member access to one SPACE — its keyring + every channel's messages and
- * attachments + the room registry, all under `spaces/{spaceId}/**`. One cap
- * covers current AND future channels.
+ * Member access to one SPACE — the space keyring, every node's content docs and
+ * attachments, all under `spaces/{spaceId}/**`. Does NOT cover `objinv` (invite-
+ * plaintext content) — use `nodeMemberScope` for that. One cap covers current AND
+ * future nodes.
  */
 declare function spaceMemberScope(spaceId: string, canWrite: boolean): ScopePreset;
+/**
+ * Narrow per-node cap for `invite+plaintext` nodes. Covers ONLY the node's `objinv`
+ * content path — the space keyring is space-wide and is covered by the broader space
+ * member scope. Use `spaceMemberScope` when the bearer also needs to decrypt enc content.
+ */
+declare function nodeMemberScope(spaceId: string, nodeId: string, canWrite: boolean): ScopePreset;
 /**
  * Personal cap: profile + space registry + device directory + all spaces.
  * Note: app-specific collections like `'dminbox'` (chat) are NOT included here —
@@ -516,46 +512,62 @@ declare class SpaceAccessError extends Error {
 }
 
 /**
- * Space access resolver — returns the right (client, encryptor) pair for any
- * space regardless of whether it is private (E2EE) or public (plaintext).
+ * Space and node access resolver.
  *
- * Replaces `space-encryptor.ts`. The key invariant: public spaces have
- * `encryptor: null`; private spaces always have a live `Encryptor`.
+ * Encryption is per-node (each node has an `enc` flag) but keyed under ONE
+ * space-wide keyring at `spaces/{spaceId}/_keyring`. All `enc` nodes in a space
+ * share the same CEK; `access` gates *fetching*, the keyring gates *decryption*.
  *
- * Resolution order (same semantics as the old `getSpaceEncryptor`):
- *   1. Link entry in the access store → sign requests as the ephemeral identity;
- *      no keyring, encryptor null.
- *   2. Member entry → open the keyring as a recipient with the stored cap.
- *   3. No entry + visibility === 'public' (from `reg`) → owner mode, no keyring.
- *   4. No entry, private → either owner (open/mint keyring) or SpaceAccessError
- *      if the space's roster shows we're a member but we're not holding a cap yet.
+ * Two entry points:
+ *   - `getSpaceClient`  — returns the right StarfishClient for member-gated
+ *     space docs (index, _access). No encryptor.
+ *   - `getNodeAccess`   — resolves the (client, encryptor) for a specific node's
+ *     CONTENT. Encryptor is null for plaintext nodes; for enc nodes the encryptor
+ *     opens the SPACE keyring (not a per-node keyring).
+ *
+ * Resolution order for `getNodeAccess`:
+ *   1. Per-node link entry  → sign as ephemeral identity; encryptor from space keyring.
+ *   2. Per-node member entry → open space keyring as recipient.
+ *   3. Space-level link entry → same client; open space keyring if enc.
+ *   4. Space-level member entry → open space keyring if enc.
+ *   5. No entry, owner        → mint space keyring if enc; plain client otherwise.
+ *   6. No entry, non-owner   → SpaceAccessError if enc; plain client otherwise.
  */
 
-interface SpaceAccessHandle {
+interface NodeAccessHandle {
     encryptor: Encryptor | null;
     client: StarfishClient;
-    /** True when opened as the space OWNER (so the caller must seed the room doc). */
+    /** True when opened as the space OWNER (may seed / mint the space keyring). */
     isOwnerOpen: boolean;
 }
 /** Drop every cached handle (on account switch — keys are per-identity). */
-declare function clearSpaceAccessCache(): void;
+declare function clearNodeAccessCache(): void;
+/**
+ * Return the right StarfishClient for reading/writing member-gated space docs
+ * (e.g. the `_index`, `_access`). Spaces are always plaintext — no encryptor.
+ */
+declare function getSpaceClient(spaceId: string, session: Session): StarfishClient;
 /**
- * Resolve the right (client, encryptor) for a space, opening and caching on first use.
+ * Resolve the right (client, encryptor) for a node's CONTENT, opening and
+ * caching on first use.
  *
- * `reg` is the space's `_rooms` access record if already known. Pass null when the
- * caller has not yet read the registry; the resolver will probe if needed.
+ * `node` carries `{ access?, enc? }` — the plaintext flags from the index.
+ * `reg` is the space's access record if already known; used to determine
+ * ownership. Pass null if unknown.
  */
-declare function getSpaceAccess(spaceId: string, session: Session, reg: {
+declare function getNodeAccess(spaceId: string, nodeId: string, node: {
+    access?: NodeAccess;
+    enc?: boolean;
+}, session: Session, reg?: {
     owner: string | null;
     members: string[];
-    visibility?: SpaceVisibility;
-} | null): Promise<SpaceAccessHandle>;
+} | null): Promise<NodeAccessHandle>;
 /**
  * SOFT resolve — never mints a keyring, never throws on missing access.
- * Returns null when the identity has no usable access for the space yet.
+ * Returns null when the identity has no usable access for the node yet.
  */
-declare function buildSpaceAccess(session: Session, spaceId: string, hint?: {
-    visibility?: SpaceVisibility;
+declare function buildNodeAccess(session: Session, spaceId: string, nodeId: string, node: {
+    enc?: boolean;
 }): Promise<{
     client: StarfishClient;
     encryptor: Encryptor | null;
@@ -604,6 +616,12 @@ declare function getSpaceAccessEntry(spaceId: string): SpaceAccessEntry | null;
 declare function saveSpaceAccessEntry(spaceId: string, entry: SpaceAccessEntry): void;
 /** Forget one space's access (on leaving that space). */
 declare function removeSpaceAccessEntry(spaceId: string): void;
+/** Look up a per-node invite access entry. Returns null if not invited or unknown. */
+declare function getNodeAccessEntry(spaceId: string, nodeId: string): SpaceAccessEntry | null;
+/** Persist an invite access entry for one node. */
+declare function saveNodeAccessEntry(spaceId: string, nodeId: string, entry: SpaceAccessEntry): void;
+/** Forget a node's invite access entry (e.g. on leaving the node). */
+declare function removeNodeAccessEntry(spaceId: string, nodeId: string): void;
 /** A snapshot of the in-memory cache — used by `recoverSpaceAccess` to find entries
  *  not yet on the server. */
 declare function localSpaceAccessEntries(): SpaceAccessMap;
@@ -618,102 +636,11 @@ declare function linkAccessFromStore(): Record<string, {
 /** Drop the in-memory cache (on account switch / sign-out). */
 declare function clearSpaceAccessStore(): void;
 
-/** The bucket new/unfiled objects land in, and the fallback a deleted category's
- *  objects are reassigned to. */
-declare const DEFAULT_CATEGORY = "CHANNELS";
-/** Deterministic category-node id from its name, so two devices that concurrently
- *  create the SAME category mint the SAME id → the union-merge dedupes them. */
-declare const categoryId: (name: string) => ID;
-/** A node plus its resolved children — the shape a tree view renders. */
-interface ObjectTreeNode extends ObjectNode {
-    depth: number;
-    children: ObjectTreeNode[];
-}
-/** Map a legacy {@link Room} `kind` to the unified room {@link RoomSubtype}. */
-declare function roomKindToSubtype(kind: Room['kind']): RoomSubtype;
-/** Inverse of {@link roomKindToSubtype}. A legacy persisted `'stream'` subtype hits
- *  the `default` and reads back as a plain `'channel'` (normalization). */
-declare function subtypeToRoomKind(subtype: RoomSubtype | undefined): Room['kind'];
-/** The order value for a new node appended after `siblings`. */
-declare function nextOrder(siblings: ObjectNode[]): number;
-/**
- * Build the render tree from a flat node list, repairing merge artifacts:
- *  - **archived** nodes (and their subtrees) are dropped.
- *  - **orphans** — a `parentId` that is missing or archived — reparent to root.
- *  - **cycles** — a node reachable from itself via `parentId` — reparent to root.
- *  - **siblings** sort by {@link compareSiblings} for cross-device determinism.
- */
-declare function buildTree(nodes: ObjectNode[], includeArchived?: boolean): ObjectTreeNode[];
-/** The root→node trail (inclusive) for breadcrumbs. Returns `[]` if unknown. */
-declare function breadcrumbs(nodes: ObjectNode[], id: ID): ObjectNode[];
-/** The root→parent trail (EXCLUSIVE of the node itself). */
-declare function ancestors(nodes: ObjectNode[], id: ID): ObjectNode[];
-/** The ids of a node and its whole subtree (for cascade-archive). */
-declare function subtreeIds(nodes: ObjectNode[], rootId: ID): Set<ID>;
-interface NewObjectInput {
-    type: ObjectType;
-    subtype?: RoomSubtype;
-    parentId?: ID | null;
-    title: string;
-    emoji?: string;
-    automation?: AutomationMeta;
-    /** Provide to reuse an id (e.g. a room id derived elsewhere); else minted. */
-    id?: ID;
-}
-/** Append a new node under `parentId` at the end of its sibling order. */
-declare function addObject(nodes: ObjectNode[], input: NewObjectInput, now: number): {
-    nodes: ObjectNode[];
-    node: ObjectNode;
-};
-/** Patch a node's mutable metadata (title/emoji/automation), bumping `updatedAt`. */
-declare function patchObject(nodes: ObjectNode[], id: ID, patch: Partial<Pick<ObjectNode, 'title' | 'emoji' | 'automation'>>, now: number): ObjectNode[];
-/** Reparent a node (move in the tree). Rejects making a node its own descendant. */
-declare function reparentObject(nodes: ObjectNode[], id: ID, parentId: ID | null, now: number): ObjectNode[];
-/** Set explicit sibling order (drag-reorder). */
-declare function reorderObjects(nodes: ObjectNode[], orderById: Record<ID, number>, now: number): ObjectNode[];
-/** Cascade-archive a node and its whole subtree (soft delete). */
-declare function archiveObject(nodes: ObjectNode[], id: ID, now: number): ObjectNode[];
-/** The category→rooms grouping the legacy UI consumes. */
-interface AdaptedCategory {
-    name: string;
-    rooms: Room[];
-}
-/**
- * Project the room/category nodes of an index into the legacy `{ name, rooms }[]`
- * shape that app UIs still consume. Category nodes become buckets; room nodes become
- * {@link Room}s grouped under their parent category (or `fallbackCategory` at root).
- * Returns null when the index holds no room/category nodes yet.
- *
- * @deprecated Use the object tree directly once apps complete their migration.
- */
-declare function objectsToRoomCategories(nodes: ObjectNode[], spaceId: string, fallbackCategory: string): AdaptedCategory[] | null;
-/**
- * Drop `kind: 'automated'` rooms from a category list (they belong to an Agents
- * view, not the main room list). A category that held only agents is removed too.
- *
- * @deprecated Use the object tree directly once apps complete their migration.
- */
-declare function excludeAutomatedRooms(categories: AdaptedCategory[]): AdaptedCategory[];
-/** A minimal object descriptor the {@link seedIndexNodes} builder turns into nodes. */
-interface SeedRoom {
-    id: ID;
-    name: string;
-    kind: Room['kind'];
-    category: string;
-}
-/**
- * Build the initial `ObjectNode[]` for a brand-new space's index: a `category` node
- * per distinct category and a `room` node per seed object parented under it. Pure +
- * deterministic (category ids via {@link categoryId}).
- */
-declare function seedIndexNodes(rooms: SeedRoom[], now: number): ObjectNode[];
-
-/** Owner-set, SHARED space identity, persisted in the `_rooms` registry doc
- *  (plaintext — NOT E2EE). `image` is a data URI. Both optional for back-compat. */
+/** Owner-set, SHARED space identity, persisted in the `_access` registry doc
+ *  (plaintext — NOT E2EE). `image` is a data URI. All fields optional for back-compat. */
 interface SpaceMeta {
     name?: string | null;
     image?: string | null;
-    visibility?: SpaceVisibility;
 }
 /** A resolved name/image update fanned out so the SpacesProvider adopts a
  *  freshly-reconciled value without waiting for its next navigation refresh. */
@@ -753,16 +680,14 @@ declare function updateArchivedDmsDoc(client: StarfishClient, userId: string, mu
 declare function setDmMapping(client: StarfishClient, userId: string, peerUserId: string, spaceId: string): Promise<void>;
 declare function writeSpaces(client: StarfishClient, userId: string, spaces: Space[], _hash: string | null): Promise<void>;
 declare function reorderSpaces(client: StarfishClient, userId: string, order: string[]): Promise<void>;
-declare function normalizeCategories(rooms: Room[], stored: unknown): string[];
-declare function readRooms(client: StarfishClient, spaceId: string): Promise<{
+declare function readSpaceAccess(client: StarfishClient, spaceId: string): Promise<{
     owner: string | null;
     members: string[];
-    visibility: SpaceVisibility | null;
     name: string | null;
     image: string | null;
     hash: string | null;
 }>;
-declare function writeRooms(client: StarfishClient, spaceId: string, owner: string, members: string[], hash: string | null, meta?: SpaceMeta): Promise<void>;
+declare function writeSpaceAccess(client: StarfishClient, spaceId: string, owner: string, members: string[], hash: string | null, meta?: SpaceMeta): Promise<void>;
 declare function addSpaceMember(client: StarfishClient, spaceId: string, ownerUserId: string, memberUserId: string): Promise<void>;
 /** Remove a member from the space roster (used for link revocation). */
 declare function removeSpaceMember(client: StarfishClient, spaceId: string, memberUserId: string): Promise<void>;
@@ -770,16 +695,10 @@ declare function addJoinedSpace(client: StarfishClient, userId: string, space: S
 declare function addJoinedSpaceWithCap(client: StarfishClient, userId: string, space: Space, capJson: string): Promise<void>;
 declare function addJoinedSpaceWithLinkAccess(client: StarfishClient, userId: string, space: Space, sealed: SealedBlob): Promise<void>;
 /**
- * Create a new space owned by the identity. Seeds ONE generic `general` object node
- * into the object index (encrypted for private, plaintext for public).
- *
- * `opts.visibility` defaults to `'private'`.
+ * Create a new space owned by the identity. Seeds an empty plaintext object index.
+ * Apps populate the index with their own object types after creation using `createNode`.
  */
-declare function createSpace(session: Session, name: string, opts?: {
-    visibility?: SpaceVisibility;
-}): Promise<Space>;
-declare class CategoryError extends Error {
-}
+declare function createSpace(session: Session, name: string): Promise<Space>;
 declare function reconcileSpaceMeta(client: StarfishClient, userId: string, spaceId: string, shared: SpaceMeta, knownSpaces?: Space[]): Promise<void>;
 
 interface JoinRequest {
@@ -789,22 +708,15 @@ interface JoinRequest {
 }
 declare function makeJoinRequest(session: Session): string;
 /**
- * Owner-side: add a recipient's KEM key to a SPACE keyring (one keyring → every
- * object in the space). Reused by {@link inviteToSpace} and by device pairing.
- */
-declare function addDeviceToSpaceKeyring(session: Session, spaceId: string, recipient: {
-    kemPub: string;
-    userId: string;
-}): Promise<void>;
-/**
- * Owner: invite an identity into a PRIVATE space. Adds them to the keyring, records
- * them in the roster, and mints a single space-scoped member cap.
+ * Owner: invite an identity into a space. Records them in the roster, mints a
+ * space-scoped member cap, and adds them to the space-wide keyring if it exists
+ * (so they can decrypt `enc` nodes from the start).
  * Returns the invite bundle JSON.
  */
 declare function inviteToSpace(session: Session, spaceId: string, requestJson: string, canWrite?: boolean, spaceName?: string): Promise<string>;
 /**
- * Invitee: accept a PRIVATE space invite — verify keyring access, store the cap,
- * and register the space. Returns the joined space.
+ * Invitee: accept a space invite — store the cap and register the space.
+ * Returns the joined space.
  */
 declare function acceptSpaceInvite(session: Session, inviteJson: string): Promise<Space>;
 /** A space invite link token (v:1, no ownerId — derive from cap.iss instead). */
@@ -831,10 +743,23 @@ declare function createSpaceInviteLink(session: Session, spaceId: string, spaceN
     link: string;
 }>;
 /**
- * Any user: join a PUBLIC space by redeeming an invite link token.
+ * Any user: join a space by redeeming an invite link token.
  * Stores the link credential locally and seals it into the synced `_spaces` doc.
  */
 declare function joinSpaceByLink(session: Session, token: SpaceInviteLinkToken): Promise<Space>;
+/**
+ * Add a device's KEM key as a recipient of a space's keyring.
+ *
+ * Call this after device pairing (for each space the new device should be able to
+ * decrypt). ONE space keyring encrypts ALL the space's `enc` nodes — adding the device
+ * once unlocks the whole space's E2EE content. Silently a no-op if the keyring doesn't
+ * exist yet.
+ */
+declare function addDeviceToSpaceKeyring(session: Session, spaceId: string, device: {
+    kemPub: string;
+    edPub: string;
+    userId: string;
+}): Promise<void>;
 /**
  * Single sign-in hydration: merges server-side caps (plaintext member caps from
  * `_spaces.caps`) and sealed link access (from `_spaces.pubAccess`) into the
@@ -846,60 +771,214 @@ declare function recoverSpaceAccess(session: Session, server: {
     pubAccess: Record<string, SealedBlob>;
 }): Promise<void>;
 
+interface CreateNodeInput {
+    type: ObjectType;
+    title: string;
+    emoji?: string;
+    parentId?: string | null;
+    /** Who may reach this node. Default: `'space'`. */
+    access?: NodeAccess;
+    /** Whether node content is E2EE under the space-wide keyring. Default: `false`. */
+    enc?: boolean;
+    /** App-specific metadata. */
+    meta?: Record<string, unknown>;
+}
 /**
- * Pull + (private: decrypt) + project a space's object index into the legacy
- * `{ rooms, categories }` shape. `encryptor` is null for a PUBLIC space.
- * Returns null on failure or an empty index.
+ * Create a new node in a space's object index.
+ *
+ * - Rejects the invalid combo `public+enc`.
+ * - For `enc` nodes, ensures the space-wide keyring exists (minted once per space,
+ *   idempotent on subsequent creates).
+ * - Returns the created node as it was inserted into the index.
  */
-declare function readIndexRooms(client: StarfishClient, encryptor: Encryptor | null, indexPath: string, spaceId: string): Promise<{
-    rooms: Room[];
-    categories: string[];
-} | null>;
+declare function createNode(session: Session, spaceId: string, input: CreateNodeInput, reg?: {
+    owner: string | null;
+    members: string[];
+} | null): Promise<ObjectNode>;
 /**
- * Read a space's index rooms + categories, resolving access automatically.
- * Pass `reg` (from `readRooms`) so the accessor picks the right auth mode.
+ * Patch the `access`/`enc` axes of a node in the index.
+ *
+ * - Rejects `public+enc`.
+ * - For enabling `enc`, ensures the space keyring exists (idempotent).
+ * - Content migration (moving between `objpub`/`objdoc`/`objinv`) is the caller's
+ *   responsibility — this only flips the metadata flags.
  */
-declare function readSpaceIndexRooms(session: Session, spaceId: string, reg: {
+declare function setNodeAccess(session: Session, spaceId: string, nodeId: string, patch: {
+    access?: NodeAccess;
+    enc?: boolean;
+}, reg?: {
     owner: string | null;
     members: string[];
-    visibility?: SpaceVisibility;
-}): Promise<{
-    rooms: Room[];
-    categories: string[];
-} | null>;
-/** SOFT read — never throws, never mints. Returns an empty array on any failure. */
-declare function readSpaceRooms(session: Session, spaceId: string, hint?: {
-    visibility?: SpaceVisibility;
-}): Promise<Room[]>;
+} | null): Promise<void>;
+interface NodeInviteBundle {
+    spaceId: string;
+    nodeId: string;
+    nodeName: string;
+    /** Space-level member cap (always present — grants index read access). */
+    cap: unknown;
+    /** Per-node narrow cap (only for `invite+plaintext` nodes). */
+    nodeCap?: unknown;
+}
 /**
- * Write the create-time seed into a space's index doc with an already-open access handle.
- * Accepts a nullable encryptor — plaintext push when null (public spaces).
- * Idempotent: a no-op if the index doc already exists (either encrypted or plaintext).
+ * Owner: invite an identity to a specific node.
+ *
+ * - For `enc` nodes: adds the invitee to the space-wide keyring (granting decryption
+ *   access to ALL enc nodes in the space) and mints a space-level member cap.
+ * - For `invite+plaintext` nodes: mints both a space-level cap (index) and a
+ *   narrow per-node cap (`nodeMemberScope`, covers `objinv` content).
+ *
+ * Returns the invite bundle JSON; pass to the invitee who calls `acceptNodeInvite`.
  */
-declare function pushIndexSeed(client: StarfishClient, encryptor: Encryptor | null, spaceId: string, rooms: SeedRoom[]): Promise<void>;
+declare function inviteToNode(session: Session, spaceId: string, nodeId: string, requestJson: string, node: {
+    enc?: boolean;
+}, nodeName?: string): Promise<string>;
 /**
- * Seed a brand-new space's index as the OWNER.
- * For private spaces: opens (minting if needed) the space keyring.
- * For public spaces: pushes plaintext nodes.
+ * Invitee: accept a direct node invite — store the cap(s) and register access.
+ * Returns the nodeId.
  */
-declare function seedSpaceObjectIndex(session: Session, spaceId: string, rooms: SeedRoom[], opts?: {
-    visibility?: SpaceVisibility;
-}): Promise<void>;
+declare function acceptNodeInvite(session: Session, bundleJson: string): Promise<string>;
+/** A node invite link token (v:1). */
+interface NodeInviteLinkToken {
+    v: 1;
+    spaceId: string;
+    nodeId: string;
+    nodeName: string;
+    /** Cap scope depends on `enc`: spaceMemberScope for enc nodes, nodeMemberScope for plaintext. */
+    cap: unknown;
+    /** The ephemeral subject's Ed25519 private key (hex). */
+    key: string;
+    write: boolean;
+}
+declare function encodeNodeInviteLink(origin: string, token: NodeInviteLinkToken): string;
+declare function decodeNodeInviteLink(fragment: string): NodeInviteLinkToken;
 /**
- * Headless read-modify-write of a space's unified OBJECT INDEX. Works for both
- * private (encrypt round-trip) and public (plaintext) spaces. Retries up to 3 times
- * on ConflictError.
+ * Owner: create a shareable invite link for a specific node.
+ *
+ * - For `enc` nodes: adds ephemeral KEM to the space-wide keyring; the link cap uses
+ *   `spaceMemberScope` so the bearer can read the keyring and decrypt enc content.
+ * - For `invite+plaintext` nodes: narrow per-node cap (`nodeMemberScope`), no keyring.
+ *
+ * Anyone with the link can access the node; revoke by calling
+ * `removeSpaceMember(ephemeralUserId)` (and rotating the space keyring for enc nodes).
+ */
+declare function createNodeInviteLink(session: Session, spaceId: string, nodeId: string, nodeName: string, node: {
+    enc?: boolean;
+}, write: boolean, origin: string): Promise<{
+    token: NodeInviteLinkToken;
+    link: string;
+}>;
+/**
+ * Any user: access a node by redeeming an invite link token.
+ * Stores the per-node link entry locally and seals it into the synced `_spaces` doc.
+ */
+declare function joinNodeByLink(session: Session, token: NodeInviteLinkToken): Promise<string>;
+
+/**
+ * Generic object-tree model — pure logic over a space's object index.
+ *
+ * A space's contents are {@link ObjectNode}s in one union-merged index doc at
+ * `spaces/{spaceId}/objects/_index`. This module is the pure, testable core:
+ * the tree builder + merge-artifact guards, breadcrumbs, ordering, and the node
+ * reducers a `store.set` applies.
+ *
+ * Because the index is union-merged (per-node last-write-wins keyed on `updatedAt`),
+ * the tree is eventually consistent — two devices can concurrently produce a cycle
+ * or an orphan. The builder below is the single place those are repaired so every
+ * consumer renders a well-formed tree.
+ *
+ * No domain types (room, category, task, …) are defined here. Apps define their own.
+ */
+
+/** A node plus its resolved children — the shape a tree view renders. */
+interface ObjectTreeNode extends ObjectNode {
+    depth: number;
+    children: ObjectTreeNode[];
+}
+/** The order value for a new node appended after `siblings`. */
+declare function nextOrder(siblings: ObjectNode[]): number;
+/**
+ * Build the render tree from a flat node list, repairing merge artifacts:
+ *  - **archived** nodes (and their subtrees) are dropped.
+ *  - **orphans** — a `parentId` that is missing or archived — reparent to root.
+ *  - **cycles** — a node reachable from itself via `parentId` — reparent to root.
+ *  - **siblings** sort by {@link compareSiblings} for cross-device determinism.
+ */
+declare function buildTree(nodes: ObjectNode[], includeArchived?: boolean): ObjectTreeNode[];
+/** The root→node trail (inclusive) for breadcrumbs. Returns `[]` if unknown. */
+declare function breadcrumbs(nodes: ObjectNode[], id: ID): ObjectNode[];
+/** The root→parent trail (EXCLUSIVE of the node itself). */
+declare function ancestors(nodes: ObjectNode[], id: ID): ObjectNode[];
+/** The ids of a node and its whole subtree (for cascade-archive). */
+declare function subtreeIds(nodes: ObjectNode[], rootId: ID): Set<ID>;
+interface NewObjectInput {
+    type: ObjectType;
+    parentId?: ID | null;
+    title: string;
+    emoji?: string;
+    /** App-specific metadata passed through to node.meta. */
+    meta?: Record<string, unknown>;
+    /** Provide to reuse an id (e.g. a node id derived elsewhere); else minted. */
+    id?: ID;
+    /** Who may reach this node. Absent ⇒ `'space'` (all space members). */
+    access?: NodeAccess;
+    /** Whether the node's content is E2EE under its own per-node keyring. Absent ⇒ false. */
+    enc?: boolean;
+}
+/** Append a new node under `parentId` at the end of its sibling order. */
+declare function addObject(nodes: ObjectNode[], input: NewObjectInput, now: number): {
+    nodes: ObjectNode[];
+    node: ObjectNode;
+};
+/** Patch a node's mutable metadata (title/emoji/meta/access/enc), bumping `updatedAt`. */
+declare function patchObject(nodes: ObjectNode[], id: ID, patch: Partial<Pick<ObjectNode, 'title' | 'emoji' | 'meta' | 'access' | 'enc'>>, now: number): ObjectNode[];
+/** Reparent a node (move in the tree). Rejects making a node its own descendant. */
+declare function reparentObject(nodes: ObjectNode[], id: ID, parentId: ID | null, now: number): ObjectNode[];
+/** Set explicit sibling order (drag-reorder). */
+declare function reorderObjects(nodes: ObjectNode[], orderById: Record<ID, number>, now: number): ObjectNode[];
+/** Cascade-archive a node and its whole subtree (soft delete). */
+declare function archiveObject(nodes: ObjectNode[], id: ID, now: number): ObjectNode[];
+
+/**
+ * Write the create-time seed into a space's index doc.
+ * Idempotent: a no-op if the index doc already exists.
+ * Pass `nodes` to seed with initial objects; defaults to an empty index.
+ */
+declare function pushIndexSeed(client: _drakkar_software_starfish_client.StarfishClient, spaceId: string, nodes?: ObjectNode[]): Promise<void>;
+/**
+ * Seed a brand-new space's index as the OWNER. Always plaintext.
+ * Pass `nodes` to seed with initial objects; defaults to an empty index.
+ */
+declare function seedSpaceObjectIndex(session: Session, spaceId: string, nodes?: ObjectNode[]): Promise<void>;
+/**
+ * Headless read-modify-write of a space's unified OBJECT INDEX.
+ * Always plaintext. Retries up to 3 times on ConflictError.
+ *
+ * The mutator receives the current nodes with real (or empty, for invite) titles.
+ * Before writing back, invite nodes have their title/emoji stripped again.
  */
 declare function updateObjectIndex(session: Session, spaceId: string, mutator: (nodes: ObjectNode[], now: number) => ObjectNode[] | null, reg?: {
     owner: string | null;
     members: string[];
-    visibility?: SpaceVisibility;
 } | null): Promise<void>;
+/**
+ * Read the current object tree (read-only, no mutation). Returns the stored
+ * nodes (titles are empty for invite nodes the caller is not invited to).
+ */
+declare function readObjectTree(session: Session, spaceId: string): Promise<ObjectNode[]>;
 
 /** The QR-payload prefix this SDK uses. Kept distinct from `octochat-pair:` so apps
  *  can route QR payloads to the correct handler during their migration window. */
 declare const PAIR_PREFIX = "octospaces-pair:";
-/** Existing device: provision + PIN-seal a new device, publish to rendezvous, return the QR payload. */
+/**
+ * Existing device: provision + PIN-seal a new device, publish to rendezvous, return
+ * the QR payload.
+ *
+ * After pairing, call `addDeviceToSpaceKeyring(session, spaceId, newDeviceKeys)` for
+ * each space whose E2EE content the new device should decrypt. ONE space keyring
+ * encrypts ALL `enc` nodes in a space — one call per space unlocks everything.
+ * Plaintext (`space` / `public`) nodes are immediately accessible via the linked-device
+ * cap-cert (no extra keyring step).
+ */
 declare function startDevicePairing(session: Session, pin: string): Promise<string>;
 interface PairResult {
     userId: string;
@@ -969,4 +1048,132 @@ declare const starfishBase64: Base64Provider;
 declare function toBase64Url(json: string): string;
 declare function fromBase64Url(b64url: string): string;
 
-export { type AdaptedCategory, type ArchivedDms, type AutomationMeta, BUILTIN_OBJECT_TYPES, CONNECT_TIMEOUT_MS, type CapMap, CategoryError, DEFAULT_CATEGORY, type DerivedIdentity, type DeviceKeys, type DmMap, type ID, type JoinRequest, type KvAdapter, type LinkedIdentity, type MutePrefs, type NewObjectInput, OBJECT_COLLECTIONS, type ObjectContentKind, type ObjectNode, type ObjectTreeNode, type ObjectType, type ObjectsIndex, type OctoSpacesConfig, PAIR_PREFIX, PULL_CACHE_MAX_AGE_MS, type PairResult, type PasskeyEnrollment, type PersistedSession, type PubAccessMap, type PublicProfile, type ReadPrefs, type Room, type RoomKind, type RoomSubtype, type SealedBlob, type SeedLock, type SeedRoom, type Session, type Space, type SpaceAccessEntry, SpaceAccessError, type SpaceAccessHandle, type SpaceAccessMap, type SpaceInviteLinkToken, type SpaceMeta, type SpaceMetaUpdate, type SpaceVisibility, type UnlockMethod, type Vault, type VaultLoad, acceptSpaceInvite, accountScope, addDeviceToSpaceKeyring, addJoinedSpace, addJoinedSpaceWithCap, addJoinedSpaceWithLinkAccess, addObject, addSpaceMember, ancestors, archiveObject, attachmentPull, attachmentPush, breadcrumbs, broadcastSpaceMeta, buildAuthHeaders, buildEncryptor, buildLinkedSession, buildSession, buildSpaceAccess, buildTree, bytesToHex, cacheProfile, capProviderFor, categoryId, clearSpaceAccessCache, clearSpaceAccessStore, completeDevicePairing, configureKv, configureOctoSpaces, createSpace, createSpaceInviteLink, decodeSpaceInviteLink, deriveSession, encodeSpaceInviteLink, ensureProfileKeys, ensurePseudo, excludeAutomatedRooms, fetchWithTimeout, fingerprintFromUserId, fromBase64Url, generateSeedWords, getSharedSpacesNamespace, getSpaceAccess, getSpaceAccessEntry, getSyncBase, getSyncNamespace, getSyncPrefix, hydrateSpaceAccessStore, inviteToSpace, isValidSeed, joinSpaceByLink, keyringName, keyringPull, keyringPush, kvGet, kvRemove, kvSet, linkAccessFromStore, linkedDeviceScope, loadCachedProfile, localSpaceAccessEntries, makeClient, makeJoinRequest, memberCapsFromStore, nextOrder, normalizeCategories, objDocPull, objDocPush, objIndexPull, objIndexPush, objLogPull, objLogPush, objectBlobPull, objectBlobPush, objectsToRoomCategories, onSpaceMeta, openEncryptor, ownerEnsureKeyring, ownerScope, ownerTrustedAdders, patchObject, profilePull, profilePush, pullCache, pushIndexSeed, randomId, readIndexRooms, readProfile, readProfiles, readPseudo, readRooms, readSpaceIndexRooms, readSpaceRooms, readSpaces, reconcileSpaceMeta, recoverSpaceAccess, removeSpaceAccessEntry, removeSpaceMember, reorderObjects, reorderSpaces, reparentObject, roomKindToSubtype, roomSlug, roomsRegistryPull, roomsRegistryPush, rootIdentityOf, saveSpaceAccessEntry, sealToRecipient, sealToSelf, seedIndexNodes, seedSpaceObjectIndex, setDmMapping, spaceIndexPull, spaceMemberScope, spacesPull, spacesPush, starfishBase64, startDevicePairing, subtreeIds, subtypeToRoomKind, toBase64Url, typesIndexPull, typesIndexPush, unsealFromRecipient, unsealFromSelf, updateArchivedDmsDoc, updateDmsDoc, updateMutesDoc, updateObjectIndex, updateQuickReactionsDoc, updateReadsDoc, updateSpacesDoc, userIdFromEdPub, writeProfile, writePseudo, writeRooms, writeSpaces };
+/**
+ * Pure title matcher + ranker for Quick Find / Search. No React, no I/O.
+ *
+ * Relevance is tiered the way a human reads a match, strongest first:
+ *
+ *   1. PREFIX        — the title starts with the query ("not" → "Notes").
+ *   2. WORD boundary — some word starts with the query ("pa" → "New page").
+ *   3. SUBSTRING     — the query appears mid-word ("page" → "Homepage").
+ *   4. FUZZY         — the query is a subsequence ("rdm" → "Roadmap").
+ *
+ * Within a tier, earlier and tighter matches in shorter titles score higher;
+ * tier gaps are wider than any intra-tier penalty, so a fuzzy hit can never
+ * outrank a real substring. Ties (same score) fall back to `updatedAt` DESC in
+ * {@link rankResults} — between two objects named "Notes", the one touched last
+ * is almost always the one wanted.
+ *
+ * Matching is case- and diacritic-insensitive via a per-UTF-16-unit fold that
+ * PRESERVES STRING LENGTH, so the returned ranges index straight into the
+ * ORIGINAL title for highlight rendering.
+ */
+/** Half-open [start, end) span into the original title. */
+interface MatchRange {
+    start: number;
+    end: number;
+}
+interface TitleMatch {
+    score: number;
+    ranges: MatchRange[];
+}
+/**
+ * Lowercase + strip diacritics WITHOUT changing length: each UTF-16 unit maps
+ * to exactly one folded unit (NFD base char, first lowercase unit). Surrogate
+ * halves pass through unchanged — they can't match an ASCII query, which is
+ * exactly right for emoji-bearing titles.
+ */
+declare function fold(s: string): string;
+/** A word starts where the previous folded char is not alphanumeric. */
+declare function isWordStart(folded: string, i: number): boolean;
+/**
+ * Match one title against a query. Returns `null` for an empty query or a miss.
+ * Ranges cover every highlighted span (one for contiguous tiers, several merged
+ * runs for fuzzy).
+ */
+declare function matchTitle(query: string, title: string): TitleMatch | null;
+interface RankedResult<T> {
+    item: T;
+    score: number;
+    ranges: MatchRange[];
+}
+/**
+ * Rank a candidate list against a query: score every title, drop misses, sort
+ * by score DESC then `updatedAt` DESC (recency breaks ties), cap at `limit`.
+ */
+declare function rankResults<T extends {
+    title: string;
+    updatedAt: number;
+}>(query: string, items: readonly T[], limit?: number): RankedResult<T>[];
+
+/**
+ * Single dispatch point for live-sync events from a global SSE connection.
+ *
+ * When a server-sent event arrives, the unread/notification layer calls
+ * `dispatchDocChange(docPath)`:
+ *   - if a hook has registered a pull for that path → call it (the user is
+ *     actively viewing that doc) and return `true` — the caller skips the
+ *     unread bump.
+ *   - otherwise return `false` → the caller bumps unread.
+ *
+ * Hooks register/unregister via `registerPull`. SSE connection health is
+ * broadcast via `emitSseStatus` so hooks can gate their fallback polling.
+ *
+ * Call `clearLiveSyncBus()` on account switch to flush all registrations.
+ */
+type PullFn = () => void;
+type StatusListener = (up: boolean) => void;
+/**
+ * Register a pull function keyed by `docPath`. Returns an unsubscribe
+ * function — call it when the hook unmounts.
+ */
+declare function registerPull(docPath: string, fn: PullFn): () => void;
+/**
+ * Dispatch a doc-change event. If a pull is registered for `docPath`, calls
+ * it and returns `true`. Returns `false` if no listener is registered
+ * (the caller should bump unread).
+ */
+declare function dispatchDocChange(docPath: string): boolean;
+/** Broadcast the current SSE health to all subscribers. */
+declare function emitSseStatus(up: boolean): void;
+/**
+ * Subscribe to SSE health changes. Fires immediately with the current state.
+ * Returns an unsubscribe function.
+ */
+declare function onSseStatus(cb: StatusListener): () => void;
+/**
+ * Flush all registered doc pulls and reset SSE health. Call on account
+ * switch. `statusListeners` are React subscriptions that self-unsubscribe on
+ * unmount and are intentionally left intact.
+ */
+declare function clearLiveSyncBus(): void;
+
+type InvitePreview = {
+    kind: 'space-link';
+    spaceName: string;
+    /** True if the link grants write access, false for read-only. */
+    write: boolean;
+    token: SpaceInviteLinkToken;
+} | {
+    kind: 'node-link';
+    spaceName: string;
+    /** The node's display name, absent for legacy tokens that omit it. */
+    nodeTitle?: string;
+    token: NodeInviteLinkToken;
+} | {
+    kind: 'member-bundle';
+    spaceName: string;
+    spaceId: string;
+    /** Short hex fingerprint of the issuing owner's signing key, or null if absent. */
+    issuerKey: string | null;
+    /** The raw cap-bundle JSON — pass verbatim to `acceptSpaceInvite` on consent. */
+    inviteJson: string;
+};
+/**
+ * Classify and decode an invite string into a typed {@link InvitePreview}.
+ * Throws a human-readable `Error` on invalid input (safe to surface verbatim
+ * in a toast or inline error message).
+ */
+declare function previewInvite(raw: string): InvitePreview;
+
+export { type ArchivedDms, CONNECT_TIMEOUT_MS, type CapMap, type CreateNodeInput, type DerivedIdentity, type DeviceKeys, type DmMap, type ID, type InvitePreview, type JoinRequest, type KvAdapter, type LinkedIdentity, type MatchRange, type MutePrefs, type MuteValue, type NewObjectInput, type NodeAccess, type NodeAccessHandle, type NodeInviteBundle, type NodeInviteLinkToken, OBJECT_COLLECTIONS, type ObjectContentKind, type ObjectNode, type ObjectTreeNode, type ObjectType, type ObjectsIndex, type OctoSpacesConfig, PAIR_PREFIX, PULL_CACHE_MAX_AGE_MS, type PairResult, type PasskeyEnrollment, type PersistedSession, type PresenceStatus, type PubAccessMap, type PublicProfile, type RankedResult, type ReadPrefs, type ReadValue, type SealedBlob, type SeedLock, type Session, type Space, type SpaceAccessEntry, SpaceAccessError, type SpaceAccessMap, type SpaceInviteLinkToken, type SpaceMeta, type SpaceMetaUpdate, type TitleMatch, type UnlockMethod, type Vault, type VaultLoad, type VerificationLevel, acceptNodeInvite, acceptSpaceInvite, accountScope, addDeviceToSpaceKeyring, addJoinedSpace, addJoinedSpaceWithCap, addJoinedSpaceWithLinkAccess, addObject, addSpaceMember, ancestors, archiveObject, attachmentName, attachmentPull, attachmentPush, breadcrumbs, broadcastSpaceMeta, buildAuthHeaders, buildEncryptor, buildLinkedSession, buildNodeAccess, buildSession, buildTree, bytesToHex, cacheProfile, capProviderFor, clearLiveSyncBus, clearNodeAccessCache, clearSpaceAccessStore, completeDevicePairing, configureKv, configureOctoSpaces, createNode, createNodeInviteLink, createSpace, createSpaceInviteLink, decodeNodeInviteLink, decodeSpaceInviteLink, deriveSession, dispatchDocChange, emitSseStatus, encodeNodeInviteLink, encodeSpaceInviteLink, ensureProfileKeys, ensurePseudo, fetchWithTimeout, fingerprintFromUserId, fold, fromBase64Url, generateSeedWords, getNodeAccess, getNodeAccessEntry, getSharedSpacesNamespace, getSpaceAccessEntry, getSpaceClient, getSyncBase, getSyncNamespace, getSyncPrefix, hydrateSpaceAccessStore, inviteToNode, inviteToSpace, isValidSeed, isWordStart, joinNodeByLink, joinSpaceByLink, keyringName, keyringPull, keyringPush, kvGet, kvRemove, kvSet, linkAccessFromStore, linkedDeviceScope, loadCachedProfile, localSpaceAccessEntries, makeClient, makeJoinRequest, matchTitle, memberCapsFromStore, nextOrder, nodeMemberScope, objDocName, objDocPull, objDocPush, objIndexName, objIndexPull, objIndexPush, objInvName, objInvPull, objInvPush, objLogName, objLogPull, objLogPush, objPubName, objPubPull, objPubPush, objectBlobName, objectBlobPull, objectBlobPush, objectDirName, objectDirPull, onSpaceMeta, onSseStatus, openEncryptor, ownerEnsureKeyring, ownerScope, ownerTrustedAdders, patchObject, previewInvite, profilePull, profilePush, pullCache, pushIndexSeed, randomId, rankResults, readObjectTree, readProfile, readProfiles, readPseudo, readSpaceAccess, readSpaces, reconcileSpaceMeta, recoverSpaceAccess, registerPull, removeNodeAccessEntry, removeSpaceAccessEntry, removeSpaceMember, reorderObjects, reorderSpaces, reparentObject, roomSlug, rootIdentityOf, saveNodeAccessEntry, saveSpaceAccessEntry, sealToRecipient, sealToSelf, seedSpaceObjectIndex, setDmMapping, setNodeAccess, spaceAccessPull, spaceAccessPush, spaceIdFromRoomId, spaceMemberScope, spacesPull, spacesPush, starfishBase64, startDevicePairing, subtreeIds, toBase64Url, typesIndexName, typesIndexPull, typesIndexPush, unsealFromRecipient, unsealFromSelf, updateArchivedDmsDoc, updateDmsDoc, updateMutesDoc, updateObjectIndex, updateQuickReactionsDoc, updateReadsDoc, updateSpacesDoc, userIdFromEdPub, writeProfile, writePseudo, writeSpaceAccess, writeSpaces };