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

package/dist/services/section-session-assignment.js

@@ -0,0 +1,80 @@
+/**
+ * A host-assigned section session, resolved against the session a live
+ * controller already holds.
+ *
+ * The rules are the ones `ItemController.setSession` applies to one item:
+ * - a value whose content equals the current session is a no-op, so echoing a
+ *   snapshot back into the `session` property applies nothing;
+ * - an item session with neither a response value nor a response field leaves
+ *   an item session that holds responses in place. The embedded item player
+ *   applies the same rule when the section hands the session down, so applying
+ *   it at section level keeps the controller and its item players from
+ *   diverging.
+ *
+ * A controller that holds no session yet takes the value as assigned.
+ */
+import { hasResponseField, hasResponseValue, } from "@pie-players/pie-players-shared/pie";
+import { structurallyEqual } from "../utils/structural-equality.js";
+import { isPlainRecord } from "@pie-players/pie-players-shared/object";
+/** An entry is canonical (`{ itemIdentifier, session, ... }`) or the raw item session. */
+function itemSessionOf(entry) {
+    return isPlainRecord(entry) && isPlainRecord(entry.session) ? entry.session : entry;
+}
+function sameItemSessions(next, current) {
+    const nextSessions = isPlainRecord(next) ? next : {};
+    const currentSessions = isPlainRecord(current) ? current : {};
+    const itemIds = new Set([
+        ...Object.keys(nextSessions),
+        ...Object.keys(currentSessions),
+    ]);
+    for (const itemId of itemIds) {
+        if (!structurallyEqual(itemSessionOf(nextSessions[itemId]), itemSessionOf(currentSessions[itemId]))) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Whether applying `next` would leave `current` as it is. A field `next` leaves
+ * out is unchanged, and item sessions compare by their session payload, so a
+ * raw `{ id, data }` matches the canonical entry the controller stored for it.
+ */
+function sameSessionContent(next, current) {
+    for (const [key, value] of Object.entries(next)) {
+        if (value === undefined)
+            continue;
+        if (key === "itemSessions") {
+            if (!sameItemSessions(value, current.itemSessions))
+                return false;
+            continue;
+        }
+        if (!structurallyEqual(value, current[key])) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * The session to apply in replace mode, or `null` when applying `next` would
+ * change nothing.
+ */
+export function resolveSectionSessionAssignment(current, next) {
+    if (!current)
+        return next;
+    const itemSessions = isPlainRecord(next.itemSessions)
+        ? { ...next.itemSessions }
+        : {};
+    const currentItemSessions = isPlainRecord(current.itemSessions)
+        ? current.itemSessions
+        : {};
+    for (const [itemId, currentEntry] of Object.entries(currentItemSessions)) {
+        if (!hasResponseValue(itemSessionOf(currentEntry)))
+            continue;
+        const assigned = itemSessionOf(itemSessions[itemId]);
+        if (hasResponseValue(assigned) || hasResponseField(assigned))
+            continue;
+        itemSessions[itemId] = currentEntry;
+    }
+    const resolved = { ...next, itemSessions };
+    return sameSessionContent(resolved, current) ? null : resolved;
+}

package/dist/services/spoken-audio-cards.d.ts

@@ -3,8 +3,8 @@
  *
  * QTI 3 treats a recording and synthesized speech as the *same* support — both
  * are `spoken`, and a card carries recorded audio through `qti-file-href` plus a
- * MIME type — so this is not a new accommodation but the other form the existing
- * one can take. Some programs prefer a human voice to synthesis; PIE's `spoken`
+ * MIME type — so a recording is the other form the existing support takes.
+ * Some programs prefer a human voice to synthesis; PIE's `spoken`
  * card was string-only, so it had no way to say "play this file for this node".
  *
  * A node commonly carries both forms in the same language: the reading script
@@ -17,12 +17,8 @@
  * Validation posture matches sign-language cards: "treat as absent, never as
  * partially valid". A malformed payload must not produce a silent player that
  * looks like read-aloud is working.
- *
- * Part of PIE Assessment Toolkit.
  */
 import type { CatalogCardPayload, MediaFragmentRange, MediaSource } from "@pie-players/pie-players-shared/types";
-/** Catalog type token for spoken alternates. Matches QTI 3's `support` value. */
-export declare const SPOKEN_CATALOG_TYPE = "spoken";
 /** A validated recorded spoken alternate, flattened for playback. */
 export interface SpokenAudioMedia {
     /**

package/dist/services/spoken-audio-cards.js

@@ -3,8 +3,8 @@
  *
  * QTI 3 treats a recording and synthesized speech as the *same* support — both
  * are `spoken`, and a card carries recorded audio through `qti-file-href` plus a
- * MIME type — so this is not a new accommodation but the other form the existing
- * one can take. Some programs prefer a human voice to synthesis; PIE's `spoken`
+ * MIME type — so a recording is the other form the existing support takes.
+ * Some programs prefer a human voice to synthesis; PIE's `spoken`
  * card was string-only, so it had no way to say "play this file for this node".
  *
  * A node commonly carries both forms in the same language: the reading script
@@ -17,12 +17,8 @@
  * Validation posture matches sign-language cards: "treat as absent, never as
  * partially valid". A malformed payload must not produce a silent player that
  * looks like read-aloud is working.
- *
- * Part of PIE Assessment Toolkit.
  */
 import { isUnsupportedMediaAssetVersion, normalizeMediaFragment, normalizeMediaSources, trimmedOrUndefined, } from "@pie-players/pie-players-shared/media";
-/** Catalog type token for spoken alternates. Matches QTI 3's `support` value. */
-export const SPOKEN_CATALOG_TYPE = "spoken";
 /**
  * Validate a `spoken` card's payload into something playable, or `null`.
  *

package/dist/services/tool-config-defaults.d.ts

@@ -1,9 +1,9 @@
 /**
  * Placement defaults this package can hold.
  *
- * Only the empty one. `PACKAGED_TOOL_PLACEMENT` and
- * `SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT` name capabilities, so they moved to
- * the composition layer (`@pie-players/pie-default-tool-loaders`).
+ * Only the empty one. `SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT` names
+ * capabilities, so it lives in the composition layer
+ * (`@pie-players/pie-default-tool-loaders`).
  */
 export declare const DEFAULT_TOOL_PLACEMENT: {
     readonly assessment: readonly [];

package/dist/services/tool-config-defaults.js

@@ -1,9 +1,9 @@
 /**
  * Placement defaults this package can hold.
  *
- * Only the empty one. `PACKAGED_TOOL_PLACEMENT` and
- * `SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT` name capabilities, so they moved to
- * the composition layer (`@pie-players/pie-default-tool-loaders`).
+ * Only the empty one. `SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT` names
+ * capabilities, so it lives in the composition layer
+ * (`@pie-players/pie-default-tool-loaders`).
  */
 export const DEFAULT_TOOL_PLACEMENT = {
     assessment: [],

package/dist/services/tool-config-validation.d.ts

@@ -1,15 +1,13 @@
 import { type CanonicalToolsConfig, type ToolsConfigInput } from "./tools-config-normalizer.js";
-import { type FrameworkErrorModel } from "./framework-error.js";
 import type { ToolRegistry } from "./ToolRegistry.js";
 export type ToolConfigStrictness = "off" | "warn" | "error";
 export type ToolConfigDiagnosticSeverity = "warning" | "error";
 export interface ToolConfigDiagnostic {
-    code: "tools.unknownToolId" | "tools.unsupportedLevel" | "tools.unplaceableActivation" | "tools.registryUnavailable" | "tools.unknownProviderKey" | "tools.removedProviderKey" | "tools.providerSanitizeFailed" | "tools.providerValidateFailed" | "tools.invalidProviderValidation";
+    code: "tools.unknownToolId" | "tools.unsupportedLevel" | "tools.unplaceableActivation" | "tools.registryUnavailable" | "tools.unknownProviderKey" | "tools.providerSanitizeFailed" | "tools.providerValidateFailed" | "tools.invalidProviderValidation";
     severity: ToolConfigDiagnosticSeverity;
     path: string;
     message: string;
     toolId?: string;
-    providerId?: string;
 }
 export interface ToolConfigValidationOptions {
     strictness?: ToolConfigStrictness;
@@ -20,13 +18,12 @@ export interface ToolConfigValidationResult {
     config: CanonicalToolsConfig;
     diagnostics: ToolConfigDiagnostic[];
 }
-export declare function frameworkErrorFromToolConfigValidation(args: {
-    source: string;
-    diagnostics?: ToolConfigDiagnostic[] | null;
-    error?: unknown;
-    recoverable?: boolean;
-}): FrameworkErrorModel;
 export declare function normalizeToolConfigStrictness(value: unknown): ToolConfigStrictness;
+/**
+ * Normalize a tools config, sanitize and validate each provider entry with its
+ * registration's hooks, check ids and levels against `options.toolRegistry`,
+ * and report the diagnostics by `options.strictness` (default `"error"`).
+ */
 export declare function normalizeAndValidateToolsConfig(input?: ToolsConfigInput | null, options?: ToolConfigValidationOptions): ToolConfigValidationResult;
 /**
  * The normalization and diagnostics of {@link normalizeAndValidateToolsConfig},
@@ -34,8 +31,8 @@ export declare function normalizeAndValidateToolsConfig(input?: ToolsConfigInput
  */
 export declare function collectToolConfigDiagnostics(input: ToolsConfigInput | null | undefined, toolRegistry: ToolRegistry | null | undefined): ToolConfigValidationResult;
 /**
- * Report diagnostics as {@link normalizeAndValidateToolsConfig} does: a removed
- * provider key throws at every strictness, `"warn"` prints every diagnostic, and
- * `"error"` throws the blocking ones or, when there are none, prints the rest.
+ * Report diagnostics as {@link normalizeAndValidateToolsConfig} does: `"warn"`
+ * prints every diagnostic, and `"error"` throws the blocking ones or, when there
+ * are none, prints the rest.
  */
 export declare function reportToolConfigDiagnostics(diagnostics: ToolConfigDiagnostic[], options?: Pick<ToolConfigValidationOptions, "strictness" | "source">): void;

package/dist/services/tool-config-validation.js

@@ -1,20 +1,4 @@
 import { normalizeToolsConfig, } from "./tools-config-normalizer.js";
-import { frameworkErrorFromToolConfigDiagnostics, frameworkErrorFromUnknown, } from "./framework-error.js";
-export function frameworkErrorFromToolConfigValidation(args) {
-    if (Array.isArray(args.diagnostics) && args.diagnostics.length > 0) {
-        return frameworkErrorFromToolConfigDiagnostics({
-            source: args.source,
-            diagnostics: args.diagnostics,
-            recoverable: args.recoverable,
-        });
-    }
-    return frameworkErrorFromUnknown({
-        kind: "tool-config",
-        source: args.source,
-        error: args.error ?? new Error("Invalid tools config"),
-        recoverable: args.recoverable,
-    });
-}
 const DEFAULT_STRICTNESS = "error";
 export function normalizeToolConfigStrictness(value) {
     if (value === "off" || value === "warn" || value === "error") {
@@ -34,21 +18,20 @@ function getRegistryToolMap(toolRegistry) {
         .sort((left, right) => left.toolId.localeCompare(right.toolId))
         .map((tool) => [tool.toolId, tool]));
 }
-function sanitizeProviderConfig(providerId, providerConfig, tool, diagnostics) {
-    if (!providerConfig || !tool?.provider?.sanitizeConfig)
+function sanitizeToolConfig(toolId, providerConfig, tool, diagnostics) {
+    if (!providerConfig || !tool?.sanitizeConfig)
         return providerConfig;
     try {
-        const sanitized = tool.provider.sanitizeConfig(providerConfig);
+        const sanitized = tool.sanitizeConfig(providerConfig);
         if (!sanitized ||
             typeof sanitized !== "object" ||
             Array.isArray(sanitized)) {
             diagnostics.push(createDiagnostic({
                 code: "tools.providerSanitizeFailed",
                 severity: "error",
-                path: `providers.${providerId}`,
-                message: `Provider sanitizer for "${providerId}" must return an object.`,
-                providerId,
-                toolId: providerId,
+                path: `providers.${toolId}`,
+                message: `Config sanitizer of tool "${toolId}" must return an object.`,
+                toolId,
             }));
             return providerConfig;
         }
@@ -58,36 +41,33 @@ function sanitizeProviderConfig(providerId, providerConfig, tool, diagnostics) {
         diagnostics.push(createDiagnostic({
             code: "tools.providerSanitizeFailed",
             severity: "error",
-            path: `providers.${providerId}`,
-            message: `Provider sanitizer failed for "${providerId}": ${error instanceof Error ? error.message : String(error)}`,
-            providerId,
-            toolId: providerId,
+            path: `providers.${toolId}`,
+            message: `Config sanitizer of tool "${toolId}" failed: ${error instanceof Error ? error.message : String(error)}`,
+            toolId,
         }));
         return providerConfig;
     }
 }
-function validateProviderConfig(providerId, providerConfig, tool, diagnostics) {
-    if (!providerConfig || !tool?.provider?.validateConfig)
+function validateToolConfig(toolId, providerConfig, tool, diagnostics) {
+    if (!providerConfig || !tool?.validateConfig)
         return;
     try {
-        const providerDiagnostics = tool.provider.validateConfig(providerConfig);
-        if (!Array.isArray(providerDiagnostics)) {
+        const toolDiagnostics = tool.validateConfig(providerConfig);
+        if (!Array.isArray(toolDiagnostics)) {
             diagnostics.push(createDiagnostic({
                 code: "tools.invalidProviderValidation",
                 severity: "error",
-                path: `providers.${providerId}`,
-                message: `Provider validator for "${providerId}" must return an array.`,
-                providerId,
-                toolId: providerId,
+                path: `providers.${toolId}`,
+                message: `Config validator of tool "${toolId}" must return an array.`,
+                toolId,
             }));
             return;
         }
-        for (const diagnostic of providerDiagnostics) {
+        for (const diagnostic of toolDiagnostics) {
             diagnostics.push({
                 ...diagnostic,
-                path: diagnostic.path || `providers.${providerId}`,
-                providerId: diagnostic.providerId || providerId,
-                toolId: diagnostic.toolId || providerId,
+                path: diagnostic.path || `providers.${toolId}`,
+                toolId: diagnostic.toolId || toolId,
             });
         }
     }
@@ -95,10 +75,9 @@ function validateProviderConfig(providerId, providerConfig, tool, diagnostics) {
         diagnostics.push(createDiagnostic({
             code: "tools.providerValidateFailed",
             severity: "error",
-            path: `providers.${providerId}`,
-            message: `Provider validator failed for "${providerId}": ${error instanceof Error ? error.message : String(error)}`,
-            providerId,
-            toolId: providerId,
+            path: `providers.${toolId}`,
+            message: `Config validator of tool "${toolId}" failed: ${error instanceof Error ? error.message : String(error)}`,
+            toolId,
         }));
     }
 }
@@ -176,27 +155,16 @@ function collectPolicyDiagnostics(config, toolMap, diagnostics) {
         }));
     }
 }
-function collectProviderKeyDiagnostics(config, toolMap, hasRemovedTtsKey, diagnostics) {
-    if (hasRemovedTtsKey) {
-        diagnostics.push(createDiagnostic({
-            code: "tools.removedProviderKey",
-            severity: "error",
-            path: "providers.tts",
-            message: `Provider key "tts" is no longer supported. Use "providers.textToSpeech".`,
-            providerId: "tts",
-            toolId: "textToSpeech",
-        }));
-    }
-    for (const providerId of Object.keys(config.providers).sort()) {
-        if (toolMap.size === 0 || toolMap.has(providerId))
+function collectProviderKeyDiagnostics(config, toolMap, diagnostics) {
+    for (const key of Object.keys(config.providers).sort()) {
+        if (toolMap.size === 0 || toolMap.has(key))
             continue;
         diagnostics.push(createDiagnostic({
             code: "tools.unknownProviderKey",
             severity: "error",
-            path: `providers.${providerId}`,
-            message: `Unknown provider key "${providerId}".`,
-            providerId,
-            toolId: providerId,
+            path: `providers.${key}`,
+            message: `Unknown provider key "${key}".`,
+            toolId: key,
         }));
     }
 }
@@ -214,6 +182,11 @@ function throwValidationError(diagnostics, source) {
         .join("\n");
     throw new Error(`[tool-config-validation:${source}] Invalid tools config:\n${formatted}`);
 }
+/**
+ * Normalize a tools config, sanitize and validate each provider entry with its
+ * registration's hooks, check ids and levels against `options.toolRegistry`,
+ * and report the diagnostics by `options.strictness` (default `"error"`).
+ */
 export function normalizeAndValidateToolsConfig(input, options = {}) {
     const result = collectToolConfigDiagnostics(input, options.toolRegistry);
     reportToolConfigDiagnostics(result.diagnostics, options);
@@ -228,11 +201,9 @@ export function collectToolConfigDiagnostics(input, toolRegistry) {
     const normalized = normalizeToolsConfig(input);
     const diagnostics = [];
     // Tool-id and provider checks need a registry to check against, and every
-    // collector below returns early without one. Say so: this package no longer
-    // falls back to a packaged registry, so a caller that used to get id
-    // validation for free now gets none, and a silent downgrade of "your ids are
-    // valid" to "nobody looked" is the kind of change that surfaces as a typo
-    // reaching a learner.
+    // collector below returns early without one. Say so, since there is no
+    // packaged fallback registry: silence would read as "your ids are valid" when
+    // nobody looked, and a typo would reach a learner.
     const hasConfiguredTools = Object.values(normalized.placement).some((ids) => ids.length > 0) ||
         Object.keys(normalized.providers).length > 0 ||
         (normalized.policy.allowed?.length ?? 0) > 0 ||
@@ -245,18 +216,13 @@ export function collectToolConfigDiagnostics(input, toolRegistry) {
             message: 'No tool registry was supplied, so tool ids, placement levels and provider config were not validated, and a coordinator without one registers no tool providers. Pass `toolRegistry` to the coordinator or the toolkit it is bound to — for the packaged capability set, `createPackagedToolRegistry()` from "@pie-players/pie-default-tool-loaders".',
         }));
     }
-    const hasRemovedTtsKey = Object.hasOwn(normalized.providers, "tts");
     const nextProviders = {
         ...(normalized.providers || {}),
     };
-    for (const providerId of Object.keys(nextProviders).sort()) {
-        if (providerId === "tts") {
-            delete nextProviders.tts;
-            continue;
-        }
-        const tool = registryTools.get(providerId);
-        nextProviders[providerId] = sanitizeProviderConfig(providerId, nextProviders[providerId], tool, diagnostics);
-        validateProviderConfig(providerId, nextProviders[providerId], tool, diagnostics);
+    for (const toolId of Object.keys(nextProviders).sort()) {
+        const tool = registryTools.get(toolId);
+        nextProviders[toolId] = sanitizeToolConfig(toolId, nextProviders[toolId], tool, diagnostics);
+        validateToolConfig(toolId, nextProviders[toolId], tool, diagnostics);
     }
     const nextConfig = {
         ...normalized,
@@ -264,32 +230,26 @@ export function collectToolConfigDiagnostics(input, toolRegistry) {
     };
     collectPlacementDiagnostics(nextConfig, registryTools, diagnostics);
     collectPolicyDiagnostics(nextConfig, registryTools, diagnostics);
-    collectProviderKeyDiagnostics(nextConfig, registryTools, hasRemovedTtsKey, diagnostics);
+    collectProviderKeyDiagnostics(nextConfig, registryTools, diagnostics);
     return {
         config: nextConfig,
         diagnostics,
     };
 }
 /**
- * Report diagnostics as {@link normalizeAndValidateToolsConfig} does: a removed
- * provider key throws at every strictness, `"warn"` prints every diagnostic, and
- * `"error"` throws the blocking ones or, when there are none, prints the rest.
+ * Report diagnostics as {@link normalizeAndValidateToolsConfig} does: `"warn"`
+ * prints every diagnostic, and `"error"` throws the blocking ones or, when there
+ * are none, prints the rest.
  */
 export function reportToolConfigDiagnostics(diagnostics, options = {}) {
     const strictness = normalizeToolConfigStrictness(options.strictness);
     const source = options.source ?? "tools";
-    const removedKeys = diagnostics.filter((entry) => entry.code === "tools.removedProviderKey");
-    if (removedKeys.length > 0) {
-        throwValidationError(removedKeys, source);
-    }
     if (strictness === "warn") {
         emitWarnings(diagnostics, source);
     }
-    // Severity decides what `strictness: "error"` rejects. Every diagnostic was
-    // `"error"` until `tools.registryUnavailable`, which reports that validation
-    // could not run rather than that the config is wrong — throwing on it would
-    // turn "no registry supplied" from a host's existing, working setup into a
-    // construction failure.
+    // Severity decides what `strictness: "error"` rejects. `tools.registryUnavailable`
+    // is a warning: it reports that validation could not run, and throwing on it
+    // would fail construction for a host whose setup works without a registry.
     const blocking = diagnostics.filter((entry) => entry.severity === "error");
     if (strictness === "error" && blocking.length > 0) {
         throwValidationError(blocking, source);

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

@@ -102,38 +102,9 @@ export interface ElementToolContext extends BaseToolContext {
  */
 export type ToolContext = AssessmentToolContext | SectionToolContext | ItemToolContext | PassageToolContext | RubricToolContext | ElementToolContext;
 /**
- * Type guard to check if context is at assessment level
- */
-export declare function isAssessmentContext(context: ToolContext): context is AssessmentToolContext;
-/**
- * Type guard to check if context is at section level
- */
-export declare function isSectionContext(context: ToolContext): context is SectionToolContext;
-/**
- * Type guard to check if context is at item level
- */
-export declare function isItemContext(context: ToolContext): context is ItemToolContext;
-/**
- * Type guard to check if context is at passage level
- */
-export declare function isPassageContext(context: ToolContext): context is PassageToolContext;
-/**
- * Type guard to check if context is at rubric level
- */
-export declare function isRubricContext(context: ToolContext): context is RubricToolContext;
-/**
- * Type guard to check if context is at element level
- */
-export declare function isElementContext(context: ToolContext): context is ElementToolContext;
-/** The plain text a context carries, tags removed. */
-export declare function extractTextContent(context: ToolContext): string;
-/**
- * The authored markup a context carries, tags intact.
- *
- * For indicators that live in the markup rather than in the prose — `<math>`
- * above all, whose whole signal is the element name.
+ * Helper to check if context contains mathematical content
+ * (Basic heuristic - can be overridden by tools)
  */
-export declare function extractMarkupContent(context: ToolContext): string;
 export declare function hasMathContent(context: ToolContext): boolean;
 /**
  * Helper to check if context contains choice-based interactions
@@ -143,6 +114,11 @@ export declare function hasChoiceInteraction(context: ToolContext): boolean;
  * Helper to check if context contains text that can be read aloud
  */
 export declare function hasReadableText(context: ToolContext): boolean;
+/**
+ * Whether read-aloud has something to read: readable text, or markup carrying
+ * a catalog idref, whose spoken card reads for content with no text.
+ */
+export declare function hasSpokenContent(context: ToolContext): boolean;
 /**
  * Helper to check if context contains science content
  * (Basic heuristic - can be overridden by tools)