@molecule/app-react 1.0.0

package/dist/hooks/useOAuth.js

@@ -0,0 +1,348 @@
+/**
+ * React hook for OAuth authentication.
+ *
+ * Supports two initiation modes that share ONE callback path:
+ *   - {@link UseOAuthReturn.redirect} — full-page redirect (the default; unchanged).
+ *   - {@link UseOAuthReturn.loginViaPopup} — opens the provider in a popup so the
+ *     opener page never navigates (used by in-app auth modals). On completion the
+ *     popup relays the result to the opener via a STRICTLY-validated `postMessage`
+ *     and closes itself; the opener establishes the session in place.
+ *
+ * Security model for the popup relay (see inline notes at each gate):
+ *   - The popup posts ONLY to its own origin (`targetOrigin = location.origin`),
+ *     never `'*'`, so the bearer token can never be delivered to another origin.
+ *   - The opener accepts a result ONLY when ALL hold: `event.origin === location.origin`,
+ *     `event.source === thePopupWindowWeOpened`, and `event.data.type` matches our
+ *     private message type. Anything else is ignored — a forged cross-origin (or
+ *     wrong-window) message cannot inject a session.
+ *   - The popup-relay path is gated on `window.name === OAUTH_POPUP_WINDOW_NAME`
+ *     AND `window.opener`, so an ordinary full-page callback is completely
+ *     unaffected (it still establishes the session inline as before).
+ *   - The opener tears down its listener + timers on result, on user-close, and on
+ *     a hard timeout, so no stale handler lingers.
+ *
+ * @module
+ */
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+import { useAuthClient } from './useAuth.js';
+/**
+ * `window.open` name for the OAuth popup. The callback page relays its result to
+ * the opener ONLY when its own `window.name` equals this AND `window.opener`
+ * exists — so a normal (full-page) callback never takes the relay path.
+ */
+const OAUTH_POPUP_WINDOW_NAME = 'molecule-oauth-popup';
+/** Private `postMessage` type for the popup→opener result relay. */
+const OAUTH_RESULT_MESSAGE_TYPE = 'molecule:oauth-result';
+/** Hard cap on how long the opener waits for the popup before giving up. */
+const OAUTH_POPUP_TIMEOUT_MS = 5 * 60 * 1000;
+/**
+ * Hook for OAuth authentication.
+ *
+ * Reads OAuth configuration from the provided config and provides
+ * helpers to build OAuth URLs and start a login (full-page or popup).
+ * Automatically handles OAuth callbacks by detecting `code` and `state`
+ * URL parameters and exchanging them for a session — and, when the callback is
+ * running inside a popup we opened, relaying the result to the opener instead.
+ *
+ * @param config - Optional OAuth configuration override.
+ * @param config.baseURL - Base URL for the API server (e.g. "https://api.example.com").
+ * @param config.oauthProviders - List of supported OAuth provider names (e.g. ["google", "github"]).
+ * @param config.oauthEndpoint - Path prefix for OAuth routes (defaults to "/oauth").
+ * @param config.loginEndpoint - Path for the OAuth login POST endpoint (defaults to "/users/log-in/oauth").
+ * @param config.onSuccess - Callback after successful OAuth login.
+ * @param config.onError - Callback on OAuth login failure.
+ *
+ * @example
+ * ```tsx
+ * const { providers, redirect, loginViaPopup } = useOAuth()
+ *
+ * return (
+ *   <div>
+ *     {providers.map(provider => (
+ *       <button key={provider} onClick={() => loginViaPopup(provider)}>
+ *         Login with {provider}
+ *       </button>
+ *     ))}
+ *   </div>
+ * )
+ * ```
+ * @returns OAuth helpers: providers, getOAuthUrl, redirect, and loginViaPopup.
+ */
+export function useOAuth(config) {
+    const authClient = useAuthClient();
+    const providers = useMemo(() => config?.oauthProviders ?? [], [config?.oauthProviders]);
+    const baseURL = config?.baseURL ?? '';
+    const oauthEndpoint = config?.oauthEndpoint ?? '/oauth';
+    const loginEndpoint = config?.loginEndpoint ?? '/users/log-in/oauth';
+    const getOAuthUrl = useCallback((provider) => {
+        // Encode the provider as a single path segment so a (future) caller passing an
+        // untrusted value can never inject a path/query/scheme into the opened URL —
+        // defense-in-depth on top of the upstream static provider allowlist. Plain
+        // provider names ('github', 'google') pass through unchanged.
+        return `${baseURL}${oauthEndpoint}/${encodeURIComponent(provider)}`;
+    }, [baseURL, oauthEndpoint]);
+    /** Stash which provider initiated the flow so the callback knows it's ours. */
+    const stashProvider = (provider) => {
+        try {
+            sessionStorage.setItem('oauth_provider', provider);
+        }
+        catch (_error) {
+            /* SSR-safe — sessionStorage is unavailable in SSR/sandboxed environments */
+        }
+    };
+    /**
+     * Append the current page's PATH as `redirect_to` so the api's initiation
+     * endpoint (`GET /users/oauth/:provider`) builds a provider `redirect_uri`
+     * that lands the callback back on THIS page — the one with `useOAuth`
+     * mounted (e.g. `/login`) — instead of the app root, where nothing may be
+     * listening for the `code` param. Path only (no origin/query): the server
+     * validates it as a same-origin absolute path, so it can never become an
+     * open redirect. Servers that predate the param simply ignore it.
+     */
+    const withReturnPath = (url) => {
+        const path = typeof window !== 'undefined' ? window.location.pathname : '';
+        if (!path || path === '/')
+            return url;
+        return `${url}${url.includes('?') ? '&' : '?'}redirect_to=${encodeURIComponent(path)}`;
+    };
+    /**
+     * Establish the authenticated session from an exchange result: seed the access
+     * token + user and let `initialize()` flip `authenticated`. Mirrors what
+     * `authClient.login()` does for password login. Returns whether a user was set
+     * (a result with no user is not a real session).
+     */
+    const establishSession = useCallback(async (token, user) => {
+        // Seed the token via the auth client's configured token storage adapter
+        // (in-memory by default) — NOT localStorage directly. Writing the bearer
+        // token to localStorage violates the in-memory-default storage contract and
+        // makes it JS-readable (XSS-exfiltratable). [P5FE-31 secure-by-default]
+        if (token)
+            authClient.setAccessToken(token);
+        if (user && typeof user === 'object') {
+            authClient.setUser(user);
+            await authClient.initialize();
+            return true;
+        }
+        return false;
+    }, [authClient]);
+    const redirect = useCallback((provider) => {
+        stashProvider(provider);
+        window.location.href = withReturnPath(getOAuthUrl(provider));
+    }, [getOAuthUrl]);
+    // The currently-open OAuth popup, so a second click focuses it instead of
+    // stacking a second flow (the relay gates already fail safe, but one window is
+    // cleaner and avoids an orphaned listener until the timeout reaps it).
+    const activePopupRef = useRef(null);
+    const loginViaPopup = useCallback((provider) => {
+        // A flow is already open — focus it rather than starting another.
+        if (activePopupRef.current && !activePopupRef.current.closed) {
+            try {
+                activePopupRef.current.focus();
+            }
+            catch (_error) {
+                /* best-effort focus */
+            }
+            return;
+        }
+        stashProvider(provider);
+        const url = withReturnPath(getOAuthUrl(provider));
+        // A named popup. We intentionally do NOT pass `noopener` — the popup needs
+        // `window.opener` to relay its result back. The window only ever navigates
+        // to OUR api → the trusted provider → OUR origin, so this is the standard
+        // OAuth-popup trade-off (a malicious *provider* could touch `window.opener`,
+        // which is out of scope; we don't open attacker-controlled URLs here).
+        const features = 'popup=yes,width=520,height=680,menubar=no,toolbar=no,location=yes';
+        const popup = window.open(url, OAUTH_POPUP_WINDOW_NAME, features);
+        // Popup blocked (or unavailable) → fall back to a full-page redirect so login
+        // still works. No listener is registered in this branch.
+        if (!popup) {
+            window.location.href = url;
+            return;
+        }
+        activePopupRef.current = popup;
+        let settled = false;
+        const timers = {};
+        const cleanup = () => {
+            window.removeEventListener('message', onMessage);
+            if (timers.closed)
+                clearInterval(timers.closed);
+            if (timers.timeout)
+                clearTimeout(timers.timeout);
+            if (activePopupRef.current === popup)
+                activePopupRef.current = null;
+        };
+        const onMessage = (event) => {
+            // SECURITY — accept the result ONLY from our own origin, ONLY from the exact
+            // popup window we opened, and ONLY when it carries our private type. Any one
+            // failing means a forged / unrelated message: ignore it silently. This is
+            // what prevents a malicious page from injecting a session.
+            if (event.origin !== window.location.origin)
+                return;
+            if (event.source !== popup)
+                return;
+            const data = event.data;
+            if (!data || typeof data !== 'object' || data.type !== OAUTH_RESULT_MESSAGE_TYPE)
+                return;
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            try {
+                popup.close();
+            }
+            catch (_error) {
+                /* already closed — nothing to do */
+            }
+            if (data.ok) {
+                void establishSession(data.token, data.user).then((ok) => {
+                    if (ok)
+                        config?.onSuccess?.();
+                    else
+                        config?.onError?.('OAuth login failed');
+                });
+            }
+            else {
+                config?.onError?.(typeof data.error === 'string' ? data.error : 'OAuth login failed');
+            }
+        };
+        window.addEventListener('message', onMessage);
+        // The user closed the popup without completing — silently stop waiting (no
+        // error toast for a deliberate cancel) and release the listener.
+        timers.closed = setInterval(() => {
+            if (popup.closed && !settled) {
+                settled = true;
+                cleanup();
+            }
+        }, 500);
+        // Hard safety timeout so a wedged popup never leaks a listener forever.
+        timers.timeout = setTimeout(() => {
+            if (!settled) {
+                settled = true;
+                cleanup();
+                try {
+                    popup.close();
+                }
+                catch (_error) {
+                    /* best-effort */
+                }
+            }
+        }, OAUTH_POPUP_TIMEOUT_MS);
+    }, [getOAuthUrl, establishSession, config]);
+    // Handle OAuth callback — detect code + state in URL params
+    useEffect(() => {
+        const params = new URLSearchParams(window.location.search);
+        const code = params.get('code');
+        const state = params.get('state');
+        if (!code)
+            return;
+        // Retrieve the provider that initiated the flow
+        let provider = null;
+        try {
+            provider = sessionStorage.getItem('oauth_provider');
+        }
+        catch (_error) {
+            /* SSR-safe — sessionStorage is unavailable in SSR/sandboxed environments */
+        }
+        if (!provider)
+            return;
+        // Are we the OAuth popup we opened? Relay the result to the opener instead of
+        // establishing the session in this (about-to-close) window. Gated on BOTH the
+        // window name AND window.opener so a normal full-page callback never relays.
+        const inPopup = typeof window !== 'undefined' && !!window.opener && window.name === OAUTH_POPUP_WINDOW_NAME;
+        // Clean up URL (remove code/state params) and sessionStorage
+        const cleanUrl = new URL(window.location.href);
+        cleanUrl.searchParams.delete('code');
+        cleanUrl.searchParams.delete('state');
+        window.history.replaceState({}, '', cleanUrl.toString());
+        try {
+            sessionStorage.removeItem('oauth_provider');
+        }
+        catch (_error) {
+            /* SSR-safe — sessionStorage is unavailable in SSR/sandboxed environments */
+        }
+        /** Relay a result to the opener (popup path) — origin-pinned, never `'*'`. */
+        const relayToOpener = (message) => {
+            try {
+                // targetOrigin is our OWN origin: the browser delivers the message (and the
+                // token it carries) ONLY if the opener is still on this origin. Never '*'.
+                window.opener?.postMessage(message, window.location.origin);
+            }
+            catch (_error) {
+                /* opener gone / cross-origin — the opener's close-poll will recover */
+            }
+            try {
+                window.close();
+            }
+            catch (_error) {
+                /* best-effort */
+            }
+        };
+        // Exchange code for session
+        const exchangeCode = async () => {
+            try {
+                const response = await fetch(`${baseURL}${loginEndpoint}`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    credentials: 'include', // Send cookies (oauth_state) for state validation
+                    body: JSON.stringify({
+                        server: provider,
+                        code,
+                        state: state || undefined,
+                        redirect_uri: window.location.origin,
+                    }),
+                });
+                if (!response.ok) {
+                    const data = await response.json().catch(() => ({ error: 'OAuth login failed' }));
+                    const error = data.error || 'OAuth login failed';
+                    if (inPopup) {
+                        relayToOpener({ type: OAUTH_RESULT_MESSAGE_TYPE, ok: false, error });
+                        return;
+                    }
+                    config?.onError?.(error);
+                    return;
+                }
+                const data = await response.json().catch(() => null);
+                // Store the token from the response
+                const authHeader = response.headers.get('authorization') || response.headers.get('set-authorization');
+                const token = authHeader ? authHeader.replace('Bearer ', '') : null;
+                // The authenticated user is `props` (molecule resource convention) or `user`
+                // (generic AuthResult). OAuth issues no refresh token, so we carry the token +
+                // user to whoever will own the session.
+                const user = data && typeof data === 'object'
+                    ? (data.props ??
+                        data.user ??
+                        null)
+                    : null;
+                if (inPopup) {
+                    // Relay to the opener — it (same origin) establishes the session in place.
+                    // Do NOT establish it here; this window is about to close.
+                    relayToOpener({ type: OAUTH_RESULT_MESSAGE_TYPE, ok: true, token, user });
+                    return;
+                }
+                // Full-page callback: establish the session here, then fire onSuccess —
+                // unchanged behavior.
+                const ok = await establishSession(token, user);
+                if (ok)
+                    config?.onSuccess?.();
+                else
+                    config?.onError?.('OAuth login failed');
+            }
+            catch (err) {
+                const error = err instanceof Error ? err.message : 'OAuth login failed';
+                if (inPopup) {
+                    relayToOpener({ type: OAUTH_RESULT_MESSAGE_TYPE, ok: false, error });
+                    return;
+                }
+                config?.onError?.(error);
+            }
+        };
+        exchangeCode();
+    }, [baseURL, loginEndpoint, config, establishSession]);
+    return {
+        providers,
+        getOAuthUrl,
+        redirect,
+        loginViaPopup,
+    };
+}
+//# sourceMappingURL=useOAuth.js.map

package/dist/hooks/useOAuth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useOAuth.js","sourceRoot":"","sources":["../../src/hooks/useOAuth.ts"],"names":[],"mappings":"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"}

package/dist/hooks/usePasswordReset.d.ts

@@ -0,0 +1,43 @@
+/**
+ * React hook for password reset with async state tracking.
+ *
+ * @module
+ */
+import type { PasswordResetConfirm, PasswordResetRequest } from '@molecule/app-auth';
+import { type UsePromiseState } from './usePromise.js';
+/**
+ * Return type for usePasswordReset hook.
+ */
+export interface UsePasswordResetReturn {
+    requestStatus: UsePromiseState<void>['status'];
+    requestError: UsePromiseState<void>['error'];
+    confirmStatus: UsePromiseState<void>['status'];
+    confirmError: UsePromiseState<void>['error'];
+    requestReset: (data: PasswordResetRequest) => Promise<void>;
+    confirmReset: (data: PasswordResetConfirm) => Promise<void>;
+    reset: () => void;
+}
+/**
+ * Hook for password reset flow with async state tracking.
+ *
+ * Provides separate tracking for the request and confirm steps.
+ *
+ * @returns Password reset state and actions
+ *
+ * @example
+ * ```tsx
+ * const { requestStatus, requestError, requestReset, confirmReset } = usePasswordReset()
+ *
+ * // Step 1: Request reset
+ * <button onClick={() => requestReset({ email })} disabled={requestStatus === 'pending'}>
+ *   Send Reset Email
+ * </button>
+ *
+ * // Step 2: Confirm reset
+ * <button onClick={() => confirmReset({ token, password })}>
+ *   Set New Password
+ * </button>
+ * ```
+ */
+export declare function usePasswordReset(): UsePasswordResetReturn;
+//# sourceMappingURL=usePasswordReset.d.ts.map

package/dist/hooks/usePasswordReset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePasswordReset.d.ts","sourceRoot":"","sources":["../../src/hooks/usePasswordReset.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAGpF,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAElE;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,aAAa,EAAE,eAAe,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,CAAA;IAC9C,YAAY,EAAE,eAAe,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAA;IAC5C,aAAa,EAAE,eAAe,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,CAAA;IAC9C,YAAY,EAAE,eAAe,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAA;IAC5C,YAAY,EAAE,CAAC,IAAI,EAAE,oBAAoB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3D,YAAY,EAAE,CAAC,IAAI,EAAE,oBAAoB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3D,KAAK,EAAE,MAAM,IAAI,CAAA;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,IAAI,sBAAsB,CA4BzD"}

package/dist/hooks/usePasswordReset.js

@@ -0,0 +1,50 @@
+/**
+ * React hook for password reset with async state tracking.
+ *
+ * @module
+ */
+import { useCallback } from 'react';
+import { useAuthClient } from './useAuth.js';
+import { usePromise } from './usePromise.js';
+/**
+ * Hook for password reset flow with async state tracking.
+ *
+ * Provides separate tracking for the request and confirm steps.
+ *
+ * @returns Password reset state and actions
+ *
+ * @example
+ * ```tsx
+ * const { requestStatus, requestError, requestReset, confirmReset } = usePasswordReset()
+ *
+ * // Step 1: Request reset
+ * <button onClick={() => requestReset({ email })} disabled={requestStatus === 'pending'}>
+ *   Send Reset Email
+ * </button>
+ *
+ * // Step 2: Confirm reset
+ * <button onClick={() => confirmReset({ token, password })}>
+ *   Set New Password
+ * </button>
+ * ```
+ */
+export function usePasswordReset() {
+    const client = useAuthClient();
+    const requestFn = useCallback((data) => client.requestPasswordReset(data), [client]);
+    const confirmFn = useCallback((data) => client.confirmPasswordReset(data), [client]);
+    const [requestState, requestCall] = usePromise(requestFn);
+    const [confirmState, confirmCall] = usePromise(confirmFn);
+    return {
+        requestStatus: requestState.status,
+        requestError: requestState.error,
+        confirmStatus: confirmState.status,
+        confirmError: confirmState.error,
+        requestReset: requestCall,
+        confirmReset: confirmCall,
+        reset: () => {
+            requestState.reset();
+            confirmState.reset();
+        },
+    };
+}
+//# sourceMappingURL=usePasswordReset.js.map

package/dist/hooks/usePasswordReset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePasswordReset.js","sourceRoot":"","sources":["../../src/hooks/usePasswordReset.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAA;AAInC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC5C,OAAO,EAAE,UAAU,EAAwB,MAAM,iBAAiB,CAAA;AAelE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,MAAM,GAAG,aAAa,EAAE,CAAA;IAE9B,MAAM,SAAS,GAAG,WAAW,CAC3B,CAAC,IAA0B,EAAE,EAAE,CAAC,MAAM,CAAC,oBAAoB,CAAC,IAAI,CAAC,EACjE,CAAC,MAAM,CAAC,CACT,CAAA;IAED,MAAM,SAAS,GAAG,WAAW,CAC3B,CAAC,IAA0B,EAAE,EAAE,CAAC,MAAM,CAAC,oBAAoB,CAAC,IAAI,CAAC,EACjE,CAAC,MAAM,CAAC,CACT,CAAA;IAED,MAAM,CAAC,YAAY,EAAE,WAAW,CAAC,GAAG,UAAU,CAAC,SAAS,CAAC,CAAA;IACzD,MAAM,CAAC,YAAY,EAAE,WAAW,CAAC,GAAG,UAAU,CAAC,SAAS,CAAC,CAAA;IAEzD,OAAO;QACL,aAAa,EAAE,YAAY,CAAC,MAAM;QAClC,YAAY,EAAE,YAAY,CAAC,KAAK;QAChC,aAAa,EAAE,YAAY,CAAC,MAAM;QAClC,YAAY,EAAE,YAAY,CAAC,KAAK;QAChC,YAAY,EAAE,WAAW;QACzB,YAAY,EAAE,WAAW;QACzB,KAAK,EAAE,GAAG,EAAE;YACV,YAAY,CAAC,KAAK,EAAE,CAAA;YACpB,YAAY,CAAC,KAAK,EAAE,CAAA;QACtB,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/hooks/usePlatform.d.ts

@@ -0,0 +1,38 @@
+/**
+ * React hook for platform detection.
+ *
+ * @module
+ */
+import type { Platform } from '@molecule/app-platform';
+/**
+ * Hook return type.
+ */
+export interface UsePlatformResult {
+    platform: Platform;
+    isNative: boolean;
+    isMobile: boolean;
+    isDesktop: boolean;
+    isWeb: boolean;
+    isDevelopment: boolean;
+    isProduction: boolean;
+    isPlatform: (...platforms: Platform[]) => boolean;
+}
+/**
+ * Hook for platform detection.
+ *
+ * Uses module-level functions — platform is a singleton, not context-provided.
+ * Platform info is static and doesn't change at runtime, so this uses `useMemo`.
+ *
+ * @returns Platform information and utility methods
+ *
+ * @example
+ * ```tsx
+ * const { isWeb, isMobile, isPlatform } = usePlatform()
+ *
+ * if (isPlatform('ios', 'android')) {
+ *   return <NativeLayout />
+ * }
+ * ```
+ */
+export declare function usePlatform(): UsePlatformResult;
+//# sourceMappingURL=usePlatform.d.ts.map

package/dist/hooks/usePlatform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePlatform.d.ts","sourceRoot":"","sources":["../../src/hooks/usePlatform.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAgB,MAAM,wBAAwB,CAAA;AAGpE;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,QAAQ,CAAA;IAClB,QAAQ,EAAE,OAAO,CAAA;IACjB,QAAQ,EAAE,OAAO,CAAA;IACjB,SAAS,EAAE,OAAO,CAAA;IAClB,KAAK,EAAE,OAAO,CAAA;IACd,aAAa,EAAE,OAAO,CAAA;IACtB,YAAY,EAAE,OAAO,CAAA;IACrB,UAAU,EAAE,CAAC,GAAG,SAAS,EAAE,QAAQ,EAAE,KAAK,OAAO,CAAA;CAClD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,IAAI,iBAAiB,CAe/C"}

package/dist/hooks/usePlatform.js

@@ -0,0 +1,40 @@
+/**
+ * React hook for platform detection.
+ *
+ * @module
+ */
+import { useMemo } from 'react';
+import { isPlatform, platform } from '@molecule/app-platform';
+/**
+ * Hook for platform detection.
+ *
+ * Uses module-level functions — platform is a singleton, not context-provided.
+ * Platform info is static and doesn't change at runtime, so this uses `useMemo`.
+ *
+ * @returns Platform information and utility methods
+ *
+ * @example
+ * ```tsx
+ * const { isWeb, isMobile, isPlatform } = usePlatform()
+ *
+ * if (isPlatform('ios', 'android')) {
+ *   return <NativeLayout />
+ * }
+ * ```
+ */
+export function usePlatform() {
+    return useMemo(() => {
+        const info = platform();
+        return {
+            platform: info.platform,
+            isNative: info.isNative,
+            isMobile: info.isMobile,
+            isDesktop: info.isDesktop,
+            isWeb: info.isWeb,
+            isDevelopment: info.isDevelopment,
+            isProduction: info.isProduction,
+            isPlatform: (...platforms) => isPlatform(...platforms),
+        };
+    }, []);
+}
+//# sourceMappingURL=usePlatform.js.map

package/dist/hooks/usePlatform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePlatform.js","sourceRoot":"","sources":["../../src/hooks/usePlatform.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAA;AAG/B,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAgB7D;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,WAAW;IACzB,OAAO,OAAO,CAAC,GAAG,EAAE;QAClB,MAAM,IAAI,GAAiB,QAAQ,EAAE,CAAA;QAErC,OAAO;YACL,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,aAAa,EAAE,IAAI,CAAC,aAAa;YACjC,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,UAAU,EAAE,CAAC,GAAG,SAAqB,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,SAAS,CAAC;SACnE,CAAA;IACH,CAAC,EAAE,EAAE,CAAC,CAAA;AACR,CAAC"}

package/dist/hooks/usePreview.d.ts

@@ -0,0 +1,20 @@
+/**
+ * React hook for live preview provider.
+ *
+ * @module
+ */
+import type { PreviewProvider } from '@molecule/app-live-preview';
+import type { UsePreviewResult } from '../types.js';
+/**
+ * Access the preview provider from context.
+ * @returns The PreviewProvider instance from the nearest PreviewContext.
+ * @throws {Error} If called outside a PreviewProvider.
+ */
+export declare function usePreviewProvider(): PreviewProvider;
+/**
+ * Hook for live preview management.
+ *
+ * @returns Preview state and controls: state (url, isLoading, device, error, isConnected), setUrl, refresh, setDevice, and openExternal.
+ */
+export declare function usePreview(): UsePreviewResult;
+//# sourceMappingURL=usePreview.d.ts.map

package/dist/hooks/usePreview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePreview.d.ts","sourceRoot":"","sources":["../../src/hooks/usePreview.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAe,eAAe,EAAgB,MAAM,4BAA4B,CAAA;AAG5F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAEnD;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,CAUpD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,IAAI,gBAAgB,CA8C7C"}

package/dist/hooks/usePreview.js

@@ -0,0 +1,62 @@
+/**
+ * React hook for live preview provider.
+ *
+ * @module
+ */
+import { useCallback, useContext, useRef, useSyncExternalStore } from 'react';
+import { t } from '@molecule/app-i18n';
+import { PreviewContext } from '../contexts.js';
+/**
+ * Access the preview provider from context.
+ * @returns The PreviewProvider instance from the nearest PreviewContext.
+ * @throws {Error} If called outside a PreviewProvider.
+ */
+export function usePreviewProvider() {
+    const provider = useContext(PreviewContext);
+    if (!provider) {
+        throw new Error(t('react.error.usePreviewOutsideProvider', undefined, {
+            defaultValue: 'usePreviewProvider must be used within a PreviewProvider',
+        }));
+    }
+    return provider;
+}
+/**
+ * Hook for live preview management.
+ *
+ * @returns Preview state and controls: state (url, isLoading, device, error, isConnected), setUrl, refresh, setDevice, and openExternal.
+ */
+export function usePreview() {
+    const provider = usePreviewProvider();
+    const cachedRef = useRef(null);
+    const getSnapshot = useCallback(() => {
+        const next = provider.getState();
+        const prev = cachedRef.current;
+        if (prev &&
+            prev.url === next.url &&
+            prev.currentUrl === next.currentUrl &&
+            prev.isLoading === next.isLoading &&
+            prev.device === next.device &&
+            prev.error === next.error &&
+            prev.isConnected === next.isConnected &&
+            prev.canGoBack === next.canGoBack &&
+            prev.canGoForward === next.canGoForward &&
+            prev.loadNonce === next.loadNonce) {
+            return prev;
+        }
+        cachedRef.current = next;
+        return next;
+    }, [provider]);
+    const subscribe = useCallback((onStoreChange) => {
+        return provider.subscribe(() => onStoreChange());
+    }, [provider]);
+    const state = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+    const setUrl = useCallback((url) => provider.setUrl(url), [provider]);
+    const refresh = useCallback(() => provider.refresh(), [provider]);
+    const setDevice = useCallback((device) => provider.setDevice(device), [provider]);
+    const openExternal = useCallback(() => provider.openExternal(), [provider]);
+    const recordNavigation = useCallback((url, isReplace) => provider.recordNavigation(url, isReplace), [provider]);
+    const back = useCallback(() => provider.back(), [provider]);
+    const forward = useCallback(() => provider.forward(), [provider]);
+    return { state, setUrl, refresh, setDevice, openExternal, recordNavigation, back, forward };
+}
+//# sourceMappingURL=usePreview.js.map

package/dist/hooks/usePreview.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePreview.js","sourceRoot":"","sources":["../../src/hooks/usePreview.ts"],"names":[],"mappings":"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"}