Comicviewer/AGENTS.md

# 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. Persist the last selected
  two-page direction and restore it in newly opened archive viewers.
- 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.
- Let users update from the About window by downloading the fixed Cafe24 latest
  bundle and checksum, verifying SHA-256, and reusing the atomic installer.

## 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.