komado 0.1.0

package/src/components/screens/MangaScreen.js

@@ -0,0 +1,125 @@
+import { useState, useEffect } from 'react';
+import { Box, Text, useInput } from 'ink';
+import { useUI } from '../../ui-context.js';
+import { getSource } from '../../sources/index.js';
+import { getProgress } from '../../state/store.js';
+import { isLoggedIn } from '../../sources/mangadex/auth.js';
+import { chapterLabel } from '../../domain/shape.js';
+import { List } from '../List.js';
+import { Header, Spinner, ErrorView, KeyHints } from '../ui.js';
+import { truncate } from '../../lib/text.js';
+
+export function MangaScreen({ params }) {
+  const { sourceId, manga: initial } = params;
+  const ui = useUI();
+  const source = getSource(sourceId);
+
+  const [manga, setManga] = useState(initial);
+  const [chapters, setChapters] = useState([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+  const [readSet, setReadSet] = useState(null); // chapter ids read on MangaDex
+  const progress = getProgress(initial.key);
+
+  useEffect(() => {
+    let cancelled = false;
+    const ctrl = new AbortController();
+    setLoading(true);
+    setError(null);
+    (async () => {
+      try {
+        const [full, chRes] = await Promise.all([
+          source.getManga(initial.id, { signal: ctrl.signal }).catch(() => initial),
+          source.listChapters(initial.id, { signal: ctrl.signal, limit: 500 }),
+        ]);
+        if (cancelled) return;
+        setManga(full);
+        setChapters(chRes.data);
+        // Decorate the list with MangaDex read-markers (logged-in only).
+        if (isLoggedIn() && source.getReadMarkers) {
+          source.getReadMarkers(initial.id, { signal: ctrl.signal })
+            .then((ids) => { if (!cancelled) setReadSet(new Set(ids)); })
+            .catch(() => {}); // decorative — never block the screen on this
+        }
+      } catch (err) {
+        if (!cancelled) setError(err);
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    })();
+    return () => {
+      cancelled = true;
+      ctrl.abort();
+    };
+  }, [initial.key]);
+
+  const openAt = (index, startPage = 0) =>
+    ui.openReader({ sourceId, manga, chapters, chapterIndex: index, startPage });
+
+  const resume = () => {
+    if (!progress) return;
+    const idx = chapters.findIndex((c) => c.id === progress.chapterId);
+    if (idx >= 0) openAt(idx, progress.page || 0);
+  };
+
+  useInput((input) => {
+    if (input === 'r' && progress && chapters.length) resume();
+  });
+
+  const cols = ui.dimensions.cols || 80;
+  const resumeChapterId = progress?.chapterId;
+
+  return (
+    <Box flexDirection="column">
+      <Header
+        title={truncate(manga.title, cols - 4)}
+        subtitle={[manga.authors?.join(', '), manga.status].filter(Boolean).join(' · ')}
+      />
+      {manga.tags?.length ? (
+        <Text color="blue">{truncate(manga.tags.join(' · '), cols - 4)}</Text>
+      ) : null}
+      {manga.description ? (
+        <Box marginTop={1} width={cols - 4}>
+          <Text dimColor wrap="truncate-end">
+            {truncate(manga.description.replace(/\s+/g, ' '), (cols - 4) * 3)}
+          </Text>
+        </Box>
+      ) : null}
+      {progress ? (
+        <Box marginTop={1}>
+          <Text color="green">{`▶ Resume Ch.${progress.chapterNumber ?? '?'} p.${(progress.page || 0) + 1}  (press r)`}</Text>
+        </Box>
+      ) : null}
+
+      <Box marginTop={1} flexDirection="column">
+        <Text bold>{`Chapters ${chapters.length ? `(${chapters.length})` : ''}`}</Text>
+        {loading ? <Spinner label="Loading chapters" /> : null}
+        {error ? <ErrorView error={error} /> : null}
+        {!loading && !error ? (
+          <List
+            items={chapters}
+            height={Math.max(4, (ui.dimensions.rows || 24) - 12)}
+            onSelect={(_c, index) => openAt(index)}
+            emptyText="No chapters available in this language (try changing language in Settings)."
+            renderItem={(ch, active) => {
+              const isResume = ch.id === resumeChapterId;
+              const read = readSet?.has(ch.id);
+              return (
+                <Box key={ch.id}>
+                  <Text
+                    inverse={active}
+                    color={active ? 'cyanBright' : isResume ? 'green' : undefined}
+                    dimColor={!active && read && !isResume}
+                  >
+                    {` ${isResume ? '▶ ' : read ? '✓ ' : '  '}${truncate(chapterLabel(ch), cols - 8)} `}
+                  </Text>
+                </Box>
+              );
+            }}
+          />
+        ) : null}
+      </Box>
+      <KeyHints hints={[['↑↓', 'move'], ['enter', 'read'], ...(progress ? [['r', 'resume']] : []), ['esc', 'back']]} />
+    </Box>
+  );
+}

package/src/components/screens/ReaderScreen.js

@@ -0,0 +1,230 @@
+import { useState, useEffect, useRef, useMemo } from 'react';
+import { Box, Text, useInput } from 'ink';
+import { useUI } from '../../ui-context.js';
+import { getSource } from '../../sources/index.js';
+import { setProgress, getConfig } from '../../state/store.js';
+import { chapterLabel } from '../../domain/shape.js';
+import { renderInline, imageSize } from '../../render/image.js';
+import { pickInlineBackend, RENDERER_CYCLE } from '../../render/detect.js';
+import { Spinner, ErrorView, KeyHints } from '../ui.js';
+import { truncate } from '../../lib/text.js';
+
+export function ReaderScreen({ params }) {
+  const { sourceId, manga, chapters, chapterIndex: startChapter, startPage = 0 } = params;
+  const ui = useUI();
+  const source = getSource(sourceId);
+  const { cols, rows } = ui.dimensions;
+
+  const [chapterIndex, setChapterIndex] = useState(startChapter);
+  const [pages, setPages] = useState(null);
+  const [pageIndex, setPageIndex] = useState(startPage);
+  const [scroll, setScroll] = useState(0);
+  const [rendered, setRendered] = useState(null);   // { lines, cols, rows }
+  const [status, setStatus] = useState('loading');  // loading | ready | error
+  const [error, setError] = useState(null);
+  const [fitMode, setFitMode] = useState(false);
+  const [rendererPref, setRendererPref] = useState(getConfig().renderer || 'auto');
+
+  const chapter = chapters[chapterIndex];
+  const viewportRows = Math.max(3, rows - 3); // status line + help line + margin
+  const renderCache = useRef(new Map());
+  const backend = useMemo(() => pickInlineBackend({ renderer: rendererPref }), [rendererPref]);
+
+  // --- Load page descriptors when the chapter changes ---
+  useEffect(() => {
+    let cancelled = false;
+    const ctrl = new AbortController();
+    setStatus('loading');
+    setPages(null);
+    setError(null);
+    (async () => {
+      try {
+        const pgs = await source.getPages(chapter.id, { signal: ctrl.signal });
+        if (cancelled) return;
+        setPages(pgs);
+        setPageIndex((p) => Math.max(0, Math.min(p, pgs.length - 1)));
+      } catch (err) {
+        if (!cancelled) {
+          setError(err);
+          setStatus('error');
+        }
+      }
+    })();
+    return () => {
+      cancelled = true;
+      ctrl.abort();
+    };
+  }, [chapter?.id]);
+
+  const cacheKeyFor = (idx) =>
+    `${chapter?.id}:${idx}:${cols}:${viewportRows}:${backend}:${fitMode ? 'fit' : 'scroll'}`;
+
+  // Load + render one page into the cache, returning its lines.
+  const renderPage = async (idx, signal) => {
+    const key = cacheKeyFor(idx);
+    if (renderCache.current.has(key)) return renderCache.current.get(key);
+    const buf = await source.loadPageBuffer(pages[idx], { signal });
+    let renderCols = cols;
+    if (fitMode) {
+      const { width, height } = await imageSize(buf);
+      // Pick a width so the whole page fits within the viewport height.
+      renderCols = Math.max(8, Math.min(cols, Math.floor(viewportRows * 2 * (width / height))));
+    }
+    const out = await renderInline(buf, { cols: renderCols, backend });
+    renderCache.current.set(key, out);
+    return out;
+  };
+
+  // Background prefetch (own controller — survives page turns, aborts on unmount).
+  const prefetchers = useRef(new Set());
+  useEffect(() => () => {
+    for (const c of prefetchers.current) c.abort();
+    prefetchers.current.clear();
+  }, []);
+  const prefetch = (idx) => {
+    if (!pages?.[idx] || renderCache.current.has(cacheKeyFor(idx))) return;
+    const c = new AbortController();
+    prefetchers.current.add(c);
+    renderPage(idx, c.signal).catch(() => {}).finally(() => prefetchers.current.delete(c));
+  };
+
+  // --- Render current page (no spinner flicker on cache hits) + prefetch next ---
+  useEffect(() => {
+    if (!pages || !pages[pageIndex]) return;
+    let cancelled = false;
+    const ctrl = new AbortController();
+
+    if (renderCache.current.has(cacheKeyFor(pageIndex))) {
+      setRendered(renderCache.current.get(cacheKeyFor(pageIndex)));
+      setScroll(0);
+      setStatus('ready');
+    } else {
+      setStatus('loading');
+      renderPage(pageIndex, ctrl.signal)
+        .then((out) => {
+          if (cancelled) return;
+          setRendered(out);
+          setScroll(0);
+          setStatus('ready');
+        })
+        .catch((err) => {
+          if (!cancelled && !ctrl.signal.aborted) {
+            setError(err);
+            setStatus('error');
+          }
+        });
+    }
+    prefetch(pageIndex + 1);
+
+    return () => {
+      cancelled = true;
+      ctrl.abort();
+    };
+  }, [pages, pageIndex, cols, viewportRows, backend, fitMode]);
+
+  // --- Persist reading progress on every settled page ---
+  useEffect(() => {
+    if (status !== 'ready' || !pages) return;
+    setProgress(manga.key, {
+      source: sourceId,
+      mangaId: manga.id,
+      mangaTitle: manga.title,
+      chapterId: chapter.id,
+      chapterNumber: chapter.number,
+      page: pageIndex,
+    });
+    // Reaching the last page = finished the chapter → push a read-marker to
+    // MangaDex. Self-guarded (login + setting) and deduped inside the source.
+    if (pageIndex === pages.length - 1 && source.syncChapterRead) {
+      source.syncChapterRead(manga.id, chapter.id);
+    }
+  }, [pageIndex, chapter?.id, status]);
+
+  // --- Navigation helpers ---
+  const lines = rendered?.lines || [];
+  const maxScroll = Math.max(0, lines.length - viewportRows);
+
+  const changeChapter = (delta) => {
+    const next = chapterIndex + delta;
+    if (next < 0 || next >= chapters.length) return;
+    setChapterIndex(next);
+    setPageIndex(0);
+    setScroll(0);
+  };
+  const nextPage = () => {
+    if (pages && pageIndex < pages.length - 1) {
+      setPageIndex(pageIndex + 1);
+      setScroll(0);
+    } else {
+      changeChapter(1);
+    }
+  };
+  const prevPage = () => {
+    if (pageIndex > 0) {
+      setPageIndex(pageIndex - 1);
+      setScroll(0);
+    } else {
+      changeChapter(-1);
+    }
+  };
+  const cycleRenderer = () => {
+    const i = RENDERER_CYCLE.indexOf(rendererPref);
+    setRendererPref(RENDERER_CYCLE[(i + 1) % RENDERER_CYCLE.length]);
+  };
+
+  useInput((input, key) => {
+    if (key.downArrow || input === 'j') setScroll((s) => Math.min(maxScroll, s + 1));
+    else if (key.upArrow || input === 'k') setScroll((s) => Math.max(0, s - 1));
+    else if (input === ' ' || key.pageDown) {
+      if (scroll >= maxScroll) nextPage();
+      else setScroll((s) => Math.min(maxScroll, s + viewportRows - 1));
+    } else if (key.pageUp) setScroll((s) => Math.max(0, s - (viewportRows - 1)));
+    else if (key.rightArrow || input === 'l' || input === 'n') nextPage();
+    else if (key.leftArrow || input === 'h' || input === 'p') prevPage();
+    else if (input === 'g') setScroll(0);
+    else if (input === 'G') setScroll(maxScroll);
+    else if (input === 'N') changeChapter(1);
+    else if (input === 'P') changeChapter(-1);
+    else if (input === 'f') setFitMode((f) => !f);
+    else if (input === 'r') cycleRenderer();
+  });
+
+  // --- Render ---
+  const pageLabel = pages ? `${pageIndex + 1}/${pages.length}` : '…';
+  const slice = lines.slice(scroll, scroll + viewportRows);
+
+  return (
+    <Box flexDirection="column">
+      <Box justifyContent="space-between">
+        <Text color="magentaBright" bold>{truncate(manga.title, Math.max(10, cols - 34))}</Text>
+        <Text>{`${truncate(chapterLabel(chapter), 24)} · ${pageLabel}${fitMode ? ' · fit' : ''}`}</Text>
+      </Box>
+
+      <Box height={viewportRows} flexDirection="column">
+        {status === 'loading' ? (
+          <Spinner label={pages ? `Rendering page ${pageIndex + 1}` : 'Loading chapter'} />
+        ) : status === 'error' ? (
+          <Box flexDirection="column">
+            <ErrorView error={error} />
+            <Text dimColor>Press N / P to skip to another chapter, or Esc to go back.</Text>
+          </Box>
+        ) : (
+          slice.map((ln, i) => (
+            <Text key={scroll + i} wrap="truncate-end">{ln}</Text>
+          ))
+        )}
+      </Box>
+
+      <KeyHints
+        hints={[
+          ['←→', 'page'],
+          ['↑↓', 'scroll'],
+          ['N/P', 'chapter'],
+          ['f', fitMode ? 'scroll' : 'fit'],
+          ['r', `render:${rendererPref}`],
+          ['esc', 'back'],
+        ]}
+      />
+    </Box>
+  );
+}

package/src/components/screens/SearchScreen.js

@@ -0,0 +1,123 @@
+import { useState, useEffect, useRef } from 'react';
+import { Box, Text, useInput } from 'ink';
+import TextInput from 'ink-text-input';
+import { useUI } from '../../ui-context.js';
+import { getSource } from '../../sources/index.js';
+import { List } from '../List.js';
+import { Header, Spinner, ErrorView, KeyHints } from '../ui.js';
+import { truncate } from '../../lib/text.js';
+
+const PAGE = 20;
+
+export function SearchScreen({ params }) {
+  const { sourceId, mode } = params;
+  const ui = useUI();
+  const source = getSource(sourceId);
+
+  const [query, setQuery] = useState('');
+  const [submitted, setSubmitted] = useState(mode === 'browse' ? '' : null); // null = not searched yet
+  const [results, setResults] = useState([]);
+  const [pagination, setPagination] = useState(null);
+  const [loading, setLoading] = useState(mode === 'browse');
+  const [error, setError] = useState(null);
+  const [focusInput, setFocusInput] = useState(mode !== 'browse');
+
+  // Raise the typing flag while the input is focused so global keys don't fire.
+  useEffect(() => {
+    ui.setTyping(focusInput);
+    return () => ui.setTyping(false);
+  }, [focusInput]);
+
+  // Monotonic request id guards against out-of-order responses (cancelled-flag).
+  const reqId = useRef(0);
+  const fetchPage = async (q, offset, append) => {
+    const id = ++reqId.current;
+    const ctrl = new AbortController();
+    setLoading(true);
+    setError(null);
+    try {
+      const res = await source.search(q, { offset, limit: PAGE, signal: ctrl.signal });
+      if (id !== reqId.current) return; // a newer request superseded this one
+      setResults((prev) => (append ? [...prev, ...res.data] : res.data));
+      setPagination(res.pagination);
+    } catch (err) {
+      if (id === reqId.current) setError(err);
+    } finally {
+      if (id === reqId.current) setLoading(false);
+    }
+  };
+
+  useEffect(() => {
+    if (mode === 'browse') fetchPage('', 0, false);
+  }, []);
+
+  const onSubmit = () => {
+    setSubmitted(query);
+    setFocusInput(false);
+    fetchPage(query, 0, false);
+  };
+
+  const loadMore = () => {
+    if (loading || !pagination?.hasMore) return;
+    fetchPage(submitted ?? '', pagination.offset + pagination.limit, true);
+  };
+
+  const onHighlight = (_item, index) => {
+    if (index >= results.length - 2) loadMore(); // prefetch near the end
+  };
+
+  // `/` refocuses the search box; Esc blurs it (handled here only while typing,
+  // so it doesn't collide with the app-level Esc=back).
+  useInput((input, key) => {
+    if (!focusInput && input === '/') setFocusInput(true);
+    else if (focusInput && key.escape) setFocusInput(false);
+  });
+
+  const listHeight = Math.max(4, (ui.dimensions.rows || 24) - 9);
+
+  return (
+    <Box flexDirection="column">
+      <Header
+        title={source.label}
+        subtitle={sourceId === 'local' ? 'filter your local library' : 'search the online catalog'}
+      />
+      <Box>
+        <Text color={focusInput ? 'cyanBright' : 'gray'}>{focusInput ? '› ' : '  '}</Text>
+        <TextInput
+          value={query}
+          onChange={setQuery}
+          onSubmit={onSubmit}
+          focus={focusInput}
+          placeholder={sourceId === 'local' ? 'type to filter…' : 'type a title, enter to search…'}
+        />
+      </Box>
+      {loading ? <Box marginTop={1}><Spinner label="Loading" /></Box> : null}
+      {error ? <Box marginTop={1}><ErrorView error={error} /></Box> : null}
+      {!error && submitted !== null ? (
+        <Box flexDirection="column" marginTop={1}>
+          <List
+            items={results}
+            isActive={!focusInput}
+            height={listHeight}
+            onSelect={(m) => ui.navigate('manga', { sourceId, manga: m })}
+            onHighlight={onHighlight}
+            emptyText={loading ? ' ' : submitted === '' ? 'Nothing found.' : `No results for "${submitted}".`}
+            renderItem={(m, active) => (
+              <Box key={m.key}>
+                <Text inverse={active} color={active ? 'cyanBright' : undefined}>
+                  {` ${truncate(m.title, Math.max(20, (ui.dimensions.cols || 80) - 24))} `}
+                </Text>
+                <Text dimColor>{`  ${m.source === 'local' ? `${m.chaptersCount ?? '?'} ch` : m.status || ''}`}</Text>
+              </Box>
+            )}
+          />
+        </Box>
+      ) : null}
+      <KeyHints
+        hints={focusInput
+          ? [['enter', 'search'], ['esc', 'to results']]
+          : [['↑↓', 'move'], ['enter', 'open'], ['/', 'search'], ['esc', 'back']]}
+      />
+    </Box>
+  );
+}

package/src/components/screens/SettingsScreen.js

@@ -0,0 +1,146 @@
+import { useState, useEffect } from 'react';
+import { Box, Text, useInput } from 'ink';
+import TextInput from 'ink-text-input';
+import { useUI } from '../../ui-context.js';
+import { getConfig, setConfig } from '../../state/store.js';
+import { scan } from '../../sources/local/index.js';
+import { isLoggedIn, logout } from '../../sources/mangadex/auth.js';
+import { detectCapabilities } from '../../render/detect.js';
+import { List } from '../List.js';
+import { Header, KeyHints } from '../ui.js';
+import { truncate } from '../../lib/text.js';
+
+const RENDERERS = ['auto', 'halfblock', 'chafa'];
+const RATING_PRESETS = [
+  ['safe'],
+  ['safe', 'suggestive'],
+  ['safe', 'suggestive', 'erotica'],
+  ['safe', 'suggestive', 'erotica', 'pornographic'],
+];
+const ratingLabel = (arr) => arr.join('+');
+const cycle = (list, current) => list[(list.indexOf(current) + 1) % list.length];
+
+export function SettingsScreen() {
+  const ui = useUI();
+  const caps = detectCapabilities();
+  const [cfg, setCfg] = useState(getConfig());
+  const [editing, setEditing] = useState(null); // null | 'language' | 'addPath'
+  const [draft, setDraft] = useState('');
+  const [highlighted, setHighlighted] = useState(null);
+  const [, setTick] = useState(0); // force a re-render after login/logout
+
+  const loggedIn = isLoggedIn();
+
+  useEffect(() => {
+    ui.setTyping(!!editing);
+    return () => ui.setTyping(false);
+  }, [editing]);
+
+  const save = (patch) => setCfg({ ...setConfig(patch) });
+
+  const items = [
+    { id: 'account', kind: 'account', label: loggedIn ? 'MangaDex account' : 'Log in to MangaDex…',
+      value: loggedIn ? 'logged in · enter to log out' : 'enter to log in' },
+    ...(loggedIn ? [{ id: 'syncProgress', kind: 'toggle', label: 'Sync reading progress (MangaDex)', value: cfg.syncProgress ? 'on' : 'off' }] : []),
+    { id: 'renderer', kind: 'cycle', label: 'Renderer', value: cfg.renderer + (caps.chafa ? '' : ' (chafa N/A)') },
+    { id: 'dataSaver', kind: 'toggle', label: 'Data saver (smaller images)', value: cfg.dataSaver ? 'on' : 'off' },
+    { id: 'rating', kind: 'cycle', label: 'Content rating', value: ratingLabel(cfg.contentRating) },
+    { id: 'language', kind: 'edit', label: 'Language (MangaDex)', value: cfg.language },
+    { id: 'addPath', kind: 'action', label: 'Add library path…', value: '' },
+    ...cfg.localLibraryPaths.map((p, i) => ({
+      id: `path:${i}`, kind: 'path', pathIndex: i, label: `Library: ${truncate(p, 48)}`, value: 'd to remove',
+    })),
+  ];
+
+  const activate = (item) => {
+    switch (item.kind) {
+      case 'account':
+        if (loggedIn) { logout(); return setTick((t) => t + 1); }
+        return ui.navigate('login');
+      case 'toggle':
+        if (item.id === 'syncProgress') return save({ syncProgress: !cfg.syncProgress });
+        return save({ dataSaver: !cfg.dataSaver });
+      case 'cycle':
+        if (item.id === 'renderer') return save({ renderer: cycle(RENDERERS, cfg.renderer) });
+        if (item.id === 'rating') {
+          const idx = RATING_PRESETS.findIndex((p) => ratingLabel(p) === ratingLabel(cfg.contentRating));
+          return save({ contentRating: RATING_PRESETS[(idx + 1) % RATING_PRESETS.length] });
+        }
+        return undefined;
+      case 'edit':
+        setDraft(cfg.language);
+        return setEditing('language');
+      case 'action':
+        setDraft('');
+        return setEditing('addPath');
+      default:
+        return undefined;
+    }
+  };
+
+  const submitEdit = () => {
+    if (editing === 'language') {
+      save({ language: draft.trim() || 'en' });
+    } else if (editing === 'addPath' && draft.trim()) {
+      save({ localLibraryPaths: [...cfg.localLibraryPaths, draft.trim()] });
+      scan();
+    }
+    setEditing(null);
+    setDraft('');
+  };
+
+  useInput((input, key) => {
+    if (editing) {
+      if (key.escape) {
+        setEditing(null);
+        setDraft('');
+      }
+      return;
+    }
+    if (input === 'd' && highlighted?.kind === 'path') {
+      save({ localLibraryPaths: cfg.localLibraryPaths.filter((_, i) => i !== highlighted.pathIndex) });
+      scan();
+    }
+  });
+
+  return (
+    <Box flexDirection="column">
+      <Header
+        title="Settings"
+        subtitle={`chafa: ${caps.chafa ? caps.chafaVersion : 'not installed'} · backend: ${caps.chafa ? 'chafa-symbols' : 'half-block'}`}
+      />
+
+      {editing ? (
+        <Box flexDirection="column">
+          <Text color="cyanBright">
+            {editing === 'addPath' ? 'New library path (folder of manga / CBZ):' : 'Language code (e.g. en, fr, ja):'}
+          </Text>
+          <Box>
+            <Text color="cyanBright">{'› '}</Text>
+            <TextInput value={draft} onChange={setDraft} onSubmit={submitEdit} focus={true} />
+          </Box>
+          <KeyHints hints={[['enter', 'save'], ['esc', 'cancel']]} />
+        </Box>
+      ) : (
+        <Box flexDirection="column">
+          <List
+            items={items}
+            isActive={true}
+            height={Math.max(6, (ui.dimensions.rows || 24) - 7)}
+            onSelect={activate}
+            onHighlight={(it) => setHighlighted(it)}
+            renderItem={(it, active) => (
+              <Box key={it.id} justifyContent="space-between">
+                <Text inverse={active} color={active ? 'cyanBright' : it.kind === 'path' ? 'blue' : undefined}>
+                  {` ${it.label} `}
+                </Text>
+                {it.value ? <Text dimColor>{it.value}</Text> : null}
+              </Box>
+            )}
+          />
+          <KeyHints hints={[['↑↓', 'move'], ['enter', 'change'], ['d', 'remove path'], ['esc', 'back']]} />
+        </Box>
+      )}
+    </Box>
+  );
+}

package/src/components/ui.js

@@ -0,0 +1,42 @@
+import { useState, useEffect } from 'react';
+import { Box, Text } from 'ink';
+
+const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+
+// Hand-rolled spinner — dependency-light, matching your preference for not
+// pulling a package for something this small.
+export function Spinner({ label = 'Loading' }) {
+  const [frame, setFrame] = useState(0);
+  useEffect(() => {
+    const t = setInterval(() => setFrame((f) => (f + 1) % FRAMES.length), 80);
+    return () => clearInterval(t);
+  }, []);
+  return <Text color="cyan">{`${FRAMES[frame]} ${label}…`}</Text>;
+}
+
+export function Header({ title, subtitle }) {
+  return (
+    <Box flexDirection="column" marginBottom={1}>
+      <Text color="magentaBright" bold>{title}</Text>
+      {subtitle ? <Text dimColor>{subtitle}</Text> : null}
+    </Box>
+  );
+}
+
+export function ErrorView({ error }) {
+  return (
+    <Box flexDirection="column">
+      <Text color="red" bold>{`✖ ${error?.message || 'Something went wrong'}`}</Text>
+      {error?.statusCode ? <Text dimColor>{`status ${error.statusCode}`}</Text> : null}
+    </Box>
+  );
+}
+
+// Footer key legend. `hints` is an array of [key, label] pairs.
+export function KeyHints({ hints = [] }) {
+  return (
+    <Box marginTop={1}>
+      <Text dimColor>{hints.map(([k, l]) => `${k} ${l}`).join('   ')}</Text>
+    </Box>
+  );
+}