From 593728881761e5a275b29140b4ea8bed49221f9d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C5=ABdolfs=20O=C5=A1i=C5=86=C5=A1?= Date: Fri, 20 Nov 2026 10:55:28 +0100 Subject: [PATCH] Amend ADR 5 for updates shown in place The patch view shows new comments in place instead of pinning a snapshot, paginated lists keep their own pages, and `cached()` stays for small lookups, so the ADR now says so. --- docs/adr/0005-reactivity.md | 42 ++++++++++++++++++++++++------------- 1 file changed, 27 insertions(+), 15 deletions(-) diff --git a/docs/adr/0005-reactivity.md b/docs/adr/0005-reactivity.md index 8c4bea94a..398ef748c 100644 --- a/docs/adr/0005-reactivity.md +++ b/docs/adr/0005-reactivity.md @@ -14,10 +14,10 @@ reacts to changes in its backend's data: desktop's backend emits only node status and download progress, its repository list polls while replication is pending, and radicle-httpd has no push API. -Both apps should react to such changes without disturbing the user. Lists -and counts can refresh in place, but a revision or diff under review must -stay as it is, showing that newer data is available until the user applies -it. +Both apps should react to such changes without disturbing the user. Lists, +counts and new comments can show in place, but what the user is reading must +not move or change under them, showing that newer data is available until +the user applies it. We also considered events that carry the new data, which ties them to each transport's response shapes; a cache of our own on Svelte stores, which would @@ -29,24 +29,34 @@ explorer, which loads the third-party nodes it browses. - Core defines the keys of the data shared code reads, by domain identity and nested under the repository, so that one prefix covers all of a repository's data. Each app supplies the fetchers for them. -- A shared query cache on TanStack Query keeps the results, deduplicates reads - and applies writes. It lives in `@radicle-gui/ui` because it needs Svelte's +- A shared query cache on TanStack Query keeps the results and deduplicates + reads. It lives in `@radicle-gui/ui` because it needs Svelte's reactivity, and only the apps' views use it; shared components keep taking props, as in ADR 3. - Route loaders load through the cache and views read from it, so that a - view's first data is already cached, and paginated lists keep their pages - in it. + view's first data is already cached. Paginated lists keep their own pages, + and the cache tells them when to refresh. - Content-addressed data, keyed by an oid, never changes, so it is cached without expiry and never invalidated. - Each app forwards its backend's ref updates: the repository and the names of the refs that changed. A pure function in core maps them to the keys they - affect, which the cache invalidates and refetches while they are shown. -- A view whose content the user is acting on, such as a revision under review, - renders a pinned snapshot and shows that newer data is available when the - cache's data is a different object. Refetches keep unchanged objects - identical, so a different object means the data changed. + affect, which the cache invalidates and refetches while they are shown. A + fetch already in flight when its key is invalidated counts as stale once it + settles, since what it read may predate the change. +- The app's own writes invalidate the keys they affect, since a node doesn't + announce every write, such as with announcing off or while it is stopped. +- New data that can be added without moving what the user is looking at, + such as comments on a diff or rows in the inbox, shows as it arrives, and + the view keeps its scroll position. Content the user is reading that newer + data would replace, such as an issue's description, renders a pinned + snapshot and shows that newer data is available when the cache's data is a + different object. Refetches keep unchanged objects identical, so a different + object means the data changed. - Desktop's backend forwards its node's events, and invalidates more broadly - when an event names no refs or events may have been missed. + when an event names no refs or events may have been missed. It also watches + the node's databases for changes other processes make without an event, + such as clearing notifications, changing seeding policies or writing a COB + without announcing it. - Explorer has no event source until radicle-httpd can push ref updates. It refetches mutable data on navigation and when the window regains focus, and so does desktop while its node is stopped. @@ -56,7 +66,9 @@ explorer, which loads the third-party nodes it browses. - Reads are deduplicated, and updates no longer reset what the user is doing. - Both apps depend on TanStack Query, which replaces `cached()` and explorer's - copy of it. Events replace desktop's polling of its repository list. + copy of it for the data views show. `cached()` stays for content-addressed + data and for small lookups such as hover cards, which are dropped whenever + data changes. Events replace desktop's polling of its repository list. - Desktop's backend has to subscribe to its node's events. - Explorer views move to runes before they use the cache. - The rule in `shared/ui/AGENTS.md` that components keep their local state