@pie-players/pie-default-tool-loaders 0.3.64 → 0.3.66

package/dist/packaged-capability-composition.js

@@ -0,0 +1,447 @@
+/**
+ * The one authored description of PIE's packaged capability composition.
+ *
+ * Registrations describe what a capability can do. This module owns the
+ * deployment decisions around them: element tags, lazy module bootstrap sets,
+ * placement presets, toolbar order and the explicit universal-support policy.
+ * Public constants are projections of this composition so adding a capability
+ * cannot leave a second hand-maintained catalogue silently behind.
+ */
+import { ToolRegistry, } from "@pie-players/pie-assessment-toolkit/tools/internal";
+import { annotationToolbarRegistration, lineReaderToolRegistration, themeToolRegistration, } from "./registrations/accessibility-tools.js";
+import { audioTranscriptRegistration } from "./registrations/audio-transcript.js";
+import { calculatorToolRegistration } from "./registrations/calculator.js";
+import { answerEliminatorToolRegistration, highlighterToolRegistration, } from "./registrations/interaction-tools.js";
+import { protractorToolRegistration, rulerToolRegistration, } from "./registrations/measurement-tools.js";
+import { graphToolRegistration, periodicTableToolRegistration, } from "./registrations/subject-specific-tools.js";
+import { ttsToolRegistration } from "./registrations/tts.js";
+const loadSideEffectModule = (load) => load().then(() => undefined);
+function loadCalculatorModule() {
+    if (typeof globalThis !== "undefined" &&
+        "customElements" in globalThis &&
+        globalThis.customElements?.get("pie-tool-calculator")) {
+        return Promise.resolve();
+    }
+    return loadSideEffectModule(() => import("@pie-players/pie-tool-calculator-desmos"));
+}
+const loadTtsModule = () => loadSideEffectModule(() => import("@pie-players/pie-tool-tts-inline"));
+const loadRulerModule = () => loadSideEffectModule(() => import("@pie-players/pie-tool-ruler"));
+const loadProtractorModule = () => loadSideEffectModule(() => import("@pie-players/pie-tool-protractor"));
+const loadAnswerEliminatorModule = () => loadSideEffectModule(() => import("@pie-players/pie-tool-answer-eliminator"));
+const loadAnnotationToolbarModule = () => loadSideEffectModule(() => import("@pie-players/pie-tool-annotation-toolbar"));
+const loadLineReaderModule = () => loadSideEffectModule(() => import("@pie-players/pie-tool-line-reader"));
+const loadThemeModule = () => loadSideEffectModule(() => import("@pie-players/pie-tool-theme"));
+const loadGraphModule = () => loadSideEffectModule(() => import("@pie-players/pie-tool-graph"));
+const loadPeriodicTableModule = () => loadSideEffectModule(() => import("@pie-players/pie-tool-periodic-table"));
+const PACKAGED_CAPABILITY_DEFINITIONS = [
+    {
+        registration: calculatorToolRegistration,
+        tagName: "pie-tool-calculator",
+        loadModule: loadCalculatorModule,
+        loaderTargets: ["item", "section"],
+        placementOrder: { element: 10 },
+        preferredPlacementOrder: { item: 10 },
+        toolbarOrder: 20,
+        universalSupportIds: [
+            "calculator",
+            "graphingCalculator",
+            "basicCalculator",
+            "scientificCalculator",
+        ],
+    },
+    {
+        registration: ttsToolRegistration,
+        tagName: "pie-tool-text-to-speech",
+        loadModule: loadTtsModule,
+        loaderTargets: ["item"],
+        placementOrder: { item: 10, passage: 10, rubric: 10, element: 30 },
+        preferredPlacementOrder: { item: 20, passage: 10 },
+        toolbarOrder: 30,
+        universalSupportIds: ["textToSpeech", "readAloud", "tts", "speechOutput"],
+    },
+    {
+        registration: rulerToolRegistration,
+        tagName: "pie-tool-ruler",
+        loadModule: loadRulerModule,
+        loaderTargets: ["section"],
+        placementOrder: { element: 40 },
+        preferredPlacementOrder: { section: 50 },
+        toolbarOrder: 80,
+        universalSupportIds: ["ruler", "measurement"],
+    },
+    {
+        registration: protractorToolRegistration,
+        tagName: "pie-tool-protractor",
+        loadModule: loadProtractorModule,
+        loaderTargets: ["section"],
+        placementOrder: { element: 50 },
+        preferredPlacementOrder: { section: 60 },
+        toolbarOrder: 90,
+        universalSupportIds: ["protractor", "angleMeasurement"],
+    },
+    {
+        registration: answerEliminatorToolRegistration,
+        tagName: "pie-tool-answer-eliminator",
+        loadModule: loadAnswerEliminatorModule,
+        loaderTargets: ["item"],
+        placementOrder: { element: 20 },
+        preferredPlacementOrder: { item: 30 },
+        toolbarOrder: 70,
+        universalSupportIds: [
+            "answerMasking",
+            "answerEliminator",
+            "strikethrough",
+            "choiceMasking",
+        ],
+    },
+    {
+        registration: highlighterToolRegistration,
+        tagName: "pie-tool-annotation-toolbar",
+        loadModule: loadAnnotationToolbarModule,
+        loaderTargets: ["item"],
+        placementOrder: { item: 20, passage: 20, rubric: 20, element: 60 },
+        toolbarOrder: 60,
+        universalSupportIds: ["highlighter", "textHighlight", "annotation"],
+    },
+    {
+        registration: lineReaderToolRegistration,
+        tagName: "pie-tool-line-reader",
+        loadModule: loadLineReaderModule,
+        loaderTargets: ["section"],
+        placementOrder: { passage: 40, rubric: 40 },
+        preferredPlacementOrder: { section: 40 },
+        toolbarOrder: 40,
+        universalSupportIds: [
+            "readingMask",
+            "readingGuide",
+            "readingRuler",
+            "lineReader",
+            "trackingGuide",
+        ],
+    },
+    {
+        registration: themeToolRegistration,
+        tagName: "pie-tool-theme",
+        loadModule: loadThemeModule,
+        loaderTargets: ["item"],
+        placementOrder: { assessment: 10, section: 10 },
+        preferredPlacementOrder: { section: 10 },
+        toolbarOrder: 10,
+        universalSupportIds: [
+            "highContrastDisplay",
+            "colorContrast",
+            "invertColors",
+            "theme",
+            "highContrast",
+            "customColors",
+        ],
+    },
+    {
+        registration: annotationToolbarRegistration,
+        tagName: "pie-tool-annotation-toolbar",
+        loadModule: loadAnnotationToolbarModule,
+        loaderTargets: ["item"],
+        placementOrder: { item: 30, passage: 30, rubric: 30, element: 70 },
+        preferredPlacementOrder: { item: 40, passage: 20 },
+        toolbarOrder: 50,
+        universalSupportIds: ["highlighting", "annotations"],
+    },
+    {
+        registration: graphToolRegistration,
+        tagName: "pie-tool-graph",
+        loadModule: loadGraphModule,
+        loaderTargets: ["section"],
+        placementOrder: { item: 40, element: 80 },
+        preferredPlacementOrder: { section: 20 },
+        toolbarOrder: 100,
+        universalSupportIds: ["graph", "coordinatePlane", "graphingTool"],
+    },
+    {
+        registration: periodicTableToolRegistration,
+        tagName: "pie-tool-periodic-table",
+        loadModule: loadPeriodicTableModule,
+        loaderTargets: ["section"],
+        placementOrder: { item: 50, element: 90 },
+        preferredPlacementOrder: { section: 30 },
+        toolbarOrder: 110,
+        universalSupportIds: [
+            "periodicTable",
+            "chemistryReference",
+            "elementReference",
+        ],
+    },
+    {
+        registration: audioTranscriptRegistration,
+        universalSupportIds: [],
+    },
+];
+const PACKAGED_PLACEMENT_LEVELS = [
+    "assessment",
+    "section",
+    "item",
+    "passage",
+    "rubric",
+    "element",
+];
+const PREFERRED_PLACEMENT_LEVELS = ["section", "item", "passage"];
+function assertUniqueWeights(definitions, levels, read, field) {
+    for (const level of levels) {
+        const seen = new Set();
+        for (const definition of definitions) {
+            const weight = read(definition)?.[level];
+            if (weight === undefined)
+                continue;
+            if (!Number.isSafeInteger(weight) || weight < 0) {
+                throw new Error(`Invalid packaged capability "${definition.registration.toolId}": ${field}.${level} must be a non-negative integer.`);
+            }
+            if (seen.has(weight)) {
+                throw new Error(`Invalid packaged capability composition: duplicate ${field}.${level} order ${weight}.`);
+            }
+            seen.add(weight);
+        }
+    }
+}
+function assertComposition(definitions) {
+    const toolIds = new Set();
+    const universalSupportIds = new Set();
+    const toolbarOrders = new Set();
+    for (const definition of definitions) {
+        const { registration } = definition;
+        if (!registration.toolId.trim()) {
+            throw new Error("Invalid packaged capability composition: tool ids must be non-empty.");
+        }
+        if (toolIds.has(registration.toolId)) {
+            throw new Error(`Invalid packaged capability composition: duplicate tool id "${registration.toolId}".`);
+        }
+        toolIds.add(registration.toolId);
+        const isRegion = registration.activation === "region";
+        if (isRegion) {
+            if (definition.tagName !== undefined ||
+                definition.loadModule !== undefined ||
+                definition.loaderTargets !== undefined ||
+                definition.toolbarOrder !== undefined ||
+                Object.keys(definition.placementOrder ?? {}).length > 0 ||
+                Object.keys(definition.preferredPlacementOrder ?? {}).length > 0) {
+                throw new Error(`Invalid packaged capability "${registration.toolId}": a region capability is surface-hosted and cannot declare element delivery or toolbar placement.`);
+            }
+        }
+        else {
+            if (!definition.tagName?.includes("-")) {
+                throw new Error(`Invalid packaged capability "${registration.toolId}": element-backed capabilities need a custom-element tag.`);
+            }
+            if (typeof definition.loadModule !== "function" ||
+                !definition.loaderTargets?.length) {
+                throw new Error(`Invalid packaged capability "${registration.toolId}": element-backed capabilities need a lazy loader and at least one bootstrap target.`);
+            }
+            if (new Set(definition.loaderTargets).size !==
+                definition.loaderTargets.length) {
+                throw new Error(`Invalid packaged capability "${registration.toolId}": loader bootstrap targets must be unique.`);
+            }
+            if (definition.toolbarOrder === undefined) {
+                throw new Error(`Invalid packaged capability "${registration.toolId}": toolbar capabilities need an order.`);
+            }
+        }
+        if (definition.toolbarOrder !== undefined) {
+            if (!Number.isSafeInteger(definition.toolbarOrder) ||
+                definition.toolbarOrder < 0) {
+                throw new Error(`Invalid packaged capability "${registration.toolId}": toolbar order must be a non-negative integer.`);
+            }
+            if (toolbarOrders.has(definition.toolbarOrder)) {
+                throw new Error(`Invalid packaged capability composition: duplicate toolbar order ${definition.toolbarOrder}.`);
+            }
+            toolbarOrders.add(definition.toolbarOrder);
+        }
+        const registrationSupportIds = new Set(registration.pnpSupportIds ?? [registration.toolId]);
+        if (registration.requiresAuthoredContent &&
+            definition.universalSupportIds.length > 0) {
+            throw new Error(`Invalid packaged capability "${registration.toolId}": content-dependent support ids cannot be universally granted.`);
+        }
+        for (const supportId of definition.universalSupportIds) {
+            if (!supportId.trim()) {
+                throw new Error(`Invalid packaged capability "${registration.toolId}": universal support ids must be non-empty.`);
+            }
+            if (!registrationSupportIds.has(supportId)) {
+                throw new Error(`Invalid packaged capability "${registration.toolId}": universal support id "${supportId}" is not declared by its registration.`);
+            }
+            if (universalSupportIds.has(supportId)) {
+                throw new Error(`Invalid packaged capability composition: universal support id "${supportId}" has more than one owner.`);
+            }
+            universalSupportIds.add(supportId);
+        }
+        for (const level of PREFERRED_PLACEMENT_LEVELS) {
+            if (definition.preferredPlacementOrder?.[level] !== undefined &&
+                !registration.supportedLevels.includes(level)) {
+                throw new Error(`Invalid packaged capability "${registration.toolId}": preferred placement "${level}" is not supported by its registration.`);
+            }
+        }
+    }
+    assertUniqueWeights(definitions, PACKAGED_PLACEMENT_LEVELS, (definition) => definition.placementOrder, "placementOrder");
+    assertUniqueWeights(definitions, PREFERRED_PLACEMENT_LEVELS, (definition) => definition.preferredPlacementOrder, "preferredPlacementOrder");
+}
+function orderedToolIds(definitions, level, read) {
+    return definitions
+        .flatMap((definition) => {
+        const order = read(definition)?.[level];
+        return order === undefined ? [] : [{ definition, order }];
+    })
+        .sort((left, right) => left.order - right.order)
+        .map(({ definition }) => definition.registration.toolId);
+}
+class PackagedCapabilityComposition {
+    definitions;
+    registrations;
+    toolTagMap;
+    itemModuleLoaders;
+    sectionModuleLoaders;
+    defaultModuleLoaders;
+    placement;
+    preferredPlacement;
+    toolbarOrder;
+    universalSupportIds;
+    constructor(definitions) {
+        this.definitions = definitions;
+        this.registrations = Object.freeze(definitions.map(({ registration }) => registration));
+        this.toolTagMap = Object.freeze(Object.fromEntries(definitions.flatMap((definition) => definition.tagName
+            ? [[definition.registration.toolId, definition.tagName]]
+            : [])));
+        this.itemModuleLoaders = this.projectModuleLoaders("item");
+        this.sectionModuleLoaders = this.projectModuleLoaders("section");
+        this.defaultModuleLoaders = Object.freeze({
+            ...this.itemModuleLoaders,
+            ...this.sectionModuleLoaders,
+        });
+        this.placement = Object.freeze(Object.fromEntries(PACKAGED_PLACEMENT_LEVELS.map((level) => [
+            level,
+            Object.freeze(orderedToolIds(definitions, level, (definition) => definition.placementOrder)),
+        ])));
+        this.preferredPlacement = Object.freeze(Object.fromEntries(PREFERRED_PLACEMENT_LEVELS.map((level) => [
+            level,
+            Object.freeze(orderedToolIds(definitions, level, (definition) => definition.preferredPlacementOrder)),
+        ])));
+        this.toolbarOrder = Object.freeze(definitions
+            .filter((definition) => definition.toolbarOrder !== undefined)
+            .slice()
+            .sort((left, right) => left.toolbarOrder - right.toolbarOrder)
+            .map(({ registration }) => registration.toolId));
+        this.universalSupportIds = Object.freeze(definitions
+            .flatMap(({ universalSupportIds }) => [...universalSupportIds])
+            .sort());
+    }
+    projectModuleLoaders(target) {
+        return Object.freeze(Object.fromEntries(this.definitions.flatMap((definition) => definition.loadModule && definition.loaderTargets?.includes(target)
+            ? [[definition.registration.toolId, definition.loadModule]]
+            : [])));
+    }
+    selectRegistrations(toolIds) {
+        // Preserve the established fail-soft host behavior: no selection means all,
+        // and unknown ids are ignored rather than preventing known tools from loading.
+        if (!toolIds?.length)
+            return this.registrations;
+        const selected = new Set(toolIds);
+        return this.registrations.filter(({ toolId }) => selected.has(toolId));
+    }
+    registerTools(registry, options = {}) {
+        const applyOverrides = options.applyOverrides ??
+            ((registration) => registration);
+        for (const registration of this.selectRegistrations(options.toolIds)) {
+            registry.register(applyOverrides(registration));
+        }
+    }
+    createRegistry(options = {}) {
+        const registry = new ToolRegistry();
+        this.registerTools(registry, {
+            toolIds: options.toolIds,
+            applyOverrides: (registration) => options.overrides?.[registration.toolId] ?? registration,
+        });
+        // Loader installation remains opt-in. Some hosts preload tool elements or
+        // provide their own tags; silently adding package loads here would change
+        // their bundle/runtime behavior.
+        if (options.toolModuleLoaders &&
+            Object.keys(options.toolModuleLoaders).length > 0) {
+            registry.setToolModuleLoaders(options.toolModuleLoaders);
+        }
+        registry.setComponentOverrides({
+            toolTagMap: { ...this.toolTagMap, ...(options.toolTagMap ?? {}) },
+            toolComponentFactory: options.toolComponentFactory,
+            toolComponentFactories: options.toolComponentFactories,
+        });
+        return registry;
+    }
+    createUniversalPersonalNeedsProfile() {
+        return {
+            supports: [...this.universalSupportIds],
+            prohibitedSupports: [],
+            activateAtInit: [],
+        };
+    }
+}
+/**
+ * Release/build gate for PIE-authored composition data.
+ *
+ * Deliberately not called by the browser runtime: an invariant regression must
+ * stop the package before publication, not turn into an import-time exception
+ * that prevents an otherwise usable assessment from rendering.
+ */
+export function assertPackagedCapabilityComposition() {
+    assertComposition(PACKAGED_CAPABILITY_DEFINITIONS);
+}
+/** Internal deep-module instance. Root exports below are its stable facade. */
+const packagedCapabilityComposition = new PackagedCapabilityComposition(PACKAGED_CAPABILITY_DEFINITIONS);
+export const PACKAGED_TOOL_REGISTRATIONS = [
+    ...packagedCapabilityComposition.registrations,
+];
+export const PACKAGED_TOOL_TAG_MAP = {
+    ...packagedCapabilityComposition.toolTagMap,
+};
+export const ITEM_TOOL_MODULE_LOADERS = {
+    ...packagedCapabilityComposition.itemModuleLoaders,
+};
+export const SECTION_TOOL_MODULE_LOADERS = {
+    ...packagedCapabilityComposition.sectionModuleLoaders,
+};
+export const DEFAULT_TOOL_MODULE_LOADERS = {
+    ...packagedCapabilityComposition.defaultModuleLoaders,
+};
+export const PACKAGED_TOOL_PLACEMENT = {
+    assessment: [...packagedCapabilityComposition.placement.assessment],
+    section: [...packagedCapabilityComposition.placement.section],
+    item: [...packagedCapabilityComposition.placement.item],
+    passage: [...packagedCapabilityComposition.placement.passage],
+    rubric: [...packagedCapabilityComposition.placement.rubric],
+    element: [...packagedCapabilityComposition.placement.element],
+};
+export const SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT = {
+    section: [...packagedCapabilityComposition.preferredPlacement.section],
+    item: [...packagedCapabilityComposition.preferredPlacement.item],
+    passage: [...packagedCapabilityComposition.preferredPlacement.passage],
+};
+export const PACKAGED_TOOL_ORDER = [
+    ...packagedCapabilityComposition.toolbarOrder,
+];
+export const UNIVERSAL_SUPPORTS_PRESET = packagedCapabilityComposition.universalSupportIds;
+/** Register packaged PIE capabilities onto an existing registry. */
+export function registerPackagedTools(registry, options = {}) {
+    packagedCapabilityComposition.registerTools(registry, options);
+}
+/** Create a registry holding the packaged PIE capabilities. */
+export function createPackagedToolRegistry(options = {}) {
+    return packagedCapabilityComposition.createRegistry(options);
+}
+/** Build a fresh profile granting the explicit universal-support preset. */
+export function createUniversalPersonalNeedsProfile() {
+    return packagedCapabilityComposition.createUniversalPersonalNeedsProfile();
+}
+/** Register packaged lazy module loaders, followed by host overrides. */
+export function registerDefaultToolModuleLoaders(registry, options = {}) {
+    registry.setToolModuleLoaders({
+        ...DEFAULT_TOOL_MODULE_LOADERS,
+        ...(options.loaders ?? {}),
+    });
+}
+/** Register only the section-bootstrap loader subset, then host overrides. */
+export function registerSectionToolModuleLoaders(registry, options = {}) {
+    registry.setToolModuleLoaders({
+        ...SECTION_TOOL_MODULE_LOADERS,
+        ...(options.loaders ?? {}),
+    });
+}

package/dist/packaged-tool-registry.d.ts

@@ -0,0 +1,2 @@
+export type { PackagedToolRegistryOptions, RegisterPackagedToolsOptions, } from "./packaged-capability-composition.js";
+export { createPackagedToolRegistry, PACKAGED_TOOL_ORDER, PACKAGED_TOOL_REGISTRATIONS, registerPackagedTools, } from "./packaged-capability-composition.js";

package/dist/packaged-tool-registry.js

@@ -0,0 +1 @@
+export { createPackagedToolRegistry, PACKAGED_TOOL_ORDER, PACKAGED_TOOL_REGISTRATIONS, registerPackagedTools, } from "./packaged-capability-composition.js";

package/dist/registrations/accessibility-tools.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Accessibility Tools Registrations
+ *
+ * Registers tools for visual accessibility and reading support:
+ * - Line Reader (reading guide)
+ * - Color Scheme (theme/contrast)
+ * - Annotation Toolbar (text highlighting)
+ *
+ * Maps to QTI 3.0 standard access features from:
+ * - visual category: highContrastDisplay, colorContrast
+ * - reading category: readingMask, readingGuide, highlighting
+ */
+import type { ToolRegistration } from "@pie-players/pie-assessment-toolkit/tools/internal";
+/**
+ * Line Reader tool registration
+ *
+ * Provides a reading guide overlay to help track reading position.
+ * Useful for text-heavy passages and questions.
+ */
+export declare const lineReaderToolRegistration: ToolRegistration;
+/**
+ * Theme tool registration
+ *
+ * Provides accessible theme and contrast controls.
+ * Global tool that affects entire assessment.
+ */
+export declare const themeToolRegistration: ToolRegistration;
+/**
+ * Annotation Toolbar registration
+ *
+ * Text highlighting with CSS Custom Highlight API.
+ * Zero DOM mutation, optimal performance.
+ */
+export declare const annotationToolbarRegistration: ToolRegistration;