@pie-players/pie-default-tool-loaders 0.3.64 → 0.3.65

package/README.md

@@ -1,24 +1,97 @@
 # PIE Default Tool Loaders
 
-Default lazy module loader mappings for built-in PIE assessment tools.
+Composition layer for the packaged PIE assessment tools: which capabilities exist
+in a deployment, and how a program tiers them.
 
-This package intentionally owns concrete `pie-tool-*` dependencies so toolkit core can remain dependency-light and cycle-safe.
+It owns the concrete `pie-tool-*` dependencies so toolkit core can stay
+dependency-light and cycle-safe, and it is the layer above core — core knows
+`featureId`, placement levels, activation kinds and precedence rules, and knows
+no capability ids.
+
+It owns four things, all answers to "which capabilities does this deployment have
+and how does the program tier them":
+
+| Export | What it decides |
+| --- | --- |
+| `PACKAGED_TOOL_REGISTRATIONS`, `createPackagedToolRegistry`, `registerPackagedTools` | Which capabilities exist, and their toolbar and surface contracts |
+| `PACKAGED_TOOL_TAG_MAP` | Which custom element each one renders as |
+| `PACKAGED_TOOL_PLACEMENT`, `SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT`, `PACKAGED_TOOL_ORDER` | Where they appear and in what order |
+| `UNIVERSAL_SUPPORTS_PRESET`, `createUniversalPersonalNeedsProfile` | Which of their support ids the program grants to everyone |
+| `DEFAULT_TOOL_MODULE_LOADERS`, `registerSectionToolModuleLoaders` | When each one's bundle loads |
+
+The individual registrations are exported too, so a host can compose its own set
+rather than take the packaged one whole.
 
 ## Usage
 
 ```ts
-import { createDefaultToolRegistry } from "@pie-players/pie-assessment-toolkit";
 import {
+	createPackagedToolRegistry,
 	DEFAULT_TOOL_MODULE_LOADERS,
-	registerSectionToolModuleLoaders,
 } from "@pie-players/pie-default-tool-loaders";
 
-// Full default loaders (item + section tools)
-const registry = createDefaultToolRegistry({
+// The packaged capability set, lazily loaded.
+const registry = createPackagedToolRegistry({
 	toolModuleLoaders: DEFAULT_TOOL_MODULE_LOADERS,
 });
+```
+
+`createDefaultToolRegistry()` in the toolkit is the other end of that choice: it
+builds an empty registry, and a host composing its own set registers into it.
 
-// Section-only loaders (for section toolbar bootstrap points)
+```ts
+import { createDefaultToolRegistry } from "@pie-players/pie-assessment-toolkit";
+import {
+	calculatorToolRegistration,
+	registerSectionToolModuleLoaders,
+	ttsToolRegistration,
+} from "@pie-players/pie-default-tool-loaders";
+
+const registry = createDefaultToolRegistry({
+	registrations: [calculatorToolRegistration, ttsToolRegistration],
+});
+// Section-only loaders, for section toolbar bootstrap points.
 registerSectionToolModuleLoaders(registry);
 ```
 
+## Accommodations are not in the packaged set
+
+A capability declaring `requiresAuthoredContent` is absent from
+`PACKAGED_TOOL_REGISTRATIONS` and its support ids from
+`UNIVERSAL_SUPPORTS_PRESET`. Signing is the shipped example: install
+`@pie-players/pie-tool-sign-language` and register it, which is the same two lines
+a host writes for a capability of its own.
+
+```ts
+import { signLanguageRegistration } from "@pie-players/pie-tool-sign-language";
+
+registry.register(signLanguageRegistration);
+```
+
+## Universal supports preset
+
+`createUniversalPersonalNeedsProfile()` builds a `PersonalNeedsProfile` granting
+`UNIVERSAL_SUPPORTS_PRESET` — the support ids the packaged tool set treats as
+universal features.
+
+```ts
+import { createUniversalPersonalNeedsProfile } from "@pie-players/pie-default-tool-loaders";
+
+const section = {
+	...authoredSection,
+	personalNeedsProfile: createUniversalPersonalNeedsProfile(),
+};
+```
+
+The core ships no populated default — `createEmptyPersonalNeedsProfile()` in
+`@pie-players/pie-assessment-toolkit` grants nothing. Which capabilities a
+deployment grants by default is a property of the program, not of a capability:
+TTS is a universal feature in one program and a documented accommodation in
+another. So the preset is data to adopt, extend or replace alongside the district
+and test-administration configuration, and it deliberately excludes any
+capability that declares a content dependency.
+
+A section carrying no profile is left alone. `pnpEnforcement` auto-detection
+engages on real host policy material, so supplying no profile means placement
+alone decides which tools appear.
+

package/dist/index.d.ts

@@ -1,3 +1,14 @@
+export { UNIVERSAL_SUPPORTS_PRESET, createUniversalPersonalNeedsProfile, } from "./universal-supports.js";
+export type { PackagedToolRegistryOptions, RegisterPackagedToolsOptions, } from "./packaged-tool-registry.js";
+export { createPackagedToolRegistry, PACKAGED_TOOL_ORDER, PACKAGED_TOOL_REGISTRATIONS, registerPackagedTools, } from "./packaged-tool-registry.js";
+export { PACKAGED_TOOL_TAG_MAP } from "./tool-tag-map.js";
+export { PACKAGED_TOOL_PLACEMENT, SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT, } from "./tool-placement.js";
+export { annotationToolbarRegistration, lineReaderToolRegistration, themeToolRegistration, } from "./registrations/accessibility-tools.js";
+export { calculatorToolRegistration } from "./registrations/calculator.js";
+export { answerEliminatorToolRegistration, highlighterToolRegistration, } 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 type ToolModuleLoader = () => Promise<unknown>;
 export interface ToolRegistryLike {
     setToolModuleLoaders(loaders: Partial<Record<string, ToolModuleLoader>>): void;

package/dist/index.js

@@ -1,3 +1,15 @@
+export { UNIVERSAL_SUPPORTS_PRESET, createUniversalPersonalNeedsProfile, } from "./universal-supports.js";
+export { createPackagedToolRegistry, PACKAGED_TOOL_ORDER, PACKAGED_TOOL_REGISTRATIONS, registerPackagedTools, } from "./packaged-tool-registry.js";
+export { PACKAGED_TOOL_TAG_MAP } from "./tool-tag-map.js";
+export { PACKAGED_TOOL_PLACEMENT, SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT, } from "./tool-placement.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 { calculatorToolRegistration } from "./registrations/calculator.js";
+export { answerEliminatorToolRegistration, highlighterToolRegistration, } 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";
 const loadSideEffectModule = (load) => load().then(() => undefined);
 function loadCalculatorModule() {
     if (typeof globalThis !== "undefined" &&

package/dist/packaged-tool-registry.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The packaged PIE capability set, and the registry factory that composes it.
+ *
+ * This is the composition layer: which capabilities exist in a deployment. It
+ * lived in `@pie-players/pie-assessment-toolkit`, where eleven concrete
+ * registrations inside the generic package meant the policy and registry core
+ * knew every capability by name and a host could not contribute one without a PR
+ * against that package.
+ *
+ * The toolkit still owns `ToolRegistry`, `createDefaultToolRegistry` (which
+ * builds an empty registry), the registration contract and the toolbar helpers.
+ * It knows `featureId`, placement levels, activation kinds and precedence rules,
+ * and knows no capability ids.
+ */
+import { ToolRegistry, type ToolComponentFactory, type ToolComponentFactoryMap, type ToolModuleLoader, type ToolRegistration, type ToolTagMap } from "@pie-players/pie-assessment-toolkit/tools/internal";
+export declare const PACKAGED_TOOL_REGISTRATIONS: readonly [ToolRegistration, ToolRegistration, ToolRegistration, ToolRegistration, ToolRegistration, ToolRegistration, ToolRegistration, ToolRegistration, ToolRegistration, ToolRegistration, ToolRegistration];
+export interface PackagedToolRegistryOptions {
+    /**
+     * Override packaged registrations by toolId. Highest-precedence extension
+     * point.
+     */
+    overrides?: Partial<Record<string, ToolRegistration>>;
+    /** Override or extend the packaged element tag mapping. */
+    toolTagMap?: Partial<ToolTagMap>;
+    /** Override the component factory globally or per tool. */
+    toolComponentFactory?: ToolComponentFactory;
+    toolComponentFactories?: Partial<ToolComponentFactoryMap>;
+    /** Lazy module loaders keyed by toolId. */
+    toolModuleLoaders?: Partial<Record<string, ToolModuleLoader>>;
+    /** Restrict registration to specific packaged tool ids. */
+    toolIds?: string[];
+}
+export interface RegisterPackagedToolsOptions {
+    toolIds?: string[];
+    applyOverrides?: (registration: ToolRegistration) => ToolRegistration;
+}
+/**
+ * Register packaged PIE capabilities onto an existing registry.
+ */
+export declare function registerPackagedTools(registry: ToolRegistry, options?: RegisterPackagedToolsOptions): void;
+/**
+ * Create a registry holding the packaged PIE capabilities.
+ *
+ * The tag map is installed through `setComponentOverrides` rather than read from
+ * a core default, so a registry composed without it resolves no packaged tags —
+ * which is the point: core no longer carries the catalogue.
+ */
+export declare function createPackagedToolRegistry(options?: PackagedToolRegistryOptions): ToolRegistry;
+/**
+ * Render order when several capabilities are visible at once.
+ */
+export declare const PACKAGED_TOOL_ORDER: readonly ["theme", "calculator", "textToSpeech", "lineReader", "annotationToolbar", "highlighter", "answerEliminator", "ruler", "protractor", "graph", "periodicTable"];

package/dist/packaged-tool-registry.js

@@ -0,0 +1,96 @@
+/**
+ * The packaged PIE capability set, and the registry factory that composes it.
+ *
+ * This is the composition layer: which capabilities exist in a deployment. It
+ * lived in `@pie-players/pie-assessment-toolkit`, where eleven concrete
+ * registrations inside the generic package meant the policy and registry core
+ * knew every capability by name and a host could not contribute one without a PR
+ * against that package.
+ *
+ * The toolkit still owns `ToolRegistry`, `createDefaultToolRegistry` (which
+ * builds an empty registry), the registration contract and the toolbar helpers.
+ * It knows `featureId`, placement levels, activation kinds and precedence rules,
+ * and knows no capability ids.
+ */
+import { ToolRegistry, } from "@pie-players/pie-assessment-toolkit/tools/internal";
+import { annotationToolbarRegistration, lineReaderToolRegistration, themeToolRegistration, } from "./registrations/accessibility-tools.js";
+import { calculatorToolRegistration } from "./registrations/calculator.js";
+import { answerEliminatorToolRegistration, highlighterToolRegistration, } from "./registrations/interaction-tools.js";
+import { protractorToolRegistration, rulerToolRegistration, } from "./registrations/measurement-tools.js";
+import { graphToolRegistration, periodicTableToolRegistration, } from "./registrations/subject-specific-tools.js";
+import { ttsToolRegistration } from "./registrations/tts.js";
+import { PACKAGED_TOOL_TAG_MAP } from "./tool-tag-map.js";
+export const PACKAGED_TOOL_REGISTRATIONS = [
+    calculatorToolRegistration,
+    ttsToolRegistration,
+    rulerToolRegistration,
+    protractorToolRegistration,
+    answerEliminatorToolRegistration,
+    highlighterToolRegistration,
+    lineReaderToolRegistration,
+    themeToolRegistration,
+    annotationToolbarRegistration,
+    graphToolRegistration,
+    periodicTableToolRegistration,
+];
+/**
+ * Register packaged PIE capabilities onto an existing registry.
+ */
+export function registerPackagedTools(registry, options = {}) {
+    const selectedToolIds = options.toolIds && options.toolIds.length > 0
+        ? new Set(options.toolIds)
+        : null;
+    const applyOverrides = options.applyOverrides ??
+        ((registration) => registration);
+    for (const registration of PACKAGED_TOOL_REGISTRATIONS) {
+        if (selectedToolIds && !selectedToolIds.has(registration.toolId))
+            continue;
+        registry.register(applyOverrides(registration));
+    }
+}
+/**
+ * Create a registry holding the packaged PIE capabilities.
+ *
+ * The tag map is installed through `setComponentOverrides` rather than read from
+ * a core default, so a registry composed without it resolves no packaged tags —
+ * which is the point: core no longer carries the catalogue.
+ */
+export function createPackagedToolRegistry(options = {}) {
+    const registry = new ToolRegistry();
+    registerPackagedTools(registry, {
+        toolIds: options.toolIds,
+        applyOverrides: (registration) => options.overrides?.[registration.toolId] ?? registration,
+    });
+    if (options.toolModuleLoaders &&
+        Object.keys(options.toolModuleLoaders).length > 0) {
+        registry.setToolModuleLoaders(options.toolModuleLoaders);
+    }
+    registry.setComponentOverrides({
+        toolTagMap: { ...PACKAGED_TOOL_TAG_MAP, ...(options.toolTagMap ?? {}) },
+        toolComponentFactory: options.toolComponentFactory,
+        toolComponentFactories: options.toolComponentFactories,
+    });
+    return registry;
+}
+/**
+ * Render order when several capabilities are visible at once.
+ */
+export const PACKAGED_TOOL_ORDER = [
+    // Global accessibility first
+    "theme",
+    // Common tools
+    "calculator",
+    "textToSpeech",
+    // Reading aids
+    "lineReader",
+    "annotationToolbar",
+    "highlighter",
+    // Interaction tools
+    "answerEliminator",
+    // Measurement tools
+    "ruler",
+    "protractor",
+    // Subject-specific
+    "graph",
+    "periodicTable",
+];

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

@@ -0,0 +1,34 @@
+/**
+ * Accessibility Tools Registrations
+ *
+ * Registers tools for visual accessibility and reading support:
+ * - Line Reader (reading guide)
+ * - Color Scheme (theme/contrast)
+ * - Annotation Toolbar (text highlighting)
+ *
+ * Maps to QTI 3.0 standard access features from:
+ * - visual category: highContrastDisplay, colorContrast
+ * - reading category: readingMask, readingGuide, highlighting
+ */
+import type { ToolRegistration } from "@pie-players/pie-assessment-toolkit/tools/internal";
+/**
+ * Line Reader tool registration
+ *
+ * Provides a reading guide overlay to help track reading position.
+ * Useful for text-heavy passages and questions.
+ */
+export declare const lineReaderToolRegistration: ToolRegistration;
+/**
+ * Theme tool registration
+ *
+ * Provides accessible theme and contrast controls.
+ * Global tool that affects entire assessment.
+ */
+export declare const themeToolRegistration: ToolRegistration;
+/**
+ * Annotation Toolbar registration
+ *
+ * Text highlighting with CSS Custom Highlight API.
+ * Zero DOM mutation, optimal performance.
+ */
+export declare const annotationToolbarRegistration: ToolRegistration;

package/dist/registrations/accessibility-tools.js

@@ -0,0 +1,256 @@
+/**
+ * Accessibility Tools Registrations
+ *
+ * Registers tools for visual accessibility and reading support:
+ * - Line Reader (reading guide)
+ * - Color Scheme (theme/contrast)
+ * - Annotation Toolbar (text highlighting)
+ *
+ * Maps to QTI 3.0 standard access features from:
+ * - visual category: highContrastDisplay, colorContrast
+ * - reading category: readingMask, readingGuide, highlighting
+ */
+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";
+/**
+ * Line Reader tool registration
+ *
+ * Provides a reading guide overlay to help track reading position.
+ * Useful for text-heavy passages and questions.
+ */
+export const lineReaderToolRegistration = {
+    toolId: "lineReader",
+    name: "Line Reader",
+    description: "Reading guide overlay",
+    icon: "bars-3",
+    // Line reader appears where there's text to read
+    supportedLevels: ["section", "passage", "rubric", "item"],
+    // PNP support IDs
+    // Maps to QTI 3.0 standard features: readingMask, readingGuide, readingRuler
+    pnpSupportIds: [
+        "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
+     */
+    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: "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,
+        };
+    },
+};
+/**
+ * Theme tool registration
+ *
+ * Provides accessible theme and contrast controls.
+ * Global tool that affects entire assessment.
+ */
+export const themeToolRegistration = {
+    toolId: "theme",
+    name: "Theme",
+    description: "Accessible themes and contrast",
+    icon: "swatch",
+    // Color scheme is assessment-wide
+    supportedLevels: ["assessment", "section"],
+    // PNP support IDs
+    // Maps to QTI 3.0 standard features: highContrastDisplay, colorContrast, invertColors
+    pnpSupportIds: [
+        "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
+    ],
+    /**
+     * Pass 2: Color scheme is always relevant when allowed
+     */
+    isVisibleInContext(context) {
+        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;
+                }
+            },
+            subscribeActive: visibility.subscribeActive,
+        };
+    },
+};
+/**
+ * Annotation Toolbar registration
+ *
+ * Text highlighting with CSS Custom Highlight API.
+ * Zero DOM mutation, optimal performance.
+ */
+export const annotationToolbarRegistration = {
+    toolId: "annotationToolbar",
+    name: "Highlighter",
+    description: "Highlight and annotate text",
+    icon: "highlighter",
+    activation: "selection-gateway",
+    singletonScope: "section",
+    /**
+     * Section-scoped singleton surface. The gateway used to be mounted by
+     * `PieSectionPlayerBaseElement.svelte`, which named this tool id in three
+     * places — the policy check, the module load and the element — so no host
+     * could contribute a second section-scoped capability. Declaring the surface
+     * moves that wiring into this registration, and the renderer discovers it
+     * through `ToolRegistry.getToolsBySurface("section-overlay")`.
+     */
+    surfaces: ["section-overlay"],
+    // Annotation appears where there's text content
+    supportedLevels: ["passage", "rubric", "item", "element"],
+    // PNP support IDs
+    // Maps to QTI 3.0 standard features: highlighting, annotations
+    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
+     */
+    isVisibleInContext(context) {
+        return hasReadableText(context);
+    },
+    /**
+     * Mount the section-scoped gateway. The element positions itself (`position:
+     * fixed` inside its shadow root) and finds its scope through the toolkit's
+     * context, which bubbles from wherever the host mounted it, so this needs to
+     * know nothing about the host's layout.
+     */
+    renderSurface(context) {
+        const componentOverrides = context.componentOverrides ?? {};
+        const tagName = resolveToolTag(context.toolId, componentOverrides);
+        if (typeof customElements !== "undefined" && !customElements.get(tagName)) {
+            // The host loads the module before mounting, so reaching here means the
+            // optional package is absent. Declining is the right answer: mounting an
+            // undefined element would render an empty box the learner cannot use.
+            return null;
+        }
+        const element = document.createElement(tagName);
+        // Reads the context it is handed. These were reactive props before the
+        // gateway moved behind `renderSurface`, and a host calling
+        // `updateAssessment(...)` mid-session swaps the coordinator without
+        // remounting — closing over the render-time services would leave the gateway
+        // highlighting into the previous session's coordinator.
+        const applyServices = (current) => {
+            element.enabled = true;
+            element.ttsService = current.services.ttsService;
+            element.highlightCoordinator =
+                current.services.toolkitCoordinator?.highlightCoordinator ?? null;
+        };
+        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,
+        };
+    },
+};

package/dist/registrations/calculator.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Calculator Tool Registration
+ *
+ * Registers the calculator tool with support for multiple calculator types
+ * (basic, scientific, graphing) via Desmos 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";
+/**
+ * Calculator tool registration
+ *
+ * Supports:
+ * - Basic, scientific, and graphing calculators via Desmos
+ * - Context-aware visibility (shows only when math content is detected)
+ * - Item level only
+ */
+export declare const calculatorToolRegistration: ToolRegistration;