@pie-players/pie-default-tool-loaders 0.3.65 → 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

@@ -1,52 +1,2 @@
-/**
- * The packaged PIE capability set, and the registry factory that composes it.
- *
- * This is the composition layer: which capabilities exist in a deployment. It
- * lived in `@pie-players/pie-assessment-toolkit`, where eleven concrete
- * registrations inside the generic package meant the policy and registry core
- * knew every capability by name and a host could not contribute one without a PR
- * against that package.
- *
- * The toolkit still owns `ToolRegistry`, `createDefaultToolRegistry` (which
- * builds an empty registry), the registration contract and the toolbar helpers.
- * It knows `featureId`, placement levels, activation kinds and precedence rules,
- * and knows no capability ids.
- */
-import { ToolRegistry, type ToolComponentFactory, type ToolComponentFactoryMap, type ToolModuleLoader, type ToolRegistration, type ToolTagMap } from "@pie-players/pie-assessment-toolkit/tools/internal";
-export declare const PACKAGED_TOOL_REGISTRATIONS: readonly [ToolRegistration, ToolRegistration, ToolRegistration, ToolRegistration, ToolRegistration, ToolRegistration, ToolRegistration, ToolRegistration, ToolRegistration, ToolRegistration, ToolRegistration];
-export interface PackagedToolRegistryOptions {
-    /**
-     * Override packaged registrations by toolId. Highest-precedence extension
-     * point.
-     */
-    overrides?: Partial<Record<string, ToolRegistration>>;
-    /** Override or extend the packaged element tag mapping. */
-    toolTagMap?: Partial<ToolTagMap>;
-    /** Override the component factory globally or per tool. */
-    toolComponentFactory?: ToolComponentFactory;
-    toolComponentFactories?: Partial<ToolComponentFactoryMap>;
-    /** Lazy module loaders keyed by toolId. */
-    toolModuleLoaders?: Partial<Record<string, ToolModuleLoader>>;
-    /** Restrict registration to specific packaged tool ids. */
-    toolIds?: string[];
-}
-export interface RegisterPackagedToolsOptions {
-    toolIds?: string[];
-    applyOverrides?: (registration: ToolRegistration) => ToolRegistration;
-}
-/**
- * Register packaged PIE capabilities onto an existing registry.
- */
-export declare function registerPackagedTools(registry: ToolRegistry, options?: RegisterPackagedToolsOptions): void;
-/**
- * Create a registry holding the packaged PIE capabilities.
- *
- * The tag map is installed through `setComponentOverrides` rather than read from
- * a core default, so a registry composed without it resolves no packaged tags —
- * which is the point: core no longer carries the catalogue.
- */
-export declare function createPackagedToolRegistry(options?: PackagedToolRegistryOptions): ToolRegistry;
-/**
- * Render order when several capabilities are visible at once.
- */
-export declare const PACKAGED_TOOL_ORDER: readonly ["theme", "calculator", "textToSpeech", "lineReader", "annotationToolbar", "highlighter", "answerEliminator", "ruler", "protractor", "graph", "periodicTable"];
+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

@@ -1,96 +1 @@
-/**
- * The packaged PIE capability set, and the registry factory that composes it.
- *
- * This is the composition layer: which capabilities exist in a deployment. It
- * lived in `@pie-players/pie-assessment-toolkit`, where eleven concrete
- * registrations inside the generic package meant the policy and registry core
- * knew every capability by name and a host could not contribute one without a PR
- * against that package.
- *
- * The toolkit still owns `ToolRegistry`, `createDefaultToolRegistry` (which
- * builds an empty registry), the registration contract and the toolbar helpers.
- * It knows `featureId`, placement levels, activation kinds and precedence rules,
- * and knows no capability ids.
- */
-import { ToolRegistry, } from "@pie-players/pie-assessment-toolkit/tools/internal";
-import { annotationToolbarRegistration, lineReaderToolRegistration, themeToolRegistration, } from "./registrations/accessibility-tools.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";
-import { PACKAGED_TOOL_TAG_MAP } from "./tool-tag-map.js";
-export const PACKAGED_TOOL_REGISTRATIONS = [
-    calculatorToolRegistration,
-    ttsToolRegistration,
-    rulerToolRegistration,
-    protractorToolRegistration,
-    answerEliminatorToolRegistration,
-    highlighterToolRegistration,
-    lineReaderToolRegistration,
-    themeToolRegistration,
-    annotationToolbarRegistration,
-    graphToolRegistration,
-    periodicTableToolRegistration,
-];
-/**
- * Register packaged PIE capabilities onto an existing registry.
- */
-export function registerPackagedTools(registry, options = {}) {
-    const selectedToolIds = options.toolIds && options.toolIds.length > 0
-        ? new Set(options.toolIds)
-        : null;
-    const applyOverrides = options.applyOverrides ??
-        ((registration) => registration);
-    for (const registration of PACKAGED_TOOL_REGISTRATIONS) {
-        if (selectedToolIds && !selectedToolIds.has(registration.toolId))
-            continue;
-        registry.register(applyOverrides(registration));
-    }
-}
-/**
- * Create a registry holding the packaged PIE capabilities.
- *
- * The tag map is installed through `setComponentOverrides` rather than read from
- * a core default, so a registry composed without it resolves no packaged tags —
- * which is the point: core no longer carries the catalogue.
- */
-export function createPackagedToolRegistry(options = {}) {
-    const registry = new ToolRegistry();
-    registerPackagedTools(registry, {
-        toolIds: options.toolIds,
-        applyOverrides: (registration) => options.overrides?.[registration.toolId] ?? registration,
-    });
-    if (options.toolModuleLoaders &&
-        Object.keys(options.toolModuleLoaders).length > 0) {
-        registry.setToolModuleLoaders(options.toolModuleLoaders);
-    }
-    registry.setComponentOverrides({
-        toolTagMap: { ...PACKAGED_TOOL_TAG_MAP, ...(options.toolTagMap ?? {}) },
-        toolComponentFactory: options.toolComponentFactory,
-        toolComponentFactories: options.toolComponentFactories,
-    });
-    return registry;
-}
-/**
- * Render order when several capabilities are visible at once.
- */
-export const PACKAGED_TOOL_ORDER = [
-    // Global accessibility first
-    "theme",
-    // Common tools
-    "calculator",
-    "textToSpeech",
-    // Reading aids
-    "lineReader",
-    "annotationToolbar",
-    "highlighter",
-    // Interaction tools
-    "answerEliminator",
-    // Measurement tools
-    "ruler",
-    "protractor",
-    // Subject-specific
-    "graph",
-    "periodicTable",
-];
+export { createPackagedToolRegistry, PACKAGED_TOOL_ORDER, PACKAGED_TOOL_REGISTRATIONS, registerPackagedTools, } from "./packaged-capability-composition.js";

package/dist/registrations/audio-transcript.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Audio transcript: the text of an audio prompt, rendered for the learners
+ * entitled to it.
+ *
+ * Two kinds of content wear the same shape, and the card says which:
+ *
+ *   - `visibility: "always"` is authored presentation. The item family was
+ *     designed to be delivered with its transcript on screen — Star Early
+ *     Literacy sentence items, for instance — so no profile grants it and none
+ *     revokes it.
+ *   - anything else, `"onGrant"` included, is the accommodation. Policy decides
+ *     against the `transcript` support id, and silence means no. For the three
+ *     Star families where a visible transcript turns the item into a reading
+ *     task, that gate is the whole point.
+ *
+ * The toolkit renders the text, not the element. Before this, the transcript rode
+ * on `model.audioTranscript` and `mc-populated-blank` revealed its own copy when
+ * an ancestor carried `.rli-with-audio-transcript` — which made delivering an
+ * accommodation the host's job, required every element carrying audio to
+ * reimplement the reveal, and put an element-specific CSS class in the contract.
+ * Rendering here is the same shape signing already has, and it is what makes one
+ * mechanism serve braille, simplified-language and the rest.
+ *
+ * No `aria-describedby` back to the element's audio control, deliberately. A
+ * description is announced as a flat string when a control takes focus, so
+ * pointing one at a multi-sentence transcript is worse to listen to than reading
+ * order: this renders a labelled region immediately before the content, where a
+ * screen-reader user meets it on the way to the control it belongs to.
+ *
+ * It ships in the packaged set, unlike signing, because its presentation half has
+ * to work with no host opt-in: an item authored to show its transcript must show
+ * it in every player, and a deployment that forgot an import would silently
+ * deliver a designed-for reading support as nothing. The accommodation half is
+ * still policy-gated exactly as signing is, and `transcript` is deliberately
+ * absent from the universal preset — a content-dependent support never belongs in
+ * a wholesale grant.
+ */
+import type { ToolContentDependencyContext, ToolRegistration } from "@pie-players/pie-assessment-toolkit/tools/internal";
+/** QTI 3.0 / AfA support id gating an audio transcript. */
+export declare const AUDIO_TRANSCRIPT_FEATURE_ID = "transcript";
+/** Catalog type carrying the transcript text. */
+export declare const AUDIO_TRANSCRIPT_CATALOG_TYPE = "transcript";
+/** Accessible name of the rendered region, and its class hook for themes. */
+export declare const AUDIO_TRANSCRIPT_REGION_LABEL = "Transcript";
+export declare const AUDIO_TRANSCRIPT_REGION_CLASS = "pie-tool-audio-transcript";
+/** The transcript to render, and why it is being rendered. */
+export interface ResolvedAudioTranscript {
+    catalogId: string;
+    text: string;
+    language?: string;
+    /** True when the card declares itself authored presentation. */
+    always: boolean;
+}
+/**
+ * The transcript an entity carries, or `null`.
+ *
+ * Read from the owner snapshot the resolver produced. Item/passage/model
+ * traversal and registration precedence have already been applied, so this
+ * capability owns only transcript interpretation.
+ *
+ * The cards are read directly rather than through `AccessibilityCatalogResolver`,
+ * which flattens a card to type/language/content and so cannot carry
+ * `visibility` — the one attribute this decision turns on. Nothing is lost by it:
+ * the resolver's value is choosing between languages of the same alternate, and a
+ * transcript is in the language of the audio it transcribes, one per prompt.
+ */
+export declare function resolveAudioTranscript(context: ToolContentDependencyContext): ResolvedAudioTranscript | null;
+/**
+ * Host surface this capability fills: the full-width slot above a card's content.
+ *
+ * Item cards and passage cards open the same surface, so declaring it once
+ * reaches both — a passage can carry an audio prompt as an item can.
+ */
+export declare const CONTENT_LEAD_SURFACE = "content-lead";
+export declare const audioTranscriptRegistration: ToolRegistration;