@sudobility/sudojo_lib 0.0.201 → 0.0.204

package/dist/index.js

@@ -26,6 +26,7 @@
  * - `useSudoku` - Primary game state (flat 81-cell array, modern API)
  * - `useGame` - Legacy game state (2D array, deprecated)
  * - `useBoardEntry` - Manual puzzle entry mode
+ * - `useBoardScan` - Read givens, player digits and pencilmarks from a photo
  *
  * **Feature hooks** (provide specific game features):
  * - `useHint` - Solver integration for hints (matches Kotlin HintInteractor)
@@ -167,7 +168,23 @@ cellsToStateString,
 /** Convert SudokuCell array to input-only string. */
 cellsToInputString, 
 /** Convert SudokuCell array to comma-separated pencilmarks string. */
-cellsToPencilmarksString, } from './utils';
+cellsToPencilmarksString, 
+/** Convert SudokuCell array to solution string ('0' where unknown). */
+cellsToSolutionString, 
+/** Count the givens (clues) in a SudokuCell array. */
+countClues, } from './utils';
+/** Board and level constants from sudojo_types, re-exported for convenience. */
+export { 
+/** Fewest givens a valid Sudoku can have (17). */
+MIN_CLUES, 
+/** Lowest difficulty level (1). */
+MIN_LEVEL, 
+/** Highest difficulty level (12). */
+MAX_LEVEL, 
+/** Whether a value is an integer level in MIN_LEVEL..MAX_LEVEL. */
+isValidLevel, 
+/** All levels, MIN_LEVEL..MAX_LEVEL. */
+ALL_LEVELS, } from '@sudobility/sudojo_types';
 /** Board presentation and color utilities matching the Kotlin renderable layer. */
 export { 
 /** Generate display states for all 81 cells (colors, digits, pencilmarks, hints). */
@@ -189,7 +206,15 @@ convertSolverLink,
 /** Convert a solver cell group to display format with ThemeColor. */
 convertSolverCellGroup, 
 /** Convert SudokuColor enum to ThemeColor enum. */
-sudokuColorToTheme, } from './utils';
+sudokuColorToTheme, 
+/** Map a solver color string to SudokuColor (case-insensitive; unknown → null). */
+solverColorToSudokuColor, 
+/** Parse a solver digit string ("125") into digits 1-9. */
+parseHintDigits, 
+/** Convert a SolverHintStep into the DisplayHintStep presentBoard takes. */
+convertSolverHintStep, 
+/** Whether a hint step is a conflict hint (has a 'conflict' link). */
+isConflictHintStep, } from './utils';
 // ============================================================================
 // Time Utilities
 // ============================================================================
@@ -213,11 +238,15 @@ isPuzzleCompleted,
 /** Get all completed level IDs from completion history. */
 getCompletedLevelIds, 
 /** Get all completed daily dates (YYYY-MM-DD) from completion history. */
-getCompletedDailyDates, } from './utils';
+getCompletedDailyDates, 
+/** Record a puzzle completion in UserProgress (pure markCompleted reducer). */
+applyPuzzleCompletion, } from './utils';
 /** Theme detection and resolution utilities. */
 export { 
 /** localStorage key for theme preference ('sudojo-theme'). */
 THEME_STORAGE_KEY, 
+/** localStorage key for font size preference ('sudojo-font-size'). */
+FONT_SIZE_STORAGE_KEY, 
 /** Detect the system color scheme preference (light/dark). */
 getSystemTheme, 
 /** Resolve a ThemePreference to an actual theme using the system theme. */
@@ -238,14 +267,76 @@ getPeriodDisplayName,
 /** Check if a subscription period is the "best value" option (annual plans). */
 isBestValuePlan, 
 /** Get a user-friendly error message for a RevenueCat error code. */
-getRevenueCatErrorMessage, } from './utils';
+getRevenueCatErrorMessage, 
+/** i18n key for a period's unit (e.g. 'P1M' -> 'periods.month'), or null. */
+getPeriodLabelKey, 
+/** Localized price suffix for a period (e.g. '/month'), or ''. */
+getPeriodLabel, 
+/** Whether a product is the best-value plan (annual period or annual/yearly id). */
+isBestValueProduct, 
+/** Months in a subscription period (named or ISO 8601), or null. */
+subscriptionPeriodToMonths, 
+/** Percent saved per month by one plan versus another, or null. */
+calculateSavingsPercent, 
+/** Whether a subscription was bought on another platform than this client. */
+isCrossPlatformSubscription, 
+/** Whether the account can be deleted now (signed in, not anonymous, no active subscription). */
+canDeleteAccount, 
+/** Fraction (0-1) of puzzles an offer unlocks, from the levels' percentages. */
+getPuzzleDistribution, 
+/** The plan the savings badge compares with (shortest known period), or null. */
+selectSavingsBasePlan, 
+/** Percent a plan saves per month against the products' savings base plan, or null. */
+getPlanSavingsPercent, } from './utils';
+/** Technique and strategy utilities. */
+export { 
+/** Get the icon URL for a solving technique by its path slug. */
+getTechniqueIconUrl, 
+/** Public slug for a technique path ('3d-medusa' -> 'medusa-coloring'). */
+toCanonicalTechniquePath, 
+/** API path for a technique slug ('medusa-coloring' -> '3d-medusa'). */
+toApiTechniquePath, 
+/** Whether two technique paths name the same technique, aliases included. */
+isSameTechniquePath, 
+/** Find a technique by API path or canonical slug. */
+findTechniqueByPath, 
+/** Parse a comma-separated dependencies field into technique ids. */
+parseTechniqueDependencies, 
+/** Techniques a technique depends on ("Requires"). */
+getTechniqueDependencies, 
+/** Techniques that depend on a technique ("Learn after"). */
+getDependentTechniques, 
+/** Sort techniques by level, then technique number. */
+sortTechniquesByLevel, 
+/** Group techniques by level (Map, each group sorted by technique number). */
+groupTechniquesByLevel, 
+/** Techniques of a strategy, sorted by technique number. */
+getTechniquesForStrategy, 
+/** Find a strategy by its URL stub. */
+findStrategyByStub, 
+/** Public slugs of all 60 techniques (footer / sitemap order). */
+TECHNIQUE_SLUGS, 
+/** Stubs of the 17 strategies (difficulty order). */
+STRATEGY_SLUGS, 
+/** Difficulty tier for a strategy's difficulty value. */
+getStrategyDifficultyTier, 
+/** i18n key for a strategy's difficulty tier (e.g. 'strategy.expert'). */
+getStrategyDifficultyKey, 
+/** Localized sections of a strategy from the strategies namespace. */
+getStrategySections, 
+/** Localized overview, how-it-works steps and tips of a technique. */
+parseTechniqueContent, } from './utils';
 // ============================================================================
-// Technique Utilities
+// Technique Bitmask Utilities
 // ============================================================================
-/** Technique display utilities. */
+/** Exact (bigint) technique bitmasks for boards, dailies and game meta. */
 export { 
-/** Get the icon URL for a solving technique by its path slug. */
-getTechniqueIconUrl, } from './utils';
+/** Exact bitmask of a board/daily/meta; never throws (falls back to 0n). */
+exactTechniqueBitmask, 
+/** Exact bitmask as the base-10 string API requests take. */
+techniqueBitmaskString, 
+/** The techniques / techniques_bitmask pair to store on game meta. */
+techniqueFieldsOf, } from './utils';
 /** Shared logic for building step-by-step technique examples from practice data. */
 export { 
 /** Parse a comma-delimited pencilmarks string into per-cell arrays. */
@@ -280,7 +371,35 @@ getLocalizedHintText,
 /** Get localized title for a hint step using a translation function. */
 getLocalizedHintTitle, 
 /** Resolve a localized API field, falling back to the raw value. */
-localizedField, } from './utils';
+localizedField, 
+/** Key prefix of the per-step heading tree ('headings.'). */
+HINT_HEADING_KEY_PREFIX, 
+/** Heading localization (headings.<path>) for a hint step, or undefined. */
+getStepHeadingLocalization, 
+/** Translated heading for a hint step, or ''. */
+getLocalizedHintHeading, 
+/** Fill {{valueN}} placeholders from a values array. */
+interpolateHintValues, 
+/** Heading for a hint step looked up in a heading tree (no i18n library). */
+getStepHeadingFromTree, 
+/** Build the text/title/heading resolvers behind the apps' useLocalizedHint. */
+createLocalizedHintHelpers, } from './utils';
+/** Translation of API entities (levels, techniques, belts). */
+export { 
+/** Route prefixed entity keys (levels.*, techniques.*) to their namespaces. */
+createNamespacedTranslate, 
+/** Display title of a level (localization, levels namespace, raw title). */
+getLevelDisplayTitle, 
+/** Display description of a level (localization, levels namespace, raw text). */
+getLevelDisplayText, 
+/** Display title of a technique (localization, techniques namespace, raw title). */
+getTechniqueDisplayTitle, 
+/** Localized belt name for a level ('belts' namespace `${level}.name`). */
+getBeltDisplayName, 
+/** Localized belt label for a level ('belts' namespace `${level}.label`). */
+getBeltDisplayLabel, 
+/** Display title of a strategy (localization, strategies namespace, raw title, stub). */
+getStrategyDisplayTitle, } from './utils';
 // ============================================================================
 // i18n Key Utilities
 // ============================================================================
@@ -309,6 +428,17 @@ getLocalizedTechniqueName, } from './utils';
 export { 
 /** Convert a digit (1-9) to its display string based on the format (numeric, kanji, emojis). */
 displayDigit, } from './utils';
+export { 
+/** Fewest givens a scanned board needs (17). */
+MIN_SCAN_CLUES, 
+/** Error thrown by scannedBoardFromResponse / useBoardScan, with a `code`. */
+ScanBoardError, 
+/** Normalize an OCR API result into givens, player digits and pencilmarks. */
+toScannedBoard, 
+/** Whether a scanned board carries any player digits. */
+hasScannedInput, 
+/** Turn the OCR endpoint's response into a ScannedBoard (or throw why not). */
+scannedBoardFromResponse, } from './utils';
 /** Build a share URL from game state. */
 export { buildShareUrl } from './utils';
 /** Parse share URL query parameters into game state. */
@@ -317,6 +447,81 @@ export { parseShareParams } from './utils';
 export { getWebUrl } from './utils';
 /** Check if user-specific API calls should be enabled (non-anonymous, has token). */
 export { isAuthenticatedUser } from './utils';
+/** Whether a user is a real (signed-in, non-anonymous) account. */
+export { isRealUser } from './utils';
+/** Supported languages, locale resolution and language storage keys. */
+export { 
+/** The 15 supported UI languages. */
+SUPPORTED_LANGUAGES, 
+/** Codes of the supported languages. */
+SUPPORTED_LANGUAGE_CODES, 
+/** Fallback language ('en'). */
+DEFAULT_LANGUAGE, 
+/** Web localStorage key for the language preference ('language'). */
+LANGUAGE_STORAGE_KEY, 
+/** RN AsyncStorage key for the language preference ('@sudojo/language'). */
+NATIVE_LANGUAGE_STORAGE_KEY, 
+/** Whether a code is a supported language code. */
+isSupportedLanguage, 
+/** Map a code or locale tag to a supported code (zh-TW/HK -> zh-hant), or null. */
+normalizeLanguageCode, 
+/** Supported language for a locale tag, defaulting to 'en'. */
+resolveLanguage, 
+/** BCP 47 casing of a code ('zh-hant' -> 'zh-Hant'). */
+toLanguageTag, 
+/** Native name of a language, or undefined. */
+getLanguageNativeName, } from './utils';
+/** Community platform order and labels. */
+export { 
+/** Known community platforms in display order. */
+COMMUNITY_PLATFORMS, 
+/** Info for a platform id (case-insensitive), or undefined. */
+getCommunityPlatform, 
+/** Sort platform ids into display order (unknown last). */
+sortCommunityPlatforms, } from './utils';
+/** Badge grouping for profile and statistics screens. */
+export { 
+/** badgeType of level mastery badges ('level_mastery'). */
+LEVEL_MASTERY_BADGE_TYPE, 
+/** badgeType of games-played badges ('games_played'). */
+GAMES_PLAYED_BADGE_TYPE, 
+/** Split badge definitions into sorted level/game lists with isEarned. */
+groupBadgeProgress, } from './utils';
+/** Client-side hint gating helpers. */
+export { 
+/** Hint steps visible without the level's entitlement (2). */
+FREE_HINT_STEP_LIMIT, 
+/** Map a hint access state to the panel's action and message variant. */
+getHintAccessAction, 
+/** i18n key suffixes for the hint access messages. */
+HINT_ACCESS_KEY_SUFFIXES, } from './utils';
+// ============================================================================
+// Daily Date Utilities
+// ============================================================================
+/** Calendar-date helpers for daily puzzles (UTC "today", like the API). */
+export { 
+/** UTC date of a Date (default now) as YYYY-MM-DD. */
+getUtcDateString, 
+/** Normalize a daily date to YYYY-MM-DD without a timezone shift, or null. */
+normalizeDailyDate, 
+/** Format a YYYY-MM-DD daily date as a local calendar date. */
+formatDailyDate, 
+/** Whether a saved daily is not today's (UTC) daily. */
+isStaleDaily, } from './utils';
+/** Status derivation shared by useLevelGame and useDailyGame. */
+export { 
+/** Whether a response/error says sign-in is required (legacy API signal). */
+isAuthRequiredResponse, 
+/** Whether a response/error says a subscription is required (legacy API signal). */
+isSubscriptionRequiredResponse, 
+/** Derive a GameFetchStatus from query state. */
+getGameFetchStatus, 
+/** HTTP status carried by an error (NetworkError.status), or undefined. */
+getErrorHttpStatus, 
+/** Derive a PracticeFetchStatus (401/402 aware) from query state. */
+getPracticeFetchStatus, } from './utils';
+/** Build walkthrough cards and headings for a stored technique example. */
+export { buildTechniqueWalkthrough } from './utils';
 // ============================================================================
 // Hooks
 // ============================================================================
@@ -366,6 +571,8 @@ useGamePlay,
 useContinueGame, 
 /** Manual puzzle entry mode with solver validation. */
 useBoardEntry, 
+/** Scan a board from an image: givens, player digits and pencilmarks. */
+useBoardScan, 
 /** Server-side game session management for gamification (points, badges). */
 useGameSession, 
 /** Check whether a level is enabled for the current user's entitlements. */
@@ -391,7 +598,35 @@ reportHintStatus,
 /** Subscribe to hint status updates. */
 onHintStatus, 
 /** Hook for SudokuGame to listen for external hint action events. */
-useHintActionListener, } from './hooks';
+useHintActionListener, 
+/** Fire a callback once each time a puzzle becomes completed (re-arms on false). */
+useCompletionTrigger, 
+/** Fetch strategies (unwrapped) with findStrategyByStub. */
+useStrategies, 
+/** Fetch a random practice for a technique with auth/subscription/empty status. */
+usePracticeGame, 
+/** Whether the user is a real (non-anonymous) account. */
+useIsRealUser, 
+/** Whether the signed-in user is a site admin (GET /users/:uid siteAdmin). */
+useIsSiteAdmin, 
+/** Look up a technique by path or alias (list first, then GET by path). */
+useTechniqueByPath, 
+/** Fetch a technique's worked example and build its walkthrough. */
+useTechniqueExample, 
+/** Build (memoized) the walkthrough for a stored technique example. */
+useTechniqueWalkthrough, 
+/** Player's puzzle progress in localStorage (markCompleted, isCompleted, stats). */
+usePuzzleProgress, 
+/** Account deletion rule and delete-then-sign-out sequence. */
+useDeleteAccount, 
+/** Saved game to resume for a play screen (snapshot; clears stale dailies). */
+useResumeGame, 
+/** The saved game a play screen should resume, or null (pure). */
+getResumeGame, 
+/** Daily/Level play screen orchestration (resume, save, session, completion). */
+usePuzzleSession, 
+/** Entered-puzzle save/resume after validation (no server session). */
+useEnteredGameSession, } from './hooks';
 // ============================================================================
 // Stores
 // ============================================================================
@@ -407,10 +642,41 @@ export { EntitlementProvider } from './context';
 /** React context for entitlements (for advanced use). */
 export { EntitlementContext, useEntitlementContext } from './context';
 // ============================================================================
+// Sudojo API Context
+// ============================================================================
+/** Optional provider of networkClient/baseUrl/token for sudojo_lib hooks. */
+export { SudojoApiProvider } from './context';
+/** API context, its hooks, and the option-over-context resolver. */
+export { 
+/** React context holding the API connection (for advanced use). */
+SudojoApiContext, 
+/** The provider's API connection (throws without a provider). */
+useSudojoApi, 
+/** The provider's API connection, or null. */
+useOptionalSudojoApi, 
+/** Merge explicit options over a context value (pure; throws if incomplete). */
+resolveSudojoApi, 
+/** Resolve a hook's API connection from options, then the provider. */
+useResolvedSudojoApi, } from './context';
+// ============================================================================
 // Entitlement Utilities (re-exported from sudojo_types)
 // ============================================================================
 /** Parse a comma-delimited entitlement string into an array. */
 export { parseEntitlements } from '@sudobility/sudojo_types';
 /** Check if a user has the required entitlement for a level. */
 export { hasRequiredEntitlement } from '@sudobility/sudojo_types';
+// ============================================================================
+// Admin (batch jobs + stats; see src/admin/index.ts for the full list)
+// ============================================================================
+/**
+ * Admin module: board generation, technique extraction, example creation and
+ * admin stats as hooks (`useBoardGenerator`, `useTechniqueExtractor`,
+ * `useExampleCreator`, `useSingleBoardExtractor`, `useBoardTechniquesUpdater`,
+ * `useAdminStats`), the framework-agnostic jobs behind them
+ * (`runBoardGeneration`, `runTechniqueExtraction`, `runExampleCreation`) and
+ * their pure rules (`mergeBoardWithUserInput`, `adjustPracticeSolution`,
+ * `extractBoardTechniques`, `levelsToSearchForTechnique`, …). Network calls go
+ * only through sudojo_client hooks (`useAdminApi`).
+ */
+export * from './admin';
 //# sourceMappingURL=index.js.map