komado 0.1.0

package/src/config.js

@@ -0,0 +1,49 @@
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+
+// Self-contained runtime home. Override with KOMADO_HOME (handy for tests).
+const usingDefaultHome = !process.env.KOMADO_HOME;
+const HOME = usingDefaultHome
+  ? path.join(os.homedir(), '.komado')
+  : path.resolve(process.env.KOMADO_HOME);
+// The pre-rename home (the project used to be "manga-tui") — migrated once on
+// first run so existing config / reading progress / MangaDex login carry over.
+const LEGACY_HOME = path.join(os.homedir(), '.manga-tui');
+
+export const paths = {
+  home: HOME,
+  configFile: path.join(HOME, 'config.json'),
+  progressFile: path.join(HOME, 'progress.json'),
+  credentialsFile: path.join(HOME, 'credentials.json'),
+  cacheDir: path.join(HOME, 'cache'),
+  logFile: path.join(HOME, 'komado.log'),
+};
+
+export function ensureDirs() {
+  // One-time migration from the old ~/.manga-tui home so saved state isn't
+  // orphaned. Best-effort, default-home only (same filesystem → rename suffices).
+  if (usingDefaultHome && !fs.existsSync(HOME) && fs.existsSync(LEGACY_HOME)) {
+    try { fs.renameSync(LEGACY_HOME, HOME); } catch { /* leave the legacy dir as-is */ }
+  }
+  fs.mkdirSync(paths.home, { recursive: true });
+  fs.mkdirSync(paths.cacheDir, { recursive: true });
+}
+
+export const DEFAULT_CONFIG = {
+  localLibraryPaths: [],   // directories scanned by the local source
+  language: 'en',          // preferred MangaDex translatedLanguage
+  contentRating: ['safe', 'suggestive'],
+  dataSaver: true,         // smaller MangaDex page images — ideal for a terminal
+  renderer: 'auto',        // auto | halfblock | chafa
+  theme: 'default',
+  syncProgress: true,      // push read-markers to MangaDex while logged in
+};
+
+export const MANGADEX = {
+  api: 'https://api.mangadex.org',
+  auth: 'https://auth.mangadex.org/realms/mangadex/protocol/openid-connect/token',
+  uploads: 'https://uploads.mangadex.org',
+  userAgent: 'komado/0.1 (+https://github.com/RyuPrad/komado)',
+  pageLimit: 20,
+};

package/src/domain/shape.js

@@ -0,0 +1,47 @@
+// The unified data-shape contract. Rows from MangaDex and from the local
+// filesystem are normalized into ONE Manga/Chapter shape, so every downstream
+// consumer (search, reader, progress, UI) treats them identically. The only
+// source-specific seam is `source.loadPageBuffer()`, which resolves raw bytes.
+
+export const globalKey = (source, id) => `${source}:${id}`;
+
+export function makeManga(p) {
+  return {
+    source: p.source,
+    id: String(p.id),
+    key: globalKey(p.source, p.id),
+    title: p.title || 'Untitled',
+    altTitles: p.altTitles || [],
+    description: p.description || '',
+    authors: p.authors || [],
+    status: p.status || 'unknown',
+    tags: p.tags || [],
+    coverUrl: p.coverUrl || null,
+    language: p.language || 'en',
+    chaptersCount: p.chaptersCount ?? null,
+    raw: p.raw,
+  };
+}
+
+export function makeChapter(p) {
+  return {
+    source: p.source,
+    id: String(p.id),
+    key: globalKey(p.source, p.id),
+    mangaKey: p.mangaKey,
+    number: p.number ?? null,   // string like "12.5", or null for oneshots
+    volume: p.volume ?? null,
+    title: p.title || '',
+    language: p.language || 'en',
+    pages: p.pages ?? null,
+    publishedAt: p.publishedAt || null,
+    raw: p.raw,
+  };
+}
+
+export function chapterLabel(ch) {
+  const head = ch.number != null && ch.number !== ''
+    ? `Ch. ${ch.number}${ch.volume != null && ch.volume !== '' ? ` (Vol. ${ch.volume})` : ''}`
+    : 'Oneshot';
+  return ch.title ? `${head} — ${ch.title}` : head;
+}

package/src/hooks/useStdoutDimensions.js

@@ -0,0 +1,19 @@
+import { useState, useEffect } from 'react';
+
+// Terminal size + live updates on resize. The reader recomputes its viewport
+// and re-renders the page at the new width from this.
+export function useStdoutDimensions() {
+  const read = () => ({
+    cols: process.stdout.columns || 80,
+    rows: process.stdout.rows || 24,
+  });
+  const [size, setSize] = useState(read);
+
+  useEffect(() => {
+    const onResize = () => setSize(read());
+    process.stdout.on('resize', onResize);
+    return () => process.stdout.off('resize', onResize);
+  }, []);
+
+  return size;
+}

package/src/lib/AppError.js

@@ -0,0 +1,26 @@
+// Typed, operational errors — same idea as your server AppError, minus HTTP plumbing.
+// statusCode is kept for parity/log triage; the TUI maps these to friendly messages.
+export class AppError extends Error {
+  constructor(message, statusCode = 500, opts = {}) {
+    super(message);
+    this.name = this.constructor.name;
+    this.statusCode = statusCode;
+    this.isOperational = true;
+    if (opts.cause) this.cause = opts.cause;
+    if (opts.meta) Object.assign(this, opts.meta);
+  }
+}
+
+// Critical-vs-decorative branching at the call site, instead of string-matching.
+export class NotFoundError extends AppError {
+  constructor(message = 'Not found', opts) { super(message, 404, opts); }
+}
+export class SourceError extends AppError {
+  constructor(message = 'Source unavailable', opts) { super(message, 502, opts); }
+}
+export class UnsupportedError extends AppError {
+  constructor(message = 'Unsupported', opts) { super(message, 422, opts); }
+}
+export class AuthError extends AppError {
+  constructor(message = 'Authentication required', opts) { super(message, 401, opts); }
+}

package/src/lib/cache.js

@@ -0,0 +1,57 @@
+// In-memory cache with TTL, negative caching, and stampede protection —
+// a port of your createCache. `wrap` shares a single in-flight promise per key
+// so concurrent callers (e.g. two screens requesting the same chapter) collapse
+// into one upstream request.
+export function createCache({ ttlMs = 60_000, negativeTtlMs = 5_000, max = 500 } = {}) {
+  const store = new Map();      // key -> { value, expires }
+  const inflight = new Map();   // key -> Promise
+
+  function get(key) {
+    const entry = store.get(key);
+    if (!entry) return undefined;
+    if (entry.expires <= Date.now()) {
+      store.delete(key);
+      return undefined;
+    }
+    return entry.value;
+  }
+
+  function set(key, value, ttl) {
+    const isEmpty = value === null || value === undefined;
+    const life = ttl ?? (isEmpty ? negativeTtlMs : ttlMs);
+    store.set(key, { value, expires: Date.now() + life });
+    // Cheap bound: evict the oldest insertion when over capacity.
+    if (store.size > max) {
+      const oldest = store.keys().next().value;
+      store.delete(oldest);
+    }
+  }
+
+  async function wrap(key, fn, ttl) {
+    const cached = get(key);
+    if (cached !== undefined) return cached; // note: a cached `null` is a hit (negative cache)
+    if (inflight.has(key)) return inflight.get(key);
+
+    const promise = (async () => {
+      try {
+        const value = await fn();
+        set(key, value, ttl);
+        return value;
+      } finally {
+        inflight.delete(key);
+      }
+    })();
+
+    inflight.set(key, promise);
+    return promise;
+  }
+
+  return {
+    get,
+    set,
+    wrap,
+    delete: (key) => store.delete(key),
+    clear: () => { store.clear(); inflight.clear(); },
+    get size() { return store.size; },
+  };
+}

package/src/lib/catchAsync.js

@@ -0,0 +1,12 @@
+// TUI flavour of your server catchAsync. Instead of forwarding to next(err),
+// it resolves a { data, error } result so hooks can drop straight into state
+// without a try/catch at every call site (and never crash the render loop).
+export function catchAsync(fn) {
+  return async (...args) => {
+    try {
+      return { data: await fn(...args), error: null };
+    } catch (error) {
+      return { data: null, error };
+    }
+  };
+}

package/src/lib/envelope.js

@@ -0,0 +1,14 @@
+// Consistent { data, pagination, meta } shape across every source, exactly like
+// your API envelope. Sources return this so hooks/UI are source-agnostic.
+export function envelope(data, { pagination = null, meta = {} } = {}) {
+  return { data, pagination, meta };
+}
+
+export function paginate({ offset = 0, limit = 0, total = 0 } = {}) {
+  return {
+    offset,
+    limit,
+    total,
+    hasMore: total > 0 ? offset + limit < total : false,
+  };
+}

package/src/lib/fetchWithBackoff.js

@@ -0,0 +1,74 @@
+import { SourceError } from './AppError.js';
+
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(signal.reason ?? new Error('aborted'));
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener('abort', () => {
+      clearTimeout(timer);
+      reject(signal.reason ?? new Error('aborted'));
+    }, { once: true });
+  });
+}
+
+// Global fetch + retries on 429/5xx with exponential backoff, honouring
+// Retry-After, plus a hard per-attempt timeout. Caller-supplied AbortSignal
+// short-circuits retries (used by the hooks' cancelled-flag guard).
+export async function fetchWithBackoff(url, options = {}) {
+  const {
+    retries = 4,
+    baseDelayMs = 500,
+    maxDelayMs = 8_000,
+    timeoutMs = 20_000,
+    signal: extSignal,
+    ...fetchOpts
+  } = options;
+
+  let attempt = 0;
+  for (;;) {
+    const ctrl = new AbortController();
+    const onExtAbort = () => ctrl.abort(extSignal.reason);
+    if (extSignal) {
+      if (extSignal.aborted) ctrl.abort(extSignal.reason);
+      else extSignal.addEventListener('abort', onExtAbort, { once: true });
+    }
+    const timer = setTimeout(() => ctrl.abort(new Error(`timeout after ${timeoutMs}ms`)), timeoutMs);
+
+    try {
+      const res = await fetch(url, { ...fetchOpts, signal: ctrl.signal });
+
+      if ((res.status === 429 || res.status >= 500) && attempt < retries) {
+        const retryAfter = Number(res.headers.get('retry-after'));
+        const delay = Number.isFinite(retryAfter) && retryAfter > 0
+          ? retryAfter * 1000
+          : Math.min(maxDelayMs, baseDelayMs * 2 ** attempt) + Math.random() * 200;
+        attempt += 1;
+        await sleep(delay, extSignal);
+        continue;
+      }
+      return res;
+    } catch (err) {
+      // Caller cancelled — propagate without retrying.
+      if (extSignal?.aborted) throw err;
+      if (attempt < retries) {
+        const delay = Math.min(maxDelayMs, baseDelayMs * 2 ** attempt) + Math.random() * 200;
+        attempt += 1;
+        await sleep(delay, extSignal);
+        continue;
+      }
+      throw new SourceError(`Request failed: ${url}`, { cause: err });
+    } finally {
+      clearTimeout(timer);
+      extSignal?.removeEventListener('abort', onExtAbort);
+    }
+  }
+}
+
+// Convenience JSON wrapper that throws a typed error on non-2xx.
+export async function fetchJson(url, options = {}) {
+  const res = await fetchWithBackoff(url, options);
+  if (!res.ok) {
+    throw new SourceError(`HTTP ${res.status} for ${url}`, { meta: { statusCode: res.status } });
+  }
+  return res.json();
+}

package/src/lib/logger.js

@@ -0,0 +1,41 @@
+import fs from 'node:fs';
+import { paths } from '../config.js';
+
+// A TUI owns stdout — console.log would corrupt the Ink render. So debug output
+// goes to a file, only when KOMADO_DEBUG is set. Tail it with:
+//   tail -f ~/.komado/komado.log
+const enabled = !!process.env.KOMADO_DEBUG;
+let stream = null;
+
+function out() {
+  if (!enabled) return null;
+  if (!stream) {
+    try {
+      fs.mkdirSync(paths.home, { recursive: true });
+      stream = fs.createWriteStream(paths.logFile, { flags: 'a' });
+    } catch {
+      stream = null;
+    }
+  }
+  return stream;
+}
+
+function fmt(arg) {
+  if (typeof arg === 'string') return arg;
+  if (arg instanceof Error) return `${arg.name}: ${arg.message}`;
+  try { return JSON.stringify(arg); } catch { return String(arg); }
+}
+
+function write(level, args) {
+  const s = out();
+  if (!s) return;
+  s.write(`[${new Date().toISOString()}] ${level} ${args.map(fmt).join(' ')}\n`);
+}
+
+export const logger = {
+  enabled,
+  debug: (...a) => write('DEBUG', a),
+  info: (...a) => write('INFO', a),
+  warn: (...a) => write('WARN', a),
+  error: (...a) => write('ERROR', a),
+};

package/src/lib/natsort.js

@@ -0,0 +1,7 @@
+// Natural ("human") ordering so page2 < page10 and "Chapter 1.5" sorts sanely.
+const collator = new Intl.Collator(undefined, { numeric: true, sensitivity: 'base' });
+
+export const naturalCompare = (a, b) => collator.compare(String(a), String(b));
+
+export const naturalSort = (arr, key = (x) => x) =>
+  [...arr].sort((a, b) => naturalCompare(key(a), key(b)));

package/src/lib/text.js

@@ -0,0 +1,18 @@
+export function truncate(str, max) {
+  const s = String(str ?? '');
+  if (max <= 1 || s.length <= max) return s;
+  return s.slice(0, Math.max(1, max - 1)) + '…';
+}
+
+// Compact relative time ("3h ago") in LOCAL time, anchored to now.
+export function relativeTime(ts) {
+  if (!ts) return '';
+  const diff = Date.now() - ts;
+  const mins = Math.round(diff / 60_000);
+  if (mins < 1) return 'just now';
+  if (mins < 60) return `${mins}m ago`;
+  const hrs = Math.round(mins / 60);
+  if (hrs < 24) return `${hrs}h ago`;
+  const days = Math.round(hrs / 24);
+  return `${days}d ago`;
+}

package/src/render/chafa.js

@@ -0,0 +1,64 @@
+import { execFile, spawnSync } from 'node:child_process';
+import { promisify } from 'node:util';
+import { writeFile, unlink, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import sharp from 'sharp';
+import { paths } from '../config.js';
+import { detectCapabilities } from './detect.js';
+
+const execFileAsync = promisify(execFile);
+
+let dirReady = false;
+async function ensureTempDir() {
+  if (dirReady) return;
+  await mkdir(paths.cacheDir, { recursive: true });
+  dirReady = true;
+}
+
+async function withTempImage(buffer, fn) {
+  await ensureTempDir();
+  const file = path.join(
+    paths.cacheDir,
+    `chafa-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.png`,
+  );
+  await writeFile(file, buffer);
+  try {
+    return await fn(file);
+  } finally {
+    unlink(file).catch(() => {});
+  }
+}
+
+// Cell-based symbol output (truecolor ANSI). Compatible with Ink's <Text>
+// layout, so the reader can scroll it like the half-block output. We size the
+// box to the image's natural aspect to avoid chafa padding the result.
+export async function renderChafaSymbols(buffer, { cols = 80 } = {}) {
+  const meta = await sharp(buffer).metadata();
+  const aspect = (meta.height || 1) / (meta.width || 1);
+  const rows = Math.max(1, Math.round((aspect * cols) / 2)); // cells are ~2x tall
+
+  const stdout = await withTempImage(buffer, (file) =>
+    execFileAsync(
+      'chafa',
+      ['--format', 'symbols', '--colors', 'full', '--size', `${cols}x${rows}`, file],
+      { maxBuffer: 96 * 1024 * 1024 },
+    ).then((r) => r.stdout),
+  );
+
+  const lines = stdout.replace(/\n+$/, '').split('\n');
+  return { lines, cols, rows: lines.length };
+}
+
+// Fullscreen one-shot: print straight to the inherited TTY so chafa can probe
+// the real terminal and auto-select kitty > sixel > symbols. Used by the
+// reader's "high-fidelity" toggle. Returns false if chafa is unavailable.
+export function spawnChafaToTerminal(file, { cols, rows } = {}) {
+  if (!detectCapabilities().chafa) return false;
+  const args = ['--colors', 'full'];
+  if (cols && rows) args.push('--size', `${cols}x${rows}`);
+  args.push(file);
+  const res = spawnSync('chafa', args, { stdio: ['ignore', 'inherit', 'inherit'] });
+  return res.status === 0;
+}
+
+export { withTempImage };

package/src/render/detect.js

@@ -0,0 +1,112 @@
+import { execFileSync } from 'node:child_process';
+
+let cached = null;
+
+// Detect terminal/image capabilities once. Conservative: we never assume a
+// pixel protocol unless there's a strong signal, because the universal
+// half-block path always works.
+export function detectCapabilities() {
+  if (cached) return cached;
+  const env = process.env;
+  const term = env.TERM || '';
+  const termProgram = env.TERM_PROGRAM || '';
+
+  const kitty =
+    !!env.KITTY_WINDOW_ID ||
+    term.includes('kitty') ||
+    termProgram === 'ghostty' ||
+    termProgram === 'WezTerm';
+
+  // Sixel is hard to probe without a terminal round-trip; trust an explicit hint
+  // or a couple of known sixel-first terminals.
+  const sixel =
+    /sixel/i.test(env.KOMADO_CAPS || '') ||
+    term === 'foot' || term.includes('foot') || term.includes('mlterm');
+
+  // We always emit 24-bit colour; non-truecolor terminals degrade gracefully.
+  const truecolor = env.COLORTERM === 'truecolor' || env.COLORTERM === '24bit';
+
+  let chafa = false;
+  let chafaVersion = null;
+  try {
+    const out = execFileSync('chafa', ['--version'], {
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).toString();
+    chafa = true;
+    chafaVersion = (out.match(/version\s+([\d.]+)/i) || [])[1] || 'unknown';
+  } catch {
+    /* chafa not on PATH — half-block fallback */
+  }
+
+  cached = { term, termProgram, kitty, sixel, truecolor, chafa, chafaVersion };
+  return cached;
+}
+
+// Inline (scrollable) reader backend. Both options produce an array of terminal
+// lines, so the reader can slice a vertical window for panning.
+export function pickInlineBackend(config, caps = detectCapabilities()) {
+  const pref = config?.renderer || 'auto';
+  if (pref === 'halfblock') return 'halfblock';
+  if (pref === 'chafa') return caps.chafa ? 'chafa-symbols' : 'halfblock';
+  // auto: chafa's symbol output is sharper than raw half-blocks when available.
+  return caps.chafa ? 'chafa-symbols' : 'halfblock';
+}
+
+// Cycle order for the in-reader "switch renderer" key.
+export const RENDERER_CYCLE = ['auto', 'halfblock', 'chafa'];
+
+// Actively ask the terminal what it supports by emitting a kitty-graphics
+// support query (APC G) + primary Device Attributes (DA1), then reading the
+// replies. DA1 returns ";4" when sixel is supported; a kitty ";OK" reply means
+// the kitty graphics protocol is available. Needs a real TTY on both ends.
+export async function probeTerminal({ timeoutMs = 350 } = {}) {
+  const { stdin, stdout } = process;
+  if (!stdout.isTTY || !stdin.isTTY) {
+    return { queried: false, sixel: false, kitty: false, cellW: null, cellH: null };
+  }
+
+  return new Promise((resolve) => {
+    let buf = '';
+    const prevRaw = stdin.isRaw;
+    const onData = (d) => { buf += d.toString('latin1'); };
+
+    try { stdin.setRawMode(true); } catch { /* ignore */ }
+    stdin.resume();
+    stdin.on('data', onData);
+    // kitty support · cell size (16t) · text-area px (14t) · text-area chars
+    // (18t) · primary DA. Replies are collected together over the timeout.
+    stdout.write('\x1b_Gi=31,s=1,v=1,a=q,t=d,f=24;AAAA\x1b\\\x1b[16t\x1b[14t\x1b[18t\x1b[c');
+
+    setTimeout(() => {
+      stdin.removeListener('data', onData);
+      try { stdin.setRawMode(prevRaw); } catch { /* ignore */ }
+      stdin.pause();
+      /* eslint-disable no-control-regex */ // matching raw terminal escape replies
+      const kitty = /\x1b_G[^\x1b]*;OK/.test(buf);
+      const da = buf.match(/\x1b\[\?([0-9;]+)c/);
+      const cell = buf.match(/\x1b\[6;(\d+);(\d+)t/);   // CSI 6 ; cellH ; cellW t
+      const areaPx = buf.match(/\x1b\[4;(\d+);(\d+)t/); // CSI 4 ; areaH ; areaW t (px)
+      const areaCh = buf.match(/\x1b\[8;(\d+);(\d+)t/); // CSI 8 ; rows ; cols t
+      /* eslint-enable no-control-regex */
+
+      const sixel = da ? da[1].split(';').includes('4') : false;
+      let cellW = null;
+      let cellH = null;
+      if (cell) {
+        cellH = Number(cell[1]);
+        cellW = Number(cell[2]);
+      } else if (areaPx && areaCh) {
+        const cols = Number(areaCh[2]);
+        const rows = Number(areaCh[1]);
+        if (cols > 0 && rows > 0) {
+          cellW = Number(areaPx[2]) / cols;
+          cellH = Number(areaPx[1]) / rows;
+        }
+      }
+      if (!(cellW > 2 && cellW < 64)) cellW = null; // ignore absurd values
+      if (!(cellH > 2 && cellH < 96)) cellH = null;
+
+      resolve({ queried: true, sixel, kitty, cellW, cellH });
+    }, timeoutMs);
+  });
+}

package/src/render/halfblock.js

@@ -0,0 +1,46 @@
+import sharp from 'sharp';
+
+const ESC = '\x1b';
+const RESET = `${ESC}[0m`;
+
+// Render an image buffer to terminal lines using the upper-half-block glyph (▀):
+// the glyph's foreground paints the TOP half of the cell, the background the
+// BOTTOM half — so each character encodes two vertical pixels at 24-bit colour.
+// One column == one pixel wide, one row == two pixels tall.
+export async function renderHalfBlock(buffer, { cols = 80 } = {}) {
+  const targetWidth = Math.max(1, Math.min(Math.floor(cols), 400));
+
+  const { data, info } = await sharp(buffer)
+    .resize({ width: targetWidth, fit: 'inside', withoutEnlargement: false })
+    .flatten({ background: '#ffffff' }) // composite any transparency onto white
+    .raw()
+    .toBuffer({ resolveWithObject: true });
+
+  const { width, height, channels } = info;
+
+  const px = (x, y) => {
+    const i = (y * width + x) * channels;
+    if (channels === 1) { const v = data[i]; return [v, v, v]; }
+    return [data[i], data[i + 1], data[i + 2]];
+  };
+
+  const lines = [];
+  for (let y = 0; y < height; y += 2) {
+    let line = '';
+    let lastFg = null;
+    let lastBg = null;
+    for (let x = 0; x < width; x++) {
+      const [tr, tg, tb] = px(x, y);
+      const [br, bg, bb] = y + 1 < height ? px(x, y + 1) : [tr, tg, tb];
+      const fg = `${tr};${tg};${tb}`;
+      const bgc = `${br};${bg};${bb}`;
+      // Emit colour codes only when they change — keeps lines compact.
+      if (fg !== lastFg) { line += `${ESC}[38;2;${fg}m`; lastFg = fg; }
+      if (bgc !== lastBg) { line += `${ESC}[48;2;${bgc}m`; lastBg = bgc; }
+      line += '▀';
+    }
+    lines.push(line + RESET);
+  }
+
+  return { lines, cols: width, rows: lines.length };
+}

package/src/render/image.js

@@ -0,0 +1,24 @@
+import sharp from 'sharp';
+import { renderHalfBlock } from './halfblock.js';
+import { renderChafaSymbols } from './chafa.js';
+import { logger } from '../lib/logger.js';
+
+export async function imageSize(buffer) {
+  const { width = 1, height = 1 } = await sharp(buffer).metadata();
+  return { width, height };
+}
+
+// Dispatch a buffer to the chosen inline backend, producing { lines, cols, rows }.
+// Always falls back to half-block so a chafa hiccup never blanks the reader —
+// the same "graceful degradation" idea as your SSR→static fallback.
+export async function renderInline(buffer, { cols = 80, backend = 'halfblock' } = {}) {
+  if (backend === 'chafa-symbols') {
+    try {
+      return await renderChafaSymbols(buffer, { cols });
+    } catch (err) {
+      logger.warn('chafa render failed, falling back to half-block', err);
+      return renderHalfBlock(buffer, { cols });
+    }
+  }
+  return renderHalfBlock(buffer, { cols });
+}