@actuate-media/cms-admin 0.11.0 → 0.12.1

package/src/__tests__/lib/active-editor.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import type { Editor } from '@tiptap/react'
+import {
+  setActiveEditor,
+  getActiveEditor,
+  clearActiveEditorIf,
+  subscribeActiveEditor,
+} from '../../lib/active-editor.js'
+
+function fakeEditor(): Editor {
+  return {} as Editor
+}
+
+beforeEach(() => {
+  setActiveEditor(null)
+})
+
+describe('active-editor registry', () => {
+  it('stores and returns the active editor', () => {
+    const a = fakeEditor()
+    expect(getActiveEditor()).toBeNull()
+    setActiveEditor(a)
+    expect(getActiveEditor()).toBe(a)
+  })
+
+  it('replaces the active editor', () => {
+    const a = fakeEditor()
+    const b = fakeEditor()
+    setActiveEditor(a)
+    setActiveEditor(b)
+    expect(getActiveEditor()).toBe(b)
+  })
+
+  it('accepts null to clear the active editor', () => {
+    setActiveEditor(fakeEditor())
+    setActiveEditor(null)
+    expect(getActiveEditor()).toBeNull()
+  })
+
+  it('notifies subscribers when the active editor changes', () => {
+    const listener = vi.fn()
+    const unsubscribe = subscribeActiveEditor(listener)
+    setActiveEditor(fakeEditor())
+    expect(listener).toHaveBeenCalledTimes(1)
+    setActiveEditor(fakeEditor())
+    expect(listener).toHaveBeenCalledTimes(2)
+    unsubscribe()
+    setActiveEditor(fakeEditor())
+    expect(listener).toHaveBeenCalledTimes(2)
+  })
+
+  it('skips notifications when the same editor is set twice', () => {
+    const listener = vi.fn()
+    const a = fakeEditor()
+    subscribeActiveEditor(listener)
+    setActiveEditor(a)
+    setActiveEditor(a)
+    expect(listener).toHaveBeenCalledTimes(1)
+  })
+
+  it('clearActiveEditorIf clears only when matched', () => {
+    const a = fakeEditor()
+    const b = fakeEditor()
+    setActiveEditor(a)
+    clearActiveEditorIf(b)
+    expect(getActiveEditor()).toBe(a)
+    clearActiveEditorIf(a)
+    expect(getActiveEditor()).toBeNull()
+  })
+})

package/src/__tests__/lib/coauthor-client.test.ts

@@ -0,0 +1,213 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+const cmsApiMock = vi.fn()
+vi.mock('../../lib/api.js', () => ({
+  cmsApi: (...args: unknown[]) => cmsApiMock(...args),
+}))
+
+const {
+  coauthorText,
+  coauthorActionLabel,
+  coauthorActionDescription,
+  isCoauthorAction,
+  COAUTHOR_ACTIONS,
+  COAUTHOR_TEXT_MAX_CHARS,
+} = await import('../../lib/coauthor-client.js')
+
+beforeEach(() => {
+  cmsApiMock.mockReset()
+})
+
+describe('isCoauthorAction', () => {
+  it('accepts the four canonical actions', () => {
+    expect(isCoauthorAction('rewrite')).toBe(true)
+    expect(isCoauthorAction('expand')).toBe(true)
+    expect(isCoauthorAction('compress')).toBe(true)
+    expect(isCoauthorAction('proofread')).toBe(true)
+  })
+
+  it('rejects anything else', () => {
+    expect(isCoauthorAction('summarize')).toBe(false)
+    expect(isCoauthorAction('')).toBe(false)
+    expect(isCoauthorAction(null)).toBe(false)
+    expect(isCoauthorAction(undefined)).toBe(false)
+    expect(isCoauthorAction(42)).toBe(false)
+  })
+})
+
+describe('COAUTHOR_ACTIONS', () => {
+  it('contains exactly the four canonical actions', () => {
+    expect([...COAUTHOR_ACTIONS]).toEqual(['rewrite', 'expand', 'compress', 'proofread'])
+  })
+})
+
+describe('coauthorActionLabel + coauthorActionDescription', () => {
+  it('returns a non-empty label and description for each action', () => {
+    for (const action of COAUTHOR_ACTIONS) {
+      expect(coauthorActionLabel(action)).toMatch(/\S/)
+      expect(coauthorActionDescription(action)).toMatch(/\S/)
+    }
+  })
+})
+
+describe('coauthorText — input validation', () => {
+  it('returns an error when text is empty', async () => {
+    const out = await coauthorText('rewrite', '')
+    expect(out).toEqual({ ok: false, error: 'No text provided', status: 0 })
+    expect(cmsApiMock).not.toHaveBeenCalled()
+  })
+
+  it('returns an error when text is only whitespace', async () => {
+    const out = await coauthorText('rewrite', '   \n\t ')
+    expect(out).toEqual({ ok: false, error: 'No text provided', status: 0 })
+    expect(cmsApiMock).not.toHaveBeenCalled()
+  })
+
+  it('returns an error when text exceeds the client-side ceiling', async () => {
+    const huge = 'a'.repeat(COAUTHOR_TEXT_MAX_CHARS + 1)
+    const out = await coauthorText('rewrite', huge)
+    expect(out.ok).toBe(false)
+    if (!out.ok) {
+      expect(out.error).toMatch(/exceeds/)
+      expect(out.status).toBe(0)
+    }
+    expect(cmsApiMock).not.toHaveBeenCalled()
+  })
+
+  it('returns an error for an unknown action', async () => {
+    // @ts-expect-error — exercising the runtime guard
+    const out = await coauthorText('summarize', 'hello world')
+    expect(out.ok).toBe(false)
+    if (!out.ok) {
+      expect(out.error).toMatch(/Unknown action/)
+    }
+    expect(cmsApiMock).not.toHaveBeenCalled()
+  })
+})
+
+describe('coauthorText — request shape', () => {
+  it('POSTs to /ai/coauthor with the action + text body', async () => {
+    cmsApiMock.mockResolvedValue({ data: { action: 'rewrite', text: 'output' }, status: 200 })
+
+    await coauthorText('rewrite', 'hello')
+
+    expect(cmsApiMock).toHaveBeenCalledTimes(1)
+    const [path, init] = cmsApiMock.mock.calls[0]!
+    expect(path).toBe('/ai/coauthor')
+    expect(init.method).toBe('POST')
+    expect(JSON.parse(init.body)).toEqual({ action: 'rewrite', text: 'hello' })
+  })
+
+  it('forwards style/tone/instructions/targetLength when provided', async () => {
+    cmsApiMock.mockResolvedValue({ data: { action: 'expand', text: 'longer output' }, status: 200 })
+
+    await coauthorText('expand', 'seed', {
+      style: 'academic',
+      tone: 'formal',
+      instructions: 'add two examples',
+      targetLength: 120,
+    })
+
+    const init = cmsApiMock.mock.calls[0]![1]
+    expect(JSON.parse(init.body)).toEqual({
+      action: 'expand',
+      text: 'seed',
+      style: 'academic',
+      tone: 'formal',
+      instructions: 'add two examples',
+      targetLength: 120,
+    })
+  })
+
+  it('omits undefined options from the body', async () => {
+    cmsApiMock.mockResolvedValue({ data: { action: 'rewrite', text: 'out' }, status: 200 })
+
+    await coauthorText('rewrite', 'in', { style: undefined, tone: undefined })
+
+    const init = cmsApiMock.mock.calls[0]![1]
+    const body = JSON.parse(init.body)
+    expect(body).toEqual({ action: 'rewrite', text: 'in' })
+    expect('style' in body).toBe(false)
+    expect('tone' in body).toBe(false)
+  })
+})
+
+describe('coauthorText — response handling', () => {
+  it('returns the parsed result on a successful response', async () => {
+    cmsApiMock.mockResolvedValue({
+      data: { action: 'rewrite', text: 'rewritten' },
+      status: 200,
+    })
+
+    const out = await coauthorText('rewrite', 'original')
+    expect(out).toEqual({
+      ok: true,
+      result: { action: 'rewrite', text: 'rewritten' },
+    })
+  })
+
+  it('forwards proofread changes only when action is proofread', async () => {
+    const changes = [{ original: 'teh', corrected: 'the' }]
+    cmsApiMock.mockResolvedValue({
+      data: { action: 'proofread', text: 'the cat', changes },
+      status: 200,
+    })
+
+    const out = await coauthorText('proofread', 'teh cat')
+    expect(out.ok).toBe(true)
+    if (out.ok) {
+      expect(out.result.changes).toEqual(changes)
+    }
+  })
+
+  it('drops changes when the action is not proofread', async () => {
+    cmsApiMock.mockResolvedValue({
+      data: { action: 'rewrite', text: 'rewritten', changes: [{ original: 'a', corrected: 'b' }] },
+      status: 200,
+    })
+
+    const out = await coauthorText('rewrite', 'a')
+    expect(out.ok).toBe(true)
+    if (out.ok) {
+      expect(out.result.changes).toBeUndefined()
+    }
+  })
+
+  it('returns an error when cmsApi reports an error', async () => {
+    cmsApiMock.mockResolvedValue({ error: 'rate limited', status: 429 })
+
+    const out = await coauthorText('rewrite', 'x')
+    expect(out).toEqual({ ok: false, error: 'rate limited', status: 429 })
+  })
+
+  it('synthesizes an error message when none is provided', async () => {
+    cmsApiMock.mockResolvedValue({ status: 500 })
+
+    const out = await coauthorText('rewrite', 'x')
+    expect(out.ok).toBe(false)
+    if (!out.ok) {
+      expect(out.error).toMatch(/500/)
+      expect(out.status).toBe(500)
+    }
+  })
+
+  it('flags malformed responses missing a text field', async () => {
+    cmsApiMock.mockResolvedValue({ data: { action: 'rewrite' }, status: 200 })
+
+    const out = await coauthorText('rewrite', 'x')
+    expect(out.ok).toBe(false)
+    if (!out.ok) {
+      expect(out.error).toMatch(/Malformed/)
+    }
+  })
+
+  it('falls back to the requested action when the server omits it', async () => {
+    cmsApiMock.mockResolvedValue({ data: { text: 'out' }, status: 200 })
+
+    const out = await coauthorText('compress', 'in')
+    expect(out.ok).toBe(true)
+    if (out.ok) {
+      expect(out.result.action).toBe('compress')
+    }
+  })
+})

package/src/__tests__/lib/collaboration-provider.test.ts

@@ -0,0 +1,425 @@
+import { Awareness } from 'y-protocols/awareness'
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest'
+import * as Y from 'yjs'
+
+import {
+  createCollaborationProvider,
+  summarisePresence,
+  type CollaborationOptions,
+} from '../../lib/collaboration-provider.js'
+
+// The provider helper requires a browser-like context (checks for `window`).
+// The cms-admin vitest config runs under `node`, so we stub a minimal window
+// for the whole file.
+const originalWindow = (globalThis as { window?: unknown }).window
+beforeAll(() => {
+  ;(globalThis as { window?: unknown }).window = globalThis
+})
+afterAll(() => {
+  ;(globalThis as { window?: unknown }).window = originalWindow
+})
+
+/**
+ * Fake WebsocketProvider that records constructor args + exposes manual
+ * emit hooks so tests can simulate connection-state transitions without
+ * opening real sockets.
+ */
+class FakeWsProvider {
+  static instances: FakeWsProvider[] = []
+  readonly url: string
+  readonly room: string
+  readonly ydoc: Y.Doc
+  readonly opts: { connect?: boolean; params?: Record<string, string> }
+  readonly awareness: Awareness
+  private listeners = new Map<string, Set<(payload: unknown) => void>>()
+  destroyed = false
+
+  constructor(
+    url: string,
+    room: string,
+    ydoc: Y.Doc,
+    opts: { connect?: boolean; params?: Record<string, string> },
+  ) {
+    this.url = url
+    this.room = room
+    this.ydoc = ydoc
+    this.opts = opts
+    this.awareness = new Awareness(ydoc)
+    FakeWsProvider.instances.push(this)
+  }
+
+  on(event: string, handler: (payload: unknown) => void): void {
+    let bucket = this.listeners.get(event)
+    if (!bucket) {
+      bucket = new Set()
+      this.listeners.set(event, bucket)
+    }
+    bucket.add(handler)
+  }
+
+  emit(event: string, payload: unknown): void {
+    const bucket = this.listeners.get(event)
+    if (!bucket) return
+    for (const handler of bucket) handler(payload)
+  }
+
+  destroy(): void {
+    this.destroyed = true
+  }
+}
+
+const Ctor = FakeWsProvider as unknown as ConstructorParameters<
+  typeof import('y-websocket').WebsocketProvider
+> extends unknown[]
+  ? typeof import('y-websocket').WebsocketProvider
+  : never
+
+const baseOptions: CollaborationOptions = {
+  documentId: 'doc-1',
+  url: 'ws://localhost:1234/realtime',
+  user: { name: 'Alice', color: '#ff00aa', userId: 'user_1' },
+}
+
+describe('createCollaborationProvider — construction', () => {
+  beforeEach(() => {
+    FakeWsProvider.instances.length = 0
+  })
+  afterEach(() => {
+    FakeWsProvider.instances.length = 0
+  })
+
+  it('throws if the global window is undefined (true SSR)', () => {
+    const origWindow = (globalThis as { window?: unknown }).window
+    delete (globalThis as { window?: unknown }).window
+    try {
+      expect(() =>
+        createCollaborationProvider(baseOptions, { WebsocketProviderCtor: Ctor }),
+      ).toThrow(/browser context/)
+    } finally {
+      ;(globalThis as { window?: unknown }).window = origWindow
+    }
+  })
+
+  it('throws when documentId is missing', () => {
+    expect(() =>
+      createCollaborationProvider(
+        { ...baseOptions, documentId: '' },
+        { WebsocketProviderCtor: Ctor },
+      ),
+    ).toThrow(/documentId/)
+  })
+
+  it('throws when url is missing', () => {
+    expect(() =>
+      createCollaborationProvider({ ...baseOptions, url: '' }, { WebsocketProviderCtor: Ctor }),
+    ).toThrow(/url/)
+  })
+
+  it('instantiates the provider with the supplied url + documentId', () => {
+    const ctx = createCollaborationProvider(baseOptions, { WebsocketProviderCtor: Ctor })
+    expect(FakeWsProvider.instances.length).toBe(1)
+    const instance = FakeWsProvider.instances[0]!
+    expect(instance.url).toBe(baseOptions.url)
+    expect(instance.room).toBe(baseOptions.documentId)
+    expect(instance.ydoc).toBe(ctx.ydoc)
+    ctx.destroy()
+  })
+
+  it('forwards params (e.g. auth token) to the provider', () => {
+    createCollaborationProvider(
+      { ...baseOptions, params: { token: 'abc' } },
+      { WebsocketProviderCtor: Ctor },
+    )
+    expect(FakeWsProvider.instances[0]!.opts.params).toEqual({ token: 'abc' })
+  })
+
+  it('defaults connect to true', () => {
+    createCollaborationProvider(baseOptions, { WebsocketProviderCtor: Ctor })
+    expect(FakeWsProvider.instances[0]!.opts.connect).toBe(true)
+  })
+
+  it('respects connect: false for offline / test usage', () => {
+    createCollaborationProvider({ ...baseOptions, connect: false }, { WebsocketProviderCtor: Ctor })
+    expect(FakeWsProvider.instances[0]!.opts.connect).toBe(false)
+  })
+})
+
+describe('createCollaborationProvider — awareness seeding', () => {
+  beforeEach(() => {
+    FakeWsProvider.instances.length = 0
+  })
+
+  it('writes the user info into local awareness state', () => {
+    const ctx = createCollaborationProvider(baseOptions, { WebsocketProviderCtor: Ctor })
+    const localState = ctx.awareness.getLocalState() as { user?: typeof baseOptions.user }
+    expect(localState.user).toEqual(baseOptions.user)
+    ctx.destroy()
+  })
+
+  it('includes avatarUrl in awareness when supplied', () => {
+    const ctx = createCollaborationProvider(
+      { ...baseOptions, user: { ...baseOptions.user, avatarUrl: 'https://example.test/a.png' } },
+      { WebsocketProviderCtor: Ctor },
+    )
+    const localState = ctx.awareness.getLocalState() as { user?: { avatarUrl?: string } }
+    expect(localState.user?.avatarUrl).toBe('https://example.test/a.png')
+    ctx.destroy()
+  })
+})
+
+describe('createCollaborationProvider — onStatus / onError', () => {
+  beforeEach(() => {
+    FakeWsProvider.instances.length = 0
+  })
+
+  it('forwards normalised status transitions to onStatus', () => {
+    const onStatus = vi.fn()
+    const ctx = createCollaborationProvider(
+      { ...baseOptions, onStatus },
+      { WebsocketProviderCtor: Ctor },
+    )
+    const provider = FakeWsProvider.instances[0]!
+    provider.emit('status', { status: 'connecting' })
+    provider.emit('status', { status: 'connected' })
+    provider.emit('status', { status: 'disconnected' })
+    expect(onStatus.mock.calls.map((c) => c[0])).toEqual([
+      'connecting',
+      'connected',
+      'disconnected',
+    ])
+    ctx.destroy()
+  })
+
+  it('ignores unknown status values', () => {
+    const onStatus = vi.fn()
+    const ctx = createCollaborationProvider(
+      { ...baseOptions, onStatus },
+      { WebsocketProviderCtor: Ctor },
+    )
+    FakeWsProvider.instances[0]!.emit('status', { status: 'gibberish' })
+    expect(onStatus).not.toHaveBeenCalled()
+    ctx.destroy()
+  })
+
+  it('calls onError when the provider fires a connection-error event', () => {
+    const onError = vi.fn()
+    const ctx = createCollaborationProvider(
+      { ...baseOptions, onError },
+      { WebsocketProviderCtor: Ctor },
+    )
+    FakeWsProvider.instances[0]!.emit('connection-error', { code: 4401 })
+    expect(onError).toHaveBeenCalledTimes(1)
+    expect((onError.mock.calls[0]![0] as Error).message).toMatch(/connection error/i)
+    ctx.destroy()
+  })
+})
+
+describe('createCollaborationProvider — destroy', () => {
+  beforeEach(() => {
+    FakeWsProvider.instances.length = 0
+  })
+
+  it('clears local awareness, destroys the provider, and destroys the doc', () => {
+    const ctx = createCollaborationProvider(baseOptions, { WebsocketProviderCtor: Ctor })
+    const provider = FakeWsProvider.instances[0]!
+    const docDestroySpy = vi.spyOn(ctx.ydoc, 'destroy')
+    ctx.destroy()
+    expect(ctx.awareness.getLocalState()).toBeNull()
+    expect(provider.destroyed).toBe(true)
+    expect(docDestroySpy).toHaveBeenCalledTimes(1)
+  })
+
+  it('is idempotent — second destroy does not throw', () => {
+    const ctx = createCollaborationProvider(baseOptions, { WebsocketProviderCtor: Ctor })
+    ctx.destroy()
+    expect(() => ctx.destroy()).not.toThrow()
+  })
+})
+
+describe('createCollaborationProvider — offline persistence', () => {
+  /** Stub IndexeddbPersistence that lets tests drive `whenSynced`. */
+  class FakeIdb {
+    static instances: FakeIdb[] = []
+    readonly name: string
+    readonly ydoc: Y.Doc
+    private resolve!: () => void
+    private reject!: (err: Error) => void
+    whenSynced: Promise<void>
+    destroyed = false
+    constructor(name: string, ydoc: Y.Doc) {
+      this.name = name
+      this.ydoc = ydoc
+      this.whenSynced = new Promise<void>((res, rej) => {
+        this.resolve = res
+        this.reject = rej
+      })
+      FakeIdb.instances.push(this)
+    }
+    fulfill() {
+      this.resolve()
+    }
+    fail(err: Error) {
+      this.reject(err)
+    }
+    destroy() {
+      this.destroyed = true
+    }
+  }
+  const IdbCtor = FakeIdb as unknown as ConstructorParameters<
+    typeof import('y-indexeddb').IndexeddbPersistence
+  > extends unknown[]
+    ? typeof import('y-indexeddb').IndexeddbPersistence
+    : never
+
+  beforeEach(() => {
+    FakeWsProvider.instances.length = 0
+    FakeIdb.instances.length = 0
+  })
+
+  it('marks offlineStatus as unsupported when indexedDB is unavailable', () => {
+    const onOfflineStatus = vi.fn()
+    const ctx = createCollaborationProvider(
+      { ...baseOptions, onOfflineStatus },
+      {
+        WebsocketProviderCtor: Ctor,
+        IndexeddbPersistenceCtor: IdbCtor,
+        isIndexedDbSupported: () => false,
+      },
+    )
+    expect(onOfflineStatus).toHaveBeenCalledWith('unsupported')
+    expect(ctx.offlinePersistence).toBeNull()
+    expect(ctx.offlineStatus).toBe('unsupported')
+    expect(FakeIdb.instances.length).toBe(0)
+    ctx.destroy()
+  })
+
+  it('opts out entirely when offline: false is passed', () => {
+    const onOfflineStatus = vi.fn()
+    const ctx = createCollaborationProvider(
+      { ...baseOptions, offline: false, onOfflineStatus },
+      {
+        WebsocketProviderCtor: Ctor,
+        IndexeddbPersistenceCtor: IdbCtor,
+        isIndexedDbSupported: () => true,
+      },
+    )
+    expect(onOfflineStatus).toHaveBeenCalledWith('unsupported')
+    expect(ctx.offlinePersistence).toBeNull()
+    expect(FakeIdb.instances.length).toBe(0)
+    ctx.destroy()
+  })
+
+  it('emits loading → ready when IndexedDB whenSynced resolves', async () => {
+    const onOfflineStatus = vi.fn()
+    const ctx = createCollaborationProvider(
+      { ...baseOptions, onOfflineStatus },
+      {
+        WebsocketProviderCtor: Ctor,
+        IndexeddbPersistenceCtor: IdbCtor,
+        isIndexedDbSupported: () => true,
+      },
+    )
+    expect(onOfflineStatus).toHaveBeenCalledWith('loading')
+    expect(FakeIdb.instances.length).toBe(1)
+    expect(FakeIdb.instances[0]!.name).toBe(`actuate-cms:${baseOptions.documentId}`)
+    expect(ctx.offlinePersistence).toBe(FakeIdb.instances[0]!)
+    FakeIdb.instances[0]!.fulfill()
+    await new Promise((r) => setTimeout(r, 0))
+    expect(onOfflineStatus).toHaveBeenLastCalledWith('ready')
+    expect(ctx.offlineStatus).toBe('ready')
+    ctx.destroy()
+    expect(FakeIdb.instances[0]!.destroyed).toBe(true)
+  })
+
+  it('emits error when whenSynced rejects', async () => {
+    const onOfflineStatus = vi.fn()
+    const onError = vi.fn()
+    const ctx = createCollaborationProvider(
+      { ...baseOptions, onOfflineStatus, onError },
+      {
+        WebsocketProviderCtor: Ctor,
+        IndexeddbPersistenceCtor: IdbCtor,
+        isIndexedDbSupported: () => true,
+      },
+    )
+    FakeIdb.instances[0]!.fail(new Error('quota exceeded'))
+    await new Promise((r) => setTimeout(r, 0))
+    expect(onOfflineStatus).toHaveBeenLastCalledWith('error')
+    expect(onError).toHaveBeenCalledTimes(1)
+    expect((onError.mock.calls[0]![0] as Error).message).toBe('quota exceeded')
+    ctx.destroy()
+  })
+
+  it('emits error when IndexeddbPersistence constructor throws', () => {
+    const onOfflineStatus = vi.fn()
+    const onError = vi.fn()
+    class ThrowingIdb {
+      constructor() {
+        throw new Error('IDB blocked')
+      }
+    }
+    const ctx = createCollaborationProvider(
+      { ...baseOptions, onOfflineStatus, onError },
+      {
+        WebsocketProviderCtor: Ctor,
+        IndexeddbPersistenceCtor:
+          ThrowingIdb as unknown as typeof FakeIdb as unknown as typeof IdbCtor,
+        isIndexedDbSupported: () => true,
+      },
+    )
+    expect(onOfflineStatus).toHaveBeenLastCalledWith('error')
+    expect(onError).toHaveBeenCalledTimes(1)
+    expect((onError.mock.calls[0]![0] as Error).message).toBe('IDB blocked')
+    expect(ctx.offlinePersistence).toBeNull()
+    ctx.destroy()
+  })
+})
+
+describe('summarisePresence', () => {
+  function makeAwareness(): Awareness {
+    return new Awareness(new Y.Doc())
+  }
+
+  it('returns the local awareness clientId', () => {
+    const aw = makeAwareness()
+    const snap = summarisePresence(aw)
+    expect(snap.selfClientId).toBe(aw.clientID)
+  })
+
+  it('includes peers that have a user object with a name', () => {
+    const aw = makeAwareness()
+    aw.setLocalState({ user: { name: 'Alice', color: '#fff', userId: 'u1' } })
+    const snap = summarisePresence(aw)
+    expect(snap.users).toHaveLength(1)
+    expect(snap.users[0]!.user.name).toBe('Alice')
+  })
+
+  it('skips entries with no user info', () => {
+    const aw = makeAwareness()
+    aw.setLocalState({})
+    const snap = summarisePresence(aw)
+    expect(snap.users).toHaveLength(0)
+  })
+
+  it('deduplicates by userId when peers share the same logical user', () => {
+    const aw = makeAwareness()
+    const otherDoc = new Y.Doc()
+    const otherAw = new Awareness(otherDoc)
+    aw.setLocalState({ user: { name: 'Alice', color: '#fff', userId: 'u1' } })
+    otherAw.setLocalState({ user: { name: 'Alice (tab 2)', color: '#000', userId: 'u1' } })
+    // Manually pipe otherAw's state into aw to simulate the awareness fan-out.
+    aw.getStates().set(otherAw.clientID, otherAw.getLocalState()!)
+    const snap = summarisePresence(aw)
+    // Both states share userId 'u1' → only one entry.
+    expect(snap.users).toHaveLength(1)
+  })
+
+  it('keeps multiple peers without userId as distinct entries', () => {
+    const aw = makeAwareness()
+    aw.setLocalState({ user: { name: 'Alice', color: '#fff' } })
+    aw.getStates().set(9999, { user: { name: 'Bob', color: '#000' } })
+    const snap = summarisePresence(aw)
+    expect(snap.users).toHaveLength(2)
+    expect(snap.users.map((u) => u.user.name).sort()).toEqual(['Alice', 'Bob'])
+  })
+})