burningtuna/Comicviewer
1
0
Fork 0
Code Issues Pull requests Projects Releases 3 Packages Wiki Activity Actions
Comicviewer/AGENTS.md
burnintuna ae1f0c7c4a Release v0.2.9
2026-07-24 22:13:07 +09:00

6.6 KiB
Raw Blame History

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.
  • 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:

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.