@vue-skuilder/db 0.1.31 → 0.1.32-b

package/dist/index.d.cts

@@ -307,6 +307,34 @@ declare class QuotaRoundRobinMixer implements SourceMixer {
     mix(batches: SourceBatch[], limit: number): WeightedCard[];
 }
 
+/**
+ * Options for requesting a mid-session replan.
+ *
+ * All fields are optional — callers can pass just the fields they need.
+ * When omitted, defaults match the existing behaviour (full 20-card
+ * replace with no hints).
+ */
+interface ReplanOptions {
+    /** Scoring hints forwarded to the pipeline (boost/exclude/require). */
+    hints?: Record<string, unknown>;
+    /**
+     * Maximum number of new cards to return from the pipeline.
+     * Default: 20 (the standard session batch size).
+     */
+    limit?: number;
+    /**
+     * How to integrate the new cards into the existing newQ.
+     * - `'replace'` (default): atomically swap the entire newQ.
+     * - `'merge'`: insert new cards at the front, keeping existing cards.
+     */
+    mode?: 'replace' | 'merge';
+    /**
+     * Human-readable label for debugging / provenance.
+     * Appears in console logs and in card provenance entries created
+     * by ephemeral hint application.
+     */
+    label?: string;
+}
 interface StudySessionRecord {
     card: {
         course_id: string;
@@ -321,6 +349,13 @@ type SessionAction = 'dismiss-success' | 'dismiss-failed' | 'marked-failed' | 'd
 interface ResponseResult {
     nextCardAction: Exclude<SessionAction, 'dismiss-error'> | 'none';
     shouldLoadNextCard: boolean;
+    /**
+     * When true, the card requested deferred advancement via `deferAdvance`.
+     * The record was logged and ELO updated, but navigation was suppressed.
+     * StudySession should stash `nextCardAction` and wait for a
+     * `ready-to-advance` event from the card before calling `nextCard()`.
+     */
+    deferred?: boolean;
     isCorrect: boolean;
     performanceScore?: number;
     shouldClearFeedbackShadow: boolean;
@@ -337,6 +372,12 @@ declare class SessionController<TView = unknown> extends Loggable {
     private mixer;
     private dataLayer;
     private courseNameCache;
+    /**
+     * Default pipeline batch size for new-card planning.
+     * Set via constructor options; falls back to 20 when not specified.
+     * Individual replans can override via `ReplanOptions.limit`.
+     */
+    private _defaultBatchLimit;
     private sources;
     private _sessionRecord;
     set sessionRecord(r: StudySessionRecord[]);
@@ -356,6 +397,20 @@ declare class SessionController<TView = unknown> extends Loggable {
      * (user state has changed from completing good cards).
      */
     private _wellIndicatedRemaining;
+    /**
+     * When true, suppresses the quality-based auto-replan trigger in
+     * nextCard(). Set after a burst replan (small limit) to prevent the
+     * auto-replan from clobbering the burst cards before they're consumed.
+     * Cleared when the depletion-triggered replan fires (newQ exhausted).
+     */
+    private _suppressQualityReplan;
+    /**
+     * Guards against infinite depletion-triggered replans. Set to true
+     * when a depletion replan fires; cleared when a replan produces
+     * content (newQ.length > 0 after replan) or when an explicit
+     * (non-auto) replan is requested.
+     */
+    private _depletionReplanAttempted;
     private startTime;
     private endTime;
     private _secondsRemaining;
@@ -369,8 +424,14 @@ declare class SessionController<TView = unknown> extends Loggable {
      * @param dataLayer - Data layer provider
      * @param getViewComponent - Function to resolve view components
      * @param mixer - Optional source mixer strategy (defaults to QuotaRoundRobinMixer)
-     */
-    constructor(sources: StudyContentSource[], time: number, dataLayer: DataLayerProvider, getViewComponent: (viewId: string) => TView, mixer?: SourceMixer);
+     * @param options - Optional session-level configuration
+     * @param options.defaultBatchLimit - Default pipeline batch size (default: 20).
+     *   Smaller values for newer users cause more frequent replans, keeping plans
+     *   aligned with rapidly-changing user state.
+     */
+    constructor(sources: StudyContentSource[], time: number, dataLayer: DataLayerProvider, getViewComponent: (viewId: string) => TView, mixer?: SourceMixer, options?: {
+        defaultBatchLimit?: number;
+    });
     private tick;
     /**
      * Returns a rough, erring toward conservative, guess at
@@ -401,7 +462,14 @@ declare class SessionController<TView = unknown> extends Loggable {
      * Typical trigger: application-level code (e.g. after a GPC intro completion)
      * calls this to ensure newly-unlocked content appears in the session.
      */
-    requestReplan(hints?: Record<string, unknown>): Promise<void>;
+    requestReplan(options?: ReplanOptions | Record<string, unknown>): Promise<void>;
+    /**
+     * Normalise the requestReplan argument. Accepts either a ReplanOptions
+     * object (new API) or a plain Record<string, unknown> (legacy callers
+     * that passed hints directly). Distinguishes the two by checking for
+     * the presence of ReplanOptions-specific keys.
+     */
+    private normalizeReplanOptions;
     /** Minimum well-indicated cards before an additive retry is attempted */
     private static readonly MIN_WELL_INDICATED;
     /**
@@ -467,6 +535,8 @@ declare class SessionController<TView = unknown> extends Loggable {
         };
         replan: {
             inProgress: boolean;
+            suppressQualityReplan: boolean;
+            defaultBatchLimit: number;
         };
     };
     /**
@@ -1017,4 +1087,4 @@ interface CouchDbUserDoc extends PouchDB.Authentication.User {
     entitlements: UserEntitlements;
 }
 
-export { type AggregatedDocument, type AttachmentUploadResult, CardHistory, type CardPresentation, CardRecord, type CouchDbUserDoc, CourseDBInterface, CourseLookup, CourseRegistrationDoc, type CustomQuestionsData, DEFAULT_MIGRATION_OPTIONS, type DataLayerConfig, DataLayerProvider, type DocumentCounts, ENV, type Entitlement, FileSystemAdapter, Loggable, type MigrationOptions, type MigrationResult, type MixerCardInfo, type MixerRunReport, NOT_SET, type ProcessedDataShape, type ProcessedQuestionData, type QueueSnapshot, QuotaRoundRobinMixer, type ResponseResult, type RestoreProgress, type SessionAction, SessionController, type SessionRunReport, type SourceBatch, type SourceMixer, type SourceSelectionBreakdown, type SourceSummary, StaticCourseManifest, type StaticCourseValidation, StaticToCouchDBMigrator, StudyContentSource, StudySessionItem, type StudySessionRecord, TagFilteredContentSource, type UserAccountStatus, UserDBInterface, type UserEntitlements, type ValidationIssue, type ValidationResult, WeightedCard, _resetDataLayer, captureMixerRun, endSessionTracking, ensureAppDataDirectory, getAppDataDirectory, getDataLayer, getDbPath, initializeDataDirectory, initializeDataLayer, isDataShapeRegistered, isDataShapeSchemaAvailable, isQuestionTypeRegistered, mixerDebugAPI, mountMixerDebugger, mountSessionDebugger, processCustomQuestionsData, recordCardPresentation, registerBlanksCard, registerCustomQuestionTypes, registerDataShape, registerQuestionType, registerSeedData, removeCustomQuestionTypes, removeDataShape, removeQuestionType, sessionDebugAPI, snapshotQueues, startSessionTracking, validateMigration, validateStaticCourse };
+export { type AggregatedDocument, type AttachmentUploadResult, CardHistory, type CardPresentation, CardRecord, type CouchDbUserDoc, CourseDBInterface, CourseLookup, CourseRegistrationDoc, type CustomQuestionsData, DEFAULT_MIGRATION_OPTIONS, type DataLayerConfig, DataLayerProvider, type DocumentCounts, ENV, type Entitlement, FileSystemAdapter, Loggable, type MigrationOptions, type MigrationResult, type MixerCardInfo, type MixerRunReport, NOT_SET, type ProcessedDataShape, type ProcessedQuestionData, type QueueSnapshot, QuotaRoundRobinMixer, type ReplanOptions, type ResponseResult, type RestoreProgress, type SessionAction, SessionController, type SessionRunReport, type SourceBatch, type SourceMixer, type SourceSelectionBreakdown, type SourceSummary, StaticCourseManifest, type StaticCourseValidation, StaticToCouchDBMigrator, StudyContentSource, StudySessionItem, type StudySessionRecord, TagFilteredContentSource, type UserAccountStatus, UserDBInterface, type UserEntitlements, type ValidationIssue, type ValidationResult, WeightedCard, _resetDataLayer, captureMixerRun, endSessionTracking, ensureAppDataDirectory, getAppDataDirectory, getDataLayer, getDbPath, initializeDataDirectory, initializeDataLayer, isDataShapeRegistered, isDataShapeSchemaAvailable, isQuestionTypeRegistered, mixerDebugAPI, mountMixerDebugger, mountSessionDebugger, processCustomQuestionsData, recordCardPresentation, registerBlanksCard, registerCustomQuestionTypes, registerDataShape, registerQuestionType, registerSeedData, removeCustomQuestionTypes, removeDataShape, removeQuestionType, sessionDebugAPI, snapshotQueues, startSessionTracking, validateMigration, validateStaticCourse };

package/dist/index.d.ts

@@ -307,6 +307,34 @@ declare class QuotaRoundRobinMixer implements SourceMixer {
     mix(batches: SourceBatch[], limit: number): WeightedCard[];
 }
 
+/**
+ * Options for requesting a mid-session replan.
+ *
+ * All fields are optional — callers can pass just the fields they need.
+ * When omitted, defaults match the existing behaviour (full 20-card
+ * replace with no hints).
+ */
+interface ReplanOptions {
+    /** Scoring hints forwarded to the pipeline (boost/exclude/require). */
+    hints?: Record<string, unknown>;
+    /**
+     * Maximum number of new cards to return from the pipeline.
+     * Default: 20 (the standard session batch size).
+     */
+    limit?: number;
+    /**
+     * How to integrate the new cards into the existing newQ.
+     * - `'replace'` (default): atomically swap the entire newQ.
+     * - `'merge'`: insert new cards at the front, keeping existing cards.
+     */
+    mode?: 'replace' | 'merge';
+    /**
+     * Human-readable label for debugging / provenance.
+     * Appears in console logs and in card provenance entries created
+     * by ephemeral hint application.
+     */
+    label?: string;
+}
 interface StudySessionRecord {
     card: {
         course_id: string;
@@ -321,6 +349,13 @@ type SessionAction = 'dismiss-success' | 'dismiss-failed' | 'marked-failed' | 'd
 interface ResponseResult {
     nextCardAction: Exclude<SessionAction, 'dismiss-error'> | 'none';
     shouldLoadNextCard: boolean;
+    /**
+     * When true, the card requested deferred advancement via `deferAdvance`.
+     * The record was logged and ELO updated, but navigation was suppressed.
+     * StudySession should stash `nextCardAction` and wait for a
+     * `ready-to-advance` event from the card before calling `nextCard()`.
+     */
+    deferred?: boolean;
     isCorrect: boolean;
     performanceScore?: number;
     shouldClearFeedbackShadow: boolean;
@@ -337,6 +372,12 @@ declare class SessionController<TView = unknown> extends Loggable {
     private mixer;
     private dataLayer;
     private courseNameCache;
+    /**
+     * Default pipeline batch size for new-card planning.
+     * Set via constructor options; falls back to 20 when not specified.
+     * Individual replans can override via `ReplanOptions.limit`.
+     */
+    private _defaultBatchLimit;
     private sources;
     private _sessionRecord;
     set sessionRecord(r: StudySessionRecord[]);
@@ -356,6 +397,20 @@ declare class SessionController<TView = unknown> extends Loggable {
      * (user state has changed from completing good cards).
      */
     private _wellIndicatedRemaining;
+    /**
+     * When true, suppresses the quality-based auto-replan trigger in
+     * nextCard(). Set after a burst replan (small limit) to prevent the
+     * auto-replan from clobbering the burst cards before they're consumed.
+     * Cleared when the depletion-triggered replan fires (newQ exhausted).
+     */
+    private _suppressQualityReplan;
+    /**
+     * Guards against infinite depletion-triggered replans. Set to true
+     * when a depletion replan fires; cleared when a replan produces
+     * content (newQ.length > 0 after replan) or when an explicit
+     * (non-auto) replan is requested.
+     */
+    private _depletionReplanAttempted;
     private startTime;
     private endTime;
     private _secondsRemaining;
@@ -369,8 +424,14 @@ declare class SessionController<TView = unknown> extends Loggable {
      * @param dataLayer - Data layer provider
      * @param getViewComponent - Function to resolve view components
      * @param mixer - Optional source mixer strategy (defaults to QuotaRoundRobinMixer)
-     */
-    constructor(sources: StudyContentSource[], time: number, dataLayer: DataLayerProvider, getViewComponent: (viewId: string) => TView, mixer?: SourceMixer);
+     * @param options - Optional session-level configuration
+     * @param options.defaultBatchLimit - Default pipeline batch size (default: 20).
+     *   Smaller values for newer users cause more frequent replans, keeping plans
+     *   aligned with rapidly-changing user state.
+     */
+    constructor(sources: StudyContentSource[], time: number, dataLayer: DataLayerProvider, getViewComponent: (viewId: string) => TView, mixer?: SourceMixer, options?: {
+        defaultBatchLimit?: number;
+    });
     private tick;
     /**
      * Returns a rough, erring toward conservative, guess at
@@ -401,7 +462,14 @@ declare class SessionController<TView = unknown> extends Loggable {
      * Typical trigger: application-level code (e.g. after a GPC intro completion)
      * calls this to ensure newly-unlocked content appears in the session.
      */
-    requestReplan(hints?: Record<string, unknown>): Promise<void>;
+    requestReplan(options?: ReplanOptions | Record<string, unknown>): Promise<void>;
+    /**
+     * Normalise the requestReplan argument. Accepts either a ReplanOptions
+     * object (new API) or a plain Record<string, unknown> (legacy callers
+     * that passed hints directly). Distinguishes the two by checking for
+     * the presence of ReplanOptions-specific keys.
+     */
+    private normalizeReplanOptions;
     /** Minimum well-indicated cards before an additive retry is attempted */
     private static readonly MIN_WELL_INDICATED;
     /**
@@ -467,6 +535,8 @@ declare class SessionController<TView = unknown> extends Loggable {
         };
         replan: {
             inProgress: boolean;
+            suppressQualityReplan: boolean;
+            defaultBatchLimit: number;
         };
     };
     /**
@@ -1017,4 +1087,4 @@ interface CouchDbUserDoc extends PouchDB.Authentication.User {
     entitlements: UserEntitlements;
 }
 
-export { type AggregatedDocument, type AttachmentUploadResult, CardHistory, type CardPresentation, CardRecord, type CouchDbUserDoc, CourseDBInterface, CourseLookup, CourseRegistrationDoc, type CustomQuestionsData, DEFAULT_MIGRATION_OPTIONS, type DataLayerConfig, DataLayerProvider, type DocumentCounts, ENV, type Entitlement, FileSystemAdapter, Loggable, type MigrationOptions, type MigrationResult, type MixerCardInfo, type MixerRunReport, NOT_SET, type ProcessedDataShape, type ProcessedQuestionData, type QueueSnapshot, QuotaRoundRobinMixer, type ResponseResult, type RestoreProgress, type SessionAction, SessionController, type SessionRunReport, type SourceBatch, type SourceMixer, type SourceSelectionBreakdown, type SourceSummary, StaticCourseManifest, type StaticCourseValidation, StaticToCouchDBMigrator, StudyContentSource, StudySessionItem, type StudySessionRecord, TagFilteredContentSource, type UserAccountStatus, UserDBInterface, type UserEntitlements, type ValidationIssue, type ValidationResult, WeightedCard, _resetDataLayer, captureMixerRun, endSessionTracking, ensureAppDataDirectory, getAppDataDirectory, getDataLayer, getDbPath, initializeDataDirectory, initializeDataLayer, isDataShapeRegistered, isDataShapeSchemaAvailable, isQuestionTypeRegistered, mixerDebugAPI, mountMixerDebugger, mountSessionDebugger, processCustomQuestionsData, recordCardPresentation, registerBlanksCard, registerCustomQuestionTypes, registerDataShape, registerQuestionType, registerSeedData, removeCustomQuestionTypes, removeDataShape, removeQuestionType, sessionDebugAPI, snapshotQueues, startSessionTracking, validateMigration, validateStaticCourse };
+export { type AggregatedDocument, type AttachmentUploadResult, CardHistory, type CardPresentation, CardRecord, type CouchDbUserDoc, CourseDBInterface, CourseLookup, CourseRegistrationDoc, type CustomQuestionsData, DEFAULT_MIGRATION_OPTIONS, type DataLayerConfig, DataLayerProvider, type DocumentCounts, ENV, type Entitlement, FileSystemAdapter, Loggable, type MigrationOptions, type MigrationResult, type MixerCardInfo, type MixerRunReport, NOT_SET, type ProcessedDataShape, type ProcessedQuestionData, type QueueSnapshot, QuotaRoundRobinMixer, type ReplanOptions, type ResponseResult, type RestoreProgress, type SessionAction, SessionController, type SessionRunReport, type SourceBatch, type SourceMixer, type SourceSelectionBreakdown, type SourceSummary, StaticCourseManifest, type StaticCourseValidation, StaticToCouchDBMigrator, StudyContentSource, StudySessionItem, type StudySessionRecord, TagFilteredContentSource, type UserAccountStatus, UserDBInterface, type UserEntitlements, type ValidationIssue, type ValidationResult, WeightedCard, _resetDataLayer, captureMixerRun, endSessionTracking, ensureAppDataDirectory, getAppDataDirectory, getDataLayer, getDbPath, initializeDataDirectory, initializeDataLayer, isDataShapeRegistered, isDataShapeSchemaAvailable, isQuestionTypeRegistered, mixerDebugAPI, mountMixerDebugger, mountSessionDebugger, processCustomQuestionsData, recordCardPresentation, registerBlanksCard, registerCustomQuestionTypes, registerDataShape, registerQuestionType, registerSeedData, removeCustomQuestionTypes, removeDataShape, removeQuestionType, sessionDebugAPI, snapshotQueues, startSessionTracking, validateMigration, validateStaticCourse };

package/dist/index.js

@@ -1936,6 +1936,7 @@ var init_hierarchyDefinition = __esm({
     "use strict";
     init_navigators();
     import_common6 = require("@vue-skuilder/common");
+    init_logger();
     DEFAULT_MIN_COUNT = 3;
     HierarchyDefinitionNavigator = class extends ContentNavigator {
       config;
@@ -2103,6 +2104,9 @@ var init_hierarchyDefinition = __esm({
               finalScore *= maxBoost;
               action = "boosted";
               finalReason = `${reason} | preReqBoost \xD7${maxBoost.toFixed(2)} for ${boostedPrereqs.join(", ")}`;
+              logger.info(
+                `[HierarchyDefinition] preReqBoost \xD7${maxBoost.toFixed(2)} applied to card ${card.cardId} via tags [${boostedPrereqs.join(", ")}] (score: ${card.score.toFixed(3)} \u2192 ${finalScore.toFixed(3)})`
+              );
             }
           }
           gated.push({
@@ -2612,7 +2616,7 @@ var init_relativePriority = __esm({
             const cardTags = card.tags ?? [];
             const priority = this.computeCardPriority(cardTags);
             const boostFactor = this.computeBoostFactor(priority);
-            const finalScore = Math.max(0, Math.min(1, card.score * boostFactor));
+            const finalScore = Math.max(0, card.score * boostFactor);
             const action = boostFactor > 1 ? "boosted" : boostFactor < 1 ? "penalized" : "passed";
             const reason = this.buildPriorityReason(cardTags, priority, boostFactor, finalScore);
             return {
@@ -3377,7 +3381,7 @@ var init_Pipeline = __esm({
                 card.provenance.push({
                   strategy: "ephemeralHint",
                   strategyId: "ephemeral-hint",
-                  strategyName: "Replan Hint",
+                  strategyName: hints._label ? `Replan Hint (${hints._label})` : "Replan Hint",
                   action: "boosted",
                   score: card.score,
                   reason: `boostTag ${pattern} \xD7${factor}`
@@ -3394,7 +3398,7 @@ var init_Pipeline = __esm({
                 card.provenance.push({
                   strategy: "ephemeralHint",
                   strategyId: "ephemeral-hint",
-                  strategyName: "Replan Hint",
+                  strategyName: hints._label ? `Replan Hint (${hints._label})` : "Replan Hint",
                   action: "boosted",
                   score: card.score,
                   reason: `boostCard ${pattern} \xD7${factor}`
@@ -3404,6 +3408,7 @@ var init_Pipeline = __esm({
           }
         }
         const cardIds = new Set(cards.map((c) => c.cardId));
+        const hintLabel = hints._label ? `Replan Hint (${hints._label})` : "Replan Hint";
         const inject = (card, reason) => {
           if (!cardIds.has(card.cardId)) {
             const floorScore = Math.max(card.score, 1);
@@ -3415,7 +3420,7 @@ var init_Pipeline = __esm({
                 {
                   strategy: "ephemeralHint",
                   strategyId: "ephemeral-hint",
-                  strategyName: "Replan Hint",
+                  strategyName: hintLabel,
                   action: "boosted",
                   score: floorScore,
                   reason
@@ -4664,10 +4669,18 @@ ${above.rows.map((r) => `	${r.id}-${r.key}
        * @param limit - Maximum number of cards to return
        * @returns Cards sorted by score descending
        */
+      _pendingHints = null;
+      setEphemeralHints(hints) {
+        this._pendingHints = hints;
+      }
       async getWeightedCards(limit) {
         const u = await this._getCurrentUser();
         try {
           const navigator = await this.createNavigator(u);
+          if (this._pendingHints) {
+            navigator.setEphemeralHints(this._pendingHints);
+            this._pendingHints = null;
+          }
           return navigator.getWeightedCards(limit);
         } catch (e) {
           logger.error(`[courseDB] Error getting weighted cards: ${e}`);
@@ -7659,9 +7672,17 @@ var init_courseDB2 = __esm({
         }
       }
       // Study Content Source implementation
+      _pendingHints = null;
+      setEphemeralHints(hints) {
+        this._pendingHints = hints;
+      }
       async getWeightedCards(limit) {
         try {
           const navigator = await this.createNavigator(this.userDB);
+          if (this._pendingHints) {
+            navigator.setEphemeralHints(this._pendingHints);
+            this._pendingHints = null;
+          }
           return navigator.getWeightedCards(limit);
         } catch (e) {
           logger.error(`[static/courseDB] Error getting weighted cards: ${e}`);
@@ -9425,8 +9446,9 @@ var ResponseProcessor = class {
     }
     try {
       const history = await cardHistory;
+      let result;
       if (cardRecord.isCorrect) {
-        return this.processCorrectResponse(
+        result = this.processCorrectResponse(
           cardRecord,
           history,
           studySessionItem,
@@ -9436,7 +9458,7 @@ var ResponseProcessor = class {
           cardId
         );
       } else {
-        return this.processIncorrectResponse(
+        result = this.processIncorrectResponse(
           cardRecord,
           history,
           courseRegistrationDoc,
@@ -9448,6 +9470,18 @@ var ResponseProcessor = class {
           sessionViews
         );
       }
+      if (cardRecord.deferAdvance && result.shouldLoadNextCard) {
+        logger.info(
+          "[ResponseProcessor] deferAdvance requested \u2014 suppressing navigation, action stashed:",
+          { nextCardAction: result.nextCardAction }
+        );
+        result = {
+          ...result,
+          shouldLoadNextCard: false,
+          deferred: true
+        };
+      }
+      return result;
     } catch (e) {
       logger.error("[ResponseProcessor] Failed to load card history", { e, cardId });
       throw e;
@@ -11938,6 +11972,12 @@ var SessionController = class _SessionController extends Loggable {
   mixer;
   dataLayer;
   courseNameCache = /* @__PURE__ */ new Map();
+  /**
+   * Default pipeline batch size for new-card planning.
+   * Set via constructor options; falls back to 20 when not specified.
+   * Individual replans can override via `ReplanOptions.limit`.
+   */
+  _defaultBatchLimit = 20;
   sources;
   // dataLayer and getViewComponent now injected into CardHydrationService
   _sessionRecord = [];
@@ -11962,6 +12002,20 @@ var SessionController = class _SessionController extends Loggable {
    * (user state has changed from completing good cards).
    */
   _wellIndicatedRemaining = 0;
+  /**
+   * When true, suppresses the quality-based auto-replan trigger in
+   * nextCard(). Set after a burst replan (small limit) to prevent the
+   * auto-replan from clobbering the burst cards before they're consumed.
+   * Cleared when the depletion-triggered replan fires (newQ exhausted).
+   */
+  _suppressQualityReplan = false;
+  /**
+   * Guards against infinite depletion-triggered replans. Set to true
+   * when a depletion replan fires; cleared when a replan produces
+   * content (newQ.length > 0 after replan) or when an explicit
+   * (non-auto) replan is requested.
+   */
+  _depletionReplanAttempted = false;
   startTime;
   endTime;
   _secondsRemaining;
@@ -11986,8 +12040,12 @@ var SessionController = class _SessionController extends Loggable {
    * @param dataLayer - Data layer provider
    * @param getViewComponent - Function to resolve view components
    * @param mixer - Optional source mixer strategy (defaults to QuotaRoundRobinMixer)
+   * @param options - Optional session-level configuration
+   * @param options.defaultBatchLimit - Default pipeline batch size (default: 20).
+   *   Smaller values for newer users cause more frequent replans, keeping plans
+   *   aligned with rapidly-changing user state.
    */
-  constructor(sources, time, dataLayer, getViewComponent, mixer) {
+  constructor(sources, time, dataLayer, getViewComponent, mixer, options) {
     super();
     this.dataLayer = dataLayer;
     this.mixer = mixer || new QuotaRoundRobinMixer();
@@ -12005,9 +12063,13 @@ var SessionController = class _SessionController extends Loggable {
     this.startTime = /* @__PURE__ */ new Date();
     this._secondsRemaining = time;
     this.endTime = new Date(this.startTime.valueOf() + 1e3 * this._secondsRemaining);
+    if (options?.defaultBatchLimit !== void 0) {
+      this._defaultBatchLimit = options.defaultBatchLimit;
+    }
     this.log(`Session constructed:
     startTime: ${this.startTime}
-    endTime: ${this.endTime}`);
+    endTime: ${this.endTime}
+    defaultBatchLimit: ${this._defaultBatchLimit}`);
   }
   tick() {
     this._secondsRemaining = Math.floor((this.endTime.valueOf() - Date.now()) / 1e3);
@@ -12083,25 +12145,47 @@ var SessionController = class _SessionController extends Loggable {
    * Typical trigger: application-level code (e.g. after a GPC intro completion)
    * calls this to ensure newly-unlocked content appears in the session.
    */
-  async requestReplan(hints) {
+  async requestReplan(options) {
+    const opts = this.normalizeReplanOptions(options);
+    if (opts.hints || opts.label || opts.limit) {
+      this._depletionReplanAttempted = false;
+    }
     if (this._replanPromise) {
       this.log("Replan already in progress, awaiting existing replan");
       return this._replanPromise;
     }
-    if (hints) {
+    if (opts.hints) {
+      const hintsWithLabel = opts.label ? { ...opts.hints, _label: opts.label } : opts.hints;
       for (const source of this.sources) {
-        this.log(`[Hints] source type=${source.constructor.name}, hasMethod=${typeof source.setEphemeralHints}`);
-        source.setEphemeralHints?.(hints);
+        source.setEphemeralHints?.(hintsWithLabel);
       }
     }
-    this.log(`Mid-session replan requested${hints ? ` (hints: ${JSON.stringify(hints)})` : ""}`);
-    this._replanPromise = this._executeReplan();
+    const labelTag = opts.label ? ` [${opts.label}]` : "";
+    this.log(
+      `Mid-session replan requested${labelTag} (limit: ${opts.limit ?? "default"}, mode: ${opts.mode ?? "replace"}${opts.hints ? ", with hints" : ""})`
+    );
+    this._replanPromise = this._executeReplan(opts);
     try {
       await this._replanPromise;
     } finally {
       this._replanPromise = null;
     }
   }
+  /**
+   * Normalise the requestReplan argument. Accepts either a ReplanOptions
+   * object (new API) or a plain Record<string, unknown> (legacy callers
+   * that passed hints directly). Distinguishes the two by checking for
+   * the presence of ReplanOptions-specific keys.
+   */
+  normalizeReplanOptions(input) {
+    if (!input) return {};
+    const replanKeys = ["hints", "limit", "mode", "label"];
+    const inputKeys = Object.keys(input);
+    if (inputKeys.some((k) => replanKeys.includes(k))) {
+      return input;
+    }
+    return { hints: input };
+  }
   /** Minimum well-indicated cards before an additive retry is attempted */
   static MIN_WELL_INDICATED = 5;
   /**
@@ -12120,16 +12204,32 @@ var SessionController = class _SessionController extends Loggable {
    * pass all hierarchy filters, one additive retry is attempted — merging
    * any new high-quality candidates into the front of the queue.
    */
-  async _executeReplan() {
-    const wellIndicated = await this.getWeightedContent({ replan: true });
+  async _executeReplan(opts = {}) {
+    const limit = opts.limit;
+    const mode = opts.mode ?? "replace";
+    const wellIndicated = await this.getWeightedContent({
+      replan: true,
+      additive: mode === "merge",
+      limit
+    });
     this._wellIndicatedRemaining = wellIndicated;
+    if (limit !== void 0 && limit < this._defaultBatchLimit) {
+      this._suppressQualityReplan = true;
+      this.log(`[Replan] Burst mode (limit=${limit}): suppressing quality-based auto-replan`);
+    } else {
+      this._suppressQualityReplan = false;
+    }
     if (wellIndicated >= 0 && wellIndicated < _SessionController.MIN_WELL_INDICATED) {
       this.log(
         `[Replan] Only ${wellIndicated}/${_SessionController.MIN_WELL_INDICATED} well-indicated cards after replan`
       );
     }
+    if (this.newQ.length > 0) {
+      this._depletionReplanAttempted = false;
+    }
     await this.hydrationService.ensureHydratedCards();
-    this.log(`Replan complete: newQ now has ${this.newQ.length} cards`);
+    const labelTag = opts.label ? ` [${opts.label}]` : "";
+    this.log(`Replan complete${labelTag}: newQ now has ${this.newQ.length} cards (mode=${mode})`);
     snapshotQueues(this.reviewQ.length, this.newQ.length, this.failedQ.length);
   }
   addTime(seconds) {
@@ -12189,7 +12289,9 @@ var SessionController = class _SessionController extends Loggable {
         cardIds: this.hydrationService.getHydratedCardIds()
       },
       replan: {
-        inProgress: this._replanPromise !== null
+        inProgress: this._replanPromise !== null,
+        suppressQualityReplan: this._suppressQualityReplan,
+        defaultBatchLimit: this._defaultBatchLimit
       }
     };
   }
@@ -12216,7 +12318,7 @@ var SessionController = class _SessionController extends Loggable {
   async getWeightedContent(options) {
     const replan = options?.replan ?? false;
     const additive = options?.additive ?? false;
-    const limit = 20;
+    const limit = options?.limit ?? this._defaultBatchLimit;
     const batches = [];
     for (let i = 0; i < this.sources.length; i++) {
       const source = this.sources[i];
@@ -12397,10 +12499,26 @@ var SessionController = class _SessionController extends Loggable {
       this.log("nextCard: awaiting in-flight replan before drawing");
       await this._replanPromise;
     }
+    if (this.newQ.length <= 1 && this._secondsRemaining > 0 && !this._replanPromise && !this._depletionReplanAttempted) {
+      this._suppressQualityReplan = false;
+      this._depletionReplanAttempted = true;
+      const otherContent = this.reviewQ.length + this.failedQ.length;
+      if (this.newQ.length === 0 && otherContent === 0) {
+        this.log(
+          `[AutoReplan:depletion] All queues empty with ${this._secondsRemaining}s remaining. Awaiting replan.`
+        );
+        await this.requestReplan();
+      } else {
+        this.log(
+          `[AutoReplan:depletion] newQ has ${this.newQ.length} card(s) (${otherContent} in other queues) with ${this._secondsRemaining}s remaining. Triggering background replan.`
+        );
+        void this.requestReplan();
+      }
+    }
     const REPLAN_BUFFER = 3;
-    if (this._wellIndicatedRemaining <= REPLAN_BUFFER && this.newQ.length > 0 && !this._replanPromise) {
+    if (!this._suppressQualityReplan && this._wellIndicatedRemaining <= REPLAN_BUFFER && this.newQ.length > 0 && !this._replanPromise) {
       this.log(
-        `[AutoReplan] ${this._wellIndicatedRemaining} well-indicated cards remaining (newQ: ${this.newQ.length}). Triggering background replan.`
+        `[AutoReplan:quality] ${this._wellIndicatedRemaining} well-indicated cards remaining (newQ: ${this.newQ.length}). Triggering background replan.`
       );
       void this.requestReplan();
     }