From 721706954722899adbfea5527a8a1826cff0cd04 Mon Sep 17 00:00:00 2001
From: rikohomeless <163776849+rikohomeless@users.noreply.github.com>
Date: Thu, 14 May 2026 16:50:06 +0000
Subject: [PATCH 1/2] feat(app): add terminal image preview toggle

---
 packages/app/src/web/panel-terminal.tsx       |  49 +++++-
 .../src/web/terminal-inline-images-core.ts    |  29 ++++
 .../src/web/terminal-panel-runtime-core.ts    |  33 ++--
 .../src/web/terminal-panel-runtime-types.ts   |   7 +-
 .../app/src/web/terminal-panel-runtime.ts     | 162 ++++++++++++++----
 .../docker-git/panel-terminal-skiller.test.ts |  26 ++-
 .../terminal-inline-images-core.test.ts       |  42 ++++-
 7 files changed, 294 insertions(+), 54 deletions(-)

diff --git a/packages/app/src/web/panel-terminal.tsx b/packages/app/src/web/panel-terminal.tsx
index f735febd..67ee9029 100644
--- a/packages/app/src/web/panel-terminal.tsx
+++ b/packages/app/src/web/panel-terminal.tsx
@@ -263,16 +263,22 @@ const TerminalActionButton = (
   {
     children,
     compactTypingMode,
-    onClick
+    onClick,
+    pressed,
+    title
   }: {
     readonly children: string
     readonly compactTypingMode: boolean
     readonly onClick: () => void
+    readonly pressed?: boolean
+    readonly title?: string
   }
 ): JSX.Element => (
   <button
+    aria-pressed={pressed}
     onClick={onClick}
     style={compactTypingMode ? compactCloseButtonStyle : closeButtonStyle}
+    title={title}
     type="button"
   >
     {children}
@@ -307,6 +313,7 @@ const OptionalTerminalActionButton = (
 const TerminalHeaderActions = (
   {
     compactHeaderMode,
+    inlineImagePreviewsEnabled,
     onApplyProject,
     onDetach,
     onKill,
@@ -314,6 +321,7 @@ const TerminalHeaderActions = (
     onOpenSkiller,
     onOpenTaskManager,
     onOpenTerminal,
+    onToggleInlineImagePreviews,
     session
   }:
     & Pick<
@@ -329,9 +337,16 @@ const TerminalHeaderActions = (
     >
     & {
       readonly compactHeaderMode: boolean
+      readonly inlineImagePreviewsEnabled: boolean
+      readonly onToggleInlineImagePreviews: () => void
     }
 ): JSX.Element => {
   const hasProjectActions = session.browserProjectId !== undefined
+  const imageToggleLabel = inlineImagePreviewsEnabled ? "Images on" : "Images off"
+  const compactImageToggleLabel = inlineImagePreviewsEnabled ? "Img on" : "Img off"
+  const imageToggleTitle = inlineImagePreviewsEnabled
+    ? "Automatic image previews enabled"
+    : "Automatic image previews disabled"
 
   return (
     <div style={compactHeaderMode ? compactHeaderActionsStyle : headerActionsStyle}>
@@ -370,6 +385,14 @@ const TerminalHeaderActions = (
         label="New terminal"
         onClick={onOpenTerminal}
       />
+      <TerminalActionButton
+        compactTypingMode={compactHeaderMode}
+        onClick={onToggleInlineImagePreviews}
+        pressed={inlineImagePreviewsEnabled}
+        title={imageToggleTitle}
+      >
+        {compactHeaderMode ? compactImageToggleLabel : imageToggleLabel}
+      </TerminalActionButton>
       <TerminalActionButton compactTypingMode={compactHeaderMode} onClick={onDetach}>
         Detach
       </TerminalActionButton>
@@ -383,6 +406,7 @@ const TerminalHeaderActions = (
 const TerminalHeader = (
   {
     compactHeaderMode,
+    inlineImagePreviewsEnabled,
     onApplyProject,
     onDetach,
     onKill,
@@ -390,6 +414,7 @@ const TerminalHeader = (
     onOpenSkiller,
     onOpenTaskManager,
     onOpenTerminal,
+    onToggleInlineImagePreviews,
     session,
     status
   }:
@@ -406,6 +431,8 @@ const TerminalHeader = (
     >
     & {
       readonly compactHeaderMode: boolean
+      readonly inlineImagePreviewsEnabled: boolean
+      readonly onToggleInlineImagePreviews: () => void
       readonly status: TerminalStatus
     }
 ): JSX.Element => (
@@ -413,6 +440,7 @@ const TerminalHeader = (
     <TerminalHeaderTitle compactHeaderMode={compactHeaderMode} session={session} status={status} />
     <TerminalHeaderActions
       compactHeaderMode={compactHeaderMode}
+      inlineImagePreviewsEnabled={inlineImagePreviewsEnabled}
       onApplyProject={onApplyProject}
       onDetach={onDetach}
       onKill={onKill}
@@ -420,6 +448,7 @@ const TerminalHeader = (
       onOpenSkiller={onOpenSkiller}
       onOpenTaskManager={onOpenTaskManager}
       onOpenTerminal={onOpenTerminal}
+      onToggleInlineImagePreviews={onToggleInlineImagePreviews}
       session={session}
     />
   </div>
@@ -575,10 +604,13 @@ export const TerminalPanel = (
 ): JSX.Element => {
   const connectionRef = useRef<TerminalConnectionState>({ closing: false, opened: false })
   const hostRef = useRef<HTMLDivElement | null>(null)
+  const inlineImagePreviewsEnabledRef = useRef(true)
   const runtimeRef = useRef<TerminalInputController | null>(null)
   const [status, setStatus] = useState<TerminalStatus>(() => resolveInitialTerminalStatus(session))
+  const [inlineImagePreviewsEnabled, setInlineImagePreviewsEnabled] = useState(true)
   const [mobileControlsCollapsed, setMobileControlsCollapsed] = useState(false)
   const [mobileCtrlArmed, setMobileCtrlArmed] = useState(false)
+  const terminalSessionId = session.session.id
   const onAttachFailureRef = useRef(onAttachFailure)
   const onMessageRef = useRef(onMessage)
   useEffect(() => {
@@ -590,12 +622,24 @@ export const TerminalPanel = (
   useEffect(() => {
     setStatus(resolveInitialTerminalStatus(session))
   }, [session])
+  useEffect(() => {
+    inlineImagePreviewsEnabledRef.current = true
+    setInlineImagePreviewsEnabled(true)
+  }, [terminalSessionId])
   const notifyAttachFailure = useCallback(() => {
     onAttachFailureRef.current()
   }, [])
   const notifyMessage = useCallback((message: string) => {
     onMessageRef.current(message)
   }, [])
+  const toggleInlineImagePreviews = useCallback(() => {
+    setInlineImagePreviewsEnabled((current) => {
+      const next = !current
+      inlineImagePreviewsEnabledRef.current = next
+      return next
+    })
+    retainTerminalFocus(runtimeRef.current)
+  }, [])
   const compactHeaderMode = resolveTerminalCompactHeaderMode(mobileMode)
   const compactTypingMode = resolveTerminalTypingMode(mobileMode, keyboardOpen)
   const hasBodyContent = bodyContent !== undefined
@@ -644,6 +688,7 @@ export const TerminalPanel = (
   useTerminalSessionLifecycle({
     connectionRef,
     hostRef,
+    inlineImagePreviewsEnabledRef,
     notifyMessage,
     onAttachFailure: notifyAttachFailure,
     runtimeRef,
@@ -655,6 +700,7 @@ export const TerminalPanel = (
     <div style={terminalPanelStyle(mobileMode, keyboardOpen)}>
       <TerminalHeader
         compactHeaderMode={compactHeaderMode}
+        inlineImagePreviewsEnabled={inlineImagePreviewsEnabled}
         onApplyProject={onApplyProject}
         onDetach={() => {
           connectionRef.current.closing = true
@@ -668,6 +714,7 @@ export const TerminalPanel = (
         onOpenSkiller={onOpenSkiller}
         onOpenTaskManager={onOpenTaskManager}
         onOpenTerminal={onOpenTerminal}
+        onToggleInlineImagePreviews={toggleInlineImagePreviews}
         session={session}
         status={status}
       />
diff --git a/packages/app/src/web/terminal-inline-images-core.ts b/packages/app/src/web/terminal-inline-images-core.ts
index 65570ad8..19cd557b 100644
--- a/packages/app/src/web/terminal-inline-images-core.ts
+++ b/packages/app/src/web/terminal-inline-images-core.ts
@@ -6,6 +6,20 @@ export type TerminalInlineImageOutputSegment = {
   readonly text: string
 }
 
+export type TerminalInlineImagePreviewsEnabledRef = { readonly current: boolean }
+
+export type TerminalOutputSegmentWriter = {
+  readonly writePreviewLineBreak: (segment: TerminalInlineImageOutputSegment, onComplete: () => void) => void
+  readonly writePreviews: (paths: ReadonlyArray<string>, onComplete: () => void) => void
+  readonly writeText: (text: string, onComplete: () => void) => void
+}
+
+export type TerminalOutputSegmentWriteArgs = {
+  readonly inlineImagePreviewsEnabledRef: TerminalInlineImagePreviewsEnabledRef
+  readonly segment: TerminalInlineImageOutputSegment
+  readonly writer: TerminalOutputSegmentWriter
+}
+
 const lineBreakPattern = /\r\n|\r|\n/gu
 
 const endsWithLineBreak = (text: string): boolean => /\r\n$|\r$|\n$/u.test(text)
@@ -38,3 +52,18 @@ export const splitTerminalInlineImageOutput = (
   }
   return segments
 }
+
+export const writeTerminalOutputSegment = (
+  { inlineImagePreviewsEnabledRef, segment, writer }: TerminalOutputSegmentWriteArgs,
+  onComplete: () => void
+): void => {
+  writer.writeText(segment.text, () => {
+    if (segment.imagePaths.length === 0 || !inlineImagePreviewsEnabledRef.current) {
+      onComplete()
+      return
+    }
+    writer.writePreviewLineBreak(segment, () => {
+      writer.writePreviews(segment.imagePaths, onComplete)
+    })
+  })
+}
diff --git a/packages/app/src/web/terminal-panel-runtime-core.ts b/packages/app/src/web/terminal-panel-runtime-core.ts
index bc25d281..e0d64aa2 100644
--- a/packages/app/src/web/terminal-panel-runtime-core.ts
+++ b/packages/app/src/web/terminal-panel-runtime-core.ts
@@ -4,7 +4,11 @@ import { Terminal } from "xterm"
 import { FitAddon } from "xterm-addon-fit"
 
 import { resolveTerminalImageFetchUrl } from "./terminal-image-url.js"
-import { splitTerminalInlineImageOutput, type TerminalInlineImageOutputSegment } from "./terminal-inline-images-core.js"
+import {
+  splitTerminalInlineImageOutput,
+  type TerminalInlineImageOutputSegment,
+  writeTerminalOutputSegment
+} from "./terminal-inline-images-core.js"
 import {
   appendTerminalInlineImagePreview,
   cachedTerminalInlineImageEntry,
@@ -353,18 +357,23 @@ const flushTerminalOutputQueue = (handlers: TerminalMessageHandlers): void => {
   }
 
   handlers.lifecycle.outputWriting = true
-  handlers.terminal.write(segment.text, () => {
-    if (segment.imagePaths.length === 0) {
-      handlers.lifecycle.outputWriting = false
-      flushTerminalOutputQueue(handlers)
-      return
+  writeTerminalOutputSegment({
+    inlineImagePreviewsEnabledRef: handlers.inlineImagePreviewsEnabledRef,
+    segment,
+    writer: {
+      writePreviewLineBreak: (outputSegment, onComplete) => {
+        writeLineBreakBeforePreview(handlers, outputSegment, onComplete)
+      },
+      writePreviews: (paths, onComplete) => {
+        writeInlineImagePreviews(handlers, paths, onComplete)
+      },
+      writeText: (text, onComplete) => {
+        handlers.terminal.write(text, onComplete)
+      }
     }
-    writeLineBreakBeforePreview(handlers, segment, () => {
-      writeInlineImagePreviews(handlers, segment.imagePaths, () => {
-        handlers.lifecycle.outputWriting = false
-        flushTerminalOutputQueue(handlers)
-      })
-    })
+  }, () => {
+    handlers.lifecycle.outputWriting = false
+    flushTerminalOutputQueue(handlers)
   })
 }
 
diff --git a/packages/app/src/web/terminal-panel-runtime-types.ts b/packages/app/src/web/terminal-panel-runtime-types.ts
index f319ce12..c87ec9f6 100644
--- a/packages/app/src/web/terminal-panel-runtime-types.ts
+++ b/packages/app/src/web/terminal-panel-runtime-types.ts
@@ -1,7 +1,10 @@
 import type { IDisposable, Terminal } from "xterm"
 import type { FitAddon } from "xterm-addon-fit"
 
-import type { TerminalInlineImageOutputSegment } from "./terminal-inline-images-core.js"
+import type {
+  TerminalInlineImageOutputSegment,
+  TerminalInlineImagePreviewsEnabledRef
+} from "./terminal-inline-images-core.js"
 import type { ActiveTerminalSession } from "./terminal.js"
 
 export type TerminalStatus = "attached" | "connecting" | "error" | "exited" | "reconnecting"
@@ -38,6 +41,7 @@ export type TerminalPasteGuard = {
 
 export type TerminalMessageHandlers = {
   readonly connectionRef: { current: TerminalConnectionState }
+  readonly inlineImagePreviewsEnabledRef: TerminalInlineImagePreviewsEnabledRef
   readonly lifecycle: TerminalLifecycleState
   readonly notifyMessage: (message: string) => void
   readonly session: ActiveTerminalSession
@@ -63,6 +67,7 @@ export type TerminalCleanupArgs = {
 export type TerminalLifecycleArgs = {
   readonly connectionRef: { current: TerminalConnectionState }
   readonly hostRef: { readonly current: HTMLDivElement | null }
+  readonly inlineImagePreviewsEnabledRef: TerminalInlineImagePreviewsEnabledRef
   readonly notifyMessage: (message: string) => void
   readonly onAttachFailure: () => void
   readonly runtimeRef: { current: TerminalInputController | null }
diff --git a/packages/app/src/web/terminal-panel-runtime.ts b/packages/app/src/web/terminal-panel-runtime.ts
index faf63f8b..c4f62667 100644
--- a/packages/app/src/web/terminal-panel-runtime.ts
+++ b/packages/app/src/web/terminal-panel-runtime.ts
@@ -14,7 +14,9 @@ import {
 } from "./terminal-panel-runtime-core.js"
 import type {
   TerminalLifecycleArgs,
+  TerminalLifecycleState,
   TerminalMessageHandlers,
+  TerminalPasteGuard,
   TerminalSocketConnectArgs,
   TerminalSocketRef
 } from "./terminal-panel-runtime-types.js"
@@ -69,6 +71,93 @@ const attachGlobalResizeListeners = (sendResize: () => void): void => {
   globalThis.visualViewport?.addEventListener("scroll", sendResize)
 }
 
+const createTerminalMessageHandlers = (
+  args: TerminalLifecycleArgs,
+  lifecycle: TerminalLifecycleState,
+  terminal: TerminalMessageHandlers["terminal"]
+): TerminalMessageHandlers => ({
+  connectionRef: args.connectionRef,
+  inlineImagePreviewsEnabledRef: args.inlineImagePreviewsEnabledRef,
+  lifecycle,
+  notifyMessage: args.notifyMessage,
+  session: args.session,
+  setStatus: args.setStatus,
+  terminal
+})
+
+type MountedTerminalDisposables = {
+  readonly imageLinkDisposable: { readonly dispose: () => void }
+  readonly imagePasteDisposable: { readonly dispose: () => void }
+  readonly inputDisposable: { readonly dispose: () => void }
+}
+
+type MountedTerminalCleanupArgs = {
+  readonly args: TerminalLifecycleArgs
+  readonly disposables: MountedTerminalDisposables
+  readonly lifecycle: TerminalLifecycleState
+  readonly resizeObserver: ResizeObserver | null
+  readonly sendResize: () => void
+  readonly socketRef: TerminalSocketRef
+  readonly terminal: TerminalMessageHandlers["terminal"]
+}
+
+const createMountedTerminalDisposables = (
+  args: TerminalLifecycleArgs,
+  host: HTMLDivElement,
+  pasteGuard: TerminalPasteGuard,
+  socketRef: TerminalSocketRef,
+  terminal: TerminalMessageHandlers["terminal"]
+): MountedTerminalDisposables => ({
+  imageLinkDisposable: attachTerminalImageLinks(terminal, args.session),
+  imagePasteDisposable: attachTerminalImagePaste({
+    host,
+    notifyMessage: args.notifyMessage,
+    pasteGuard,
+    socketRef,
+    terminal
+  }),
+  inputDisposable: attachTerminalInput(terminal, socketRef, pasteGuard)
+})
+
+const createMountedTerminalConnector = (
+  args: TerminalLifecycleArgs,
+  lifecycle: TerminalLifecycleState,
+  socketRef: TerminalSocketRef,
+  terminal: TerminalMessageHandlers["terminal"],
+  sendResize: () => void
+): () => void =>
+  createConnectSocket({
+    handlers: createTerminalMessageHandlers(args, lifecycle, terminal),
+    lifecycle,
+    notifyMessage: args.notifyMessage,
+    onAttachFailure: args.onAttachFailure,
+    sendResize,
+    session: args.session,
+    setStatus: args.setStatus,
+    socketRef,
+    terminal
+  })
+
+const createMountedTerminalCleanup = (
+  { args, disposables, lifecycle, resizeObserver, sendResize, socketRef, terminal }: MountedTerminalCleanupArgs
+): () => void =>
+  createTerminalCleanup({
+    cleanupArgs: {
+      connectionRef: args.connectionRef,
+      lifecycle,
+      notifyMessage: args.notifyMessage,
+      resizeObserver,
+      runtimeRef: args.runtimeRef,
+      session: args.session,
+      socketRef,
+      terminal
+    },
+    imageLinkDisposable: disposables.imageLinkDisposable,
+    imagePasteDisposable: disposables.imagePasteDisposable,
+    inputDisposable: disposables.inputDisposable,
+    sendResize
+  })
+
 const resolveMountHost = (
   { hostRef, session }: Pick<TerminalLifecycleArgs, "hostRef" | "session">
 ): HTMLDivElement | null => {
@@ -78,74 +167,73 @@ const resolveMountHost = (
   return hostRef.current
 }
 
-const mountTerminalSession = (
-  { connectionRef, hostRef, notifyMessage, onAttachFailure, runtimeRef, session, setStatus }: TerminalLifecycleArgs
-): (() => void) | undefined => {
-  const host = resolveMountHost({ hostRef, session })
+const mountTerminalSession = (args: TerminalLifecycleArgs): (() => void) | undefined => {
+  const host = resolveMountHost(args)
   if (host === null) {
     return undefined
   }
 
-  connectionRef.current = { closing: false, opened: false }
+  args.connectionRef.current = { closing: false, opened: false }
   const lifecycle = createLifecycleState()
   const socketRef: TerminalSocketRef = { current: null }
   const { fitAddon, terminal } = createTerminalRuntime(host)
   const terminalInputController = createTerminalInputController(terminal, socketRef)
   const pasteGuard = createTerminalPasteGuard()
-  const sendResize = () => {
+  const sendResize = (): void => {
     sendTerminalResize(fitAddon, socketRef, terminal)
   }
   const resizeObserver = observeTerminalResize(host, sendResize)
-  const inputDisposable = attachTerminalInput(terminal, socketRef, pasteGuard)
-  const imagePasteDisposable = attachTerminalImagePaste({ host, notifyMessage, pasteGuard, socketRef, terminal })
-  const imageLinkDisposable = attachTerminalImageLinks(terminal, session)
-  const handlers: TerminalMessageHandlers = {
-    connectionRef,
-    lifecycle,
-    notifyMessage,
-    session,
-    setStatus,
-    terminal
-  }
-  const connectSocket = createConnectSocket({
-    handlers,
-    lifecycle,
-    notifyMessage,
-    onAttachFailure,
-    sendResize,
-    session,
-    setStatus,
-    socketRef,
-    terminal
-  })
+  const disposables = createMountedTerminalDisposables(args, host, pasteGuard, socketRef, terminal)
+  const connectSocket = createMountedTerminalConnector(args, lifecycle, socketRef, terminal, sendResize)
 
-  runtimeRef.current = terminalInputController
+  args.runtimeRef.current = terminalInputController
   attachGlobalResizeListeners(sendResize)
   connectSocket()
 
-  return createTerminalCleanup({
-    cleanupArgs: { connectionRef, lifecycle, notifyMessage, resizeObserver, runtimeRef, session, socketRef, terminal },
-    imageLinkDisposable,
-    imagePasteDisposable,
-    inputDisposable,
-    sendResize
+  return createMountedTerminalCleanup({
+    args,
+    disposables,
+    lifecycle,
+    resizeObserver,
+    sendResize,
+    socketRef,
+    terminal
   })
 }
 
 export const useTerminalSessionLifecycle = (
-  { connectionRef, hostRef, notifyMessage, onAttachFailure, runtimeRef, session, setStatus }: TerminalLifecycleArgs
+  {
+    connectionRef,
+    hostRef,
+    inlineImagePreviewsEnabledRef,
+    notifyMessage,
+    onAttachFailure,
+    runtimeRef,
+    session,
+    setStatus
+  }: TerminalLifecycleArgs
 ): void => {
   useEffect(() => {
     return mountTerminalSession({
       connectionRef,
       hostRef,
+      inlineImagePreviewsEnabledRef,
       notifyMessage,
       onAttachFailure,
       runtimeRef,
       session,
       setStatus
     })
-  }, [connectionRef, hostRef, notifyMessage, onAttachFailure, runtimeRef, session, setStatus])
+  }, [
+    connectionRef,
+    hostRef,
+    inlineImagePreviewsEnabledRef,
+    notifyMessage,
+    onAttachFailure,
+    runtimeRef,
+    session,
+    setStatus
+  ])
 }
 
 export {
diff --git a/packages/app/tests/docker-git/panel-terminal-skiller.test.ts b/packages/app/tests/docker-git/panel-terminal-skiller.test.ts
index 61867dfd..6ff7a520 100644
--- a/packages/app/tests/docker-git/panel-terminal-skiller.test.ts
+++ b/packages/app/tests/docker-git/panel-terminal-skiller.test.ts
@@ -36,7 +36,9 @@ const session: ActiveTerminalSession = {
   websocketPath: "/projects/by-key/0a278e578d69/terminal-sessions/proof-terminal/ws"
 }
 
-const renderTerminalPanel = (): string =>
+type TerminalPanelRenderOverrides = Partial<Parameters<typeof TerminalPanel>[0]>
+
+const renderTerminalPanel = (overrides: TerminalPanelRenderOverrides = {}): string =>
   renderToStaticMarkup(createElement(TerminalPanel, {
     keyboardOpen: false,
     mobileMode: false,
@@ -49,7 +51,8 @@ const renderTerminalPanel = (): string =>
     onOpenSkiller: vi.fn(),
     onOpenTaskManager: vi.fn(),
     onOpenTerminal: vi.fn(),
-    session
+    session,
+    ...overrides
   }))
 
 describe("TerminalPanel Skiller action", () => {
@@ -64,4 +67,23 @@ describe("TerminalPanel Skiller action", () => {
     expect(skillerIndex).toBeGreaterThan(openBrowserIndex)
     expect(applyIndex).toBeGreaterThan(skillerIndex)
   })
+
+  it("renders automatic image previews enabled by default in the terminal header action row", () => {
+    const html = renderTerminalPanel()
+
+    const imagesIndex = html.indexOf("Images on")
+    const detachIndex = html.indexOf("Detach")
+
+    expect(imagesIndex).toBeGreaterThanOrEqual(0)
+    expect(detachIndex).toBeGreaterThan(imagesIndex)
+    expect(html).toContain("aria-pressed=\"true\"")
+    expect(html).toContain("title=\"Automatic image previews enabled\"")
+  })
+
+  it("uses a compact image preview toggle label in compact terminal headers", () => {
+    const html = renderTerminalPanel({ mobileMode: true })
+
+    expect(html).toContain("Img on")
+    expect(html).not.toContain("Images on")
+  })
 })
diff --git a/packages/app/tests/docker-git/terminal-inline-images-core.test.ts b/packages/app/tests/docker-git/terminal-inline-images-core.test.ts
index cc6a3365..8260b197 100644
--- a/packages/app/tests/docker-git/terminal-inline-images-core.test.ts
+++ b/packages/app/tests/docker-git/terminal-inline-images-core.test.ts
@@ -1,7 +1,10 @@
 import { describe, expect, it } from "@effect/vitest"
 import { vi } from "vitest"
 
-import { splitTerminalInlineImageOutput } from "../../src/web/terminal-inline-images-core.js"
+import {
+  splitTerminalInlineImageOutput,
+  writeTerminalOutputSegment
+} from "../../src/web/terminal-inline-images-core.js"
 import {
   cachedTerminalInlineImageEntry,
   cacheTerminalInlineImageBlob,
@@ -66,6 +69,43 @@ describe("terminal inline image output", () => {
     expect(terminalInlineImageSpacer).toBe("\r\n\r\n\r\n\r\n")
   })
 
+  it("writes detected image paths as plain terminal text when automatic previews are disabled", () => {
+    const textWrites: Array<string> = []
+    const previewWrites: Array<ReadonlyArray<string>> = []
+    const previewLineBreaks = { count: 0 }
+    const completions = { count: 0 }
+
+    writeTerminalOutputSegment({
+      inlineImagePreviewsEnabledRef: { current: false },
+      segment: {
+        endedWithLineBreak: false,
+        imagePaths: [issue250ImagePath],
+        text: issue250DeleteCommand
+      },
+      writer: {
+        writePreviewLineBreak: (_segment, onComplete) => {
+          previewLineBreaks.count += 1
+          onComplete()
+        },
+        writePreviews: (paths, onComplete) => {
+          previewWrites.push(paths)
+          onComplete()
+        },
+        writeText: (text, onComplete) => {
+          textWrites.push(text)
+          onComplete()
+        }
+      }
+    }, () => {
+      completions.count += 1
+    })
+
+    expect(textWrites).toEqual([issue250DeleteCommand])
+    expect(previewLineBreaks.count).toBe(0)
+    expect(previewWrites).toEqual([])
+    expect(completions.count).toBe(1)
+  })
+
   it("caches successful image fetch blobs as reusable object urls", () => {
     const createObjectUrl = vi.spyOn(URL, "createObjectURL").mockReturnValue("blob:terminal-image")
     const revokeObjectUrl = vi.spyOn(URL, "revokeObjectURL").mockImplementation(() => void 0)

From 3d3153f47645d1720953d54948b92a78e1bdb9e8 Mon Sep 17 00:00:00 2001
From: rikohomeless <163776849+rikohomeless@users.noreply.github.com>
Date: Thu, 14 May 2026 17:13:34 +0000
Subject: [PATCH 2/2] chore(app): address terminal preview review comments

---
 .../src/web/terminal-inline-images-core.ts    | 21 +++++++++++++++++++
 .../app/src/web/terminal-panel-runtime.ts     |  1 -
 2 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/packages/app/src/web/terminal-inline-images-core.ts b/packages/app/src/web/terminal-inline-images-core.ts
index 19cd557b..003e26f0 100644
--- a/packages/app/src/web/terminal-inline-images-core.ts
+++ b/packages/app/src/web/terminal-inline-images-core.ts
@@ -53,6 +53,27 @@ export const splitTerminalInlineImageOutput = (
   return segments
 }
 
+/**
+ * Coordinates terminal output writes for one parsed segment.
+ *
+ * This function only sequences the supplied writer callbacks. It does not fetch
+ * image data, allocate decorations, or mutate terminal state directly; those
+ * effects belong to the writer implementation.
+ *
+ * @pure false - invokes effectful writer callbacks.
+ * @effect writer callbacks: writeText, writePreviewLineBreak, writePreviews.
+ * @precondition segment is the next queued terminal output segment and
+ * onComplete belongs to the caller's active output queue drain.
+ * @postcondition writeText is requested exactly once; when previews are enabled
+ * and imagePaths is non-empty, the preview line break and preview writes are
+ * requested in order before onComplete.
+ * @invariant segment.text is emitted before any preview callback, and preview
+ * callbacks never run when imagePaths is empty or previews are disabled.
+ * @complexity O(1) plus writer callback complexity; image paths are forwarded
+ * without iteration.
+ * @throws Through writer callbacks or onComplete only; this function has no
+ * explicit throw path.
+ */
 export const writeTerminalOutputSegment = (
   { inlineImagePreviewsEnabledRef, segment, writer }: TerminalOutputSegmentWriteArgs,
   onComplete: () => void
diff --git a/packages/app/src/web/terminal-panel-runtime.ts b/packages/app/src/web/terminal-panel-runtime.ts
index c4f62667..f8c3e8e0 100644
--- a/packages/app/src/web/terminal-panel-runtime.ts
+++ b/packages/app/src/web/terminal-panel-runtime.ts
@@ -227,7 +227,6 @@ export const useTerminalSessionLifecycle = (
   }, [
     connectionRef,
     hostRef,
-    inlineImagePreviewsEnabledRef,
     notifyMessage,
     onAttachFailure,
     runtimeRef,