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

package/dist/services/ToolRegistry.d.ts

@@ -7,7 +7,7 @@
 import type { I18nProvider } from "@pie-players/pie-players-shared/i18n/types";
 import type { CatalogOwnerSnapshot } from "./AccessibilityCatalogResolver.js";
 import type { ToolContext, ToolLevel } from "./tool-context.js";
-import type { ToolComponentOverrides } from "../tools/tool-tag-map.js";
+import { type ToolComponentOverrides } from "../tools/tool-tag-map.js";
 import type { AccessibilityCatalogResolverApi, ElementToolStateStoreApi, ToolCoordinatorApi, ToolkitCoordinatorApi, TtsServiceApi } from "./interfaces.js";
 import type { ToolProviderApi } from "./tool-providers/ToolProviderApi.js";
 import type { ToolProviderConfig as ToolRuntimeConfig } from "./tools-config-normalizer.js";
@@ -65,9 +65,10 @@ export interface ToolbarContext {
      * Content-alternate language: which authored alternate the catalog resolver
      * should select. Not the interface locale — see {@link ToolbarContext.i18n}. The
      * two are independent by QTI 3's own statement, and conflating them is how a
-     * Spanish passage ends up forcing Spanish widget chrome.
+     * Spanish passage ends up forcing Spanish widget chrome. Absent when neither
+     * the toolbar's `language` nor the host's `content-language` names one.
      */
-    language: string;
+    language?: string;
     /**
      * Interface-locale provider for this capability's own UI strings.
      *
@@ -83,12 +84,19 @@ export interface ToolbarContext {
         size?: string;
     };
     getScopeElement?: () => HTMLElement | null;
-    getGlobalElementId?: () => string | null;
+    /**
+     * State key of one PIE element in this toolbar's item, by its model id, for
+     * `elementToolStateStore`. `null` until the store and the ids it needs are
+     * known.
+     */
+    getGlobalElementId?: (elementId: string) => string | null;
     toolCoordinator: ToolCoordinatorApi | null;
     toolkitCoordinator: ToolkitCoordinatorApi | null;
     ttsService: TtsServiceApi | null;
     elementToolStateStore: ElementToolStateStoreApi | null;
+    /** Toggles this toolbar's instance of a base tool id. */
     toggleTool: (toolId: string) => void;
+    /** Whether this toolbar's instance of a base tool id is shown. */
     isToolVisible: (toolId: string) => boolean;
     subscribeVisibility: ((listener: () => void) => () => void) | null;
     componentOverrides?: ToolComponentOverrides;
@@ -207,24 +215,18 @@ export interface HostedToolSize {
     width: number;
     height: number;
 }
+/**
+ * How the coordinator builds a tool's provider from the tool's config. The
+ * provider registers under the tool's own id, so `ensureProviderReady(toolId)`
+ * finds it; `provider.id` in the config selects an implementation and never
+ * renames the registration.
+ */
 export interface ToolProviderDescriptor {
-    getProviderId?: (config: ToolRuntimeConfig | undefined) => string;
     createProvider: (config: ToolRuntimeConfig | undefined) => ToolProviderApi;
     getInitConfig?: (config: ToolRuntimeConfig | undefined) => Record<string, unknown>;
-    sanitizeConfig?: (config: ToolRuntimeConfig) => ToolRuntimeConfig;
-    validateConfig?: (config: ToolRuntimeConfig) => ToolConfigDiagnostic[];
     getAuthFetcher?: (config: ToolRuntimeConfig | undefined) => (() => Promise<Record<string, unknown>>) | undefined;
     lazy?: boolean;
 }
-/**
- * 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 declare function resolveToolProviderId(registration: Pick<ToolRegistration, "toolId" | "provider">, config: ToolRuntimeConfig | undefined): string | null;
 export interface ToolToolbarRenderResult {
     toolId: string;
     elements?: ToolRenderElement[];
@@ -280,8 +282,14 @@ export interface ToolSurfaceServices {
  */
 export interface ToolSurfaceRenderContext {
     toolId: string;
-    /** The PNP/AfA support id policy granted for this render. */
-    featureId: string;
+    /**
+     * Whether a PNP support, a requirement or a test-administration override
+     * granted the capability. `false` for a capability rendered because it is
+     * placed with no grant, and for a
+     * {@link ToolRegistration.resolvesWithoutGrant} capability answering from
+     * content alone.
+     */
+    granted: boolean;
     /** Host slot being filled. */
     surface: string;
     /** Feature parameters from the policy decision, if any. */
@@ -296,8 +304,6 @@ export interface ToolSurfaceRenderContext {
  * present.
  */
 export interface ToolContentDependencyContext {
-    /** The PNP/AfA support id being resolved. */
-    featureId: string;
     /** Feature parameters from the policy decision, if any. */
     parameters?: unknown;
     /**
@@ -309,7 +315,7 @@ export interface ToolContentDependencyContext {
      */
     catalogs: CatalogOwnerSnapshot | null;
     /**
-     * Whether policy granted one of this capability's support ids.
+     * Whether policy granted this capability's support id.
      *
      * `false` reaches `resolve` only for a capability that declares
      * {@link ToolRegistration.resolvesWithoutGrant}, and it is the signal that the
@@ -448,12 +454,6 @@ export interface ToolRegistration {
      * Optional singleton scope for activation models that mount exactly one instance.
      */
     singletonScope?: ToolSingletonScope;
-    /**
-     * PNP support IDs that enable this tool (optional)
-     * Used by the tool policy engine to determine if a PNP support enables this tool.
-     * Example: ['calculator', 'basic-calculator', 'scientific-calculator']
-     */
-    pnpSupportIds?: string[];
     /**
      * Authored content this capability needs before it has anything to show.
      *
@@ -484,6 +484,16 @@ export interface ToolRegistration {
      * without hardcoded tool-specific branches.
      */
     provider?: ToolProviderDescriptor;
+    /**
+     * Normalize this tool's `tools.providers.<toolId>` entry. Tools-config
+     * validation runs it before {@link ToolRegistration.validateConfig}; a throw is
+     * reported as a diagnostic and the entry passes through unchanged.
+     */
+    sanitizeConfig?: (config: ToolRuntimeConfig) => ToolRuntimeConfig;
+    /**
+     * Diagnostics for this tool's sanitized `tools.providers.<toolId>` entry.
+     */
+    validateConfig?: (config: ToolRuntimeConfig) => ToolConfigDiagnostic[];
     /**
      * Optional shell-host lifecycle hooks for hosted (floating) tools.
      */
@@ -547,10 +557,12 @@ export interface ToolRegistration {
  */
 export declare class ToolRegistry {
     private tools;
-    private pnpIndex;
     private componentOverrides;
+    private watchedUndefinedToolElements;
     private moduleLoaders;
     private loadedToolModules;
+    private warnedLoaderReplacements;
+    private warnedUnregisteredAllowedTools;
     private moduleLoadPromises;
     private changeListeners;
     private emitChange;
@@ -560,11 +572,11 @@ export declare class ToolRegistry {
      */
     onRegistryChange(listener: ToolRegistryChangeListener): () => void;
     /**
-     * Normalize a single tool alias to canonical toolId.
+     * Normalize a single tool id (trims surrounding whitespace).
      */
     normalizeToolId(toolId: string): string;
     /**
-     * Normalize a list of tool aliases to canonical toolIds.
+     * Normalize a list of tool ids (trims surrounding whitespace).
      */
     normalizeToolIds(toolIds: string[]): string[];
     /**
@@ -612,13 +624,6 @@ export declare class ToolRegistry {
      * @returns Array of tool registrations
      */
     getAllTools(): ToolRegistration[];
-    /**
-     * 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: string): Set<string>;
     /**
      * Get tools that support a specific level
      *
@@ -644,11 +649,12 @@ export declare class ToolRegistry {
      */
     getToolsBySurface(surface: string): ToolRegistration[];
     /**
-     * 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(): string[];
     /**
@@ -658,7 +664,7 @@ export declare 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)
@@ -684,13 +690,12 @@ export declare 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(): Array<{
         toolId: string;
         name: string;
         description: string;
-        pnpSupportIds: string[];
         supportedLevels: ToolLevel[];
         activation: ToolActivation;
         singletonScope: ToolSingletonScope | null;
@@ -698,14 +703,6 @@ export declare class ToolRegistry {
         requiresAuthoredContent: boolean;
         contentDependencyDescription: string | 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: string[]): string[];
     /**
      * Clear all registrations (useful for testing)
      */
@@ -717,17 +714,39 @@ export declare 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: Partial<Record<string, ToolModuleLoader>>): void;
+    private warnLoaderReplacedAfterLoad;
     /**
      * Ensure tool module side-effects are loaded exactly once.
      * Safe to call repeatedly; concurrent callers share the same promise.
      */
     ensureToolModuleLoaded(toolId: string): Promise<void>;
     /**
-     * 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.
+     */
+    private undefinedToolElementTag;
+    /**
+     * 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.
+     */
+    private warnIfLoadedToolElementUndefined;
+    /**
+     * 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.
+     */
+    private watchUndefinedToolElement;
+    /**
+     * 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.
      */
-    ensureToolModulesLoaded(toolIds: string[]): Promise<void>;
+    ensureToolModulesLoaded(toolIds: string[]): Promise<Map<string, unknown>>;
     /**
      * Whether a tool module has already been loaded.
      */
@@ -745,7 +764,5 @@ export declare class ToolRegistry {
      * nothing and fail on every packaged capability. Overrides passed in the
      * context still win, matching the toolbar path's precedence.
      */
-    renderForSurface(toolId: string, context: Omit<ToolSurfaceRenderContext, "componentOverrides"> & {
-        componentOverrides?: ToolComponentOverrides;
-    }): ToolSurfaceRenderResult | null;
+    renderForSurface(toolId: string, context: ToolSurfaceRenderContext): ToolSurfaceRenderResult | null;
 }

package/dist/services/ToolRegistry.js

@@ -5,23 +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";
-/**
- * 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";
 /**
  * A registration's display name in the interface locale.
  *
@@ -163,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.`);
@@ -186,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") {
@@ -209,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) {
@@ -240,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));
@@ -263,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] });
     }
     /**
@@ -284,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] });
     }
     /**
@@ -310,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] });
     }
@@ -356,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
      *
@@ -401,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.
@@ -426,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)
@@ -438,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
@@ -492,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,
@@ -508,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)
      */
@@ -535,7 +450,6 @@ export class ToolRegistry {
         if (toolIds.length === 0)
             return;
         this.tools.clear();
-        this.pnpIndex.clear();
         this.emitChange({ kind: "clear", toolIds });
     }
     /**
@@ -550,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);
@@ -563,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);
         }
@@ -570,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.
@@ -583,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 {
@@ -598,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.