@pie-players/pie-players-shared 0.3.74 → 0.3.75

package/README.md

@@ -128,7 +128,9 @@ jsDelivr is the default npm CDN provider. Hosts can opt into `esm.sh` with
 Provider names are open-ended: custom/internal providers can pass their own name
 when they follow the jsDelivr-compatible package-file URL layout, or pass a
 provider object when package artifacts and shared dependencies need different
-route builders.
+route builders. Under `esm` the item player's own MathJax takes the provider's
+package-file root as its asset root when the page sets none; see
+[MathJax assets](../../docs/item-player/loading-strategies.md#mathjax-assets).
 
 `dependencies` and `peerDependencies` are not used as fallback runtime contracts.
 If multiple elements request different minor or patch versions of a shared

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

@@ -393,30 +393,6 @@ declare const enUS: {
         textToSpeech: {
             name: string;
             description: string;
-            toolA11y: string;
-            title: string;
-            initializing: string;
-            initFailed: string;
-            selectText: string;
-            speed: string;
-            play: string;
-            pause: string;
-            resume: string;
-            stop: string;
-            speaking: string;
-            paused: string;
-            charactersSelected: {
-                one: string;
-                other: string;
-            };
-            rate: {
-                slow: string;
-                slower: string;
-                normal: string;
-                faster: string;
-                fast: string;
-                veryFast: string;
-            };
             /** Inline reading controls and their live-region announcements. */
             inline: {
                 controlsA11y: string;
@@ -538,6 +514,7 @@ declare const enUS: {
             resolvedTools: string;
             provenanceSummary: string;
             perToolDecisions: string;
+            policyDiagnostics: string;
             profileReadOnly: string;
         };
         /** TTS settings panel. */

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

@@ -407,30 +407,6 @@ const enUS = {
         textToSpeech: {
             name: "Text to Speech",
             description: "Read content aloud",
-            toolA11y: "Text-to-speech tool",
-            title: "Text-to-Speech",
-            initializing: "Initializing…",
-            initFailed: "Failed to initialize text-to-speech.",
-            selectText: "Select text on the page to read it aloud.",
-            speed: "Speed:",
-            play: "Play",
-            pause: "Pause",
-            resume: "Resume",
-            stop: "Stop",
-            speaking: "Speaking…",
-            paused: "Paused",
-            charactersSelected: {
-                one: "{count} character selected",
-                other: "{count} characters selected",
-            },
-            rate: {
-                slow: "Slow",
-                slower: "Slower",
-                normal: "Normal",
-                faster: "Faster",
-                fast: "Fast",
-                veryFast: "Very Fast",
-            },
             /** Inline reading controls and their live-region announcements. */
             inline: {
                 controlsA11y: "Reading controls",
@@ -552,6 +528,7 @@ const enUS = {
             resolvedTools: "Resolved Tools (toolkit)",
             provenanceSummary: "Tool Policy Provenance Summary",
             perToolDecisions: "Per-Tool Decisions",
+            policyDiagnostics: "Policy Diagnostics",
             profileReadOnly: "PNP Profile (read-only)",
         },
         /** TTS settings panel. */

package/dist/i18n/messages/nl-NL.d.ts

@@ -321,30 +321,6 @@ declare const nlNL: {
         textToSpeech: {
             name: string;
             description: string;
-            toolA11y: string;
-            title: string;
-            initializing: string;
-            initFailed: string;
-            selectText: string;
-            speed: string;
-            play: string;
-            pause: string;
-            resume: string;
-            stop: string;
-            speaking: string;
-            paused: string;
-            charactersSelected: {
-                one: string;
-                other: string;
-            };
-            rate: {
-                slow: string;
-                slower: string;
-                normal: string;
-                faster: string;
-                fast: string;
-                veryFast: string;
-            };
             inline: {
                 controlsA11y: string;
                 playbackSpeedA11y: string;
@@ -450,6 +426,7 @@ declare const nlNL: {
             resolvedTools: string;
             provenanceSummary: string;
             perToolDecisions: string;
+            policyDiagnostics: string;
             profileReadOnly: string;
         };
         tts: {

package/dist/i18n/messages/nl-NL.js

@@ -321,30 +321,6 @@ const nlNL = {
         textToSpeech: {
             name: "Voorlezen",
             description: "Inhoud laten voorlezen",
-            toolA11y: "Voorleeshulp",
-            title: "Voorlezen",
-            initializing: "Wordt gestart…",
-            initFailed: "Voorlezen kon niet worden gestart.",
-            selectText: "Selecteer tekst op de pagina om die te laten voorlezen.",
-            speed: "Snelheid:",
-            play: "Voorlezen",
-            pause: "Pauzeren",
-            resume: "Hervatten",
-            stop: "Stoppen",
-            speaking: "Aan het voorlezen…",
-            paused: "Gepauzeerd",
-            charactersSelected: {
-                one: "{count} teken geselecteerd",
-                other: "{count} tekens geselecteerd",
-            },
-            rate: {
-                slow: "Langzaam",
-                slower: "Langzamer",
-                normal: "Normaal",
-                faster: "Sneller",
-                fast: "Snel",
-                veryFast: "Zeer snel",
-            },
             inline: {
                 controlsA11y: "Voorleesknoppen",
                 playbackSpeedA11y: "Voorleessnelheid",
@@ -450,6 +426,7 @@ const nlNL = {
             resolvedTools: "Toegekende hulpmiddelen (toolkit)",
             provenanceSummary: "Overzicht van herkomst van het hulpmiddelenbeleid",
             perToolDecisions: "Beslissingen per hulpmiddel",
+            policyDiagnostics: "Diagnose van het hulpmiddelenbeleid",
             profileReadOnly: "PNP-profiel (alleen lezen)",
         },
         tts: {

package/dist/i18n/types.d.ts

@@ -52,11 +52,10 @@ 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 `tools.textToSpeech.charactersSelected`, never with
- * `…charactersSelected.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.
+ * with `player.formative.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.
  */
 type NestedKeys<T> = {
     [K in keyof T & string]: T[K] extends string ? K : keyof T[K] extends PluralCategoryKey ? K : T[K] extends object ? K | `${K}.${NestedKeys<T[K]>}` : K;

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, RubricBlock, TestPart, } from "./types/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 { editorPostFix } from "./types/index.js";
 export * from "./ui/attribute-coercion.js";
 export * from "./ui/content-styles.js";

package/dist/loaders/esm-adapter.d.ts

@@ -73,4 +73,15 @@ export declare function resolveEsmRuntimeSupportUrl(packageVersion: string, opti
     cdnBaseUrl: string;
     cdnProvider?: EsmCdnProviderOption;
 }): string | undefined;
+/**
+ * The npm root the ESM CDN the players load elements from serves raw package
+ * files under, `<root>/<package>@<version>/<path>`: the base URL for jsDelivr,
+ * raw.esm.sh for esm.sh, and for a custom provider whatever its
+ * `packageJsonUrl` puts before the package. `undefined` when that URL names
+ * no such root.
+ */
+export declare function resolveEsmAssetRoot(options: {
+    cdnBaseUrl: string;
+    cdnProvider?: EsmCdnProviderOption;
+}): string | undefined;
 export declare function pickElementClass(module: any, view: string): unknown;

package/dist/loaders/esm-adapter.js

@@ -21,7 +21,7 @@ import { BundleType, isCustomElementConstructor, Status, } from "../pie/types.js
 import { parsePackageName } from "../pie/utils.js";
 import { AdapterFailure, } from "./element-loader-types.js";
 import { isExactSemver } from "./element-package-policy.js";
-import { forwardMathjaxVersionConflicts } from "./mathjax-version-conflict.js";
+import { forwardMathjaxEvents } from "./mathjax-events.js";
 export const BUILT_IN_VIEWS = {
     delivery: { subpath: "", tagSuffix: "" },
     author: { subpath: "/author", tagSuffix: "-config", fallback: "delivery" },
@@ -41,8 +41,8 @@ export function createEsmBackend(config) {
     const editorRuntimeVariants = new Map();
     /** Packages that do not publish the browser ESM exports this backend loads. */
     const unpublishedPackages = new Map();
-    /** Windows whose MathJax version conflicts this backend forwards. */
-    const mathjaxConflictViews = new WeakSet();
+    /** Windows whose MathJax events this backend forwards. */
+    const mathjaxEventViews = new WeakSet();
     let sharedDependencyVersions = {};
     let importer = defaultImporter;
     let packageMetadataLoader = defaultPackageMetadataLoader;
@@ -82,7 +82,7 @@ export function createEsmBackend(config) {
         if (moduleResolution === "import-map") {
             assertImportMapSupported();
         }
-        forwardMathjaxVersionConflictsOf(context.doc);
+        forwardMathjaxEventsOf(context.doc);
         const newEntries = {};
         for (const [tag, pkg] of Object.entries(elements)) {
             const packageName = parsePackageName(pkg).name;
@@ -481,12 +481,12 @@ export function createEsmBackend(config) {
             return undefined;
         return provider;
     }
-    function forwardMathjaxVersionConflictsOf(doc) {
+    function forwardMathjaxEventsOf(doc) {
         const view = doc.defaultView;
-        if (!view || mathjaxConflictViews.has(view))
+        if (!view || mathjaxEventViews.has(view))
             return;
-        mathjaxConflictViews.add(view);
-        forwardMathjaxVersionConflicts(view, getInstrumentationProvider);
+        mathjaxEventViews.add(view);
+        forwardMathjaxEvents(view, getInstrumentationProvider);
     }
     function reportSharedDependencyConflict(attributes, message = `[pie-esm] Shared dependency version conflict resolved for ${String(attributes.dependencyName)}`) {
         if (typeof console !== "undefined" && console.warn) {
@@ -608,6 +608,24 @@ export function resolveEsmRuntimeSupportUrl(packageVersion, options) {
         ? `${packageJsonUrl.slice(0, -"package.json".length)}${RUNTIME_SUPPORT_PATH}`
         : undefined;
 }
+/** A package the probe below names, so a provider URL ends in its `<package>@<version>` path. */
+const ROOT_PROBE_PACKAGE = "@pie-element/shared-math-rendering-mathjax@0.0.0";
+/**
+ * The npm root the ESM CDN the players load elements from serves raw package
+ * files under, `<root>/<package>@<version>/<path>`: the base URL for jsDelivr,
+ * raw.esm.sh for esm.sh, and for a custom provider whatever its
+ * `packageJsonUrl` puts before the package. `undefined` when that URL names
+ * no such root.
+ */
+export function resolveEsmAssetRoot(options) {
+    const cdnBaseUrl = options.cdnBaseUrl.replace(/\/+$/, "");
+    const provider = resolveCdnProvider(options.cdnProvider, cdnBaseUrl);
+    const suffix = `/${ROOT_PROBE_PACKAGE}/package.json`;
+    const packageJsonUrl = provider.packageJsonUrl(ROOT_PROBE_PACKAGE);
+    return packageJsonUrl.endsWith(suffix)
+        ? packageJsonUrl.slice(0, -suffix.length) || undefined
+        : undefined;
+}
 function resolveCdnProvider(provider, cdnBaseUrl) {
     if (isEsmCdnProvider(provider))
         return provider;

package/dist/loaders/index.d.ts

@@ -37,12 +37,14 @@ export { assertElementPackagesAllowed, ElementPackagePolicyError, } from "./elem
 export type { BackendContext, BackendOption, ElementLoaderBackend, ElementTag, EnsureRegisteredOptions, EsmBackendConfig, IifeBackendConfig, RegistrationFailureReason, } from "./element-loader.js";
 export { AdapterFailure, ElementAssertionError, ElementLoaderError, assertRegistered, describeRegistrationFailures, ensureRegistered, } from "./element-loader.js";
 export type { BuiltInEsmCdnProviderName, EsmBackend, EsmCdnProvider, EsmCdnProviderName, EsmCdnProviderOption, ViewConfig, } from "./esm-adapter.js";
-export { BUILT_IN_VIEWS, createEsmBackend, mapEsmViewElements, resolveEsmRuntimeSupportUrl, } from "./esm-adapter.js";
+export { BUILT_IN_VIEWS, createEsmBackend, mapEsmViewElements, resolveEsmAssetRoot, resolveEsmRuntimeSupportUrl, } from "./esm-adapter.js";
 export type { IifeBackend, IifeBundleRetryStatus, } from "./iife-adapter.js";
+export { forwardMathjaxEvents, MATHJAX_NO_ASSET_ROOT_EVENT, MATHJAX_VERSION_CONFLICT_EVENT, } from "./mathjax-events.js";
 export { DEFAULT_BUNDLE_HOST, DEFAULT_ESM_CDN_URL } from "./defaults.js";
 export { createIifeBackend } from "./iife-adapter.js";
 export { resolveLoadControllers } from "./controller-loading.js";
-export type { PreloadedController, PreloadedElement, } from "./preloaded-registration.js";
+export type { PreloadedController, PreloadedElement, PreloadedRegistrationOptions, } from "./preloaded-registration.js";
+export type { MathAssetOptions } from "../pie/math-assets.js";
 export { registerPreloadedElements } from "./preloaded-registration.js";
 export type { PreloadedElementSpecs } from "./preloaded-alignment.js";
 export { alignPreloadedElementVersions } from "./preloaded-alignment.js";

package/dist/loaders/index.js

@@ -33,7 +33,8 @@
 export { aggregateElements } from "./ElementLoader.js";
 export { assertElementPackagesAllowed, ElementPackagePolicyError, } from "./element-package-policy.js";
 export { AdapterFailure, ElementAssertionError, ElementLoaderError, assertRegistered, describeRegistrationFailures, ensureRegistered, } from "./element-loader.js";
-export { BUILT_IN_VIEWS, createEsmBackend, mapEsmViewElements, resolveEsmRuntimeSupportUrl, } from "./esm-adapter.js";
+export { BUILT_IN_VIEWS, createEsmBackend, mapEsmViewElements, resolveEsmAssetRoot, resolveEsmRuntimeSupportUrl, } from "./esm-adapter.js";
+export { forwardMathjaxEvents, MATHJAX_NO_ASSET_ROOT_EVENT, MATHJAX_VERSION_CONFLICT_EVENT, } from "./mathjax-events.js";
 export { DEFAULT_BUNDLE_HOST, DEFAULT_ESM_CDN_URL } from "./defaults.js";
 export { createIifeBackend } from "./iife-adapter.js";
 export { resolveLoadControllers } from "./controller-loading.js";

package/dist/loaders/mathjax-events.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Forwards the MathJax adapter's page events to instrumentation.
+ *
+ * Every copy of the MathJax 4 adapter that browser ESM elements render with
+ * dispatches these on `window`, once per condition per page:
+ * `pie-mathjax-version-conflict` when MathJax 3 runs on the same page — an
+ * unsupported page, see
+ * docs/item-player/loading-strategies.md#one-mathjax-version-per-page — and
+ * `pie-mathjax-no-asset-root` when a copy has nowhere to load MathJax's files
+ * from, see docs/item-player/loading-strategies.md#mathjax-assets. The event
+ * names are repeated here because players do not depend on the element
+ * packages.
+ */
+import type { InstrumentationProvider } from "../instrumentation/types.js";
+export declare const MATHJAX_VERSION_CONFLICT_EVENT = "pie-mathjax-version-conflict";
+export declare const MATHJAX_NO_ASSET_ROOT_EVENT = "pie-mathjax-no-asset-root";
+/**
+ * Tracks each MathJax event on `target` with the provider `getProvider`
+ * returns when it fires, once per provider. Returns the function that stops
+ * forwarding.
+ */
+export declare function forwardMathjaxEvents(target: EventTarget, getProvider: () => InstrumentationProvider | undefined): () => void;

package/dist/loaders/mathjax-events.js

@@ -0,0 +1,65 @@
+/**
+ * Forwards the MathJax adapter's page events to instrumentation.
+ *
+ * Every copy of the MathJax 4 adapter that browser ESM elements render with
+ * dispatches these on `window`, once per condition per page:
+ * `pie-mathjax-version-conflict` when MathJax 3 runs on the same page — an
+ * unsupported page, see
+ * docs/item-player/loading-strategies.md#one-mathjax-version-per-page — and
+ * `pie-mathjax-no-asset-root` when a copy has nowhere to load MathJax's files
+ * from, see docs/item-player/loading-strategies.md#mathjax-assets. The event
+ * names are repeated here because players do not depend on the element
+ * packages.
+ */
+export const MATHJAX_VERSION_CONFLICT_EVENT = "pie-mathjax-version-conflict";
+export const MATHJAX_NO_ASSET_ROOT_EVENT = "pie-mathjax-no-asset-root";
+/** The detail fields each event is tracked with. */
+const TRACKED_FIELDS = {
+    [MATHJAX_VERSION_CONFLICT_EVENT]: ["condition", "docsUrl"],
+    [MATHJAX_NO_ASSET_ROOT_EVENT]: ["effect", "docsUrl"],
+};
+// Every player on a page listens, and each player bundle carries its own copy
+// of this module, so the providers that tracked an event are kept on the page.
+const TRACKED = Symbol.for("@pie-players/pie-players-shared/mathjax-version-conflict-tracked");
+function providersThatTracked(event) {
+    const registry = globalThis;
+    registry[TRACKED] ??= new WeakMap();
+    let providers = registry[TRACKED].get(event);
+    if (!providers) {
+        providers = new WeakSet();
+        registry[TRACKED].set(event, providers);
+    }
+    return providers;
+}
+/**
+ * Tracks each MathJax event on `target` with the provider `getProvider`
+ * returns when it fires, once per provider. Returns the function that stops
+ * forwarding.
+ */
+export function forwardMathjaxEvents(target, getProvider) {
+    const forward = (event) => {
+        const provider = getProvider();
+        if (!provider)
+            return;
+        const tracked = providersThatTracked(event);
+        if (tracked.has(provider))
+            return;
+        tracked.add(provider);
+        const detail = event.detail;
+        const fields = (detail && typeof detail === "object" ? detail : {});
+        try {
+            provider.trackEvent(event.type, Object.fromEntries(TRACKED_FIELDS[event.type].map((field) => [field, fields[field]])));
+        }
+        catch {
+            // Swallow: instrumentation must never break rendering.
+        }
+    };
+    for (const type of Object.keys(TRACKED_FIELDS)) {
+        target.addEventListener(type, forward);
+    }
+    return () => {
+        for (const type of Object.keys(TRACKED_FIELDS)) {
+            target.removeEventListener(type, forward);
+        }
+    };
+}

package/dist/loaders/preloaded-registration.d.ts

@@ -15,7 +15,12 @@
  * player that is not hosted runs the controller's `model()` in the browser, so
  * it needs the `controller` an entry registers; the item player warns about
  * each tag it renders without one.
+ *
+ * Bundled by the host, the elements' copies of the MathJax adapter find no npm
+ * root in their module URLs, so the registration also takes where they load
+ * MathJax's fonts and speech from (`options.math`): a root, or each file's URL.
  */
+import { type MathAssetOptions } from "../pie/math-assets.js";
 /** A controller module: the `model()` a player that is not hosted runs. */
 export type PreloadedController = {
     readonly model: (...args: any[]) => unknown;
@@ -43,6 +48,16 @@ export interface PreloadedElement {
         readonly default: PreloadedController;
     };
 }
+export interface PreloadedRegistrationOptions {
+    /**
+     * Where the elements' MathJax loads its fonts, its speech worker and, on the
+     * adapter's npm build, MathJax itself from, and whether math is in the tab
+     * order, written to `window['@pie-lib/math-rendering@2'].opts`. With neither
+     * an `assetRoot` nor the fonts in `assetUrls`, math renders without web fonts
+     * and speech.
+     */
+    math?: MathAssetOptions;
+}
 /**
  * Register host-bundled elements for the `preloaded` strategy.
  *
@@ -51,6 +66,7 @@ export interface PreloadedElement {
  * registry entry, which only gains a controller it lacked. Every entry is
  * validated before any is registered. A package registers at one version per
  * page, because the players align every authored version of a package to the
- * registered one.
+ * registered one. `options.math` replaces the page's math asset options it
+ * sets, and keeps the others.
  */
-export declare function registerPreloadedElements(elements: readonly PreloadedElement[]): void;
+export declare function registerPreloadedElements(elements: readonly PreloadedElement[], options?: PreloadedRegistrationOptions): void;

package/dist/loaders/preloaded-registration.js

@@ -15,8 +15,13 @@
  * player that is not hosted runs the controller's `model()` in the browser, so
  * it needs the `controller` an entry registers; the item player warns about
  * each tag it renders without one.
+ *
+ * Bundled by the host, the elements' copies of the MathJax adapter find no npm
+ * root in their module URLs, so the registration also takes where they load
+ * MathJax's fonts and speech from (`options.math`): a root, or each file's URL.
  */
 import { defineCustomElementSafely } from "../pie/custom-element-define.js";
+import { mathAssetOptionsError, setMathAssetOptions, } from "../pie/math-assets.js";
 import { writeRegistryEntry } from "../pie/registry.js";
 import { BundleType, isCustomElementConstructor, Status } from "../pie/types.js";
 import { parsePackageName } from "../pie/utils.js";
@@ -31,15 +36,22 @@ import { pickElementClass } from "./esm-adapter.js";
  * registry entry, which only gains a controller it lacked. Every entry is
  * validated before any is registered. A package registers at one version per
  * page, because the players align every authored version of a package to the
- * registered one.
+ * registered one. `options.math` replaces the page's math asset options it
+ * sets, and keeps the others.
  */
-export function registerPreloadedElements(elements) {
+export function registerPreloadedElements(elements, options = {}) {
     if (typeof window === "undefined" || typeof customElements === "undefined") {
         throw new Error("[registerPreloadedElements] requires a browser with customElements");
     }
     const preloaded = preloadedPackageSpecs();
     const resolved = elements.map(resolveElement);
     assertOneVersionPerPackage(resolved, preloaded);
+    const mathError = options.math === undefined ? undefined : mathAssetOptionsError(options.math);
+    if (mathError) {
+        throw new Error(`[registerPreloadedElements] options.math: ${mathError}`);
+    }
+    if (options.math)
+        setMathAssetOptions(options.math);
     for (const { packageName, spec, tagName, elementClass, controller } of resolved) {
         defineCustomElementSafely(tagName, class extends elementClass {
         }, `preloaded element tag for ${packageName}`);

package/dist/pie/elements-rendered.d.ts

@@ -0,0 +1,25 @@
+/**
+ * When the PIE elements of a player have rendered.
+ *
+ * An element renders after its model and session are assigned, in a task of
+ * its own: legacy React elements debounce the render and commit through the
+ * React scheduler, so the commit lands tens of milliseconds after the
+ * assignment. No event marks it in both element generations — `model-set` is
+ * dispatched by about half of them, some before rendering — so this reads the
+ * DOM.
+ *
+ * An element has rendered once it holds content, and so has every custom
+ * element defined below it: an `ebsr` paints its parts, which then render
+ * themselves. Some elements render nothing, a rubric for a student among them,
+ * so an element still empty when the subtree has had no mutation for
+ * `quietMs` counts as rendered. A render slower than that window, with no
+ * mutation before it, is missed rather than waited for.
+ */
+import type { ConfigEntity } from "../types/index.js";
+/** Longer than the 50ms render debounce legacy elements use, plus a scheduler task. */
+export declare const ELEMENT_RENDER_QUIET_MS = 200;
+/**
+ * Resolves once every element of `configs` in `root` has rendered, or when
+ * `signal` aborts. Never rejects.
+ */
+export declare function elementsRendered(root: Element, configs: ConfigEntity[], signal: AbortSignal, quietMs?: number): Promise<void>;

package/dist/pie/elements-rendered.js

@@ -0,0 +1,96 @@
+/**
+ * When the PIE elements of a player have rendered.
+ *
+ * An element renders after its model and session are assigned, in a task of
+ * its own: legacy React elements debounce the render and commit through the
+ * React scheduler, so the commit lands tens of milliseconds after the
+ * assignment. No event marks it in both element generations — `model-set` is
+ * dispatched by about half of them, some before rendering — so this reads the
+ * DOM.
+ *
+ * An element has rendered once it holds content, and so has every custom
+ * element defined below it: an `ebsr` paints its parts, which then render
+ * themselves. Some elements render nothing, a rubric for a student among them,
+ * so an element still empty when the subtree has had no mutation for
+ * `quietMs` counts as rendered. A render slower than that window, with no
+ * mutation before it, is missed rather than waited for.
+ */
+/** Longer than the 50ms render debounce legacy elements use, plus a scheduler task. */
+export const ELEMENT_RENDER_QUIET_MS = 200;
+function hasContent(element) {
+    if (element.firstElementChild || element.shadowRoot?.firstChild)
+        return true;
+    return Boolean(element.textContent?.trim());
+}
+function isDefinedCustomElement(element) {
+    return (element.localName.includes("-") &&
+        customElements.get(element.localName) !== undefined);
+}
+function hasRendered(element) {
+    if (!element.isConnected)
+        return true;
+    if (!hasContent(element))
+        return false;
+    for (const nested of element.querySelectorAll("*")) {
+        if (isDefinedCustomElement(nested) && !hasContent(nested))
+            return false;
+    }
+    return true;
+}
+/** The elements of `configs` in `root`, found as `updatePieElements` finds them. */
+function renderedElements(root, configs) {
+    const elements = [];
+    for (const config of configs) {
+        const ids = new Set((config.models ?? []).map((model) => model?.id));
+        for (const tag of Object.keys(config.elements ?? {})) {
+            // An undefined tag renders nothing until its bundle loads.
+            if (!customElements.get(tag))
+                continue;
+            for (const element of root.querySelectorAll(tag)) {
+                if (ids.has(element.id))
+                    elements.push(element);
+            }
+        }
+    }
+    return elements;
+}
+/**
+ * Resolves once every element of `configs` in `root` has rendered, or when
+ * `signal` aborts. Never rejects.
+ */
+export function elementsRendered(root, configs, signal, quietMs = ELEMENT_RENDER_QUIET_MS) {
+    const elements = renderedElements(root, configs);
+    const allRendered = () => elements.every(hasRendered);
+    if (signal.aborted ||
+        allRendered() ||
+        typeof MutationObserver === "undefined") {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        let quiet;
+        const observer = new MutationObserver(() => {
+            if (allRendered()) {
+                done();
+                return;
+            }
+            armQuiet();
+        });
+        function armQuiet() {
+            clearTimeout(quiet);
+            quiet = setTimeout(done, quietMs);
+        }
+        function done() {
+            clearTimeout(quiet);
+            observer.disconnect();
+            signal.removeEventListener("abort", done);
+            resolve();
+        }
+        observer.observe(root, {
+            childList: true,
+            subtree: true,
+            characterData: true,
+        });
+        signal.addEventListener("abort", done);
+        armQuiet();
+    });
+}

package/dist/pie/index.d.ts

@@ -18,16 +18,14 @@ export { initializeMathRendering, setMathRenderer, } from "./math-rendering.js";
 export { attachInstrumentationEventBridge } from "./instrumentation-event-bridge.js";
 export type { AttachInstrumentationEventBridgeArgs } from "./instrumentation-event-bridge.js";
 export { resolveInstrumentationProvider } from "./instrumentation-provider-resolution.js";
-export { STAGES, applicableStages, stageOrdinal, } from "./stages.js";
-export type { LoadingCompleteDetail, Stage, StageChangeDetail, StageSourceCe, StageStatus, } from "./stages.js";
-export { createStageTracker } from "./stage-tracker.js";
-export type { CreateStageTrackerOptions, StageTracker, } from "./stage-tracker.js";
+export { STAGES } from "./stages.js";
+export type { LoadingCompleteDetail, Stage, StageChangeDetail, StageStatus, } from "./stages.js";
 export { ASSESSMENT_INSTRUMENTATION_EVENT_MAP, ITEM_INSTRUMENTATION_EVENT_MAP, SECTION_INSTRUMENTATION_EVENT_MAP, TOOLKIT_INSTRUMENTATION_EVENT_MAP, } from "./instrumentation-event-map.js";
 export type { InstrumentationEventMapping } from "./instrumentation-event-map.js";
 export type { ItemControllerOptions } from "./item-controller.js";
 export { ItemController, normalizeItemSessionContainer, } from "./item-controller.js";
 export type { ItemSessionContainer as CanonicalItemSessionContainer, ItemSessionUpdateIntent, NormalizedItemSessionChange, } from "./item-session-contract.js";
-export { ensureHostSessionEntries, hasLearnerResponse, hasResponseValue, normalizeItemSessionChange, projectSessionIntoHostContainer, } from "./item-session-contract.js";
+export { ensureHostSessionEntries, hasLearnerResponse, hasResponseField, hasResponseValue, normalizeItemSessionChange, projectSessionIntoHostContainer, } from "./item-session-contract.js";
 export type { ItemSessionContainer, ItemSessionStorageStrategy, } from "./item-controller-storage.js";
 export { MemoryItemSessionStorage, SessionStorageItemSessionStorage, } from "./item-controller-storage.js";
 export { SESSION_COMMIT_METHOD, bindPageLifecycleCommit, commitPendingSessions, flushPendingSessionNotifications, noteSessionBaseline, noteSessionObserved, } from "./session-commit.js";
@@ -35,7 +33,7 @@ export type { BindPageLifecycleCommitOptions, CommitPendingSessionsOptions, Comm
 export { createSessionSnapshot, isSessionSnapshotEnabled, isSnapshotIdentitySpecific, sessionSnapshotKey, sessionStorageSnapshotStore, } from "./session-snapshot.js";
 export type { SessionSnapshot, SessionSnapshotConfig, SessionSnapshotIdentity, SessionSnapshotRecord, SessionSnapshotStore, } from "./session-snapshot.js";
 export type { PieLogger } from "./logger.js";
-export { createPieLogger, isGlobalDebugEnabled } from "./logger.js";
+export { createPieLogger, isGlobalDebugEnabled, isTtsDebugEnabled, } from "./logger.js";
 export { pieRegistry } from "./registry.js";
 export { findPieController, scorePieItem } from "./scoring.js";
 export type { Entry, EventListeners, EventListenersMap, LoadPieElementsOptions, PieElement, PieRegistry, UpdatePieElementOptions, } from "./types.js";