@thesimonharms/basa 0.1.0

package/src/flashcards/halfblock.ts

@@ -0,0 +1,55 @@
+import type { RgbaImage } from './image.js';
+
+/**
+ * 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: RgbaImage): string[] {
+  const { width, height, pixels } = image;
+  const out: string[] = [];
+  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: Uint8Array, width: number, height: number, x: number, y: number): { r: number; g: number; b: number } {
+  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: number,
+  sourceHeight: number,
+  maxCellsWidth: number,
+  maxCellsHeight: number,
+): { width: number; height: number } {
+  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/src/flashcards/image.ts

@@ -0,0 +1,97 @@
+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: string): boolean {
+  const lower = ref.toLowerCase();
+  for (const ext of IMAGE_EXTS) {
+    if (lower.endsWith(ext)) return true;
+  }
+  return false;
+}
+
+export interface RgbaImage {
+  width: number;
+  height: number;
+  /** Row-major RGBA bytes. */
+  pixels: Uint8Array;
+}
+
+/**
+ * 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: string, width: number, height: number): Promise<RgbaImage | null> {
+  if (!existsSync(file)) return null;
+  const tool = findMagick();
+  if (tool === null) return null;
+
+  return new Promise<RgbaImage | null>((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: Buffer[] = [];
+    let total = 0;
+    let settled = false;
+
+    const finish = (value: RgbaImage | null) => {
+      if (settled) return;
+      settled = true;
+      child.kill();
+      resolve(value);
+    };
+
+    child.stdout!.on('data', (chunk: Buffer) => {
+      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(): string | null {
+  for (const candidate of ['magick', 'convert']) {
+    if (probeOnPath(candidate)) return candidate;
+  }
+  return null;
+}
+
+function probeOnPath(cmd: string): boolean {
+  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: string): boolean {
+  // 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: string, ref: string): string {
+  return resolveMediaPath(deckPath, ref);
+}

package/src/flashcards/render.ts

@@ -0,0 +1,123 @@
+import { existsSync } from 'node:fs';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import type { Field, Side } from './types.js';
+import { isImagePath, loadRgba } from './image.js';
+import { halfBlockLines } from './halfblock.js';
+
+export interface RenderContext {
+  deckPath: string;
+  /** Max width in cells available for the card face. */
+  cellsWidth: number;
+  /** Max height in cells. */
+  cellsHeight: number;
+  /** Reused so we don't reload + re-resize the same image every frame. */
+  imageCache: Map<string, Promise<string[] | null>>;
+}
+
+export interface RenderedSide {
+  /** Plain text rows (no images). Always present, useful for animations. */
+  text: string[];
+  /** Pre-rendered image rows (already half-block ANSI strings). Empty if no images. */
+  imageRows: string[];
+}
+
+/**
+ * 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: Side, ctx: RenderContext): Promise<RenderedSide> {
+  const fields = normalizeSide(side);
+  const textRows: string[] = [];
+  const imageRows: string[] = [];
+
+  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: Side): Field[] {
+  if (typeof side === 'string') return [{ text: side }];
+  return side;
+}
+
+function wrapText(text: string, width: number): string[] {
+  if (width <= 0) return [text];
+  const out: string[] = [];
+  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: string, ctx: RenderContext): Promise<string[] | null> {
+  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: string, ref: string): string {
+  if (ref.startsWith('~')) return ref.replace(/^~/, process.env.HOME ?? '');
+  if (isAbsolute(ref)) return ref;
+  return resolve(dirname(deckPath), ref);
+}
+
+function pickImageSize(cellsWidth: number, cellsHeight: number): { width: number; height: number } {
+  // ImageMagick does the resize for us, so we just hand it the cell size.
+  return { width: cellsWidth, height: cellsHeight * 2 };
+}

package/src/flashcards/sound.ts

@@ -0,0 +1,115 @@
+import { AudioOut, detectAudio, silentRequested, type AudioClip, type AudioDetection } from '@mudah-cli/audio';
+import type { Grade } from './types.js';
+
+const SAMPLE_RATE = 44100;
+
+/** A BasaFx is a tiny sound effect player with two one-shots. */
+export class BasaFx {
+  private audio: AudioOut | null = null;
+  readonly detection: AudioDetection | null;
+
+  private constructor(audio: AudioOut | null, detection: AudioDetection | null) {
+    this.audio = audio;
+    this.detection = detection;
+  }
+
+  /** Probe + open. Returns a silent instance if no backend is available. */
+  static async open(): Promise<BasaFx> {
+    if (silentRequested()) return new BasaFx(null, null);
+    const detection = detectAudio();
+    if (detection.backend === 'silent') return new BasaFx(null, detection);
+    try {
+      const audio = await AudioOut.open({ sampleRate: SAMPLE_RATE, channels: 1 });
+      return new BasaFx(audio, detection);
+    } catch {
+      return new BasaFx(null, detection);
+    }
+  }
+
+  get isLive(): boolean {
+    return this.audio !== null;
+  }
+
+  /** Play the "you got it" sound. Grade 2 (Good) and 3 (Easy) → happy ding. */
+  async playCorrect(grade: Grade): Promise<void> {
+    if (this.audio === null) return;
+    const clip = grade === 3 ? happyChirp() : ding();
+    await this.audio.play(clip);
+  }
+
+  /** Play the "not quite" sound. Grade 0 (Again) → low buzz. */
+  async playIncorrect(): Promise<void> {
+    if (this.audio === null) return;
+    await this.audio.play(buzz());
+  }
+
+  async dispose(): Promise<void> {
+    this.audio?.dispose();
+    this.audio = null;
+  }
+}
+
+/**
+ * A two-note ascending arpeggio (C5 → E5). Quick, bright, low-volume.
+ * 0.18s total.
+ */
+function ding(): AudioClip {
+  const samples = renderSequence([
+    { freq: 523.25, durationMs: 90, volume: 0.4 },
+    { freq: 659.25, durationMs: 90, volume: 0.4 },
+  ]);
+  return { samples, sampleRate: SAMPLE_RATE, channels: 1 };
+}
+
+/** Three ascending notes (C5 → E5 → G5). Triumphant. 0.30s total. */
+function happyChirp(): AudioClip {
+  const samples = renderSequence([
+    { freq: 523.25, durationMs: 80, volume: 0.45 },
+    { freq: 659.25, durationMs: 80, volume: 0.45 },
+    { freq: 783.99, durationMs: 140, volume: 0.5 },
+  ]);
+  return { samples, sampleRate: SAMPLE_RATE, channels: 1 };
+}
+
+/** Two low square-ish pulses. 0.20s total. */
+function buzz(): AudioClip {
+  const samples = renderSequence([
+    { freq: 196.0, durationMs: 90, volume: 0.35, pulse: true },
+    { freq: 164.81, durationMs: 90, volume: 0.35, pulse: true },
+  ]);
+  return { samples, sampleRate: SAMPLE_RATE, channels: 1 };
+}
+
+interface Note {
+  freq: number;
+  durationMs: number;
+  volume: number;
+  pulse?: boolean;
+}
+
+function renderSequence(notes: Note[]): Int16Array {
+  const total = notes.reduce((sum, n) => sum + Math.ceil((n.durationMs / 1000) * SAMPLE_RATE), 0);
+  const out = new Int16Array(total);
+  let cursor = 0;
+  for (const note of notes) {
+    const frames = Math.ceil((note.durationMs / 1000) * SAMPLE_RATE);
+    for (let i = 0; i < frames; i++) {
+      const t = i / SAMPLE_RATE;
+      const envelope = triangle(i, frames);
+      const value = Math.sin(2 * Math.PI * note.freq * t) * envelope * note.volume;
+      const square = note.pulse ? (Math.sin(2 * Math.PI * note.freq * t) >= 0 ? 1 : -1) : 0;
+      const mixed = note.pulse ? 0.6 * value + 0.4 * square * note.volume * envelope : value;
+      out[cursor + i] = Math.max(-1, Math.min(1, mixed)) * 0x7fff;
+    }
+    cursor += frames;
+  }
+  return out;
+}
+
+function triangle(i: number, total: number): number {
+  // Quick attack, slow release: 0..0.05 then linear decay to 0.
+  const attack = 0.05;
+  const t = i / total;
+  if (t < attack) return t / attack;
+  return Math.max(0, 1 - (t - attack) / (1 - attack));
+}

package/src/flashcards/srs.ts

@@ -0,0 +1,88 @@
+import type { Grade, SrsState } from './types.js';
+
+/** A relaxed SM-2 implementation. Reasonable defaults, no anki-parity goal. */
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+export function freshState(now: number = Date.now()): SrsState {
+  // `due: null` means "due immediately" — see `isDue`. Using a captured
+  // timestamp here is racey when the caller samples `Date.now()` again
+  // later (e.g. the list command compares state.due against a `now`
+  // sampled before the loop, while the loop's `loadReviewCards` calls
+  // freshState() for each card with progressively later timestamps).
+  void now;
+  return {
+    due: null,
+    streak: 0,
+    ease: 2.5,
+    intervalDays: 0,
+    reviews: 0,
+    lastGrade: null,
+  };
+}
+
+/**
+ * Apply a grade to a card's state and return the next state.
+ * Pure function — no I/O, no randomness — so it's trivially testable.
+ */
+export function grade(state: SrsState, grade: Grade, now: number = Date.now()): SrsState {
+  const next: SrsState = {
+    due: state.due,
+    streak: state.streak,
+    ease: state.ease,
+    intervalDays: state.intervalDays,
+    reviews: state.reviews + 1,
+    lastGrade: grade,
+  };
+
+  if (grade === 0) {
+    // Again: reset streak, ease drops, see it again in 10 minutes.
+    next.streak = 0;
+    next.ease = Math.max(1.3, state.ease - 0.2);
+    next.intervalDays = 0;
+    next.due = now + 10 * 60 * 1000;
+    return next;
+  }
+
+  next.streak = state.streak + 1;
+  // SM-2 ease adjustment for non-failing grades. Hard (1) drops ease slightly;
+  // Easy (3) bumps it; Good (2) holds.
+  const easeDelta = grade === 1 ? -0.15 : grade === 3 ? 0.15 : 0;
+  next.ease = clamp(state.ease + easeDelta, 1.3, 2.8);
+
+  if (next.streak === 1) {
+    next.intervalDays = 1;
+  } else if (next.streak === 2) {
+    next.intervalDays = 6;
+  } else {
+    next.intervalDays = Math.max(1, Math.round(state.intervalDays * next.ease));
+  }
+
+  next.due = now + next.intervalDays * DAY_MS;
+  return next;
+}
+
+function clamp(value: number, lo: number, hi: number): number {
+  return Math.max(lo, Math.min(hi, value));
+}
+
+/** Cards that are due now or earlier. `null` `due` is treated as "due immediately". */
+export function isDue(state: SrsState, now: number = Date.now()): boolean {
+  if (state.due === null) return true;
+  return state.due <= now;
+}
+
+/** Pick the next due card, ordered by oldest-due first, with new cards last. */
+export function pickNext<T extends { state: SrsState }>(
+  cards: readonly T[],
+  now: number = Date.now(),
+): T | undefined {
+  const due = cards.filter((c) => isDue(c.state, now));
+  if (due.length === 0) return undefined;
+  const sorted = [...due].sort((a, b) => {
+    const ad = a.state.due ?? 0;
+    const bd = b.state.due ?? 0;
+    return ad - bd;
+  });
+  return sorted[0];
+}

package/src/flashcards/types.ts

@@ -0,0 +1,85 @@
+/**
+ * Open flashcard format.
+ *
+ * A deck is a single file (YAML or JSON) with this shape:
+ *
+ *   name: "Spanish 101"
+ *   description: "First-year Spanish vocabulary"
+ *   cards:
+ *     - front: "hola"
+ *       back: "hello"
+ *     - front: "perro"
+ *       back: "dog"
+ *     - front:
+ *         text: "ありがとう"
+ *         image: "./assets/thanks.png"   # optional
+ *       back:
+ *         text: "thank you"
+ *
+ * Each side is either a plain string (a single text field) or a list of
+ * fields, where each field is `{ text?, image?, audio? }`. The renderer walks
+ * the list top-to-bottom, leaving a blank line between fields. An `image`
+ * field is rendered with half-block cells (universal truecolor); a `text`
+ * field is rendered verbatim. An `audio` field is a relative path to a WAV
+ * that the user can play with `p` while reviewing.
+ */
+
+export interface Field {
+  text?: string;
+  image?: string;
+  audio?: string;
+}
+
+export type Side = string | Field[];
+
+export interface Card {
+  front: Side;
+  back: Side;
+  /**
+   * Optional per-card hints. The SRS engine reads `tags` for filtering; the
+   * UI reads `hint` to show a small prompt after a wrong answer.
+   */
+  tags?: string[];
+  hint?: string;
+}
+
+export interface Deck {
+  name: string;
+  description?: string;
+  cards: Card[];
+}
+
+export interface SrsState {
+  /** Next due time, ms since epoch. `null` means "not started". */
+  due: number | null;
+  /** Number of successful reviews in a row. Resets to 0 on `again`. */
+  streak: number;
+  /** SM-2 ease factor, 1.3 .. 2.8. */
+  ease: number;
+  /** Current interval in days. */
+  intervalDays: number;
+  /** Total times this card has been shown. */
+  reviews: number;
+  /** Last grade given (0..3). */
+  lastGrade: 0 | 1 | 2 | 3 | null;
+}
+
+/** A card together with its review state. */
+export interface ReviewCard {
+  card: Card;
+  state: SrsState;
+}
+
+/** SM-2-style grades. */
+export type Grade = 0 | 1 | 2 | 3;
+
+export const GRADE_LABELS: readonly string[] = ['Again', 'Hard', 'Good', 'Easy'];
+
+/**
+ * What a user actually answered. The text input is free-form; the rating bar
+ * is graded. We capture both so the UI can show "you typed X, the answer was Y".
+ */
+export interface AnswerRecord {
+  typed: string;
+  grade: Grade;
+}

package/src/providers/AppProvider.ts

@@ -0,0 +1,14 @@
+import { ServiceProvider } from '@mudah-cli/mudah';
+
+export default class BasaProvider extends ServiceProvider {
+  register(): void {
+    this.app.config().merge('app', {
+      name: 'basa',
+      env: 'local',
+      // Default location for user decks (~/.config/basa/decks).
+      decksDir: '~/basa/decks',
+      // Optional sound effects: 'on' | 'off' | 'auto'.
+      sound: 'auto',
+    });
+  }
+}