deepspace 0.7.0 → 0.8.0

package/features/docs/src/DocsListPage.tsx

@@ -25,18 +25,14 @@ import {
   Pencil,
 } from 'lucide-react'
 import { LibrarySidebar, readSidebarCollapsed, writeSidebarCollapsed } from './LibrarySidebar'
-import { getFavorites, saveFavorites } from './docs-favorites'
-import type { DocFolderFields, LibraryNavSelection } from './docs-library-types'
+import {
+  parseDocsIdList,
+  type DocFolderFields,
+  type DocsDocumentFields,
+  type LibraryNavSelection,
+} from './docs-library-types'
 import './docs-ui.css'
 
-interface DocumentFields {
-  title: string
-  ownerId: string
-  collaborators?: string
-  editors?: string
-  folderId?: string
-}
-
 type SortOption = 'lastEdited' | 'titleAZ' | 'titleZA'
 type ViewMode = 'grid' | 'list'
 
@@ -47,6 +43,24 @@ const SORT_OPTIONS: { value: SortOption; label: string }[] = [
 ]
 
 const UNTITLED = 'Untitled Document'
+const FAVORITES_KEY = 'deepspace-docs-favorites'
+
+function readFavorites(): Set<string> {
+  try {
+    const stored = localStorage.getItem(FAVORITES_KEY)
+    return new Set(parseDocsIdList(stored ?? undefined))
+  } catch {
+    return new Set()
+  }
+}
+
+function writeFavorites(favorites: Set<string>): void {
+  try {
+    localStorage.setItem(FAVORITES_KEY, JSON.stringify([...favorites]))
+  } catch {
+    // Favorites are local convenience state; storage denial must not break UI state.
+  }
+}
 
 function greetingForTime(): string {
   const h = new Date().getHours()
@@ -63,16 +77,6 @@ function formatDate(iso: string): string {
   })
 }
 
-function parseIdList(raw: string | undefined): string[] {
-  if (!raw) return []
-  try {
-    const parsed = JSON.parse(raw)
-    return Array.isArray(parsed) ? parsed.filter((id): id is string => typeof id === 'string') : []
-  } catch {
-    return []
-  }
-}
-
 export default function DocsListPage() {
   const { user } = useUser()
   const navigate = useNavigate()
@@ -83,7 +87,7 @@ export default function DocsListPage() {
   const [sortBy, setSortBy] = useState<SortOption>('lastEdited')
   const [viewMode, setViewMode] = useState<ViewMode>('grid')
   const [sortOpen, setSortOpen] = useState(false)
-  const [favorites, setFavorites] = useState<Set<string>>(() => getFavorites())
+  const [favorites, setFavorites] = useState<Set<string>>(readFavorites)
   const [libraryNav, setLibraryNav] = useState<LibraryNavSelection>({ kind: 'all' })
   const [sidebarCollapsed, setSidebarCollapsed] = useState(readSidebarCollapsed)
   const [renamingId, setRenamingId] = useState<string | null>(null)
@@ -93,11 +97,11 @@ export default function DocsListPage() {
   const [moveMenuId, setMoveMenuId] = useState<string | null>(null)
   const [actionsMenuId, setActionsMenuId] = useState<string | null>(null)
 
-  const { records: documents, status } = useQuery<DocumentFields>('documents', {
+  const { records: documents, status } = useQuery<DocsDocumentFields>('documents', {
     orderBy: 'createdAt',
     orderDir: 'desc',
   })
-  const { create, remove, put } = useMutations<DocumentFields>('documents')
+  const { create, remove, put } = useMutations<DocsDocumentFields>('documents')
 
   const { records: folderRecords } = useQuery<DocFolderFields>('doc_folders', {
     orderBy: 'createdAt',
@@ -128,16 +132,16 @@ export default function DocsListPage() {
   const displayFirstName = user?.name?.trim().split(/\s+/)[0] ?? 'there'
 
   const isOwnedDocument = useCallback(
-    (d: RecordData<DocumentFields>) => d.data.ownerId === user?.id,
+    (d: RecordData<DocsDocumentFields>) => d.data.ownerId === user?.id,
     [user?.id],
   )
 
   const isSharedWithCurrentUser = useCallback(
-    (d: RecordData<DocumentFields>) =>
+    (d: RecordData<DocsDocumentFields>) =>
       Boolean(
         user?.id &&
-          d.data.ownerId !== user.id &&
-          parseIdList(d.data.collaborators).includes(user.id),
+        d.data.ownerId !== user.id &&
+        parseDocsIdList(d.data.collaborators).includes(user.id),
       ),
     [user?.id],
   )
@@ -160,7 +164,7 @@ export default function DocsListPage() {
   }, [libraryNav, sortedFolders])
 
   const matchesNav = useCallback(
-    (d: RecordData<DocumentFields>) => {
+    (d: RecordData<DocsDocumentFields>) => {
       const fid = d.data.folderId ?? ''
       if (libraryNav.kind === 'all') return isOwnedDocument(d)
       if (libraryNav.kind === 'shared') return isSharedWithCurrentUser(d)
@@ -205,7 +209,7 @@ export default function DocsListPage() {
       const next = new Set(prev)
       if (next.has(contentId)) next.delete(contentId)
       else next.add(contentId)
-      saveFavorites(next)
+      writeFavorites(next)
       return next
     })
   }, [])

package/features/docs/src/InviteDialog.tsx

@@ -3,14 +3,7 @@ import type { RecordData } from 'deepspace'
 import { useMutations, useQuery, useUser } from 'deepspace'
 import { Mail, ShieldCheck, UserMinus, Users } from 'lucide-react'
 import { Modal, useToast } from '@/components/ui'
-
-export interface InviteDialogDocumentFields {
-  title: string
-  ownerId: string
-  collaborators?: string
-  editors?: string
-  folderId?: string
-}
+import { parseDocsIdList, type DocsDocumentFields, type InviteAclDiff } from './docs-library-types'
 
 interface UserFields {
   email?: string
@@ -20,25 +13,10 @@ interface UserFields {
 
 type InviteRole = 'viewer' | 'editor'
 
-/**
- * Diff that resulted from an InviteDialog save. The editor page rebroadcasts
- * this over the doc's presence channel so the affected peer gets the change
- * even when the docs schema's `read: 'collaborator'` rule prevents the
- * `documents` record update from reaching a now-removed user.
- */
-export interface InviteAclDiff {
-  /** Users dropped from `collaborators` entirely. */
-  removedUserIds: string[]
-  /** Users who lost the editor role but remain collaborators (now viewers). */
-  demotedUserIds: string[]
-  /** Existing collaborators who gained the editor role. */
-  promotedUserIds: string[]
-}
-
 interface InviteDialogProps {
   open: boolean
   onOpenChange: (open: boolean) => void
-  doc: RecordData<InviteDialogDocumentFields>
+  doc: RecordData<DocsDocumentFields>
   isOwner: boolean
   /**
    * Called after a save mutation that changed the ACL. The parent uses it to
@@ -49,16 +27,6 @@ interface InviteDialogProps {
   onAclChange?: (diff: InviteAclDiff) => void
 }
 
-function parseIds(raw: string | undefined): string[] {
-  if (!raw) return []
-  try {
-    const parsed = JSON.parse(raw)
-    return Array.isArray(parsed) ? parsed.filter((id): id is string => typeof id === 'string') : []
-  } catch {
-    return []
-  }
-}
-
 function uniqueIds(ids: string[]): string[] {
   return [...new Set(ids.filter(Boolean))]
 }
@@ -75,14 +43,17 @@ function initialsFor(name: string): string {
 export function InviteDialog({ open, onOpenChange, doc, isOwner, onAclChange }: InviteDialogProps) {
   const { user } = useUser()
   const { records: users } = useQuery<UserFields>('users')
-  const { put } = useMutations<InviteDialogDocumentFields>('documents')
+  const { put } = useMutations<DocsDocumentFields>('documents')
   const toast = useToast()
   const [email, setEmail] = useState('')
   const [role, setRole] = useState<InviteRole>('editor')
   const [saving, setSaving] = useState(false)
 
-  const collaborators = useMemo(() => parseIds(doc.data.collaborators), [doc.data.collaborators])
-  const editors = useMemo(() => parseIds(doc.data.editors), [doc.data.editors])
+  const collaborators = useMemo(
+    () => parseDocsIdList(doc.data.collaborators),
+    [doc.data.collaborators],
+  )
+  const editors = useMemo(() => parseDocsIdList(doc.data.editors), [doc.data.editors])
 
   const ownerRecord = useMemo(
     () => users.find((u) => u.recordId === doc.data.ownerId),
@@ -100,8 +71,8 @@ export function InviteDialog({ open, onOpenChange, doc, isOwner, onAclChange }:
   if (!isOwner) return null
 
   const saveAccess = async (nextCollaborators: string[], nextEditors: string[]) => {
-    const prevCollaborators = parseIds(doc.data.collaborators)
-    const prevEditors = parseIds(doc.data.editors)
+    const prevCollaborators = parseDocsIdList(doc.data.collaborators)
+    const prevEditors = parseDocsIdList(doc.data.editors)
     const nextCollabList = uniqueIds(nextCollaborators)
     const nextCollabSet = new Set(nextCollabList)
     const nextEditorList = uniqueIds(nextEditors).filter((id) => nextCollabSet.has(id))
@@ -181,7 +152,7 @@ export function InviteDialog({ open, onOpenChange, doc, isOwner, onAclChange }:
 
   return (
     <Modal open={open} onClose={() => onOpenChange(false)} size="lg" className="docs-feature-scope">
-      <Modal.Header onClose={() => onOpenChange(false)}>
+      <Modal.Header>
         <Modal.Title>Share document</Modal.Title>
         <Modal.Description>
           Invite DeepSpace users by the email address on their account.

package/features/docs/src/__tests__/docs-presence-access.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'vitest'
+import {
+  deriveDocsAccessChange,
+  detectDocsAclEvent,
+  isDocsOwner,
+  resolveDocsAccessRole,
+} from '../use-docs-presence-access'
+
+describe('document access policy', () => {
+  const document = {
+    data: {
+      ownerId: 'owner',
+      collaborators: JSON.stringify(['editor', 'viewer']),
+      editors: JSON.stringify(['editor']),
+    },
+  }
+
+  it('resolves owner, editor, viewer, and no-access roles from the document ACL', () => {
+    expect(resolveDocsAccessRole(document, 'owner')).toBe('owner')
+    expect(resolveDocsAccessRole(document, 'editor')).toBe('editor')
+    expect(resolveDocsAccessRole(document, 'viewer')).toBe('viewer')
+    expect(resolveDocsAccessRole(document, 'outsider')).toBe('none')
+    expect(resolveDocsAccessRole(document, null)).toBe('none')
+  })
+
+  it('does not expose owner controls while both the document and user are loading', () => {
+    expect(isDocsOwner(undefined, undefined)).toBe(false)
+    expect(isDocsOwner(document, undefined)).toBe(false)
+    expect(isDocsOwner(undefined, 'owner')).toBe(false)
+    expect(isDocsOwner(document, 'owner')).toBe(true)
+  })
+
+  it('treats malformed ACL fields as empty lists', () => {
+    const malformed = {
+      data: { ownerId: 'owner', collaborators: '{broken', editors: JSON.stringify('editor') },
+    }
+    expect(resolveDocsAccessRole(malformed, 'editor')).toBe('none')
+  })
+
+  it('derives only actionable transitions from the session baseline', () => {
+    expect(deriveDocsAccessChange('editor', 'viewer', null)).toBe('downgrade')
+    expect(deriveDocsAccessChange('viewer', 'editor', null)).toBe('upgrade')
+    expect(deriveDocsAccessChange('viewer', 'none', null)).toBe('revoked')
+    expect(deriveDocsAccessChange('owner', 'owner', null)).toBeNull()
+    expect(deriveDocsAccessChange(null, 'viewer', { kind: 'downgrade', at: 20 })).toBe('downgrade')
+    expect(deriveDocsAccessChange('editor', 'viewer', { kind: 'revoked', at: 20 })).toBe('revoked')
+  })
+
+  it('accepts only a fresh ACL signal addressed to the current user', () => {
+    const state = {
+      aclSignal: {
+        at: 20,
+        removed: ['removed-user'],
+        demoted: ['demoted-user'],
+        promoted: ['promoted-user'],
+      },
+    }
+
+    expect(detectDocsAclEvent(state, 'removed-user', 10)).toEqual({ kind: 'revoked', at: 20 })
+    expect(detectDocsAclEvent(state, 'demoted-user', 10)).toEqual({
+      kind: 'downgrade',
+      at: 20,
+    })
+    expect(detectDocsAclEvent(state, 'promoted-user', 10)).toEqual({
+      kind: 'upgrade',
+      at: 20,
+    })
+    expect(detectDocsAclEvent(state, 'other-user', 10)).toBeNull()
+    expect(detectDocsAclEvent(state, 'removed-user', 20)).toBeNull()
+  })
+})

package/features/docs/src/docs-library-types.ts

@@ -1,15 +1,40 @@
-/**
- * Library navigation + folder types for docs UI (aligned with docs2).
- */
+/** Shared document, ACL, folder, and navigation model for the Docs feature. */
+
+export interface DocsDocumentFields {
+  title: string
+  ownerId: string
+  collaborators?: string
+  editors?: string
+  folderId?: string
+}
 
 export interface DocFolderFields {
   name: string
   ownerId: string
 }
 
+export interface InviteAclDiff {
+  /** Users dropped from `collaborators` entirely. */
+  removedUserIds: string[]
+  /** Users who lost the editor role but remain collaborators (now viewers). */
+  demotedUserIds: string[]
+  /** Existing collaborators who gained the editor role. */
+  promotedUserIds: string[]
+}
+
 export type LibraryNavSelection =
   | { kind: 'all' }
   | { kind: 'shared' }
   | { kind: 'favorites' }
   | { kind: 'uncategorized' }
   | { kind: 'folder'; folderId: string }
+
+export function parseDocsIdList(raw: string | undefined): string[] {
+  if (!raw) return []
+  try {
+    const parsed: unknown = JSON.parse(raw)
+    return Array.isArray(parsed) ? parsed.filter((id): id is string => typeof id === 'string') : []
+  } catch {
+    return []
+  }
+}

package/features/docs/src/docs-ui.css

@@ -18,10 +18,7 @@
   --docs-el-accent: var(--color-primary, var(--theme-accent, var(--ui-accent, #3b82f6)));
   --docs-el-line: var(--color-border, var(--theme-border, rgba(15, 23, 42, 0.12)));
 
-  --docs-el-selection: var(
-    --color-primary-muted,
-    color-mix(in srgb, var(--docs-el-accent) 22%, transparent)
-  );
+  --docs-el-selection: color-mix(in srgb, var(--docs-el-accent) 22%, transparent);
 
   --docs-editor-desk: var(
     --color-muted,

package/features/docs/src/use-docs-presence-access.ts

@@ -0,0 +1,330 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { usePresenceRoom, type PresencePeerClient, type UsePresenceRoomResult } from 'deepspace'
+import type { Editor } from '@tiptap/react'
+import type { DocsPresenceParticipant } from './DocsPresence'
+import { parseDocsIdList, type DocsDocumentFields, type InviteAclDiff } from './docs-library-types'
+
+const TYPING_IDLE_MS = 1600
+const TYPING_STALE_MS = 5000
+/** Re-broadcast presence so clients who connect later still see existing viewers. */
+const PRESENCE_HEARTBEAT_MS = 25_000
+
+export type DocsAccessRole = 'owner' | 'editor' | 'viewer' | 'none'
+export type AccessChangeKind = 'downgrade' | 'upgrade' | 'revoked'
+
+interface DocsAccessDocument {
+  data: Pick<DocsDocumentFields, 'ownerId' | 'collaborators' | 'editors'>
+}
+
+interface DocsPresenceUser {
+  id: string
+  name?: string | null
+  email?: string | null
+  imageUrl?: string | null
+}
+
+interface DetectedAclEvent {
+  kind: AccessChangeKind
+  at: number
+}
+
+export function isDocsOwner(
+  document: DocsAccessDocument | null | undefined,
+  userId: string | null | undefined,
+): boolean {
+  return Boolean(document && userId && document.data.ownerId === userId)
+}
+
+export function resolveDocsAccessRole(
+  document: DocsAccessDocument | null | undefined,
+  userId: string | null | undefined,
+): DocsAccessRole {
+  if (!userId || !document) return 'none'
+  if (isDocsOwner(document, userId)) return 'owner'
+  if (parseDocsIdList(document.data.editors).includes(userId)) return 'editor'
+  if (parseDocsIdList(document.data.collaborators).includes(userId)) return 'viewer'
+  return 'none'
+}
+
+export function deriveDocsAccessChange(
+  initialRole: DocsAccessRole | null,
+  effectiveRole: DocsAccessRole,
+  detectedEvent: DetectedAclEvent | null,
+): AccessChangeKind | null {
+  // A presence-derived revoke is the only signal guaranteed to reach a peer
+  // whose document subscription was removed, so it takes precedence.
+  if (detectedEvent?.kind === 'revoked') return 'revoked'
+
+  if (initialRole && initialRole !== 'owner') {
+    if (effectiveRole === 'none') return 'revoked'
+    if (initialRole === 'editor' && effectiveRole === 'viewer') return 'downgrade'
+    if (initialRole === 'viewer' && effectiveRole === 'editor') return 'upgrade'
+  }
+
+  return detectedEvent?.kind ?? null
+}
+
+export function detectDocsAclEvent(
+  state: Record<string, unknown>,
+  userId: string,
+  sessionStartedAt: number,
+): DetectedAclEvent | null {
+  const rawSignal = state.aclSignal
+  if (!rawSignal || typeof rawSignal !== 'object') return null
+
+  const signal = rawSignal as {
+    at?: unknown
+    removed?: unknown
+    demoted?: unknown
+    promoted?: unknown
+  }
+  if (typeof signal.at !== 'number' || signal.at <= sessionStartedAt) return null
+
+  const includesUser = (list: unknown): boolean =>
+    Array.isArray(list) && list.some((id) => id === userId)
+
+  if (includesUser(signal.removed)) return { kind: 'revoked', at: signal.at }
+  if (includesUser(signal.demoted)) return { kind: 'downgrade', at: signal.at }
+  if (includesUser(signal.promoted)) return { kind: 'upgrade', at: signal.at }
+  return null
+}
+
+function peerToDocsParticipant(peer: PresencePeerClient): DocsPresenceParticipant {
+  const state = peer.state
+  const mode: DocsPresenceParticipant['mode'] = state.mode === 'view' ? 'view' : 'edit'
+  const lastTypedAt = typeof state.lastTypedAt === 'number' ? state.lastTypedAt : undefined
+  const participant: DocsPresenceParticipant = {
+    clientId: 0,
+    userId: peer.userId,
+    name: peer.userName?.trim() || peer.userEmail?.trim() || 'Guest',
+    mode,
+    typing: state.typing === true,
+    isSelf: false,
+  }
+  if (peer.userEmail) participant.email = peer.userEmail
+  if (peer.userImageUrl) participant.imageUrl = peer.userImageUrl
+  if (lastTypedAt != null) participant.lastTypedAt = lastTypedAt
+  return participant
+}
+
+function sortDocsPresenceParticipants(
+  left: DocsPresenceParticipant,
+  right: DocsPresenceParticipant,
+): number {
+  if (left.isSelf !== right.isSelf) return left.isSelf ? -1 : 1
+  if (left.mode !== right.mode) return left.mode === 'edit' ? -1 : 1
+  return left.name.localeCompare(right.name)
+}
+
+function buildDocsPresence(
+  peers: PresencePeerClient[],
+  self: DocsPresenceUser | null | undefined,
+  editMode: boolean,
+): DocsPresenceParticipant[] {
+  if (!self) {
+    return [...peers.map(peerToDocsParticipant)].sort(sortDocsPresenceParticipants)
+  }
+
+  const selfRow: DocsPresenceParticipant = {
+    clientId: 0,
+    userId: self.id,
+    name: self.name?.trim() || self.email?.trim() || 'You',
+    mode: editMode ? 'edit' : 'view',
+    isSelf: true,
+  }
+  if (self.email) selfRow.email = self.email
+  if (self.imageUrl) selfRow.imageUrl = self.imageUrl
+
+  const others = peers.filter((peer) => peer.userId !== self.id).map(peerToDocsParticipant)
+  return [selfRow, ...others].sort(sortDocsPresenceParticipants)
+}
+
+interface UseDocsPresenceAccessOptions {
+  docId: string | undefined
+  document: DocsAccessDocument | null | undefined
+  user: DocsPresenceUser | null | undefined
+  yjsCanWrite: boolean
+  writeAuthResolved: boolean
+}
+
+interface DocsPresenceAccessResult {
+  isOwner: boolean
+  effectiveRole: DocsAccessRole
+  effectiveCanWrite: boolean
+  showReadOnlyDocUx: boolean
+  accessChangeKind: AccessChangeKind | null
+  handleAclChange: (diff: InviteAclDiff) => void
+  presenceAsEditMode: boolean
+  presenceRoom: UsePresenceRoomResult
+}
+
+export function useDocsPresenceAccess({
+  docId,
+  document,
+  user,
+  yjsCanWrite,
+  writeAuthResolved,
+}: UseDocsPresenceAccessOptions): DocsPresenceAccessResult {
+  const presenceRoom = usePresenceRoom(docId ? `doc:${docId}` : '_')
+  const { peers, updateState } = presenceRoom
+  const isOwner = isDocsOwner(document, user?.id)
+  const effectiveRole = resolveDocsAccessRole(document, user?.id)
+  const policyCanEdit = effectiveRole === 'owner' || effectiveRole === 'editor'
+
+  /** The first concrete role is the baseline for live ACL transitions. */
+  const [initialRole, setInitialRole] = useState<DocsAccessRole | null>(null)
+  const sessionStartedAtRef = useRef<number | null>(null)
+  useEffect(() => {
+    setInitialRole(null)
+    sessionStartedAtRef.current = null
+  }, [docId])
+  useEffect(() => {
+    if (initialRole || !document || !user || effectiveRole === 'none') return
+    setInitialRole(effectiveRole)
+    sessionStartedAtRef.current = Date.now()
+  }, [document, effectiveRole, initialRole, user])
+
+  /** Presence reaches peers after document-read access has been revoked. */
+  const [detectedAclEvent, setDetectedAclEvent] = useState<DetectedAclEvent | null>(null)
+  useEffect(() => {
+    setDetectedAclEvent(null)
+  }, [docId])
+  useEffect(() => {
+    if (!user || !document || detectedAclEvent) return
+    const sessionStartedAt = sessionStartedAtRef.current
+    if (sessionStartedAt == null || user.id === document.data.ownerId) return
+
+    const ownerPeer = peers.find((peer) => peer.userId === document.data.ownerId)
+    if (!ownerPeer) return
+    const nextEvent = detectDocsAclEvent(ownerPeer.state, user.id, sessionStartedAt)
+    if (nextEvent) setDetectedAclEvent(nextEvent)
+  }, [detectedAclEvent, document, peers, user])
+
+  const accessChangeKind = useMemo(
+    () => deriveDocsAccessChange(initialRole, effectiveRole, detectedAclEvent),
+    [detectedAclEvent, effectiveRole, initialRole],
+  )
+  const accessLocked = accessChangeKind !== null
+  const writesLockedByAcl = accessLocked && accessChangeKind !== 'upgrade'
+  const effectiveCanWrite = yjsCanWrite && policyCanEdit && !writesLockedByAcl
+  const showReadOnlyDocUx =
+    effectiveRole === 'viewer' || (policyCanEdit && writeAuthResolved && !yjsCanWrite)
+  const presenceAsEditMode =
+    policyCanEdit && !(writeAuthResolved && !yjsCanWrite) && !writesLockedByAcl
+
+  const handleAclChange = useCallback(
+    (diff: InviteAclDiff) => {
+      if (!isOwner) return
+      updateState({
+        aclSignal: {
+          at: Date.now(),
+          removed: diff.removedUserIds,
+          demoted: diff.demotedUserIds,
+          promoted: diff.promotedUserIds,
+        },
+      })
+    },
+    [isOwner, updateState],
+  )
+
+  return {
+    isOwner,
+    effectiveRole,
+    effectiveCanWrite,
+    showReadOnlyDocUx,
+    accessChangeKind,
+    handleAclChange,
+    presenceAsEditMode,
+    presenceRoom,
+  }
+}
+
+interface UseDocsEditorPresenceOptions {
+  editor: Editor | null
+  document: DocsAccessDocument | null | undefined
+  user: DocsPresenceUser | null | undefined
+  synced: boolean
+  access: DocsPresenceAccessResult
+}
+
+export function useDocsEditorPresence({
+  editor,
+  document,
+  user,
+  synced,
+  access,
+}: UseDocsEditorPresenceOptions): {
+  participants: DocsPresenceParticipant[]
+  typingNames: string[]
+} {
+  const { effectiveCanWrite, presenceAsEditMode, presenceRoom } = access
+  const { peers, connected, updateState } = presenceRoom
+  const typingRef = useRef(false)
+  const typingTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  const participants = useMemo(
+    () => buildDocsPresence(peers, user, presenceAsEditMode),
+    [peers, presenceAsEditMode, user],
+  )
+
+  const publishPresence = useCallback(
+    (typing: boolean) => {
+      if (!document || !user || !synced) return
+      updateState({
+        mode: presenceAsEditMode ? 'edit' : 'view',
+        typing,
+        ...(typing ? { lastTypedAt: Date.now() } : {}),
+      })
+    },
+    [document, presenceAsEditMode, synced, updateState, user],
+  )
+
+  useEffect(() => {
+    if (!editor) return
+    const onUpdate = () => {
+      if (!effectiveCanWrite) return
+      typingRef.current = true
+      publishPresence(true)
+      if (typingTimeoutRef.current) clearTimeout(typingTimeoutRef.current)
+      typingTimeoutRef.current = setTimeout(() => {
+        typingRef.current = false
+        publishPresence(false)
+      }, TYPING_IDLE_MS)
+    }
+    editor.on('update', onUpdate)
+    return () => {
+      editor.off('update', onUpdate)
+      if (typingTimeoutRef.current) clearTimeout(typingTimeoutRef.current)
+    }
+  }, [editor, effectiveCanWrite, publishPresence])
+
+  useEffect(() => {
+    publishPresence(typingRef.current)
+  }, [connected, publishPresence])
+
+  useEffect(() => {
+    if (!synced || !document || !user) return
+    const id = window.setInterval(() => publishPresence(typingRef.current), PRESENCE_HEARTBEAT_MS)
+    return () => clearInterval(id)
+  }, [document, publishPresence, synced, user])
+
+  const typingNames = useMemo(() => {
+    const names: string[] = []
+    const seen = new Set<string>()
+    for (const participant of participants) {
+      if (participant.isSelf || !participant.typing) continue
+      if (
+        participant.lastTypedAt != null &&
+        Date.now() - participant.lastTypedAt >= TYPING_STALE_MS
+      ) {
+        continue
+      }
+      if (seen.has(participant.name)) continue
+      seen.add(participant.name)
+      names.push(participant.name)
+    }
+    return names
+  }, [participants])
+
+  return { participants, typingNames }
+}