@thesimonharms/basa 0.1.0 → 0.1.2

package/bin/basa.js

@@ -1,4 +1,65 @@
 #!/usr/bin/env node
+// Basa CLI shim. Boots the Mudah app kernel and points it at this
+// package's own `dist/` for providers and commands, so a published
+// install works from any working directory (not just the project root).
+import { readdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { Application } from '@mudah-cli/core';
 import { run } from '@mudah-cli/mudah';
 
-process.exitCode = await run();
+const here = dirname(fileURLToPath(import.meta.url));
+const pkgDir = dirname(here);
+const pkg = JSON.parse(readFileSync(join(pkgDir, 'package.json'), 'utf8'));
+
+// Application discovery defaults to <basePath>/src/{commands,providers}.
+// The published package ships compiled output under dist/, so we pre-load
+// the built providers and command modules from there and inject them via
+// run({providers, commands}). This is the supported escape hatch for
+// packages that don't follow the scaffolded-app layout.
+const distDir = join(pkgDir, 'dist');
+const commandModules = await loadModules(join(distDir, 'commands'));
+const providerModules = await loadModules(join(distDir, 'providers'));
+
+const manifest = {
+  name: pkg.name,
+  version: pkg.version,
+  bin: 'basa',
+  ui: { theme: 'auto' },
+};
+
+const app = new Application(pkgDir, manifest);
+for (const mod of providerModules) {
+  const value = mod.default ?? mod;
+  if (typeof value === 'function') app.register(value);
+}
+
+const code = await run({
+  app,
+  cwd: process.cwd(),
+  manifest,
+  argv: process.argv.slice(2),
+  stdout: process.stdout,
+  stderr: process.stderr,
+  stdin: process.stdin,
+  commands: commandModules,
+});
+
+process.exitCode = code;
+
+async function loadModules(dir) {
+  const modules = [];
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return modules;
+  }
+  for (const entry of entries) {
+    if (!entry.isFile() || !/\.(c?js|mjs)$/.test(entry.name)) continue;
+    const file = join(dir, entry.name);
+    const mod = await import(pathToFileURL(file).href);
+    if (mod.default) modules.push(mod);
+  }
+  return modules;
+}

package/dist/commands/list.command.js

@@ -0,0 +1,59 @@
+import { Command } from '@mudah-cli/mudah';
+import { defaultDecksDir, listDecks, loadDeck, loadReviewCards } from '../flashcards/deck.js';
+import { isDue } from '../flashcards/srs.js';
+import { renderTable } from '@mudah-cli/ui';
+export default class ListCommand extends Command {
+    signature = 'list [--all] [--dir=]';
+    description = 'List decks (and per-deck card counts)';
+    async handle() {
+        const flag = this.option('dir');
+        const dir = typeof flag === 'string' && flag.length > 0
+            ? flag
+            : (this.app.config().get('app.decksDir') ?? defaultDecksDir());
+        const paths = await listDecks(dir);
+        if (paths.length === 0) {
+            this.output.muted(`No decks found in ${dir}.`);
+            this.output.hint(`Create one with \`basa new <name>\`, or pass --dir=<path>.`);
+            return 0;
+        }
+        const showAll = this.option('all') === true;
+        const now = Date.now();
+        const rows = [];
+        let totalCards = 0;
+        let totalDue = 0;
+        for (const path of paths) {
+            const deck = await loadDeck(path);
+            const cards = await loadReviewCards(deck, path);
+            const due = cards.filter((c) => isDue(c.state, now)).length;
+            totalCards += cards.length;
+            totalDue += due;
+            const description = (deck.description ?? '').replace(/\s+/g, ' ').trim();
+            rows.push([
+                deck.name,
+                String(cards.length),
+                String(due),
+                truncate(description, 50),
+            ]);
+        }
+        if (showAll) {
+            for (const path of paths)
+                this.output.muted(`• ${path}`);
+            this.output.raw('');
+        }
+        const columns = [
+            { header: 'Deck', align: 'left' },
+            { header: 'Cards', align: 'right' },
+            { header: 'Due', align: 'right' },
+            { header: 'Description', align: 'left' },
+        ];
+        this.output.raw(renderTable(columns, rows, { level: 0, unicode: true }));
+        this.output.raw('');
+        this.output.muted(`${totalDue} of ${totalCards} cards due across ${paths.length} decks.`);
+        return 0;
+    }
+}
+function truncate(text, max) {
+    if (text.length <= max)
+        return text;
+    return `${text.slice(0, max - 1)}…`;
+}

package/dist/commands/new.command.js

@@ -0,0 +1,24 @@
+import { join } from 'node:path';
+import { Command } from '@mudah-cli/mudah';
+import { createDeck, defaultDecksDir, expandHome } from '../flashcards/deck.js';
+export default class NewCommand extends Command {
+    signature = 'new {name} [--format=yaml] [--dir=]';
+    description = 'Create a new empty deck';
+    async handle() {
+        const name = this.arg('name');
+        if (name === undefined)
+            throw new Error('Deck name is required.');
+        const format = this.option('format') ?? 'yaml';
+        const flag = this.option('dir');
+        const baseDir = typeof flag === 'string' && flag.length > 0
+            ? flag
+            : (this.app.config().get('app.decksDir') ?? defaultDecksDir());
+        const dir = expandHome(baseDir);
+        const ext = format === 'json' ? '.json' : '.yml';
+        const file = join(dir, `${name}${ext}`);
+        const path = await createDeck(file, name);
+        this.output.success(`Created ${path}`);
+        this.output.hint(`Edit it, then run \`basa study ${name}\`.`);
+        return 0;
+    }
+}

package/dist/commands/study.command.js

@@ -0,0 +1,78 @@
+import { Command } from '@mudah-cli/mudah';
+import { Program } from '@mudah-cli/tui';
+import { loadDeck, loadReviewCards, resolveDeckPath, defaultDecksDir } from '../flashcards/deck.js';
+import { BasaFx } from '../flashcards/sound.js';
+import { StudyApp } from '../tui/StudyApp.js';
+export default class StudyCommand extends Command {
+    signature = 'study {name?} [--no-sound] [--dir=]';
+    description = 'Open a flashcard deck in the terminal';
+    async handle() {
+        const decksDir = this.configDecksDir();
+        const deckPath = await resolveDeckPath(decksDir, this.arg('name'));
+        const deck = await loadDeck(deckPath);
+        const cards = await loadReviewCards(deck, deckPath);
+        const fx = await openFx(this.configSound());
+        let study;
+        let resizeListener;
+        const program = new Program({ mouse: true, keyboard: true, stdin: process.stdin });
+        const width = process.stdout.columns ?? 80;
+        const height = process.stdout.rows ?? 24;
+        study = new StudyApp({
+            deck,
+            deckPath,
+            cards,
+            width,
+            height,
+            fx,
+        });
+        program.mount(study.root);
+        // Repaint loop: Program repaints every 16ms via setInterval, but we
+        // want the StudyApp to also tick (advance animations, swap card).
+        const ticker = setInterval(() => {
+            study?.tick();
+            program.requestFrame();
+        }, 16);
+        // Handle terminal resize. Program's diff renderer adapts automatically
+        // to the new column count, but we need to re-render images and layout.
+        resizeListener = () => {
+            const w = process.stdout.columns ?? width;
+            const h = process.stdout.rows ?? height;
+            study?.resize(w, h);
+            program.requestFrame();
+        };
+        process.stdout.on('resize', resizeListener);
+        try {
+            return await program.run();
+        }
+        finally {
+            clearInterval(ticker);
+            if (resizeListener !== undefined)
+                process.stdout.off('resize', resizeListener);
+            await study?.persist();
+            await fx.dispose();
+        }
+    }
+    configDecksDir() {
+        const flag = this.option('dir');
+        if (typeof flag === 'string' && flag.length > 0)
+            return flag;
+        return this.app.config().get('app.decksDir') ?? defaultDecksDir();
+    }
+    configSound() {
+        const noSound = this.option('no-sound') === true;
+        if (noSound)
+            return 'off';
+        const value = this.app.config().get('app.sound');
+        if (value === 'on' || value === 'off' || value === 'auto')
+            return value;
+        return 'auto';
+    }
+}
+async function openFx(setting) {
+    // BasaFx already handles all three settings via the same open() call:
+    // it probes for an audio backend and falls back to silent if none is
+    // available. The `setting` is reserved for future per-setting behavior
+    // (e.g. a sound-test command, a "play even in CI" override).
+    void setting;
+    return BasaFx.open();
+}

package/dist/flashcards/deck.js

@@ -0,0 +1,207 @@
+import { readFile, writeFile, readdir, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { basename, dirname, extname, isAbsolute, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import yaml from 'js-yaml';
+import { freshState } from './srs.js';
+export class DeckLoadError extends Error {
+    path;
+    constructor(message, path) {
+        super(`${path}: ${message}`);
+        this.path = path;
+    }
+}
+/** Resolve a leading `~` to the user's home directory. */
+export function expandHome(p) {
+    if (p.startsWith('~/'))
+        return join(homedir(), p.slice(2));
+    if (p === '~')
+        return homedir();
+    return p;
+}
+/** The default location for user decks: `~/basa/decks`. */
+export function defaultDecksDir() {
+    return join(homedir(), 'basa', 'decks');
+}
+/** Find every supported deck file in a directory (non-recursive). */
+export async function listDecks(dir) {
+    const path = expandHome(dir);
+    if (!existsSync(path))
+        return [];
+    const entries = await readdir(path, { withFileTypes: true });
+    return entries
+        .filter((e) => e.isFile() && /\.(ya?ml|json)$/i.test(e.name))
+        .map((e) => join(path, e.name))
+        .sort();
+}
+export async function loadDeck(file) {
+    const path = isAbsolute(file) ? file : expandHome(file);
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch (err) {
+        throw new DeckLoadError(`cannot read file: ${err.message}`, path);
+    }
+    let parsed;
+    const ext = extname(path).toLowerCase();
+    try {
+        if (ext === '.json') {
+            parsed = JSON.parse(raw);
+        }
+        else {
+            parsed = yaml.load(raw);
+        }
+    }
+    catch (err) {
+        throw new DeckLoadError(`parse error: ${err.message}`, path);
+    }
+    return validateDeck(parsed, path);
+}
+function validateDeck(value, path) {
+    if (value === null || typeof value !== 'object') {
+        throw new DeckLoadError('deck must be a mapping (name + cards)', path);
+    }
+    const obj = value;
+    if (typeof obj.name !== 'string' || obj.name.length === 0) {
+        throw new DeckLoadError('deck.name must be a non-empty string', path);
+    }
+    if (!Array.isArray(obj.cards)) {
+        throw new DeckLoadError('deck.cards must be an array', path);
+    }
+    const cards = obj.cards.map((c, i) => validateCard(c, path, i));
+    return {
+        name: obj.name,
+        description: typeof obj.description === 'string' ? obj.description : undefined,
+        cards,
+    };
+}
+function validateCard(value, path, index) {
+    if (value === null || typeof value !== 'object') {
+        throw new DeckLoadError(`card #${index + 1} must be a mapping`, path);
+    }
+    const obj = value;
+    if (obj.front === undefined || obj.back === undefined) {
+        throw new DeckLoadError(`card #${index + 1} is missing front or back`, path);
+    }
+    return {
+        front: validateSide(obj.front, `card #${index + 1}.front`, path),
+        back: validateSide(obj.back, `card #${index + 1}.back`, path),
+        tags: Array.isArray(obj.tags) ? obj.tags.filter((t) => typeof t === 'string') : undefined,
+        hint: typeof obj.hint === 'string' ? obj.hint : undefined,
+    };
+}
+function validateSide(value, where, path) {
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value))
+        return value.map((f, i) => validateField(f, `${where}[${i}]`, path));
+    if (value !== null && typeof value === 'object') {
+        return [validateField(value, where, path)];
+    }
+    throw new DeckLoadError(`${where} must be a string, mapping, or list of fields`, path);
+}
+function validateField(value, where, path) {
+    if (value === null || typeof value !== 'object') {
+        throw new DeckLoadError(`${where} must be a mapping`, path);
+    }
+    const field = value;
+    const out = {};
+    if (typeof field.text === 'string')
+        out.text = field.text;
+    if (typeof field.image === 'string')
+        out.image = field.image;
+    if (typeof field.audio === 'string')
+        out.audio = field.audio;
+    if (out.text === undefined && out.image === undefined && out.audio === undefined) {
+        throw new DeckLoadError(`${where} has no text, image, or audio`, path);
+    }
+    return out;
+}
+/** Sibling file where SRS state is persisted, keyed by absolute deck path. */
+function progressPathFor(deckPath) {
+    return `${deckPath}.progress.json`;
+}
+/** Load SRS state for every card, defaulting to a fresh state. */
+export async function loadReviewCards(deck, deckPath) {
+    const path = progressPathFor(deckPath);
+    let saved = {};
+    if (existsSync(path)) {
+        try {
+            const raw = await readFile(path, 'utf8');
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === 'object' && parsed.states)
+                saved = parsed.states;
+        }
+        catch {
+            // Corrupt progress file: ignore and start fresh.
+        }
+    }
+    return deck.cards.map((card, i) => {
+        const key = String(i);
+        const state = saved[key] ?? freshState();
+        return { card, state };
+    });
+}
+/** Persist SRS state for every card. Stable across deck reorders by index. */
+export async function saveReviewCards(deckPath, cards) {
+    const path = progressPathFor(deckPath);
+    const states = {};
+    cards.forEach((c, i) => {
+        states[String(i)] = c.state;
+    });
+    await writeFile(path, JSON.stringify({ version: 1, states }, null, 2) + '\n', 'utf8');
+}
+/** Create an empty deck file at the given path. Auto-creates parent directories. */
+export async function createDeck(file, name) {
+    const path = isAbsolute(file) ? file : expandHome(file);
+    if (existsSync(path)) {
+        throw new DeckLoadError('file already exists', path);
+    }
+    await mkdir(dirname(path), { recursive: true });
+    const stub = {
+        name,
+        description: 'A new Basa deck.',
+        cards: [
+            { front: 'hello', back: 'a greeting' },
+            { front: 'thanks', back: 'an expression of gratitude' },
+        ],
+    };
+    if (path.endsWith('.json')) {
+        await writeFile(path, JSON.stringify(stub, null, 2) + '\n', 'utf8');
+    }
+    else {
+        await writeFile(path, yaml.dump(stub, { lineWidth: 120 }), 'utf8');
+    }
+    return path;
+}
+/** Resolve a deck name or path. With a `dir`, looks for `dir/<name>.{yml,yaml,json}`. */
+export async function resolveDeckPath(dir, nameOrPath) {
+    if (nameOrPath === undefined) {
+        const decks = await listDecks(dir);
+        if (decks.length === 0) {
+            throw new Error(`No decks found in ${expandHome(dir)}. Create one with \`basa new <name>\`.`);
+        }
+        if (decks.length === 1)
+            return decks[0];
+        throw new Error(`Multiple decks in ${expandHome(dir)} — pass a deck name (e.g. \`basa study ${basename(decks[0], extname(decks[0]))}\`).`);
+    }
+    // If it's a path that exists, use it directly.
+    const direct = isAbsolute(nameOrPath) ? nameOrPath : expandHome(nameOrPath);
+    if (existsSync(direct))
+        return direct;
+    // Otherwise try `dir/<name>.{yml,yaml,json}`.
+    const base = join(expandHome(dir), nameOrPath);
+    for (const ext of ['.yml', '.yaml', '.json']) {
+        const candidate = base + ext;
+        if (existsSync(candidate))
+            return candidate;
+    }
+    throw new Error(`Deck not found: ${nameOrPath} (looked in ${expandHome(dir)})`);
+}
+/** A relative `image` or `audio` path is resolved against the deck file's directory. */
+export function resolveMediaPath(deckPath, ref) {
+    if (isAbsolute(ref) || ref.startsWith('~'))
+        return expandHome(ref);
+    return resolve(dirname(deckPath), ref);
+}

package/dist/flashcards/halfblock.js

@@ -0,0 +1,48 @@
+/**
+ * Encode an RGBA pixel buffer as ANSI truecolor half-block cells. Each
+ * terminal cell represents two vertical pixels using `▀` with the top pixel
+ * as the foreground and the bottom as the background. Works in any
+ * truecolor terminal — no Kitty/SIXEL needed.
+ */
+export function halfBlockLines(image) {
+    const { width, height, pixels } = image;
+    const out = [];
+    let row = 0;
+    while (row < height) {
+        let line = '';
+        for (let col = 0; col < width; col++) {
+            const top = pixelAt(pixels, width, height, col, row);
+            const bottom = row + 1 < height ? pixelAt(pixels, width, height, col, row + 1) : top;
+            line += `\x1b[38;2;${top.r};${top.g};${top.b};48;2;${bottom.r};${bottom.g};${bottom.b}m▀`;
+        }
+        line += '\x1b[0m';
+        out.push(line);
+        row += 2;
+    }
+    return out;
+}
+function pixelAt(pixels, width, height, x, y) {
+    if (x < 0 || y < 0 || x >= width || y >= height)
+        return { r: 0, g: 0, b: 0 };
+    const offset = (y * width + x) * 4;
+    return {
+        r: pixels[offset] ?? 0,
+        g: pixels[offset + 1] ?? 0,
+        b: pixels[offset + 2] ?? 0,
+    };
+}
+/** Pick a width and height in pixels that fit a given cell budget. */
+export function fitToCells(sourceWidth, sourceHeight, maxCellsWidth, maxCellsHeight) {
+    if (sourceWidth === 0 || sourceHeight === 0)
+        return { width: 1, height: 1 };
+    const aspect = sourceWidth / sourceHeight;
+    // Half-block makes 1 cell represent 2 vertical pixels → effective aspect per cell is 0.5.
+    const cellAspect = (maxCellsWidth / maxCellsHeight) * 0.5;
+    let cellsH = maxCellsHeight;
+    let cellsW = Math.round(cellsH * aspect / 0.5);
+    if (cellsW > maxCellsWidth) {
+        cellsW = maxCellsWidth;
+        cellsH = Math.round(cellsW * 0.5 / aspect);
+    }
+    return { width: cellsW, height: cellsH * 2 };
+}

package/dist/flashcards/image.js

@@ -0,0 +1,89 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { resolveMediaPath } from './deck.js';
+const IMAGE_EXTS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.svg']);
+/** True if a path looks like a relative/absolute reference to an image file. */
+export function isImagePath(ref) {
+    const lower = ref.toLowerCase();
+    for (const ext of IMAGE_EXTS) {
+        if (lower.endsWith(ext))
+            return true;
+    }
+    return false;
+}
+/**
+ * Decode an image to raw RGBA at a given pixel size, using ImageMagick if
+ * available. The function does NOT throw if the tool is missing or the file
+ * is broken — it returns `null` and the caller renders a placeholder.
+ */
+export async function loadRgba(file, width, height) {
+    if (!existsSync(file))
+        return null;
+    const tool = findMagick();
+    if (tool === null)
+        return null;
+    return new Promise((resolve) => {
+        const args = [
+            tool,
+            file,
+            '-resize',
+            `${Math.max(1, width)}x${Math.max(1, height)}!`,
+            '-depth',
+            '8',
+            'rgba:-',
+        ];
+        const child = spawn(args[0], args.slice(1), { stdio: ['ignore', 'pipe', 'ignore'] });
+        const chunks = [];
+        let total = 0;
+        let settled = false;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            child.kill();
+            resolve(value);
+        };
+        child.stdout.on('data', (chunk) => {
+            chunks.push(chunk);
+            total += chunk.length;
+        });
+        child.on('error', () => finish(null));
+        child.on('close', (code) => {
+            if (code !== 0)
+                return finish(null);
+            if (total !== width * height * 4)
+                return finish(null);
+            const buf = Buffer.concat(chunks, total);
+            resolve({ width, height, pixels: new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength) });
+        });
+    });
+}
+function findMagick() {
+    for (const candidate of ['magick', 'convert']) {
+        if (probeOnPath(candidate))
+            return candidate;
+    }
+    return null;
+}
+function probeOnPath(cmd) {
+    const path = process.env.PATH ?? '';
+    for (const dir of path.split(':')) {
+        if (dir.length === 0)
+            continue;
+        if (existsSync(`${dir}/${cmd}`))
+            return true;
+    }
+    return false;
+}
+/** Auto-detect whether a `Side` is "complex enough" that image rendering helps. */
+export function isLikelyComplexScript(text) {
+    // CJK, Hangul, Hiragana/Katakana, Devanagari, Arabic, Hebrew, Thai, Tibetan.
+    // The user is learning one of these alphabets → render the card as an image
+    // so the terminal fonts don't fight us. (This requires the user to supply
+    // a font-rendered PNG of the text; the renderer falls back to plain text.)
+    return /[\u3000-\u9fff\uac00-\ud7af\u0900-\u097f\u0600-\u06ff\u0590-\u05ff\u0e00-\u0e7f\u0f00-\u0fff]/.test(text);
+}
+/** Resolve a media reference against the deck file's directory. */
+export function resolveDeckMedia(deckPath, ref) {
+    return resolveMediaPath(deckPath, ref);
+}

package/dist/flashcards/render.js

@@ -0,0 +1,110 @@
+import { existsSync } from 'node:fs';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { isImagePath, loadRgba } from './image.js';
+import { halfBlockLines } from './halfblock.js';
+/**
+ * Render a `Side` to text + image rows. Text rows are returned synchronously
+ * (so card reveals are instant). Image rows resolve asynchronously and
+ * populate the cache.
+ */
+export async function renderSide(side, ctx) {
+    const fields = normalizeSide(side);
+    const textRows = [];
+    const imageRows = [];
+    for (const field of fields) {
+        if (field.text !== undefined) {
+            for (const row of wrapText(field.text, ctx.cellsWidth)) {
+                textRows.push(row);
+            }
+        }
+        if (field.image !== undefined) {
+            const rendered = await renderImageField(field.image, ctx);
+            if (rendered !== null) {
+                // Leave a blank line before an image if we already have text.
+                if (textRows.length > 0)
+                    textRows.push('');
+                imageRows.push(...rendered);
+            }
+            else {
+                textRows.push(`[image missing: ${field.image}]`);
+            }
+        }
+    }
+    return { text: textRows, imageRows };
+}
+function normalizeSide(side) {
+    if (typeof side === 'string')
+        return [{ text: side }];
+    return side;
+}
+function wrapText(text, width) {
+    if (width <= 0)
+        return [text];
+    const out = [];
+    for (const paragraph of text.split('\n')) {
+        if (paragraph.length === 0) {
+            out.push('');
+            continue;
+        }
+        // Greedy wrap on whitespace; preserves CJK by breaking on any char.
+        const isWide = /[\u3000-\u9fff\uff00-\uffef]/.test(paragraph);
+        if (isWide) {
+            for (let i = 0; i < paragraph.length; i += width) {
+                out.push(paragraph.slice(i, i + width));
+            }
+        }
+        else {
+            const words = paragraph.split(/(\s+)/);
+            let line = '';
+            for (const word of words) {
+                if (line.length + word.length > width && line.length > 0) {
+                    out.push(line);
+                    line = word.trimStart();
+                    if (line.length > width) {
+                        // Long word: hard-split.
+                        for (let i = 0; i < line.length; i += width) {
+                            out.push(line.slice(i, i + width));
+                        }
+                        line = '';
+                    }
+                }
+                else {
+                    line += word;
+                }
+            }
+            if (line.length > 0)
+                out.push(line);
+        }
+    }
+    return out;
+}
+async function renderImageField(ref, ctx) {
+    const cached = ctx.imageCache.get(ref);
+    if (cached !== undefined)
+        return cached;
+    const promise = (async () => {
+        if (!isImagePath(ref))
+            return null;
+        const resolved = resolveRef(ctx.deckPath, ref);
+        if (!existsSync(resolved))
+            return null;
+        const size = pickImageSize(ctx.cellsWidth, ctx.cellsHeight);
+        const rgba = await loadRgba(resolved, size.width, size.height);
+        if (rgba === null)
+            return null;
+        return halfBlockLines(rgba);
+    })();
+    ctx.imageCache.set(ref, promise);
+    return promise;
+}
+function resolveRef(deckPath, ref) {
+    if (ref.startsWith('~'))
+        return ref.replace(/^~/, process.env.HOME ?? '');
+    if (isAbsolute(ref))
+        return ref;
+    return resolve(dirname(deckPath), ref);
+}
+function pickImageSize(cellsWidth, cellsHeight) {
+    // ImageMagick does the resize for us, so we just hand it the cell size.
+    return { width: cellsWidth, height: cellsHeight * 2 };
+}