@pie-players/pie-assessment-toolkit 1.0.0-beta.0 → 1.0.0-beta.10

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 (145) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +21 -8
  3. package/custom-elements.json +51 -23
  4. package/dist/attempt/AssessmentSession.d.ts +7 -0
  5. package/dist/attempt/AssessmentSession.js +14 -0
  6. package/dist/attempt/TestSession.d.ts +7 -0
  7. package/dist/attempt/TestSession.js +3 -0
  8. package/dist/components/ItemScope.custom-element.js +1 -1
  9. package/dist/components/ItemToolBar.custom-element.js +1 -1
  10. package/dist/components/PieAssessmentToolkit.custom-element.js +45 -45
  11. package/dist/components/SectionToolBar.custom-element.js +1 -1
  12. package/dist/components/THIRD-PARTY-LICENSES.txt +42 -0
  13. package/dist/components/chunks/ItemToolBar-8qpnhyg4.js +40 -0
  14. package/dist/components/chunks/ItemToolBar-bsww9e8f.js +4 -0
  15. package/dist/components/chunks/ItemToolBar-eg8jarh0.js +2 -0
  16. package/dist/components/chunks/{ItemToolBar-66hcwmfw.js → ItemToolBar-gsb96731.js} +2 -2
  17. package/dist/components/chunks/ItemToolBar-na4e5vwt.js +2 -0
  18. package/dist/components/chunks/{ItemToolBar-kkj69ptr.js → ItemToolBar-wcw4yxjy.js} +1 -1
  19. package/dist/components/chunks/sre-engine-wazxma67.js +1 -0
  20. package/dist/components/element-contracts.d.ts +115 -0
  21. package/dist/components/element-contracts.js +1 -0
  22. package/dist/components/item-scope-element.d.ts +1 -1
  23. package/dist/components/item-scope-element.js +0 -1
  24. package/dist/components/item-toolbar-element.d.ts +1 -1
  25. package/dist/components/item-toolbar-element.js +0 -1
  26. package/dist/components/pie-assessment-toolkit-element.d.ts +1 -1
  27. package/dist/components/pie-assessment-toolkit-element.js +0 -1
  28. package/dist/components/section-toolbar-element.d.ts +1 -1
  29. package/dist/components/section-toolbar-element.js +0 -1
  30. package/dist/context/assessment-toolkit-context.d.ts +15 -1
  31. package/dist/index.d.ts +3 -3
  32. package/dist/index.js +2 -2
  33. package/dist/policy/core/ToolPolicyEngine.d.ts +8 -0
  34. package/dist/policy/core/ToolPolicyEngine.js +4 -2
  35. package/dist/policy/core/compose-decision.js +31 -0
  36. package/dist/policy/core/decision-types.d.ts +30 -5
  37. package/dist/policy/core/feature-decision.d.ts +11 -4
  38. package/dist/policy/core/feature-decision.js +9 -2
  39. package/dist/policy/core/pnp-policy-inputs.js +6 -2
  40. package/dist/policy/core/provenance.d.ts +1 -1
  41. package/dist/policy/core/tool-parameters.js +17 -5
  42. package/dist/policy/engine.d.ts +2 -1
  43. package/dist/policy/sources/PnpPolicySource.d.ts +48 -4
  44. package/dist/policy/sources/PnpPolicySource.js +107 -12
  45. package/dist/runtime/SectionControllerBinding.js +14 -6
  46. package/dist/runtime/content-language.js +31 -5
  47. package/dist/runtime/core/engine-resolver.d.ts +17 -0
  48. package/dist/runtime/item-feature-decisions.js +115 -0
  49. package/dist/runtime/registration-events.d.ts +31 -4
  50. package/dist/runtime/registration-events.js +20 -1
  51. package/dist/runtime/shell-event-bridge.d.ts +7 -1
  52. package/dist/runtime/shell-event-bridge.js +44 -1
  53. package/dist/runtime/shell-scope.d.ts +2 -2
  54. package/dist/runtime/shell-scope.js +14 -5
  55. package/dist/services/AccessibilityCatalogResolver.js +9 -5
  56. package/dist/services/HighlightCoordinator.js +54 -47
  57. package/dist/services/SSMLExtractor.js +8 -23
  58. package/dist/services/TTSService.d.ts +10 -7
  59. package/dist/services/TTSService.js +43 -17
  60. package/dist/services/ToolRegistry.d.ts +17 -8
  61. package/dist/services/ToolRegistry.js +10 -5
  62. package/dist/services/ToolkitCoordinator.d.ts +21 -47
  63. package/dist/services/ToolkitCoordinator.js +74 -289
  64. package/dist/services/interfaces.d.ts +14 -0
  65. package/dist/services/section-controller-types.d.ts +71 -20
  66. package/dist/services/support-conflicts.js +11 -0
  67. package/dist/services/tool-config-validation.d.ts +1 -1
  68. package/dist/services/tool-config-validation.js +8 -2
  69. package/dist/services/tool-context.d.ts +33 -2
  70. package/dist/services/tool-context.js +163 -60
  71. package/dist/services/tool-icons.js +3 -0
  72. package/dist/services/tool-provider-defaults.js +20 -0
  73. package/dist/services/tool-providers/TTSToolProvider.d.ts +16 -1
  74. package/dist/services/tool-providers/TTSToolProvider.js +50 -32
  75. package/dist/services/toolbar-decided-tools.js +1 -0
  76. package/dist/services/toolbar-items.d.ts +1 -1
  77. package/dist/services/tts/browser-provider.js +12 -3
  78. package/dist/services/tts/math-control-names.js +42 -2
  79. package/dist/services/tts/tts-lifecycle.d.ts +142 -0
  80. package/dist/services/tts/tts-lifecycle.js +341 -0
  81. package/dist/tools/content-surfaces.d.ts +35 -0
  82. package/dist/tools/content-surfaces.js +35 -0
  83. package/dist/tools/registration.d.ts +4 -2
  84. package/dist/tools/registration.js +6 -1
  85. package/package.json +31 -23
  86. package/dist/components/chunks/ItemToolBar-3zrc4p3d.js +0 -4
  87. package/dist/components/chunks/ItemToolBar-9gqhfxtn.js +0 -40
  88. package/dist/components/chunks/ItemToolBar-hzc5wyjp.js +0 -2
  89. package/dist/components/chunks/ItemToolBar-vdkyn9f3.js +0 -2
  90. package/dist/components/chunks/sre-engine-bj997w4b.js +0 -1
  91. package/dist/policy/core/compose-decision.d.ts +0 -58
  92. package/dist/policy/core/pnp-policy-inputs.d.ts +0 -59
  93. package/dist/policy/core/tool-parameters.d.ts +0 -11
  94. package/dist/runtime/RuntimeRegistry.d.ts +0 -12
  95. package/dist/runtime/SectionControllerBinding.d.ts +0 -283
  96. package/dist/runtime/adapter/SectionEngineAdapter.d.ts +0 -82
  97. package/dist/runtime/adapter/dom-event-bridge.d.ts +0 -47
  98. package/dist/runtime/composition-emit-scheduler.d.ts +0 -72
  99. package/dist/runtime/content-language.d.ts +0 -32
  100. package/dist/runtime/content-registration.d.ts +0 -13
  101. package/dist/runtime/core/SectionEngineCore.d.ts +0 -49
  102. package/dist/runtime/core/engine-transition.d.ts +0 -43
  103. package/dist/runtime/page-warnings.d.ts +0 -13
  104. package/dist/runtime/policy-input-forwarding.d.ts +0 -25
  105. package/dist/runtime/runtime-event-claim.d.ts +0 -8
  106. package/dist/runtime/runtime-id.d.ts +0 -7
  107. package/dist/runtime/session-event-emitter-policy.d.ts +0 -11
  108. package/dist/runtime/shell-registration.d.ts +0 -73
  109. package/dist/runtime/unclaimed-registration-watch.d.ts +0 -7
  110. package/dist/services/section-session-assignment.d.ts +0 -21
  111. package/dist/services/spoken-audio-cards.d.ts +0 -50
  112. package/dist/services/tool-config-defaults.d.ts +0 -15
  113. package/dist/services/toolbar-decided-tools.d.ts +0 -16
  114. package/dist/services/tts/catalog-span-alignment.d.ts +0 -24
  115. package/dist/services/tts/generated-speech/assemble-plan.d.ts +0 -35
  116. package/dist/services/tts/generated-speech/dom/build-dom-plan.d.ts +0 -27
  117. package/dist/services/tts/generated-speech/dom/to-chunk-inputs.d.ts +0 -19
  118. package/dist/services/tts/generated-speech/dom/types.d.ts +0 -37
  119. package/dist/services/tts/generated-speech/index.d.ts +0 -17
  120. package/dist/services/tts/generated-speech/math-speech-cache.d.ts +0 -17
  121. package/dist/services/tts/generated-speech/types.d.ts +0 -92
  122. package/dist/services/tts/highlight-pipeline/boundary-normalizer.d.ts +0 -2
  123. package/dist/services/tts/highlight-pipeline/create-highlight-plan.d.ts +0 -6
  124. package/dist/services/tts/highlight-pipeline/highlight-policy.d.ts +0 -2
  125. package/dist/services/tts/highlight-pipeline/index.d.ts +0 -9
  126. package/dist/services/tts/highlight-pipeline/math-semantic-resolver.d.ts +0 -3
  127. package/dist/services/tts/highlight-pipeline/normalize-speech-chunks.d.ts +0 -29
  128. package/dist/services/tts/highlight-pipeline/prose-boundary-resolver.d.ts +0 -2
  129. package/dist/services/tts/highlight-pipeline/readable-region.d.ts +0 -1
  130. package/dist/services/tts/highlight-pipeline/rendered-math-target-resolver.d.ts +0 -6
  131. package/dist/services/tts/highlight-pipeline/types.d.ts +0 -77
  132. package/dist/services/tts/highlight-pipeline/visible-map-range.d.ts +0 -14
  133. package/dist/services/tts/math-alignment/index.d.ts +0 -25
  134. package/dist/services/tts/math-alignment/mathml-tokenizer.d.ts +0 -2
  135. package/dist/services/tts/math-alignment/range-resolver.d.ts +0 -10
  136. package/dist/services/tts/math-alignment/sequence-aligner.d.ts +0 -7
  137. package/dist/services/tts/math-alignment/speech-tokenizer.d.ts +0 -39
  138. package/dist/services/tts/math-alignment/types.d.ts +0 -60
  139. package/dist/services/tts/math-control-names.d.ts +0 -21
  140. package/dist/services/tts/mathml-sanitization.d.ts +0 -8
  141. package/dist/services/tts/sre-engine.d.ts +0 -7
  142. package/dist/services/tts/sre-locales.d.ts +0 -14
  143. package/dist/services/tts/ssml/spoken-text.d.ts +0 -9
  144. package/dist/services/tts/text-segmentation.d.ts +0 -21
  145. package/dist/utils/structural-equality.d.ts +0 -11
@@ -12,6 +12,7 @@
12
12
  * warnings and the toolbar and surface render helpers.
13
13
  */
14
14
  import { dynamicMessageKey } from "@pie-players/pie-players-shared/i18n/provider";
15
+ import { settleAll } from "@pie-players/pie-players-shared/promise";
15
16
  import { resolveToolTag, } from "../tools/tool-tag-map.js";
16
17
  import { PENDING_INPUT_WARNING_DELAY_MS, warnOncePerDocument, } from "../runtime/page-warnings.js";
17
18
  const logToolCallbackFailure = (toolId, phase, error) => console.error(`[ToolRegistry] Tool '${toolId}' ${phase} check threw:`, error);
@@ -381,8 +382,10 @@ export class ToolRegistry {
381
382
  * @param contexts - Every context the tool could act on at this placement
382
383
  * @param onFailure - Receives the gate's throw; the tool then counts as
383
384
  * applicable. Logs when omitted.
385
+ * @param config - The tool's `tools.providers.<toolId>` entry, passed to the
386
+ * gate
384
387
  */
385
- isApplicableToAnyContext(toolId, contexts, onFailure = logToolCallbackFailure) {
388
+ isApplicableToAnyContext(toolId, contexts, onFailure = logToolCallbackFailure, config) {
386
389
  const tool = this.get(toolId);
387
390
  if (!tool?.isApplicableToContent)
388
391
  return true;
@@ -390,7 +393,7 @@ export class ToolRegistry {
390
393
  return true;
391
394
  return contexts.some((context) => {
392
395
  try {
393
- return tool.isApplicableToContent?.(context) ?? true;
396
+ return tool.isApplicableToContent?.(context, config) ?? true;
394
397
  }
395
398
  catch (error) {
396
399
  onFailure(toolId, "tool-applicability", error);
@@ -418,8 +421,10 @@ export class ToolRegistry {
418
421
  * @param contexts - Every context the tools could act on at that surface
419
422
  * @param onFailure - Receives a relevance or applicability check's throw.
420
423
  * Logs when omitted.
424
+ * @param getToolConfig - A tool's `tools.providers.<toolId>` entry, which
425
+ * applicability receives; a toolkit coordinator's `getToolConfig`
421
426
  */
422
- filterDecidedToolIds(entries, level, contexts, onFailure = logToolCallbackFailure) {
427
+ filterDecidedToolIds(entries, level, contexts, onFailure = logToolCallbackFailure, getToolConfig) {
423
428
  const granted = new Set();
424
429
  const decided = [];
425
430
  for (const entry of entries) {
@@ -446,7 +451,7 @@ export class ToolRegistry {
446
451
  }
447
452
  }
448
453
  return decided.filter((toolId) => relevant.has(toolId) &&
449
- this.isApplicableToAnyContext(toolId, contexts, onFailure));
454
+ this.isApplicableToAnyContext(toolId, contexts, onFailure, getToolConfig?.(toolId) ?? undefined));
450
455
  }
451
456
  /**
452
457
  * Plain metadata for every registration, in registration order, for UIs
@@ -608,7 +613,7 @@ export class ToolRegistry {
608
613
  * tools loaded and usable. A failed tool is retried on the next call.
609
614
  */
610
615
  async ensureToolModulesLoaded(toolIds) {
611
- const results = await Promise.allSettled(toolIds.map((toolId) => this.ensureToolModuleLoaded(toolId)));
616
+ const results = await settleAll(toolIds.map((toolId) => this.ensureToolModuleLoaded(toolId)));
612
617
  const failures = new Map();
613
618
  results.forEach((result, index) => {
614
619
  if (result.status === "rejected")
@@ -22,6 +22,7 @@
22
22
  * - config-change application and TTS reconfiguration, last.
23
23
  */
24
24
  import type { AccessibilityCatalog, AssessmentEntity, ItemSettings, ToolParametersFor } from "@pie-players/pie-players-shared/types";
25
+ import type { FeatureDecisionAppliedDetail } from "@pie-players/pie-context";
25
26
  import { type CanonicalToolsConfig, type ToolPlacementConfig, type ToolPolicyConfig, type TextToSpeechToolProviderConfig, type ToolProviderConfig, type ToolProvidersConfig, type ToolsConfigInput } from "./tools-config-normalizer.js";
26
27
  import { type ToolConfigStrictness } from "./tool-config-validation.js";
27
28
  import { AccessibilityCatalogResolver } from "./AccessibilityCatalogResolver.js";
@@ -34,13 +35,14 @@ import type { ToolCoordinatorApi } from "./interfaces.js";
34
35
  import { TTSService } from "./TTSService.js";
35
36
  import { ToolProviderRegistry } from "./tool-providers/index.js";
36
37
  import type { ToolProviderApi } from "./tool-providers/ToolProviderApi.js";
38
+ import { TTS_TOOL_ID } from "./tts/tts-lifecycle.js";
37
39
  import { ToolRegistry } from "./ToolRegistry.js";
38
40
  import type { ResolvedToolContext, ToolContextResolverContext, ToolContextResolverMap } from "./ToolRegistry.js";
39
41
  import type { ToolFailurePhase } from "./tool-failure.js";
40
42
  import type { ToolOpenRequest, ToolRequestTarget } from "./tool-request.js";
41
43
  import { type FeaturePolicyDecision, type PnpEnforcementMode, type PolicySource, type ResolvedEngineInputs, type ToolPolicyChangeListener, type ToolPolicyDecision, type ToolPolicyDecisionRequest, type ToolPolicyDiagnostic, type ToolScope } from "../policy/engine.js";
42
44
  import type { SectionControllerContext, SectionControllerEvent, SectionControllerEventType, SectionControllerFactoryDefaults, SectionControllerHandle, SectionControllerKey, SectionControllerSessionState, SectionSessionPersistenceStrategy, SectionPersistenceFactoryDefaults } from "./section-controller-types.js";
43
- export type { SectionControllerContext, SectionControllerEvent, SectionControllerEventType, SectionControllerFactoryDefaults, SectionControllerHandle, SectionControllerKey, SectionControllerLoadedRenderable, SectionSessionPersistenceConfig, SectionSessionPersistenceStrategy, SectionControllerRuntimeState, SectionControllerSessionState, SectionPersistenceFactoryDefaults, } from "./section-controller-types.js";
45
+ export type { SectionControllerContext, SectionControllerEvent, SectionControllerEventType, SectionControllerFactoryDefaults, SectionControllerHandle, SectionControllerKey, SectionItemScore, SectionItemScorer, SectionScore, SectionControllerLoadedRenderable, SectionSessionPersistenceConfig, SectionSessionPersistenceStrategy, SectionControllerRuntimeState, SectionControllerSessionState, SectionPersistenceFactoryDefaults, } from "./section-controller-types.js";
44
46
  export type { FeaturePolicyDecision, PnpEnforcementMode, ResolvedEngineInputs, ToolPolicyChangeListener, ToolPolicyDecision, ToolPolicyDecisionRequest, } from "../policy/engine.js";
45
47
  export interface ToolkitToolsConfig extends CanonicalToolsConfig {
46
48
  policy: ToolPolicyConfig;
@@ -290,11 +292,7 @@ export declare class ToolkitCoordinator {
290
292
  readonly hooks: ToolkitCoordinatorHooks;
291
293
  readonly lazyInit: boolean;
292
294
  /** Track TTS initialization state */
293
- private ttsInitialized;
294
- /** Text-to-speech failed to start and policy does not grant it. */
295
- private ttsDegraded;
296
- private ttsInitPromise?;
297
- private ttsReconfigurePromise?;
295
+ private tts;
298
296
  /**
299
297
  * The loader ran, whether or not it returned state. A failed load is
300
298
  * reported once and the coordinator runs without saved tool state.
@@ -397,18 +395,6 @@ export declare class ToolkitCoordinator {
397
395
  * lifetime for no new information.
398
396
  */
399
397
  private reportedUnboundFeaturePolicy;
400
- /**
401
- * Whether {@link _initializeTTS} has already reported a non-browser backend
402
- * falling back to browser speech because no text-to-speech provider is registered.
403
- * Once per coordinator: a text-to-speech config change re-runs
404
- * initialization, and the missing provider is the same gap each time.
405
- */
406
- private reportedMissingTTSProvider;
407
- /**
408
- * The backend of a fallback {@link reportMissingTTSProvider} held back while
409
- * the registry was unsettled, reported if the bound toolkit has no registry.
410
- */
411
- private heldMissingTTSProviderBackend;
412
398
  /**
413
399
  * Whether {@link validateToolsConfig} has already reported validating with
414
400
  * no registry (`tools.registryUnavailable`). Once per coordinator: every
@@ -527,7 +513,6 @@ export declare class ToolkitCoordinator {
527
513
  private ensureStateLoaded;
528
514
  /** Whether the toolkit this coordinator binds to may still supply a registry. */
529
515
  private toolRegistryPending;
530
- private reportMissingTTSProvider;
531
516
  /**
532
517
  * Take the registry of the toolkit this coordinator is bound to, when the host
533
518
  * constructed it without one: the config is validated against it, its
@@ -693,27 +678,13 @@ export declare class ToolkitCoordinator {
693
678
  private disposeOwnedResources;
694
679
  private waitForAdmittedInitialization;
695
680
  /**
696
- * Initialize the TTS service from the `textToSpeech` tool config.
681
+ * Initialize the TTS service from the `textToSpeech` tool config. The
682
+ * lifecycle itself lives in `services/tts/tts-lifecycle.ts`; the coordinator
683
+ * keeps the public method hosts call.
697
684
  */
698
685
  ensureTTSReady(): Promise<void>;
699
- private waitForPendingTTSReconfigure;
700
- private _initializeTTS;
701
- private resolveTTSToolConfig;
702
- private initializeTTSService;
703
686
  waitUntilReady(): Promise<void>;
704
687
  isReady(): boolean;
705
- /**
706
- * Readiness waits for text-to-speech when it is enabled and either starts
707
- * eagerly or is granted: a granted read-aloud fails before the learner starts.
708
- */
709
- private ttsRequiredForReadiness;
710
- /**
711
- * Starts text-to-speech for readiness. A failure policy does not grant leaves
712
- * the tool degraded, reporting itself unavailable, and readiness settles; a
713
- * granted tool's failure rejects.
714
- */
715
- private startTTSForReadiness;
716
- private getTTSConfigFromProviders;
717
688
  private assertCanonicalToolId;
718
689
  private installToolContextResolvers;
719
690
  /**
@@ -724,14 +695,17 @@ export declare class ToolkitCoordinator {
724
695
  setToolContextResolvers(resolvers: ToolContextResolverMap | null | undefined): void;
725
696
  private notifyToolContextResolverChange;
726
697
  /**
727
- * Get tool configuration, or null if the tool is not configured.
698
+ * Get tool configuration, or null if the tool is not configured. The
699
+ * read-aloud overload takes its literal from `TTS_TOOL_ID` (the same type the
700
+ * runtime compares against), so the capability id is named once, where the
701
+ * capability lives.
728
702
  */
729
- getToolConfig(toolId: "textToSpeech"): TextToSpeechToolProviderConfig | null;
703
+ getToolConfig(toolId: typeof TTS_TOOL_ID): TextToSpeechToolProviderConfig | null;
730
704
  getToolConfig(toolId: string): ToolProviderConfig | null;
731
705
  /**
732
706
  * Update tool configuration and apply the change to the underlying services.
733
707
  */
734
- updateToolConfig(toolId: "textToSpeech", updates: Partial<TextToSpeechToolProviderConfig>): void;
708
+ updateToolConfig(toolId: typeof TTS_TOOL_ID, updates: Partial<TextToSpeechToolProviderConfig>): void;
735
709
  updateToolConfig(toolId: string, updates: Partial<ToolProviderConfig>): void;
736
710
  /**
737
711
  * Patch one or more placement levels in the canonical tools config.
@@ -789,6 +763,14 @@ export declare class ToolkitCoordinator {
789
763
  * registered settings ({@link registerItemSettings}).
790
764
  */
791
765
  decideFeaturePolicy<K extends string>(featureId: K, scope?: ToolScope): FeaturePolicyDecision<ToolParametersFor<K>>;
766
+ /**
767
+ * Hear that an item player applied a feature decision to its item's models.
768
+ * A `support-conflict` hold that displaced the player's attribute or the
769
+ * item's authored setting raises `tool-policy.supportConflict`, as a
770
+ * conflict that displaced a granting rule already did when it was decided.
771
+ * Every other block was recorded by a person and raises nothing.
772
+ */
773
+ reportFeatureDecisionApplied(detail: FeatureDecisionAppliedDetail, scope: ToolScope): void;
792
774
  /**
793
775
  * Subscribe to policy-engine change events. Fires whenever the
794
776
  * coordinator's bound inputs change (`updateToolConfig`,
@@ -890,12 +872,4 @@ export declare class ToolkitCoordinator {
890
872
  * so a check on the policy change the update dispatched finds the new provider.
891
873
  */
892
874
  private _registerChangedToolProvider;
893
- /**
894
- * Re-register the text-to-speech provider for the current config and registry, then
895
- * re-initialize unless initialization is lazy. An initialization already
896
- * running finishes first: it would otherwise mark its provider ready after
897
- * the reset.
898
- */
899
- private scheduleTTSReconfigure;
900
- private _reconfigureTTSProvider;
901
875
  }