# Home Page Contract

## Purpose

Home provides a user-maintained landing page for the local archive. It combines one current image with Markdown text and lets the operator edit both without changing application source or prompt assets.

## Routes

| Route | Browser path | Purpose |
| --- | --- | --- |
| `/homepage` | `/ui/homepage` | View current homepage image and Markdown. |
| `/homepage/edit` | `/ui/homepage/edit` | Upload an image and edit Markdown. |

The application root and `/ui` redirect to `/ui/homepage`.

## View Behavior

- The visible page heading is **Home**; the browser tab title is **VibeScribe Home**.
- The latest homepage image appears in the shared dark-room viewer.
- Saved Markdown is rendered in the **Home Text** card.
- Missing text displays `No homepage text saved yet.`
- Missing image displays the viewer's empty state.
- **Edit Home Page** opens the edit route.

## Edit Behavior

- The image upload accepts JPEG, PNG, GIF, WebP, BMP, and TIFF files.
- A successful upload immediately stores the file, updates the preview to that image, and displays a positive notification.
- The Markdown textarea is initialized from the currently stored homepage text.
- **Save** writes the textarea content, displays `Homepage saved`, and returns to Home.
- **Cancel** returns to Home without saving textarea changes. An image already uploaded during the edit session remains stored.

## Storage Contract

- Homepage content is mutable application data under `data/homepage`.
- Markdown is stored in `homepage.md`.
- Uploaded images keep a sanitized basename.
- The view selects the supported image with the most recent modification time.
- Homepage files are not transcription prompts and are not database records.

## Acceptance Checklist

- `/`, `/ui`, and the application brand reach Home.
- Home renders with or without stored Markdown and image content.
- Edit loads existing Markdown.
- A supported image upload updates the preview and becomes the latest homepage image.
- Save persists Markdown and returns to Home.
- Cancel does not save changed Markdown.

## Implementation Anchors

- `src/transcription/ui/pages/home_page.py`
- `src/transcription/ui/homepage_store.py`
- `src/transcription/ui/components/app_shell.py`
- `tests/ui/test_upload_page.py`
- `tests/ui/test_navigation_and_mounts.py`
- `tests/ui/test_pages_registration.py`

## Known Limitations

- Homepage storage location is configured by application settings and must remain writable in the active runtime environment.
- Uploading an image is immediate and is not rolled back by Cancel.
- The editor does not currently delete or select among previously uploaded images.