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

package/dist/native/bridge/useBaseHook.d.ts

@@ -0,0 +1,137 @@
+import type { StandardError } from "./errors";
+/**
+ * Progress of a long-running native operation, as reported through the
+ * `progress` key that every operation-carrying hook returns.
+ */
+export interface HookProgress {
+    /** Coarse lifecycle state — see {@link PROGRESS_STATES}. */
+    state: string;
+    /** Completion from 0-100, or null when the operation cannot report it. */
+    percentage: number | null;
+    /** Human-readable status message, or null. */
+    message: string | null;
+    /** Operation-specific phase, or null. */
+    phase: string | null;
+    /** Transport the native side chose for the payload, or null. */
+    transport: string | null;
+    /** Bytes transferred so far, or null. */
+    bytesLoaded: number | null;
+    /** Total bytes expected, or null. */
+    bytesTotal: number | null;
+}
+/**
+ * The runtime-context keys every native hook returns, whatever else it adds.
+ *
+ * `isNative` and `isWeb` are always complementary booleans, resolved live at
+ * render time rather than cached from SSR.
+ */
+export interface HookEnvironment {
+    /** True when running inside a native WebView with the bridge available. */
+    isNative: boolean;
+    /** True when running on the plain web. Always `!isNative`. */
+    isWeb: boolean;
+}
+/**
+ * The state contract shared by every native hook: the data/loading/error triple
+ * plus the runtime-context keys.
+ *
+ * Two hooks are exempt from the `error` half — `useNativeTransition` and
+ * `useSafeArea` return no `error` key at all — and two carry it with the wrong
+ * type: `error` on `useDeviceInfo` and `useNetworkStatus` is a plain string
+ * rather than a {@link StandardError}, and stays a string until 2.0.
+ *
+ * @typeParam TData - what the hook's `data` key holds.
+ */
+export interface HookState<TData = any> extends HookEnvironment {
+    /** The hook's payload, or null before it has one. */
+    data: TData | null;
+    /** True while a native operation is in flight. */
+    loading: boolean;
+    /** The last error, or null. */
+    error: StandardError | null;
+}
+/** Options accepted by hooks that can fall back to a web implementation. */
+export interface WebFallbackOptions {
+    /**
+     * Opt out of the hook's web fallback by passing `false`. When omitted, the
+     * fallback is controlled imperatively through `setWebFallback` instead.
+     */
+    webFallback?: boolean;
+}
+/** The web-fallback control keys returned by hooks that declare a fallback. */
+export interface WebFallbackState {
+    /** True when the hook is serving its web fallback implementation. */
+    webFallbackActive: boolean;
+    /** True when on web and the fallback has been turned off. */
+    webFallbackDisabled: boolean;
+    /** Imperatively enable or disable the web fallback. */
+    setWebFallback: (enabled: boolean) => void;
+}
+/** Configuration passed by a hook to {@link useBaseHook}. */
+interface UseBaseHookOptions extends WebFallbackOptions {
+    /** Whether this hook implements a web fallback at all. */
+    hasWebFallback?: boolean;
+}
+/**
+ * Base hook utility that provides standardized interface for all Catalyst hooks
+ * Handles environment detection, error standardization, and common state management
+ *
+ * @param hookName - Name of the hook for debugging purposes
+ * @returns Base hook interface with common functionality
+ */
+export declare const useBaseHook: (hookName: string, { hasWebFallback, webFallback }?: UseBaseHookOptions) => {
+    isWeb: boolean;
+    isNative: boolean;
+    data: any;
+    loading: boolean;
+    progress: HookProgress;
+    error: any;
+    webFallbackActive: boolean;
+    webFallbackDisabled: boolean;
+    setWebFallback: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    clear: () => void;
+    clearError: () => void;
+    setData: import("react").Dispatch<any>;
+    setLoading: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    setError: import("react").Dispatch<any>;
+    setProgress: import("react").Dispatch<import("react").SetStateAction<HookProgress>>;
+    updateProgress: (updates: Partial<HookProgress>) => void;
+    resetProgress: () => void;
+    startProgress: (phase?: string | null, message?: string | null) => void;
+    completeProgress: () => void;
+    errorProgress: () => void;
+    setDataAndComplete: (newData: any) => void;
+    handleNativeError: (nativeError: any) => StandardError;
+    callNative: (fn: () => void) => void;
+    executeOperation: (operationCallback: () => void, operationName?: string) => void;
+};
+/**
+ * Hook for development debugging and testing
+ * @param hookName
+ * @returns Environment information and utilities
+ */
+export declare const useEnvironmentInfo: (hookName: string) => {
+    isNative: boolean;
+    isWeb: boolean;
+    environmentDetails: any;
+};
+/**
+ * Progress state constants for consistency across hooks
+ */
+export declare const PROGRESS_STATES: {
+    IDLE: string;
+    STARTING: string;
+    COMPLETE: string;
+    ERROR: string;
+    OPENING: string;
+    PROCESSING: string;
+    ROUTING: string;
+    REQUESTING: string;
+    CAPTURING: string;
+    DOWNLOADING: string;
+    OPENING_FILE: string;
+    CONNECTING: string;
+    UPLOADING: string;
+    SERVING: string;
+};
+export {};

package/dist/native/bridge/useBaseHook.js

@@ -8,12 +8,42 @@ var _react = require("react");
 var _NativeBridge = _interopRequireDefault(require("./utils/NativeBridge.js"));
 var _errors = require("./errors");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * Progress of a long-running native operation, as reported through the
+ * `progress` key that every operation-carrying hook returns.
+ */
+
+/**
+ * The runtime-context keys every native hook returns, whatever else it adds.
+ *
+ * `isNative` and `isWeb` are always complementary booleans, resolved live at
+ * render time rather than cached from SSR.
+ */
+
+/**
+ * The state contract shared by every native hook: the data/loading/error triple
+ * plus the runtime-context keys.
+ *
+ * Two hooks are exempt from the `error` half — `useNativeTransition` and
+ * `useSafeArea` return no `error` key at all — and two carry it with the wrong
+ * type: `error` on `useDeviceInfo` and `useNetworkStatus` is a plain string
+ * rather than a {@link StandardError}, and stays a string until 2.0.
+ *
+ * @typeParam TData - what the hook's `data` key holds.
+ */
+
+/** Options accepted by hooks that can fall back to a web implementation. */
+
+/** The web-fallback control keys returned by hooks that declare a fallback. */
+
+/** Configuration passed by a hook to {@link useBaseHook}. */
+
 /**
  * Base hook utility that provides standardized interface for all Catalyst hooks
  * Handles environment detection, error standardization, and common state management
  *
- * @param {string} hookName - Name of the hook for debugging purposes
- * @returns {Object} Base hook interface with common functionality
+ * @param hookName - Name of the hook for debugging purposes
+ * @returns Base hook interface with common functionality
  */
 const useBaseHook = (hookName, {
   hasWebFallback = false,
@@ -224,8 +254,8 @@ const useBaseHook = (hookName, {
 
 /**
  * Hook for development debugging and testing
- * @param {string} hookName
- * @returns {Object} Environment information and utilities
+ * @param hookName
+ * @returns Environment information and utilities
  */
 exports.useBaseHook = useBaseHook;
 const useEnvironmentInfo = hookName => {

package/dist/native/bridge/utils/CameraUtils.d.ts

@@ -0,0 +1,94 @@
+/** Options accepted when opening the native camera. */
+export interface CameraOptions {
+    /** Image quality: `"high"`, `"medium"` or `"low"`. */
+    quality?: string;
+    /** Image format: `"jpeg"` or `"png"`. */
+    format?: string;
+    /** Which camera to use: `"front"` or `"rear"`. */
+    cameraDevice?: string;
+    /** Flash behaviour: `"auto"`, `"on"` or `"off"`. */
+    flashMode?: string;
+    /** Whether to let the user edit the image after capture. */
+    allowEditing?: boolean;
+}
+/** Configuration accepted when requesting camera permission. */
+export interface CameraPermissionConfig {
+    /** Ask the native side for a detailed permission payload. */
+    includeDetails?: boolean;
+    [key: string]: any;
+}
+/**
+ * Camera Utility Module
+ * Provides Promise-based camera operations with proper option validation
+ */
+declare class CameraUtils {
+    /**
+     * Open camera and capture image
+     * @param {Object} options - Camera options
+     * @param {string} options.quality - Image quality: 'high', 'medium', 'low'
+     * @param {string} options.format - Image format: 'jpeg', 'png'
+     * @param {string} options.cameraDevice - Camera device: 'front', 'rear'
+     * @param {string} options.flashMode - Flash mode: 'auto', 'on', 'off'
+     * @param {boolean} options.allowEditing - Allow image editing after capture
+     * @param {Function} registerCallback - Callback registration function
+     * @param {Function} unregisterCallback - Callback unregistration function
+     * @returns {Promise<Object>} - Promise that resolves with camera result or rejects with error
+     */
+    static openCamera(options: CameraOptions, registerCallback: (event: string, handler: (data: any) => void) => void, unregisterCallback: (event: string) => void): Promise<any>;
+    /**
+     * Request camera permission
+     * @param {Object} config - Permission configuration
+     * @param {boolean} config.includeDetails - Include detailed permission info in response
+     * @param {Function} registerCallback - Callback registration function
+     * @param {Function} unregisterCallback - Callback unregistration function
+     * @returns {Promise<Object>} - Promise that resolves with permission status or rejects with error
+     */
+    static requestCameraPermission(config: CameraPermissionConfig, registerCallback: (event: string, handler: (data: any) => void) => void, unregisterCallback: (event: string) => void): Promise<any>;
+    /**
+     * Validate camera options and set defaults
+     * @param {Object} options - Raw camera options
+     * @returns {Object} - Validated camera options with defaults
+     */
+    static validateCameraOptions(options: CameraOptions): CameraOptions;
+    /**
+     * Get default camera options
+     * @returns {Object} - Default camera options
+     */
+    static getDefaultOptions(): {
+        quality: string;
+        format: string;
+        allowEditing: boolean;
+    };
+    /**
+     * Get default permission config
+     * @returns {Object} - Default permission config
+     */
+    static getDefaultPermissionConfig(): {
+        includeDetails: boolean;
+    };
+    /**
+     * Validate camera quality
+     * @param {string} quality - Quality string to validate
+     * @returns {boolean} - True if valid quality
+     */
+    static isValidQuality(quality: string): boolean;
+    /**
+     * Validate camera format
+     * @param {string} format - Format string to validate
+     * @returns {boolean} - True if valid format
+     */
+    static isValidFormat(format: string): boolean;
+    /**
+     * Validate camera device
+     * @param {string} device - Device string to validate
+     * @returns {boolean} - True if valid device
+     */
+    static isValidDevice(device: string): boolean;
+    /**
+     * Validate flash mode
+     * @param {string} flashMode - Flash mode string to validate
+     * @returns {boolean} - True if valid flash mode
+     */
+    static isValidFlashMode(flashMode: string): boolean;
+}
+export default CameraUtils;

package/dist/native/bridge/utils/CameraUtils.js

@@ -7,6 +7,10 @@ exports.default = void 0;
 var _NativeInterfaces = require("../constants/NativeInterfaces.js");
 var _NativeBridge = _interopRequireDefault(require("./NativeBridge.js"));
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/** Options accepted when opening the native camera. */
+
+/** Configuration accepted when requesting camera permission. */
+
 /**
  * Camera Utility Module
  * Provides Promise-based camera operations with proper option validation

package/dist/native/bridge/utils/FileObjectConverter.d.ts

@@ -0,0 +1,36 @@
+/**
+ * FileObjectConverter
+ * Converts base64 and URL file data to JavaScript File objects
+ * for direct use in FormData and POST API calls
+ */
+/**
+ * Convert base64 data URI to File object (synchronous)
+ * @param {string} base64String - Base64 data URI (e.g., "data:image/jpeg;base64,...")
+ * @param {string} filename - Desired filename for the File object
+ * @param {string} mimeType - MIME type (e.g., "image/jpeg")
+ * @returns {File} JavaScript File object
+ * @throws {Error} If base64 string is invalid or conversion fails
+ */
+export declare function base64ToFile(base64String: any, filename: any, mimeType: any): File;
+/**
+ * Fetch file from URL and convert to File object (asynchronous)
+ * Used for Framework Server routes (localhost:8080)
+ * @param {string} url - File URL (e.g., "http://localhost:8080/file/xyz")
+ * @param {string} filename - Desired filename for the File object
+ * @param {string} mimeType - MIME type (e.g., "image/jpeg")
+ * @returns {Promise<File>} JavaScript File object
+ * @throws {Error} If fetch fails or conversion fails
+ */
+export declare function urlToFile(url: any, filename: any, mimeType: any): Promise<File>;
+/**
+ * Check if a File object can be created from the given transport type
+ * @param {string} transport - Transport type (BRIDGE_BASE64, FRAMEWORK_SERVER, CONTENT_PROVIDER)
+ * @returns {boolean} True if File object can be created
+ */
+export declare function canCreateFileObject(transport: any): boolean;
+/**
+ * Get user-friendly error message for unsupported transport
+ * @param {string} transport - Transport type
+ * @returns {string} Error message
+ */
+export declare function getUnsupportedTransportMessage(transport: any): string;

package/dist/native/bridge/utils/NativeBridge.d.ts

@@ -0,0 +1,270 @@
+/**
+ * NativeBridge Utility
+ * Handles communication from Web to Native platforms
+ * Supports both Android (window.NativeBridge) and iOS (webkit.messageHandlers)
+ */
+declare class NativeBridgeUtil {
+    /**
+     * Platform detection, resolved once at construction.
+     *
+     * Declared without initializers so they erase at compile time — the
+     * constructor below stays the only thing that assigns them.
+     *
+     * These are a snapshot; `isAvailable()` re-detects live for callers that
+     * must not read a stale value.
+     */
+    isAndroid: boolean;
+    isIOS: boolean;
+    isNativeEnvironment: boolean;
+    constructor();
+    /**
+     * Detect if running on Android WebView
+     */
+    _detectAndroid(): boolean;
+    /**
+     * Detect if running on iOS WebView
+     */
+    _detectIOS(): boolean;
+    /**
+     * Log environment detection info for debugging
+     */
+    _logEnvironmentInfo(): void;
+    /**
+     * Validate command before execution
+     */
+    _validateCommand(command: any): void;
+    /**
+     * Execute command on Android platform
+     */
+    _executeAndroidCommand(command: any, data: any): boolean;
+    /**
+     * Execute command on iOS platform
+     */
+    _executeIOSCommand(command: any, data: any): boolean;
+    /**
+     * Main method to call native commands
+     * @param {string} command - The command to execute (from NATIVE_COMMANDS)
+     * @param {any} data - Optional data to pass to the native side
+     * @returns {boolean} - Success status
+     */
+    call(command: any, data?: any): boolean;
+    /**
+     * Video stream methods
+     */
+    videoStream: {
+        /**
+         * Start native camera video stream
+         * @param {Object} options - Stream options
+         *   facing: 'back' | 'front'
+         *   format: 'qr' | 'barcode' | 'all'  — format filter (default: 'all')
+         *   zoom: { auto: true, initial: 1.0 }  — auto-zoom via ML Kit, initial is multiplier (1.0=1x)
+         *   zoom: { auto: false, initial: 2.0 } — manual, starts at 2x
+         */
+        start: (options?: {}) => boolean;
+        /**
+         * Stop native camera video stream
+         */
+        stop: () => boolean;
+        /**
+         * Set zoom level multiplier (e.g. 1.0 = 1x, 2.0 = 2x)
+         * @param {number} zoomPct - multiplier >= 1.0
+         */
+        setZoom: (zoomPct: any) => boolean;
+        /**
+         * Enable or disable torch (back camera only)
+         * @param {boolean} on
+         */
+        setTorch: (on: any) => boolean;
+        /**
+         * Set target FPS range — triggers session restart
+         * @param {number|null} min - minimum fps (e.g. 15), null to clear
+         * @param {number|null} max - maximum fps (e.g. 30), null to clear
+         */
+        setFps: (min: any, max: any) => boolean;
+        /**
+         * Flip between front and back camera — restarts the native session internally
+         * Torch resets to off after flip; ON_TORCH_CHANGED(false) fires automatically.
+         */
+        flip: () => boolean;
+    };
+    /**
+     * Camera-specific methods for easier usage
+     */
+    camera: {
+        /**
+         * Open camera for photo capture
+         * @param {string} options - JSON string of camera options
+         */
+        open: (options?: any) => boolean;
+        /**
+         * Request camera permission
+         * @param {string} config - JSON string of permission config
+         */
+        requestPermission: (config?: any) => boolean;
+    };
+    /**
+     * File-specific methods for easier usage
+     */
+    file: {
+        /**
+         * Open file picker
+         * @param {string|Object|null} options - MIME type string or options object with advanced config
+         */
+        pick: (options?: string | Record<string, any> | null) => boolean;
+        /**
+         * Open file with external app
+         * @param {string} fileUrl - URL of the file to open
+         * @param {string} mimeType - Optional MIME type
+         */
+        openWithIntent: (fileUrl: any, mimeType?: any) => boolean;
+    };
+    /**
+     * Network helpers
+     */
+    network: {
+        /**
+         * Request current network status from native side
+         */
+        getStatus: () => boolean;
+    };
+    /**
+     * Haptic feedback methods
+     */
+    haptic: {
+        /**
+         * Request haptic feedback
+         * @param {string} feedbackType - Type of haptic feedback
+         */
+        feedback: (feedbackType?: string) => boolean;
+    };
+    /**
+     * Notification methods for local and push notifications
+     */
+    notification: {
+        /**
+         * Schedule a local notification
+         * @param {Object} config - Notification configuration object
+         */
+        scheduleLocal: (config: any) => boolean;
+        /**
+         * Cancel a local notification
+         * @param {string} notificationId - ID of the notification to cancel
+         */
+        cancelLocal: (notificationId: any) => boolean;
+        /**
+         * Request notification permission
+         */
+        requestPermission: () => boolean;
+        /**
+         * Register for push notifications
+         */
+        registerForPush: () => boolean;
+        /**
+         * Update badge count
+         * @param {number} count - Badge count number
+         */
+        updateBadge: (count: any) => boolean;
+        /**
+         * Subscribe to push notification topic
+         * @param {string} topic - Topic name to subscribe to
+         */
+        subscribeToTopic: (topic: any) => boolean;
+        /**
+         * Unsubscribe from push notification topic
+         * @param {string} topic - Topic name to unsubscribe from
+         */
+        unsubscribeFromTopic: (topic: any) => boolean;
+        /**
+         * Get list of subscribed topics
+         */
+        getSubscribedTopics: () => boolean;
+    };
+    /**
+     * Device info methods
+     */
+    device: {
+        /**
+         * Get device information
+         * @returns {Promise} - Returns device info through callback
+         */
+        getDeviceInfo: () => boolean;
+    };
+    /**
+     * Auth methods
+     */
+    auth: {
+        /**
+         * Trigger Google Sign-In (Credential Manager)
+         * @param {Object} options - config (clientId, nonce, autoSelect, etc.)
+         */
+        googleSignIn: (options?: {}) => boolean;
+    };
+    /** Safe area methods
+     */
+    safeArea: {
+        /**
+         * Get current safe area insets
+         * Returns insets through ON_SAFE_AREA_INSETS_UPDATED callback
+         */
+        get: () => boolean;
+    };
+    /**
+     * Security methods
+     */
+    security: {
+        /**
+         * Enable or disable FLAG_SECURE (prevents screenshots / app-switcher caching)
+         * @param {boolean} enable - true to secure, false to unsecure
+         */
+        setScreenSecure: (enable: any) => boolean;
+        /**
+         * Query current FLAG_SECURE status
+         * Returns result through ON_SCREEN_SECURE_SET callback
+         */
+        getScreenSecure: () => boolean;
+        /**
+         * Clear all WebView data (cache, history, cookies, WebStorage)
+         * Returns result through ON_WEB_DATA_CLEARED / ON_WEB_DATA_CLEAR_ERROR callback
+         */
+        clearWebData: () => boolean;
+    };
+    transition: {
+        /**
+         * Begin a native transition — native takes a snapshot/overlay of the current screen.
+         * @param {Object} options
+         *   type: 'slide' | 'fade'
+         *   direction: 'left' | 'right' | 'up' | 'down'  (slide only)
+         *   duration: number (ms, default 300)
+         *   timeout: number (ms, safety timer — native force-fades overlay if commitTransition is never called)
+         */
+        start: (options?: {}) => boolean;
+        /**
+         * Commit the transition — native animates the snapshot overlay out, revealing the new page.
+         */
+        commit: () => boolean;
+        /**
+         * Cancel the transition — native removes the overlay immediately without animating.
+         */
+        cancel: () => boolean;
+    };
+    /**
+     * Get environment info
+     */
+    getEnvironmentInfo(): {
+        isAndroid: boolean;
+        isIOS: boolean;
+        isNativeEnvironment: boolean;
+        platform: string;
+    };
+    /**
+     * Check if native bridge is available — live check, never stale
+     */
+    isAvailable(): boolean;
+    /**
+     * Debug method to test native bridge connectivity
+     */
+    testConnection(): void;
+}
+declare const nativeBridge: NativeBridgeUtil;
+export default nativeBridge;
+export { NativeBridgeUtil };

package/dist/native/bridge/utils/NativeBridge.js

@@ -11,6 +11,16 @@ var _NativeInterfaces = require("../constants/NativeInterfaces.js");
  * Supports both Android (window.NativeBridge) and iOS (webkit.messageHandlers)
  */
 class NativeBridgeUtil {
+  /**
+   * Platform detection, resolved once at construction.
+   *
+   * Declared without initializers so they erase at compile time — the
+   * constructor below stays the only thing that assigns them.
+   *
+   * These are a snapshot; `isAvailable()` re-detects live for callers that
+   * must not read a stale value.
+   */
+
   constructor() {
     this.isAndroid = this._detectAndroid();
     this.isIOS = this._detectIOS();

package/dist/native/buildAndroid/index.js

@@ -6,7 +6,7 @@ const {
   runCommand,
   runInteractiveCommand
 } = require("../utils.js");
-const TerminalProgress = require("../TerminalProgress.js").default;
+const TerminalProgress = require("../terminalProgress.js").default;
 const {
   composeAndroidPlugins
 } = require("../pluginComposerAndroid.js");

package/dist/native/buildAppAndroid.js

@@ -4,6 +4,9 @@ const {
   createAndroidBuild,
   pwd
 } = require("./buildAndroid/index.js");
+const {
+  formatBuildError
+} = require("./buildErrorFormat.js");
 const {
   WEBVIEW_CONFIG,
   BUILD_OUTPUT_PATH
@@ -19,6 +22,12 @@ async function main() {
   try {
     await buildAndroidApp();
   } catch (error) {
+    console.error(formatBuildError({
+      code: "ANDROID-000",
+      category: "ANDROID",
+      upstreamName: "Gradle",
+      error
+    }));
     process.exit(1);
   }
   process.exit(0);

package/dist/native/buildAppIos.js

@@ -12,6 +12,9 @@ const {
   resolveInternalPluginsRoot,
   resolvePluginConfig
 } = require("./internalPluginUtils.js");
+const {
+  formatBuildError
+} = require("./buildErrorFormat.js");
 const catalystCorePath = path.dirname(require.resolve("catalyst-core/package.json"));
 const {
   WEBVIEW_CONFIG,
@@ -46,7 +49,19 @@ async function main() {
     await syncPluginResources(pluginComposition);
     await buildForIOS(pluginComposition);
   } catch (error) {
-    progress.log("Build failed: " + error.message, "error");
+    // progress.log() prefixes every call with an icon/color and does a
+    // single console.log per invocation — it's built for single-line
+    // status messages, not our multi-line boxed verbose/debug output
+    // (piping a box through it would prefix an icon onto every border
+    // line and break the box shape). Bypass it here and use plain
+    // console.error instead, matching buildAppAndroid.js; progress.log
+    // is unaffected everywhere else in this build.
+    console.error(formatBuildError({
+      code: "IOS-000",
+      category: "IOS",
+      upstreamName: "Xcode/CocoaPods",
+      error
+    }));
     process.exit(1);
   }
   process.exit(0);