@ultimat3/ui 19.3.3 → 20.0.0

package/src/form/form-binding.ts

@@ -17,10 +17,18 @@ import {
   distributeIssues,
   errorOf,
   type FormState,
+  firstInvalidField,
   IDLE_FORM_STATE,
   messagesOf,
   NO_FORM_ERRORS,
 } from './form-state';
+import {
+  type FormTouch,
+  markDirty,
+  markTouched,
+  NO_FORM_TOUCH,
+  sameFieldValue,
+} from './form-touch';
 
 export interface FormBindingOptions<TValues, TResult> {
   /**
@@ -40,6 +48,17 @@ export interface FormBindingOptions<TValues, TResult> {
   readonly schema?: FormSchema | undefined;
   /** Called on every transition — how a reactive shell mirrors the state into a signal. */
   readonly onState?: ((state: FormState<TResult>) => void) | undefined;
+  /**
+   * The values the form OPENED with, keyed by the same field paths — what `edit()` compares
+   * against to decide dirtiness. A create form passes nothing, and every non-blank value is then a
+   * change. A path missing from this map has a baseline of `undefined`, which `sameFieldValue`
+   * treats as equal to an empty control.
+   *
+   * The baseline is fixed for the life of the binding: a form that stays mounted after a save and
+   * wants the saved values as its new baseline builds a new binding, because this one never sees
+   * what the user typed and cannot invent one.
+   */
+  readonly initial?: Readonly<Record<string, unknown>> | undefined;
 }
 
 export interface FormBinding<TValues, TResult> {
@@ -49,6 +68,20 @@ export interface FormBinding<TValues, TResult> {
   readonly errorFor: (path: string) => string | undefined;
   /** Every message bound to one path, when a form renders more than one. */
   readonly messagesFor: (path: string) => readonly string[];
+  /**
+   * A submit is in flight. The one value that reaches BOTH the submit control (`<Button loading>`)
+   * and the form (`<Form busy>`) — one derivation, so a control can be busy and its form not.
+   */
+  readonly pending: () => boolean;
+  /**
+   * The first declared field a failed submit put an error on. What `<Form invalidField>` focuses:
+   * the thing that has to be fixed, rather than the summary that describes it.
+   */
+  readonly firstInvalidField: () => string | undefined;
+  /** The user left a control. */
+  readonly touch: (path: string) => void;
+  /** The user changed a control. Dirtiness is decided against `initial`, never by the caller. */
+  readonly edit: (path: string, value: unknown) => void;
   readonly reset: () => void;
 }
 
@@ -71,12 +104,35 @@ export function createFormBinding<TValues, TResult>(
 ): FormBinding<TValues, TResult> {
   const fields = declaredFields(options.fields);
   let state: FormState<TResult> = IDLE_FORM_STATE;
+  let touch: FormTouch = NO_FORM_TOUCH;
   let inFlight: Promise<FormState<TResult>> | null = null;
 
-  const publish = (next: FormState<TResult>): FormState<TResult> => {
-    state = next;
-    options.onState?.(next);
-    return next;
+  /**
+   * A transition names the submit's own members; `touched`/`dirty` are added here, from the one
+   * place that owns them. Spelling the parameter as the whole `FormState` would let a transition
+   * carry a stale pair — the exact drift `publishTouch` exists to prevent.
+   */
+  const publish = (next: Omit<FormState<TResult>, keyof FormTouch>): FormState<TResult> => {
+    state = { ...next, touched: touch.touched, dirty: touch.dirty };
+    options.onState?.(state);
+    return state;
+  };
+
+  /**
+   * The value this field opened with. `Object.hasOwn`, never the read alone: `initial` is the app's
+   * own object, so `initial['constructor']` answers the `Object` FUNCTION where an absent key must
+   * answer `undefined` — and that field would then read as permanently changed.
+   */
+  const baseline = (path: string): unknown => {
+    const initial = options.initial;
+    return initial !== undefined && Object.hasOwn(initial, path) ? initial[path] : undefined;
+  };
+
+  /** Progress through the form is not a transition, so it publishes without disturbing `status`. */
+  const publishTouch = (next: FormTouch): void => {
+    if (next === touch) return;
+    touch = next;
+    publish(state);
   };
 
   const failed = (issues: readonly FormIssue[]): FormState<TResult> =>
@@ -102,6 +158,9 @@ export function createFormBinding<TValues, TResult>(
 
     try {
       const result = await options.submit(values);
+      // The server accepted what the form held, so there is nothing left to lose. `touched` stays:
+      // the user has still visited those fields, and a hint that vanishes on save is a flicker.
+      touch = { touched: touch.touched, dirty: NO_FORM_TOUCH.dirty };
       return publish({ status: 'succeeded', ...NO_FORM_ERRORS, result, issues: [] });
     } catch (rejection) {
       return failed(issuesFromRejection(rejection));
@@ -121,7 +180,13 @@ export function createFormBinding<TValues, TResult>(
     },
     errorFor: (path) => errorOf(state, path),
     messagesFor: (path) => messagesOf(state, path),
+    pending: () => state.status === 'submitting',
+    firstInvalidField: () => firstInvalidField(state, fields),
+    touch: (path) => publishTouch(markTouched(touch, path)),
+    edit: (path, value) =>
+      publishTouch(markDirty(touch, path, !sameFieldValue(value, baseline(path)))),
     reset: () => {
+      touch = NO_FORM_TOUCH;
       publish(IDLE_FORM_STATE);
     },
   };

package/src/form/form-state.ts

@@ -3,6 +3,7 @@
 // control the app forgot to declare, which is worse than having no binding at all.
 
 import type { FormIssue } from './form-issue';
+import { type FormTouch, NO_FORM_TOUCH } from './form-touch';
 
 export type FormStatus = 'idle' | 'submitting' | 'succeeded' | 'failed';
 
@@ -12,7 +13,7 @@ export interface FormErrors {
   readonly formErrors: readonly string[];
 }
 
-export interface FormState<TResult> extends FormErrors {
+export interface FormState<TResult> extends FormErrors, FormTouch {
   readonly status: FormStatus;
   /** The server's answer. Only ever set from a resolved `submit`. */
   readonly result: TResult | undefined;
@@ -35,6 +36,8 @@ export const IDLE_FORM_STATE: FormState<never> = Object.freeze({
   formErrors: [],
   result: undefined,
   issues: [],
+  touched: NO_FORM_TOUCH.touched,
+  dirty: NO_FORM_TOUCH.dirty,
 });
 
 /**
@@ -78,6 +81,21 @@ export function distributeIssues(
   return { fieldErrors, formErrors };
 }
 
+/**
+ * The first DECLARED field carrying an error, in declaration order — which is also the order the
+ * controls are rendered in, so it is the one the reader reaches first going down the page. What a
+ * failed submit moves focus to.
+ *
+ * Declaration order, never the ISSUE order: a server is free to report the last field first, and
+ * focus would then land halfway down a form the user has not read.
+ */
+export function firstInvalidField(state: FormErrors, fields: Iterable<string>): string | undefined {
+  for (const name of fields) {
+    if (state.fieldErrors.has(name)) return name;
+  }
+  return undefined;
+}
+
 /** Every message bound to one field, in the order the issues arrived. */
 export function messagesOf(state: FormErrors, path: string): readonly string[] {
   return state.fieldErrors.get(path) ?? [];

package/src/form/form-touch.ts

@@ -0,0 +1,51 @@
+// Which fields the user has LEFT (touched) and which they have CHANGED (dirty). Pure, and
+// deliberately not a value store: this binding is server-authoritative, so it holds opinions about
+// the user's progress through the form and never a second copy of what the form says.
+
+/** Two sets, addressed in the same path grammar a control's `name` and a schema issue use. */
+export interface FormTouch {
+  readonly touched: ReadonlySet<string>;
+  readonly dirty: ReadonlySet<string>;
+}
+
+const NO_PATHS: ReadonlySet<string> = new Set();
+
+export const NO_FORM_TOUCH: FormTouch = Object.freeze({ touched: NO_PATHS, dirty: NO_PATHS });
+
+/**
+ * An empty control and an absent baseline are the same thing to the person filling the form: they
+ * typed something into a new record's field and then deleted it again, and calling that "changed"
+ * turns every abandoned keystroke into an unsaved-changes prompt. `Object.is` for everything else,
+ * so `0` and `false` are values and not blanks.
+ */
+export function sameFieldValue(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true;
+  return isBlank(a) && isBlank(b);
+}
+
+function isBlank(value: unknown): boolean {
+  return value === undefined || value === null || value === '';
+}
+
+/** The user left the control. Touched is one-way: leaving a field cannot un-visit it. */
+export function markTouched(touch: FormTouch, path: string): FormTouch {
+  if (touch.touched.has(path)) return touch;
+  return { touched: new Set([...touch.touched, path]), dirty: touch.dirty };
+}
+
+/**
+ * The user changed the control. `changed` is two-way on purpose — typing a character and deleting
+ * it again leaves the form clean, which is the only answer an "unsaved changes" guard can act on.
+ */
+export function markDirty(touch: FormTouch, path: string, changed: boolean): FormTouch {
+  if (touch.dirty.has(path) === changed) return touch;
+  const dirty = new Set(touch.dirty);
+  if (changed) dirty.add(path);
+  else dirty.delete(path);
+  return { touched: touch.touched, dirty };
+}
+
+/** Anything at all to lose. What a navigation guard asks. */
+export function isFormDirty(touch: FormTouch): boolean {
+  return touch.dirty.size > 0;
+}

package/src/form/use-form.ts

@@ -6,7 +6,13 @@
 
 import { solid } from '../theme/solid-adapter';
 import { createFormBinding, type FormBinding, type FormBindingOptions } from './form-binding';
-import { errorOf, type FormState, IDLE_FORM_STATE, messagesOf } from './form-state';
+import {
+  errorOf,
+  type FormState,
+  firstInvalidField,
+  IDLE_FORM_STATE,
+  messagesOf,
+} from './form-state';
 
 /**
  * Call it in a component body. On the server there is no registered runtime and the inert one
@@ -34,5 +40,9 @@ export function useForm<TValues, TResult>(
     state,
     errorFor: (path) => errorOf(state(), path),
     messagesFor: (path) => messagesOf(state(), path),
+    pending: () => state().status === 'submitting',
+    // Same reason: `firstInvalidField` off the binding closes over a snapshot, so a `<Form>` bound
+    // to it would keep focusing whichever field failed the FIRST submit, for the rest of the page.
+    firstInvalidField: () => firstInvalidField(state(), options.fields),
   };
 }

package/src/index.ts

@@ -6,7 +6,13 @@
 // would be TS2307 there. The reference pulls the contract along with the entry.
 /// <reference path="./scss.d.ts" />
 
-export type { FocusTrap, Politeness, RovingOptions, RovingOrientation } from './a11y';
+export type {
+  FocusTrap,
+  LiveRegionAttrs,
+  Politeness,
+  RovingOptions,
+  RovingOrientation,
+} from './a11y';
 export {
   announce,
   ariaBool,
@@ -14,6 +20,8 @@ export {
   createRovingTabindex,
   FOCUSABLE_SELECTOR,
   focusableWithin,
+  LIVE_REGION_LEVELS,
+  liveRegionAttrs,
   nextRovingIndex,
   resetIdCounter,
   useId,
@@ -25,12 +33,28 @@ export type { AlertProps } from './components/Alert';
 export { Alert } from './components/Alert';
 export type { AppShellProps } from './components/AppShell';
 export { AppShell } from './components/AppShell';
+export type { AsyncRegionProps } from './components/AsyncRegion';
+// --- async regions: the one four-way decision, and the component that renders it --------------
+export { AsyncRegion } from './components/AsyncRegion';
 export type { AvatarProps } from './components/Avatar';
 export { Avatar, initialsOf } from './components/Avatar';
 export type { AccordionSection } from './components/accordion-view';
 export { accordionOpenIds } from './components/accordion-view';
 export type { ShellIds, ShellLandmark, ShellSlots } from './components/app-shell-view';
 export { shellIds, shellLandmarks } from './components/app-shell-view';
+export type {
+  AsyncBranch,
+  AsyncFlags,
+  AsyncState,
+  ReserveBox,
+} from './components/async-branch';
+export {
+  asyncBranch,
+  asyncStateOf,
+  isBusyBranch,
+  isEmptyData,
+  reserveBlockSize,
+} from './components/async-branch';
 export type { BadgeProps } from './components/Badge';
 export { Badge } from './components/Badge';
 export type { BreadcrumbItem, BreadcrumbProps } from './components/Breadcrumb';
@@ -110,7 +134,7 @@ export { Input } from './components/Input';
 export type { IconElement, IconGlyph, IconTag } from './components/icon-glyph';
 export { ICON_TAGS, iconElements, isIconTag } from './components/icon-glyph';
 export type { ImageBox, ImageLoadingHints, ImageVariant } from './components/image-source';
-export { boxFor, loadingHints, srcsetFor } from './components/image-source';
+export { boxFor, loadingHints, ratioFor, srcsetFor } from './components/image-source';
 export type { LoadMoreInput, LoadMoreState } from './components/infinite-scroll-view';
 export { loadMoreState } from './components/infinite-scroll-view';
 export type { LinkProps } from './components/Link';
@@ -162,8 +186,10 @@ export type { TextareaProps } from './components/Textarea';
 export { Textarea } from './components/Textarea';
 export type { ThemeChoice, ThemeToggleProps } from './components/ThemeToggle';
 export { ThemeToggle } from './components/ThemeToggle';
-export type { ToastProps, ToastRegionProps } from './components/Toast';
+export type { ToastPlacement, ToastProps, ToastRegionProps } from './components/Toast';
 export { Toast, ToastRegion } from './components/Toast';
+export type { ToasterProps } from './components/Toaster';
+export { Toaster } from './components/Toaster';
 export type { ToolbarProps } from './components/Toolbar';
 export { Toolbar } from './components/Toolbar';
 export type { TooltipProps } from './components/Tooltip';
@@ -179,6 +205,7 @@ export { DEBOUNCE_DEFAULT_MS, debounce } from './debounce';
 export type { UiErrorCode } from './errors';
 export {
   conflictingFieldNameError,
+  insufficientContrastError,
   invalidBrandTokenError,
   invalidFieldPathError,
   invalidGlyphError,
@@ -193,7 +220,7 @@ export {
 } from './errors';
 // --- forms: the binding between an action's input schema and Field's error slot ---------------
 export type { FieldPathSegment, IssuePathSegment } from './form/field-path';
-export { formatFieldPath, MAX_FIELD_INDEX, parseFieldPath } from './form/field-path';
+export { fieldSelector, formatFieldPath, MAX_FIELD_INDEX, parseFieldPath } from './form/field-path';
 export type { FormBinding, FormBindingOptions } from './form/form-binding';
 export { createFormBinding } from './form/form-binding';
 export type {
@@ -207,10 +234,19 @@ export type { FormErrors, FormState, FormStatus } from './form/form-state';
 export {
   distributeIssues,
   errorOf,
+  firstInvalidField,
   IDLE_FORM_STATE,
   messagesOf,
   NO_FORM_ERRORS,
 } from './form/form-state';
+export type { FormTouch } from './form/form-touch';
+export {
+  isFormDirty,
+  markDirty,
+  markTouched,
+  NO_FORM_TOUCH,
+  sameFieldValue,
+} from './form/form-touch';
 export { valuesOfForm } from './form/form-values';
 export { useForm } from './form/use-form';
 export type { UiKey } from './i18n-keys';
@@ -266,6 +302,25 @@ export {
   toggleTheme,
   watchOsTheme,
 } from './theme/theme';
+export type {
+  ToastAction,
+  ToastDwell,
+  ToastHold,
+  ToastInput,
+  ToastItem,
+  ToastQueue,
+} from './toast/toast-state';
+// --- toasts: the queue behind ToastRegion ------------------------------------
+export {
+  collapsedToasts,
+  EMPTY_TOAST_QUEUE,
+  TOAST_DWELL_MS,
+  TOAST_MAX_VISIBLE,
+  visibleToasts,
+} from './toast/toast-state';
+export type { ToastEnv, ToastStore } from './toast/toast-store';
+export { browserToastEnv, createToastStore, INERT_TOAST_ENV } from './toast/toast-store';
+export { useToasts } from './toast/use-toasts';
 export type { Channels } from './tokens/contrast';
 export {
   AA_LARGE,
@@ -277,6 +332,8 @@ export {
   relativeLuminance,
   roleContrast,
 } from './tokens/contrast';
+export type { ContrastPair } from './tokens/contrast-pairs';
+export { CONTRAST_PAIRS, VISIBLE_EDGE } from './tokens/contrast-pairs';
 export type { ColorRole, RadiusName, Theme } from './tokens/tokens';
 // --- tokens ------------------------------------------------------------------
 export {

package/src/theme/brand.ts

@@ -3,11 +3,18 @@
 // level it emits. There is deliberately no SCSS `@use ... with ()` seam — two ways to change the
 // accent colour is the ambiguity axiom 1 exists to delete.
 
-import { invalidBrandTokenError, runtimeMissingError, unknownTokenError } from '../errors';
-import { parseChannels } from '../tokens/contrast';
+import {
+  insufficientContrastError,
+  invalidBrandTokenError,
+  runtimeMissingError,
+  unknownTokenError,
+} from '../errors';
+import { contrastRatio, parseChannels } from '../tokens/contrast';
+import { CONTRAST_PAIRS } from '../tokens/contrast-pairs';
 import {
   COLOR_ROLES,
   type ColorRole,
+  colorTokens,
   type RadiusName,
   radiusTokens,
   type Theme,
@@ -48,6 +55,12 @@ export function defineTheme(input: BrandInput): Brand {
   const blocks: string[] = [];
   const light = colorDeclarations(input.colors?.light, 'colors.light');
   const dark = colorDeclarations(input.colors?.dark, 'colors.dark');
+  // Measured AFTER the channels parse and BEFORE a single declaration is rendered: a palette that
+  // fails AA is not a stylesheet with a warning attached, it is a refusal. The pairings are the
+  // ones the framework's own palette is held to (`CONTRAST_PAIRS`), so an app cannot ship a brand
+  // the design system would have failed its own tests over.
+  assertContrast('light', input.colors?.light);
+  assertContrast('dark', input.colors?.dark);
   const root: string[] = [
     ...light,
     ...radiusDeclarations(input.radius),
@@ -161,6 +174,30 @@ function fontDeclarations(overrides: Partial<Record<FontSlot, string>> | undefin
   return out;
 }
 
+/**
+ * The palette as it will actually render: the shipped channels, with this brand's overrides on
+ * top. Measured on the RESOLVED set and not on the overrides alone, because the pairing that
+ * breaks is nearly always one the author only touched half of — a new `accent` against the
+ * shipped `accent-fg` is the single most common way a brand goes unreadable.
+ */
+function assertContrast(
+  theme: Theme,
+  overrides: Partial<Record<ColorRole, string>> | undefined,
+): void {
+  if (overrides === undefined) return;
+  const resolved = (role: ColorRole): string => overrides[role] ?? colorTokens[theme][role];
+  for (const pair of CONTRAST_PAIRS) {
+    // Only pairings this brand can have changed. The rest are the shipped palette, which
+    // `contrast.test.ts` already holds — re-reporting them would blame the app for our colours.
+    if (overrides[pair.fg] === undefined && overrides[pair.bg] === undefined) continue;
+    const fg = resolved(pair.fg);
+    const bg = resolved(pair.bg);
+    const ratio = contrastRatio(fg, bg);
+    if (ratio >= pair.minimum) continue;
+    throw insufficientContrastError(theme, pair.what, pair.fg, pair.bg, ratio, pair.minimum);
+  }
+}
+
 function assertChannels(scope: string, role: string, value: string): void {
   try {
     parseChannels(value);

package/src/toast/toast-store.ts

@@ -0,0 +1,179 @@
+// The queue with a clock attached: auto-dismiss, and the three independent reasons it stops.
+//
+// Hover and focus-within are the two everybody implements. `document.hidden` is the one everybody
+// forgets, and it is the one that loses the message outright: a backgrounded tab burns the whole
+// dwell, so the user switches back to an empty corner and never learns the save failed. All three
+// are HOLDS on one counter, because a pointer leaving while the tab is still hidden must not
+// restart the countdown.
+
+import { useId } from '../a11y';
+import {
+  addToast,
+  advanceToasts,
+  dismissToast,
+  EMPTY_TOAST_QUEUE,
+  nextExpiryMs,
+  type ToastHold,
+  type ToastInput,
+  type ToastQueue,
+  toastItem,
+} from './toast-state';
+
+/**
+ * Every host capability the store touches, injected — the same shape `ThemeEnv` has and for the
+ * same reason: a test drives the clock instead of waiting on it, and a server render gets an env
+ * whose timers never fire rather than a store that throws.
+ */
+export interface ToastEnv {
+  readonly now: () => number;
+  readonly setTimer: (fn: () => void, ms: number) => number;
+  readonly clearTimer: (handle: number) => void;
+  readonly isHidden: () => boolean;
+  /** Subscribe to tab visibility; answers the unsubscribe. */
+  readonly onVisibilityChange: (fn: () => void) => () => void;
+}
+
+/**
+ * A server render has no tab to hide and no frame to wait for, so the honest env is one where
+ * nothing is ever scheduled — not a stub of a browser, the same way `INERT_SOLID_RUNTIME` is not
+ * a stub of a Solid runtime. A `<ToastRegion>` rendered against it emits its empty live region,
+ * which is exactly what the document needs to carry BEFORE the first message arrives.
+ */
+export const INERT_TOAST_ENV: ToastEnv = Object.freeze({
+  now: () => 0,
+  setTimer: () => 0,
+  clearTimer: () => undefined,
+  isHidden: () => false,
+  onVisibilityChange: () => () => undefined,
+});
+
+export function browserToastEnv(): ToastEnv {
+  return {
+    // `Date.now`, not `performance.now`: the dwell is wall-clock time a human is reading for, and
+    // it is compared only against itself.
+    now: () => Date.now(),
+    setTimer: (fn, ms) => Number(setTimeout(fn, ms)),
+    clearTimer: (handle) => {
+      clearTimeout(handle);
+    },
+    isHidden: () => document.hidden,
+    onVisibilityChange: (fn) => {
+      document.addEventListener('visibilitychange', fn);
+      return () => {
+        document.removeEventListener('visibilitychange', fn);
+      };
+    },
+  };
+}
+
+export interface ToastStore {
+  readonly queue: () => ToastQueue;
+  /** Shows a toast, or refreshes the identical one already queued. Answers the live toast's id. */
+  readonly show: (input: ToastInput) => string;
+  readonly dismiss: (id: string) => void;
+  /** Stop the countdown for one reason. Holds are independent — the last one released resumes. */
+  readonly hold: (reason: ToastHold) => void;
+  readonly release: (reason: ToastHold) => void;
+  readonly subscribe: (listener: (queue: ToastQueue) => void) => () => void;
+  /** Drop the timer and the visibility listener. Called from an island's `onCleanup`. */
+  readonly stop: () => void;
+}
+
+/** A DOM is the whole question, exactly as `solid()` asks it. */
+function defaultEnv(): ToastEnv {
+  return typeof document === 'undefined' ? INERT_TOAST_ENV : browserToastEnv();
+}
+
+export function createToastStore(env: ToastEnv = defaultEnv()): ToastStore {
+  const holds = new Set<ToastHold>();
+  const listeners = new Set<(queue: ToastQueue) => void>();
+  let queue: ToastQueue = EMPTY_TOAST_QUEUE;
+  let timer: number | null = null;
+  let lastAt = env.now();
+
+  /** The ids on the list, which is the only change a renderer can see. */
+  const shape = (): string => queue.items.map((item) => item.id).join(' ');
+
+  /** Bank the time that has passed. While held, nothing is spent — only the clock is re-based. */
+  const spend = (): void => {
+    const now = env.now();
+    if (holds.size === 0) queue = advanceToasts(queue, now - lastAt);
+    lastAt = now;
+  };
+
+  const schedule = (): void => {
+    if (timer !== null) {
+      env.clearTimer(timer);
+      timer = null;
+    }
+    if (holds.size > 0) return;
+    const next = nextExpiryMs(queue);
+    if (next === null) return;
+    timer = env.setTimer(onDue, Math.max(next, 0));
+  };
+
+  const publish = (before: string): void => {
+    if (shape() === before) return;
+    for (const listener of [...listeners]) listener(queue);
+  };
+
+  function onDue(): void {
+    timer = null;
+    const before = shape();
+    spend();
+    publish(before);
+    schedule();
+  }
+
+  const act = (change: () => void): void => {
+    const before = shape();
+    spend();
+    change();
+    publish(before);
+    schedule();
+  };
+
+  const stopVisibility = env.onVisibilityChange(() => {
+    if (env.isHidden()) act(() => holds.add('hidden'));
+    else act(() => holds.delete('hidden'));
+  });
+  // A store created while the tab is ALREADY in the background starts held: the first
+  // `visibilitychange` it hears is the one that brings the tab back, and by then the dwell is gone.
+  if (env.isHidden()) holds.add('hidden');
+
+  return {
+    queue: () => queue,
+    show: (input) => {
+      let id = '';
+      act(() => {
+        const added = addToast(queue, toastItem(useId('toast'), input));
+        queue = added.queue;
+        id = added.id;
+      });
+      return id;
+    },
+    dismiss: (id) => {
+      act(() => {
+        queue = dismissToast(queue, id);
+      });
+    },
+    hold: (reason) => {
+      act(() => holds.add(reason));
+    },
+    release: (reason) => {
+      act(() => holds.delete(reason));
+    },
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    stop: () => {
+      if (timer !== null) env.clearTimer(timer);
+      timer = null;
+      stopVisibility();
+      listeners.clear();
+    },
+  };
+}

package/src/toast/use-toasts.ts

@@ -0,0 +1,26 @@
+// The reactive shell over `createToastStore`, and the whole of what it adds: the queue lands in a
+// signal, so `<Toaster>` re-renders when a message arrives or a dwell runs out.
+//
+// The subscription lives in an EFFECT, which is the package's one seam for DOM-only work: a server
+// render never runs it, so the store is never subscribed to on a path where no timer can fire and
+// the region renders empty — which is exactly what a document needs to carry before the first
+// message, since a live region created with its content already inside it is not announced.
+
+import { solid } from '../theme/solid-adapter';
+import type { ToastQueue } from './toast-state';
+import type { ToastStore } from './toast-store';
+
+export function useToasts(store: ToastStore): () => ToastQueue {
+  const runtime = solid();
+  const [queue, setQueue] = runtime.createSignal<ToastQueue>(store.queue());
+
+  runtime.createEffect(() => {
+    const unsubscribe = store.subscribe(setQueue);
+    // A toast shown between the render and this effect would otherwise never be seen: the signal
+    // holds the queue as it was when the component body ran.
+    setQueue(store.queue());
+    runtime.onCleanup(unsubscribe);
+  });
+
+  return queue;
+}