kafox-cli 0.8.0 → 0.9.1

package/README.md

@@ -46,7 +46,7 @@ URL `https://kafox.pypag.com/cli?code=...`, entre na sua conta e clique em
 | `kafox continue` / `kafox -c` | volta para a conversa mais recente |
 | `kafox status` | conta, saldo e gateway |
 | `kafox theme` | seletor de tema |
-| `kafox background [url]` | imagem de fundo do terminal |
+| `kafox background [arquivo\|url]` | imagem de fundo da interface (`off` remove) |
 | `kafox compact` / `clear` | compacta / limpa o contexto do REPL |
 
 ## Conversas salvas
@@ -74,6 +74,17 @@ ou a roda do mouse navegam, clique ou Enter retomam a conversa escolhida.
 `kafox resume 3f1c` aceita o codigo inteiro ou so o comeco dele, e
 `kafox continue` (ou `-c`) vai direto para a ultima.
 
+A conversa guarda o modelo, o tema e o modo **rodar tudo**: se voce retomar um
+chat que estava com a aprovacao automatica ligada, ele volta ligado (e o
+contrario tambem). `kafox --allow-all` continua valendo por cima de tudo.
+
+## Imagem de fundo
+
+`/background ~/Imagens/ponte.jpg` (ou uma URL https) desenha a foto atras da
+conversa, com o texto por cima. Aceita **PNG** e **JPG**; a imagem e escurecida
+para nao atrapalhar a leitura e se ajusta sozinha ao tamanho do terminal.
+`/background off` remove, e a escolha fica em `~/.kafox/config.json`.
+
 ## Agentes e subagentes
 
 O agente tem a ferramenta `spawn_subagent`: ele lança subagentes com objetivo

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kafox-cli",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "Kafox CLI: TUI com streaming, thinking, edit com diff, agent tools (files/shell), MCP e temas",
   "bin": {
     "kafox": "bin/kafox.js"
@@ -17,7 +17,8 @@
   "dependencies": {
     "chalk": "4.1.2",
     "commander": "12.1.0",
-    "inquirer": "8.2.6"
+    "inquirer": "8.2.6",
+    "jpeg-js": "^0.4.4"
   },
   "scripts": {
     "test": "node --test \"test/*.test.js\"",

package/src/cli.js

@@ -28,7 +28,7 @@ const COMMANDS = {
   "/agents": "lista os subagentes desta sessao (objetivo, ferramentas, tempo)",
   "/mcp": "list MCP servers and tools (/mcp reload reconecta)",
   "/allow": "aprovacao automatica nesta sessao (/allow off volta a perguntar)",
-  "/background": "set background image (modal asks for URL)",
+  "/background": "imagem de fundo (/background <arquivo|url>; off remove)",
   "/clear": "clear conversation context",
   "/compact": "compact conversation context",
   "/status": "show account, balance and gateway status",
@@ -315,8 +315,8 @@ async function runREPL(options = {}) {
   return runTUI({
     commands: COMMANDS,
     onCommand: handleCommand,
-    // /theme roda dentro da TUI (modal com preview); os demais abrem prompt no terminal.
-    interactiveCommands: new Set(["/login", "/key", "/background"]),
+    // /theme e /background rodam dentro da TUI; os demais abrem prompt no terminal.
+    interactiveCommands: new Set(["/login", "/key"]),
     autoApprove: Boolean(options?.allowAll),
     // kafox --resume <codigo> volta para a conversa salva em ~/.kafox/chats.
     resume: options?.resume || null,

package/src/sessions.js

@@ -69,7 +69,7 @@ function titleFrom(messages, fallback = "") {
   return text.length > TITLE_MAX ? `${text.slice(0, TITLE_MAX - 1).trimEnd()}…` : text;
 }
 
-function save({ id, cwd, model, theme, messages, context, startedAt, title }) {
+function save({ id, cwd, model, theme, allowAll, messages, context, startedAt, title }) {
   if (!id) return null;
   ensureDir();
   const now = new Date().toISOString();
@@ -80,6 +80,8 @@ function save({ id, cwd, model, theme, messages, context, startedAt, title }) {
     cwd: cwd || process.cwd(),
     model: model || null,
     theme: theme || null,
+    // "rodar tudo" e uma escolha da conversa: ao retomar, volta como estava.
+    allowAll: Boolean(allowAll),
     startedAt: startedAt || now,
     updatedAt: now,
     messages: list,
@@ -122,6 +124,7 @@ function list() {
       title: data.title || titleFrom(data.messages),
       cwd: data.cwd,
       model: data.model,
+      allowAll: Boolean(data.allowAll),
       updatedAt: data.updatedAt,
       messages: (data.messages || []).length,
     });

package/src/theme.js

@@ -356,21 +356,16 @@ async function setContentBackground(url) {
       {
         type: "input",
         name: "url",
-        message: "Background image URL (PNG/JPG):",
+        message: "Imagem de fundo (arquivo ou URL PNG/JPG):",
         validate: (v) =>
-          /^https?:\/\/.+\.(png|jpg|jpeg|gif|webp)(\?.*)?$/i.test(v.trim()) ||
-          "Enter a valid image URL (http/https)",
+          Boolean(v.trim()) || "Informe o caminho do arquivo ou a URL",
       },
     ]);
     bg = answer.url.trim();
   }
   storage.setConfig({ background: bg });
-  console.log(chalk.green(`Background set: ${bg}`));
-  console.log(
-    chalk.dim(
-      "Tip: terminals like Windows Terminal / iTerm2 support image backgrounds. Use `kafox background` to open the modal."
-    )
-  );
+  console.log(chalk.green(`Fundo definido: ${bg}`));
+  console.log(chalk.dim("Abra a interface (kafox) para ver a imagem atras da conversa."));
 }
 
 module.exports = {

package/src/tools.js

@@ -1,6 +1,6 @@
 const fs = require("fs");
 const path = require("path");
-const { spawnSync } = require("child_process");
+const { spawn } = require("child_process");
 
 // Limites para nao estourar o contexto nem travar a TUI.
 const MAX_READ_CHARS = 40_000;
@@ -213,27 +213,94 @@ function listDir(cwd, args) {
   return `${relative(cwd, full)}\n${rows.join("\n")}${extra}`;
 }
 
+// Quanto de cada stream fica em memoria enquanto o comando roda. A saida
+// enviada ao modelo e menor (MAX_OUTPUT_CHARS), mas guardar um pouco mais
+// evita perder o comeco do stderr de um comando que fala muito.
+const MAX_COMMAND_BUFFER = 8 * 1024 * 1024;
+
+/**
+ * Executa o comando sem travar a TUI: `spawn` assincrono em vez de
+ * `spawnSync`, para o spinner e o relogio do cartao continuarem andando
+ * enquanto o processo roda.
+ */
 function runCommand(cwd, args) {
   const command = String(args.command || "").trim();
   if (!command) throw new Error("comando vazio");
   const timeout = Math.min(120_000, Math.max(1_000, Number(args.timeout_ms) || COMMAND_TIMEOUT_MS));
 
-  const result = spawnSync(command, {
-    shell: true,
-    cwd: path.resolve(cwd),
-    timeout,
-    encoding: "utf8",
-    maxBuffer: 8 * 1024 * 1024,
-    env: { ...process.env, KAFOX_CLI: "1" },
-  });
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(command, {
+        shell: true,
+        cwd: path.resolve(cwd),
+        env: { ...process.env, KAFOX_CLI: "1" },
+        windowsHide: true,
+      });
+    } catch (error) {
+      return resolve(`exit: ?\nstderr:\n${error.message}`);
+    }
+
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let spawnError = null;
+    let done = false;
 
-  const stdout = truncate(result.stdout || "", MAX_OUTPUT_CHARS);
-  const stderr = truncate(result.stderr || "", MAX_OUTPUT_CHARS);
-  const parts = [`exit: ${result.status == null ? "?" : result.status}`];
-  if (result.error?.code === "ETIMEDOUT") parts.push(`timeout: ${timeout}ms`);
-  if (stdout.trim()) parts.push(`stdout:\n${stdout.trimEnd()}`);
-  if (stderr.trim()) parts.push(`stderr:\n${stderr.trimEnd()}`);
-  return parts.join("\n");
+    // No Windows o `shell: true` cria um cmd.exe que nao leva o processo
+    // filho junto ao ser morto: taskkill /T encerra a arvore inteira.
+    const killTree = () => {
+      if (!child.pid) return;
+      if (process.platform === "win32") {
+        try {
+          const killer = spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], {
+            windowsHide: true,
+            stdio: "ignore",
+          });
+          killer.on("error", () => {});
+        } catch {}
+        return;
+      }
+      try {
+        child.kill("SIGKILL");
+      } catch {}
+    };
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      killTree();
+    }, timeout);
+    timer.unref?.();
+
+    child.stdout?.setEncoding("utf8");
+    child.stderr?.setEncoding("utf8");
+    child.stdout?.on("data", (chunk) => {
+      if (stdout.length < MAX_COMMAND_BUFFER) stdout += chunk;
+    });
+    child.stderr?.on("data", (chunk) => {
+      if (stderr.length < MAX_COMMAND_BUFFER) stderr += chunk;
+    });
+
+    const finish = (status) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      const out = truncate(stdout, MAX_OUTPUT_CHARS);
+      const err = truncate(stderr, MAX_OUTPUT_CHARS);
+      const parts = [`exit: ${status == null || spawnError ? "?" : status}`];
+      if (timedOut) parts.push(`timeout: ${timeout}ms`);
+      if (out.trim()) parts.push(`stdout:\n${out.trimEnd()}`);
+      if (err.trim()) parts.push(`stderr:\n${err.trimEnd()}`);
+      else if (spawnError) parts.push(`stderr:\n${spawnError}`);
+      resolve(parts.join("\n"));
+    };
+
+    child.on("error", (error) => {
+      spawnError = error.message;
+      finish(null);
+    });
+    child.on("close", (code) => finish(code));
+  });
 }
 
 async function executeTool(name, args = {}, context = {}) {

package/src/tui.js

@@ -24,6 +24,7 @@ const { diffBlocks } = require("./diff");
 const { toolMeta, parseCommandOutput } = require("./tools");
 const { McpHub } = require("./mcp");
 const sessions = require("./sessions");
+const wallpaper = require("./wallpaper");
 
 const ANSI = /\x1b\[[0-9;]*m/g;
 const stripAnsi = (value) => String(value).replace(ANSI, "");
@@ -510,6 +511,7 @@ function initialState() {
     pageSize: 10,
     mouse: true,
     retry: null,
+    wallpaper: null,
     sessionId: null,
     sessionStartedAt: null,
     model: cfg.model || null,
@@ -1335,6 +1337,9 @@ async function runTUI({
 
   // resume: "pick" abre o seletor de conversas, "last" pega a mais recente e
   // qualquer outro valor e o codigo do chat que o usuario fechou no Ctrl+C.
+  // `kafox --allow-all` (ou KAFOX_ALLOW_ALL=1) vale para a sessao inteira e
+  // ganha do que esta salvo na conversa.
+  const forcedAllow = Boolean(autoApprove) || process.env.KAFOX_ALLOW_ALL === "1";
   let resumeMissing = null;
   let resumePick = false;
   if (resume) {
@@ -1350,6 +1355,7 @@ async function runTUI({
         state.context = Array.isArray(saved.context) ? saved.context : [];
         if (saved.model) state.model = saved.model;
         if (saved.theme) state.theme = saved.theme;
+        state.autoApprove = forcedAllow || Boolean(saved.allowAll);
         state.tokens = estimateTokens(state);
       } else {
         resumeMissing = String(id || resume);
@@ -1360,8 +1366,8 @@ async function runTUI({
     state.sessionId = sessions.newId();
     state.sessionStartedAt = new Date().toISOString();
   }
-  // `kafox --allow-all` (ou KAFOX_ALLOW_ALL=1) ja comeca sem pedir aprovacao.
-  state.autoApprove = Boolean(autoApprove) || process.env.KAFOX_ALLOW_ALL === "1";
+  // Sem conversa retomada, so a flag/env libera a aprovacao automatica.
+  if (forcedAllow) state.autoApprove = true;
   let mcp = new McpHub({ cwd: process.cwd() });
   let spinner = null;
   let escTimer = null;
@@ -1444,6 +1450,7 @@ async function runTUI({
         cwd: process.cwd(),
         model: state.model,
         theme: state.theme,
+        allowAll: state.autoApprove,
         messages: state.messages,
         context: state.context,
         startedAt: state.sessionStartedAt,
@@ -1458,9 +1465,56 @@ async function runTUI({
     const cols = Math.max(30, stdout.columns || 80);
     const rows = Math.max(14, stdout.rows || 24);
     const frame = buildFrame(state, cols, rows, commands);
+    const grid = wallpaperGrid(cols, rows);
+    if (grid) frame.lines = wallpaper.paint(frame.lines, grid);
     paintFrame(frame, { cols, rows });
   }
 
+  /**
+   * Grade da imagem no tamanho atual do terminal. Fica em cache: so e refeita
+   * quando a tela muda de tamanho ou quando o fundo troca.
+   */
+  function wallpaperGrid(cols, rows) {
+    const bg = state.wallpaper;
+    if (!bg?.image) return null;
+    if (!bg.grid || bg.cols !== cols || bg.rows !== rows || bg.theme !== state.theme) {
+      const base = wallpaper.hexToRgb(themeColors(state.theme).bg) || [12, 12, 16];
+      bg.grid = wallpaper.buildGrid(bg.image, cols, rows, { dim: 0.45, base });
+      bg.cols = cols;
+      bg.rows = rows;
+      bg.theme = state.theme;
+    }
+    return bg.grid;
+  }
+
+  /** `/background <arquivo|url>` desenha a foto atras da conversa. */
+  async function setBackground(source, { quiet = false } = {}) {
+    const value = String(source || "").trim();
+    if (!value || ["off", "none", "0", "limpar"].includes(value.toLowerCase())) {
+      state.wallpaper = null;
+      state.modal = { title: "Fundo", text: "Imagem de fundo removida." };
+      storage.setConfig({ background: null });
+      return render();
+    }
+
+    state.modal = null;
+    state.wallpaper = { source: value, image: null, grid: null, cols: 0, rows: 0 };
+    render();
+    try {
+      const image = await wallpaper.load(value);
+      state.wallpaper = { source: value, image, grid: null, cols: 0, rows: 0 };
+      storage.setConfig({ background: value });
+    } catch (error) {
+      state.wallpaper = null;
+      // No inicio da sessao o fundo salvo pode falhar (offline, arquivo movido):
+      // nao vale abrir um modal por isso, so avisa quando o usuario pediu.
+      if (!quiet) {
+        state.modal = { title: "Fundo", text: `Nao consegui carregar ${value}.\n${error.message}` };
+      }
+    }
+    return render();
+  }
+
   /**
    * Desenho incremental: manda so as linhas diferentes, dentro de uma unica
    * atualizacao sincronizada. E o que impede o piscar do modal e do streaming.
@@ -1562,6 +1616,7 @@ async function runTUI({
     state.context = Array.isArray(saved.context) ? saved.context : [];
     if (saved.model) state.model = saved.model;
     if (saved.theme) state.theme = saved.theme;
+    state.autoApprove = forcedAllow || Boolean(saved.allowAll);
     state.files = [];
     state.tokens = estimateTokens(state);
     state.scroll = 0;
@@ -1647,9 +1702,25 @@ async function runTUI({
     // /models e /model sem argumento abrem o mesmo seletor navegavel.
     if ((name === "/model" || name === "/models") && !parts[1]) return openModelPicker();
     if (name === "/theme") return openThemePicker();
+    if (name === "/background" || name === "/bg") {
+      const value = parts.slice(1).join(" ");
+      if (!value) {
+        state.modal = {
+          title: "Fundo",
+          text:
+            "kafox /background <arquivo ou URL>\n\n" +
+            "Aceita PNG e JPG, de um arquivo do computador ou de um link https.\n" +
+            "Exemplo: /background ~/Imagens/ponte.jpg\n" +
+            "/background off remove a imagem.",
+        };
+        return render();
+      }
+      return setBackground(value);
+    }
     if (name === "/allow") {
       const argument = (parts[1] || "on").toLowerCase();
       state.autoApprove = argument !== "off" && argument !== "ask";
+      persist();
       state.modal = {
         title: "Aprovacao",
         text: state.autoApprove
@@ -1958,6 +2029,7 @@ async function runTUI({
     if (!pending) return;
     state.approval = null;
     if (decision === "always") state.autoApprove = true;
+    if (decision === "always") persist();
     render();
     pending.resolve(decision !== "deny");
   }
@@ -2277,6 +2349,8 @@ async function runTUI({
   render();
   if (resumePick) openChatPicker();
   connectMcp().catch(() => {});
+  const savedBackground = storage.getConfig().background;
+  if (savedBackground) setBackground(savedBackground, { quiet: true }).catch(() => {});
 
   spinner = setInterval(() => {
     if (!state.busy || closed) return;

package/src/wallpaper.js

@@ -0,0 +1,380 @@
+/**
+ * Imagem de fundo da TUI.
+ *
+ * O terminal nao tem "papel de parede": o jeito de mostrar uma foto e desenhar
+ * cada celula com dois pixels, um no primeiro plano e outro no fundo do caractere
+ * "▀" (meio bloco). Assim a imagem aparece atras do texto e o desenho continua
+ * legivel porque as cores sao escurecidas antes de entrar na tela.
+ *
+ * Suporta PNG (decodificado aqui, sem dependencia) e JPEG (jpeg-js), de um
+ * arquivo local ou de uma URL http(s).
+ */
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const zlib = require("zlib");
+
+const MAX_BYTES = 12 * 1024 * 1024;
+const FETCH_TIMEOUT_MS = 15_000;
+const HALF_BLOCK = "▀";
+
+/* ------------------------------------------------------------------ decoders */
+
+function paeth(a, b, c) {
+  const p = a + b - c;
+  const pa = Math.abs(p - a);
+  const pb = Math.abs(p - b);
+  const pc = Math.abs(p - c);
+  if (pa <= pb && pa <= pc) return a;
+  return pb <= pc ? b : c;
+}
+
+/** PNG 8 bits (RGB, RGBA, tons de cinza e paleta), sem entrelacamento. */
+function decodePng(buffer) {
+  if (buffer.length < 8 || buffer.readUInt32BE(0) !== 0x89504e47) {
+    throw new Error("nao e um PNG valido");
+  }
+
+  let offset = 8;
+  let width = 0;
+  let height = 0;
+  let bitDepth = 8;
+  let colorType = 6;
+  let interlace = 0;
+  let palette = null;
+  const chunks = [];
+
+  while (offset + 8 <= buffer.length) {
+    const length = buffer.readUInt32BE(offset);
+    const type = buffer.toString("ascii", offset + 4, offset + 8);
+    const data = buffer.subarray(offset + 8, offset + 8 + length);
+    offset += 12 + length;
+
+    if (type === "IHDR") {
+      width = data.readUInt32BE(0);
+      height = data.readUInt32BE(4);
+      bitDepth = data[8];
+      colorType = data[9];
+      interlace = data[12];
+    } else if (type === "PLTE") {
+      palette = Buffer.from(data);
+    } else if (type === "IDAT") {
+      chunks.push(Buffer.from(data));
+    } else if (type === "IEND") {
+      break;
+    }
+  }
+
+  if (!width || !height) throw new Error("PNG sem cabecalho IHDR");
+  if (bitDepth !== 8) throw new Error(`PNG ${bitDepth} bits por canal nao suportado (use 8)`);
+  if (interlace) throw new Error("PNG entrelacado nao suportado");
+
+  const channels = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 }[colorType];
+  if (!channels) throw new Error(`tipo de cor PNG ${colorType} nao suportado`);
+  if (colorType === 3 && !palette) throw new Error("PNG com paleta mas sem PLTE");
+
+  const raw = zlib.inflateSync(Buffer.concat(chunks));
+  const stride = width * channels;
+  const lines = Buffer.alloc(stride * height);
+
+  let read = 0;
+  for (let y = 0; y < height; y += 1) {
+    if (read >= raw.length) throw new Error("PNG truncado");
+    const filter = raw[read];
+    read += 1;
+    const out = lines.subarray(y * stride, (y + 1) * stride);
+    const prev = y ? lines.subarray((y - 1) * stride, y * stride) : null;
+
+    for (let x = 0; x < stride; x += 1) {
+      const value = raw[read + x];
+      const left = x >= channels ? out[x - channels] : 0;
+      const up = prev ? prev[x] : 0;
+      const upLeft = prev && x >= channels ? prev[x - channels] : 0;
+      let byte;
+      switch (filter) {
+        case 0:
+          byte = value;
+          break;
+        case 1:
+          byte = value + left;
+          break;
+        case 2:
+          byte = value + up;
+          break;
+        case 3:
+          byte = value + ((left + up) >> 1);
+          break;
+        case 4:
+          byte = value + paeth(left, up, upLeft);
+          break;
+        default:
+          throw new Error(`filtro PNG ${filter} desconhecido`);
+      }
+      out[x] = byte & 0xff;
+    }
+    read += stride;
+  }
+
+  const pixels = new Uint8Array(width * height * 4);
+  for (let y = 0; y < height; y += 1) {
+    for (let x = 0; x < width; x += 1) {
+      const source = y * stride + x * channels;
+      const target = (y * width + x) * 4;
+      if (colorType === 0) {
+        const gray = lines[source];
+        pixels[target] = gray;
+        pixels[target + 1] = gray;
+        pixels[target + 2] = gray;
+        pixels[target + 3] = 255;
+      } else if (colorType === 4) {
+        const gray = lines[source];
+        pixels[target] = gray;
+        pixels[target + 1] = gray;
+        pixels[target + 2] = gray;
+        pixels[target + 3] = lines[source + 1];
+      } else if (colorType === 3) {
+        const index = lines[source] * 3;
+        pixels[target] = palette[index] ?? 0;
+        pixels[target + 1] = palette[index + 1] ?? 0;
+        pixels[target + 2] = palette[index + 2] ?? 0;
+        pixels[target + 3] = 255;
+      } else {
+        pixels[target] = lines[source];
+        pixels[target + 1] = lines[source + 1];
+        pixels[target + 2] = lines[source + 2];
+        pixels[target + 3] = colorType === 6 ? lines[source + 3] : 255;
+      }
+    }
+  }
+
+  return { width, height, pixels };
+}
+
+function decodeJpeg(buffer) {
+  // Carregado so quando alguem usa JPEG: quem nunca pediu fundo nao paga por ele.
+  let jpeg;
+  try {
+    jpeg = require("jpeg-js");
+  } catch {
+    throw new Error("JPEG precisa do pacote jpeg-js (npm i -g kafox-cli de novo)");
+  }
+  const image = jpeg.decode(Buffer.from(buffer), { useTArray: true, formatAsRGBA: true });
+  if (!image?.width) throw new Error("JPEG invalido");
+  return { width: image.width, height: image.height, pixels: image.data };
+}
+
+/** Descobre o formato pelos primeiros bytes e devolve RGBA. */
+function decodeBuffer(buffer) {
+  if (!buffer?.length) throw new Error("imagem vazia");
+  if (buffer.length < 12) throw new Error("arquivo pequeno demais para ser imagem");
+
+  const isPng = buffer.readUInt32BE(0) === 0x89504e47;
+  const isJpeg = buffer[0] === 0xff && buffer[1] === 0xd8;
+  if (isPng) return decodePng(buffer);
+  if (isJpeg) return decodeJpeg(buffer);
+
+  const head = buffer.toString("ascii", 0, 6);
+  if (head.startsWith("GIF")) throw new Error("GIF nao suportado: use PNG ou JPG");
+  if (head.startsWith("RIFF") && buffer.toString("ascii", 8, 12) === "WEBP") {
+    throw new Error("WebP nao suportado: use PNG ou JPG");
+  }
+  throw new Error("formato desconhecido: use PNG ou JPG");
+}
+
+/* ------------------------------------------------------------------ carregar */
+
+function expandHome(source) {
+  if (!source.startsWith("~")) return source;
+  return path.join(os.homedir(), source.slice(1));
+}
+
+async function readSource(source) {
+  const value = String(source || "").trim();
+  if (!value) throw new Error("informe o caminho ou a URL da imagem");
+
+  if (/^https?:\/\//i.test(value)) {
+    const response = await fetch(value, {
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+      headers: { accept: "image/png,image/jpeg,image/*" },
+    });
+    if (!response.ok) throw new Error(`download falhou (HTTP ${response.status})`);
+    const size = Number(response.headers.get("content-length") || 0);
+    if (size > MAX_BYTES) throw new Error(`imagem grande demais (${Math.round(size / 1024 / 1024)} MB)`);
+    return Buffer.from(await response.arrayBuffer());
+  }
+
+  const file = path.resolve(expandHome(value));
+  const info = fs.statSync(file);
+  if (!info.isFile()) throw new Error(`${value} nao e um arquivo`);
+  if (info.size > MAX_BYTES) throw new Error(`imagem grande demais (${Math.round(info.size / 1024 / 1024)} MB)`);
+  return fs.readFileSync(file);
+}
+
+/** Carrega de URL ou arquivo e devolve a imagem em RGBA. */
+async function load(source) {
+  return decodeBuffer(await readSource(source));
+}
+
+/* ------------------------------------------------------------------ desenho */
+
+function hexToRgb(value) {
+  const hex = String(value || "").replace("#", "");
+  if (hex.length !== 6) return null;
+  const number = parseInt(hex, 16);
+  if (Number.isNaN(number)) return null;
+  return [(number >> 16) & 0xff, (number >> 8) & 0xff, number & 0xff];
+}
+
+/**
+ * Recorta o centro da imagem no formato da tela. Cada meia linha do terminal e
+ * um pixel quadrado, entao a proporcao alvo e `cols x rows*2`.
+ */
+function coverRegion(image, cols, rows) {
+  const target = cols / Math.max(1, rows * 2);
+  const current = image.width / image.height;
+  if (current > target) {
+    const width = image.height * target;
+    return { x: (image.width - width) / 2, y: 0, width, height: image.height };
+  }
+  const height = image.width / target;
+  return { x: 0, y: (image.height - height) / 2, width: image.width, height };
+}
+
+function averageColor(image, x0, y0, x1, y1, samples = 4) {
+  const { pixels, width } = image;
+  let r = 0;
+  let g = 0;
+  let b = 0;
+  let count = 0;
+  const stepX = (x1 - x0) / samples;
+  const stepY = (y1 - y0) / samples;
+
+  for (let sy = 0; sy < samples; sy += 1) {
+    const py = Math.min(image.height - 1, Math.floor(y0 + sy * stepY));
+    for (let sx = 0; sx < samples; sx += 1) {
+      const px = Math.min(image.width - 1, Math.floor(x0 + sx * stepX));
+      const index = (py * width + px) * 4;
+      r += pixels[index];
+      g += pixels[index + 1];
+      b += pixels[index + 2];
+      count += 1;
+    }
+  }
+
+  if (!count) return [0, 0, 0];
+  return [Math.round(r / count), Math.round(g / count), Math.round(b / count)];
+}
+
+/**
+ * Monta a grade de celulas: cada celula tem dois pixels (topo e base do "▀").
+ * `dim` mistura a imagem com `base` para o texto continuar legivel.
+ */
+function buildGrid(image, cols, rows, { dim = 0.45, base = null } = {}) {
+  const columns = Math.max(1, Math.floor(cols));
+  const lines = Math.max(1, Math.floor(rows) * 2);
+  const region = coverRegion(image, columns, lines);
+  const back = base || [10, 10, 14];
+  const mix = (color) => color.map((value, index) => Math.round(value * dim + back[index] * (1 - dim)));
+
+  const cells = [];
+  for (let row = 0; row < lines; row += 1) {
+    const y0 = region.y + (row * region.height) / lines;
+    const y1 = region.y + ((row + 1) * region.height) / lines;
+    const line = [];
+    for (let col = 0; col < columns; col += 1) {
+      const x0 = region.x + (col * region.width) / columns;
+      const x1 = region.x + ((col + 1) * region.width) / columns;
+      line.push(mix(averageColor(image, x0, y0, x1, y1)));
+    }
+    cells.push(line);
+  }
+
+  // Junta as meias linhas em celulas com topo e base.
+  const grid = [];
+  for (let row = 0; row < lines; row += 2) {
+    const top = cells[row];
+    const bottom = cells[row + 1] || cells[row];
+    grid.push(top.map((color, col) => ({ top: color, bottom: bottom[col] })));
+  }
+  return { cols: columns, rows: Math.floor(rows), cells: grid };
+}
+
+/* ------------------------------------------------------------------ ANSI */
+
+/** Atualiza o estilo corrente a partir de uma sequencia SGR. */
+function trackStyle(sequence, style) {
+  const params = sequence.slice(2, -1);
+  const parts = params ? params.split(";") : ["0"];
+  if (parts.includes("0")) style.length = 0;
+  for (const part of parts) {
+    if (part === "0" || part === "39" || part === "49") continue;
+    style.push(part);
+  }
+}
+
+function backgroundActive(style) {
+  return style.some((part) => {
+    const code = Number(part);
+    return (code >= 40 && code <= 47) || (code >= 100 && code <= 107) || code === 48;
+  });
+}
+
+function cellEscape({ top, bottom }) {
+  return `\x1b[38;2;${top[0]};${top[1]};${top[2]}m\x1b[48;2;${bottom[0]};${bottom[1]};${bottom[2]}m`;
+}
+
+/**
+ * Troca os espacos vazios do frame pelas celulas da imagem. Texto e celulas com
+ * fundo proprio (caixas, paineis) ficam como estao.
+ */
+function paint(lines, grid) {
+  if (!grid?.cells?.length) return lines;
+
+  return lines.map((line, row) => {
+    const cells = grid.cells[row];
+    if (!cells) return line;
+    if (!line.includes(" ")) return line;
+
+    let out = "";
+    let col = 0;
+    let index = 0;
+    const style = [];
+
+    while (index < line.length) {
+      if (line[index] === "\x1b") {
+        const match = /^\x1b\[[0-9;]*m/.exec(line.slice(index));
+        if (match) {
+          out += match[0];
+          trackStyle(match[0], style);
+          index += match[0].length;
+          continue;
+        }
+      }
+
+      const char = line[index];
+      const cell = cells[col];
+      if (char === " " && cell && !backgroundActive(style)) {
+        const restore = style.length ? `\x1b[${style.join(";")}m` : "";
+        out += `\x1b[0m${cellEscape(cell)}${HALF_BLOCK}${restore}`;
+      } else {
+        out += char;
+      }
+      index += 1;
+      col += 1;
+    }
+
+    return out;
+  });
+}
+
+module.exports = {
+  load,
+  decodeBuffer,
+  decodePng,
+  buildGrid,
+  paint,
+  coverRegion,
+  hexToRgb,
+  HALF_BLOCK,
+  MAX_BYTES,
+};