@pie-players/pie-assessment-toolkit 0.3.74 → 1.0.0-beta.0

package/dist/services/ToolRegistry.js

@@ -1,27 +1,20 @@
 /**
- * Tool Registry
+ * Tool registry: the registration contract every tool declares itself with,
+ * the shape validation `register` and `override` run, and the `ToolRegistry`
+ * class.
  *
- * Central registry for all assessment tools. Manages tool metadata, visibility logic,
- * and button/instance creation. Supports dynamic registration and override by integrators.
+ * Layout: the exported contract types come first, ending with
+ * `ToolRegistration`, then `assertToolRegistrationShape`, then the class. Its
+ * members run from mutation and change observation, through queries and the
+ * filters for the second and third passes of tool resolution (relevance in
+ * `filterVisibleInContext`, applicability in `filterDecidedToolIds`; the policy
+ * engine owns the first), to module loading with its undefined-element
+ * warnings and the toolbar and surface render helpers.
  */
 import { dynamicMessageKey } from "@pie-players/pie-players-shared/i18n/provider";
-import { normalizeToolAlias } from "./tools-config-normalizer.js";
-/**
- * The id a registration's provider registers under for one tool config: the
- * descriptor's answer, then the config's `provider.id`, then the tool id. `null`
- * when the registration carries no provider.
- *
- * The coordinator registers providers under this id and the section player looks
- * for them in a host-supplied coordinator by it, so the two resolve it one way.
- */
-export function resolveToolProviderId(registration, config) {
-    const descriptor = registration.provider;
-    if (!descriptor)
-        return null;
-    return (descriptor.getProviderId?.(config) ??
-        config?.provider?.id ??
-        registration.toolId);
-}
+import { resolveToolTag, } from "../tools/tool-tag-map.js";
+import { PENDING_INPUT_WARNING_DELAY_MS, warnOncePerDocument, } from "../runtime/page-warnings.js";
+const logToolCallbackFailure = (toolId, phase, error) => console.error(`[ToolRegistry] Tool '${toolId}' ${phase} check threw:`, error);
 /**
  * A registration's display name in the interface locale.
  *
@@ -163,11 +156,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.`);
@@ -186,12 +174,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") {
@@ -209,10 +191,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) {
@@ -240,22 +224,19 @@ 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));
     }
     /**
-     * Register a tool
-     *
-     * @param registration - Tool registration
-     * @throws Error if toolId is already registered
+     * Register a tool. Throws when its `toolId` is already registered.
      */
     register(registration) {
         assertToolRegistrationShape(registration);
@@ -263,114 +244,44 @@ 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] });
     }
     /**
-     * Override an existing tool registration
-     *
-     * @param registration - New tool registration (must have existing toolId)
+     * Replace an existing tool registration. Throws when its `toolId` is not
+     * registered.
      */
     override(registration) {
         assertToolRegistrationShape(registration);
         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] });
     }
     /**
-     * Unregister a tool
-     *
-     * @param toolId - Tool ID to remove
+     * Unregister a tool. An unknown id is a no-op and emits no change.
      */
     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] });
     }
-    /**
-     * Get a tool registration by ID
-     *
-     * @param toolId - Tool ID
-     * @returns Tool registration or undefined
-     */
     get(toolId) {
         return this.tools.get(toolId);
     }
-    /**
-     * Check if a tool is registered
-     *
-     * @param toolId - Tool ID
-     * @returns true if registered
-     */
     has(toolId) {
         return this.tools.has(toolId);
     }
-    /**
-     * Get all registered tool IDs
-     *
-     * @returns Array of tool IDs
-     */
+    /** Registered tool ids, in registration order. */
     getAllToolIds() {
         return Array.from(this.tools.keys());
     }
-    /**
-     * Get all tool registrations
-     *
-     * @returns Array of tool registrations
-     */
+    /** Registrations, in registration order. */
     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
-     *
-     * @param level - Tool level (assessment, section, item, passage, element)
-     * @returns Array of tool registrations that support this level
-     */
+    /** Registrations whose `supportedLevels` include `level`. */
     getToolsByLevel(level) {
         return this.getAllTools().filter((tool) => tool.supportedLevels.includes(level));
     }
@@ -401,21 +312,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.
@@ -424,36 +332,37 @@ export class ToolRegistry {
         return toolIds.filter((toolId) => this.getToolActivation(toolId) === activation);
     }
     /**
-     * Filter tools by visibility in a given context
+     * Pass 2 of tool resolution: the registrations among `allowedToolIds` (the
+     * ids policy allowed in pass 1) that support `context.level` and answer
+     * `isVisibleInContext` with `true`.
      *
-     * Pass 2 of the two-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)
-     * @param context - Context to evaluate
-     * @returns Array of visible tool registrations
+     * @param onFailure - Receives a relevance check's throw; the tool is then not
+     *   visible. Logs when omitted.
      */
-    filterVisibleInContext(allowedToolIds, context) {
+    filterVisibleInContext(allowedToolIds, context, onFailure = logToolCallbackFailure) {
         const visible = [];
         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
             if (!tool.supportedLevels.includes(context.level)) {
                 continue;
             }
-            // Pass 2: Ask tool if it's relevant. A region capability declares no
-            // answer and has no toolbar presence, so it is never visible here.
+            // A region capability declares no answer and has no toolbar presence,
+            // so it is never visible here.
             try {
                 if (tool.isVisibleInContext?.(context)) {
                     visible.push(tool);
                 }
             }
             catch (error) {
-                console.error(`Error evaluating visibility for tool '${toolId}':`, error);
+                onFailure(toolId, "tool-visibility", error);
             }
         }
         return visible;
@@ -470,8 +379,10 @@ export class ToolRegistry {
      *
      * @param toolId - Tool to ask
      * @param contexts - Every context the tool could act on at this placement
+     * @param onFailure - Receives the gate's throw; the tool then counts as
+     *   applicable. Logs when omitted.
      */
-    isApplicableToAnyContext(toolId, contexts) {
+    isApplicableToAnyContext(toolId, contexts, onFailure = logToolCallbackFailure) {
         const tool = this.get(toolId);
         if (!tool?.isApplicableToContent)
             return true;
@@ -482,24 +393,70 @@ export class ToolRegistry {
                 return tool.isApplicableToContent?.(context) ?? true;
             }
             catch (error) {
-                console.error(`Error evaluating applicability for tool '${toolId}':`, error);
+                onFailure(toolId, "tool-applicability", error);
                 // A gate that throws has not established that the tool is useless.
                 return true;
             }
         });
     }
     /**
-     * Get tool metadata for building UIs
-     * Useful for building PNP configuration interfaces
+     * Passes 2 and 3 over a policy decision's tools: the ids a surface at `level`
+     * shows against `contexts`, in decision order. This is the rule a toolbar
+     * applies, for a host that builds its own tool surface.
      *
-     * @returns Array of tool metadata (id, name, description, pnpSupportIds)
+     * - A tool that does not support `level` is dropped.
+     * - Relevance (`isVisibleInContext`) keeps a tool visible in any one context.
+     *   It does not run for a granted entry (`required` or `alwaysAvailable`),
+     *   at section level, whose relevance is item-dependent, or when `contexts`
+     *   is empty, since content that has not resolved cannot rule a tool out.
+     * - Applicability (`isApplicableToContent`) then removes a tool that can act
+     *   on none of `contexts`, granted or not. It does not run at section level.
+     *
+     * @param entries - The decision's surviving entries (Pass 1), such as
+     *   `ToolPolicyDecision.visibleTools`
+     * @param level - The level of the surface the tools render on
+     * @param contexts - Every context the tools could act on at that surface
+     * @param onFailure - Receives a relevance or applicability check's throw.
+     *   Logs when omitted.
+     */
+    filterDecidedToolIds(entries, level, contexts, onFailure = logToolCallbackFailure) {
+        const granted = new Set();
+        const decided = [];
+        for (const entry of entries) {
+            const toolId = this.normalizeToolId(entry.toolId);
+            if (!toolId)
+                continue;
+            if (entry.required || entry.alwaysAvailable)
+                granted.add(toolId);
+            if (decided.includes(toolId))
+                continue;
+            if (!this.get(toolId)?.supportedLevels.includes(level))
+                continue;
+            decided.push(toolId);
+        }
+        if (level === "section")
+            return decided;
+        const relevant = new Set(contexts.length === 0
+            ? decided
+            : decided.filter((toolId) => granted.has(toolId)));
+        for (const context of contexts) {
+            const ungranted = decided.filter((toolId) => !relevant.has(toolId));
+            for (const tool of this.filterVisibleInContext(ungranted, context, onFailure)) {
+                relevant.add(tool.toolId);
+            }
+        }
+        return decided.filter((toolId) => relevant.has(toolId) &&
+            this.isApplicableToAnyContext(toolId, contexts, onFailure));
+    }
+    /**
+     * Plain metadata for every registration, in registration order, for UIs
+     * such as a PNP configuration screen.
      */
     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,
@@ -508,25 +465,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)
      */
@@ -535,7 +473,6 @@ export class ToolRegistry {
         if (toolIds.length === 0)
             return;
         this.tools.clear();
-        this.pnpIndex.clear();
         this.emitChange({ kind: "clear", toolIds });
     }
     /**
@@ -550,6 +487,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);
@@ -563,6 +502,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);
         }
@@ -570,6 +514,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.
@@ -583,11 +533,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 {
@@ -598,10 +551,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. Register one with setToolModuleLoaders or import the tool's package before it renders; a registry from createPackagedToolRegistry has the packaged loaders unless its toolModuleLoaders replaced them. 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.
@@ -625,10 +638,7 @@ export class ToolRegistry {
         }
         const mergedContext = {
             ...toolbarContext,
-            componentOverrides: {
-                ...(this.componentOverrides || {}),
-                ...(toolbarContext.componentOverrides || {}),
-            },
+            componentOverrides: this.mergeComponentOverrides(toolbarContext.componentOverrides),
         };
         return tool.renderToolbar(context, mergedContext);
     }
@@ -651,10 +661,14 @@ export class ToolRegistry {
         }
         return tool.renderSurface({
             ...context,
-            componentOverrides: {
-                ...(this.componentOverrides || {}),
-                ...(context.componentOverrides || {}),
-            },
+            componentOverrides: this.mergeComponentOverrides(context.componentOverrides),
         });
     }
+    /** The registry's component overrides, with the caller's taking precedence. */
+    mergeComponentOverrides(contextOverrides) {
+        return {
+            ...(this.componentOverrides || {}),
+            ...(contextOverrides || {}),
+        };
+    }
 }