Add experimental workspace presence and host user directories

.agents/rules/typescript.md

@@ -1,10 +1,11 @@
 ---
-description: TypeScript conventions for props, types, and type safety.
+description: TypeScript conventions for component filenames, props, types, and type safety.
 globs: '*.ts, *.tsx'
 alwaysApply: false
 ---
 
 - Always define a named `type` for component props above the component. Never use inline object types for props. Name it after the component: `type ChatPanelProps = { ... }`.
+- Use kebab-case for new React component filenames and their tests, such as `chat-panel.tsx` and `chat-panel.test.tsx`. Keep component and props identifiers in PascalCase: `ChatPanel`, `ChatPanelProps`.
 - Never use `any`. Use `unknown` when the type is truly unknown, then narrow it.
 - Never cast with `as any`. Prefer proper typing or `as unknown as T` with a comment explaining why.
 - Reuse existing types from `lib/types.ts` instead of redefining equivalent shapes.

client/api/app-config.test.ts

@@ -0,0 +1,29 @@
+import { afterEach, expect, test } from 'bun:test'
+import type { ClientAppConfig } from '@/lib/types'
+
+import { loadAppConfig } from './app-config'
+
+const originalFetch = Object.getOwnPropertyDescriptor(globalThis, 'fetch')
+
+afterEach(() => {
+  if (originalFetch) Object.defineProperty(globalThis, 'fetch', originalFetch)
+  else Reflect.deleteProperty(globalThis, 'fetch')
+})
+
+test('startup receives confirmed config while a failed refresh cannot enable a local profile from cached config', async () => {
+  const config: ClientAppConfig = {
+    cloudDemo: false,
+    experimental: { collab: true },
+    demoInstallUrl: 'https://moi.computer'
+  }
+  Object.defineProperty(globalThis, 'fetch', {
+    configurable: true,
+    value: async () => Response.json(config)
+  })
+  expect(await loadAppConfig()).toEqual(config)
+  Object.defineProperty(globalThis, 'fetch', {
+    configurable: true,
+    value: async () => Response.json({}, { status: 503 })
+  })
+  expect(await loadAppConfig()).toBeUndefined()
+})

client/api/app-config.ts

@@ -1,6 +1,7 @@
 import { useSyncExternalStore } from 'react'
 
 import type { ClientAppConfig } from '@/lib/types'
+import { EXPERIMENTAL_DEFAULTS } from '@/lib/experimental'
 
 import { onWorkspaceEventsReconnect } from '@/client/runtime/useWorkspaceEvents'
 
@@ -14,7 +15,7 @@ import { requestJson } from './http'
 
 const DEFAULTS: ClientAppConfig = {
   cloudDemo: false,
-  experiments: [],
+  experimental: { ...EXPERIMENTAL_DEFAULTS },
   demoInstallUrl: 'https://moi.computer'
 }
 
@@ -30,20 +31,22 @@ function subscribe(listener: () => void): () => void {
 
 // Failures keep the last known value (defaults on the very first fetch):
 // non-demo is the safe presentation, and the server still enforces its gates.
-async function fetchAppConfig(): Promise<void> {
+async function fetchAppConfig(): Promise<ClientAppConfig | undefined> {
   try {
     current = await requestJson<ClientAppConfig>('/api/config')
     for (const listener of listeners) listener()
+    return current
   } catch {}
 }
 
 // Called once from init() before the app mounts; never rejects, so a config
 // hiccup cannot block the app from starting.
-export async function loadAppConfig(): Promise<void> {
-  await fetchAppConfig()
+export async function loadAppConfig(): Promise<ClientAppConfig | undefined> {
+  const config = await fetchAppConfig()
   onWorkspaceEventsReconnect(() => {
     void fetchAppConfig()
   })
+  return config
 }
 
 export function useAppConfig(): ClientAppConfig {

client/app/routes/WorkspaceRoute.tsx

@@ -1,6 +1,8 @@
+import { CollabProvider, useCollabEnabled } from '@/client/features/collab'
 import { useQueryClient } from '@tanstack/react-query'
 
 import { workspaceKeys } from '@/client/api/workspace-keys'
+import { useAppConfig } from '@/client/api/app-config'
 import { LedLogo } from '@/client/components/shared/LedLogo'
 import { SidebarLayout } from '@/client/app/shell/SidebarLayout'
 import { useSelectedSession } from '@/client/features/chat/sessions/useSelectedSession'
@@ -19,19 +21,24 @@ type WorkspaceRouteProps = {
   id: string
 }
 
-// The URL's tab segment is not threaded down — useWorkspaceNavigation reads it
-// off the matched route with wouter's `useParams`.
+// Navigation reads the raw browser address so encoded paths and query params
+// are decoded exactly once; the route only owns the workspace ID.
 export function WorkspaceRoute({ id }: WorkspaceRouteProps) {
+  const { experimental } = useAppConfig()
+
   return (
     <Workspace id={id}>
       <WorkspaceLayoutProvider id={id}>
-        <WorkspaceLoader id={id} />
+        <CollabProvider workspaceId={id} enabled={experimental.collab}>
+          <WorkspaceContent id={id} />
+        </CollabProvider>
       </WorkspaceLayoutProvider>
     </Workspace>
   )
 }
 
-function WorkspaceLoader({ id }: WorkspaceRouteProps) {
+function WorkspaceContent({ id }: WorkspaceRouteProps) {
+  const collabEnabled = useCollabEnabled()
   const queryClient = useQueryClient()
   const [selectedSessionId] = useSelectedSession()
   const { isLoading: layoutLoading } = useWorkspaceLayoutCtx()
@@ -62,20 +69,21 @@ function WorkspaceLoader({ id }: WorkspaceRouteProps) {
     builders.isLoading
 
   return (
-    <>
-      <SidebarLayout>
-        {fresh ? (
-          <div className="flex h-full items-center justify-center">
-            <LedLogo sprite="moi" effect="chaos" />
-          </div>
-        ) : (
-          <WorkspaceScreen
-            widgets={widgets.data}
-            views={views.data ?? []}
-            builders={builders.data ?? []}
-          />
-        )}
-      </SidebarLayout>
-    </>
+    <SidebarLayout>
+      {fresh ? (
+        <div className="flex h-full items-center justify-center">
+          <LedLogo sprite="moi" effect="chaos" />
+        </div>
+      ) : (
+        // Browser tab state is read when the screen mounts. Reset the screen
+        // when it switches between shared workspace tabs and browser tab state.
+        <WorkspaceScreen
+          key={collabEnabled ? 'browser-tab' : 'shared'}
+          widgets={widgets.data}
+          views={views.data ?? []}
+          builders={builders.data ?? []}
+        />
+      )}
+    </SidebarLayout>
   )
 }

client/features/applets/AppletMount.tsx → client/features/applets/AppletContainer.tsx

@@ -1,11 +1,12 @@
 import { type ReactNode } from 'react'
 
+import { AppletPresenceProvider } from '@/client/features/collab'
 import { useWorkspaceId } from '@/client/features/workspace/WorkspaceContext'
 
-import { type AppletSegment, appletScope, appletStyleKey } from './applet-cache'
+import { type AppletSegment, appletId, appletStyleKey } from './applet-cache'
 import { useAppletStyle } from './applet-styles'
 
-type AppletMountProps = {
+type AppletContainerProps = {
   segment: AppletSegment
   name: string
   version: number
@@ -19,13 +20,14 @@ type AppletMountProps = {
 // page. This is the widget path. Views don't use it: ViewManager parks a view's
 // DOM offscreen instead of unmounting it, so it holds the styles itself, above
 // the boundary that hides the view.
-export function AppletMount({ segment, name, version, children }: AppletMountProps) {
+export function AppletContainer({ segment, name, version, children }: AppletContainerProps) {
   const workspaceId = useWorkspaceId()
+  const id = appletId(segment, name)
   useAppletStyle(appletStyleKey(segment, workspaceId, name), version)
 
   return (
-    <div data-applet={appletScope(segment, name)} className="size-full">
-      {children}
+    <div data-applet={id} className="size-full">
+      <AppletPresenceProvider appletId={id}>{children}</AppletPresenceProvider>
     </div>
   )
 }

client/features/applets/WidgetShell.tsx

@@ -1,6 +1,6 @@
 import { AnimatePresence, motion } from 'motion/react'
 
-import { AppletMount } from '@/client/features/applets/AppletMount'
+import { AppletContainer } from '@/client/features/applets/AppletContainer'
 import { useWidget } from '@/client/features/applets/useApplet'
 import { useWorkspaceId } from '@/client/features/workspace/WorkspaceContext'
 
@@ -31,9 +31,9 @@ export function WidgetShell({ name }: WidgetShellProps) {
             workspaceId={workspaceId}
             resetKey={widget.version}
           >
-            <AppletMount segment="widgets" name={name} version={widget.version}>
+            <AppletContainer segment="widgets" name={name} version={widget.version}>
               <widget.Component />
-            </AppletMount>
+            </AppletContainer>
           </WidgetErrorBoundary>
         </motion.div>
       )}

client/features/applets/applet-cache.ts

@@ -54,11 +54,9 @@ export function appletStyleKey(segment: AppletSegment, workspaceId: string, name
   return `/api/workspaces/${workspaceId}/${segment}/${name}`
 }
 
-// The `data-applet` value the bundle's scoped CSS selectors key off (see
-// server/applets/applet-css.ts). It goes on the container wrapping a mounted
-// applet — AppletMount for widgets, the view slot for views.
-export function appletScope(segment: AppletSegment, name: string): string {
-  return `${segment === 'widgets' ? 'widget' : 'view'}:${name}`
+// Stable applet identity used by scoped CSS, presence, and thumbnail capture.
+export function appletId(segment: AppletSegment, name: string): string {
+  return `${segment}/${name}`
 }
 
 export function getCachedApplet(key: string): Promise<unknown> | undefined {

client/features/applets/applet-runtime.test.ts

@@ -1,6 +1,7 @@
 import * as appletLog from './applet-log'
 import { describe, expect, test, spyOn } from 'bun:test'
 import { toast } from '@/client/components/ui/toast'
+import type { AppletBridge } from '@/lib/types'
 
 import {
   appletKey,
@@ -9,7 +10,6 @@ import {
   setCachedApplet
 } from './applet-cache'
 import {
-  type AppletBridge,
   type AppletChatMessage,
   type AppletIdentity,
   appletRuntime,
@@ -45,27 +45,39 @@ describe('bridge validation', () => {
     const log = spyOn(appletLog, 'reportAppletError').mockImplementation(() => {})
     bridge.navigate('moi:/views/orders?order=o-1')
     bridge.navigate('moi:/overview')
+    bridge.navigate('moi:/files/clips/video.mp4#t=5')
     bridge.navigate(['invalid'])
     bridge.navigate('javascript:alert(1)')
-    expect(calls).toEqual(['moi:/views/orders?order=o-1', 'moi:/overview'])
-    expect(log).toHaveBeenCalledTimes(2)
+    bridge.navigate('moi:/files/clips/%2Fvideo.mp4')
+    expect(calls).toEqual([
+      'moi:/views/orders?order=o-1',
+      'moi:/overview',
+      'moi:/files/clips/video.mp4#t=5'
+    ])
+    expect(log).toHaveBeenCalledTimes(3)
     log.mockRestore()
   })
 
   test('resolves native anchor hrefs in the source workspace and disposes safely', () => {
     const { bridge, dispose } = appletRuntime('ws-1').connect(VIEW)
-    expect(bridge.resolveHref('moi:/views/orders?order=o-1')).toBe(
+    expect(bridge.resolveUrl('moi:/views/orders?order=o-1')).toBe(
       '/workspace/ws-1/views/orders?order=o-1'
     )
-    expect(bridge.resolveHref('https://example.com/')).toBe('https://example.com/')
-    expect(() => bridge.resolveHref('javascript:alert(1)')).toThrow()
+    expect(bridge.resolveUrl('https://example.com/')).toBe('https://example.com/')
+    expect(bridge.resolveUrl('moi:/files/clips/a%20b.mp4')).toBe(
+      '/api/workspaces/ws-1/files/clips/a%20b.mp4'
+    )
+    expect(() => bridge.resolveUrl('javascript:alert(1)')).toThrow()
     dispose()
-    expect(bridge.resolveHref('moi:/overview')).toBe('')
+    expect(bridge.resolveUrl('moi:/overview')).toBe('')
   })
 
   test('resolves applet links with the host router base', () => {
     const { bridge } = appletRuntime('prefixed').connect(VIEW, '/prefix')
-    expect(bridge.resolveHref('moi:/views/orders')).toBe('/prefix/workspace/prefixed/views/orders')
+    expect(bridge.resolveUrl('moi:/views/orders')).toBe('/prefix/workspace/prefixed/views/orders')
+    expect(bridge.resolveUrl('moi:/files/photo.png')).toBe(
+      '/api/workspaces/prefixed/files/photo.png'
+    )
   })
 
   test('drops calls with malformed addresses instead of emitting', () => {
@@ -334,6 +346,22 @@ describe('sendChatMessage rate limiting', () => {
 })
 
 describe('disposal', () => {
+  test('collaboration shares the host API and is revoked with its connection', () => {
+    const runtime = appletRuntime(`ws-${crypto.randomUUID()}`)
+    const view = runtime.connect(VIEW)
+    const widget = runtime.connect(WIDGET)
+    const api = view.bridge.collab
+
+    expect(typeof api?.usePeers).toBe('function')
+    expect(typeof api?.useWorkspaceUsers).toBe('function')
+    expect(widget.bridge.collab).toBe(api)
+
+    view.dispose()
+    expect(view.bridge.collab).toBeUndefined()
+    expect(widget.bridge.collab).toBe(api)
+    widget.dispose()
+  })
+
   test('a disposed connection is inert even while subscribers are live', () => {
     const ws = `ws-${crypto.randomUUID()}`
     const { calls } = subscribeNavigation(ws)