@thesimonharms/basa 0.1.0

package/src/tui/CardView.ts

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

package/src/tui/Footer.ts

@@ -0,0 +1,65 @@
+import { BaseComponent } from '@mudah-cli/tui';
+import { detectCapabilities } from '@mudah-cli/terminal';
+import { paint } from '@mudah-cli/ui';
+
+const KEYS: ReadonlyArray<{ key: string; label: string; tone: 'good' | 'meh' | 'bad' | 'neutral' }> = [
+  { key: '1', label: 'Again', tone: 'bad' },
+  { key: '2', label: 'Hard',  tone: 'meh' },
+  { key: '3', label: 'Good',  tone: 'good' },
+  { key: '4', label: 'Easy',  tone: 'good' },
+];
+
+const TONES: Record<'good' | 'meh' | 'bad' | 'neutral', string> = {
+  good: '#4ade80',
+  meh: '#fbbf24',
+  bad: '#f87171',
+  neutral: '#94a3b8',
+};
+
+/** The key legend. Centered, three rows: title, four key chips, hints. */
+export class Footer extends BaseComponent {
+  readonly focusable = false;
+
+  private width: number;
+
+  constructor(width: number) {
+    super();
+    this.width = width;
+  }
+
+  resize(width: number): void {
+    this.width = width;
+  }
+
+  render(): string[] {
+    const lvl = detectCapabilities().colorLevel;
+    const chips = KEYS.map((k) => {
+      const color = TONES[k.tone];
+      return `${paint('#0f172a', ` ${k.key} `, lvl)}${paint(color, ` ${k.label} `, lvl)}`;
+    }).join('  ');
+    const row1 = centerLine(chips, this.width);
+    const row2 = centerLine(
+      paint('#64748b', 'space/enter: reveal   n: skip   esc: quit', lvl),
+      this.width,
+    );
+    return ['', row1, row2];
+  }
+}
+
+function centerLine(text: string, width: number): string {
+  return ' '.repeat(Math.max(0, Math.floor((width - visibleOf(text)) / 2))) + text;
+}
+
+function visibleOf(text: string): number {
+  let visible = 0;
+  let inEscape = false;
+  for (const ch of text) {
+    if (ch === '\x1b') { inEscape = true; continue; }
+    if (inEscape) {
+      if (ch === 'm') inEscape = false;
+      continue;
+    }
+    visible++;
+  }
+  return visible;
+}

package/src/tui/Header.ts

@@ -0,0 +1,58 @@
+import { BaseComponent } from '@mudah-cli/tui';
+import { detectCapabilities } from '@mudah-cli/terminal';
+import { paint } from '@mudah-cli/ui';
+
+export interface HeaderOptions {
+  deckName: string;
+  reviewed: number;
+  total: number;
+  width: number;
+}
+
+/** Deck name + progress bar. One row, centered. */
+export class Header extends BaseComponent {
+  readonly focusable = false;
+
+  private readonly options: HeaderOptions;
+
+  constructor(options: HeaderOptions) {
+    super();
+    this.options = options;
+  }
+
+  update(options: HeaderOptions): void {
+    Object.assign(this.options, options);
+  }
+
+  render(): string[] {
+    const lvl = detectCapabilities().colorLevel;
+    const barWidth = Math.max(10, Math.min(40, this.options.width - 30));
+    const ratio = this.options.total > 0 ? this.options.reviewed / this.options.total : 0;
+    const filled = Math.round(ratio * barWidth);
+    const bar = '█'.repeat(filled) + '░'.repeat(barWidth - filled);
+    const left = paint('#e2e8f0', this.options.deckName, lvl);
+    const right = paint('#94a3b8', ` ${this.options.reviewed}/${this.options.total}`, lvl);
+    const progress = paint(ratio >= 1 ? '#4ade80' : '#60a5fa', bar, lvl);
+    const line = `${left}  ${progress}${right}`;
+    return [centerLine(line, this.options.width)];
+  }
+}
+
+function centerLine(text: string, width: number): string {
+  // Use a simple visible-length estimate: count chars, ignore ANSI.
+  return ' '.repeat(Math.max(0, Math.floor((width - visibleOf(text)) / 2))) + text;
+}
+
+function visibleOf(text: string): number {
+  let visible = 0;
+  let inEscape = false;
+  for (const ch of text) {
+    if (ch === '\x1b') { inEscape = true; continue; }
+    if (inEscape) {
+      if (ch === 'm') inEscape = false;
+      continue;
+    }
+    visible++;
+  }
+  return visible;
+}

package/src/tui/StudyApp.ts

@@ -0,0 +1,147 @@
+import { Container } from '@mudah-cli/tui';
+import type { Deck, Grade, ReviewCard } from '../flashcards/types.js';
+import { grade, pickNext } from '../flashcards/srs.js';
+import { saveReviewCards } from '../flashcards/deck.js';
+import { BasaFx } from '../flashcards/sound.js';
+import { CardView } from './CardView.js';
+import { Header } from './Header.js';
+import { Footer } from './Footer.js';
+
+export interface StudyAppOptions {
+  deck: Deck;
+  deckPath: string;
+  cards: ReviewCard[];
+  width: number;
+  height: number;
+  fx: BasaFx;
+}
+
+interface SessionStats {
+  reviewed: number;
+  again: number;
+  hard: number;
+  good: number;
+  easy: number;
+}
+
+/**
+ * The study session. Owns SRS state, the focused card, the session stats.
+ * Exposes a `Container` for the TUI program to mount, plus `tick()` and
+ * `resize()` methods the host calls every frame and on terminal resize.
+ */
+export class StudyApp {
+  readonly root: Container;
+  private readonly cardView: CardView;
+  private readonly header: Header;
+  private readonly footer: Footer;
+  private cards: ReviewCard[];
+  private current: ReviewCard | undefined;
+  private stats: SessionStats = { reviewed: 0, again: 0, hard: 0, good: 0, easy: 0 };
+  private width: number;
+  private height: number;
+
+  private readonly options: StudyAppOptions;
+
+  constructor(options: StudyAppOptions) {
+    this.options = options;
+    this.cards = options.cards;
+    this.width = options.width;
+    this.height = options.height;
+
+    const cardHeight = Math.max(8, options.height - 8);
+    this.cardView = new CardView({
+      deckPath: options.deckPath,
+      cellsWidth: options.width,
+      cellsHeight: cardHeight,
+      onGraded: (g, typed) => void this.handleGrade(g, typed),
+      onSkip: () => this.handleSkip(),
+    });
+    this.header = new Header({
+      deckName: options.deck.name,
+      reviewed: 0,
+      total: this.cards.length,
+      width: options.width,
+    });
+    this.footer = new Footer(options.width);
+
+    this.root = new Container().add(this.header).add(this.cardView).add(this.footer);
+    void this.advance();
+  }
+
+  /** Drive animations. Called by the host on every frame. */
+  tick(): void {
+    this.cardView.tick();
+  }
+
+  /** Apply a terminal resize. */
+  resize(width: number, height: number): void {
+    this.width = width;
+    this.height = height;
+    this.header.update({
+      deckName: this.options.deck.name,
+      reviewed: this.stats.reviewed,
+      total: this.cards.length,
+      width,
+    });
+    this.footer.resize(width);
+    const cardHeight = Math.max(8, height - 8);
+    this.cardView.resize(width, cardHeight);
+  }
+
+  /** Persist state on shutdown. Safe to call multiple times. */
+  async persist(): Promise<void> {
+    await saveReviewCards(this.options.deckPath, this.cards).catch(() => {});
+  }
+
+  private async advance(): Promise<void> {
+    this.current = pickNext(this.cards, Date.now());
+    if (this.current === undefined) {
+      await this.cardView.setCard(undefined, this.stats);
+      return;
+    }
+    await this.cardView.setCard(this.current);
+  }
+
+  private async handleGrade(gradeValue: Grade, _typed: string): Promise<void> {
+    if (this.current === undefined) return;
+    const idx = this.cards.indexOf(this.current);
+    if (idx < 0) return;
+    const next = grade(this.current.state, gradeValue);
+    this.cards[idx] = { card: this.current.card, state: next };
+    this.stats = {
+      reviewed: this.stats.reviewed + 1,
+      again: this.stats.again + (gradeValue === 0 ? 1 : 0),
+      hard: this.stats.hard + (gradeValue === 1 ? 1 : 0),
+      good: this.stats.good + (gradeValue === 2 ? 1 : 0),
+      easy: this.stats.easy + (gradeValue === 3 ? 1 : 0),
+    };
+    this.header.update({
+      deckName: this.options.deck.name,
+      reviewed: this.stats.reviewed,
+      total: this.cards.length,
+      width: this.width,
+    });
+
+    if (gradeValue === 0) {
+      await this.options.fx.playIncorrect();
+    } else {
+      await this.options.fx.playCorrect(gradeValue);
+    }
+
+    // Persist after every grade so a crash doesn't lose progress.
+    await saveReviewCards(this.options.deckPath, this.cards).catch(() => {});
+
+    await this.advance();
+  }
+
+  private handleSkip(): void {
+    if (this.current === undefined) return;
+    const idx = this.cards.indexOf(this.current);
+    if (idx < 0) return;
+    this.cards[idx] = {
+      card: this.current.card,
+      state: { ...this.current.state, due: Date.now() + 30_000 },
+    };
+    void this.advance();
+  }
+}

package/src/tui/effects.ts

@@ -0,0 +1,81 @@
+/**
+ * Visual effect helpers. Each is a small mutable object that the card view
+ * ticks every frame. They never touch the terminal directly — they just
+ * transform strings the component is about to render.
+ */
+
+export interface TypeOnState {
+  /** Total frames the effect should run for. */
+  durationFrames: number;
+  /** Frame counter, incremented by the host. */
+  frame: number;
+}
+
+/** Reveal a string array row-by-row. 0 → 0 rows, 1 → all rows. */
+export function typeOnRows(state: TypeOnState, rows: string[]): string[] {
+  const t = Math.min(1, state.frame / Math.max(1, state.durationFrames));
+  const visible = Math.max(1, Math.ceil(rows.length * t));
+  return rows.slice(0, visible);
+}
+
+export interface ShakeState {
+  durationFrames: number;
+  frame: number;
+}
+
+/** Apply a per-row horizontal jitter that decays. The component pads each
+ *  row with random leading spaces within a window that shrinks over time. */
+export function shakeRows(state: ShakeState, rows: string[], seed: number): string[] {
+  const t = Math.min(1, state.frame / Math.max(1, state.durationFrames));
+  const amplitude = Math.round((1 - t) * 3);
+  if (amplitude === 0) return rows;
+  return rows.map((row, i) => {
+    // Deterministic pseudo-random per row+frame so the diff renderer still works.
+    const x = pseudo(seed + i * 7 + state.frame * 13);
+    const offset = Math.floor(x * (amplitude * 2 + 1)) - amplitude;
+    if (offset === 0) return row;
+    if (offset > 0) return ' '.repeat(offset) + row;
+    return row.slice(-offset);
+  });
+}
+
+function pseudo(n: number): number {
+  const x = Math.sin(n * 12.9898) * 43758.5453;
+  return x - Math.floor(x);
+}
+
+export interface ConfettiSpec {
+  /** Frame counter, incremented by the host. */
+  frame: number;
+  /** Total frames. */
+  durationFrames: number;
+  /** Pseudo-random seed. */
+  seed: number;
+  /** Width in cells. */
+  width: number;
+  /** Palette: 24-bit color codes as strings. */
+  palette: string[];
+}
+
+/** Render a confetti overlay as N rows. Each row is a string. */
+export function confettiRows(spec: ConfettiSpec, height: number): string[] {
+  const out: string[] = [];
+  for (let row = 0; row < height; row++) {
+    let line = '';
+    for (let col = 0; col < spec.width; col++) {
+      const x = pseudo(spec.seed + row * 91 + col * 17 + spec.frame * 5);
+      const visible = x > 0.65;
+      if (!visible) {
+        line += ' ';
+        continue;
+      }
+      const colorIndex = Math.floor(pseudo(spec.seed + row + col + spec.frame * 3) * spec.palette.length);
+      const color = spec.palette[colorIndex] ?? spec.palette[0]!;
+      const glyphs = ['✦', '✧', '•', '·', '◆', '◇'];
+      const glyph = glyphs[Math.floor(pseudo(spec.seed + col + row) * glyphs.length)] ?? '·';
+      line += `${color}${glyph}\x1b[0m`;
+    }
+    out.push(line);
+  }
+  return out;
+}