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

package/dist/policy/sources/PnpPolicySource.js

@@ -19,6 +19,7 @@ export class PnpPolicySource {
         const allSupports = new Set();
         pnp?.supports?.forEach((s) => allSupports.add(s));
         pnp?.prohibitedSupports?.forEach((s) => allSupports.add(s));
+        pnp?.activateAtInit?.forEach((s) => allSupports.add(s));
         districtPolicy?.blockedTools?.forEach((s) => allSupports.add(s));
         districtPolicy?.requiredTools?.forEach((s) => allSupports.add(s));
         for (const s of Object.keys(testAdmin?.toolOverrides ?? {})) {
@@ -162,6 +163,7 @@ export class PnpPolicySource {
             });
             return;
         }
+        const activateAtInit = ctx.pnp?.activateAtInit?.includes(supportId) === true;
         const mandate = ctx.itemSettings?.requiredTools?.includes(supportId)
             ? "item-requirement"
             : ctx.districtPolicy?.requiredTools?.includes(supportId)
@@ -175,6 +177,7 @@ export class PnpPolicySource {
             out.perToolFlags.set(supportId, {
                 required: mandate !== undefined,
                 alwaysAvailable: true,
+                activateAtInit,
                 rule: "test-admin-override",
             });
             out.decisions.push({
@@ -194,6 +197,7 @@ export class PnpPolicySource {
             out.perToolFlags.set(supportId, {
                 required: true,
                 alwaysAvailable: false,
+                activateAtInit,
                 rule: "item-requirement",
             });
             out.decisions.push({
@@ -213,6 +217,7 @@ export class PnpPolicySource {
             out.perToolFlags.set(supportId, {
                 required: true,
                 alwaysAvailable: false,
+                activateAtInit,
                 rule: "district-requirement",
             });
             out.decisions.push({
@@ -226,11 +231,31 @@ export class PnpPolicySource {
             });
             return;
         }
-        // 8. Profile supports (student needs)
+        // 8. Profile supports (student needs). `activateAtInit` grants as
+        // `supports` does and names the tool to turn on at start.
+        if (activateAtInit) {
+            out.perToolFlags.set(supportId, {
+                required: false,
+                alwaysAvailable: true,
+                activateAtInit,
+                rule: "pnp-activate-at-init",
+            });
+            out.decisions.push({
+                precedence: 8,
+                rule: "pnp-activate-at-init",
+                featureId: supportId,
+                action: "enable",
+                sourceType: "student",
+                reason: `Student PNP profile turns on "${supportId}" at start`,
+                value: ctx.pnp?.activateAtInit,
+            });
+            return;
+        }
         if (ctx.pnp?.supports?.includes(supportId)) {
             out.perToolFlags.set(supportId, {
                 required: false,
                 alwaysAvailable: true,
+                activateAtInit: false,
                 rule: "pnp-support",
             });
             out.decisions.push({
@@ -281,6 +306,7 @@ export class PnpPolicySource {
             ["pnp-prohibited", pnp?.prohibitedSupports],
             ["item-requirement", items.flatMap((item) => item.requiredTools ?? [])],
             ["district-requirement", settings?.districtPolicy?.requiredTools],
+            ["pnp-activate-at-init", pnp?.activateAtInit],
             ["pnp-support", pnp?.supports],
         ];
         for (const [rule, ids] of named) {

package/dist/services/TTSService.d.ts

@@ -121,7 +121,8 @@ export declare class TTSService {
      */
     initialize(provider: ITTSProvider, config?: Partial<ToolkitTTSConfig>): Promise<void>;
     /**
-     * Update rate, pitch, voice or provider options without reinitializing.
+     * Update rate, pitch, volume, voice or provider options without
+     * reinitializing.
      * `providerOptions` merge over the ones already configured.
      */
     updateSettings(settings: Partial<TTSConfig>): Promise<void>;
@@ -254,10 +255,10 @@ export declare class TTSService {
      */
     speak(target: Range | Element, options?: SpeakOptions): Promise<void>;
     /**
-     * Sets the rate a run starts at, after any rate write in flight. The run has
-     * no playback yet, so nothing restarts.
+     * Sets the rate, pitch and volume a run starts at, after any rate write in
+     * flight. The run has no playback yet, so nothing restarts.
      */
-    private applyRunRate;
+    private applyRunSettings;
     /**
      * Suppression is read from the live ancestors of what is read, because the
      * element carrying it may sit above the content root.

package/dist/services/TTSService.js

@@ -389,7 +389,8 @@ export class TTSService {
         this.provider = await provider.initialize(config);
     }
     /**
-     * Update rate, pitch, voice or provider options without reinitializing.
+     * Update rate, pitch, volume, voice or provider options without
+     * reinitializing.
      * `providerOptions` merge over the ones already configured.
      */
     async updateSettings(settings) {
@@ -1160,24 +1161,37 @@ export class TTSService {
             return;
         }
         const runId = waitingRunId ?? this.beginRun(owner);
-        if (options.rate !== undefined) {
-            await this.applyRunRate(options.rate);
+        if (options.rate !== undefined ||
+            options.pitch !== undefined ||
+            options.volume !== undefined) {
+            await this.applyRunSettings(options);
             if (runId !== this.speakRunId)
                 return;
         }
         await this.speakContent(content.text, content.options, runId);
     }
     /**
-     * Sets the rate a run starts at, after any rate write in flight. The run has
-     * no playback yet, so nothing restarts.
+     * Sets the rate, pitch and volume a run starts at, after any rate write in
+     * flight. The run has no playback yet, so nothing restarts.
      */
-    async applyRunRate(rate) {
+    async applyRunSettings(options) {
         await this.playbackRateWriteQueue;
-        const nextRate = this.normalizePlaybackRate(rate);
-        const currentRate = this.normalizePlaybackRate(Number(this.ttsConfig.rate ?? 1));
-        if (nextRate === currentRate)
-            return;
-        await this.updateSettings({ rate: nextRate });
+        const settings = {};
+        if (options.rate !== undefined) {
+            const nextRate = this.normalizePlaybackRate(options.rate);
+            const currentRate = this.normalizePlaybackRate(Number(this.ttsConfig.rate ?? 1));
+            if (nextRate !== currentRate)
+                settings.rate = nextRate;
+        }
+        if (options.pitch !== undefined && options.pitch !== this.ttsConfig.pitch) {
+            settings.pitch = options.pitch;
+        }
+        if (options.volume !== undefined &&
+            options.volume !== this.ttsConfig.volume) {
+            settings.volume = options.volume;
+        }
+        if (Object.keys(settings).length > 0)
+            await this.updateSettings(settings);
     }
     /**
      * Suppression is read from the live ancestors of what is read, because the

package/dist/services/ToolRegistry.d.ts

@@ -114,9 +114,10 @@ export interface ToolbarContext {
     getResolvedToolContext?: (toolId: string) => ResolvedToolContext | null;
     getToolRenderParams?: (toolId: string) => Record<string, unknown> | null;
     /**
-     * The tool's policy parameters on this toolbar: the item's `toolParameters`
-     * entry on an item's own toolbar, else the assessment's `toolParameters` entry.
-     * Authored content, so a registration checks what it reads.
+     * The tool's policy parameters on this toolbar: the profile's, assessment's
+     * and, on an item's own toolbar, item's `toolParameters` entries merged key by
+     * key, later ones winning. Authored content, so a registration checks what it
+     * reads.
      */
     getToolParameters?: <K extends string>(toolId: K) => ToolParametersFor<K> | null;
 }

package/dist/services/ToolRegistry.js

@@ -12,6 +12,7 @@
  * warnings and the toolbar and surface render helpers.
  */
 import { dynamicMessageKey } from "@pie-players/pie-players-shared/i18n/provider";
+import { settleAll } from "@pie-players/pie-players-shared/promise";
 import { resolveToolTag, } from "../tools/tool-tag-map.js";
 import { PENDING_INPUT_WARNING_DELAY_MS, warnOncePerDocument, } from "../runtime/page-warnings.js";
 const logToolCallbackFailure = (toolId, phase, error) => console.error(`[ToolRegistry] Tool '${toolId}' ${phase} check threw:`, error);
@@ -608,7 +609,7 @@ export class ToolRegistry {
      * tools loaded and usable. A failed tool is retried on the next call.
      */
     async ensureToolModulesLoaded(toolIds) {
-        const results = await Promise.allSettled(toolIds.map((toolId) => this.ensureToolModuleLoaded(toolId)));
+        const results = await settleAll(toolIds.map((toolId) => this.ensureToolModuleLoaded(toolId)));
         const failures = new Map();
         results.forEach((result, index) => {
             if (result.status === "rejected")

package/dist/services/ToolkitCoordinator.js

@@ -21,6 +21,7 @@
  * - tool-open requests;
  * - config-change application and TTS reconfiguration, last.
  */
+import { settleAll } from "@pie-players/pie-players-shared/promise";
 import { normalizeToolsConfig, } from "./tools-config-normalizer.js";
 import { collectToolConfigDiagnostics, normalizeToolConfigStrictness, reportToolConfigDiagnostics, } from "./tool-config-validation.js";
 import { AccessibilityCatalogResolver } from "./AccessibilityCatalogResolver.js";
@@ -1272,7 +1273,7 @@ export class ToolkitCoordinator {
             // retired controller out of the cache immediately, but do not let its
             // replacement hydrate until that exact cohort's save/dispose pipeline has
             // settled. Other cohorts remain independent.
-            await Promise.allSettled([pendingDisposal]);
+            await settleAll([pendingDisposal]);
         }
         if (this.disposePromise !== null) {
             throw new ToolkitCoordinatorDisposedError();
@@ -1540,7 +1541,7 @@ export class ToolkitCoordinator {
                 return existingDisposal;
             if (!initEntry)
                 return Promise.resolve();
-            const retirementBarrier = Promise.allSettled([initEntry.promise]).then(() => undefined);
+            const retirementBarrier = settleAll([initEntry.promise]).then(() => undefined);
             return this.trackSectionControllerDisposal(mapKey, retirementBarrier);
         }
         const persistenceStrategy = this.sectionPersistenceStrategies.get(mapKey);
@@ -1576,7 +1577,7 @@ export class ToolkitCoordinator {
             persistenceStrategy,
         });
         const disposalBarrier = initEntry
-            ? Promise.allSettled([initEntry.promise]).then(() => controllerDisposalPromise)
+            ? settleAll([initEntry.promise]).then(() => controllerDisposalPromise)
             : controllerDisposalPromise;
         return this.trackSectionControllerDisposal(mapKey, disposalBarrier);
     }
@@ -1694,7 +1695,7 @@ export class ToolkitCoordinator {
                 attemptId: key.attemptId,
             });
         }
-        await Promise.allSettled(Array.from(this.sectionControllerDisposePromises.values()));
+        await settleAll(Array.from(this.sectionControllerDisposePromises.values()));
         this.sectionControllers.clear();
         this.sectionControllerKeys.clear();
         this.sectionControllerInitEntries.clear();
@@ -1742,7 +1743,7 @@ export class ToolkitCoordinator {
         for (const promise of this.providerInitPromises.values()) {
             pending.add(promise);
         }
-        await Promise.allSettled(pending);
+        await settleAll(pending);
     }
     /**
      * Initialize the TTS service from the `textToSpeech` tool config.

package/dist/services/interfaces.d.ts

@@ -211,6 +211,10 @@ export interface SpeakOptions {
     ownerId?: string;
     /** The rate the read starts at; it stays the service's rate afterwards. */
     rate?: number;
+    /** The pitch the read starts at, 0–2 with 1 normal; it stays the service's. */
+    pitch?: number;
+    /** The volume the read starts at, 0–1; it stays the service's. */
+    volume?: number;
 }
 /**
  * TTS service interface

package/dist/services/tool-context.d.ts

@@ -107,9 +107,40 @@ export type ToolContext = AssessmentToolContext | SectionToolContext | ItemToolC
  */
 export declare function hasMathContent(context: ToolContext): boolean;
 /**
- * Helper to check if context contains choice-based interactions
+ * What one element of a context declares about the PNP supports it implements.
+ *
+ * An element declares them on its class, as `static pieSupports`: a list of AfA
+ * PNP 3.0 support terms, such as `answer-masking`. The toolkit reads the class
+ * `customElements` holds under the element's runtime tag, so the declaration is
+ * known before the element renders. What a support needs from the rendered
+ * element is between the element and the tool that provides it, and that tool
+ * documents it.
+ */
+export interface ElementSupports {
+    /** The element's model id. */
+    elementId: string | undefined;
+    /** The tag the item binds the element to, as authored. */
+    tag: string;
+    /** The element's package spec in the item's `elements` map, when it has one. */
+    packageSpec: string | undefined;
+    /**
+     * The terms the element's class declares: `undefined` while the class is
+     * undefined, and for a class that declares nothing. An empty list is a
+     * declaration that the element implements none.
+     */
+    supports: readonly string[] | undefined;
+    /**
+     * The runtime tags the class can still be defined under, empty once it is
+     * defined. A definition landing under one of them can change `supports`.
+     */
+    pendingTags: readonly string[];
+}
+/**
+ * The supports each element of a context declares: the element's own at element
+ * level, every element of the item or passage config at those levels, and none
+ * elsewhere. A model that names no element renders nothing and is skipped.
  */
-export declare function hasChoiceInteraction(context: ToolContext): boolean;
+export declare function elementSupports(context: ToolContext): ElementSupports[];
 /**
  * Helper to check if context contains text that can be read aloud
  */

package/dist/services/tool-context.js

@@ -4,6 +4,8 @@
  * Defines the context types passed to tools for making visibility and behavior decisions.
  * Each context level provides increasingly specific information about where the tool is being used.
  */
+import { runtimeElementTags } from "@pie-players/pie-players-shared/pie";
+import { parseVersionedTagName } from "@pie-players/pie-players-shared/pie/tag-names";
 /**
  * Type guard to check if context is at item level
  */
@@ -300,63 +302,81 @@ export function hasMathContent(context) {
         hasSpacedSubtraction(text) ||
         hasAppliedPercentage(text));
 }
-const CHOICE_INTERACTION_ELEMENTS = new Set([
-    "multiple-choice",
-    "inline-choice",
-    "select-text",
-    "ebsr",
-]);
-// Content names one interaction several ways: `multiple-choice`, `pie-multiple-choice`,
-// `pie-element-multiple-choice`, a runtime `--version-*` tag, or any tag the item's
-// `elements` map binds to `@pie-element/multiple-choice`.
-const baseElementName = (tag) => tag
-    .toLowerCase()
-    .replace(/--version-[0-9a-z-]+$/, "")
-    .replace(/^pie-(element-)?/, "");
-function isChoiceElement(tag, elements) {
-    if (CHOICE_INTERACTION_ELEMENTS.has(baseElementName(tag)))
-        return true;
+function packageSpecFor(tag, elements) {
     if (!elements || typeof elements !== "object")
-        return false;
+        return undefined;
     const map = elements;
-    const spec = map[tag] ?? map[tag.replace(/--version-[0-9A-Za-z-]+$/, "")];
-    if (typeof spec !== "string")
-        return false;
-    const packageName = spec.match(/^@pie-element\/([^@]+)/)?.[1];
-    return !!packageName && CHOICE_INTERACTION_ELEMENTS.has(packageName);
+    const spec = map[tag] ?? map[parseVersionedTagName(tag).baseName];
+    return typeof spec === "string" && spec ? spec : undefined;
+}
+function declaredSupports(elementClass) {
+    let declared;
+    try {
+        declared = elementClass.pieSupports;
+    }
+    catch {
+        return undefined;
+    }
+    if (!Array.isArray(declared))
+        return undefined;
+    return declared.filter((term) => typeof term === "string");
+}
+function readElementSupports(model, elements) {
+    if (!model || typeof model !== "object")
+        return null;
+    const { id, element } = model;
+    if (typeof element !== "string" || !element)
+        return null;
+    const packageSpec = packageSpecFor(element, elements);
+    const candidates = runtimeElementTags(element, packageSpec);
+    const registry = typeof customElements === "undefined" ? undefined : customElements;
+    for (const tag of candidates) {
+        const elementClass = registry?.get(tag);
+        if (elementClass) {
+            return {
+                elementId: typeof id === "string" ? id : undefined,
+                tag: element,
+                packageSpec,
+                supports: declaredSupports(elementClass),
+                pendingTags: [],
+            };
+        }
+    }
+    return {
+        elementId: typeof id === "string" ? id : undefined,
+        tag: element,
+        packageSpec,
+        supports: undefined,
+        pendingTags: registry ? candidates : [],
+    };
 }
 /**
- * Helper to check if context contains choice-based interactions
+ * The supports each element of a context declares: the element's own at element
+ * level, every element of the item or passage config at those levels, and none
+ * elsewhere. A model that names no element renders nothing and is skipped.
  */
-export function hasChoiceInteraction(context) {
+export function elementSupports(context) {
+    let config;
+    let models;
     if (isElementContext(context)) {
-        const config = context.item.config;
-        if (!config?.models)
-            return false;
-        const model = findElementModel(config.models, context.elementId);
-        if (!model)
-            return false;
-        const type = model.element || "";
-        return isChoiceElement(type, config.elements);
+        config = context.item.config;
+        models = [findElementModel(config?.models, context.elementId)];
     }
-    if (isItemContext(context)) {
-        const config = context.item.config;
-        return normalizeModels(config?.models).some((candidate) => {
-            if (!candidate || typeof candidate !== "object")
-                return false;
-            const model = candidate;
-            const type = model.element || "";
-            // A model that names its element has answered the question, whichever way
-            // the answer falls: `placement-ordering`, `categorize` and
-            // `drag-in-the-blank` each hold their draggables in `choices` without
-            // being choice interactions. The `choices` heuristic remains for configs
-            // that name no element.
-            if (type)
-                return isChoiceElement(type, config?.elements);
-            return Array.isArray(model.choices) && model.choices.length > 0;
-        });
+    else if (isItemContext(context)) {
+        config = context.item?.config;
+        models = normalizeModels(config?.models);
     }
-    return false;
+    else if (isPassageContext(context)) {
+        config = context.passage?.config;
+        models = normalizeModels(config?.models);
+    }
+    else {
+        return [];
+    }
+    return models.flatMap((model) => {
+        const supports = readElementSupports(model, config?.elements);
+        return supports ? [supports] : [];
+    });
 }
 /**
  * Helper to check if context contains text that can be read aloud

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

@@ -4,6 +4,7 @@ export interface DecidedToolbarTool {
     toolId: string;
     required: boolean;
     alwaysAvailable: boolean;
+    activateAtInit: boolean;
     parameters?: Record<string, unknown>;
 }
 /**

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

@@ -17,6 +17,7 @@ export function createDecidedToolsTracker() {
             toolId: entry.toolId,
             required: entry.required,
             alwaysAvailable: entry.alwaysAvailable,
+            activateAtInit: entry.activateAtInit,
             parameters: entry.parameters,
         }));
         if (last?.renderVersion === renderVersion &&

package/dist/services/tts/browser-provider.js

@@ -37,6 +37,8 @@ export const browserFallbackConfig = (config) => {
         fallback.rate = config.rate;
     if (config.pitch !== undefined)
         fallback.pitch = config.pitch;
+    if (config.volume !== undefined)
+        fallback.volume = config.volume;
     if (config.mathTokenHighlighting !== undefined) {
         fallback.mathTokenHighlighting = config.mathTokenHighlighting;
     }
@@ -437,8 +439,10 @@ class BrowserTTSProviderImpl {
                 utterance.voice = voice;
             if (this.config?.rate)
                 utterance.rate = this.config.rate;
-            if (this.config?.pitch)
+            if (this.config?.pitch !== undefined)
                 utterance.pitch = this.config.pitch;
+            if (this.config?.volume !== undefined)
+                utterance.volume = this.config.volume;
             let didStart = false;
             let settled = false;
             let startTimeout = null;
@@ -616,7 +620,7 @@ class BrowserTTSProviderImpl {
         this.releaseHold();
     }
     /**
-     * Update settings dynamically (rate, pitch, voice)
+     * Update settings dynamically (rate, pitch, volume, voice)
      * Changes take effect on the next speak() call
      */
     updateSettings(settings) {
@@ -629,6 +633,9 @@ class BrowserTTSProviderImpl {
         if (settings.pitch !== undefined) {
             this.config.pitch = settings.pitch;
         }
+        if (settings.volume !== undefined) {
+            this.config.volume = settings.volume;
+        }
         if (settings.voice !== undefined) {
             this.config.voice = settings.voice;
         }

package/dist/tools/registration.d.ts

@@ -32,8 +32,8 @@ export type { ContentCapabilityPhase, ContentCapabilityPolicy, ResolveContentCap
 export { resolveContentCapabilities } from "./content-capability-resolution.js";
 export type { ToolSurfaceHost, ToolSurfaceHostInput, ToolSurfaceHostOptions, ToolSurfaceHostSnapshot, ToolSurfaceScope, } from "./tool-surface-host.js";
 export { createToolSurfaceHost } from "./tool-surface-host.js";
-export type { ToolContext } from "../services/tool-context.js";
-export { hasChoiceInteraction, hasMathContent, hasReadableText, hasSpokenContent, hasScienceContent, } from "../services/tool-context.js";
+export type { ElementSupports, ToolContext, } from "../services/tool-context.js";
+export { elementSupports, hasMathContent, hasReadableText, hasSpokenContent, hasScienceContent, } from "../services/tool-context.js";
 export type { ParsedToolInstanceId } from "../services/tool-instance-id.js";
 export { createScopedToolId, parseScopedToolId, } from "../services/tool-instance-id.js";
 export type { ToolComponentFactory, ToolComponentFactoryMap, ToolComponentOverrides, ToolTagMap, } from "./tool-tag-map.js";

package/dist/tools/registration.js

@@ -30,7 +30,7 @@ export { reportToolFailure } from "../services/tool-failure.js";
 export { resolveFallbackToolIcon } from "../services/tool-icons.js";
 export { resolveContentCapabilities } from "./content-capability-resolution.js";
 export { createToolSurfaceHost } from "./tool-surface-host.js";
-export { hasChoiceInteraction, hasMathContent, hasReadableText, hasSpokenContent, hasScienceContent, } from "../services/tool-context.js";
+export { elementSupports, hasMathContent, hasReadableText, hasSpokenContent, hasScienceContent, } from "../services/tool-context.js";
 export { createScopedToolId, parseScopedToolId, } from "../services/tool-instance-id.js";
 export { createToolElement, resolveToolTag } from "./tool-tag-map.js";
 // Toolbar button/overlay wiring shared by every toolbar-toggle registration,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/pie-assessment-toolkit",
-	"version": "1.0.0-beta.0",
+	"version": "1.0.0-beta.2",
 	"type": "module",
 	"description": "PIE assessment toolkit: composable services + reference implementation for assessment players and tool coordination",
 	"license": "MIT",
@@ -69,17 +69,17 @@
 		"test": "bun test"
 	},
 	"dependencies": {
-		"@pie-players/pie-calculator": "1.0.0-beta.0",
-		"@pie-players/pie-context": "1.0.0-beta.0",
-		"@pie-players/pie-players-shared": "1.0.0-beta.0",
-		"@pie-players/pie-tts": "1.0.0-beta.0",
+		"@pie-players/pie-calculator": "1.0.0-beta.2",
+		"@pie-players/pie-context": "1.0.0-beta.2",
+		"@pie-players/pie-players-shared": "1.0.0-beta.2",
+		"@pie-players/pie-tts": "1.0.0-beta.2",
 		"speech-rule-engine": "5.0.0-rc.4"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.5.15",
 		"@happy-dom/global-registrator": "^20.14.5",
-		"@pie-players/tts-client-server": "1.0.0-beta.0",
-		"svelte": "^5.57.1",
+		"@pie-players/tts-client-server": "1.0.0-beta.2",
+		"svelte": "^5.57.2",
 		"svelte-check": "^4.7.6",
 		"typescript": "^5.9.3"
 	},