Improve 3D gallery UX, placeholders, and image accuracy.

Add multi-row dynamic halls, eye-level camera, canvas covers for missing works, preserved view when returning from detail, and corrected image overrides for Kauffman and Raphael. Update documentation and add fetched painting assets.

Co-authored-by: Cursor <cursoragent@cursor.com>

Documentation/basics.md

@@ -80,17 +80,30 @@ Each artist has **exactly one hall**. The hall is a rectangular room sized to fi
 
 | Rule | Implementation |
 |------|----------------|
-| One hall per artist | `VirtualGallery.tsx` builds a single room from that artist’s paintings and periods |
-| Paintings on walls | Works hang on the **back, left, and right** walls at eye level; periods are distributed across walls |
+| One hall per artist | `VirtualGallery.tsx` builds a single room from that artist’s paintings |
+| Paintings on walls | Works hang on the **back, left, and right** walls; the room **grows and uses multiple rows** when the catalog is large (e.g. 75+ works) |
+| Eye-level viewing | Frame centres sit at **eye height (~1.65 m)**; the camera stays **level with the floor** (no pitch up/down) |
 | Open centre | Floor and ceiling only — no columns, pedestals, or other centre objects |
 | Single exit | One doorway on the **front wall**; walk to it or click it |
 | Hall-to-hall travel | Exit opens a panel: **Predecessors** (left) and **Successors** (right), each grouped by art movement |
+| Missing images | Works without a local file show a **draped canvas cover** in the frame (not a blank white rectangle) |
+| Detail view return | Opening a painting close-up **keeps the 3D hall mounted** in the background so position and view direction are preserved when you go back |
 
-**Controls:** `WASD` / arrow keys to move; click a painting to open its detail view. At the exit, click the doorway or press `E` to choose the next artist.
+**Controls:**
+
+| Input | Action |
+|-------|--------|
+| `W` / `↑` | Walk forward |
+| `S` / `↓` | Walk back |
+| `A` / `←` / `Q` | Turn left |
+| `D` / `→` | Turn right |
+| Mouse drag | Look left / right (same direction as keyboard turns) |
+| Click painting | Open detail view |
+| Exit doorway / `E` / **Exit →** header button | Open path picker |
 
 Predecessors and successors come from the **painting influence graph** (`painting_influences` → other artists). Empty lists mean no influence edges are recorded yet for that artist — run `npm run update-influences` or extend seed data.
 
-**3D images** use locally cached files only (`galleryImageUrl` in `client/src/api/client.ts`). Remote fetches are too slow for realtime WebGL textures; call `POST /api/artists/:id/preload-images` before entering a hall to link disk files.
+**3D images** use locally cached files only (`galleryImageUrl` in `client/src/api/client.ts`). Remote fetches are too slow for realtime WebGL textures; call `POST /api/artists/:id/preload-images` before entering a hall to link disk files. While a texture is loading, the frame shows the canvas cover instead of a white placeholder.
 
 ## Key design decisions
 

Documentation/data-and-images.md

@@ -63,6 +63,7 @@ When no image is available:
 
 - `/placeholder-portrait.svg` — timeline / movement band portraits
 - `/placeholder-art.svg` — paintings in lists and detail view
+- **3D gallery** — draped **canvas cover** inside the frame (`CanvasCover` in `VirtualGallery.tsx`); shown when there is no local file, the fetch failed, or the texture has not loaded yet
 
 These live in `client/public/` (and `client/dist/` after build).
 
@@ -75,4 +76,16 @@ These live in `client/public/` (and `client/dist/` after build).
 
 ## Image fetcher overrides
 
-`scripts/image-fetcher.js` includes hand-maintained overrides for ambiguous Wikipedia titles and direct URLs (e.g. works whose Commons name does not match the article title). Extend `PAINTING_WIKI_OVERRIDES` and `DIRECT_IMAGE_OVERRIDES` when automated resolution fails.
+`scripts/image-fetcher.js` includes hand-maintained overrides for ambiguous Wikipedia titles and direct URLs (e.g. works whose Commons name does not match the article title, or when museum search returns the wrong work). Extend these maps when automated resolution fails:
+
+| Map | Use when |
+|-----|----------|
+| `PAINTING_WIKI_OVERRIDES` | DB / seed title should resolve to a different Wikipedia or Wikidata label |
+| `DIRECT_IMAGE_OVERRIDES` | You know the exact Commons URL (bypasses Met / Art Institute false matches) |
+
+Examples already in the repo:
+
+- `Self-Portrait Hesitating` → Kauffman, Wikimedia Commons (National Trust)
+- `Cherubs of the Sistine Madonna` → Raphael’s putti detail, Wikimedia Commons
+
+After adding an override, delete any wrong cached file under `data/images/paintings/` and re-run fetch or call the on-demand image endpoint for that painting.

Documentation/setup.md

@@ -98,7 +98,9 @@ After clone: copy `.env.example` → `.env`, install dependencies, run `npm run
 |---------|--------------|-----|
 | Empty timeline | DB not seeded | `npm run seed` |
 | 500 on all `/api/*` | Wrong `.env` or Postgres down | Check connection, logs |
-| Black frames in 3D gallery | No local image for painting | `POST …/preload-images` or `npm run fetch-images` |
+| Black frames in 3D gallery | No local image for painting | `POST …/preload-images` or `npm run fetch-images`; missing works show a canvas cover |
+| White/grey flicker on frames | Texture loading or z-fighting with wall | Rebuild client (`cd client && npm run build`); ensure latest `VirtualGallery.tsx` |
+| Wrong painting image | Bad museum / search match | Add entry to `DIRECT_IMAGE_OVERRIDES` in `scripts/image-fetcher.js`, re-fetch file |
 | Empty exit navigation lists | No `painting_influences` edges for artist | `npm run update-influences` or extend seed data |
 | Default Vite page instead of gallery | `client/dist` missing or stale | `cd client && npm run build` |
 | Permission denied creating tables | `gallery` user lacks CREATE | Run admin grants, then migrate |