beads-ui 0.2.0 → 0.3.0

package/app/main.js

@@ -1,5 +1,11 @@
+/**
+ * @import { MessageType } from './protocol.js'
+ */
 import { html, render } from 'lit-html';
+import { createListSelectors } from './data/list-selectors.js';
 import { createDataLayer } from './data/providers.js';
+import { createSubscriptionIssueStores } from './data/subscription-issue-stores.js';
+import { createSubscriptionStore } from './data/subscriptions-store.js';
 import { createHashRouter, parseHash } from './router.js';
 import { createStore } from './state.js';
 import { showToast } from './utils/toast.js';
@@ -43,10 +49,55 @@ export function bootstrap(root_element) {
   const detail_mount = document.getElementById('detail-panel');
   if (list_mount && issues_root && epics_root && board_root && detail_mount) {
     const client = createWsClient();
+    // Subscriptions: wire client events and expose subscribe/unsubscribe helpers
+    const subscriptions = createSubscriptionStore((type, payload) =>
+      client.send(type, payload)
+    );
+    // Per-subscription stores (source of truth)
+    const sub_issue_stores = createSubscriptionIssueStores();
+    // Route per-subscription push envelopes to the owning store
+    client.on('snapshot', (payload) => {
+      const p = /** @type {any} */ (payload);
+      const id = p && typeof p.id === 'string' ? p.id : '';
+      const store = id ? sub_issue_stores.getStore(id) : null;
+      if (store && p && p.type === 'snapshot') {
+        try {
+          store.applyPush(p);
+        } catch {
+          // ignore
+        }
+      }
+    });
+    client.on('upsert', (payload) => {
+      const p = /** @type {any} */ (payload);
+      const id = p && typeof p.id === 'string' ? p.id : '';
+      const store = id ? sub_issue_stores.getStore(id) : null;
+      if (store && p && p.type === 'upsert') {
+        try {
+          store.applyPush(p);
+        } catch {
+          // ignore
+        }
+      }
+    });
+    client.on('delete', (payload) => {
+      const p = /** @type {any} */ (payload);
+      const id = p && typeof p.id === 'string' ? p.id : '';
+      const store = id ? sub_issue_stores.getStore(id) : null;
+      if (store && p && p.type === 'delete') {
+        try {
+          store.applyPush(p);
+        } catch {
+          // ignore
+        }
+      }
+    });
+    // Derived list selectors: render from per-subscription snapshots
+    const listSelectors = createListSelectors(sub_issue_stores);
     // Show toasts for WebSocket connectivity changes
     /** @type {boolean} */
     let had_disconnect = false;
-    if (typeof (/** @type {any} */ (client).onConnection) === 'function') {
+    if (typeof client.onConnection === 'function') {
       /** @type {(s: 'connecting'|'open'|'closed'|'reconnecting') => void} */
       const onConn = (s) => {
         if (s === 'reconnecting' || s === 'closed') {
@@ -57,11 +108,11 @@ export function bootstrap(root_element) {
           showToast('Reconnected', 'success', 2200);
         }
       };
-      /** @type {any} */ (client).onConnection(onConn);
+      client.onConnection(onConn);
     }
     // Load persisted filters (status/search/type) from localStorage
     /** @type {{ status: 'all'|'open'|'in_progress'|'closed'|'ready', search: string, type: string }} */
-    let persistedFilters = { status: 'all', search: '', type: '' };
+    let persisted_filters = { status: 'all', search: '', type: '' };
     try {
       const raw = window.localStorage.getItem('beads-ui.filters');
       if (raw) {
@@ -82,7 +133,7 @@ export function bootstrap(root_element) {
             }
             parsed_type = first_valid;
           }
-          persistedFilters = {
+          persisted_filters = {
             status: ['all', 'open', 'in_progress', 'closed', 'ready'].includes(
               obj.status
             )
@@ -121,7 +172,7 @@ export function bootstrap(root_element) {
         if (obj && typeof obj === 'object') {
           const cf = String(obj.closed_filter || 'today');
           if (cf === 'today' || cf === '3' || cf === '7') {
-            persistedBoard.closed_filter = /** @type {any} */ (cf);
+            persistedBoard.closed_filter = cf;
           }
         }
       }
@@ -130,7 +181,7 @@ export function bootstrap(root_element) {
     }
 
     const store = createStore({
-      filters: persistedFilters,
+      filters: persisted_filters,
       view: last_view,
       board: persistedBoard
     });
@@ -142,7 +193,7 @@ export function bootstrap(root_element) {
      */
     const transport = async (type, payload) => {
       try {
-        return await client.send(/** @type {any} */ (type), payload);
+        return await client.send(/** @type {MessageType} */ (type), payload);
       } catch {
         return [];
       }
@@ -155,7 +206,7 @@ export function bootstrap(root_element) {
     // Global New Issue dialog (UI-106) mounted at root so it is always visible
     const new_issue_dialog = createNewIssueDialog(
       root_element,
-      (type, payload) => client.send(/** @type {any} */ (type), payload),
+      (type, payload) => client.send(type, payload),
       router,
       store
     );
@@ -171,16 +222,35 @@ export function bootstrap(root_element) {
       // ignore missing header
     }
 
+    // Local transport shim: for list-issues, serve from local listSelectors;
+    // otherwise forward to ws transport for mutations/show.
+    /**
+     * @param {MessageType} type
+     * @param {unknown} payload
+     */
+    const listTransport = async (type, payload) => {
+      if (type === 'list-issues') {
+        try {
+          return listSelectors.selectIssuesFor('tab:issues');
+        } catch {
+          return [];
+        }
+      }
+      return transport(type, payload);
+    };
+
     const issues_view = createListView(
       list_mount,
-      transport,
+      /** @type {any} */ (listTransport),
       (hash) => {
         const id = parseHash(hash);
         if (id) {
           router.gotoIssue(id);
         }
       },
-      store
+      store,
+      subscriptions,
+      sub_issue_stores
     );
     // Persist filter changes to localStorage
     store.subscribe((s) => {
@@ -225,12 +295,17 @@ export function bootstrap(root_element) {
     /** @type {ReturnType<typeof createDetailView> | null} */
     let detail = null;
     // Mount details into the dialog body only
-    detail = createDetailView(dialog.getMount(), transport, (hash) => {
-      const id = parseHash(hash);
-      if (id) {
-        router.gotoIssue(id);
-      }
-    });
+    detail = createDetailView(
+      dialog.getMount(),
+      transport,
+      (hash) => {
+        const id = parseHash(hash);
+        if (id) {
+          router.gotoIssue(id);
+        }
+      },
+      sub_issue_stores
+    );
 
     // If router already set a selected id (deep-link), open dialog now
     const initial_id = store.getState().selected_id;
@@ -240,9 +315,21 @@ export function bootstrap(root_element) {
       if (detail) {
         void detail.load(initial_id);
       }
+      // Ensure detail subscription is active on initial deep-link
+      const client_id = `detail:${initial_id}`;
+      const spec = { type: 'issue-detail', params: { id: initial_id } };
+      // Register store first to avoid dropping the initial snapshot
+      try {
+        sub_issue_stores.register(client_id, spec);
+      } catch {
+        // ignore
+      }
+      void subscriptions.subscribeList(client_id, spec).catch(() => {});
     }
 
     // Open/close dialog based on selected_id (always dialog; no page variant)
+    /** @type {null | (() => Promise<void>)} */
+    let unsub_detail = null;
     store.subscribe((s) => {
       const id = s.selected_id;
       if (id) {
@@ -251,6 +338,26 @@ export function bootstrap(root_element) {
         if (detail) {
           void detail.load(id);
         }
+        // Wire per-issue subscription for detail
+        const client_id = `detail:${id}`;
+        const spec = { type: 'issue-detail', params: { id } };
+        // Ensure per-subscription issue store exists before subscribing
+        try {
+          sub_issue_stores.register(client_id, spec);
+        } catch {
+          // ignore
+        }
+        // Subscribe server-side
+        void subscriptions
+          .subscribeList(client_id, spec)
+          .then((unsub) => {
+            // Unsubscribe previous if any
+            if (unsub_detail) {
+              void unsub_detail().catch(() => {});
+            }
+            unsub_detail = unsub;
+          })
+          .catch(() => {});
       } else {
         try {
           dialog.close();
@@ -261,69 +368,234 @@ export function bootstrap(root_element) {
           detail.clear();
         }
         detail_mount.hidden = true;
+        if (unsub_detail) {
+          void unsub_detail().catch(() => {});
+          unsub_detail = null;
+        }
       }
     });
 
-    // Refresh views on push updates (target minimally and avoid flicker)
-    // UI-114: Coalesce near-simultaneous events. When an ID-scoped update
-    // arrives, suppress a trailing watcher-only full refresh for a short
-    // window to avoid duplicate work and flicker.
-    /** @type {number} */
-    let suppress_full_until = 0;
-    client.on('issues-changed', (payload) => {
-      const s = store.getState();
-      const hint_ids =
-        payload && payload.hint && Array.isArray(payload.hint.ids)
-          ? /** @type {string[]} */ (payload.hint.ids)
-          : null;
+    // Removed: issues-changed handling. All views re-render from
+    // per-subscription stores which are updated by snapshot/upsert/delete.
 
-      const now = Date.now();
-      if (!hint_ids || hint_ids.length === 0) {
-        if (now <= suppress_full_until) {
-          // Drop redundant full refresh that follows a targeted update.
-          return;
-        }
-      } else {
-        // Prefer ID-scoped updates for a brief window.
-        suppress_full_until = now + 500;
+    // Toggle route shells on view/detail change and persist
+    const data = createDataLayer(transport);
+    const epics_view = createEpicsView(
+      epics_root,
+      data,
+      (id) => router.gotoIssue(id),
+      subscriptions,
+      sub_issue_stores
+    );
+    const board_view = createBoardView(
+      board_root,
+      data,
+      (id) => router.gotoIssue(id),
+      store,
+      subscriptions,
+      sub_issue_stores
+    );
+    // Preload epics when switching to view
+    /**
+     * @param {{ selected_id: string | null, view: 'issues'|'epics'|'board', filters: any }} s
+     */
+    // --- Subscriptions: tab-level management and filter-driven updates ---
+    /** @type {null | (() => Promise<void>)} */
+    let unsub_issues_tab = null;
+    /** @type {null | (() => Promise<void>)} */
+    let unsub_epics_tab = null;
+    /** @type {null | (() => Promise<void>)} */
+    let unsub_board_ready = null;
+    /** @type {null | (() => Promise<void>)} */
+    let unsub_board_in_progress = null;
+    /** @type {null | (() => Promise<void>)} */
+    let unsub_board_closed = null;
+    /** @type {null | (() => Promise<void>)} */
+    let unsub_board_blocked = null;
+
+    /**
+     * Compute subscription spec for Issues tab based on filters.
+     * @param {{ status?: string }} filters
+     * @returns {{ type: string, params?: Record<string, string|number|boolean> }}
+     */
+    function computeIssuesSpec(filters) {
+      const st = String(filters?.status || 'all');
+      if (st === 'ready') {
+        return { type: 'ready-issues' };
+      }
+      if (st === 'in_progress') {
+        return { type: 'in-progress-issues' };
       }
+      if (st === 'closed') {
+        return { type: 'closed-issues' };
+      }
+      // "all" and "open" map to all-issues; client filters apply locally
+      return { type: 'all-issues' };
+    }
 
-      const showing_detail = Boolean(s.selected_id);
+    /** @type {string|null} */
+    let last_issues_spec_key = null;
+    /**
+     * Ensure only the active tab has subscriptions; clean up previous.
+     * @param {{ view: 'issues'|'epics'|'board', filters: any }} s
+     */
+    function ensureTabSubscriptions(s) {
+      // Issues tab
+      if (s.view === 'issues') {
+        const spec = computeIssuesSpec(s.filters || {});
+        const key = JSON.stringify(spec);
+        // Register store first to capture the initial snapshot
+        try {
+          sub_issue_stores.register('tab:issues', spec);
+        } catch {
+          // ignore
+        }
+        // Only (re)subscribe if not yet subscribed or the spec changed
+        if (!unsub_issues_tab || key !== last_issues_spec_key) {
+          void subscriptions
+            .subscribeList('tab:issues', spec)
+            .then((unsub) => {
+              unsub_issues_tab = unsub;
+              last_issues_spec_key = key;
+            })
+            .catch(() => {
+              // ignore transport errors; retry on next change
+            });
+        }
+      } else if (unsub_issues_tab) {
+        void unsub_issues_tab().catch(() => {});
+        unsub_issues_tab = null;
+        last_issues_spec_key = null;
+        try {
+          sub_issue_stores.unregister('tab:issues');
+        } catch {
+          // ignore
+        }
+      }
 
-      // If a top-level view is visible (and not detail), refresh that view
-      if (!showing_detail) {
-        if (s.view === 'issues') {
-          void issues_view.load();
-        } else if (s.view === 'epics') {
-          void epics_view.load();
-        } else if (s.view === 'board') {
-          void board_view.load();
+      // Epics tab
+      if (s.view === 'epics') {
+        // Register store first to avoid race with initial snapshot
+        try {
+          sub_issue_stores.register('tab:epics', { type: 'epics' });
+        } catch {
+          // ignore
+        }
+        void subscriptions
+          .subscribeList('tab:epics', { type: 'epics' })
+          .then((unsub) => {
+            unsub_epics_tab = unsub;
+          })
+          .catch(() => {});
+      } else if (unsub_epics_tab) {
+        void unsub_epics_tab().catch(() => {});
+        unsub_epics_tab = null;
+        try {
+          sub_issue_stores.unregister('tab:epics');
+        } catch {
+          // ignore
         }
       }
 
-      // If a detail is visible, re-fetch it when relevant or when hints are absent
-      if (showing_detail && s.selected_id) {
-        if (!hint_ids || hint_ids.includes(s.selected_id)) {
-          if (detail) {
-            void detail.load(s.selected_id);
+      // Board tab subscribes to lists used by columns
+      if (s.view === 'board') {
+        if (!unsub_board_ready) {
+          try {
+            sub_issue_stores.register('tab:board:ready', {
+              type: 'ready-issues'
+            });
+          } catch {
+            // ignore
+          }
+          void subscriptions
+            .subscribeList('tab:board:ready', { type: 'ready-issues' })
+            .then((u) => (unsub_board_ready = u))
+            .catch(() => {});
+        }
+        if (!unsub_board_in_progress) {
+          try {
+            sub_issue_stores.register('tab:board:in-progress', {
+              type: 'in-progress-issues'
+            });
+          } catch {
+            // ignore
+          }
+          void subscriptions
+            .subscribeList('tab:board:in-progress', {
+              type: 'in-progress-issues'
+            })
+            .then((u) => (unsub_board_in_progress = u))
+            .catch(() => {});
+        }
+        if (!unsub_board_closed) {
+          try {
+            sub_issue_stores.register('tab:board:closed', {
+              type: 'closed-issues'
+            });
+          } catch {
+            // ignore
+          }
+          void subscriptions
+            .subscribeList('tab:board:closed', { type: 'closed-issues' })
+            .then((u) => (unsub_board_closed = u))
+            .catch(() => {});
+        }
+        if (!unsub_board_blocked) {
+          try {
+            sub_issue_stores.register('tab:board:blocked', {
+              type: 'blocked-issues'
+            });
+          } catch {
+            // ignore
+          }
+          void subscriptions
+            .subscribeList('tab:board:blocked', { type: 'blocked-issues' })
+            .then((u) => (unsub_board_blocked = u))
+            .catch(() => {});
+        }
+      } else {
+        // Unsubscribe all board lists when leaving the board view
+        if (unsub_board_ready) {
+          void unsub_board_ready().catch(() => {});
+          unsub_board_ready = null;
+          try {
+            sub_issue_stores.unregister('tab:board:ready');
+          } catch {
+            // ignore
+          }
+        }
+        if (unsub_board_in_progress) {
+          void unsub_board_in_progress().catch(() => {});
+          unsub_board_in_progress = null;
+          try {
+            sub_issue_stores.unregister('tab:board:in-progress');
+          } catch {
+            // ignore
+          }
+        }
+        if (unsub_board_closed) {
+          void unsub_board_closed().catch(() => {});
+          unsub_board_closed = null;
+          try {
+            sub_issue_stores.unregister('tab:board:closed');
+          } catch {
+            // ignore
+          }
+        }
+        if (unsub_board_blocked) {
+          void unsub_board_blocked().catch(() => {});
+          unsub_board_blocked = null;
+          try {
+            sub_issue_stores.unregister('tab:board:blocked');
+          } catch {
+            // ignore
           }
         }
       }
-    });
+    }
 
-    // Toggle route shells on view/detail change and persist
-    const data = createDataLayer(/** @type {any} */ (transport), client.on);
-    const epics_view = createEpicsView(epics_root, data, (id) =>
-      router.gotoIssue(id)
-    );
-    const board_view = createBoardView(
-      board_root,
-      data,
-      (id) => router.gotoIssue(id),
-      store
-    );
-    // Preload epics when switching to view
     /**
+     * Manage route visibility and list subscriptions per view.
      * @param {{ selected_id: string | null, view: 'issues'|'epics'|'board', filters: any }} s
      */
     const onRouteChange = (s) => {
@@ -334,6 +606,9 @@ export function bootstrap(root_element) {
         board_root.hidden = s.view !== 'board';
         // detail_mount visibility handled in subscription above
       }
+      // Ensure subscriptions for the active tab before loading the view to
+      // avoid empty initial renders due to racing list-delta.
+      ensureTabSubscriptions(s);
       if (!s.selected_id && s.view === 'epics') {
         void epics_view.load();
       }
@@ -350,12 +625,13 @@ export function bootstrap(root_element) {
     // Ensure initial state is reflected (fixes reload on #/epics)
     onRouteChange(store.getState());
 
+    // Removed redundant filter-change subscription: handled by ensureTabSubscriptions
+
     // Keyboard shortcuts: Ctrl/Cmd+N opens new issue; Ctrl/Cmd+Enter submits inside dialog
     window.addEventListener('keydown', (ev) => {
       const is_modifier = ev.ctrlKey || ev.metaKey;
       const key = String(ev.key || '').toLowerCase();
-      /** @type {HTMLElement} */
-      const target = /** @type {any} */ (ev.target);
+      const target = /** @type {HTMLElement} */ (ev.target);
       const tag =
         target && target.tagName ? String(target.tagName).toLowerCase() : '';
       const is_editable =

package/app/protocol.js

@@ -6,17 +6,10 @@
  * - Client → Server uses RequestEnvelope.
  * - Server → Client uses ReplyEnvelope.
  * - Every request is correlated by `id` in replies.
- * - Server can also send unsolicited events (e.g., `issues-changed`).
- *
- * Versioning
- * - Increment `PROTOCOL_VERSION` on breaking changes.
- * - Add new message types without breaking existing ones when possible.
+ * - Server can also send unsolicited events (e.g., subscription `snapshot`).
  */
 
-/** @constant {string} */
-export const PROTOCOL_VERSION = '1.0.0';
-
-/** @typedef {'list-issues'|'show-issue'|'update-status'|'edit-text'|'update-priority'|'create-issue'|'list-ready'|'subscribe-updates'|'issues-changed'|'dep-add'|'dep-remove'|'epic-status'|'update-assignee'|'label-add'|'label-remove'} MessageType */
+/** @typedef {'list-issues'|'update-status'|'edit-text'|'update-priority'|'create-issue'|'list-ready'|'dep-add'|'dep-remove'|'epic-status'|'update-assignee'|'label-add'|'label-remove'|'subscribe-list'|'unsubscribe-list'|'snapshot'|'upsert'|'delete'} MessageType */
 
 /**
  * @typedef {Object} RequestEnvelope
@@ -44,20 +37,23 @@ export const PROTOCOL_VERSION = '1.0.0';
 /** @type {MessageType[]} */
 export const MESSAGE_TYPES = /** @type {const} */ ([
   'list-issues',
-  'show-issue',
   'update-status',
   'edit-text',
   'update-priority',
   'create-issue',
   'list-ready',
-  'subscribe-updates',
-  'issues-changed',
   'dep-add',
   'dep-remove',
   'epic-status',
   'update-assignee',
   'label-add',
-  'label-remove'
+  'label-remove',
+  'subscribe-list',
+  'unsubscribe-list',
+  // vNext per-subscription full-issue push events
+  'snapshot',
+  'upsert',
+  'delete'
 ]);
 
 /**
@@ -162,7 +158,7 @@ export function isReply(value) {
     return false;
   }
   if (value.ok === false) {
-    const err = /** @type {any} */ (value).error;
+    const err = value.error;
     if (
       !isRecord(err) ||
       typeof err.code !== 'string' ||

package/app/protocol.md

@@ -1,4 +1,12 @@
-# beads-ui WebSocket Protocol (v1.0.0)
+# beads-ui WebSocket Protocol (v2.0.0)
+
+Note (2025-10-26)
+
+- The server no longer implements legacy read RPCs `list-issues` and
+  `epic-status`. Clients must use the push-only protocol described in
+  `docs/protocol/issues-push-v2.md` (subscribe-list with per-subscription events
+  snapshot/upsert/delete). The shapes below are retained for historical
+  reference of v1.
 
 This document defines the JSON messages exchanged between the browser client and
 the local server.
@@ -13,13 +21,13 @@ the local server.
 - ReplyEnvelope:
   `{ id: string, ok: boolean, type: string, payload?: any, error?: { code: string, message: string, details?: any } }`
 
-Server may send unsolicited events (e.g., `issues-changed`) using the
-ReplyEnvelope shape with `ok: true` and a generated `id`.
+Server may send unsolicited events (e.g., subscription
+`snapshot`/`upsert`/`delete`) using the ReplyEnvelope shape with `ok: true` and
+a generated `id`.
 
 ## Message Types
 
-- `list-issues` payload: `{ filters?: { status?: string, priority?: number } }`
-- `show-issue` payload: `{ id: string }`
+- Removed in v2: `list-issues` (use subscriptions + push stores)
 - `update-status` payload:
   `{ id: string, status: 'open'|'in_progress'|'closed' }`
 - `edit-text` payload:
@@ -28,9 +36,9 @@ ReplyEnvelope shape with `ok: true` and a generated `id`.
 - `create-issue` payload:
   `{ title: string, type?: 'bug'|'feature'|'task'|'epic'|'chore', priority?: 0|1|2|3|4, description?: string }`
 - `list-ready` payload: `{}`
-- `subscribe-updates` payload: `{}` (server responds with `ok` and begins
-  emitting events)
-- `issues-changed` payload: `{ ts: number, hint?: { ids?: string[] } }`
+- Removed in v2: `subscribe-updates` and the `issues-changed` event. All list
+  and detail updates flow via per-subscription push envelopes
+  (`snapshot`/`upsert`/`delete`).
 - `dep-add` payload: `{ a: string, b: string, view_id?: string }` where `a`
   depends on `b` (i.e., `a` is blocked by `b`). Reply payload is the updated
   issue for `view_id` (or `a` when omitted).
@@ -40,8 +48,8 @@ ReplyEnvelope shape with `ok: true` and a generated `id`.
 
 ## Mapping to `bd` CLI
 
-- `list-issues` → `bd list --json [--status <s>] [--priority <n>]`
-- `show-issue` → `bd show <id> --json`
+- Removed in v2: `list-issues` → use subscriptions and push
+  (`docs/protocol/issues-push-v2.md`)
 - `update-status` → `bd update <id> --status <status>`
 - `edit-text` → `bd update <id> --title <t>` or `--description <d>` or
   `--acceptance-criteria <a>` or `--notes <n>` or `--design <z>`
@@ -56,8 +64,3 @@ Errors follow the shape `{ code, message, details? }`. Common codes:
 - `bad_request` – malformed payload or unknown type
 - `not_found` – entity not found (e.g., issue id)
 - `bd_error` – underlying `bd` command failed
-
-## Versioning
-
-Breaking changes to shapes or semantics increment `PROTOCOL_VERSION` in
-`app/protocol.js`.