trekoon 0.4.0 → 0.4.2

package/src/board/assets/state/api.js

@@ -13,6 +13,133 @@ function cloneSnapshot(snapshot) {
   return JSON.parse(JSON.stringify(snapshot));
 }
 
+const SNAPSHOT_COLLECTIONS = ["epics", "tasks", "subtasks", "dependencies"];
+
+const COLLECTION_TO_DELETED_KEY = {
+  epics: "deletedEpicIds",
+  tasks: "deletedTaskIds",
+  subtasks: "deletedSubtaskIds",
+  dependencies: "deletedDependencyIds",
+};
+
+function arraysShallowEqual(left, right) {
+  if (left === right) return true;
+  if (!Array.isArray(left) || !Array.isArray(right)) return false;
+  if (left.length !== right.length) return false;
+  for (let i = 0; i < left.length; i += 1) {
+    if (left[i] !== right[i]) return false;
+  }
+  return true;
+}
+
+/**
+ * Shallow equality on plain board records.
+ *
+ * Board records are flat objects whose values are primitives or arrays of
+ * primitives (e.g. dependency-id arrays). A field-by-field shallow comparison
+ * is therefore equivalent to a structural deep-equal but avoids the
+ * O(snapshot) JSON.stringify cost the previous implementation paid on every
+ * rollback. Cross-realm values and odd nested objects fall back to
+ * reference equality, which is a safe over-restore (worst case: an unchanged
+ * record is included in the inverse delta).
+ */
+function recordsShallowEqual(left, right) {
+  if (left === right) return true;
+  if (!left || !right || typeof left !== "object" || typeof right !== "object") return false;
+  const leftKeys = Object.keys(left);
+  const rightKeys = Object.keys(right);
+  if (leftKeys.length !== rightKeys.length) return false;
+  for (const key of leftKeys) {
+    const leftValue = left[key];
+    const rightValue = right[key];
+    if (leftValue === rightValue) continue;
+    if (Array.isArray(leftValue) || Array.isArray(rightValue)) {
+      if (!arraysShallowEqual(leftValue, rightValue)) return false;
+      continue;
+    }
+    return false;
+  }
+  return true;
+}
+
+function indexById(records) {
+  const map = new Map();
+  if (!Array.isArray(records)) {
+    return map;
+  }
+
+  for (const record of records) {
+    if (record && typeof record === "object" && typeof record.id === "string" && record.id.length > 0) {
+      map.set(record.id, record);
+    }
+  }
+
+  return map;
+}
+
+/**
+ * Compute the inverse delta needed to revert an optimistic mutation.
+ *
+ * The inverse is built by diffing the snapshot _before_ the optimistic patch
+ * against the snapshot _after_ the patch. We only describe entities the
+ * optimistic patch actually touched so that concurrent deltas pushed by the
+ * server (for unrelated entities) are preserved when we apply the inverse.
+ *
+ * @param {object} previousSnapshot - Snapshot prior to optimistic apply.
+ * @param {object} optimisticSnapshot - Snapshot after optimistic apply.
+ * @returns {{
+ *   epics?: object[], tasks?: object[], subtasks?: object[], dependencies?: object[],
+ *   deletedEpicIds?: string[], deletedTaskIds?: string[], deletedSubtaskIds?: string[], deletedDependencyIds?: string[],
+ * }}
+ */
+export function computeInverseDelta(previousSnapshot, optimisticSnapshot) {
+  const inverse = {};
+  for (const collection of SNAPSHOT_COLLECTIONS) {
+    const before = indexById(previousSnapshot?.[collection]);
+    const after = indexById(optimisticSnapshot?.[collection]);
+
+    const restored = [];
+    const deletedIds = [];
+
+    // Entities that the optimistic patch deleted -> restore them.
+    for (const [id, beforeRecord] of before) {
+      if (!after.has(id)) {
+        restored.push(beforeRecord);
+      }
+    }
+
+    // Entities present in both but mutated -> restore the previous version.
+    // cloneSnapshot/normalizeSnapshot always produce fresh references for
+    // every record in the optimistic snapshot, so plain reference inequality
+    // would flag every entity. Use a shallow field-by-field equality check
+    // instead — equivalent to a structural compare for these flat records but
+    // O(field) per record rather than O(snapshot) JSON.stringify on each
+    // rollback (P2 perf finding).
+    for (const [id, afterRecord] of after) {
+      const beforeRecord = before.get(id);
+      if (beforeRecord && beforeRecord !== afterRecord && !recordsShallowEqual(beforeRecord, afterRecord)) {
+        restored.push(beforeRecord);
+      }
+    }
+
+    // Entities the optimistic patch added -> mark for deletion.
+    for (const id of after.keys()) {
+      if (!before.has(id)) {
+        deletedIds.push(id);
+      }
+    }
+
+    if (restored.length > 0) {
+      inverse[collection] = restored;
+    }
+    if (deletedIds.length > 0) {
+      inverse[COLLECTION_TO_DELETED_KEY[collection]] = deletedIds;
+    }
+  }
+
+  return inverse;
+}
+
 async function readJsonPayload(response) {
   const text = await response.text();
   if (text.length === 0) {
@@ -119,14 +246,27 @@ export function createMutationQueue(model, rerender) {
 
     while (queue.length > 0) {
       const mutation = queue.shift();
-      const previousSnapshot = cloneSnapshot(model.store.snapshot);
       if (model.store.notice?.retryMutationId !== mutation.id) {
         model.store.notice = null;
       }
 
+      // Capture per-mutation inverse delta if the optimistic patch ran.
+      // Using an inverse delta (rather than wholesale replaceSnapshot) means
+      // concurrent server-pushed deltas applied to unrelated entities while
+      // the request was in flight survive a rollback.
+      let inverseDelta = null;
+
       try {
         if (typeof mutation.optimistic === "function") {
-          model.store.snapshot = mutation.optimistic(cloneSnapshot(model.store.snapshot));
+          const previousSnapshot = cloneSnapshot(model.store.snapshot);
+          const optimisticSnapshot = mutation.optimistic(cloneSnapshot(model.store.snapshot));
+          inverseDelta = computeInverseDelta(previousSnapshot, optimisticSnapshot);
+          model.store.snapshot = optimisticSnapshot;
+          // Direct snapshot mutation bypasses setState/syncState; invalidate
+          // the memo so the next getBoardState() reflects the optimistic write.
+          if (typeof model.invalidateBoardStateMemo === "function") {
+            model.invalidateBoardStateMemo();
+          }
           rerender();
         }
 
@@ -146,8 +286,11 @@ export function createMutationQueue(model, rerender) {
           ? { type: "success", message: mutation.successMessage }
           : null;
       } catch (error) {
-        // Revert to pre-optimistic snapshot
-        model.replaceSnapshot(previousSnapshot);
+        // Revert only the entities this mutation touched. Any unrelated
+        // entities updated by concurrent server deltas remain intact.
+        if (inverseDelta) {
+          model.applySnapshotDelta(inverseDelta);
+        }
 
         const message = error instanceof Error ? error.message : String(error);
         model.store.notice = {
@@ -166,6 +309,9 @@ export function createMutationQueue(model, rerender) {
 
     processing = false;
     model.store.isMutating = false;
+    if (typeof model.invalidateBoardStateMemo === "function") {
+      model.invalidateBoardStateMemo();
+    }
     rerender();
     resolveFlushes();
   }
@@ -204,20 +350,26 @@ export function createApi(model, options) {
   let lastFailedMutation = null;
 
   function enqueueMutation(definition) {
+    // Assign a stable identity token so success callbacks can clear
+    // lastFailedMutation by id rather than by function-reference equality
+    // (inline arrow functions are never the same reference across retries).
+    const mutationId = crypto.randomUUID();
+    const tagged = { ...definition, mutationId };
+
     queue.enqueue({
-      ...definition,
+      ...tagged,
       onSuccess(data) {
-        if (lastFailedMutation?.request === definition.request) {
+        if (lastFailedMutation?.mutationId === mutationId) {
           lastFailedMutation = null;
         }
-        if (typeof definition.onSuccess === "function") {
-          definition.onSuccess(data);
+        if (typeof tagged.onSuccess === "function") {
+          tagged.onSuccess(data);
         }
       },
       onError(error) {
-        lastFailedMutation = definition;
-        if (typeof definition.onError === "function") {
-          definition.onError(error);
+        lastFailedMutation = tagged;
+        if (typeof tagged.onError === "function") {
+          tagged.onError(error);
         }
       },
     });
@@ -403,3 +555,124 @@ export function createApi(model, options) {
     },
   };
 }
+
+/**
+ * Subscribe the board client to /api/snapshot/stream.
+ *
+ * Receives `snapshotDelta` events emitted by the per-server-instance event bus
+ * (own server mutations + WAL-watcher-derived deltas from external CLI writes)
+ * and applies them via `model.applySnapshotDelta`. Idempotent merge means
+ * re-applying a delta we already saw via the mutation response is harmless.
+ *
+ * Returns a `dispose()` function that closes the EventSource and stops
+ * processing further events.
+ *
+ * @param {object} model - Store with `applySnapshotDelta` method
+ * @param {object} options
+ * @param {string} options.sessionToken - Auth token (forwarded as ?token=)
+ * @param {function} options.rerender - Trigger UI rerender after applying deltas
+ * @param {typeof EventSource} [options.EventSourceCtor] - Constructor override for tests
+ * @param {string} [options.path] - Override stream path; default /api/snapshot/stream
+ * @returns {{ dispose: () => void, eventSource: EventSource | null }}
+ */
+export function subscribeSnapshotStream(model, options) {
+  const {
+    sessionToken,
+    rerender,
+    EventSourceCtor = typeof EventSource !== "undefined" ? EventSource : null,
+    path = "/api/snapshot/stream",
+  } = options ?? {};
+
+  if (!EventSourceCtor) {
+    return { dispose: () => {}, eventSource: null };
+  }
+
+  // EventSource cannot set custom headers, so the auth token rides as a query
+  // parameter. Server `extractToken` already accepts ?token=.
+  const url = sessionToken && sessionToken.length > 0
+    ? `${path}?token=${encodeURIComponent(sessionToken)}`
+    : path;
+
+  let disposed = false;
+  const eventSource = new EventSourceCtor(url);
+
+  const handleSnapshotDelta = (event) => {
+    if (disposed) return;
+    const raw = typeof event?.data === "string" ? event.data : "";
+    if (raw.length === 0) return;
+    let payload;
+    try {
+      payload = JSON.parse(raw);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      // Surface malformed payloads so operators can spot serialization bugs.
+      // Avoid logging the raw text (may include sensitive content) — just length + error.
+      console.warn(`subscribeSnapshotStream: malformed snapshotDelta JSON (${raw.length} bytes): ${message}`);
+      return;
+    }
+    const delta = payload?.snapshotDelta;
+    if (!delta || typeof delta !== "object") return;
+    model.applySnapshotDelta(delta);
+    if (typeof rerender === "function") rerender();
+  };
+
+  const handleSnapshot = (event) => {
+    if (disposed) return;
+    const raw = typeof event?.data === "string" ? event.data : "";
+    if (raw.length === 0) return;
+    let payload;
+    try {
+      payload = JSON.parse(raw);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.warn(`subscribeSnapshotStream: malformed snapshot JSON (${raw.length} bytes): ${message}`);
+      return;
+    }
+    const snapshot = payload?.snapshot;
+    if (!snapshot || typeof snapshot !== "object") return;
+    if (typeof model.replaceSnapshot === "function") {
+      model.replaceSnapshot(snapshot);
+      if (typeof rerender === "function") rerender();
+    }
+  };
+
+  const handleError = () => {
+    if (disposed) return;
+    // Surface the disconnect to the user so they don't silently miss live
+    // updates. EventSource will keep auto-reconnecting; once a snapshot/
+    // snapshotDelta event lands again, the regular notice clearing flow
+    // (e.g. on the next mutation) replaces this notice.
+    if (model.store && typeof model.store === "object") {
+      const existing = model.store.notice;
+      if (!existing || existing.code !== "live_updates_disconnected") {
+        model.store.notice = {
+          type: "warning",
+          code: "live_updates_disconnected",
+          title: "Live updates disconnected",
+          message: "Reconnecting to the server. Changes from other sessions may be delayed.",
+        };
+        if (typeof rerender === "function") rerender();
+      }
+    }
+  };
+
+  eventSource.addEventListener("snapshotDelta", handleSnapshotDelta);
+  eventSource.addEventListener("snapshot", handleSnapshot);
+  // EventSource calls .onerror on disconnect (and will continue auto-reconnecting).
+  // Use the onerror property rather than addEventListener("error") so tests can
+  // trigger it via `instance.onerror?.()` without a full event object.
+  eventSource.onerror = handleError;
+
+  return {
+    eventSource,
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      try {
+        eventSource.close();
+      } catch {
+        // best-effort
+      }
+    },
+  };
+}

package/src/board/assets/state/store.js

@@ -116,9 +116,19 @@ export function orderEpicsNewestFirst(epics) {
 
 /** Recently-done epics stay visible for 24h even when the "done" filter is off. */
 const DONE_GRACE_PERIOD_MS = 86400000;
+/**
+ * Bucket Date.now() into hour-aligned chunks so the memoized epic selector
+ * re-evaluates the 24h grace cutoff at most once per hour on a long-open page.
+ */
+const GRACE_BUCKET_MS = 3600000;
 
 const selectVisibleEpics = createSelector(
-  (s) => [s.snapshot?.epics, s.searchQuery, s.epicStatusFilter],
+  (s) => [
+    s.snapshot?.epics,
+    s.searchQuery,
+    s.epicStatusFilter,
+    Math.floor(Date.now() / GRACE_BUCKET_MS),
+  ],
   (epics, searchQuery, epicStatusFilter) => {
     if (!epics) return [];
     const now = Date.now();
@@ -224,6 +234,8 @@ function selectSearchScope(state) {
  * @property {object|null} selectedTask
  * @property {string|null} selectedSubtaskId
  * @property {object|null} selectedSubtask
+ * @property {boolean} taskModalOpen
+ * @property {boolean} subtaskModalOpen
  * @property {string} search
  * @property {string} searchQuery
  * @property {object} searchScope
@@ -231,6 +243,38 @@ function selectSearchScope(state) {
  * @property {object[]} visibleTasks
  */
 
+/**
+ * Create a memoizer for deriveBoardState that returns the same reference until
+ * invalidate() is called or the hour bucket changes (so time-sensitive
+ * selectors like selectVisibleEpics can re-evaluate the 24h grace cutoff).
+ * Designed to be invalidated by the store's notify().
+ * @param {(state: object) => BoardState} compute
+ */
+function createBoardStateMemo(compute) {
+  let cachedState = null;
+  let cachedBucket = null;
+  let cachedResult = null;
+  let dirty = true;
+
+  function get(state) {
+    const bucket = Math.floor(Date.now() / GRACE_BUCKET_MS);
+    if (!dirty && cachedState === state && cachedBucket === bucket) {
+      return cachedResult;
+    }
+    cachedState = state;
+    cachedBucket = bucket;
+    cachedResult = compute(state);
+    dirty = false;
+    return cachedResult;
+  }
+
+  function invalidate() {
+    dirty = true;
+  }
+
+  return { get, invalidate };
+}
+
 /**
  * Compute full derived board state from the internal state, using memoized selectors.
  * @param {object} state
@@ -264,6 +308,9 @@ function deriveBoardState(state) {
     : stateWithScreen;
   const selectedSubtask = selectedTaskId ? selectSelectedSubtask(stateWithTaskSelection) : null;
 
+  const taskModalOpen = state.taskModalOpen === true;
+  const subtaskModalOpen = state.subtaskModalOpen === true && selectedSubtask !== null;
+
   return {
     screen,
     selectedEpicId: selectedEpic?.id ?? null,
@@ -272,6 +319,8 @@ function deriveBoardState(state) {
     selectedTask: selectedTaskId ? selectedTask : null,
     selectedSubtaskId: selectedSubtask?.id ?? null,
     selectedSubtask,
+    taskModalOpen,
+    subtaskModalOpen,
     search: stateWithScreen.search,
     searchQuery: stateWithScreen.searchQuery,
     searchScope: selectSearchScope(stateWithScreen),
@@ -289,6 +338,8 @@ function reconcileBoardState(state) {
     view: VIEW_MODES.includes(state.view) ? state.view : "kanban",
     selectedTaskId: derived.selectedTaskId,
     selectedSubtaskId: derived.selectedSubtaskId,
+    taskModalOpen: derived.taskModalOpen,
+    subtaskModalOpen: derived.subtaskModalOpen,
   };
 }
 
@@ -331,11 +382,14 @@ export function createStore(initialSnapshot, options = {}) {
     view: VIEW_MODES.includes(storedState.view) ? storedState.view : "kanban",
     selectedTaskId: typeof storedState.selectedTaskId === "string" ? storedState.selectedTaskId : null,
     selectedSubtaskId: null,
+    taskModalOpen: false,
+    subtaskModalOpen: false,
     theme: readThemePreference(),
     focusedEpicIndex: 0,
     copyFeedback: null,
     notice: null,
     isMutating: false,
+    dragFeedback: null,
     notesPanelOpen: storedState.notesPanelOpen === true,
     epicStatusFilter: readStatusFilter(storedState.epicStatusFilter),
     taskStatusFilter: readStatusFilter(storedState.taskStatusFilter),
@@ -344,7 +398,10 @@ export function createStore(initialSnapshot, options = {}) {
   /** @type {Set<(state: object) => void>} */
   const listeners = new Set();
 
+  const boardStateMemo = createBoardStateMemo(deriveBoardState);
+
   function notify() {
+    boardStateMemo.invalidate();
     for (const listener of listeners) {
       listener(state);
     }
@@ -355,12 +412,12 @@ export function createStore(initialSnapshot, options = {}) {
       screen: state.screen,
       selectedEpicId: state.selectedEpicId,
       search: state.search,
-        view: state.view,
-        selectedTaskId: state.selectedTaskId,
-        notesPanelOpen: state.notesPanelOpen,
-        epicStatusFilter: state.epicStatusFilter,
-        taskStatusFilter: state.taskStatusFilter,
-      });
+      view: state.view,
+      selectedTaskId: state.selectedTaskId,
+      notesPanelOpen: state.notesPanelOpen,
+      epicStatusFilter: state.epicStatusFilter,
+      taskStatusFilter: state.taskStatusFilter,
+    });
   }
 
   function syncState(patch = {}) {
@@ -375,7 +432,9 @@ export function createStore(initialSnapshot, options = {}) {
       || state.search !== reconciled.search
       || state.view !== reconciled.view
       || state.selectedTaskId !== reconciled.selectedTaskId
-      || state.selectedSubtaskId !== reconciled.selectedSubtaskId;
+      || state.selectedSubtaskId !== reconciled.selectedSubtaskId
+      || state.taskModalOpen !== reconciled.taskModalOpen
+      || state.subtaskModalOpen !== reconciled.subtaskModalOpen;
 
     state.screen = reconciled.screen;
     state.selectedEpicId = reconciled.selectedEpicId;
@@ -384,10 +443,12 @@ export function createStore(initialSnapshot, options = {}) {
     state.view = reconciled.view;
     state.selectedTaskId = reconciled.selectedTaskId;
     state.selectedSubtaskId = reconciled.selectedSubtaskId;
+    state.taskModalOpen = reconciled.taskModalOpen;
+    state.subtaskModalOpen = reconciled.subtaskModalOpen;
     if (changed) {
       notify();
     }
-    return deriveBoardState(state);
+    return boardStateMemo.get(state);
   }
 
   // Reconcile initial state
@@ -450,7 +511,7 @@ export function createStore(initialSnapshot, options = {}) {
      * @returns {BoardState}
      */
     getBoardState() {
-      return deriveBoardState(state);
+      return boardStateMemo.get(state);
     },
 
     /**
@@ -528,7 +589,22 @@ export function createStore(initialSnapshot, options = {}) {
      * @returns {object|null}
      */
     getSelectedTask() {
-      return deriveBoardState(state).selectedTask;
+      return boardStateMemo.get(state).selectedTask;
     },
+
+    /**
+     * Invalidate the memoized board state. Call after a direct mutation of
+     * `model.store` that didn't go through `setState`/`syncState`/`notify`,
+     * before triggering a rerender, so `getBoardState()` recomputes.
+     */
+    invalidateBoardStateMemo() {
+      boardStateMemo.invalidate();
+    },
+
+    /**
+     * Notify subscribers (and invalidate the memo). Use after a direct
+     * mutation of `model.store` that needs to be reflected in derived state.
+     */
+    notify,
   };
 }

package/src/board/assets/state/url.js

@@ -47,6 +47,9 @@ export function stateToHash(state) {
   if (state.selectedTaskId) {
     params.set("task", state.selectedTaskId);
   }
+  if (state.selectedSubtaskId) {
+    params.set("subtask", state.selectedSubtaskId);
+  }
   if (state.screen === "epics" && state.selectedEpicId) {
     params.set("screen", "epics");
   }
@@ -73,6 +76,7 @@ export function hashToState(hash) {
 
   const epicId = params.get("epic") || null;
   const taskId = params.get("task") || null;
+  const subtaskId = params.get("subtask") || null;
   const screenParam = params.get("screen");
   const search = params.get("search") || "";
   const view = params.get("view") || DEFAULT_VIEW;
@@ -82,9 +86,15 @@ export function hashToState(hash) {
       ? "tasks"
       : "epics";
 
+  // Deep-linking with task=/subtask= must open the corresponding modals so the
+  // booted page actually renders the deep-linked dialog instead of just
+  // selecting a row in the workspace.
   return {
     selectedEpicId: epicId,
     selectedTaskId: taskId,
+    selectedSubtaskId: subtaskId,
+    taskModalOpen: Boolean(taskId),
+    subtaskModalOpen: Boolean(subtaskId),
     search,
     view,
     screen,

package/src/board/assets/state/utils.js

@@ -311,7 +311,8 @@ export function escapeHtml(value) {
     .replaceAll("&", "&")
     .replaceAll("<", "&lt;")
     .replaceAll(">", "&gt;")
-    .replaceAll('"', "&quot;");
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
 }
 
 /**

package/src/board/event-bus.ts

@@ -0,0 +1,72 @@
+/**
+ * Board event bus.
+ *
+ * Per-server-instance pub/sub used to broadcast snapshot deltas to SSE
+ * subscribers (browser tabs). Publishers (board route handlers, future WAL
+ * watcher) call publish; subscribers receive the JSON-serializable payload.
+ */
+
+export interface BoardDeltaEvent {
+  readonly type: "snapshotDelta";
+  readonly id: number;
+  readonly snapshotDelta: Record<string, unknown>;
+}
+
+export type BoardEvent = BoardDeltaEvent;
+
+export type BoardEventListener = (event: BoardEvent) => void;
+
+export interface BoardEventBus {
+  publishSnapshotDelta(snapshotDelta: Record<string, unknown>): BoardDeltaEvent;
+  subscribe(listener: BoardEventListener): () => void;
+  readonly subscriberCount: number;
+  close(): void;
+}
+
+export function createBoardEventBus(): BoardEventBus {
+  const listeners = new Set<BoardEventListener>();
+  let nextId = 1;
+  let closed = false;
+
+  return {
+    publishSnapshotDelta(snapshotDelta: Record<string, unknown>): BoardDeltaEvent {
+      const event: BoardDeltaEvent = {
+        type: "snapshotDelta",
+        id: nextId++,
+        snapshotDelta,
+      };
+
+      if (closed) {
+        return event;
+      }
+
+      // Snapshot to allow listeners to unsubscribe during dispatch.
+      for (const listener of [...listeners]) {
+        try {
+          listener(event);
+        } catch {
+          // Listener errors must not block other subscribers.
+        }
+      }
+
+      return event;
+    },
+    subscribe(listener: BoardEventListener): () => void {
+      if (closed) {
+        return () => {};
+      }
+
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    get subscriberCount(): number {
+      return listeners.size;
+    },
+    close(): void {
+      closed = true;
+      listeners.clear();
+    },
+  };
+}