music_library/presto/AGENTS.md

Presto App Guidance

This directory contains MicroPython apps for the Pimoroni Presto. The main app is records_on_the_day.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 records_on_the_day.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

• The project task deploys the records app:

  mise run presto
  

• Manual deployment copies records_on_the_day.py to the device as main.py:

  mpremote fs cp records_on_the_day.py :main.py
  mpremote fs cp secrets.py :secrets.py
  mpremote reset
  

• Before finishing Python edits, run a syntax-only check that does not leave __pycache__ behind:

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

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

Hardware And Runtime Constraints

• Target stock Pimoroni Presto firmware: MicroPython, PicoGraphics, touch driver, urequests, ntptime, and usually jpegdec.
• Presto hardware is RP2350B, but stock firmware should be treated as a single Python runtime. Do not assume _thread or user-accessible multicore support.
• Keep memory pressure low. Avoid large in-memory image buffers, aggressive caching of large responses, and repeated gc.collect() in hot render paths.
• Network calls are blocking. Avoid doing HTTP requests during drag scrolling or repeated redraw loops.

Records App Behavior

• Boot should land on today's records, not the month calendar.
• The Back button returns from day view to month view.
• Month and day headers should share the same header geometry: height, button dimensions, side margins, and centered title/date positioning.
• Day rows show cover art, title, artists, and a dim metadata line of format | year.
• release_date is displayed as year only.
• Text shown with bitmap fonts should pass through display_text() to replace unsupported punctuation such as smart dashes and quotes. Do not strip diacritics; the font can render them.

Image Handling

• Prefer micro_cover_url, then mini_cover_url, then thumb_url.
• Keep THUMB_SIZE aligned with the micro image size when possible.
• Cache downloaded thumbnail bytes on the record dict as _thumb_data.
• Keep the placeholder-while-dragging behavior. Decoding JPEGs during drag was too slow on device, even with micro covers.
• Repaint real covers after the finger is released.
• Do not call gc.collect() per row draw. Collect after record preparation, after API fetches, or at other non-hot-path points.
• JPEG is the practical default on stock firmware. PNG generally has worse memory characteristics, and raw/RGB565 should only be attempted after confirming a stable on-device blit API.

Scroll Performance

• The scroll hot path must not measure text, join artist lists, sanitize strings, calculate full content height, or fetch images.
• After fetching records, call the preparation path that caches:
  • _display_title
  • _display_artists
  • _display_meta
  • _thumb_url
  • _row_height
  • total _content_height
• Preload only micro_cover_url thumbnails before the first day-view draw. Do not eagerly fetch larger fallback images.
• Drag scrolling should remain pixel-based, but redraws should be throttled by both time and pixel delta (DRAG_REDRAW_MS, DRAG_REDRAW_PX).
• Preserve any pending drag delta on touch release and redraw once with real covers if the view moved.

Layout Details

• Use named constants for pixel geometry instead of scattered literals.
• For record rows, keep cover top and bottom spacing visually symmetric:
  • ROW_PAD_Y is the padding above and below the cover.
  • ROW_SEPARATOR_H is the separator line height after the bottom padding.
• If row spacing looks wrong on device, reason in terms of inclusive pixel drawing: a separator drawn inside the padding visually consumes that padding.

Display Sleep

• The display sleeps by setting the backlight to 0.0; the app and WiFi stay running.
• The first touch after sleep should wake the backlight and be consumed so it does not also activate a control.
• On wake, check WiFi and reconnect only if it dropped.

API Contract

The records endpoint is:

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

Expected record fields used by the app:

• title
• artists
• format
• release_date
• micro_cover_url
• mini_cover_url
• thumb_url

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