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

package/dist/services/ToolRegistry.d.ts

@@ -1,18 +1,31 @@
 /**
- * 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 type { I18nProvider } from "@pie-players/pie-players-shared/i18n/types";
+import type { ToolParametersFor } from "@pie-players/pie-players-shared/types";
 import type { CatalogOwnerSnapshot } from "./AccessibilityCatalogResolver.js";
+import type { ToolPolicyEntry } from "../policy/core/decision-types.js";
 import type { ToolContext, ToolLevel } from "./tool-context.js";
-import type { ToolComponentOverrides } from "../tools/tool-tag-map.js";
+import type { ToolScopeLevel } from "./tool-instance-id.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";
+import type { ToolProviderConfig } from "./tools-config-normalizer.js";
 import type { ToolConfigDiagnostic } from "./tool-config-validation.js";
+import type { ToolFailurePhase } from "./tool-failure.js";
 export type ToolModuleLoader = () => Promise<unknown>;
+/** Receives a registration callback's throw, from which the registry recovers. */
+export type ToolCallbackFailureHandler = (toolId: string, phase: Extract<ToolFailurePhase, "tool-visibility" | "tool-applicability">, error: unknown) => void;
 export type ToolRegistryChangeKind = "register" | "override" | "unregister" | "clear" | "component-overrides" | "module-loaders";
 /** A successful mutation to discoverable or rendering registry state. */
 export interface ToolRegistryChangeEvent {
@@ -24,18 +37,16 @@ export interface ToolToolbarButtonDefinition {
     toolId: string;
     label: string;
     /**
-     * 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 —
+     * Optional to match the renderer: `ItemToolBar.svelte` guards on
+     * `button.icon`, and `ToolbarItem.icon` is optional too. A registration that
+     * renders a button still has to declare an icon —
      * `assertToolRegistrationShape` enforces that.
      */
     icon?: string;
     /**
      * FontAwesome icon name, opting this button into `<nds-icon-button>` rendering
      * where the host enables NDS icons (`ndsIcons`). Absent means the toolbar keeps
-     * its own button rendering, which is what every capability got before the NDS
-     * button existed.
+     * its own button rendering.
      *
      * A declaration rather than a toolId lookup in the toolbar: which capabilities
      * a deployment renders through the host's design system is a composition-layer
@@ -51,7 +62,7 @@ export interface ToolToolbarButtonDefinition {
 }
 export interface ToolbarContext {
     scope: {
-        level: ToolLevel;
+        level: ToolScopeLevel;
         scopeId: string;
         assessmentId?: string;
         sectionId?: string;
@@ -65,9 +76,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,17 +95,30 @@ 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;
     getResolvedToolContext?: (toolId: string) => ResolvedToolContext | null;
     getToolRenderParams?: (toolId: string) => Record<string, unknown> | null;
+    /**
+     * The tool's policy parameters on this toolbar: the item's `toolParameters`
+     * entry on an item's own toolbar, else the assessment's `toolParameters` entry.
+     * Authored content, so a registration checks what it reads.
+     */
+    getToolParameters?: <K extends string>(toolId: K) => ToolParametersFor<K> | null;
 }
 export interface ToolContextResolverContext {
     toolId: string;
@@ -207,24 +232,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;
+    createProvider: (config: ToolProviderConfig | undefined) => ToolProviderApi;
+    getInitConfig?: (config: ToolProviderConfig | undefined) => Record<string, unknown>;
+    getAuthFetcher?: (config: ToolProviderConfig | 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,12 +299,18 @@ 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. */
-    parameters?: unknown;
+    parameters?: Record<string, unknown>;
     /** Resolved content dependency, when the capability declares one. */
     content?: unknown;
     services: ToolSurfaceServices;
@@ -296,10 +321,8 @@ 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;
+    parameters?: Record<string, unknown>;
     /**
      * Owner-scoped catalog cards, or `null` when no resolver is available.
      *
@@ -309,7 +332,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
@@ -327,8 +350,8 @@ export interface ToolContentDependencyContext {
  * It is intrinsic to the capability, unlike eligibility tier, which is a property
  * of the program.
  *
- * Two independent things follow from declaring it, and both used to be done by
- * naming ids in core:
+ * Two independent things follow from declaring it, neither of which needs core
+ * to name a capability id:
  *
  *   1. **Availability is grant AND content.** The host renders only when policy
  *      granted the feature *and* `resolve` returned something. Neither half
@@ -392,7 +415,8 @@ export interface ToolSurfaceRenderResult {
     destroy?: () => void;
 }
 /**
- * Tool registration interface
+ * The contract a tool declares itself with; `ToolRegistry.register` validates
+ * its shape.
  */
 export interface ToolRegistration {
     /** Unique tool identifier (e.g., 'calculator', 'textToSpeech') */
@@ -448,12 +472,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 +502,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: ToolProviderConfig) => ToolProviderConfig;
+    /**
+     * Diagnostics for this tool's sanitized `tools.providers.<toolId>` entry.
+     */
+    validateConfig?: (config: ToolProviderConfig) => ToolConfigDiagnostic[];
     /**
      * Optional shell-host lifecycle hooks for hosted (floating) tools.
      */
@@ -491,17 +519,14 @@ export interface ToolRegistration {
     onHostedResize?: (size: HostedToolSize, element: HTMLElement, context: HostedToolContext) => void | Promise<void>;
     onHostedUnmount?: (element: HTMLElement, context: HostedToolContext) => void | Promise<void>;
     /**
-     * Pass 2: Tool decides if it's relevant in this context
-     * Called ONLY if orchestrator has already allowed the tool (Pass 1)
+     * Whether the tool is relevant in this context (pass 2). Asked only for a
+     * tool policy already allows (pass 1).
      *
      * Required for the toolbar activations, and meaningless for `activation:
      * "region"`: a region capability has no toolbar presence to be relevant to, and
      * the question it *would* answer — is there anything to show here — is
      * `requiresAuthoredContent`. A registration that omits this is never returned
-     * by `getVisibleTools`.
-     *
-     * @param context - Rich context about where tool is being evaluated
-     * @returns true if tool should be visible, false to hide
+     * by `filterVisibleInContext`.
      */
     isVisibleInContext?(context: ToolContext): boolean;
     /**
@@ -519,9 +544,6 @@ export interface ToolRegistration {
      * Declare this only where the tool's own controls provably do nothing:
      * withdrawing a granted accommodation on a false negative is the more
      * expensive failure. Omitting it means "applicable".
-     *
-     * @param context - The item or element context the tool would act on
-     * @returns false to withdraw the tool from this context
      */
     isApplicableToContent?(context: ToolContext): boolean;
     /**
@@ -547,10 +569,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,71 +584,33 @@ 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[];
     /**
-     * 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: ToolRegistration): void;
     /**
-     * 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: ToolRegistration): void;
     /**
-     * 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: string): void;
-    /**
-     * Get a tool registration by ID
-     *
-     * @param toolId - Tool ID
-     * @returns Tool registration or undefined
-     */
     get(toolId: string): ToolRegistration | undefined;
-    /**
-     * Check if a tool is registered
-     *
-     * @param toolId - Tool ID
-     * @returns true if registered
-     */
     has(toolId: string): boolean;
-    /**
-     * Get all registered tool IDs
-     *
-     * @returns Array of tool IDs
-     */
+    /** Registered tool ids, in registration order. */
     getAllToolIds(): string[];
-    /**
-     * Get all tool registrations
-     *
-     * @returns Array of tool registrations
-     */
+    /** Registrations, in registration order. */
     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
-     *
-     * @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: ToolLevel): ToolRegistration[];
     /**
      * Resolve tool activation, defaulting to toolbar-toggle.
@@ -644,11 +630,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[];
     /**
@@ -656,16 +643,14 @@ export declare class ToolRegistry {
      */
     filterToolIdsByActivation(toolIds: string[], activation: ToolActivation): string[];
     /**
-     * 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: string[], context: ToolContext): ToolRegistration[];
+    filterVisibleInContext(allowedToolIds: string[], context: ToolContext, onFailure?: ToolCallbackFailureHandler): ToolRegistration[];
     /**
      * Whether a tool can act on any of the contexts it would be placed against.
      * Unlike the relevance pass this is a veto: a `false` here removes the tool
@@ -678,19 +663,39 @@ export declare 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: string, contexts: readonly ToolContext[]): boolean;
+    isApplicableToAnyContext(toolId: string, contexts: readonly ToolContext[], onFailure?: ToolCallbackFailureHandler): boolean;
     /**
-     * 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.
+     *
+     * - 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.
      *
-     * @returns Array of tool metadata (id, name, description, pnpSupportIds)
+     * @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: readonly Pick<ToolPolicyEntry, "toolId" | "required" | "alwaysAvailable">[], level: ToolLevel, contexts: readonly ToolContext[], onFailure?: ToolCallbackFailureHandler): string[];
+    /**
+     * Plain metadata for every registration, in registration order, for UIs
+     * such as a PNP configuration screen.
      */
     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,7 @@ 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;
+    /** The registry's component overrides, with the caller's taking precedence. */
+    private mergeComponentOverrides;
 }