@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
@@ -1,2 +1 @@
1
1
  import "./SectionToolBar.custom-element.js";
2
- export {};
@@ -29,7 +29,7 @@ export interface AssessmentToolkitRuntimeContext {
29
29
  attemptId?: string;
30
30
  itemPlayer: ItemPlayerConfig;
31
31
  /**
32
- * Opt-in flag: context consumers render the vendored `<nds-icon-button>`
32
+ * Opt-in flag: context consumers render the vendored `<pie-nds-icon-button>`
33
33
  * only when this is `true`; otherwise (unset/`false`, the default) they
34
34
  * render plain `<button>` controls. Sourced from the `nds-icons` attribute
35
35
  * on the toolkit or section player.
@@ -62,6 +62,12 @@ export interface AssessmentToolkitRuntimeContext {
62
62
  * they saw.
63
63
  */
64
64
  i18n?: I18nProvider;
65
+ /**
66
+ * Whether a host chose the interface locale (`hostChoseInterfaceLocale`):
67
+ * the chrome stamps {@link locale}'s `lang` and `dir` only while this holds,
68
+ * so a host that chooses none leaves the page's language in effect.
69
+ */
70
+ interfaceLocaleChosen?: boolean;
65
71
  /**
66
72
  * Content language: the language the authored content is written in, which
67
73
  * read-aloud speaks it in and catalog lookups select alternates by. Sourced
@@ -73,6 +79,14 @@ export interface AssessmentToolkitRuntimeContext {
73
79
  * an interface in another.
74
80
  */
75
81
  contentLanguage?: string;
82
+ /**
83
+ * The content language the item and passage players stamp on content that
84
+ * declares none: {@link contentLanguage} when the host names one, else
85
+ * `auto` (`lang=""` with `dir="auto"`) when the host sets an interface
86
+ * locale, else unset, which leaves undeclared content inheriting the page's
87
+ * language and direction. See `defaultContentLanguage`.
88
+ */
89
+ contentLanguageDefault?: string;
76
90
  /**
77
91
  * Reports a failure that keeps the section's content from loading as the
78
92
  * section controller's `section-error`, with source `section-runtime`.
package/dist/index.d.ts CHANGED
@@ -9,7 +9,7 @@
9
9
  export type { AssessmentToolkitRuntimeContext, ItemPlayerConfig, ItemPlayerType, ShellContextKind, } from "./context/assessment-toolkit-context.js";
10
10
  export type { TTSHighlightContext, TTSHighlightTargetResolver, TTSHighlightTargetResolverProvider, TTSHighlightTargetResolverRuntime, } from "./services/tts/highlight-target-resolver.js";
11
11
  export { catalogOwnerContextFor, type CatalogOwnerContext, type CatalogOwnerIdentity, type CatalogSourceEntity, } from "./services/catalog-owner.js";
12
- export { PIE_INTERNAL_FORMATIVE_ACTION_EVENT, PIE_INTERNAL_ITEM_SESSION_CHANGED_EVENT, PIE_INTERNAL_MEDIA_TIME_SOURCE_EVENT, PIE_ITEM_SESSION_CHANGED_EVENT, type InternalFormativeActionDetail, type InternalMediaTimeSourceDetail, } from "./runtime/registration-events.js";
12
+ export { PIE_INTERNAL_TRY_ACTION_EVENT, PIE_INTERNAL_ITEM_SESSION_CHANGED_EVENT, PIE_INTERNAL_MEDIA_TIME_SOURCE_EVENT, PIE_ITEM_PLAYER_EVENT, PIE_ITEM_SESSION_CHANGED_EVENT, RELAYED_ITEM_PLAYER_EVENTS, type InternalTryActionDetail, type InternalMediaTimeSourceDetail, type ItemPlayerEventDetail, type RelayedItemPlayerEventType, } from "./runtime/registration-events.js";
13
13
  export { createShellScope, type ShellScope, type ShellScopeState, } from "./runtime/shell-scope.js";
14
14
  export { createShellEventBridge, type ShellEventBridge, type ShellEventBridgeOptions, } from "./runtime/shell-event-bridge.js";
15
15
  export { connectToolRuntimeContext, dispatchCrossBoundaryEvent, } from "./runtime/tool-host-contract.js";
@@ -32,7 +32,7 @@ export type { ToolComponentFactory, ToolComponentFactoryMap, ToolComponentOverri
32
32
  export type { ExtractionResult } from "./services/SSMLExtractor.js";
33
33
  export { SSMLExtractor } from "./services/SSMLExtractor.js";
34
34
  export { ZIndexLayer } from "./services/ToolCoordinator.js";
35
- export type { ProviderLifecycleContext, SectionControllerContext, SectionControllerEvent, SectionControllerEventType, SectionItemEvent, SectionItemEventType, SectionControllerFactoryDefaults, SectionControllerHandle, SectionControllerKey, SectionScopedEvent, SectionScopedEventType, SectionSessionPersistenceConfig, SectionItemEventSubscriptionArgs, SectionScopedEventSubscriptionArgs, SectionEventSubscriptionArgs, SectionSessionPersistenceStrategy, SectionControllerLoadedRenderable, SectionControllerRuntimeState, SectionControllerSessionState, SectionPersistenceFactoryDefaults, ToolkitCoordinatorConfig, ToolkitCoordinatorHooks, ToolkitErrorContext, } from "./services/ToolkitCoordinator.js";
35
+ export type { ProviderLifecycleContext, SectionControllerContext, SectionControllerEvent, SectionControllerEventType, SectionItemEvent, SectionItemEventType, SectionControllerFactoryDefaults, SectionControllerHandle, SectionControllerKey, SectionItemScore, SectionItemScorer, SectionScore, SectionScopedEvent, SectionScopedEventType, SectionSessionPersistenceConfig, SectionItemEventSubscriptionArgs, SectionScopedEventSubscriptionArgs, SectionEventSubscriptionArgs, SectionSessionPersistenceStrategy, SectionControllerLoadedRenderable, SectionControllerRuntimeState, SectionControllerSessionState, SectionPersistenceFactoryDefaults, ToolkitCoordinatorConfig, ToolkitCoordinatorHooks, ToolkitErrorContext, } from "./services/ToolkitCoordinator.js";
36
36
  export { ToolkitCoordinator } from "./services/ToolkitCoordinator.js";
37
37
  export type { CalculatorToolProviderConfig, CanonicalToolsConfig, ToolPlacementConfig, ToolPlacementLevel, ToolPolicyConfig, ToolProvidersConfig, ToolsConfigInput, TextToSpeechToolProviderConfig, } from "./services/tools-config-normalizer.js";
38
38
  export type { FrameworkErrorCohort, FrameworkErrorKind, FrameworkErrorModel, FrameworkErrorScope, FrameworkErrorSeverity, } from "./services/framework-error.js";
@@ -51,4 +51,4 @@ export type { ITTSProvider, ITTSProviderImplementation, TTSConfig, TTSSpeechSegm
51
51
  export type { TestAttemptItemSession, TestAttemptSession, TestAttemptSessionNavigationState, TestAttemptSessionRealization, } from "./attempt/TestSession.js";
52
52
  export { createNewTestAttemptSession, setCurrentPosition, toItemSessionsRecord, upsertItemSessionFromPieSessionChange, upsertVisitedItem, } from "./attempt/TestSession.js";
53
53
  export type { AssessmentSession, AssessmentSectionSessionState, AssessmentSessionNavigationState, AssessmentSessionRealization, } from "./attempt/AssessmentSession.js";
54
- export { createNewAssessmentSession, setCurrentSectionPosition, upsertSectionSession, } from "./attempt/AssessmentSession.js";
54
+ export { createNewAssessmentSession, markAssessmentSessionSubmitted, setCurrentSectionPosition, upsertSectionSession, } from "./attempt/AssessmentSession.js";
package/dist/index.js CHANGED
@@ -7,7 +7,7 @@
7
7
  * @packageDocumentation
8
8
  */
9
9
  export { catalogOwnerContextFor, } from "./services/catalog-owner.js";
10
- export { PIE_INTERNAL_FORMATIVE_ACTION_EVENT, PIE_INTERNAL_ITEM_SESSION_CHANGED_EVENT, PIE_INTERNAL_MEDIA_TIME_SOURCE_EVENT, PIE_ITEM_SESSION_CHANGED_EVENT, } from "./runtime/registration-events.js";
10
+ export { PIE_INTERNAL_TRY_ACTION_EVENT, PIE_INTERNAL_ITEM_SESSION_CHANGED_EVENT, PIE_INTERNAL_MEDIA_TIME_SOURCE_EVENT, PIE_ITEM_PLAYER_EVENT, PIE_ITEM_SESSION_CHANGED_EVENT, RELAYED_ITEM_PLAYER_EVENTS, } from "./runtime/registration-events.js";
11
11
  export { createShellScope, } from "./runtime/shell-scope.js";
12
12
  // A shell's translation of its player's events into the runtime's, shared by the
13
13
  // section player's passage shell and `<pie-item-scope>`.
@@ -30,4 +30,4 @@ export { createScopedToolId } from "./services/tool-instance-id.js";
30
30
  export { PlaybackState, TTSService } from "./services/TTSService.js";
31
31
  export { BrowserTTSProvider } from "./services/tts/browser-provider.js";
32
32
  export { createNewTestAttemptSession, setCurrentPosition, toItemSessionsRecord, upsertItemSessionFromPieSessionChange, upsertVisitedItem, } from "./attempt/TestSession.js";
33
- export { createNewAssessmentSession, setCurrentSectionPosition, upsertSectionSession, } from "./attempt/AssessmentSession.js";
33
+ export { createNewAssessmentSession, markAssessmentSessionSubmitted, setCurrentSectionPosition, upsertSectionSession, } from "./attempt/AssessmentSession.js";
@@ -20,6 +20,7 @@ import type { ToolRegistry } from "../../services/ToolRegistry.js";
20
20
  import type { ToolPolicyDecision, ToolPolicyDecisionRequest, ToolPolicyDiagnostic, ToolScope } from "./decision-types.js";
21
21
  import type { PolicySource } from "./PolicySource.js";
22
22
  import type { FeaturePolicyDecision } from "./feature-decision.js";
23
+ import { type SupportConflict } from "../sources/PnpPolicySource.js";
23
24
  export type { PnpEnforcementMode };
24
25
  export interface ToolPolicyEngineInputs {
25
26
  tools?: CanonicalToolsConfig | null;
@@ -50,6 +51,12 @@ export interface ToolPolicyEngineArgs {
50
51
  * Defaults to `false`.
51
52
  */
52
53
  assessmentOptional?: boolean;
54
+ /**
55
+ * Supports that withhold other ids while in effect, resolved at precedence 4
56
+ * under `support-conflict`. Defaults to none; `ToolkitCoordinator` passes
57
+ * the toolkit's own.
58
+ */
59
+ supportConflicts?: readonly SupportConflict[];
53
60
  }
54
61
  export interface ToolPolicyChangeEvent {
55
62
  /**
@@ -92,6 +99,7 @@ export declare class ToolPolicyEngine {
92
99
  private readonly contextId;
93
100
  private readonly assessmentOptional;
94
101
  private pnpPolicySource;
102
+ private readonly supportConflicts;
95
103
  private readonly customSources;
96
104
  private readonly listeners;
97
105
  private tools;
@@ -32,6 +32,7 @@ export class ToolPolicyEngine {
32
32
  contextId;
33
33
  assessmentOptional;
34
34
  pnpPolicySource;
35
+ supportConflicts;
35
36
  customSources;
36
37
  listeners = new Set();
37
38
  tools;
@@ -48,7 +49,8 @@ export class ToolPolicyEngine {
48
49
  this.toolRegistry = args.toolRegistry;
49
50
  this.contextId = args.contextId ?? "tool-policy";
50
51
  this.assessmentOptional = args.assessmentOptional === true;
51
- this.pnpPolicySource = new PnpPolicySource(this.toolRegistry);
52
+ this.supportConflicts = args.supportConflicts ?? [];
53
+ this.pnpPolicySource = new PnpPolicySource(this.toolRegistry, this.supportConflicts);
52
54
  this.customSources = args.customSources ? [...args.customSources] : [];
53
55
  const inputs = args.inputs ?? {};
54
56
  this.tools = inputs.tools ?? DEFAULT_TOOLS;
@@ -284,7 +286,7 @@ export class ToolPolicyEngine {
284
286
  this.assertNotDisposed();
285
287
  this.unsubscribeRegistry();
286
288
  this.toolRegistry = toolRegistry;
287
- this.pnpPolicySource = new PnpPolicySource(toolRegistry);
289
+ this.pnpPolicySource = new PnpPolicySource(toolRegistry, this.supportConflicts);
288
290
  this.unsubscribeRegistry = this.watchRegistry();
289
291
  this.tools = tools;
290
292
  this.refreshInputDiagnostics();
@@ -138,6 +138,13 @@ export function composeDecision(inputs) {
138
138
  for (const [toolId, rule] of pnpPolicyResult.blockedOverrides) {
139
139
  diagnostics.push(overrideBlockedDiagnostic(toolId, rule, request.level));
140
140
  }
141
+ // A withheld tool this level would have shown: placed and past the host
142
+ // gates. One the host removed was never going to be served here.
143
+ for (const [toolId, conflict] of pnpPolicyResult.supportConflicts) {
144
+ if (!postHostCandidates.has(toolId))
145
+ continue;
146
+ diagnostics.push(supportConflictDiagnostic(toolId, conflict.support, conflict.grant ?? "placement", request.level));
147
+ }
141
148
  // 5a — remove PNP/profile-blocked tools from the candidate set.
142
149
  const { blockedToolIds } = pnpPolicyResult;
143
150
  candidates = candidates.filter((toolId) => !blockedToolIds.has(toolId));
@@ -288,6 +295,7 @@ export function composeDecision(inputs) {
288
295
  toolId,
289
296
  required: flag?.required ?? false,
290
297
  alwaysAvailable: flag?.alwaysAvailable ?? false,
298
+ activateAtInit: flag?.activateAtInit ?? false,
291
299
  parameters: resolveToolParameters(toolId, pnpPolicy.assessment, pnpPolicy.item),
292
300
  };
293
301
  });
@@ -335,9 +343,11 @@ const PNP_RULE_FIELDS = {
335
343
  "test-admin-override": "settings.testAdministration.toolOverrides",
336
344
  "item-restriction": "item settings.restrictedTools",
337
345
  "pnp-prohibited": "personalNeedsProfile.prohibitedSupports",
346
+ "support-conflict": "a withholding support in personalNeedsProfile.supports",
338
347
  "item-requirement": "item settings.requiredTools",
339
348
  "district-requirement": "settings.districtPolicy.requiredTools",
340
349
  "pnp-support": "personalNeedsProfile.supports",
350
+ "pnp-activate-at-init": "personalNeedsProfile.activateAtInit",
341
351
  };
342
352
  /**
343
353
  * A `tool-policy.overrideBlocked` diagnostic for a tool a `true` test
@@ -353,6 +363,27 @@ export function overrideBlockedDiagnostic(toolId, rule, level) {
353
363
  details: { rule },
354
364
  };
355
365
  }
366
+ /**
367
+ * A `tool-policy.supportConflict` diagnostic for an id `support` withholds
368
+ * although `servedBy` would have served it. `level` is absent on a feature
369
+ * decision, which has no toolbar level.
370
+ */
371
+ export function supportConflictDiagnostic(toolId, support, servedBy, level) {
372
+ const source = servedBy === "placement"
373
+ ? "tools.placement"
374
+ : servedBy === "attribute"
375
+ ? "The item player's attribute"
376
+ : servedBy === "authored"
377
+ ? "The item's authored content"
378
+ : PNP_RULE_FIELDS[servedBy];
379
+ return {
380
+ code: "tool-policy.supportConflict",
381
+ ...(level ? { level } : {}),
382
+ toolId,
383
+ message: `${source} serves "${toolId}", but the student's "${support}" support withholds it.`,
384
+ details: { support, servedBy },
385
+ };
386
+ }
356
387
  /**
357
388
  * A `tool-policy.unknownSupportId` diagnostic for an id the registry lacks,
358
389
  * naming every list that names it. It describes the engine's inputs rather
@@ -79,6 +79,11 @@ export interface ToolPolicyDecisionRequest {
79
79
  * `restrictedTools` or the profile's `prohibitedSupports` withdraws instead.
80
80
  * `details` is {@link OverrideBlockedDetails}.
81
81
  *
82
+ * `tool-policy.supportConflict` fires for each id a support in effect withdraws
83
+ * that something would otherwise have served, as the toolkit's `screenReader`
84
+ * withdraws `textToSpeech`. It replaces `tool-policy.overrideBlocked` for a `true`
85
+ * override the conflict withdraws. `details` is {@link SupportConflictDetails}.
86
+ *
82
87
  * The toolkit coordinator logs each diagnostic once per code, tool and item,
83
88
  * and hands the same ones to its `onPolicyDiagnostic` listeners.
84
89
  */
@@ -122,6 +127,20 @@ export interface OverrideBlockedDetails {
122
127
  /** The rule that withdrew the granted tool. */
123
128
  rule: "item-restriction" | "pnp-prohibited";
124
129
  }
130
+ /**
131
+ * What would have served an id a support conflict withdraws: the placement
132
+ * that put the tool on this toolbar, the rule that would have granted it, or,
133
+ * for a feature an item player applies, the player's attribute or the item's
134
+ * authored setting it displaced.
135
+ */
136
+ export type SupportConflictServedBy = "placement" | "attribute" | "authored" | Extract<PnpPolicySourceRule, "test-admin-override" | "item-requirement" | "district-requirement" | "pnp-activate-at-init" | "pnp-support">;
137
+ /** Payload of a `tool-policy.supportConflict` diagnostic. */
138
+ export interface SupportConflictDetails {
139
+ /** The support in effect that withholds the id. */
140
+ support: string;
141
+ /** What would otherwise have served the withheld id. */
142
+ servedBy: SupportConflictServedBy;
143
+ }
125
144
  /** Payload of a `tool-policy.itemSettingNotApplied` diagnostic. */
126
145
  export interface ItemSettingNotAppliedDetails {
127
146
  /** Canonical id of the item whose setting names the tool. */
@@ -138,6 +157,7 @@ export interface ToolPolicyDiagnosticDetails {
138
157
  "tool-policy.unknownSupportId": UnknownSupportIdDetails;
139
158
  "tool-policy.itemSettingNotApplied": ItemSettingNotAppliedDetails;
140
159
  "tool-policy.overrideBlocked": OverrideBlockedDetails;
160
+ "tool-policy.supportConflict": SupportConflictDetails;
141
161
  }
142
162
  /** A policy diagnostic, its `details` typed by its `code`. */
143
163
  export type ToolPolicyDiagnostic = {
@@ -163,17 +183,22 @@ export interface ToolPolicyEntry {
163
183
  */
164
184
  required: boolean;
165
185
  /**
166
- * `true` for a tool the student's PNP `supports` or a
167
- * `testAdministration.toolOverrides` entry grants — UI-level signal that
186
+ * `true` for a tool the student's PNP `supports` or `activateAtInit`, or a
187
+ * `testAdministration.toolOverrides` entry, grants — UI-level signal that
168
188
  * the host cannot toggle this tool off in user preferences. Does NOT
169
189
  * override host blocks (they would have removed the entry before this
170
190
  * flag is read).
171
191
  */
172
192
  alwaysAvailable: boolean;
173
193
  /**
174
- * The tool's parameters: the item's `toolParameters` entry on the item's own
175
- * toolbar, else the assessment's `toolParameters` entry. Set whether or not a
176
- * grant admitted the tool.
194
+ * `true` for a tool the student's PNP `activateAtInit` lists that policy
195
+ * admits: the toolbar turns it on when it first shows it.
196
+ */
197
+ activateAtInit: boolean;
198
+ /**
199
+ * The tool's parameters: the profile's, assessment's and, on the item's own
200
+ * toolbar, item's `toolParameters` entries merged key by key, later ones
201
+ * winning. Set whether or not a grant admitted the tool.
177
202
  */
178
203
  parameters?: Record<string, unknown>;
179
204
  }
@@ -72,14 +72,21 @@ export interface FeaturePolicyDecision<P = Record<string, unknown>> {
72
72
  */
73
73
  required: boolean;
74
74
  /**
75
- * The feature's parameters: the item's `toolParameters` entry for an item's
76
- * scope, else the assessment's `toolParameters` entry, keyed by the feature id.
77
- * Set on a denial too; a host denial leaves it out.
75
+ * The feature's parameters: the profile's, assessment's and, for an item's
76
+ * scope, item's `toolParameters` entries for the feature id, merged key by key,
77
+ * later ones winning. Set on a denial too; a host denial leaves it out.
78
78
  */
79
79
  parameters?: P;
80
+ /**
81
+ * The support in effect that withholds the feature, on a `support-conflict`
82
+ * verdict.
83
+ */
84
+ withheldBy?: string;
80
85
  /**
81
86
  * Conflicts found while deciding: a `tool-policy.overrideBlocked` for a
82
- * granting override the decision withdrew. Empty on a host denial, which
87
+ * granting override the decision withdrew, and a
88
+ * `tool-policy.supportConflict` for a granting rule a support in effect
89
+ * displaced. Empty on a host denial, which
83
90
  * consults no policy source. An id no tool is registered under describes the
84
91
  * inputs, so it is reported on the engine inputs' `diagnostics`.
85
92
  */
@@ -20,7 +20,7 @@
20
20
  * "nothing was bound to ask against" are the same verdict for different
21
21
  * reasons, and only the second is a defect.
22
22
  */
23
- import { overrideBlockedDiagnostic } from "./compose-decision.js";
23
+ import { overrideBlockedDiagnostic, supportConflictDiagnostic, } from "./compose-decision.js";
24
24
  /**
25
25
  * Reason text for a denial that had no assessment to decide against.
26
26
  *
@@ -79,6 +79,7 @@ export function interpretFeatureResult(featureId, result, context, parameters) {
79
79
  // The source logs "no rule fired" as a skip at the last level so the trail
80
80
  // stays ordered; the verdict names no rule for it.
81
81
  const fired = decision !== undefined && decision.action !== "skip";
82
+ const conflict = result.supportConflicts.get(featureId);
82
83
  return {
83
84
  featureId,
84
85
  granted,
@@ -95,7 +96,13 @@ export function interpretFeatureResult(featureId, result, context, parameters) {
95
96
  : unboundAssessmentReason(featureId),
96
97
  required: Boolean(flags?.required),
97
98
  parameters,
99
+ ...(fired && decision.rule === "support-conflict" && conflict
100
+ ? { withheldBy: conflict.support }
101
+ : {}),
98
102
  assessmentBound: context.assessmentBound,
99
- diagnostics: Array.from(result.blockedOverrides, ([toolId, rule]) => overrideBlockedDiagnostic(toolId, rule)),
103
+ diagnostics: [
104
+ ...Array.from(result.blockedOverrides, ([toolId, rule]) => overrideBlockedDiagnostic(toolId, rule)),
105
+ ...Array.from(result.supportConflicts).flatMap(([toolId, { support, grant }]) => grant ? [supportConflictDiagnostic(toolId, support, grant)] : []),
106
+ ],
100
107
  };
101
108
  }
@@ -11,7 +11,8 @@
11
11
  * record (only `id` / `name`, no PNP and no settings) do not engage
12
12
  * PNP/profile gates. The flip happens the moment the assessment carries any of:
13
13
  *
14
- * - `personalNeedsProfile` (any `supports` or `prohibitedSupports`),
14
+ * - `personalNeedsProfile` (any `supports`, `prohibitedSupports` or
15
+ * `activateAtInit`),
15
16
  * - `settings.districtPolicy` (any `blockedTools` or `requiredTools`),
16
17
  * - `settings.testAdministration` (any `toolOverrides` entry),
17
18
  * - or, for an item-scoped decision, the item's settings carry
@@ -36,7 +37,10 @@ export function assessmentHasPnpPolicyInputs(assessment) {
36
37
  if (!assessment)
37
38
  return false;
38
39
  const pnp = assessment.personalNeedsProfile;
39
- if (pnp && (hasEntries(pnp.supports) || hasEntries(pnp.prohibitedSupports))) {
40
+ if (pnp &&
41
+ (hasEntries(pnp.supports) ||
42
+ hasEntries(pnp.prohibitedSupports) ||
43
+ hasEntries(pnp.activateAtInit))) {
40
44
  return true;
41
45
  }
42
46
  const settings = assessment.settings;
@@ -8,7 +8,7 @@
8
8
  * provider veto, PNP/profile gates, and custom policy sources.
9
9
  */
10
10
  /** The PNP/profile precedence rules, highest first. */
11
- export type PnpPolicySourceRule = "district-block" | "test-admin-override" | "item-restriction" | "pnp-prohibited" | "item-requirement" | "district-requirement" | "pnp-support";
11
+ export type PnpPolicySourceRule = "district-block" | "test-admin-override" | "item-restriction" | "pnp-prohibited" | "support-conflict" | "item-requirement" | "district-requirement" | "pnp-support" | "pnp-activate-at-init";
12
12
  /**
13
13
  * Rule vocabulary for tool policy decisions. A decision's `rule` is the one
14
14
  * attribution channel: it names the step that enabled, blocked or advised on a
@@ -1,6 +1,12 @@
1
+ function asParameters(value) {
2
+ return value && typeof value === "object" && !Array.isArray(value)
3
+ ? value
4
+ : undefined;
5
+ }
1
6
  /**
2
- * A tool's parameters for one decision: the item's `toolParameters` entry, else
3
- * the assessment's `toolParameters` entry.
7
+ * A tool's parameters for one decision, merged key by key: the profile's
8
+ * `toolParameters` entry, overridden by the assessment's, overridden by the
9
+ * item's.
4
10
  *
5
11
  * Parameters say how a tool behaves wherever policy shows it, so they reach a
6
12
  * tool placed without a grant, and PNP enforcement does not gate them. `item` is
@@ -8,8 +14,14 @@
8
14
  */
9
15
  export function resolveToolParameters(toolId, assessment, item) {
10
16
  const settings = assessment?.settings;
11
- const value = item?.settings.toolParameters?.[toolId] ?? settings?.toolParameters?.[toolId];
12
- return value && typeof value === "object" && !Array.isArray(value)
13
- ? value
17
+ const layers = [
18
+ assessment?.personalNeedsProfile?.toolParameters?.[toolId],
19
+ settings?.toolParameters?.[toolId],
20
+ item?.settings.toolParameters?.[toolId],
21
+ ]
22
+ .map(asParameters)
23
+ .filter((layer) => layer !== undefined);
24
+ return layers.length > 0
25
+ ? Object.assign({}, ...layers)
14
26
  : undefined;
15
27
  }
@@ -7,6 +7,7 @@
7
7
  */
8
8
  export { ToolPolicyEngine, type PnpEnforcementMode, type ResolvedEngineInputs, type ToolPolicyChangeEvent, type ToolPolicyChangeListener, type ToolPolicyEngineArgs, type ToolPolicyEngineInputs, } from "./core/ToolPolicyEngine.js";
9
9
  export { isHostDeniedFeature, type FeaturePolicyDecision, type FeaturePolicyRule, } from "./core/feature-decision.js";
10
- export type { ItemSettingNotAppliedDetails, OverrideBlockedDetails, PlacementMissingDetails, RequiredToolBlockedDetails, ToolPolicyDecision, ToolPolicyDecisionRequest, ToolPolicyDiagnostic, ToolPolicyDiagnosticCode, ToolPolicyDiagnosticDetails, ToolPolicyEntry, ToolPolicyHostGate, ToolScope, UnknownSupportIdDetails, } from "./core/decision-types.js";
10
+ export type { ItemSettingNotAppliedDetails, OverrideBlockedDetails, PlacementMissingDetails, RequiredToolBlockedDetails, SupportConflictDetails, SupportConflictServedBy, ToolPolicyDecision, ToolPolicyDecisionRequest, ToolPolicyDiagnostic, ToolPolicyDiagnosticCode, ToolPolicyDiagnosticDetails, ToolPolicyEntry, ToolPolicyHostGate, ToolScope, UnknownSupportIdDetails, } from "./core/decision-types.js";
11
11
  export type { PolicySource, PolicySourceDecisionContext, PolicySourceProvenanceEntry, PolicySourceResult, } from "./core/PolicySource.js";
12
+ export type { SupportConflict } from "./sources/PnpPolicySource.js";
12
13
  export type { PnpPolicySourceRule, ToolPolicyDecisionRule, ToolPolicyFeatureTrail, ToolPolicyProvenance, ToolPolicyResolutionDecision, ToolPolicySourceType, } from "./core/provenance.js";
@@ -10,16 +10,30 @@
10
10
  import type { AssessmentEntity, ItemSettings } from "@pie-players/pie-players-shared/types";
11
11
  import type { ToolRegistry } from "../../services/ToolRegistry.js";
12
12
  import type { PnpPolicySourceRule, ToolPolicyResolutionDecision, ToolPolicySourceType } from "../core/provenance.js";
13
- import type { OverrideBlockedDetails } from "../core/decision-types.js";
13
+ import type { OverrideBlockedDetails, SupportConflictServedBy } from "../core/decision-types.js";
14
+ /**
15
+ * A support whose being in effect withholds other ids: they resolve blocked
16
+ * under `support-conflict` at precedence 4 while `support` resolves enabled.
17
+ * Every id a conflict names is recognized without a tool registration, so none
18
+ * raises `tool-policy.unknownSupportId`.
19
+ */
20
+ export interface SupportConflict {
21
+ /** The support id that withholds. */
22
+ support: string;
23
+ /** The ids withheld while `support` is in effect. */
24
+ withholds: readonly string[];
25
+ }
14
26
  /** Per-tool flags PNP/profile policy may attach to a surviving entry. */
15
27
  export interface PnpPolicyToolFlags {
16
28
  /** PNP/profile policy mandates this tool (item or district `requiredTools`). */
17
29
  required: boolean;
18
30
  /**
19
- * The student's profile supports this tool, or a test-administration
20
- * override grants it (host UI cannot toggle off).
31
+ * The student's profile supports this tool or activates it at start, or a
32
+ * test-administration override grants it (host UI cannot toggle off).
21
33
  */
22
34
  alwaysAvailable: boolean;
35
+ /** The student's profile lists this tool in `activateAtInit`. */
36
+ activateAtInit: boolean;
23
37
  /** Which PNP/profile rule contributed the surviving verdict. */
24
38
  rule: PnpPolicySourceRule;
25
39
  }
@@ -80,6 +94,14 @@ export interface PnpPolicyResult {
80
94
  * engine turns each into a `tool-policy.overrideBlocked` diagnostic.
81
95
  */
82
96
  blockedOverrides: Map<string, OverrideBlockedDetails["rule"]>;
97
+ /**
98
+ * Ids a support in effect withdrew under `support-conflict`, each with that
99
+ * support and the rule that would otherwise have granted the id, absent when
100
+ * none would have. The engine turns each into a
101
+ * `tool-policy.supportConflict` diagnostic when something would have served
102
+ * the id.
103
+ */
104
+ supportConflicts: Map<string, SupportConflictResolution>;
83
105
  /** Configuration sources the engine should attach to its provenance. */
84
106
  sources: {
85
107
  assessment?: {
@@ -99,10 +121,21 @@ export interface PnpPolicyResult {
99
121
  };
100
122
  };
101
123
  }
124
+ /** A rule a support conflict can displace: one of levels 5 to 8. */
125
+ export type SupportConflictGrant = Exclude<SupportConflictServedBy, "placement" | "attribute" | "authored">;
126
+ /** One `support-conflict` withdrawal. */
127
+ export interface SupportConflictResolution {
128
+ support: string;
129
+ grant?: SupportConflictGrant;
130
+ }
102
131
  export declare class PnpPolicySource {
103
132
  readonly id = "pnp";
104
133
  private readonly toolRegistry;
105
- constructor(toolRegistry: ToolRegistry);
134
+ private readonly supportConflicts;
135
+ /** Withheld id to the supports that withhold it, in declaration order. */
136
+ private readonly withheldBy;
137
+ private readonly registrylessIds;
138
+ constructor(toolRegistry: ToolRegistry, supportConflicts?: readonly SupportConflict[]);
106
139
  apply(args: PnpPolicyApplyArgs): PnpPolicyResult;
107
140
  /**
108
141
  * Evaluate exactly one PNP support id through the same eight-level
@@ -124,6 +157,17 @@ export declare class PnpPolicySource {
124
157
  * configuration-source attribution) from the bound policy inputs.
125
158
  */
126
159
  private prepare;
160
+ /**
161
+ * Whether `support` resolves enabled, conflicts aside: a support another
162
+ * conflict withholds still withholds, and two conflicts naming each other
163
+ * cannot recurse.
164
+ */
165
+ private supportInEffect;
166
+ /**
167
+ * `withConflict: false` resolves the id as if no support conflict applied,
168
+ * which names the grant a conflict displaces without a second copy of
169
+ * levels 5 to 8.
170
+ */
127
171
  private resolveSupport;
128
172
  /**
129
173
  * Ids the assessment or any of `items` names that no tool is registered