@phenx-inc/ctlsurf 0.12.1 → 0.13.4

package/src/renderer/components/CtlsurfPanel.tsx

@@ -1,65 +1,199 @@
-import { useRef, useEffect, useState } from 'react'
+import { useRef, useEffect, useState, useCallback } from 'react'
 
 interface CtlsurfPanelProps {
-  // An authenticated ctlsurf URL to load (e.g. from a terminal link click).
-  // `n` bumps per request so repeat navigations to the same URL still apply.
+  // A URL to load (e.g. from a terminal link click). `n` bumps per request so
+  // repeat navigations to the same URL still apply.
   navigate?: { url: string; n: number } | null
 }
 
+// The <webview> element exposes navigation methods at runtime that aren't in
+// React's typings — narrow the ref to the bits we use.
+type WebviewEl = HTMLElement & {
+  loadURL: (url: string) => void
+  goBack: () => void
+  goForward: () => void
+  reload: () => void
+  stop: () => void
+  canGoBack: () => boolean
+  canGoForward: () => boolean
+}
+
+// Strip the noisy auth/embed params so the address bar shows a clean URL.
+function displayUrl(raw: string): string {
+  try {
+    const u = new URL(raw)
+    u.searchParams.delete('_code')
+    u.searchParams.delete('embed')
+    return u.toString()
+  } catch {
+    return raw
+  }
+}
+
 export function CtlsurfPanel({ navigate }: CtlsurfPanelProps) {
-  const webviewRef = useRef<HTMLWebViewElement>(null)
-  const [url, setUrl] = useState<string | null>(null)
-  const [key, setKey] = useState(0) // force remount on cwd change / navigation
+  const webviewRef = useRef<WebviewEl | null>(null)
+  const [src, setSrc] = useState<string | null>(null) // initial webview src
+  const [address, setAddress] = useState('')          // editable address-bar text
+  const [loading, setLoading] = useState(false)
+  const [nav, setNav] = useState({ back: false, forward: false })
+  const [key, setKey] = useState(0)                   // remount on cwd change
+
+  const hasSrcRef = useRef(false)                // has the webview been seeded?
+  const readyRef = useRef(false)                 // is the webview dom-ready?
+  const pendingRef = useRef<string | null>(null) // url queued before dom-ready
+
+  // Resolve a raw URL to an authenticated ctlsurf embed URL when it points at
+  // ctlsurf, else return it unchanged.
+  const resolve = useCallback(async (raw: string): Promise<string> => {
+    try {
+      return (await window.worker.getEmbedUrl(raw)) || raw
+    } catch {
+      return raw
+    }
+  }, [])
+
+  // Load a URL into the webview. The first load seeds the `src` attribute (the
+  // element doesn't exist yet); later loads call loadURL so in-webview history
+  // stays intact for the back/forward buttons.
+  const load = useCallback((url: string) => {
+    if (!url) return
+    setAddress(displayUrl(url))
+    if (!hasSrcRef.current) {
+      hasSrcRef.current = true
+      setSrc(url)
+      return
+    }
+    const wv = webviewRef.current
+    if (wv && readyRef.current) wv.loadURL(url)
+    else pendingRef.current = url
+  }, [])
 
-  const loadUrl = async () => {
+  // Default-load the project page, preferring the authenticated page URL.
+  const loadProject = useCallback(async () => {
     try {
       const info = await window.worker.getWebviewInfo()
-      setUrl(info.pageUrl || info.frontendUrl)
+      load(info.pageUrl || info.frontendUrl)
     } catch (err) {
       console.error('[ctlsurf] Failed to get webview info:', err)
-      setUrl('https://app.ctlsurf.com')
+      load('https://app.ctlsurf.com')
     }
-  }
+  }, [load])
 
-  // Default-load the project page on mount, unless a navigation is already
-  // queued (e.g. the pane was just revealed to show a clicked link).
-  useEffect(() => { if (!navigate?.url) loadUrl() }, [])
+  // On mount, load the project page unless a navigation is already queued (e.g.
+  // the pane was just revealed to show a clicked link).
+  useEffect(() => { if (!navigate?.url) loadProject() }, [])
 
-  // Navigate to a specific authenticated URL when requested.
+  // Navigate to a specific URL when requested (terminal / external link click).
   useEffect(() => {
-    if (navigate?.url) {
-      setUrl(navigate.url)
-      setKey(k => k + 1)
-    }
+    if (navigate?.url) resolve(navigate.url).then(load)
   }, [navigate?.n])
 
-  // Reload webview when cwd changes
+  // Reload (remount) when the cwd changes — new project context.
   useEffect(() => {
     const unsub = window.worker.onCwdChanged(() => {
-      setUrl(null)
+      hasSrcRef.current = false
+      readyRef.current = false
+      pendingRef.current = null
+      setSrc(null)
       setKey(k => k + 1)
-      loadUrl()
+      loadProject()
     })
     return unsub
-  }, [])
+  }, [loadProject])
 
-  if (!url) {
-    return (
-      <div className="ctlsurf-panel" style={{ display: 'flex', alignItems: 'center', justifyContent: 'center' }}>
-        <span style={{ color: '#565f89', fontSize: '13px' }}>Loading ctlsurf...</span>
-      </div>
-    )
+  // Wire webview lifecycle + navigation events to the address bar.
+  useEffect(() => {
+    const wv = webviewRef.current
+    if (!wv) return
+    const syncNav = () =>
+      setNav({ back: wv.canGoBack?.() ?? false, forward: wv.canGoForward?.() ?? false })
+    const onReady = () => {
+      readyRef.current = true
+      if (pendingRef.current) {
+        wv.loadURL(pendingRef.current)
+        pendingRef.current = null
+      }
+      syncNav()
+    }
+    const onNavigate = (e: Event) => {
+      const url = (e as Event & { url?: string }).url
+      if (url) setAddress(displayUrl(url))
+      syncNav()
+    }
+    const onStart = () => setLoading(true)
+    const onStop = () => { setLoading(false); syncNav() }
+    wv.addEventListener('dom-ready', onReady)
+    wv.addEventListener('did-navigate', onNavigate)
+    wv.addEventListener('did-navigate-in-page', onNavigate)
+    wv.addEventListener('did-start-loading', onStart)
+    wv.addEventListener('did-stop-loading', onStop)
+    return () => {
+      wv.removeEventListener('dom-ready', onReady)
+      wv.removeEventListener('did-navigate', onNavigate)
+      wv.removeEventListener('did-navigate-in-page', onNavigate)
+      wv.removeEventListener('did-start-loading', onStart)
+      wv.removeEventListener('did-stop-loading', onStop)
+    }
+  }, [src, key])
+
+  const onSubmit = (e: React.FormEvent) => {
+    e.preventDefault()
+    let target = address.trim()
+    if (!target) return
+    // Bare hostnames (no scheme) default to https.
+    if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(target)) target = 'https://' + target
+    resolve(target).then(load)
   }
 
   return (
     <div className="ctlsurf-panel">
-      <webview
-        key={key}
-        ref={webviewRef as any}
-        src={url}
-        style={{ width: '100%', height: '100%' }}
-        allowpopups={'true' as any}
-      />
+      <div className="ctlsurf-addressbar">
+        <button
+          type="button"
+          className="ctlsurf-nav-btn"
+          title="Back"
+          disabled={!nav.back}
+          onClick={() => webviewRef.current?.goBack?.()}
+        >‹</button>
+        <button
+          type="button"
+          className="ctlsurf-nav-btn"
+          title="Forward"
+          disabled={!nav.forward}
+          onClick={() => webviewRef.current?.goForward?.()}
+        >›</button>
+        <button
+          type="button"
+          className="ctlsurf-nav-btn"
+          title={loading ? 'Stop' : 'Reload'}
+          onClick={() => (loading ? webviewRef.current?.stop?.() : webviewRef.current?.reload?.())}
+        >{loading ? '×' : '⟳'}</button>
+        <form className="ctlsurf-address-form" onSubmit={onSubmit}>
+          <input
+            className="ctlsurf-address-input"
+            value={address}
+            spellCheck={false}
+            placeholder="Enter a URL"
+            onChange={e => setAddress(e.target.value)}
+            onFocus={e => e.currentTarget.select()}
+          />
+        </form>
+      </div>
+      <div className="ctlsurf-webview-host">
+        {src ? (
+          <webview
+            key={key}
+            ref={webviewRef as any}
+            src={src}
+            style={{ width: '100%', height: '100%' }}
+            allowpopups={'true' as any}
+          />
+        ) : (
+          <div className="ctlsurf-webview-loading">
+            <span style={{ color: '#565f89', fontSize: '13px' }}>Loading ctlsurf...</span>
+          </div>
+        )}
+      </div>
     </div>
   )
 }

package/src/renderer/components/SettingsDialog.tsx

@@ -33,6 +33,7 @@ export function SettingsDialog({ open, onClose }: SettingsDialogProps) {
   const [trackTime, setTrackTime] = useState(false)
   const [idleTimeoutMin, setIdleTimeoutMin] = useState(15)
   const [saved, setSaved] = useState(false)
+  const [version, setVersion] = useState('')
 
   const loadProfiles = async () => {
     const data = await window.worker.listProfiles() as ProfileListResponse
@@ -45,6 +46,7 @@ export function SettingsDialog({ open, onClose }: SettingsDialogProps) {
       loadProfiles()
       setEditingId(null)
       setSaved(false)
+      window.worker.getVersion().then(setVersion).catch(() => { /* ignore */ })
     }
   }, [open])
 
@@ -235,6 +237,17 @@ export function SettingsDialog({ open, onClose }: SettingsDialogProps) {
             </div>
           </div>
         )}
+
+        <div className="settings-section settings-about">
+          <h4>About</h4>
+          <div className="about-name">ctlsurf{version ? ` · v${version}` : ''}</div>
+          <p className="about-copyright">© 2026 Phenx, Inc. All rights reserved.</p>
+          <p className="settings-hint">
+            Proprietary and confidential. No license to use, copy, modify, or
+            distribute is granted except under a separate written agreement with
+            Phenx, Inc.
+          </p>
+        </div>
       </div>
     </div>
   )

package/src/renderer/components/SpeakControls.tsx

@@ -40,6 +40,11 @@ export function SpeakControls({ remote = false }: { remote?: boolean }) {
     return () => { alive = false }
   }, [])
 
+  // Neural is the default engine; preload its model in the background on launch
+  // so the first spoken text isn't stalled by the one-time download. No-op when
+  // the user has explicitly switched to the system voice.
+  useEffect(() => { speech.warmup() }, [])
+
   // Speak replies as they arrive. Main only forwards when the setting is on, so
   // this is a no-op while disabled.
   useEffect(() => {

package/src/renderer/components/TerminalPanel.tsx

@@ -4,47 +4,69 @@ import { FitAddon } from '@xterm/addon-fit'
 import { WebLinksAddon } from '@xterm/addon-web-links'
 import '@xterm/xterm/css/xterm.css'
 import { convertToEmailTable } from '../lib/tableToHtml'
+import { speech } from '../lib/speech'
 
-// Convert the terminal's current selection into a rich HTML table on the
-// clipboard. Broadcasts an `email-table-result` event so the active panel can
-// show a toast. Reused by both the hotkey and the right-click menu.
-function copySelectionAsEmailTable(terminal: Terminal): void {
-  const result = convertToEmailTable(terminal.getSelection())
+// Show a transient toast in the active terminal panel. Broadcast as a window
+// event so module-level helpers (which have no component scope) can trigger it.
+function showTerminalToast(message: string): void {
+  window.dispatchEvent(new CustomEvent('terminal-toast', { detail: { message } }))
+}
+
+// ─── Text actions — operate on a plain string, which may be an xterm
+// selection (menu/shortcuts) or a DOM selection from the snapshot panel ───
+
+function copyTextValue(text: string): void {
+  if (!text) return
+  void window.worker.copyText(text)
+  showTerminalToast('Copied to clipboard')
+}
+
+function convertTextToTable(text: string): void {
+  const result = convertToEmailTable(text)
   if (result) {
     window.worker.copyEmailTable(result.html, result.text)
+    showTerminalToast(`Copied ${result.rows}×${result.cols} table to clipboard`)
+  } else {
+    showTerminalToast('No table found in selection')
   }
-  window.dispatchEvent(
-    new CustomEvent('email-table-result', {
-      detail: result
-        ? { ok: true, message: `Copied ${result.rows}×${result.cols} table to clipboard` }
-        : { ok: false, message: 'No table found in selection' },
-    })
-  )
 }
 
-// Open a URL in the system browser, mirroring WebLinksAddon's safe default
-// (clear the opener so the new page can't reach back into this window).
-function openExternal(uri: string): void {
-  const win = window.open()
-  if (win) {
-    try { (win as { opener: unknown }).opener = null } catch { /* ignore */ }
-    win.location.href = uri
+// unlock() is called from the triggering gesture so the neural voice isn't
+// autoplay-blocked.
+function speakTextValue(text: string): void {
+  if (!text.trim()) return
+  speech.unlock()
+  speech.enqueue(text)
+}
+
+// xterm-selection wrappers for the right-click menu and keyboard shortcuts.
+function copySelectionPlain(terminal: Terminal): void { copyTextValue(terminal.getSelection()) }
+function copySelectionAsEmailTable(terminal: Terminal): void { convertTextToTable(terminal.getSelection()) }
+function speakSelection(terminal: Terminal): void { speakTextValue(terminal.getSelection()) }
+
+// Snapshot the visible screen as plain text. xterm selections don't survive a
+// repainting TUI (Claude Code), so the snapshot panel freezes this text into a
+// static, normally-selectable surface instead.
+function captureVisibleText(terminal: Terminal): string {
+  const buf = terminal.buffer.active
+  const lines: string[] = []
+  for (let i = 0; i < terminal.rows; i++) {
+    const line = buf.getLine(buf.viewportY + i)
+    lines.push(line ? line.translateToString(true) : '')
   }
+  while (lines.length && lines[lines.length - 1].trim() === '') lines.pop()
+  return lines.join('\n')
 }
 
-// Custom handler for links clicked in the terminal. ctlsurf page links are
-// routed into the embedded (authenticated) ctlsurf panel via a window event;
-// everything else opens in the default browser as before.
+// Custom handler for links clicked in the terminal. Every clicked URL is routed
+// into the embedded ctlsurf browser panel via a window event: ctlsurf links are
+// first resolved to an authenticated embed URL, anything else loads as-is.
 function handleTerminalLink(_event: MouseEvent, uri: string): void {
+  const openInPanel = (url: string) =>
+    window.dispatchEvent(new CustomEvent('ctlsurf-open-url', { detail: { url } }))
   window.worker.getEmbedUrl(uri)
-    .then((embedUrl) => {
-      if (embedUrl) {
-        window.dispatchEvent(new CustomEvent('ctlsurf-open-url', { detail: { url: embedUrl } }))
-      } else {
-        openExternal(uri)
-      }
-    })
-    .catch(() => openExternal(uri))
+    .then((embedUrl) => openInPanel(embedUrl || uri))
+    .catch(() => openInPanel(uri))
 }
 
 interface AgentConfig {
@@ -177,20 +199,33 @@ function getOrCreateTerminal(tabId: string, onExit: (tabId: string) => void): {
   terminal.loadAddon(fitAddon)
   terminal.loadAddon(new WebLinksAddon(handleTerminalLink))
 
-  // ⌘/Ctrl+Shift+E → convert the current selection to an email table. Handled
-  // here (not as a DOM listener) so it works even while a mouse-tracking TUI
-  // is running, where right-click is forwarded to the program instead.
+  // Selection actions via ⌘/Ctrl+Shift+[C|E|S] → copy / convert-to-table /
+  // read-aloud. Handled here (not as DOM listeners) so they work even while a
+  // mouse-tracking TUI is running, where right-click and mouse selection are
+  // forwarded to the program instead.
   terminal.attachCustomKeyEventHandler((e) => {
     if (e.type !== 'keydown') return true
     // Buffer-scroll keys count as a user gesture (see onScroll).
     if (e.key === 'PageUp' || e.key === 'PageDown' || e.key === 'Home' || e.key === 'End') {
       markGesture(tabId)
     }
-    const isCombo = (e.metaKey || e.ctrlKey) && e.shiftKey && e.code === 'KeyE'
-    if (!isCombo) return true
-    e.preventDefault()
-    copySelectionAsEmailTable(terminal)
-    return false // consume — don't forward to the pty
+    const mod = (e.metaKey || e.ctrlKey) && e.shiftKey
+    if (mod && e.code === 'KeyE') {
+      e.preventDefault()
+      copySelectionAsEmailTable(terminal)
+      return false // consume — don't forward to the pty
+    }
+    if (mod && e.code === 'KeyC' && terminal.hasSelection()) {
+      e.preventDefault()
+      copySelectionPlain(terminal)
+      return false
+    }
+    if (mod && e.code === 'KeyS' && terminal.getSelection().trim()) {
+      e.preventDefault()
+      speakSelection(terminal)
+      return false
+    }
+    return true
   })
 
   const state: TermState = {
@@ -275,6 +310,11 @@ export function destroyTerminal(tabId: string): void {
 export function TerminalPanel({ tabId, agent, onSpawn, onExit, isActive }: TerminalPanelProps) {
   const containerRef = useRef<HTMLDivElement>(null)
   const [menu, setMenu] = useState<{ x: number; y: number } | null>(null)
+  // Snapshot panel: the ⋮ button freezes the visible screen text into a static,
+  // selectable overlay where Copy/Table/Speak work even over a repainting TUI
+  // (which wipes live xterm selections). snapTextRef holds the frozen text.
+  const [snapOpen, setSnapOpen] = useState(false)
+  const snapTextRef = useRef('')
   const [toast, setToast] = useState<string | null>(null)
   // Mirrors the terminal's follow-mode; drives the "jump to latest" overlay,
   // which only shows while the user has scrolled up.
@@ -288,29 +328,60 @@ export function TerminalPanel({ tabId, agent, onSpawn, onExit, isActive }: Termi
     s.terminal.focus()
   }
 
-  // Right-click → offer "Copy as email table", but only when the current
-  // selection actually parses as a table; otherwise fall through to default.
+  // Right-click on a non-empty selection → show Copy / Convert to table /
+  // Read it. With nothing selected we let the native menu through.
   const handleContextMenu = (e: React.MouseEvent) => {
     const sel = _terminals.get(tabId)?.terminal.getSelection() ?? ''
-    if (!convertToEmailTable(sel)) return
+    if (!sel.trim()) return
     e.preventDefault()
     setMenu({ x: e.clientX, y: e.clientY })
   }
 
+  // Right-click menu actions (act on the live xterm selection — only reliable
+  // over static output / a plain shell, not a repainting TUI).
+  const runCopy = () => {
+    const term = _terminals.get(tabId)?.terminal
+    if (term) copySelectionPlain(term)
+    setMenu(null)
+  }
+
   const runConvert = () => {
     const term = _terminals.get(tabId)?.terminal
     if (term) copySelectionAsEmailTable(term)
     setMenu(null)
   }
 
-  // Show a transient toast when a conversion happens (hotkey or menu).
+  const runSpeak = () => {
+    const term = _terminals.get(tabId)?.terminal
+    if (term) speakSelection(term)
+    setMenu(null)
+  }
+
+  // Snapshot panel: freeze the visible screen, then act on the user's DOM
+  // selection within it (or the whole snapshot if nothing is selected).
+  const openSnapshot = () => {
+    const term = _terminals.get(tabId)?.terminal
+    snapTextRef.current = term ? captureVisibleText(term) : ''
+    setSnapOpen(true)
+  }
+
+  const snapAction = (kind: 'copy' | 'table' | 'speak') => {
+    const domSel = window.getSelection()?.toString() ?? ''
+    const text = domSel.trim() ? domSel : snapTextRef.current
+    if (kind === 'copy') copyTextValue(text)
+    else if (kind === 'table') convertTextToTable(text)
+    else speakTextValue(text)
+  }
+
+  // Show a transient toast on a terminal action (copy / table), fired by the
+  // module-level helpers as a window event.
   useEffect(() => {
-    const onResult = (e: Event) => {
-      const detail = (e as CustomEvent).detail as { ok: boolean; message: string } | null
-      if (detail) setToast(detail.message)
+    const onToast = (e: Event) => {
+      const detail = (e as CustomEvent).detail as { message?: string } | null
+      if (detail?.message) setToast(detail.message)
     }
-    window.addEventListener('email-table-result', onResult)
-    return () => window.removeEventListener('email-table-result', onResult)
+    window.addEventListener('terminal-toast', onToast)
+    return () => window.removeEventListener('terminal-toast', onToast)
   }, [])
 
   useEffect(() => {
@@ -459,11 +530,47 @@ export function TerminalPanel({ tabId, agent, onSpawn, onExit, isActive }: Termi
             ↓ Latest
           </button>
         )}
+        <button
+          type="button"
+          className="term-util-btn"
+          onMouseDown={(e) => { e.preventDefault(); openSnapshot() }}
+          title="Snapshot screen → copy / convert to table / read aloud"
+        >
+          ⋮
+        </button>
+        {snapOpen && (
+          <div className="term-snapshot">
+            <div className="term-snapshot-head">
+              <span>Select text below (or select nothing to use everything), then pick an action.</span>
+              <button
+                type="button"
+                className="term-snapshot-x"
+                onMouseDown={(e) => { e.preventDefault(); setSnapOpen(false) }}
+                title="Close"
+              >
+                ✕
+              </button>
+            </div>
+            <pre className="term-snapshot-text">{snapTextRef.current}</pre>
+            <div className="term-snapshot-actions">
+              <button type="button" onMouseDown={(e) => { e.preventDefault(); snapAction('copy') }}>⧉ Copy</button>
+              <button type="button" onMouseDown={(e) => { e.preventDefault(); snapAction('table') }}>▦ Convert to table</button>
+              <button type="button" onMouseDown={(e) => { e.preventDefault(); snapAction('speak') }}>🔊 Read aloud</button>
+              <button type="button" className="term-snapshot-done" onMouseDown={(e) => { e.preventDefault(); setSnapOpen(false) }}>Close</button>
+            </div>
+          </div>
+        )}
       </div>
       {menu && (
         <div className="term-context-menu" style={{ position: 'fixed', left: menu.x, top: menu.y }}>
+          <button type="button" onMouseDown={(e) => { e.preventDefault(); runCopy() }}>
+            Copy
+          </button>
           <button type="button" onMouseDown={(e) => { e.preventDefault(); runConvert() }}>
-            Copy as email table
+            Convert to table
+          </button>
+          <button type="button" onMouseDown={(e) => { e.preventDefault(); runSpeak() }}>
+            Read it
           </button>
         </div>
       )}