@skyhook-io/k8s-ui 1.8.0 → 1.8.2

package/src/components/applications/applications-view.test.tsx

@@ -0,0 +1,147 @@
+import { describe, it, expect } from 'vitest'
+import {
+  buildSingleAppEntry,
+  searchTextForEntry,
+  foldAppGroups,
+  type AppRow,
+  type SingleAppEntry,
+} from '../../utils/applications'
+
+// Parity tests for the pure core the shared ApplicationsView is built on:
+// buildSingleAppEntry (the extracted former buildEntry), the search-text helper,
+// and the fold. These pin that the single variant behaves exactly as the old
+// ApplicationsList body did — fold grouping, facet counts, search matching.
+
+const wl = (over: Partial<AppRow['workloads'][number]> = {}): AppRow['workloads'][number] => ({
+  kind: 'Deployment',
+  namespace: 'default',
+  name: 'svc',
+  workload_class: 'service',
+  health: 'healthy',
+  ready: 1,
+  desired: 1,
+  restarts: 0,
+  ...over,
+})
+
+const app = (over: Partial<AppRow> = {}): AppRow => ({
+  key: over.key ?? 'default/svc',
+  name: over.name ?? 'svc',
+  namespace: 'default',
+  health: 'healthy',
+  workloads: [wl()],
+  ...over,
+})
+
+describe('buildSingleAppEntry', () => {
+  it('tags the single variant and aggregates ready/desired + kinds', () => {
+    const e = buildSingleAppEntry(
+      app({
+        workloads: [
+          wl({ kind: 'Deployment', ready: 2, desired: 3 }),
+          wl({ kind: 'CronJob', workload_class: 'job', ready: 0, desired: 0 }),
+        ],
+      }),
+    )
+    expect(e.variant).toBe('single')
+    expect(e.ready).toBe(2)
+    expect(e.desired).toBe(3)
+    expect(e.readyRatio).toBeCloseTo(2 / 3)
+    expect(e.kinds).toEqual({ Deployment: 1, CronJob: 1 })
+    // service + job → mixed for the facet set; class set is inclusive.
+    expect(e.classSet.sort()).toEqual(['job', 'service'])
+  })
+
+  it('resolves env from the namespace heuristic and marks it inferred', () => {
+    const e = buildSingleAppEntry(app({ namespace: 'billing-prod', workloads: [wl({ namespace: 'billing-prod' })] }))
+    expect(e.env).toBe('prod')
+    expect(e.envInferred).toBe(true)
+  })
+
+  it('takes the identity env as authoritative (not inferred when declared)', () => {
+    const e = buildSingleAppEntry(
+      app({
+        identity: { key: 'svc', env: 'staging', confidence: 'high', evidence: 'declared source path' },
+      }),
+    )
+    expect(e.env).toBe('staging')
+    expect(e.envInferred).toBe(false)
+  })
+})
+
+describe('searchTextForEntry (single)', () => {
+  it('matches on name, namespace, version, env, and workload kind', () => {
+    const e = buildSingleAppEntry(
+      app({
+        name: 'checkout',
+        namespace: 'shop-prod',
+        versions: ['1.4.2'],
+        workloads: [wl({ kind: 'StatefulSet', namespace: 'shop-prod' })],
+      }),
+    )
+    const text = searchTextForEntry(e)
+    expect(text).toContain('checkout')
+    expect(text).toContain('shop-prod')
+    expect(text).toContain('1.4.2')
+    expect(text).toContain('prod')
+    expect(text).toContain('statefulset')
+    expect(text).not.toContain('zzz-no-match')
+  })
+})
+
+// One logical app across two envs must fold into a single group row with two
+// instance children; an orphan (filtered to one member) must render flat.
+describe('foldAppGroups over single entries', () => {
+  const ident = (env: string) => ({ key: 'shop', env, confidence: 'high', evidence: 'declared source path' })
+
+  const mkSibling = (env: string): SingleAppEntry =>
+    buildSingleAppEntry(
+      app({ key: `shop-${env}/web`, name: `web-${env}`, namespace: `shop-${env}`, identity: ident(env), versions: ['1.0.0'] }),
+    )
+
+  it('folds ≥2 same-identity instances into one group with nested instances', () => {
+    const entries = [mkSibling('dev'), mkSibling('prod')]
+    const collapsed = foldAppGroups(entries, new Set(), false)
+    expect(collapsed).toHaveLength(1)
+    expect(collapsed[0].kind).toBe('group')
+    if (collapsed[0].kind === 'group') {
+      expect(collapsed[0].members).toHaveLength(2)
+      expect(collapsed[0].cells.map((c) => c.env).sort()).toEqual(['dev', 'prod'])
+    }
+
+    const expanded = foldAppGroups(entries, new Set(['shop']), false)
+    // group row + two instance children
+    expect(expanded).toHaveLength(3)
+    expect(expanded.filter((r) => r.kind === 'instance')).toHaveLength(2)
+  })
+
+  it('renders a lone surviving member as a flat instance, not a group', () => {
+    const out = foldAppGroups([mkSibling('dev')], new Set(), false)
+    expect(out).toHaveLength(1)
+    expect(out[0].kind).toBe('instance')
+  })
+
+  it('auto-expands every group when the search flag is set', () => {
+    const out = foldAppGroups([mkSibling('dev'), mkSibling('prod')], new Set(), true)
+    expect(out[0].kind).toBe('group')
+    if (out[0].kind === 'group') expect(out[0].expanded).toBe(true)
+    expect(out.filter((r) => r.kind === 'instance')).toHaveLength(2)
+  })
+
+  it('builds the env ladder from envsOf (per-cluster slices), not identity.env', () => {
+    // A fleet member can span several per-cluster envs; envsOf supplies them so
+    // the ladder shows every env, including ones that are not the member's own
+    // identity.env (which the hub can stale on a same-key cross-cluster join).
+    const a = mkSibling('dev')
+    const b = mkSibling('prod')
+    const envsOf = (e: SingleAppEntry) =>
+      e.env === 'dev'
+        ? [{ env: 'dev', health: 'healthy' as const }, { env: 'staging', health: 'degraded' as const }]
+        : [{ env: 'prod', health: 'healthy' as const }]
+    const out = foldAppGroups([a, b], new Set(), false, { envsOf })
+    expect(out[0].kind).toBe('group')
+    if (out[0].kind === 'group') {
+      expect(out[0].cells.map((c) => c.env).sort()).toEqual(['dev', 'prod', 'staging'])
+    }
+  })
+})

package/src/components/applications/index.ts

@@ -1,5 +1,9 @@
 export { ApplicationsList } from './ApplicationsList'
 export type { ApplicationsListProps } from './ApplicationsList'
+export { ApplicationsView } from './ApplicationsView'
+export type { ApplicationsViewProps } from './ApplicationsView'
+export type { AppEntry, SingleAppEntry, FleetAppEntry, EnvSlice, AppClusterRef } from '../../utils/applications'
+export { buildSingleAppEntry } from '../../utils/applications'
 // Facet moved to the shared ui/ primitives; re-exported here for compatibility.
 export { Facet } from '../ui/Facet'
 export { ApplicationDetail } from './ApplicationDetail'

package/src/components/checks/ChecksView.tsx

@@ -820,9 +820,9 @@ function FindingLine({
         </button>
       ) : resourceHref ? (
         // Opens in a new tab to match the ExternalLink glyph in `body`. For the
-        // Hub fleet view this href crosses the Hub→Cluster SPA boundary (a full
+        // Hub fleet view this href crosses the Hub to Cluster route-tree boundary (a full
         // document nav); a new tab keeps the Checks queue intact and avoids the
-        // cross-tree browser-Back dead-end (SKY-931).
+        // cross-tree browser-Back dead-end.
         <a href={resourceHref(r)} target="_blank" rel="noreferrer" className={cls}>
           {body}
         </a>

package/src/components/dock/LocalTerminalTab.tsx

@@ -5,6 +5,9 @@ import { WebLinksAddon } from '@xterm/addon-web-links'
 import '@xterm/xterm/css/xterm.css'
 import { RefreshCw } from 'lucide-react'
 import { clsx } from 'clsx'
+import { setupTerminalClipboard, copyTerminalSelection } from './terminalClipboard'
+import { TerminalClipboardToolbar } from './TerminalClipboardToolbar'
+import { useMultilinePasteConfirm } from './useMultilinePasteConfirm'
 
 export interface LocalTerminalTabProps {
   isActive?: boolean
@@ -30,6 +33,12 @@ export function LocalTerminalTab({
   const [isConnected, setIsConnected] = useState(false)
   const [isConnecting, setIsConnecting] = useState(true)
   const [error, setError] = useState<string | null>(null)
+  const [hasSelection, setHasSelection] = useState(false)
+  const { confirmPaste, pasteDialog } = useMultilinePasteConfirm()
+
+  const handleCopy = useCallback(() => {
+    if (xtermRef.current) copyTerminalSelection(xtermRef.current)
+  }, [])
 
   const connect = useCallback(() => {
     if (!terminalRef.current) return
@@ -82,6 +91,12 @@ export function LocalTerminalTab({
     xtermRef.current = xterm
     fitAddonRef.current = fitAddon
 
+    setHasSelection(false)
+    const disposeClipboard = setupTerminalClipboard(xterm, terminalRef.current, {
+      confirmPaste,
+      onSelectionChange: setHasSelection,
+    })
+
     const doFit = (ws?: WebSocket) => {
       const dims = fitAddon.proposeDimensions()
       if (dims) xterm.resize(dims.cols, dims.rows)
@@ -123,7 +138,10 @@ export function LocalTerminalTab({
       }, 100)
     })
     resizeObserver.observe(terminalRef.current)
-    cleanupRef.current = () => resizeObserver.disconnect()
+    cleanupRef.current = () => {
+      resizeObserver.disconnect()
+      disposeClipboard()
+    }
 
     createSessionRef.current()
       .then(({ wsUrl }) => {
@@ -229,6 +247,8 @@ export function LocalTerminalTab({
             Reconnect
           </button>
         )}
+
+        {!error && <TerminalClipboardToolbar hasSelection={hasSelection} onCopy={handleCopy} />}
       </div>
 
       {/* Terminal or error */}
@@ -247,6 +267,7 @@ export function LocalTerminalTab({
       ) : (
         <div key="terminal" ref={terminalRef} className="absolute top-8 left-0 right-0 bottom-0 bg-[#0f172a] [&_.xterm-viewport]:!bg-[#0f172a]" />
       )}
+      {pasteDialog}
     </div>
   )
 }

package/src/components/dock/TerminalClipboardToolbar.tsx

@@ -0,0 +1,35 @@
+import { Copy } from 'lucide-react'
+import { isMac } from '../../utils/platform'
+
+/**
+ * Right-aligned clipboard affordances for a terminal mini-toolbar: an explicit
+ * Copy button (enabled only when there's a selection — we don't copy-on-select)
+ * and a muted paste hint that truncates on narrow docks. Shared by TerminalTab
+ * and LocalTerminalTab.
+ */
+export function TerminalClipboardToolbar({
+  hasSelection,
+  onCopy,
+}: {
+  hasSelection: boolean
+  onCopy: () => void
+}) {
+  // Copy is an explicit button (+ ⌘C on macOS), so the hint just covers paste.
+  const hint = isMac() ? '⌘V to paste' : 'Right-click or Ctrl+V to paste'
+  return (
+    <>
+      <button
+        onClick={onCopy}
+        disabled={!hasSelection}
+        title="Copy selection"
+        className="ml-auto flex items-center gap-1 px-2 py-0.5 text-xs text-theme-text-tertiary hover:text-theme-text-primary hover:bg-theme-elevated rounded disabled:opacity-40 disabled:hover:bg-transparent disabled:cursor-default"
+      >
+        <Copy className="w-3 h-3" />
+        Copy
+      </button>
+      <span className="min-w-0 truncate text-[11px] text-theme-text-tertiary/70" title={hint}>
+        {hint}
+      </span>
+    </>
+  )
+}

package/src/components/dock/TerminalTab.tsx

@@ -5,6 +5,9 @@ import { WebLinksAddon } from '@xterm/addon-web-links'
 import '@xterm/xterm/css/xterm.css'
 import { RefreshCw, ChevronDown, Bug } from 'lucide-react'
 import { clsx } from 'clsx'
+import { setupTerminalClipboard, copyTerminalSelection } from './terminalClipboard'
+import { TerminalClipboardToolbar } from './TerminalClipboardToolbar'
+import { useMultilinePasteConfirm } from './useMultilinePasteConfirm'
 
 export interface TerminalTabProps {
   namespace: string
@@ -46,6 +49,12 @@ export function TerminalTab({
   const [errorType, setErrorType] = useState<string | null>(null)
   const [isCreatingDebug, setIsCreatingDebug] = useState(false)
   const [selectedContainer, setSelectedContainer] = useState(containerName)
+  const [hasSelection, setHasSelection] = useState(false)
+  const { confirmPaste, pasteDialog } = useMultilinePasteConfirm()
+
+  const handleCopy = useCallback(() => {
+    if (xtermRef.current) copyTerminalSelection(xtermRef.current)
+  }, [])
 
   const connect = useCallback(() => {
     if (!terminalRef.current) return
@@ -99,6 +108,12 @@ export function TerminalTab({
     xtermRef.current = xterm
     fitAddonRef.current = fitAddon
 
+    setHasSelection(false)
+    const disposeClipboard = setupTerminalClipboard(xterm, terminalRef.current, {
+      confirmPaste,
+      onSelectionChange: setHasSelection,
+    })
+
     const doFit = (ws?: WebSocket) => {
       const dims = fitAddon.proposeDimensions()
       if (dims) xterm.resize(dims.cols, dims.rows)
@@ -140,7 +155,10 @@ export function TerminalTab({
       }, 100)
     })
     resizeObserver.observe(terminalRef.current)
-    cleanupRef.current = () => resizeObserver.disconnect()
+    cleanupRef.current = () => {
+      resizeObserver.disconnect()
+      disposeClipboard()
+    }
 
     createSessionRef.current(selectedContainer)
       .then(({ wsUrl }) => {
@@ -276,6 +294,8 @@ export function TerminalTab({
             Reconnect
           </button>
         )}
+
+        {!error && <TerminalClipboardToolbar hasSelection={hasSelection} onCopy={handleCopy} />}
       </div>
 
       {/* Terminal or error — key forces xterm canvas unmount/remount on toggle */}
@@ -330,6 +350,7 @@ export function TerminalTab({
       ) : (
         <div key="terminal" ref={terminalRef} className="absolute top-8 left-0 right-0 bottom-0 bg-[#0f172a] [&_.xterm-viewport]:!bg-[#0f172a]" />
       )}
+      {pasteDialog}
     </div>
   )
 }

package/src/components/dock/terminalClipboard.test.ts

@@ -0,0 +1,221 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { setupTerminalClipboard, copyTerminalSelection } from './terminalClipboard'
+
+// Minimal fakes — the helper touches onSelectionChange/getSelection/hasSelection/
+// paste/modes/attachCustomKeyEventHandler on the terminal and add/removeEventListener
+// on the element.
+function makeXterm(opts: { selection?: string; bracketed?: boolean } = {}) {
+  let selCb: (() => void) | null = null
+  let keyHandler: ((e: KeyboardEvent) => boolean) | null = null
+  const selection = opts.selection ?? ''
+  return {
+    _fireSelection: () => selCb?.(),
+    _key: (e: Partial<KeyboardEvent>) => keyHandler?.(e as KeyboardEvent),
+    onSelectionChange: vi.fn((fn: () => void) => { selCb = fn; return { dispose: vi.fn() } }),
+    attachCustomKeyEventHandler: vi.fn((fn: (e: KeyboardEvent) => boolean) => { keyHandler = fn }),
+    getSelection: vi.fn(() => selection),
+    hasSelection: vi.fn(() => selection.length > 0),
+    paste: vi.fn(),
+    modes: { bracketedPasteMode: opts.bracketed ?? false },
+  }
+}
+
+function makeElement() {
+  const handlers: Record<string, EventListener> = {}
+  return {
+    handlers,
+    addEventListener: vi.fn((type: string, fn: EventListener) => { handlers[type] = fn }),
+    removeEventListener: vi.fn((type: string) => { delete handlers[type] }),
+  }
+}
+
+function makePasteEvent(text: string) {
+  return { clipboardData: { getData: () => text }, preventDefault: vi.fn(), stopImmediatePropagation: vi.fn() }
+}
+
+const flush = () => new Promise((r) => setTimeout(r, 0))
+
+function setPlatform(platform: string) {
+  Object.defineProperty(globalThis, 'navigator', {
+    value: {
+      platform,
+      clipboard: {
+        writeText: vi.fn(() => Promise.resolve()),
+        readText: vi.fn(() => Promise.resolve('line one\nline two')),
+      },
+    },
+    configurable: true,
+  })
+}
+
+const origNavigator = globalThis.navigator
+const allow = () => Promise.resolve(true)
+const deny = () => Promise.resolve(false)
+
+beforeEach(() => setPlatform('Linux x86_64'))
+afterEach(() => {
+  Object.defineProperty(globalThis, 'navigator', { value: origNavigator, configurable: true })
+  vi.restoreAllMocks()
+})
+
+describe('copyTerminalSelection', () => {
+  it('writes the selection to the clipboard', () => {
+    copyTerminalSelection(makeXterm({ selection: 'pod-123' }) as never)
+    expect(navigator.clipboard.writeText).toHaveBeenCalledWith('pod-123')
+  })
+
+  it('is a no-op when nothing is selected', () => {
+    copyTerminalSelection(makeXterm({ selection: '' }) as never)
+    expect(navigator.clipboard.writeText).not.toHaveBeenCalled()
+  })
+})
+
+describe('setupTerminalClipboard — selection reporting (no copy-on-select)', () => {
+  it('reports selection presence but never copies on selection', () => {
+    const xterm = makeXterm({ selection: 'hello' })
+    const onSelectionChange = vi.fn()
+    setupTerminalClipboard(xterm as never, makeElement() as never, { onSelectionChange })
+    xterm._fireSelection()
+    expect(onSelectionChange).toHaveBeenCalledWith(true)
+    expect(navigator.clipboard.writeText).not.toHaveBeenCalled() // <- key: selecting does NOT copy
+  })
+})
+
+describe('setupTerminalClipboard — ⌘C copy on macOS', () => {
+  beforeEach(() => setPlatform('MacIntel'))
+
+  it('copies the selection on ⌘C and swallows the event', () => {
+    const xterm = makeXterm({ selection: 'cmd-c-text' })
+    setupTerminalClipboard(xterm as never, makeElement() as never)
+    const e = { type: 'keydown', metaKey: true, key: 'c', preventDefault: vi.fn() }
+    const result = xterm._key(e)
+    expect(navigator.clipboard.writeText).toHaveBeenCalledWith('cmd-c-text')
+    expect(e.preventDefault).toHaveBeenCalled()
+    expect(result).toBe(false)
+  })
+
+  it('leaves Ctrl+C alone so it still sends SIGINT', () => {
+    const xterm = makeXterm({ selection: 'x' })
+    setupTerminalClipboard(xterm as never, makeElement() as never)
+    const result = xterm._key({ type: 'keydown', ctrlKey: true, key: 'c', preventDefault: vi.fn() })
+    expect(navigator.clipboard.writeText).not.toHaveBeenCalled()
+    expect(result).toBe(true)
+  })
+
+  it('does not treat ⌘⇧C as copy (leaves the chord for the browser)', () => {
+    const xterm = makeXterm({ selection: 'x' })
+    setupTerminalClipboard(xterm as never, makeElement() as never)
+    const result = xterm._key({ type: 'keydown', metaKey: true, shiftKey: true, key: 'C', preventDefault: vi.fn() })
+    expect(navigator.clipboard.writeText).not.toHaveBeenCalled()
+    expect(result).toBe(true)
+  })
+
+  it('does nothing on ⌘C with no selection', () => {
+    const xterm = makeXterm({ selection: '' })
+    setupTerminalClipboard(xterm as never, makeElement() as never)
+    const result = xterm._key({ type: 'keydown', metaKey: true, key: 'c', preventDefault: vi.fn() })
+    expect(navigator.clipboard.writeText).not.toHaveBeenCalled()
+    expect(result).toBe(true)
+  })
+})
+
+describe('setupTerminalClipboard — no copy keybinding off macOS', () => {
+  it('does not attach a key handler on Linux/Windows (Copy button only)', () => {
+    const xterm = makeXterm({ selection: 'x' })
+    setupTerminalClipboard(xterm as never, makeElement() as never)
+    expect(xterm.attachCustomKeyEventHandler).not.toHaveBeenCalled()
+  })
+})
+
+describe('setupTerminalClipboard — right-click paste (non-mac)', () => {
+  it('pastes via xterm.paste on right-click', async () => {
+    const xterm = makeXterm()
+    const el = makeElement()
+    setupTerminalClipboard(xterm as never, el as never, { confirmPaste: allow })
+    expect(el.addEventListener).toHaveBeenCalledWith('contextmenu', expect.any(Function))
+    await el.handlers.contextmenu({ preventDefault: vi.fn() } as never)
+    await flush()
+    expect(xterm.paste).toHaveBeenCalledWith('line one\nline two')
+  })
+
+  it('does not paste when the multi-line confirmation is declined', async () => {
+    const xterm = makeXterm()
+    const el = makeElement()
+    const confirmPaste = vi.fn(deny)
+    setupTerminalClipboard(xterm as never, el as never, { confirmPaste })
+    await el.handlers.contextmenu({ preventDefault: vi.fn() } as never)
+    await flush()
+    expect(confirmPaste).toHaveBeenCalled()
+    expect(xterm.paste).not.toHaveBeenCalled()
+  })
+})
+
+describe('setupTerminalClipboard — multi-line paste guard', () => {
+  it('blocks a declined multi-line paste when bracketed-paste is off', async () => {
+    const xterm = makeXterm({ bracketed: false })
+    const el = makeElement()
+    const confirmPaste = vi.fn(deny)
+    setupTerminalClipboard(xterm as never, el as never, { confirmPaste })
+    const ev = makePasteEvent('rm -rf /tmp/a\nrm -rf /tmp/b')
+    el.handlers.paste(ev as never)
+    expect(ev.preventDefault).toHaveBeenCalled()
+    expect(ev.stopImmediatePropagation).toHaveBeenCalled()
+    expect(confirmPaste).toHaveBeenCalledWith({ lineCount: 2, text: 'rm -rf /tmp/a\nrm -rf /tmp/b' })
+    await flush()
+    expect(xterm.paste).not.toHaveBeenCalled()
+  })
+
+  it('confirms then pastes a multi-line paste that is accepted', async () => {
+    const xterm = makeXterm({ bracketed: false })
+    const el = makeElement()
+    setupTerminalClipboard(xterm as never, el as never, { confirmPaste: allow })
+    const ev = makePasteEvent('one\ntwo\nthree')
+    el.handlers.paste(ev as never)
+    expect(ev.preventDefault).toHaveBeenCalled()
+    await flush()
+    expect(xterm.paste).toHaveBeenCalledWith('one\ntwo\nthree')
+  })
+
+  it('does not paste once the helper is disposed (reconnect/teardown mid-confirm)', async () => {
+    const xterm = makeXterm({ bracketed: false })
+    const el = makeElement()
+    const dispose = setupTerminalClipboard(xterm as never, el as never, { confirmPaste: allow })
+    el.handlers.paste(makePasteEvent('one\ntwo') as never)
+    dispose() // terminal torn down before the (already-resolved) confirm runs
+    await flush()
+    expect(xterm.paste).not.toHaveBeenCalled()
+  })
+
+  it('does not warn on a single-line paste', () => {
+    const el = makeElement()
+    const confirmPaste = vi.fn(allow)
+    setupTerminalClipboard(makeXterm({ bracketed: false }) as never, el as never, { confirmPaste })
+    const ev = makePasteEvent('just one line\n')
+    el.handlers.paste(ev as never)
+    expect(confirmPaste).not.toHaveBeenCalled()
+    expect(ev.preventDefault).not.toHaveBeenCalled()
+  })
+
+  it('does not warn when bracketed-paste mode is on, even for multi-line', () => {
+    const el = makeElement()
+    const confirmPaste = vi.fn(allow)
+    setupTerminalClipboard(makeXterm({ bracketed: true }) as never, el as never, { confirmPaste })
+    const ev = makePasteEvent('one\ntwo')
+    el.handlers.paste(ev as never)
+    expect(confirmPaste).not.toHaveBeenCalled()
+    expect(ev.preventDefault).not.toHaveBeenCalled()
+  })
+})
+
+describe('setupTerminalClipboard — teardown', () => {
+  it('disposer removes listeners and disposes the selection listener', () => {
+    const xterm = makeXterm()
+    const el = makeElement()
+    const dispose = setupTerminalClipboard(xterm as never, el as never, { confirmPaste: allow })
+    const selectionDisposable = xterm.onSelectionChange.mock.results[0].value
+    dispose()
+    expect(selectionDisposable.dispose).toHaveBeenCalled()
+    expect(el.removeEventListener).toHaveBeenCalledWith('paste', expect.any(Function), true)
+    expect(el.removeEventListener).toHaveBeenCalledWith('contextmenu', expect.any(Function))
+  })
+})

package/src/components/dock/terminalClipboard.ts

@@ -0,0 +1,122 @@
+import type { Terminal as XTerm } from '@xterm/xterm'
+import { isMac } from '../../utils/platform'
+
+export interface PasteConfirmInfo {
+  lineCount: number
+  text: string
+}
+
+/** Asks the host to confirm a risky paste; resolves true to proceed. */
+export type PasteConfirmer = (info: PasteConfirmInfo) => Promise<boolean>
+
+export interface TerminalClipboardOptions {
+  confirmPaste?: PasteConfirmer
+  /** Notified when the selection changes; drives the toolbar Copy button's enabled state. */
+  onSelectionChange?: (hasSelection: boolean) => void
+}
+
+/** Copies the terminal's current selection to the clipboard. No-op if nothing is selected. */
+export function copyTerminalSelection(xterm: XTerm): void {
+  const selection = xterm.getSelection()
+  if (selection) navigator.clipboard.writeText(selection).catch(() => {})
+}
+
+function pasteLineCount(text: string): number {
+  return text.replace(/\r\n?/g, '\n').replace(/\n+$/, '').split('\n').length
+}
+
+/**
+ * A paste is risky when it spans multiple lines AND the shell hasn't enabled
+ * bracketed-paste mode — without that mode every newline runs as a command, so
+ * the paste auto-executes. Mirrors VS Code's default: warn only when the paste
+ * would actually run (modern bash/zsh enable bracketed paste; sh/ash/dash don't).
+ */
+function isRiskyMultilinePaste(xterm: XTerm, text: string): boolean {
+  if (xterm.modes.bracketedPasteMode) return false
+  return text.replace(/\r\n?/g, '\n').trim().includes('\n')
+}
+
+/**
+ * Wires terminal clipboard behavior onto an xterm instance.
+ *
+ * Copy is explicit — the host's toolbar Copy button (via copyTerminalSelection)
+ * and ⌘C on macOS (Ctrl+C stays SIGINT). We deliberately do NOT copy on
+ * selection: a browser terminal has a single system clipboard with no separate
+ * PRIMARY buffer, so copy-on-select would clobber the clipboard on every
+ * incidental drag. `onSelectionChange` just reports selection presence so the
+ * host can enable/disable its Copy button.
+ *
+ * Paste: right-click on Windows/Linux (PuTTY/VS Code convention); macOS keeps its
+ * native menu. A risky multi-line paste is confirmed first via `confirmPaste`;
+ * the capture listener covers every paste entry point (Cmd/Ctrl+V, the macOS
+ * native menu) and the right-click handler reuses the gate. readText() is blocked
+ * in the Wails desktop webview, so all ops fail safe. Returns a disposer.
+ */
+export function setupTerminalClipboard(
+  xterm: XTerm,
+  element: HTMLElement,
+  options: TerminalClipboardOptions = {},
+): () => void {
+  const { confirmPaste, onSelectionChange } = options
+  const mac = isMac()
+  // Async paste (confirm dialog / readText) can resolve after the terminal is
+  // torn down by a reconnect or container switch, which disposes this xterm and
+  // builds a new one. Pasting into the disposed instance silently misses the
+  // visible session, so we gate the deferred paste on this flag.
+  let disposed = false
+
+  const selectionListener = xterm.onSelectionChange(() => {
+    onSelectionChange?.(xterm.hasSelection())
+  })
+
+  // macOS: ⌘C copies the selection. Ctrl+C is left untouched so it still sends
+  // SIGINT. Other platforms have no conflict-free copy keystroke in a browser
+  // (Ctrl+C = SIGINT, Ctrl+Shift+C = devtools), so they rely on the Copy button.
+  if (mac) {
+    xterm.attachCustomKeyEventHandler((e) => {
+      if (
+        e.type === 'keydown' && e.metaKey && !e.ctrlKey && !e.altKey && !e.shiftKey &&
+        (e.key === 'c' || e.key === 'C') && xterm.hasSelection()
+      ) {
+        e.preventDefault()
+        copyTerminalSelection(xterm)
+        return false
+      }
+      return true
+    })
+  }
+
+  const handlePaste = (e: ClipboardEvent) => {
+    const text = e.clipboardData?.getData('text') ?? ''
+    if (!text || !confirmPaste || !isRiskyMultilinePaste(xterm, text)) return
+    e.preventDefault()
+    e.stopImmediatePropagation()
+    confirmPaste({ lineCount: pasteLineCount(text), text }).then((ok) => {
+      if (ok && !disposed) xterm.paste(text)
+    }).catch(() => {})
+  }
+  element.addEventListener('paste', handlePaste, true)
+
+  let handleContextMenu: ((e: MouseEvent) => void) | undefined
+  if (!mac) {
+    handleContextMenu = (e: MouseEvent) => {
+      e.preventDefault()
+      navigator.clipboard.readText().then(async (text) => {
+        if (!text || disposed) return
+        if (confirmPaste && isRiskyMultilinePaste(xterm, text)) {
+          const ok = await confirmPaste({ lineCount: pasteLineCount(text), text })
+          if (!ok || disposed) return
+        }
+        xterm.paste(text)
+      }).catch(() => {})
+    }
+    element.addEventListener('contextmenu', handleContextMenu)
+  }
+
+  return () => {
+    disposed = true
+    selectionListener.dispose()
+    element.removeEventListener('paste', handlePaste, true)
+    if (handleContextMenu) element.removeEventListener('contextmenu', handleContextMenu)
+  }
+}