Add Makefile for user-scoped install, as well as DEVLOG

DEVLOG.md

@@ -0,0 +1,75 @@
+# Development Log
+
+This file records the app's architecture and the implementation choices made
+to improve startup and queue responsiveness. It describes intended behavior;
+no formal performance benchmark has been run.
+
+## Architecture
+
+- `mpvremote/config.py` is the central settings module. It defines the mpv IPC
+  socket path, supported video extensions, key bindings, app version, and media
+  directory. The media directory defaults to `~/Videos`; an override is read
+  from `~/.config/mpvremotemedia` and can be edited in Settings.
+- `mpvremote/mpv_client.py` sends JSON commands to mpv over its Unix-domain IPC
+  socket and decodes JSON responses.
+- `mpvremote/views.py` contains the curses views:
+  - `MainView` provides playback controls and status.
+  - `PlaylistView` displays and edits mpv's current playlist.
+  - `QueueView` searches the configured media library and queues files.
+  - `SettingsView` edits the media-directory setting.
+  - `AboutView` displays app information and key bindings.
+- `mpvremote/app.py` initializes curses, constructs the views, owns the media
+  cache and scan worker, and coordinates drawing and input in the application
+  loop.
+- `mpvremote/__init__.py` exports `App` and `SOCKET`. Running
+  `python3 -m mpvremote` loads the package and enters `mpvremote/__main__.py`.
+  The entry point handles `--help`, checks that the configured socket exists,
+  then uses `curses.wrapper` to set up and restore the terminal. The app enables
+  keypad mode and handles input through its `getch()` loop.
+
+## Startup and media scanning
+
+The initial recursive media scan runs on a background worker instead of
+blocking `App` initialization. The worker scans immediately and waits 120
+seconds between subsequent scans. An event marks completion of the first scan.
+If Queue is opened before that scan completes, it displays a scanning message
+and populates automatically when the scan publishes its results.
+
+The scan commits an immutable tuple of entries containing the display name,
+absolute path, and a pre-normalized `casefold()` name. Cache replacement and
+version increments happen under a lock. `get_videos_with_version()` returns
+the snapshot and version together; `get_videos()` retains the simpler
+`(name, path)` interface for other callers.
+
+## Responsiveness changes
+
+### Escape-key decoding
+
+After curses initializes, the app requests a 50 ms Escape-sequence delay using
+`curses.set_escdelay()`, when the platform supports it. This reduces the wait
+when Escape is pressed while retaining a short interval for distinguishing
+Escape from terminal key sequences such as arrows.
+
+### Queue filtering and rendering
+
+`QueueView` caches its indexed media snapshot and filtered results. Filtering
+runs only when the search query or media-cache version changes; rendering does
+not rescan or refilter the list. While Queue is active, the event loop uses a
+100 ms input timeout and calls the view's update hook, allowing completed
+background scans to appear without requiring a keypress. Other views continue
+to wait for input normally.
+
+## User-level installation
+
+The root `Makefile` provides `install`, `verify`, and `uninstall` targets.
+Installation copies the package beneath `~/.local/share/mpvremote` and creates
+an executable `~/.local/bin/mpvremote` wrapper that sets `PYTHONPATH` and runs
+`python3 -m mpvremote`. It does not edit shell startup files; it prints a PATH
+instruction when needed. The verification target runs the installed launcher
+with `--help`, which does not require mpv to be running.
+
+## Known performance limits
+
+The main view still retrieves playback status properties synchronously through
+mpv IPC. Those requests have not been batched or moved to a background poller;
+they remain a possible area for future profiling and optimization.