tabby-clip-image 0.0.0-stage → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 barton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,68 @@
-# Temporary Holding Version
+# tabby-clip-image
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Paste **images** into remote TUIs (Claude Code, Codex, …) running over SSH in Tabby.
+
+In an SSH tab, paste with any of `Ctrl+V`, `Cmd+V`, `Ctrl+Shift+V`, `Shift+Insert`, right-click or middle-click. If the clipboard holds
+
+| Clipboard | Result |
+|---|---|
+| a screenshot / copied image (pixels) | uploaded as `.png` |
+| image **file(s)** copied in the file manager (png, jpg, gif, webp, bmp, tif, heic/heif, avif, svg, ico) | uploaded **unchanged**, original format kept, multiple files supported (Windows lists them via the built-in PowerShell) |
+| text, or non-image files | normal paste |
+
+the bytes go over the tab's **existing SSH connection** (built-in SSH tabs: new exec channel, no extra login) into `~/.cache/clip-recv/shots/shot-<time>-<pid>-<name>.<ext>` on the host, and the absolute path is pasted at the cursor.
+
+**Nothing to install on the host**: it only uses POSIX `sh`, `mkdir`, `date`, `cat`, `chmod`, `find`. No X11/Wayland needed.
+
+Client side: Linux (X11/Wayland), macOS, Windows — local tabs and text pastes are untouched.
+
+## Install
+
+Manual: copy this folder to Tabby's user plugin dir — Windows `%APPDATA%\tabby\plugins\node_modules\tabby-clip-image`, macOS `~/Library/Application Support/tabby/plugins/node_modules/tabby-clip-image`, Linux `~/.config/tabby/plugins/node_modules/tabby-clip-image` — then quit and restart Tabby. Or run `install-tabby-plugin.sh` / `.ps1` from the repo. Works in Tabby's built-in **SSH tabs** and, since 0.5.0, in **local tabs where you run `ssh`** (see below).
+
+Plugin manager:
+
+Tabby → Settings → Plugins → search `clip-image` → Install → restart Tabby.
+
+## Local tabs running `ssh` (since 0.5.0)
+
+If you connect with the system `ssh` from a Tabby local shell (`ssh myhost`, aliases from `~/.ssh/config`, jump hosts, keys in `ssh-agent`), the plugin finds the `ssh` process that the tab's shell is running, reuses its options and starts a **second, non-interactive** `ssh` (`-T -o BatchMode=yes`) to upload the image. Therefore:
+
+- the host must be reachable without a prompt: key/agent auth, or `ControlMaster`/`ControlPersist` in `~/.ssh/config` (password-only hosts fail with an error toast);
+- `ssh` must be started directly from the tab's shell (not inside a *local* tmux/screen). `tmux` on the **remote** host is fine;
+- if nothing is running `ssh` in the tab, pasting behaves exactly as before.
+
+## Configuration
+
+- Path prefix: `PATH_PREFIX` in `index.js` (default `''`). When the app enabled bracketed paste (Claude Code, Codex, …) each path is sent as a paste, exactly like drag-and-drop, so the TUI shows `[Image #1]`; otherwise (a shell prompt) the plain path is typed. Verified with real Claude Code and Codex; `'@'` only works as a file mention in Claude Code.
+- Max file size: `MAX_FILE_BYTES` (default 50 MB).
+- Target directory on the host: `CLIP_RECV_DIR` (must be visible to non-interactive `sh`). Files older than 2 days are pruned (`-mtime +2` in `REMOTE_SH`).
+
+## Notes
+
+- Uploaded files are mode 600.
+- Only triggers when the clipboard has an image (or image files) and no text; on failure a notification is shown and the normal paste/`Ctrl+V` is passed through.
+- File-copy detection reads OS clipboard formats (`text/uri-list` / `x-special/gnome-copied-files` on Linux, `NSFilenamesPboardType` / `public.file-url` on macOS, `FileNameW` on Windows).
+
+## Troubleshooting (copied files not detected)
+
+Open Tabby's DevTools (`Ctrl+Shift+I` / `Cmd+Option+I`), Console, copy a file in the file manager, then run:
+
+```js
+require('electron').clipboard.availableFormats()
+```
+
+then check what the plugin itself would upload for the current clipboard (empty array = it would paste normally):
+
+```js
+require('electron').clipboard && require(require('path').join(require('os').homedir(), '.config/tabby/plugins/node_modules/tabby-clip-image')).collectItems(require('electron').clipboard).map(i => i.error || `${i.base}.${i.ext}`)
+```
+
+(on Windows use `%APPDATA%\\tabby\\plugins\\node_modules\\tabby-clip-image`, on macOS `~/Library/Application Support/tabby/plugins/node_modules/tabby-clip-image`), and open an issue with the output and your OS. Expected: `text/uri-list` (Linux), `NSFilenamesPboardType`/`public.file-url` (macOS), `FileNameW` (Windows).
+
+## Verification status
+
+- Linux client, real Tabby 1.0.238 over SSH, real Claude Code and Codex in remote tmux: screenshot and copied files (png/jpg/webp) pasted as `[Image #1]`.
+- macOS and Windows clients: clipboard-format parsing covered by unit tests with simulated clipboards only; not yet run on real machines.
+
+MIT

package/index.js

@@ -0,0 +1,497 @@
+'use strict'
+// tabby-clip-image: paste images into remote TUIs (claude/codex/...) over SSH.
+//
+// When you paste in an SSH tab (Ctrl+V, Cmd+V, Ctrl+Shift+V, Shift+Insert, right/middle click)
+// and the clipboard holds
+//   - copied image FILE(s)  (png/jpg/gif/webp/bmp/tiff/heic/avif/svg/ico) -> uploaded as-is, or
+//   - a screenshot / copied image (pixels)                                  -> uploaded as PNG,
+// the bytes are streamed over the tab's existing SSH connection to a fixed directory on the host
+// (plain `sh` + `cat`; nothing to install there) and the absolute path is typed at the cursor.
+// Anything else (text, non-image files, local tabs) pastes normally.
+const VERSION = '0.5.0'
+// Trace to the console AND to ~/.tabby-clip-image.log (capped) so problems can be diagnosed without DevTools.
+const LOG_FILE = require('path').join(require('os').homedir(), '.tabby-clip-image.log')
+const log = (...a) => {
+    console.log('[tabby-clip-image]', ...a)
+    try {
+        const fsx = require('fs')
+        try { if (fsx.statSync(LOG_FILE).size > 200 * 1024) { fsx.renameSync(LOG_FILE, LOG_FILE + '.old') } } catch { /* no file yet */ }
+        fsx.appendFileSync(LOG_FILE, `${new Date().toISOString()} ${a.map(x => typeof x === 'string' ? x : JSON.stringify(x)).join(' ')}\n`)
+    } catch { /* never break the terminal because of logging */ }
+}
+
+log('loaded v' + VERSION + ' on ' + process.platform + ' ' + process.arch)
+const fs = require('fs')
+const path = require('path')
+const { fileURLToPath } = require('url')
+const { NgModule } = require('@angular/core')
+const { TerminalDecorator, SessionMiddleware } = require('tabby-terminal')
+
+// Typed before each path. '' (plain absolute path) is recognised as an image attachment by both
+// Claude Code and Codex when it arrives as a bracketed paste; '@' only works as a file mention in Claude Code.
+const PATH_PREFIX = ''
+const MAX_FILE_BYTES = 50 * 1024 * 1024
+const CHUNK = 32 * 1024
+const IMAGE_EXTS = new Set(['png', 'jpg', 'jpeg', 'jfif', 'gif', 'webp', 'bmp', 'tif', 'tiff', 'heic', 'heif', 'avif', 'svg', 'ico'])
+
+// Runs on the host via the SSH exec channel as: sh -c '<script>' sh <name> <ext>
+// Saves stdin to $CLIP_RECV_DIR (default ~/.cache/clip-recv/shots), prunes files older than
+// 2 days and prints "ok <ext> <absolute path>".
+const REMOTE_SH = [
+    'd="${CLIP_RECV_DIR:-$HOME/.cache/clip-recv/shots}"',
+    'mkdir -p "$d"',
+    'f="$d/shot-$(date +%Y%m%d-%H%M%S)-$$-$1.$2"',
+    'cat > "$f"',
+    '[ -s "$f" ] || { rm -f "$f"; false; }',
+    'chmod 600 "$f"',
+    '{ find "$d" -maxdepth 1 -type f -name "shot-*" -mtime +2 -delete 2>/dev/null || true; }',
+    'echo "ok $2 $f"',
+].join(' && ')
+
+function getClipboard () {
+    try { return require('electron').clipboard } catch { return null }
+}
+
+// ---------- reading the local clipboard ----------
+
+function decodeXml (s) {
+    return s.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, '&')
+}
+
+function parseUriList (text) {
+    const out = []
+    for (const line of String(text).split(/\r?\n/)) {
+        const l = line.trim()
+        if (!l.startsWith('file://')) { continue }
+        try { out.push(fileURLToPath(l)) } catch { /* ignore */ }
+    }
+    return out
+}
+
+/** Windows only: every copied file via the built-in PowerShell (FileNameW holds just the first one). */
+function winFileDropList () {
+    const { execFileSync } = require('child_process')
+    const out = execFileSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-STA', '-Command',
+        '[Console]::OutputEncoding=[Text.Encoding]::UTF8; Add-Type -AssemblyName System.Windows.Forms; [Windows.Forms.Clipboard]::GetFileDropList() | ForEach-Object { $_ }',
+    ], { timeout: 4000, windowsHide: true, encoding: 'utf8' })
+    return out.split(/\r?\n/).map(x => x.trim()).filter(Boolean)
+}
+
+/** Paths of files currently copied in the OS file manager (empty if none). */
+function clipboardFilePaths (cb, platform = process.platform, deps = { winFileDropList }) {
+    const read = (fn) => { try { return fn() } catch { return null } }
+    let paths = []
+    if (platform === 'win32') {
+        const buf = read(() => cb.readBuffer('FileNameW'))
+        if (buf && buf.length) {
+            const p = Buffer.from(buf).toString('ucs2').replace(/\0.*$/s, '')
+            if (p) {
+                paths.push(p)
+                try { const all = deps.winFileDropList(); if (all.length > 1) { paths = all } } catch { /* keep the first file */ }
+            }
+        }
+    } else if (platform === 'darwin') {
+        const plist = read(() => cb.read('NSFilenamesPboardType'))
+        if (plist) {
+            for (const m of plist.matchAll(/<string>([\s\S]*?)<\/string>/g)) { paths.push(decodeXml(m[1])) }
+        }
+        if (!paths.length) {
+            const u = read(() => cb.read('public.file-url'))
+            if (u) { paths = parseUriList(u) }
+        }
+    } else {
+        for (const fmt of ['text/uri-list', 'x-special/gnome-copied-files']) {
+            const t = read(() => Buffer.from(cb.readBuffer(fmt)).toString('utf8')) // renderer returns Uint8Array, not Buffer
+            if (t) { paths = parseUriList(t) }
+            if (paths.length) { break }
+        }
+    }
+    return [...new Set(paths)]
+}
+
+function safeBase (file) {
+    const b = path.basename(file, path.extname(file)).replace(/[^A-Za-z0-9_-]+/g, '_').replace(/^_+|_+$/g, '').slice(0, 32)
+    return b || 'img'
+}
+
+/**
+ * Image items to upload for the current clipboard, or [] when this is a normal (text) paste.
+ * Each item: { base, ext, size?, load: () => Promise<Buffer> }  or { error } for unusable files.
+ */
+function collectItems (cb, platform = process.platform, deps) {
+    if (!cb) { log('no electron clipboard available'); return [] }
+    const files = clipboardFilePaths(cb, platform, deps)
+    if (files.length) {
+        const items = []
+        for (const f of files) {
+            const ext = path.extname(f).slice(1).toLowerCase()
+            if (!IMAGE_EXTS.has(ext)) { continue }
+            let st
+            try { st = fs.statSync(f) } catch { continue }
+            if (!st.isFile()) { continue }
+            if (st.size > MAX_FILE_BYTES) { items.push({ error: `${path.basename(f)} is larger than ${MAX_FILE_BYTES >> 20} MB` }); continue }
+            items.push({ base: safeBase(f), ext: ext === 'jpeg' || ext === 'jfif' ? 'jpg' : ext === 'tiff' ? 'tif' : ext, size: st.size, load: () => fs.promises.readFile(f) })
+        }
+        return items // [] when only non-image files are copied -> normal paste
+    }
+    try {
+        if (cb.readText()) { return [] }
+        const img = cb.readImage()
+        if (!img || img.isEmpty()) { return [] }
+        return [{ base: 'clip', ext: 'png', load: async () => img.toPNG() }]
+    } catch { return [] }
+}
+
+/** Human-readable reason when a paste in an SSH tab found nothing to upload and no text (else null). */
+function describeNothingToPaste (cb) {
+    try {
+        if (!cb || cb.readText()) { return null }
+        const f = cb.availableFormats()
+        return f.length ? `clipboard has no text or usable image (formats: ${f.join(', ')})` : 'clipboard is empty (a screenshot saved to a file is not on the clipboard; use Cmd+Ctrl+Shift+4 on macOS)'
+    } catch { return null }
+}
+
+let announced = false
+function notifyTab (tab, kind, msg) { try { tab.notifications?.[kind]?.(msg) } catch { /* ignore */ } }
+
+// ---------- uploading ----------
+
+const { spawn, execFile } = require('child_process')
+
+/** Tabby's built-in SSH tab: new exec channel on the tab's existing connection. */
+async function uploadViaBuiltinSsh (ssh, item) {
+    const bytes = await item.load()
+    if (!bytes.length) { throw new Error('empty image') }
+    const ch = await ssh.activateChannel(await ssh.openSessionChannel())
+    let out = ''
+    const subs = []
+    const done = new Promise(resolve => {
+        subs.push(ch.data$.subscribe(b => { out += Buffer.from(b).toString() }))
+        subs.push(ch.extendedData$.subscribe(b => { out += Buffer.from(b).toString() }))
+        subs.push(ch.closed$.subscribe({ next: resolve, complete: resolve }))
+        subs.push(ch.eof$.subscribe({ next: () => {}, complete: () => {} }))
+    })
+    let timer
+    const timeout = new Promise((_, reject) => { timer = setTimeout(() => reject(new Error('timeout')), 15000 + bytes.length / 50) })
+    try {
+        await ch.requestExec(`sh -c '${REMOTE_SH}' sh ${item.base} ${item.ext}`)
+        for (let i = 0; i < bytes.length; i += CHUNK) {
+            await ch.write(bytes.subarray(i, i + CHUNK))
+        }
+        await ch.eof()
+        await Promise.race([done, timeout])
+    } finally {
+        clearTimeout(timer)
+        subs.forEach(s => s.unsubscribe?.())
+    }
+    const m = /^ok (\S+) (.+)$/m.exec(out.trim())
+    if (!m) { throw new Error(out.trim() || 'no output from host (is `sh` available?)') }
+    return m[2].trim()
+}
+
+// ---- local tabs that run the system `ssh` (e.g. `ssh myhost` typed in a Tabby local shell) ----
+
+const SSH_ARG_FLAGS = new Set('BbcDEeFIiJLlmOopQRSWw'.split('')) // short ssh options that take a value
+const SSH_DROP_FLAGS = new Set('tTNfnvqVGM'.split(''))           // tty / background / verbosity / control flags we must not forward
+
+function tokenizeCommandLine (s) {
+    const out = []
+    let cur = ''
+    let q = null
+    let has = false
+    for (const ch of String(s)) {
+        if (q) { if (ch === q) { q = null } else { cur += ch } continue }
+        if (ch === '"' || ch === "'") { q = ch; has = true; continue }
+        if (/\s/.test(ch)) { if (cur || has) { out.push(cur); cur = ''; has = false } continue }
+        cur += ch
+    }
+    if (cur || has) { out.push(cur) }
+    return out
+}
+
+/** tokens = ['ssh', ...args] -> { prefix: forwardable ssh options, dest } or null. The remote command (if any) is dropped. */
+function parseSshCommand (tokens) {
+    const prefix = []
+    let i = 1
+    while (i < tokens.length) {
+        const t = tokens[i]
+        if (t === '--') { i++; break }
+        if (t[0] !== '-' || t.length === 1) { break }
+        for (let j = 1; j < t.length; j++) {
+            const ch = t[j]
+            if (SSH_ARG_FLAGS.has(ch)) {
+                const attached = t.slice(j + 1)
+                const val = attached || tokens[i + 1]
+                if (val === undefined) { return null }
+                prefix.push('-' + ch, val)
+                if (!attached) { i++ }
+                break
+            }
+            if (!SSH_DROP_FLAGS.has(ch)) { prefix.push('-' + ch) }
+        }
+        i++
+    }
+    const dest = tokens[i]
+    return dest ? { prefix, dest } : null
+}
+
+function execFileP (file, args, opts) {
+    return new Promise((resolve, reject) => execFile(file, args, { timeout: 4000, windowsHide: true, encoding: 'utf8', ...opts }, (e, so) => e ? reject(e) : resolve(so)))
+}
+
+/** Full command line of a process (Tabby only gives the name + pid on macOS/Windows). */
+async function commandLineOf (pid) {
+    const n = Number(pid)
+    if (process.platform === 'win32') {
+        return (await execFileP('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', `(Get-CimInstance Win32_Process -Filter 'ProcessId=${n}').CommandLine`])).trim()
+    }
+    return (await execFileP('ps', ['-ww', '-o', 'args=', '-p', String(n)])).trim()
+}
+
+/** SSH_AUTH_SOCK of a running process (the GUI app may not have the agent socket that the user's shell exported). */
+async function agentSockOf (pid) {
+    try {
+        const n = Number(pid)
+        if (process.platform === 'linux') {
+            const env = fs.readFileSync(`/proc/${n}/environ`, 'utf8').split('\0')
+            const hit = env.find(e => e.startsWith('SSH_AUTH_SOCK='))
+            return hit ? hit.slice('SSH_AUTH_SOCK='.length) : null
+        }
+        if (process.platform === 'darwin') {
+            const out = await execFileP('ps', ['-ww', '-E', '-o', 'command=', '-p', String(n)])
+            const m = /(?:^|\s)SSH_AUTH_SOCK=(\S+)/.exec(out)
+            return m ? m[1] : null
+        }
+    } catch { /* best effort */ }
+    return null
+}
+
+/** The `ssh` the local shell of this tab is currently running, as { prefix, dest }, or null. */
+async function findLocalSsh (tab, deps = { commandLineOf, agentSockOf }) {
+    let procs = []
+    try { procs = (await tab.session?.getChildProcesses?.()) || [] } catch (e) { log('getChildProcesses failed: ' + e); return null }
+    for (const p of procs) {
+        const exe = path.basename(String(p.command || '')).replace(/\.exe$/i, '')
+        if (exe !== 'ssh') { continue }
+        let tokens
+        if (Array.isArray(p.arguments) && p.arguments.length) { tokens = [p.command, ...p.arguments] } else {
+            try { tokens = tokenizeCommandLine(await deps.commandLineOf(p.pid)) } catch (e) { log('cannot read the ssh command line: ' + e); continue }
+        }
+        const parsed = parseSshCommand(tokens)
+        if (parsed) {
+            if (!process.env.SSH_AUTH_SOCK || process.platform === 'darwin') { parsed.agentSock = await (deps.agentSockOf || agentSockOf)(p.pid) }
+            return parsed
+        }
+    }
+    return null
+}
+
+/** Upload with a separate, non-interactive `ssh` that reuses the user's own options and ~/.ssh/config (ProxyJump, keys, ControlMaster). */
+function uploadViaSystemSsh (target, item, sshBin = 'ssh') {
+    return item.load().then(bytes => new Promise((resolve, reject) => {
+        if (!bytes.length) { reject(new Error('empty image')); return }
+        const args = ['-T', '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=15', ...target.prefix, target.dest, `sh -c '${REMOTE_SH}' sh ${item.base} ${item.ext}`]
+        const env = target.agentSock ? { ...process.env, SSH_AUTH_SOCK: target.agentSock } : process.env
+        const child = spawn(sshBin, args, { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true, env })
+        let out = ''
+        let err = ''
+        let settled = false
+        const finish = (fn, v) => { if (!settled) { settled = true; clearTimeout(timer); fn(v) } }
+        const timer = setTimeout(() => { try { child.kill() } catch { /* ignore */ } finish(reject, new Error('timeout')) }, 20000 + bytes.length / 50)
+        child.stdout.on('data', d => { out += d })
+        child.stderr.on('data', d => { err += d })
+        child.on('error', e => finish(reject, e))
+        child.on('close', code => {
+            const m = /^ok (\S+) (.+)$/m.exec(out.trim())
+            if (m) { finish(resolve, m[2].trim()) } else {
+                const why = (err || out).trim().split('\n').filter(Boolean).slice(-2).join(' ')
+                finish(reject, new Error((why || `ssh exited with ${code}`) + (/permission denied|password|passphrase/i.test(why) ? ' (needs key/agent or ControlMaster: the upload ssh runs non-interactively)' : '')))
+            }
+        })
+        child.stdin.on('error', () => {})
+        child.stdin.end(Buffer.from(bytes))
+    }))
+}
+
+/** How to upload for this tab: Tabby's SSH connection, the local shell's running `ssh`, or null (nothing to do). */
+async function resolveTransport (tab) {
+    if (tab.sshSession) {
+        const ssh = tab.sshSession.ssh
+        if (ssh && typeof ssh.openSessionChannel === 'function') { return { kind: 'tabby-ssh', upload: item => uploadViaBuiltinSsh(ssh, item) } }
+        return { kind: 'tabby-ssh', upload: async () => { throw new Error('SSH session not ready') } }
+    }
+    const target = await findLocalSsh(tab)
+    if (target) { return { kind: 'system-ssh', target, upload: item => uploadViaSystemSsh(target, item) } }
+    return null
+}
+
+const busyTabs = new WeakSet()
+const lastHandled = new WeakMap() // tab -> timestamp of the last paste this plugin took over
+const markHandled = tab => lastHandled.set(tab, Date.now())
+const handledRecently = tab => Date.now() - (lastHandled.get(tab) || 0) < 1500
+
+// Diagnostics: do real Cmd/Ctrl+V key presses and DOM paste events reach the page? (logged to the trace file)
+let diagInstalled = false
+function installDiagnostics () {
+    if (diagInstalled || typeof document === 'undefined') { return }
+    diagInstalled = true
+    const where = el => el ? `${el.tagName}.${String(el.className || '').slice(0, 40)}` : 'null'
+    document.addEventListener('keydown', e => {
+        if ((e.key || '').toLowerCase() === 'v' && (e.metaKey || e.ctrlKey)) { log(`keydown v meta=${e.metaKey} ctrl=${e.ctrlKey} shift=${e.shiftKey} target=${where(e.target)} defaultPrevented=${e.defaultPrevented}`) }
+    }, true)
+    document.addEventListener('paste', e => {
+        log(`DOM paste event target=${where(e.target)} types=${e.clipboardData ? Array.from(e.clipboardData.types).join(',') : 'none'}`)
+    }, true)
+}
+installDiagnostics()
+
+/**
+ * Upload all items and call emit(buffer) with the typed paths.
+ * Resolves true when at least one path was emitted.
+ */
+async function pasteItems (tab, items, emit, transport) {
+    const notify = (kind, msg) => { try { tab.notifications?.[kind]?.(msg) } catch { /* ignore */ } }
+    const tr = transport || await resolveTransport(tab)
+    if (!tr) { notify('error', 'Image paste: this tab is not connected to an SSH host'); return false }
+    log('uploading ' + items.length + ' item(s) via ' + tr.kind + (tr.target ? ' to ' + tr.target.dest : ''))
+    const paths = []
+    for (const item of items) {
+        if (item.error) { notify('error', `Image paste: ${item.error}`); continue }
+        try { paths.push(await tr.upload(item)) } catch (e) { log('upload error: ' + (e && e.stack || e)); notify('error', `Image paste failed: ${e.message || e}`) }
+    }
+    if (!paths.length) { return false }
+    notify('notice', paths.length === 1 ? `Image saved on host: ${paths[0]}` : `${paths.length} images saved on host`)
+    // Like a drag-and-drop: one bracketed paste per path when the app enabled it (TUIs then attach the image),
+    // plain text otherwise (shell prompt).
+    const bracketed = !!(tab.frontend && tab.frontend.supportsBracketedPaste && tab.frontend.supportsBracketedPaste())
+    log('uploaded ' + paths.length + ' file(s), bracketed=' + bracketed)
+    emit(Buffer.from(paths.map(p => bracketed ? `\x1b[200~${PATH_PREFIX}${p} \x1b[201~` : `${PATH_PREFIX}${p} `).join('')))
+    return true
+}
+
+// ---------- Tabby integration ----------
+
+// Ctrl+V sends 0x16 into the session on Windows/Linux (and Ctrl+V on macOS).
+class ClipImageMiddleware extends SessionMiddleware {
+    constructor (tab, clipboardProvider) {
+        super()
+        this.tab = tab
+        this.getClipboard = clipboardProvider || getClipboard
+        this.busy = false // only true while *this middleware* holds keystrokes during an upload
+        this.queue = []
+    }
+
+    feedFromTerminal (data) {
+        if (this.busy) { this.queue.push(data); return }
+        if (data.length === 1 && data[0] === 0x16) {
+            const items = collectItems(this.getClipboard())
+            log('Ctrl+V: formats=' + (this.getClipboard()?.availableFormats?.().join(',') || '?') + ' -> ' + items.length + ' image(s)')
+            if (items.length) {
+                if (busyTabs.has(this.tab)) { return } // a paste is already uploading
+                this.busy = true
+                busyTabs.add(this.tab)
+                resolveTransport(this.tab)
+                    .then(tr => {
+                        if (!tr) { return false }
+                        markHandled(this.tab)
+                        return pasteItems(this.tab, items, buf => this.outputToSession.next(buf), tr)
+                    })
+                    .then(ok => { if (!ok) { this.outputToSession.next(data) } })
+                    .catch(() => this.outputToSession.next(data))
+                    .then(() => {
+                        this.busy = false
+                        busyTabs.delete(this.tab)
+                        const q = this.queue; this.queue = []
+                        q.forEach(d => this.feedFromTerminal(d))
+                    })
+                return
+            }
+        }
+        this.outputToSession.next(data)
+    }
+}
+
+class ClipImageDecorator extends TerminalDecorator {
+    attachToSession (tab) {
+        if (!tab.session || !tab.session.middleware) { return }
+        tab.session.middleware.unshift(new ClipImageMiddleware(tab))
+    }
+
+    // Shared by tab.paste() and the DOM paste event: take over when there is something to upload and somewhere to upload it.
+    takeOver (tab, items, original) {
+        busyTabs.add(tab)
+        return resolveTransport(tab)
+            .then(tr => {
+                if (!tr) { busyTabs.delete(tab); return original() }
+                markHandled(tab)
+                return pasteItems(tab, items, buf => tab.sendInput(buf), tr)
+                    .catch(() => false)
+                    .then(ok => { busyTabs.delete(tab); if (!ok) { return original() } })
+            })
+            .catch(e => { busyTabs.delete(tab); log('takeOver error: ' + (e && e.stack || e)); return original() })
+    }
+
+    // Cmd+V, Ctrl+Shift+V, Shift+Insert, right-click and middle-click paste all call tab.paste().
+    hookPaste (tab) {
+        if (tab.__clipImageHooked || typeof tab.paste !== 'function') { return }
+        tab.__clipImageHooked = true
+        const original = tab.paste.bind(tab)
+        tab.__clipImageOriginalPaste = original
+        tab.paste = () => {
+            log('tab.paste() called, sshSession=' + !!tab.sshSession + ' busy=' + busyTabs.has(tab))
+            if (busyTabs.has(tab)) { return Promise.resolve() }
+            const items = collectItems(getClipboard())
+            log('paste(): formats=' + (getClipboard()?.availableFormats?.().join(',') || '?') + ' -> ' + items.length + ' image(s)')
+            if (!items.length) {
+                const why = describeNothingToPaste(getClipboard())
+                if (why) { resolveTransport(tab).then(tr => { if (tr) { notifyTab(tab, 'info', `Image paste: ${why}`) } }).catch(() => {}) } // 'info' stays ~5s; Tabby's 'notice' only 1s
+                return original()
+            }
+            return this.takeOver(tab, items, original)
+        }
+    }
+
+    // macOS can deliver Cmd+V as a native "Paste" (DOM paste event on xterm's textarea) without going through tab.paste().
+    hookDomPaste (tab) {
+        if (tab.__clipImageDom || typeof document === 'undefined') { return }
+        tab.__clipImageDom = true
+        const handler = ev => {
+            try {
+                const ta = tab.frontend && tab.frontend.xterm && tab.frontend.xterm.textarea
+                if (!ta || ev.target !== ta) { return }
+                if (busyTabs.has(tab) || handledRecently(tab)) { ev.preventDefault(); ev.stopImmediatePropagation(); log('DOM paste: already handled, swallowed'); return }
+                const items = collectItems(getClipboard())
+                if (!items.length) {
+                    const why = describeNothingToPaste(getClipboard())
+                    if (why) { resolveTransport(tab).then(tr => { if (tr) { notifyTab(tab, 'info', `Image paste: ${why}`) } }).catch(() => {}) }
+                    return // let xterm paste text normally
+                }
+                ev.preventDefault(); ev.stopImmediatePropagation()
+                log('DOM paste: taking over, ' + items.length + ' item(s)')
+                this.takeOver(tab, items, tab.__clipImageOriginalPaste || (() => {}))
+            } catch (e) { log('DOM paste handler error: ' + (e && e.stack || e)) }
+        }
+        document.addEventListener('paste', handler, true)
+        try { tab.destroyed$?.subscribe?.(() => document.removeEventListener('paste', handler, true)) } catch { /* ignore */ }
+    }
+
+    attach (tab) {
+        log('attach tab=' + (tab && tab.constructor && tab.constructor.name) + ' hasSshSession=' + ('sshSession' in tab) + ' hasPaste=' + (typeof tab.paste))
+        this.hookPaste(tab)
+        this.hookDomPaste(tab)
+        if (!announced) { announced = true; setTimeout(() => notifyTab(tab, 'info', `tabby-clip-image ${VERSION} is active (SSH tabs, and local tabs running ssh): paste an image or copied image file`), 1500) }
+        setTimeout(() => {
+            this.attachToSession(tab)
+            if (tab.sessionChanged$) { this.subscribeUntilDetached(tab, tab.sessionChanged$.subscribe(() => this.attachToSession(tab))) }
+        })
+    }
+}
+
+class ClipImageModule {}
+NgModule({
+    providers: [
+        { provide: TerminalDecorator, useFactory: () => new ClipImageDecorator(), multi: true },
+    ],
+})(ClipImageModule)
+
+module.exports = { default: ClipImageModule, ClipImageMiddleware, collectItems, clipboardFilePaths, pasteItems, REMOTE_SH, parseSshCommand, tokenizeCommandLine, findLocalSsh, resolveTransport, uploadViaSystemSsh }

package/package.json

@@ -1,6 +1,23 @@
 {
   "name": "tabby-clip-image",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.0",
+  "description": "Paste images (screenshots or copied image files) in Tabby into remote TUIs (Claude Code, Codex...) over SSH: works in built-in SSH tabs AND in local tabs running ssh. Uploads to a fixed dir on the host and pastes the path. Nothing to install on the host.",
+  "keywords": [
+    "tabby-plugin",
+    "tabby",
+    "ssh",
+    "clipboard",
+    "image",
+    "paste",
+    "claude",
+    "codex"
+  ],
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "author": "barton",
+  "license": "MIT"
+}