Home Page Contract

Purpose

Home provides a user-maintained landing page for the local archive. It combines a database-backed image gallery 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 homepage gallery and Markdown.
`/homepage/edit`	`/ui/homepage/edit`	Upload images, manage image metadata, 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 featured homepage image (photo.is_primary) is shown first; remaining images are shown in random order.
The current image appears in the shared dark-room viewer with its description.
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.
The same Home Text content is also editable from Settings → Home Page Text.

Edit Behavior

The image upload accepts JPEG, PNG, GIF, WebP, BMP, and TIFF files and supports multi-file uploads.
A successful upload immediately stores files in the shared photo table/media layout and displays a positive notification.
The editor supports per-image description edits, setting a featured image, and deleting the current image.
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 markdown text is mutable application data at UPLOAD_DIR/homepage.md.
Homepage images are stored as photo rows (person_id = NULL) with files under UPLOAD_DIR/photos/.
Uploaded images are renamed to {photo_id}{suffix}.
Homepage images are database records; markdown remains file-backed.

Acceptance Checklist

/, /ui, and the application brand reach Home.
Home renders with or without stored Markdown and image content.
Edit loads existing Markdown.
Supported image upload stores one or more images and makes the first image featured when no featured image exists yet.
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 markdown storage location is UPLOAD_DIR/homepage.md and must remain writable in the active runtime environment.
Uploading an image is immediate and is not rolled back by Cancel.

2.9 KiB Raw Blame History