@pie-players/pie-players-shared 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 (122) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +18 -17
  3. package/dist/THIRD-PARTY-LICENSES.txt +51 -0
  4. package/dist/components/vendor/nds/README.md +43 -5
  5. package/dist/components/vendor/nds/nds-icon-button.d.ts +2 -2
  6. package/dist/components/vendor/nds/nds-icon-button.js +2 -2
  7. package/dist/i18n/catalogs.d.ts +25 -13
  8. package/dist/i18n/catalogs.js +30 -22
  9. package/dist/i18n/content-language.d.ts +77 -0
  10. package/dist/i18n/content-language.js +129 -0
  11. package/dist/i18n/index.d.ts +7 -2
  12. package/dist/i18n/index.js +5 -2
  13. package/dist/i18n/language-tags.d.ts +3 -55
  14. package/dist/i18n/language-tags.js +3 -90
  15. package/dist/i18n/locale-load-error.d.ts +35 -0
  16. package/dist/i18n/locale-load-error.js +30 -0
  17. package/dist/i18n/messages/en-US.d.ts +151 -7
  18. package/dist/i18n/messages/en-US.js +168 -7
  19. package/dist/i18n/provider.d.ts +122 -18
  20. package/dist/i18n/provider.js +315 -133
  21. package/dist/i18n/pseudo.d.ts +34 -0
  22. package/dist/i18n/pseudo.js +106 -0
  23. package/dist/i18n/types.d.ts +19 -3
  24. package/dist/index.d.ts +16 -20
  25. package/dist/index.js +19 -19
  26. package/dist/instrumentation/providers/CompositeInstrumentationProvider.js +2 -1
  27. package/dist/item-session-control/index.d.ts +16 -0
  28. package/dist/item-session-control/index.js +5 -0
  29. package/dist/{formative → item-session-control}/mastery.d.ts +5 -5
  30. package/dist/{formative → item-session-control}/mastery.js +3 -3
  31. package/dist/{formative → item-session-control}/outcome.d.ts +3 -3
  32. package/dist/{formative → item-session-control}/outcome.js +2 -2
  33. package/dist/{formative → item-session-control}/policy.d.ts +11 -11
  34. package/dist/{formative → item-session-control}/policy.js +12 -12
  35. package/dist/item-session-control/session.d.ts +19 -0
  36. package/dist/{formative → item-session-control}/session.js +12 -12
  37. package/dist/{formative → item-session-control}/state.d.ts +26 -26
  38. package/dist/{formative → item-session-control}/state.js +13 -13
  39. package/dist/{formative → item-session-control}/types.d.ts +38 -40
  40. package/dist/{formative → item-session-control}/types.js +2 -2
  41. package/dist/loaders/ElementLoader.d.ts +1 -1
  42. package/dist/loaders/element-loader.d.ts +4 -1
  43. package/dist/loaders/element-loader.js +74 -21
  44. package/dist/loaders/element-package-spec.d.ts +16 -0
  45. package/dist/loaders/element-package-spec.js +30 -0
  46. package/dist/loaders/esm-adapter.d.ts +12 -1
  47. package/dist/loaders/esm-adapter.js +113 -19
  48. package/dist/loaders/iife-adapter.d.ts +7 -0
  49. package/dist/loaders/iife-adapter.js +1 -1
  50. package/dist/loaders/index.d.ts +2 -1
  51. package/dist/loaders/index.js +2 -1
  52. package/dist/loaders/preloaded-registration.d.ts +18 -6
  53. package/dist/loaders/preloaded-registration.js +44 -9
  54. package/dist/object/index.d.ts +4 -1
  55. package/dist/object/index.js +8 -1
  56. package/dist/pie/config.d.ts +8 -0
  57. package/dist/pie/config.js +32 -1
  58. package/dist/pie/index.d.ts +2 -0
  59. package/dist/pie/index.js +1 -0
  60. package/dist/pie/math-rendering.d.ts +13 -1
  61. package/dist/pie/math-rendering.js +54 -1
  62. package/dist/pie/updates.d.ts +4 -1
  63. package/dist/pie/updates.js +21 -5
  64. package/dist/pie/versioned-tag.d.ts +10 -0
  65. package/dist/pie/versioned-tag.js +27 -0
  66. package/dist/promise/index.d.ts +10 -0
  67. package/dist/promise/index.js +16 -0
  68. package/dist/security/overwide-regions.js +65 -0
  69. package/dist/security/private-hosts.d.ts +27 -0
  70. package/dist/security/private-hosts.js +85 -0
  71. package/dist/security/validate-style-url.js +2 -2
  72. package/dist/security/wrap-overwide-images.d.ts +6 -2
  73. package/dist/security/wrap-overwide-images.js +5 -2
  74. package/dist/security/wrap-overwide-tables.d.ts +6 -2
  75. package/dist/security/wrap-overwide-tables.js +5 -2
  76. package/dist/security/wrap-overwide.d.ts +13 -0
  77. package/dist/security/wrap-overwide.js +68 -3
  78. package/dist/timed-media/index.d.ts +1 -1
  79. package/dist/timed-media/index.js +1 -1
  80. package/dist/timed-media/policy.d.ts +2 -2
  81. package/dist/timed-media/policy.js +2 -2
  82. package/dist/timed-media/session.d.ts +1 -1
  83. package/dist/timed-media/session.js +1 -1
  84. package/dist/timed-media/types.d.ts +11 -11
  85. package/dist/tools/term-lookup.d.ts +15 -0
  86. package/dist/tools/term-lookup.js +16 -0
  87. package/dist/types/index.d.ts +127 -47
  88. package/dist/types/interchange.d.ts +116 -0
  89. package/dist/types/interchange.js +1 -0
  90. package/dist/ui/content-styles-entry.d.ts +1 -0
  91. package/dist/ui/content-styles-entry.js +2 -0
  92. package/dist/ui/content-styles.d.ts +24 -3
  93. package/dist/ui/content-styles.js +114 -3
  94. package/dist/ui/focus-trap.d.ts +12 -0
  95. package/dist/ui/focus-trap.js +41 -1
  96. package/dist/ui/fontawesome.d.ts +51 -0
  97. package/dist/ui/fontawesome.js +122 -0
  98. package/dist/ui/ime.d.ts +6 -0
  99. package/dist/ui/ime.js +10 -0
  100. package/dist/ui/overlay-containment.d.ts +13 -0
  101. package/dist/ui/overlay-containment.js +23 -0
  102. package/dist/ui/overlay-placement.d.ts +28 -0
  103. package/dist/ui/overlay-placement.js +17 -2
  104. package/package.json +72 -36
  105. package/dist/formative/index.d.ts +0 -16
  106. package/dist/formative/index.js +0 -5
  107. package/dist/formative/session.d.ts +0 -19
  108. package/dist/i18n/messages/nl-NL.d.ts +0 -529
  109. package/dist/i18n/messages/nl-NL.js +0 -529
  110. package/dist/instrumentation/new-relic-agent.d.ts +0 -20
  111. package/dist/loaders/module-shim.d.ts +0 -12
  112. package/dist/pie/authoring-tag.d.ts +0 -6
  113. package/dist/pie/configure-initialization.d.ts +0 -21
  114. package/dist/pie/correct-response-env.d.ts +0 -3
  115. package/dist/pie/element-announcements.d.ts +0 -39
  116. package/dist/pie/elements-rendered.d.ts +0 -23
  117. package/dist/pie/initialize-element.d.ts +0 -26
  118. package/dist/pie/markup-math.d.ts +0 -20
  119. package/dist/pie/resource-monitor.d.ts +0 -217
  120. package/dist/security/sanitize-forbidden-lists.d.ts +0 -8
  121. package/dist/ui/pointer-rotate.d.ts +0 -29
  122. package/dist/ui/safe-storage.d.ts +0 -2
@@ -1,6 +1,6 @@
1
- import type { FormativeFeedbackReveal, FormativeItemState, FormativeItemView, FormativeTryOutcome, ResolvedFormativePolicy } from "./types.js";
2
- export declare const FORMATIVE_ITEM_STATE_VERSION: 1;
3
- export declare function createFormativeItemState(itemIdentifier: string): FormativeItemState;
1
+ import type { FeedbackReveal, ItemTryState, ItemTryView, TryOutcome, ResolvedItemSessionControlPolicy } from "./types.js";
2
+ export declare const ITEM_TRY_STATE_VERSION: 1;
3
+ export declare function createItemTryState(itemIdentifier: string): ItemTryState;
4
4
  /**
5
5
  * Record one Try.
6
6
  *
@@ -8,24 +8,24 @@ export declare function createFormativeItemState(itemIdentifier: string): Format
8
8
  * state can be checked, so a second click landing before the projection
9
9
  * round-trips is dropped rather than spending a Try.
10
10
  */
11
- export declare function recordFormativeTry(args: {
12
- state?: FormativeItemState;
11
+ export declare function recordTry(args: {
12
+ state?: ItemTryState;
13
13
  itemIdentifier: string;
14
- policy: ResolvedFormativePolicy;
15
- outcome: FormativeTryOutcome;
16
- }): FormativeItemState;
14
+ policy: ResolvedItemSessionControlPolicy;
15
+ outcome: TryOutcome;
16
+ }): ItemTryState;
17
17
  /**
18
18
  * Dismiss a reveal and reopen the item for editing. Withdrawing `revealed` is
19
19
  * what withdraws the env override, so the item returns to the section's own
20
20
  * mode.
21
21
  *
22
22
  * A learner action, so it respects the Try budget: an item with none left keeps
23
- * its feedback on screen. `hideFormativeItem` is the host-authority version.
23
+ * its feedback on screen. `hideItemFeedback` is the host-authority version.
24
24
  */
25
- export declare function retryFormativeItem(args: {
26
- state?: FormativeItemState;
27
- policy: ResolvedFormativePolicy;
28
- }): FormativeItemState | undefined;
25
+ export declare function retryItem(args: {
26
+ state?: ItemTryState;
27
+ policy: ResolvedItemSessionControlPolicy;
28
+ }): ItemTryState | undefined;
29
29
  /**
30
30
  * Reveal on host authority — a teacher-driven "show the answer".
31
31
  *
@@ -38,23 +38,23 @@ export declare function retryFormativeItem(args: {
38
38
  * whatever response is there, including none, which is what "show the answer"
39
39
  * means before the learner has answered.
40
40
  */
41
- export declare function revealFormativeItem(args: {
42
- state?: FormativeItemState;
41
+ export declare function revealItemFeedback(args: {
42
+ state?: ItemTryState;
43
43
  itemIdentifier: string;
44
- policy: ResolvedFormativePolicy;
45
- feedback: Exclude<FormativeFeedbackReveal, "none">;
46
- }): FormativeItemState;
44
+ policy: ResolvedItemSessionControlPolicy;
45
+ feedback: Exclude<FeedbackReveal, "none">;
46
+ }): ItemTryState;
47
47
  /**
48
48
  * Withdraw a reveal on host authority. Unlike a learner retry this ignores the
49
49
  * Try budget: a host that revealed an item with no Tries left must be able to
50
50
  * put it back.
51
51
  */
52
- export declare function hideFormativeItem(args: {
53
- state?: FormativeItemState;
54
- policy: ResolvedFormativePolicy;
55
- }): FormativeItemState | undefined;
52
+ export declare function hideItemFeedback(args: {
53
+ state?: ItemTryState;
54
+ policy: ResolvedItemSessionControlPolicy;
55
+ }): ItemTryState | undefined;
56
56
  /** Derive everything a rendering component needs from policy plus state. */
57
- export declare function resolveFormativeItemView(args: {
58
- policy: ResolvedFormativePolicy;
59
- state?: FormativeItemState;
60
- }): FormativeItemView;
57
+ export declare function resolveItemTryView(args: {
58
+ policy: ResolvedItemSessionControlPolicy;
59
+ state?: ItemTryState;
60
+ }): ItemTryView;
@@ -1,7 +1,7 @@
1
- export const FORMATIVE_ITEM_STATE_VERSION = 1;
2
- export function createFormativeItemState(itemIdentifier) {
1
+ export const ITEM_TRY_STATE_VERSION = 1;
2
+ export function createItemTryState(itemIdentifier) {
3
3
  return {
4
- version: FORMATIVE_ITEM_STATE_VERSION,
4
+ version: ITEM_TRY_STATE_VERSION,
5
5
  itemIdentifier,
6
6
  tryCount: 0,
7
7
  revealed: false,
@@ -20,7 +20,7 @@ function shouldReveal(policy, tryCount) {
20
20
  return false;
21
21
  if (policy.revealOn === "on-try")
22
22
  return true;
23
- // Defensive: `resolveFormativePolicy` already coerces `"on-final-try"` to
23
+ // Defensive: `resolveItemSessionControl` already coerces `"on-final-try"` to
24
24
  // `"on-try"` under unlimited Tries, so this branch only guards a
25
25
  // hand-constructed policy.
26
26
  if (policy.maxTries === "unlimited")
@@ -34,8 +34,8 @@ function shouldReveal(policy, tryCount) {
34
34
  * state can be checked, so a second click landing before the projection
35
35
  * round-trips is dropped rather than spending a Try.
36
36
  */
37
- export function recordFormativeTry(args) {
38
- const current = args.state ?? createFormativeItemState(args.itemIdentifier);
37
+ export function recordTry(args) {
38
+ const current = args.state ?? createItemTryState(args.itemIdentifier);
39
39
  if (!args.policy.enabled)
40
40
  return current;
41
41
  const remaining = triesRemaining(args.policy, current.tryCount);
@@ -44,7 +44,7 @@ export function recordFormativeTry(args) {
44
44
  const tryCount = current.tryCount + 1;
45
45
  return {
46
46
  ...current,
47
- version: FORMATIVE_ITEM_STATE_VERSION,
47
+ version: ITEM_TRY_STATE_VERSION,
48
48
  itemIdentifier: args.itemIdentifier,
49
49
  tryCount,
50
50
  revealed: shouldReveal(args.policy, tryCount),
@@ -62,9 +62,9 @@ export function recordFormativeTry(args) {
62
62
  * mode.
63
63
  *
64
64
  * A learner action, so it respects the Try budget: an item with none left keeps
65
- * its feedback on screen. `hideFormativeItem` is the host-authority version.
65
+ * its feedback on screen. `hideItemFeedback` is the host-authority version.
66
66
  */
67
- export function retryFormativeItem(args) {
67
+ export function retryItem(args) {
68
68
  const current = args.state;
69
69
  if (!current || !args.policy.enabled)
70
70
  return current;
@@ -87,8 +87,8 @@ export function retryFormativeItem(args) {
87
87
  * whatever response is there, including none, which is what "show the answer"
88
88
  * means before the learner has answered.
89
89
  */
90
- export function revealFormativeItem(args) {
91
- const current = args.state ?? createFormativeItemState(args.itemIdentifier);
90
+ export function revealItemFeedback(args) {
91
+ const current = args.state ?? createItemTryState(args.itemIdentifier);
92
92
  if (!args.policy.enabled)
93
93
  return current;
94
94
  if (current.revealed && current.revealOverride === args.feedback) {
@@ -101,7 +101,7 @@ export function revealFormativeItem(args) {
101
101
  * Try budget: a host that revealed an item with no Tries left must be able to
102
102
  * put it back.
103
103
  */
104
- export function hideFormativeItem(args) {
104
+ export function hideItemFeedback(args) {
105
105
  const current = args.state;
106
106
  if (!current || !args.policy.enabled)
107
107
  return current;
@@ -119,7 +119,7 @@ function envOverrideFor(policy, revealed, revealOverride) {
119
119
  };
120
120
  }
121
121
  /** Derive everything a rendering component needs from policy plus state. */
122
- export function resolveFormativeItemView(args) {
122
+ export function resolveItemTryView(args) {
123
123
  const { policy } = args;
124
124
  const tryCount = args.state?.tryCount ?? 0;
125
125
  const revealed = args.state?.revealed === true;
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Formative delivery vocabulary.
2
+ * Item session control vocabulary.
3
3
  *
4
4
  * A **Try** is one submitted-for-checking pass over a single item. It is not
5
5
  * `TestAttemptSession` (the assessment administration) and not
@@ -7,11 +7,11 @@
7
7
  * an item). Both of those already own the word "attempt" in this codebase, at
8
8
  * two different scopes, which is why this contract does not use it.
9
9
  *
10
- * See `docs/prds/formative-delivery-contract.md` for the ratified contract and
10
+ * See `docs/prds/item-session-control-contract.md` for the ratified contract and
11
11
  * its QTI 3 mapping.
12
12
  */
13
13
  /** How many Tries a learner gets on one item. */
14
- export type FormativeTryLimit = number | "unlimited";
14
+ export type TryLimit = number | "unlimited";
15
15
  /**
16
16
  * What the learner sees after a Try.
17
17
  *
@@ -20,54 +20,52 @@ export type FormativeTryLimit = number | "unlimited";
20
20
  * `role: "instructor"`, which is the element convention for additionally
21
21
  * revealing the authored correct response.
22
22
  */
23
- export type FormativeFeedbackReveal = "none" | "correctness" | "solution";
23
+ export type FeedbackReveal = "none" | "correctness" | "solution";
24
24
  /** When a reveal happens: after every Try, or only once Tries are spent. */
25
- export type FormativeRevealTiming = "on-try" | "on-final-try";
25
+ export type FeedbackRevealTiming = "on-try" | "on-final-try";
26
26
  /**
27
- * Authored policy. Lives on `AssessmentSection.formative` as the section
28
- * default and on `AssessmentItemRef.formative` as a per-item override.
27
+ * Authored policy. Lives on `AssessmentSection.itemSessionControl` as the section
28
+ * default and on `AssessmentItemRef.itemSessionControl` as a per-item override.
29
29
  */
30
- export interface FormativeDeliveryPolicy {
30
+ export interface ItemSessionControlPolicy {
31
31
  /**
32
32
  * Absent or `false` leaves delivery exactly as it is without this contract:
33
33
  * no control, no projection, no state.
34
34
  */
35
35
  enabled?: boolean;
36
36
  /** Default 1. */
37
- maxTries?: FormativeTryLimit;
37
+ maxTries?: TryLimit;
38
38
  /** Default `"correctness"`. */
39
- feedback?: FormativeFeedbackReveal;
39
+ feedback?: FeedbackReveal;
40
40
  /** Default `"on-try"`. */
41
- revealOn?: FormativeRevealTiming;
41
+ revealOn?: FeedbackRevealTiming;
42
42
  }
43
- /** Same shape as the section policy; every field overrides independently. */
44
- export type FormativeItemPolicy = FormativeDeliveryPolicy;
45
43
  /** The policy after built-in defaults, section, and item ref are merged. */
46
- export interface ResolvedFormativePolicy {
44
+ export interface ResolvedItemSessionControlPolicy {
47
45
  enabled: boolean;
48
- maxTries: FormativeTryLimit;
49
- feedback: FormativeFeedbackReveal;
50
- revealOn: FormativeRevealTiming;
46
+ maxTries: TryLimit;
47
+ feedback: FeedbackReveal;
48
+ revealOn: FeedbackRevealTiming;
51
49
  }
52
50
  /**
53
51
  * `"unknown"` is the honest state for an item no loaded controller can score —
54
52
  * one holding a rubric element, or one whose element bundle exposes no
55
53
  * `outcome`. It is never collapsed into `"incorrect"`.
56
54
  */
57
- export type FormativeCorrectness = "correct" | "partial" | "incorrect" | "unknown";
55
+ export type TryCorrectness = "correct" | "partial" | "incorrect" | "unknown";
58
56
  /**
59
57
  * The subset of an element outcome that aggregation reads. `OutcomeResponse` is
60
58
  * assignable to this; the structural type keeps this module free of a
61
59
  * dependency on the entity types, which import policy types from here.
62
60
  */
63
- export interface FormativeScoredOutcome {
61
+ export interface ScoredElementOutcome {
64
62
  score?: number;
65
63
  max?: number;
66
64
  [key: string]: unknown;
67
65
  }
68
66
  /** The recorded result of one Try. */
69
- export interface FormativeTryOutcome {
70
- correctness: FormativeCorrectness;
67
+ export interface TryOutcome {
68
+ correctness: TryCorrectness;
71
69
  points?: number;
72
70
  max?: number;
73
71
  scoredElementCount: number;
@@ -84,10 +82,10 @@ export interface FormativeTryOutcome {
84
82
  * A trade: this persists inside the session slice, so a snapshot grows by
85
83
  * whatever the elements put in their outcomes — some include a scoring trace.
86
84
  */
87
- elementOutcomes?: FormativeScoredOutcome[];
85
+ elementOutcomes?: ScoredElementOutcome[];
88
86
  }
89
- /** Per-item delivery state. Persisted; see `FormativeSectionSlice`. */
90
- export interface FormativeItemState {
87
+ /** Per-item delivery state. Persisted; see `TrySectionSlice`. */
88
+ export interface ItemTryState {
91
89
  version: 1;
92
90
  itemIdentifier: string;
93
91
  tryCount: number;
@@ -98,7 +96,7 @@ export interface FormativeItemState {
98
96
  * reload restores the screen the learner left.
99
97
  */
100
98
  revealed: boolean;
101
- lastOutcome?: FormativeTryOutcome;
99
+ lastOutcome?: TryOutcome;
102
100
  /** 1-based Try on which the item first scored full credit. Never overwritten. */
103
101
  firstCorrectTry?: number;
104
102
  /**
@@ -106,19 +104,19 @@ export interface FormativeItemState {
106
104
  * than the learner earning it. Overrides the policy's `feedback` for the env
107
105
  * projection only — the policy still decides Tries.
108
106
  *
109
- * Set by `revealFormativeItem`, cleared by `hideFormativeItem` and by a
107
+ * Set by `revealItemFeedback`, cleared by `hideItemFeedback` and by a
110
108
  * learner retry, so a teacher-driven "show the answer" does not silently
111
109
  * upgrade every later reveal on that item.
112
110
  */
113
- revealOverride?: FormativeFeedbackReveal;
111
+ revealOverride?: FeedbackReveal;
114
112
  }
115
- /** The persisted slice, carried on `SectionControllerSessionState.formative`. */
116
- export interface FormativeSectionSlice {
113
+ /** The persisted slice, carried on `SectionControllerSessionState.tries`. */
114
+ export interface TrySectionSlice {
117
115
  version: 1;
118
- items: Record<string, FormativeItemState>;
116
+ items: Record<string, ItemTryState>;
119
117
  }
120
118
  /** Projected over the section env for one revealed item. */
121
- export interface FormativeEnvOverride {
119
+ export interface FeedbackEnvOverride {
122
120
  mode: "evaluate";
123
121
  role: "student" | "instructor";
124
122
  }
@@ -126,18 +124,18 @@ export interface FormativeEnvOverride {
126
124
  * What a rendering component needs, derived once so no component reimplements
127
125
  * the predicate. Carries no copy — wording belongs to the rendering package.
128
126
  */
129
- export interface FormativeItemView {
127
+ export interface ItemTryView {
130
128
  enabled: boolean;
131
129
  tryCount: number;
132
130
  triesRemaining: number | "unlimited";
133
131
  canCheck: boolean;
134
132
  canRetry: boolean;
135
133
  revealed: boolean;
136
- envOverride?: FormativeEnvOverride;
137
- lastOutcome?: FormativeTryOutcome;
134
+ envOverride?: FeedbackEnvOverride;
135
+ lastOutcome?: TryOutcome;
138
136
  }
139
137
  /** Section rollup over Try outcomes. */
140
- export interface FormativeMasteryRollup {
138
+ export interface MasteryRollup {
141
139
  version: 1;
142
140
  totalItems: number;
143
141
  /**
@@ -153,12 +151,12 @@ export interface FormativeMasteryRollup {
153
151
  complete: boolean;
154
152
  }
155
153
  /** The composition-model projection layouts read. */
156
- export interface FormativeSectionProjection {
154
+ export interface TrySectionProjection {
157
155
  version: 1;
158
156
  enabled: boolean;
159
- policies: Record<string, ResolvedFormativePolicy>;
160
- states: Record<string, FormativeItemState>;
161
- mastery: FormativeMasteryRollup;
157
+ policies: Record<string, ResolvedItemSessionControlPolicy>;
158
+ states: Record<string, ItemTryState>;
159
+ mastery: MasteryRollup;
162
160
  }
163
161
  /** The two learner actions a rendering component can request. */
164
- export type FormativeAction = "check" | "retry";
162
+ export type TryAction = "check" | "retry";
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Formative delivery vocabulary.
2
+ * Item session control vocabulary.
3
3
  *
4
4
  * A **Try** is one submitted-for-checking pass over a single item. It is not
5
5
  * `TestAttemptSession` (the assessment administration) and not
@@ -7,7 +7,7 @@
7
7
  * an item). Both of those already own the word "attempt" in this codebase, at
8
8
  * two different scopes, which is why this contract does not use it.
9
9
  *
10
- * See `docs/prds/formative-delivery-contract.md` for the ratified contract and
10
+ * See `docs/prds/item-session-control-contract.md` for the ratified contract and
11
11
  * its QTI 3 mapping.
12
12
  */
13
13
  export {};
@@ -41,4 +41,4 @@ export type ElementMap = {
41
41
  * // }
42
42
  * ```
43
43
  */
44
- export declare function aggregateElements(items: ItemEntity[]): ElementMap;
44
+ export declare function aggregateElements(items: ReadonlyArray<Pick<ItemEntity, "config">>): ElementMap;
@@ -88,7 +88,10 @@ export type EnsureRegisteredOptions = {
88
88
  *
89
89
  * The primitive is the sole authority on registration state:
90
90
  * - Empty element map resolves immediately (no backend call).
91
- * - Already-registered tags resolve immediately (no backend call).
91
+ * - Already-registered tags resolve immediately (no backend call). A request
92
+ * that loads other tags through an IIFE or ESM backend that loads controllers
93
+ * also loads its registered tags with no controller, so their controllers
94
+ * fill in.
92
95
  * - Concurrent identical requests share one backend call.
93
96
  * - After the adapter's `load` settles, a post-load verification pass
94
97
  * (bounded `customElements.whenDefined`) checks every tag. Any missing
@@ -26,7 +26,7 @@ import { parsePackageName } from "../pie/utils.js";
26
26
  import { parseVersionedTagName } from "../pie/versioned-tag.js";
27
27
  import { AdapterFailure, } from "./element-loader-types.js";
28
28
  import { clearPackageMetadataRequests, createEsmBackend, } from "./esm-adapter.js";
29
- import { createIifeBackend } from "./iife-adapter.js";
29
+ import { createIifeBackend, findIifeElementMapConflict, } from "./iife-adapter.js";
30
30
  import { assertElementPackagesAllowed, } from "./element-package-policy.js";
31
31
  export { AdapterFailure } from "./element-loader-types.js";
32
32
  /**
@@ -125,9 +125,10 @@ function registeredPackageName(tag) {
125
125
  }
126
126
  const DEFAULT_WHEN_DEFINED_TIMEOUT_MS = 5000;
127
127
  const DEFAULT_LOAD_TIMEOUT_MS = DEFAULT_IIFE_BUNDLE_RETRY_CONFIG.timeoutMs;
128
- // Module-scoped in-flight cache. Key: backend signature + sorted elements.
129
- // Keeps concurrent identical requests collapsed to one backend call.
128
+ // Requests share a backend call by both the original map and the unresolved
129
+ // subset, so incremental registration does not change an in-flight identity.
130
130
  const inFlightRequests = new Map();
131
+ const inFlightKeysByPromise = new Map();
131
132
  // An ESM backend keeps page state that later loads build on (the import maps it
132
133
  // injected, the shared dependency versions they fixed), so every load with the
133
134
  // same config reuses one backend. IIFE backends are created per call.
@@ -139,7 +140,10 @@ const resolvedBackendOverrides = new Map();
139
140
  *
140
141
  * The primitive is the sole authority on registration state:
141
142
  * - Empty element map resolves immediately (no backend call).
142
- * - Already-registered tags resolve immediately (no backend call).
143
+ * - Already-registered tags resolve immediately (no backend call). A request
144
+ * that loads other tags through an IIFE or ESM backend that loads controllers
145
+ * also loads its registered tags with no controller, so their controllers
146
+ * fill in.
143
147
  * - Concurrent identical requests share one backend call.
144
148
  * - After the adapter's `load` settles, a post-load verification pass
145
149
  * (bounded `customElements.whenDefined`) checks every tag. Any missing
@@ -153,30 +157,54 @@ export async function ensureRegistered(elements, options) {
153
157
  // Enforce policy before the already-registered fast path: a matching tag in
154
158
  // the registry must not turn a disallowed authored package into valid input.
155
159
  assertElementPackagesAllowed(elements, options.elementPackagePolicy);
156
- const tags = Object.keys(elements);
160
+ // Preserve the original request identity while tags register mid-flight.
161
+ const originalDedupKey = buildDedupKey(options.backend, elements);
162
+ const originalRequest = inFlightRequests.get(originalDedupKey);
163
+ if (originalRequest)
164
+ return originalRequest;
165
+ if (Object.keys(elements).every(isRegistered))
166
+ return;
167
+ const loadsControllers = backendLoadsControllers(options.backend);
168
+ const unresolvedElements = {};
169
+ for (const [tag, packageSpec] of Object.entries(elements)) {
170
+ if (!isRegistered(tag) || (loadsControllers && awaitsController(tag))) {
171
+ unresolvedElements[tag] = packageSpec;
172
+ }
173
+ }
174
+ const tags = Object.keys(unresolvedElements);
157
175
  const timeoutMs = options.whenDefinedTimeoutMs ?? DEFAULT_WHEN_DEFINED_TIMEOUT_MS;
158
176
  const loadTimeoutMs = options.loadTimeoutMs ?? DEFAULT_LOAD_TIMEOUT_MS;
159
- // Fast path: everything already registered. Skip backend and dedup
160
- // bookkeeping entirely.
161
- if (allAlreadyRegistered(tags))
162
- return;
163
- const dedupKey = buildDedupKey(options.backend, elements);
177
+ const dedupKey = buildDedupKey(options.backend, unresolvedElements);
164
178
  const existing = inFlightRequests.get(dedupKey);
165
- if (existing)
179
+ if (existing) {
180
+ aliasInFlightRequest(originalDedupKey, existing);
166
181
  return existing;
182
+ }
167
183
  const backend = resolveBackend(options.backend);
168
184
  const doc = resolveDoc(options.doc);
169
- const promise = runEnsureRegistered(elements, tags, backend, { doc, whenDefinedTimeoutMs: timeoutMs }, timeoutMs, loadTimeoutMs);
170
- inFlightRequests.set(dedupKey, promise);
185
+ const loadElements = isIifeConfig(options.backend)
186
+ ? iifeLoadElements(elements, unresolvedElements)
187
+ : unresolvedElements;
188
+ const promise = runEnsureRegistered(loadElements, tags, backend, { doc, whenDefinedTimeoutMs: timeoutMs }, timeoutMs, loadTimeoutMs);
189
+ aliasInFlightRequest(originalDedupKey, promise);
190
+ aliasInFlightRequest(dedupKey, promise);
171
191
  try {
172
192
  await promise;
173
193
  }
174
194
  finally {
175
- if (inFlightRequests.get(dedupKey) === promise) {
176
- inFlightRequests.delete(dedupKey);
195
+ for (const key of inFlightKeysByPromise.get(promise) ?? []) {
196
+ if (inFlightRequests.get(key) === promise)
197
+ inFlightRequests.delete(key);
177
198
  }
199
+ inFlightKeysByPromise.delete(promise);
178
200
  }
179
201
  }
202
+ function aliasInFlightRequest(key, promise) {
203
+ inFlightRequests.set(key, promise);
204
+ const keys = inFlightKeysByPromise.get(promise) ?? new Set();
205
+ keys.add(key);
206
+ inFlightKeysByPromise.set(promise, keys);
207
+ }
180
208
  async function runEnsureRegistered(elements, tags, backend, context, timeoutMs, loadTimeoutMs) {
181
209
  let adapterError;
182
210
  try {
@@ -273,13 +301,13 @@ function resolveBackend(backend) {
273
301
  if (isDirectBackend(backend))
274
302
  return backend;
275
303
  if ("kind" in backend) {
304
+ const backendKey = backendKeyOf(backend);
305
+ const override = resolvedBackendOverrides.get(backendKey);
306
+ if (override)
307
+ return override;
276
308
  if (backend.kind === "iife")
277
309
  return createIifeBackend(backend);
278
310
  if (backend.kind === "esm") {
279
- const backendKey = backendKeyOf(backend);
280
- const override = resolvedBackendOverrides.get(backendKey);
281
- if (override)
282
- return override;
283
311
  const existing = resolvedEsmBackends.get(backendKey);
284
312
  if (existing)
285
313
  return existing;
@@ -415,8 +443,32 @@ function getOpaqueObjectRefId(value) {
415
443
  }
416
444
  return id;
417
445
  }
418
- function allAlreadyRegistered(tags) {
419
- return tags.every((tag) => isRegistered(tag));
446
+ function isIifeConfig(backend) {
447
+ return !isDirectBackend(backend) && "kind" in backend && backend.kind === "iife";
448
+ }
449
+ /**
450
+ * An IIFE bundle URL names its packages, so the full map keeps it the URL a
451
+ * host already fetched. Two specs of one package cannot share a bundle, so a
452
+ * conflict narrows the map: first to the unresolved tags, then to the undefined.
453
+ */
454
+ function iifeLoadElements(elements, unresolvedElements) {
455
+ if (!findIifeElementMapConflict(elements))
456
+ return elements;
457
+ if (!findIifeElementMapConflict(unresolvedElements))
458
+ return unresolvedElements;
459
+ return Object.fromEntries(Object.entries(unresolvedElements).filter(([tag]) => !isRegistered(tag)));
460
+ }
461
+ function backendLoadsControllers(backend) {
462
+ if (isDirectBackend(backend) || !("kind" in backend))
463
+ return false;
464
+ if (backend.kind === "iife")
465
+ return backend.needsControllers ?? true;
466
+ if (backend.kind === "esm")
467
+ return backend.loadControllers ?? true;
468
+ return false;
469
+ }
470
+ function awaitsController(tag) {
471
+ return typeof window !== "undefined" && !pieRegistry()[tag]?.controller;
420
472
  }
421
473
  function isRegistered(tag) {
422
474
  if (typeof customElements === "undefined")
@@ -471,6 +523,7 @@ function extractAdapterReason(err, tag) {
471
523
  export const __testing = {
472
524
  resetDedupState() {
473
525
  inFlightRequests.clear();
526
+ inFlightKeysByPromise.clear();
474
527
  resolvedEsmBackends.clear();
475
528
  resolvedBackendOverrides.clear();
476
529
  clearPackageMetadataRequests();
@@ -0,0 +1,16 @@
1
+ /**
2
+ * Shape check for the package specs an item config names in `elements`.
3
+ *
4
+ * Loaders that build CDN URLs from a spec run it through
5
+ * `isScopedPackageSpec` first: item configs are authored content, and a
6
+ * version such as `1.0.0/../../../gh/owner/repo@main` would otherwise
7
+ * resolve to a path outside the package.
8
+ */
9
+ /**
10
+ * A scoped npm package name with an optional semver version or dist-tag, as
11
+ * item configs store it: `@pie-element/rubric`, `@pie-element/rubric@latest`,
12
+ * `@pie-element/rubric@8.0.0-hotfix.2`.
13
+ */
14
+ export declare function isScopedPackageSpec(spec: unknown): spec is string;
15
+ /** Why a loader refused `spec`, for its failure reason. */
16
+ export declare function invalidPackageSpecMessage(spec: unknown): string;
@@ -0,0 +1,30 @@
1
+ /**
2
+ * Shape check for the package specs an item config names in `elements`.
3
+ *
4
+ * Loaders that build CDN URLs from a spec run it through
5
+ * `isScopedPackageSpec` first: item configs are authored content, and a
6
+ * version such as `1.0.0/../../../gh/owner/repo@main` would otherwise
7
+ * resolve to a path outside the package.
8
+ */
9
+ const SEMVER_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
10
+ const DIST_TAG = /^[A-Za-z][A-Za-z0-9_-]*$/;
11
+ const SCOPED_PACKAGE_NAME = /^@[a-z0-9~-][a-z0-9._~-]*\/[a-z0-9~-][a-z0-9._~-]*$/;
12
+ /**
13
+ * A scoped npm package name with an optional semver version or dist-tag, as
14
+ * item configs store it: `@pie-element/rubric`, `@pie-element/rubric@latest`,
15
+ * `@pie-element/rubric@8.0.0-hotfix.2`.
16
+ */
17
+ export function isScopedPackageSpec(spec) {
18
+ if (typeof spec !== "string")
19
+ return false;
20
+ const versionAt = spec.indexOf("@", 1);
21
+ if (versionAt === -1)
22
+ return SCOPED_PACKAGE_NAME.test(spec);
23
+ const version = spec.slice(versionAt + 1);
24
+ return (SCOPED_PACKAGE_NAME.test(spec.slice(0, versionAt)) &&
25
+ (SEMVER_VERSION.test(version) || DIST_TAG.test(version)));
26
+ }
27
+ /** Why a loader refused `spec`, for its failure reason. */
28
+ export function invalidPackageSpecMessage(spec) {
29
+ return `Invalid element package spec ${JSON.stringify(String(spec))}: expected a scoped npm package name with an optional semver version or dist-tag`;
30
+ }
@@ -67,7 +67,8 @@ export declare function createEsmBackend(config: EsmBackendConfig): EsmBackend;
67
67
  export declare function mapEsmViewElements(elements: ElementMap, view?: string, viewConfig?: ViewConfig): ElementMap;
68
68
  /**
69
69
  * URL of a package's `./runtime-support` module on the ESM CDN the players load
70
- * elements from, or `undefined` when a custom provider names no package root.
70
+ * elements from, or `undefined` when a custom provider names no package root or
71
+ * `packageVersion` is not a scoped package spec.
71
72
  */
72
73
  export declare function resolveEsmRuntimeSupportUrl(packageVersion: string, options: {
73
74
  cdnBaseUrl: string;
@@ -84,4 +85,14 @@ export declare function resolveEsmAssetRoot(options: {
84
85
  cdnBaseUrl: string;
85
86
  cdnProvider?: EsmCdnProviderOption;
86
87
  }): string | undefined;
88
+ /**
89
+ * URL of a raw npm package file, `file` being `<package>@<version>/<path>`, on
90
+ * the ESM CDN a player's `loaderOptions` name, so a page asset the players add,
91
+ * such as a stylesheet, comes from where the elements do. Reads untyped options
92
+ * as a toolkit runtime context carries them; jsDelivr when they set no base.
93
+ */
94
+ export declare function resolveEsmPackageFileUrl(loaderOptions: {
95
+ esmCdnUrl?: unknown;
96
+ esmCdnProvider?: unknown;
97
+ } | null | undefined, file: string): string;
87
98
  export declare function pickElementClass(module: any, view: string): unknown;