# 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 image files stored in
ZIP archives.

## Technology

- Rust
- GTK4 with GIO/GVfs for desktop and remote filesystem integration
- SQLite for cached directory metadata, search indexes, 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.
- 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.
- Support JPEG, PNG, WebP, static GIF, BMP, and AVIF images in ZIP archives.
- 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.
- Search folder and ZIP names recursively below the current location using the
  cached index.
- 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.
- 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.
- Use atomic writes for configuration, database migrations, and completed remote
  downloads. Incomplete downloads must use a distinct temporary suffix.
- 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 and image dimensions before allocation.
- 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, cache eviction, metadata refresh,
archive filtering, reading progress, and remote file change detection.

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