@pie-players/pie-assessment-toolkit 0.3.63 → 0.3.64

package/dist/services/defaultPersonalNeedsProfile.js

@@ -1,9 +1,32 @@
 import { createPackagedToolRegistry } from "./createDefaultToolRegistry.js";
+/**
+ * PNP support ids that must never enter the computed default profile, however
+ * they reach the registry.
+ *
+ * `computeDefaultSupports()` derives the fallback profile from every registered
+ * tool's `pnpSupportIds`, which is right for universal features — a highlighter
+ * or a zoom control should be there for every student by default. It is wrong
+ * for an **accommodation**: signing requires a documented need (IEP / 504), so
+ * granting it to every host that does not supply its own profile would invert
+ * the eligibility tier. Registry membership is about being policy-addressable,
+ * not about who may enable it.
+ *
+ * Excluded here rather than by declining to register, so the guarantee holds
+ * even if a signing tool is later registered for some other reason.
+ */
+export const ACCOMMODATION_ONLY_SUPPORT_IDS = [
+    // QTI 3.0 / AfA `signLanguage`. Signed alternates are rendered by
+    // section-player's per-item media region, gated on this id.
+    "signLanguage",
+];
 function computeDefaultSupports() {
     const registry = createPackagedToolRegistry();
     const supports = new Set();
+    const excluded = new Set(ACCOMMODATION_ONLY_SUPPORT_IDS);
     for (const tool of registry.getAllTools()) {
         for (const supportId of tool.pnpSupportIds || []) {
+            if (excluded.has(supportId))
+                continue;
             supports.add(supportId);
         }
     }

package/dist/services/interfaces.d.ts

@@ -8,7 +8,7 @@
  * Part of PIE Assessment Toolkit.
  */
 import type { I18nServiceApi } from "@pie-players/pie-players-shared/i18n";
-import type { AccessibilityCatalogResolver, CatalogLookupContext, CatalogLookupOptions, CatalogOwnerContext, CatalogStatistics, CatalogType, ResolvedCatalog } from "./AccessibilityCatalogResolver.js";
+import type { AccessibilityCatalogResolver, CatalogChangeListener, CatalogLookupContext, CatalogLookupOptions, CatalogOwnerContext, CatalogStatistics, CatalogType, ResolvedCatalog } from "./AccessibilityCatalogResolver.js";
 import type { FrameworkErrorListener } from "./framework-error-bus.js";
 import type { HighlightColor, HighlightType } from "./HighlightCoordinator.js";
 import type { SectionControllerHandle, SectionItemEventSubscriptionArgs, SectionScopedEventSubscriptionArgs, SectionEventSubscriptionArgs, ToolkitCoordinatorHooks, ToolkitInitStatus } from "./ToolkitCoordinator.js";
@@ -18,7 +18,7 @@ import type { PlaybackState, TTSConfig } from "./TTSService.js";
 import type { TTSHighlightTargetResolverProvider } from "./tts/highlight-target-resolver.js";
 import type { ToolPlacementConfig, ToolPlacementLevel, ToolProviderConfig } from "./tools-config-normalizer.js";
 import type { ToolProviderRegistry } from "./tool-providers/ToolProviderRegistry.js";
-import type { PolicySource, PnpEnforcementMode, ResolvedEngineInputs, ToolPolicyChangeListener, ToolPolicyDecision, ToolPolicyDecisionRequest } from "../policy/engine.js";
+import type { FeaturePolicyDecision, PolicySource, PnpEnforcementMode, ResolvedEngineInputs, ToolPolicyChangeListener, ToolPolicyDecision, ToolPolicyDecisionRequest } from "../policy/engine.js";
 import type { AssessmentEntity, AssessmentItemRef } from "@pie-players/pie-players-shared/types";
 import type { ITTSProvider, TTSProviderCapabilities } from "@pie-players/pie-tts";
 import type { ResolvedToolContext, ToolContextResolver, ToolContextResolverContext, ToolContextResolverMap } from "./ToolRegistry.js";
@@ -593,6 +593,16 @@ export interface ToolkitCoordinatorApi {
      * `decision.visibleTools` themselves.
      */
     decideToolPolicy(request: ToolPolicyDecisionRequest): ToolPolicyDecision;
+    /**
+     * Resolve eligibility for one PNP/AfA feature id through the six-level
+     * precedence, independent of toolbar placement — for capabilities that
+     * render as their own surface rather than a toolbar button (a signed
+     * alternate's region, for example).
+     *
+     * Optional so host-supplied coordinator stubs predating this method stay
+     * assignable; call sites must feature-detect.
+     */
+    decideFeaturePolicy?(featureId: string): FeaturePolicyDecision;
     /**
      * Subscribe to policy-engine change events. Fires whenever the
      * coordinator's bound policy inputs change (`updateToolConfig`,
@@ -602,6 +612,23 @@ export interface ToolkitCoordinatorApi {
      * call `decideToolPolicy(...)` with their level / scope.
      */
     onPolicyChange(listener: ToolPolicyChangeListener): () => void;
+    /**
+     * Subscribe to accessibility-catalog registrations and removals.
+     *
+     * The companion to {@link onPolicyChange} for the other mutable input a
+     * capability's visibility depends on. A region that renders a catalog card
+     * needs both: policy decides whether the learner may have it, catalogs decide
+     * whether the content exists, and catalogs arrive on an item shell's mount
+     * event — after a card alongside that item has already computed its first
+     * answer. Listeners re-query through
+     * {@link accessibilityCatalogResolver}; the event names only what changed.
+     *
+     * Required, unlike {@link decideFeaturePolicy}: this ships with its only
+     * consumer, so there are no pre-existing stubs to stay assignable to, and
+     * `AGENTS.md` rules out adding an internal-API compatibility shim without a
+     * documented exception.
+     */
+    onCatalogsChange(listener: CatalogChangeListener): () => void;
     /**
      * Bind (or clear) the active assessment for PNP/profile policy decisions.
      *

package/dist/services/pnp-standard-features.d.ts

@@ -167,7 +167,7 @@ export declare const QTI_STANDARD_ACCESS_FEATURES: {
 /**
  * Flat list of all standard access features for validation
  */
-export declare const ALL_STANDARD_ACCESS_FEATURES: ("braille" | "textToSpeech" | "graph" | "periodicTable" | "calculator" | "answerEliminator" | "ruler" | "protractor" | "graphingCalculator" | "readAloud" | "strikethrough" | "answerMasking" | "readingMask" | "readingGuide" | "readingRuler" | "highContrastDisplay" | "colorContrast" | "invertColors" | "highlighting" | "annotations" | "magnification" | "screenMagnifier" | "zoomable" | "highContrastAudio" | "displayTransformability" | "largePrint" | "fontEnlargement" | "resizeText" | "alternativeText" | "longDescription" | "describedMath" | "tactileGraphic" | "tactileObject" | "audioDescription" | "humanVoice" | "syntheticVoice" | "speechRate" | "speechVolume" | "voicePitch" | "captions" | "closedCaptions" | "openCaptions" | "transcript" | "signLanguage" | "subtitles" | "audioControl" | "noBackgroundAudio" | "keyboardControl" | "mouseControl" | "touchControl" | "voiceControl" | "switchControl" | "eyeGazeControl" | "singleSwitchAccess" | "stickyKeys" | "keyboardShortcuts" | "timingControl" | "unlimitedTime" | "extendedTime" | "pauseControl" | "simplifiedLanguage" | "reducedComplexity" | "structuralNavigation" | "tableOfContents" | "reducedDistraction" | "noFlashing" | "pauseAnimation" | "bookmarking" | "guidedNavigation" | "thesaurus" | "spellingAssistance" | "grammarAssistance" | "lineSpacing" | "wordSpacing" | "letterSpacing" | "fontFamily" | "wordHighlighting" | "lineHighlighting" | "focusIndicator" | "printableResource" | "nemeth" | "refreshableBraille" | "index" | "pageNavigation" | "skipContent" | "breadcrumbs" | "searchable" | "fullTextSearch" | "multilingualText" | "translatedText" | "glossary" | "signLanguageInterpretation" | "visualLanguage" | "formulaSheet" | "itemGlossary" | "tutorialAvailable")[];
+export declare const ALL_STANDARD_ACCESS_FEATURES: ("transcript" | "braille" | "textToSpeech" | "graph" | "periodicTable" | "calculator" | "answerEliminator" | "ruler" | "protractor" | "graphingCalculator" | "readAloud" | "strikethrough" | "answerMasking" | "readingMask" | "readingGuide" | "readingRuler" | "highContrastDisplay" | "colorContrast" | "invertColors" | "highlighting" | "annotations" | "signLanguage" | "magnification" | "screenMagnifier" | "zoomable" | "highContrastAudio" | "displayTransformability" | "largePrint" | "fontEnlargement" | "resizeText" | "alternativeText" | "longDescription" | "describedMath" | "tactileGraphic" | "tactileObject" | "audioDescription" | "humanVoice" | "syntheticVoice" | "speechRate" | "speechVolume" | "voicePitch" | "captions" | "closedCaptions" | "openCaptions" | "subtitles" | "audioControl" | "noBackgroundAudio" | "keyboardControl" | "mouseControl" | "touchControl" | "voiceControl" | "switchControl" | "eyeGazeControl" | "singleSwitchAccess" | "stickyKeys" | "keyboardShortcuts" | "timingControl" | "unlimitedTime" | "extendedTime" | "pauseControl" | "simplifiedLanguage" | "reducedComplexity" | "structuralNavigation" | "tableOfContents" | "reducedDistraction" | "noFlashing" | "pauseAnimation" | "bookmarking" | "guidedNavigation" | "thesaurus" | "spellingAssistance" | "grammarAssistance" | "lineSpacing" | "wordSpacing" | "letterSpacing" | "fontFamily" | "wordHighlighting" | "lineHighlighting" | "focusIndicator" | "printableResource" | "nemeth" | "refreshableBraille" | "index" | "pageNavigation" | "skipContent" | "breadcrumbs" | "searchable" | "fullTextSearch" | "multilingualText" | "translatedText" | "glossary" | "signLanguageInterpretation" | "visualLanguage" | "formulaSheet" | "itemGlossary" | "tutorialAvailable")[];
 /**
  * Example PNP configurations for common accessibility needs
  * These are NOT official profiles but illustrative examples showing

package/dist/services/sign-language-cards.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Sign-language catalog card payloads.
+ *
+ * A `sign-language` catalog card carries a signing video rather than text, so
+ * `CatalogCard.content` (a flat string) cannot describe it: no second source,
+ * no MIME type, no poster, no time range. `CatalogCard.payload` carries those,
+ * and this module is the single place that decides whether a card describes a
+ * playable signed alternate.
+ *
+ * The payload is the *only* accepted form. A bare URL in `content` is not a
+ * signing card: nothing writes that shape, so accepting it would buy a second
+ * code path and a second source of truth for no existing content. Such a card
+ * is reported and treated as absent rather than silently rendering.
+ *
+ * Validation is "treat as absent, never as text": a malformed payload must not
+ * degrade to an empty video or render a URL as visible content.
+ *
+ * There is deliberately no signing equivalent of `data-tts-suppress`. Whether a
+ * clip gives a decoding item away depends on fingerspelling versus lexical
+ * signing — a fact about the recording, known to the signer and not to whoever
+ * authors an attribute. And suppression is per node while a signed alternate is
+ * one video per item, so the only available rule would withhold a deaf
+ * candidate's whole translation over one word. Read-aloud needs a machine-readable
+ * guard because a synthesizer speaks whatever text is present; signed content does
+ * not exist until a signer films it. Revisit only if per-node signing docking
+ * lands and a program authors signing for decoding-construct items.
+ *
+ * Part of PIE Assessment Toolkit.
+ */
+import type { CatalogCard, CatalogCardPayload, MediaFragmentRange, MediaSource } from "@pie-players/pie-players-shared/types";
+import { applyMediaFragment } from "./catalog-media.js";
+export { applyMediaFragment };
+/** Catalog type token for signed alternates. Matches QTI 3's `support` value. */
+export declare const SIGN_LANGUAGE_CATALOG_TYPE = "sign-language";
+/** ISO 639-3 code for American Sign Language, and QTI 3's `xml:lang` value. */
+export declare const AMERICAN_SIGN_LANGUAGE = "ase";
+export declare function describeSignLanguage(signLang?: string): string;
+/**
+ * A validated signed alternate, flattened for rendering.
+ *
+ * `signLang` is optional because a card need not assert a language. Callers
+ * decide what to do with an unknown one; see `matchesRequestedSignLanguage`.
+ */
+export interface SignLanguageMedia {
+    signLang?: string;
+    sources: MediaSource[];
+    poster?: string;
+    label?: string;
+    fragment?: MediaFragmentRange;
+}
+type SignLanguageCardLike = {
+    language?: string;
+    content?: string;
+    payload?: CatalogCardPayload;
+};
+/**
+ * Validate a `sign-language` card into something renderable, or `null`.
+ *
+ * Returns `null` — meaning "this card is absent" — when the payload yields no
+ * usable source. Never returns a partially-valid result that would render an
+ * empty player.
+ *
+ * A payload that carries sources but no `signLang` falls back to the card's
+ * `language`, and then to unlabelled. Language *matching* is a separate
+ * decision (see `matchesRequestedSignLanguage`) so the strict
+ * no-cross-sign-language rule lives in exactly one place.
+ */
+export declare function resolveSignLanguageMedia(card: SignLanguageCardLike | null | undefined): SignLanguageMedia | null;
+/**
+ * Whether a resolved signed alternate may be shown for a requested sign
+ * language.
+ *
+ * Deliberately strict: there is no cross-sign-language fallback. ASL, BSL and
+ * LSF are not interchangeable, so showing a different sign language than the
+ * one requested would hand a learner a language they may not follow — worse
+ * than showing nothing. A card that asserts *no* language is accepted, because it
+ * cannot be shown to be a mismatch — only a positive claim of another language
+ * is refused.
+ */
+export declare function matchesRequestedSignLanguage(media: SignLanguageMedia, requestedSignLang: string): boolean;
+/** Whether a catalog card is a sign-language card at all. */
+export declare function isSignLanguageCard(card: CatalogCard): boolean;

package/dist/services/sign-language-cards.js

@@ -0,0 +1,133 @@
+/**
+ * Sign-language catalog card payloads.
+ *
+ * A `sign-language` catalog card carries a signing video rather than text, so
+ * `CatalogCard.content` (a flat string) cannot describe it: no second source,
+ * no MIME type, no poster, no time range. `CatalogCard.payload` carries those,
+ * and this module is the single place that decides whether a card describes a
+ * playable signed alternate.
+ *
+ * The payload is the *only* accepted form. A bare URL in `content` is not a
+ * signing card: nothing writes that shape, so accepting it would buy a second
+ * code path and a second source of truth for no existing content. Such a card
+ * is reported and treated as absent rather than silently rendering.
+ *
+ * Validation is "treat as absent, never as text": a malformed payload must not
+ * degrade to an empty video or render a URL as visible content.
+ *
+ * There is deliberately no signing equivalent of `data-tts-suppress`. Whether a
+ * clip gives a decoding item away depends on fingerspelling versus lexical
+ * signing — a fact about the recording, known to the signer and not to whoever
+ * authors an attribute. And suppression is per node while a signed alternate is
+ * one video per item, so the only available rule would withhold a deaf
+ * candidate's whole translation over one word. Read-aloud needs a machine-readable
+ * guard because a synthesizer speaks whatever text is present; signed content does
+ * not exist until a signer films it. Revisit only if per-node signing docking
+ * lands and a program authors signing for decoding-construct items.
+ *
+ * Part of PIE Assessment Toolkit.
+ */
+import { applyMediaFragment, isSafeMediaSrc, normalizeMediaFragment, normalizeMediaSources, trimmedOrUndefined, } from "./catalog-media.js";
+// Re-exported because `applyMediaFragment` is part of the toolkit's public
+// surface under this module's name; the implementation is shared with spoken
+// audio cards now that both forms reference media.
+export { applyMediaFragment };
+/** Catalog type token for signed alternates. Matches QTI 3's `support` value. */
+export const SIGN_LANGUAGE_CATALOG_TYPE = "sign-language";
+/** ISO 639-3 code for American Sign Language, and QTI 3's `xml:lang` value. */
+export const AMERICAN_SIGN_LANGUAGE = "ase";
+/**
+ * Human-readable names for the sign languages PIE has a reason to name today.
+ *
+ * Used for the region's accessible label, which must name the language ("American
+ * Sign Language") rather than say "video". Unknown codes fall back to a labelled
+ * code rather than a lie.
+ */
+const SIGN_LANGUAGE_NAMES = {
+    ase: "American Sign Language",
+    bfi: "British Sign Language",
+    fsl: "French Sign Language",
+    gss: "Greek Sign Language",
+    mfs: "Mexican Sign Language",
+    // Signed English is not a distinct sign language; it rides the same card
+    // type tagged with a spoken-language code, so name it where it appears.
+    "eng-US": "Signed English",
+    "en-US": "Signed English",
+};
+export function describeSignLanguage(signLang) {
+    const code = (signLang || "").trim();
+    if (!code)
+        return "Sign language";
+    return SIGN_LANGUAGE_NAMES[code] ?? `Sign language (${code})`;
+}
+/**
+ * Validate a `sign-language` card into something renderable, or `null`.
+ *
+ * Returns `null` — meaning "this card is absent" — when the payload yields no
+ * usable source. Never returns a partially-valid result that would render an
+ * empty player.
+ *
+ * A payload that carries sources but no `signLang` falls back to the card's
+ * `language`, and then to unlabelled. Language *matching* is a separate
+ * decision (see `matchesRequestedSignLanguage`) so the strict
+ * no-cross-sign-language rule lives in exactly one place.
+ */
+export function resolveSignLanguageMedia(card) {
+    if (!card)
+        return null;
+    const cardLanguage = trimmedOrUndefined(card.language);
+    const payload = card.payload;
+    if (!payload || typeof payload !== "object") {
+        // Always say something. A signing card that yields nothing is invisible to
+        // everyone except the learner who needed the accommodation, so the only
+        // place it can surface is here.
+        //
+        // `payload` was briefly also spelled `signLanguage` by two producers, and
+        // this function accepted both. It no longer does — one fact under two names
+        // is what let a card render on one code path and read as absent on another —
+        // so a card left over from that spelling arrives here with no payload at
+        // all, which is what the second message is for.
+        if (trimmedOrUndefined(card.content)) {
+            console.warn("[sign-language] card carries `content` but no `payload`; signing media must be a structured payload, so this card is ignored");
+        }
+        else {
+            console.warn("[sign-language] card carries no `payload`; signing media lives in `payload` (a card written against the older `signLanguage` key needs re-importing), so this card is ignored");
+        }
+        return null;
+    }
+    const media = payload.media;
+    const sources = normalizeMediaSources(media?.sources);
+    if (sources.length === 0)
+        return null;
+    const poster = trimmedOrUndefined(media?.poster);
+    return {
+        signLang: trimmedOrUndefined(payload.signLang) ?? cardLanguage,
+        sources,
+        poster: poster && isSafeMediaSrc(poster) ? poster : undefined,
+        label: trimmedOrUndefined(media?.label),
+        fragment: normalizeMediaFragment(payload.fragment),
+    };
+}
+/**
+ * Whether a resolved signed alternate may be shown for a requested sign
+ * language.
+ *
+ * Deliberately strict: there is no cross-sign-language fallback. ASL, BSL and
+ * LSF are not interchangeable, so showing a different sign language than the
+ * one requested would hand a learner a language they may not follow — worse
+ * than showing nothing. A card that asserts *no* language is accepted, because it
+ * cannot be shown to be a mismatch — only a positive claim of another language
+ * is refused.
+ */
+export function matchesRequestedSignLanguage(media, requestedSignLang) {
+    if (!media.signLang)
+        return true;
+    const requested = (requestedSignLang || "").trim();
+    if (!requested)
+        return true;
+    return media.signLang.toLowerCase() === requested.toLowerCase();
+}
+/** Whether a catalog card is a sign-language card at all. */
+export function isSignLanguageCard(card) {
+    return card?.catalog === SIGN_LANGUAGE_CATALOG_TYPE;
+}

package/dist/services/spoken-audio-cards.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Recorded audio as a `spoken` catalog card.
+ *
+ * QTI 3 treats a recording and synthesized speech as the *same* support — both
+ * are `spoken`, and a card carries recorded audio through `qti-file-href` plus a
+ * MIME type — so this is not a new accommodation but the other form the existing
+ * one can take. Some programs prefer a human voice to synthesis; PIE's `spoken`
+ * card was string-only, so it had no way to say "play this file for this node".
+ *
+ * A node commonly carries both forms in the same language: the reading script
+ * *and* a recording of it. That is APIP's pattern and what QTI's migration
+ * guidance preserves, because the script is both the source the audio was
+ * generated from and the fallback for when the audio will not play. Resolution
+ * chooses between them with `CatalogLookupOptions.form`; playback treats the
+ * script as the recording's fallback.
+ *
+ * Validation posture matches sign-language cards: "treat as absent, never as
+ * partially valid". A malformed payload must not produce a silent player that
+ * looks like read-aloud is working.
+ *
+ * Part of PIE Assessment Toolkit.
+ */
+import type { CatalogCardPayload, MediaFragmentRange, MediaSource } from "@pie-players/pie-players-shared/types";
+/** Catalog type token for spoken alternates. Matches QTI 3's `support` value. */
+export declare const SPOKEN_CATALOG_TYPE = "spoken";
+/** A validated recorded spoken alternate, flattened for playback. */
+export interface SpokenAudioMedia {
+    /**
+     * Authored order preserved. Playback uses the first entry: an `<audio>` element
+     * fed alternative `<source>` children reports failure through a path that is
+     * awkward to observe reliably, and a dependable fallback to the reading script
+     * is worth more than encoding negotiation. Extra entries are kept so a future
+     * consumer can negotiate without re-reading the card.
+     */
+    sources: MediaSource[];
+    fragment?: MediaFragmentRange;
+    label?: string;
+}
+type SpokenAudioCardLike = {
+    language?: string;
+    content?: string;
+    payload?: CatalogCardPayload;
+};
+/**
+ * Validate a `spoken` card's payload into something playable, or `null`.
+ *
+ * Silent when the card simply is not a recording — a card carrying `content` is
+ * a reading script, which is the overwhelmingly common case and not a fault.
+ * Loud when a card looks like it meant to be a recording and cannot be played,
+ * because that failure is otherwise invisible to everyone but the learner who
+ * needed it.
+ */
+export declare function resolveSpokenAudioMedia(card: SpokenAudioCardLike | null | undefined): SpokenAudioMedia | null;
+export {};

package/dist/services/spoken-audio-cards.js

@@ -0,0 +1,66 @@
+/**
+ * Recorded audio as a `spoken` catalog card.
+ *
+ * QTI 3 treats a recording and synthesized speech as the *same* support — both
+ * are `spoken`, and a card carries recorded audio through `qti-file-href` plus a
+ * MIME type — so this is not a new accommodation but the other form the existing
+ * one can take. Some programs prefer a human voice to synthesis; PIE's `spoken`
+ * card was string-only, so it had no way to say "play this file for this node".
+ *
+ * A node commonly carries both forms in the same language: the reading script
+ * *and* a recording of it. That is APIP's pattern and what QTI's migration
+ * guidance preserves, because the script is both the source the audio was
+ * generated from and the fallback for when the audio will not play. Resolution
+ * chooses between them with `CatalogLookupOptions.form`; playback treats the
+ * script as the recording's fallback.
+ *
+ * Validation posture matches sign-language cards: "treat as absent, never as
+ * partially valid". A malformed payload must not produce a silent player that
+ * looks like read-aloud is working.
+ *
+ * Part of PIE Assessment Toolkit.
+ */
+import { normalizeMediaFragment, normalizeMediaSources, trimmedOrUndefined, } from "./catalog-media.js";
+/** Catalog type token for spoken alternates. Matches QTI 3's `support` value. */
+export const SPOKEN_CATALOG_TYPE = "spoken";
+/**
+ * Validate a `spoken` card's payload into something playable, or `null`.
+ *
+ * Silent when the card simply is not a recording — a card carrying `content` is
+ * a reading script, which is the overwhelmingly common case and not a fault.
+ * Loud when a card looks like it meant to be a recording and cannot be played,
+ * because that failure is otherwise invisible to everyone but the learner who
+ * needed it.
+ */
+export function resolveSpokenAudioMedia(card) {
+    if (!card)
+        return null;
+    const payload = card.payload;
+    if (!payload || typeof payload !== "object") {
+        // A script card, not a broken audio card. Resolution asks for the payload
+        // form as a *preference*, so getting a `content` card back here is normal.
+        return null;
+    }
+    const media = payload.media;
+    if (!media || typeof media !== "object") {
+        console.warn("[spoken-audio] card carries a `payload` with no `media`; recorded speech needs `media.sources`, so this card is ignored and read-aloud falls back to the script or generated speech");
+        return null;
+    }
+    // A signing video filed under `spoken` is a mis-authored card, not an audio
+    // track to guess at. Refusing it keeps the two card types from quietly
+    // swapping roles.
+    if (media.kind !== undefined && media.kind !== "audio") {
+        console.warn(`[spoken-audio] card's media is kind "${media.kind}", not "audio"; a spoken card carries recorded speech, so this card is ignored`);
+        return null;
+    }
+    const sources = normalizeMediaSources(media.sources);
+    if (sources.length === 0) {
+        console.warn("[spoken-audio] card's `media.sources` yielded no usable URL; read-aloud falls back to the script or generated speech");
+        return null;
+    }
+    return {
+        sources,
+        fragment: normalizeMediaFragment(payload.fragment),
+        label: trimmedOrUndefined(media.label),
+    };
+}

package/dist/services/tts/math-aware-text-processing.js

@@ -1,5 +1,5 @@
 import { canonicalizeMathML } from "./mathml-sanitization.js";
-import { collectVisibleTextAndMap, isNodeHiddenForTTS, normalizeTextForSpeech, shouldInsertWordBoundarySpace, } from "./text-processing.js";
+import { collectVisibleTextAndMap, isNodeExcludedFromSpeech, normalizeTextForSpeech, shouldInsertWordBoundarySpace, } from "./text-processing.js";
 const createAccumulator = (options) => ({
     chars: [],
     map: new Map(),
@@ -226,7 +226,7 @@ const textFallbackFromMathML = (mathml) => {
 const collectVisibleMathFallback = (element, canonicalMathML, options) => {
     const mathAcc = createAccumulator(options);
     const visit = (node) => {
-        if (isNodeHiddenForTTS(node, element))
+        if (isNodeExcludedFromSpeech(node, element))
             return;
         if (node.nodeType === 3) {
             appendTextNode(mathAcc, node);
@@ -284,7 +284,7 @@ const collectMathAware = (root, options) => {
         textChunkSourceElement = undefined;
     };
     const processNode = (node) => {
-        if (isNodeHiddenForTTS(node, root))
+        if (isNodeExcludedFromSpeech(node, root))
             return;
         if (node.nodeType === Node.TEXT_NODE) {
             const sourceElement = resolveTextChunkSourceElement(node, root);

package/dist/services/tts/text-processing.d.ts

@@ -11,6 +11,57 @@ export declare const normalizeTextForSpeech: (text: string) => string;
 export declare const createSpeechAlignmentTokenPattern: () => RegExp;
 export declare const isElementHiddenForTTS: (element: Element) => boolean;
 export declare const isNodeHiddenForTTS: (node: Node, root?: Element | null) => boolean;
+/**
+ * Marks content that must be shown but never spoken — items where reading *is*
+ * the construct, such as decoding and spelling, where speaking the node hands
+ * over the answer.
+ *
+ * Not a PNP field: `prohibitedSupports` is the learner declining a support, while
+ * this is the item saying "not here, for anyone", so it overrides an entitlement
+ * rather than yielding to it.
+ *
+ * Shape follows QTI 3's `data-qti-suppress-tts` — an attribute on the content
+ * element, single-valued, vocabulary below. Element placement is what makes it
+ * work on undocked nodes and enforceable in the selection read-aloud path, which
+ * consults no catalog. The name follows PIE's `data-tts-*` family, and PIE reads
+ * only this spelling; importers map QTI's.
+ */
+export declare const TTS_SUPPRESS_ATTRIBUTE = "data-tts-suppress";
+/**
+ * Whether this element forbids machine read-aloud of itself and its subtree.
+ *
+ * Unrecognized and empty values suppress rather than pass through, and say so once
+ * per distinct value: a typo that fell through would speak a word the item was
+ * measuring, invalidating the score with no visible symptom, whereas
+ * over-suppressing only withholds speech an author had already marked as withheld.
+ */
+export declare const isElementSuppressedForTTS: (element: Element) => boolean;
+export declare const isNodeSuppressedForTTS: (node: Node, root?: Element | null) => boolean;
+/**
+ * The predicate every speech-producing path filters on: hidden *or* suppressed.
+ *
+ * Kept distinct from `isNodeHiddenForTTS`, which stays a question about
+ * visibility — suppressed content is visible on purpose, and the highlight
+ * geometry resolvers that ask "can the candidate see this" must keep getting
+ * the visibility answer rather than this one.
+ */
+export declare const isNodeExcludedFromSpeech: (node: Node, root?: Element | null) => boolean;
+/**
+ * Text of a range with the parts that must not be spoken removed.
+ *
+ * `Range.toString()` is not usable for speech: it is pure character extraction
+ * and honours no DOM filter at all, so it happily returns suppressed — and
+ * hidden — text. The selection read-aloud path is a text-in path rather than a
+ * DOM walk, which makes this the only place its content can be filtered.
+ *
+ * `filtered` reports whether anything was dropped, so a caller can tell "the
+ * candidate selected nothing speakable" apart from "the candidate selected
+ * nothing".
+ */
+export declare const collectRangeTextForSpeech: (range: Range, root: Element) => {
+    text: string;
+    filtered: boolean;
+};
 export declare const shouldInsertWordBoundarySpace: (previousChar: string | null, nextChar: string | null, options?: TextProcessingOptions) => boolean;
 export declare const collectVisibleTextAndMap: (element: Element, options?: TextProcessingOptions) => {
     text: string;