@hncode/hncode 0.5.6 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hncode/hncode",
-  "version": "0.5.6",
+  "version": "0.6.1",
   "description": "hncode — A cyan-blue TUI AI coding agent with zero runtime dependencies.",
   "type": "module",
   "main": "src/index.js",
@@ -33,6 +33,5 @@
     "coding",
     "ai",
     "tui"
-  ],
-  "dependencies": {}
+  ]
 }

package/src/agent.js

@@ -4,6 +4,7 @@
 
 import { LLM, setToolsList } from './llm.js';
 import { tools, combinedTools, getTool, llmTools } from './tools/index.js';
+import { validateToolArgs } from './tools/validate-args.js';
 import { DELEGATION_TOOLS } from './subagent-types.js';
 import { estimateMessagesTokens, estimateRequestOverhead, estimateTokens, measureToolDefTokens, messageTokens, TokenLedger, forgetMessageTokens } from './term.js';
 import { runHooks, runPatch, runPatchSync } from './plugin.js';
@@ -72,10 +73,46 @@ const COMPACTION_INSTRUCTION = [
   '',
   'Be concise and proportional: a long multi-step task warrants detail, a nearly finished exchange needs only a sentence or two.',
   '',
-  'Respond with text only. Do not call any tools.',
+  'Respond with text only. Do not call any tools. Any tool-call syntax in your answer is discarded and scores the handoff as failed.'
 ].join('\n');
 
 // Trailing note: the model should RESUME, not answer the summary.
+// A summariser can answer with tool-call syntax even when no tools were offered — the format is in its
+// training data, and a model interrupted mid-workflow reaches for it. Nothing was called, so the text is
+// noise, and left in a handoff summary the next turn reads it as a step that happened.
+//
+// The shapes covered are the ones these models actually emit: a special-token block (`<|tool_call|>`), a
+// fenced ```tool_call block, and a bare JSON object that claims a `name` and `arguments`. Only a block that
+// occupies whole lines is removed, so prose that merely mentions calling a tool survives.
+function stripToolCallText(text) {
+  if (typeof text !== 'string' || !text) return text || '';
+
+  // NOTHING WAS CALLED, SO THE BLOCK IS NOISE — but removing it outright can leave nothing at all.
+  //
+  // A summariser that answers ONLY with a tool call produced no summary: stripping to '' makes the caller
+  // treat the compaction as failed, and the fallback there is to drop the history. So the stripped text is
+  // measured: if it lost its substance, the original is kept VERBATIM with a note saying what it is. A
+  // confusing summary is recoverable; a discarded one is not.
+  let out = text;
+  // A special-token block: closed form, or an unterminated one running to the end of its line.
+  out = out.replace(/<\|tool_call\|>[^\n]*(?:<\|\/tool_call\|>)?/g, '');
+  // Fenced block form.
+  out = out.replace(/```tool_call[\s\S]*?```/g, '');
+  // A bare JSON object on its own lines that declares a tool invocation.
+  out = out.replace(/^\s*\{[^\n]*"name"\s*:\s*"[^"]+"[^\n]*"arguments"[^\n]*\}\s*$/gm, '');
+  out = out.replace(/\n{3,}/g, '\n\n').trim();
+
+  if (out.length > 0) return out;
+
+  // Every remaining character was a tool call: keep the original, marked for what it is.
+  return [
+    '(The summariser answered with a tool call instead of a summary. No tool was actually run — the text is',
+    'reproduced below unchanged so nothing is lost. Treat it as a summary that was never written.)',
+    '',
+    text.trim(),
+  ].join('\n');
+}
+
 const COMPACTION_CONTINUATION_TEXT = 'Context compaction is complete — continue the work that was in progress when it began.';
 
 // Clip to a TOKEN budget, counting non-ASCII as one token per character (the same
@@ -842,7 +879,20 @@ const filtered = (Array.isArray(cfg.toolFilter) && cfg.toolFilter.length
           // reasoning model they can consume the whole output budget — which
           // returns an EMPTY summary, and an empty summary is what turns a
           // compaction into a silent loss of history.
-          try { summary = await llm.requestText(summaryPrompt, { noReasoning: true, noTools: true }); } catch { summary = ''; }
+          try {
+            // A DECLARATION IS NEEDED FOR THE REFUSAL.
+            //
+            // `tool_choice: 'none'` is rejected by both providers unless a tool list accompanies it, and the
+            // summariser is a fresh instance with none. One inert definition is declared so the refusal can be
+            // expressed: the model then cannot produce a tool call, rather than being asked not to.
+            llm._tools = [{
+              name: 'noop',
+              description: 'Takes no action. Present only so the request can refuse tool use.',
+              parameters: { type: 'object', properties: {}, additionalProperties: false },
+            }];
+            const raw = await llm.requestText(summaryPrompt, { noReasoning: true, toolChoice: 'none' });
+            summary = stripToolCallText(raw);
+          } catch { summary = ''; }
           this._summaryLlm = null;
         }
         // Interrupted mid-summary: do NOT trim. Aborting yields an empty summary, and
@@ -1123,6 +1173,21 @@ const filtered = (Array.isArray(cfg.toolFilter) && cfg.toolFilter.length
           return { ok: false, result, editDiff: null, media: false };
         }
 
+        // THE ARGUMENTS MUST MATCH THE TOOL'S OWN SCHEMA.
+        //
+        // An unknown parameter used to be accepted in silence, and the model had no way to learn that the
+        // argument it took trouble to compute was thrown away: it sends `line_offset` to a tool that takes
+        // `start_line`, gets a plausible answer computed from defaults, and concludes the tool is broken.
+        // Refusing the call names the key and lists the accepted ones, which is the only thing that stops the
+        // same mistake being retried with a different spelling.
+        const argError = validateToolArgs(tc.args, tool.parameters);
+        if (argError) {
+          result = `Error: ${tc.name}: ${argError}`;
+          this.onEvent({ type: 'tool_use', id: tc.id, name: tc.name, args: tc.args });
+          return { ok: false, result, editDiff: null, media: false };
+        }
+
+
         // SHELL HOOK: PreToolUse. A non-zero exit blocks the tool, and its
         // message goes back to the model in place of the tool result — that is
         // the whole point of a pre-hook (e.g. refuse a write that fails a lint

package/src/clipboard.js

@@ -62,33 +62,51 @@ function win() { return process.platform === 'win32'; }
 /**
  * Put text on the clipboard.
  *
- * WINDOWS: `Set-Clipboard` through PowerShell, NOT `clip.exe`.
+ * WINDOWS: `clip.exe` on STDIN, with the PowerShell path as the fallback.
  *
- * `clip.exe` takes UTF-16LE and needed a byte order mark to be read correctly — without it
- * non-ASCII arrived as mojibake (`中文测试` came back as `-N噀Km諎`, measured). But the mark is then
- * part of the clipboard text: every copy began with a zero-width U+FEFF that showed up as a stray
- * invisible character wherever it was pasted. Measured over six samples, `Set-Clipboard` was better
- * on every one:
+ * An earlier version chose `Set-Clipboard` because `clip.exe` prefixed every copy with a zero-width U+FEFF.
+ * That was a BOM problem, not a `clip.exe` problem: it reads stdin as a byte stream, so a leading `FF FE` is
+ * two literal characters. Sent as plain UTF-16LE with no mark, it round-trips exactly — verified on ASCII,
+ * Chinese, emoji, embedded newlines and 400000 characters.
  *
- *     copied           clip.exe + BOM             Set-Clipboard
- *     hello            U+FEFF hello               hello
- *     中文测试          U+FEFF 中文测试             中文测试
- *     line1\nline2     U+FEFF line1 CRLF line2    line1\nline2   (line endings untouched)
- *     emoji 🎉 ok       U+FEFF emoji 🎉 ok         emoji 🎉 ok
+ * Two measured reasons to prefer it:
  *
- * It also needs no escaping: PowerShell receives a .NET string rather than a byte stream, so there
- * is no console parser to satisfy — which is what the BOM and the quoting were working around.
+ *   characters   clip.exe   pwsh one-shot
+ *          100      77ms          788ms
+ *         5000      56ms          748ms
+ *        20000      61ms   ENAMETOOLONG   <- the command line is capped near 32KB
+ *       400000      58ms   ENAMETOOLONG
  *
- * `clip.exe` stays as a fallback for a machine with no PowerShell at all, where a copy carrying a
- * stray BOM beats no copy.
+ * `clip.exe` takes the text on STDIN, so its cost does not depend on the length and it has no ceiling; the
+ * PowerShell route puts the text on its COMMAND LINE and fails outright past ~20k characters. The one
+ * difference that remains: `clip.exe` normalises `\n` to `\r\n`, which is what the Windows clipboard expects
+ * anyway.
+ *
+ * `setClipboardText` stays for a machine with no `clip.exe`.
  */
 export function copyText(text) {
   const s = String(text == null ? '' : text);
   if (!s) return false;
   if (win()) {
-    if (setClipboardText(s)) return true;
-    cp.execSync('clip', { input: Buffer.concat([Buffer.from([0xff, 0xfe]), Buffer.from(s, 'utf16le')]), windowsHide: true, timeout: 5000 });
-    return true;
+    // `clip.exe` FIRST, fed UTF-8 through a 65001 console.
+    //
+    // Measured 150-193ms at every size from 100 to 400000 characters, against 748-788ms for a PowerShell
+    // one-shot — and the PowerShell route puts the text on its COMMAND LINE, which Windows caps near 32KB, so
+    // a 20k-character copy failed outright with ENAMETOOLONG.
+    //
+    // THE ENCODING IS NOT UTF-16. `clip.exe` decodes stdin with the console code page, which is 936 (GBK) on a
+    // Chinese Windows: UTF-16LE bytes came back byte-swapped (`你好` U+4F60 U+597D arrived as U+604F U+597D)
+    // and UTF-8 bytes without the matching code page came back as mojibake. `chcp 65001` on the child and UTF-8
+    // in the pipe is what round-trips — verified on ASCII, Chinese, emoji and 400k characters.
+    //
+    // Synchronous, because the caller announces "Copied" the moment this returns.
+    const r = cp.spawnSync('cmd', ['/c', 'chcp 65001 >nul && clip'], {
+      input: Buffer.from(s, 'utf8'),
+      windowsHide: true,
+      timeout: 5000,
+    });
+    if (r && r.status === 0) return true;
+    return setClipboardText(s);
   }
   const cmd = process.platform === 'darwin' ? 'pbcopy' : 'xclip -selection clipboard';
   cp.execSync(cmd, { input: Buffer.from(s, 'utf8'), timeout: 5000 });
@@ -113,6 +131,41 @@ function setClipboardText(s) {
   return false;
 }
 
+/**
+ * Put text on the clipboard WITHOUT blocking the event loop.
+ *
+ * `copyText` is synchronous because most callers want to know the outcome before they say "Copied". A copy is
+ * 150-190ms of child process on Windows, which is long enough to be felt as a stutter when it runs between two
+ * paints. The TUI uses this where a reply is not needed.
+ *
+ * @param {string} text
+ * @returns {Promise<boolean>}
+ */
+export function copyTextAsync(text) {
+  const s = String(text == null ? '' : text);
+  if (!s) return Promise.resolve(false);
+  if (!win()) {
+    try { copyText(s); return Promise.resolve(true); } catch { return Promise.resolve(false); }
+  }
+  return new Promise((resolve) => {
+    try {
+      // Same command and encoding as `copyText`: the code page has to be set on the child, and the payload is
+      // UTF-8. See the note there for why UTF-16 does not work.
+      const child = cp.spawn('cmd', ['/c', 'chcp 65001 >nul && clip'], {
+        windowsHide: true,
+        stdio: ['pipe', 'ignore', 'ignore'],
+      });
+      child.on('error', () => resolve(false));
+      child.on('close', (code) => resolve(code === 0));
+      child.stdin.on('error', () => { /* a broken pipe is reported by `close` */ });
+      child.stdin.end(Buffer.from(s, 'utf8'));
+    } catch {
+      // No clip.exe: fall back to the blocking route rather than losing the copy.
+      try { resolve(setClipboardText(s)); } catch { resolve(false); }
+    }
+  });
+}
+
 // Which PowerShell the helper runs. `pwsh` (7) starts far faster than the built-in
 // `powershell` (5.1) — measured 1.9s vs 11.5s for the same image probe — and the image
 // path needs the WinForms/Drawing assemblies. This is only the PREFERRED name: it is
@@ -193,7 +246,13 @@ function startHelper(exe) {
   // unavailable" for a clipboard that had content. The queued resolver here is what
   // marks the shell as ready, so one sentinel still has exactly one owner.
   helperQueue.push(() => { helperReady = true; });
-  helper.stdin.write("try { Add-Type -AssemblyName System.Windows.Forms; Add-Type -AssemblyName System.Drawing } catch {}\n'" + SENT + "'\n");
+  // The sequence probe's P/Invoke declaration is compiled here too: the first `Add-Type` on a cold shell
+  // measured ~900ms, which is exactly the cost this warm-up exists to move off the paste path.
+  helper.stdin.write(
+    "try { Add-Type -AssemblyName System.Windows.Forms; Add-Type -AssemblyName System.Drawing } catch {}\n"
+    + "try { if(-not ('HnClip' -as [type])){Add-Type -Namespace '' -Name 'HnClip' -MemberDefinition '[DllImport(\"user32.dll\")] public static extern uint GetClipboardSequenceNumber();'} } catch {}\n"
+    + "'" + SENT + "'\n",
+  );
 }
 
 /** Tear down the helper and release every waiter. A read must never be left hanging on
@@ -249,7 +308,10 @@ function helperRun(script, timeoutMs) {
 function readOnce() {
   if (win()) {
     const b64 = runPowershell(
-      '-NoProfile -Command "[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes((Get-Clipboard -Raw) + \'\'))"',
+      // `Clipboard::GetText()` instead of `Get-Clipboard -Raw`: measured on a 20k-character text, the cmdlet
+      // took 169ms and the .NET call 13ms. `Get-Clipboard` goes through PowerShell's COM wrapper, which
+      // copies the string several times before it reaches the pipeline.
+      '-NoProfile -Command "Add-Type -AssemblyName System.Windows.Forms; [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes([System.Windows.Forms.Clipboard]::GetText() + \'\'))"',
       { encoding: 'ascii', windowsHide: true, timeout: ONESHOT_MS },
     );
     if (b64 == null) throw new Error('no powershell');
@@ -269,7 +331,7 @@ export async function readText(timeoutMs = HELPER_CMD_MS) {
     // warming is answered by nothing, and the cold path is the expensive one.
     if (helper && await waitHelperReady(HELPER_READY_MS)) {
       helperBusy = true;
-      const out = await helperRun('[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes((Get-Clipboard -Raw) + ""))', timeoutMs);
+      const out = await helperRun('[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes([System.Windows.Forms.Clipboard]::GetText() + ""))', timeoutMs);
       if (out != null) {
         const b64 = out.replace(/\r/g, '').split('\n').filter((l) => l.trim()).pop() || '';
         try { return { text: Buffer.from(b64.trim(), 'base64').toString('utf8'), via: 'helper' }; } catch {}
@@ -301,7 +363,38 @@ export async function readText(timeoutMs = HELPER_CMD_MS) {
 // PowerShell expression (silently returned nothing), which made FILE pastes fall
 // back to the slow cold spawn. Emitting one F:: line per file is simpler and
 // also supports multi-file copies.
-//
+/**
+ * Just the clipboard's TEXT, or '' — no file list, no image.
+ *
+ * Asked before paying for a PNG: a browser's image copy carries the pixels AND the address, and only the text
+ * formats can hold that address. Cheap on the warm helper, which is already running by the time anyone pastes.
+ *
+ * @returns {Promise<string>}
+ */
+export async function readClipboardTextOnly() {
+  if (!win()) { try { return readOnce() || ''; } catch { return ''; } }
+  warmClipboard();
+  if (!helper) {
+    try { return readOnce() || ''; } catch { return ''; }
+  }
+  if (!helperReady && !await waitHelperReady(HELPER_READY_MS)) {
+    try { return readOnce() || ''; } catch { return ''; }
+  }
+  for (let i = 0; i < 20 && helperBusy; i++) await new Promise((r) => setTimeout(r, 25));
+  if (helperBusy || !helper) {
+    try { return readOnce() || ''; } catch { return ''; }
+  }
+  helperBusy = true;
+  let out;
+  try {
+    out = await helperRun(CLIP_PROBE_TEXT, HELPER_CMD_MS);
+  } finally {
+    helperBusy = false;
+  }
+  const line = String(out || '').split('\n').map((l) => l.trim()).find((l) => l.startsWith('T::'));
+  if (!line) return '';
+  try { return Buffer.from(line.slice(3), 'base64').toString('utf8'); } catch { return ''; }
+}
 // The image branch uses the .NET WinForms clipboard, NOT `Get-Clipboard -Image`:
 // that parameter only exists on some builds (and is absent even from the pwsh 7
 // in use here), so it silently failed everywhere and image paste never worked.
@@ -321,15 +414,24 @@ export async function readText(timeoutMs = HELPER_CMD_MS) {
  */
 const CLIP_PROBE_TEXT = [
   "$ErrorActionPreference='SilentlyContinue'",
-  "$t=Get-Clipboard -Raw",
+  // .NET, not the cmdlet: 13ms against 169ms on the same 20k-character text.
+  "$t=[System.Windows.Forms.Clipboard]::GetText()",
   "if($t){'T::'+[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($t))}",
 ].join('; ');
 
 const CLIP_PROBE = [
   "$ErrorActionPreference='SilentlyContinue'",
-  "$f=Get-Clipboard -Format FileDropList",
-  "if($f -and $f.Count -gt 0){$f|ForEach-Object{'F::'+$_.FullName};return}",
-  "$t=Get-Clipboard -Raw",
+  // FILES COME FROM THE .NET CLIPBOARD, not `Get-Clipboard -Format FileDropList`.
+  //
+  // That parameter does not exist in PowerShell 7 — `Get-Clipboard: A parameter cannot be found that matches
+  // parameter name 'Format'` — and the `SilentlyContinue` above turns the error into an empty result, so a
+  // copied file read as "clipboard unavailable" while copied text worked. `Clipboard::GetFileDropList()` is the
+  // same call on both versions; verified on the 5.1 build in System32 and on pwsh 7 here.
+  "Add-Type -AssemblyName System.Windows.Forms",
+  "$f=[System.Windows.Forms.Clipboard]::GetFileDropList()",
+  "if($f -and $f.Count -gt 0){$f|ForEach-Object{'F::'+$_};return}",
+  // .NET, not the cmdlet: 13ms against 169ms on the same 20k-character text.
+  "$t=[System.Windows.Forms.Clipboard]::GetText()",
   "if($t){'T::'+[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($t));return}",
   // The assemblies are loaded once by warmClipboard(); no Add-Type here, so the
   // probe stays fast even the first time an image is on the clipboard.
@@ -337,6 +439,22 @@ const CLIP_PROBE = [
   "if($null -ne $i){$p=Join-Path $env:TEMP ('hncode-paste-'+[guid]::NewGuid().ToString('N')+'.png');$i.Save($p,[System.Drawing.Imaging.ImageFormat]::Png);'I::'+$p}",
 ].join('; ');
 
+/**
+ * The clipboard's sequence number, one integer.
+ *
+ * Windows bumps it on every clipboard write, so comparing two readings answers "did the content change"
+ * without reading the content. `Get-Clipboard` has no equivalent, so this P/Invokes `user32` — once, because
+ * the type stays compiled for the life of the warm shell.
+ *
+ * A real read costs time proportional to the payload (measured: 14ms at 1k characters, 48ms at 400k); this
+ * does not, which is what makes a repeat paste of a long text instant.
+ */
+const CLIP_SEQ_PROBE = [
+  "$ErrorActionPreference='SilentlyContinue'",
+  "if(-not ('HnClip' -as [type])){Add-Type -Namespace '' -Name 'HnClip' -MemberDefinition '[DllImport(\"user32.dll\")] public static extern uint GetClipboardSequenceNumber();'}",
+  "'S::'+[HnClip]::GetClipboardSequenceNumber()",
+].join('; ');
+
 // Parse the probe output into { text, via }. Handles one-or-more F:: lines.
 function parseClipResult(out) {
   const lines = String(out == null ? '' : out).replace(/\r/g, '').split('\n').map((l) => l.trim()).filter(Boolean);
@@ -353,6 +471,38 @@ function parseClipResult(out) {
   return null;
 }
 
+/**
+ * A URL hidden in the TEXT of a copied image, or null.
+ *
+ * Copying an image out of a browser puts several formats on the clipboard at once: the pixels, an HTML
+ * fragment (`<img src="…">`, sometimes a `data:` URL) and, for a plain image, the image's own address. The
+ * pixel route costs a PNG written to disk for something the model can fetch directly — so the text formats
+ * are checked FIRST and only a clipboard with no address at all becomes a file.
+ *
+ * Only http(s) and `data:` are accepted. A `file:` URL is the same thing as a copied file, which the file
+ * drop list already covers.
+ *
+ * @param {string} text The clipboard's text, possibly an HTML fragment.
+ * @returns {string|null}
+ */
+export function imageUrlFromClipboardText(text) {
+  const s = String(text || '').trim();
+  if (!s) return null;
+  // A bare URL: the image's own address was copied.
+  const bare = /^(https?:\/\/\S+|data:image\/[a-z0-9.+-]+;base64,[A-Za-z0-9+/=\s]+)$/i.exec(s);
+  if (bare) return bare[1].replace(/\s+/g, '').trim();
+  // An HTML fragment: take the src of the first <img>, which is what a browser's image copy produces.
+  const img = /<img\b[^>]*\bsrc\s*=\s*("([^"]*)"|'([^']*)'|([^\s>]+))/i.exec(s);
+  if (img) {
+    const url = (img[2] || img[3] || img[4] || '').trim();
+    if (/^(https?:\/\/|data:image\/)/i.test(url)) return url.replace(/\s+/g, '');
+  }
+  // A plain address on its own line inside a longer text selection.
+  const line = s.split(/\r?\n/).map((l) => l.trim())
+    .find((l) => /^https?:\/\/\S+\.(png|jpe?g|gif|webp|bmp|svg)(\?\S*)?$/i.test(l));
+  return line || null;
+}
+
 // ---- pasted-image lifecycle ------------------------------------------------
 // A pasted image is written to a temp .png (the model needs a PATH to hand to
 // ReadMediaFile), so something has to remove it again or the temp dir fills up
@@ -442,14 +592,49 @@ export function readClipboardContent() {
   return parseClipResult(out) || { text: '', via: 'none' };
 }
 
+// ---- the fast path's memory --------------------------------------------------
+//
+// `GetClipboardSequenceNumber` is one integer, and Windows bumps it on every clipboard write. Asking the
+// helper for it is a single cheap call; when it matches the last read, the previous result is returned without
+// touching the clipboard at all. That is what makes a repeat paste instant regardless of how long the text is —
+// the read cost scaled with the payload, but the sequence check does not.
+let lastSeq = null;
+let lastResult = null;
+/** The sequence number alone, read on the warm helper. Null when it is not available. */
+async function readClipboardSequence() {
+  warmClipboard();
+  if (!helper) return null;
+  if (!helperReady && !await waitHelperReady(HELPER_READY_MS)) return null;
+  if (helperBusy) return null;               // somebody is mid-command; the caller can just read normally
+  helperBusy = true;
+  let out;
+  try {
+    out = await helperRun(CLIP_SEQ_PROBE, HELPER_CMD_MS);
+  } finally {
+    helperBusy = false;
+  }
+  const line = String(out || '').split('\n').map((l) => l.trim()).find((l) => l.startsWith('S::'));
+  if (!line) return null;
+  const n = Number(line.slice(3));
+  return Number.isFinite(n) ? n : null;
+}
+
 // Async version that prefers the warm helper (~10ms) over a cold spawn (~2.9s).
 export async function readClipboardContentAsync() {
   if (!win()) {
     try { return { text: readOnce(), via: 'oneshot' }; } catch { return { text: '', via: 'none' }; }
   }
+  // A CLIPBOARD THAT HAS NOT CHANGED IS NOT READ AGAIN.
+  //
+  // The measured cost of a read is dominated by the payload (14ms for 1k characters, 48ms for 400k) and the
+  // user pays it on every paste even when the clipboard holds the same thing. The sequence number answers "did
+  // it change" in one cheap call, so a repeat paste of the same large text is instant.
+  const seq = await readClipboardSequence();
+  if (seq !== null && seq === lastSeq && lastResult) return { ...lastResult };
   const viaHelper = await readViaHelper();
-  if (viaHelper) return viaHelper;
-  return readClipboardContent();
+  const result = viaHelper || readClipboardContent();
+  if (seq !== null) { lastSeq = seq; lastResult = result; }
+  return result;
 }
 
 // The PowerShell logic for the one-shot fallback lives in a temp .ps1 file:
@@ -461,13 +646,16 @@ function clipScriptPath() {
   const p = path.join(os.tmpdir(), 'hncode-clipread.ps1');
   const script = [
     "$ErrorActionPreference = 'SilentlyContinue'",
-    '$files = Get-Clipboard -Format FileDropList',
-    'if ($files -and $files.Count -gt 0) { $files | ForEach-Object { "F::" + $_.FullName }; exit }',
-    '$txt = Get-Clipboard -Raw',
-    'if ($txt) { "T::" + [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($txt)); exit }',
-    // .NET clipboard, not `Get-Clipboard -Image` (see the CLIP_PROBE note).
+    // .NET clipboard for BOTH files and images. `Get-Clipboard -Format FileDropList` is missing from
+    // PowerShell 7, and with SilentContinue that turned a copied file into "nothing on the clipboard".
     'Add-Type -AssemblyName System.Windows.Forms',
     'Add-Type -AssemblyName System.Drawing',
+    '$files = [System.Windows.Forms.Clipboard]::GetFileDropList()',
+    'if ($files -and $files.Count -gt 0) { $files | ForEach-Object { "F::" + $_ }; exit }',
+    // .NET, not the cmdlet: the cmdlet copies the string several times before the pipeline sees it.
+    '$txt = [System.Windows.Forms.Clipboard]::GetText()',
+    'if ($txt) { "T::" + [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($txt)); exit }',
+    // .NET clipboard, not `Get-Clipboard -Image` (see the CLIP_PROBE note).
     '$img = [System.Windows.Forms.Clipboard]::GetImage()',
     'if ($null -ne $img) {',
     '  $path = Join-Path $env:TEMP ("hncode-paste-" + [guid]::NewGuid().ToString("N") + ".png")',

package/src/image-row.js

@@ -0,0 +1,111 @@
+/**
+ * Where a bitmap sits in a text frame.
+ *
+ * The TUI composes a frame as an array of strings and writes only the rows that changed, each addressed
+ * absolutely. A bitmap breaks that model twice: it is not text, so it cannot live in a row's bytes, and it
+ * is more than one row tall, so the rows under it must stay blank or the next repaint paints over it.
+ *
+ * So a row that carries an image is written as a sentinel — a single private-use character plus the
+ * payload — and this module turns a frame into the bytes that place it: address the row, emit the
+ * sequence, then remember which rows the image covers so the following text rows can be skipped.
+ *
+ * A SIXEL PAYLOAD DRAWN INLINE IS JUST CHARACTERS. That is why the first attempt showed nothing: the
+ * terminal consumed the bytes as text, scrolled them, and the formula never appeared. Placement needs a
+ * cursor move first, which is what `\x1b[<row>;<col>H` does.
+ */
+
+/** Marks a row whose content is a placed bitmap. A private-use code point no text will contain. */
+export const IMAGE_MARK = '\u0001IMG:';
+
+/**
+ * Separates the payload from the source that produced it.
+ *
+ * NOT A NUL BYTE. `SPIN_PLACEHOLDER` in the transcript renderer is `\u0000`, and every row is run through a
+ * substitution that replaces it with the spinner frame — so a tag built on it arrived as `⠋SRC:…` and the
+ * source was unreadable. `\u0001` is what `IMAGE_MARK` already uses and nothing substitutes it.
+ */
+export const SOURCE_TAG = '\u0001SRC:';
+
+
+/**
+ * Encode an image row: the mark, then the payload and its geometry, base64-free but length-prefixed so a
+ * payload containing the mark cannot be misparsed.
+ *
+ * `source` is optional and travels with the row for pictures that can be REGENERATED: a formula that straddles
+ * the top of the window must be redrawn from its first visible row, and only its TeX can produce that raster.
+ * It is stored last, after the sequence, so a row written before this field existed still parses.
+ *
+ * @param {string} sequence The terminal sequence to emit.
+ * @param {number} rows Rows of text the image covers.
+ * @param {number} cols Columns the image covers.
+ * @param {string} [source] What produced the sequence, for a picture that may need cropping later.
+ */
+export function encodeImageRow(sequence, rows, cols, source) {
+  const head = IMAGE_MARK + rows + ':' + cols + ':';
+  return typeof source === 'string' && source !== ''
+    ? head + sequence + SOURCE_TAG + source
+    : head + sequence;
+}
+
+/**
+ * True when a composed row is an image rather than text.
+ *
+ * The row may carry the transcript's indent prefix — `messageLines` gives every line one — so the marker is
+ * not necessarily at index 0. Matching it anywhere in the first few characters is what makes this work
+ * without the row builder having to special-case images.
+ */
+export function isImageRow(line) {
+  if (typeof line !== 'string') return false;
+  const at = line.indexOf(IMAGE_MARK);
+  return at >= 0 && at < 8 && /^\s*$/.test(line.slice(0, at));
+}
+
+/**
+ * Split an image row back into its parts.
+ * @returns {{sequence: string, rows: number, cols: number, source: string}|null}
+ */
+export function parseImageRow(line) {
+  if (!isImageRow(line)) return null;
+  const at = line.indexOf(IMAGE_MARK);
+  const rest = line.slice(at + IMAGE_MARK.length);
+  const firstColon = rest.indexOf(':');
+  if (firstColon < 0) return null;
+  const secondColon = rest.indexOf(':', firstColon + 1);
+  if (secondColon < 0) return null;
+  const rows = Number(rest.slice(0, firstColon));
+  const cols = Number(rest.slice(firstColon + 1, secondColon));
+  if (!Number.isFinite(rows) || !Number.isFinite(cols)) return null;
+  let body = rest.slice(secondColon + 1);
+  let source = '';
+  const tag = body.lastIndexOf(SOURCE_TAG);
+  if (tag >= 0) {
+    source = body.slice(tag + SOURCE_TAG.length);
+    body = body.slice(0, tag);
+  }
+  return { rows, cols, sequence: body, source };
+}
+
+
+/**
+ * The bytes that place one image at its row, and how many rows it covers.
+ *
+ * @param {string} line The image row.
+ * @param {number} rowIndex 0-based screen row the row was composed for.
+ * @param {string} reset SGR reset to restore after the sequence.
+ * @returns {{bytes: string, covered: number}|null}
+ */
+export function imageBytes(line, rowIndex, reset) {
+  const parsed = parseImageRow(line);
+  if (!parsed) return null;
+
+  // DEC PRIVATE MODE 80 IS THE SIXEL SCROLLING MODE.
+  //
+  // With it enabled (the default) a terminal that draws a bitmap pushes the text below it down — and in a
+  // full-screen TUI every bitmap therefore scrolls the whole interface. That is what produced the repeated
+  // composer: each formula shoved the frame up and the next paint drew it again further down.
+  //
+  // `?80l` turns the mode off for the duration of the draw and `?80h` restores it. dsh-tui wraps its own
+  // placement the same way.
+  const bytes = `\x1b[?80l\x1b[${rowIndex + 1};1H${reset}${parsed.sequence}\x1b[?80h`;
+  return { bytes, covered: parsed.rows };
+}