Astra!ny-start

1 files changed, 49 insertions, 141 deletions

diff --git a/README.md b/README.md
index c3eb7b9..ce86f3a 100644
--- a/README.md
+++ b/README.md
@@ -1,150 +1,58 @@
-# Electrotechnique & Electrophysics Sandbox
+# Fieldwork · Electrophysics
 
-Three.js + strict TypeScript + Vite, developed in Ubuntu on WSL2.
+An interactive 3D learning lab built with TypeScript, Vite, Three.js, and KaTeX.
+`PLAN.md` controls the subject scope. The only implemented subject is **Electric flux and charge**.
 
-## Develop
+## Run locally
 
-Run in your Ubuntu terminal:
+Use Node 22 (at least 22.12.0), as specified in `.nvmrc`.
 
-```bash
-cd /home/victor/projects/geekedin
+```sh
 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
-
-The app now opens with **Test 4 in 3D**, a guided study collection based on
-`docs/Test_4.md` and `docs/Test_Answers.md`. Select **All experiments** to
-return to the original eight subjects. All previous subject links work.
-
-| Test question | 3D learning activity | URL fragment |
-| --- | --- | --- |
-| 1 · Work by the electric force (30p) | Compare straight and curved paths with the same endpoints | `#test-work` |
-| 2 · Energy conservation (15p) | Exchange potential and kinetic energy while keeping the total constant | `#test-conservation` |
-| 3 · Central field (55p) | Radial motion, U(r), signed work and the exact reference at infinity | `#test-central` |
-| 4 · Charge assembly (25p) | Build a tetrahedral configuration, counting each pair once | `#test-assembly` |
-| 5 · Uniform field (25p) | Project an angled displacement along E | `#test-uniform` |
-| 6 · Dipole rotation (50p) | Inspect force couples, signed torque, rotation work and U(θ) | `#test-dipole` |
-
-Each question includes its original scope and subparts, adjustable numerical
-examples, live observations, expandable derivations and a prediction with a
-revealable explanation. Journey/rotation sliders select a position or angle,
-not elapsed time. The original Markdown questions and answers are available
-from the lesson links, including in the production build. Test 4A and 4B each
-carry 100 points. These are teaching examples rather than an automatic grader.
-
-Equations, derivations, inline lesson notation, control symbols and mathematical
-3D annotations use KaTeX with locally bundled fonts and accessible MathML.
-Long equations scroll within their own containers on narrow screens. Scene
-annotations follow the camera through a CSS2D overlay, leaving orbit controls
-usable.
-
-The added models are in `src/physics/test4.ts`, lesson content in
-`src/test4.ts`, scene builders in `src/scene/test4.ts`, and browser coverage
-in `tests/test4.spec.ts`.
-
-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
-```
+Open the local URL printed by Vite. `npm run build` type-checks and builds the app into `dist/`; `npm run preview` serves that build. `npm run typecheck` runs TypeScript separately.
+
+No test scripts or test files were created for this implementation. The pre-existing test commands and dependencies in `package.json` are retained, but there is no test suite in the current working tree.
+
+## The experiment
+
+- Change a point charge from −5 to +5 nC and move it along the x-axis.
+- Choose a sphere or cube and change its radius or half side length.
+- Compare enclosed charge, surface area, and exact net flux.
+- Try positive, negative, and external-charge presets.
+- Toggle the surface, field lines, and outward normals.
+- Drag to orbit; scroll to zoom. Focus the canvas and use arrow keys to orbit, `+`/`−` to zoom, and `Home` to reset. All other controls are native keyboard-operable inputs.
+
+The model assumes a stationary ideal point charge in vacuum. The imaginary Gaussian surface is centered at the origin. Geometry uses metres, physics uses SI units, and the interface presents charge in nanocoulombs. A nonzero charge exactly on the surface produces an undefined enclosed-charge/flux result because its field is singular there. The visible marker's radius does not change the point-charge model. Sampled lines and fixed-size arrows illustrate field direction; total flux is calculated analytically, never by counting those lines.
+
+Reference: `docs/theory/3Electric flux and charge.pdf`, sections 3.2–3.4. Lesson copy and graphics are original, based on these definitions.
+
+## Add another 3D model
 
-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)
+1. Enable its subject in `PLAN.md` first.
+2. Create `src/models/<model-id>/` with separate physics, state, scene, and view modules.
+3. Implement `ModelDefinition` from `src/core/model.ts`. `mount(host, { i18n })` renders into its host and returns a `ModelInstance` whose `dispose()` releases listeners, GPU resources, and observers.
+4. Add its title, controls, explanations, accessibility text, and messages to `src/i18n/en.ts`.
+5. Register a lazy-loading definition in `src/models/registry.ts`. The current shell mounts its first entry. Add model selection to the shell when a second enabled model is implemented; each model's physics and scene remain independent.
+
+`src/models/electric-flux/physics.ts` has no dependency on DOM, Three.js, or translations. Rendering consumes physical field directions; it does not own the equations or measurement state. Scenes render only when controls, state, or viewport size changes.
+
+## Add a language
+
+English (`en`) is the default and fallback. User-facing copy is in `src/i18n/en.ts`, accessed through stable typed keys. Messages accept named parameters and numbers use `Intl.NumberFormat`.
+
+To support another language, add its catalog and register its BCP 47 locale in `src/i18n/index.ts`. Pass that locale to `createI18n` in the shell. Missing messages fall back to English. No physics or model components need rewriting. Add a language selector only once another language has been requested and supplied.
+
+## Layout
+
+```text
+src/core/                    Shared model lifecycle contract
+src/i18n/                    English catalog, locale registry, formatting
+src/models/registry.ts       Enabled, lazy-loaded models
+src/models/electric-flux/    Pure physics, state, Three.js scene, lesson view
+src/ui/                      Shared interface graphics
+src/main.ts                  Application shell
+src/style.css                Responsive presentation
+```