Reveal
Reveal is a personal native macOS photo workflow app (Tauri 2, Rust, wgpu, Svelte 5) designed around one loop: ingest, cull, develop, and publish to Obsidian/Garden with minimal friction.
What it is
- A menu-bar + window app for high-volume photo sessions.
- A file-first system: originals stay untouched, metadata stays in sidecars, and the app index is disposable.
- A stage-based architecture: Ingest -> Develop -> Print, with plugin seams for each stage.
Core rules
- Archive layout follows the
date_folderspattern (Settings; default%Y/%Y-%m-%d, e.g.2026/2026-09-14/), based on capture date. - Keep original filenames on import and export.
- The folder on disk is the source of truth, not app-internal state.
What it does today
- Import from a mounted card into the archive, filed by capture date. A library never nests inside another, and an import never creates one.
- Browse and cull in a grid or masonry layout, with a single-photo view, zoom and loupe, ratings, a quick collection, and a keyboard shortcut for nearly everything.
- Apple Photos & Immich can be connected as catalogues next to your folders — browsed, rated and developed directly without copying files into local folders.
- Develop non-destructively with interchangeable engines: Spektra, a film simulation built on
spektrafilm-rs, and Rapid, a GPU digital engine with tone curves, LUTs, and scopes. The recipe lives in an.xmpsidecar next to the RAW; the developed preview is a plain JPEG any tool can read. - Tidy a folder: preview what filing it by the import rule would do (supporting RAWs, standalone JPEGs, and multimedia companion files), then apply it with a confirmation click. A photo moves with all its companions or not at all, nothing is overwritten, and a failed move is rolled back.
- Story mode: compose a folder’s photos and prose as a markdown note, then publish it to a Standard Garden site, export it, or write it to an Obsidian daily note.
- Multicast export (Immich & Google Photos): automatically upload developed JPEGs upon export to your self-hosted Immich server and/or your Google Photos library, keeping the local folder as the single canonical source of truth.
- Updates: Reveal checks for a newer version shortly after it opens, shows the release notes, and installs it on request.
Install
Download Reveal.dmg from the latest release. Reveal is built for Apple silicon only and is not notarized by Apple, so the first launch needs right-click → Open. The site’s install page walks through it. After that, it updates itself.
Build & develop
pnpm devruns the app in development;pnpm dev:webruns the frontend alone in a browser.pnpm buildruns./install.sh: it rebuilds and installs/Applications/Reveal.app. Run it after changing the app — icon, tray and window chrome are baked at bundle time, so the installed copy keeps showing the previous build until you do. It refuses to run while Reveal is open. It also emptiessrc-tauri/target/debugfirst (the test and check output, about 20 GB, never used by the installed app): the tests you run stay available until the next build.pnpm testruns the unit tests and the jsdom tests intests/(they mount whole screens, up to the full app against a fake Tauri backend),pnpm checkruns svelte-check,cargo test(insrc-tauri) runs the Rust tests.- Versions and releases:
node scripts/release.mjs <patch|minor|major> --tag, thennode scripts/publish.mjs.
Architecture (short)
Index(SQLite) is a derived cache and can be rebuilt at any time.Contact Sheetreads from the index and drives browsing performance.- Editing/develop settings are persisted to sidecars and mirrored to index fields for speed.
- Story content is stored in folder-local markdown (
<date>.md) with frontmatter + body. - Every write of user data goes through
reveal-io(src-tauri/crates/reveal-io): sidecars, story notes, the daily note, preview sidecars, exports, published pages, and the import copy. The files live on a NAS that times out (os error 60), goes stale or drops a write into the page cache, so one rule covers them all: retry the errors a NAS recovers from at 0.4 / 1.5 / 4 s, and write by temp file,fsync, read-back, rename. Do not add a barefs::writefor something a person made. The recipe save queue in the webview (saveRecipeSoon) is a second, slower layer on top of it. - A photo’s picture is served by one module,
src-tauri/src/thumb.rs(reveal://thumb): parse the request, local cache, offline fallback, wait for a slot, then climb the ladder of sources (developed sidecar → embedded preview → companion JPEG → neutral render → plain image). The order of that ladder is a tested function; do not add a branch to the protocol handler inlib.rs. Who decodes next isthumb_queue.rs: newest request first (the cells on screen), and a request nobody has waited for in 20 s is dropped.
Product direction
- Keep the daily workflow fast and simple.
- Keep deep technical controls available but out of the way.
- Keep plugin seams clean so engines can evolve without rewriting the app shell.