beads-ui 0.2.0 → 0.3.1

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`.

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) {