@avail-project/widgets 0.0.1

package/README.md

@@ -0,0 +1,34 @@
+# @avail-project/widgets
+
+Public npm distribution for Avail widgets.
+
+Install from npm:
+
+```bash
+pnpm add @avail-project/widgets
+```
+
+For internal GitHub installs, the package runs its `prepare` script and builds `dist` after clone:
+
+```bash
+pnpm add github:availproject/widgets
+```
+
+```tsx
+import { NexusProvider, NexusWidget } from "@avail-project/widgets";
+
+export function App() {
+  return (
+    <NexusProvider config={{ network: "mainnet", debug: false }}>
+      <NexusWidget config={{ mode: "swap" }} />
+    </NexusProvider>
+  );
+}
+```
+
+The shadcn registry remains the open source code-install path. Until the
+namespace is listed in shadcn, install with:
+
+```bash
+npx shadcn@latest add availproject/widgets/nexus
+```

package/dist/common/components/ErrorBoundary.d.ts

@@ -0,0 +1,44 @@
+import { Component, type ErrorInfo, type ReactNode } from "react";
+interface ErrorBoundaryProps {
+    children: ReactNode;
+    fallback?: ReactNode;
+    onError?: (error: Error, errorInfo: ErrorInfo) => void;
+}
+interface ErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+}
+/**
+ * Error boundary component that catches JavaScript errors in child components.
+ * Displays a fallback UI instead of crashing the entire widget.
+ *
+ * @example
+ * <ErrorBoundary
+ *   fallback={<div>Something went wrong</div>}
+ *   onError={(error) => console.error(error)}
+ * >
+ *   <MyComponent />
+ * </ErrorBoundary>
+ */
+export declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    constructor(props: ErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    render(): ReactNode;
+}
+/**
+ * A more specific error boundary for widget containers with reset capability.
+ */
+interface WidgetErrorBoundaryProps extends ErrorBoundaryProps {
+    widgetName?: string;
+    onReset?: () => void;
+}
+export declare class WidgetErrorBoundary extends Component<WidgetErrorBoundaryProps, ErrorBoundaryState> {
+    constructor(props: WidgetErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    handleReset: () => void;
+    render(): ReactNode;
+}
+export {};
+//# sourceMappingURL=ErrorBoundary.d.ts.map

package/dist/common/components/ErrorBoundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorBoundary.d.ts","sourceRoot":"","sources":["../../../.build-src/common/components/ErrorBoundary.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAElE,UAAU,kBAAkB;IAC1B,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,KAAK,IAAI,CAAC;CACxD;AAED,UAAU,kBAAkB;IAC1B,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,aAAc,SAAQ,SAAS,CAC1C,kBAAkB,EAClB,kBAAkB,CACnB;gBACa,KAAK,EAAE,kBAAkB;IAKrC,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,KAAK,GAAG,kBAAkB;IAIjE,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,GAAG,IAAI;IAK3D,MAAM,IAAI,SAAS;CA0BpB;AAED;;GAEG;AACH,UAAU,wBAAyB,SAAQ,kBAAkB;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACtB;AAED,qBAAa,mBAAoB,SAAQ,SAAS,CAChD,wBAAwB,EACxB,kBAAkB,CACnB;gBACa,KAAK,EAAE,wBAAwB;IAK3C,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,KAAK,GAAG,kBAAkB;IAIjE,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,GAAG,IAAI;IAS3D,WAAW,QAAO,IAAI,CAGpB;IAEF,MAAM,IAAI,SAAS;CA4BpB"}

package/dist/common/components/ErrorBoundary.js

@@ -0,0 +1,65 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Component } from "react";
+/**
+ * Error boundary component that catches JavaScript errors in child components.
+ * Displays a fallback UI instead of crashing the entire widget.
+ *
+ * @example
+ * <ErrorBoundary
+ *   fallback={<div>Something went wrong</div>}
+ *   onError={(error) => console.error(error)}
+ * >
+ *   <MyComponent />
+ * </ErrorBoundary>
+ */
+export class ErrorBoundary extends Component {
+    constructor(props) {
+        super(props);
+        this.state = { hasError: false, error: null };
+    }
+    static getDerivedStateFromError(error) {
+        return { hasError: true, error };
+    }
+    componentDidCatch(error, errorInfo) {
+        console.error("ErrorBoundary caught an error:", error, errorInfo);
+        this.props.onError?.(error, errorInfo);
+    }
+    render() {
+        if (this.state.hasError) {
+            if (this.props.fallback) {
+                return this.props.fallback;
+            }
+            return (_jsxs("div", { className: "flex flex-col items-center justify-center p-6 text-center", children: [_jsx("div", { className: "text-destructive font-medium mb-2", children: "Something went wrong" }), _jsx("p", { className: "text-muted-foreground text-sm mb-4", children: "An unexpected error occurred. Please try again." }), _jsx("button", { onClick: () => this.setState({ hasError: false, error: null }), className: "px-4 py-2 text-sm font-medium text-primary-foreground bg-primary rounded-md hover:bg-primary/90 transition-colors", children: "Try again" })] }));
+        }
+        return this.props.children;
+    }
+}
+export class WidgetErrorBoundary extends Component {
+    constructor(props) {
+        super(props);
+        this.handleReset = () => {
+            this.props.onReset?.();
+            this.setState({ hasError: false, error: null });
+        };
+        this.state = { hasError: false, error: null };
+    }
+    static getDerivedStateFromError(error) {
+        return { hasError: true, error };
+    }
+    componentDidCatch(error, errorInfo) {
+        console.error(`WidgetErrorBoundary [${this.props.widgetName ?? "Unknown"}]:`, error, errorInfo);
+        this.props.onError?.(error, errorInfo);
+    }
+    render() {
+        if (this.state.hasError) {
+            if (this.props.fallback) {
+                return this.props.fallback;
+            }
+            return (_jsxs("div", { className: "flex flex-col items-center justify-center p-6 text-center bg-destructive/5 rounded-lg border border-destructive/20", children: [_jsx("div", { className: "text-destructive font-medium mb-2", children: this.props.widgetName
+                            ? `${this.props.widgetName} encountered an error`
+                            : "Widget error" }), _jsx("p", { className: "text-muted-foreground text-sm mb-4", children: this.state.error?.message || "An unexpected error occurred." }), _jsx("button", { onClick: this.handleReset, className: "px-4 py-2 text-sm font-medium text-primary-foreground bg-primary rounded-md hover:bg-primary/90 transition-colors", children: "Reset widget" })] }));
+        }
+        return this.props.children;
+    }
+}

package/dist/common/hooks/useDebouncedCallback.d.ts

@@ -0,0 +1,13 @@
+type AnyFn = (...args: any[]) => any;
+export interface Debounced<T extends AnyFn> {
+    (...args: Parameters<T>): void;
+    cancel: () => void;
+    flush: () => void;
+}
+/**
+ * Returns a debounced function that delays invoking `fn` until after `delay`
+ * milliseconds have elapsed since the last call.
+ */
+export declare function useDebouncedCallback<T extends AnyFn>(fn: T, delay: number): Debounced<T>;
+export {};
+//# sourceMappingURL=useDebouncedCallback.d.ts.map

package/dist/common/hooks/useDebouncedCallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDebouncedCallback.d.ts","sourceRoot":"","sources":["../../../.build-src/common/hooks/useDebouncedCallback.ts"],"names":[],"mappings":"AAGA,KAAK,KAAK,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC;AAErC,MAAM,WAAW,SAAS,CAAC,CAAC,SAAS,KAAK;IACxC,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAC/B,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,KAAK,EAClD,EAAE,EAAE,CAAC,EACL,KAAK,EAAE,MAAM,GACZ,SAAS,CAAC,CAAC,CAAC,CAyCd"}

package/dist/common/hooks/useDebouncedCallback.js

@@ -0,0 +1,42 @@
+import { useEffect, useMemo, useRef } from "react";
+import { useStableCallback } from "./useStableCallback";
+/**
+ * Returns a debounced function that delays invoking `fn` until after `delay`
+ * milliseconds have elapsed since the last call.
+ */
+export function useDebouncedCallback(fn, delay) {
+    const latest = useStableCallback(fn);
+    const timerRef = useRef(null);
+    const lastArgsRef = useRef(null);
+    const cancel = () => {
+        if (timerRef.current) {
+            clearTimeout(timerRef.current);
+            timerRef.current = null;
+        }
+    };
+    const flush = () => {
+        if (timerRef.current && lastArgsRef.current) {
+            clearTimeout(timerRef.current);
+            timerRef.current = null;
+            latest(...lastArgsRef.current);
+            lastArgsRef.current = null;
+        }
+    };
+    // cancel when delay changes/unmounts
+    useEffect(() => cancel, [delay]);
+    return useMemo(() => {
+        const debounced = ((...args) => {
+            lastArgsRef.current = args;
+            cancel();
+            timerRef.current = setTimeout(() => {
+                latest(...lastArgsRef.current);
+                lastArgsRef.current = null;
+                timerRef.current = null;
+            }, delay);
+        });
+        debounced.cancel = cancel;
+        debounced.flush = flush;
+        return debounced;
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [delay, latest]);
+}

package/dist/common/hooks/useDebouncedValue.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Derives a debounced value from an input value and delay.
+ */
+export declare function useDebouncedValue<T>(value: T, delay: number): T;
+//# sourceMappingURL=useDebouncedValue.d.ts.map

package/dist/common/hooks/useDebouncedValue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDebouncedValue.d.ts","sourceRoot":"","sources":["../../../.build-src/common/hooks/useDebouncedValue.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,CAAC,CAW/D"}

package/dist/common/hooks/useDebouncedValue.js

@@ -0,0 +1,15 @@
+import { useEffect, useState } from "react";
+import { useDebouncedCallback } from "./useDebouncedCallback";
+/**
+ * Derives a debounced value from an input value and delay.
+ */
+export function useDebouncedValue(value, delay) {
+    const [debounced, setDebounced] = useState(value);
+    const setter = useDebouncedCallback((v) => setDebounced(v), delay);
+    useEffect(() => {
+        setter(value);
+        return setter.cancel;
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [value, delay]);
+    return debounced;
+}

package/dist/common/hooks/useInterval.d.ts

@@ -0,0 +1,11 @@
+interface UseIntervalOptions {
+    enabled?: boolean;
+    immediate?: boolean;
+}
+/**
+ * Declarative setInterval with pause/resume and latest-callback semantics.
+ * Pass delay=null to pause.
+ */
+export declare function useInterval(callback: () => void, delay: number | null, options?: UseIntervalOptions): void;
+export {};
+//# sourceMappingURL=useInterval.d.ts.map

package/dist/common/hooks/useInterval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useInterval.d.ts","sourceRoot":"","sources":["../../../.build-src/common/hooks/useInterval.ts"],"names":[],"mappings":"AAGA,UAAU,kBAAkB;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,IAAI,EACpB,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,OAAO,GAAE,kBAAuB,QAmBjC"}

package/dist/common/hooks/useInterval.js

@@ -0,0 +1,25 @@
+import { useEffect, useRef } from "react";
+import { useStableCallback } from "./useStableCallback";
+/**
+ * Declarative setInterval with pause/resume and latest-callback semantics.
+ * Pass delay=null to pause.
+ */
+export function useInterval(callback, delay, options = {}) {
+    const { enabled = true, immediate = false } = options;
+    const savedCallback = useStableCallback(callback);
+    const intervalRef = useRef(null);
+    useEffect(() => {
+        if (!enabled || delay == null)
+            return;
+        if (immediate) {
+            savedCallback();
+        }
+        intervalRef.current = setInterval(savedCallback, delay);
+        return () => {
+            if (intervalRef.current) {
+                clearInterval(intervalRef.current);
+                intervalRef.current = null;
+            }
+        };
+    }, [delay, enabled, immediate, savedCallback]);
+}

package/dist/common/hooks/useLatest.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Returns a ref that always contains the latest value.
+ * Useful for accessing current values in callbacks without causing re-renders.
+ *
+ * @example
+ * const countRef = useLatest(count);
+ * const handleClick = useCallback(() => {
+ *   console.log(countRef.current); // Always the latest count
+ * }, []); // No dependency needed!
+ */
+export declare function useLatest<T>(value: T): React.MutableRefObject<T>;
+//# sourceMappingURL=useLatest.d.ts.map

package/dist/common/hooks/useLatest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLatest.d.ts","sourceRoot":"","sources":["../../../.build-src/common/hooks/useLatest.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAShE"}

package/dist/common/hooks/useLatest.js

@@ -0,0 +1,19 @@
+import { useRef, useLayoutEffect } from "react";
+/**
+ * Returns a ref that always contains the latest value.
+ * Useful for accessing current values in callbacks without causing re-renders.
+ *
+ * @example
+ * const countRef = useLatest(count);
+ * const handleClick = useCallback(() => {
+ *   console.log(countRef.current); // Always the latest count
+ * }, []); // No dependency needed!
+ */
+export function useLatest(value) {
+    const ref = useRef(value);
+    // Use useLayoutEffect to update synchronously before any effects run
+    useLayoutEffect(() => {
+        ref.current = value;
+    });
+    return ref;
+}

package/dist/common/hooks/useNexusError.d.ts

@@ -0,0 +1,20 @@
+declare function handler(err: unknown): {
+    code: string;
+    message: string;
+    context: undefined;
+    details: undefined;
+} | {
+    code: import("@avail-project/nexus-core").ErrorCode;
+    message: string;
+    context: {
+        operation?: import("@avail-project/nexus-core").OperationName;
+        service: "wallet" | "hook" | "rpc" | "middleware" | "lifi" | "bebop" | "fibrous" | "zerox" | "coinbase" | undefined;
+        stepId?: string;
+        stepType?: string;
+        chainId?: number | bigint;
+    };
+    details: Record<string, unknown> | undefined;
+};
+export declare function useNexusError(): typeof handler;
+export {};
+//# sourceMappingURL=useNexusError.d.ts.map

package/dist/common/hooks/useNexusError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useNexusError.d.ts","sourceRoot":"","sources":["../../../.build-src/common/hooks/useNexusError.ts"],"names":[],"mappings":"AAoHA,iBAAS,OAAO,CAAC,GAAG,EAAE,OAAO;;;;;;;;;;;;;;;;EAuC5B;AAED,wBAAgB,aAAa,mBAE5B"}

package/dist/common/hooks/useNexusError.js

@@ -0,0 +1,120 @@
+import { ERROR_CODES, NexusError } from "@avail-project/nexus-core";
+const DEFAULT_ERROR_MESSAGE = "Oops! Something went wrong. Please try again.";
+const USER_REJECTED_MESSAGE = "Transaction was rejected in your wallet.";
+const EMPTY_ERROR_MESSAGE = "Unable to determine transaction state. Please refresh and try again.";
+const ERROR_MESSAGE_BY_CODE = {
+    [ERROR_CODES.INVALID_VALUES_ALLOWANCE_HOOK]: "Invalid allowance selection. Please review allowance values and try again.",
+    [ERROR_CODES.SDK_NOT_INITIALIZED]: "Nexus SDK is not initialized. Reconnect your wallet and try again.",
+    [ERROR_CODES.SDK_INIT_STATE_NOT_EXPECTED]: "Nexus is still initializing. Please wait a few seconds and retry.",
+    [ERROR_CODES.CHAIN_NOT_FOUND]: "Selected chain is not supported for this route.",
+    [ERROR_CODES.CHAIN_DATA_NOT_FOUND]: "Chain metadata is unavailable for this route. Please try another chain.",
+    [ERROR_CODES.ASSET_NOT_FOUND]: "Requested asset was not found in your balances.",
+    [ERROR_CODES.TOKEN_NOT_SUPPORTED]: "Selected token is not supported for this route.",
+    [ERROR_CODES.UNIVERSE_NOT_SUPPORTED]: "Selected chain universe is not supported yet.",
+    [ERROR_CODES.ENVIRONMENT_NOT_SUPPORTED]: "Selected environment is not supported yet.",
+    [ERROR_CODES.ENVIRONMENT_NOT_KNOWN]: "Selected environment is not recognized.",
+    [ERROR_CODES.INTERNAL_UNKNOWN_SIGNATURE]: "Unsupported signature type for this transaction.",
+    [ERROR_CODES.USER_INTENT_HOOK_DENIED]: USER_REJECTED_MESSAGE,
+    [ERROR_CODES.USER_ALLOWANCE_APPROVAL_DENIED]: USER_REJECTED_MESSAGE,
+    [ERROR_CODES.USER_INTENT_SIGNATURE_DENIED]: USER_REJECTED_MESSAGE,
+    [ERROR_CODES.USER_SIWE_SIGNATURE_DENIED]: USER_REJECTED_MESSAGE,
+    [ERROR_CODES.INSUFFICIENT_BALANCE]: "Insufficient balance to proceed.",
+    [ERROR_CODES.WALLET_NOT_CONNECTED]: "Wallet is not connected. Connect your wallet and try again.",
+    [ERROR_CODES.EXEC_GAS_PRICE_FETCH_FAILED]: "Unable to estimate gas right now. Please retry.",
+    [ERROR_CODES.SIMULATION_ERROR]: "Simulation failed. Please review your inputs and try again.",
+    [ERROR_CODES.BACKEND_GET_QUOTE_FAILED]: "Unable to fetch a quote right now. Please retry.",
+    [ERROR_CODES.VAULT_CONTRACT_NOT_FOUND]: "Required vault contract is unavailable on this chain.",
+    [ERROR_CODES.EXEC_SLIPPAGE_EXCEEDED]: "Slippage exceeded tolerance. Refresh quote and retry.",
+    [ERROR_CODES.EXTERNAL_RATES_DRIFT_EXCEEDED]: "Rates changed beyond tolerance. Review and retry.",
+    [ERROR_CODES.INVALID_INPUT]: "Some transaction inputs are invalid. Please review and try again.",
+    [ERROR_CODES.INVALID_ADDRESS_LENGTH]: "Address format is invalid for the selected chain.",
+    [ERROR_CODES.NO_BALANCE_FOR_ADDRESS]: "No balance found for this wallet on supported source chains.",
+    [ERROR_CODES.EXEC_TX_RECEIPT_WAIT_TIMEOUT]: "Transaction is taking longer than expected. Check your wallet and explorer.",
+    [ERROR_CODES.EXEC_TX_ONCHAIN_REVERTED]: "Transaction reverted on-chain. Please verify inputs and retry.",
+    [ERROR_CODES.INTERNAL_DESTINATION_REQUEST_HASH_NOT_FOUND]: "Could not finalize destination request. Please retry.",
+};
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function getErrorMessage(value) {
+    if (!isRecord(value))
+        return undefined;
+    const message = value.message;
+    return typeof message === "string" ? message : undefined;
+}
+function getErrorCode(value) {
+    if (!isRecord(value))
+        return undefined;
+    const code = value.code;
+    if (typeof code === "string" || typeof code === "number") {
+        return code;
+    }
+    return undefined;
+}
+function looksLikeUserRejection(err) {
+    if (err instanceof NexusError) {
+        return (err.code === ERROR_CODES.USER_ALLOWANCE_APPROVAL_DENIED ||
+            err.code === ERROR_CODES.USER_INTENT_HOOK_DENIED ||
+            err.code === ERROR_CODES.USER_INTENT_SIGNATURE_DENIED ||
+            err.code === ERROR_CODES.USER_SIWE_SIGNATURE_DENIED);
+    }
+    const code = getErrorCode(err);
+    if (code === 4001 || code === "ACTION_REJECTED") {
+        return true;
+    }
+    const message = getErrorMessage(err)?.toLowerCase();
+    if (!message)
+        return false;
+    return (message.includes("user denied") ||
+        message.includes("user rejected") ||
+        message.includes("rejected request") ||
+        message.includes("denied transaction signature"));
+}
+function sanitizeMessage(message) {
+    if (!message)
+        return DEFAULT_ERROR_MESSAGE;
+    const cleaned = message
+        .replace(/^Internal error:\s*/i, "")
+        .replace(/^COSMOS:\s*/i, "")
+        .trim();
+    return cleaned || DEFAULT_ERROR_MESSAGE;
+}
+function handler(err) {
+    if (err === null || err === undefined) {
+        console.error("Unexpected empty error from Nexus SDK:", err);
+        return {
+            code: "unexpected_error",
+            message: EMPTY_ERROR_MESSAGE,
+            context: undefined,
+            details: undefined,
+        };
+    }
+    if (looksLikeUserRejection(err)) {
+        return {
+            code: ERROR_CODES.USER_INTENT_HOOK_DENIED,
+            message: USER_REJECTED_MESSAGE,
+            context: undefined,
+            details: undefined,
+        };
+    }
+    if (err instanceof NexusError) {
+        const mappedMessage = ERROR_MESSAGE_BY_CODE[err.code] ?? sanitizeMessage(err.message);
+        return {
+            code: err.code,
+            message: mappedMessage,
+            context: err.context,
+            details: err.details,
+        };
+    }
+    const unknownMessage = sanitizeMessage(getErrorMessage(err));
+    console.error("Unexpected error:", err);
+    return {
+        code: String(getErrorCode(err) ?? "unexpected_error"),
+        message: unknownMessage || DEFAULT_ERROR_MESSAGE,
+        context: undefined,
+        details: undefined,
+    };
+}
+export function useNexusError() {
+    return handler;
+}

package/dist/common/hooks/usePolling.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Declarative polling with in-flight protection (no overlap).
+ * When enabled becomes true, an immediate run is executed,
+ * followed by interval-based runs.
+ */
+export declare function usePolling(enabled: boolean, fn: () => Promise<void> | void, intervalMs: number): void;
+//# sourceMappingURL=usePolling.d.ts.map

package/dist/common/hooks/usePolling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePolling.d.ts","sourceRoot":"","sources":["../../../.build-src/common/hooks/usePolling.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,OAAO,EAChB,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,EAC9B,UAAU,EAAE,MAAM,QAmBnB"}

package/dist/common/hooks/usePolling.js

@@ -0,0 +1,29 @@
+import { useRef } from "react";
+import { useInterval } from "./useInterval";
+import { useStableCallback } from "./useStableCallback";
+/**
+ * Declarative polling with in-flight protection (no overlap).
+ * When enabled becomes true, an immediate run is executed,
+ * followed by interval-based runs.
+ */
+export function usePolling(enabled, fn, intervalMs) {
+    const inFlightRef = useRef(false);
+    const wrapped = useStableCallback(async () => {
+        if (inFlightRef.current)
+            return;
+        try {
+            inFlightRef.current = true;
+            await fn();
+        }
+        catch (error) {
+            console.error(error);
+        }
+        finally {
+            inFlightRef.current = false;
+        }
+    });
+    useInterval(wrapped, enabled ? intervalMs : null, {
+        enabled,
+        immediate: enabled,
+    });
+}

package/dist/common/hooks/useStableCallback.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Returns a stable function identity that always calls the latest implementation.
+ * Useful when passing callbacks to memoized children without re-creating handlers.
+ */
+export declare function useStableCallback<Args extends readonly unknown[], Return>(fn: (...args: Args) => Return): (...args: Args) => Return;
+//# sourceMappingURL=useStableCallback.d.ts.map

package/dist/common/hooks/useStableCallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStableCallback.d.ts","sourceRoot":"","sources":["../../../.build-src/common/hooks/useStableCallback.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,SAAS,SAAS,OAAO,EAAE,EAAE,MAAM,EACvE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,MAAM,GAC5B,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,MAAM,CAa3B"}

package/dist/common/hooks/useStableCallback.js

@@ -0,0 +1,13 @@
+import { useCallback, useRef } from "react";
+/**
+ * Returns a stable function identity that always calls the latest implementation.
+ * Useful when passing callbacks to memoized children without re-creating handlers.
+ */
+export function useStableCallback(fn) {
+    const fnRef = useRef(fn);
+    fnRef.current = fn;
+    const stable = useCallback(((...args) => {
+        return fnRef.current(...args);
+    }), []);
+    return stable;
+}

package/dist/common/hooks/useStopwatch.d.ts

@@ -0,0 +1,17 @@
+interface UseStopwatchOptions {
+    running?: boolean;
+    intervalMs?: number;
+}
+/**
+ * Simple stopwatch that increments elapsed seconds while running.
+ * Designed to replace scattered timer effects.
+ */
+export declare function useStopwatch(options?: UseStopwatchOptions): {
+    seconds: number;
+    start: () => void;
+    stop: () => void;
+    reset: () => void;
+    running: boolean;
+};
+export {};
+//# sourceMappingURL=useStopwatch.d.ts.map

package/dist/common/hooks/useStopwatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStopwatch.d.ts","sourceRoot":"","sources":["../../../.build-src/common/hooks/useStopwatch.ts"],"names":[],"mappings":"AAEA,UAAU,mBAAmB;IAC3B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB;;;;;;EAyC7D"}

package/dist/common/hooks/useStopwatch.js

@@ -0,0 +1,44 @@
+import { useEffect, useRef, useState } from "react";
+/**
+ * Simple stopwatch that increments elapsed seconds while running.
+ * Designed to replace scattered timer effects.
+ */
+export function useStopwatch(options = {}) {
+    const { running = false, intervalMs = 100 } = options;
+    const [elapsedSeconds, setElapsedSeconds] = useState(0);
+    const timerRef = useRef(null);
+    const reset = () => {
+        setElapsedSeconds(0);
+    };
+    const stop = () => {
+        if (timerRef.current) {
+            clearInterval(timerRef.current);
+            timerRef.current = null;
+        }
+    };
+    const start = () => {
+        if (timerRef.current)
+            return;
+        timerRef.current = setInterval(() => {
+            // 1s == 1000ms; we add fractional seconds per tick
+            setElapsedSeconds((prev) => prev + intervalMs / 1000);
+        }, intervalMs);
+    };
+    useEffect(() => {
+        if (running) {
+            start();
+        }
+        else {
+            stop();
+        }
+        return stop;
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [running, intervalMs]);
+    return {
+        seconds: elapsedSeconds,
+        start,
+        stop,
+        reset,
+        running: Boolean(timerRef.current),
+    };
+}