# Presto App Guidance

This directory contains MicroPython apps for the Pimoroni Presto. The main app is
`main.py`, deployed to the device as `main.py`.

## Context To Read First

- Read `README.md` before changing setup, deployment, user-facing behavior, or API response assumptions.
- Read `main.py` before changing layout, touch handling, networking, display sleep, or performance-sensitive code.
- The root project conventions still apply, but most Phoenix/Elixir conventions are not relevant inside `presto/`.

## Deployment And Verification

```bash
mise run presto                     # deploy and reset
```

Manual deployment:

```bash
mpremote fs cp main.py :main.py
mpremote fs cp secrets.py :secrets.py
mpremote reset
```

Syntax check (no `__pycache__`):

```bash
python3 -c "import py_compile; py_compile.compile('main.py', cfile='/tmp/main.pyc', doraise=True)"
```

Do not claim device behavior is verified unless it was tested on the physical Presto.

## Testing

The test harness lives in `presto/tests/` and uses the `pimoroni-emulator`'s
mock MicroPython modules for headless smoke testing.

- Run tests: `mise run test`
- Tests import `main.py` without starting the event loop (guarded by
  `PRESTO_TEST_MODE=1`).
- Smoke tests cover every screen state.  When adding a new screen, add a
  corresponding test in `presto/tests/test_screens.py`.
- All tests use mock data from `make_mock_record()`.  No network calls are
  made during test execution — `fetch_thumbnail` is monkey-patched to raise
  on any accidental network access.
- Screenshots are saved to `presto/tests/fixtures/` for manual visual
  inspection.

## Hardware And Runtime Constraints

- Stock Presto firmware: MicroPython, PicoGraphics, touch driver, `urequests`, `ntptime`, usually `jpegdec`.
- Treat as single-threaded. Do not assume `_thread` or user-accessible multicore.
- Keep memory pressure low: no large in-memory buffers, no aggressive response caching, no `gc.collect()` in hot render paths.
- Network calls (`urequests`) are blocking. Never make HTTP requests during drag scrolling or inside repeated redraw loops.

## State Management

- Every view state (`STATE_STARTUP`, `STATE_MONTH`, `STATE_DAY`, `STATE_RECORD`) must be handled in `redraw_current_view()` for correct display sleep/wake.
- When transitioning into a view, reset its scroll offset to 0 so it always starts at the top.
- When adding a new state, update `main()` globals, `redraw_current_view()`, the main loop dispatch, and any related state cleanup on navigation.

## Scroll Performance

_These rules apply to any scrollable view (day list, detail page, or future additions)._

- The scroll hot path must not: measure text, join strings, sanitize text, compute layout heights, or fetch images over the network.
- Pre-compute and cache all display strings and dimensions after data arrives and before the first draw.
- Throttle drag redraws by both time (`DRAG_REDRAW_MS`) and pixel delta (`DRAG_REDRAW_PX`). Preserve pending delta on touch release and redraw once.
- Each scrollable view gets its own offset variable and its own content-height cache. Never reuse one view's scroll state for another.
- If the view has a fixed header, use `display.set_clip()` / `display.remove_clip()` to prevent scrollable content from drawing over it.

## Image Handling

- Row thumbnails use `covers.small` from the API. Detail covers use `covers.medium`.
- The API provides display-ready JPEG sizes: `covers.small` is 80px and `covers.medium` is 460px. Do not resize covers on the device.
- Cache downloaded image bytes on the record dict. Use separate cache keys for different sizes (e.g., `_thumb_data` for rows, `_detail_thumb_data` for detail view). Never fetch images during drag — show placeholders instead and repaint real covers on release.
- JPEG is the practical default. PNG has worse memory characteristics; raw/RGB565 needs a confirmed stable blit API on the target firmware.

## Text Rendering

- All user-visible text shown with bitmap fonts must pass through `display_text()` to replace unsupported punctuation (smart quotes, dashes, ellipsis). Do not strip diacritics — the font can render them.
- `release_date` is displayed as year only (first 4 characters).

## Layout

- Use named constants for all pixel geometry. No scattered literals.
- Keep header geometry consistent across views: same height, button dimensions, and side margins.

## Display Sleep

- Sleep by setting backlight to `0.0`. WiFi stays enabled.
- The first touch after sleep must wake the backlight and be consumed — it must not also activate a button or trigger a scroll.
- On wake, `set_today()` refreshes the global date from the system clock, WiFi is reconnected if it dropped, and the current view is always redrawn so the today-highlight stays current across midnight.

## API Contract

```
GET https://music-library.claudio-ortolina.org/api/v1/collection/on_this_day?date=YYYY-MM-DD
Authorization: Bearer <API_TOKEN>
```

Fields used by the app: `title`, `artists`, `format`, `release_date`, `genres`, `record_type`, `purchased_at`, `covers.small`, `covers.medium`, `selected_release_id`.

POST /api/v1/collection/:record_id/scrobble
Authorization: Bearer <API_TOKEN>

When adding or changing API assumptions, update `README.md`.
