# DESIGN — rules for the `soul` 3D models (`home.html`, `dome.html`)

These rules are binding on every change. The machine-checkable ones are enforced by the
`node:test` suites in `home/*.test.js` and must stay green.

## Architecture & modularity
- **One concern per module.** `geometry.js` = pure layout math; `walls.js` = walls; `slabs.js`
  = horizontal plates + stairs; `utils.js` = **all furniture** — reusable object components AND
  the room assemblies (e.g. `createKitchen`) that place them. `home.html` merely assembles.
- **ALL furniture work lives in `utils.js`** (there is no per-room file). Room assemblies place
  `utils` components and compute positions from the room basis — they never model raw boxes.
- **Repeated detail becomes a component** (a named builder). Never copy-paste geometry. DRY.
- Dense, explanatory comments. Preserve every `FIX HISTORY` / `DO NOT` note **verbatim**.

## Testing
- Every module's layout math (dimensions, placement, containment) is a **pure, THREE-free
  function** with `node:test` coverage in `home/*.test.js`. Tests must pass before shipping.
- `utils.js` therefore splits into pure exports (`roomBasis`, `roomPoint`, `inRoom`,
  `boxInRoom`, …) that node can test, and a `createUtils({THREE, GEO})` factory that only wraps
  those results in meshes.

## Geometry rules
- **No CSG / boolean geometry.** Openings are part of the mesh outline (Shape/extrude). No
  triangulation slivers or T-junctions (see the `slabs.js` `mediumFrontBulgeNotch` FIX HISTORY).
- **Metres**, always. Shared constants come from `GEO` (`SLAB_T`, `FLOOR_H`, `WALL_T`, …).
- **Everything rests on its floor:** a furniture object's lowest point sits on the ground-slab
  top (`y = SLAB_T`). Nothing floats or sinks.
- **Furniture stays inside its footprint:** no part crosses a bounding wall or guide line.
  (`boxInRoom` checks this in room coordinates.)
- **Hang only on solid walls.** Wall-mounted items (wall cabinets, hoods) attach to solid walls,
  never to a glazed bay or an open side.
- **Orient to the basis.** Objects are placed with their wall/room basis (`ex`, `ey`, up), never
  axis-aligned to world X/Z by guesswork.

## Workflow
- The dev server caches JS — reload with a unique `?v=N` query and hard-refresh (Ctrl+Shift+R).
- **No scratch / debug render or screenshot files.** The user verifies visually.