@pie-players/pie-assessment-toolkit 0.2.0

package/dist/services/PNPToolResolver.d.ts

@@ -0,0 +1,127 @@
+/**
+ * PNP Tool Resolver
+ *
+ * Resolves tool availability from QTI 3.0 Personal Needs Profile (PNP) and
+ * assessment settings. Implements precedence hierarchy for tool configuration.
+ *
+ * Precedence (highest to lowest):
+ * 1. District block (absolute veto)
+ * 2. Test administration override
+ * 3. Item restriction (per-item block)
+ * 4. Item requirement (forces enable)
+ * 5. District requirement
+ * 6. PNP supports (student needs)
+ *
+ * Part of PIE Assessment Toolkit.
+ */
+import type { AssessmentEntity, AssessmentItemRef } from "@pie-players/pie-players-shared/types";
+/**
+ * Resolved tool configuration with source tracking
+ */
+export interface ResolvedToolConfig {
+    id: string;
+    enabled: boolean;
+    required?: boolean;
+    alwaysAvailable?: boolean;
+    settings?: any;
+    source: "district" | "item" | "pnp" | "settings";
+}
+/**
+ * Resolves tool availability from QTI 3.0 assessment structure
+ */
+export declare class PNPToolResolver {
+    /**
+     * Resolve all tools from QTI 3.0 assessment + optional item context
+     *
+     * @param assessment QTI 3.0 assessment with personalNeedsProfile
+     * @param currentItemRef Current item for item-specific requirements (optional)
+     * @returns Array of resolved tool configurations
+     *
+     * @example
+     * const resolver = new PNPToolResolver();
+     * const tools = resolver.resolveTools(assessment, itemRef);
+     * tools.forEach(tool => {
+     *   console.log(`${tool.id}: ${tool.enabled ? 'enabled' : 'disabled'}`);
+     * });
+     */
+    resolveTools(assessment: AssessmentEntity, currentItemRef?: AssessmentItemRef): ResolvedToolConfig[];
+    /**
+     * Resolve availability of a single PNP support
+     *
+     * Applies precedence rules to determine if support should be enabled.
+     *
+     * @param supportId PNP support identifier
+     * @param context Resolution context with all configuration sources
+     * @returns Resolved config or null if blocked/disabled
+     */
+    private resolveSupport;
+    /**
+     * Build resolved tool configuration
+     *
+     * Maps PNP support ID to PIE tool ID and merges tool-specific settings.
+     *
+     * @param supportId PNP support identifier
+     * @param context Resolution context for settings lookup
+     * @param flags Availability flags (required, alwaysAvailable, source)
+     * @returns Complete resolved tool configuration
+     */
+    private buildToolConfig;
+    /**
+     * Check if a specific tool is enabled
+     *
+     * @param toolId PIE tool identifier (e.g., 'pie-tool-calculator')
+     * @param assessment Assessment with PNP
+     * @param itemRef Optional item context
+     * @returns true if tool is enabled
+     */
+    isToolEnabled(toolId: string, assessment: AssessmentEntity, itemRef?: AssessmentItemRef): boolean;
+    /**
+     * Check if a tool is required (cannot be disabled)
+     *
+     * @param toolId PIE tool identifier
+     * @param assessment Assessment with PNP
+     * @param itemRef Optional item context
+     * @returns true if tool is required or always available
+     */
+    isToolRequired(toolId: string, assessment: AssessmentEntity, itemRef?: AssessmentItemRef): boolean;
+    /**
+     * Get list of auto-activate tools from PNP
+     *
+     * Returns PIE tool IDs that should be automatically opened/activated
+     * when the assessment starts, based on PNP activateAtInit field.
+     *
+     * @param assessment Assessment with PNP
+     * @returns Array of PIE tool IDs to auto-activate
+     *
+     * @example
+     * const autoActivate = resolver.getAutoActivateTools(assessment);
+     * // Returns: ['pie-tool-text-to-speech', 'pie-tool-line-reader']
+     */
+    getAutoActivateTools(assessment: AssessmentEntity): string[];
+    /**
+     * Get all enabled tools
+     *
+     * @param assessment Assessment with PNP
+     * @param itemRef Optional item context
+     * @returns Array of PIE tool IDs that are enabled
+     */
+    getEnabledTools(assessment: AssessmentEntity, itemRef?: AssessmentItemRef): string[];
+    /**
+     * Get all required tools
+     *
+     * @param assessment Assessment with PNP
+     * @param itemRef Optional item context
+     * @returns Array of PIE tool IDs that are required
+     */
+    getRequiredTools(assessment: AssessmentEntity, itemRef?: AssessmentItemRef): string[];
+    /**
+     * Get tool configuration settings
+     *
+     * @param toolId PIE tool identifier
+     * @param assessment Assessment with PNP
+     * @param itemRef Optional item context
+     * @returns Tool-specific settings or null if not found
+     */
+    getToolSettings(toolId: string, assessment: AssessmentEntity, itemRef?: AssessmentItemRef): any | null;
+}
+//# sourceMappingURL=PNPToolResolver.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PNPToolResolver.d.ts","sourceRoot":"","sources":["../../src/services/PNPToolResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EACX,gBAAgB,EAChB,iBAAiB,EAIjB,MAAM,uCAAuC,CAAC;AAG/C;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,GAAG,CAAC;IACf,MAAM,EAAE,UAAU,GAAG,MAAM,GAAG,KAAK,GAAG,UAAU,CAAC;CACjD;AAaD;;GAEG;AACH,qBAAa,eAAe;IAC3B;;;;;;;;;;;;;OAaG;IACH,YAAY,CACX,UAAU,EAAE,gBAAgB,EAC5B,cAAc,CAAC,EAAE,iBAAiB,GAChC,kBAAkB,EAAE;IAgCvB;;;;;;;;OAQG;IACH,OAAO,CAAC,cAAc;IAsDtB;;;;;;;;;OASG;IACH,OAAO,CAAC,eAAe;IA2BvB;;;;;;;OAOG;IACH,aAAa,CACZ,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,gBAAgB,EAC5B,OAAO,CAAC,EAAE,iBAAiB,GACzB,OAAO;IAKV;;;;;;;OAOG;IACH,cAAc,CACb,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,gBAAgB,EAC5B,OAAO,CAAC,EAAE,iBAAiB,GACzB,OAAO;IAMV;;;;;;;;;;;;OAYG;IACH,oBAAoB,CAAC,UAAU,EAAE,gBAAgB,GAAG,MAAM,EAAE;IAS5D;;;;;;OAMG;IACH,eAAe,CACd,UAAU,EAAE,gBAAgB,EAC5B,OAAO,CAAC,EAAE,iBAAiB,GACzB,MAAM,EAAE;IAKX;;;;;;OAMG;IACH,gBAAgB,CACf,UAAU,EAAE,gBAAgB,EAC5B,OAAO,CAAC,EAAE,iBAAiB,GACzB,MAAM,EAAE;IAOX;;;;;;;OAOG;IACH,eAAe,CACd,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,gBAAgB,EAC5B,OAAO,CAAC,EAAE,iBAAiB,GACzB,GAAG,GAAG,IAAI;CAKb"}

package/dist/services/PNPToolResolver.js

@@ -0,0 +1,222 @@
+/**
+ * PNP Tool Resolver
+ *
+ * Resolves tool availability from QTI 3.0 Personal Needs Profile (PNP) and
+ * assessment settings. Implements precedence hierarchy for tool configuration.
+ *
+ * Precedence (highest to lowest):
+ * 1. District block (absolute veto)
+ * 2. Test administration override
+ * 3. Item restriction (per-item block)
+ * 4. Item requirement (forces enable)
+ * 5. District requirement
+ * 6. PNP supports (student needs)
+ *
+ * Part of PIE Assessment Toolkit.
+ */
+import { mapPNPSupportToToolId } from "./PNPMapper";
+/**
+ * Resolves tool availability from QTI 3.0 assessment structure
+ */
+export class PNPToolResolver {
+    /**
+     * Resolve all tools from QTI 3.0 assessment + optional item context
+     *
+     * @param assessment QTI 3.0 assessment with personalNeedsProfile
+     * @param currentItemRef Current item for item-specific requirements (optional)
+     * @returns Array of resolved tool configurations
+     *
+     * @example
+     * const resolver = new PNPToolResolver();
+     * const tools = resolver.resolveTools(assessment, itemRef);
+     * tools.forEach(tool => {
+     *   console.log(`${tool.id}: ${tool.enabled ? 'enabled' : 'disabled'}`);
+     * });
+     */
+    resolveTools(assessment, currentItemRef) {
+        const pnp = assessment.personalNeedsProfile;
+        const settings = assessment.settings;
+        const itemSettings = currentItemRef?.settings;
+        // Collect all PNP support IDs mentioned anywhere
+        const allSupports = new Set();
+        pnp?.supports?.forEach((s) => allSupports.add(s));
+        settings?.districtPolicy?.blockedTools?.forEach((s) => allSupports.add(s));
+        settings?.districtPolicy?.requiredTools?.forEach((s) => allSupports.add(s));
+        itemSettings?.requiredTools?.forEach((s) => allSupports.add(s));
+        itemSettings?.restrictedTools?.forEach((s) => allSupports.add(s));
+        const resolved = [];
+        for (const supportId of allSupports) {
+            const config = this.resolveSupport(supportId, {
+                pnp,
+                districtPolicy: settings?.districtPolicy,
+                testAdmin: settings?.testAdministration,
+                itemSettings,
+                toolConfigs: settings?.toolConfigs,
+            });
+            if (config) {
+                resolved.push(config);
+            }
+        }
+        return resolved;
+    }
+    /**
+     * Resolve availability of a single PNP support
+     *
+     * Applies precedence rules to determine if support should be enabled.
+     *
+     * @param supportId PNP support identifier
+     * @param context Resolution context with all configuration sources
+     * @returns Resolved config or null if blocked/disabled
+     */
+    resolveSupport(supportId, context) {
+        // Precedence (highest to lowest):
+        // 1. District block (absolute veto)
+        if (context.districtPolicy?.blockedTools?.includes(supportId)) {
+            return null; // Blocked
+        }
+        // 2. Test administration override
+        if (context.testAdmin?.toolOverrides?.[supportId] === false) {
+            return null; // Blocked
+        }
+        // 3. Item restriction
+        if (context.itemSettings?.restrictedTools?.includes(supportId)) {
+            return null; // Blocked for this item
+        }
+        // 4. Item requirement (forces enable)
+        if (context.itemSettings?.requiredTools?.includes(supportId)) {
+            return this.buildToolConfig(supportId, context, {
+                required: true,
+                source: "item",
+            });
+        }
+        // 5. District requirement
+        if (context.districtPolicy?.requiredTools?.includes(supportId)) {
+            return this.buildToolConfig(supportId, context, {
+                required: true,
+                source: "district",
+            });
+        }
+        // 6. PNP supports (student needs)
+        if (context.pnp?.supports?.includes(supportId)) {
+            // Check if prohibited
+            const isProhibited = context.pnp.prohibitedSupports?.includes(supportId);
+            if (!isProhibited) {
+                return this.buildToolConfig(supportId, context, {
+                    alwaysAvailable: true,
+                    source: "pnp",
+                });
+            }
+        }
+        // Not enabled
+        return null;
+    }
+    /**
+     * Build resolved tool configuration
+     *
+     * Maps PNP support ID to PIE tool ID and merges tool-specific settings.
+     *
+     * @param supportId PNP support identifier
+     * @param context Resolution context for settings lookup
+     * @param flags Availability flags (required, alwaysAvailable, source)
+     * @returns Complete resolved tool configuration
+     */
+    buildToolConfig(supportId, context, flags) {
+        // Map PNP support ID to PIE tool ID
+        const pieToolId = mapPNPSupportToToolId(supportId) || supportId;
+        // Get tool-specific config from settings (item takes precedence)
+        const toolConfig = context.itemSettings?.toolParameters?.[supportId] ||
+            context.toolConfigs?.[supportId];
+        return {
+            id: pieToolId,
+            enabled: true,
+            required: flags.required || false,
+            alwaysAvailable: flags.alwaysAvailable || false,
+            settings: toolConfig,
+            source: flags.source,
+        };
+    }
+    /**
+     * Check if a specific tool is enabled
+     *
+     * @param toolId PIE tool identifier (e.g., 'pie-tool-calculator')
+     * @param assessment Assessment with PNP
+     * @param itemRef Optional item context
+     * @returns true if tool is enabled
+     */
+    isToolEnabled(toolId, assessment, itemRef) {
+        const resolved = this.resolveTools(assessment, itemRef);
+        return resolved.some((t) => t.id === toolId && t.enabled);
+    }
+    /**
+     * Check if a tool is required (cannot be disabled)
+     *
+     * @param toolId PIE tool identifier
+     * @param assessment Assessment with PNP
+     * @param itemRef Optional item context
+     * @returns true if tool is required or always available
+     */
+    isToolRequired(toolId, assessment, itemRef) {
+        const resolved = this.resolveTools(assessment, itemRef);
+        const tool = resolved.find((t) => t.id === toolId);
+        return tool?.required || tool?.alwaysAvailable || false;
+    }
+    /**
+     * Get list of auto-activate tools from PNP
+     *
+     * Returns PIE tool IDs that should be automatically opened/activated
+     * when the assessment starts, based on PNP activateAtInit field.
+     *
+     * @param assessment Assessment with PNP
+     * @returns Array of PIE tool IDs to auto-activate
+     *
+     * @example
+     * const autoActivate = resolver.getAutoActivateTools(assessment);
+     * // Returns: ['pie-tool-text-to-speech', 'pie-tool-line-reader']
+     */
+    getAutoActivateTools(assessment) {
+        const pnp = assessment.personalNeedsProfile;
+        if (!pnp?.activateAtInit)
+            return [];
+        return pnp.activateAtInit
+            .map((supportId) => mapPNPSupportToToolId(supportId))
+            .filter(Boolean);
+    }
+    /**
+     * Get all enabled tools
+     *
+     * @param assessment Assessment with PNP
+     * @param itemRef Optional item context
+     * @returns Array of PIE tool IDs that are enabled
+     */
+    getEnabledTools(assessment, itemRef) {
+        const resolved = this.resolveTools(assessment, itemRef);
+        return resolved.filter((t) => t.enabled).map((t) => t.id);
+    }
+    /**
+     * Get all required tools
+     *
+     * @param assessment Assessment with PNP
+     * @param itemRef Optional item context
+     * @returns Array of PIE tool IDs that are required
+     */
+    getRequiredTools(assessment, itemRef) {
+        const resolved = this.resolveTools(assessment, itemRef);
+        return resolved
+            .filter((t) => t.required || t.alwaysAvailable)
+            .map((t) => t.id);
+    }
+    /**
+     * Get tool configuration settings
+     *
+     * @param toolId PIE tool identifier
+     * @param assessment Assessment with PNP
+     * @param itemRef Optional item context
+     * @returns Tool-specific settings or null if not found
+     */
+    getToolSettings(toolId, assessment, itemRef) {
+        const resolved = this.resolveTools(assessment, itemRef);
+        const tool = resolved.find((t) => t.id === toolId);
+        return tool?.settings || null;
+    }
+}
+//# sourceMappingURL=PNPToolResolver.js.map

package/dist/services/PNPToolResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PNPToolResolver.js","sourceRoot":"","sources":["../../src/services/PNPToolResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AASH,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAyBpD;;GAEG;AACH,MAAM,OAAO,eAAe;IAC3B;;;;;;;;;;;;;OAaG;IACH,YAAY,CACX,UAA4B,EAC5B,cAAkC;QAElC,MAAM,GAAG,GAAG,UAAU,CAAC,oBAAoB,CAAC;QAC5C,MAAM,QAAQ,GAAG,UAAU,CAAC,QAA8B,CAAC;QAC3D,MAAM,YAAY,GAAG,cAAc,EAAE,QAAwB,CAAC;QAE9D,iDAAiD;QACjD,MAAM,WAAW,GAAG,IAAI,GAAG,EAAU,CAAC;QACtC,GAAG,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAClD,QAAQ,EAAE,cAAc,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3E,QAAQ,EAAE,cAAc,EAAE,aAAa,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5E,YAAY,EAAE,aAAa,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAChE,YAAY,EAAE,eAAe,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAElE,MAAM,QAAQ,GAAyB,EAAE,CAAC;QAE1C,KAAK,MAAM,SAAS,IAAI,WAAW,EAAE,CAAC;YACrC,MAAM,MAAM,GAAG,IAAI,CAAC,cAAc,CAAC,SAAS,EAAE;gBAC7C,GAAG;gBACH,cAAc,EAAE,QAAQ,EAAE,cAAc;gBACxC,SAAS,EAAE,QAAQ,EAAE,kBAAkB;gBACvC,YAAY;gBACZ,WAAW,EAAE,QAAQ,EAAE,WAAW;aAClC,CAAC,CAAC;YAEH,IAAI,MAAM,EAAE,CAAC;gBACZ,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACvB,CAAC;QACF,CAAC;QAED,OAAO,QAAQ,CAAC;IACjB,CAAC;IAED;;;;;;;;OAQG;IACK,cAAc,CACrB,SAAiB,EACjB,OAA0B;QAE1B,kCAAkC;QAElC,oCAAoC;QACpC,IAAI,OAAO,CAAC,cAAc,EAAE,YAAY,EAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YAC/D,OAAO,IAAI,CAAC,CAAC,UAAU;QACxB,CAAC;QAED,kCAAkC;QAClC,IAAI,OAAO,CAAC,SAAS,EAAE,aAAa,EAAE,CAAC,SAAS,CAAC,KAAK,KAAK,EAAE,CAAC;YAC7D,OAAO,IAAI,CAAC,CAAC,UAAU;QACxB,CAAC;QAED,sBAAsB;QACtB,IAAI,OAAO,CAAC,YAAY,EAAE,eAAe,EAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YAChE,OAAO,IAAI,CAAC,CAAC,wBAAwB;QACtC,CAAC;QAED,sCAAsC;QACtC,IAAI,OAAO,CAAC,YAAY,EAAE,aAAa,EAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YAC9D,OAAO,IAAI,CAAC,eAAe,CAAC,SAAS,EAAE,OAAO,EAAE;gBAC/C,QAAQ,EAAE,IAAI;gBACd,MAAM,EAAE,MAAM;aACd,CAAC,CAAC;QACJ,CAAC;QAED,0BAA0B;QAC1B,IAAI,OAAO,CAAC,cAAc,EAAE,aAAa,EAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YAChE,OAAO,IAAI,CAAC,eAAe,CAAC,SAAS,EAAE,OAAO,EAAE;gBAC/C,QAAQ,EAAE,IAAI;gBACd,MAAM,EAAE,UAAU;aAClB,CAAC,CAAC;QACJ,CAAC;QAED,kCAAkC;QAClC,IAAI,OAAO,CAAC,GAAG,EAAE,QAAQ,EAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YAChD,sBAAsB;YACtB,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;YAEzE,IAAI,CAAC,YAAY,EAAE,CAAC;gBACnB,OAAO,IAAI,CAAC,eAAe,CAAC,SAAS,EAAE,OAAO,EAAE;oBAC/C,eAAe,EAAE,IAAI;oBACrB,MAAM,EAAE,KAAK;iBACb,CAAC,CAAC;YACJ,CAAC;QACF,CAAC;QAED,cAAc;QACd,OAAO,IAAI,CAAC;IACb,CAAC;IAED;;;;;;;;;OASG;IACK,eAAe,CACtB,SAAiB,EACjB,OAA0B,EAC1B,KAIC;QAED,oCAAoC;QACpC,MAAM,SAAS,GAAG,qBAAqB,CAAC,SAAS,CAAC,IAAI,SAAS,CAAC;QAEhE,iEAAiE;QACjE,MAAM,UAAU,GACf,OAAO,CAAC,YAAY,EAAE,cAAc,EAAE,CAAC,SAAS,CAAC;YACjD,OAAO,CAAC,WAAW,EAAE,CAAC,SAAS,CAAC,CAAC;QAElC,OAAO;YACN,EAAE,EAAE,SAAS;YACb,OAAO,EAAE,IAAI;YACb,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,KAAK;YACjC,eAAe,EAAE,KAAK,CAAC,eAAe,IAAI,KAAK;YAC/C,QAAQ,EAAE,UAAU;YACpB,MAAM,EAAE,KAAK,CAAC,MAAa;SAC3B,CAAC;IACH,CAAC;IAED;;;;;;;OAOG;IACH,aAAa,CACZ,MAAc,EACd,UAA4B,EAC5B,OAA2B;QAE3B,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QACxD,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC;IAC3D,CAAC;IAED;;;;;;;OAOG;IACH,cAAc,CACb,MAAc,EACd,UAA4B,EAC5B,OAA2B;QAE3B,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QACxD,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,CAAC,CAAC;QACnD,OAAO,IAAI,EAAE,QAAQ,IAAI,IAAI,EAAE,eAAe,IAAI,KAAK,CAAC;IACzD,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,oBAAoB,CAAC,UAA4B;QAChD,MAAM,GAAG,GAAG,UAAU,CAAC,oBAAoB,CAAC;QAC5C,IAAI,CAAC,GAAG,EAAE,cAAc;YAAE,OAAO,EAAE,CAAC;QAEpC,OAAO,GAAG,CAAC,cAAc;aACvB,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,qBAAqB,CAAC,SAAS,CAAC,CAAC;aACpD,MAAM,CAAC,OAAO,CAAa,CAAC;IAC/B,CAAC;IAED;;;;;;OAMG;IACH,eAAe,CACd,UAA4B,EAC5B,OAA2B;QAE3B,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QACxD,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC3D,CAAC;IAED;;;;;;OAMG;IACH,gBAAgB,CACf,UAA4B,EAC5B,OAA2B;QAE3B,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QACxD,OAAO,QAAQ;aACb,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,eAAe,CAAC;aAC9C,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACpB,CAAC;IAED;;;;;;;OAOG;IACH,eAAe,CACd,MAAc,EACd,UAA4B,EAC5B,OAA2B;QAE3B,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QACxD,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,CAAC,CAAC;QACnD,OAAO,IAAI,EAAE,QAAQ,IAAI,IAAI,CAAC;IAC/B,CAAC;CACD"}

package/dist/services/SSMLExtractor.d.ts

@@ -0,0 +1,61 @@
+/**
+ * SSMLExtractor
+ *
+ * Service for extracting embedded SSML from PIE item content and converting
+ * it into QTI 3.0 accessibility catalogs.
+ *
+ * Authors can embed <speak> SSML tags directly in content for convenience.
+ * The extractor automatically:
+ * 1. Parses markup and finds all <speak> elements
+ * 2. Extracts SSML content with language metadata
+ * 3. Generates accessibility catalogs with unique IDs
+ * 4. Cleans visual markup (removes SSML, adds data-catalog-id)
+ *
+ * This enables proper pronunciation, emphasis, and pacing for TTS without
+ * requiring authors to maintain separate catalog files.
+ *
+ * Part of PIE Assessment Toolkit.
+ */
+import type { AccessibilityCatalog, ConfigEntity } from "@pie-players/pie-players-shared/types";
+/**
+ * Result from extracting SSML from entire item config
+ */
+export interface ExtractionResult {
+    catalogs: AccessibilityCatalog[];
+    cleanedConfig: ConfigEntity;
+}
+/**
+ * SSMLExtractor Service
+ *
+ * Extracts embedded SSML from PIE content and generates accessibility catalogs.
+ */
+export declare class SSMLExtractor {
+    private catalogCounter;
+    /**
+     * Extract SSML from entire item config (markup + models)
+     *
+     * @param config Item configuration with potential embedded SSML
+     * @returns Extracted catalogs and cleaned config
+     */
+    extractFromItemConfig(config: ConfigEntity): ExtractionResult;
+    /**
+     * Extract SSML from markup string
+     *
+     * @param markup HTML markup potentially containing <speak> elements
+     * @param idPrefix Prefix for generating catalog IDs
+     * @returns Extracted catalogs and cleaned markup
+     */
+    private extractFromMarkup;
+    /**
+     * Generate unique catalog ID
+     *
+     * @param prefix Context prefix (e.g., 'prompt-q1', 'choice-q1-a')
+     * @returns Unique catalog ID (e.g., 'auto-prompt-q1-0')
+     */
+    private generateCatalogId;
+    /**
+     * Reset counter (useful for testing or new extraction contexts)
+     */
+    reset(): void;
+}
+//# sourceMappingURL=SSMLExtractor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SSMLExtractor.d.ts","sourceRoot":"","sources":["../../src/services/SSMLExtractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EACX,oBAAoB,EACpB,YAAY,EAEZ,MAAM,uCAAuC,CAAC;AAU/C;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,QAAQ,EAAE,oBAAoB,EAAE,CAAC;IACjC,aAAa,EAAE,YAAY,CAAC;CAC5B;AAED;;;;GAIG;AACH,qBAAa,aAAa;IACzB,OAAO,CAAC,cAAc,CAAK;IAE3B;;;;;OAKG;IACH,qBAAqB,CAAC,MAAM,EAAE,YAAY,GAAG,gBAAgB;IA6D7D;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAmGzB;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IAMzB;;OAEG;IACH,KAAK,IAAI,IAAI;CAGb"}

package/dist/services/SSMLExtractor.js

@@ -0,0 +1,181 @@
+/**
+ * SSMLExtractor
+ *
+ * Service for extracting embedded SSML from PIE item content and converting
+ * it into QTI 3.0 accessibility catalogs.
+ *
+ * Authors can embed <speak> SSML tags directly in content for convenience.
+ * The extractor automatically:
+ * 1. Parses markup and finds all <speak> elements
+ * 2. Extracts SSML content with language metadata
+ * 3. Generates accessibility catalogs with unique IDs
+ * 4. Cleans visual markup (removes SSML, adds data-catalog-id)
+ *
+ * This enables proper pronunciation, emphasis, and pacing for TTS without
+ * requiring authors to maintain separate catalog files.
+ *
+ * Part of PIE Assessment Toolkit.
+ */
+/**
+ * SSMLExtractor Service
+ *
+ * Extracts embedded SSML from PIE content and generates accessibility catalogs.
+ */
+export class SSMLExtractor {
+    catalogCounter = 0;
+    /**
+     * Extract SSML from entire item config (markup + models)
+     *
+     * @param config Item configuration with potential embedded SSML
+     * @returns Extracted catalogs and cleaned config
+     */
+    extractFromItemConfig(config) {
+        const allCatalogs = [];
+        // Deep clone config to avoid mutating original
+        const cleanedConfig = {
+            ...config,
+            models: config.models ? [...config.models] : [],
+        };
+        // 1. Extract from top-level markup (passages)
+        if (config.markup) {
+            const markupResult = this.extractFromMarkup(config.markup, "markup");
+            allCatalogs.push(...markupResult.catalogs);
+            cleanedConfig.markup = markupResult.cleanedMarkup;
+        }
+        // 2. Extract from models (prompts, choices, etc.)
+        if (config.models && config.models.length > 0) {
+            cleanedConfig.models = config.models.map((model) => {
+                const cleanedModel = { ...model };
+                const modelCatalogs = [];
+                // Extract from prompt
+                if (model.prompt && typeof model.prompt === "string") {
+                    const promptResult = this.extractFromMarkup(model.prompt, `prompt-${model.id}`);
+                    modelCatalogs.push(...promptResult.catalogs);
+                    cleanedModel.prompt = promptResult.cleanedMarkup;
+                }
+                // Extract from choices
+                if (model.choices && Array.isArray(model.choices)) {
+                    cleanedModel.choices = model.choices.map((choice) => {
+                        if (choice.label && typeof choice.label === "string") {
+                            const choiceResult = this.extractFromMarkup(choice.label, `choice-${model.id}-${choice.value}`);
+                            modelCatalogs.push(...choiceResult.catalogs);
+                            return {
+                                ...choice,
+                                label: choiceResult.cleanedMarkup,
+                            };
+                        }
+                        return choice;
+                    });
+                }
+                allCatalogs.push(...modelCatalogs);
+                return cleanedModel;
+            });
+        }
+        return {
+            catalogs: allCatalogs,
+            cleanedConfig,
+        };
+    }
+    /**
+     * Extract SSML from markup string
+     *
+     * @param markup HTML markup potentially containing <speak> elements
+     * @param idPrefix Prefix for generating catalog IDs
+     * @returns Extracted catalogs and cleaned markup
+     */
+    extractFromMarkup(markup, idPrefix) {
+        if (!markup || markup.trim() === "") {
+            return { catalogs: [], cleanedMarkup: markup };
+        }
+        // Check if running in browser environment
+        if (typeof window === "undefined" || typeof DOMParser === "undefined") {
+            console.warn("[SSMLExtractor] DOMParser not available (SSR?), skipping extraction");
+            return { catalogs: [], cleanedMarkup: markup };
+        }
+        const catalogs = [];
+        try {
+            const parser = new DOMParser();
+            const doc = parser.parseFromString(markup, "text/html");
+            // Find all <speak> elements
+            const speakElements = Array.from(doc.querySelectorAll("speak"));
+            if (speakElements.length === 0) {
+                // No SSML found, return original markup
+                return { catalogs: [], cleanedMarkup: markup };
+            }
+            // Process each <speak> element
+            for (const speakEl of speakElements) {
+                try {
+                    // Generate unique catalog ID
+                    const catalogId = this.generateCatalogId(idPrefix);
+                    // Extract SSML content
+                    const ssmlContent = speakEl.outerHTML;
+                    // Extract language (check both xml:lang and lang attributes)
+                    const language = speakEl.getAttribute("xml:lang") ||
+                        speakEl.getAttribute("lang") ||
+                        "en-US";
+                    // Get plain text for visual display
+                    const plainText = speakEl.textContent || "";
+                    // Find parent element or create wrapper
+                    let wrapper = speakEl.parentElement;
+                    if (!wrapper || wrapper.tagName === "BODY") {
+                        // SPEAK is at root level - create span wrapper
+                        const span = doc.createElement("span");
+                        speakEl.parentNode?.insertBefore(span, speakEl);
+                        span.appendChild(doc.createTextNode(plainText));
+                        wrapper = span;
+                        speakEl.remove();
+                    }
+                    else {
+                        // Just remove <speak> - visual content should be in sibling element
+                        speakEl.remove();
+                    }
+                    // Add catalog ID to wrapper element
+                    if (wrapper) {
+                        wrapper.setAttribute("data-catalog-id", catalogId);
+                    }
+                    // Create catalog entry
+                    catalogs.push({
+                        identifier: catalogId,
+                        cards: [
+                            {
+                                catalog: "spoken",
+                                language,
+                                content: ssmlContent,
+                            },
+                        ],
+                    });
+                }
+                catch (error) {
+                    console.error("[SSMLExtractor] Error processing <speak> element:", error);
+                    // Continue with other elements
+                }
+            }
+            // Return cleaned markup
+            const cleanedMarkup = doc.body.innerHTML;
+            return { catalogs, cleanedMarkup };
+        }
+        catch (error) {
+            console.error("[SSMLExtractor] Error parsing markup:", error);
+            // Return original markup if parsing fails
+            return { catalogs: [], cleanedMarkup: markup };
+        }
+    }
+    /**
+     * Generate unique catalog ID
+     *
+     * @param prefix Context prefix (e.g., 'prompt-q1', 'choice-q1-a')
+     * @returns Unique catalog ID (e.g., 'auto-prompt-q1-0')
+     */
+    generateCatalogId(prefix) {
+        const id = `auto-${prefix}-${this.catalogCounter}`;
+        this.catalogCounter++;
+        return id;
+    }
+    /**
+     * Reset counter (useful for testing or new extraction contexts)
+     */
+    reset() {
+        this.catalogCounter = 0;
+    }
+}
+//# sourceMappingURL=SSMLExtractor.js.map

package/dist/services/SSMLExtractor.js.map

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