feat(J): WebSocket live-events + replace polling + fix ffmpeg turntable timeout

- fix(render): ffmpeg overlay=0:0 -> overlay=0:0:shortest=1 to prevent hang on finite PNG sequences
- feat(ws): add core/websocket.py ConnectionManager + Redis Pub/Sub subscriber loop
- feat(ws): add /api/ws WebSocket endpoint with JWT query-param auth in main.py
- feat(ws): emit render_complete/failed + cad_processing_complete events from step_tasks.py
- feat(ws): emit order_status_change events from orders router
- feat(ws): add beat_tasks.py broadcast_queue_status task (every 10s via Redis __broadcast__)
- feat(frontend): add useWebSocket hook with auto-reconnect (exponential backoff, 25s ping)
- feat(frontend): add WebSocketContext + WebSocketProvider wrapping App
- refactor(frontend): remove polling from WorkerActivity (was 5s/3s) + OrderDetail (was 5s)
- refactor(frontend): reduce polling in Layout (8s->60s) + NotificationCenter (15s->60s)
- docs: add ffmpeg shortest=1 + WebSocket JWT auth learnings to LEARNINGS.md

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

frontend/src/App.tsx

@@ -1,5 +1,6 @@
 import { BrowserRouter, Routes, Route, Navigate } from 'react-router-dom'
 import { useAuthStore } from './store/auth'
+import { WebSocketProvider } from './contexts/WebSocketContext'
 import Layout from './components/layout/Layout'
 import LoginPage from './pages/Login'
 import DashboardPage from './pages/Dashboard'
@@ -38,7 +39,8 @@ function AdminRoute({ children }: { children: React.ReactNode }) {
 export default function App() {
   return (
     <BrowserRouter>
-      <Routes>
+      <WebSocketProvider>
+        <Routes>
         <Route path="/login" element={<LoginPage />} />
         <Route
           path="/"
@@ -103,7 +105,8 @@ export default function App() {
             }
           />
         </Route>
-      </Routes>
+        </Routes>
+      </WebSocketProvider>
     </BrowserRouter>
   )
 }

frontend/src/components/layout/Layout.tsx

@@ -23,8 +23,8 @@ export default function Layout() {
   const { data: activity } = useQuery({
     queryKey: ['worker-activity'],
     queryFn: getWorkerActivity,
-    refetchInterval: 8000,
-    staleTime: 4000,
+    refetchInterval: 60_000,
+    staleTime: 30_000,
   })
 
   const { data: draftOrders } = useQuery({

frontend/src/components/layout/NotificationCenter.tsx

@@ -81,7 +81,7 @@ export default function NotificationCenter() {
   const { data: unreadCount = 0 } = useQuery({
     queryKey: ['notifications', 'unread-count'],
     queryFn: getUnreadCount,
-    refetchInterval: 15_000,
+    refetchInterval: 60_000,
     staleTime: 5_000,
   })
 
@@ -203,7 +203,7 @@ export default function NotificationCenter() {
                     <p className={clsx('text-sm', !n.read_at ? 'font-medium text-content' : 'text-content-secondary')}>
                       {cfg.label(n.details)}
                     </p>
-                    {n.details?.error && (
+                    {!!n.details?.error && (
                       <p className="mt-1 text-xs text-red-600 font-mono bg-red-50 rounded px-1.5 py-0.5 truncate">
                         {String(n.details.error)}
                       </p>

frontend/src/contexts/WebSocketContext.tsx

@@ -0,0 +1,62 @@
+/**
+ * WebSocketContext — global WebSocket provider.
+ *
+ * Wraps the app with a single WebSocket connection. On incoming events it
+ * invalidates the relevant React Query caches so all subscribers refresh.
+ */
+import { createContext, useContext, useCallback } from 'react'
+import { useQueryClient } from '@tanstack/react-query'
+import { useWebSocket, type WSEvent } from '../hooks/useWebSocket'
+
+const WebSocketContext = createContext<null>(null)
+
+export function WebSocketProvider({ children }: { children: React.ReactNode }) {
+  const qc = useQueryClient()
+
+  const onEvent = useCallback(
+    (event: WSEvent) => {
+      switch (event.type) {
+        case 'render_complete':
+        case 'render_failed':
+          qc.invalidateQueries({ queryKey: ['orders'] })
+          if (event.order_id) {
+            qc.invalidateQueries({ queryKey: ['order', event.order_id as string] })
+          }
+          qc.invalidateQueries({ queryKey: ['worker-activity'] })
+          break
+
+        case 'cad_processing_complete':
+          qc.invalidateQueries({ queryKey: ['worker-activity'] })
+          break
+
+        case 'order_status_change':
+          qc.invalidateQueries({ queryKey: ['orders'] })
+          if (event.order_id) {
+            qc.invalidateQueries({ queryKey: ['order', event.order_id as string] })
+          }
+          break
+
+        case 'queue_update':
+          qc.setQueryData(['queue-status'], event.depths)
+          break
+
+        default:
+          break
+      }
+    },
+    [qc],
+  )
+
+  useWebSocket({ onEvent })
+
+  return (
+    <WebSocketContext.Provider value={null}>
+      {children}
+    </WebSocketContext.Provider>
+  )
+}
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+export function useWebSocketContext() {
+  return useContext(WebSocketContext)
+}

frontend/src/hooks/useWebSocket.ts

@@ -0,0 +1,99 @@
+/**
+ * WebSocket connection hook with auto-reconnect.
+ *
+ * Connects to /api/ws?token=<jwt> and emits parsed JSON events via callbacks.
+ * Reconnect strategy: 1s, 2s, 4s, 8s, ... capped at 30s.
+ */
+import { useEffect, useRef, useCallback } from 'react'
+import { useAuthStore } from '../store/auth'
+
+export interface WSEvent {
+  type: string
+  [key: string]: unknown
+}
+
+export type WSEventHandler = (event: WSEvent) => void
+
+interface UseWebSocketOptions {
+  onEvent?: WSEventHandler
+  enabled?: boolean
+}
+
+const WS_BASE =
+  window.location.protocol === 'https:'
+    ? `wss://${window.location.host}`
+    : `ws://${window.location.hostname}:8888`
+
+const PING_INTERVAL_MS = 25_000
+const MAX_BACKOFF_MS = 30_000
+
+export function useWebSocket({ onEvent, enabled = true }: UseWebSocketOptions = {}) {
+  const token = useAuthStore((s) => s.token)
+  const wsRef = useRef<WebSocket | null>(null)
+  const backoffRef = useRef(1000)
+  const pingRef = useRef<ReturnType<typeof setInterval> | null>(null)
+  const reconnectRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const onEventRef = useRef(onEvent)
+  onEventRef.current = onEvent
+
+  const cleanup = useCallback(() => {
+    if (pingRef.current) clearInterval(pingRef.current)
+    if (reconnectRef.current) clearTimeout(reconnectRef.current)
+    if (wsRef.current) {
+      wsRef.current.onclose = null
+      wsRef.current.onerror = null
+      wsRef.current.onmessage = null
+      wsRef.current.close()
+      wsRef.current = null
+    }
+  }, [])
+
+  const connect = useCallback(() => {
+    if (!token || !enabled) return
+    cleanup()
+
+    const url = `${WS_BASE}/api/ws?token=${encodeURIComponent(token)}`
+    const ws = new WebSocket(url)
+    wsRef.current = ws
+
+    ws.onopen = () => {
+      backoffRef.current = 1000 // reset backoff on successful connect
+      // Keep-alive pings
+      pingRef.current = setInterval(() => {
+        if (ws.readyState === WebSocket.OPEN) {
+          ws.send('ping')
+        }
+      }, PING_INTERVAL_MS)
+    }
+
+    ws.onmessage = (evt) => {
+      try {
+        const event = JSON.parse(evt.data) as WSEvent
+        onEventRef.current?.(event)
+      } catch {
+        // ignore non-JSON messages (e.g. pong)
+      }
+    }
+
+    ws.onclose = () => {
+      if (pingRef.current) clearInterval(pingRef.current)
+      // Schedule reconnect with exponential backoff
+      const delay = backoffRef.current
+      backoffRef.current = Math.min(backoffRef.current * 2, MAX_BACKOFF_MS)
+      reconnectRef.current = setTimeout(() => connect(), delay)
+    }
+
+    ws.onerror = () => {
+      ws.close()
+    }
+  }, [token, enabled, cleanup])
+
+  useEffect(() => {
+    if (token && enabled) {
+      connect()
+    } else {
+      cleanup()
+    }
+    return cleanup
+  }, [token, enabled, connect, cleanup])
+}

frontend/src/pages/OrderDetail.tsx

@@ -70,10 +70,6 @@ export default function OrderDetailPage() {
   const { data: order, isLoading } = useQuery({
     queryKey: ['order', id],
     queryFn: () => getOrder(id!),
-    refetchInterval: (query) => {
-      const status = query.state.data?.status
-      return status === 'processing' ? 5000 : false
-    },
   })
 
   const submitMut = useMutation({
@@ -169,7 +165,7 @@ export default function OrderDetailPage() {
   async function handleDownloadRenders() {
     setIsDownloading(true)
     try {
-      await downloadOrderRenders(id!, order.order_number)
+      await downloadOrderRenders(id!, order!.order_number)
     } catch (e: any) {
       toast.error(e.response?.data?.detail || 'Download failed')
     } finally {

frontend/src/pages/WorkerActivity.tsx

@@ -24,7 +24,6 @@ export default function WorkerActivityPage() {
   const { data, isLoading, dataUpdatedAt } = useQuery({
     queryKey: ['worker-activity'],
     queryFn: getWorkerActivity,
-    refetchInterval: 5000,
   })
 
   const reprocessMut = useMutation({
@@ -237,7 +236,7 @@ function QueuePanel() {
   const { data: queue, isLoading } = useQuery({
     queryKey: ['worker-queue'],
     queryFn: getQueueStatus,
-    refetchInterval: 3000,
+    refetchInterval: 10_000,
   })
 
   const purgeMut = useMutation({