Controller

The controller is what createCloudlet() and useCloudlet() return. Its type is ReactCloudletController, that is CloudletController<ReactNode, AbortSignal>. Every method has a stable reference, so you can pass cloudlet.show around or hand subscribe to React directly. Expected refusals are returned as results, never thrown: check status instead of wrapping calls in try.

show

show(spec: ReactNotificationSpec): AdmissionResult

ReactNotificationSpec is NotificationSpec<ReactNode>: the content of a notification plus its identity. Only title is required. A new notification goes on top of the stack; Notifications & time shows each field in use.

With exactOptionalPropertyTypes, leave a field out rather than passing undefined.

AdmissionResult

AdmissionRejection, checked in this order:

Deduplication happens before the capacity check, so a duplicate is still counted when the stack is full.

update

update(handle: NotificationHandle, patch: ReactNotificationPatch): MutationResult

ReactNotificationPatch is NotificationPatch<ReactNode>. A field you leave out keeps its value; null removes optional content. id and dedupeKey cannot change.

A rejected patch changes nothing, not even its valid fields. A patch that changes nothing returns unchanged.

MutationResult

update, dismiss and acknowledgeOverflow return the same union.

MutationRejection. A handle is checked in this order: controller disposed, a real handle, this controller's handle, still alive.

The first three handle reasons are also exported together as HandleRejection.

getHandle

getHandle(id: string): NotificationHandle | undefined

Returns the handle of the live notification with this ID, or undefined: for an unknown, empty or non-string ID, and always after dispose(). It never creates or opens anything. A handle is tied to one appearance of a notification: after it closes, the same ID can be used again and gets a new handle.

track

track<T>(source: PromiseLike<T> | ReactOperationFactory<T>, options: ReactTrackOptions<T>): OperationHandle<T>

Shows a loading notification with the pending content, then replaces it with the result. The source is a promise you already have, or a factory (context) => T | PromiseLike<T> that Cloudlet calls once per attempt with a ReactOperationContext: signal (an AbortSignal), token and attempt (1, 2, …). Only a factory can be retried. A source that is neither a function nor a thenable throws a TypeError. Operations & cancellation walks through it.

ReactTrackOptions<T> is TrackOptions<T, ReactNode, AbortSignal>:

NotificationContent is the part of a spec that describes what is shown: title, description, icon, progress, action, announcementPriority, duration and attention, with the meaning they have in show. Tracked operations cannot have a dedupeKey.

A mapping function that throws or returns invalid content gives a safe fallback title from messages and a mapper-error diagnostic. The business operation runs even when the notification is rejected, and nothing about the notification ever changes its result.

OperationHandle

The handle is itself the first attempt: its token, attempt and result never change.

Each new attempt returns its own OperationAttempt<T>: token, attempt and result. Retrying never creates a new notification; after the notification closed, the attempt runs without one.

AttemptStartResult<T>:

CancelResult:

OperationSnapshot

dismiss

dismiss(handle: NotificationHandle): MutationResult

Closes the notification at once, with the close reason programmatic. A late result or animation can never bring it back. Dismissing a tracked operation's notification does not cancel the operation.

clear

clear(): ClearResult

Closes every notification (close reason clear) and collapses the Island. The missed count stays until acknowledgeOverflow().

requestFocus

requestFocus(target?: FocusTarget): FocusResult

Arrival and auto-open never move focus; this is the explicit way to do it, for example from a keyboard shortcut. requested means the command was accepted: the renderer moves focus after its next commit, not synchronously.

FocusTarget, default { kind: 'anchor' }:

FocusResult:

acknowledgeOverflow

acknowledgeOverflow(): MutationResult

Resets the missed count shown on the badge and in the Island: applied, unchanged when there was nothing to acknowledge, or rejected with disposed. It does not touch the notifications.

getSnapshot and getServerSnapshot

getSnapshot(): ControllerSnapshot<ReactNode>

getServerSnapshot(): ControllerSnapshot<ReactNode>

getSnapshot returns the same readonly object until something observable changes, so it can feed useSyncExternalStore directly. getServerSnapshot always returns one stable empty snapshot, for the server render and the first hydration render.

import { useSyncExternalStore } from 'react';
import { useCloudlet } from '@cloudlet/toast';

export function NotificationCount() {
  const cloudlet = useCloudlet();
  const snapshot = useSyncExternalStore(cloudlet.subscribe, cloudlet.getSnapshot, cloudlet.getServerSnapshot);
  return <span>{snapshot.notifications.length} open</span>;
}

ControllerSnapshot:

Each NotificationSnapshot is described on Types.

subscribe and onEvent

subscribe(listener: () => void): Unsubscribe

onEvent(listener: (event: SemanticEvent) => void): Unsubscribe

subscribe is called after every committed change; read the new state with getSnapshot(). onEvent receives what happened, in order, after the snapshot listeners. Neither replays the past: read the snapshot when you subscribe. Calling the returned Unsubscribe twice is harmless. A listener that throws becomes a listener-error diagnostic and the others still run.

import { createCloudlet } from '@cloudlet/toast';

const cloudlet = createCloudlet();
const stop = cloudlet.onEvent((event) => {
  if (event.type === 'closed') console.info(event.handle.id, event.reason);
});

Every SemanticEvent has the EventBase fields controller, sequence (a growing local number) and at (monotonic milliseconds, not wall-clock time), plus:

Events carry no business values or errors. Opening and collapsing the Island is not an event: read snapshot.island.

dispose

dispose(): void

Ends the controller. Every open notification closes with the reason dispose (its onClose runs), the disposed event is delivered, then all listeners are released. Afterwards show, update, clear and the other commands return disposed, and getSnapshot() returns a stable empty snapshot with disposed: true. Calling it again does nothing. Running operations are not aborted: their result still settles.

NotificationController

NotificationController is the controller without track, for code that only shows notifications. Any controller can be passed where it is expected.

import type { ReactNode } from 'react';
import { createCloudlet, type NotificationController } from '@cloudlet/toast';

export function notifySaved(notifications: NotificationController<ReactNode>) {
  return notifications.show({ title: 'Saved', kind: 'success' });
}

notifySaved(createCloudlet());

The generic form is CloudletController<Slot, Signal>: Slot is the type of rich content (ReactNode here) and Signal the abort signal operations receive (AbortSignal here).