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

package/dist/registrations/calculator.d.ts

@@ -3,13 +3,9 @@
  *
  * Registers the calculator tool with support for multiple calculator types
  * (basic, scientific, graphing) through a host-selected provider.
- *
- * Maps to QTI 3.0 standard access features:
- * - calculator (cognitive support)
- * - graphingCalculator (assessment tool)
  */
-import type { ToolRegistration } from "@pie-players/pie-assessment-toolkit/tools/internal";
-import type { ToolProviderConfig } from "@pie-players/pie-assessment-toolkit/tools/internal";
+import type { ToolRegistration } from "@pie-players/pie-assessment-toolkit/tools/registration";
+import type { ToolProviderConfig } from "@pie-players/pie-assessment-toolkit/tools/registration";
 export type CalculatorProviderId = "calculator-desmos" | "calculator-geogebra" | "calculator-cortex";
 export declare const DEFAULT_CALCULATOR_PROVIDER_ID: CalculatorProviderId;
 export declare function resolveCalculatorProviderId(config: ToolProviderConfig | undefined): CalculatorProviderId;

package/dist/registrations/calculator.js

@@ -3,17 +3,14 @@
  *
  * Registers the calculator tool with support for multiple calculator types
  * (basic, scientific, graphing) through a host-selected provider.
- *
- * Maps to QTI 3.0 standard access features:
- * - calculator (cognitive support)
- * - graphingCalculator (assessment tool)
  */
-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 { hasMathContent } from "@pie-players/pie-assessment-toolkit/tools/registration";
+import { createScopedToolId } from "@pie-players/pie-assessment-toolkit/tools/registration";
+import { createToolElement } from "@pie-players/pie-assessment-toolkit/tools/registration";
+import { CortexToolProvider } from "../calculator-providers/CortexToolProvider.js";
+import { DesmosToolProvider } from "../calculator-providers/DesmosToolProvider.js";
+import { GeoGebraToolProvider } from "../calculator-providers/GeoGebraToolProvider.js";
+import { 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 +47,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
@@ -117,11 +82,9 @@ const CALCULATOR_NAME_KEYS = {
     graphing: "tools.calculator.nameGraphing",
     untyped: "tools.calculator.name",
 };
-function applyCalculatorParamsToElement(element, calculatorType, availableTypes, providerId, calculatorConfig) {
+function applyCalculatorParamsToElement(element, calculatorType, availableTypes, calculatorConfig) {
     const calculatorElement = element;
-    calculatorElement.providerId = providerId;
     calculatorElement.calculatorConfig = calculatorConfig;
-    element.setAttribute("provider-id", providerId);
     if (calculatorType) {
         calculatorElement.calculatorType = calculatorType;
         element.setAttribute("calculator-type", calculatorType);
@@ -153,7 +116,6 @@ export const calculatorToolRegistration = {
     descriptionKey: "tools.calculator.description",
     icon: "calculator",
     provider: {
-        getProviderId: resolveCalculatorProviderId,
         createProvider: createCalculatorToolProvider,
         getInitConfig: (config) => config?.provider?.init ?? {},
         getAuthFetcher: (config) => {
@@ -166,16 +128,6 @@ export const calculatorToolRegistration = {
     },
     // Calculator is item-level in this player architecture.
     supportedLevels: ["item"],
-    // PNP support IDs that enable this tool
-    // Maps to QTI 3.0 standard features: calculator, graphingCalculator
-    // A type is not a feature id: `calculatorType` arrives through the host's
-    // render params, so `basicCalculator` / `scientificCalculator` granted the
-    // same untyped calculator these two do and only looked like they selected a
-    // variant.
-    pnpSupportIds: [
-        "calculator", // QTI 3.0 standard (cognitive.calculator)
-        "graphingCalculator", // QTI 3.0 standard (assessment.graphingCalculator)
-    ],
     /**
      * Pass 2: Determine if calculator is relevant in this context
      *
@@ -188,20 +140,16 @@ export const calculatorToolRegistration = {
     },
     renderToolbar(context, toolbarContext) {
         const { calculatorType, availableTypes, displayName } = getCalculatorRenderParams(toolbarContext);
-        const calculatorToolConfig = toolbarContext.toolkitCoordinator?.config.tools?.providers?.calculator;
-        const providerId = resolveCalculatorProviderId(calculatorToolConfig);
+        const calculatorToolConfig = toolbarContext.toolkitCoordinator?.getToolConfig(this.toolId) ||
+            undefined;
         const calculatorConfig = getCalculatorInstanceConfig(calculatorToolConfig);
         const fullToolId = createScopedToolId(this.toolId, toolbarContext.scope.level, toolbarContext.scope.scopeId);
         const componentOverrides = toolbarContext.componentOverrides;
-        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);
+        applyCalculatorParamsToElement(overlay, calculatorType, availableTypes, calculatorConfig);
         const button = {
             toolId: this.toolId,
             label: displayName,
@@ -218,7 +166,7 @@ export const calculatorToolRegistration = {
             ariaLabel: displayName,
             tooltip: displayName,
             onClick: () => toolbarContext.toggleTool(this.toolId),
-            active: toolbarContext.isToolVisible(fullToolId),
+            active: toolbarContext.isToolVisible(this.toolId),
         };
         let lastVisibleState = button.active;
         if (overlay.visible !== button.active) {
@@ -297,7 +245,7 @@ export const calculatorToolRegistration = {
             ],
             button,
             sync: () => {
-                const active = toolbarContext.isToolVisible(fullToolId);
+                const active = toolbarContext.isToolVisible(this.toolId);
                 button.active = active;
                 button.label = displayName;
                 // Static across the toggle. The previous `Close ${name.toLowerCase()}`
@@ -310,16 +258,13 @@ export const calculatorToolRegistration = {
                     overlay.visible = active;
                     lastVisibleState = active;
                 }
-                if (overlay.toolkitCoordinator !== toolbarContext.toolkitCoordinator) {
-                    overlay.toolkitCoordinator = toolbarContext.toolkitCoordinator;
-                }
-                applyCalculatorParamsToElement(overlay, calculatorType, availableTypes, providerId, calculatorConfig);
+                applyCalculatorParamsToElement(overlay, calculatorType, availableTypes, calculatorConfig);
             },
             subscribeActive: (callback) => {
                 if (!toolbarContext.subscribeVisibility)
                     return () => { };
                 return toolbarContext.subscribeVisibility(() => {
-                    callback(toolbarContext.isToolVisible(fullToolId));
+                    callback(toolbarContext.isToolVisible(this.toolId));
                 });
             },
         };

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

@@ -15,7 +15,7 @@
  * there without caret browsing, an OS toggle absent on mobile — so a selection-only
  * dictionary is unreachable for them. The panel's own field is the keyboard route.
  */
-import type { ToolRegistration } from "@pie-players/pie-assessment-toolkit/tools/internal";
+import type { ToolRegistration } from "@pie-players/pie-assessment-toolkit/tools/registration";
 /**
  * What distinguishes one dictionary capability from another.
  *
@@ -32,14 +32,15 @@ import type { ToolRegistration } from "@pie-players/pie-assessment-toolkit/tools
  * so a host catalog that lacks one is a plain label rather than a broken button.
  */
 export interface DictionaryVariantOptions {
-    /** Capability id, unique per language. Defaults to the base tool's id. */
+    /**
+     * Capability id, unique per language, and the PNP support id that grants it.
+     * Defaults to the base tool's id.
+     */
     toolId?: string;
     name?: string;
     description?: string;
     /** Catalog prefix for this variant's strings. Defaults to `tools.<toolId>`. */
     messageKeyPrefix?: string;
-    /** PNP ids that grant this variant. A language variant needs its own. */
-    pnpSupportIds?: string[];
     /**
      * The corpus language this capability looks words up in, as a BCP-47 tag.
      *
@@ -53,7 +54,7 @@ export interface DictionaryVariantOptions {
  * 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.
+ * `toolId` and `lookupLanguage` to offer a second language beside it.
  */
 export declare function createDictionaryToolRegistration(options?: DictionaryVariantOptions): ToolRegistration;
 /** The content-following dictionary every deployment gets. */

package/dist/registrations/dictionary-tools.js

@@ -15,7 +15,14 @@
  * 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";
+import { createScopedVisibilityBinding, createToolElement, hasReadableText, syncButtonAndOverlayVisibility, } from "@pie-players/pie-assessment-toolkit/tools/registration";
+import { resolveOverlayElement } from "./overlay-element-cache.js";
+/**
+ * The lookup fields each panel last took from render params. The panel outlives
+ * renders, so a field the host stops supplying is cleared here; a field it never
+ * supplied, such as one a component factory set, is left alone.
+ */
+const appliedLookupFields = new WeakMap();
 /**
  * Apply the host's per-tool render params to the panel.
  *
@@ -33,14 +40,23 @@ function applyLookupParams(element, toolId, toolbarContext,
 /** A language variant's own corpus language; see {@link DictionaryVariantOptions}. */
 lookupLanguage) {
     const params = toolbarContext.getToolRenderParams?.(toolId) ?? {};
+    const supplied = {};
     if (typeof params.endpoint === "string")
-        element.endpoint = params.endpoint;
+        supplied.endpoint = params.endpoint;
     if (typeof params.lookup === "function")
-        element.lookup = params.lookup;
+        supplied.lookup = params.lookup;
     if (typeof params.headers === "function")
-        element.headers = params.headers;
+        supplied.headers = params.headers;
     if (typeof params.credentials === "string")
-        element.credentials = params.credentials;
+        supplied.credentials = params.credentials;
+    // A dropped `lookup` left in place would keep outranking the endpoint that
+    // replaced it.
+    for (const field of appliedLookupFields.get(element) ?? []) {
+        if (!(field in supplied))
+            element[field] = undefined;
+    }
+    Object.assign(element, supplied);
+    appliedLookupFields.set(element, new Set(Object.keys(supplied)));
     // 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
@@ -81,7 +97,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 {
@@ -121,7 +137,7 @@ function renderDictionaryPanel(args) {
  * 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.
+ * `toolId` and `lookupLanguage` to offer a second language beside it.
  */
 export function createDictionaryToolRegistration(options = {}) {
     const toolId = options.toolId ?? "dictionary";
@@ -135,15 +151,6 @@ export function createDictionaryToolRegistration(options = {}) {
         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);
@@ -184,15 +191,6 @@ export function createPictureDictionaryToolRegistration(options = {}) {
         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);
         },
@@ -223,13 +221,11 @@ export const spanishDictionaryToolRegistration = createDictionaryToolRegistratio
     toolId: "dictionarySpanish",
     name: "Spanish Dictionary",
     description: "Look up word definitions in Spanish",
-    pnpSupportIds: ["spanishDictionary"],
     lookupLanguage: "es",
 });
 export const spanishPictureDictionaryToolRegistration = createPictureDictionaryToolRegistration({
     toolId: "pictureDictionarySpanish",
     name: "Spanish Picture Dictionary",
     description: "Look up pictures for words in Spanish",
-    pnpSupportIds: ["spanishPictureDictionary"],
     lookupLanguage: "es",
 });

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

@@ -3,14 +3,8 @@
  *
  * Registers tools for interacting with question content:
  * - Answer Eliminator (strike through answer choices)
- * - Highlighter (highlight text passages)
- *
- * Maps to QTI 3.0 standard access features:
- * - answerMasking (assessment tool)
- * - strikethrough (visual transformation)
- * - highlighting (cognitive/reading support)
  */
-import type { ToolRegistration } from "@pie-players/pie-assessment-toolkit/tools/internal";
+import type { ToolRegistration } from "@pie-players/pie-assessment-toolkit/tools/registration";
 /**
  * Answer Eliminator tool registration
  *

package/dist/registrations/interaction-tools.js

@@ -3,16 +3,28 @@
  *
  * Registers tools for interacting with question content:
  * - Answer Eliminator (strike through answer choices)
- * - Highlighter (highlight text passages)
- *
- * Maps to QTI 3.0 standard access features:
- * - answerMasking (assessment tool)
- * - strikethrough (visual transformation)
- * - highlighting (cognitive/reading support)
  */
-import { hasChoiceInteraction, hasReadableText, } 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 { hasChoiceInteraction } from "@pie-players/pie-assessment-toolkit/tools/registration";
+import { createToolElement, } from "@pie-players/pie-assessment-toolkit/tools/registration";
+import { createScopedVisibilityBinding, syncButtonAndOverlayVisibility, } from "@pie-players/pie-assessment-toolkit/tools/registration";
+import { resolveOverlayElement } from "./overlay-element-cache.js";
+/** `tools.providers.answerEliminator.strategy`, defaulting to strikethrough. */
+const normalizeEliminationStrategy = (value) => value === "mask" ? "mask" : "strikethrough";
+/** The state-store key of each PIE element in the item, by model id. */
+function resolveElementStateKeys(context, toolbarContext) {
+    const keys = {};
+    if (!("item" in context) || !toolbarContext.getGlobalElementId)
+        return keys;
+    for (const model of context.item?.config?.models ?? []) {
+        const elementId = model?.id;
+        if (typeof elementId !== "string" || !elementId)
+            continue;
+        const key = toolbarContext.getGlobalElementId(elementId);
+        if (key)
+            keys[elementId] = key;
+    }
+    return keys;
+}
 /**
  * Answer Eliminator tool registration
  *
@@ -28,13 +40,6 @@ export const answerEliminatorToolRegistration = {
     icon: "strikethrough",
     // Answer eliminator appears at item level only
     supportedLevels: ["item"],
-    // PNP support IDs
-    // Maps to QTI 3.0 standard feature: answerMasking
-    pnpSupportIds: [
-        "answerMasking", // QTI 3.0 standard (assessment.answerMasking)
-        "answerEliminator", // QTI 3.0 standard (assessment.answerEliminator)
-        "strikethrough", // QTI 3.0 standard (assessment.strikethrough)
-    ],
     /**
      * Pass 2: Answer eliminator is relevant only for choice-based questions
      */
@@ -55,10 +60,10 @@ 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");
+        overlay.setAttribute("strategy", normalizeEliminationStrategy(toolbarContext.toolkitCoordinator?.getToolConfig(this.toolId)?.strategy));
         const button = {
             toolId: this.toolId,
             label: this.name,
@@ -79,17 +84,8 @@ export const answerEliminatorToolRegistration = {
                     overlay,
                     isActive: visibility.isActive,
                 });
-                if (toolbarContext.toolCoordinator) {
-                    overlay.coordinator = toolbarContext.toolCoordinator;
-                }
                 overlay.scopeElement = toolbarContext.getScopeElement?.() || null;
-                if (toolbarContext.elementToolStateStore) {
-                    overlay.elementToolStateStore = toolbarContext.elementToolStateStore;
-                }
-                const globalElementId = toolbarContext.getGlobalElementId?.();
-                if (globalElementId) {
-                    overlay.globalElementId = globalElementId;
-                }
+                overlay.elementStateKeys = resolveElementStateKeys(context, toolbarContext);
             },
             subscribeActive: visibility.subscribeActive,
         };

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

@@ -2,12 +2,8 @@
  * Measurement Tools Registrations
  *
  * Registers ruler and protractor tools for on-screen measurements.
- *
- * Maps to QTI 3.0 standard access features:
- * - ruler (assessment tool)
- * - protractor (assessment tool)
  */
-import type { ToolRegistration } from "@pie-players/pie-assessment-toolkit/tools/internal";
+import type { ToolRegistration } from "@pie-players/pie-assessment-toolkit/tools/registration";
 /**
  * Ruler tool registration
  *

package/dist/registrations/measurement-tools.js

@@ -2,14 +2,8 @@
  * Measurement Tools Registrations
  *
  * Registers ruler and protractor tools for on-screen measurements.
- *
- * Maps to QTI 3.0 standard access features:
- * - ruler (assessment tool)
- * - 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 { hasMathContent } from "@pie-players/pie-assessment-toolkit/tools/registration";
 import { renderOverlayToolbar } from "./overlay-toolbar-render.js";
 /**
  * Ruler tool registration
@@ -26,11 +20,6 @@ export const rulerToolRegistration = {
     icon: "ruler",
     // Ruler typically appears at section/item/element level
     supportedLevels: ["section", "item", "element"],
-    // PNP support IDs
-    // Maps to QTI 3.0 standard feature: ruler
-    pnpSupportIds: [
-        "ruler", // QTI 3.0 standard (assessment.ruler)
-    ],
     /**
      * Pass 2: Ruler is relevant when math content is present
      */
@@ -40,7 +29,6 @@ export const rulerToolRegistration = {
     renderToolbar(context, toolbarContext) {
         return renderOverlayToolbar(this, context, toolbarContext, {
             surface: "frameless",
-            handsOverCoordinator: true,
         });
     },
 };
@@ -59,11 +47,6 @@ export const protractorToolRegistration = {
     icon: "protractor",
     // Protractor typically appears at section/item/element level
     supportedLevels: ["section", "item", "element"],
-    // PNP support IDs
-    // Maps to QTI 3.0 standard feature: protractor
-    pnpSupportIds: [
-        "protractor", // QTI 3.0 standard (assessment.protractor)
-    ],
     /**
      * Pass 2: Protractor is relevant when math content is present
      */
@@ -73,7 +56,6 @@ export const protractorToolRegistration = {
     renderToolbar(context, toolbarContext) {
         return renderOverlayToolbar(this, context, toolbarContext, {
             surface: "frameless",
-            handsOverCoordinator: true,
         });
     },
 };

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

@@ -0,0 +1,23 @@
+/**
+ * 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/registration";
+/** The property the toolbar calls as it unmounts a tool element. */
+export declare const TOOL_ELEMENT_UNMOUNT_CALLBACK_PROP = "__pieToolElementUnmount";
+/**
+ * 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,48 @@
+/**
+ * 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.
+ */
+/** The property the toolbar calls as it unmounts a tool element. */
+export const TOOL_ELEMENT_UNMOUNT_CALLBACK_PROP = "__pieToolElementUnmount";
+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.d.ts

@@ -3,9 +3,8 @@
  * 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
+ * two options below and nothing else: whether the overlay paints its own chrome
+ * or takes a draggable window, and that window's size. 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,
@@ -16,7 +15,7 @@
  * 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";
+import { type ToolContext, type ToolRegistration, type ToolToolbarRenderResult, type ToolbarContext } from "@pie-players/pie-assessment-toolkit/tools/registration";
 /** A window's geometry. Absent for overlays that paint their own chrome. */
 export interface OverlayToolShell {
     resizable: boolean;
@@ -33,11 +32,5 @@ export interface RenderOverlayToolbarOptions {
     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

@@ -3,9 +3,8 @@
  * 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
+ * two options below and nothing else: whether the overlay paints its own chrome
+ * or takes a draggable window, and that window's size. 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,
@@ -16,7 +15,8 @@
  * 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";
+import { applyOverlaySurface, createScopedVisibilityBinding, createToolElement, resolveToolRegistrationName, syncButtonAndOverlayVisibility, } from "@pie-players/pie-assessment-toolkit/tools/registration";
+import { resolveOverlayElement } from "./overlay-element-cache.js";
 export function renderOverlayToolbar(registration, context, toolbarContext, options = {}) {
     const { toolId } = registration;
     const visibility = createScopedVisibilityBinding(toolId, toolbarContext);
@@ -34,7 +34,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");
@@ -73,9 +73,6 @@ export function renderOverlayToolbar(registration, context, toolbarContext, opti
                 overlay,
                 isActive: visibility.isActive,
             });
-            if (options.handsOverCoordinator && toolbarContext.toolkitCoordinator) {
-                overlay.toolkitCoordinator = toolbarContext.toolkitCoordinator;
-            }
         },
         subscribeActive: visibility.subscribeActive,
     };

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

@@ -12,7 +12,7 @@
  * 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";
+import type { ToolSelectionAction, ToolSurfaceServices } from "@pie-players/pie-assessment-toolkit/tools/registration";
 /**
  * Actions for the gateway to render, given the services it was handed.
  *