# AGENTS.md ## Project Overview Comicviewer is a desktop comic archive viewer for CachyOS and Arch Linux. It browses local, SMB, FTP, and SFTP locations and opens ZIP archives, standalone images, and videos. ## Technology - Rust - GTK4 with GIO/GVfs for desktop and remote filesystem integration - SQLite for cached directory metadata and reading history - AppImage as the primary distribution format - Korean-first UI with all user-facing strings kept translatable ## Core Requirements - Save local and remote location profiles, including credentials. - Store credentials as plain text in the application configuration as requested, but restrict the configuration file permissions to `0600`. - Cache remote directory metadata and refresh it asynchronously when browsing. - Cancel a superseded remote directory request so only the latest request can consume resources, update progress, or replace browser entries. - Download remote ZIP archives before opening them. - Limit the persistent ZIP cache with a user-configurable LRU quota. The default is 10 GB. A quota of 0 disables persistent ZIP caching and uses temporary files. - Evict the oldest unpinned ZIP cache files before a download needs space, at startup, and after an open archive releases its cache pin. Allow users to clear cached ZIPs without deleting open archives or reading history. - Keep temporary remote media in the application cache directory, remove it when its viewer closes, and clean stale temporary downloads on the next startup. - Support JPEG, PNG, WebP, GIF, BMP, and AVIF images both standalone and in ZIP archives. Play animated GIF and WebP frames with their delays and loop counts. - Support common standalone video formats through GStreamer. In video playback, Left/Right seek by five seconds and Up/Down adjust volume by five percent. - Sort archive images and browser entries using natural filename ordering. - Support ascending and descending sorting by name, modification time, and creation time. Treat unavailable creation times as unknown rather than inventing values. - Filter the currently displayed browser directory by filename and restore all entries when the search text is cleared. - Provide 100%, fit-width, fit-height, two-page, and continuous vertical viewing. - Support both right-to-left and left-to-right two-page layouts, plus controls that advance by one page to adjust page pairing. - Reuse viewer windows when moving between ZIP, image, and video files. Preserve fullscreen state and keep the registered GTK titlebar widget stable while the displayed header changes. - Provide a toggleable file list on the right side of each viewer. Double-click or Enter opens the selected viewable file; its context menu provides favorite and download actions. - Filter each viewer's current file list with a temporary search field and restore the complete list when the search text is cleared. - Accept one local file or folder dropped onto the main window or a viewer. Browse dropped folders in the main window; for dropped files, browse the parent folder and open the exact naturally sorted item in a new viewer window. - Save favorites for local and remote folders and files, and preserve the saved location profile needed to reconnect to remote favorites. - Save progress per ZIP and save the most recently read ZIP for resume support. ## Data Locations Follow the XDG Base Directory specification: - Configuration: `${XDG_CONFIG_HOME:-~/.config}/comicviewer/` - Persistent data: `${XDG_DATA_HOME:-~/.local/share}/comicviewer/` - Cache: `${XDG_CACHE_HOME:-~/.cache}/comicviewer/` Do not write application state into the source tree. ## Engineering Guidelines - Prefer the smallest correct implementation and avoid speculative abstractions. - Keep network and archive work off the GTK main thread. - Show cached directory data immediately, then update it in the background. - Abort superseded GIO futures and guard asynchronous progress and completion callbacks against stale generations or closed/reused windows. - Handle file drops as `COPY` actions through `GdkFileList`. Inspect local paths asynchronously, reject ambiguous/multiple drops, and never reuse the source viewer window for a dropped file. - Use atomic writes for configuration, database migrations, and completed remote downloads. Incomplete downloads must use a distinct temporary suffix. - Reserve persistent cache capacity before writing a known-size remote ZIP. Cache cleanup must skip active temporary downloads and pinned/open archives. - Do not extract an entire archive to disk. Decode only requested images and prefetch a small window around the current page. - Validate archive entry sizes, image dimensions, animation frame counts, and cumulative decoded animation size before retaining decoded data. - Cancel animation timers when pictures are hidden, viewers are replaced, or windows close. GTK/GDK objects must only be created on the GTK main thread. - Avoid strong `Rc` cycles between GTK signal handlers and controllers. Viewer teardown must release temporary files, ZIP cache pins, textures, and timers. - Never trust archive paths or use them as extraction destinations. - Preserve errors from GIO, ZIP parsing, and image decoding and present concise, actionable messages in the UI. - Keep protocol-independent browsing logic separate from GTK widgets. - Do not introduce credential encryption or keyring integration unless the requirement changes. ## Quality Checks Before considering a change complete, run the checks available in the project, including formatting, linting, and tests. Once the Rust project exists, the minimum expected commands are: ```sh cargo fmt --check cargo clippy --all-targets --all-features -- -D warnings cargo test --all-features ``` Add focused tests for natural sorting, oldest-first cache eviction, pin and temporary-file protection, metadata refresh, archive filtering, animated image decoding, video seek/volume calculations, viewer sibling navigation, reading progress, dropped-file sorting/index selection, and remote file change detection. For UI or packaging changes, also run a GTK startup smoke test with isolated XDG directories; release builds must verify the AppImage and downloaded release bundle checksums. ## Git Practices - Keep commits focused and do not commit generated build output or cached data. - Do not commit real server addresses, usernames, passwords, or local test configuration. - Update documentation when runtime dependencies or AppImage requirements change.