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

package/dist/registrations/dictionary-tools.js

@@ -0,0 +1,235 @@
+/**
+ * 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 { createScopedVisibilityBinding, createToolElement, hasReadableText, syncButtonAndOverlayVisibility, } from "@pie-players/pie-assessment-toolkit/tools/internal";
+/**
+ * Apply the host's per-tool render params to the panel.
+ *
+ * `lookup` wins over `endpoint` when a host supplies both, matching the element's own
+ * precedence: a host that already has a client should not also have to describe its
+ * HTTP shape. Absent both, the panel renders its unconfigured state — PIE ships no
+ * dictionary endpoint, because the corpus behind one is licensed per programme.
+ *
+ * An `endpoint` alone is the whole configuration for the common case: the panel calls
+ * it on the assessment's own session, so a route already behind that session answers
+ * without a token. `headers` and `credentials` are the seam for a host authorising some
+ * other way, and neither is required.
+ */
+function applyLookupParams(element, toolId, toolbarContext, 
+/** A language variant's own corpus language; see {@link DictionaryVariantOptions}. */
+lookupLanguage) {
+    const params = toolbarContext.getToolRenderParams?.(toolId) ?? {};
+    if (typeof params.endpoint === "string")
+        element.endpoint = params.endpoint;
+    if (typeof params.lookup === "function")
+        element.lookup = params.lookup;
+    if (typeof params.headers === "function")
+        element.headers = params.headers;
+    if (typeof params.credentials === "string")
+        element.credentials = params.credentials;
+    // The selection door: a gateway acting on the learner's selection requests this
+    // tool with the words in `term`, and the toolbar layers that over the host's own
+    // params. The toolbar stamps every request with a neutral `toolRequestId` — core
+    // names no tool's concepts — and this layer, which knows both, hands it to the panel
+    // as the identity of its term. That is what makes reapplying an unchanged term on a
+    // later sync free while a second request for the same word still re-runs.
+    if (typeof params.term === "string" && params.term)
+        element.term = params.term;
+    if (typeof params.toolRequestId === "string" ||
+        typeof params.toolRequestId === "number") {
+        element.termRequestId = params.toolRequestId;
+    }
+    // Resolution order: what the host named for this tool, then the capability's own
+    // corpus language if it is a language variant, then the toolbar's scope. A variant
+    // exists precisely to look words up in a language the surrounding content is not in —
+    // a Spanish gloss for an English passage — so its language outranks the scope's, and a
+    // host that names one anyway still wins.
+    const language = typeof params.language === "string"
+        ? params.language
+        : (lookupLanguage ?? toolbarContext.language);
+    if (typeof language === "string" && language)
+        element.language = language;
+}
+function renderDictionaryPanel(args) {
+    const { registration, context, toolbarContext } = args;
+    const visibility = createScopedVisibilityBinding(registration.toolId, toolbarContext);
+    const button = {
+        toolId: registration.toolId,
+        label: registration.name,
+        icon: typeof registration.icon === "function"
+            ? registration.icon(context)
+            : registration.icon,
+        disabled: false,
+        ariaLabel: toolbarContext.i18n.t(args.buttonA11yKey),
+        tooltip: toolbarContext.i18n.t(args.tooltipKey),
+        onClick: () => toolbarContext.toggleTool(registration.toolId),
+        active: visibility.isActive(),
+    };
+    const componentOverrides = toolbarContext.componentOverrides ??
+        {};
+    const overlay = createToolElement(registration.toolId, context, toolbarContext, componentOverrides);
+    overlay.setAttribute("tool-id", visibility.fullToolId);
+    applyLookupParams(overlay, registration.toolId, toolbarContext, args.lookupLanguage);
+    return {
+        toolId: registration.toolId,
+        button,
+        elements: [
+            {
+                element: overlay,
+                mount: "after-buttons",
+                shell: {
+                    title: toolbarContext.i18n.t(args.shellTitleKey),
+                    draggable: true,
+                    resizable: true,
+                    closeable: true,
+                    initialWidth: args.initialWidth,
+                    initialHeight: args.initialHeight,
+                    minWidth: args.minWidth,
+                    minHeight: args.minHeight,
+                },
+            },
+        ],
+        // Re-read params on sync rather than closing over them: a host calling
+        // `updateToolConfig` mid-session changes the endpoint without remounting, and a
+        // remount would discard the learner's current lookup.
+        sync: () => {
+            syncButtonAndOverlayVisibility({
+                button,
+                overlay,
+                isActive: visibility.isActive,
+            });
+            applyLookupParams(overlay, registration.toolId, toolbarContext, args.lookupLanguage);
+        },
+        subscribeActive: visibility.subscribeActive,
+    };
+}
+/**
+ * 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 function createDictionaryToolRegistration(options = {}) {
+    const toolId = options.toolId ?? "dictionary";
+    const prefix = options.messageKeyPrefix ?? `tools.${toolId}`;
+    return {
+        toolId,
+        name: options.name ?? "Dictionary",
+        description: options.description ?? "Look up word definitions",
+        nameKey: `${prefix}.name`,
+        descriptionKey: `${prefix}.description`,
+        icon: "book-open",
+        // Text can appear at any of these; the panel itself floats at section scope.
+        supportedLevels: ["section", "item", "passage", "rubric"],
+        // PNP support IDs
+        // Maps to AfA PNP 3.0 / QTI 3.0 dictionary support, plus the common variants a
+        // host profile is likely to carry.
+        pnpSupportIds: options.pnpSupportIds ?? [
+            "dictionary", // Canonical id
+            "englishDictionary", // Common variant
+            "glossary", // Common variant
+            "definitions", // Common variant
+        ],
+        /** Pass 2: a dictionary is relevant wherever there is text to look words up from. */
+        isVisibleInContext(context) {
+            return hasReadableText(context);
+        },
+        renderToolbar(context, toolbarContext) {
+            return renderDictionaryPanel({
+                registration: this,
+                context,
+                toolbarContext,
+                buttonA11yKey: `${prefix}.buttonA11y`,
+                tooltipKey: `${prefix}.tooltip`,
+                shellTitleKey: `${prefix}.name`,
+                lookupLanguage: options.lookupLanguage,
+                initialWidth: 420,
+                initialHeight: 380,
+                minWidth: 300,
+                minHeight: 240,
+            });
+        },
+    };
+}
+/** The content-following dictionary every deployment gets. */
+export const dictionaryToolRegistration = createDictionaryToolRegistration();
+/**
+ * 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 function createPictureDictionaryToolRegistration(options = {}) {
+    const toolId = options.toolId ?? "pictureDictionary";
+    const prefix = options.messageKeyPrefix ?? `tools.${toolId}`;
+    return {
+        toolId,
+        name: options.name ?? "Picture Dictionary",
+        description: options.description ?? "Look up pictures for words",
+        nameKey: `${prefix}.name`,
+        descriptionKey: `${prefix}.description`,
+        icon: "photo",
+        supportedLevels: ["section", "item", "passage", "rubric"],
+        // PNP support IDs
+        // AfA PNP 3.0 names an illustrated equivalent of a glossary; the variants cover
+        // what host profiles call it in practice.
+        pnpSupportIds: options.pnpSupportIds ?? [
+            "pictureDictionary", // Canonical id
+            "illustratedGlossary", // Common variant
+            "symbolDictionary", // Common variant
+            "pictureSupport", // Common variant
+        ],
+        isVisibleInContext(context) {
+            return hasReadableText(context);
+        },
+        renderToolbar(context, toolbarContext) {
+            return renderDictionaryPanel({
+                registration: this,
+                context,
+                toolbarContext,
+                buttonA11yKey: `${prefix}.buttonA11y`,
+                tooltipKey: `${prefix}.tooltip`,
+                shellTitleKey: `${prefix}.name`,
+                lookupLanguage: options.lookupLanguage,
+                initialWidth: 520,
+                initialHeight: 460,
+                minWidth: 320,
+                minHeight: 280,
+            });
+        },
+    };
+}
+/** The content-following picture dictionary every deployment gets. */
+export const pictureDictionaryToolRegistration = createPictureDictionaryToolRegistration();
+/**
+ * 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 const spanishDictionaryToolRegistration = createDictionaryToolRegistration({
+    toolId: "dictionarySpanish",
+    name: "Spanish Dictionary",
+    description: "Look up word definitions in Spanish",
+    pnpSupportIds: ["spanishDictionary", "spanishGlossary"],
+    lookupLanguage: "es",
+});
+export const spanishPictureDictionaryToolRegistration = createPictureDictionaryToolRegistration({
+    toolId: "pictureDictionarySpanish",
+    name: "Spanish Picture Dictionary",
+    description: "Look up pictures for words in Spanish",
+    pnpSupportIds: ["spanishPictureDictionary", "spanishIllustratedGlossary"],
+    lookupLanguage: "es",
+});

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

@@ -18,10 +18,3 @@ import type { ToolRegistration } from "@pie-players/pie-assessment-toolkit/tools
  * Only appears on multiple-choice style questions.
  */
 export declare const answerEliminatorToolRegistration: ToolRegistration;
-/**
- * Highlighter tool registration
- *
- * Allows students to highlight text in passages and questions.
- * Appears on items with readable text content.
- */
-export declare const highlighterToolRegistration: ToolRegistration;

package/dist/registrations/interaction-tools.js

@@ -23,6 +23,8 @@ export const answerEliminatorToolRegistration = {
     toolId: "answerEliminator",
     name: "Answer Eliminator",
     description: "Strike through answer choices",
+    nameKey: "tools.answerEliminator.name",
+    descriptionKey: "tools.answerEliminator.description",
     icon: "strikethrough",
     // Answer eliminator appears at item level only
     supportedLevels: ["item"],
@@ -52,8 +54,8 @@ export const answerEliminatorToolRegistration = {
             label: this.name,
             icon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="20" height="20" fill="currentColor" aria-hidden="true"><path d="M19,3H16.3H7.7H5A2,2 0 0,0 3,5V7.7V16.4V19A2,2 0 0,0 5,21H7.7H16.4H19A2,2 0 0,0 21,19V16.3V7.7V5A2,2 0 0,0 19,3M15.6,17L12,13.4L8.4,17L7,15.6L10.6,12L7,8.4L8.4,7L12,10.6L15.6,7L17,8.4L13.4,12L17,15.6L15.6,17Z"/></svg>',
             disabled: false,
-            ariaLabel: "Answer eliminator - Strike through choices",
-            tooltip: "Strike Through",
+            ariaLabel: toolbarContext.i18n.t("tools.answerEliminator.buttonA11y"),
+            tooltip: toolbarContext.i18n.t("tools.answerEliminator.tooltip"),
             onClick: () => toolbarContext.toggleTool(this.toolId),
             active: visibility.isActive(),
         };
@@ -83,61 +85,3 @@ export const answerEliminatorToolRegistration = {
         };
     },
 };
-/**
- * Highlighter tool registration
- *
- * Allows students to highlight text in passages and questions.
- * Appears on items with readable text content.
- */
-export const highlighterToolRegistration = {
-    toolId: "highlighter",
-    name: "Highlighter",
-    description: "Highlight text",
-    icon: "highlighter",
-    activation: "toolbar-toggle",
-    // Highlighter appears at passage, rubric, item, and element levels
-    supportedLevels: ["passage", "rubric", "item", "element"],
-    // PNP support IDs
-    pnpSupportIds: ["highlighter", "textHighlight", "annotation"],
-    /**
-     * Pass 2: Highlighter is relevant when readable text is available
-     */
-    isVisibleInContext(context) {
-        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: "Highlighter - 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,
-                    onActiveChange: (active) => {
-                        overlay.enabled = active;
-                    },
-                });
-                if (toolbarContext.ttsService) {
-                    overlay.ttsService = toolbarContext.ttsService;
-                }
-            },
-            subscribeActive: visibility.subscribeActive,
-        };
-    },
-};

package/dist/registrations/measurement-tools.js

@@ -10,6 +10,7 @@
 import { hasMathContent } from "@pie-players/pie-assessment-toolkit/tools/internal";
 import { createToolElement, } from "@pie-players/pie-assessment-toolkit/tools/internal";
 import { applyOverlaySurface, createScopedVisibilityBinding, syncButtonAndOverlayVisibility, } from "@pie-players/pie-assessment-toolkit/tools/internal";
+import { renderOverlayToolbar } from "./overlay-toolbar-render.js";
 /**
  * Ruler tool registration
  *
@@ -20,6 +21,8 @@ export const rulerToolRegistration = {
     toolId: "ruler",
     name: "Ruler",
     description: "On-screen ruler for measurements",
+    nameKey: "tools.ruler.name",
+    descriptionKey: "tools.ruler.description",
     icon: "ruler",
     // Ruler typically appears at section/item/element level
     supportedLevels: ["section", "item", "element"],
@@ -36,37 +39,10 @@ export const rulerToolRegistration = {
         return hasMathContent(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: "Open ruler tool",
-            tooltip: "Ruler",
-            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,
+        });
     },
 };
 /**
@@ -79,6 +55,8 @@ export const protractorToolRegistration = {
     toolId: "protractor",
     name: "Protractor",
     description: "On-screen protractor for angle measurements",
+    nameKey: "tools.protractor.name",
+    descriptionKey: "tools.protractor.description",
     icon: "protractor",
     // Protractor typically appears at section/item/element level
     supportedLevels: ["section", "item", "element"],
@@ -95,36 +73,9 @@ export const protractorToolRegistration = {
         return hasMathContent(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: "Open protractor tool",
-            tooltip: "Protractor",
-            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,
+        });
     },
 };

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

@@ -0,0 +1,43 @@
+/**
+ * The `renderToolbar` shape shared by every packaged capability that puts one
+ * overlay behind one toolbar button.
+ *
+ * Seven registrations had this inline. What actually varies between them is the
+ * three options below and nothing else: whether the overlay paints its own chrome
+ * or takes a draggable window, that window's size, and whether the overlay needs
+ * the coordinator re-handed on each sync. Everything else — the visibility
+ * binding, the button, the component-override lookup, the `tool-id` attribute, the
+ * sync — was identical, which is why one rule landing in three spellings was
+ * possible: the shell title was `resolveToolRegistrationName` in two files,
+ * `displayName` in a third and a raw `t(key)` in a fourth.
+ *
+ * Catalog keys are derived from `toolId`, which held at all seven sites:
+ * `tools.<toolId>.buttonA11y` and `tools.<toolId>.tooltip`. A capability needing a
+ * different prefix — the dictionary variants, which compose several capabilities
+ * off one element — keeps its own renderer.
+ */
+import { type ToolContext, type ToolRegistration, type ToolToolbarRenderResult, type ToolbarContext } from "@pie-players/pie-assessment-toolkit/tools/internal";
+/** A window's geometry. Absent for overlays that paint their own chrome. */
+export interface OverlayToolShell {
+    resizable: boolean;
+    initialWidth: number;
+    initialHeight: number;
+    minWidth: number;
+    minHeight: number;
+}
+export interface RenderOverlayToolbarOptions {
+    /**
+     * `"frameless"` for an overlay that draws its own surface — a ruler or a line
+     * reader sits on the content rather than in a panel.
+     */
+    surface?: "frameless";
+    /** Present when the capability opens in a draggable, closeable window. */
+    shell?: OverlayToolShell;
+    /**
+     * Re-hand the toolkit coordinator on every sync. Overlays that take part in
+     * stacking or visibility restore need it; the two that only render their own
+     * model do not, and giving them a property they ignore is not free to assume.
+     */
+    handsOverCoordinator?: boolean;
+}
+export declare function renderOverlayToolbar(registration: ToolRegistration, context: ToolContext, toolbarContext: ToolbarContext, options?: RenderOverlayToolbarOptions): ToolToolbarRenderResult;

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

@@ -0,0 +1,75 @@
+/**
+ * The `renderToolbar` shape shared by every packaged capability that puts one
+ * overlay behind one toolbar button.
+ *
+ * Seven registrations had this inline. What actually varies between them is the
+ * three options below and nothing else: whether the overlay paints its own chrome
+ * or takes a draggable window, that window's size, and whether the overlay needs
+ * the coordinator re-handed on each sync. Everything else — the visibility
+ * binding, the button, the component-override lookup, the `tool-id` attribute, the
+ * sync — was identical, which is why one rule landing in three spellings was
+ * possible: the shell title was `resolveToolRegistrationName` in two files,
+ * `displayName` in a third and a raw `t(key)` in a fourth.
+ *
+ * Catalog keys are derived from `toolId`, which held at all seven sites:
+ * `tools.<toolId>.buttonA11y` and `tools.<toolId>.tooltip`. A capability needing a
+ * different prefix — the dictionary variants, which compose several capabilities
+ * off one element — keeps its own renderer.
+ */
+import { applyOverlaySurface, createScopedVisibilityBinding, createToolElement, resolveToolRegistrationName, syncButtonAndOverlayVisibility, } from "@pie-players/pie-assessment-toolkit/tools/internal";
+export function renderOverlayToolbar(registration, context, toolbarContext, options = {}) {
+    const { toolId } = registration;
+    const visibility = createScopedVisibilityBinding(toolId, toolbarContext);
+    const button = {
+        toolId,
+        label: registration.name,
+        icon: typeof registration.icon === "function"
+            ? registration.icon(context)
+            : registration.icon,
+        disabled: false,
+        ariaLabel: toolbarContext.i18n.t(`tools.${toolId}.buttonA11y`),
+        tooltip: toolbarContext.i18n.t(`tools.${toolId}.tooltip`),
+        onClick: () => toolbarContext.toggleTool(toolId),
+        active: visibility.isActive(),
+    };
+    const componentOverrides = toolbarContext.componentOverrides ??
+        {};
+    const overlay = createToolElement(toolId, context, toolbarContext, componentOverrides);
+    overlay.setAttribute("tool-id", visibility.fullToolId);
+    if (options.surface === "frameless") {
+        applyOverlaySurface(overlay, "frameless");
+    }
+    return {
+        toolId,
+        button,
+        elements: [
+            {
+                element: overlay,
+                mount: "after-buttons",
+                ...(options.shell
+                    ? {
+                        shell: {
+                            // Through `nameKey`, so a window's title tracks the interface
+                            // locale the way its button already does.
+                            title: resolveToolRegistrationName(registration, toolbarContext.i18n),
+                            draggable: true,
+                            closeable: true,
+                            ...options.shell,
+                        },
+                    }
+                    : {}),
+            },
+        ],
+        sync: () => {
+            syncButtonAndOverlayVisibility({
+                button,
+                overlay,
+                isActive: visibility.isActive,
+            });
+            if (options.handsOverCoordinator && toolbarContext.toolkitCoordinator) {
+                overlay.toolkitCoordinator = toolbarContext.toolkitCoordinator;
+            }
+        },
+        subscribeActive: visibility.subscribeActive,
+    };
+}

package/dist/registrations/selection-actions.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Which capabilities appear as actions on the learner's current selection.
+ *
+ * The one place that pairs a selection gateway to the tools it can open. The gateway
+ * renders what it is handed and names nothing; the tools know nothing about
+ * selections. Composition is the only layer allowed to know both, which is why this
+ * list lives here rather than in either of them.
+ *
+ * A selection is a shortcut, never the only way in. Chromium does not extend a
+ * selection with Shift+Arrow in non-editable content unless caret browsing is on —
+ * an OS toggle that does not exist on mobile — so a sighted keyboard-only learner
+ * cannot originate one at all. Every tool named here also opens from the toolbar and
+ * carries its own term field.
+ */
+import type { ToolSelectionAction, ToolSurfaceServices } from "@pie-players/pie-assessment-toolkit/tools/internal";
+/**
+ * Actions for the gateway to render, given the services it was handed.
+ *
+ * Rebuilt on every sync rather than captured once: a host calling
+ * `updateAssessment` mid-session swaps the coordinator without remounting the
+ * gateway, and an action closing over the previous one would open a tool in a
+ * session the learner has left.
+ */
+export declare function buildSelectionActions(services: ToolSurfaceServices): ToolSelectionAction[];

package/dist/registrations/selection-actions.js

@@ -0,0 +1,73 @@
+/**
+ * Which capabilities appear as actions on the learner's current selection.
+ *
+ * The one place that pairs a selection gateway to the tools it can open. The gateway
+ * renders what it is handed and names nothing; the tools know nothing about
+ * selections. Composition is the only layer allowed to know both, which is why this
+ * list lives here rather than in either of them.
+ *
+ * A selection is a shortcut, never the only way in. Chromium does not extend a
+ * selection with Shift+Arrow in non-editable content unless caret browsing is on —
+ * an OS toggle that does not exist on mobile — so a sighted keyboard-only learner
+ * cannot originate one at all. Every tool named here also opens from the toolbar and
+ * carries its own term field.
+ */
+import { resolveFallbackToolIcon } from "@pie-players/pie-assessment-toolkit/tools/internal";
+function asRequestCapable(coordinator) {
+    const candidate = coordinator;
+    if (typeof candidate?.canRequestTool !== "function")
+        return null;
+    if (typeof candidate.requestTool !== "function")
+        return null;
+    return candidate;
+}
+const SELECTION_ACTION_SPECS = [
+    {
+        toolId: "dictionary",
+        label: "Look up selected text in dictionary",
+        tooltip: "Look up",
+        icon: "book-open",
+    },
+    {
+        toolId: "pictureDictionary",
+        label: "Show pictures for selected text",
+        tooltip: "Show pictures",
+        icon: "photo",
+    },
+];
+/**
+ * Actions for the gateway to render, given the services it was handed.
+ *
+ * Rebuilt on every sync rather than captured once: a host calling
+ * `updateAssessment` mid-session swaps the coordinator without remounting the
+ * gateway, and an action closing over the previous one would open a tool in a
+ * session the learner has left.
+ */
+export function buildSelectionActions(services) {
+    const coordinator = asRequestCapable(services.toolkitCoordinator);
+    if (!coordinator)
+        return [];
+    return SELECTION_ACTION_SPECS.map((spec) => {
+        const iconSvg = resolveFallbackToolIcon(spec.icon) ?? undefined;
+        return {
+            id: spec.toolId,
+            label: spec.label,
+            tooltip: spec.tooltip,
+            iconSvg,
+            // Asked per selection. A tool the PNP does not grant, or that no toolbar in
+            // this section hosts, is absent rather than present and inert.
+            isAvailable: () => coordinator.canRequestTool(spec.toolId),
+            run: (selection) => {
+                const term = selection.text.trim();
+                if (!term)
+                    return;
+                // Both panels read the selected text from `term`. No level is named, so the
+                // request takes whichever toolbar hosts the tool, preferring section scope.
+                coordinator.requestTool({
+                    toolId: spec.toolId,
+                    params: { term },
+                });
+            },
+        };
+    });
+}