@pie-players/pie-default-tool-loaders 0.3.75 → 1.0.0-beta.1

package/README.md

@@ -1,16 +1,15 @@
 # PIE Default Tool Loaders
 
-Composition layer for the packaged PIE assessment tools: which capabilities exist
-in a deployment, and how a program tiers them.
+The packaged PIE assessment tools: which capabilities exist in a deployment, how
+they load, and which of them a program grants to everyone. This README is for
+host integrators choosing a tool set and a calculator, and for contributors
+adding a packaged capability.
 
-It owns the concrete `pie-tool-*` dependencies and the calculator engines
-(`pie-calculator-cortex`, `-desmos` and `-geogebra`) so toolkit core can stay
-dependency-light and cycle-safe, and it is the layer above core — core knows
-`featureId`, placement levels, activation kinds and precedence rules, and knows
-no capability ids.
-
-It owns five things, all answers to "which capabilities does this deployment have
-and how does the program tier them":
+The package owns the concrete `pie-tool-*` dependencies and the calculator
+engines (`pie-calculator-cortex`, `-desmos` and `-geogebra`), so toolkit core
+stays dependency-light and cycle-safe. Core knows the concepts — support ids,
+placement levels, activation kinds and precedence rules — and no concrete
+capability id. A support id is the tool id a profile grants.
 
 | Export | What it decides |
 | --- | --- |
@@ -18,49 +17,56 @@ and how does the program tier them":
 | `PACKAGED_TOOL_TAG_MAP` | Which custom element each one renders as |
 | `SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT` | Where they appear and in what order |
 | `createUniversalPersonalNeedsProfile`, `createEmptyPersonalNeedsProfile` | Which of them the program grants to everyone, or to no one |
+| `createPersonalNeedsProfileFromAfa` | Which of them a student's AfA PNP 3.0 record grants, prohibits and turns on at start, and with which settings |
 | `DEFAULT_TOOL_MODULE_LOADERS` | When each one's bundle loads |
+| `CONTENT_ALTERNATE_REGISTRATIONS` | Which of them carry an authored alternate that renders as a region; the print player mounts these |
 
-The individual registrations are exported too, so a host can compose its own set
-rather than take the packaged one whole.
-
-These exports are projections of one internal **Packaged Capability
-Composition**. Each packaged capability is authored once with its registration,
-element delivery, module loader, preferred placement and explicit
-universal-support policy. The package build rejects contradictory PIE-owned data
-— for example, a region capability with a toolbar tag, or a content-dependent
-capability marked universal — so release tests find a missing facet
-instead of a learner finding a dead affordance. The browser does not repeat that
-strict gate at import time: a PIE authoring defect must block publication, not an
-otherwise usable assessment.
-
-That invariant boundary does not make host input stricter: lazy module loading
-is opt-in, registration/tag/factory overrides take precedence, an empty
-`toolIds` array selects the full packaged set, and unknown selected ids are
-ignored while known ids register.
+The individual registrations are exported too, so a host can compose its own
+set ([Custom sets](#custom-sets)).
 
 ## Usage
 
 ```ts
-import {
-	createPackagedToolRegistry,
-	DEFAULT_TOOL_MODULE_LOADERS,
-} from "@pie-players/pie-default-tool-loaders";
+import { createPackagedToolRegistry } from "@pie-players/pie-default-tool-loaders";
 
 // The packaged capability set, lazily loaded.
-const registry = createPackagedToolRegistry({
-	toolModuleLoaders: DEFAULT_TOOL_MODULE_LOADERS,
-});
+const registry = createPackagedToolRegistry();
+
+// The same registrations for a host that defines the tool elements itself.
+const preloaded = createPackagedToolRegistry({ toolModuleLoaders: {} });
 ```
 
 One loader set serves every host shape. `DEFAULT_TOOL_MODULE_LOADERS` holds a
-loader per packaged capability, and a registry loads a module only when a tool
-first renders, so an item player, a section player and an assessment player
-pass the same set and load only the tools they place.
-
-The calculator is one element, `<pie-tool-calculator>`, for every provider.
-Desmos is the provider when none is configured; the toolkit picks another from
-`tools.providers.calculator` when the element mounts, and an open calculator
-remounts on the new provider when a tool-config update replaces it.
+loader per packaged capability and is what `createPackagedToolRegistry`
+installs unless `toolModuleLoaders` replaces it. A registry loads a module only
+when a tool first renders, so an item player, a section player and an
+assessment player share the set and load only the tools they place.
+
+`createPackagedToolRegistry` is lenient with host input. Registration, tag-map
+and component-factory overrides take precedence over the packaged data. An
+empty `toolIds` array selects the full packaged set, and unknown ids in it are
+ignored while the known ones register.
+
+## Calculator providers
+
+The calculator is one element, `<pie-tool-calculator>`, for every provider. The
+toolkit picks the provider from `tools.providers.calculator` when the element
+mounts, and an open calculator remounts on the new provider when a tool-config
+update replaces it.
+
+Desmos is the provider when none is configured, and it needs an API key: pass
+it through `provider.runtime.authFetcher`, a `provider.init.proxyEndpoint` that
+returns it, or `provider.init.apiKey` in development
+([Calculator with host auth](../../docs/tools-and-accomodations/tool_provider_system.md#calculator-with-host-auth)).
+Without one the calculator fails to load. For a keyless, offline-capable
+calculator with no runtime CDN, use `provider.id: "calculator-cortex"`. Its
+`settings` take the `CortexCalculatorSettings` type that
+`@pie-players/pie-calculator-cortex` exports: `angleMode`,
+`calculationPrecision`, `displayPrecision`, `historyLimit`,
+`evaluationTimeLimitMs`, `allowedFunctions`, `allowClipboard`, `messages`,
+`direction` and `graph`. Clipboard blocking follows `restrictedMode`;
+`allowClipboard` alone blocks nothing. The [Cortex README](../calculator-cortex/README.md)
+covers localization, message overrides and the keypad.
 
 ```ts
 const tools = {
@@ -76,10 +82,7 @@ const tools = {
 };
 ```
 
-For an offline-capable calculator with no API key or runtime CDN, use
-`provider.id: "calculator-cortex"`. Its `settings` accept angle mode, precision,
-history, evaluation limit, allowed functions, clipboard policy, and graph
-viewport options documented by `@pie-players/pie-calculator-cortex`.
+## Custom sets
 
 A host composing its own set starts from the toolkit's empty `ToolRegistry`,
 registers into it, and installs the tag map its registrations create elements
@@ -105,19 +108,21 @@ A later `setToolModuleLoaders` call adds or replaces entries. A replacement
 registered after a tool's module has loaded is ignored with a warning, since the
 elements it defines are already in place.
 
-## Content-dependent capabilities require an explicit packaging decision
+## Content-dependent capabilities
 
-A content-dependent capability is never granted by
-`createUniversalPersonalNeedsProfile()`. It may ship in `PACKAGED_TOOL_REGISTRATIONS` only
-when it has a useful presentation path without a grant and declares
-`resolvesWithoutGrant`. Audio transcript is the shipped example: an authored
-`visibility: "always"` transcript reaches every player, while its accommodation
-path remains policy-gated and `transcript` stays out of the universal profile.
+A content-dependent capability declares `requiresAuthoredContent`: it renders
+only where the content carries what it needs, and
+`createUniversalPersonalNeedsProfile()` never grants one. It ships in
+`PACKAGED_TOOL_REGISTRATIONS` only when it has a useful presentation path
+without a grant and declares `resolvesWithoutGrant`. Audio transcript is the
+shipped example: an authored `visibility: "always"` transcript reaches every
+player, while its accommodation path stays policy-gated and `transcript` stays
+out of the universal profile.
 
-A content-dependent capability with no presentation path remains an explicit
-deployment choice. Signing is the shipped example: install
-`@pie-players/pie-tool-sign-language` and register it, which is the same two
-lines a host writes for a capability of its own.
+A content-dependent capability with no such path is an explicit deployment
+choice. Signing is the shipped example: install
+`@pie-players/pie-tool-sign-language` and register it, the same two lines a
+host writes for a capability of its own.
 
 ```ts
 import { signLanguageRegistration } from "@pie-players/pie-tool-sign-language";
@@ -129,25 +134,59 @@ registry.register(signLanguageRegistration);
 
 `createUniversalPersonalNeedsProfile()` builds a fresh `PersonalNeedsProfile`
 granting the tool ids of the capabilities the packaged set treats as universal
-features. A support id is the tool id it grants.
+features. Tool policy reads the profile from the assessment entity, so set it
+there: on the player's `assessment` property, or through
+`coordinator.updateAssessment(...)` on a coordinator you pass. A
+`section.personalNeedsProfile` is ignored with a console warning.
 
 ```ts
 import { createUniversalPersonalNeedsProfile } from "@pie-players/pie-default-tool-loaders";
 
-const section = {
-	...authoredSection,
+sectionPlayer.assessment = {
+	...authoredAssessment,
 	personalNeedsProfile: createUniversalPersonalNeedsProfile(),
 };
 ```
 
 The toolkit ships no populated default, and `createEmptyPersonalNeedsProfile()`
-builds a profile granting nothing. Which capabilities a
-deployment grants by default is a property of the program, not of a capability:
-TTS is a universal feature in one program and a documented accommodation in
-another. So the universal profile is data to adopt, extend or replace alongside the district
-and test-administration configuration, and it deliberately excludes any
-capability that declares a content dependency.
-
-A section carrying no profile is left alone. `pnpEnforcement` auto-detection
-engages on real host policy material, so supplying no profile means placement
-alone decides which tools appear.
+builds a profile granting nothing. Which capabilities a deployment grants by
+default is a property of the program: TTS is a universal feature in one program
+and a documented accommodation in another. The universal profile is data to
+adopt, extend or replace alongside the district and test-administration
+configuration, and it excludes every capability that declares a content
+dependency.
+
+An assessment carrying no profile is left alone. `pnpEnforcement`
+auto-detection engages only on host policy material, so with no profile,
+placement alone decides which tools appear.
+
+## AfA profiles
+
+`createPersonalNeedsProfileFromAfa(record)` builds a fresh profile from a
+student's AfA PNP 3.0 record, held as JSON keyed by the spec's terms. Features
+become support ids in the packaged set's names, the activation sets fill
+`activateAtInit` and `prohibitedSupports`, and the settings the packaged tools
+read become `toolParameters`: read-aloud speed, pitch and volume, the calculator
+type and the sign language. The toolkit's PNP configuration guide gives each AfA
+feature's disposition.
+
+```ts
+import { createPersonalNeedsProfileFromAfa } from "@pie-players/pie-default-tool-loaders";
+
+sectionPlayer.assessment = {
+	...authoredAssessment,
+	personalNeedsProfile: createPersonalNeedsProfileFromAfa(afaRecord),
+};
+```
+
+## Packaged capability composition
+
+The exports are projections of one internal composition. Each packaged
+capability is authored once with its registration, element delivery, module
+loader, preferred placement and explicit universal-support flag.
+
+The package build rejects contradictory PIE-owned data, such as a region
+capability with a toolbar tag or a content-dependent capability marked
+universal, so release tests catch a missing facet before it ships. The browser
+skips that strict check at import time: a PIE authoring defect blocks
+publication and never an otherwise usable assessment.

package/dist/afa-profile.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The AfA PNP 3.0 adapter: an AfA record, as JSON keyed by the spec's
+ * kebab-case terms, becomes the toolkit's personal-needs profile.
+ *
+ * Each feature the record names is a support id, the term camelCased, except
+ * where a packaged tool carries the capability under an id of its own
+ * (`TOOL_REGISTRY.md`, Support ids). `spoken` resolves by its `reading-type`:
+ * `computer-read-aloud` is `textToSpeech`, and `screen-reader`, AfA's default,
+ * is `screenReader` (ADR 0004). `extensions` and the resource-matching
+ * preferences name no support and are skipped.
+ *
+ * A feature at the record's root or in `activate-as-option-set` is granted, one
+ * in `activate-at-initialization-set` is granted and on at start, and one in
+ * `prohibit-set` is prohibited, which withdraws it from both. The settings of
+ * a feature a packaged tool reads become that tool's `toolParameters`.
+ */
+import type { PersonalNeedsProfile } from "@pie-players/pie-players-shared/types";
+/** `spoken`'s settings, in AfA's units. */
+export interface AfaSpoken {
+    "reading-type"?: "screen-reader" | "computer-read-aloud";
+    /** Words per minute; AfA's default is 180. */
+    "speech-rate"?: number;
+    /** 0–1; AfA's default is 0.5. */
+    pitch?: number;
+    /** 0–1; AfA's default is 0.5. */
+    volume?: number;
+    [setting: string]: unknown;
+}
+/** A set's features: empty elements keyed by feature, or the feature names. */
+export type AfaFeatureSet = Readonly<Record<string, unknown>> | readonly string[];
+/** An AfA PNP 3.0 record in JSON. A feature is present unless absent, `null` or `false`. */
+export interface AfaPnpRecord {
+    spoken?: AfaSpoken;
+    "calculator-on-screen"?: {
+        "calculator-type"?: string;
+        [setting: string]: unknown;
+    };
+    "sign-language"?: {
+        language?: string;
+        [setting: string]: unknown;
+    };
+    "activate-at-initialization-set"?: AfaFeatureSet;
+    "activate-as-option-set"?: AfaFeatureSet;
+    "prohibit-set"?: AfaFeatureSet;
+    [feature: string]: unknown;
+}
+/** A fresh profile carrying `record`'s grants, prohibitions and settings, ids sorted. */
+export declare function createPersonalNeedsProfileFromAfa(record: AfaPnpRecord): PersonalNeedsProfile;

package/dist/afa-profile.js

@@ -0,0 +1,117 @@
+/**
+ * The AfA PNP 3.0 adapter: an AfA record, as JSON keyed by the spec's
+ * kebab-case terms, becomes the toolkit's personal-needs profile.
+ *
+ * Each feature the record names is a support id, the term camelCased, except
+ * where a packaged tool carries the capability under an id of its own
+ * (`TOOL_REGISTRY.md`, Support ids). `spoken` resolves by its `reading-type`:
+ * `computer-read-aloud` is `textToSpeech`, and `screen-reader`, AfA's default,
+ * is `screenReader` (ADR 0004). `extensions` and the resource-matching
+ * preferences name no support and are skipped.
+ *
+ * A feature at the record's root or in `activate-as-option-set` is granted, one
+ * in `activate-at-initialization-set` is granted and on at start, and one in
+ * `prohibit-set` is prohibited, which withdraws it from both. The settings of
+ * a feature a packaged tool reads become that tool's `toolParameters`.
+ */
+const RENAMED_FEATURES = {
+    "calculator-on-screen": "calculator",
+    "answer-masking": "answerEliminator",
+    "dictionary-on-screen": "dictionary",
+};
+/**
+ * Keys that name no support: the sets, `extensions`, and the preferences that
+ * select among adapted resources by metadata PIE content does not carry. The
+ * interface language is the host's `locale`.
+ */
+const NON_SUPPORT_KEYS = new Set([
+    "activate-at-initialization-set",
+    "activate-as-option-set",
+    "prohibit-set",
+    "extensions",
+    "access-mode-required",
+    "adaptation-type-required",
+    "at-interoperable",
+    "educational-complexity-of-adaptation",
+    "hazard-avoidance",
+    "input-requirements",
+    "language-of-adaptation",
+    "language-of-interface",
+    "adaptation-detail-required",
+    "adaptation-media-required",
+    "educational-level-of-adaptation",
+]);
+/** AfA's `standard` calculator has no PIE type, so it keeps the tool's default. */
+const CALCULATOR_TYPES = new Set(["basic", "scientific", "graphing"]);
+/** AfA's default `speech-rate`, which PIE's normal speed 1 stands for. */
+const AFA_NORMAL_SPEECH_RATE = 180;
+const isPresent = (value) => value !== undefined && value !== null && value !== false;
+const finiteNumber = (value) => typeof value === "number" && Number.isFinite(value) ? value : undefined;
+const camelCase = (term) => term.replace(/-([a-z0-9])/g, (_, next) => next.toUpperCase());
+function featureNames(set) {
+    if (!set)
+        return [];
+    const names = Array.isArray(set)
+        ? set.filter((name) => typeof name === "string")
+        : Object.entries(set)
+            .filter(([, value]) => isPresent(value))
+            .map(([name]) => name);
+    return names.filter((name) => !NON_SUPPORT_KEYS.has(name));
+}
+function spokenParameters(spoken) {
+    const speechRate = finiteNumber(spoken["speech-rate"]);
+    const pitch = finiteNumber(spoken.pitch);
+    const volume = finiteNumber(spoken.volume);
+    return {
+        ...(speechRate !== undefined && speechRate > 0
+            ? { rate: speechRate / AFA_NORMAL_SPEECH_RATE }
+            : {}),
+        ...(pitch !== undefined ? { pitch: pitch * 2 } : {}),
+        ...(volume !== undefined ? { volume } : {}),
+    };
+}
+/** A fresh profile carrying `record`'s grants, prohibitions and settings, ids sorted. */
+export function createPersonalNeedsProfileFromAfa(record) {
+    const spoken = typeof record.spoken === "object" && record.spoken !== null
+        ? record.spoken
+        : {};
+    const readAloud = spoken["reading-type"] === "computer-read-aloud";
+    const supportId = (feature) => feature === "spoken"
+        ? readAloud
+            ? "textToSpeech"
+            : "screenReader"
+        : (RENAMED_FEATURES[feature] ?? camelCase(feature));
+    // PIE cannot withhold a screen reader, so a prohibited `spoken` withholds
+    // the spoken presentation PIE makes, read-aloud.
+    const prohibited = new Set(featureNames(record["prohibit-set"]).map((feature) => feature === "spoken" ? "textToSpeech" : supportId(feature)));
+    const admitted = (ids) => [...new Set(ids)].filter((id) => !prohibited.has(id)).sort();
+    const activateAtInit = admitted(featureNames(record["activate-at-initialization-set"]).map(supportId));
+    const supports = admitted([
+        ...featureNames(record).map(supportId),
+        ...featureNames(record["activate-as-option-set"]).map(supportId),
+        ...activateAtInit,
+    ]);
+    const toolParameters = {};
+    if (readAloud) {
+        const speech = spokenParameters(spoken);
+        if (Object.keys(speech).length > 0) {
+            toolParameters.textToSpeech = speech;
+        }
+    }
+    const calculatorType = record["calculator-on-screen"]?.["calculator-type"];
+    if (calculatorType && CALCULATOR_TYPES.has(calculatorType)) {
+        toolParameters.calculator = {
+            type: calculatorType,
+        };
+    }
+    const signLang = record["sign-language"]?.language;
+    if (typeof signLang === "string" && signLang.length > 0) {
+        toolParameters.signLanguage = { signLang };
+    }
+    return {
+        supports,
+        prohibitedSupports: [...prohibited].sort(),
+        ...(activateAtInit.length > 0 ? { activateAtInit } : {}),
+        ...(Object.keys(toolParameters).length > 0 ? { toolParameters } : {}),
+    };
+}

package/dist/calculator-providers/CortexToolProvider.d.ts

@@ -1,12 +1,10 @@
 /** Fully bundled open-source calculator adapter for the tool-provider registry. */
 import type { CalculatorToolProviderInitConfig, LazyCalculatorProviderDefinition } from "./LazyCalculatorToolProvider.js";
 import { LazyCalculatorToolProvider } from "./LazyCalculatorToolProvider.js";
-import type { ToolProviderCapabilities } from "@pie-players/pie-assessment-toolkit/tools/registration";
 export type CortexToolProviderConfig = CalculatorToolProviderInitConfig;
 export declare class CortexToolProvider extends LazyCalculatorToolProvider<CortexToolProviderConfig> {
     readonly providerName = "PIE Open-Source Calculator";
     readonly version = "1";
     readonly requiresAuth = false;
     protected getDefinition(): LazyCalculatorProviderDefinition<CortexToolProviderConfig>;
-    getCapabilities(): ToolProviderCapabilities;
 }

package/dist/calculator-providers/CortexToolProvider.js

@@ -15,17 +15,4 @@ export class CortexToolProvider extends LazyCalculatorToolProvider {
             initializationErrorMessage: "Failed to initialize the PIE open-source calculator provider. Confirm that this browser supports module workers and that the bundled worker assets are available.",
         };
     }
-    getCapabilities() {
-        return {
-            supportsOffline: true,
-            requiresAuth: false,
-            maxInstances: null,
-            features: {
-                basic: true,
-                scientific: true,
-                graphing: true,
-                fourFunction: true,
-            },
-        };
-    }
 }

package/dist/calculator-providers/DesmosToolProvider.d.ts

@@ -1,7 +1,6 @@
 /** Desmos calculator adapter for the generic tool-provider registry. */
 import type { CalculatorProviderInit } from "@pie-players/pie-calculator";
 import { LazyCalculatorToolProvider, type LazyCalculatorProviderDefinition } from "./LazyCalculatorToolProvider.js";
-import type { ToolProviderCapabilities } from "@pie-players/pie-assessment-toolkit/tools/registration";
 /** Provider initialization is the provider-neutral calculator contract. */
 export type DesmosToolProviderConfig = CalculatorProviderInit;
 export declare class DesmosToolProvider extends LazyCalculatorToolProvider<DesmosToolProviderConfig> {
@@ -9,5 +8,4 @@ export declare class DesmosToolProvider extends LazyCalculatorToolProvider<Desmo
     readonly version = "1.12";
     readonly requiresAuth = true;
     protected getDefinition(): LazyCalculatorProviderDefinition<DesmosToolProviderConfig>;
-    getCapabilities(): ToolProviderCapabilities;
 }

package/dist/calculator-providers/DesmosToolProvider.js

@@ -15,17 +15,4 @@ export class DesmosToolProvider extends LazyCalculatorToolProvider {
             initializationErrorMessage: "Failed to initialize Desmos calculator provider. Check the application key, preloaded API, runtime endpoint, or network access.",
         };
     }
-    getCapabilities() {
-        return {
-            supportsOffline: false,
-            requiresAuth: true,
-            maxInstances: null,
-            features: {
-                basic: true,
-                scientific: true,
-                graphing: true,
-                fourFunction: true,
-            },
-        };
-    }
 }

package/dist/calculator-providers/GeoGebraToolProvider.d.ts

@@ -1,7 +1,6 @@
 /** GeoGebra calculator adapter for the generic tool-provider registry. */
 import type { CalculatorToolProviderInitConfig, LazyCalculatorProviderDefinition } from "./LazyCalculatorToolProvider.js";
 import { LazyCalculatorToolProvider } from "./LazyCalculatorToolProvider.js";
-import type { ToolProviderCapabilities } from "@pie-players/pie-assessment-toolkit/tools/registration";
 export interface GeoGebraToolProviderConfig extends CalculatorToolProviderInitConfig {
     scriptUrl?: string;
     appletTimeoutMs?: number;
@@ -11,5 +10,4 @@ export declare class GeoGebraToolProvider extends LazyCalculatorToolProvider<Geo
     readonly version = "6";
     readonly requiresAuth = false;
     protected getDefinition(): LazyCalculatorProviderDefinition<GeoGebraToolProviderConfig>;
-    getCapabilities(): ToolProviderCapabilities;
 }

package/dist/calculator-providers/GeoGebraToolProvider.js

@@ -15,17 +15,4 @@ export class GeoGebraToolProvider extends LazyCalculatorToolProvider {
             initializationErrorMessage: "Failed to initialize GeoGebra calculator provider. Confirm that the deployment may load GeoGebra and that its script URL is reachable.",
         };
     }
-    getCapabilities() {
-        return {
-            supportsOffline: false,
-            requiresAuth: false,
-            maxInstances: null,
-            features: {
-                basic: true,
-                scientific: true,
-                graphing: true,
-                fourFunction: false,
-            },
-        };
-    }
 }

package/dist/calculator-providers/LazyCalculatorToolProvider.d.ts

@@ -1,5 +1,5 @@
 import type { CalculatorProvider, CalculatorProviderInit } from "@pie-players/pie-calculator";
-import type { ToolProviderApi, ToolProviderCapabilities } from "@pie-players/pie-assessment-toolkit/tools/registration";
+import type { ToolProviderApi } from "@pie-players/pie-assessment-toolkit/tools/registration";
 export type CalculatorToolProviderInitConfig = Pick<CalculatorProviderInit, "onTelemetry">;
 type InitializableCalculatorProvider<TConfig> = CalculatorProvider & {
     initialize(config: TConfig): Promise<void>;
@@ -12,7 +12,7 @@ export interface LazyCalculatorProviderDefinition<TConfig> {
 }
 /**
  * Shared lazy-module and lifecycle implementation for calculator tool adapters.
- * Concrete adapters own only their metadata, capabilities and provider import.
+ * Concrete adapters own only their metadata and provider import.
  */
 export declare abstract class LazyCalculatorToolProvider<TConfig extends CalculatorToolProviderInitConfig> implements ToolProviderApi<CalculatorProvider> {
     abstract readonly providerName: string;
@@ -20,7 +20,6 @@ export declare abstract class LazyCalculatorToolProvider<TConfig extends Calcula
     abstract readonly version: string;
     abstract readonly requiresAuth: boolean;
     protected abstract getDefinition(): LazyCalculatorProviderDefinition<TConfig>;
-    abstract getCapabilities(): ToolProviderCapabilities;
     private calculatorProvider;
     private initializationPromise;
     private lifecycleGeneration;

package/dist/calculator-providers/LazyCalculatorToolProvider.js

@@ -1,6 +1,6 @@
 /**
  * Shared lazy-module and lifecycle implementation for calculator tool adapters.
- * Concrete adapters own only their metadata, capabilities and provider import.
+ * Concrete adapters own only their metadata and provider import.
  */
 export class LazyCalculatorToolProvider {
     category = "calculator";

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 export type { PackagedToolRegistryOptions } from "./packaged-capability-composition.js";
 export { createEmptyPersonalNeedsProfile, createPackagedToolRegistry, createUniversalPersonalNeedsProfile, DEFAULT_TOOL_MODULE_LOADERS, PACKAGED_TOOL_REGISTRATIONS, PACKAGED_TOOL_TAG_MAP, SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT, } from "./packaged-capability-composition.js";
+export { type AfaFeatureSet, type AfaPnpRecord, type AfaSpoken, createPersonalNeedsProfileFromAfa, } from "./afa-profile.js";
 export { CONTENT_ALTERNATE_REGISTRATIONS } from "./content-alternates.js";
 export { annotationToolbarRegistration, lineReaderToolRegistration, themeToolRegistration, } from "./registrations/accessibility-tools.js";
-export { AUDIO_TRANSCRIPT_FEATURE_ID, AUDIO_TRANSCRIPT_REGION_CLASS, AUDIO_TRANSCRIPT_REGION_LABEL, audioTranscriptRegistration, resolveAudioTranscript, type ResolvedAudioTranscript, } from "./registrations/audio-transcript.js";
+export { AUDIO_TRANSCRIPT_FEATURE_ID, AUDIO_TRANSCRIPT_REGION_CLASS, AUDIO_TRANSCRIPT_REGION_LABEL, audioTranscriptRegistration, CONTENT_LEAD_SURFACE, resolveAudioTranscript, type ResolvedAudioTranscript, } from "./registrations/audio-transcript.js";
 export { calculatorToolRegistration } from "./registrations/calculator.js";
 export { createDictionaryToolRegistration, createPictureDictionaryToolRegistration, dictionaryToolRegistration, type DictionaryVariantOptions, pictureDictionaryToolRegistration, spanishDictionaryToolRegistration, spanishPictureDictionaryToolRegistration, } from "./registrations/dictionary-tools.js";
 export { answerEliminatorToolRegistration } from "./registrations/interaction-tools.js";

package/dist/index.js

@@ -1,11 +1,13 @@
 export { createEmptyPersonalNeedsProfile, createPackagedToolRegistry, createUniversalPersonalNeedsProfile, DEFAULT_TOOL_MODULE_LOADERS, PACKAGED_TOOL_REGISTRATIONS, PACKAGED_TOOL_TAG_MAP, SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT, } from "./packaged-capability-composition.js";
+// A profile from an AfA PNP 3.0 record, in the packaged set's support ids.
+export { createPersonalNeedsProfileFromAfa, } from "./afa-profile.js";
 // The authored-alternate subset, for a renderer that shows alternates and no
 // toolbar — importable without the packaged composition's tool loaders.
 export { CONTENT_ALTERNATE_REGISTRATIONS } from "./content-alternates.js";
 // Individual registrations, for a host composing a subset rather than the whole
 // packaged set.
 export { annotationToolbarRegistration, lineReaderToolRegistration, themeToolRegistration, } from "./registrations/accessibility-tools.js";
-export { AUDIO_TRANSCRIPT_FEATURE_ID, AUDIO_TRANSCRIPT_REGION_CLASS, AUDIO_TRANSCRIPT_REGION_LABEL, audioTranscriptRegistration, resolveAudioTranscript, } from "./registrations/audio-transcript.js";
+export { AUDIO_TRANSCRIPT_FEATURE_ID, AUDIO_TRANSCRIPT_REGION_CLASS, AUDIO_TRANSCRIPT_REGION_LABEL, audioTranscriptRegistration, CONTENT_LEAD_SURFACE, resolveAudioTranscript, } from "./registrations/audio-transcript.js";
 export { calculatorToolRegistration } from "./registrations/calculator.js";
 export { createDictionaryToolRegistration, createPictureDictionaryToolRegistration, dictionaryToolRegistration, pictureDictionaryToolRegistration, spanishDictionaryToolRegistration, spanishPictureDictionaryToolRegistration, } from "./registrations/dictionary-tools.js";
 export { answerEliminatorToolRegistration } from "./registrations/interaction-tools.js";

package/dist/packaged-capability-composition.d.ts

@@ -16,7 +16,11 @@ export interface PackagedToolRegistryOptions {
     toolTagMap?: Partial<ToolTagMap>;
     /** Override the component factory per tool. */
     toolComponentFactories?: Partial<ToolComponentFactoryMap>;
-    /** Lazy module loaders keyed by toolId. */
+    /**
+     * Module loaders keyed by toolId, each loading its tool's element on first
+     * render. Defaults to `DEFAULT_TOOL_MODULE_LOADERS`; a map replaces it, so a
+     * host that defines its tool elements itself passes `{}`.
+     */
     toolModuleLoaders?: Partial<Record<string, ToolModuleLoader>>;
     /** Restrict registration to specific packaged tool ids. */
     toolIds?: string[];

package/dist/packaged-capability-composition.js

@@ -248,13 +248,9 @@ class PackagedCapabilityComposition {
         for (const registration of this.selectRegistrations(options.toolIds)) {
             registry.register(options.overrides?.[registration.toolId] ?? registration);
         }
-        // Loader installation remains opt-in. Some hosts preload tool elements or
-        // provide their own tags; silently adding package loads here would change
-        // their bundle/runtime behavior.
-        if (options.toolModuleLoaders &&
-            Object.keys(options.toolModuleLoaders).length > 0) {
-            registry.setToolModuleLoaders({ ...options.toolModuleLoaders });
-        }
+        registry.setToolModuleLoaders({
+            ...(options.toolModuleLoaders ?? this.moduleLoaders),
+        });
         registry.setComponentOverrides({
             toolTagMap: {
                 ...this.toolTagMap,

package/dist/registrations/accessibility-tools.js

@@ -23,7 +23,6 @@ export const lineReaderToolRegistration = {
     nameKey: "tools.lineReader.name",
     descriptionKey: "tools.lineReader.description",
     icon: "bars-3",
-    // Line reader appears where there's text to read
     supportedLevels: ["section", "passage", "rubric", "item"],
     /**
      * Pass 2: Line reader is relevant when readable text is present
@@ -56,7 +55,7 @@ export const themeToolRegistration = {
      * Pass 2: Color scheme is always relevant when allowed
      */
     isVisibleInContext(context) {
-        return true; // Always show if allowed by orchestrator
+        return true;
     },
     renderToolbar(context, toolbarContext) {
         return renderOverlayToolbar(this, context, toolbarContext, {
@@ -86,15 +85,12 @@ export const annotationToolbarRegistration = {
     activation: "selection-gateway",
     singletonScope: "section",
     /**
-     * Section-scoped singleton surface. The gateway used to be mounted by
-     * `PieSectionPlayerBaseElement.svelte`, which named this tool id in three
-     * places — the policy check, the module load and the element — so no host
-     * could contribute a second section-scoped capability. Declaring the surface
-     * moves that wiring into this registration, and the renderer discovers it
-     * through `ToolRegistry.getToolsBySurface("section-overlay")`.
+     * Section-scoped singleton surface. The renderer discovers it through
+     * `ToolRegistry.getToolsBySurface("section-overlay")`, so the section player
+     * names no tool id and a host can contribute another section-scoped
+     * capability.
      */
     surfaces: ["section-overlay"],
-    // Annotation appears where there's text content
     supportedLevels: ["passage", "rubric", "item", "element"],
     /**
      * Pass 2: Annotation is relevant when readable text is present

package/dist/registrations/audio-transcript.d.ts

@@ -5,13 +5,13 @@
  * 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.
+ *     designed to be delivered with its transcript on screen — sentence items in
+ *     an early-literacy assessment, 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.
+ *     against the `transcript` support id, and silence means no. For item
+ *     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
@@ -47,6 +47,7 @@ export declare const AUDIO_TRANSCRIPT_REGION_CLASS = "pie-tool-audio-transcript"
 export interface ResolvedAudioTranscript {
     catalogId: string;
     text: string;
+    /** BCP 47, as the region's `lang` takes it, whatever syntax the card used. */
     language?: string;
     /** True when the card declares itself authored presentation. */
     always: boolean;

package/dist/registrations/audio-transcript.js

@@ -5,13 +5,13 @@
  * 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.
+ *     designed to be delivered with its transcript on screen — sentence items in
+ *     an early-literacy assessment, 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.
+ *     against the `transcript` support id, and silence means no. For item
+ *     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
@@ -35,6 +35,7 @@
  * absent from the universal preset — a content-dependent support never belongs in
  * a wholesale grant.
  */
+import { toLanguageTag } from "@pie-players/pie-players-shared/i18n/language-tags";
 /** QTI 3.0 / AfA support id gating an audio transcript. */
 export const AUDIO_TRANSCRIPT_FEATURE_ID = "transcript";
 /** Catalog type carrying the transcript text. */
@@ -55,6 +56,10 @@ const isTranscriptCard = (card) => !!card && card.catalog === AUDIO_TRANSCRIPT_C
 const isAlwaysVisible = (card) => typeof card.visibility === "string" &&
     card.visibility.trim().toLowerCase() === ALWAYS_VISIBLE;
 const cardText = (card) => typeof card.content === "string" ? card.content.trim() : "";
+// The Learnosity transform emits POSIX `es_ES`, which `lang` does not accept.
+const cardLanguage = (card) => typeof card.language === "string"
+    ? toLanguageTag(card.language) || undefined
+    : undefined;
 /**
  * The transcript an entity carries, or `null`.
  *
@@ -83,7 +88,7 @@ export function resolveAudioTranscript(context) {
         const resolved = {
             catalogId,
             text,
-            language: typeof card.language === "string" ? card.language : undefined,
+            language: cardLanguage(card),
             always: isAlwaysVisible(card),
         };
         // An `always` card answers whether or not policy granted anything, so it

package/dist/registrations/calculator.js

@@ -54,7 +54,10 @@ function normalizeCalculatorType(value) {
 }
 function getCalculatorRenderParams(toolbarContext) {
     const params = toolbarContext.getToolRenderParams?.("calculator") ?? {};
-    const calculatorType = normalizeCalculatorType(params.calculatorType);
+    // A host resolver or a request names the type; the policy parameters'
+    // `type` is the default beneath both.
+    const calculatorType = normalizeCalculatorType(params.calculatorType) ??
+        normalizeCalculatorType(toolbarContext.getToolParameters?.("calculator")?.type);
     const availableTypesRaw = params.availableTypes;
     const availableTypes = Array.isArray(availableTypesRaw)
         ? availableTypesRaw
@@ -135,7 +138,6 @@ export const calculatorToolRegistration = {
      * (MathML, LaTeX, arithmetic markers).
      */
     isVisibleInContext(context) {
-        // Show only when math is present in item content.
         return hasMathContent(context);
     },
     renderToolbar(context, toolbarContext) {
@@ -156,8 +158,7 @@ export const calculatorToolRegistration = {
             icon: typeof this.icon === "function" ? this.icon(context) : this.icon,
             // Routes this button through <nds-icon-button> where the host enables NDS
             // icons. Declared here because which capabilities render in the host's
-            // design system is a composition decision; the toolbar used to map it from
-            // the `calculator` toolId, which put a capability name in the generic core.
+            // design system is a composition decision.
             faIconName: "calculator",
             disabled: false,
             // The name stays put across open and closed. The toolbar mirrors
@@ -248,10 +249,9 @@ export const calculatorToolRegistration = {
                 const active = toolbarContext.isToolVisible(this.toolId);
                 button.active = active;
                 button.label = displayName;
-                // Static across the toggle. The previous `Close ${name.toLowerCase()}`
-                // was a hardcoded English template built by lowercasing a localized
-                // noun — "Close rekenmachine" under nl-NL — and it is the state
-                // `aria-pressed` already carries.
+                // Static across the toggle: `aria-pressed` carries the state, and a
+                // "Close …" template built from a localized noun mixes languages
+                // ("Close rekenmachine" under nl-NL).
                 button.ariaLabel = displayName;
                 button.tooltip = displayName;
                 if (lastVisibleState !== active) {

package/dist/registrations/interaction-tools.d.ts

@@ -9,6 +9,6 @@ import type { ToolRegistration } from "@pie-players/pie-assessment-toolkit/tools
  * Answer Eliminator tool registration
  *
  * Allows students to strike through incorrect answer choices.
- * Only appears on multiple-choice style questions.
+ * Only appears on items with an element that supports answer masking.
  */
 export declare const answerEliminatorToolRegistration: ToolRegistration;

package/dist/registrations/interaction-tools.js

@@ -4,12 +4,40 @@
  * Registers tools for interacting with question content:
  * - Answer Eliminator (strike through answer choices)
  */
-import { hasChoiceInteraction } from "@pie-players/pie-assessment-toolkit/tools/registration";
+import { elementSupports } from "@pie-players/pie-assessment-toolkit/tools/registration";
 import { createToolElement, } from "@pie-players/pie-assessment-toolkit/tools/registration";
 import { createScopedVisibilityBinding, syncButtonAndOverlayVisibility, } from "@pie-players/pie-assessment-toolkit/tools/registration";
 import { resolveOverlayElement } from "./overlay-element-cache.js";
-/** `tools.providers.answerEliminator.strategy`, defaulting to strikethrough. */
+/** The policy parameters' `strategy`, defaulting to strikethrough. */
 const normalizeEliminationStrategy = (value) => value === "mask" ? "mask" : "strikethrough";
+/** The AfA PNP 3.0 support term an element declares to take the eliminator. */
+const ANSWER_MASKING = "answer-masking";
+/**
+ * pie-item contract compatibility: legacy pie-elements, and pie-elements-ng
+ * releases from before elements declared their supports, render the markup the
+ * eliminator's built-in adapters read for these two. An element that declares
+ * its supports is decided by its declaration, these two included.
+ */
+const UNDECLARED_ANSWER_MASKING_ELEMENTS = new Set(["multiple-choice", "ebsr"]);
+// Content names one element several ways: `multiple-choice`,
+// `pie-multiple-choice`, `pie-element-multiple-choice`, a runtime `--version-*`
+// tag, or any tag the item's `elements` map binds to `@pie-element/multiple-choice`.
+function isUndeclaredAnswerMaskingElement(tag, packageSpec) {
+    const name = tag
+        .toLowerCase()
+        .replace(/--version-[0-9a-z-]+$/, "")
+        .replace(/^pie-(element-)?/, "");
+    if (UNDECLARED_ANSWER_MASKING_ELEMENTS.has(name))
+        return true;
+    const packageName = packageSpec?.match(/^@pie-element\/([^@]+)/)?.[1];
+    return !!packageName && UNDECLARED_ANSWER_MASKING_ELEMENTS.has(packageName);
+}
+/** Whether an element of the context supports answer masking. */
+function supportsAnswerMasking(context) {
+    return elementSupports(context).some(({ supports, tag, packageSpec }) => supports
+        ? supports.includes(ANSWER_MASKING)
+        : isUndeclaredAnswerMaskingElement(tag, packageSpec));
+}
 /** The state-store key of each PIE element in the item, by model id. */
 function resolveElementStateKeys(context, toolbarContext) {
     const keys = {};
@@ -29,7 +57,7 @@ function resolveElementStateKeys(context, toolbarContext) {
  * Answer Eliminator tool registration
  *
  * Allows students to strike through incorrect answer choices.
- * Only appears on multiple-choice style questions.
+ * Only appears on items with an element that supports answer masking.
  */
 export const answerEliminatorToolRegistration = {
     toolId: "answerEliminator",
@@ -38,32 +66,31 @@ export const answerEliminatorToolRegistration = {
     nameKey: "tools.answerEliminator.name",
     descriptionKey: "tools.answerEliminator.description",
     icon: "strikethrough",
-    // Answer eliminator appears at item level only
     supportedLevels: ["item"],
     /**
-     * Pass 2: Answer eliminator is relevant only for choice-based questions
+     * Pass 2: relevant where an element supports answer masking. An element
+     * declares it on its class, and the answer eliminator's README says what the
+     * element then supplies.
      */
     isVisibleInContext(context) {
-        return hasChoiceInteraction(context);
+        return supportsAnswerMasking(context);
     },
     /**
      * Pass 3: the same question, asked as a capability. Elimination controls are
-     * rendered per choice, so an item with no choice interaction gives this tool
-     * nothing to act on — `placement-ordering`, `categorize` and
-     * `drag-in-the-blank` included, whose `choices` hold draggables the
-     * eliminator cannot reach. Answering the relevance gate alone left the button
-     * on those items for any learner whose profile grants answer masking.
+     * rendered per choice, so an item none of whose elements supports answer
+     * masking gives this tool nothing to act on. Answering the relevance gate
+     * alone left the button on such items for any learner whose profile grants
+     * answer masking.
      */
     isApplicableToContent(context) {
-        return hasChoiceInteraction(context);
+        return supportsAnswerMasking(context);
     },
     renderToolbar(context, toolbarContext) {
         const visibility = createScopedVisibilityBinding(this.toolId, toolbarContext);
         const componentOverrides = toolbarContext.componentOverrides ?? {};
         const overlay = resolveOverlayElement(toolbarContext, visibility.fullToolId, () => createToolElement(this.toolId, context, toolbarContext, componentOverrides));
-        overlay.setAttribute("tool-id", visibility.fullToolId);
         overlay.setAttribute("button-alignment", "inline");
-        overlay.setAttribute("strategy", normalizeEliminationStrategy(toolbarContext.toolkitCoordinator?.getToolConfig(this.toolId)?.strategy));
+        overlay.setAttribute("strategy", normalizeEliminationStrategy(toolbarContext.getToolParameters?.("answerEliminator")?.strategy));
         const button = {
             toolId: this.toolId,
             label: this.name,
@@ -84,7 +111,6 @@ export const answerEliminatorToolRegistration = {
                     overlay,
                     isActive: visibility.isActive,
                 });
-                overlay.scopeElement = toolbarContext.getScopeElement?.() || null;
                 overlay.elementStateKeys = resolveElementStateKeys(context, toolbarContext);
             },
             subscribeActive: visibility.subscribeActive,

package/dist/registrations/overlay-toolbar-render.d.ts

@@ -2,18 +2,15 @@
  * The `renderToolbar` shape shared by every packaged capability that puts one
  * overlay behind one toolbar button.
  *
- * Seven registrations had this inline. What actually varies between them is the
- * two options below and nothing else: whether the overlay paints its own chrome
- * or takes a draggable window, and that window's size. Everything else — the visibility
- * binding, the button, the component-override lookup, the `tool-id` attribute, the
- * sync — was identical, which is why one rule landing in three spellings was
- * possible: the shell title was `resolveToolRegistrationName` in two files,
- * `displayName` in a third and a raw `t(key)` in a fourth.
+ * What varies between capabilities is the two options below: whether the overlay
+ * paints its own chrome or takes a draggable window, and that window's size. The
+ * visibility binding, the button, the component-override lookup, the `tool-id`
+ * attribute and the sync are shared, so the shell title has one spelling.
  *
- * Catalog keys are derived from `toolId`, which held at all seven sites:
- * `tools.<toolId>.buttonA11y` and `tools.<toolId>.tooltip`. A capability needing a
- * different prefix — the dictionary variants, which compose several capabilities
- * off one element — keeps its own renderer.
+ * Catalog keys are derived from `toolId`: `tools.<toolId>.buttonA11y` and
+ * `tools.<toolId>.tooltip`. A capability needing a different prefix — the
+ * dictionary variants, which compose several capabilities off one element —
+ * keeps its own renderer.
  */
 import { type ToolContext, type ToolRegistration, type ToolToolbarRenderResult, type ToolbarContext } from "@pie-players/pie-assessment-toolkit/tools/registration";
 /** A window's geometry. Absent for overlays that paint their own chrome. */

package/dist/registrations/overlay-toolbar-render.js

@@ -2,18 +2,15 @@
  * The `renderToolbar` shape shared by every packaged capability that puts one
  * overlay behind one toolbar button.
  *
- * Seven registrations had this inline. What actually varies between them is the
- * two options below and nothing else: whether the overlay paints its own chrome
- * or takes a draggable window, and that window's size. Everything else — the visibility
- * binding, the button, the component-override lookup, the `tool-id` attribute, the
- * sync — was identical, which is why one rule landing in three spellings was
- * possible: the shell title was `resolveToolRegistrationName` in two files,
- * `displayName` in a third and a raw `t(key)` in a fourth.
+ * What varies between capabilities is the two options below: whether the overlay
+ * paints its own chrome or takes a draggable window, and that window's size. The
+ * visibility binding, the button, the component-override lookup, the `tool-id`
+ * attribute and the sync are shared, so the shell title has one spelling.
  *
- * Catalog keys are derived from `toolId`, which held at all seven sites:
- * `tools.<toolId>.buttonA11y` and `tools.<toolId>.tooltip`. A capability needing a
- * different prefix — the dictionary variants, which compose several capabilities
- * off one element — keeps its own renderer.
+ * Catalog keys are derived from `toolId`: `tools.<toolId>.buttonA11y` and
+ * `tools.<toolId>.tooltip`. A capability needing a different prefix — the
+ * dictionary variants, which compose several capabilities off one element —
+ * keeps its own renderer.
  */
 import { applyOverlaySurface, createScopedVisibilityBinding, createToolElement, resolveToolRegistrationName, syncButtonAndOverlayVisibility, } from "@pie-players/pie-assessment-toolkit/tools/registration";
 import { resolveOverlayElement } from "./overlay-element-cache.js";

package/dist/registrations/tts.d.ts

@@ -4,13 +4,12 @@
  * Registers the TTS tool for reading content aloud.
  */
 import type { ToolRegistration } from "@pie-players/pie-assessment-toolkit/tools/registration";
-export declare const TOOL_ACTIVE_CHANGE_EVENT = "pie-tool-active-change";
 /**
  * Text-to-Speech tool registration
  *
  * Supports:
  * - Reading content aloud using browser TTS or external providers
  * - Context-aware visibility (shows when readable text is available)
- * - All levels except assessment and element
+ * - Item and passage levels
  */
 export declare const ttsToolRegistration: ToolRegistration;

package/dist/registrations/tts.js

@@ -3,22 +3,22 @@
  *
  * Registers the TTS tool for reading content aloud.
  */
-import { hasReadableText } from "@pie-players/pie-assessment-toolkit/tools/registration";
-import { createScopedToolId, createToolElement, } from "@pie-players/pie-assessment-toolkit/tools/registration";
-import { buildRuntimeTTSConfig, normalizeTTSLayoutMode, normalizeTTSSpeedControlOptions, resolveTTSHostToolbarLayout, resolveTTSLayoutMode, resolveTTSRuntimeSettings, } from "@pie-players/pie-assessment-toolkit/tools/registration";
+import { hasSpokenContent } from "@pie-players/pie-assessment-toolkit/tools/registration";
+import { createScopedToolId, createToolElement, TOOL_ACTIVE_CHANGE_EVENT, } from "@pie-players/pie-assessment-toolkit/tools/registration";
+import { buildRuntimeTTSConfig, normalizeTTSSpeedControlOptions, resolveTTSHostToolbarLayout, resolveTTSRuntimeSettings, } from "@pie-players/pie-assessment-toolkit/tools/registration";
 import { TTSToolProvider } from "@pie-players/pie-assessment-toolkit/tools/registration";
 import { resolveOverlayElement } from "./overlay-element-cache.js";
 // This package owns the server adapter's import, so the toolkit never names it
 // and a bundler building the toolkit alone has nothing to resolve.
 const loadServerTTSProvider = async () => (await import("@pie-players/tts-client-server")).ServerTTSProvider;
-export const TOOL_ACTIVE_CHANGE_EVENT = "pie-tool-active-change";
+const numberOrUndefined = (value) => typeof value === "number" ? value : undefined;
 /**
  * Text-to-Speech tool registration
  *
  * Supports:
  * - Reading content aloud using browser TTS or external providers
  * - Context-aware visibility (shows when readable text is available)
- * - All levels except assessment and element
+ * - Item and passage levels
  */
 export const ttsToolRegistration = {
     toolId: "textToSpeech",
@@ -46,9 +46,6 @@ export const ttsToolRegistration = {
         const normalizedConfig = {
             ...config,
         };
-        if ("layoutMode" in normalizedConfig) {
-            normalizedConfig.layoutMode = normalizeTTSLayoutMode(normalizedConfig.layoutMode);
-        }
         if ("speedOptions" in normalizedConfig) {
             normalizedConfig.speedOptions = normalizeTTSSpeedControlOptions(normalizedConfig.speedOptions);
         }
@@ -59,11 +56,10 @@ export const ttsToolRegistration = {
     /**
      * Pass 2: Determine if TTS is relevant in this context
      *
-     * TTS is relevant when:
-     * - Context contains readable text (at least 10 characters)
+     * TTS is relevant when the context holds readable text or a catalog idref.
      */
     isVisibleInContext(context) {
-        return hasReadableText(context);
+        return hasSpokenContent(context);
     },
     renderToolbar(context, toolbarContext) {
         const resolveRuntimeSettings = () => resolveTTSRuntimeSettings(toolbarContext.toolkitCoordinator?.getToolConfig(this.toolId) ||
@@ -72,19 +68,7 @@ export const ttsToolRegistration = {
             const runtimeSettings = resolveRuntimeSettings();
             return normalizeTTSSpeedControlOptions(runtimeSettings.speedOptions);
         };
-        const resolveLayoutMode = () => resolveTTSLayoutMode(resolveRuntimeSettings());
-        const resolveHostLayout = () => resolveTTSHostToolbarLayout(resolveRuntimeSettings());
         const fullToolId = createScopedToolId(this.toolId, toolbarContext.scope.level, toolbarContext.scope.scopeId);
-        // Only a language the toolbar or its host named: unnamed, the control resolves
-        // markup `lang`, and the browser voice follows the browser's language.
-        const applyContentLanguage = (element) => {
-            if (toolbarContext.language) {
-                element.setAttribute("language", toolbarContext.language);
-            }
-            else {
-                element.removeAttribute("language");
-            }
-        };
         const resolveControlSize = () => {
             const raw = toolbarContext.ui?.size;
             return raw === "sm" || raw === "lg" ? raw : "md";
@@ -92,22 +76,26 @@ export const ttsToolRegistration = {
         const element = resolveOverlayElement(toolbarContext, fullToolId, () => createToolElement(this.toolId, context, toolbarContext, toolbarContext.componentOverrides));
         const applyAttributes = () => {
             element.setAttribute("catalog-id", toolbarContext.catalogId || toolbarContext.itemId);
-            applyContentLanguage(element);
             element.setAttribute("size", resolveControlSize());
-            element.setAttribute("layout-mode", resolveLayoutMode());
+            element.setAttribute("layout-mode", resolveRuntimeSettings().layoutMode);
             element.speedOptions = resolveElementSpeedOptions();
             element.showSingleSpeedOption =
                 resolveRuntimeSettings().showSingleSpeedOption === true;
+            // The element range-checks these; a non-number means the default.
+            const speech = toolbarContext.getToolParameters?.("textToSpeech");
+            element.baseRate = numberOrUndefined(speech?.rate);
+            element.pitch = numberOrUndefined(speech?.pitch);
+            element.volume = numberOrUndefined(speech?.volume);
         };
         applyAttributes();
-        const hostLayout = resolveHostLayout();
+        const hostLayout = resolveTTSHostToolbarLayout(resolveRuntimeSettings());
         return {
             toolId: this.toolId,
             button: null,
             elements: [
                 {
                     element,
-                    mount: hostLayout.mount,
+                    mount: "before-buttons",
                     layoutHints: {
                         controlsRow: {
                             reserveSpace: hostLayout.controlsRow.reserveSpace,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/pie-default-tool-loaders",
-	"version": "0.3.75",
+	"version": "1.0.0-beta.1",
 	"type": "module",
 	"description": "Composition layer for the packaged PIE assessment tools: registrations, tag map, placement preset, universal and empty profiles, and lazy module loaders",
 	"repository": {
@@ -33,25 +33,25 @@
 		"test": "bun test"
 	},
 	"dependencies": {
-		"@pie-players/pie-assessment-toolkit": "0.3.75",
-		"@pie-players/pie-calculator": "0.3.75",
-		"@pie-players/pie-calculator-cortex": "0.3.75",
-		"@pie-players/pie-calculator-desmos": "0.3.75",
-		"@pie-players/pie-calculator-geogebra": "0.3.75",
-		"@pie-players/pie-players-shared": "0.3.75",
-		"@pie-players/pie-tool-annotation-toolbar": "0.3.75",
-		"@pie-players/pie-tool-answer-eliminator": "0.3.75",
-		"@pie-players/pie-tool-calculator-shared": "0.3.75",
-		"@pie-players/pie-tool-dictionary": "0.3.75",
-		"@pie-players/pie-tool-graph": "0.3.75",
-		"@pie-players/pie-tool-line-reader": "0.3.75",
-		"@pie-players/pie-tool-periodic-table": "0.3.75",
-		"@pie-players/pie-tool-picture-dictionary": "0.3.75",
-		"@pie-players/pie-tool-protractor": "0.3.75",
-		"@pie-players/pie-tool-ruler": "0.3.75",
-		"@pie-players/pie-tool-theme": "0.3.75",
-		"@pie-players/pie-tool-tts-inline": "0.3.75",
-		"@pie-players/tts-client-server": "0.3.75"
+		"@pie-players/pie-assessment-toolkit": "1.0.0-beta.1",
+		"@pie-players/pie-calculator": "1.0.0-beta.1",
+		"@pie-players/pie-calculator-cortex": "1.0.0-beta.1",
+		"@pie-players/pie-calculator-desmos": "1.0.0-beta.1",
+		"@pie-players/pie-calculator-geogebra": "1.0.0-beta.1",
+		"@pie-players/pie-players-shared": "1.0.0-beta.1",
+		"@pie-players/pie-tool-annotation-toolbar": "1.0.0-beta.1",
+		"@pie-players/pie-tool-answer-eliminator": "1.0.0-beta.1",
+		"@pie-players/pie-tool-calculator-shared": "1.0.0-beta.1",
+		"@pie-players/pie-tool-dictionary": "1.0.0-beta.1",
+		"@pie-players/pie-tool-graph": "1.0.0-beta.1",
+		"@pie-players/pie-tool-line-reader": "1.0.0-beta.1",
+		"@pie-players/pie-tool-periodic-table": "1.0.0-beta.1",
+		"@pie-players/pie-tool-picture-dictionary": "1.0.0-beta.1",
+		"@pie-players/pie-tool-protractor": "1.0.0-beta.1",
+		"@pie-players/pie-tool-ruler": "1.0.0-beta.1",
+		"@pie-players/pie-tool-theme": "1.0.0-beta.1",
+		"@pie-players/pie-tool-tts-inline": "1.0.0-beta.1",
+		"@pie-players/tts-client-server": "1.0.0-beta.1"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.5.15",