Skip to content

Redesign the app shell and study sessions, and move to Next 16 - #13

Merged
Ben-K-Jordan merged 135 commits into
mainfrom
redesign
Oct 16, 2026
Merged

Ben-K-Jordan merged 135 commits into
mainfrom
redesign

Conversation

@Ben-K-Jordan

Copy link
Copy Markdown
Owner

This branch rebuilds every screen. The shell (Home, Plan, Study, Flashcards, Study guides, Chat, Progress and Settings) now follows Material 3 the way Google's web apps do. A study session runs like a Duolingo lesson: one question per screen, a progress bar on top, answer cards that press down and a feedback sheet that slides up. I also moved from Next 14 to Next 16, deleted a lot of dead code, closed several security gaps, rewrote the copy and replaced the e2e suite.

It's 135 commits on top of 66e7f29, so reviewing by theme is probably easier than reading them in order. A few commits from the second review round don't build on their own, because a module move is spread across them. The branch head builds and passes everything below, so a squash merge keeps main bisectable.

What changed

Framework and tooling

  • Next 14.2 to 16.4 (by way of 15.5), React 18.3 to 19.3, and ESLint 8 to 9 with a flat config. middleware.ts is now proxy.ts. Prisma 7.10, Playwright 1.64 and next-auth 4.24.15.
  • postinstall runs prisma generate, there's a typecheck script, and tsconfig targets ES2022.
  • pdf-parse is kept out of the server bundle, and upload paths are kept out of build file tracing, which had been copying .env into the standalone output.
  • Docker runs only the database now, and npm run setup applies the pgvector script.

Cleanup

  • Deleted the API routes nothing called, the unused calendar provider layer, the legacy styles and components, exports only tests used, and the bundled research PDFs. The learning science doc links each citation by DOI instead.
  • run.ts is split into src/services/run/, and nine pure modules moved into src/lib. A lint rule stops services, lib and API routes from importing UI code.
  • .env.example documents every variable the code reads.

Design system

  • Tailwind v4 and shadcn/ui on Radix, restyled to Material 3 colour roles. Sessions and card reviews use their own lesson palette. Both have light and dark themes that follow the system setting, with an override in Settings.
  • Google Sans Flex is self-hosted. Sessions turn its roundness axis up, so the same family reads square in the shell and rounder in a lesson.
  • New shell: a navigation rail from 600px, a bottom bar with a More sheet on phones, a top app bar, and a Start session button that's one step from anywhere.
  • /design renders every token and component in development. DESIGN.md writes them down.

Screens

  • Home leads with exam countdowns, weak spots (unresolved errors and low-mastery topics) and today's session.
  • Plan lists sessions by day, shows new times before rescheduling anything, and has a materials manager. Plans are scheduled in the plan's time zone.
  • Study recommends the next session with a plain reason, and offers Resume session when a planned session is already under way.
  • Sessions have a start screen that says what they'll ask, then one question per screen. You rate how sure you are (Guessing, Unsure or Sure) before anything is revealed, score free recall against the model answer, log errors, and finish on an end screen with accuracy, a Confidence section and follow-ups. Exam simulation takes every answer first and scores them after.
  • Flashcards, Chat, Study guides, Progress, Settings and the sign-in pages are rebuilt on the new components. Settings has an explicit save, a time zone picker, Google Calendar controls, data export and account deletion.
  • All visible text follows one voice guide: sentence case, no dashes or exclamation marks, dates and plurals through Intl, and an "AI-written" tag on every block of AI text.

Accessibility

  • The target is WCAG 2.2 AA, and 105 e2e tests run axe across the desktop and phone projects.
  • The answer loop works from the keyboard. Single-key shortcuts can be turned off in sessions and card reviews, and the session's shortcuts button now sits in the top bar, so touch screens get it too.
  • Session headings take focus on navigation, and focus goes back to the opener when a dialog closes. Focused controls scroll clear of the bars, and the bars go static in short windows such as 400% zoom. Selected and current states stay visible in forced colours mode, and reduced motion is respected.

Security

  • Session pages are owner-only and answer 404 to anyone else before the page streams. Every admin route goes through one requireAdmin check.
  • The proxy rejects cross-site API writes. The production CSP no longer allows unsafe-eval, and X-Powered-By is off.
  • The X-User-Id test header is only trusted with ALLOW_TEST_AUTH, plus CI=true on a production build and a loopback NEXTAUTH_URL.
  • Sign-in is limited per address and per account, and a signed known-browser cookie stops someone else from locking a student out. Link tokens are stored hashed, a reset link stays usable until the new password saves, passwords over 72 bytes are refused, and a reset or account deletion ends existing sessions.
  • Request bodies are bounded, AI spend has a daily ceiling across all accounts, and log lines are redacted.
  • Google tokens are bound to the signed-in user and revoked only after an account deletion commits.
  • Added a security policy, Dependabot and read-only CI permissions.

Tests

  • Unit tests run in UTC unless TZ is set, and the payload budget test moved to the integration suite.
  • The e2e suite is rebuilt around fixtures and a signed-in setup project, with a desktop Chrome project and a Pixel 7 project for @mobile tests. CI runs it in two shards, each with its own database and production build.

Docs

  • A new README with screenshots of each screen in both themes, DESIGN.md, an e2e guide, corrections to the learning science doc so it matches what the app does, SECURITY.md, the MIT license and package metadata.

Verification

Run on the branch head:

  • npm run typecheck: clean.
  • npm run lint: 0 errors, 0 warnings.
  • Unit tests: 121 files, 1,430 tests pass.
  • Integration tests against PostgreSQL: 11 files, 142 tests pass.
  • npm run build with the mock providers: passes.
  • e2e in CI mode on a fresh database, both projects: 263 passed, 3 skipped, 0 failed, 0 flaky. The skips are phone-only tests on the desktop project.

Known limitations

  • Breaks can't be reached from the UI, because every session is created with one block (cycles: 1).
  • Full-text search matches any of the question's words above a floor, and it can still cite an off-topic passage now and then.
  • Rate limits and the AI circuit breaker live in memory. They reset on restart and assume one server process.
  • The mock provider writes only free-recall templates, so multiple choice shows up only with a real AI key or a seeded deck (the README's multiple-choice screenshots use a seeded one).
  • Flashcard decks have no source column. "AI-written" on a deck is inferred from its title, and there's no manual New deck.
  • The Progress calibration chart hard-codes its dark theme colours, and a few components still use raw text sizes instead of the type scale.
  • scripts/seed-research.ts still has dashes in its text. Only the planning prompt reads it, and changing the text would change the hashes the seed uses to skip papers it has already loaded.

Before merging

  • The research PDFs are out of the tree but still in main's history. Taking them out of history needs a rewrite and a force push.
  • SECURITY.md points to GitHub's private vulnerability reporting, which has to be turned on in the repository settings.
  • The CI checks for branch protection are "Lint, Typecheck & Build", "Unit Tests", "Integration Tests", "E2E Tests (shard 1 of 2)" and "E2E Tests (shard 2 of 2)".

Move off Next 14, which has unpatched critical advisories, to Next 15.5.27
with React 19.3. Bump next-auth to 4.24.15 for its security fixes.

Dynamic route handlers and the session page now type params as a Promise,
matching the Next 15 route signature. The handlers already awaited params,
so only the annotations change. The route tests pass params the same way.

Also update prisma, @prisma/client and @prisma/adapter-pg to 7.10, zod to
4.6, nanoid to 3.3.20, and apply the non-breaking npm audit fixes. Next
adds an explicit compile target to tsconfig.json.
Run prisma generate after every install so the generated client never
drifts from the schema, and add a typecheck script that CI now runs
before the build.
When webpack bundles pdf-parse v1, its entry-module check always passes and
it tries to read a test PDF that is not shipped, so PDF processing throws
in production builds. Mark it as a server external package so Node loads
it from node_modules.
next lint filled in an ES2017 target during the Next 15 upgrade, which
makes tsc reject the BigInt literals in two test files. Every supported
Node version and browser handles ES2022.
getClientIp only reads headers, so it now takes any Request and the auth
routes no longer cast. The NextAuth POST handler types its context, the
reflow transaction lets Prisma infer the client, and the attempt route
narrows on result.error so the extra error fields are typed.
The upload directory comes from an env var, so Turbopack could not scope
it and traced the whole project, .env and research PDFs included, into
the standalone output. Mark those path calls as ignored for tracing.
Move to Next 16.4 (Turbopack now builds by default) and keep React on
19.3. Next 16 drops next lint, so linting runs through the ESLint 9 CLI
with a flat eslint.config.mjs built from eslint-config-next's
core-web-vitals and typescript configs. The old .eslintrc.json was
already removed in the previous tsconfig commit, and @eslint/eslintrc is
no longer needed.

The new lint setup also covers e2e and scripts. Tests keep allowing any,
and the screens that trip the new React hooks rules report them as
warnings until the UI redesign replaces them. Next also switched
tsconfig to the react-jsx runtime and added the dev route types.
Next 16 deprecates the middleware file convention in favor of proxy. The
matcher and auth logic are unchanged. Proxy always runs on the Node.js
runtime, which getToken supports.
Next 16 can generate an AGENTS.md at the project root during next dev.
Turn that off so the file never lands in the repo.
The PDFs were publisher copies that no code read. The learning science
doc now links every reference to its DOI, adds the papers it cited in
the text but left out of the list, and lists the seeded research papers
under further reading.
design/exports-raw was left over from a removed asset pipeline. The FTS
index in prisma/indexes.sql already exists as a migration, and nothing
ever ran the two partial indexes.
The callback redirected to /settings/calendar, which no longer exists,
so connecting Google always ended on a 404. Outcomes now land on
/settings with google=connected or google=error and an encoded reason.

The settings page UI tests in the calendar spec targeted the removed
page and always skipped; they are gone, and the remaining publish flow
tests live in calendar-publish.spec.ts.
The Dockerfile could not build (dev tools were omitted before next build)
and the app service never ran migrations, so both are gone. The app runs
on the host with next start, which no longer conflicts with standalone
output.

npm run setup now applies prisma/manual-scripts/001_pgvector.sql after
the migrations. The script only uses IF NOT EXISTS statements, so it is
safe to re-run, and setup reports a missing extension as a note.
Plan creation and reflow placed availability windows with setHours and
setDate, so "09:00" meant 09:00 on the server's clock and day indices
followed the server's calendar. On a UTC server a New York student got
sessions four hours early, and the reflow tests failed on any machine
not set to UTC.

lib/timezone gains addDays, daysBetween, hourOfDay and zonedTimeToUtc
(moved from followups). Plan creation, the pre-exam taper, slot scoring,
bedtime estimation, reflow, the reflow busy window and follow-up day
indices now all work in StudyPlan.timezone. A plan's timezone comes from
the request, then the user's setting, then America/New_York as before.
Plan start and end dates in API responses are calendar days in that zone.
An explicit TZ still applies, so the suite can be checked in other zones.
Inline VAR=value prefixes in the webServer command only work in POSIX
shells, so local e2e runs failed on Windows. The env block also sets
GOOGLE_PROVIDER=fake, which the calendar publish and reflow specs need
and which CI never set, so those specs always skipped. AI and email are
pinned to their offline providers.
Removed: POST /api/content/search, GET /api/mastery, POST
/api/stats/daily-goal, GET /api/plans/[planId]/feed, and
/api/integrations/google/{test,freebusy}. No page, script or service
called them. The feed route was blocked by auth for calendar clients
anyway, so the feed_url and webcal_url fields go with it. Helpers that
only served these routes (searchContentSchema, setDailyXpGoal) and the
e2e check for freebusy are removed too.
src/lib/calendar held an abandoned provider interface, a second fake
Google client, and a second computeEventHash; production code uses the
ones in src/lib/google. The only live piece, hashUserId, now lives in
event-builder.ts next to its one caller. The tests for the removed
copies go with them.
src/lib/crypto.ts only re-exported token-vault under older names.
Deleted with their tests: pushLimiter, BADGE_KEYS, BadgeType,
ItemStatus, TaperInput, UpdateAttemptMetaInput,
findIntradaySpacingViolations, fetchFeedbackExcerpts (and its private
storeCitations), listEvidenceTags, and the break helpers checkBreakEnded,
breakRemainingSeconds and workRemainingSeconds.

endBreak in the run service rebuilt the break state inline, which was a
copy of endBreakEarly, so it now calls endBreakEarly instead.
getBreakConfig stays because initBreakState uses it.
pdf.js copies its input with new input.constructor(input). For a Buffer
under 4 KB that copy comes from Node's shared pool at a non-zero offset,
which pdf.js ignores, so small PDFs failed with "bad XRef entry". The
extractor now passes a plain Uint8Array.

It also loads pdf-parse/lib/pdf-parse.js directly, which skips the debug
routine in the package entry, and collects text per page through
pagerender. The old form-feed split never matched pdf-parse's output, so
chunks never carried page numbers.

A unit test builds a two-page PDF in memory and checks the text and page
numbers.
Server code read NEXT_PUBLIC_APP_URL for links in emails. Next inlines
NEXT_PUBLIC_ variables at build time, so a build made with the default
baked in localhost. getBaseUrl() reads BASE_URL at runtime.
.env.example documented GOOGLE_SYNC_CONCURRENCY, but publish read
GOOGLE_CALENDAR_SYNC_CONCURRENCY and the client's own setting was never
used. Both now share one value, default 3.
GOOGLE_TOKEN_ENC_KEY and TEST_TOKEN_ENC_KEY were undocumented legacy
names for the same key.
Adds UPLOAD_DIR and a one-line comment for each setting, fixes the
ADMIN_USER_IDS note (there is no /admin page, only /api/admin), and
drops NEXT_PUBLIC_APP_URL.
zod 4 exports the same API from "zod" and "zod/v4" (the same module
objects), and one file already used the root.
Nothing used the Vite React plugin. Node 22 is the version CI and .nvmrc
target, so the Node types now match it.
Starting a run doesn't write the plan item. Home folds the open runs into
each item's status, but Study read the stored status, so its planned row
said Start session while Home said Resume session. Both now go through
withRunUnderWay, with the run statuses Plan already counts as in progress.
The button was hidden on touch screens, so a phone or tablet with a
paired keyboard ran the single-key shortcuts with no way to turn them off
(WCAG 2.1.4). It now sits at the end of the lesson top bar on every
screen, as in the card review. The phone footer stays one control tall,
and the button stays on screen during feedback, where "?" used to open
nothing.
@Ben-K-Jordan
Ben-K-Jordan merged commit e40e172 into main Oct 16, 2026
5 checks passed
@Ben-K-Jordan
Ben-K-Jordan deleted the redesign branch October 16, 2026 13:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant