pi-fluency 0.1.3 → 0.2.0

package/extensions/pi-fluency/overlay.ts

@@ -11,10 +11,20 @@ import {
   type TUI,
   wrapTextWithAnsi,
 } from "@earendil-works/pi-tui";
-import { computeFluencyAnalytics, type FluencyAnalytics, type RuleAnalytics } from "./analytics.js";
+import {
+  computeFluencyAnalytics,
+  resolvePracticeTargets,
+  type FluencyAnalytics,
+  type RuleAnalytics,
+} from "./analytics.js";
 import { compactDiffFallback, renderCompactDiff } from "./diff.js";
 import type { FluencyStore } from "./store.js";
-import type { ReviewPattern } from "./types.js";
+import type {
+  PracticeSettings,
+  PracticeTarget,
+  ResolvedPracticeTarget,
+  ReviewPattern,
+} from "./types.js";
 import {
   ERRANT_CATEGORY_LABELS,
   errantCategory,
@@ -31,12 +41,20 @@ type SelectionKeybinding =
 export type IgnoreTarget = { kind: "pattern"; value: string } | { kind: "category"; value: ErrantCategory };
 type MaybePromise = void | Promise<void>;
 
+export interface PracticeOverlayState {
+  settings: PracticeSettings;
+  targets: ResolvedPracticeTarget[];
+  sessionSnoozed: boolean;
+  now: number;
+}
+
 export interface FluencyOverlayOptions {
   tui: Pick<TUI, "requestRender"> & { terminal?: { readonly rows: number } };
   theme: Pick<Theme, "fg">;
   keybindings: { matches(data: string, keybinding: SelectionKeybinding): boolean };
   patterns(): ReviewPattern[];
   stats(): FluencyAnalytics;
+  practice?(): PracticeOverlayState;
   initialView?: FluencyView;
   ignoredBy?(pattern: ReviewPattern): IgnoreTarget[];
   selectIgnore?(title: string, options: string[]): Promise<string | undefined>;
@@ -45,6 +63,8 @@ export interface FluencyOverlayOptions {
   ignorePattern(patternKey: string, pattern: ReviewPattern): MaybePromise;
   ignoreCategory(category: ErrantCategory, pattern: ReviewPattern): MaybePromise;
   restoreIgnored(targets: IgnoreTarget[], pattern: ReviewPattern): MaybePromise;
+  activatePractice?(target?: PracticeTarget): MaybePromise;
+  setPracticeTarget?(target: PracticeTarget, selected: boolean): MaybePromise;
   close(): void;
   viewChanged?(view: FluencyView): void;
   mutationError?(error: unknown): void;
@@ -57,6 +77,20 @@ const HEADER_LINES = 2;
 const FOOTER_LINES = 3;
 const BORDER_LINES = 2;
 const DETAIL_SCROLL_STEP = 5;
+const MAX_ERROR_LENGTH = 200;
+
+interface StatsRuleRow {
+  rowKey: string;
+  target: PracticeTarget;
+  selected: boolean;
+  paused: boolean;
+  section: "recurring" | "historical" | "paused";
+}
+
+interface StatsBody {
+  lines: string[];
+  focusedRange?: { start: number; end: number };
+}
 
 interface SourceSegment {
   text: string;
@@ -141,7 +175,10 @@ export function wrapCompactDiff(lines: string[], marker: string, width: number):
 
 function sanitizedError(error: unknown): string {
   const message = error instanceof Error ? error.message : String(error);
-  return message.replace(/[\u0000-\u001f\u007f-\u009f]/g, "?").trim() || "Unknown error";
+  const sanitized = message.replace(/[\u0000-\u001f\u007f-\u009f]/g, "?").trim() || "Unknown error";
+  return sanitized.length <= MAX_ERROR_LENGTH
+    ? sanitized
+    : `${sanitized.slice(0, MAX_ERROR_LENGTH - 1)}…`;
 }
 
 /** Disposable keyboard-first inbox used inside Pi custom overlay lifecycle. */
@@ -153,6 +190,9 @@ export class FluencyOverlay implements Component {
   private disposed = false;
   private loadError: string | undefined;
   private actionError: string | undefined;
+  private statsRuleIndex = 0;
+  private statsRuleFocusKey: string | undefined;
+  private statsRulePending = false;
   private callbacks: FluencyOverlayOptions | undefined;
 
   constructor(options: FluencyOverlayOptions) {
@@ -236,15 +276,133 @@ export class FluencyOverlay implements Component {
     this.changed();
   }
 
+  private getPractice(): PracticeOverlayState | undefined {
+    try {
+      const practice = this.callbacks?.practice?.();
+      this.loadError = undefined;
+      return practice;
+    } catch (error) {
+      this.loadError = sanitizedError(error);
+      return undefined;
+    }
+  }
+
+  private statsRuleRows(stats: FluencyAnalytics, practice: PracticeOverlayState): StatsRuleRow[] {
+    const selectedByExplanation = new Map(practice.targets.map((target) => [target.explanation, target]));
+    const recurring: StatsRuleRow[] = stats.rules.flatMap((rule) => {
+      const selected = selectedByExplanation.get(rule.explanation);
+      if (selected && !selected.coachingEnabled) return [];
+      return [{
+        rowKey: rule.rowKey,
+        target: { explanation: rule.explanation, memberPatternKeys: [...rule.memberPatternKeys] },
+        selected: selected !== undefined,
+        paused: false,
+        section: "recurring" as const,
+      }];
+    });
+    const recurringExplanations = new Set(stats.rules.map((rule) => rule.explanation));
+    const historical: StatsRuleRow[] = practice.targets
+      .filter((target) => target.coachingEnabled && !recurringExplanations.has(target.explanation))
+      .map((target) => ({
+        rowKey: target.rowKey,
+        target: { explanation: target.explanation, memberPatternKeys: [...target.memberPatternKeys] },
+        selected: true,
+        paused: false,
+        section: "historical" as const,
+      }));
+    const paused: StatsRuleRow[] = practice.targets
+      .filter((target) => !target.coachingEnabled)
+      .map((target) => ({
+        rowKey: target.rowKey,
+        target: { explanation: target.explanation, memberPatternKeys: [...target.memberPatternKeys] },
+        selected: true,
+        paused: true,
+        section: "paused" as const,
+      }));
+    const rows = [...recurring, ...historical, ...paused];
+    if (this.statsRuleFocusKey) {
+      const index = rows.findIndex((row) => row.rowKey === this.statsRuleFocusKey);
+      if (index >= 0) this.statsRuleIndex = index;
+    }
+    this.statsRuleIndex = Math.max(0, Math.min(this.statsRuleIndex, Math.max(0, rows.length - 1)));
+    this.statsRuleFocusKey = rows[this.statsRuleIndex]?.rowKey;
+    return rows;
+  }
+
+  private async performStatsRule(action: () => MaybePromise, focusKey: string): Promise<void> {
+    if (this.statsRulePending) return;
+    this.clearActionError();
+    this.statsRulePending = true;
+    this.changed();
+    try {
+      await action();
+      if (this.disposed) return;
+      this.actionError = undefined;
+    } catch (error) {
+      if (this.disposed) return;
+      this.actionError = sanitizedError(error);
+      this.statsRuleFocusKey = focusKey;
+      try { this.callbacks?.mutationError?.(error); } catch { /* advisory */ }
+    } finally {
+      if (!this.disposed) {
+        this.statsRulePending = false;
+        this.changed();
+      }
+    }
+  }
+
+  private moveStatsRuleFocus(direction: -1 | 1): void {
+    if (this.statsRulePending) return;
+    const stats = this.getStats();
+    const practice = this.getPractice();
+    if (!stats || !practice) return;
+    const rows = this.statsRuleRows(stats, practice);
+    this.statsRuleIndex = Math.max(0, Math.min(rows.length - 1, this.statsRuleIndex + direction));
+    this.statsRuleFocusKey = rows[this.statsRuleIndex]?.rowKey;
+    this.clearActionError();
+    this.changed();
+  }
+
+  private async toggleFocusedStatsRule(): Promise<void> {
+    if (this.statsRulePending) return;
+    const callbacks = this.callbacks;
+    const stats = this.getStats();
+    const practice = this.getPractice();
+    if (!callbacks || !stats || !practice) return;
+    const rows = this.statsRuleRows(stats, practice);
+    const row = rows[this.statsRuleIndex];
+    if (!row) return;
+    if (!row.selected && practice.settings.consentedAt === undefined) {
+      await this.performStatsRule(() => callbacks.activatePractice?.(row.target), row.rowKey);
+      return;
+    }
+    await this.performStatsRule(() => callbacks.setPracticeTarget?.(row.target, !row.selected), row.rowKey);
+  }
+
   async handleInput(data: string): Promise<void> {
     const callbacks = this.callbacks;
     if (this.disposed || !callbacks) return;
+    if (this.statsRulePending) return;
     const items = this.items();
 
     if (callbacks.keybindings.matches(data, "tui.select.cancel")) {
       callbacks.close();
       return;
     }
+    if (this.view === "stats") {
+      if (callbacks.keybindings.matches(data, "tui.select.up") || data === "k") {
+        this.moveStatsRuleFocus(-1);
+        return;
+      }
+      if (callbacks.keybindings.matches(data, "tui.select.down") || data === "j") {
+        this.moveStatsRuleFocus(1);
+        return;
+      }
+      if (data === " ") {
+        await this.toggleFocusedStatsRule();
+        return;
+      }
+    }
     if (data === "\t" || matchesKey(data, Key.tab)) {
       this.clearActionError();
       this.view = VIEWS[(VIEWS.indexOf(this.view) + 1) % VIEWS.length]!;
@@ -376,7 +534,7 @@ export class FluencyOverlay implements Component {
   private verticalBudget(): number {
     const rows = this.callbacks?.tui.terminal?.rows;
     if (typeof rows !== "number" || !Number.isFinite(rows) || rows <= 0) return FALLBACK_VERTICAL_BUDGET;
-    return Math.max(HEADER_LINES + FOOTER_LINES + BORDER_LINES + 1, Math.min(Math.floor(rows * 0.8), rows - 2));
+    return Math.max(HEADER_LINES + FOOTER_LINES + BORDER_LINES + 1, Math.min(Math.floor(rows * 0.8) + 1, rows - 2));
   }
 
   private visiblePatternLines(pattern: ReviewPattern, width: number, available: number): string[] {
@@ -406,32 +564,41 @@ export class FluencyOverlay implements Component {
     }
   }
 
-  private ruleTrend(rule: RuleAnalytics): string {
-    if (rule.trend === "new") return "✦ new";
+  private ruleTrend(rule: RuleAnalytics): string | undefined {
+    if (rule.trend === "new") return undefined;
     if (rule.trend === "stable") return "→";
     const arrow = rule.trend === "improving" ? "↓" : "↑";
     const change = rule.changePercent === undefined ? "" : `${Math.abs(Math.round(rule.changePercent))}%`;
     return `${arrow}${change}`;
   }
 
-  private statsLines(stats: FluencyAnalytics, width: number): string[] {
-    const body: string[] = [];
-    const append = (text = ""): void => {
+  private statsBody(stats: FluencyAnalytics, width: number, practice?: PracticeOverlayState): StatsBody {
+    const lines: string[] = [];
+    const append = (text = ""): { start: number; end: number } => {
+      const start = lines.length;
       const wrapped = wrapTextWithAnsi(text, Math.max(1, width - 1));
-      if (wrapped.length === 0) body.push("");
-      else for (const line of wrapped) body.push(` ${line}`);
+      if (wrapped.length === 0) lines.push("");
+      else for (const line of wrapped) lines.push(` ${line}`);
+      return { start, end: lines.length - 1 };
+    };
+    const appendHanging = (prefix: string, content: string): { start: number; end: number } => {
+      const available = Math.max(1, width - 1 - visibleWidth(prefix));
+      const wrapped = wrapTextWithAnsi(content, available);
+      const start = lines.length;
+      const continuation = " ".repeat(visibleWidth(prefix));
+      wrapped.forEach((line, index) => lines.push(` ${index === 0 ? prefix : continuation}${line}`));
+      return { start, end: lines.length - 1 };
     };
     const periodRate = stats.periodRatePerThousand === undefined
       ? "—"
       : stats.periodRatePerThousand.toFixed(1);
-    const currentRate = stats.currentRatePerThousand === undefined
-      ? "—"
-      : stats.currentRatePerThousand.toFixed(1);
     const coverage = stats.reviewCoverage === undefined
       ? "—"
       : `${Math.round(stats.reviewCoverage * 100)}%`;
 
-    append("Fluency trend · 30 days");
+    append("Mistakes / 1,000 words · last 30 days");
+    append(`${stats.dailyRateSparkline}  ${periodRate}/k`);
+    append("30 days ago ... today");
     append();
     append(`Accepted rate       ${periodRate} / 1000 English words`);
     append(`English words       ${stats.englishWords.toLocaleString("en-US")}`);
@@ -441,33 +608,103 @@ export class FluencyOverlay implements Component {
     append(`Pending             ${stats.periodPendingOccurrences.toLocaleString("en-US")}`);
     append(`Review coverage     ${coverage}`);
     append(`Active rules        ${stats.activeRules.toLocaleString("en-US")}`);
-    append(`${stats.toolbarSparkline}  ${currentRate === "—" ? "—/k" : `${currentRate}/k`}`);
     append();
     append("Concrete rules");
-    append(`↓ ${stats.trendCounts.improving} improving   ↑ ${stats.trendCounts.worsening} worsening   → ${stats.trendCounts.stable} stable   ✦ ${stats.trendCounts.new} new`);
+    append(`↓ ${stats.trendCounts.improving} improving   ↑ ${stats.trendCounts.worsening} worsening   → ${stats.trendCounts.stable} stable`);
     append();
-    if (stats.rules.length === 0) {
+
+    if (!practice) {
+      if (stats.rules.length === 0) append("No recurring concrete rules in this period.");
+      return { lines };
+    }
+    const rows = this.statsRuleRows(stats, practice);
+    if (rows.length === 0) {
       append("No recurring concrete rules in this period.");
-    } else {
-      for (const rule of stats.rules) {
-        append(rule.explanation);
-        const ruleRate = rule.ratePerThousand === undefined ? "—/k" : `${rule.ratePerThousand.toFixed(1)}/k`;
-        append(`${ruleRate}  ${this.ruleTrend(rule)}  ${rule.sparkline}`);
-        append();
-      }
+      return { lines };
     }
-    return body;
+
+    const labels: Partial<Record<StatsRuleRow["section"], string>> = {
+      historical: "Selected, not currently recurring",
+      paused: "Selected, paused by Ignore",
+    };
+    let section: StatsRuleRow["section"] | undefined;
+    let focusedRange: StatsBody["focusedRange"];
+    rows.forEach((row, index) => {
+      if (row.section !== section) {
+        if (section !== undefined) append();
+        section = row.section;
+        const label = labels[section];
+        if (label) append(label);
+      }
+      const marker = index === this.statsRuleIndex ? ">" : " ";
+      const prefix = `${marker} ${row.selected ? "[x]" : "[ ]"} `;
+      const suffix = row.paused ? " · paused by Ignore" : "";
+      const title = appendHanging(prefix, `${row.target.explanation}${suffix}`);
+      let end = title.end;
+      if (row.section === "recurring") {
+        const rule = stats.rules.find((candidate) => candidate.rowKey === row.rowKey);
+        if (rule) {
+          const ruleRate = rule.ratePerThousand === undefined ? "—/k" : `${rule.ratePerThousand.toFixed(1)}/k`;
+          const metadata = [ruleRate, this.ruleTrend(rule), rule.sparkline].filter((field): field is string => Boolean(field));
+          end = appendHanging("      ", metadata.join("  ")).end;
+        }
+      }
+      if (this.actionError && index === this.statsRuleIndex) {
+        end = appendHanging("      ", `Action failed: ${this.actionError}`).end;
+      }
+      if (index === this.statsRuleIndex) focusedRange = { start: title.start, end };
+    });
+    return { lines, ...(focusedRange ? { focusedRange } : {}) };
   }
 
-  private visibleStatsLines(stats: FluencyAnalytics, width: number, available: number): string[] {
+  private visibleStatsLines(stats: FluencyAnalytics, width: number, available: number, practice?: PracticeOverlayState): string[] {
     if (available <= 0) {
       this.resetDetailPaging();
       return [];
     }
-    const body = this.statsLines(stats, width);
-    this.maxDetailOffset = Math.max(0, body.length - available);
+    const body = this.statsBody(stats, width, practice);
+    this.maxDetailOffset = Math.max(0, body.lines.length - available);
     this.detailOffset = Math.min(this.detailOffset, this.maxDetailOffset);
-    return body.slice(this.detailOffset, this.detailOffset + available);
+    const focused = body.focusedRange;
+    if (focused) {
+      const focusHeight = focused.end - focused.start + 1;
+      if (focusHeight > available) {
+        this.detailOffset = focused.start;
+      } else if (focused.start < this.detailOffset) {
+        this.detailOffset = focused.start;
+      } else if (focused.end >= this.detailOffset + available) {
+        this.detailOffset = focused.end - available + 1;
+      }
+      this.detailOffset = Math.max(0, Math.min(this.detailOffset, this.maxDetailOffset));
+    }
+    return body.lines.slice(this.detailOffset, this.detailOffset + available);
+  }
+
+  private practiceStatus(practice?: PracticeOverlayState): string | undefined {
+    if (!practice) return undefined;
+    if (!practice.settings.enabled) return " Practice off · selected rules not checked";
+    const globalSnoozed = (practice.settings.snoozedUntil ?? 0) > practice.now;
+    if (practice.sessionSnoozed && globalSnoozed) {
+      return " Session + global snooze · selected rules not checked";
+    }
+    if (practice.sessionSnoozed) return " Session snooze · selected rules not checked";
+    if (globalSnoozed) return " Global snooze · selected rules not checked";
+    return " Practice on · selected rules checked before send";
+  }
+
+  private footerLines(contentWidth: number, practice?: PracticeOverlayState): string[] {
+    if (this.view === "stats") {
+      const action = this.statsRulePending
+        ? " Saving…   focus and toggle disabled"
+        : " ↑↓/jk focus + scroll   Space toggle   tab view   esc close";
+      const status = this.practiceStatus(practice);
+      return [
+        ...(status ? wrapTextWithAnsi(status, Math.max(1, contentWidth)) : []),
+        ...wrapTextWithAnsi(action, Math.max(1, contentWidth)),
+      ];
+    }
+    if (this.view === "inbox") return [" ←→ card  ↑↓/jk scroll  a accept  d dismiss", " i ignore  tab view  esc close"];
+    return [" ←→ card  ↑↓/jk scroll", this.view === "ignored" ? " u restore all  tab view  esc close" : " i ignore  tab view  esc close"];
   }
 
   render(width: number): string[] {
@@ -479,6 +716,7 @@ export class FluencyOverlay implements Component {
     const innerBudget = Math.max(0, budget - BORDER_LINES);
     const items = this.items();
     const stats = this.view === "stats" ? this.getStats() : undefined;
+    const practice = this.view === "stats" && stats ? this.getPractice() : undefined;
     const title = ` Pi Fluency · ${this.view[0]!.toUpperCase()}${this.view.slice(1)}`;
     const noun = this.view === "inbox" ? "pending" : this.view;
     const selected = items[this.selectedIndex];
@@ -491,14 +729,15 @@ export class FluencyOverlay implements Component {
     const headerLines = combinedHeaderWidth <= contentWidth
       ? [title + " ".repeat(contentWidth - visibleWidth(title) - visibleWidth(paging)) + paging]
       : [title, ...wrapTextWithAnsi(` ${paging}`, contentWidth)];
+    const footerLines = this.footerLines(contentWidth, practice);
     const lines: string[] = [...headerLines, ` ${"─".repeat(Math.max(0, contentWidth - 2))}`];
 
     if (this.loadError) {
       this.resetDetailPaging();
       lines.push(` Could not load ${this.view === "stats" ? "statistics" : "patterns"}: ${this.loadError}`);
     } else if (this.view === "stats" && stats) {
-      const reserved = headerLines.length + 1 + FOOTER_LINES;
-      lines.push(...this.visibleStatsLines(stats, contentWidth, Math.max(1, innerBudget - reserved)));
+      const reserved = headerLines.length + 2 + footerLines.length;
+      lines.push(...this.visibleStatsLines(stats, contentWidth, Math.max(1, innerBudget - reserved), practice));
     } else {
       if (this.actionError) lines.push(` Action failed: ${this.actionError}`);
       if (items.length === 0) {
@@ -511,14 +750,7 @@ export class FluencyOverlay implements Component {
     }
 
     lines.push(` ${"─".repeat(Math.max(0, contentWidth - 2))}`);
-    if (this.view === "stats") {
-      lines.push(" ↑↓/jk scroll  pgup/pgdn");
-      lines.push(" tab view  esc close");
-    } else {
-      if (this.view === "inbox") lines.push(" ←→ card  ↑↓/jk scroll  a accept  d dismiss");
-      else lines.push(" ←→ card  ↑↓/jk scroll");
-      lines.push(this.view === "ignored" ? " u restore all  tab view  esc close" : " i ignore  tab view  esc close");
-    }
+    lines.push(...footerLines);
 
     const border = (text: string): string => this.callbacks?.theme.fg("border", text) ?? text;
     const top = border(`╭${"─".repeat(contentWidth)}╮`);
@@ -532,6 +764,11 @@ export class FluencyOverlay implements Component {
   }
 }
 
+export interface PracticeOverlayRuntime {
+  sessionSnoozed(): boolean;
+  resumeSession(): void;
+}
+
 export async function showFluencyOverlay(
   ctx: ExtensionContext,
   store: FluencyStore,
@@ -540,6 +777,7 @@ export async function showFluencyOverlay(
   onMutationError?: (error: unknown) => void,
   initialView: FluencyView = "inbox",
   now: () => number = Date.now,
+  practiceRuntime?: PracticeOverlayRuntime,
 ): Promise<void> {
   if (ctx.mode !== "tui") {
     ctx.ui.notify("Pi Fluency inbox requires interactive TUI mode", "warning");
@@ -572,6 +810,22 @@ export async function showFluencyOverlay(
               now: now(),
             });
           },
+          practice: () => {
+            const snapshot = store.getAnalyticsSnapshot();
+            const settings = store.getSettings();
+            const practiceSettings = store.getPracticeSettings();
+            return {
+              settings: practiceSettings,
+              targets: resolvePracticeTargets({
+                targets: practiceSettings.targets,
+                patterns: snapshot.patterns,
+                ignoredPatternKeys: new Set(settings.ignoredPatternKeys),
+                ignoredCategories: new Set(settings.ignoredCategories),
+              }),
+              sessionSnoozed: practiceRuntime?.sessionSnoozed() ?? false,
+              now: now(),
+            };
+          },
           initialView,
           ignoredBy: (pattern) => {
             const settings = store.getSettings();
@@ -610,6 +864,8 @@ export async function showFluencyOverlay(
             });
             onProgressChanged?.();
           },
+          activatePractice: (target) => store.activatePractice(now(), target),
+          setPracticeTarget: (target, selected) => store.setPracticeTarget(target, selected),
           ...(onMutationError ? { mutationError: onMutationError } : {}),
           close: () => done(),
         });