@lavalogic/scoria 0.35.0 → 0.37.0

package/dist/Contexts/ToastContext.svelte.js

@@ -1,6 +1,12 @@
+import { dev } from '$app/environment';
 import { getErrorMessage } from '../Helpers/Helpers.svelte.js';
 import { Validity } from '../Types/Internal/Validity.js';
-let idIncrement = 0;
+/**
+ * Narrows an unknown value to a wrapped-HTTP-response shape:
+ * `{ payload: { data: string } }`. Used by {@link ToastContext.toast}
+ * so that consumers can pass an unwrapped service response straight
+ * into the toast layer without an explicit cast.
+ */
 function isWrappedResponse(message) {
     return (message != null &&
         typeof message == 'object' &&
@@ -10,23 +16,73 @@ function isWrappedResponse(message) {
         'data' in message.payload &&
         typeof message.payload.data == 'string');
 }
+/**
+ * Narrows an object to {@link ToastMessage}: requires both a `result`
+ * field that is a recognised {@link Validity} value and a `message`
+ * field of type `string`. Previously this guard accepted any object
+ * with a `result` property; tightened to actually validate the shape.
+ */
+function isToastMessage(message) {
+    if (!('result' in message) || !('message' in message)) {
+        return false;
+    }
+    const m = message;
+    if (typeof m.message !== 'string') {
+        return false;
+    }
+    return (m.result === Validity.Invalid ||
+        m.result === Validity.Valid ||
+        m.result === Validity.Info ||
+        m.result === Validity.Warning ||
+        m.result === Validity.Neutral);
+}
+/**
+ * Default per-toast lifetime in milliseconds. Mirrors the value
+ * referenced from `ToastMessage.timeout` JSDoc.
+ */
+const DEFAULT_TOAST_TIMEOUT_MS = 10000;
+/**
+ * Application context driving the global `ToastContainer` host.
+ *
+ * The id counter is an instance field so multiple contexts (e.g.
+ * tests or HMR-reloaded hosts) do not collide. Verbose copy output
+ * (stack trace, cause chain) is gated on `$app/environment.dev`
+ * so production users cannot leak backend internals to the
+ * clipboard.
+ */
 export class ToastContext {
+    /** Stable lookup symbol used by `getContext`/`setContext`. */
     static identifier = Symbol();
+    idIncrement = 0;
     _toasts = $state([]);
+    /**
+     * The currently visible toasts. Returned as a `ReadonlyArray` so
+     * consumers cannot mutate the internal queue; use {@link ToastContext.toast}
+     * to add and `IdentifiableToastMessage.close` to remove.
+     */
     get toasts() {
         return this._toasts;
     }
     set toasts(v) {
-        this._toasts = v;
+        this._toasts = [...v];
     }
+    // The handles map is non-reactive bookkeeping; SvelteMap would just add overhead.
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity
+    timeoutHandles = new Map();
+    /**
+     * Queues a toast for display. Accepts `string`, `ReadonlyArray<string>`,
+     * `Error`, {@link ToastMessage}, the wrapped HTTP response shape, or
+     * anything else (rendered as "Unknown Error"). `null` / `undefined`
+     * are silently dropped.
+     */
     toast = (message) => {
         if (message == null) {
             return;
         }
-        const id = idIncrement++;
+        const id = this.idIncrement++;
         const newMessage = (() => {
             const closeable = true;
-            const timeout = 10000;
+            const timeout = DEFAULT_TOAST_TIMEOUT_MS;
             if (Array.isArray(message)) {
                 return {
                     result: Validity.Info,
@@ -68,8 +124,8 @@ export class ToastContext {
                         },
                         getVerbose: () => getErrorMessage(message, {
                             includeUUID: true,
-                            includeCause: true,
-                            includeStack: true,
+                            includeCause: dev,
+                            includeStack: dev,
                         }),
                     };
                 }
@@ -86,18 +142,18 @@ export class ToastContext {
                         },
                     };
                 }
-            }
-            if (isWrappedResponse(message)) {
-                return {
-                    result: Validity.Info,
-                    closeable,
-                    timeout,
-                    message: message.payload.data,
-                    id,
-                    close: () => {
-                        this.dismiss(id);
-                    },
-                };
+                if (isWrappedResponse(message)) {
+                    return {
+                        result: Validity.Info,
+                        closeable,
+                        timeout,
+                        message: message.payload.data,
+                        id,
+                        close: () => {
+                            this.dismiss(id);
+                        },
+                    };
+                }
             }
             return {
                 result: Validity.Invalid,
@@ -108,17 +164,33 @@ export class ToastContext {
                 close: () => {
                     this.dismiss(id);
                 },
-                getVerbose: () => getErrorMessage(message),
+                getVerbose: () => getErrorMessage(message, {
+                    includeUUID: true,
+                    includeCause: dev,
+                    includeStack: dev,
+                }),
             };
         })();
-        this.toasts.push(newMessage);
+        this._toasts.push(newMessage);
         if (newMessage.timeout) {
-            setTimeout(() => {
+            const handle = setTimeout(() => {
+                this.timeoutHandles.delete(newMessage.id);
                 this.dismiss(newMessage.id);
             }, newMessage.timeout);
+            this.timeoutHandles.set(newMessage.id, handle);
         }
     };
+    /**
+     * Removes the toast with the given id from the visible queue and
+     * clears any pending auto-dismiss timer so the closure does not
+     * leak.
+     */
     dismiss(id) {
+        const handle = this.timeoutHandles.get(id);
+        if (handle !== undefined) {
+            clearTimeout(handle);
+            this.timeoutHandles.delete(id);
+        }
         const index = this._toasts.findIndex((it) => it.id === id);
         if (index != -1) {
             const [removed] = this._toasts.splice(index, 1);
@@ -126,6 +198,3 @@ export class ToastContext {
         }
     }
 }
-function isToastMessage(message) {
-    return 'result' in message;
-}

package/dist/Contexts/TooltipContext.svelte.d.ts

@@ -1,31 +1,98 @@
 import type { Delay } from '../Delay/Delay.js';
 import { Side } from '../Types/Internal/Side.js';
+/**
+ * Application context driving the global `Tooltip` host.
+ *
+ * The visual host (`Components/Contexts/Tooltip.svelte`, mounted by
+ * `Components/Base/ContextWrapper.svelte`) listens to `x`, `y`,
+ * `text`, `anchor`, and `isShowingTooltip` and renders the tooltip
+ * accordingly. Consumers (Button, Action, NavTab, ...) call
+ * {@link TooltipContext.showTooltip} on `mouseenter`/`focus` and
+ * {@link TooltipContext.hideTooltip} on `mouseleave`/`blur`/`click`
+ * and on component unmount.
+ *
+ * Conforms to the canonical scoria context pattern:
+ * - `static readonly identifier = Symbol()`.
+ * - Private runes-backed fields exposed via getter / private setter.
+ *
+ * Stale-tooltip cleanup contract: consumers are responsible for
+ * calling `hideTooltip` in their unmount handler when they have
+ * called `showTooltip` and the user has not yet moved focus or
+ * mouse away. Without this, a component that unmounts mid-hover
+ * leaves its tooltip visible indefinitely.
+ */
 export declare class TooltipContext {
+    /** Stable lookup symbol used by `getContext`/`setContext`. */
     static readonly identifier: unique symbol;
     private _x;
+    /** Tooltip x-coordinate in viewport-relative CSS pixels. */
     get x(): number;
     private set x(value);
     private _y;
+    /** Tooltip y-coordinate in viewport-relative CSS pixels. */
     get y(): number;
     private set y(value);
     private _text;
+    /**
+     * The text currently shown in the tooltip. `undefined` when the
+     * tooltip is hidden.
+     */
     get text(): string | undefined;
     private set text(value);
     private _anchor;
+    /** The side of the anchor element the tooltip arrow points to. */
     get anchor(): Side;
     private set anchor(value);
     private _isShowingTooltip;
+    /**
+     * Whether the visual host should render. The host treats this as
+     * a strict "draw / do not draw" toggle.
+     */
     get isShowingTooltip(): boolean;
     private set isShowingTooltip(value);
+    /**
+     * Tracks the pending show-tooltip debounce timer. Initialised to
+     * the sentinel value `undefined`; `clearTimeout(undefined)` is a
+     * documented no-op.
+     */
     private timeout;
+    /**
+     * Requests that the tooltip be shown with the given text, anchor
+     * side, and bounding rectangle. The actual draw is delayed by
+     * `props.delay` (typically `Delay.Default`) so transient hovers
+     * do not flash a tooltip.
+     *
+     * Any pending show-timer is cleared before scheduling the new
+     * one, so rapid hover transitions cancel cleanly.
+     */
     readonly showTooltip: (props: TooltipProps) => void;
-    hideTooltip: (value: string) => void;
+    /**
+     * Hides the tooltip if its current text matches the given value.
+     * The text-compare is a structural race-guard: when two
+     * consumers race show/hide on different labels, the wrong
+     * consumer's `hideTooltip` does not clobber the right
+     * consumer's `showTooltip`.
+     *
+     * Note: a future migration may switch this to a handle-based
+     * API returning an `Unsubscriber` from `showTooltip`. Tracked
+     * in the TooltipContext workorder.
+     */
+    readonly hideTooltip: (value: string) => void;
 }
+/**
+ * Configuration accepted by {@link TooltipContext.showTooltip}.
+ */
 export interface TooltipProps {
+    /** The visible tooltip text. */
     text: string;
+    /** Bounding rect of the anchor element (in viewport-relative pixels). */
     rect: DOMRect;
+    /** The side of the anchor the arrow points to. */
     arrow: Side;
+    /** Optional show-delay in milliseconds. */
     delay?: Delay;
+    /** Optional additional x-offset applied after anchor maths. */
     offsetX?: number;
+    /** Optional additional y-offset applied after anchor maths. */
     offsetY?: number;
 }

package/dist/Contexts/TooltipContext.svelte.js

@@ -1,7 +1,38 @@
 import { Side } from '../Types/Internal/Side.js';
+/**
+ * CSS arrow-half-width in pixels. Matches the `border-width` set
+ * on the `.arrow` pseudo-element in `Tooltip.svelte`. Centralised
+ * here so the layout maths and the visual styling cannot drift
+ * silently. When updating, also update the matching value in
+ * `Components/Contexts/Tooltip.svelte`.
+ */
+const ARROW_HALF_WIDTH_PX = 6;
+/**
+ * Application context driving the global `Tooltip` host.
+ *
+ * The visual host (`Components/Contexts/Tooltip.svelte`, mounted by
+ * `Components/Base/ContextWrapper.svelte`) listens to `x`, `y`,
+ * `text`, `anchor`, and `isShowingTooltip` and renders the tooltip
+ * accordingly. Consumers (Button, Action, NavTab, ...) call
+ * {@link TooltipContext.showTooltip} on `mouseenter`/`focus` and
+ * {@link TooltipContext.hideTooltip} on `mouseleave`/`blur`/`click`
+ * and on component unmount.
+ *
+ * Conforms to the canonical scoria context pattern:
+ * - `static readonly identifier = Symbol()`.
+ * - Private runes-backed fields exposed via getter / private setter.
+ *
+ * Stale-tooltip cleanup contract: consumers are responsible for
+ * calling `hideTooltip` in their unmount handler when they have
+ * called `showTooltip` and the user has not yet moved focus or
+ * mouse away. Without this, a component that unmounts mid-hover
+ * leaves its tooltip visible indefinitely.
+ */
 export class TooltipContext {
+    /** Stable lookup symbol used by `getContext`/`setContext`. */
     static identifier = Symbol();
     _x = $state(0);
+    /** Tooltip x-coordinate in viewport-relative CSS pixels. */
     get x() {
         return this._x;
     }
@@ -9,6 +40,7 @@ export class TooltipContext {
         this._x = v;
     }
     _y = $state(0);
+    /** Tooltip y-coordinate in viewport-relative CSS pixels. */
     get y() {
         return this._y;
     }
@@ -16,6 +48,10 @@ export class TooltipContext {
         this._y = v;
     }
     _text = $state();
+    /**
+     * The text currently shown in the tooltip. `undefined` when the
+     * tooltip is hidden.
+     */
     get text() {
         return this._text;
     }
@@ -23,6 +59,7 @@ export class TooltipContext {
         this._text = v;
     }
     _anchor = $state(Side.Top);
+    /** The side of the anchor element the tooltip arrow points to. */
     get anchor() {
         return this._anchor;
     }
@@ -30,27 +67,41 @@ export class TooltipContext {
         this._anchor = v;
     }
     _isShowingTooltip = $state(false);
+    /**
+     * Whether the visual host should render. The host treats this as
+     * a strict "draw / do not draw" toggle.
+     */
     get isShowingTooltip() {
         return this._isShowingTooltip;
     }
     set isShowingTooltip(v) {
         this._isShowingTooltip = v;
     }
-    timeout = -1;
+    /**
+     * Tracks the pending show-tooltip debounce timer. Initialised to
+     * the sentinel value `undefined`; `clearTimeout(undefined)` is a
+     * documented no-op.
+     */
+    timeout = undefined;
+    /**
+     * Requests that the tooltip be shown with the given text, anchor
+     * side, and bounding rectangle. The actual draw is delayed by
+     * `props.delay` (typically `Delay.Default`) so transient hovers
+     * do not flash a tooltip.
+     *
+     * Any pending show-timer is cleared before scheduling the new
+     * one, so rapid hover transitions cancel cleanly.
+     */
     showTooltip = (props) => {
         clearTimeout(this.timeout);
-        if (this.isShowingTooltip) {
-            this.isShowingTooltip = false;
-            this.text = undefined;
-        }
         this.text = props.text;
         this.anchor = props.arrow;
         const totalOffsetX = (props.offsetX ?? 0) +
             (props.arrow === Side.Top || props.arrow === Side.Bottom
                 ? props.rect.width / 2
                 : props.arrow === Side.Right
-                    ? -6 //  arrow width
-                    : props.rect.width + 6); // arrow width
+                    ? -ARROW_HALF_WIDTH_PX
+                    : props.rect.width + ARROW_HALF_WIDTH_PX);
         const totalOffsetY = (props.offsetY ?? 0) +
             (props.arrow === Side.Left || props.arrow === Side.Right
                 ? props.rect.height / 2
@@ -68,9 +119,21 @@ export class TooltipContext {
             this.isShowingTooltip = true;
         }
     };
+    /**
+     * Hides the tooltip if its current text matches the given value.
+     * The text-compare is a structural race-guard: when two
+     * consumers race show/hide on different labels, the wrong
+     * consumer's `hideTooltip` does not clobber the right
+     * consumer's `showTooltip`.
+     *
+     * Note: a future migration may switch this to a handle-based
+     * API returning an `Unsubscriber` from `showTooltip`. Tracked
+     * in the TooltipContext workorder.
+     */
     hideTooltip = (value) => {
         if (this.text === value) {
             clearTimeout(this.timeout);
+            this.timeout = undefined;
             this.isShowingTooltip = false;
             this.text = undefined;
         }

package/dist/Contexts/UntypedInputContext.svelte.d.ts

@@ -1,16 +1,65 @@
-export type StringCallback = (value: string) => boolean | Promise<boolean>;
 import type { Unsubscriber } from '../Types/Internal/Misc.js';
+/**
+ * Callback signature accepted by
+ * {@link UntypedInputContext.registerListener}. Returns - or
+ * resolves to - `true` to stop propagation, `false` to continue
+ * the chain.
+ */
+export type UntypedInputListener = (value: string) => boolean | Promise<boolean>;
+/**
+ * Legacy alias for {@link UntypedInputListener}. Prefer
+ * `UntypedInputListener` in new code; this re-export is kept for
+ * backwards compatibility with existing consumers.
+ */
+export type StringCallback = UntypedInputListener;
+/**
+ * Application context that buffers global keystrokes so a hardware
+ * barcode scanner (which delivers each character as a synthesised
+ * `keydown` and terminates with Enter) can be treated as a single
+ * "command" without occupying a visible focusable input.
+ *
+ * Security model:
+ * - Treats any sequence of keydowns terminated by `Enter`, while
+ *   focus is not inside an `INPUT`/`TEXTAREA`/`BUTTON`/`A`, as a
+ *   trusted command.
+ * - Synthetic events (`e.isTrusted === false`) are ignored to
+ *   blunt the easiest attack vector.
+ * - Listeners are run from most-recently registered to oldest,
+ *   and may short-circuit by returning `true`.
+ */
 export declare class UntypedInputContext {
-    private debug;
-    constructor(debug?: boolean);
+    private readonly debug;
+    /** Stable lookup symbol used by `getContext`/`setContext`. */
     static readonly identifier: unique symbol;
+    /**
+     * @param debug - When `true`, internal state transitions are
+     *   logged via `console.log`.
+     */
+    constructor(debug?: boolean);
     private readonly registeredListeners;
-    readonly registerListener: (listener: StringCallback) => Unsubscriber;
+    /**
+     * Registers a listener to receive each fully-buffered untyped
+     * value. Returns an {@link Unsubscriber} that removes it again.
+     */
+    readonly registerListener: (listener: UntypedInputListener) => Unsubscriber;
+    /**
+     * Fires the registered listeners in reverse-registration order
+     * with the current untyped value. Snapshots the listener array
+     * before iterating so a listener that mutates the registration
+     * set during its own invocation does not corrupt the loop.
+     * Short-circuits on the first listener that returns truthy.
+     */
     private readonly fire;
     private _untypedValue;
+    /** The current buffered untyped value. Cleared after fire and after debounce. */
     get untypedValue(): string;
     private set untypedValue(value);
     private debounceTimer;
-    private readonly tagNameSet;
+    /**
+     * Global `keydown` handler. Ignores synthetic events, passes
+     * through to inputs/buttons/links, buffers single-character
+     * keys, and fires the listener chain on `Enter` or after
+     * {@link UNTYPED_DEBOUNCE_MS} of idle.
+     */
     readonly handleGlobalKeydown: (e: KeyboardEvent) => void;
 }

package/dist/Contexts/UntypedInputContext.svelte.js

@@ -1,13 +1,47 @@
 import { dev } from '$app/environment';
 import { devCatch } from '../Helpers/Helpers.svelte.js';
-import { SvelteSet } from 'svelte/reactivity';
+/**
+ * The set of `activeElement.tagName` values for which the global
+ * keydown listener bows out. If focus is inside any of these the
+ * keystroke is treated as ordinary form input.
+ */
+const FOCUSABLE_TAG_NAMES = new Set(['INPUT', 'TEXTAREA', 'BUTTON', 'A']);
+/**
+ * Debounce in milliseconds after which the untyped buffer is
+ * cleared without firing.
+ */
+const UNTYPED_DEBOUNCE_MS = 500;
+/**
+ * Application context that buffers global keystrokes so a hardware
+ * barcode scanner (which delivers each character as a synthesised
+ * `keydown` and terminates with Enter) can be treated as a single
+ * "command" without occupying a visible focusable input.
+ *
+ * Security model:
+ * - Treats any sequence of keydowns terminated by `Enter`, while
+ *   focus is not inside an `INPUT`/`TEXTAREA`/`BUTTON`/`A`, as a
+ *   trusted command.
+ * - Synthetic events (`e.isTrusted === false`) are ignored to
+ *   blunt the easiest attack vector.
+ * - Listeners are run from most-recently registered to oldest,
+ *   and may short-circuit by returning `true`.
+ */
 export class UntypedInputContext {
     debug;
+    /** Stable lookup symbol used by `getContext`/`setContext`. */
+    static identifier = Symbol();
+    /**
+     * @param debug - When `true`, internal state transitions are
+     *   logged via `console.log`.
+     */
     constructor(debug = false) {
         this.debug = debug;
     }
-    static identifier = Symbol();
     registeredListeners = [];
+    /**
+     * Registers a listener to receive each fully-buffered untyped
+     * value. Returns an {@link Unsubscriber} that removes it again.
+     */
     registerListener = (listener) => {
         this.registeredListeners.push(listener);
         return () => {
@@ -20,54 +54,73 @@ export class UntypedInputContext {
             }
         };
     };
+    /**
+     * Fires the registered listeners in reverse-registration order
+     * with the current untyped value. Snapshots the listener array
+     * before iterating so a listener that mutates the registration
+     * set during its own invocation does not corrupt the loop.
+     * Short-circuits on the first listener that returns truthy.
+     */
     fire = async () => {
-        for (let i = this.registeredListeners.length - 1; i > -1; i--) {
-            const shouldStop = await this.registeredListeners[i](this.untypedValue);
+        const snapshot = [...this.registeredListeners];
+        const value = this.untypedValue;
+        for (let i = snapshot.length - 1; i > -1; i--) {
+            const listener = snapshot[i];
+            const shouldStop = await listener(value);
             if (shouldStop) {
                 return;
             }
         }
     };
     _untypedValue = $state('');
+    /** The current buffered untyped value. Cleared after fire and after debounce. */
     get untypedValue() {
         return this._untypedValue;
     }
     set untypedValue(v) {
         this._untypedValue = v;
     }
-    debounceTimer = $state(-1);
-    tagNameSet = new SvelteSet().add('INPUT').add('TEXTAREA').add('BUTTON').add('A');
+    debounceTimer = undefined;
+    /**
+     * Global `keydown` handler. Ignores synthetic events, passes
+     * through to inputs/buttons/links, buffers single-character
+     * keys, and fires the listener chain on `Enter` or after
+     * {@link UNTYPED_DEBOUNCE_MS} of idle.
+     */
     handleGlobalKeydown = (e) => {
-        if (!this.tagNameSet.has(document.activeElement?.tagName)) {
-            clearTimeout(this.debounceTimer);
-            if (e.key === 'Enter') {
-                if (this.debug) {
-                    console.log('firing');
-                }
-                this.fire().catch(devCatch);
-                if (this.debug) {
-                    console.log('clearing');
-                }
-                this.untypedValue = '';
-                return;
+        if (!e.isTrusted) {
+            if (this.debug) {
+                console.log('ignoring synthetic event');
             }
-            if (e.key.length == 1) {
-                if (this.debug) {
-                    console.log(`adding ${e.key}`);
-                }
-                this.untypedValue += e.key;
+            return;
+        }
+        const tag = document.activeElement?.tagName;
+        if (tag && FOCUSABLE_TAG_NAMES.has(tag)) {
+            return;
+        }
+        clearTimeout(this.debounceTimer);
+        if (e.key === 'Enter') {
+            if (this.debug) {
+                console.log('firing');
             }
-            // else {
-            // 	if (dev) {
-            // 		console.log(`found non-single length key ${e.key}`);
-            // 	}
-            // }
-            this.debounceTimer = setTimeout(() => {
-                if (this.debug) {
-                    console.log('clearing due to debounce');
-                }
-                this.untypedValue = '';
-            }, 500);
+            this.fire().catch(devCatch);
+            if (this.debug) {
+                console.log('clearing');
+            }
+            this.untypedValue = '';
+            return;
+        }
+        if (e.key.length == 1) {
+            if (this.debug) {
+                console.log(`adding ${e.key}`);
+            }
+            this.untypedValue += e.key;
         }
+        this.debounceTimer = setTimeout(() => {
+            if (this.debug) {
+                console.log('clearing due to debounce');
+            }
+            this.untypedValue = '';
+        }, UNTYPED_DEBOUNCE_MS);
     };
 }

package/dist/Delay/Delay.js

@@ -1,4 +1,4 @@
 export const Delay = {
-    Default: 300
+    Default: 300,
 };
 Object.freeze(Delay);

package/dist/Helpers/AsyncFlag.svelte.d.ts

@@ -0,0 +1,39 @@
+import type { AsyncFlag } from '../Types/Internal/AsyncFlag.js';
+/**
+ * The result returned by {@link useAsyncFlag}. Exposes the latest resolved
+ * value of the flag through a readonly `value` getter that is backed by
+ * `$state`, so consumers reading it inside a reactive scope automatically
+ * re-render when the resolution changes.
+ */
+export interface AsyncFlagResult<T> {
+    readonly value: T;
+}
+/**
+ * Reactively resolve a prop that may be either a bare value or a Promise
+ * of that value (see {@link AsyncFlag}). Centralises the boolean-or-Promise
+ * pattern used pervasively across button, tab, and modal families.
+ *
+ * Behaviour:
+ * - If `input()` returns a non-Promise value, `value` is set synchronously.
+ * - If `input()` returns `undefined`, `value` falls back to `fallback`.
+ * - If `input()` returns a Promise, `value` stays at the current resolution
+ *   until the Promise settles. A sequence counter discards stale resolutions
+ *   so that, when several Promises overlap, the most recently issued one
+ *   wins regardless of resolution order.
+ * - Rejected Promises do not flip `value` back; the previous valid resolution
+ *   (or `fallback`) is preserved.
+ *
+ * Errors are routed through {@link ToastContext.toast} when a context is
+ * available (i.e. the consumer is rendered inside `ContextWrapper`), and
+ * fall back to {@link devCatch} otherwise. The helper looks the context up
+ * once at initialisation time.
+ *
+ * @param input A thunk returning the current flag value or a Promise of it.
+ *              Wrapped in a thunk so the helper can establish its own
+ *              `$effect` dependency on whatever reactive state the caller
+ *              reads inside.
+ * @param fallback The value to use while no resolution is available, and
+ *                 the value returned when `input()` is `undefined`.
+ * @returns An {@link AsyncFlagResult} exposing the latest resolved value.
+ */
+export declare function useAsyncFlag<T>(input: () => AsyncFlag<T> | undefined, fallback: T): AsyncFlagResult<T>;