@tldiagram/core-ui 1.95.1 → 2.0.0

package/src/components/WorkspacePanel.tsx

@@ -0,0 +1,938 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { useLocation, useNavigate } from 'react-router-dom'
+import { useQueryClient } from '@tanstack/react-query'
+import {
+  Badge,
+  Box,
+  Button,
+  Collapse,
+  HStack,
+  IconButton,
+  Menu,
+  MenuButton,
+  MenuList,
+  MenuItem,
+  Popover,
+  PopoverBody,
+  PopoverContent,
+  PopoverTrigger,
+  Portal,
+  Text,
+  Tooltip,
+  VStack,
+} from '@chakra-ui/react'
+import { ChevronDownIcon, ChevronLeftIcon, ChevronRightIcon, ChevronUpIcon, CloseIcon, RepeatIcon, TimeIcon, ViewIcon, ViewOffIcon } from '@chakra-ui/icons'
+import {
+  api,
+  type WatchDiff,
+  type WatchEvent,
+  type WatchLock,
+  type WatchRepresentationSummary,
+  type WatchRepository,
+  type WatchVersion,
+  type WorkspaceVersion,
+} from '../api/client'
+import { buildWorkspaceVersionPreview, useWorkspaceVersionPreview } from '../context/WorkspaceVersionContext'
+import {
+  buildWatchDiffLocations,
+  summarizeWatchDiffs,
+  type WatchDiffLocation,
+  type WatchDiffSummary,
+} from '../utils/watchDiffSummary'
+
+export const WATCH_REPRESENTATION_UPDATED_EVENT = 'tld:watch-representation-updated'
+
+// ─── Watch helpers ────────────────────────────────────────────────────────────
+
+type WatchLine = {
+  id: number
+  at: string
+  text: string
+  tone: 'info' | 'success' | 'warning' | 'error'
+}
+
+function PauseGlyph() {
+  return (
+    <svg width="12" height="12" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+      <rect x="6" y="5" width="4" height="14" rx="1" />
+      <rect x="14" y="5" width="4" height="14" rx="1" />
+    </svg>
+  )
+}
+
+function summarizeEvent(event: WatchEvent): WatchLine | null {
+  const id = Date.now() + Math.random()
+  const at = event.at || new Date().toISOString()
+  const type = event.type
+  if (type === 'watch.heartbeat') return null
+  if (type === 'watch.connected') return { id, at, text: 'Watch stream connected', tone: 'success' }
+  if (type === 'watch.paused') return { id, at, text: 'Watch paused', tone: 'warning' }
+  if (type === 'watch.stopped') return { id, at, text: 'Watch stopped', tone: 'warning' }
+  if (type === 'watch.error') return { id, at, text: event.message || 'Watch error', tone: 'error' }
+  if (type === 'lock.disabled') return null
+  if (type === 'lock.enabled') return { id, at, text: 'Workspace locked for watch updates', tone: 'info' }
+  if (type === 'version.created') return null
+  if (type === 'representation.updated') {
+    const data = event.data as Partial<WatchRepresentationSummary> | undefined
+    const changed = [
+      data?.views_created ? `views +${data.views_created}` : '',
+      data?.elements_created || data?.elements_updated ? `elements +${data.elements_created ?? 0}/${data.elements_updated ?? 0}` : '',
+      data?.connectors_created || data?.connectors_updated ? `connectors +${data.connectors_created ?? 0}/${data.connectors_updated ?? 0}` : '',
+    ].filter(Boolean).join(', ')
+    return { id, at, text: changed ? `Workspace updated: ${changed}` : 'Workspace refreshed', tone: 'success' }
+  }
+  if (type === 'scan.started') {
+    const files = event.changed_files ? ` · ${event.changed_files} files` : ''
+    return { id, at, text: `Scanning${files}`, tone: 'info' }
+  }
+  if (type === 'scan.completed') {
+    const warnings = event.warnings?.length ? ` · ${event.warnings[0]}` : ''
+    return { id, at, text: `Scan complete${warnings}`, tone: event.warnings?.length ? 'warning' : 'success' }
+  }
+  if (type === 'source.changed') {
+    const data = event.data as { change?: { path?: string; change_type?: string }; representation_changed?: boolean } | undefined
+    const path = data?.change?.path ?? 'source file'
+    const suffix = data?.representation_changed ? 'changed the diagram' : 'did not change the diagram'
+    return { id, at, text: `${path} ${suffix}`, tone: data?.representation_changed ? 'success' : 'info' }
+  }
+  return { id, at, text: type, tone: 'info' }
+}
+
+function shortPath(path: string | undefined): string {
+  if (!path) return 'repository'
+  const parts = path.split(/[/\\]/).filter(Boolean)
+  return parts.slice(-2).join('/') || path
+}
+
+function versionLabel(version: WatchVersion) {
+  const subject = version.commit_message?.trim()
+  return subject || `Version ${new Date(version.created_at).toLocaleTimeString()}`
+}
+
+function normalizeDiffs(value: WatchDiff[] | null | undefined): WatchDiff[] {
+  return Array.isArray(value) ? value : []
+}
+
+function mergeRepositoryOption(repos: WatchRepository[], repo: WatchRepository | null | undefined): WatchRepository[] {
+  if (!repo) return repos
+  const existing = repos.find((item) => item.id === repo.id)
+  if (existing) {
+    return repos.map((item) => item.id === repo.id ? { ...item, ...repo } : item)
+  }
+  return [repo, ...repos]
+}
+
+function ResourceCountDisplay({ summary }: { summary: WatchDiffSummary }) {
+  const rows = [
+    { label: 'Elements', stat: summary.elements },
+    { label: 'Connectors', stat: summary.connectors },
+  ]
+  const total = rows.reduce((sum, row) => (
+    sum + row.stat.added + row.stat.updated + row.stat.deleted + row.stat.initialized
+  ), 0)
+  const changes = [
+    { key: 'added', label: 'added', color: 'green.300' },
+    { key: 'updated', label: 'updated', color: 'yellow.300' },
+    { key: 'deleted', label: 'deleted', color: 'red.300' },
+    { key: 'initialized', label: 'initialized', color: 'blue.300' },
+  ] as const
+
+  return (
+    <Box
+      px={4}
+      py={3}
+      border="1px solid"
+      borderColor="whiteAlpha.100"
+      borderRadius="md"
+      bg="whiteAlpha.50"
+    >
+      <HStack justify="space-between" mb={2} spacing={3}>
+        <Text fontSize="12px" color="gray.400" fontWeight="700" textTransform="uppercase">
+          Diagram resources
+        </Text>
+        <Text fontSize="11px" color="gray.500">{total} total</Text>
+      </HStack>
+      <VStack align="stretch" spacing={1.5}>
+        {rows.map((row) => (
+          <HStack key={row.label} spacing={2} minW={0} justify="space-between">
+            <Text fontSize="12px" color="gray.300" fontWeight="600" minW="76px">{row.label}</Text>
+            <HStack spacing={2} justify="flex-end" flexWrap="wrap">
+              {changes.map((change) => {
+                const count = row.stat[change.key]
+                return count > 0 ? (
+                  <Text key={change.key} fontSize="11px" color={change.color} fontFamily="mono">
+                    {count} {change.label}
+                  </Text>
+                ) : null
+              })}
+              {row.stat.added + row.stat.updated + row.stat.deleted + row.stat.initialized === 0 && (
+                <Text fontSize="11px" color="gray.600" fontFamily="mono">none</Text>
+              )}
+            </HStack>
+          </HStack>
+        ))}
+      </VStack>
+    </Box>
+  )
+}
+
+// ─── Themed dropdown ──────────────────────────────────────────────────────────
+
+interface ThemedSelectProps<T extends string | number> {
+  value: T | ''
+  options: { value: T; label: string }[]
+  placeholder?: string
+  onChange: (value: T | '') => void
+  isDisabled?: boolean
+  flex?: number
+}
+
+function ThemedSelect<T extends string | number>({ value, options, placeholder, onChange, isDisabled, flex }: ThemedSelectProps<T>) {
+  const selected = options.find((o) => o.value === value)
+  return (
+    <Menu placement="bottom-start" strategy="fixed">
+      <MenuButton
+        as={Button}
+        rightIcon={<ChevronDownIcon />}
+        size="sm"
+        variant="ghost"
+        isDisabled={isDisabled}
+        flex={flex}
+        minW={0}
+        h="32px"
+        px={3}
+        fontSize="13px"
+        fontWeight="500"
+        color={selected ? 'gray.100' : 'gray.500'}
+        bg="whiteAlpha.50"
+        border="1px solid"
+        borderColor="whiteAlpha.100"
+        borderRadius="md"
+        _hover={{ bg: 'whiteAlpha.100', borderColor: 'whiteAlpha.200' }}
+        _active={{ bg: 'whiteAlpha.150' }}
+        textAlign="left"
+        justifyContent="flex-start"
+        overflow="hidden"
+        sx={{ '> span:first-of-type': { overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' } }}
+      >
+        {selected?.label ?? placeholder ?? '—'}
+      </MenuButton>
+      <Portal>
+        <MenuList
+          data-zui-native-wheel="true"
+          bg="rgba(var(--bg-main-rgb), 0.98)"
+          border="1px solid"
+          borderColor="whiteAlpha.200"
+          borderRadius="lg"
+          boxShadow="0 12px 32px rgba(0,0,0,0.5)"
+          backdropFilter="blur(18px)"
+          minW="200px"
+          maxH="240px"
+          overflowY="auto"
+          zIndex={2000}
+          py={1}
+          sx={{ overscrollBehavior: 'contain', WebkitOverflowScrolling: 'touch', touchAction: 'pan-y' }}
+        >
+          {options.length === 0 && (
+            <MenuItem isDisabled fontSize="13px" color="gray.500" bg="transparent">No options</MenuItem>
+          )}
+          {options.map((opt) => (
+            <MenuItem
+              key={String(opt.value)}
+              fontSize="13px"
+              color={opt.value === value ? 'var(--accent)' : 'gray.200'}
+              fontWeight={opt.value === value ? '600' : '400'}
+              bg="transparent"
+              _hover={{ bg: 'whiteAlpha.100' }}
+              _focus={{ bg: 'whiteAlpha.100' }}
+              py={2}
+              px={3}
+              onClick={() => onChange(opt.value)}
+            >
+              {opt.label}
+            </MenuItem>
+          ))}
+        </MenuList>
+      </Portal>
+    </Menu>
+  )
+}
+
+// ─── Main combined panel ──────────────────────────────────────────────────────
+
+export default function WorkspacePanel() {
+  const navigate = useNavigate()
+  const location = useLocation()
+  const queryClient = useQueryClient()
+
+  // ── Version state ─────────────────────────────────────────────────────────
+  const { preview, setPreview, clearPreview, requestFollow } = useWorkspaceVersionPreview()
+  const [versionsOpen, setVersionsOpen] = useState(false)
+  const [diffVisible, setDiffVisible] = useState(false)
+  const [repos, setRepos] = useState<WatchRepository[]>([])
+  const [versions, setVersions] = useState<WatchVersion[]>([])
+  const [workspaceVersions, setWorkspaceVersions] = useState<WorkspaceVersion[]>([])
+  const [repoId, setRepoId] = useState<number | ''>('')
+  const [versionId, setVersionId] = useState<number | ''>('')
+  const [diffs, setDiffs] = useState<WatchDiff[]>([])
+  const [diffLocations, setDiffLocations] = useState<WatchDiffLocation[]>([])
+  const [activeDiffLocationKey, setActiveDiffLocationKey] = useState<string | null>(null)
+  const [watchActive, setWatchActive] = useState(false)
+  const [watchPaused, setWatchPaused] = useState(false)
+  const [watchRepository, setWatchRepository] = useState<WatchRepository | null>(null)
+  const [watchLock, setWatchLock] = useState<WatchLock | null>(null)
+  const [watchConnected, setWatchConnected] = useState(false)
+  const [watcherMode, setWatcherMode] = useState('')
+  const [languages, setLanguages] = useState<string[]>([])
+  const [watchLines, setWatchLines] = useState<WatchLine[]>([])
+  const [runtimeOpen, setRuntimeOpen] = useState(true)
+
+  const repoOptions = useMemo(() => mergeRepositoryOption(repos, watchRepository), [repos, watchRepository])
+  const selectedRepo = useMemo(() => {
+    const selected = repoOptions.find((r) => r.id === repoId)
+    if (selected) return selected
+    if (!repoId || watchRepository?.id === repoId) return watchRepository ?? null
+    return null
+  }, [repoOptions, repoId, watchRepository])
+  const selectedVersion = useMemo(() => versions.find((v) => v.id === versionId) ?? null, [versions, versionId])
+
+  const selectLatestWatchVersion = useCallback(async (targetRepoId: number) => {
+    const nextVersions = await api.watch.versions(targetRepoId)
+    setVersions(nextVersions)
+    const latest = nextVersions[0] ?? null
+    setVersionId(latest?.id ?? '')
+    if (!latest) {
+      setDiffs([])
+      return
+    }
+    const latestDiffs = await api.watch.diffs(latest.id).catch(() => [] as WatchDiff[])
+    setDiffs(normalizeDiffs(latestDiffs))
+  }, [])
+
+  const loadVersions = useCallback(async () => {
+    const [nextRepos, nextWsVersions] = await Promise.all([
+      api.watch.repositories().catch(() => [] as WatchRepository[]),
+      api.versions.list(50).catch(() => [] as WorkspaceVersion[]),
+    ])
+    const mergedRepos = mergeRepositoryOption(nextRepos, watchRepository)
+    setRepos(mergedRepos)
+    setWorkspaceVersions(nextWsVersions)
+    const nextRepoId = repoId || watchRepository?.id || mergedRepos[0]?.id || ''
+    setRepoId(nextRepoId)
+    if (nextRepoId) {
+      const nextVersions = await api.watch.versions(nextRepoId)
+      setVersions(nextVersions)
+      setVersionId(versionId || nextVersions[0]?.id || '')
+    }
+  }, [repoId, versionId, watchRepository])
+
+  useEffect(() => {
+    if (!versionsOpen && !preview) return
+    void loadVersions()
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [versionsOpen])
+
+  useEffect(() => {
+    if (!repoId) { setVersions([]); setVersionId(''); return }
+    api.watch.versions(repoId).then((next) => {
+      setVersions(next)
+      setVersionId(next[0]?.id ?? '')
+    }).catch(() => { setVersions([]); setVersionId('') })
+  }, [repoId])
+
+  useEffect(() => {
+    if (!versionId) { setDiffs([]); return }
+    api.watch.diffs(versionId).then((next) => setDiffs(normalizeDiffs(next))).catch(() => setDiffs([]))
+  }, [versionId])
+
+  useEffect(() => {
+    if (!diffs.length) {
+      setDiffLocations([])
+      return
+    }
+    let cancelled = false
+    api.explore.load().then((data) => {
+      if (!cancelled) setDiffLocations(buildWatchDiffLocations(data, diffs))
+    }).catch(() => {
+      if (!cancelled) setDiffLocations([])
+    })
+    return () => { cancelled = true }
+  }, [diffs])
+
+  const displayedDiffLocations = useMemo(() => diffLocations.slice(0, 24), [diffLocations])
+  const navigableDiffLocations = useMemo(() => {
+    const elementLocations = diffLocations.filter((target) => target.resourceType === 'element')
+    return elementLocations.length > 0 ? elementLocations : diffLocations
+  }, [diffLocations])
+  const activeDiffLocationIndex = useMemo(() => {
+    if (!activeDiffLocationKey) return -1
+    const index = navigableDiffLocations.findIndex((target) => target.key === activeDiffLocationKey)
+    return index >= 0 ? index : -1
+  }, [activeDiffLocationKey, navigableDiffLocations])
+
+  useEffect(() => {
+    if (!selectedVersion || !diffVisible) {
+      clearPreview()
+      return
+    }
+    setPreview(buildWorkspaceVersionPreview({ repository: selectedRepo, version: selectedVersion, workspaceVersions, diffs }))
+  }, [clearPreview, diffVisible, diffs, selectedRepo, selectedVersion, setPreview, workspaceVersions])
+
+  const navigateToDiffLocation = useCallback((target: WatchDiffLocation) => {
+    setActiveDiffLocationKey(target.key)
+    requestFollow({
+      resourceType: target.resourceType,
+      resourceId: target.resourceId,
+      viewId: target.viewId,
+      changeType: target.changeType,
+    })
+    if (location.pathname === '/dependencies' && target.resourceType === 'element' && target.resourceId) {
+      navigate(`/dependencies?element=${target.resourceId}`)
+      return
+    }
+    if (location.pathname.startsWith('/views/') && !location.pathname.startsWith('/views?')) {
+      const elementQuery = target.resourceType === 'element' && target.resourceId ? `?element=${target.resourceId}` : ''
+      navigate(`/views/${target.viewId}${elementQuery}`)
+      return
+    }
+    const elementQuery = target.resourceType === 'element' && target.resourceId ? `&element=${target.resourceId}` : ''
+    navigate(`/views?view=explore&focus=${target.viewId}${elementQuery}`)
+  }, [location.pathname, navigate, requestFollow])
+
+  const navigateDiffLocationByOffset = useCallback((offset: number) => {
+    if (navigableDiffLocations.length === 0) return
+    const nextIndex = activeDiffLocationIndex < 0
+      ? offset > 0 ? 0 : navigableDiffLocations.length - 1
+      : (activeDiffLocationIndex + offset + navigableDiffLocations.length) % navigableDiffLocations.length
+    navigateToDiffLocation(navigableDiffLocations[nextIndex])
+  }, [activeDiffLocationIndex, navigableDiffLocations, navigateToDiffLocation])
+
+  const activeVersion = preview?.version ?? selectedVersion
+  const diffSummary = useMemo(() => summarizeWatchDiffs(diffs), [diffs])
+  const totalFileChanges = diffSummary.files.added + diffSummary.files.updated + diffSummary.files.deleted + diffSummary.files.initialized
+  const totalTldChanges = diffSummary.elements.added + diffSummary.elements.updated + diffSummary.elements.deleted + diffSummary.elements.initialized +
+    diffSummary.connectors.added + diffSummary.connectors.updated + diffSummary.connectors.deleted + diffSummary.connectors.initialized
+  const activeDiffLocation = activeDiffLocationIndex >= 0 ? navigableDiffLocations[activeDiffLocationIndex] : null
+  const headerAddedLines = activeDiffLocation?.addedLines ?? diffSummary.elements.addedLines + diffSummary.connectors.addedLines
+  const headerRemovedLines = activeDiffLocation?.removedLines ?? diffSummary.elements.removedLines + diffSummary.connectors.removedLines
+
+  // ── Watch state ───────────────────────────────────────────────────────────
+  const socketRef = useRef<WebSocket | null>(null)
+  const reconnectTimerRef = useRef<number | null>(null)
+  const reconnectAttemptRef = useRef(0)
+  const lastWatchMessageAtRef = useRef(0)
+  const socketHealthTimerRef = useRef<number | null>(null)
+  const lastRepresentationHashRef = useRef('')
+  const addLine = useCallback((line: WatchLine | null) => {
+    if (!line) return
+    setWatchLines((current) => {
+      if (current[0]?.text === line.text && current[0]?.tone === line.tone) return current
+      return [line, ...current].slice(0, 8)
+    })
+  }, [])
+
+  const refreshWorkspace = useCallback((event: WatchEvent) => {
+    const data = event.data as Partial<WatchRepresentationSummary> | undefined
+    const hash = data?.representation_hash ?? ''
+    if (hash && hash === lastRepresentationHashRef.current) return
+    if (hash) lastRepresentationHashRef.current = hash
+    void queryClient.invalidateQueries({ queryKey: ['workspace', 'views'] })
+    void queryClient.invalidateQueries({ queryKey: ['elements', 'list'] })
+    window.dispatchEvent(new CustomEvent(WATCH_REPRESENTATION_UPDATED_EVENT, { detail: event }))
+  }, [queryClient])
+
+  const handleEvent = useCallback((event: WatchEvent) => {
+    const eventLock = event.data && typeof event.data === 'object' && 'status' in event.data
+      ? event.data as WatchLock : null
+    if (event.repository_id) setWatchLock((current) => eventLock ?? current)
+    if (eventLock) setWatchPaused(eventLock.status === 'paused')
+    if (event.watcher_mode) setWatcherMode(event.watcher_mode)
+    if (event.languages?.length) setLanguages(event.languages)
+    if (event.type === 'watch.paused') setWatchPaused(true)
+    if (event.type === 'watch.heartbeat') {
+      setWatchActive(true)
+      if (eventLock) setWatchPaused(eventLock.status === 'paused')
+    }
+    if (event.type === 'watch.stopped') { setWatchActive(false); setWatchPaused(false) }
+    if (event.type === 'representation.updated') {
+      const data = event.data as Partial<WatchRepresentationSummary> | undefined
+      if ('diffs' in (data ?? {})) setDiffs(normalizeDiffs(data?.diffs))
+      refreshWorkspace(event)
+    }
+    if (event.type === 'version.created') {
+      const version = event.data as Partial<WatchVersion> | undefined
+      const targetRepoId = event.repository_id || version?.repository_id || watchLock?.repository_id || watchRepository?.id || 0
+      clearPreview()
+      setDiffs([])
+      if (targetRepoId > 0) {
+        setRepoId(targetRepoId)
+        void selectLatestWatchVersion(targetRepoId)
+      }
+    }
+    if (event.type !== 'watch.stopped' || watchActive) addLine(summarizeEvent(event))
+  }, [watchActive, addLine, clearPreview, refreshWorkspace, selectLatestWatchVersion, watchLock?.repository_id, watchRepository?.id])
+  const handleEventRef = useRef(handleEvent)
+
+  useEffect(() => {
+    handleEventRef.current = handleEvent
+  }, [handleEvent])
+
+  useEffect(() => {
+    let cancelled = false
+    const poll = async () => {
+      const status = await api.watch.status().catch(() => null)
+      if (!status || cancelled) return
+      setWatchActive(status.active)
+      setWatchRepository(status.repository ?? null)
+      setWatchLock(status.lock ?? null)
+      setWatchPaused(status.lock?.status === 'paused')
+      if (status.repository) {
+        setRepos((current) => mergeRepositoryOption(current, status.repository))
+        setRepoId((current) => current || status.repository?.id || '')
+      }
+    }
+    void poll()
+    const interval = window.setInterval(poll, 5000)
+    return () => { cancelled = true; window.clearInterval(interval) }
+  }, [])
+
+  useEffect(() => {
+    let disposed = false
+    const scheduleReconnect = () => {
+      if (disposed) return
+      const delay = Math.min(5000, 1000 * 2 ** Math.min(reconnectAttemptRef.current, 3))
+      reconnectAttemptRef.current += 1
+      reconnectTimerRef.current = window.setTimeout(connect, delay)
+    }
+    const connect = () => {
+      if (disposed) return
+      const socket = new WebSocket(api.watch.websocketUrl())
+      socketRef.current = socket
+      lastWatchMessageAtRef.current = Date.now()
+      socket.onopen = () => {
+        setWatchConnected(true)
+        reconnectAttemptRef.current = 0
+        lastWatchMessageAtRef.current = Date.now()
+        addLine({ id: Date.now() + Math.random(), at: new Date().toISOString(), text: 'Watch stream connected', tone: 'success' })
+        try { socket.send(JSON.stringify({ type: 'watch.status' })) } catch { /* ignore */ }
+      }
+      socket.onclose = () => {
+        setWatchConnected(false)
+        if (!disposed) {
+          addLine({ id: Date.now() + Math.random(), at: new Date().toISOString(), text: 'Watch stream reconnecting', tone: 'warning' })
+          scheduleReconnect()
+        }
+      }
+      socket.onerror = () => socket.close()
+      socket.onmessage = (msg) => {
+        lastWatchMessageAtRef.current = Date.now()
+        try { handleEventRef.current(JSON.parse(msg.data) as WatchEvent) } catch { /* ignore */ }
+      }
+    }
+    connect()
+    socketHealthTimerRef.current = window.setInterval(() => {
+      const socket = socketRef.current
+      if (socket?.readyState === WebSocket.OPEN && Date.now() - lastWatchMessageAtRef.current > 10000) {
+        socket.close()
+      }
+    }, 5000)
+    return () => {
+      disposed = true
+      if (reconnectTimerRef.current !== null) window.clearTimeout(reconnectTimerRef.current)
+      if (socketHealthTimerRef.current !== null) window.clearInterval(socketHealthTimerRef.current)
+      socketRef.current?.close()
+      socketRef.current = null
+    }
+  }, [addLine])
+
+  const sendControl = useCallback((type: 'watch.pause' | 'watch.resume' | 'watch.stop') => {
+    const socket = socketRef.current
+    if (!socket || socket.readyState !== WebSocket.OPEN) return
+    socket.send(JSON.stringify({ type, repository_id: watchLock?.repository_id ?? watchRepository?.id ?? 0 }))
+    if (type === 'watch.pause') setWatchPaused(true)
+    if (type === 'watch.resume') setWatchPaused(false)
+    if (type === 'watch.stop') setWatchActive(false)
+  }, [watchLock?.repository_id, watchRepository?.id])
+
+  const watchStatusColor = !watchActive ? 'gray' : watchPaused ? 'yellow' : watchConnected ? 'green' : 'orange'
+  const watchStatusLabel = !watchActive ? 'Stopped' : watchPaused ? 'Paused' : 'Live'
+  const watchTitle = useMemo(() => shortPath(watchRepository?.repo_root), [watchRepository?.repo_root])
+  const watchMode = [watcherMode || (watchConnected ? 'live' : 'connecting'), languages.length ? languages.join(', ') : ''].filter(Boolean).join(' · ')
+  const triggerLabel = watchActive ? `${watchStatusLabel}: ${watchTitle}` : 'Workspace versions'
+
+  const showRuntimeSection = watchActive || watchLines.length > 0
+
+  // ── Render ────────────────────────────────────────────────────────────────
+  return (
+    <Popover placement="bottom-end" isLazy>
+      <Tooltip label={triggerLabel} placement="bottom" openDelay={400}>
+        <Box>
+          <PopoverTrigger>
+            {watchActive ? (
+              <Button
+                aria-label="Workspace watch panel"
+                size="sm"
+                h="34px"
+                minW={0}
+                px={2.5}
+                gap={2}
+                borderRadius="full"
+                bg="whiteAlpha.100"
+                color="whiteAlpha.900"
+                border="1px solid"
+                borderColor={watchStatusColor === 'green' ? 'green.400' : watchStatusColor === 'yellow' ? 'yellow.400' : 'orange.300'}
+                boxShadow={watchStatusColor === 'green' ? '0 0 18px rgba(72,187,120,0.28)' : '0 6px 18px rgba(0,0,0,0.32)'}
+                _hover={{ bg: 'whiteAlpha.200', transform: 'translateY(-1px)' }}
+                _active={{ transform: 'translateY(0)' }}
+              >
+                <Badge
+                  bg={watchStatusColor === 'green' ? 'green.900' : watchStatusColor === 'yellow' ? 'yellow.900' : 'orange.900'}
+                  color={watchStatusColor === 'green' ? 'green.200' : watchStatusColor === 'yellow' ? 'yellow.200' : 'orange.100'}
+                  borderRadius="full"
+                  textTransform="none"
+                  fontSize="10px"
+                  px={1.5}
+                  py={0.5}
+                  flexShrink={0}
+                >
+                  {watchStatusLabel}
+                </Badge>
+                <Text
+                  as="span"
+                  maxW={{ base: '96px', lg: '160px' }}
+                  fontSize="12px"
+                  fontWeight="600"
+                  color="gray.100"
+                  noOfLines={1}
+                >
+                  {watchTitle}
+                </Text>
+                <ChevronDownIcon boxSize={4} color="whiteAlpha.700" />
+              </Button>
+            ) : (
+              <IconButton
+                aria-label="Workspace versions"
+                icon={<TimeIcon boxSize={4} />}
+                size="sm"
+                borderRadius="full"
+                bg={preview ? 'rgba(var(--accent-rgb), 0.22)' : 'whiteAlpha.100'}
+                color={preview ? 'var(--accent)' : 'whiteAlpha.700'}
+                border="1px solid"
+                borderColor={preview ? 'rgba(var(--accent-rgb), 0.45)' : 'whiteAlpha.100'}
+                _hover={{ bg: 'whiteAlpha.200', color: 'white', transform: 'translateY(-1px)' }}
+              />
+            )}
+          </PopoverTrigger>
+        </Box>
+      </Tooltip>
+      <Portal>
+        <PopoverContent
+          data-zui-native-wheel="true"
+          w={{ base: 'calc(100vw - 24px)', md: watchActive ? '460px' : '420px' }}
+          maxW="calc(100vw - 24px)"
+          mt={2}
+          mr={{ base: 2, sm: 0 }}
+          bg="rgba(var(--bg-main-rgb), 0.96)"
+          border="1px solid"
+          borderColor={preview ? 'rgba(var(--accent-rgb), 0.45)' : 'whiteAlpha.200'}
+          borderRadius="lg"
+          boxShadow="0 18px 48px rgba(0,0,0,0.45)"
+          backdropFilter="blur(18px)"
+          overflow="hidden"
+          zIndex={2100}
+          _focus={{ boxShadow: '0 18px 48px rgba(0,0,0,0.45)' }}
+          sx={{
+            overscrollBehavior: 'contain',
+            WebkitOverflowScrolling: 'touch',
+            touchAction: 'pan-y',
+          }}
+        >
+          <PopoverBody p={0}>
+        {/* ── Versions header ── */}
+        <VStack align="stretch" spacing={3} px={4} py={4}>
+          <HStack spacing={3} align="center">
+            <HStack flex={1} spacing={2} minW={0}>
+              <ThemedSelect<number>
+                value={repoId}
+                placeholder="Repository"
+                options={repoOptions.map((r) => ({ value: r.id, label: r.display_name || shortPath(r.repo_root) }))}
+                onChange={(v) => setRepoId(v)}
+                flex={1}
+              />
+              <ThemedSelect<number>
+                value={versionId}
+                placeholder="Branch"
+                options={versions.map((v) => ({
+                  value: v.id,
+                  label: `${v.branch || 'detached'} (${new Date(v.created_at).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })})`,
+                }))}
+                onChange={(v) => setVersionId(v)}
+                flex={1}
+              />
+            </HStack>
+            <HStack spacing={1}>
+              {activeVersion && (
+                <Tooltip label={diffVisible ? 'Hide diff' : 'Show diff'} placement="top">
+                  <IconButton
+                    aria-label="Toggle diff"
+                    icon={diffVisible ? <ViewOffIcon boxSize={3.5} /> : <ViewIcon boxSize={3.5} />}
+                    size="sm"
+                    variant="ghost"
+                    color={diffVisible ? 'var(--accent)' : 'whiteAlpha.700'}
+                    onClick={() => setDiffVisible((visible) => !visible)}
+                  />
+                </Tooltip>
+              )}
+              <Tooltip label={versionsOpen ? 'Collapse list' : 'Expand list'} placement="top">
+                <IconButton
+                  aria-label="Toggle list"
+                  icon={versionsOpen ? <ChevronDownIcon boxSize={4} /> : <ChevronUpIcon boxSize={4} />}
+                  size="sm"
+                  variant="ghost"
+                  color={versionsOpen ? 'var(--accent)' : 'whiteAlpha.700'}
+                  onClick={() => setVersionsOpen((v) => !v)}
+                />
+              </Tooltip>
+            </HStack>
+          </HStack>
+
+          <HStack
+            px={3}
+            py={2.5}
+            bg="whiteAlpha.50"
+            borderRadius="md"
+            border="1px solid"
+            borderColor="whiteAlpha.100"
+            justify="space-between"
+            align="center"
+          >
+            <HStack spacing={3} minW={0} flex={1}>
+              <Text fontSize="13px" color="green.400" fontWeight="700" fontFamily="mono">
+                +{headerAddedLines}
+              </Text>
+              <Text fontSize="13px" color="red.400" fontWeight="700" fontFamily="mono">
+                -{headerRemovedLines}
+              </Text>
+              <Text fontSize="12px" color="gray.400" fontWeight="500" noOfLines={1} flex={1}>
+                {activeDiffLocation
+                  ? `${activeDiffLocationIndex + 1} of ${navigableDiffLocations.length}: ${activeDiffLocation.label}`
+                  : `${totalTldChanges} changed elements`}
+              </Text>
+            </HStack>
+            <HStack spacing={1} flexShrink={0}>
+              <Tooltip label="Previous element" placement="top">
+                <IconButton
+                  aria-label="Previous"
+                  icon={<ChevronLeftIcon boxSize={5} />}
+                  size="sm"
+                  variant="solid"
+                  h="32px"
+                  w="32px"
+                  bg="whiteAlpha.200"
+                  _hover={{ bg: 'whiteAlpha.300' }}
+                  _active={{ bg: 'whiteAlpha.400' }}
+                  isDisabled={navigableDiffLocations.length === 0}
+                  onClick={() => navigateDiffLocationByOffset(-1)}
+                />
+              </Tooltip>
+              <Tooltip label="Next element" placement="top">
+                <IconButton
+                  aria-label="Next"
+                  icon={<ChevronRightIcon boxSize={5} />}
+                  size="sm"
+                  variant="solid"
+                  h="32px"
+                  w="32px"
+                  bg="whiteAlpha.200"
+                  _hover={{ bg: 'whiteAlpha.300' }}
+                  _active={{ bg: 'whiteAlpha.400' }}
+                  isDisabled={navigableDiffLocations.length === 0}
+                  onClick={() => navigateDiffLocationByOffset(1)}
+                />
+              </Tooltip>
+            </HStack>
+          </HStack>
+        </VStack>
+
+        {/* ── Versions body ── */}
+        <Collapse in={versionsOpen} animateOpacity>
+          <VStack align="stretch" spacing={3} px={4} pb={4} borderTop="1px solid" borderColor="whiteAlpha.100">
+            <Box
+              mt={3}
+              px={4}
+              py={3}
+              border="1px solid"
+              borderColor="whiteAlpha.100"
+              borderRadius="md"
+              bg="whiteAlpha.50"
+            >
+              <Text fontSize="13px" color="gray.400" noOfLines={1} mb={2} fontWeight="500">
+                {activeVersion ? versionLabel(activeVersion) : 'Repository snapshot'}
+              </Text>
+              <HStack spacing={2} fontFamily="mono" fontSize="13px" minW={0} align="center">
+                <Text color="gray.300" fontWeight="500">
+                  {totalFileChanges} files
+                </Text>
+                <Text color="green.400">+{diffSummary.files.addedLines}</Text>
+                <Text color="red.400">-{diffSummary.files.removedLines}</Text>
+                <Text color="gray.500" ml="auto" fontSize="11px">{workspaceVersions.length} snapshots</Text>
+              </HStack>
+            </Box>
+
+            <ResourceCountDisplay summary={diffSummary} />
+
+            {displayedDiffLocations.length > 0 && (
+              <VStack
+                data-zui-native-wheel="true"
+                align="stretch"
+                spacing={1}
+                maxH="180px"
+                overflowY="auto"
+                borderTop="1px solid"
+                borderColor="whiteAlpha.100"
+                pt={3}
+                sx={{ overscrollBehavior: 'contain', WebkitOverflowScrolling: 'touch', touchAction: 'pan-y' }}
+              >
+                {displayedDiffLocations.map((target) => (
+                  <Button
+                    key={target.key}
+                    variant="ghost"
+                    size="sm"
+                    h="auto"
+                    minH="32px"
+                    justifyContent="flex-start"
+                    px={3}
+                    py={1.5}
+                    fontSize="12px"
+                    color={activeDiffLocationKey === target.key ? 'white' : 'gray.200'}
+                    bg={activeDiffLocationKey === target.key ? 'whiteAlpha.100' : 'transparent'}
+                    onClick={() => navigateToDiffLocation(target)}
+                  >
+                    <HStack w="full" spacing={3} minW={0}>
+                      <Badge
+                        colorScheme={target.changeType === 'added' ? 'green' : target.changeType === 'deleted' ? 'red' : 'yellow'}
+                        fontSize="9px"
+                      >
+                        {target.resourceType}
+                      </Badge>
+                      <Box minW={0} flex={1} textAlign="left">
+                        <Text noOfLines={1}>{target.summary || target.label}</Text>
+                        <Text color="gray.500" noOfLines={1}>{target.viewName}</Text>
+                      </Box>
+                      {(target.addedLines > 0 || target.removedLines > 0) && (
+                        <HStack spacing={1.5} flexShrink={0}>
+                          {target.addedLines > 0 && <Text color="green.400">+{target.addedLines}</Text>}
+                          {target.removedLines > 0 && <Text color="red.400">-{target.removedLines}</Text>}
+                        </HStack>
+                      )}
+                    </HStack>
+                  </Button>
+                ))}
+              </VStack>
+            )}
+          </VStack>
+        </Collapse>
+
+        {/* ── Runtime section (collapsible) ── */}
+        {showRuntimeSection && (
+          <Box borderTop="1px solid" borderColor="whiteAlpha.100">
+            <HStack
+              px={4}
+              py={3}
+              justify="space-between"
+              cursor="pointer"
+              onClick={() => setRuntimeOpen((v) => !v)}
+              _hover={{ bg: 'whiteAlpha.50' }}
+              transition="background 0.15s"
+            >
+              <HStack spacing={3} minW={0} flex={1}>
+                <Badge
+                  bg={watchStatusColor === 'green' ? 'green.900' : 'whiteAlpha.200'}
+                  color={watchStatusColor === 'green' ? 'green.200' : 'white'}
+                  borderRadius="sm"
+                  textTransform="none"
+                  fontSize="10px"
+                  px={1.5}
+                  py={0.5}
+                >
+                  {watchStatusLabel.toUpperCase()}
+                </Badge>
+                <Text fontSize="13px" fontWeight="500" color="gray.300" noOfLines={1}>{watchTitle}</Text>
+                {watchMode ? <Text fontSize="12px" color="gray.500" noOfLines={1}>{watchMode}</Text> : null}
+              </HStack>
+              <HStack spacing={1} onClick={(e) => e.stopPropagation()}>
+                {watchActive && (
+                  <>
+                    <Tooltip label={watchPaused ? 'Resume watch' : 'Pause watch'} placement="top">
+                      <IconButton
+                        aria-label={watchPaused ? 'Resume watch' : 'Pause watch'}
+                        icon={watchPaused ? <RepeatIcon boxSize={3.5} /> : <PauseGlyph />}
+                        size="sm"
+                        variant="ghost"
+                        color="gray.400"
+                        _hover={{ color: 'white', bg: 'whiteAlpha.100' }}
+                        onClick={() => sendControl(watchPaused ? 'watch.resume' : 'watch.pause')}
+                      />
+                    </Tooltip>
+                    <Tooltip label="Stop watch" placement="top">
+                      <IconButton
+                        aria-label="Stop watch"
+                        icon={<CloseIcon boxSize={2.5} />}
+                        size="sm"
+                        variant="ghost"
+                        color="gray.400"
+                        _hover={{ color: 'white', bg: 'whiteAlpha.100' }}
+                        onClick={() => sendControl('watch.stop')}
+                      />
+                    </Tooltip>
+                  </>
+                )}
+                <IconButton
+                  aria-label={runtimeOpen ? 'Collapse runtime' : 'Expand runtime'}
+                  icon={runtimeOpen ? <ChevronDownIcon boxSize={4} /> : <ChevronUpIcon boxSize={4} />}
+                  size="sm"
+                  variant="ghost"
+                  color="gray.400"
+                  _hover={{ color: 'white', bg: 'whiteAlpha.100' }}
+                  onClick={() => setRuntimeOpen((v) => !v)}
+                />
+              </HStack>
+            </HStack>
+
+            <Collapse in={runtimeOpen} animateOpacity>
+              <VStack
+                data-zui-native-wheel="true"
+                align="stretch"
+                spacing={0}
+                maxH="180px"
+                overflowY="auto"
+                pb={2}
+                sx={{ overscrollBehavior: 'contain', WebkitOverflowScrolling: 'touch', touchAction: 'pan-y' }}
+              >
+                {watchLines.length === 0 ? (
+                  <Text px={4} py={2} fontSize="13px" color="gray.500">Waiting for watch output…</Text>
+                ) : watchLines.map((line) => (
+                  <HStack key={line.id} px={4} py={2} spacing={3} borderTop="1px solid" borderColor="whiteAlpha.50" align="flex-start">
+                    <Text fontSize="12px" color="gray.500" fontFamily="mono" flexShrink={0} pt={0.5}>
+                      {new Date(line.at).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit', second: '2-digit' })}
+                    </Text>
+                    <Text
+                      fontSize="13px"
+                      color={line.tone === 'error' ? 'red.300' : line.tone === 'warning' ? 'yellow.300' : line.tone === 'success' ? 'green.300' : 'gray.400'}
+                      noOfLines={2}
+                      lineHeight="1.4"
+                    >
+                      {line.text}
+                    </Text>
+                  </HStack>
+                ))}
+              </VStack>
+            </Collapse>
+          </Box>
+        )}
+          </PopoverBody>
+        </PopoverContent>
+      </Portal>
+    </Popover>
+  )
+}