init

1 files changed, 120 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..916cb69
--- /dev/null
+++ b/README.md
@@ -0,0 +1,120 @@
+# 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)