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

package/dist/services/framework-error.d.ts

@@ -1,10 +1,25 @@
-import type { ToolConfigDiagnostic } from "./tool-config-validation.js";
+import type { ToolFailurePhase } from "./tool-failure.js";
 export type FrameworkErrorKind = "tool-config" | "runtime-init" | "runtime-dispose" | "coordinator-init" | "provider-init" | "provider-register" | "tts-init" | "tool-state-load" | "tool-state-save" | "section-controller-init" | "section-controller-dispose" | "tool-surface"
 /**
  * A toolbar could not load a tool's module. Recoverable unless policy grants
  * the tool: the toolbar withholds the tool and the assessment goes on.
  */
  | "tool-module-load"
+/**
+ * A toolbar threw opening a requested tool or answering whether it hosts one.
+ * Recoverable: the request goes unclaimed or passes the toolbar by.
+ */
+ | "tool-request"
+/**
+ * A tool registration's relevance check or applicability gate threw.
+ * Recoverable: the toolbar applies the answer a missing check would give.
+ */
+ | "tool-registration"
+/**
+ * A tool could not play, seek or change the rate of speech after it started.
+ * Recoverable: the tool stays available and the learner can retry.
+ */
+ | "tool-playback"
 /**
  * A timed-media section could not deliver a policy as authored: a media time
  * source missing `canPause` / `canRestrictSeeking` (recoverable — cues still
@@ -34,6 +49,14 @@ export type FrameworkErrorSeverity = "warning" | "error";
  * later section runs on, so readiness stays failed. Set by the report site.
  */
 export type FrameworkErrorScope = "cohort" | "runtime";
+/**
+ * The section a `cohort`-scoped error was reported for. A section can fail after
+ * the learner has left it, so a reader holding another section ignores the error.
+ */
+export interface FrameworkErrorCohort {
+    sectionId: string;
+    attemptId?: string;
+}
 export interface FrameworkErrorModel {
     kind: FrameworkErrorKind;
     severity: FrameworkErrorSeverity;
@@ -42,6 +65,8 @@ export interface FrameworkErrorModel {
     details: string[];
     recoverable: boolean;
     scope: FrameworkErrorScope;
+    /** Set on a `cohort`-scoped error whose report site knows its section. */
+    cohort?: FrameworkErrorCohort;
     cause?: unknown;
 }
 export declare function toFrameworkErrorModel(args: {
@@ -53,6 +78,7 @@ export declare function toFrameworkErrorModel(args: {
     recoverable?: boolean;
     /** Defaults to `runtime`. */
     scope?: FrameworkErrorScope;
+    cohort?: FrameworkErrorCohort;
     cause?: unknown;
 }): FrameworkErrorModel;
 export declare function frameworkErrorFromUnknown(args: {
@@ -61,6 +87,7 @@ export declare function frameworkErrorFromUnknown(args: {
     error: unknown;
     recoverable?: boolean;
     scope?: FrameworkErrorScope;
+    cohort?: FrameworkErrorCohort;
 }): FrameworkErrorModel;
 /**
  * Coordinator-side error context shape consumed by
@@ -73,7 +100,7 @@ export declare function frameworkErrorFromUnknown(args: {
  * truth for coordinator code; values of that type satisfy this shape.
  */
 export interface FrameworkErrorCoordinatorContext {
-    phase: "coordinator-ready" | "state-load" | "state-save" | "provider-register" | "provider-init" | "tts-init" | "section-controller-init" | "section-controller-dispose" | "tool-module-load";
+    phase: "coordinator-ready" | "state-load" | "state-save" | "provider-register" | "provider-init" | "tts-init" | "section-controller-init" | "section-controller-dispose" | ToolFailurePhase;
     toolId?: string;
     details?: Record<string, unknown>;
 }
@@ -95,10 +122,6 @@ export declare function frameworkErrorFromCoordinatorContext(args: {
     context: FrameworkErrorCoordinatorContext;
     recoverable?: boolean;
     scope?: FrameworkErrorScope;
-}): FrameworkErrorModel;
-export declare function frameworkErrorFromToolConfigDiagnostics(args: {
-    source: string;
-    diagnostics: ToolConfigDiagnostic[];
-    recoverable?: boolean;
+    cohort?: FrameworkErrorCohort;
 }): FrameworkErrorModel;
 export declare function formatFrameworkErrorForConsole(error: FrameworkErrorModel): string;

package/dist/services/framework-error.js

@@ -7,6 +7,7 @@ export function toFrameworkErrorModel(args) {
         details: [...(args.details || [])],
         recoverable: args.recoverable === true,
         scope: args.scope ?? "runtime",
+        ...(args.cohort ? { cohort: { ...args.cohort } } : {}),
         cause: args.cause,
     };
 }
@@ -20,6 +21,7 @@ export function frameworkErrorFromUnknown(args) {
         message,
         recoverable: args.recoverable,
         scope: args.scope,
+        cohort: args.cohort,
         cause: args.error,
     });
 }
@@ -33,6 +35,13 @@ const COORDINATOR_PHASE_TO_KIND = {
     "section-controller-init": "section-controller-init",
     "section-controller-dispose": "section-controller-dispose",
     "tool-module-load": "tool-module-load",
+    "tool-request-open": "tool-request",
+    "tool-request-host-check": "tool-request",
+    "tool-visibility": "tool-registration",
+    "tool-applicability": "tool-registration",
+    "tool-state-load": "tool-state-load",
+    "tool-state-save": "tool-state-save",
+    "tool-playback": "tool-playback",
 };
 /**
  * Build a {@link FrameworkErrorModel} from a coordinator-side error +
@@ -58,19 +67,7 @@ export function frameworkErrorFromCoordinatorContext(args) {
         error: args.error,
         recoverable: args.recoverable,
         scope: args.scope,
-    });
-}
-export function frameworkErrorFromToolConfigDiagnostics(args) {
-    const details = args.diagnostics.map((diagnostic) => `${diagnostic.path}: ${diagnostic.message}`);
-    const message = details.length > 0
-        ? "Invalid tools config."
-        : "Invalid tools config (no diagnostics details were provided).";
-    return toFrameworkErrorModel({
-        kind: "tool-config",
-        source: args.source,
-        message,
-        details,
-        recoverable: args.recoverable,
+        cohort: args.cohort,
     });
 }
 export function formatFrameworkErrorForConsole(error) {

package/dist/services/interfaces.d.ts

@@ -9,22 +9,24 @@
  */
 import type { I18nServiceApi } from "@pie-players/pie-players-shared/i18n";
 import type { AccessibilityCatalog, SectionControllerSessionState } from "@pie-players/pie-players-shared/types";
-import type { AccessibilityCatalogResolver, CatalogChangeListener, CatalogLookupContext, CatalogLookupOptions, CatalogOwnerRegistration, CatalogOwnerView, CatalogStatistics, CatalogType, ResolvedCatalog } from "./AccessibilityCatalogResolver.js";
+import type { CatalogChangeListener, CatalogLookupContext, CatalogLookupOptions, CatalogOwnerRegistration, CatalogOwnerView, CatalogStatistics, CatalogType, ResolvedCatalog } from "./AccessibilityCatalogResolver.js";
 import type { CatalogOwnerContext } from "./catalog-owner.js";
 import type { FrameworkErrorListener } from "./framework-error-bus.js";
 import type { FrameworkErrorModel } from "./framework-error.js";
-import type { Annotation, HighlightColor, HighlightType } from "./HighlightCoordinator.js";
+import type { ToolFailurePhase } from "./tool-failure.js";
+import type { Annotation, HighlightColor } from "./HighlightCoordinator.js";
 import type { SerializedRange } from "./RangeSerializer.js";
 import type { SectionControllerHandle, SectionItemEventSubscriptionArgs, SectionScopedEventSubscriptionArgs, SectionEventSubscriptionArgs, ToolkitCoordinatorHooks } from "./ToolkitCoordinator.js";
+import type { ElementIdComponents } from "./ElementToolStateStore.js";
 import type { ZIndexLayer } from "./ToolCoordinator.js";
-import type { PlaybackState, TTSConfig } from "./TTSService.js";
+import type { PlaybackState } from "./TTSService.js";
 import type { TTSHighlightTargetResolverProvider } from "./tts/highlight-target-resolver.js";
 import type { TextToSpeechToolProviderConfig, ToolPlacementConfig, ToolProviderConfig } from "./tools-config-normalizer.js";
 import type { ToolProviderApi } from "./tool-providers/ToolProviderApi.js";
 import type { ToolProviderRegistry } from "./tool-providers/ToolProviderRegistry.js";
-import type { FeaturePolicyDecision, PolicySource, PnpEnforcementMode, ResolvedEngineInputs, ToolPolicyChangeListener, ToolPolicyDecision, ToolPolicyDecisionRequest, ToolScope } from "../policy/engine.js";
-import type { AssessmentEntity, ItemSettings } from "@pie-players/pie-players-shared/types";
-import type { ITTSProvider, TTSProviderCapabilities } from "@pie-players/pie-tts";
+import type { FeaturePolicyDecision, PolicySource, PnpEnforcementMode, ResolvedEngineInputs, ToolPolicyChangeListener, ToolPolicyDecision, ToolPolicyDecisionRequest, ToolPolicyDiagnostic, ToolScope } from "../policy/engine.js";
+import type { AssessmentEntity, ItemSettings, ToolParametersFor } from "@pie-players/pie-players-shared/types";
+import type { TTSConfig } from "@pie-players/pie-tts";
 import type { ResolvedToolContext, ToolContextResolverContext, ToolRegistry } from "./ToolRegistry.js";
 import type { ToolOpenRequest, ToolRequestTarget } from "./tool-request.js";
 export type { I18nServiceApi };
@@ -34,10 +36,6 @@ export type { I18nServiceApi };
  * Manages content highlighting for TTS, annotations, and selections.
  */
 export interface HighlightCoordinatorApi {
-    /**
-     * Highlight a text range
-     */
-    highlightRange(range: Range, type: HighlightType, color: HighlightColor): void;
     /**
      * Highlight the word being read (temporary): one range per tree the word
      * spans, all painted, so a word split across inline elements highlights
@@ -68,17 +66,9 @@ export interface HighlightCoordinatorApi {
      */
     clearTTS(): void;
     /**
-     * Clear highlights of a specific type
-     */
-    clearHighlights(type: HighlightType): void;
-    /**
-     * Check if highlighting is supported in current environment
+     * Clear the TTS word highlight, keeping the sentence highlight
      */
-    isSupported(): boolean;
-    /**
-     * Update TTS highlight style dynamically
-     */
-    updateTTSHighlightStyle(color: string, opacity: number): void;
+    clearTTSWord(): void;
     /**
      * Record a learner annotation over a range.
      *
@@ -214,6 +204,13 @@ export interface SpeakOptions {
      * element target is its own root.
      */
     contentRoot?: Element | null;
+    /**
+     * Who starts the read. The run carries it until the next read starts, a
+     * seek's restart included, and {@link TtsServiceApi.getRunOwner} reports it.
+     */
+    ownerId?: string;
+    /** The rate the read starts at; it stays the service's rate afterwards. */
+    rate?: number;
 }
 /**
  * TTS service interface
@@ -222,10 +219,6 @@ export interface SpeakOptions {
  * Supports QTI 3.0 accessibility catalogs for pre-authored spoken content.
  */
 export interface TtsServiceApi {
-    /**
-     * Initialize TTS with a provider
-     */
-    initialize(provider: ITTSProvider, config?: Partial<TTSConfig>): Promise<void>;
     /**
      * Read `target` aloud: a range reads the text it selects, an element its
      * content. A node with a spoken card that the target holds whole reads its
@@ -243,7 +236,8 @@ export interface TtsServiceApi {
      */
     resume(): void;
     /**
-     * Stop playback
+     * Stop playback and release the run owner. A read that ends on its own
+     * keeps its owner.
      */
     stop(): void;
     /**
@@ -251,13 +245,6 @@ export interface TtsServiceApi {
      * service cannot speak.
      */
     dispose(): void;
-    /**
-     * Request active TTS controls to hand off/deactivate their UI state.
-     *
-     * This is an orchestration hint for TTS tool chrome and does not replace
-     * playback controls such as stop/pause/resume.
-     */
-    requestControlHandoff(): void;
     /**
      * Seek forward by sentence units
      */
@@ -266,30 +253,21 @@ export interface TtsServiceApi {
      * Seek backward by sentence units
      */
     seekBackward(units?: number): Promise<void>;
-    /**
-     * Check if currently playing
-     */
-    isPlaying(): boolean;
-    /**
-     * Check if paused
-     */
-    isPaused(): boolean;
     /**
      * Get current playback state
      */
     getState(): PlaybackState;
     /**
-     * Get currently speaking text
+     * The `ownerId` the latest read started with, or null when it named none,
+     * nothing has been read or {@link stop} released it. A new read announces
+     * itself through {@link onStateChange} with `loading`, and a stop that
+     * releases an owner announces `idle`, so a listener sees the owner change.
      */
-    getCurrentText(): string | null;
+    getRunOwner(): string | null;
     /**
      * Subscribe to state changes. Returns the function that unsubscribes.
      */
     onStateChange(callback: (state: PlaybackState) => void): () => void;
-    /**
-     * Get capabilities of current provider
-     */
-    getCapabilities(): TTSProviderCapabilities | null;
     /**
      * Update TTS settings dynamically (rate, pitch, voice)
      */
@@ -298,18 +276,10 @@ export interface TtsServiceApi {
      * Update playback speed and apply it to active planned playback.
      */
     setPlaybackRate(rate: number): Promise<void>;
-    /**
-     * Set highlight coordinator for word highlighting
-     */
-    setHighlightCoordinator(coordinator: HighlightCoordinatorApi): void;
     /**
      * Set a late-bound provider for optional host TTS highlight target remapping.
      */
-    setHighlightTargetResolverProvider?(provider: TTSHighlightTargetResolverProvider | null): () => void;
-    /**
-     * Set accessibility catalog resolver for spoken content
-     */
-    setCatalogResolver(resolver: AccessibilityCatalogResolver): void;
+    setHighlightTargetResolverProvider(provider: TTSHighlightTargetResolverProvider | null): () => void;
 }
 /**
  * Accessibility catalog resolver interface
@@ -387,18 +357,15 @@ export interface AccessibilityCatalogResolverApi {
  */
 export interface ElementToolStateStoreApi {
     /**
-     * Generate a globally unique element ID from components
+     * Generate a globally unique element ID from its parts. `attemptId` is `""`
+     * when the host names no attempt; a tool keyed by item or section leaves
+     * `elementId`, and for a section `itemId`, as `""`.
      */
-    getGlobalElementId(assessmentId: string, sectionId: string, itemId: string, elementId: string): string;
+    getGlobalElementId(parts: ElementIdComponents): string;
     /**
      * Parse a global element ID into its components
      */
-    parseGlobalElementId(globalElementId: string): {
-        assessmentId: string;
-        sectionId: string;
-        itemId: string;
-        elementId: string;
-    } | null;
+    parseGlobalElementId(globalElementId: string): ElementIdComponents | null;
     /**
      * Set state for a specific tool on an element
      */
@@ -436,7 +403,7 @@ export interface ElementToolStateStoreApi {
      */
     clearTool(toolId: string): void;
     /**
-     * Clear all elements in a specific section
+     * Clear all elements in a specific section, across its attempts
      */
     clearSection(assessmentId: string, sectionId: string): void;
     /**
@@ -480,9 +447,9 @@ export interface ToolkitCoordinatorApi {
      */
     readonly toolProviderRegistry: ToolProviderRegistry;
     /**
-     * Ensure TTS service is initialized and ready.
+     * Ensure the TTS service is initialized from the `textToSpeech` tool config.
      */
-    ensureTTSReady(config?: Record<string, unknown>): Promise<void>;
+    ensureTTSReady(): Promise<void>;
     /**
      * Ensure a tool's provider is initialized and ready. Providers register under
      * their tool's id, so a tool passes its own base tool id. A tool starts its
@@ -619,11 +586,11 @@ export interface ToolkitCoordinatorApi {
      */
     reportFrameworkError?(model: FrameworkErrorModel): void;
     /**
-     * Report that a toolbar could not load a tool's module. The tool degrades
-     * unless policy grants it, in which case the failure is fatal. Optional so
-     * structural host coordinators remain assignable; a toolbar without it logs.
+     * Report that a tool failed in `phase`, under the tool failure policy
+     * {@link ToolFailurePhase} describes. Optional so structural host
+     * coordinators remain assignable; a reporter without it logs.
      */
-    reportToolModuleFailure?(toolId: string, error: unknown): void;
+    reportToolFailure?(toolId: string, phase: ToolFailurePhase, error: unknown): void;
     /**
      * Resolve the visible tool set for a given placement level + scope.
      * Returns the engine's full decision (visible tools, diagnostics,
@@ -643,7 +610,7 @@ export interface ToolkitCoordinatorApi {
      * Optional so host-supplied coordinator stubs predating this method stay
      * assignable; call sites must feature-detect.
      */
-    decideFeaturePolicy?(featureId: string, scope?: ToolScope): FeaturePolicyDecision;
+    decideFeaturePolicy?<K extends string>(featureId: K, scope?: ToolScope): FeaturePolicyDecision<ToolParametersFor<K>>;
     /**
      * Subscribe to policy-engine change events. Fires whenever the
      * coordinator's bound policy inputs change (`updateToolConfig`,
@@ -653,6 +620,15 @@ export interface ToolkitCoordinatorApi {
      * should call `decideToolPolicy(...)` with their level / scope.
      */
     onPolicyChange(listener: ToolPolicyChangeListener): () => void;
+    /**
+     * Subscribe to the policy diagnostics the coordinator reports: the ones it
+     * logs as console warnings, once per code, tool and item. A new listener is
+     * first handed every diagnostic already reported. A change to the bound
+     * policy inputs or to PNP enforcement clears the record, and so does a tool
+     * registration that makes a named support id known or unknown, so a conflict
+     * that survives the change is reported again once.
+     */
+    onPolicyDiagnostic(listener: (diagnostic: ToolPolicyDiagnostic) => void): () => void;
     /**
      * Subscribe to accessibility-catalog registrations and removals.
      *

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

@@ -27,14 +27,14 @@ export interface SectionSessionPersistenceConfig {
     context: SectionControllerContext;
     strategy: SectionSessionPersistenceStrategy;
 }
+/**
+ * applySession contract:
+ * - Preferred input is the output of getSession().
+ * - itemSessions may contain canonical attempt entries
+ *   ({ itemIdentifier, session, isCompleted }) or raw session payloads
+ *   ({ id, data, ... }); controller normalizes these before applying.
+ */
 export interface SectionControllerApplySessionOptions {
-    /**
-     * applySession contract:
-     * - Preferred input is the output of getSession().
-     * - itemSessions may contain canonical attempt entries
-     *   ({ itemIdentifier, session, isCompleted }) or raw session payloads
-     *   ({ id, data, ... }); controller normalizes these before applying.
-     */
     mode?: "replace" | "merge";
 }
 export interface SectionControllerLoadedRenderable {

package/dist/services/section-session-assignment.js

@@ -15,16 +15,14 @@
  */
 import { hasResponseField, hasResponseValue, } from "@pie-players/pie-players-shared/pie";
 import { structurallyEqual } from "../utils/structural-equality.js";
-function isRecord(value) {
-    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
+import { isPlainRecord } from "@pie-players/pie-players-shared/object";
 /** An entry is canonical (`{ itemIdentifier, session, ... }`) or the raw item session. */
 function itemSessionOf(entry) {
-    return isRecord(entry) && isRecord(entry.session) ? entry.session : entry;
+    return isPlainRecord(entry) && isPlainRecord(entry.session) ? entry.session : entry;
 }
 function sameItemSessions(next, current) {
-    const nextSessions = isRecord(next) ? next : {};
-    const currentSessions = isRecord(current) ? current : {};
+    const nextSessions = isPlainRecord(next) ? next : {};
+    const currentSessions = isPlainRecord(current) ? current : {};
     const itemIds = new Set([
         ...Object.keys(nextSessions),
         ...Object.keys(currentSessions),
@@ -63,10 +61,10 @@ function sameSessionContent(next, current) {
 export function resolveSectionSessionAssignment(current, next) {
     if (!current)
         return next;
-    const itemSessions = isRecord(next.itemSessions)
+    const itemSessions = isPlainRecord(next.itemSessions)
         ? { ...next.itemSessions }
         : {};
-    const currentItemSessions = isRecord(current.itemSessions)
+    const currentItemSessions = isPlainRecord(current.itemSessions)
         ? current.itemSessions
         : {};
     for (const [itemId, currentEntry] of Object.entries(currentItemSessions)) {

package/dist/services/spoken-audio-cards.d.ts

@@ -3,8 +3,8 @@
  *
  * QTI 3 treats a recording and synthesized speech as the *same* support — both
  * are `spoken`, and a card carries recorded audio through `qti-file-href` plus a
- * MIME type — so this is not a new accommodation but the other form the existing
- * one can take. Some programs prefer a human voice to synthesis; PIE's `spoken`
+ * MIME type — so a recording is the other form the existing support takes.
+ * Some programs prefer a human voice to synthesis; PIE's `spoken`
  * card was string-only, so it had no way to say "play this file for this node".
  *
  * A node commonly carries both forms in the same language: the reading script
@@ -17,8 +17,6 @@
  * Validation posture matches sign-language cards: "treat as absent, never as
  * partially valid". A malformed payload must not produce a silent player that
  * looks like read-aloud is working.
- *
- * Part of PIE Assessment Toolkit.
  */
 import type { CatalogCardPayload, MediaFragmentRange, MediaSource } from "@pie-players/pie-players-shared/types";
 /** A validated recorded spoken alternate, flattened for playback. */

package/dist/services/spoken-audio-cards.js

@@ -3,8 +3,8 @@
  *
  * QTI 3 treats a recording and synthesized speech as the *same* support — both
  * are `spoken`, and a card carries recorded audio through `qti-file-href` plus a
- * MIME type — so this is not a new accommodation but the other form the existing
- * one can take. Some programs prefer a human voice to synthesis; PIE's `spoken`
+ * MIME type — so a recording is the other form the existing support takes.
+ * Some programs prefer a human voice to synthesis; PIE's `spoken`
  * card was string-only, so it had no way to say "play this file for this node".
  *
  * A node commonly carries both forms in the same language: the reading script
@@ -17,8 +17,6 @@
  * Validation posture matches sign-language cards: "treat as absent, never as
  * partially valid". A malformed payload must not produce a silent player that
  * looks like read-aloud is working.
- *
- * Part of PIE Assessment Toolkit.
  */
 import { isUnsupportedMediaAssetVersion, normalizeMediaFragment, normalizeMediaSources, trimmedOrUndefined, } from "@pie-players/pie-players-shared/media";
 /**

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

@@ -1,5 +1,4 @@
 import { type CanonicalToolsConfig, type ToolsConfigInput } from "./tools-config-normalizer.js";
-import { type FrameworkErrorModel } from "./framework-error.js";
 import type { ToolRegistry } from "./ToolRegistry.js";
 export type ToolConfigStrictness = "off" | "warn" | "error";
 export type ToolConfigDiagnosticSeverity = "warning" | "error";
@@ -19,13 +18,12 @@ export interface ToolConfigValidationResult {
     config: CanonicalToolsConfig;
     diagnostics: ToolConfigDiagnostic[];
 }
-export declare function frameworkErrorFromToolConfigValidation(args: {
-    source: string;
-    diagnostics?: ToolConfigDiagnostic[] | null;
-    error?: unknown;
-    recoverable?: boolean;
-}): FrameworkErrorModel;
 export declare function normalizeToolConfigStrictness(value: unknown): ToolConfigStrictness;
+/**
+ * Normalize a tools config, sanitize and validate each provider entry with its
+ * registration's hooks, check ids and levels against `options.toolRegistry`,
+ * and report the diagnostics by `options.strictness` (default `"error"`).
+ */
 export declare function normalizeAndValidateToolsConfig(input?: ToolsConfigInput | null, options?: ToolConfigValidationOptions): ToolConfigValidationResult;
 /**
  * The normalization and diagnostics of {@link normalizeAndValidateToolsConfig},

package/dist/services/tool-config-validation.js

@@ -1,20 +1,4 @@
 import { normalizeToolsConfig, } from "./tools-config-normalizer.js";
-import { frameworkErrorFromToolConfigDiagnostics, frameworkErrorFromUnknown, } from "./framework-error.js";
-export function frameworkErrorFromToolConfigValidation(args) {
-    if (Array.isArray(args.diagnostics) && args.diagnostics.length > 0) {
-        return frameworkErrorFromToolConfigDiagnostics({
-            source: args.source,
-            diagnostics: args.diagnostics,
-            recoverable: args.recoverable,
-        });
-    }
-    return frameworkErrorFromUnknown({
-        kind: "tool-config",
-        source: args.source,
-        error: args.error ?? new Error("Invalid tools config"),
-        recoverable: args.recoverable,
-    });
-}
 const DEFAULT_STRICTNESS = "error";
 export function normalizeToolConfigStrictness(value) {
     if (value === "off" || value === "warn" || value === "error") {
@@ -198,6 +182,11 @@ function throwValidationError(diagnostics, source) {
         .join("\n");
     throw new Error(`[tool-config-validation:${source}] Invalid tools config:\n${formatted}`);
 }
+/**
+ * Normalize a tools config, sanitize and validate each provider entry with its
+ * registration's hooks, check ids and levels against `options.toolRegistry`,
+ * and report the diagnostics by `options.strictness` (default `"error"`).
+ */
 export function normalizeAndValidateToolsConfig(input, options = {}) {
     const result = collectToolConfigDiagnostics(input, options.toolRegistry);
     reportToolConfigDiagnostics(result.diagnostics, options);
@@ -212,11 +201,9 @@ export function collectToolConfigDiagnostics(input, toolRegistry) {
     const normalized = normalizeToolsConfig(input);
     const diagnostics = [];
     // Tool-id and provider checks need a registry to check against, and every
-    // collector below returns early without one. Say so: this package no longer
-    // falls back to a packaged registry, so a caller that used to get id
-    // validation for free now gets none, and a silent downgrade of "your ids are
-    // valid" to "nobody looked" is the kind of change that surfaces as a typo
-    // reaching a learner.
+    // collector below returns early without one. Say so, since there is no
+    // packaged fallback registry: silence would read as "your ids are valid" when
+    // nobody looked, and a typo would reach a learner.
     const hasConfiguredTools = Object.values(normalized.placement).some((ids) => ids.length > 0) ||
         Object.keys(normalized.providers).length > 0 ||
         (normalized.policy.allowed?.length ?? 0) > 0 ||
@@ -260,11 +247,9 @@ export function reportToolConfigDiagnostics(diagnostics, options = {}) {
     if (strictness === "warn") {
         emitWarnings(diagnostics, source);
     }
-    // Severity decides what `strictness: "error"` rejects. Every diagnostic was
-    // `"error"` until `tools.registryUnavailable`, which reports that validation
-    // could not run rather than that the config is wrong — throwing on it would
-    // turn "no registry supplied" from a host's existing, working setup into a
-    // construction failure.
+    // Severity decides what `strictness: "error"` rejects. `tools.registryUnavailable`
+    // is a warning: it reports that validation could not run, and throwing on it
+    // would fail construction for a host whose setup works without a registry.
     const blocking = diagnostics.filter((entry) => entry.severity === "error");
     if (strictness === "error" && blocking.length > 0) {
         throwValidationError(blocking, source);

package/dist/services/tool-context.d.ts

@@ -102,30 +102,9 @@ export interface ElementToolContext extends BaseToolContext {
  */
 export type ToolContext = AssessmentToolContext | SectionToolContext | ItemToolContext | PassageToolContext | RubricToolContext | ElementToolContext;
 /**
- * Type guard to check if context is at item level
- */
-export declare function isItemContext(context: ToolContext): context is ItemToolContext;
-/**
- * Type guard to check if context is at passage level
- */
-export declare function isPassageContext(context: ToolContext): context is PassageToolContext;
-/**
- * Type guard to check if context is at rubric level
- */
-export declare function isRubricContext(context: ToolContext): context is RubricToolContext;
-/**
- * Type guard to check if context is at element level
- */
-export declare function isElementContext(context: ToolContext): context is ElementToolContext;
-/** The plain text a context carries, tags removed. */
-export declare function extractTextContent(context: ToolContext): string;
-/**
- * The authored markup a context carries, tags intact.
- *
- * For indicators that live in the markup rather than in the prose — `<math>`
- * above all, whose whole signal is the element name.
+ * Helper to check if context contains mathematical content
+ * (Basic heuristic - can be overridden by tools)
  */
-export declare function extractMarkupContent(context: ToolContext): string;
 export declare function hasMathContent(context: ToolContext): boolean;
 /**
  * Helper to check if context contains choice-based interactions
@@ -135,6 +114,11 @@ export declare function hasChoiceInteraction(context: ToolContext): boolean;
  * Helper to check if context contains text that can be read aloud
  */
 export declare function hasReadableText(context: ToolContext): boolean;
+/**
+ * Whether read-aloud has something to read: readable text, or markup carrying
+ * a catalog idref, whose spoken card reads for content with no text.
+ */
+export declare function hasSpokenContent(context: ToolContext): boolean;
 /**
  * Helper to check if context contains science content
  * (Basic heuristic - can be overridden by tools)