From f298130cb07fb9098d7a1eefba9e3273e1909b4f Mon Sep 17 00:00:00 2001
From: Stefan Ernst <24554551+stefan-ernst@users.noreply.github.com>
Date: Mon, 2 Nov 2026 21:28:31 +0100
Subject: [PATCH] refactor(frontend): route refresh-work-items through one
 reconciliation (WI-1924)

Seven surfaces listened to the global refresh-work-items broadcast
independently, so one mutation started several unrelated reads: the
homepage snapshot, the item SLA panel, every SLA badge, child items and
the collection delta. The SLA panel also bypassed slaState and issued its
own per-item read, duplicating the workspace batch the badges already use.

Add a workItemRefresh coordinator that owns the single listener, merges a
burst into one notification, and notifies each subscriber once. Migrate
the homepage lifecycle, homepage, item detail, collection views, SLA
panel and SLA badge to subscribe to it. The panel now reads through
slaState so it shares the workspace batch with badges, and both skip a
burst that names another workspace.

Cache invalidation stays a synchronous window listener in slaState so the
cache is cleared before the debounced subscribers reload.
---
 .../collections/CollectionBacklog.svelte      |  10 +-
 .../collections/CollectionBoard.svelte        |   9 +-
 .../collections/CollectionList.svelte         |  24 ++--
 .../src/lib/features/items/ItemDetail.svelte  |  29 +++--
 .../features/items/ItemDetailSidebar.svelte   |   2 +-
 .../lib/features/items/ItemSLAPanel.svelte    |  19 ++-
 frontend/src/lib/features/sla/SLABadge.svelte |   9 +-
 frontend/src/lib/pages/Homepage.svelte        |   3 +-
 frontend/src/lib/pages/useMainAppLifecycle.js |   9 +-
 frontend/src/lib/stores/workItemRefresh.js    | 121 ++++++++++++++++++
 10 files changed, 191 insertions(+), 44 deletions(-)
 create mode 100644 frontend/src/lib/stores/workItemRefresh.js

diff --git a/frontend/src/lib/features/collections/CollectionBacklog.svelte b/frontend/src/lib/features/collections/CollectionBacklog.svelte
index 8481fd428..fe5e18ba2 100644
--- a/frontend/src/lib/features/collections/CollectionBacklog.svelte
+++ b/frontend/src/lib/features/collections/CollectionBacklog.svelte
@@ -1,6 +1,5 @@
 <script>
   import { onMount } from 'svelte';
-  import { useEventListener } from 'runed';
   import { items } from '../../api/items.js';
   import { iterations } from '../../api/milestones.js';
   import { t } from '../../stores/i18n.svelte.js';
@@ -24,6 +23,7 @@
   import { sortBacklogIterations } from './backlogIterationOrder.js';
   import ItemPicker from '../../pickers/ItemPicker.svelte';
   import { backlogStore } from '../../stores/backlogStore.svelte.js';
+  import { onWorkItemRefresh } from '../../stores/workItemRefresh.js';
   import { workspaceDataStore } from '../../stores/workspaceDataStore.svelte.js';
   import { collectionPreferences } from '../../stores/collectionPreferences.svelte.js';
   import { itemModalStore } from '../../stores/itemModalStore.svelte.js';
@@ -228,10 +228,10 @@
   const styles = useGradientStyles();
 
   // Listen for newly created items
-  async function handleRefreshWorkItems(event) {
-    if (!event.detail?.itemId) return;
+  async function handleRefreshWorkItems(detail) {
+    if (!detail?.itemId) return;
     try {
-      const newItem = event.detail.item ?? await items.get(event.detail.itemId);
+      const newItem = detail.item ?? await items.get(detail.itemId);
       // Collection QL and sub-filters depend on server state, so verify rather
       // than assume membership. Unknown never permits an insert; it reconciles.
       const membership = await resolveCreatedItemMembership(newItem, {
@@ -251,7 +251,7 @@
     }
   }
 
-  useEventListener(() => window, 'refresh-work-items', handleRefreshWorkItems);
+  $effect(() => onWorkItemRefresh(handleRefreshWorkItems));
 
   onMount(async () => {
     if (workspaceId) {
diff --git a/frontend/src/lib/features/collections/CollectionBoard.svelte b/frontend/src/lib/features/collections/CollectionBoard.svelte
index 50cc4d3dd..7f0ceb076 100644
--- a/frontend/src/lib/features/collections/CollectionBoard.svelte
+++ b/frontend/src/lib/features/collections/CollectionBoard.svelte
@@ -2,6 +2,7 @@
   import { onMount, untrack } from 'svelte';
   import { useEventListener } from 'runed';
   import { t } from '../../stores/i18n.svelte.js';
+  import { onWorkItemRefresh } from '../../stores/workItemRefresh.js';
   import { items as itemsApi } from '../../api/items.js';
   import { getAssignableUsers } from '../../api/users.js';
   import { labels as labelsApi } from '../../api/misc.js';
@@ -263,10 +264,10 @@
   }
 
   // Listen for newly created items
-  async function handleRefreshWorkItems(event) {
-    if (!event.detail?.itemId) return;
+  async function handleRefreshWorkItems(detail) {
+    if (!detail?.itemId) return;
     try {
-      const newItem = event.detail.item ?? (await itemsApi.get(event.detail.itemId));
+      const newItem = detail.item ?? (await itemsApi.get(detail.itemId));
       const membership = await resolveCreatedItemMembership(newItem, createdItemScope());
       if (membership === 'member') {
         // A create event can arrive more than once (modal event plus a delta or
@@ -281,7 +282,7 @@
     }
   }
 
-  useEventListener(() => window, 'refresh-work-items', handleRefreshWorkItems);
+  $effect(() => onWorkItemRefresh(handleRefreshWorkItems));
 
   // Quick-add functions
 
diff --git a/frontend/src/lib/features/collections/CollectionList.svelte b/frontend/src/lib/features/collections/CollectionList.svelte
index ac3453645..5a97ec028 100644
--- a/frontend/src/lib/features/collections/CollectionList.svelte
+++ b/frontend/src/lib/features/collections/CollectionList.svelte
@@ -1,7 +1,7 @@
 <script>
-  import { useEventListener } from 'runed';
   import { t } from '../../stores/i18n.svelte.js';
   import { errorToast } from '../../stores/toasts.svelte.js';
+  import { onWorkItemRefresh } from '../../stores/workItemRefresh.js';
   import {
     applyCollectionItem,
     collectionStore,
@@ -98,16 +98,18 @@
 
   let gridMinWidth = $derived(listGridMinWidth(listColumns));
 
-  useEventListener(() => window, 'refresh-work-items', (/** @type {CustomEvent} */ event) => {
-    const item = event.detail?.item;
-    // Workspace-scoped views can apply the item immediately as a display
-    // optimization. Collection membership is verified by the store's
-    // coalesced reconciliation instead of one query per event.
-    if (item && !collectionId && Number(item.workspace_id) === Number(workspaceId)) {
-      applyCollectionItem(item);
-    }
-    scheduleCollectionReconciliation();
-  });
+  $effect(() =>
+    onWorkItemRefresh((detail) => {
+      const item = detail?.item;
+      // Workspace-scoped views can apply the item immediately as a display
+      // optimization. Collection membership is verified by the store's
+      // coalesced reconciliation instead of one query per event.
+      if (item && !collectionId && Number(item.workspace_id) === Number(workspaceId)) {
+        applyCollectionItem(item);
+      }
+      scheduleCollectionReconciliation();
+    })
+  );
 
   // Scoped SSE invalidations (WI-1624): any frame runs the existing delta fetch,
   // and a reconnect reconciles. Without this the list kept showing items that
diff --git a/frontend/src/lib/features/items/ItemDetail.svelte b/frontend/src/lib/features/items/ItemDetail.svelte
index c1ba301a2..f1b8fa5e8 100644
--- a/frontend/src/lib/features/items/ItemDetail.svelte
+++ b/frontend/src/lib/features/items/ItemDetail.svelte
@@ -36,6 +36,7 @@
   import { useItemEventStream } from '../../composables/useItemEventStream.svelte.js';
   import { notificationActions } from '../../stores/notifications.js';
   import { agentRuns } from '../../stores/agentRuns.svelte.js';
+  import { onWorkItemRefresh } from '../../stores/workItemRefresh.js';
   import {
     registerContextCommands,
     unregisterContextCommands,
@@ -300,17 +301,23 @@ import NativeSelect from '../../components/NativeSelect.svelte';
 
   useEventListener(() => document, 'keydown', handleItemDetailShortcuts);
 
-  // Reload child items when a new child is created against the item currently open.
-  useEventListener(() => window, 'refresh-work-items', (/** @type {CustomEvent<{parentId?: number}>} */ event) => {
-    const parentId = event?.detail?.parentId;
-    if (parentId == null) return;
-    const currentId = itemDetailStore.item?.id;
-    if (currentId == null) return;
-    if (Number(parentId) !== Number(currentId)) return;
-    itemDetailStore.loadChildItems().catch((err) => {
-      console.error('Failed to reload child items after child creation:', err);
-    });
-  });
+  // Reload child items when a new child is created against the item currently
+  // open. The coordinator batches a burst; check every parent it named.
+  $effect(() =>
+    onWorkItemRefresh((detail) => {
+      const currentId = itemDetailStore.item?.id;
+      if (currentId == null) return;
+      const parents = detail?.parentIds?.length
+        ? detail.parentIds
+        : detail?.parentId != null
+          ? [detail.parentId]
+          : [];
+      if (!parents.some((parentId) => Number(parentId) === Number(currentId))) return;
+      itemDetailStore.loadChildItems().catch((err) => {
+        console.error('Failed to reload child items after child creation:', err);
+      });
+    })
+  );
 
   function handleFocusStatus() {
     // Focus the status field by starting edit mode
diff --git a/frontend/src/lib/features/items/ItemDetailSidebar.svelte b/frontend/src/lib/features/items/ItemDetailSidebar.svelte
index 83953e6ab..f37b77a64 100644
--- a/frontend/src/lib/features/items/ItemDetailSidebar.svelte
+++ b/frontend/src/lib/features/items/ItemDetailSidebar.svelte
@@ -659,7 +659,7 @@
       />
     {/snippet}
     {#if item?.id}
-      <ItemSLAPanel itemId={item.id} />
+      <ItemSLAPanel itemId={item.id} workspaceId={item.workspace_id} />
     {/if}
     <!-- DETAILS Section Header -->
     <div class="flex items-center justify-between mb-2">
diff --git a/frontend/src/lib/features/items/ItemSLAPanel.svelte b/frontend/src/lib/features/items/ItemSLAPanel.svelte
index a4cbdaf21..fb8a8c849 100644
--- a/frontend/src/lib/features/items/ItemSLAPanel.svelte
+++ b/frontend/src/lib/features/items/ItemSLAPanel.svelte
@@ -1,14 +1,14 @@
 <script>
-  import { useEventListener } from 'runed';
-  import { sla } from '../../api/sla.js';
   import Lozenge from '../../components/Lozenge.svelte';
   import Tooltip from '../../components/Tooltip.svelte';
   import Gauge from '@lucide/svelte/icons/gauge';
   import Clock from '@lucide/svelte/icons/clock';
   import { t } from '../../stores/i18n.svelte.js';
   import { formatInstant } from '../../utils/dateFormatter.js';
+  import { onWorkItemRefresh, workItemRefreshTouchesWorkspace } from '../../stores/workItemRefresh.js';
+  import { getItemSLA } from '../sla/slaState.js';
 
-  let { itemId = null } = $props();
+  let { itemId = null, workspaceId = null } = $props();
 
   // Server-computed remaining/breach state has to be re-read while a timer is
   // visible; elapsed time and business-hours transitions never reach the client
@@ -25,7 +25,7 @@
     const requestedItemId = itemId;
     loading = true;
     try {
-      const result = (await sla.getItemSLA(requestedItemId)) ?? [];
+      const result = (await getItemSLA(requestedItemId, workspaceId)) ?? [];
       // A newer request or an item switch supersedes this response.
       if (token !== requestToken) return;
       states = result;
@@ -51,8 +51,15 @@
   });
 
   // Item mutations (status, assignee, comments, etc.) are broadcast globally;
-  // refresh the derived SLA state when they happen.
-  useEventListener(() => window, 'refresh-work-items', () => void load());
+  // refresh the derived SLA state when they happen. Reading through slaState
+  // means the panel and any SLA badges in the same workspace share one batch,
+  // and a burst in another workspace is skipped entirely.
+  $effect(() =>
+    onWorkItemRefresh((detail) => {
+      if (!workItemRefreshTouchesWorkspace(detail, workspaceId)) return;
+      void load();
+    })
+  );
 
   function formatDuration(ms) {
     if (ms == null) return '';
diff --git a/frontend/src/lib/features/sla/SLABadge.svelte b/frontend/src/lib/features/sla/SLABadge.svelte
index 7c41f93e7..3a0cfdd14 100644
--- a/frontend/src/lib/features/sla/SLABadge.svelte
+++ b/frontend/src/lib/features/sla/SLABadge.svelte
@@ -1,9 +1,9 @@
 <script>
-  import { useEventListener } from 'runed';
   import Lozenge from '../../components/Lozenge.svelte';
   import Tooltip from '../../components/Tooltip.svelte';
   import { t } from '../../stores/i18n.svelte.js';
   import { formatInstant } from '../../utils/dateFormatter.js';
+  import { onWorkItemRefresh, workItemRefreshTouchesWorkspace } from '../../stores/workItemRefresh.js';
   import { getItemSLA, getSLAThresholds, onSLAThresholdsInvalidated } from './slaState.js';
 
   let { itemId = null, workspaceId = null, refreshToken = 0 } = $props();
@@ -37,7 +37,12 @@
     };
   });
 
-  useEventListener(() => window, 'refresh-work-items', () => void load(itemId, workspaceId, refreshToken));
+  $effect(() =>
+    onWorkItemRefresh((detail) => {
+      if (!workItemRefreshTouchesWorkspace(detail, workspaceId)) return;
+      void load(itemId, workspaceId, refreshToken);
+    })
+  );
 
   // A threshold mutation in this tab must refresh mounted badges immediately;
   // failed mutations never emit, and other tabs pick the change up once the
diff --git a/frontend/src/lib/pages/Homepage.svelte b/frontend/src/lib/pages/Homepage.svelte
index 15b837bf7..6a96ee89b 100644
--- a/frontend/src/lib/pages/Homepage.svelte
+++ b/frontend/src/lib/pages/Homepage.svelte
@@ -18,6 +18,7 @@
   import Trash2 from '@lucide/svelte/icons/trash-2';
   import X from '@lucide/svelte/icons/x';
   import { useEventListener } from 'runed';
+  import { onWorkItemRefresh } from '../stores/workItemRefresh.js';
   import { createDashboardWidgetDrag } from '../composables/dashboardWidgetDrag.js';
   import { useDashboardCustomization } from '../composables/useDashboardCustomization.svelte.js';
   import { confirm } from '../composables/useConfirm.js';
@@ -112,7 +113,7 @@
   }
 
   useEventListener(() => window, 'refresh-workspaces', handleRefresh);
-  useEventListener(() => window, 'refresh-work-items', handleRefresh);
+  $effect(() => onWorkItemRefresh(handleRefresh));
 
   // --- Layout / mode handlers ---
 
diff --git a/frontend/src/lib/pages/useMainAppLifecycle.js b/frontend/src/lib/pages/useMainAppLifecycle.js
index 32397deea..5e0a3b8ba 100644
--- a/frontend/src/lib/pages/useMainAppLifecycle.js
+++ b/frontend/src/lib/pages/useMainAppLifecycle.js
@@ -12,6 +12,7 @@ import { authStore } from '../stores/auth.svelte.js';
 import { capabilitiesStore } from '../stores/capabilities.svelte.js';
 import { homepageStore } from '../stores/homepageStore.svelte.js';
 import { startNotificationPoller, stopNotificationPoller } from '../stores/notifications.js';
+import { onWorkItemRefresh } from '../stores/workItemRefresh.js';
 import { workspaceDataStore } from '../stores/workspaceDataStore.svelte.js';
 import { workspacesStore } from '../stores/workspaces.svelte.js';
 import { initDesktopFocusRefresh } from '../utils/desktopFocusRefresh.svelte.js';
@@ -124,20 +125,22 @@ export function useMainAppLifecycle({
       void workspacesStore.reload();
     };
     const handleRefreshWorkspaceData = () => void workspaceDataStore.refresh();
-    const handleRefreshWorkItems = () => homepageStore.invalidateSnapshot();
+    // The homepage only marks its snapshot stale here; the mounted Homepage
+    // component refreshes it. One coordinator owns the event so this is not a
+    // second independent listener.
+    const unsubscribeRefreshWorkItems = onWorkItemRefresh(() => homepageStore.invalidateSnapshot());
 
     window.addEventListener('show-create-modal', handleShowCreateModal);
     window.addEventListener(ADMIN_UI_MUTATION_EVENT, scheduleAdminUIRefresh);
     window.addEventListener('refresh-workspaces', handleRefreshWorkspaces);
     window.addEventListener('refresh-workspace-data', handleRefreshWorkspaceData);
-    window.addEventListener('refresh-work-items', handleRefreshWorkItems);
 
     return () => {
       window.removeEventListener('show-create-modal', handleShowCreateModal);
       window.removeEventListener(ADMIN_UI_MUTATION_EVENT, scheduleAdminUIRefresh);
       window.removeEventListener('refresh-workspaces', handleRefreshWorkspaces);
       window.removeEventListener('refresh-workspace-data', handleRefreshWorkspaceData);
-      window.removeEventListener('refresh-work-items', handleRefreshWorkItems);
+      unsubscribeRefreshWorkItems();
       if (adminUIRefreshTimer) clearTimeout(adminUIRefreshTimer);
     };
   });
diff --git a/frontend/src/lib/stores/workItemRefresh.js b/frontend/src/lib/stores/workItemRefresh.js
new file mode 100644
index 000000000..259563866
--- /dev/null
+++ b/frontend/src/lib/stores/workItemRefresh.js
@@ -0,0 +1,121 @@
+// One debounced reconciliation for the global `refresh-work-items` broadcast.
+//
+// The event is a "work items changed" signal. Surfaces used to add their own
+// window listener, so one mutation started several independent reads (homepage
+// snapshot, item SLA, child items, collection delta). This module owns the
+// single surface listener, merges a burst into one notification, and each
+// subscriber reconciles its own surface at most once.
+
+// Synchronous bursts (modal event plus an SSE frame plus a cross-tab frame)
+// coalesce into one flush. Zero delay keeps the reconciliation on the next
+// task without adding perceptible latency to a single mutation.
+const RECONCILE_DELAY_MS = 0;
+
+/**
+ * @typedef {Object} WorkItemRefresh
+ * @property {any} [item] Latest item in the burst.
+ * @property {number} [itemId] Latest item id in the burst.
+ * @property {number} [workspaceId] Latest workspace id in the burst.
+ * @property {number|null} [parentId] Latest parent id in the burst.
+ * @property {number[]} itemIds Every item id seen in the burst.
+ * @property {number[]} parentIds Every parent id seen in the burst.
+ */
+
+/** @type {Set<(detail: WorkItemRefresh) => void>} */
+const subscribers = new Set();
+/** @type {ReturnType<typeof setTimeout>|null} */
+let timer = null;
+/** @type {WorkItemRefresh|null} */
+let pending = null;
+
+function emptyDetail() {
+  return { itemIds: [], parentIds: [] };
+}
+
+function mergeDetail(current, event) {
+  const detail = current ?? emptyDetail();
+  const next = event?.detail ?? {};
+  if (next.item) detail.item = next.item;
+  if (next.itemId != null) detail.itemId = next.itemId;
+  if (next.workspaceId != null) detail.workspaceId = next.workspaceId;
+  if (next.parentId != null) detail.parentId = next.parentId;
+
+  const itemId = next.itemId ?? next.item?.id;
+  if (itemId != null && !detail.itemIds.includes(itemId)) detail.itemIds.push(itemId);
+  if (next.parentId != null && !detail.parentIds.includes(next.parentId)) {
+    detail.parentIds.push(next.parentId);
+  }
+  return detail;
+}
+
+function flush() {
+  timer = null;
+  const detail = pending ?? emptyDetail();
+  pending = null;
+  for (const subscriber of subscribers) {
+    try {
+      subscriber(detail);
+    } catch (error) {
+      console.error('refresh-work-items subscriber failed:', error);
+    }
+  }
+}
+
+function handleWindowEvent(event) {
+  pending = mergeDetail(pending, event);
+  if (timer != null) return;
+  timer = setTimeout(flush, RECONCILE_DELAY_MS);
+}
+
+/**
+ * Subscribe to one debounced reconciliation per `refresh-work-items` burst.
+ *
+ * @param {(detail: WorkItemRefresh) => void} subscriber
+ * @returns {() => void} unsubscribe
+ */
+export function onWorkItemRefresh(subscriber) {
+  if (typeof window === 'undefined') return () => {};
+  subscribers.add(subscriber);
+  if (subscribers.size === 1) {
+    window.addEventListener('refresh-work-items', handleWindowEvent);
+  }
+  return () => {
+    subscribers.delete(subscriber);
+    if (subscribers.size === 0) {
+      window.removeEventListener('refresh-work-items', handleWindowEvent);
+      if (timer != null) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      pending = null;
+    }
+  };
+}
+
+/**
+ * Whether a burst names the given workspace, or carries no workspace to
+ * filter on. Lets a workspace-scoped surface skip a reconciliation that
+ * cannot affect it.
+ *
+ * @param {WorkItemRefresh} detail
+ * @param {number|null|undefined} workspaceId
+ * @returns {boolean}
+ */
+export function workItemRefreshTouchesWorkspace(detail, workspaceId) {
+  const eventWorkspace = detail?.item?.workspace_id ?? detail?.workspaceId ?? null;
+  if (eventWorkspace == null || workspaceId == null) return true;
+  return Number(eventWorkspace) === Number(workspaceId);
+}
+
+/** Test-only: drop subscribers and any pending reconciliation. */
+export function resetWorkItemRefresh() {
+  subscribers.clear();
+  if (typeof window !== 'undefined') {
+    window.removeEventListener('refresh-work-items', handleWindowEvent);
+  }
+  if (timer != null) {
+    clearTimeout(timer);
+    timer = null;
+  }
+  pending = null;
+}