@thesimonharms/basa 0.1.0 → 0.1.2

package/src/flashcards/render.ts

@@ -1,123 +0,0 @@
-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

@@ -1,115 +0,0 @@
-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

@@ -1,88 +0,0 @@
-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

@@ -1,85 +0,0 @@
-/**
- * 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

@@ -1,14 +0,0 @@
-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',
-    });
-  }
-}

package/src/tui/CardView.ts

@@ -1,281 +0,0 @@
-import { BaseComponent } from '@mudah-cli/tui';
-import { detectCapabilities, type KeyEvent } from '@mudah-cli/terminal';
-import { paint, visibleLength } from '@mudah-cli/ui';
-import type { Grade, ReviewCard } from '../flashcards/types.js';
-import { renderSide, type RenderContext, type RenderedSide } from '../flashcards/render.js';
-import {
-  confettiRows,
-  shakeRows,
-  typeOnRows,
-  type ConfettiSpec,
-  type ShakeState,
-  type TypeOnState,
-} from './effects.js';
-
-export interface CardViewOptions {
-  deckPath: string;
-  cellsWidth: number;
-  cellsHeight: number;
-  onGraded: (grade: Grade, typed: string) => void;
-  onSkip: () => void;
-  onDone?: () => void;
-}
-
-export interface SessionStats {
-  reviewed: number;
-  again: number;
-  hard: number;
-  good: number;
-  easy: number;
-}
-
-interface EffectFrame {
-  /** Centered, padded text content. */
-  rows: string[];
-  /** Image rows to draw below the text. */
-  imageRows: string[];
-}
-
-/**
- * The flashcard face. Renders the front; on space, animates the back in.
- * Keys 1-4 grade. `n` skips (no grade recorded). `enter` submits typed answer.
- *
- * Owns its own animation state — tick() is called by the host every frame.
- */
-export class CardView extends BaseComponent {
-  readonly focusable = true;
-  private typed = '';
-
-  private front: RenderedSide = { text: [], imageRows: [] };
-  private back: RenderedSide = { text: [], imageRows: [] };
-  private doneStats: SessionStats | null = null;
-
-  private revealed = false;
-  private revealAnim: TypeOnState = { durationFrames: 8, frame: 0 };
-  private shake: ShakeState | null = null;
-  private confetti: ConfettiSpec | null = null;
-
-  private readonly ctx: RenderContext;
-  private current: ReviewCard | undefined;
-
-  private readonly options: CardViewOptions;
-
-  constructor(options: CardViewOptions) {
-    super();
-    this.options = options;
-    this.ctx = {
-      deckPath: options.deckPath,
-      cellsWidth: options.cellsWidth,
-      cellsHeight: options.cellsHeight,
-      imageCache: new Map(),
-    };
-  }
-
-  /** Update the active card. Resets reveal + animation state. */
-  async setCard(card: ReviewCard | undefined, stats?: SessionStats): Promise<void> {
-    this.current = card;
-    this.revealed = false;
-    this.typed = '';
-    this.shake = null;
-    this.confetti = null;
-    this.revealAnim = { durationFrames: 8, frame: 0 };
-    if (card === undefined) {
-      this.doneStats = stats ?? null;
-      this.front = { text: this.doneViewText(), imageRows: [] };
-      this.back = { text: [], imageRows: [] };
-      this.options.onDone?.();
-      return;
-    }
-    this.doneStats = null;
-    this.front = await renderSide(card.card.front, this.ctx);
-    this.back = await renderSide(card.card.back, this.ctx);
-  }
-
-  private doneViewText(): string[] {
-    if (this.doneStats === null) {
-      return ['All caught up!', 'Press Esc to quit.'];
-    }
-    const s = this.doneStats;
-    return [
-      '',
-      '   ╭───────────────────────────────────────╮',
-      '   │                                       │',
-      '   │        session complete!              │',
-      '   │                                       │',
-      `   │   reviewed  ${pad(s.reviewed, 3)} cards                    │`,
-      `   │   again  ${pad(s.again, 3)}   hard  ${pad(s.hard, 3)}   good  ${pad(s.good, 3)}   easy  ${pad(s.easy, 3)}    │`,
-      '   │                                       │',
-      '   │        press esc to exit              │',
-      '   │                                       │',
-      '   ╰───────────────────────────────────────╯',
-      '',
-    ];
-  }
-
-  /** Drive animations. Called by the host once per repaint. */
-  tick(): void {
-    if (this.revealed && this.revealAnim.frame < this.revealAnim.durationFrames) {
-      this.revealAnim.frame++;
-    }
-    if (this.shake !== null && this.shake.frame < this.shake.durationFrames) {
-      this.shake.frame++;
-      if (this.shake.frame >= this.shake.durationFrames) this.shake = null;
-    }
-    if (this.confetti !== null && this.confetti.frame < this.confetti.durationFrames) {
-      this.confetti.frame++;
-      if (this.confetti.frame >= this.confetti.durationFrames) this.confetti = null;
-    }
-  }
-
-  /** Resize the rendering area (after a terminal resize). */
-  resize(cellsWidth: number, cellsHeight: number): void {
-    this.ctx.cellsWidth = cellsWidth;
-    this.ctx.cellsHeight = cellsHeight;
-    this.ctx.imageCache.clear();
-    if (this.current !== undefined) {
-      // Re-render in the background. Until the new rows arrive, the existing
-      // rows still display — no flicker, no jump.
-      void this.setCard(this.current);
-    }
-  }
-
-  override onKey(event: KeyEvent): boolean {
-    if (event.name === 'space' || event.name === 'enter') {
-      this.revealed = true;
-      this.revealAnim = { durationFrames: 8, frame: 0 };
-      return true;
-    }
-    if (event.name === 'backspace') {
-      this.typed = this.typed.slice(0, -1);
-      return true;
-    }
-    if (this.revealed) {
-      switch (event.name) {
-        case '1':
-          this.grade(0);
-          return true;
-        case '2':
-          this.grade(1);
-          return true;
-        case '3':
-          this.grade(2);
-          return true;
-        case '4':
-          this.grade(3);
-          return true;
-      }
-    }
-    if (event.name === 'n') {
-      this.options.onSkip();
-      return true;
-    }
-    if (event.ch !== undefined && event.ch >= ' ' && event.ch !== 'n' && (event.ch < '0' || event.ch > '9')) {
-      this.typed += event.ch;
-      return true;
-    }
-    return false;
-  }
-
-  private grade(g: Grade): void {
-    this.options.onGraded(g, this.typed);
-    if (g === 0) {
-      this.shake = { durationFrames: 10, frame: 0 };
-    } else if (g === 3) {
-      this.confetti = {
-        frame: 0,
-        durationFrames: 24,
-        seed: Math.floor(Math.random() * 1e6),
-        width: this.options.cellsWidth,
-        palette: ['\x1b[38;5;213m', '\x1b[38;5;215m', '\x1b[38;5;220m', '\x1b[38;5;156m', '\x1b[38;5;123m'],
-      };
-    }
-    this.typed = '';
-  }
-
-  render(): string[] {
-    const out: string[] = [];
-
-    // Header line: prompt + type input
-    const lvl = detectCapabilities().colorLevel;
-    const promptText = this.revealed
-      ? paint('#fbbf24', 'Type your answer, then press 1-4 to grade', lvl)
-      : paint('#94a3b8', 'Press Space to reveal', lvl);
-    const typed = this.typed.length > 0 ? paint('#e2e8f0', ` > ${this.typed}▏`, lvl) : '';
-    out.push(centerLine(`${promptText}${typed}`, this.options.cellsWidth));
-
-    // Spacer
-    out.push('');
-
-    // Card front
-    const frontRows = this.front.text;
-    const centeredFront = frontRows.map((row) => centerLine(row, this.options.cellsWidth));
-    out.push(...this.applyEffects(centeredFront, 'front'));
-
-    // Spacer
-    out.push('');
-
-    // Divider
-    if (this.revealed) {
-      out.push(centerLine(paint('#475569', '─'.repeat(Math.min(60, this.options.cellsWidth - 4)), lvl), this.options.cellsWidth));
-      out.push('');
-
-      const backRows = this.back.text;
-      const typedBack = this.revealed ? typeOnRows(this.revealAnim, backRows) : [];
-      const centeredBack = typedBack.map((row) => centerLine(row, this.options.cellsWidth));
-      out.push(...this.applyEffects(centeredBack, 'back'));
-
-      // Hint, if any
-      if (this.current?.card.hint !== undefined && this.revealed) {
-        out.push('');
-        out.push(centerLine(paint('#64748b', `hint: ${this.current.card.hint}`, lvl), this.options.cellsWidth));
-      }
-    }
-
-    // Image rows (always rendered below the text).
-    const imageRows = this.revealed
-      ? [...this.front.imageRows, ...this.back.imageRows]
-      : this.front.imageRows;
-    for (const row of imageRows) {
-      out.push(centerLine(row, this.options.cellsWidth));
-    }
-
-    // Confetti overlay
-    if (this.confetti !== null) {
-      const overlay = confettiRows(this.confetti, Math.min(8, this.options.cellsHeight));
-      for (let i = 0; i < overlay.length; i++) {
-        out[out.length - overlay.length + i] = overlay[i] ?? '';
-      }
-    }
-
-    // Pad / truncate to fit the cell height so the screen layout is stable.
-    while (out.length < this.options.cellsHeight) out.push('');
-    if (out.length > this.options.cellsHeight) out.length = this.options.cellsHeight;
-
-    return out;
-  }
-
-  private applyEffects(rows: string[], seedKey: string): string[] {
-    let out = rows;
-    if (this.shake !== null) {
-      out = shakeRows(this.shake, out, hashString(`${seedKey}:${this.current?.card.front ?? ''}`));
-    }
-    return out;
-  }
-}
-
-function centerLine(text: string, width: number): string {
-  const visible = visibleLength(text);
-  if (visible >= width) return text;
-  const pad = Math.floor((width - visible) / 2);
-  return ' '.repeat(pad) + text;
-}
-
-function hashString(s: string): number {
-  let h = 0;
-  for (let i = 0; i < s.length; i++) h = (h * 31 + s.charCodeAt(i)) | 0;
-  return h;
-}
-
-function pad(n: number, width: number): string {
-  return String(n).padStart(width, ' ');
-}