npm - @pie-players/pie-assessment-toolkit - Versions diffs - 0.3.51 → 0.3.52 - Mend

@pie-players/pie-assessment-toolkit 0.3.51 → 0.3.52

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (24) hide show

package/dist/components/PieAssessmentToolkit.custom-element.js +174 -19
package/dist/context/assessment-toolkit-context.d.ts +2 -0
package/dist/context/assessment-toolkit-context.js.map +1 -1
package/dist/index.d.ts +2 -1
package/dist/index.js +1 -1
package/dist/index.js.map +1 -1
package/dist/services/HighlightCoordinator.d.ts +6 -0
package/dist/services/HighlightCoordinator.js +20 -5
package/dist/services/HighlightCoordinator.js.map +1 -1
package/dist/services/TTSService.d.ts +15 -0
package/dist/services/TTSService.js +184 -15
package/dist/services/TTSService.js.map +1 -1
package/dist/services/createDefaultToolRegistry.d.ts +2 -1
package/dist/services/createDefaultToolRegistry.js +2 -1
package/dist/services/createDefaultToolRegistry.js.map +1 -1
package/dist/services/interfaces.d.ts +11 -0
package/dist/services/interfaces.js.map +1 -1
package/dist/services/tool-config-defaults.d.ts +11 -0
package/dist/services/tool-config-defaults.js +18 -0
package/dist/services/tool-config-defaults.js.map +1 -1
package/dist/services/tts/highlight-target-resolver.d.ts +17 -0
package/dist/services/tts/highlight-target-resolver.js +2 -0
package/dist/services/tts/highlight-target-resolver.js.map +1 -0
package/package.json +7 -7

package/dist/services/createDefaultToolRegistry.d.ts CHANGED Viewed

@@ -8,7 +8,7 @@ import { ToolRegistry } from "./ToolRegistry.js";
 import type { ToolRegistration } from "./ToolRegistry.js";
 import type { ToolModuleLoader } from "./ToolRegistry.js";
 import { type ToolComponentFactory, type ToolComponentFactoryMap, type ToolTagMap } from "../tools/tool-tag-map.js";
-import { DEFAULT_TOOL_PLACEMENT, PACKAGED_TOOL_PLACEMENT } from "./tool-config-defaults.js";
+import { DEFAULT_TOOL_PLACEMENT, PACKAGED_TOOL_PLACEMENT, SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT } from "./tool-config-defaults.js";
 export interface DefaultToolRegistryOptions {
     /**
      * Override default tool registrations by toolId.
@@ -78,6 +78,7 @@ export declare function createPackagedToolRegistry(options?: Omit<DefaultToolReg
  */
 export { DEFAULT_TOOL_PLACEMENT };
 export { PACKAGED_TOOL_PLACEMENT };
+export { SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT };
 /**
  * Tool priority order for rendering
  * Tools will be rendered in this order when multiple tools are visible

package/dist/services/createDefaultToolRegistry.js CHANGED Viewed

@@ -12,7 +12,7 @@ import { answerEliminatorToolRegistration, highlighterToolRegistration, } from "
 import { lineReaderToolRegistration, themeToolRegistration, annotationToolbarRegistration, } from "../tools/registrations/accessibility-tools.js";
 import { graphToolRegistration, periodicTableToolRegistration, } from "../tools/registrations/subject-specific-tools.js";
 import { DEFAULT_TOOL_TAG_MAP, } from "../tools/tool-tag-map.js";
-import { DEFAULT_TOOL_PLACEMENT, PACKAGED_TOOL_PLACEMENT, } from "./tool-config-defaults.js";
+import { DEFAULT_TOOL_PLACEMENT, PACKAGED_TOOL_PLACEMENT, SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT, } from "./tool-config-defaults.js";
 const PACKAGED_TOOL_REGISTRATIONS = [
     calculatorToolRegistration,
     ttsToolRegistration,
@@ -99,6 +99,7 @@ export function createPackagedToolRegistry(options = {}) {
  */
 export { DEFAULT_TOOL_PLACEMENT };
 export { PACKAGED_TOOL_PLACEMENT };
+export { SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT };
 /**
  * Tool priority order for rendering
  * Tools will be rendered in this order when multiple tools are visible

package/dist/services/createDefaultToolRegistry.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"createDefaultToolRegistry.js","sourceRoot":"","sources":["../../src/services/createDefaultToolRegistry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGjD,OAAO,EAAE,0BAA0B,EAAE,MAAM,sCAAsC,CAAC;AAClF,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,EACN,qBAAqB,EACrB,0BAA0B,GAC1B,MAAM,6CAA6C,CAAC;AACrD,OAAO,EACN,gCAAgC,EAChC,2BAA2B,GAC3B,MAAM,6CAA6C,CAAC;AACrD,OAAO,EACN,0BAA0B,EAC1B,qBAAqB,EACrB,6BAA6B,GAC7B,MAAM,+CAA+C,CAAC;AACvD,OAAO,EACN,qBAAqB,EACrB,6BAA6B,GAC7B,MAAM,kDAAkD,CAAC;AAC1D,OAAO,EACN,oBAAoB,GAIpB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACN,sBAAsB,EACtB,uBAAuB,~~GACvB~~,MAAM,2BAA2B,CAAC;AAEnC,MAAM,2BAA2B,GAAG;IACnC,0BAA0B;IAC1B,mBAAmB;IACnB,qBAAqB;IACrB,0BAA0B;IAC1B,gCAAgC;IAChC,2BAA2B;IAC3B,0BAA0B;IAC1B,qBAAqB;IACrB,6BAA6B;IAC7B,qBAAqB;IACrB,6BAA6B;CACpB,CAAC;AAmCX;;;;;;;;GAQG;AACH,MAAM,UAAU,yBAAyB,CACxC,UAAsC,EAAE;IAExC,MAAM,QAAQ,GAAG,IAAI,YAAY,EAAE,CAAC;IACpC,MAAM,eAAe,GAAG;QACvB,UAAU,EAAE;YACX,GAAG,oBAAoB;YACvB,GAAG,CAAC,OAAO,CAAC,UAAU,IAAI,EAAE,CAAC;SAC7B;QACD,oBAAoB,EAAE,OAAO,CAAC,oBAAoB;QAClD,sBAAsB,EAAE,OAAO,CAAC,sBAAsB;KACtD,CAAC;IAEF,MAAM,cAAc,GAAG,CAAC,YAA8B,EAAoB,EAAE,CAC3E,OAAO,CAAC,SAAS,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,IAAI,YAAY,CAAC;IAE1D,IAAI,OAAO,CAAC,oBAAoB,EAAE,CAAC;QAClC,qBAAqB,CAAC,QAAQ,EAAE;YAC/B,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,cAAc;SACd,CAAC,CAAC;IACJ,CAAC;IAED,IACC,OAAO,CAAC,iBAAiB;QACzB,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,MAAM,GAAG,CAAC,EAChD,CAAC;QACF,QAAQ,CAAC,oBAAoB,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC1D,CAAC;IAED,QAAQ,CAAC,qBAAqB,CAAC,eAAe,CAAC,CAAC;IAEhD,OAAO,QAAQ,CAAC;AACjB,CAAC;AAOD;;GAEG;AACH,MAAM,UAAU,qBAAqB,CACpC,QAAsB,EACtB,UAAwC,EAAE;IAE1C,MAAM,eAAe,GACpB,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC;QAC5C,CAAC,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC;QAC1B,CAAC,CAAC,IAAI,CAAC;IACT,MAAM,cAAc,GACnB,OAAO,CAAC,cAAc;QACtB,CAAC,CAAC,YAA8B,EAAE,EAAE,CAAC,YAAY,CAAC,CAAC;IACpD,KAAK,MAAM,YAAY,IAAI,2BAA2B,EAAE,CAAC;QACxD,IAAI,eAAe,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC;YAClE,SAAS;QACV,CAAC;QACD,QAAQ,CAAC,QAAQ,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC,CAAC;IACjD,CAAC;AACF,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,0BAA0B,CACzC,UAAoE,EAAE;IAEtE,OAAO,yBAAyB,CAAC;QAChC,GAAG,OAAO;QACV,oBAAoB,EAAE,IAAI;KAC1B,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,sBAAsB,EAAE,CAAC;AAClC,OAAO,EAAE,uBAAuB,EAAE,CAAC;~~AAEnC~~;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IACjC,6BAA6B;IAC7B,OAAO;IACP,eAAe;IACf,YAAY;IACZ,cAAc;IACd,eAAe;IACf,YAAY;IACZ,mBAAmB;IACnB,aAAa;IACb,oBAAoB;IACpB,kBAAkB;IAClB,oBAAoB;IACpB,OAAO;IACP,YAAY;IACZ,mBAAmB;IACnB,OAAO;IACP,eAAe;CACN,CAAC","sourcesContent":["/*\n Default Tool Registry Factory\n \n Creates a ToolRegistry pre-populated with all PIE framework tools.\n * Integrators can use this as a starting point and customize as needed.\n /\n\nimport { ToolRegistry } from \"./ToolRegistry.js\";\nimport type { ToolRegistration } from \"./ToolRegistry.js\";\nimport type { ToolModuleLoader } from \"./ToolRegistry.js\";\nimport { calculatorToolRegistration } from \"../tools/registrations/calculator.js\";\nimport { ttsToolRegistration } from \"../tools/registrations/tts.js\";\nimport {\n\trulerToolRegistration,\n\tprotractorToolRegistration,\n} from \"../tools/registrations/measurement-tools.js\";\nimport {\n\tanswerEliminatorToolRegistration,\n\thighlighterToolRegistration,\n} from \"../tools/registrations/interaction-tools.js\";\nimport {\n\tlineReaderToolRegistration,\n\tthemeToolRegistration,\n\tannotationToolbarRegistration,\n} from \"../tools/registrations/accessibility-tools.js\";\nimport {\n\tgraphToolRegistration,\n\tperiodicTableToolRegistration,\n} from \"../tools/registrations/subject-specific-tools.js\";\nimport {\n\tDEFAULT_TOOL_TAG_MAP,\n\ttype ToolComponentFactory,\n\ttype ToolComponentFactoryMap,\n\ttype ToolTagMap,\n} from \"../tools/tool-tag-map.js\";\nimport {\n\tDEFAULT_TOOL_PLACEMENT,\n\tPACKAGED_TOOL_PLACEMENT,\n} from \"./tool-config-defaults.js\";\n\nconst PACKAGED_TOOL_REGISTRATIONS = [\n\tcalculatorToolRegistration,\n\tttsToolRegistration,\n\trulerToolRegistration,\n\tprotractorToolRegistration,\n\tanswerEliminatorToolRegistration,\n\thighlighterToolRegistration,\n\tlineReaderToolRegistration,\n\tthemeToolRegistration,\n\tannotationToolbarRegistration,\n\tgraphToolRegistration,\n\tperiodicTableToolRegistration,\n] as const;\n\nexport interface DefaultToolRegistryOptions {\n\t/\n\t Override default tool registrations by toolId.\n\t * This is the highest-precedence extension point.\n\t /\n\toverrides?: Partial<Record<string, ToolRegistration>>;\n\t/\n\t Override default component tag mapping used by built-in registrations.\n\t /\n\ttoolTagMap?: Partial<ToolTagMap>;\n\t/\n\t Override component factory globally (all tools) or per tool.\n\t /\n\ttoolComponentFactory?: ToolComponentFactory;\n\ttoolComponentFactories?: Partial<ToolComponentFactoryMap>;\n\t/\n\t Optional lazy module loaders keyed by toolId.\n\t * Hosts can inject default loaders from an external package.\n\t /\n\ttoolModuleLoaders?: Partial<Record<string, ToolModuleLoader>>;\n\t/\n\t Register packaged PIE tools by default.\n\t \n\t @default false\n\t /\n\tincludePackagedTools?: boolean;\n\t/\n\t Restrict registration to specific packaged tool IDs.\n\t * Ignored when includePackagedTools is false.\n\t /\n\ttoolIds?: string[];\n}\n\n/\n Create a tool registry.\n \n By default, this creates an empty registry so hosts can explicitly opt in.\n * For convenience, pass { includePackagedTools: true } to register all packaged tools,\n * or use createPackagedToolRegistry().\n \n @returns ToolRegistry with all default tools\n /\nexport function createDefaultToolRegistry(\n\toptions: DefaultToolRegistryOptions = {},\n): ToolRegistry {\n\tconst registry = new ToolRegistry();\n\tconst componentConfig = {\n\t\ttoolTagMap: {\n\t\t\t...DEFAULT_TOOL_TAG_MAP,\n\t\t\t...(options.toolTagMap \|\| {}),\n\t\t},\n\t\ttoolComponentFactory: options.toolComponentFactory,\n\t\ttoolComponentFactories: options.toolComponentFactories,\n\t};\n\n\tconst applyOverrides = (registration: ToolRegistration): ToolRegistration =>\n\t\toptions.overrides?.[registration.toolId] \|\| registration;\n\n\tif (options.includePackagedTools) {\n\t\tregisterPackagedTools(registry, {\n\t\t\ttoolIds: options.toolIds,\n\t\t\tapplyOverrides,\n\t\t});\n\t}\n\n\tif (\n\t\toptions.toolModuleLoaders &&\n\t\tObject.keys(options.toolModuleLoaders).length > 0\n\t) {\n\t\tregistry.setToolModuleLoaders(options.toolModuleLoaders);\n\t}\n\n\tregistry.setComponentOverrides(componentConfig);\n\n\treturn registry;\n}\n\nexport interface RegisterPackagedToolsOptions {\n\ttoolIds?: string[];\n\tapplyOverrides?: (registration: ToolRegistration) => ToolRegistration;\n}\n\n/\n Register packaged PIE tools onto an existing registry.\n /\nexport function registerPackagedTools(\n\tregistry: ToolRegistry,\n\toptions: RegisterPackagedToolsOptions = {},\n): void {\n\tconst selectedToolIds =\n\t\toptions.toolIds && options.toolIds.length > 0\n\t\t\t? new Set(options.toolIds)\n\t\t\t: null;\n\tconst applyOverrides =\n\t\toptions.applyOverrides \|\|\n\t\t((registration: ToolRegistration) => registration);\n\tfor (const registration of PACKAGED_TOOL_REGISTRATIONS) {\n\t\tif (selectedToolIds && !selectedToolIds.has(registration.toolId)) {\n\t\t\tcontinue;\n\t\t}\n\t\tregistry.register(applyOverrides(registration));\n\t}\n}\n\n/\n Convenience factory that registers all packaged PIE tools.\n /\nexport function createPackagedToolRegistry(\n\toptions: Omit<DefaultToolRegistryOptions, \"includePackagedTools\"> = {},\n): ToolRegistry {\n\treturn createDefaultToolRegistry({\n\t\t...options,\n\t\tincludePackagedTools: true,\n\t});\n}\n\n/\n Default tool placement configuration\n \n Defines which tools appear at which levels by default.\n * Integrators can override this configuration.\n \n Categories:\n * - Global tools: theme (assessment/section level)\n * - Context-smart: calculator, graph, periodicTable (item/element, auto-detect)\n * - Reading aids: textToSpeech, lineReader, annotationToolbar (where text exists)\n * - Interaction-specific: answerEliminator (choice questions), highlighter (text)\n * - Measurement: ruler, protractor (element level, diagram/geometry)\n /\nexport { DEFAULT_TOOL_PLACEMENT };\nexport { PACKAGED_TOOL_PLACEMENT };\n\n/\n Tool priority order for rendering\n * Tools will be rendered in this order when multiple tools are visible\n */\nexport const DEFAULT_TOOL_ORDER = [\n\t// Global accessibility first\n\t\"theme\",\n\t// Common tools\n\t\"calculator\",\n\t\"textToSpeech\",\n\t// Reading aids\n\t\"lineReader\",\n\t\"annotationToolbar\",\n\t\"highlighter\",\n\t// Interaction tools\n\t\"answerEliminator\",\n\t// Measurement tools\n\t\"ruler\",\n\t\"protractor\",\n\t// Subject-specific\n\t\"graph\",\n\t\"periodicTable\",\n] as const;\n"]}
1	+ {"version":3,"file":"createDefaultToolRegistry.js","sourceRoot":"","sources":["../../src/services/createDefaultToolRegistry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGjD,OAAO,EAAE,0BAA0B,EAAE,MAAM,sCAAsC,CAAC;AAClF,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,EACN,qBAAqB,EACrB,0BAA0B,GAC1B,MAAM,6CAA6C,CAAC;AACrD,OAAO,EACN,gCAAgC,EAChC,2BAA2B,GAC3B,MAAM,6CAA6C,CAAC;AACrD,OAAO,EACN,0BAA0B,EAC1B,qBAAqB,EACrB,6BAA6B,GAC7B,MAAM,+CAA+C,CAAC;AACvD,OAAO,EACN,qBAAqB,EACrB,6BAA6B,GAC7B,MAAM,kDAAkD,CAAC;AAC1D,OAAO,EACN,oBAAoB,GAIpB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACN,sBAAsB,EACtB,uBAAuB,EACvB,uCAAuC,GACvC,MAAM,2BAA2B,CAAC;AAEnC,MAAM,2BAA2B,GAAG;IACnC,0BAA0B;IAC1B,mBAAmB;IACnB,qBAAqB;IACrB,0BAA0B;IAC1B,gCAAgC;IAChC,2BAA2B;IAC3B,0BAA0B;IAC1B,qBAAqB;IACrB,6BAA6B;IAC7B,qBAAqB;IACrB,6BAA6B;CACpB,CAAC;AAmCX;;;;;;;;GAQG;AACH,MAAM,UAAU,yBAAyB,CACxC,UAAsC,EAAE;IAExC,MAAM,QAAQ,GAAG,IAAI,YAAY,EAAE,CAAC;IACpC,MAAM,eAAe,GAAG;QACvB,UAAU,EAAE;YACX,GAAG,oBAAoB;YACvB,GAAG,CAAC,OAAO,CAAC,UAAU,IAAI,EAAE,CAAC;SAC7B;QACD,oBAAoB,EAAE,OAAO,CAAC,oBAAoB;QAClD,sBAAsB,EAAE,OAAO,CAAC,sBAAsB;KACtD,CAAC;IAEF,MAAM,cAAc,GAAG,CAAC,YAA8B,EAAoB,EAAE,CAC3E,OAAO,CAAC,SAAS,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,IAAI,YAAY,CAAC;IAE1D,IAAI,OAAO,CAAC,oBAAoB,EAAE,CAAC;QAClC,qBAAqB,CAAC,QAAQ,EAAE;YAC/B,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,cAAc;SACd,CAAC,CAAC;IACJ,CAAC;IAED,IACC,OAAO,CAAC,iBAAiB;QACzB,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,MAAM,GAAG,CAAC,EAChD,CAAC;QACF,QAAQ,CAAC,oBAAoB,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC1D,CAAC;IAED,QAAQ,CAAC,qBAAqB,CAAC,eAAe,CAAC,CAAC;IAEhD,OAAO,QAAQ,CAAC;AACjB,CAAC;AAOD;;GAEG;AACH,MAAM,UAAU,qBAAqB,CACpC,QAAsB,EACtB,UAAwC,EAAE;IAE1C,MAAM,eAAe,GACpB,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC;QAC5C,CAAC,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC;QAC1B,CAAC,CAAC,IAAI,CAAC;IACT,MAAM,cAAc,GACnB,OAAO,CAAC,cAAc;QACtB,CAAC,CAAC,YAA8B,EAAE,EAAE,CAAC,YAAY,CAAC,CAAC;IACpD,KAAK,MAAM,YAAY,IAAI,2BAA2B,EAAE,CAAC;QACxD,IAAI,eAAe,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC;YAClE,SAAS;QACV,CAAC;QACD,QAAQ,CAAC,QAAQ,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC,CAAC;IACjD,CAAC;AACF,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,0BAA0B,CACzC,UAAoE,EAAE;IAEtE,OAAO,yBAAyB,CAAC;QAChC,GAAG,OAAO;QACV,oBAAoB,EAAE,IAAI;KAC1B,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,sBAAsB,EAAE,CAAC;AAClC,OAAO,EAAE,uBAAuB,EAAE,CAAC;AACnC,OAAO,EAAE,uCAAuC,EAAE,CAAC;AAEnD;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IACjC,6BAA6B;IAC7B,OAAO;IACP,eAAe;IACf,YAAY;IACZ,cAAc;IACd,eAAe;IACf,YAAY;IACZ,mBAAmB;IACnB,aAAa;IACb,oBAAoB;IACpB,kBAAkB;IAClB,oBAAoB;IACpB,OAAO;IACP,YAAY;IACZ,mBAAmB;IACnB,OAAO;IACP,eAAe;CACN,CAAC","sourcesContent":["/*\n Default Tool Registry Factory\n \n Creates a ToolRegistry pre-populated with all PIE framework tools.\n * Integrators can use this as a starting point and customize as needed.\n /\n\nimport { ToolRegistry } from \"./ToolRegistry.js\";\nimport type { ToolRegistration } from \"./ToolRegistry.js\";\nimport type { ToolModuleLoader } from \"./ToolRegistry.js\";\nimport { calculatorToolRegistration } from \"../tools/registrations/calculator.js\";\nimport { ttsToolRegistration } from \"../tools/registrations/tts.js\";\nimport {\n\trulerToolRegistration,\n\tprotractorToolRegistration,\n} from \"../tools/registrations/measurement-tools.js\";\nimport {\n\tanswerEliminatorToolRegistration,\n\thighlighterToolRegistration,\n} from \"../tools/registrations/interaction-tools.js\";\nimport {\n\tlineReaderToolRegistration,\n\tthemeToolRegistration,\n\tannotationToolbarRegistration,\n} from \"../tools/registrations/accessibility-tools.js\";\nimport {\n\tgraphToolRegistration,\n\tperiodicTableToolRegistration,\n} from \"../tools/registrations/subject-specific-tools.js\";\nimport {\n\tDEFAULT_TOOL_TAG_MAP,\n\ttype ToolComponentFactory,\n\ttype ToolComponentFactoryMap,\n\ttype ToolTagMap,\n} from \"../tools/tool-tag-map.js\";\nimport {\n\tDEFAULT_TOOL_PLACEMENT,\n\tPACKAGED_TOOL_PLACEMENT,\n\tSECTION_PLAYER_PREFERRED_TOOL_PLACEMENT,\n} from \"./tool-config-defaults.js\";\n\nconst PACKAGED_TOOL_REGISTRATIONS = [\n\tcalculatorToolRegistration,\n\tttsToolRegistration,\n\trulerToolRegistration,\n\tprotractorToolRegistration,\n\tanswerEliminatorToolRegistration,\n\thighlighterToolRegistration,\n\tlineReaderToolRegistration,\n\tthemeToolRegistration,\n\tannotationToolbarRegistration,\n\tgraphToolRegistration,\n\tperiodicTableToolRegistration,\n] as const;\n\nexport interface DefaultToolRegistryOptions {\n\t/\n\t Override default tool registrations by toolId.\n\t * This is the highest-precedence extension point.\n\t /\n\toverrides?: Partial<Record<string, ToolRegistration>>;\n\t/\n\t Override default component tag mapping used by built-in registrations.\n\t /\n\ttoolTagMap?: Partial<ToolTagMap>;\n\t/\n\t Override component factory globally (all tools) or per tool.\n\t /\n\ttoolComponentFactory?: ToolComponentFactory;\n\ttoolComponentFactories?: Partial<ToolComponentFactoryMap>;\n\t/\n\t Optional lazy module loaders keyed by toolId.\n\t * Hosts can inject default loaders from an external package.\n\t /\n\ttoolModuleLoaders?: Partial<Record<string, ToolModuleLoader>>;\n\t/\n\t Register packaged PIE tools by default.\n\t \n\t @default false\n\t /\n\tincludePackagedTools?: boolean;\n\t/\n\t Restrict registration to specific packaged tool IDs.\n\t * Ignored when includePackagedTools is false.\n\t /\n\ttoolIds?: string[];\n}\n\n/\n Create a tool registry.\n \n By default, this creates an empty registry so hosts can explicitly opt in.\n * For convenience, pass { includePackagedTools: true } to register all packaged tools,\n * or use createPackagedToolRegistry().\n \n @returns ToolRegistry with all default tools\n /\nexport function createDefaultToolRegistry(\n\toptions: DefaultToolRegistryOptions = {},\n): ToolRegistry {\n\tconst registry = new ToolRegistry();\n\tconst componentConfig = {\n\t\ttoolTagMap: {\n\t\t\t...DEFAULT_TOOL_TAG_MAP,\n\t\t\t...(options.toolTagMap \|\| {}),\n\t\t},\n\t\ttoolComponentFactory: options.toolComponentFactory,\n\t\ttoolComponentFactories: options.toolComponentFactories,\n\t};\n\n\tconst applyOverrides = (registration: ToolRegistration): ToolRegistration =>\n\t\toptions.overrides?.[registration.toolId] \|\| registration;\n\n\tif (options.includePackagedTools) {\n\t\tregisterPackagedTools(registry, {\n\t\t\ttoolIds: options.toolIds,\n\t\t\tapplyOverrides,\n\t\t});\n\t}\n\n\tif (\n\t\toptions.toolModuleLoaders &&\n\t\tObject.keys(options.toolModuleLoaders).length > 0\n\t) {\n\t\tregistry.setToolModuleLoaders(options.toolModuleLoaders);\n\t}\n\n\tregistry.setComponentOverrides(componentConfig);\n\n\treturn registry;\n}\n\nexport interface RegisterPackagedToolsOptions {\n\ttoolIds?: string[];\n\tapplyOverrides?: (registration: ToolRegistration) => ToolRegistration;\n}\n\n/\n Register packaged PIE tools onto an existing registry.\n /\nexport function registerPackagedTools(\n\tregistry: ToolRegistry,\n\toptions: RegisterPackagedToolsOptions = {},\n): void {\n\tconst selectedToolIds =\n\t\toptions.toolIds && options.toolIds.length > 0\n\t\t\t? new Set(options.toolIds)\n\t\t\t: null;\n\tconst applyOverrides =\n\t\toptions.applyOverrides \|\|\n\t\t((registration: ToolRegistration) => registration);\n\tfor (const registration of PACKAGED_TOOL_REGISTRATIONS) {\n\t\tif (selectedToolIds && !selectedToolIds.has(registration.toolId)) {\n\t\t\tcontinue;\n\t\t}\n\t\tregistry.register(applyOverrides(registration));\n\t}\n}\n\n/\n Convenience factory that registers all packaged PIE tools.\n /\nexport function createPackagedToolRegistry(\n\toptions: Omit<DefaultToolRegistryOptions, \"includePackagedTools\"> = {},\n): ToolRegistry {\n\treturn createDefaultToolRegistry({\n\t\t...options,\n\t\tincludePackagedTools: true,\n\t});\n}\n\n/\n Default tool placement configuration\n \n Defines which tools appear at which levels by default.\n * Integrators can override this configuration.\n \n Categories:\n * - Global tools: theme (assessment/section level)\n * - Context-smart: calculator, graph, periodicTable (item/element, auto-detect)\n * - Reading aids: textToSpeech, lineReader, annotationToolbar (where text exists)\n * - Interaction-specific: answerEliminator (choice questions), highlighter (text)\n * - Measurement: ruler, protractor (element level, diagram/geometry)\n /\nexport { DEFAULT_TOOL_PLACEMENT };\nexport { PACKAGED_TOOL_PLACEMENT };\nexport { SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT };\n\n/\n Tool priority order for rendering\n * Tools will be rendered in this order when multiple tools are visible\n */\nexport const DEFAULT_TOOL_ORDER = [\n\t// Global accessibility first\n\t\"theme\",\n\t// Common tools\n\t\"calculator\",\n\t\"textToSpeech\",\n\t// Reading aids\n\t\"lineReader\",\n\t\"annotationToolbar\",\n\t\"highlighter\",\n\t// Interaction tools\n\t\"answerEliminator\",\n\t// Measurement tools\n\t\"ruler\",\n\t\"protractor\",\n\t// Subject-specific\n\t\"graph\",\n\t\"periodicTable\",\n] as const;\n"]}

package/dist/services/interfaces.d.ts CHANGED Viewed

@@ -15,6 +15,7 @@ import type { SectionControllerHandle, SectionItemEventSubscriptionArgs, Section
 import type { ThemeConfig } from "./ThemeProvider.js";
 import type { ZIndexLayer } from "./ToolCoordinator.js";
 import type { PlaybackState, TTSConfig } from "./TTSService.js";
+import type { TTSHighlightTargetResolverProvider } from "./tts/highlight-target-resolver.js";
 import type { ToolPlacementConfig, ToolPlacementLevel, ToolProviderConfig } from "./tools-config-normalizer.js";
 import type { ToolProviderRegistry } from "./tool-providers/ToolProviderRegistry.js";
 import type { PolicySource, PnpEnforcementMode, ResolvedEngineInputs, ToolPolicyChangeListener, ToolPolicyDecision, ToolPolicyDecisionRequest } from "../policy/engine.js";
@@ -76,6 +77,12 @@ export interface HighlightCoordinatorApi {
      * Highlight sentence(s) for TTS (background layer)
      */
     highlightTTSSentence(ranges: Range[]): void;
+    /**
+     * Highlight sentence/block element targets for TTS (background layer).
+     *
+     * Optional so lightweight coordinator mocks can omit it.
+     */
+    highlightTTSSentenceElements?(elements: Element[]): void;
     /**
      * Clear all TTS highlights (word and sentence)
      */
@@ -251,6 +258,10 @@ export interface TtsServiceApi {
      * Set highlight coordinator for word highlighting
      */
     setHighlightCoordinator(coordinator: HighlightCoordinatorApi): void;
+    /**
+     * Set a late-bound provider for optional host TTS highlight target remapping.
+     */
+    setHighlightTargetResolverProvider?(provider: TTSHighlightTargetResolverProvider | null): () => void;
     /**
      * Set accessibility catalog resolver for spoken content
      */

package/dist/services/interfaces.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../../src/services/interfaces.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;;AAk1BH,0EAA0E","sourcesContent":["/*\n Service Interfaces\n \n Public interfaces for all core assessment toolkit services.\n * These interfaces define the contracts that service implementations must fulfill,\n * enabling dependency injection, testing, and custom implementations.\n \n Part of PIE Assessment Toolkit.\n /\n\nimport type { I18nServiceApi } from \"@pie-players/pie-players-shared/i18n\";\nimport type {\n\tAccessibilityCatalogResolver,\n\tCatalogLookupContext,\n\tCatalogLookupOptions,\n\tCatalogOwnerContext,\n\tCatalogStatistics,\n\tCatalogType,\n\tResolvedCatalog,\n} from \"./AccessibilityCatalogResolver.js\";\nimport type { FrameworkErrorListener } from \"./framework-error-bus.js\";\nimport type { HighlightColor, HighlightType } from \"./HighlightCoordinator.js\";\nimport type {\n\tSectionControllerHandle,\n\tSectionItemEventSubscriptionArgs,\n\tSectionScopedEventSubscriptionArgs,\n\tSectionEventSubscriptionArgs,\n\tToolkitCoordinatorHooks,\n\tToolkitInitStatus,\n} from \"./ToolkitCoordinator.js\";\nimport type { FontSize, ThemeConfig } from \"./ThemeProvider.js\";\nimport type { ZIndexLayer } from \"./ToolCoordinator.js\";\nimport type { PlaybackState, TTSConfig } from \"./TTSService.js\";\nimport type {\n\tToolPlacementConfig,\n\tToolPlacementLevel,\n\tToolProviderConfig,\n} from \"./tools-config-normalizer.js\";\nimport type { ToolProviderRegistry } from \"./tool-providers/ToolProviderRegistry.js\";\nimport type {\n\tPolicySource,\n\tPnpEnforcementMode,\n\tResolvedEngineInputs,\n\tToolPolicyChangeListener,\n\tToolPolicyDecision,\n\tToolPolicyDecisionRequest,\n} from \"../policy/engine.js\";\nimport type {\n\tAssessmentEntity,\n\tAssessmentItemRef,\n} from \"@pie-players/pie-players-shared/types\";\nimport type {\n\tITTSProvider,\n\tTTSProviderCapabilities,\n} from \"@pie-players/pie-tts\";\nimport type {\n\tResolvedToolContext,\n\tToolContextResolver,\n\tToolContextResolverContext,\n\tToolContextResolverMap,\n} from \"./ToolRegistry.js\";\n\n// Re-export I18nServiceApi from players-shared\nexport type { I18nServiceApi };\n\n/\n Theme provider interface\n \n Applies consistent accessibility theming across items and tools.\n /\nexport interface ThemeProviderApi {\n\t/\n\t Apply theme configuration\n\t /\n\tapplyTheme(config: ThemeConfig): void;\n\n\t/\n\t Get current theme configuration\n\t /\n\tgetCurrentTheme(): Required<ThemeConfig>;\n\n\t/\n\t Reset to default theme\n\t /\n\treset(): void;\n\n\t/\n\t Clean up and remove theme styles\n\t /\n\tdestroy(): void;\n}\n\n/\n Highlight coordinator interface\n \n Manages content highlighting for TTS, annotations, and selections.\n /\nexport interface HighlightCoordinatorApi {\n\t/\n\t Highlight a text range\n\t /\n\thighlightRange(\n\t\trange: Range,\n\t\ttype: HighlightType,\n\t\tcolor: HighlightColor,\n\t): void;\n\n\t/\n\t Highlight a word for TTS (temporary)\n\t /\n\thighlightTTSWord(\n\t\ttextNode: Text,\n\t\tstartOffset: number,\n\t\tendOffset: number,\n\t): void;\n\n\t/\n\t Highlight a single element as the active TTS word (temporary).\n\t \n\t Marks exactly the supplied element (via `data-pie-tts-word-element`)\n\t * without walking up to a containing ancestor. Used for atomic targets that\n\t * have no direct text node to range over — most notably MathJax CHTML tokens\n\t * (e.g. `<mjx-mi><mjx-c/></mjx-mi>`) and whole-expression fallbacks. Painting\n\t * the element itself is what lets a resolved math token highlight as a token\n\t * rather than escalating to the full `<math>` / `<mjx-container>`.\n\t \n\t Optional so lightweight coordinator mocks can omit it.\n\t /\n\thighlightTTSWordElement?(element: Element): void;\n\n\t/\n\t Highlight sentence(s) for TTS (background layer)\n\t /\n\thighlightTTSSentence(ranges: Range[]): void;\n\n\t/\n\t Clear all TTS highlights (word and sentence)\n\t /\n\tclearTTS(): void;\n\n\t/\n\t Clear highlights of a specific type\n\t /\n\tclearHighlights(type: HighlightType): void;\n\n\t/\n\t Clear all highlights\n\t /\n\tclearAll(): void;\n\n\t/\n\t Check if highlighting is supported in current environment\n\t /\n\tisSupported(): boolean;\n\n\t/\n\t Update TTS highlight style dynamically\n\t /\n\tupdateTTSHighlightStyle(color: string, opacity: number): void;\n}\n\n/\n Tool state interface\n /\nexport interface ToolState {\n\tid: string;\n\tname: string;\n\tisVisible: boolean;\n\telement: HTMLElement \| null;\n\tlayer: ZIndexLayer;\n}\n\n/\n Tool coordinator interface\n \n Manages z-index layering and visibility for floating tools.\n /\nexport interface ToolCoordinatorApi {\n\t/\n\t Register a tool with the coordinator\n\t /\n\tregisterTool(\n\t\tid: string,\n\t\tname: string,\n\t\telement?: HTMLElement,\n\t\tlayer?: ZIndexLayer,\n\t): void;\n\n\t/\n\t Unregister a tool\n\t /\n\tunregisterTool(id: string): void;\n\n\t/\n\t Show a tool\n\t /\n\tshowTool(id: string): void;\n\n\t/\n\t Hide a tool\n\t /\n\thideTool(id: string): void;\n\n\t/\n\t Toggle tool visibility\n\t /\n\ttoggleTool(id: string): void;\n\n\t/\n\t Check if tool is visible\n\t /\n\tisToolVisible(id: string): boolean;\n\n\t/\n\t Bring an element to the front of its layer\n\t /\n\tbringToFront(element: HTMLElement): void;\n\n\t/\n\t Update the element reference for a tool\n\t /\n\tupdateToolElement(id: string, element: HTMLElement): void;\n\n\t/\n\t Get state for a specific tool\n\t /\n\tgetToolState(id: string): ToolState \| undefined;\n\n\t/\n\t Get all visible tools\n\t /\n\tgetVisibleTools(): ToolState[];\n\n\t/\n\t Subscribe to tool state changes\n\t /\n\tsubscribe(listener: () => void): () => void;\n}\n\n/\n TTS service interface\n \n Provides text-to-speech functionality with provider-based architecture.\n * Supports QTI 3.0 accessibility catalogs for pre-authored spoken content.\n /\nexport interface TtsServiceApi {\n\t/\n\t Initialize TTS with a provider\n\t /\n\tinitialize(\n\t\tprovider: ITTSProvider,\n\t\tconfig?: Partial<TTSConfig>,\n\t): Promise<void>;\n\n\t/\n\t Speak text with optional catalog support\n\t /\n\tspeak(\n\t\ttext: string,\n\t\toptions?: {\n\t\t\tcatalogId?: string;\n\t\t\tcatalogContext?: CatalogLookupContext;\n\t\t\tlanguage?: string;\n\t\t\tcontentElement?: Element;\n\t\t},\n\t): Promise<void>;\n\n\t/\n\t Speak a text range\n\t /\n\tspeakRange(\n\t\trange: Range,\n\t\toptions?: { contentRoot?: Element \| null },\n\t): Promise<void>;\n\n\t/\n\t Pause playback\n\t /\n\tpause(): void;\n\n\t/\n\t Resume playback\n\t /\n\tresume(): void;\n\n\t/\n\t Stop playback\n\t /\n\tstop(): void;\n\n\t/\n\t Request active TTS controls to hand off/deactivate their UI state.\n\t \n\t This is an orchestration hint for TTS tool chrome and does not replace\n\t * playback controls such as stop/pause/resume.\n\t /\n\trequestControlHandoff(): void;\n\n\t/\n\t Seek forward by sentence units\n\t /\n\tseekForward(units?: number): Promise<void>;\n\n\t/\n\t Seek backward by sentence units\n\t /\n\tseekBackward(units?: number): Promise<void>;\n\n\t/\n\t Check if currently playing\n\t /\n\tisPlaying(): boolean;\n\n\t/\n\t Check if paused\n\t /\n\tisPaused(): boolean;\n\n\t/\n\t Get current playback state\n\t /\n\tgetState(): PlaybackState;\n\n\t/\n\t Get currently speaking text\n\t /\n\tgetCurrentText(): string \| null;\n\n\t/\n\t Subscribe to state changes\n\t /\n\tonStateChange(id: string, callback: (state: PlaybackState) => void): void;\n\n\t/\n\t Unsubscribe from state changes\n\t /\n\toffStateChange(id: string, callback: (state: PlaybackState) => void): void;\n\n\t/\n\t Get capabilities of current provider\n\t /\n\tgetCapabilities(): TTSProviderCapabilities \| null;\n\n\t/\n\t Update TTS settings dynamically (rate, pitch, voice)\n\t /\n\tupdateSettings(settings: Partial<TTSConfig>): Promise<void>;\n\n\t/\n\t Update playback speed and apply it to active planned playback.\n\t /\n\tsetPlaybackRate(rate: number): Promise<void>;\n\n\t/\n\t Set highlight coordinator for word highlighting\n\t /\n\tsetHighlightCoordinator(coordinator: HighlightCoordinatorApi): void;\n\n\t/\n\t Set accessibility catalog resolver for spoken content\n\t /\n\tsetCatalogResolver(resolver: AccessibilityCatalogResolver): void;\n}\n\n/\n Accessibility catalog resolver interface\n \n Manages QTI 3.0 accessibility catalogs at assessment and item levels.\n * Provides lookup and resolution services for alternative content representations.\n /\nexport interface AccessibilityCatalogResolverApi {\n\t/\n\t Set the default language for fallback resolution\n\t /\n\tsetDefaultLanguage(language: string): void;\n\n\t/\n\t Get the default language\n\t /\n\tgetDefaultLanguage(): string;\n\n\t/\n\t Add item-level catalogs (called when rendering a new item)\n\t /\n\taddItemCatalogs(catalogs: any[]): void;\n\n\t/\n\t Register catalogs scoped to a mounted content owner.\n\t /\n\tregisterCatalogs?(context: CatalogOwnerContext, catalogs: any[]): () => void;\n\n\t/\n\t Clear item-level catalogs (called when leaving an item)\n\t /\n\tclearItemCatalogs(): void;\n\n\t/\n\t Check if a catalog exists\n\t /\n\thasCatalog(catalogId: string): boolean;\n\n\t/\n\t Get alternative content for a catalog identifier\n\t /\n\tgetAlternative(\n\t\tcatalogId: string,\n\t\toptions: CatalogLookupOptions,\n\t): ResolvedCatalog \| null;\n\n\t/\n\t Get all available alternatives for a catalog identifier\n\t /\n\tgetAllAlternatives(catalogId: string): ResolvedCatalog[];\n\n\t/\n\t Get all catalog identifiers available\n\t /\n\tgetAllCatalogIds(): string[];\n\n\t/\n\t Get statistics about available catalogs\n\t /\n\tgetStatistics(): CatalogStatistics;\n\n\t/\n\t Check if a specific catalog type is available\n\t /\n\thasAlternativeType(catalogId: string, type: CatalogType): boolean;\n\n\t/\n\t Get all catalog IDs that have a specific type of alternative\n\t /\n\tgetCatalogsByType(type: CatalogType): string[];\n\n\t/\n\t Reset all catalogs\n\t /\n\treset(): void;\n\n\t/\n\t Destroy and cleanup\n\t /\n\tdestroy(): void;\n}\n\n/\n Element tool state store interface\n \n Manages element-level ephemeral tool state using composite keys for global uniqueness.\n * Tool state is client-only and separate from PIE session data (which is sent to server for scoring).\n /\nexport interface ElementToolStateStoreApi {\n\t/\n\t Generate a globally unique element ID from components\n\t /\n\tgetGlobalElementId(\n\t\tassessmentId: string,\n\t\tsectionId: string,\n\t\titemId: string,\n\t\telementId: string,\n\t): string;\n\n\t/\n\t Parse a global element ID into its components\n\t /\n\tparseGlobalElementId(globalElementId: string): {\n\t\tassessmentId: string;\n\t\tsectionId: string;\n\t\titemId: string;\n\t\telementId: string;\n\t} \| null;\n\n\t/\n\t Set state for a specific tool on an element\n\t /\n\tsetState(globalElementId: string, toolId: string, state: any): void;\n\n\t/\n\t Get state for a specific tool on an element\n\t /\n\tgetState(globalElementId: string, toolId: string): any \| undefined;\n\n\t/\n\t Get all tool states for a specific element\n\t /\n\tgetElementState(globalElementId: string): Record<string, any>;\n\n\t/\n\t Get all element states\n\t /\n\tgetAllState(): Record<string, Record<string, any>>;\n\n\t/\n\t Subscribe to state changes\n\t /\n\tsubscribe(\n\t\tcallback: (state: Map<string, Map<string, any>>) => void,\n\t): () => void;\n\n\t/\n\t Set callback for persistence integration\n\t /\n\tsetOnStateChange(\n\t\tcallback: (state: Record<string, Record<string, any>>) => void,\n\t): void;\n\n\t/\n\t Load state from persistence\n\t /\n\tloadState(state: Record<string, Record<string, any>>): void;\n\n\t/\n\t Clear state for a specific element\n\t /\n\tclearElement(globalElementId: string): void;\n\n\t/\n\t Clear state for a specific tool across all elements\n\t /\n\tclearTool(toolId: string): void;\n\n\t/\n\t Clear all elements in a specific section\n\t /\n\tclearSection(assessmentId: string, sectionId: string): void;\n\n\t/\n\t Clear all state\n\t /\n\tclearAll(): void;\n}\n\n/\n Toolkit coordinator interface\n \n Orchestrates all toolkit services (TTS, tools, accessibility, state management) from a single entry point.\n * Provides centralized configuration for tool availability and settings.\n /\nexport interface ToolkitCoordinatorApi {\n\t/\n\t Assessment identifier\n\t /\n\treadonly assessmentId: string;\n\n\t/\n\t Configuration\n\t /\n\treadonly config: {\n\t\ttools?: {\n\t\t\tproviders?: Record<string, ToolProviderConfig \| undefined>;\n\t\t};\n\t};\n\n\t/\n\t TTS service\n\t /\n\treadonly ttsService: TtsServiceApi;\n\n\t/\n\t Tool coordinator\n\t /\n\treadonly toolCoordinator: ToolCoordinatorApi;\n\n\t/\n\t Highlight coordinator\n\t /\n\treadonly highlightCoordinator: HighlightCoordinatorApi;\n\n\t/\n\t Element tool state store\n\t /\n\treadonly elementToolStateStore: ElementToolStateStoreApi;\n\n\t/\n\t Catalog resolver\n\t /\n\treadonly catalogResolver: AccessibilityCatalogResolverApi;\n\n\t/\n\t Tool provider registry\n\t /\n\treadonly toolProviderRegistry: ToolProviderRegistry;\n\n\t/\n\t Get all services as a bundle\n\t /\n\tgetServiceBundle(): {\n\t\tttsService: TtsServiceApi;\n\t\ttoolCoordinator: ToolCoordinatorApi;\n\t\thighlightCoordinator: HighlightCoordinatorApi;\n\t\telementToolStateStore: ElementToolStateStoreApi;\n\t\tcatalogResolver: AccessibilityCatalogResolverApi;\n\t\ttoolProviderRegistry: ToolProviderRegistry;\n\t};\n\n\t/\n\t Ensure TTS service is initialized and ready.\n\t /\n\tensureTTSReady(config?: Record<string, unknown>): Promise<void>;\n\n\t/\n\t Ensure a provider is initialized and ready.\n\t /\n\tensureProviderReady(providerId: string): Promise<unknown>;\n\n\t/\n\t Wait until coordinator initialization is complete.\n\t /\n\twaitUntilReady(): Promise<void>;\n\n\t/\n\t Check if coordinator has completed initialization.\n\t /\n\tisReady(): boolean;\n\n\t/\n\t Read current initialization status.\n\t /\n\tgetInitStatus(): ToolkitInitStatus;\n\n\t/\n\t Check if a tool is enabled\n\t /\n\tisToolEnabled(toolId: string): boolean;\n\n\t/\n\t Get tool configuration\n\t /\n\tgetToolConfig(toolId: string): ToolProviderConfig \| null;\n\n\t/\n\t Update tool configuration\n\t /\n\tupdateToolConfig(toolId: string, updates: Partial<ToolProviderConfig>): void;\n\n\t/\n\t Update the enabled tool list for one placement level.\n\t /\n\tupdateToolPlacement(level: ToolPlacementLevel, toolIds: string[]): void;\n\n\t/\n\t Patch one or more placement levels in the canonical tools config.\n\t /\n\tupdateToolsPlacement(partial: ToolPlacementConfig): void;\n\n\t/\n\t Register or update lifecycle hooks at runtime.\n\t /\n\tsetHooks(hooks: ToolkitCoordinatorHooks): void;\n\n\t/\n\t Return a section controller if already created.\n\t /\n\tgetSectionController(args: {\n\t\tsectionId: string;\n\t\tattemptId?: string;\n\t}): SectionControllerHandle \| undefined;\n\n\t/\n\t Subscribe to section controller events.\n\t \n\t The listener is bound to the toolkit's active section cohort and\n\t * automatically migrates across cohort transitions\n\t * (`getOrCreateSectionController` for a different cohort). On every\n\t * migration the listener receives a snapshot replay of the new\n\t * cohort's already-loaded `content-loaded` events followed by the\n\t * aggregate `section-loading-complete`, in the canonical order a\n\t * fresh subscriber would have observed.\n\t \n\t Throws if no active section cohort exists; host code must call\n\t * `getOrCreateSectionController(...)` at least once before\n\t * subscribing. (`toolkit-ready` alone is not sufficient — it fires\n\t * once toolkit state has loaded but before any section controller\n\t * has been created.) The typical pattern is to subscribe once\n\t * immediately after the first `getOrCreateSectionController(...)`\n\t * resolves; the subscription then follows the active cohort across\n\t * all subsequent navigation without further wiring.\n\t \n\t Subscribing the same `listener` reference twice replaces the prior\n\t * subscription with the new one (filter args from the second call\n\t * win); calling the returned disposer twice is a no-op.\n\t \n\t A listener that throws is caught and `console.warn`-logged; the\n\t * throw does not interrupt fan-out to the remaining listeners.\n\t /\n\tsubscribeSectionEvents(args: SectionEventSubscriptionArgs): () => void;\n\n\t/\n\t Subscribe to item-scoped section controller events.\n\t \n\t Same active-cohort binding contract as {@link subscribeSectionEvents};\n\t * defaults `eventTypes` to the item-scoped subset.\n\t /\n\tsubscribeItemEvents(args: SectionItemEventSubscriptionArgs): () => void;\n\n\t/\n\t Subscribe to section-scoped lifecycle/loading/completion/error events.\n\t \n\t Same active-cohort binding contract as {@link subscribeSectionEvents};\n\t * defaults `eventTypes` to the section-scoped subset.\n\t /\n\tsubscribeSectionLifecycleEvents(\n\t\targs: SectionScopedEventSubscriptionArgs,\n\t): () => void;\n\n\t/\n\t Create or reuse a section controller with single-flight deduplication.\n\t /\n\tgetOrCreateSectionController(args: {\n\t\tsectionId: string;\n\t\tattemptId?: string;\n\t\tinput?: unknown;\n\t\tupdateExisting?: boolean;\n\t\tcreateDefaultController: () =>\n\t\t\t\| SectionControllerHandle\n\t\t\t\| Promise<SectionControllerHandle>;\n\t}): Promise<SectionControllerHandle>;\n\n\t/\n\t Dispose an existing section controller.\n\t /\n\tdisposeSectionController(args: {\n\t\tsectionId: string;\n\t\tattemptId?: string;\n\t\tpersistBeforeDispose?: boolean;\n\t\tclearPersistence?: boolean;\n\t}): Promise<void>;\n\n\t/\n\t Subscribe to framework-error events emitted by the coordinator.\n\t \n\t Mirrors the shape of {@link subscribeTelemetry} (see\n\t * `ToolkitCoordinator.subscribeTelemetry`): a synchronous,\n\t * multi-subscriber stream where each call to the internal bus's\n\t * `reportFrameworkError` fans out to every active listener exactly once.\n\t \n\t The returned function detaches the listener; calling it twice is a\n\t * no-op. A listener that throws is caught and logged; the throw does\n\t * not break fan-out to the remaining listeners.\n\t \n\t Use this to wire framework errors into Sentry / Datadog / a custom\n\t * banner without listening on a DOM event. The DOM event\n\t * (`framework-error`) and the canonical `onFrameworkError` prop on\n\t * `<pie-assessment-toolkit>` consume the same bus.\n\t /\n\tsubscribeFrameworkErrors(listener: FrameworkErrorListener): () => void;\n\n\t// ----------------------------------------------------------------\n\t// Tool Policy Engine — public surface (M8 PR 2 / PR 3).\n\t//\n\t// The coordinator owns a single `ToolPolicyEngine` instance and\n\t// exposes its decision and subscription surface through the API\n\t// so that toolbar custom elements (`pie-item-toolbar`,\n\t// `pie-section-toolbar`), the base section player, and bespoke\n\t// host instrumentation (PNP debugger, etc.) all flow through the\n\t// same engine. Hosts that want to drive PNP/profile inputs imperatively\n\t// (instead of binding props on `<pie-assessment-toolkit>`) call\n\t// `updateAssessment` / `updateCurrentItemRef` /\n\t// `setPnpEnforcement` directly.\n\t// ----------------------------------------------------------------\n\n\t/\n\t Resolve the visible tool set for a given placement level + scope.\n\t * Returns the engine's full decision (visible tools, diagnostics,\n\t * provenance). Hosts that only need the IDs may map\n\t * `decision.visibleTools` themselves.\n\t /\n\tdecideToolPolicy(request: ToolPolicyDecisionRequest): ToolPolicyDecision;\n\n\t/\n\t Subscribe to policy-engine change events. Fires whenever the\n\t * coordinator's bound policy inputs change (`updateToolConfig`,\n\t * `updateToolPlacement`, `updateAssessment`, `updateCurrentItemRef`,\n\t * `setPnpEnforcement`) or a custom `PolicySource` is registered /\n\t * removed. Listeners that need the new visible tool set should\n\t * call `decideToolPolicy(...)` with their level / scope.\n\t /\n\tonPolicyChange(listener: ToolPolicyChangeListener): () => void;\n\n\t/\n\t Bind (or clear) the active assessment for PNP/profile policy decisions.\n\t \n\t Under auto-mode (no host override via {@link setPnpEnforcement}),\n\t * the engine flips to `pnpEnforcement: \"on\"` iff the assessment\n\t * carries profile precedence material (`personalNeedsProfile`,\n\t * `settings.districtPolicy`, `settings.testAdministration`) or the\n\t * currently-bound item ref carries item-level profile inputs. A bare\n\t * assessment record (just `id` / `name`) keeps `\"off\"`.\n\t \n\t The host override set via {@link setPnpEnforcement} is sticky\n\t * across assessment swaps.\n\t /\n\tupdateAssessment(assessment: AssessmentEntity \| null): void;\n\n\t/\n\t Bind (or clear) the current item reference for policy decisions.\n\t * Used by item-level profile gates (item `requiredTools` /\n\t * `restrictedTools` / `toolParameters`). Item-level profile material\n\t * also feeds the auto-mode helper — navigating to an item with\n\t * profile settings can flip auto-mode to `\"on\"` even when the parent\n\t * assessment carries no profile block of its own.\n\t /\n\tupdateCurrentItemRef(itemRef: AssessmentItemRef \| null): void;\n\n\t/\n\t Override the auto-mode PNP/profile enforcement decision. Pass `\"on\"` /\n\t * `\"off\"` to pin the mode, or `null` to clear the override and\n\t * return to auto-mode (`\"on\"` iff the bound assessment / item ref\n\t * carries profile material, otherwise `\"off\"`).\n\t /\n\tsetPnpEnforcement(mode: PnpEnforcementMode \| null): void;\n\n\t/\n\t Read the engine inputs currently driving decisions. Useful for\n\t * debugging / instrumentation; do not mutate.\n\t /\n\tgetPolicyInputs(): Readonly<ResolvedEngineInputs>;\n\n\t/\n\t Register a custom `PolicySource`. The source participates in\n\t * every subsequent `decideToolPolicy(...)` call until disposed\n\t * (the returned function detaches).\n\t /\n\tregisterPolicySource(source: PolicySource): () => void;\n\n\t/\n\t Register a host-owned resolver for scoped tool render context.\n\t /\n\tregisterToolContextResolver(\n\t\ttoolId: string,\n\t\tresolver: ToolContextResolver,\n\t): () => void;\n\n\t/\n\t Replace all host-owned render-context resolvers.\n\t /\n\tsetToolContextResolvers(\n\t\tresolvers: ToolContextResolverMap \| null \| undefined,\n\t): void;\n\n\t/\n\t Whether a host resolver is registered for this tool.\n\t /\n\thasToolContextResolver(toolId: string): boolean;\n\n\t/\n\t Resolve render visibility/params for a tool that already survived policy gates.\n\t /\n\tresolveToolContext(\n\t\tcontext: ToolContextResolverContext,\n\t): ResolvedToolContext \| null;\n\n\t/\n\t Subscribe to resolver registration/removal changes.\n\t */\n\tonToolContextResolverChange(listener: () => void): () => void;\n}\n\n// I18nServiceApi is re-exported from @pie-players/pie-players-shared/i18n\n"]}
1	+ {"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../../src/services/interfaces.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;;AAi2BH,0EAA0E","sourcesContent":["/*\n Service Interfaces\n \n Public interfaces for all core assessment toolkit services.\n * These interfaces define the contracts that service implementations must fulfill,\n * enabling dependency injection, testing, and custom implementations.\n \n Part of PIE Assessment Toolkit.\n /\n\nimport type { I18nServiceApi } from \"@pie-players/pie-players-shared/i18n\";\nimport type {\n\tAccessibilityCatalogResolver,\n\tCatalogLookupContext,\n\tCatalogLookupOptions,\n\tCatalogOwnerContext,\n\tCatalogStatistics,\n\tCatalogType,\n\tResolvedCatalog,\n} from \"./AccessibilityCatalogResolver.js\";\nimport type { FrameworkErrorListener } from \"./framework-error-bus.js\";\nimport type { HighlightColor, HighlightType } from \"./HighlightCoordinator.js\";\nimport type {\n\tSectionControllerHandle,\n\tSectionItemEventSubscriptionArgs,\n\tSectionScopedEventSubscriptionArgs,\n\tSectionEventSubscriptionArgs,\n\tToolkitCoordinatorHooks,\n\tToolkitInitStatus,\n} from \"./ToolkitCoordinator.js\";\nimport type { FontSize, ThemeConfig } from \"./ThemeProvider.js\";\nimport type { ZIndexLayer } from \"./ToolCoordinator.js\";\nimport type { PlaybackState, TTSConfig } from \"./TTSService.js\";\nimport type { TTSHighlightTargetResolverProvider } from \"./tts/highlight-target-resolver.js\";\nimport type {\n\tToolPlacementConfig,\n\tToolPlacementLevel,\n\tToolProviderConfig,\n} from \"./tools-config-normalizer.js\";\nimport type { ToolProviderRegistry } from \"./tool-providers/ToolProviderRegistry.js\";\nimport type {\n\tPolicySource,\n\tPnpEnforcementMode,\n\tResolvedEngineInputs,\n\tToolPolicyChangeListener,\n\tToolPolicyDecision,\n\tToolPolicyDecisionRequest,\n} from \"../policy/engine.js\";\nimport type {\n\tAssessmentEntity,\n\tAssessmentItemRef,\n} from \"@pie-players/pie-players-shared/types\";\nimport type {\n\tITTSProvider,\n\tTTSProviderCapabilities,\n} from \"@pie-players/pie-tts\";\nimport type {\n\tResolvedToolContext,\n\tToolContextResolver,\n\tToolContextResolverContext,\n\tToolContextResolverMap,\n} from \"./ToolRegistry.js\";\n\n// Re-export I18nServiceApi from players-shared\nexport type { I18nServiceApi };\n\n/\n Theme provider interface\n \n Applies consistent accessibility theming across items and tools.\n /\nexport interface ThemeProviderApi {\n\t/\n\t Apply theme configuration\n\t /\n\tapplyTheme(config: ThemeConfig): void;\n\n\t/\n\t Get current theme configuration\n\t /\n\tgetCurrentTheme(): Required<ThemeConfig>;\n\n\t/\n\t Reset to default theme\n\t /\n\treset(): void;\n\n\t/\n\t Clean up and remove theme styles\n\t /\n\tdestroy(): void;\n}\n\n/\n Highlight coordinator interface\n \n Manages content highlighting for TTS, annotations, and selections.\n /\nexport interface HighlightCoordinatorApi {\n\t/\n\t Highlight a text range\n\t /\n\thighlightRange(\n\t\trange: Range,\n\t\ttype: HighlightType,\n\t\tcolor: HighlightColor,\n\t): void;\n\n\t/\n\t Highlight a word for TTS (temporary)\n\t /\n\thighlightTTSWord(\n\t\ttextNode: Text,\n\t\tstartOffset: number,\n\t\tendOffset: number,\n\t): void;\n\n\t/\n\t Highlight a single element as the active TTS word (temporary).\n\t \n\t Marks exactly the supplied element (via `data-pie-tts-word-element`)\n\t * without walking up to a containing ancestor. Used for atomic targets that\n\t * have no direct text node to range over — most notably MathJax CHTML tokens\n\t * (e.g. `<mjx-mi><mjx-c/></mjx-mi>`) and whole-expression fallbacks. Painting\n\t * the element itself is what lets a resolved math token highlight as a token\n\t * rather than escalating to the full `<math>` / `<mjx-container>`.\n\t \n\t Optional so lightweight coordinator mocks can omit it.\n\t /\n\thighlightTTSWordElement?(element: Element): void;\n\n\t/\n\t Highlight sentence(s) for TTS (background layer)\n\t /\n\thighlightTTSSentence(ranges: Range[]): void;\n\n\t/\n\t Highlight sentence/block element targets for TTS (background layer).\n\t \n\t Optional so lightweight coordinator mocks can omit it.\n\t /\n\thighlightTTSSentenceElements?(elements: Element[]): void;\n\n\t/\n\t Clear all TTS highlights (word and sentence)\n\t /\n\tclearTTS(): void;\n\n\t/\n\t Clear highlights of a specific type\n\t /\n\tclearHighlights(type: HighlightType): void;\n\n\t/\n\t Clear all highlights\n\t /\n\tclearAll(): void;\n\n\t/\n\t Check if highlighting is supported in current environment\n\t /\n\tisSupported(): boolean;\n\n\t/\n\t Update TTS highlight style dynamically\n\t /\n\tupdateTTSHighlightStyle(color: string, opacity: number): void;\n}\n\n/\n Tool state interface\n /\nexport interface ToolState {\n\tid: string;\n\tname: string;\n\tisVisible: boolean;\n\telement: HTMLElement \| null;\n\tlayer: ZIndexLayer;\n}\n\n/\n Tool coordinator interface\n \n Manages z-index layering and visibility for floating tools.\n /\nexport interface ToolCoordinatorApi {\n\t/\n\t Register a tool with the coordinator\n\t /\n\tregisterTool(\n\t\tid: string,\n\t\tname: string,\n\t\telement?: HTMLElement,\n\t\tlayer?: ZIndexLayer,\n\t): void;\n\n\t/\n\t Unregister a tool\n\t /\n\tunregisterTool(id: string): void;\n\n\t/\n\t Show a tool\n\t /\n\tshowTool(id: string): void;\n\n\t/\n\t Hide a tool\n\t /\n\thideTool(id: string): void;\n\n\t/\n\t Toggle tool visibility\n\t /\n\ttoggleTool(id: string): void;\n\n\t/\n\t Check if tool is visible\n\t /\n\tisToolVisible(id: string): boolean;\n\n\t/\n\t Bring an element to the front of its layer\n\t /\n\tbringToFront(element: HTMLElement): void;\n\n\t/\n\t Update the element reference for a tool\n\t /\n\tupdateToolElement(id: string, element: HTMLElement): void;\n\n\t/\n\t Get state for a specific tool\n\t /\n\tgetToolState(id: string): ToolState \| undefined;\n\n\t/\n\t Get all visible tools\n\t /\n\tgetVisibleTools(): ToolState[];\n\n\t/\n\t Subscribe to tool state changes\n\t /\n\tsubscribe(listener: () => void): () => void;\n}\n\n/\n TTS service interface\n \n Provides text-to-speech functionality with provider-based architecture.\n * Supports QTI 3.0 accessibility catalogs for pre-authored spoken content.\n /\nexport interface TtsServiceApi {\n\t/\n\t Initialize TTS with a provider\n\t /\n\tinitialize(\n\t\tprovider: ITTSProvider,\n\t\tconfig?: Partial<TTSConfig>,\n\t): Promise<void>;\n\n\t/\n\t Speak text with optional catalog support\n\t /\n\tspeak(\n\t\ttext: string,\n\t\toptions?: {\n\t\t\tcatalogId?: string;\n\t\t\tcatalogContext?: CatalogLookupContext;\n\t\t\tlanguage?: string;\n\t\t\tcontentElement?: Element;\n\t\t},\n\t): Promise<void>;\n\n\t/\n\t Speak a text range\n\t /\n\tspeakRange(\n\t\trange: Range,\n\t\toptions?: { contentRoot?: Element \| null },\n\t): Promise<void>;\n\n\t/\n\t Pause playback\n\t /\n\tpause(): void;\n\n\t/\n\t Resume playback\n\t /\n\tresume(): void;\n\n\t/\n\t Stop playback\n\t /\n\tstop(): void;\n\n\t/\n\t Request active TTS controls to hand off/deactivate their UI state.\n\t \n\t This is an orchestration hint for TTS tool chrome and does not replace\n\t * playback controls such as stop/pause/resume.\n\t /\n\trequestControlHandoff(): void;\n\n\t/\n\t Seek forward by sentence units\n\t /\n\tseekForward(units?: number): Promise<void>;\n\n\t/\n\t Seek backward by sentence units\n\t /\n\tseekBackward(units?: number): Promise<void>;\n\n\t/\n\t Check if currently playing\n\t /\n\tisPlaying(): boolean;\n\n\t/\n\t Check if paused\n\t /\n\tisPaused(): boolean;\n\n\t/\n\t Get current playback state\n\t /\n\tgetState(): PlaybackState;\n\n\t/\n\t Get currently speaking text\n\t /\n\tgetCurrentText(): string \| null;\n\n\t/\n\t Subscribe to state changes\n\t /\n\tonStateChange(id: string, callback: (state: PlaybackState) => void): void;\n\n\t/\n\t Unsubscribe from state changes\n\t /\n\toffStateChange(id: string, callback: (state: PlaybackState) => void): void;\n\n\t/\n\t Get capabilities of current provider\n\t /\n\tgetCapabilities(): TTSProviderCapabilities \| null;\n\n\t/\n\t Update TTS settings dynamically (rate, pitch, voice)\n\t /\n\tupdateSettings(settings: Partial<TTSConfig>): Promise<void>;\n\n\t/\n\t Update playback speed and apply it to active planned playback.\n\t /\n\tsetPlaybackRate(rate: number): Promise<void>;\n\n\t/\n\t Set highlight coordinator for word highlighting\n\t /\n\tsetHighlightCoordinator(coordinator: HighlightCoordinatorApi): void;\n\n\t/\n\t Set a late-bound provider for optional host TTS highlight target remapping.\n\t /\n\tsetHighlightTargetResolverProvider?(\n\t\tprovider: TTSHighlightTargetResolverProvider \| null,\n\t): () => void;\n\n\t/\n\t Set accessibility catalog resolver for spoken content\n\t /\n\tsetCatalogResolver(resolver: AccessibilityCatalogResolver): void;\n}\n\n/\n Accessibility catalog resolver interface\n \n Manages QTI 3.0 accessibility catalogs at assessment and item levels.\n * Provides lookup and resolution services for alternative content representations.\n /\nexport interface AccessibilityCatalogResolverApi {\n\t/\n\t Set the default language for fallback resolution\n\t /\n\tsetDefaultLanguage(language: string): void;\n\n\t/\n\t Get the default language\n\t /\n\tgetDefaultLanguage(): string;\n\n\t/\n\t Add item-level catalogs (called when rendering a new item)\n\t /\n\taddItemCatalogs(catalogs: any[]): void;\n\n\t/\n\t Register catalogs scoped to a mounted content owner.\n\t /\n\tregisterCatalogs?(context: CatalogOwnerContext, catalogs: any[]): () => void;\n\n\t/\n\t Clear item-level catalogs (called when leaving an item)\n\t /\n\tclearItemCatalogs(): void;\n\n\t/\n\t Check if a catalog exists\n\t /\n\thasCatalog(catalogId: string): boolean;\n\n\t/\n\t Get alternative content for a catalog identifier\n\t /\n\tgetAlternative(\n\t\tcatalogId: string,\n\t\toptions: CatalogLookupOptions,\n\t): ResolvedCatalog \| null;\n\n\t/\n\t Get all available alternatives for a catalog identifier\n\t /\n\tgetAllAlternatives(catalogId: string): ResolvedCatalog[];\n\n\t/\n\t Get all catalog identifiers available\n\t /\n\tgetAllCatalogIds(): string[];\n\n\t/\n\t Get statistics about available catalogs\n\t /\n\tgetStatistics(): CatalogStatistics;\n\n\t/\n\t Check if a specific catalog type is available\n\t /\n\thasAlternativeType(catalogId: string, type: CatalogType): boolean;\n\n\t/\n\t Get all catalog IDs that have a specific type of alternative\n\t /\n\tgetCatalogsByType(type: CatalogType): string[];\n\n\t/\n\t Reset all catalogs\n\t /\n\treset(): void;\n\n\t/\n\t Destroy and cleanup\n\t /\n\tdestroy(): void;\n}\n\n/\n Element tool state store interface\n \n Manages element-level ephemeral tool state using composite keys for global uniqueness.\n * Tool state is client-only and separate from PIE session data (which is sent to server for scoring).\n /\nexport interface ElementToolStateStoreApi {\n\t/\n\t Generate a globally unique element ID from components\n\t /\n\tgetGlobalElementId(\n\t\tassessmentId: string,\n\t\tsectionId: string,\n\t\titemId: string,\n\t\telementId: string,\n\t): string;\n\n\t/\n\t Parse a global element ID into its components\n\t /\n\tparseGlobalElementId(globalElementId: string): {\n\t\tassessmentId: string;\n\t\tsectionId: string;\n\t\titemId: string;\n\t\telementId: string;\n\t} \| null;\n\n\t/\n\t Set state for a specific tool on an element\n\t /\n\tsetState(globalElementId: string, toolId: string, state: any): void;\n\n\t/\n\t Get state for a specific tool on an element\n\t /\n\tgetState(globalElementId: string, toolId: string): any \| undefined;\n\n\t/\n\t Get all tool states for a specific element\n\t /\n\tgetElementState(globalElementId: string): Record<string, any>;\n\n\t/\n\t Get all element states\n\t /\n\tgetAllState(): Record<string, Record<string, any>>;\n\n\t/\n\t Subscribe to state changes\n\t /\n\tsubscribe(\n\t\tcallback: (state: Map<string, Map<string, any>>) => void,\n\t): () => void;\n\n\t/\n\t Set callback for persistence integration\n\t /\n\tsetOnStateChange(\n\t\tcallback: (state: Record<string, Record<string, any>>) => void,\n\t): void;\n\n\t/\n\t Load state from persistence\n\t /\n\tloadState(state: Record<string, Record<string, any>>): void;\n\n\t/\n\t Clear state for a specific element\n\t /\n\tclearElement(globalElementId: string): void;\n\n\t/\n\t Clear state for a specific tool across all elements\n\t /\n\tclearTool(toolId: string): void;\n\n\t/\n\t Clear all elements in a specific section\n\t /\n\tclearSection(assessmentId: string, sectionId: string): void;\n\n\t/\n\t Clear all state\n\t /\n\tclearAll(): void;\n}\n\n/\n Toolkit coordinator interface\n \n Orchestrates all toolkit services (TTS, tools, accessibility, state management) from a single entry point.\n * Provides centralized configuration for tool availability and settings.\n /\nexport interface ToolkitCoordinatorApi {\n\t/\n\t Assessment identifier\n\t /\n\treadonly assessmentId: string;\n\n\t/\n\t Configuration\n\t /\n\treadonly config: {\n\t\ttools?: {\n\t\t\tproviders?: Record<string, ToolProviderConfig \| undefined>;\n\t\t};\n\t};\n\n\t/\n\t TTS service\n\t /\n\treadonly ttsService: TtsServiceApi;\n\n\t/\n\t Tool coordinator\n\t /\n\treadonly toolCoordinator: ToolCoordinatorApi;\n\n\t/\n\t Highlight coordinator\n\t /\n\treadonly highlightCoordinator: HighlightCoordinatorApi;\n\n\t/\n\t Element tool state store\n\t /\n\treadonly elementToolStateStore: ElementToolStateStoreApi;\n\n\t/\n\t Catalog resolver\n\t /\n\treadonly catalogResolver: AccessibilityCatalogResolverApi;\n\n\t/\n\t Tool provider registry\n\t /\n\treadonly toolProviderRegistry: ToolProviderRegistry;\n\n\t/\n\t Get all services as a bundle\n\t /\n\tgetServiceBundle(): {\n\t\tttsService: TtsServiceApi;\n\t\ttoolCoordinator: ToolCoordinatorApi;\n\t\thighlightCoordinator: HighlightCoordinatorApi;\n\t\telementToolStateStore: ElementToolStateStoreApi;\n\t\tcatalogResolver: AccessibilityCatalogResolverApi;\n\t\ttoolProviderRegistry: ToolProviderRegistry;\n\t};\n\n\t/\n\t Ensure TTS service is initialized and ready.\n\t /\n\tensureTTSReady(config?: Record<string, unknown>): Promise<void>;\n\n\t/\n\t Ensure a provider is initialized and ready.\n\t /\n\tensureProviderReady(providerId: string): Promise<unknown>;\n\n\t/\n\t Wait until coordinator initialization is complete.\n\t /\n\twaitUntilReady(): Promise<void>;\n\n\t/\n\t Check if coordinator has completed initialization.\n\t /\n\tisReady(): boolean;\n\n\t/\n\t Read current initialization status.\n\t /\n\tgetInitStatus(): ToolkitInitStatus;\n\n\t/\n\t Check if a tool is enabled\n\t /\n\tisToolEnabled(toolId: string): boolean;\n\n\t/\n\t Get tool configuration\n\t /\n\tgetToolConfig(toolId: string): ToolProviderConfig \| null;\n\n\t/\n\t Update tool configuration\n\t /\n\tupdateToolConfig(toolId: string, updates: Partial<ToolProviderConfig>): void;\n\n\t/\n\t Update the enabled tool list for one placement level.\n\t /\n\tupdateToolPlacement(level: ToolPlacementLevel, toolIds: string[]): void;\n\n\t/\n\t Patch one or more placement levels in the canonical tools config.\n\t /\n\tupdateToolsPlacement(partial: ToolPlacementConfig): void;\n\n\t/\n\t Register or update lifecycle hooks at runtime.\n\t /\n\tsetHooks(hooks: ToolkitCoordinatorHooks): void;\n\n\t/\n\t Return a section controller if already created.\n\t /\n\tgetSectionController(args: {\n\t\tsectionId: string;\n\t\tattemptId?: string;\n\t}): SectionControllerHandle \| undefined;\n\n\t/\n\t Subscribe to section controller events.\n\t \n\t The listener is bound to the toolkit's active section cohort and\n\t * automatically migrates across cohort transitions\n\t * (`getOrCreateSectionController` for a different cohort). On every\n\t * migration the listener receives a snapshot replay of the new\n\t * cohort's already-loaded `content-loaded` events followed by the\n\t * aggregate `section-loading-complete`, in the canonical order a\n\t * fresh subscriber would have observed.\n\t \n\t Throws if no active section cohort exists; host code must call\n\t * `getOrCreateSectionController(...)` at least once before\n\t * subscribing. (`toolkit-ready` alone is not sufficient — it fires\n\t * once toolkit state has loaded but before any section controller\n\t * has been created.) The typical pattern is to subscribe once\n\t * immediately after the first `getOrCreateSectionController(...)`\n\t * resolves; the subscription then follows the active cohort across\n\t * all subsequent navigation without further wiring.\n\t \n\t Subscribing the same `listener` reference twice replaces the prior\n\t * subscription with the new one (filter args from the second call\n\t * win); calling the returned disposer twice is a no-op.\n\t \n\t A listener that throws is caught and `console.warn`-logged; the\n\t * throw does not interrupt fan-out to the remaining listeners.\n\t /\n\tsubscribeSectionEvents(args: SectionEventSubscriptionArgs): () => void;\n\n\t/\n\t Subscribe to item-scoped section controller events.\n\t \n\t Same active-cohort binding contract as {@link subscribeSectionEvents};\n\t * defaults `eventTypes` to the item-scoped subset.\n\t /\n\tsubscribeItemEvents(args: SectionItemEventSubscriptionArgs): () => void;\n\n\t/\n\t Subscribe to section-scoped lifecycle/loading/completion/error events.\n\t \n\t Same active-cohort binding contract as {@link subscribeSectionEvents};\n\t * defaults `eventTypes` to the section-scoped subset.\n\t /\n\tsubscribeSectionLifecycleEvents(\n\t\targs: SectionScopedEventSubscriptionArgs,\n\t): () => void;\n\n\t/\n\t Create or reuse a section controller with single-flight deduplication.\n\t /\n\tgetOrCreateSectionController(args: {\n\t\tsectionId: string;\n\t\tattemptId?: string;\n\t\tinput?: unknown;\n\t\tupdateExisting?: boolean;\n\t\tcreateDefaultController: () =>\n\t\t\t\| SectionControllerHandle\n\t\t\t\| Promise<SectionControllerHandle>;\n\t}): Promise<SectionControllerHandle>;\n\n\t/\n\t Dispose an existing section controller.\n\t /\n\tdisposeSectionController(args: {\n\t\tsectionId: string;\n\t\tattemptId?: string;\n\t\tpersistBeforeDispose?: boolean;\n\t\tclearPersistence?: boolean;\n\t}): Promise<void>;\n\n\t/\n\t Subscribe to framework-error events emitted by the coordinator.\n\t \n\t Mirrors the shape of {@link subscribeTelemetry} (see\n\t * `ToolkitCoordinator.subscribeTelemetry`): a synchronous,\n\t * multi-subscriber stream where each call to the internal bus's\n\t * `reportFrameworkError` fans out to every active listener exactly once.\n\t \n\t The returned function detaches the listener; calling it twice is a\n\t * no-op. A listener that throws is caught and logged; the throw does\n\t * not break fan-out to the remaining listeners.\n\t \n\t Use this to wire framework errors into Sentry / Datadog / a custom\n\t * banner without listening on a DOM event. The DOM event\n\t * (`framework-error`) and the canonical `onFrameworkError` prop on\n\t * `<pie-assessment-toolkit>` consume the same bus.\n\t /\n\tsubscribeFrameworkErrors(listener: FrameworkErrorListener): () => void;\n\n\t// ----------------------------------------------------------------\n\t// Tool Policy Engine — public surface (M8 PR 2 / PR 3).\n\t//\n\t// The coordinator owns a single `ToolPolicyEngine` instance and\n\t// exposes its decision and subscription surface through the API\n\t// so that toolbar custom elements (`pie-item-toolbar`,\n\t// `pie-section-toolbar`), the base section player, and bespoke\n\t// host instrumentation (PNP debugger, etc.) all flow through the\n\t// same engine. Hosts that want to drive PNP/profile inputs imperatively\n\t// (instead of binding props on `<pie-assessment-toolkit>`) call\n\t// `updateAssessment` / `updateCurrentItemRef` /\n\t// `setPnpEnforcement` directly.\n\t// ----------------------------------------------------------------\n\n\t/\n\t Resolve the visible tool set for a given placement level + scope.\n\t * Returns the engine's full decision (visible tools, diagnostics,\n\t * provenance). Hosts that only need the IDs may map\n\t * `decision.visibleTools` themselves.\n\t /\n\tdecideToolPolicy(request: ToolPolicyDecisionRequest): ToolPolicyDecision;\n\n\t/\n\t Subscribe to policy-engine change events. Fires whenever the\n\t * coordinator's bound policy inputs change (`updateToolConfig`,\n\t * `updateToolPlacement`, `updateAssessment`, `updateCurrentItemRef`,\n\t * `setPnpEnforcement`) or a custom `PolicySource` is registered /\n\t * removed. Listeners that need the new visible tool set should\n\t * call `decideToolPolicy(...)` with their level / scope.\n\t /\n\tonPolicyChange(listener: ToolPolicyChangeListener): () => void;\n\n\t/\n\t Bind (or clear) the active assessment for PNP/profile policy decisions.\n\t \n\t Under auto-mode (no host override via {@link setPnpEnforcement}),\n\t * the engine flips to `pnpEnforcement: \"on\"` iff the assessment\n\t * carries profile precedence material (`personalNeedsProfile`,\n\t * `settings.districtPolicy`, `settings.testAdministration`) or the\n\t * currently-bound item ref carries item-level profile inputs. A bare\n\t * assessment record (just `id` / `name`) keeps `\"off\"`.\n\t \n\t The host override set via {@link setPnpEnforcement} is sticky\n\t * across assessment swaps.\n\t /\n\tupdateAssessment(assessment: AssessmentEntity \| null): void;\n\n\t/\n\t Bind (or clear) the current item reference for policy decisions.\n\t * Used by item-level profile gates (item `requiredTools` /\n\t * `restrictedTools` / `toolParameters`). Item-level profile material\n\t * also feeds the auto-mode helper — navigating to an item with\n\t * profile settings can flip auto-mode to `\"on\"` even when the parent\n\t * assessment carries no profile block of its own.\n\t /\n\tupdateCurrentItemRef(itemRef: AssessmentItemRef \| null): void;\n\n\t/\n\t Override the auto-mode PNP/profile enforcement decision. Pass `\"on\"` /\n\t * `\"off\"` to pin the mode, or `null` to clear the override and\n\t * return to auto-mode (`\"on\"` iff the bound assessment / item ref\n\t * carries profile material, otherwise `\"off\"`).\n\t /\n\tsetPnpEnforcement(mode: PnpEnforcementMode \| null): void;\n\n\t/\n\t Read the engine inputs currently driving decisions. Useful for\n\t * debugging / instrumentation; do not mutate.\n\t /\n\tgetPolicyInputs(): Readonly<ResolvedEngineInputs>;\n\n\t/\n\t Register a custom `PolicySource`. The source participates in\n\t * every subsequent `decideToolPolicy(...)` call until disposed\n\t * (the returned function detaches).\n\t /\n\tregisterPolicySource(source: PolicySource): () => void;\n\n\t/\n\t Register a host-owned resolver for scoped tool render context.\n\t /\n\tregisterToolContextResolver(\n\t\ttoolId: string,\n\t\tresolver: ToolContextResolver,\n\t): () => void;\n\n\t/\n\t Replace all host-owned render-context resolvers.\n\t /\n\tsetToolContextResolvers(\n\t\tresolvers: ToolContextResolverMap \| null \| undefined,\n\t): void;\n\n\t/\n\t Whether a host resolver is registered for this tool.\n\t /\n\thasToolContextResolver(toolId: string): boolean;\n\n\t/\n\t Resolve render visibility/params for a tool that already survived policy gates.\n\t /\n\tresolveToolContext(\n\t\tcontext: ToolContextResolverContext,\n\t): ResolvedToolContext \| null;\n\n\t/\n\t Subscribe to resolver registration/removal changes.\n\t */\n\tonToolContextResolverChange(listener: () => void): () => void;\n}\n\n// I18nServiceApi is re-exported from @pie-players/pie-players-shared/i18n\n"]}

package/dist/services/tool-config-defaults.d.ts CHANGED Viewed

@@ -18,3 +18,14 @@ export declare const PACKAGED_TOOL_PLACEMENT: {
     readonly rubric: readonly ["textToSpeech", "highlighter", "annotationToolbar", "lineReader"];
     readonly element: readonly ["calculator", "answerEliminator", "textToSpeech", "ruler", "protractor", "highlighter", "annotationToolbar", "graph", "periodicTable"];
 };
+/**
+ * Opt-in section-player placement preset for hosts that want to expose every
+ * packaged tool once at its normal assessment surface. This is not exhaustive:
+ * `supportedLevels` still defines where tools can run, and hosts can still
+ * choose different placement for custom UX.
+ */
+export declare const SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT: {
+    section: string[];
+    item: string[];
+    passage: string[];
+};

package/dist/services/tool-config-defaults.js CHANGED Viewed

@@ -34,4 +34,22 @@ export const PACKAGED_TOOL_PLACEMENT = {
         "periodicTable",
     ],
 };
+/**
+ * Opt-in section-player placement preset for hosts that want to expose every
+ * packaged tool once at its normal assessment surface. This is not exhaustive:
+ * `supportedLevels` still defines where tools can run, and hosts can still
+ * choose different placement for custom UX.
+ */
+export const SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT = {
+    section: [
+        "theme",
+        "graph",
+        "periodicTable",
+        "lineReader",
+        "ruler",
+        "protractor",
+    ],
+    item: ["calculator", "textToSpeech", "answerEliminator", "annotationToolbar"],
+    passage: ["textToSpeech", "annotationToolbar"],
+};
 //# sourceMappingURL=tool-config-defaults.js.map

package/dist/services/tool-config-defaults.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"tool-config-defaults.js","sourceRoot":"","sources":["../../src/services/tool-config-defaults.ts"],"names":[],"mappings":"~~AAAA~~,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACrC,UAAU,EAAE,EAAE;IACd,OAAO,EAAE,EAAE;IACX,IAAI,EAAE,EAAE;IACR,OAAO,EAAE,EAAE;IACX,MAAM,EAAE,EAAE;IACV,OAAO,EAAE,EAAE;CACF,CAAC;AAEX;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACtC,UAAU,EAAE,CAAC,OAAO,CAAC;IACrB,OAAO,EAAE,CAAC,OAAO,CAAC;IAClB,IAAI,EAAE;QACL,cAAc;QACd,aAAa;QACb,mBAAmB;QACnB,OAAO;QACP,eAAe;KACf;IACD,OAAO,EAAE,CAAC,cAAc,EAAE,aAAa,EAAE,mBAAmB,EAAE,YAAY,CAAC;IAC3E,MAAM,EAAE,CAAC,cAAc,EAAE,aAAa,EAAE,mBAAmB,EAAE,YAAY,CAAC;IAC1E,OAAO,EAAE;QACR,YAAY;QACZ,kBAAkB;QAClB,cAAc;QACd,OAAO;QACP,YAAY;QACZ,aAAa;QACb,mBAAmB;QACnB,OAAO;QACP,eAAe;KACf;CACQ,CAAC","sourcesContent":["~~export~~ const DEFAULT_TOOL_PLACEMENT = {\n\tassessment: [],\n\tsection: [],\n\titem: [],\n\tpassage: [],\n\trubric: [],\n\telement: [],\n} as const;\n\n/*\n Complete placement preset for hosts that want to enable all packaged tools.\n * Prefer explicit host configuration over implicit defaults.\n */\nexport const PACKAGED_TOOL_PLACEMENT = {\n\tassessment: [\"theme\"],\n\tsection: [\"theme\"],\n\titem: [\n\t\t\"textToSpeech\",\n\t\t\"highlighter\",\n\t\t\"annotationToolbar\",\n\t\t\"graph\",\n\t\t\"periodicTable\",\n\t],\n\tpassage: [\"textToSpeech\", \"highlighter\", \"annotationToolbar\", \"lineReader\"],\n\trubric: [\"textToSpeech\", \"highlighter\", \"annotationToolbar\", \"lineReader\"],\n\telement: [\n\t\t\"calculator\",\n\t\t\"answerEliminator\",\n\t\t\"textToSpeech\",\n\t\t\"ruler\",\n\t\t\"protractor\",\n\t\t\"highlighter\",\n\t\t\"annotationToolbar\",\n\t\t\"graph\",\n\t\t\"periodicTable\",\n\t],\n} as const;\n"]}
1	+ {"version":3,"file":"tool-config-defaults.js","sourceRoot":"","sources":["../../src/services/tool-config-defaults.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACrC,UAAU,EAAE,EAAE;IACd,OAAO,EAAE,EAAE;IACX,IAAI,EAAE,EAAE;IACR,OAAO,EAAE,EAAE;IACX,MAAM,EAAE,EAAE;IACV,OAAO,EAAE,EAAE;CACF,CAAC;AAEX;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACtC,UAAU,EAAE,CAAC,OAAO,CAAC;IACrB,OAAO,EAAE,CAAC,OAAO,CAAC;IAClB,IAAI,EAAE;QACL,cAAc;QACd,aAAa;QACb,mBAAmB;QACnB,OAAO;QACP,eAAe;KACf;IACD,OAAO,EAAE,CAAC,cAAc,EAAE,aAAa,EAAE,mBAAmB,EAAE,YAAY,CAAC;IAC3E,MAAM,EAAE,CAAC,cAAc,EAAE,aAAa,EAAE,mBAAmB,EAAE,YAAY,CAAC;IAC1E,OAAO,EAAE;QACR,YAAY;QACZ,kBAAkB;QAClB,cAAc;QACd,OAAO;QACP,YAAY;QACZ,aAAa;QACb,mBAAmB;QACnB,OAAO;QACP,eAAe;KACf;CACQ,CAAC;AAEX;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uCAAuC,GAAG;IACtD,OAAO,EAAE;QACR,OAAO;QACP,OAAO;QACP,eAAe;QACf,YAAY;QACZ,OAAO;QACP,YAAY;KACZ;IACD,IAAI,EAAE,CAAC,YAAY,EAAE,cAAc,EAAE,kBAAkB,EAAE,mBAAmB,CAAC;IAC7E,OAAO,EAAE,CAAC,cAAc,EAAE,mBAAmB,CAAC;CAChB,CAAC","sourcesContent":["import type { ToolPlacementConfig } from \"./tools-config-normalizer.js\";\n\nexport const DEFAULT_TOOL_PLACEMENT = {\n\tassessment: [],\n\tsection: [],\n\titem: [],\n\tpassage: [],\n\trubric: [],\n\telement: [],\n} as const;\n\n/*\n Complete placement preset for hosts that want to enable all packaged tools.\n * Prefer explicit host configuration over implicit defaults.\n /\nexport const PACKAGED_TOOL_PLACEMENT = {\n\tassessment: [\"theme\"],\n\tsection: [\"theme\"],\n\titem: [\n\t\t\"textToSpeech\",\n\t\t\"highlighter\",\n\t\t\"annotationToolbar\",\n\t\t\"graph\",\n\t\t\"periodicTable\",\n\t],\n\tpassage: [\"textToSpeech\", \"highlighter\", \"annotationToolbar\", \"lineReader\"],\n\trubric: [\"textToSpeech\", \"highlighter\", \"annotationToolbar\", \"lineReader\"],\n\telement: [\n\t\t\"calculator\",\n\t\t\"answerEliminator\",\n\t\t\"textToSpeech\",\n\t\t\"ruler\",\n\t\t\"protractor\",\n\t\t\"highlighter\",\n\t\t\"annotationToolbar\",\n\t\t\"graph\",\n\t\t\"periodicTable\",\n\t],\n} as const;\n\n/\n Opt-in section-player placement preset for hosts that want to expose every\n * packaged tool once at its normal assessment surface. This is not exhaustive:\n * `supportedLevels` still defines where tools can run, and hosts can still\n * choose different placement for custom UX.\n */\nexport const SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT = {\n\tsection: [\n\t\t\"theme\",\n\t\t\"graph\",\n\t\t\"periodicTable\",\n\t\t\"lineReader\",\n\t\t\"ruler\",\n\t\t\"protractor\",\n\t],\n\titem: [\"calculator\", \"textToSpeech\", \"answerEliminator\", \"annotationToolbar\"],\n\tpassage: [\"textToSpeech\", \"annotationToolbar\"],\n} satisfies ToolPlacementConfig;\n"]}

package/dist/services/tts/highlight-target-resolver.d.ts ADDED Viewed

@@ -0,0 +1,17 @@
+export interface TTSHighlightContext {
+    scopeElement?: HTMLElement | null;
+    itemId?: string;
+    canonicalItemId?: string;
+    kind?: string;
+    contentKind?: string;
+    regionPolicy?: string;
+}
+export interface TTSHighlightTargetResolver {
+    resolveWordRange?(range: Range, context: TTSHighlightContext): Range | null | undefined;
+    resolveSentenceRanges?(ranges: Range[], context: TTSHighlightContext): Array<Range | HTMLElement> | null | undefined;
+}
+export interface TTSHighlightTargetResolverRuntime {
+    context: TTSHighlightContext;
+    resolver?: TTSHighlightTargetResolver | null;
+}
+export type TTSHighlightTargetResolverProvider = () => TTSHighlightTargetResolverRuntime | null | undefined;

package/dist/services/tts/highlight-target-resolver.js ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ export {};
2	+ //# sourceMappingURL=highlight-target-resolver.js.map

package/dist/services/tts/highlight-target-resolver.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"highlight-target-resolver.js","sourceRoot":"","sources":["../../../src/services/tts/highlight-target-resolver.ts"],"names":[],"mappings":"","sourcesContent":["export interface TTSHighlightContext {\n\tscopeElement?: HTMLElement | null;\n\titemId?: string;\n\tcanonicalItemId?: string;\n\tkind?: string;\n\tcontentKind?: string;\n\tregionPolicy?: string;\n}\n\nexport interface TTSHighlightTargetResolver {\n\tresolveWordRange?(\n\t\trange: Range,\n\t\tcontext: TTSHighlightContext,\n\t): Range | null | undefined;\n\tresolveSentenceRanges?(\n\t\tranges: Range[],\n\t\tcontext: TTSHighlightContext,\n\t): Array<Range | HTMLElement> | null | undefined;\n}\n\nexport interface TTSHighlightTargetResolverRuntime {\n\tcontext: TTSHighlightContext;\n\tresolver?: TTSHighlightTargetResolver | null;\n}\n\nexport type TTSHighlightTargetResolverProvider =\n\t() => TTSHighlightTargetResolverRuntime | null | undefined;\n"]}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/pie-assessment-toolkit",
-	"version": "0.3.51",
+	"version": "0.3.52",
 	"type": "module",
 	"description": "PIE assessment toolkit: composable services + reference implementation for assessment players and tool coordination",
 	"license": "MIT",
@@ -75,15 +75,15 @@
 		"test": "bun test"
 	},
 	"dependencies": {
-		"@pie-players/pie-calculator": "0.3.51",
-		"@pie-players/pie-context": "0.3.51",
-		"@pie-players/pie-players-shared": "0.3.51",
-		"@pie-players/pie-tts": "0.3.51",
+		"@pie-players/pie-calculator": "0.3.52",
+		"@pie-players/pie-context": "0.3.52",
+		"@pie-players/pie-players-shared": "0.3.52",
+		"@pie-players/pie-tts": "0.3.52",
 		"speech-rule-engine": "^5.0.0-rc.1"
 	},
 	"peerDependencies": {
-		"@pie-players/pie-calculator-desmos": "0.3.51",
-		"@pie-players/tts-client-server": "0.3.51"
+		"@pie-players/pie-calculator-desmos": "0.3.52",
+		"@pie-players/tts-client-server": "0.3.52"
 	},
 	"peerDependenciesMeta": {
 		"@pie-players/pie-calculator-desmos": {