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

package/dist/services/ToolkitCoordinator.d.ts

@@ -13,8 +13,8 @@
  *
  * Part of PIE Assessment Toolkit.
  */
-import type { AccessibilityCatalog, AssessmentEntity, AssessmentItemRef } from "@pie-players/pie-players-shared/types";
-import { type CanonicalToolsConfig, type ToolPlacementConfig, type ToolPlacementLevel, type ToolPolicyConfig, type ToolProviderConfig, type ToolProvidersConfig } from "./tools-config-normalizer.js";
+import type { AccessibilityCatalog, AssessmentEntity, ItemSettings } from "@pie-players/pie-players-shared/types";
+import { type CanonicalToolsConfig, type ToolPlacementConfig, type ToolPolicyConfig, type TextToSpeechToolProviderConfig, type ToolProviderConfig, type ToolProvidersConfig, type ToolsConfigInput } from "./tools-config-normalizer.js";
 import { type ToolConfigStrictness } from "./tool-config-validation.js";
 import { AccessibilityCatalogResolver } from "./AccessibilityCatalogResolver.js";
 import type { CatalogChangeListener } from "./AccessibilityCatalogResolver.js";
@@ -24,53 +24,15 @@ import { FrameworkErrorBus, type FrameworkErrorListener } from "./framework-erro
 import { HighlightCoordinator } from "./HighlightCoordinator.js";
 import { ToolCoordinator } from "./ToolCoordinator.js";
 import { TTSService } from "./TTSService.js";
-import { type TTSRuntimeSettings } from "./tts-runtime-config.js";
-import type { SREMathSpeechOptions } from "./tts/math-speech.js";
 import { ToolProviderRegistry } from "./tool-providers/index.js";
 import type { ToolProviderApi } from "./tool-providers/ToolProviderApi.js";
-import type { TTSToolProviderConfig } from "./tool-providers/index.js";
 import { ToolRegistry } from "./ToolRegistry.js";
-import type { ResolvedToolContext, ToolContextResolver, ToolContextResolverContext, ToolContextResolverMap } from "./ToolRegistry.js";
+import type { ResolvedToolContext, ToolContextResolverContext, ToolContextResolverMap } from "./ToolRegistry.js";
 import type { ToolOpenRequest, ToolRequestTarget } from "./tool-request.js";
-import { type FeaturePolicyDecision, type PnpEnforcementMode, type PolicySource, type ResolvedEngineInputs, type ToolPolicyChangeListener, type ToolPolicyDecision, type ToolPolicyDecisionRequest } from "../policy/engine.js";
-import type { SectionControllerContext, SectionControllerEvent, SectionControllerEventType, SectionControllerFactoryDefaults, SectionControllerHandle, SectionControllerKey, SectionSessionPersistenceStrategy, SectionPersistenceFactoryDefaults } from "./section-controller-types.js";
+import { type FeaturePolicyDecision, type PnpEnforcementMode, type PolicySource, type ResolvedEngineInputs, type ToolPolicyChangeListener, type ToolPolicyDecision, type ToolPolicyDecisionRequest, type ToolScope } from "../policy/engine.js";
+import type { SectionControllerContext, SectionControllerEvent, SectionControllerEventType, SectionControllerFactoryDefaults, SectionControllerHandle, SectionControllerKey, SectionControllerSessionState, SectionSessionPersistenceStrategy, SectionPersistenceFactoryDefaults } from "./section-controller-types.js";
 export type { SectionControllerContext, SectionControllerEvent, SectionControllerEventType, SectionControllerFactoryDefaults, SectionControllerHandle, SectionControllerKey, SectionControllerLoadedRenderable, SectionSessionPersistenceConfig, SectionSessionPersistenceStrategy, SectionControllerRuntimeState, SectionControllerSessionState, SectionPersistenceFactoryDefaults, } from "./section-controller-types.js";
 export type { FeaturePolicyDecision, PnpEnforcementMode, ResolvedEngineInputs, ToolPolicyChangeListener, ToolPolicyDecision, ToolPolicyDecisionRequest, } from "../policy/engine.js";
-/**
- * Generic tool configuration
- */
-export interface ToolConfig {
-    enabled?: boolean;
-    provider?: unknown;
-    settings?: Record<string, unknown>;
-    [key: string]: unknown;
-}
-/**
- * TTS configuration as a host writes it.
- *
- * The field set is `TTSRuntimeSettings`, which the runtime resolver owns: the two
- * were declared separately and had already drifted in both directions, so a field
- * the runtime honoured could not be named here. What this adds is the two things
- * only a host-facing config has — a place to stash unrecognised keys, and a
- * callback for fetching provider credentials, neither of which the resolved
- * runtime settings carry.
- *
- * An intersection rather than an interface: `ToolConfig.provider` is `unknown`
- * where the runtime settings narrow it to the three provider ids, and an interface
- * cannot inherit a member from two parents that type it differently.
- */
-export type TTSToolConfig = ToolConfig & TTSRuntimeSettings & {
-    settings?: Record<string, unknown> & {
-        mathSpeech?: SREMathSpeechOptions;
-    };
-    authFetcher?: () => Promise<Partial<TTSToolProviderConfig>>;
-};
-/**
- * Answer eliminator tool configuration
- */
-export interface AnswerEliminatorToolConfig extends ToolConfig {
-    strategy?: "strikethrough" | "hide";
-}
 export interface ToolkitToolsConfig extends CanonicalToolsConfig {
     policy: ToolPolicyConfig;
     placement: Required<ToolPlacementConfig>;
@@ -86,10 +48,10 @@ export interface ToolkitCoordinatorConfig {
      */
     assessmentId: string;
     /**
-     * Tool availability and configuration.
-     * Defaults: all tools enabled with default settings.
+     * Tool availability and configuration. The default placement is empty: a tool
+     * shows only where placement puts it, and a grant does not place one.
      */
-    tools?: Partial<CanonicalToolsConfig>;
+    tools?: ToolsConfigInput;
     /**
      * Validation strictness for tool config contracts.
      * - off: keep diagnostics internal (no warnings or throws)
@@ -100,8 +62,12 @@ export interface ToolkitCoordinatorConfig {
      */
     toolConfigStrictness?: ToolConfigStrictness;
     /**
-     * Optional registry used for tool-config validation and provider descriptor resolution.
-     * Defaults to packaged PIE tools when omitted.
+     * Registry used for tool-config validation and the only source of tool
+     * providers: the coordinator registers one per registration that carries a
+     * provider descriptor. Omitted, the coordinator takes the registry of the
+     * toolkit it is bound to — the section player's, under a section player — and
+     * until then validates nothing and registers no provider. A registry passed
+     * here is never replaced.
      */
     toolRegistry?: ToolRegistry | null;
     /**
@@ -125,12 +91,21 @@ export interface ToolkitCoordinatorConfig {
      */
     hooks?: ToolkitCoordinatorHooks;
     /**
-     * Lazy initialization mode.
-     * When true, async service/provider initialization is deferred until ensure methods are called.
+     * Start text-to-speech at its first use rather than as part of readiness.
+     * `waitUntilReady()` then settles without it, unless policy grants the tool,
+     * so a granted read-aloud still fails before the learner starts.
      *
      * @default false
      */
     lazyInit?: boolean;
+    /**
+     * Start initializing at construction. `<pie-assessment-toolkit>` passes false
+     * for the coordinator it builds, and starts initialization once its section
+     * composes.
+     *
+     * @default !lazyInit
+     */
+    eagerInit?: boolean;
     /**
      * Internal bootstrap escape hatch used by framework-owned hosts.
      * When true, constructor skips throwing validation and expects caller
@@ -139,6 +114,15 @@ export interface ToolkitCoordinatorConfig {
      * @internal
      */
     deferToolConfigValidation?: boolean;
+    /**
+     * Set by `<pie-assessment-toolkit>` on the coordinator it builds for itself.
+     * That toolkit binds only the `assessment` its host passes, and a section
+     * player passes none, so feature policy reports an unbound assessment only
+     * while PNP enforcement is explicitly `"on"`.
+     *
+     * @internal
+     */
+    assessmentOptional?: boolean;
     /**
      * Optional pre-constructed framework-error bus.
      *
@@ -153,20 +137,15 @@ export interface ToolkitCoordinatorConfig {
     frameworkErrorBus?: FrameworkErrorBus;
 }
 export interface ToolkitErrorContext {
-    phase: "coordinator-ready" | "state-load" | "state-save" | "provider-register" | "provider-init" | "tts-init" | "section-controller-init" | "section-controller-dispose";
-    providerId?: string;
+    phase: "coordinator-ready" | "state-load" | "state-save" | "provider-register" | "provider-init" | "tts-init" | "section-controller-init" | "section-controller-dispose" | "tool-module-load";
+    /** The tool whose provider failed. */
+    toolId?: string;
     details?: Record<string, unknown>;
+    recoverable?: boolean;
 }
 export interface ProviderLifecycleContext {
-    providerId: string;
     providerName?: string;
 }
-export interface ToolkitInitStatus {
-    tts: boolean;
-    stateLoaded: boolean;
-    coordinator: boolean;
-    providers: Record<string, boolean>;
-}
 export interface SectionControllerLifecycleEvent {
     type: "ready" | "disposed";
     key: SectionControllerKey;
@@ -236,9 +215,9 @@ export interface ToolkitCoordinatorHooks {
     onBeforeTTSInit?: (context: ToolkitErrorContext) => void | Promise<void>;
     onTTSReady?: () => void | Promise<void>;
     onCoordinatorReady?: (coordinator: ToolkitCoordinator) => void | Promise<void>;
-    onProviderRegistered?: (providerId: string, meta: ProviderLifecycleContext) => void | Promise<void>;
-    onProviderInitStart?: (providerId: string, meta: ProviderLifecycleContext) => void | Promise<void>;
-    onProviderReady?: (providerId: string, meta: ProviderLifecycleContext) => void | Promise<void>;
+    onProviderRegistered?: (toolId: string, meta: ProviderLifecycleContext) => void | Promise<void>;
+    onProviderInitStart?: (toolId: string, meta: ProviderLifecycleContext) => void | Promise<void>;
+    onProviderReady?: (toolId: string, meta: ProviderLifecycleContext) => void | Promise<void>;
     onTelemetry?: (eventName: string, payload?: Record<string, unknown>) => void | Promise<void>;
     loadToolState?: () => Record<string, Record<string, unknown>> | Promise<Record<string, Record<string, unknown>> | null | undefined> | null | undefined;
     saveToolState?: (state: Record<string, Record<string, unknown>>) => void | Promise<void>;
@@ -256,29 +235,24 @@ export type ToolkitTelemetryListener = (args: {
     eventName: string;
     payload?: Record<string, unknown>;
 }) => void;
-/**
- * Service bundle returned by getServiceBundle()
- */
-export interface ToolkitServiceBundle {
-    ttsService: TTSService;
-    toolCoordinator: ToolCoordinator;
-    highlightCoordinator: HighlightCoordinator;
-    elementToolStateStore: ElementToolStateStore;
-    catalogResolver: AccessibilityCatalogResolver;
-    toolProviderRegistry: ToolProviderRegistry;
-}
 /**
  * ToolkitCoordinator - Orchestrates all assessment toolkit services
  *
  * @example
  * ```typescript
+ * // Both are exported by @pie-players/pie-default-tool-loaders
+ * const toolRegistry = createPackagedToolRegistry({
+ *   toolModuleLoaders: DEFAULT_TOOL_MODULE_LOADERS,
+ * });
+ *
  * // Create coordinator with configuration
  * const coordinator = new ToolkitCoordinator({
  *   assessmentId: 'demo-three-questions',
+ *   toolRegistry,
  *   tools: {
  *     providers: {
  *       textToSpeech: { enabled: true, backend: 'browser' },
- *       answerEliminator: { enabled: true, strategy: 'strikethrough' }
+ *       answerEliminator: { enabled: true }
  *     },
  *     placement: {
  *       item: ['textToSpeech', 'answerEliminator']
@@ -287,7 +261,7 @@ export interface ToolkitServiceBundle {
  * });
  *
  * // Pass to section player
- * player.toolkitCoordinator = coordinator;
+ * player.runtime = { ...(player.runtime ?? {}), coordinator };
  *
  * // Access services directly
  * const ttsService = coordinator.ttsService;
@@ -310,14 +284,43 @@ export declare class ToolkitCoordinator {
     readonly lazyInit: boolean;
     /** Track TTS initialization state */
     private ttsInitialized;
+    /** Text-to-speech failed to start and policy does not grant it. */
+    private ttsDegraded;
     private ttsInitPromise?;
     private ttsReconfigurePromise?;
     private stateLoaded;
+    /**
+     * The loader ran, whether or not it returned state. A failed load is
+     * reported once and the coordinator runs without saved tool state.
+     */
+    private stateLoadSettled;
     private stateLoadPromise?;
     private coordinatorReadyPromise?;
     private coordinatorReadyNotified;
     private readonly providerInitPromises;
-    private readonly toolRegistry;
+    /**
+     * Recoverable failures, by tool. A policy change that grants one of these
+     * tools reports its failure again as fatal.
+     */
+    private readonly degradedTools;
+    /** Tools a toolbar reported a module failure for, each reported once. */
+    private readonly toolModuleFailures;
+    private readonly readyChangeListeners;
+    private readonly eagerInit;
+    private toolRegistry;
+    /** Whether the host passed `toolRegistry`, which then always stands. */
+    private readonly toolRegistrySupplied;
+    /**
+     * Whether the registry is final: supplied at construction, or adopted from
+     * the toolkit this coordinator is bound to.
+     */
+    private toolRegistrySettled;
+    /**
+     * Whether a bound toolkit reported having no registry. Until then, or until a
+     * registry settles, the empty placeholder reports no missing registry, since
+     * the toolkit may supply one.
+     */
+    private toolRegistryAbsent;
     private readonly toolContextResolvers;
     private readonly toolContextResolverChangeListeners;
     private readonly toolRequests;
@@ -344,14 +347,16 @@ export declare class ToolkitCoordinator {
      * Phase D: map key of the section controller currently treated as
      * the *active cohort*. Set by `getOrCreateSectionController` (both
      * the create-new and resolve-existing paths) and cleared when the
-     * matching controller is disposed. `null` while no cohort exists,
-     * which is the only state where `subscribeSectionEvents` throws.
+     * matching controller is disposed, and `null` while the next requested
+     * cohort is still starting.
      */
     private activeCohortMapKey;
     /**
      * Latest requested active cohort. Async controller initialization can
      * resolve out of order; only the most recent request may migrate active
      * subscriptions. Older completions still populate the controller cache.
+     * `null` until the first request, which is the only state where
+     * `subscribeSectionEvents` throws.
      */
     private latestRequestedActiveCohortMapKey;
     private readonly telemetryListeners;
@@ -367,32 +372,20 @@ export declare class ToolkitCoordinator {
      */
     private readonly policyEngine;
     /**
-     * Host-set override for PNP/profile enforcement. `null` (the default) means
-     * "auto" — the coordinator infers the effective mode from the
-     * PNP/profile policy inputs the bound `AssessmentEntity` and `AssessmentItemRef`
-     * actually carry (see {@link resolveEffectivePnpEnforcement}).
+     * Host-set override for PNP/profile enforcement, passed to the engine.
+     * `null` (the default) is auto-mode, which the engine resolves per decision
+     * from the policy material the bound assessment and the decision's item carry.
      * `"on"` / `"off"` are explicit host opt-in / opt-out and stick
-     * across subsequent assessment / item swaps until the host clears
+     * across subsequent assessment swaps until the host clears
      * the override by calling `setPnpEnforcement(null)`.
      */
     private pnpEnforcementOverride;
     /**
-     * Last assessment passed to {@link updateAssessment}. Read by
-     * {@link resolveEffectivePnpEnforcement} to compute auto-mode.
-     * The engine's own copy is the canonical record for decisions;
-     * this mirror exists only so the auto-mode helper does not need
-     * to round-trip through {@link policyEngine}'s frozen snapshot.
-     */
-    private boundAssessment;
-    /**
-     * Last item reference passed to {@link updateCurrentItemRef}.
-     * Mirrored alongside {@link boundAssessment} so
-     * {@link resolveEffectivePnpEnforcement} can detect item-level
-     * profile policy inputs (`requiredTools` / `restrictedTools` /
-     * `toolParameters`) without round-tripping through the engine's
-     * frozen snapshot.
+     * Policy diagnostics already logged, keyed by code, tool id and, for
+     * `tool-policy.itemSettingNotApplied`, item id; see
+     * {@link warnPolicyDiagnostics}.
      */
-    private boundCurrentItemRef;
+    private readonly warnedPolicyDiagnostics;
     /**
      * Whether {@link decideFeaturePolicy} has already reported serving a decision
      * with no assessment bound.
@@ -404,7 +397,31 @@ export declare class ToolkitCoordinator {
      * lifetime for no new information.
      */
     private reportedUnboundFeaturePolicy;
-    private static resolveConfig;
+    /**
+     * Whether {@link _initializeTTS} has already reported a non-browser backend
+     * falling back to browser speech because no text-to-speech provider is registered.
+     * Once per coordinator: a text-to-speech config change re-runs
+     * initialization, and the missing provider is the same gap each time.
+     */
+    private reportedMissingTTSProvider;
+    /**
+     * The backend of a fallback {@link reportMissingTTSProvider} held back while
+     * the registry was unsettled, reported if the bound toolkit has no registry.
+     */
+    private heldMissingTTSProviderBackend;
+    /**
+     * Whether {@link validateToolsConfig} has already reported validating with
+     * no registry (`tools.registryUnavailable`). Once per coordinator: every
+     * {@link updateToolConfig} and {@link updateToolsPlacement} re-validates, and
+     * the missing registry is the same gap each time.
+     */
+    private reportedRegistryUnavailable;
+    private resolveConfig;
+    /**
+     * `normalizeAndValidateToolsConfig`, except that `tools.registryUnavailable`
+     * is reported once per coordinator, whichever call validates.
+     */
+    private validateToolsConfig;
     constructor(config: ToolkitCoordinatorConfig);
     private assertNotDisposed;
     /**
@@ -441,7 +458,39 @@ export declare class ToolkitCoordinator {
      */
     private emitTelemetry;
     private emitSectionControllerLifecycle;
+    /**
+     * Every report site states whether the coordinator carries on after the
+     * failure; one that takes down only its section passes `scope: "cohort"`.
+     */
     private handleError;
+    /**
+     * Whether policy grants `toolId` as an accommodation on some surface: a
+     * test-administration override, a mounted item's or a district requirement,
+     * or profile support. Read without the unbound-assessment warning.
+     */
+    private isToolGranted;
+    /**
+     * Reports a tool's start failure: recoverable, so the tool reports itself
+     * unavailable and the assessment goes on, unless policy grants the tool.
+     * `fallbackFollows` marks a failure another path absorbs, which is recoverable
+     * whatever the policy.
+     */
+    private reportToolFailure;
+    /**
+     * Report that a toolbar could not load a tool's module. The failure follows
+     * the start-failure policy: the tool degrades, so the toolbar withholds it,
+     * unless policy grants it. Reported once per tool however many toolbars fail
+     * to load it. Every report re-announces the request targets, since the
+     * reporting toolbar no longer hosts the tool.
+     */
+    reportToolModuleFailure(toolId: string, error: unknown): void;
+    private reportNewlyGrantedFailures;
+    /**
+     * Subscribe to changes of {@link isReady}: state loading, text-to-speech
+     * starting, failing or reconfiguring. The listener reads the status itself.
+     */
+    onReadyChange(listener: () => void): () => void;
+    private notifyReadyChange;
     /**
      * Subscribe to framework-error events emitted by this coordinator.
      *
@@ -472,16 +521,44 @@ export declare class ToolkitCoordinator {
     private resolveSectionPersistence;
     private setupStatePersistenceHooks;
     private ensureStateLoaded;
+    /** Whether the toolkit this coordinator binds to may still supply a registry. */
+    private toolRegistryPending;
+    private reportMissingTTSProvider;
+    /**
+     * Take the registry of the toolkit this coordinator is bound to, when the host
+     * constructed it without one: the config is validated against it, its
+     * providers register, and text-to-speech re-initializes through it if it
+     * already started. The toolkit elements call this on binding, and again when
+     * their registry changes. A registry passed at construction stands, and the
+     * first registry adopted wins; `null` records a toolkit without one, which
+     * reports the registry as missing and still adopts one that arrives later.
+     *
+     * @returns Whether `registry` was adopted.
+     */
+    adoptToolRegistry(registry: ToolRegistry | null): boolean;
     /**
      * Register tool providers in the registry
      */
     private _registerToolProviders;
     private getProviderDescriptorTools;
+    /**
+     * Register the provider `tool`'s descriptor creates for the tool's current
+     * config under the tool's id, unless the tool is disabled or, without
+     * `replace`, a provider is registered under that id. A descriptor that throws
+     * is reported the way a failed registration is.
+     */
     private registerProviderFromTool;
     private createToolTelemetryForwarder;
     private addToolTelemetryReporter;
     private registerProvider;
-    ensureProviderReady(providerId: string): Promise<ToolProviderApi>;
+    /**
+     * A console warning and a `provider-register` framework error, under the
+     * start-failure policy every other tool failure follows.
+     */
+    private reportProviderRegisterFailure;
+    ensureProviderReady(toolId: string): Promise<ToolProviderApi>;
+    /** `fallbackFollows`: the caller recovers from a failure on its own. */
+    private initializeProvider;
     setHooks(hooks: ToolkitCoordinatorHooks): void;
     subscribeTelemetry(listener: ToolkitTelemetryListener): () => void;
     getSectionController(args: {
@@ -565,17 +642,31 @@ export declare class ToolkitCoordinator {
         attemptId?: string;
         input?: unknown;
         updateExisting?: boolean;
+        initialSession?: SectionControllerSessionState | null;
         createDefaultController: () => SectionControllerHandle | Promise<SectionControllerHandle>;
     }): Promise<SectionControllerHandle>;
     private resolveExistingSectionController;
     private createSectionControllerContext;
     private initializeNewSectionController;
+    /**
+     * Apply a host-supplied session to a controller that is already published,
+     * under the rules `resolveSectionSessionAssignment` sets: an equal session is a
+     * no-op and recorded responses are not replaced by response-free ones.
+     */
+    private assignSessionToPublishedController;
     private createSectionControllerRetirementError;
     private retireUnpublishedSectionControllerIfNeeded;
     private cleanupUnpublishedSectionController;
     private retirePublishedSectionControllerIfNeeded;
     private finalizeSectionControllerReady;
     private handleSectionControllerInitError;
+    /**
+     * A section that fails to start has no controller of its own to emit its
+     * `section-error`, and the host's subscriptions are already off the outgoing
+     * section, so the coordinator delivers the error to them while that section
+     * is still the one requested.
+     */
+    private deliverSectionStartError;
     disposeSectionController(args: {
         sectionId: string;
         attemptId?: string;
@@ -597,46 +688,41 @@ export declare class ToolkitCoordinator {
     /**
      * Initialize TTS service with provider
      */
-    ensureTTSReady(config?: TTSToolConfig): Promise<void>;
+    ensureTTSReady(config?: TextToSpeechToolProviderConfig): Promise<void>;
     private waitForPendingTTSReconfigure;
     private _initializeTTS;
     private resolveTTSToolConfig;
     private initializeTTSService;
-    private ensureBrowserVoicesReady;
+    waitUntilReady(): Promise<void>;
+    isReady(): boolean;
     /**
-     * Get all services as a bundle for section player convenience.
-     * Section player can extract and pass services to child components.
+     * Readiness waits for text-to-speech when it is enabled and either starts
+     * eagerly or is granted: a granted read-aloud fails before the learner starts.
      */
-    getServiceBundle(): ToolkitServiceBundle;
+    private ttsRequiredForReadiness;
     /**
-     * Get a tool provider from the registry
-     *
-     * @param providerId Provider identifier
-     * @returns Tool provider instance
+     * Starts text-to-speech for readiness. A failure policy does not grant leaves
+     * the tool degraded, reporting itself unavailable, and readiness settles; a
+     * granted tool's failure rejects.
      */
-    getToolProvider(providerId: string): Promise<ToolProviderApi<any, any>>;
-    waitUntilReady(): Promise<void>;
-    isReady(): boolean;
-    getInitStatus(): ToolkitInitStatus;
+    private startTTSForReadiness;
     private getTTSConfigFromProviders;
     private assertCanonicalToolId;
     private installToolContextResolvers;
-    setToolContextResolvers(resolvers: ToolContextResolverMap | null | undefined): void;
-    private notifyToolContextResolverChange;
     /**
-     * Check if a tool is enabled.
-     * Tools are enabled by default unless explicitly disabled.
-     *
-     * @param toolId Tool identifier (e.g., 'textToSpeech', 'answerEliminator')
-     * @returns True if tool is enabled
+     * Replace all host-owned render-context resolvers. The toolkit element
+     * calls this from `runtime.toolContextResolvers`; it is not on
+     * `ToolkitCoordinatorApi`.
      */
-    isToolEnabled(toolId: string): boolean;
+    setToolContextResolvers(resolvers: ToolContextResolverMap | null | undefined): void;
+    private notifyToolContextResolverChange;
     /**
      * Get tool configuration.
      *
      * @param toolId Tool identifier
      * @returns Tool configuration or null if not configured
      */
+    getToolConfig(toolId: "textToSpeech"): TextToSpeechToolProviderConfig | null;
     getToolConfig(toolId: string): ToolProviderConfig | null;
     /**
      * Update tool configuration.
@@ -645,27 +731,38 @@ export declare class ToolkitCoordinator {
      * @param toolId Tool identifier
      * @param updates Partial configuration updates
      */
-    updateToolConfig(toolId: "textToSpeech", updates: Partial<TTSToolConfig>): void;
+    updateToolConfig(toolId: "textToSpeech", updates: Partial<TextToSpeechToolProviderConfig>): void;
     updateToolConfig(toolId: string, updates: Partial<ToolProviderConfig>): void;
     /**
-     * Update the enabled tool list for one placement level.
+     * Patch one or more placement levels in the canonical tools config.
      *
      * This is the generic placement companion to {@link updateToolConfig}:
      * it validates the next canonical tools config, keeps the policy
      * engine in lockstep, and emits the same policy-change event used by
      * live toolbars/debug panels.
      */
-    updateToolPlacement(level: ToolPlacementLevel, toolIds: string[]): void;
-    /**
-     * Patch one or more placement levels in the canonical tools config.
-     */
     updateToolsPlacement(partial: ToolPlacementConfig): void;
     /**
      * Resolve the visible tool set for a given placement level + scope.
      *
-     * Thin shim over the owned tool-policy engine.
+     * Delegates to the owned tool-policy engine and logs the decision's
+     * diagnostics through {@link warnPolicyDiagnostics}.
      */
     decideToolPolicy(request: ToolPolicyDecisionRequest): ToolPolicyDecision;
+    /**
+     * Log each policy diagnostic as a console warning, once per code and tool
+     * id, and per item for `tool-policy.itemSettingNotApplied`. Decisions re-run
+     * on every input change, so a conflict would otherwise repeat on each.
+     */
+    private warnPolicyDiagnostics;
+    /**
+     * File a mounted item's policy settings (`requiredTools`, `restrictedTools`,
+     * `toolParameters`) under its canonical id. They govern the decisions scoped
+     * to that item: its own item-level toolbar, and the feature decisions its
+     * content asks with the item's scope. `pie-item-scope` registers them from
+     * its `settings` property; the returned function withdraws them.
+     */
+    registerItemSettings(itemId: string, settings: ItemSettings): () => void;
     /**
      * Resolve eligibility for one PNP/AfA feature id, independent of toolbar
      * placement.
@@ -679,14 +776,23 @@ export declare class ToolkitCoordinator {
      * capability it asks about, which is indistinguishable from a student who was
      * properly declined — so without this, forgetting {@link updateAssessment}
      * presents as an accommodation that silently never appears.
+     *
+     * A coordinator built with `assessmentOptional` reports only while PNP
+     * enforcement is explicitly `"on"`. Its toolkit binds whatever assessment the
+     * host gave, usually none, and a host that passes no profile and leaves
+     * enforcement unset or `"off"` has asked for no accommodation.
+     *
+     * `scope` is the surface asking; an item's scope brings in that item's
+     * registered settings ({@link registerItemSettings}).
      */
-    decideFeaturePolicy(featureId: string): FeaturePolicyDecision;
+    decideFeaturePolicy(featureId: string, scope?: ToolScope): FeaturePolicyDecision;
     /**
      * Subscribe to policy-engine change events. Fires whenever the
      * coordinator's bound inputs change (`updateToolConfig`,
-     * `updateToolPlacement`, `updateAssessment`, `updateCurrentItemRef`,
-     * `setPnpEnforcement`) or a custom `PolicySource` is registered /
-     * removed via {@link registerPolicySource}.
+     * `updateToolsPlacement`, `updateAssessment`, `setPnpEnforcement`), an
+     * item's settings are registered or withdrawn ({@link registerItemSettings}),
+     * or a custom `PolicySource` is registered / removed via
+     * {@link registerPolicySource}.
      *
      * The listener receives a `ToolPolicyChangeEvent` with the event
      * `reason` and a frozen snapshot of the engine inputs. Listeners
@@ -712,31 +818,20 @@ export declare class ToolkitCoordinator {
     /**
      * Bind (or clear) the active assessment for PNP/profile policy decisions.
      *
-     * Under auto-mode (no host override via {@link setPnpEnforcement}),
-     * the coordinator promotes the engine to `pnpEnforcement: "on"`
-     * iff the assessment carries any profile precedence material
-     * (`personalNeedsProfile`, `settings.districtPolicy`,
-     * `settings.testAdministration`) or the currently-bound item ref
-     * carries item-level profile policy inputs. A bare assessment record (just
+     * Under auto-mode (no host override via {@link setPnpEnforcement}), a
+     * decision enforces PNP/profile policy iff the assessment carries profile
+     * precedence material (`personalNeedsProfile`, `settings.districtPolicy`,
+     * `settings.testAdministration`), or the decision is scoped to an item whose
+     * settings carry item-level policy inputs. A bare assessment record (just
      * `id` / `name`, no PNP, no settings) keeps `"off"`.
      *
      * The host override set via {@link setPnpEnforcement} is sticky
-     * across assessment swaps; calling with `null` clears the binding
-     * and re-runs the auto-mode helper.
+     * across assessment swaps.
      */
     updateAssessment(assessment: AssessmentEntity | null): void;
     /**
-     * Bind (or clear) the current item reference for policy decisions.
-     *
-     * Used by item-level profile gates (item `requiredTools` /
-     * `restrictedTools` / `toolParameters`). Item-level profile material
-     * also feeds {@link resolveEffectivePnpEnforcement} — navigating
-     * to an item with profile settings can flip auto-mode to `"on"` even
-     * when the parent assessment carries no profile block of its own.
-     */
-    updateCurrentItemRef(itemRef: AssessmentItemRef | null): void;
-    /**
-     * Override the auto-mode PNP/profile enforcement decision.
+     * Override the auto-mode PNP/profile enforcement decision; `null` returns
+     * to auto-mode.
      */
     setPnpEnforcement(mode: PnpEnforcementMode | null): void;
     /**
@@ -757,19 +852,10 @@ export declare class ToolkitCoordinator {
      * compose with the built-in PNP policy source).
      */
     registerPolicySource(source: PolicySource): () => void;
-    /**
-     * Register a host-owned resolver for one tool's render context.
-     *
-     * Resolvers are evaluated only for tools that already survived the
-     * framework policy pipeline. They can hide the tool for the current
-     * scope or attach render params consumed by the packaged registration;
-     * they cannot re-enable tools blocked by placement, provider config,
-     * host policy, or PNP/profile rules.
-     */
-    registerToolContextResolver(toolId: string, resolver: ToolContextResolver): () => void;
     hasToolContextResolver(toolId: string): boolean;
     resolveToolContext(context: ToolContextResolverContext): ResolvedToolContext | null;
     onToolContextResolverChange(listener: () => void): () => void;
+    getToolRegistry(): ToolRegistry;
     /**
      * Claim requests for one placement level. Called by a toolbar on mount.
      */
@@ -788,26 +874,26 @@ export declare class ToolkitCoordinator {
      * surface, and a host that swapped the registry for one without the tool would
      * otherwise lose the whole surface to an exception over an absent action.
      */
-    canRequestTool(toolId: string, level?: ToolOpenRequest["level"]): boolean;
+    canRequestTool(toolId: string, level?: ToolOpenRequest["level"], scopeId?: string): boolean;
     onToolRequestTargetsChange(listener: () => void): () => void;
-    /**
-     * Compute the effective PNP/profile enforcement mode given the explicit
-     * host override and the auto-mode helper.
-     *
-     * Auto-mode (no override) defers to
-     * {@link resolveDefaultPnpEnforcement}, which returns `"on"`
-     * exactly when the bound assessment or current item ref carries
-     * profile precedence material (PNP, district policy, test
-     * administration, item-level required/restricted/parameters), and
-     * `"off"` otherwise. Profile gates engage the moment profile material
-     * is present.
-     */
-    private resolveEffectivePnpEnforcement;
     private resolveConfiguredPnpEnforcement;
     /**
      * Apply tool configuration changes to underlying services.
      * Called after updateToolConfig().
      */
     private _applyToolConfigChange;
+    /**
+     * Register the provider a tool's updated config builds, replacing the one
+     * registered under the tool's id. Registration completes before this returns,
+     * so a check on the policy change the update dispatched finds the new provider.
+     */
+    private _registerChangedToolProvider;
+    /**
+     * Re-register the text-to-speech provider for the current config and registry, then
+     * re-initialize unless initialization is lazy. An initialization already
+     * running finishes first: it would otherwise mark its provider ready after
+     * the reset.
+     */
+    private scheduleTTSReconfigure;
     private _reconfigureTTSProvider;
 }