deepspace 0.10.1 → 0.10.3

package/features/{docs/src/use-docs-presence-access.ts → documents/src/use-documents-presence-access.ts}

@@ -1,22 +1,22 @@
 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'
+import type { DocumentsPresenceParticipant } from './DocumentsPresence'
+import { parseDocumentsIdList, type DocumentsDocumentFields, type InviteAclDiff } from './documents-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 DocumentsAccessRole = 'owner' | 'editor' | 'viewer' | 'none'
 export type AccessChangeKind = 'downgrade' | 'upgrade' | 'revoked'
 
-interface DocsAccessDocument {
-  data: Pick<DocsDocumentFields, 'ownerId' | 'collaborators' | 'editors'>
+interface DocumentsAccessDocument {
+  data: Pick<DocumentsDocumentFields, 'ownerId' | 'collaborators' | 'editors'>
 }
 
-interface DocsPresenceUser {
+interface DocumentsPresenceUser {
   id: string
   name?: string | null
   email?: string | null
@@ -28,27 +28,27 @@ interface DetectedAclEvent {
   at: number
 }
 
-export function isDocsOwner(
-  document: DocsAccessDocument | null | undefined,
+export function isDocumentsOwner(
+  document: DocumentsAccessDocument | null | undefined,
   userId: string | null | undefined,
 ): boolean {
   return Boolean(document && userId && document.data.ownerId === userId)
 }
 
-export function resolveDocsAccessRole(
-  document: DocsAccessDocument | null | undefined,
+export function resolveDocumentsAccessRole(
+  document: DocumentsAccessDocument | null | undefined,
   userId: string | null | undefined,
-): DocsAccessRole {
+): DocumentsAccessRole {
   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'
+  if (isDocumentsOwner(document, userId)) return 'owner'
+  if (parseDocumentsIdList(document.data.editors).includes(userId)) return 'editor'
+  if (parseDocumentsIdList(document.data.collaborators).includes(userId)) return 'viewer'
   return 'none'
 }
 
-export function deriveDocsAccessChange(
-  initialRole: DocsAccessRole | null,
-  effectiveRole: DocsAccessRole,
+export function deriveDocumentsAccessChange(
+  initialRole: DocumentsAccessRole | null,
+  effectiveRole: DocumentsAccessRole,
   detectedEvent: DetectedAclEvent | null,
 ): AccessChangeKind | null {
   // A presence-derived revoke is the only signal guaranteed to reach a peer
@@ -64,7 +64,7 @@ export function deriveDocsAccessChange(
   return detectedEvent?.kind ?? null
 }
 
-export function detectDocsAclEvent(
+export function detectDocumentsAclEvent(
   state: Record<string, unknown>,
   userId: string,
   sessionStartedAt: number,
@@ -89,11 +89,11 @@ export function detectDocsAclEvent(
   return null
 }
 
-function peerToDocsParticipant(peer: PresencePeerClient): DocsPresenceParticipant {
+function peerToDocumentsParticipant(peer: PresencePeerClient): DocumentsPresenceParticipant {
   const state = peer.state
-  const mode: DocsPresenceParticipant['mode'] = state.mode === 'view' ? 'view' : 'edit'
+  const mode: DocumentsPresenceParticipant['mode'] = state.mode === 'view' ? 'view' : 'edit'
   const lastTypedAt = typeof state.lastTypedAt === 'number' ? state.lastTypedAt : undefined
-  const participant: DocsPresenceParticipant = {
+  const participant: DocumentsPresenceParticipant = {
     clientId: 0,
     userId: peer.userId,
     name: peer.userName?.trim() || peer.userEmail?.trim() || 'Guest',
@@ -107,25 +107,25 @@ function peerToDocsParticipant(peer: PresencePeerClient): DocsPresenceParticipan
   return participant
 }
 
-function sortDocsPresenceParticipants(
-  left: DocsPresenceParticipant,
-  right: DocsPresenceParticipant,
+function sortDocumentsPresenceParticipants(
+  left: DocumentsPresenceParticipant,
+  right: DocumentsPresenceParticipant,
 ): 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(
+function buildDocumentsPresence(
   peers: PresencePeerClient[],
-  self: DocsPresenceUser | null | undefined,
+  self: DocumentsPresenceUser | null | undefined,
   editMode: boolean,
-): DocsPresenceParticipant[] {
+): DocumentsPresenceParticipant[] {
   if (!self) {
-    return [...peers.map(peerToDocsParticipant)].sort(sortDocsPresenceParticipants)
+    return [...peers.map(peerToDocumentsParticipant)].sort(sortDocumentsPresenceParticipants)
   }
 
-  const selfRow: DocsPresenceParticipant = {
+  const selfRow: DocumentsPresenceParticipant = {
     clientId: 0,
     userId: self.id,
     name: self.name?.trim() || self.email?.trim() || 'You',
@@ -135,21 +135,21 @@ function buildDocsPresence(
   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)
+  const others = peers.filter((peer) => peer.userId !== self.id).map(peerToDocumentsParticipant)
+  return [selfRow, ...others].sort(sortDocumentsPresenceParticipants)
 }
 
-interface UseDocsPresenceAccessOptions {
+interface UseDocumentsPresenceAccessOptions {
   docId: string | undefined
-  document: DocsAccessDocument | null | undefined
-  user: DocsPresenceUser | null | undefined
+  document: DocumentsAccessDocument | null | undefined
+  user: DocumentsPresenceUser | null | undefined
   yjsCanWrite: boolean
   writeAuthResolved: boolean
 }
 
-interface DocsPresenceAccessResult {
+interface DocumentsPresenceAccessResult {
   isOwner: boolean
-  effectiveRole: DocsAccessRole
+  effectiveRole: DocumentsAccessRole
   effectiveCanWrite: boolean
   showReadOnlyDocUx: boolean
   accessChangeKind: AccessChangeKind | null
@@ -158,21 +158,21 @@ interface DocsPresenceAccessResult {
   presenceRoom: UsePresenceRoomResult
 }
 
-export function useDocsPresenceAccess({
+export function useDocumentsPresenceAccess({
   docId,
   document,
   user,
   yjsCanWrite,
   writeAuthResolved,
-}: UseDocsPresenceAccessOptions): DocsPresenceAccessResult {
+}: UseDocumentsPresenceAccessOptions): DocumentsPresenceAccessResult {
   const presenceRoom = usePresenceRoom(docId ? `doc:${docId}` : '_')
   const { peers, updateState } = presenceRoom
-  const isOwner = isDocsOwner(document, user?.id)
-  const effectiveRole = resolveDocsAccessRole(document, user?.id)
+  const isOwner = isDocumentsOwner(document, user?.id)
+  const effectiveRole = resolveDocumentsAccessRole(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 [initialRole, setInitialRole] = useState<DocumentsAccessRole | null>(null)
   const sessionStartedAtRef = useRef<number | null>(null)
   useEffect(() => {
     setInitialRole(null)
@@ -196,12 +196,12 @@ export function useDocsPresenceAccess({
 
     const ownerPeer = peers.find((peer) => peer.userId === document.data.ownerId)
     if (!ownerPeer) return
-    const nextEvent = detectDocsAclEvent(ownerPeer.state, user.id, sessionStartedAt)
+    const nextEvent = detectDocumentsAclEvent(ownerPeer.state, user.id, sessionStartedAt)
     if (nextEvent) setDetectedAclEvent(nextEvent)
   }, [detectedAclEvent, document, peers, user])
 
   const accessChangeKind = useMemo(
-    () => deriveDocsAccessChange(initialRole, effectiveRole, detectedAclEvent),
+    () => deriveDocumentsAccessChange(initialRole, effectiveRole, detectedAclEvent),
     [detectedAclEvent, effectiveRole, initialRole],
   )
   const accessLocked = accessChangeKind !== null
@@ -239,22 +239,22 @@ export function useDocsPresenceAccess({
   }
 }
 
-interface UseDocsEditorPresenceOptions {
+interface UseDocumentsEditorPresenceOptions {
   editor: Editor | null
-  document: DocsAccessDocument | null | undefined
-  user: DocsPresenceUser | null | undefined
+  document: DocumentsAccessDocument | null | undefined
+  user: DocumentsPresenceUser | null | undefined
   synced: boolean
-  access: DocsPresenceAccessResult
+  access: DocumentsPresenceAccessResult
 }
 
-export function useDocsEditorPresence({
+export function useDocumentsEditorPresence({
   editor,
   document,
   user,
   synced,
   access,
-}: UseDocsEditorPresenceOptions): {
-  participants: DocsPresenceParticipant[]
+}: UseDocumentsEditorPresenceOptions): {
+  participants: DocumentsPresenceParticipant[]
   typingNames: string[]
 } {
   const { effectiveCanWrite, presenceAsEditMode, presenceRoom } = access
@@ -263,7 +263,7 @@ export function useDocsEditorPresence({
   const typingTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
 
   const participants = useMemo(
-    () => buildDocsPresence(peers, user, presenceAsEditMode),
+    () => buildDocumentsPresence(peers, user, presenceAsEditMode),
     [peers, presenceAsEditMode, user],
   )
 

package/features/file-attachments/src/attachments-schema.ts

@@ -10,7 +10,7 @@
  * - Pairing collection metadata with R2 file storage
  */
 
-import type { CollectionSchema } from 'deepspace/worker'
+import type { CollectionSchema } from 'deepspace/schema'
 
 export const attachmentsSchema: CollectionSchema = {
   name: 'attachments',

package/features/items/src/items-schema.ts

@@ -8,7 +8,7 @@
  * - Basic CRUD with role-based permissions
  */
 
-import type { CollectionSchema } from 'deepspace/worker'
+import type { CollectionSchema } from 'deepspace/schema'
 
 export const itemsSchema: CollectionSchema = {
   name: 'items',

package/features/leaderboard/src/leaderboard-schema.ts

@@ -7,7 +7,7 @@
  * - Admin override for updating any entry
  */
 
-import type { CollectionSchema } from 'deepspace/worker'
+import type { CollectionSchema } from 'deepspace/schema'
 
 export const leaderboardSchema: CollectionSchema = {
   name: 'leaderboard',

package/features/messaging/src/ChatMultiPage.tsx

@@ -19,7 +19,7 @@ import { useMutations } from 'deepspace'
 import { RecordScope } from 'deepspace'
 import type { Channel, ChannelMember } from 'deepspace'
 import type { RecordData } from 'deepspace'
-import type { CollectionSchema } from 'deepspace/worker'
+import type { CollectionSchema } from 'deepspace/schema'
 import { messagingSchemas } from '../schemas/messaging-schema'
 import { ChannelSidebar } from '../components/messaging/chat-multi/ChannelSidebar'
 import { MessageList } from '../components/messaging/chat/MessageList'

package/features/messaging/src/ChatPage.tsx

@@ -7,7 +7,7 @@ import { useEffect, useRef } from 'react'
 import { useChatChannel } from '../components/messaging/hooks/useChatChannel'
 import { useReadReceipts } from 'deepspace'
 import { RecordScope } from 'deepspace'
-import type { CollectionSchema } from 'deepspace/worker'
+import type { CollectionSchema } from 'deepspace/schema'
 import { messagingSchemas } from '../schemas/messaging-schema'
 import { ChatHeader } from '../components/messaging/chat/ChatHeader'
 import { MessageList } from '../components/messaging/chat/MessageList'

package/features/messaging/src/messaging-schema.ts

@@ -5,7 +5,7 @@
  * Spread into the app's schemas array: ...messagingSchemas
  */
 
-import type { CollectionSchema } from 'deepspace/worker'
+import type { CollectionSchema } from 'deepspace/schema'
 import {
   CHANNELS_SCHEMA,
   MESSAGES_SCHEMA,
@@ -13,7 +13,7 @@ import {
   CHANNEL_MEMBERS_SCHEMA,
   CHANNEL_INVITATIONS_SCHEMA,
   READ_RECEIPTS_SCHEMA,
-} from 'deepspace/worker'
+} from 'deepspace/schema'
 
 export const messagingSchemas: CollectionSchema[] = [
   CHANNELS_SCHEMA,

package/features/tasks/src/tasks-schema.ts

@@ -8,7 +8,7 @@
  * - Admin-only grading workflow
  */
 
-import type { CollectionSchema } from 'deepspace/worker'
+import type { CollectionSchema } from 'deepspace/schema'
 
 export const challengesSchema: CollectionSchema = {
   name: 'challenges',

package/features/testing/src/test-schema.ts

@@ -2,8 +2,8 @@
  * Test Items Schema — exercises RBAC and CRUD for e2e testing.
  */
 
-import type { CollectionSchema } from 'deepspace/worker'
-import { ROLE_ANONYMOUS } from 'deepspace/worker'
+import { ROLE_ANONYMOUS } from 'deepspace'
+import type { CollectionSchema } from 'deepspace/schema'
 
 export const testItemsSchema: CollectionSchema = {
   name: 'test-items',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepspace",
-  "version": "0.10.1",
+  "version": "0.10.3",
   "engines": {
     "node": ">=22.15.0"
   },
@@ -17,6 +17,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./schema": {
+      "types": "./dist/schema.d.ts",
+      "import": "./dist/schema.js"
+    },
     "./worker": {
       "types": "./dist/worker.d.ts",
       "import": "./dist/worker.js"
@@ -28,6 +32,14 @@
     "./testing": {
       "types": "./dist/testing.d.ts",
       "import": "./dist/testing.js"
+    },
+    "./documentation": {
+      "types": "./dist/documentation.d.ts",
+      "import": "./dist/documentation.js"
+    },
+    "./documentation/react": {
+      "types": "./dist/documentation-react.d.ts",
+      "import": "./dist/documentation-react.js"
     }
   },
   "files": [
@@ -39,6 +51,7 @@
     "build": "node ../../scripts/clean-artifacts.mjs dist --tsbuildinfo && tsup",
     "type-check": "tsc --noEmit",
     "test": "vitest run",
+    "test:documentation-browser": "playwright test --config src/documentation/runtime/__browser__/playwright.config.ts",
     "clean": "node ../../scripts/clean-artifacts.mjs dist --tsbuildinfo",
     "prepublishOnly": "pnpm build"
   },
@@ -47,14 +60,25 @@
     "@ai-sdk/openai": "^2.0.0",
     "@ai-sdk/openai-compatible": "^1.0.0",
     "@clack/prompts": "^1.2.0",
+    "@mdx-js/mdx": "^3.1.1",
+    "acorn": "^8.16.0",
     "ai": "^5.0.0",
     "better-auth": "1.6.23",
     "citty": "^0.2.0",
     "cross-spawn": "^7.0.6",
     "esbuild": "^0.27.0",
+    "highlight.js": "^11.11.1",
     "hono": "^4.6.0",
     "jose": "^6.1.0",
+    "marked": "^18.0.7",
+    "mdast-util-gfm": "^3.1.0",
+    "mdast-util-to-markdown": "^2.1.2",
+    "rehype-highlight": "^7.0.2",
+    "remark-frontmatter": "^5.0.0",
+    "remark-gfm": "^4.0.1",
+    "sanitize-html": "^2.17.6",
     "smol-toml": "^1.6.1",
+    "yaml": "^2.9.0",
     "yjs": "^13.6.0",
     "zod": "^4.3.6"
   },
@@ -93,6 +117,7 @@
     "@types/cross-spawn": "^6.0.6",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
+    "@types/sanitize-html": "^2.16.1",
     "better-sqlite3": "^12.0.0",
     "clsx": "^2.1.1",
     "framer-motion": "^12.38.0",

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

@@ -1,71 +0,0 @@
-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()
-  })
-})