@pie-players/pie-players-shared 1.0.0-beta.7 → 1.0.0-beta.9

package/README.md

@@ -2,7 +2,7 @@
 
 Shared runtime utilities for the `@pie-players/*` player suite: the element
 loader, PIE config and session helpers, markup security, i18n, and the
-formative, timed-media and media contracts. For framework code and host
+item session control, timed-media and media contracts. For framework code and host
 integrations that need the helpers the player packages use.
 
 ## Public Exports
@@ -20,9 +20,10 @@ The subpaths below are the package's `exports`; nothing else is importable.
 | `@pie-players/pie-players-shared` | The root: the loader, PIE, security and object helpers, loader config, instrumentation providers, the item-player strategy helpers, the default bundle host URL (`BUILDER_BUNDLE_URL`), a subset of the shared types, and the UI helpers (attribute coercion, content styles, pointer gestures, overlay placement, focus trap, safe storage, scoped CSS) |
 | `/loader-config` | `LoaderConfig` and its defaults: instrumentation (`trackPageActions`, `instrumentationProvider`), resource retry, and IIFE bundle retry |
 | `/security` | The item-markup sanitizer (`sanitizeItemMarkup`, `createDefaultItemMarkupSanitizer`, `buildAuthoringAllowList`), external-stylesheet URL validation, the SVG icon and `style` attribute sanitizers, and the wrappers that put overwide images and tables in a scrollable region |
+| `/security/private-hosts` | `isPrivateHostname` and `isCloudMetadataHostname`, the host classification for a URL a server fetches on someone else's behalf. Node-safe: it loads none of the markup sanitizers |
 | `/object` | `mergeObjectsIgnoringNullUndefined`, `cloneDeep`, `isPlainRecord` |
 | `/types` | The shared types: item, passage, section and session entities, PIE models and controllers, accessibility catalogs, and the [media vocabulary](#media-validation) |
-| `/formative` | [Formative delivery](#formative-delivery) |
+| `/item-session-control` | [Item session control](#item-session-control) |
 | `/timed-media` | [Timed media](#timed-media) |
 | `/media` | [Media validation](#media-validation) |
 | `/pie` | PIE runtime utilities: config helpers, bundle initialization, `ItemController` and the item session contract, session commit and snapshots, authoring helpers, math renderer setup, instrumentation event maps ([PIE utilities](src/pie/README.md)) |
@@ -33,14 +34,15 @@ The subpaths below are the package's `exports`; nothing else is importable.
 | `/i18n/provider` | `SimpleI18n`, `getDefaultI18n` and `resolveInterfaceI18n`, with the English catalog only |
 | `/i18n/catalogs` | `BUNDLED_LOCALES` and lazy loaders for the bundled locales other than English |
 | `/i18n/language-tags` | BCP 47 language tag normalization and matching |
-| `/nds-icon-button` | `<nds-icon-button>`, an icon button vendored as a prebuilt bundle with Lit inlined; importing it registers the tag. The assessment toolkit and `@pie-players/pie-tool-tts-inline` render it |
+| `/nds-icon-button` | `<nds-icon-button>`, an icon button vendored as a prebuilt bundle with Lit inlined; importing it registers the tag. The assessment toolkit, the section player and `@pie-players/pie-tool-tts-inline` render it |
 | `/ui/attribute-coercion` | Boolean attribute coercion for custom elements |
 | `/ui/content-styles` | `installContentStyles`, `auditContentStyles` and the opt-out checks behind the item player's content styles |
+| `/ui/fontawesome` | The FontAwesome `<nds-icon-button>` glyphs need: the one FA Free pin, Pro detection, the `<head>` and shadow-root installs, and the glyph weight. The assessment toolkit, the section player and `@pie-players/pie-tool-tts-inline` use it |
 | `/tools/term-lookup` | Term normalization and the lookup session the dictionary tools share; the host supplies the endpoint or a resolver |
 
-## Formative Delivery
+## Item Session Control
 
-`@pie-players/pie-players-shared/formative` holds the policy resolution, outcome
+`@pie-players/pie-players-shared/item-session-control` holds the policy resolution, outcome
 aggregation, Try-state reducer, item view, and mastery rollup that
 `pie-section-player` drives. It is pure (no DOM, no timers, no element
 registry), so it is testable without a browser and importable by an adapter that
@@ -48,18 +50,18 @@ has no player.
 
 ```ts
 import {
-  aggregateFormativeOutcome,
-  resolveFormativePolicy,
-  resolveFormativeItemView,
-  rollupFormativeMastery,
-} from "@pie-players/pie-players-shared/formative";
+  aggregateTryOutcome,
+  resolveItemSessionControl,
+  resolveItemTryView,
+  rollupMastery,
+} from "@pie-players/pie-players-shared/item-session-control";
 ```
 
-The authored half, `FormativeDeliveryPolicy` on `AssessmentSection` and
-`FormativeItemPolicy` on `AssessmentItemRef`, is re-exported from the package
+The authored half, `ItemSessionControlPolicy` on `AssessmentSection` and
+`AssessmentItemRef`, is re-exported from the package
 root and from `/types`, beside the section types it annotates.
 
-The contract is [`docs/prds/formative-delivery-contract.md`](../../docs/prds/formative-delivery-contract.md),
+The contract is [`docs/prds/item-session-control-contract.md`](../../docs/prds/item-session-control-contract.md),
 including the QTI 3 mapping and why PIE says **Try** rather than "attempt".
 
 ## Timed Media
@@ -92,7 +94,7 @@ re-exported from the package root and from `/types`, beside the section types it
 annotates.
 
 The contract is [`docs/prds/timed-media-section-contract.md`](../../docs/prds/timed-media-section-contract.md),
-including why cue gate conditions name the formative vocabulary and why an
+including why cue gate conditions name the Try vocabulary and why an
 unenforceable policy degrades to advisory rather than failing closed.
 
 ## Media Validation

package/dist/i18n/catalogs.d.ts

@@ -1,5 +1,5 @@
 /**
- * Lazy catalog loaders for every locale this repository ships.
+ * The bundled catalog loader: `en-US`, the one statically shipped catalog.
  *
  * Imported by players, never by tools. A tool resolves its provider from the
  * toolkit runtime context and needs only the interface plus the English
@@ -7,25 +7,32 @@
  * into a bundle that never calls `setLocale`, because every tool
  * `vite.config.ts` sets `external: []`.
  *
- * An explicit static map rather than a bundler macro: `tsc` emits these
- * `import()` calls verbatim, so `players-shared/dist` evaluates anywhere ESM
- * does — webpack, esbuild, Rollup, Node, or a browser loading the files
- * directly. `pie-qti` used `import.meta.glob` and shipped a `dist` that throws
- * under every one of those. Each bundler still sees the specifiers statically,
- * so each locale stays its own chunk. Adding a locale means adding one line here
- * alongside the file.
+ * `en-US` is the source of truth — the fallback for every missing key in every
+ * other locale — so the provider imports it statically and it is always
+ * resident. It is the only catalog this package ships: every other locale this
+ * repository ships lives in the optional generated tier
+ * (`@pie-players/pie-i18n-generated`), whose loaders a host composes after
+ * this one. The composed shape is that package's README's wiring example:
  *
- * `en-US` is absent: it is the fallback for every missing key in every other
- * locale, so the provider imports it statically and it is always resident.
+ * ```ts
+ * loadCatalog: (locale) =>
+ *   loadBundledCatalog(locale).catch(() => loadGeneratedCatalog(locale));
+ * ```
+ *
+ * A request this function cannot serve rejects, and the provider treats that
+ * as "resolve through the fallback chain" rather than an error, so a host
+ * locale nothing ships still renders English.
  *
  * @module @pie-players/pie-players-shared/i18n/catalogs
  */
 import type { BundledLocaleCode, MessageCatalog } from "./types.js";
 /**
- * Every locale tag this repository ships a catalog for, English included.
+ * Every locale tag this repository bundles a catalog for. `en-US` alone: the
+ * statically resident source of truth.
  *
  * The provider resolves a request against this list through RFC 4647 lookup and
- * primary-subtag widening, so `nl`, `nl_NL` and `nl-BE` all reach `nl-NL`.
+ * primary-subtag widening, so `en`, `en_US` and `en-GB`-without-a-catalog all
+ * land on `en-US` unless a composed loader serves the region.
  */
 export declare const BUNDLED_LOCALES: readonly BundledLocaleCode[];
 /**
@@ -36,7 +43,7 @@ export declare const BUNDLED_LOCALES: readonly BundledLocaleCode[];
  * or a pseudo-localization of the English catalog — asks for it by name like
  * any other locale.
  *
- * Throws for a locale with no shipped catalog; the provider treats that as
+ * Rejects for a locale with no bundled catalog; the provider treats that as
  * "resolve through the fallback chain" rather than an error, so a host locale we
  * do not ship still renders.
  */

package/dist/i18n/catalogs.js

@@ -1,5 +1,5 @@
 /**
- * Lazy catalog loaders for every locale this repository ships.
+ * The bundled catalog loader: `en-US`, the one statically shipped catalog.
  *
  * Imported by players, never by tools. A tool resolves its provider from the
  * toolkit runtime context and needs only the interface plus the English
@@ -7,30 +7,34 @@
  * into a bundle that never calls `setLocale`, because every tool
  * `vite.config.ts` sets `external: []`.
  *
- * An explicit static map rather than a bundler macro: `tsc` emits these
- * `import()` calls verbatim, so `players-shared/dist` evaluates anywhere ESM
- * does — webpack, esbuild, Rollup, Node, or a browser loading the files
- * directly. `pie-qti` used `import.meta.glob` and shipped a `dist` that throws
- * under every one of those. Each bundler still sees the specifiers statically,
- * so each locale stays its own chunk. Adding a locale means adding one line here
- * alongside the file.
+ * `en-US` is the source of truth — the fallback for every missing key in every
+ * other locale — so the provider imports it statically and it is always
+ * resident. It is the only catalog this package ships: every other locale this
+ * repository ships lives in the optional generated tier
+ * (`@pie-players/pie-i18n-generated`), whose loaders a host composes after
+ * this one. The composed shape is that package's README's wiring example:
  *
- * `en-US` is absent: it is the fallback for every missing key in every other
- * locale, so the provider imports it statically and it is always resident.
+ * ```ts
+ * loadCatalog: (locale) =>
+ *   loadBundledCatalog(locale).catch(() => loadGeneratedCatalog(locale));
+ * ```
+ *
+ * A request this function cannot serve rejects, and the provider treats that
+ * as "resolve through the fallback chain" rather than an error, so a host
+ * locale nothing ships still renders English.
  *
  * @module @pie-players/pie-players-shared/i18n/catalogs
  */
 import enUS from "./messages/en-US.js";
-const CATALOG_LOADERS = {
-    "nl-NL": () => import("./messages/nl-NL.js"),
-};
 /**
- * Every locale tag this repository ships a catalog for, English included.
+ * Every locale tag this repository bundles a catalog for. `en-US` alone: the
+ * statically resident source of truth.
  *
  * The provider resolves a request against this list through RFC 4647 lookup and
- * primary-subtag widening, so `nl`, `nl_NL` and `nl-BE` all reach `nl-NL`.
+ * primary-subtag widening, so `en`, `en_US` and `en-GB`-without-a-catalog all
+ * land on `en-US` unless a composed loader serves the region.
  */
-export const BUNDLED_LOCALES = ["en-US", "nl-NL"];
+export const BUNDLED_LOCALES = ["en-US"];
 /**
  * Load one shipped catalog.
  *
@@ -39,7 +43,7 @@ export const BUNDLED_LOCALES = ["en-US", "nl-NL"];
  * or a pseudo-localization of the English catalog — asks for it by name like
  * any other locale.
  *
- * Throws for a locale with no shipped catalog; the provider treats that as
+ * Rejects for a locale with no bundled catalog; the provider treats that as
  * "resolve through the fallback chain" rather than an error, so a host locale we
  * do not ship still renders.
  */
@@ -47,10 +51,5 @@ export async function loadBundledCatalog(locale) {
     if (locale === "en-US") {
         return enUS;
     }
-    const loader = CATALOG_LOADERS[locale];
-    if (!loader) {
-        throw new Error(`No bundled i18n catalog for locale: ${locale}`);
-    }
-    const module = await loader();
-    return module.default;
+    throw new Error(`No bundled i18n catalog for locale: ${locale}`);
 }

package/dist/i18n/language-tags.d.ts

@@ -78,19 +78,31 @@ export declare function languageTagScriptLookupSequence(tag: string | null | und
  * `zh-TW` passes it by.
  */
 export declare function findBestLanguageMatch(requested: string | null | undefined, available: readonly (string | null | undefined)[]): string | undefined;
+/**
+ * A tag without its variant, extension and private-use subtags, casing kept:
+ * `en-GB-x-gulf` yields `en-GB`. The form for a speech engine, whose voices
+ * are keyed by language and region.
+ */
+export declare function languageTagWithoutVariants(tag: string | null | undefined): string;
 /**
  * `findBestLanguageMatch`, then primary-subtag widening, so `nl-BE` and a bare
- * `nl` reach a regional `nl-NL` and `es-MX` reaches `es-ES`. Both stay within
- * the request's script: `zh` never reaches `zh-TW`, and `sr-Latn` may reach
- * `sr-ME`. The rule that picks an interface catalog and a content variant alike.
+ * `nl` reach a regional `nl-NL` and `es-MX` reaches `es-ES`. Widening stays
+ * within the request's script and keeps its variant subtags: `zh` never
+ * reaches `zh-TW`, `sr-Latn` may reach `sr-ME`, `en-GB` never reaches
+ * `en-GB-x-gulf`, and `en-US-x-gulf` may reach `en-GB-x-gulf`. Among several
+ * siblings the first in `available` wins. The rule that picks an interface
+ * catalog and a content variant alike.
  */
 export declare function findClosestLanguageMatch(requested: string | null | undefined, available: readonly (string | null | undefined)[]): string | undefined;
 /** The content language a backend serves, and whether it is a substitute. */
 export interface ContentLanguageMatch {
     /** The `available` entry served, as authored; `null` for content that declares no language. */
     language: string | null;
-    /** `"fallback"` when the served content stands in for the request. */
-    substitution?: "fallback";
+    /**
+     * `"fallback"` when the served content stands in for the request;
+     * `"variety"` when it is another variety of the requested language.
+     */
+    substitution?: "fallback" | "variety";
 }
 /**
  * The language to serve content in: the closest `available` match for the
@@ -100,7 +112,12 @@ export interface ContentLanguageMatch {
  * chain serves the closest match for `defaultLanguage` (`en-US` reaches `en`),
  * then content that declares no language (a `null` entry), then `source`;
  * `matching` does not narrow it. `undefined` means nothing can be served. No
- * requested languages run the chain without a substitution.
+ * requested languages run the chain without a substitution. A closest match
+ * in another variety, `es-MX` served `es-ES`, records `"variety"`; a host
+ * that must not serve one sets `matching: "exact"` and lists the varieties it
+ * accepts. Candidates rank
+ * `source` first, then by tag, so the order of `available` never decides
+ * between two siblings.
  */
 export declare function negotiateContentLanguage(requested: readonly string[], available: readonly (string | null)[], options?: {
     defaultLanguage?: string;

package/dist/i18n/language-tags.js

@@ -149,11 +149,59 @@ export function findBestLanguageMatch(requested, available) {
     }
     return undefined;
 }
+/**
+ * A tag's subtags split at the end of its language, script and region:
+ * `en-GB-x-gulf` yields `[["en", "GB"], ["x", "gulf"]]`. The second part holds
+ * variants, extensions and private use, as authored.
+ */
+function splitVariantSubtags(tag) {
+    const subtags = toLanguageTag(tag).split(/[.@]/)[0].split("-");
+    let length = 1;
+    if (/^[a-z]{4}$/i.test(subtags[length] ?? ""))
+        length++;
+    if (/^([a-z]{2}|\d{3})$/i.test(subtags[length] ?? ""))
+        length++;
+    return [subtags.slice(0, length), subtags.slice(length)];
+}
+/** The variant, extension and private-use subtags as a comparison key. */
+function variantSubtagsKey(tag) {
+    return splitVariantSubtags(tag)[1].join("-").toLowerCase();
+}
+/**
+ * Whether `served` is another variety of `requested`: it names a different
+ * region, or different variant or private-use subtags. `es-MX` served `es-ES`
+ * or `en-GB-x-gulf` served `en-GB` is; `es-MX` served `es`, or `zh-TW` served
+ * `zh-Hant`, is not.
+ */
+function isOtherLanguageVariety(requested, served) {
+    const region = (tag) => {
+        const [base] = splitVariantSubtags(tag);
+        const last = base.length > 1 ? base[base.length - 1] : "";
+        return /^([a-z]{2}|\d{3})$/i.test(last) ? last.toLowerCase() : undefined;
+    };
+    const requestedRegion = region(requested);
+    const servedRegion = region(served);
+    return ((requestedRegion !== undefined &&
+        servedRegion !== undefined &&
+        requestedRegion !== servedRegion) ||
+        variantSubtagsKey(requested) !== variantSubtagsKey(served));
+}
+/**
+ * A tag without its variant, extension and private-use subtags, casing kept:
+ * `en-GB-x-gulf` yields `en-GB`. The form for a speech engine, whose voices
+ * are keyed by language and region.
+ */
+export function languageTagWithoutVariants(tag) {
+    return splitVariantSubtags(tag)[0].join("-");
+}
 /**
  * `findBestLanguageMatch`, then primary-subtag widening, so `nl-BE` and a bare
- * `nl` reach a regional `nl-NL` and `es-MX` reaches `es-ES`. Both stay within
- * the request's script: `zh` never reaches `zh-TW`, and `sr-Latn` may reach
- * `sr-ME`. The rule that picks an interface catalog and a content variant alike.
+ * `nl` reach a regional `nl-NL` and `es-MX` reaches `es-ES`. Widening stays
+ * within the request's script and keeps its variant subtags: `zh` never
+ * reaches `zh-TW`, `sr-Latn` may reach `sr-ME`, `en-GB` never reaches
+ * `en-GB-x-gulf`, and `en-US-x-gulf` may reach `en-GB-x-gulf`. Among several
+ * siblings the first in `available` wins. The rule that picks an interface
+ * catalog and a content variant alike.
  */
 export function findClosestLanguageMatch(requested, available) {
     const best = findBestLanguageMatch(requested, available);
@@ -162,7 +210,9 @@ export function findClosestLanguageMatch(requested, available) {
     const language = normalizeLanguageTag(requested).split("-")[0];
     if (!language)
         return undefined;
+    const variants = variantSubtagsKey(requested);
     const sibling = available.find((candidate) => normalizeLanguageTag(candidate).split("-")[0] === language &&
+        variantSubtagsKey(candidate) === variants &&
         languageTagScriptsMatch(requested, candidate));
     return sibling ?? undefined;
 }
@@ -174,20 +224,35 @@ export function findClosestLanguageMatch(requested, available) {
  * chain serves the closest match for `defaultLanguage` (`en-US` reaches `en`),
  * then content that declares no language (a `null` entry), then `source`;
  * `matching` does not narrow it. `undefined` means nothing can be served. No
- * requested languages run the chain without a substitution.
+ * requested languages run the chain without a substitution. A closest match
+ * in another variety, `es-MX` served `es-ES`, records `"variety"`; a host
+ * that must not serve one sets `matching: "exact"` and lists the varieties it
+ * accepts. Candidates rank
+ * `source` first, then by tag, so the order of `available` never decides
+ * between two siblings.
  */
 export function negotiateContentLanguage(requested, available, options = {}) {
     const { defaultLanguage, fallback = "default", matching = "closest", source } = options;
+    const candidates = [...available].sort((a, b) => {
+        if ((a === source) !== (b === source))
+            return a === source ? -1 : 1;
+        const left = normalizeLanguageTag(a);
+        const right = normalizeLanguageTag(b);
+        return left < right ? -1 : left > right ? 1 : 0;
+    });
     for (const tag of requested) {
         const language = matching === "exact"
-            ? available.find((candidate) => languageTagsEqual(candidate, tag))
-            : findClosestLanguageMatch(tag, available);
-        if (language != null)
-            return { language };
+            ? candidates.find((candidate) => languageTagsEqual(candidate, tag))
+            : findClosestLanguageMatch(tag, candidates);
+        if (language != null) {
+            return isOtherLanguageVariety(tag, language)
+                ? { language, substitution: "variety" }
+                : { language };
+        }
     }
     if (requested.length > 0 && fallback === "none")
         return undefined;
-    let language = findClosestLanguageMatch(defaultLanguage, available);
+    let language = findClosestLanguageMatch(defaultLanguage, candidates);
     if (language === undefined && available.includes(null))
         language = null;
     if (language === undefined && source !== undefined && available.includes(source)) {

package/dist/i18n/messages/en-US.d.ts

@@ -109,16 +109,16 @@ declare const enUS: {
             loadFailed: string;
             restoreFailed: string;
         };
-        /** Formative delivery: check-answer control and its outcome announcements. */
-        formative: {
-            checkAnswer: string;
+        /** Item session control: check-answer control and its outcome announcements. */
+        check: {
+            answer: string;
             tryAgain: string;
             answerRecorded: string;
             correct: string;
             partlyCorrect: string;
             notCorrect: string;
             notAutoScored: string;
-            checkFailed: string;
+            failed: string;
             /**
              * Appended after the outcome, so the announcement reads
              * "Not correct. 2 tries left." Kept a separate plural group rather than
@@ -301,6 +301,12 @@ declare const enUS: {
                 lanthanide: string;
                 actinide: string;
             };
+            /** Standard-state phase, keyed by the data file's lowercased `phase` value. */
+            phaseValue: {
+                solid: string;
+                liquid: string;
+                gas: string;
+            };
         };
         ruler: {
             name: string;
@@ -462,6 +468,17 @@ declare const enUS: {
             highlightPinkA11y: string;
             highlightBlueA11y: string;
             highlightGreenA11y: string;
+            selectionAvailableA11y: string;
+            highlightedYellowA11y: string;
+            highlightedPinkA11y: string;
+            highlightedBlueA11y: string;
+            highlightedGreenA11y: string;
+            underlinedA11y: string;
+            removedA11y: string;
+            clearedA11y: {
+                one: string;
+                other: string;
+            };
         };
         theme: {
             name: string;

package/dist/i18n/messages/en-US.js

@@ -109,16 +109,16 @@ const enUS = {
             loadFailed: "The assessment could not be loaded. Try again.",
             restoreFailed: "Your saved answers for this section could not be restored. Try again.",
         },
-        /** Formative delivery: check-answer control and its outcome announcements. */
-        formative: {
-            checkAnswer: "Check answer",
+        /** Item session control: check-answer control and its outcome announcements. */
+        check: {
+            answer: "Check answer",
             tryAgain: "Try again",
             answerRecorded: "Answer recorded.",
             correct: "Correct.",
             partlyCorrect: "Partly correct.",
             notCorrect: "Not correct.",
             notAutoScored: "Answer recorded. This question is not scored automatically.",
-            checkFailed: "This question could not be checked. Try again.",
+            failed: "This question could not be checked. Try again.",
             /**
              * Appended after the outcome, so the announcement reads
              * "Not correct. 2 tries left." Kept a separate plural group rather than
@@ -306,6 +306,12 @@ const enUS = {
                 lanthanide: "Lanthanide",
                 actinide: "Actinide",
             },
+            /** Standard-state phase, keyed by the data file's lowercased `phase` value. */
+            phaseValue: {
+                solid: "Solid",
+                liquid: "Liquid",
+                gas: "Gas",
+            },
         },
         ruler: {
             name: "Ruler",
@@ -482,6 +488,19 @@ const enUS = {
             highlightPinkA11y: "Pink highlight",
             highlightBlueA11y: "Blue highlight",
             highlightGreenA11y: "Green highlight",
+            // Announced in the strip's live region. A colour is authored per phrase:
+            // a colour adjective agrees with its noun in some languages.
+            selectionAvailableA11y: "Annotation toolbar available for “{text}”. Press Shift+F10 for annotation tools.",
+            highlightedYellowA11y: "“{text}” highlighted in yellow",
+            highlightedPinkA11y: "“{text}” highlighted in pink",
+            highlightedBlueA11y: "“{text}” highlighted in blue",
+            highlightedGreenA11y: "“{text}” highlighted in green",
+            underlinedA11y: "“{text}” underlined",
+            removedA11y: "Removed annotation from “{text}”",
+            clearedA11y: {
+                one: "{count} annotation cleared",
+                other: "{count} annotations cleared",
+            },
         },
         theme: {
             name: "Theme",

package/dist/i18n/types.d.ts

@@ -16,8 +16,13 @@ import type enUS from "./messages/en-US.js";
  * syntax — the Learnosity transform emits POSIX `nl_NL`, QTI catalog cards carry
  * `xml:lang` — and the resolver normalizes both onto these, so this list is the
  * set of catalogs, not the set of accepted inputs.
+ *
+ * `en-US` is the only bundled catalog: the statically resident source of truth
+ * every other locale falls back through. Every other locale this repository
+ * ships lives in the optional generated tier
+ * (`@pie-players/pie-i18n-generated`), which a host composes into its loader.
  */
-export type BundledLocaleCode = "en-US" | "nl-NL";
+export type BundledLocaleCode = "en-US";
 /**
  * Any locale tag. A host may supply a locale we ship no catalog for and provide
  * its own messages through {@link I18nConfig.customMessages}, so this is
@@ -52,7 +57,7 @@ type PluralCategoryKey = keyof PluralTranslation;
  * Dot-notation keys of a catalog shape.
  *
  * A plural group terminates the path at the group itself: `plural()` is called
- * with `player.formative.triesLeft`, never with `…triesLeft.other`. A group is
+ * with `player.check.triesLeft`, never with `…triesLeft.other`. A group is
  * recognized by every one of its keys being a CLDR plural category — the
  * containment has to run this way round, because a group carrying only
  * `one`/`other` does not contain the whole category union.

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export * from "./security/index.js";
 export * from "./loaders/index.js";
 export * from "./object/index.js";
 export * from "./pie/index.js";
-export type { AssessmentEntity, AssessmentItemRef, AssessmentSection, AdvancedItemConfig, ConfigEntity, ConfigResource, Env, FormativeDeliveryPolicy, FormativeItemPolicy, TimedMediaSectionData, ItemConfig, ItemEntity, ItemSession, OutcomeResponse, PassageEntity, PieController, PieContent, PieDefaultModel, PieItemElement, PieModel, PieUpdateSession, ReferencedItemEntity, ReferencedPassageEntity, RubricBlock, TestPart, } from "./types/index.js";
+export type { AssessmentEntity, AssessmentItemRef, AssessmentSection, AdvancedItemConfig, ConfigEntity, ConfigResource, Env, ItemSessionControlPolicy, TimedMediaSectionData, ItemConfig, ItemEntity, ItemSession, OutcomeResponse, PassageEntity, PieController, PieContent, PieDefaultModel, PieItemElement, PieModel, PieUpdateSession, ReferencedItemEntity, ReferencedPassageEntity, RubricBlock, TestPart, } from "./types/index.js";
 export { editorPostFix } from "./types/index.js";
 export * from "./ui/attribute-coercion.js";
 export * from "./ui/content-styles.js";

package/dist/item-session-control/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Item session control: Try state, feedback reveal, and section mastery.
+ *
+ * Pure and Node-safe by design — no DOM, no timers, no element registry — so
+ * the contract is testable without a browser and an adapter can import it
+ * without pulling in a player. Everything that touches the DOM stays in
+ * `@pie-players/pie-section-player`.
+ *
+ * Contract: `docs/prds/item-session-control-contract.md`.
+ */
+export type { TryAction, TryCorrectness, ItemSessionControlPolicy, FeedbackEnvOverride, FeedbackReveal, ItemTryState, ItemTryView, MasteryRollup, FeedbackRevealTiming, ScoredElementOutcome, TrySectionProjection, TrySectionSlice, TryLimit, TryOutcome, ResolvedItemSessionControlPolicy, } from "./types.js";
+export { ITEM_SESSION_CONTROL_DEFAULTS, isItemSessionControlEnabledInSection, resolveItemSessionControls, resolveItemSessionControl, } from "./policy.js";
+export { aggregateTryOutcome } from "./outcome.js";
+export { ITEM_TRY_STATE_VERSION, createItemTryState, hideItemFeedback, recordTry, resolveItemTryView, retryItem, revealItemFeedback, } from "./state.js";
+export { MASTERY_ROLLUP_VERSION, rollupMastery } from "./mastery.js";
+export { TRY_SLICE_VERSION, normalizeTrySectionSlice, toTrySectionSlice, } from "./session.js";

package/dist/item-session-control/index.js

@@ -0,0 +1,5 @@
+export { ITEM_SESSION_CONTROL_DEFAULTS, isItemSessionControlEnabledInSection, resolveItemSessionControls, resolveItemSessionControl, } from "./policy.js";
+export { aggregateTryOutcome } from "./outcome.js";
+export { ITEM_TRY_STATE_VERSION, createItemTryState, hideItemFeedback, recordTry, resolveItemTryView, retryItem, revealItemFeedback, } from "./state.js";
+export { MASTERY_ROLLUP_VERSION, rollupMastery } from "./mastery.js";
+export { TRY_SLICE_VERSION, normalizeTrySectionSlice, toTrySectionSlice, } from "./session.js";

package/dist/{formative → item-session-control}/mastery.d.ts

@@ -1,5 +1,5 @@
-import type { FormativeItemState, FormativeMasteryRollup } from "./types.js";
-export declare const FORMATIVE_MASTERY_VERSION: 1;
+import type { ItemTryState, MasteryRollup } from "./types.js";
+export declare const MASTERY_ROLLUP_VERSION: 1;
 /**
  * Roll Try outcomes up to the section.
  *
@@ -10,7 +10,7 @@ export declare const FORMATIVE_MASTERY_VERSION: 1;
  * excluded: nothing yet says it cannot be scored, so it keeps the section from
  * reading as complete after one correct answer.
  */
-export declare function rollupFormativeMastery(args: {
+export declare function rollupMastery(args: {
     itemIdentifiers: readonly string[];
-    states: Record<string, FormativeItemState>;
-}): FormativeMasteryRollup;
+    states: Record<string, ItemTryState>;
+}): MasteryRollup;

package/dist/{formative → item-session-control}/mastery.js

@@ -1,4 +1,4 @@
-export const FORMATIVE_MASTERY_VERSION = 1;
+export const MASTERY_ROLLUP_VERSION = 1;
 /**
  * Roll Try outcomes up to the section.
  *
@@ -9,7 +9,7 @@ export const FORMATIVE_MASTERY_VERSION = 1;
  * excluded: nothing yet says it cannot be scored, so it keeps the section from
  * reading as complete after one correct answer.
  */
-export function rollupFormativeMastery(args) {
+export function rollupMastery(args) {
     const identifiers = args.itemIdentifiers ?? [];
     const totalItems = identifiers.length;
     let notScorableItems = 0;
@@ -31,7 +31,7 @@ export function rollupFormativeMastery(args) {
     }
     const scorableItems = Math.max(0, totalItems - notScorableItems);
     return {
-        version: FORMATIVE_MASTERY_VERSION,
+        version: MASTERY_ROLLUP_VERSION,
         totalItems,
         scorableItems,
         masteredItems,

package/dist/{formative → item-session-control}/outcome.d.ts

@@ -1,10 +1,10 @@
-import type { FormativeScoredOutcome, FormativeTryOutcome } from "./types.js";
+import type { ScoredElementOutcome, TryOutcome } from "./types.js";
 /**
  * Reduce the array `pie-item-player.provideScore()` returns to one Try outcome.
  *
  * The aggregation mirrors the policy the persisted API scoring path already
  * documents (`docs/item-player/scoring-and-rubrics.md`), so a browser-derived
- * formative result and a server-derived score do not disagree about what a
+ * Try result and a server-derived score do not disagree about what a
  * multi-element item is worth:
  *
  * - one scored outcome: `points = score`, `max = max ?? 1`;
@@ -16,4 +16,4 @@ import type { FormativeScoredOutcome, FormativeTryOutcome } from "./types.js";
  * those slots count toward `totalElementCount` and not toward
  * `scoredElementCount`.
  */
-export declare function aggregateFormativeOutcome(outcomes: ReadonlyArray<FormativeScoredOutcome | null | undefined> | null): FormativeTryOutcome;
+export declare function aggregateTryOutcome(outcomes: ReadonlyArray<ScoredElementOutcome | null | undefined> | null): TryOutcome;

package/dist/{formative → item-session-control}/outcome.js

@@ -39,7 +39,7 @@ function classify(points, max) {
  *
  * The aggregation mirrors the policy the persisted API scoring path already
  * documents (`docs/item-player/scoring-and-rubrics.md`), so a browser-derived
- * formative result and a server-derived score do not disagree about what a
+ * Try result and a server-derived score do not disagree about what a
  * multi-element item is worth:
  *
  * - one scored outcome: `points = score`, `max = max ?? 1`;
@@ -51,7 +51,7 @@ function classify(points, max) {
  * those slots count toward `totalElementCount` and not toward
  * `scoredElementCount`.
  */
-export function aggregateFormativeOutcome(outcomes) {
+export function aggregateTryOutcome(outcomes) {
     const all = Array.isArray(outcomes) ? outcomes : [];
     const scored = all.filter(isScored);
     const totalElementCount = all.length;