feat: implement WebSocket management with a dedicated worker and update packing logic

Author: Krande

frontend/scripts/pack.js

@@ -5,8 +5,9 @@ import path from 'path'
 import AdmZip from 'adm-zip'
 
 const root = path.resolve(process.cwd())
-const distIndex = path.join(root, 'dist', 'index.html')
-const outZipFrontend = path.join(root, 'dist', 'frontend.zip')
+const distDir = path.join(root, 'dist')
+const distIndex = path.join(distDir, 'index.html')
+const outZipFrontend = path.join(distDir, 'frontend.zip')
 const resourcesZip = path.resolve(root, '..', 'src', 'paradoc', 'resources', 'frontend.zip')
 
 function ensureDir(p) {
@@ -22,9 +23,22 @@ function main() {
     process.exit(1)
   }
 
-  // Create zip with only index.html (renamed to index.html inside zip)
+  // Create zip with everything from dist (excluding the zip itself), so workers/assets are preserved
   const zip = new AdmZip()
-  zip.addLocalFile(distIndex, '', 'index.html')
+
+  // Add all files under dist, preserving paths
+  const entries = fs.readdirSync(distDir)
+  for (const entry of entries) {
+    const full = path.join(distDir, entry)
+    if (full === outZipFrontend) continue
+    const stat = fs.statSync(full)
+    if (stat.isFile()) {
+      zip.addLocalFile(full, '')
+    } else if (stat.isDirectory()) {
+      zip.addLocalFolder(full, entry)
+    }
+  }
+
   zip.writeZip(outZipFrontend)
   console.log(`[pack] Wrote ${outZipFrontend}`)
 

frontend/src/App.tsx

@@ -2,7 +2,11 @@ import React, { useEffect, useMemo, useRef, useState } from 'react'
 import { Topbar } from './components/Topbar'
 import { Navbar, TocItem } from './components/Navbar'
 
-const WS_URL = 'ws://localhost:13579'
+// WebSocket management is delegated to a Web Worker that reconnects and forwards messages
+// Vite will inline the worker into the single-file build
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore
+const WorkerCtor = (URL as any) ? (url: string) => new Worker(new URL(url, import.meta.url), { type: 'module' }) : null
 
 const MOCK_HTML = `
   <main>
@@ -19,7 +23,7 @@ const MOCK_HTML = `
 export default function App() {
   const [connected, setConnected] = useState<boolean>(false)
   const [docHtml, setDocHtml] = useState<string>(MOCK_HTML)
-  const wsRef = useRef<WebSocket | null>(null)
+  const workerRef = useRef<Worker | null>(null)
 
   // Parse HTML into a Document for TOC extraction
   const doc = useMemo(() => {
@@ -79,28 +83,35 @@ export default function App() {
   }, [doc])
 
   useEffect(() => {
-    const ws = new WebSocket(WS_URL)
-    wsRef.current = ws
-    ws.addEventListener('open', () => setConnected(true))
-    ws.addEventListener('close', () => setConnected(false))
-    ws.addEventListener('error', () => setConnected(false))
-
-    ws.addEventListener('message', (event) => {
-      const data = typeof event.data === 'string' ? event.data : ''
-      if (data.trim()) {
-        setDocHtml(data)
+    // Start the WS worker (runs in a dedicated thread)
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
+    const worker: Worker = new Worker(new URL('./ws/worker.ts', import.meta.url), { type: 'module' })
+    workerRef.current = worker
+
+    const onMessage = (event: MessageEvent) => {
+      const msg = event.data
+      if (!msg) return
+      if (msg.type === 'status') {
+        setConnected(!!msg.connected)
+      } else if (msg.type === 'html' && typeof msg.html === 'string') {
+        if (msg.html.trim()) setDocHtml(msg.html)
       }
-    })
+    }
+
+    worker.addEventListener('message', onMessage)
 
     return () => {
-      ws.close()
-      wsRef.current = null
+      try { worker.postMessage({ type: 'stop' }) } catch {}
+      worker.removeEventListener('message', onMessage)
+      worker.terminate()
+      workerRef.current = null
     }
   }, [])
 
   const sendHtml = (html: string) => {
-    if (wsRef.current && wsRef.current.readyState === WebSocket.OPEN) {
-      wsRef.current.send(html)
+    if (workerRef.current) {
+      workerRef.current.postMessage({ type: 'send', html })
     }
   }
 

frontend/src/main.tsx

@@ -2,10 +2,6 @@ import React from 'react'
 import { createRoot } from 'react-dom/client'
 import App from './App'
 import './styles.css'
-import { initWsListener } from './ws/listener'
-
-// Initialize in-app WebSocket listener in development
-initWsListener()
 
 const container = document.getElementById('root')!
 const root = createRoot(container)

frontend/src/ws/worker.ts

@@ -0,0 +1,97 @@
+// Web Worker to maintain a persistent WebSocket connection and forward HTML to the UI
+// Runs in its own thread. Reconnects with backoff and sends heartbeats to keep the connection alive.
+
+// In a worker, self is DedicatedWorkerGlobalScope
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const ctx: any = self as any
+
+const WS_URL = 'ws://localhost:13579'
+
+let ws: WebSocket | null = null
+let stopped = false
+let reconnectAttempts = 0
+let heartbeatTimer: number | null = null
+
+function scheduleReconnect() {
+  if (stopped) return
+  reconnectAttempts++
+  const delay = Math.min(30000, 1000 * Math.pow(2, Math.min(5, reconnectAttempts))) // 1s → 32s, capped at 30s
+  setTimeout(connect, delay)
+}
+
+function clearHeartbeat() {
+  if (heartbeatTimer !== null) {
+    clearInterval(heartbeatTimer)
+    heartbeatTimer = null
+  }
+}
+
+function startHeartbeat() {
+  clearHeartbeat()
+  // Send a ping every 20s to keep NATs/IDS from closing idle connections
+  heartbeatTimer = setInterval(() => {
+    try {
+      if (ws && ws.readyState === WebSocket.OPEN) {
+        ws.send('') // empty ping
+      }
+    } catch {
+      // ignore
+    }
+  }, 20000) as unknown as number
+}
+
+function connect() {
+  if (stopped) return
+
+  try {
+    ws = new WebSocket(WS_URL)
+  } catch (e) {
+    // Unable to construct; try again later
+    scheduleReconnect()
+    return
+  }
+
+  ws.addEventListener('open', () => {
+    reconnectAttempts = 0
+    startHeartbeat()
+    ctx.postMessage({ type: 'status', connected: true })
+  })
+
+  ws.addEventListener('close', () => {
+    ctx.postMessage({ type: 'status', connected: false })
+    clearHeartbeat()
+    scheduleReconnect()
+  })
+
+  ws.addEventListener('error', () => {
+    ctx.postMessage({ type: 'status', connected: false })
+  })
+
+  ws.addEventListener('message', (event: MessageEvent) => {
+    const data = typeof event.data === 'string' ? event.data : ''
+    if (data && data.trim()) {
+      ctx.postMessage({ type: 'html', html: data })
+    }
+  })
+}
+
+// Allow main thread to forward HTML back to the server if needed
+ctx.addEventListener('message', (event: MessageEvent) => {
+  const msg = event.data
+  if (!msg) return
+  if (msg.type === 'stop') {
+    stopped = true
+    try { ws?.close() } catch {}
+    clearHeartbeat()
+    return
+  }
+  if (msg.type === 'send' && typeof msg.html === 'string') {
+    try {
+      if (ws && ws.readyState === WebSocket.OPEN) {
+        ws.send(msg.html)
+      }
+    } catch {}
+  }
+})
+
+connect()