@pie-players/pie-assessment-toolkit 0.2.0

package/dist/services/ContextVariableStore.js

@@ -0,0 +1,207 @@
+/**
+ * Context Variable Store
+ *
+ * Standalone service for managing QTI 3.0 context variables.
+ * Context variables are global assessment-level variables that can be
+ * shared across items.
+ *
+ * Can be used independently by any assessment player without requiring
+ * the full AssessmentPlayer.
+ *
+ * Part of PIE Assessment Toolkit.
+ */
+/**
+ * Standalone service for managing QTI 3.0 context variables.
+ *
+ * Context variables are global assessment-level variables that can be
+ * shared across items. Can be used independently by any assessment player.
+ *
+ * @example
+ * ```typescript
+ * // Initialize with declarations
+ * const store = new ContextVariableStore(declarations);
+ *
+ * // Get/set variables
+ * const seed = store.get('RANDOM_SEED');
+ * store.set('DIFFICULTY_LEVEL', 'hard');
+ *
+ * // Pass to items
+ * const context = store.toObject();
+ * await renderItem(item, session, context);
+ *
+ * // Persist in session
+ * session.contextVariables = store.toObject();
+ * ```
+ */
+export class ContextVariableStore {
+    variables = new Map();
+    declarations = new Map();
+    /**
+     * Initialize store with context declarations from assessment
+     *
+     * @param declarations QTI 3.0 context declarations
+     */
+    constructor(declarations) {
+        if (declarations) {
+            this.initialize(declarations);
+        }
+    }
+    /**
+     * Initialize context variables from declarations
+     *
+     * Sets each variable to its defaultValue or type-appropriate default.
+     */
+    initialize(declarations) {
+        this.declarations.clear();
+        this.variables.clear();
+        for (const decl of declarations) {
+            this.declarations.set(decl.identifier, decl);
+            const value = decl.defaultValue ??
+                this.getDefaultValueForType(decl.baseType, decl.cardinality);
+            this.variables.set(decl.identifier, value);
+        }
+        console.debug(`ContextVariableStore: Initialized ${declarations.length} context variables:`, Array.from(this.variables.keys()));
+    }
+    /**
+     * Get context variable value
+     *
+     * @param identifier Variable identifier
+     * @returns Variable value or undefined if not found
+     */
+    get(identifier) {
+        return this.variables.get(identifier);
+    }
+    /**
+     * Set context variable value
+     *
+     * @param identifier Variable identifier
+     * @param value New value
+     */
+    set(identifier, value) {
+        if (!this.declarations.has(identifier)) {
+            console.warn(`ContextVariableStore: Setting undeclared context variable: ${identifier}`, "Consider declaring it in contextDeclarations");
+        }
+        // Type validation (optional but recommended)
+        const decl = this.declarations.get(identifier);
+        if (decl) {
+            this.validateValue(decl, value);
+        }
+        this.variables.set(identifier, value);
+    }
+    /**
+     * Check if variable exists
+     */
+    has(identifier) {
+        return this.variables.has(identifier);
+    }
+    /**
+     * Get all variable names
+     */
+    getIdentifiers() {
+        return Array.from(this.variables.keys());
+    }
+    /**
+     * Get all variables as object (for passing to PIE elements)
+     *
+     * @returns Plain object with all context variables
+     */
+    toObject() {
+        return Object.fromEntries(this.variables);
+    }
+    /**
+     * Load state from serialized object (for session restore)
+     *
+     * @param state Object containing context variable values
+     */
+    fromObject(state) {
+        for (const [key, value] of Object.entries(state)) {
+            this.variables.set(key, value);
+        }
+    }
+    /**
+     * Clear all variables (reset to defaults)
+     */
+    reset() {
+        for (const [identifier, decl] of this.declarations) {
+            const value = decl.defaultValue ??
+                this.getDefaultValueForType(decl.baseType, decl.cardinality);
+            this.variables.set(identifier, value);
+        }
+        console.debug("ContextVariableStore: Reset to default values");
+    }
+    /**
+     * Get declaration for variable
+     *
+     * @param identifier Variable identifier
+     * @returns Declaration or undefined if not found
+     */
+    getDeclaration(identifier) {
+        return this.declarations.get(identifier);
+    }
+    /**
+     * Get all declarations
+     */
+    getDeclarations() {
+        return Array.from(this.declarations.values());
+    }
+    /**
+     * Get default value for QTI base type
+     *
+     * @private
+     */
+    getDefaultValueForType(baseType, cardinality) {
+        if (cardinality === "multiple" || cardinality === "ordered") {
+            return [];
+        }
+        if (cardinality === "record") {
+            return {};
+        }
+        // Single cardinality defaults
+        switch (baseType) {
+            case "boolean":
+                return false;
+            case "integer":
+                return 0;
+            case "float":
+                return 0.0;
+            case "string":
+            case "identifier":
+            case "uri":
+                return "";
+            case "point":
+                return [0, 0];
+            case "pair":
+                return ["", ""];
+            case "directedPair":
+                return ["", ""];
+            case "duration":
+                return 0;
+            case "file":
+                return null;
+            default:
+                return null;
+        }
+    }
+    /**
+     * Validate value matches declared type (basic validation)
+     *
+     * @private
+     */
+    validateValue(decl, value) {
+        // Basic type checking - can be extended
+        if (decl.baseType === "integer" && !Number.isInteger(value)) {
+            console.warn(`ContextVariableStore: Variable ${decl.identifier} expects integer, got:`, typeof value);
+        }
+        if (decl.baseType === "float" && typeof value !== "number") {
+            console.warn(`ContextVariableStore: Variable ${decl.identifier} expects float, got:`, typeof value);
+        }
+        if (decl.baseType === "boolean" && typeof value !== "boolean") {
+            console.warn(`ContextVariableStore: Variable ${decl.identifier} expects boolean, got:`, typeof value);
+        }
+        if ((decl.cardinality === "multiple" || decl.cardinality === "ordered") &&
+            !Array.isArray(value)) {
+            console.warn(`ContextVariableStore: Variable ${decl.identifier} expects array (cardinality: ${decl.cardinality}), got:`, typeof value);
+        }
+    }
+}
+//# sourceMappingURL=ContextVariableStore.js.map

package/dist/services/ContextVariableStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContextVariableStore.js","sourceRoot":"","sources":["../../src/services/ContextVariableStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAO,oBAAoB;IACxB,SAAS,GAAqB,IAAI,GAAG,EAAE,CAAC;IACxC,YAAY,GAAoC,IAAI,GAAG,EAAE,CAAC;IAElE;;;;OAIG;IACH,YAAY,YAAmC;QAC9C,IAAI,YAAY,EAAE,CAAC;YAClB,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;QAC/B,CAAC;IACF,CAAC;IAED;;;;OAIG;IACH,UAAU,CAAC,YAAkC;QAC5C,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC;QAC1B,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QAEvB,KAAK,MAAM,IAAI,IAAI,YAAY,EAAE,CAAC;YACjC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;YAE7C,MAAM,KAAK,GACV,IAAI,CAAC,YAAY;gBACjB,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;YAE9D,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;QAC5C,CAAC;QAED,OAAO,CAAC,KAAK,CACZ,qCAAqC,YAAY,CAAC,MAAM,qBAAqB,EAC7E,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CACjC,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,GAAG,CAAC,UAAkB;QACrB,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACvC,CAAC;IAED;;;;;OAKG;IACH,GAAG,CAAC,UAAkB,EAAE,KAAU;QACjC,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;YACxC,OAAO,CAAC,IAAI,CACX,8DAA8D,UAAU,EAAE,EAC1E,8CAA8C,CAC9C,CAAC;QACH,CAAC;QAED,6CAA6C;QAC7C,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAC/C,IAAI,IAAI,EAAE,CAAC;YACV,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACjC,CAAC;QAED,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IACvC,CAAC;IAED;;OAEG;IACH,GAAG,CAAC,UAAkB;QACrB,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACvC,CAAC;IAED;;OAEG;IACH,cAAc;QACb,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC;IAC1C,CAAC;IAED;;;;OAIG;IACH,QAAQ;QACP,OAAO,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC3C,CAAC;IAED;;;;OAIG;IACH,UAAU,CAAC,KAA0B;QACpC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YAClD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAChC,CAAC;IACF,CAAC;IAED;;OAEG;IACH,KAAK;QACJ,KAAK,MAAM,CAAC,UAAU,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACpD,MAAM,KAAK,GACV,IAAI,CAAC,YAAY;gBACjB,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;YAC9D,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;QACvC,CAAC;QAED,OAAO,CAAC,KAAK,CAAC,+CAA+C,CAAC,CAAC;IAChE,CAAC;IAED;;;;;OAKG;IACH,cAAc,CAAC,UAAkB;QAChC,OAAO,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAC1C,CAAC;IAED;;OAEG;IACH,eAAe;QACd,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED;;;;OAIG;IACK,sBAAsB,CAAC,QAAgB,EAAE,WAAmB;QACnE,IAAI,WAAW,KAAK,UAAU,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;YAC7D,OAAO,EAAE,CAAC;QACX,CAAC;QAED,IAAI,WAAW,KAAK,QAAQ,EAAE,CAAC;YAC9B,OAAO,EAAE,CAAC;QACX,CAAC;QAED,8BAA8B;QAC9B,QAAQ,QAAQ,EAAE,CAAC;YAClB,KAAK,SAAS;gBACb,OAAO,KAAK,CAAC;YACd,KAAK,SAAS;gBACb,OAAO,CAAC,CAAC;YACV,KAAK,OAAO;gBACX,OAAO,GAAG,CAAC;YACZ,KAAK,QAAQ,CAAC;YACd,KAAK,YAAY,CAAC;YAClB,KAAK,KAAK;gBACT,OAAO,EAAE,CAAC;YACX,KAAK,OAAO;gBACX,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;YACf,KAAK,MAAM;gBACV,OAAO,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;YACjB,KAAK,cAAc;gBAClB,OAAO,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;YACjB,KAAK,UAAU;gBACd,OAAO,CAAC,CAAC;YACV,KAAK,MAAM;gBACV,OAAO,IAAI,CAAC;YACb;gBACC,OAAO,IAAI,CAAC;QACd,CAAC;IACF,CAAC;IAED;;;;OAIG;IACK,aAAa,CAAC,IAAwB,EAAE,KAAU;QACzD,wCAAwC;QACxC,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;YAC7D,OAAO,CAAC,IAAI,CACX,kCAAkC,IAAI,CAAC,UAAU,wBAAwB,EACzE,OAAO,KAAK,CACZ,CAAC;QACH,CAAC;QAED,IAAI,IAAI,CAAC,QAAQ,KAAK,OAAO,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC5D,OAAO,CAAC,IAAI,CACX,kCAAkC,IAAI,CAAC,UAAU,sBAAsB,EACvE,OAAO,KAAK,CACZ,CAAC;QACH,CAAC;QAED,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;YAC/D,OAAO,CAAC,IAAI,CACX,kCAAkC,IAAI,CAAC,UAAU,wBAAwB,EACzE,OAAO,KAAK,CACZ,CAAC;QACH,CAAC;QAED,IACC,CAAC,IAAI,CAAC,WAAW,KAAK,UAAU,IAAI,IAAI,CAAC,WAAW,KAAK,SAAS,CAAC;YACnE,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EACpB,CAAC;YACF,OAAO,CAAC,IAAI,CACX,kCAAkC,IAAI,CAAC,UAAU,gCAAgC,IAAI,CAAC,WAAW,SAAS,EAC1G,OAAO,KAAK,CACZ,CAAC;QACH,CAAC;IACF,CAAC;CACD"}

package/dist/services/ElementToolStateStore.d.ts

@@ -0,0 +1,125 @@
+/**
+ * ElementToolStateStore - Manages element-level ephemeral tool state
+ *
+ * Provides centralized storage for UI tool state (answer eliminations, flags, etc.)
+ * that should NOT be sent to the server for scoring. Each element is uniquely identified
+ * across the entire assessment using composite keys.
+ *
+ * Key features:
+ * - Element-level granularity (not item-level)
+ * - Composite keys for global uniqueness: `assessmentId:sectionId:itemId:elementId`
+ * - Cross-section state persistence
+ * - Reactive subscriptions
+ * - Optional persistence callback integration
+ * - Generic solution for any tool
+ */
+export interface ElementIdComponents {
+    assessmentId: string;
+    sectionId: string;
+    itemId: string;
+    elementId: string;
+}
+export declare class ElementToolStateStore {
+    private elementStates;
+    private listeners;
+    private onStateChange;
+    /**
+     * Generates a globally unique element ID by combining assessment, section, item, and element IDs.
+     * Format: `${assessmentId}:${sectionId}:${itemId}:${elementId}`
+     *
+     * @example
+     * getGlobalElementId('demo-assessment', 'section-1', 'q1', 'mc1')
+     * // Returns: "demo-assessment:section-1:q1:mc1"
+     */
+    getGlobalElementId(assessmentId: string, sectionId: string, itemId: string, elementId: string): string;
+    /**
+     * Parses a global element ID into its component parts.
+     *
+     * @example
+     * parseGlobalElementId('demo-assessment:section-1:q1:mc1')
+     * // Returns: { assessmentId: 'demo-assessment', sectionId: 'section-1', itemId: 'q1', elementId: 'mc1' }
+     */
+    parseGlobalElementId(globalElementId: string): ElementIdComponents | null;
+    /**
+     * Sets tool state for a specific element.
+     * Notifies all subscribers and triggers persistence callback.
+     *
+     * @param globalElementId Composite key identifying the element
+     * @param toolId Tool identifier (e.g., 'answerEliminator', 'flagging')
+     * @param state Tool-specific state object
+     */
+    setState(globalElementId: string, toolId: string, state: any): void;
+    /**
+     * Gets tool state for a specific element.
+     *
+     * @param globalElementId Composite key identifying the element
+     * @param toolId Tool identifier
+     * @returns Tool state or undefined if not found
+     */
+    getState(globalElementId: string, toolId: string): any | undefined;
+    /**
+     * Gets all tool states for a specific element.
+     *
+     * @param globalElementId Composite key identifying the element
+     * @returns Object with tool states keyed by toolId
+     */
+    getElementState(globalElementId: string): Record<string, any>;
+    /**
+     * Gets all tool states for all elements.
+     * Used for persistence and debugging.
+     *
+     * @returns Nested object: { globalElementId: { toolId: state } }
+     */
+    getAllState(): Record<string, Record<string, any>>;
+    /**
+     * Subscribes to state changes.
+     * Callback is invoked whenever any element's tool state changes.
+     *
+     * @param callback Function to call on state changes
+     * @returns Unsubscribe function
+     */
+    subscribe(callback: (state: Map<string, Map<string, any>>) => void): () => void;
+    private _notifyListeners;
+    /**
+     * Sets a callback to be invoked on state changes for persistence integration.
+     * Used by demo/app layer to persist tool state to localStorage or server.
+     *
+     * @param callback Function to call with serialized state on changes
+     */
+    setOnStateChange(callback: (state: Record<string, Record<string, any>>) => void): void;
+    private _notifyStateChange;
+    /**
+     * Loads tool state from serialized format.
+     * Used to restore state from localStorage or server.
+     *
+     * @param state Serialized state object
+     */
+    loadState(state: Record<string, Record<string, any>>): void;
+    /**
+     * Clears all tool state for a specific element.
+     *
+     * @param globalElementId Composite key identifying the element
+     */
+    clearElement(globalElementId: string): void;
+    /**
+     * Clears state for a specific tool across all elements.
+     * Useful when disabling a tool globally.
+     *
+     * @param toolId Tool identifier
+     */
+    clearTool(toolId: string): void;
+    /**
+     * Clears all tool state for a specific section.
+     * Useful when unmounting/disposing a section.
+     *
+     * @param assessmentId Assessment identifier
+     * @param sectionId Section identifier
+     */
+    clearSection(assessmentId: string, sectionId: string): void;
+    /**
+     * Clears all tool state.
+     * Useful when switching between assessments or demos.
+     */
+    clearAll(): void;
+}
+//# sourceMappingURL=ElementToolStateStore.d.ts.map

package/dist/services/ElementToolStateStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ElementToolStateStore.d.ts","sourceRoot":"","sources":["../../src/services/ElementToolStateStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,mBAAmB;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,qBAAqB;IACjC,OAAO,CAAC,aAAa,CAAuC;IAC5D,OAAO,CAAC,SAAS,CAA6D;IAC9E,OAAO,CAAC,aAAa,CAEN;IAEf;;;;;;;OAOG;IACH,kBAAkB,CACjB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GACf,MAAM;IAIT;;;;;;OAMG;IACH,oBAAoB,CAAC,eAAe,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI;IAWzE;;;;;;;OAOG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI;IAWnE;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,GAAG,GAAG,SAAS;IAIlE;;;;;OAKG;IACH,eAAe,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAM7D;;;;;OAKG;IACH,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAQlD;;;;;;OAMG;IACH,SAAS,CACR,QAAQ,EAAE,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,KAAK,IAAI,GACtD,MAAM,IAAI;IAKb,OAAO,CAAC,gBAAgB;IAMxB;;;;;OAKG;IACH,gBAAgB,CACf,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,KAAK,IAAI,GAC5D,IAAI;IAIP,OAAO,CAAC,kBAAkB;IAM1B;;;;;OAKG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,IAAI;IAS3D;;;;OAIG;IACH,YAAY,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI;IAM3C;;;;;OAKG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAQ/B;;;;;;OAMG;IACH,YAAY,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAe3D;;;OAGG;IACH,QAAQ,IAAI,IAAI;CAKhB"}

package/dist/services/ElementToolStateStore.js

@@ -0,0 +1,200 @@
+/**
+ * ElementToolStateStore - Manages element-level ephemeral tool state
+ *
+ * Provides centralized storage for UI tool state (answer eliminations, flags, etc.)
+ * that should NOT be sent to the server for scoring. Each element is uniquely identified
+ * across the entire assessment using composite keys.
+ *
+ * Key features:
+ * - Element-level granularity (not item-level)
+ * - Composite keys for global uniqueness: `assessmentId:sectionId:itemId:elementId`
+ * - Cross-section state persistence
+ * - Reactive subscriptions
+ * - Optional persistence callback integration
+ * - Generic solution for any tool
+ */
+export class ElementToolStateStore {
+    elementStates = new Map();
+    listeners = new Set();
+    onStateChange = null;
+    /**
+     * Generates a globally unique element ID by combining assessment, section, item, and element IDs.
+     * Format: `${assessmentId}:${sectionId}:${itemId}:${elementId}`
+     *
+     * @example
+     * getGlobalElementId('demo-assessment', 'section-1', 'q1', 'mc1')
+     * // Returns: "demo-assessment:section-1:q1:mc1"
+     */
+    getGlobalElementId(assessmentId, sectionId, itemId, elementId) {
+        return `${assessmentId}:${sectionId}:${itemId}:${elementId}`;
+    }
+    /**
+     * Parses a global element ID into its component parts.
+     *
+     * @example
+     * parseGlobalElementId('demo-assessment:section-1:q1:mc1')
+     * // Returns: { assessmentId: 'demo-assessment', sectionId: 'section-1', itemId: 'q1', elementId: 'mc1' }
+     */
+    parseGlobalElementId(globalElementId) {
+        const parts = globalElementId.split(":");
+        if (parts.length !== 4)
+            return null;
+        return {
+            assessmentId: parts[0],
+            sectionId: parts[1],
+            itemId: parts[2],
+            elementId: parts[3],
+        };
+    }
+    /**
+     * Sets tool state for a specific element.
+     * Notifies all subscribers and triggers persistence callback.
+     *
+     * @param globalElementId Composite key identifying the element
+     * @param toolId Tool identifier (e.g., 'answerEliminator', 'flagging')
+     * @param state Tool-specific state object
+     */
+    setState(globalElementId, toolId, state) {
+        let elementState = this.elementStates.get(globalElementId);
+        if (!elementState) {
+            elementState = new Map();
+            this.elementStates.set(globalElementId, elementState);
+        }
+        elementState.set(toolId, state);
+        this._notifyListeners();
+        this._notifyStateChange();
+    }
+    /**
+     * Gets tool state for a specific element.
+     *
+     * @param globalElementId Composite key identifying the element
+     * @param toolId Tool identifier
+     * @returns Tool state or undefined if not found
+     */
+    getState(globalElementId, toolId) {
+        return this.elementStates.get(globalElementId)?.get(toolId);
+    }
+    /**
+     * Gets all tool states for a specific element.
+     *
+     * @param globalElementId Composite key identifying the element
+     * @returns Object with tool states keyed by toolId
+     */
+    getElementState(globalElementId) {
+        const elementState = this.elementStates.get(globalElementId);
+        if (!elementState)
+            return {};
+        return Object.fromEntries(elementState.entries());
+    }
+    /**
+     * Gets all tool states for all elements.
+     * Used for persistence and debugging.
+     *
+     * @returns Nested object: { globalElementId: { toolId: state } }
+     */
+    getAllState() {
+        const result = {};
+        for (const [globalElementId, toolStates] of this.elementStates.entries()) {
+            result[globalElementId] = Object.fromEntries(toolStates.entries());
+        }
+        return result;
+    }
+    /**
+     * Subscribes to state changes.
+     * Callback is invoked whenever any element's tool state changes.
+     *
+     * @param callback Function to call on state changes
+     * @returns Unsubscribe function
+     */
+    subscribe(callback) {
+        this.listeners.add(callback);
+        return () => this.listeners.delete(callback);
+    }
+    _notifyListeners() {
+        for (const listener of this.listeners) {
+            listener(this.elementStates);
+        }
+    }
+    /**
+     * Sets a callback to be invoked on state changes for persistence integration.
+     * Used by demo/app layer to persist tool state to localStorage or server.
+     *
+     * @param callback Function to call with serialized state on changes
+     */
+    setOnStateChange(callback) {
+        this.onStateChange = callback;
+    }
+    _notifyStateChange() {
+        if (this.onStateChange) {
+            this.onStateChange(this.getAllState());
+        }
+    }
+    /**
+     * Loads tool state from serialized format.
+     * Used to restore state from localStorage or server.
+     *
+     * @param state Serialized state object
+     */
+    loadState(state) {
+        this.elementStates.clear();
+        for (const [globalElementId, toolStates] of Object.entries(state)) {
+            const elementState = new Map(Object.entries(toolStates));
+            this.elementStates.set(globalElementId, elementState);
+        }
+        this._notifyListeners();
+    }
+    /**
+     * Clears all tool state for a specific element.
+     *
+     * @param globalElementId Composite key identifying the element
+     */
+    clearElement(globalElementId) {
+        this.elementStates.delete(globalElementId);
+        this._notifyListeners();
+        this._notifyStateChange();
+    }
+    /**
+     * Clears state for a specific tool across all elements.
+     * Useful when disabling a tool globally.
+     *
+     * @param toolId Tool identifier
+     */
+    clearTool(toolId) {
+        for (const elementState of this.elementStates.values()) {
+            elementState.delete(toolId);
+        }
+        this._notifyListeners();
+        this._notifyStateChange();
+    }
+    /**
+     * Clears all tool state for a specific section.
+     * Useful when unmounting/disposing a section.
+     *
+     * @param assessmentId Assessment identifier
+     * @param sectionId Section identifier
+     */
+    clearSection(assessmentId, sectionId) {
+        const prefix = `${assessmentId}:${sectionId}:`;
+        const keysToDelete = [];
+        for (const key of this.elementStates.keys()) {
+            if (key.startsWith(prefix)) {
+                keysToDelete.push(key);
+            }
+        }
+        for (const key of keysToDelete) {
+            this.elementStates.delete(key);
+        }
+        this._notifyListeners();
+        this._notifyStateChange();
+    }
+    /**
+     * Clears all tool state.
+     * Useful when switching between assessments or demos.
+     */
+    clearAll() {
+        this.elementStates.clear();
+        this._notifyListeners();
+        this._notifyStateChange();
+    }
+}
+//# sourceMappingURL=ElementToolStateStore.js.map

package/dist/services/ElementToolStateStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ElementToolStateStore.js","sourceRoot":"","sources":["../../src/services/ElementToolStateStore.ts"],"names":[],"mappings":"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"}