deepspace 0.3.9 → 0.3.11

package/features/docs/src/editor/useDocEditor.ts

@@ -0,0 +1,206 @@
+/**
+ * Tiptap editor hook bound to a Yjs `XmlFragment` + Awareness.
+ *
+ * Why Tiptap vs the old contenteditable approach:
+ *   - Y.XmlFragment is a structured CRDT — remote keystrokes become
+ *     fine-grained ProseMirror transactions, not an `innerHTML` swap.
+ *   - Local caret survives concurrent remote edits via ProseMirror's
+ *     position-mapping system (no manual probe / restore).
+ *   - Remote cursors come from `@tiptap/extension-collaboration-caret`
+ *     reading the same Awareness instance our WS hook already wires.
+ *   - No HTML round-trip in storage, so browser-inserted artefacts
+ *     (`&nbsp;`, `<div><br></div>`, IME composition state) cannot
+ *     corrupt the shared document.
+ */
+
+import { useEffect, useMemo, useRef } from 'react'
+import { useEditor, type Editor } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import Collaboration from '@tiptap/extension-collaboration'
+import { CollaborationCaret } from '@tiptap/extension-collaboration-caret'
+import Placeholder from '@tiptap/extension-placeholder'
+import Typography from '@tiptap/extension-typography'
+import TextAlign from '@tiptap/extension-text-align'
+import { TextStyle } from '@tiptap/extension-text-style'
+import Color from '@tiptap/extension-color'
+import Highlight from '@tiptap/extension-highlight'
+import Subscript from '@tiptap/extension-subscript'
+import Superscript from '@tiptap/extension-superscript'
+import TaskList from '@tiptap/extension-task-list'
+import TaskItem from '@tiptap/extension-task-item'
+import type { Awareness } from 'deepspace'
+import type * as Y from 'yjs'
+
+type CollaborationUser = {
+  name?: string | null
+  color?: string | null
+}
+
+const DEFAULT_COLLABORATION_COLOR = '#2563eb'
+const DISALLOWED_COLLABORATION_COLORS = new Set([
+  '#fff',
+  '#ffff',
+  '#ffffff',
+  '#ffffffff',
+  'white',
+  'rgb(255, 255, 255)',
+  'rgba(255, 255, 255, 1)',
+])
+
+export interface UseDocEditorOptions {
+  doc: Y.Doc
+  /** Awareness instance shared with the Yjs WS hook (or null while not yet connected). */
+  awareness: Awareness | null
+  userName: string
+  userColor: string
+  synced: boolean
+  canWrite: boolean
+  placeholder?: string
+}
+
+function collaborationColorFor(user: CollaborationUser): string {
+  const color = user.color?.trim()
+  if (!color || DISALLOWED_COLLABORATION_COLORS.has(color.toLowerCase())) {
+    return DEFAULT_COLLABORATION_COLOR
+  }
+  return color
+}
+
+function renderCollaborationCaret(user: CollaborationUser): HTMLElement {
+  const color = collaborationColorFor(user)
+  const cursor = document.createElement('span')
+  cursor.classList.add('collaboration-carets__caret')
+  cursor.style.setProperty('--collaboration-caret-color', color)
+  cursor.setAttribute('aria-hidden', 'true')
+
+  const label = document.createElement('span')
+  label.classList.add('collaboration-carets__label')
+  label.style.backgroundColor = `color-mix(in srgb, ${color} 16%, var(--docs-editor-paper))`
+  label.style.color = color
+  label.textContent = user.name || 'Collaborator'
+  cursor.appendChild(label)
+
+  return cursor
+}
+
+function renderCollaborationSelection(user: CollaborationUser) {
+  const color = collaborationColorFor(user)
+  return {
+    class: 'ProseMirror-yjs-selection collaboration-carets__selection',
+    style: `background-color: color-mix(in srgb, ${color} 20%, transparent)`,
+  }
+}
+
+/** Pasted HTML sometimes carries our own collab caret nodes — scrub them. */
+function stripCollaborationArtifactsFromHTML(html: string): string {
+  if (typeof document === 'undefined') return html
+
+  const container = document.createElement('div')
+  container.innerHTML = html
+
+  container
+    .querySelectorAll('.collaboration-carets__caret, .collaboration-carets__label')
+    .forEach((node) => node.remove())
+
+  container
+    .querySelectorAll('.ProseMirror-yjs-selection, .collaboration-carets__selection')
+    .forEach((node) => {
+      node.replaceWith(...Array.from(node.childNodes))
+    })
+
+  return container.innerHTML
+}
+
+export function useDocEditor({
+  doc,
+  awareness,
+  userName,
+  userColor,
+  synced,
+  canWrite,
+  placeholder = 'Start typing — toolbar above for formatting…',
+}: UseDocEditorOptions): Editor | null {
+  /** Structured CRDT field that ProseMirror binds to — distinct from the legacy Y.Text('content'). */
+  const fragment = useMemo(() => doc.getXmlFragment('default'), [doc])
+
+  /** CollaborationCaret expects a provider-shaped `{ awareness }` object. */
+  const provider = useMemo(() => (awareness ? { awareness } : null), [awareness])
+
+  const extensions = useMemo(() => {
+    const exts: unknown[] = [
+      StarterKit.configure({
+        // Yjs has its own undo/redo history via the Collaboration extension; keeping
+        // both enabled corrupts the shared document on undo.
+        undoRedo: false,
+        link: {
+          openOnClick: false,
+          autolink: true,
+          HTMLAttributes: { rel: 'noopener noreferrer', target: '_blank' },
+        },
+      }),
+      Collaboration.configure({ fragment }),
+      TextAlign.configure({ types: ['heading', 'paragraph'] }),
+      TextStyle,
+      Color,
+      Highlight.configure({
+        multicolor: true,
+        HTMLAttributes: { class: 'docs-text-highlight' },
+      }),
+      Subscript,
+      Superscript,
+      TaskList,
+      TaskItem.configure({ nested: true }),
+      Typography,
+      Placeholder.configure({ placeholder }),
+    ]
+
+    if (provider) {
+      exts.push(
+        CollaborationCaret.configure({
+          provider,
+          user: { name: userName, color: userColor },
+          render: renderCollaborationCaret,
+          selectionRender: renderCollaborationSelection,
+        }),
+      )
+    }
+
+    return exts
+  }, [fragment, provider, userName, userColor, placeholder])
+
+  const editor = useEditor(
+    {
+      editable: synced && canWrite,
+      // Tiptap renders synchronously by default which trips up React's strict mode
+      // in dev (the editor view is destroyed and re-created, and any subscriber
+      // that runs in between throws on `editor.view`). Defer to a useEffect.
+      immediatelyRender: false,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      extensions: extensions as any,
+      editorProps: {
+        transformPastedHTML: stripCollaborationArtifactsFromHTML,
+        attributes: {
+          class: 'docs-tiptap-editor',
+          'data-testid': 'docs-tiptap-editor',
+        },
+      },
+    },
+    [extensions],
+  )
+
+  /**
+   * Toggle editable without thrashing the editor: setEditable is cheap and
+   * preserves selection/awareness, whereas re-creating the editor on every
+   * `synced`/`canWrite` change would flicker remote carets and reset undo.
+   */
+  const prevEditable = useRef(false)
+  useEffect(() => {
+    const editable = synced && canWrite
+    if (editor && editable !== prevEditable.current) {
+      prevEditable.current = editable
+      editor.setEditable(editable)
+    }
+  }, [editor, synced, canWrite])
+
+  return editor
+}

package/features/docs/src/use-yjs-room-with-awareness.ts

@@ -0,0 +1,285 @@
+/**
+ * Matches {@link import('deepspace').useYjsRoom} (YjsRoom DO via /ws/yjs/:id) but wires
+ * {@link Awareness} over the server's MSG_AWARENESS path. Published `useYjsRoom` builds may
+ * omit awareness relay; collaborator avatars/presence otherwise never populate.
+ */
+
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react'
+import * as Y from 'yjs'
+import {
+  Awareness,
+  createDecoder,
+  createEncoder,
+  encodeAwarenessMessage,
+  getAuthToken,
+  handleAwarenessMessage,
+  MSG_AWARENESS,
+  MSG_SYNC,
+  MSG_SYNC_STEP1,
+  MSG_SYNC_STEP2,
+  MSG_SYNC_UPDATE,
+  readVarUint,
+  readVarUint8Array,
+  toUint8Array,
+  writeVarUint,
+  writeVarUint8Array,
+} from 'deepspace'
+
+const UPDATE_BATCH_DELAY_MS = 16
+
+export interface UseYjsRoomWithAwarenessResult {
+  doc: Y.Doc
+  text: string
+  setText: (value: string) => void
+  synced: boolean
+  /** From the server's WebSocket `{ type:'auth', canWrite }`; false until confirmed. */
+  canWrite: boolean
+  /** Becomes true after the auth message is parsed (eliminates transient false before handshake). */
+  writeAuthResolved: boolean
+  awareness: Awareness
+}
+
+export function useYjsRoomWithAwareness(
+  docId: string,
+  fieldName: string,
+): UseYjsRoomWithAwarenessResult {
+  const [syncedDocId, setSyncedDocId] = useState<string | null>(null)
+  const [canWrite, setCanWrite] = useState(false)
+  const [writeAuthResolved, setWriteAuthResolved] = useState(false)
+  const [text, setTextState] = useState('')
+  const [, setUpdateCount] = useState(0)
+  const synced = syncedDocId === docId
+
+  const { doc, awareness } = useMemo(() => {
+    const nextDoc = new Y.Doc()
+    return { doc: nextDoc, awareness: new Awareness(nextDoc) }
+  }, [docId])
+
+  const wsRef = useRef<WebSocket | null>(null)
+  const isLocalRef = useRef(false)
+  const applyingRemoteAwarenessRef = useRef(false)
+  const pendingUpdatesRef = useRef<Uint8Array[]>([])
+  const updateBatchTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  const yText = useMemo(() => doc.getText(fieldName), [doc, fieldName])
+
+  useEffect(() => {
+    return () => {
+      awareness.setLocalState(null)
+      doc.destroy()
+    }
+  }, [awareness, doc])
+
+  useLayoutEffect(() => {
+    setSyncedDocId(null)
+    setCanWrite(false)
+    setWriteAuthResolved(false)
+    setTextState('')
+  }, [docId])
+
+  useEffect(() => {
+    const observer = () => {
+      if (isLocalRef.current) return
+      setTextState(yText.toString())
+    }
+    yText.observe(observer)
+    return () => yText.unobserve(observer)
+  }, [yText])
+
+  useEffect(() => {
+    let ws: WebSocket | null = null
+    let reconnectTimer: ReturnType<typeof setTimeout> | null = null
+    let alive = true
+
+    const connect = async (isReconnect: boolean) => {
+      if (!alive) return
+
+      if (!isReconnect) {
+        doc.transact(() => {
+          if (yText.length > 0) yText.delete(0, yText.length)
+        })
+        setTextState('')
+        try {
+          awareness.setLocalState(null)
+        } catch {
+          /* ignore */
+        }
+      }
+
+      const token = await getAuthToken()
+      if (!alive) return
+      const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:'
+      const baseUrl = `${protocol}//${window.location.host}`
+      const url = new URL(`/ws/yjs/${encodeURIComponent(docId)}`, baseUrl)
+      if (token) url.searchParams.set('token', token)
+      ws = new WebSocket(url.toString())
+      ws.binaryType = 'arraybuffer'
+      wsRef.current = ws
+
+      ws.onopen = () => {
+        setSyncedDocId(null)
+      }
+
+      ws.onmessage = (event: MessageEvent<ArrayBuffer>) => {
+        if (typeof event.data === 'string') {
+          try {
+            const msg = JSON.parse(event.data) as { type?: string; canWrite?: boolean }
+            if (msg.type === 'auth') {
+              setWriteAuthResolved(true)
+              if (typeof msg.canWrite === 'boolean') setCanWrite(msg.canWrite)
+            }
+          } catch {
+            /* ignore */
+          }
+          return
+        }
+
+        const data = new Uint8Array(event.data)
+        const decoder = createDecoder(data)
+        const messageType = readVarUint(decoder)
+
+        if (messageType === MSG_SYNC) {
+          const syncType = readVarUint(decoder)
+          const payload = readVarUint8Array(decoder)
+          switch (syncType) {
+            case MSG_SYNC_STEP1: {
+              const diff = Y.encodeStateAsUpdate(doc, payload)
+              const enc = createEncoder()
+              writeVarUint(enc, MSG_SYNC)
+              writeVarUint(enc, MSG_SYNC_STEP2)
+              writeVarUint8Array(enc, diff)
+              ws?.send(toUint8Array(enc).buffer)
+              setSyncedDocId(docId)
+              break
+            }
+            case MSG_SYNC_STEP2: {
+              Y.applyUpdate(doc, payload, 'server')
+              setTextState(yText.toString())
+              setSyncedDocId(docId)
+              break
+            }
+            case MSG_SYNC_UPDATE: {
+              Y.applyUpdate(doc, payload, 'server')
+              setTextState(yText.toString())
+              setUpdateCount((c) => c + 1)
+              break
+            }
+          }
+        } else if (messageType === MSG_AWARENESS) {
+          applyingRemoteAwarenessRef.current = true
+          try {
+            handleAwarenessMessage(awareness, data)
+          } catch {
+            /* ignore malformed */
+          } finally {
+            applyingRemoteAwarenessRef.current = false
+          }
+        }
+      }
+
+      ws.onclose = () => {
+        wsRef.current = null
+        setSyncedDocId(null)
+        if (alive) reconnectTimer = setTimeout(() => void connect(true), 1000)
+      }
+
+      ws.onerror = () => ws?.close()
+    }
+
+    void connect(false)
+
+    return () => {
+      alive = false
+      if (reconnectTimer) clearTimeout(reconnectTimer)
+      if (ws) {
+        ws.onclose = null
+        ws.onmessage = null
+        ws.onerror = null
+        ws.close()
+      }
+      wsRef.current = null
+    }
+  }, [doc, docId, yText, awareness])
+
+  useEffect(() => {
+    /**
+     * Tiptap fires a Yjs `update` for every keystroke. Sending each as its
+     * own WS frame floods the socket and visibly drops typing latency under
+     * load. We coalesce into a single MSG_SYNC_UPDATE per ~16 ms via
+     * Y.mergeUpdates — same behaviour Tiptap collab examples ship with.
+     */
+    const flushPendingUpdates = () => {
+      updateBatchTimerRef.current = null
+      const updates = pendingUpdatesRef.current
+      pendingUpdatesRef.current = []
+      const socket = wsRef.current
+      if (!socket || socket.readyState !== WebSocket.OPEN || updates.length === 0) return
+
+      const enc = createEncoder()
+      writeVarUint(enc, MSG_SYNC)
+      writeVarUint(enc, MSG_SYNC_UPDATE)
+      writeVarUint8Array(enc, updates.length === 1 ? updates[0] : Y.mergeUpdates(updates))
+      socket.send(toUint8Array(enc).buffer)
+    }
+
+    const handler = (update: Uint8Array, origin: unknown) => {
+      if (origin === 'server') return
+      const socket = wsRef.current
+      if (!socket || socket.readyState !== WebSocket.OPEN) return
+      pendingUpdatesRef.current.push(update)
+      if (!updateBatchTimerRef.current) {
+        updateBatchTimerRef.current = setTimeout(flushPendingUpdates, UPDATE_BATCH_DELAY_MS)
+      }
+    }
+    doc.on('update', handler)
+    return () => {
+      doc.off('update', handler)
+      if (updateBatchTimerRef.current) {
+        clearTimeout(updateBatchTimerRef.current)
+        flushPendingUpdates()
+      }
+      pendingUpdatesRef.current = []
+    }
+  }, [doc])
+
+  useEffect(() => {
+    const handleAwarenessUpdate = ({
+      added,
+      updated,
+      removed,
+    }: {
+      added: number[]
+      updated: number[]
+      removed: number[]
+    }) => {
+      if (applyingRemoteAwarenessRef.current) return
+      const changedClients = [...added, ...updated, ...removed]
+      if (changedClients.length === 0) return
+      const socket = wsRef.current
+      if (!socket || socket.readyState !== WebSocket.OPEN) return
+      socket.send(encodeAwarenessMessage(awareness, changedClients).buffer)
+    }
+
+    awareness.on('update', handleAwarenessUpdate)
+    return () => {
+      awareness.off('update', handleAwarenessUpdate)
+      awareness.setLocalState(null)
+    }
+  }, [awareness])
+
+  const setText = useCallback(
+    (value: string) => {
+      setTextState(value)
+      if (!canWrite) return
+      isLocalRef.current = true
+      doc.transact(() => {
+        yText.delete(0, yText.length)
+        yText.insert(0, value)
+      })
+      isLocalRef.current = false
+    },
+    [doc, yText, canWrite],
+  )
+
+  return { doc, text, setText, synced, canWrite, writeAuthResolved, awareness }
+}

package/features/file-attachments/feature.json

@@ -0,0 +1,42 @@
+{
+  "id": "file-attachments",
+  "name": "File Attachments",
+  "category": "data",
+  "description": "File upload with inline previews for images, videos, audio, PDF, code, CSV, DOCX, XLSX",
+  "details": "Adds a file attachments collection backed by R2 storage with useR2Files. Includes two hooks: useMimeTypeDetection (magic-byte MIME detection + 11 file categories) and useFilePreview (centralized preview with dynamic imports for PDF.js, CodeMirror, PapaParse, docx-preview, ExcelJS). Members can upload and manage their own files, admins can manage all.",
+  "files": [
+    { "src": "src/attachments-schema.ts", "dest": "src/schemas/attachments-schema.ts" },
+    { "src": "src/attachments-constants.ts", "dest": "src/constants/attachments-constants.ts" },
+    { "src": "src/useMimeTypeDetection.ts", "dest": "src/hooks/useMimeTypeDetection.ts" },
+    { "src": "src/useFilePreview.ts", "dest": "src/hooks/useFilePreview.ts" },
+    { "src": "src/AttachmentsPage.tsx", "dest": "src/pages/attachments.tsx" }
+  ],
+  "schema": {
+    "exportName": "attachmentsSchema",
+    "importPath": "./schemas/attachments-schema",
+    "spreadOperator": false
+  },
+  "route": {
+    "path": "/attachments",
+    "protected": true
+  },
+  "requires": [],
+  "dependencies": {
+    "file-type": "^19.6.0",
+    "@uiw/react-codemirror": "^4.23.0",
+    "@codemirror/lang-javascript": "^6.2.2",
+    "@codemirror/theme-one-dark": "^6.1.2",
+    "papaparse": "^5.4.1",
+    "docx-preview": "^0.3.5",
+    "exceljs": "^4.4.0",
+    "pdfjs-dist": "^4.7.76"
+  },
+  "instructions": [],
+  "patterns": [
+    "useMimeTypeDetection() → { detectMimeType, getFileCategory, getExtension, canPreview }",
+    "useFilePreview({ url, fileName, mimeType }) → { category, canPreview, textContent, csvData, codeEditorKit, xlsxData, ... }",
+    "useR2Files() → { upload, downloadFile, readFile, deleteFile, list, getUrl, isUploading }",
+    "File metadata stored in collection, binary stored in R2",
+    "Dynamic imports: PDF.js for PDF, CodeMirror for code, PapaParse for CSV, docx-preview for DOCX, ExcelJS for XLSX"
+  ]
+}