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

package/README.md

@@ -1,24 +1,118 @@
 # PIE Default Tool Loaders
 
-Default lazy module loader mappings for built-in PIE assessment tools.
+Composition layer for the packaged PIE assessment tools: which capabilities exist
+in a deployment, and how a program tiers them.
 
-This package intentionally owns concrete `pie-tool-*` dependencies so toolkit core can remain dependency-light and cycle-safe.
+It owns the concrete `pie-tool-*` dependencies so toolkit core can stay
+dependency-light and cycle-safe, and it is the layer above core — core knows
+`featureId`, placement levels, activation kinds and precedence rules, and knows
+no capability ids.
+
+It owns five things, all answers to "which capabilities does this deployment have
+and how does the program tier them":
+
+| Export | What it decides |
+| --- | --- |
+| `PACKAGED_TOOL_REGISTRATIONS`, `createPackagedToolRegistry`, `registerPackagedTools` | Which capabilities exist, and their toolbar and surface contracts |
+| `PACKAGED_TOOL_TAG_MAP` | Which custom element each one renders as |
+| `PACKAGED_TOOL_PLACEMENT`, `SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT`, `PACKAGED_TOOL_ORDER` | Where they appear and in what order |
+| `UNIVERSAL_SUPPORTS_PRESET`, `createUniversalPersonalNeedsProfile` | Which of their support ids the program grants to everyone |
+| `DEFAULT_TOOL_MODULE_LOADERS`, `registerSectionToolModuleLoaders` | When each one's bundle loads |
+
+The individual registrations are exported too, so a host can compose its own set
+rather than take the packaged one whole.
+
+These exports are projections of one internal **Packaged Capability
+Composition**. Each packaged capability is authored once with its registration,
+element delivery, loader bootstrap sets, placement/order membership and explicit
+universal-support policy. The package build rejects contradictory PIE-owned data
+— for example, a region capability with a toolbar tag, or a universal support
+id its registration does not declare — so release tests find a missing facet
+instead of a learner finding a dead affordance. The browser does not repeat that
+strict gate at import time: a PIE authoring defect must block publication, not an
+otherwise usable assessment.
+
+That invariant boundary does not make host input stricter. The existing public
+factory and constants are unchanged: lazy module loading remains opt-in,
+registration/tag/factory overrides retain precedence, an empty `toolIds` array
+still selects the full packaged set, and unknown selected ids are ignored while
+known ids continue to register.
 
 ## Usage
 
 ```ts
-import { createDefaultToolRegistry } from "@pie-players/pie-assessment-toolkit";
 import {
+	createPackagedToolRegistry,
 	DEFAULT_TOOL_MODULE_LOADERS,
-	registerSectionToolModuleLoaders,
 } from "@pie-players/pie-default-tool-loaders";
 
-// Full default loaders (item + section tools)
-const registry = createDefaultToolRegistry({
+// The packaged capability set, lazily loaded.
+const registry = createPackagedToolRegistry({
 	toolModuleLoaders: DEFAULT_TOOL_MODULE_LOADERS,
 });
+```
+
+`createDefaultToolRegistry()` in the toolkit is the other end of that choice: it
+builds an empty registry, and a host composing its own set registers into it.
+
+```ts
+import { createDefaultToolRegistry } from "@pie-players/pie-assessment-toolkit";
+import {
+	calculatorToolRegistration,
+	registerSectionToolModuleLoaders,
+	ttsToolRegistration,
+} from "@pie-players/pie-default-tool-loaders";
 
-// Section-only loaders (for section toolbar bootstrap points)
+const registry = createDefaultToolRegistry({
+	registrations: [calculatorToolRegistration, ttsToolRegistration],
+});
+// Section-only loaders, for section toolbar bootstrap points.
 registerSectionToolModuleLoaders(registry);
 ```
 
+## Content-dependent capabilities require an explicit packaging decision
+
+A content-dependent capability is never inferred into
+`UNIVERSAL_SUPPORTS_PRESET`. It may ship in `PACKAGED_TOOL_REGISTRATIONS` only
+when it has a useful presentation path without a grant and declares
+`resolvesWithoutGrant`. Audio transcript is the shipped example: an authored
+`visibility: "always"` transcript reaches every player, while its accommodation
+path remains policy-gated and `transcript` stays out of the universal preset.
+
+A content-dependent capability with no presentation path remains an explicit
+deployment choice. Signing is the shipped example: install
+`@pie-players/pie-tool-sign-language` and register it, which is the same two
+lines a host writes for a capability of its own.
+
+```ts
+import { signLanguageRegistration } from "@pie-players/pie-tool-sign-language";
+
+registry.register(signLanguageRegistration);
+```
+
+## Universal supports preset
+
+`createUniversalPersonalNeedsProfile()` builds a `PersonalNeedsProfile` granting
+`UNIVERSAL_SUPPORTS_PRESET` — the support ids the packaged tool set treats as
+universal features.
+
+```ts
+import { createUniversalPersonalNeedsProfile } from "@pie-players/pie-default-tool-loaders";
+
+const section = {
+	...authoredSection,
+	personalNeedsProfile: createUniversalPersonalNeedsProfile(),
+};
+```
+
+The core ships no populated default — `createEmptyPersonalNeedsProfile()` in
+`@pie-players/pie-assessment-toolkit` grants nothing. Which capabilities a
+deployment grants by default is a property of the program, not of a capability:
+TTS is a universal feature in one program and a documented accommodation in
+another. So the preset is data to adopt, extend or replace alongside the district
+and test-administration configuration, and it deliberately excludes any
+capability that declares a content dependency.
+
+A section carrying no profile is left alone. `pnpEnforcement` auto-detection
+engages on real host policy material, so supplying no profile means placement
+alone decides which tools appear.

package/dist/index.d.ts

@@ -1,16 +1,9 @@
-export type ToolModuleLoader = () => Promise<unknown>;
-export interface ToolRegistryLike {
-    setToolModuleLoaders(loaders: Partial<Record<string, ToolModuleLoader>>): void;
-}
-export declare const SECTION_TOOL_MODULE_LOADERS: Record<string, ToolModuleLoader>;
-export declare const ITEM_TOOL_MODULE_LOADERS: Record<string, ToolModuleLoader>;
-export declare const DEFAULT_TOOL_MODULE_LOADERS: Record<string, ToolModuleLoader>;
-export type RegisterDefaultToolModuleLoadersOptions = {
-    loaders?: Partial<Record<string, ToolModuleLoader>>;
-};
-/**
- * Register built-in lazy module loaders on a registry.
- * Hosts can override or extend the defaults via options.loaders.
- */
-export declare function registerDefaultToolModuleLoaders(registry: ToolRegistryLike, options?: RegisterDefaultToolModuleLoadersOptions): void;
-export declare function registerSectionToolModuleLoaders(registry: ToolRegistryLike, options?: RegisterDefaultToolModuleLoadersOptions): void;
+export type { PackagedToolRegistryOptions, RegisterDefaultToolModuleLoadersOptions, RegisterPackagedToolsOptions, ToolModuleLoader, ToolRegistryLike, } from "./packaged-capability-composition.js";
+export { createPackagedToolRegistry, createUniversalPersonalNeedsProfile, DEFAULT_TOOL_MODULE_LOADERS, ITEM_TOOL_MODULE_LOADERS, PACKAGED_TOOL_ORDER, PACKAGED_TOOL_PLACEMENT, PACKAGED_TOOL_REGISTRATIONS, PACKAGED_TOOL_TAG_MAP, registerDefaultToolModuleLoaders, registerPackagedTools, registerSectionToolModuleLoaders, SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT, SECTION_TOOL_MODULE_LOADERS, UNIVERSAL_SUPPORTS_PRESET, } from "./packaged-capability-composition.js";
+export { annotationToolbarRegistration, lineReaderToolRegistration, themeToolRegistration, } from "./registrations/accessibility-tools.js";
+export { AUDIO_TRANSCRIPT_FEATURE_ID, AUDIO_TRANSCRIPT_REGION_CLASS, AUDIO_TRANSCRIPT_REGION_LABEL, audioTranscriptRegistration, resolveAudioTranscript, type ResolvedAudioTranscript, } from "./registrations/audio-transcript.js";
+export { calculatorToolRegistration } from "./registrations/calculator.js";
+export { answerEliminatorToolRegistration, highlighterToolRegistration, } from "./registrations/interaction-tools.js";
+export { protractorToolRegistration, rulerToolRegistration, } from "./registrations/measurement-tools.js";
+export { graphToolRegistration, periodicTableToolRegistration, } from "./registrations/subject-specific-tools.js";
+export { ttsToolRegistration } from "./registrations/tts.js";

package/dist/index.js

@@ -1,45 +1,10 @@
-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"));
-}
-export const SECTION_TOOL_MODULE_LOADERS = {
-    calculator: loadCalculatorModule,
-    graph: () => loadSideEffectModule(() => import("@pie-players/pie-tool-graph")),
-    periodicTable: () => loadSideEffectModule(() => import("@pie-players/pie-tool-periodic-table")),
-    ruler: () => loadSideEffectModule(() => import("@pie-players/pie-tool-ruler")),
-    protractor: () => loadSideEffectModule(() => import("@pie-players/pie-tool-protractor")),
-    lineReader: () => loadSideEffectModule(() => import("@pie-players/pie-tool-line-reader")),
-};
-export const ITEM_TOOL_MODULE_LOADERS = {
-    calculator: loadCalculatorModule,
-    textToSpeech: () => loadSideEffectModule(() => import("@pie-players/pie-tool-tts-inline")),
-    answerEliminator: () => loadSideEffectModule(() => import("@pie-players/pie-tool-answer-eliminator")),
-    highlighter: () => loadSideEffectModule(() => import("@pie-players/pie-tool-annotation-toolbar")),
-    annotationToolbar: () => loadSideEffectModule(() => import("@pie-players/pie-tool-annotation-toolbar")),
-    theme: () => loadSideEffectModule(() => import("@pie-players/pie-tool-theme")),
-};
-export const DEFAULT_TOOL_MODULE_LOADERS = {
-    ...ITEM_TOOL_MODULE_LOADERS,
-    ...SECTION_TOOL_MODULE_LOADERS,
-};
-/**
- * Register built-in lazy module loaders on a registry.
- * Hosts can override or extend the defaults via options.loaders.
- */
-export function registerDefaultToolModuleLoaders(registry, options = {}) {
-    registry.setToolModuleLoaders({
-        ...DEFAULT_TOOL_MODULE_LOADERS,
-        ...(options.loaders || {}),
-    });
-}
-export function registerSectionToolModuleLoaders(registry, options = {}) {
-    registry.setToolModuleLoaders({
-        ...SECTION_TOOL_MODULE_LOADERS,
-        ...(options.loaders || {}),
-    });
-}
+export { createPackagedToolRegistry, createUniversalPersonalNeedsProfile, DEFAULT_TOOL_MODULE_LOADERS, ITEM_TOOL_MODULE_LOADERS, PACKAGED_TOOL_ORDER, PACKAGED_TOOL_PLACEMENT, PACKAGED_TOOL_REGISTRATIONS, PACKAGED_TOOL_TAG_MAP, registerDefaultToolModuleLoaders, registerPackagedTools, registerSectionToolModuleLoaders, SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT, SECTION_TOOL_MODULE_LOADERS, UNIVERSAL_SUPPORTS_PRESET, } from "./packaged-capability-composition.js";
+// Individual registrations, for a host composing a subset rather than the whole
+// packaged set.
+export { annotationToolbarRegistration, lineReaderToolRegistration, themeToolRegistration, } from "./registrations/accessibility-tools.js";
+export { AUDIO_TRANSCRIPT_FEATURE_ID, AUDIO_TRANSCRIPT_REGION_CLASS, AUDIO_TRANSCRIPT_REGION_LABEL, audioTranscriptRegistration, resolveAudioTranscript, } from "./registrations/audio-transcript.js";
+export { calculatorToolRegistration } from "./registrations/calculator.js";
+export { answerEliminatorToolRegistration, highlighterToolRegistration, } from "./registrations/interaction-tools.js";
+export { protractorToolRegistration, rulerToolRegistration, } from "./registrations/measurement-tools.js";
+export { graphToolRegistration, periodicTableToolRegistration, } from "./registrations/subject-specific-tools.js";
+export { ttsToolRegistration } from "./registrations/tts.js";

package/dist/packaged-capability-composition.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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, type ToolComponentFactory, type ToolComponentFactoryMap, type ToolRegistration, type ToolTagMap } from "@pie-players/pie-assessment-toolkit/tools/internal";
+import type { PersonalNeedsProfile } from "@pie-players/pie-players-shared/types";
+export type ToolModuleLoader = () => Promise<unknown>;
+export interface ToolRegistryLike {
+    setToolModuleLoaders(loaders: Partial<Record<string, ToolModuleLoader>>): void;
+}
+export interface PackagedToolRegistryOptions {
+    /** Override packaged registrations by toolId. */
+    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;
+}
+export type RegisterDefaultToolModuleLoadersOptions = {
+    loaders?: Partial<Record<string, ToolModuleLoader>>;
+};
+/**
+ * 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 declare function assertPackagedCapabilityComposition(): void;
+export declare const PACKAGED_TOOL_REGISTRATIONS: readonly [ToolRegistration, ToolRegistration, ToolRegistration, ToolRegistration, ToolRegistration, ToolRegistration, ToolRegistration, ToolRegistration, ToolRegistration, ToolRegistration, ToolRegistration, ToolRegistration];
+export declare const PACKAGED_TOOL_TAG_MAP: ToolTagMap;
+export declare const ITEM_TOOL_MODULE_LOADERS: Record<string, ToolModuleLoader>;
+export declare const SECTION_TOOL_MODULE_LOADERS: Record<string, ToolModuleLoader>;
+export declare const DEFAULT_TOOL_MODULE_LOADERS: Record<string, ToolModuleLoader>;
+export declare const PACKAGED_TOOL_PLACEMENT: {
+    readonly assessment: readonly ["theme"];
+    readonly section: readonly ["theme"];
+    readonly item: readonly ["textToSpeech", "highlighter", "annotationToolbar", "graph", "periodicTable"];
+    readonly passage: readonly ["textToSpeech", "highlighter", "annotationToolbar", "lineReader"];
+    readonly rubric: readonly ["textToSpeech", "highlighter", "annotationToolbar", "lineReader"];
+    readonly element: readonly ["calculator", "answerEliminator", "textToSpeech", "ruler", "protractor", "highlighter", "annotationToolbar", "graph", "periodicTable"];
+};
+export declare const SECTION_PLAYER_PREFERRED_TOOL_PLACEMENT: {
+    section: string[];
+    item: string[];
+    passage: string[];
+};
+export declare const PACKAGED_TOOL_ORDER: readonly ["theme", "calculator", "textToSpeech", "lineReader", "annotationToolbar", "highlighter", "answerEliminator", "ruler", "protractor", "graph", "periodicTable"];
+export declare const UNIVERSAL_SUPPORTS_PRESET: readonly string[];
+/** 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. */
+export declare function createPackagedToolRegistry(options?: PackagedToolRegistryOptions): ToolRegistry;
+/** Build a fresh profile granting the explicit universal-support preset. */
+export declare function createUniversalPersonalNeedsProfile(): PersonalNeedsProfile;
+/** Register packaged lazy module loaders, followed by host overrides. */
+export declare function registerDefaultToolModuleLoaders(registry: ToolRegistryLike, options?: RegisterDefaultToolModuleLoadersOptions): void;
+/** Register only the section-bootstrap loader subset, then host overrides. */
+export declare function registerSectionToolModuleLoaders(registry: ToolRegistryLike, options?: RegisterDefaultToolModuleLoadersOptions): void;