@pie-players/pie-assessment-toolkit 0.3.74 → 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 TextToSpeechToolProviderConfig, type ToolProviderConfig, type ToolProvidersConfig, type ToolsConfigInput } 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 { 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 one thing
- * only a host-facing config has — a place to stash unrecognised keys, which the
- * resolved runtime settings do not carry.
- *
- * `provider` is typed from the `textToSpeech` tools-config entry instead: a host
- * gives either a server provider id or a runtime provider object, whose
- * `runtime.authFetcher` the TTS registration reads, and `TTSRuntimeSettings`
- * names only the id. The entry is therefore assignable to this type, which is
- * what `getToolConfig("textToSpeech")` returns.
- */
-export type TTSToolConfig = ToolConfig & Omit<TTSRuntimeSettings, "provider"> & {
-    provider?: TextToSpeechToolProviderConfig["provider"];
-    settings?: Record<string, unknown> & {
-        mathSpeech?: SREMathSpeechOptions;
-    };
-};
-/**
- * Answer eliminator tool configuration
- */
-export interface AnswerEliminatorToolConfig extends ToolConfig {
-    strategy?: "strikethrough" | "hide";
-}
 export interface ToolkitToolsConfig extends CanonicalToolsConfig {
     policy: ToolPolicyConfig;
     placement: Required<ToolPlacementConfig>;
@@ -86,8 +48,8 @@ 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?: ToolsConfigInput;
     /**
@@ -129,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
@@ -166,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;
@@ -249,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>;
@@ -269,24 +235,15 @@ 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
- * // createPackagedToolRegistry is exported by @pie-players/pie-default-tool-loaders
- * const toolRegistry = createPackagedToolRegistry();
+ * // 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({
@@ -295,7 +252,7 @@ export interface ToolkitServiceBundle {
  *   tools: {
  *     providers: {
  *       textToSpeech: { enabled: true, backend: 'browser' },
- *       answerEliminator: { enabled: true, strategy: 'strikethrough' }
+ *       answerEliminator: { enabled: true }
  *     },
  *     placement: {
  *       item: ['textToSpeech', 'answerEliminator']
@@ -327,22 +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;
+    /**
+     * 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. Until then the empty placeholder
-     * reports no missing registry, since the toolkit will supply one.
+     * 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;
@@ -369,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;
@@ -392,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.
@@ -431,7 +399,7 @@ export declare class ToolkitCoordinator {
     private reportedUnboundFeaturePolicy;
     /**
      * Whether {@link _initializeTTS} has already reported a non-browser backend
-     * falling back to browser speech because no `tts` provider is registered.
+     * 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.
      */
@@ -490,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.
      *
@@ -521,14 +521,17 @@ 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. A registry
-     * passed at construction stands, and the first call wins; `null` records a
-     * toolkit without one, which reports the registry as missing.
+     * 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.
      */
@@ -540,19 +543,22 @@ export declare class ToolkitCoordinator {
     private getProviderDescriptorTools;
     /**
      * Register the provider `tool`'s descriptor creates for the tool's current
-     * config, unless the tool is disabled or that provider id is registered. A
-     * descriptor that throws is reported the way a failed registration is.
+     * 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;
     /**
-     * A console warning and a `provider-register` framework error. `providerId`
-     * is null when resolving it is what failed; the warning names the tool then.
+     * A console warning and a `provider-register` framework error, under the
+     * start-failure policy every other tool failure follows.
      */
     private reportProviderRegisterFailure;
-    ensureProviderReady(providerId: string): Promise<ToolProviderApi>;
+    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: {
@@ -636,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;
@@ -668,47 +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"): TTSToolConfig | null;
+    getToolConfig(toolId: "textToSpeech"): TextToSpeechToolProviderConfig | null;
     getToolConfig(toolId: string): ToolProviderConfig | null;
     /**
      * Update tool configuration.
@@ -717,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.
@@ -756,14 +781,18 @@ export declare class ToolkitCoordinator {
      * 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
@@ -789,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;
     /**
@@ -834,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.
      */
@@ -865,37 +874,22 @@ 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() with the tool's config before the update.
+     * Called after updateToolConfig().
      */
     private _applyToolConfigChange;
     /**
-     * Register the provider a tool's updated config names, and unregister the
-     * one its previous config named when the provider id changed, as
-     * {@link _reconfigureTTSProvider} does for `tts`. Registration completes
-     * before this returns, so a check on the policy change the update dispatched
-     * finds the new provider.
+     * 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 `tts` provider for the current config and registry, then
+     * 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.