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

package/dist/runtime/shell-event-bridge.js

@@ -1,5 +1,5 @@
 import { commitPendingSessions, createPieLogger, normalizeItemSessionChange, } from "@pie-players/pie-players-shared";
-import { PIE_INTERNAL_CONTENT_LOADED_EVENT, PIE_INTERNAL_ITEM_PLAYER_ERROR_EVENT, PIE_INTERNAL_ITEM_SESSION_CHANGED_EVENT, PIE_ITEM_SESSION_CHANGED_EVENT, } from "./registration-events.js";
+import { PIE_INTERNAL_CONTENT_IDENTITY_EVENT, PIE_INTERNAL_CONTENT_LOADED_EVENT, PIE_INTERNAL_ITEM_PLAYER_ERROR_EVENT, PIE_INTERNAL_ITEM_SESSION_CHANGED_EVENT, PIE_ITEM_PLAYER_EVENT, PIE_ITEM_SESSION_CHANGED_EVENT, RELAYED_ITEM_PLAYER_EVENTS, } from "./registration-events.js";
 import { dispatchCrossBoundaryEvent } from "./tool-host-contract.js";
 /**
  * Elements repeat themselves, a `complete` echo most often, so a session event
@@ -21,6 +21,9 @@ function sessionEventFingerprint(detail) {
         return String(semanticDetail);
     }
 }
+const isCorrectResponseSession = (detail) => Boolean(detail &&
+    typeof detail === "object" &&
+    detail.sessionSource === "correct-response");
 const isCommit = (detail) => Boolean(detail &&
     typeof detail === "object" &&
     detail.sessionCommitReason);
@@ -70,6 +73,8 @@ export function createShellEventBridge(options) {
         if (kind !== "item")
             return;
         const detail = event.detail;
+        if (isCorrectResponseSession(detail))
+            return;
         const fingerprint = sessionEventFingerprint(detail);
         // A commit is the response's last chance to reach the section.
         if (!isCommit(detail) && fingerprint === lastForwardedFingerprint)
@@ -91,6 +96,22 @@ export function createShellEventBridge(options) {
         };
         send(PIE_INTERNAL_CONTENT_LOADED_EVENT, detail);
     };
+    const onBackendLoadComplete = (event) => {
+        if (mode() !== "section" || kind !== "item")
+            return;
+        const loaded = event.detail;
+        if (loaded?.scope !== "delivery")
+            return;
+        const { itemId, canonicalItemId } = identity();
+        if (!itemId)
+            return;
+        const detail = {
+            itemId,
+            canonicalItemId: canonicalItemId || itemId,
+            ...(loaded.identity ? { identity: loaded.identity } : {}),
+        };
+        send(PIE_INTERNAL_CONTENT_IDENTITY_EVENT, detail);
+    };
     const onPlayerError = (event) => {
         if (mode() === "section")
             event.stopPropagation();
@@ -105,9 +126,27 @@ export function createShellEventBridge(options) {
         };
         send(PIE_INTERNAL_ITEM_PLAYER_ERROR_EVENT, detail);
     };
+    const relayItemPlayerEvent = (event) => {
+        if (mode() !== "section" || kind !== "item")
+            return;
+        const { itemId, canonicalItemId } = identity();
+        if (!itemId)
+            return;
+        const payload = {
+            itemId,
+            canonicalItemId: canonicalItemId || itemId,
+            type: event.type,
+            detail: event.detail,
+        };
+        dispatchCrossBoundaryEvent(host, PIE_ITEM_PLAYER_EVENT, payload);
+    };
     host.addEventListener("session-changed", onSessionChanged);
     host.addEventListener("load-complete", onLoadComplete);
+    host.addEventListener("backend-load-complete", onBackendLoadComplete);
     host.addEventListener("player-error", onPlayerError);
+    for (const type of RELAYED_ITEM_PLAYER_EVENTS) {
+        host.addEventListener(type, relayItemPlayerEvent);
+    }
     return {
         disconnect: () => {
             // An escape from the commit must not strand the listeners it needed, so
@@ -120,7 +159,11 @@ export function createShellEventBridge(options) {
             finally {
                 host.removeEventListener("session-changed", onSessionChanged);
                 host.removeEventListener("load-complete", onLoadComplete);
+                host.removeEventListener("backend-load-complete", onBackendLoadComplete);
                 host.removeEventListener("player-error", onPlayerError);
+                for (const type of RELAYED_ITEM_PLAYER_EVENTS) {
+                    host.removeEventListener(type, relayItemPlayerEvent);
+                }
             }
         },
     };

package/dist/runtime/shell-scope.d.ts

@@ -62,7 +62,7 @@ export interface ShellScope {
  * replays the request instead, once the toolkit's provider connects. A
  * different runtime answering later, a nearer toolkit taking over, moves the
  * registration: the old runtime is told to unregister by its id, and the new
- * one gets the registration and the content's last load, which only the old
- * one heard.
+ * one gets the registration and the content's last load and served identity,
+ * which only the old one heard.
  */
 export declare function createShellScope(): ShellScope;

package/dist/runtime/shell-scope.js

@@ -1,7 +1,7 @@
 import { ContextProvider, } from "@pie-players/pie-context";
 import { assessmentToolkitRegionScopeContext, assessmentToolkitShellContext, } from "../context/assessment-toolkit-context.js";
 import { catalogSourceSignature, } from "../services/catalog-owner.js";
-import { PIE_INTERNAL_CONTENT_LOADED_EVENT } from "./registration-events.js";
+import { PIE_INTERNAL_CONTENT_IDENTITY_EVENT, PIE_INTERNAL_CONTENT_LOADED_EVENT, } from "./registration-events.js";
 import { createShellRegistrationDispatcher, shellEventTarget, } from "./shell-registration.js";
 import { connectHostRuntimeContext, dispatchCrossBoundaryEvent, } from "./tool-host-contract.js";
 /**
@@ -65,8 +65,8 @@ const setAttributeIfChanged = (host, name, value) => {
  * replays the request instead, once the toolkit's provider connects. A
  * different runtime answering later, a nearer toolkit taking over, moves the
  * registration: the old runtime is told to unregister by its id, and the new
- * one gets the registration and the content's last load, which only the old
- * one heard.
+ * one gets the registration and the content's last load and served identity,
+ * which only the old one heard.
  */
 export function createShellScope() {
     const registration = createShellRegistrationDispatcher();
@@ -79,6 +79,7 @@ export function createShellScope() {
     let identity = null;
     let held = [];
     let loaded = null;
+    let served = null;
     const syncRegistration = () => {
         if (runtime !== null)
             registration.sync(identity, runtime);
@@ -90,6 +91,8 @@ export function createShellScope() {
     function send(type, detail) {
         if (type === PIE_INTERNAL_CONTENT_LOADED_EVENT)
             loaded = detail;
+        if (type === PIE_INTERNAL_CONTENT_IDENTITY_EVENT)
+            served = detail;
         if (host && runtime !== null && !runtimeDeparted(host, runtime)) {
             dispatchCrossBoundaryEvent(shellEventTarget(host, runtime), type, {
                 ...detail,
@@ -113,8 +116,13 @@ export function createShellScope() {
         held = [];
         for (const event of pending)
             send(event.type, event.detail);
-        const replayed = pending.some((event) => event.type === PIE_INTERNAL_CONTENT_LOADED_EVENT);
-        if (moved && loaded && !replayed) {
+        if (!moved)
+            return;
+        const replayed = (type) => pending.some((event) => event.type === type);
+        if (served && !replayed(PIE_INTERNAL_CONTENT_IDENTITY_EVENT)) {
+            send(PIE_INTERNAL_CONTENT_IDENTITY_EVENT, served);
+        }
+        if (loaded && !replayed(PIE_INTERNAL_CONTENT_LOADED_EVENT)) {
             send(PIE_INTERNAL_CONTENT_LOADED_EVENT, loaded);
         }
     }
@@ -126,6 +134,7 @@ export function createShellScope() {
         runtime = null;
         held = [];
         loaded = null;
+        served = null;
         identity = null;
         shell = null;
         region = null;

package/dist/services/SSMLExtractor.js

@@ -14,6 +14,7 @@
  * This enables proper pronunciation, emphasis, and pacing for TTS without
  * requiring authors to maintain separate catalog files.
  */
+import { isCloudMetadataHostname, isPrivateHostname, } from "@pie-players/pie-players-shared/security/private-hosts";
 /**
  * Allow-listed SSML elements (from the SSML 1.1 spec subset we forward to
  * TTS providers). Anything outside this list is unwrapped during
@@ -108,27 +109,11 @@ function expandSelfClosingVoidTags(input) {
     return next;
 }
 /**
- * Hosts that must never appear inside an SSML `<audio src>` because they
- * would cause the server-side TTS provider to fetch a private / metadata
- * endpoint on behalf of the request. Mirrors the SchoolCity provider's
- * defense-in-depth check; the SSML-side block is cheap and belt-and-braces.
+ * Whether an SSML `<audio src>` may stay. The server-side TTS provider fetches
+ * it on the request's behalf, so it must be http(s) and must not reach a cloud
+ * metadata or private host. The provider checks its own asset URLs against the
+ * same lists; this SSML-side block is cheap and belt-and-braces.
  */
-const SSML_PRIVATE_AUDIO_HOSTS = [
-    /^localhost$/i,
-    /^127(?:\.\d{1,3}){3}$/,
-    /^0(?:\.\d{1,3}){3}$/,
-    /^10(?:\.\d{1,3}){3}$/,
-    /^192\.168(?:\.\d{1,3}){2}$/,
-    /^172\.(?:1[6-9]|2\d|3[01])(?:\.\d{1,3}){2}$/,
-    /^169\.254(?:\.\d{1,3}){2}$/,
-    /^::1$/,
-    /^fe80:/i,
-    /^fc00:/i,
-    /^fd[0-9a-f]{2}:/i,
-    /^metadata\.google\.internal$/i,
-    /^metadata\.azure\.internal$/i,
-    /^metadata\.packet\.net$/i,
-];
 function isSafeSsmlAudioSrc(raw) {
     if (typeof raw !== "string" || raw.length === 0)
         return false;
@@ -142,8 +127,8 @@ function isSafeSsmlAudioSrc(raw) {
     if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
         return false;
     }
-    const hostname = parsed.hostname.replace(/^\[|\]$/g, "").replace(/\.$/, "");
-    return !SSML_PRIVATE_AUDIO_HOSTS.some((pattern) => pattern.test(hostname));
+    return (!isCloudMetadataHostname(parsed.hostname) &&
+        !isPrivateHostname(parsed.hostname));
 }
 /**
  * Sanitize an SSML subtree in place: remove disallowed attributes and
@@ -173,7 +158,7 @@ function sanitizeSsmlElement(element) {
         }
     }
     // `src` survives the attribute allow-list, and a server-side provider
-    // fetches it: keep it only for an http(s) URL off SSML_PRIVATE_AUDIO_HOSTS.
+    // fetches it: keep it only when isSafeSsmlAudioSrc allows it.
     if (element.tagName.toLowerCase() === "audio") {
         const src = element.getAttribute("src");
         if (src !== null && !isSafeSsmlAudioSrc(src)) {

package/dist/services/ToolRegistry.d.ts

@@ -545,8 +545,12 @@ export interface ToolRegistration {
      * Declare this only where the tool's own controls provably do nothing:
      * withdrawing a granted accommodation on a false negative is the more
      * expensive failure. Omitting it means "applicable".
+     *
+     * `config` is this tool's `tools.providers.<toolId>` entry, when the surface
+     * asking has one: host configuration can narrow what a tool acts on, and a
+     * tool that acts on nothing here is not applicable.
      */
-    isApplicableToContent?(context: ToolContext): boolean;
+    isApplicableToContent?(context: ToolContext, config?: ToolProviderConfig): boolean;
     /**
      * Toolbar render contract. Required for `toolbar-toggle` and
      * `selection-gateway`; a region capability renders through
@@ -666,8 +670,10 @@ export declare class ToolRegistry {
      * @param contexts - Every context the tool could act on at this placement
      * @param onFailure - Receives the gate's throw; the tool then counts as
      *   applicable. Logs when omitted.
+     * @param config - The tool's `tools.providers.<toolId>` entry, passed to the
+     *   gate
      */
-    isApplicableToAnyContext(toolId: string, contexts: readonly ToolContext[], onFailure?: ToolCallbackFailureHandler): boolean;
+    isApplicableToAnyContext(toolId: string, contexts: readonly ToolContext[], onFailure?: ToolCallbackFailureHandler, config?: ToolProviderConfig): boolean;
     /**
      * Passes 2 and 3 over a policy decision's tools: the ids a surface at `level`
      * shows against `contexts`, in decision order. This is the rule a toolbar
@@ -687,8 +693,10 @@ export declare class ToolRegistry {
      * @param contexts - Every context the tools could act on at that surface
      * @param onFailure - Receives a relevance or applicability check's throw.
      *   Logs when omitted.
+     * @param getToolConfig - A tool's `tools.providers.<toolId>` entry, which
+     *   applicability receives; a toolkit coordinator's `getToolConfig`
      */
-    filterDecidedToolIds(entries: readonly Pick<ToolPolicyEntry, "toolId" | "required" | "alwaysAvailable">[], level: ToolLevel, contexts: readonly ToolContext[], onFailure?: ToolCallbackFailureHandler): string[];
+    filterDecidedToolIds(entries: readonly Pick<ToolPolicyEntry, "toolId" | "required" | "alwaysAvailable">[], level: ToolLevel, contexts: readonly ToolContext[], onFailure?: ToolCallbackFailureHandler, getToolConfig?: (toolId: string) => ToolProviderConfig | null): string[];
     /**
      * Plain metadata for every registration, in registration order, for UIs
      * such as a PNP configuration screen.

package/dist/services/ToolRegistry.js

@@ -382,8 +382,10 @@ export class ToolRegistry {
      * @param contexts - Every context the tool could act on at this placement
      * @param onFailure - Receives the gate's throw; the tool then counts as
      *   applicable. Logs when omitted.
+     * @param config - The tool's `tools.providers.<toolId>` entry, passed to the
+     *   gate
      */
-    isApplicableToAnyContext(toolId, contexts, onFailure = logToolCallbackFailure) {
+    isApplicableToAnyContext(toolId, contexts, onFailure = logToolCallbackFailure, config) {
         const tool = this.get(toolId);
         if (!tool?.isApplicableToContent)
             return true;
@@ -391,7 +393,7 @@ export class ToolRegistry {
             return true;
         return contexts.some((context) => {
             try {
-                return tool.isApplicableToContent?.(context) ?? true;
+                return tool.isApplicableToContent?.(context, config) ?? true;
             }
             catch (error) {
                 onFailure(toolId, "tool-applicability", error);
@@ -419,8 +421,10 @@ export class ToolRegistry {
      * @param contexts - Every context the tools could act on at that surface
      * @param onFailure - Receives a relevance or applicability check's throw.
      *   Logs when omitted.
+     * @param getToolConfig - A tool's `tools.providers.<toolId>` entry, which
+     *   applicability receives; a toolkit coordinator's `getToolConfig`
      */
-    filterDecidedToolIds(entries, level, contexts, onFailure = logToolCallbackFailure) {
+    filterDecidedToolIds(entries, level, contexts, onFailure = logToolCallbackFailure, getToolConfig) {
         const granted = new Set();
         const decided = [];
         for (const entry of entries) {
@@ -447,7 +451,7 @@ export class ToolRegistry {
             }
         }
         return decided.filter((toolId) => relevant.has(toolId) &&
-            this.isApplicableToAnyContext(toolId, contexts, onFailure));
+            this.isApplicableToAnyContext(toolId, contexts, onFailure, getToolConfig?.(toolId) ?? undefined));
     }
     /**
      * Plain metadata for every registration, in registration order, for UIs

package/dist/services/ToolkitCoordinator.d.ts

@@ -35,13 +35,14 @@ import type { ToolCoordinatorApi } from "./interfaces.js";
 import { TTSService } from "./TTSService.js";
 import { ToolProviderRegistry } from "./tool-providers/index.js";
 import type { ToolProviderApi } from "./tool-providers/ToolProviderApi.js";
+import { TTS_TOOL_ID } from "./tts/tts-lifecycle.js";
 import { ToolRegistry } from "./ToolRegistry.js";
 import type { ResolvedToolContext, ToolContextResolverContext, ToolContextResolverMap } from "./ToolRegistry.js";
 import type { ToolFailurePhase } from "./tool-failure.js";
 import type { ToolOpenRequest, ToolRequestTarget } from "./tool-request.js";
 import { type FeaturePolicyDecision, type PnpEnforcementMode, type PolicySource, type ResolvedEngineInputs, type ToolPolicyChangeListener, type ToolPolicyDecision, type ToolPolicyDecisionRequest, type ToolPolicyDiagnostic, type ToolScope } from "../policy/engine.js";
 import type { SectionControllerContext, SectionControllerEvent, SectionControllerEventType, SectionControllerFactoryDefaults, SectionControllerHandle, SectionControllerKey, SectionControllerSessionState, SectionSessionPersistenceStrategy, SectionPersistenceFactoryDefaults } from "./section-controller-types.js";
-export type { SectionControllerContext, SectionControllerEvent, SectionControllerEventType, SectionControllerFactoryDefaults, SectionControllerHandle, SectionControllerKey, SectionControllerLoadedRenderable, SectionSessionPersistenceConfig, SectionSessionPersistenceStrategy, SectionControllerRuntimeState, SectionControllerSessionState, SectionPersistenceFactoryDefaults, } from "./section-controller-types.js";
+export type { SectionControllerContext, SectionControllerEvent, SectionControllerEventType, SectionControllerFactoryDefaults, SectionControllerHandle, SectionControllerKey, SectionItemScore, SectionItemScorer, SectionScore, SectionControllerLoadedRenderable, SectionSessionPersistenceConfig, SectionSessionPersistenceStrategy, SectionControllerRuntimeState, SectionControllerSessionState, SectionPersistenceFactoryDefaults, } from "./section-controller-types.js";
 export type { FeaturePolicyDecision, PnpEnforcementMode, ResolvedEngineInputs, ToolPolicyChangeListener, ToolPolicyDecision, ToolPolicyDecisionRequest, } from "../policy/engine.js";
 export interface ToolkitToolsConfig extends CanonicalToolsConfig {
     policy: ToolPolicyConfig;
@@ -291,11 +292,7 @@ export declare class ToolkitCoordinator {
     readonly hooks: ToolkitCoordinatorHooks;
     readonly lazyInit: boolean;
     /** Track TTS initialization state */
-    private ttsInitialized;
-    /** Text-to-speech failed to start and policy does not grant it. */
-    private ttsDegraded;
-    private ttsInitPromise?;
-    private ttsReconfigurePromise?;
+    private tts;
     /**
      * The loader ran, whether or not it returned state. A failed load is
      * reported once and the coordinator runs without saved tool state.
@@ -398,18 +395,6 @@ export declare class ToolkitCoordinator {
      * lifetime for no new information.
      */
     private reportedUnboundFeaturePolicy;
-    /**
-     * 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.
-     */
-    private reportedMissingTTSProvider;
-    /**
-     * The backend of a fallback {@link reportMissingTTSProvider} held back while
-     * the registry was unsettled, reported if the bound toolkit has no registry.
-     */
-    private heldMissingTTSProviderBackend;
     /**
      * Whether {@link validateToolsConfig} has already reported validating with
      * no registry (`tools.registryUnavailable`). Once per coordinator: every
@@ -528,7 +513,6 @@ export declare class ToolkitCoordinator {
     private ensureStateLoaded;
     /** Whether the toolkit this coordinator binds to may still supply a registry. */
     private toolRegistryPending;
-    private reportMissingTTSProvider;
     /**
      * Take the registry of the toolkit this coordinator is bound to, when the host
      * constructed it without one: the config is validated against it, its
@@ -694,27 +678,13 @@ export declare class ToolkitCoordinator {
     private disposeOwnedResources;
     private waitForAdmittedInitialization;
     /**
-     * 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.
      */
     ensureTTSReady(): Promise<void>;
-    private waitForPendingTTSReconfigure;
-    private _initializeTTS;
-    private resolveTTSToolConfig;
-    private initializeTTSService;
     waitUntilReady(): Promise<void>;
     isReady(): boolean;
-    /**
-     * 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.
-     */
-    private ttsRequiredForReadiness;
-    /**
-     * 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.
-     */
-    private startTTSForReadiness;
-    private getTTSConfigFromProviders;
     private assertCanonicalToolId;
     private installToolContextResolvers;
     /**
@@ -725,14 +695,17 @@ export declare class ToolkitCoordinator {
     setToolContextResolvers(resolvers: ToolContextResolverMap | null | undefined): void;
     private notifyToolContextResolverChange;
     /**
-     * Get tool configuration, or null if the tool is not configured.
+     * Get tool configuration, or null if the tool is not configured. The
+     * read-aloud overload takes its literal from `TTS_TOOL_ID` (the same type the
+     * runtime compares against), so the capability id is named once, where the
+     * capability lives.
      */
-    getToolConfig(toolId: "textToSpeech"): TextToSpeechToolProviderConfig | null;
+    getToolConfig(toolId: typeof TTS_TOOL_ID): TextToSpeechToolProviderConfig | null;
     getToolConfig(toolId: string): ToolProviderConfig | null;
     /**
      * Update tool configuration and apply the change to the underlying services.
      */
-    updateToolConfig(toolId: "textToSpeech", updates: Partial<TextToSpeechToolProviderConfig>): void;
+    updateToolConfig(toolId: typeof TTS_TOOL_ID, updates: Partial<TextToSpeechToolProviderConfig>): void;
     updateToolConfig(toolId: string, updates: Partial<ToolProviderConfig>): void;
     /**
      * Patch one or more placement levels in the canonical tools config.
@@ -899,12 +872,4 @@ export declare class ToolkitCoordinator {
      * so a check on the policy change the update dispatched finds the new provider.
      */
     private _registerChangedToolProvider;
-    /**
-     * 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.
-     */
-    private scheduleTTSReconfigure;
-    private _reconfigureTTSProvider;
 }