catalyst-core 0.3.0-beta.5 → 0.3.0-canary.2

package/dist/native/bridge/hooks/useHapticFeedback.d.ts

@@ -0,0 +1,76 @@
+import type { WebFallbackOptions } from "../useBaseHook.js";
+export declare const requestHapticFeedback: (feedbackType?: string) => Promise<any>;
+export declare const useHapticFeedback: ({ webFallback }?: WebFallbackOptions) => {
+    data: any;
+    loading: boolean;
+    progress: any;
+    error: any;
+    isWeb: boolean;
+    isNative: boolean;
+    webFallbackActive: boolean;
+    webFallbackDisabled: boolean;
+    setWebFallback: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    execute: () => void;
+    clear: () => void;
+    clearError: () => void;
+    triggerHaptic: () => void;
+    trigger: () => void;
+    light: () => void;
+    medium: () => void;
+    heavy: () => void;
+    success: () => void;
+    warning: () => void;
+    errorHaptic: () => void;
+    selection: () => void;
+    impact: () => void;
+    capabilities: {
+        isSupported: boolean;
+        availableTypes: undefined[];
+        platform: string;
+    };
+    isSupported: boolean;
+    isAvailable: boolean;
+    availableTypes: any[];
+    HAPTIC_TYPES: {};
+} | {
+    data: any;
+    loading: boolean;
+    progress: import("../useBaseHook.js").HookProgress;
+    error: any;
+    isWeb: boolean;
+    isNative: boolean;
+    webFallbackActive: boolean;
+    webFallbackDisabled: boolean;
+    setWebFallback: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    clear: () => void;
+    clearError: () => void;
+    execute: (type?: string, options?: {}) => Promise<any>;
+    triggerHaptic: (type?: string, options?: {}) => Promise<any>;
+    trigger: (type?: string, options?: {}) => Promise<any>;
+    light: () => Promise<any>;
+    medium: () => Promise<any>;
+    heavy: () => Promise<any>;
+    success: () => Promise<any>;
+    warning: () => Promise<any>;
+    errorHaptic: () => Promise<any>;
+    selection: () => Promise<any>;
+    impact: () => Promise<any>;
+    capabilities: {
+        isSupported: boolean;
+        availableTypes: string[];
+        platform: string;
+    };
+    isSupported: boolean;
+    isAvailable: boolean;
+    availableTypes: string[];
+    HAPTIC_TYPES: {
+        LIGHT: string;
+        MEDIUM: string;
+        HEAVY: string;
+        SUCCESS: string;
+        WARNING: string;
+        ERROR: string;
+        SELECTION: string;
+        IMPACT: string;
+    };
+};

package/dist/native/bridge/hooks/useHapticFeedback.js

@@ -116,7 +116,12 @@ const useHapticFeedback = ({
   (0, _react.useEffect)(() => {
     setCapabilities(detectHapticCapabilities(base.isNative));
   }, [base.isNative]);
-  const handleWebHaptic = type => {
+
+  // The caller passes `(type, options)`, but the web path has never read the
+  // second argument — `navigator.vibrate` takes only a pattern. The parameter
+  // is declared so the discard is explicit at the signature rather than being
+  // an arity mismatch; behavior is unchanged.
+  const handleWebHaptic = (type, _options) => {
     if (!navigator.vibrate) return false;
     const vibrationPatterns = {
       [HAPTIC_TYPES.LIGHT]: [50],

package/dist/native/bridge/hooks/useIntent.d.ts

@@ -0,0 +1,33 @@
+import type { HookProgress, HookState } from "../useBaseHook.js";
+/** What {@link useIntent} returns. Wraps one operation: opening a file externally. */
+export interface UseIntentResult extends HookState {
+    /** Progress of the in-flight intent, or null under SSR. */
+    progress: HookProgress | null;
+    /** Open a file with an external app. The canonical action. */
+    openFile: (fileUrl: string, mimeType?: string | null) => void;
+    /** Alias of `openFile`, named to match the shared hook contract. */
+    execute: (fileUrl: string, mimeType?: string | null) => void;
+    /** Drop the current result and error. */
+    clear: () => void;
+    /** Drop the current error, keeping any data. */
+    clearError: () => void;
+    /** The current phase of the intent, or null when idle. */
+    processingState: string | null;
+    /** True once the intent completed successfully, else null. */
+    success: boolean | null;
+    /**
+     * True while the intent is in flight.
+     *
+     * @deprecated Use `loading` instead. `isLoading` is a deprecated alias kept
+     * for backward compatibility and will be removed at 2.0.
+     */
+    isLoading: boolean;
+    /**
+     * Drop the current result and error.
+     *
+     * @deprecated Use `clear` instead. `reset` is a deprecated alias kept for
+     * backward compatibility and will be removed at 2.0.
+     */
+    reset: () => void;
+}
+export declare const useIntent: () => UseIntentResult;

package/dist/native/bridge/hooks/useIntent.js

@@ -11,6 +11,8 @@ var _useBaseHook = require("../useBaseHook.js");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 /* eslint-disable react-compiler/react-compiler, react-hooks/exhaustive-deps */
 
+/** What {@link useIntent} returns. Wraps one operation: opening a file externally. */
+
 const useIntent = () => {
   const base = (0, _useBaseHook.useBaseHook)("useIntent");
   if (typeof window === "undefined") {

package/dist/native/bridge/hooks/useNativeTransition.d.ts

@@ -0,0 +1,53 @@
+import type { HookEnvironment } from "../useBaseHook.js";
+/** Transition options, accepted as hook defaults and per-navigate overrides. */
+export interface NativeTransitionOptions {
+    /** Animation style. Defaults to `"slide"`. */
+    type?: "slide" | "fade";
+    /** Slide direction. Slide only. Defaults to `"left"`. */
+    direction?: "left" | "right" | "up" | "down";
+    /** Animation length in ms. Defaults to 300. */
+    duration?: number;
+    /** Safety timer in ms. Defaults to `max(duration * 3, 800)`. */
+    timeout?: number;
+    /** Replace the current history entry instead of pushing. */
+    replace?: boolean;
+    /** Router state to carry through the navigation. */
+    state?: any;
+}
+/**
+ * What {@link useNativeTransition} returns.
+ *
+ * A multi-action hook: its named functions are the API, so it has no `execute`.
+ * It also returns no `error` key — a failed transition self-heals into a plain
+ * navigation, so there is nothing for a caller to handle.
+ */
+export interface UseNativeTransitionResult extends HookEnvironment {
+    /** Navigate with a native transition. */
+    navigate: (to: any, options?: NativeTransitionOptions) => void;
+    /** Cancel an in-flight transition. Best-effort. */
+    cancelTransition: () => void;
+    /** True while a transition is running. */
+    loading: boolean;
+    /**
+     * True while a transition is running.
+     *
+     * @deprecated Use `loading` instead. `transitioning` is a deprecated alias
+     * kept for backward compatibility and will be removed at 2.0.
+     */
+    transitioning: boolean;
+}
+/**
+ * Wraps useNavigate with native slide/fade transitions using a snapshot overlay pattern.
+ *
+ * Native path:
+ *   navigate(to, opts) → startTransition → native snapshots screen → router.navigate(to) →
+ *   commitTransition → native animates overlay out revealing new page.
+ *
+ * Safety net: native-side timer (configurable via opts.timeout, default max(duration*3, 800ms))
+ *   force-fades the overlay if commitTransition is never called.
+ *
+ * Web fallback: CSS overlay on document.body, driven by the same state machine.
+ *
+ * @param defaults - Default transition options applied to every navigate call
+ */
+export declare const useNativeTransition: (defaults?: NativeTransitionOptions) => UseNativeTransitionResult;

package/dist/native/bridge/hooks/useNativeTransition.js

@@ -15,6 +15,16 @@ const DEFAULT_DURATION = 300;
 const DEFAULT_TIMEOUT_MULTIPLIER = 3;
 const MIN_TIMEOUT = 800;
 
+/** Transition options, accepted as hook defaults and per-navigate overrides. */
+
+/**
+ * What {@link useNativeTransition} returns.
+ *
+ * A multi-action hook: its named functions are the API, so it has no `execute`.
+ * It also returns no `error` key — a failed transition self-heals into a plain
+ * navigation, so there is nothing for a caller to handle.
+ */
+
 /**
  * Wraps useNavigate with native slide/fade transitions using a snapshot overlay pattern.
  *
@@ -27,11 +37,7 @@ const MIN_TIMEOUT = 800;
  *
  * Web fallback: CSS overlay on document.body, driven by the same state machine.
  *
- * @param {Object} defaults - Default transition options applied to every navigate call
- *   type: 'slide' | 'fade' (default: 'slide')
- *   direction: 'left' | 'right' | 'up' | 'down' (default: 'left')
- *   duration: ms (default: 300)
- *   timeout: ms safety timer (default: max(duration*3, 800))
+ * @param defaults - Default transition options applied to every navigate call
  */
 const useNativeTransition = (defaults = {}) => {
   const router = (0, _reactRouter.useNavigate)();
@@ -211,6 +217,7 @@ const useNativeTransition = (defaults = {}) => {
     navigate,
     cancelTransition,
     transitioning,
+    loading: transitioning,
     isNative,
     isWeb: !isNative
   };

package/dist/native/bridge/hooks/useNetworkStatus.d.ts

@@ -0,0 +1,22 @@
+import type { HookEnvironment, WebFallbackOptions, WebFallbackState } from "../useBaseHook.js";
+/**
+ * What {@link useNetworkStatus} returns: connectivity spread at the top level,
+ * plus the runtime-context keys.
+ *
+ * Read-only, so it has no action functions.
+ */
+export interface UseNetworkStatusResult extends HookEnvironment, WebFallbackState {
+    /** True when the device reports a usable connection. */
+    online: boolean;
+    /** Connection type reported by native, or null when unknown. */
+    type: string | null;
+    /**
+     * The failure message, or null.
+     *
+     * Note this is a plain string rather than a standard error object. That is
+     * a known inconsistency with the rest of the hook contract, and it stays a
+     * string until 2.0.
+     */
+    error: string | null;
+}
+export declare const useNetworkStatus: ({ webFallback }?: WebFallbackOptions) => UseNetworkStatusResult;

package/dist/native/bridge/hooks/useNetworkStatus.js

@@ -11,6 +11,13 @@ var _utils = require("./utils.js");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 /* eslint-disable react-compiler/react-compiler, react-hooks/exhaustive-deps */
 
+/**
+ * What {@link useNetworkStatus} returns: connectivity spread at the top level,
+ * plus the runtime-context keys.
+ *
+ * Read-only, so it has no action functions.
+ */
+
 const useNetworkStatus = ({
   webFallback
 } = {}) => {

package/dist/native/bridge/hooks/useNotification.d.ts

@@ -0,0 +1,83 @@
+import type { HookProgress, HookState } from "../useBaseHook.js";
+export declare const requestNotificationPermission: () => Promise<any>;
+/**
+ * What {@link useNotificationPermission} returns.
+ *
+ * Gained `loading`, `data`, `error`, `isNative` and `isWeb` when the hook
+ * surface was made consistent, and it now reports permission failures as a
+ * standard error object instead of only logging them.
+ */
+export interface UseNotificationPermissionResult extends HookState<string> {
+    /**
+     * The permission status.
+     *
+     * @deprecated Use `data` instead. `permission` is a deprecated alias kept
+     * for backward compatibility and will be removed at 2.0.
+     */
+    permission: string | null;
+    /**
+     * True while the permission state is resolving.
+     *
+     * @deprecated Use `loading` instead. `isLoading` is a deprecated alias kept
+     * for backward compatibility and will be removed at 2.0.
+     */
+    isLoading: boolean;
+}
+export declare const useNotificationPermission: () => UseNotificationPermissionResult;
+/**
+ * What {@link useNotification} returns.
+ *
+ * This is the one multi-action hook that still carries `execute`. It and
+ * `schedule` are frozen aliases of `scheduleLocal` kept for backward
+ * compatibility, and neither should be read as the pattern for multi-action
+ * hooks — those expose their named functions and no `execute` at all.
+ */
+export interface UseNotificationResult extends HookState {
+    /** Progress of the in-flight operation, or null under SSR. */
+    progress: HookProgress | null;
+    /** Drop the current result and error. */
+    clear: () => void;
+    /** Drop the current error, keeping any data. */
+    clearError: () => void;
+    /** Latest notification permission status, or null. */
+    permissionStatus: string | null;
+    /** Push token issued by the platform, or null. */
+    pushToken: string | null;
+    /** Current app badge count. */
+    badges: number;
+    /** The most recently received or tapped notification, or null. */
+    lastNotification: any;
+    /** Topics this device is subscribed to. */
+    subscribedTopics: any[];
+    /** Schedule a local notification. The canonical action. */
+    scheduleLocal: (config: any) => void;
+    /** Cancel a previously scheduled local notification. */
+    cancelLocal: (notificationId: string) => void;
+    /** Register this device for push notifications. */
+    registerForPush: () => void;
+    /** Set the app badge count. */
+    updateBadge: (count: number) => void;
+    /** Subscribe to a push topic. */
+    subscribeToTopic: (topic: string) => void;
+    /** Unsubscribe from a push topic. */
+    unsubscribeFromTopic: (topic: string) => void;
+    /** Ask the native side for the current topic subscriptions. */
+    getSubscribedTopics: () => void;
+    /** Prompt for notification permission. */
+    requestPermission: () => void;
+    /**
+     * Schedule a local notification.
+     *
+     * @deprecated Use `scheduleLocal` instead. `execute` is a frozen alias kept
+     * for backward compatibility and will be removed at 2.0.
+     */
+    execute: (config: any) => void;
+    /**
+     * Schedule a local notification.
+     *
+     * @deprecated Use `scheduleLocal` instead. `schedule` is a frozen alias kept
+     * for backward compatibility and will be removed at 2.0.
+     */
+    schedule: (config: any) => void;
+}
+export declare const useNotification: () => UseNotificationResult;

package/dist/native/bridge/hooks/useNotification.js

@@ -7,6 +7,7 @@ exports.useNotificationPermission = exports.useNotification = exports.requestNot
 var _react = require("react");
 var _NativeBridge = _interopRequireDefault(require("../utils/NativeBridge.js"));
 var _NativeInterfaces = require("../constants/NativeInterfaces.js");
+var _errors = require("../errors.js");
 var _useBaseHook = require("../useBaseHook.js");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 /* eslint-disable react-compiler/react-compiler, react-hooks/exhaustive-deps */
@@ -63,19 +64,20 @@ const requestNotificationPermission = () => {
     }
   });
 };
+
+/**
+ * What {@link useNotificationPermission} returns.
+ *
+ * Gained `loading`, `data`, `error`, `isNative` and `isWeb` when the hook
+ * surface was made consistent, and it now reports permission failures as a
+ * standard error object instead of only logging them.
+ */
 exports.requestNotificationPermission = requestNotificationPermission;
 const useNotificationPermission = () => {
-  if (typeof window === "undefined") {
-    return {
-      permission: null,
-      isLoading: false
-    };
-  }
-  if (!window.WebBridge) {
-    throw new Error("WebBridge is not initialized. Call WebBridge.init() first.");
-  }
   const [permission, setPermission] = (0, _react.useState)(null);
   const [isLoading, setIsLoading] = (0, _react.useState)(true);
+  const [error, setError] = (0, _react.useState)(null);
+  const isWeb = typeof window === "undefined" ? true : !_NativeBridge.default.isAvailable();
   (0, _react.useEffect)(() => {
     const requestPermission = async () => {
       try {
@@ -90,9 +92,10 @@ const useNotificationPermission = () => {
           console.log("🔔 Notification permission status updated:", data);
         });
         _NativeBridge.default.notification.requestPermission();
-      } catch (error) {
-        console.error("🔔 Error requesting notification permission:", error);
+      } catch (err) {
+        console.error("🔔 Error requesting notification permission:", err);
         setPermission(_NativeInterfaces.PERMISSION_STATUS.DENIED);
+        setError((0, _errors.createStandardError)(_errors.ERROR_CODES.PERMISSION_DENIED, "Notification permission denied", err));
         setIsLoading(false);
       }
     };
@@ -101,11 +104,39 @@ const useNotificationPermission = () => {
       window.WebBridge.unregister(_NativeInterfaces.NATIVE_CALLBACKS.NOTIFICATION_PERMISSION_STATUS);
     };
   }, []);
+  if (typeof window === "undefined") {
+    return {
+      permission: null,
+      isLoading: false,
+      loading: false,
+      data: null,
+      error: null,
+      isNative: false,
+      isWeb: true
+    };
+  }
+  if (!window.WebBridge) {
+    throw new Error("WebBridge is not initialized. Call WebBridge.init() first.");
+  }
   return {
     permission,
-    isLoading
+    isLoading,
+    loading: isLoading,
+    data: permission,
+    error,
+    isNative: !isWeb,
+    isWeb
   };
 };
+
+/**
+ * What {@link useNotification} returns.
+ *
+ * This is the one multi-action hook that still carries `execute`. It and
+ * `schedule` are frozen aliases of `scheduleLocal` kept for backward
+ * compatibility, and neither should be read as the pattern for multi-action
+ * hooks — those expose their named functions and no `execute` at all.
+ */
 exports.useNotificationPermission = useNotificationPermission;
 const useNotification = () => {
   const base = (0, _useBaseHook.useBaseHook)("useNotification");
@@ -114,28 +145,6 @@ const useNotification = () => {
   const [badges, setBadges] = (0, _react.useState)(0);
   const [lastNotification, setLastNotification] = (0, _react.useState)(null);
   const [subscribedTopics, setSubscribedTopics] = (0, _react.useState)([]);
-  if (typeof window === "undefined") {
-    return {
-      data: null,
-      loading: false,
-      error: null,
-      execute: () => {},
-      scheduleLocal: () => {},
-      cancelLocal: () => {},
-      registerForPush: () => {},
-      updateBadge: () => {},
-      subscribeToTopic: () => {},
-      unsubscribeFromTopic: () => {},
-      getSubscribedTopics: () => {},
-      permissionStatus: null,
-      pushToken: null,
-      badges: 0,
-      subscribedTopics: []
-    };
-  }
-  if (!window.WebBridge) {
-    throw new Error("WebBridge is not initialized. Call WebBridge.init() first.");
-  }
   (0, _react.useEffect)(() => {
     const unregister = registerPermissionStatusListener(data => {
       setPermissionStatus(data);
@@ -252,6 +261,44 @@ const useNotification = () => {
       window.WebBridge.unregister(_NativeInterfaces.NATIVE_CALLBACKS.SUBSCRIBED_TOPICS_RESULT);
     };
   }, []);
+  if (typeof window === "undefined") {
+    return {
+      data: null,
+      loading: false,
+      progress: {
+        state: "idle",
+        percentage: null,
+        message: null,
+        phase: null,
+        transport: null,
+        bytesLoaded: null,
+        bytesTotal: null
+      },
+      error: null,
+      execute: () => {},
+      clear: () => {},
+      clearError: () => {},
+      isNative: false,
+      isWeb: true,
+      permissionStatus: null,
+      pushToken: null,
+      badges: 0,
+      lastNotification: null,
+      subscribedTopics: [],
+      scheduleLocal: () => {},
+      cancelLocal: () => {},
+      registerForPush: () => {},
+      updateBadge: () => {},
+      subscribeToTopic: () => {},
+      unsubscribeFromTopic: () => {},
+      getSubscribedTopics: () => {},
+      schedule: () => {},
+      requestPermission: () => {}
+    };
+  }
+  if (!window.WebBridge) {
+    throw new Error("WebBridge is not initialized. Call WebBridge.init() first.");
+  }
   const requestPermission = () => {
     requestNotificationPermission().catch(err => base.handleNativeError(err));
   };

package/dist/native/bridge/hooks/useSafeArea.d.ts

@@ -0,0 +1,12 @@
+import type { SafeAreaInsets } from "../safeArea.js";
+import type { HookEnvironment, WebFallbackOptions, WebFallbackState } from "../useBaseHook.js";
+/**
+ * What {@link useSafeArea} returns: the four insets spread at the top level,
+ * plus the runtime-context keys.
+ *
+ * Read-only, so it has no action functions, and it returns no `error` key —
+ * insets always resolve to numeric defaults, so there is nothing to report.
+ */
+export interface UseSafeAreaResult extends SafeAreaInsets, HookEnvironment, WebFallbackState {
+}
+export declare const useSafeArea: ({ webFallback }?: WebFallbackOptions) => UseSafeAreaResult;

package/dist/native/bridge/hooks/useSafeArea.js

@@ -10,6 +10,14 @@ var _safeArea = require("../safeArea.js");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 /* eslint-disable react-compiler/react-compiler, react-hooks/exhaustive-deps */
 
+/**
+ * What {@link useSafeArea} returns: the four insets spread at the top level,
+ * plus the runtime-context keys.
+ *
+ * Read-only, so it has no action functions, and it returns no `error` key —
+ * insets always resolve to numeric defaults, so there is nothing to report.
+ */
+
 const useSafeArea = ({
   webFallback
 } = {}) => {

package/dist/native/bridge/hooks/useVideoStream.d.ts

@@ -0,0 +1,67 @@
+import type { WebFallbackOptions } from "../useBaseHook.js";
+/** Options accepted when starting the native or web video stream. */
+export interface VideoStreamStartOptions {
+    /** Which camera to open: `"back"` or `"front"`. */
+    facing?: string;
+    /** Detection filter: `"qr"`, `"barcode"` or `"all"`. */
+    format?: string;
+    /** Zoom behaviour, e.g. `{ auto: true, initial: 1.0 }`. */
+    zoom?: any;
+    /** Target frame rate. */
+    fps?: number;
+    [key: string]: any;
+}
+/** Options accepted by {@link useVideoStream}. */
+export interface VideoStreamOptions extends WebFallbackOptions {
+    /** Called with each detected QR/barcode payload. */
+    onQRDetected?: (value: any) => void;
+}
+export declare const useVideoStream: ({ onQRDetected, webFallback }?: VideoStreamOptions) => {
+    isStreaming: boolean;
+    streamState: {
+        zoom: any;
+        minZoom: any;
+        maxZoom: any;
+        torchOn: boolean;
+        fpsMin: any;
+        fpsMax: any;
+    };
+    loading: boolean;
+    error: any;
+    isNative: boolean;
+    isWeb: boolean;
+    webFallbackActive: boolean;
+    webFallbackDisabled: boolean;
+    setWebFallback: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    mediaStream: any;
+    viewfinderRef: import("react").RefObject<any>;
+    start: (options?: VideoStreamStartOptions) => Promise<void>;
+    stop: () => void;
+    sendCommand: (type: any, value: any) => Promise<void>;
+    flip: () => Promise<void>;
+    clearError: () => void;
+} | {
+    isStreaming: boolean;
+    streamState: {
+        zoom: any;
+        minZoom: any;
+        maxZoom: any;
+        torchOn: boolean;
+        fpsMin: any;
+        fpsMax: any;
+    };
+    loading: boolean;
+    error: any;
+    isNative: boolean;
+    isWeb: boolean;
+    webFallbackActive: boolean;
+    webFallbackDisabled: boolean;
+    setWebFallback: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    mediaStream: any;
+    viewfinderRef: import("react").RefObject<any>;
+    start: (options?: VideoStreamStartOptions) => void;
+    stop: () => void;
+    sendCommand: (type: any, value: any) => void;
+    flip: () => void;
+    clearError: () => void;
+};