@sixthshift/design-system 0.4.0 → 0.6.0

package/src/hooks/useStack.ts

@@ -1,4 +1,6 @@
-import { type Dispatch, type Reducer, startTransition, useCallback, useEffect, useReducer } from "react";
+"use client";
+
+import { type Dispatch, type Reducer, startTransition, useCallback, useEffect, useReducer, useRef } from "react";
 
 type Id = string | number;
 type Transition = {
@@ -70,23 +72,44 @@ export function useStack<T extends StackItem>(initialStack: T[] = []): [T[], Sta
 
   const [state, dispatch] = useReducer(reducer, initialStack);
 
+  // One removal timer per transitioning item. The effect re-runs on every
+  // state change, so timers are tracked in a ref keyed by item id: an item
+  // already scheduled is never scheduled again (re-running the effect must not
+  // reset or duplicate its countdown), and a timer whose item has left the
+  // stack by other means is cancelled rather than left to fire at a reused id.
+  const removalTimersRef = useRef(new Map<Id, ReturnType<typeof setTimeout>>());
+
   useEffect(() => {
-    const itemsToRemove = state.filter((item) => item.transition);
+    const timers = removalTimersRef.current;
+    const transitioning = new Set(state.filter((item) => item.transition).map((item) => item.id));
 
-    if (itemsToRemove.length === 0) {
-      return;
+    for (const [id, timer] of timers) {
+      if (!transitioning.has(id)) {
+        clearTimeout(timer);
+        timers.delete(id);
+      }
     }
 
-    itemsToRemove.reverse().forEach((itemToRemove) => {
-      setTimeout(
-        () => {
-          dispatch({ type: "remove", id: itemToRemove.id });
-        }, // We found the item by the `transition` property, so we can be sure it exists.
-        (itemToRemove.transition as Transition).duration
-      );
-    });
+    for (const item of state) {
+      if (!item.transition || timers.has(item.id)) continue;
+      const timer = setTimeout(() => {
+        timers.delete(item.id);
+        dispatch({ type: "remove", id: item.id });
+      }, item.transition.duration);
+      timers.set(item.id, timer);
+    }
   }, [state]);
 
+  // Unmount only: without this, a stack unmounted mid-transition dispatches
+  // into an unmounted reducer.
+  useEffect(() => {
+    const timers = removalTimersRef.current;
+    return () => {
+      for (const timer of timers.values()) clearTimeout(timer);
+      timers.clear();
+    };
+  }, []);
+
   // Memoize the dispatch wrapper to prevent unnecessary re-renders
   // dispatch from useReducer is stable, so this only creates once
   const wrappedDispatch = useCallback((params: Action<T>) => {

package/src/hooks/useTheme.ts

@@ -1,3 +1,5 @@
+"use client";
+
 import { useCallback, useSyncExternalStore } from "react";
 
 export type Theme = "light" | "dark" | "system";

package/src/internal/PickerField.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { cn } from "@sixthshift/design-system/utils";
 import { X } from "lucide-react";
 import * as React from "react";

package/src/internal/SegmentedField.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { cn } from "@sixthshift/design-system/utils";
 import * as React from "react";
 import { useRef, useState } from "react";

package/src/internal/escapeLayers.ts

@@ -0,0 +1,53 @@
+"use client";
+
+import { useEffect } from "react";
+
+/**
+ * Registry of open "escape layers" — transient floating overlays (popovers,
+ * select dropdowns, picker calendars) that should consume an Escape press
+ * before any dialog beneath them reacts to it.
+ *
+ * The dialogs and these overlays each listen for Escape on `document`
+ * independently (floating-ui's `useDismiss` has no tree here), and document
+ * listeners fire in registration order — usually the dialog's first, since it
+ * opened first. So a dialog cannot rely on `defaultPrevented`; instead it asks
+ * this registry whether a layer is open and, if so, leaves the Escape to it.
+ * The registry is read synchronously during the event, before React commits
+ * the layer's close, so the layer that is handling this Escape still counts.
+ *
+ * Module-level on purpose: Popover, Select and Modal live in separate subpath
+ * entries with no shared context, and a context would also miss overlays
+ * rendered outside an `OverlayProvider`.
+ */
+const transientLayers = new Set<symbol>();
+const dialogLayers = new Set<symbol>();
+
+/** True while any transient escape-consuming overlay (popover-like) is open. */
+export const hasOpenEscapeLayer = () => transientLayers.size > 0;
+
+/** True while any modal dialog is open. A non-modal Sheet under a Modal defers Escape to it. */
+export const hasOpenEscapeDialog = () => dialogLayers.size > 0;
+
+function useRegistration(registry: Set<symbol>, active: boolean) {
+  useEffect(() => {
+    if (!active) return;
+    const token = Symbol("escape-layer");
+    registry.add(token);
+    return () => {
+      registry.delete(token);
+    };
+  }, [registry, active]);
+}
+
+/**
+ * Marks this component as an open transient escape layer while `active` is
+ * true. Call with the overlay's `open` state.
+ */
+export function useEscapeLayer(active: boolean) {
+  useRegistration(transientLayers, active);
+}
+
+/** Marks this component as an open modal dialog while `active` is true. */
+export function useEscapeDialog(active: boolean) {
+  useRegistration(dialogLayers, active);
+}

package/src/lib/ErrorBoundary.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { Component, type ErrorInfo, type ReactNode } from "react";
 
 export type ErrorFallbackProps = {

package/src/lib/contexts/ComponentsContext/ComponentsContext.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { createContext, type PropsWithChildren, type ReactNode, useContext } from "react";
 
 type LinkProps = {

package/src/lib/contexts/OverlayContext/OverlayContext.tsx

@@ -1,10 +1,19 @@
+"use client";
+
 import { FloatingPortal, type FloatingPortalProps } from "@floating-ui/react";
 import { type StackItem, useStack } from "@sixthshift/design-system/hooks";
 import { createContext, type FunctionComponent, type PropsWithChildren, useContext, useEffect, useMemo } from "react";
+import { hasOpenEscapeLayer } from "../../../internal/escapeLayers";
+import { ToastStack } from "./ToastStack";
+import { toastStore as defaultToastStore, type ToastStore } from "./toastStore";
 
 type OverlayContextProps = {
   modal?: FloatingPortalProps["root"];
   toast?: FloatingPortalProps["root"];
+  /** The toast stack to render. Default: the app's one, which `toast()` opens onto. Hand in your own for a second bundle or a test. */
+  toasts?: ToastStore;
+  /** Merged over the toast stack's container classes, so an app can move it (above a bottom bar, into a corner). */
+  toastClassName?: string;
 };
 
 /** Stack item for overlays - component is a self-contained wrapper */
@@ -18,24 +27,48 @@ type OverlayStackItem = StackItem & {
 };
 
 type OverlayContextType = {
-  modalRoot: FloatingPortalProps["root"];
+  // `undefined` spelled out rather than an optional `?:` — the context value
+  // below always sets the key, and `exactOptionalPropertyTypes` treats "absent"
+  // and "present but undefined" as different types.
+  modalRoot: FloatingPortalProps["root"] | undefined;
   modalStack: ReturnType<typeof useStack<OverlayStackItem>>;
-  toastRoot: FloatingPortalProps["root"];
-  toastStack: ReturnType<typeof useStack<OverlayStackItem>>;
+  toastRoot: FloatingPortalProps["root"] | undefined;
+  toastStore: ToastStore;
 };
 
+/**
+ * `root` omitted when the caller gave none, rather than passed as `undefined`
+ * or `null`. The distinction is load-bearing: `FloatingPortal` bails out of
+ * creating its portal node entirely on an explicit `null` ("wait for the root
+ * to exist"), and only a missing `root` falls through to `document.body`.
+ */
+const rootProp = (root: FloatingPortalProps["root"] | undefined) => (root === undefined ? {} : { root });
+
 const OverlayContext = createContext<OverlayContextType>(undefined as unknown as OverlayContextType);
 export const useOverlayContext = () => useContext(OverlayContext);
 
-export const OverlayProvider = ({ modal: modalRoot, toast: toastRoot, children }: PropsWithChildren<OverlayContextProps>) => {
-  const resolvedModalRoot = modalRoot ?? document.body;
-  const resolvedToastRoot = toastRoot ?? document.body;
-
+export const OverlayProvider = ({
+  modal: modalRoot,
+  toast: toastRoot,
+  toasts: toastStore = defaultToastStore,
+  toastClassName,
+  children,
+}: PropsWithChildren<OverlayContextProps>) => {
+  // The roots pass through unresolved, deliberately. `"use client"` makes this a
+  // Client Component, but a Client Component is still rendered once on the
+  // server — defaulting to `document.body` here read the DOM at render scope and
+  // threw "document is not defined" on the first App Router request, which
+  // src/testing/stories.ssr.test.tsx and src/exports.ssr.test.tsx now catch. It
+  // bought nothing either: `FloatingPortal` already falls back to
+  // `document.body` when no `root` is given, and does it in an effect, on the
+  // client, where a body exists. Both portals below are behind a non-empty
+  // stack, and both stacks start empty, so nothing portals on the server anyway.
+  //
+  // Modals are a `useStack` here; toasts are a store outside React, so that
+  // `toast()` works from code that is not a component.
   const modalStack = useStack<OverlayStackItem>([]);
-  const toastStack = useStack<OverlayStackItem>([]);
 
   const [modals] = modalStack;
-  const [toasts] = toastStack;
 
   // Global escape key handler - closes topmost modal
   useEffect(() => {
@@ -43,6 +76,10 @@ export const OverlayProvider = ({ modal: modalRoot, toast: toastRoot, children }
 
     const handleEscape = (event: KeyboardEvent) => {
       if (event.key === "Escape") {
+        // A transient overlay open above the modal (a Select dropdown, a
+        // Popover, a picker calendar) consumes this Escape via its own
+        // dismiss handling — closing the modal too would double-fire.
+        if (hasOpenEscapeLayer()) return;
         const topModal = modals.at(-1);
         topModal?.onClose?.();
       }
@@ -55,12 +92,12 @@ export const OverlayProvider = ({ modal: modalRoot, toast: toastRoot, children }
   // Memoize context value to prevent unnecessary re-renders in consumers
   const contextValue = useMemo(
     () => ({
-      modalRoot: resolvedModalRoot,
+      modalRoot,
       modalStack,
-      toastRoot: resolvedToastRoot,
-      toastStack,
+      toastRoot,
+      toastStore,
     }),
-    [resolvedModalRoot, modalStack, resolvedToastRoot, toastStack]
+    [modalRoot, modalStack, toastRoot, toastStore]
   );
 
   return (
@@ -69,25 +106,15 @@ export const OverlayProvider = ({ modal: modalRoot, toast: toastRoot, children }
 
       {/* Modal stack - rendered in portal */}
       {modals.length > 0 && (
-        <FloatingPortal root={resolvedModalRoot}>
+        <FloatingPortal {...rootProp(modalRoot)}>
           {modals.map(({ id, component: Component, data }) => (
             <Component key={id} data={data} />
           ))}
         </FloatingPortal>
       )}
 
-      {/* Toast stack - rendered in portal */}
-      {toasts.length > 0 && (
-        <FloatingPortal root={resolvedToastRoot}>
-          <div className="pointer-events-none fixed bottom-6 left-1/2 z-toast flex -translate-x-1/2 flex-col-reverse items-center gap-3">
-            {toasts.map(({ id, component: Component, onClose, ...props }) => (
-              <div key={id} className="pointer-events-auto">
-                <Component onClose={onClose} {...props} />
-              </div>
-            ))}
-          </div>
-        </FloatingPortal>
-      )}
+      {/* Toast stack - portals itself, and only while it holds something */}
+      <ToastStack store={toastStore} className={toastClassName} {...rootProp(toastRoot)} />
     </OverlayContext.Provider>
   );
 };

package/src/lib/contexts/OverlayContext/ToastStack.tsx

@@ -0,0 +1,71 @@
+"use client";
+
+import { FloatingPortal, type FloatingPortalProps } from "@floating-ui/react";
+import { Toast } from "@sixthshift/design-system/toast";
+import { cn } from "@sixthshift/design-system/utils";
+import { useCallback, useEffect, useSyncExternalStore } from "react";
+import { toastStore as defaultStore, type ToastRecord, type ToastStore } from "./toastStore";
+
+const EMPTY: readonly ToastRecord[] = [];
+
+/** The store's stack, re-rendering the caller as it changes. Empty during server rendering. */
+export function useToasts(store: ToastStore = defaultStore): readonly ToastRecord[] {
+  return useSyncExternalStore(store.subscribe, store.snapshot, () => EMPTY);
+}
+
+/**
+ * One toast in the stack: the dismissal timer lives here, not in the store,
+ * so the store stays free of the DOM. Expiry and the X button take the same
+ * path — `open` flips false, `Toast` plays its exit, and `onClose` drops the
+ * record once the animation ends.
+ */
+function ToastItem({ record, store }: { record: ToastRecord; store: ToastStore }) {
+  const { id, duration, closing } = record;
+  // `duration` is the stack's to act on, not the toast's to render.
+  const { component: Component = Toast, duration: _duration, ...props } = record.options;
+
+  useEffect(() => {
+    if (duration <= 0 || closing) return;
+    const timer = setTimeout(() => store.close(id), duration);
+    return () => clearTimeout(timer);
+  }, [id, duration, closing, store]);
+
+  const onClose = useCallback(() => store.remove(id), [store, id]);
+
+  return (
+    <div className="pointer-events-auto" data-toast-id={id} data-toast-intent={props.intent ?? "neutral"}>
+      <Component {...props} standalone={false} open={!closing} onClose={onClose} />
+    </div>
+  );
+}
+
+export type ToastStackProps = {
+  /** The stack to render. Default: the app's one, which `toast()` opens onto. */
+  store?: ToastStore | undefined;
+  /** Portal root (default: `document.body`). */
+  root?: FloatingPortalProps["root"] | undefined;
+  /** Merged over the container's classes, so an app can move the stack (above a bottom bar, to a corner). */
+  className?: string | undefined;
+};
+
+/** The container's own classes: bottom centre, newest at the bottom, click-through between toasts. */
+export const TOAST_STACK_CLASS = "pointer-events-none fixed bottom-6 left-1/2 z-toast flex -translate-x-1/2 flex-col-reverse items-center gap-3";
+
+/**
+ * The open toasts, portalled and positioned. `OverlayProvider` renders one;
+ * render it yourself only when there is no provider to host it.
+ */
+export function ToastStack({ store = defaultStore, root, className }: ToastStackProps) {
+  const toasts = useToasts(store);
+  if (toasts.length === 0) return null;
+  // `root` omitted rather than passed as `undefined`: see OverlayContext's `rootProp`.
+  return (
+    <FloatingPortal {...(root === undefined ? {} : { root })}>
+      <div className={cn(TOAST_STACK_CLASS, className)} data-toast-stack="" data-count={toasts.length}>
+        {toasts.map((record) => (
+          <ToastItem key={record.id} record={record} store={store} />
+        ))}
+      </div>
+    </FloatingPortal>
+  );
+}

package/src/lib/contexts/OverlayContext/hooks/useModal.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { ModalContextProvider, type ModalProps, type OnClose } from "@sixthshift/design-system/modal";
 import { type ComponentType, type ReactNode, Suspense, useCallback, useId, useRef } from "react";
 import { useOverlayContext } from "../OverlayContext";

package/src/lib/contexts/OverlayContext/hooks/useToast.ts

@@ -1,80 +1,37 @@
-import type { StackItem } from "@sixthshift/design-system/hooks";
-import { Toast, type ToastProps } from "@sixthshift/design-system/toast";
-import { type FunctionComponent, useCallback, useEffect, useId, useRef } from "react";
-import { useOverlayContext } from "../OverlayContext";
-
-// Default auto-dismiss duration in milliseconds
-const DEFAULT_DURATION = 5000;
-
-// Native replacements for lodash functions
-const isFunction = (value: unknown): value is FunctionComponent<ToastProps> => typeof value === "function";
-
-const isPlainObject = (value: unknown): value is ToastPropsWithDuration => typeof value === "object" && value !== null && !Array.isArray(value);
+"use client";
 
-type ToastPropsWithDuration = Omit<ToastProps, "onClose"> & {
-  /** Auto-dismiss duration in ms. Set to 0 to disable. Default: 5000 */
-  duration?: number;
-};
+import { useCallback } from "react";
+import { useOverlayContext } from "../OverlayContext";
+import { toastStore as defaultStore, type ToastOptions } from "../toastStore";
 
 /**
- * Toast stack item - extends base StackItem with component and additional props
- * that are passed through to the Toast component in OverlayContext
+ * Open toasts on the provider's stack, with the content decided at the moment
+ * of opening: an error's message, a count, whatever the action produced.
+ *
+ * @example
+ * ```tsx
+ * const { openToast } = useToast();
+ *
+ * async function save() {
+ *   try {
+ *     await api.save();
+ *     openToast({ intent: "success", title: "Saved" });
+ *   } catch (error) {
+ *     openToast({ intent: "danger", title: "Could not save", children: String(error) });
+ *   }
+ * }
+ * ```
+ *
+ * Outside any provider this opens on the app's default stack, which is also
+ * what the plain `toast()` export uses, so code that is not a component — a
+ * store, a callback from a service worker — has the same door.
  */
-type ToastStackItem = StackItem & {
-  component: FunctionComponent<ToastProps>;
-  onClose?: () => void;
-} & Partial<Omit<ToastProps, "onClose">>;
-
-export const useToast = (args: ToastPropsWithDuration | FunctionComponent<ToastProps>) => {
-  const {
-    toastStack: [, dispatch],
-  } = useOverlayContext();
-
-  const id = useId();
-
-  const customComponent = isFunction(args) ? args : null;
-  const props = isPlainObject(args) ? args : ({} as ToastPropsWithDuration);
-  const { duration = DEFAULT_DURATION, ...toastPropsRaw } = props;
-
-  const closeToast = useCallback(() => {
-    dispatch({ type: "remove", id, transition: { duration: 300 } });
-  }, [dispatch, id]);
-
-  // `openToast` has to be both referentially stable — callers put it in effect
-  // dependency arrays — and able to see the current props. A ref refreshed after
-  // every render gives both.
-  //
-  // It previously memoised the props object against JSON.stringify(props) as a
-  // cache key. JSON.stringify silently drops function-valued properties, so a
-  // changed `onAction` whose serialisable fields were identical did not
-  // invalidate the key, and `openToast` kept firing the stale closure.
-  const latest = useRef({ customComponent, toastProps: toastPropsRaw, duration });
-  useEffect(() => {
-    latest.current = { customComponent, toastProps: toastPropsRaw, duration };
-  });
-
-  const openToast = useCallback(() => {
-    const { customComponent: component, toastProps, duration: autoDismiss } = latest.current;
-
-    dispatch({
-      type: "push",
-      item: {
-        id,
-        component: component ?? Toast,
-        onClose: closeToast,
-        standalone: false, // OverlayContext handles positioning
-        ...toastProps,
-      } as ToastStackItem,
-    });
+export const useToast = () => {
+  const store = useOverlayContext()?.toastStore ?? defaultStore;
 
-    // Auto-dismiss if duration is set
-    if (autoDismiss > 0) {
-      setTimeout(closeToast, autoDismiss);
-    }
-  }, [dispatch, id, closeToast]);
+  const openToast = useCallback((options: ToastOptions) => store.open(options), [store]);
+  const closeToast = useCallback((id: string) => store.close(id), [store]);
+  const closeAllToasts = useCallback(() => store.clear(), [store]);
 
-  return {
-    openToast,
-    closeToast,
-  };
+  return { openToast, closeToast, closeAllToasts };
 };

package/src/lib/contexts/OverlayContext/index.ts

@@ -4,3 +4,5 @@ export { Modal } from "@sixthshift/design-system/modal";
 export * from "./hooks/useModal";
 export * from "./hooks/useToast";
 export * from "./OverlayContext";
+export { TOAST_STACK_CLASS, ToastStack, type ToastStackProps, useToasts } from "./ToastStack";
+export * from "./toastStore";

package/src/lib/contexts/OverlayContext/toastStore.ts

@@ -0,0 +1,138 @@
+import type { ToastProps } from "@sixthshift/design-system/toast";
+import type { FunctionComponent } from "react";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/** What a caller passes to open a toast: the `Toast`'s own props, plus how long it stays. */
+export type ToastOptions = Omit<ToastProps, "onClose" | "open" | "standalone" | "root"> & {
+  /**
+   * Milliseconds until the toast dismisses itself. `0` keeps it until it is
+   * dismissed by hand. Default: `0` for `intent="danger"` (a failure usually
+   * carries a message worth reading, and often a retry), `5000` otherwise.
+   */
+  duration?: number;
+  /** Render this instead of `Toast`. It receives `ToastProps` and must honour `open` and `onClose` as `Toast` does. */
+  component?: FunctionComponent<ToastProps>;
+};
+
+/** One toast as the stack holds it. */
+export type ToastRecord = {
+  id: string;
+  options: ToastOptions;
+  /** The resolved lifetime, in ms; `0` sticks. */
+  duration: number;
+  /** Playing its exit; removed once the animation ends. */
+  closing: boolean;
+};
+
+/** What `open` hands back: the toast's id, and a way to close it early. */
+export type ToastHandle = { id: string; close: () => void };
+
+/**
+ * The stack of open toasts, with subscribers. No DOM and no timers: the
+ * `ToastStack` that renders it owns dismissal timing, and `Toast` owns the
+ * exit animation. Plain functions, so a toast can be opened from anywhere —
+ * an event handler, a store, a service-worker callback — not only from a
+ * component.
+ */
+export type ToastStore = {
+  /** Register a listener; returns the unsubscribe. */
+  subscribe: (listener: () => void) => () => void;
+  /** The current stack, oldest first. Reference-stable until it changes, as `useSyncExternalStore` needs. */
+  snapshot: () => readonly ToastRecord[];
+  /** Add a toast. Past `max`, the oldest is dropped at once. */
+  open: (options: ToastOptions) => ToastHandle;
+  /** Begin a toast's exit. It leaves the stack when `remove` is called, which `Toast` does after its animation. */
+  close: (id: string) => void;
+  /** Drop a toast at once. */
+  remove: (id: string) => void;
+  /** Begin every toast's exit. */
+  clear: () => void;
+};
+
+export type ToastStoreOptions = {
+  /** How many toasts show at once; the oldest falls off. Default: 3 — a short stack reads on a phone. */
+  max?: number;
+  /** Ids in open order. Injectable so a test can name them. */
+  newId?: () => string;
+};
+
+// =============================================================================
+// Defaults
+// =============================================================================
+
+export const DEFAULT_TOAST_DURATION = 5000;
+export const DEFAULT_MAX_TOASTS = 3;
+
+/** The lifetime an intent gets when none is given: failures stay, everything else expires. */
+export function defaultToastDuration(intent: ToastOptions["intent"]): number {
+  return intent === "danger" ? 0 : DEFAULT_TOAST_DURATION;
+}
+
+let opened = 0;
+const nextId = () => `toast-${++opened}`;
+
+// =============================================================================
+// Store
+// =============================================================================
+
+const EMPTY: readonly ToastRecord[] = [];
+
+export function createToastStore({ max = DEFAULT_MAX_TOASTS, newId = nextId }: ToastStoreOptions = {}): ToastStore {
+  let toasts: readonly ToastRecord[] = EMPTY;
+  const listeners = new Set<() => void>();
+
+  const set = (next: readonly ToastRecord[]) => {
+    toasts = next.length === 0 ? EMPTY : next;
+    for (const listener of [...listeners]) listener();
+  };
+
+  const close = (id: string) => {
+    const record = toasts.find((toast) => toast.id === id);
+    if (record === undefined || record.closing) return;
+    set(toasts.map((toast) => (toast === record ? { ...toast, closing: true } : toast)));
+  };
+
+  return {
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => void listeners.delete(listener);
+    },
+    snapshot: () => toasts,
+    open(options) {
+      const id = newId();
+      const record: ToastRecord = { id, options, duration: options.duration ?? defaultToastDuration(options.intent), closing: false };
+      set([...toasts, record].slice(-max));
+      return { id, close: () => close(id) };
+    },
+    close,
+    remove(id) {
+      const next = toasts.filter((toast) => toast.id !== id);
+      if (next.length !== toasts.length) set(next);
+    },
+    clear() {
+      if (toasts.every((toast) => toast.closing)) return;
+      set(toasts.map((toast) => ({ ...toast, closing: true })));
+    },
+  };
+}
+
+/** The app's one stack: what `OverlayProvider` renders unless handed another. */
+export const toastStore = createToastStore();
+
+/** Open a toast on the app's stack, from anywhere. Returns its id and a way to close it early. */
+export function toast(options: ToastOptions): ToastHandle {
+  return toastStore.open(options);
+}
+
+/** Begin a toast's exit on the app's stack. */
+export function closeToast(id: string): void {
+  toastStore.close(id);
+}
+
+/** Begin every toast's exit on the app's stack. */
+export function closeAllToasts(): void {
+  toastStore.clear();
+}

package/src/lib/withErrorBoundary.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import type { ComponentType, ReactNode } from "react";
 import { ErrorBoundary, type ErrorFallbackProps } from "./ErrorBoundary";
 

package/src/lib/withSuspenseAndErrorBoundary.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import type { ComponentType, ReactNode } from "react";
 import { Suspense } from "react";
 import { ErrorBoundary, type ErrorFallbackProps } from "./ErrorBoundary";

package/src/theme/linen/index.css

@@ -0,0 +1,11 @@
+/**
+ * Linen — the exported artifact (`@sixthshift/design-system/themes/linen.css`).
+ * The system's one theme, consolidated from the plans/10 exploration (was
+ * "02 Hue-anchored"; the six alternatives live at the `themes-exploration` tag).
+ * Plain CSS composition, no build step. A theme is exactly two imports: its
+ * own tokens, plus the theme-independent system (recipes, Tailwind config),
+ * which theming/tailwind.css composes.
+ */
+
+@import "./theme.css"; /* imports ./palette.css itself */
+@import "../../theming/tailwind.css"; /* imports every component's *.recipe.css itself */