kokoirc 0.2.2 → 0.2.4

package/src/core/commands/help-formatter.ts

@@ -7,7 +7,7 @@ import { commands, findByAlias, getCanonicalName } from "./registry"
 
 const CATEGORY_ORDER = [
   "Connection", "Channel", "Messaging", "Moderation",
-  "Configuration", "Statusbar", "Info",
+  "Media", "Configuration", "Statusbar", "Info",
 ]
 
 // ─── /help (no args) — categorized command list ─────────────

package/src/core/commands/helpers.ts

@@ -1,6 +1,7 @@
 import { useStore } from "@/core/state/store"
 import { makeBufferId, BufferType } from "@/types"
 import type { AppConfig } from "@/types/config"
+import { nextMsgId } from "@/core/utils/id"
 import { CREDENTIAL_FIELDS } from "./types"
 import type { ResolvedConfig } from "./types"
 
@@ -10,7 +11,7 @@ export function addLocalEvent(text: string) {
   const buf = s.activeBufferId
   if (!buf) return
   s.addMessage(buf, {
-    id: crypto.randomUUID(),
+    id: nextMsgId(),
     timestamp: new Date(),
     type: "event",
     text,
@@ -155,6 +156,7 @@ export function listAllSettings(config: AppConfig): void {
   showSection("sidepanel.left", "sidepanel.left", config.sidepanel.left)
   showSection("sidepanel.right", "sidepanel.right", config.sidepanel.right)
   showSection("statusbar", "statusbar", config.statusbar)
+  showSection("image_preview", "image_preview", config.image_preview)
 
   if (Object.keys(config.aliases).length > 0) {
     showSection("aliases", "aliases", config.aliases)

package/src/core/commands/registry.ts

@@ -1,5 +1,6 @@
 import { getClient, connectServer, disconnectServer, getAllClientIds } from "@/core/irc"
 import { useStore } from "@/core/state/store"
+import { nextMsgId } from "@/core/utils/id"
 import { loadConfig, saveConfig, saveCredentialsToEnv, cloneConfig } from "@/core/config/loader"
 import { loadTheme } from "@/core/theme/loader"
 import { BufferType, makeBufferId, ActivityLevel } from "@/types"
@@ -192,7 +193,7 @@ export const commands: Record<string, CommandDef> = {
       // Show the sent message in the target buffer
       if (s.buffers.has(bufferId)) {
         s.addMessage(bufferId, {
-          id: crypto.randomUUID(),
+          id: nextMsgId(),
           timestamp: new Date(),
           type: "message",
           nick: conn?.nick ?? "",
@@ -220,7 +221,7 @@ export const commands: Record<string, CommandDef> = {
         client.action(buf.name, args[0])
         const conn = s.connections.get(connId)
         s.addMessage(buf.id, {
-          id: crypto.randomUUID(),
+          id: nextMsgId(),
           timestamp: new Date(),
           type: "action",
           nick: conn?.nick ?? "",
@@ -248,7 +249,7 @@ export const commands: Record<string, CommandDef> = {
 
   quit: {
     handler(args) {
-      const reason = args.join(" ") || "kIRC"
+      const reason = args.join(" ") || "kokoIRC — https://github.com/kofany/kokoIRC"
       const ids = getAllClientIds()
       for (const id of ids) {
         disconnectServer(id, reason)
@@ -267,13 +268,92 @@ export const commands: Record<string, CommandDef> = {
       const s = useStore.getState()
       const buf = s.activeBufferId ? s.buffers.get(s.activeBufferId) : null
       if (args.length >= 2) {
+        // /topic #channel new topic text
         client.setTopic(args[0], args[1])
+      } else if (args.length === 1 && args[0].startsWith("#")) {
+        // /topic #channel — request topic from server
+        client.raw(`TOPIC ${args[0]}`)
       } else if (buf && args[0]) {
+        // /topic new topic text — set on current channel
         client.setTopic(buf.name, args[0])
+      } else if (buf) {
+        // /topic — display current topic locally
+        if (buf.topic) {
+          const setBy = buf.topicSetBy ? ` %Z565f89(set by ${buf.topicSetBy})%N` : ""
+          addLocalEvent(`%Z7aa2f7Topic for ${buf.name}:%N ${buf.topic}${setBy}`)
+        } else {
+          addLocalEvent(`%Z565f89No topic set for ${buf.name}%N`)
+        }
       }
     },
     description: "Set or view channel topic",
-    usage: "/topic [channel] <text>",
+    usage: "/topic [channel] [text]",
+  },
+
+  names: {
+    handler(args, connId) {
+      const client = getClient(connId)
+      if (!client) return
+      const s = useStore.getState()
+      const channel = args[0] || getActiveChannel()
+      if (!channel) {
+        addLocalEvent(`%Zf7768eUsage: /names [channel]%N`)
+        return
+      }
+      // Display current nick list from buffer state
+      const bufferId = s.activeBufferId?.split("/")[0]
+        ? makeBufferId(s.activeBufferId.split("/")[0], channel)
+        : null
+      const buf = bufferId ? s.buffers.get(bufferId) : null
+      if (buf && buf.users.size > 0) {
+        const nicks: string[] = []
+        for (const [, entry] of buf.users) {
+          nicks.push(`${entry.prefix}${entry.nick}`)
+        }
+        nicks.sort((a, b) => a.replace(/^[@+%~&!]/, "").localeCompare(b.replace(/^[@+%~&!]/, "")))
+        addLocalEvent(`%Z7aa2f7Users on ${channel}%N [${buf.users.size}]: ${nicks.join(" ")}`)
+      }
+      // Also request fresh NAMES from server (updates nick list panel)
+      client.raw(`NAMES ${channel}`)
+    },
+    description: "List users in a channel",
+    usage: "/names [channel]",
+  },
+
+  invite: {
+    handler(args, connId) {
+      const client = getClient(connId)
+      if (!client || !args[0]) {
+        addLocalEvent(`%Zf7768eUsage: /invite <nick> [channel]%N`)
+        return
+      }
+      const nick = args[0]
+      const channel = args[1] || getActiveChannel()
+      if (!channel) {
+        addLocalEvent(`%Zf7768eNo active channel — specify a channel: /invite ${nick} #channel%N`)
+        return
+      }
+      client.raw(`INVITE ${nick} ${channel}`)
+    },
+    description: "Invite a user to a channel",
+    usage: "/invite <nick> [channel]",
+  },
+
+  version: {
+    handler(args, connId) {
+      const client = getClient(connId)
+      if (!client) return
+      if (args[0]) {
+        // /version <nick> — send CTCP VERSION query
+        client.ctcpRequest(args[0], "VERSION")
+      } else {
+        // /version — query server version
+        client.raw("VERSION")
+      }
+    },
+    description: "Query server or user client version",
+    usage: "/version [nick]",
+    aliases: ["ver"],
   },
 
   notice: {
@@ -303,13 +383,34 @@ export const commands: Record<string, CommandDef> = {
       } else if (buf.type === BufferType.Query) {
         s.removeBuffer(buf.id)
       } else if (buf.type === BufferType.Server) {
-        addLocalEvent(`%Ze0af68Cannot close server buffer%N`)
+        const conn = s.connections.get(buf.connectionId)
+        const isDefault = buf.connectionId === "_default"
+        const isDisconnected = !conn || conn.status === "disconnected" || conn.status === "error"
+
+        if (!isDefault && !isDisconnected) {
+          addLocalEvent(`%Ze0af68Cannot close server buffer while connected. /disconnect first%N`)
+          return
+        }
+
+        // Atomically remove all buffers + connection for this server
+        s.closeConnection(buf.connectionId)
       }
     },
     description: "Close current buffer",
     usage: "/close [reason]",
   },
 
+  clear: {
+    handler() {
+      const s = useStore.getState()
+      if (!s.activeBufferId) return
+      s.clearMessages(s.activeBufferId)
+      addLocalEvent(`%Z6e738dBuffer cleared%N`)
+    },
+    description: "Clear current buffer's messages",
+    usage: "/clear",
+  },
+
   whois: {
     handler(args, connId) {
       const client = getClient(connId)
@@ -411,7 +512,7 @@ export const commands: Record<string, CommandDef> = {
         const id = args[1]?.toLowerCase()
         const addrArg = args[2]
         if (!id || !addrArg) {
-          addLocalEvent(`%Zf7768eUsage: /server add <id> <address>[:<port>] [-tls] [-noauto] [-bind=<ip>] [-label=<name>] [-password=<pass>] [-sasl=<user>:<pass>]%N`)
+          addLocalEvent(`%Zf7768eUsage: /server add <id> <address>[:<port>] [-tls] [-noauto] [-bind=<ip>] [-label=<name>] [-password=<pass>] [-sasl=<user>:<pass>] [-autosendcmd=<cmds>]%N`)
           return
         }
 
@@ -435,6 +536,7 @@ export const commands: Record<string, CommandDef> = {
         let sasl_pass: string | undefined
         let label = id
         let tls_verify = true
+        let autosendcmd: string | undefined
 
         for (let i = 3; i < args.length; i++) {
           const a = args[i]
@@ -450,6 +552,11 @@ export const commands: Record<string, CommandDef> = {
             sasl_user = saslParts[0]
             sasl_pass = saslParts.slice(1).join(":")
           }
+          else if (a.startsWith("-autosendcmd=")) {
+            // Consumes rest of args since the value contains spaces
+            autosendcmd = [a.slice(13), ...args.slice(i + 1)].join(" ").replace(/^"|"$/g, "")
+            break
+          }
         }
 
         const serverConfig: ServerConfig = {
@@ -463,6 +570,7 @@ export const commands: Record<string, CommandDef> = {
           nick,
           bind_ip,
           sasl_user,
+          autosendcmd,
         }
 
         const s = useStore.getState()
@@ -1343,6 +1451,79 @@ export const commands: Record<string, CommandDef> = {
     usage: "/log [status|search] [query]",
   },
 
+  preview: {
+    handler(args) {
+      if (!args[0]) {
+        addLocalEvent(`%Zf7768eUsage: /preview <url>%N`)
+        return
+      }
+      useStore.getState().showImagePreview(args[0])
+    },
+    description: "Preview an image URL in the terminal",
+    usage: "/preview <url>",
+  },
+
+  image: {
+    async handler(args) {
+      const sub = args[0]?.toLowerCase()
+      const s = useStore.getState()
+      const config = s.config?.image_preview
+
+      if (!sub) {
+        addLocalEvent(`%Z7aa2f7───── Image Preview ─────────────────────%N`)
+        addLocalEvent(`  %Z565f89Status:%N ${config?.enabled ? "%Z9ece6aenabled%N" : "%Zf7768edisabled%N"}`)
+        addLocalEvent(`  %Z565f89Protocol:%N %Zc0caf5${config?.protocol ?? "auto"}%N`)
+        addLocalEvent(`  %Z565f89Cache limit:%N %Zc0caf5${config?.cache_max_mb ?? 100}MB%N`)
+        addLocalEvent(`%Z7aa2f7─────────────────────────────────────────────%N`)
+        addLocalEvent(`  %Z565f89Commands: stats, clear%N`)
+        addLocalEvent(`  %Z565f89Toggle: /set image_preview.enabled true|false%N`)
+        return
+      }
+
+      if (sub === "stats") {
+        const { readdir, stat } = await import("node:fs/promises")
+        const { IMAGE_CACHE_DIR } = await import("@/core/constants")
+        try {
+          const files = await readdir(IMAGE_CACHE_DIR)
+          let totalSize = 0
+          for (const file of files) {
+            const { join } = await import("node:path")
+            const s = await stat(join(IMAGE_CACHE_DIR, file))
+            totalSize += s.size
+          }
+          const sizeMb = (totalSize / 1024 / 1024).toFixed(1)
+          addLocalEvent(`%Z7aa2f7Image cache:%N %Zc0caf5${files.length}%N files, %Zc0caf5${sizeMb}%N MB`)
+        } catch {
+          addLocalEvent(`%Z565f89Cache empty or not initialized%N`)
+        }
+        return
+      }
+
+      if (sub === "clear") {
+        const { readdir, unlink } = await import("node:fs/promises")
+        const { IMAGE_CACHE_DIR } = await import("@/core/constants")
+        const { join } = await import("node:path")
+        try {
+          const files = await readdir(IMAGE_CACHE_DIR)
+          let count = 0
+          for (const file of files) {
+            await unlink(join(IMAGE_CACHE_DIR, file))
+            count++
+          }
+          addLocalEvent(`%Z9ece6aCleared ${count} cached images%N`)
+        } catch {
+          addLocalEvent(`%Z565f89Cache already empty%N`)
+        }
+        return
+      }
+
+      addLocalEvent(`%Zf7768eUnknown subcommand: /image ${sub}. Use: stats, clear%N`)
+      addLocalEvent(`%Z565f89Settings via /set image_preview.<field> — enabled, protocol, max_width, etc.%N`)
+    },
+    description: "Image cache management (settings via /set image_preview.*)",
+    usage: "/image [stats|clear]",
+  },
+
   disconnect: {
     handler(args, connId) {
       const target = args[0]?.toLowerCase()
@@ -1371,6 +1552,70 @@ export const commands: Record<string, CommandDef> = {
     description: "Disconnect from a server",
     usage: "/disconnect [server-id] [message]",
   },
+
+  quote: {
+    handler(args, connId) {
+      const client = getClient(connId)
+      if (!client || args.length === 0) {
+        addLocalEvent(`%Zf7768eUsage: /quote <raw command>%N`)
+        return
+      }
+      client.raw(args.join(" "))
+    },
+    aliases: ["raw"],
+    description: "Send a raw IRC command to the server",
+    usage: "/quote <raw command>",
+  },
+
+  stats: {
+    handler(args, connId) {
+      const client = getClient(connId)
+      if (!client) return
+      client.raw("STATS" + (args.length ? " " + args.join(" ") : ""))
+    },
+    description: "Request server statistics",
+    usage: "/stats [type] [server]",
+  },
+
+  oper: {
+    handler(args, connId) {
+      const client = getClient(connId)
+      if (!client || args.length < 2) {
+        addLocalEvent(`%Zf7768eUsage: /oper <name> <password>%N`)
+        return
+      }
+      client.raw(`OPER ${args[0]} ${args[1]}`)
+    },
+    description: "Authenticate as an IRC operator",
+    usage: "/oper <name> <password>",
+  },
+
+  kill: {
+    handler(args, connId) {
+      const client = getClient(connId)
+      if (!client || args.length === 0) {
+        addLocalEvent(`%Zf7768eUsage: /kill <nick> [reason]%N`)
+        return
+      }
+      const reason = args.slice(1).join(" ") || args[0]
+      client.raw(`KILL ${args[0]} :${reason}`)
+    },
+    description: "Disconnect a user from the network (oper only)",
+    usage: "/kill <nick> [reason]",
+  },
+
+  wallops: {
+    handler(args, connId) {
+      const client = getClient(connId)
+      if (!client || args.length === 0) {
+        addLocalEvent(`%Zf7768eUsage: /wallops <message>%N`)
+        return
+      }
+      client.raw(`WALLOPS :${args.join(" ")}`)
+    },
+    description: "Send a message to all opers (oper only)",
+    usage: "/wallops <message>",
+  },
 }
 
 // ─── Built-in Alias Resolution ────────────────────────────────

package/src/core/config/defaults.ts

@@ -40,6 +40,17 @@ export const DEFAULT_CONFIG: AppConfig = {
     input_color: "",
     cursor_color: "",
   },
+  image_preview: {
+    enabled: true,
+    max_width: 0,
+    max_height: 0,
+    cache_max_mb: 100,
+    cache_max_days: 7,
+    fetch_timeout: 30,
+    max_file_size: 10485760,
+    protocol: "auto",
+    kitty_format: "rgba",
+  },
   servers: {
     ircnet: {
       label: "IRCnet",

package/src/core/config/loader.ts

@@ -13,6 +13,7 @@ export function cloneConfig(config: AppConfig): AppConfig {
       right: { ...config.sidepanel.right },
     },
     statusbar: { ...config.statusbar, items: [...config.statusbar.items], item_formats: { ...config.statusbar.item_formats } },
+    image_preview: { ...config.image_preview },
     servers: Object.fromEntries(
       Object.entries(config.servers).map(([id, srv]) => [id, { ...srv, channels: [...srv.channels] }])
     ),
@@ -42,6 +43,7 @@ export function mergeWithDefaults(partial: Record<string, any>): AppConfig {
       right: { ...DEFAULT_CONFIG.sidepanel.right, ...partial.sidepanel?.right },
     },
     statusbar: { ...DEFAULT_CONFIG.statusbar, ...partial.statusbar },
+    image_preview: { ...DEFAULT_CONFIG.image_preview, ...partial.image_preview },
     servers: partial.servers ?? {},
     aliases: partial.aliases ?? {},
     ignores: (partial.ignores as IgnoreEntry[] | undefined) ?? [],
@@ -120,6 +122,7 @@ function cleanServerForTOML(server: ServerConfig): Record<string, any> {
   if (server.auto_reconnect === false) obj.auto_reconnect = false
   if (server.reconnect_delay && server.reconnect_delay !== 30) obj.reconnect_delay = server.reconnect_delay
   if (server.reconnect_max_retries != null) obj.reconnect_max_retries = server.reconnect_max_retries
+  if (server.autosendcmd) obj.autosendcmd = server.autosendcmd
   // SASL and password stored in config only if NOT in .env — sasl_user kept, pass stripped
   if (server.sasl_user) obj.sasl_user = server.sasl_user
   // password and sasl_pass NOT saved to TOML — they go to .env
@@ -163,6 +166,8 @@ export async function saveConfig(configPath: string, config: AppConfig): Promise
     tomlObj.servers[id] = cleanServerForTOML(server)
   }
 
+  tomlObj.image_preview = config.image_preview
+
   if (config.ignores.length > 0) {
     tomlObj.ignores = config.ignores.map((e) => {
       const obj: Record<string, any> = { mask: e.mask, levels: e.levels }

package/src/core/constants.ts

@@ -16,5 +16,8 @@ export const SCRIPTS_DIR = join(HOME_DIR, "scripts")
 
 export const LOG_DB_PATH = join(HOME_DIR, "logs.db")
 
+// Image cache
+export const IMAGE_CACHE_DIR = join(HOME_DIR, "image_cache")
+
 // Default assets bundled with the package
 export const DEFAULT_THEMES_DIR = join(PKG_DIR, "themes")

package/src/core/image-preview/cache.ts

@@ -0,0 +1,108 @@
+import { createHash } from "crypto"
+import { readdir, stat, unlink } from "node:fs/promises"
+import { join, extname } from "node:path"
+import { IMAGE_CACHE_DIR } from "@/core/constants"
+
+// Magic bytes for common image formats
+const MAGIC = {
+  jpeg: [0xff, 0xd8, 0xff],
+  png:  [0x89, 0x50, 0x4e, 0x47],
+  gif:  [0x47, 0x49, 0x46],
+  webp: [0x52, 0x49, 0x46, 0x46],  // RIFF header (check WEBP at offset 8)
+} as const
+
+/** Get the cache file path for a URL */
+export function getCachePath(url: string, ext?: string): string {
+  const hash = createHash("sha256").update(url).digest("hex")
+  const suffix = ext || extname(new URL(url).pathname) || ".img"
+  return join(IMAGE_CACHE_DIR, hash + suffix)
+}
+
+/** Check if a URL is already cached and valid. Returns path or null. */
+export async function isCached(url: string): Promise<string | null> {
+  // Try common extensions since we may not know the original
+  const hash = createHash("sha256").update(url).digest("hex")
+  const glob = new Bun.Glob(hash + ".*")
+
+  for await (const file of glob.scan(IMAGE_CACHE_DIR)) {
+    const path = join(IMAGE_CACHE_DIR, file)
+    if (await validateImage(path)) return path
+  }
+
+  return null
+}
+
+/** Write image data to cache, return the path */
+export async function writeCache(url: string, data: Buffer, ext?: string): Promise<string> {
+  const path = getCachePath(url, ext)
+  await Bun.write(path, data)
+  return path
+}
+
+/** Validate an image file by checking magic bytes */
+export async function validateImage(path: string): Promise<boolean> {
+  const file = Bun.file(path)
+  if (!(await file.exists())) return false
+
+  const header = new Uint8Array(await file.slice(0, 12).arrayBuffer())
+  if (header.length < 3) return false
+
+  // JPEG
+  if (header[0] === 0xff && header[1] === 0xd8 && header[2] === 0xff) return true
+  // PNG
+  if (header[0] === 0x89 && header[1] === 0x50 && header[2] === 0x4e && header[3] === 0x47) return true
+  // GIF
+  if (header[0] === 0x47 && header[1] === 0x49 && header[2] === 0x46) return true
+  // WEBP (RIFF....WEBP)
+  if (header[0] === 0x52 && header[1] === 0x49 && header[2] === 0x46 && header[3] === 0x46 &&
+      header[8] === 0x57 && header[9] === 0x45 && header[10] === 0x42 && header[11] === 0x50) return true
+
+  return false
+}
+
+/** Clean up old cache files based on size and age limits */
+export async function cleanupCache(maxMb: number, maxDays: number): Promise<void> {
+  const entries: Array<{ path: string; size: number; mtimeMs: number }> = []
+  const maxAgeMs = maxDays * 24 * 60 * 60 * 1000
+  const now = Date.now()
+
+  let files: string[]
+  try {
+    files = await readdir(IMAGE_CACHE_DIR)
+  } catch {
+    return
+  }
+
+  for (const file of files) {
+    const path = join(IMAGE_CACHE_DIR, file)
+    try {
+      const s = await stat(path)
+      if (!s.isFile()) continue
+
+      // Remove files older than maxDays
+      if (now - s.mtimeMs > maxAgeMs) {
+        await unlink(path)
+        continue
+      }
+
+      entries.push({ path, size: s.size, mtimeMs: s.mtimeMs })
+    } catch {
+      // Skip files we can't stat
+    }
+  }
+
+  // Sort oldest first, remove until under size limit
+  entries.sort((a, b) => a.mtimeMs - b.mtimeMs)
+  const maxBytes = maxMb * 1024 * 1024
+  let totalSize = entries.reduce((sum, e) => sum + e.size, 0)
+
+  for (const entry of entries) {
+    if (totalSize <= maxBytes) break
+    try {
+      await unlink(entry.path)
+      totalSize -= entry.size
+    } catch {
+      // Skip
+    }
+  }
+}

package/src/core/image-preview/detect.ts

@@ -0,0 +1,105 @@
+export type ImageProtocol = "kitty" | "iterm2" | "sixel" | "symbols"
+
+export function isInsideTmux(): boolean {
+  return !!process.env.TMUX
+}
+
+/** Get the tmux pane's absolute position on the outer terminal screen */
+export function getTmuxPaneOffset(): { top: number; left: number } {
+  try {
+    const result = Bun.spawnSync(["tmux", "display-message", "-p", "#{pane_top}:#{pane_left}"])
+    const output = new TextDecoder().decode(result.stdout).trim()
+    const [top, left] = output.split(":").map(Number)
+    if (!isNaN(top) && !isNaN(left)) return { top, left }
+  } catch {}
+  return { top: 0, left: 0 }
+}
+
+/** Match a terminal identifier string to a protocol.
+ *  Works with both #{client_termtype} (e.g. "iTerm2 3.6.8", "ghostty 1.3.0")
+ *  and #{client_termname} (e.g. "xterm-ghostty", "xterm-kitty").
+ *  iterm FIRST, then kitty family, then sixel-capable terminals. */
+function matchTermName(name: string): ImageProtocol | null {
+  const t = name.toLowerCase()
+
+  // iTerm2 — "iTerm2 3.6.8" from termtype, or "iterm2" from termname
+  if (t.includes("iterm")) return "iterm2"
+
+  // Kitty protocol family
+  if (t.includes("kitty")) return "kitty"
+  if (t.includes("ghostty")) return "kitty"
+  if (t.includes("wezterm")) return "kitty"
+  if (t.includes("rio")) return "kitty"
+  // Subterm: "subterm x.x.x" from termtype, LC_TERMINAL=Subterm without tmux
+  if (t.includes("subterm")) return "kitty"
+
+  // Sixel-capable terminals
+  if (t.includes("foot")) return "sixel"
+  if (t.includes("contour")) return "sixel"
+  if (t.includes("konsole")) return "sixel"
+  if (t.includes("mintty")) return "sixel"
+  if (t.includes("mlterm")) return "sixel"
+  if (t.includes("xterm")) return "sixel"
+
+  return null
+}
+
+/** Detect the best image display protocol for the current terminal.
+ *  Returns [protocol, detectedName] — detectedName is the raw string that matched.
+ *  In tmux: queries #{client_termtype} first (returns real terminal identity
+ *  like "iTerm2 3.6.8", "ghostty 1.3.0"), then #{client_termname} as fallback.
+ *  Outside tmux: checks env vars, then generic TERM. */
+export function detectProtocol(configOverride?: string): [ImageProtocol, string] {
+  if (configOverride && configOverride !== "auto") {
+    return [configOverride as ImageProtocol, `config:${configOverride}`]
+  }
+
+  const inTmux = isInsideTmux()
+
+  // ─── tmux: query the REAL outer terminal ───────────────────
+  if (inTmux) {
+    // #{client_termtype} returns the actual terminal identity
+    // (e.g. "iTerm2 3.6.8", "ghostty 1.3.0-main+...", "subterm 1.0")
+    // unlike #{client_termname} which returns generic "xterm-256color" for iTerm2
+    try {
+      const result = Bun.spawnSync(["tmux", "display-message", "-p", "#{client_termtype}"])
+      const termType = new TextDecoder().decode(result.stdout).trim()
+      if (termType) {
+        const match = matchTermName(termType)
+        if (match) return [match, termType]
+      }
+    } catch {}
+
+    // Fallback: #{client_termname} (works for ghostty "xterm-ghostty", kitty "xterm-kitty")
+    try {
+      const result = Bun.spawnSync(["tmux", "display-message", "-p", "#{client_termname}"])
+      const termName = new TextDecoder().decode(result.stdout).trim()
+      if (termName) {
+        const match = matchTermName(termName)
+        if (match) return [match, termName]
+      }
+    } catch {}
+  }
+
+  // ─── env var detection (non-tmux, or tmux query returned unknown) ──
+  const termProgram = (process.env.TERM_PROGRAM ?? "").toLowerCase()
+  const lcTerminal = (process.env.LC_TERMINAL ?? "").toLowerCase()
+
+  if (termProgram === "iterm.app" || termProgram === "iterm2" || lcTerminal === "iterm2") {
+    return ["iterm2", `TERM_PROGRAM=${process.env.TERM_PROGRAM ?? lcTerminal}`]
+  }
+  if (lcTerminal === "subterm") return ["kitty", `LC_TERMINAL=${process.env.LC_TERMINAL}`]
+  if (termProgram === "wezterm") return ["kitty", `TERM_PROGRAM=${process.env.TERM_PROGRAM}`]
+  if (termProgram === "rio") return ["kitty", `TERM_PROGRAM=${process.env.TERM_PROGRAM}`]
+  if (termProgram === "mintty") return ["sixel", `TERM_PROGRAM=${process.env.TERM_PROGRAM}`]
+  if (process.env.KITTY_PID) return ["kitty", `KITTY_PID=${process.env.KITTY_PID}`]
+  if (process.env.GHOSTTY_RESOURCES_DIR) return ["kitty", "GHOSTTY_RESOURCES_DIR"]
+  if (process.env.WT_SESSION) return ["sixel", "WT_SESSION"]
+
+  // Generic TERM value — last resort
+  const term = (process.env.TERM ?? "").toLowerCase()
+  const termMatch = matchTermName(term)
+  if (termMatch) return [termMatch, `TERM=${process.env.TERM}`]
+
+  return ["symbols", "unknown"]
+}