@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
@@ -10,8 +10,22 @@
10
10
  export class PnpPolicySource {
11
11
  id = "pnp";
12
12
  toolRegistry;
13
- constructor(toolRegistry) {
13
+ supportConflicts;
14
+ /** Withheld id to the supports that withhold it, in declaration order. */
15
+ withheldBy = new Map();
16
+ registrylessIds = new Set();
17
+ constructor(toolRegistry, supportConflicts = []) {
14
18
  this.toolRegistry = toolRegistry;
19
+ this.supportConflicts = supportConflicts;
20
+ for (const { support, withholds } of supportConflicts) {
21
+ this.registrylessIds.add(support);
22
+ for (const id of withholds) {
23
+ this.registrylessIds.add(id);
24
+ const supports = this.withheldBy.get(id) ?? [];
25
+ supports.push(support);
26
+ this.withheldBy.set(id, supports);
27
+ }
28
+ }
15
29
  }
16
30
  apply(args) {
17
31
  const { ctx, result } = this.prepare(args);
@@ -19,6 +33,7 @@ export class PnpPolicySource {
19
33
  const allSupports = new Set();
20
34
  pnp?.supports?.forEach((s) => allSupports.add(s));
21
35
  pnp?.prohibitedSupports?.forEach((s) => allSupports.add(s));
36
+ pnp?.activateAtInit?.forEach((s) => allSupports.add(s));
22
37
  districtPolicy?.blockedTools?.forEach((s) => allSupports.add(s));
23
38
  districtPolicy?.requiredTools?.forEach((s) => allSupports.add(s));
24
39
  for (const s of Object.keys(testAdmin?.toolOverrides ?? {})) {
@@ -26,6 +41,12 @@ export class PnpPolicySource {
26
41
  }
27
42
  itemSettings?.requiredTools?.forEach((s) => allSupports.add(s));
28
43
  itemSettings?.restrictedTools?.forEach((s) => allSupports.add(s));
44
+ // A conflict withdraws a placed tool that no policy input names.
45
+ for (const { support, withholds } of this.supportConflicts) {
46
+ if (this.supportInEffect(support, ctx)) {
47
+ withholds.forEach((s) => allSupports.add(s));
48
+ }
49
+ }
29
50
  for (const supportId of allSupports) {
30
51
  this.resolveSupport(supportId, ctx, result);
31
52
  }
@@ -59,14 +80,7 @@ export class PnpPolicySource {
59
80
  const pnp = assessment?.personalNeedsProfile;
60
81
  const settings = assessment?.settings;
61
82
  const itemSettings = item?.settings;
62
- const result = {
63
- blockedToolIds: new Set(),
64
- mandates: new Map(),
65
- perToolFlags: new Map(),
66
- decisions: [],
67
- blockedOverrides: new Map(),
68
- sources: {},
69
- };
83
+ const result = emptyResult();
70
84
  if (settings?.districtPolicy || settings?.testAdministration) {
71
85
  result.sources.assessment = {
72
86
  id: assessment?.id || "unknown",
@@ -96,7 +110,22 @@ export class PnpPolicySource {
96
110
  };
97
111
  return { ctx, result };
98
112
  }
99
- resolveSupport(supportId, ctx, out) {
113
+ /**
114
+ * Whether `support` resolves enabled, conflicts aside: a support another
115
+ * conflict withholds still withholds, and two conflicts naming each other
116
+ * cannot recurse.
117
+ */
118
+ supportInEffect(support, ctx) {
119
+ const scratch = emptyResult();
120
+ this.resolveSupport(support, ctx, scratch, false);
121
+ return scratch.decisions[0]?.action === "enable";
122
+ }
123
+ /**
124
+ * `withConflict: false` resolves the id as if no support conflict applied,
125
+ * which names the grant a conflict displaces without a second copy of
126
+ * levels 5 to 8.
127
+ */
128
+ resolveSupport(supportId, ctx, out, withConflict = true) {
100
129
  // 1. District block (absolute veto)
101
130
  if (ctx.districtPolicy?.blockedTools?.includes(supportId)) {
102
131
  out.blockedToolIds.add(supportId);
@@ -162,6 +191,36 @@ export class PnpPolicySource {
162
191
  });
163
192
  return;
164
193
  }
194
+ // 4. Support conflict. Ranks with the profile prohibition, below the
195
+ // blocks a person recorded.
196
+ const withholding = withConflict
197
+ ? this.withheldBy
198
+ .get(supportId)
199
+ ?.find((support) => this.supportInEffect(support, ctx))
200
+ : undefined;
201
+ if (withholding) {
202
+ const displaced = emptyResult();
203
+ this.resolveSupport(supportId, ctx, displaced, false);
204
+ const grant = displaced.decisions[0];
205
+ out.blockedToolIds.add(supportId);
206
+ out.supportConflicts.set(supportId, {
207
+ support: withholding,
208
+ ...(grant?.action === "enable"
209
+ ? { grant: grant.rule }
210
+ : {}),
211
+ });
212
+ out.decisions.push({
213
+ precedence: 4,
214
+ rule: "support-conflict",
215
+ featureId: supportId,
216
+ action: "block",
217
+ sourceType: "student",
218
+ reason: `"${supportId}" is withheld while the student's "${withholding}" support is in effect`,
219
+ value: { support: withholding },
220
+ });
221
+ return;
222
+ }
223
+ const activateAtInit = ctx.pnp?.activateAtInit?.includes(supportId) === true;
165
224
  const mandate = ctx.itemSettings?.requiredTools?.includes(supportId)
166
225
  ? "item-requirement"
167
226
  : ctx.districtPolicy?.requiredTools?.includes(supportId)
@@ -175,6 +234,7 @@ export class PnpPolicySource {
175
234
  out.perToolFlags.set(supportId, {
176
235
  required: mandate !== undefined,
177
236
  alwaysAvailable: true,
237
+ activateAtInit,
178
238
  rule: "test-admin-override",
179
239
  });
180
240
  out.decisions.push({
@@ -194,6 +254,7 @@ export class PnpPolicySource {
194
254
  out.perToolFlags.set(supportId, {
195
255
  required: true,
196
256
  alwaysAvailable: false,
257
+ activateAtInit,
197
258
  rule: "item-requirement",
198
259
  });
199
260
  out.decisions.push({
@@ -213,6 +274,7 @@ export class PnpPolicySource {
213
274
  out.perToolFlags.set(supportId, {
214
275
  required: true,
215
276
  alwaysAvailable: false,
277
+ activateAtInit,
216
278
  rule: "district-requirement",
217
279
  });
218
280
  out.decisions.push({
@@ -226,11 +288,31 @@ export class PnpPolicySource {
226
288
  });
227
289
  return;
228
290
  }
229
- // 8. Profile supports (student needs)
291
+ // 8. Profile supports (student needs). `activateAtInit` grants as
292
+ // `supports` does and names the tool to turn on at start.
293
+ if (activateAtInit) {
294
+ out.perToolFlags.set(supportId, {
295
+ required: false,
296
+ alwaysAvailable: true,
297
+ activateAtInit,
298
+ rule: "pnp-activate-at-init",
299
+ });
300
+ out.decisions.push({
301
+ precedence: 8,
302
+ rule: "pnp-activate-at-init",
303
+ featureId: supportId,
304
+ action: "enable",
305
+ sourceType: "student",
306
+ reason: `Student PNP profile turns on "${supportId}" at start`,
307
+ value: ctx.pnp?.activateAtInit,
308
+ });
309
+ return;
310
+ }
230
311
  if (ctx.pnp?.supports?.includes(supportId)) {
231
312
  out.perToolFlags.set(supportId, {
232
313
  required: false,
233
314
  alwaysAvailable: true,
315
+ activateAtInit: false,
234
316
  rule: "pnp-support",
235
317
  });
236
318
  out.decisions.push({
@@ -281,12 +363,14 @@ export class PnpPolicySource {
281
363
  ["pnp-prohibited", pnp?.prohibitedSupports],
282
364
  ["item-requirement", items.flatMap((item) => item.requiredTools ?? [])],
283
365
  ["district-requirement", settings?.districtPolicy?.requiredTools],
366
+ ["pnp-activate-at-init", pnp?.activateAtInit],
284
367
  ["pnp-support", pnp?.supports],
285
368
  ];
286
369
  for (const [rule, ids] of named) {
287
370
  for (const id of ids ?? []) {
288
- if (this.toolRegistry.has(id))
371
+ if (this.toolRegistry.has(id) || this.registrylessIds.has(id)) {
289
372
  continue;
373
+ }
290
374
  const rules = unmapped.get(id) ?? [];
291
375
  if (!rules.includes(rule))
292
376
  rules.push(rule);
@@ -296,3 +380,14 @@ export class PnpPolicySource {
296
380
  return unmapped;
297
381
  }
298
382
  }
383
+ function emptyResult() {
384
+ return {
385
+ blockedToolIds: new Set(),
386
+ mandates: new Map(),
387
+ perToolFlags: new Map(),
388
+ decisions: [],
389
+ blockedOverrides: new Map(),
390
+ supportConflicts: new Map(),
391
+ sources: {},
392
+ };
393
+ }
@@ -357,27 +357,35 @@ export class SectionControllerBinding {
357
357
  const controller = this.requireControllerFor({ itemId, canonicalItemId: canonicalId }, "a session update");
358
358
  return controller?.updateItemSession?.(canonicalId, session) ?? null;
359
359
  }
360
+ /** Canonicalized for the same reason `updateItemSession` is. */
361
+ recordServedContentIdentity(args) {
362
+ const canonicalId = args.canonicalItemId || this.getCanonicalItemId(args.itemId);
363
+ this.requireControllerFor({ itemId: args.itemId, canonicalItemId: canonicalId }, "a served content identity")?.recordServedContentIdentity?.({
364
+ itemId: canonicalId,
365
+ identity: args.identity,
366
+ });
367
+ }
360
368
  navigateToItem(index) {
361
369
  return this.controller?.navigateToItem?.(index) ?? null;
362
370
  }
363
371
  /**
364
- * Route a learner's formative action to the controller.
372
+ * Route a learner's Try action to the controller.
365
373
  *
366
374
  * Canonicalized here for the same reason `updateItemSession` is: the runtime
367
375
  * id a card dispatches with is not necessarily the identifier the controller
368
376
  * keys state by. Both ids are kept, since the composition's renderables are
369
377
  * keyed by the runtime one.
370
378
  */
371
- handleFormativeAction(action) {
379
+ handleTryAction(action) {
372
380
  if (!action?.itemId)
373
381
  return;
374
382
  const canonicalId = action.canonicalItemId || this.getCanonicalItemId(action.itemId);
375
- const controller = this.requireControllerFor({ itemId: action.itemId, canonicalItemId: canonicalId }, "a formative action");
383
+ const controller = this.requireControllerFor({ itemId: action.itemId, canonicalItemId: canonicalId }, "a Try action");
376
384
  if (action.action === "retry") {
377
- controller?.retryFormativeItem?.({ itemId: canonicalId });
385
+ controller?.retryItem?.({ itemId: canonicalId });
378
386
  return;
379
387
  }
380
- controller?.recordFormativeTry?.({
388
+ controller?.recordTry?.({
381
389
  itemId: canonicalId,
382
390
  outcomes: action.outcomes,
383
391
  });
@@ -385,7 +393,7 @@ export class SectionControllerBinding {
385
393
  /**
386
394
  * Bind or release the section's Media Time Source.
387
395
  *
388
- * A pass-through, like `handleFormativeAction`: the binding routes, the
396
+ * A pass-through, like `handleTryAction`: the binding routes, the
389
397
  * controller decides. `renderableId` travels with the attach because whether the
390
398
  * registering renderable is the one `stimulusRef` names is the controller's call
391
399
  * — it validated `stimulusRef` in the first place.
@@ -3,8 +3,11 @@ import { findShellScopeHost } from "./content-region.js";
3
3
  /** The content language when neither the markup nor the host names one. */
4
4
  export const DEFAULT_CONTENT_LANGUAGE = "en-US";
5
5
  /**
6
- * The nearest non-empty `lang` attribute at or above `node`, climbing through
7
- * shadow hosts, and ending after `boundary` when one is given.
6
+ * The nearest `lang` attribute at or above `node`, climbing through shadow
7
+ * hosts, and ending after `boundary` when one is given. An empty `lang` names
8
+ * the language unknown and ends the climb with no language, as it ends the
9
+ * browser's own inheritance: the players stamp it on content that declares
10
+ * none, so the interface's `lang` above never reads as the content's.
8
11
  */
9
12
  export const findLangAttribute = (node, boundary) => {
10
13
  let current = !node
@@ -13,15 +16,38 @@ export const findLangAttribute = (node, boundary) => {
13
16
  ? node
14
17
  : composedParentElement(node);
15
18
  while (current) {
16
- const lang = current.getAttribute("lang")?.trim();
17
- if (lang)
18
- return lang;
19
+ const lang = current.getAttribute("lang");
20
+ if (lang !== null)
21
+ return lang.trim() || undefined;
19
22
  if (boundary && current === boundary)
20
23
  return undefined;
21
24
  current = composedParentElement(current);
22
25
  }
23
26
  return undefined;
24
27
  };
28
+ /**
29
+ * The language the content `root` holds is declared in: the `lang` its
30
+ * outermost `lang`-carrying descendants share, or undefined when they disagree,
31
+ * one is empty, or there are none. The players stamp `lang` on the content root
32
+ * they render, below the shell a whole-item read targets, so this is how such
33
+ * a read finds the language an item declared through `env.locale`.
34
+ */
35
+ export const findHeldContentLanguage = (root) => {
36
+ let language;
37
+ for (const element of root.querySelectorAll("[lang]")) {
38
+ const outer = element.parentElement?.closest("[lang]");
39
+ if (outer && outer !== root && root.contains(outer))
40
+ continue;
41
+ const lang = element.getAttribute("lang")?.trim();
42
+ if (!lang)
43
+ return undefined;
44
+ if (language === undefined)
45
+ language = lang;
46
+ else if (language.toLowerCase() !== lang.toLowerCase())
47
+ return undefined;
48
+ }
49
+ return language;
50
+ };
25
51
  /**
26
52
  * The language the content at `target` is named as being in: the nearest `lang`
27
53
  * between it and its shell scope host, else the host's `content-language` input.
@@ -22,6 +22,7 @@
22
22
  * `toolConfigStrictness` beside `runtime`.
23
23
  */
24
24
  import type { LoaderConfig } from "@pie-players/pie-players-shared/loader-config";
25
+ import type { I18nProvider } from "@pie-players/pie-players-shared/i18n";
25
26
  import type { LoadingCompleteDetail, StageChangeDetail } from "@pie-players/pie-players-shared/pie";
26
27
  import type { FrameworkErrorModel } from "../../services/framework-error.js";
27
28
  import type { ToolConfigStrictness } from "../../services/tool-config-validation.js";
@@ -71,6 +72,14 @@ export type RuntimeConfig = {
71
72
  * Unset reads as `en-US` wherever the markup names no language.
72
73
  */
73
74
  contentLanguage?: string;
75
+ /**
76
+ * The interface-locale provider the toolkit publishes on its runtime
77
+ * context, in place of the one it would construct: the catalogs it can
78
+ * serve, their loaders, and any host messages. `locale` on the element
79
+ * still names the locale; a provider given with none set keeps the locale
80
+ * its owner gave it.
81
+ */
82
+ i18n?: I18nProvider;
74
83
  onFrameworkError?: FrameworkErrorHandler;
75
84
  /** Called with each `pie-stage-change` detail. */
76
85
  onStageChange?: StageChangeHandler;
@@ -131,6 +140,14 @@ export declare function resolveRuntime(args: {
131
140
  * Unset reads as `en-US` wherever the markup names no language.
132
141
  */
133
142
  contentLanguage?: string;
143
+ /**
144
+ * The interface-locale provider the toolkit publishes on its runtime
145
+ * context, in place of the one it would construct: the catalogs it can
146
+ * serve, their loaders, and any host messages. `locale` on the element
147
+ * still names the locale; a provider given with none set keeps the locale
148
+ * its owner gave it.
149
+ */
150
+ i18n?: I18nProvider;
134
151
  onFrameworkError?: FrameworkErrorHandler;
135
152
  /** Called with each `pie-stage-change` detail. */
136
153
  onStageChange?: StageChangeHandler;
@@ -0,0 +1,115 @@
1
+ import { ContextProvider, FEATURE_DECISION_APPLIED_EVENT, itemFeatureDecisionsContext, } from "@pie-players/pie-context";
2
+ /** The feature ids an item player applies to its item's models. */
3
+ export const ITEM_PLAYER_FEATURE_IDS = ["autoplayAudio"];
4
+ const NO_DECISIONS = Object.freeze({
5
+ features: Object.freeze({}),
6
+ });
7
+ /**
8
+ * The scope an item's feature decisions are asked with, which brings in the
9
+ * item's registered settings; the same scope an item's content surfaces ask
10
+ * with.
11
+ */
12
+ export function itemFeatureScope(identity) {
13
+ const canonicalItemId = identity.canonicalItemId || identity.itemId;
14
+ return {
15
+ level: "item",
16
+ scopeId: canonicalItemId,
17
+ itemId: identity.itemId,
18
+ canonicalItemId,
19
+ };
20
+ }
21
+ /**
22
+ * The decisions an item player applies, leaving out each id no rule names. No
23
+ * coordinator, or one predating feature decisions, decides nothing.
24
+ */
25
+ export function resolveItemFeatureDecisions(coordinator, scope) {
26
+ if (!scope || typeof coordinator?.decideFeaturePolicy !== "function") {
27
+ return NO_DECISIONS;
28
+ }
29
+ const features = {};
30
+ for (const featureId of ITEM_PLAYER_FEATURE_IDS) {
31
+ const decision = coordinator.decideFeaturePolicy(featureId, scope);
32
+ if (decision.rule === "none")
33
+ continue;
34
+ features[featureId] = { granted: decision.granted, rule: decision.rule };
35
+ }
36
+ return { features };
37
+ }
38
+ /**
39
+ * Answers `itemFeatureDecisionsContext` for the item player under `host`, and
40
+ * relays the player's `feature-decision-applied` to the coordinator.
41
+ *
42
+ * It answers with no decision until both a coordinator and an item are set, so
43
+ * an item player under a scope no toolkit has answered keeps its own setting.
44
+ * A value is republished only when a decision changed, since every new value
45
+ * remounts the item.
46
+ */
47
+ export function provideItemFeatureDecisions(host) {
48
+ const provider = new ContextProvider(host, {
49
+ context: itemFeatureDecisionsContext,
50
+ initialValue: NO_DECISIONS,
51
+ });
52
+ provider.connect();
53
+ let signature = JSON.stringify(NO_DECISIONS.features);
54
+ let coordinator = null;
55
+ let scope = null;
56
+ let stopFollowingPolicy = null;
57
+ const refresh = () => {
58
+ const next = resolveItemFeatureDecisions(coordinator, scope);
59
+ const nextSignature = JSON.stringify(next.features);
60
+ if (nextSignature === signature)
61
+ return;
62
+ signature = nextSignature;
63
+ provider.setValue(next);
64
+ };
65
+ const stopFollowing = () => {
66
+ const stop = stopFollowingPolicy;
67
+ stopFollowingPolicy = null;
68
+ try {
69
+ stop?.();
70
+ }
71
+ catch {
72
+ // The coordinator may already have been disposed.
73
+ }
74
+ };
75
+ const onApplied = (event) => {
76
+ const detail = event.detail;
77
+ if (!detail || !scope)
78
+ return;
79
+ coordinator?.reportFeatureDecisionApplied?.(detail, scope);
80
+ };
81
+ host.addEventListener(FEATURE_DECISION_APPLIED_EVENT, onApplied);
82
+ return {
83
+ setCoordinator(next) {
84
+ if (next === coordinator)
85
+ return;
86
+ stopFollowing();
87
+ coordinator = next;
88
+ if (next && typeof next.onPolicyChange === "function") {
89
+ stopFollowingPolicy = next.onPolicyChange((event) => {
90
+ if (event.reason === "disposed") {
91
+ stopFollowing();
92
+ coordinator = null;
93
+ }
94
+ refresh();
95
+ });
96
+ }
97
+ refresh();
98
+ },
99
+ setItem(identity) {
100
+ const next = identity?.itemId ? itemFeatureScope(identity) : null;
101
+ if (next?.scopeId === scope?.scopeId && next?.itemId === scope?.itemId) {
102
+ return;
103
+ }
104
+ scope = next;
105
+ refresh();
106
+ },
107
+ disconnect() {
108
+ host.removeEventListener(FEATURE_DECISION_APPLIED_EVENT, onApplied);
109
+ stopFollowing();
110
+ coordinator = null;
111
+ scope = null;
112
+ provider.disconnect();
113
+ },
114
+ };
115
+ }
@@ -1,13 +1,22 @@
1
1
  import type { SessionCommitReason } from "@pie-players/pie-players-shared/pie";
2
- import type { ItemSettings } from "@pie-players/pie-players-shared/types";
2
+ import type { ItemSettings, ServedContentIdentity } from "@pie-players/pie-players-shared/types";
3
3
  import type { MediaTimeSource } from "@pie-players/pie-players-shared/timed-media";
4
4
  export declare const PIE_REGISTER_EVENT = "pie-register";
5
5
  export declare const PIE_UNREGISTER_EVENT = "pie-unregister";
6
6
  export declare const PIE_INTERNAL_ITEM_SESSION_CHANGED_EVENT = "pie-item-session-changed";
7
7
  export declare const PIE_ITEM_SESSION_CHANGED_EVENT = "item-session-changed";
8
+ export declare const PIE_ITEM_PLAYER_EVENT = "item-player-event";
9
+ /**
10
+ * The item-player events an item scope in a section relays as
11
+ * `item-player-event`. Each keeps its own behaviour: `load-complete` and
12
+ * `player-error` still stop at the scope, the rest still bubble.
13
+ */
14
+ export declare const RELAYED_ITEM_PLAYER_EVENTS: readonly ["load-complete", "player-error", "correct-responses-populated", "bundle-retry-status", "session-snapshot-available", "backend-load-complete", "backend-model-complete", "backend-session-saved", "backend-score-complete", "backend-error"];
15
+ export type RelayedItemPlayerEventType = (typeof RELAYED_ITEM_PLAYER_EVENTS)[number];
8
16
  export declare const PIE_INTERNAL_CONTENT_LOADED_EVENT = "pie-content-loaded";
17
+ export declare const PIE_INTERNAL_CONTENT_IDENTITY_EVENT = "pie-content-identity";
9
18
  export declare const PIE_INTERNAL_ITEM_PLAYER_ERROR_EVENT = "pie-item-player-error";
10
- export declare const PIE_INTERNAL_FORMATIVE_ACTION_EVENT = "pie-formative-action";
19
+ export declare const PIE_INTERNAL_TRY_ACTION_EVENT = "pie-try-action";
11
20
  export declare const PIE_INTERNAL_MEDIA_TIME_SOURCE_EVENT = "pie-media-time-source";
12
21
  export type RuntimeRegistrationKind = "item" | "passage";
13
22
  export interface RuntimeRegistrationDetail {
@@ -36,6 +45,14 @@ export interface ItemSessionChangedDetail {
36
45
  /** Set when the change is a commit at a teardown, navigation or page-hidden seam. */
37
46
  sessionCommitReason?: SessionCommitReason;
38
47
  }
48
+ /** An item player's event, with the item it came from. */
49
+ export interface ItemPlayerEventDetail {
50
+ itemId: string;
51
+ canonicalItemId: string;
52
+ type: RelayedItemPlayerEventType;
53
+ /** The item player's own event detail. */
54
+ detail: unknown;
55
+ }
39
56
  export interface InternalItemSessionChangedDetail {
40
57
  itemId: string;
41
58
  session: unknown;
@@ -46,6 +63,16 @@ export interface InternalContentLoadedDetail {
46
63
  contentKind?: string;
47
64
  detail?: unknown;
48
65
  }
66
+ /**
67
+ * The content a backend served an item as, from the item player's
68
+ * `backend-load-complete`. `identity` is absent when a load reported none, which
69
+ * clears what an earlier load reported.
70
+ */
71
+ export interface InternalContentIdentityDetail {
72
+ itemId: string;
73
+ canonicalItemId?: string;
74
+ identity?: ServedContentIdentity;
75
+ }
49
76
  export interface InternalItemPlayerErrorDetail {
50
77
  itemId: string;
51
78
  canonicalItemId?: string;
@@ -53,7 +80,7 @@ export interface InternalItemPlayerErrorDetail {
53
80
  error: unknown;
54
81
  }
55
82
  /**
56
- * A learner's formative action, dispatched by the component that owns the
83
+ * A learner's Try action, dispatched by the component that owns the
57
84
  * control and the item player node — the only place that can call
58
85
  * `provideScore()`. It reports outcomes rather than interpreting them; the
59
86
  * section controller derives correctness and owns the state.
@@ -62,7 +89,7 @@ export interface InternalItemPlayerErrorDetail {
62
89
  * including the `undefined` slots it leaves for models with no element or
63
90
  * controller.
64
91
  */
65
- export interface InternalFormativeActionDetail {
92
+ export interface InternalTryActionDetail {
66
93
  itemId: string;
67
94
  canonicalItemId?: string;
68
95
  action: "check" | "retry";
@@ -2,7 +2,26 @@ export const PIE_REGISTER_EVENT = "pie-register";
2
2
  export const PIE_UNREGISTER_EVENT = "pie-unregister";
3
3
  export const PIE_INTERNAL_ITEM_SESSION_CHANGED_EVENT = "pie-item-session-changed";
4
4
  export const PIE_ITEM_SESSION_CHANGED_EVENT = "item-session-changed";
5
+ export const PIE_ITEM_PLAYER_EVENT = "item-player-event";
6
+ /**
7
+ * The item-player events an item scope in a section relays as
8
+ * `item-player-event`. Each keeps its own behaviour: `load-complete` and
9
+ * `player-error` still stop at the scope, the rest still bubble.
10
+ */
11
+ export const RELAYED_ITEM_PLAYER_EVENTS = [
12
+ "load-complete",
13
+ "player-error",
14
+ "correct-responses-populated",
15
+ "bundle-retry-status",
16
+ "session-snapshot-available",
17
+ "backend-load-complete",
18
+ "backend-model-complete",
19
+ "backend-session-saved",
20
+ "backend-score-complete",
21
+ "backend-error",
22
+ ];
5
23
  export const PIE_INTERNAL_CONTENT_LOADED_EVENT = "pie-content-loaded";
24
+ export const PIE_INTERNAL_CONTENT_IDENTITY_EVENT = "pie-content-identity";
6
25
  export const PIE_INTERNAL_ITEM_PLAYER_ERROR_EVENT = "pie-item-player-error";
7
- export const PIE_INTERNAL_FORMATIVE_ACTION_EVENT = "pie-formative-action";
26
+ export const PIE_INTERNAL_TRY_ACTION_EVENT = "pie-try-action";
8
27
  export const PIE_INTERNAL_MEDIA_TIME_SOURCE_EVENT = "pie-media-time-source";
@@ -3,7 +3,13 @@ import type { ShellContextKind } from "../context/assessment-toolkit-context.js"
3
3
  * `section`: the shell is its content's only channel to the section. The
4
4
  * player's `session-changed`, `load-complete` and `player-error` stop at the
5
5
  * shell and travel on as the runtime's internal events, with an item's
6
- * response changes also announced as `item-session-changed`.
6
+ * response changes also announced as `item-session-changed`. A session the
7
+ * player filled with the item's correct responses goes neither way: it renders
8
+ * in the player and never enters the section session. An item's
9
+ * host-actionable events are also announced as `item-player-event`, with the
10
+ * item's identity. The identity in
11
+ * an item's delivery `backend-load-complete` travels on too, for the section
12
+ * to record on the item's session; the event itself goes on to the host.
7
13
  *
8
14
  * `plain`: the host owns the player and listens to it, so the player's events
9
15
  * pass through untouched. The runtime still hears that the content loaded or
@@ -1,5 +1,5 @@
1
1
  import { commitPendingSessions, createPieLogger, normalizeItemSessionChange, } from "@pie-players/pie-players-shared";
2
- import { PIE_INTERNAL_CONTENT_LOADED_EVENT, PIE_INTERNAL_ITEM_PLAYER_ERROR_EVENT, PIE_INTERNAL_ITEM_SESSION_CHANGED_EVENT, PIE_ITEM_SESSION_CHANGED_EVENT, } from "./registration-events.js";
2
+ import { PIE_INTERNAL_CONTENT_IDENTITY_EVENT, PIE_INTERNAL_CONTENT_LOADED_EVENT, PIE_INTERNAL_ITEM_PLAYER_ERROR_EVENT, PIE_INTERNAL_ITEM_SESSION_CHANGED_EVENT, PIE_ITEM_PLAYER_EVENT, PIE_ITEM_SESSION_CHANGED_EVENT, RELAYED_ITEM_PLAYER_EVENTS, } from "./registration-events.js";
3
3
  import { dispatchCrossBoundaryEvent } from "./tool-host-contract.js";
4
4
  /**
5
5
  * Elements repeat themselves, a `complete` echo most often, so a session event
@@ -21,6 +21,9 @@ function sessionEventFingerprint(detail) {
21
21
  return String(semanticDetail);
22
22
  }
23
23
  }
24
+ const isCorrectResponseSession = (detail) => Boolean(detail &&
25
+ typeof detail === "object" &&
26
+ detail.sessionSource === "correct-response");
24
27
  const isCommit = (detail) => Boolean(detail &&
25
28
  typeof detail === "object" &&
26
29
  detail.sessionCommitReason);
@@ -70,6 +73,8 @@ export function createShellEventBridge(options) {
70
73
  if (kind !== "item")
71
74
  return;
72
75
  const detail = event.detail;
76
+ if (isCorrectResponseSession(detail))
77
+ return;
73
78
  const fingerprint = sessionEventFingerprint(detail);
74
79
  // A commit is the response's last chance to reach the section.
75
80
  if (!isCommit(detail) && fingerprint === lastForwardedFingerprint)
@@ -91,6 +96,22 @@ export function createShellEventBridge(options) {
91
96
  };
92
97
  send(PIE_INTERNAL_CONTENT_LOADED_EVENT, detail);
93
98
  };
99
+ const onBackendLoadComplete = (event) => {
100
+ if (mode() !== "section" || kind !== "item")
101
+ return;
102
+ const loaded = event.detail;
103
+ if (loaded?.scope !== "delivery")
104
+ return;
105
+ const { itemId, canonicalItemId } = identity();
106
+ if (!itemId)
107
+ return;
108
+ const detail = {
109
+ itemId,
110
+ canonicalItemId: canonicalItemId || itemId,
111
+ ...(loaded.identity ? { identity: loaded.identity } : {}),
112
+ };
113
+ send(PIE_INTERNAL_CONTENT_IDENTITY_EVENT, detail);
114
+ };
94
115
  const onPlayerError = (event) => {
95
116
  if (mode() === "section")
96
117
  event.stopPropagation();
@@ -105,9 +126,27 @@ export function createShellEventBridge(options) {
105
126
  };
106
127
  send(PIE_INTERNAL_ITEM_PLAYER_ERROR_EVENT, detail);
107
128
  };
129
+ const relayItemPlayerEvent = (event) => {
130
+ if (mode() !== "section" || kind !== "item")
131
+ return;
132
+ const { itemId, canonicalItemId } = identity();
133
+ if (!itemId)
134
+ return;
135
+ const payload = {
136
+ itemId,
137
+ canonicalItemId: canonicalItemId || itemId,
138
+ type: event.type,
139
+ detail: event.detail,
140
+ };
141
+ dispatchCrossBoundaryEvent(host, PIE_ITEM_PLAYER_EVENT, payload);
142
+ };
108
143
  host.addEventListener("session-changed", onSessionChanged);
109
144
  host.addEventListener("load-complete", onLoadComplete);
145
+ host.addEventListener("backend-load-complete", onBackendLoadComplete);
110
146
  host.addEventListener("player-error", onPlayerError);
147
+ for (const type of RELAYED_ITEM_PLAYER_EVENTS) {
148
+ host.addEventListener(type, relayItemPlayerEvent);
149
+ }
111
150
  return {
112
151
  disconnect: () => {
113
152
  // An escape from the commit must not strand the listeners it needed, so
@@ -120,7 +159,11 @@ export function createShellEventBridge(options) {
120
159
  finally {
121
160
  host.removeEventListener("session-changed", onSessionChanged);
122
161
  host.removeEventListener("load-complete", onLoadComplete);
162
+ host.removeEventListener("backend-load-complete", onBackendLoadComplete);
123
163
  host.removeEventListener("player-error", onPlayerError);
164
+ for (const type of RELAYED_ITEM_PLAYER_EVENTS) {
165
+ host.removeEventListener(type, relayItemPlayerEvent);
166
+ }
124
167
  }
125
168
  },
126
169
  };