@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
@@ -28,9 +28,9 @@ export declare function normalizeTimedMediaSectionData(args: {
28
28
  itemIdentifiers: readonly string[];
29
29
  resolveStimulusRenderableId: (stimulusRef: string) => string | undefined;
30
30
  /**
31
- * The Try budget each item's resolved formative policy leaves, so a gate on
31
+ * The Try budget each item's resolved item session control policy leaves, so a gate on
32
32
  * correctness can be refused where it would strand the learner. Supplied by the
33
- * caller because formative policy resolution is that contract's, not this one's.
33
+ * caller because item session control policy resolution is that contract's, not this one's.
34
34
  */
35
35
  resolveItemTryBudget: (itemIdentifier: string) => TimedMediaItemTryBudget;
36
36
  }): TimedMediaValidationResult;
@@ -240,7 +240,7 @@ export function normalizeTimedMediaSectionData(args) {
240
240
  // A correctness gate is only passable while the learner still has a Try
241
241
  // to spend. Over an item with a finite budget the gate becomes
242
242
  // unpassable the moment the budget runs out, and over an item that does
243
- // not deliver formatively there is never a Try at all — in both cases
243
+ // not enable item session control there is never a Try at all — in both cases
244
244
  // nothing the learner can do releases playback, and no host action
245
245
  // releases it either, because a forced reveal is not a correct answer.
246
246
  // Refused here rather than released at runtime: releasing would deliver
@@ -250,7 +250,7 @@ export function normalizeTimedMediaSectionData(args) {
250
250
  if (unpassable.length > 0) {
251
251
  errors.push({
252
252
  code: "gate-requires-unlimited-tries",
253
- message: `Gate cue "${identifier}" releases on correctness, so every item it names needs formative delivery with maxTries: "unlimited" — otherwise a learner who runs out of Tries can never release playback. Offending item refs: ${unpassable.join(", ")}.`,
253
+ message: `Gate cue "${identifier}" releases on correctness, so every item it names needs item session control with maxTries: "unlimited" — otherwise a learner who runs out of Tries can never release playback. Offending item refs: ${unpassable.join(", ")}.`,
254
254
  cueIdentifier: identifier,
255
255
  });
256
256
  continue;
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Persistence for the timed-media slice.
3
3
  *
4
- * Same posture as the formative slice: an unreadable slice is rejected whole and
4
+ * Same posture as the Try slice: an unreadable slice is rejected whole and
5
5
  * delivery starts from clean cue state, while item sessions in the same snapshot
6
6
  * are normalized separately and survive. A version bump here must never cost a
7
7
  * learner their responses.
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Persistence for the timed-media slice.
3
3
  *
4
- * Same posture as the formative slice: an unreadable slice is rejected whole and
4
+ * Same posture as the Try slice: an unreadable slice is rejected whole and
5
5
  * delivery starts from clean cue state, while item sessions in the same snapshot
6
6
  * are normalized separately and survive. A version bump here must never cost a
7
7
  * learner their responses.
@@ -9,7 +9,7 @@
9
9
  * See `docs/prds/timed-media-section-contract.md` for the ratified contract and
10
10
  * `docs/architecture/timed-media-section.md` for the layer-ownership record.
11
11
  */
12
- import type { FormativeCorrectness } from "../formative/types.js";
12
+ import type { TryCorrectness } from "../item-session-control/types.js";
13
13
  import type { MediaFragmentRange } from "../types/index.js";
14
14
  /**
15
15
  * What a cue does to the items it names.
@@ -23,15 +23,15 @@ export type TimedMediaCueActivation = "reveal" | "gate" | "metadata";
23
23
  /**
24
24
  * The condition over delivery state that releases a gate.
25
25
  *
26
- * Named from the shipped formative vocabulary rather than defined here, which is
27
- * the whole reason formative delivery sequenced first — see
26
+ * Named from the shipped Try vocabulary rather than defined here, which is
27
+ * the whole reason item session control sequenced first — see
28
28
  * `docs/adr/0001-formative-delivery-before-timed-media.md`. `"responded"` is the
29
29
  * response-only case, and it reads item completion rather than Try state so a
30
- * gate works in a section that does not deliver formatively at all.
30
+ * gate works in a section that does not enable item session control at all.
31
31
  */
32
32
  export type TimedMediaGateCondition = "responded" | "correct" | "partial-or-better";
33
33
  /**
34
- * What a gate does when the item cannot be auto-scored — `FormativeCorrectness`
34
+ * What a gate does when the item cannot be auto-scored — `TryCorrectness`
35
35
  * of `"unknown"`, which is the honest state of an item holding a rubric element
36
36
  * rather than a defect to design around.
37
37
  *
@@ -131,13 +131,13 @@ export interface ResolvedTimedMediaSectionData {
131
131
  scoringPolicy?: TimedMediaScoringPolicy;
132
132
  }
133
133
  /**
134
- * What a gated item's resolved formative policy leaves the learner.
134
+ * What a gated item's resolved item session control policy leaves the learner.
135
135
  *
136
136
  * Read by validation, not by the reduction: a gate on correctness over an item
137
137
  * with a finite Try budget is a dead end, and so is one over an item that does not
138
- * deliver formatively at all — no Try means no correctness, ever.
138
+ * enable item session control at all — no Try means no correctness, ever.
139
139
  */
140
- export type TimedMediaItemTryBudget = "unlimited" | "finite" | "not-formative";
140
+ export type TimedMediaItemTryBudget = "unlimited" | "finite" | "none";
141
141
  export interface TimedMediaValidationError {
142
142
  /** Machine-readable, so a host can branch without parsing prose. */
143
143
  code: "missing-stimulus-ref" | "unresolved-stimulus-ref"
@@ -219,7 +219,7 @@ export interface MediaTimeSource {
219
219
  /**
220
220
  * The persisted slice, carried on `SectionControllerSessionState.timedMedia`.
221
221
  *
222
- * One shape live and persisted, unlike formative's split between a per-item
222
+ * One shape live and persisted, unlike the Try state's split between a per-item
223
223
  * reducer state and a slice: timed-media state is section-scoped, so there is
224
224
  * nothing to key.
225
225
  */
@@ -241,14 +241,14 @@ export interface TimedMediaSectionSessionSlice {
241
241
  }
242
242
  /**
243
243
  * Delivery state a gate condition reads, supplied by the caller so this module
244
- * stays pure and depends on neither the controller nor the formative module's
244
+ * stays pure and depends on neither the controller nor the item session control module's
245
245
  * live state.
246
246
  */
247
247
  export interface TimedMediaDeliveryState {
248
248
  /** Item completion by canonical id: the `"responded"` condition's signal. */
249
249
  respondedByItemId: Record<string, boolean>;
250
250
  /** Last Try correctness by canonical id; absent means no Try yet. */
251
- correctnessByItemId: Record<string, FormativeCorrectness | undefined>;
251
+ correctnessByItemId: Record<string, TryCorrectness | undefined>;
252
252
  /** Whether every item in the section reports completion. */
253
253
  itemsComplete: boolean;
254
254
  }
@@ -13,6 +13,7 @@
13
13
  * corpus behind one is licensed per programme, so a host supplies either an endpoint
14
14
  * or a resolver of its own.
15
15
  */
16
+ import type { TextDirection } from "../i18n/types.js";
16
17
  /** What a host's term service is asked for. */
17
18
  export interface TermLookupRequest {
18
19
  /** The term, already normalised by {@link normalizeTerm}. */
@@ -187,3 +188,17 @@ export declare function termPanelStatusMessage<TItem>(state: TermPanelState<TIte
187
188
  countLabel: (count: number) => string;
188
189
  emptyLabel: (term: string) => string;
189
190
  }): string;
191
+ /**
192
+ * `lang` and `dir` for a lookup's results: the language the lookup asked in.
193
+ *
194
+ * Results are in the corpus's language, which is neither the panel's interface
195
+ * locale nor necessarily the content the term came from: a Spanish gloss for an
196
+ * English passage. Stamped on the results, an Arabic definition in an English panel
197
+ * reads and lays out as Arabic, and the panel's language never reaches the content.
198
+ * With no language named the corpus's is unknown, so the stamp is `lang=""` and
199
+ * `dir="auto"`, the one undeclared content gets.
200
+ */
201
+ export declare function termResultLanguage(language: string | undefined): {
202
+ lang: string;
203
+ dir: TextDirection | "auto";
204
+ };
@@ -13,6 +13,8 @@
13
13
  * corpus behind one is licensed per programme, so a host supplies either an endpoint
14
14
  * or a resolver of its own.
15
15
  */
16
+ import { toLanguageTag } from "../i18n/language-tags.js";
17
+ import { localeDirection } from "../i18n/provider.js";
16
18
  /** Longest term worth sending. Past this it is prose, not a headword. */
17
19
  export const MAX_LOOKUP_TERM_LENGTH = 80;
18
20
  /** Words a term may span. Generous enough for `carbon dioxide` and `mother in law`. */
@@ -282,3 +284,17 @@ export function termPanelStatusMessage(state, labels) {
282
284
  return labels.emptyLabel(state.term);
283
285
  return "";
284
286
  }
287
+ /**
288
+ * `lang` and `dir` for a lookup's results: the language the lookup asked in.
289
+ *
290
+ * Results are in the corpus's language, which is neither the panel's interface
291
+ * locale nor necessarily the content the term came from: a Spanish gloss for an
292
+ * English passage. Stamped on the results, an Arabic definition in an English panel
293
+ * reads and lays out as Arabic, and the panel's language never reaches the content.
294
+ * With no language named the corpus's is unknown, so the stamp is `lang=""` and
295
+ * `dir="auto"`, the one undeclared content gets.
296
+ */
297
+ export function termResultLanguage(language) {
298
+ const tag = toLanguageTag(language);
299
+ return tag ? { lang: tag, dir: localeDirection(tag) } : { lang: "", dir: "auto" };
300
+ }
@@ -8,10 +8,12 @@
8
8
  * them. The module depends on nothing beyond this package's own type modules,
9
9
  * so front-end and server code can both import it.
10
10
  */
11
- import type { FormativeDeliveryPolicy, FormativeItemPolicy, FormativeSectionSlice } from "../formative/types.js";
11
+ import type { ItemSessionControlPolicy, TrySectionSlice } from "../item-session-control/types.js";
12
12
  import type { TimedMediaSectionData, TimedMediaSectionSessionSlice } from "../timed-media/types.js";
13
- export type { FormativeDeliveryPolicy, FormativeItemPolicy };
13
+ import type { AdaptationLink, CurriculumStandard, LanguagePolicy, SkillLevel } from "./interchange.js";
14
+ export type { ItemSessionControlPolicy };
14
15
  export type { TimedMediaSectionData };
16
+ export type { AdaptationLink, ContentSubstitution, CurriculumStandard, LanguagePolicy, ServedContentIdentity, SkillLevel, } from "./interchange.js";
15
17
  export interface BaseEntity {
16
18
  id?: string;
17
19
  createdAt?: Date;
@@ -32,12 +34,6 @@ export interface VersionEntity extends BaseEntity {
32
34
  signature?: string;
33
35
  version: SemVer;
34
36
  }
35
- export interface SearchMetaData {
36
- [key: string]: any;
37
- }
38
- export interface SearchMetaDataEntity extends BaseEntity {
39
- searchMetaData?: SearchMetaData;
40
- }
41
37
  export interface ConfigElements {
42
38
  [key: string]: string;
43
39
  }
@@ -69,16 +65,36 @@ export interface ConfigEntity {
69
65
  export interface ConfigContainerEntity extends BaseEntity {
70
66
  config: ConfigEntity;
71
67
  }
72
- export interface PassageEntity extends VersionEntity, ConfigContainerEntity, SearchMetaDataEntity {
68
+ export interface PassageEntity extends VersionEntity, ConfigContainerEntity {
73
69
  name: string;
70
+ /**
71
+ * BCP 47 tag of the content's language (QTI `xml:lang`). The players render
72
+ * and score it under this language; absent, the section's `env.locale` holds.
73
+ */
74
+ language?: string;
75
+ /** The source a translated version was adapted from. No player reads it. */
76
+ isAdaptationOf?: AdaptationLink;
74
77
  /** QTI/APIP-style accessibility catalogs owned by this passage content. */
75
78
  accessibilityCatalogs?: AccessibilityCatalog[];
79
+ /**
80
+ * Standards and skills the content is aligned to. Absent means no data; `[]`
81
+ * means the writer states that none applies. No player reads it.
82
+ */
83
+ curriculumStandards?: CurriculumStandard[];
84
+ /** DOK and Bloom's classifications, on the same terms. No player reads it. */
85
+ skillLevels?: SkillLevel[];
76
86
  retired?: boolean;
77
87
  published?: boolean;
78
- highlights?: Record<string, string[]>;
79
88
  }
80
- export interface ItemEntity extends VersionEntity, ConfigContainerEntity, SearchMetaDataEntity {
89
+ export interface ItemEntity extends VersionEntity, ConfigContainerEntity {
81
90
  name?: string;
91
+ /**
92
+ * BCP 47 tag of the content's language (QTI `xml:lang`). The players render
93
+ * and score it under this language; absent, the section's `env.locale` holds.
94
+ */
95
+ language?: string;
96
+ /** The source a translated version was adapted from. No player reads it. */
97
+ isAdaptationOf?: AdaptationLink;
82
98
  /**
83
99
  * `null` as well as absent, because importers write it: JSON has no
84
100
  * `undefined`, so an item transformed from another format carries an
@@ -87,10 +103,16 @@ export interface ItemEntity extends VersionEntity, ConfigContainerEntity, Search
87
103
  passage?: string | PassageEntity | null;
88
104
  /** QTI/APIP-style accessibility catalogs owned by the item root. */
89
105
  accessibilityCatalogs?: AccessibilityCatalog[];
106
+ /**
107
+ * Standards and skills the content is aligned to. Absent means no data; `[]`
108
+ * means the writer states that none applies. No player reads it.
109
+ */
110
+ curriculumStandards?: CurriculumStandard[];
111
+ /** DOK and Bloom's classifications, on the same terms. No player reads it. */
112
+ skillLevels?: SkillLevel[];
90
113
  retired?: boolean;
91
114
  published?: boolean;
92
115
  configuration?: any;
93
- highlights?: Record<string, string[]>;
94
116
  }
95
117
  /**
96
118
  * `baseId` and `version` are optional on an entity a section references. They
@@ -110,19 +132,10 @@ export type ReferencedItemEntity = Omit<WithOptionalVersion<ItemEntity>, "passag
110
132
  passage?: string | ReferencedPassageEntity | null;
111
133
  };
112
134
  /**
113
- * Metadata specifically for interpretation by clients, typically containing
114
- * options that are relevant for the user interface. This is not indexed for search.
115
- */
116
- export interface SettingsMetaData {
117
- [key: string]: any;
118
- }
119
- /**
120
- * Objects that contain metadata in the settings property, which is NOT indexed for search
121
- * but typically only relevant for particular client cases.
135
+ * QTI 3 `qti-rubric-block@view` roles — the complete token set of the QTI 3.0
136
+ * ASI information model (v3p0p1). QTI 3 kebab-cases element names but keeps
137
+ * these camelCase attribute values unchanged from QTI 2.x.
122
138
  */
123
- export interface SettingsMetaDataEntity {
124
- settings?: SettingsMetaData;
125
- }
126
139
  export type RubricBlockView = "author" | "candidate" | "proctor" | "scorer" | "testConstructor" | "tutor";
127
140
  export interface RubricBlock {
128
141
  identifier?: string;
@@ -150,7 +163,7 @@ export interface RubricBlock {
150
163
  * References an item within a section. The item property contains the resolved
151
164
  * ItemEntity with its PIE config.
152
165
  */
153
- export interface AssessmentItemRef extends SearchMetaDataEntity {
166
+ export interface AssessmentItemRef extends BaseEntity {
154
167
  id?: string;
155
168
  identifier: string;
156
169
  title?: string;
@@ -167,15 +180,15 @@ export interface AssessmentItemRef extends SearchMetaDataEntity {
167
180
  /** Item-level settings for tool requirements and customization */
168
181
  settings?: ItemSettings;
169
182
  /**
170
- * Formative delivery override for this item. Every field overrides the
171
- * section's `formative` policy independently, which is the order QTI 3 uses
183
+ * Item session control override for this item. Every field overrides the
184
+ * section's `itemSessionControl` policy independently, which is the order QTI 3 uses
172
185
  * for `qti-item-session-control` on an item ref versus its section.
173
186
  *
174
- * See `docs/prds/formative-delivery-contract.md`.
187
+ * See `docs/prds/item-session-control-contract.md`.
175
188
  */
176
- formative?: FormativeItemPolicy;
189
+ itemSessionControl?: ItemSessionControlPolicy;
177
190
  }
178
- export interface AssessmentSection extends SearchMetaDataEntity, SettingsMetaDataEntity {
191
+ export interface AssessmentSection extends BaseEntity {
179
192
  id?: string;
180
193
  identifier: string;
181
194
  title?: string;
@@ -200,15 +213,15 @@ export interface AssessmentSection extends SearchMetaDataEntity, SettingsMetaDat
200
213
  assessmentItemRefs?: AssessmentItemRef[];
201
214
  rubricBlocks?: RubricBlock[];
202
215
  /**
203
- * Formative delivery policy for this section: how many Tries a learner gets
216
+ * Item session control policy for this section: how many Tries a learner gets
204
217
  * on each item, when feedback is revealed, and whether the behavior is on at
205
218
  * all. Absent or `enabled: false` delivers exactly as a section without this
206
219
  * field — no control, no state, no env override.
207
220
  *
208
- * Individual items override it through `AssessmentItemRef.formative`. See
209
- * `docs/prds/formative-delivery-contract.md`.
221
+ * Individual items override it through `AssessmentItemRef.itemSessionControl`. See
222
+ * `docs/prds/item-session-control-contract.md`.
210
223
  */
211
- formative?: FormativeDeliveryPolicy;
224
+ itemSessionControl?: ItemSessionControlPolicy;
212
225
  /**
213
226
  * The section flavor. Absent for every section authored so far, and the only
214
227
  * value is `"timed-media"`, which pairs with `timedMedia` below.
@@ -233,8 +246,20 @@ export interface AssessmentSection extends SearchMetaDataEntity, SettingsMetaDat
233
246
  export interface TestPart {
234
247
  id?: string;
235
248
  identifier: string;
236
- navigationMode: "linear" | "nonlinear";
237
- submissionMode: "individual" | "simultaneous";
249
+ /**
250
+ * QTI 3.0 import metadata (`qti-test-part@navigation-mode`), declared for
251
+ * structural fidelity and read by no player. PIE delivery is index-linear
252
+ * over the flattened section plan whatever this says, so it stays optional
253
+ * rather than requiring a value the runtime cannot honor.
254
+ */
255
+ navigationMode?: "linear" | "nonlinear";
256
+ /**
257
+ * QTI 3.0 import metadata (`qti-test-part@submission-mode`), declared for
258
+ * structural fidelity and read by no player. How an item commits its
259
+ * response is delivery policy (ADR 0005, `sessionCommitContext`), not this
260
+ * field.
261
+ */
262
+ submissionMode?: "individual" | "simultaneous";
238
263
  sections: AssessmentSection[];
239
264
  }
240
265
  /**
@@ -250,19 +275,19 @@ export interface SectionControllerSessionState {
250
275
  visitedItemIdentifiers?: string[];
251
276
  itemSessions: Record<string, unknown>;
252
277
  /**
253
- * Formative delivery state — Try counts and reveal state per item.
278
+ * Try state — Try counts and reveal state per item.
254
279
  *
255
280
  * Optional, and its absence is indistinguishable from a snapshot saved
256
- * before formative delivery existed, which is what keeps existing persisted
281
+ * before item session control existed, which is what keeps existing persisted
257
282
  * sessions valid. A slice with an unrecognized `version` is rejected whole
258
- * and formative state starts clean; `itemSessions` in the same snapshot is
259
- * unaffected, so a formative version bump never costs a learner responses.
283
+ * and Try state starts clean; `itemSessions` in the same snapshot is
284
+ * unaffected, so a Try slice version bump never costs a learner responses.
260
285
  */
261
- formative?: FormativeSectionSlice;
286
+ tries?: TrySectionSlice;
262
287
  /**
263
288
  * Timed-media delivery state — media progress, cue visits and completions.
264
289
  *
265
- * Same posture as `formative`: optional, absence indistinguishable from a
290
+ * Same posture as `tries`: optional, absence indistinguishable from a
266
291
  * pre-timed-media snapshot, and an unrecognized `version` rejected whole so
267
292
  * cue progress restarts while item sessions in the same snapshot are applied
268
293
  * untouched.
@@ -464,11 +489,27 @@ export interface AccessibilityCatalog {
464
489
  identifier: string;
465
490
  cards: CatalogCard[];
466
491
  }
492
+ /**
493
+ * A learner's personal needs profile, in tool ids. An AfA PNP 3.0 record maps to
494
+ * it through the AfA adapter the packaged tool set exports.
495
+ */
467
496
  export interface PersonalNeedsProfile {
497
+ /** Tools the learner may turn on. */
468
498
  supports: string[];
499
+ /** Tools withheld from the learner; a prohibition outranks a support. */
469
500
  prohibitedSupports?: string[];
501
+ /**
502
+ * Tools granted as `supports` grants them and turned on when the learner's
503
+ * toolbar first shows them. A block withdraws them as it withdraws a support.
504
+ */
505
+ activateAtInit?: string[];
506
+ /**
507
+ * Parameters by tool id, the lowest layer: the assessment's and an item's
508
+ * `toolParameters` override them key by key.
509
+ */
510
+ toolParameters?: ToolParameters;
470
511
  }
471
- export interface AssessmentEntity extends BaseEntity, SearchMetaDataEntity {
512
+ export interface AssessmentEntity extends BaseEntity {
472
513
  name?: string;
473
514
  title?: string;
474
515
  identifier?: string;
@@ -481,8 +522,18 @@ export interface AssessmentEntity extends BaseEntity, SearchMetaDataEntity {
481
522
  contextDeclarations?: ContextDeclaration[];
482
523
  /** QTI 3.0: Integrated APIP accessibility catalogs */
483
524
  accessibilityCatalogs?: AccessibilityCatalog[];
484
- /** QTI 3.0: Personal Needs Profile (PNP 3.0) */
525
+ /**
526
+ * A learner's Personal Needs Profile in PIE tool ids — the AfA PNP 3.0
527
+ * vocabulary, shaped through the adapter in `@pie-players/default-tool-loaders`
528
+ * (`createPersonalNeedsProfileFromAfa`). This is not a QTI structure and not
529
+ * an AfA record itself.
530
+ */
485
531
  personalNeedsProfile?: PersonalNeedsProfile;
532
+ /**
533
+ * The languages the assessment is offered in, read by a backend that
534
+ * resolves language variants. No player reads it.
535
+ */
536
+ languagePolicy?: LanguagePolicy;
486
537
  /**
487
538
  * QTI 3.0: testParts structure (authoritative for QTI format).
488
539
  */
@@ -509,8 +560,9 @@ export interface AssessmentSettings {
509
560
  toolOverrides?: Record<string, boolean>;
510
561
  };
511
562
  /**
512
- * Parameters by tool id, handed to the tool wherever policy shows it; an
513
- * item's `toolParameters` entry wins on that item's own toolbar. Provider
563
+ * Parameters by tool id, handed to the tool wherever policy shows it. They
564
+ * override the profile's `toolParameters` key by key, and an item's
565
+ * `toolParameters` override them on that item's own toolbar. Provider
514
566
  * configuration belongs in the toolkit's `tools.providers`.
515
567
  */
516
568
  toolParameters?: ToolParameters;
@@ -531,6 +583,26 @@ export interface ToolParameterMap {
531
583
  signLanguage: {
532
584
  signLang?: string;
533
585
  };
586
+ /**
587
+ * `language` is the BCP 47 content language the learner reads items in. A
588
+ * host passes it to delivery as `requestedLanguages`.
589
+ */
590
+ itemTranslation: {
591
+ language?: string;
592
+ };
593
+ /**
594
+ * `rate` multiplies every playback speed, 1 being the provider's normal
595
+ * speed; `pitch` runs 0–2 with 1 normal; `volume` runs 0–1.
596
+ */
597
+ textToSpeech: {
598
+ rate?: number;
599
+ pitch?: number;
600
+ volume?: number;
601
+ };
602
+ /** `zoom` is the lens's starting magnification, 2 meaning twice the size. */
603
+ magnification: {
604
+ zoom?: number;
605
+ };
534
606
  }
535
607
  /** The parameter shape of tool `K`: its {@link ToolParameterMap} entry, else open. */
536
608
  export type ToolParametersFor<K extends string> = K extends keyof ToolParameterMap ? ToolParameterMap[K] : Record<string, unknown>;
@@ -547,7 +619,7 @@ export type ToolParameters = {
547
619
  export interface ItemSettings {
548
620
  requiredTools?: string[];
549
621
  restrictedTools?: string[];
550
- /** Parameters by tool id; outranks the assessment's `toolParameters` entry. */
622
+ /** Parameters by tool id; override the assessment's key by key. */
551
623
  toolParameters?: ToolParameters;
552
624
  }
553
625
  export type PlayerMode = "gather" | "view" | "evaluate" | "author";
@@ -556,6 +628,14 @@ export interface Env {
556
628
  mode: PlayerMode;
557
629
  role: PlayerRole;
558
630
  partialScoring?: boolean;
631
+ /**
632
+ * BCP 47 tag of the language the item's content is written in, when the
633
+ * delivery knows it. The player reflects it onto the content subtree as
634
+ * `lang`/`dir`; a host that emits nothing leaves the content unstamped.
635
+ * The interface locale never travels here — it is the player's `locale`
636
+ * attribute and the `pie.interfaceLocale` context.
637
+ */
638
+ locale?: string;
559
639
  }
560
640
  /** The `detail` of the `player-error` event `pie-item-player` dispatches. */
561
641
  export interface PieItemPlayerErrorDetail {
@@ -0,0 +1,116 @@
1
+ /**
2
+ * Interchange types: backends and authoring tools exchange them, and no player
3
+ * reads them. Their tier is listed on the content-model page.
4
+ *
5
+ * Language variants (PIE-1393): no player reads `AdaptationLink` or
6
+ * `LanguagePolicy`.
7
+ * A language variant is its own item or passage version that declares
8
+ * `language` and, when it is a translation, `isAdaptationOf`. Its family is
9
+ * `isAdaptationOf.baseId ?? baseId`.
10
+ */
11
+ import type { SemVer } from "./index.js";
12
+ /** The source a translated item or passage was adapted from. */
13
+ export interface AdaptationLink {
14
+ baseId: string;
15
+ /** The source version translated. Absent when provenance is unknown. */
16
+ version?: SemVer;
17
+ }
18
+ /**
19
+ * The languages an assessment offers and what a backend serves when a family
20
+ * has no variant in the requested language.
21
+ */
22
+ export interface LanguagePolicy {
23
+ /** BCP 47 tags the assessment may be served in. */
24
+ languages: string[];
25
+ /**
26
+ * `"default"` serves an item whose family lacks the requested language in
27
+ * the closest match for the platform default, `en-US` (so `en` or `en-GB`),
28
+ * then its content that declares no language, then its source. Fallback is
29
+ * per item; items sharing a passage fall back together. `"none"` fails the
30
+ * load.
31
+ */
32
+ fallback: "default" | "none";
33
+ /**
34
+ * `"closest"`, the default, serves the nearest variant in the requested
35
+ * language, so `es-MX` reaches `es` or `es-ES`; `"exact"` serves only an
36
+ * equal tag and leaves anything else to `fallback`.
37
+ */
38
+ matching?: "closest" | "exact";
39
+ /**
40
+ * `"serve"` serves a variant whose source has a newer release and records
41
+ * it as stale; `"require-current"` treats that variant as missing.
42
+ */
43
+ staleness: "serve" | "require-current";
44
+ }
45
+ /**
46
+ * Why the served content differs from what was requested: `"fallback"`, not
47
+ * in a requested language; `"variety"`, in another variety of a requested
48
+ * language, such as `es-ES` for `es-MX`; `"stale"`, a translation of an older
49
+ * source release.
50
+ */
51
+ export type ContentSubstitution = "fallback" | "stale" | "variety";
52
+ /** The content version a backend served, and the language it served it in. */
53
+ export interface ServedContentIdentity {
54
+ baseId: string;
55
+ version?: SemVer;
56
+ /** The family key, when the served version belongs to a variant family. */
57
+ family?: string;
58
+ /** BCP 47 tag of the served content. */
59
+ servedLanguage?: string;
60
+ substitution?: ContentSubstitution;
61
+ }
62
+ /**
63
+ * One curriculum standard, skill or competency the content is aligned to
64
+ * (PIE-1381). QTI 3 Curriculum Standards Metadata (CSM 1.1), one entry per
65
+ * `labelledGUID`. Content records direct links only; a framework provider
66
+ * resolves parents, crosswalks and successors on read.
67
+ */
68
+ export interface CurriculumStandard {
69
+ /**
70
+ * CSM `curriculumStandardsMetadata@providerId`: who issued `guid`, from the
71
+ * provider-id registry on the content-model page, or a host value. Absent
72
+ * means `"AB"` (Academic Benchmarks).
73
+ */
74
+ providerId?: string;
75
+ /**
76
+ * CSM `labelledGUID/GUID`, as the provider issued it. Stored with its case
77
+ * and compared case-insensitively.
78
+ */
79
+ guid: string;
80
+ /** CSM `labelledGUID/caseItemURI`, for a CASE framework item. */
81
+ caseItemURI?: string;
82
+ /** CSM `labelledGUID/label`: a display code. Never a key. */
83
+ label?: string;
84
+ /** LOM classification purpose. Absent means `"educational objective"`. */
85
+ purpose?: "educational objective" | "prerequisite" | (string & {});
86
+ /** The record's main standard for this provider. At most one per `providerId`. */
87
+ primary?: boolean;
88
+ /** How the link was made. */
89
+ provenance?: "authored" | "derived" | "imported";
90
+ /**
91
+ * For a derived link: the link it was generated from. An absent
92
+ * `providerId` means `"AB"`.
93
+ */
94
+ derivedFrom?: {
95
+ providerId?: string;
96
+ guid: string;
97
+ };
98
+ }
99
+ /**
100
+ * A cognitive-complexity classification of the content (PIE-1381). LOM
101
+ * classification purpose "skill level".
102
+ */
103
+ export interface SkillLevel {
104
+ /**
105
+ * LOM `taxonPath/source`: `"webb-dok"`, `"blooms-revised"`,
106
+ * `"blooms-original"`, or a host taxonomy.
107
+ */
108
+ source: string;
109
+ /**
110
+ * LOM `taxon/id`: `"1"` to `"4"` for `webb-dok`; `"remember"` to `"create"`
111
+ * for `blooms-revised`.
112
+ */
113
+ id: string;
114
+ /** PIE extension: the author's justification. */
115
+ rationale?: string;
116
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1 @@
1
+ export { adoptContentStylesInto, auditContentStyles, type ContentStylesAdoption, type ContentStylesResult, contentStylesOptedOut, contentStylesPresent, installContentStyles, } from "./content-styles.js";
@@ -0,0 +1,2 @@
1
+ // The `./ui/content-styles` entry: the module's exports less its test-only reset.
2
+ export { adoptContentStylesInto, auditContentStyles, contentStylesOptedOut, contentStylesPresent, installContentStyles, } from "./content-styles.js";