@pie-players/pie-assessment-toolkit 1.0.0-beta.7 → 1.0.0-beta.9

package/dist/services/ToolkitCoordinator.js

@@ -31,9 +31,9 @@ import { FrameworkErrorBus, } from "./framework-error-bus.js";
 import { HighlightCoordinator } from "./HighlightCoordinator.js";
 import { ToolCoordinator } from "./ToolCoordinator.js";
 import { TTSService } from "./TTSService.js";
-import { BrowserTTSProvider, browserFallbackConfig, } from "./tts/browser-provider.js";
-import { buildRuntimeTTSConfig, resolveTTSBackend, resolveTTSRuntimeSettings, } from "./tts-runtime-config.js";
 import { ToolProviderRegistry } from "./tool-providers/index.js";
+import { TtsLifecycle, TTS_TOOL_ID, deepMergeMathSpeech, } from "./tts/tts-lifecycle.js";
+import { DEFAULT_TOOL_PROVIDERS } from "./tool-provider-defaults.js";
 import { ToolRegistry } from "./ToolRegistry.js";
 import { ToolRequestRegistry } from "./tool-request.js";
 import { ToolPolicyEngine, } from "../policy/engine.js";
@@ -52,13 +52,11 @@ class SectionControllerRetiredError extends Error {
         this.name = "SectionControllerRetiredError";
     }
 }
-const isPlainRecord = (value) => !!value && typeof value === "object" && !Array.isArray(value);
 const mergeToolConfigUpdate = (toolId, current, updates) => {
     const next = { ...current, ...updates };
-    if (toolId === "textToSpeech" &&
-        isPlainRecord(current.mathSpeech) &&
-        isPlainRecord(updates.mathSpeech)) {
-        next.mathSpeech = { ...current.mathSpeech, ...updates.mathSpeech };
+    const deepMathSpeech = deepMergeMathSpeech(toolId, current, updates);
+    if (deepMathSpeech) {
+        next.mathSpeech = deepMathSpeech;
     }
     return next;
 };
@@ -136,11 +134,7 @@ export class ToolkitCoordinator {
     hooks;
     lazyInit;
     /** Track TTS initialization state */
-    ttsInitialized = false;
-    /** Text-to-speech failed to start and policy does not grant it. */
-    ttsDegraded = false;
-    ttsInitPromise;
-    ttsReconfigurePromise;
+    tts;
     /**
      * The loader ran, whether or not it returned state. A failed load is
      * reported once and the coordinator runs without saved tool state.
@@ -243,18 +237,6 @@ export class ToolkitCoordinator {
      * lifetime for no new information.
      */
     reportedUnboundFeaturePolicy = false;
-    /**
-     * 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.
-     */
-    reportedMissingTTSProvider = false;
-    /**
-     * The backend of a fallback {@link reportMissingTTSProvider} held back while
-     * the registry was unsettled, reported if the bound toolkit has no registry.
-     */
-    heldMissingTTSProviderBackend = null;
     /**
      * Whether {@link validateToolsConfig} has already reported validating with
      * no registry (`tools.registryUnavailable`). Once per coordinator: every
@@ -278,13 +260,7 @@ export class ToolkitCoordinator {
                 toolRegistry,
             });
         const defaultProviders = {
-            textToSpeech: {
-                enabled: true,
-                backend: "browser",
-            },
-            annotationToolbar: {
-                enabled: true,
-            },
+            ...DEFAULT_TOOL_PROVIDERS,
         };
         return {
             ...config,
@@ -358,7 +334,27 @@ export class ToolkitCoordinator {
         // A caller that speaks without `ensureTTSReady()` first, such as selection
         // read-aloud, starts the service instead of finding it uninitialized.
         this.ttsService.setReadinessGate(() => this.ensureTTSReady());
-        this.ttsService.setMathSpeechSource(() => buildRuntimeTTSConfig(resolveTTSRuntimeSettings(this.resolveTTSToolConfig())).providerOptions?.mathSpeech);
+        this.tts = new TtsLifecycle({
+            assertNotDisposed: () => this.assertNotDisposed(),
+            isDisposalStarted: () => this.disposePromise !== null,
+            isDisposalError: (error) => error instanceof ToolkitCoordinatorDisposedError,
+            emitTelemetry: (eventName, payload) => this.emitTelemetry(eventName, payload),
+            hooks: this.hooks,
+            toolProviderRegistry: this.toolProviderRegistry,
+            initializeProvider: (toolId, fallbackFollows) => this.initializeProvider(toolId, fallbackFollows),
+            ttsService: this.ttsService,
+            catalogResolver: this.catalogResolver,
+            clearDegradedTool: (toolId) => void this.degradedTools.delete(toolId),
+            reportStartFailure: (error, context, toolIds) => this.reportStartFailure(error, context, toolIds),
+            isToolGranted: (toolId) => this.isToolGranted(toolId),
+            lazyInit: this.lazyInit,
+            isToolRegistryPending: () => this.toolRegistryPending(),
+            providersConfig: () => this.config.tools?.providers,
+            getProviderDescriptorTools: () => this.getProviderDescriptorTools(),
+            registerProviderFromTool: (tool, replace) => this.registerProviderFromTool(tool, replace),
+            notifyReadyChange: () => this.notifyReadyChange(),
+        });
+        this.ttsService.setMathSpeechSource(() => this.tts.mathSpeechRuntimeOptions());
         this.setupStatePersistenceHooks();
         // The unified ToolPolicyEngine, seeded with the validated tools config.
         // The assessment starts `null` and items register their settings as they
@@ -724,17 +720,6 @@ export class ToolkitCoordinator {
     toolRegistryPending() {
         return !this.toolRegistrySettled && !this.toolRegistryAbsent;
     }
-    reportMissingTTSProvider(backend) {
-        // The toolkit this coordinator binds to may still supply the provider.
-        if (this.toolRegistryPending()) {
-            this.heldMissingTTSProviderBackend = backend;
-            return;
-        }
-        if (this.reportedMissingTTSProvider)
-            return;
-        this.reportedMissingTTSProvider = true;
-        console.warn(`[ToolkitCoordinator] Text-to-speech is configured for the "${backend}" backend but falls back to browser speech: no "textToSpeech" tool provider is registered. A coordinator registers tool providers only from its \`toolRegistry\`, or from its toolkit's when constructed without one, so supply one that carries the text-to-speech registration — for the packaged capability set, \`createPackagedToolRegistry()\` from "@pie-players/pie-default-tool-loaders". Reported once per coordinator.`);
-    }
     /**
      * 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
@@ -751,8 +736,6 @@ export class ToolkitCoordinator {
             return false;
         if (!registry && this.toolRegistryAbsent)
             return false;
-        const heldBackend = this.heldMissingTTSProviderBackend;
-        this.heldMissingTTSProviderBackend = null;
         const strictness = this.config.toolConfigStrictness ?? "error";
         const source = "ToolkitCoordinator.adoptToolRegistry";
         if (!registry) {
@@ -762,13 +745,13 @@ export class ToolkitCoordinator {
                 source,
                 toolRegistry: this.toolRegistry,
             });
-            if (heldBackend)
-                this.reportMissingTTSProvider(heldBackend);
+            this.tts.reportHeldMissingProvider();
             return false;
         }
         this.toolRegistrySettled = true;
         this.toolRegistry = registry;
         this.config.toolRegistry = registry;
+        this.tts.discardHeldMissingProvider();
         try {
             // Warn at most: the config was accepted at construction, and a binding
             // toolkit has no caller to throw to.
@@ -782,16 +765,14 @@ export class ToolkitCoordinator {
             console.warn("[ToolkitCoordinator] Tool config does not validate against the adopted tool registry:", err);
         }
         this.policyEngine.replaceToolRegistry(registry, this.config.tools);
-        const ttsStarted = this.ttsInitialized ||
-            this.ttsInitPromise !== undefined ||
-            this.ttsReconfigurePromise !== undefined;
+        const ttsStarted = this.tts.isStarted();
         for (const tool of this.getProviderDescriptorTools()) {
-            if (ttsStarted && tool.toolId === "textToSpeech")
+            if (ttsStarted && this.tts.ownsTool(tool.toolId))
                 continue;
             void this.registerProviderFromTool(tool);
         }
         if (ttsStarted)
-            this.scheduleTTSReconfigure();
+            this.tts.scheduleReconfigure();
         return true;
     }
     _registerToolProviders() {
@@ -1738,159 +1719,19 @@ export class ToolkitCoordinator {
         if (this.coordinatorReadyPromise) {
             pending.add(this.coordinatorReadyPromise);
         }
-        if (this.ttsInitPromise)
-            pending.add(this.ttsInitPromise);
-        if (this.ttsReconfigurePromise) {
-            pending.add(this.ttsReconfigurePromise);
-        }
+        this.tts.flushInitPromises(pending);
         for (const promise of this.providerInitPromises.values()) {
             pending.add(promise);
         }
         await settleAll(pending);
     }
     /**
-     * Initialize the TTS service from the `textToSpeech` tool config.
+     * Initialize the TTS service from the `textToSpeech` tool config. The
+     * lifecycle itself lives in `services/tts/tts-lifecycle.ts`; the coordinator
+     * keeps the public method hosts call.
      */
     async ensureTTSReady() {
-        this.assertNotDisposed();
-        await this.waitForPendingTTSReconfigure();
-        this.assertNotDisposed();
-        if (this.ttsInitialized)
-            return;
-        if (this.ttsInitPromise)
-            return this.ttsInitPromise;
-        this.ttsInitPromise = this._initializeTTS()
-            .then(() => this.assertNotDisposed())
-            .finally(() => {
-            this.ttsInitPromise = undefined;
-            this.notifyReadyChange();
-        });
-        return this.ttsInitPromise;
-    }
-    async waitForPendingTTSReconfigure() {
-        let pending = this.ttsReconfigurePromise;
-        while (pending) {
-            await pending;
-            pending = this.ttsReconfigurePromise;
-        }
-    }
-    async _initializeTTS() {
-        if (this.ttsInitialized)
-            return;
-        const resolvedToolConfig = this.resolveTTSToolConfig();
-        const runtimeSettings = resolveTTSRuntimeSettings(resolvedToolConfig);
-        const resolvedBackend = resolveTTSBackend(runtimeSettings);
-        const runtimeTTSConfig = buildRuntimeTTSConfig(runtimeSettings);
-        await this.hooks.onBeforeTTSInit?.({
-            phase: "tts-init",
-            details: {
-                backend: resolvedBackend,
-            },
-        });
-        this.assertNotDisposed();
-        await this.emitTelemetry("pie-toolkit-tts-init-start", {
-            backend: resolvedBackend,
-        });
-        await this.emitTelemetry("pie-tool-init-start", {
-            toolId: "textToSpeech",
-            operation: "tts-init",
-            backend: resolvedBackend,
-        });
-        if (this.toolProviderRegistry.has("textToSpeech")) {
-            try {
-                // Browser speech follows a server provider that fails to start.
-                const ttsProvider = await this.initializeProvider("textToSpeech", true);
-                const providerInstance = await ttsProvider.createInstance();
-                await this.initializeTTSService(providerInstance, runtimeTTSConfig);
-                await this.emitTelemetry("pie-toolkit-tts-init-success", {
-                    provider: "registry",
-                });
-                await this.emitTelemetry("pie-tool-init-success", {
-                    toolId: "textToSpeech",
-                    operation: "tts-init",
-                    backend: resolvedBackend,
-                    provider: "registry",
-                });
-                return;
-            }
-            catch (error) {
-                if (error instanceof ToolkitCoordinatorDisposedError)
-                    throw error;
-                const normalized = error instanceof Error ? error : new Error(String(error));
-                await this.emitTelemetry("pie-tool-init-fallback", {
-                    toolId: "textToSpeech",
-                    operation: "tts-init",
-                    backend: resolvedBackend,
-                    fromProvider: "registry",
-                    toProvider: "browser",
-                    reason: normalized.message,
-                });
-                console.warn("[ToolkitCoordinator] Failed to initialize TTS via registry, falling back to browser provider:", normalized);
-            }
-        }
-        else if (resolvedBackend !== "browser") {
-            this.reportMissingTTSProvider(resolvedBackend);
-        }
-        // Browser speech, configured or standing in for a backend that has no
-        // provider or failed to start.
-        const provider = new BrowserTTSProvider();
-        try {
-            await this.initializeTTSService(provider, resolvedBackend === "browser"
-                ? runtimeTTSConfig
-                : browserFallbackConfig(runtimeTTSConfig));
-            await this.emitTelemetry("pie-toolkit-tts-init-success", {
-                provider: "browser-fallback",
-            });
-            await this.emitTelemetry("pie-tool-init-success", {
-                toolId: "textToSpeech",
-                operation: "tts-init",
-                backend: resolvedBackend,
-                provider: "browser-fallback",
-            });
-        }
-        catch (error) {
-            if (error instanceof ToolkitCoordinatorDisposedError)
-                throw error;
-            const normalized = error instanceof Error ? error : new Error(String(error));
-            this.reportStartFailure(normalized, { phase: "tts-init" }, ["textToSpeech"]);
-            await this.emitTelemetry("pie-toolkit-tts-init-error", {
-                message: normalized.message,
-            });
-            await this.emitTelemetry("pie-tool-init-error", {
-                toolId: "textToSpeech",
-                operation: "tts-init",
-                backend: resolvedBackend,
-                errorType: "TTSInitError",
-                message: normalized.message,
-            });
-            throw normalized;
-        }
-    }
-    resolveTTSToolConfig() {
-        return this.getTTSConfigFromProviders() || {};
-    }
-    async initializeTTSService(provider, config) {
-        const nextProviderOptions = {
-            ...config.providerOptions,
-            __pieTelemetry: async (eventName, payload) => {
-                await this.emitTelemetry(eventName, {
-                    toolId: "textToSpeech",
-                    ...(payload || {}),
-                });
-            },
-        };
-        const nextConfig = {
-            ...config,
-            providerOptions: nextProviderOptions,
-        };
-        await this.ttsService.initialize(provider, nextConfig);
-        this.assertNotDisposed();
-        this.ttsService.setCatalogResolver(this.catalogResolver);
-        this.ttsInitialized = true;
-        this.ttsDegraded = false;
-        this.degradedTools.delete("textToSpeech");
-        await this.hooks.onTTSReady?.();
-        this.assertNotDisposed();
+        return this.tts.ensureReady();
     }
     async waitUntilReady() {
         this.assertNotDisposed();
@@ -1901,8 +1742,8 @@ export class ToolkitCoordinator {
         this.coordinatorReadyPromise = (async () => {
             await this.ensureStateLoaded();
             this.assertNotDisposed();
-            if (this.ttsRequiredForReadiness()) {
-                await this.startTTSForReadiness();
+            if (this.tts.requiredForReadiness()) {
+                await this.tts.startForReadiness();
             }
             this.assertNotDisposed();
             if (!this.coordinatorReadyNotified) {
@@ -1920,39 +1761,9 @@ export class ToolkitCoordinator {
     }
     isReady() {
         return ((this.stateLoadSettled || !this.hooks.loadToolState) &&
-            (this.ttsInitialized ||
-                this.ttsDegraded ||
-                !this.ttsRequiredForReadiness()));
-    }
-    /**
-     * 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.
-     */
-    ttsRequiredForReadiness() {
-        if (this.getTTSConfigFromProviders()?.enabled === false)
-            return false;
-        return !this.lazyInit || this.isToolGranted("textToSpeech");
-    }
-    /**
-     * 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.
-     */
-    async startTTSForReadiness() {
-        try {
-            await this.ensureTTSReady();
-        }
-        catch (error) {
-            if (error instanceof ToolkitCoordinatorDisposedError)
-                throw error;
-            if (this.isToolGranted("textToSpeech"))
-                throw error;
-            this.ttsDegraded = true;
-            this.notifyReadyChange();
-        }
-    }
-    getTTSConfigFromProviders() {
-        return this.config.tools?.providers?.textToSpeech;
+            (this.tts.started ||
+                this.tts.failedUngranted ||
+                !this.tts.requiredForReadiness()));
     }
     assertCanonicalToolId(toolId) {
         if (typeof toolId !== "string" || toolId.trim().length === 0) {
@@ -2360,8 +2171,8 @@ export class ToolkitCoordinator {
     _applyToolConfigChange(toolId) {
         if (this.disposePromise !== null)
             return;
-        if (toolId === "textToSpeech") {
-            this.scheduleTTSReconfigure();
+        if (this.tts.ownsTool(toolId)) {
+            this.tts.scheduleReconfigure();
             return;
         }
         this._registerChangedToolProvider(toolId);
@@ -2379,54 +2190,4 @@ export class ToolkitCoordinator {
         this.degradedTools.delete(toolId);
         void this.registerProviderFromTool(registration, true);
     }
-    /**
-     * 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.
-     */
-    scheduleTTSReconfigure() {
-        const inFlight = this.ttsInitPromise;
-        const reconfigurePromise = inFlight
-            ? inFlight.catch(() => { }).then(() => this._reconfigureTTSProvider())
-            : this._reconfigureTTSProvider();
-        this.ttsReconfigurePromise = reconfigurePromise;
-        void reconfigurePromise.finally(() => {
-            if (this.ttsReconfigurePromise === reconfigurePromise) {
-                this.ttsReconfigurePromise = undefined;
-            }
-        });
-        void reconfigurePromise
-            .then(async () => {
-            if (this.disposePromise !== null)
-                return;
-            if (this.ttsRequiredForReadiness())
-                await this.startTTSForReadiness();
-        })
-            // Reported where it failed; a granted failure has nowhere else to go.
-            .catch(() => { });
-    }
-    async _reconfigureTTSProvider() {
-        this.ttsInitialized = false;
-        this.ttsDegraded = false;
-        this.degradedTools.delete("textToSpeech");
-        this.ttsInitPromise = undefined;
-        this.notifyReadyChange();
-        try {
-            // The next speak waits on readiness, which starts the new provider.
-            this.ttsService.releaseProvider();
-        }
-        catch {
-            // noop: release best effort
-        }
-        if (this.toolProviderRegistry.has("textToSpeech")) {
-            await this.toolProviderRegistry.unregister("textToSpeech");
-        }
-        if (this.disposePromise !== null)
-            return;
-        const ttsRegistration = this.getProviderDescriptorTools().find((tool) => tool.toolId === "textToSpeech");
-        if (!ttsRegistration)
-            return;
-        await this.registerProviderFromTool(ttsRegistration);
-    }
 }

package/dist/services/section-controller-types.d.ts

@@ -1,4 +1,4 @@
-import type { FormativeFeedbackReveal, FormativeMasteryRollup, FormativeSectionProjection, FormativeTryOutcome } from "@pie-players/pie-players-shared/formative";
+import type { FeedbackReveal, MasteryRollup, TrySectionProjection, TryOutcome } from "@pie-players/pie-players-shared/item-session-control";
 import type { MediaTimeSource, TimedMediaDegradation, TimedMediaSectionProjection, TimedMediaValidationError } from "@pie-players/pie-players-shared/timed-media";
 import type { SessionCommitReason } from "@pie-players/pie-players-shared/pie";
 import type { SectionControllerSessionState } from "@pie-players/pie-players-shared/types";
@@ -175,12 +175,12 @@ export type SectionControllerSectionErrorEvent = SectionControllerEventBase & {
     contentKind?: "item" | "passage" | "rubric" | "unknown";
     currentItemIndex: number;
 };
-export type SectionControllerFormativeTryRecordedEvent = SectionControllerEventBase & {
-    type: "formative-try-recorded";
+export type SectionControllerItemTryRecordedEvent = SectionControllerEventBase & {
+    type: "item-try-recorded";
     itemId: string;
     canonicalItemId: string;
     tryCount: number;
-    outcome: FormativeTryOutcome;
+    outcome: TryOutcome;
     /** Whether feedback is now on screen for this item. */
     revealed: boolean;
     currentItemIndex: number;
@@ -189,16 +189,16 @@ export type SectionControllerFormativeTryRecordedEvent = SectionControllerEventB
  * The reveal state changed without a Try being recorded: a learner dismissed
  * feedback to edit again, or a host forced a reveal or withdrew one.
  *
- * A Try that reveals reports through `formative-try-recorded`, which carries its
+ * A Try that reveals reports through `item-try-recorded`, which carries its
  * own `revealed`. This event is for every other transition.
  */
-export type SectionControllerFormativeRevealChangedEvent = SectionControllerEventBase & {
-    type: "formative-reveal-changed";
+export type SectionControllerItemFeedbackRevealChangedEvent = SectionControllerEventBase & {
+    type: "item-feedback-reveal-changed";
     itemId: string;
     canonicalItemId: string;
     revealed: boolean;
     /** Reveal level in force, when a host overrode the policy's. */
-    feedback?: FormativeFeedbackReveal;
+    feedback?: FeedbackReveal;
     /** Tries already spent; none of these transitions consume one. */
     tryCount: number;
     source: "learner" | "host";
@@ -206,7 +206,7 @@ export type SectionControllerFormativeRevealChangedEvent = SectionControllerEven
 };
 export type SectionControllerSectionMasteryChangedEvent = SectionControllerEventBase & {
     type: "section-mastery-changed";
-    mastery: FormativeMasteryRollup;
+    mastery: MasteryRollup;
     currentItemIndex: number;
 };
 /**
@@ -268,8 +268,28 @@ export type SectionControllerTimedMediaInvalidEvent = SectionControllerEventBase
     errors: TimedMediaValidationError[];
     currentItemIndex: number;
 };
-export type SectionControllerEvent = SectionControllerItemSessionDataChangedEvent | SectionControllerItemSessionMetaChangedEvent | SectionControllerItemSelectedEvent | SectionControllerSectionNavigationChangedEvent | SectionControllerSectionSessionAppliedEvent | SectionControllerContentLoadedEvent | SectionControllerItemPlayerErrorEvent | SectionControllerItemCompleteChangedEvent | SectionControllerSectionLoadingCompleteEvent | SectionControllerSectionItemsCompleteChangedEvent | SectionControllerSectionErrorEvent | SectionControllerFormativeTryRecordedEvent | SectionControllerFormativeRevealChangedEvent | SectionControllerSectionMasteryChangedEvent | SectionControllerTimedMediaCueChangedEvent | SectionControllerTimedMediaAudioStartedEvent | SectionControllerTimedMediaPolicyDegradedEvent | SectionControllerTimedMediaInvalidEvent;
+export type SectionControllerEvent = SectionControllerItemSessionDataChangedEvent | SectionControllerItemSessionMetaChangedEvent | SectionControllerItemSelectedEvent | SectionControllerSectionNavigationChangedEvent | SectionControllerSectionSessionAppliedEvent | SectionControllerContentLoadedEvent | SectionControllerItemPlayerErrorEvent | SectionControllerItemCompleteChangedEvent | SectionControllerSectionLoadingCompleteEvent | SectionControllerSectionItemsCompleteChangedEvent | SectionControllerSectionErrorEvent | SectionControllerItemTryRecordedEvent | SectionControllerItemFeedbackRevealChangedEvent | SectionControllerSectionMasteryChangedEvent | SectionControllerTimedMediaCueChangedEvent | SectionControllerTimedMediaAudioStartedEvent | SectionControllerTimedMediaPolicyDegradedEvent | SectionControllerTimedMediaInvalidEvent;
 export type SectionControllerEventType = SectionControllerEvent["type"];
+/** One item's part of a {@link SectionScore}. */
+export type SectionItemScore = {
+    canonicalItemId: string;
+    /**
+     * The item's element outcomes, one slot per scored model as
+     * `pie-item-player.provideScore()` returns them. `null` while the item is not
+     * rendered, or when it has no scorable model.
+     */
+    outcomes: Array<Record<string, unknown> | undefined> | null;
+};
+/** The section's browser score, from {@link SectionControllerHandle.score}. */
+export type SectionScore = {
+    /** Every item in the section, in section order. */
+    items: SectionItemScore[];
+};
+/**
+ * Scores one rendered item in the browser: its element outcomes, `false` when
+ * the item has no scorable model, or `null` when its player has not mounted.
+ */
+export type SectionItemScorer = (canonicalItemId: string) => Promise<false | null | Array<Record<string, unknown> | undefined>>;
 /**
  * Host-facing controller for a single section cohort.
  *
@@ -422,10 +442,30 @@ export interface SectionControllerHandle {
      * those boundaries.
      */
     setPendingSessionCommit?(commit: (() => void) | null): void;
+    /**
+     * Commit every element's pending response to the section session, so the
+     * next `getSession()` holds it. For a host about to read or submit the
+     * session; the controller already commits before its own boundaries.
+     */
+    commitPendingSessions?(): void;
+    /**
+     * Register how the controller scores a rendered item. The controller is
+     * DOM-free, so the layout that renders the item players supplies it, as with
+     * `setPendingSessionCommit`. The latest registration wins; the returned
+     * release unregisters this scorer and leaves a later one in place, so two
+     * layouts on one controller do not unregister each other.
+     */
+    registerItemScorer?(scorer: SectionItemScorer): () => void;
+    /**
+     * Score the section in the browser: each item's element outcomes, in section
+     * order. An item that is not rendered, or has no scorable model, scores
+     * `null`.
+     */
+    score?(): Promise<SectionScore>;
     /**
      * Record one Try for an item: derive correctness from the element outcomes,
      * increment the Try count, and reveal feedback if the item's resolved
-     * formative policy says so.
+     * item session control policy says so.
      *
      * `outcomes` is what `pie-item-player.provideScore()` returned. The caller
      * does not interpret it — correctness derivation belongs to the controller so
@@ -434,18 +474,29 @@ export interface SectionControllerHandle {
      * No-op when the item's policy is disabled, when feedback is already
      * revealed, or when Tries are spent, which makes a double submit safe.
      */
-    recordFormativeTry?(args: {
+    recordTry?(args: {
         itemId: string;
         outcomes?: unknown[];
     }): void;
+    /**
+     * Score a rendered item through the registered item scorer and record the
+     * Try from its outcomes: Check answer, for a host that hides the built-in
+     * control (`policies.checkControl.enabled: false`). Rejects, spending no
+     * Try, when no layout has registered a scorer, the item's player has not
+     * mounted, or scoring throws. A call while a check of the same item is
+     * pending is dropped.
+     */
+    checkItem?(args: {
+        itemId: string;
+    }): Promise<void>;
     /**
      * Dismiss a revealed item's feedback and reopen it for editing. Withdrawing
      * the reveal is what withdraws the `mode: "evaluate"` projection.
      *
      * The learner action, so it respects the Try budget: no-op when nothing is
-     * revealed or Tries are spent. Use `hideFormativeItem` for host authority.
+     * revealed or Tries are spent. Use `hideItemFeedback` for host authority.
      */
-    retryFormativeItem?(args: {
+    retryItem?(args: {
         itemId: string;
     }): void;
     /**
@@ -457,27 +508,27 @@ export interface SectionControllerHandle {
      * `feedback` is stated rather than taken from the policy, because a reveal
      * under `feedback: "none"` would project nothing.
      */
-    revealFormativeItem?(args: {
+    revealItemFeedback?(args: {
         itemId: string;
         feedback: "correctness" | "solution";
     }): void;
     /**
-     * Withdraw a reveal on host authority. Unlike `retryFormativeItem` this
+     * Withdraw a reveal on host authority. Unlike `retryItem` this
      * ignores the Try budget, so a host that revealed a spent item can put it
      * back.
      */
-    hideFormativeItem?(args: {
+    hideItemFeedback?(args: {
         itemId: string;
     }): void;
     /**
-     * The section's formative projection — resolved policies, per-item state, and
+     * The section's Try projection — resolved policies, per-item state, and
      * the mastery rollup.
      *
-     * `null` when no item in the section delivers formatively. The same
+     * `null` when no item in the section enables item session control. The same
      * projection rides on the composition model, so layouts normally read it from
      * there rather than calling this.
      */
-    getFormativeProjection?(): FormativeSectionProjection | null;
+    getTryProjection?(): TrySectionProjection | null;
     /**
      * Bind the section's Media Time Source — the only way it reaches media.
      *

package/dist/services/tool-config-validation.d.ts

@@ -3,7 +3,7 @@ import type { ToolRegistry } from "./ToolRegistry.js";
 export type ToolConfigStrictness = "off" | "warn" | "error";
 export type ToolConfigDiagnosticSeverity = "warning" | "error";
 export interface ToolConfigDiagnostic {
-    code: "tools.unknownToolId" | "tools.unsupportedLevel" | "tools.unplaceableActivation" | "tools.registryUnavailable" | "tools.unknownProviderKey" | "tools.providerSanitizeFailed" | "tools.providerValidateFailed" | "tools.invalidProviderValidation";
+    code: "tools.unknownToolId" | "tools.unsupportedLevel" | "tools.unplaceableActivation" | "tools.registryUnavailable" | "tools.unknownProviderKey" | "tools.providerSanitizeFailed" | "tools.providerValidateFailed" | "tools.invalidProviderValidation" | "tools.invalidProviderConfig";
     severity: ToolConfigDiagnosticSeverity;
     path: string;
     message: string;