@lssm/module.learning-journey 1.41.1 → 1.42.1

package/dist/engines/srs.d.ts

@@ -0,0 +1,111 @@
+//#region src/engines/srs.d.ts
+/**
+ * Spaced Repetition System (SRS) Engine
+ *
+ * Implements the SM-2 algorithm variant for optimal flashcard scheduling.
+ *
+ * The algorithm calculates the optimal time to review a card based on:
+ * - User's rating of recall difficulty (again, hard, good, easy)
+ * - Current interval between reviews
+ * - Ease factor (how easy the card is for this user)
+ * - Number of successful repetitions
+ */
+type CardRating = 'AGAIN' | 'HARD' | 'GOOD' | 'EASY';
+interface SRSState {
+  /** Current interval in days */
+  interval: number;
+  /** Ease factor (typically 1.3 to 2.5+) */
+  easeFactor: number;
+  /** Number of successful repetitions */
+  repetitions: number;
+  /** Current learning step (for new cards) */
+  learningStep: number;
+  /** Whether card has graduated to review phase */
+  isGraduated: boolean;
+  /** Whether card is being relearned after a lapse */
+  isRelearning: boolean;
+  /** Number of times card was forgotten */
+  lapses: number;
+}
+interface ReviewResult {
+  /** New interval in days */
+  interval: number;
+  /** New ease factor */
+  easeFactor: number;
+  /** New repetition count */
+  repetitions: number;
+  /** Next review date */
+  nextReviewAt: Date;
+  /** New learning step */
+  learningStep: number;
+  /** Whether card has graduated */
+  isGraduated: boolean;
+  /** Whether card is being relearned */
+  isRelearning: boolean;
+  /** Updated lapse count */
+  lapses: number;
+}
+interface SRSConfig {
+  /** Learning steps in minutes [1, 10] = 1 min, 10 min */
+  learningSteps: number[];
+  /** Graduating interval in days */
+  graduatingInterval: number;
+  /** Easy interval (for easy button on new cards) */
+  easyInterval: number;
+  /** Relearning steps in minutes */
+  relearningSteps: number[];
+  /** Minimum ease factor */
+  minEaseFactor: number;
+  /** Maximum interval in days */
+  maxInterval: number;
+  /** Interval modifier (1.0 = 100%) */
+  intervalModifier: number;
+  /** New cards interval modifier */
+  newIntervalModifier: number;
+  /** Hard interval modifier */
+  hardIntervalModifier: number;
+  /** Easy bonus modifier */
+  easyBonus: number;
+}
+declare const DEFAULT_SRS_CONFIG: SRSConfig;
+declare class SRSEngine {
+  private config;
+  constructor(config?: Partial<SRSConfig>);
+  /**
+   * Calculate the next review state based on rating.
+   */
+  calculateNextReview(state: SRSState, rating: CardRating, now?: Date): ReviewResult;
+  /**
+   * Get initial SRS state for a new card.
+   */
+  getInitialState(): SRSState;
+  /**
+   * Check if a card is due for review.
+   */
+  isDue(nextReviewAt: Date, now?: Date): boolean;
+  /**
+   * Calculate overdue days (negative if not yet due).
+   */
+  getOverdueDays(nextReviewAt: Date, now?: Date): number;
+  /**
+   * Handle learning phase (new cards).
+   */
+  private handleLearningCard;
+  /**
+   * Handle relearning phase (lapsed cards).
+   */
+  private handleRelearningCard;
+  /**
+   * Handle review phase (graduated cards).
+   */
+  private handleReviewCard;
+  private addMinutes;
+  private addDays;
+}
+/**
+ * Default SRS engine instance.
+ */
+declare const srsEngine: SRSEngine;
+//#endregion
+export { CardRating, DEFAULT_SRS_CONFIG, ReviewResult, SRSConfig, SRSEngine, SRSState, srsEngine };
+//# sourceMappingURL=srs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"srs.d.ts","names":[],"sources":["../../src/engines/srs.ts"],"sourcesContent":[],"mappings":";;AAcA;AAEA;AAiBA;AAmBA;AAyBA;AAeA;;;;;AAaS,KA3FG,UAAA,GA2FH,OAAA,GAAA,MAAA,GAAA,MAAA,GAAA,MAAA;AACJ,UA1FY,QAAA,CA0FZ;EAkBgB;EAeC,QAAA,EAAA,MAAA;EAAW;EAOF,UAAA,EAAA,MAAA;EAAW;EAAiB,WAAA,EAAA,MAAA;EA4O9C;;;;;;;;;UA7VI,YAAA;;;;;;;;gBAQD;;;;;;;;;;UAWC,SAAA;;;;;;;;;;;;;;;;;;;;;;cAyBJ,oBAAoB;cAepB,SAAA;;uBAGS,QAAQ;;;;6BAQnB,kBACC,kBACH,OACJ;;;;qBAkBgB;;;;sBAeC,YAAW;;;;+BAOF,YAAW;;;;;;;;;;;;;;;;;;;cA4O7B,WAAS"}

package/dist/engines/srs.js

@@ -1 +1,219 @@
-const e={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 t=class{config;constructor(t={}){this.config={...e,...t}}calculateNextReview(e,t,n=new Date){return!e.isGraduated&&!e.isRelearning?this.handleLearningCard(e,t,n):e.isRelearning?this.handleRelearningCard(e,t,n):this.handleReviewCard(e,t,n)}handleLearningCard(e,t,n){let r=this.config.learningSteps,i=e.learningStep,a=!1,o=0,s;switch(t){case`AGAIN`:i=0,o=r[0]??1,s=this.addMinutes(n,o);break;case`HARD`:o=r[i]??r[0]??1,s=this.addMinutes(n,o);break;case`GOOD`:i++,i>=r.length?(a=!0,o=this.config.graduatingInterval,s=this.addDays(n,o)):(o=r[i]??10,s=this.addMinutes(n,o));break;case`EASY`:a=!0,o=this.config.easyInterval,s=this.addDays(n,o);break}return{interval:a?o:0,easeFactor:e.easeFactor,repetitions:a?1:0,nextReviewAt:s,learningStep:i,isGraduated:a,isRelearning:!1,lapses:e.lapses}}handleRelearningCard(e,t,n){let r=this.config.relearningSteps,i=e.learningStep,a=!0,o=0,s;switch(t){case`AGAIN`:i=0,o=r[0]??10,s=this.addMinutes(n,o);break;case`HARD`:o=r[i]??r[0]??10,s=this.addMinutes(n,o);break;case`GOOD`:i++,i>=r.length?(a=!1,o=Math.max(1,Math.floor(e.interval*this.config.newIntervalModifier)),s=this.addDays(n,o)):(o=r[i]??10,s=this.addMinutes(n,o));break;case`EASY`:a=!1,o=Math.max(1,Math.floor(e.interval*this.config.newIntervalModifier*1.5)),s=this.addDays(n,o);break}return{interval:a?e.interval:o,easeFactor:e.easeFactor,repetitions:a?e.repetitions:e.repetitions+1,nextReviewAt:s,learningStep:i,isGraduated:!0,isRelearning:a,lapses:e.lapses}}handleReviewCard(e,t,n){let r,i=e.easeFactor,a=e.repetitions,o=!1,s=0,c=e.lapses;switch(t){case`AGAIN`:c++,o=!0,s=0,i=Math.max(this.config.minEaseFactor,i-.2),r=e.interval;let t=this.config.relearningSteps[0]??10;return{interval:r,easeFactor:i,repetitions:a,nextReviewAt:this.addMinutes(n,t),learningStep:s,isGraduated:!0,isRelearning:!0,lapses:c};case`HARD`:i=Math.max(this.config.minEaseFactor,i-.15),r=Math.max(e.interval+1,e.interval*this.config.hardIntervalModifier);break;case`GOOD`:r=e.interval*i*this.config.intervalModifier,a++;break;case`EASY`:i+=.15,r=e.interval*i*this.config.easyBonus*this.config.intervalModifier,a++;break}return r=Math.min(Math.round(r),this.config.maxInterval),r=Math.max(1,r),{interval:r,easeFactor:i,repetitions:a,nextReviewAt:this.addDays(n,r),learningStep:s,isGraduated:!0,isRelearning:o,lapses:c}}getInitialState(){return{interval:0,easeFactor:2.5,repetitions:0,learningStep:0,isGraduated:!1,isRelearning:!1,lapses:0}}isDue(e,t=new Date){return e<=t}getOverdueDays(e,t=new Date){let n=t.getTime()-e.getTime();return Math.floor(n/(1e3*60*60*24))}addMinutes(e,t){return new Date(e.getTime()+t*60*1e3)}addDays(e,t){return new Date(e.getTime()+t*24*60*60*1e3)}};const n=new t;export{e as DEFAULT_SRS_CONFIG,t as SRSEngine,n as srsEngine};
+//#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

@@ -1 +1,194 @@
-const e={timezone:`UTC`,freezesPerMonth:2,maxFreezes:5,gracePeriodHours:4};var t=class{config;constructor(t={}){this.config={...e,...t}}update(e,t=new Date){let n=this.getDateString(t),r={state:{...e},streakMaintained:!1,streakLost:!1,freezeUsed:!1,newStreak:!1,daysMissed:0};if(!e.lastActivityDate)return r.state.currentStreak=1,r.state.longestStreak=Math.max(1,e.longestStreak),r.state.lastActivityAt=t,r.state.lastActivityDate=n,r.newStreak=!0,r.streakMaintained=!0,r;if(e.lastActivityDate===n)return r.state.lastActivityAt=t,r.streakMaintained=!0,r;let i=this.getDaysBetween(e.lastActivityDate,n);if(i===1)return r.state.currentStreak=e.currentStreak+1,r.state.longestStreak=Math.max(r.state.currentStreak,e.longestStreak),r.state.lastActivityAt=t,r.state.lastActivityDate=n,r.streakMaintained=!0,r;r.daysMissed=i-1;let a=r.daysMissed;return a<=e.freezesRemaining?(r.state.freezesRemaining=e.freezesRemaining-a,r.state.freezeUsedAt=t,r.state.currentStreak=e.currentStreak+1,r.state.longestStreak=Math.max(r.state.currentStreak,e.longestStreak),r.state.lastActivityAt=t,r.state.lastActivityDate=n,r.freezeUsed=!0,r.streakMaintained=!0,r):(r.streakLost=!0,r.state.currentStreak=1,r.state.lastActivityAt=t,r.state.lastActivityDate=n,r.newStreak=!0,r)}checkStatus(e,t=new Date){if(!e.lastActivityDate)return{isActive:!1,willExpireAt:null,canUseFreeze:!1,daysUntilExpiry:0};let n=this.getDateString(t),r=this.getDaysBetween(e.lastActivityDate,n);if(r===0){let n=this.addDays(t,1);return n.setHours(23,59,59,999),{isActive:!0,willExpireAt:n,canUseFreeze:e.freezesRemaining>0,daysUntilExpiry:1}}if(r===1){let n=new Date(t);return n.setHours(23+this.config.gracePeriodHours,59,59,999),{isActive:!0,willExpireAt:n,canUseFreeze:e.freezesRemaining>0,daysUntilExpiry:0}}let i=r-1;return{isActive:i<=e.freezesRemaining,willExpireAt:null,canUseFreeze:i<=e.freezesRemaining,daysUntilExpiry:-i}}useFreeze(e,t=new Date){return e.freezesRemaining<=0?null:{...e,freezesRemaining:e.freezesRemaining-1,freezeUsedAt:t}}awardMonthlyFreezes(e){return{...e,freezesRemaining:Math.min(e.freezesRemaining+this.config.freezesPerMonth,this.config.maxFreezes)}}getInitialState(){return{currentStreak:0,longestStreak:0,lastActivityAt:null,lastActivityDate:null,freezesRemaining:this.config.freezesPerMonth,freezeUsedAt:null}}getMilestones(e){let t=[3,7,14,30,60,90,180,365,500,1e3];return{achieved:t.filter(t=>e>=t),next:t.find(t=>e<t)??null}}getDateString(e){return`${e.getFullYear()}-${String(e.getMonth()+1).padStart(2,`0`)}-${String(e.getDate()).padStart(2,`0`)}`}getDaysBetween(e,t){let n=new Date(e),r=new Date(t).getTime()-n.getTime();return Math.floor(r/(1e3*60*60*24))}addDays(e,t){return new Date(e.getTime()+t*24*60*60*1e3)}};const n=new t;export{e as DEFAULT_STREAK_CONFIG,t as StreakEngine,n as streakEngine};
+//#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