@pie-players/pie-assessment-toolkit 0.3.73 → 0.3.75

package/dist/services/ToolRegistry.js

@@ -5,7 +5,8 @@
  * and button/instance creation. Supports dynamic registration and override by integrators.
  */
 import { dynamicMessageKey } from "@pie-players/pie-players-shared/i18n/provider";
-import { normalizeToolAlias } from "./tools-config-normalizer.js";
+import { resolveToolTag, } from "../tools/tool-tag-map.js";
+import { PENDING_INPUT_WARNING_DELAY_MS, warnOncePerDocument, } from "../runtime/page-warnings.js";
 /**
  * A registration's display name in the interface locale.
  *
@@ -13,16 +14,12 @@ import { normalizeToolAlias } from "./tools-config-normalizer.js";
  * falls back to `name` rather than rendering the key, so a catalog gap degrades
  * to English instead of to `tools.something.name` on a toolbar button.
  *
- * Both display resolvers live here so the toolbars, the settings panels and the
- * PNP debugger cannot each invent their own precedence.
+ * It lives here so the toolbars, the settings panels and the PNP debugger
+ * cannot each invent their own precedence.
  */
 export function resolveToolRegistrationName(registration, i18n) {
     return resolveKeyedString(registration.name, registration.nameKey, i18n);
 }
-/** A registration's description in the interface locale. See the name resolver. */
-export function resolveToolRegistrationDescription(registration, i18n) {
-    return resolveKeyedString(registration.description, registration.descriptionKey, i18n);
-}
 function resolveKeyedString(source, key, i18n) {
     if (!key || !i18n)
         return source;
@@ -50,7 +47,7 @@ function assertNonEmptyString(value, fieldName) {
 }
 // Defence-in-depth: reject obvious XSS payloads in tool-registered icon
 // markup at registration time. Runtime rendering still runs each icon
-// through DOMPurify (see `ToolIcon.svelte`), but surfacing the problem
+// through DOMPurify (`sanitizeSvgIcon` in `ItemToolBar.svelte`), but surfacing the problem
 // early produces a clearer error for tool authors than "the icon silently
 // disappeared after sanitization".
 const SCRIPTABLE_ICON_PATTERNS = [
@@ -151,11 +148,6 @@ function assertToolRegistrationShape(registration) {
         registration.singletonScope !== "section") {
         throw new Error(`Invalid tool registration "${registration.toolId}": selection-gateway tools must declare singletonScope "section".`);
     }
-    if (registration.pnpSupportIds !== undefined &&
-        (!Array.isArray(registration.pnpSupportIds) ||
-            registration.pnpSupportIds.some((pnpId) => typeof pnpId !== "string" || pnpId.trim().length === 0))) {
-        throw new Error(`Invalid tool registration "${registration.toolId}": "pnpSupportIds" must be an array of non-empty strings.`);
-    }
     if (registration.activation !== "region" &&
         typeof registration.isVisibleInContext !== "function") {
         throw new Error(`Invalid tool registration "${registration.toolId}": "isVisibleInContext" must be a function.`);
@@ -174,12 +166,6 @@ function assertToolRegistrationShape(registration) {
             typeof registration.requiresAuthoredContent.resolve !== "function") {
             throw new Error(`Invalid tool registration "${registration.toolId}": "requiresAuthoredContent" must be an object with a "resolve" function.`);
         }
-        if (!registration.pnpSupportIds?.length) {
-            // A content dependency's second job is keeping the capability out of a
-            // wholesale grant, and a host filters that by support id. Declaring one
-            // with no id to filter on would silently drop that guarantee.
-            throw new Error(`Invalid tool registration "${registration.toolId}": "requiresAuthoredContent" requires at least one entry in "pnpSupportIds", which is what a host filters a default grant list on.`);
-        }
     }
     if (registration.renderToolbar !== undefined) {
         if (typeof registration.renderToolbar !== "function") {
@@ -197,10 +183,12 @@ function assertToolRegistrationShape(registration) {
  */
 export class ToolRegistry {
     tools = new Map();
-    pnpIndex = new Map(); // pnpSupportId → Set<toolId>
     componentOverrides = {};
+    watchedUndefinedToolElements = new Set();
     moduleLoaders = new Map();
     loadedToolModules = new Set();
+    warnedLoaderReplacements = new Set();
+    warnedUnregisteredAllowedTools = new Set();
     moduleLoadPromises = new Map();
     changeListeners = new Set();
     emitChange(event) {
@@ -228,13 +216,13 @@ export class ToolRegistry {
         };
     }
     /**
-     * Normalize a single tool alias to canonical toolId.
+     * Normalize a single tool id (trims surrounding whitespace).
      */
     normalizeToolId(toolId) {
-        return normalizeToolAlias(toolId);
+        return toolId.trim();
     }
     /**
-     * Normalize a list of tool aliases to canonical toolIds.
+     * Normalize a list of tool ids (trims surrounding whitespace).
      */
     normalizeToolIds(toolIds) {
         return toolIds.map((toolId) => this.normalizeToolId(toolId));
@@ -251,15 +239,6 @@ export class ToolRegistry {
             throw new Error(`Tool '${registration.toolId}' is already registered`);
         }
         this.tools.set(registration.toolId, registration);
-        // Index PNP support IDs
-        if (registration.pnpSupportIds) {
-            for (const pnpId of registration.pnpSupportIds) {
-                if (!this.pnpIndex.has(pnpId)) {
-                    this.pnpIndex.set(pnpId, new Set());
-                }
-                this.pnpIndex.get(pnpId).add(registration.toolId);
-            }
-        }
         this.emitChange({ kind: "register", toolIds: [registration.toolId] });
     }
     /**
@@ -272,24 +251,7 @@ export class ToolRegistry {
         if (!this.tools.has(registration.toolId)) {
             throw new Error(`Cannot override non-existent tool '${registration.toolId}'`);
         }
-        // Remove old PNP index entries
-        const oldReg = this.tools.get(registration.toolId);
-        if (oldReg.pnpSupportIds) {
-            for (const pnpId of oldReg.pnpSupportIds) {
-                this.pnpIndex.get(pnpId)?.delete(registration.toolId);
-            }
-        }
-        // Add new registration
         this.tools.set(registration.toolId, registration);
-        // Re-index PNP support IDs
-        if (registration.pnpSupportIds) {
-            for (const pnpId of registration.pnpSupportIds) {
-                if (!this.pnpIndex.has(pnpId)) {
-                    this.pnpIndex.set(pnpId, new Set());
-                }
-                this.pnpIndex.get(pnpId).add(registration.toolId);
-            }
-        }
         this.emitChange({ kind: "override", toolIds: [registration.toolId] });
     }
     /**
@@ -298,15 +260,8 @@ export class ToolRegistry {
      * @param toolId - Tool ID to remove
      */
     unregister(toolId) {
-        const reg = this.tools.get(toolId);
-        if (!reg)
+        if (!this.tools.has(toolId))
             return;
-        // Remove PNP index entries
-        if (reg.pnpSupportIds) {
-            for (const pnpId of reg.pnpSupportIds) {
-                this.pnpIndex.get(pnpId)?.delete(toolId);
-            }
-        }
         this.tools.delete(toolId);
         this.emitChange({ kind: "unregister", toolIds: [toolId] });
     }
@@ -344,15 +299,6 @@ export class ToolRegistry {
     getAllTools() {
         return Array.from(this.tools.values());
     }
-    /**
-     * Find tool IDs that support a given PNP support ID
-     *
-     * @param pnpSupportId - PNP support ID (e.g., 'calculator')
-     * @returns Set of tool IDs that support this PNP ID
-     */
-    getToolsByPNPSupport(pnpSupportId) {
-        return this.pnpIndex.get(pnpSupportId) || new Set();
-    }
     /**
      * Get tools that support a specific level
      *
@@ -389,21 +335,18 @@ export class ToolRegistry {
             tool.surfaces?.includes(surface));
     }
     /**
-     * Support ids belonging to capabilities that need authored content.
+     * Support ids, which are tool ids, of the capabilities that need authored
+     * content.
      *
-     * What a host filters a default grant list on, in place of the compile-time
-     * exclusion array this replaced: granting one of these wholesale grants an
-     * accommodation to learners with no documented need for it.
+     * What a host filters a default grant list on: granting one of these
+     * wholesale grants an accommodation to learners with no documented need
+     * for it.
      */
     getContentDependentSupportIds() {
-        const ids = new Set();
-        for (const tool of this.getAllTools()) {
-            if (!tool.requiresAuthoredContent)
-                continue;
-            for (const supportId of tool.pnpSupportIds || [])
-                ids.add(supportId);
-        }
-        return [...ids].sort();
+        return this.getAllTools()
+            .filter((tool) => tool.requiresAuthoredContent)
+            .map((tool) => tool.toolId)
+            .sort();
     }
     /**
      * Filter tool IDs by activation type.
@@ -414,7 +357,7 @@ export class ToolRegistry {
     /**
      * Filter tools by visibility in a given context
      *
-     * Pass 2 of the two-pass model: Given a list of allowed tool IDs (from Pass 1),
+     * Pass 2 of the three-pass model: Given a list of allowed tool IDs (from Pass 1),
      * ask each tool if it's relevant in this context.
      *
      * @param allowedToolIds - Tool IDs that passed Pass 1 (orchestrator approval)
@@ -426,7 +369,11 @@ export class ToolRegistry {
         for (const toolId of allowedToolIds) {
             const tool = this.get(toolId);
             if (!tool) {
-                console.warn(`Tool '${toolId}' is allowed but not registered`);
+                // Toolbars filter on every render; one warning per id carries it.
+                if (!this.warnedUnregisteredAllowedTools.has(toolId)) {
+                    this.warnedUnregisteredAllowedTools.add(toolId);
+                    console.warn(`Tool '${toolId}' is allowed but not registered`);
+                }
                 continue;
             }
             // Check if tool supports this level
@@ -480,14 +427,13 @@ export class ToolRegistry {
      * Get tool metadata for building UIs
      * Useful for building PNP configuration interfaces
      *
-     * @returns Array of tool metadata (id, name, description, pnpSupportIds)
+     * @returns Array of tool metadata (id, name, description, levels, activation)
      */
     getToolMetadata() {
         return this.getAllTools().map((tool) => ({
             toolId: tool.toolId,
             name: tool.name,
             description: tool.description,
-            pnpSupportIds: tool.pnpSupportIds || [],
             supportedLevels: tool.supportedLevels,
             activation: tool.activation || "toolbar-toggle",
             singletonScope: tool.singletonScope || null,
@@ -496,25 +442,6 @@ export class ToolRegistry {
             contentDependencyDescription: tool.requiresAuthoredContent?.description ?? null,
         }));
     }
-    /**
-     * Generate PNP support IDs from enabled tools
-     * Useful for creating PNP profiles
-     *
-     * @param enabledToolIds - Tool IDs to enable
-     * @returns Array of unique PNP support IDs
-     */
-    generatePNPSupportsFromTools(enabledToolIds) {
-        const pnpSupports = new Set();
-        for (const toolId of enabledToolIds) {
-            const tool = this.get(toolId);
-            if (tool?.pnpSupportIds) {
-                for (const pnpId of tool.pnpSupportIds) {
-                    pnpSupports.add(pnpId);
-                }
-            }
-        }
-        return Array.from(pnpSupports);
-    }
     /**
      * Clear all registrations (useful for testing)
      */
@@ -523,7 +450,6 @@ export class ToolRegistry {
         if (toolIds.length === 0)
             return;
         this.tools.clear();
-        this.pnpIndex.clear();
         this.emitChange({ kind: "clear", toolIds });
     }
     /**
@@ -538,6 +464,8 @@ export class ToolRegistry {
     /**
      * Register lazy module loaders by toolId.
      * Toolbars call ensureToolModuleLoaded(toolId) before instance creation.
+     * A tool whose module has loaded, or is loading, keeps its loader: its
+     * elements are already defined, so a replacement could never take effect.
      */
     setToolModuleLoaders(loaders) {
         const entries = Object.entries(loaders).filter((entry) => entry[1] !== undefined);
@@ -551,6 +479,11 @@ export class ToolRegistry {
         for (const [toolId, loader] of entries) {
             if (this.moduleLoaders.get(toolId) === loader)
                 continue;
+            if (this.loadedToolModules.has(toolId) ||
+                this.moduleLoadPromises.has(toolId)) {
+                this.warnLoaderReplacedAfterLoad(toolId);
+                continue;
+            }
             this.moduleLoaders.set(toolId, loader);
             changedToolIds.push(toolId);
         }
@@ -558,6 +491,12 @@ export class ToolRegistry {
             this.emitChange({ kind: "module-loaders", toolIds: changedToolIds });
         }
     }
+    warnLoaderReplacedAfterLoad(toolId) {
+        if (this.warnedLoaderReplacements.has(toolId))
+            return;
+        this.warnedLoaderReplacements.add(toolId);
+        console.warn(`[ToolRegistry] Ignored a new module loader for "${toolId}": its module already loaded, so the elements it defines stay in place. Register loaders before the tool first renders.`);
+    }
     /**
      * Ensure tool module side-effects are loaded exactly once.
      * Safe to call repeatedly; concurrent callers share the same promise.
@@ -571,11 +510,14 @@ export class ToolRegistry {
             return;
         }
         const loader = this.moduleLoaders.get(toolId);
-        if (!loader)
+        if (!loader) {
+            this.watchUndefinedToolElement(toolId);
             return;
+        }
         const loadPromise = (async () => {
             await loader();
             this.loadedToolModules.add(toolId);
+            this.warnIfLoadedToolElementUndefined(toolId);
         })();
         this.moduleLoadPromises.set(toolId, loadPromise);
         try {
@@ -586,10 +528,70 @@ export class ToolRegistry {
         }
     }
     /**
-     * Ensure a set of tool modules are loaded.
+     * The undefined element tag a tool would render, or `null` when the tool is
+     * built by a component factory, its element is defined, or there is no DOM.
+     */
+    undefinedToolElementTag(toolId) {
+        if (typeof customElements === "undefined" || typeof document === "undefined") {
+            return null;
+        }
+        const overrides = this.componentOverrides;
+        if (overrides.toolComponentFactories?.[toolId])
+            return null;
+        let tagName;
+        try {
+            tagName = resolveToolTag(toolId, overrides);
+        }
+        catch {
+            // Element creation reports the missing tag mapping.
+            return null;
+        }
+        return customElements.get(tagName) ? null : tagName;
+    }
+    /**
+     * Warn when a tool's module loader finished without defining the element the
+     * tag map points the tool at, as when a host remaps the tag but keeps a
+     * loader that defines the packaged element. The tool otherwise renders blank.
+     */
+    warnIfLoadedToolElementUndefined(toolId) {
+        const tagName = this.undefinedToolElementTag(toolId);
+        if (!tagName)
+            return;
+        warnOncePerDocument(document, `loadedToolElementUndefined.${toolId}.${tagName}`, `[ToolRegistry] Tool "${toolId}" renders <${tagName}>, but its module loader finished without defining it, so the tool renders blank. The tag map and the loader disagree: map "${toolId}" to the tag its loader defines, or register a loader that defines <${tagName}>. Reported once per page.`);
+    }
+    /**
+     * Warn when a tool with no module loader still has no element definition
+     * after the pending-input delay. A registry built without loaders otherwise
+     * renders the tool as an unknown element with no error.
+     */
+    watchUndefinedToolElement(toolId) {
+        if (this.watchedUndefinedToolElements.has(toolId))
+            return;
+        const tagName = this.undefinedToolElementTag(toolId);
+        if (!tagName)
+            return;
+        this.watchedUndefinedToolElements.add(toolId);
+        const doc = document;
+        const timer = setTimeout(() => {
+            if (customElements.get(tagName))
+                return;
+            warnOncePerDocument(doc, `undefinedToolElement.${toolId}`, `[ToolRegistry] Tool "${toolId}" renders <${tagName}>, which is still undefined after ${PENDING_INPUT_WARNING_DELAY_MS / 1000} s, and its registry has no module loader for it. Pass toolModuleLoaders to createPackagedToolRegistry (DEFAULT_TOOL_MODULE_LOADERS from @pie-players/pie-default-tool-loaders loads the stock tools), register one with setToolModuleLoaders, or import the tool's package before it renders. Reported once per page.`);
+        }, PENDING_INPUT_WARNING_DELAY_MS);
+        void customElements.whenDefined(tagName).then(() => clearTimeout(timer));
+    }
+    /**
+     * Load a set of tool modules, each to completion, and resolve with the error
+     * of every tool whose module failed, by tool id. One failure leaves the other
+     * tools loaded and usable. A failed tool is retried on the next call.
      */
     async ensureToolModulesLoaded(toolIds) {
-        await Promise.all(toolIds.map((toolId) => this.ensureToolModuleLoaded(toolId)));
+        const results = await Promise.allSettled(toolIds.map((toolId) => this.ensureToolModuleLoaded(toolId)));
+        const failures = new Map();
+        results.forEach((result, index) => {
+            if (result.status === "rejected")
+                failures.set(toolIds[index], result.reason);
+        });
+        return failures;
     }
     /**
      * Whether a tool module has already been loaded.