@saluzi/saluzi-edu 0.2.59 → 0.2.61

package/dist/guide/guide-data.json

@@ -6066,6 +6066,10 @@
       "category": "bridge",
       "description": "worker 连接的 RCS 地址"
     },
+    {
+      "name": "SALUZI_BRIDGE_CLAIM_TIMEOUT_MS",
+      "category": "other"
+    },
     {
       "name": "SALUZI_BRIDGE_MAX_SESSIONS",
       "category": "other"
@@ -7144,7 +7148,7 @@
           "可视化"
         ]
       },
-      "content": "\n## 什么是 /parade\n\nParade 是 Saluzi 的桌面悬浮提示功能。它在桌面显示一个小型悬浮窗口（基于 Electron），实时反映：\n\n- **运行中会话数**：当前正在执行工具调用的会话\n- **等待中会话数**：等待用户输入或权限确认的会话\n- **连接状态**：WebSocket 连接状态指示灯\n\n外观示意（运行中 2 / 等待 1）：\n\n::parade-preview::\n\n## 启用 Parade\n\n```\n> /parade\n```\n\n首次启用会自动检测并安装 Electron（若未安装），然后启动悬浮窗。悬浮窗默认定位在**主显示器顶部居中**，220×130 像素，无边框始终置顶。\n\n## 关闭 Parade\n\n```\n> /parade off\n```\n\n## 多会话并行\n\n多个终端各自运行 Saluzi 会话时，所有 CLI 实例共享同一个 Parade 窗口（通过 PID 锁文件确保单例）。悬浮窗显示所有已连接会话的运行/等待计数。\n\nParade 服务器以**脱离模式**运行——即使启动它的 CLI 关闭，悬浮窗仍然存活，直到用 `/parade off` 显式关闭。\n\n## 平台支持\n\n| 平台 | 状态 | 说明 |\n|------|------|------|\n| macOS | 完全支持 | 原生 Electron |\n| Linux | 支持 | 需 X11 或 Wayland |\n| Windows | 支持 | Electron |\n| WSL | 支持 | 通过 /etc/resolv.conf 解析主机 IP |\n\n## 故障排查\n\n- **悬浮窗不显示**：检查 Electron 是否安装（`/parade` 会自动安装，支持 `ELECTRON_MIRROR` 环境变量配置镜像）\n- **Electron 安装路径**：`~/.saluzi/parade/`\n- **多显示器**：悬浮窗默认在主显示器顶部居中\n"
+      "content": "\n## 什么是 /parade\n\nParade 是 Saluzi 的桌面悬浮提示功能。它在桌面显示一个小型悬浮窗口（基于 Electron），实时反映：\n\n- **运行中会话数**：当前正在执行工具调用的会话\n- **等待中会话数**：等待用户输入或权限确认的会话\n- **连接状态**：WebSocket 连接状态指示灯\n\n外观示意（运行中 2 / 等待 1）：\n\n::parade-preview::\n\n## 启用 Parade\n\n```\n> /parade\n```\n\n首次启用会自动检测并安装 Electron（若未安装），然后启动悬浮窗。悬浮窗默认定位在**主显示器右下角**（避开任务栏），220×130 像素，无边框始终置顶。\n\n## 关闭 Parade\n\n```\n> /parade off\n```\n\n## 多会话并行\n\n多个终端各自运行 Saluzi 会话时，所有 CLI 实例共享同一个 Parade 窗口（通过 PID 锁文件确保单例）。悬浮窗显示所有已连接会话的运行/等待计数。\n\nParade 服务器以**脱离模式**运行——即使启动它的 CLI 关闭，悬浮窗仍然存活，直到用 `/parade off` 显式关闭。\n\n## 显示模式\n\n右键悬浮窗（或在左侧立方体区域滚动滚轮）可在 4 种显示模式间切换，按信息完整度排序：\n\n| 模式 | 显示内容 | 默认窗口尺寸 |\n|------|----------|--------------|\n| Cube only | 仅左侧立方体图案 | 130×130 |\n| Cube + counts | 立方体 + 运行/等待计数 | 176×130 |\n| Standard（默认） | 立方体 + 计数 + 会话列表 | 220×130 |\n| Detail | 大窗口详情：全部会话、状态徽章（RUN/BLOCK/IDLE）、更完整的 prompt，整行可点击跳转 | 460×340 |\n\n- 当前模式在右键菜单中以实心圆点标记，切换后持久化，重启悬浮窗后仍生效\n- 窗口尺寸随模式自动调整；手动拖拽调整过的尺寸按模式记忆（下次进入同一模式时恢复）\n- 放大窗口时，立方体图案与字体大小按比例缩放\n- 菜单底部的 **Rotation: Dynamic/Static** 控制旋转时机：运行时旋转（默认）或空闲时旋转\n\n## 跳转终端\n\n会话列表每行左侧的指示点（悬停变为 ▸）可跳转到该会话所在的终端窗口；Detail 模式下点击整行即可。\n\n跨边界场景（WSL 内的 CLI 向 Windows 侧悬浮窗上报）中，WSL 进程在 Windows 侧没有对应进程 ID，Parade 会退而激活检测到的终端窗口（Windows Terminal 等）。存在多个终端窗口时聚焦第一个匹配窗口，不保证定位到具体标签页。\n\n## 平台支持\n\n| 平台 | 状态 | 说明 |\n|------|------|------|\n| macOS | 完全支持 | 原生 Electron |\n| Linux | 支持 | 需 X11 或 Wayland |\n| Windows | 支持 | Electron |\n| WSL | 支持 | 通过 /etc/resolv.conf 解析主机 IP |\n\n## 故障排查\n\n- **悬浮窗不显示**：检查 Electron 是否安装（`/parade` 会自动安装，支持 `ELECTRON_MIRROR` 环境变量配置镜像）\n- **Electron 安装路径**：`~/.saluzi/parade/`\n- **多显示器**：悬浮窗默认在主显示器顶部居中\n"
     },
     "docs/guide/keyboard-shortcuts": {
       "frontmatter": {

package/dist/parade/web/cube.js

@@ -3,38 +3,224 @@
  *
  * Responsibilities:
  *   1. Render a purple 3D cube via CSS 3D transforms in the left stage area.
- *   2. Animate the cube with gyroscope-style rotation when runningCount > 0.
+ *   2. Animate the cube with a fast glow-pulse rotation when runningCount > 0.
  *   3. Update the info bar (right side) with running/waiting counts and
  *      per-session prompt text from WebSocket pushes.
+ *   4. Manage the 4-level display mode (logo / mini / standard / detail) with
+ *      window-size sync, persistence, and right-click menu switching.
  *
  * WebSocket protocol: receives JSON array of SessionEntry objects:
  *   [{ pid, sessionId, state, prompt, lastHeartbeat }, ...]
+ *
+ * Unit contract (must match the electron main script in paradeWindow.ts):
+ *   - design px: the base coordinate system. All CSS dimensions are
+ *     calc(Npx * var(--ui-scale)); --ui-scale is derived from the window
+ *     size relative to the current mode's base size.
+ *   - IPC bounds (parade-set-bounds / parade-bounds-changed): design px.
+ *     The main process multiplies/divides by its unitScale (dpiScale).
+ *   - localStorage sizes: design px (portable across DPI settings).
  */
 
 // ---------------------------------------------------------------------------
 // Configuration
 // ---------------------------------------------------------------------------
 
-const MAX_PROMPT_LENGTH = 30
-const MAX_DISPLAYED_SESSIONS = 5
-const WS_RECONNECT_MS = 2000
+var WS_RECONNECT_MS = 2000
+
+// Per-mode config. win = natural window size (design px, applied on mode
+// switch when no user-customized size is saved). base = scale reference
+// (design px at --ui-scale 1) — detail uses a smaller base so fonts render
+// large enough to read at its natural window size. maxPrompt/maxRows control
+// the session list density.
+var MODES = {
+  logo: { win: [130, 130], base: [130, 130], maxPrompt: 30, maxRows: 5 },
+  mini: { win: [176, 130], base: [176, 130], maxPrompt: 30, maxRows: 5 },
+  standard: { win: [220, 130], base: [220, 130], maxPrompt: 30, maxRows: 5 },
+  detail: { win: [460, 340], base: [300, 220], maxPrompt: 80, maxRows: 20 },
+}
+var MODE_ORDER = ['logo', 'mini', 'standard', 'detail']
+var SCALE_MIN = 1
+var SCALE_MAX = 3
+// Window bounds clamps in design px — must match the parade-set-bounds
+// clamps in the electron main script (which multiplies by unitScale).
+var BOUNDS_MIN = [100, 80]
+var BOUNDS_MAX = [900, 700]
+
+// ---------------------------------------------------------------------------
+// Zoom / port (needed before everything — applyScale divides by zoomFactor)
+// ---------------------------------------------------------------------------
+
+// Derive port from the current page's URL so the WebSocket targets the same
+// server that served this page. Falls back to query string (?port=) for the
+// file:// case (native Webview windows launched with a file URL), then to
+// the default 17841.
+var urlParams = new URLSearchParams(window.location.search)
+var port = window.location.port || urlParams.get('port') || '17841'
+
+// On native Win11, Electron is launched with --force-device-scale-factor=1
+// to eliminate DPI conversion mismatches in getBounds/setBounds. This makes
+// 1 CSS pixel = 1 physical pixel, so content renders at 1x scale (smaller
+// on high-DPI displays). The main process passes the OS DPI factor as ?zoom=
+// so we can CSS-zoom the content to match the intended physical size.
+//
+// --ui-scale must be computed against DESIGN px, not the zoomed CSS px:
+// window.innerWidth counts physical px here (root zoom doesn't change the
+// viewport CSS px count), so divide by zoomFactor to avoid double-scaling.
+var zoomParam = parseFloat(urlParams.get('zoom')) || 0
+if (zoomParam > 1) {
+  document.documentElement.style.zoom = String(zoomParam)
+}
+var zoomFactor = zoomParam > 1 ? zoomParam : 1
+
+// ---------------------------------------------------------------------------
+// Display mode state (applied as early as possible to avoid resize flash)
+// ---------------------------------------------------------------------------
+
+var displayMode = 'standard'
+try {
+  let storedMode = localStorage.getItem('parade-display-mode')
+  if (storedMode && MODES[storedMode]) displayMode = storedMode
+} catch (_) {
+  /* localStorage may be unavailable */
+}
+document.body.dataset.mode = displayMode
+
+// Per-mode user-customized window size (design px). Saved on manual resize,
+// preferred over the mode's natural size on mode entry / boot.
+function clampSize(w, h) {
+  return [
+    Math.max(BOUNDS_MIN[0], Math.min(BOUNDS_MAX[0], Math.round(w))),
+    Math.max(BOUNDS_MIN[1], Math.min(BOUNDS_MAX[1], Math.round(h))),
+  ]
+}
+
+function savedSize(mode) {
+  try {
+    const raw = localStorage.getItem('parade-size-' + mode)
+    if (!raw) return null
+    const parts = JSON.parse(raw)
+    if (
+      Array.isArray(parts) &&
+      parts.length === 2 &&
+      Number.isFinite(parts[0]) &&
+      Number.isFinite(parts[1])
+    ) {
+      return clampSize(parts[0], parts[1])
+    }
+  } catch (_) {
+    /* ignore */
+  }
+  return null
+}
+
+function saveSize(mode, w, h) {
+  try {
+    localStorage.setItem('parade-size-' + mode, JSON.stringify(clampSize(w, h)))
+  } catch (_) {
+    /* ignore */
+  }
+}
+
+// Bounds echo suppression: after WE request bounds, the main process echoes
+// parade-bounds-changed back — without the flag we'd persist our own mode
+// size as a "user customization" (feedback loop).
+var suppressBoundsSave = false
+
+function requestWindowBounds(w, h) {
+  if (!window.parade || typeof window.parade.setBounds !== 'function') return
+  var s = clampSize(w, h)
+  suppressBoundsSave = true
+  window.parade.setBounds(s[0], s[1])
+}
+
+if (window.parade && typeof window.parade.onBoundsChanged === 'function') {
+  window.parade.onBoundsChanged(function (w, h) {
+    if (suppressBoundsSave) {
+      suppressBoundsSave = false
+      return
+    }
+    if (typeof w === 'number' && typeof h === 'number' && w > 0 && h > 0) {
+      saveSize(displayMode, w, h)
+    }
+  })
+}
 
 // ---------------------------------------------------------------------------
 // DOM references
 // ---------------------------------------------------------------------------
 
-const cubeEl = document.getElementById('cube')
-const runningCountEl = document.getElementById('running-count')
-const waitingCountEl = document.getElementById('waiting-count')
-const waitingPillEl = document.getElementById('waiting-pill')
-const sessionsEl = document.getElementById('sessions-inner')
-const sessionsContainer = document.getElementById('sessions')
-const scrollbarTrack = document.getElementById('scrollbar-track')
-const scrollbarThumb = document.getElementById('scrollbar-thumb')
-const moreLineEl = document.getElementById('more-line')
-const ctxMenu = document.getElementById('ctx-menu')
-const ctxMode = document.getElementById('ctx-mode')
-const closeBtn = document.getElementById('close-btn')
+var cubeEl = document.getElementById('cube')
+var cubeStageEl = document.getElementById('cube-stage')
+var runningCountEl = document.getElementById('running-count')
+var waitingCountEl = document.getElementById('waiting-count')
+var waitingPillEl = document.getElementById('waiting-pill')
+var sessionsEl = document.getElementById('sessions-inner')
+var sessionsContainer = document.getElementById('sessions')
+var scrollbarTrack = document.getElementById('scrollbar-track')
+var scrollbarThumb = document.getElementById('scrollbar-thumb')
+var moreLineEl = document.getElementById('more-line')
+var ctxMenu = document.getElementById('ctx-menu')
+var ctxMode = document.getElementById('ctx-mode')
+var closeBtn = document.getElementById('close-btn')
+
+// ---------------------------------------------------------------------------
+// Session state
+// ---------------------------------------------------------------------------
+
+/** @type {Array<{pid:number, sessionId:string, state:string, prompt:string, lastHeartbeat:number}>} */
+var sessions = []
+var runningCount = 0
+var waitingCount = 0
+var ws = null
+
+// ---------------------------------------------------------------------------
+// UI scale — grows the cube and fonts with the window
+// ---------------------------------------------------------------------------
+
+function applyScale() {
+  var mode = MODES[displayMode]
+  var w = window.innerWidth / zoomFactor
+  var h = window.innerHeight / zoomFactor
+  var s = Math.min(w / mode.base[0], h / mode.base[1])
+  s = Math.max(SCALE_MIN, Math.min(SCALE_MAX, s))
+  document.documentElement.style.setProperty('--ui-scale', s.toFixed(4))
+  // Window resizes change the session viewport — re-measure the scrollbar.
+  requestAnimationFrame(updateScrollbar)
+}
+
+// Re-measure on every window resize (restored — the WebGL→CSS refactor in
+// 982be36 accidentally dropped this listener).
+window.addEventListener('resize', applyScale)
+
+// ---------------------------------------------------------------------------
+// Display mode switching
+// ---------------------------------------------------------------------------
+
+function setMode(mode) {
+  if (!MODES[mode]) return
+  var changed = mode !== displayMode
+  displayMode = mode
+  try {
+    localStorage.setItem('parade-display-mode', mode)
+  } catch (_) {
+    /* ignore */
+  }
+  document.body.dataset.mode = mode
+  if (changed) {
+    // Replay the mode-swap fade animation (needs a reflow to restart).
+    document.body.classList.remove('mode-swap')
+    void document.body.offsetWidth
+    document.body.classList.add('mode-swap')
+    // Truncation/badges/row cap changed — force a row rebuild.
+    lastRowSig = null
+  }
+  updateViewMenu()
+  applyScale()
+  updateSessionRows()
+  // Resize the window to this mode's saved (or natural) size.
+  var size = savedSize(mode) || MODES[mode].win
+  requestWindowBounds(size[0], size[1])
+}
 
 // ---------------------------------------------------------------------------
 // Custom scrollbar — invisible by default, fades in on hover/scroll.
@@ -161,29 +347,6 @@ if (scrollbarThumb && scrollbarTrack) {
 // WebSocket connection
 // ---------------------------------------------------------------------------
 
-// Derive port from the current page's URL so the WebSocket targets the same
-// server that served this page. Falls back to query string (?port=) for the
-// file:// case (native Webview windows launched with a file URL), then to
-// the default 17841.
-var urlParams = new URLSearchParams(window.location.search)
-var port = window.location.port || urlParams.get('port') || '17841'
-
-// On native Win11, Electron is launched with --force-device-scale-factor=1
-// to eliminate DPI conversion mismatches in getBounds/setBounds. This makes
-// 1 CSS pixel = 1 physical pixel, so content renders at 1x scale (smaller
-// on high-DPI displays). The main process passes the OS DPI factor as ?zoom=
-// so we can CSS-zoom the content to match the intended physical size.
-var zoomParam = parseFloat(urlParams.get('zoom')) || 0
-if (zoomParam > 1) {
-  document.documentElement.style.zoom = String(zoomParam)
-}
-
-/** @type {Array<{pid:number, sessionId:string, state:string, prompt:string, lastHeartbeat:number}>} */
-let sessions = []
-let runningCount = 0
-let waitingCount = 0
-let ws = null
-
 function connectWebSocket() {
   try {
     ws = new WebSocket('ws://localhost:' + port + '/ws')
@@ -269,7 +432,33 @@ function updateCounts() {
   updateCubeRotation()
 }
 
+// ---------------------------------------------------------------------------
+// Session rows
+// ---------------------------------------------------------------------------
+// Rows are rebuilt ONLY when the displayed data actually changes. The CLI
+// heartbeats every 1s and each POST broadcasts the full session list —
+// rebuilding on every message would replace row elements between a user's
+// mousedown and mouseup, swallowing clicks (the original jump-button bug).
+
+var lastRowSig = null
+
+function sessionSignature() {
+  return sessions
+    .map(function (s) {
+      return s.pid + '|' + s.state + '|' + (s.prompt || '')
+    })
+    .join('¦')
+}
+
 function updateSessionRows() {
+  var mode = MODES[displayMode]
+  var sig = sessionSignature()
+  if (sig === lastRowSig) {
+    requestAnimationFrame(updateScrollbar)
+    return
+  }
+  lastRowSig = sig
+
   var runningSessions = sessions.filter(function (s) {
     return s.state === 'running'
   })
@@ -291,21 +480,23 @@ function updateSessionRows() {
     return
   }
 
+  var cap = mode.maxRows
   // Running sessions first (primary focus, purple dot)
-  var displayedRunning = runningSessions.slice(0, MAX_DISPLAYED_SESSIONS)
+  var displayedRunning = runningSessions.slice(0, cap)
   displayedRunning.forEach(function (s) {
     sessionsEl.appendChild(buildSessionRow(s, 'running'))
   })
 
-  // Blocked sessions next (amber dot, needs user action)
-  var displayedBlocked = blockedSessions.slice(0, 2)
+  // Blocked sessions next (amber dot, needs user action). Standard modes
+  // keep at most 2 visible so running rows dominate; detail shows all.
+  var blockedCap = displayMode === 'detail' ? cap : 2
+  var displayedBlocked = blockedSessions.slice(0, blockedCap)
   displayedBlocked.forEach(function (s) {
     sessionsEl.appendChild(buildSessionRow(s, 'blocked'))
   })
 
   // Idle sessions last (dim, just "connected")
-  var slotsLeft =
-    MAX_DISPLAYED_SESSIONS - displayedRunning.length - displayedBlocked.length
+  var slotsLeft = cap - displayedRunning.length - displayedBlocked.length
   var displayedIdle = idleSessions.slice(0, Math.max(0, slotsLeft))
   displayedIdle.forEach(function (s) {
     sessionsEl.appendChild(buildSessionRow(s, 'idle'))
@@ -325,11 +516,13 @@ function updateSessionRows() {
 }
 
 function buildSessionRow(s, kind) {
+  var mode = MODES[displayMode]
   var row = document.createElement('div')
   row.className = 'session-row ' + kind
+  row.setAttribute('data-pid', String(s.pid))
   var promptText = s.prompt || ''
-  if (promptText.length > MAX_PROMPT_LENGTH) {
-    promptText = promptText.substring(0, MAX_PROMPT_LENGTH) + '...'
+  if (promptText.length > mode.maxPrompt) {
+    promptText = promptText.substring(0, mode.maxPrompt) + '...'
   }
   var text = document.createElement('span')
   text.className = 'session-text'
@@ -340,13 +533,53 @@ function buildSessionRow(s, kind) {
   } else {
     text.textContent = promptText || '(running)'
   }
-  // Jump-to-terminal dot — placed at left indicator, morphs into ▸ on hover
+  // State badge — visible in detail mode only (CSS)
+  var badge = document.createElement('span')
+  badge.className =
+    'session-badge ' +
+    (kind === 'running' ? 'run' : kind === 'blocked' ? 'block' : 'idle')
+  badge.textContent =
+    kind === 'running' ? 'RUN' : kind === 'blocked' ? 'BLOCK' : 'IDLE'
+  // Jump-to-terminal dot — placed at left indicator, morphs into ▸ on hover.
+  // Click handling is delegated (see mousedown/mouseup pairing below) so a
+  // rebuild between press and release can't swallow the jump.
   var jump = document.createElement('span')
   jump.className = 'session-jump'
-  jump.addEventListener('click', function (e) {
-    e.stopPropagation()
-    if (ws && ws.readyState === WebSocket.OPEN) {
-      ws.send(JSON.stringify({ type: 'focus', pid: s.pid }))
+  row.appendChild(text)
+  row.appendChild(badge)
+  row.insertBefore(jump, row.firstChild)
+
+  return row
+}
+
+// Jump dispatch: mousedown records the pressed row; mouseup on the SAME row
+// fires the focus request. Immune to element replacement between events.
+// In detail mode the whole row is the hit target; other modes require the
+// jump dot.
+var pressedPid = null
+
+sessionsEl.addEventListener('mousedown', function (e) {
+  if (e.button !== 0) return
+  var row = e.target.closest('.session-row')
+  pressedPid = row ? row.getAttribute('data-pid') : null
+})
+
+sessionsEl.addEventListener('mouseup', function (e) {
+  if (e.button !== 0 || pressedPid === null) return
+  var pressed = pressedPid
+  pressedPid = null
+  var row = e.target.closest('.session-row')
+  var pid = row ? row.getAttribute('data-pid') : null
+  var isJumpClick = !!e.target.closest('.session-jump')
+  if (!row || pid === null || pid !== pressed) return
+  if (displayMode !== 'detail' && !isJumpClick) return
+  sendFocus(Number(pid), row)
+})
+
+function sendFocus(pid, row) {
+  if (ws && ws.readyState === WebSocket.OPEN) {
+    ws.send(JSON.stringify({ type: 'focus', pid: pid }))
+    if (row) {
       // Pulse the row to confirm jump was sent
       row.classList.remove('jumping')
       void row.offsetWidth // force reflow to restart animation
@@ -354,25 +587,21 @@ function buildSessionRow(s, kind) {
       setTimeout(function () {
         row.classList.remove('jumping')
       }, 1300)
-      if (window.parade && typeof window.parade.debugLog === 'function') {
-        window.parade.debugLog('[jump] click pid=' + s.pid + ' ws=OPEN sent')
-      }
-    } else {
-      if (window.parade && typeof window.parade.debugLog === 'function') {
-        window.parade.debugLog(
-          '[jump] click pid=' +
-            s.pid +
-            ' ws=' +
-            (ws ? ws.readyState : 'null') +
-            ' NOT sent',
-        )
-      }
     }
-  })
-  row.appendChild(text)
-  row.insertBefore(jump, row.firstChild)
-
-  return row
+    if (window.parade && typeof window.parade.debugLog === 'function') {
+      window.parade.debugLog('[jump] click pid=' + pid + ' ws=OPEN sent')
+    }
+  } else {
+    if (window.parade && typeof window.parade.debugLog === 'function') {
+      window.parade.debugLog(
+        '[jump] click pid=' +
+          pid +
+          ' ws=' +
+          (ws ? ws.readyState : 'null') +
+          ' NOT sent',
+      )
+    }
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -381,12 +610,46 @@ function buildSessionRow(s, kind) {
 
 document.addEventListener('contextmenu', function (e) {
   e.preventDefault()
+  // Electron bridge: the menu opens as its own cursor-anchored popup window
+  // (see paradeWindow.ts 'parade-open-menu'), so it can extend beyond this
+  // window's bounds — the in-page fallback below is clipped by them, which
+  // truncated the menu on the small logo/mini modes.
+  if (window.parade && typeof window.parade.openMenu === 'function') {
+    window.parade.openMenu({ mode: displayMode, rot: cubeMode })
+    return
+  }
+  // Fallback (bridge missing — e.g. debugging the UI in a regular browser
+  // tab): show the in-page menu with flip/clamp positioning, accepting that
+  // it cannot leave the window.
   updateModeLabel()
+  updateViewMenu()
   ctxMenu.style.display = 'block'
-  ctxMenu.style.left = e.clientX + 'px'
-  ctxMenu.style.top = e.clientY + 'px'
+  // Flip/clamp positioning: the menu is taller than the logo/mini windows.
+  var mw = ctxMenu.offsetWidth
+  var mh = ctxMenu.offsetHeight
+  var x = Math.min(e.clientX, window.innerWidth - mw - 4)
+  var y = e.clientY
+  if (y + mh > window.innerHeight - 4) {
+    y = Math.max(4, e.clientY - mh)
+  }
+  ctxMenu.style.left = Math.max(4, x) + 'px'
+  ctxMenu.style.top = y + 'px'
 })
 
+// Actions arriving from the popup menu window (relayed via the main process).
+// The parade window stays the source of truth — the popup only reports what
+// was clicked, this side applies and persists it.
+if (window.parade && typeof window.parade.onMenuAction === 'function') {
+  window.parade.onMenuAction(function (action) {
+    if (!action || typeof action !== 'object') return
+    if (action.type === 'view' && MODES[action.value]) {
+      setMode(action.value)
+    } else if (action.type === 'rotation') {
+      toggleRotationMode()
+    }
+  })
+}
+
 // Frameless window drag + corner resize via IPC (Electron). Left-click on
 // the body starts a move-drag; left-click on a .corner-handle starts a
 // proportional resize. The main process polls the cursor and moves/resizes
@@ -425,6 +688,25 @@ document.addEventListener('click', function () {
   ctxMenu.style.display = 'none'
 })
 
+// View-mode radio items
+var viewItems = ctxMenu.querySelectorAll('.ctx-view')
+for (let vi = 0; vi < viewItems.length; vi++) {
+  viewItems[vi].addEventListener('click', function (e) {
+    e.stopPropagation()
+    ctxMenu.style.display = 'none'
+    setMode(this.getAttribute('data-view'))
+  })
+}
+
+function updateViewMenu() {
+  for (let i = 0; i < viewItems.length; i++) {
+    viewItems[i].classList.toggle(
+      'active',
+      viewItems[i].getAttribute('data-view') === displayMode,
+    )
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Close button (top-right corner)
 // ---------------------------------------------------------------------------
@@ -451,7 +733,7 @@ closeBtn.addEventListener('click', function () {
 // ---------------------------------------------------------------------------
 // Dynamic (default): cube rotates when sessions are running, static when idle.
 // Static (inverse): cube static when running, rotates when idle.
-// The context menu shows the *switchable* label (opposite of current mode).
+// The context menu shows the CURRENT mode.
 
 var cubeMode = 'dynamic'
 try {
@@ -461,11 +743,12 @@ try {
 }
 
 function updateModeLabel() {
-  ctxMode.textContent = cubeMode === 'dynamic' ? 'Static' : 'Dynamic'
+  ctxMode.textContent =
+    'Rotation: ' + (cubeMode === 'dynamic' ? 'Dynamic' : 'Static')
 }
 
-ctxMode.addEventListener('click', function () {
-  ctxMenu.style.display = 'none'
+// Shared by the in-page menu (fallback) and the popup menu action relay.
+function toggleRotationMode() {
   cubeMode = cubeMode === 'dynamic' ? 'static' : 'dynamic'
   try {
     localStorage.setItem('parade-cube-mode', cubeMode)
@@ -474,16 +757,54 @@ ctxMode.addEventListener('click', function () {
   }
   updateModeLabel()
   updateCubeRotation()
+}
+
+ctxMode.addEventListener('click', function (e) {
+  e.stopPropagation()
+  ctxMenu.style.display = 'none'
+  toggleRotationMode()
 })
 
 updateModeLabel()
 
+// ---------------------------------------------------------------------------
+// Wheel-to-cycle display modes (on the cube stage)
+// ---------------------------------------------------------------------------
+// Accumulates wheel deltas with a threshold + cooldown so a single notch
+// (or trackpad flood — the logo mode stage spans the whole window) flips
+// exactly one mode.
+
+var wheelAccum = 0
+var wheelLockUntil = 0
+
+cubeStageEl.addEventListener(
+  'wheel',
+  function (e) {
+    if (!e.deltaY) return
+    e.preventDefault()
+    var now = Date.now()
+    if (now < wheelLockUntil) return
+    wheelAccum += e.deltaY
+    if (Math.abs(wheelAccum) >= 120) {
+      const dir = wheelAccum > 0 ? 1 : -1
+      wheelAccum = 0
+      wheelLockUntil = now + 500
+      const idx = MODE_ORDER.indexOf(displayMode)
+      const next = Math.min(MODE_ORDER.length - 1, Math.max(0, idx + dir))
+      if (next !== idx) setMode(MODE_ORDER[next])
+    }
+  },
+  { passive: false },
+)
+
 // ---------------------------------------------------------------------------
 // CSS 3D Cube rotation control
 // ---------------------------------------------------------------------------
 // The cube is a CSS 3D transform element (see index.html <style>). Rotation
 // is driven by applying/removing the .rotating class, which toggles the
-// cube-spin @keyframes animation. Logic mirrors the previous WebGL loop:
+// cube-spin @keyframes animation plus the stage-level glow/halo pulses
+// (never on .cube itself — filter/opacity would flatten preserve-3d).
+// Logic mirrors the previous WebGL loop:
 //   Dynamic: rotate when runningCount > 0
 //   Static:  rotate when runningCount === 0 (inverse)
 
@@ -491,16 +812,17 @@ function updateCubeRotation() {
   if (!cubeEl) return
   var shouldRotate =
     cubeMode === 'dynamic' ? runningCount > 0 : runningCount === 0
-  if (shouldRotate) {
-    cubeEl.classList.add('rotating')
-  } else {
-    cubeEl.classList.remove('rotating')
-  }
+  cubeEl.classList.toggle('rotating', shouldRotate)
+  if (cubeStageEl) cubeStageEl.classList.toggle('rotating', shouldRotate)
 }
 
 // Apply initial state — re-evaluated on each WS message via updateCounts
 updateCubeRotation()
 
+// Apply the persisted mode/scale/window bounds as early as possible so a
+// detail-mode boot doesn't flash at the default 220x130 size.
+setMode(displayMode)
+
 // Start the WebSocket connection
 setWsStatus('connecting')
 connectWebSocket()