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

package/dist/services/toolbar-items.js

@@ -19,13 +19,10 @@ export function isValidToolbarItemShape(value) {
         return false;
     if (item.disabled !== undefined && typeof item.disabled !== "boolean")
         return false;
+    // A link or a button: exactly one of `href` and `onClick`.
     const hasHref = typeof item.href === "string";
     const hasOnClick = typeof item.onClick === "function";
-    if (hasHref === hasOnClick)
-        return false;
-    if (hasHref)
-        return true;
-    return hasOnClick;
+    return hasHref !== hasOnClick;
 }
 export function isInlineSvgIcon(icon) {
     return typeof icon === "string" && icon.trimStart().startsWith("<svg");

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,34 +72,30 @@ 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`) or through `setPnpEnforcement`.
  *
- * - `"on"` — force enforcement (engine applies PNP/profile gates).
- * - `"off"` — opt out (engine ignores PNP/profile inputs).
- * - omitted / `undefined` — auto-mode (the default). The toolkit
- *   coordinator computes the effective mode from PNP/profile policy material on the
- *   bound `AssessmentEntity` / `AssessmentItemRef`. See
+ * - `"on"` — toolbar decisions apply PNP/profile policy.
+ * - `"off"` — toolbar decisions skip it. Feature decisions read it either way.
+ * - omitted — auto-mode (the default): on when the bound assessment carries
+ *   PNP/profile policy material, or, for a decision scoped to an item, when
+ *   that item's settings require or restrict a tool. See
  *   `resolveDefaultPnpEnforcement` in `policy/core/pnp-policy-inputs.ts`.
  */
-export type ToolsPnpEnforcement = "on" | "off";
+export type PnpEnforcementMode = "on" | "off";
 export interface CanonicalToolsConfig {
     policy: ToolPolicyConfig;
     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 PnpEnforcementMode} for semantics.
      */
-    pnpEnforcement?: ToolsPnpEnforcement;
+    pnpEnforcement?: PnpEnforcementMode;
 }
 /**
  * The tools config a host supplies. Every part is optional, placement levels
@@ -108,7 +104,15 @@ export interface CanonicalToolsConfig {
 export type ToolsConfigInput = Omit<Partial<CanonicalToolsConfig>, "placement"> & {
     placement?: ToolPlacementConfig;
 };
-export declare function normalizeToolAlias(toolId: string): string;
+/**
+ * Tool ids trimmed, with empty ones dropped and duplicates removed in
+ * first-seen order. Throws on a non-string entry.
+ */
 export declare function normalizeToolList(toolIds: string[] | undefined | null): string[];
 export declare function parseToolList(input: string | undefined | null): string[];
+/**
+ * Check a host's tools config shape, throwing at the first malformed field, and
+ * return it canonical: tool lists trimmed and deduplicated, and every placement
+ * level that names no tool filled with its default.
+ */
 export declare function normalizeToolsConfig(input?: ToolsConfigInput | null): CanonicalToolsConfig;

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

@@ -1,12 +1,10 @@
 import { DEFAULT_TOOL_PLACEMENT } from "./tool-config-defaults.js";
+import { isPlainRecord } from "@pie-players/pie-players-shared/object";
 const DEFAULT_PLACEMENT = {
     section: [...DEFAULT_TOOL_PLACEMENT.section],
     item: [...DEFAULT_TOOL_PLACEMENT.item],
     passage: [...DEFAULT_TOOL_PLACEMENT.passage],
 };
-function isPlainObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 function assertStringArray(value, fieldPath) {
     if (value == null)
         return [];
@@ -22,7 +20,7 @@ function assertStringArray(value, fieldPath) {
 function assertPlacementConfig(value) {
     if (value == null)
         return undefined;
-    if (!isPlainObject(value)) {
+    if (!isPlainRecord(value)) {
         throw new Error('Invalid tools config at "placement": expected an object with section/item/passage arrays.');
     }
     return value;
@@ -30,7 +28,7 @@ function assertPlacementConfig(value) {
 function assertPolicyConfig(value) {
     if (value == null)
         return undefined;
-    if (!isPlainObject(value)) {
+    if (!isPlainRecord(value)) {
         throw new Error('Invalid tools config at "policy": expected an object with allowed/blocked arrays.');
     }
     return value;
@@ -38,11 +36,10 @@ function assertPolicyConfig(value) {
 function assertProviderConfig(providerId, value) {
     if (value == null)
         return undefined;
-    if (!isPlainObject(value)) {
+    if (!isPlainRecord(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") {
@@ -50,13 +47,12 @@ function assertProviderConfig(providerId, value) {
     }
     if ("settings" in config &&
         config.settings !== undefined &&
-        !isPlainObject(config.settings)) {
+        !isPlainRecord(config.settings)) {
         throw new Error(`Invalid tools config at "providers.${providerId}.settings": expected an object.`);
     }
     if ("provider" in config &&
         config.provider !== undefined &&
-        !isPlainObject(config.provider) &&
-        !(providerId === "textToSpeech" && isTTSRuntimeProviderId(config.provider))) {
+        !isPlainRecord(config.provider)) {
         throw new Error(`Invalid tools config at "providers.${providerId}.provider": expected an object.`);
     }
     return config;
@@ -64,7 +60,7 @@ function assertProviderConfig(providerId, value) {
 function assertProvidersConfig(value) {
     if (value == null)
         return {};
-    if (!isPlainObject(value)) {
+    if (!isPlainRecord(value)) {
         throw new Error('Invalid tools config at "providers": expected an object keyed by tool id.');
     }
     const normalized = {};
@@ -73,12 +69,10 @@ function assertProvidersConfig(value) {
     }
     return normalized;
 }
-export function normalizeToolAlias(toolId) {
-    const trimmed = toolId.trim();
-    if (!trimmed)
-        return "";
-    return trimmed;
-}
+/**
+ * Tool ids trimmed, with empty ones dropped and duplicates removed in
+ * first-seen order. Throws on a non-string entry.
+ */
 export function normalizeToolList(toolIds) {
     if (!toolIds || toolIds.length === 0)
         return [];
@@ -87,7 +81,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);
@@ -109,8 +103,18 @@ function assertPnpEnforcement(value, fieldPath) {
         return value;
     throw new Error(`Invalid tools config at "${fieldPath}": expected "on" or "off", got ${JSON.stringify(value)}.`);
 }
+/** A placement level's tool ids, or the level's default when it names none. */
+function normalizePlacementLevel(placement, level) {
+    const toolIds = normalizeToolList(assertStringArray(placement?.[level], `placement.${level}`));
+    return toolIds.length ? toolIds : [...DEFAULT_PLACEMENT[level]];
+}
+/**
+ * Check a host's tools config shape, throwing at the first malformed field, and
+ * return it canonical: tool lists trimmed and deduplicated, and every placement
+ * level that names no tool filled with its default.
+ */
 export function normalizeToolsConfig(input) {
-    if (input != null && !isPlainObject(input)) {
+    if (input != null && !isPlainRecord(input)) {
         throw new Error('Invalid tools config: expected an object with "policy", "placement", and "providers".');
     }
     const policy = assertPolicyConfig(input?.policy);
@@ -123,15 +127,9 @@ export function normalizeToolsConfig(input) {
             blocked: normalizeToolList(assertStringArray(policy?.blocked, "policy.blocked")),
         },
         placement: {
-            section: normalizeToolList(assertStringArray(placement?.section, "placement.section")).length
-                ? normalizeToolList(assertStringArray(placement?.section, "placement.section"))
-                : [...DEFAULT_PLACEMENT.section],
-            item: normalizeToolList(assertStringArray(placement?.item, "placement.item")).length
-                ? normalizeToolList(assertStringArray(placement?.item, "placement.item"))
-                : [...DEFAULT_PLACEMENT.item],
-            passage: normalizeToolList(assertStringArray(placement?.passage, "placement.passage")).length
-                ? normalizeToolList(assertStringArray(placement?.passage, "placement.passage"))
-                : [...DEFAULT_PLACEMENT.passage],
+            section: normalizePlacementLevel(placement, "section"),
+            item: normalizePlacementLevel(placement, "item"),
+            passage: normalizePlacementLevel(placement, "passage"),
         },
         providers,
     };

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

@@ -3,10 +3,46 @@
  *
  * Text-to-speech provider using the browser's Web Speech API.
  * Works in all modern browsers that support SpeechSynthesis.
- *
- * 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";
+import type { ToolkitTTSConfig } from "./provider-options.js";
+/**
+ * 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<ToolkitTTSConfig>) => Partial<ToolkitTTSConfig>;
+/**
+ * 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
  *
@@ -14,10 +50,7 @@ import type { ITTSProvider, ITTSProviderImplementation, TTSConfig, TTSFeature, T
  */
 export declare class BrowserTTSProvider implements ITTSProvider {
     readonly providerId = "browser";
-    readonly providerName = "Browser Speech Synthesis";
-    readonly version = "1.0.0";
     initialize(config: TTSConfig): Promise<ITTSProviderImplementation>;
-    supportsFeature(feature: TTSFeature): boolean;
     getCapabilities(): TTSProviderCapabilities;
     destroy(): void;
 }