@pie-players/pie-default-tool-loaders 0.3.65 → 0.3.66

package/dist/registrations/audio-transcript.js

@@ -0,0 +1,183 @@
+/**
+ * Audio transcript: the text of an audio prompt, rendered for the learners
+ * entitled to it.
+ *
+ * Two kinds of content wear the same shape, and the card says which:
+ *
+ *   - `visibility: "always"` is authored presentation. The item family was
+ *     designed to be delivered with its transcript on screen — Star Early
+ *     Literacy sentence items, for instance — so no profile grants it and none
+ *     revokes it.
+ *   - anything else, `"onGrant"` included, is the accommodation. Policy decides
+ *     against the `transcript` support id, and silence means no. For the three
+ *     Star families where a visible transcript turns the item into a reading
+ *     task, that gate is the whole point.
+ *
+ * The toolkit renders the text, not the element. Before this, the transcript rode
+ * on `model.audioTranscript` and `mc-populated-blank` revealed its own copy when
+ * an ancestor carried `.rli-with-audio-transcript` — which made delivering an
+ * accommodation the host's job, required every element carrying audio to
+ * reimplement the reveal, and put an element-specific CSS class in the contract.
+ * Rendering here is the same shape signing already has, and it is what makes one
+ * mechanism serve braille, simplified-language and the rest.
+ *
+ * No `aria-describedby` back to the element's audio control, deliberately. A
+ * description is announced as a flat string when a control takes focus, so
+ * pointing one at a multi-sentence transcript is worse to listen to than reading
+ * order: this renders a labelled region immediately before the content, where a
+ * screen-reader user meets it on the way to the control it belongs to.
+ *
+ * It ships in the packaged set, unlike signing, because its presentation half has
+ * to work with no host opt-in: an item authored to show its transcript must show
+ * it in every player, and a deployment that forgot an import would silently
+ * deliver a designed-for reading support as nothing. The accommodation half is
+ * still policy-gated exactly as signing is, and `transcript` is deliberately
+ * absent from the universal preset — a content-dependent support never belongs in
+ * a wholesale grant.
+ */
+/** QTI 3.0 / AfA support id gating an audio transcript. */
+export const AUDIO_TRANSCRIPT_FEATURE_ID = "transcript";
+/** Catalog type carrying the transcript text. */
+export const AUDIO_TRANSCRIPT_CATALOG_TYPE = "transcript";
+/** Accessible name of the rendered region, and its class hook for themes. */
+export const AUDIO_TRANSCRIPT_REGION_LABEL = "Transcript";
+export const AUDIO_TRANSCRIPT_REGION_CLASS = "pie-tool-audio-transcript";
+/** Card value that makes a transcript authored presentation. */
+const ALWAYS_VISIBLE = "always";
+const isTranscriptCard = (card) => !!card && card.catalog === AUDIO_TRANSCRIPT_CATALOG_TYPE;
+/**
+ * Whether a card declares itself authored presentation.
+ *
+ * Absent reads as the accommodation, the same fail-closed reading the policy
+ * engine takes of a silent profile: a card that says nothing about presentation
+ * has not claimed to be presentation.
+ */
+const isAlwaysVisible = (card) => typeof card.visibility === "string" &&
+    card.visibility.trim().toLowerCase() === ALWAYS_VISIBLE;
+const cardText = (card) => typeof card.content === "string" ? card.content.trim() : "";
+/**
+ * The transcript an entity carries, or `null`.
+ *
+ * Read from the owner snapshot the resolver produced. Item/passage/model
+ * traversal and registration precedence have already been applied, so this
+ * capability owns only transcript interpretation.
+ *
+ * The cards are read directly rather than through `AccessibilityCatalogResolver`,
+ * which flattens a card to type/language/content and so cannot carry
+ * `visibility` — the one attribute this decision turns on. Nothing is lost by it:
+ * the resolver's value is choosing between languages of the same alternate, and a
+ * transcript is in the language of the audio it transcribes, one per prompt.
+ */
+export function resolveAudioTranscript(context) {
+    if (!context.catalogs)
+        return null;
+    let firstOnGrant = null;
+    for (const { catalogId, card } of context.catalogs.cards) {
+        if (!isTranscriptCard(card))
+            continue;
+        const text = cardText(card);
+        // A card with no text is not a transcript; rendering an empty region
+        // would announce an alternate that is not there.
+        if (!text)
+            continue;
+        const resolved = {
+            catalogId,
+            text,
+            language: typeof card.language === "string" ? card.language : undefined,
+            always: isAlwaysVisible(card),
+        };
+        // An `always` card answers whether or not policy granted anything, so it
+        // wins over an accommodation card found earlier.
+        if (resolved.always)
+            return resolved;
+        firstOnGrant ??= resolved;
+    }
+    if (!firstOnGrant)
+        return null;
+    // The accommodation half: without a grant this learner is not entitled to it,
+    // and being asked anyway is the price of also serving the authored case.
+    return context.granted ? firstOnGrant : null;
+}
+/**
+ * Host surface this capability fills: the full-width slot above a card's content.
+ *
+ * Item cards and passage cards open the same surface, so declaring it once
+ * reaches both — a passage can carry an audio prompt as an item can.
+ */
+export const CONTENT_LEAD_SURFACE = "content-lead";
+/**
+ * A labelled region holding the transcript text.
+ *
+ * Plain DOM rather than a custom element: there is no state, no lifecycle and
+ * nothing to load, so a package and a registration ceremony would buy nothing.
+ * `renderSurface` promises an `HTMLElement`, not a custom one.
+ */
+function buildTranscriptRegion() {
+    const region = document.createElement("section");
+    region.className = AUDIO_TRANSCRIPT_REGION_CLASS;
+    // A region rather than a bare paragraph so it is reachable as a landmark and
+    // announces its purpose before its content.
+    region.setAttribute("role", "region");
+    const text = document.createElement("p");
+    text.className = `${AUDIO_TRANSCRIPT_REGION_CLASS}__text`;
+    region.appendChild(text);
+    return region;
+}
+const applyTranscript = (region, transcript) => {
+    const text = region.querySelector(`.${AUDIO_TRANSCRIPT_REGION_CLASS}__text`);
+    if (!text)
+        return;
+    text.textContent = transcript?.text ?? "";
+    if (transcript?.language) {
+        region.setAttribute("lang", transcript.language);
+    }
+    else {
+        region.removeAttribute("lang");
+    }
+    // Which half put it on screen, for a policy debugger and for hosts that theme
+    // authored presentation differently from an accommodation.
+    region.dataset.transcriptVisibility = transcript?.always
+        ? "always"
+        : "onGrant";
+};
+export const audioTranscriptRegistration = {
+    toolId: AUDIO_TRANSCRIPT_FEATURE_ID,
+    name: "Audio Transcript",
+    description: "Text of an audio prompt, read before the content it transcribes",
+    supportedLevels: ["item", "passage"],
+    pnpSupportIds: [AUDIO_TRANSCRIPT_FEATURE_ID],
+    // No button to press: a transcript is either authored-visible, or granted and
+    // present, or absent. `region` is the activation for a capability with no
+    // toolbar presence, and tools-config validation reports a `tools.placement`
+    // entry naming it as unplaceable rather than silently doing nothing.
+    activation: "region",
+    surfaces: [CONTENT_LEAD_SURFACE],
+    // The resource half of the AfA pair, and the only reader of the card.
+    requiresAuthoredContent: {
+        resolve(context) {
+            return resolveAudioTranscript(context);
+        },
+        description: "An accessibility catalog card of type `transcript` on the item or passage",
+    },
+    // Authored presentation is not a grant, so the content has to be consulted even
+    // when policy granted nothing; `resolveAudioTranscript` returns null for an
+    // accommodation card in that case.
+    resolvesWithoutGrant: true,
+    renderSurface(context) {
+        const transcript = context.content;
+        // No content means the host asked before resolving, or resolved to nothing.
+        // Declining is the honest answer; an empty region is not.
+        if (!transcript)
+            return null;
+        const region = buildTranscriptRegion();
+        applyTranscript(region, transcript);
+        return {
+            element: region,
+            ariaLabel: AUDIO_TRANSCRIPT_REGION_LABEL,
+            // Reads the context it is handed, never the one captured above: on a
+            // re-resolve the host's context carries the current card, and a learner must
+            // not keep reading the previous item's transcript.
+            sync: (current) => applyTranscript(region, current.content),
+        };
+    },
+};

package/dist/tool-placement.d.ts

@@ -1,29 +1 @@
-/**
- * Placement presets for the packaged capability set.
- *
- * Composition data for the same reason the tag map and the registrations are:
- * they name capabilities. The toolkit keeps `DEFAULT_TOOL_PLACEMENT`, which is
- * empty at every level and names none.
- */
-/**
- * Every packaged capability at every level it supports. Prefer explicit host
- * configuration over adopting this wholesale.
- */
-export declare const PACKAGED_TOOL_PLACEMENT: {
-    readonly assessment: readonly ["theme"];
-    readonly section: readonly ["theme"];
-    readonly item: readonly ["textToSpeech", "highlighter", "annotationToolbar", "graph", "periodicTable"];
-    readonly passage: readonly ["textToSpeech", "highlighter", "annotationToolbar", "lineReader"];
-    readonly rubric: readonly ["textToSpeech", "highlighter", "annotationToolbar", "lineReader"];
-    readonly element: readonly ["calculator", "answerEliminator", "textToSpeech", "ruler", "protractor", "highlighter", "annotationToolbar", "graph", "periodicTable"];
-};
-/**
- * Each packaged capability once, at its usual assessment surface. Not
- * exhaustive: `supportedLevels` still bounds where a capability can run, and a
- * host can place them differently for its own UX.
- */
-export declare const SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT: {
-    section: string[];
-    item: string[];
-    passage: string[];
-};
+export { PACKAGED_TOOL_PLACEMENT, SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT, } from "./packaged-capability-composition.js";

package/dist/tool-placement.js

@@ -1,52 +1 @@
-/**
- * Placement presets for the packaged capability set.
- *
- * Composition data for the same reason the tag map and the registrations are:
- * they name capabilities. The toolkit keeps `DEFAULT_TOOL_PLACEMENT`, which is
- * empty at every level and names none.
- */
-/**
- * Every packaged capability at every level it supports. Prefer explicit host
- * configuration over adopting this wholesale.
- */
-export const PACKAGED_TOOL_PLACEMENT = {
-    assessment: ["theme"],
-    section: ["theme"],
-    item: [
-        "textToSpeech",
-        "highlighter",
-        "annotationToolbar",
-        "graph",
-        "periodicTable",
-    ],
-    passage: ["textToSpeech", "highlighter", "annotationToolbar", "lineReader"],
-    rubric: ["textToSpeech", "highlighter", "annotationToolbar", "lineReader"],
-    element: [
-        "calculator",
-        "answerEliminator",
-        "textToSpeech",
-        "ruler",
-        "protractor",
-        "highlighter",
-        "annotationToolbar",
-        "graph",
-        "periodicTable",
-    ],
-};
-/**
- * Each packaged capability once, at its usual assessment surface. Not
- * exhaustive: `supportedLevels` still bounds where a capability can run, and a
- * host can place them differently for its own UX.
- */
-export const SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT = {
-    section: [
-        "theme",
-        "graph",
-        "periodicTable",
-        "lineReader",
-        "ruler",
-        "protractor",
-    ],
-    item: ["calculator", "textToSpeech", "answerEliminator", "annotationToolbar"],
-    passage: ["textToSpeech", "annotationToolbar"],
-};
+export { PACKAGED_TOOL_PLACEMENT, SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT, } from "./packaged-capability-composition.js";

package/dist/tool-tag-map.d.ts

@@ -1,16 +1 @@
-import type { ToolTagMap } from "@pie-players/pie-assessment-toolkit/tools/internal";
-/**
- * Element tag for each packaged tool.
- *
- * Composition data, not core data: it is a catalogue of which capabilities exist
- * in a deployment and which element renders each. It lived in the toolkit, where
- * a core module naming eleven capabilities meant a host could not add a twelfth
- * without editing our package — the map was overridable, but its default was
- * core-resident, so the core still had to know the names.
- *
- * `resolveToolTag` in the toolkit reads only the overrides it is handed, and
- * `createPackagedToolRegistry` installs this map through
- * `ToolRegistry.setComponentOverrides`. A host composing its own registry
- * supplies its own map the same way.
- */
-export declare const PACKAGED_TOOL_TAG_MAP: ToolTagMap;
+export { PACKAGED_TOOL_TAG_MAP } from "./packaged-capability-composition.js";

package/dist/tool-tag-map.js

@@ -1,27 +1 @@
-/**
- * Element tag for each packaged tool.
- *
- * Composition data, not core data: it is a catalogue of which capabilities exist
- * in a deployment and which element renders each. It lived in the toolkit, where
- * a core module naming eleven capabilities meant a host could not add a twelfth
- * without editing our package — the map was overridable, but its default was
- * core-resident, so the core still had to know the names.
- *
- * `resolveToolTag` in the toolkit reads only the overrides it is handed, and
- * `createPackagedToolRegistry` installs this map through
- * `ToolRegistry.setComponentOverrides`. A host composing its own registry
- * supplies its own map the same way.
- */
-export const PACKAGED_TOOL_TAG_MAP = {
-    calculator: "pie-tool-calculator",
-    textToSpeech: "pie-tool-text-to-speech",
-    ruler: "pie-tool-ruler",
-    protractor: "pie-tool-protractor",
-    answerEliminator: "pie-tool-answer-eliminator",
-    highlighter: "pie-tool-annotation-toolbar",
-    lineReader: "pie-tool-line-reader",
-    theme: "pie-tool-theme",
-    annotationToolbar: "pie-tool-annotation-toolbar",
-    graph: "pie-tool-graph",
-    periodicTable: "pie-tool-periodic-table",
-};
+export { PACKAGED_TOOL_TAG_MAP } from "./packaged-capability-composition.js";

package/dist/universal-supports.d.ts

@@ -1,33 +1 @@
-/**
- * Named preset of the PNP support ids the packaged tool set treats as universal
- * features — data, not a derivation.
- *
- * This list was previously computed at import time by unioning every registered
- * tool's `pnpSupportIds`, which made registry membership decide eligibility tier
- * and had to be corrected by a compile-time exclusion list no host could extend.
- * The ids below are that computation's output, frozen: adopt it, extend it, or
- * replace it alongside the district and test-administration configuration, the
- * same way any other policy input is chosen.
- *
- * Two properties this list must keep:
- *
- *   1. **Universal features only.** An accommodation belongs here only if the
- *      program has decided it is universal — which is a decision about the
- *      program, not about the capability. TTS sits here because the packaged set
- *      treats it as a universal feature; it is a documented accommodation in
- *      other programs.
- *   2. **No content-dependent capability.** A capability declaring
- *      `requiresAuthoredContent` needs an authored resource to have anything to
- *      show, so granting it wholesale grants an accommodation to learners who
- *      have no documented need for it. `tests/universal-supports.test.ts`
- *      enforces this against the registrations rather than against a name list.
- */
-import type { PersonalNeedsProfile } from "@pie-players/pie-players-shared/types";
-export declare const UNIVERSAL_SUPPORTS_PRESET: readonly string[];
-/**
- * Build a profile granting {@link UNIVERSAL_SUPPORTS_PRESET}.
- *
- * A fresh array per call: a profile flows into policy inputs that hosts mutate,
- * and handing out a shared reference would let one host's edit reach another's.
- */
-export declare function createUniversalPersonalNeedsProfile(): PersonalNeedsProfile;
+export { UNIVERSAL_SUPPORTS_PRESET, createUniversalPersonalNeedsProfile, } from "./packaged-capability-composition.js";

package/dist/universal-supports.js

@@ -1,77 +1 @@
-/**
- * Named preset of the PNP support ids the packaged tool set treats as universal
- * features — data, not a derivation.
- *
- * This list was previously computed at import time by unioning every registered
- * tool's `pnpSupportIds`, which made registry membership decide eligibility tier
- * and had to be corrected by a compile-time exclusion list no host could extend.
- * The ids below are that computation's output, frozen: adopt it, extend it, or
- * replace it alongside the district and test-administration configuration, the
- * same way any other policy input is chosen.
- *
- * Two properties this list must keep:
- *
- *   1. **Universal features only.** An accommodation belongs here only if the
- *      program has decided it is universal — which is a decision about the
- *      program, not about the capability. TTS sits here because the packaged set
- *      treats it as a universal feature; it is a documented accommodation in
- *      other programs.
- *   2. **No content-dependent capability.** A capability declaring
- *      `requiresAuthoredContent` needs an authored resource to have anything to
- *      show, so granting it wholesale grants an accommodation to learners who
- *      have no documented need for it. `tests/universal-supports.test.ts`
- *      enforces this against the registrations rather than against a name list.
- */
-export const UNIVERSAL_SUPPORTS_PRESET = Object.freeze([
-    "angleMeasurement",
-    "annotation",
-    "annotations",
-    "answerEliminator",
-    "answerMasking",
-    "basicCalculator",
-    "calculator",
-    "chemistryReference",
-    "choiceMasking",
-    "colorContrast",
-    "coordinatePlane",
-    "customColors",
-    "elementReference",
-    "graph",
-    "graphingCalculator",
-    "graphingTool",
-    "highContrast",
-    "highContrastDisplay",
-    "highlighter",
-    "highlighting",
-    "invertColors",
-    "lineReader",
-    "measurement",
-    "periodicTable",
-    "protractor",
-    "readAloud",
-    "readingGuide",
-    "readingMask",
-    "readingRuler",
-    "ruler",
-    "scientificCalculator",
-    "speechOutput",
-    "strikethrough",
-    "textHighlight",
-    "textToSpeech",
-    "theme",
-    "trackingGuide",
-    "tts",
-]);
-/**
- * Build a profile granting {@link UNIVERSAL_SUPPORTS_PRESET}.
- *
- * A fresh array per call: a profile flows into policy inputs that hosts mutate,
- * and handing out a shared reference would let one host's edit reach another's.
- */
-export function createUniversalPersonalNeedsProfile() {
-    return {
-        supports: [...UNIVERSAL_SUPPORTS_PRESET],
-        prohibitedSupports: [],
-        activateAtInit: [],
-    };
-}
+export { UNIVERSAL_SUPPORTS_PRESET, createUniversalPersonalNeedsProfile, } from "./packaged-capability-composition.js";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/pie-default-tool-loaders",
-	"version": "0.3.65",
+	"version": "0.3.66",
 	"type": "module",
 	"description": "Composition layer for the packaged PIE assessment tools: registrations, tag map, placement presets, universal supports and lazy module loaders",
 	"repository": {
@@ -25,25 +25,26 @@
 		"README.md"
 	],
 	"scripts": {
-		"build": "tsc -p tsconfig.json",
+		"build": "bun run check:composition && tsc -p tsconfig.json",
+		"check:composition": "bun test tests/packaged-capability-composition.test.ts",
 		"dev": "tsc -p tsconfig.json --watch",
 		"typecheck": "tsc -p tsconfig.json --noEmit",
 		"lint": "biome check .",
 		"test": "bun test"
 	},
 	"dependencies": {
-		"@pie-players/pie-assessment-toolkit": "0.3.65",
-		"@pie-players/pie-players-shared": "0.3.65",
-		"@pie-players/pie-tool-annotation-toolbar": "0.3.65",
-		"@pie-players/pie-tool-answer-eliminator": "0.3.65",
-		"@pie-players/pie-tool-calculator-desmos": "0.3.65",
-		"@pie-players/pie-tool-graph": "0.3.65",
-		"@pie-players/pie-tool-line-reader": "0.3.65",
-		"@pie-players/pie-tool-periodic-table": "0.3.65",
-		"@pie-players/pie-tool-protractor": "0.3.65",
-		"@pie-players/pie-tool-ruler": "0.3.65",
-		"@pie-players/pie-tool-theme": "0.3.65",
-		"@pie-players/pie-tool-tts-inline": "0.3.65"
+		"@pie-players/pie-assessment-toolkit": "0.3.66",
+		"@pie-players/pie-players-shared": "0.3.66",
+		"@pie-players/pie-tool-annotation-toolbar": "0.3.66",
+		"@pie-players/pie-tool-answer-eliminator": "0.3.66",
+		"@pie-players/pie-tool-calculator-desmos": "0.3.66",
+		"@pie-players/pie-tool-graph": "0.3.66",
+		"@pie-players/pie-tool-line-reader": "0.3.66",
+		"@pie-players/pie-tool-periodic-table": "0.3.66",
+		"@pie-players/pie-tool-protractor": "0.3.66",
+		"@pie-players/pie-tool-ruler": "0.3.66",
+		"@pie-players/pie-tool-theme": "0.3.66",
+		"@pie-players/pie-tool-tts-inline": "0.3.66"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.5.7",