@vue-skuilder/db 0.1.29 → 0.1.30

package/docs/navigators-architecture.md

@@ -374,6 +374,45 @@ Set `staticWeight: true` for foundational strategies that should not be tuned:
 
 ## Creating New Strategies
 
+Strategies can be defined in two places:
+
+- **Framework-internal:** Added directly to `NavigatorRoles` in `index.ts`. Used
+  for general-purpose strategies shipped with the framework.
+- **Consumer-defined:** Registered at app startup via `registerNavigator()`.
+  Used for course-specific strategies that live in the consumer codebase.
+
+Both types participate identically in the pipeline once registered.
+
+### Registration
+
+Framework-internal strategies are listed in the hardcoded `NavigatorRoles` record.
+Consumer-defined strategies use the public `registerNavigator()` API:
+
+```typescript
+import { registerNavigator, NavigatorRole } from '@vue-skuilder/db';
+import { MyFilter } from './MyFilter';
+
+// At app init, before any study session:
+registerNavigator('myFilter', MyFilter, NavigatorRole.FILTER);
+```
+
+The third argument (`role`) is **required** for consumer-defined strategies —
+without it, `PipelineAssembler` cannot classify the strategy and will skip it
+with a warning. For framework-internal strategies the role is already in
+`NavigatorRoles`, so the argument is optional.
+
+A corresponding `NAVIGATION_STRATEGY` document must exist in CouchDB with
+`implementingClass` matching the registered name:
+
+```json
+{
+  "_id": "NAVIGATION_STRATEGY-my-filter",
+  "implementingClass": "myFilter",
+  "name": "My Filter",
+  "serializedData": "{}"
+}
+```
+
 ### Generator
 
 ```typescript
@@ -382,7 +421,7 @@ class MyGenerator extends ContentNavigator implements CardGenerator {
 
   async getWeightedCards(limit: number, context?: GeneratorContext): Promise<WeightedCard[]> {
     const candidates = await this.findCandidates(limit);
-    
+
     return candidates.map(c => ({
       cardId: c.id,
       courseId: this.course.getCourseID(),
@@ -400,8 +439,6 @@ class MyGenerator extends ContentNavigator implements CardGenerator {
 }
 ```
 
-Register in `NavigatorRoles` as `NavigatorRole.GENERATOR`.
-
 ### Filter
 
 ```typescript
@@ -413,7 +450,7 @@ class MyFilter extends ContentNavigator implements CardFilter {
       const multiplier = this.computeMultiplier(card, context);
       const newScore = card.score * multiplier;
       const action = multiplier < 1 ? 'penalized' : multiplier > 1 ? 'boosted' : 'passed';
-      
+
       return {
         ...card,
         score: newScore,
@@ -434,7 +471,29 @@ class MyFilter extends ContentNavigator implements CardFilter {
 }
 ```
 
-Register in `NavigatorRoles` as `NavigatorRole.FILTER`.
+### Accessing Strategy State from Consumer Filters
+
+Consumer strategies can share state with other parts of the consumer app via
+`getStrategyState()` / `putStrategyState()`. Override `strategyKey` to read
+an existing state document:
+
+```typescript
+class MyFilter extends ContentNavigator implements CardFilter {
+  // Read the same doc that another part of the app writes
+  protected get strategyKey(): string {
+    return 'MySharedStateKey';
+  }
+
+  async transform(cards: WeightedCard[], context: FilterContext): Promise<WeightedCard[]> {
+    const state = await this.getStrategyState<MyStateType>();
+    // ... use state for filtering decisions
+  }
+}
+```
+
+This enables **single source of truth** patterns: the consumer app writes state
+via `UsrCrsDataInterface.putStrategyState()`, and the consumer filter reads it
+via the same key. No framework changes needed.
 
 ---
 

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.29",
+  "version": "0.1.30",
   "description": "Database layer for vue-skuilder",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -48,7 +48,7 @@
   },
   "dependencies": {
     "@nilock2/pouchdb-authentication": "^1.0.2",
-    "@vue-skuilder/common": "0.1.29",
+    "@vue-skuilder/common": "0.1.30",
     "cross-fetch": "^4.1.0",
     "moment": "^2.29.4",
     "pouchdb": "^9.0.0",
@@ -62,5 +62,5 @@
     "vite": "^7.0.0",
     "vitest": "^4.0.15"
   },
-  "stableVersion": "0.1.29"
+  "stableVersion": "0.1.30"
 }

package/src/core/navigators/index.ts

@@ -46,10 +46,20 @@ export type NavigatorConstructor = new (
 ) => ContentNavigator;
 
 /**
- * Registry mapping implementingClass names to navigator constructors.
+ * Entry in the navigator registry, storing the constructor and an optional
+ * pipeline role. The role is used by PipelineAssembler to classify
+ * consumer-registered navigators that aren't in the built-in Navigators enum.
+ */
+interface NavigatorRegistryEntry {
+  constructor: NavigatorConstructor;
+  role?: NavigatorRole;
+}
+
+/**
+ * Registry mapping implementingClass names to navigator entries.
  * Populated by registerNavigator() and used by ContentNavigator.create().
  */
-const navigatorRegistry = new Map<string, NavigatorConstructor>();
+const navigatorRegistry = new Map<string, NavigatorRegistryEntry>();
 
 /**
  * Register a navigator implementation.
@@ -57,15 +67,21 @@ const navigatorRegistry = new Map<string, NavigatorConstructor>();
  * Call this to make a navigator available for instantiation by
  * ContentNavigator.create() without relying on dynamic imports.
  *
- * @param implementingClass - The class name (e.g., 'elo', 'hierarchyDefinition')
+ * Passing a `role` is optional for built-in navigators (whose roles are in
+ * the hardcoded `NavigatorRoles` record), but **required** for consumer-
+ * defined navigators that need to participate in pipeline assembly.
+ *
+ * @param implementingClass - The class name (e.g., 'elo', 'letterGatingFilter')
  * @param constructor - The navigator class constructor
+ * @param role - Optional pipeline role (GENERATOR or FILTER)
  */
 export function registerNavigator(
   implementingClass: string,
-  constructor: NavigatorConstructor
+  constructor: NavigatorConstructor,
+  role?: NavigatorRole
 ): void {
-  navigatorRegistry.set(implementingClass, constructor);
-  logger.debug(`[NavigatorRegistry] Registered: ${implementingClass}`);
+  navigatorRegistry.set(implementingClass, { constructor, role });
+  logger.debug(`[NavigatorRegistry] Registered: ${implementingClass}${role ? ` (${role})` : ''}`);
 }
 
 /**
@@ -75,7 +91,7 @@ export function registerNavigator(
  * @returns The constructor, or undefined if not registered
  */
 export function getRegisteredNavigator(implementingClass: string): NavigatorConstructor | undefined {
-  return navigatorRegistry.get(implementingClass);
+  return navigatorRegistry.get(implementingClass)?.constructor;
 }
 
 /**
@@ -88,6 +104,16 @@ export function hasRegisteredNavigator(implementingClass: string): boolean {
   return navigatorRegistry.has(implementingClass);
 }
 
+/**
+ * Get the registered role for a navigator, if one was provided at registration.
+ *
+ * @param implementingClass - The class name to look up
+ * @returns The role, or undefined if not registered or no role was specified
+ */
+export function getRegisteredNavigatorRole(implementingClass: string): NavigatorRole | undefined {
+  return navigatorRegistry.get(implementingClass)?.role;
+}
+
 /**
  * Get all registered navigator names.
  * Useful for debugging and testing.
@@ -371,17 +397,24 @@ export const NavigatorRoles: Record<Navigators, NavigatorRole> = {
  * @returns true if the navigator is a generator, false otherwise
  */
 export function isGenerator(impl: string): boolean {
-  return NavigatorRoles[impl as Navigators] === NavigatorRole.GENERATOR;
+  if (NavigatorRoles[impl as Navigators] === NavigatorRole.GENERATOR) return true;
+  // Fallback: check the registry for consumer-registered navigators
+  return getRegisteredNavigatorRole(impl) === NavigatorRole.GENERATOR;
 }
 
 /**
  * Check if a navigator implementation is a filter.
  *
- * @param impl - Navigator implementation name (e.g., 'elo', 'hierarchyDefinition')
+ * Checks the built-in NavigatorRoles enum first, then falls back to the
+ * navigator registry for consumer-registered navigators.
+ *
+ * @param impl - Navigator implementation name (e.g., 'elo', 'letterGatingFilter')
  * @returns true if the navigator is a filter, false otherwise
  */
 export function isFilter(impl: string): boolean {
-  return NavigatorRoles[impl as Navigators] === NavigatorRole.FILTER;
+  if (NavigatorRoles[impl as Navigators] === NavigatorRole.FILTER) return true;
+  // Fallback: check the registry for consumer-registered navigators
+  return getRegisteredNavigatorRole(impl) === NavigatorRole.FILTER;
 }
 
 /**