feat(web): add infrastructure for displaying out-of-sync alert

[dgdavid]

Introduce a reusable component that listens for change events on a given scope and displays a toast alert when the change was originated from a different client.

This helps notify users when the interface may be out of sync due to external changes, without forcing a reload and disrupting their workflow abruptly.

Its usage is straightforward, consisting on mounting one instance per watched scope in the desired pages. In future iterations, the component may support accepting multiple scopes if a real need for that arises.

---

Post merge notes

After merging this PR, a few concerns were raised that are worth documenting and discussing here.

First of all, as stated in the component’s documentation, the purpose of this alert is to inform users about changes that happened externally that might affect settings of the specific section they are viewing, meaning the interface may be out of sync. The idea is to gently encourage a page reload to fetch the latest data, while intentionally leaving that decision to the user. This is because, at this stage of development, Agama actually does not support multi-user environments, and we assume most users encountering this are advanced enough to understand what’s happening.

It's true the interface can also become out of sync due to the execution of scripts, but that’s still a relatively advanced use case, where an auto-installation was started and the user later continued in the web interface.

In any case, it's worth keeping the following in mind:

• Agama’s UI is designed around a user-driven workflow, which means it avoids taking automatic actions that might interrupt what the user is doing.

• Agama doesn’t force data refreshes, since it can't reliably know the user’s context. As a simple (and maybe silly) example, think of a user who might want to copy some values from the screen before reloading. Instead of interrupting, Agama informs users of potential risks and lets them decide.

• The interface should handle missing resources gracefully. If a user is editing something that no longer exists, both the backend and UI should respond accordingly. For instance, a “Resource not found or no longer available” page should appear. This is something that must work regardless of how the user got there, whether by typing a URL, following a link, or through an out-of-sync state.

• In rare cases, like a user editing the storage configuration and immediately clicking Install while ignoring the out-of-sync alert, it's true they might be starting an installation using a different setup than what they saw. But this highlights something else: our confirmation dialog still needs improvement. This has been discussed before, and there are already ideas about evolving the current confirmation step into a more meaningful summary page. For instance, turning the “Overview” into a “System” page holding things like hostname and localization, and upgrading the “Confirmation Dialog” into a dedicated page summarizing what the installed system will look like, which would be much more helpful than what Agama has today.

So, summarizing the above, the current alert is intentionally minimal in design, strongly informative in content, and user-driven in behavior. It keeps the interface simple, avoiding automatic or blocking behaviors that might do more harm than good.

Many of the edge cases raised are actually highlighting areas of the UX that still need to evolve. Thus, rather than jumping straight into making the out-of-sync alert blocking or automatic, it would be more effective to address these broader UX opportunities first.

That said, we're absolutely open to rethinking this approach if it proves confusing or risky in real-world use. Feedback is always welcome, as it often helps refine our thinking and guide future improvements, even when it doesn't lead to immediate changes.

---

NOTE: look&feel has changed as consequence of changes from code review, but screenshot and screencast still valid to get the idea

Screencast.From.2025-07-31.10-42-38.online-video-cutter.com.1.mp4

[coveralls]

coverage: 53.762% (+31.7%) from 22.019%
when pulling 9e72bb5 on out-of-sync-toast
into cd32708 on ui-sync.

[ancorgs]

LGTM

[dgdavid]

Post merge notes

After merging this PR, a few concerns were raised that are worth documenting and discussing here.

First of all, as stated in the component’s documentation, the purpose of this alert is to inform users about changes that happened externally that might affect settings of the specific section they are viewing, meaning the interface may be out of sync. The idea is to gently encourage a page reload to fetch the latest data, while intentionally leaving that decision to the user. This is because, at this stage of development, Agama actually does not support multi-user environments, and we assume most users encountering this are advanced enough to understand what’s happening.

It's true the interface can also become out of sync due to the execution of scripts, but that’s still a relatively advanced use case, where an auto-installation was started and the user later continued in the web interface.

In any case, it's worth keeping the following in mind:

• Agama’s UI is designed around a user-driven workflow, which means it avoids taking automatic actions that might interrupt what the user is doing.
• Agama doesn’t force data refreshes, since it can't reliably know the user’s context. As a simple (and maybe silly) example, think of a user who might want to copy some values from the screen before reloading. Instead of interrupting, Agama informs users of potential risks and lets them decide.
• The interface should handle missing resources gracefully. If a user is editing something that no longer exists, both the backend and UI should respond accordingly. For instance, a “Resource not found or no longer available” page should appear. This is something that must work regardless of how the user got there, whether by typing a URL, following a link, or through an out-of-sync state.
• In rare cases, like a user editing the storage configuration and immediately clicking Install while ignoring the out-of-sync alert, it's true they might be starting an installation using a different setup than what they saw. But this highlights something else: our confirmation dialog still needs improvement. This has been discussed before, and there are already ideas about evolving the current confirmation step into a more meaningful summary page. For instance, turning the “Overview” into a “System” page holding things like hostname and localization, and upgrading the “Confirmation Dialog” into a dedicated page summarizing what the installed system will look like, which would be much more helpful than what Agama has today.

So, summarizing the above, the current alert is intentionally minimal in design, strongly informative in content, and user-driven in behavior. It keeps the interface simple, avoiding automatic or blocking behaviors that might do more harm than good.

Many of the edge cases raised are actually highlighting areas of the UX that still need to evolve. Thus, rather than jumping straight into making the out-of-sync alert blocking or automatic, it would be more effective to address these broader UX opportunities first.

That said, we're absolutely open to rethinking this approach if it proves confusing or risky in real-world use. Feedback is always welcome, as it often helps refine our thinking and guide future improvements, even when it doesn't lead to immediate changes.

While all of the above still valid at the time of writing, unfortunately, we've found additional issues to the inherent complexity of keeping the UI reliably in sync that are not easy to resolve at this stage. Thus, we believe the safest short-term solution is to adopt a blocking approach that prevents users from proceeding until the interface is reloaded. See #2622

This decision doesn't mean we've abandoned our user-driven philosophy. Rather, it is intended as a temporary safeguard until we have time to address the underlying issues and/or to re-evaluate how reactive the Agama web interface should be. We may relax this constraint, explore less intrusive alternatives, or consider shifting toward a less (or none) automatic syncs approach.

It's also worth noting that, while Agama currently does not support multi-user, it does support multi-client usage. This does not necessarily mean all clients must be kept in sync, although it would be ideal if we eventually find a way to do so without compromising the user experience or introducing unwanted side effects.