Improve timeline UX and add catalog restore scripts for paintings and portraits.

Load the home-page catalog once with a lightweight artists API, batch pan/zoom updates per frame, use dynamic year labels, and speed up movement-flow zoom. Add sync-image-paths and fetch-artist-images plus docs for the post-seed pipeline.

Documentation/basics.md

@@ -53,6 +53,10 @@ Gallery/
 │   │   └── utils/timelineView.ts          # Shared zoom/pan math for timeline + movements
 │   └── dist/            # Production build (served by API when present)
 ├── scripts/             # Seed, bios, catalog expansion, image fetch, checkup tools
+│   ├── seed-wikipedia.js
+│   ├── seed-catalog-data.js
+│   ├── sync-image-paths.js
+│   ├── fetch-artist-images.js
 │   ├── fetch-artist-bios.js
 │   ├── expand-paintings.js
 │   ├── famous-paintings-data.js
@@ -92,7 +96,7 @@ npm run dev:server   # API on PORT from .env (3520 production, 3001 typical dev)
 npm run dev:client   # Vite on :5173, proxies /api and /images to PORT
 ```
 
-Use the Vite URL during frontend work for HMR.
+Use the Vite URL during frontend work for HMR. When the public domain is proxied to Vite (see [`deploy/nginx-gallery.conf`](../deploy/nginx-gallery.conf)), both `dev:server` and `dev:client` must stay running or visitors see **503**.
 
 ## User navigation flow
 
@@ -132,12 +136,26 @@ The home page shows two linked views over the **same year window** (`viewStart`
 | Era bar | `Timeline.tsx` | Historical eras, major event markers, click-to-zoom |
 | Movement flow | `MovementBands.tsx` | Curved streams per movement, lineage branches, artist portraits |
 
-Both views share zoom/pan behaviour via `client/src/utils/timelineView.ts`. The home page uses a **fixed viewport** (`100vh`): timeline + movement flow sit in a shared `home-timeline-stack` so event guide lines can extend from the era bar down through the movement canvas. The movement flow compresses vertically so all movements in the visible year range fit without page scrolling.
+Both views share zoom/pan behaviour via `client/src/utils/timelineView.ts` (`zoomTimelineView`, `panTimelineView`, `chooseTimelineTickInterval`, `createViewChangeScheduler`). The home page uses a **fixed viewport** (`100vh`): timeline + movement flow sit in a shared `home-timeline-stack` so event guide lines can extend from the era bar down through the movement canvas. The movement flow compresses vertically so all movements in the visible year range fit without page scrolling.
+
+### Timeline data loading
+
+On first visit, `HomePage.tsx` fetches the full catalog once:
+
+1. `GET /api/bounds` — initialise the year range.
+2. `GET /api/timeline?start=…&end=…` — all eras and movements for that range.
+3. `GET /api/artists?timeline=1` — lightweight artist rows (portraits, lifespan, movement colour; no full biography text).
+
+Pan, zoom, and era/event click-to-zoom only update **local** `viewStart` / `viewEnd` state. `MovementBands.tsx` and `Timeline.tsx` filter what is visible for the current window — they do not trigger new API calls. The “Loading art history…” message appears only until the first successful load completes.
+
+View updates are **batched to one commit per animation frame** via `createViewChangeScheduler()` in `timelineView.ts` (`HomePage.tsx` → `handleViewChange`), so rapid scroll-wheel events do not flood React with separate renders.
 
 ### Timeline year labels
 
 Year ticks along the bottom of the era bar use **large, high-contrast** labels (bold cream text with shadow). The active range in the control row (e.g. `1400 CE — 1900 CE`) uses the same stronger styling.
 
+Label density is **dynamic**: `chooseTimelineTickInterval()` in `timelineView.ts` picks a “nice” step (1, 2, 5, 10, … 5000 years) from the visible span and measured bar width so labels stay ~76 px apart. Zoomed-out overviews show fewer dates; zooming in reveals finer steps automatically.
+
 ### Timeline controls
 
 | Input | Action |
@@ -165,7 +183,7 @@ Each visible movement is drawn as a **portrait-width curved stream** (~54 px str
 | Vertical depth | Successor movements sit on rows below their deepest parent; sibling movements at the same depth are spread into lanes to limit overlap |
 | Branch connectors | Smooth curves from the **centre** of a parent stream to the **centre** of each child stream (siblings fan out along the parent’s length) |
 | Visual blending | Path-aligned SVG gradients with transparent fades at stream ends and branch junctions; streams draw on top of branches so overlap brightness stays uniform |
-| Filtering | Same rule as the API: only movements with at least one artist active in the visible year range |
+| Filtering | Same rule as the API: only movements with at least one artist active in the visible year range (filtered client-side after initial load) |
 | Viewport layout | Row height and stream width scale from measured canvas size so every visible movement row fits in the remaining screen space |
 
 ### Artists on movement streams
@@ -184,12 +202,14 @@ Each artist appears as a **portrait circle** on their movement’s stream row:
 
 | Input | Action |
 |-------|--------|
-| Scroll wheel on flow canvas | Zoom (same range as timeline) |
+| Scroll wheel anywhere on flow canvas | Zoom (same year range as timeline; works over portraits and labels too) |
 | Drag on flow canvas | Pan |
 | Click portrait | Open artist biography |
 | Click **movement name** (label on stream) | Open **movement gallery** for that movement |
 
-Artist portraits stop wheel/drag propagation so zooming over a face does not fight portrait clicks. Hovering a portrait highlights the artist’s lifespan on the era bar and brightens their segment on the movement stream.
+**Zoom/pan performance:** The movement canvas uses a **capture-phase** wheel listener so scroll zoom works even when the cursor is over a portrait. While scrolling or dragging, a short **interaction mode** (~120 ms after the last input) draws simplified solid SVG strokes and temporarily hides portrait/label DOM so zoom stays responsive; full gradients and portraits return when you stop.
+
+Only **mousedown** on portraits and movement labels stops propagation (so drag-to-pan does not start when clicking them). Hovering a portrait highlights the artist’s lifespan on the era bar and brightens their segment on the movement stream.
 
 **Note:** Movement lineage is **frontend curation** for layout and labels — it is not stored in PostgreSQL. Painting influence links live in **`painting_influence_sources`** (paintings, artists, or movements as sources). The API reads that table for detail panels, hall navigation, and `has_influence_links`. The legacy **`painting_influences`** table is still written in parallel when curators add painting-to-painting edges but is not queried for display.
 
@@ -309,6 +329,8 @@ Next to the toggle, **Show more** (checkbox, persisted in `localStorage`) opens
 ## Key design decisions
 
 - **Timeline bounds** derive from the earliest art movement start year, not ancient-era metadata alone, so the default view opens where catalogued content begins.
+- **Timeline catalog** loads once from the API; pan/zoom is client-side only, with per-frame batching via `createViewChangeScheduler()`.
+- **Movement flow interaction** uses simplified SVG and hides portrait DOM during active scroll/drag so zoom stays responsive over dense portrait fields.
 - **Movement filtering** on zoom only shows movements that have at least one artist active in the visible year range.
 - **Movement lineage** (`movement-lineage.ts`) documents art-historical predecessor→successor links for the flow diagram; extend that file to add or correct branches.
 - **One hall per artist** keeps navigation predictable: enter from the timeline or bio, leave via the single exit or back button.