@pie-players/pie-default-tool-loaders 0.3.73 → 0.3.74

package/README.md

@@ -3,7 +3,8 @@
 Composition layer for the packaged PIE assessment tools: which capabilities exist
 in a deployment, and how a program tiers them.
 
-It owns the concrete `pie-tool-*` dependencies so toolkit core can stay
+It owns the concrete `pie-tool-*` dependencies and the calculator engines
+(`pie-calculator-cortex`, `-desmos` and `-geogebra`) 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.
@@ -89,24 +90,31 @@ For an offline-capable calculator with no API key or runtime CDN, use
 history, evaluation limit, allowed functions, clipboard policy, and graph
 viewport options documented by `@pie-players/pie-calculator-cortex`.
 
-`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.
+The toolkit's `ToolRegistry` is the other end of that choice: it starts empty,
+and a host composing its own set registers into it and installs the tag map its
+registrations create elements from.
 
 ```ts
-import { createDefaultToolRegistry } from "@pie-players/pie-assessment-toolkit";
+import { ToolRegistry } from "@pie-players/pie-assessment-toolkit";
 import {
 	calculatorToolRegistration,
-	registerSectionToolModuleLoaders,
+	PACKAGED_TOOL_TAG_MAP,
+	registerDefaultToolModuleLoaders,
 	ttsToolRegistration,
 } from "@pie-players/pie-default-tool-loaders";
 
-const registry = createDefaultToolRegistry({
-	registrations: [calculatorToolRegistration, ttsToolRegistration],
-});
-// Section-only loaders, for section toolbar bootstrap points.
-registerSectionToolModuleLoaders(registry);
+const registry = new ToolRegistry();
+registry.register(calculatorToolRegistration);
+registry.register(ttsToolRegistration);
+registry.setComponentOverrides({ toolTagMap: PACKAGED_TOOL_TAG_MAP });
+registerDefaultToolModuleLoaders(registry);
 ```
 
+`registerDefaultToolModuleLoaders` installs a loader for every packaged tool.
+`registerSectionToolModuleLoaders` installs only the section-bootstrap subset,
+which has no text-to-speech loader, so a registry that places item-level text to
+speech needs the full set.
+
 ## Content-dependent capabilities require an explicit packaging decision
 
 A content-dependent capability is never inferred into

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

@@ -0,0 +1,13 @@
+/** Fully bundled open-source calculator adapter for the tool-provider registry. */
+import type { CalculatorToolProviderInitConfig, LazyCalculatorProviderDefinition } from "./LazyCalculatorToolProvider.js";
+import { LazyCalculatorToolProvider } from "./LazyCalculatorToolProvider.js";
+import type { ToolProviderCapabilities } from "@pie-players/pie-assessment-toolkit/tools/internal";
+export type CortexToolProviderConfig = CalculatorToolProviderInitConfig;
+export declare class CortexToolProvider extends LazyCalculatorToolProvider<CortexToolProviderConfig> {
+    readonly providerId = "cortex-calculator";
+    readonly providerName = "PIE Open-Source Calculator";
+    readonly version = "1";
+    readonly requiresAuth = false;
+    protected getDefinition(): LazyCalculatorProviderDefinition<CortexToolProviderConfig>;
+    getCapabilities(): ToolProviderCapabilities;
+}

package/dist/calculator-providers/CortexToolProvider.js

@@ -0,0 +1,32 @@
+/** Fully bundled open-source calculator adapter for the tool-provider registry. */
+import { LazyCalculatorToolProvider } from "./LazyCalculatorToolProvider.js";
+export class CortexToolProvider extends LazyCalculatorToolProvider {
+    providerId = "cortex-calculator";
+    providerName = "PIE Open-Source Calculator";
+    version = "1";
+    requiresAuth = false;
+    getDefinition() {
+        return {
+            backend: "cortex",
+            moduleImportOperation: "cortex-provider-module-import",
+            loadProvider: async () => {
+                const module = await import("@pie-players/pie-calculator-cortex");
+                return module.CortexCalculatorProvider;
+            },
+            initializationErrorMessage: "Failed to initialize the PIE open-source calculator provider. Confirm that this browser supports module workers and that the bundled worker assets are available.",
+        };
+    }
+    getCapabilities() {
+        return {
+            supportsOffline: true,
+            requiresAuth: false,
+            maxInstances: null,
+            features: {
+                basic: true,
+                scientific: true,
+                graphing: true,
+                fourFunction: true,
+            },
+        };
+    }
+}

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

@@ -0,0 +1,14 @@
+/** Desmos calculator adapter for the generic tool-provider registry. */
+import type { CalculatorProviderInit } from "@pie-players/pie-calculator";
+import { LazyCalculatorToolProvider, type LazyCalculatorProviderDefinition } from "./LazyCalculatorToolProvider.js";
+import type { ToolProviderCapabilities } from "@pie-players/pie-assessment-toolkit/tools/internal";
+/** Provider initialization is the provider-neutral calculator contract. */
+export type DesmosToolProviderConfig = CalculatorProviderInit;
+export declare class DesmosToolProvider extends LazyCalculatorToolProvider<DesmosToolProviderConfig> {
+    readonly providerId = "desmos-calculator";
+    readonly providerName = "Desmos Calculator";
+    readonly version = "1.12";
+    readonly requiresAuth = true;
+    protected getDefinition(): LazyCalculatorProviderDefinition<DesmosToolProviderConfig>;
+    getCapabilities(): ToolProviderCapabilities;
+}

package/dist/calculator-providers/DesmosToolProvider.js

@@ -0,0 +1,32 @@
+/** Desmos calculator adapter for the generic tool-provider registry. */
+import { LazyCalculatorToolProvider, } from "./LazyCalculatorToolProvider.js";
+export class DesmosToolProvider extends LazyCalculatorToolProvider {
+    providerId = "desmos-calculator";
+    providerName = "Desmos Calculator";
+    version = "1.12";
+    requiresAuth = true;
+    getDefinition() {
+        return {
+            backend: "desmos",
+            moduleImportOperation: "desmos-provider-module-import",
+            loadProvider: async () => {
+                const module = await import("@pie-players/pie-calculator-desmos");
+                return module.DesmosCalculatorProvider;
+            },
+            initializationErrorMessage: "Failed to initialize Desmos calculator provider. Check the application key, preloaded API, runtime endpoint, or network access.",
+        };
+    }
+    getCapabilities() {
+        return {
+            supportsOffline: false,
+            requiresAuth: true,
+            maxInstances: null,
+            features: {
+                basic: true,
+                scientific: true,
+                graphing: true,
+                fourFunction: true,
+            },
+        };
+    }
+}

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

@@ -0,0 +1,16 @@
+/** GeoGebra calculator adapter for the generic tool-provider registry. */
+import type { CalculatorToolProviderInitConfig, LazyCalculatorProviderDefinition } from "./LazyCalculatorToolProvider.js";
+import { LazyCalculatorToolProvider } from "./LazyCalculatorToolProvider.js";
+import type { ToolProviderCapabilities } from "@pie-players/pie-assessment-toolkit/tools/internal";
+export interface GeoGebraToolProviderConfig extends CalculatorToolProviderInitConfig {
+    scriptUrl?: string;
+    appletTimeoutMs?: number;
+}
+export declare class GeoGebraToolProvider extends LazyCalculatorToolProvider<GeoGebraToolProviderConfig> {
+    readonly providerId = "geogebra-calculator";
+    readonly providerName = "GeoGebra Calculator";
+    readonly version = "6";
+    readonly requiresAuth = false;
+    protected getDefinition(): LazyCalculatorProviderDefinition<GeoGebraToolProviderConfig>;
+    getCapabilities(): ToolProviderCapabilities;
+}

package/dist/calculator-providers/GeoGebraToolProvider.js

@@ -0,0 +1,32 @@
+/** GeoGebra calculator adapter for the generic tool-provider registry. */
+import { LazyCalculatorToolProvider } from "./LazyCalculatorToolProvider.js";
+export class GeoGebraToolProvider extends LazyCalculatorToolProvider {
+    providerId = "geogebra-calculator";
+    providerName = "GeoGebra Calculator";
+    version = "6";
+    requiresAuth = false;
+    getDefinition() {
+        return {
+            backend: "geogebra",
+            moduleImportOperation: "geogebra-provider-module-import",
+            loadProvider: async () => {
+                const module = await import("@pie-players/pie-calculator-geogebra");
+                return module.GeoGebraCalculatorProvider;
+            },
+            initializationErrorMessage: "Failed to initialize GeoGebra calculator provider. Confirm that the deployment may load GeoGebra and that its script URL is reachable.",
+        };
+    }
+    getCapabilities() {
+        return {
+            supportsOffline: false,
+            requiresAuth: false,
+            maxInstances: null,
+            features: {
+                basic: true,
+                scientific: true,
+                graphing: true,
+                fourFunction: false,
+            },
+        };
+    }
+}

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

@@ -0,0 +1,35 @@
+import type { CalculatorProvider, CalculatorProviderInit } from "@pie-players/pie-calculator";
+import type { ToolProviderApi, ToolProviderCapabilities } from "@pie-players/pie-assessment-toolkit/tools/internal";
+export type CalculatorToolProviderInitConfig = Pick<CalculatorProviderInit, "onTelemetry">;
+type InitializableCalculatorProvider<TConfig> = CalculatorProvider & {
+    initialize(config: TConfig): Promise<void>;
+};
+export interface LazyCalculatorProviderDefinition<TConfig> {
+    backend: string;
+    moduleImportOperation: string;
+    loadProvider: () => Promise<new () => InitializableCalculatorProvider<TConfig>>;
+    initializationErrorMessage: string;
+}
+/**
+ * Shared lazy-module and lifecycle implementation for calculator tool adapters.
+ * Concrete adapters own only their metadata, capabilities and provider import.
+ */
+export declare abstract class LazyCalculatorToolProvider<TConfig extends CalculatorToolProviderInitConfig> implements ToolProviderApi<TConfig, CalculatorProvider> {
+    abstract readonly providerId: string;
+    abstract readonly providerName: string;
+    readonly category: "calculator";
+    abstract readonly version: string;
+    abstract readonly requiresAuth: boolean;
+    protected abstract getDefinition(): LazyCalculatorProviderDefinition<TConfig>;
+    abstract getCapabilities(): ToolProviderCapabilities;
+    private calculatorProvider;
+    private initializationPromise;
+    private lifecycleGeneration;
+    private emitTelemetry;
+    initialize(config?: TConfig): Promise<void>;
+    private initializeProvider;
+    createInstance(): Promise<CalculatorProvider>;
+    isReady(): boolean;
+    destroy(): void;
+}
+export {};

package/dist/calculator-providers/LazyCalculatorToolProvider.js

@@ -0,0 +1,95 @@
+/**
+ * Shared lazy-module and lifecycle implementation for calculator tool adapters.
+ * Concrete adapters own only their metadata, capabilities and provider import.
+ */
+export class LazyCalculatorToolProvider {
+    category = "calculator";
+    calculatorProvider = null;
+    initializationPromise = null;
+    lifecycleGeneration = 0;
+    async emitTelemetry(config, eventName, payload) {
+        try {
+            await config.onTelemetry?.(eventName, payload);
+        }
+        catch (error) {
+            console.warn(`[${this.providerName}] telemetry callback failed:`, error);
+        }
+    }
+    async initialize(config = {}) {
+        if (this.calculatorProvider)
+            return;
+        if (this.initializationPromise)
+            return this.initializationPromise;
+        const generation = ++this.lifecycleGeneration;
+        const initializationPromise = this.initializeProvider(config, generation);
+        this.initializationPromise = initializationPromise;
+        try {
+            await initializationPromise;
+        }
+        finally {
+            if (this.initializationPromise === initializationPromise) {
+                this.initializationPromise = null;
+            }
+        }
+    }
+    async initializeProvider(config, generation) {
+        const definition = this.getDefinition();
+        const moduleLoadStartedAt = Date.now();
+        await this.emitTelemetry(config, "pie-tool-library-load-start", {
+            toolId: "calculator",
+            operation: definition.moduleImportOperation,
+            backend: definition.backend,
+        });
+        let ProviderConstructor;
+        try {
+            ProviderConstructor = await definition.loadProvider();
+            await this.emitTelemetry(config, "pie-tool-library-load-success", {
+                toolId: "calculator",
+                operation: definition.moduleImportOperation,
+                backend: definition.backend,
+                duration: Date.now() - moduleLoadStartedAt,
+            });
+        }
+        catch (error) {
+            await this.emitTelemetry(config, "pie-tool-library-load-error", {
+                toolId: "calculator",
+                operation: definition.moduleImportOperation,
+                backend: definition.backend,
+                duration: Date.now() - moduleLoadStartedAt,
+                errorType: "ToolLibraryLoadError",
+                message: error instanceof Error ? error.message : String(error),
+            });
+            throw new Error(definition.initializationErrorMessage, { cause: error });
+        }
+        if (generation !== this.lifecycleGeneration) {
+            throw new Error(`${this.providerName} initialization was cancelled`);
+        }
+        const candidate = new ProviderConstructor();
+        try {
+            await candidate.initialize(config);
+            if (generation !== this.lifecycleGeneration) {
+                throw new Error(`${this.providerName} initialization was cancelled`);
+            }
+            this.calculatorProvider = candidate;
+        }
+        catch (error) {
+            candidate.destroy();
+            throw new Error(definition.initializationErrorMessage, { cause: error });
+        }
+    }
+    async createInstance() {
+        if (!this.calculatorProvider) {
+            throw new Error(`[${this.providerName}] Provider not initialized. Call initialize() first.`);
+        }
+        return this.calculatorProvider;
+    }
+    isReady() {
+        return this.calculatorProvider !== null;
+    }
+    destroy() {
+        this.lifecycleGeneration += 1;
+        this.initializationPromise = null;
+        this.calculatorProvider?.destroy();
+        this.calculatorProvider = null;
+    }
+}

package/dist/packaged-capability-composition.d.ts

@@ -7,7 +7,7 @@
  * Public constants are projections of this composition so adding a capability
  * cannot leave a second hand-maintained catalogue silently behind.
  */
-import { ToolRegistry, type ToolComponentFactory, type ToolComponentFactoryMap, type ToolRegistration, type ToolTagMap, type ToolProviderConfig } from "@pie-players/pie-assessment-toolkit/tools/internal";
+import { ToolRegistry, type CalculatorToolProviderConfig, type ToolComponentFactory, type ToolComponentFactoryMap, type ToolRegistration, type ToolTagMap } from "@pie-players/pie-assessment-toolkit/tools/internal";
 import type { PersonalNeedsProfile } from "@pie-players/pie-players-shared/types";
 export type ToolModuleLoader = () => Promise<unknown>;
 export interface ToolRegistryLike {
@@ -19,7 +19,7 @@ export interface PackagedCalculatorCompositionOptions {
      * Selects the matching packaged element and default loader. Omit it to retain
      * the existing Desmos delivery.
      */
-    calculatorProviderConfig?: ToolProviderConfig;
+    calculatorProviderConfig?: CalculatorToolProviderConfig;
 }
 export interface PackagedToolRegistryOptions extends PackagedCalculatorCompositionOptions {
     /** Override packaged registrations by toolId. */

package/dist/packaged-capability-composition.js

@@ -69,7 +69,7 @@ const PACKAGED_CAPABILITY_DEFINITIONS = [
     },
     {
         registration: ttsToolRegistration,
-        tagName: "pie-tool-text-to-speech",
+        tagName: "pie-tool-tts-inline",
         loadModule: loadTtsModule,
         loaderTargets: ["item"],
         placementOrder: { item: 10, passage: 10, rubric: 10, element: 30 },

package/dist/registrations/accessibility-tools.js

@@ -11,8 +11,7 @@
  * - 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";
+import { resolveToolTag, } from "@pie-players/pie-assessment-toolkit/tools/internal";
 import { buildSelectionActions } from "./selection-actions.js";
 import { renderOverlayToolbar } from "./overlay-toolbar-render.js";
 /**

package/dist/registrations/calculator.js

@@ -10,10 +10,11 @@
  */
 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";
+import { CortexToolProvider } from "../calculator-providers/CortexToolProvider.js";
+import { DesmosToolProvider } from "../calculator-providers/DesmosToolProvider.js";
+import { GeoGebraToolProvider } from "../calculator-providers/GeoGebraToolProvider.js";
+import { resolveOverlayElement } from "./overlay-element-cache.js";
 export const DEFAULT_CALCULATOR_PROVIDER_ID = "calculator-desmos";
 export function resolveCalculatorProviderId(config) {
     const configured = config?.provider?.id;
@@ -50,38 +51,6 @@ function getCalculatorInstanceConfig(config) {
             : 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
-// mount), so we cache the overlay element by coordinator + scoped tool id.
-// Reusing the same element keeps `mountContent` a no-op and avoids tearing
-// down and re-initializing the calculator on every re-render.
-const overlayElementCache = new WeakMap();
-function getCachedOverlay(coordinator, fullToolId) {
-    if (!coordinator)
-        return null;
-    const scoped = overlayElementCache.get(coordinator);
-    const element = scoped?.get(fullToolId);
-    if (!element)
-        return null;
-    // Svelte custom elements destroy their component when disconnected.
-    // A detached cached element is a dead instance — drop it and recreate.
-    if (!element.isConnected) {
-        scoped?.delete(fullToolId);
-        return null;
-    }
-    return element;
-}
-function setCachedOverlay(coordinator, fullToolId, element) {
-    if (!coordinator)
-        return;
-    let scoped = overlayElementCache.get(coordinator);
-    if (!scoped) {
-        scoped = new Map();
-        overlayElementCache.set(coordinator, scoped);
-    }
-    scoped.set(fullToolId, element);
-}
 function normalizeCalculatorType(value) {
     return value === "basic" || value === "scientific" || value === "graphing"
         ? value
@@ -188,17 +157,15 @@ export const calculatorToolRegistration = {
     },
     renderToolbar(context, toolbarContext) {
         const { calculatorType, availableTypes, displayName } = getCalculatorRenderParams(toolbarContext);
-        const calculatorToolConfig = toolbarContext.toolkitCoordinator?.config.tools?.providers?.calculator;
+        const calculatorToolConfig = toolbarContext.toolkitCoordinator?.getToolConfig(this.toolId) ||
+            undefined;
         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);
-        const overlay = (cachedOverlay ??
-            createToolElement(this.toolId, context, toolbarContext, componentOverrides));
-        if (!cachedOverlay) {
-            setCachedOverlay(toolbarContext.toolCoordinator, fullToolId, overlay);
-        }
+        // 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);
         overlay.toolkitCoordinator = toolbarContext.toolkitCoordinator;
         applyCalculatorParamsToElement(overlay, calculatorType, availableTypes, providerId, calculatorConfig);

package/dist/registrations/dictionary-tools.js

@@ -16,6 +16,7 @@
  * 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";
+import { resolveOverlayElement } from "./overlay-element-cache.js";
 /**
  * Apply the host's per-tool render params to the panel.
  *
@@ -81,7 +82,7 @@ function renderDictionaryPanel(args) {
     };
     const componentOverrides = toolbarContext.componentOverrides ??
         {};
-    const overlay = createToolElement(registration.toolId, context, toolbarContext, componentOverrides);
+    const overlay = resolveOverlayElement(toolbarContext, visibility.fullToolId, () => createToolElement(registration.toolId, context, toolbarContext, componentOverrides));
     overlay.setAttribute("tool-id", visibility.fullToolId);
     applyLookupParams(overlay, registration.toolId, toolbarContext, args.lookupLanguage);
     return {

package/dist/registrations/interaction-tools.js

@@ -10,9 +10,10 @@
  * - strikethrough (visual transformation)
  * - highlighting (cognitive/reading support)
  */
-import { hasChoiceInteraction, hasReadableText, } from "@pie-players/pie-assessment-toolkit/tools/internal";
+import { hasChoiceInteraction } from "@pie-players/pie-assessment-toolkit/tools/internal";
 import { createToolElement, } from "@pie-players/pie-assessment-toolkit/tools/internal";
 import { createScopedVisibilityBinding, syncButtonAndOverlayVisibility, } from "@pie-players/pie-assessment-toolkit/tools/internal";
+import { resolveOverlayElement } from "./overlay-element-cache.js";
 /**
  * Answer Eliminator tool registration
  *
@@ -55,7 +56,7 @@ export const answerEliminatorToolRegistration = {
     renderToolbar(context, toolbarContext) {
         const visibility = createScopedVisibilityBinding(this.toolId, toolbarContext);
         const componentOverrides = toolbarContext.componentOverrides ?? {};
-        const overlay = createToolElement(this.toolId, context, toolbarContext, componentOverrides);
+        const overlay = resolveOverlayElement(toolbarContext, visibility.fullToolId, () => createToolElement(this.toolId, context, toolbarContext, componentOverrides));
         overlay.setAttribute("tool-id", visibility.fullToolId);
         overlay.setAttribute("strategy", "strikethrough");
         overlay.setAttribute("button-alignment", "inline");

package/dist/registrations/measurement-tools.js

@@ -8,8 +8,6 @@
  * - protractor (assessment tool)
  */
 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

package/dist/registrations/overlay-element-cache.d.ts

@@ -0,0 +1,21 @@
+/**
+ * One overlay element per coordinator and scoped tool id, reused across renders.
+ *
+ * The toolbar re-derives its rendered tools whenever an input moves — a policy
+ * emit, a tool-config update, the interface locale — and mounts whichever
+ * element each render returns, swapping out one it has not seen. A registration
+ * that creates its overlay on every render therefore remounts it, and the
+ * learner loses the ruler's position, the graph's points or the eliminated
+ * choices while the tool stays open. Reusing the element keeps the mount a
+ * no-op, so per-render attributes are the registration's to re-apply.
+ *
+ * A Svelte custom element tears its component down once it leaves the document,
+ * so a cached element found disconnected is dropped and recreated.
+ */
+import type { ToolbarContext } from "@pie-players/pie-assessment-toolkit/tools/internal";
+/**
+ * The element cached for `fullToolId` under this toolbar's coordinator, or the
+ * one `create` returns, which is then cached. Without a coordinator there is no
+ * session to key by, and every render creates.
+ */
+export declare function resolveOverlayElement<T extends HTMLElement>(toolbarContext: ToolbarContext, fullToolId: string, create: () => T): T;

package/dist/registrations/overlay-element-cache.js

@@ -0,0 +1,47 @@
+/**
+ * One overlay element per coordinator and scoped tool id, reused across renders.
+ *
+ * The toolbar re-derives its rendered tools whenever an input moves — a policy
+ * emit, a tool-config update, the interface locale — and mounts whichever
+ * element each render returns, swapping out one it has not seen. A registration
+ * that creates its overlay on every render therefore remounts it, and the
+ * learner loses the ruler's position, the graph's points or the eliminated
+ * choices while the tool stays open. Reusing the element keeps the mount a
+ * no-op, so per-render attributes are the registration's to re-apply.
+ *
+ * A Svelte custom element tears its component down once it leaves the document,
+ * so a cached element found disconnected is dropped and recreated.
+ */
+import { TOOL_ELEMENT_UNMOUNT_CALLBACK_PROP } from "./tts.js";
+const overlayElements = new WeakMap();
+/**
+ * The element cached for `fullToolId` under this toolbar's coordinator, or the
+ * one `create` returns, which is then cached. Without a coordinator there is no
+ * session to key by, and every render creates.
+ */
+export function resolveOverlayElement(toolbarContext, fullToolId, create) {
+    const coordinator = toolbarContext.toolCoordinator;
+    if (!coordinator)
+        return create();
+    let scoped = overlayElements.get(coordinator);
+    const cached = scoped?.get(fullToolId);
+    if (cached?.isConnected)
+        return cached;
+    const element = create();
+    if (!scoped) {
+        scoped = new Map();
+        overlayElements.set(coordinator, scoped);
+    }
+    scoped.set(fullToolId, element);
+    // The toolbar calls this as it unmounts the element, before detaching it, so
+    // the check waits a microtask: an element another toolbar has adopted in the
+    // meantime is still connected and stays cached.
+    element[TOOL_ELEMENT_UNMOUNT_CALLBACK_PROP] = () => {
+        queueMicrotask(() => {
+            if (!element.isConnected && scoped.get(fullToolId) === element) {
+                scoped.delete(fullToolId);
+            }
+        });
+    };
+    return element;
+}

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

@@ -17,6 +17,7 @@
  * off one element — keeps its own renderer.
  */
 import { applyOverlaySurface, createScopedVisibilityBinding, createToolElement, resolveToolRegistrationName, syncButtonAndOverlayVisibility, } from "@pie-players/pie-assessment-toolkit/tools/internal";
+import { resolveOverlayElement } from "./overlay-element-cache.js";
 export function renderOverlayToolbar(registration, context, toolbarContext, options = {}) {
     const { toolId } = registration;
     const visibility = createScopedVisibilityBinding(toolId, toolbarContext);
@@ -34,7 +35,7 @@ export function renderOverlayToolbar(registration, context, toolbarContext, opti
     };
     const componentOverrides = toolbarContext.componentOverrides ??
         {};
-    const overlay = createToolElement(toolId, context, toolbarContext, componentOverrides);
+    const overlay = resolveOverlayElement(toolbarContext, visibility.fullToolId, () => createToolElement(toolId, context, toolbarContext, componentOverrides));
     overlay.setAttribute("tool-id", visibility.fullToolId);
     if (options.surface === "frameless") {
         applyOverlaySurface(overlay, "frameless");

package/dist/registrations/subject-specific-tools.d.ts

@@ -2,11 +2,10 @@
  * Subject-Specific Tools Registrations
  *
  * Registers tools for specific subject areas:
- * - Graph (graphing calculator/coordinate plane)
+ * - Graph (coordinate plane)
  * - Periodic Table (chemistry reference)
  *
  * Maps to QTI 3.0 standard access features:
- * - graphingCalculator (assessment tool)
  * - graph (assessment tool)
  * - periodicTable (assessment tool)
  */
@@ -14,7 +13,7 @@ import type { ToolRegistration } from "@pie-players/pie-assessment-toolkit/tools
 /**
  * Graph tool registration
  *
- * Provides graphing calculator and coordinate plane functionality.
+ * Provides a coordinate plane.
  * Context-smart: appears automatically for math content or when explicitly enabled.
  */
 export declare const graphToolRegistration: ToolRegistration;

package/dist/registrations/subject-specific-tools.js

@@ -2,38 +2,35 @@
  * Subject-Specific Tools Registrations
  *
  * Registers tools for specific subject areas:
- * - Graph (graphing calculator/coordinate plane)
+ * - Graph (coordinate plane)
  * - Periodic Table (chemistry reference)
  *
  * Maps to QTI 3.0 standard access features:
- * - graphingCalculator (assessment tool)
  * - graph (assessment tool)
  * - periodicTable (assessment tool)
  */
 import { hasMathContent, hasScienceContent, } from "@pie-players/pie-assessment-toolkit/tools/internal";
-import { createToolElement, } from "@pie-players/pie-assessment-toolkit/tools/internal";
-import { createScopedVisibilityBinding, syncButtonAndOverlayVisibility, } from "@pie-players/pie-assessment-toolkit/tools/internal";
 import { renderOverlayToolbar } from "./overlay-toolbar-render.js";
 /**
  * Graph tool registration
  *
- * Provides graphing calculator and coordinate plane functionality.
+ * Provides a coordinate plane.
  * Context-smart: appears automatically for math content or when explicitly enabled.
  */
 export const graphToolRegistration = {
     toolId: "graph",
     name: "Graph",
-    description: "Graphing calculator and coordinate plane",
+    description: "Coordinate plane",
     nameKey: "tools.graph.name",
     descriptionKey: "tools.graph.description",
     icon: "chart-bar",
-    // Graph is a section-level floating tool.
-    supportedLevels: ["section"],
-    // PNP support IDs
-    // Maps to QTI 3.0 standard features: graph, graphingCalculator
+    // A floating tool, placed on a section toolbar or on an item toolbar where
+    // the toolkit runs without a section.
+    supportedLevels: ["section", "item"],
+    // `graphingCalculator` grants the calculator, whose graphing type a host
+    // selects through render params; the coordinate plane is not that tool.
     pnpSupportIds: [
         "graph", // QTI 3.0 standard (assessment.graph)
-        "graphingCalculator", // QTI 3.0 standard (assessment.graphingCalculator)
     ],
     /**
      * Pass 2: Graph is relevant when math content is present
@@ -66,8 +63,9 @@ export const periodicTableToolRegistration = {
     nameKey: "tools.periodicTable.name",
     descriptionKey: "tools.periodicTable.description",
     icon: "beaker",
-    // Periodic table is a section-level floating tool.
-    supportedLevels: ["section"],
+    // A floating tool, placed on a section toolbar or on an item toolbar where
+    // the toolkit runs without a section.
+    supportedLevels: ["section", "item"],
     // PNP support IDs
     // Maps to QTI 3.0 standard feature: periodicTable
     pnpSupportIds: [

package/dist/registrations/tts.js

@@ -11,6 +11,9 @@ import { hasReadableText } from "@pie-players/pie-assessment-toolkit/tools/inter
 import { createScopedToolId } from "@pie-players/pie-assessment-toolkit/tools/internal";
 import { buildRuntimeTTSConfig, normalizeTTSLayoutMode, normalizeTTSSpeedControlOptions, resolveTTSHostToolbarLayout, resolveTTSLayoutMode, resolveTTSBackend, resolveTTSRuntimeSettings, resolveRuntimeProvider, resolveTransportMode, } from "@pie-players/pie-assessment-toolkit/tools/internal";
 import { TTSToolProvider } from "@pie-players/pie-assessment-toolkit/tools/internal";
+// This package owns the server adapter's import, so the toolkit never names it
+// and a bundler building the toolkit alone has nothing to resolve.
+const loadServerTTSProvider = async () => (await import("@pie-players/tts-client-server")).ServerTTSProvider;
 const inlineTTSControls = new Map();
 export const TOOL_ELEMENT_UNMOUNT_CALLBACK_PROP = "__pieToolElementUnmount";
 export const TOOL_ACTIVE_CHANGE_EVENT = "pie-tool-active-change";
@@ -33,7 +36,9 @@ export const ttsToolRegistration = {
         getProviderId: () => "tts",
         createProvider: (config) => {
             const settings = resolveTTSRuntimeSettings(config);
-            return new TTSToolProvider(resolveTTSBackend(settings));
+            return new TTSToolProvider(resolveTTSBackend(settings), {
+                loadServerProvider: loadServerTTSProvider,
+            });
         },
         getInitConfig: (config) => {
             const settings = resolveTTSRuntimeSettings(config);
@@ -128,7 +133,6 @@ export const ttsToolRegistration = {
                 };
                 inlineTTSControls.set(fullToolId, element);
             }
-            element.setAttribute("tool-id", fullToolId);
             element.setAttribute("catalog-id", toolbarContext.catalogId || toolbarContext.itemId);
             element.setAttribute("language", toolbarContext.language || "en-US");
             element.setAttribute("size", resolveControlSize());

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/pie-default-tool-loaders",
-	"version": "0.3.73",
+	"version": "0.3.74",
 	"type": "module",
 	"description": "Composition layer for the packaged PIE assessment tools: registrations, tag map, placement presets, universal supports and lazy module loaders",
 	"repository": {
@@ -29,30 +29,34 @@
 		"check:composition": "bun test tests/packaged-capability-composition.test.ts",
 		"dev": "tsc -p tsconfig.json --watch",
 		"typecheck": "tsc -p tsconfig.json --noEmit",
-		"lint": "biome check .",
+		"lint": "biome lint .",
 		"test": "bun test"
 	},
 	"dependencies": {
-		"@pie-players/pie-assessment-toolkit": "0.3.73",
-		"@pie-players/pie-players-shared": "0.3.73",
-		"@pie-players/pie-tool-annotation-toolbar": "0.3.73",
-		"@pie-players/pie-tool-answer-eliminator": "0.3.73",
-		"@pie-players/pie-tool-calculator-desmos": "0.3.73",
-		"@pie-players/pie-tool-calculator-cortex": "0.3.73",
-		"@pie-players/pie-tool-calculator-geogebra": "0.3.73",
-		"@pie-players/pie-tool-calculator-shared": "0.3.73",
-		"@pie-players/pie-tool-dictionary": "0.3.73",
-		"@pie-players/pie-tool-graph": "0.3.73",
-		"@pie-players/pie-tool-line-reader": "0.3.73",
-		"@pie-players/pie-tool-periodic-table": "0.3.73",
-		"@pie-players/pie-tool-picture-dictionary": "0.3.73",
-		"@pie-players/pie-tool-protractor": "0.3.73",
-		"@pie-players/pie-tool-ruler": "0.3.73",
-		"@pie-players/pie-tool-theme": "0.3.73",
-		"@pie-players/pie-tool-tts-inline": "0.3.73"
+		"@pie-players/pie-assessment-toolkit": "0.3.74",
+		"@pie-players/pie-calculator": "0.3.74",
+		"@pie-players/pie-calculator-cortex": "0.3.74",
+		"@pie-players/pie-calculator-desmos": "0.3.74",
+		"@pie-players/pie-calculator-geogebra": "0.3.74",
+		"@pie-players/pie-players-shared": "0.3.74",
+		"@pie-players/pie-tool-annotation-toolbar": "0.3.74",
+		"@pie-players/pie-tool-answer-eliminator": "0.3.74",
+		"@pie-players/pie-tool-calculator-cortex": "0.3.74",
+		"@pie-players/pie-tool-calculator-geogebra": "0.3.74",
+		"@pie-players/pie-tool-calculator-shared": "0.3.74",
+		"@pie-players/pie-tool-dictionary": "0.3.74",
+		"@pie-players/pie-tool-graph": "0.3.74",
+		"@pie-players/pie-tool-line-reader": "0.3.74",
+		"@pie-players/pie-tool-periodic-table": "0.3.74",
+		"@pie-players/pie-tool-picture-dictionary": "0.3.74",
+		"@pie-players/pie-tool-protractor": "0.3.74",
+		"@pie-players/pie-tool-ruler": "0.3.74",
+		"@pie-players/pie-tool-theme": "0.3.74",
+		"@pie-players/pie-tool-tts-inline": "0.3.74",
+		"@pie-players/tts-client-server": "0.3.74"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "^2.5.13",
+		"@biomejs/biome": "^2.5.15",
 		"typescript": "^5.9.3"
 	},
 	"homepage": "https://github.com/pie-framework/pie-players/tree/master/packages/default-tool-loaders#readme",

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

@@ -1,2 +0,0 @@
-export type { PackagedToolRegistryOptions, RegisterPackagedToolsOptions, } from "./packaged-capability-composition.js";
-export { createPackagedToolRegistry, PACKAGED_TOOL_ORDER, PACKAGED_TOOL_REGISTRATIONS, registerPackagedTools, } from "./packaged-capability-composition.js";

package/dist/packaged-tool-registry.js

@@ -1 +0,0 @@
-export { createPackagedToolRegistry, PACKAGED_TOOL_ORDER, PACKAGED_TOOL_REGISTRATIONS, registerPackagedTools, } from "./packaged-capability-composition.js";

package/dist/tool-placement.d.ts

@@ -1 +0,0 @@
-export { PACKAGED_TOOL_PLACEMENT, SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT, } from "./packaged-capability-composition.js";

package/dist/tool-placement.js

@@ -1 +0,0 @@
-export { PACKAGED_TOOL_PLACEMENT, SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT, } from "./packaged-capability-composition.js";

package/dist/tool-tag-map.d.ts

@@ -1 +0,0 @@
-export { PACKAGED_TOOL_TAG_MAP } from "./packaged-capability-composition.js";

package/dist/tool-tag-map.js

@@ -1 +0,0 @@
-export { PACKAGED_TOOL_TAG_MAP } from "./packaged-capability-composition.js";

package/dist/universal-supports.d.ts

@@ -1 +0,0 @@
-export { UNIVERSAL_SUPPORTS_PRESET, createUniversalPersonalNeedsProfile, } from "./packaged-capability-composition.js";

package/dist/universal-supports.js

@@ -1 +0,0 @@
-export { UNIVERSAL_SUPPORTS_PRESET, createUniversalPersonalNeedsProfile, } from "./packaged-capability-composition.js";