FeedTheMonkey/BACKLOG.md

FeedTheMonkey v3 — Backlog

A rewrite of FeedTheMonkey from Qt5/C++/QML to Rust + GTK4 + libadwaita. The app is a FreshRSS client using the Google Reader compatible API.

Design principles

• Idiomatic libadwaita: follows the GNOME HIG, not a port of the Qt UI
• Dark mode follows the system (AdwStyleManager), no in-app toggle
• Credentials stored in the system keyring (libsecret), not a config file
• App settings stored in GSettings

Tech stack

• Language: Rust (stable)
• UI: GTK4 + libadwaita
• Web content: webkit6 crate (webkitgtk-6.0)
• UI templates: Blueprint (.blp) compiled at build time via blueprint-compiler
• HTTP: reqwest (async, TLS)
• JSON: serde + serde_json
• Async: tokio
• Credentials: libsecret crate
• Settings: GSettings (net.jeena.FeedTheMonkey schema)
• API: FreshRSS Google Reader compatible API

API reference

Base URL: https://rss.jeena.net/api/greader.php

Purpose	Method	Path	Notes
Login	POST	/accounts/ClientLogin	Body: Email=&Passwd= → Auth=<token>
Write token	GET	/reader/api/0/token	Header: Authorization: GoogleLogin auth=
Fetch unread	GET	/reader/api/0/stream/contents/reading-list	?xt=user/-/state/com.google/read&n=200&output=json
Mark read	POST	/reader/api/0/edit-tag	Body: i=<id>&a=user/-/state/com.google/read&T=<token>
Mark unread	POST	/reader/api/0/edit-tag	Body: i=<id>&r=user/-/state/com.google/read&T=<token>

Article JSON → content.html field mapping

Google Reader field	JS template field
title	title
origin.title	feed_title
canonical[0].href	link
published (unix ts)	updated
summary.content	content
author	author
unread	categories does NOT contain user/-/state/com.google/read

UI structure

AdwApplicationWindow
└── AdwToastOverlay
    └── AdwNavigationSplitView
        ├── sidebar: AdwNavigationPage (title="FeedTheMonkey")
        │   └── AdwToolbarView
        │       ├── top: AdwHeaderBar
        │       │   ├── start: GtkButton (view-refresh-symbolic)
        │       │   │         → AdwSpinner while loading (via GtkStack)
        │       │   └── end:   GtkMenuButton (open-menu-symbolic, primary=True)
        │       │              └── GMenu: Log Out, Keyboard Shortcuts, About
        │       └── content: GtkScrolledWindow → GtkListView (ArticleRow)
        │                    or AdwStatusPage (empty / loading / error)
        └── content: AdwNavigationPage (title = article title, dynamic)
            └── AdwToolbarView (top-bar-style=raised)
                ├── top: AdwHeaderBar (auto back button on narrow)
                │   └── end: GtkMenuButton (view-more-symbolic)
                │            └── GMenu: Mark Unread, Open in Browser
                └── content: WebKitWebView (loads html/content.html)
                             or AdwStatusPage ("Select an article")

GSettings schema

Schema ID: net.jeena.FeedTheMonkey

Key	Type	Default	Notes
window-width	int	900
window-height	int	600
window-maximized	bool	false
sidebar-width	int	280
zoom-level	double	1.0	WebKitWebView zoom level

Credentials (libsecret, not GSettings):

• server-url
• username
• password

---

Epic 1 — Project scaffold

Set up a working Rust + GTK4 + libadwaita project that opens a blank AdwApplicationWindow. No logic, just the skeleton.

Stories

1.1 Create the v3 git branch from master.

1.2 Write Cargo.toml with all dependencies:

• gtk4, libadwaita, webkit6, gio, glib
• reqwest (with rustls-tls feature, no native-tls)
• serde, serde_json
• tokio (full features)
• secret (libsecret)
• blueprint-compiler is a build-time tool, not a crate

1.3 Write build.rs that:

1. Runs blueprint-compiler batch-compile on all .blp files in data/ui/ to produce .ui files alongside them
2. Runs glib-compile-resources on data/resources.gresource.xml to produce a compiled .gresource file, then registers it

1.4 Write data/resources.gresource.xml bundling:

• Compiled .ui files from data/ui/
• html/content.html and html/content.css

1.5 Write the GSettings schema data/net.jeena.FeedTheMonkey.gschema.xml with the keys listed above.

1.6 Write data/ui/window.blp — a minimal AdwApplicationWindow containing AdwNavigationSplitView with placeholder sidebar and content pages.

1.7 Write src/main.rs and src/app.rs — AdwApplication with APP_ID net.jeena.FeedTheMonkey, activates the main window.

1.8 Write src/window.rs — AdwApplicationWindow GObject subclass that loads the window Blueprint template and restores window size from GSettings.

1.9 Verify the app compiles and opens a blank window.

---

Epic 2 — Authentication

Login dialog, credential storage, session management, logout.

Stories

2.1 Write data/ui/login_dialog.blp — an AdwDialog with:

• AdwToolbarView + AdwHeaderBar (title "Log In")
• AdwClamp → AdwPreferencesGroup containing:
  • AdwEntryRow — Server URL (placeholder: https://example.com)
  • AdwEntryRow — Username
  • AdwPasswordEntryRow — Password
  • AdwButtonRow — "Log In" (style: .suggested-action)

2.2 Write src/login_dialog.rs — LoginDialog GObject subclass using the Blueprint template. Emits a logged-in signal on success.

2.3 Write src/settings.rs — libsecret helpers:

• store_credentials(server_url, username, password)
• load_credentials() -> Option<(server_url, username, password)>
• clear_credentials()

2.4 Write src/api.rs — Api struct with:

• login(server_url, username, password) -> Result<AuthToken> Calls POST /accounts/ClientLogin, parses Auth= line from response
• fetch_write_token(auth_token) -> Result<WriteToken> Calls GET /reader/api/0/token

2.5 Connect login dialog to Api::login(). On success:

• Store credentials via libsecret
• Store AuthToken and WriteToken in application state
• Close the dialog, trigger article fetch (Epic 3)

2.6 On app start: call load_credentials(). If found, call Api::login() automatically and skip showing the login dialog.

2.7 Implement logout: clear libsecret credentials, discard tokens, show the login dialog again.

2.8 Show login errors via AdwAlertDialog (title "Login Failed", body = server error message, single "OK" button).

---

Epic 3 — Article fetching

Fetch unread articles from the server and populate the list model.

Stories

3.1 Write src/model.rs — Article struct (plain Rust, not GObject):

id: String
title: String
feed_title: String
author: String
link: String
published: i64        ← unix timestamp
content: String
excerpt: String       ← plain text, first ~150 chars of content stripped of HTML
unread: bool

Also a GObject wrapper ArticleObject (implementing glib::Object) so it can be stored in a gio::ListStore.

3.2 Add Api::fetch_unread(auth_token) -> Result<Vec<Article>> that:

• Calls GET /reader/api/0/stream/contents/reading-list?xt=...&n=200&output=json
• Deserializes the JSON response
• Maps Google Reader fields to Article struct
• Derives unread from categories not containing user/-/state/com.google/read

3.3 In src/window.rs: after successful login, call fetch_unread() in a background tokio task and populate a gio::ListStore<ArticleObject>.

3.4 Show AdwStatusPage with AdwSpinnerPaintable and title "Loading…" in the sidebar while fetching is in progress.

3.5 Show AdwStatusPage with icon rss-symbolic and title "No unread articles" when the list is empty after a successful fetch.

3.6 Show AdwStatusPage with icon network-error-symbolic and title "Could not load articles" (description = error message) on network/API error. Include a "Try Again" button that re-triggers the fetch.

3.7 Implement reload: the refresh button in the sidebar header bar re-runs fetch_unread(), replaces the list store contents, and scrolls the list back to the top.

---

Epic 4 — Sidebar

Article list view with custom rows, navigation, and split view behavior.

Stories

4.1 Write data/ui/article_row.blp — composite template for ArticleRow:

GtkBox (orientation=vertical, margin=12, spacing=4)
├── GtkBox (orientation=horizontal, spacing=4)
│   ├── GtkLabel (id=feed_title, hexpand=True, xalign=0, .dim-label, small font)
│   └── GtkLabel (id=date, xalign=1, .dim-label, small font)
├── GtkLabel (id=title, xalign=0, wrap=True, lines=2)
└── GtkLabel (id=excerpt, xalign=0, .dim-label, small font, ellipsize=end, lines=1)

4.2 Write src/article_row.rs — ArticleRow GObject subclass.

• Bind ArticleObject properties to labels
• Apply .dim-label style to the title label when article is read
• Format published timestamp as relative time ("2 hours ago", "Yesterday", etc.)

4.3 Set up GtkListView in the sidebar with a GtkSignalListItemFactory that creates and binds ArticleRow widgets.

4.4 Connect list selection (GtkSingleSelection) to show the selected article in the content pane and call adw_navigation_split_view_set_show_content(true) on narrow screens.

4.5 Implement next_article() and previous_article() functions that move the selection in the list view (used by keyboard shortcuts).

4.6 Persist and restore sidebar-width from GSettings using AdwNavigationSplitView::sidebar-width-fraction or equivalent.

---

Epic 5 — Content pane

WebKitWebView loading content.html, link handling, empty state.

Stories

5.1 Update html/content.html:

• Change <title> from "TTRSS" to "FeedTheMonkey"
• Remove setFont() and setNightmode() JavaScript functions (no longer needed)
• Remove "loading" and "empty" string handling from setArticle() (these states are now handled by AdwStatusPage in Rust)
• Remove the "logout" string handling
• Keep setArticle(article) for JSON object input
• Keep checkKey() and the keyboard event listener

5.2 Update html/content.css:

• Replace the .nightmode body class block with @media (prefers-color-scheme: dark) { ... }
• Keep all existing styles, just change the selector

5.3 Write src/content_view.rs — wrapper around webkit::WebView:

• Loads content.html from GResource on init
• Exposes set_article(article: &Article) which calls window.setArticle() via WebView::evaluate_javascript()
• Handles decide-policy signal: intercept feedthemonkey:previous, feedthemonkey:next, feedthemonkey:open URIs and emit corresponding GObject signals; intercept all other link clicks and open with gtk::show_uri()
• Exposes zoom_level property (get/set), used by Epic 8

5.4 Show AdwStatusPage with icon document-open-symbolic and title "No Article Selected" when nothing is selected in the sidebar.

5.5 Ensure WebKit loads the local content.html from GResource using a custom URI scheme or load_html() with a base URI so that content.css is resolved correctly.

---

Epic 6 — Read state

Auto-mark-read, manual mark-unread, API sync.

Stories

6.1 Add Api::mark_read(auth_token, write_token, item_id) -> Result<()> that POSTs to /reader/api/0/edit-tag with i=<id>&a=user/-/state/com.google/read&T=<write_token>.

6.2 Add Api::mark_unread(auth_token, write_token, item_id) -> Result<()> that POSTs to /reader/api/0/edit-tag with i=<id>&r=user/-/state/com.google/read&T=<write_token>.

6.3 When the selected article changes (user navigates to next/previous), mark the previously selected article as read via Api::mark_read(). Update ArticleObject::unread to false so the row styling updates immediately (optimistic update — no waiting for the API response).

6.4 Implement "Mark Unread" action (key u, content pane menu):

• Set ArticleObject::unread to true (optimistic update)
• Call Api::mark_unread() in the background
• Show an AdwToast "Marked as unread" in the AdwToastOverlay
• Set a guard flag so navigating away does not re-mark the article as read

6.5 Handle API errors from mark_read/mark_unread silently (log to stderr, do not show a dialog — these are background operations).

---

Epic 7 — Keyboard shortcuts

Full keyboard navigation matching the feature set of v2.

Stories

7.1 Register GtkShortcutController on the main window for all shortcuts:

Key(s)	Action
j, Right	Next article
k, Left	Previous article
Enter, n	Open current article in browser
r	Reload articles
u	Mark current article unread
Space, Page_Down	Scroll content down one page
Page_Up	Scroll content up one page
Home	Scroll content to top
End	Scroll content to bottom
Ctrl+plus	Zoom in
Ctrl+minus	Zoom out
Ctrl+0	Reset zoom
F11	Toggle fullscreen
Ctrl+W	Close window
Ctrl+Q	Quit application

7.2 Write data/ui/shortcuts.blp — AdwShortcutsDialog documenting all shortcuts, grouped by category (Navigation, Article, View, Application).

7.3 Connect the "Keyboard Shortcuts" menu item to show the shortcuts dialog. Also register F1 as an alias.

---

Epic 8 — Zoom

WebView zoom with keyboard shortcuts and persistence.

Stories

8.1 Implement zoom_in(), zoom_out(), zoom_reset() in content_view.rs:

• zoom_in: multiply WebView::zoom_level by 1.1
• zoom_out: divide by 1.1
• zoom_reset: set to 1.0

8.2 On zoom change, save the new zoom level to GSettings (zoom-level key).

8.3 On app start, read zoom-level from GSettings and apply to the WebView.

---

Epic 9 — Window state persistence

Save and restore window size and sidebar width.

Stories

9.1 On window close, save window-width, window-height, window-maximized to GSettings.

9.2 On window open, restore width, height, and maximized state from GSettings.

9.3 Save sidebar-width to GSettings when the sidebar is resized. Restore on startup.

---

Epic 10 — Polish

Final details for a shippable app.

Stories

10.1 Write data/net.jeena.FeedTheMonkey.desktop — .desktop file with Name=FeedTheMonkey, Exec=feedthemonkey, Icon=feedthemonkey, Categories=Network;Feed;.

10.2 Include the existing misc/feedthemonkey.xpm icon in the GResource bundle and reference it in the .desktop file.

10.3 Implement AdwAboutDialog with app name, version, license (GPL-3.0), website, and developer name. Connect to "About" menu item.

10.4 Handle the write token expiry: if an edit-tag call returns 401, fetch a new write token and retry once.

10.5 Add AdwAlertDialog for logout confirmation ("Are you sure you want to log out?" with "Log Out" destructive button and "Cancel").

10.6 Graceful shutdown: cancel in-flight API requests when the window closes.