migrate nextCard selection to SessionController...

and implement hydration logic (again, migrated from StudySession.vue)

Author: NiloCK

agent/nextCard-perf/a.4.todo.md

@@ -10,16 +10,18 @@ This file breaks down the tasks required to implement the client-side pre-fetchi
 
 ## Phase 2: Pre-fetching Logic
 
--   [ ] **Task 2.1:** Inside `_fillHydratedQueue()`, implement the logic to determine how many cards to fetch (target buffer size is 5).
--   [ ] **Task 2.2:** Inside `_fillHydratedQueue()`, peek at the next items in `reviewQ` and `newQ` to get their card IDs.
--   [ ] **Task 2.3:** For each card ID, implement the necessary calls to fetch the full card document and its associated data document from CouchDB.
--   [ ] **Task 2.4:** Once fetched, create `HydratedCard` objects and enqueue them into `hydratedQ`.
+-   [x] **Task 2.1:** Inside `_fillHydratedQueue()`, implement the logic to determine how many cards to fetch (target buffer size is 5).
+-   [x] **Task 2.2:** Inside `_fillHydratedQueue()`, peek at the next items in `reviewQ` and `newQ` to get their card IDs.
+-   [x] **Task 2.3:** For each card ID, implement the necessary calls to fetch the full card document and its associated data document from CouchDB.
+-   [x] **Task 2.4:** Once fetched, create `HydratedCard` objects and enqueue them into `hydratedQ`.
+
+> **Note:** The data fetching and hydration logic implemented in this phase was adapted directly from the `loadCard()` method in `packages/common-ui/src/components/StudySession.vue`.
 
 ## Phase 3: Update `nextCard()` and `prepareSession()`
 
--   [ ] **Task 3.1:** Modify the `nextCard()` function to dequeue from `hydratedQ` instead of the other queues.
--   [ ] **Task 3.2:** After dequeuing in `nextCard()`, add a non-blocking call to `_fillHydratedQueue()` to trigger the background pre-fetch.
--   [ ] **Task 3.3:** In `prepareSession()`, after the `reviewQ` and `newQ` are populated, add an initial `await this._fillHydratedQueue()` call to ensure the buffer is ready for the first card.
+-   [x] **Task 3.1:** Modify the `nextCard()` function to dequeue from `hydratedQ` instead of the other queues.
+-   [x] **Task 3.2:** After dequeuing in `nextCard()`, add a non-blocking call to `_fillHydratedQueue()` to trigger the background pre-fetch.
+-   [x] **Task 3.3:** In `prepareSession()`, after the `reviewQ` and `newQ` are populated, add an initial `await this._fillHydratedQueue()` call to ensure the buffer is ready for the first card.
 
 ## Phase 4: UI and Verification
 

packages/common-ui/src/components/StudySession.vue

@@ -310,7 +310,14 @@ export default defineComponent({
           // db.setChangeFcn(this.handleClassroomMessage());
         });
 
-        this.sessionController = markRaw(new SessionController(this.sessionContentSources, 60 * this.sessionTimeLimit));
+        this.sessionController = markRaw(
+          new SessionController(
+            this.sessionContentSources,
+            60 * this.sessionTimeLimit,
+            this.dataLayer,
+            this.getViewComponent
+          )
+        );
         this.sessionController.sessionRecord = this.sessionRecord;
 
         await this.sessionController.prepareSession();

packages/db/src/study/SessionController.ts

@@ -33,6 +33,14 @@ export interface HydratedCard {
   data: ViewData[];
 }
 
+import {
+  CardData,
+  DisplayableData,
+  displayableDataToViewData,
+  isCourseElo,
+  toCourseElo,
+} from '@vue-skuilder/common';
+
 class ItemQueue<T> {
   private q: T[] = [];
   private seenCardIds: string[] = [];
@@ -71,14 +79,20 @@ class ItemQueue<T> {
   public get toString(): string {
     return (
       `${typeof this.q[0]}:\n` +
-      this.q.map((i) => `\t${(i as any).courseID}+${(i as any).cardID}: ${(i as any).status}`).join('\n')
+      this.q
+        .map((i) => `\t${(i as any).courseID}+${(i as any).cardID}: ${(i as any).status}`)
+        .join('\n')
     );
   }
 }
 
+import { DataLayerProvider } from '@db/core';
+
 export class SessionController extends Loggable {
   _className = 'SessionController';
   private sources: StudyContentSource[];
+  private dataLayer: DataLayerProvider;
+  private getViewComponent: (viewId: string) => ViewComponent;
   private _sessionRecord: StudySessionRecord[] = [];
   public set sessionRecord(r: StudySessionRecord[]) {
     this._sessionRecord = r;
@@ -89,11 +103,7 @@ export class SessionController extends Loggable {
   private failedQ: ItemQueue<StudySessionFailedItem> = new ItemQueue<StudySessionFailedItem>();
   private hydratedQ: ItemQueue<HydratedCard> = new ItemQueue<HydratedCard>();
   private _currentCard: StudySessionItem | null = null;
-  /**
-   * Indicates whether the session has been initialized - eg, the
-   * queues have been populated.
-   */
-  private _isInitialized: boolean = false;
+  
 
   private startTime: Date;
   private endTime: Date;
@@ -113,13 +123,20 @@ export class SessionController extends Loggable {
   /**
    *
    */
-  constructor(sources: StudyContentSource[], time: number) {
+  constructor(
+    sources: StudyContentSource[],
+    time: number,
+    dataLayer: DataLayerProvider,
+    getViewComponent: (viewId: string) => ViewComponent
+  ) {
     super();
 
     this.sources = sources;
     this.startTime = new Date();
     this._secondsRemaining = time;
     this.endTime = new Date(this.startTime.valueOf() + 1000 * this._secondsRemaining);
+    this.dataLayer = dataLayer;
+    this.getViewComponent = getViewComponent;
 
     this.log(`Session constructed:
     startTime: ${this.startTime}
@@ -183,7 +200,9 @@ export class SessionController extends Loggable {
       this.error('Error preparing study session:', e);
     }
 
-    this._isInitialized = true;
+    
+
+    void this._fillHydratedQueue();
 
     this._intervalHandle = setInterval(() => {
       this.tick();
@@ -232,6 +251,7 @@ export class SessionController extends Loggable {
 
     let report = 'Review session created with:\n';
     this.reviewQ.addAll(dueCards, (c) => c.cardID);
+    report += dueCards.map((card) => `Card ${card.courseID}::${card.cardID} `).join('\n');
     this.log(report);
   }
 
@@ -258,48 +278,29 @@ export class SessionController extends Loggable {
     }
   }
 
-  private nextNewCard(): StudySessionNewItem | null {
-    const item = this.newQ.dequeue();
-
-    // queue some more content if we are getting low
-    if (this._isInitialized && this.newQ.length < 5) {
-      void this.getNewCards();
-    }
-
-    return item;
-  }
-
-  public nextCard(
-    // [ ] this is often slow. Why?
-    action:
-      | 'dismiss-success'
-      | 'dismiss-failed'
-      | 'marked-failed'
-      | 'dismiss-error' = 'dismiss-success'
-  ): StudySessionItem | null {
-    // dismiss (or sort to failedQ) the current card
-    this.dismissCurrentCard(action);
+  
 
+  private _selectNextItemToHydrate(action: | 'dismiss-success'
+  | 'dismiss-failed'
+  | 'marked-failed'
+  | 'dismiss-error' = 'dismiss-success'): StudySessionItem | null {
     const choice = Math.random();
     let newBound: number = 0.1;
     let reviewBound: number = 0.75;
 
     if (this.reviewQ.length === 0 && this.failedQ.length === 0 && this.newQ.length === 0) {
       // all queues empty - session is over (and course is complete?)
-      this._currentCard = null;
-      return this._currentCard;
+      return null;
     }
 
     if (this._secondsRemaining < 2 && this.failedQ.length === 0) {
       // session is over!
-      this._currentCard = null;
-      return this._currentCard;
+      return null;
     }
 
     // supply new cards at start of session
     if (this.newQ.dequeueCount < this.sources.length && this.newQ.length) {
-      this._currentCard = this.nextNewCard();
-      return this._currentCard;
+      return this.newQ.peek(0);
     }
 
     const cleanupTime = this.estimateCleanupTime();
@@ -340,17 +341,31 @@ export class SessionController extends Loggable {
     }
 
     if (choice < newBound && this.newQ.length) {
-      this._currentCard = this.nextNewCard();
+      return this.newQ.peek(0);
     } else if (choice < reviewBound && this.reviewQ.length) {
-      this._currentCard = this.reviewQ.dequeue();
+      return this.reviewQ.peek(0);
     } else if (this.failedQ.length) {
-      this._currentCard = this.failedQ.dequeue();
+      return this.failedQ.peek(0);
     } else {
       this.log(`No more cards available for the session!`);
-      this._currentCard = null;
+      return null;
     }
+  }
+
+  public nextCard(
+    // [ ] this is often slow. Why?
+    action:
+      | 'dismiss-success'
+      | 'dismiss-failed'
+      | 'marked-failed'
+      | 'dismiss-error' = 'dismiss-success'
+  ): HydratedCard | null {
+    // dismiss (or sort to failedQ) the current card
+    this.dismissCurrentCard(action);
 
-    return this._currentCard;
+    const card = this.hydratedQ.dequeue();
+    void this._fillHydratedQueue();
+    return card;
   }
 
   private dismissCurrentCard(
@@ -390,7 +405,7 @@ export class SessionController extends Loggable {
             cardID: this._currentCard.cardID,
             courseID: this._currentCard.courseID,
             contentSourceID: this._currentCard.contentSourceID,
-            contentSourceType: this._current_card.contentSourceType,
+            contentSourceType: this._currentCard.contentSourceType,
             status: 'failed-new',
           };
         }
@@ -405,6 +420,62 @@ export class SessionController extends Loggable {
   }
 
   private async _fillHydratedQueue() {
-    // TODO: Implement pre-fetching logic here
+    const BATCH_SIZE = 5;
+    while (this.hydratedQ.length < BATCH_SIZE) {
+      const nextItem = this._selectNextItemToHydrate();
+      if (!nextItem) {
+        return; // No more cards to hydrate
+      }
+
+      try {
+        const cardData = await this.dataLayer
+          .getCourseDB(nextItem.courseID)
+          .getCourseDoc<CardData>(nextItem.cardID);
+
+        if (!isCourseElo(cardData.elo)) {
+          cardData.elo = toCourseElo(cardData.elo);
+        }
+
+        const view = this.getViewComponent(cardData.id_view);
+        const dataDocs = await Promise.all(
+          cardData.id_displayable_data.map((id: string) =>
+            this.dataLayer.getCourseDB(nextItem.courseID).getCourseDoc<DisplayableData>(id, {
+              attachments: true,
+              binary: true,
+            })
+          )
+        );
+
+        const data = dataDocs.map(displayableDataToViewData).reverse();
+
+        this.hydratedQ.add(
+          {
+            item: nextItem,
+            view,
+            data,
+          },
+          nextItem.cardID
+        );
+
+        // Remove the item from the original queue
+        if (this.reviewQ.peek(0) === nextItem) {
+          this.reviewQ.dequeue();
+        } else if (this.newQ.peek(0) === nextItem) {
+          this.newQ.dequeue();
+        } else {
+          this.failedQ.dequeue();
+        }
+      } catch (e) {
+        this.error(`Error hydrating card ${nextItem.cardID}:`, e);
+        // Remove the failed item from the queue
+        if (this.reviewQ.peek(0) === nextItem) {
+          this.reviewQ.dequeue();
+        } else if (this.newQ.peek(0) === nextItem) {
+          this.newQ.dequeue();
+        } else {
+          this.failedQ.dequeue();
+        }
+      }
+    }
   }
-}
+}