@magmamath/students-features 1.4.1 → 1.4.2

package/src/features/fluency/model/FluencySolvingModel.ts

@@ -0,0 +1,183 @@
+import { createEvent, createStore, restore, sample } from 'effector'
+import type { Store } from 'effector'
+import {
+  AttemptStatus,
+  FLUSH_ATTEMPTS_COUNT,
+  FluencyMode,
+  SESSION_LENGTH,
+  getTimeThresholdByGrade,
+} from '../shared/fluency.constants'
+import { calculateNextBox, selectNextFact, toSolvingFacts } from '../shared/fluencySolving.helpers'
+import type { QuestionOutcome, SolvingFact } from '../shared/fluencySolving.types'
+import type { FluencyAttemptItem, FluencyConfig, GetMatrixResponse } from '../shared/fluency.types'
+import type { FluencyMatrixModel } from './FluencyMatrixModel'
+import { createAction } from 'effector-action'
+
+export class FluencySolvingModel {
+  public readonly reset = createEvent()
+
+  public readonly start = createEvent<FluencyMode | void>()
+  public readonly submit = createEvent()
+  public readonly setAnswer = createEvent<string | null>()
+  public readonly setSessionCompleted = createEvent<boolean>()
+  public readonly updateFact = createEvent<SolvingFact>()
+  public readonly flushAttempts = createEvent<FluencyAttemptItem[]>()
+
+  public readonly $answer = restore(this.setAnswer, null).reset(this.reset)
+  public readonly $current = createStore<SolvingFact | null>(null).reset(this.reset)
+  public readonly $outcomes = createStore<QuestionOutcome[]>([]).reset(this.reset)
+  public readonly $facts = createStore<SolvingFact[]>([])
+    .on(this.updateFact, (facts, updatedFact) =>
+      facts.map((fact) => (fact.id === updatedFact.id ? updatedFact : fact)),
+    )
+    .reset(this.reset)
+
+  public readonly $sessionDurationMs = createStore(0).reset(this.reset)
+  public readonly $completedDurationMs = createStore(0).reset(this.reset)
+  public readonly $timeSpentInCurrentMs = createStore(0).reset(this.reset)
+
+  public readonly $isSessionComplete = restore(this.setSessionCompleted, false).reset(this.reset)
+  public readonly $pendingAttempts = createStore<FluencyAttemptItem[]>([])
+    .reset(this.flushAttempts)
+    .reset(this.reset)
+
+  constructor(
+    private readonly matrixModel: FluencyMatrixModel,
+    private readonly $config: Store<FluencyConfig | null>,
+  ) {
+    this.setupStartTrigger()
+    this.setupSubmitTrigger()
+    this.setupFlushTrigger()
+  }
+
+  private setupStartTrigger() {
+    createAction(this.start, {
+      source: { data: this.matrixModel.$data },
+      target: {
+        $facts: this.$facts,
+        $current: this.$current,
+        $answer: this.$answer,
+        $outcomes: this.$outcomes,
+        $isSessionComplete: this.$isSessionComplete,
+        $pendingAttempts: this.$pendingAttempts,
+        $sessionDurationMs: this.$sessionDurationMs,
+        $completedDurationMs: this.$completedDurationMs,
+        $timeSpentInCurrentMs: this.$timeSpentInCurrentMs,
+      },
+      fn: (target, source, mode) => {
+        if (!source.data) return
+
+        const facts = this.getFactsFromData(source.data, mode || undefined)
+        target.$facts(facts)
+        target.$current(selectNextFact(facts, Date.now()))
+        target.$answer(null)
+        target.$outcomes([])
+        target.$isSessionComplete(false)
+        target.$pendingAttempts([])
+        target.$sessionDurationMs(Date.now())
+        target.$completedDurationMs(0)
+        target.$timeSpentInCurrentMs(Date.now())
+      },
+    })
+  }
+
+  private setupSubmitTrigger() {
+    createAction(this.submit, {
+      source: {
+        answer: this.$answer,
+        facts: this.$facts,
+        current: this.$current,
+        outcomes: this.$outcomes,
+        timeSpentInCurrentMs: this.$timeSpentInCurrentMs,
+        sessionDurationMs: this.$sessionDurationMs,
+        pendingAttempts: this.$pendingAttempts,
+        config: this.$config,
+      },
+      target: {
+        $current: this.$current,
+        $outcomes: this.$outcomes,
+        $answer: this.$answer,
+        $sessionDurationMs: this.$sessionDurationMs,
+        $completedDurationMs: this.$completedDurationMs,
+        $timeSpentInCurrentMs: this.$timeSpentInCurrentMs,
+        $pendingAttempts: this.$pendingAttempts,
+        update: this.updateFact,
+        setSessionCompleted: this.setSessionCompleted,
+      },
+      fn: (target, source) => {
+        if (!source.facts || !source.current) return
+
+        const timeTakenToSolveFactMs = Date.now() - source.timeSpentInCurrentMs
+        const isCorrect = source.answer !== null && Number(source.answer) === source.current.answer
+        const isFast = timeTakenToSolveFactMs <= getTimeThresholdByGrade(source.config?.grade)
+        const isLastQuestion = source.outcomes.length + 1 >= SESSION_LENGTH
+
+        const nextBox = calculateNextBox({
+          isFast,
+          isCorrect,
+          currentBox: source.current.box,
+          sessionStartBox: source.current.sessionStartBox,
+          hasFailedThisSession: source.current.hasFailedThisSession,
+        })
+
+        const updatedFact = {
+          ...source.current,
+          box: nextBox,
+          lastSeenMs: Date.now(),
+          hasFailedThisSession: source.current.hasFailedThisSession || !isCorrect,
+          attemptsCount: source.current.attemptsCount + 1,
+          correctCount: source.current.correctCount + (isCorrect ? 1 : 0),
+        }
+
+        const updatedFacts = source.facts.map((f) => (f.id === updatedFact.id ? updatedFact : f))
+        target.update(updatedFact)
+
+        const attemptItem: FluencyAttemptItem = {
+          factId: source.current.id,
+          status: isCorrect ? AttemptStatus.CORRECT : AttemptStatus.INCORRECT,
+          startedAt: new Date(source.timeSpentInCurrentMs).toISOString(),
+          timeToSolve: timeTakenToSolveFactMs,
+          boxAfter: nextBox,
+        }
+        target.$pendingAttempts([...source.pendingAttempts, attemptItem])
+        target.$outcomes([
+          ...source.outcomes,
+          {
+            factId: source.current.id,
+            status: isCorrect ? AttemptStatus.CORRECT : AttemptStatus.INCORRECT,
+            answer: source.answer,
+            numbers: source.current.numbers,
+            mode: source.current.mode,
+          },
+        ])
+
+        if (isLastQuestion) {
+          target.$completedDurationMs(Date.now() - source.sessionDurationMs)
+          target.$sessionDurationMs(0)
+          target.setSessionCompleted(true)
+          return
+        }
+
+        target.$current(selectNextFact(updatedFacts, Date.now()))
+        target.$answer(null)
+        target.$timeSpentInCurrentMs(Date.now())
+      },
+    })
+  }
+
+  private setupFlushTrigger() {
+    sample({
+      clock: this.$pendingAttempts,
+      filter: (attempts) => attempts.length >= FLUSH_ATTEMPTS_COUNT,
+      target: this.flushAttempts,
+    })
+  }
+
+  private getFactsFromData(data: GetMatrixResponse, mode?: FluencyMode) {
+    return mode
+      ? toSolvingFacts(data.operations[mode].facts, mode)
+      : Object.entries(data.operations).flatMap(([key, { facts }]) =>
+          toSolvingFacts(facts, key as FluencyMode),
+        )
+  }
+}

package/src/features/fluency/shared/fluency.constants.ts

@@ -0,0 +1,108 @@
+import { ButtonColor, COLORS, SelectOptionColor } from '@magmamath/react-native-ui'
+import { createFluencyMode } from './fluency.helpers'
+import type { FluencyColorPalette, FluencyModeConfig, FluencyModePreset } from './fluency.types'
+
+export const MAX_INPUT_LENGTH = 3
+export const SESSION_LENGTH = 20
+export const FLUSH_ATTEMPTS_COUNT = 5
+
+export const getTimeThresholdByGrade = (grade?: number): number => {
+  if (grade == null || grade >= 4) return 4000
+  if (grade >= 2) return 5000
+  return 6000
+}
+
+export enum FluencyMode {
+  ADDITION = 'addition',
+  SUBTRACTION = 'subtraction',
+  MULTIPLICATION = 'multiplication',
+  DIVISION = 'division',
+}
+
+export enum FluencyMasteryLevel {
+  NOT_STARTED = 0,
+  LEARNING = 1,
+  GROWING = 2,
+  STRONG = 3,
+  MASTERED = 4,
+}
+
+export enum FluencyColorFamily {
+  GREEN = 'GREEN',
+  ORANGE = 'ORANGE',
+  BLUE = 'BLUE',
+  PURPLE = 'PURPLE',
+}
+
+export enum StreakStatus {
+  MISSED = 'missed',
+  GAINED = 'gained',
+  TODAY = 'today',
+  TODAY_GAINED = 'today_gained',
+}
+
+export enum AttemptStatus {
+  CORRECT = 'correct',
+  INCORRECT = 'incorrect',
+  SKIPPED = 'skipped',
+}
+
+export enum MatrixConfig {
+  STANDARD = 'standard',
+}
+
+export const COLOR_FAMILY_PALETTES: Record<FluencyColorFamily, FluencyColorPalette> = {
+  [FluencyColorFamily.GREEN]: {
+    shades: [COLORS.GREEN_2, COLORS.GREEN_3, COLORS.PRIMARY_GREEN, COLORS.GREEN_6],
+    button: ButtonColor.GREEN,
+    select: SelectOptionColor.GREEN,
+  },
+  [FluencyColorFamily.ORANGE]: {
+    shades: [COLORS.ORANGE_2, COLORS.ORANGE_3, COLORS.PRIMARY_ORANGE, COLORS.ORANGE_6],
+    button: ButtonColor.ORANGE,
+    select: SelectOptionColor.ORANGE,
+  },
+  [FluencyColorFamily.BLUE]: {
+    shades: [COLORS.BLUE_2, COLORS.BLUE_3, COLORS.PRIMARY_BLUE, COLORS.BLUE_6],
+    button: ButtonColor.BLUE,
+    select: SelectOptionColor.BLUE,
+  },
+  [FluencyColorFamily.PURPLE]: {
+    shades: [COLORS.PURPLE_2, COLORS.PURPLE_3, COLORS.PRIMARY_PURPLE, COLORS.PURPLE_6],
+    button: ButtonColor.PURPLE,
+    select: SelectOptionColor.PURPLE,
+  },
+}
+
+export const FLUENCY_MODES: readonly FluencyModeConfig[] = [
+  createFluencyMode({
+    mode: FluencyMode.ADDITION,
+    label: 'student.fluency.addition',
+    symbol: '+',
+    colorFamily: FluencyColorFamily.GREEN,
+  }),
+  createFluencyMode({
+    mode: FluencyMode.SUBTRACTION,
+    label: 'student.fluency.subtraction',
+    symbol: '−',
+    colorFamily: FluencyColorFamily.ORANGE,
+  }),
+  createFluencyMode({
+    mode: FluencyMode.MULTIPLICATION,
+    label: 'student.fluency.multiplication',
+    symbol: '×',
+    colorFamily: FluencyColorFamily.BLUE,
+  }),
+  createFluencyMode({
+    mode: FluencyMode.DIVISION,
+    label: 'student.fluency.division',
+    symbol: '÷',
+    colorFamily: FluencyColorFamily.PURPLE,
+  }),
+]
+
+export const FLUENCY_MODE_PRESETS: Record<FluencyMode, FluencyModePreset> = Object.fromEntries(
+  FLUENCY_MODES.map(({ mode, preset }) => [mode, preset]),
+) as Record<FluencyMode, FluencyModePreset>
+
+export const ONE_DAY_MS = 86_400_000

package/src/features/fluency/shared/fluency.helpers.ts

@@ -0,0 +1,134 @@
+import { COLORS } from '@magmamath/react-native-ui'
+import {
+  FluencyColorFamily,
+  FluencyMasteryLevel,
+  FluencyMode,
+  COLOR_FAMILY_PALETTES,
+  StreakStatus,
+  ONE_DAY_MS,
+} from './fluency.constants'
+import type {
+  FluencyModeConfig,
+  GetMatrixResponse,
+  GetWeeklyStatsResponse,
+  GridCell,
+  MatrixGrid,
+} from './fluency.types'
+import type { TranslationKey } from '../../../i18n/i18n'
+
+type CreateFluencyModeParams = {
+  mode: FluencyMode
+  label: TranslationKey
+  symbol: string
+  colorFamily: FluencyColorFamily
+}
+
+export const createFluencyMode = ({
+  mode,
+  label,
+  symbol,
+  colorFamily,
+}: CreateFluencyModeParams): FluencyModeConfig => {
+  const palette = COLOR_FAMILY_PALETTES[colorFamily]
+  const [learning, growing, strong, mastered] = palette.shades
+
+  return {
+    mode,
+    label,
+    symbol,
+    select: palette.select,
+    preset: {
+      buttonColor: palette.button,
+      symbol,
+      accentColor: strong,
+      header: {
+        streakColor: { gained: growing, todayBorder: strong },
+      },
+      matrix: {
+        operatorLabel: label,
+        levelColors: {
+          [FluencyMasteryLevel.NOT_STARTED]: COLORS.NEUTRAL_2,
+          [FluencyMasteryLevel.LEARNING]: learning,
+          [FluencyMasteryLevel.GROWING]: growing,
+          [FluencyMasteryLevel.STRONG]: strong,
+          [FluencyMasteryLevel.MASTERED]: mastered,
+        },
+      },
+    },
+  }
+}
+
+export const buildMatrixGrid = (data: GetMatrixResponse, mode: FluencyMode): MatrixGrid => {
+  const facts = Object.values(data.operations[mode].facts)
+  const maxRow = Math.max(0, ...facts.map((f) => f.position.row))
+  const maxColumn = Math.max(0, ...facts.map((f) => f.position.column))
+  const isDivision = mode === FluencyMode.DIVISION
+  const isSubtraction = mode === FluencyMode.SUBTRACTION
+  const isCommutative = mode === FluencyMode.ADDITION || mode === FluencyMode.MULTIPLICATION
+
+  const factAt = (row: number, col: number) =>
+    facts.find((f) => f.position.row === row && f.position.column === col)
+
+  // Division columns are 1-indexed in the API (÷1, ÷2...); all others are 0-indexed.
+  // Subtraction rows: the API stores position.row = result (like division stores quotient),
+  // but we display a minuend×subtrahend grid, so we derive row count from the max minuend
+  // stored in fact.numbers[0] and look up each cell by result = minuend − subtrahend.
+  const maxMinuend = isSubtraction ? Math.max(0, ...facts.map((f) => f.numbers[0])) : maxRow
+  const rowNumbers = Array.from({ length: maxMinuend + 1 }, (_, i) => i)
+  const columnNumbers = isDivision
+    ? Array.from({ length: maxColumn }, (_, i) => i + 1)
+    : Array.from({ length: maxColumn + 1 }, (_, i) => i)
+
+  const headerRow: GridCell[] = [
+    { isHeader: false, isEmpty: false, label: null, box: null, numbers: null },
+    ...columnNumbers.map(
+      (col): GridCell => ({ isHeader: true, isEmpty: false, label: col, box: null, numbers: null }),
+    ),
+  ]
+
+  const dataRows: GridCell[][] = rowNumbers.map((row) => [
+    { isHeader: true, isEmpty: false, label: row, box: null, numbers: null },
+    ...columnNumbers.map((col): GridCell => {
+      if (isSubtraction && col > row) {
+        return { isHeader: false, isEmpty: true, label: null, box: null, numbers: null }
+      }
+
+      // Subtraction: row=minuend, col=subtrahend — look up by result=minuend−subtrahend
+      const fact = isSubtraction ? factAt(row - col, col) : factAt(row, col)
+      const mirrorFact = isCommutative ? factAt(col, row) : null
+      const primaryBox = fact?.box ?? null
+      const mirrorBox = mirrorFact?.box ?? null
+      const effectiveBox =
+        primaryBox !== null && mirrorBox !== null
+          ? Math.max(primaryBox, mirrorBox)
+          : (primaryBox ?? mirrorBox)
+      const numbers: readonly [number, number] =
+        fact?.numbers ?? (isDivision ? [row * col, col] : [row, col])
+      return {
+        isHeader: false,
+        isEmpty: false,
+        label: null,
+        box: effectiveBox,
+        numbers,
+      }
+    }),
+  ])
+
+  return [headerRow, ...dataRows]
+}
+
+export const generateStreakDates = (stats: GetWeeklyStatsResponse) => {
+  const todayMs = new Date().setHours(0, 0, 0, 0)
+  const startMs = new Date(stats.weekStart).setHours(0, 0, 0, 0)
+  const practiced = new Set(stats.practicedDates.map((d) => new Date(d).setHours(0, 0, 0, 0)))
+
+  return [0, 1, 2, 3, 4].map((i) => {
+    const dayMs = startMs + i * ONE_DAY_MS
+    const isPracticed = practiced.has(dayMs)
+    const isToday = dayMs === todayMs
+    if (isPracticed && isToday) return StreakStatus.TODAY_GAINED
+    if (isPracticed) return StreakStatus.GAINED
+    if (isToday) return StreakStatus.TODAY
+    return StreakStatus.MISSED
+  })
+}

package/src/features/fluency/shared/fluency.types.ts

@@ -0,0 +1,132 @@
+import type { ButtonColor, SelectOptionColor } from '@magmamath/react-native-ui'
+import type {
+  AttemptStatus,
+  FluencyMasteryLevel,
+  FluencyMode,
+  MatrixConfig,
+} from './fluency.constants'
+import type { TranslationKey } from '../../../i18n/i18n'
+
+export type LegendItem = {
+  label: string
+  color: string
+  withBorder?: boolean
+}
+
+export type FluencyColorPalette = {
+  shades: readonly [string, string, string, string]
+  button: ButtonColor
+  select: SelectOptionColor
+}
+
+export type FluencyModePreset = {
+  buttonColor: ButtonColor
+  symbol: string
+  accentColor: string
+  header: {
+    streakColor: { gained: string; todayBorder: string }
+  }
+  matrix: {
+    operatorLabel: TranslationKey
+    levelColors: Record<FluencyMasteryLevel, string>
+  }
+}
+
+export type FluencyModeConfig = {
+  mode: FluencyMode
+  label: TranslationKey
+  symbol: string
+  select: SelectOptionColor
+  preset: FluencyModePreset
+}
+
+export type GetMatrixPayload = {
+  grade: number
+}
+
+export type FluencyAttemptItem = {
+  factId: string
+  status: AttemptStatus
+  startedAt: string
+  timeToSolve: number
+  boxAfter: number
+}
+
+export type FluencyAttemptPayload = {
+  grade: number
+  attempts: FluencyAttemptItem[]
+  matrixConfig?: MatrixConfig
+}
+
+export type FluencyModelProps = {
+  api: {
+    getMatrix: (payload: GetMatrixPayload) => Promise<GetMatrixResponse>
+    getWeeklyStats: () => Promise<GetWeeklyStatsResponse>
+    postAttempt: (payload: FluencyAttemptPayload) => Promise<void>
+  }
+}
+
+export type FluencyConfig = {
+  grade: number
+  name: string
+}
+
+export type FluencyModelGateProps = {
+  config: FluencyConfig
+}
+
+type FactPosition = {
+  column: number
+  row: number
+}
+
+export type Fact = {
+  attemptsCount: number
+  averageTimeMs: number | null
+  box: FluencyMasteryLevel | null
+  correctCount: number
+  difficulty: number
+  lastAttemptedAt: string | null
+  lastSolvedAt: string | null
+  numbers: readonly [number, number]
+  position: FactPosition
+  streak: number
+}
+
+type Operator = 'addition' | 'subtraction' | 'multiplication' | 'division'
+
+type Operation = {
+  completionRate: number
+  grade: number | null
+  facts: Record<string, Fact>
+}
+
+export type GetMatrixResponse = {
+  studentId: string
+  operations: Record<Operator, Operation>
+}
+
+export type GetWeeklyStatsResponse = {
+  daysPracticed: number
+  daysWithoutPractice: number
+  practicedDates: string[]
+  weekStart: string
+}
+
+export type GridCell = {
+  isHeader: boolean
+  isEmpty: boolean
+  label: number | null
+  box: FluencyMasteryLevel | null
+  numbers: readonly [number, number] | null // null for header cells
+}
+
+export type MatrixGrid = GridCell[][]
+
+export type FlashcardLayout = {
+  card: { width: number; height: number; radius: number }
+  answer: { width: number; height: number; radius: number }
+  fontSize: number
+  position: { right: number; top: number; zIndex: number }
+  rotation: string
+}

package/src/features/fluency/shared/fluencySolving.constants.ts

@@ -0,0 +1,25 @@
+import { FluencyMode } from './fluency.constants'
+import type { PickerParams } from './fluencySolving.types'
+
+const HOUR_MS = 60 * 60 * 1000
+const BOX_1_INTERVAL = 4 * HOUR_MS
+const BOX_2_INTERVAL = 36 * HOUR_MS // 1.5 days
+const BOX_3_INTERVAL = 144 * HOUR_MS // 6 days
+const BOX_4_INTERVAL = 672 * HOUR_MS // 4 weeks
+const BOX_5_INTERVAL = 2016 * HOUR_MS // 12 weeks
+
+export const DEFAULT_PICKER_PARAMS: PickerParams = {
+  wDue: 0.05,
+  wWeak: 0.35,
+  wEase: 0.3,
+  wRand: 0.02,
+  numBoxes: 5,
+  boxIntervals: [0, BOX_1_INTERVAL, BOX_2_INTERVAL, BOX_3_INTERVAL, BOX_4_INTERVAL, BOX_5_INTERVAL],
+}
+
+export const MODE_ANSWER_EVAL_FORMULA: Record<FluencyMode, (a: number, b: number) => number> = {
+  [FluencyMode.ADDITION]: (a, b) => a + b,
+  [FluencyMode.SUBTRACTION]: (a, b) => a - b,
+  [FluencyMode.MULTIPLICATION]: (a, b) => a * b,
+  [FluencyMode.DIVISION]: (a, b) => a / b,
+}

package/src/features/fluency/shared/fluencySolving.helpers.ts

@@ -0,0 +1,102 @@
+import { AttemptStatus, FluencyMode } from './fluency.constants'
+import type { Fact } from './fluency.types'
+import { DEFAULT_PICKER_PARAMS, MODE_ANSWER_EVAL_FORMULA } from './fluencySolving.constants'
+import type { PickerParams, QuestionOutcome, SolvingFact } from './fluencySolving.types'
+
+export function toSolvingFacts(factMap: Record<string, Fact>, mode: FluencyMode): SolvingFact[] {
+  return Object.entries(factMap).map(([id, fact]) => {
+    const [a, b] = fact.numbers
+    const answer = MODE_ANSWER_EVAL_FORMULA[mode](a, b)
+    const box = fact.box ?? 0
+    return {
+      id,
+      mode,
+      numbers: fact.numbers,
+      answer,
+      difficulty: fact.difficulty,
+      box,
+      lastSeenMs: fact.lastAttemptedAt ? new Date(fact.lastAttemptedAt).getTime() : null,
+      sessionStartBox: box,
+      hasFailedThisSession: false,
+      attemptsCount: fact.attemptsCount,
+      correctCount: fact.correctCount,
+    }
+  })
+}
+
+function computePriority(
+  fact: SolvingFact,
+  now: number,
+  params: PickerParams,
+  maxDifficulty: number,
+): number {
+  const interval = Math.max(0.001, params.boxIntervals[Math.max(1, fact.box)])
+  const overdueness =
+    fact.lastSeenMs === null ? 1.0 : Math.min(1, (now - fact.lastSeenMs) / (2 * interval))
+  const weakness = (params.numBoxes - fact.box) / params.numBoxes
+  const ease = (1 - fact.difficulty / Math.max(0.1, maxDifficulty)) * weakness
+  return (
+    params.wDue * overdueness +
+    params.wWeak * weakness +
+    params.wEase * ease +
+    params.wRand * Math.random()
+  )
+}
+
+export function selectNextFact(
+  facts: SolvingFact[],
+  now: number,
+  params: PickerParams = DEFAULT_PICKER_PARAMS,
+): SolvingFact | null {
+  if (facts.length === 0) return null
+  const pool = facts
+  const maxDifficulty = pool.reduce((m, f) => Math.max(m, f.difficulty), 1)
+  let best = pool[0]
+  let bestScore = -Infinity
+  for (const f of pool) {
+    const score = computePriority(f, now, params, maxDifficulty)
+    if (score > bestScore) {
+      bestScore = score
+      best = f
+    }
+  }
+  return best
+}
+
+export const formatSessionDuration = (ms: number): string => {
+  const totalSeconds = Math.floor(ms / 1000)
+  const minutes = Math.floor(totalSeconds / 60)
+  const seconds = totalSeconds % 60
+  return `${minutes}:${seconds.toString().padStart(2, '0')}`
+}
+
+export const calculateMaxStreak = (outcomes: QuestionOutcome[]): number =>
+  outcomes.reduce(
+    (acc, outcome) => {
+      const current = outcome.status === AttemptStatus.CORRECT ? acc.current + 1 : 0
+      return { max: Math.max(acc.max, current), current }
+    },
+    { max: 0, current: 0 },
+  ).max
+
+type BoxTransitionParams = {
+  currentBox: number
+  isCorrect: boolean
+  isFast: boolean
+  sessionStartBox: number
+  hasFailedThisSession: boolean
+}
+
+export function calculateNextBox({
+  currentBox,
+  isCorrect,
+  isFast,
+  sessionStartBox,
+  hasFailedThisSession,
+}: BoxTransitionParams): number {
+  if (!isCorrect) return Math.max(1, currentBox - 1)
+  if (!isFast) return currentBox === 0 ? 1 : currentBox
+  if (hasFailedThisSession) return Math.min(currentBox + 1, sessionStartBox)
+  if (currentBox >= sessionStartBox + 1) return currentBox
+  return Math.min(currentBox + 1, 4)
+}