@vue-skuilder/db 0.1.16 → 0.1.18

package/dist/index.mjs

@@ -922,23 +922,460 @@ var init_courseLookupDB = __esm({
   }
 });
 
+// src/core/navigators/CompositeGenerator.ts
+var CompositeGenerator_exports = {};
+__export(CompositeGenerator_exports, {
+  AggregationMode: () => AggregationMode,
+  default: () => CompositeGenerator
+});
+var AggregationMode, DEFAULT_AGGREGATION_MODE, FREQUENCY_BOOST_FACTOR, CompositeGenerator;
+var init_CompositeGenerator = __esm({
+  "src/core/navigators/CompositeGenerator.ts"() {
+    "use strict";
+    init_navigators();
+    init_logger();
+    AggregationMode = /* @__PURE__ */ ((AggregationMode2) => {
+      AggregationMode2["MAX"] = "max";
+      AggregationMode2["AVERAGE"] = "average";
+      AggregationMode2["FREQUENCY_BOOST"] = "frequencyBoost";
+      return AggregationMode2;
+    })(AggregationMode || {});
+    DEFAULT_AGGREGATION_MODE = "frequencyBoost" /* FREQUENCY_BOOST */;
+    FREQUENCY_BOOST_FACTOR = 0.1;
+    CompositeGenerator = class _CompositeGenerator extends ContentNavigator {
+      /** Human-readable name for CardGenerator interface */
+      name = "Composite Generator";
+      generators;
+      aggregationMode;
+      constructor(generators, aggregationMode = DEFAULT_AGGREGATION_MODE) {
+        super();
+        this.generators = generators;
+        this.aggregationMode = aggregationMode;
+        if (generators.length === 0) {
+          throw new Error("CompositeGenerator requires at least one generator");
+        }
+        logger.debug(
+          `[CompositeGenerator] Created with ${generators.length} generators, mode: ${aggregationMode}`
+        );
+      }
+      /**
+       * Creates a CompositeGenerator from strategy data.
+       *
+       * This is a convenience factory for use by PipelineAssembler.
+       */
+      static async fromStrategies(user, course, strategies, aggregationMode = DEFAULT_AGGREGATION_MODE) {
+        const generators = await Promise.all(
+          strategies.map((s) => ContentNavigator.create(user, course, s))
+        );
+        return new _CompositeGenerator(generators, aggregationMode);
+      }
+      /**
+       * Get weighted cards from all generators, merge and deduplicate.
+       *
+       * Cards appearing in multiple generators receive a score boost.
+       * Provenance tracks which generators produced each card and how scores were aggregated.
+       *
+       * This method supports both the legacy signature (limit only) and the
+       * CardGenerator interface signature (limit, context).
+       *
+       * @param limit - Maximum number of cards to return
+       * @param context - Optional GeneratorContext passed to child generators
+       */
+      async getWeightedCards(limit, context) {
+        const results = await Promise.all(
+          this.generators.map((g) => g.getWeightedCards(limit, context))
+        );
+        const byCardId = /* @__PURE__ */ new Map();
+        for (const cards of results) {
+          for (const card of cards) {
+            const existing = byCardId.get(card.cardId) || [];
+            existing.push(card);
+            byCardId.set(card.cardId, existing);
+          }
+        }
+        const merged = [];
+        for (const [, cards] of byCardId) {
+          const aggregatedScore = this.aggregateScores(cards);
+          const finalScore = Math.min(1, aggregatedScore);
+          const mergedProvenance = cards.flatMap((c) => c.provenance);
+          const initialScore = cards[0].score;
+          const action = finalScore > initialScore ? "boosted" : finalScore < initialScore ? "penalized" : "passed";
+          const reason = this.buildAggregationReason(cards, finalScore);
+          merged.push({
+            ...cards[0],
+            score: finalScore,
+            provenance: [
+              ...mergedProvenance,
+              {
+                strategy: "composite",
+                strategyName: "Composite Generator",
+                strategyId: "COMPOSITE_GENERATOR",
+                action,
+                score: finalScore,
+                reason
+              }
+            ]
+          });
+        }
+        return merged.sort((a, b) => b.score - a.score).slice(0, limit);
+      }
+      /**
+       * Build human-readable reason for score aggregation.
+       */
+      buildAggregationReason(cards, finalScore) {
+        const count = cards.length;
+        const scores = cards.map((c) => c.score.toFixed(2)).join(", ");
+        if (count === 1) {
+          return `Single generator, score ${finalScore.toFixed(2)}`;
+        }
+        const strategies = cards.map((c) => c.provenance[0]?.strategy || "unknown").join(", ");
+        switch (this.aggregationMode) {
+          case "max" /* MAX */:
+            return `Max of ${count} generators (${strategies}): scores [${scores}] \u2192 ${finalScore.toFixed(2)}`;
+          case "average" /* AVERAGE */:
+            return `Average of ${count} generators (${strategies}): scores [${scores}] \u2192 ${finalScore.toFixed(2)}`;
+          case "frequencyBoost" /* FREQUENCY_BOOST */: {
+            const avg = cards.reduce((sum, c) => sum + c.score, 0) / count;
+            const boost = 1 + FREQUENCY_BOOST_FACTOR * (count - 1);
+            return `Frequency boost from ${count} generators (${strategies}): avg ${avg.toFixed(2)} \xD7 ${boost.toFixed(2)} \u2192 ${finalScore.toFixed(2)}`;
+          }
+          default:
+            return `Aggregated from ${count} generators: ${finalScore.toFixed(2)}`;
+        }
+      }
+      /**
+       * Aggregate scores from multiple generators for the same card.
+       */
+      aggregateScores(cards) {
+        const scores = cards.map((c) => c.score);
+        switch (this.aggregationMode) {
+          case "max" /* MAX */:
+            return Math.max(...scores);
+          case "average" /* AVERAGE */:
+            return scores.reduce((sum, s) => sum + s, 0) / scores.length;
+          case "frequencyBoost" /* FREQUENCY_BOOST */: {
+            const avg = scores.reduce((sum, s) => sum + s, 0) / scores.length;
+            const frequencyBoost = 1 + FREQUENCY_BOOST_FACTOR * (cards.length - 1);
+            return avg * frequencyBoost;
+          }
+          default:
+            return scores[0];
+        }
+      }
+      /**
+       * Get new cards from all generators, merged and deduplicated.
+       */
+      async getNewCards(n) {
+        const legacyGenerators = this.generators.filter(
+          (g) => g instanceof ContentNavigator
+        );
+        const results = await Promise.all(legacyGenerators.map((g) => g.getNewCards(n)));
+        const seen = /* @__PURE__ */ new Set();
+        const merged = [];
+        for (const cards of results) {
+          for (const card of cards) {
+            if (!seen.has(card.cardID)) {
+              seen.add(card.cardID);
+              merged.push(card);
+            }
+          }
+        }
+        return n ? merged.slice(0, n) : merged;
+      }
+      /**
+       * Get pending reviews from all generators, merged and deduplicated.
+       */
+      async getPendingReviews() {
+        const legacyGenerators = this.generators.filter(
+          (g) => g instanceof ContentNavigator
+        );
+        const results = await Promise.all(legacyGenerators.map((g) => g.getPendingReviews()));
+        const seen = /* @__PURE__ */ new Set();
+        const merged = [];
+        for (const reviews of results) {
+          for (const review of reviews) {
+            if (!seen.has(review.cardID)) {
+              seen.add(review.cardID);
+              merged.push(review);
+            }
+          }
+        }
+        return merged;
+      }
+    };
+  }
+});
+
+// src/core/navigators/Pipeline.ts
+var Pipeline_exports = {};
+__export(Pipeline_exports, {
+  Pipeline: () => Pipeline
+});
+import { toCourseElo as toCourseElo2 } from "@vue-skuilder/common";
+var Pipeline;
+var init_Pipeline = __esm({
+  "src/core/navigators/Pipeline.ts"() {
+    "use strict";
+    init_navigators();
+    init_logger();
+    Pipeline = class extends ContentNavigator {
+      generator;
+      filters;
+      /**
+       * Create a new pipeline.
+       *
+       * @param generator - The generator (or CompositeGenerator) that produces candidates
+       * @param filters - Filters to apply sequentially (order doesn't matter for multipliers)
+       * @param user - User database interface
+       * @param course - Course database interface
+       */
+      constructor(generator, filters, user, course) {
+        super();
+        this.generator = generator;
+        this.filters = filters;
+        this.user = user;
+        this.course = course;
+        logger.debug(
+          `[Pipeline] Created with generator '${generator.name}' and ${filters.length} filters: ${filters.map((f) => f.name).join(", ")}`
+        );
+      }
+      /**
+       * Get weighted cards by running generator and applying filters.
+       *
+       * 1. Build shared context (user ELO, etc.)
+       * 2. Get candidates from generator (passing context)
+       * 3. Apply each filter sequentially
+       * 4. Remove zero-score cards
+       * 5. Sort by score descending
+       * 6. Return top N
+       *
+       * @param limit - Maximum number of cards to return
+       * @returns Cards sorted by score descending
+       */
+      async getWeightedCards(limit) {
+        const context = await this.buildContext();
+        const overFetchMultiplier = 2 + this.filters.length * 0.5;
+        const fetchLimit = Math.ceil(limit * overFetchMultiplier);
+        logger.debug(
+          `[Pipeline] Fetching ${fetchLimit} candidates from generator '${this.generator.name}'`
+        );
+        let cards = await this.generator.getWeightedCards(fetchLimit, context);
+        logger.debug(`[Pipeline] Generator returned ${cards.length} candidates`);
+        for (const filter of this.filters) {
+          const beforeCount = cards.length;
+          cards = await filter.transform(cards, context);
+          logger.debug(`[Pipeline] Filter '${filter.name}': ${beforeCount} \u2192 ${cards.length} cards`);
+        }
+        cards = cards.filter((c) => c.score > 0);
+        cards.sort((a, b) => b.score - a.score);
+        const result = cards.slice(0, limit);
+        logger.debug(
+          `[Pipeline] Returning ${result.length} cards (top scores: ${result.slice(0, 3).map((c) => c.score.toFixed(2)).join(", ")}...)`
+        );
+        return result;
+      }
+      /**
+       * Build shared context for generator and filters.
+       *
+       * Called once per getWeightedCards() invocation.
+       * Contains data that the generator and multiple filters might need.
+       *
+       * The context satisfies both GeneratorContext and FilterContext interfaces.
+       */
+      async buildContext() {
+        let userElo = 1e3;
+        try {
+          const courseReg = await this.user.getCourseRegDoc(this.course.getCourseID());
+          const courseElo = toCourseElo2(courseReg.elo);
+          userElo = courseElo.global.score;
+        } catch (e) {
+          logger.debug(`[Pipeline] Could not get user ELO, using default: ${e}`);
+        }
+        return {
+          user: this.user,
+          course: this.course,
+          userElo
+        };
+      }
+      // ===========================================================================
+      // Legacy StudyContentSource methods
+      // ===========================================================================
+      //
+      // These delegate to the generator for backward compatibility.
+      // Eventually SessionController will use getWeightedCards() exclusively.
+      //
+      /**
+       * Get new cards via legacy API.
+       * Delegates to the generator if it supports the legacy interface.
+       */
+      async getNewCards(n) {
+        if ("getNewCards" in this.generator && typeof this.generator.getNewCards === "function") {
+          return this.generator.getNewCards(n);
+        }
+        return [];
+      }
+      /**
+       * Get pending reviews via legacy API.
+       * Delegates to the generator if it supports the legacy interface.
+       */
+      async getPendingReviews() {
+        if ("getPendingReviews" in this.generator && typeof this.generator.getPendingReviews === "function") {
+          return this.generator.getPendingReviews();
+        }
+        return [];
+      }
+      /**
+       * Get the course ID for this pipeline.
+       */
+      getCourseID() {
+        return this.course.getCourseID();
+      }
+    };
+  }
+});
+
+// src/core/navigators/PipelineAssembler.ts
+var PipelineAssembler_exports = {};
+__export(PipelineAssembler_exports, {
+  PipelineAssembler: () => PipelineAssembler
+});
+var PipelineAssembler;
+var init_PipelineAssembler = __esm({
+  "src/core/navigators/PipelineAssembler.ts"() {
+    "use strict";
+    init_navigators();
+    init_Pipeline();
+    init_types_legacy();
+    init_logger();
+    init_CompositeGenerator();
+    PipelineAssembler = class {
+      /**
+       * Assembles a navigation pipeline from strategy documents.
+       *
+       * 1. Separates into generators and filters by role
+       * 2. Validates at least one generator exists (or creates default ELO)
+       * 3. Instantiates generators - wraps multiple in CompositeGenerator
+       * 4. Instantiates filters
+       * 5. Returns Pipeline(generator, filters)
+       *
+       * @param input - Strategy documents plus user/course interfaces
+       * @returns Assembled pipeline and any warnings
+       */
+      async assemble(input) {
+        const { strategies, user, course } = input;
+        const warnings = [];
+        if (strategies.length === 0) {
+          return {
+            pipeline: null,
+            generatorStrategies: [],
+            filterStrategies: [],
+            warnings
+          };
+        }
+        const generatorStrategies = [];
+        const filterStrategies = [];
+        for (const s of strategies) {
+          if (isGenerator(s.implementingClass)) {
+            generatorStrategies.push(s);
+          } else if (isFilter(s.implementingClass)) {
+            filterStrategies.push(s);
+          } else {
+            warnings.push(`Unknown strategy type '${s.implementingClass}', skipping: ${s.name}`);
+          }
+        }
+        if (generatorStrategies.length === 0) {
+          if (filterStrategies.length > 0) {
+            logger.debug(
+              "[PipelineAssembler] No generator found, using default ELO with configured filters"
+            );
+            generatorStrategies.push(this.makeDefaultEloStrategy(course.getCourseID()));
+          } else {
+            warnings.push("No generator strategy found");
+            return {
+              pipeline: null,
+              generatorStrategies: [],
+              filterStrategies: [],
+              warnings
+            };
+          }
+        }
+        let generator;
+        if (generatorStrategies.length === 1) {
+          const nav = await ContentNavigator.create(user, course, generatorStrategies[0]);
+          generator = nav;
+          logger.debug(`[PipelineAssembler] Using single generator: ${generatorStrategies[0].name}`);
+        } else {
+          logger.debug(
+            `[PipelineAssembler] Using CompositeGenerator for ${generatorStrategies.length} generators: ${generatorStrategies.map((g) => g.name).join(", ")}`
+          );
+          generator = await CompositeGenerator.fromStrategies(user, course, generatorStrategies);
+        }
+        const filters = [];
+        const sortedFilterStrategies = [...filterStrategies].sort(
+          (a, b) => a.name.localeCompare(b.name)
+        );
+        for (const filterStrategy of sortedFilterStrategies) {
+          try {
+            const nav = await ContentNavigator.create(user, course, filterStrategy);
+            if ("transform" in nav && typeof nav.transform === "function") {
+              filters.push(nav);
+              logger.debug(`[PipelineAssembler] Added filter: ${filterStrategy.name}`);
+            } else {
+              warnings.push(
+                `Filter '${filterStrategy.name}' does not implement CardFilter.transform(), skipping`
+              );
+            }
+          } catch (e) {
+            warnings.push(`Failed to instantiate filter '${filterStrategy.name}': ${e}`);
+          }
+        }
+        const pipeline = new Pipeline(generator, filters, user, course);
+        logger.debug(
+          `[PipelineAssembler] Assembled pipeline with ${generatorStrategies.length} generator(s) and ${filters.length} filter(s)`
+        );
+        return {
+          pipeline,
+          generatorStrategies,
+          filterStrategies: sortedFilterStrategies,
+          warnings
+        };
+      }
+      /**
+       * Creates a default ELO generator strategy.
+       * Used when filters are configured but no generator is specified.
+       */
+      makeDefaultEloStrategy(courseId) {
+        return {
+          _id: "NAVIGATION_STRATEGY-ELO-default",
+          course: courseId,
+          docType: "NAVIGATION_STRATEGY" /* NAVIGATION_STRATEGY */,
+          name: "ELO (default)",
+          description: "Default ELO-based generator",
+          implementingClass: "elo" /* ELO */,
+          serializedData: ""
+        };
+      }
+    };
+  }
+});
+
 // src/core/navigators/elo.ts
 var elo_exports = {};
 __export(elo_exports, {
   default: () => ELONavigator
 });
+import { toCourseElo as toCourseElo3 } from "@vue-skuilder/common";
 var ELONavigator;
 var init_elo = __esm({
   "src/core/navigators/elo.ts"() {
     "use strict";
     init_navigators();
     ELONavigator = class extends ContentNavigator {
-      user;
-      course;
-      constructor(user, course) {
-        super();
-        this.user = user;
-        this.course = course;
+      /** Human-readable name for CardGenerator interface */
+      name;
+      constructor(user, course, strategyData) {
+        super(user, course, strategyData);
+        this.name = strategyData?.name || "ELO";
       }
       async getPendingReviews() {
         const reviews = await this.user.getPendingReviews(this.course.getCourseID());
@@ -984,10 +1421,154 @@ var init_elo = __esm({
           };
         });
       }
+      /**
+       * Get new cards with suitability scores based on ELO distance.
+       *
+       * Cards closer to user's ELO get higher scores.
+       * Score formula: max(0, 1 - distance / 500)
+       *
+       * NOTE: This generator only handles NEW cards. Reviews are handled by
+       * SRSNavigator. Use CompositeGenerator to combine both.
+       *
+       * This method supports both the legacy signature (limit only) and the
+       * CardGenerator interface signature (limit, context).
+       *
+       * @param limit - Maximum number of cards to return
+       * @param context - Optional GeneratorContext (used when called via Pipeline)
+       */
+      async getWeightedCards(limit, context) {
+        let userGlobalElo;
+        if (context?.userElo !== void 0) {
+          userGlobalElo = context.userElo;
+        } else {
+          const courseReg = await this.user.getCourseRegDoc(this.course.getCourseID());
+          const userElo = toCourseElo3(courseReg.elo);
+          userGlobalElo = userElo.global.score;
+        }
+        const newCards = await this.getNewCards(limit);
+        const cardIds = newCards.map((c) => c.cardID);
+        const cardEloData = await this.course.getCardEloData(cardIds);
+        const scored = newCards.map((c, i) => {
+          const cardElo = cardEloData[i]?.global?.score ?? 1e3;
+          const distance = Math.abs(cardElo - userGlobalElo);
+          const score = Math.max(0, 1 - distance / 500);
+          return {
+            cardId: c.cardID,
+            courseId: c.courseID,
+            score,
+            provenance: [
+              {
+                strategy: "elo",
+                strategyName: this.strategyName || this.name,
+                strategyId: this.strategyId || "NAVIGATION_STRATEGY-ELO-default",
+                action: "generated",
+                score,
+                reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userGlobalElo)}), new card`
+              }
+            ]
+          };
+        });
+        scored.sort((a, b) => b.score - a.score);
+        return scored.slice(0, limit);
+      }
     };
   }
 });
 
+// src/core/navigators/filters/eloDistance.ts
+var eloDistance_exports = {};
+__export(eloDistance_exports, {
+  DEFAULT_HALF_LIFE: () => DEFAULT_HALF_LIFE,
+  DEFAULT_MAX_MULTIPLIER: () => DEFAULT_MAX_MULTIPLIER,
+  DEFAULT_MIN_MULTIPLIER: () => DEFAULT_MIN_MULTIPLIER,
+  createEloDistanceFilter: () => createEloDistanceFilter
+});
+function computeMultiplier(distance, halfLife, minMultiplier, maxMultiplier) {
+  const normalizedDistance = distance / halfLife;
+  const decay = Math.exp(-(normalizedDistance * normalizedDistance));
+  return minMultiplier + (maxMultiplier - minMultiplier) * decay;
+}
+function createEloDistanceFilter(config) {
+  const halfLife = config?.halfLife ?? DEFAULT_HALF_LIFE;
+  const minMultiplier = config?.minMultiplier ?? DEFAULT_MIN_MULTIPLIER;
+  const maxMultiplier = config?.maxMultiplier ?? DEFAULT_MAX_MULTIPLIER;
+  return {
+    name: "ELO Distance Filter",
+    async transform(cards, context) {
+      const { course, userElo } = context;
+      const cardIds = cards.map((c) => c.cardId);
+      const cardElos = await course.getCardEloData(cardIds);
+      return cards.map((card, i) => {
+        const cardElo = cardElos[i]?.global?.score ?? 1e3;
+        const distance = Math.abs(cardElo - userElo);
+        const multiplier = computeMultiplier(distance, halfLife, minMultiplier, maxMultiplier);
+        const newScore = card.score * multiplier;
+        const action = multiplier < maxMultiplier - 0.01 ? "penalized" : "passed";
+        return {
+          ...card,
+          score: newScore,
+          provenance: [
+            ...card.provenance,
+            {
+              strategy: "eloDistance",
+              strategyName: "ELO Distance Filter",
+              strategyId: "ELO_DISTANCE_FILTER",
+              action,
+              score: newScore,
+              reason: `ELO distance ${Math.round(distance)} (card: ${Math.round(cardElo)}, user: ${Math.round(userElo)}) \u2192 ${multiplier.toFixed(2)}x`
+            }
+          ]
+        };
+      });
+    }
+  };
+}
+var DEFAULT_HALF_LIFE, DEFAULT_MIN_MULTIPLIER, DEFAULT_MAX_MULTIPLIER;
+var init_eloDistance = __esm({
+  "src/core/navigators/filters/eloDistance.ts"() {
+    "use strict";
+    DEFAULT_HALF_LIFE = 200;
+    DEFAULT_MIN_MULTIPLIER = 0.3;
+    DEFAULT_MAX_MULTIPLIER = 1;
+  }
+});
+
+// src/core/navigators/filters/index.ts
+var filters_exports = {};
+__export(filters_exports, {
+  createEloDistanceFilter: () => createEloDistanceFilter
+});
+var init_filters = __esm({
+  "src/core/navigators/filters/index.ts"() {
+    "use strict";
+    init_eloDistance();
+  }
+});
+
+// src/core/navigators/filters/types.ts
+var types_exports = {};
+var init_types = __esm({
+  "src/core/navigators/filters/types.ts"() {
+    "use strict";
+  }
+});
+
+// src/core/navigators/generators/index.ts
+var generators_exports = {};
+var init_generators = __esm({
+  "src/core/navigators/generators/index.ts"() {
+    "use strict";
+  }
+});
+
+// src/core/navigators/generators/types.ts
+var types_exports2 = {};
+var init_types2 = __esm({
+  "src/core/navigators/generators/types.ts"() {
+    "use strict";
+  }
+});
+
 // src/core/navigators/hardcodedOrder.ts
 var hardcodedOrder_exports = {};
 __export(hardcodedOrder_exports, {
@@ -1000,13 +1581,12 @@ var init_hardcodedOrder = __esm({
     init_navigators();
     init_logger();
     HardcodedOrderNavigator = class extends ContentNavigator {
+      /** Human-readable name for CardGenerator interface */
+      name;
       orderedCardIds = [];
-      user;
-      course;
       constructor(user, course, strategyData) {
-        super();
-        this.user = user;
-        this.course = course;
+        super(user, course, strategyData);
+        this.name = strategyData.name || "Hardcoded Order";
         if (strategyData.serializedData) {
           try {
             this.orderedCardIds = JSON.parse(strategyData.serializedData);
@@ -1014,36 +1594,792 @@ var init_hardcodedOrder = __esm({
             logger.error("Failed to parse serializedData for HardcodedOrderNavigator", e);
           }
         }
-      }
-      async getPendingReviews() {
+      }
+      async getPendingReviews() {
+        const reviews = await this.user.getPendingReviews(this.course.getCourseID());
+        return reviews.map((r) => {
+          return {
+            ...r,
+            contentSourceType: "course",
+            contentSourceID: this.course.getCourseID(),
+            cardID: r.cardId,
+            courseID: r.courseId,
+            reviewID: r._id,
+            status: "review"
+          };
+        });
+      }
+      async getNewCards(limit = 99) {
+        const activeCardIds = (await this.user.getActiveCards()).map((c) => c.cardID);
+        const newCardIds = this.orderedCardIds.filter((cardId) => !activeCardIds.includes(cardId));
+        const cardsToReturn = newCardIds.slice(0, limit);
+        return cardsToReturn.map((cardId) => {
+          return {
+            cardID: cardId,
+            courseID: this.course.getCourseID(),
+            contentSourceType: "course",
+            contentSourceID: this.course.getCourseID(),
+            status: "new"
+          };
+        });
+      }
+      /**
+       * Get cards in hardcoded order with scores based on position.
+       *
+       * Earlier cards in the sequence get higher scores.
+       * Score formula: 1.0 - (position / totalCards) * 0.5
+       * This ensures scores range from 1.0 (first card) to 0.5+ (last card).
+       *
+       * This method supports both the legacy signature (limit only) and the
+       * CardGenerator interface signature (limit, context).
+       *
+       * @param limit - Maximum number of cards to return
+       * @param _context - Optional GeneratorContext (currently unused, but required for interface)
+       */
+      async getWeightedCards(limit, _context) {
+        const activeCardIds = (await this.user.getActiveCards()).map((c) => c.cardID);
+        const reviews = await this.getPendingReviews();
+        const newCardIds = this.orderedCardIds.filter((cardId) => !activeCardIds.includes(cardId));
+        const totalCards = newCardIds.length;
+        const scoredNew = newCardIds.slice(0, limit).map((cardId, index) => {
+          const position = index + 1;
+          const score = Math.max(0.5, 1 - index / totalCards * 0.5);
+          return {
+            cardId,
+            courseId: this.course.getCourseID(),
+            score,
+            provenance: [
+              {
+                strategy: "hardcodedOrder",
+                strategyName: this.strategyName || this.name,
+                strategyId: this.strategyId || "NAVIGATION_STRATEGY-hardcoded",
+                action: "generated",
+                score,
+                reason: `Position ${position} of ${totalCards} in fixed sequence, new card`
+              }
+            ]
+          };
+        });
+        const scoredReviews = reviews.map((r) => ({
+          cardId: r.cardID,
+          courseId: r.courseID,
+          score: 1,
+          provenance: [
+            {
+              strategy: "hardcodedOrder",
+              strategyName: this.strategyName || this.name,
+              strategyId: this.strategyId || "NAVIGATION_STRATEGY-hardcoded",
+              action: "generated",
+              score: 1,
+              reason: "Scheduled review, highest priority"
+            }
+          ]
+        }));
+        const all = [...scoredReviews, ...scoredNew];
+        all.sort((a, b) => b.score - a.score);
+        return all.slice(0, limit);
+      }
+    };
+  }
+});
+
+// src/core/navigators/hierarchyDefinition.ts
+var hierarchyDefinition_exports = {};
+__export(hierarchyDefinition_exports, {
+  default: () => HierarchyDefinitionNavigator
+});
+import { toCourseElo as toCourseElo4 } from "@vue-skuilder/common";
+var DEFAULT_MIN_COUNT, HierarchyDefinitionNavigator;
+var init_hierarchyDefinition = __esm({
+  "src/core/navigators/hierarchyDefinition.ts"() {
+    "use strict";
+    init_navigators();
+    DEFAULT_MIN_COUNT = 3;
+    HierarchyDefinitionNavigator = class extends ContentNavigator {
+      config;
+      _strategyData;
+      /** Human-readable name for CardFilter interface */
+      name;
+      constructor(user, course, _strategyData) {
+        super(user, course, _strategyData);
+        this._strategyData = _strategyData;
+        this.config = this.parseConfig(_strategyData.serializedData);
+        this.name = _strategyData.name || "Hierarchy Definition";
+      }
+      parseConfig(serializedData) {
+        try {
+          const parsed = JSON.parse(serializedData);
+          return {
+            prerequisites: parsed.prerequisites || {}
+          };
+        } catch {
+          return {
+            prerequisites: {}
+          };
+        }
+      }
+      /**
+       * Check if a specific prerequisite is satisfied
+       */
+      isPrerequisiteMet(prereq, userTagElo, userGlobalElo) {
+        if (!userTagElo) return false;
+        const minCount = prereq.masteryThreshold?.minCount ?? DEFAULT_MIN_COUNT;
+        if (userTagElo.count < minCount) return false;
+        if (prereq.masteryThreshold?.minElo !== void 0) {
+          return userTagElo.score >= prereq.masteryThreshold.minElo;
+        } else {
+          return userTagElo.score >= userGlobalElo;
+        }
+      }
+      /**
+       * Get the set of tags the user has mastered.
+       * A tag is "mastered" if it appears as a prerequisite somewhere and meets its threshold.
+       */
+      async getMasteredTags(context) {
+        const mastered = /* @__PURE__ */ new Set();
+        try {
+          const courseReg = await context.user.getCourseRegDoc(context.course.getCourseID());
+          const userElo = toCourseElo4(courseReg.elo);
+          for (const prereqs of Object.values(this.config.prerequisites)) {
+            for (const prereq of prereqs) {
+              const tagElo = userElo.tags[prereq.tag];
+              if (this.isPrerequisiteMet(prereq, tagElo, userElo.global.score)) {
+                mastered.add(prereq.tag);
+              }
+            }
+          }
+        } catch {
+        }
+        return mastered;
+      }
+      /**
+       * Get the set of tags that are unlocked (prerequisites met)
+       */
+      getUnlockedTags(masteredTags) {
+        const unlocked = /* @__PURE__ */ new Set();
+        for (const [tagId, prereqs] of Object.entries(this.config.prerequisites)) {
+          const allPrereqsMet = prereqs.every((prereq) => masteredTags.has(prereq.tag));
+          if (allPrereqsMet) {
+            unlocked.add(tagId);
+          }
+        }
+        return unlocked;
+      }
+      /**
+       * Check if a tag has prerequisites defined in config
+       */
+      hasPrerequisites(tagId) {
+        return tagId in this.config.prerequisites;
+      }
+      /**
+       * Check if a card is unlocked and generate reason.
+       */
+      async checkCardUnlock(cardId, course, unlockedTags, masteredTags) {
+        try {
+          const tagResponse = await course.getAppliedTags(cardId);
+          const cardTags = tagResponse.rows.map((row) => row.value?.name || row.key);
+          const lockedTags = cardTags.filter(
+            (tag) => this.hasPrerequisites(tag) && !unlockedTags.has(tag)
+          );
+          if (lockedTags.length === 0) {
+            const tagList = cardTags.length > 0 ? cardTags.join(", ") : "none";
+            return {
+              isUnlocked: true,
+              reason: `Prerequisites met, tags: ${tagList}`
+            };
+          }
+          const missingPrereqs = lockedTags.flatMap((tag) => {
+            const prereqs = this.config.prerequisites[tag] || [];
+            return prereqs.filter((p) => !masteredTags.has(p.tag)).map((p) => p.tag);
+          });
+          return {
+            isUnlocked: false,
+            reason: `Blocked: missing prerequisites ${missingPrereqs.join(", ")} for tags ${lockedTags.join(", ")}`
+          };
+        } catch {
+          return {
+            isUnlocked: true,
+            reason: "Prerequisites check skipped (tag lookup failed)"
+          };
+        }
+      }
+      /**
+       * CardFilter.transform implementation.
+       *
+       * Apply prerequisite gating to cards. Cards with locked tags receive score: 0.
+       */
+      async transform(cards, context) {
+        const masteredTags = await this.getMasteredTags(context);
+        const unlockedTags = this.getUnlockedTags(masteredTags);
+        const gated = [];
+        for (const card of cards) {
+          const { isUnlocked, reason } = await this.checkCardUnlock(
+            card.cardId,
+            context.course,
+            unlockedTags,
+            masteredTags
+          );
+          const finalScore = isUnlocked ? card.score : 0;
+          const action = isUnlocked ? "passed" : "penalized";
+          gated.push({
+            ...card,
+            score: finalScore,
+            provenance: [
+              ...card.provenance,
+              {
+                strategy: "hierarchyDefinition",
+                strategyName: this.strategyName || this.name,
+                strategyId: this.strategyId || "NAVIGATION_STRATEGY-hierarchy",
+                action,
+                score: finalScore,
+                reason
+              }
+            ]
+          });
+        }
+        return gated;
+      }
+      /**
+       * Legacy getWeightedCards - now throws as filters should not be used as generators.
+       *
+       * Use transform() via Pipeline instead.
+       */
+      async getWeightedCards(_limit) {
+        throw new Error(
+          "HierarchyDefinitionNavigator is a filter and should not be used as a generator. Use Pipeline with a generator and this filter via transform()."
+        );
+      }
+      // Legacy methods - stub implementations since filters don't generate cards
+      async getNewCards(_n) {
+        return [];
+      }
+      async getPendingReviews() {
+        return [];
+      }
+    };
+  }
+});
+
+// src/core/navigators/interferenceMitigator.ts
+var interferenceMitigator_exports = {};
+__export(interferenceMitigator_exports, {
+  default: () => InterferenceMitigatorNavigator
+});
+import { toCourseElo as toCourseElo5 } from "@vue-skuilder/common";
+var DEFAULT_MIN_COUNT2, DEFAULT_MIN_ELAPSED_DAYS, DEFAULT_INTERFERENCE_DECAY, InterferenceMitigatorNavigator;
+var init_interferenceMitigator = __esm({
+  "src/core/navigators/interferenceMitigator.ts"() {
+    "use strict";
+    init_navigators();
+    DEFAULT_MIN_COUNT2 = 10;
+    DEFAULT_MIN_ELAPSED_DAYS = 3;
+    DEFAULT_INTERFERENCE_DECAY = 0.8;
+    InterferenceMitigatorNavigator = class extends ContentNavigator {
+      config;
+      _strategyData;
+      /** Human-readable name for CardFilter interface */
+      name;
+      /** Precomputed map: tag -> set of { partner, decay } it interferes with */
+      interferenceMap;
+      constructor(user, course, _strategyData) {
+        super(user, course, _strategyData);
+        this._strategyData = _strategyData;
+        this.config = this.parseConfig(_strategyData.serializedData);
+        this.interferenceMap = this.buildInterferenceMap();
+        this.name = _strategyData.name || "Interference Mitigator";
+      }
+      parseConfig(serializedData) {
+        try {
+          const parsed = JSON.parse(serializedData);
+          let sets = parsed.interferenceSets || [];
+          if (sets.length > 0 && Array.isArray(sets[0])) {
+            sets = sets.map((tags) => ({ tags }));
+          }
+          return {
+            interferenceSets: sets,
+            maturityThreshold: {
+              minCount: parsed.maturityThreshold?.minCount ?? DEFAULT_MIN_COUNT2,
+              minElo: parsed.maturityThreshold?.minElo,
+              minElapsedDays: parsed.maturityThreshold?.minElapsedDays ?? DEFAULT_MIN_ELAPSED_DAYS
+            },
+            defaultDecay: parsed.defaultDecay ?? DEFAULT_INTERFERENCE_DECAY
+          };
+        } catch {
+          return {
+            interferenceSets: [],
+            maturityThreshold: {
+              minCount: DEFAULT_MIN_COUNT2,
+              minElapsedDays: DEFAULT_MIN_ELAPSED_DAYS
+            },
+            defaultDecay: DEFAULT_INTERFERENCE_DECAY
+          };
+        }
+      }
+      /**
+       * Build a map from each tag to its interference partners with decay coefficients.
+       * If tags A, B, C are in an interference group with decay 0.8, then:
+       * - A interferes with B (decay 0.8) and C (decay 0.8)
+       * - B interferes with A (decay 0.8) and C (decay 0.8)
+       * - etc.
+       */
+      buildInterferenceMap() {
+        const map = /* @__PURE__ */ new Map();
+        for (const group of this.config.interferenceSets) {
+          const decay = group.decay ?? this.config.defaultDecay ?? DEFAULT_INTERFERENCE_DECAY;
+          for (const tag of group.tags) {
+            if (!map.has(tag)) {
+              map.set(tag, []);
+            }
+            const partners = map.get(tag);
+            for (const other of group.tags) {
+              if (other !== tag) {
+                const existing = partners.find((p) => p.partner === other);
+                if (existing) {
+                  existing.decay = Math.max(existing.decay, decay);
+                } else {
+                  partners.push({ partner: other, decay });
+                }
+              }
+            }
+          }
+        }
+        return map;
+      }
+      /**
+       * Get the set of tags that are currently immature for this user.
+       * A tag is immature if the user has interacted with it but hasn't
+       * reached the maturity threshold.
+       */
+      async getImmatureTags(context) {
+        const immature = /* @__PURE__ */ new Set();
+        try {
+          const courseReg = await context.user.getCourseRegDoc(context.course.getCourseID());
+          const userElo = toCourseElo5(courseReg.elo);
+          const minCount = this.config.maturityThreshold?.minCount ?? DEFAULT_MIN_COUNT2;
+          const minElo = this.config.maturityThreshold?.minElo;
+          const minElapsedDays = this.config.maturityThreshold?.minElapsedDays ?? DEFAULT_MIN_ELAPSED_DAYS;
+          const minCountForElapsed = minElapsedDays * 2;
+          for (const [tagId, tagElo] of Object.entries(userElo.tags)) {
+            if (tagElo.count === 0) continue;
+            const belowCount = tagElo.count < minCount;
+            const belowElo = minElo !== void 0 && tagElo.score < minElo;
+            const belowElapsed = tagElo.count < minCountForElapsed;
+            if (belowCount || belowElo || belowElapsed) {
+              immature.add(tagId);
+            }
+          }
+        } catch {
+        }
+        return immature;
+      }
+      /**
+       * Get all tags that interfere with any immature tag, along with their decay coefficients.
+       * These are the tags we want to avoid introducing.
+       */
+      getTagsToAvoid(immatureTags) {
+        const avoid = /* @__PURE__ */ new Map();
+        for (const immatureTag of immatureTags) {
+          const partners = this.interferenceMap.get(immatureTag);
+          if (partners) {
+            for (const { partner, decay } of partners) {
+              if (!immatureTags.has(partner)) {
+                const existing = avoid.get(partner) ?? 0;
+                avoid.set(partner, Math.max(existing, decay));
+              }
+            }
+          }
+        }
+        return avoid;
+      }
+      /**
+       * Get tags for a single card
+       */
+      async getCardTags(cardId, course) {
+        try {
+          const tagResponse = await course.getAppliedTags(cardId);
+          return tagResponse.rows.map((row) => row.value?.name || row.key).filter(Boolean);
+        } catch {
+          return [];
+        }
+      }
+      /**
+       * Compute interference score reduction for a card.
+       * Returns: { multiplier, interfering tags, reason }
+       */
+      computeInterferenceEffect(cardTags, tagsToAvoid, immatureTags) {
+        if (tagsToAvoid.size === 0) {
+          return {
+            multiplier: 1,
+            interferingTags: [],
+            reason: "No interference detected"
+          };
+        }
+        let multiplier = 1;
+        const interferingTags = [];
+        for (const tag of cardTags) {
+          const decay = tagsToAvoid.get(tag);
+          if (decay !== void 0) {
+            interferingTags.push(tag);
+            multiplier *= 1 - decay;
+          }
+        }
+        if (interferingTags.length === 0) {
+          return {
+            multiplier: 1,
+            interferingTags: [],
+            reason: "No interference detected"
+          };
+        }
+        const causingTags = /* @__PURE__ */ new Set();
+        for (const tag of interferingTags) {
+          for (const immatureTag of immatureTags) {
+            const partners = this.interferenceMap.get(immatureTag);
+            if (partners?.some((p) => p.partner === tag)) {
+              causingTags.add(immatureTag);
+            }
+          }
+        }
+        const reason = `Interferes with immature tags ${Array.from(causingTags).join(", ")} (tags: ${interferingTags.join(", ")}, multiplier: ${multiplier.toFixed(2)})`;
+        return { multiplier, interferingTags, reason };
+      }
+      /**
+       * CardFilter.transform implementation.
+       *
+       * Apply interference-aware scoring. Cards with tags that interfere with
+       * immature learnings get reduced scores.
+       */
+      async transform(cards, context) {
+        const immatureTags = await this.getImmatureTags(context);
+        const tagsToAvoid = this.getTagsToAvoid(immatureTags);
+        const adjusted = [];
+        for (const card of cards) {
+          const cardTags = await this.getCardTags(card.cardId, context.course);
+          const { multiplier, reason } = this.computeInterferenceEffect(
+            cardTags,
+            tagsToAvoid,
+            immatureTags
+          );
+          const finalScore = card.score * multiplier;
+          const action = multiplier < 1 ? "penalized" : multiplier > 1 ? "boosted" : "passed";
+          adjusted.push({
+            ...card,
+            score: finalScore,
+            provenance: [
+              ...card.provenance,
+              {
+                strategy: "interferenceMitigator",
+                strategyName: this.strategyName || this.name,
+                strategyId: this.strategyId || "NAVIGATION_STRATEGY-interference",
+                action,
+                score: finalScore,
+                reason
+              }
+            ]
+          });
+        }
+        return adjusted;
+      }
+      /**
+       * Legacy getWeightedCards - now throws as filters should not be used as generators.
+       *
+       * Use transform() via Pipeline instead.
+       */
+      async getWeightedCards(_limit) {
+        throw new Error(
+          "InterferenceMitigatorNavigator is a filter and should not be used as a generator. Use Pipeline with a generator and this filter via transform()."
+        );
+      }
+      // Legacy methods - stub implementations since filters don't generate cards
+      async getNewCards(_n) {
+        return [];
+      }
+      async getPendingReviews() {
+        return [];
+      }
+    };
+  }
+});
+
+// src/core/navigators/relativePriority.ts
+var relativePriority_exports = {};
+__export(relativePriority_exports, {
+  default: () => RelativePriorityNavigator
+});
+var DEFAULT_PRIORITY, DEFAULT_PRIORITY_INFLUENCE, DEFAULT_COMBINE_MODE, RelativePriorityNavigator;
+var init_relativePriority = __esm({
+  "src/core/navigators/relativePriority.ts"() {
+    "use strict";
+    init_navigators();
+    DEFAULT_PRIORITY = 0.5;
+    DEFAULT_PRIORITY_INFLUENCE = 0.5;
+    DEFAULT_COMBINE_MODE = "max";
+    RelativePriorityNavigator = class extends ContentNavigator {
+      config;
+      _strategyData;
+      /** Human-readable name for CardFilter interface */
+      name;
+      constructor(user, course, _strategyData) {
+        super(user, course, _strategyData);
+        this._strategyData = _strategyData;
+        this.config = this.parseConfig(_strategyData.serializedData);
+        this.name = _strategyData.name || "Relative Priority";
+      }
+      parseConfig(serializedData) {
+        try {
+          const parsed = JSON.parse(serializedData);
+          return {
+            tagPriorities: parsed.tagPriorities || {},
+            defaultPriority: parsed.defaultPriority ?? DEFAULT_PRIORITY,
+            combineMode: parsed.combineMode ?? DEFAULT_COMBINE_MODE,
+            priorityInfluence: parsed.priorityInfluence ?? DEFAULT_PRIORITY_INFLUENCE
+          };
+        } catch {
+          return {
+            tagPriorities: {},
+            defaultPriority: DEFAULT_PRIORITY,
+            combineMode: DEFAULT_COMBINE_MODE,
+            priorityInfluence: DEFAULT_PRIORITY_INFLUENCE
+          };
+        }
+      }
+      /**
+       * Look up the priority for a tag.
+       */
+      getTagPriority(tagId) {
+        return this.config.tagPriorities[tagId] ?? this.config.defaultPriority ?? DEFAULT_PRIORITY;
+      }
+      /**
+       * Compute combined priority for a card based on its tags.
+       */
+      computeCardPriority(cardTags) {
+        if (cardTags.length === 0) {
+          return this.config.defaultPriority ?? DEFAULT_PRIORITY;
+        }
+        const priorities = cardTags.map((tag) => this.getTagPriority(tag));
+        switch (this.config.combineMode) {
+          case "max":
+            return Math.max(...priorities);
+          case "min":
+            return Math.min(...priorities);
+          case "average":
+            return priorities.reduce((sum, p) => sum + p, 0) / priorities.length;
+          default:
+            return Math.max(...priorities);
+        }
+      }
+      /**
+       * Compute boost factor based on priority.
+       *
+       * The formula: 1 + (priority - 0.5) * priorityInfluence
+       *
+       * This creates a multiplier centered around 1.0:
+       * - Priority 1.0 with influence 0.5 → 1.25 (25% boost)
+       * - Priority 0.5 with any influence → 1.00 (neutral)
+       * - Priority 0.0 with influence 0.5 → 0.75 (25% reduction)
+       */
+      computeBoostFactor(priority) {
+        const influence = this.config.priorityInfluence ?? DEFAULT_PRIORITY_INFLUENCE;
+        return 1 + (priority - 0.5) * influence;
+      }
+      /**
+       * Build human-readable reason for priority adjustment.
+       */
+      buildPriorityReason(cardTags, priority, boostFactor, finalScore) {
+        if (cardTags.length === 0) {
+          return `No tags, neutral priority (${priority.toFixed(2)})`;
+        }
+        const tagList = cardTags.slice(0, 3).join(", ");
+        const more = cardTags.length > 3 ? ` (+${cardTags.length - 3} more)` : "";
+        if (boostFactor === 1) {
+          return `Neutral priority (${priority.toFixed(2)}) for tags: ${tagList}${more}`;
+        } else if (boostFactor > 1) {
+          return `High-priority tags: ${tagList}${more} (priority ${priority.toFixed(2)} \u2192 boost ${boostFactor.toFixed(2)}x \u2192 ${finalScore.toFixed(2)})`;
+        } else {
+          return `Low-priority tags: ${tagList}${more} (priority ${priority.toFixed(2)} \u2192 reduce ${boostFactor.toFixed(2)}x \u2192 ${finalScore.toFixed(2)})`;
+        }
+      }
+      /**
+       * Get tags for a single card.
+       */
+      async getCardTags(cardId, course) {
+        try {
+          const tagResponse = await course.getAppliedTags(cardId);
+          return tagResponse.rows.map((r) => r.doc?.name).filter((x) => !!x);
+        } catch {
+          return [];
+        }
+      }
+      /**
+       * CardFilter.transform implementation.
+       *
+       * Apply priority-adjusted scoring. Cards with high-priority tags get boosted,
+       * cards with low-priority tags get reduced scores.
+       */
+      async transform(cards, context) {
+        const adjusted = await Promise.all(
+          cards.map(async (card) => {
+            const cardTags = await this.getCardTags(card.cardId, context.course);
+            const priority = this.computeCardPriority(cardTags);
+            const boostFactor = this.computeBoostFactor(priority);
+            const finalScore = Math.max(0, Math.min(1, card.score * boostFactor));
+            const action = boostFactor > 1 ? "boosted" : boostFactor < 1 ? "penalized" : "passed";
+            const reason = this.buildPriorityReason(cardTags, priority, boostFactor, finalScore);
+            return {
+              ...card,
+              score: finalScore,
+              provenance: [
+                ...card.provenance,
+                {
+                  strategy: "relativePriority",
+                  strategyName: this.strategyName || this.name,
+                  strategyId: this.strategyId || "NAVIGATION_STRATEGY-priority",
+                  action,
+                  score: finalScore,
+                  reason
+                }
+              ]
+            };
+          })
+        );
+        return adjusted;
+      }
+      /**
+       * Legacy getWeightedCards - now throws as filters should not be used as generators.
+       *
+       * Use transform() via Pipeline instead.
+       */
+      async getWeightedCards(_limit) {
+        throw new Error(
+          "RelativePriorityNavigator is a filter and should not be used as a generator. Use Pipeline with a generator and this filter via transform()."
+        );
+      }
+      // Legacy methods - stub implementations since filters don't generate cards
+      async getNewCards(_n) {
+        return [];
+      }
+      async getPendingReviews() {
+        return [];
+      }
+    };
+  }
+});
+
+// src/core/navigators/srs.ts
+var srs_exports = {};
+__export(srs_exports, {
+  default: () => SRSNavigator
+});
+import moment3 from "moment";
+var SRSNavigator;
+var init_srs = __esm({
+  "src/core/navigators/srs.ts"() {
+    "use strict";
+    init_navigators();
+    SRSNavigator = class extends ContentNavigator {
+      /** Human-readable name for CardGenerator interface */
+      name;
+      constructor(user, course, strategyData) {
+        super(user, course, strategyData);
+        this.name = strategyData?.name || "SRS";
+      }
+      /**
+       * Get review cards scored by urgency.
+       *
+       * Score formula combines:
+       * - Relative overdueness: hoursOverdue / intervalHours
+       * - Interval recency: exponential decay favoring shorter intervals
+       *
+       * Cards not yet due are excluded (not scored as 0).
+       *
+       * This method supports both the legacy signature (limit only) and the
+       * CardGenerator interface signature (limit, context).
+       *
+       * @param limit - Maximum number of cards to return
+       * @param _context - Optional GeneratorContext (currently unused, but required for interface)
+       */
+      async getWeightedCards(limit, _context) {
+        if (!this.user || !this.course) {
+          throw new Error("SRSNavigator requires user and course to be set");
+        }
         const reviews = await this.user.getPendingReviews(this.course.getCourseID());
-        return reviews.map((r) => {
+        const now = moment3.utc();
+        const dueReviews = reviews.filter((r) => now.isAfter(moment3.utc(r.reviewTime)));
+        const scored = dueReviews.map((review) => {
+          const { score, reason } = this.computeUrgencyScore(review, now);
           return {
-            ...r,
-            contentSourceType: "course",
-            contentSourceID: this.course.getCourseID(),
-            cardID: r.cardId,
-            courseID: r.courseId,
-            reviewID: r._id,
-            status: "review"
+            cardId: review.cardId,
+            courseId: review.courseId,
+            score,
+            provenance: [
+              {
+                strategy: "srs",
+                strategyName: this.strategyName || this.name,
+                strategyId: this.strategyId || "NAVIGATION_STRATEGY-SRS-default",
+                action: "generated",
+                score,
+                reason
+              }
+            ]
           };
         });
+        return scored.sort((a, b) => b.score - a.score).slice(0, limit);
       }
-      async getNewCards(limit = 99) {
-        const activeCardIds = (await this.user.getActiveCards()).map((c) => c.cardID);
-        const newCardIds = this.orderedCardIds.filter(
-          (cardId) => !activeCardIds.includes(cardId)
-        );
-        const cardsToReturn = newCardIds.slice(0, limit);
-        return cardsToReturn.map((cardId) => {
-          return {
-            cardID: cardId,
-            courseID: this.course.getCourseID(),
-            contentSourceType: "course",
-            contentSourceID: this.course.getCourseID(),
-            status: "new"
-          };
-        });
+      /**
+       * Compute urgency score for a review card.
+       *
+       * Two factors:
+       * 1. Relative overdueness = hoursOverdue / intervalHours
+       *    - 2 days overdue on 3-day interval = 0.67 (urgent)
+       *    - 2 days overdue on 180-day interval = 0.01 (not urgent)
+       *
+       * 2. Interval recency factor = 0.3 + 0.7 * exp(-intervalHours / 720)
+       *    - 24h interval → ~1.0 (very recent learning)
+       *    - 30 days (720h) → ~0.56
+       *    - 180 days → ~0.30
+       *
+       * Combined: base 0.5 + weighted average of factors * 0.45
+       * Result range: approximately 0.5 to 0.95
+       */
+      computeUrgencyScore(review, now) {
+        const scheduledAt = moment3.utc(review.scheduledAt);
+        const due = moment3.utc(review.reviewTime);
+        const intervalHours = Math.max(1, due.diff(scheduledAt, "hours"));
+        const hoursOverdue = now.diff(due, "hours");
+        const relativeOverdue = hoursOverdue / intervalHours;
+        const recencyFactor = 0.3 + 0.7 * Math.exp(-intervalHours / 720);
+        const overdueContribution = Math.min(1, Math.max(0, relativeOverdue));
+        const urgency = overdueContribution * 0.5 + recencyFactor * 0.5;
+        const score = Math.min(0.95, 0.5 + urgency * 0.45);
+        const reason = `${Math.round(hoursOverdue)}h overdue (interval: ${Math.round(intervalHours)}h, relative: ${relativeOverdue.toFixed(2)}), recency: ${recencyFactor.toFixed(2)}, review`;
+        return { score, reason };
+      }
+      /**
+       * Get pending reviews in legacy format.
+       *
+       * Returns all pending reviews for the course, enriched with session item fields.
+       */
+      async getPendingReviews() {
+        if (!this.user || !this.course) {
+          throw new Error("SRSNavigator requires user and course to be set");
+        }
+        const reviews = await this.user.getPendingReviews(this.course.getCourseID());
+        return reviews.map((r) => ({
+          ...r,
+          contentSourceType: "course",
+          contentSourceID: this.course.getCourseID(),
+          cardID: r.cardId,
+          courseID: r.courseId,
+          qualifiedID: `${r.courseId}-${r.cardId}`,
+          reviewID: r._id,
+          status: "review"
+        }));
+      }
+      /**
+       * SRS does not generate new cards.
+       * Use ELONavigator or another generator for new cards.
+       */
+      async getNewCards(_n) {
+        return [];
       }
     };
   }
@@ -1054,9 +2390,21 @@ var globImport;
 var init_ = __esm({
   'import("./**/*") in src/core/navigators/index.ts'() {
     globImport = __glob({
+      "./CompositeGenerator.ts": () => Promise.resolve().then(() => (init_CompositeGenerator(), CompositeGenerator_exports)),
+      "./Pipeline.ts": () => Promise.resolve().then(() => (init_Pipeline(), Pipeline_exports)),
+      "./PipelineAssembler.ts": () => Promise.resolve().then(() => (init_PipelineAssembler(), PipelineAssembler_exports)),
       "./elo.ts": () => Promise.resolve().then(() => (init_elo(), elo_exports)),
+      "./filters/eloDistance.ts": () => Promise.resolve().then(() => (init_eloDistance(), eloDistance_exports)),
+      "./filters/index.ts": () => Promise.resolve().then(() => (init_filters(), filters_exports)),
+      "./filters/types.ts": () => Promise.resolve().then(() => (init_types(), types_exports)),
+      "./generators/index.ts": () => Promise.resolve().then(() => (init_generators(), generators_exports)),
+      "./generators/types.ts": () => Promise.resolve().then(() => (init_types2(), types_exports2)),
       "./hardcodedOrder.ts": () => Promise.resolve().then(() => (init_hardcodedOrder(), hardcodedOrder_exports)),
-      "./index.ts": () => Promise.resolve().then(() => (init_navigators(), navigators_exports))
+      "./hierarchyDefinition.ts": () => Promise.resolve().then(() => (init_hierarchyDefinition(), hierarchyDefinition_exports)),
+      "./index.ts": () => Promise.resolve().then(() => (init_navigators(), navigators_exports)),
+      "./interferenceMitigator.ts": () => Promise.resolve().then(() => (init_interferenceMitigator(), interferenceMitigator_exports)),
+      "./relativePriority.ts": () => Promise.resolve().then(() => (init_relativePriority(), relativePriority_exports)),
+      "./srs.ts": () => Promise.resolve().then(() => (init_srs(), srs_exports))
     });
   }
 });
@@ -1065,9 +2413,34 @@ var init_ = __esm({
 var navigators_exports = {};
 __export(navigators_exports, {
   ContentNavigator: () => ContentNavigator,
-  Navigators: () => Navigators
+  NavigatorRole: () => NavigatorRole,
+  NavigatorRoles: () => NavigatorRoles,
+  Navigators: () => Navigators,
+  getCardOrigin: () => getCardOrigin,
+  isFilter: () => isFilter,
+  isGenerator: () => isGenerator
 });
-var Navigators, ContentNavigator;
+function getCardOrigin(card) {
+  if (card.provenance.length === 0) {
+    throw new Error("Card has no provenance - cannot determine origin");
+  }
+  const firstEntry = card.provenance[0];
+  const reason = firstEntry.reason.toLowerCase();
+  if (reason.includes("failed")) {
+    return "failed";
+  }
+  if (reason.includes("review")) {
+    return "review";
+  }
+  return "new";
+}
+function isGenerator(impl) {
+  return NavigatorRoles[impl] === "generator" /* GENERATOR */;
+}
+function isFilter(impl) {
+  return NavigatorRoles[impl] === "filter" /* FILTER */;
+}
+var Navigators, NavigatorRole, NavigatorRoles, ContentNavigator;
 var init_navigators = __esm({
   "src/core/navigators/index.ts"() {
     "use strict";
@@ -1075,14 +2448,55 @@ var init_navigators = __esm({
     init_();
     Navigators = /* @__PURE__ */ ((Navigators2) => {
       Navigators2["ELO"] = "elo";
+      Navigators2["SRS"] = "srs";
       Navigators2["HARDCODED"] = "hardcodedOrder";
+      Navigators2["HIERARCHY"] = "hierarchyDefinition";
+      Navigators2["INTERFERENCE"] = "interferenceMitigator";
+      Navigators2["RELATIVE_PRIORITY"] = "relativePriority";
       return Navigators2;
     })(Navigators || {});
+    NavigatorRole = /* @__PURE__ */ ((NavigatorRole2) => {
+      NavigatorRole2["GENERATOR"] = "generator";
+      NavigatorRole2["FILTER"] = "filter";
+      return NavigatorRole2;
+    })(NavigatorRole || {});
+    NavigatorRoles = {
+      ["elo" /* ELO */]: "generator" /* GENERATOR */,
+      ["srs" /* SRS */]: "generator" /* GENERATOR */,
+      ["hardcodedOrder" /* HARDCODED */]: "generator" /* GENERATOR */,
+      ["hierarchyDefinition" /* HIERARCHY */]: "filter" /* FILTER */,
+      ["interferenceMitigator" /* INTERFERENCE */]: "filter" /* FILTER */,
+      ["relativePriority" /* RELATIVE_PRIORITY */]: "filter" /* FILTER */
+    };
     ContentNavigator = class {
+      /** User interface for this navigation session */
+      user;
+      /** Course interface for this navigation session */
+      course;
+      /** Human-readable name for this strategy instance (from ContentNavigationStrategyData.name) */
+      strategyName;
+      /** Unique document ID for this strategy instance (from ContentNavigationStrategyData._id) */
+      strategyId;
+      /**
+       * Constructor for standard navigators.
+       * Call this from subclass constructors to initialize common fields.
+       *
+       * Note: CompositeGenerator doesn't use this pattern and should call super() without args.
+       */
+      constructor(user, course, strategyData) {
+        if (user && course && strategyData) {
+          this.user = user;
+          this.course = course;
+          this.strategyName = strategyData.name;
+          this.strategyId = strategyData._id;
+        }
+      }
       /**
+       * Factory method to create navigator instances dynamically.
        *
-       * @param user
-       * @param strategyData
+       * @param user - User interface
+       * @param course - Course interface
+       * @param strategyData - Strategy configuration document
        * @returns the runtime object used to steer a study session.
        */
       static async create(user, course, strategyData) {
@@ -1103,6 +2517,70 @@ var init_navigators = __esm({
         }
         return new NavigatorImpl(user, course, strategyData);
       }
+      /**
+       * Get cards with suitability scores and provenance trails.
+       *
+       * **This is the PRIMARY API for navigation strategies.**
+       *
+       * Returns cards ranked by suitability score (0-1). Higher scores indicate
+       * better candidates for presentation. Each card includes a provenance trail
+       * documenting how strategies contributed to the final score.
+       *
+       * ## For Generators
+       * Override this method to generate candidates and compute scores based on
+       * your strategy's logic (e.g., ELO proximity, review urgency). Create the
+       * initial provenance entry with action='generated'.
+       *
+       * ## Default Implementation
+       * The base class provides a backward-compatible default that:
+       * 1. Calls legacy getNewCards() and getPendingReviews()
+       * 2. Assigns score=1.0 to all cards
+       * 3. Creates minimal provenance from legacy methods
+       * 4. Returns combined results up to limit
+       *
+       * This allows existing strategies to work without modification while
+       * new strategies can override with proper scoring and provenance.
+       *
+       * @param limit - Maximum cards to return
+       * @returns Cards sorted by score descending, with provenance trails
+       */
+      async getWeightedCards(limit) {
+        const newCards = await this.getNewCards(limit);
+        const reviews = await this.getPendingReviews();
+        const weighted = [
+          ...newCards.map((c) => ({
+            cardId: c.cardID,
+            courseId: c.courseID,
+            score: 1,
+            provenance: [
+              {
+                strategy: "legacy",
+                strategyName: this.strategyName || "Legacy API",
+                strategyId: this.strategyId || "legacy-fallback",
+                action: "generated",
+                score: 1,
+                reason: "Generated via legacy getNewCards(), new card"
+              }
+            ]
+          })),
+          ...reviews.map((r) => ({
+            cardId: r.cardID,
+            courseId: r.courseID,
+            score: 1,
+            provenance: [
+              {
+                strategy: "legacy",
+                strategyName: this.strategyName || "Legacy API",
+                strategyId: this.strategyId || "legacy-fallback",
+                action: "generated",
+                score: 1,
+                reason: "Generated via legacy getPendingReviews(), review"
+              }
+            ]
+          }))
+        ];
+        return weighted.slice(0, limit);
+      }
     };
   }
 });
@@ -1112,7 +2590,7 @@ import {
   EloToNumber,
   Status,
   blankCourseElo as blankCourseElo2,
-  toCourseElo as toCourseElo2
+  toCourseElo as toCourseElo6
 } from "@vue-skuilder/common";
 function randIntWeightedTowardZero(n) {
   return Math.floor(Math.random() * Math.random() * Math.random() * n);
@@ -1201,6 +2679,12 @@ var init_courseDB = __esm({
     init_courseAPI();
     init_courseLookupDB();
     init_navigators();
+    init_Pipeline();
+    init_PipelineAssembler();
+    init_CompositeGenerator();
+    init_elo();
+    init_srs();
+    init_eloDistance();
     CoursesDB = class {
       _courseIDs;
       constructor(courseIDs) {
@@ -1312,7 +2796,7 @@ var init_courseDB = __esm({
         docs.rows.forEach((r) => {
           if (isSuccessRow(r)) {
             if (r.doc && r.doc.elo) {
-              ret.push(toCourseElo2(r.doc.elo));
+              ret.push(toCourseElo6(r.doc.elo));
             } else {
               logger.warn("no elo data for card: " + r.id);
               ret.push(blankCourseElo2());
@@ -1585,42 +3069,82 @@ ${above.rows.map((r) => `	${r.id}-${r.key}
         logger.debug(JSON.stringify(data));
         return Promise.resolve();
       }
-      async surfaceNavigationStrategy() {
+      /**
+       * Creates an instantiated navigator for this course.
+       *
+       * Handles multiple generators by wrapping them in CompositeGenerator.
+       * This is the preferred method for getting a ready-to-use navigator.
+       *
+       * @param user - User database interface
+       * @returns Instantiated ContentNavigator ready for use
+       */
+      async createNavigator(user) {
         try {
-          const config = await this.getCourseConfig();
-          if (config.defaultNavigationStrategyId) {
-            try {
-              const strategy = await this.getNavigationStrategy(config.defaultNavigationStrategyId);
-              if (strategy) {
-                logger.debug(`Surfacing strategy ${strategy.name} from course config`);
-                return strategy;
-              }
-            } catch (e) {
-              logger.warn(
-                // @ts-expect-error tmp: defaultNavigationStrategyId property does not yet exist
-                `Failed to load strategy '${config.defaultNavigationStrategyId}' specified in course config. Falling back to ELO.`,
-                e
-              );
-            }
+          const allStrategies = await this.getAllNavigationStrategies();
+          if (allStrategies.length === 0) {
+            logger.debug(
+              "[courseDB] No strategy documents found, using default Pipeline(Composite(ELO, SRS), [eloDistanceFilter])"
+            );
+            return this.createDefaultPipeline(user);
           }
-        } catch (e) {
-          logger.warn(
-            "Could not retrieve course config to determine navigation strategy. Falling back to ELO.",
-            e
+          const assembler = new PipelineAssembler();
+          const { pipeline, generatorStrategies, filterStrategies, warnings } = await assembler.assemble({
+            strategies: allStrategies,
+            user,
+            course: this
+          });
+          for (const warning of warnings) {
+            logger.warn(`[PipelineAssembler] ${warning}`);
+          }
+          if (!pipeline) {
+            logger.debug("[courseDB] Pipeline assembly failed, using default pipeline");
+            return this.createDefaultPipeline(user);
+          }
+          logger.debug(
+            `[courseDB] Using assembled pipeline with ${generatorStrategies.length} generator(s) and ${filterStrategies.length} filter(s)`
           );
+          return pipeline;
+        } catch (e) {
+          logger.error(`[courseDB] Error creating navigator: ${e}`);
+          throw e;
         }
-        logger.warn(`Returning hard-coded default ELO navigator`);
-        const ret = {
-          _id: "NAVIGATION_STRATEGY-ELO",
+      }
+      makeDefaultEloStrategy() {
+        return {
+          _id: "NAVIGATION_STRATEGY-ELO-default",
           docType: "NAVIGATION_STRATEGY" /* NAVIGATION_STRATEGY */,
-          name: "ELO",
-          description: "ELO-based navigation strategy",
+          name: "ELO (default)",
+          description: "Default ELO-based navigation strategy for new cards",
           implementingClass: "elo" /* ELO */,
           course: this.id,
           serializedData: ""
-          // serde is a noop for ELO navigator.
         };
-        return Promise.resolve(ret);
+      }
+      makeDefaultSrsStrategy() {
+        return {
+          _id: "NAVIGATION_STRATEGY-SRS-default",
+          docType: "NAVIGATION_STRATEGY" /* NAVIGATION_STRATEGY */,
+          name: "SRS (default)",
+          description: "Default SRS-based navigation strategy for reviews",
+          implementingClass: "srs" /* SRS */,
+          course: this.id,
+          serializedData: ""
+        };
+      }
+      /**
+       * Creates the default navigation pipeline for courses with no configured strategies.
+       *
+       * Default: Pipeline(Composite(ELO, SRS), [eloDistanceFilter])
+       * - ELO generator: scores new cards by skill proximity
+       * - SRS generator: scores reviews by overdueness and interval recency
+       * - ELO distance filter: penalizes cards far from user's current level
+       */
+      createDefaultPipeline(user) {
+        const eloNavigator = new ELONavigator(user, this, this.makeDefaultEloStrategy());
+        const srsNavigator = new SRSNavigator(user, this, this.makeDefaultSrsStrategy());
+        const compositeGenerator = new CompositeGenerator([eloNavigator, srsNavigator]);
+        const eloDistanceFilter = createEloDistanceFilter();
+        return new Pipeline(compositeGenerator, [eloDistanceFilter], user, this);
       }
       ////////////////////////////////////
       // END NavigationStrategyManager implementation
@@ -1631,22 +3155,39 @@ ${above.rows.map((r) => `	${r.id}-${r.key}
       async getNewCards(limit = 99) {
         const u = await this._getCurrentUser();
         try {
-          const strategy = await this.surfaceNavigationStrategy();
-          const navigator = await ContentNavigator.create(u, this, strategy);
+          const navigator = await this.createNavigator(u);
           return navigator.getNewCards(limit);
         } catch (e) {
-          logger.error(`[courseDB] Error surfacing a NavigationStrategy: ${e}`);
+          logger.error(`[courseDB] Error in getNewCards: ${e}`);
           throw e;
         }
       }
       async getPendingReviews() {
         const u = await this._getCurrentUser();
         try {
-          const strategy = await this.surfaceNavigationStrategy();
-          const navigator = await ContentNavigator.create(u, this, strategy);
+          const navigator = await this.createNavigator(u);
           return navigator.getPendingReviews();
         } catch (e) {
-          logger.error(`[courseDB] Error surfacing a NavigationStrategy: ${e}`);
+          logger.error(`[courseDB] Error in getPendingReviews: ${e}`);
+          throw e;
+        }
+      }
+      /**
+       * Get cards with suitability scores for presentation.
+       *
+       * This is the PRIMARY API for content sources going forward. Delegates to the
+       * course's configured NavigationStrategy to get scored candidates.
+       *
+       * @param limit - Maximum number of cards to return
+       * @returns Cards sorted by score descending
+       */
+      async getWeightedCards(limit) {
+        const u = await this._getCurrentUser();
+        try {
+          const navigator = await this.createNavigator(u);
+          return navigator.getWeightedCards(limit);
+        } catch (e) {
+          logger.error(`[courseDB] Error getting weighted cards: ${e}`);
           throw e;
         }
       }
@@ -1786,7 +3327,7 @@ ${above.rows.map((r) => `	${r.id}-${r.key}
 });
 
 // src/impl/couch/classroomDB.ts
-import moment3 from "moment";
+import moment4 from "moment";
 var classroomLookupDBTitle, CLASSROOM_CONFIG, ClassroomDBBase, StudentClassroomDB, TeacherClassroomDB, ClassroomLookupDB;
 var init_classroomDB2 = __esm({
   "src/impl/couch/classroomDB.ts"() {
@@ -1887,9 +3428,9 @@ var init_classroomDB2 = __esm({
       }
       async getNewCards() {
         const activeCards = await this._user.getActiveCards();
-        const now = moment3.utc();
+        const now = moment4.utc();
         const assigned = await this.getAssignedContent();
-        const due = assigned.filter((c) => now.isAfter(moment3.utc(c.activeOn, REVIEW_TIME_FORMAT2)));
+        const due = assigned.filter((c) => now.isAfter(moment4.utc(c.activeOn, REVIEW_TIME_FORMAT2)));
         logger.info(`Due content: ${JSON.stringify(due)}`);
         let ret = [];
         for (let i = 0; i < due.length; i++) {
@@ -1926,6 +3467,52 @@ var init_classroomDB2 = __esm({
           }
         });
       }
+      /**
+       * Get cards with suitability scores for presentation.
+       *
+       * This implementation wraps the legacy getNewCards/getPendingReviews methods,
+       * assigning score=1.0 to all cards. StudentClassroomDB does not currently
+       * support pluggable navigation strategies.
+       *
+       * @param limit - Maximum number of cards to return
+       * @returns Cards sorted by score descending (all scores = 1.0)
+       */
+      async getWeightedCards(limit) {
+        const [newCards, reviews] = await Promise.all([this.getNewCards(), this.getPendingReviews()]);
+        const weighted = [
+          ...newCards.map((c) => ({
+            cardId: c.cardID,
+            courseId: c.courseID,
+            score: 1,
+            provenance: [
+              {
+                strategy: "classroom",
+                strategyName: "Classroom",
+                strategyId: "CLASSROOM",
+                action: "generated",
+                score: 1,
+                reason: "Classroom legacy getNewCards(), new card"
+              }
+            ]
+          })),
+          ...reviews.map((r) => ({
+            cardId: r.cardID,
+            courseId: r.courseID,
+            score: 1,
+            provenance: [
+              {
+                strategy: "classroom",
+                strategyName: "Classroom",
+                strategyId: "CLASSROOM",
+                action: "generated",
+                score: 1,
+                reason: "Classroom legacy getPendingReviews(), review"
+              }
+            ]
+          }))
+        ];
+        return weighted.slice(0, limit);
+      }
     };
     TeacherClassroomDB = class _TeacherClassroomDB extends ClassroomDBBase {
       _stuDb;
@@ -1982,8 +3569,8 @@ var init_classroomDB2 = __esm({
             type: "tag",
             _id: id,
             assignedBy: content.assignedBy,
-            assignedOn: moment3.utc(),
-            activeOn: content.activeOn || moment3.utc()
+            assignedOn: moment4.utc(),
+            activeOn: content.activeOn || moment4.utc()
           });
         } else {
           put = await this._db.put({
@@ -1991,8 +3578,8 @@ var init_classroomDB2 = __esm({
             type: "course",
             _id: id,
             assignedBy: content.assignedBy,
-            assignedOn: moment3.utc(),
-            activeOn: content.activeOn || moment3.utc()
+            assignedOn: moment4.utc(),
+            activeOn: content.activeOn || moment4.utc()
           });
         }
         if (put.ok) {
@@ -2357,7 +3944,7 @@ var init_CouchDBSyncStrategy = __esm({
 
 // src/impl/couch/index.ts
 import fetch3 from "cross-fetch";
-import moment4 from "moment";
+import moment5 from "moment";
 import process2 from "process";
 function createPouchDBConfig() {
   const hasExplicitCredentials = ENV.COUCHDB_USERNAME && ENV.COUCHDB_PASSWORD;
@@ -2442,7 +4029,7 @@ var init_couch = __esm({
 
 // src/impl/common/BaseUserDB.ts
 import { Status as Status3 } from "@vue-skuilder/common";
-import moment5 from "moment";
+import moment6 from "moment";
 function accomodateGuest() {
   logger.log("[funnel] accomodateGuest() called");
   if (typeof localStorage === "undefined") {
@@ -2880,7 +4467,7 @@ Currently logged-in as ${this._username}.`
         );
         return reviews.rows.filter((r) => {
           if (r.id.startsWith(DocTypePrefixes["SCHEDULED_CARD" /* SCHEDULED_CARD */])) {
-            const date = moment5.utc(
+            const date = moment6.utc(
               r.id.substr(DocTypePrefixes["SCHEDULED_CARD" /* SCHEDULED_CARD */].length),
               REVIEW_TIME_FORMAT
             );
@@ -2893,11 +4480,11 @@ Currently logged-in as ${this._username}.`
         }).map((r) => r.doc);
       }
       async getReviewsForcast(daysCount) {
-        const time = moment5.utc().add(daysCount, "days");
+        const time = moment6.utc().add(daysCount, "days");
         return this.getReviewstoDate(time);
       }
       async getPendingReviews(course_id) {
-        const now = moment5.utc();
+        const now = moment6.utc();
         return this.getReviewstoDate(now, course_id);
       }
       async getScheduledReviewCount(course_id) {
@@ -3184,7 +4771,7 @@ Currently logged-in as ${this._username}.`
        */
       async putCardRecord(record) {
         const cardHistoryID = getCardHistoryID(record.courseID, record.cardID);
-        record.timeStamp = moment5.utc(record.timeStamp).toString();
+        record.timeStamp = moment6.utc(record.timeStamp).toString();
         try {
           const cardHistory = await this.update(
             cardHistoryID,
@@ -3200,7 +4787,7 @@ Currently logged-in as ${this._username}.`
             const ret = {
               ...record2
             };
-            ret.timeStamp = moment5.utc(record2.timeStamp);
+            ret.timeStamp = moment6.utc(record2.timeStamp);
             return ret;
           });
           return cardHistory;
@@ -4204,9 +5791,6 @@ var init_courseDB2 = __esm({
       async updateNavigationStrategy(_id, _data) {
         throw new Error("Cannot update navigation strategies in static mode");
       }
-      async surfaceNavigationStrategy() {
-        return this.getNavigationStrategy("ELO");
-      }
       // Study Content Source implementation
       async getPendingReviews() {
         return [];
@@ -4527,7 +6111,215 @@ var init_factory = __esm({
   }
 });
 
+// src/study/TagFilteredContentSource.ts
+import { hasActiveFilter } from "@vue-skuilder/common";
+var TagFilteredContentSource;
+var init_TagFilteredContentSource = __esm({
+  "src/study/TagFilteredContentSource.ts"() {
+    "use strict";
+    init_courseDB();
+    init_logger();
+    TagFilteredContentSource = class {
+      courseId;
+      filter;
+      user;
+      // Cache resolved card IDs to avoid repeated lookups within a session
+      resolvedCardIds = null;
+      constructor(courseId, filter, user) {
+        this.courseId = courseId;
+        this.filter = filter;
+        this.user = user;
+        logger.info(
+          `[TagFilteredContentSource] Created for course "${courseId}" with filter:`,
+          JSON.stringify(filter)
+        );
+      }
+      /**
+       * Resolves the TagFilter to a set of eligible card IDs.
+       *
+       * - Cards in `include` tags are OR'd together (card needs at least one)
+       * - Cards in `exclude` tags are removed from the result
+       */
+      async resolveFilteredCardIds() {
+        if (this.resolvedCardIds !== null) {
+          return this.resolvedCardIds;
+        }
+        const includedCardIds = /* @__PURE__ */ new Set();
+        if (this.filter.include.length > 0) {
+          for (const tagName of this.filter.include) {
+            try {
+              const tagDoc = await getTag(this.courseId, tagName);
+              tagDoc.taggedCards.forEach((cardId) => includedCardIds.add(cardId));
+            } catch (error) {
+              logger.warn(
+                `[TagFilteredContentSource] Could not resolve tag "${tagName}" for inclusion:`,
+                error
+              );
+            }
+          }
+        }
+        if (includedCardIds.size === 0 && this.filter.include.length > 0) {
+          logger.warn(
+            `[TagFilteredContentSource] No cards found for include tags: ${this.filter.include.join(", ")}`
+          );
+          this.resolvedCardIds = /* @__PURE__ */ new Set();
+          return this.resolvedCardIds;
+        }
+        const excludedCardIds = /* @__PURE__ */ new Set();
+        if (this.filter.exclude.length > 0) {
+          for (const tagName of this.filter.exclude) {
+            try {
+              const tagDoc = await getTag(this.courseId, tagName);
+              tagDoc.taggedCards.forEach((cardId) => excludedCardIds.add(cardId));
+            } catch (error) {
+              logger.warn(
+                `[TagFilteredContentSource] Could not resolve tag "${tagName}" for exclusion:`,
+                error
+              );
+            }
+          }
+        }
+        const finalCardIds = /* @__PURE__ */ new Set();
+        for (const cardId of includedCardIds) {
+          if (!excludedCardIds.has(cardId)) {
+            finalCardIds.add(cardId);
+          }
+        }
+        logger.info(
+          `[TagFilteredContentSource] Resolved ${finalCardIds.size} cards (included: ${includedCardIds.size}, excluded: ${excludedCardIds.size})`
+        );
+        this.resolvedCardIds = finalCardIds;
+        return finalCardIds;
+      }
+      /**
+       * Gets new cards that match the tag filter and are not already active for the user.
+       */
+      async getNewCards(limit) {
+        if (!hasActiveFilter(this.filter)) {
+          logger.warn("[TagFilteredContentSource] getNewCards called with no active filter");
+          return [];
+        }
+        const eligibleCardIds = await this.resolveFilteredCardIds();
+        const activeCards = await this.user.getActiveCards();
+        const activeCardIds = new Set(activeCards.map((c) => c.cardID));
+        const newItems = [];
+        for (const cardId of eligibleCardIds) {
+          if (!activeCardIds.has(cardId)) {
+            newItems.push({
+              courseID: this.courseId,
+              cardID: cardId,
+              contentSourceType: "course",
+              contentSourceID: this.courseId,
+              status: "new"
+            });
+          }
+          if (limit !== void 0 && newItems.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.
+       */
+      async getPendingReviews() {
+        if (!hasActiveFilter(this.filter)) {
+          logger.warn("[TagFilteredContentSource] getPendingReviews called with no active filter");
+          return [];
+        }
+        const eligibleCardIds = await this.resolveFilteredCardIds();
+        const allReviews = await this.user.getPendingReviews(this.courseId);
+        const filteredReviews = allReviews.filter((review) => {
+          return 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",
+          contentSourceID: this.courseId,
+          reviewID: r._id,
+          status: "review"
+        }));
+      }
+      /**
+       * 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)
+       */
+      async getWeightedCards(limit) {
+        const [newCards, reviews] = await Promise.all([
+          this.getNewCards(limit),
+          this.getPendingReviews()
+        ]);
+        const weighted = [
+          ...reviews.map((r) => ({
+            cardId: r.cardID,
+            courseId: r.courseID,
+            score: 1,
+            provenance: [
+              {
+                strategy: "tagFilter",
+                strategyName: "Tag Filter",
+                strategyId: "TAG_FILTER",
+                action: "generated",
+                score: 1,
+                reason: `Tag-filtered review (tags: ${this.filter.include.join(", ")})`
+              }
+            ]
+          })),
+          ...newCards.map((c) => ({
+            cardId: c.cardID,
+            courseId: c.courseID,
+            score: 1,
+            provenance: [
+              {
+                strategy: "tagFilter",
+                strategyName: "Tag Filter",
+                strategyId: "TAG_FILTER",
+                action: "generated",
+                score: 1,
+                reason: `Tag-filtered new card (tags: ${this.filter.include.join(", ")})`
+              }
+            ]
+          }))
+        ];
+        return weighted.slice(0, limit);
+      }
+      /**
+       * Clears the cached resolved card IDs.
+       * Call this if the underlying tag data may have changed during a session.
+       */
+      clearCache() {
+        this.resolvedCardIds = null;
+      }
+      /**
+       * Returns the course ID this source is filtering.
+       */
+      getCourseId() {
+        return this.courseId;
+      }
+      /**
+       * Returns the active tag filter.
+       */
+      getFilter() {
+        return this.filter;
+      }
+    };
+  }
+});
+
 // src/core/interfaces/contentSource.ts
+import { hasActiveFilter as hasActiveFilter2 } from "@vue-skuilder/common";
 function isReview(item) {
   const ret = item.status === "review" || item.status === "failed-review" || "reviewID" in item;
   return ret;
@@ -4536,6 +6328,9 @@ async function getStudySource(source, user) {
   if (source.type === "classroom") {
     return await StudentClassroomDB.factory(source.id, user);
   } else {
+    if (hasActiveFilter2(source.tagFilter)) {
+      return new TagFilteredContentSource(source.id, source.tagFilter, user);
+    }
     return getDataLayer().getCourseDB(source.id);
   }
 }
@@ -4544,6 +6339,7 @@ var init_contentSource = __esm({
     "use strict";
     init_factory();
     init_classroomDB2();
+    init_TagFilteredContentSource();
   }
 });
 
@@ -4709,7 +6505,7 @@ var init_cardProcessor = __esm({
 });
 
 // src/core/bulkImport/types.ts
-var init_types = __esm({
+var init_types3 = __esm({
   "src/core/bulkImport/types.ts"() {
     "use strict";
   }
@@ -4720,7 +6516,7 @@ var init_bulkImport = __esm({
   "src/core/bulkImport/index.ts"() {
     "use strict";
     init_cardProcessor();
-    init_types();
+    init_types3();
   }
 });
 
@@ -4744,13 +6540,13 @@ init_courseLookupDB();
 
 // src/study/services/SrsService.ts
 init_couch();
-import moment7 from "moment";
+import moment8 from "moment";
 
 // src/study/SpacedRepetition.ts
 init_util();
 init_logger();
-import moment6 from "moment";
-var duration = moment6.duration;
+import moment7 from "moment";
+var duration = moment7.duration;
 function newInterval(user, cardHistory) {
   if (areQuestionRecords(cardHistory)) {
     return newQuestionInterval(user, cardHistory);
@@ -4814,8 +6610,8 @@ function getInitialInterval(cardHistory) {
   return 60 * 60 * 24 * 3;
 }
 function secondsBetween(start, end) {
-  start = moment6(start);
-  end = moment6(end);
+  start = moment7(start);
+  end = moment7(end);
   const ret = duration(end.diff(start)).asSeconds();
   return ret;
 }
@@ -4835,7 +6631,7 @@ var SrsService = class {
    */
   async scheduleReview(history, item) {
     const nextInterval = newInterval(this.user, history);
-    const nextReviewTime = moment7.utc().add(nextInterval, "seconds");
+    const nextReviewTime = moment8.utc().add(nextInterval, "seconds");
     if (isReview(item)) {
       logger.info(`[SrsService] Removing previously scheduled review for: ${item.cardID}`);
       void this.user.removeScheduledCardReview(item.reviewID);
@@ -4853,7 +6649,7 @@ var SrsService = class {
 
 // src/study/services/EloService.ts
 init_logger();
-import { adjustCourseScores, toCourseElo as toCourseElo3 } from "@vue-skuilder/common";
+import { adjustCourseScores, toCourseElo as toCourseElo7 } from "@vue-skuilder/common";
 var EloService = class {
   dataLayer;
   user;
@@ -4875,7 +6671,7 @@ var EloService = class {
       logger.warn(`k value interpretation not currently implemented`);
     }
     const courseDB = this.dataLayer.getCourseDB(currentCard.card.course_id);
-    const userElo = toCourseElo3(userCourseRegDoc.courses.find((c) => c.courseID === course_id).elo);
+    const userElo = toCourseElo7(userCourseRegDoc.courses.find((c) => c.courseID === course_id).elo);
     const cardElo = (await courseDB.getCardEloData([currentCard.card.card_id]))[0];
     if (cardElo && userElo) {
       const eloUpdate = adjustCourseScores(userElo, cardElo, userScore);
@@ -5084,7 +6880,7 @@ init_logger();
 import {
   displayableDataToViewData,
   isCourseElo,
-  toCourseElo as toCourseElo4
+  toCourseElo as toCourseElo8
 } from "@vue-skuilder/common";
 
 // src/study/ItemQueue.ts
@@ -5209,7 +7005,7 @@ var CardHydrationService = class {
             const courseDB = this.getCourseDB(nextItem.courseID);
             const cardData = await courseDB.getCourseDoc(nextItem.cardID);
             if (!isCourseElo(cardData.elo)) {
-              cardData.elo = toCourseElo4(cardData.elo);
+              cardData.elo = toCourseElo8(cardData.elo);
             }
             const view = this.getViewComponent(cardData.id_view);
             const dataDocs = await Promise.all(
@@ -6675,6 +8471,7 @@ init_dataDirectory();
 init_tuiLogger();
 
 // src/study/SessionController.ts
+init_navigators();
 function randomInt(min, max) {
   return Math.floor(Math.random() * (max - min + 1)) + min;
 }
@@ -6777,7 +8574,12 @@ var SessionController = class extends Loggable {
   }
   async prepareSession() {
     try {
-      await Promise.all([this.getScheduledReviews(), this.getNewCards()]);
+      const hasWeightedCards = this.sources.some((s) => typeof s.getWeightedCards === "function");
+      if (hasWeightedCards) {
+        await this.getWeightedContent();
+      } else {
+        await Promise.all([this.getScheduledReviews(), this.getNewCards()]);
+      }
     } catch (e) {
       this.error("Error preparing study session:", e);
     }
@@ -6803,6 +8605,9 @@ var SessionController = class extends Loggable {
    * Used by SessionControllerDebug component for runtime inspection.
    */
   getDebugInfo() {
+    const supportsWeightedCards = this.sources.some(
+      (s) => typeof s.getWeightedCards === "function"
+    );
     const extractQueueItems = (queue, limit = 10) => {
       const items = [];
       for (let i = 0; i < Math.min(queue.length, limit); i++) {
@@ -6820,6 +8625,10 @@ var SessionController = class extends Loggable {
       return items;
     };
     return {
+      api: {
+        mode: supportsWeightedCards ? "weighted" : "legacy",
+        description: supportsWeightedCards ? "Using getWeightedCards() API with scored candidates" : "Using legacy getNewCards()/getPendingReviews() API"
+      },
       reviewQueue: {
         length: this.reviewQ.length,
         dequeueCount: this.reviewQ.dequeueCount,
@@ -6842,6 +8651,109 @@ var SessionController = class extends Loggable {
       }
     };
   }
+  /**
+   * Fetch content using the new getWeightedCards API.
+   *
+   * This method uses getWeightedCards() to get scored candidates, then uses the
+   * scores to determine ordering. For reviews, we still need the full ScheduledCard
+   * data from getPendingReviews(), so we fetch both and use scores for ordering.
+   *
+   * The hybrid approach:
+   * 1. Fetch weighted cards to get scoring/ordering information
+   * 2. Fetch full review data via legacy getPendingReviews()
+   * 3. Order reviews by their weighted scores
+   * 4. Add new cards ordered by their weighted scores
+   */
+  async getWeightedContent() {
+    const limit = 20;
+    const allWeighted = [];
+    const allReviews = [];
+    const allNewCards = [];
+    for (const source of this.sources) {
+      try {
+        const reviews = await source.getPendingReviews().catch((error) => {
+          this.error(`Failed to get reviews for source:`, error);
+          return [];
+        });
+        allReviews.push(...reviews);
+        if (typeof source.getWeightedCards === "function") {
+          const weighted = await source.getWeightedCards(limit);
+          allWeighted.push(...weighted);
+        } else {
+          const newCards = await source.getNewCards(limit);
+          allNewCards.push(...newCards);
+          allWeighted.push(
+            ...newCards.map((c) => ({
+              cardId: c.cardID,
+              courseId: c.courseID,
+              score: 1,
+              provenance: [
+                {
+                  strategy: "legacy",
+                  strategyName: "Legacy Fallback",
+                  strategyId: "legacy-fallback",
+                  action: "generated",
+                  score: 1,
+                  reason: "Fallback to legacy getNewCards(), new card"
+                }
+              ]
+            })),
+            ...reviews.map((r) => ({
+              cardId: r.cardID,
+              courseId: r.courseID,
+              score: 1,
+              provenance: [
+                {
+                  strategy: "legacy",
+                  strategyName: "Legacy Fallback",
+                  strategyId: "legacy-fallback",
+                  action: "generated",
+                  score: 1,
+                  reason: "Fallback to legacy getPendingReviews(), review"
+                }
+              ]
+            }))
+          );
+        }
+      } catch (error) {
+        this.error(`Failed to get content from source:`, error);
+      }
+    }
+    const scoreMap = /* @__PURE__ */ new Map();
+    for (const w of allWeighted) {
+      const key = `${w.courseId}::${w.cardId}`;
+      scoreMap.set(key, w.score);
+    }
+    const scoredReviews = allReviews.map((r) => ({
+      review: r,
+      score: scoreMap.get(`${r.courseID}::${r.cardID}`) ?? 1
+    }));
+    scoredReviews.sort((a, b) => b.score - a.score);
+    let report = "Weighted content session created with:\n";
+    for (const { review, score } of scoredReviews) {
+      this.reviewQ.add(review, review.cardID);
+      report += `Review: ${review.courseID}::${review.cardID} (score: ${score.toFixed(2)})
+`;
+    }
+    const newCardWeighted = allWeighted.filter((w) => getCardOrigin(w) === "new").sort((a, b) => b.score - a.score);
+    for (const card of newCardWeighted) {
+      const newItem = {
+        cardID: card.cardId,
+        courseID: card.courseId,
+        contentSourceType: "course",
+        contentSourceID: card.courseId,
+        status: "new"
+      };
+      this.newQ.add(newItem, card.cardId);
+      report += `New: ${card.courseId}::${card.cardId} (score: ${card.score.toFixed(2)})
+`;
+    }
+    this.log(report);
+  }
+  /**
+   * @deprecated Use getWeightedContent() instead. This method is kept for backward
+   * compatibility with sources that don't support getWeightedCards().
+   */
   async getScheduledReviews() {
     const reviews = await Promise.all(
       this.sources.map(
@@ -6867,6 +8779,10 @@ var SessionController = class extends Loggable {
     report += dueCards.map((card) => `Card ${card.courseID}::${card.cardID} `).join("\n");
     this.log(report);
   }
+  /**
+   * @deprecated Use getWeightedContent() instead. This method is kept for backward
+   * compatibility with sources that don't support getWeightedCards().
+   */
   async getNewCards(n = 10) {
     const perCourse = Math.ceil(n / this.sources.length);
     const newContent = await Promise.all(this.sources.map((c) => c.getNewCards(perCourse)));
@@ -7031,6 +8947,9 @@ var SessionController = class extends Loggable {
   }
 };
 
+// src/study/index.ts
+init_TagFilteredContentSource();
+
 // src/index.ts
 init_factory();
 export {
@@ -7044,15 +8963,19 @@ export {
   GuestUsername,
   Loggable,
   NOT_SET,
+  NavigatorRole,
+  NavigatorRoles,
   Navigators,
   SessionController,
   StaticToCouchDBMigrator,
+  TagFilteredContentSource,
   _resetDataLayer,
   areQuestionRecords,
   docIsDeleted,
   ensureAppDataDirectory,
   getAppDataDirectory,
   getCardHistoryID,
+  getCardOrigin,
   getDataLayer,
   getDbPath,
   getLogFilePath,
@@ -7061,6 +8984,8 @@ export {
   initializeDataDirectory,
   initializeDataLayer,
   initializeTuiLogging,
+  isFilter,
+  isGenerator,
   isQuestionRecord,
   isReview,
   log,