@ailuracode/alpine-toast 0.1.1 → 2.0.0

package/dist/index.d.ts

@@ -1,8 +1,22 @@
-import AlpineType from 'alpinejs';
+import { SingletonScope, Alpine, Unsubscribe, PluginCallback, BaseController } from '@ailuracode/alpine-core';
+export { Unsubscribe } from '@ailuracode/alpine-core';
+import { Alpine as Alpine$1 } from 'alpinejs';
+
+/**
+ * Public type contracts for `@ailuracode/alpine-toast`.
+ *
+ * Per `.cursor/rules/formatting.mdc`, every public type
+ * lives in a `types.ts` module so consumers can import them without pulling
+ * the implementation. The shape IS the contract — changes to a field name
+ * or type are breaking changes.
+ */
 
 /** Built-in Alpine store key for the toast queue. */
 declare const TOAST_STORE_KEY: "toast";
+/** Built-in `$toast` magic key registered by {@link toastPlugin}. */
+declare const TOAST_MAGIC_KEY: "toast";
 type ToastStoreKey = typeof TOAST_STORE_KEY;
+type ToastMagicKey = typeof TOAST_MAGIC_KEY;
 /** Built-in position used when none is provided. Map to CSS in your UI layer. */
 type DefaultToastPosition = "bottom-right";
 /** Union of `bottom-right` plus developer-defined positions from plugin options. */
@@ -76,6 +90,14 @@ interface ToastPluginOptions<TVariants extends readonly string[] = readonly [],
     listenToWindowEvents?: boolean;
     /** Internal store key. Default: `"toast"`. */
     storeKey?: ToastStoreKey;
+    /**
+     * `$toast` magic key the Alpine plugin registers under. Defaults to
+     * {@link TOAST_MAGIC_KEY}. Set when the host already owns a `toast`
+     * magic or another toolkit plugin would collide on that name — the
+     * rename avoids the collision without touching the controller.
+     * Ignored by the standalone `createToastController` helper.
+     */
+    magicKey?: string;
 }
 interface ToastPromiseMessages<T = unknown, TVariant extends string = string, TContent = unknown> {
     loading?: string;
@@ -155,25 +177,154 @@ type ResolvedToastPluginConfig<TVariants extends readonly string[] = readonly []
     maxVisible: number;
     listenToWindowEvents: boolean;
     storeKey: ToastStoreKey;
+    magicKey: string;
     variants: TVariants;
     positions: TPositions;
     promise: ResolvedPromiseConfig<TVariants>;
 };
-
-/** Resolves plugin options with defaults and queue limit rules. */
-declare function resolveToastPluginConfig<const TVariants extends readonly string[] = readonly [], const TPositions extends readonly string[] = readonly []>(options?: ToastPluginOptions<TVariants, TPositions>): ResolvedToastPluginConfig<TVariants, TPositions>;
-/** Builds typed toast plugin options with inferred variant and position literals. */
-declare function toastOptions<const TVariants extends readonly string[] = readonly [], const TPositions extends readonly string[] = readonly [], TContent = unknown>(options: ToastPluginOptions<TVariants, TPositions, TContent>): ToastPluginOptions<TVariants, TPositions, TContent>;
-/** Declares toast variant names with full literal inference. */
-declare function toastVariants<const T extends readonly string[]>(variants: T): T;
-/** Declares toast position names with full literal inference. */
-declare function toastPositions<const T extends readonly string[]>(positions: T): T;
-
-/** Variant names that cannot override core `$toast` methods. */
-declare const RESERVED_TOAST_MAGIC_KEYS: Set<string>;
-/** Builds the callable `$toast` magic API backed by the internal toast store. */
-declare function createToastMagic<const TVariants extends readonly string[], const TPositions extends readonly string[] = readonly [], TContent = unknown>(config: ResolvedToastPluginConfig<TVariants, TPositions>, getStore: () => ToastStore<TVariants, TPositions, TContent>): ToastMagic<TVariants, TPositions, TContent>;
-
+/**
+ * Source of a toast transition — informs subscribers why a change
+ * happened. Single source of truth for the `change` event's `source`
+ * field; adding a new member ripples through every consumer so
+ * exhaustiveness is enforced by TypeScript.
+ *
+ * Public: branching on `detail.source` is a contract.
+ */
+type ToastChangeSource = "initialization" | "push" | "pushUnique" | "update" | "dismiss" | "dismissAt" | "dismissAll";
+/**
+ * Structured payload delivered to subscribers on every transition.
+ *
+ * - `source` discriminates the kind of transition.
+ * - `items` is the full snapshot — Alpine's reactive proxy mirrors
+ *   the array reference (replacing, not mutating in place) so
+ *   template `x-for` loops see the new contents.
+ */
+interface ToastChangeDetail<TVariants extends readonly string[] = readonly [], TPositions extends readonly string[] = readonly [], TContent = unknown> {
+    readonly source: ToastChangeSource;
+    readonly items: ToastItem<TVariants, TPositions, TContent>[];
+}
+/** Options accepted by {@link createToastController}. */
+interface CreateToastControllerOptions<TPositions extends readonly string[] = readonly [], _TContent = unknown> {
+    /**
+     * Stable identifier exposed via {@link ToastController.id}. When
+     * omitted, the controller generates one from the controller name.
+     * Tests typically pin this for deterministic assertions.
+     */
+    readonly id?: string;
+    /** Default position for new toasts when payload omits it. */
+    readonly defaultPosition?: ToastPosition<TPositions>;
+    /** Declared positions — each gets its own stack. */
+    readonly positions?: TPositions;
+    /** Default auto-dismiss duration in milliseconds. */
+    readonly defaultDuration?: number;
+    /** Maximum toasts in the queue. `0` = unlimited. */
+    readonly maxToasts?: number;
+    /** Maximum toasts shown at once. Defaults to `maxToasts`. */
+    readonly maxVisible?: number;
+    /** Listen for `toast` window events. Default: `true`. */
+    readonly listenToWindowEvents?: boolean;
+    /** Internal store key. Default: `"toast"`. */
+    readonly storeKey?: ToastStoreKey;
+    /**
+     * Reactive store accessor — maintained for backwards compatibility
+     * with the pre-controller architecture. The auto-dismiss timer
+     * routes through this accessor when provided, so callers can wrap
+     * the store in a proxy and observe timer-fired dismissals.
+     */
+    readonly getStore?: () => ToastStore<readonly [], TPositions, unknown>;
+    /**
+     * Singleton scope for this controller. Defaults to the active
+     * `document`, an ambient `runWithSingletonScope()` context, or —
+     * in SSR — must be provided explicitly as a plain object.
+     */
+    readonly scope?: SingletonScope;
+}
+/**
+ * Public, framework-agnostic manager returned by {@link createToastController}.
+ *
+ * Reads flow through getters; mutations go through the manager so
+ * subscriptions and the in-place snapshot stay consistent.
+ *
+ * The Alpine integration subscribes to the `change` event and
+ * mirrors the snapshot into the reactive store so bindings re-render
+ * automatically. Standalone consumers can wire their own adapter via
+ * `manager.on("change", detail => ...)`.
+ */
+interface ToastManager<TVariants extends readonly string[] = readonly [], TPositions extends readonly string[] = readonly [], TContent = unknown> {
+    /** Default position for new toasts when payload omits it. */
+    readonly defaultPosition: ToastPosition<TPositions>;
+    /** Declared positions with an independent stack each. */
+    readonly stackPositions: readonly ToastPosition<TPositions>[];
+    /** Maximum toasts in the queue. `0` = unlimited. */
+    readonly maxToasts: number;
+    /** Maximum toasts shown at once. */
+    readonly maxVisible: number;
+    /** Live snapshot of every toast (newest first). */
+    readonly items: ToastItem<TVariants, TPositions, TContent>[];
+    /** Pushes a new toast and returns its id. */
+    push(payload?: ToastPayload<TVariants, TPositions, TContent>): string;
+    /**
+     * Dismisses every active toast with the same `key`, then pushes.
+     * Useful for undo flows and single-slot notices.
+     */
+    pushUnique(key: string, payload?: ToastPayload<TVariants, TPositions, TContent>): string;
+    /** Patches a toast in place by id. Resets the auto-dismiss timer if `duration` changes. */
+    update(id: string, payload?: Partial<ToastPayload<TVariants, TPositions, TContent>>): void;
+    /** Marks a toast as removed; purge happens after a short delay. */
+    dismiss(id: string): void;
+    /** Marks every toast at `position` as removed. */
+    dismissAt(position: ToastPosition<TPositions>): void;
+    /** Marks every toast as removed. */
+    dismissAll(): void;
+    /** Toasts at `position`, newest first (includes exiting `removed` items). */
+    itemsAt(position: ToastPosition<TPositions>): ToastItem<TVariants, TPositions, TContent>[];
+    /** Timed stack at `position` (includes exiting `removed` items). */
+    timedItemsAt(position: ToastPosition<TPositions>): ToastItem<TVariants, TPositions, TContent>[];
+    /** Persistent stack at `position` (includes exiting `removed` items). */
+    persistentItemsAt(position: ToastPosition<TPositions>): ToastItem<TVariants, TPositions, TContent>[];
+    /** Active timed toasts only — preferred for `x-for` render lists. */
+    activeTimedItemsAt(position: ToastPosition<TPositions>): ToastItem<TVariants, TPositions, TContent>[];
+    /** Active persistent toasts only — preferred for `x-for` render lists. */
+    activePersistentItemsAt(position: ToastPosition<TPositions>): ToastItem<TVariants, TPositions, TContent>[];
+    /** Whether the timed toast at `index` (within `timedItemsAt`) should render. */
+    isVisibleAt(position: ToastPosition<TPositions>, index: number): boolean;
+    /**
+     * Subscribes to a `change` event. Returns an unsubscribe function.
+     * The detail payload carries `source` and `items` (full snapshot).
+     */
+    on(event: "change", listener: (detail: ToastChangeDetail<TVariants, TPositions, TContent>) => void): Unsubscribe;
+    /** Tears down listeners and timers. Idempotent. */
+    destroy(): void;
+}
+/**
+ * Typed view of `Alpine` the toast plugin uses internally.
+ *
+ * Built from the toolkit's {@link Alpine} generic with the `toast`
+ * store mapped to its concrete {@link ToastStore} shape. A real
+ * `Alpine` runtime is assignable to `ToastAlpine` without a cast
+ * because the toolkit's `Alpine<Stores>` only adds overloads.
+ *
+ * The optional `cleanup?` member mirrors theme/lang/scroll's
+ * integrations so `controller.destroy()` can be forwarded through
+ * Alpine's lifecycle when available.
+ */
+type ToastAlpine = Alpine<{
+    toast: ToastStore;
+}> & {
+    /** Forwarded through Alpine's cleanup mechanism when available. */
+    cleanup?(callback: () => void): void;
+};
+/**
+ * `Alpine.plugin()` callback signature.
+ *
+ * Typed against the base {@link AlpineBase} via the toolkit's
+ * {@link PluginCallback} generic, which keeps this alias structurally
+ * assignable to `Base.PluginCallback`. The plugin narrows the
+ * runtime instance to {@link ToastAlpine} inside the function body
+ * for typed access to the `"toast"` store / magic.
+ */
+type ToastPluginCallback = PluginCallback<Alpine$1>;
+/** Backwards-compat alias for {@link CreateToastControllerOptions}. */
 interface CreateToastStoreOptions<TPositions extends readonly string[] = readonly []> {
     defaultPosition?: ToastPosition<TPositions>;
     /** Declared positions — each gets its own stack. */
@@ -184,6 +335,203 @@ interface CreateToastStoreOptions<TPositions extends readonly string[] = readonl
     /** Reactive store accessor — required for Alpine auto-dismiss timers. */
     getStore?: () => ToastStore<readonly [], TPositions, unknown>;
 }
+
+/**
+ * Strongly-typed event map for the toast controller.
+ *
+ * Per the toolkit convention (see `@ailuracode/alpine-theme` and
+ * `@ailuracode/alpine-lang`), the event map is the small surface
+ * this module owns; the detail types live in `./types.ts` so the
+ * manager interface in that module can reference them without an
+ * `events.ts ↔ types.ts` import cycle.
+ *
+ * The controller emits a single `change` event after every state
+ * mutation (push, update, dismiss, dismissAt, dismissAll,
+ * pushUnique). The Alpine adapter subscribes to this one event and
+ * mirrors the `items` snapshot into the reactive store proxy.
+ *
+ * `source` discriminates the kind of transition so subscribers can
+ * branch on intent (e.g. animations might react differently to
+ * `push` vs `dismiss`).
+ *
+ * The event map is parameterized by `TPositions` and `TContent` so
+ * `BaseController.emit` infers the right `ToastChangeDetail` shape
+ * for each generic instantiation of the controller.
+ */
+
+/**
+ * Event map consumed by `BaseController<ToastEvents>`. Single-key
+ * contract: every transition emits `change` with the same
+ * {@link ToastChangeDetail} payload.
+ */
+interface ToastEvents<TPositions extends readonly string[] = readonly [], TContent = unknown> extends Record<string, unknown> {
+    change: ToastChangeDetail<readonly [], TPositions, TContent>;
+}
+/**
+ * Subscriber callback for the `change` event. Hardcoded to the
+ * listener signature `(detail: ToastChangeDetail) => void` rather
+ * than indexed via `ToastEvents['change']` because that indexer
+ * returns the *payload* type, not the *callback* type. Keeping it
+ * explicit avoids the silent payload-vs-callback swap.
+ */
+type ToastListener<TPositions extends readonly string[] = readonly [], TContent = unknown> = (detail: ToastChangeDetail<readonly [], TPositions, TContent>) => void;
+
+/**
+ * Toast controller — the framework-agnostic core of
+ * `@ailuracode/alpine-toast`. Owns every piece of toast queue
+ * state and is the single source of truth for the
+ * `items` array, the auto-dismiss timers, and the position /
+ * variant filtering logic.
+ *
+ * Responsibilities:
+ *
+ * 1. **State** — owns `items`, `defaultPosition`, `stackPositions`,
+ *    `maxToasts`, `maxVisible`. Mutations always produce a fresh
+ *    `items` array (immutable replacement) so Alpine's reactive
+ *    proxy can observe the change.
+ * 2. **Timers** — schedules auto-dismiss timers per timed toast.
+ *    Timers are tracked internally and cleared on `destroy()`
+ *    via `registerCleanup()` so the BaseController lifecycle
+ *    covers them.
+ * 3. **Queue limits** — enforces `maxToasts` per (position, stack)
+ *    pair on every `push` / `update` (when position or duration
+ *    flips between timed ↔ persistent).
+ * 4. **Subscriptions** — typed `on('change', listener)` from the
+ *    inherited bus, with the toast-level detail shape (`source`
+ *    discriminator + full `items` snapshot).
+ *
+ * Construction rules:
+ *
+ * - The constructor MUST NOT touch `window`, `document`, or timers.
+ *   Browser-side wiring (the window `toast` event listener) lives
+ *   in `mount()`.
+ * - The factory `createToastController()` auto-mounts so callers
+ *   receive a fully-initialized instance.
+ * - `destroy()` MUST be idempotent and MUST clear every pending
+ *   timer.
+ */
+
+/**
+ * Public entrypoint — builds and mounts a fully-initialized
+ * {@link ToastController}. The constructor stays pure; the factory
+ * wires the browser-touching `mount()` step.
+ *
+ * Singleton guarantee: at most one live `ToastController` per
+ * document. Repeated calls return the existing instance; the
+ * controller's `destroy()` releases the slot so the next call
+ * builds a fresh one. Direct `new ToastController(...)` is still
+ * supported for tests and advanced consumers — only the
+ * `createToastController()` factory enforces uniqueness.
+ */
+declare function createToastController<const TPositions extends readonly string[] = readonly [], TContent = unknown>(options?: CreateToastControllerOptions<TPositions, TContent>): ToastController<TPositions, TContent>;
+/**
+ * Headless controller for `@ailuracode/alpine-toast`. Owns every
+ * piece of toast queue state. The Alpine integration in
+ * `plugin.ts` subscribes to the controller's `change` event and
+ * mirrors the snapshot into the reactive store so bindings
+ * re-render automatically.
+ *
+ * Standalone consumers (non-Alpine) can `createToastController()`
+ * directly and wire their own adapter via
+ * `manager.on("change", detail => ...)`.
+ */
+declare class ToastController<const TPositions extends readonly string[] = readonly [], TContent = unknown> extends BaseController<ToastEvents<TPositions, TContent>> {
+    #private;
+    constructor(options: CreateToastControllerOptions<TPositions, TContent>);
+    /**
+     * Tears down every side effect. Idempotent. `super.destroy()` runs
+     * the registered cleanups (currently just the window listener)
+     * first; the timer cleanup runs as a final step. Also releases
+     * the singleton slot so the next `createToastController()` call
+     * builds a fresh controller.
+     */
+    destroy(): void;
+    /**
+     * Starts the controller's side effects. The constructor leaves
+     * `#items` empty; `mount()` registers the `toast` window event
+     * listener (when enabled) and emits the initialization event.
+     *
+     * Calling `mount()` more than once is a no-op — `BaseController`
+     * guards the phase. Calling it after `destroy()` throws.
+     */
+    mount(): void;
+    get defaultPosition(): ToastPosition<TPositions>;
+    get stackPositions(): readonly ToastPosition<TPositions>[];
+    get maxToasts(): number;
+    get maxVisible(): number;
+    get items(): ToastItem<readonly [], TPositions, TContent>[];
+    push(payload?: ToastPayload<readonly [], TPositions, TContent>): string;
+    pushUnique(key: string, payload?: ToastPayload<readonly [], TPositions, TContent>): string;
+    update(id: string, payload?: Partial<ToastPayload<readonly [], TPositions, TContent>>): void;
+    dismiss(id: string): void;
+    dismissAt(position: ToastPosition<TPositions>): void;
+    dismissAll(): void;
+    itemsAt(position: ToastPosition<TPositions>): ToastItem<readonly [], TPositions, TContent>[];
+    timedItemsAt(position: ToastPosition<TPositions>): ToastItem<readonly [], TPositions, TContent>[];
+    persistentItemsAt(position: ToastPosition<TPositions>): ToastItem<readonly [], TPositions, TContent>[];
+    activeTimedItemsAt(position: ToastPosition<TPositions>): ToastItem<readonly [], TPositions, TContent>[];
+    activePersistentItemsAt(position: ToastPosition<TPositions>): ToastItem<readonly [], TPositions, TContent>[];
+    isVisibleAt(position: ToastPosition<TPositions>, index: number): boolean;
+    /**
+     * Public escape hatch for callers (mainly the magic's `fromPayload`)
+     * that need to push a toast from a raw `ToastEventPayload` shape.
+     */
+    fromPayload(payload?: ToastPayload<readonly [], TPositions, TContent>): string;
+}
+/**
+ * Wraps a {@link ToastController} in the {@link ToastStore} surface.
+ * The store's reads delegate to the controller; mutations go
+ * through the controller's semantic commands.
+ *
+ * The wrapper subscribes to the controller's `change` event so its
+ * own `items` property stays in sync with the controller's queue —
+ * that subscription is what keeps standalone consumers (`store.items`
+ * reads in tests, scripts) up to date. Alpine consumers also benefit
+ * because the wrapper's `items` is a regular settable property,
+ * which means Alpine's reactive proxy can intercept assignments
+ * through its SET trap and trigger template re-renders.
+ *
+ * The Alpine adapter (`plugin.ts`) registers its own subscription
+ * that mirrors changes into the proxy via the SET trap — that is
+ * what triggers Alpine's reactivity. The wrapper's own subscription
+ * keeps `store.items` fresh in standalone use and provides a
+ * redundant but safe update path in Alpine use (Alpine's SET trap
+ * still fires because the proxy's cached value lags the target's
+ * direct mutation).
+ *
+ * `destroy()` unsubscribes the internal listener AND forwards to
+ * the controller's destroy so callers have one entry point.
+ *
+ * Used both by `toastPlugin` (to register with Alpine) and by the
+ * standalone {@link createToastStore} factory.
+ */
+declare function wrapToastStore<const TPositions extends readonly string[] = readonly [], TContent = unknown>(controller: ToastController<TPositions, TContent>): ToastStore<readonly [], TPositions, TContent>;
+/**
+ * Standalone factory — creates a fresh (non-singleton)
+ * {@link ToastController} and returns the {@link ToastStore}
+ * surface. Useful for tests, scripts, and non-Alpine consumers
+ * that need a one-off queue.
+ *
+ * Each call returns a NEW controller; for the document-level
+ * singleton pattern, use {@link createToastController} instead.
+ */
+declare function createToastStore<const TPositions extends readonly string[] = readonly [], TContent = unknown>(options?: CreateToastControllerOptions<TPositions, TContent>): ToastStore<readonly [], TPositions, TContent>;
+/**
+ * Timed duration for `$toast.promise` loading state.
+ * Stays in the timed stack; the timer is replaced when the promise
+ * settles. Exported from `./index.ts` so consumers can compare
+ * against the sentinel without importing the controller module.
+ */
+declare const PROMISE_LOADING_DURATION = 3600000;
+/** Canonical persistent value — `0` is normalized to `false`. */
+declare function normalizeToastDuration(duration: ToastDuration): ToastDuration;
+/** Resolves payload duration — `false` / `0` persist; `undefined` uses the default. */
+declare function resolveToastDuration(duration: ToastDuration | undefined, defaultDuration: number): ToastDuration;
+/** Whether the toast should schedule an auto-dismiss timer. */
+declare function shouldAutoDismiss(duration: ToastDuration): duration is number;
+/** Persistent toasts (`duration: false` / `0`) use a separate UI stack from timed toasts. */
+declare function isPersistentDuration(duration: ToastDuration): boolean;
+/** Resolves `maxToasts` / `maxVisible` with the standard clamp rule. */
 declare function resolveToastLimits(options?: {
     maxToasts?: number;
     maxVisible?: number;
@@ -193,33 +541,53 @@ declare function resolveToastLimits(options?: {
 };
 /** Unique stack keys: built-in default plus configured positions. */
 declare function resolveStackPositions<TPositions extends readonly string[]>(defaultPosition: ToastPosition<TPositions>, positions?: TPositions): readonly ToastPosition<TPositions>[];
-/** Canonical persistent value — `0` is normalized to `false`. */
-declare function normalizeToastDuration(duration: ToastDuration): ToastDuration;
-/** Resolves payload duration — `false` / `0` persist; `undefined` uses the default. */
-declare function resolveToastDuration(duration: ToastDuration | undefined, defaultDuration: number): ToastDuration;
-/** Whether the toast should schedule an auto-dismiss timer. */
-declare function shouldAutoDismiss(duration: ToastDuration): duration is number;
-/** Persistent toasts (`duration: false` / `0`) use a separate UI stack from timed toasts. */
-declare function isPersistentDuration(duration: ToastDuration): boolean;
+
 /**
- * Timed duration for `$toast.promise` loading state.
- * Stays in the timed stack; the timer is replaced when the promise settles.
+ * Alpine.js integration for `@ailuracode/alpine-toast`.
+ *
+ * Thin adapter that wires {@link ToastController} into `$store.toast`
+ * and the `$toast` magic. Every command forwards to the controller
+ * (see `AGENTS.md` for the integration contract).
  */
-declare const PROMISE_LOADING_DURATION = 3600000;
-/** Creates the internal reactive toast queue consumed by `$toast` and UI integrators. */
-declare function createToastStore<const TPositions extends readonly string[] = readonly [], TContent = unknown>(options?: CreateToastStoreOptions<TPositions>): ToastStore<readonly [], TPositions, TContent>;
 
-/** Alpine.js toast plugin. Registers magic `$toast` with an internal reactive queue. CSS-framework agnostic — no markup or styles. */
-declare function toastPlugin<const TVariants extends readonly string[] = readonly [], const TPositions extends readonly string[] = readonly [], TContent = unknown>(optionsOrAlpine?: ToastPluginOptions<TVariants, TPositions, TContent> | AlpineType.Alpine): undefined | ((Alpine: AlpineType.Alpine) => void);
-declare global {
-    namespace Alpine {
-        interface Stores {
-            toast: ToastStore;
-        }
-        interface Magics<T> {
-            $toast: ToastMagic;
-        }
-    }
-}
+/** Variant names that cannot override core `$toast` methods. */
+declare const RESERVED_TOAST_MAGIC_KEYS: Set<string>;
+/** Resolves plugin options with defaults and queue limit rules. */
+declare function resolveToastPluginConfig<const TVariants extends readonly string[] = readonly [], const TPositions extends readonly string[] = readonly []>(options?: ToastPluginOptions<TVariants, TPositions>): ResolvedToastPluginConfig<TVariants, TPositions>;
+/** Builds typed toast plugin options with inferred variant and position literals. */
+declare function toastOptions<const TVariants extends readonly string[] = readonly [], const TPositions extends readonly string[] = readonly [], TContent = unknown>(options: ToastPluginOptions<TVariants, TPositions, TContent>): ToastPluginOptions<TVariants, TPositions, TContent>;
+/** Declares toast variant names with full literal inference. */
+declare function toastVariants<const T extends readonly string[]>(variants: T): T;
+/** Declares toast position names with full literal inference. */
+declare function toastPositions<const T extends readonly string[]>(positions: T): T;
+/**
+ * Plugin factory — returns the `Alpine.plugin()` callback. Pass
+ * {@link ToastPluginOptions} to configure {@link ToastController},
+ * or `{}` for the package defaults. See `AGENTS.md` for the
+ * integration contract.
+ */
+declare function toastPlugin<const TVariants extends readonly string[] = readonly [], const TPositions extends readonly string[] = readonly [], TContent = unknown>(options?: ToastPluginOptions<TVariants, TPositions, TContent>): ToastPluginCallback;
+/**
+ * Wraps a {@link ToastController} in the {@link ToastStore} surface
+ * that Alpine consumers (templates, `$store.toast.*` references)
+ * see. The store's reads delegate to the controller; mutations go
+ * through the controller's semantic commands.
+ *
+ * The store is intentionally a thin object literal — every field is
+ * a direct getter into the controller, and every method is a one-line
+ * delegation. Splitting helpers would add indirection without buying
+ * anything because the controller already exposes the entire surface.
+ *
+ * The implementation lives in `./controller.ts` (see
+ * {@link wrapToastStore}) so both `toastPlugin` and the standalone
+ * `createToastStore` factory can share it.
+ */
+/**
+ * Builds the callable `$toast` magic API. The magic delegates every
+ * command to the store accessor passed in by the caller — typically
+ * `() => Alpine.store("toast")` so the magic stays reactive, but
+ * tests inject their own store.
+ */
+declare function createToastMagic<const TVariants extends readonly string[], const TPositions extends readonly string[] = readonly [], TContent = unknown>(config: ResolvedToastPluginConfig<TVariants, TPositions>, getStore: () => ToastStore<TVariants, TPositions, TContent>): ToastMagic<TVariants, TPositions, TContent>;
 
-export { type DefaultToastPosition, type DefaultToastVariant, PROMISE_LOADING_DURATION, RESERVED_TOAST_MAGIC_KEYS, type ResolvedPromiseConfig, type ResolvedToastPluginConfig, TOAST_STORE_KEY, type ToastAction, type ToastDuration, type ToastEventPayload, type ToastItem, type ToastMagic, type ToastPayload, type ToastPayloadWithoutVariant, type ToastPluginOptions, type ToastPosition, type ToastPromiseInput, type ToastPromiseMessages, type ToastPromiseOptions, type ToastStore, type ToastStoreKey, type ToastVariant, type ToastVariantMethods, createToastMagic, createToastStore, toastPlugin as default, isPersistentDuration, normalizeToastDuration, resolveStackPositions, resolveToastDuration, resolveToastLimits, resolveToastPluginConfig, shouldAutoDismiss, toastOptions, toastPositions, toastVariants };
+export { type CreateToastControllerOptions, type CreateToastStoreOptions, type DefaultToastPosition, type DefaultToastVariant, PROMISE_LOADING_DURATION, RESERVED_TOAST_MAGIC_KEYS, type ResolvedPromiseConfig, type ResolvedToastPluginConfig, TOAST_MAGIC_KEY, TOAST_STORE_KEY, type ToastAction, type ToastAlpine, type ToastChangeDetail, type ToastChangeSource, ToastController, type ToastDuration, type ToastEventPayload, type ToastEvents, type ToastItem, type ToastListener, type ToastMagic, type ToastMagicKey, type ToastManager, type ToastPayload, type ToastPayloadWithoutVariant, type ToastPluginCallback, type ToastPluginOptions, type ToastPosition, type ToastPromiseInput, type ToastPromiseMessages, type ToastPromiseOptions, type ToastStore, type ToastStoreKey, type ToastVariant, type ToastVariantMethods, createToastController, createToastMagic, createToastStore, toastPlugin as default, isPersistentDuration, normalizeToastDuration, resolveStackPositions, resolveToastDuration, resolveToastLimits, resolveToastPluginConfig, shouldAutoDismiss, toastOptions, toastPlugin, toastPositions, toastVariants, wrapToastStore };