@leavepulse/ui 0.43.4 → 0.44.0

package/src/composables/useFormDraft.ts

@@ -69,9 +69,16 @@ export interface UseFormDraftOptions<T> {
 }
 
 export interface UseFormDraft<T> {
-  /** A draft was found for this key, and has not been restored or discarded. */
+  /**
+   * A draft was found for this key, and has not been restored or discarded.
+   * Only a draft found on reading counts: the writes this composable makes as
+   * the user types never raise it. While it is up, automatic writes are held
+   * back, so the draft on offer cannot be overwritten by the form's own state
+   * (an async load of the record, or typing past the banner) before the user
+   * has answered.
+   */
   hasDraft: Ref<boolean>
-  /** When that draft was written, ISO-8601, or `null` when there is none. */
+  /** When the found draft was written, ISO-8601, or `null` when there is none. */
   savedAt: Ref<string | null>
   /**
    * The stored value, or `null`. Reading does not apply it — the caller decides
@@ -80,7 +87,7 @@ export interface UseFormDraft<T> {
   read: () => T | null
   /** Forget the draft. Call after applying it, and after a successful save. */
   discard: () => void
-  /** Write now, ignoring `dirty`. For "save and come back to this later". */
+  /** Write now, ignoring `dirty` and a pending draft. For "save and come back to this later". */
   save: () => void
 }
 
@@ -132,6 +139,17 @@ export function useFormDraft<T>(options: UseFormDraftOptions<T>): UseFormDraft<T
     return String(toValue(options.key) || "").trim()
   }
 
+  // An envelope still worth offering, or null. No side effects: the key watcher
+  // only looks, and `read` decides what to clear.
+  function fresh(parsed: DraftEnvelope<T> | null): boolean {
+    if (!parsed || parsed.version !== ENVELOPE_VERSION) return false
+    if (maxAge <= 0) return true
+    // NaN when the stamp is unreadable, and NaN > maxAge is false — an
+    // unreadable stamp is treated as "no idea how old", which errs towards
+    // offering the draft rather than throwing away somebody's typing.
+    return !(Date.now() - Date.parse(parsed.savedAt) > maxAge)
+  }
+
   function read(): T | null {
     const store = storage()
     const key = currentKey()
@@ -145,20 +163,10 @@ export function useFormDraft<T>(options: UseFormDraftOptions<T>): UseFormDraft<T
     if (!raw) return null
     try {
       const parsed = JSON.parse(raw) as DraftEnvelope<T>
-      if (!parsed || parsed.version !== ENVELOPE_VERSION) {
+      if (!fresh(parsed)) {
         discard()
         return null
       }
-      if (maxAge > 0) {
-        const age = Date.now() - Date.parse(parsed.savedAt)
-        // NaN when the stamp is unreadable, and NaN > maxAge is false — an
-        // unreadable stamp is treated as "no idea how old", which errs towards
-        // offering the draft rather than throwing away somebody's typing.
-        if (age > maxAge) {
-          discard()
-          return null
-        }
-      }
       return parsed.value
     } catch {
       // Corrupt or hand-edited. Nothing to rescue, and leaving it means asking
@@ -172,13 +180,12 @@ export function useFormDraft<T>(options: UseFormDraftOptions<T>): UseFormDraft<T
     const store = storage()
     const key = currentKey()
     if (!store || !key) return
-    const stamp = new Date().toISOString()
     try {
       store.setItem(
         key,
         JSON.stringify({
           version: ENVELOPE_VERSION,
-          savedAt: stamp,
+          savedAt: new Date().toISOString(),
           value,
         } satisfies DraftEnvelope<T>),
       )
@@ -187,8 +194,6 @@ export function useFormDraft<T>(options: UseFormDraftOptions<T>): UseFormDraft<T
       // unharmed; it simply has no safety net.
       return
     }
-    hasDraft.value = true
-    savedAt.value = stamp
   }
 
   function discard() {
@@ -226,7 +231,7 @@ export function useFormDraft<T>(options: UseFormDraftOptions<T>): UseFormDraft<T
       if (!raw) return
       try {
         const parsed = JSON.parse(raw) as DraftEnvelope<T>
-        if (parsed?.version !== ENVELOPE_VERSION) return
+        if (!fresh(parsed)) return
         hasDraft.value = true
         savedAt.value = parsed.savedAt
       } catch {
@@ -240,7 +245,7 @@ export function useFormDraft<T>(options: UseFormDraftOptions<T>): UseFormDraft<T
   watch(
     () => [toValue(options.value), toValue(options.dirty), toValue(options.disabled)],
     ([value, dirty, disabled]) => {
-      if (disabled) return
+      if (disabled || hasDraft.value) return
       // `dirty` unset means "every change is worth keeping"; the option exists
       // so a form that knows it is untouched leaves no trace.
       if (options.dirty !== undefined && !dirty) return

package/src/composables/useHotkeys.ts

@@ -1,4 +1,14 @@
-import { computed, onBeforeUnmount, onMounted, shallowReactive, type MaybeRefOrGetter, toValue } from "vue"
+import {
+  computed,
+  getCurrentInstance,
+  onBeforeUnmount,
+  onMounted,
+  ref,
+  shallowReactive,
+  toValue,
+  type MaybeRefOrGetter,
+} from "vue"
+import { topModalElement } from "../components/modalDepth"
 
 /*
  * One keydown listener over a registry of bindings, so a shortcut is declared
@@ -39,6 +49,16 @@ export interface HotkeyBinding {
    * something there — Escape, and the palette the user reaches from anywhere.
    */
   allowInInput?: boolean
+  /**
+   * Runs even while an overlay owns the keyboard. By default a binding declared
+   * outside the topmost modal stays quiet while that modal is open, and an
+   * Escape binding declared outside the topmost dismissable layer (dialog,
+   * popover, menu) leaves Escape to that layer, so a page-level shortcut can
+   * neither act behind a dialog nor stop the dialog from closing.
+   */
+  overLayers?: boolean
+  /** Set `false` to ignore auto-repeat while the key is held. */
+  repeat?: boolean
   /**
    * How the key reference lists this binding while it is mounted. Bindings
    * without it still work, they just stay out of `activeShortcuts`.
@@ -87,12 +107,22 @@ export const isAppleKeyboard =
   typeof navigator !== "undefined"
   && /Mac|iPhone|iPad|iPod/.test(navigator.platform || "")
 
+/**
+ * `isAppleKeyboard` for render paths: false until mounted, so the server and
+ * the hydrating client print the same label and the client switches after.
+ */
+export function useAppleKeyboard() {
+  const apple = ref(false)
+  onMounted(() => (apple.value = isAppleKeyboard))
+  return apple
+}
+
 /**
  * The symbol to print for a modifier on this platform. Bindings treat Ctrl and
  * Meta as one modifier, so only the label may differ — never the binding.
  */
-export function appleModifierLabel(key: string): string {
-  if (!isAppleKeyboard) return key
+export function appleModifierLabel(key: string, apple = isAppleKeyboard): string {
+  if (!apple) return key
   if (key === "Ctrl") return "⌘"
   if (key === "Alt") return "⌥"
   return key
@@ -123,13 +153,22 @@ function isTextEntry(target: EventTarget | null): boolean {
   return false
 }
 
-function matches(event: KeyboardEvent, binding: HotkeyBinding): boolean {
+const MODIFIER_KEYS = new Set(["control", "meta", "shift", "alt"])
+
+export function matchesHotkey(event: KeyboardEvent, binding: HotkeyBinding): boolean {
+  const key = binding.key.toLowerCase()
   const ctrlHeld = event.ctrlKey || event.metaKey
-  if (ctrlHeld !== Boolean(binding.ctrl)) return false
-  if (event.shiftKey !== Boolean(binding.shift)) return false
-  if (event.altKey !== Boolean(binding.alt)) return false
+  const wantsCtrl = Boolean(binding.ctrl) || key === "control" || key === "meta"
+  if (ctrlHeld !== wantsCtrl) return false
+  // Shift is part of typing a symbol on most layouts ("?", "+"), so a binding
+  // on a symbol that does not mention Shift accepts it either way.
+  const symbol = key.length === 1 && key.toLowerCase() === key.toUpperCase()
+  const shiftFree = key === "shift" || (binding.shift === undefined && symbol)
+  if (!shiftFree && event.shiftKey !== Boolean(binding.shift)) return false
+  if (key !== "alt" && event.altKey !== Boolean(binding.alt)) return false
+  if (MODIFIER_KEYS.has(key)) return event.key.toLowerCase() === key
   return (
-    event.key.toLowerCase() === binding.key.toLowerCase()
+    event.key.toLowerCase() === key
     || (binding.code !== undefined && event.code === binding.code)
   )
 }
@@ -165,11 +204,23 @@ interface MountedHotkeys {
   enabled: MaybeRefOrGetter<boolean> | undefined
   priority: MaybeRefOrGetter<number> | undefined
   order: number
+  /** Where the declaring component sits in the DOM, for the overlay check. */
+  host: () => Node | null
 }
 
-const mounted = shallowReactive(new Set<MountedHotkeys>())
-let mountOrder = 0
-let listening = false
+// Pinned to a global symbol for the same reason as the toast queue: a barrel
+// and a deep import must not end up with two registries and two listeners.
+const STATE_KEY = Symbol.for("@leavepulse/ui:hotkeys")
+type GlobalWithHotkeys = typeof globalThis & {
+  [STATE_KEY]?: { mounted: Set<MountedHotkeys>; order: number; listening: boolean }
+}
+const g = globalThis as GlobalWithHotkeys
+const state = (g[STATE_KEY] ??= {
+  mounted: shallowReactive(new Set<MountedHotkeys>()),
+  order: 0,
+  listening: false,
+})
+const mounted = state.mounted
 
 function inScope(target: EventTarget | null, scope: MountedHotkeys["scope"]): boolean {
   const el = toValue(scope)
@@ -178,17 +229,32 @@ function inScope(target: EventTarget | null, scope: MountedHotkeys["scope"]): bo
   return !!node && (el === node || el.contains(node))
 }
 
+function topLayer(): Element | null {
+  const layers = document.querySelectorAll("[data-dismissable-layer]")
+  return layers[layers.length - 1] ?? null
+}
+
+function insideOf(entry: MountedHotkeys, layer: Element): boolean {
+  const scope = toValue(entry.scope)
+  const node = scope ?? entry.host()
+  return !!node && layer.contains(node)
+}
+
 function onKeydown(event: KeyboardEvent) {
-  if (event.isComposing) return
+  if (event.isComposing || event.defaultPrevented) return
   const inTextEntry = isTextEntry(event.target)
+  const blocker = event.key === "Escape" ? topLayer() : topModalElement()
   const entries = [...mounted].sort(
     (a, b) => Number(toValue(b.priority) || 0) - Number(toValue(a.priority) || 0) || b.order - a.order,
   )
   for (const entry of entries) {
     if (toValue(entry.enabled) === false || !inScope(event.target, entry.scope)) continue
+    const covered = !!blocker && !insideOf(entry, blocker)
     for (const binding of entry.read()) {
       if (inTextEntry && !binding.allowInInput) continue
-      if (!matches(event, binding)) continue
+      if (event.repeat && binding.repeat === false) continue
+      if (covered && !binding.overLayers) continue
+      if (!matchesHotkey(event, binding)) continue
       if (binding.handler(event) === false) continue
       event.preventDefault()
       return
@@ -200,25 +266,30 @@ export function useHotkeys(
   bindings: MaybeRefOrGetter<HotkeyBinding[]>,
   options: UseHotkeysOptions = {},
 ) {
+  const instance = getCurrentInstance()
   const entry: MountedHotkeys = {
     read: () => toValue(bindings),
     scope: options.scope,
     enabled: options.enabled,
     priority: options.priority,
-    order: ++mountOrder,
+    order: ++state.order,
+    host: () => {
+      const el = instance?.vnode.el
+      return el instanceof Node ? el : null
+    },
   }
   onMounted(() => {
     mounted.add(entry)
-    if (!listening) {
+    if (!state.listening) {
       window.addEventListener("keydown", onKeydown)
-      listening = true
+      state.listening = true
     }
   })
   onBeforeUnmount(() => {
     mounted.delete(entry)
-    if (!mounted.size && listening) {
+    if (!mounted.size && state.listening) {
       window.removeEventListener("keydown", onKeydown)
-      listening = false
+      state.listening = false
     }
   })
 }

package/src/composables/useInputFilter.ts

@@ -18,6 +18,12 @@ import { computed, type MaybeRefOrGetter, toValue } from "vue"
  *
  * A bare string pattern is treated as a full-string match (anchored), mirroring
  * the native HTML `pattern` attribute.
+ *
+ * Composition cannot be vetoed (its `beforeinput` is not cancelable), and on
+ * Android most keyboards compose ordinary typing, so `beforeinput` alone left
+ * `restrict` doing nothing there. `onInput` and `onCompositionEnd` clean up
+ * whatever got through — composed text, a drop, an autocorrect replacement —
+ * keeping the caret where it was. Bind `onInput` BEFORE reading the value.
  */
 
 export interface UseInputFilterOptions {
@@ -27,31 +33,57 @@ export interface UseInputFilterOptions {
   pattern?: MaybeRefOrGetter<RegExp | string | undefined>
 }
 
-function toAnchored(p: RegExp | string): RegExp {
-  if (p instanceof RegExp) {
-    // Re-anchor so `pattern` validates the whole string, like HTML's attribute.
-    const src = p.source.replace(/^\^/, "").replace(/\$$/, "")
-    return new RegExp(`^(?:${src})$`, p.flags.replace(/[gy]/g, ""))
-  }
+/**
+ * Anchor a pattern to the whole string, like HTML's `pattern` attribute. The
+ * source is wrapped, never edited: anchors the caller wrote stay valid inside
+ * the group, while trimming a trailing `$` broke an escaped `\$` into an
+ * unterminated group.
+ */
+export function anchorPattern(p: RegExp | string): RegExp {
+  if (p instanceof RegExp) return new RegExp(`^(?:${p.source})$`, p.flags.replace(/[gy]/g, ""))
   return new RegExp(`^(?:${p})$`)
 }
 
+// Strip g/y so lastIndex can't leak state across .test() calls.
+function charTester(charRe: RegExp): (ch: string) => boolean {
+  const re = new RegExp(charRe.source, charRe.flags.replace(/[gy]/g, ""))
+  return (ch) => re.test(ch)
+}
+
 /** Does a string contain only restrict-allowed characters? */
 function allAllowed(text: string, charRe: RegExp): boolean {
-  // Strip g/y so lastIndex can't leak state across .test() calls, then reuse
-  // the one instance per char (tested by code point, so surrogate pairs hold).
-  const re = new RegExp(charRe.source, charRe.flags.replace(/[gy]/g, ""))
+  const ok = charTester(charRe)
+  // By code point, so surrogate pairs hold.
   for (const ch of text) {
-    if (!re.test(ch)) return false
+    if (!ok(ch)) return false
   }
   return true
 }
 
+/**
+ * `text` with every disallowed character removed, and where `caret` lands once
+ * the characters before it that were removed are gone.
+ */
+export function stripDisallowed(text: string, charRe: RegExp, caret = text.length): { text: string; caret: number } {
+  const ok = charTester(charRe)
+  let kept = ""
+  let at = 0
+  let offset = 0
+  for (const ch of text) {
+    if (ok(ch)) {
+      kept += ch
+      if (offset < caret) at += ch.length
+    }
+    offset += ch.length
+  }
+  return { text: kept, caret: at }
+}
+
 export function useInputFilter(options: UseInputFilterOptions = {}) {
   const restrict = computed(() => toValue(options.restrict))
   const patternRe = computed(() => {
     const p = toValue(options.pattern)
-    return p === undefined ? undefined : toAnchored(p)
+    return p === undefined ? undefined : anchorPattern(p)
   })
 
   /** True when a non-empty value fails `pattern`. Empty is treated as valid. */
@@ -68,12 +100,43 @@ export function useInputFilter(options: UseInputFilterOptions = {}) {
   function onBeforeInput(event: InputEvent): void {
     const re = restrict.value
     if (!re || event.isComposing) return
-    // Deletions / formatting carry no data to validate; let them through.
-    const data = event.data
+    // A drop or a replacement carries its text in dataTransfer, not data.
+    // Deletions / formatting carry neither; let them through.
+    const data = event.data ?? event.dataTransfer?.getData("text") ?? null
     if (data == null) return
     if (!allAllowed(data, re)) event.preventDefault()
   }
 
+  // Remove what slipped past `beforeinput`; true when the value changed.
+  function sanitize(target: EventTarget | null): boolean {
+    const re = restrict.value
+    if (!re) return false
+    if (!(target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement)) return false
+    const { text, caret } = stripDisallowed(target.value, re, target.selectionStart ?? target.value.length)
+    if (text === target.value) return false
+    target.value = text
+    try {
+      target.setSelectionRange(caret, caret)
+    } catch {
+      // Input types without a selection (number, email) cannot place a caret.
+    }
+    return true
+  }
+
+  /** Attach to `input`, ahead of whatever reads the value. */
+  function onInput(event: Event): void {
+    if ((event as InputEvent).isComposing) return
+    sanitize(event.target)
+  }
+
+  /**
+   * Attach to `compositionend`. Some browsers fire the last `input` before
+   * this, so a cleaned value is announced with a fresh `input` event.
+   */
+  function onCompositionEnd(event: CompositionEvent): void {
+    if (sanitize(event.target)) event.target?.dispatchEvent(new Event("input", { bubbles: true }))
+  }
+
   /**
    * Attach to `paste`. Veto the paste if any pasted char is disallowed, rather
    * than silently dropping part of it — partial pastes confuse more than help.
@@ -85,5 +148,5 @@ export function useInputFilter(options: UseInputFilterOptions = {}) {
     if (text && !allAllowed(text, re)) event.preventDefault()
   }
 
-  return { isInvalid, onBeforeInput, onPaste, patternRe, restrict }
+  return { isInvalid, onBeforeInput, onInput, onCompositionEnd, onPaste, patternRe, restrict }
 }

package/src/composables/useLpConfig.ts

@@ -0,0 +1,87 @@
+import {
+  computed,
+  inject,
+  provide,
+  toValue,
+  type App,
+  type Component,
+  type ComputedRef,
+  type InjectionKey,
+  type MaybeRefOrGetter,
+} from "vue"
+
+/*
+ * App-wide kit configuration, said once at the root instead of on every call
+ * site: the router link component that navigation pieces render, and the text
+ * the kit would otherwise hard-code in English.
+ *
+ * Labels are grouped by scope (one scope per component, e.g. "lightbox",
+ * "toast") so each component owns its own keys and defaults. The precedence is
+ * always: the component's own `labels` prop, then the nearest config, then the
+ * component's English defaults.
+ */
+export type LabelScope = Record<string, string>
+
+export interface LpConfig {
+  /** Component rendered for internal links (RouterLink, NuxtLink). Plain `<a>` when unset. */
+  linkComponent?: Component | string
+  /** Text overrides by scope: `{ lightbox: { previous: "Back" } }`. */
+  labels?: Partial<Record<string, Partial<LabelScope>>>
+}
+
+export const LP_CONFIG: InjectionKey<MaybeRefOrGetter<LpConfig>> = Symbol.for("lp-config")
+
+/** Provide kit configuration to every component below the caller. */
+export function provideLpConfig(config: MaybeRefOrGetter<LpConfig>): void {
+  provide(LP_CONFIG, layered(inject(LP_CONFIG, {}), config))
+}
+
+/** Install the configuration app-wide: `app.use(lpConfig({ ... }))`. */
+export function lpConfig(config: MaybeRefOrGetter<LpConfig>) {
+  return {
+    install: (app: App) => {
+      const outer = app.runWithContext(() => inject(LP_CONFIG, {}))
+      app.provide(LP_CONFIG, layered(outer, config))
+    },
+  }
+}
+
+/*
+ * A nested config refines the one above it rather than replacing it: an app's
+ * own labels must not drop the link component a framework plugin provided.
+ */
+function layered(outer: MaybeRefOrGetter<LpConfig>, inner: MaybeRefOrGetter<LpConfig>): () => LpConfig {
+  return () => mergeConfig(toValue(outer), toValue(inner))
+}
+
+export function mergeConfig(outer: LpConfig, inner: LpConfig): LpConfig {
+  const labels: Partial<Record<string, Partial<LabelScope>>> = { ...outer.labels }
+  for (const [scope, values] of Object.entries(inner.labels ?? {})) {
+    labels[scope] = { ...labels[scope], ...values }
+  }
+  return { ...outer, ...inner, linkComponent: inner.linkComponent ?? outer.linkComponent, labels }
+}
+
+export function useLpConfig(): ComputedRef<LpConfig> {
+  const config = inject(LP_CONFIG, {})
+  return computed(() => toValue(config))
+}
+
+/**
+ * The labels a component renders: its own `labels` prop over the configured
+ * scope over its defaults.
+ */
+export function useLabels<T extends LabelScope>(
+  scope: string,
+  defaults: T,
+  own?: () => Partial<T> | undefined,
+): ComputedRef<T> {
+  const config = useLpConfig()
+  return computed(() => ({ ...defaults, ...config.value.labels?.[scope], ...own?.() }) as T)
+}
+
+/** The link component to render for an internal destination. */
+export function useLinkComponent(): ComputedRef<Component | string> {
+  const config = useLpConfig()
+  return computed(() => config.value.linkComponent ?? "a")
+}

package/src/composables/useRovingFocus.ts

@@ -1,5 +1,7 @@
 import { computed, ref, watch, type MaybeRefOrGetter, toValue } from "vue"
 
+const NON_TEXT_INPUTS = new Set(["checkbox", "radio", "button", "submit", "reset", "range", "color", "file", "image"])
+
 /*
  * Arrow-key navigation over a list, with a roving tabindex.
  *
@@ -152,7 +154,16 @@ export function useRovingFocus(
     }
   }
 
+  function isTextEntry(target: EventTarget | null): boolean {
+    if (!(target instanceof HTMLElement)) return false
+    if (target.isContentEditable || target instanceof HTMLTextAreaElement || target instanceof HTMLSelectElement) return true
+    return target instanceof HTMLInputElement && !NON_TEXT_INPUTS.has(target.type)
+  }
+
   function onKeydown(event: KeyboardEvent) {
+    // A field inside a row (an inline rename, a filter) owns its keys: the list
+    // taking letters for typeahead or Space for activation made it untypeable.
+    if (event.isComposing || isTextEntry(event.target)) return
     const vertical = orientation === "vertical" || orientation === "both"
     const horizontal = orientation === "horizontal" || orientation === "both"
 

package/src/composables/useTilt.ts

@@ -1,5 +1,5 @@
 import { useReducedMotion } from "motion-v"
-import { computed, ref, type ComputedRef, type CSSProperties, type Ref } from "vue"
+import { computed, ref, toValue, type ComputedRef, type CSSProperties, type MaybeRefOrGetter, type Ref } from "vue"
 
 /*
  * useTilt — pointer-reactive 3D tilt for a "tactile" surface (a card, a tile, a
@@ -35,10 +35,8 @@ export interface UseTilt {
   active: Ref<boolean>
 }
 
-export function useTilt(options: UseTiltOptions = {}): UseTilt {
-  const max = options.max ?? 10
-  const lift = options.lift ?? 8
-  const scale = options.scale ?? 1.03
+export function useTilt(source: MaybeRefOrGetter<UseTiltOptions> = {}): UseTilt {
+  const options = computed(() => toValue(source))
   const reduceMotion = useReducedMotion()
 
   const active = ref(false)
@@ -72,6 +70,7 @@ export function useTilt(options: UseTiltOptions = {}): UseTilt {
     // rotateX tips away from the pointer's vertical position; rotateY toward its
     // horizontal one. Only tilt while active so it rests flat when the pointer
     // leaves (nx/ny are already zeroed on leave).
+    const { max = 10, lift = 8, scale = 1.03 } = options.value
     const rx = active.value ? -ny.value * max : 0
     const ry = active.value ? nx.value * max : 0
     const z = active.value ? lift : 0
@@ -86,7 +85,7 @@ export function useTilt(options: UseTiltOptions = {}): UseTilt {
   })
 
   const glareStyle = computed<CSSProperties>(() => {
-    if (!options.glare || reduceMotion.value || !active.value) {
+    if (!options.value.glare || reduceMotion.value || !active.value) {
       return { opacity: 0 }
     }
     // Bright spot tracks the pointer; map [-1,1] → [0%,100%].

package/src/composables/useToast.ts

@@ -11,6 +11,9 @@ export interface ToastAction {
 
 export interface ToastItem {
   id: number
+  /** Bumped when a toast with the same `key` replaces this one in place. */
+  rev: number
+  key?: string
   title?: string
   message: string
   variant: ToastVariant
@@ -23,6 +26,12 @@ export interface ToastItem {
 }
 
 export interface ToastOptions {
+  /**
+   * A toast with the same key replaces the one on screen instead of stacking
+   * beside it: "Saved" ten times is one toast, and a progress toast can turn
+   * into its result.
+   */
+  key?: string
   title?: string
   duration?: number
   actions?: ToastAction[]
@@ -48,10 +57,12 @@ function push(
   message: string,
   options: ToastOptions = {},
 ): number {
-  const id = state.nextId++
+  // A server render has no one to show it to, and the queue would outlive the
+  // request and surface in the next visitor's page.
+  if (typeof window === "undefined") return -1
   const duration = options.duration ?? DEFAULT_DURATION
-  const item: ToastItem = {
-    id,
+  const fields = {
+    key: options.key,
     title: options.title,
     message,
     variant,
@@ -61,14 +72,54 @@ function push(
     onClick: options.onClick,
   }
 
+  const same = options.key === undefined ? -1 : queue.findIndex((t) => t.key === options.key)
+  const existing = queue[same]
+  if (existing) {
+    queue.splice(same, 1, { ...fields, id: existing.id, rev: existing.rev + 1 })
+    return existing.id
+  }
+
+  const id = state.nextId++
   // Cap the active count: drop the oldest beyond the limit.
   const overflow = queue.length - (MAX_ACTIVE - 1)
   if (overflow > 0) queue.splice(0, overflow)
-  queue.push(item)
+  queue.push({ ...fields, id, rev: 0 })
 
   return id
 }
 
+export interface ToastPromiseMessages<T> {
+  loading: string
+  success: string | ((value: T) => string)
+  error: string | ((error: unknown) => string)
+}
+
+let promiseKey = 0
+
+/**
+ * One toast that follows a promise: a persistent "loading" toast that turns
+ * into the success or error toast when it settles. Returns the promise itself.
+ */
+function promise<T>(
+  task: Promise<T>,
+  messages: ToastPromiseMessages<T>,
+  options: ToastOptions = {},
+): Promise<T> {
+  const key = options.key ?? `@leavepulse/ui:promise-${promiseKey++}`
+  push("info", messages.loading, { ...options, key, duration: 0, actions: undefined })
+  task.then(
+    (value) => {
+      const text = typeof messages.success === "function" ? messages.success(value) : messages.success
+      push("success", text, { ...options, key })
+    },
+    (error: unknown) => {
+      const text = typeof messages.error === "function" ? messages.error(error) : messages.error
+      push("error", text, { ...options, key })
+    },
+  )
+  return task
+}
+
 function dismiss(id: number): void {
   const i = queue.findIndex((t) => t.id === id)
   if (i !== -1) queue.splice(i, 1)
@@ -86,6 +137,7 @@ export function useToast() {
     success: (message: string, o?: ToastOptions) => push("success", message, o),
     warning: (message: string, o?: ToastOptions) => push("warning", message, o),
     error: (message: string, o?: ToastOptions) => push("error", message, o),
+    promise,
     /** Low-level push for bridges (e.g. @leavepulse/ui-sdk apiError). */
     push,
     dismiss,