@drakkar.software/octospaces-sdk 0.4.1 → 0.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakkar.software/octospaces-sdk",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Shared headless spaces core — identity, registry, objects, and sync plumbing.",
   "type": "module",
   "sideEffects": false,

package/src/core/types.ts

@@ -21,8 +21,9 @@ export type ID = string;
 /** A user's presence indicator. The theme maps each to a color (app-side). */
 export type PresenceStatus = 'online' | 'away' | 'dnd' | 'offline';
 
-/** A security item's verification state. The theme maps each to a color (app-side). */
-export type VerificationLevel = 'verified' | 'pending' | 'unverified';
+/** 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. */
+export 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

package/src/index.ts

@@ -20,9 +20,13 @@ export type {
   CapMap,
   PubAccessMap,
   DmMap,
+  MuteValue,
   MutePrefs,
+  ReadValue,
   ReadPrefs,
   ArchivedDms,
+  PresenceStatus,
+  VerificationLevel,
 } from './core/types.js';
 
 // Ids
@@ -39,6 +43,7 @@ export {
   keyringName,
   keyringPull,
   keyringPush,
+  objIndexName,
   objIndexPull,
   objIndexPush,
   objPubName,
@@ -55,16 +60,22 @@ export {
   spaceAccessPush,
   profilePull,
   profilePush,
+  objLogName,
   objLogPull,
   objLogPush,
+  objDocName,
   objDocPull,
   objDocPush,
+  objectBlobName,
   objectBlobPull,
   objectBlobPush,
+  typesIndexName,
   typesIndexPull,
   typesIndexPush,
+  attachmentName,
   attachmentPull,
   attachmentPush,
+  spaceIdFromRoomId,
   userIdFromEdPub,
   bytesToHex,
 } from './sync/paths.js';
@@ -233,3 +244,12 @@ export { fetchWithTimeout, CONNECT_TIMEOUT_MS } from './sync/fetch-timeout.js';
 // Base64
 export { starfishBase64 } from './sync/base64.js';
 export { toBase64Url, fromBase64Url } from './sync/base64url.js';
+
+// Utilities
+export { matchTitle, rankResults, fold, isWordStart } from './utils/search-match.js';
+export type { MatchRange, TitleMatch, RankedResult } from './utils/search-match.js';
+
+export { registerPull, dispatchDocChange, emitSseStatus, onSseStatus, clearLiveSyncBus } from './utils/live-sync-bus.js';
+
+export { previewInvite } from './utils/invite-preview.js';
+export type { InvitePreview } from './utils/invite-preview.js';

package/src/utils/invite-preview.test.ts

@@ -0,0 +1,169 @@
+import { describe, it, expect } from 'vitest';
+import { previewInvite } from './invite-preview.js';
+import { encodeSpaceInviteLink } from '../spaces/members.js';
+import { encodeNodeInviteLink } from '../spaces/nodes.js';
+import type { SpaceInviteLinkToken } from '../spaces/members.js';
+import type { NodeInviteLinkToken } from '../spaces/nodes.js';
+
+const spaceToken: SpaceInviteLinkToken = {
+  v: 1,
+  spaceId: 'sp-abc123',
+  spaceName: 'My Space',
+  cap: { kind: 'member', iss: 'deadbeef', sub: 'cafecafe', scope: {} },
+  key: 'a1b2c3d4',
+  write: true,
+};
+
+const nodeToken: NodeInviteLinkToken = {
+  v: 1,
+  spaceId: 'sp-abc123',
+  nodeId: 'nd-xyz789',
+  nodeName: 'Secret Doc',
+  cap: { kind: 'member', iss: 'deadbeef', sub: 'cafecafe', scope: {} },
+  key: 'b2c3d4e5',
+  write: false,
+};
+
+const spaceLink = encodeSpaceInviteLink('https://app.example.com', spaceToken);
+const nodeLink = encodeNodeInviteLink('https://app.example.com', nodeToken);
+
+// ── space-link ────────────────────────────────────────────────────────────────
+
+describe('previewInvite — space-link', () => {
+  it('classifies a space invite link', () => {
+    const p = previewInvite(spaceLink);
+    expect(p.kind).toBe('space-link');
+  });
+
+  it('extracts spaceName and write flag', () => {
+    const p = previewInvite(spaceLink);
+    if (p.kind !== 'space-link') throw new Error('wrong kind');
+    expect(p.spaceName).toBe('My Space');
+    expect(p.write).toBe(true);
+  });
+
+  it('exposes the decoded token', () => {
+    const p = previewInvite(spaceLink);
+    if (p.kind !== 'space-link') throw new Error('wrong kind');
+    expect(p.token.spaceId).toBe('sp-abc123');
+  });
+
+  it('accepts a raw fragment (no origin prefix)', () => {
+    const fragment = spaceLink.slice(spaceLink.indexOf('#'));
+    const p = previewInvite(fragment);
+    expect(p.kind).toBe('space-link');
+  });
+
+  it('accepts a read-only (write:false) link', () => {
+    const readOnlyToken: SpaceInviteLinkToken = { ...spaceToken, write: false };
+    const link = encodeSpaceInviteLink('https://app.example.com', readOnlyToken);
+    const p = previewInvite(link);
+    if (p.kind !== 'space-link') throw new Error('wrong kind');
+    expect(p.write).toBe(false);
+  });
+});
+
+// ── node-link ─────────────────────────────────────────────────────────────────
+
+describe('previewInvite — node-link', () => {
+  it('classifies a node invite link', () => {
+    const p = previewInvite(nodeLink);
+    expect(p.kind).toBe('node-link');
+  });
+
+  it('extracts nodeTitle from nodeName', () => {
+    const p = previewInvite(nodeLink);
+    if (p.kind !== 'node-link') throw new Error('wrong kind');
+    expect(p.nodeTitle).toBe('Secret Doc');
+  });
+
+  it('exposes spaceId via spaceName fallback', () => {
+    const p = previewInvite(nodeLink);
+    if (p.kind !== 'node-link') throw new Error('wrong kind');
+    expect(p.spaceName).toContain('abc123'.slice(-6));
+  });
+
+  it('exposes the decoded token', () => {
+    const p = previewInvite(nodeLink);
+    if (p.kind !== 'node-link') throw new Error('wrong kind');
+    expect(p.token.nodeId).toBe('nd-xyz789');
+  });
+});
+
+// ── member-bundle ─────────────────────────────────────────────────────────────
+
+const bundle = JSON.stringify({
+  spaceId: 'sp-abc123',
+  spaceName: 'Team Space',
+  cap: { kind: 'member', iss: 'aabbccddee112233' },
+});
+
+describe('previewInvite — member-bundle', () => {
+  it('classifies a private member-bundle JSON', () => {
+    const p = previewInvite(bundle);
+    expect(p.kind).toBe('member-bundle');
+  });
+
+  it('extracts spaceName and spaceId', () => {
+    const p = previewInvite(bundle);
+    if (p.kind !== 'member-bundle') throw new Error('wrong kind');
+    expect(p.spaceName).toBe('Team Space');
+    expect(p.spaceId).toBe('sp-abc123');
+  });
+
+  it('builds issuerKey fingerprint from iss', () => {
+    const p = previewInvite(bundle);
+    if (p.kind !== 'member-bundle') throw new Error('wrong kind');
+    expect(p.issuerKey).toContain('aabbccdd');
+    expect(p.issuerKey).toContain('…');
+  });
+
+  it('issuerKey is null when iss is absent', () => {
+    const noIss = JSON.stringify({ spaceId: 'sp-abc123', cap: { kind: 'member' } });
+    const p = previewInvite(noIss);
+    if (p.kind !== 'member-bundle') throw new Error('wrong kind');
+    expect(p.issuerKey).toBeNull();
+  });
+
+  it('falls back to id-derived spaceName when spaceName is absent', () => {
+    const noName = JSON.stringify({ spaceId: 'sp-abc123', cap: { kind: 'member' } });
+    const p = previewInvite(noName);
+    if (p.kind !== 'member-bundle') throw new Error('wrong kind');
+    expect(p.spaceName).toBe('space-abc123');
+  });
+
+  it('preserves raw inviteJson verbatim', () => {
+    const p = previewInvite(bundle);
+    if (p.kind !== 'member-bundle') throw new Error('wrong kind');
+    expect(p.inviteJson).toBe(bundle);
+  });
+});
+
+// ── error cases ───────────────────────────────────────────────────────────────
+
+describe('previewInvite — errors', () => {
+  it('throws on empty input', () => {
+    expect(() => previewInvite('')).toThrow('Paste an invite');
+  });
+
+  it('throws on a whitespace-only input', () => {
+    expect(() => previewInvite('   ')).toThrow('Paste an invite');
+  });
+
+  it('throws on a malformed URL fragment', () => {
+    expect(() => previewInvite('#not-valid-base64!!!!')).toThrow();
+  });
+
+  it('throws on plain text (not JSON, not a link)', () => {
+    expect(() => previewInvite('hello world')).toThrow("doesn't look like an invite");
+  });
+
+  it('throws on JSON that is not a member bundle', () => {
+    expect(() => previewInvite(JSON.stringify({ foo: 'bar' }))).toThrow('not a valid space invite');
+  });
+
+  it('throws on a bundle whose cap.kind is not member', () => {
+    const bad = JSON.stringify({ spaceId: 'sp-1', cap: { kind: 'owner' } });
+    expect(() => previewInvite(bad)).toThrow('not a valid space invite');
+  });
+});

package/src/utils/invite-preview.ts

@@ -0,0 +1,101 @@
+/**
+ * Parse an invite (pasted text or a `#fragment` deep link) into a preview the
+ * join screen can show on a consent card — name, type, identifying fingerprint
+ * — WITHOUT joining. Actual join calls (`joinSpaceByLink`, `joinNodeByLink`,
+ * `acceptSpaceInvite`, `acceptNodeInvite`) only run after the user confirms.
+ *
+ * Accepts three input forms:
+ *   - A space invite link (URL fragment encoded by `createSpaceInviteLink`)
+ *   - A node invite link (URL fragment encoded by `createNodeInviteLink`)
+ *   - A private member-bundle JSON minted by `inviteToSpace`
+ */
+import { decodeSpaceInviteLink } from '../spaces/members.js';
+import { decodeNodeInviteLink } from '../spaces/nodes.js';
+import type { SpaceInviteLinkToken } from '../spaces/members.js';
+import type { NodeInviteLinkToken } from '../spaces/nodes.js';
+
+export type { SpaceInviteLinkToken, NodeInviteLinkToken };
+
+export 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;
+    };
+
+/** Shape of the private invite bundle minted by `inviteToSpace`. */
+interface PrivateInviteShape {
+  spaceId?: string;
+  spaceName?: string;
+  cap?: { kind?: string; iss?: 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).
+ */
+export function previewInvite(raw: string): InvitePreview {
+  const text = raw.trim();
+  if (!text) throw new Error('Paste an invite link or code first.');
+
+  // Invite links carry their credential in a URL fragment.
+  if (text.includes('#')) {
+    const fragment = text.slice(text.indexOf('#'));
+    // Try node-invite link first — it has a `nodeId` field the space link lacks.
+    try {
+      const token = decodeNodeInviteLink(fragment);
+      return {
+        kind: 'node-link',
+        spaceName: `space-${token.spaceId.slice(-6)}`,
+        nodeTitle: token.nodeName,
+        token,
+      };
+    } catch {
+      // fall through to space link
+    }
+    try {
+      const token = decodeSpaceInviteLink(fragment);
+      return { kind: 'space-link', spaceName: token.spaceName, write: token.write, token };
+    } catch {
+      throw new Error('That invite link appears to be invalid or expired.');
+    }
+  }
+
+  // Private member-bundle JSON minted by `inviteToSpace`.
+  let parsed: PrivateInviteShape;
+  try {
+    parsed = JSON.parse(text) as PrivateInviteShape;
+  } catch {
+    throw new Error("That doesn't look like an invite. Paste the full invite code or link.");
+  }
+  if (!parsed?.spaceId || parsed.cap?.kind !== 'member') {
+    throw new Error('That is not a valid space invite.');
+  }
+  const iss = parsed.cap?.iss;
+  return {
+    kind: 'member-bundle',
+    spaceName: parsed.spaceName?.trim() || `space-${parsed.spaceId.slice(-6)}`,
+    spaceId: parsed.spaceId,
+    issuerKey: typeof iss === 'string' && iss.length >= 8 ? `${iss.slice(0, 8)}…${iss.slice(-8)}` : null,
+    inviteJson: text,
+  };
+}

package/src/utils/live-sync-bus.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+  registerPull,
+  dispatchDocChange,
+  emitSseStatus,
+  onSseStatus,
+  clearLiveSyncBus,
+} from './live-sync-bus.js';
+
+beforeEach(() => clearLiveSyncBus());
+
+// ── registerPull / dispatchDocChange ──────────────────────────────────────────
+
+describe('registerPull / dispatchDocChange', () => {
+  it('returns false when no pull is registered for the path', () => {
+    expect(dispatchDocChange('spaces/sp-1/objects/_index')).toBe(false);
+  });
+
+  it('calls the registered pull and returns true', () => {
+    const pull = vi.fn();
+    registerPull('spaces/sp-1/objects/_index', pull);
+    const dispatched = dispatchDocChange('spaces/sp-1/objects/_index');
+    expect(dispatched).toBe(true);
+    expect(pull).toHaveBeenCalledOnce();
+  });
+
+  it('does not cross-fire — different paths are independent', () => {
+    const pull1 = vi.fn();
+    const pull2 = vi.fn();
+    registerPull('spaces/sp-1/objects/_index', pull1);
+    registerPull('spaces/sp-2/objects/_index', pull2);
+    dispatchDocChange('spaces/sp-1/objects/_index');
+    expect(pull1).toHaveBeenCalledOnce();
+    expect(pull2).not.toHaveBeenCalled();
+  });
+
+  it('unsubscribe removes the registration', () => {
+    const pull = vi.fn();
+    const unsub = registerPull('spaces/sp-1/objects/_index', pull);
+    unsub();
+    expect(dispatchDocChange('spaces/sp-1/objects/_index')).toBe(false);
+    expect(pull).not.toHaveBeenCalled();
+  });
+
+  it('stale unsubscribe is a no-op after re-registration', () => {
+    const pull1 = vi.fn();
+    const pull2 = vi.fn();
+    const unsub1 = registerPull('spaces/sp-1/objects/_index', pull1);
+    registerPull('spaces/sp-1/objects/_index', pull2); // overwrites
+    unsub1(); // should NOT remove pull2
+    dispatchDocChange('spaces/sp-1/objects/_index');
+    expect(pull2).toHaveBeenCalledOnce();
+  });
+});
+
+// ── emitSseStatus / onSseStatus ───────────────────────────────────────────────
+
+describe('emitSseStatus / onSseStatus', () => {
+  it('fires immediately with the current state (false by default)', () => {
+    const cb = vi.fn();
+    onSseStatus(cb);
+    expect(cb).toHaveBeenCalledWith(false);
+  });
+
+  it('fires on each status change', () => {
+    const cb = vi.fn();
+    onSseStatus(cb);
+    emitSseStatus(true);
+    emitSseStatus(false);
+    expect(cb).toHaveBeenNthCalledWith(1, false); // initial
+    expect(cb).toHaveBeenNthCalledWith(2, true);
+    expect(cb).toHaveBeenNthCalledWith(3, false);
+  });
+
+  it('unsubscribe stops receiving updates', () => {
+    const cb = vi.fn();
+    const unsub = onSseStatus(cb);
+    unsub();
+    emitSseStatus(true);
+    expect(cb).toHaveBeenCalledOnce(); // only the initial fire
+  });
+
+  it('new subscriber gets current state after emitSseStatus(true)', () => {
+    emitSseStatus(true);
+    const cb = vi.fn();
+    onSseStatus(cb);
+    expect(cb).toHaveBeenCalledWith(true);
+  });
+});
+
+// ── clearLiveSyncBus ──────────────────────────────────────────────────────────
+
+describe('clearLiveSyncBus', () => {
+  it('clears all registered pulls', () => {
+    const pull = vi.fn();
+    registerPull('spaces/sp-1/objects/_index', pull);
+    clearLiveSyncBus();
+    expect(dispatchDocChange('spaces/sp-1/objects/_index')).toBe(false);
+  });
+
+  it('resets SSE health to false', () => {
+    emitSseStatus(true);
+    clearLiveSyncBus();
+    const cb = vi.fn();
+    onSseStatus(cb);
+    expect(cb).toHaveBeenCalledWith(false);
+  });
+
+  it('leaves status listeners intact (they self-unsub on unmount)', () => {
+    const cb = vi.fn();
+    onSseStatus(cb);
+    clearLiveSyncBus();
+    emitSseStatus(true);
+    expect(cb).toHaveBeenCalledWith(true); // still fires
+  });
+});

package/src/utils/live-sync-bus.ts

@@ -0,0 +1,71 @@
+/**
+ * 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;
+
+const pullRegistry = new Map<string, PullFn>();
+const statusListeners = new Set<StatusListener>();
+let sseUp = false;
+
+/**
+ * Register a pull function keyed by `docPath`. Returns an unsubscribe
+ * function — call it when the hook unmounts.
+ */
+export function registerPull(docPath: string, fn: PullFn): () => void {
+  pullRegistry.set(docPath, fn);
+  return () => {
+    if (pullRegistry.get(docPath) === fn) pullRegistry.delete(docPath);
+  };
+}
+
+/**
+ * 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).
+ */
+export function dispatchDocChange(docPath: string): boolean {
+  const pull = pullRegistry.get(docPath);
+  if (!pull) return false;
+  pull();
+  return true;
+}
+
+/** Broadcast the current SSE health to all subscribers. */
+export function emitSseStatus(up: boolean): void {
+  sseUp = up;
+  for (const l of statusListeners) l(up);
+}
+
+/**
+ * Subscribe to SSE health changes. Fires immediately with the current state.
+ * Returns an unsubscribe function.
+ */
+export function onSseStatus(cb: StatusListener): () => void {
+  statusListeners.add(cb);
+  cb(sseUp);
+  return () => statusListeners.delete(cb);
+}
+
+/**
+ * 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.
+ */
+export function clearLiveSyncBus(): void {
+  pullRegistry.clear();
+  sseUp = false;
+}

package/src/utils/search-match.test.ts

@@ -0,0 +1,149 @@
+import { describe, it, expect } from 'vitest';
+import { matchTitle, rankResults, fold, isWordStart } from './search-match.js';
+
+// ── fold ──────────────────────────────────────────────────────────────────────
+
+describe('fold', () => {
+  it('lowercases ASCII', () => expect(fold('Hello World')).toBe('hello world'));
+  it('strips diacritics (é → e, ñ → n)', () => {
+    expect(fold('café')).toBe('cafe');
+    expect(fold('mañana')).toBe('manana');
+  });
+  it('preserves string length after stripping diacritics', () => {
+    const s = 'crêpe';
+    expect(fold(s).length).toBe(s.length);
+  });
+  it('passes through surrogate pairs unchanged', () => {
+    const emoji = '🐙notes';
+    expect(fold(emoji).length).toBe(emoji.length);
+  });
+});
+
+// ── isWordStart ───────────────────────────────────────────────────────────────
+
+describe('isWordStart', () => {
+  it('position 0 is always a word start', () => expect(isWordStart('hello', 0)).toBe(true));
+  it('letter after a space is a word start', () => expect(isWordStart('hello world', 6)).toBe(true));
+  it('letter after another letter is not', () => expect(isWordStart('hello', 2)).toBe(false));
+  it('letter after a dash is a word start', () => expect(isWordStart('hello-world', 6)).toBe(true));
+});
+
+// ── matchTitle tiers ──────────────────────────────────────────────────────────
+
+describe('matchTitle', () => {
+  it('returns null for empty query', () => expect(matchTitle('', 'Notes')).toBeNull());
+  it('returns null on a miss', () => expect(matchTitle('xyz', 'Notes')).toBeNull());
+
+  it('PREFIX tier — title starts with query', () => {
+    const m = matchTitle('not', 'Notes');
+    expect(m).not.toBeNull();
+    expect(m!.score).toBeGreaterThanOrEqual(3900);
+    expect(m!.ranges).toEqual([{ start: 0, end: 3 }]);
+  });
+
+  it('WORD tier — query matches at a word boundary', () => {
+    const m = matchTitle('pa', 'New page');
+    expect(m).not.toBeNull();
+    expect(m!.score).toBeGreaterThanOrEqual(2900);
+    expect(m!.score).toBeLessThan(4000);
+    expect(m!.ranges[0]!.start).toBe(4); // 'p' in "page"
+  });
+
+  it('SUBSTRING tier — query appears mid-word', () => {
+    const m = matchTitle('page', 'Homepage');
+    expect(m).not.toBeNull();
+    expect(m!.score).toBeGreaterThanOrEqual(1900);
+    expect(m!.score).toBeLessThan(3000);
+  });
+
+  it('FUZZY tier — query is a subsequence', () => {
+    const m = matchTitle('rdm', 'Roadmap');
+    expect(m).not.toBeNull();
+    expect(m!.score).toBeGreaterThanOrEqual(900);
+    expect(m!.score).toBeLessThan(2000);
+  });
+
+  it('PREFIX beats WORD beats SUBSTRING beats FUZZY', () => {
+    const prefix = matchTitle('no', 'Notes')!.score;
+    const word = matchTitle('pa', 'New page')!.score;
+    const substr = matchTitle('age', 'Homepage')!.score;
+    const fuzzy = matchTitle('rdm', 'Roadmap')!.score;
+    expect(prefix).toBeGreaterThan(word);
+    expect(word).toBeGreaterThan(substr);
+    expect(substr).toBeGreaterThan(fuzzy);
+  });
+
+  it('match is case-insensitive', () => {
+    expect(matchTitle('NOTE', 'notes')).not.toBeNull();
+    expect(matchTitle('note', 'NOTES')).not.toBeNull();
+  });
+
+  it('match is diacritic-insensitive', () => {
+    expect(matchTitle('cafe', 'café au lait')).not.toBeNull();
+    expect(matchTitle('creme', 'crème brûlée')).not.toBeNull();
+  });
+
+  it('fuzzy: spaces in query are ignored', () => {
+    expect(matchTitle('new pg', 'New page')).not.toBeNull();
+  });
+
+  it('fuzzy: adjacent hits merge into one range', () => {
+    const m = matchTitle('ab', 'xaby');
+    expect(m).not.toBeNull();
+    // 'ab' appears at position 1 as a substring; but if it fell through to fuzzy
+    // the two chars 'a' and 'b' at positions 1 and 2 would be one merged range.
+    expect(m!.ranges.length).toBe(1);
+  });
+
+  it('range spans index into original title (not folded)', () => {
+    const title = 'New Page';
+    const m = matchTitle('pa', title);
+    expect(m).not.toBeNull();
+    const { start, end } = m!.ranges[0]!;
+    expect(title.slice(start, end).toLowerCase()).toBe('pa');
+  });
+});
+
+// ── rankResults ───────────────────────────────────────────────────────────────
+
+const NOW = 1_700_000_000_000;
+
+function item(title: string, updatedAt = NOW) {
+  return { title, updatedAt };
+}
+
+describe('rankResults', () => {
+  it('returns empty array for empty list', () => {
+    expect(rankResults('test', [])).toEqual([]);
+  });
+
+  it('drops items that do not match', () => {
+    const results = rankResults('xyz', [item('Notes'), item('Roadmap')]);
+    expect(results).toHaveLength(0);
+  });
+
+  it('higher-tier match comes first', () => {
+    // "Notes" is a prefix match for "not"; "Homepage" is only a substring match
+    const results = rankResults('not', [item('Homepage notation'), item('Notes')]);
+    expect(results[0]!.item.title).toBe('Notes');
+  });
+
+  it('recency breaks score ties', () => {
+    const old = item('Notes', NOW - 10_000);
+    const recent = item('Notes', NOW);
+    const results = rankResults('not', [old, recent]);
+    expect(results[0]!.item).toBe(recent);
+  });
+
+  it('respects limit', () => {
+    const items = Array.from({ length: 10 }, (_, i) => item(`note ${i}`));
+    const results = rankResults('note', items, 3);
+    expect(results).toHaveLength(3);
+  });
+
+  it('each result carries score and ranges', () => {
+    const results = rankResults('note', [item('Notes')]);
+    expect(results[0]!.score).toBeGreaterThan(0);
+    expect(results[0]!.ranges.length).toBeGreaterThan(0);
+  });
+});