@pie-players/pie-assessment-toolkit 0.3.73 → 0.3.75

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;
@@ -68,4 +67,15 @@ export declare function catalogOwnerContextFor(owner: CatalogOwnerIdentity): Cat
  * register the owner once through `AccessibilityCatalogResolver.registerOwner`.
  */
 export declare function collectOwnerCatalogRegistrations(entity: CatalogSourceEntity | null | undefined, owner: CatalogOwnerIdentity): CatalogOwnerRegistrationEntry[];
+/**
+ * The catalogs an owner registration of `entity` would file, as a string equal
+ * for any two entities that register the same catalogs. A shell holding new
+ * content under an unchanged identity compares it to decide whether the runtime
+ * has anything new to register. It is derived from the registration walk, so it
+ * cannot disagree with the registration about what counts as a catalog.
+ *
+ * `null` when the catalogs do not serialize: nothing can be concluded, and the
+ * caller registers again.
+ */
+export declare function catalogSourceSignature(entity: CatalogSourceEntity | null | undefined, kind: CatalogOwnerIdentity["kind"]): string | null;
 export {};

package/dist/services/catalog-owner.js

@@ -62,3 +62,28 @@ export function collectOwnerCatalogRegistrations(entity, owner) {
     }
     return registrations;
 }
+/**
+ * The catalogs an owner registration of `entity` would file, as a string equal
+ * for any two entities that register the same catalogs. A shell holding new
+ * content under an unchanged identity compares it to decide whether the runtime
+ * has anything new to register. It is derived from the registration walk, so it
+ * cannot disagree with the registration about what counts as a catalog.
+ *
+ * `null` when the catalogs do not serialize: nothing can be concluded, and the
+ * caller registers again.
+ */
+export function catalogSourceSignature(entity, kind) {
+    const registrations = collectOwnerCatalogRegistrations(entity, {
+        kind,
+        itemId: "",
+    });
+    try {
+        return JSON.stringify(registrations.map((registration) => [
+            registration.context.modelId ?? null,
+            registration.catalogs,
+        ]));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/services/create-tools-config.d.ts

@@ -1,8 +1,8 @@
-import type { CanonicalToolsConfig } from "./tools-config-normalizer.js";
+import type { ToolsConfigInput } from "./tools-config-normalizer.js";
 import type { ToolRegistry } from "./ToolRegistry.js";
 import { type ToolConfigStrictness, type ToolConfigValidationResult } from "./tool-config-validation.js";
 export interface CreateToolsConfigArgs {
-    tools?: Partial<CanonicalToolsConfig> | null;
+    tools?: ToolsConfigInput | null;
     toolRegistry?: ToolRegistry | null;
     strictness?: ToolConfigStrictness;
     source?: 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,10 @@
 import type { ToolConfigDiagnostic } from "./tool-config-validation.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 timed-media section could not deliver a policy as authored: a media time
  * source missing `canPause` / `canRestrictSeeking` (recoverable — cues still
@@ -13,8 +18,22 @@ export type FrameworkErrorKind = "tool-config" | "runtime-init" | "runtime-dispo
  * key still resolves through the English fallback chain, so the player renders
  * — in the wrong language, which a host wants to know about.
  */
- | "i18n-locale-load" | "unknown";
+ | "i18n-locale-load"
+/**
+ * A section player could not register the elements its items need before
+ * mounting them: a renderable failed the config contract, an element bundle
+ * or module failed to load, or a `preloaded` page lacks a registration the
+ * content names. Not recoverable — the section's items stay unmounted.
+ */
+ | "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";
 export interface FrameworkErrorModel {
     kind: FrameworkErrorKind;
     severity: FrameworkErrorSeverity;
@@ -22,6 +41,7 @@ export interface FrameworkErrorModel {
     message: string;
     details: string[];
     recoverable: boolean;
+    scope: FrameworkErrorScope;
     cause?: unknown;
 }
 export declare function toFrameworkErrorModel(args: {
@@ -31,6 +51,8 @@ export declare function toFrameworkErrorModel(args: {
     message: string;
     details?: string[];
     recoverable?: boolean;
+    /** Defaults to `runtime`. */
+    scope?: FrameworkErrorScope;
     cause?: unknown;
 }): FrameworkErrorModel;
 export declare function frameworkErrorFromUnknown(args: {
@@ -38,6 +60,7 @@ export declare function frameworkErrorFromUnknown(args: {
     source: string;
     error: unknown;
     recoverable?: boolean;
+    scope?: FrameworkErrorScope;
 }): FrameworkErrorModel;
 /**
  * Coordinator-side error context shape consumed by
@@ -50,8 +73,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" | "tool-module-load";
+    toolId?: string;
     details?: Record<string, unknown>;
 }
 /**
@@ -59,20 +82,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;
+    scope?: FrameworkErrorScope;
 }): FrameworkErrorModel;
 export declare function frameworkErrorFromToolConfigDiagnostics(args: {
     source: string;

package/dist/services/framework-error.js

@@ -6,6 +6,7 @@ export function toFrameworkErrorModel(args) {
         message: args.message,
         details: [...(args.details || [])],
         recoverable: args.recoverable === true,
+        scope: args.scope ?? "runtime",
         cause: args.cause,
     };
 }
@@ -18,6 +19,7 @@ export function frameworkErrorFromUnknown(args) {
         source: args.source,
         message,
         recoverable: args.recoverable,
+        scope: args.scope,
         cause: args.error,
     });
 }
@@ -30,32 +32,32 @@ 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",
 };
 /**
  * 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,
+        scope: args.scope,
     });
 }
 export function frameworkErrorFromToolConfigDiagnostics(args) {