@pie-players/pie-default-tool-loaders 0.3.67 → 0.3.69

package/dist/registrations/accessibility-tools.js

@@ -13,6 +13,8 @@
 import { hasReadableText } from "@pie-players/pie-assessment-toolkit/tools/internal";
 import { createToolElement, resolveToolTag, } from "@pie-players/pie-assessment-toolkit/tools/internal";
 import { applyOverlaySurface, createScopedVisibilityBinding, syncButtonAndOverlayVisibility, } from "@pie-players/pie-assessment-toolkit/tools/internal";
+import { buildSelectionActions } from "./selection-actions.js";
+import { renderOverlayToolbar } from "./overlay-toolbar-render.js";
 /**
  * Line Reader tool registration
  *
@@ -23,6 +25,8 @@ export const lineReaderToolRegistration = {
     toolId: "lineReader",
     name: "Line Reader",
     description: "Reading guide overlay",
+    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"],
@@ -32,8 +36,6 @@ export const lineReaderToolRegistration = {
         "readingMask", // QTI 3.0 standard (reading.readingMask)
         "readingGuide", // QTI 3.0 standard (reading.readingGuide)
         "readingRuler", // QTI 3.0 standard (reading.readingRuler)
-        "lineReader", // Common variant
-        "trackingGuide", // Common variant
     ],
     /**
      * Pass 2: Line reader is relevant when readable text is present
@@ -42,37 +44,10 @@ export const lineReaderToolRegistration = {
         return hasReadableText(context);
     },
     renderToolbar(context, toolbarContext) {
-        const visibility = createScopedVisibilityBinding(this.toolId, toolbarContext);
-        const button = {
-            toolId: this.toolId,
-            label: this.name,
-            icon: typeof this.icon === "function" ? this.icon(context) : this.icon,
-            disabled: false,
-            ariaLabel: "Line reader - Reading guide",
-            tooltip: "Line Reader",
-            onClick: () => toolbarContext.toggleTool(this.toolId),
-            active: visibility.isActive(),
-        };
-        const componentOverrides = toolbarContext.componentOverrides ?? {};
-        const overlay = createToolElement(this.toolId, context, toolbarContext, componentOverrides);
-        overlay.setAttribute("tool-id", visibility.fullToolId);
-        applyOverlaySurface(overlay, "frameless");
-        return {
-            toolId: this.toolId,
-            button,
-            elements: [{ element: overlay, mount: "after-buttons" }],
-            sync: () => {
-                syncButtonAndOverlayVisibility({
-                    button,
-                    overlay,
-                    isActive: visibility.isActive,
-                });
-                if (toolbarContext.toolkitCoordinator) {
-                    overlay.toolkitCoordinator = toolbarContext.toolkitCoordinator;
-                }
-            },
-            subscribeActive: visibility.subscribeActive,
-        };
+        return renderOverlayToolbar(this, context, toolbarContext, {
+            surface: "frameless",
+            handsOverCoordinator: true,
+        });
     },
 };
 /**
@@ -85,6 +60,8 @@ export const themeToolRegistration = {
     toolId: "theme",
     name: "Theme",
     description: "Accessible themes and contrast",
+    nameKey: "tools.theme.name",
+    descriptionKey: "tools.theme.description",
     icon: "swatch",
     // Color scheme is assessment-wide
     supportedLevels: ["assessment", "section"],
@@ -94,9 +71,7 @@ export const themeToolRegistration = {
         "highContrastDisplay", // QTI 3.0 standard (visual.highContrastDisplay)
         "colorContrast", // QTI 3.0 standard (visual.colorContrast)
         "invertColors", // QTI 3.0 standard (visual.invertColors)
-        "theme", // Canonical id
-        "highContrast", // Common variant
-        "customColors", // Common variant
+        "theme", // Canonical id, and this registration's toolId
     ],
     /**
      * Pass 2: Color scheme is always relevant when allowed
@@ -105,51 +80,16 @@ export const themeToolRegistration = {
         return true; // Always show if allowed by orchestrator
     },
     renderToolbar(context, toolbarContext) {
-        const visibility = createScopedVisibilityBinding(this.toolId, toolbarContext);
-        const button = {
-            toolId: this.toolId,
-            label: this.name,
-            icon: typeof this.icon === "function" ? this.icon(context) : this.icon,
-            disabled: false,
-            ariaLabel: "Theme - Change colors and contrast",
-            tooltip: "Theme",
-            onClick: () => toolbarContext.toggleTool(this.toolId),
-            active: visibility.isActive(),
-        };
-        const componentOverrides = toolbarContext.componentOverrides ?? {};
-        const overlay = createToolElement(this.toolId, context, toolbarContext, componentOverrides);
-        overlay.setAttribute("tool-id", visibility.fullToolId);
-        return {
-            toolId: this.toolId,
-            button,
-            elements: [
-                {
-                    element: overlay,
-                    mount: "after-buttons",
-                    shell: {
-                        title: this.name,
-                        draggable: true,
-                        resizable: false,
-                        closeable: true,
-                        initialWidth: 520,
-                        initialHeight: 380,
-                        minWidth: 420,
-                        minHeight: 300,
-                    },
-                },
-            ],
-            sync: () => {
-                syncButtonAndOverlayVisibility({
-                    button,
-                    overlay,
-                    isActive: visibility.isActive,
-                });
-                if (toolbarContext.toolkitCoordinator) {
-                    overlay.toolkitCoordinator = toolbarContext.toolkitCoordinator;
-                }
+        return renderOverlayToolbar(this, context, toolbarContext, {
+            shell: {
+                resizable: false,
+                initialWidth: 520,
+                initialHeight: 380,
+                minWidth: 420,
+                minHeight: 300,
             },
-            subscribeActive: visibility.subscribeActive,
-        };
+            handsOverCoordinator: true,
+        });
     },
 };
 /**
@@ -162,6 +102,8 @@ export const annotationToolbarRegistration = {
     toolId: "annotationToolbar",
     name: "Highlighter",
     description: "Highlight and annotate text",
+    nameKey: "tools.annotationToolbar.name",
+    descriptionKey: "tools.annotationToolbar.description",
     icon: "highlighter",
     activation: "selection-gateway",
     singletonScope: "section",
@@ -181,9 +123,6 @@ export const annotationToolbarRegistration = {
     pnpSupportIds: [
         "highlighting", // QTI 3.0 standard (cognitive.highlighting / reading.wordHighlighting)
         "annotations", // QTI 3.0 standard (cognitive.annotations)
-        "highlighter", // Common variant
-        "textHighlight", // Common variant
-        "annotation", // Common variant
     ],
     /**
      * Pass 2: Annotation is relevant when readable text is present
@@ -217,40 +156,17 @@ export const annotationToolbarRegistration = {
             element.ttsService = current.services.ttsService;
             element.highlightCoordinator =
                 current.services.toolkitCoordinator?.highlightCoordinator ?? null;
+            // The second door onto the dictionaries. The gateway renders these and
+            // knows nothing of what they open; the pairing is composition's, which is
+            // why the list is built in `selection-actions.ts` and not here.
+            element.selectionActions = buildSelectionActions(current.services);
         };
         applyServices(context);
         return { element, sync: applyServices };
     },
     renderToolbar(context, toolbarContext) {
-        const visibility = createScopedVisibilityBinding(this.toolId, toolbarContext);
-        const button = {
-            toolId: this.toolId,
-            label: this.name,
-            icon: typeof this.icon === "function" ? this.icon(context) : this.icon,
-            disabled: false,
-            ariaLabel: "Annotation toolbar - Highlight text",
-            tooltip: "Highlight",
-            onClick: () => toolbarContext.toggleTool(this.toolId),
-            active: visibility.isActive(),
-        };
-        const componentOverrides = toolbarContext.componentOverrides ?? {};
-        const overlay = createToolElement(this.toolId, context, toolbarContext, componentOverrides);
-        overlay.setAttribute("tool-id", visibility.fullToolId);
-        return {
-            toolId: this.toolId,
-            button,
-            elements: [{ element: overlay, mount: "after-buttons" }],
-            sync: () => {
-                syncButtonAndOverlayVisibility({
-                    button,
-                    overlay,
-                    isActive: visibility.isActive,
-                });
-                if (toolbarContext.toolkitCoordinator) {
-                    overlay.toolkitCoordinator = toolbarContext.toolkitCoordinator;
-                }
-            },
-            subscribeActive: visibility.subscribeActive,
-        };
+        return renderOverlayToolbar(this, context, toolbarContext, {
+            handsOverCoordinator: true,
+        });
     },
 };

package/dist/registrations/audio-transcript.js

@@ -144,6 +144,8 @@ export const audioTranscriptRegistration = {
     toolId: AUDIO_TRANSCRIPT_FEATURE_ID,
     name: "Audio Transcript",
     description: "Text of an audio prompt, read before the content it transcribes",
+    nameKey: "tools.audioTranscript.name",
+    descriptionKey: "tools.audioTranscript.description",
     supportedLevels: ["item", "passage"],
     pnpSupportIds: [AUDIO_TRANSCRIPT_FEATURE_ID],
     // No button to press: a transcript is either authored-visible, or granted and
@@ -173,7 +175,11 @@ export const audioTranscriptRegistration = {
         applyTranscript(region, transcript);
         return {
             element: region,
-            ariaLabel: AUDIO_TRANSCRIPT_REGION_LABEL,
+            // `AUDIO_TRANSCRIPT_REGION_LABEL` stays the English source and the
+            // exported constant tests address; the catalog supplies the rendered
+            // label when a host published a provider.
+            ariaLabel: context.services.i18n?.t("tools.audioTranscript.regionA11y") ??
+                AUDIO_TRANSCRIPT_REGION_LABEL,
             // Reads the context it is handed, never the one captured above: on a
             // re-resolve the host's context carries the current card, and a learner must
             // not keep reading the previous item's transcript.

package/dist/registrations/calculator.d.ts

@@ -2,18 +2,22 @@
  * Calculator Tool Registration
  *
  * Registers the calculator tool with support for multiple calculator types
- * (basic, scientific, graphing) via Desmos provider.
+ * (basic, scientific, graphing) through a host-selected provider.
  *
  * Maps to QTI 3.0 standard access features:
  * - calculator (cognitive support)
  * - graphingCalculator (assessment tool)
  */
 import type { ToolRegistration } from "@pie-players/pie-assessment-toolkit/tools/internal";
+import type { ToolProviderConfig } from "@pie-players/pie-assessment-toolkit/tools/internal";
+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;
 /**
  * Calculator tool registration
  *
  * Supports:
- * - Basic, scientific, and graphing calculators via Desmos
+ * - Basic, scientific, and graphing calculators through Desmos, GeoGebra, or Cortex
  * - Context-aware visibility (shows only when math content is detected)
  * - Item level only
  */

package/dist/registrations/calculator.js

@@ -2,7 +2,7 @@
  * Calculator Tool Registration
  *
  * Registers the calculator tool with support for multiple calculator types
- * (basic, scientific, graphing) via Desmos provider.
+ * (basic, scientific, graphing) through a host-selected provider.
  *
  * Maps to QTI 3.0 standard access features:
  * - calculator (cognitive support)
@@ -11,7 +11,45 @@
 import { hasMathContent } from "@pie-players/pie-assessment-toolkit/tools/internal";
 import { createScopedToolId } from "@pie-players/pie-assessment-toolkit/tools/internal";
 import { DesmosToolProvider } from "@pie-players/pie-assessment-toolkit/tools/internal";
+import { CortexToolProvider } from "@pie-players/pie-assessment-toolkit/tools/internal";
+import { GeoGebraToolProvider } from "@pie-players/pie-assessment-toolkit/tools/internal";
 import { createToolElement } from "@pie-players/pie-assessment-toolkit/tools/internal";
+export const DEFAULT_CALCULATOR_PROVIDER_ID = "calculator-desmos";
+export function resolveCalculatorProviderId(config) {
+    const configured = config?.provider?.id;
+    if (configured === undefined || configured === "") {
+        return DEFAULT_CALCULATOR_PROVIDER_ID;
+    }
+    if (configured === "calculator-desmos" ||
+        configured === "calculator-geogebra" ||
+        configured === "calculator-cortex") {
+        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();
+    }
+}
+function getCalculatorInstanceConfig(config) {
+    const theme = config?.theme;
+    return {
+        settings: config?.settings && typeof config.settings === "object"
+            ? { ...config.settings }
+            : {},
+        restrictedMode: config?.restrictedMode === true,
+        locale: typeof config?.locale === "string" ? config.locale : undefined,
+        theme: theme === "light" || theme === "dark" || theme === "auto"
+            ? theme
+            : undefined,
+    };
+}
 // The toolbar parent re-derives `renderedTools` whenever item state changes
 // (e.g. the learner answers a question and `effectiveItem`/`renderContext`
 // recompute). Calculator initialization is expensive (Desmos boot, container
@@ -45,7 +83,9 @@ function setCachedOverlay(coordinator, fullToolId, element) {
     scoped.set(fullToolId, element);
 }
 function normalizeCalculatorType(value) {
-    return value === "basic" || value === "scientific" ? value : null;
+    return value === "basic" || value === "scientific" || value === "graphing"
+        ? value
+        : null;
 }
 function getCalculatorRenderParams(toolbarContext) {
     const params = toolbarContext.getToolRenderParams?.("calculator") ?? {};
@@ -61,15 +101,27 @@ function getCalculatorRenderParams(toolbarContext) {
     return {
         calculatorType,
         availableTypes,
-        displayName: calculatorType === "scientific"
-            ? "Scientific Calculator"
-            : calculatorType === "basic"
-                ? "Basic Calculator"
-                : "Calculator",
+        displayName: toolbarContext.i18n.t(CALCULATOR_NAME_KEYS[calculatorType ?? "untyped"]),
     };
 }
-function applyCalculatorParamsToElement(element, calculatorType, availableTypes) {
+/**
+ * The calculator's displayed name, per host-declared type.
+ *
+ * `untyped` keeps the pre-adoption behaviour of naming the scientific
+ * calculator, which is what the toolbar has always announced when the host
+ * declares no type.
+ */
+const CALCULATOR_NAME_KEYS = {
+    basic: "tools.calculator.nameBasic",
+    scientific: "tools.calculator.nameScientific",
+    graphing: "tools.calculator.nameGraphing",
+    untyped: "tools.calculator.name",
+};
+function applyCalculatorParamsToElement(element, calculatorType, availableTypes, providerId, calculatorConfig) {
     const calculatorElement = element;
+    calculatorElement.providerId = providerId;
+    calculatorElement.calculatorConfig = calculatorConfig;
+    element.setAttribute("provider-id", providerId);
     if (calculatorType) {
         calculatorElement.calculatorType = calculatorType;
         element.setAttribute("calculator-type", calculatorType);
@@ -89,7 +141,7 @@ function applyCalculatorParamsToElement(element, calculatorType, availableTypes)
  * Calculator tool registration
  *
  * Supports:
- * - Basic, scientific, and graphing calculators via Desmos
+ * - Basic, scientific, and graphing calculators through Desmos, GeoGebra, or Cortex
  * - Context-aware visibility (shows only when math content is detected)
  * - Item level only
  */
@@ -97,27 +149,18 @@ 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: {
-        getProviderId: (config) => typeof config?.provider?.id === "string" && config.provider.id.length > 0
-            ? config.provider.id
-            : "calculator-desmos",
-        createProvider: () => new DesmosToolProvider(),
+        getProviderId: resolveCalculatorProviderId,
+        createProvider: createCalculatorToolProvider,
         getInitConfig: (config) => config?.provider?.init ?? {},
         getAuthFetcher: (config) => {
             const runtimeAuthFetcher = config?.provider?.runtime?.authFetcher;
-            if (typeof runtimeAuthFetcher === "function")
-                return runtimeAuthFetcher;
-            return async () => {
-                const response = await fetch("/api/tools/desmos/auth", {
-                    method: "GET",
-                    credentials: "same-origin",
-                });
-                if (!response.ok) {
-                    throw new Error(`Failed to fetch Desmos auth config (${response.status})`);
-                }
-                return (await response.json());
-            };
+            return typeof runtimeAuthFetcher === "function"
+                ? runtimeAuthFetcher
+                : undefined;
         },
         lazy: true,
     },
@@ -125,11 +168,13 @@ export const calculatorToolRegistration = {
     supportedLevels: ["item"],
     // PNP support IDs that enable this tool
     // Maps to QTI 3.0 standard features: calculator, graphingCalculator
+    // A type is not a feature id: `calculatorType` arrives through the host's
+    // render params, so `basicCalculator` / `scientificCalculator` granted the
+    // same untyped calculator these two do and only looked like they selected a
+    // variant.
     pnpSupportIds: [
         "calculator", // QTI 3.0 standard (cognitive.calculator)
         "graphingCalculator", // QTI 3.0 standard (assessment.graphingCalculator)
-        "basicCalculator", // Common variant
-        "scientificCalculator", // Common variant
     ],
     /**
      * Pass 2: Determine if calculator is relevant in this context
@@ -143,6 +188,9 @@ export const calculatorToolRegistration = {
     },
     renderToolbar(context, toolbarContext) {
         const { calculatorType, availableTypes, displayName } = getCalculatorRenderParams(toolbarContext);
+        const calculatorToolConfig = toolbarContext.toolkitCoordinator?.config.tools?.providers?.calculator;
+        const providerId = resolveCalculatorProviderId(calculatorToolConfig);
+        const calculatorConfig = getCalculatorInstanceConfig(calculatorToolConfig);
         const fullToolId = createScopedToolId(this.toolId, toolbarContext.scope.level, toolbarContext.scope.scopeId);
         const componentOverrides = toolbarContext.componentOverrides;
         const cachedOverlay = getCachedOverlay(toolbarContext.toolCoordinator, fullToolId);
@@ -153,19 +201,21 @@ export const calculatorToolRegistration = {
         }
         overlay.setAttribute("tool-id", fullToolId);
         overlay.toolkitCoordinator = toolbarContext.toolkitCoordinator;
-        applyCalculatorParamsToElement(overlay, calculatorType, availableTypes);
-        const openLabel = calculatorType === null
-            ? "Open scientific calculator"
-            : `Open ${displayName.toLowerCase()}`;
-        const closeLabel = calculatorType === null
-            ? "Close scientific calculator"
-            : `Close ${displayName.toLowerCase()}`;
+        applyCalculatorParamsToElement(overlay, calculatorType, availableTypes, providerId, 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; the toolbar used to map it from
+            // the `calculator` toolId, which put a capability name in the generic core.
+            faIconName: "calculator",
             disabled: false,
-            ariaLabel: openLabel,
+            // 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(fullToolId),
@@ -181,16 +231,63 @@ export const calculatorToolRegistration = {
                     element: overlay,
                     mount: "after-buttons",
                     shell: {
-                        title: this.name,
+                        // The variant name the button already carries — "Basic Calculator",
+                        // not the registration's generic one.
+                        title: displayName,
                         draggable: true,
                         resizable: true,
                         closeable: true,
-                        initialWidth: 380,
-                        initialHeight: 420,
+                        /*
+                         * 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: 420,
-                        initialAlign: "bottom-right",
+                        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,
@@ -203,10 +300,12 @@ export const calculatorToolRegistration = {
                 const active = toolbarContext.isToolVisible(fullToolId);
                 button.active = active;
                 button.label = displayName;
-                button.ariaLabel = active ? closeLabel : openLabel;
-                button.tooltip = active
-                    ? `Close ${displayName.toLowerCase()}`
-                    : 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.
+                button.ariaLabel = displayName;
+                button.tooltip = displayName;
                 if (lastVisibleState !== active) {
                     overlay.visible = active;
                     lastVisibleState = active;
@@ -214,7 +313,7 @@ export const calculatorToolRegistration = {
                 if (overlay.toolkitCoordinator !== toolbarContext.toolkitCoordinator) {
                     overlay.toolkitCoordinator = toolbarContext.toolkitCoordinator;
                 }
-                applyCalculatorParamsToElement(overlay, calculatorType, availableTypes);
+                applyCalculatorParamsToElement(overlay, calculatorType, availableTypes, providerId, calculatorConfig);
             },
             subscribeActive: (callback) => {
                 if (!toolbarContext.subscribeVisibility)

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

@@ -0,0 +1,75 @@
+/**
+ * Dictionary Tool Registrations
+ *
+ * Word lookup and picture (symbol) lookup, each a floating panel opened from the
+ * toolbar.
+ *
+ * Neither declares a universal support id. A dictionary is a granted accommodation,
+ * not a universal affordance: on a vocabulary item it is construct-relevant, so
+ * handing it to every learner by default would change what the item measures. A
+ * programme grants it through the PNP like any other accommodation.
+ *
+ * Both panels also accept a `term` from whatever selection affordance a host offers,
+ * but neither depends on one. A sighted keyboard-only learner cannot originate a text
+ * selection in non-editable content — Chromium does not extend one with Shift+Arrow
+ * there without caret browsing, an OS toggle absent on mobile — so a selection-only
+ * dictionary is unreachable for them. The panel's own field is the keyboard route.
+ */
+import type { ToolRegistration } from "@pie-players/pie-assessment-toolkit/tools/internal";
+/**
+ * What distinguishes one dictionary capability from another.
+ *
+ * A dictionary's language belongs to the learner, not to the content: the learner who
+ * needs a Spanish gloss is reading an English passage. So a deployment that offers two
+ * languages at once composes two capabilities, each granted on its own through the PNP,
+ * rather than one capability that follows whatever the section was authored in. That is
+ * also how the delivery systems PIE is measured against ship it — English Dictionary and
+ * Spanish Dictionary as two entries a programme grants separately.
+ *
+ * Catalog keys are derived from `toolId` (`tools.<toolId>.name` and so on), which holds for
+ * every packaged variant. A host composing a variant against its own catalog passes
+ * `messageKeyPrefix`; a key that does not resolve falls back to `name` and `description`,
+ * so a host catalog that lacks one is a plain label rather than a broken button.
+ */
+export interface DictionaryVariantOptions {
+    /** Capability id, unique per language. Defaults to the base tool's id. */
+    toolId?: string;
+    name?: string;
+    description?: string;
+    /** Catalog prefix for this variant's strings. Defaults to `tools.<toolId>`. */
+    messageKeyPrefix?: string;
+    /** PNP ids that grant this variant. A language variant needs its own. */
+    pnpSupportIds?: string[];
+    /**
+     * The corpus language this capability looks words up in, as a BCP-47 tag.
+     *
+     * Sent with every lookup, outranking the toolbar's content-alternate language and
+     * outranked by a language the host names in this tool's render params. Absent on the
+     * base capabilities, which follow the content.
+     */
+    lookupLanguage?: string;
+}
+/**
+ * Dictionary tool registration
+ *
+ * Word lookup from a host-supplied service, in one language. Call this again with another
+ * `toolId`, `pnpSupportIds` and `lookupLanguage` to offer a second language beside it.
+ */
+export declare function createDictionaryToolRegistration(options?: DictionaryVariantOptions): ToolRegistration;
+/** The content-following dictionary every deployment gets. */
+export declare const dictionaryToolRegistration: ToolRegistration;
+/**
+ * Picture Dictionary tool registration
+ *
+ * Symbol or picture lookup from a host-supplied service. Sized wider than the word
+ * dictionary because its results are a grid rather than a column of text.
+ */
+export declare function createPictureDictionaryToolRegistration(options?: DictionaryVariantOptions): ToolRegistration;
+/** The content-following picture dictionary every deployment gets. */
+export declare const pictureDictionaryToolRegistration: ToolRegistration;
+/**
+ * Spanish variants, packaged because a Spanish gloss for English content is a named
+ * accommodation rather than a hypothetical. Neither appears unless a PNP grants it.
+ */
+export declare const spanishDictionaryToolRegistration: ToolRegistration;
+export declare const spanishPictureDictionaryToolRegistration: ToolRegistration;