@kabmo-labs/kabmo 0.3.1 → 0.5.0

package/src/client/hooks/chat/waiting/choice.ts

@@ -0,0 +1,53 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The composer's "wait for session" pick, per chat.
+ *
+ * Held in the session's own UI state (`chat.waitingFor`) rather than in
+ * component state: the composer is remounted by a stretch, a tab switch and a
+ * reload, and a pick that evaporated with it would silently send the prompt
+ * immediately — the one outcome the user explicitly deferred.
+ *
+ * The ref is the other half, and it is not redundant: the send handler is
+ * created once per deps record, so reading the pick from render state there
+ * would dispatch with whatever it was when that closure was built.
+ */
+
+import { useCallback, useEffect, useRef } from 'preact/hooks';
+import { useSessionState } from '@/client/hooks/workspace/session-state';
+import type { WaitingCandidate } from '@/client/components/workspace/chat-timeline/chat-input/WaitingDependencyPicker';
+
+export interface WaitingDependencyChoice {
+  value: WaitingCandidate | null;
+  ref: { current: WaitingCandidate | null };
+  set: (candidate: WaitingCandidate | null) => void;
+  clear: () => void;
+}
+
+export function useWaitingDependencyChoice(sessionId: string | null): WaitingDependencyChoice {
+  const [stored, setStored] = useSessionState<WaitingCandidate | null>('chat.waitingFor', null);
+  const ref = useRef<WaitingCandidate | null>(stored);
+  ref.current = stored;
+
+  // The pick belongs to ONE chat's next prompt. A pending chat is replaced by
+  // the id a spawn adopts, which is a different slot — so nothing has to be
+  // cleared for the normal path. This covers the other direction: a session that
+  // is not pending at all has no use for a pick, and a stale value there would
+  // be applied by the next New Session the user opens in that slot.
+  const pending = Boolean(sessionId?.startsWith('new-'));
+  useEffect(() => {
+    if (!pending && stored !== null) setStored(null);
+  }, [pending, stored, setStored]);
+
+  const set = useCallback((candidate: WaitingCandidate | null) => {
+    ref.current = candidate;
+    setStored(candidate);
+  }, [setStored]);
+
+  const clear = useCallback(() => set(null), [set]);
+
+  return { value: stored, ref, set, clear };
+}

package/src/client/hooks/chat/waiting/dispatch.ts

@@ -0,0 +1,91 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Following a held prompt to its outcome.
+ *
+ * The dispatch happens on the SERVER, in a process that may be a different
+ * instance, a different tab's, or one that started after this page was closed.
+ * Nothing on this side sends it, so the only thing that can report it is the
+ * `waiting` topic — and what a dispatched row carries is exactly what the local
+ * send path produces for itself: the omp session id the spawn answered with.
+ *
+ * That is why the adoption is here rather than in the composer: the pending
+ * row's `new-…` id has to move onto the real one whether or not the composer is
+ * still mounted, and whether or not this tab is the one that created it.
+ */
+
+import { useEffect, useRef } from 'preact/hooks';
+import { useWaitingPrompts } from '@/client/hooks/chat/waiting/store';
+import {
+  adoptPendingSession,
+  releasePendingSession,
+} from '@/client/hooks/chat/omp/pending-sessions';
+import { clearPendingSessionWaiting, pendingSessionWait } from '@/client/hooks/chat/omp/pending-waiting';
+import { useSearchParams } from '@/client/lib/router/search-params';
+
+export interface WaitingDispatchOptions {
+  /** Surfaces an outcome the user must know about (a failed or cancelled wait). */
+  onNotice?: (message: string) => void;
+}
+
+/**
+ * Adopt the session a held prompt became, and report the outcomes that are not
+ * a dispatch.
+ *
+ * Mounted once, beside the sidebar's own data provider: every layout needs it,
+ * and the pending row it adopts lives in the same client store both sidebars
+ * read.
+ */
+export function useWaitingDispatch({ onNotice }: WaitingDispatchOptions = {}): void {
+  const { prompts } = useWaitingPrompts();
+  const [, setSearchParams] = useSearchParams();
+  // The toast stack's `pushToast` is a fresh closure per render, so it must not
+  // be an effect dependency: every unrelated render would re-run this walk.
+  const noticeRef = useRef(onNotice);
+  noticeRef.current = onNotice;
+
+  useEffect(() => {
+    for (const prompt of prompts) {
+      const pendingId = prompt.pendingId;
+      if (!pendingId) continue;
+      const held = pendingSessionWait(pendingId);
+
+      if (prompt.status === 'dispatched' && prompt.sessionId) {
+        // Adopt when this tab OWNS the chat: it still holds the cue, or its URL
+        // names the pending id (a reload, a second tab on the same chat). A row
+        // from someone else's chat is left alone — adopting it would mint a
+        // sidebar entry for a session this tab never opened.
+        const openId = new URLSearchParams(window.location.search).get('sessionId');
+        if (!held && openId !== pendingId) continue;
+        adoptPendingSession(pendingId, prompt.sessionId, prompt.folderId);
+        // The URL may still name the pending id — this tab was left on the chat
+        // while the dispatch happened elsewhere.
+        setSearchParams((prev) => {
+          if (prev.get('sessionId') !== pendingId) return prev;
+          const next = new URLSearchParams(prev);
+          next.set('sessionId', prompt.sessionId as string);
+          return next;
+        }, { replace: true });
+        noticeRef.current?.(`Waiting finished — your prompt is now running in a new session.`);
+        continue;
+      }
+
+      if (prompt.status === 'error') {
+        const openId = new URLSearchParams(window.location.search).get('sessionId');
+        if (!held && openId !== pendingId) continue;
+        clearPendingSessionWaiting(pendingId);
+        releasePendingSession(pendingId);
+        noticeRef.current?.(`The prompt you held was not sent: ${prompt.error ?? 'the dispatch failed.'}`);
+        continue;
+      }
+
+      if (prompt.status === 'cancelled' && held) {
+        clearPendingSessionWaiting(pendingId);
+        noticeRef.current?.('The held prompt was cancelled.');
+      }
+    }
+  }, [prompts, setSearchParams]);
+}

package/src/client/hooks/chat/waiting/held.ts

@@ -0,0 +1,42 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The held prompt of the chat on screen, and how to drop it.
+ *
+ * A chat whose prompt is deferred has no session and no transcript, so the
+ * composer is the only place the wait is visible — and it must be DISABLED
+ * while the wait lasts: a second prompt would have nowhere to go.
+ */
+
+import { useCallback, useMemo } from 'preact/hooks';
+import { useWaitingPrompts } from '@/client/hooks/chat/waiting/store';
+import { useCancelWait } from '@/client/hooks/chat/waiting/cancel';
+import type { WaitingPrompt } from '@/shared/types/waiting';
+
+export interface HeldWait {
+  /** The waiting row for the open chat, or null. */
+  heldWait: WaitingPrompt | null;
+  cancelHeldWait: () => void;
+}
+
+export function useHeldWait(
+  sessionId: string | null,
+  isPendingSession: boolean,
+  onNotice?: (message: string, type?: 'success' | 'error') => void,
+): HeldWait {
+  const { prompts } = useWaitingPrompts();
+  const cancelWait = useCancelWait(onNotice);
+  const heldWait = useMemo(
+    () => (isPendingSession
+      ? prompts.find((prompt) => prompt.pendingId === sessionId && prompt.status === 'waiting') ?? null
+      : null),
+    [isPendingSession, sessionId, prompts],
+  );
+  const cancelHeldWait = useCallback(() => {
+    if (heldWait) cancelWait(heldWait.id);
+  }, [heldWait, cancelWait]);
+  return { heldWait, cancelHeldWait };
+}

package/src/client/hooks/chat/waiting/hold.test.ts

@@ -0,0 +1,139 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The hold path: what makes a prompt deferred instead of sent.
+ *
+ * Three behaviours are pinned, and each is a decision rather than an
+ * implementation detail:
+ *
+ *   - a stale pick (the session finished while the draft was written) SENDS,
+ *     and says so — a wait created on it would be released by the next sweep;
+ *   - a refusal KEEPS the draft, because the user's text is the one thing that
+ *     cannot be recovered from anywhere else;
+ *   - a success writes the pending row's cue, which is what keeps the sidebar
+ *     row on screen until the dispatch adopts it.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { holdPromptForDependency, type HoldDeps } from '@/client/hooks/chat/waiting/hold';
+import {
+  listPendingSessions,
+  releasePendingSession,
+  startPendingSession,
+} from '@/client/hooks/chat/omp/pending-sessions';
+import { pendingSessionWait } from '@/client/hooks/chat/omp/pending-waiting';
+import type { WaitingCandidate } from '@/client/components/workspace/chat-timeline/chat-input/WaitingDependencyPicker';
+import type { Attachment } from '@/shared/types/chat';
+
+const DEPENDENCY: WaitingCandidate = { id: 'sess-a', title: 'Refactor parser', folderName: 'alpha' };
+
+interface Recorded {
+  drafts: string[];
+  attachments: Attachment[][];
+  errors: string[];
+  cleared: number;
+  posted: Record<string, unknown>[];
+}
+
+const nativeFetch = globalThis.fetch;
+/** The id `startPendingSession` minted for this case; the store owns the clock. */
+let pendingId = '';
+
+function harness(overrides: Partial<HoldDeps> = {}): { deps: HoldDeps; recorded: Recorded } {
+  const recorded: Recorded = { drafts: [], attachments: [], errors: [], cleared: 0, posted: [] };
+  const deps: HoldDeps = {
+    sessionId: pendingId,
+    folders: [{ id: 1, name: 'alpha', project_path: '/tmp/alpha', isExpanded: true, hasMore: false, totalSessions: 0, sessions: [] }],
+    selectedFolderId: 1,
+    composerModelRef: { current: { provider: 'anthropic', modelId: 'claude', thinkingLevel: 'high' } },
+    accessModeRef: { current: 'always-ask' },
+    spawnModesRef: { current: { plan: false, goal: false } },
+    streamStatusMap: { 'sess-a': 'stream' },
+    setInputValue: (value) => recorded.drafts.push(value),
+    setAttachments: (value) => recorded.attachments.push(value),
+    reportActionError: (message) => recorded.errors.push(message),
+    clearChoice: () => { recorded.cleared += 1; },
+    ...overrides,
+  };
+  return { deps, recorded };
+}
+
+beforeEach(() => {
+  pendingId = startPendingSession(1);
+  (globalThis as Record<string, unknown>).fetch = async (_input: unknown, init?: { body?: string }) => {
+    const body = init?.body ? JSON.parse(init.body) : {};
+    createdBody = body;
+    return new Response(JSON.stringify({ prompt: { id: 'wait-1', ...body, status: 'waiting' } }), {
+      status: 200,
+      headers: { 'content-type': 'application/json' },
+    });
+  };
+});
+
+let createdBody: Record<string, unknown> = {};
+
+afterEach(() => {
+  globalThis.fetch = nativeFetch;
+  for (const entry of listPendingSessions()) releasePendingSession(entry.id);
+  createdBody = {};
+});
+
+describe('holdPromptForDependency', () => {
+  test('writes the row and marks the pending chat as waiting', async () => {
+    const { deps, recorded } = harness();
+    const held = await holdPromptForDependency(deps, DEPENDENCY, 'summarise it', []);
+
+    expect(held).toBe(true);
+    expect(recorded.drafts).toEqual(['']);
+    expect(recorded.attachments).toEqual([[]]);
+    expect(recorded.cleared).toBe(1);
+    expect(createdBody).toMatchObject({
+      dependsOn: 'sess-a',
+      dependsOnTitle: 'Refactor parser',
+      prompt: 'summarise it',
+      cwd: '/tmp/alpha',
+      folderId: 1,
+      model: { provider: 'anthropic', modelId: 'claude', thinkingLevel: 'high', accessMode: 'always-ask' },
+    });
+    expect(pendingSessionWait(pendingId)).toMatchObject({ waitId: 'wait-1', dependsOn: 'sess-a' });
+  });
+
+  test('no pick means the caller sends normally', async () => {
+    const { deps, recorded } = harness();
+    expect(await holdPromptForDependency(deps, null, 'hello', [])).toBe(false);
+    expect(recorded.drafts).toEqual([]);
+  });
+
+  // The dropdown was opened while the dependency was running; by the time the
+  // user hit send it had finished. Holding would be a wait of zero length.
+  test('a dependency that finished meanwhile sends instead, and says so', async () => {
+    const { deps, recorded } = harness({ streamStatusMap: { 'sess-a': 'finish' } });
+    expect(await holdPromptForDependency(deps, DEPENDENCY, 'hello', [])).toBe(false);
+    expect(recorded.errors).toEqual(['"Refactor parser" has already finished — sending now instead of waiting.']);
+    expect(recorded.cleared).toBe(1);
+    expect(recorded.drafts).toEqual([]);
+  });
+
+  test('a refused request keeps the draft and reports the server reason', async () => {
+    (globalThis as Record<string, unknown>).fetch = async () =>
+      new Response(JSON.stringify({ error: 'That session has already finished' }), {
+        status: 409,
+        headers: { 'content-type': 'application/json' },
+      });
+    const { deps, recorded } = harness();
+    expect(await holdPromptForDependency(deps, DEPENDENCY, 'hello', [])).toBe(false);
+    expect(recorded.errors).toEqual(['That session has already finished']);
+    expect(recorded.drafts).toEqual([]);
+    expect(pendingSessionWait(pendingId)).toBeNull();
+  });
+
+  test('a chat with no workspace is refused before anything is written', async () => {
+    const { deps, recorded } = harness({ folders: [], selectedFolderId: null });
+    expect(await holdPromptForDependency(deps, DEPENDENCY, 'hello', [])).toBe(false);
+    expect(recorded.errors).toEqual(['Pick a workspace before holding this prompt.']);
+    expect(createdBody).toEqual({});
+  });
+});

package/src/client/hooks/chat/waiting/hold.ts

@@ -0,0 +1,156 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Sending a NEW chat's prompt into a wait instead of dispatching it now.
+ *
+ * The prompt never reaches omp from here: the row is written server-side and a
+ * sweep spawns the session when the dependency finishes. That is why this path
+ * clears the composer and marks the pending row, and why it does NOT arm the
+ * generating state — nothing is running yet, and a spinner would say otherwise.
+ *
+ * The dependency is re-checked against the live status map at send time. A
+ * dropdown opened a minute ago can name a session that has since finished, and
+ * a prompt held on it would be released by the very next sweep: the user asked
+ * to wait, so the honest outcome is to send it now and say so.
+ */
+
+import type { Attachment } from '@/shared/types/chat';
+import type { WorkspaceFolderData } from '@/shared/types/workspace';
+import { prepareQueuedAttachments } from '@/shared/lib/chat/attachments';
+import { createWaitingPromptRequest } from '@/client/hooks/chat/waiting/store';
+import { markPendingSessionWaiting } from '@/client/hooks/chat/omp/pending-waiting';
+import type { WaitingCandidate } from '@/client/components/workspace/chat-timeline/chat-input/WaitingDependencyPicker';
+
+/**
+ * The slice of the composer's deps record a hold needs.
+ *
+ * Structural, not an import of the actions record: the caller passes that whole
+ * record and TypeScript checks it against this, so the two stay decoupled and
+ * this module never depends on the send hook's shape.
+ */
+export interface ComposerHoldDeps {
+  sessionId: string | null;
+  folders: WorkspaceFolderData[];
+  selectedFolderId: number | null;
+  composerModelRef: { current: { provider: string; modelId: string; thinkingLevel: string } | null };
+  accessModeRef: { current: string };
+  spawnSelectionRef?: { current: { plan: boolean; goal: boolean } | null };
+  streamStatusMap?: Record<string, string | undefined>;
+  setInputValue: (value: string) => void;
+  setInputAttachments: (attachments: Attachment[] | ((prev: Attachment[]) => Attachment[])) => void;
+  reportActionError: (message: string) => void;
+  clearWaitingDependency?: () => void;
+  waitingDependencyRef?: { current: WaitingCandidate | null };
+}
+
+/**
+ * The composer's own entry point: hold the draft if a dependency is picked and
+ * the chat is idle, else answer false and let the normal send proceed.
+ *
+ * Idle is part of the condition rather than the caller's business: a chat with
+ * a run in flight queues its follow-up (or steers), which is a different
+ * decision made further down the send path.
+ */
+export async function holdFromComposer(
+  deps: ComposerHoldDeps,
+  text: string,
+  attachments: Attachment[],
+  busy: boolean,
+): Promise<boolean> {
+  const choice = deps.waitingDependencyRef?.current ?? null;
+  if (!choice || busy) return false;
+  return holdPromptForDependency({
+    sessionId: deps.sessionId,
+    folders: deps.folders,
+    selectedFolderId: deps.selectedFolderId,
+    composerModelRef: deps.composerModelRef,
+    accessModeRef: deps.accessModeRef,
+    spawnModesRef: deps.spawnSelectionRef ?? { current: null },
+    streamStatusMap: deps.streamStatusMap ?? {},
+    setInputValue: deps.setInputValue,
+    setAttachments: (next) => deps.setInputAttachments(next),
+    reportActionError: deps.reportActionError,
+    clearChoice: () => deps.clearWaitingDependency?.(),
+  }, choice, text, attachments);
+}
+
+export interface HoldDeps {
+  sessionId: string | null;
+  folders: WorkspaceFolderData[];
+  selectedFolderId: number | null;
+  composerModelRef: { current: { provider: string; modelId: string; thinkingLevel: string } | null };
+  accessModeRef: { current: string };
+  spawnModesRef: { current: { plan: boolean; goal: boolean } | null };
+  streamStatusMap: Record<string, string | undefined>;
+  setInputValue: (value: string) => void;
+  setAttachments: (attachments: Attachment[]) => void;
+  reportActionError: (message: string) => void;
+  /** The dependency pick, cleared once the prompt is held. */
+  clearChoice: () => void;
+}
+
+/**
+ * Hold `text` until `dependency` finishes.
+ *
+ * Returns true when the prompt was held — the caller must then do nothing else.
+ * A false return means the caller should fall through to a normal send: either
+ * there is no dependency, or it is no longer running.
+ */
+export async function holdPromptForDependency(
+  deps: HoldDeps,
+  dependency: WaitingCandidate | null,
+  text: string,
+  attachments: Attachment[],
+): Promise<boolean> {
+  if (!dependency) return false;
+  if (deps.streamStatusMap[dependency.id] !== 'stream') {
+    // Stale pick: the session finished while the draft was being written. Send
+    // normally rather than creating a wait that releases on the next sweep.
+    deps.reportActionError(`"${dependency.title}" has already finished — sending now instead of waiting.`);
+    deps.clearChoice();
+    return false;
+  }
+  const folder = deps.folders.find((entry) => String(entry.id) === String(deps.selectedFolderId));
+  const cwd = folder?.project_path || folder?.name;
+  if (!cwd) {
+    deps.reportActionError('Pick a workspace before holding this prompt.');
+    return false;
+  }
+
+  // Attachments become the persisted shape here, while the live `File` handles
+  // still exist: the server sends the prompt hours later, from the row.
+  const prepared = await prepareQueuedAttachments(attachments);
+  const composerPick = deps.composerModelRef.current;
+  try {
+    const created = await createWaitingPromptRequest({
+      pendingId: deps.sessionId,
+      dependsOn: dependency.id,
+      dependsOnTitle: dependency.title,
+      prompt: text,
+      attachments: prepared,
+      model: composerPick ? { ...composerPick, accessMode: deps.accessModeRef.current } : null,
+      modes: deps.spawnModesRef.current,
+      cwd,
+      folderId: folder ? Number(folder.id) : null,
+    });
+    if (deps.sessionId) {
+      markPendingSessionWaiting(deps.sessionId, {
+        waitId: created.id,
+        dependsOn: dependency.id,
+        dependsOnTitle: dependency.title,
+      });
+    }
+    deps.setInputValue('');
+    deps.setAttachments([]);
+    deps.clearChoice();
+    return true;
+  } catch (error) {
+    // The draft is KEPT: a refusal that also threw away the prompt would be the
+    // worst of both outcomes, and the composer still holds what the user wrote.
+    deps.reportActionError(error instanceof Error ? error.message : String(error));
+    return false;
+  }
+}

package/src/client/hooks/chat/waiting/store.ts

@@ -0,0 +1,100 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Client view of the waiting prompts (`waiting_prompts`, owned by the server).
+ *
+ * The panel is a VIEW, exactly like the follow-up queue: the server holds the
+ * clock, the row is the state, and this hook reads it off the `waiting` topic.
+ * The HTTP route is the fallback for a socket that is down.
+ */
+
+import { useCallback, useEffect, useState } from 'preact/hooks';
+import { useRealtimeTopic } from '@/client/hooks/ui/realtime';
+import { TOPIC_WAITING } from '@/shared/lib/realtime/protocol';
+import type { WaitingPrompt } from '@/shared/types/waiting';
+
+export interface WaitingPromptsState {
+  prompts: WaitingPrompt[];
+  /**
+   * Whether the list has been READ from the server.
+   *
+   * Load-bearing for anything that CLEARS state from an absence: before the
+   * first payload, "no row names this wait" is not a fact, it is a page that
+   * has not loaded yet. Clearing on it deleted a cue the user had just created —
+   * the controller's effect runs on the render the hold triggers, one frame
+   * before the topic's first snapshot.
+   */
+  loaded: boolean;
+  /** Ask the server for a fresh snapshot (a manual refresh). */
+  refresh: () => void;
+}
+
+export function useWaitingPrompts(): WaitingPromptsState {
+  const topic = useRealtimeTopic<WaitingPrompt[]>(TOPIC_WAITING);
+  const [fallback, setFallback] = useState<WaitingPrompt[]>([]);
+  const [loadedFallback, setLoadedFallback] = useState(false);
+
+  // The topic is the source; the HTTP read only fills in before the first frame
+  // lands, or when the socket is down (a phone that just woke).
+  useEffect(() => {
+    if (Array.isArray(topic.data)) return;
+    let active = true;
+    fetch('/api/waiting')
+      .then((response) => (response.ok ? response.json() : null))
+      .then((data) => {
+        if (!active || !Array.isArray(data?.prompts)) return;
+        setFallback(data.prompts as WaitingPrompt[]);
+        setLoadedFallback(true);
+      })
+      .catch(() => {});
+    return () => {
+      active = false;
+    };
+  }, [topic.data]);
+
+  const fromTopic = Array.isArray(topic.data);
+  const prompts = fromTopic ? (topic.data as WaitingPrompt[]) : fallback;
+  const refresh = useCallback(() => topic.refresh(), [topic]);
+  return {
+    prompts,
+    // The HTTP read counts too: it is the same list, and a socket that is down
+    // must not leave every consumer believing the server holds nothing.
+    loaded: fromTopic || loadedFallback,
+    refresh,
+  };
+}
+
+/** Create a held prompt. Throws the server's own reason on a refusal. */
+export async function createWaitingPromptRequest(input: {
+  pendingId: string | null;
+  dependsOn: string;
+  dependsOnTitle: string | null;
+  prompt: string;
+  attachments: unknown[];
+  model: unknown;
+  modes: { plan: boolean; goal: boolean } | null;
+  cwd: string;
+  folderId: number | null;
+}): Promise<WaitingPrompt> {
+  const response = await fetch('/api/waiting', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(input),
+  });
+  const data = await response.json().catch(() => null);
+  if (!response.ok || !data?.prompt) {
+    throw new Error(typeof data?.error === 'string' ? data.error : `HTTP ${response.status}`);
+  }
+  return data.prompt as WaitingPrompt;
+}
+
+/** Cancel a held prompt. Returns the server's refusal rather than swallowing it. */
+export async function cancelWaitingPromptRequest(id: string): Promise<{ ok: boolean; error?: string }> {
+  const response = await fetch(`/api/waiting?id=${encodeURIComponent(id)}`, { method: 'DELETE' });
+  if (response.ok) return { ok: true };
+  const data = await response.json().catch(() => null);
+  return { ok: false, error: typeof data?.error === 'string' ? data.error : `HTTP ${response.status}` };
+}

package/src/client/hooks/ui/toasts.ts

@@ -1,7 +1,18 @@
 import { useRef, useState } from 'preact/hooks';
 import type { ToastData } from '@/client/components/common/Toast';
 
-export function useToasts() {
+/** What `useToasts` hands back — named, so a component takes the contract rather than `ReturnType`. */
+export interface ToastsHandle {
+  toasts: ToastData[];
+  pushToast: (
+    message: string,
+    type?: 'success' | 'error',
+    options?: { action?: ToastData['action']; duration?: number },
+  ) => void;
+  dismissToast: (id: number) => void;
+}
+
+export function useToasts(): ToastsHandle {
   const [toasts, setToasts] = useState<ToastData[]>([]);
   const toastIdRef = useRef(0);