# Build Guide

## Architecture

The site is deliberately static:

- `index.html` contains semantic interface structure and accessible dialogs.
- `css/styles.css` contains the full visual system and responsive layouts.
- `js/data.js` exposes the story data without requiring network requests.
- `js/app.js` handles rendering, pan/zoom, layer toggles, journey playback, dialogs, search, settings, and accessibility states.
- `assets/meshes/` contains independent transparent SVG map layers.
- `assets/icons/` contains standalone interface and story symbols.
- `assets/images/` contains raster atmosphere, map, event, and character artwork.

## Map coordinate model

Each event, place, and map character uses percentage coordinates:

```json
{"x": 45, "y": 55}
```

`x: 0, y: 0` is the upper-left of the map. `x: 100, y: 100` is the lower-right. This keeps markers aligned as the viewport resizes.

## Adding a new event

1. Add an image to `assets/images/events/`.
2. Add a numbered marker SVG to `assets/icons/` if the event exceeds 10.
3. Add the event record to `assets/data/events.json` and `js/data.js`.
4. Include `x`, `y`, title, summary, detail, narrator, motif, and image values.
5. Reload the page; both the map marker and event rail are generated automatically.

## Replacing the map

Replace `assets/images/yoknapatawpha-clean-base.webp` with another 4:3 image. Keep the same filename to preserve references. The vector layers can be edited independently:

- `terrain-mesh.svg`
- `water.svg`
- `roads.svg`
- `route.svg`
- `settlements.svg`

All use a `1000 × 750` viewBox.

## Accessibility requirements

When adding controls:

- Use native buttons and dialogs.
- Supply an accessible name.
- Maintain visible keyboard focus.
- Respect the reduced-motion setting.
- Do not place essential information only inside images.

## Recommended next phase

A second phase could add:

- Chapter-to-map synchronization for all 59 narrator sections
- Student annotation and export
- Audio ambience with user-controlled volume
- A narrator-filter layer
- Citation popovers linked to exact passages
- Optional Three.js terrain extrusion using the existing SVG relief mesh