@vue-skuilder/db 0.1.17 → 0.1.20

package/docs/todo-nominal-tag-types.md

@@ -0,0 +1,121 @@
+# TODO: Nominal Tag Types
+
+## Status: NOT STARTED
+
+## Problem
+
+Tag identification in the codebase is ambiguous. Two representations are used interchangeably:
+
+- **TagName**: Human-readable name (e.g., `"scales"`, `"C Major"`)
+- **TagID**: Prefixed document ID (e.g., `"TAG-scales"`, `"TAG-C Major"`)
+
+The `getTagID()` function normalizes between them:
+
+```typescript
+// packages/db/src/impl/couch/courseAPI.ts
+export function getTagID(tagName: string): string {
+  const tagPrefix = DocType.TAG.valueOf() + '-';
+  if (tagName.indexOf(tagPrefix) === 0) {
+    return tagName;
+  } else {
+    return tagPrefix + tagName;
+  }
+}
+```
+
+This defensive pattern (accepting either form) suggests the ambiguity causes friction. Function signatures like `getTag(courseID: string, tagName: string)` don't indicate whether they expect a name or ID.
+
+## Proposed Solution: Branded Types
+
+Use TypeScript branded types to distinguish tag names from tag IDs at compile time:
+
+```typescript
+// Branded type definitions
+type TagName = string & { readonly __brand: 'TagName' };
+type TagID = string & { readonly __brand: 'TagID' };
+
+// Smart constructors
+function tagName(s: string): TagName {
+  // Strip prefix if present (normalize to name)
+  const prefix = DocType.TAG.valueOf() + '-';
+  return (s.startsWith(prefix) ? s.slice(prefix.length) : s) as TagName;
+}
+
+function tagID(name: TagName): TagID {
+  return `${DocType.TAG.valueOf()}-${name}` as TagID;
+}
+
+// Now function signatures are self-documenting:
+function getTag(courseID: string, tagName: TagName): Promise<Tag>;
+function addTagToCard(courseID: string, cardID: string, tagID: TagID): Promise<Response>;
+```
+
+## Benefits
+
+1. **Self-documenting APIs**: Function signatures indicate expected format
+2. **Compile-time safety**: Can't accidentally pass a TagID where TagName expected
+3. **Reduced defensive code**: No need for `getTagID()` normalization everywhere
+4. **IDE support**: Autocomplete and type hints clarify intent
+
+## Implementation Steps
+
+### Step 1: Define Branded Types
+
+- [ ] Create `packages/db/src/core/types/tagTypes.ts`
+- [ ] Define `TagName` and `TagID` branded types
+- [ ] Create smart constructors with normalization
+- [ ] Export from `packages/db/src/core/types/index.ts`
+
+### Step 2: Update Tag Interface
+
+- [ ] Update `Tag.name` to be `TagName` type
+- [ ] Update `Tag._id` typing if applicable
+
+### Step 3: Update CourseDB Interface
+
+- [ ] Update `getTag(tagName: TagName)`
+- [ ] Update `createTag(tagName: TagName, ...)`
+- [ ] Update `addTagToCard(cardId, tagId: TagID)`
+- [ ] Update `removeTagFromCard(cardId, tagId: TagID)`
+
+### Step 4: Update Implementations
+
+- [ ] `packages/db/src/impl/couch/courseDB.ts`
+- [ ] `packages/db/src/impl/couch/courseAPI.ts`
+- [ ] `packages/db/src/impl/static/courseDB.ts` (if applicable)
+
+### Step 5: Update Consumers
+
+- [ ] Navigation strategies using tags
+- [ ] Classroom tag assignments
+- [ ] MCP tag resources
+- [ ] UI components displaying/selecting tags
+
+## Files Affected
+
+| File | Changes |
+|------|---------|
+| `core/types/tagTypes.ts` | New file with branded types |
+| `core/types/types-legacy.ts` | Update `Tag` interface |
+| `core/interfaces/courseDB.ts` | Update method signatures |
+| `impl/couch/courseAPI.ts` | Update `getTagID`, `addTagToCard` |
+| `impl/couch/courseDB.ts` | Update tag-related functions |
+| Multiple navigators | Update tag handling |
+
+## Migration Strategy
+
+1. Start with type definitions that are compatible with plain strings
+2. Add branded types gradually, file by file
+3. Use `as TagName` / `as TagID` at boundaries during migration
+4. Tighten constraints once all code is updated
+
+## Considerations
+
+- **Runtime cost**: Zero - branded types are compile-time only
+- **Breaking change**: Moderate - requires updating call sites
+- **Effort**: Medium - touches many files but changes are mechanical
+
+## Related
+
+- `TagFilter` interface uses `string[]` for simplicity; could use `TagName[]` after this work
+- Hierarchical tags (e.g., `"parent>child"`) may need additional consideration

package/docs/todo-strategy-authoring.md

@@ -0,0 +1,401 @@
+# NavigationStrategy Authoring Tools
+
+## Status: UI COMPLETE ✅ (CLI/MCP Optional)
+
+## Goal
+
+Provide tools for course authors to create and configure NavigationStrategy documents
+without direct database manipulation. This includes UI components, CLI commands, and
+potentially MCP tools.
+
+**UI implementation completed.** CLI and MCP remain as optional future enhancements for
+scriptable/agent-based workflows.
+
+## Current State (Updated)
+
+### What Exists ✅
+
+| Component | Location | Status |
+|-----------|----------|--------|
+| `HardcodedOrderConfigForm.vue` | `packages/edit-ui/src/components/NavigationStrategy/` | ✅ Complete |
+| `HierarchyConfigForm.vue` | `packages/edit-ui/src/components/NavigationStrategy/` | ✅ Complete |
+| `InterferenceConfigForm.vue` | `packages/edit-ui/src/components/NavigationStrategy/` | ✅ Complete |
+| `RelativePriorityConfigForm.vue` | `packages/edit-ui/src/components/NavigationStrategy/` | ✅ Complete |
+| `NavigationStrategyEditor.vue` | `packages/edit-ui/src/components/NavigationStrategy/` | ✅ All strategy types supported |
+| `NavigationStrategyList.vue` | `packages/edit-ui/src/components/NavigationStrategy/` | ✅ Compact layout, edit/delete |
+| `CourseDB.addNavigationStrategy()` | `packages/db/src/impl/couch/courseDB.ts` | ✅ DB write method |
+| `CourseDB.updateNavigationStrategy()` | `packages/db/src/impl/couch/courseDB.ts` | ✅ DB update method |
+| `CourseDB.getAllNavigationStrategies()` | `packages/db/src/impl/couch/courseDB.ts` | ✅ DB read method |
+
+### What's Complete
+
+- ✅ UI forms for all four strategy types (Hardcoded, Hierarchy, Interference, RelativePriority)
+- ✅ Dual input modes (Visual Editor / JSON Editor) for each form
+- ✅ Tag loading from course database
+- ✅ Real-time validation with error messages
+- ✅ Edit functionality for existing strategies
+- ✅ Compact, non-modal two-column layout
+- ✅ Responsive design (desktop and mobile)
+- ✅ Full CRUD operations (Create, Read, Update, Delete)
+
+### What's Optional (Future Enhancements)
+
+- ⏸️ CLI commands for strategy creation (scriptable workflows)
+- ⏸️ MCP tools for agent-based authoring (LLM-guided config generation)
+- ⏸️ Strategy behavior preview/simulation
+
+## Strategy Types and Their Configs
+
+### 1. HierarchyDefinition
+
+```typescript
+interface HierarchyConfig {
+  prerequisites: {
+    [tagId: string]: TagPrerequisite[];
+  };
+  delegateStrategy?: string;  // default: "elo"
+}
+
+interface TagPrerequisite {
+  tag: string;
+  masteryThreshold?: {
+    minElo?: number;
+    minCount?: number;
+  };
+}
+```
+
+**Example:**
+```json
+{
+  "prerequisites": {
+    "cvc-words": [
+      { "tag": "letter-sounds", "masteryThreshold": { "minCount": 10, "minElo": 1050 } }
+    ],
+    "blends": [
+      { "tag": "cvc-words", "masteryThreshold": { "minCount": 20 } }
+    ]
+  },
+  "delegateStrategy": "elo"
+}
+```
+
+**UI Requirements:**
+- Tag selector (from course's available tags)
+- Prerequisite builder (tag → requires tags with thresholds)
+- Threshold inputs (minCount, minElo)
+- Delegate strategy selector
+
+---
+
+### 2. InterferenceMitigator
+
+```typescript
+interface InterferenceConfig {
+  interferenceSets: InterferenceGroup[];
+  maturityThreshold?: {
+    minCount?: number;
+    minElo?: number;
+    minElapsedDays?: number;
+  };
+  defaultDecay?: number;
+  delegateStrategy?: string;
+}
+
+interface InterferenceGroup {
+  tags: string[];
+  decay?: number;
+}
+```
+
+**Example:**
+```json
+{
+  "interferenceSets": [
+    { "tags": ["letter-b", "letter-d", "letter-p"], "decay": 0.9 },
+    { "tags": ["letter-m", "letter-n"], "decay": 0.7 }
+  ],
+  "maturityThreshold": { "minCount": 15, "minElapsedDays": 3 },
+  "defaultDecay": 0.8
+}
+```
+
+**UI Requirements:**
+- Interference group builder (add/remove groups)
+- Tag multi-selector for each group
+- Decay slider (0-1) per group
+- Maturity threshold inputs
+- Delegate strategy selector
+
+---
+
+### 3. RelativePriority
+
+```typescript
+interface RelativePriorityConfig {
+  tagPriorities: { [tagId: string]: number };
+  defaultPriority?: number;
+  combineMode?: 'max' | 'average' | 'min';
+  priorityInfluence?: number;
+  delegateStrategy?: string;
+}
+```
+
+**Example:**
+```json
+{
+  "tagPriorities": {
+    "letter-s": 0.95,
+    "letter-t": 0.90,
+    "letter-a": 0.88,
+    "letter-x": 0.10,
+    "letter-z": 0.05
+  },
+  "defaultPriority": 0.5,
+  "combineMode": "max",
+  "priorityInfluence": 0.5
+}
+```
+
+**UI Requirements:**
+- Tag list with priority sliders (0-1)
+- Default priority input
+- Combine mode selector (max/average/min)
+- Priority influence slider
+- Delegate strategy selector
+
+---
+
+## Implementation Options
+
+### Option A: Extend NavigationStrategyEditor.vue
+
+**Pros:**
+- Single location for all strategy editing
+- Consistent with existing UI patterns
+- User-facing, accessible to course authors
+
+**Cons:**
+- More complex Vue component
+- Requires form validation logic
+
+**Implementation:**
+1. Add strategy type selector dropdown
+2. Conditional rendering of config forms based on type
+3. Form validation before save
+4. Serialize config to `serializedData` JSON
+
+---
+
+### Option B: CLI Commands
+
+**Pros:**
+- Scriptable, automatable
+- Good for bulk operations
+- Can be used by agents
+
+**Cons:**
+- Not user-friendly for non-technical authors
+- Requires terminal access
+
+**Implementation:**
+```bash
+# Create a hierarchy strategy
+yarn cli strategy:create <courseId> \
+  --type hierarchy \
+  --name "Phonics Progression" \
+  --config ./hierarchy-config.json
+
+# Create an interference strategy
+yarn cli strategy:create <courseId> \
+  --type interference \
+  --config ./interference-config.json
+
+# List strategies
+yarn cli strategy:list <courseId>
+
+# Set default strategy
+yarn cli strategy:set-default <courseId> <strategyId>
+
+# Delete strategy
+yarn cli strategy:delete <courseId> <strategyId>
+```
+
+**Files to modify:**
+- `packages/cli/src/commands/` — Add strategy commands
+- `packages/cli/src/index.ts` — Register new commands
+
+---
+
+### Option C: MCP Tools
+
+**Pros:**
+- Agent-accessible for automated course building
+- Consistent with existing MCP pattern
+- Can leverage LLM for config generation
+
+**Cons:**
+- Requires MCP client
+- Not directly user-facing
+
+**Implementation:**
+Add to `packages/mcp/src/tools/`:
+
+```typescript
+// create_navigation_strategy tool
+{
+  name: 'create_navigation_strategy',
+  description: 'Create a navigation strategy for the course',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      strategyType: { enum: ['hierarchy', 'interference', 'relativePriority'] },
+      name: { type: 'string' },
+      description: { type: 'string' },
+      config: { type: 'object' }
+    }
+  }
+}
+```
+
+---
+
+## Implementation Completed: UI-First Approach ✅
+
+**Phase 1: UI Forms (COMPLETED)**
+- ✅ All four strategy configuration forms implemented
+- ✅ Visual editor with guided inputs
+- ✅ JSON editor for power users
+- ✅ Tag selectors, sliders, multi-selects
+- ✅ Validation and error messages
+- ✅ Edit/Create/Delete functionality
+- ✅ Compact two-column layout (list + form)
+
+**Phase 2 (Optional): CLI Commands**
+- Scriptable strategy creation from JSON files
+- Bulk operations and automation
+- Terminal-based workflows
+- **Status:** Not started, optional enhancement
+
+**Phase 3 (Optional): MCP Tools**
+- Agent-accessible strategy authoring
+- LLM-guided config generation
+- Extends existing MCP infrastructure
+- **Status:** Not started, optional enhancement
+
+---
+
+## Validation Requirements
+
+All authoring tools should validate:
+
+1. **Tag existence**: All referenced tags exist in the course
+2. **Circular dependencies** (Hierarchy): No circular prerequisite chains
+3. **Config completeness**: Required fields present
+4. **Value ranges**: Scores/thresholds in valid ranges (e.g., 0-1)
+5. **Delegate validity**: Delegate strategy type exists
+
+```typescript
+interface ValidationResult {
+  valid: boolean;
+  errors: Array<{
+    field: string;
+    message: string;
+  }>;
+  warnings: Array<{
+    field: string;
+    message: string;
+  }>;
+}
+```
+
+---
+
+## Files Created/Modified
+
+### UI Implementation (COMPLETED ✅)
+
+| File | Action | Description | Status |
+|------|--------|-------------|--------|
+| `packages/edit-ui/src/components/NavigationStrategy/HardcodedOrderConfigForm.vue` | CREATED | Card ID list form | ✅ |
+| `packages/edit-ui/src/components/NavigationStrategy/HierarchyConfigForm.vue` | CREATED | Prerequisite gating config | ✅ |
+| `packages/edit-ui/src/components/NavigationStrategy/InterferenceConfigForm.vue` | CREATED | Interference groups config | ✅ |
+| `packages/edit-ui/src/components/NavigationStrategy/RelativePriorityConfigForm.vue` | CREATED | Tag priorities config | ✅ |
+| `packages/edit-ui/src/components/NavigationStrategy/NavigationStrategyEditor.vue` | MODIFIED | Two-column layout, all strategy types | ✅ |
+| `packages/edit-ui/src/components/NavigationStrategy/NavigationStrategyList.vue` | MODIFIED | Compact density, simplified display | ✅ |
+
+### CLI Implementation (OPTIONAL, NOT STARTED)
+
+| File | Action | Description | Status |
+|------|--------|-------------|--------|
+| `packages/cli/src/commands/strategy.ts` | CREATE | Strategy management commands | ⏸️ |
+| `packages/cli/src/utils/strategy-validation.ts` | CREATE | Config validation utilities | ⏸️ |
+| `packages/cli/src/index.ts` | MODIFY | Register strategy commands | ⏸️ |
+
+### MCP Implementation (OPTIONAL, NOT STARTED)
+
+| File | Action | Description | Status |
+|------|--------|-------------|--------|
+| `packages/mcp/src/tools/create-navigation-strategy.ts` | CREATE | Create strategy tool | ⏸️ |
+| `packages/mcp/src/tools/update-navigation-strategy.ts` | CREATE | Update strategy tool | ⏸️ |
+| `packages/mcp/src/tools/list-navigation-strategies.ts` | CREATE | List strategies tool | ⏸️ |
+| `packages/mcp/src/tools/delete-navigation-strategy.ts` | CREATE | Delete strategy tool | ⏸️ |
+| `packages/mcp/src/types/tools.ts` | MODIFY | Add strategy schemas | ⏸️ |
+| `packages/mcp/src/tools/index.ts` | MODIFY | Export new tools | ⏸️ |
+
+---
+
+## Key Features Delivered
+
+### Dual Input Modes
+All forms support two modes for flexibility:
+- **Visual Editor**: Guided UI with selectors, sliders, and inputs
+- **JSON Editor**: Direct JSON editing with real-time validation
+
+### Strategy-Specific Capabilities
+
+**HierarchyConfigForm:**
+- Add/remove prerequisite rules
+- Tag selectors for gated tags and their prerequisites
+- Mastery thresholds (minCount, minElo)
+- Delegate strategy selector
+
+**InterferenceConfigForm:**
+- Add/remove interference groups
+- Multi-tag selector for each group
+- Per-group decay sliders (0-1)
+- Maturity threshold configuration (minCount, minElo, minElapsedDays)
+- Default decay setting
+
+**RelativePriorityConfigForm:**
+- Individual priority sliders for all course tags
+- Default priority configuration
+- Combine mode selector (max/average/min)
+- Priority influence slider
+
+### User Experience
+- **Compact Layout**: Two-column design (strategy list + form)
+- **Always Visible**: No modal dialogs, form always accessible
+- **Responsive**: Works on desktop and mobile
+- **Real-time Validation**: Inline error messages
+- **Tag Loading**: Automatically fetches course tags
+- **Edit Support**: Click any strategy to edit
+
+---
+
+## Access
+
+The NavigationStrategy editor is accessible in:
+- **studio-ui**: `/course-editor` route → "Navigation" tab
+- **platform-ui**: `/edit/:courseId` route → "Navigation" tab
+
+---
+
+## Related Files
+
+- `packages/db/src/core/types/contentNavigationStrategy.ts` — Strategy data schema
+- `packages/db/src/impl/couch/courseDB.ts` — DB methods for strategies
+- `packages/db/src/core/navigators/hierarchyDefinition.ts` — Config interface reference
+- `packages/db/src/core/navigators/interferenceMitigator.ts` — Config interface reference
+- `packages/db/src/core/navigators/relativePriority.ts` — Config interface reference
+- `packages/edit-ui/src/components/NavigationStrategy/` — UI components (all forms)

package/eslint.config.mjs

@@ -3,7 +3,7 @@ import backendConfig from '../../eslint.config.backend.mjs';
 export default [
   ...backendConfig,
   {
-    ignores: ['node_modules/**', 'dist/**', 'eslint.config.mjs', 'tsup.config.ts'],
+    ignores: ['node_modules/**', 'dist/**', 'eslint.config.mjs', 'tsup.config.ts', 'vitest.config.ts'],
   },
   {
     languageOptions: {

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@vue-skuilder/db",
+  "type": "module",
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.17",
+  "version": "0.1.20",
   "description": "Database layer for vue-skuilder",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -39,13 +40,15 @@
     "build": "tsup",
     "build:debug": "tsup --sourcemap inline",
     "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "lint": "npx eslint .",
     "lint:fix": "npx eslint . --fix",
     "lint:check": "npx eslint . --max-warnings 0"
   },
   "dependencies": {
     "@nilock2/pouchdb-authentication": "^1.0.2",
-    "@vue-skuilder/common": "0.1.17",
+    "@vue-skuilder/common": "0.1.20",
     "cross-fetch": "^4.1.0",
     "moment": "^2.29.4",
     "pouchdb": "^9.0.0",
@@ -55,7 +58,9 @@
   "devDependencies": {
     "@types/uuid": "^10.0.0",
     "tsup": "^8.0.2",
-    "typescript": "~5.7.2"
+    "typescript": "~5.9.3",
+    "vite": "^7.0.0",
+    "vitest": "^4.0.15"
   },
-  "stableVersion": "0.1.17"
+  "stableVersion": "0.1.20"
 }

package/src/core/index.ts

@@ -3,6 +3,7 @@
 export * from './interfaces';
 export * from './types/types-legacy';
 export * from './types/user';
+export * from './types/strategyState';
 export * from '../util/Loggable';
 export * from './util';
 export * from './navigators';

package/src/core/interfaces/contentSource.ts

@@ -2,6 +2,41 @@ import { getDataLayer } from '@db/factory';
 import { UserDBInterface } from '..';
 import { StudentClassroomDB } from '../../impl/couch/classroomDB';
 import { ScheduledCard } from '@db/core/types/user';
+import { WeightedCard } from '../navigators';
+import { TagFilter, hasActiveFilter } from '@vue-skuilder/common';
+import { TagFilteredContentSource } from '../../study/TagFilteredContentSource';
+
+// ============================================================================
+// API MIGRATION NOTICE
+// ============================================================================
+//
+// The StudyContentSource interface is being superseded by the ContentNavigator
+// class and its getWeightedCards() API. See:
+//   packages/db/src/core/navigators/ARCHITECTURE.md
+//
+// HISTORICAL CONTEXT:
+// - This interface was designed to abstract 'classrooms' and 'courses' as
+//   content sources for study sessions.
+// - getNewCards() and getPendingReviews() were artifacts of two hard-coded
+//   navigation strategies: ELO proximity (new) and SRS scheduling (reviews).
+// - The new/review split reflected implementation details, not fundamentals.
+//
+// THE PROBLEM:
+// - "What does 'get reviews' mean for an interference mitigator?" - it doesn't.
+// - SRS is just one strategy that could express review urgency as scores.
+// - Some strategies generate candidates, others filter/score them.
+//
+// THE SOLUTION:
+// - ContentNavigator.getWeightedCards() returns unified scored candidates.
+// - WeightedCard.source field distinguishes new/review/failed (metadata, not API).
+// - Strategies compose via delegate pattern (filter wraps generator).
+//
+// MIGRATION PATH:
+// 1. ContentNavigator implements StudyContentSource for backward compat
+// 2. SessionController will migrate to call getWeightedCards()
+// 3. Legacy methods will be deprecated, then removed
+//
+// ============================================================================
 
 export type StudySessionFailedItem = StudySessionFailedNewItem | StudySessionFailedReviewItem;
 
@@ -43,12 +78,60 @@ export interface StudySessionItem {
 export interface ContentSourceID {
   type: 'course' | 'classroom';
   id: string;
+  /**
+   * Optional tag filter for scoped study sessions.
+   * When present, creates a TagFilteredContentSource instead of a regular course source.
+   */
+  tagFilter?: TagFilter;
 }
 
 // #region docs_StudyContentSource
+/**
+ * Interface for sources that provide study content to SessionController.
+ *
+ * @deprecated This interface will be superseded by ContentNavigator.getWeightedCards().
+ * The getNewCards/getPendingReviews split was an artifact of hard-coded ELO and SRS
+ * strategies. The new API returns unified WeightedCard[] with scores.
+ *
+ * MIGRATION:
+ * - Implement ContentNavigator instead of StudyContentSource directly
+ * - Override getWeightedCards() as the primary method
+ * - Legacy methods can delegate to getWeightedCards() or be left as-is
+ *
+ * See: packages/db/src/core/navigators/ARCHITECTURE.md
+ */
 export interface StudyContentSource {
+  /**
+   * Get cards scheduled for review based on SRS algorithm.
+   *
+   * @deprecated Will be replaced by getWeightedCards() which returns scored candidates.
+   * Review urgency will be expressed as a score rather than a separate method.
+   */
   getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]>;
+
+  /**
+   * Get new cards for introduction, typically ordered by ELO proximity.
+   *
+   * @deprecated Will be replaced by getWeightedCards() which returns scored candidates.
+   * New card selection and scoring will be unified with review scoring.
+   *
+   * @param n - Maximum number of new cards to return
+   */
   getNewCards(n?: number): Promise<StudySessionNewItem[]>;
+
+  /**
+   * Get cards with suitability scores for presentation.
+   *
+   * This is the PRIMARY API for content sources going forward. Returns unified
+   * scored candidates that can be sorted and selected by SessionController.
+   *
+   * The `source` field on WeightedCard indicates origin ('new' | 'review' | 'failed')
+   * for queue routing purposes during the migration period.
+   *
+   * @param limit - Maximum number of cards to return
+   * @returns Cards sorted by score descending
+   */
+  getWeightedCards?(limit: number): Promise<WeightedCard[]>;
 }
 // #endregion docs_StudyContentSource
 
@@ -59,11 +142,12 @@ export async function getStudySource(
   if (source.type === 'classroom') {
     return await StudentClassroomDB.factory(source.id, user);
   } else {
-    // if (source.type === 'course') - removed so tsc is certain something returns
-    // return new CourseDB(source.id, async () => {
-    //   return user;
-    // });
+    // Check if this is a tag-filtered course source
+    if (hasActiveFilter(source.tagFilter)) {
+      return new TagFilteredContentSource(source.id, source.tagFilter!, user);
+    }
 
+    // Regular course source
     return getDataLayer().getCourseDB(source.id) as unknown as StudyContentSource;
   }
 }