NeuronLab Frontend V2

NeuronLab Frontend V2 is a standalone Next.js prototype for a mathematics-first machine-learning learning flow. Authentication, curriculum, lessons, code execution, reasoning, visualization jobs, profiles, and progress are deterministic browser-local simulations. No backend process is required.

Requirements and setup

• Node.js 20.9 or newer
• npm
• Chromium for Playwright browser tests

npm install
npx playwright install chromium
npm run dev

Open http://localhost:3000. To exercise a production build manually:

npm run build
npm run start

Scripts

Command	Purpose
npm run dev	Start the Next.js development server.
npm run build	Create the production build.
npm run start	Serve an existing production build.
npm run lint	Run ESLint.
npm run typecheck	Run strict TypeScript checking without emitting files.
npm test	Start Vitest in watch mode.
npm run test:run	Run the unit and integration tests once.
npm run test:e2e	Run the functional Playwright specs in tests/e2e.
npm run test:accessibility	Run the route accessibility specs in tests/accessibility.
npm run test:visual	Run the visual-contract specs in tests/visual.
npm run check	Run lint, typecheck, Vitest, and the production build in sequence.
npm run doctor	Run React Doctor and return JSON diagnostics.

Playwright owns one production server at http://127.0.0.1:3116, uses one desktop Chromium project, and lets individual specs resize their own viewport. The server is never reused. Traces, videos, screenshots, and explicit test evidence are written under test-results/.

Use --list to inspect discovery without starting the server or running a browser:

npm run test:e2e -- --list
npm run test:accessibility -- --list
npm run test:visual -- --list

Routes

Route	Access	Purpose
/	Public	Landing page, curriculum preview, and entry to the local diagnostic.
/login	Public	Sign in with a deterministic mock account.
/register	Public	Create a browser-local mock identity.
/diagnostic	Local session required	Complete or review the two-question placement diagnostic.
/dashboard	Local session required	Review placement, learning progress, activity, and next actions.
/learn	Local session required	Browse the fixture-backed learning roadmap.
/learn/[module]/[lesson]	Local session required	Work through a staged lesson; unknown fixture IDs return not found.
/problems	Local session required	Browse deterministic practice states and readiness.
/problem/[id]	Local session required	Use the focused Monaco problem workspace; unknown fixture IDs return not found.
/profile	Local session required	Review the current learner's local fixture and activity summary.
/settings	Local session required	Select a theme and reset the current learner's progress.
/showcase	Public	Inspect the design-system, application-shell, and focus-shell specimens.

Mock accounts and local data

Learner	Email	Password
Ada Lovelace	ada@example.test	vector123
Raka Pratama	raka@example.test	matrix456

Registration creates another local identity from the submitted name and email; it does not create a remote account. The browser stores:

• the current mock session at neuronlab.mock-session;
• each learner's progress at neuronlab.learning.v1.<userId>;
• theme preferences at neuronlab.theme and neuronlab.colorMode.

The reset action in /settings removes only the signed-in learner's progress. It preserves the session, theme, unrelated keys, and other learners' records. For a complete local reset, clear site data in browser developer tools or run this in the console and reload:

localStorage.clear();
location.reload();

Fixtures and test layout

• src/mocks/contracts.ts: Zod contracts for mock users, content, execution, profiles, reasoning, and visualization jobs.
• src/mocks/fixtures.ts: deterministic users, credentials, curriculum, lessons, problems, and result/event fixtures.
• src/mocks/service.ts: asynchronous in-process adapter used by the UI; it performs no HTTP requests.
• src/state/learning-schema.ts and src/state/learning-store.ts: versioned, user-scoped browser progress.
• src/theme/presets/: 42 pinned OpenChamber variants grouped into 21 selectable families.
• src/**/*.test.{ts,tsx}: Vitest unit and integration coverage.
• tests/e2e, tests/accessibility, and tests/visual: Playwright functional, accessibility, and visual-contract suites.

Monaco is bundled from the pinned monaco-editor npm package. src/features/problems/code-editor.tsx configures that local module directly, and src/features/problems/monaco-editor.worker.ts supplies its bundled worker. The editor does not use a CDN.

Prototype boundaries

• Runtime product data never calls a NeuronLab backend or third-party API. The mock service uses deterministic fixtures, local timers, and in-process async generators.
• Login and registration are demonstrations, not production authentication. There is no password security, account recovery, remote persistence, or cross-device sync.
• Code execution selects deterministic fixture outcomes; it does not run arbitrary code in a sandbox.
• Reasoning and Manim progress are fixture streams. The visualization surface reports fixture metadata rather than fetching or rendering remote media.
• Local storage is the only persistence boundary and can be cleared by the browser or user.

A future backend integration should replace the focused mock-service/auth/storage adapters with contract-validated network adapters while preserving the existing UI contracts. Backend connectivity, real authentication, sandboxed execution, durable storage, sync, and production security remain outside this prototype.

Themes and third-party notices

The theme picker exposes 21 families and their 42 light/dark variants vendored from OpenChamber commit eb9a2140a97c6412d0839d130c21b1fa1d2fa906. Attribution and the installed HeroUI package-license metadata are recorded in THIRD_PARTY_NOTICES.md. Those notices do not declare a license for NeuronLab itself.

Troubleshooting

• If Chromium is missing, run npx playwright install chromium.

• Playwright requires port 3116 to be free because it deliberately refuses to reuse another server.

• If stale prototype state changes the route you see, perform the complete local reset above.

• Development mode loads React Scan and React Grab from unpkg.com. For offline work, strict no-external-request checks, or Content Security Policy troubleshooting, opt out before starting Next.js:

  NEXT_PUBLIC_DISABLE_REACT_DEVTOOLS=1 npm run dev

• Playwright already sets NEXT_PUBLIC_DISABLE_REACT_DEVTOOLS=1 and NEXT_TELEMETRY_DISABLED=1 for its production server.