trekoon 0.3.6 → 0.3.8

package/src/board/assets/app.js

@@ -13,7 +13,6 @@ import { createConfirmDialog } from "./components/ConfirmDialog.js";
 import { createEpicsOverview } from "./components/EpicsOverview.js";
 import { panelClasses, renderIcon, sectionLabelClasses, escapeHtml } from "./components/helpers.js";
 
-const SESSION_TOKEN_STORAGE_KEY = "trekoon-board-session-token";
 const SEARCH_FOCUS_KEYS = new Set(["/", "s"]);
 const FOCUSABLE_SELECTOR = [
   "a[href]",
@@ -33,30 +32,15 @@ const FOCUSABLE_SELECTOR = [
 // Session token management
 // ---------------------------------------------------------------------------
 
-function readSessionTokenFromStorage() {
-  try {
-    return (sessionStorage.getItem(SESSION_TOKEN_STORAGE_KEY) || "").trim();
-  } catch {
-    return "";
-  }
-}
-
-function persistSessionToken(token) {
-  try {
-    sessionStorage.setItem(SESSION_TOKEN_STORAGE_KEY, token);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 function resolveRuntimeSession() {
   const url = new URL(window.location.href);
   const queryToken = (url.searchParams.get("token") || "").trim();
   if (queryToken.length > 0) {
-    return { token: queryToken, shouldScrubAddressBar: persistSessionToken(queryToken) };
+    return { token: queryToken, shouldScrubAddressBar: true };
   }
-  return { token: readSessionTokenFromStorage(), shouldScrubAddressBar: false };
+  const bootstrap = readJsonScript("trekoon-board-bootstrap") ?? {};
+  const bootstrapToken = typeof bootstrap?.token === "string" ? bootstrap.token.trim() : "";
+  return { token: bootstrapToken, shouldScrubAddressBar: false };
 }
 
 function scrubTokenFromAddressBar() {
@@ -149,11 +133,10 @@ export async function bootLegacyBoard(options = {}) {
     if (runtimeSession.shouldScrubAddressBar) scrubTokenFromAddressBar();
 
     // Fetch snapshot
-    let snapshotPayload = readJsonScript("trekoon-board-snapshot") ?? {};
-    if (runtimeSession.token.length > 0) {
-      const headers = new Headers();
-      headers.set("authorization", `Bearer ${runtimeSession.token}`);
-      const response = await fetch("/api/snapshot", { headers });
+    const bootstrap = readJsonScript("trekoon-board-bootstrap") ?? {};
+    let snapshotPayload = bootstrap?.snapshot ?? readJsonScript("trekoon-board-snapshot") ?? {};
+    if ((!snapshotPayload || typeof snapshotPayload !== "object") && runtimeSession.token.length > 0) {
+      const response = await fetch("/api/snapshot");
       const payload = await response.json();
       if (!payload?.ok) throw new Error(payload?.error?.message || "Board request failed");
       snapshotPayload = payload?.data?.snapshot ?? {};
@@ -422,6 +405,17 @@ export async function bootLegacyBoard(options = {}) {
       notice.update({
         notice: store.notice,
         onDismiss() { store.notice = null; rerender(); },
+        onRetry() {
+          const didRetry = api.retryLastFailedMutation();
+          if (!didRetry) {
+            store.notice = {
+              type: "error",
+              title: "Retry unavailable",
+              message: "The failed action is no longer available. Repeat the change from the board.",
+            };
+          }
+          rerender();
+        },
       });
 
       if (showTasks) {

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

@@ -26,11 +26,11 @@ export function createNotice() {
     },
 
     /**
-     * @param {{ notice: { type: string, message: string, title?: string } | null, onDismiss?: () => void }} props
+     * @param {{ notice: { type: string, message: string, title?: string, retryLabel?: string } | null, onDismiss?: () => void, onRetry?: () => void }} props
      */
     update(props) {
       if (!container) return;
-      const { notice, onDismiss } = props;
+      const { notice, onDismiss, onRetry } = props;
 
       if (!notice) {
         if (lastNotice) {
@@ -42,7 +42,12 @@ export function createNotice() {
       }
 
       // Same notice — skip
-      if (lastNotice && lastNotice.type === notice.type && lastNotice.message === notice.message) {
+      if (
+        lastNotice
+        && lastNotice.type === notice.type
+        && lastNotice.message === notice.message
+        && lastNotice.retryMutationId === notice.retryMutationId
+      ) {
         return;
       }
 
@@ -61,14 +66,23 @@ export function createNotice() {
             <div class="board-toast__content">
               <p class="board-toast__title" id="board-notice-title">${escapeHtml(noticeTitle)}</p>
               <p class="board-toast__message">${escapeHtml(notice.message)}</p>
+              ${typeof notice.retryLabel === "string" && notice.retryLabel.trim().length > 0
+    ? `<button type="button" class="mt-3 inline-flex items-center gap-2 rounded-lg border border-[var(--board-border-strong)] bg-[var(--board-surface-2)] px-3 py-2 text-sm font-medium text-[var(--board-text)] transition hover:border-[var(--board-accent)] hover:text-[var(--board-accent)]" data-board-notice-retry>${escapeHtml(notice.retryLabel.trim())}</button>`
+    : ""}
             </div>
           </section>
         </div>
       `;
-      lastNotice = { type: notice.type, message: notice.message };
+      lastNotice = { type: notice.type, message: notice.message, retryMutationId: notice.retryMutationId };
 
       // Auto-dismiss after 4 s
       clearTimer();
+      const retryButton = typeof container.querySelector === "function"
+        ? container.querySelector("[data-board-notice-retry]")
+        : null;
+      if (retryButton && typeof retryButton.addEventListener === "function" && typeof onRetry === "function") {
+        retryButton.addEventListener("click", onRetry);
+      }
       if (typeof onDismiss === "function") {
         dismissTimer = setTimeout(() => {
           onDismiss();

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

@@ -75,14 +75,14 @@ export function cascadeEpicStatusInSnapshot(snapshot, epicId, status, normalizeS
   return normalizeSnapshot(nextSnapshot);
 }
 
-export function addDependencyInSnapshot(snapshot, sourceId, dependsOnId, normalizeSnapshot) {
+export function addDependencyInSnapshot(snapshot, sourceId, dependsOnId, normalizeSnapshot, optimisticId = null) {
   const nextSnapshot = cloneSnapshot(snapshot);
   const duplicate = normalizeArray(nextSnapshot.dependencies).some(
     (dependency) => dependency.sourceId === sourceId && dependency.dependsOnId === dependsOnId,
   );
   if (!duplicate) {
     normalizeArray(nextSnapshot.dependencies).push({
-      id: crypto.randomUUID(),
+      id: optimisticId ?? crypto.randomUUID(),
       sourceId,
       sourceKind: nextSnapshot.subtasks.some((subtask) => subtask.id === sourceId) ? "subtask" : "task",
       dependsOnId,
@@ -102,10 +102,10 @@ export function removeDependencyInSnapshot(snapshot, sourceId, dependsOnId, norm
   return normalizeSnapshot(nextSnapshot);
 }
 
-export function createSubtaskInSnapshot(snapshot, input, normalizeSnapshot) {
+export function createSubtaskInSnapshot(snapshot, input, normalizeSnapshot, optimisticId = null) {
   const nextSnapshot = cloneSnapshot(snapshot);
   normalizeArray(nextSnapshot.subtasks).push({
-    id: crypto.randomUUID(),
+    id: optimisticId ?? crypto.randomUUID(),
     taskId: input.taskId,
     title: input.title,
     description: input.description ?? "",
@@ -382,7 +382,7 @@ export function createBoardActions(options) {
         return;
       }
 
-      api.createSubtask(input, (snapshot) => createSubtaskInSnapshot(snapshot, input, normalizeSnapshot));
+      api.createSubtask(input, (snapshot, optimisticId) => createSubtaskInSnapshot(snapshot, input, normalizeSnapshot, optimisticId));
     },
     deleteSubtask(subtaskId) {
       if (!subtaskId) {
@@ -399,7 +399,7 @@ export function createBoardActions(options) {
         return;
       }
 
-      api.addDependency(sourceId, dependsOnId, (snapshot) => addDependencyInSnapshot(snapshot, sourceId, dependsOnId, normalizeSnapshot));
+      api.addDependency(sourceId, dependsOnId, (snapshot, optimisticId) => addDependencyInSnapshot(snapshot, sourceId, dependsOnId, normalizeSnapshot, optimisticId));
     },
     removeDependency(sourceId, dependsOnId) {
       api.removeDependency(sourceId, dependsOnId, (snapshot) => removeDependencyInSnapshot(snapshot, sourceId, dependsOnId, normalizeSnapshot));

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

@@ -47,6 +47,40 @@ function buildRequestError(method, path, response, payload) {
   return error;
 }
 
+const DEFAULT_REQUEST_TIMEOUT_MS = 10000;
+
+function createClientRequestId() {
+  return crypto.randomUUID();
+}
+
+function createOptimisticId(prefix, clientRequestId) {
+  return `optimistic:${prefix}:${clientRequestId}`;
+}
+
+function augmentSnapshotDeltaWithOptimisticDelete(snapshotDelta, key, optimisticId) {
+  if (!snapshotDelta || typeof snapshotDelta !== "object" || typeof optimisticId !== "string" || optimisticId.length === 0) {
+    return snapshotDelta;
+  }
+
+  const deletedKey = key === "subtasks" ? "deletedSubtaskIds" : "deletedDependencyIds";
+  const deletedIds = Array.isArray(snapshotDelta[deletedKey]) ? snapshotDelta[deletedKey] : [];
+  if (deletedIds.includes(optimisticId)) {
+    return snapshotDelta;
+  }
+
+  return {
+    ...snapshotDelta,
+    [deletedKey]: [...deletedIds, optimisticId],
+  };
+}
+
+function createTimeoutError(method, path, timeoutMs) {
+  const error = new Error(`${method} ${path} timed out after ${timeoutMs}ms. Retry your change.`);
+  error.code = "request_timeout";
+  error.timeoutMs = timeoutMs;
+  return error;
+}
+
 /**
  * Create a serial mutation queue.
  *
@@ -64,6 +98,7 @@ export function createMutationQueue(model, rerender) {
   /** @type {Array<{ optimistic?: function, request: function, onSuccess?: function, onError?: function, successMessage?: string }>} */
   const queue = [];
   let processing = false;
+  let nextMutationId = 1;
   /** @type {Array<() => void>} */
   let flushResolvers = [];
 
@@ -85,19 +120,22 @@ export function createMutationQueue(model, rerender) {
     while (queue.length > 0) {
       const mutation = queue.shift();
       const previousSnapshot = cloneSnapshot(model.store.snapshot);
-      model.store.notice = null;
-
-      // Apply optimistic update
-      if (typeof mutation.optimistic === "function") {
-        model.store.snapshot = mutation.optimistic(cloneSnapshot(model.store.snapshot));
-        rerender();
+      if (model.store.notice?.retryMutationId !== mutation.id) {
+        model.store.notice = null;
       }
 
       try {
+        if (typeof mutation.optimistic === "function") {
+          model.store.snapshot = mutation.optimistic(cloneSnapshot(model.store.snapshot));
+          rerender();
+        }
+
         const data = await mutation.request();
 
         if (data?.snapshot) {
           model.replaceSnapshot(data.snapshot);
+        } else if (data?.snapshotDelta) {
+          model.applySnapshotDelta(data.snapshotDelta);
         }
 
         if (typeof mutation.onSuccess === "function") {
@@ -112,14 +150,17 @@ export function createMutationQueue(model, rerender) {
         model.replaceSnapshot(previousSnapshot);
 
         const message = error instanceof Error ? error.message : String(error);
-        model.store.notice = { type: "error", message };
+        model.store.notice = {
+          type: "error",
+          title: "Action failed",
+          message,
+          retryLabel: "Retry",
+          retryMutationId: mutation.id,
+        };
 
         if (typeof mutation.onError === "function") {
           mutation.onError(error);
         }
-
-        // Clear remaining queue on error to prevent cascading failures
-        queue.length = 0;
       }
     }
 
@@ -131,7 +172,8 @@ export function createMutationQueue(model, rerender) {
 
   return {
     enqueue(mutation) {
-      queue.push(mutation);
+      queue.push({ ...mutation, id: nextMutationId });
+      nextMutationId += 1;
       processNext();
     },
 
@@ -158,11 +200,35 @@ export function createMutationQueue(model, rerender) {
  * @returns {object} API methods: patchTask, patchSubtask, createSubtask, deleteSubtask, addDependency, removeDependency
  */
 export function createApi(model, options) {
-  const { sessionToken, rerender } = options;
+  const { sessionToken, rerender, requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS } = options;
+  let lastFailedMutation = null;
+
+  function enqueueMutation(definition) {
+    queue.enqueue({
+      ...definition,
+      onSuccess(data) {
+        if (lastFailedMutation?.request === definition.request) {
+          lastFailedMutation = null;
+        }
+        if (typeof definition.onSuccess === "function") {
+          definition.onSuccess(data);
+        }
+      },
+      onError(error) {
+        lastFailedMutation = definition;
+        if (typeof definition.onError === "function") {
+          definition.onError(error);
+        }
+      },
+    });
+  }
 
   async function request(path, requestOptions = {}) {
     const method = typeof requestOptions.method === "string" ? requestOptions.method.toUpperCase() : "GET";
     const headers = new Headers(requestOptions.headers || {});
+    const timeoutMs = Number.isFinite(requestOptions.timeoutMs) && requestOptions.timeoutMs > 0
+      ? requestOptions.timeoutMs
+      : requestTimeoutMs;
     if (sessionToken.length > 0) {
       headers.set("authorization", `Bearer ${sessionToken}`);
     }
@@ -171,14 +237,26 @@ export function createApi(model, options) {
     }
 
     let response;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => {
+      controller.abort(createTimeoutError(method, path, timeoutMs));
+    }, timeoutMs);
+
     try {
-      response = await fetch(path, { ...requestOptions, headers });
+      response = await fetch(path, { ...requestOptions, headers, signal: controller.signal });
     } catch (error) {
+      if (controller.signal.aborted) {
+        throw controller.signal.reason instanceof Error
+          ? controller.signal.reason
+          : createTimeoutError(method, path, timeoutMs);
+      }
       const message = error instanceof Error ? error.message : String(error);
       const requestError = new Error(`${method} ${path} failed before a response was received: ${message}`);
       requestError.code = "network_error";
       requestError.cause = error;
       throw requestError;
+    } finally {
+      clearTimeout(timeoutId);
     }
 
     const payload = await readJsonPayload(response);
@@ -192,8 +270,16 @@ export function createApi(model, options) {
   const queue = createMutationQueue(model, rerender);
 
   return {
+    retryLastFailedMutation() {
+      if (!lastFailedMutation) {
+        return false;
+      }
+      enqueueMutation(lastFailedMutation);
+      return true;
+    },
+
     patchEpic(epicId, updates, optimistic) {
-      queue.enqueue({
+      enqueueMutation({
         optimistic,
         successMessage: "Epic saved.",
         request: () => request(`/api/epics/${encodeURIComponent(epicId)}`, {
@@ -204,7 +290,7 @@ export function createApi(model, options) {
     },
 
     patchTask(taskId, updates, optimistic) {
-      queue.enqueue({
+      enqueueMutation({
         optimistic,
         successMessage: "Task saved.",
         request: () => request(`/api/tasks/${encodeURIComponent(taskId)}`, {
@@ -215,7 +301,7 @@ export function createApi(model, options) {
     },
 
     patchSubtask(subtaskId, updates, optimistic) {
-      queue.enqueue({
+      enqueueMutation({
         optimistic,
         successMessage: "Subtask saved.",
         request: () => request(`/api/subtasks/${encodeURIComponent(subtaskId)}`, {
@@ -226,7 +312,7 @@ export function createApi(model, options) {
     },
 
     cascadeEpicStatus(epicId, status, optimistic) {
-      queue.enqueue({
+      enqueueMutation({
         optimistic,
         successMessage: "Epic cascade status updated.",
         request: () => request(`/api/epics/${encodeURIComponent(epicId)}/cascade`, {
@@ -237,43 +323,81 @@ export function createApi(model, options) {
     },
 
     createSubtask(input, optimistic) {
-      queue.enqueue({
-        optimistic,
+      const clientRequestId = createClientRequestId();
+      const optimisticId = createOptimisticId("subtask", clientRequestId);
+      enqueueMutation({
+        optimistic: typeof optimistic === "function"
+          ? (snapshot) => optimistic(snapshot, optimisticId)
+          : optimistic,
         successMessage: "Subtask added.",
-        request: () => request("/api/subtasks", {
-          method: "POST",
-          body: JSON.stringify(input),
-        }),
+        request: async () => {
+          const data = await request("/api/subtasks", {
+            method: "POST",
+            headers: {
+              "x-trekoon-idempotency-key": clientRequestId,
+            },
+            body: JSON.stringify({ ...input, clientRequestId }),
+          });
+          return data?.snapshotDelta
+            ? {
+              ...data,
+              snapshotDelta: augmentSnapshotDeltaWithOptimisticDelete(data.snapshotDelta, "subtasks", optimisticId),
+            }
+            : data;
+        },
       });
     },
 
     deleteSubtask(subtaskId, optimistic) {
-      queue.enqueue({
+      const clientRequestId = createClientRequestId();
+      enqueueMutation({
         optimistic,
         successMessage: "Subtask removed.",
         request: () => request(`/api/subtasks/${encodeURIComponent(subtaskId)}`, {
           method: "DELETE",
+          headers: {
+            "x-trekoon-idempotency-key": clientRequestId,
+          },
         }),
       });
     },
 
     addDependency(sourceId, dependsOnId, optimistic) {
-      queue.enqueue({
-        optimistic,
+      const clientRequestId = createClientRequestId();
+      const optimisticId = createOptimisticId("dependency", clientRequestId);
+      enqueueMutation({
+        optimistic: typeof optimistic === "function"
+          ? (snapshot) => optimistic(snapshot, optimisticId)
+          : optimistic,
         successMessage: "Dependency added.",
-        request: () => request("/api/dependencies", {
-          method: "POST",
-          body: JSON.stringify({ sourceId, dependsOnId }),
-        }),
+        request: async () => {
+          const data = await request("/api/dependencies", {
+            method: "POST",
+            headers: {
+              "x-trekoon-idempotency-key": clientRequestId,
+            },
+            body: JSON.stringify({ sourceId, dependsOnId, clientRequestId }),
+          });
+          return data?.snapshotDelta
+            ? {
+              ...data,
+              snapshotDelta: augmentSnapshotDeltaWithOptimisticDelete(data.snapshotDelta, "dependencies", optimisticId),
+            }
+            : data;
+        },
       });
     },
 
     removeDependency(sourceId, dependsOnId, optimistic) {
-      queue.enqueue({
+      const clientRequestId = createClientRequestId();
+      enqueueMutation({
         optimistic,
         successMessage: "Dependency removed.",
         request: () => request(`/api/dependencies?sourceId=${encodeURIComponent(sourceId)}&dependsOnId=${encodeURIComponent(dependsOnId)}`, {
           method: "DELETE",
+          headers: {
+            "x-trekoon-idempotency-key": clientRequestId,
+          },
         }),
       });
     },

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

@@ -1,4 +1,4 @@
-import { normalizeSnapshot, VIEW_MODES } from "./utils.js";
+import { applySnapshotDelta, normalizeSnapshot, VIEW_MODES } from "./utils.js";
 
 export const THEME_STORAGE_KEY = "trekoon-board-theme";
 export const STATE_STORAGE_KEY = "trekoon-board-state";
@@ -23,6 +23,10 @@ function readStatusFilter(raw) {
 
 export function readStoredState() {
   try {
+    if (typeof localStorage?.getItem !== "function") {
+      return {};
+    }
+
     return JSON.parse(localStorage.getItem(STATE_STORAGE_KEY) || "{}");
   } catch {
     return {};
@@ -30,17 +34,38 @@ export function readStoredState() {
 }
 
 export function writeStoredState(nextState) {
-  localStorage.setItem(STATE_STORAGE_KEY, JSON.stringify(nextState));
+  try {
+    if (typeof localStorage?.setItem !== "function") {
+      return false;
+    }
+
+    localStorage.setItem(STATE_STORAGE_KEY, JSON.stringify(nextState));
+    return true;
+  } catch {
+    return false;
+  }
 }
 
 export function readThemePreference() {
-  const storedTheme = localStorage.getItem(THEME_STORAGE_KEY);
-  return storedTheme === "light" || storedTheme === "dark" ? storedTheme : "dark";
+  try {
+    if (typeof localStorage?.getItem !== "function") {
+      return "dark";
+    }
+
+    const storedTheme = localStorage.getItem(THEME_STORAGE_KEY);
+    return storedTheme === "light" || storedTheme === "dark" ? storedTheme : "dark";
+  } catch {
+    return "dark";
+  }
 }
 
 export function applyTheme(theme) {
   document.documentElement.dataset.theme = theme;
-  localStorage.setItem(THEME_STORAGE_KEY, theme);
+  try {
+    localStorage?.setItem?.(THEME_STORAGE_KEY, theme);
+  } catch {
+    // Ignore storage failures so board rendering remains usable.
+  }
 
   const themeColor = theme === "light" ? "#f4f6fb" : "#0b0d12";
   const themeColorMeta = document.querySelector('meta[name="theme-color"][data-board-theme-color="active"]');
@@ -326,7 +351,7 @@ export function createStore(initialSnapshot, options = {}) {
   }
 
   function persist() {
-    writeStoredState({
+    return writeStoredState({
       screen: state.screen,
       selectedEpicId: state.selectedEpicId,
       search: state.search,
@@ -457,6 +482,13 @@ export function createStore(initialSnapshot, options = {}) {
       notify();
     },
 
+    applySnapshotDelta(delta) {
+      state.snapshot = normalize(applySnapshotDelta(state.snapshot, delta));
+      syncState();
+      persist();
+      notify();
+    },
+
     /** Persist navigational state to localStorage. */
     persist,