# Electrotechnique & Electrophysics Sandbox

Three.js + strict TypeScript + Vite, developed in Ubuntu on WSL2.

## Develop

Run in your Ubuntu terminal:

```bash
cd /home/victor/projects/geekedin
npm install
npm run dev
```

Open http://localhost:5173 in your Windows browser. The dev server binds to
127.0.0.1 by default and Vite provides hot module replacement.
Use a browser with WebGL and hardware acceleration enabled.

Node.js 22.12+ is required; `.nvmrc` selects Node 22 if you use nvm.
For a fresh checkout with a lockfile, use `npm ci` for repeatable installs.

## Commands

- `npm run dev`: development server, hot reload.
- `npm run typecheck`: strict TypeScript check.
- `npm test`: physics unit tests with Vitest.
- `npm run test:e2e`: Chromium browser checks with Playwright.
- `npm run build`: type check and production bundle in `dist/`.
- `npm run preview`: preview the production build at http://localhost:4173.

## Eight experiments from PLAN.md

Each lesson has an interactive 3D scene, adjustable parameters, live SI
measurements, governing equations, a short explanation, a challenge and a
model/scales disclosure. Use the subject tabs or these URL fragments:

| Subject | Interactive view | URL fragment |
| --- | --- | --- |
| Electric charge, force and field | Dipole/like charges, field arrows and force on a source | `#field` |
| Electric flux and charge | Move a signed charge through a spherical Gaussian surface | `#flux` |
| Electric potential energy | Vary separation and charge, plot U(r) and field work | `#energy` |
| Electric potential and gradient | Potential landscape with field arrows and a movable probe | `#potential` |
| Capacitance | Vary plate area, gap and applied voltage | `#capacitance` |
| Dielectric materials | Polarization at fixed voltage versus fixed free charge | `#dielectric` |
| Current | Ohmic copper wire with electrons drifting against conventional current | `#current` |
| Semiconducting materials | Intrinsic, n-type and p-type silicon, carrier densities and bands | `#semiconductor` |

Drag to orbit, scroll to zoom, right-drag to pan. Focus the canvas to pan
with arrow keys. Reset the camera independently or reset the current
experiment. Settings survive switching subjects for the current page session.
URL fragments support browser back/forward and direct links. Animations can
be paused, and start paused when reduced motion is preferred. Without WebGL,
lessons, controls and measurements remain usable.

These are teaching models: electrostatics in vacuum, ideal parallel plates,
linear fully filling dielectrics, an Ohmic copper wire at fixed temperature,
and non-degenerate silicon in equilibrium at 300 K. The semiconductor lab
uses approximate reference constants disclosed in the lesson. It does not
model a p–n junction or compare real devices. Geometry, arrow lengths,
carrier populations and animation speeds use explicit visual scales.

In the isolated dielectric experiment, each parameter setting represents
charging the selected geometry in vacuum at the charging voltage, then
disconnecting and filling it with dielectric. Q is fixed while varying κ;
changing geometry or charging voltage prepares a different capacitor state.

## Verification

```bash
npm test
npm run build
# Once per development machine:
npx playwright install chromium
npm run test:e2e
```

The unit suite checks force direction, the potential gradient, energy,
Gauss's law, capacitance, fixed-Q/fixed-V dielectric behavior, current,
drift and semiconductor mass action/neutrality. Playwright checks rendered
content in all eight scenes, parameter changes, reset, history, mobile layout,
pausing and the WebGL fallback. The browser suite starts Vite if necessary.
On a minimal Ubuntu installation, Playwright may require browser libraries;
its installer can identify them (`npx playwright install-deps chromium`).

## Extend

- `src/main.ts`: subject navigation, parameter controls, lesson UI.
- `src/experiments.ts`: lesson definitions, defaults, units and measurements.
- `src/scene/lab.ts`: renderer, orbit controls, resizing and frame loop.
- `src/scene/experiments.ts`: one scene builder per topic.
- `src/scene/primitives.ts`: shared geometry/labels and GPU resource disposal.
- `src/physics/`: framework-independent SI models and unit tests.
- `tests/lab.spec.ts`: real-browser interaction and rendering checks.

Add model calculations under `src/physics/`, then connect an experiment
and a scene builder. Keep physical quantities in SI and perform display
conversion in the lesson definitions.

## WSL2 notes

Keep the project in `/home/victor/projects` for Linux file watching and I/O.
Run Node/npm in Ubuntu rather than mixing Windows and Linux installations.
For VS Code, run `code .` in Ubuntu and use its WSL extension.

If Windows cannot reach localhost, first check the URL printed by Vite (it
may choose another port if 5173 is busy). If WSL localhost forwarding is
unavailable, run `npm run dev -- --host 0.0.0.0` and access the WSL address
shown by `hostname -I`. This exposes the development server on available
interfaces; use it only on a trusted development network.

If file changes do not reload on a mounted Windows filesystem, move the
project into the Linux filesystem. Polling can be enabled in Vite config if
needed, but is unnecessary for the default project location.

## References

- [Vite getting started](https://vite.dev/guide/)
- [Three.js installation](https://threejs.org/manual/pages/installation.html)
- [OpenStax University Physics Volume 2](https://openstax.org/details/books/university-physics-volume-2)
- [OpenStax band theory of solids](https://openstax.org/books/university-physics-volume-3/pages/9-5-band-theory-of-solids)