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

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;

package/dist/registrations/calculator.js

@@ -7,32 +7,21 @@
 import { hasMathContent } from "@pie-players/pie-assessment-toolkit/tools/registration";
 import { createScopedToolId } from "@pie-players/pie-assessment-toolkit/tools/registration";
 import { createToolElement } from "@pie-players/pie-assessment-toolkit/tools/registration";
-import { CortexToolProvider } from "../calculator-providers/CortexToolProvider.js";
-import { DesmosToolProvider } from "../calculator-providers/DesmosToolProvider.js";
-import { GeoGebraToolProvider } from "../calculator-providers/GeoGebraToolProvider.js";
+import { LazyCalculatorToolProvider, } from "../calculator-providers/LazyCalculatorToolProvider.js";
+import { DEFAULT_CALCULATOR_PROVIDER_ID, PACKAGED_CALCULATOR_PROVIDERS, } from "../calculator-providers/packaged-calculator-providers.js";
 import { resolveOverlayElement } from "./overlay-element-cache.js";
-export const DEFAULT_CALCULATOR_PROVIDER_ID = "calculator-desmos";
-export function resolveCalculatorProviderId(config) {
+export function resolveCalculatorProviderId(config, providers = PACKAGED_CALCULATOR_PROVIDERS) {
     const configured = config?.provider?.id;
     if (configured === undefined || configured === "") {
         return DEFAULT_CALCULATOR_PROVIDER_ID;
     }
-    if (configured === "calculator-desmos" ||
-        configured === "calculator-geogebra" ||
-        configured === "calculator-cortex") {
+    if (typeof configured === "string" && Object.hasOwn(providers, configured)) {
         return configured;
     }
-    throw new Error(`Unsupported calculator provider "${String(configured)}". Expected "calculator-desmos", "calculator-geogebra", or "calculator-cortex".`);
-}
-function createCalculatorToolProvider(config) {
-    switch (resolveCalculatorProviderId(config)) {
-        case "calculator-cortex":
-            return new CortexToolProvider();
-        case "calculator-geogebra":
-            return new GeoGebraToolProvider();
-        default:
-            return new DesmosToolProvider();
-    }
+    const expected = Object.keys(providers)
+        .map((id) => `"${id}"`)
+        .join(", ");
+    throw new Error(`Unsupported calculator provider "${String(configured)}". Expected one of ${expected}.`);
 }
 function getCalculatorInstanceConfig(config) {
     const theme = config?.theme;
@@ -104,169 +93,175 @@ function applyCalculatorParamsToElement(element, calculatorType, availableTypes,
     }
 }
 /**
- * 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 const calculatorToolRegistration = {
-    toolId: "calculator",
-    name: "Calculator",
-    description: "Multi-type calculator (basic, scientific, graphing)",
-    nameKey: "tools.calculator.name",
-    descriptionKey: "tools.calculator.description",
-    icon: "calculator",
-    provider: {
-        createProvider: createCalculatorToolProvider,
-        getInitConfig: (config) => config?.provider?.init ?? {},
-        getAuthFetcher: (config) => {
-            const runtimeAuthFetcher = config?.provider?.runtime?.authFetcher;
-            return typeof runtimeAuthFetcher === "function"
-                ? runtimeAuthFetcher
-                : undefined;
+export function createCalculatorToolRegistration(options = {}) {
+    const providers = { ...PACKAGED_CALCULATOR_PROVIDERS, ...options.providers };
+    return {
+        toolId: "calculator",
+        name: "Calculator",
+        description: "Multi-type calculator (basic, scientific, graphing)",
+        nameKey: "tools.calculator.name",
+        descriptionKey: "tools.calculator.description",
+        icon: "calculator",
+        provider: {
+            createProvider: (config) => new LazyCalculatorToolProvider(providers[resolveCalculatorProviderId(config, providers)]),
+            getInitConfig: (config) => config?.provider?.init ?? {},
+            getAuthFetcher: (config) => {
+                const runtimeAuthFetcher = config?.provider?.runtime?.authFetcher;
+                return typeof runtimeAuthFetcher === "function"
+                    ? runtimeAuthFetcher
+                    : undefined;
+            },
+            lazy: true,
+        },
+        // Calculator is item-level in this player architecture.
+        supportedLevels: ["item"],
+        /**
+         * Pass 2: Determine if calculator is relevant in this context
+         *
+         * Calculator is relevant when context contains mathematical content
+         * (MathML, LaTeX, arithmetic markers).
+         */
+        isVisibleInContext(context) {
+            return hasMathContent(context);
         },
-        lazy: true,
-    },
-    // Calculator is item-level in this player architecture.
-    supportedLevels: ["item"],
-    /**
-     * Pass 2: Determine if calculator is relevant in this context
-     *
-     * Calculator is relevant when context contains mathematical content
-     * (MathML, LaTeX, arithmetic markers).
-     */
-    isVisibleInContext(context) {
-        return hasMathContent(context);
-    },
-    renderToolbar(context, toolbarContext) {
-        const { calculatorType, availableTypes, displayName } = getCalculatorRenderParams(toolbarContext);
-        const calculatorToolConfig = toolbarContext.toolkitCoordinator?.getToolConfig(this.toolId) ||
-            undefined;
-        const calculatorConfig = getCalculatorInstanceConfig(calculatorToolConfig);
-        const fullToolId = createScopedToolId(this.toolId, toolbarContext.scope.level, toolbarContext.scope.scopeId);
-        const componentOverrides = toolbarContext.componentOverrides;
-        // Reused across renders: besides keeping state, this spares a Desmos boot
-        // and container mount on every re-render.
-        const overlay = resolveOverlayElement(toolbarContext, fullToolId, () => createToolElement(this.toolId, context, toolbarContext, componentOverrides));
-        overlay.setAttribute("tool-id", fullToolId);
-        applyCalculatorParamsToElement(overlay, calculatorType, availableTypes, calculatorConfig);
-        const button = {
-            toolId: this.toolId,
-            label: displayName,
-            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.
-            faIconName: "calculator",
-            disabled: false,
-            // The name stays put across open and closed. The toolbar mirrors
-            // `active` onto the button as `aria-pressed`, so the state is already
-            // exposed; a name that also swapped to "Close …" would contradict it.
-            ariaLabel: displayName,
-            tooltip: displayName,
-            onClick: () => toolbarContext.toggleTool(this.toolId),
-            active: toolbarContext.isToolVisible(this.toolId),
-        };
-        let lastVisibleState = button.active;
-        if (overlay.visible !== button.active) {
-            overlay.visible = button.active;
-        }
-        return {
-            toolId: this.toolId,
-            elements: [
-                {
-                    element: overlay,
-                    mount: "after-buttons",
-                    shell: {
-                        // The variant name the button already carries — "Basic Calculator",
-                        // not the registration's generic one.
-                        title: displayName,
-                        draggable: true,
-                        resizable: true,
-                        closeable: true,
-                        /*
-                         * Sized per type from what each layout measures, rather than one
-                         * size for all three. A shell subtracts ~74px of header from the
-                         * height it is given, and the numbers below are the content each
-                         * type needs plus room for its history tape:
-                         *
-                         * - basic: strip, display, edit row and a four-row keypad measure
-                         *   398px. 560 left ~90px of blank above the entry line, which is
-                         *   the gap that made the panel look mis-sized.
-                         * - scientific: the same plus a keypad layer tab row.
-                         * - graphing: the expression rail beside the plot, whose column
-                         *   wants 486px on its own — viewport controls, a 14rem board floor
-                         *   and the readout that *is* the graph for assistive technology,
-                         *   since the board itself is `aria-hidden`. At 620 that column was
-                         *   12px short and the readout's last line was cut off.
-                         *
-                         * The minimums stay shared across types and providers. This
-                         * registration serves Desmos, GeoGebra and Cortex alike, so a
-                         * graphing-only floor would move the resize limit under two vendors
-                         * whose layouts were never measured for it. Cortex below 42rem
-                         * stacks the rail above the plot and needs 701px there, which no
-                         * spacing tier closes — it scrolls its own content instead of
-                         * clipping it, which is the contract every size below the opening
-                         * one already relies on.
-                         */
-                        initialWidth: calculatorType === "graphing" ? 720 : 380,
-                        initialHeight: calculatorType === "graphing"
-                            ? 660
-                            : calculatorType === "basic"
-                                ? 500
-                                : 560,
-                        minWidth: 380,
-                        minHeight: 480,
-                        /*
-                         * `bottom-right` put a 560-620px-tall shell over the items
-                         * column it shares the viewport with — tall enough, at
-                         * ordinary viewport heights, to sit on top of a sibling
-                         * item's own toolbar row and block its button from mouse
-                         * and touch input. `bottom-left` keeps the same footprint
-                         * over the passage column instead, which carries no
-                         * per-item controls to collide with.
-                         */
-                        initialAlign: "bottom-left",
-                        initialMargin: 16,
-                        // Header controls in the host's design system, and the layout that
-                        // goes with them.
-                        ndsHeaderControls: true,
-                        // A learner reads the question while using the calculator, so Tab and
-                        // Shift+Tab cross between the page and the shell instead of cycling
-                        // inside it.
-                        pageTabOrder: true,
-                        content: {
-                            overflowY: "auto",
-                            preserveMinHeight: true,
+        renderToolbar(context, toolbarContext) {
+            const { calculatorType, availableTypes, displayName } = getCalculatorRenderParams(toolbarContext);
+            const calculatorToolConfig = toolbarContext.toolkitCoordinator?.getToolConfig(this.toolId) ||
+                undefined;
+            const calculatorConfig = getCalculatorInstanceConfig(calculatorToolConfig);
+            const fullToolId = createScopedToolId(this.toolId, toolbarContext.scope.level, toolbarContext.scope.scopeId);
+            const componentOverrides = toolbarContext.componentOverrides;
+            // Reused across renders: besides keeping state, this spares a Desmos boot
+            // and container mount on every re-render.
+            const overlay = resolveOverlayElement(toolbarContext, fullToolId, () => createToolElement(this.toolId, context, toolbarContext, componentOverrides));
+            overlay.setAttribute("tool-id", fullToolId);
+            applyCalculatorParamsToElement(overlay, calculatorType, availableTypes, calculatorConfig);
+            const button = {
+                toolId: this.toolId,
+                label: displayName,
+                icon: typeof this.icon === "function" ? this.icon(context) : this.icon,
+                // Routes this button through <pie-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.
+                faIconName: "calculator",
+                disabled: false,
+                // The name stays put across open and closed. The toolbar mirrors
+                // `active` onto the button as `aria-pressed`, so the state is already
+                // exposed; a name that also swapped to "Close …" would contradict it.
+                ariaLabel: displayName,
+                tooltip: displayName,
+                onClick: () => toolbarContext.toggleTool(this.toolId),
+                active: toolbarContext.isToolVisible(this.toolId),
+            };
+            let lastVisibleState = button.active;
+            if (overlay.visible !== button.active) {
+                overlay.visible = button.active;
+            }
+            return {
+                toolId: this.toolId,
+                elements: [
+                    {
+                        element: overlay,
+                        mount: "after-buttons",
+                        shell: {
+                            // The variant name the button already carries — "Basic Calculator",
+                            // not the registration's generic one.
+                            title: displayName,
+                            draggable: true,
+                            resizable: true,
+                            closeable: true,
+                            /*
+                             * Sized per type from what each layout measures, rather than one
+                             * size for all three. A shell subtracts ~74px of header from the
+                             * height it is given, and the numbers below are the content each
+                             * type needs plus room for its history tape:
+                             *
+                             * - basic: strip, display, edit row and a four-row keypad measure
+                             *   398px. 560 left ~90px of blank above the entry line, which is
+                             *   the gap that made the panel look mis-sized.
+                             * - scientific: the same plus a keypad layer tab row.
+                             * - graphing: the expression rail beside the plot, whose column
+                             *   wants 486px on its own — viewport controls, a 14rem board floor
+                             *   and the readout that *is* the graph for assistive technology,
+                             *   since the board itself is `aria-hidden`. At 620 that column was
+                             *   12px short and the readout's last line was cut off.
+                             *
+                             * The minimums stay shared across types and backends. One
+                             * registration serves every backend, so a graphing-only floor
+                             * would move the resize limit under vendors whose layouts were
+                             * never measured for it. Cortex below 42rem stacks the rail above
+                             * the plot and needs 701px there, which no spacing tier closes — it
+                             * scrolls its own content instead of clipping it, which is the
+                             * contract every size below the opening one already relies on.
+                             */
+                            initialWidth: calculatorType === "graphing" ? 720 : 380,
+                            initialHeight: calculatorType === "graphing"
+                                ? 660
+                                : calculatorType === "basic"
+                                    ? 500
+                                    : 560,
+                            minWidth: 380,
+                            minHeight: 480,
+                            /*
+                             * `bottom-right` put a 560-620px-tall shell over the items
+                             * column it shares the viewport with — tall enough, at
+                             * ordinary viewport heights, to sit on top of a sibling
+                             * item's own toolbar row and block its button from mouse
+                             * and touch input. `bottom-left` keeps the same footprint
+                             * over the passage column instead, which carries no
+                             * per-item controls to collide with.
+                             */
+                            initialAlign: "bottom-left",
+                            initialMargin: 16,
+                            // Header controls in the host's design system, and the layout that
+                            // goes with them.
+                            ndsHeaderControls: true,
+                            // A learner reads the question while using the calculator, so Tab and
+                            // Shift+Tab cross between the page and the shell instead of cycling
+                            // inside it.
+                            pageTabOrder: true,
+                            content: {
+                                overflowY: "auto",
+                                preserveMinHeight: true,
+                            },
                         },
                     },
+                ],
+                button,
+                sync: () => {
+                    const active = toolbarContext.isToolVisible(this.toolId);
+                    button.active = active;
+                    button.label = displayName;
+                    // 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) {
+                        overlay.visible = active;
+                        lastVisibleState = active;
+                    }
+                    applyCalculatorParamsToElement(overlay, calculatorType, availableTypes, calculatorConfig);
                 },
-            ],
-            button,
-            sync: () => {
-                const active = toolbarContext.isToolVisible(this.toolId);
-                button.active = active;
-                button.label = displayName;
-                // 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) {
-                    overlay.visible = active;
-                    lastVisibleState = active;
-                }
-                applyCalculatorParamsToElement(overlay, calculatorType, availableTypes, calculatorConfig);
-            },
-            subscribeActive: (callback) => {
-                if (!toolbarContext.subscribeVisibility)
-                    return () => { };
-                return toolbarContext.subscribeVisibility(() => {
-                    callback(toolbarContext.isToolVisible(this.toolId));
-                });
-            },
-        };
-    },
-};
+                subscribeActive: (callback) => {
+                    if (!toolbarContext.subscribeVisibility)
+                        return () => { };
+                    return toolbarContext.subscribeVisibility(() => {
+                        callback(toolbarContext.isToolVisible(this.toolId));
+                    });
+                },
+            };
+        },
+    };
+}
+/** The calculator over the packaged Desmos and GeoGebra backends. */
+export const calculatorToolRegistration = createCalculatorToolRegistration();

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

@@ -4,11 +4,24 @@
  * Registers tools for interacting with question content:
  * - Answer Eliminator (strike through answer choices)
  */
-import type { ToolRegistration } from "@pie-players/pie-assessment-toolkit/tools/registration";
+import type { ToolProviderConfig, ToolRegistration } from "@pie-players/pie-assessment-toolkit/tools/registration";
+/**
+ * The answer eliminator's `tools.providers.answerEliminator` entry.
+ */
+export interface AnswerEliminatorToolConfig extends ToolProviderConfig {
+    /**
+     * The elements the eliminator acts on, by the name `<name>` of their
+     * `@pie-element/<name>` package, such as `["multiple-choice"]`. An element
+     * must also support answer masking. Omitted, every element that supports it
+     * takes the eliminator; empty, none does. A host lists the elements whose
+     * support it has vetted.
+     */
+    elements?: readonly string[];
+}
 /**
  * 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;