@patternbank/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,919 @@
+import { SupabaseClient } from '@supabase/supabase-js';
+
+type Difficulty = "Easy" | "Medium" | "Hard";
+type Confidence = 1 | 2 | 3 | 4 | 5;
+type SyncStatus = "idle" | "syncing" | "pending" | "synced" | "offline" | "error";
+type LeetCodeSyncStatus = "idle" | "syncing" | "synced" | "error" | "no_visible_submissions" | "rate_limited";
+type LeetCodeSubmissionStatus = "detected" | "linked_existing" | "pending" | "imported" | "ignored" | "rated";
+interface Problem {
+    id: string;
+    title: string;
+    leetcodeNumber: number | null;
+    url: string | null;
+    difficulty: Difficulty;
+    patterns: string[];
+    confidence: Confidence;
+    notes: string;
+    excludeFromReview: boolean;
+    dateAdded: string;
+    lastReviewed: string | null;
+    nextReviewDate: string;
+    fiveStarStreak?: number;
+    updatedAt: string;
+}
+interface LeetCodeProblem {
+    n: number;
+    t: string;
+    d: Difficulty;
+    s: string;
+}
+interface LeetCodeConnection {
+    userId: string;
+    leetcodeUsername: string;
+    leetcodeDisplayName?: string | null;
+    leetcodeAvatarUrl?: string | null;
+    leetcodeTotalSolved?: number | null;
+    lastSeenAcceptedCount?: number | null;
+    lastSyncedAt?: string | null;
+    lastSyncStartedAt?: string | null;
+    syncStatus: LeetCodeSyncStatus;
+    syncError?: string | null;
+    createdAt?: string;
+    updatedAt?: string;
+}
+interface LeetCodeSubmission {
+    id: string;
+    userId: string;
+    leetcodeUsername: string;
+    leetcodeSubmissionId: string;
+    titleSlug: string;
+    title: string;
+    leetcodeNumber: number | null;
+    difficulty: Difficulty | null;
+    submittedAt: string;
+    problemId?: string | null;
+    status: LeetCodeSubmissionStatus;
+    createdAt?: string;
+    updatedAt?: string;
+}
+interface LeetCodeIgnoredImport {
+    userId: string;
+    titleSlug: string;
+    leetcodeNumber: number | null;
+    ignoredAt?: string;
+    createdAt?: string;
+}
+interface PendingLeetCodeImport {
+    submissionDbId: string;
+    leetcodeSubmissionId?: string | null;
+    titleSlug: string;
+    title: string;
+    leetcodeNumber: number | null;
+    difficulty: Difficulty | null;
+    submittedAt: string;
+    firstSeenAt?: string;
+    suggestedPatterns: string[];
+    expired: boolean;
+}
+type TodayLeetCodeItem = (PendingLeetCodeImport & {
+    kind: "pending_import";
+    status: "detected";
+    matchedProblemId: null;
+    statusLabel: "Rate to add";
+}) | {
+    kind: "linked_existing" | "imported" | "rated";
+    submissionDbId: string;
+    titleSlug: string;
+    title: string;
+    leetcodeNumber: number | null;
+    difficulty: Difficulty | null;
+    submittedAt: string;
+    suggestedPatterns: string[];
+    matchedProblemId: string | null;
+    status: "linked_existing" | "imported" | "rated";
+    statusLabel: "In library" | "Review due" | "Imported" | "Rated";
+    leetcodeSubmissionId?: string | null;
+    confidence: Confidence | null;
+    reviewedTodayConfidence: Confidence | null;
+};
+interface LeetCodeSyncSummary {
+    fetchedCount?: number;
+    insertedCount?: number;
+    existingCount?: number;
+    linkedExistingCount?: number;
+    lastSyncedAt?: string | null;
+    throttled?: boolean;
+}
+interface ReviewLogEntry {
+    date: string;
+}
+interface ReviewEvent {
+    date: string;
+    problemId: string;
+    confidence: number;
+    patterns: string[];
+    timestamp: string;
+}
+interface ProblemTombstone {
+    problemId: string;
+    deletedAt: string;
+}
+interface DataReset {
+    resetAt: string;
+}
+/**
+ * Preferences shared by every platform. Platforms extend this with their own
+ * fields (mobile adds notification settings) and alias it as `Preferences`.
+ * `updatedAt` powers newest-wins preference sync (F-6); it is optional because
+ * blobs persisted before the field existed lack it — sync treats absence as
+ * the epoch so legacy cloud data still wins the first merge.
+ */
+interface CorePreferences {
+    dailyReviewGoal: number;
+    hidePatternsDuringReview: boolean;
+    enabledExtraPatterns: string[];
+    updatedAt?: string;
+}
+interface BackupData {
+    exportedAt?: string;
+    problems: Problem[];
+    reviewLog?: ReviewLogEntry[];
+    reviewEvents?: ReviewEvent[];
+}
+interface PatternColor {
+    text: string;
+    bg: string;
+}
+interface ReviewHistoryEntry {
+    reviewDate: string;
+    newConfidence: number;
+    createdAt: string;
+}
+interface ProblemList {
+    id: string;
+    name: string;
+    nameZh: string;
+    description: string;
+    source: string;
+    numbers: number[];
+}
+interface ListSummary {
+    id: string;
+    name: string;
+    nameZh: string;
+    description: string;
+    total: number;
+    existing: number;
+    newCount: number;
+}
+
+declare const CORE_PATTERNS: readonly ["Two Pointers", "Hash Table", "Sliding Window", "Binary Search", "Sorting", "Linked List", "Stack", "Queue", "Tree", "BFS", "DFS", "Heap", "Greedy", "Backtracking", "Graph", "Union Find", "Trie", "DP"];
+declare const EXTRA_PATTERNS: readonly ["Intervals", "Mono Stack", "Prefix Sum", "Bit", "System Design", "OOD"];
+declare function getVisiblePatterns(enabledExtras: string[]): string[];
+declare const DIFFICULTIES: readonly Difficulty[];
+declare const STORAGE_KEY = "patternbank-problems";
+declare const REVIEW_LOG_KEY = "patternbank-review-log";
+declare const REVIEW_EVENTS_KEY = "patternbank-review-events";
+declare const PREFERENCES_KEY = "patternbank-preferences";
+declare const PROBLEM_TOMBSTONES_KEY = "patternbank-problem-tombstones";
+declare const DATA_RESET_KEY = "patternbank-data-reset";
+/**
+ * ISO cutoff below which review events were locally pruned (F-3). Merge drops
+ * cloud events older than this watermark so pruned history is not resurrected.
+ */
+declare const REVIEW_EVENTS_PRUNED_BEFORE_KEY = "patternbank-review-events-pruned-before";
+declare const DEFAULT_PREFERENCES: CorePreferences;
+
+declare function formatLocalDate(date: Date): string;
+declare function parseDateOnly(dateStr: string): {
+    year: number;
+    month: number;
+    day: number;
+};
+declare function dateOnlyToUtcMs(dateStr: string): number;
+declare function todayStr(): string;
+declare function formatDisplayDate(dateStr: string): string;
+declare function utcToLocalDateStr(isoTimestamp: string | null | undefined): string | null;
+declare function addDays(dateStr: string, days: number): string;
+declare function formatRelativeDate(dateStr: string): string;
+declare function generateId(): string;
+/**
+ * Parse an ISO timestamp to epoch ms; missing or unparseable values collapse
+ * to 0 (the epoch). Sync merges rely on this guard (F-17) so a malformed
+ * timestamp deterministically loses to any valid one instead of winning a
+ * `NaN` comparison.
+ */
+declare function timestampMs(value: string | null | undefined): number;
+
+/**
+ * Platform callback hooks (plan: "Adapter contracts").
+ * Core never imports posthog/sentry/console; platforms inject these instead.
+ */
+interface CoreHooks {
+    analytics?: (event: string, props?: Record<string, unknown>) => void;
+    /** Web Today-LC snapshot logging. */
+    debugLog?: (message: string, data?: unknown) => void;
+    /** F-14 corrupt-row warnings. */
+    warn?: (message: string, data?: unknown) => void;
+    /** Injectable clock for testability. */
+    now?: () => Date;
+}
+
+declare const INTERVALS: Record<Confidence, number>;
+declare const FIVE_STAR_GRADUATION_INTERVALS: readonly [30, 60, 120, 240, 365];
+declare function getIntervalDays(confidence: Confidence): number;
+declare function getDefaultFiveStarStreak(confidence: number): number;
+declare function getFiveStarGraduationIntervalDays(streak: number): number;
+declare function getPreviousFiveStarStreak(problem: Problem): number;
+declare function getNextFiveStarStreak(problem: Problem, newConfidence: Confidence): number;
+declare function getReviewIntervalDays(problem: Problem, newConfidence: Confidence): number;
+declare function prioritizeProblems(dueProblems: Problem[], limit: number, today?: string): Problem[];
+
+interface ProgressConfidenceTint {
+    background: string;
+    border: string;
+    text: string;
+}
+declare const PROGRESS_EMPTY_CONFIDENCE_TINT: ProgressConfidenceTint;
+declare const PROGRESS_HEATMAP_CONFIDENCE_TINTS: readonly ProgressConfidenceTint[];
+declare const PROGRESS_CONFIDENCE_TINTS: readonly ProgressConfidenceTint[];
+declare function getProgressConfidenceTint(avgConfidence: number, count: number): ProgressConfidenceTint;
+declare function getProgressHeatmapTint(avgConfidence: number, count: number): ProgressConfidenceTint;
+
+declare function calculateLongestStreak(log: ReviewLogEntry[]): number;
+declare function buildReviewCountMap(reviewEvents: ReviewEvent[], reviewLog: ReviewLogEntry[]): Map<string, number>;
+declare function getWeekStart(dateStr: string): string;
+declare function groupEventsByWeek(events: ReviewEvent[], numWeeks: number, startDate: string): {
+    weekStart: string;
+    avg: number | null;
+}[];
+declare function getConfidenceDistribution(confidences: number[]): [number, number, number, number, number];
+declare function getTopPatterns(patterns: string[][], limit: number): [string, number][];
+
+interface ProblemRow {
+    id: string;
+    user_id: string;
+    title: string;
+    leetcode_number: number | null;
+    url: string | null;
+    difficulty: string;
+    patterns: string[];
+    confidence: number;
+    notes: string;
+    exclude_from_review: boolean;
+    date_added: string;
+    last_reviewed: string | null;
+    next_review_date: string;
+    five_star_streak?: number | null;
+    /** F-14: always a string on write; reads are validated with an epoch fallback. */
+    updated_at: string;
+}
+interface ProblemTombstoneRow {
+    user_id: string;
+    problem_id: string;
+    deleted_at: string;
+    created_at?: string;
+    updated_at?: string;
+}
+interface DataResetRow {
+    user_id: string;
+    reset_at: string;
+    created_at?: string;
+    updated_at?: string;
+}
+interface ReviewEventRow {
+    problem_id: string;
+    new_confidence: number;
+    patterns: string[] | null;
+    review_date: string;
+    created_at: string;
+}
+/**
+ * The subset of preferences that syncs to Supabase. Platforms may extend
+ * their local Preferences (mobile adds notification fields) — only these
+ * fields travel to the cloud. `updatedAt` powers newest-wins merge (F-6).
+ */
+type CloudPreferences = Pick<CorePreferences, "dailyReviewGoal" | "hidePatternsDuringReview" | "enabledExtraPatterns" | "updatedAt">;
+declare function toCloudPreferences(data: Record<string, unknown>): CloudPreferences;
+/** F-8: deterministic dedupe key shared by logReview and batch review-log inserts. */
+declare function reviewDedupeKey(userId: string, problemId: string, timestamp: string): string;
+declare function toSnakeCase(problem: Problem): Omit<ProblemRow, "user_id">;
+declare function toCamelCase(row: Record<string, unknown>, hooks?: Pick<CoreHooks, "warn">): Problem;
+
+/** Compares only the cloud-synced content fields — platform extras (and `updatedAt`) are ignored. */
+declare function preferencesEqual(a: Pick<CorePreferences, "dailyReviewGoal" | "hidePatternsDuringReview" | "enabledExtraPatterns">, b: Pick<CorePreferences, "dailyReviewGoal" | "hidePatternsDuringReview" | "enabledExtraPatterns">): boolean;
+interface MergePreferencesResult<P extends CorePreferences> {
+    preferences: P;
+    winner: "local" | "cloud";
+}
+/**
+ * Newest-wins preference merge (F-6). Blobs persisted before `updatedAt`
+ * existed get the epoch shim — anything stamped beats them, and two unstamped
+ * blobs preserve the legacy cloud-wins behavior (ties go to cloud). Platform
+ * extras on the local blob (e.g. mobile notification fields) always survive;
+ * only the cloud-synced subset is overwritten when cloud wins.
+ */
+declare function mergePreferences<P extends CorePreferences>(local: P, cloud: CloudPreferences | null): MergePreferencesResult<P>;
+
+interface BuildNewProblemsOptions {
+    today: string;
+    now: string;
+    dailyGoal: number;
+    patternMap: Map<number, string[]> | null;
+}
+/**
+ * Filter out LC problems that already exist in the user's library.
+ */
+declare function filterExistingProblems(lcProblems: LeetCodeProblem[], existingProblems: Problem[]): {
+    newProblems: LeetCodeProblem[];
+    skippedCount: number;
+};
+/**
+ * Round-robin interleave problems by difficulty (Easy, Medium, Hard).
+ */
+declare function interleaveByDifficulty(lcProblems: LeetCodeProblem[]): LeetCodeProblem[];
+/**
+ * Build full problem objects from LC problem data, distributing review dates.
+ */
+declare function buildNewProblems(lcProblems: LeetCodeProblem[], { today, now, dailyGoal, patternMap }: BuildNewProblemsOptions): Problem[];
+/**
+ * Deduplicate problems by leetcodeNumber, keeping the entry with the most recent updatedAt.
+ * Problems without a leetcodeNumber are always kept.
+ */
+declare function deduplicateProblems(problems: Problem[]): {
+    problems: Problem[];
+    removedIds: string[];
+};
+/**
+ * Merge imported problems with existing ones by id, then by LeetCode number.
+ * When a cross-device LeetCode match has a different local id, keep the local
+ * canonical id so existing review history stays attached to the same problem.
+ */
+declare function mergeImportedProblems(existingProblems: Problem[], importedProblems: Problem[]): {
+    mergedProblems: Problem[];
+    addedCount: number;
+    updatedCount: number;
+    changedProblems: Problem[];
+    importedIdToCanonicalId: Map<string, string>;
+};
+/**
+ * Compute review progress toward the daily goal.
+ */
+declare function computeReviewProgress(problems: Problem[], dailyReviewGoal: number): {
+    currentReviewed: number;
+    totalDue: number;
+    effectiveGoal: number;
+};
+/**
+ * Build an updated problem after a review with new confidence and dates.
+ */
+declare function buildReviewedProblem(problem: Problem, newConfidence: Confidence): Problem;
+declare function computeNextReviewDate(initialData: Problem | null, newConfidence: Confidence, today: string): string;
+
+type ProjectionDistribution = [number, number, number, number, number];
+interface ProjectionSnapshot {
+    day: number;
+    distribution: ProjectionDistribution;
+}
+type ProjectionDay = ProjectionSnapshot;
+interface ProjectionSeriesOptions {
+    startDistribution: ProjectionDistribution;
+    dailyGoal: number;
+    newPerWeek: number;
+    days?: number;
+    seed?: number;
+    advanceRate?: number;
+}
+declare function simulateProjection(startDistribution: ProjectionDistribution, dailyGoal: number, newPerWeek: number, days?: number, seed?: number): ProjectionSnapshot[];
+declare function simulateProjectionSeries({ startDistribution, dailyGoal, newPerWeek, days, seed, advanceRate, }: ProjectionSeriesOptions): ProjectionDay[];
+
+/**
+ * Platform storage abstraction (plan: "Adapter contracts").
+ * Web wraps localStorage in Promises; mobile passes AsyncStorage directly.
+ */
+interface StorageAdapter {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+    /** AsyncStorage-native batch removal; web loops removeItem instead. */
+    multiRemove?(keys: string[]): Promise<void>;
+}
+
+interface CreateCloudDataOptions {
+    /**
+     * Platform Supabase client. May be null (missing credentials) — every
+     * returned function then no-ops with its `{ data: null, error: null }`-style
+     * guard shape, exactly as both platforms behave today.
+     */
+    supabase: SupabaseClient | null;
+    hooks?: CoreHooks;
+    /** Per-operation cloud timeout (F-9). */
+    timeoutMs?: number;
+}
+interface CloudData {
+    fetchProblems(userId: string): Promise<{
+        data: Problem[] | null;
+        error: unknown;
+    }>;
+    upsertProblem(userId: string, problem: Problem): Promise<{
+        data: Problem | null;
+        error: unknown;
+    }>;
+    upsertProblems(userId: string, problems: Problem[]): Promise<{
+        data: Problem[] | null;
+        error: unknown;
+    }>;
+    deleteProblem(problemId: string): Promise<{
+        data: null;
+        error: unknown;
+    }>;
+    deleteProblems(problemIds: string[]): Promise<{
+        error: unknown;
+    }>;
+    fetchProblemTombstones(userId: string): Promise<{
+        data: ProblemTombstone[] | null;
+        error: unknown;
+    }>;
+    upsertProblemTombstone(userId: string, tombstone: ProblemTombstone): Promise<{
+        error: unknown;
+    }>;
+    upsertProblemTombstones(userId: string, tombstones: ProblemTombstone[]): Promise<{
+        error: unknown;
+    }>;
+    fetchDataReset(userId: string): Promise<{
+        data: DataReset | null;
+        error: unknown;
+    }>;
+    upsertDataReset(userId: string, reset: DataReset): Promise<{
+        error: unknown;
+    }>;
+    fetchReviewLog(userId: string): Promise<{
+        data: ReviewLogEntry[] | null;
+        error: unknown;
+    }>;
+    logReview(userId: string, problemId: string, oldConfidence: Confidence, newConfidence: Confidence, patterns?: string[], timestamp?: string): Promise<{
+        data: unknown;
+        error: unknown;
+    }>;
+    replaceReviewLog(userId: string, problemId: string, oldConfidence: Confidence, newConfidence: Confidence, patterns: string[], timestamp?: string): Promise<{
+        data: unknown;
+        error: unknown;
+    }>;
+    fetchReviewEvents(userId: string, since?: string): Promise<{
+        data: ReviewEvent[] | null;
+        error: unknown;
+    }>;
+    batchInsertReviewLogs(userId: string, events: ReviewEvent[]): Promise<{
+        error: unknown;
+    }>;
+    fetchProblemReviewHistory(userId: string, problemId: string): Promise<{
+        data: ReviewHistoryEntry[] | null;
+        error: unknown;
+    }>;
+    fetchPreferences(userId: string): Promise<{
+        data: CloudPreferences | null;
+        error: unknown;
+    }>;
+    upsertPreferences(userId: string, prefs: CloudPreferences): Promise<{
+        data: CloudPreferences | null;
+        error: unknown;
+    }>;
+    submitFeedback(userId: string | null, message: string): Promise<{
+        error: unknown;
+    }>;
+    deleteAllUserProblems(userId: string): Promise<{
+        error: unknown;
+    }>;
+    deleteAllUserReviewLog(userId: string): Promise<{
+        error: unknown;
+    }>;
+}
+declare function createCloudData(options: CreateCloudDataOptions): CloudData;
+
+/** The slice of the cloud-data surface performFullSync drives; the full CloudData satisfies it. */
+type FullSyncCloud = Pick<CloudData, "fetchProblems" | "fetchProblemTombstones" | "fetchDataReset" | "fetchReviewLog" | "fetchReviewEvents" | "fetchPreferences" | "upsertDataReset" | "deleteAllUserProblems" | "deleteAllUserReviewLog" | "upsertProblemTombstones" | "deleteProblems" | "upsertProblems" | "batchInsertReviewLogs" | "upsertPreferences">;
+interface FullSyncLocalState<P extends CorePreferences = CorePreferences> {
+    problems: Problem[];
+    reviewLog: ReviewLogEntry[];
+    reviewEvents: ReviewEvent[];
+    preferences: P;
+    problemTombstones: ProblemTombstone[];
+    dataReset: DataReset | null;
+}
+interface FullSyncDeps<P extends CorePreferences = CorePreferences> {
+    userId: string;
+    cloud: FullSyncCloud;
+    /**
+     * Used only for the prune watermark (F-3). Merged data is RETURNED, never
+     * written here — the platform persists it, so a failed sync leaves local
+     * state untouched (F-5).
+     */
+    storage: StorageAdapter;
+    local: FullSyncLocalState<P>;
+    /** Local review-event retention: null never prunes (web); mobile passes 180. */
+    eventRetentionDays: number | null;
+    hooks?: CoreHooks;
+}
+interface FullSyncSuccess<P extends CorePreferences = CorePreferences> extends FullSyncLocalState<P> {
+    status: "success";
+    hasChanges: boolean;
+}
+interface FullSyncFailure {
+    status: "error";
+    error: unknown;
+}
+type FullSyncResult<P extends CorePreferences = CorePreferences> = FullSyncSuccess<P> | FullSyncFailure;
+/**
+ * Full sign-in sync: pull everything, merge with the provided local snapshot,
+ * repair the cloud, and return the merged state for the platform to persist.
+ *
+ * Fail-closed (F-5): any critical fetch or any cloud write failure aborts with
+ * `{ status: "error" }` and no partial local writes. Tolerated degradations
+ * (kept from both platforms): review-event and preference fetch failures skip
+ * their backfill/merge instead of aborting.
+ */
+declare function performFullSync<P extends CorePreferences = CorePreferences>(deps: FullSyncDeps<P>): Promise<FullSyncResult<P>>;
+
+interface MergeProblemsResult {
+    problems: Problem[];
+    cloudAdded: number;
+    cloudWon: number;
+}
+declare function mergeProblems(localProblems: Problem[], cloudProblems: Problem[]): MergeProblemsResult;
+interface MergeProblemTombstonesResult {
+    tombstones: ProblemTombstone[];
+    addedFromCloud: number;
+}
+declare function mergeProblemTombstones(localTombstones: ProblemTombstone[], cloudTombstones: ProblemTombstone[]): MergeProblemTombstonesResult;
+/**
+ * F-25: last-write-wins — a tombstone only kills rows not updated after it, so
+ * a problem restored from a backup (re-stamped past its tombstone) survives
+ * everywhere while stale pre-delete copies on other devices still die. Ties go
+ * to the delete.
+ */
+declare function filterTombstonedProblems(problems: Problem[], tombstones: ProblemTombstone[]): Problem[];
+interface MergeReviewLogResult {
+    log: ReviewLogEntry[];
+    addedFromCloud: number;
+}
+declare function mergeReviewLog(localLog: ReviewLogEntry[], cloudLog: ReviewLogEntry[]): MergeReviewLogResult;
+declare function dataResetTime(reset: DataReset | null | undefined): number;
+declare function compareDataResets(localReset: DataReset | null, cloudReset: DataReset | null): "local" | "cloud" | "none";
+declare function newestDataReset(localReset: DataReset | null, cloudReset: DataReset | null): DataReset | null;
+declare function filterProblemsAfterDataReset(problems: Problem[], reset: DataReset | null): {
+    problems: Problem[];
+    removedIds: string[];
+};
+declare function filterReviewEventsAfterDataReset(events: ReviewEvent[], reset: DataReset | null): ReviewEvent[];
+/**
+ * F-20: review-log entries are date-only, so compare against the LOCAL date of
+ * the reset. `>=` keeps legitimate same-day post-clear reviews; the plain
+ * date-string compare avoids rebuilding the log from events (which would churn
+ * under mobile's 180-day event retention).
+ */
+declare function filterReviewLogAfterDataReset(log: ReviewLogEntry[], reset: DataReset | null): ReviewLogEntry[];
+declare function filterTombstonesAfterDataReset(tombstones: ProblemTombstone[], reset: DataReset | null): ProblemTombstone[];
+declare function reviewLogFromEvents(events: ReviewEvent[]): ReviewLogEntry[];
+/** F-7: review events whose problem did not survive the merge are orphans. */
+declare function filterReviewEventsToProblems(events: ReviewEvent[], problemIds: Set<string>): ReviewEvent[];
+
+declare function reviewEventKey(event: ReviewEvent): string;
+/**
+ * Two events are the same review when their keys match exactly, or when they
+ * hit the same problem within 5 seconds ON THE SAME calendar date (legacy
+ * timestamp mismatch between platforms). The date gate is canonical core
+ * behavior: near-midnight events on different dates are distinct streak days
+ * and must both survive a merge.
+ */
+declare function reviewEventsMatch(a: ReviewEvent, b: ReviewEvent): boolean;
+interface MergeReviewEventsOptions {
+    /**
+     * F-3 prune watermark (ISO): cloud events strictly older than this were
+     * pruned locally on purpose and are dropped instead of resurrected.
+     */
+    prunedBefore?: string | null;
+}
+interface MergeReviewEventsResult {
+    events: ReviewEvent[];
+    addedFromCloud: number;
+    localOnlyEvents: ReviewEvent[];
+}
+declare function mergeReviewEvents(localEvents: ReviewEvent[], cloudEvents: ReviewEvent[], options?: MergeReviewEventsOptions): MergeReviewEventsResult;
+
+declare const CLOUD_OPERATION_TIMEOUT_MS = 15000;
+declare const FULL_SYNC_TIMEOUT_MS = 25000;
+declare const LEETCODE_ACTIVITY_TIMEOUT_MS = 45000;
+declare class SyncTimeoutError extends Error {
+    operation: string;
+    timeoutMs: number;
+    constructor(operation: string, timeoutMs: number);
+}
+declare function isSyncTimeoutError(error: unknown): error is SyncTimeoutError;
+declare function isLikelyOfflineError(error: unknown): boolean;
+declare function withTimeout<T>(promise: PromiseLike<T>, timeoutMs: number, operation: string): Promise<T>;
+declare function withCloudOperationTimeout<T>(operation: string, promise: PromiseLike<T>): Promise<T>;
+
+interface TodayReviewState {
+    todaysReviews: Problem[];
+    totalDueCount: number;
+    reviewedToday: number;
+    effectiveGoal: number;
+    remainingSlots: number;
+}
+interface DoneTodayFeedItem {
+    id: string;
+    problemId: string;
+    title: string;
+    leetcodeNumber: number | null;
+    difficulty: Difficulty;
+    confidence: Confidence;
+    timestamp: string;
+}
+type TodayActivityFeedItem = {
+    type: "pb_review";
+    id: string;
+    problemId: string;
+    title: string;
+    leetcodeNumber: number | null;
+    difficulty: Difficulty;
+    confidence: Confidence;
+    timestamp: string;
+} | {
+    type: "leetcode_solve";
+    id: string;
+    submissionDbId: string;
+    problemId: string;
+    title: string;
+    leetcodeNumber: number | null;
+    difficulty: Difficulty;
+    submittedAt: string;
+    status: "linked_existing" | "imported" | "rated";
+    reviewDue: boolean;
+    canRate: boolean;
+};
+interface SolvedOnLeetCodeTodayIndex {
+    problemIds: Set<string>;
+    leetcodeNumbers: Set<number>;
+}
+interface ExitingTodayLeetCodeItem {
+    key: string;
+    item: TodayLeetCodeItem;
+}
+declare function buildTodayReviewState(problems: Problem[], dailyGoal: number, today?: string): TodayReviewState;
+declare function buildDoneTodayFeedItems(problems: Problem[], reviewEvents: ReviewEvent[], today?: string): DoneTodayFeedItem[];
+declare function buildSolvedOnLeetCodeTodayIndex(leetcodeSubmissions: LeetCodeSubmission[], today?: string): SolvedOnLeetCodeTodayIndex;
+declare function buildTodayLeetCodeItemKey(item: TodayLeetCodeItem): string;
+declare function buildRemovedTodayLeetCodeItems({ previousItems, currentItems, exitingKeys, }: {
+    previousItems: TodayLeetCodeItem[];
+    currentItems: TodayLeetCodeItem[];
+    exitingKeys: Set<string>;
+}): ExitingTodayLeetCodeItem[];
+declare function buildTodayActivityFeedItems({ problems, reviewEvents, leetcodeSubmissions, today, }: {
+    problems: Problem[];
+    reviewEvents: ReviewEvent[];
+    leetcodeSubmissions: LeetCodeSubmission[];
+    today?: string;
+}): TodayActivityFeedItem[];
+
+declare function calculateStreak(log: ReviewLogEntry[]): number;
+declare function countReviewedToday(problems: Problem[]): number;
+interface PruneOldEventsOptions {
+    /** Days of history to keep; null/undefined disables pruning entirely (web). */
+    retentionDays?: number | null;
+    today?: string;
+}
+interface PruneOldEventsResult {
+    kept: ReviewEvent[];
+    /**
+     * F-3 watermark: the YYYY-MM-DD cutoff (events with date >= cutoff are kept),
+     * or null when pruning is disabled. Platforms persist this under
+     * REVIEW_EVENTS_PRUNED_BEFORE_KEY so merges can drop pre-cutoff cloud events.
+     */
+    cutoffIso: string | null;
+}
+/**
+ * Pure prune (F-3): no persistence side effects; callers save `kept` and the
+ * watermark explicitly as a post-sync maintenance step, never on load.
+ */
+declare function pruneOldEvents(events: ReviewEvent[], { retentionDays, today }: PruneOldEventsOptions): PruneOldEventsResult;
+
+declare const LEETCODE_RECENT_ACTIVITY_LIMIT = 100;
+interface LeetCodeConnectionRow {
+    user_id: string;
+    leetcode_username: string;
+    leetcode_display_name?: string | null;
+    leetcode_avatar_url?: string | null;
+    leetcode_total_solved?: number | null;
+    last_seen_accepted_count?: number | null;
+    last_synced_at?: string | null;
+    last_sync_started_at?: string | null;
+    sync_status: string;
+    sync_error?: string | null;
+    created_at?: string;
+    updated_at?: string;
+}
+interface LeetCodeSubmissionRow {
+    id: string;
+    user_id: string;
+    leetcode_username: string;
+    leetcode_submission_id: string;
+    title_slug: string;
+    title: string;
+    leetcode_number?: number | null;
+    difficulty?: string | null;
+    submitted_at: string;
+    problem_id?: string | null;
+    status: string;
+    created_at?: string;
+    updated_at?: string;
+}
+interface LeetCodeIgnoredImportRow {
+    user_id: string;
+    title_slug: string;
+    leetcode_number?: number | null;
+    ignored_at?: string;
+    created_at?: string;
+}
+interface LeetCodeActivityFunctionResponse {
+    connection: LeetCodeConnection | null;
+    submissions: LeetCodeSubmission[];
+    ignoredImports: LeetCodeIgnoredImport[];
+    summary: LeetCodeSyncSummary;
+    error?: string;
+}
+interface LeetCodeActivityResult {
+    data: LeetCodeActivityFunctionResponse | null;
+    error: string | null;
+}
+declare function normalizeLeetCodeUsername(input: string): string;
+declare function sanitizeLeetCodeActivityError(error: unknown): string;
+declare function toLeetCodeConnection(row: LeetCodeConnectionRow): LeetCodeConnection;
+declare function toLeetCodeSubmission(row: LeetCodeSubmissionRow): LeetCodeSubmission;
+declare function toLeetCodeIgnoredImport(row: LeetCodeIgnoredImportRow): LeetCodeIgnoredImport;
+interface CreateLeetCodeActivityDataOptions {
+    /** Platform Supabase client; null falls back to the no-op guard shapes. */
+    supabase: SupabaseClient | null;
+    /** Per-operation timeout for table reads (F-9). */
+    timeoutMs?: number;
+    /** Timeout for the sync-leetcode-activity Edge Function invoke. */
+    invokeTimeoutMs?: number;
+}
+interface LeetCodeActivityData {
+    fetchLeetCodeConnection(userId: string): Promise<{
+        data: LeetCodeConnection | null;
+        error: unknown;
+    }>;
+    fetchRecentLeetCodeSubmissions(userId: string, limit?: number): Promise<{
+        data: LeetCodeSubmission[] | null;
+        error: unknown;
+    }>;
+    fetchLeetCodeIgnoredImports(userId: string): Promise<{
+        data: LeetCodeIgnoredImport[] | null;
+        error: unknown;
+    }>;
+    connectLeetCodeActivity(username: string): Promise<LeetCodeActivityResult>;
+    syncLeetCodeActivity(force?: boolean): Promise<LeetCodeActivityResult>;
+    disconnectLeetCodeActivity(): Promise<LeetCodeActivityResult>;
+    markLeetCodeImportImported(submissionDbId: string, problemId: string): Promise<LeetCodeActivityResult>;
+    markLeetCodeImportLinkedExisting(submissionDbId: string, problemId: string): Promise<LeetCodeActivityResult>;
+    ignoreLeetCodeImport(submissionDbId: string): Promise<LeetCodeActivityResult>;
+    restoreIgnoredLeetCodeImport(titleSlug: string): Promise<LeetCodeActivityResult>;
+    markLeetCodeSubmissionRated(submissionDbId: string, problemId: string): Promise<LeetCodeActivityResult>;
+}
+declare function createLeetCodeActivityData(options: CreateLeetCodeActivityDataOptions): LeetCodeActivityData;
+
+interface BuildPendingLeetCodeImportsArgs {
+    submissions: LeetCodeSubmission[];
+    problems: Problem[];
+    ignoredImports: LeetCodeIgnoredImport[];
+    reviewEvents?: ReviewEvent[];
+    today?: string;
+}
+interface BuildProblemOptions {
+    today?: string;
+    now?: string;
+    autoExpired?: boolean;
+}
+declare function buildPendingLeetCodeImports({ submissions, problems, ignoredImports, today, }: BuildPendingLeetCodeImportsArgs): PendingLeetCodeImport[];
+declare function buildTodayLeetCodeItems({ submissions, problems, ignoredImports, reviewEvents, today, }: BuildPendingLeetCodeImportsArgs): TodayLeetCodeItem[];
+declare function buildProblemFromLeetCodeImport(item: PendingLeetCodeImport, confidence: Confidence, options?: BuildProblemOptions): Problem;
+
+/**
+ * Get all available lists with computed counts.
+ */
+declare function getListSummaries(existingNumbers: Set<number>): ListSummary[];
+/**
+ * Get the problems to add for a specific list.
+ * Returns only problems NOT already in the user's library.
+ * Each problem gets its pattern from PATTERN_MAP.
+ */
+declare function getListProblems(listId: string, existingNumbers: Set<number>): {
+    lcProblems: LeetCodeProblem[];
+    patternMap: Map<number, string[]>;
+};
+declare function getPatternsForProblemNumber(problemNumber: number | null | undefined): string[];
+
+type TodayLeetCodeCompletionAction = "imported" | "linked_existing" | "rated";
+interface LeetCodeCompletionIdentity {
+    submissionDbId?: string | null;
+    leetcodeSubmissionId?: string | null;
+    titleSlug?: string | null;
+    leetcodeNumber?: number | null;
+    problemId?: string | null;
+}
+interface TodayLeetCodeCompletion extends Required<Pick<LeetCodeCompletionIdentity, "submissionDbId">> {
+    key: string;
+    date: string;
+    leetcodeSubmissionId: string | null;
+    titleSlug: string | null;
+    leetcodeNumber: number | null;
+    problemId: string;
+    action: TodayLeetCodeCompletionAction;
+    completedAt: string;
+}
+declare function buildTodayLeetCodeCompletionsStorageKey(today?: string): string;
+declare function buildLeetCodeCompletionKey(identity: LeetCodeCompletionIdentity): string;
+declare function buildLeetCodeCompletionKeys(identity: LeetCodeCompletionIdentity): string[];
+/** Pure raw-storage-value → records parse; platforms feed it their own reads. */
+declare function parseTodayLeetCodeCompletions(raw: string | null, today?: string): TodayLeetCodeCompletion[];
+/** Pure records → raw storage value; keeps only the given day's records. */
+declare function serializeTodayLeetCodeCompletions(completions: TodayLeetCodeCompletion[], today?: string): string;
+declare function loadTodayLeetCodeCompletions(storage: StorageAdapter, today?: string): Promise<TodayLeetCodeCompletion[]>;
+declare function saveTodayLeetCodeCompletions(storage: StorageAdapter, completions: TodayLeetCodeCompletion[], today?: string, hooks?: CoreHooks): Promise<void>;
+declare function mergeTodayLeetCodeCompletion(completions: TodayLeetCodeCompletion[], completion: LeetCodeCompletionIdentity & {
+    submissionDbId: string;
+    problemId: string;
+    action: TodayLeetCodeCompletionAction;
+    completedAt?: string;
+}, today?: string, now?: string): TodayLeetCodeCompletion[];
+declare function addTodayLeetCodeCompletion(storage: StorageAdapter, completion: LeetCodeCompletionIdentity & {
+    submissionDbId: string;
+    problemId: string;
+    action: TodayLeetCodeCompletionAction;
+}, today?: string): Promise<TodayLeetCodeCompletion[]>;
+declare function isLeetCodeSubmissionCompletedToday(identity: LeetCodeCompletionIdentity, completions: TodayLeetCodeCompletion[]): boolean;
+declare function buildLeetCodeSubmissionsWithCompletions(submissions: LeetCodeSubmission[], completions: TodayLeetCodeCompletion[]): LeetCodeSubmission[];
+
+interface RateLeetCodeReviewLocallyFirstParams {
+    submissionDbId: string;
+    problemId: string;
+    confidence: Confidence;
+    completionSource?: LeetCodeCompletionIdentity;
+    onReview: (problemId: string, confidence: Confidence, options?: {
+        replaceSameDayReviewEvent?: boolean;
+    }) => void;
+    markRated: (submissionDbId: string, problemId: string) => Promise<LeetCodeActivityResult>;
+    onLocalReviewRecorded?: (source: LeetCodeCompletionIdentity & {
+        submissionDbId: string;
+    }, problemId: string) => void;
+    onError?: (error: string) => void;
+}
+declare function rateLeetCodeReviewLocallyFirst({ submissionDbId, problemId, confidence, completionSource, onReview, markRated, onLocalReviewRecorded, onError, }: RateLeetCodeReviewLocallyFirstParams): Promise<LeetCodeActivityResult>;
+
+interface ResolveTodayLeetCodeStateArgs {
+    problems: Problem[];
+    reviewEvents: ReviewEvent[];
+    leetcodeSubmissions: LeetCodeSubmission[];
+    ignoredImports: LeetCodeIgnoredImport[];
+    todayCompletions: TodayLeetCodeCompletion[];
+    today: string;
+}
+interface TodayLeetCodeResolvedState {
+    fromLeetCodeItems: TodayLeetCodeItem[];
+    doneTodayLeetCodeSubmissions: LeetCodeSubmission[];
+    effectiveCompletions: TodayLeetCodeCompletion[];
+}
+type CompletionInput = LeetCodeCompletionIdentity & {
+    submissionDbId: string;
+    problemId: string;
+    action: TodayLeetCodeCompletion["action"];
+    completedAt?: string;
+};
+declare function buildReviewedTodayLeetCodeCompletions({ submissions, problems, reviewEvents, today, }: {
+    submissions: LeetCodeSubmission[];
+    problems: Problem[];
+    reviewEvents: ReviewEvent[];
+    today: string;
+}): CompletionInput[];
+declare function mergeTodayLeetCodeCompletions(completions: TodayLeetCodeCompletion[], completionInputs: CompletionInput[], today: string): TodayLeetCodeCompletion[];
+declare function resolveTodayLeetCodeState({ problems, reviewEvents, leetcodeSubmissions, ignoredImports, todayCompletions, today, }: ResolveTodayLeetCodeStateArgs): TodayLeetCodeResolvedState;
+
+declare const LEETCODE_PROBLEMS: LeetCodeProblem[];
+
+
+declare function searchProblems(query: string, limit?: number): LeetCodeProblem[];
+declare function getProblemByNumber(num: number): LeetCodeProblem | null;
+declare function buildLeetCodeUrl(slug: string): string;
+
+/**
+ * @patternbank/core — shared domain logic for PatternBank web and mobile.
+ *
+ * Pure logic only: no UI, no Tailwind classes, no import-time side effects.
+ * Platform concerns (storage, Supabase client, analytics) are injected via
+ * adapters — see storage/adapter.ts and supabase/data.ts as they land.
+ */
+
+/** Placeholder export proving the workspace wiring; replaced as modules extract. */
+declare const CORE_PACKAGE_NAME = "@patternbank/core";
+
+export { type BackupData, CLOUD_OPERATION_TIMEOUT_MS, CORE_PACKAGE_NAME, CORE_PATTERNS, type CloudData, type CloudPreferences, type Confidence, type CoreHooks, type CorePreferences, type CreateCloudDataOptions, type CreateLeetCodeActivityDataOptions, DATA_RESET_KEY, DEFAULT_PREFERENCES, DIFFICULTIES, type DataReset, type DataResetRow, type Difficulty, type DoneTodayFeedItem, EXTRA_PATTERNS, type ExitingTodayLeetCodeItem, FIVE_STAR_GRADUATION_INTERVALS, FULL_SYNC_TIMEOUT_MS, type FullSyncCloud, type FullSyncDeps, type FullSyncFailure, type FullSyncLocalState, type FullSyncResult, type FullSyncSuccess, INTERVALS, LEETCODE_ACTIVITY_TIMEOUT_MS, LEETCODE_PROBLEMS, LEETCODE_RECENT_ACTIVITY_LIMIT, type LeetCodeActivityData, type LeetCodeActivityFunctionResponse, type LeetCodeActivityResult, type LeetCodeCompletionIdentity, type LeetCodeConnection, type LeetCodeConnectionRow, type LeetCodeIgnoredImport, type LeetCodeIgnoredImportRow, type LeetCodeProblem, type LeetCodeSubmission, type LeetCodeSubmissionRow, type LeetCodeSubmissionStatus, type LeetCodeSyncStatus, type LeetCodeSyncSummary, type ListSummary, type MergePreferencesResult, type MergeProblemTombstonesResult, type MergeProblemsResult, type MergeReviewEventsOptions, type MergeReviewEventsResult, type MergeReviewLogResult, PREFERENCES_KEY, PROBLEM_TOMBSTONES_KEY, PROGRESS_CONFIDENCE_TINTS, PROGRESS_EMPTY_CONFIDENCE_TINT, PROGRESS_HEATMAP_CONFIDENCE_TINTS, type PatternColor, type PendingLeetCodeImport, type Problem, type ProblemList, type ProblemRow, type ProblemTombstone, type ProblemTombstoneRow, type ProgressConfidenceTint, type ProjectionDay, type ProjectionDistribution, type ProjectionSeriesOptions, type ProjectionSnapshot, type PruneOldEventsOptions, type PruneOldEventsResult, REVIEW_EVENTS_KEY, REVIEW_EVENTS_PRUNED_BEFORE_KEY, REVIEW_LOG_KEY, type RateLeetCodeReviewLocallyFirstParams, type ReviewEvent, type ReviewEventRow, type ReviewHistoryEntry, type ReviewLogEntry, STORAGE_KEY, type SolvedOnLeetCodeTodayIndex, type StorageAdapter, type SyncStatus, SyncTimeoutError, type TodayActivityFeedItem, type TodayLeetCodeCompletion, type TodayLeetCodeCompletionAction, type TodayLeetCodeItem, type TodayLeetCodeResolvedState, type TodayReviewState, addDays, addTodayLeetCodeCompletion, buildDoneTodayFeedItems, buildLeetCodeCompletionKey, buildLeetCodeCompletionKeys, buildLeetCodeSubmissionsWithCompletions, buildLeetCodeUrl, buildNewProblems, buildPendingLeetCodeImports, buildProblemFromLeetCodeImport, buildRemovedTodayLeetCodeItems, buildReviewCountMap, buildReviewedProblem, buildReviewedTodayLeetCodeCompletions, buildSolvedOnLeetCodeTodayIndex, buildTodayActivityFeedItems, buildTodayLeetCodeCompletionsStorageKey, buildTodayLeetCodeItemKey, buildTodayLeetCodeItems, buildTodayReviewState, calculateLongestStreak, calculateStreak, compareDataResets, computeNextReviewDate, computeReviewProgress, countReviewedToday, createCloudData, createLeetCodeActivityData, dataResetTime, dateOnlyToUtcMs, deduplicateProblems, filterExistingProblems, filterProblemsAfterDataReset, filterReviewEventsAfterDataReset, filterReviewEventsToProblems, filterReviewLogAfterDataReset, filterTombstonedProblems, filterTombstonesAfterDataReset, formatDisplayDate, formatLocalDate, formatRelativeDate, generateId, getConfidenceDistribution, getDefaultFiveStarStreak, getFiveStarGraduationIntervalDays, getIntervalDays, getListProblems, getListSummaries, getNextFiveStarStreak, getPatternsForProblemNumber, getPreviousFiveStarStreak, getProblemByNumber, getProgressConfidenceTint, getProgressHeatmapTint, getReviewIntervalDays, getTopPatterns, getVisiblePatterns, getWeekStart, groupEventsByWeek, interleaveByDifficulty, isLeetCodeSubmissionCompletedToday, isLikelyOfflineError, isSyncTimeoutError, loadTodayLeetCodeCompletions, mergeImportedProblems, mergePreferences, mergeProblemTombstones, mergeProblems, mergeReviewEvents, mergeReviewLog, mergeTodayLeetCodeCompletion, mergeTodayLeetCodeCompletions, newestDataReset, normalizeLeetCodeUsername, parseDateOnly, parseTodayLeetCodeCompletions, performFullSync, preferencesEqual, prioritizeProblems, pruneOldEvents, rateLeetCodeReviewLocallyFirst, resolveTodayLeetCodeState, reviewDedupeKey, reviewEventKey, reviewEventsMatch, reviewLogFromEvents, sanitizeLeetCodeActivityError, saveTodayLeetCodeCompletions, searchProblems, serializeTodayLeetCodeCompletions, simulateProjection, simulateProjectionSeries, timestampMs, toCamelCase, toCloudPreferences, toLeetCodeConnection, toLeetCodeIgnoredImport, toLeetCodeSubmission, toSnakeCase, todayStr, utcToLocalDateStr, withCloudOperationTimeout, withTimeout };