@miragon/mcp-toolkit-ui 2.7.0 → 2.8.0

package/src/lib/focus-return.test.ts

@@ -0,0 +1,288 @@
+import { createElement } from "react"
+import { renderToStaticMarkup } from "react-dom/server"
+import ts from "typescript"
+import { afterEach, describe, expect, it, vi } from "vitest"
+import { createFocusReturn, useFocusReturn, type AutoFocusEventLike } from "./focus-return.js"
+
+/**
+ * Focus return of the kit's dialogs and sheets (CI §12 and §8 "Fokus im
+ * Dialog halten und danach zurückgeben"): the hand-back itself, and the
+ * gates that keep every overlay on it.
+ */
+
+declare global {
+  interface ImportMeta {
+    glob(
+      pattern: string | string[],
+      options: { query: "?raw"; import: "default"; eager: true },
+    ): Record<string, string>
+  }
+}
+
+const element = (isConnected = true) => ({ isConnected, focus: vi.fn<() => void>() })
+const BODY = { body: true }
+
+function closeEvent(defaultPrevented = false): AutoFocusEventLike & {
+  preventDefault: ReturnType<typeof vi.fn<() => void>>
+} {
+  return { defaultPrevented, preventDefault: vi.fn<() => void>() }
+}
+
+describe("createFocusReturn", () => {
+  it("hands the focus back to the element that had it as the overlay opened", () => {
+    const fr = createFocusReturn()
+    const opener = element()
+    fr.capture(opener, BODY)
+    const event = closeEvent()
+    fr.restore(event, true)
+    expect(opener.focus).toHaveBeenCalledOnce()
+    // Radix's own close handler (it focuses only a Trigger) must not run after it.
+    expect(event.preventDefault).toHaveBeenCalledOnce()
+  })
+
+  it("leaves Radix's default alone when the body had the focus (nothing to return to)", () => {
+    const fr = createFocusReturn()
+    fr.capture(null, BODY)
+    const nothing = closeEvent()
+    fr.restore(nothing, true)
+    expect(nothing.preventDefault).not.toHaveBeenCalled()
+
+    const body = { ...element(), ...BODY }
+    fr.capture(body, body)
+    const event = closeEvent()
+    fr.restore(event, true)
+    expect(body.focus).not.toHaveBeenCalled()
+    expect(event.preventDefault).not.toHaveBeenCalled()
+  })
+
+  it("does not focus an opener that left the document (Apply or Discard unmounted it)", () => {
+    const fr = createFocusReturn()
+    const opener = element(false)
+    fr.capture(opener, BODY)
+    const event = closeEvent()
+    fr.restore(event, true)
+    expect(opener.focus).not.toHaveBeenCalled()
+    expect(event.preventDefault).not.toHaveBeenCalled()
+  })
+
+  it("leaves the focus where it went when it did not get lost with the overlay", () => {
+    // A click outside a non-modal overlay, or a hand-off (Apply) that already moved it.
+    const fr = createFocusReturn()
+    const opener = element()
+    fr.capture(opener, BODY)
+    const event = closeEvent()
+    fr.restore(event, false)
+    expect(opener.focus).not.toHaveBeenCalled()
+    expect(event.preventDefault).not.toHaveBeenCalled()
+  })
+
+  it("yields to a consumer's close handler that prevented the default", () => {
+    const fr = createFocusReturn()
+    const opener = element()
+    fr.capture(opener, BODY)
+    fr.restore(closeEvent(true), true)
+    expect(opener.focus).not.toHaveBeenCalled()
+  })
+
+  it("returns the focus once per opening, to the latest opener", () => {
+    const fr = createFocusReturn()
+    const first = element()
+    const second = element()
+    fr.capture(first, BODY)
+    fr.capture(second, BODY)
+    fr.restore(closeEvent(), true)
+    fr.restore(closeEvent(), true)
+    expect(first.focus).not.toHaveBeenCalled()
+    expect(second.focus).toHaveBeenCalledOnce()
+  })
+})
+
+// -------------------------------------------------------------------------- //
+// useFocusReturn: the order around the consumer's own handlers
+// -------------------------------------------------------------------------- //
+
+/** A Radix-like auto-focus event: `preventDefault()` sets `defaultPrevented`. */
+function autoFocusEvent(): AutoFocusEventLike {
+  const event = {
+    defaultPrevented: false,
+    preventDefault: () => {
+      event.defaultPrevented = true
+    },
+  }
+  return event
+}
+
+type Handlers = ReturnType<typeof useFocusReturn<AutoFocusEventLike>>
+
+/** The handler pair the hook hands a Radix content, from one SSR render. */
+function handlersOf(consumer: Partial<Handlers>): Handlers {
+  let handlers: Handlers | undefined
+  function Probe() {
+    handlers = useFocusReturn(consumer)
+    return null
+  }
+  renderToStaticMarkup(createElement(Probe))
+  if (!handlers) throw new Error("the probe did not render")
+  return handlers
+}
+
+describe("useFocusReturn", () => {
+  const body = { tag: "body" }
+  const doc = { activeElement: null as unknown, body }
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it("notes the opener BEFORE the consumer's open handler can move the focus", () => {
+    vi.stubGlobal("document", doc)
+    const opener = element()
+    const elsewhere = element()
+    const handlers = handlersOf({
+      onOpenAutoFocus: () => {
+        doc.activeElement = elsewhere
+      },
+    })
+    doc.activeElement = opener
+    handlers.onOpenAutoFocus(autoFocusEvent())
+    doc.activeElement = body // the overlay closed with the focus inside it
+    const close = autoFocusEvent()
+    handlers.onCloseAutoFocus(close)
+    expect(opener.focus).toHaveBeenCalledOnce()
+    expect(elsewhere.focus).not.toHaveBeenCalled()
+    expect(close.defaultPrevented).toBe(true)
+  })
+
+  it("runs the consumer's close handler first: its preventDefault keeps the focus with it", () => {
+    vi.stubGlobal("document", doc)
+    const opener = element()
+    const onCloseAutoFocus = vi.fn((event: AutoFocusEventLike) => event.preventDefault())
+    const handlers = handlersOf({ onCloseAutoFocus })
+    doc.activeElement = opener
+    handlers.onOpenAutoFocus(autoFocusEvent())
+    doc.activeElement = body
+    handlers.onCloseAutoFocus(autoFocusEvent())
+    expect(onCloseAutoFocus).toHaveBeenCalledOnce()
+    expect(opener.focus).not.toHaveBeenCalled()
+  })
+
+  it("hands back on a lost focus only: the body, or none at all", () => {
+    vi.stubGlobal("document", doc)
+    const opener = element()
+    const handlers = handlersOf({})
+    for (const atClose of [body, null]) {
+      doc.activeElement = opener
+      handlers.onOpenAutoFocus(autoFocusEvent())
+      doc.activeElement = atClose
+      handlers.onCloseAutoFocus(autoFocusEvent())
+    }
+    expect(opener.focus).toHaveBeenCalledTimes(2)
+
+    // The focus already sits on another element: it stays there.
+    const moved = element()
+    doc.activeElement = opener
+    handlers.onOpenAutoFocus(autoFocusEvent())
+    doc.activeElement = moved
+    const close = autoFocusEvent()
+    handlers.onCloseAutoFocus(close)
+    expect(opener.focus).toHaveBeenCalledTimes(2)
+    expect(close.defaultPrevented).toBe(false)
+  })
+
+  it("notes no opener that cannot take the focus", () => {
+    vi.stubGlobal("document", doc)
+    const handlers = handlersOf({})
+    doc.activeElement = { isConnected: true } // no focus()
+    handlers.onOpenAutoFocus(autoFocusEvent())
+    doc.activeElement = body
+    const close = autoFocusEvent()
+    expect(() => handlers.onCloseAutoFocus(close)).not.toThrow()
+    expect(close.defaultPrevented).toBe(false)
+  })
+})
+
+// -------------------------------------------------------------------------- //
+// Gates: every overlay of the kit goes through the hand-back
+// -------------------------------------------------------------------------- //
+
+const SOURCES = import.meta.glob(["../**/*.tsx", "!../**/*.test.tsx"], {
+  query: "?raw",
+  import: "default",
+  eager: true,
+})
+
+/** Names of the JSX attributes on every `<tag …>` in a source (spreads as `...expr`). */
+function attributesOf(file: string, source: string, tag: string): string[][] {
+  const sf = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX)
+  const found: string[][] = []
+  const visit = (node: ts.Node) => {
+    if (
+      (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) &&
+      node.tagName.getText(sf) === tag
+    ) {
+      found.push(
+        node.attributes.properties.map((p) =>
+          ts.isJsxAttribute(p) ? p.name.getText(sf) : `...${p.expression.getText(sf)}`,
+        ),
+      )
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(sf)
+  return found
+}
+
+/** Whether a source puts `autoFocus` on any JSX element. */
+function hasAutoFocus(file: string, source: string): boolean {
+  const sf = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX)
+  let found = false
+  const visit = (node: ts.Node) => {
+    if (ts.isJsxAttribute(node) && node.name.getText(sf) === "autoFocus") found = true
+    ts.forEachChild(node, visit)
+  }
+  visit(sf)
+  return found
+}
+
+describe("overlay focus gates", () => {
+  it("scans the kit's components", () => {
+    expect(Object.keys(SOURCES)).toContain("../primitives/dialog.tsx")
+    expect(Object.keys(SOURCES)).toContain("../app/builder/DiscardDialog.tsx")
+  })
+
+  it("imports Radix's Dialog only in the two primitives that add the hand-back", () => {
+    const importers = Object.entries(SOURCES)
+      .filter(([, src]) =>
+        /import\s*\{[^}]*\b(?:Alert)?Dialog\b[^}]*\}\s*from\s*"radix-ui"/.test(src),
+      )
+      .map(([file]) => file)
+      .sort()
+    expect(importers).toEqual(["../primitives/dialog.tsx", "../primitives/sheet.tsx"])
+  })
+
+  it("spreads the hand-back into the Radix content AFTER the consumer's props", () => {
+    for (const [file, primitive] of [
+      ["../primitives/dialog.tsx", "DialogPrimitive.Content"],
+      ["../primitives/sheet.tsx", "SheetPrimitive.Content"],
+    ] as const) {
+      const contents = attributesOf(file, SOURCES[file] ?? "", primitive)
+      expect(contents, file).toHaveLength(1)
+      const attrs = contents[0] ?? []
+      expect(attrs.indexOf("...focusReturn"), file).toBeGreaterThan(attrs.indexOf("...props"))
+      expect(SOURCES[file], file).toMatch(
+        /useFocusReturn\(\{ onOpenAutoFocus, onCloseAutoFocus \}\)/,
+      )
+    }
+  })
+
+  it("lets no overlay content take the focus itself (Radix would skip noting the opener)", () => {
+    const overlays = Object.entries(SOURCES).filter(([, src]) =>
+      /<(DialogContent|SheetContent)\b/.test(src),
+    )
+    expect(overlays.length).toBeGreaterThan(3)
+    expect(overlays.filter(([file, src]) => hasAutoFocus(file, src)).map(([file]) => file)).toEqual(
+      [],
+    )
+    expect(hasAutoFocus("self.tsx", "const A = () => <input autoFocus />")).toBe(true)
+    expect(hasAutoFocus("self.tsx", "const autoFocus = 1")).toBe(false)
+  })
+})

package/src/lib/focus-return.ts

@@ -0,0 +1,96 @@
+import { useState } from "react"
+
+/**
+ * Focus return for the kit's dialogs and sheets (CI §12: focus goes back to
+ * where it came from).
+ *
+ * A Radix dialog returns the focus only to its `Trigger`. The kit's overlays
+ * mostly open from React state, without one (the builder's Save, Discard and
+ * Catalogue, a cell's props sheet), and Radix then cancels its focus scope's
+ * own restore and focuses nothing: closing them by keyboard left the focus on
+ * the document body. `DialogContent` and `SheetContent` therefore note the
+ * element that has the focus as they open and hand the focus back to it when
+ * they close and the focus went with them, while that element is still in the
+ * document. A consumer's own `onCloseAutoFocus` that calls `preventDefault()`
+ * keeps full control.
+ */
+
+/** The part of an element the hand-back needs (structural, so it tests without a DOM). */
+export interface FocusReturnTarget {
+  readonly isConnected: boolean
+  focus: () => void
+}
+
+/** The part of Radix's auto-focus events the hand-back reads. */
+export interface AutoFocusEventLike {
+  readonly defaultPrevented: boolean
+  preventDefault: () => void
+}
+
+/** One overlay's hand-back, from {@link createFocusReturn}. */
+export interface FocusReturn {
+  /**
+   * Notes the element that has the focus as the overlay opens. The document
+   * body is no target: a pointer that opened it without focusing anything
+   * (Safari does not focus a clicked button) leaves Radix's default in place.
+   */
+  capture: (active: FocusReturnTarget | null, body: unknown) => void
+  /**
+   * Hands the focus back to the noted element when the overlay closes and the
+   * focus went with it (`focusLost`: it sits on the body). It leaves the focus
+   * where it is when a handler before it prevented that, when the focus
+   * already sits elsewhere (a click outside a non-modal overlay, a hand-off
+   * that moved it) or when the element left the document (an Apply or
+   * Discard that unmounted the builder). Forgets the element either way.
+   */
+  restore: (event: AutoFocusEventLike, focusLost: boolean) => void
+}
+
+/** A {@link FocusReturn} with nothing noted yet. */
+export function createFocusReturn(): FocusReturn {
+  let opener: FocusReturnTarget | null = null
+  return {
+    capture: (active, body) => {
+      opener = active === body ? null : active
+    },
+    restore: (event, focusLost) => {
+      const target = opener
+      opener = null
+      if (event.defaultPrevented || !focusLost || target === null || !target.isConnected) return
+      event.preventDefault()
+      target.focus()
+    },
+  }
+}
+
+/**
+ * The `onOpenAutoFocus` / `onCloseAutoFocus` pair of a Radix dialog content
+ * with the focus hand-back of {@link createFocusReturn} composed in: it notes
+ * the opener BEFORE the consumer's open handler runs (that one may move the
+ * focus) and hands it back AFTER the consumer's close handler (whose
+ * `preventDefault()` keeps it out). Radix fires the open event only when the
+ * focus is outside the content as it mounts, so an element inside it must not
+ * take the focus itself (`autoFocus`): Radix focuses the first one anyway.
+ */
+export function useFocusReturn<E extends AutoFocusEventLike>(handlers: {
+  onOpenAutoFocus?: (event: E) => void
+  onCloseAutoFocus?: (event: E) => void
+}): { onOpenAutoFocus: (event: E) => void; onCloseAutoFocus: (event: E) => void } {
+  const [focusReturn] = useState(createFocusReturn)
+  return {
+    onOpenAutoFocus: (event) => {
+      focusReturn.capture(activeElementOf(document), document.body)
+      handlers.onOpenAutoFocus?.(event)
+    },
+    onCloseAutoFocus: (event) => {
+      handlers.onCloseAutoFocus?.(event)
+      const active = document.activeElement
+      focusReturn.restore(event, active === null || active === document.body)
+    },
+  }
+}
+
+function activeElementOf(doc: Document): FocusReturnTarget | null {
+  const active = doc.activeElement
+  return active && "focus" in active ? (active as HTMLElement) : null
+}

package/src/lib/parse-tool-result.test.ts

@@ -1,5 +1,10 @@
 import { describe, expect, it } from "vitest"
-import { parseToolResult, parseViewToolResult } from "./parse-tool-result.js"
+import {
+  isToolError,
+  parseToolResult,
+  parseViewToolResult,
+  ToolResultError,
+} from "./parse-tool-result.js"
 
 describe("parseToolResult (structuredContent-first contract)", () => {
   it("prefers structuredContent over the text channel", () => {
@@ -137,3 +142,43 @@ describe("parseViewToolResult (show-tool envelope unwrap)", () => {
     expect(() => parseViewToolResult(result)).toThrowError("boom")
   })
 })
+
+describe("ToolResultError / isToolError (the query layer's no-retry signal)", () => {
+  it("an isError result throws a ToolResultError that carries the result", () => {
+    const result = { isError: true, content: [{ type: "text", text: "[404] gone" }] }
+    let thrown: unknown
+    try {
+      parseToolResult(result)
+    } catch (err) {
+      thrown = err
+    }
+    expect(thrown).toBeInstanceOf(ToolResultError)
+    expect(thrown).toBeInstanceOf(Error)
+    expect(thrown).toMatchObject({ name: "ToolResultError", message: "[404] gone", result })
+    expect(isToolError(thrown)).toBe(true)
+  })
+
+  it("recognises mcp-use's ToolError by its name and its isError result", () => {
+    const toolError = Object.assign(new Error("busy"), {
+      name: "ToolError",
+      result: { isError: true, content: [] },
+    })
+    expect(isToolError(toolError)).toBe(true)
+  })
+
+  it("anything else is no tool error: a transport failure, a look-alike, a non-error", () => {
+    expect(isToolError(new Error("connection lost"))).toBe(false)
+    expect(isToolError(Object.assign(new Error("x"), { name: "ToolError" }))).toBe(false)
+    expect(
+      isToolError(Object.assign(new Error("x"), { name: "ToolError", result: { isError: false } })),
+    ).toBe(false)
+    expect(isToolError(Object.assign(new Error("x"), { name: "ToolError", result: null }))).toBe(
+      false,
+    )
+    expect(
+      isToolError(Object.assign(new Error("x"), { name: "Other", result: { isError: true } })),
+    ).toBe(false)
+    expect(isToolError({ name: "ToolError", result: { isError: true } })).toBe(false)
+    expect(isToolError(undefined)).toBe(false)
+  })
+})

package/src/lib/parse-tool-result.ts

@@ -16,10 +16,48 @@ export interface ParseToolResultOptions {
   prefer?: "structured" | "text"
 }
 
+/**
+ * A tool answered with an `isError` result: a deterministic failure of the
+ * call itself (a validation error, an engine 404), not of the transport.
+ * Thrown by {@link parseToolResult}. The query hooks retry it like any
+ * failure by default (the client's `retry`); pass `retry: shouldRetryToolCall`
+ * to stop that, since repeating the call repeats the answer. Still an `Error`
+ * with the tool's first text block as its message.
+ */
+export class ToolResultError extends Error {
+  /** The `isError` result as the tool returned it. */
+  readonly result: unknown
+
+  constructor(message: string, result: unknown) {
+    super(message)
+    this.name = "ToolResultError"
+    this.result = result
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null
+}
+
+/**
+ * Whether `error` is a tool's own `isError` answer: a {@link ToolResultError},
+ * or mcp-use's `ToolError` (how `useDynamicTool` rejects an `isError` result
+ * inside a view), recognised by its name and result so the root barrel never
+ * imports `mcp-use/react`. Transport failures (a lost connection, a JSON-RPC
+ * error such as an unknown tool) are not tool errors.
+ */
+export function isToolError(error: unknown): boolean {
+  if (error instanceof ToolResultError) return true
+  if (!(error instanceof Error) || error.name !== "ToolError") return false
+  const result: unknown = (error as Error & { result?: unknown }).result
+  return isRecord(result) && result.isError === true
+}
+
 /**
  * Decodes an MCP tool result down to its data payload.
  *
- * Default (`prefer: "structured"`): `isError` → throw the first text block,
+ * Default (`prefer: "structured"`): `isError` → throw a
+ * {@link ToolResultError} with the first text block,
  * then `structuredContent` (if non-null), then JSON-decode the first text
  * block (verbatim string if it isn't JSON), then the raw result.
  *
@@ -37,7 +75,7 @@ export function parseToolResult<T = unknown>(result: unknown, opts?: ParseToolRe
         isError?: boolean
       }
     | undefined
-  if (r?.isError) throw new Error(r.content?.[0]?.text ?? "Tool call failed")
+  if (r?.isError) throw new ToolResultError(r.content?.[0]?.text ?? "Tool call failed", result)
 
   const fromStructured = (): T | undefined =>
     r?.structuredContent != null ? (r.structuredContent as T) : undefined

package/src/lib/toast-model.test.ts

@@ -1,12 +1,16 @@
-import { describe, expect, it } from "vitest"
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
 import {
   createToast,
+  createToastTimer,
   MAX_VISIBLE_TOASTS,
+  resolveToastTone,
   TOAST_DURATION_MS,
   TOAST_ERROR_DURATION_MS,
   toastDuration,
   toastReducer,
+  type ToastClock,
   type ToastItem,
+  type ToastOptions,
 } from "./toast-model.js"
 
 const item = (id: number): ToastItem => createToast(id, { title: `t${id}` })
@@ -50,6 +54,34 @@ describe("createToast", () => {
       duration: 5000,
     })
   })
+
+  it("resolves an untyped retired tone instead of keeping a name no icon exists for", () => {
+    // Plain JS or wire data: `error` is `danger`, with the error toast's 5 s.
+    const fromWire = { tone: "error", title: "Failed" } as unknown as ToastOptions
+    expect(createToast(4, fromWire)).toMatchObject({ tone: "danger", duration: 5000 })
+    const unknown = { tone: "purple", title: "x" } as unknown as ToastOptions
+    expect(createToast(5, unknown).tone).toBe("info")
+  })
+})
+
+describe("resolveToastTone (fail-soft for an untyped tone)", () => {
+  it("keeps the four toast tones and maps a retired name through resolveTone", () => {
+    for (const tone of ["success", "warning", "danger", "info"] as const) {
+      expect(resolveToastTone(tone)).toBe(tone)
+    }
+    expect(resolveToastTone("critical")).toBe("danger")
+    expect(resolveToastTone("Warn")).toBe("warning")
+    expect(resolveToastTone("ok")).toBe("success")
+    expect(resolveToastTone("notice")).toBe("info")
+  })
+
+  it("shows neutral, unknown and missing tones as info (a toast has no neutral edge)", () => {
+    expect(resolveToastTone("neutral")).toBe("info")
+    expect(resolveToastTone("secondary")).toBe("info")
+    expect(resolveToastTone("purple")).toBe("info")
+    expect(resolveToastTone(undefined)).toBe("info")
+    expect(resolveToastTone(42)).toBe("info")
+  })
 })
 
 describe("toastReducer", () => {
@@ -66,3 +98,136 @@ describe("toastReducer", () => {
     expect(toastReducer(state, { type: "dismiss", id: 9 })).toBe(state)
   })
 })
+
+describe("createToastTimer (a held toast resumes its REMAINING time)", () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it("expires once, after the full duration, when nothing holds it", () => {
+    const onExpire = vi.fn()
+    const timer = createToastTimer(2800, onExpire)
+    expect(timer.remaining()).toBe(2800)
+    vi.advanceTimersByTime(2799)
+    expect(onExpire).not.toHaveBeenCalled()
+    expect(timer.remaining()).toBe(1)
+    vi.advanceTimersByTime(1)
+    expect(onExpire).toHaveBeenCalledTimes(1)
+    expect(timer.remaining()).toBe(0)
+    vi.advanceTimersByTime(10_000)
+    expect(onExpire).toHaveBeenCalledTimes(1)
+  })
+
+  it("pauses while held and resumes with the time that was left, not a fresh duration", () => {
+    const onExpire = vi.fn()
+    const timer = createToastTimer(2800, onExpire)
+    vi.advanceTimersByTime(1000)
+    timer.hold("pointer")
+    expect(timer.remaining()).toBe(1800)
+    vi.advanceTimersByTime(60_000) // reading for a minute: nothing runs out
+    expect(onExpire).not.toHaveBeenCalled()
+    expect(timer.remaining()).toBe(1800)
+    timer.release("pointer")
+    vi.advanceTimersByTime(1799)
+    expect(onExpire).not.toHaveBeenCalled()
+    vi.advanceTimersByTime(1)
+    expect(onExpire).toHaveBeenCalledTimes(1)
+  })
+
+  it("keeps counting down across several holds (each resume continues the rest)", () => {
+    const onExpire = vi.fn()
+    const timer = createToastTimer(5000, onExpire)
+    vi.advanceTimersByTime(2000)
+    timer.hold("pointer")
+    vi.advanceTimersByTime(500)
+    timer.release("pointer")
+    vi.advanceTimersByTime(2000)
+    timer.hold("focus")
+    expect(timer.remaining()).toBe(1000)
+    timer.release("focus")
+    vi.advanceTimersByTime(999)
+    expect(onExpire).not.toHaveBeenCalled()
+    vi.advanceTimersByTime(1)
+    expect(onExpire).toHaveBeenCalledTimes(1)
+  })
+
+  it("stays held until EVERY reason is released (hover and keyboard focus overlap)", () => {
+    const onExpire = vi.fn()
+    const timer = createToastTimer(1000, onExpire)
+    timer.hold("pointer")
+    timer.hold("focus")
+    timer.hold("focus")
+    timer.release("pointer")
+    vi.advanceTimersByTime(5000)
+    expect(onExpire).not.toHaveBeenCalled()
+    timer.release("unknown")
+    vi.advanceTimersByTime(5000)
+    expect(onExpire).not.toHaveBeenCalled()
+    timer.release("focus")
+    vi.advanceTimersByTime(1000)
+    expect(onExpire).toHaveBeenCalledTimes(1)
+  })
+
+  it("never fires after cancel, released or not", () => {
+    const onExpire = vi.fn()
+    const timer = createToastTimer(1000, onExpire)
+    vi.advanceTimersByTime(400)
+    timer.cancel()
+    expect(timer.remaining()).toBe(600)
+    timer.release("pointer")
+    vi.advanceTimersByTime(5000)
+    expect(onExpire).not.toHaveBeenCalled()
+    const held = createToastTimer(1000, onExpire)
+    held.hold("focus")
+    held.cancel()
+    held.release("focus")
+    vi.advanceTimersByTime(5000)
+    expect(onExpire).not.toHaveBeenCalled()
+  })
+
+  it("expires at once for a non-positive duration", () => {
+    const onExpire = vi.fn()
+    const timer = createToastTimer(-50, onExpire)
+    expect(timer.remaining()).toBe(0)
+    vi.advanceTimersByTime(0)
+    expect(onExpire).toHaveBeenCalledTimes(1)
+  })
+
+  it("runs on an injected clock and clears the handle it scheduled", () => {
+    let now = 100
+    const pending = new Map<number, () => void>()
+    let nextHandle = 0
+    const cleared: unknown[] = []
+    const scheduled: number[] = []
+    const clock: ToastClock = {
+      now: () => now,
+      setTimeout: (callback, ms) => {
+        nextHandle += 1
+        pending.set(nextHandle, callback)
+        scheduled.push(ms)
+        return nextHandle
+      },
+      clearTimeout: (handle) => {
+        cleared.push(handle)
+        pending.delete(handle as number)
+      },
+    }
+    const onExpire = vi.fn()
+    const timer = createToastTimer(2800, onExpire, clock)
+    expect(scheduled).toEqual([2800])
+    now += 800
+    timer.hold("pointer")
+    expect(cleared).toEqual([1])
+    expect(pending.size).toBe(0)
+    now += 10_000
+    timer.release("pointer")
+    expect(scheduled).toEqual([2800, 2000])
+    now += 2000
+    pending.get(2)?.()
+    expect(onExpire).toHaveBeenCalledTimes(1)
+    expect(timer.remaining()).toBe(0)
+  })
+})