@pie-players/pie-assessment-toolkit 0.3.73 → 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";
@@ -24,8 +24,8 @@ export interface ToolToolbarButtonDefinition {
     toolId: string;
     label: string;
     /**
-     * Optional to match what the renderers already do: `ToolButton.svelte` and
-     * `ItemToolBar.svelte` both guard on `button.icon`, and `ToolbarItem.icon` is
+     * Optional to match what the renderer already does: `ItemToolBar.svelte`
+     * guards on `button.icon`, and `ToolbarItem.icon` is
      * already optional, so requiring it here claimed a guarantee nothing relied
      * on. A registration that renders a button still has to declare an icon —
      * `assertToolRegistrationShape` enforces that.
@@ -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,12 +215,15 @@ 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;
 }
@@ -230,12 +241,10 @@ export interface ToolToolbarRenderResult {
  * 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 declare function resolveToolRegistrationName(registration: Pick<ToolRegistration, "name" | "nameKey">, i18n?: I18nProvider): string;
-/** A registration's description in the interface locale. See the name resolver. */
-export declare function resolveToolRegistrationDescription(registration: Pick<ToolRegistration, "description" | "descriptionKey">, i18n?: I18nProvider): string;
 export type ToolActivation = "toolbar-toggle" | "selection-gateway" | "region";
 export type ToolSingletonScope = "section";
 /**
@@ -273,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. */
@@ -289,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;
     /**
@@ -302,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
@@ -441,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.
      *
@@ -477,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.
      */
@@ -540,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;
@@ -553,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[];
     /**
@@ -605,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
      *
@@ -637,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[];
     /**
@@ -651,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)
@@ -677,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;
@@ -691,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)
      */
@@ -710,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.
      */
@@ -738,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;
 }