@sudobility/sudojo_lib 0.0.200 → 0.0.203

package/dist/hooks/useDailyGame.js

@@ -3,49 +3,21 @@
  * Handles auth and subscription status with automatic refresh
  */
 import { useEffect, useMemo, useRef } from 'react';
+import { useResolvedSudojoApi } from '../context/SudojoApiContext';
 import { useSudojoDailyByDate } from '@sudobility/sudojo_client';
-/** Get today's date in local timezone as YYYY-MM-DD */
-function getLocalDateString() {
-    const now = new Date();
-    const year = now.getFullYear();
-    const month = String(now.getMonth() + 1).padStart(2, '0');
-    const day = String(now.getDate()).padStart(2, '0');
-    return `${year}-${month}-${day}`;
-}
-/** Check if response indicates auth is required */
-function isAuthRequired(response, error) {
-    if (response?.success === false &&
-        response.action?.type === 'auth_required') {
-        return true;
-    }
-    if (error && typeof error === 'object') {
-        const err = error;
-        if (err.message?.includes('Account required'))
-            return true;
-    }
-    return false;
-}
-/** Check if response indicates subscription is required */
-function isSubscriptionRequired(response, error) {
-    if (response?.success === false &&
-        response.action?.type === 'subscription_required') {
-        return true;
-    }
-    if (error && typeof error === 'object') {
-        const err = error;
-        if (err.message?.includes('Daily limit reached') ||
-            err.message?.includes('subscription')) {
-            return true;
-        }
-    }
-    return false;
-}
+import { getUtcDateString, normalizeDailyDate } from '../utils/date';
+import { getGameFetchStatus, } from '../utils/gameFetchStatus';
 /**
  * Hook for fetching today's daily puzzle
  *
  * Automatically refetches when auth token or subscription status changes.
  * Returns status indicating whether auth or subscription is required.
  *
+ * "Today" is the **UTC** date (getUtcDateString), the same day the API's
+ * `/dailies/today` serves, computed once per mount. (It used to be the local
+ * date, which asked for tomorrow's or yesterday's daily near midnight.)
+ * `dailyDate` is the daily's own `YYYY-MM-DD`, never timezone-shifted.
+ *
  * @param options - Hook options
  * @returns Daily puzzle data and status
  *
@@ -69,44 +41,31 @@ function isSubscriptionRequired(response, error) {
  * ```
  */
 export function useDailyGame(options) {
-    const { networkClient, baseUrl, token, subscriptionActive = false, enabled: _enabled = true, } = options;
+    const { subscriptionActive = false, enabled: _enabled = true } = options;
+    const { networkClient, baseUrl, token } = useResolvedSudojoApi(options, 'useDailyGame');
     // Track previous state to detect changes
     const prevStateRef = useRef({
         authToken: token,
         subscriptionActive,
     });
-    const todayDate = useMemo(() => getLocalDateString(), []);
+    // "Today" is the UTC date, the same day the API's /dailies/today serves.
+    const todayDate = useMemo(() => getUtcDateString(), []);
     const { data, isLoading, error, refetch } = useSudojoDailyByDate(networkClient, baseUrl, token, todayDate);
     // Determine status based on response
-    const status = useMemo(() => {
-        if (isLoading)
-            return 'loading';
-        if (isAuthRequired(data, error))
-            return 'auth_required';
-        if (isSubscriptionRequired(data, error))
-            return 'subscription_required';
-        if (error)
-            return 'error';
-        if (data?.success && data.data)
-            return 'success';
-        return 'loading';
-    }, [isLoading, data, error]);
+    const status = useMemo(() => getGameFetchStatus({
+        isLoading,
+        response: data,
+        error,
+    }), [isLoading, data, error]);
     const daily = useMemo(() => {
         if (data?.success && data.data) {
             return data.data;
         }
         return null;
     }, [data]);
-    const dailyDate = useMemo(() => {
-        if (daily?.date) {
-            const d = new Date(daily.date);
-            const year = d.getFullYear();
-            const month = String(d.getMonth() + 1).padStart(2, '0');
-            const day = String(d.getDate()).padStart(2, '0');
-            return `${year}-${month}-${day}`;
-        }
-        return null;
-    }, [daily]);
+    // The daily's calendar date as sent, without a timezone shift
+    // (`new Date('YYYY-MM-DD')` is UTC midnight, the previous day west of UTC).
+    const dailyDate = useMemo(() => normalizeDailyDate(daily?.date), [daily]);
     // Auto-refresh when auth token or subscription status changes
     useEffect(() => {
         const prev = prevStateRef.current;

package/dist/hooks/useDailyGame.js.map

@@ -1 +1 @@
-{"version":3,"file":"useDailyGame.js","sourceRoot":"","sources":["../../src/hooks/useDailyGame.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Hook for fetching and managing today's daily puzzle\n * Handles auth and subscription status with automatic refresh\n */\n\nimport { useEffect, useMemo, useRef } from 'react';\nimport type { Daily } from '@sudobility/sudojo_types';\nimport type { NetworkClient } from '@sudobility/types';\nimport { useSudojoDailyByDate } from '@sudobility/sudojo_client';\nimport type { GameFetchStatus } from './useLevelGame';\n\n/** Get today's date in local timezone as YYYY-MM-DD */\nfunction getLocalDateString(): string {\n  const now = new Date();\n  const year = now.getFullYear();\n  const month = String(now.getMonth() + 1).padStart(2, '0');\n  const day = String(now.getDate()).padStart(2, '0');\n  return `${year}-${month}-${day}`;\n}\n\n/** Extended API response with action field from Sudojo API */\ninterface SudojoApiResponse<T> {\n  success: boolean;\n  data?: T;\n  error?: string | null | undefined;\n  message?: string;\n  action?: {\n    type: string;\n    options?: string[];\n  };\n}\n\n/** Check if response indicates auth is required */\nfunction isAuthRequired(\n  response: SudojoApiResponse<unknown> | undefined,\n  error: unknown\n): boolean {\n  if (\n    response?.success === false &&\n    response.action?.type === 'auth_required'\n  ) {\n    return true;\n  }\n  if (error && typeof error === 'object') {\n    const err = error as { message?: string };\n    if (err.message?.includes('Account required')) return true;\n  }\n  return false;\n}\n\n/** Check if response indicates subscription is required */\nfunction isSubscriptionRequired(\n  response: SudojoApiResponse<unknown> | undefined,\n  error: unknown\n): boolean {\n  if (\n    response?.success === false &&\n    response.action?.type === 'subscription_required'\n  ) {\n    return true;\n  }\n  if (error && typeof error === 'object') {\n    const err = error as { message?: string };\n    if (\n      err.message?.includes('Daily limit reached') ||\n      err.message?.includes('subscription')\n    ) {\n      return true;\n    }\n  }\n  return false;\n}\n\nexport interface UseDailyGameOptions {\n  /** Network client for API calls */\n  networkClient: NetworkClient;\n  /** Base URL for the Sudojo API */\n  baseUrl: string;\n  /** Access token for authentication */\n  token: string;\n  /** Whether subscription is currently active */\n  subscriptionActive?: boolean;\n  /** Whether to enable the query */\n  enabled?: boolean;\n}\n\nexport interface UseDailyGameResult {\n  /** Today's daily puzzle */\n  daily: Daily | null;\n  /** The date string for this daily (YYYY-MM-DD) */\n  dailyDate: string | null;\n  /** Current status of the game fetch */\n  status: GameFetchStatus;\n  /** Whether data is loading */\n  isLoading: boolean;\n  /** Error if fetch failed */\n  error: Error | null;\n  /** Refetch the daily puzzle */\n  refetch: () => void;\n}\n\n/**\n * Hook for fetching today's daily puzzle\n *\n * Automatically refetches when auth token or subscription status changes.\n * Returns status indicating whether auth or subscription is required.\n *\n * @param options - Hook options\n * @returns Daily puzzle data and status\n *\n * @example\n * ```tsx\n * function DailyPage() {\n *   const { daily, dailyDate, status, refetch } = useDailyGame({\n *     networkClient,\n *     config,\n *     auth,\n *     subscriptionActive: subscription.isActive,\n *   });\n *\n *   if (status === 'loading') return <Loading />;\n *   if (status === 'auth_required') return <AuthRequired onLogin={openAuthModal} />;\n *   if (status === 'subscription_required') return <SubscriptionPaywall onSuccess={refetch} />;\n *   if (status === 'error') return <Error />;\n *\n *   return <SudokuGame puzzle={daily.board} solution={daily.solution} />;\n * }\n * ```\n */\nexport function useDailyGame(options: UseDailyGameOptions): UseDailyGameResult {\n  const {\n    networkClient,\n    baseUrl,\n    token,\n    subscriptionActive = false,\n    enabled: _enabled = true,\n  } = options;\n\n  // Track previous state to detect changes\n  const prevStateRef = useRef({\n    authToken: token,\n    subscriptionActive,\n  });\n\n  const todayDate = useMemo(() => getLocalDateString(), []);\n\n  const { data, isLoading, error, refetch } = useSudojoDailyByDate(\n    networkClient,\n    baseUrl,\n    token,\n    todayDate\n  );\n\n  // Determine status based on response\n  const status = useMemo((): GameFetchStatus => {\n    if (isLoading) return 'loading';\n    if (isAuthRequired(data, error)) return 'auth_required';\n    if (isSubscriptionRequired(data, error)) return 'subscription_required';\n    if (error) return 'error';\n    if (data?.success && data.data) return 'success';\n    return 'loading';\n  }, [isLoading, data, error]);\n\n  const daily = useMemo(() => {\n    if (data?.success && data.data) {\n      return data.data;\n    }\n    return null;\n  }, [data]);\n\n  const dailyDate = useMemo((): string | null => {\n    if (daily?.date) {\n      const d = new Date(daily.date);\n      const year = d.getFullYear();\n      const month = String(d.getMonth() + 1).padStart(2, '0');\n      const day = String(d.getDate()).padStart(2, '0');\n      return `${year}-${month}-${day}`;\n    }\n    return null;\n  }, [daily]);\n\n  // Auto-refresh when auth token or subscription status changes\n  useEffect(() => {\n    const prev = prevStateRef.current;\n    const authChanged = prev.authToken !== token;\n    const subscriptionChanged = !prev.subscriptionActive && subscriptionActive;\n\n    if (authChanged || subscriptionChanged) {\n      refetch();\n    }\n\n    // Update ref for next comparison\n    prevStateRef.current = { authToken: token, subscriptionActive };\n  }, [token, subscriptionActive, refetch]);\n\n  return {\n    daily,\n    dailyDate,\n    status,\n    isLoading,\n    error: error ?? (data?.error ? new Error(data.error) : null),\n    refetch: () => refetch(),\n  };\n}\n"]}
+{"version":3,"file":"useDailyGame.js","sourceRoot":"","sources":["../../src/hooks/useDailyGame.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAGnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,EAGL,kBAAkB,GACnB,MAAM,0BAA0B,CAAC;AA8BlC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,UAAU,YAAY,CAAC,OAA4B;IACvD,MAAM,EAAE,kBAAkB,GAAG,KAAK,EAAE,OAAO,EAAE,QAAQ,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IACzE,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,oBAAoB,CAC5D,OAAO,EACP,cAAc,CACf,CAAC;IAEF,yCAAyC;IACzC,MAAM,YAAY,GAAG,MAAM,CAAC;QAC1B,SAAS,EAAE,KAAK;QAChB,kBAAkB;KACnB,CAAC,CAAC;IAEH,yEAAyE;IACzE,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,gBAAgB,EAAE,EAAE,EAAE,CAAC,CAAC;IAExD,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,oBAAoB,CAC9D,aAAa,EACb,OAAO,EACP,KAAK,EACL,SAAS,CACV,CAAC;IAEF,qCAAqC;IACrC,MAAM,MAAM,GAAG,OAAO,CACpB,GAAoB,EAAE,CACpB,kBAAkB,CAAC;QACjB,SAAS;QACT,QAAQ,EAAE,IAAqC;QAC/C,KAAK;KACN,CAAC,EACJ,CAAC,SAAS,EAAE,IAAI,EAAE,KAAK,CAAC,CACzB,CAAC;IAEF,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,EAAE;QACzB,IAAI,IAAI,EAAE,OAAO,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YAC/B,OAAO,IAAI,CAAC,IAAI,CAAC;QACnB,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IAEX,8DAA8D;IAC9D,4EAA4E;IAC5E,MAAM,SAAS,GAAG,OAAO,CACvB,GAAkB,EAAE,CAAC,kBAAkB,CAAC,KAAK,EAAE,IAAI,CAAC,EACpD,CAAC,KAAK,CAAC,CACR,CAAC;IAEF,8DAA8D;IAC9D,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,IAAI,GAAG,YAAY,CAAC,OAAO,CAAC;QAClC,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,KAAK,KAAK,CAAC;QAC7C,MAAM,mBAAmB,GAAG,CAAC,IAAI,CAAC,kBAAkB,IAAI,kBAAkB,CAAC;QAE3E,IAAI,WAAW,IAAI,mBAAmB,EAAE,CAAC;YACvC,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,iCAAiC;QACjC,YAAY,CAAC,OAAO,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAClE,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,EAAE,OAAO,CAAC,CAAC,CAAC;IAEzC,OAAO;QACL,KAAK;QACL,SAAS;QACT,MAAM;QACN,SAAS;QACT,KAAK,EAAE,KAAK,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAC5D,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE;KACzB,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Hook for fetching and managing today's daily puzzle\n * Handles auth and subscription status with automatic refresh\n */\n\nimport { useEffect, useMemo, useRef } from 'react';\nimport type { Daily } from '@sudobility/sudojo_types';\nimport type { NetworkClient } from '@sudobility/types';\nimport { useResolvedSudojoApi } from '../context/SudojoApiContext';\nimport { useSudojoDailyByDate } from '@sudobility/sudojo_client';\nimport { getUtcDateString, normalizeDailyDate } from '../utils/date';\nimport {\n  type GameFetchResponse,\n  type GameFetchStatus,\n  getGameFetchStatus,\n} from '../utils/gameFetchStatus';\n\nexport interface UseDailyGameOptions {\n  /** Network client for API calls (default: SudojoApiProvider) */\n  networkClient?: NetworkClient | undefined;\n  /** Base URL for the Sudojo API (default: SudojoApiProvider) */\n  baseUrl?: string | undefined;\n  /** Access token for authentication */\n  token?: string | undefined;\n  /** Whether subscription is currently active */\n  subscriptionActive?: boolean;\n  /** Whether to enable the query */\n  enabled?: boolean;\n}\n\nexport interface UseDailyGameResult {\n  /** Today's daily puzzle */\n  daily: Daily | null;\n  /** The date string for this daily (YYYY-MM-DD) */\n  dailyDate: string | null;\n  /** Current status of the game fetch */\n  status: GameFetchStatus;\n  /** Whether data is loading */\n  isLoading: boolean;\n  /** Error if fetch failed */\n  error: Error | null;\n  /** Refetch the daily puzzle */\n  refetch: () => void;\n}\n\n/**\n * Hook for fetching today's daily puzzle\n *\n * Automatically refetches when auth token or subscription status changes.\n * Returns status indicating whether auth or subscription is required.\n *\n * \"Today\" is the **UTC** date (getUtcDateString), the same day the API's\n * `/dailies/today` serves, computed once per mount. (It used to be the local\n * date, which asked for tomorrow's or yesterday's daily near midnight.)\n * `dailyDate` is the daily's own `YYYY-MM-DD`, never timezone-shifted.\n *\n * @param options - Hook options\n * @returns Daily puzzle data and status\n *\n * @example\n * ```tsx\n * function DailyPage() {\n *   const { daily, dailyDate, status, refetch } = useDailyGame({\n *     networkClient,\n *     config,\n *     auth,\n *     subscriptionActive: subscription.isActive,\n *   });\n *\n *   if (status === 'loading') return <Loading />;\n *   if (status === 'auth_required') return <AuthRequired onLogin={openAuthModal} />;\n *   if (status === 'subscription_required') return <SubscriptionPaywall onSuccess={refetch} />;\n *   if (status === 'error') return <Error />;\n *\n *   return <SudokuGame puzzle={daily.board} solution={daily.solution} />;\n * }\n * ```\n */\nexport function useDailyGame(options: UseDailyGameOptions): UseDailyGameResult {\n  const { subscriptionActive = false, enabled: _enabled = true } = options;\n  const { networkClient, baseUrl, token } = useResolvedSudojoApi(\n    options,\n    'useDailyGame'\n  );\n\n  // Track previous state to detect changes\n  const prevStateRef = useRef({\n    authToken: token,\n    subscriptionActive,\n  });\n\n  // \"Today\" is the UTC date, the same day the API's /dailies/today serves.\n  const todayDate = useMemo(() => getUtcDateString(), []);\n\n  const { data, isLoading, error, refetch } = useSudojoDailyByDate(\n    networkClient,\n    baseUrl,\n    token,\n    todayDate\n  );\n\n  // Determine status based on response\n  const status = useMemo(\n    (): GameFetchStatus =>\n      getGameFetchStatus({\n        isLoading,\n        response: data as GameFetchResponse | undefined,\n        error,\n      }),\n    [isLoading, data, error]\n  );\n\n  const daily = useMemo(() => {\n    if (data?.success && data.data) {\n      return data.data;\n    }\n    return null;\n  }, [data]);\n\n  // The daily's calendar date as sent, without a timezone shift\n  // (`new Date('YYYY-MM-DD')` is UTC midnight, the previous day west of UTC).\n  const dailyDate = useMemo(\n    (): string | null => normalizeDailyDate(daily?.date),\n    [daily]\n  );\n\n  // Auto-refresh when auth token or subscription status changes\n  useEffect(() => {\n    const prev = prevStateRef.current;\n    const authChanged = prev.authToken !== token;\n    const subscriptionChanged = !prev.subscriptionActive && subscriptionActive;\n\n    if (authChanged || subscriptionChanged) {\n      refetch();\n    }\n\n    // Update ref for next comparison\n    prevStateRef.current = { authToken: token, subscriptionActive };\n  }, [token, subscriptionActive, refetch]);\n\n  return {\n    daily,\n    dailyDate,\n    status,\n    isLoading,\n    error: error ?? (data?.error ? new Error(data.error) : null),\n    refetch: () => refetch(),\n  };\n}\n"]}

package/dist/hooks/useDeleteAccount.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Hook for deleting the signed-in user's account: the rule (who may delete)
+ * and the delete-then-sign-out sequence. Confirmation dialogs and error
+ * alerts stay in the apps.
+ */
+import type { NetworkClient } from '@sudobility/types';
+import type { DeleteUserVariables } from '@sudobility/sudojo_client';
+import { type DeleteAccountBlocker, type DeleteAccountCheck } from '../utils/subscription';
+/** Provider tokens the API uses to revoke Sign in with Apple, etc. */
+export type DeleteAccountProviderTokens = DeleteUserVariables['providerTokens'];
+/** What deleteAccount did. */
+export type DeleteAccountOutcome = {
+    status: 'deleted';
+} | {
+    status: 'blocked';
+    reason: DeleteAccountBlocker;
+} | {
+    status: 'failed';
+    error: Error;
+};
+export interface UseDeleteAccountOptions {
+    /** Network client for API calls (default: SudojoApiProvider) */
+    networkClient?: NetworkClient | undefined;
+    /** Base URL for the Sudojo API (default: SudojoApiProvider) */
+    baseUrl?: string | undefined;
+    /** Access token (default: SudojoApiProvider) */
+    token?: string | null | undefined;
+    /** The signed-in user */
+    user: {
+        uid?: string | null;
+        isAnonymous?: boolean | null;
+    } | null | undefined;
+    /** Whether the user has an active subscription (must cancel first) */
+    subscriptionActive: boolean | null | undefined;
+    /**
+     * Sign out locally after the account is deleted (the API deletes the
+     * Firebase user; the client must still drop its session).
+     */
+    signOut?: () => void | Promise<void>;
+}
+export interface UseDeleteAccountResult {
+    /** Whether the account may be deleted now, and why not */
+    canDelete: DeleteAccountCheck;
+    /**
+     * Delete the account (after the app's confirmation), then sign out.
+     * Never throws: the outcome says whether it was blocked or failed.
+     */
+    deleteAccount: (providerTokens?: DeleteAccountProviderTokens) => Promise<DeleteAccountOutcome>;
+    /** True while the delete request (and sign-out) is in flight */
+    isDeleting: boolean;
+    /** The last failure, cleared on the next attempt */
+    error: Error | null;
+}
+/**
+ * @example
+ * ```tsx
+ * const { canDelete, deleteAccount, isDeleting } = useDeleteAccount({
+ *   user, subscriptionActive: subscription.isActive, signOut,
+ * });
+ * const onPress = async () => {
+ *   if (!canDelete.allowed) {
+ *     if (canDelete.reason === 'active_subscription') alert(t('auth.deleteAccountUnsubscribeFirst'));
+ *     return;
+ *   }
+ *   if (!confirm(t('auth.deleteAccountConfirm'))) return;
+ *   const outcome = await deleteAccount();
+ *   if (outcome.status === 'failed') alert(outcome.error.message);
+ * };
+ * ```
+ */
+export declare function useDeleteAccount(options: UseDeleteAccountOptions): UseDeleteAccountResult;
+//# sourceMappingURL=useDeleteAccount.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useDeleteAccount.d.ts","sourceRoot":"","sources":["../../src/hooks/useDeleteAccount.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAErE,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACxB,MAAM,uBAAuB,CAAC;AAE/B,sEAAsE;AACtE,MAAM,MAAM,2BAA2B,GAAG,mBAAmB,CAAC,gBAAgB,CAAC,CAAC;AAEhF,8BAA8B;AAC9B,MAAM,MAAM,oBAAoB,GAC5B;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,GACrB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,oBAAoB,CAAA;CAAE,GACnD;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AAEvC,MAAM,WAAW,uBAAuB;IACtC,gEAAgE;IAChE,aAAa,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAC1C,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAClC,yBAAyB;IACzB,IAAI,EACA;QAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,WAAW,CAAC,EAAE,OAAO,GAAG,IAAI,CAAA;KAAE,GACrD,IAAI,GACJ,SAAS,CAAC;IACd,sEAAsE;IACtE,kBAAkB,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC;IAC/C;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,sBAAsB;IACrC,0DAA0D;IAC1D,SAAS,EAAE,kBAAkB,CAAC;IAC9B;;;OAGG;IACH,aAAa,EAAE,CACb,cAAc,CAAC,EAAE,2BAA2B,KACzC,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACnC,gEAAgE;IAChE,UAAU,EAAE,OAAO,CAAC;IACpB,oDAAoD;IACpD,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,uBAAuB,GAC/B,sBAAsB,CAuDxB"}

package/dist/hooks/useDeleteAccount.js

@@ -0,0 +1,71 @@
+/**
+ * Hook for deleting the signed-in user's account: the rule (who may delete)
+ * and the delete-then-sign-out sequence. Confirmation dialogs and error
+ * alerts stay in the apps.
+ */
+import { useCallback, useMemo, useState } from 'react';
+import { useSudojoDeleteUser } from '@sudobility/sudojo_client';
+import { useResolvedSudojoApi } from '../context/SudojoApiContext';
+import { canDeleteAccount, } from '../utils/subscription';
+/**
+ * @example
+ * ```tsx
+ * const { canDelete, deleteAccount, isDeleting } = useDeleteAccount({
+ *   user, subscriptionActive: subscription.isActive, signOut,
+ * });
+ * const onPress = async () => {
+ *   if (!canDelete.allowed) {
+ *     if (canDelete.reason === 'active_subscription') alert(t('auth.deleteAccountUnsubscribeFirst'));
+ *     return;
+ *   }
+ *   if (!confirm(t('auth.deleteAccountConfirm'))) return;
+ *   const outcome = await deleteAccount();
+ *   if (outcome.status === 'failed') alert(outcome.error.message);
+ * };
+ * ```
+ */
+export function useDeleteAccount(options) {
+    const { user, subscriptionActive, signOut } = options;
+    const { networkClient, baseUrl, token } = useResolvedSudojoApi(options, 'useDeleteAccount');
+    const { mutateAsync } = useSudojoDeleteUser(networkClient, baseUrl);
+    const [isDeleting, setIsDeleting] = useState(false);
+    const [error, setError] = useState(null);
+    const canDelete = useMemo(() => canDeleteAccount({ user, subscriptionActive }), [user, subscriptionActive]);
+    const deleteAccount = useCallback(async (providerTokens) => {
+        if (!canDelete.allowed) {
+            return { status: 'blocked', reason: canDelete.reason };
+        }
+        const userId = user?.uid ?? '';
+        setIsDeleting(true);
+        setError(null);
+        try {
+            await mutateAsync({
+                token,
+                userId,
+                ...(providerTokens !== undefined && { providerTokens }),
+            });
+        }
+        catch (err) {
+            const failure = err instanceof Error
+                ? err
+                : new Error(String(err) || 'Failed to delete account');
+            setError(failure);
+            setIsDeleting(false);
+            return { status: 'failed', error: failure };
+        }
+        try {
+            // The account is gone either way; a failed local sign-out does not
+            // make the deletion a failure.
+            await signOut?.();
+        }
+        catch (err) {
+            console.error('[useDeleteAccount] signOut failed:', err);
+        }
+        finally {
+            setIsDeleting(false);
+        }
+        return { status: 'deleted' };
+    }, [canDelete, user, mutateAsync, token, signOut]);
+    return { canDelete, deleteAccount, isDeleting, error };
+}
+//# sourceMappingURL=useDeleteAccount.js.map

package/dist/hooks/useDeleteAccount.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDeleteAccount.js","sourceRoot":"","sources":["../../src/hooks/useDeleteAccount.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAEhE,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EACL,gBAAgB,GAGjB,MAAM,uBAAuB,CAAC;AAgD/B;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAgC;IAEhC,MAAM,EAAE,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IACtD,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,oBAAoB,CAC5D,OAAO,EACP,kBAAkB,CACnB,CAAC;IACF,MAAM,EAAE,WAAW,EAAE,GAAG,mBAAmB,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;IACpE,MAAM,CAAC,UAAU,EAAE,aAAa,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IACpD,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAe,IAAI,CAAC,CAAC;IAEvD,MAAM,SAAS,GAAG,OAAO,CACvB,GAAG,EAAE,CAAC,gBAAgB,CAAC,EAAE,IAAI,EAAE,kBAAkB,EAAE,CAAC,EACpD,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAC3B,CAAC;IAEF,MAAM,aAAa,GAAG,WAAW,CAC/B,KAAK,EACH,cAA4C,EACb,EAAE;QACjC,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;YACvB,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,CAAC;QACzD,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,EAAE,GAAG,IAAI,EAAE,CAAC;QAC/B,aAAa,CAAC,IAAI,CAAC,CAAC;QACpB,QAAQ,CAAC,IAAI,CAAC,CAAC;QACf,IAAI,CAAC;YACH,MAAM,WAAW,CAAC;gBAChB,KAAK;gBACL,MAAM;gBACN,GAAG,CAAC,cAAc,KAAK,SAAS,IAAI,EAAE,cAAc,EAAE,CAAC;aACxD,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,OAAO,GACX,GAAG,YAAY,KAAK;gBAClB,CAAC,CAAC,GAAG;gBACL,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,0BAA0B,CAAC,CAAC;YAC3D,QAAQ,CAAC,OAAO,CAAC,CAAC;YAClB,aAAa,CAAC,KAAK,CAAC,CAAC;YACrB,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;QAC9C,CAAC;QACD,IAAI,CAAC;YACH,mEAAmE;YACnE,+BAA+B;YAC/B,MAAM,OAAO,EAAE,EAAE,CAAC;QACpB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,oCAAoC,EAAE,GAAG,CAAC,CAAC;QAC3D,CAAC;gBAAS,CAAC;YACT,aAAa,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAC/B,CAAC,EACD,CAAC,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,CAAC,CAC/C,CAAC;IAEF,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;AACzD,CAAC","sourcesContent":["/**\n * Hook for deleting the signed-in user's account: the rule (who may delete)\n * and the delete-then-sign-out sequence. Confirmation dialogs and error\n * alerts stay in the apps.\n */\n\nimport { useCallback, useMemo, useState } from 'react';\nimport type { NetworkClient } from '@sudobility/types';\nimport { useSudojoDeleteUser } from '@sudobility/sudojo_client';\nimport type { DeleteUserVariables } from '@sudobility/sudojo_client';\nimport { useResolvedSudojoApi } from '../context/SudojoApiContext';\nimport {\n  canDeleteAccount,\n  type DeleteAccountBlocker,\n  type DeleteAccountCheck,\n} from '../utils/subscription';\n\n/** Provider tokens the API uses to revoke Sign in with Apple, etc. */\nexport type DeleteAccountProviderTokens = DeleteUserVariables['providerTokens'];\n\n/** What deleteAccount did. */\nexport type DeleteAccountOutcome =\n  | { status: 'deleted' }\n  | { status: 'blocked'; reason: DeleteAccountBlocker }\n  | { status: 'failed'; error: Error };\n\nexport interface UseDeleteAccountOptions {\n  /** Network client for API calls (default: SudojoApiProvider) */\n  networkClient?: NetworkClient | undefined;\n  /** Base URL for the Sudojo API (default: SudojoApiProvider) */\n  baseUrl?: string | undefined;\n  /** Access token (default: SudojoApiProvider) */\n  token?: string | null | undefined;\n  /** The signed-in user */\n  user:\n    | { uid?: string | null; isAnonymous?: boolean | null }\n    | null\n    | undefined;\n  /** Whether the user has an active subscription (must cancel first) */\n  subscriptionActive: boolean | null | undefined;\n  /**\n   * Sign out locally after the account is deleted (the API deletes the\n   * Firebase user; the client must still drop its session).\n   */\n  signOut?: () => void | Promise<void>;\n}\n\nexport interface UseDeleteAccountResult {\n  /** Whether the account may be deleted now, and why not */\n  canDelete: DeleteAccountCheck;\n  /**\n   * Delete the account (after the app's confirmation), then sign out.\n   * Never throws: the outcome says whether it was blocked or failed.\n   */\n  deleteAccount: (\n    providerTokens?: DeleteAccountProviderTokens\n  ) => Promise<DeleteAccountOutcome>;\n  /** True while the delete request (and sign-out) is in flight */\n  isDeleting: boolean;\n  /** The last failure, cleared on the next attempt */\n  error: Error | null;\n}\n\n/**\n * @example\n * ```tsx\n * const { canDelete, deleteAccount, isDeleting } = useDeleteAccount({\n *   user, subscriptionActive: subscription.isActive, signOut,\n * });\n * const onPress = async () => {\n *   if (!canDelete.allowed) {\n *     if (canDelete.reason === 'active_subscription') alert(t('auth.deleteAccountUnsubscribeFirst'));\n *     return;\n *   }\n *   if (!confirm(t('auth.deleteAccountConfirm'))) return;\n *   const outcome = await deleteAccount();\n *   if (outcome.status === 'failed') alert(outcome.error.message);\n * };\n * ```\n */\nexport function useDeleteAccount(\n  options: UseDeleteAccountOptions\n): UseDeleteAccountResult {\n  const { user, subscriptionActive, signOut } = options;\n  const { networkClient, baseUrl, token } = useResolvedSudojoApi(\n    options,\n    'useDeleteAccount'\n  );\n  const { mutateAsync } = useSudojoDeleteUser(networkClient, baseUrl);\n  const [isDeleting, setIsDeleting] = useState(false);\n  const [error, setError] = useState<Error | null>(null);\n\n  const canDelete = useMemo(\n    () => canDeleteAccount({ user, subscriptionActive }),\n    [user, subscriptionActive]\n  );\n\n  const deleteAccount = useCallback(\n    async (\n      providerTokens?: DeleteAccountProviderTokens\n    ): Promise<DeleteAccountOutcome> => {\n      if (!canDelete.allowed) {\n        return { status: 'blocked', reason: canDelete.reason };\n      }\n      const userId = user?.uid ?? '';\n      setIsDeleting(true);\n      setError(null);\n      try {\n        await mutateAsync({\n          token,\n          userId,\n          ...(providerTokens !== undefined && { providerTokens }),\n        });\n      } catch (err) {\n        const failure =\n          err instanceof Error\n            ? err\n            : new Error(String(err) || 'Failed to delete account');\n        setError(failure);\n        setIsDeleting(false);\n        return { status: 'failed', error: failure };\n      }\n      try {\n        // The account is gone either way; a failed local sign-out does not\n        // make the deletion a failure.\n        await signOut?.();\n      } catch (err) {\n        console.error('[useDeleteAccount] signOut failed:', err);\n      } finally {\n        setIsDeleting(false);\n      }\n      return { status: 'deleted' };\n    },\n    [canDelete, user, mutateAsync, token, signOut]\n  );\n\n  return { canDelete, deleteAccount, isDeleting, error };\n}\n"]}

package/dist/hooks/useEnteredGameSession.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Save / resume orchestration for an entered (typed-in or scanned) puzzle,
+ * after useBoardEntry validated it. Port of the web EnterBoard's play-mode
+ * logic. Entered puzzles get no server session (no gamification), and their
+ * completion is not recorded in progress.
+ */
+import type { BoardEntryPlayState, ValidatedPuzzle } from './useBoardEntry';
+import type { PuzzleGameProps } from './usePuzzleSession';
+import { type UseResumeGameResult } from './useResumeGame';
+export interface UseEnteredGameSessionOptions {
+    /** useBoardEntry's validatedPuzzle (null until Validate succeeds) */
+    validatedPuzzle: ValidatedPuzzle | null | undefined;
+    /** useBoardEntry's initialPlayState (scanned input / entry pencilmarks) */
+    initialPlayState?: BoardEntryPlayState | undefined;
+    /** The resume decision (default: useResumeGame({ source: 'entered' })) */
+    resume?: UseResumeGameResult | undefined;
+    /** Forwarded to the internal useResumeGame (RN: its onStoreReady state) */
+    isStoreHydrated?: boolean | undefined;
+    /**
+     * Called by newGame() to reset the entry board (pass useBoardEntry's
+     * `reset`), so the old validatedPuzzle does not start play again.
+     */
+    onReset?: () => void;
+}
+export interface UseEnteredGameSessionResult {
+    /** Whether the resume decision is made (store hydrated) */
+    isReady: boolean;
+    /** Whether a saved entered game is being resumed */
+    isResuming: boolean;
+    /** The puzzle to play (resumed, else validated), or null while entering */
+    activePuzzle: ValidatedPuzzle | null;
+    /** Whether to show the game (there is an active puzzle) instead of entry */
+    isPlaying: boolean;
+    /**
+     * Props for the game component, or null while entering. Always
+     * `scramble: false`. Initial state comes from the saved game when resuming,
+     * else from initialPlayState.
+     */
+    gameProps: PuzzleGameProps | null;
+    /** Remount key for the game component (the puzzle string), or null */
+    gameKey: string | null;
+    /** Web SudokuGame's onScrambledReady: saves the game once per puzzle */
+    onScrambledReady: (board: {
+        puzzle: string;
+        solution: string;
+    }) => void;
+    /** RN SudokuGame's onBoardReady: same as onScrambledReady */
+    onBoardReady: (puzzle: string, solution: string) => void;
+    /** The game's onProgressUpdate (throttled save) */
+    onProgress: (inputString: string, pencilmarksString: string, isPencilMode: boolean, autoPencilmarks: boolean, elapsedTime: number) => void;
+    /** The game's onComplete: clears the saved game (nothing else) */
+    onComplete: () => void;
+    /** Back to entry: clear the save, stop resuming, call onReset */
+    newGame: () => void;
+}
+/**
+ * @example
+ * ```tsx
+ * const entry = useBoardEntry();
+ * const session = useEnteredGameSession({
+ *   validatedPuzzle: entry.validatedPuzzle,
+ *   initialPlayState: entry.initialPlayState,
+ *   onReset: entry.reset,
+ * });
+ * if (session.isPlaying) {
+ *   return <SudokuGame key={session.gameKey} {...session.gameProps}
+ *     onScrambledReady={session.onScrambledReady} onProgressUpdate={session.onProgress}
+ *     onComplete={session.onComplete} onNewGame={session.newGame} />;
+ * }
+ * ```
+ */
+export declare function useEnteredGameSession(options: UseEnteredGameSessionOptions): UseEnteredGameSessionResult;
+//# sourceMappingURL=useEnteredGameSession.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useEnteredGameSession.d.ts","sourceRoot":"","sources":["../../src/hooks/useEnteredGameSession.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAE5E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAiB,KAAK,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAE1E,MAAM,WAAW,4BAA4B;IAC3C,qEAAqE;IACrE,eAAe,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,CAAC;IACpD,2EAA2E;IAC3E,gBAAgB,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;IACnD,0EAA0E;IAC1E,MAAM,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;IACzC,2EAA2E;IAC3E,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACtC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,2BAA2B;IAC1C,2DAA2D;IAC3D,OAAO,EAAE,OAAO,CAAC;IACjB,oDAAoD;IACpD,UAAU,EAAE,OAAO,CAAC;IACpB,2EAA2E;IAC3E,YAAY,EAAE,eAAe,GAAG,IAAI,CAAC;IACrC,4EAA4E;IAC5E,SAAS,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,SAAS,EAAE,eAAe,GAAG,IAAI,CAAC;IAClC,sEAAsE;IACtE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,wEAAwE;IACxE,gBAAgB,EAAE,CAAC,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACxE,6DAA6D;IAC7D,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACzD,mDAAmD;IACnD,UAAU,EAAE,CACV,WAAW,EAAE,MAAM,EACnB,iBAAiB,EAAE,MAAM,EACzB,YAAY,EAAE,OAAO,EACrB,eAAe,EAAE,OAAO,EACxB,WAAW,EAAE,MAAM,KAChB,IAAI,CAAC;IACV,kEAAkE;IAClE,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,iEAAiE;IACjE,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,4BAA4B,GACpC,2BAA2B,CAsJ7B"}

package/dist/hooks/useEnteredGameSession.js

@@ -0,0 +1,155 @@
+/**
+ * Save / resume orchestration for an entered (typed-in or scanned) puzzle,
+ * after useBoardEntry validated it. Port of the web EnterBoard's play-mode
+ * logic. Entered puzzles get no server session (no gamification), and their
+ * completion is not recorded in progress.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useGamePlay } from './useGamePlay';
+import { useResumeGame } from './useResumeGame';
+/**
+ * @example
+ * ```tsx
+ * const entry = useBoardEntry();
+ * const session = useEnteredGameSession({
+ *   validatedPuzzle: entry.validatedPuzzle,
+ *   initialPlayState: entry.initialPlayState,
+ *   onReset: entry.reset,
+ * });
+ * if (session.isPlaying) {
+ *   return <SudokuGame key={session.gameKey} {...session.gameProps}
+ *     onScrambledReady={session.onScrambledReady} onProgressUpdate={session.onProgress}
+ *     onComplete={session.onComplete} onNewGame={session.newGame} />;
+ * }
+ * ```
+ */
+export function useEnteredGameSession(options) {
+    const { validatedPuzzle, initialPlayState, onReset } = options;
+    const internalResume = useResumeGame({
+        source: 'entered',
+        slot: 'play',
+        ...(options.isStoreHydrated !== undefined && {
+            isStoreHydrated: options.isStoreHydrated,
+        }),
+    });
+    const resume = options.resume ?? internalResume;
+    const resumeGame = resume.resumeGame;
+    const isResuming = resumeGame !== null;
+    const { startGame, updateProgress, clearGame } = useGamePlay({
+        slot: 'play',
+    });
+    const resumedPuzzle = useMemo(() => {
+        if (!resumeGame)
+            return null;
+        // Level and score were saved with the game, since resuming does not
+        // validate again.
+        const puzzle = {
+            puzzle: resumeGame.puzzle,
+            solution: resumeGame.solution,
+        };
+        if (resumeGame.meta.level !== undefined) {
+            puzzle.level = resumeGame.meta.level;
+        }
+        if (resumeGame.meta.difficultyScore !== undefined) {
+            puzzle.difficultyScore = resumeGame.meta.difficultyScore;
+        }
+        return puzzle;
+    }, [resumeGame]);
+    const activePuzzle = resumedPuzzle ?? validatedPuzzle ?? null;
+    const gameKey = activePuzzle?.puzzle ?? null;
+    // --- Save the fresh game once the game reports its board -----------------
+    const [reported, setReported] = useState(null);
+    const onScrambledReady = useCallback((board) => {
+        if (!gameKey)
+            return;
+        if (board.puzzle.length !== 81 || board.solution.length !== 81)
+            return;
+        setReported(prev => prev?.key === gameKey &&
+            prev.puzzle === board.puzzle &&
+            prev.solution === board.solution
+            ? prev
+            : { key: gameKey, ...board });
+    }, [gameKey]);
+    const onBoardReady = useCallback((puzzle, solution) => {
+        onScrambledReady({ puzzle, solution });
+    }, [onScrambledReady]);
+    const startedRef = useRef('');
+    const pencilmarks = initialPlayState?.pencilmarks;
+    const autopencil = initialPlayState?.autopencil ?? false;
+    useEffect(() => {
+        if (isResuming || !activePuzzle || !reported)
+            return;
+        if (reported.key !== gameKey || startedRef.current === gameKey)
+            return;
+        startedRef.current = gameKey;
+        const meta = {};
+        if (activePuzzle.level !== undefined)
+            meta.level = activePuzzle.level;
+        if (activePuzzle.difficultyScore !== undefined) {
+            meta.difficultyScore = activePuzzle.difficultyScore;
+        }
+        startGame('entered', {
+            original: reported.puzzle,
+            user: reported.puzzle,
+            pencilmark: pencilmarks
+                ? { numbers: pencilmarks, autopencil }
+                : { numbers: '', autopencil: false },
+        }, reported.solution, meta);
+    }, [
+        isResuming,
+        activePuzzle,
+        reported,
+        gameKey,
+        pencilmarks,
+        autopencil,
+        startGame,
+    ]);
+    const discardResume = resume.discard;
+    const onComplete = useCallback(() => {
+        clearGame();
+    }, [clearGame]);
+    const newGame = useCallback(() => {
+        clearGame();
+        discardResume();
+        setReported(null);
+        startedRef.current = '';
+        onReset?.();
+    }, [clearGame, discardResume, onReset]);
+    const gameProps = useMemo(() => {
+        if (!activePuzzle)
+            return null;
+        if (resumeGame) {
+            return {
+                puzzle: activePuzzle.puzzle,
+                solution: activePuzzle.solution,
+                scramble: false,
+                initialInput: resumeGame.inputString,
+                initialPencilmarks: resumeGame.pencilmarksString,
+                initialElapsedTime: resumeGame.elapsedTime,
+                initialAutoPencilmarks: resumeGame.autoPencilmarks,
+            };
+        }
+        return {
+            puzzle: activePuzzle.puzzle,
+            solution: activePuzzle.solution,
+            scramble: false,
+            initialInput: initialPlayState?.input,
+            initialPencilmarks: initialPlayState?.pencilmarks,
+            initialAutoPencilmarks: initialPlayState?.autopencil,
+        };
+    }, [activePuzzle, resumeGame, initialPlayState]);
+    return {
+        isReady: resume.isReady,
+        isResuming,
+        activePuzzle,
+        isPlaying: activePuzzle !== null,
+        gameProps,
+        gameKey,
+        onScrambledReady,
+        onBoardReady,
+        onProgress: updateProgress,
+        onComplete,
+        newGame,
+    };
+}
+//# sourceMappingURL=useEnteredGameSession.js.map

package/dist/hooks/useEnteredGameSession.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useEnteredGameSession.js","sourceRoot":"","sources":["../../src/hooks/useEnteredGameSession.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Save / resume orchestration for an entered (typed-in or scanned) puzzle,\n * after useBoardEntry validated it. Port of the web EnterBoard's play-mode\n * logic. Entered puzzles get no server session (no gamification), and their\n * completion is not recorded in progress.\n */\n\nimport { useCallback, useEffect, useMemo, useRef, useState } from 'react';\nimport type { CurrentGameMeta } from '../types/currentGame';\nimport type { BoardEntryPlayState, ValidatedPuzzle } from './useBoardEntry';\nimport { useGamePlay } from './useGamePlay';\nimport type { PuzzleGameProps } from './usePuzzleSession';\nimport { useResumeGame, type UseResumeGameResult } from './useResumeGame';\n\nexport interface UseEnteredGameSessionOptions {\n  /** useBoardEntry's validatedPuzzle (null until Validate succeeds) */\n  validatedPuzzle: ValidatedPuzzle | null | undefined;\n  /** useBoardEntry's initialPlayState (scanned input / entry pencilmarks) */\n  initialPlayState?: BoardEntryPlayState | undefined;\n  /** The resume decision (default: useResumeGame({ source: 'entered' })) */\n  resume?: UseResumeGameResult | undefined;\n  /** Forwarded to the internal useResumeGame (RN: its onStoreReady state) */\n  isStoreHydrated?: boolean | undefined;\n  /**\n   * Called by newGame() to reset the entry board (pass useBoardEntry's\n   * `reset`), so the old validatedPuzzle does not start play again.\n   */\n  onReset?: () => void;\n}\n\nexport interface UseEnteredGameSessionResult {\n  /** Whether the resume decision is made (store hydrated) */\n  isReady: boolean;\n  /** Whether a saved entered game is being resumed */\n  isResuming: boolean;\n  /** The puzzle to play (resumed, else validated), or null while entering */\n  activePuzzle: ValidatedPuzzle | null;\n  /** Whether to show the game (there is an active puzzle) instead of entry */\n  isPlaying: boolean;\n  /**\n   * Props for the game component, or null while entering. Always\n   * `scramble: false`. Initial state comes from the saved game when resuming,\n   * else from initialPlayState.\n   */\n  gameProps: PuzzleGameProps | null;\n  /** Remount key for the game component (the puzzle string), or null */\n  gameKey: string | null;\n  /** Web SudokuGame's onScrambledReady: saves the game once per puzzle */\n  onScrambledReady: (board: { puzzle: string; solution: string }) => void;\n  /** RN SudokuGame's onBoardReady: same as onScrambledReady */\n  onBoardReady: (puzzle: string, solution: string) => void;\n  /** The game's onProgressUpdate (throttled save) */\n  onProgress: (\n    inputString: string,\n    pencilmarksString: string,\n    isPencilMode: boolean,\n    autoPencilmarks: boolean,\n    elapsedTime: number\n  ) => void;\n  /** The game's onComplete: clears the saved game (nothing else) */\n  onComplete: () => void;\n  /** Back to entry: clear the save, stop resuming, call onReset */\n  newGame: () => void;\n}\n\n/**\n * @example\n * ```tsx\n * const entry = useBoardEntry();\n * const session = useEnteredGameSession({\n *   validatedPuzzle: entry.validatedPuzzle,\n *   initialPlayState: entry.initialPlayState,\n *   onReset: entry.reset,\n * });\n * if (session.isPlaying) {\n *   return <SudokuGame key={session.gameKey} {...session.gameProps}\n *     onScrambledReady={session.onScrambledReady} onProgressUpdate={session.onProgress}\n *     onComplete={session.onComplete} onNewGame={session.newGame} />;\n * }\n * ```\n */\nexport function useEnteredGameSession(\n  options: UseEnteredGameSessionOptions\n): UseEnteredGameSessionResult {\n  const { validatedPuzzle, initialPlayState, onReset } = options;\n\n  const internalResume = useResumeGame({\n    source: 'entered',\n    slot: 'play',\n    ...(options.isStoreHydrated !== undefined && {\n      isStoreHydrated: options.isStoreHydrated,\n    }),\n  });\n  const resume = options.resume ?? internalResume;\n  const resumeGame = resume.resumeGame;\n  const isResuming = resumeGame !== null;\n\n  const { startGame, updateProgress, clearGame } = useGamePlay({\n    slot: 'play',\n  });\n\n  const resumedPuzzle = useMemo((): ValidatedPuzzle | null => {\n    if (!resumeGame) return null;\n    // Level and score were saved with the game, since resuming does not\n    // validate again.\n    const puzzle: ValidatedPuzzle = {\n      puzzle: resumeGame.puzzle,\n      solution: resumeGame.solution,\n    };\n    if (resumeGame.meta.level !== undefined) {\n      puzzle.level = resumeGame.meta.level;\n    }\n    if (resumeGame.meta.difficultyScore !== undefined) {\n      puzzle.difficultyScore = resumeGame.meta.difficultyScore;\n    }\n    return puzzle;\n  }, [resumeGame]);\n\n  const activePuzzle = resumedPuzzle ?? validatedPuzzle ?? null;\n  const gameKey = activePuzzle?.puzzle ?? null;\n\n  // --- Save the fresh game once the game reports its board -----------------\n  const [reported, setReported] = useState<{\n    key: string;\n    puzzle: string;\n    solution: string;\n  } | null>(null);\n\n  const onScrambledReady = useCallback(\n    (board: { puzzle: string; solution: string }) => {\n      if (!gameKey) return;\n      if (board.puzzle.length !== 81 || board.solution.length !== 81) return;\n      setReported(prev =>\n        prev?.key === gameKey &&\n        prev.puzzle === board.puzzle &&\n        prev.solution === board.solution\n          ? prev\n          : { key: gameKey, ...board }\n      );\n    },\n    [gameKey]\n  );\n\n  const onBoardReady = useCallback(\n    (puzzle: string, solution: string) => {\n      onScrambledReady({ puzzle, solution });\n    },\n    [onScrambledReady]\n  );\n\n  const startedRef = useRef('');\n  const pencilmarks = initialPlayState?.pencilmarks;\n  const autopencil = initialPlayState?.autopencil ?? false;\n  useEffect(() => {\n    if (isResuming || !activePuzzle || !reported) return;\n    if (reported.key !== gameKey || startedRef.current === gameKey) return;\n    startedRef.current = gameKey;\n    const meta: CurrentGameMeta = {};\n    if (activePuzzle.level !== undefined) meta.level = activePuzzle.level;\n    if (activePuzzle.difficultyScore !== undefined) {\n      meta.difficultyScore = activePuzzle.difficultyScore;\n    }\n    startGame(\n      'entered',\n      {\n        original: reported.puzzle,\n        user: reported.puzzle,\n        pencilmark: pencilmarks\n          ? { numbers: pencilmarks, autopencil }\n          : { numbers: '', autopencil: false },\n      },\n      reported.solution,\n      meta\n    );\n  }, [\n    isResuming,\n    activePuzzle,\n    reported,\n    gameKey,\n    pencilmarks,\n    autopencil,\n    startGame,\n  ]);\n\n  const discardResume = resume.discard;\n  const onComplete = useCallback(() => {\n    clearGame();\n  }, [clearGame]);\n\n  const newGame = useCallback(() => {\n    clearGame();\n    discardResume();\n    setReported(null);\n    startedRef.current = '';\n    onReset?.();\n  }, [clearGame, discardResume, onReset]);\n\n  const gameProps = useMemo((): PuzzleGameProps | null => {\n    if (!activePuzzle) return null;\n    if (resumeGame) {\n      return {\n        puzzle: activePuzzle.puzzle,\n        solution: activePuzzle.solution,\n        scramble: false,\n        initialInput: resumeGame.inputString,\n        initialPencilmarks: resumeGame.pencilmarksString,\n        initialElapsedTime: resumeGame.elapsedTime,\n        initialAutoPencilmarks: resumeGame.autoPencilmarks,\n      };\n    }\n    return {\n      puzzle: activePuzzle.puzzle,\n      solution: activePuzzle.solution,\n      scramble: false,\n      initialInput: initialPlayState?.input,\n      initialPencilmarks: initialPlayState?.pencilmarks,\n      initialAutoPencilmarks: initialPlayState?.autopencil,\n    };\n  }, [activePuzzle, resumeGame, initialPlayState]);\n\n  return {\n    isReady: resume.isReady,\n    isResuming,\n    activePuzzle,\n    isPlaying: activePuzzle !== null,\n    gameProps,\n    gameKey,\n    onScrambledReady,\n    onBoardReady,\n    onProgress: updateProgress,\n    onComplete,\n    newGame,\n  };\n}\n"]}

package/dist/hooks/useGameSession.d.ts

@@ -9,9 +9,13 @@
 import type { GameFinishResponse, GameStartRequest, LocalizedHint } from '@sudobility/sudojo_types';
 import type { NetworkClient } from '@sudobility/types';
 export interface UseGameSessionOptions {
-    networkClient: NetworkClient;
-    baseUrl: string;
-    token: string | null;
+    /** Network client for API calls (default: SudojoApiProvider) */
+    networkClient?: NetworkClient | undefined;
+    /** Base URL for the Sudojo API (default: SudojoApiProvider) */
+    baseUrl?: string | undefined;
+    /** Access token; null = signed out (default: SudojoApiProvider) */
+    token?: string | null | undefined;
+    /** Signed-in (non-anonymous) user id, or null */
     userId: string | null;
 }
 export interface GameSessionResult {
@@ -38,7 +42,7 @@ export interface GameFinishResult {
     /** Total points earned */
     totalPointsEarned: number;
 }
-export declare function useGameSession({ networkClient, baseUrl, token, userId, }: UseGameSessionOptions): {
+export declare function useGameSession(options: UseGameSessionOptions): {
     startSession: (data: GameStartRequest) => Promise<GameSessionResult>;
     finishSession: (elapsedTime: number) => Promise<GameFinishResult>;
     isStarting: boolean;

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

@@ -1 +1 @@
-{"version":3,"file":"useGameSession.d.ts","sourceRoot":"","sources":["../../src/hooks/useGameSession.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,OAAO,KAAK,EACV,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACd,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,MAAM,WAAW,qBAAqB;IACpC,aAAa,EAAE,aAAa,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,cAAc,EAAE,OAAO,CAAC;IACxB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,wCAAwC;IACxC,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,kCAAkC;IAClC,SAAS,EAAE,OAAO,CAAC;IACnB,wBAAwB;IACxB,SAAS,EAAE,KAAK,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,YAAY,CAAC,EAAE;YACb,KAAK,CAAC,EAAE,aAAa,CAAC;YACtB,WAAW,CAAC,EAAE,aAAa,CAAC;SAC7B,CAAC;KACH,CAAC,CAAC;IACH,0BAA0B;IAC1B,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAgB,cAAc,CAAC,EAC7B,aAAa,EACb,OAAO,EACP,KAAK,EACL,MAAM,GACP,EAAE,qBAAqB;yBAyBP,gBAAgB,KAAG,OAAO,CAAC,iBAAiB,CAAC;iCAsCtC,MAAM,KAAG,OAAO,CAAC,gBAAgB,CAAC;;;;;EA4DzD"}
+{"version":3,"file":"useGameSession.d.ts","sourceRoot":"","sources":["../../src/hooks/useGameSession.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,OAAO,KAAK,EACV,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACd,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGvD,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,aAAa,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAC1C,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAClC,iDAAiD;IACjD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,cAAc,EAAE,OAAO,CAAC;IACxB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,wCAAwC;IACxC,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,kCAAkC;IAClC,SAAS,EAAE,OAAO,CAAC;IACnB,wBAAwB;IACxB,SAAS,EAAE,KAAK,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,YAAY,CAAC,EAAE;YACb,KAAK,CAAC,EAAE,aAAa,CAAC;YACtB,WAAW,CAAC,EAAE,aAAa,CAAC;SAC7B,CAAC;KACH,CAAC,CAAC;IACH,0BAA0B;IAC1B,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,qBAAqB;yBA8B5C,gBAAgB,KAAG,OAAO,CAAC,iBAAiB,CAAC;iCAsCtC,MAAM,KAAG,OAAO,CAAC,gBAAgB,CAAC;;;;;EA4DzD"}

package/dist/hooks/useGameSession.js

@@ -8,7 +8,10 @@
  */
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { useSudojoPlayFinish, useSudojoPlayStart, } from '@sudobility/sudojo_client';
-export function useGameSession({ networkClient, baseUrl, token, userId, }) {
+import { useResolvedSudojoApi } from '../context/SudojoApiContext';
+export function useGameSession(options) {
+    const { userId } = options;
+    const { networkClient, baseUrl, token } = useResolvedSudojoApi(options, 'useGameSession');
     const [isStarting, setIsStarting] = useState(false);
     const [isFinishing, setIsFinishing] = useState(false);
     const sessionIdRef = useRef(null);