beads-ui 0.3.0 → 0.3.1

package/CHANGES.md

@@ -1,5 +1,14 @@
 # Changes
 
+## 0.3.1
+
+- [`3912ae5`](https://github.com/mantoni/beads-ui/commit/3912ae552b1cc97e61fbaaa0815ca77675c542e4)
+  Status filter intermittently not applied on Issues screen
+- [`a160484`](https://github.com/mantoni/beads-ui/commit/a16048479d1d7d61ed4ad4e53365a5736eb053af)
+  Upgrade eslint-plugin-jsdoc and switch config
+
+_Released by [Maximilian Antoni](https://github.com/mantoni) on 2025-10-27._
+
 ## 0.3.0
 
 - 🍏 Rewrite data-exchange layer to push-only updates via WebSocket.

package/app/data/list-selectors.js

@@ -13,6 +13,7 @@ import { cmpClosedDesc, cmpPriorityThenCreated } from './sort.js';
  *
  * Source of truth is per-subscription stores providing snapshots for a given
  * client id. Central issues store fallback has been removed.
+ *
  * @param {{ snapshotFor?: (client_id: string) => IssueLite[], subscribe?: (fn: () => void) => () => void }} [issue_stores]
  */
 export function createListSelectors(issue_stores = undefined) {
@@ -20,6 +21,7 @@ export function createListSelectors(issue_stores = undefined) {
 
   /**
    * Get entities for a subscription id with Issues List sort (priority asc → created asc).
+   *
    * @param {string} client_id
    * @returns {IssueLite[]}
    */
@@ -35,6 +37,7 @@ export function createListSelectors(issue_stores = undefined) {
 
   /**
    * Get entities for a Board column with column-specific sort.
+   *
    * @param {string} client_id
    * @param {'ready'|'blocked'|'in_progress'|'closed'} mode
    * @returns {IssueLite[]}
@@ -58,6 +61,7 @@ export function createListSelectors(issue_stores = undefined) {
   /**
    * Get children for an epic subscribed as client id `epic:${id}`.
    * Sorted as Issues List (priority asc → created asc).
+   *
    * @param {string} epic_id
    * @returns {IssueLite[]}
    */
@@ -79,6 +83,7 @@ export function createListSelectors(issue_stores = undefined) {
 
   /**
    * Subscribe for re-render; triggers once per issues envelope.
+   *
    * @param {() => void} fn
    * @returns {() => void}
    */

package/app/data/providers.js

@@ -5,6 +5,7 @@
  * Data layer: typed wrappers around the ws transport for mutations and
  * single-issue fetch. List reads have been removed in favor of push-only
  * stores and selectors (see docs/adr/001-push-only-lists.md).
+ *
  * @param {(type: MessageType, payload?: unknown) => Promise<unknown>} transport - Request/response function.
  * @returns {{ updateIssue: (input: { id: string, title?: string, acceptance?: string, notes?: string, design?: string, status?: 'open'|'in_progress'|'closed', priority?: number, assignee?: string }) => Promise<unknown> }}
  */
@@ -13,6 +14,7 @@ export function createDataLayer(transport) {
    * Update issue fields by dispatching specific mutations.
    * Supported fields: title, acceptance, notes, design, status, priority, assignee.
    * Returns the updated issue on success.
+   *
    * @param {{ id: string, title?: string, acceptance?: string, notes?: string, design?: string, status?: 'open'|'in_progress'|'closed', priority?: number, assignee?: string }} input
    * @returns {Promise<unknown>}
    */

package/app/data/sort.js

@@ -9,6 +9,7 @@
 
 /**
  * Compare by priority asc, then created_at asc, then id asc.
+ *
  * @param {IssueLite} a
  * @param {IssueLite} b
  */
@@ -30,6 +31,7 @@ export function cmpPriorityThenCreated(a, b) {
 
 /**
  * Compare by closed_at desc, then id asc for stability.
+ *
  * @param {IssueLite} a
  * @param {IssueLite} b
  */

package/app/data/subscription-issue-store.js

@@ -9,10 +9,9 @@ import { cmpPriorityThenCreated } from './sort.js';
  * delete messages in revision order and preserves object identity per id.
  */
 
-// Sort comparator is centralized in app/data/sort.js
-
 /**
  * Create a SubscriptionIssueStore for a given subscription id.
+ *
  * @param {string} id
  * @param {SubscriptionIssueStoreOptions} [options]
  * @returns {SubscriptionIssueStore}
@@ -50,6 +49,7 @@ export function createSubscriptionIssueStore(id, options = {}) {
    * - Ignore messages with revision <= last_revision (except snapshot which resets first).
    * - Preserve object identity when updating an existing item by mutating
    *   fields in place rather than replacing the object reference.
+   *
    * @param {{ type: 'snapshot'|'upsert'|'delete', id: string, revision: number, issues?: any[], issue?: any, issue_id?: string }} msg
    */
   function applyPush(msg) {

package/app/data/subscription-issue-stores.js

@@ -10,9 +10,6 @@ import { subKeyOf } from './subscriptions-store.js';
  * push envelopes (snapshot/upsert/delete) per subscription id and expose
  * read-only snapshots for rendering.
  */
-
-/**
- */
 export function createSubscriptionIssueStores() {
   /** @type {Map<string, ReturnType<typeof createSubscriptionIssueStore>>} */
   const stores_by_id = new Map();
@@ -36,19 +33,48 @@ export function createSubscriptionIssueStores() {
   /**
    * Ensure a store exists for client_id and attach a listener that fans out
    * store-level updates to global listeners.
+   *
    * @param {string} client_id
    * @param {{ type: string, params?: Record<string, string|number|boolean> }} [spec]
    * @param {SubscriptionIssueStoreOptions} [options]
    */
   function register(client_id, spec, options) {
-    key_by_id.set(client_id, spec ? subKeyOf(spec) : '');
-    if (!stores_by_id.has(client_id)) {
+    const next_key = spec ? subKeyOf(spec) : '';
+    const prev_key = key_by_id.get(client_id) || '';
+    const has_store = stores_by_id.has(client_id);
+    // If the subscription spec changed for an existing client id, replace the
+    // underlying store to reset revision state and avoid ignoring a fresh
+    // snapshot with a lower revision (different server list).
+    if (has_store && prev_key && next_key && prev_key !== next_key) {
+      const prev_store = stores_by_id.get(client_id);
+      if (prev_store) {
+        try {
+          prev_store.dispose();
+        } catch {
+          // ignore
+        }
+      }
+      const off_prev = store_unsubs.get(client_id);
+      if (off_prev) {
+        try {
+          off_prev();
+        } catch {
+          // ignore
+        }
+        store_unsubs.delete(client_id);
+      }
+      const new_store = createSubscriptionIssueStore(client_id, options);
+      stores_by_id.set(client_id, new_store);
+      const off_new = new_store.subscribe(() => emit());
+      store_unsubs.set(client_id, off_new);
+    } else if (!has_store) {
       const store = createSubscriptionIssueStore(client_id, options);
       stores_by_id.set(client_id, store);
       // Fan out per-store events to global subscribers
       const off = store.subscribe(() => emit());
       store_unsubs.set(client_id, off);
     }
+    key_by_id.set(client_id, next_key);
     return () => unregister(client_id);
   }
 

package/app/data/subscriptions-store.js

@@ -16,6 +16,7 @@
 /**
  * Generate a stable subscription key string from a spec.
  * Mirrors server `keyOf` implementation (sorted params, URLSearchParams).
+ *
  * @param {SubscriptionSpec} spec
  * @returns {string}
  */
@@ -38,9 +39,10 @@ export function subKeyOf(spec) {
  * Create a list subscription store.
  *
  * Wiring:
- *  - Use `subscribeList` to register a subscription and send the request.
+ * - Use `subscribeList` to register a subscription and send the request.
  *
  * Selectors are synchronous and return derived state by client id.
+ *
  * @param {(type: MessageType, payload?: unknown) => Promise<unknown>} send - ws send.
  */
 export function createSubscriptionStore(send) {
@@ -51,6 +53,7 @@ export function createSubscriptionStore(send) {
 
   /**
    * Apply a delta to all client ids mapped to a given key.
+   *
    * @param {string} key
    * @param {{ added: string[], updated: string[], removed: string[] }} delta
    */
@@ -91,6 +94,7 @@ export function createSubscriptionStore(send) {
    * Subscribe to a list spec with a client-provided id.
    * Returns an unsubscribe function.
    * Creates an empty items store immediately; server will publish deltas.
+   *
    * @param {string} client_id
    * @param {SubscriptionSpec} spec
    * @returns {Promise<() => Promise<void>>}
@@ -158,6 +162,7 @@ export function createSubscriptionStore(send) {
   const selectors = {
     /**
      * Get an array of item ids for a subscription.
+     *
      * @param {string} client_id
      * @returns {string[]}
      */
@@ -170,6 +175,7 @@ export function createSubscriptionStore(send) {
     },
     /**
      * Check if an id exists in a subscription.
+     *
      * @param {string} client_id
      * @param {string} id
      * @returns {boolean}
@@ -183,6 +189,7 @@ export function createSubscriptionStore(send) {
     },
     /**
      * Count items for a subscription.
+     *
      * @param {string} client_id
      * @returns {number}
      */
@@ -192,6 +199,7 @@ export function createSubscriptionStore(send) {
     },
     /**
      * Return a shallow object copy `{ [id]: true }` for rendering helpers.
+     *
      * @param {string} client_id
      * @returns {Record<string, true>}
      */

package/app/main.js

@@ -20,6 +20,7 @@ import { createWsClient } from './ws.js';
 
 /**
  * Bootstrap the SPA shell with two panels.
+ *
  * @param {HTMLElement} root_element - The container element to render into.
  */
 export function bootstrap(root_element) {
@@ -415,6 +416,7 @@ export function bootstrap(root_element) {
 
     /**
      * Compute subscription spec for Issues tab based on filters.
+     *
      * @param {{ status?: string }} filters
      * @returns {{ type: string, params?: Record<string, string|number|boolean> }}
      */
@@ -437,6 +439,7 @@ export function bootstrap(root_element) {
     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) {
@@ -596,6 +599,7 @@ export function bootstrap(root_element) {
 
     /**
      * Manage route visibility and list subscriptions per view.
+     *
      * @param {{ selected_id: string | null, view: 'issues'|'epics'|'board', filters: any }} s
      */
     const onRouteChange = (s) => {

package/app/protocol.js

@@ -58,6 +58,7 @@ export const MESSAGE_TYPES = /** @type {const} */ ([
 
 /**
  * Generate a lexically sortable request id.
+ *
  * @returns {string}
  */
 export function nextId() {
@@ -68,6 +69,7 @@ export function nextId() {
 
 /**
  * Create a request envelope.
+ *
  * @param {MessageType} type - Message type.
  * @param {unknown} [payload] - Message payload.
  * @param {string} [id] - Optional id; generated if omitted.
@@ -79,6 +81,7 @@ export function makeRequest(type, payload, id = nextId()) {
 
 /**
  * Create a successful reply envelope for a given request.
+ *
  * @param {RequestEnvelope} req - Original request.
  * @param {unknown} [payload] - Reply payload.
  * @returns {ReplyEnvelope}
@@ -89,10 +92,11 @@ export function makeOk(req, payload) {
 
 /**
  * Create an error reply envelope for a given request.
+ *
  * @param {RequestEnvelope} req - Original request.
- * @param {string} code - Error code.
- * @param {string} message - Error message.
- * @param {unknown} [details] - Extra details.
+ * @param {string} code
+ * @param {string} message
+ * @param {unknown} [details]
  * @returns {ReplyEnvelope}
  */
 export function makeError(req, code, message, details) {
@@ -106,6 +110,7 @@ export function makeError(req, code, message, details) {
 
 /**
  * Check if a value is a plain object.
+ *
  * @param {unknown} value
  * @returns {value is Record<string, unknown>}
  */
@@ -115,6 +120,7 @@ function isRecord(value) {
 
 /**
  * Type guard for MessageType values.
+ *
  * @param {unknown} value
  * @returns {value is MessageType}
  */
@@ -127,6 +133,7 @@ export function isMessageType(value) {
 
 /**
  * Type guard for RequestEnvelope.
+ *
  * @param {unknown} value
  * @returns {value is RequestEnvelope}
  */
@@ -143,6 +150,7 @@ export function isRequest(value) {
 
 /**
  * Type guard for ReplyEnvelope.
+ *
  * @param {unknown} value
  * @returns {value is ReplyEnvelope}
  */
@@ -173,6 +181,7 @@ export function isReply(value) {
 /**
  * Normalize and validate an incoming JSON value as a RequestEnvelope.
  * Throws a user-friendly error if invalid.
+ *
  * @param {unknown} json
  * @returns {RequestEnvelope}
  */
@@ -185,6 +194,7 @@ export function decodeRequest(json) {
 
 /**
  * Normalize and validate an incoming JSON value as a ReplyEnvelope.
+ *
  * @param {unknown} json
  * @returns {ReplyEnvelope}
  */

package/app/router.js

@@ -8,6 +8,7 @@ import { issueHashFor } from './utils/issue-url.js';
  * Parse an application hash and extract the selected issue id.
  * Supports canonical form "#/(issues|epics|board)?issue=<id>" and legacy
  * "#/issue/<id>" which we will rewrite to the canonical form.
+ *
  * @param {string} hash
  * @returns {string | null}
  */
@@ -31,6 +32,7 @@ export function parseHash(hash) {
 
 /**
  * Parse the current view from hash.
+ *
  * @param {string} hash
  * @returns {'issues'|'epics'|'board'}
  */
@@ -95,6 +97,7 @@ export function createHashRouter(store) {
     },
     /**
      * Navigate to a top-level view.
+     *
      * @param {'issues'|'epics'|'board'} view
      */
     /**

package/app/state.js

@@ -28,6 +28,7 @@
 
 /**
  * Create a simple store for application state.
+ *
  * @param {Partial<AppState>} [initial]
  * @returns {{ getState: () => AppState, setState: (patch: { selected_id?: string | null, filters?: Partial<Filters> }) => void, subscribe: (fn: (s: AppState) => void) => () => void }}
  */
@@ -71,6 +72,7 @@ export function createStore(initial = {}) {
     },
     /**
      * Update state. Nested filters can be partial.
+     *
      * @param {{ selected_id?: string | null, filters?: Partial<Filters>, board?: Partial<BoardState> }} patch
      */
     setState(patch) {

package/app/utils/issue-id-renderer.js

@@ -5,6 +5,7 @@ import { issueDisplayId } from './issue-id.js';
  * Looks like the current inline ID (monospace `#123`) but acts as a button
  * that copies the full, prefixed ID (e.g., `UI-123`) when activated.
  * Shows transient "Copied" feedback and then restores the ID.
+ *
  * @param {string} id - Full issue id including the prefix (e.g., "UI-123").
  * @param {{ class_name?: string, duration_ms?: number }} [opts]
  * @returns {HTMLButtonElement}
@@ -25,7 +26,7 @@ export function createIssueIdRenderer(id, opts) {
   const label = issueDisplayId(id);
   btn.textContent = label;
 
-  /** Copy handler with feedback */
+  /** Copy handler with feedback. */
   async function doCopy() {
     // Prevent accidental row navigation and parent handlers
     // (click/key handlers call this inside an event context)

package/app/utils/issue-id.js

@@ -1,6 +1,7 @@
 /**
  * Format a beads issue id as a user-facing display string `#${n}`.
  * Extracts the trailing numeric portion of the id and prefixes with '#'.
+ *
  * @param {string | null | undefined} id
  * @returns {string}
  */

package/app/utils/issue-type.js

@@ -1,11 +1,13 @@
 /**
  * Known issue types in canonical order for dropdowns.
+ *
  * @type {Array<'bug'|'feature'|'task'|'epic'|'chore'>}
  */
 export const ISSUE_TYPES = ['bug', 'feature', 'task', 'epic', 'chore'];
 
 /**
  * Return a human-friendly label for an issue type.
+ *
  * @param {string | null | undefined} type
  * @returns {string}
  */

package/app/utils/issue-url.js

@@ -1,5 +1,6 @@
 /**
  * Build a canonical issue hash that retains the view.
+ *
  * @param {'issues'|'epics'|'board'} view
  * @param {string} id
  */

package/app/utils/markdown.js

@@ -1,5 +1,4 @@
 import DOMPurify from 'dompurify';
-import { html } from 'lit-html';
 import { unsafeHTML } from 'lit-html/directives/unsafe-html.js';
 import { marked } from 'marked';
 
@@ -7,16 +6,11 @@ import { marked } from 'marked';
  * Render Markdown safely as HTML using marked and DOMPurify.
  * Returns a lit-html TemplateResult via the unsafeHTML directive so it can be
  * embedded directly in templates.
- * @function renderMarkdown
- * @param {string} src Markdown source text
- * @returns {import('lit-html').TemplateResult}
+ *
+ * @param {string} markdown - Markdown source text
  */
-export function renderMarkdown(src) {
-  /** @type {string} */
-  const markdown = String(src || '');
-  /** @type {string} */
+export function renderMarkdown(markdown) {
   const parsed = /** @type {string} */ (marked.parse(markdown));
-  /** @type {string} */
   const html_string = DOMPurify.sanitize(parsed);
-  return html`${unsafeHTML(html_string)}`;
+  return unsafeHTML(html_string);
 }

package/app/utils/priority-badge.js

@@ -2,6 +2,7 @@ import { priority_levels } from './priority.js';
 
 /**
  * Create a colored badge for a priority value (0..4).
+ *
  * @param {number | null | undefined} priority
  * @returns {HTMLSpanElement}
  */

package/app/utils/status-badge.js

@@ -1,5 +1,6 @@
 /**
  * Create a colored badge for a status value.
+ *
  * @param {string | null | undefined} status - 'open' | 'in_progress' | 'closed'
  * @returns {HTMLSpanElement}
  */

package/app/utils/status.js

@@ -1,11 +1,13 @@
 /**
  * Known status values in canonical order.
+ *
  * @type {Array<'open'|'in_progress'|'closed'>}
  */
 export const STATUSES = ['open', 'in_progress', 'closed'];
 
 /**
  * Map canonical status to display label.
+ *
  * @param {string | null | undefined} status
  * @returns {string}
  */

package/app/utils/toast.js

@@ -1,5 +1,6 @@
 /**
  * Show a transient global toast message anchored to the viewport.
+ *
  * @param {string} text - Message text.
  * @param {'info'|'success'|'error'} [variant] - Visual variant.
  * @param {number} [duration_ms] - Auto-dismiss delay in milliseconds.

package/app/utils/type-badge.js

@@ -1,5 +1,6 @@
 /**
  * Create a compact, colored badge for an issue type.
+ *
  * @param {string | undefined | null} issue_type - One of: bug, feature, task, epic, chore
  * @returns {HTMLSpanElement}
  */

package/app/views/board.js

@@ -23,8 +23,9 @@ import { createTypeBadge } from '../utils/type-badge.js';
  * Push-only: derives items from per-subscription stores.
  *
  * Sorting rules:
- * - Ready/Blocked/In progress: priority asc, then created_at asc
- * - Closed: closed_at desc
+ * - Ready/Blocked/In progress: priority asc, then created_at asc.
+ * - Closed: closed_at desc.
+ *
  * @param {HTMLElement} mount_element
  * @param {unknown} _data - Unused (legacy param retained for call-compat)
  * @param {(id: string) => void} gotoIssue - Navigate to issue detail.
@@ -58,6 +59,7 @@ export function createBoardView(
    * Closed column filter mode.
    * 'today' → items with closed_at since local day start
    * '3' → last 3 days; '7' → last 7 days
+   *
    * @type {'today'|'3'|'7'}
    */
   let closed_filter_mode = 'today';
@@ -165,10 +167,10 @@ export function createBoardView(
 
   /**
    * Enhance rendered board with a11y and keyboard navigation.
-   * - Roving tabindex per column (first card tabbable)
-   * - ArrowUp/ArrowDown within column
-   * - ArrowLeft/ArrowRight to adjacent non-empty column (focus top card)
-   * - Enter/Space to open details for focused card
+   * - Roving tabindex per column (first card tabbable).
+   * - ArrowUp/ArrowDown within column.
+   * - ArrowLeft/ArrowRight to adjacent non-empty column (focus top card).
+   * - Enter/Space to open details for focused card.
    */
   function postRenderEnhance() {
     try {

package/app/views/detail.js

@@ -44,6 +44,7 @@ function defaultNavigateFn(hash) {
 
 /**
  * Create the Issue Detail view.
+ *
  * @param {HTMLElement} mount_element - Element to render into.
  * @param {(type: string, payload?: unknown) => Promise<unknown>} sendFn - RPC transport.
  * @param {(hash: string) => void} [navigateFn] - Navigation function; defaults to setting location.hash.
@@ -1071,6 +1072,7 @@ export function createDetailView(
 
   /**
    * Create a click handler for the remove button of a dependency row.
+   *
    * @param {string} did
    * @param {'Dependencies'|'Dependents'} title
    * @returns {(ev: Event) => Promise<void>}
@@ -1114,6 +1116,7 @@ export function createDetailView(
 
   /**
    * Create a click handler for the Add button in a dependency section.
+   *
    * @param {Dependency[]} items
    * @param {'Dependencies'|'Dependents'} title
    * @returns {(ev: Event) => Promise<void>}

package/app/views/epics.js

@@ -9,11 +9,12 @@ import { createIssueRowRenderer } from './issue-row.js';
 
 /**
  * Epics view (push-only):
- * - Derives epic groups from the local issues store (no RPC reads)
- * - Subscribes to `tab:epics` for top-level membership
- * - On expand, subscribes to `detail:{id}` (issue-detail) for the epic
- * - Renders children from the epic detail's `dependents` list
- * - Provides inline edits via mutations; UI re-renders on push
+ * - Derives epic groups from the local issues store (no RPC reads).
+ * - Subscribes to `tab:epics` for top-level membership.
+ * - On expand, subscribes to `detail:{id}` (issue-detail) for the epic.
+ * - Renders children from the epic detail's `dependents` list.
+ * - Provides inline edits via mutations; UI re-renders on push.
+ *
  * @param {HTMLElement} mount_element
  * @param {{ updateIssue: (input: any) => Promise<any> }} data
  * @param {(id: string) => void} goto_issue - Navigate to issue detail.

package/app/views/issue-dialog.js

@@ -10,6 +10,7 @@ import { createIssueIdRenderer } from '../utils/issue-id-renderer.js';
 
 /**
  * Create and manage the Issue Details dialog.
+ *
  * @param {HTMLElement} mount_element - Container to attach the <dialog> to (e.g., #detail-panel)
  * @param {Store} store - Read-only access to app state
  * @param {() => void} onClose - Called when dialog requests close (backdrop/esc/button)

package/app/views/issue-row.js

@@ -12,6 +12,7 @@ import { createTypeBadge } from '../utils/type-badge.js';
 /**
  * Create a reusable issue row renderer used by list and epics views.
  * Handles inline editing for title/assignee and selects for status/priority.
+ *
  * @param {{
  *   navigate: (id: string) => void,
  *   onUpdate: (id: string, patch: { title?: string, assignee?: string, status?: 'open'|'in_progress'|'closed', priority?: number }) => Promise<void>,

package/app/views/list.js

@@ -15,6 +15,7 @@ import { createIssueRowRenderer } from './issue-row.js';
 
 /**
  * Create the Issues List view.
+ *
  * @param {HTMLElement} mount_element - Element to render into.
  * @param {(type: string, payload?: unknown) => Promise<unknown>} sendFn - RPC transport.
  * @param {(hash: string) => void} [navigate_fn] - Navigation function (defaults to setting location.hash).
@@ -25,6 +26,7 @@ import { createIssueRowRenderer } from './issue-row.js';
  */
 /**
  * Create the Issues List view.
+ *
  * @param {HTMLElement} mount_element
  * @param {(type: string, payload?: unknown) => Promise<unknown>} sendFn
  * @param {(hash: string) => void} [navigateFn]
@@ -104,6 +106,7 @@ export function createListView(
 
   /**
    * Event: type select change.
+   *
    * @param {Event} ev
    */
   const onTypeChange = (ev) => {
@@ -237,6 +240,7 @@ export function createListView(
 
   /**
    * Update minimal fields inline via ws mutations and refresh that row's data.
+   *
    * @param {string} id
    * @param {{ [k: string]: any }} patch
    */

package/app/views/nav.js

@@ -2,6 +2,7 @@ import { html, render } from 'lit-html';
 
 /**
  * Render the top navigation with three tabs and handle route changes.
+ *
  * @param {HTMLElement} mount_element
  * @param {{ getState: () => any, subscribe: (fn: (s: any) => void) => () => void }} store
  * @param {{ gotoView: (v: 'issues'|'epics'|'board') => void }} router

package/app/views/new-issue-dialog.js

@@ -3,6 +3,7 @@ import { priority_levels } from '../utils/priority.js';
 
 /**
  * Create and manage the New Issue dialog (native <dialog>).
+ *
  * @param {HTMLElement} mount_element - Container to attach dialog (e.g., main#app)
  * @param {(type: import('../protocol.js').MessageType, payload?: unknown) => Promise<unknown>} sendFn - Transport function
  * @param {{ gotoIssue: (id: string) => void }} router - Router for opening details after create
@@ -184,6 +185,7 @@ export function createNewIssueDialog(mount_element, sendFn, router, store) {
 
   /**
    * Extract numeric suffix from an id like "UI-123"; return -1 when absent.
+   *
    * @param {string} id
    */
   function idNumeric(id) {
@@ -193,6 +195,7 @@ export function createNewIssueDialog(mount_element, sendFn, router, store) {
 
   /**
    * Submit handler: validate, create, then open the created issue details.
+   *
    * @returns {Promise<void>}
    */
   async function createNow() {

package/app/ws.js

@@ -1,4 +1,3 @@
-/* global Console */
 /**
  * @import { MessageType } from './protocol.js'
  */
@@ -27,6 +26,7 @@ import { MESSAGE_TYPES, makeRequest, nextId } from './protocol.js';
 
 /**
  * Create a WebSocket client with auto-reconnect and message correlation.
+ *
  * @param {ClientOptions} [options]
  */
 export function createWsClient(options = {}) {
@@ -211,6 +211,7 @@ export function createWsClient(options = {}) {
   return {
     /**
      * Send a request and await its correlated reply payload.
+     *
      * @param {MessageType} type
      * @param {unknown} [payload]
      * @returns {Promise<any>}
@@ -233,6 +234,7 @@ export function createWsClient(options = {}) {
     /**
      * Register a handler for a server-initiated event type.
      * Returns an unsubscribe function.
+     *
      * @param {MessageType} type
      * @param {(payload: any) => void} handler
      * @returns {() => void}
@@ -249,6 +251,7 @@ export function createWsClient(options = {}) {
     },
     /**
      * Subscribe to connection state changes.
+     *
      * @param {(state: ConnectionState) => void} handler
      * @returns {() => void}
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beads-ui",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Local‑first UI for Beads — a fast issue tracker for your coding agent.",
   "homepage": "https://github.com/mantoni/beads-ui",
   "type": "module",
@@ -32,9 +32,8 @@
     "@types/ws": "^8.18.1",
     "eslint": "^9.11.0",
     "eslint-plugin-import": "^2.29.1",
-    "eslint-plugin-jsdoc": "^48.10.2",
+    "eslint-plugin-jsdoc": "^61.1.9",
     "eslint-plugin-n": "^17.9.0",
-    "eslint-plugin-promise": "^6.1.1",
     "globals": "^16.4.0",
     "jsdom": "^27.0.1",
     "prettier": "^3.3.3",

package/server/app.js

@@ -6,6 +6,7 @@ import path from 'node:path';
 
 /**
  * Create and configure the Express application.
+ *
  * @param {{ host: string, port: number, env: string, app_dir: string, root_dir: string }} config - Server configuration.
  * @returns {Express} Configured Express app instance.
  */
@@ -28,6 +29,7 @@ export function createApp(config) {
   /**
    * On-demand bundle for the browser using esbuild.
    * Note: esbuild is loaded lazily so tests don't require it to be installed.
+   *
    * @param {Request} _req
    * @param {Response} res
    */

package/server/bd.js

@@ -3,6 +3,7 @@ import { resolveDbPath } from './db.js';
 
 /**
  * Resolve the bd executable path.
+ *
  * @returns {string}
  */
 export function getBdBin() {
@@ -16,6 +17,7 @@ export function getBdBin() {
 /**
  * Run the `bd` CLI with provided arguments.
  * Shell is not used to avoid injection; args must be pre-split.
+ *
  * @param {string[]} args - Arguments to pass (e.g., ["list", "--json"]).
  * @param {{ cwd?: string, env?: Record<string, string | undefined>, timeout_ms?: number }} [options]
  * @returns {Promise<{ code: number, stdout: string, stderr: string }>}
@@ -88,6 +90,7 @@ export function runBd(args, options = {}) {
 
 /**
  * Run `bd` and parse JSON from stdout if exit code is 0.
+ *
  * @param {string[]} args - Must include flags that cause JSON to be printed (e.g., `--json`).
  * @param {{ cwd?: string, env?: Record<string, string | undefined>, timeout_ms?: number }} [options]
  * @returns {Promise<{ code: number, stdoutJson?: unknown, stderr?: string }>}
@@ -109,6 +112,7 @@ export async function runBdJson(args, options = {}) {
 
 /**
  * Add a resolved "--db <path>" pair to args when none present.
+ *
  * @param {string[]} args
  * @param {string} cwd
  * @param {Record<string, string | undefined>} env

package/server/cli/commands.js

@@ -13,6 +13,7 @@ import { openUrl, waitForServer } from './open.js';
  * Handle `start` command. Idempotent when already running.
  * - Spawns a detached server process, writes PID file, returns 0.
  * - If already running (PID file present and process alive), prints URL and returns 0.
+ *
  * @returns {Promise<number>} Exit code (0 on success)
  */
 /**
@@ -52,6 +53,7 @@ export async function handleStart(options) {
  * Handle `stop` command.
  * - Sends SIGTERM and waits for exit (with SIGKILL fallback), removes PID file.
  * - Returns 2 if not running.
+ *
  * @returns {Promise<number>} Exit code
  */
 export async function handleStop() {
@@ -78,12 +80,14 @@ export async function handleStop() {
 
 /**
  * Handle `restart` command: stop (ignore not-running) then start.
+ *
  * @returns {Promise<number>} Exit code (0 on success)
  */
 /**
  * Handle `restart` command: stop (ignore not-running) then start.
  * Accepts the same options as `handleStart` and passes them through,
  * so restart only opens a browser when `no_open` is explicitly false.
+ *
  * @param {{ no_open?: boolean }} [options]
  * @returns {Promise<number>}
  */

package/server/cli/daemon.js

@@ -13,6 +13,7 @@ import { resolveDbPath } from '../db.js';
  * Resolve the runtime directory used for PID and log files.
  * Prefers `BDUI_RUNTIME_DIR`, then `$XDG_RUNTIME_DIR/beads-ui`,
  * and finally `os.tmpdir()/beads-ui`.
+ *
  * @returns {string}
  */
 export function getRuntimeDir() {
@@ -31,6 +32,7 @@ export function getRuntimeDir() {
 
 /**
  * Ensure a directory exists with safe permissions and return its path.
+ *
  * @param {string} dir_path
  * @returns {string}
  */
@@ -61,6 +63,7 @@ export function getLogFilePath() {
 
 /**
  * Read PID from the PID file if present.
+ *
  * @returns {number | null}
  */
 export function readPidFile() {
@@ -100,6 +103,7 @@ export function removePidFile() {
 
 /**
  * Check whether a process is running.
+ *
  * @param {number} pid
  * @returns {boolean}
  */
@@ -122,6 +126,7 @@ export function isProcessRunning(pid) {
 
 /**
  * Compute the absolute path to the server entry file.
+ *
  * @returns {string}
  */
 export function getServerEntryPath() {
@@ -134,6 +139,7 @@ export function getServerEntryPath() {
 /**
  * Spawn the server as a detached daemon, redirecting stdio to the log file.
  * Writes the PID file upon success.
+ *
  * @returns {{ pid: number } | null} Returns child PID on success; null on failure.
  */
 export function startDaemon() {
@@ -183,6 +189,7 @@ export function startDaemon() {
 
 /**
  * Send SIGTERM then (optionally) SIGKILL to stop a process and wait for exit.
+ *
  * @param {number} pid
  * @param {number} timeout_ms
  * @returns {Promise<boolean>} Resolves true if the process is gone.

package/server/cli/index.js

@@ -3,6 +3,7 @@ import { printUsage } from './usage.js';
 
 /**
  * Parse argv into a command token and flags.
+ *
  * @param {string[]} args
  * @returns {{ command: string | null, flags: string[] }}
  */
@@ -41,6 +42,7 @@ export function parseArgs(args) {
 /**
  * CLI main entry. Returns an exit code and prints usage on `--help` or errors.
  * No side effects beyond invoking stub handlers.
+ *
  * @param {string[]} args
  * @returns {Promise<number>}
  */

package/server/cli/open.js

@@ -3,6 +3,7 @@ import http from 'node:http';
 
 /**
  * Compute a platform-specific command to open a URL in the default browser.
+ *
  * @param {string} url
  * @param {string} platform
  * @returns {{ cmd: string, args: string[] }}
@@ -21,6 +22,7 @@ export function computeOpenCommand(url, platform) {
 
 /**
  * Open the given URL in the default browser. Best-effort; resolves true on spawn success.
+ *
  * @param {string} url
  * @returns {Promise<boolean>}
  */
@@ -41,6 +43,7 @@ export async function openUrl(url) {
 /**
  * Wait until the server at the URL accepts a connection, with a brief retry.
  * Does not throw; returns when either a connection was accepted or timeout elapsed.
+ *
  * @param {string} url
  * @param {number} total_timeout_ms
  * @returns {Promise<void>}

package/server/cli/usage.js

@@ -1,5 +1,6 @@
 /**
  * Print CLI usage to a stream-like target.
+ *
  * @param {{ write: (chunk: string) => any }} out_stream
  */
 export function printUsage(out_stream) {

package/server/config.js

@@ -6,8 +6,9 @@ import { fileURLToPath } from 'node:url';
  * Notes:
  * - `app_dir` is resolved relative to the installed package location.
  * - `root_dir` represents the directory where the process was invoked
- *   (i.e., the current working directory) so DB resolution follows the
- *   caller's context rather than the install location.
+ * (i.e., the current working directory) so DB resolution follows the
+ * caller's context rather than the install location.
+ *
  * @returns {{ host: string, port: number, env: string, app_dir: string, root_dir: string, url: string }}
  */
 export function getConfig() {

package/server/db.js

@@ -11,6 +11,7 @@ import path from 'node:path';
  *
  * Returns a normalized absolute path and a `source` indicator. Existence is
  * returned via the `exists` boolean.
+ *
  * @param {{ cwd?: string, env?: Record<string, string | undefined>, explicit_db?: string }} [options]
  * @returns {{ path: string, source: 'flag'|'env'|'nearest'|'home-default', exists: boolean }}
  */
@@ -48,6 +49,7 @@ export function resolveDbPath(options = {}) {
 /**
  * Find nearest .beads/*.db by walking up from start.
  * First alphabetical .db.
+ *
  * @param {string} start
  * @returns {string | null}
  */
@@ -79,6 +81,7 @@ export function findNearestBeadsDb(start) {
 
 /**
  * Resolve possibly relative `p` against `cwd` to an absolute filesystem path.
+ *
  * @param {string} p
  * @param {string} cwd
  */

package/server/list-adapters.js

@@ -3,6 +3,7 @@ import { runBdJson } from './bd.js';
 /**
  * Build concrete `bd` CLI args for a subscription type + params.
  * Always includes `--json` for parseable output.
+ *
  * @param {{ type: string, params?: Record<string, string | number | boolean> }} spec
  * @returns {string[]}
  */
@@ -43,9 +44,10 @@ export function mapSubscriptionToBdArgs(spec) {
 
 /**
  * Normalize bd list output to minimal Issue shape used by the registry.
- * - Ensures `id` is a string
- * - Coerces timestamps to numbers
- * - `closed_at` defaults to null when missing or invalid
+ * - Ensures `id` is a string.
+ * - Coerces timestamps to numbers.
+ * - `closed_at` defaults to null when missing or invalid.
+ *
  * @param {unknown} value
  * @returns {Array<{ id: string, created_at: number, updated_at: number, closed_at: number | null } & Record<string, unknown>>}
  */
@@ -95,6 +97,7 @@ export function normalizeIssueList(value) {
 /**
  * Execute the mapped `bd` command for a subscription spec and return normalized items.
  * Errors do not throw; they are surfaced as a structured object.
+ *
  * @param {{ type: string, params?: Record<string, string | number | boolean> }} spec
  * @returns {Promise<FetchListResultSuccess | FetchListResultFailure>}
  */
@@ -171,6 +174,7 @@ export async function fetchListForSubscription(spec) {
 
 /**
  * Create a `bad_request` error object.
+ *
  * @param {string} message
  */
 function badRequest(message) {
@@ -182,6 +186,7 @@ function badRequest(message) {
 
 /**
  * Normalize arbitrary thrown values to a structured error object.
+ *
  * @param {unknown} err
  * @returns {FetchListResultFailure['error']}
  */
@@ -199,6 +204,7 @@ function toErrorObject(err) {
 /**
  * Parse a bd timestamp string to epoch ms using Date.parse.
  * Falls back to numeric coercion when parsing fails.
+ *
  * @param {unknown} v
  * @returns {number}
  */

package/server/subscriptions.js

@@ -36,6 +36,7 @@
 
 /**
  * Create a new, empty entry object.
+ *
  * @returns {Entry}
  */
 function createEntry() {
@@ -49,6 +50,7 @@ function createEntry() {
 
 /**
  * Generate a stable subscription key string from a spec. Sorts params keys.
+ *
  * @param {SubscriptionSpec} spec
  * @returns {string}
  */
@@ -69,6 +71,7 @@ export function keyOf(spec) {
 
 /**
  * Compute a delta between previous and next item maps.
+ *
  * @param {Map<string, ItemMeta>} prev
  * @param {Map<string, ItemMeta>} next
  * @returns {{ added: string[], updated: string[], removed: string[] }}
@@ -101,6 +104,7 @@ export function computeDelta(prev, next) {
 
 /**
  * Normalize array of issue-like objects into an itemsById map.
+ *
  * @param {Array<{ id: string, updated_at: number, closed_at?: number|null }>} items
  * @returns {Map<string, ItemMeta>}
  */
@@ -136,6 +140,7 @@ export class SubscriptionRegistry {
 
   /**
    * Get an entry by key, or null if missing.
+   *
    * @param {string} key
    * @returns {Entry | null}
    */
@@ -145,6 +150,7 @@ export class SubscriptionRegistry {
 
   /**
    * Ensure an entry exists for a spec; returns the key and entry.
+   *
    * @param {SubscriptionSpec} spec
    * @returns {{ key: string, entry: Entry }}
    */
@@ -160,6 +166,7 @@ export class SubscriptionRegistry {
 
   /**
    * Attach a subscriber to a spec. Creates the entry if missing.
+   *
    * @param {SubscriptionSpec} spec
    * @param {WebSocket} ws
    * @returns {{ key: string, subscribed: true }}
@@ -173,6 +180,7 @@ export class SubscriptionRegistry {
   /**
    * Detach a subscriber from the spec. Keeps entry even if empty; eviction
    * is handled by `onDisconnect` sweep.
+   *
    * @param {SubscriptionSpec} spec
    * @param {WebSocket} ws
    * @returns {boolean} true when the subscriber was removed
@@ -189,6 +197,7 @@ export class SubscriptionRegistry {
   /**
    * On socket disconnect, remove it from all subscriber sets and evict any
    * entries that become empty as a result of this sweep.
+   *
    * @param {WebSocket} ws
    */
   onDisconnect(ws) {
@@ -207,6 +216,7 @@ export class SubscriptionRegistry {
 
   /**
    * Serialize a function against a key so only one runs at a time per key.
+   *
    * @template T
    * @param {string} key
    * @param {() => Promise<T>} fn
@@ -243,6 +253,7 @@ export class SubscriptionRegistry {
 
   /**
    * Replace items for a key and compute the delta, storing the new map.
+   *
    * @param {string} key
    * @param {Map<string, ItemMeta>} next_map
    * @returns {{ added: string[], updated: string[], removed: string[] }}
@@ -261,6 +272,7 @@ export class SubscriptionRegistry {
 
   /**
    * Convenience: update items from an array of objects with id/updated_at/closed_at.
+   *
    * @param {string} key
    * @param {Array<{ id: string, updated_at: number, closed_at?: number|null }>} items
    * @returns {{ added: string[], updated: string[], removed: string[] }}

package/server/validators.js

@@ -6,6 +6,7 @@
 
 /**
  * Known subscription types supported by the server.
+ *
  * @type {Set<string>}
  */
 const SUBSCRIPTION_TYPES = new Set([
@@ -20,6 +21,7 @@ const SUBSCRIPTION_TYPES = new Set([
 
 /**
  * Validate a subscribe-list payload and normalize to a SubscriptionSpec.
+ *
  * @param {unknown} payload
  * @returns {{ ok: true, id: string, spec: { type: string, params?: Record<string, string|number|boolean> } } | { ok: false, code: 'bad_request', message: string }}
  */

package/server/watcher.js

@@ -5,6 +5,7 @@ import { resolveDbPath } from './db.js';
 /**
  * Watch the resolved beads SQLite DB file and invoke a callback after a debounce window.
  * The DB path is resolved following beads precedence and can be overridden via options.
+ *
  * @param {string} root_dir - Project root directory (starting point for resolution).
  * @param {() => void} onChange - Called when changes are detected.
  * @param {{ debounce_ms?: number, explicit_db?: string }} [options]
@@ -33,6 +34,7 @@ export function watchDb(root_dir, onChange, options = {}) {
 
   /**
    * Attach a watcher to the directory containing the resolved DB path.
+   *
    * @param {string} base_dir
    * @param {string | undefined} explicit_db
    */
@@ -84,6 +86,7 @@ export function watchDb(root_dir, onChange, options = {}) {
     },
     /**
      * Re-resolve and reattach watcher when root_dir or explicit_db changes.
+     *
      * @param {{ root_dir?: string, explicit_db?: string }} [opts]
      */
     rebind(opts = {}) {

package/server/ws.js

@@ -40,6 +40,7 @@ let MUTATION_GATE = null;
  * suppressed during the window.
  *
  * Fire-and-forget; callers should not await this.
+ *
  * @param {number} [timeout_ms]
  */
 function triggerMutationRefreshOnce(timeout_ms = 500) {
@@ -95,6 +96,7 @@ function triggerMutationRefreshOnce(timeout_ms = 500) {
 
 /**
  * Collect unique active list subscription specs across all connected clients.
+ *
  * @returns {Array<{ type: string, params?: Record<string,string|number|boolean> }>}
  */
 function collectActiveListSpecs() {
@@ -181,6 +183,7 @@ let CURRENT_WSS = null;
 
 /**
  * Get or initialize the subscription state for a socket.
+ *
  * @param {WebSocket} ws
  * @returns {any}
  */
@@ -199,6 +202,7 @@ function ensureSubs(ws) {
 
 /**
  * Get next monotonically increasing revision for a subscription key on this connection.
+ *
  * @param {WebSocket} ws
  * @param {string} key
  */
@@ -306,6 +310,7 @@ function emitSubscriptionDelete(ws, client_id, key, issue_id) {
 /**
  * Refresh a subscription spec: fetch via adapter, apply to registry and emit
  * per-subscription full-issue envelopes to subscribers. Serialized per key.
+ *
  * @param {{ type: string, params?: Record<string, string|number|boolean> }} spec
  */
 async function refreshAndPublish(spec) {
@@ -362,6 +367,7 @@ async function refreshAndPublish(spec) {
 
 /**
  * Apply pre-diff filtering for closed-issues lists based on spec.params.since (epoch ms).
+ *
  * @param {{ type: string, params?: Record<string, string|number|boolean> }} spec
  * @param {Array<{ id: string, updated_at: number, closed_at: number | null } & Record<string, unknown>>} items
  */
@@ -387,6 +393,7 @@ function applyClosedIssuesFilter(spec, items) {
 
 /**
  * Attach a WebSocket server to an existing HTTP server.
+ *
  * @param {Server} http_server
  * @param {{ path?: string, heartbeat_ms?: number, refresh_debounce_ms?: number }} [options]
  * @returns {{ wss: WebSocketServer, broadcast: (type: MessageType, payload?: unknown) => void, scheduleListRefresh: () => void }}
@@ -451,6 +458,7 @@ export function attachWsServer(http_server, options = {}) {
 
   /**
    * Broadcast a server-initiated event to all open clients.
+   *
    * @param {MessageType} type
    * @param {unknown} [payload]
    */
@@ -478,6 +486,7 @@ export function attachWsServer(http_server, options = {}) {
 
 /**
  * Handle an incoming message frame and respond to the same socket.
+ *
  * @param {WebSocket} ws
  * @param {RawData} data
  */