saterminal 0.3.2 → 0.5.0

package/src/{text.ts → text/html.ts}

@@ -1,17 +1,7 @@
 import he from "he";
 import { HTMLElement, NodeType, parse, type Node } from "node-html-parser";
-import wrap from "word-wrap";
-
-export type TextStyle = {
-  bold?: boolean;
-  underline?: boolean;
-  italic?: boolean;
-};
-
-export type TextSegment = {
-  text: string;
-  style: TextStyle;
-};
+import { prepareMediaHtml } from "@/text/media.ts";
+import { appendSegment, finalizeSegments, type TextSegment, type TextStyle } from "@/text/rich-text.ts";
 
 export function htmlToText(html = ""): string {
   const text = parseHtmlSegments(html)
@@ -25,7 +15,7 @@ export function htmlToText(html = ""): string {
 }
 
 export function parseHtmlSegments(html = ""): TextSegment[] {
-  const root = parse(prepareHtml(html), { lowerCaseTagName: true });
+  const root = parse(prepareMediaHtml(html), { lowerCaseTagName: true });
   const segments: TextSegment[] = [];
   walkNodes(root, {}, segments);
 
@@ -35,59 +25,6 @@ export function parseHtmlSegments(html = ""): TextSegment[] {
   }));
 }
 
-export function wrapSegments(segments: TextSegment[], width: number): TextSegment[][] {
-  const usableWidth = Math.max(1, width);
-  const lines: TextSegment[][] = [];
-  let currentLine: TextSegment[] = [];
-  let currentWidth = 0;
-
-  const flushLine = () => {
-    lines.push(currentLine);
-    currentLine = [];
-    currentWidth = 0;
-  };
-
-  const appendToLine = (text: string, style: TextStyle) => {
-    if (!text) {
-      return;
-    }
-
-    const last = currentLine[currentLine.length - 1];
-    if (last && stylesEqual(last.style, style)) {
-      last.text += text;
-    } else {
-      currentLine.push({ text, style: { ...style } });
-    }
-    currentWidth += text.length;
-  };
-
-  for (const segment of segments) {
-    const parts = segment.text.split("\n");
-    for (let partIndex = 0; partIndex < parts.length; partIndex += 1) {
-      if (partIndex > 0) {
-        flushLine();
-      }
-
-      const words = parts[partIndex].split(/\s+/).filter(Boolean);
-      for (const word of words) {
-        const needed = (currentWidth === 0 ? 0 : 1) + word.length;
-
-        if (currentWidth > 0 && currentWidth + needed > usableWidth) {
-          flushLine();
-        }
-
-        appendToLine(`${currentWidth === 0 ? "" : " "}${word}`, segment.style);
-      }
-    }
-  }
-
-  if (currentLine.length > 0 || lines.length === 0) {
-    flushLine();
-  }
-
-  return lines;
-}
-
 export function hasHtmlTable(...values: Array<string | undefined>): boolean {
   return values.some((value) => parse(value ?? "").querySelector("table") !== null);
 }
@@ -96,15 +33,6 @@ export function decodeEntities(value: string): string {
   return he.decode(value);
 }
 
-export function wrapText(value: string, width: number): string[] {
-  return wrap(value, {
-    width: Math.max(1, width),
-    trim: true,
-    indent: "",
-    newline: "\n",
-  }).split("\n");
-}
-
 function walkNodes(node: Node, style: TextStyle, segments: TextSegment[]): void {
   if (node.nodeType === NodeType.TEXT_NODE) {
     pushText(segments, node.text, style);
@@ -163,12 +91,6 @@ function hasUnderlineStyle(style: string): boolean {
   return /text-decoration\s*:\s*[^;"]*underline/i.test(style);
 }
 
-function prepareHtml(html: string): string {
-  return html
-    .replace(/<\s*svg\b([^>]*)>[\s\S]*?<\s*\/\s*svg\s*>/gi, (_match, attrs: string) => mediaLabel("Graph", attrs))
-    .replace(/<\s*img\b([^>]*)>/gi, (_match, attrs: string) => mediaLabel("Image", attrs));
-}
-
 function pushText(segments: TextSegment[], text: string, style: TextStyle): void {
   if (!text) {
     return;
@@ -187,44 +109,6 @@ function pushText(segments: TextSegment[], text: string, style: TextStyle): void
   appendSegment(segments, normalized, style);
 }
 
-function appendSegment(segments: TextSegment[], text: string, style: TextStyle): void {
-  const last = segments[segments.length - 1];
-  if (last && stylesEqual(last.style, style)) {
-    last.text += text;
-    return;
-  }
-
-  segments.push({ text, style: { ...style } });
-}
-
-function stylesEqual(left: TextStyle, right: TextStyle): boolean {
-  return !!left.bold === !!right.bold && !!left.underline === !!right.underline && !!left.italic === !!right.italic;
-}
-
-function finalizeSegments(segments: TextSegment[]): TextSegment[] {
-  const merged: TextSegment[] = [];
-  for (const segment of segments) {
-    const last = merged[merged.length - 1];
-    if (last && stylesEqual(last.style, segment.style)) {
-      last.text += segment.text;
-    } else {
-      merged.push({ text: segment.text, style: { ...segment.style } });
-    }
-  }
-  return merged;
-}
-
-function mediaLabel(kind: string, attrs: string): string {
-  const label = readAttribute(attrs, "aria-label") ?? readAttribute(attrs, "alt");
-  return label ? `\n[${kind}: ${label}]\n` : `\n[${kind}]\n`;
-}
-
-function readAttribute(attrs: string, name: string): string | undefined {
-  const pattern = new RegExp(`${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s>]+))`, "i");
-  const match = attrs.match(pattern);
-  return match?.[1] ?? match?.[2] ?? match?.[3];
-}
-
 function normalizeDisplayText(value: string): string {
   return value
     .replace(/\u2019/g, "'")

package/src/text/media.ts

@@ -0,0 +1,16 @@
+export function prepareMediaHtml(html: string): string {
+  return html
+    .replace(/<\s*svg\b([^>]*)>[\s\S]*?<\s*\/\s*svg\s*>/gi, (_match, attrs: string) => mediaLabel("Graph", attrs))
+    .replace(/<\s*img\b([^>]*)>/gi, (_match, attrs: string) => mediaLabel("Image", attrs));
+}
+
+function mediaLabel(kind: string, attrs: string): string {
+  const label = readAttribute(attrs, "aria-label") ?? readAttribute(attrs, "alt");
+  return label ? `\n[${kind}: ${label}]\n` : `\n[${kind}]\n`;
+}
+
+function readAttribute(attrs: string, name: string): string | undefined {
+  const pattern = new RegExp(`${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s>]+))`, "i");
+  const match = attrs.match(pattern);
+  return match?.[1] ?? match?.[2] ?? match?.[3];
+}

package/src/text/rich-text.ts

@@ -0,0 +1,37 @@
+export type TextStyle = {
+  bold?: boolean;
+  underline?: boolean;
+  italic?: boolean;
+};
+
+export type TextSegment = {
+  text: string;
+  style: TextStyle;
+};
+
+export function appendSegment(segments: TextSegment[], text: string, style: TextStyle): void {
+  const last = segments[segments.length - 1];
+  if (last && stylesEqual(last.style, style)) {
+    last.text += text;
+    return;
+  }
+
+  segments.push({ text, style: { ...style } });
+}
+
+export function finalizeSegments(segments: TextSegment[]): TextSegment[] {
+  const merged: TextSegment[] = [];
+  for (const segment of segments) {
+    const last = merged[merged.length - 1];
+    if (last && stylesEqual(last.style, segment.style)) {
+      last.text += segment.text;
+    } else {
+      merged.push({ text: segment.text, style: { ...segment.style } });
+    }
+  }
+  return merged;
+}
+
+export function stylesEqual(left: TextStyle, right: TextStyle): boolean {
+  return !!left.bold === !!right.bold && !!left.underline === !!right.underline && !!left.italic === !!right.italic;
+}

package/src/text/wrap.ts

@@ -0,0 +1,59 @@
+import { appendSegment, stylesEqual, type TextSegment, type TextStyle } from "@/text/rich-text.ts";
+
+export function wrapSegments(segments: TextSegment[], width: number): TextSegment[][] {
+  const usableWidth = Math.max(1, width);
+  const lines: TextSegment[][] = [];
+  let currentLine: TextSegment[] = [];
+  let currentWidth = 0;
+
+  const flushLine = () => {
+    lines.push(currentLine);
+    currentLine = [];
+    currentWidth = 0;
+  };
+
+  const appendToLine = (text: string, style: TextStyle) => {
+    if (!text) {
+      return;
+    }
+
+    const last = currentLine[currentLine.length - 1];
+    if (last && stylesEqual(last.style, style)) {
+      last.text += text;
+    } else {
+      currentLine.push({ text, style: { ...style } });
+    }
+    currentWidth += Bun.stringWidth(text);
+  };
+
+  for (const segment of segments) {
+    const parts = segment.text.split("\n");
+    for (let partIndex = 0; partIndex < parts.length; partIndex += 1) {
+      if (partIndex > 0) {
+        flushLine();
+      }
+
+      const words = parts[partIndex].split(/\s+/).filter(Boolean);
+      for (const word of words) {
+        const spacer = currentWidth === 0 ? "" : " ";
+        const needed = Bun.stringWidth(spacer + word);
+
+        if (currentWidth > 0 && currentWidth + needed > usableWidth) {
+          flushLine();
+        }
+
+        appendToLine(`${currentWidth === 0 ? "" : " "}${word}`, segment.style);
+      }
+    }
+  }
+
+  if (currentLine.length > 0 || lines.length === 0) {
+    flushLine();
+  }
+
+  return lines;
+}
+
+export function wrapText(value: string, width: number): string[] {
+  return Bun.wrapAnsi(value, Math.max(1, width), { hard: false }).split("\n").map((line) => line.trim());
+}

package/src/tui/app.tsx

@@ -0,0 +1,243 @@
+import { Spinner } from "@inkjs/ui";
+import { Box, Text, useApp, useInput, useStdout } from "ink";
+import { useCallback, useEffect, useState } from "react";
+import { loadFocus, saveFocus } from "@/database/focus-repository.ts";
+import { dataDirectoryExists } from "@/database/index.ts";
+import { loadAttemptEvents, loadAttempts } from "@/database/progress-repository.ts";
+import { dataDirectory, displayPath } from "@/local-data/paths.ts";
+import { ensureLocalData } from "@/local-data/setup.ts";
+import { answerQuestion } from "@/practice/answer-question.ts";
+import {
+  emptyQueueMessage,
+  questionsToReview,
+  skipQuestion,
+  takeNextQuestion,
+  unansweredQuestions,
+  type QuestionQueue,
+} from "@/practice/question-queue.ts";
+import { loadPreferences, type ResultDetail, type ReviewPreferences } from "@/preferences/index.ts";
+import type { AnswerRecord, Attempt, AttemptEvent } from "@/progress/attempt.ts";
+import type { Focus } from "@/questions/focus.ts";
+import { defaultFocus } from "@/questions/focus.ts";
+import { findQuestion, loadQuestionBank, questionBankStatus } from "@/questions/local-bank.ts";
+import type { Question } from "@/questions/question.ts";
+import { useTerminalSize } from "@/tui/hooks/use-terminal-size.ts";
+import { DetailScreen } from "@/tui/screens/detail.tsx";
+import { FocusScreen } from "@/tui/screens/focus.tsx";
+import { HistoryScreen } from "@/tui/screens/history.tsx";
+import { PracticeScreen } from "@/tui/screens/practice.tsx";
+import { ResultScreen } from "@/tui/screens/result.tsx";
+import { SetupScreen } from "@/tui/screens/setup.tsx";
+import { SummaryScreen } from "@/tui/screens/summary.tsx";
+
+type View = "setup" | "loading" | "focus" | "practice" | "result" | "history" | "summary" | "detail" | "error";
+
+type StudyRecords = {
+  attempts: ReadonlyMap<string, Attempt>;
+  events: readonly AttemptEvent[];
+  reviewPreferences: ReviewPreferences;
+};
+
+type SessionEntry = (records: StudyRecords) => {
+  queue: QuestionQueue;
+  destination: "focus" | "question";
+  emptyNotice?: string;
+};
+
+const choosePracticeFocus: SessionEntry = () => ({
+  queue: unansweredQuestions(),
+  destination: "focus",
+});
+
+const beginReview: SessionEntry = ({ attempts, events, reviewPreferences }) => ({
+  queue: questionsToReview(attempts.values(), events, reviewPreferences),
+  destination: "question",
+  emptyNotice: `No questions are ready. Review requires ${reviewPreferences.minimumDays} days and ${reviewPreferences.minimumAnswersAfter} later answers.`,
+});
+
+export function PracticeSession() {
+  return <StudyShell enterSession={choosePracticeFocus} />;
+}
+
+export function ReviewSession() {
+  return <StudyShell enterSession={beginReview} />;
+}
+
+function StudyShell({ enterSession }: { enterSession: SessionEntry }) {
+  const { exit } = useApp();
+  const { stdout } = useStdout();
+  const terminal = useTerminalSize();
+  const [view, setView] = useState<View>("loading");
+  const [focus, setFocus] = useState<Focus>(defaultFocus);
+  const [attempts, setAttempts] = useState<Map<string, Attempt>>(() => new Map());
+  const [question, setQuestion] = useState<Question>();
+  const [detail, setDetail] = useState<{ question: Question; attempt: Attempt }>();
+  const [result, setResult] = useState<AnswerRecord>();
+  const [notice, setNotice] = useState<string>();
+  const [error, setError] = useState<string>();
+  const [resultDetail, setResultDetail] = useState<ResultDetail>("standard");
+  const [queue, setQueue] = useState<QuestionQueue>(() => unansweredQuestions());
+
+  const showNextQuestion = useCallback(async (
+    currentQueue = queue,
+    currentAttempts = attempts,
+    currentFocus = focus,
+  ) => {
+    setView("loading");
+    try {
+      const next = await takeNextQuestion(currentQueue, currentAttempts, currentFocus);
+      setQueue(next.queue);
+      if (!next.question) {
+        setNotice(emptyQueueMessage(next.queue));
+        setView("history");
+        return;
+      }
+      setQuestion(next.question);
+      setResult(undefined);
+      setView("practice");
+    } catch (cause) {
+      setError(message(cause));
+      setView("error");
+    }
+  }, [attempts, focus, queue]);
+
+  const initialize = useCallback(async () => {
+    setView("loading");
+    try {
+      await ensureLocalData();
+      const currentAttempts = loadAttempts();
+      const currentEvents = loadAttemptEvents();
+      const currentFocus = loadFocus();
+      const preferences = await loadPreferences();
+      setResultDetail(preferences.display.resultDetail);
+      await loadQuestionBank();
+      const status = await questionBankStatus();
+      setAttempts(currentAttempts);
+      setFocus(currentFocus);
+      setNotice(`${status.questions ?? 0} questions available offline.`);
+      const entry = enterSession({
+        attempts: currentAttempts,
+        events: currentEvents,
+        reviewPreferences: preferences.review,
+      });
+      setQueue(entry.queue);
+      if (entry.destination === "question") {
+        if (entry.queue.kind === "review" && !entry.queue.pendingIds.length) {
+          setNotice(entry.emptyNotice ?? "No questions are ready for review.");
+          setView("history");
+          return;
+        }
+        const first = await takeNextQuestion(entry.queue, currentAttempts, currentFocus);
+        setQueue(first.queue);
+        if (first.question) {
+          setQuestion(first.question);
+          setView("practice");
+        } else {
+          setNotice(emptyQueueMessage(first.queue));
+          setView("history");
+        }
+      } else {
+        setView("focus");
+      }
+    } catch (cause) {
+      setError(message(cause));
+      setView("error");
+    }
+  }, [enterSession]);
+
+  useEffect(() => {
+    void dataDirectoryExists()
+      .then((exists) => { if (exists) void initialize(); else setView("setup"); })
+      .catch((cause) => { setError(message(cause)); setView("error"); });
+  }, [initialize]);
+
+  useEffect(() => {
+    if (!stdout.isTTY) return;
+    stdout.write("\x1b[?1049h\x1b[?25l");
+    return () => { stdout.write("\x1b[?25h\x1b[?1049l"); };
+  }, [stdout]);
+
+  useInput((input) => {
+    if (input === "q") exit();
+    else if (input === "f" && view !== "setup") setView("focus");
+    else if (input === "h" && view !== "setup") setView("history");
+    else if (input === "s" && view !== "setup") setView("summary");
+    else if (input === "p" && view !== "setup") {
+      if (question && view !== "result") setView("practice");
+      else void showNextQuestion(unansweredQuestions());
+    }
+  });
+
+  const answer = async (choice: string, durationSeconds: number) => {
+    if (!question) return;
+    setView("loading");
+    try {
+      const answerResult = await answerQuestion({ attempts, question, answer: choice, durationSeconds });
+      setAttempts((current) => new Map(current).set(answerResult.attempt.questionId, answerResult.attempt));
+      setResult(answerResult);
+      setView("result");
+    } catch (cause) {
+      setError(message(cause));
+      setView("error");
+    }
+  };
+
+  const updateFocus = (next: Focus) => {
+    saveFocus(next);
+    setFocus(next);
+    setQuestion(undefined);
+    setQueue(unansweredQuestions());
+  };
+
+  const openAttempt = async (attempt: Attempt) => {
+    setView("loading");
+    const found = await findQuestion(attempt.questionId);
+    if (found) {
+      setDetail({ question: found, attempt });
+      setView("detail");
+    } else {
+      setNotice(`Question ${attempt.questionId} is no longer in the local bank.`);
+      setView("history");
+    }
+  };
+
+  let content;
+  if (view === "setup") {
+    content = <SetupScreen location={displayPath(dataDirectory)} onAccept={() => void initialize()} onDecline={exit} />;
+  } else if (view === "focus") {
+    content = <FocusScreen focus={focus} notice={notice} onChange={updateFocus} onStart={() => void showNextQuestion(unansweredQuestions())} />;
+  } else if (view === "practice" && question) {
+    content = (
+      <PracticeScreen
+        key={question.id}
+        question={question}
+        onAnswer={(choice, duration) => void answer(choice, duration)}
+        onSkip={() => void showNextQuestion(skipQuestion(queue, question.id))}
+      />
+    );
+  } else if (view === "result" && question && result) {
+    content = <ResultScreen question={question} result={result} resultDetail={resultDetail} onNext={() => void showNextQuestion()} />;
+  } else if (view === "history") {
+    content = <HistoryScreen attempts={attempts.values()} notice={notice} onOpen={(attempt) => void openAttempt(attempt)} />;
+  } else if (view === "summary") {
+    content = <SummaryScreen attempts={attempts.values()} />;
+  } else if (view === "detail" && detail) {
+    content = <DetailScreen question={detail.question} attempt={detail.attempt} onBack={() => setView("history")} />;
+  } else if (view === "error") {
+    content = (
+      <Box flexDirection="column">
+        <Text bold color="red">Something went wrong.</Text>
+        <Text>{error}</Text>
+        <Text color="gray">Press q to quit.</Text>
+      </Box>
+    );
+  } else {
+    content = <Spinner label="Loading local SAT data" />;
+  }
+
+  return <Box width={terminal.width} height={terminal.height}>{content}</Box>;
+}
+
+function message(value: unknown): string {
+  return value instanceof Error ? value.message : String(value);
+}

package/src/tui/components/chrome.tsx

@@ -0,0 +1,39 @@
+import { Box, Text, useStdout } from "ink";
+import type { ReactNode } from "react";
+
+const globalShortcuts = "f focus · h history · s stats · p practice · q quit";
+
+type ScreenProps = {
+  title: string;
+  detail?: ReactNode;
+  children: ReactNode;
+  footer?: string;
+  globalNavigation?: boolean;
+};
+
+export function HorizontalRule({ width }: { width: number }) {
+  return <Text color="gray">{"─".repeat(Math.max(1, width - 1))}</Text>;
+}
+
+export function PaneTitle({ active, children }: { active: boolean; children: string }) {
+  return <Text bold color="cyan" underline={active}>{children}</Text>;
+}
+
+export function Screen({ title, detail, children, footer, globalNavigation = true }: ScreenProps) {
+  const { stdout } = useStdout();
+  const shortcuts = [footer, globalNavigation ? globalShortcuts : undefined].filter(Boolean).join(" · ");
+  const renderedDetail = typeof detail === "string"
+    ? <Text color="gray">{detail}</Text>
+    : detail ?? <Text color="gray">offline</Text>;
+  return (
+    <Box flexDirection="column" height="100%">
+      <Box justifyContent="space-between">
+        <Text bold color="cyan">saterminal :: {title}</Text>
+        {renderedDetail}
+      </Box>
+      <Box flexGrow={1} flexDirection="column" paddingTop={1}>{children}</Box>
+      <HorizontalRule width={stdout.columns ?? 80} />
+      <Text color="gray">{shortcuts}</Text>
+    </Box>
+  );
+}

package/src/tui/components/question-content.tsx

@@ -0,0 +1,91 @@
+import { Box, Text } from "ink";
+import { htmlToText } from "@/text/html.ts";
+import { wrapText } from "@/text/wrap.ts";
+import type { Question } from "@/questions/question.ts";
+
+export type ChoiceLine = {
+  text: string;
+  choiceIndex?: number;
+};
+
+export type ChoiceRange = {
+  start: number;
+  end: number;
+};
+
+type ViewportProps = {
+  question: Question;
+  width: number;
+  height: number;
+  scroll?: number;
+};
+
+type AnswerChoicesProps = ViewportProps & {
+  selected: number;
+};
+
+export function QuestionContent({ question, width, height, scroll = 0 }: ViewportProps) {
+  const passage = htmlToText(question.passage ?? "");
+  const prompt = htmlToText(question.prompt);
+  const lines = [
+    ...(passage ? wrapText(passage, width) : []),
+    ...(passage ? [""] : []),
+    ...wrapText(prompt, width),
+  ];
+  const maximum = Math.max(0, lines.length - height);
+  const start = Math.max(0, Math.min(scroll, maximum));
+  return <Text>{lines.slice(start, start + height).join("\n")}</Text>;
+}
+
+export function AnswerChoices({ question, selected, width, height, scroll = 0 }: AnswerChoicesProps) {
+  const { lines } = answerChoiceLayout(question, selected, width);
+  const start = clampedScroll(scroll, lines.length, height);
+  const visible = lines.slice(start, start + height);
+  return (
+    <Box flexDirection="column">
+      {visible.map((entry, index) => (
+        <Text key={`${start}-${index}`} color={entry.choiceIndex === selected ? "yellow" : undefined} bold={entry.choiceIndex === selected}>
+          {entry.text}
+        </Text>
+      ))}
+    </Box>
+  );
+}
+
+export function answerChoiceLayout(question: Question, selected: number | undefined, width: number): { lines: ChoiceLine[]; ranges: ChoiceRange[] } {
+  const markerWidth = Math.max(...question.choices.map((choice) => Bun.stringWidth(`  ${choice.key}.`)));
+  const choices = question.choices.map((choice, index) => ({
+    index,
+    lines: hangingChoiceLines(choice.key, choice.content, index === selected, markerWidth, width),
+  }));
+  const ranges: ChoiceRange[] = [];
+  let cursor = 0;
+  const lines = choices.flatMap((choice) => {
+    ranges.push({ start: cursor, end: cursor + choice.lines.length });
+    const rendered = [
+      ...choice.lines.map((text) => ({ text, choiceIndex: choice.index })),
+      ...(choice.index === choices.length - 1 ? [] : [{ text: " " }]),
+    ];
+    cursor += rendered.length;
+    return rendered;
+  });
+  return { lines, ranges };
+}
+
+export function clampedScroll(scroll: number, lineCount: number, height: number): number {
+  return Math.max(0, Math.min(scroll, Math.max(0, lineCount - height)));
+}
+
+export function revealRange(scroll: number, height: number, range: ChoiceRange | undefined): number {
+  if (!range) return scroll;
+  if (range.start < scroll) return range.start;
+  if (range.end > scroll + height) return Math.max(0, range.end - height);
+  return scroll;
+}
+
+function hangingChoiceLines(key: string, content: string, selected: boolean, markerWidth: number, width: number): string[] {
+  const marker = `${selected ? ">" : " "} ${key}.`.padEnd(markerWidth);
+  const indent = " ".repeat(markerWidth + 1);
+  return wrapText(htmlToText(content).replace(/\n+/g, " "), Math.max(10, width - indent.length))
+    .map((line, index) => index === 0 ? `${marker} ${line}` : `${indent}${line}`);
+}

package/src/tui/hooks/use-terminal-size.ts

@@ -0,0 +1,16 @@
+import { useStdout } from "ink";
+import { useEffect, useState } from "react";
+
+export type TerminalSize = { width: number; height: number };
+
+export function useTerminalSize(): TerminalSize {
+  const { stdout } = useStdout();
+  const read = () => ({ width: stdout.columns ?? 80, height: stdout.rows ?? 24 });
+  const [size, setSize] = useState<TerminalSize>(read);
+  useEffect(() => {
+    const resize = () => setSize(read());
+    stdout.on("resize", resize);
+    return () => { stdout.off("resize", resize); };
+  }, [stdout]);
+  return size;
+}

package/src/tui/screens/detail.tsx

@@ -0,0 +1,20 @@
+import { Text, useInput } from "ink";
+import { htmlToText } from "@/text/html.ts";
+import type { Question } from "@/questions/question.ts";
+import type { Attempt } from "@/progress/attempt.ts";
+import { Screen } from "@/tui/components/chrome.tsx";
+
+export function DetailScreen({ question, attempt, onBack }: { question: Question; attempt: Attempt; onBack: () => void }) {
+  useInput((_input, key) => { if (key.escape) onBack(); });
+  return (
+    <Screen title="question details" detail={attempt.outcome} footer="esc back">
+      <Text bold color={attempt.outcome === "incorrect" ? "red" : attempt.outcome === "corrected" ? "yellow" : "green"}>{attempt.outcome.toUpperCase()}</Text>
+      <Text color="gray">{question.domain} · {question.skill} · difficulty {question.difficulty} · {question.id}</Text>
+      <Text> </Text>
+      <Text bold>Correct answer: <Text color="green">{question.correctAnswers.join(", ")}</Text></Text>
+      <Text> </Text>
+      <Text bold color="cyan">Explanation</Text>
+      <Text>{htmlToText(question.explanation ?? "No explanation is available.")}</Text>
+    </Screen>
+  );
+}