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

package/dist/services/tool-request.js

@@ -32,11 +32,11 @@ export class ToolRequestRegistry {
     changeListeners = new Set();
     registerTarget(target) {
         this.targets.add(target);
-        this.notifyChange();
+        this.notifyTargetsChange();
         return () => {
             if (!this.targets.delete(target))
                 return;
-            this.notifyChange();
+            this.notifyTargetsChange();
         };
     }
     /**
@@ -46,12 +46,12 @@ export class ToolRequestRegistry {
      * nothing is worse than an absent one, and availability moves with policy —
      * hence {@link onTargetsChange}.
      */
-    canRequest(toolId, level) {
-        return this.findTarget(toolId, level) !== null;
+    canRequest(toolId, level, scopeId) {
+        return this.findTarget(toolId, level, scopeId) !== null;
     }
     /** Returns whether a target claimed the request. */
     request(request) {
-        const target = this.findTarget(request.toolId, request.level);
+        const target = this.findTarget(request.toolId, request.level, request.scopeId);
         if (!target)
             return false;
         try {
@@ -64,12 +64,13 @@ export class ToolRequestRegistry {
         return true;
     }
     /**
-     * Fires when a toolbar registers or unregisters.
+     * Fires when a toolbar registers or unregisters, and on
+     * {@link notifyTargetsChange}.
      *
-     * Not when a registered toolbar's own visible set changes: `hostsTool` is read
-     * live, so a caller re-asking `canRequest` gets the current answer. A surface
-     * that needs to notice a policy change should also follow the policy signal it
-     * already has.
+     * Not when a policy change moves a registered toolbar's visible set: `hostsTool`
+     * is read live, so a caller re-asking `canRequest` gets the current answer. A
+     * surface that needs to notice a policy change should also follow the policy
+     * signal it already has.
      */
     onTargetsChange(listener) {
         this.changeListeners.add(listener);
@@ -84,22 +85,26 @@ export class ToolRequestRegistry {
      * and still have a section-scoped gateway reach it. Requesting a level explicitly
      * does not fall back, because a requester that named one meant it.
      */
-    findTarget(toolId, level) {
-        const preferred = this.findTargetAtLevel(toolId, level ?? DEFAULT_TOOL_REQUEST_LEVEL);
+    findTarget(toolId, level, scopeId) {
+        const preferred = this.findTargetAtLevel(toolId, level ?? DEFAULT_TOOL_REQUEST_LEVEL, scopeId);
         if (preferred || level !== undefined)
             return preferred;
         for (const target of this.targets) {
             if (target.level === DEFAULT_TOOL_REQUEST_LEVEL)
                 continue;
+            if (scopeId !== undefined && target.scopeId !== scopeId)
+                continue;
             if (this.hostsTool(target, toolId))
                 return target;
         }
         return null;
     }
-    findTargetAtLevel(toolId, level) {
+    findTargetAtLevel(toolId, level, scopeId) {
         for (const target of this.targets) {
             if (target.level !== level)
                 continue;
+            if (scopeId !== undefined && target.scopeId !== scopeId)
+                continue;
             if (this.hostsTool(target, toolId))
                 return target;
         }
@@ -114,7 +119,12 @@ export class ToolRequestRegistry {
             return false;
         }
     }
-    notifyChange() {
+    /**
+     * Tell change listeners that what the targets can claim changed. Registration
+     * calls it, and so does the coordinator when a target stops hosting a tool
+     * outside a policy change, as when the tool's module fails to load.
+     */
+    notifyTargetsChange() {
         for (const listener of this.changeListeners) {
             try {
                 listener();

package/dist/services/toolbar-decided-tools.d.ts

@@ -0,0 +1,15 @@
+import type { ToolPolicyDecision } from "../policy/core/decision-types.js";
+/** What a toolbar renders from in a policy decision, per visible tool. */
+export interface DecidedToolbarTool {
+    toolId: string;
+    required: boolean;
+    alwaysAvailable: boolean;
+}
+/**
+ * A toolbar's decided tools across re-decisions. The tracker returns its
+ * previous list while `renderVersion` is unchanged and the decision shows the
+ * same tools, so a re-decision that changes nothing the toolbar renders from
+ * keeps the rendered tools: rendering swaps in fresh tool elements, whose state
+ * starts over. A new `renderVersion` always yields a new list.
+ */
+export declare function createDecidedToolsTracker(): (decision: ToolPolicyDecision | null, renderVersion: number) => readonly DecidedToolbarTool[] | null;

package/dist/services/toolbar-decided-tools.js

@@ -0,0 +1,28 @@
+import { structurallyEqual } from "../utils/structural-equality.js";
+/**
+ * A toolbar's decided tools across re-decisions. The tracker returns its
+ * previous list while `renderVersion` is unchanged and the decision shows the
+ * same tools, so a re-decision that changes nothing the toolbar renders from
+ * keeps the rendered tools: rendering swaps in fresh tool elements, whose state
+ * starts over. A new `renderVersion` always yields a new list.
+ */
+export function createDecidedToolsTracker() {
+    let last = null;
+    return (decision, renderVersion) => {
+        if (!decision) {
+            last = null;
+            return null;
+        }
+        const tools = decision.visibleTools.map((entry) => ({
+            toolId: entry.toolId,
+            required: entry.required,
+            alwaysAvailable: entry.alwaysAvailable,
+        }));
+        if (last?.renderVersion === renderVersion &&
+            structurallyEqual(last.tools, tools)) {
+            return last.tools;
+        }
+        last = { renderVersion, tools };
+        return tools;
+    };
+}

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

@@ -1,5 +1,5 @@
 import type { CalculatorProviderConfig } from "@pie-players/pie-calculator";
-import type { SREMathSpeechOptions } from "./tts/math-speech.js";
+import type { TTSRuntimeSettings } from "./tts-runtime-config.js";
 export type ToolPlacementLevel = "section" | "item" | "passage";
 export interface ToolPolicyConfig {
     allowed?: string[];
@@ -43,22 +43,22 @@ export interface ToolRuntimeProviderConfig {
     init?: Record<string, unknown>;
     runtime?: ToolRuntimeProviderBridge;
 }
-export type TextToSpeechRuntimeProviderId = "polly" | "google" | "custom";
 export interface ToolProviderConfig {
     enabled?: boolean;
     provider?: ToolRuntimeProviderConfig;
     settings?: Record<string, unknown>;
     [key: string]: unknown;
 }
-export interface TextToSpeechToolProviderSettings extends Record<string, unknown> {
-    mathSpeech?: SREMathSpeechOptions;
-}
-export interface TextToSpeechToolProviderConfig extends Omit<ToolProviderConfig, "provider" | "settings"> {
-    provider?: ToolRuntimeProviderConfig | TextToSpeechRuntimeProviderId;
-    serverProvider?: TextToSpeechRuntimeProviderId;
-    mathSpeech?: SREMathSpeechOptions;
-    settings?: TextToSpeechToolProviderSettings;
-}
+/**
+ * `tools.providers.textToSpeech`, closed to the runtime settings the TTS tool
+ * reads plus the registration's `enabled` and runtime `provider`. `Pick` keeps
+ * it assignable to the providers index signature, which an interface would not
+ * be.
+ */
+export type TextToSpeechToolProviderConfig = Pick<TTSRuntimeSettings, keyof TTSRuntimeSettings> & {
+    enabled?: boolean;
+    provider?: ToolRuntimeProviderConfig;
+};
 /**
  * `tools.providers.calculator`, closed to the keys the calculator reads, so a
  * misplaced key such as a top-level `authFetcher` fails to compile instead of
@@ -72,13 +72,11 @@ export type CalculatorToolProviderConfig = Pick<CalculatorProviderConfig, keyof
 export interface ToolProvidersConfig {
     textToSpeech?: TextToSpeechToolProviderConfig;
     calculator?: CalculatorToolProviderConfig;
-    [key: string]: ToolProviderConfig | TextToSpeechToolProviderConfig | undefined;
+    [key: string]: ToolProviderConfig | undefined;
 }
 /**
- * PNP/profile enforcement mode mirrored on `runtime.tools.pnpEnforcement`
- * (M5 mirror rule). Carried alongside `policy` / `placement` /
- * `providers` so hosts can pin or opt out of PNP/profile precedence via
- * the runtime config without reaching for the toolkit prop directly.
+ * PNP/profile enforcement mode, set as `tools.pnpEnforcement` (on a section
+ * player, `runtime.tools.pnpEnforcement`).
  *
  * - `"on"` — force enforcement (engine applies PNP/profile gates).
  * - `"off"` — opt out (engine ignores PNP/profile inputs).
@@ -93,11 +91,9 @@ export interface CanonicalToolsConfig {
     placement: Required<ToolPlacementConfig>;
     providers: ToolProvidersConfig;
     /**
-     * Optional PNP/profile enforcement override. Mirrored on
-     * `runtime.tools.pnpEnforcement`; consumed by
-     * `<pie-assessment-toolkit>` and `ToolkitCoordinator` as the
-     * embedded path's equivalent of the standalone `pnp-enforcement`
-     * attribute. See {@link ToolsPnpEnforcement} for semantics.
+     * Optional PNP/profile enforcement override, read by
+     * `<pie-assessment-toolkit>` and `ToolkitCoordinator`. See
+     * {@link ToolsPnpEnforcement} for semantics.
      */
     pnpEnforcement?: ToolsPnpEnforcement;
 }
@@ -108,7 +104,6 @@ export interface CanonicalToolsConfig {
 export type ToolsConfigInput = Omit<Partial<CanonicalToolsConfig>, "placement"> & {
     placement?: ToolPlacementConfig;
 };
-export declare function normalizeToolAlias(toolId: string): string;
 export declare function normalizeToolList(toolIds: string[] | undefined | null): string[];
 export declare function parseToolList(input: string | undefined | null): string[];
 export declare function normalizeToolsConfig(input?: ToolsConfigInput | null): CanonicalToolsConfig;

package/dist/services/tools-config-normalizer.js

@@ -42,7 +42,6 @@ function assertProviderConfig(providerId, value) {
         throw new Error(`Invalid tools config at "providers.${providerId}": expected an object.`);
     }
     const config = value;
-    const isTTSRuntimeProviderId = (provider) => provider === "polly" || provider === "google" || provider === "custom";
     if ("enabled" in config &&
         config.enabled !== undefined &&
         typeof config.enabled !== "boolean") {
@@ -55,8 +54,7 @@ function assertProviderConfig(providerId, value) {
     }
     if ("provider" in config &&
         config.provider !== undefined &&
-        !isPlainObject(config.provider) &&
-        !(providerId === "textToSpeech" && isTTSRuntimeProviderId(config.provider))) {
+        !isPlainObject(config.provider)) {
         throw new Error(`Invalid tools config at "providers.${providerId}.provider": expected an object.`);
     }
     return config;
@@ -73,12 +71,6 @@ function assertProvidersConfig(value) {
     }
     return normalized;
 }
-export function normalizeToolAlias(toolId) {
-    const trimmed = toolId.trim();
-    if (!trimmed)
-        return "";
-    return trimmed;
-}
 export function normalizeToolList(toolIds) {
     if (!toolIds || toolIds.length === 0)
         return [];
@@ -87,7 +79,7 @@ export function normalizeToolList(toolIds) {
         if (typeof rawToolId !== "string") {
             throw new Error("Invalid tools config: tool list entries must be strings.");
         }
-        const normalized = normalizeToolAlias(rawToolId);
+        const normalized = rawToolId.trim();
         if (!normalized)
             continue;
         deduped.add(normalized);

package/dist/services/tts/browser-provider.d.ts

@@ -6,7 +6,44 @@
  *
  * Part of PIE Assessment Toolkit.
  */
-import type { ITTSProvider, ITTSProviderImplementation, TTSConfig, TTSFeature, TTSProviderCapabilities } from "@pie-players/pie-tts";
+import type { ITTSProvider, ITTSProviderImplementation, TTSConfig, TTSProviderCapabilities } from "@pie-players/pie-tts";
+/**
+ * The part of another provider's configuration that keeps its meaning on
+ * browser speech. Every path that replaces a provider with browser speech
+ * starts it with this.
+ */
+export declare const browserFallbackConfig: (config: Partial<TTSConfig>) => Partial<TTSConfig>;
+/**
+ * The voice traits browser voice selection reads. A `SpeechSynthesisVoice` has
+ * them all; a host's own voice list may carry a subset.
+ */
+export interface BrowserVoiceTraits {
+    voiceURI?: string;
+    name?: string;
+    lang?: string;
+    localService?: boolean;
+    default?: boolean;
+}
+/**
+ * Whether a voice speaks `contentLanguage`, or the browser's own language when
+ * the content names none: the same language, or the same primary subtag.
+ */
+export declare const browserVoiceMatchesLanguage: (voice: Pick<BrowserVoiceTraits, "lang">, contentLanguage?: string) => boolean;
+/**
+ * The voice to read with: the configured one, else one for `contentLanguage`
+ * (the language of the content being read), else one for the browser's own
+ * language.
+ */
+export declare const findBrowserVoice: <Voice extends BrowserVoiceTraits>(voices: readonly Voice[], preferredVoice?: string, contentLanguage?: string) => Voice | null;
+/**
+ * Waits for `synth` to publish its voice inventory, which browsers fill
+ * asynchronously after page load. Resolves `true` once `getVoices()` is
+ * non-empty, at once when it already is; `false` after `timeoutMs`, once
+ * `isCurrent` reports the wait superseded, or when `synth` offers no
+ * `voiceschanged` channel to wait on. A previous `onvoiceschanged` handler
+ * keeps running and is restored afterwards.
+ */
+export declare const waitForBrowserVoices: (synth: SpeechSynthesis, timeoutMs: number, isCurrent?: () => boolean) => Promise<boolean>;
 /**
  * Browser TTS Provider
  *
@@ -17,7 +54,6 @@ export declare class BrowserTTSProvider implements ITTSProvider {
     readonly providerName = "Browser Speech Synthesis";
     readonly version = "1.0.0";
     initialize(config: TTSConfig): Promise<ITTSProviderImplementation>;
-    supportsFeature(feature: TTSFeature): boolean;
     getCapabilities(): TTSProviderCapabilities;
     destroy(): void;
 }