@vue-skuilder/db 0.1.18 → 0.1.21

package/src/study/TagFilteredContentSource.ts

@@ -1,11 +1,6 @@
-import {
-  StudyContentSource,
-  StudySessionNewItem,
-  StudySessionReviewItem,
-} from '@db/core/interfaces/contentSource';
+import { StudyContentSource } from '@db/core/interfaces/contentSource';
 import { WeightedCard } from '@db/core/navigators';
 import { UserDBInterface } from '@db/core';
-import { ScheduledCard } from '@db/core/types/user';
 import { TagFilter, hasActiveFilter } from '@vue-skuilder/common';
 import { getTag } from '../impl/couch/courseDB';
 import { logger } from '@db/util/logger';
@@ -113,122 +108,84 @@ export class TagFilteredContentSource implements StudyContentSource {
   }
 
   /**
-   * Gets new cards that match the tag filter and are not already active for the user.
+   * Get cards with suitability scores for presentation.
+   *
+   * Filters cards by tag inclusion/exclusion and assigns score=1.0 to all.
+   * TagFilteredContentSource does not currently support pluggable navigation
+   * strategies - it returns flat-scored candidates.
+   *
+   * @param limit - Maximum number of cards to return
+   * @returns Cards sorted by score descending (all scores = 1.0)
    */
-  public async getNewCards(limit?: number): Promise<StudySessionNewItem[]> {
+  public async getWeightedCards(limit: number): Promise<WeightedCard[]> {
     if (!hasActiveFilter(this.filter)) {
-      logger.warn('[TagFilteredContentSource] getNewCards called with no active filter');
+      logger.warn('[TagFilteredContentSource] getWeightedCards called with no active filter');
       return [];
     }
 
     const eligibleCardIds = await this.resolveFilteredCardIds();
+
+    // Get new cards: eligible cards that are not already active
     const activeCards = await this.user.getActiveCards();
     const activeCardIds = new Set(activeCards.map((c) => c.cardID));
 
-    const newItems: StudySessionNewItem[] = [];
+    const newCardWeighted: WeightedCard[] = [];
     for (const cardId of eligibleCardIds) {
       if (!activeCardIds.has(cardId)) {
-        newItems.push({
-          courseID: this.courseId,
-          cardID: cardId,
-          contentSourceType: 'course',
-          contentSourceID: this.courseId,
-          status: 'new',
+        newCardWeighted.push({
+          cardId,
+          courseId: this.courseId,
+          score: 1.0,
+          provenance: [
+            {
+              strategy: 'tagFilter',
+              strategyName: 'Tag Filter',
+              strategyId: 'TAG_FILTER',
+              action: 'generated' as const,
+              score: 1.0,
+              reason: `Tag-filtered new card (tags: ${this.filter.include.join(', ')})`,
+            },
+          ],
         });
       }
 
-      if (limit !== undefined && newItems.length >= limit) {
+      if (newCardWeighted.length >= limit) {
         break;
       }
     }
 
-    logger.info(`[TagFilteredContentSource] Found ${newItems.length} new cards matching filter`);
-    return newItems;
-  }
-
-  /**
-   * Gets pending reviews, filtered to only include cards that match the tag filter.
-   */
-  public async getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]> {
-    if (!hasActiveFilter(this.filter)) {
-      logger.warn('[TagFilteredContentSource] getPendingReviews called with no active filter');
-      return [];
-    }
+    logger.info(
+      `[TagFilteredContentSource] Found ${newCardWeighted.length} new cards matching filter`
+    );
 
-    const eligibleCardIds = await this.resolveFilteredCardIds();
+    // Get pending reviews: reviews for cards in the eligible set
     const allReviews = await this.user.getPendingReviews(this.courseId);
-
-    const filteredReviews = allReviews.filter((review) => {
-      return eligibleCardIds.has(review.cardId);
-    });
+    const filteredReviews = allReviews.filter((review) => eligibleCardIds.has(review.cardId));
 
     logger.info(
       `[TagFilteredContentSource] Found ${filteredReviews.length} pending reviews matching filter ` +
         `(of ${allReviews.length} total)`
     );
 
-    return filteredReviews.map((r) => ({
-      ...r,
-      courseID: r.courseId,
-      cardID: r.cardId,
-      contentSourceType: 'course' as const,
-      contentSourceID: this.courseId,
+    const reviewWeighted: WeightedCard[] = filteredReviews.map((r) => ({
+      cardId: r.cardId,
+      courseId: r.courseId,
+      score: 1.0,
       reviewID: r._id,
-      status: 'review' as const,
+      provenance: [
+        {
+          strategy: 'tagFilter',
+          strategyName: 'Tag Filter',
+          strategyId: 'TAG_FILTER',
+          action: 'generated' as const,
+          score: 1.0,
+          reason: `Tag-filtered review (tags: ${this.filter.include.join(', ')})`,
+        },
+      ],
     }));
-  }
-
-  /**
-   * Get cards with suitability scores for presentation.
-   *
-   * This implementation wraps the legacy getNewCards/getPendingReviews methods,
-   * assigning score=1.0 to all cards. TagFilteredContentSource does not currently
-   * support pluggable navigation strategies - it returns flat-scored candidates.
-   *
-   * @param limit - Maximum number of cards to return
-   * @returns Cards sorted by score descending (all scores = 1.0)
-   */
-  public async getWeightedCards(limit: number): Promise<WeightedCard[]> {
-    const [newCards, reviews] = await Promise.all([
-      this.getNewCards(limit),
-      this.getPendingReviews(),
-    ]);
-
-    const weighted: WeightedCard[] = [
-      ...reviews.map((r) => ({
-        cardId: r.cardID,
-        courseId: r.courseID,
-        score: 1.0,
-        provenance: [
-          {
-            strategy: 'tagFilter',
-            strategyName: 'Tag Filter',
-            strategyId: 'TAG_FILTER',
-            action: 'generated' as const,
-            score: 1.0,
-            reason: `Tag-filtered review (tags: ${this.filter.include.join(', ')})`,
-          },
-        ],
-      })),
-      ...newCards.map((c) => ({
-        cardId: c.cardID,
-        courseId: c.courseID,
-        score: 1.0,
-        provenance: [
-          {
-            strategy: 'tagFilter',
-            strategyName: 'Tag Filter',
-            strategyId: 'TAG_FILTER',
-            action: 'generated' as const,
-            score: 1.0,
-            reason: `Tag-filtered new card (tags: ${this.filter.include.join(', ')})`,
-          },
-        ],
-      })),
-    ];
 
     // Reviews first, then new cards; respect limit
-    return weighted.slice(0, limit);
+    return [...reviewWeighted, ...newCardWeighted].slice(0, limit);
   }
 
   /**

package/src/study/index.ts

@@ -1,3 +1,4 @@
 export * from './SessionController';
+export * from './SourceMixer';
 export * from './SpacedRepetition';
 export * from './TagFilteredContentSource';

package/src/study/services/CardHydrationService.ts

@@ -7,89 +7,156 @@ import {
 } from '@vue-skuilder/common';
 import { StudySessionItem } from '@db/impl/couch';
 import { logger } from '@db/util/logger';
-import { ItemQueue } from '../ItemQueue';
 import { CourseDBInterface } from '@db/core';
 
+/**
+ * Extract audio URLs from arbitrary field data using heuristic pattern matching.
+ * This is a "worse is better" approach - catches obvious URLs, silently ignores edge cases.
+ */
+function parseAudioURIs(data: unknown): string[] {
+  if (typeof data !== 'string') return [];
+
+  // Match URLs ending in common audio extensions
+  const audioPattern = /https?:\/\/[^\s"'<>]+\.(wav|mp3|ogg|m4a|aac|webm)/gi;
+  return data.match(audioPattern) ?? [];
+}
+
+/**
+ * Prefetch an audio file by loading it into browser cache.
+ * Resolves when the audio is ready to play (or on error, to avoid blocking).
+ */
+function prefetchAudio(url: string): Promise<void> {
+  return new Promise((resolve) => {
+    const audio = new Audio();
+    audio.preload = 'auto';
+
+    const cleanup = () => {
+      audio.oncanplaythrough = null;
+      audio.onerror = null;
+    };
+
+    audio.oncanplaythrough = () => {
+      cleanup();
+      resolve();
+    };
+
+    audio.onerror = () => {
+      cleanup();
+      logger.warn(`[CardHydrationService] Failed to prefetch audio: ${url}`);
+      resolve(); // Don't block hydration on failed prefetch
+    };
+
+    audio.src = url;
+  });
+}
+
 export interface HydratedCard<TView = unknown> {
   item: StudySessionItem;
   view: TView;
   data: any[];
 }
 
-// ItemQueue now imported from separate file
-
 /**
- * Service responsible for managing a queue of hydrated (ready-to-display) cards.
- * Handles pre-fetching card data, caching failed cards, and maintaining optimal buffer size.
+ * Service responsible for managing hydrated (ready-to-display) cards.
+ * Uses a Map-based cache for direct ID lookup - no ordering assumptions.
+ * SessionController owns all ordering decisions.
  */
 export class CardHydrationService<TView = unknown> {
-  private hydratedQ: ItemQueue<HydratedCard<TView>> = new ItemQueue<HydratedCard<TView>>();
-  private failedCardCache: Map<string, HydratedCard<TView>> = new Map();
+  private hydratedCards: Map<string, HydratedCard<TView>> = new Map();
+  private hydrationInFlight: Set<string> = new Set();
   private hydrationInProgress: boolean = false;
-  private readonly BUFFER_SIZE = 5;
 
   constructor(
     private getViewComponent: (viewId: string) => TView,
     private getCourseDB: (courseId: string) => CourseDBInterface,
-    private selectNextItemToHydrate: () => StudySessionItem | null,
-    private removeItemFromQueue: (item: StudySessionItem) => void,
-    private hasAvailableCards: () => boolean
+    private getItemsToHydrate: () => StudySessionItem[]
   ) {}
 
   /**
-   * Get the next hydrated card from the queue.
-   * @returns Hydrated card or null if none available
+   * Get a hydrated card by ID.
+   * @returns Hydrated card or null if not in cache
    */
-  public dequeueHydratedCard(): HydratedCard<TView> | null {
-    return this.hydratedQ.dequeue((item) => item.item.cardID);
+  public getHydratedCard(cardId: string): HydratedCard<TView> | null {
+    return this.hydratedCards.get(cardId) ?? null;
+  }
+
+  /**
+   * Check if a card is hydrated.
+   */
+  public hasHydratedCard(cardId: string): boolean {
+    return this.hydratedCards.has(cardId);
+  }
+
+  /**
+   * Remove a card from the cache (call on successful dismiss to free memory).
+   */
+  public removeCard(cardId: string): void {
+    this.hydratedCards.delete(cardId);
   }
 
   /**
    * Check if hydration should be triggered and start background hydration if needed.
    */
   public async ensureHydratedCards(): Promise<void> {
-    // Trigger background hydration to maintain cache (async, non-blocking)
-    if (this.hydratedQ.length < 3) {
-      void this.fillHydratedQueue();
-    }
+    void this.fillHydratedCards();
   }
 
   /**
-   * Wait for a hydrated card to become available.
+   * Wait for a specific card to become hydrated.
    * @returns Promise that resolves to a hydrated card or null
    */
-  public async waitForHydratedCard(): Promise<HydratedCard<TView> | null> {
-    // If no hydrated card but source cards available, start hydration
-    if (this.hydratedQ.length === 0 && this.hasAvailableCards()) {
-      void this.fillHydratedQueue(); // Start hydration in background
+  public async waitForCard(cardId: string): Promise<HydratedCard<TView> | null> {
+    // If already hydrated, return immediately
+    if (this.hydratedCards.has(cardId)) {
+      return this.hydratedCards.get(cardId)!;
+    }
+
+    // Start hydration if not already in progress
+    if (!this.hydrationInProgress) {
+      void this.fillHydratedCards();
     }
 
-    // Wait for a card to become available in hydratedQ
-    while (this.hydratedQ.length === 0 && this.hasAvailableCards()) {
-      await new Promise((resolve) => setTimeout(resolve, 25)); // Short polling interval
+    // Wait for the specific card to become available
+    const maxWaitMs = 10000; // 10 second timeout
+    const pollIntervalMs = 25;
+    let elapsed = 0;
+
+    while (elapsed < maxWaitMs) {
+      if (this.hydratedCards.has(cardId)) {
+        return this.hydratedCards.get(cardId)!;
+      }
+
+      // If the card is not in flight and not hydrated, it may have failed
+      if (!this.hydrationInFlight.has(cardId) && !this.hydrationInProgress) {
+        break;
+      }
+
+      await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+      elapsed += pollIntervalMs;
     }
 
-    return this.dequeueHydratedCard();
+    return this.hydratedCards.get(cardId) ?? null;
   }
 
   /**
-   * Get current hydrated queue length.
+   * Get current hydrated cache size.
    */
   public get hydratedCount(): number {
-    return this.hydratedQ.length;
+    return this.hydratedCards.size;
   }
 
   /**
-   * Get current failed card cache size.
+   * Get list of currently hydrated card IDs (for debugging).
    */
-  public get failedCacheSize(): number {
-    return this.failedCardCache.size;
+  public getHydratedCardIds(): string[] {
+    return Array.from(this.hydratedCards.keys());
   }
 
   /**
-   * Fill the hydrated queue up to BUFFER_SIZE with pre-fetched cards.
+   * Fill the hydrated cache by hydrating items from getItemsToHydrate().
+   * This is a pure cache-warming operation - no queue mutation.
    */
-  private async fillHydratedQueue(): Promise<void> {
+  private async fillHydratedCards(): Promise<void> {
     if (this.hydrationInProgress) {
       return; // Prevent concurrent hydration
     }
@@ -97,53 +164,18 @@ export class CardHydrationService<TView = unknown> {
     this.hydrationInProgress = true;
 
     try {
-      while (this.hydratedQ.length < this.BUFFER_SIZE) {
-        const nextItem = this.selectNextItemToHydrate();
-        if (!nextItem) {
-          return; // No more cards to hydrate
+      const itemsToHydrate = this.getItemsToHydrate();
+
+      for (const item of itemsToHydrate) {
+        // Skip if already hydrated or in flight
+        if (this.hydratedCards.has(item.cardID) || this.hydrationInFlight.has(item.cardID)) {
+          continue;
         }
 
         try {
-          // Check cache first for failed cards
-          if (this.failedCardCache.has(nextItem.cardID)) {
-            const cachedCard = this.failedCardCache.get(nextItem.cardID)!;
-            this.hydratedQ.add(cachedCard, cachedCard.item.cardID);
-            this.failedCardCache.delete(nextItem.cardID);
-          } else {
-            // Hydrate new card using original logic pattern
-            const courseDB = this.getCourseDB(nextItem.courseID);
-            const cardData = await courseDB.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) =>
-                courseDB.getCourseDoc<DisplayableData>(id, {
-                  attachments: true,
-                  binary: true,
-                })
-              )
-            );
-
-            const data = dataDocs.map(displayableDataToViewData).reverse();
-
-            this.hydratedQ.add(
-              {
-                item: nextItem,
-                view,
-                data,
-              },
-              nextItem.cardID
-            );
-          }
+          await this.hydrateCard(item);
         } catch (e) {
-          logger.error(`Error hydrating card ${nextItem.cardID}:`, e);
-        } finally {
-          // Remove the item from the original queue, regardless of success/failure/cache
-          this.removeItemFromQueue(nextItem);
+          logger.error(`[CardHydrationService] Error hydrating card ${item.cardID}:`, e);
         }
       }
     } finally {
@@ -152,9 +184,61 @@ export class CardHydrationService<TView = unknown> {
   }
 
   /**
-   * Cache a failed card for quick re-access.
+   * Hydrate a single card and add to cache.
    */
-  public cacheFailedCard(card: HydratedCard<TView>): void {
-    this.failedCardCache.set(card.item.cardID, card);
+  private async hydrateCard(item: StudySessionItem): Promise<void> {
+    if (this.hydratedCards.has(item.cardID) || this.hydrationInFlight.has(item.cardID)) {
+      return; // Already hydrated or in progress
+    }
+
+    this.hydrationInFlight.add(item.cardID);
+
+    try {
+      const courseDB = this.getCourseDB(item.courseID);
+      const cardData = await courseDB.getCourseDoc<CardData>(item.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) =>
+          courseDB.getCourseDoc<DisplayableData>(id, {
+            attachments: true,
+            binary: true,
+          })
+        )
+      );
+
+      // Extract audio URLs from all data fields and prefetch them
+      const audioToPrefetch: string[] = [];
+      dataDocs.forEach((dd) => {
+        dd.data.forEach((f) => {
+          audioToPrefetch.push(...parseAudioURIs(f.data));
+        });
+      });
+
+      // Dedupe and prefetch, waiting for browser cache to be ready
+      const uniqueAudioUrls = [...new Set(audioToPrefetch)];
+      if (uniqueAudioUrls.length > 0) {
+        logger.debug(
+          `[CardHydrationService] Prefetching ${uniqueAudioUrls.length} audio files for card ${item.cardID}`
+        );
+        await Promise.allSettled(uniqueAudioUrls.map(prefetchAudio));
+      }
+
+      const data = dataDocs.map(displayableDataToViewData).reverse();
+
+      this.hydratedCards.set(item.cardID, {
+        item,
+        view,
+        data,
+      });
+
+      logger.debug(`[CardHydrationService] Hydrated card ${item.cardID}`);
+    } finally {
+      this.hydrationInFlight.delete(item.cardID);
+    }
   }
 }

package/src/util/dataDirectory.ts

@@ -4,7 +4,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
-import { logger } from './tuiLogger';
+import { logger } from './logger';
 import { ENV } from '@db/factory';
 
 /**

package/src/util/index.ts

@@ -2,4 +2,3 @@ export * from './Loggable';
 export * from './packer';
 export * from './migrator';
 export * from './dataDirectory';
-export * from './tuiLogger';