trekoon 0.4.1 → 0.4.2

package/src/board/assets/components/Workspace.js

@@ -166,7 +166,7 @@ function renderWorkspaceHeader(props) {
 // ---------------------------------------------------------------------------
 
 function renderKanbanColumns(props) {
-  const { visibleTasks, selectedTaskId, isMutating, taskStatusFilter } = props;
+  const { visibleTasks, selectedTaskId, isMutating, taskStatusFilter, dragFeedback } = props;
   const filter = taskStatusFilter || { ...DEFAULT_STATUS_FILTER };
 
   const columnsMarkup = STATUS_ORDER
@@ -178,6 +178,12 @@ function renderKanbanColumns(props) {
       ? renderEmptyState(`No ${columnTitle.toLowerCase()} work`, "Adjust search or switch epics to inspect more tasks.")
       : columnTasks.map((task) => renderTaskCard({ task, selected: selectedTaskId === task.id, isMutating })).join("");
 
+    // Re-apply drag-feedback class from store so a rerender during drag does
+    // not silently wipe the visual feedback that was set by handleDragover.
+    const feedbackClass = dragFeedback?.targetStatus === status
+      ? (dragFeedback.kind === "valid" ? " board-drop-valid" : " board-drop-invalid")
+      : "";
+
     return `
       <section class="board-column board-column--dense ${secondaryPanelClasses("flex min-h-[20rem] min-w-0 flex-col p-3")}" aria-labelledby="column-${status}">
         <header class="board-column__header flex items-start justify-between gap-3 border-b border-[var(--board-border)] pb-3">
@@ -190,7 +196,7 @@ function renderKanbanColumns(props) {
           </div>
           ${columnTasks.length > 0 ? `<span class="board-column__count text-xs font-medium text-[var(--board-text-soft)]">${columnTasks.length === 1 ? "1 task" : `${columnTasks.length} tasks`}</span>` : ""}
         </header>
-        <div class="board-column__tasks mt-3 grid min-h-0 flex-1 content-start gap-2.5 overflow-auto pr-1 overscroll-contain" id="column-${status}" data-drop-status="${escapeHtml(status)}">${content}</div>
+        <div class="board-column__tasks mt-3 grid min-h-0 flex-1 content-start gap-2.5 overflow-auto pr-1 overscroll-contain${feedbackClass}" id="column-${status}" data-drop-status="${escapeHtml(status)}">${content}</div>
       </section>
     `;
   }).join("");
@@ -292,7 +298,7 @@ function render(props) {
   });
 
   const contentMarkup = store.view === "kanban"
-    ? renderKanbanColumns({ visibleTasks, selectedTaskId, isMutating: store.isMutating, taskStatusFilter: store.taskStatusFilter })
+    ? renderKanbanColumns({ visibleTasks, selectedTaskId, isMutating: store.isMutating, taskStatusFilter: store.taskStatusFilter, dragFeedback: store.dragFeedback ?? null })
     : renderListView({ visibleTasks, selectedTaskId });
 
   return `

package/src/board/assets/components/helpers.js

@@ -255,6 +255,10 @@ export function shouldUseTaskModal(boardState, store) {
   return Boolean(boardState?.taskModalOpen && boardState?.selectedTask);
 }
 
+export function shouldUseSubtaskModal(boardState) {
+  return Boolean(boardState?.subtaskModalOpen && boardState?.selectedSubtask);
+}
+
 export function lookupNode(snapshot, id) {
   return snapshot.tasks.find((task) => task.id === id)
     ?? snapshot.subtasks.find((subtask) => subtask.id === id)

package/src/board/assets/runtime/delegation.js

@@ -310,6 +310,8 @@ export function createDelegation(rootElement, actions) {
     for (const el of rootElement.querySelectorAll(".board-drop-valid, .board-drop-invalid")) {
       el.classList.remove("board-drop-valid", "board-drop-invalid");
     }
+    // Clear feedback in store so rerenders do not re-apply stale classes.
+    actions.setDragFeedback?.(null);
   }
 
   function handleDragstart(event) {
@@ -336,11 +338,15 @@ export function createDelegation(rootElement, actions) {
     const targetStatus = column.dataset.dropStatus;
     if (draggedTaskStatus && isValidTransition(draggedTaskStatus, targetStatus)) {
       event.preventDefault();
+      // Fast path: apply directly to DOM for immediate visual feedback.
       column.classList.add("board-drop-valid");
       column.classList.remove("board-drop-invalid");
+      // Also persist in store so a rerender during drag restores the class.
+      actions.setDragFeedback?.({ targetStatus, kind: "valid" });
     } else if (draggedTaskStatus && targetStatus !== draggedTaskStatus) {
       column.classList.add("board-drop-invalid");
       column.classList.remove("board-drop-valid");
+      actions.setDragFeedback?.({ targetStatus, kind: "invalid" });
     }
   }
 
@@ -348,6 +354,8 @@ export function createDelegation(rootElement, actions) {
     const column = event.target.closest("[data-drop-status]");
     if (column && !column.contains(event.relatedTarget)) {
       column.classList.remove("board-drop-valid", "board-drop-invalid");
+      // Clear store feedback when leaving the column.
+      actions.setDragFeedback?.(null);
     }
   }
 

package/src/board/assets/runtime/focus-trap.js

@@ -0,0 +1,48 @@
+/**
+ * Lazy overlay focus-trap controller.
+ *
+ * Attaches the document-level keydown/focusin listeners only while an overlay
+ * is actually open, and detaches them on close. Without this, plain Tab outside
+ * any overlay can be intercepted by a stale handler in the microtask window
+ * between overlay close and rerender.
+ *
+ * @param {{
+ *   doc?: Document,
+ *   onTabKey: (event: KeyboardEvent) => void,
+ *   onFocusIn: (event: FocusEvent) => void,
+ * }} options
+ */
+export function createOverlayFocusTrap(options) {
+  const doc = options.doc ?? (typeof document !== "undefined" ? document : null);
+  if (!doc) {
+    return {
+      attach() {},
+      detach() {},
+      isAttached() { return false; },
+    };
+  }
+
+  const onKeyDown = options.onTabKey;
+  const onFocusIn = options.onFocusIn;
+  let attached = false;
+
+  function attach() {
+    if (attached) return;
+    doc.addEventListener("keydown", onKeyDown, true);
+    doc.addEventListener("focusin", onFocusIn, true);
+    attached = true;
+  }
+
+  function detach() {
+    if (!attached) return;
+    doc.removeEventListener("keydown", onKeyDown, true);
+    doc.removeEventListener("focusin", onFocusIn, true);
+    attached = false;
+  }
+
+  return {
+    attach,
+    detach,
+    isAttached() { return attached; },
+  };
+}

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

@@ -142,6 +142,13 @@ export function createBoardActions(options) {
     searchFocusKeys,
   } = options;
   const { store, persist, getBoardState, getTaskById, syncState } = model;
+  // Direct mutations of `store.*` (filter toggles, notice changes, drag
+  // feedback) bypass setState/syncState, so `getBoardState()`'s memo would
+  // otherwise return a stale reference until the next syncState/notify.
+  // Route these through invalidateBoardStateMemo() before rerender.
+  const invalidateMemo = typeof model.invalidateBoardStateMemo === "function"
+    ? () => model.invalidateBoardStateMemo()
+    : () => {};
 
   const transition = (patch = {}, options = {}) => {
     const { persistState = true, rerenderBoard = true } = options;
@@ -348,13 +355,21 @@ export function createBoardActions(options) {
       });
     },
     closeTask() {
-      transition({ selectedTaskId: null, selectedSubtaskId: null, taskModalOpen: false });
+      transition({
+        selectedTaskId: null,
+        selectedSubtaskId: null,
+        taskModalOpen: false,
+        subtaskModalOpen: false,
+      });
     },
     openSubtask(subtaskId) {
-      transition({ selectedSubtaskId: subtaskId || null }, { persistState: false });
+      transition(
+        { selectedSubtaskId: subtaskId || null, subtaskModalOpen: Boolean(subtaskId) },
+        { persistState: false },
+      );
     },
     closeSubtask() {
-      transition({ selectedSubtaskId: null }, { persistState: false });
+      transition({ selectedSubtaskId: null, subtaskModalOpen: false }, { persistState: false });
     },
     submitTaskForm(taskId, formData) {
       const updates = {
@@ -413,12 +428,31 @@ export function createBoardActions(options) {
       const task = getTaskById(taskId);
       return task?.status ?? null;
     },
+    /**
+     * Record the current drag-over feedback in store state so it survives a
+     * rerender triggered by an unrelated event (e.g. a server SSE push).
+     * Pass null to clear feedback (dragend / drop / dragleave).
+     *
+     * @param {{ targetStatus: string, kind: 'valid'|'invalid' }|null} feedback
+     */
+    setDragFeedback(feedback) {
+      // Reference equality on freshly-allocated `{ targetStatus, kind }` always
+      // fails, so dragover would rerender on every move. Compare by primitive
+      // key so repeats over the same column become a no-op.
+      const prev = store.dragFeedback;
+      const prevKey = prev ? `${prev.targetStatus}|${prev.kind}` : null;
+      const nextKey = feedback ? `${feedback.targetStatus}|${feedback.kind}` : null;
+      if (prevKey === nextKey) return;
+      store.dragFeedback = feedback;
+      rerender();
+    },
     dropTaskStatus(taskId, nextStatus) {
       const task = getTaskById(taskId);
       if (!task || !nextStatus || task.status === nextStatus) {
         return;
       }
-      transition({ selectedTaskId: taskId, taskModalOpen: false }, { rerenderBoard: false });
+      // Drag/drop is a status change only; do not mutate selection or modal state,
+      // otherwise dropping a card while another task modal is open hijacks it.
       api.patchTask(taskId, { status: nextStatus }, (snapshot) => updateTaskInSnapshot(snapshot, taskId, { status: nextStatus }, normalizeSnapshot));
     },
     changeEpicStatus(epicId, newStatus) {
@@ -438,22 +472,26 @@ export function createBoardActions(options) {
     toggleEpicStatusFilter(status) {
       const current = store.epicStatusFilter || { ...DEFAULT_STATUS_FILTER };
       store.epicStatusFilter = { ...current, [status]: !current[status] };
+      invalidateMemo();
       persist();
       rerender();
     },
     toggleTaskStatusFilter(status) {
       const current = store.taskStatusFilter || { ...DEFAULT_STATUS_FILTER };
       store.taskStatusFilter = { ...current, [status]: !current[status] };
+      invalidateMemo();
       persist();
       rerender();
     },
     resetEpicFilter() {
       store.epicStatusFilter = { ...DEFAULT_STATUS_FILTER };
+      invalidateMemo();
       persist();
       rerender();
     },
     resetTaskFilter() {
       store.taskStatusFilter = { ...DEFAULT_STATUS_FILTER };
+      invalidateMemo();
       persist();
       rerender();
     },

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
+      }
+    },
+  };
+}