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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PIE Framework contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -5,9 +5,9 @@ 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.
 
-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,
+The package owns the concrete `pie-tool-*` dependencies and the Desmos and
+GeoGebra calculator adapters (`pie-calculator-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.
 
@@ -15,6 +15,8 @@ capability id. A support id is the tool id a profile grants.
 | --- | --- |
 | `PACKAGED_TOOL_REGISTRATIONS`, `createPackagedToolRegistry` | Which capabilities exist, and their toolbar and surface contracts |
 | `PACKAGED_TOOL_TAG_MAP` | Which custom element each one renders as |
+| `createCalculatorToolRegistration` | Which calculator backends `provider.id` selects among |
+| `createTTSToolRegistration` | Which host text-to-speech providers `provider.id` selects among |
 | `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 |
@@ -58,15 +60,8 @@ 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.
+Without one the calculator fails to load. `provider.id: "calculator-geogebra"`
+selects GeoGebra, which needs no key.
 
 ```ts
 const tools = {
@@ -82,6 +77,95 @@ const tools = {
 };
 ```
 
+### Adding a backend
+
+The packaged registration selects among Desmos and GeoGebra only, because a
+bundler that inlines dynamic imports inlines every backend the registration
+names, selected or not. `createCalculatorToolRegistration({ providers })` builds
+the registration with more backends, keyed by `provider.id`; an id the packaged
+set already holds is replaced. The keyless, offline-capable Cortex calculator,
+which needs no runtime CDN, is composed in this way from
+`@pie-players/pie-calculator-cortex`, which the host installs:
+
+```ts
+import {
+	createCalculatorToolRegistration,
+	createPackagedToolRegistry,
+} from "@pie-players/pie-default-tool-loaders";
+
+const registry = createPackagedToolRegistry({
+	overrides: {
+		calculator: createCalculatorToolRegistration({
+			providers: {
+				"calculator-cortex": {
+					providerName: "PIE Open-Source Calculator",
+					version: "1",
+					requiresAuth: false,
+					backend: "cortex",
+					load: async () =>
+						(await import("@pie-players/pie-calculator-cortex"))
+							.CortexCalculatorProvider,
+					initializationErrorMessage:
+						"Failed to initialize the Cortex calculator provider.",
+				},
+			},
+		}),
+	},
+});
+```
+
+`provider.id: "calculator-cortex"` then selects it. 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.
+
+## Text-to-speech providers
+
+The packaged text-to-speech registration speaks through the browser or a TTS
+server, as `backend` selects. `createTTSToolRegistration({ providers })` adds a
+host's own `ITTSProvider`, keyed by `provider.id`; the class is imported only
+when its id is selected.
+
+```ts
+import {
+	createPackagedToolRegistry,
+	createTTSToolRegistration,
+} from "@pie-players/pie-default-tool-loaders";
+
+const registry = createPackagedToolRegistry({
+	overrides: {
+		textToSpeech: createTTSToolRegistration({
+			providers: {
+				"host-tts": {
+					load: async () => (await import("./host-tts.js")).HostTTSProvider,
+				},
+			},
+		}),
+	},
+});
+
+// tools.providers.textToSpeech
+const textToSpeech = {
+	enabled: true,
+	language: "en-US",
+	provider: { id: "host-tts" },
+};
+```
+
+The provider's `initialize()` receives the config the toolkit builds for every
+backend: `voice`, `rate`, `pitch`, `language`, `providerOptions` (the host's
+`language` as `locale`) and `mathTokenHighlighting`. `apiEndpoint` and the
+backend and transport keys are not required. With `requiresAuth: true` on the
+descriptor, the toolkit first awaits `provider.runtime.authFetcher` and merges what it returns, such as
+`authToken` or `headers`, into that config. A provider that fails to initialize
+falls back to browser speech, as a server backend does. A `provider.id` that
+names no registered provider, or none at all, keeps the browser or server
+backend.
+
 ## Custom sets
 
 A host composing its own set starts from the toolkit's empty `ToolRegistry`,
@@ -167,8 +251,8 @@ 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.
+type, the sign language and the magnifier's starting zoom. The toolkit's PNP
+configuration guide gives each AfA feature's disposition.
 
 ```ts
 import { createPersonalNeedsProfileFromAfa } from "@pie-players/pie-default-tool-loaders";

package/dist/afa-profile.d.ts

@@ -28,6 +28,10 @@ export interface AfaSpoken {
 }
 /** A set's features: empty elements keyed by feature, or the feature names. */
 export type AfaFeatureSet = Readonly<Record<string, unknown>> | readonly string[];
+/** AfA's `ZoomAmount`: a magnification multiplier. */
+export interface AfaZoomAmount {
+    "zoom-amount"?: number;
+}
 /** An AfA PNP 3.0 record in JSON. A feature is present unless absent, `null` or `false`. */
 export interface AfaPnpRecord {
     spoken?: AfaSpoken;
@@ -39,6 +43,19 @@ export interface AfaPnpRecord {
         language?: string;
         [setting: string]: unknown;
     };
+    "item-translation"?: {
+        language?: string;
+        [setting: string]: unknown;
+    };
+    /** One selection: the amount for all content, or for text and non-text apart. */
+    magnification?: {
+        "all-content"?: AfaZoomAmount;
+        selectMagnification?: {
+            text?: AfaZoomAmount;
+            "non-text"?: AfaZoomAmount;
+        };
+        [setting: string]: unknown;
+    };
     "activate-at-initialization-set"?: AfaFeatureSet;
     "activate-as-option-set"?: AfaFeatureSet;
     "prohibit-set"?: AfaFeatureSet;

package/dist/afa-profile.js

@@ -70,6 +70,16 @@ function spokenParameters(spoken) {
         ...(volume !== undefined ? { volume } : {}),
     };
 }
+/**
+ * The lens's starting zoom. The lens magnifies text and non-text alike, so a
+ * record that sets them apart gives the text amount, else the non-text one.
+ */
+function magnifierZoom(magnification) {
+    const select = magnification?.selectMagnification;
+    return (finiteNumber(magnification?.["all-content"]?.["zoom-amount"]) ??
+        finiteNumber(select?.text?.["zoom-amount"]) ??
+        finiteNumber(select?.["non-text"]?.["zoom-amount"]));
+}
 /** 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
@@ -108,6 +118,14 @@ export function createPersonalNeedsProfileFromAfa(record) {
     if (typeof signLang === "string" && signLang.length > 0) {
         toolParameters.signLanguage = { signLang };
     }
+    const translationLang = record["item-translation"]?.language;
+    if (typeof translationLang === "string" && translationLang.length > 0) {
+        toolParameters.itemTranslation = { language: translationLang };
+    }
+    const zoom = magnifierZoom(record.magnification);
+    if (zoom !== undefined && zoom > 1) {
+        toolParameters.magnification = { zoom };
+    }
     return {
         supports,
         prohibitedSupports: [...prohibited].sort(),

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

@@ -1,33 +1,47 @@
 import type { CalculatorProvider, CalculatorProviderInit } from "@pie-players/pie-calculator";
 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>;
-};
-export interface LazyCalculatorProviderDefinition<TConfig> {
-    backend: string;
-    moduleImportOperation: string;
-    loadProvider: () => Promise<new () => InitializableCalculatorProvider<TConfig>>;
-    initializationErrorMessage: string;
+/**
+ * One calculator backend, selected by the toolkit's `provider.id`. `load` runs
+ * on first use, but a bundler that inlines dynamic imports inlines what it
+ * names whether or not the host selects the backend. The packaged set therefore
+ * holds only the thin Desmos and GeoGebra adapters, and a host adds any other
+ * backend through `createCalculatorToolRegistration`.
+ */
+export interface CalculatorProviderDefinition {
+    /** Names the provider in toolkit logs, telemetry and error messages. */
+    readonly providerName: string;
+    readonly version: string;
+    /**
+     * Whether the registry merges the result of `provider.runtime.authFetcher`
+     * into the configuration `initialize()` receives.
+     */
+    readonly requiresAuth: boolean;
+    /** The `backend` of library-load telemetry. */
+    readonly backend: string;
+    /** Loads the adapter's provider class, usually through a dynamic import. */
+    readonly load: () => Promise<new () => CalculatorProvider>;
+    /** Thrown, with the failure as its cause, when loading or initializing fails. */
+    readonly initializationErrorMessage: string;
 }
 /**
- * Shared lazy-module and lifecycle implementation for calculator tool adapters.
- * Concrete adapters own only their metadata and provider import.
+ * Lazy-module and lifecycle implementation shared by every calculator backend:
+ * concurrent initialization is deduplicated, and `destroy()` cancels one in
+ * flight.
  */
-export declare abstract class LazyCalculatorToolProvider<TConfig extends CalculatorToolProviderInitConfig> implements ToolProviderApi<CalculatorProvider> {
-    abstract readonly providerName: string;
+export declare class LazyCalculatorToolProvider implements ToolProviderApi<CalculatorProvider> {
+    readonly providerName: string;
     readonly category: "calculator";
-    abstract readonly version: string;
-    abstract readonly requiresAuth: boolean;
-    protected abstract getDefinition(): LazyCalculatorProviderDefinition<TConfig>;
+    readonly version: string;
+    readonly requiresAuth: boolean;
+    private readonly definition;
     private calculatorProvider;
     private initializationPromise;
     private lifecycleGeneration;
+    constructor(definition: CalculatorProviderDefinition);
     private emitTelemetry;
-    initialize(config?: TConfig): Promise<void>;
+    initialize(config?: CalculatorProviderInit): Promise<void>;
     private initializeProvider;
     createInstance(): Promise<CalculatorProvider>;
     isReady(): boolean;
     destroy(): void;
 }
-export {};

package/dist/calculator-providers/LazyCalculatorToolProvider.js

@@ -1,12 +1,23 @@
 /**
- * Shared lazy-module and lifecycle implementation for calculator tool adapters.
- * Concrete adapters own only their metadata and provider import.
+ * Lazy-module and lifecycle implementation shared by every calculator backend:
+ * concurrent initialization is deduplicated, and `destroy()` cancels one in
+ * flight.
  */
 export class LazyCalculatorToolProvider {
+    providerName;
     category = "calculator";
+    version;
+    requiresAuth;
+    definition;
     calculatorProvider = null;
     initializationPromise = null;
     lifecycleGeneration = 0;
+    constructor(definition) {
+        this.definition = definition;
+        this.providerName = definition.providerName;
+        this.version = definition.version;
+        this.requiresAuth = definition.requiresAuth;
+    }
     async emitTelemetry(config, eventName, payload) {
         try {
             await config.onTelemetry?.(eventName, payload);
@@ -33,33 +44,34 @@ export class LazyCalculatorToolProvider {
         }
     }
     async initializeProvider(config, generation) {
-        const definition = this.getDefinition();
+        const { backend, initializationErrorMessage } = this.definition;
+        const operation = `${backend}-provider-module-import`;
         const moduleLoadStartedAt = Date.now();
         await this.emitTelemetry(config, "pie-tool-library-load-start", {
             toolId: "calculator",
-            operation: definition.moduleImportOperation,
-            backend: definition.backend,
+            operation,
+            backend,
         });
         let ProviderConstructor;
         try {
-            ProviderConstructor = await definition.loadProvider();
+            ProviderConstructor = await this.definition.load();
             await this.emitTelemetry(config, "pie-tool-library-load-success", {
                 toolId: "calculator",
-                operation: definition.moduleImportOperation,
-                backend: definition.backend,
+                operation,
+                backend,
                 duration: Date.now() - moduleLoadStartedAt,
             });
         }
         catch (error) {
             await this.emitTelemetry(config, "pie-tool-library-load-error", {
                 toolId: "calculator",
-                operation: definition.moduleImportOperation,
-                backend: definition.backend,
+                operation,
+                backend,
                 duration: Date.now() - moduleLoadStartedAt,
                 errorType: "ToolLibraryLoadError",
                 message: error instanceof Error ? error.message : String(error),
             });
-            throw new Error(definition.initializationErrorMessage, { cause: error });
+            throw new Error(initializationErrorMessage, { cause: error });
         }
         if (generation !== this.lifecycleGeneration) {
             throw new Error(`${this.providerName} initialization was cancelled`);
@@ -74,7 +86,7 @@ export class LazyCalculatorToolProvider {
         }
         catch (error) {
             candidate.destroy();
-            throw new Error(definition.initializationErrorMessage, { cause: error });
+            throw new Error(initializationErrorMessage, { cause: error });
         }
     }
     async createInstance() {

package/dist/calculator-providers/packaged-calculator-providers.js

@@ -0,0 +1,26 @@
+/**
+ * The calculator backends of the packaged set, by `provider.id`. Every import
+ * named here lands in a host bundle that inlines dynamic imports, so only thin
+ * adapters over a vendor-hosted engine belong in it.
+ */
+export const DEFAULT_CALCULATOR_PROVIDER_ID = "calculator-desmos";
+export const PACKAGED_CALCULATOR_PROVIDERS = {
+    "calculator-desmos": {
+        providerName: "Desmos Calculator",
+        version: "1.12",
+        requiresAuth: true,
+        backend: "desmos",
+        load: async () => (await import("@pie-players/pie-calculator-desmos"))
+            .DesmosCalculatorProvider,
+        initializationErrorMessage: "Failed to initialize Desmos calculator provider. Check the application key, preloaded API, runtime endpoint, or network access.",
+    },
+    "calculator-geogebra": {
+        providerName: "GeoGebra Calculator",
+        version: "6",
+        requiresAuth: false,
+        backend: "geogebra",
+        load: async () => (await import("@pie-players/pie-calculator-geogebra"))
+            .GeoGebraCalculatorProvider,
+        initializationErrorMessage: "Failed to initialize GeoGebra calculator provider. Confirm that the deployment may load GeoGebra and that its script URL is reachable.",
+    },
+};

package/dist/index.d.ts

@@ -1,12 +1,13 @@
 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 { type AfaFeatureSet, type AfaPnpRecord, type AfaSpoken, type AfaZoomAmount, 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, CONTENT_LEAD_SURFACE, resolveAudioTranscript, type ResolvedAudioTranscript, } from "./registrations/audio-transcript.js";
-export { calculatorToolRegistration } from "./registrations/calculator.js";
+export { annotationToolbarRegistration, lineReaderToolRegistration, magnificationToolRegistration, 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 { CONTENT_LEAD_SURFACE } from "@pie-players/pie-assessment-toolkit/tools/registration";
+export { type CalculatorProviderDefinition, type CalculatorRegistrationOptions, calculatorToolRegistration, createCalculatorToolRegistration, } 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";
+export { type AnswerEliminatorToolConfig, answerEliminatorToolRegistration, } from "./registrations/interaction-tools.js";
 export { protractorToolRegistration, rulerToolRegistration, } from "./registrations/measurement-tools.js";
 export { graphToolRegistration, periodicTableToolRegistration, } from "./registrations/subject-specific-tools.js";
-export { ttsToolRegistration } from "./registrations/tts.js";
+export { createTTSToolRegistration, type TTSHostProviderDescriptor, type TTSRegistrationOptions, ttsToolRegistration, } from "./registrations/tts.js";

package/dist/index.js

@@ -6,11 +6,14 @@ export { createPersonalNeedsProfileFromAfa, } from "./afa-profile.js";
 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, CONTENT_LEAD_SURFACE, resolveAudioTranscript, } from "./registrations/audio-transcript.js";
-export { calculatorToolRegistration } from "./registrations/calculator.js";
+export { annotationToolbarRegistration, lineReaderToolRegistration, magnificationToolRegistration, 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";
+// The canonical surface ids live in the toolkit; re-exported so the packaged
+// set's surface stays unchanged.
+export { CONTENT_LEAD_SURFACE } from "@pie-players/pie-assessment-toolkit/tools/registration";
+export { calculatorToolRegistration, createCalculatorToolRegistration, } from "./registrations/calculator.js";
 export { createDictionaryToolRegistration, createPictureDictionaryToolRegistration, dictionaryToolRegistration, pictureDictionaryToolRegistration, spanishDictionaryToolRegistration, spanishPictureDictionaryToolRegistration, } from "./registrations/dictionary-tools.js";
-export { answerEliminatorToolRegistration } from "./registrations/interaction-tools.js";
+export { answerEliminatorToolRegistration, } from "./registrations/interaction-tools.js";
 export { protractorToolRegistration, rulerToolRegistration, } from "./registrations/measurement-tools.js";
 export { graphToolRegistration, periodicTableToolRegistration, } from "./registrations/subject-specific-tools.js";
-export { ttsToolRegistration } from "./registrations/tts.js";
+export { createTTSToolRegistration, ttsToolRegistration, } from "./registrations/tts.js";

package/dist/packaged-capability-composition.js

@@ -8,7 +8,7 @@
  * cannot leave a second hand-maintained catalogue silently behind.
  */
 import { ToolRegistry, } from "@pie-players/pie-assessment-toolkit/tools/registration";
-import { annotationToolbarRegistration, lineReaderToolRegistration, themeToolRegistration, } from "./registrations/accessibility-tools.js";
+import { annotationToolbarRegistration, lineReaderToolRegistration, magnificationToolRegistration, themeToolRegistration, } from "./registrations/accessibility-tools.js";
 import { audioTranscriptRegistration } from "./registrations/audio-transcript.js";
 import { calculatorToolRegistration } from "./registrations/calculator.js";
 import { dictionaryToolRegistration, pictureDictionaryToolRegistration, spanishDictionaryToolRegistration, spanishPictureDictionaryToolRegistration, } from "./registrations/dictionary-tools.js";
@@ -28,6 +28,7 @@ const loadProtractorModule = () => loadSideEffectModule(() => import("@pie-playe
 const loadAnswerEliminatorModule = () => loadSideEffectModule(() => import("@pie-players/pie-tool-answer-eliminator"));
 const loadAnnotationToolbarModule = () => loadSideEffectModule(() => import("@pie-players/pie-tool-annotation-toolbar"));
 const loadLineReaderModule = () => loadSideEffectModule(() => import("@pie-players/pie-tool-line-reader"));
+const loadMagnifierModule = () => loadSideEffectModule(() => import("@pie-players/pie-tool-magnifier"));
 const loadThemeModule = () => loadSideEffectModule(() => import("@pie-players/pie-tool-theme"));
 const loadGraphModule = () => loadSideEffectModule(() => import("@pie-players/pie-tool-graph"));
 const loadPeriodicTableModule = () => loadSideEffectModule(() => import("@pie-players/pie-tool-periodic-table"));
@@ -76,6 +77,15 @@ const PACKAGED_CAPABILITY_DEFINITIONS = [
         preferredPlacementOrder: { section: 40 },
         universal: true,
     },
+    {
+        registration: magnificationToolRegistration,
+        tagName: "pie-tool-magnifier",
+        loadModule: loadMagnifierModule,
+        preferredPlacementOrder: { section: 45 },
+        // Magnification is a granted low-vision accommodation in AfA PNP, so it
+        // is never universal.
+        universal: false,
+    },
     {
         registration: themeToolRegistration,
         tagName: "pie-tool-theme",

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

@@ -3,6 +3,7 @@
  *
  * Registers tools for visual accessibility and reading support:
  * - Line Reader (reading guide)
+ * - Magnifier (movable magnifying lens)
  * - Color Scheme (theme/contrast)
  * - Annotation Toolbar (text highlighting)
  */
@@ -14,6 +15,13 @@ import type { ToolRegistration } from "@pie-players/pie-assessment-toolkit/tools
  * Useful for text-heavy passages and questions.
  */
 export declare const lineReaderToolRegistration: ToolRegistration;
+/**
+ * Magnifier tool registration
+ *
+ * A movable lens that shows the content under it enlarged. The AfA
+ * `magnification` tool parameter `zoom` sets the lens's starting level.
+ */
+export declare const magnificationToolRegistration: ToolRegistration;
 /**
  * Theme tool registration
  *

package/dist/registrations/accessibility-tools.js

@@ -3,6 +3,7 @@
  *
  * Registers tools for visual accessibility and reading support:
  * - Line Reader (reading guide)
+ * - Magnifier (movable magnifying lens)
  * - Color Scheme (theme/contrast)
  * - Annotation Toolbar (text highlighting)
  */
@@ -36,6 +37,43 @@ export const lineReaderToolRegistration = {
         });
     },
 };
+/** A `zoom` worth passing on: a finite magnification above 1. */
+const normalizeMagnifierZoom = (value) => typeof value === "number" && Number.isFinite(value) && value > 1
+    ? value
+    : undefined;
+/**
+ * Magnifier tool registration
+ *
+ * A movable lens that shows the content under it enlarged. The AfA
+ * `magnification` tool parameter `zoom` sets the lens's starting level.
+ */
+export const magnificationToolRegistration = {
+    toolId: "magnification",
+    name: "Magnifier",
+    description: "Magnify the content under a movable lens",
+    nameKey: "tools.magnification.name",
+    descriptionKey: "tools.magnification.description",
+    icon: "magnifying-glass",
+    supportedLevels: ["section", "passage", "rubric", "item"],
+    /**
+     * Pass 2: anything on screen can be magnified, text or not
+     */
+    isVisibleInContext() {
+        return true;
+    },
+    renderToolbar(context, toolbarContext) {
+        const result = renderOverlayToolbar(this, context, toolbarContext, {
+            surface: "frameless",
+        });
+        const overlay = result.elements?.[0]?.element;
+        const zoom = normalizeMagnifierZoom(toolbarContext.getToolParameters?.("magnification")?.zoom);
+        if (zoom === undefined)
+            overlay?.removeAttribute("zoom");
+        else
+            overlay?.setAttribute("zoom", String(zoom));
+        return result;
+    },
+};
 /**
  * Theme tool registration
  *

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

@@ -66,11 +66,4 @@ export interface ResolvedAudioTranscript {
  * transcript is in the language of the audio it transcribes, one per prompt.
  */
 export declare function resolveAudioTranscript(context: ToolContentDependencyContext): ResolvedAudioTranscript | 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 declare const CONTENT_LEAD_SURFACE = "content-lead";
 export declare const audioTranscriptRegistration: ToolRegistration;

package/dist/registrations/audio-transcript.js

@@ -35,6 +35,7 @@
  * absent from the universal preset — a content-dependent support never belongs in
  * a wholesale grant.
  */
+import { CONTENT_LEAD_SURFACE } from "@pie-players/pie-assessment-toolkit/tools/registration";
 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";
@@ -103,13 +104,6 @@ export function resolveAudioTranscript(context) {
     // 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.
  *

package/dist/registrations/calculator.d.ts

@@ -6,15 +6,26 @@
  */
 import type { ToolRegistration } from "@pie-players/pie-assessment-toolkit/tools/registration";
 import type { ToolProviderConfig } from "@pie-players/pie-assessment-toolkit/tools/registration";
-export type CalculatorProviderId = "calculator-desmos" | "calculator-geogebra" | "calculator-cortex";
-export declare const DEFAULT_CALCULATOR_PROVIDER_ID: CalculatorProviderId;
-export declare function resolveCalculatorProviderId(config: ToolProviderConfig | undefined): CalculatorProviderId;
+import { type CalculatorProviderDefinition } from "../calculator-providers/LazyCalculatorToolProvider.js";
+export type { CalculatorProviderDefinition };
+export interface CalculatorRegistrationOptions {
+    /**
+     * Backends by `provider.id`, merged over the packaged Desmos and GeoGebra
+     * definitions. An entry under a packaged id replaces that backend.
+     */
+    providers?: Readonly<Record<string, CalculatorProviderDefinition>>;
+}
+export declare function resolveCalculatorProviderId(config: ToolProviderConfig | undefined, providers?: Readonly<Record<string, CalculatorProviderDefinition>>): string;
 /**
- * Calculator tool registration
+ * Builds the calculator registration over the packaged backends plus any the
+ * host adds, so a host bundles a backend only by naming it.
  *
  * Supports:
- * - Basic, scientific, and graphing calculators through Desmos, GeoGebra, or Cortex
+ * - Basic, scientific, and graphing calculators through the backend that
+ *   `provider.id` selects, Desmos by default
  * - Context-aware visibility (shows only when math content is detected)
  * - Item level only
  */
+export declare function createCalculatorToolRegistration(options?: CalculatorRegistrationOptions): ToolRegistration;
+/** The calculator over the packaged Desmos and GeoGebra backends. */
 export declare const calculatorToolRegistration: ToolRegistration;