generated from john/python-template
64 lines
2.6 KiB
Markdown
64 lines
2.6 KiB
Markdown
# 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.
|