trekoon 0.4.1 → 0.4.3

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) {
@@ -95,10 +222,9 @@ function createTimeoutError(method, path, timeoutMs) {
  * }}
  */
 export function createMutationQueue(model, rerender) {
-  /** @type {Array<{ optimistic?: function, request: function, onSuccess?: function, onError?: function, successMessage?: string }>} */
+  /** @type {Array<{ mutationId: string, optimistic?: function, request: function, onSuccess?: function, onError?: function, successMessage?: string }>} */
   const queue = [];
   let processing = false;
-  let nextMutationId = 1;
   /** @type {Array<() => void>} */
   let flushResolvers = [];
 
@@ -119,14 +245,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) {
+      if (model.store.notice?.retryMutationId !== mutation.mutationId) {
         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 = model.store.snapshot;
+          const optimisticSnapshot = mutation.optimistic(cloneSnapshot(previousSnapshot));
+          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 +285,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 = {
@@ -155,7 +297,7 @@ export function createMutationQueue(model, rerender) {
           title: "Action failed",
           message,
           retryLabel: "Retry",
-          retryMutationId: mutation.id,
+          retryMutationId: mutation.mutationId,
         };
 
         if (typeof mutation.onError === "function") {
@@ -166,14 +308,19 @@ export function createMutationQueue(model, rerender) {
 
     processing = false;
     model.store.isMutating = false;
+    if (typeof model.invalidateBoardStateMemo === "function") {
+      model.invalidateBoardStateMemo();
+    }
     rerender();
     resolveFlushes();
   }
 
   return {
     enqueue(mutation) {
-      queue.push({ ...mutation, id: nextMutationId });
-      nextMutationId += 1;
+      queue.push({
+        ...mutation,
+        mutationId: mutation.mutationId ?? crypto.randomUUID(),
+      });
       processNext();
     },
 
@@ -204,20 +351,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 +556,137 @@ 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 for API parity; EventSource uses the same-origin HttpOnly cookie.
+ * @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 {
+    rerender,
+    EventSourceCtor = typeof EventSource !== "undefined" ? EventSource : null,
+    path = "/api/snapshot/stream",
+  } = options ?? {};
+
+  if (!EventSourceCtor) {
+    return { dispose: () => {}, eventSource: null };
+  }
+
+  let disposed = false;
+  let consecutiveErrors = 0;
+  const eventSource = new EventSourceCtor(path);
+
+  const clearLiveUpdateNotice = () => {
+    if (model.store?.notice?.code === "live_updates_disconnected") {
+      model.store.notice = null;
+    }
+  };
+
+  const markLiveUpdateSuccess = () => {
+    consecutiveErrors = 0;
+    clearLiveUpdateNotice();
+  };
+
+  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);
+    markLiveUpdateSuccess();
+    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);
+      markLiveUpdateSuccess();
+      if (typeof rerender === "function") rerender();
+    }
+  };
+
+  function dispose() {
+    if (disposed) return;
+    disposed = true;
+    try {
+      eventSource.close();
+    } catch {
+      // best-effort
+    }
+  }
+
+  const handleError = () => {
+    if (disposed) return;
+    consecutiveErrors += 1;
+    if (model.store && typeof model.store === "object") {
+      const existing = model.store.notice;
+      const disabled = consecutiveErrors >= 5;
+      const nextCode = disabled ? "live_updates_disabled" : "live_updates_disconnected";
+      if (!existing || existing.code !== nextCode) {
+        model.store.notice = {
+          type: "warning",
+          code: nextCode,
+          title: disabled ? "Live updates disabled" : "Live updates disconnected",
+          message: disabled
+            ? "Refresh the board to resume live updates from other sessions."
+            : "Reconnecting to the server. Changes from other sessions may be delayed.",
+        };
+        if (typeof rerender === "function") rerender();
+      }
+      if (disabled) {
+        dispose();
+      }
+    }
+  };
+
+  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,
+  };
+}

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();
@@ -225,6 +235,7 @@ function selectSearchScope(state) {
  * @property {string|null} selectedSubtaskId
  * @property {object|null} selectedSubtask
  * @property {boolean} taskModalOpen
+ * @property {boolean} subtaskModalOpen
  * @property {string} search
  * @property {string} searchQuery
  * @property {object} searchScope
@@ -232,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
@@ -266,6 +309,7 @@ function deriveBoardState(state) {
   const selectedSubtask = selectedTaskId ? selectSelectedSubtask(stateWithTaskSelection) : null;
 
   const taskModalOpen = state.taskModalOpen === true;
+  const subtaskModalOpen = state.subtaskModalOpen === true && selectedSubtask !== null;
 
   return {
     screen,
@@ -276,6 +320,7 @@ function deriveBoardState(state) {
     selectedSubtaskId: selectedSubtask?.id ?? null,
     selectedSubtask,
     taskModalOpen,
+    subtaskModalOpen,
     search: stateWithScreen.search,
     searchQuery: stateWithScreen.searchQuery,
     searchScope: selectSearchScope(stateWithScreen),
@@ -294,6 +339,7 @@ function reconcileBoardState(state) {
     selectedTaskId: derived.selectedTaskId,
     selectedSubtaskId: derived.selectedSubtaskId,
     taskModalOpen: derived.taskModalOpen,
+    subtaskModalOpen: derived.subtaskModalOpen,
   };
 }
 
@@ -337,11 +383,13 @@ export function createStore(initialSnapshot, options = {}) {
     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),
@@ -350,7 +398,13 @@ export function createStore(initialSnapshot, options = {}) {
   /** @type {Set<(state: object) => void>} */
   const listeners = new Set();
 
+  const boardStateMemo = createBoardStateMemo(deriveBoardState);
+
+  // Direct `model.store` mutations must manually invalidate this memo before
+  // rerendering. Current direct-mutation fields: snapshot, notice, isMutating,
+  // dragFeedback.
   function notify() {
+    boardStateMemo.invalidate();
     for (const listener of listeners) {
       listener(state);
     }
@@ -361,12 +415,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 = {}) {
@@ -382,7 +436,8 @@ export function createStore(initialSnapshot, options = {}) {
       || state.view !== reconciled.view
       || state.selectedTaskId !== reconciled.selectedTaskId
       || state.selectedSubtaskId !== reconciled.selectedSubtaskId
-      || state.taskModalOpen !== reconciled.taskModalOpen;
+      || state.taskModalOpen !== reconciled.taskModalOpen
+      || state.subtaskModalOpen !== reconciled.subtaskModalOpen;
 
     state.screen = reconciled.screen;
     state.selectedEpicId = reconciled.selectedEpicId;
@@ -392,10 +447,11 @@ export function createStore(initialSnapshot, options = {}) {
     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
@@ -458,7 +514,7 @@ export function createStore(initialSnapshot, options = {}) {
      * @returns {BoardState}
      */
     getBoardState() {
-      return deriveBoardState(state);
+      return boardStateMemo.get(state);
     },
 
     /**
@@ -536,7 +592,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;");
 }
 
 /**