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

package/dist/services/audio-handoff.d.ts

@@ -13,27 +13,26 @@
  */
 import type { TtsServiceApi } from "./interfaces.js";
 /** Only what a handoff needs, so a host passing a partial service still works. */
-type TtsHandoffSubscriber = Pick<TtsServiceApi, "onStateChange" | "offStateChange">;
-type TtsHandoffPlayback = Pick<TtsServiceApi, "isPlaying" | "pause">;
+type TtsHandoffSubscriber = Pick<TtsServiceApi, "onStateChange">;
+type TtsHandoffPlayback = Pick<TtsServiceApi, "getState" | "pause">;
 /**
  * Silence a media surface whenever read-aloud starts speaking.
  *
- * `LOADING` as well as `PLAYING`, so the pause lands before the first word rather
- * than a provider round-trip after it. A `LOADING` that then fails leaves media
- * paused, which costs the learner one press of play.
+ * Silenced on loading, so the pause lands before the first word rather than a
+ * provider round-trip after it. A load that then fails leaves media paused,
+ * which costs the learner one press of play.
  *
  * Returns the teardown, including where there was nothing to bind.
  */
 export declare function bindTtsAudioHandoff(args: {
     ttsService: Partial<TtsHandoffSubscriber> | null | undefined;
-    /** Unique per surface: the service keys its listener sets by this. */
-    listenerId: string;
     silence: () => void;
 }): () => void;
 /**
  * The other half: media audio has started, so read-aloud yields.
  *
  * Paused rather than stopped, so the learner keeps their place in the passage.
+ * A read still loading pauses too, and holds until the learner resumes it.
  */
 export declare function pauseTtsForMediaAudio(ttsService: Partial<TtsHandoffPlayback> | null | undefined): void;
 export {};

package/dist/services/audio-handoff.js

@@ -13,29 +13,34 @@
  */
 import { PlaybackState } from "./TTSService.js";
 const NOOP = () => { };
+/**
+ * Read-aloud counts as speaking from the moment a read starts loading. A
+ * loading read sounds as soon as its audio arrives, so both halves treat it as
+ * a playing one.
+ */
+function isSpeaking(state) {
+    return state === PlaybackState.PLAYING || state === PlaybackState.LOADING;
+}
 /**
  * Silence a media surface whenever read-aloud starts speaking.
  *
- * `LOADING` as well as `PLAYING`, so the pause lands before the first word rather
- * than a provider round-trip after it. A `LOADING` that then fails leaves media
- * paused, which costs the learner one press of play.
+ * Silenced on loading, so the pause lands before the first word rather than a
+ * provider round-trip after it. A load that then fails leaves media paused,
+ * which costs the learner one press of play.
  *
  * Returns the teardown, including where there was nothing to bind.
  */
 export function bindTtsAudioHandoff(args) {
-    const { ttsService, listenerId, silence } = args;
+    const { ttsService, silence } = args;
     if (typeof ttsService?.onStateChange !== "function")
         return NOOP;
-    const onTtsState = (state) => {
-        if (state !== PlaybackState.PLAYING && state !== PlaybackState.LOADING) {
-            return;
-        }
-        silence();
-    };
-    ttsService.onStateChange(listenerId, onTtsState);
+    const unsubscribe = ttsService.onStateChange((state) => {
+        if (isSpeaking(state))
+            silence();
+    });
     return () => {
         try {
-            ttsService.offStateChange?.(listenerId, onTtsState);
+            unsubscribe();
         }
         catch {
             // A torn-down service is not a failure to detach from.
@@ -46,11 +51,12 @@ export function bindTtsAudioHandoff(args) {
  * The other half: media audio has started, so read-aloud yields.
  *
  * Paused rather than stopped, so the learner keeps their place in the passage.
+ * A read still loading pauses too, and holds until the learner resumes it.
  */
 export function pauseTtsForMediaAudio(ttsService) {
     try {
-        if (ttsService?.isPlaying?.())
-            ttsService.pause?.();
+        if (isSpeaking(ttsService?.getState?.()))
+            ttsService?.pause?.();
     }
     catch {
         // A torn-down or uninitialized TTS service must not break playback.

package/dist/services/catalog-owner.d.ts

@@ -6,7 +6,6 @@
  * adapter, while keeping the entity walk private to the resolver package.
  */
 import type { AccessibilityCatalog } from "@pie-players/pie-players-shared/types";
-export type CatalogOwnerKind = "global" | "passage" | "itemModel";
 interface CatalogOwnerScopeContext {
     assessmentId?: string;
     sectionId?: string;

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

@@ -48,12 +48,9 @@ export interface FrameworkErrorReporter {
  *   before constructing the coordinator so the `coordinator-init`
  *   failure path emits through the same bus.
  *
- * **Why not a public class.** This bus is constructed inside the toolkit
- * CE (`PieAssessmentToolkit.svelte`) and passed into
- * `ToolkitCoordinator`. Hosts subscribe via
- * `ToolkitCoordinatorApi.subscribeFrameworkErrors`, never via the bus
- * class itself. Keeping the class package-internal lets us iterate on
- * its shape without a public-API change.
+ * **Where it is constructed.** The toolkit CE (`PieAssessmentToolkit.svelte`)
+ * builds one and passes it into `ToolkitCoordinator`; hosts subscribe via
+ * `ToolkitCoordinatorApi.subscribeFrameworkErrors`.
  */
 export declare class FrameworkErrorBus implements FrameworkErrorPort, FrameworkErrorReporter {
     private readonly listeners;

package/dist/services/framework-error-bus.js

@@ -20,12 +20,9 @@
  *   before constructing the coordinator so the `coordinator-init`
  *   failure path emits through the same bus.
  *
- * **Why not a public class.** This bus is constructed inside the toolkit
- * CE (`PieAssessmentToolkit.svelte`) and passed into
- * `ToolkitCoordinator`. Hosts subscribe via
- * `ToolkitCoordinatorApi.subscribeFrameworkErrors`, never via the bus
- * class itself. Keeping the class package-internal lets us iterate on
- * its shape without a public-API change.
+ * **Where it is constructed.** The toolkit CE (`PieAssessmentToolkit.svelte`)
+ * builds one and passes it into `ToolkitCoordinator`; hosts subscribe via
+ * `ToolkitCoordinatorApi.subscribeFrameworkErrors`.
  */
 export class FrameworkErrorBus {
     listeners = new Set();

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

@@ -1,5 +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
@@ -22,6 +42,21 @@ export type FrameworkErrorKind = "tool-config" | "runtime-init" | "runtime-dispo
  */
  | "element-preload" | "unknown";
 export type FrameworkErrorSeverity = "warning" | "error";
+/**
+ * What a non-recoverable error takes down. `cohort`: the section it was reported
+ * for, so the section player's readiness recovers when the learner moves to
+ * another section. `runtime`: the coordinator or one of its tools, which every
+ * 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;
@@ -29,6 +64,9 @@ export interface FrameworkErrorModel {
     message: string;
     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: {
@@ -38,6 +76,9 @@ export declare function toFrameworkErrorModel(args: {
     message: string;
     details?: string[];
     recoverable?: boolean;
+    /** Defaults to `runtime`. */
+    scope?: FrameworkErrorScope;
+    cohort?: FrameworkErrorCohort;
     cause?: unknown;
 }): FrameworkErrorModel;
 export declare function frameworkErrorFromUnknown(args: {
@@ -45,6 +86,8 @@ export declare function frameworkErrorFromUnknown(args: {
     source: string;
     error: unknown;
     recoverable?: boolean;
+    scope?: FrameworkErrorScope;
+    cohort?: FrameworkErrorCohort;
 }): FrameworkErrorModel;
 /**
  * Coordinator-side error context shape consumed by
@@ -57,8 +100,8 @@ 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";
-    providerId?: string;
+    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>;
 }
 /**
@@ -66,24 +109,19 @@ export interface FrameworkErrorCoordinatorContext {
  * context pair.
  *
  * Maps `context.phase` to the canonical {@link FrameworkErrorKind} and
- * synthesizes a `source` from `context.providerId` when present
- * (`pie-toolkit-coordinator/<providerId>`); falls back to a phase-tagged
+ * synthesizes a `source` from `context.toolId` when present
+ * (`pie-toolkit-coordinator/<toolId>`); falls back to a phase-tagged
  * source (`pie-toolkit-coordinator:<phase>`) otherwise. Forwards the
  * original `error` as `cause` so hosts that care about the underlying
  * `Error` keep getting it.
  *
- * Recoverable defaults to `false` (most coordinator-phase failures are
- * not auto-recovered today). Override with `recoverable: true` for the
- * phases where the coordinator continues operating after the failure.
+ * `recoverable` defaults to `false` and `scope` to `runtime`.
  */
 export declare function frameworkErrorFromCoordinatorContext(args: {
     error: unknown;
     context: FrameworkErrorCoordinatorContext;
     recoverable?: boolean;
-}): FrameworkErrorModel;
-export declare function frameworkErrorFromToolConfigDiagnostics(args: {
-    source: string;
-    diagnostics: ToolConfigDiagnostic[];
-    recoverable?: boolean;
+    scope?: FrameworkErrorScope;
+    cohort?: FrameworkErrorCohort;
 }): FrameworkErrorModel;
 export declare function formatFrameworkErrorForConsole(error: FrameworkErrorModel): string;

package/dist/services/framework-error.js

@@ -6,6 +6,8 @@ export function toFrameworkErrorModel(args) {
         message: args.message,
         details: [...(args.details || [])],
         recoverable: args.recoverable === true,
+        scope: args.scope ?? "runtime",
+        ...(args.cohort ? { cohort: { ...args.cohort } } : {}),
         cause: args.cause,
     };
 }
@@ -18,6 +20,8 @@ export function frameworkErrorFromUnknown(args) {
         source: args.source,
         message,
         recoverable: args.recoverable,
+        scope: args.scope,
+        cohort: args.cohort,
         cause: args.error,
     });
 }
@@ -30,45 +34,40 @@ const COORDINATOR_PHASE_TO_KIND = {
     "tts-init": "tts-init",
     "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 +
  * context pair.
  *
  * Maps `context.phase` to the canonical {@link FrameworkErrorKind} and
- * synthesizes a `source` from `context.providerId` when present
- * (`pie-toolkit-coordinator/<providerId>`); falls back to a phase-tagged
+ * synthesizes a `source` from `context.toolId` when present
+ * (`pie-toolkit-coordinator/<toolId>`); falls back to a phase-tagged
  * source (`pie-toolkit-coordinator:<phase>`) otherwise. Forwards the
  * original `error` as `cause` so hosts that care about the underlying
  * `Error` keep getting it.
  *
- * Recoverable defaults to `false` (most coordinator-phase failures are
- * not auto-recovered today). Override with `recoverable: true` for the
- * phases where the coordinator continues operating after the failure.
+ * `recoverable` defaults to `false` and `scope` to `runtime`.
  */
 export function frameworkErrorFromCoordinatorContext(args) {
     const kind = COORDINATOR_PHASE_TO_KIND[args.context.phase];
-    const source = args.context.providerId
-        ? `pie-toolkit-coordinator/${args.context.providerId}`
+    const source = args.context.toolId
+        ? `pie-toolkit-coordinator/${args.context.toolId}`
         : `pie-toolkit-coordinator:${args.context.phase}`;
     return frameworkErrorFromUnknown({
         kind,
         source,
         error: args.error,
         recoverable: args.recoverable,
-    });
-}
-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,
+        scope: args.scope,
+        cohort: args.cohort,
     });
 }
 export function formatFrameworkErrorForConsole(error) {