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

package/dist/services/ToolCoordinator.d.ts

@@ -8,8 +8,6 @@
  * coordinator's alone: an element bound to a tool (`registerTool` with an
  * element, or `updateToolElement`) takes a z-index in the tool's layer and comes
  * to the front of that layer when shown or pressed.
- *
- * Part of PIE Assessment Toolkit.
  */
 import type { ToolCoordinatorApi, ToolState, ToolStateFilter } from "./interfaces.js";
 /**
@@ -34,70 +32,36 @@ export declare class ToolCoordinator implements ToolCoordinatorApi {
     /**
      * Register a tool with the coordinator. Registering a known id keeps its
      * on/off state and takes the name, the element when one is given, and the
-     * layer when none was declared before.
-     *
-     * @param id Unique tool identifier
-     * @param name Display name
-     * @param element DOM element to stack (optional)
-     * @param layer Z-index layer. Without one the tool stacks on TOOL until a
-     * registration names one.
+     * layer when none was declared before. Without a `layer` the tool stacks on
+     * TOOL until a registration names one.
      */
     registerTool(id: string, name: string, element?: HTMLElement, layer?: ZIndexLayer): void;
     /**
      * Unregister a tool's element binding, keeping its on/off state so a
      * re-registration of the same id (an item re-render) restores it. Use
      * {@link releaseTool} on genuine teardown.
-     *
-     * @param id Tool identifier
      */
     unregisterTool(id: string): void;
     /**
      * Fully release a tool: unregister its element binding and discard its
      * on/off state. Call this on genuine teardown (leaving the item or section
      * that owns the tool).
-     *
-     * @param id Tool identifier
      */
     releaseTool(id: string): void;
-    /**
-     * Show a tool
-     *
-     * @param id Tool identifier
-     */
     showTool(id: string): void;
-    /**
-     * Hide a tool
-     *
-     * @param id Tool identifier
-     */
     hideTool(id: string): void;
-    /**
-     * Toggle tool visibility
-     *
-     * @param id Tool identifier
-     */
     toggleTool(id: string): void;
-    /**
-     * Check if tool is visible
-     *
-     * @param id Tool identifier
-     */
     isToolVisible(id: string): boolean;
     /**
      * Bring a bound element to the front of its tool's layer. An element no tool
      * is bound to is left alone.
-     *
-     * @param element DOM element to bring forward
      */
     bringToFront(element: HTMLElement): void;
     /**
-     * Ids of the tools an element registration currently holds.
+     * Release every tool, registered or not, and drop the subscribers. The
+     * owning toolkit coordinator calls this when it is disposed.
      */
-    getRegisteredTools(): string[];
-    /**
-     * Get tool element by ID
-     */
-    getToolElement(id: string): HTMLElement | null;
+    destroy(): void;
     private setVisible;
     private detachElement;
     /**
@@ -112,9 +76,6 @@ export declare class ToolCoordinator implements ToolCoordinatorApi {
      * The outermost element stacks: binding an element inside the bound one keeps
      * the binding, so a tool rendered inside a toolbar's floating window stacks
      * by that window whichever binds first.
-     *
-     * @param id Tool identifier
-     * @param element New DOM element
      */
     updateToolElement(id: string, element: HTMLElement): void;
     /**
@@ -122,11 +83,7 @@ export declare class ToolCoordinator implements ToolCoordinatorApi {
      * `{ baseId }`, notifying subscribers once.
      */
     hideAllTools(filter?: ToolStateFilter): void;
-    /**
-     * State of a tool an element registration holds.
-     *
-     * @param id Tool identifier
-     */
+    /** State of a tool an element registration holds. */
     getToolState(id: string): ToolState | undefined;
     /**
      * Every visible tool, or every visible instance of one tool with

package/dist/services/ToolCoordinator.js

@@ -8,12 +8,10 @@
  * coordinator's alone: an element bound to a tool (`registerTool` with an
  * element, or `updateToolElement`) takes a z-index in the tool's layer and comes
  * to the front of that layer when shown or pressed.
- *
- * Part of PIE Assessment Toolkit.
  */
-import { createLogger } from "../utils/logger.js";
+import { createPieLogger, isGlobalDebugEnabled, } from "@pie-players/pie-players-shared/pie";
 import { parseScopedToolId } from "./tool-instance-id.js";
-const log = createLogger("ToolCoordinator");
+const logger = createPieLogger("ToolCoordinator", isGlobalDebugEnabled);
 /**
  * Z-index layers for assessment components
  */
@@ -65,16 +63,16 @@ export class ToolCoordinator {
     /**
      * Register a tool with the coordinator. Registering a known id keeps its
      * on/off state and takes the name, the element when one is given, and the
-     * layer when none was declared before.
-     *
-     * @param id Unique tool identifier
-     * @param name Display name
-     * @param element DOM element to stack (optional)
-     * @param layer Z-index layer. Without one the tool stacks on TOOL until a
-     * registration names one.
+     * layer when none was declared before. Without a `layer` the tool stacks on
+     * TOOL until a registration names one.
      */
     registerTool(id, name, element, layer) {
-        log("registerTool called:", { id, name, hasElement: !!element, layer });
+        logger.debug("registerTool called:", {
+            id,
+            name,
+            hasElement: !!element,
+            layer,
+        });
         let entry = this.tools.get(id);
         if (entry) {
             entry.name = name;
@@ -110,8 +108,6 @@ export class ToolCoordinator {
      * Unregister a tool's element binding, keeping its on/off state so a
      * re-registration of the same id (an item re-render) restores it. Use
      * {@link releaseTool} on genuine teardown.
-     *
-     * @param id Tool identifier
      */
     unregisterTool(id) {
         const entry = this.tools.get(id);
@@ -124,8 +120,6 @@ export class ToolCoordinator {
      * Fully release a tool: unregister its element binding and discard its
      * on/off state. Call this on genuine teardown (leaving the item or section
      * that owns the tool).
-     *
-     * @param id Tool identifier
      */
     releaseTool(id) {
         const entry = this.tools.get(id);
@@ -136,43 +130,28 @@ export class ToolCoordinator {
         if (entry.isVisible)
             this.notifyListeners();
     }
-    /**
-     * Show a tool
-     *
-     * @param id Tool identifier
-     */
     showTool(id) {
         const entry = this.tools.get(id);
         if (!entry) {
-            log(`Tool ${id} not found`);
+            logger.debug(`Tool ${id} not found`);
             return;
         }
         if (entry.element)
             this.bringToFront(entry.element);
         this.setVisible(entry, true);
     }
-    /**
-     * Hide a tool
-     *
-     * @param id Tool identifier
-     */
     hideTool(id) {
         const entry = this.tools.get(id);
         if (!entry) {
-            log(`Tool ${id} not found`);
+            logger.debug(`Tool ${id} not found`);
             return;
         }
         this.setVisible(entry, false);
     }
-    /**
-     * Toggle tool visibility
-     *
-     * @param id Tool identifier
-     */
     toggleTool(id) {
         const entry = this.tools.get(id);
         if (!entry) {
-            log(`Tool ${id} not found`);
+            logger.debug(`Tool ${id} not found`);
             return;
         }
         if (entry.isVisible) {
@@ -182,19 +161,12 @@ export class ToolCoordinator {
             this.showTool(id);
         }
     }
-    /**
-     * Check if tool is visible
-     *
-     * @param id Tool identifier
-     */
     isToolVisible(id) {
         return this.tools.get(id)?.isVisible ?? false;
     }
     /**
      * Bring a bound element to the front of its tool's layer. An element no tool
      * is bound to is left alone.
-     *
-     * @param element DOM element to bring forward
      */
     bringToFront(element) {
         const entry = Array.from(this.tools.values()).find((t) => t.element === element);
@@ -203,18 +175,17 @@ export class ToolCoordinator {
         this.stackOnTop(entry);
     }
     /**
-     * Ids of the tools an element registration currently holds.
+     * Release every tool, registered or not, and drop the subscribers. The
+     * owning toolkit coordinator calls this when it is disposed.
      */
-    getRegisteredTools() {
-        return Array.from(this.tools.values())
-            .filter((entry) => entry.registered)
-            .map((entry) => entry.id);
-    }
-    /**
-     * Get tool element by ID
-     */
-    getToolElement(id) {
-        return this.tools.get(id)?.element ?? null;
+    destroy() {
+        const anyVisible = Array.from(this.tools.values()).some((entry) => entry.isVisible);
+        for (const entry of this.tools.values())
+            this.detachElement(entry);
+        this.tools.clear();
+        if (anyVisible)
+            this.notifyListeners();
+        this.listeners.clear();
     }
     setVisible(entry, visible) {
         if (entry.isVisible === visible)
@@ -256,14 +227,11 @@ export class ToolCoordinator {
      * The outermost element stacks: binding an element inside the bound one keeps
      * the binding, so a tool rendered inside a toolbar's floating window stacks
      * by that window whichever binds first.
-     *
-     * @param id Tool identifier
-     * @param element New DOM element
      */
     updateToolElement(id, element) {
         const entry = this.tools.get(id);
         if (!entry?.registered) {
-            log(`Tool ${id} not found`);
+            logger.debug(`Tool ${id} not found`);
             return;
         }
         if (entry.element === element)
@@ -294,11 +262,7 @@ export class ToolCoordinator {
         if (changed)
             this.notifyListeners();
     }
-    /**
-     * State of a tool an element registration holds.
-     *
-     * @param id Tool identifier
-     */
+    /** State of a tool an element registration holds. */
     getToolState(id) {
         const entry = this.tools.get(id);
         return entry?.registered ? toToolState(entry) : undefined;

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 { 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;
@@ -102,6 +113,12 @@ export interface ToolbarContext {
     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;
@@ -222,9 +239,9 @@ export interface HostedToolSize {
  * renames the registration.
  */
 export interface ToolProviderDescriptor {
-    createProvider: (config: ToolRuntimeConfig | undefined) => ToolProviderApi;
-    getInitConfig?: (config: ToolRuntimeConfig | undefined) => Record<string, unknown>;
-    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;
 }
 export interface ToolToolbarRenderResult {
@@ -293,7 +310,7 @@ export interface ToolSurfaceRenderContext {
     /** 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;
@@ -305,7 +322,7 @@ export interface ToolSurfaceRenderContext {
  */
 export interface ToolContentDependencyContext {
     /** 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.
      *
@@ -333,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
@@ -398,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') */
@@ -489,11 +507,11 @@ export interface ToolRegistration {
      * validation runs it before {@link ToolRegistration.validateConfig}; a throw is
      * reported as a diagnostic and the entry passes through unchanged.
      */
-    sanitizeConfig?: (config: ToolRuntimeConfig) => ToolRuntimeConfig;
+    sanitizeConfig?: (config: ToolProviderConfig) => ToolProviderConfig;
     /**
      * Diagnostics for this tool's sanitized `tools.providers.<toolId>` entry.
      */
-    validateConfig?: (config: ToolRuntimeConfig) => ToolConfigDiagnostic[];
+    validateConfig?: (config: ToolProviderConfig) => ToolConfigDiagnostic[];
     /**
      * Optional shell-host lifecycle hooks for hosted (floating) tools.
      */
@@ -501,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;
     /**
@@ -529,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;
     /**
@@ -580,56 +592,25 @@ export declare class ToolRegistry {
      */
     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[];
-    /**
-     * 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.
@@ -662,16 +643,14 @@ export declare class ToolRegistry {
      */
     filterToolIdsByActivation(toolIds: string[], activation: ToolActivation): string[];
     /**
-     * Filter tools by visibility in a given context
-     *
-     * 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.
+     * 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`.
      *
-     * @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
@@ -684,13 +663,34 @@ 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.
      *
-     * @returns Array of tool metadata (id, name, description, levels, activation)
+     * - 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: 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;
@@ -765,4 +765,6 @@ export declare class ToolRegistry {
      * context still win, matching the toolbar path's precedence.
      */
     renderForSurface(toolId: string, context: ToolSurfaceRenderContext): ToolSurfaceRenderResult | null;
+    /** The registry's component overrides, with the caller's taking precedence. */
+    private mergeComponentOverrides;
 }