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

package/dist/services/ToolkitCoordinator.d.ts

@@ -1,20 +1,28 @@
 /**
- * ToolkitCoordinator - Centralized Assessment Toolkit Service Management
+ * ToolkitCoordinator: one per assessment, the owner of every toolkit service
+ * (TTSService, ToolCoordinator, HighlightCoordinator, ElementToolStateStore,
+ * AccessibilityCatalogResolver, ToolProviderRegistry), the ToolPolicyEngine,
+ * the framework-error bus and the section controllers. It holds toolkit
+ * concerns only; navigation, timing and progress belong to the player.
  *
- * Orchestrates all toolkit services (TTS, tools, accessibility, state management) from a single entry point.
- * Provides centralized configuration for tool availability and settings.
- *
- * Key features:
- * - Owns all toolkit services (TTSService, ToolCoordinator, HighlightCoordinator, ElementToolStateStore, AccessibilityCatalogResolver)
- * - Single configuration point for tool availability and settings
- * - Sensible defaults for standalone usage
- * - Direct access for settings widgets (no player dependency)
- * - Clean separation: toolkit concerns only (NOT assessment state like navigation, timing, progress)
- *
- * Part of PIE Assessment Toolkit.
+ * Layout: the module's exported config, hook and event types come first, then
+ * the class, whose members run in this order:
+ * - config resolution and the constructor;
+ * - error, telemetry and tool-failure reporting, readiness listeners and the
+ *   framework-error bus;
+ * - element tool-state persistence;
+ * - tool registry adoption and provider registration;
+ * - section-event subscriptions, which follow the active cohort;
+ * - section controller creation, publication and disposal;
+ * - coordinator disposal;
+ * - TTS bring-up and readiness;
+ * - tool config updates and the policy engine surface, with the tool-context
+ *   resolvers split around it (installation before, queries after);
+ * - tool-open requests;
+ * - config-change application and TTS reconfiguration, last.
  */
-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, ToolParametersFor } 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";
@@ -22,55 +30,18 @@ import { ElementToolStateStore } from "./ElementToolStateStore.js";
 import { type FrameworkErrorModel } from "./framework-error.js";
 import { FrameworkErrorBus, type FrameworkErrorListener } from "./framework-error-bus.js";
 import { HighlightCoordinator } from "./HighlightCoordinator.js";
-import { ToolCoordinator } from "./ToolCoordinator.js";
+import type { ToolCoordinatorApi } from "./interfaces.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 { ToolFailurePhase } from "./tool-failure.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 ToolPolicyDiagnostic, 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 +57,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 +100,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 +146,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" | ToolFailurePhase;
+    /** 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;
@@ -188,8 +163,8 @@ export interface SectionControllerLifecycleEvent {
 /**
  * Subscribe-time arguments for {@link ToolkitCoordinator.subscribeSectionEvents}.
  *
- * Phase D contract: subscriptions follow the toolkit's *active section
- * cohort* automatically. The listener is bound to whatever section
+ * Subscriptions follow the toolkit's *active section cohort*
+ * automatically. The listener is bound to whatever section
  * controller is active at subscribe time and is migrated, with snapshot
  * replay, on every cohort transition. There is no per-subscription
  * `(sectionId, attemptId)` binding.
@@ -210,8 +185,8 @@ export type SectionScopedEvent = Extract<SectionControllerEvent, {
 /**
  * Subscribe-time arguments for {@link ToolkitCoordinator.subscribeItemEvents}.
  *
- * See {@link SectionEventSubscriptionArgs} for the Phase D active-cohort
- * binding contract.
+ * See {@link SectionEventSubscriptionArgs} for the active-cohort binding
+ * contract.
  */
 export interface SectionItemEventSubscriptionArgs {
     listener: (event: SectionItemEvent) => void;
@@ -222,8 +197,8 @@ export interface SectionItemEventSubscriptionArgs {
  * Subscribe-time arguments for
  * {@link ToolkitCoordinator.subscribeSectionLifecycleEvents}.
  *
- * See {@link SectionEventSubscriptionArgs} for the Phase D active-cohort
- * binding contract.
+ * See {@link SectionEventSubscriptionArgs} for the active-cohort binding
+ * contract.
  */
 export interface SectionScopedEventSubscriptionArgs {
     listener: (event: SectionScopedEvent) => void;
@@ -249,9 +224,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,23 +244,12 @@ 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
+ * // Exported by @pie-players/pie-default-tool-loaders
  * const toolRegistry = createPackagedToolRegistry();
  *
  * // Create coordinator with configuration
@@ -295,7 +259,7 @@ export interface ToolkitServiceBundle {
  *   tools: {
  *     providers: {
  *       textToSpeech: { enabled: true, backend: 'browser' },
- *       answerEliminator: { enabled: true, strategy: 'strikethrough' }
+ *       answerEliminator: { enabled: true }
  *     },
  *     placement: {
  *       item: ['textToSpeech', 'answerEliminator']
@@ -318,7 +282,7 @@ export declare class ToolkitCoordinator {
     readonly config: ToolkitCoordinatorConfig;
     /** Managed services (public for direct access) */
     readonly ttsService: TTSService;
-    readonly toolCoordinator: ToolCoordinator;
+    readonly toolCoordinator: ToolCoordinatorApi;
     readonly highlightCoordinator: HighlightCoordinator;
     readonly elementToolStateStore: ElementToolStateStore;
     readonly catalogResolver: AccessibilityCatalogResolver;
@@ -327,22 +291,42 @@ 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;
+    /** Tool failures already reported, by phase and tool, each reported once. */
+    private readonly reportedToolFailures;
+    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;
@@ -353,8 +337,8 @@ export declare class ToolkitCoordinator {
     private readonly sectionPersistenceStrategies;
     private readonly sectionControllerLifecycleListeners;
     /**
-     * Phase D: every active section-event subscription, indexed by
-     * listener identity. The listener follows the toolkit's active
+     * Every active section-event subscription, indexed by listener
+     * identity. The listener follows the toolkit's active
      * section cohort across transitions; this map is the registry the
      * coordinator iterates on every cohort change to detach the listener
      * from the outgoing controller, attach it to the new one, and replay
@@ -366,22 +350,26 @@ export declare class ToolkitCoordinator {
      */
     private readonly activeSubscriptions;
     /**
-     * Phase D: map key of the section controller currently treated as
-     * the *active cohort*. Set by `getOrCreateSectionController` (both
+     * 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;
     private readonly frameworkErrorBus;
     private readonly ownsFrameworkErrorBus;
+    /** The instance behind {@link toolCoordinator}, kept for disposal. */
+    private readonly ownedToolCoordinator;
     private frameworkErrorHookUnsubscribe;
     private disposePromise;
     /**
@@ -392,32 +380,12 @@ 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}).
-     * `"on"` / `"off"` are explicit host opt-in / opt-out and stick
-     * across subsequent assessment / item 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 reported since the last input change, keyed by code,
+     * tool id and, for `tool-policy.itemSettingNotApplied`, item id; see
+     * {@link warnPolicyDiagnostics}.
      */
-    private boundCurrentItemRef;
+    private readonly reportedPolicyDiagnostics;
+    private readonly policyDiagnosticListeners;
     /**
      * 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,42 @@ 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 that section.
+     */
     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. A toolbar tool counts only surfaces where PNP
+     * enforcement is on; a region feature ignores enforcement, as its decisions
+     * do. 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 reportStartFailure;
+    /**
+     * Report that a tool failed in `phase`. A module that failed to load follows
+     * the start-failure policy: the tool degrades, so toolbars withhold it, unless
+     * policy grants it. Every other phase is recoverable, since its report site
+     * keeps a recovery, and is reported on a microtask. Reported once per tool and
+     * phase however many toolbars or instances fail. A module failure re-announces the request targets, since
+     * the reporting toolbar no longer hosts the tool.
+     */
+    reportToolFailure(toolId: string, phase: ToolFailurePhase, 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.
      *
@@ -516,43 +519,47 @@ export declare class ToolkitCoordinator {
      * @internal
      */
     reportFrameworkError(model: FrameworkErrorModel): void;
+    private sectionControllerKey;
     private getSectionControllerMapKey;
     private createDefaultSectionPersistence;
     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.
      */
     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, 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: {
@@ -561,7 +568,7 @@ export declare class ToolkitCoordinator {
     }): SectionControllerHandle | undefined;
     subscribeSectionEvents(args: SectionEventSubscriptionArgs): () => void;
     /**
-     * Bind a Phase D subscription to a section controller. Detaches any
+     * Bind an active-cohort subscription to a section controller. Detaches any
      * prior controller binding the subscription was holding, attaches a
      * fresh `controller.subscribe(...)` callback, and replays the
      * canonical late-subscribe sequence (content-loaded × N then
@@ -594,6 +601,12 @@ export declare class ToolkitCoordinator {
      * re-bind them to the new controller.
      */
     private clearActiveCohortIfMatches;
+    /**
+     * Detach every active subscription from its controller. Iterates a snapshot,
+     * as `setActiveCohort` does, because a disposer may mutate
+     * `activeSubscriptions`.
+     */
+    private detachActiveSubscriptions;
     private buildSectionEventPredicate;
     private collectEventItemIds;
     /**
@@ -636,17 +649,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;
@@ -666,78 +693,79 @@ export declare class ToolkitCoordinator {
     private disposeOwnedResources;
     private waitForAdmittedInitialization;
     /**
-     * Initialize TTS service with provider
+     * Initialize the TTS service from the `textToSpeech` tool config.
      */
-    ensureTTSReady(config?: TTSToolConfig): Promise<void>;
+    ensureTTSReady(): 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
+     * Get tool configuration, or null if the tool is not configured.
      */
-    getToolConfig(toolId: "textToSpeech"): TTSToolConfig | null;
+    getToolConfig(toolId: "textToSpeech"): TextToSpeechToolProviderConfig | null;
     getToolConfig(toolId: string): ToolProviderConfig | null;
     /**
-     * Update tool configuration.
-     * Applies changes to underlying services.
-     *
-     * @param toolId Tool identifier
-     * @param updates Partial configuration updates
+     * Update tool configuration and apply the change to the underlying services.
      */
-    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;
+    /**
+     * Report each policy diagnostic as a console warning and to the
+     * {@link onPolicyDiagnostic} listeners, once per code and tool id, and per
+     * item for `tool-policy.itemSettingNotApplied`. Every toolbar and feature
+     * asks for decisions, so a conflict would otherwise repeat on each; the
+     * engine's input diagnostics arrive with each policy change.
+     */
+    private warnPolicyDiagnostics;
+    private notifyPolicyDiagnosticListener;
+    /**
+     * 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.
@@ -747,8 +775,8 @@ export declare class ToolkitCoordinator {
      * `pnpEnforcement` is not consulted.
      *
      * Reports once per coordinator when it is asked about a feature with no
-     * assessment bound. A host in that state gets a correct denial for every
-     * capability it asks about, which is indistinguishable from a student who was
+     * assessment bound. A host in that state gets a denial for every capability
+     * no item requires, which is indistinguishable from a student who was
      * properly declined — so without this, forgetting {@link updateAssessment}
      * presents as an accommodation that silently never appears.
      *
@@ -756,14 +784,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<K extends string>(featureId: K, scope?: ToolScope): FeaturePolicyDecision<ToolParametersFor<K>>;
     /**
      * 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
@@ -775,6 +807,7 @@ export declare class ToolkitCoordinator {
      * their own lifetime ends before the coordinator's.
      */
     onPolicyChange(listener: ToolPolicyChangeListener): () => void;
+    onPolicyDiagnostic(listener: (diagnostic: ToolPolicyDiagnostic) => void): () => void;
     /**
      * Subscribe to accessibility-catalog registrations and removals.
      *
@@ -789,31 +822,21 @@ 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. `"on"` and `"off"` stick across assessment swaps until
+     * cleared.
      */
     setPnpEnforcement(mode: PnpEnforcementMode | null): void;
     /**
@@ -834,19 +857,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 +879,19 @@ 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.
-     */
+    /** Apply an `updateToolConfig` change to the underlying services. */
     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.