@henryavila/mdprobe 0.1.0

package/src/ui/hooks/useClientLibs.js

@@ -0,0 +1,97 @@
+import { useEffect, useRef } from 'preact/hooks'
+import { currentHtml, theme } from '../state/store.js'
+
+const MERMAID_CDN = 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js'
+const KATEX_CSS_CDN = 'https://cdn.jsdelivr.net/npm/katex@0.16/dist/katex.min.css'
+const KATEX_JS_CDN = 'https://cdn.jsdelivr.net/npm/katex@0.16/dist/katex.min.js'
+
+let mermaidLoaded = false
+let katexLoaded = false
+
+function loadScript(src) {
+  return new Promise((resolve, reject) => {
+    if (document.querySelector(`script[src="${src}"]`)) return resolve()
+    const s = document.createElement('script')
+    s.src = src
+    s.onload = resolve
+    s.onerror = reject
+    document.head.appendChild(s)
+  })
+}
+
+function loadCSS(href) {
+  if (document.querySelector(`link[href="${href}"]`)) return
+  const l = document.createElement('link')
+  l.rel = 'stylesheet'
+  l.href = href
+  document.head.appendChild(l)
+}
+
+/**
+ * Initialize Mermaid diagrams and KaTeX math after content renders.
+ * Libraries are loaded lazily from CDN on first use.
+ */
+export function useClientLibs() {
+  const lastHtml = useRef('')
+
+  useEffect(() => {
+    if (currentHtml.value === lastHtml.current) return
+    lastHtml.current = currentHtml.value
+
+    // Mermaid: render all <pre class="mermaid"> blocks
+    const mermaidEls = document.querySelectorAll('pre.mermaid:not([data-processed])')
+    if (mermaidEls.length > 0) {
+      initMermaid(mermaidEls)
+    }
+
+    // KaTeX: render all elements with data-math or math class
+    const mathEls = document.querySelectorAll('[data-math], .math-inline, .math-display')
+    if (mathEls.length > 0) {
+      initKaTeX(mathEls)
+    }
+  }, [currentHtml.value, theme.value])
+}
+
+async function initMermaid(elements) {
+  try {
+    if (!mermaidLoaded) {
+      await loadScript(MERMAID_CDN)
+      mermaidLoaded = true
+    }
+    const isDark = !['latte', 'light'].includes(theme.value)
+    window.mermaid.initialize({
+      startOnLoad: false,
+      theme: isDark ? 'dark' : 'default',
+    })
+    // Mermaid 11+ uses run() with nodes
+    for (const el of elements) {
+      el.setAttribute('data-processed', 'true')
+    }
+    await window.mermaid.run({ nodes: [...elements] })
+  } catch (err) {
+    console.warn('mdprobe: Mermaid rendering failed', err)
+  }
+}
+
+async function initKaTeX(elements) {
+  try {
+    if (!katexLoaded) {
+      loadCSS(KATEX_CSS_CDN)
+      await loadScript(KATEX_JS_CDN)
+      katexLoaded = true
+    }
+    for (const el of elements) {
+      if (el.getAttribute('data-katex-rendered')) continue
+      const tex = el.textContent
+      const displayMode = el.classList.contains('math-display')
+      try {
+        window.katex.render(tex, el, { displayMode, throwOnError: false })
+        el.setAttribute('data-katex-rendered', 'true')
+      } catch {
+        // Leave raw LaTeX visible
+      }
+    }
+  } catch (err) {
+    console.warn('mdprobe: KaTeX rendering failed', err)
+  }
+}

package/src/ui/hooks/useKeyboard.js

@@ -0,0 +1,128 @@
+import { useEffect } from 'preact/hooks'
+import {
+  leftPanelOpen,
+  rightPanelOpen,
+  selectedAnnotationId,
+  filteredAnnotations,
+} from '../state/store.js'
+
+/**
+ * Registers global keyboard shortcuts for the mdprobe UI.
+ * Shortcuts are suppressed when focus is inside a text input, textarea,
+ * select, or contentEditable element.
+ *
+ * Bindings:
+ *   [   – toggle left panel
+ *   ]   – toggle right panel
+ *   \   – toggle both panels (focus mode)
+ *   j   – select next annotation
+ *   k   – select previous annotation
+ *   r   – reserved (resolve, handled by parent)
+ *   e   – reserved (edit, handled by parent)
+ *   ?   – show help overlay
+ *
+ * @param {{ onShowHelp?: () => void }} options
+ */
+export function useKeyboard({ onShowHelp } = {}) {
+  useEffect(() => {
+    function handleKey(e) {
+      // Don't intercept when typing in form controls
+      const tag = document.activeElement?.tagName
+      if (tag === 'TEXTAREA' || tag === 'INPUT' || tag === 'SELECT') return
+      if (document.activeElement?.isContentEditable) return
+
+      switch (e.key) {
+        case '[':
+          e.preventDefault()
+          leftPanelOpen.value = !leftPanelOpen.value
+          break
+
+        case ']':
+          e.preventDefault()
+          rightPanelOpen.value = !rightPanelOpen.value
+          break
+
+        case '\\': {
+          e.preventDefault()
+          const bothOpen = leftPanelOpen.value && rightPanelOpen.value
+          leftPanelOpen.value = !bothOpen
+          rightPanelOpen.value = !bothOpen
+          break
+        }
+
+        case 'j':
+          e.preventDefault()
+          navigateAnnotation(1)
+          break
+
+        case 'k':
+          e.preventDefault()
+          navigateAnnotation(-1)
+          break
+
+        case 'r':
+          // Resolve – handled by parent component listener
+          break
+
+        case 'e':
+          // Edit – handled by parent component listener
+          break
+
+        case '?':
+          e.preventDefault()
+          onShowHelp?.()
+          break
+
+        default:
+          break
+      }
+    }
+
+    document.addEventListener('keydown', handleKey)
+    return () => document.removeEventListener('keydown', handleKey)
+  }, [onShowHelp])
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Move selection to the next/previous annotation in the filtered list
+ * and scroll both the right-panel card and the content highlight into view.
+ *
+ * @param {1|-1} direction  1 = next, -1 = previous
+ */
+function navigateAnnotation(direction) {
+  const list = filteredAnnotations.value
+  if (list.length === 0) return
+
+  const currentId = selectedAnnotationId.value
+  const currentIndex = list.findIndex((a) => a.id === currentId)
+
+  let nextIndex
+  if (currentIndex === -1) {
+    // Nothing selected yet – jump to first or last depending on direction
+    nextIndex = direction > 0 ? 0 : list.length - 1
+  } else {
+    nextIndex = currentIndex + direction
+    // Wrap around
+    if (nextIndex < 0) nextIndex = list.length - 1
+    if (nextIndex >= list.length) nextIndex = 0
+  }
+
+  const target = list[nextIndex]
+  selectedAnnotationId.value = target.id
+
+  // Scroll the annotation card into view in the right panel
+  const card = document.querySelector(
+    `[data-annotation-id="${target.id}"]`,
+  )
+  card?.scrollIntoView({ behavior: 'smooth', block: 'nearest' })
+
+  // Scroll the corresponding content highlight into view
+  const highlight = document.querySelector(
+    `[data-highlight-id="${target.id}"]`,
+  )
+  highlight?.scrollIntoView({ behavior: 'smooth', block: 'center' })
+}

package/src/ui/hooks/useTheme.js

@@ -0,0 +1,57 @@
+import { useEffect } from 'preact/hooks'
+import { theme } from '../state/store.js'
+
+/** Available themes with display metadata. */
+export const THEMES = [
+  { id: 'mocha', label: 'Mocha', color: '#1e1e2e' },
+  { id: 'macchiato', label: 'Macchiato', color: '#24273a' },
+  { id: 'frappe', label: 'Frapp\u00e9', color: '#303446' },
+  { id: 'latte', label: 'Latte', color: '#eff1f5' },
+  { id: 'light', label: 'Light', color: '#ffffff' },
+]
+
+const STORAGE_KEY = 'mdprobe-theme'
+
+/**
+ * Theme management hook.
+ *
+ * - Applies the active theme as a `data-theme` attribute on `<html>`.
+ * - Persists the selection to `localStorage`.
+ * - Subscribes to signal changes so the DOM stays in sync even when the
+ *   signal is mutated outside this hook.
+ *
+ * @returns {{ theme: import('@preact/signals').Signal<string>, setTheme: (id: string) => void, themes: typeof THEMES }}
+ */
+export function useTheme() {
+  // Subscribe to the theme signal and keep the DOM + storage in sync.
+  useEffect(() => {
+    // Apply immediately in case the signal already holds a value
+    applyTheme(theme.value)
+
+    const dispose = theme.subscribe((value) => {
+      applyTheme(value)
+    })
+
+    return dispose
+  }, [])
+
+  /** Set the active theme by id. */
+  function setTheme(id) {
+    theme.value = id
+  }
+
+  return { theme, setTheme, themes: THEMES }
+}
+
+// ---------------------------------------------------------------------------
+// Internal helper
+// ---------------------------------------------------------------------------
+
+function applyTheme(id) {
+  document.documentElement.setAttribute('data-theme', id)
+  try {
+    localStorage.setItem(STORAGE_KEY, id)
+  } catch {
+    // Storage may be unavailable (private browsing, quota exceeded, etc.)
+  }
+}

package/src/ui/hooks/useWebSocket.js

@@ -0,0 +1,126 @@
+import { useEffect, useRef, useCallback } from 'preact/hooks'
+import {
+  currentHtml,
+  currentToc,
+  currentFile,
+  files,
+  annotations,
+  sections,
+  driftWarning,
+} from '../state/store.js'
+
+const RECONNECT_DELAY_MS = 2000
+const MAX_RECONNECT_DELAY_MS = 30000
+
+/**
+ * Manages the WebSocket connection to the mdprobe server.
+ * Automatically reconnects with exponential back-off on disconnection.
+ * Dispatches incoming messages to the appropriate signals in the store.
+ *
+ * @returns {import('preact/hooks').Ref<WebSocket|null>} ref to the active WebSocket
+ */
+export function useWebSocket() {
+  const wsRef = useRef(null)
+  const reconnectDelay = useRef(RECONNECT_DELAY_MS)
+  const reconnectTimer = useRef(null)
+  const unmounted = useRef(false)
+
+  const connect = useCallback(() => {
+    if (unmounted.current) return
+
+    const protocol = location.protocol === 'https:' ? 'wss:' : 'ws:'
+    const ws = new WebSocket(`${protocol}//${location.host}/ws`)
+    wsRef.current = ws
+
+    ws.onopen = () => {
+      // Reset back-off on successful connection
+      reconnectDelay.current = RECONNECT_DELAY_MS
+    }
+
+    ws.onmessage = (event) => {
+      let msg
+      try {
+        msg = JSON.parse(event.data)
+      } catch {
+        console.warn('mdprobe: received non-JSON WebSocket message')
+        return
+      }
+
+      switch (msg.type) {
+        case 'update': {
+          // Preserve scroll position across live reload
+          const contentEl = document.querySelector('.content-area')
+          const savedScroll = contentEl ? contentEl.scrollTop : 0
+          currentHtml.value = msg.html
+          currentToc.value = msg.toc || []
+          // Restore scroll after DOM update
+          if (contentEl) {
+            requestAnimationFrame(() => { contentEl.scrollTop = savedScroll })
+          }
+          break
+        }
+
+        case 'file-added':
+          // Avoid duplicates
+          if (!files.value.some((f) => f.path === msg.file)) {
+            files.value = [
+              ...files.value,
+              { path: msg.file, label: msg.file.replace(/\.md$/, '') },
+            ]
+          }
+          break
+
+        case 'file-removed':
+          files.value = files.value.filter((f) => f.path !== msg.file)
+          break
+
+        case 'annotations':
+          // Only apply if the broadcast is for the currently viewed file
+          if (!msg.file || msg.file === currentFile.value) {
+            annotations.value = msg.annotations || []
+            sections.value = msg.sections || []
+          }
+          break
+
+        case 'drift':
+          driftWarning.value = msg.warning || true
+          break
+
+        case 'error':
+          // Keep last valid render; surface the warning in the console
+          console.warn('mdprobe:', msg.message)
+          break
+      }
+    }
+
+    ws.onerror = (err) => {
+      console.warn('mdprobe: WebSocket error', err)
+    }
+
+    ws.onclose = () => {
+      wsRef.current = null
+      if (unmounted.current) return
+
+      // Exponential back-off with jitter, capped at MAX_RECONNECT_DELAY_MS
+      const delay = reconnectDelay.current
+      reconnectDelay.current = Math.min(delay * 2, MAX_RECONNECT_DELAY_MS)
+      const jitter = Math.random() * delay * 0.3
+
+      reconnectTimer.current = setTimeout(connect, delay + jitter)
+    }
+  }, [])
+
+  useEffect(() => {
+    unmounted.current = false
+    connect()
+
+    return () => {
+      unmounted.current = true
+      clearTimeout(reconnectTimer.current)
+      wsRef.current?.close()
+      wsRef.current = null
+    }
+  }, [connect])
+
+  return wsRef
+}

package/src/ui/index.html

@@ -0,0 +1,19 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>mdprobe</title>
+  <script>
+    (function() {
+      var theme = localStorage.getItem('mdprobe-theme') || 'mocha';
+      document.documentElement.setAttribute('data-theme', theme);
+    })();
+  </script>
+  <link rel="stylesheet" href="./styles/themes.css" />
+</head>
+<body>
+  <div id="app"></div>
+  <script type="module" src="./app.jsx"></script>
+</body>
+</html>

package/src/ui/state/store.js

@@ -0,0 +1,76 @@
+import { signal, computed } from '@preact/signals'
+
+// Files
+export const files = signal([])
+export const currentFile = signal(null)
+
+// Content
+export const currentHtml = signal('')
+export const currentToc = signal([])
+export const frontmatter = signal(null)
+
+// Annotations
+export const annotations = signal([])
+export const sections = signal([])
+export const selectedAnnotationId = signal(null)
+export const showResolved = signal(false)
+export const filterTag = signal(null)
+export const filterAuthor = signal(null)
+
+// UI state — restore from localStorage
+export const leftPanelOpen = signal(localStorage.getItem('mdprobe-left-panel') !== 'false')
+export const rightPanelOpen = signal(localStorage.getItem('mdprobe-right-panel') !== 'false')
+export const theme = signal(localStorage.getItem('mdprobe-theme') || 'mocha')
+export const driftWarning = signal(false)
+
+// Persist panel state on change via effect (subscribed below)
+leftPanelOpen.subscribe(v => localStorage.setItem('mdprobe-left-panel', v))
+rightPanelOpen.subscribe(v => localStorage.setItem('mdprobe-right-panel', v))
+
+// Config
+export const author = signal('anonymous')
+export const reviewMode = signal(false)
+
+// Computed
+export const openAnnotations = computed(() =>
+  annotations.value.filter(a => a.status === 'open')
+)
+
+export const resolvedAnnotations = computed(() =>
+  annotations.value.filter(a => a.status === 'resolved')
+)
+
+export const filteredAnnotations = computed(() => {
+  let list = showResolved.value
+    ? annotations.value
+    : annotations.value.filter(a => a.status === 'open')
+
+  if (filterTag.value) {
+    list = list.filter(a => a.tag === filterTag.value)
+  }
+  if (filterAuthor.value) {
+    list = list.filter(a => a.author === filterAuthor.value)
+  }
+
+  return list
+})
+
+export const uniqueTags = computed(() =>
+  [...new Set(annotations.value.map(a => a.tag))]
+)
+
+export const uniqueAuthors = computed(() =>
+  [...new Set(annotations.value.map(a => a.author))]
+)
+
+// Adaptive section level (set from API response)
+export const sectionLevel = signal(2)
+
+// Section stats — count at the adaptive section level
+export const sectionStats = computed(() => {
+  const lvl = sectionLevel.value
+  const atLevel = sections.value.filter(s => s.level === lvl)
+  const total = atLevel.length
+  const reviewed = atLevel.filter(s => s.status !== 'pending').length
+  return { total, reviewed }
+})