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

package/dist/services/ToolConfigResolver.js

@@ -1,229 +0,0 @@
-/**
- * ToolConfigResolver
- *
- * Implements 3-tier hierarchy for tool configuration:
- * Item requirements > Roster allowances > Student accommodations
- *
- * Ensures IEP/504 compliance by properly handling accommodation requirements
- * while respecting item-level and test-level restrictions.
- *
- * Features:
- * - 3-tier configuration hierarchy
- * - IEP/504 accommodation support
- * - Item-specific tool requirements
- * - Test-level tool restrictions
- * - Type-safe configuration
- *
- * Part of PIE Assessment Toolkit.
- */
-export class ToolConfigResolver {
-    /**
-     * Resolve configuration for a specific tool
-     *
-     * Hierarchy (highest to lowest priority):
-     * 1. Item level: Item requires scientific calculator → must provide
-     * 2. Roster level: Test blocks a tool → blocked regardless of accommodation
-     * 3. Student level: IEP requires TTS → enabled unless blocked above
-     *
-     * @param toolId Tool identifier
-     * @param itemConfig Item-level tool configuration
-     * @param rosterConfig Roster-level tool allowances
-     * @param studentProfile Student accommodation profile
-     * @returns Resolved configuration or null if tool not available
-     */
-    resolveTool(toolId, itemConfig, rosterConfig, studentProfile) {
-        // Check item level (highest priority)
-        const itemTool = itemConfig?.[toolId];
-        if (itemTool) {
-            // Item explicitly configures this tool
-            return {
-                enabled: true,
-                type: itemTool.type,
-                required: itemTool.required ?? false,
-                settings: itemTool.settings,
-                source: "item",
-            };
-        }
-        // Check roster level (blocks take precedence)
-        const rosterAllowance = rosterConfig?.[toolId];
-        if (rosterAllowance === "0") {
-            // Roster explicitly blocks this tool
-            return null;
-        }
-        if (rosterAllowance === "1") {
-            // Roster allows this tool
-            return {
-                enabled: true,
-                required: false,
-                source: "roster",
-            };
-        }
-        // Check student level (lowest priority)
-        const hasAccommodation = studentProfile?.accommodations.includes(toolId) ?? false;
-        if (hasAccommodation) {
-            // Student has accommodation for this tool
-            return {
-                enabled: true,
-                required: false,
-                source: "student",
-            };
-        }
-        // Tool not configured at any level
-        return null;
-    }
-    /**
-     * Resolve all tools from configuration
-     *
-     * @param input Configuration input
-     * @returns Map of tool ID to resolved configuration
-     */
-    resolveAll(input) {
-        const resolved = new Map();
-        // Collect all tool IDs from all levels
-        const allToolIds = new Set();
-        // From item config
-        if (input.itemConfig) {
-            Object.keys(input.itemConfig).forEach((id) => allToolIds.add(id));
-        }
-        // From roster config
-        if (input.rosterConfig) {
-            Object.keys(input.rosterConfig).forEach((id) => allToolIds.add(id));
-        }
-        // From student accommodations
-        if (input.studentProfile) {
-            input.studentProfile.accommodations.forEach((id) => allToolIds.add(id));
-        }
-        // Resolve each tool
-        for (const toolId of allToolIds) {
-            const config = this.resolveTool(toolId, input.itemConfig, input.rosterConfig, input.studentProfile);
-            if (config) {
-                resolved.set(toolId, config);
-            }
-        }
-        return resolved;
-    }
-    /**
-     * Check if a tool is enabled
-     *
-     * @param toolId Tool identifier
-     * @param input Configuration input
-     * @returns true if tool is enabled
-     */
-    isToolEnabled(toolId, input) {
-        const config = this.resolveTool(toolId, input.itemConfig, input.rosterConfig, input.studentProfile);
-        return config?.enabled ?? false;
-    }
-    /**
-     * Check if a tool is required
-     *
-     * @param toolId Tool identifier
-     * @param input Configuration input
-     * @returns true if tool is required
-     */
-    isToolRequired(toolId, input) {
-        const config = this.resolveTool(toolId, input.itemConfig, input.rosterConfig, input.studentProfile);
-        return config?.required ?? false;
-    }
-    /**
-     * Get tool type (e.g., 'scientific' for calculator)
-     *
-     * @param toolId Tool identifier
-     * @param input Configuration input
-     * @returns Tool type or null
-     */
-    getToolType(toolId, input) {
-        const config = this.resolveTool(toolId, input.itemConfig, input.rosterConfig, input.studentProfile);
-        return config?.type ?? null;
-    }
-    /**
-     * Get tool settings
-     *
-     * @param toolId Tool identifier
-     * @param input Configuration input
-     * @returns Tool settings or null
-     */
-    getToolSettings(toolId, input) {
-        const config = this.resolveTool(toolId, input.itemConfig, input.rosterConfig, input.studentProfile);
-        return config?.settings ?? null;
-    }
-    /**
-     * Get list of all enabled tools
-     *
-     * @param input Configuration input
-     * @returns Array of enabled tool IDs
-     */
-    getEnabledTools(input) {
-        const resolved = this.resolveAll(input);
-        return Array.from(resolved.entries())
-            .filter(([_, config]) => config.enabled)
-            .map(([toolId]) => toolId);
-    }
-    /**
-     * Get list of required tools
-     *
-     * @param input Configuration input
-     * @returns Array of required tool IDs
-     */
-    getRequiredTools(input) {
-        const resolved = this.resolveAll(input);
-        return Array.from(resolved.entries())
-            .filter(([_, config]) => config.required)
-            .map(([toolId]) => toolId);
-    }
-    /**
-     * Validate that all required tools are available
-     *
-     * @param availableTools Set of available tool IDs
-     * @param input Configuration input
-     * @returns Object with validation result
-     */
-    validate(availableTools, input) {
-        const requiredTools = this.getRequiredTools(input);
-        const missingTools = requiredTools.filter((toolId) => !availableTools.has(toolId));
-        return {
-            valid: missingTools.length === 0,
-            missingTools,
-        };
-    }
-    /**
-     * Merge multiple roster configurations (for complex assessments)
-     *
-     * More restrictive settings win (blocked > allowed).
-     *
-     * @param configs Array of roster configurations
-     * @returns Merged configuration
-     */
-    mergeRosterConfigs(...configs) {
-        const merged = {};
-        for (const config of configs) {
-            for (const [toolId, allowance] of Object.entries(config)) {
-                // If any config blocks the tool, it's blocked
-                if (allowance === "0") {
-                    merged[toolId] = "0";
-                }
-                else if (!merged[toolId]) {
-                    // If not already set, use this allowance
-                    merged[toolId] = allowance;
-                }
-            }
-        }
-        return merged;
-    }
-    /**
-     * Merge multiple student accommodation profiles
-     *
-     * Union of all accommodations.
-     *
-     * @param profiles Array of student profiles
-     * @returns Merged profile
-     */
-    mergeStudentProfiles(...profiles) {
-        const allAccommodations = new Set();
-        for (const profile of profiles) {
-            profile.accommodations.forEach((acc) => allAccommodations.add(acc));
-        }
-        return {
-            accommodations: Array.from(allAccommodations),
-        };
-    }
-}

package/dist/services/catalog-media.d.ts

@@ -1,56 +0,0 @@
-/**
- * Validation primitives shared by every catalog card whose payload references
- * media.
- *
- * Extracted from `sign-language-cards.ts` when `spoken` cards gained a recorded
- * audio form: both card types take authored, wire-facing URLs and hand them to a
- * media element in the learner's browser, so both need the same scheme
- * allow-list and the same "treat as absent, never as partially valid" posture.
- * Two copies of a URL allow-list is one copy that gets a fix and one that does
- * not.
- *
- * Part of PIE Assessment Toolkit.
- */
-import type { MediaFragmentRange, MediaSource } from "@pie-players/pie-players-shared/types";
-/**
- * The only `MediaAssetRef.version` this build renders.
- *
- * `media-asset-contract.md` requires unknown-version rejection for runtime
- * rendering: bumping to `2` obliges every consumer to accept both for as long as
- * any producer emits `1`, so a card claiming a version this build does not
- * implement must not be rendered on a guess at which fields still mean what they
- * did.
- */
-export declare const SUPPORTED_MEDIA_ASSET_VERSION = 1;
-/**
- * Whether a media reference claims a version this build cannot render.
- *
- * An absent `version` is accepted rather than rejected — the same posture the
- * rest of this module takes toward absent fields, and the one `media.kind` and
- * `matchesRequestedSignLanguage` already take: only a positive claim of
- * something else is refused. Producers predate the field, and treating its
- * absence as a rejection would drop cards that are otherwise wholly valid.
- */
-export declare function isUnsupportedMediaAssetVersion(version: unknown): boolean;
-export declare function isSafeMediaSrc(raw: unknown): raw is string;
-export declare function normalizeMediaSources(raw: unknown): MediaSource[];
-export declare function normalizeMediaFragment(raw: unknown): MediaFragmentRange | undefined;
-export declare function trimmedOrUndefined(value: unknown): string | undefined;
-/**
- * Hold a media element to one fragment's range, and return the disposer.
- *
- * The `#t=` URI `applyMediaFragment` writes is a hint browsers honour at neither
- * bound reliably, so every consumer that means "play only this slice" enforces it
- * here instead of reimplementing the pair. Both shipped consumers do —
- * `SignLanguageMediaRegion` pausing at the end, `TTSService.playRecordedAudio`
- * ending the clip so the chunk sequence advances — which is why the end action is
- * the caller's and only the arithmetic is shared.
- *
- * The start seek is forward only: a browser that did honour the URI has already
- * positioned past the start, and seeking back would replay audio the learner has
- * heard. `onReachedEnd` may fire more than once and must tolerate it; polling
- * stops while the element is paused, so an element left sitting past its end bound
- * goes quiet rather than being told repeatedly.
- */
-export declare function enforceMediaFragment(element: HTMLMediaElement, fragment: MediaFragmentRange | undefined, onReachedEnd: () => void): () => void;
-export declare function applyMediaFragment(src: string, fragment?: MediaFragmentRange): string;

package/dist/services/catalog-media.js

@@ -1,190 +0,0 @@
-/**
- * Validation primitives shared by every catalog card whose payload references
- * media.
- *
- * Extracted from `sign-language-cards.ts` when `spoken` cards gained a recorded
- * audio form: both card types take authored, wire-facing URLs and hand them to a
- * media element in the learner's browser, so both need the same scheme
- * allow-list and the same "treat as absent, never as partially valid" posture.
- * Two copies of a URL allow-list is one copy that gets a fix and one that does
- * not.
- *
- * Part of PIE Assessment Toolkit.
- */
-/**
- * Media source URLs are handed to a media element in the learner's browser. Only
- * schemes such an element can actually fetch are allowed; anything else is
- * dropped so an authored `javascript:` / `file:` URL cannot ride into the DOM.
- * Relative and protocol-relative URLs are allowed — host content is commonly
- * served from the same origin as the player.
- */
-const DISALLOWED_SRC_SCHEME = /^[a-z][a-z0-9+.-]*:/i;
-const ALLOWED_SRC_SCHEMES = new Set(["http:", "https:", "data:", "blob:"]);
-/**
- * The only `MediaAssetRef.version` this build renders.
- *
- * `media-asset-contract.md` requires unknown-version rejection for runtime
- * rendering: bumping to `2` obliges every consumer to accept both for as long as
- * any producer emits `1`, so a card claiming a version this build does not
- * implement must not be rendered on a guess at which fields still mean what they
- * did.
- */
-export const SUPPORTED_MEDIA_ASSET_VERSION = 1;
-/**
- * Whether a media reference claims a version this build cannot render.
- *
- * An absent `version` is accepted rather than rejected — the same posture the
- * rest of this module takes toward absent fields, and the one `media.kind` and
- * `matchesRequestedSignLanguage` already take: only a positive claim of
- * something else is refused. Producers predate the field, and treating its
- * absence as a rejection would drop cards that are otherwise wholly valid.
- */
-export function isUnsupportedMediaAssetVersion(version) {
-    return version !== undefined && version !== SUPPORTED_MEDIA_ASSET_VERSION;
-}
-export function isSafeMediaSrc(raw) {
-    if (typeof raw !== "string")
-        return false;
-    const src = raw.trim();
-    if (!src)
-        return false;
-    // Relative ("/video.mp4", "video.mp4") and protocol-relative ("//cdn/x.mp4")
-    // forms carry no scheme to check and inherit the document's.
-    if (src.startsWith("//") || !DISALLOWED_SRC_SCHEME.test(src))
-        return true;
-    const scheme = src.slice(0, src.indexOf(":") + 1).toLowerCase();
-    return ALLOWED_SRC_SCHEMES.has(scheme);
-}
-export function normalizeMediaSources(raw) {
-    if (!Array.isArray(raw))
-        return [];
-    const sources = [];
-    for (const entry of raw) {
-        if (!entry || typeof entry !== "object")
-            continue;
-        const candidate = entry;
-        if (!isSafeMediaSrc(candidate.src))
-            continue;
-        const source = { src: candidate.src.trim() };
-        if (typeof candidate.type === "string" && candidate.type.trim()) {
-            source.type = candidate.type.trim();
-        }
-        if (Number.isFinite(candidate.width))
-            source.width = candidate.width;
-        if (Number.isFinite(candidate.height))
-            source.height = candidate.height;
-        // Deduplicated by `src`, because the signing region renders `<source>`
-        // elements in an `{#each}` keyed on exactly that: an authored card listing
-        // one URL twice — the same file under two MIME types is the plausible way —
-        // would otherwise throw Svelte's duplicate-key error and take the whole
-        // region down rather than degrade. The first entry wins, so authored order
-        // still decides which encoding the browser is offered first.
-        if (sources.some((existing) => existing.src === source.src))
-            continue;
-        sources.push(source);
-    }
-    return sources;
-}
-export function normalizeMediaFragment(raw) {
-    if (!raw || typeof raw !== "object")
-        return undefined;
-    const candidate = raw;
-    const start = Number(candidate.startSeconds);
-    if (!Number.isFinite(start) || start < 0)
-        return undefined;
-    const end = Number(candidate.endSeconds);
-    // An end at or before the start would produce a zero/negative slice; treat
-    // it as "no end" rather than a range that can never play.
-    if (!Number.isFinite(end) || end <= start)
-        return { startSeconds: start };
-    return { startSeconds: start, endSeconds: end };
-}
-export function trimmedOrUndefined(value) {
-    if (typeof value !== "string")
-        return undefined;
-    const trimmed = value.trim();
-    return trimmed || undefined;
-}
-/**
- * Apply a fragment range to a source URL as a Media Fragments URI, so one
- * recording can serve several content nodes.
- *
- * The URI is a hint only: browsers honour both bounds inconsistently, so the
- * caller enforces the range itself — seek forward to the start once metadata is
- * available, and stop at the end. `SignLanguageMediaRegion` and
- * `TTSService.playRecordedAudio` are the two shipped consumers that do so.
- */
-/**
- * How often the end bound is re-checked while a slice is playing. `timeupdate`
- * alone fires about four times a second, which is loose enough to leak a sliver
- * of the next node's recording.
- */
-const END_CHECK_INTERVAL_MS = 100;
-/** `HTMLMediaElement.HAVE_METADATA`, which not every DOM implementation exposes. */
-const HAVE_METADATA = 1;
-/**
- * Hold a media element to one fragment's range, and return the disposer.
- *
- * The `#t=` URI `applyMediaFragment` writes is a hint browsers honour at neither
- * bound reliably, so every consumer that means "play only this slice" enforces it
- * here instead of reimplementing the pair. Both shipped consumers do —
- * `SignLanguageMediaRegion` pausing at the end, `TTSService.playRecordedAudio`
- * ending the clip so the chunk sequence advances — which is why the end action is
- * the caller's and only the arithmetic is shared.
- *
- * The start seek is forward only: a browser that did honour the URI has already
- * positioned past the start, and seeking back would replay audio the learner has
- * heard. `onReachedEnd` may fire more than once and must tolerate it; polling
- * stops while the element is paused, so an element left sitting past its end bound
- * goes quiet rather than being told repeatedly.
- */
-export function enforceMediaFragment(element, fragment, onReachedEnd) {
-    if (!fragment)
-        return () => { };
-    const { startSeconds, endSeconds } = fragment;
-    let seekToStart;
-    if (startSeconds > 0) {
-        seekToStart = () => {
-            if (element.currentTime < startSeconds) {
-                element.currentTime = startSeconds;
-            }
-        };
-        // Seeking before metadata is available only sets the default start
-        // position, so wait for it unless it already landed.
-        if (element.readyState >= HAVE_METADATA)
-            seekToStart();
-        else
-            element.addEventListener("loadedmetadata", seekToStart);
-    }
-    let checkEnd;
-    let endPoll;
-    if (endSeconds !== undefined) {
-        checkEnd = () => {
-            if (element.currentTime >= endSeconds)
-                onReachedEnd();
-        };
-        element.addEventListener("timeupdate", checkEnd);
-        endPoll = setInterval(() => {
-            if (!element.paused)
-                checkEnd?.();
-        }, END_CHECK_INTERVAL_MS);
-    }
-    return () => {
-        if (seekToStart)
-            element.removeEventListener("loadedmetadata", seekToStart);
-        if (checkEnd)
-            element.removeEventListener("timeupdate", checkEnd);
-        if (endPoll !== undefined)
-            clearInterval(endPoll);
-    };
-}
-export function applyMediaFragment(src, fragment) {
-    if (!fragment)
-        return src;
-    // Never stack a second fragment onto a URL that already carries one — the
-    // authored value wins.
-    if (src.includes("#"))
-        return src;
-    const end = fragment.endSeconds !== undefined ? `,${fragment.endSeconds}` : "";
-    return `${src}#t=${fragment.startSeconds}${end}`;
-}

package/dist/services/createDefaultToolRegistry.d.ts

@@ -1,53 +0,0 @@
-/**
- * Tool Registry Factory
- *
- * Creates an empty `ToolRegistry` and installs whatever component overrides and
- * lazy module loaders the caller supplies.
- *
- * It registers nothing by itself, deliberately. Eleven concrete registrations
- * used to live in this package, which made the policy and registry core know
- * every capability by name and left a host unable to contribute one without a PR
- * against this package. The packaged set now lives in the composition layer:
- * `createPackagedToolRegistry` from `@pie-players/pie-default-tool-loaders`.
- */
-import type { ToolRegistration, ToolModuleLoader } from "./ToolRegistry.js";
-import { ToolRegistry } from "./ToolRegistry.js";
-import type { ToolComponentFactory, ToolComponentFactoryMap, ToolTagMap } from "../tools/tool-tag-map.js";
-import { DEFAULT_TOOL_PLACEMENT } from "./tool-config-defaults.js";
-export interface DefaultToolRegistryOptions {
-    /**
-     * Registrations to register, keyed by toolId. Nothing is registered when this
-     * is absent.
-     */
-    registrations?: Partial<Record<string, ToolRegistration>>;
-    /**
-     * Element tag mapping for the registrations being installed. There is no
-     * built-in default: a tag map names capabilities, so it belongs to whoever
-     * decides which capabilities exist.
-     */
-    toolTagMap?: Partial<ToolTagMap>;
-    /**
-     * Override component creation globally (all tools) or per tool.
-     */
-    toolComponentFactory?: ToolComponentFactory;
-    toolComponentFactories?: Partial<ToolComponentFactoryMap>;
-    /**
-     * Optional lazy module loaders keyed by toolId.
-     */
-    toolModuleLoaders?: Partial<Record<string, ToolModuleLoader>>;
-}
-/**
- * Create a tool registry.
- *
- * @returns an empty `ToolRegistry` unless `registrations` is supplied
- */
-export declare function createDefaultToolRegistry(options?: DefaultToolRegistryOptions): ToolRegistry;
-/**
- * Placement configuration with every level empty.
- *
- * The only placement default this package can hold: a populated one would name
- * capabilities. `PACKAGED_TOOL_PLACEMENT` and
- * `SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT` are in
- * `@pie-players/pie-default-tool-loaders`.
- */
-export { DEFAULT_TOOL_PLACEMENT };

package/dist/services/createDefaultToolRegistry.js

@@ -1,45 +0,0 @@
-/**
- * Tool Registry Factory
- *
- * Creates an empty `ToolRegistry` and installs whatever component overrides and
- * lazy module loaders the caller supplies.
- *
- * It registers nothing by itself, deliberately. Eleven concrete registrations
- * used to live in this package, which made the policy and registry core know
- * every capability by name and left a host unable to contribute one without a PR
- * against this package. The packaged set now lives in the composition layer:
- * `createPackagedToolRegistry` from `@pie-players/pie-default-tool-loaders`.
- */
-import { ToolRegistry } from "./ToolRegistry.js";
-import { DEFAULT_TOOL_PLACEMENT } from "./tool-config-defaults.js";
-/**
- * Create a tool registry.
- *
- * @returns an empty `ToolRegistry` unless `registrations` is supplied
- */
-export function createDefaultToolRegistry(options = {}) {
-    const registry = new ToolRegistry();
-    for (const registration of Object.values(options.registrations ?? {})) {
-        if (registration)
-            registry.register(registration);
-    }
-    if (options.toolModuleLoaders &&
-        Object.keys(options.toolModuleLoaders).length > 0) {
-        registry.setToolModuleLoaders(options.toolModuleLoaders);
-    }
-    registry.setComponentOverrides({
-        toolTagMap: options.toolTagMap,
-        toolComponentFactory: options.toolComponentFactory,
-        toolComponentFactories: options.toolComponentFactories,
-    });
-    return registry;
-}
-/**
- * Placement configuration with every level empty.
- *
- * The only placement default this package can hold: a populated one would name
- * capabilities. `PACKAGED_TOOL_PLACEMENT` and
- * `SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT` are in
- * `@pie-players/pie-default-tool-loaders`.
- */
-export { DEFAULT_TOOL_PLACEMENT };

package/dist/services/defaultPersonalNeedsProfile.d.ts

@@ -1,21 +0,0 @@
-import type { PersonalNeedsProfile } from "@pie-players/pie-players-shared/types";
-/**
- * An empty personal-needs profile: nothing granted, nothing prohibited, nothing
- * activated at init.
- *
- * The core ships no populated default on purpose. It once derived one from every
- * registered tool's `pnpSupportIds`, which read *registry membership* as
- * *eligibility tier* — registration means "policy-addressable", not "universal,
- * on by default" — so an accommodation-tier capability was granted to every
- * student of every host that supplied no profile. The remedy at the time was a
- * compile-time list of ids to exclude, which a host could not extend for its own
- * accommodation.
- *
- * Which capabilities a deployment grants by default is a property of the
- * program, not of this package: TTS is a universal feature in one program and a
- * documented accommodation in another. That belongs in policy configuration
- * alongside the district and test-administration levels. A named preset of
- * today's universal set ships as data from
- * `@pie-players/pie-default-tool-loaders`, for hosts that want it.
- */
-export declare function createEmptyPersonalNeedsProfile(): PersonalNeedsProfile;

package/dist/services/defaultPersonalNeedsProfile.js

@@ -1,26 +0,0 @@
-/**
- * An empty personal-needs profile: nothing granted, nothing prohibited, nothing
- * activated at init.
- *
- * The core ships no populated default on purpose. It once derived one from every
- * registered tool's `pnpSupportIds`, which read *registry membership* as
- * *eligibility tier* — registration means "policy-addressable", not "universal,
- * on by default" — so an accommodation-tier capability was granted to every
- * student of every host that supplied no profile. The remedy at the time was a
- * compile-time list of ids to exclude, which a host could not extend for its own
- * accommodation.
- *
- * Which capabilities a deployment grants by default is a property of the
- * program, not of this package: TTS is a universal feature in one program and a
- * documented accommodation in another. That belongs in policy configuration
- * alongside the district and test-administration levels. A named preset of
- * today's universal set ships as data from
- * `@pie-players/pie-default-tool-loaders`, for hosts that want it.
- */
-export function createEmptyPersonalNeedsProfile() {
-    return {
-        supports: [],
-        prohibitedSupports: [],
-        activateAtInit: [],
-    };
-}