@contractspec/module.learning-journey 1.44.0

package/dist/engines/srs.js

@@ -0,0 +1,219 @@
+//#region src/engines/srs.ts
+const DEFAULT_SRS_CONFIG = {
+	learningSteps: [1, 10],
+	graduatingInterval: 1,
+	easyInterval: 4,
+	relearningSteps: [10],
+	minEaseFactor: 1.3,
+	maxInterval: 365,
+	intervalModifier: 1,
+	newIntervalModifier: .5,
+	hardIntervalModifier: 1.2,
+	easyBonus: 1.3
+};
+var SRSEngine = class {
+	config;
+	constructor(config = {}) {
+		this.config = {
+			...DEFAULT_SRS_CONFIG,
+			...config
+		};
+	}
+	/**
+	* Calculate the next review state based on rating.
+	*/
+	calculateNextReview(state, rating, now = /* @__PURE__ */ new Date()) {
+		if (!state.isGraduated && !state.isRelearning) return this.handleLearningCard(state, rating, now);
+		if (state.isRelearning) return this.handleRelearningCard(state, rating, now);
+		return this.handleReviewCard(state, rating, now);
+	}
+	/**
+	* Get initial SRS state for a new card.
+	*/
+	getInitialState() {
+		return {
+			interval: 0,
+			easeFactor: 2.5,
+			repetitions: 0,
+			learningStep: 0,
+			isGraduated: false,
+			isRelearning: false,
+			lapses: 0
+		};
+	}
+	/**
+	* Check if a card is due for review.
+	*/
+	isDue(nextReviewAt, now = /* @__PURE__ */ new Date()) {
+		return nextReviewAt <= now;
+	}
+	/**
+	* Calculate overdue days (negative if not yet due).
+	*/
+	getOverdueDays(nextReviewAt, now = /* @__PURE__ */ new Date()) {
+		const diff = now.getTime() - nextReviewAt.getTime();
+		return Math.floor(diff / (1e3 * 60 * 60 * 24));
+	}
+	/**
+	* Handle learning phase (new cards).
+	*/
+	handleLearningCard(state, rating, now) {
+		const steps = this.config.learningSteps;
+		let newStep = state.learningStep;
+		let isGraduated = false;
+		let interval = 0;
+		let nextReviewAt;
+		switch (rating) {
+			case "AGAIN":
+				newStep = 0;
+				interval = steps[0] ?? 1;
+				nextReviewAt = this.addMinutes(now, interval);
+				break;
+			case "HARD":
+				interval = steps[newStep] ?? steps[0] ?? 1;
+				nextReviewAt = this.addMinutes(now, interval);
+				break;
+			case "GOOD":
+				newStep++;
+				if (newStep >= steps.length) {
+					isGraduated = true;
+					interval = this.config.graduatingInterval;
+					nextReviewAt = this.addDays(now, interval);
+				} else {
+					interval = steps[newStep] ?? 10;
+					nextReviewAt = this.addMinutes(now, interval);
+				}
+				break;
+			case "EASY":
+				isGraduated = true;
+				interval = this.config.easyInterval;
+				nextReviewAt = this.addDays(now, interval);
+				break;
+		}
+		return {
+			interval: isGraduated ? interval : 0,
+			easeFactor: state.easeFactor,
+			repetitions: isGraduated ? 1 : 0,
+			nextReviewAt,
+			learningStep: newStep,
+			isGraduated,
+			isRelearning: false,
+			lapses: state.lapses
+		};
+	}
+	/**
+	* Handle relearning phase (lapsed cards).
+	*/
+	handleRelearningCard(state, rating, now) {
+		const steps = this.config.relearningSteps;
+		let newStep = state.learningStep;
+		let isRelearning = true;
+		let interval = 0;
+		let nextReviewAt;
+		switch (rating) {
+			case "AGAIN":
+				newStep = 0;
+				interval = steps[0] ?? 10;
+				nextReviewAt = this.addMinutes(now, interval);
+				break;
+			case "HARD":
+				interval = steps[newStep] ?? steps[0] ?? 10;
+				nextReviewAt = this.addMinutes(now, interval);
+				break;
+			case "GOOD":
+				newStep++;
+				if (newStep >= steps.length) {
+					isRelearning = false;
+					interval = Math.max(1, Math.floor(state.interval * this.config.newIntervalModifier));
+					nextReviewAt = this.addDays(now, interval);
+				} else {
+					interval = steps[newStep] ?? 10;
+					nextReviewAt = this.addMinutes(now, interval);
+				}
+				break;
+			case "EASY":
+				isRelearning = false;
+				interval = Math.max(1, Math.floor(state.interval * this.config.newIntervalModifier * 1.5));
+				nextReviewAt = this.addDays(now, interval);
+				break;
+		}
+		return {
+			interval: isRelearning ? state.interval : interval,
+			easeFactor: state.easeFactor,
+			repetitions: isRelearning ? state.repetitions : state.repetitions + 1,
+			nextReviewAt,
+			learningStep: newStep,
+			isGraduated: true,
+			isRelearning,
+			lapses: state.lapses
+		};
+	}
+	/**
+	* Handle review phase (graduated cards).
+	*/
+	handleReviewCard(state, rating, now) {
+		let newInterval;
+		let newEaseFactor = state.easeFactor;
+		let repetitions = state.repetitions;
+		let isRelearning = false;
+		let learningStep = 0;
+		let lapses = state.lapses;
+		switch (rating) {
+			case "AGAIN":
+				lapses++;
+				isRelearning = true;
+				learningStep = 0;
+				newEaseFactor = Math.max(this.config.minEaseFactor, newEaseFactor - .2);
+				newInterval = state.interval;
+				return {
+					interval: newInterval,
+					easeFactor: newEaseFactor,
+					repetitions,
+					nextReviewAt: this.addMinutes(now, this.config.relearningSteps[0] ?? 10),
+					learningStep,
+					isGraduated: true,
+					isRelearning: true,
+					lapses
+				};
+			case "HARD":
+				newEaseFactor = Math.max(this.config.minEaseFactor, newEaseFactor - .15);
+				newInterval = Math.max(state.interval + 1, state.interval * this.config.hardIntervalModifier);
+				break;
+			case "GOOD":
+				newInterval = state.interval * newEaseFactor * this.config.intervalModifier;
+				repetitions++;
+				break;
+			case "EASY":
+				newEaseFactor = newEaseFactor + .15;
+				newInterval = state.interval * newEaseFactor * this.config.easyBonus * this.config.intervalModifier;
+				repetitions++;
+				break;
+		}
+		newInterval = Math.min(Math.round(newInterval), this.config.maxInterval);
+		newInterval = Math.max(1, newInterval);
+		return {
+			interval: newInterval,
+			easeFactor: newEaseFactor,
+			repetitions,
+			nextReviewAt: this.addDays(now, newInterval),
+			learningStep,
+			isGraduated: true,
+			isRelearning,
+			lapses
+		};
+	}
+	addMinutes(date, minutes) {
+		return new Date(date.getTime() + minutes * 60 * 1e3);
+	}
+	addDays(date, days) {
+		return new Date(date.getTime() + days * 24 * 60 * 60 * 1e3);
+	}
+};
+/**
+* Default SRS engine instance.
+*/
+const srsEngine = new SRSEngine();
+
+//#endregion
+export { DEFAULT_SRS_CONFIG, SRSEngine, srsEngine };
+//# sourceMappingURL=srs.js.map

package/dist/engines/srs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"srs.js","names":["DEFAULT_SRS_CONFIG: SRSConfig","nextReviewAt: Date","newInterval: number"],"sources":["../../src/engines/srs.ts"],"sourcesContent":["/**\n * Spaced Repetition System (SRS) Engine\n *\n * Implements the SM-2 algorithm variant for optimal flashcard scheduling.\n *\n * The algorithm calculates the optimal time to review a card based on:\n * - User's rating of recall difficulty (again, hard, good, easy)\n * - Current interval between reviews\n * - Ease factor (how easy the card is for this user)\n * - Number of successful repetitions\n */\n\n// ============ Types ============\n\nexport type CardRating = 'AGAIN' | 'HARD' | 'GOOD' | 'EASY';\n\nexport interface SRSState {\n  /** Current interval in days */\n  interval: number;\n  /** Ease factor (typically 1.3 to 2.5+) */\n  easeFactor: number;\n  /** Number of successful repetitions */\n  repetitions: number;\n  /** Current learning step (for new cards) */\n  learningStep: number;\n  /** Whether card has graduated to review phase */\n  isGraduated: boolean;\n  /** Whether card is being relearned after a lapse */\n  isRelearning: boolean;\n  /** Number of times card was forgotten */\n  lapses: number;\n}\n\nexport interface ReviewResult {\n  /** New interval in days */\n  interval: number;\n  /** New ease factor */\n  easeFactor: number;\n  /** New repetition count */\n  repetitions: number;\n  /** Next review date */\n  nextReviewAt: Date;\n  /** New learning step */\n  learningStep: number;\n  /** Whether card has graduated */\n  isGraduated: boolean;\n  /** Whether card is being relearned */\n  isRelearning: boolean;\n  /** Updated lapse count */\n  lapses: number;\n}\n\nexport interface SRSConfig {\n  /** Learning steps in minutes [1, 10] = 1 min, 10 min */\n  learningSteps: number[];\n  /** Graduating interval in days */\n  graduatingInterval: number;\n  /** Easy interval (for easy button on new cards) */\n  easyInterval: number;\n  /** Relearning steps in minutes */\n  relearningSteps: number[];\n  /** Minimum ease factor */\n  minEaseFactor: number;\n  /** Maximum interval in days */\n  maxInterval: number;\n  /** Interval modifier (1.0 = 100%) */\n  intervalModifier: number;\n  /** New cards interval modifier */\n  newIntervalModifier: number;\n  /** Hard interval modifier */\n  hardIntervalModifier: number;\n  /** Easy bonus modifier */\n  easyBonus: number;\n}\n\n// ============ Default Configuration ============\n\nexport const DEFAULT_SRS_CONFIG: SRSConfig = {\n  learningSteps: [1, 10], // 1 minute, 10 minutes\n  graduatingInterval: 1, // 1 day\n  easyInterval: 4, // 4 days\n  relearningSteps: [10], // 10 minutes\n  minEaseFactor: 1.3,\n  maxInterval: 365, // 1 year\n  intervalModifier: 1.0,\n  newIntervalModifier: 0.5,\n  hardIntervalModifier: 1.2,\n  easyBonus: 1.3,\n};\n\n// ============ SRS Engine ============\n\nexport class SRSEngine {\n  private config: SRSConfig;\n\n  constructor(config: Partial<SRSConfig> = {}) {\n    this.config = { ...DEFAULT_SRS_CONFIG, ...config };\n  }\n\n  /**\n   * Calculate the next review state based on rating.\n   */\n  calculateNextReview(\n    state: SRSState,\n    rating: CardRating,\n    now: Date = new Date()\n  ): ReviewResult {\n    // Handle new/learning cards\n    if (!state.isGraduated && !state.isRelearning) {\n      return this.handleLearningCard(state, rating, now);\n    }\n\n    // Handle relearning cards\n    if (state.isRelearning) {\n      return this.handleRelearningCard(state, rating, now);\n    }\n\n    // Handle graduated cards in review\n    return this.handleReviewCard(state, rating, now);\n  }\n\n  /**\n   * Get initial SRS state for a new card.\n   */\n  getInitialState(): SRSState {\n    return {\n      interval: 0,\n      easeFactor: 2.5,\n      repetitions: 0,\n      learningStep: 0,\n      isGraduated: false,\n      isRelearning: false,\n      lapses: 0,\n    };\n  }\n\n  /**\n   * Check if a card is due for review.\n   */\n  isDue(nextReviewAt: Date, now: Date = new Date()): boolean {\n    return nextReviewAt <= now;\n  }\n\n  /**\n   * Calculate overdue days (negative if not yet due).\n   */\n  getOverdueDays(nextReviewAt: Date, now: Date = new Date()): number {\n    const diff = now.getTime() - nextReviewAt.getTime();\n    return Math.floor(diff / (1000 * 60 * 60 * 24));\n  }\n\n  /**\n   * Handle learning phase (new cards).\n   */\n  private handleLearningCard(\n    state: SRSState,\n    rating: CardRating,\n    now: Date\n  ): ReviewResult {\n    const steps = this.config.learningSteps;\n    let newStep = state.learningStep;\n    let isGraduated = false;\n    let interval = 0;\n    let nextReviewAt: Date;\n\n    switch (rating) {\n      case 'AGAIN':\n        // Reset to first step\n        newStep = 0;\n        interval = steps[0] ?? 1;\n        nextReviewAt = this.addMinutes(now, interval);\n        break;\n\n      case 'HARD':\n        // Stay at current step (or repeat first step)\n        interval = steps[newStep] ?? steps[0] ?? 1;\n        nextReviewAt = this.addMinutes(now, interval);\n        break;\n\n      case 'GOOD':\n        // Move to next step\n        newStep++;\n        if (newStep >= steps.length) {\n          // Graduate the card\n          isGraduated = true;\n          interval = this.config.graduatingInterval;\n          nextReviewAt = this.addDays(now, interval);\n        } else {\n          interval = steps[newStep] ?? 10;\n          nextReviewAt = this.addMinutes(now, interval);\n        }\n        break;\n\n      case 'EASY':\n        // Graduate immediately with easy interval\n        isGraduated = true;\n        interval = this.config.easyInterval;\n        nextReviewAt = this.addDays(now, interval);\n        break;\n    }\n\n    return {\n      interval: isGraduated ? interval : 0,\n      easeFactor: state.easeFactor,\n      repetitions: isGraduated ? 1 : 0,\n      nextReviewAt,\n      learningStep: newStep,\n      isGraduated,\n      isRelearning: false,\n      lapses: state.lapses,\n    };\n  }\n\n  /**\n   * Handle relearning phase (lapsed cards).\n   */\n  private handleRelearningCard(\n    state: SRSState,\n    rating: CardRating,\n    now: Date\n  ): ReviewResult {\n    const steps = this.config.relearningSteps;\n    let newStep = state.learningStep;\n    let isRelearning = true;\n    let interval = 0;\n    let nextReviewAt: Date;\n\n    switch (rating) {\n      case 'AGAIN':\n        // Reset to first relearning step\n        newStep = 0;\n        interval = steps[0] ?? 10;\n        nextReviewAt = this.addMinutes(now, interval);\n        break;\n\n      case 'HARD':\n        // Stay at current step\n        interval = steps[newStep] ?? steps[0] ?? 10;\n        nextReviewAt = this.addMinutes(now, interval);\n        break;\n\n      case 'GOOD':\n        // Move to next step or graduate back to review\n        newStep++;\n        if (newStep >= steps.length) {\n          isRelearning = false;\n          // Use reduced interval after lapse\n          interval = Math.max(\n            1,\n            Math.floor(state.interval * this.config.newIntervalModifier)\n          );\n          nextReviewAt = this.addDays(now, interval);\n        } else {\n          interval = steps[newStep] ?? 10;\n          nextReviewAt = this.addMinutes(now, interval);\n        }\n        break;\n\n      case 'EASY':\n        // Graduate immediately with slightly longer interval\n        isRelearning = false;\n        interval = Math.max(\n          1,\n          Math.floor(state.interval * this.config.newIntervalModifier * 1.5)\n        );\n        nextReviewAt = this.addDays(now, interval);\n        break;\n    }\n\n    return {\n      interval: isRelearning ? state.interval : interval,\n      easeFactor: state.easeFactor,\n      repetitions: isRelearning ? state.repetitions : state.repetitions + 1,\n      nextReviewAt,\n      learningStep: newStep,\n      isGraduated: true,\n      isRelearning,\n      lapses: state.lapses,\n    };\n  }\n\n  /**\n   * Handle review phase (graduated cards).\n   */\n  private handleReviewCard(\n    state: SRSState,\n    rating: CardRating,\n    now: Date\n  ): ReviewResult {\n    let newInterval: number;\n    let newEaseFactor = state.easeFactor;\n    let repetitions = state.repetitions;\n    let isRelearning = false;\n    let learningStep = 0;\n    let lapses = state.lapses;\n\n    switch (rating) {\n      case 'AGAIN':\n        // Card lapsed - move to relearning\n        lapses++;\n        isRelearning = true;\n        learningStep = 0;\n        newEaseFactor = Math.max(\n          this.config.minEaseFactor,\n          newEaseFactor - 0.2\n        );\n        newInterval = state.interval; // Keep old interval for reference\n        return {\n          interval: newInterval,\n          easeFactor: newEaseFactor,\n          repetitions,\n          nextReviewAt: this.addMinutes(\n            now,\n            this.config.relearningSteps[0] ?? 10\n          ),\n          learningStep,\n          isGraduated: true,\n          isRelearning: true,\n          lapses,\n        };\n\n      case 'HARD':\n        // Reduce interval slightly, reduce ease\n        newEaseFactor = Math.max(\n          this.config.minEaseFactor,\n          newEaseFactor - 0.15\n        );\n        newInterval = Math.max(\n          state.interval + 1,\n          state.interval * this.config.hardIntervalModifier\n        );\n        break;\n\n      case 'GOOD':\n        // Standard interval increase\n        newInterval =\n          state.interval * newEaseFactor * this.config.intervalModifier;\n        repetitions++;\n        break;\n\n      case 'EASY':\n        // Larger interval increase, increase ease\n        newEaseFactor = newEaseFactor + 0.15;\n        newInterval =\n          state.interval *\n          newEaseFactor *\n          this.config.easyBonus *\n          this.config.intervalModifier;\n        repetitions++;\n        break;\n    }\n\n    // Apply bounds\n    newInterval = Math.min(Math.round(newInterval), this.config.maxInterval);\n    newInterval = Math.max(1, newInterval);\n\n    return {\n      interval: newInterval,\n      easeFactor: newEaseFactor,\n      repetitions,\n      nextReviewAt: this.addDays(now, newInterval),\n      learningStep,\n      isGraduated: true,\n      isRelearning,\n      lapses,\n    };\n  }\n\n  // ============ Helpers ============\n\n  private addMinutes(date: Date, minutes: number): Date {\n    return new Date(date.getTime() + minutes * 60 * 1000);\n  }\n\n  private addDays(date: Date, days: number): Date {\n    return new Date(date.getTime() + days * 24 * 60 * 60 * 1000);\n  }\n}\n\n/**\n * Default SRS engine instance.\n */\nexport const srsEngine = new SRSEngine();\n"],"mappings":"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"}

package/dist/engines/streak.d.ts

@@ -0,0 +1,100 @@
+//#region src/engines/streak.d.ts
+/**
+ * Streak Tracking Engine
+ *
+ * Manages daily learning streaks with timezone support and freeze protection.
+ */
+interface StreakState {
+  /** Current streak days */
+  currentStreak: number;
+  /** Longest streak ever */
+  longestStreak: number;
+  /** Last activity timestamp */
+  lastActivityAt: Date | null;
+  /** Last activity date (YYYY-MM-DD) */
+  lastActivityDate: string | null;
+  /** Available streak freezes */
+  freezesRemaining: number;
+  /** When a freeze was last used */
+  freezeUsedAt: Date | null;
+}
+interface StreakUpdateResult {
+  /** Updated streak state */
+  state: StreakState;
+  /** Whether streak was maintained */
+  streakMaintained: boolean;
+  /** Whether streak was lost */
+  streakLost: boolean;
+  /** Whether a freeze was used */
+  freezeUsed: boolean;
+  /** Whether this activity started a new streak */
+  newStreak: boolean;
+  /** Days missed (if streak was lost) */
+  daysMissed: number;
+}
+interface StreakConfig {
+  /** Timezone for the user */
+  timezone: string;
+  /** How many streak freezes to give per month */
+  freezesPerMonth: number;
+  /** Maximum freezes that can be accumulated */
+  maxFreezes: number;
+  /** Grace period in hours after midnight */
+  gracePeriodHours: number;
+}
+declare const DEFAULT_STREAK_CONFIG: StreakConfig;
+declare class StreakEngine {
+  private config;
+  constructor(config?: Partial<StreakConfig>);
+  /**
+   * Update streak based on new activity.
+   */
+  update(state: StreakState, now?: Date): StreakUpdateResult;
+  /**
+   * Check streak status without recording activity.
+   */
+  checkStatus(state: StreakState, now?: Date): {
+    isActive: boolean;
+    willExpireAt: Date | null;
+    canUseFreeze: boolean;
+    daysUntilExpiry: number;
+  };
+  /**
+   * Manually use a freeze to protect streak.
+   */
+  useFreeze(state: StreakState, now?: Date): StreakState | null;
+  /**
+   * Award monthly freezes.
+   */
+  awardMonthlyFreezes(state: StreakState): StreakState;
+  /**
+   * Get initial streak state.
+   */
+  getInitialState(): StreakState;
+  /**
+   * Calculate streak milestones.
+   */
+  getMilestones(currentStreak: number): {
+    achieved: number[];
+    next: number | null;
+  };
+  /**
+   * Get date string in YYYY-MM-DD format.
+   */
+  private getDateString;
+  /**
+   * Get number of days between two date strings.
+   */
+  private getDaysBetween;
+  /**
+   * Add days to a date.
+   */
+  private addDays;
+}
+/**
+ * Default streak engine instance.
+ */
+declare const streakEngine: StreakEngine;
+//#endregion
+export { DEFAULT_STREAK_CONFIG, StreakConfig, StreakEngine, StreakState, StreakUpdateResult, streakEngine };
+//# sourceMappingURL=streak.d.ts.map

package/dist/engines/streak.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streak.d.ts","names":[],"sources":["../../src/engines/streak.ts"],"sourcesContent":[],"mappings":";;AAQA;AAeA;AAeA;AAaA;AASa,UApDI,WAAA,CAoDQ;EAGK;EAAR,aAAA,EAAA,MAAA;EAON;EAAkB,aAAA,EAAA,MAAA;EAAoB;EAmF3C,cAAA,EA3IO,IA2IP,GAAA,IAAA;EACF;EAGS,gBAAA,EAAA,MAAA,GAAA,IAAA;EAwDC;EAAkB,gBAAA,EAAA,MAAA;EAAoB;EAe5B,YAAA,EAhNb,IAgNa,GAAA,IAAA;;AAaR,UA1NJ,kBAAA,CA0NI;EAAW;EA0DnB,KAAA,EAlRJ,WAkRqC;;;;;;;;;;;;UArQ7B,YAAA;;;;;;;;;;cAaJ,uBAAuB;cASvB,YAAA;;uBAGS,QAAQ;;;;gBAOd,mBAAkB,OAAoB;;;;qBAmF3C,mBACF;;kBAGS;;;;;;;mBAwDC,mBAAkB,OAAoB;;;;6BAe5B,cAAc;;;;qBAatB;;;;;;;;;;;;;;;;;;;;;;;;cA0DR,cAAY"}

package/dist/engines/streak.js

@@ -0,0 +1,194 @@
+//#region src/engines/streak.ts
+const DEFAULT_STREAK_CONFIG = {
+	timezone: "UTC",
+	freezesPerMonth: 2,
+	maxFreezes: 5,
+	gracePeriodHours: 4
+};
+var StreakEngine = class {
+	config;
+	constructor(config = {}) {
+		this.config = {
+			...DEFAULT_STREAK_CONFIG,
+			...config
+		};
+	}
+	/**
+	* Update streak based on new activity.
+	*/
+	update(state, now = /* @__PURE__ */ new Date()) {
+		const todayDate = this.getDateString(now);
+		const result = {
+			state: { ...state },
+			streakMaintained: false,
+			streakLost: false,
+			freezeUsed: false,
+			newStreak: false,
+			daysMissed: 0
+		};
+		if (!state.lastActivityDate) {
+			result.state.currentStreak = 1;
+			result.state.longestStreak = Math.max(1, state.longestStreak);
+			result.state.lastActivityAt = now;
+			result.state.lastActivityDate = todayDate;
+			result.newStreak = true;
+			result.streakMaintained = true;
+			return result;
+		}
+		if (state.lastActivityDate === todayDate) {
+			result.state.lastActivityAt = now;
+			result.streakMaintained = true;
+			return result;
+		}
+		const daysSinceActivity = this.getDaysBetween(state.lastActivityDate, todayDate);
+		if (daysSinceActivity === 1) {
+			result.state.currentStreak = state.currentStreak + 1;
+			result.state.longestStreak = Math.max(result.state.currentStreak, state.longestStreak);
+			result.state.lastActivityAt = now;
+			result.state.lastActivityDate = todayDate;
+			result.streakMaintained = true;
+			return result;
+		}
+		result.daysMissed = daysSinceActivity - 1;
+		const freezesNeeded = result.daysMissed;
+		if (freezesNeeded <= state.freezesRemaining) {
+			result.state.freezesRemaining = state.freezesRemaining - freezesNeeded;
+			result.state.freezeUsedAt = now;
+			result.state.currentStreak = state.currentStreak + 1;
+			result.state.longestStreak = Math.max(result.state.currentStreak, state.longestStreak);
+			result.state.lastActivityAt = now;
+			result.state.lastActivityDate = todayDate;
+			result.freezeUsed = true;
+			result.streakMaintained = true;
+			return result;
+		}
+		result.streakLost = true;
+		result.state.currentStreak = 1;
+		result.state.lastActivityAt = now;
+		result.state.lastActivityDate = todayDate;
+		result.newStreak = true;
+		return result;
+	}
+	/**
+	* Check streak status without recording activity.
+	*/
+	checkStatus(state, now = /* @__PURE__ */ new Date()) {
+		if (!state.lastActivityDate) return {
+			isActive: false,
+			willExpireAt: null,
+			canUseFreeze: false,
+			daysUntilExpiry: 0
+		};
+		const todayDate = this.getDateString(now);
+		const daysSinceActivity = this.getDaysBetween(state.lastActivityDate, todayDate);
+		if (daysSinceActivity === 0) {
+			const tomorrow = this.addDays(now, 1);
+			tomorrow.setHours(23, 59, 59, 999);
+			return {
+				isActive: true,
+				willExpireAt: tomorrow,
+				canUseFreeze: state.freezesRemaining > 0,
+				daysUntilExpiry: 1
+			};
+		}
+		if (daysSinceActivity === 1) {
+			const endOfDay = new Date(now);
+			endOfDay.setHours(23 + this.config.gracePeriodHours, 59, 59, 999);
+			return {
+				isActive: true,
+				willExpireAt: endOfDay,
+				canUseFreeze: state.freezesRemaining > 0,
+				daysUntilExpiry: 0
+			};
+		}
+		const missedDays = daysSinceActivity - 1;
+		return {
+			isActive: missedDays <= state.freezesRemaining,
+			willExpireAt: null,
+			canUseFreeze: missedDays <= state.freezesRemaining,
+			daysUntilExpiry: -missedDays
+		};
+	}
+	/**
+	* Manually use a freeze to protect streak.
+	*/
+	useFreeze(state, now = /* @__PURE__ */ new Date()) {
+		if (state.freezesRemaining <= 0) return null;
+		return {
+			...state,
+			freezesRemaining: state.freezesRemaining - 1,
+			freezeUsedAt: now
+		};
+	}
+	/**
+	* Award monthly freezes.
+	*/
+	awardMonthlyFreezes(state) {
+		return {
+			...state,
+			freezesRemaining: Math.min(state.freezesRemaining + this.config.freezesPerMonth, this.config.maxFreezes)
+		};
+	}
+	/**
+	* Get initial streak state.
+	*/
+	getInitialState() {
+		return {
+			currentStreak: 0,
+			longestStreak: 0,
+			lastActivityAt: null,
+			lastActivityDate: null,
+			freezesRemaining: this.config.freezesPerMonth,
+			freezeUsedAt: null
+		};
+	}
+	/**
+	* Calculate streak milestones.
+	*/
+	getMilestones(currentStreak) {
+		const milestones = [
+			3,
+			7,
+			14,
+			30,
+			60,
+			90,
+			180,
+			365,
+			500,
+			1e3
+		];
+		return {
+			achieved: milestones.filter((m) => currentStreak >= m),
+			next: milestones.find((m) => currentStreak < m) ?? null
+		};
+	}
+	/**
+	* Get date string in YYYY-MM-DD format.
+	*/
+	getDateString(date) {
+		return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`;
+	}
+	/**
+	* Get number of days between two date strings.
+	*/
+	getDaysBetween(dateStr1, dateStr2) {
+		const date1 = new Date(dateStr1);
+		const diffTime = new Date(dateStr2).getTime() - date1.getTime();
+		return Math.floor(diffTime / (1e3 * 60 * 60 * 24));
+	}
+	/**
+	* Add days to a date.
+	*/
+	addDays(date, days) {
+		return new Date(date.getTime() + days * 24 * 60 * 60 * 1e3);
+	}
+};
+/**
+* Default streak engine instance.
+*/
+const streakEngine = new StreakEngine();
+
+//#endregion
+export { DEFAULT_STREAK_CONFIG, StreakEngine, streakEngine };
+//# sourceMappingURL=streak.js.map

package/dist/engines/streak.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streak.js","names":["DEFAULT_STREAK_CONFIG: StreakConfig","result: StreakUpdateResult"],"sources":["../../src/engines/streak.ts"],"sourcesContent":["/**\n * Streak Tracking Engine\n *\n * Manages daily learning streaks with timezone support and freeze protection.\n */\n\n// ============ Types ============\n\nexport interface StreakState {\n  /** Current streak days */\n  currentStreak: number;\n  /** Longest streak ever */\n  longestStreak: number;\n  /** Last activity timestamp */\n  lastActivityAt: Date | null;\n  /** Last activity date (YYYY-MM-DD) */\n  lastActivityDate: string | null;\n  /** Available streak freezes */\n  freezesRemaining: number;\n  /** When a freeze was last used */\n  freezeUsedAt: Date | null;\n}\n\nexport interface StreakUpdateResult {\n  /** Updated streak state */\n  state: StreakState;\n  /** Whether streak was maintained */\n  streakMaintained: boolean;\n  /** Whether streak was lost */\n  streakLost: boolean;\n  /** Whether a freeze was used */\n  freezeUsed: boolean;\n  /** Whether this activity started a new streak */\n  newStreak: boolean;\n  /** Days missed (if streak was lost) */\n  daysMissed: number;\n}\n\nexport interface StreakConfig {\n  /** Timezone for the user */\n  timezone: string;\n  /** How many streak freezes to give per month */\n  freezesPerMonth: number;\n  /** Maximum freezes that can be accumulated */\n  maxFreezes: number;\n  /** Grace period in hours after midnight */\n  gracePeriodHours: number;\n}\n\n// ============ Default Configuration ============\n\nexport const DEFAULT_STREAK_CONFIG: StreakConfig = {\n  timezone: 'UTC',\n  freezesPerMonth: 2,\n  maxFreezes: 5,\n  gracePeriodHours: 4, // 4 hours grace period\n};\n\n// ============ Streak Engine ============\n\nexport class StreakEngine {\n  private config: StreakConfig;\n\n  constructor(config: Partial<StreakConfig> = {}) {\n    this.config = { ...DEFAULT_STREAK_CONFIG, ...config };\n  }\n\n  /**\n   * Update streak based on new activity.\n   */\n  update(state: StreakState, now: Date = new Date()): StreakUpdateResult {\n    const todayDate = this.getDateString(now);\n    const result: StreakUpdateResult = {\n      state: { ...state },\n      streakMaintained: false,\n      streakLost: false,\n      freezeUsed: false,\n      newStreak: false,\n      daysMissed: 0,\n    };\n\n    // If no previous activity, start new streak\n    if (!state.lastActivityDate) {\n      result.state.currentStreak = 1;\n      result.state.longestStreak = Math.max(1, state.longestStreak);\n      result.state.lastActivityAt = now;\n      result.state.lastActivityDate = todayDate;\n      result.newStreak = true;\n      result.streakMaintained = true;\n      return result;\n    }\n\n    // Check if activity is on the same day\n    if (state.lastActivityDate === todayDate) {\n      // Same day - just update timestamp, streak unchanged\n      result.state.lastActivityAt = now;\n      result.streakMaintained = true;\n      return result;\n    }\n\n    // Calculate days since last activity\n    const daysSinceActivity = this.getDaysBetween(\n      state.lastActivityDate,\n      todayDate\n    );\n\n    if (daysSinceActivity === 1) {\n      // Perfect - activity on consecutive day\n      result.state.currentStreak = state.currentStreak + 1;\n      result.state.longestStreak = Math.max(\n        result.state.currentStreak,\n        state.longestStreak\n      );\n      result.state.lastActivityAt = now;\n      result.state.lastActivityDate = todayDate;\n      result.streakMaintained = true;\n      return result;\n    }\n\n    // Streak was potentially broken\n    result.daysMissed = daysSinceActivity - 1;\n\n    // Check if we can use freezes\n    const freezesNeeded = result.daysMissed;\n    if (freezesNeeded <= state.freezesRemaining) {\n      // Use freezes to maintain streak\n      result.state.freezesRemaining = state.freezesRemaining - freezesNeeded;\n      result.state.freezeUsedAt = now;\n      result.state.currentStreak = state.currentStreak + 1; // Add today\n      result.state.longestStreak = Math.max(\n        result.state.currentStreak,\n        state.longestStreak\n      );\n      result.state.lastActivityAt = now;\n      result.state.lastActivityDate = todayDate;\n      result.freezeUsed = true;\n      result.streakMaintained = true;\n      return result;\n    }\n\n    // Streak is lost\n    result.streakLost = true;\n    result.state.currentStreak = 1; // Start new streak\n    result.state.lastActivityAt = now;\n    result.state.lastActivityDate = todayDate;\n    result.newStreak = true;\n    return result;\n  }\n\n  /**\n   * Check streak status without recording activity.\n   */\n  checkStatus(\n    state: StreakState,\n    now: Date = new Date()\n  ): {\n    isActive: boolean;\n    willExpireAt: Date | null;\n    canUseFreeze: boolean;\n    daysUntilExpiry: number;\n  } {\n    if (!state.lastActivityDate) {\n      return {\n        isActive: false,\n        willExpireAt: null,\n        canUseFreeze: false,\n        daysUntilExpiry: 0,\n      };\n    }\n\n    const todayDate = this.getDateString(now);\n    const daysSinceActivity = this.getDaysBetween(\n      state.lastActivityDate,\n      todayDate\n    );\n\n    if (daysSinceActivity === 0) {\n      // Activity today - streak is active\n      const tomorrow = this.addDays(now, 1);\n      tomorrow.setHours(23, 59, 59, 999);\n      return {\n        isActive: true,\n        willExpireAt: tomorrow,\n        canUseFreeze: state.freezesRemaining > 0,\n        daysUntilExpiry: 1,\n      };\n    }\n\n    if (daysSinceActivity === 1) {\n      // No activity today yet, but still within window\n      const endOfDay = new Date(now);\n      endOfDay.setHours(23 + this.config.gracePeriodHours, 59, 59, 999);\n      return {\n        isActive: true,\n        willExpireAt: endOfDay,\n        canUseFreeze: state.freezesRemaining > 0,\n        daysUntilExpiry: 0,\n      };\n    }\n\n    // Streak would be broken\n    const missedDays = daysSinceActivity - 1;\n    return {\n      isActive: missedDays <= state.freezesRemaining,\n      willExpireAt: null,\n      canUseFreeze: missedDays <= state.freezesRemaining,\n      daysUntilExpiry: -missedDays,\n    };\n  }\n\n  /**\n   * Manually use a freeze to protect streak.\n   */\n  useFreeze(state: StreakState, now: Date = new Date()): StreakState | null {\n    if (state.freezesRemaining <= 0) {\n      return null;\n    }\n\n    return {\n      ...state,\n      freezesRemaining: state.freezesRemaining - 1,\n      freezeUsedAt: now,\n    };\n  }\n\n  /**\n   * Award monthly freezes.\n   */\n  awardMonthlyFreezes(state: StreakState): StreakState {\n    return {\n      ...state,\n      freezesRemaining: Math.min(\n        state.freezesRemaining + this.config.freezesPerMonth,\n        this.config.maxFreezes\n      ),\n    };\n  }\n\n  /**\n   * Get initial streak state.\n   */\n  getInitialState(): StreakState {\n    return {\n      currentStreak: 0,\n      longestStreak: 0,\n      lastActivityAt: null,\n      lastActivityDate: null,\n      freezesRemaining: this.config.freezesPerMonth,\n      freezeUsedAt: null,\n    };\n  }\n\n  /**\n   * Calculate streak milestones.\n   */\n  getMilestones(currentStreak: number): {\n    achieved: number[];\n    next: number | null;\n  } {\n    const milestones = [3, 7, 14, 30, 60, 90, 180, 365, 500, 1000];\n    const achieved = milestones.filter((m) => currentStreak >= m);\n    const next = milestones.find((m) => currentStreak < m) ?? null;\n    return { achieved, next };\n  }\n\n  // ============ Helpers ============\n\n  /**\n   * Get date string in YYYY-MM-DD format.\n   */\n  private getDateString(date: Date): string {\n    // Simple implementation - for production, use a proper timezone library\n    const year = date.getFullYear();\n    const month = String(date.getMonth() + 1).padStart(2, '0');\n    const day = String(date.getDate()).padStart(2, '0');\n    return `${year}-${month}-${day}`;\n  }\n\n  /**\n   * Get number of days between two date strings.\n   */\n  private getDaysBetween(dateStr1: string, dateStr2: string): number {\n    const date1 = new Date(dateStr1);\n    const date2 = new Date(dateStr2);\n    const diffTime = date2.getTime() - date1.getTime();\n    return Math.floor(diffTime / (1000 * 60 * 60 * 24));\n  }\n\n  /**\n   * Add days to a date.\n   */\n  private addDays(date: Date, days: number): Date {\n    return new Date(date.getTime() + days * 24 * 60 * 60 * 1000);\n  }\n}\n\n/**\n * Default streak engine instance.\n */\nexport const streakEngine = new StreakEngine();\n"],"mappings":"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"}

package/dist/engines/xp.d.ts

@@ -0,0 +1,97 @@
+//#region src/engines/xp.d.ts
+/**
+ * XP (Experience Points) Engine
+ *
+ * Calculates XP rewards for various learning activities.
+ */
+type XPActivityType = 'lesson_complete' | 'quiz_pass' | 'quiz_perfect' | 'flashcard_review' | 'course_complete' | 'module_complete' | 'streak_bonus' | 'achievement_unlock' | 'daily_goal_complete' | 'first_lesson' | 'onboarding_step' | 'onboarding_complete';
+interface XPCalculationInput {
+  /** Type of activity */
+  activity: XPActivityType;
+  /** Base XP for the activity (from content config) */
+  baseXp?: number;
+  /** Score achieved (0-100) for scored activities */
+  score?: number;
+  /** Current streak (for streak bonuses) */
+  currentStreak?: number;
+  /** Time spent in seconds */
+  timeSpent?: number;
+  /** Attempt number (for quizzes) */
+  attemptNumber?: number;
+  /** Whether this is a retry */
+  isRetry?: boolean;
+}
+interface XPResult {
+  /** Total XP earned */
+  totalXp: number;
+  /** Base XP before bonuses */
+  baseXp: number;
+  /** Breakdown of XP sources */
+  breakdown: XPBreakdown[];
+}
+interface XPBreakdown {
+  /** Source of XP */
+  source: string;
+  /** XP amount */
+  amount: number;
+  /** Multiplier applied */
+  multiplier?: number;
+}
+interface XPConfig {
+  /** Base XP values for each activity */
+  baseValues: Record<XPActivityType, number>;
+  /** Score thresholds for bonus XP */
+  scoreThresholds: {
+    min: number;
+    multiplier: number;
+  }[];
+  /** Streak bonus tiers */
+  streakTiers: {
+    days: number;
+    bonus: number;
+  }[];
+  /** Perfect score bonus multiplier */
+  perfectScoreMultiplier: number;
+  /** First attempt bonus */
+  firstAttemptBonus: number;
+  /** Retry penalty multiplier */
+  retryPenalty: number;
+  /** Speed bonus (complete under expected time) */
+  speedBonusMultiplier: number;
+  /** Speed bonus threshold (percentage of expected time) */
+  speedBonusThreshold: number;
+}
+declare const DEFAULT_XP_CONFIG: XPConfig;
+declare class XPEngine {
+  private config;
+  constructor(config?: Partial<XPConfig>);
+  /**
+   * Calculate XP for an activity.
+   */
+  calculate(input: XPCalculationInput): XPResult;
+  /**
+   * Calculate streak bonus XP.
+   */
+  calculateStreakBonus(currentStreak: number): XPResult;
+  /**
+   * Calculate XP needed for a level.
+   */
+  getXpForLevel(level: number): number;
+  /**
+   * Get level from total XP.
+   */
+  getLevelFromXp(totalXp: number): {
+    level: number;
+    xpInLevel: number;
+    xpForNextLevel: number;
+  };
+  private getScoreMultiplier;
+  private getStreakBonus;
+}
+/**
+ * Default XP engine instance.
+ */
+declare const xpEngine: XPEngine;
+//#endregion
+export { DEFAULT_XP_CONFIG, XPActivityType, XPBreakdown, XPCalculationInput, XPConfig, XPEngine, XPResult, xpEngine };
+//# sourceMappingURL=xp.d.ts.map

package/dist/engines/xp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xp.d.ts","names":[],"sources":["../../src/engines/xp.ts"],"sourcesContent":[],"mappings":";;AAQA;AAcA;AAiBA;AASA;AASiB,KAjDL,cAAA,GAmDS,iBAAP,GAAA,WAAM,GAAA,cAAA,GAAA,kBAAA,GAAA,iBAAA,GAAA,iBAAA,GAAA,cAAA,GAAA,oBAAA,GAAA,qBAAA,GAAA,cAAA,GAAA,iBAAA,GAAA,qBAAA;AAmBP,UAxDI,kBAAA,CAwDe;EAyCnB;EAGiB,QAAA,EAlGlB,cAkGkB;EAAR;EAcH,MAAA,CAAA,EAAA,MAAA;EAAqB;EAsFO,KAAA,CAAA,EAAA,MAAA;EAAQ;EA6E1C,aAAyB,CAAA,EAAA,MAAA;;;;;;;;UApQrB,QAAA;;;;;;aAMJ;;UAGI,WAAA;;;;;;;;UASA,QAAA;;cAEH,OAAO;;;;;;;;;;;;;;;;;;;;;;cAmBR,mBAAmB;cAyCnB,QAAA;;uBAGS,QAAQ;;;;mBAcX,qBAAqB;;;;+CAsFO;;;;;;;;;;;;;;;;;;;cA6ElC,UAAQ"}