Shared TypeScript package for review-game apps
`review-game-core` is the decision layer behind the course apps in this workspace. It chooses the next concept, tracks quiz turn state, decides when to open support or recovery, schedules spaced return after independent work, and evaluates which study track a learner should do next.
What one learner turn includes
A learner turn moves through six named states: route, question, staged answer, support, recovery, complete.Consumer apps own the UI, content, and data. The core owns the workflow logic so the product does not drift into ad hoc quiz behavior.
One real API surface
import { evaluateGoalPlan } from '@brandon-gottshall/review-game-core'
const evaluation = evaluateGoalPlan(plan, snapshots, {
localDate: '2026-04-16',
})
const nextTrack = evaluation.trackPriority[0]
// Use this to decide which launcher card or study track
// the learner should see first today.Module split
State machine for a learner turn. It keeps routing, question state, staged answers, support, recovery, persistence, and debug hooks in one place — plus a content-identity seam so a restored turn can be compared against current authored content before it is resumed.
Concept mastery and spaced-return logic with the guided rep ladder — light, hard, and recovery-light phases — and named selection reasons the launcher can surface without inventing its own vocabulary.
Launcher and study-plan logic. It reads dated phase snapshots and returns a next-track recommendation such as primary, catch-up, queued, or complete.
A coarse 0–100 readiness signal plus a six-value phase vocabulary that rolls up honestly. Good for routing and launcher copy, intentionally not an assessment instrument.
Deterministic cohort resolution, exposure records, and served-question metadata let experimental or LLM-variant questions ride the same turn engine — with the WF harness gating them before learner exposure.
Used in these apps
Real consumers
stats-exam-prep-game
The stats launcher turns concept progress into a clear next-track recommendation without embedding learner planning into the core itself.
math-1111-review-game
Math1111 converts section completion and deadline windows into a unit recommendation while keeping course policy, sources, and learner identity out of the core.
core
The shared WF harness keeps type coverage, payload shape, concept consistency, and scheduler expectations testable before browser-level regression or low-context WF passes.
Feature showcase
state-machine
Ordered phases, local-date deadlines, and recommendation roles let consumer apps turn progress counts into a clear next track.
state-machine
Concept-level mastery math, spacing, and next-concept selection stay policy-driven so each game can own its own UI and gating rules.
state-machine
Concept-first rep phases — light, hard, and recovery-light — with explicit attempt budgets and selection reasons so apps can teach first, then fade to independent proof.
code-snippet
A coarse 0–100 readiness signal and a six-value phase vocabulary (not_started, learning, practicing, mastered, shaky, tracked_in_quiz) that products can roll up without overclaiming.
consumer-flow
The quiz engine runs a turn through six phases; session and debug helpers let consumer shells persist and force routes deterministically.
code-snippet
Session snapshots carry an optional content identity (questionId, contentId, contentVersion) so a restored turn can be compared honestly against current authored content before it is resumed.
code-snippet
Deterministic cohort resolution, exposure records, and served-question metadata for experimental or LLM-variant questions — so gated content stays visible, auditable, and WF-testable before it reaches learners.
code-snippet
The harness validates static well-formedness across question coverage, payload shape, concept wiring, generator determinism, and scheduler scenarios.
code-snippet
The graph layer projects authored learning structure into Neo4j as a rebuildable read model instead of turning the graph into an operational source of truth.
code-snippet
Questions, concepts, and seeded generators stay minimal so consumer repos can shape content and rendering without fighting a heavyweight framework — with room for a concept-first rubric (disclosure, scaffold-then-fade) above the core types.
Docs
Getting Started
Minimal imports for questions, concepts, generators, scheduling, and workflow contracts.
Open pageGraph
Projection-first graph contracts, query helpers, and Neo4j read-model boundaries.
Open pageOverview
Start here for the package framing, site structure, and the three public surfaces of the docs site.
Open pageOverview
Install the package, understand the source-first layout, and see how the site fits into the repo.
Open page
