saterminal 0.2.0 → 0.3.0

package/src/tui/question.ts

@@ -1,8 +1,7 @@
 import { spawn } from "node:child_process";
-import { hasHtmlTable, htmlToText, parseHtmlSegments, wrapSegments } from "../text.ts";
+import { hasHtmlTable, parseHtmlSegments, wrapSegments } from "../text.ts";
 import type { PracticeQuestion, QuestionDetail } from "../types.ts";
-import { lineAt, printWrappedAt, renderStyledLine, term } from "./terminal.ts";
-import type { DisplayRow, PaneLayout } from "./types.ts";
+import type { DisplayRow } from "./types.ts";
 
 export function answerKeys(question?: PracticeQuestion): string[] {
   return Object.keys(question?.detail.answerOptions ?? {}).sort();
@@ -17,10 +16,6 @@ export function questionNeedsExternalDisplay(detail: QuestionDetail): boolean {
   );
 }
 
-export function questionPageSize(): number {
-  return Math.max(1, term.height - 6);
-}
-
 export function questionRows(detail: QuestionDetail, width: number): DisplayRow[] {
   const rows: DisplayRow[] = [];
   const stimulus = wrapSegments(parseHtmlSegments(detail.stimulus), width).map((segments) => ({ segments }));
@@ -34,59 +29,6 @@ export function questionRows(detail: QuestionDetail, width: number): DisplayRow[
   return rows;
 }
 
-export function renderQuestionPane(detail: QuestionDetail, x: number, width: number, scroll: number): void {
-  const rows = questionRows(detail, width);
-  const maxRows = questionPageSize();
-  const maxScroll = Math.max(0, rows.length - maxRows);
-  const start = Math.min(scroll, maxScroll);
-
-  for (const [offset, row] of rows.slice(start, start + maxRows).entries()) {
-    const y = 4 + offset;
-    renderStyledLine(x, y, width, row.segments, row.bold);
-  }
-
-  if (start > 0) {
-    lineAt(x + width - 4, 4, 4, "^");
-  }
-  if (start < maxScroll) {
-    lineAt(x + width - 4, term.height - 3, 4, "v");
-  }
-}
-
-export function renderUnsupportedQuestion(question: PracticeQuestion, panes: PaneLayout): void {
-  const { meta, detail } = question;
-  const appUrl = practiceQuestionUrl(question);
-  const apiUrl = practiceQuestionApiUrl(question);
-  let y = 4;
-
-  lineAt(panes.leftX, y++, panes.leftWidth, "This question contains a table.");
-  y++;
-  y = printWrappedAt(
-    "The terminal renderer cannot display this table accurately enough to answer the question here.",
-    panes.leftX,
-    y,
-    panes.leftWidth,
-    term.height - 3,
-  );
-  y++;
-  y = printWrappedAt("Open it in PracticeSAT, search this question ID, then skip it in this app.", panes.leftX, y, panes.leftWidth, term.height - 3);
-  y++;
-  y = printWrappedAt(`Question ID: ${meta.questionId}`, panes.leftX, y, panes.leftWidth, term.height - 3);
-  y++;
-  y = printWrappedAt(appUrl, panes.leftX, y, panes.leftWidth, term.height - 3);
-  y++;
-  y = printWrappedAt(`API fallback: ${apiUrl}`, panes.leftX, y, panes.leftWidth, term.height - 3);
-
-  let rightY = 4;
-  lineAt(panes.rightX, rightY++, panes.rightWidth, `${meta.primary_class_cd} | ${meta.skill_cd}`);
-  lineAt(panes.rightX, rightY++, panes.rightWidth, `difficulty ${meta.difficulty} | ${meta.questionId}`);
-  rightY++;
-  lineAt(panes.rightX, rightY++, panes.rightWidth, "o open externally");
-  lineAt(panes.rightX, rightY++, panes.rightWidth, "n/x/enter skip");
-  rightY++;
-  printWrappedAt(htmlToText(detail.stem), panes.rightX, rightY, panes.rightWidth, term.height - 3, true);
-}
-
 export function practiceQuestionUrl(question: PracticeQuestion): string {
   return `https://practicesat.vercel.app/question?questionId=${encodeURIComponent(question.meta.questionId)}`;
 }

package/src/tui/render.ts

@@ -2,6 +2,8 @@ import { buildSummaryRows, displayStateDir, stateDir } from "../state.ts";
 import { focusSummary } from "../focus.ts";
 import { htmlToText, wrapText } from "../text.ts";
 import type { TextSegment } from "../text.ts";
+import { progressBarText } from "../progress.ts";
+import { Frame, FrameRenderer, TerminalFrameOutput, truncate, type TextAttr } from "./frame.ts";
 import { focusGrid, normalizeFocusGridPosition, type FocusGridColumn, type FocusGridRow } from "./focus-grid.ts";
 import { historyRows } from "./history.ts";
 import {
@@ -11,64 +13,59 @@ import {
   questionRows,
 } from "./question.ts";
 import { elapsedQuestionSeconds, formatElapsed, timerStatus } from "./timer.ts";
-import { terminalSize, tk, type TkDocument } from "./kit.ts";
+import { term, terminalSize } from "./kit.ts";
 import { PANE_BODY_Y, PANE_HEADER_Y, paneLayout, paneViewportHeight } from "./layout.ts";
 import { detailPaneRows, practiceAnswerPaneRows, reviewPaneRows, type PaneTextRow } from "./pane-content.ts";
 import type { AppState, PaneLayout } from "./types.ts";
 import type { Attempt, Outcome, QuestionMeta, SummaryRow } from "../types.ts";
 import { clampScroll, maxScroll, type PaneViewport } from "./viewport.ts";
 
-type TextAttr = Record<string, unknown>;
-
-export function createDocument(): TkDocument {
-  return new tk.Document({
-    eventSource: tk.terminal,
-    outputDst: tk.terminal,
-    backgroundAttr: {},
-  });
+export function createFrameRenderer(): FrameRenderer {
+  return new FrameRenderer(new TerminalFrameOutput(term));
 }
 
-export function render(doc: TkDocument, state: AppState): void {
-  doc.clear();
+export function render(renderer: FrameRenderer, state: AppState): void {
+  const { width, height } = terminalSize();
+  const frame = new Frame(width, height);
 
   if (state.view === "practice" && state.timerPaused) {
-    renderPaused(doc);
-    footer(doc, state);
-    doc.draw();
+    renderPaused(frame);
+    footer(frame, state);
+    renderer.draw(frame);
     return;
   }
 
-  header(doc, state);
+  header(frame, state);
 
   if (state.view === "loading") {
-    renderLoading(doc);
+    renderLoading(frame);
   } else if (state.view === "setup") {
-    renderSetup(doc);
+    renderSetup(frame);
   } else if (state.view === "focus") {
-    renderFocus(doc, state);
+    renderFocus(frame, state);
   } else if (state.view === "practice") {
-    renderPractice(doc, state);
+    renderPractice(frame, state);
   } else if (state.view === "review") {
-    renderReview(doc, state);
+    renderReview(frame, state);
   } else if (state.view === "history") {
-    renderHistory(doc, state);
+    renderHistory(frame, state);
   } else if (state.view === "summary") {
-    renderSummary(doc, state);
+    renderSummary(frame, state);
   } else if (state.view === "detail") {
-    renderDetail(doc, state);
+    renderDetail(frame, state);
   } else if (state.view === "error") {
-    renderError(doc, state);
+    renderError(frame, state);
   }
 
-  footer(doc, state);
-  doc.draw();
+  footer(frame, state);
+  renderer.draw(frame);
 }
 
-function renderLoading(doc: TkDocument): void {
+function renderLoading(doc: Frame): void {
   text(doc, 0, 3, "Loading...");
 }
 
-function renderSetup(doc: TkDocument): void {
+function renderSetup(doc: Frame): void {
   const { width } = terminalSize();
   const location = displayStateDir(stateDir);
 
@@ -78,22 +75,23 @@ function renderSetup(doc: TkDocument): void {
   text(doc, 0, 9, location, { color: "cyan" }, width);
 }
 
-function renderPaused(doc: TkDocument): void {
+function renderPaused(doc: Frame): void {
   const { width, height } = terminalSize();
   const label = "PAUSED";
   text(doc, Math.max(0, Math.floor((width - label.length) / 2)), Math.max(0, Math.floor(height / 2)), label, { bold: true });
 }
 
-function header(doc: TkDocument, state: AppState): void {
+function header(doc: Frame, state: AppState): void {
   const { width } = terminalSize();
   const answered = state.attempts.size;
+  const mode = state.reviewMode ? "review queue" : "reading/writing";
   const timer = state.timerHidden ? "" : `  time ${formatElapsed(elapsedQuestionSeconds(state))}${timerStatus(state)}`;
   text(doc, 0, 0, "sat", { bold: true });
-  text(doc, 7, 0, `reading/writing  answered ${answered}${timer}`, { color: "gray" }, width - 7);
+  text(doc, 7, 0, `${mode}  answered ${answered}${timer}`, { color: "gray" }, width - 7);
   text(doc, 0, 1, "-".repeat(width), { color: "gray" }, width);
 }
 
-function footer(doc: TkDocument, state: AppState): void {
+function footer(doc: Frame, state: AppState): void {
   const { width, height } = terminalSize();
   const controls = state.view === "setup"
     ? "y allow | n decline | q quit"
@@ -115,7 +113,7 @@ function footer(doc: TkDocument, state: AppState): void {
   text(doc, 0, Math.max(0, height - 1), controls, { color: "gray" }, width);
 }
 
-function renderFocus(doc: TkDocument, state: AppState): void {
+function renderFocus(doc: Frame, state: AppState): void {
   const { width } = terminalSize();
   const columns = focusGrid(state.focus);
   const position = normalizeFocusGridPosition(columns, { column: state.focusColumn, row: state.focusRow });
@@ -131,7 +129,7 @@ function renderFocus(doc: TkDocument, state: AppState): void {
   renderDomainColumns(doc, columns.slice(1), position.column - 1, position.row);
 }
 
-function renderDifficultyColumn(doc: TkDocument, column: FocusGridColumn, selectedRow: number): void {
+function renderDifficultyColumn(doc: Frame, column: FocusGridColumn, selectedRow: number): void {
   text(doc, 0, 6, column.title, { color: "cyan", bold: true });
 
   for (const [index, row] of column.rows.entries()) {
@@ -140,7 +138,7 @@ function renderDifficultyColumn(doc: TkDocument, column: FocusGridColumn, select
   }
 }
 
-function renderDomainColumns(doc: TkDocument, columns: FocusGridColumn[], selectedColumn: number, selectedRow: number): void {
+function renderDomainColumns(doc: Frame, columns: FocusGridColumn[], selectedColumn: number, selectedRow: number): void {
   const { width } = terminalSize();
   const startY = 11;
   const gap = 4;
@@ -170,7 +168,7 @@ function focusOptionText(row: FocusGridRow, focused: boolean): string {
 }
 
 function writeFocusOption(
-  doc: TkDocument,
+  doc: Frame,
   x: number,
   y: number,
   value: string,
@@ -182,7 +180,7 @@ function writeFocusOption(
   text(doc, x, y, value, attr, width);
 }
 
-function renderPractice(doc: TkDocument, state: AppState): void {
+function renderPractice(doc: Frame, state: AppState): void {
   if (!state.question) {
     return;
   }
@@ -205,7 +203,7 @@ function renderPractice(doc: TkDocument, state: AppState): void {
   renderPaneRows(doc, answerContent, panes.rightX, panes.rightWidth, answerViewport, state.activePane === "answers");
 }
 
-function renderReview(doc: TkDocument, state: AppState): void {
+function renderReview(doc: Frame, state: AppState): void {
   if (!state.question) {
     return;
   }
@@ -227,11 +225,14 @@ function renderReview(doc: TkDocument, state: AppState): void {
   renderPaneRows(doc, reviewContent, panes.rightX, panes.rightWidth, answerViewport, state.activePane === "answers");
 }
 
-function renderHistory(doc: TkDocument, state: AppState): void {
+function renderHistory(doc: Frame, state: AppState): void {
   const attempts = historyRows(state);
   const { width, height } = terminalSize();
   let y = 3;
   text(doc, 0, y++, "answered questions", { color: "cyan", bold: true });
+  if (state.notice) {
+    text(doc, 0, y++, state.notice, { color: "yellow" }, width);
+  }
   y++;
 
   if (attempts.length === 0) {
@@ -239,7 +240,7 @@ function renderHistory(doc: TkDocument, state: AppState): void {
     return;
   }
 
-  text(doc, 0, y++, "  question   status     updated", { color: "gray" }, width);
+  text(doc, 0, y++, "  question   status     skill  updated", { color: "gray" }, width);
 
   const visibleRows = Math.max(1, height - 8);
   const start = Math.max(0, Math.min(state.historyIndex - visibleRows + 1, attempts.length - visibleRows));
@@ -249,7 +250,7 @@ function renderHistory(doc: TkDocument, state: AppState): void {
   }
 }
 
-function renderSummary(doc: TkDocument, state: AppState): void {
+function renderSummary(doc: Frame, state: AppState): void {
   const { width } = terminalSize();
   let y = 3;
   text(doc, 0, y++, "stats summary", { color: "cyan", bold: true });
@@ -260,7 +261,7 @@ function renderSummary(doc: TkDocument, state: AppState): void {
   }
 }
 
-function renderDetail(doc: TkDocument, state: AppState): void {
+function renderDetail(doc: Frame, state: AppState): void {
   const panes = paneLayout();
   if (!state.detailQuestion) {
     text(doc, 0, 3, "Could not fetch details for this question.");
@@ -286,12 +287,12 @@ function renderDetail(doc: TkDocument, state: AppState): void {
   renderPaneRows(doc, detailContent, panes.rightX, panes.rightWidth, answerViewport, state.activePane === "answers");
 }
 
-function renderError(doc: TkDocument, state: AppState): void {
+function renderError(doc: Frame, state: AppState): void {
   text(doc, 0, 3, "Something went wrong.", { bold: true, color: "red" });
   printWrappedAt(doc, state.error ?? "Unknown error.", 0, 5, terminalSize().width - 1, terminalSize().height - 4);
 }
 
-function renderUnsupportedQuestion(doc: TkDocument, state: AppState, panes: PaneLayout): void {
+function renderUnsupportedQuestion(doc: Frame, state: AppState, panes: PaneLayout): void {
   if (!state.question) {
     return;
   }
@@ -351,7 +352,7 @@ function renderUnsupportedQuestion(doc: TkDocument, state: AppState, panes: Pane
 }
 
 function renderPaneHeaders(
-  doc: TkDocument,
+  doc: Frame,
   panes: PaneLayout,
   state: AppState,
   questionViewport: PaneViewport,
@@ -362,7 +363,7 @@ function renderPaneHeaders(
   renderPaneHeader(doc, panes.rightX, panes.rightWidth, rightLabel, state.activePane === "answers", answerViewport);
 }
 
-function renderPaneHeader(doc: TkDocument, x: number, width: number, label: string, active: boolean, viewport: PaneViewport): void {
+function renderPaneHeader(doc: Frame, x: number, width: number, label: string, active: boolean, viewport: PaneViewport): void {
   const attr = active ? { color: "cyan", underline: true } : { color: "gray" };
   text(doc, x, PANE_HEADER_Y, label, attr, width);
 
@@ -376,7 +377,7 @@ function renderPaneHeader(doc: TkDocument, x: number, width: number, label: stri
 }
 
 function renderQuestionRows(
-  doc: TkDocument,
+  doc: Frame,
   rows: ReturnType<typeof questionRows>,
   x: number,
   width: number,
@@ -390,7 +391,7 @@ function renderQuestionRows(
   renderScrollGutter(doc, x, width, viewport, active);
 }
 
-function renderPaneRows(doc: TkDocument, rows: PaneTextRow[], x: number, width: number, viewport: PaneViewport, active: boolean): void {
+function renderPaneRows(doc: Frame, rows: PaneTextRow[], x: number, width: number, viewport: PaneViewport, active: boolean): void {
   for (const [offset, row] of rows.slice(viewport.scroll, viewport.scroll + viewport.height).entries()) {
     text(doc, x, PANE_BODY_Y + offset, row.text, paneRowAttr(row), width);
   }
@@ -398,7 +399,7 @@ function renderPaneRows(doc: TkDocument, rows: PaneTextRow[], x: number, width:
   renderScrollGutter(doc, x, width, viewport, active);
 }
 
-function renderScrollGutter(doc: TkDocument, x: number, width: number, viewport: PaneViewport, active: boolean): void {
+function renderScrollGutter(doc: Frame, x: number, width: number, viewport: PaneViewport, active: boolean): void {
   const scrollX = Math.min(terminalSize().width - 1, x + width);
   const attr = active ? { color: "cyan" } : { color: "gray" };
   if (viewport.scroll > 0) {
@@ -436,7 +437,7 @@ function paneRowAttr(row: PaneTextRow): TextAttr {
   return attr;
 }
 
-function renderStyledLine(doc: TkDocument, x: number, y: number, width: number, segments: TextSegment[], forceBold = false): void {
+function renderStyledLine(doc: Frame, x: number, y: number, width: number, segments: TextSegment[], forceBold = false): void {
   let col = 0;
   for (const segment of segments) {
     if (col >= width) {
@@ -458,7 +459,7 @@ function renderStyledLine(doc: TkDocument, x: number, y: number, width: number,
 }
 
 function printWrappedAt(
-  doc: TkDocument,
+  doc: Frame,
   value: string | undefined,
   x: number,
   y: number,
@@ -477,15 +478,16 @@ function printWrappedAt(
   return y;
 }
 
-function renderHistoryRow(doc: TkDocument, attempt: Attempt, selected: boolean, y: number, width: number): void {
+function renderHistoryRow(doc: Frame, attempt: Attempt, selected: boolean, y: number, width: number): void {
   const strong = selected ? { bold: true } : {};
   text(doc, 0, y, selected ? ">" : " ", selected ? { color: "yellow", bold: true } : { color: "gray" }, 1);
   text(doc, 2, y, attempt.question_id, { color: selected ? "yellow" : "cyan", ...strong }, 10);
   text(doc, 13, y, attempt.outcome, { ...outcomeAttr(attempt.outcome), ...strong }, 9);
-  text(doc, 24, y, attempt.updated_at, { color: selected ? "yellow" : "gray", ...strong }, width - 24);
+  text(doc, 24, y, attempt.skill ?? "-", { color: selected ? "yellow" : "green", ...strong }, 5);
+  text(doc, 31, y, shortTimestamp(attempt.updated_at), { color: selected ? "yellow" : "gray", ...strong }, width - 31);
 }
 
-function renderSummaryRow(doc: TkDocument, row: SummaryRow, y: number, width: number): void {
+function renderSummaryRow(doc: Frame, row: SummaryRow, y: number, width: number): void {
   const value = summaryValue(row);
   const attr = summaryAttr(row);
 
@@ -499,7 +501,7 @@ function renderSummaryRow(doc: TkDocument, row: SummaryRow, y: number, width: nu
 }
 
 function renderQuestionMetadata(
-  doc: TkDocument,
+  doc: Frame,
   meta: QuestionMeta,
   attempt: Attempt | undefined,
   x: number,
@@ -525,6 +527,19 @@ function formatSkill(meta: QuestionMeta): string {
   return meta.skill_desc ? `${meta.skill_cd}  ${meta.skill_desc}` : meta.skill_cd;
 }
 
+function shortTimestamp(value: string): string {
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) {
+    return value;
+  }
+
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  const hour = String(date.getHours()).padStart(2, "0");
+  const minute = String(date.getMinutes()).padStart(2, "0");
+  return `${month}/${day} ${hour}:${minute}`;
+}
+
 function outcomeAttr(outcome: Outcome): TextAttr {
   if (outcome === "correct") {
     return { color: "green" };
@@ -584,9 +599,7 @@ function summaryAttr(row: SummaryRow): TextAttr {
 
 function accuracyBar(value: string, width: number): string {
   const barWidth = Math.max(8, width - 2);
-  const ratio = readRatio(value);
-  const filled = Math.round(ratio * barWidth);
-  return `[${"#".repeat(filled)}${"-".repeat(barWidth - filled)}]`;
+  return `[${progressBarText(readRatio(value), barWidth)}]`;
 }
 
 function readRatio(value: string): number {
@@ -597,34 +610,12 @@ function readRatio(value: string): number {
   return Math.min(1, Math.max(0, ratio));
 }
 
-function text(doc: TkDocument, x: number, y: number, value: string, attr: TextAttr = {}, width = terminalSize().width - x): void {
-  if (y < 0 || y >= terminalSize().height || width <= 0) {
+function text(doc: Frame, x: number, y: number, value: string, attr: TextAttr = {}, width = doc.width - x): void {
+  if (y < 0 || y >= doc.height || width <= 0) {
     return;
   }
 
-  const content = truncate(value, width);
-  if (!content) {
-    return;
-  }
-
-  new tk.Text({
-    parent: doc,
-    x,
-    y,
-    content,
-    attr,
-    noDraw: true,
-  });
-}
-
-function truncate(value: string, width: number): string {
-  if (value.length <= width) {
-    return value;
-  }
-  if (width <= 1) {
-    return value.slice(0, width);
-  }
-  return `${value.slice(0, width - 1)}…`;
+  doc.writeText(x, y, value, attr, width);
 }
 
 function practiceControls(state: AppState): string {

package/src/tui/types.ts

@@ -8,6 +8,8 @@ export type AppState = {
   attempts: Map<string, Attempt>;
   skippedIds: Set<string>;
   nextQuestion?: Promise<PracticeQuestion | undefined>;
+  reviewMode?: boolean;
+  reviewQuestionIds?: string[];
   focus: Focus;
   focusIndex: number;
   focusColumn: number;
@@ -26,6 +28,7 @@ export type AppState = {
   lastCorrect?: boolean;
   detailQuestion?: PracticeQuestion;
   historyIndex: number;
+  notice?: string;
   error?: string;
 };
 

package/src/types/terminal-kit.d.ts

@@ -19,6 +19,9 @@ declare module "terminal-kit" {
     underline: Terminal;
     inverse: Terminal;
     defaultColor: Terminal;
+    italic: Terminal;
+    styleReset(): Terminal;
+    eraseLineAfter(): Terminal;
     fullscreen(enabled: boolean): void;
     hideCursor(enabled?: boolean): void;
     grabInput(enabled?: boolean): void;

package/src/types.ts

@@ -5,6 +5,23 @@ export type Attempt = {
   outcome: Outcome;
   updated_at: string;
   elapsed_seconds: number;
+  difficulty?: string;
+  domain?: string;
+  domain_desc?: string;
+  skill?: string;
+  skill_desc?: string;
+};
+
+export type AttemptEvent = {
+  question_id: string;
+  correct: boolean;
+  answered_at: string;
+  elapsed_seconds: number;
+  difficulty: string;
+  domain: string;
+  domain_desc?: string;
+  skill: string;
+  skill_desc?: string;
 };
 
 export type SummaryRow = {