> Agent-readable docs index: /llms.txt. Download /docs.zip to grep all markdown files locally.

# User Test: Eli (2026-01-25)

## Context

* First run on a machine that is not my development Mac.
* Uses Apple Photos as a source (permission prompt shown and granted).
* Photos library had **Optimize Mac Storage** enabled.

## What went well

* The “no sources”/empty state appeared correctly when no sources were configured.
* After granting Apple Photos permission, the library provisioned and content started loading.
* Even with optimized storage, playback did eventually begin (after an initial blank/loading period).
* After earlier fixes (empty library, settings, Photos permission), the app felt generally usable.

## Observations / Issues

* **Initial loading delay:** After enabling Apple Photos, there was a short period of “nothing happening” (blank screen) before the first clip played.
* **New-user behavior:** We immediately tried to go forward (generating new videos). Several generated clips appeared **black** at first, which was confusing.
  * Root cause: the underlying assets were still downloading from iCloud due to optimized storage; the “black” clips resolved once downloads completed.
* **Optimized storage + multiple layers:** When multiple clips are requested quickly, optimized storage can trigger multiple concurrent downloads.
  * Risk: clips may not download fast enough to start playback before their intended play window is over.

## Takeaways

* The app *can* work with optimized storage, but needs explicit user feedback while assets are downloading.
* The current UX makes it easy for a new user to interpret “still downloading” as “broken”.

## Potential mitigations (ordered by preference)

1. **Show a loading/asset-fetching indicator** when the Photos asset request is in-flight (and/or when playback is waiting on a local file).
2. **Maintain a small “prefetch buffer”** (at least 1 future hypnograph composed/identified ahead of time) so content is ready when the user advances.
3. **If possible, source only from already-downloaded videos** (or strongly prefer them), refreshing the eligible list periodically.
   * Key question: can the Apple Photos API reliably tell whether an asset is local vs. needs download?

## Product/UX notes

* If we intentionally download assets from iCloud to enable playback, users should be told (briefly) that this can use additional disk space.
  * Likely temporary over time as Photos re-optimizes, but users with optimized storage are usually storage-constrained and may care.

## Follow-ups

* Check Eli’s Photos library disk usage after the session to estimate how much space was consumed by pulled-down videos.
* Investigate whether Photos frameworks expose:
  * optimized-storage status, and/or
  * a “local-only” filter (or a way to detect local availability without forcing download).

Other things noted on a fresh installation:

* Default max layers is 5, and it should be 1
* Default Min clip length is 2 seconds, and it should be 5
* The default transition is "crossfade", and it should be "none"
* Both "Images" and "Videos" are on by default for Sources, "Video" should be the defauult with "Images" toggled off.